Contenido de la documentación de Python

Qué hay de nuevo en Python

What’s New In Python 3.9

Summary – Release highlights

You should check for DeprecationWarning in your code

New Features

Dictionary Merge & Update Operators

New String Methods to Remove Prefixes and Suffixes

Type Hinting Generics in Standard Collections

New Parser

Other Language Changes

New Modules

zoneinfo

graphlib

Improved Modules

ast

asyncio

compileall

concurrent.futures

curses

datetime

distutils

fcntl

ftplib

gc

hashlib

http

IDLE and idlelib

imaplib

importlib

inspect

ipaddress

math

multiprocessing

nntplib

os

pathlib

pdb

poplib

pprint

pydoc

random

signal

smtplib

socket

time

sys

tracemalloc

typing

unicodedata

venv

xml

Optimizations

Deprecated

Removed

Porting to Python 3.9

Changes in the Python API

Changes in the C API

CPython bytecode changes

Build Changes

C API Changes

New Features

Porting to Python 3.9

Removed

Notable changes in Python 3.9.1

typing

macOS 11.0 (Big Sur) and Apple Silicon Mac support

Notable changes in Python 3.9.2

collections.abc

urllib.parse

Notable changes in Python 3.9.3

Notable changes in Python 3.9.5

urllib.parse

Notable security feature in 3.9.14

Notable Changes in 3.9.17

tarfile

Qué hay de nuevo en Python 3.8

Resumen – Aspectos destacados de la versión

Nuevas características

Expresiones de asignación

Parámetros solo posicionales

Caché del sistema de archivos paralelo para archivos de bytecode compilados

La compilación de depuración usa la misma ABI que la compilación de lanzamiento

los f-strings soportan = para expresiones autodocumentadas y depuración

PEP 578: Ganchos de auditoría en tiempo de ejecución de Python

PEP 587: Configuración de inicialización de Python

PEP 590: Vectorcall: un protocolo de llamada rápida para CPython

Protocolo 5 de Pickle con búferes de datos fuera de banda

Otros cambios en el lenguaje

Nuevos módulos

Módulos mejorados

ast

asyncio

builtins

collections

cProfile

csv

curses

ctypes

datetime

functools

gc

gettext

gzip

IDLE e idlelib

inspect

io

itertools

json.tool

logging

math

mmap

multiprocessing

os

os.path

pathlib

pickle

plistlib

pprint

py_compile

shlex

shutil

socket

ssl

statistics

sys

tarfile

threading

tokenize

tkinter

time

typing

unicodedata

unittest

venv

weakref

xml

xmlrpc

Optimizaciones

Cambios en la compilación y la API de C

Obsoleto

APIs y características eliminadas

Portando a Python 3.8

Cambios en el comportamiento de Python

Cambios en la API de Python

Cambios en la API de C

Cambios en el bytecode de CPython

Demos y herramientas

Cambios notables en Python 3.8.1

Cambios notables en Python 3.8.8

Notable changes in Python 3.8.12

Que hay de nuevo en Python 3.7

Resumen – Lanzamientos Destacados

Nuevas Características

PEP 563: Evaluación pospuesta de anotaciones

PEP 538: Coerción de configuración regional del Legado de C

PEP 540: Modo de tiempo de ejecución UTF-8 forzado

PEP 553: Incorporada en breakpoint()

PEP 539: Nueva API C para almacenamiento local de subprocesos

PEP 562: Personalización del acceso a los atributos del módulo

PEP 564: Nuevas funciones de tiempo con resolución de nanosegundos

PEP 565: Mostrar DeprecationWarning en __main__

PEP 560: Soporte básico para el módulo de typing y tipos genéricos

PEP 552: Archivos .pyc basados en hash

PEP 545: Traducciones de Documentaciones de Python

Modo de desarrollo de Python (-X dev)

Otros cambios en el lenguaje

Nuevos módulos

contextvars

dataclasses

importlib.resources

Módulos mejorados

argparse

asyncio

binascii

calendar

collections

compileall

concurrent.futures

contextlib

cProfile

crypt

datetime

dbm

decimal

dis

distutils

enum

functools

gc

hmac

http.client

http.server

idlelib and IDLE

importlib

io

ipaddress

itertools

locale

logging

math

mimetypes

msilib

multiprocessing

os

pathlib

pdb

py_compile

pydoc

queue

re

signal

socket

socketserver

sqlite3

ssl

string

subprocess

sys

time

tkinter

tracemalloc

types

unicodedata

unittest

unittest.mock

urllib.parse

uu

uuid

warnings

xml.etree

xmlrpc.server

zipapp

zipfile

Cambios en la API C

Construir cambios

Optimizaciones

Otros cambios de implementación de CPython

Comportamiento obsoleto de Python

Módulos, funciones y métodos de Python obsoletos

aifc

asyncio

collections

dbm

enum

gettext

importlib

locale

macpath

threading

socket

ssl

sunau

sys

wave

Funciones y tipos obsoletos de la API C

Eliminación de soporte de plataforma

Eliminaciones de API y funciones

Eliminaciones de módulos

Cambios solo en Windows

Portando a Python 3.7

Cambios en el comportamiento de Python

Cambios en la API Python

Cambios en la API de C

Cambios en el código de bytes de CPython

Cambios solo en Windows

Otra implementación de cambios en CPython

Cambios notables en Python 3.7.1

Cambios notables en Python 3.7.2

Cambios notables en Python 3.7.6

Cambios notables en Python 3.7.10

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.4

Notable changes in Python 3.6.5

Notable changes in Python 3.6.7

Notable changes in Python 3.6.10

Notable changes in Python 3.6.13

Qué hay de nuevo en Python 3.5

Resumen – Aspectos destacados de la versión

Nuevas características

PEP 492 - Corrutinas con sintaxis async y await

PEP 465 - Un operador infijo dedicado para la multiplicación de matrices

PEP 448 - Generalizaciones de desembalaje adicionales

PEP 461 - soporte de formateo porcentual para bytes y bytearray

PEP 484 - Indicador de tipos

PEP 471 - Función os.scandir() – un iterador de directorio mejor y más rápido

PEP 475: Reintentar las llamadas al sistema que fallan con EINTR

PEP 479: Cambiar el gestor de StopIteration dentro de generadores

PEP 485: Una función para probar la igualdad aproximada

PEP 486: Hacer que el launcher de Python sea consciente de los entornos virtuales

PEP 488: Eliminación de archivos PYO

PEP 489: Inicialización del módulo de extensión multifase

Otros cambios en el lenguaje

Nuevos módulos

typing

zipapp

Módulos mejorados

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 e 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

Soporte de memoria BIO

Soporte de negociación de protocolo de capa de aplicación

Otros cambios

sqlite3

subprocess

sys

sysconfig

tarfile

threading

time

timeit

tkinter

traceback

types

unicodedata

unittest

unittest.mock

urllib

wsgiref

xmlrpc

xml.sax

zipfile

Otros cambios a nivel de módulo

Optimizaciones

Cambios en la compilación y la API de C

Obsoleto

Nuevas palabras clave

Comportamiento obsoleto de Python

Sistemas operativos no compatibles

Módulos, funciones y métodos obsoletos de Python

Eliminado

APIs y características eliminadas

Portando a Python 3.5

Cambios en el comportamiento de Python

Cambios en la API de Python

Cambios en la API de C

Cambios notables en Python 3.5.4

Nuevo objetivo de compilación make regen-all

Eliminación del objetivo de compilación make touch

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

Que novedades hay en python 3.3

Resumen – aspectos destacados de la versión

PEP 405: Entornos virtuales

PEP 420: Paquetes para espacios de nombres implícitos

PEP 3118: Nueva implementación de vista de memoria y en la documentación del protocolo del buffer

Características

Cambios en la API

PEP 393: Representación flexible de cadenas de caracteres

Funcionalidad

Rendimiento y uso de recursos

PEP 397: Lanzador de python para windows

PEP 3151: Reelaborando de la jerarquía de excepciones de IO y OS

PEP 380: Sintaxis para delegar en un subgenerador

PEP 409: Suprimir el contexto de excepción

PEP 414: Literales Unicode explícitos

PEP 3155: Nombres calificados para clases y funciones

PEP 412: Diccionario de intercambio de claves

PEP 362: Objeto de firma de función

PEP 421: Agregar sys.implementation

SimpleNamespace

Usar importlib como implementación de Import

Nuevas APIs

Cambios visibles

Otros cambios de idioma

Un bloqueo de importación más detallado

Funciones y tipos incorporados

Nuevos módulos

faulthandler

ipaddress

lzma

Módulos mejorados

abc

array

base64

binascii

bz2

códecs

colecciones

contextlib

crypt

curses

datetime

decimal

Características

Cambios en la API

email

Marco de políticas

Política provisional con nueva API de encabezado

Otros cambios en la API

ftplib

functools

gc

hmac

http

html

imaplib

inspect

io

itertools

logging

math

mmap

multiprocesamiento

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

Optimizaciones

Construcción y cambios en la API de C

Obsoleto

Sistemas operativos no compatibles

Módulos , funciones y métodos obsoletos en Python

Funciones y tipos obsoletos en la API de C

Características obsoletas

Migración a Python 3.3

Portando código Python

Portando código C

Construyendo extensiones C

Cambios en el conmutador de línea de comandos

Qué hay de nuevo en Python 3.2

PEP 384: Definición de un ABI estable

PEP 389: Módulo de análisis sintáctico (Parser) de línea de comandos Argparse

PEP 391: Configuración basada en diccionario para Logging

PEP 3148: El módulo concurrent.futures

PEP 3147: Directorios del repositorio de PYC

PEP 3149: Archivos .so con etiquetado de versión para ABI

PEP 3333: Interfaz de puerta de enlace del servidor web Python v1.0.1

Otros cambios de lenguaje

Módulos nuevos, mejorados y obsoletos

email

elementtree

functools

itertools

collections

threading

datetime and time

math

abc

io

reprlib

logging

csv

contextlib

decimal and fractions

ftp

popen

select

gzip y zipfile

tarfile

hashlib

ast

os

shutil

sqlite3

html

socket

ssl

nntp

certificados

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

Documentación

IDLE

Repositorio de código

Cambios en la API de construcción y C

Portar a Python 3.2

Qué hay de nuevo en Python 3.1

PEP 372: Diccionarios ordenados

PEP 378: Especificador de formato para el separador de miles

Otros cambios del lenguaje

Módulos nuevos, mejorados y obsoletos

Optimizaciones

IDLE

Cambios en la compilación y la API de C

Portando a Python 3.1

Qué hay de nuevo en Python 3.0

Escollos comunes

Print es una función

Vistas e iteradores en lugar de listas

Comparaciones de ordenamiento

Enteros

Texto vs. datos en lugar de unicode vs. 8 bits

Descripción general de los cambios de sintaxis

Nueva sintaxis

Sintaxis modificada

Sintaxis eliminada

Cambios ya presentes en Python 2.6

Cambios de biblioteca

PEP 3101: Un nuevo enfoque al formateo de cadena de caracteres

Cambios a excepciones

Otros cambios diversos

Operadores y métodos especiales

Incorporados

Construcción y cambios a la API de C

Rendimiento

Migración a Python 3.0

Qué hay de nuevo en Python 2.7

El futuro de Python 2.x

Cambios en el manejo de las advertencias de desuso

Características de Python 3.1

PEP 372: Adición de un diccionario ordenado a las colecciones

PEP 378: Especificador de formato para separador de miles

PEP 389: El módulo argparse para el análisis de líneas de comando

PEP 391: Configuración basada en diccionarios para el registro

PEP 3106: Vistas de diccionario

PEP 3137: El objeto memoryview

Otros cambios de lenguaje

Cambios en el intérprete

Optimizaciones

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

Two new environment variables for debug mode

PEP 434: IDLE Enhancement Exception for All Branches

PEP 466: Network Security Enhancements for Python 2.7

PEP 477: Backport ensurepip (PEP 453) to Python 2.7

Bootstrapping pip By Default

Documentation Changes

PEP 476: Enabling certificate verification by default for stdlib http clients

PEP 493: HTTPS verification migration tools for Python 2.7

New make regen-all build target

Removal of make touch build target

Acknowledgements

Qué hay de nuevo en Python 2.6

Python 3.0

Cambios en el proceso de desarrollo

Nuevo seguidor de incidentes: Roundup

Nuevo formato de documentación: texto reestructurado con Sphinx

PEP 343: La sentencia “with”

Escribiendo gestores de contexto

El módulo contextlib

PEP 366: Importaciones relativas explícitas desde un módulo principal

PEP 370: Directorio de site-packages por usuario

PEP 371: El paquete multiprocessing

PEP 3101: Formateo avanzado de cadena de caracteres

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

Optimizaciones

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

Agradecimientos

Novedades de Python 2.5

PEP 308: Expresiones condicionales

PEP 309: Aplicación parcial de funciones

PEP 314: Metadatos para paquetes de software Python v1.1

PEP 328: Importaciones absolutas y relativas

PEP 338: Ejecutando Módulos como Scripts

PEP 341: Try/except/finally unificados

PEP 342: Nuevas funciones del generador

PEP 343: La declaración «con

Redacción de Gestores de Contexto

El módulo contextlib

PEP 352: Las excepciones como clases de nuevo estilo

PEP 353: Uso de ssize_t como tipo de índice

PEP 357: El método “__index__”

Otros cambios lingüísticos

Cambios en el intérprete interactivo

Optimizaciones

Módulos nuevos, mejorados y eliminados

El paquete ctypes

El paquete ElementTree

El paquete hashlib

El paquete sqlite3

El paquete wsgiref

Cambios en la API de construcción y C

Cambios específicos en los puertos

Adaptación a Python 2.5

Agradecimientos

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

Qué hay de nuevo en Python 2.3

PEP 218: Un tipo de datos de conjunto estándar

PEP 255: Generadores simples

PEP 263: Codificación del código fuente

PEP 273: Importar módulos desde archivos ZIP

PEP 277: Soporte de nombres de archivo Unicode para Windows NT

PEP 278: Soporte universal de nuevas líneas

PEP 279: enumerate()

PEP 282: El paquete de registro

PEP 285: Un tipo booleano

PEP 293: Llamadas de retorno para el manejo de errores del códec

PEP 301: Índice de paquetes y metadatos para Distutils

PEP 302: Nuevos ganchos de importación

PEP 305: Archivos separados por comas

PEP 307: Mejoras en Pickle

Rebanadas ampliadas

Otros cambios en el lenguaje

Cambios en las cadenas de texto

Optimizaciones

Módulos nuevos, mejorados y obsoletos

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

Qué hay de nuevo en Python 2.2

Introducción

PEPs 252 y 253: Cambios de tipo y clase

Clases antiguas y nuevas

Descriptores

Herencia múltiple: la regla del diamante

Acceso a atributos

Enlaces relacionados

PEP 234: Iteradores

PEP 255: Generadores simples

PEP 237: Unificación de enteros largos y enteros

PEP 238: Cambio del operador de división

Cambios en Unicode

PEP 227: Ámbitos anidados

Módulos nuevos y mejorados

Cambios y correcciones en el intérprete

Otros cambios y correcciones

Agradecimientos

Novedades de Python 2.1

Introducción

PEP 227: Ámbitos anidados

PEP 236: Directivas __future__

PEP 207: Comparaciones Enriquecidas

PEP 230: Marco de advertencia

PEP 229: Sistema de construcción nuevo

PEP 205: Referencias débiles

PEP 232: Atributos de la función

PEP 235: Importación de módulos en plataformas que no distinguen entre mayúsculas y minúsculas

PEP 217: Gancho de pantalla interactivo

PEP 208: Nuevo modelo de coerción

PEP 241: Metadatos en paquetes de Python

Módulos nuevos y mejorados

Otros cambios y correcciones

Agradecimientos

Novedades de Python 2.0

Introducción

¿Qué pasa con Python 1.6?

Nuevo proceso de desarrollo

Unicode

Comprensión de listas

Asignación aumentada

Métodos de cadena de caracteres

Recogida de basura de los ciclos

Otros cambios en el núcleo

Cambios menores del lenguaje

Cambios en las funciones incorporadas

Adaptación a la versión 2.0

Extensión/Incorporación de cambios

Distutils: Facilitando la instalación de módulos

Módulos XML

Soporte de SAX2

Soporte DOM

Relación con PyXML

Cambios en los módulos

Nuevos módulos

Mejoras en IDLE

Módulos eliminados y obsoletos

Agradecimientos

Changelog

Python next

Security

Core and Builtins

Library

Windows

Tools/Demos

Python 3.9.18 final

Security

Library

Tools/Demos

C API

Python 3.9.17 final

Security

Core and Builtins

Library

Windows

macOS

Python 3.9.16 final

Security

Python 3.9.15 final

Security

Core and Builtins

Library

Windows

macOS

Python 3.9.14 final

Security

Core and Builtins

Library

Tests

Python 3.9.13 final

Core and Builtins

Library

Documentation

Tests

Build

Windows

Tools/Demos

Python 3.9.12 final

Core and Builtins

Library

Python 3.9.11 final

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Python 3.9.10 final

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

Tools/Demos

C API

Python 3.9.9 final

Core and Builtins

Library

Documentation

Windows

Python 3.9.8 final

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

C API

Python 3.9.7 final

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

Python 3.9.6 final

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

C API

Python 3.9.5 final

Security

Core and Builtins

Library

Documentation

Tests

Windows

macOS

IDLE

Python 3.9.4 final

Core and Builtins

Library

Python 3.9.3 final

Security

Core and Builtins

Library

Documentation

Tests

Build

macOS

IDLE

Python 3.9.2 final

Windows

Python 3.9.2 release candidate 1

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

C API

Python 3.9.1 final

Core and Builtins

Library

Tests

macOS

IDLE

Python 3.9.1 release candidate 1

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

C API

Python 3.9.0 final

Library

Tests

Build

Python 3.9.0 release candidate 2

Core and Builtins

Library

Documentation

Tests

Build

Windows

C API

Python 3.9.0 release candidate 1

Core and Builtins

Library

Documentation

Windows

IDLE

Python 3.9.0 beta 5

Security

Core and Builtins

Library

Documentation

macOS

IDLE

C API

Python 3.9.0 beta 4

Security

Core and Builtins

Library

Tests

Build

Windows

macOS

IDLE

C API

Python 3.9.0 beta 3

Library

Build

Python 3.9.0 beta 2

Core and Builtins

Library

Tests

Build

Windows

macOS

IDLE

C API

Python 3.9.0 beta 1

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

Tools/Demos

C API

Python 3.9.0 alpha 6

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

C API

Python 3.9.0 alpha 5

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

C API

Python 3.9.0 alpha 4

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

IDLE

C API

Python 3.9.0 alpha 3

Core and Builtins

Library

Documentation

Build

IDLE

C API

Python 3.9.0 alpha 2

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

C API

Python 3.9.0 alpha 1

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

C API

Python 3.8.0 beta 1

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

C API

Python 3.8.0 alpha 4

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

C API

Python 3.8.0 alpha 3

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

IDLE

Tools/Demos

C API

Python 3.8.0 alpha 2

Core and Builtins

Library

Documentation

Tests

Windows

IDLE

Python 3.8.0 alpha 1

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

C API

Python 3.7.0 final

Library

C API

Python 3.7.0 release candidate 1

Core and Builtins

Library

Documentation

Build

Windows

IDLE

Python 3.7.0 beta 5

Core and Builtins

Library

Documentation

Tests

Build

macOS

IDLE

Python 3.7.0 beta 4

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

Python 3.7.0 beta 3

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

C API

Python 3.7.0 beta 2

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

Python 3.7.0 beta 1

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

C API

Python 3.7.0 alpha 4

Core and Builtins

Library

Documentation

Tests

Windows

Tools/Demos

C API

Python 3.7.0 alpha 3

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

C API

Python 3.7.0 alpha 2

Core and Builtins

Library

Documentation

Build

IDLE

C API

Python 3.7.0 alpha 1

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

IDLE

Tools/Demos

C API

Python 3.6.6 final

Python 3.6.6 release candidate 1

Core and Builtins

Library

Documentation

Tests

Build

Windows

macOS

IDLE

Tools/Demos

C API

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

Security

Core and Builtins

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

Security

Core and Builtins

Library

IDLE

C API

Build

Tools/Demos

Documentation

Tests

Python 3.6.0 alpha 2

Security

Core and Builtins

Library

IDLE

Documentation

Tests

Windows

Build

C API

Tools/Demos

Python 3.6.0 alpha 1

Security

Core and Builtins

Library

IDLE

Documentation

Tests

Build

Windows

Tools/Demos

C API

Python 3.5.5 final

Python 3.5.5 release candidate 1

Security

Core and Builtins

Library

Python 3.5.4 final

Library

Python 3.5.4 release candidate 1

Security

Core and Builtins

Library

Documentation

Tests

Build

Windows

C API

Python 3.5.3 final

Python 3.5.3 release candidate 1

Security

Core and Builtins

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

Security

Core and Builtins

Library

IDLE

Documentation

Tests

Build

Windows

Tools/Demos

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

Tutorial de Python

1. Abriendo el apetito

2. Usando el intérprete de Python

2.1. Invocando al intérprete

2.1.1. Paso de argumentos

2.1.2. Modo interactivo

2.2. El intérprete y su entorno

2.2.1. Codificación del código fuente

3. Una introducción informal a Python

3.1. Usando Python como una calculadora

3.1.1. Números

3.1.2. Cadenas de caracteres

3.1.3. Listas

3.2. Primeros pasos hacia la programación

4. Más herramientas para control de flujo

4.1. La sentencia if

4.2. La sentencia for

4.3. La función range()

4.4. Las sentencias break, continue, y else en bucles

4.5. La sentencia pass

4.6. Definiendo funciones

4.7. Más sobre definición de funciones

4.7.1. Argumentos con valores por omisión

4.7.2. Palabras claves como argumentos

4.7.3. Parámetros especiales

4.7.3.1. Argumentos posicionales o de palabras claves

4.7.3.2. Parámetros únicamente posicionales

4.7.3.3. Argumentos únicamente de palabras clave

4.7.3.4. Ejemplos de Funciones

4.7.3.5. Resumen

4.7.4. Listas de argumentos arbitrarios

4.7.5. Desempaquetando una lista de argumentos

4.7.6. Expresiones lambda

4.7.7. Cadenas de texto de documentación

4.7.8. Anotación de funciones

4.8. Intermezzo: Estilo de codificación

5. Estructuras de datos

5.1. Más sobre listas

5.1.1. Usando listas como pilas

5.1.2. Usando listas como colas

5.1.3. Comprensión de listas

5.1.4. Listas por comprensión anidadas

5.2. La instrucción del

5.3. Tuplas y secuencias

5.4. Conjuntos

5.5. Diccionarios

5.6. Técnicas de iteración

5.7. Más acerca de condiciones

5.8. Comparando secuencias y otros tipos

6. Módulos

6.1. Más sobre los módulos

6.1.1. Ejecutando módulos como scripts

6.1.2. El camino de búsqueda de los módulos

6.1.3. Archivos «compilados» de Python

6.2. Módulos estándar

6.3. La función dir()

6.4. Paquetes

6.4.1. Importando * desde un paquete

6.4.2. Referencias internas en paquetes

6.4.3. Paquetes en múltiples directorios

7. Entrada y salida

7.1. Formateo elegante de la salida

7.1.1. Formatear cadenas literales

7.1.2. El método format() de cadenas

7.1.3. Formateo manual de cadenas

7.1.4. Viejo formateo de cadenas

7.2. Leyendo y escribiendo archivos

7.2.1. Métodos de los objetos Archivo

7.2.2. Guardar datos estructurados con json

8. Errores y excepciones

8.1. Errores de sintaxis

8.2. Excepciones

8.3. Gestionando excepciones

8.4. Lanzando excepciones

8.5. Encadenamiento de excepciones

8.6. Excepciones definidas por el usuario

8.7. Definiendo acciones de limpieza

8.8. Acciones predefinidas de limpieza

9. Clases

9.1. Unas palabras sobre nombres y objetos

9.2. Ámbitos y espacios de nombres en Python

9.2.1. Ejemplo de ámbitos y espacios de nombre

9.3. Un primer vistazo a las clases

9.3.1. Sintaxis de definición de clases

9.3.2. Objetos clase

9.3.3. Objetos instancia

9.3.4. Objetos método

9.3.5. Variables de clase y de instancia

9.4. Algunas observaciones

9.5. Herencia

9.5.1. Herencia múltiple

9.6. Variables privadas

9.7. Cambalache

9.8. Iteradores

9.9. Generadores

9.10. Expresiones generadoras

10. Pequeño paseo por la Biblioteca Estándar

10.1. Interfaz al sistema operativo

10.2. Comodines de archivos

10.3. Argumentos de linea de órdenes

10.4. Redirigir la salida de error y finalización del programa

10.5. Coincidencia en patrones de cadenas

10.6. Matemática

10.7. Acceso a Internet

10.8. Fechas y tiempos

10.9. Compresión de datos

10.10. Medición de rendimiento

10.11. Control de calidad

10.12. Las pilas incluidas

11. Pequeño paseo por la Biblioteca Estándar— Parte II

11.1. Formato de salida

11.2. Plantillas

11.3. Trabajar con registros estructurados conteniendo datos binarios

11.4. Multi-hilos

11.5. Registrando

11.6. Referencias débiles

11.7. Herramientas para trabajar con listas

11.8. Aritmética de punto flotante decimal

12. Entornos Virtuales y Paquetes

12.1. Introducción

12.2. Creando Entornos Virtuales

12.3. Manejando paquetes con pip

13. ¿Y ahora qué?

14. Edición de entrada interactiva y sustitución de historial

14.1. Autocompletado con tab e historial de edición

14.2. Alternativas al intérprete interactivo

15. Aritmética de Punto Flotante: Problemas y Limitaciones

15.1. Error de Representación

16. Apéndice

16.1. Modo interactivo

16.1.1. Manejo de errores

16.1.2. Programas ejecutables de Python

16.1.3. El archivo de inicio interactivo

16.1.4. Los módulos de customización

Configuración y Uso de Python

1. Línea de comandos y entorno

1.1. Línea de comando

1.1.1. Opciones de interfaz

1.1.2. Opciones genéricas

1.1.3. Opciones diversas

1.1.4. Opciones que no debe usar

1.2. Variables de entorno

1.2.1. Variables de modo de depuración

2. Uso de Python en plataformas Unix

2.1. Obteniendo e instalando la última versión de Python

2.1.1. En Linux

2.1.2. En FreeBSD y OpenBSD

2.1.3. En OpenSolaris

2.2. Construyendo Python

2.3. Rutas y archivos relacionados con Python

2.4. Miscelánea

3. Uso de Python en Windows

3.1. El instalador completo

3.1.1. Pasos para la instalación

3.1.2. Quitar el límite de MAX_PATH

3.1.3. Instalación sin interfaz de usuario

3.1.4. Instalación sin descargas

3.1.5. Modificar una instalación

3.2. El paquete Microsoft Store

3.2.1. Problemas conocidos

3.3. El paquete de nuget.org

3.4. El paquete incrustable

3.4.1. Aplicación Python

3.4.2. Incrustar Python

3.5. Distribuciones alternativas

3.6. Configuración de Python

3.6.1. Excurso: configurar variables de entorno

3.6.2. Encontrar el ejecutable de Python

3.7. Modo UTF-8

3.8. Lanzador de Python para Windows

3.8.1. Comenzar

3.8.1.1. Desde la línea de comandos

3.8.1.2. Entornos virtuales

3.8.1.3. Desde un script

3.8.1.4. Desde asociaciones de archivos

3.8.2. Líneas shebang

3.8.3. Argumentos en líneas shebang

3.8.4. Personalización

3.8.4.1. Personalización con archivos INI

3.8.4.2. Personalizar las versiones de Python predeterminadas

3.8.5. Diagnóstico

3.9. Encontrar módulos

3.10. Módulos adicionales

3.10.1. PyWin32

3.10.2. cx_Freeze

3.11. Compilar Python en Windows

3.12. Otras plataformas

4. Using Python on a Mac

4.1. Obteniendo e instalando MacPython

4.1.1. Cómo ejecutar un script de Python

4.1.2. Ejecutar scripts con una GUI

4.1.3. Configuración

4.2. El IDE

4.3. Instalación de paquetes adicionales de Python

4.4. Programación de GUI en Mac

4.5. Distribuyendo aplicaciones de Python en la Mac

4.6. Otros recursos

5. Editores e IDEs

Referencia del Lenguaje Python

1. Introducción

1.1. Implementaciones alternativas

1.2. Notación

2. Análisis léxico

2.1. Estructura de línea

2.1.1. Líneas lógicas

2.1.2. Líneas físicas

2.1.3. Comentarios

2.1.4. Declaración de Codificación

2.1.5. Unión explícita de líneas

2.1.6. Unión implícita de líneas

2.1.7. Líneas en blanco

2.1.8. Sangría

2.1.9. Espacios en blanco entre tokens

2.2. Otros tokens

2.3. Identificadores y palabras clave

2.3.1. Palabras clave

2.3.2. Clases reservadas de identificadores

2.4. Literales

2.4.1. Literales de cadenas y bytes

2.4.2. Concatenación de literales de cadena

2.4.3. Literales de cadena formateados

2.4.4. Literales numéricos

2.4.5. Literales enteros

2.4.6. Literales de punto flotante

2.4.7. Literales imaginarios

2.5. Operadores

2.6. Delimitadores

3. Modelo de datos

3.1. Objetos, valores y tipos

3.2. Jerarquía de tipos estándar

3.3. Nombres especiales de método

3.3.1. Personalización básica

3.3.2. Personalizando acceso a atributos

3.3.2.1. Personalizando acceso a atributos de módulo

3.3.2.2. Implementando Descriptores

3.3.2.3. Invocando Descriptores

3.3.2.4. __slots__

3.3.2.4.1. Notas sobre el uso de __slots__

3.3.3. Personalización de creación de clases

3.3.3.1. Metaclases

3.3.3.2. Resolviendo entradas de la Orden de Resolución de Métodos (MRU)

3.3.3.3. Determinando la metaclase adecuada

3.3.3.4. Preparando el espacio de nombres de la clase

3.3.3.5. Ejecutando el cuerpo de la clase

3.3.3.6. Creando el objeto de clase

3.3.3.7. Usos para metaclases

3.3.4. Personalizando revisiones de instancia y subclase

3.3.5. Emulando tipos genéricos

3.3.5.1. The purpose of __class_getitem__

3.3.5.2. __class_getitem__ versus __getitem__

3.3.6. Emulando objetos que se pueden llamar

3.3.7. Emulando tipos de contenedores

3.3.8. Emulando tipos numéricos

3.3.9. Gestores de Contexto en la Declaración with

3.3.10. Búsqueda de método especial

3.4. Corrutinas

3.4.1. Objetos Esperables

3.4.2. Objetos de Corrutina

3.4.3. Iteradores asíncronos

3.4.4. Gestores de Contexto Asíncronos

4. Modelo de ejecución

4.1. Estructura de un programa

4.2. Nombres y vínculos

4.2.1. Vinculación de nombres

4.2.2. Resolución de nombres

4.2.3. Integraciones y ejecución restringida

4.2.4. Interacción con funcionalidades dinámicas

4.3. Excepciones

5. El sistema de importación

5.1. importlib

5.2. Paquetes

5.2.1. Paquetes regulares

5.2.2. Paquetes de espacio de nombres

5.3. Buscando

5.3.1. La caché del módulo

5.3.2. Buscadores y cargadores

5.3.3. Ganchos de importación

5.3.4. La meta ruta (path)

5.4. Cargando

5.4.1. Cargadores

5.4.2. Submódulos

5.4.3. Especificaciones del módulo

5.4.4. Atributos de módulo relacionados con la importación

5.4.5. module.__path__

5.4.6. Representación (Reprs) de módulos

5.4.7. Invalidación del código de bytes en caché

5.5. El buscador basado en rutas

5.5.1. Buscadores de entradas de ruta

5.5.2. Buscadores de entradas de ruta

5.6. Reemplazando el sistema de importación estándar

5.7. Paquete Importaciones relativas

5.8. Consideraciones especiales para __main__

5.8.1. __main__.__spec__

5.9. Problemas sin resolver

5.10. Referencias

6. Expresiones

6.1. Conversiones aritméticas

6.2. Átomos

6.2.1. Identificadores (Nombres)

6.2.2. Literales

6.2.3. Formas entre paréntesis

6.2.4. Despliegues para listas, conjuntos y diccionarios

6.2.5. Despliegues de lista

6.2.6. Despliegues de conjuntos

6.2.7. Despliegues de diccionario

6.2.8. Expresiones de generador

6.2.9. Expresiones yield

6.2.9.1. Métodos generador-iterador

6.2.9.2. Ejemplos

6.2.9.3. Funciones generadoras asincrónicas

6.2.9.4. Métodos asincrónicos de generador-iterador

6.3. Primarios

6.3.1. Referencias de atributos

6.3.2. Suscripciones

6.3.3. Segmentos

6.3.4. Invocaciones

6.4. Expresión await

6.5. El operador de potencia

6.6. Aritmética unaria y operaciones bit a bit

6.7. Operaciones aritméticas binarias

6.8. Operaciones de desplazamiento

6.9. Operaciones bit a bit binarias

6.10. Comparaciones

6.10.1. Comparaciones de valor

6.10.2. Operaciones de prueba de membresía

6.10.3. Comparaciones de identidad

6.11. Operaciones booleanas

6.12. Expresiones de asignación

6.13. Expresiones condicionales

6.14. Lambdas

6.15. Listas de expresiones

6.16. Orden de evaluación

6.17. Prioridad de operador

7. Declaraciones simples

7.1. Declaraciones de tipo expresión

7.2. Declaraciones de asignación

7.2.1. Declaraciones de asignación aumentada

7.2.2. Declaraciones de asignación anotadas

7.3. La declaración assert

7.4. La declaración pass

7.5. La declaración del

7.6. La declaración return

7.7. La declaración yield

7.8. La declaración raise

7.9. La declaración break

7.10. La declaración continue

7.11. La declaración import

7.11.1. Declaraciones Futuras

7.12. La declaración global

7.13. La declaración nonlocal

8. Sentencias compuestas

8.1. La sentencia if

8.2. La sentencia while

8.3. La sentencia for

8.4. La sentencia try

8.5. La sentencia with

8.6. Definiciones de funciones

8.7. Definiciones de clase

8.8. Corrutinas

8.8.1. Definición de la función corrutina

8.8.2. La sentencia async for

8.8.3. La sentencia async with

9. Componentes de nivel superior

9.1. Programas completos de Python

9.2. Entrada de archivo

9.3. Entrada interactiva

9.4. Entrada de expresión

10. Especificación completa de la gramática

La Biblioteca Estándar de Python

Introducción

Notas sobre la disponibilidad

Funciones Built-in

Constantes incorporadas

Constantes agregadas por el módulo site

Tipos Integrados

Evaluar como valor verdadero/falso

Operaciones booleanas — and, or, not

Comparaciones

Tipos numéricos — int, float, complex

Operaciones de bits en números enteros

Métodos adicionales de los enteros

Métodos adicionales de Float

Calculo del hash de tipos numéricos

Tipos de iteradores

Tipos Generador

Tipos secuencia — list, tuple, range

Operaciones comunes de las secuencias

Tipos de secuencia inmutables

Tipos de secuencia mutables

Listas

Tuplas

Rangos

Cadenas de caracteres — str

Métodos de las cadenas de caracteres

Formateo de cadenas al estilo *printf*

Tipos de secuencias binarias — bytes, bytearray y memoryview

Objetos de tipo Bytes

Objetos de tipo Bytearray

Operaciones de bytes y bytearray

Usando el formateo tipo printf con bytes

Vistas de memoria

Conjuntos — set, frozenset

Tipos Mapa — dict

Objetos tipos vista de diccionario

Tipos Gestores de Contexto

Tipo Alias Genérico

Standard Generic Classes

Special Attributes of GenericAlias objects

Otros tipos predefinidos

Módulos

Clases e instancias de clase

Funciones

Métodos

Objetos código

Objetos Tipo

El objeto nulo (Null)

El objeto puntos suspensivos (Ellipsis)

El objeto NotImplemented

Valores booleanos

Objetos internos

Atributos especiales

Integer string conversion length limitation

Affected APIs

Configuring the limit

Recommended configuration

Excepciones incorporadas

Exception context

Inheriting from built-in exceptions

Clases base

Excepciones específicas

Excepciones del sistema operativo

Advertencias

Jerarquía de excepción

Servicios de procesamiento de texto

string — Operaciones comunes de cadena de caracteres

Constantes de cadenas

Formato de cadena de caracteres personalizado

Sintaxis de formateo de cadena

Especificación de formato Mini-Lenguaje

Ejemplos de formateo

Cadenas de plantillas

Funciones de ayuda

re — Operaciones con expresiones regulares

Sintaxis de expresiones regulares

Contenidos del módulo

Objetos expresión regular

Objetos de coincidencia

Ejemplos de expresiones regulares

Buscando un par

Simular scanf()

search() vs. match()

Haciendo una guía telefónica

Mungear texto

Encontrar todos los adverbios

Encontrar todos los adverbios y sus posiciones

Notación de cadena raw

Escribir un Tokenizador

difflib — Funciones auxiliares para calcular deltas

Objetos SequenceMatcher

SequenceMatcher Ejemplos

Objetos Differ

Ejemplo de Differ

Una interfaz de línea de comandos para difflib

textwrap — Envoltura y relleno de texto

unicodedata — Base de datos Unicode

stringprep — Preparación de cadenas de Internet

readline — Interfaz readline de GNU

Archivo de inicio

Búfer de línea

Archivo de historial

Lista del historial

Ganchos (hooks) de inicialización

Terminación

Ejemplo

rlcompleter — Función de completado para GNU readline

Objetos de Completado

Servicios de datos binarios

struct — Interpreta bytes como paquetes de datos binarios

Funciones y Excepciones

Cadenas de Formato

Orden de Bytes, Tamaño y Alineación

Formato de caracteres

Ejemplos

Clases

codecs — Registro de códec y clases base

Clases Base de Códec

Manejadores de errores

Codificación y decodificación sin estado

Codificación y decodificación incrementales

Objetos IncrementalEncoder

Objetos IncrementalDecoder

Codificación y decodificación de flujos

Objetos StreamWriter

Objetos StreamReader

Objetos StreamReaderWriter

Objetos StreamRecoder

Codificaciones y Unicode

Codificaciones estándar

Codificaciones específicas de Python

Codificaciones de texto

Transformaciones Binarias

Transformaciones de texto

encodings.idna — Nombres de dominio internacionalizados en aplicaciones

encodings.mbcs — Página de códigos ANSI de Windows

encodings.utf_8_sig — Códec UTF-8 con firma BOM

Tipos de datos

datetime — Tipos básicos de fecha y hora

Objetos conscientes (aware) y naífs (naive)

Constantes

Tipos disponibles

Propiedades comunes

Determinando si un objeto es Consciente (Aware) o Naíf (Naive)

Objetos timedelta

Ejemplos de uso: timedelta

Objeto date

Ejemplos de uso: date

Objetos datetime

Ejemplos de uso: datetime

Objetos time

Ejemplos de uso: time

Objetos tzinfo

Objetos timezone

Comportamiento strftime() y strptime()

Códigos de formato strftime() y strptime()

Detalle técnico

zoneinfo — Soporte de zona horaria IANA

Usando ZoneInfo

Fuentes de datos

Configurando los orígenes de datos

Configuración en tiempo de compilación

Configuración del entorno

Configuración de tiempo de ejecución

La clase ZoneInfo

Representaciones de cadenas

Serialización de Pickle

Funciones

Globales

Excepciones y advertencias

calendar — Funciones generales relacionadas con el calendario

collections — Tipos de datos contenedor

Objetos ChainMap

Ejemplos y recetas ChainMap

Objetos Counter

Objetos deque

Recetas deque

Objetos defaultdict

Ejemplos defaultdict

namedtuple() Funciones Factory para Tuplas y Campos con Nombres

Objetos OrderedDict

Ejemplos y Recetas OrderedDict

Objetos UserDict

Objetos UserList

Objetos UserString

collections.abc — Clases Base Abstractas para Contenedores

Colecciones Clases Base Abstractas

heapq — Algoritmo de colas montículos (heap)

Ejemplos Básicos

Notas de Aplicación de la Cola de Prioridades

Teoría

bisect — Algoritmo de bisección de arreglos

Búsqueda en listas ordenadas

Otros ejemplos

array — Arreglos eficientes de valores numéricos

weakref — Referencias débiles

Objetos de Referencias Débiles

Ejemplo

Objetos Finalizadores

Comparando finalizadores con los métodos __del__()

types — Creación de tipos dinámicos y nombres para tipos integrados

Creación dinámica de tipos

Tipos de Intérpretes Estándar

Clases y funciones de utilidad adicionales

Funciones de utilidad de corutina

copy — Operaciones de copia superficial y profunda

pprint — Impresión bonita de datos

Objetos PrettyPrinter

Ejemplo

reprlib — Implementación repr() alternativa

Objetos Repr

Subclasificando Objetos Repr

enum — Soporte para enumeraciones

Contenido del Módulo

Creando un Enum

Acceso programático a los miembros de la enumeración y sus atributos

Duplicando miembros y valores enum

Garantizando valores de enumeración únicos

Usando valores automáticos

Iteración

Comparaciones

Miembros permitidos y atributos de enumeraciones

Subclases restringidas de Enum

Serialización

API Funcional

Enumeraciones derivadas

IntEnum

IntFlag

Bandera

Otros

Cuándo usar __new__() contra __init__()

Ejemplos interesantes

Omitir valores

Usando auto

Usando object

Usando una cadena descriptiva

Usando __new__() personalizados

OrderedEnum

DuplicateFreeEnum

Planeta

Periodo de tiempo

¿Cómo son diferentes las Enums?

Clases Enum

Miembros de Enum (también conocidos como instancias)

Puntos más finos

Nombres soportados __dunder__

Nombres _sunder_ compatibles

_Private__names

Tipo de miembro Enum

Valor booleano de las clases y miembros Enum

Enum clases con métodos

Combinando miembros de``Flag``

graphlib — Functionality to operate with graph-like structures

Exceptions

Módulos numéricos y matemáticos

numbers — Clase base abstracta numérica

La torre numérica

Notas para implementadores de tipos

Agregar más ABCs numéricos

Implementar operaciones aritméticas

math — Funciones matemáticas

Teoría de números y funciones de representación

Funciones logarítmicas y exponenciales

Funciones trigonométricas

Conversión angular

Funciones hiperbólicas

Funciones especiales

Constantes

cmath – Función matemática para números complejos

Conversión a y desde coordenadas polares

Funciones logarítmicas y de potencias

Funciones trigonométricas

Funciones hiperbólicas

Funciones de clasificación

Constantes

decimal — Aritmética decimal de coma fija y coma flotante

Tutorial de inicio rápido

Objetos Decimal

Operandos lógicos

Objetos Context

Constantes

Modos de redondeo

Señales

Notas sobre la representación en coma flotante

Mitigación del error de redondeo usando mayor precisión

Valores especiales

Trabajando con hilos

Casos prácticos

Preguntas frecuentes sobre Decimal

fractions — Números racionales

random —Generar números pseudoaleatorios

Funciones de contabilidad

Funciones para los bytes

Funciones para enteros

Funciones para secuencias

Distribuciones para los nombres reales

Generador alternativo

Notas sobre la Reproducibilidad

Ejemplos

Recetas

statistics — Funciones de estadística matemática

Promedios y medidas de tendencia central

Medidas de dispersión

Detalles de las funciones

Excepciones

Objetos NormalDist

Ejemplos de uso de NormalDist

Módulos de programación funcional

itertools — Funciones que crean iteradores para bucles eficientes

Funciones de itertools

Fórmulas con itertools

functools — Funciones de orden superior y operaciones sobre objetos invocables

partial Objetos

operator — Operadores estándar como funciones

Asignación de operadores a funciones

Operadores In-place

Acceso a archivos y directorios

pathlib — Object-oriented filesystem paths

Uso básico

Rutas puras

Propiedades generales

Operadores

Acceso a partes individuales

Métodos y propiedades

Rutas concretas

Métodos

Correspondencia a herramientas en el módulo os

os.path — Manipulaciones comunes de nombre de ruta

fileinput — Iterar sobre líneas de múltiples flujos de entrada

stat — Interpretación de los resultados de stat()

filecmp— Comparaciones de Archivo y Directorio

La clase dircmp

tempfile — Generar archivos y directorios temporales

Ejemplos

Funciones y variables deprecadas

glob — Expansión del patrón de nombres de ruta de estilo Unix

fnmatch — Coincidencia de patrones de nombre de archivos Unix

linecache — Acceso aleatorio a líneas de texto

shutil — Operaciones de archivos de alto nivel

Operaciones de directorios y archivos

Operaciones de copia eficientes dependientes de la plataforma

ejemplo de copytree

ejemplo de rmtree

Operaciones de archivado

Ejemplo de archivado

Ejemplo de archivado con base_dir

Consulta el tamaño de la terminal de salida

Persistencia de datos

pickle — Serialización de objetos Python

Relación con otros módulos de Python

Comparación con marshal

Comparación con json

Formato de flujo de datos

Interfaz del módulo

¿Qué se puede serializar (pickled) y deserializar (unpickled) con pickle?

Pickling de Instancias de clases

Persistencia de objetos externos

Tablas de despacho

Manejo de objetos con estado

Reducción personalizada para tipos, funciones y otros objetos

Búferes fuera de banda

API de proveedor

API de consumidor

Ejemplo

Restricción de Globals

Performance

Ejemplos

copyreg — Registrar funciones de soporte de pickle

Ejemplo

shelve — Persistencia de objetos de Python

Restricciones

Ejemplo

marshal — Serialización interna de objetos Python

dbm — Interfaces para «bases de datos» de Unix

dbm.gnu — La reinterpretación de GNU de dbm

dbm.ndbm — Interfaz basada en ndbm

dbm.dumb — Implementación de DBM portátil

sqlite3 — DB-API 2.0 interfaz para bases de datos SQLite

Funciones y constantes del módulo

Objetos de conexión

Objetos Cursor

Objetos Fila (Row)

Excepciones

SQLite y tipos de Python

Introducción

Usando adaptadores para almacenar tipos adicionales de Python en bases de datos SQLite

Permitiéndole al objeto auto adaptarse

Registrando un adaptador invocable

Convertir valores SQLite a tipos de Python personalizados

Adaptadores y convertidores por defecto

Controlando Transacciones

Usando sqlite3 eficientemente

Usando métodos atajo

Accediendo a las columnas por el nombre en lugar del índice

Usando la conexión como un administrador de contexto

Compresión de datos y archivado

zlib — Compresión compatible con gzip

gzip — Soporte para archivos gzip

Ejemplos de uso

Interfaz de Línea de Comandos

Opciones de línea de comandos

bz2 — Soporte para compresión bzip2

(De)compresión de archivos

(De)compresión incremental

(Des)comprimir en un solo paso

Ejemplos de uso

lzma — Compresión utilizando el algoritmo LZMA

Leyendo y escribiendo ficheros comprimidos

Comprimiendo y descomprimiendo datos en memoria

Misceláneas

Especificando cadenas de filtro personalizadas

Ejemplos

zipfile — Trabajar con archivos ZIP

Objetos ZipFile

Objetos de ruta

Objetos PyZipFile

Objetos ZipInfo

Interfaz de línea de comandos

Opciones de línea de comando

Problemas de descompresión

Del archivo mismo

Limitaciones del sistema de archivos

Limitaciones de recursos

Interrupción

Comportamientos predeterminados de extracción

tarfile — Leer y escribir archivos tar

Objetos TarFile

Objetos TarInfo

Extraction filters

Default named filters

Filter errors

Hints for further verification

Supporting older Python versions

Stateful extraction filter example

Interfaz de línea de comandos

Opciones de línea de comandos

Ejemplos

Formatos tar con soporte

Problemas Unicode

Formatos de archivo

csv — Lectura y escritura de archivos CSV

Contenidos del módulo

Dialectos y parámetros de formato

Objetos Reader

Objetos Writer

Ejemplos

configparser — Parser para archivos de configuración

Inicio Rápido

Tipos de Datos Soportados

Valores de contingencia

Estructura Soportada para el Archivo INI

Interpolación de valores

Acceso por Protocolo de Mapeo

Personalizando el Comportamiento del Parser

Ejemplos de la API heredada

Objetos ConfigParser

Objetos RawConfigParser

Excepciones

netrc — procesado del fichero netrc

Objetos netrc

plistlib — Genera y analiza archivos .plist de Apple

Ejemplos

Servicios Criptográficos

hashlib — Hashes seguros y resúmenes de mensajes

Algoritmos de hash

Resúmenes SHAKE de largo variable

Derivación de clave

BLAKE2

Creando objetos hash

Constantes

Ejemplos

Cifrado simple

Usar diferentes tamaños de resumen

Cifrado de clave

Cifrado aleatorio

Personalización

Modo de árbol

Créditos

hmac — Hash con clave para autenticación de mensajes

secrets — Genera números aleatorios seguros para trabajar con secretos criptográficos

Números aleatorios

Generando tokens

¿Cuántos bytes deben tener los tokens?

Otras funciones

Recetas y mejores prácticas

Servicios genéricos del sistema operativo

os — Interfaces misceláneas del sistema operativo

Nombres de archivos, argumentos de la línea de comandos y variables de entorno

Parámetros de proceso

Creación de objetos de tipo archivo

Operaciones de descriptores de archivos

Consultando las dimensiones de una terminal

Herencia de los descriptores de archivos

Archivos y directorios

Atributos extendidos de Linux

Gestión de proceso

Interfaz al planificador

Información miscelánea del sistema

Números al azar

io — Herramientas principales para trabajar con streams

Resumen

E/S Texto

E/S Binaria

E/S sin formato

Interfaz de módulo de alto nivel

Jerarquía de clases

Clases base E/S

Archivo sin formato E/S

Streams almacenados (búfer)

E/S Texto

Rendimiento

E/S Binaria

E/S Texto

Multihilo

Reentrada

time — Tiempo de acceso y conversiones

Las Funciones

Constantes de ID de reloj

Constantes de zona horaria

argparse — Analizador sintáctico (Parser) para las opciones, argumentos y sub-comandos de la línea de comandos

Ejemplo

Creando un analizador sintáctico (parser)

Añadiendo argumentos

Analizando argumentos

Objetos ArgumentParser

prog

uso

description

epilog

parents

formatter_class

prefix_chars

fromfile_prefix_chars

argument_default

allow_abbrev

conflict_handler

add_help

exit_on_error

El método add_argument()

name or flags

action

nargs

const

default

type

choices

required

help

metavar

dest

Las clases Action

El método parse_args()

Sintaxis del valor de la opción

Argumentos no válidos

Argumentos conteniendo -

Abreviaturas de los argumentos (coincidencia de prefijos)

Más allá de sys.argv

El objeto Namespace

Otras utilidades

Sub-comandos

Objetos FileType

Grupos de argumentos

Exclusión mutua

Valores por defecto del analizador

Mostrando la ayuda

Análisis parcial

Personalizando el análisis de archivos

Métodos de salida

Análisis entremezclado

Actualizar el código de optparse

getopt — Analizador de estilo C para opciones de línea de comando

logging — Instalación de logging para Python

Objetos Logger

Niveles de logging

Gestor de objetos

Objetos formateadores

Filtro de Objetos

Objetos LogRecord

Atributos LogRecord

Objetos LoggerAdapter

Seguridad del hilo

Funciones a nivel de módulo

Atributos a nivel de módulo

Integración con el módulo de advertencias

logging.config — Configuración de registro

Funciones de configuración

Security considerations

Esquema del diccionario de configuración

Detalles del esquema del diccionario

Configuración incremental

Conexiones de objeto

Objetos definidos por el usuario

Acceso a objetos externos

Acceso a objetos internos

Resolución de importación e importadores personalizados

Formato de archivo de configuración

logging.handlers — Gestores de logging

StreamHandler

FileHandler

NullHandler

WatchedFileHandler

BaseRotatingHandler

RotatingFileHandler

TimedRotatingFileHandler

SocketHandler

DatagramHandler

Gestor SysLog (SysLogHandler)

Gestor de eventos NTELog (NTEventLogHandler)

SMTPHandler

MemoryHandler

HTTPHandler

QueueHandler

QueueListener

getpass — Entrada de contraseña portátil

curses — Manejo de terminales para pantallas de celdas de caracteres

Funciones

Objetos de ventana

Constantes

curses.textpad— Widget de entrada de texto para programas de curses

Objeto de caja de texto

curses.ascii — Utilidades para los caracteres ASCII

curses.panel — Una extensión de pila de panel para curses

Funciones

Objetos de Panel

platform — Acceso a los datos identificativos de la plataforma subyacente

Plataforma cruzada

Plataforma Java

Plataforma windows

macOS Platform

Plataformas Unix

errno — Símbolos estándar del sistema errno

ctypes — Una biblioteca de funciones foráneas para Python

tutorial de ctypes

Carga de bibliotecas de enlaces dinámicos

Acceder a las funciones de los dll cargados

Funciones de llamada

Tipos de datos fundamentales

Funciones de llamada, continuación

Funciones de llamada con sus propios tipos de datos personalizados

Especificar los tipos de argumentos requeridos (prototipos de funciones)

Tipos de retorno

Pasar los punteros (o: pasar los parámetros por referencia)

Estructuras y uniones

Alineación de estructura/unión y orden de bytes

Campos de bits en estructuras y uniones

Arreglos

Punteros

Conversiones de tipos

Tipos incompletos

Funciones de retrollamadas (callback)

Acceder a los valores exportados de los dlls

Sorpresas

Tipos de datos de tamaño variable

referencia ctypes

Encontrar bibliotecas compartidas

Cargando bibliotecas compartidas

Funciones foráneas

Prototipos de funciones

Funciones de utilidad

Tipos de datos

Tipos de datos fundamentales

Tipos de datos estructurados

Arreglos y punteros

Ejecución concurrente

threading — Paralelismo basado en hilos

Datos locales del hilo

Objetos tipo hilo

Objetos tipo lock

Objetos Rlock

Objetos condicionales

Objetos semáforo

Ejemplo de Semaphore

Objetos de eventos

Objetos temporizadores

Objetos de barrera

Uso de locks, condiciones y semáforos en la declaración with

multiprocessing — Paralelismo basado en procesos

Introducción

La clase Process

Contextos y métodos de inicio

Intercambiando objetos entre procesos

Sincronización entre procesos

Compartiendo estado entre procesos

Usando una piscina de trabajadores (pool of workers)

Referencia

Process y excepciones

Tuberías (Pipes) y Colas (Queues)

Miscelánea

Objetos de conexión Connection Objects

Primitivas de sincronización (Synchronization primitives)

Objetos compartidos ctypes

El módulo multiprocessing.sharedctypes

Administradores (Managers)

Administradores customizables (Customized managers)

Utilizando un administrador remoto

Objetos Proxy (Proxy Objects)

Limpieza (Cleanup)

Piscinas de procesos (Process Pools)

Oyentes y Clientes (Listeners and Clients)

Formatos de dirección (Address formats)

Llaves de autentificación

Logging

El módulo multiprocessing.dummy

Pautas de programación

Todos los métodos de inicio

Los métodos de inicio spawn y forkserver

Ejemplos

multiprocessing.shared_memory — Proporciona memoria compartida para acceso directo a través de procesos

El paquete concurrent

concurrent.futures — Lanzamiento de tareas paralelas

Objetos Ejecutores

ThreadPoolExecutor

Ejemplo de ThreadPoolExecutor

ProcessPoolExecutor

Ejemplo de ProcessPoolExecutor

Objetos Futuro

Funciones del Módulo

Clases de Excepciones

subprocess — Gestión de subprocesos

Uso del módulo subprocess

Argumentos frecuentemente empleados

El constructor de Popen

Excepciones

Consideraciones sobre seguridad

Objetos Popen

Elementos auxiliares de Popen en Windows

Constantes de Windows

Antigua API de alto nivel

Cómo reemplazar anteriores funciones con el módulo subprocess

Cómo reemplazar la sustitución de órdenes de /bin/sh

Cómo remplazar los flujos de la shell

Cómo reemplazar os.system()

Cómo reemplazar la familia os.spawn

Cómo reemplazar os.popen(), os.popen2(), os.popen3()

Cómo reemplazar las funciones del módulo popen2

Funciones de llamada a la shell de retrocompatibilidad

Notas

Cómo convertir una secuencia de argumentos a una cadena en Windows

sched — Eventos del planificador

Objetos de Scheduler

queue — clase de cola sincronizada

Objetos de la cola

Objetos de cola simple

contextvars — Variables de Contexto

Variables de Contexto

Gestión de Contexto Manual

Soporte asyncio

_thread — API de bajo nivel para manejo de hilos

Comunicación en redes y entre procesos

asyncio — E/S Asíncrona

Corrutinas y Tareas

Corrutinas

Esperables

Ejecutando un programa asyncio

Creando Tareas

Durmiendo

Ejecutando Tareas Concurrentemente

Protección contra Cancelación

Tiempo agotado

Esperando Primitivas

Ejecutando en Hilos

Planificación Desde Otros Hilos

Introspección

Objeto Task

Corrutinas basadas en generadores

Streams

StreamReader

StreamWriter

Ejemplos

Cliente eco TCP usando streams

Servidor eco TCP usando streams

Obtener encabezados HTTP

Registrar un socket abierto para esperar datos usando streams

Primitivas de sincronización

Lock

Event

Condition

Semaphore

BoundedSemaphore

Sub-procesos

Creando sub-procesos

Constantes

Interactuando con Subprocesos

Subprocesos y Hilos

Ejemplos

Colas

Cola

Cola de prioridad

Cola UEPA (o LIFO en inglés)

Excepciones

Ejemplos

Excepciones

Bucle de eventos

Métodos del bucle de eventos

Iniciar y para el bucle

Programación de llamadas de retorno

Planificando llamadas retardadas

Creando Futuros y Tareas

Abriendo conexiones de red

Creando servidores de red

Transfiriendo archivos

Actualización de TLS

Viendo descriptores de archivos

Trabajar con objetos sockets directamente

DNS

Trabajando con tuberías

Señales Unix

Ejecutando código en un hilos o grupos de procesos

API para manejo de errores

Habilitando el modo depuración

Ejecutando Subprocesos

Gestores de llamadas

Objetos Servidor

Implementaciones del bucle de eventos

Examples

Hola Mundo con call_soon()

Muestra la fecha actual con call_later()

Mirar un descriptor de archivo para leer eventos

Establece los gestores de señal para SIGINT y SIGTERM

Futures

Funciones Future

Objeto Future

Transportes y protocolos

Transportes

Jerarquía de transportes

Transporte base

Transportes de solo lectura

Transportes de solo escritura

Transportes de datagramas

Transportes de subprocesos

Protocolos

Protocolos base

Protocolo base

Protocolos de streaming

Protocolos de streaming mediante búfer

Protocolos de datagramas

Protocolos de subprocesos

Ejemplos

Servidor de eco TCP

Cliente de eco TCP

Servidor de eco UDP

Cliente de eco UDP

Conectando sockets existentes

loop.subprocess_exec() y SubprocessProtocol

Políticas

Obteniendo y Configurando la Política

Objetos de Política

Observadores de procesos

Personalizar Políticas

Soporte de plataforma

Todas las Plataformas

Windows

Soporte de sub-procesos en Windows

macOS

Índice de API de alto nivel

Tareas

Colas

Subprocesos

Flujos

Sincronización

Excepciones

Índice de API de bajo nivel

Obtención del bucle de eventos

Métodos del bucle de eventos

Transportes

Protocolos

Políticas de bucle de eventos

Desarrollando con asyncio

Modo Depuración

Concurrencia y Multihilo

Ejecutando Código Bloqueante

Logueando

Detectar corrutinas no esperadas

Detectar excepciones nunca recuperadas

socket — interfaz de red de bajo nivel

Familias Socket

Contenido del módulo

Excepciones

Constantes

Funciones

Creación de sockets

Otras funciones

Objetos Socket

Notas sobre los tiempos de espera del socket

Tiempos de espera y el método connect

Tiempos de espera y el método accept

Ejemplo

ssl —Empaquetador o wrapper TLS/SSL para objetos de tipo socket

Funciones, constantes y excepciones

Creación de sockets

Creación de contexto

Excepciones

Generación aleatoria

Gestión de certificados

Constantes

Sockets SSL

Contextos SSL

Certificados

Cadenas de certificados

Certificados CA

Clave y certificado combinados

Certificados auto-firmados

Ejemplos

Pruebas de compatibilidad con SSL

Operación del lado del cliente

Operación del lado del servidor

Notas sobre los sockets no bloqueantes

Soporte de memoria BIO

Sesión SSL

Consideraciones de seguridad

Los mejores valores por defecto

Ajustes manuales

Verificación de certificados

Versiones del protocolo

Selección de cifrado

Multiprocesamiento

TLS 1.3

Soporte LibreSSL

select — Esperando la finalización de E/S

Objetos de sondeo /dev/poll

Objetos de sondeo de Edge y Level Trigger (epoll)

Sondeo de objetos

Objetos Kqueue

Objetos Kevent

selectors — Multiplexación de E/S de alto nivel

Introducción

Clases

Ejemplos

signal — Establece gestores para eventos asíncronos

Reglas generales

Ejecución de los gestores de señales de Python

Señales e hilos

Contenidos del módulo

Ejemplo

Nota sobre SIGPIPE

Note on Signal Handlers and Exceptions

mmap — Soporte de archivos mapeados en memoria

Constantes MADV_*

Manejo de Datos de Internet

email — Un paquete de manejo de correo electrónico y MIME

email.message: Representando un mensaje de correo electrónico

email.parser: Analizar mensajes de correo electrónico

API FeedParser

API Parser

Notas adicionales

email.generator: Generando documentos MIME

email.policy: Objetos Policy

email.errors: Clases de excepción y defecto

email.headerregistry: Objetos de encabezado personalizados

email.contentmanager: Gestión de contenido MIME

Instancias gestoras de contenido

email: Ejemplos

email.message.Message: Representar un mensaje de correo electrónico usando la API compat32

email.mime: Creación de correo electrónico y objetos MIME desde cero

email.header: Cabeceras internacionalizadas

email.charset: Representa conjunto de caracteres

email.encoders: Codificadores

email.utils: Utilidades misceláneas

email.iterators: Iteradores

json — Codificador y decodificador JSON

Uso básico

Codificadores y Decodificadores

Excepciones

Cumplimiento e interoperabilidad estándar

Codificaciones de caracteres

Valores de número infinito y NaN

Nombres repetidos dentro de un objeto

Valores de nivel superior No-Objeto , No-Arreglo

Limitaciones de la implementación

Interfaz de línea de comandos

Opciones de línea de comandos

mailbox — Manipular buzones de correo en varios formatos

Objetos :class:”Mailbox”

Maildir

mbox

MH

Babyl

MMDF

Objetos Message

MaildirMessage

mboxMessage

MHMessage

BabylMessage

MMDFMessage

Excepciones

Ejemplos

mimetypes — Mapea nombres de archivo a tipos MIME

Objetos MimeTypes

base64 — Codificaciones de datos Base16, Base32, Base64, y Base85

binhex — Codificar y decodificar archivos binhex4

Notas

binascii — Convertir entre binario y ASCII

quopri — Codificar y decodificar datos MIME imprimibles entre comillas

Herramientas Para Procesar Formatos de Marcado Estructurado

html — Compatibilidad con el Lenguaje de marcado de hipertexto

html.parser — Analizador simple de HTML y XHTML

Aplicación ejemplo de un analizador sintáctico (parser) de HTML

Métodos HTMLParser

Ejemplos

html.entities — Definiciones de entidades generales HTML

Módulos de procesamiento XML

Vulnerabilidades XML

El paquete defusedxml

xml.etree.ElementTree — La API XML de ElementTree

Tutorial

Árbol y elementos XML

Procesando XML

API de consulta para un procesamiento no bloqueante

Encontrando elementos interesantes

Modificando un archivo XML

Construyendo documentos XML

Procesando XML con espacio de nombres

Soporte de XPath

Ejemplo

Sintaxis XPath soportada

Referencia

Funciones

Soporte de XInclude

Ejemplo

Referencia

Funciones

Objetos Element

Objetos ElementTree

Objetos QName

Objetos TreeBuilder

Objetos XMLParser

Objetos XMLPullParser

Excepciones

xml.dom — El API del Modelo de Objetos del Documento

Contenido del Módulo

Objetos en el DOM

Objetos DOMImplementation

Objetos Nodo

Objetos NodeList

Objetos DocumentType

Objetos Documento

Objetos Elemento

Objetos Atributo

Objetos NamedNodeMap

Objetos Comentario

Objetos Texto y CDATASection

Objetos ProcessingInstruction

Excepciones

Conformidad

Mapeo de tipos

Métodos de acceso (accessor)

xml.dom.minidom — Implementación mínima del DOM

Objetos del DOM

Ejemplo de DOM

minidom y el estándar DOM

xml.dom.pulldom — Soporte para la construcción parcial de árboles DOM

Objetos DOMEventStream

XML.sax— Soporte para analizadores SAX2

Objetos SAXException

xml.sax.handler — Clases base para los handlers SAX

Objetos ContentHandler

Objetos DTDHandler

Objetos EntityResolver

Objetos ErrorHandler

xml.sax.saxutils — Utilidades SAX

xml.sax.xmlreader — Interfaz para analizadores XML

Objetos XMLReader

Objetos IncrementalParser

Objetos localizadores

Objetos InputSource

La Interfaz Attributes

La Interfaz AttributesNS

xml.parsers.expat — Análisis rápido XML usando Expat

Objetos XMLParser

Excepciones de ExpatError

Ejemplo

Descripciones del modelo de contenido

Constantes de error de expansión

Protocolos y soporte de Internet

webbrowser — Cómodo controlador de navegador web

Objetos controladores de navegador

wsgiref — Utilidades WSGI e implementación de referencia

wsgiref.util – Utilidades de entorno WSGI

wsgiref.headers – Herramientas para cabeceras de respuesta WSGI

wsgiref.simple_server– Un servidor HTTP WSGI simple

wsgiref.validate — Verificador de compatibilidad WSGI

wsgiref.handlers – Clases base servidor/gateway

Ejemplos

urllib — URL módulos de manipulación

urllib.request — Biblioteca extensible para abrir URLs

Objetos Request

Objetos OpenerDirector

Objetos BaseHandler

Objetos HTTPRedirectHandler

Objetos HTTPCookieProcessor

Objetos ProxyHandler

Objetos HTTPPasswordMgr

Objetos HTTPPasswordMgrWithPriorAuth

Objetos AbstractBasicAuthHandler

Objetos HTTPBasicAuthHandler

Objetos ProxyBasicAuthHandler

Objetos AbstractDigestAuthHandler

Objetos HTTPDigestAuthHandler

Objetos ProxyDigestAuthHandler

Objetos HTTPHandler

Objetos HTTPSHandler

Objetos FileHandler

Objetos DataHandler

Objetos FTPHandler

Objetos CacheFTPHandler

Objetos UnknownHandler

Objetos HTTPErrorProcessor

Ejemplos

Interfaz heredada

Restricciones urllib.request

urllib.response — Clases de respuesta usadas por urllib

urllib.parse — Analiza URL en componentes

Análisis de URL

URL parsing security

Análisis de bytes codificados ASCII

Resultados del análisis estructurado

Cita de URL

urllib.error — Clases de excepción lanzadas por urllib.request

urllib.robotparser — Analizador para robots.txt

http — Módulos HTTP

Códigos de estado HTTP

http.client — Cliente de protocolo HTTP

Objetos de HTTPConnection

Objetos de HTTPResponse

Ejemplos

Objetos de HTTPMessage

ftplib — cliente de protocolo FTP

Objetos FTP

Objetos FTP_TLS

poplib — Cliente de protocolo POP3

Objetos POP3

Ejemplo POP3

imaplib — Protocolo del cliente IMAP4

Objetos de IMAP4

Ejemplo IMAP4

smtplib — Cliente de protocolo SMTP

Objetos SMTP

Ejemplo SMTP

uuid — objetos UUID según RFC 4122

Ejemplo

socketserver — Un framework para servidores de red

Notas de creación del servidor

Objetos de servidor

Solicitar objetos de controlador

Ejemplos

socketserver.TCPServer Ejemplo

socketserver.UDPServer Ejemplo

Mixins asincrónicos

http.server — Servidores HTTP

Security Considerations

http.cookies — Gestión del estado HTTP

Objetos de cookie

Objetos Morsel

Ejemplo

http.cookiejar — Manejo de cookies para clientes HTTP

Objetos CookieJar y FileCookieJar

Subclases FileCookieJar y co-operación con navegadores web

Objetos CookiePolicy

Objetos DefaultCookiePolicy

Objetos Cookie

Ejemplos

xmlrpc — Módulos XMLRPC para cliente y servidor

xmlrpc.client — acceso cliente XML-RPC

Objetos ServerProxy

Objetos DateTime

Objetos binarios

Objetos Faults

Objetos ProtocolError

Objectos MultiCall

Funciones de Conveniencia

Ejemplo de Uso de Cliente

Ejemplo de Uso de Cliente y Servidor

xmlrpc.server — Servidores básicos XML-RPC

Objetos SimpleXMLRPCServer

Ejemplo de SimpleXMLRPCServer

CGIXMLRPCRequestHandler

Documentando el servidor XMLRPC

Objetos DocXMLRPCServer

DocCGIXMLRPCRequestHandler

ipaddress — Biblioteca de manipulación IPv4/IPv6

Funciones de fábrica de conveniencia

Direcciones IP

Objetos de dirección

Conversión a cadenas de caracteres y enteros

Operadores

Operadores de comparación

Operadores aritméticos

Definiciones de red IP

Prefijo, máscara de red y máscara de host

Objetos de red

Operadores

Operadores lógicos

Iteración

Redes como contenedores de direcciones

Objetos de interfaz

Operadores

Operadores lógicos

Otras funciones a nivel de módulo

Excepciones personalizadas

Servicios Multimedia

wave — Leer y escribir archivos WAV

Los objetos Wave_read

Los objetos Wave_write

colorsys — Conversiones entre sistemas de color

Internacionalización

gettext — Servicios de internacionalización multilingües

GNU API gettext

API basada en clases

La clase NullTranslations

La clase GNUTranslations

Soporte de catálogo de mensajes de Solaris

El constructor del catálogo

Internacionalizando sus programas y módulos

Agregar configuración regional a su módulo

Agregar configuración regional a su aplicación

Cambiar idiomas sobre la marcha

Traducciones diferidas

Agradecimientos

locale — Servicios de internacionalización

Segundo plano, detalles, indicaciones, consejos y advertencias

Para escritores de extensión y programas que incrustan Python

Acceso a los catálogos de mensajes

Frameworks de programa

turtle — Gráficos con Turtle

Introducción

Reseña de los métodos disponibles para Turtle y Screen

Métodos Turtle

Métodos de TurtleScreen/Screen

Métodos de RawTurtle/Turtle Y sus correspondientes funciones

Movimiento de Turtle

Mostrar el estado de la tortuga

Configuración de las medidas

Control del lápiz

Estado de dibujo

Control del color

Relleno

Más controles de dibujo

Estado de la Tortuga

Visibilidad

Apariencia

Usando eventos

Métodos especiales de Turtle

Formas compuestas

Métodos de TurtleScreen/Screen y sus correspondientes funciones

Control de ventana

Control de animación

Usando eventos de pantalla

Métodos de entrada

Configuración y métodos especiales

Métodos específicos de Screen, no heredados de TurtleScreen

Clases públicas

Ayuda y configuración

Cómo usar la ayuda

Traducción de cadenas de documentos a diferentes idiomas

Cómo configurar Screen and Turtles

turtledemo — Scripts de demostración

Cambios desde Python 2.6

Cambios desde Python 3.0

cmd — Soporte para intérpretes orientados a línea de comandos

Objetos Cmd

Ejemplo Cmd

shlex — Análisis léxico simple

objetos shlex

Reglas de análisis

Compatibilidad mejorada con intérprete de comandos

Interfaces gráficas de usuario con Tk

tkinter — Interface de Python para Tcl/Tk

Módulos Tkinter

Guía de supervivencia de Tkinter

Cómo usar esta sección

Un simple programa Hola Mundo

Una (muy) rápida mirada a Tcl/Tk

Mapeo básico de Tk en Tkinter

Cómo se relacionan Tk y Tkinter

Guía práctica

Configuración de opciones

El empaquetador

Opciones del empaquetador

Asociación de variables de widget

El gestor de ventanas

Tipos de datos de opciones Tk

Enlaces y eventos

El parámetro índice

Imágenes

Gestor de archivos

tkinter.colorchooser — Diálogo de elección de color

tkinter.font — Envoltorio de fuente Tkinter

Diálogos Tkinter

tkinter.simpledialog —Diálogos de entrada estándar de Tkinter

Diálogos de selección de archivos

Diálogos nativos de carga/guardado

tkinter.commondialog — Plantillas de ventanas de diálogo

tkinter.messagebox — Indicadores de mensajes de Tkinter

tkinter.scrolledtext — Widget de texto desplazado

tkinter.dnd — Soporte de arrastrar y soltar

tkinter.ttk — Tk widgets temáticos

Uso de Ttk

Ttk widgets

Widget

Opciones estándar

Opciones de widgets desplegables

Opciones de etiqueta

Opciones de compatibilidad

Estados del widget

ttk.Widget

Combobox

Opciones

Eventos virtuales

ttk.Combobox

Spinbox

Opciones

Eventos virtuales

ttk.Spinbox

Notebook

Opciones

Opciones de pestañas

Identificadores de pestañas

Eventos virtuales

ttk.Notebook

Progressbar

Opciones

ttk.Progressbar

Separator

Opciones

Sizegrip

Notas específicas por plataforma

Errores detectados

Treeview

Opciones

Opciones de elementos

Opciones de etiqueta

Identificadores de columna

Eventos virtuales

ttk.Treeview

Ttk Styling

Diseños

tkinter.tix — Ampliación de widgets para Tk

Usando Tix

Widgets de Tix

Widgets Básicos

Selectores de Archivos

ListBox jerárquico

ListBox Tabular

Gestores de Widgets

Tipos de Imágenes

Widgets Varios

Gestor de Geometría de Formulario

Comandos Tix

IDLE

Menús

Menú de archivo (Shell y Editor)

Menú editar (Shell y Editor)

Menú de formato (solo ventana del Editor)

Menú ejecutar (solo ventana Editor)

Menú de shell (solo ventana de shell)

Menú de depuración (solo ventana de shell)

Menú de opciones (Shell y editor)

Menú de ventana (shell y editor)

Menú de ayuda (shell y editor)

Menús contextuales

Edición y navegación

Ventana del editor

Atajos de teclado

Indentación automática

Terminaciones

Sugerencias de llamada

Contexto del código

Shell de Python

Colores del texto

Inicio y ejecución de código

Uso de línea de comando

Error de inicio

Ejecutando código del usuario

Salida del usuario en consola

Desarrollando aplicaciones tkinter

Ejecutando sin un subproceso

Ayuda y preferencias

Recursos de ayuda

Preferencias de configuración

IDLE en macOS

Extensiones

Herramientas de desarrollo

typing — Soporte para type hints

Relevant PEPs

Alias de tipo

NewType

Callable

Genéricos

Tipos genéricos definidos por el usuario

El tipo Any

Subtipado nominal vs estructural

Contenido del módulo

Primitivos especiales de tipado

Tipos especiales

Formas especiales

Tipos de construcción de genéricos

Otras directivas especiales

Colecciones genéricas concretas

Correspondientes a tipos integrados

Correspondiente a tipos en collections

Otros tipos concretos

Clase base abstracta para tipos genéricos

Correspondientes a las colecciones en collections.abc

Correspondiente a otros tipos en collections.abc

Programación asíncrona

Tipos del administrador de contextos

Protocolos

Funciones y decoradores

Ayudas de introspección

Constantes

pydoc — Generador de documentación y Sistema de ayuda en línea

Modo de desarrollo de Python

Efectos del modo de desarrollo de Python

Ejemplo de ResourceWarning

Ejemplo de error de descriptor de archivo incorrecto

doctest – Prueba ejemplos interactivos de Python

Uso simple: verificar ejemplos en docstrings

Uso Simple: Verificar ejemplos en un Archivo de Texto

Cómo funciona

¿Qué docstrings son examinados?

¿Cómo se reconocen los ejemplos de docstring?

¿Cuál es el contexto de ejecución?

¿Y las excepciones?

Banderas de Opción

Directivas

Advertencias

API básica

API de unittest

API avanzada

Objetos DocTest

Objetos Example

Objetos DocTestFinder

Objetos DocTestParser

Objetos DocTestRunner

Objetos OutputChecker

Depuración

Plataforma improvisada

unittest — Infraestructura de tests unitarios

Ejemplo sencillo

Interfaz de línea de comandos

Opciones de la línea de órdenes

Descubrimiento de pruebas

Organización del código de pruebas

Reutilización de código de prueba anterior

Omitir tests y fallos esperados

Distinguiendo iteraciones de tests empleando subtests

Clases y funciones

Casos de test

Alias obsoletos

Agrupando tests

Cargando y ejecutando tests

load_tests protocolo

Instalaciones para clases y módulos

setUpClass y tearDownClass

setUpModule y tearDownModule

Manejo de señales

unittest.mock — Biblioteca de objetos simulados

Guía rápida

La clase Mock

Llamar a los objetos simulados

Eliminar atributos

Los nombres de los objetos simulados y el atributo name

Adjuntar objetos simulados como atributos

Parcheadores

patch

patch.object

patch.dict

patch.multiple

Métodos start y stop de patch

Parchear objetos incorporados (builtins)

TEST_PREFIX

Anidando decoradores patch

Dónde parchear

Parcheando descriptores y objetos proxy

MagicMock y el soporte de métodos mágicos

Simular métodos mágicos

Magic Mock

Ayudantes

sentinel

DEFAULT

call

create_autospec

ANY

FILTER_DIR

mock_open

Autoespecificación

Sellar objetos simulados

unittest.mock — primeros pasos

Usando Mock

Métodos de parcheo Mock

Mock de llamadas a métodos sobre un objeto

Clases Mocking

Nombrando tus mocks

Siguiendo todas las llamadas

Establecer valores de retorno y atributos

Generar excepciones con mocks

Funciones de efectos secundarios e iterables

Iteradores asincrónicos de Mocking

El gestor de contexto asincrónico de Mocking

Creando un mock desde un objeto existente

Decoradores de Parches

Otros Ejemplos

Mocking de llamadas encadenadas

Mocking parcial

Mocking de un Método Generador

Aplicar el mismo parche a cada método de prueba

Mocking de métodos sin enlazar

Comprobación de varias llamadas con mock

Copiando con argumentos mutables

Anidando Parches

Mocking a un diccionario usando MagickMock

Mock de subclases y sus atributos

Importaciones de Mocking con patch.dict

Seguimiento del orden de las llamadas y de las aserciones de llamadas menos detalladas

Coincidencia de argumentos más compleja

2to3 - Traducción de código Python 2 a 3

Usando 2to3

Fixers

lib2to3 - librería 2to3

test — Paquete de pruebas de regresión para Python

Escritura de pruebas unitarias para el paquete test

Ejecución de pruebas utilizando la interfaz de línea de comandos

test.support — Utilidades para el conjunto de pruebas de Python

test.support.socket_helper — Utilidades para pruebas de socket

test.support.script_helper —Utilidades para las pruebas de ejecución de Python

test.support.bytecode_helper — Herramientas de apoyo para comprobar la correcta generación de bytecode

Depuración y perfilado

Tabla de auditoría de eventos

bdb — Framework de depuración

faulthandler — Volcar el rastreo de Python

Volcar el rastreo

Estado del gestor de fallos

Volcar los rastreos después de un tiempo de espera

Volcar el rastreo en una señal del usuario

Problema con descriptores de archivo

Ejemplo

pdb — El Depurador de Python

Comandos del depurador

Los perfiladores de Python

Introducción a los perfiladores

Manual instantáneo de usuario

Referencia del módulo profile y cProfile

La clase Stats

¿Qué es el perfil determinista?

Limitaciones

Calibración

Usando un temporizador personalizado

timeit — Mide el tiempo de ejecución de pequeños fragmentos de código

Ejemplos básicos

Interfaz de Python

Interfaz de línea de comandos

Ejemplos

trace — Rastrear la ejecución de la declaración de Python

Uso de la línea de comandos

Opciones principales

Modificadores

Filtros

Interfaz programática

tracemalloc— Rastrea la asignación de memoria

Ejemplos

Mostrar los 10 principales

Calcula las diferencias

Consigue el seguimiento del bloque de memoria

Los 10 más bonitos

Graba los tamaños actual y máximo de todos los bloques de memoria rastreados

API

Funciones

Filtro de dominio

Filtro

Cuadro

Captura instantánea

Estadística

StatisticDiff

Rastro

Seguimiento

Empaquetado y distribución de software

distutils — Creación e instalación de módulos Python

ensurepip — Ejecutando el instalador pip

Interfaz de línea de comandos

API del módulo

venv — Creación de entornos virtuales

Creación de entornos virtuales

API

Un ejemplo de la extensión de EnvBuilder

zipapp — Gestiona archivadores zip ejecutables de Python

Ejemplo básico

Interfaz de línea de comando

API de Python

Ejemplos

Especificar el intérprete

Creando aplicaciones independientes con zipapp

Hacer un ejecutable para Windows

Advertencias

El formato de archivado Zip de aplicaciones Python

Servicios en tiempo de ejecución de Python

sys — Parámetros y funciones específicos del sistema

sysconfig — Proporciona acceso a la información de configuración de Python

Variables de configuración

Rutas de instalación

Otras funciones

Usando sysconfig como un script

builtins — Objetos incorporados

__main__ — Entorno de script del nivel superior

warnings — Control de advertencias

Categorías de advertencia

El filtro de advertencias

Descripción de los filtros de advertencia

Filtro de advertencia predeterminado

Anulando el filtro por defecto

Eliminación temporal de las advertencias

Advertencias de prueba

Actualización del código para las nuevas versiones de las dependencias

Funciones Disponibles

Gestores de Contexto disponibles

dataclasses — Clases de datos

Decoradores, clases y funciones del módulo

Procesamiento posterior a la inicialización

Variables de clase

Variable de solo inicialización

Instancias congeladas

Herencia

Funciones fábrica por defecto

Valores por defecto mutables

Excepciones

contextlib — Utilidades para declaraciones de contexto with

Utilidades

Ejemplos y recetas

Apoyando un número variable de gestores de contexto

Capturando excepciones de los métodos __enter__

Limpieza en una implementación __enter__

Reemplazar cualquier uso de try-finally y marcar variables

Usar un gestor de contexto como decorador de funciones

Gestores de contexto de uso único, reutilizables y reentrantes

Gestores contextuales reentrantes

Gestores contextuales reutilizables

abc — Clases de Base Abstracta

atexit — Gestores de Salida

Ejemplo con atexit

traceback — Imprimir o recuperar un seguimiento de pila

Objetos TracebackException

Objetos StackSummary

Objetos FrameSummary

Ejemplos de seguimiento de pila

__future__ — Definiciones de declaraciones futuras

gc — Interfaz del recolector de basura

inspect — Inspeccionar objetos vivos

Tipos y miembros

Recuperar el código fuente

Introspección de los invocables con el objeto Signature

Clases y funciones

La pila del interprete

Obteniendo atributos estáticamente

Estado actual de los Generadores y las Corutinas

Objetos de código Bit Flags

Interfaz de la línea de comando

site — Enlace (hook) de configuración específico del sitio

Configuración de Readline

Contenido del módulo

Interfaz de línea de comando

Intérpretes de Python personalizados

code — Clases básicas de intérpretes

Objetos de intérprete interactivo

Objetos de consola interactiva

codeop — Compila código Python

Importando módulos

zipimport — Importar módulos desde archivos zip

Objetos zipimporter

Ejemplos

pkgutil — Utilidad de extensión de paquete

modulefinder — Buscar módulos usados por un script

Ejemplo de uso de ModuleFinder

runpy — Localización y ejecución de módulos Python

importlib — La implementación de import

Introducción

Funciones

importlib.abc – Clases base abstractas relacionadas con la importación

importlib.resources – Recursos

importlib.machinery – Importadores y enlaces de ruta

importlib.util – Código de utilidad para importadores

Ejemplos

Importar programáticamente

Comprobando si se puede importar un módulo

Importar un archivo fuente directamente

Configurar un importador

Aproximando importlib.import_module()

Usando importlib.metadata

Descripción general

API funcional

Puntos de entrada

Metadatos de distribución

Versiones de distribución

Archivos de distribución

Requerimientos de la distribución

Distribuciones

Extendiendo el algoritmo de búsqueda

Servicios del lenguaje Python

parser — Acceder a árboles de análisis sintáctico de Python

Crear objetos ST

Convertir objetos ST

Consultas en objetos ST

Manejo de errores y excepciones

Objetos ST

Ejemplo: Emulación de compile()

ast — Árboles de sintaxis abstracta

Gramática abstracta

Clases Nodo

Literals

Variables

Expressions

Subscripting

Comprehensions

Statements

Imports

Control flow

Function and class definitions

Async and await

Ayudantes de ast

Compiler Flags

Command-Line Usage

symtable — Acceso a la tabla de símbolos del compilador

Generando tablas de símbolos

Examinando la tabla de símbolos

symbol — Constantes utilizadas con árboles de análisis de Python

token— Constantes usadas con árboles de sintaxis de Python

keyword — Pruebas para palabras clave en Python

tokenize — Conversor a tokens para código Python

Convirtiendo la entrada en tokens

Uso como línea de comandos

Ejemplos

tabnanny — Detección de indentación ambigua

pyclbr — Soporte para navegador de módulos Python

Objetos Function

Objetos Class

py_compile` — Compila archivos fuente Python

compileall — Bibliotecas de Python de compilación de bytes

Uso de la línea de comandos

Funciones públicas

dis — Desensamblador para bytecode de Python

Análisis de bytecode

Funciones de análisis

Instrucciones bytecode de Python

Colecciones opcode

pickletools — Herramientas para desarrolladores pickle

Uso de la línea de comandos

Opciones de línea de comandos

Interfaz programática

Servicios varios

formatter — Formateo de salida genérica

La interfaz Formateador

Implementaciones del formateador

La interfaz Escritor

Implementaciones del escritor

Servicios Específicos para MS Windows

msvcrt — Rutinas útiles del entorno de ejecución MS VC++

Operaciones con archivos

Consola E/S

Otras funciones

winreg — Acceso al registro de Windows

Funciones

Constantes

HKEY_* Constantes

Access Rights

Específico de 64 bits

Tipos de valor

Objetos de control del registro

:mod:”winsound” — Interfaz de reproducción de sonido para Windows

Servicios específicos de Unix

posix — Las llamadas más comunes al sistema POSIX

Soporte de archivos grandes

Contenido notable del módulo

pwd — La base de datos de contraseñas

grp — La base de datos de grupo

termios —Control tty estilo POSIX

Ejemplo

tty — Funciones de control de terminal

pty — Utilidades para Pseudo-terminal

Ejemplo

fcntl — Las llamadas a sistema fcntl y ioctl

resource — Información sobre el uso de recursos

Límites de recursos

Utilización de recursos

syslog — Rutinas de la biblioteca syslog de Unix

Ejemplos

Ejemplo sencillo

Módulos Reemplazados

aifc — Lee y escribe archivos AIFF y AIFC

asynchat — Gestor de comandos/respuestas en sockets asíncronos

Ejemplo de asynchat

asyncore — controlador de socket asincrónico

Ejemplo asyncore de cliente HTTP básico

Ejemplo asyncore de servidor de eco básico

audioop — Manipula datos de audio sin procesar

cgi — Soporte de Interfaz de Entrada Común (CGI)

Introducción

Usando el módulo CGI

Interfaz de Nivel Superior

Funciones

Preocuparse por la seguridad

Instalando su script de CGI en un sistema Unix

Probando su script de CGI

Depurando scripts de CGI

Problemas comunes y soluciones

cgitb — Administrador traceback para scripts CGI.

chunk — Lee los datos de los trozos de IFF

crypt — Función para verificar contraseñas Unix

Métodos de hashing

Atributos del módulo

Funciones del módulo

Ejemplos

:mod:”imghdr” — Determinar el tipo de imagen

imp — Acceda a import internamente

Ejemplos

mailcap — Manejo de archivos Mailcap

msilib — Leer y escribir archivos Microsoft Installer

Objetos Database

Objetos View

Objetos Summary Information

Objetos Record

Errores

Objetos CAB

Objetos Directory

Features

Clases GUI

Tablas pre-calculadas

nis — Interfaz a Sun’s NIS (Páginas amarillas)

nntplib — Protocolo de cliente NNTP

Objetos NNTP

Atributos

Métodos

Funciones de utilidad

optparse — Analizador sintáctico (parser) para opciones de línea de comandos

Contexto

Terminología

¿Qué finalidad tienen las opciones?

¿Qué finalidad tienen los argumentos posicionales?

Tutorial

Comprendiendo las acciones de opción

La acción store

Manejo de opciones booleanas (flags)

Otras acciones

Valores por defecto

Generando ayuda

Agrupando opciones

Imprimir una cadena de caracteres con la versión del programa

Cómo maneja los errores el módulo optparse

Reuniendo todas las piezas

Guía de referencia

Creando el analizador sintáctico (parser)

Completando el analizador con opciones

Definiendo las opciones

Atributos de opción

Acciones de opción estándares

Tipos de opción estándares

Analizando los argumentos

Consultar y manipular el analizador de opciones

Conflictos entre opciones

Limpieza

Otros métodos

Retrollamadas de opción

Definición de una opción con retrollamada

Cómo son invocadas las retrollamadas

Lanzando errores en una retrollamada

Ejemplo de retrollamada 1: una retrollamada trivial

Ejemplo de retrollamada 2: comprobar el orden de las opciones

Ejemplo de retrollamada 3: comprobar el orden de las opciones (generalizado)

Ejemplo de retrollamada 4: comprobar una condición arbitraria

Ejemplo de retrollamada 5: argumentos fijos

Ejemplo de retrollamada 6: argumentos variables

Extendiendo el módulo optparse

Agregando nuevos tipos

Agregando nuevas acciones

ossaudiodev — Acceso a dispositivos de audio compatibles con OSS

Objetos de dispositivo de audio

Objetos del dispositivo mezclador

pipes — Interfaz para tuberías de shell

Objetos Template

smtpd — Servidor SMTP

Objetos SMTPServer

Objetos DebuggingServer

Objetos PureProxy

Objetos MailmanProxy

Objetos SMTPChannel

sndhdr — Determinar el tipo de archivo de sonido

spwd — La base de datos de contraseñas ocultas

sunau — Lectura y escritura de ficheros Sun AU

Objetos AU_read

Objetos AU_write

telnetlib — cliente Telnet

Objetos Telnet

Ejemplo de Telnet

uu — Codifica y decodifica archivos UUEncode

xdrlib — Codificar y decodificar datos XDR

Instancias de la clase Packer

Instancias de la clase Unpacker

Excepciones

Security Considerations

Ampliación e incrustación del intérprete de Python

Herramientas de terceros recomendadas

Crear extensiones sin herramientas de terceros

1. Extendiendo Python con C o C++

1.1. Un ejemplo simple

1.2. Intermezzo: errores y excepciones

1.3. De vuelta al ejemplo

1.4. La tabla de métodos del módulo y la función de inicialización

1.5. Compilación y Enlazamiento

1.6. Llamando funciones Python desde C

1.7. Extracción de parámetros en funciones de extensión

1.8. Parámetros de palabras clave para funciones de extensión

1.9. Construyendo Valores Arbitrarios

1.10. Conteo de Referencias

1.10.1. Conteo de Referencias en Python

1.10.2. Reglas de Propiedad

1.10.3. Hielo delgado

1.10.4. Punteros NULL

1.11. Escribiendo Extensiones en C++

1.12. Proporcionar una API C para un módulo de extensión

2. Definición de tipos de extensión: Tutorial

2.1. Lo Básico

2.2. Agregar datos y métodos al ejemplo básico

2.3. Proporcionar un control más preciso sobre los atributos de datos

2.4. Apoyo a la recolección de basura cíclica

2.5. Subclases de otros tipos

3. Definición de tipos de extensión: temas variados

3.1. Finalización y desasignación

3.2. Presentación de Objetos

3.3. Gestión de atributos

3.3.1. Gestión de atributos genéricos

3.3.2. Gestión de atributos específicos de tipo

3.4. Comparación de Objetos

3.5. Soporte de protocolo abstracto

3.6. Soporte de referencia débil

3.7. Más Sugerencias

4. Construyendo Extensiones C y C++

4.1. Construyendo Extensiones C y C++ con distutils

4.2. Distribuyendo sus módulos de extensión

5. Creación de extensiones C y C++ en Windows

5.1. Un enfoque de libro de cocina

5.2. Diferencias entre Unix y Windows

5.3. Usar DLL en la práctica

Incrustar el tiempo de ejecución de CPython en una aplicación más grande

1. Incrustando Python en Otra Aplicación

1.1. Incrustación de muy alto nivel

1.2. Más allá de la incrustación de muy alto nivel: una visión general

1.3. Incrustación pura

1.4. Extendiendo Python Incrustado

1.5. Incrustando Python en C++

1.6. Compilar y enlazar bajo sistemas tipo Unix

Manual de referencia de la API en C de Python

Introducción

Estándares de codificación

Archivos de cabecera (Include)

Macros útiles

Objetos, tipos y conteos de referencias

Conteo de Referencias

Detalles del conteo de referencia

Tipos

Excepciones

Integración de Python

Depuración de compilaciones

Interfaz binaria de aplicación estable

La capa de muy alto nivel

Conteo de referencias

Manejo de excepciones

Impresión y limpieza

Lanzando excepciones

Emitir advertencias

Consultando el indicador de error

Manejo de señal

Clases de Excepción

Objetos Excepción

Objectos Unicode de Excepción

Control de Recursión

Excepciones Estándar

Categorías de advertencia estándar

Utilidades

Utilidades del sistema operativo

Funciones del Sistema

Control de procesos

Importando Módulos

Soporte de empaquetado (marshalling) de datos

Analizando argumentos y construyendo valores

Analizando argumentos

Cadena de caracteres y búferes

Números

Otros objetos

Funciones API

Construyendo valores

Conversión y formato de cadenas de caracteres

Reflexión

Registro de códec y funciones de soporte

API de búsqueda de códec

API de registro para controladores de errores de codificación Unicode

Capa de objetos abstractos

Protocolo de objeto

Protocolo de llamada

El protocolo tp_call

El protocolo vectorcall

Control de recursión

API de soporte para vectorcall

API para invocar objetos

API de soporte de llamadas

Protocolo de números

Protocolo de secuencia

Protocolo de mapeo

Protocolo iterador

Protocolo Búfer

Estructura de búfer

Tipos de solicitud búfer

campos independientes de solicitud

formato de sólo lectura

formas, strides, suboffsets

solicitudes de contigüidad

solicitudes compuestas

Arreglos complejos

Estilo NumPy: forma y strides

Estilo PIL: forma, strides y suboffsets

Funciones relacionadas a búfer

Protocolo de búfer antiguo

Capa de objetos concretos

Objetos fundamentales

Objetos Tipos

Crear tipos asignados en montículo (heap)

El objeto None

Objetos numéricos

Objetos Enteros

Objetos Booleanos

Objetos de punto flotante

Objetos de números complejos

Números complejos como estructuras C

Números complejos como objetos de Python

Objetos de secuencia

Objetos Bytes

Objetos de arreglos de bytes (bytearrays)

Macros de verificación de tipos

Funciones API directas

Macros

Objetos y códecs Unicode

Objetos Unicode

Tipo Unicode

Propiedades de caracteres Unicode

Creando y accediendo a cadenas de caracteres Unicode

APIs de Py_UNICODE deprecadas

Codificación regional

Codificación del sistema de archivos

soporte wchar_t

Códecs incorporados

Códecs genéricos

Códecs UTF-8

Códecs UTF-32

Códecs UTF-16

Códecs UTF-7

Códecs Unicode escapado

Códecs para Unicode escapado en bruto

Códecs Latin-1

Códecs ASCII

Códecs de mapa de caracteres

Códecs MBCS para Windows

Métodos & Ranuras (Slots)

Métodos y funciones de ranura (Slot)

Objetos Tuplas

Objetos de secuencia de estructura

Objetos lista

Objetos contenedor

Objetos Diccionarios

Objetos Conjunto

Objetos de función

Objetos función

Objetos de método de instancia

Objetos método

Objetos Celda

Objetos Código

Otros objetos

Objetos archivo

Objectos Modulo

Inicializando módulos en C

Inicialización monofásica

Inicialización multifase

Funciones de creación de módulos de bajo nivel

Funciones de soporte

Búsqueda de módulos

Objetos iteradores

Objetos descriptores

Objeto rebanada (slice)

Objeto Elipsis

Objetos de vista de memoria (MemoryView)

Objetos de referencia débil

Cápsulas

Objetos Generadores

Objetos corrutina

Objetos de variables de contexto

Objetos DateTime

Objects for Type Hinting

Inicialización, Finalización e Hilos

Antes de la inicialización de Python

Variables de configuración global

Inicializando y finalizando el intérprete

Parámetros de todo el proceso

Estado del hilo y el bloqueo global del intérprete

Liberando el GIL del código de extensión

Hilos creados sin Python

Precauciones sobre fork()

API de alto nivel

API de bajo nivel

Soporte de subinterprete

Errores y advertencias

Notificaciones asincrónicas

Perfilado y Rastreo

Soporte avanzado del depurador

Soporte de almacenamiento local de hilo

API de almacenamiento específico de hilo (TSS, Thread Specific Storage)

Asignación dinámica

Métodos

API de almacenamiento local de hilos (TLS, Thread Local Storage)

Configuración de inicialización de Python

PyWideStringList

PyStatus

PyPreConfig

Preinicialización con PyPreConfig

PyConfig

Inicialización con PyConfig

Configuración aislada

Configuración de Python

Configuración de ruta

Py_RunMain()

Py_GetArgcArgv()

API Provisional Privada de Inicialización Multifásica

Gestión de la memoria

Visión general

Interfaz de memoria sin procesar

Interfaz de memoria

Asignadores de objetos

Asignadores de memoria predeterminados

Personalizar asignadores de memoria

El asignador pymalloc

Personalizar asignador de arena de pymalloc

tracemalloc C API

Ejemplos

Soporte de implementación de objetos

Asignación de objetos en el montículo

Estructuras de objetos comunes

Tipos objeto base y macros

Implementando funciones y métodos

Acceder a atributos de tipos de extensión

Objetos Tipo

Referencia rápida

«ranuras tp» (tp slots)

sub-ranuras (sub-slots)

ranura de typedefs

Definición de PyTypeObject

Ranuras (Slots) PyObject

Ranuras PyVarObject

Ranuras PyTypeObject

Tipos Montículos (Heap Types)

Estructuras de Objetos de Números

Estructuras de Objetos Mapeo

Estructuras de objetos secuencia

Estructuras de Objetos Búfer

Estructuras de objetos asíncronos

Tipo Ranura typedefs

Ejemplos

Apoyo a la recolección de basura cíclica

Versiones de API y ABI

Distribuir módulos de Python

Términos clave

Licencias de código abierto y colaboración

Instalando las herramientas

Leyendo la «Python Packaging User Guide»

Cómo puedo…?

… elegir un nombre para mi proyecto?

… crear y distribuir extensiones binarias?

Instalando módulos de Python

Palabras clave

Uso básico

¿Cómo…

… instalo pip en versiones de Python anteriores a Python 3.4?

… instalo paquetes solamente para el usuario actual?

… instalo paquetes científicos de Python?

… trabajo con múltiples versiones de Python instaladas en paralelo?

Problemas de instalación comunes

Instalando en el Python del sistema bajo Linux

Pip no está instalado

Instalando extensiones binarias

Comos (HOWTOs) de Python

Portando código de Python 2 a Python 3

La breve explicación

Detalles

Compatibilidad con Python 2.6 y versiones anteriores

Asegúrese de especificar el soporte de versión adecuado en su archivo setup.py

Tener una buena cobertura de prueba

Aprende las diferencias entre Python 2 & 3

Actualiza tu código

División

Texto frente a datos binarios

Utilice la detección de funciones en lugar de la detección de versiones

Evitar regresiones de compatibilidad

Compruebe qué dependencias bloquean la transición

Actualice su archivo setup.py para denotar compatibilidad con Python 3

Utilice la integración continua para seguir siendo compatible

Considere la posibilidad de usar la comprobación de tipos estáticos opcionales

Portar módulos de extensión a Python 3

Programación de Curses con Python

Qué es curses?

El módulo curses de Python

Iniciar y finalizar una aplicación de curses

Ventanas y pads

Mostrando el texto

Atributos y color

Input del usuario

Para más información

Guía práctica de uso de los descriptores

Guía introductoria

Ejemplo simple: un descriptor que retorna una constante

Búsquedas dinámicas

Atributos gestionados

Nombres personalizados

Pensamientos finales

Ejemplo completo práctico

Clase validadora

Validadores personalizados

Aplicación práctica

Tutorial técnico

Resumen

Definición e introducción

Protocolo de descriptores

Visión general de invocación de descriptores

Invocación desde una instancia

Invocación desde una clase

Invocación desde super

Resumen de la lógica de invocación

Notificación automática de nombre

Ejemplo de mapeos objeto-relacional (ORM)

Equivalentes en Python puro

Propiedades

Funciones y métodos

Kinds of methods

Métodos estáticos

Métodos de clase

Objetos miembros y __slots__

HOWTO - Programación funcional

Introducción

Demostrabilidad formal

Modularidad

Facilidad de depurar y probar

Componibilidad

Iteradores

Tipos de datos que soportan iteradores

Expresiones generadoras y listas por comprensión

Generadores

Pasar valores a un generador

Funciones incorporadas

El módulo itertools

Crear nuevos iteradores

Aplicar funciones a los elementos

Seleccionar elementos

Funciones combinatorias

Agrupar elementos

El módulo functools

El módulo operator

Funciones pequeñas y la expresión lambda

Historia de revisiones y reconocimientos

Referencias

Generales

Específicas de Python

Documentación de Python

HOWTO Hacer Registros (Logging)

Tutorial Básico de Logging

Cuándo usar logging

Un simple ejemplo

Logging a un archivo

Logging de múltiples módulos

Registrar datos de variables

Cambiar el formato de los mensajes mostrados

Visualización de la fecha/hora en los mensajes

Próximos pasos

Tutorial de registro avanzado

Flujo de Registro

Registradores

Gestores

Formateadores

Configuración del registro

¿Qué pasa si no se proporciona ninguna configuración

Configurando Logging para una biblioteca

Niveles de registro

Niveles personalizados

Gestores útiles

Excepciones lanzadas durante logging

Usando objetos arbitrarios como mensajes

Optimización

Libro de recetas de Logging

Usar logging en múltiples módulos

Logging desde múltiples hilos

Múltiples gestores y formateadores

Logging en múltiples destinos

Ejemplo de servidor de configuración

Tratar con gestores que bloquean

Enviar y recibir eventos logging a través de una red

Running a logging socket listener in production

Agregar información contextual a su salida de logging

Uso de LoggerAdapters para impartir información contextual

Usar objetos distintos a los diccionarios para transmitir información contextual

Usar filtros para impartir información contextual

Logging a un sólo archivo desde múltiples procesos

Usando concurrent.futures.ProcessPoolExecutor

Deploying Web applications using Gunicorn and uWSGI

Usando rotación de archivos

Uso de estilos de formato alternativos

Personalización de LogRecord

Subclasificación QueueHandler - un ejemplo de ZeroMQ

Subclasificación QueueListener - un ejemplo de ZeroMQ

Una configuración de ejemplo basada en diccionario

Usar un rotador y un nombre para personalizar el procesamiento de rotación de log

Un ejemplo de multiprocesamiento más elaborado

Insertar BOM en mensajes enviados a SysLogHandler

Implementar logging estructurado

Personalización de gestores con dictConfig()

Usar estilos de formato particulares en toda su aplicación

Uso de fábricas de LogRecord

Usar objetos de mensaje personalizados

Configurar filtros con dictConfig()

Formato de excepción personalizado

Mensajes de logging hablantes

Almacenamiento en búfer de mensajes de logging y su salida condicional

Formateo de horas usando UTC (GMT) a través de la configuración

Usar un administrador de contexto para logging selectivo

Una plantilla de inicio de aplicación CLI

Una GUI de Qt para logging

Patterns to avoid

Opening the same log file multiple times

Using loggers as attributes in a class or passing them as parameters

Adding handlers other than NullHandler to a logger in a library

Creating a lot of loggers

Expresiones regulares COMOS (HOWTO)

Introducción

Patrones simples

Coincidencia de Caracteres (Matching Characters)

Repitiendo cosas

Usando Expresiones Regulares

Compilando Expresiones regulares

La plaga de la barra invertida (The Backslash Plague)

Realizando coincidencias

Funciones a nivel de módulo

Los Flags de compilación

Más poder de patrones

Más metacarácteres

Agrupando

Grupos con nombre y sin captura

Aserciones Anticipadas

Modificando cadenas de caracteres

Separando cadenas de caracteres

Búsqueda y Remplazo

Problemas comunes

Uso de métodos de cadenas de caracteres

match() versus search()

Codiciosa versus no codiciosa (Greedy versus Non-Greedy)

Usando re.VERBOSE

Feedback

HOW TO - Programación con sockets

Sockets

Historia

Creando un socket

IPC

Usando un socket

Datos binarios

Desconectando

Cuando los sockets mueren

Sockets no bloqueantes

HOW TO - Ordenar

Conceptos básicos de ordenación

Funciones clave

Funciones del módulo operator

Ascendente y descendente

Estabilidad de ordenamiento y ordenamientos complejos

El método tradicional utilizando Decorate-Sort-Undecorate

El método tradicional utilizando el Parámetro cmp

Comentarios finales

CÓMO (HOWTO) Unicode

Introducción a Unicode

Definiciones

Codificaciones

Referencias

Soporte Unicode de Python

El tipo cadena

Convirtiendo a Bytes

Literales Unicode en código fuente Python

Propiedades Unicode

Comparando cadenas

Expresiones Regulares Unicode

Referencias

Leyendo y escribiendo datos Unicode

Nombres de archivos Unicode

Consejos para escribir programas compatibles con Unicode

Conversión entre codificaciones de archivo

Archivos en una codificación desconocida

Referencias

Agradecimientos

HOWTO - Cómo obtener recursos de Internet con el paquete urllib

Introducción

Obtención de URLs

Datos

Encabezados (Headers)

Gestión de excepciones

URLError

HTTPError

Códigos de Error

Resumiéndolo

Número 1

Número 2

info y geturl

Objetos de Apertura (Openers) y Gestores (Handlers)

Autenticación Básica

Proxies

Sockets y Capas

Notas a pie de página

Tutorial de Argparse

Conceptos

Las bases

Introducción a los argumentos posicionales

Introducción a los argumentos opcionales

Opciones cortas

Combinar argumentos opcionales y posicionales

Un poco mas avanzado

Opciones conflictivas

Conclusión

Introducción al modulo ipaddress

Creando objetos Dirección/Red/Interfaz (Address/Network/Interface)

Nota sobre versiones IP

Direcciones IP del Host

Definiendo Redes

Interfaces de Host

Inspeccionando objetos Dirección/Red/Interfaz (Address/Network/Interface)

Redes como listas de direcciones

Comparaciones

Uso de direcciones IP con otros módulos

Obtener más detalles cuando se produce un error en la creación de instancias

How-To Argument Clinic

Los objetivos del Argument Clinic

Conceptos básicos y uso

Convirtiendo su primera función

Temas avanzados

Valores predeterminados simbólicos

Cambiar el nombre de las funciones y variables C generadas por Argument Clinic

Convirtiendo funciones usando PyArg_UnpackTuple

Grupos opcionales

Usar convertidores de Argument Clinic reales, en lugar de «convertidores heredados»

Py_buffer

Convertidores avanzados

Valores predeterminados de los parámetros

El valor predeterminado NULL

Expresiones especificadas como valores por defecto

Usando un convertidor de retorno

Clonando funciones existentes

Llamando código Python

Usando un «auto convertidor»

Escribiendo un convertidor personalizado

Escribiendo un convertidor de retorno personalizado

METH_O y METH_NOARGS

funciones tp_new y tp_init

Cambiar y redirigir la salida de Clinic

El truco #ifdef

Usando Argument Clinic en archivos Python

Instrumentación de CPython con DTrace y SystemTap

Habilitando los marcadores estáticos

Sondas estáticas DTrace

Marcadores estáticos SystemTap

Marcadores estáticos disponibles

SystemTap Tapsets

Ejemplos

Preguntas más frecuentes de Python

Preguntas frecuentes generales sobre Python

Información General

Python en el mundo real

Preguntas frecuentes de programación

Preguntas generales

Núcleo del lenguaje

Números y cadenas

Rendimiento

Secuencias (Tuplas/Listas)

Objetos

Módulos

Preguntas frecuentes sobre diseño e historia

¿Por qué Python usa indentación para agrupar declaraciones?

¿Por qué obtengo resultados extraños con operaciones aritméticas simples?

¿Por qué los cálculos de punto flotante son tan inexactos?

¿Por qué las cadenas de caracteres de Python son inmutables?

¿Por qué debe usarse “self” explícitamente en las definiciones y llamadas de métodos?

¿Por qué no puedo usar una tarea en una expresión?

¿Por qué Python usa métodos para alguna funcionalidad (por ejemplo, list.index()) pero funciones para otra (por ejemplo, len(list))?

¿Por qué join() es un método de cadena de caracteres en lugar de un método de lista o tupla?

¿Qué tan rápido van las excepciones?

¿Por qué no hay un switch o una declaración case en Python?

¿No puede emular hilos en el intérprete en lugar de confiar en una implementación de hilos específica del sistema operativo?

¿Por qué las expresiones lambda no pueden contener sentencias?

¿Se puede compilar Python en código máquina, C o algún otro lenguaje?

¿Cómo gestiona Python la memoria?

¿Por qué CPython no utiliza un esquema de recolección de basura más tradicional?

¿Por qué no se libera toda la memoria cuando sale CPython?

¿Por qué hay tipos de datos separados de tuplas y listas?

¿Cómo se implementan las listas en Python?

¿Cómo se implementan los diccionarios en CPython?

¿Por qué las claves del diccionario deben ser inmutables?

¿Por qué list.sort() no retorna la lista ordenada?

¿Cómo se especifica y aplica una especificación de interfaz en Python?

¿Por qué no hay goto?

¿Por qué las cadenas de caracteres sin formato (r-strings) no pueden terminar con una barra diagonal inversa?

¿Por qué Python no tiene una declaración «with» para las asignaciones de atributos?

Why don’t generators support the with statement?

¿Por qué se requieren dos puntos para las declaraciones if/while/def/class?

¿Por qué Python permite comas al final de las listas y tuplas?

Preguntas frecuentes sobre bibliotecas y extensiones

Cuestiones generales sobre bibliotecas

Tareas comunes

Hilos

Entrada y Salida

Programación de Redes/Internet

Bases de datos

Matemáticas y Numérica

Extendiendo/Embebiendo FAQ

¿Puedo crear mis propias funciones en C?

¿Puedo crear mis propias funciones en C++?

Escribir en C es difícil; ¿no hay otra alternativa?

¿Cómo puedo ejecutar declaraciones arbitrarias de Python desde C?

¿Cómo puedo evaluar una expresión arbitraria de Python desde C?

¿Cómo extraigo valores C de un objeto Python?

¿Cómo utilizo Py_BuildValue() para crear una tupla de un tamaño arbitrario?

¿Cómo puedo llamar un método de un objeto desde C?

¿Cómo obtengo la salida de PyErr_Print() (o cualquier cosa que se imprime a stdout/stderr)?

¿Cómo accedo al módulo escrito en Python desde C?

¿Cómo hago una interface a objetos C++ desde Python?

He agregado un módulo usando el archivo de configuración y el make falla. ¿Porque?

¿Cómo puedo depurar una extensión?

Quiero compilar un módulo Python en mi sistema Linux, pero me faltan algunos archivos . ¿Por qué?

¿Cómo digo «entrada incompleta» desde «entrada inválida»?

¿Cómo encuentro símbolos g++ __builtin_new o __pure_virtual?

¿Puedo crear una clase objeto con algunos métodos implementado en C y otros en Python (por ejemplo a través de la herencia)?

Preguntas frecuentes sobre Python en Windows

¿Cómo ejecutar un programa Python en Windows?

¿Cómo hacer que los scripts de Python sean ejecutables?

¿Por qué Python tarda en comenzar?

¿Cómo hacer un ejecutable a partir de un script de Python?

¿Es un archivo *.pyd lo mismo que una DLL?

¿Cómo puedo integrar Python en una aplicación de Windows?

¿Cómo puedo evitar que mi editor inserte pestañas en mi archivo fuente de Python?

¿Cómo verifico una pulsación de tecla sin bloquearla?

Preguntas frecuentes sobre la Interfaz Gráfica de Usuario (GUI)

Preguntas generales de la GUI

What GUI toolkits exist for Python?

Preguntas de Tkinter

«¿Por qué está Python instalado en mi ordenador?» FAQ

¿Qué es Python?

¿Por qué Python está instalado en mi máquina?

¿Puedo eliminar Python?

Glosario

Acerca de estos documentos

Contribuidores de la documentación de Python

Lidiar con errores

Documentación de errores

Utilizar el issue tracker de Python

Para empezar a contribuir en Python

Derechos de autor

Historia y Licencia

Historia del software

Términos y condiciones para acceder o usar Python

ACUERDO DE LICENCIA DE PSF PARA PYTHON | lanzamiento |

ACUERDO DE LICENCIA DE BEOPEN.COM PARA PYTHON 2.0

ACUERDO DE LICENCIA CNRI PARA PYTHON 1.6.1

ACUERDO DE LICENCIA CWI PARA PYTHON 0.9.0 HASTA 1.2

LICENCIA BSD DE CLÁUSULA CERO PARA CÓDIGO EN EL PYTHON | lanzamiento | DOCUMENTACIÓN

Licencias y reconocimientos para software incorporado

Mersenne Twister

Sockets

Servicios de socket asincrónicos

Gestión de cookies

Seguimiento de ejecución

funciones UUencode y UUdecode

Llamadas a procedimientos remotos XML

test_epoll

Seleccionar kqueue

SipHash24

strtod y dtoa

OpenSSL

expat

libffi

zlib

cfuhash

libmpdec

Conjunto de pruebas W3C C14N

Qué hay de nuevo en Python

La serie «Qué hay de nuevo en Python» da un vistazo a los cambios más importantes entre las versiones de Python. Son de «lectura obligatoria» para cualquier persona que quiera estar al día después de un nuevo lanzamiento.

What’s New In Python 3.9

Summary – Release highlights

You should check for DeprecationWarning in your code

New Features

Other Language Changes

New Modules

Improved Modules

Optimizations

Deprecated

Removed

Porting to Python 3.9

Build Changes

C API Changes

Notable changes in Python 3.9.1

Notable changes in Python 3.9.2

Notable changes in Python 3.9.3

Notable changes in Python 3.9.5

Notable security feature in 3.9.14

Notable Changes in 3.9.17

Qué hay de nuevo en Python 3.8

Resumen – Aspectos destacados de la versión

Nuevas características

Otros cambios en el lenguaje

Nuevos módulos

Módulos mejorados

Optimizaciones

Cambios en la compilación y la API de C

Obsoleto

APIs y características eliminadas

Portando a Python 3.8

Cambios notables en Python 3.8.1

Cambios notables en Python 3.8.8

Notable changes in Python 3.8.12

Que hay de nuevo en Python 3.7

Resumen – Lanzamientos Destacados

Nuevas Características

Otros cambios en el lenguaje

Nuevos módulos

Módulos mejorados

Cambios en la API C

Construir cambios

Optimizaciones

Otros cambios de implementación de CPython

Comportamiento obsoleto de Python

Módulos, funciones y métodos de Python obsoletos

Funciones y tipos obsoletos de la API C

Eliminación de soporte de plataforma

Eliminaciones de API y funciones

Eliminaciones de módulos

Cambios solo en Windows

Portando a Python 3.7

Cambios notables en Python 3.7.1

Cambios notables en Python 3.7.2

Cambios notables en Python 3.7.6

Cambios notables en Python 3.7.10

What’s New In Python 3.6

Summary – Release highlights

New Features

Other Language Changes

New Modules

Improved Modules

Optimizations

Build and C API Changes

Other Improvements

Deprecated

Removed

Porting to Python 3.6

Notable changes in Python 3.6.2

Notable changes in Python 3.6.4

Notable changes in Python 3.6.5

Notable changes in Python 3.6.7

Notable changes in Python 3.6.10

Notable changes in Python 3.6.13

Qué hay de nuevo en Python 3.5

Resumen – Aspectos destacados de la versión

Nuevas características

Otros cambios en el lenguaje

Nuevos módulos

Módulos mejorados

Otros cambios a nivel de módulo

Optimizaciones

Cambios en la compilación y la API de C

Obsoleto

Eliminado

Portando a Python 3.5

Cambios notables en Python 3.5.4

What’s New In Python 3.4

Summary – Release Highlights

New Features

New Modules

Improved Modules

CPython Implementation Changes

Deprecated

Removed

Porting to Python 3.4

Changed in 3.4.3

Que novedades hay en python 3.3

Resumen – aspectos destacados de la versión

PEP 405: Entornos virtuales

PEP 420: Paquetes para espacios de nombres implícitos

PEP 3118: Nueva implementación de vista de memoria y en la documentación del protocolo del buffer

PEP 393: Representación flexible de cadenas de caracteres

PEP 397: Lanzador de python para windows

PEP 3151: Reelaborando de la jerarquía de excepciones de IO y OS

PEP 380: Sintaxis para delegar en un subgenerador

PEP 409: Suprimir el contexto de excepción

PEP 414: Literales Unicode explícitos

PEP 3155: Nombres calificados para clases y funciones

PEP 412: Diccionario de intercambio de claves

PEP 362: Objeto de firma de función

PEP 421: Agregar sys.implementation

Usar importlib como implementación de Import

Otros cambios de idioma

Un bloqueo de importación más detallado

Funciones y tipos incorporados

Nuevos módulos

Módulos mejorados

Optimizaciones

Construcción y cambios en la API de C

Obsoleto

Migración a Python 3.3

Qué hay de nuevo en Python 3.2

PEP 384: Definición de un ABI estable

PEP 389: Módulo de análisis sintáctico (Parser) de línea de comandos Argparse

PEP 391: Configuración basada en diccionario para Logging

PEP 3148: El módulo concurrent.futures

PEP 3147: Directorios del repositorio de PYC

PEP 3149: Archivos .so con etiquetado de versión para ABI

PEP 3333: Interfaz de puerta de enlace del servidor web Python v1.0.1

Otros cambios de lenguaje

Módulos nuevos, mejorados y obsoletos

Multi-threading

Optimizations

Unicode

Codecs

Documentación

IDLE

Repositorio de código

Cambios en la API de construcción y C

Portar a Python 3.2

Qué hay de nuevo en Python 3.1

PEP 372: Diccionarios ordenados

PEP 378: Especificador de formato para el separador de miles

Otros cambios del lenguaje

Módulos nuevos, mejorados y obsoletos

Optimizaciones

IDLE

Cambios en la compilación y la API de C

Portando a Python 3.1

Qué hay de nuevo en Python 3.0

Escollos comunes

Descripción general de los cambios de sintaxis

Cambios ya presentes en Python 2.6

Cambios de biblioteca

PEP 3101: Un nuevo enfoque al formateo de cadena de caracteres

Cambios a excepciones

Otros cambios diversos

Construcción y cambios a la API de C

Rendimiento

Migración a Python 3.0

Qué hay de nuevo en Python 2.7

El futuro de Python 2.x

Cambios en el manejo de las advertencias de desuso

Características de Python 3.1

PEP 372: Adición de un diccionario ordenado a las colecciones

PEP 378: Especificador de formato para separador de miles

PEP 389: El módulo argparse para el análisis de líneas de comando

PEP 391: Configuración basada en diccionarios para el registro

PEP 3106: Vistas de diccionario

PEP 3137: El objeto memoryview

Otros cambios de lenguaje

New and Improved Modules

Build and C API Changes

Other Changes and Fixes

Porting to Python 2.7

New Features Added to Python 2.7 Maintenance Releases

Acknowledgements

Qué hay de nuevo en Python 2.6

Python 3.0

Cambios en el proceso de desarrollo

PEP 343: La sentencia “with”

PEP 366: Importaciones relativas explícitas desde un módulo principal

PEP 370: Directorio de site-packages por usuario

PEP 371: El paquete multiprocessing

PEP 3101: Formateo avanzado de cadena de caracteres

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

Other Language Changes

New and Improved Modules

Deprecations and Removals

Build and C API Changes

Porting to Python 2.6

Agradecimientos

Novedades de Python 2.5

PEP 308: Expresiones condicionales

PEP 309: Aplicación parcial de funciones

PEP 314: Metadatos para paquetes de software Python v1.1

PEP 328: Importaciones absolutas y relativas

PEP 338: Ejecutando Módulos como Scripts

PEP 341: Try/except/finally unificados

PEP 342: Nuevas funciones del generador

PEP 343: La declaración «con

PEP 352: Las excepciones como clases de nuevo estilo

PEP 353: Uso de ssize_t como tipo de índice

PEP 357: El método “__index__”

Otros cambios lingüísticos

Módulos nuevos, mejorados y eliminados

Cambios en la API de construcción y C

Adaptación a Python 2.5

Agradecimientos

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

PEP 328: Multi-line Imports

PEP 331: Locale-Independent Float/String Conversions

Other Language Changes

New, Improved, and Deprecated Modules

Build and C API Changes

Porting to Python 2.4

Acknowledgements

Qué hay de nuevo en Python 2.3

PEP 218: Un tipo de datos de conjunto estándar

PEP 255: Generadores simples

PEP 263: Codificación del código fuente

PEP 273: Importar módulos desde archivos ZIP

PEP 277: Soporte de nombres de archivo Unicode para Windows NT

PEP 278: Soporte universal de nuevas líneas

PEP 279: enumerate()

PEP 282: El paquete de registro

PEP 285: Un tipo booleano

PEP 293: Llamadas de retorno para el manejo de errores del códec

PEP 301: Índice de paquetes y metadatos para Distutils

PEP 302: Nuevos ganchos de importación

PEP 305: Archivos separados por comas

PEP 307: Mejoras en Pickle

Rebanadas ampliadas

Otros cambios en el lenguaje

Módulos nuevos, mejorados y obsoletos

Pymalloc: A Specialized Object Allocator

Build and C API Changes

Other Changes and Fixes

Porting to Python 2.3

Acknowledgements

Qué hay de nuevo en Python 2.2

Introducción

PEPs 252 y 253: Cambios de tipo y clase

PEP 234: Iteradores

PEP 255: Generadores simples

PEP 237: Unificación de enteros largos y enteros

PEP 238: Cambio del operador de división

Cambios en Unicode

PEP 227: Ámbitos anidados

Módulos nuevos y mejorados

Cambios y correcciones en el intérprete

Otros cambios y correcciones

Agradecimientos

Novedades de Python 2.1

Introducción

PEP 227: Ámbitos anidados

PEP 236: Directivas __future__

PEP 207: Comparaciones Enriquecidas

PEP 230: Marco de advertencia

PEP 229: Sistema de construcción nuevo

PEP 205: Referencias débiles

PEP 232: Atributos de la función

PEP 235: Importación de módulos en plataformas que no distinguen entre mayúsculas y minúsculas

PEP 217: Gancho de pantalla interactivo

PEP 208: Nuevo modelo de coerción

PEP 241: Metadatos en paquetes de Python

Módulos nuevos y mejorados

Otros cambios y correcciones

Agradecimientos

Novedades de Python 2.0

Introducción

¿Qué pasa con Python 1.6?

Nuevo proceso de desarrollo

Unicode

Comprensión de listas

Asignación aumentada

Métodos de cadena de caracteres

Recogida de basura de los ciclos

Otros cambios en el núcleo

Adaptación a la versión 2.0

Extensión/Incorporación de cambios

Distutils: Facilitando la instalación de módulos

Módulos XML

Cambios en los módulos

Nuevos módulos

Mejoras en IDLE

Módulos eliminados y obsoletos

Agradecimientos

El «Changelog» is una versión HTML del archivo creado [https://pypi.org/project/blurb] a partir del contenido del directorio Misc/NEWS.d [https://github.com/python/cpython/tree/3.9/Misc/NEWS.d], el cual contiene todos los cambios no triviales en Python para la versión actual.

Changelog

Python next

Python 3.9.18 final

Python 3.9.17 final

Python 3.9.16 final

Python 3.9.15 final

Python 3.9.14 final

Python 3.9.13 final

Python 3.9.12 final

Python 3.9.11 final

Python 3.9.10 final

Python 3.9.9 final

Python 3.9.8 final

Python 3.9.7 final

Python 3.9.6 final

Python 3.9.5 final

Python 3.9.4 final

Python 3.9.3 final

Python 3.9.2 final

Python 3.9.2 release candidate 1

Python 3.9.1 final

Python 3.9.1 release candidate 1

Python 3.9.0 final

Python 3.9.0 release candidate 2

Python 3.9.0 release candidate 1

Python 3.9.0 beta 5

Python 3.9.0 beta 4

Python 3.9.0 beta 3

Python 3.9.0 beta 2

Python 3.9.0 beta 1

Python 3.9.0 alpha 6

Python 3.9.0 alpha 5

Python 3.9.0 alpha 4

Python 3.9.0 alpha 3

Python 3.9.0 alpha 2

Python 3.9.0 alpha 1

Python 3.8.0 beta 1

Python 3.8.0 alpha 4

Python 3.8.0 alpha 3

Python 3.8.0 alpha 2

Python 3.8.0 alpha 1

Python 3.7.0 final

Python 3.7.0 release candidate 1

Python 3.7.0 beta 5

Python 3.7.0 beta 4

Python 3.7.0 beta 3

Python 3.7.0 beta 2

Python 3.7.0 beta 1

Python 3.7.0 alpha 4

Python 3.7.0 alpha 3

Python 3.7.0 alpha 2

Python 3.7.0 alpha 1

Python 3.6.6 final

Python 3.6.6 release candidate 1

Python 3.6.5 final

Python 3.6.5 release candidate 1

Python 3.6.4 final

Python 3.6.4 release candidate 1

Python 3.6.3 final

Python 3.6.3 release candidate 1

Python 3.6.2 final

Python 3.6.2 release candidate 2

Python 3.6.2 release candidate 1

Python 3.6.1 final

Python 3.6.1 release candidate 1

Python 3.6.0 final

Python 3.6.0 release candidate 2

Python 3.6.0 release candidate 1

Python 3.6.0 beta 4

Python 3.6.0 beta 3

Python 3.6.0 beta 2

Python 3.6.0 beta 1

Python 3.6.0 alpha 4

Python 3.6.0 alpha 3

Python 3.6.0 alpha 2

Python 3.6.0 alpha 1

Python 3.5.5 final

Python 3.5.5 release candidate 1

Python 3.5.4 final

Python 3.5.4 release candidate 1

Python 3.5.3 final

Python 3.5.3 release candidate 1

Python 3.5.2 final

Python 3.5.2 release candidate 1

Python 3.5.1 final

Python 3.5.1 release candidate 1

Python 3.5.0 final

Python 3.5.0 release candidate 4

Python 3.5.0 release candidate 3

Python 3.5.0 release candidate 2

Python 3.5.0 release candidate 1

Python 3.5.0 beta 4

Python 3.5.0 beta 3

Python 3.5.0 beta 2

Python 3.5.0 beta 1

Python 3.5.0 alpha 4

Python 3.5.0 alpha 3

Python 3.5.0 alpha 2

Python 3.5.0 alpha 1

What’s New In Python 3.9

Release

3.9.18

Date

febrero 07, 2024

Editor

Łukasz Langa

This article explains the new features in Python 3.9, compared to 3.8. Python 3.9 was released on October 5th, 2020.

For full details, see the changelog.

Ver también

PEP 596 [https://www.python.org/dev/peps/pep-0596] - Python 3.9 Release Schedule

Summary – Release highlights

New syntax features:

PEP 584 [https://www.python.org/dev/peps/pep-0584], union operators added to dict;

PEP 585 [https://www.python.org/dev/peps/pep-0585], type hinting generics in standard collections;

PEP 614 [https://www.python.org/dev/peps/pep-0614], relaxed grammar restrictions on decorators.

New built-in features:

PEP 616 [https://www.python.org/dev/peps/pep-0616], string methods to remove prefixes and suffixes.

New features in the standard library:

PEP 593 [https://www.python.org/dev/peps/pep-0593], flexible function and variable annotations;

os.pidfd_open() added that allows process management without races and signals.

Interpreter improvements:

PEP 573 [https://www.python.org/dev/peps/pep-0573], fast access to module state from methods of C extension types;

PEP 617 [https://www.python.org/dev/peps/pep-0617], CPython now uses a new parser based on PEG;

a number of Python builtins (range, tuple, set, frozenset, list, dict) are now sped up using PEP 590 [https://www.python.org/dev/peps/pep-0590] vectorcall;

garbage collection does not block on resurrected objects;

a number of Python modules (_abc, audioop, _bz2, _codecs, _contextvars, _crypt, _functools, _json, _locale, math, operator, resource, time, _weakref) now use multiphase initialization as defined by PEP 489;

a number of standard library modules (audioop, ast, grp, _hashlib, pwd, _posixsubprocess, random, select, struct, termios, zlib) are now using the stable ABI defined by PEP 384.

New library modules:

PEP 615 [https://www.python.org/dev/peps/pep-0615], the IANA Time Zone Database is now present in the standard library in the zoneinfo module;

an implementation of a topological sort of a graph is now provided in the new graphlib module.

Release process changes:

PEP 602 [https://www.python.org/dev/peps/pep-0602], CPython adopts an annual release cycle.

You should check for DeprecationWarning in your code

When Python 2.7 was still supported, a lot of functionality in Python 3 was kept for backward compatibility with Python 2.7. With the end of Python 2 support, these backward compatibility layers have been removed, or will be removed soon. Most of them emitted a DeprecationWarning warning for several years. For example, using collections.Mapping instead of collections.abc.Mapping emits a DeprecationWarning since Python 3.3, released in 2012.

Test your application with the -W default command-line option to see DeprecationWarning and PendingDeprecationWarning, or even with -W error to treat them as errors. Warnings Filter can be used to ignore warnings from third-party code.

Python 3.9 is the last version providing those Python 2 backward compatibility layers, to give more time to Python projects maintainers to organize the removal of the Python 2 support and add support for Python 3.9.

Aliases to Abstract Base Classes in the collections module, like collections.Mapping alias to collections.abc.Mapping, are kept for one last release for backward compatibility. They will be removed from Python 3.10.

More generally, try to run your tests in the Python Development Mode which helps to prepare your code to make it compatible with the next Python version.

Note: a number of pre-existing deprecations were removed in this version of Python as well. Consult the Removed section.

New Features

Dictionary Merge & Update Operators

Merge (|) and update (|=) operators have been added to the built-in dict class. Those complement the existing dict.update and {**d1, **d2} methods of merging dictionaries.

Example:

>>> x = {"key1": "value1 from x", "key2": "value2 from x"}
>>> y = {"key2": "value2 from y", "key3": "value3 from y"}
>>> x | y
{'key1': 'value1 from x', 'key2': 'value2 from y', 'key3': 'value3 from y'}
>>> y | x
{'key2': 'value2 from x', 'key3': 'value3 from y', 'key1': 'value1 from x'}

See PEP 584 [https://www.python.org/dev/peps/pep-0584] for a full description. (Contributed by Brandt Bucher in bpo-36144 [https://bugs.python.org/issue?@action=redirect&bpo=36144].)

New String Methods to Remove Prefixes and Suffixes

str.removeprefix(prefix) and str.removesuffix(suffix) have been added to easily remove an unneeded prefix or a suffix from a string. Corresponding bytes, bytearray, and collections.UserString methods have also been added. See PEP 616 [https://www.python.org/dev/peps/pep-0616] for a full description. (Contributed by Dennis Sweeney in bpo-39939 [https://bugs.python.org/issue?@action=redirect&bpo=39939].)

Type Hinting Generics in Standard Collections

In type annotations you can now use built-in collection types such as list and dict as generic types instead of importing the corresponding capitalized types (e.g. List or Dict) from typing. Some other types in the standard library are also now generic, for example queue.Queue.

Example:

def greet_all(names: list[str]) -> None:
    for name in names:
        print("Hello", name)

See PEP 585 [https://www.python.org/dev/peps/pep-0585] for more details. (Contributed by Guido van Rossum, Ethan Smith, and Batuhan Taşkaya in bpo-39481 [https://bugs.python.org/issue?@action=redirect&bpo=39481].)

New Parser

Python 3.9 uses a new parser, based on PEG [https://en.wikipedia.org/wiki/Parsing_expression_grammar] instead of LL(1) [https://en.wikipedia.org/wiki/LL_parser]. The new parser’s performance is roughly comparable to that of the old parser, but the PEG formalism is more flexible than LL(1) when it comes to designing new language features. We’ll start using this flexibility in Python 3.10 and later.

The ast module uses the new parser and produces the same AST as the old parser.

In Python 3.10, the old parser will be deleted and so will all functionality that depends on it (primarily the parser module, which has long been deprecated). In Python 3.9 only, you can switch back to the LL(1) parser using a command line switch (-X oldparser) or an environment variable (PYTHONOLDPARSER=1).

See PEP 617 [https://www.python.org/dev/peps/pep-0617] for more details. (Contributed by Guido van Rossum, Pablo Galindo and Lysandros Nikolaou in bpo-40334 [https://bugs.python.org/issue?@action=redirect&bpo=40334].)

Other Language Changes

__import__() now raises ImportError instead of ValueError, which used to occur when a relative import went past its top-level package. (Contributed by Ngalim Siregar in bpo-37444 [https://bugs.python.org/issue?@action=redirect&bpo=37444].)

Python now gets the absolute path of the script filename specified on the command line (ex: python3 script.py): the __file__ attribute of the __main__ module became an absolute path, rather than a relative path. These paths now remain valid after the current directory is changed by os.chdir(). As a side effect, the traceback also displays the absolute path for __main__ module frames in this case. (Contributed by Victor Stinner in bpo-20443 [https://bugs.python.org/issue?@action=redirect&bpo=20443].)

In the Python Development Mode and in debug build, the encoding and errors arguments are now checked for string encoding and decoding operations. Examples: open(), str.encode() and bytes.decode().

By default, for best performance, the errors argument is only checked at the first encoding/decoding error and the encoding argument is sometimes ignored for empty strings. (Contributed by Victor Stinner in bpo-37388 [https://bugs.python.org/issue?@action=redirect&bpo=37388].)

"".replace("", s, n) now returns s instead of an empty string for all non-zero n. It is now consistent with "".replace("", s). There are similar changes for bytes and bytearray objects. (Contributed by Serhiy Storchaka in bpo-28029 [https://bugs.python.org/issue?@action=redirect&bpo=28029].)

Any valid expression can now be used as a decorator. Previously, the grammar was much more restrictive. See PEP 614 [https://www.python.org/dev/peps/pep-0614] for details. (Contributed by Brandt Bucher in bpo-39702 [https://bugs.python.org/issue?@action=redirect&bpo=39702].)

Improved help for the typing module. Docstrings are now shown for all special forms and special generic aliases (like Union and List). Using help() with generic alias like List[int] will show the help for the correspondent concrete type (list in this case). (Contributed by Serhiy Storchaka in bpo-40257 [https://bugs.python.org/issue?@action=redirect&bpo=40257].)

Parallel running of aclose() / asend() / athrow() is now prohibited, and ag_running now reflects the actual running status of the async generator. (Contributed by Yury Selivanov in bpo-30773 [https://bugs.python.org/issue?@action=redirect&bpo=30773].)

Unexpected errors in calling the __iter__ method are no longer masked by TypeError in the in operator and functions contains(), indexOf() and countOf() of the operator module. (Contributed by Serhiy Storchaka in bpo-40824 [https://bugs.python.org/issue?@action=redirect&bpo=40824].)

Unparenthesized lambda expressions can no longer be the expression part in an if clause in comprehensions and generator expressions. See bpo-41848 [https://bugs.python.org/issue?@action=redirect&bpo=41848] and bpo-43755 [https://bugs.python.org/issue?@action=redirect&bpo=43755] for details.

New Modules

zoneinfo

The zoneinfo module brings support for the IANA time zone database to the standard library. It adds zoneinfo.ZoneInfo, a concrete datetime.tzinfo implementation backed by the system’s time zone data.

Example:

>>> from zoneinfo import ZoneInfo
>>> from datetime import datetime, timedelta

>>> # Daylight saving time
>>> dt = datetime(2020, 10, 31, 12, tzinfo=ZoneInfo("America/Los_Angeles"))
>>> print(dt)
2020-10-31 12:00:00-07:00
>>> dt.tzname()
'PDT'

>>> # Standard time
>>> dt += timedelta(days=7)
>>> print(dt)
2020-11-07 12:00:00-08:00
>>> print(dt.tzname())
PST

As a fall-back source of data for platforms that don’t ship the IANA database, the tzdata [https://pypi.org/project/tzdata/] module was released as a first-party package – distributed via PyPI and maintained by the CPython core team.

Ver también

PEP 615 [https://www.python.org/dev/peps/pep-0615] – Support for the IANA Time Zone Database in the Standard Library

PEP written and implemented by Paul Ganssle

graphlib

A new module, graphlib, was added that contains the graphlib.TopologicalSorter class to offer functionality to perform topological sorting of graphs. (Contributed by Pablo Galindo, Tim Peters and Larry Hastings in bpo-17005 [https://bugs.python.org/issue?@action=redirect&bpo=17005].)

Improved Modules

ast

Added the indent option to dump() which allows it to produce a multiline indented output. (Contributed by Serhiy Storchaka in bpo-37995 [https://bugs.python.org/issue?@action=redirect&bpo=37995].)

Added ast.unparse() as a function in the ast module that can be used to unparse an ast.AST object and produce a string with code that would produce an equivalent ast.AST object when parsed. (Contributed by Pablo Galindo and Batuhan Taskaya in bpo-38870 [https://bugs.python.org/issue?@action=redirect&bpo=38870].)

Added docstrings to AST nodes that contains the ASDL signature used to construct that node. (Contributed by Batuhan Taskaya in bpo-39638 [https://bugs.python.org/issue?@action=redirect&bpo=39638].)

asyncio

Due to significant security concerns, the reuse_address parameter of asyncio.loop.create_datagram_endpoint() is no longer supported. This is because of the behavior of the socket option SO_REUSEADDR in UDP. For more details, see the documentation for loop.create_datagram_endpoint(). (Contributed by Kyle Stanley, Antoine Pitrou, and Yury Selivanov in bpo-37228 [https://bugs.python.org/issue?@action=redirect&bpo=37228].)

Added a new coroutine shutdown_default_executor() that schedules a shutdown for the default executor that waits on the ThreadPoolExecutor to finish closing. Also, asyncio.run() has been updated to use the new coroutine. (Contributed by Kyle Stanley in bpo-34037 [https://bugs.python.org/issue?@action=redirect&bpo=34037].)

Added asyncio.PidfdChildWatcher, a Linux-specific child watcher implementation that polls process file descriptors. (bpo-38692 [https://bugs.python.org/issue?@action=redirect&bpo=38692])

Added a new coroutine asyncio.to_thread(). It is mainly used for running IO-bound functions in a separate thread to avoid blocking the event loop, and essentially works as a high-level version of run_in_executor() that can directly take keyword arguments. (Contributed by Kyle Stanley and Yury Selivanov in bpo-32309 [https://bugs.python.org/issue?@action=redirect&bpo=32309].)

When cancelling the task due to a timeout, asyncio.wait_for() will now wait until the cancellation is complete also in the case when timeout is <= 0, like it does with positive timeouts. (Contributed by Elvis Pranskevichus in bpo-32751 [https://bugs.python.org/issue?@action=redirect&bpo=32751].)

asyncio now raises TyperError when calling incompatible methods with an ssl.SSLSocket socket. (Contributed by Ido Michael in bpo-37404 [https://bugs.python.org/issue?@action=redirect&bpo=37404].)

compileall

Added new possibility to use hardlinks for duplicated .pyc files: hardlink_dupes parameter and –hardlink-dupes command line option. (Contributed by Lumír “Frenzy” Balhar in bpo-40495 [https://bugs.python.org/issue?@action=redirect&bpo=40495].)

Added new options for path manipulation in resulting .pyc files: stripdir, prependdir, limit_sl_dest parameters and -s, -p, -e command line options. Added the possibility to specify the option for an optimization level multiple times. (Contributed by Lumír “Frenzy” Balhar in bpo-38112 [https://bugs.python.org/issue?@action=redirect&bpo=38112].)

concurrent.futures

Added a new cancel_futures parameter to concurrent.futures.Executor.shutdown() that cancels all pending futures which have not started running, instead of waiting for them to complete before shutting down the executor. (Contributed by Kyle Stanley in bpo-39349 [https://bugs.python.org/issue?@action=redirect&bpo=39349].)

Removed daemon threads from ThreadPoolExecutor and ProcessPoolExecutor. This improves compatibility with subinterpreters and predictability in their shutdown processes. (Contributed by Kyle Stanley in bpo-39812 [https://bugs.python.org/issue?@action=redirect&bpo=39812].)

Workers in ProcessPoolExecutor are now spawned on demand, only when there are no available idle workers to reuse. This optimizes startup overhead and reduces the amount of lost CPU time to idle workers. (Contributed by Kyle Stanley in bpo-39207 [https://bugs.python.org/issue?@action=redirect&bpo=39207].)

curses

Added curses.get_escdelay(), curses.set_escdelay(), curses.get_tabsize(), and curses.set_tabsize() functions. (Contributed by Anthony Sottile in bpo-38312 [https://bugs.python.org/issue?@action=redirect&bpo=38312].)

datetime

The isocalendar() of datetime.date and isocalendar() of datetime.datetime methods now returns a namedtuple() instead of a tuple. (Contributed by Dong-hee Na in bpo-24416 [https://bugs.python.org/issue?@action=redirect&bpo=24416].)

distutils

The upload command now creates SHA2-256 and Blake2b-256 hash digests. It skips MD5 on platforms that block MD5 digest. (Contributed by Christian Heimes in bpo-40698 [https://bugs.python.org/issue?@action=redirect&bpo=40698].)

fcntl

Added constants F_OFD_GETLK, F_OFD_SETLK and F_OFD_SETLKW. (Contributed by Dong-hee Na in bpo-38602 [https://bugs.python.org/issue?@action=redirect&bpo=38602].)

ftplib

FTP and FTP_TLS now raise a ValueError if the given timeout for their constructor is zero to prevent the creation of a non-blocking socket. (Contributed by Dong-hee Na in bpo-39259 [https://bugs.python.org/issue?@action=redirect&bpo=39259].)

gc

When the garbage collector makes a collection in which some objects resurrect (they are reachable from outside the isolated cycles after the finalizers have been executed), do not block the collection of all objects that are still unreachable. (Contributed by Pablo Galindo and Tim Peters in bpo-38379 [https://bugs.python.org/issue?@action=redirect&bpo=38379].)

Added a new function gc.is_finalized() to check if an object has been finalized by the garbage collector. (Contributed by Pablo Galindo in bpo-39322 [https://bugs.python.org/issue?@action=redirect&bpo=39322].)

hashlib

The hashlib module can now use SHA3 hashes and SHAKE XOF from OpenSSL when available. (Contributed by Christian Heimes in bpo-37630 [https://bugs.python.org/issue?@action=redirect&bpo=37630].)

Builtin hash modules can now be disabled with ./configure --without-builtin-hashlib-hashes or selectively enabled with e.g. ./configure --with-builtin-hashlib-hashes=sha3,blake2 to force use of OpenSSL based implementation. (Contributed by Christian Heimes in bpo-40479 [https://bugs.python.org/issue?@action=redirect&bpo=40479])

http

HTTP status codes 103 EARLY_HINTS, 418 IM_A_TEAPOT and 425 TOO_EARLY are added to http.HTTPStatus. (Contributed by Dong-hee Na in bpo-39509 [https://bugs.python.org/issue?@action=redirect&bpo=39509] and Ross Rhodes in bpo-39507 [https://bugs.python.org/issue?@action=redirect&bpo=39507].)

IDLE and idlelib

Added option to toggle cursor blink off. (Contributed by Zackery Spytz in bpo-4603 [https://bugs.python.org/issue?@action=redirect&bpo=4603].)

Escape key now closes IDLE completion windows. (Contributed by Johnny Najera in bpo-38944 [https://bugs.python.org/issue?@action=redirect&bpo=38944].)

Added keywords to module name completion list. (Contributed by Terry J. Reedy in bpo-37765 [https://bugs.python.org/issue?@action=redirect&bpo=37765].)

New in 3.9 maintenance releases

Make IDLE invoke sys.excepthook() (when started without “-n”). User hooks were previously ignored. (Contributed by Ken Hilton in bpo-43008 [https://bugs.python.org/issue?@action=redirect&bpo=43008].)

The changes above have been backported to 3.8 maintenance releases.

Rearrange the settings dialog. Split the General tab into Windows and Shell/Ed tabs. Move help sources, which extend the Help menu, to the Extensions tab. Make space for new options and shorten the dialog. The latter makes the dialog better fit small screens. (Contributed by Terry Jan Reedy in bpo-40468 [https://bugs.python.org/issue?@action=redirect&bpo=40468].) Move the indent space setting from the Font tab to the new Windows tab. (Contributed by Mark Roseman and Terry Jan Reedy in bpo-33962 [https://bugs.python.org/issue?@action=redirect&bpo=33962].)

Apply syntax highlighting to .pyi files. (Contributed by Alex Waygood and Terry Jan Reedy in bpo-45447 [https://bugs.python.org/issue?@action=redirect&bpo=45447].)

imaplib

IMAP4 and IMAP4_SSL now have an optional timeout parameter for their constructors. Also, the open() method now has an optional timeout parameter with this change. The overridden methods of IMAP4_SSL and IMAP4_stream were applied to this change. (Contributed by Dong-hee Na in bpo-38615 [https://bugs.python.org/issue?@action=redirect&bpo=38615].)

imaplib.IMAP4.unselect() is added. imaplib.IMAP4.unselect() frees server’s resources associated with the selected mailbox and returns the server to the authenticated state. This command performs the same actions as imaplib.IMAP4.close(), except that no messages are permanently removed from the currently selected mailbox. (Contributed by Dong-hee Na in bpo-40375 [https://bugs.python.org/issue?@action=redirect&bpo=40375].)

importlib

To improve consistency with import statements, importlib.util.resolve_name() now raises ImportError instead of ValueError for invalid relative import attempts. (Contributed by Ngalim Siregar in bpo-37444 [https://bugs.python.org/issue?@action=redirect&bpo=37444].)

Import loaders which publish immutable module objects can now publish immutable packages in addition to individual modules. (Contributed by Dino Viehland in bpo-39336 [https://bugs.python.org/issue?@action=redirect&bpo=39336].)

Added importlib.resources.files() function with support for subdirectories in package data, matching backport in importlib_resources version 1.5. (Contributed by Jason R. Coombs in bpo-39791 [https://bugs.python.org/issue?@action=redirect&bpo=39791].)

Refreshed importlib.metadata from importlib_metadata version 1.6.1.

inspect

inspect.BoundArguments.arguments is changed from OrderedDict to regular dict. (Contributed by Inada Naoki in bpo-36350 [https://bugs.python.org/issue?@action=redirect&bpo=36350] and bpo-39775 [https://bugs.python.org/issue?@action=redirect&bpo=39775].)

ipaddress

ipaddress now supports IPv6 Scoped Addresses (IPv6 address with suffix %<scope_id>).

Scoped IPv6 addresses can be parsed using ipaddress.IPv6Address. If present, scope zone ID is available through the scope_id attribute. (Contributed by Oleksandr Pavliuk in bpo-34788 [https://bugs.python.org/issue?@action=redirect&bpo=34788].)

Starting with Python 3.9.5 the ipaddress module no longer accepts any leading zeros in IPv4 address strings. (Contributed by Christian Heimes in bpo-36384 [https://bugs.python.org/issue?@action=redirect&bpo=36384]).

math

Expanded the math.gcd() function to handle multiple arguments. Formerly, it only supported two arguments. (Contributed by Serhiy Storchaka in bpo-39648 [https://bugs.python.org/issue?@action=redirect&bpo=39648].)

Added math.lcm(): return the least common multiple of specified arguments. (Contributed by Mark Dickinson, Ananthakrishnan and Serhiy Storchaka in bpo-39479 [https://bugs.python.org/issue?@action=redirect&bpo=39479] and bpo-39648 [https://bugs.python.org/issue?@action=redirect&bpo=39648].)

Added math.nextafter(): return the next floating-point value after x towards y. (Contributed by Victor Stinner in bpo-39288 [https://bugs.python.org/issue?@action=redirect&bpo=39288].)

Added math.ulp(): return the value of the least significant bit of a float. (Contributed by Victor Stinner in bpo-39310 [https://bugs.python.org/issue?@action=redirect&bpo=39310].)

multiprocessing

The multiprocessing.SimpleQueue class has a new close() method to explicitly close the queue. (Contributed by Victor Stinner in bpo-30966 [https://bugs.python.org/issue?@action=redirect&bpo=30966].)

nntplib

NNTP and NNTP_SSL now raise a ValueError if the given timeout for their constructor is zero to prevent the creation of a non-blocking socket. (Contributed by Dong-hee Na in bpo-39259 [https://bugs.python.org/issue?@action=redirect&bpo=39259].)

os

Added CLD_KILLED and CLD_STOPPED for si_code. (Contributed by Dong-hee Na in bpo-38493 [https://bugs.python.org/issue?@action=redirect&bpo=38493].)

Exposed the Linux-specific os.pidfd_open() (bpo-38692 [https://bugs.python.org/issue?@action=redirect&bpo=38692]) and os.P_PIDFD (bpo-38713 [https://bugs.python.org/issue?@action=redirect&bpo=38713]) for process management with file descriptors.

The os.unsetenv() function is now also available on Windows. (Contributed by Victor Stinner in bpo-39413 [https://bugs.python.org/issue?@action=redirect&bpo=39413].)

The os.putenv() and os.unsetenv() functions are now always available. (Contributed by Victor Stinner in bpo-39395 [https://bugs.python.org/issue?@action=redirect&bpo=39395].)

Added os.waitstatus_to_exitcode() function: convert a wait status to an exit code. (Contributed by Victor Stinner in bpo-40094 [https://bugs.python.org/issue?@action=redirect&bpo=40094].)

pathlib

Added pathlib.Path.readlink() which acts similarly to os.readlink(). (Contributed by Girts Folkmanis in bpo-30618 [https://bugs.python.org/issue?@action=redirect&bpo=30618])

pdb

On Windows now Pdb supports ~/.pdbrc. (Contributed by Tim Hopper and Dan Lidral-Porter in bpo-20523 [https://bugs.python.org/issue?@action=redirect&bpo=20523].)

poplib

POP3 and POP3_SSL now raise a ValueError if the given timeout for their constructor is zero to prevent the creation of a non-blocking socket. (Contributed by Dong-hee Na in bpo-39259 [https://bugs.python.org/issue?@action=redirect&bpo=39259].)

pprint

pprint can now pretty-print types.SimpleNamespace. (Contributed by Carl Bordum Hansen in bpo-37376 [https://bugs.python.org/issue?@action=redirect&bpo=37376].)

pydoc

The documentation string is now shown not only for class, function, method etc, but for any object that has its own __doc__ attribute. (Contributed by Serhiy Storchaka in bpo-40257 [https://bugs.python.org/issue?@action=redirect&bpo=40257].)

random

Added a new random.Random.randbytes method: generate random bytes. (Contributed by Victor Stinner in bpo-40286 [https://bugs.python.org/issue?@action=redirect&bpo=40286].)

signal

Exposed the Linux-specific signal.pidfd_send_signal() for sending to signals to a process using a file descriptor instead of a pid. (bpo-38712 [https://bugs.python.org/issue?@action=redirect&bpo=38712])

smtplib

SMTP and SMTP_SSL now raise a ValueError if the given timeout for their constructor is zero to prevent the creation of a non-blocking socket. (Contributed by Dong-hee Na in bpo-39259 [https://bugs.python.org/issue?@action=redirect&bpo=39259].)

LMTP constructor now has an optional timeout parameter. (Contributed by Dong-hee Na in bpo-39329 [https://bugs.python.org/issue?@action=redirect&bpo=39329].)

socket

The socket module now exports the CAN_RAW_JOIN_FILTERS constant on Linux 4.1 and greater. (Contributed by Stefan Tatschner and Zackery Spytz in bpo-25780 [https://bugs.python.org/issue?@action=redirect&bpo=25780].)

The socket module now supports the CAN_J1939 protocol on platforms that support it. (Contributed by Karl Ding in bpo-40291 [https://bugs.python.org/issue?@action=redirect&bpo=40291].)

The socket module now has the socket.send_fds() and socket.recv_fds() functions. (Contributed by Joannah Nanjekye, Shinya Okano and Victor Stinner in bpo-28724 [https://bugs.python.org/issue?@action=redirect&bpo=28724].)

time

On AIX, thread_time() is now implemented with thread_cputime() which has nanosecond resolution, rather than clock_gettime(CLOCK_THREAD_CPUTIME_ID) which has a resolution of 10 ms. (Contributed by Batuhan Taskaya in bpo-40192 [https://bugs.python.org/issue?@action=redirect&bpo=40192])

sys

Added a new sys.platlibdir attribute: name of the platform-specific library directory. It is used to build the path of standard library and the paths of installed extension modules. It is equal to "lib" on most platforms. On Fedora and SuSE, it is equal to "lib64" on 64-bit platforms. (Contributed by Jan Matějek, Matěj Cepl, Charalampos Stratakis and Victor Stinner in bpo-1294959 [https://bugs.python.org/issue?@action=redirect&bpo=1294959].)

Previously, sys.stderr was block-buffered when non-interactive. Now stderr defaults to always being line-buffered. (Contributed by Jendrik Seipp in bpo-13601 [https://bugs.python.org/issue?@action=redirect&bpo=13601].)

tracemalloc

Added tracemalloc.reset_peak() to set the peak size of traced memory blocks to the current size, to measure the peak of specific pieces of code. (Contributed by Huon Wilson in bpo-40630 [https://bugs.python.org/issue?@action=redirect&bpo=40630].)

typing

PEP 593 [https://www.python.org/dev/peps/pep-0593] introduced an typing.Annotated type to decorate existing types with context-specific metadata and new include_extras parameter to typing.get_type_hints() to access the metadata at runtime. (Contributed by Till Varoquaux and Konstantin Kashin.)

unicodedata

The Unicode database has been updated to version 13.0.0. (bpo-39926 [https://bugs.python.org/issue?@action=redirect&bpo=39926]).

venv

The activation scripts provided by venv now all specify their prompt customization consistently by always using the value specified by __VENV_PROMPT__. Previously some scripts unconditionally used __VENV_PROMPT__, others only if it happened to be set (which was the default case), and one used __VENV_NAME__ instead. (Contributed by Brett Cannon in bpo-37663 [https://bugs.python.org/issue?@action=redirect&bpo=37663].)

xml

White space characters within attributes are now preserved when serializing xml.etree.ElementTree to XML file. EOLNs are no longer normalized to «n». This is the result of discussion about how to interpret section 2.11 of XML spec. (Contributed by Mefistotelis in bpo-39011 [https://bugs.python.org/issue?@action=redirect&bpo=39011].)

Optimizations

Optimized the idiom for assignment a temporary variable in comprehensions. Now for y in [expr] in comprehensions is as fast as a simple assignment y = expr. For example:

sums = [s for s in [0] for x in data for s in [s + x]]

Unlike the := operator this idiom does not leak a variable to the outer scope.

(Contributed by Serhiy Storchaka in bpo-32856 [https://bugs.python.org/issue?@action=redirect&bpo=32856].)

Optimized signal handling in multithreaded applications. If a thread different than the main thread gets a signal, the bytecode evaluation loop is no longer interrupted at each bytecode instruction to check for pending signals which cannot be handled. Only the main thread of the main interpreter can handle signals.

Previously, the bytecode evaluation loop was interrupted at each instruction until the main thread handles signals. (Contributed by Victor Stinner in bpo-40010 [https://bugs.python.org/issue?@action=redirect&bpo=40010].)

Optimized the subprocess module on FreeBSD using closefrom(). (Contributed by Ed Maste, Conrad Meyer, Kyle Evans, Kubilay Kocak and Victor Stinner in bpo-38061 [https://bugs.python.org/issue?@action=redirect&bpo=38061].)

PyLong_FromDouble() is now up to 1.87x faster for values that fit into long. (Contributed by Sergey Fedoseev in bpo-37986 [https://bugs.python.org/issue?@action=redirect&bpo=37986].)

A number of Python builtins (range, tuple, set, frozenset, list, dict) are now sped up by using PEP 590 [https://www.python.org/dev/peps/pep-0590] vectorcall protocol. (Contributed by Dong-hee Na, Mark Shannon, Jeroen Demeyer and Petr Viktorin in bpo-37207 [https://bugs.python.org/issue?@action=redirect&bpo=37207].)

Optimized difference_update() for the case when the other set is much larger than the base set. (Suggested by Evgeny Kapun with code contributed by Michele Orrù in bpo-8425 [https://bugs.python.org/issue?@action=redirect&bpo=8425].)

Python’s small object allocator (obmalloc.c) now allows (no more than) one empty arena to remain available for immediate reuse, without returning it to the OS. This prevents thrashing in simple loops where an arena could be created and destroyed anew on each iteration. (Contributed by Tim Peters in bpo-37257 [https://bugs.python.org/issue?@action=redirect&bpo=37257].)

floor division of float operation now has a better performance. Also the message of ZeroDivisionError for this operation is updated. (Contributed by Dong-hee Na in bpo-39434 [https://bugs.python.org/issue?@action=redirect&bpo=39434].)

Decoding short ASCII strings with UTF-8 and ascii codecs is now about 15% faster. (Contributed by Inada Naoki in bpo-37348 [https://bugs.python.org/issue?@action=redirect&bpo=37348].)

Here’s a summary of performance improvements from Python 3.4 through Python 3.9:

Python version                       3.4     3.5     3.6     3.7     3.8    3.9
--------------                       ---     ---     ---     ---     ---    ---

Variable and attribute read access:
    read_local                       7.1     7.1     5.4     5.1     3.9    3.9
    read_nonlocal                    7.1     8.1     5.8     5.4     4.4    4.5
    read_global                     15.5    19.0    14.3    13.6     7.6    7.8
    read_builtin                    21.1    21.6    18.5    19.0     7.5    7.8
    read_classvar_from_class        25.6    26.5    20.7    19.5    18.4   17.9
    read_classvar_from_instance     22.8    23.5    18.8    17.1    16.4   16.9
    read_instancevar                32.4    33.1    28.0    26.3    25.4   25.3
    read_instancevar_slots          27.8    31.3    20.8    20.8    20.2   20.5
    read_namedtuple                 73.8    57.5    45.0    46.8    18.4   18.7
    read_boundmethod                37.6    37.9    29.6    26.9    27.7   41.1

Variable and attribute write access:
    write_local                      8.7     9.3     5.5     5.3     4.3    4.3
    write_nonlocal                  10.5    11.1     5.6     5.5     4.7    4.8
    write_global                    19.7    21.2    18.0    18.0    15.8   16.7
    write_classvar                  92.9    96.0   104.6   102.1    39.2   39.8
    write_instancevar               44.6    45.8    40.0    38.9    35.5   37.4
    write_instancevar_slots         35.6    36.1    27.3    26.6    25.7   25.8

Data structure read access:
    read_list                       24.2    24.5    20.8    20.8    19.0   19.5
    read_deque                      24.7    25.5    20.2    20.6    19.8   20.2
    read_dict                       24.3    25.7    22.3    23.0    21.0   22.4
    read_strdict                    22.6    24.3    19.5    21.2    18.9   21.5

Data structure write access:
    write_list                      27.1    28.5    22.5    21.6    20.0   20.0
    write_deque                     28.7    30.1    22.7    21.8    23.5   21.7
    write_dict                      31.4    33.3    29.3    29.2    24.7   25.4
    write_strdict                   28.4    29.9    27.5    25.2    23.1   24.5

Stack (or queue) operations:
    list_append_pop                 93.4   112.7    75.4    74.2    50.8   50.6
    deque_append_pop                43.5    57.0    49.4    49.2    42.5   44.2
    deque_append_popleft            43.7    57.3    49.7    49.7    42.8   46.4

Timing loop:
    loop_overhead                    0.5     0.6     0.4     0.3     0.3    0.3

These results were generated from the variable access benchmark script at: Tools/scripts/var_access_benchmark.py. The benchmark script displays timings in nanoseconds. The benchmarks were measured on an Intel® Core™ i7-4960HQ processor [https://ark.intel.com/content/www/us/en/ark/products/76088/intel-core-i7-4960hq-processor-6m-cache-up-to-3-80-ghz.html] running the macOS 64-bit builds found at python.org [https://www.python.org/downloads/mac-osx/].

Deprecated

The distutils bdist_msi command is now deprecated, use bdist_wheel (wheel packages) instead. (Contributed by Hugo van Kemenade in bpo-39586 [https://bugs.python.org/issue?@action=redirect&bpo=39586].)

Currently math.factorial() accepts float instances with non-negative integer values (like 5.0). It raises a ValueError for non-integral and negative floats. It is now deprecated. In future Python versions it will raise a TypeError for all floats. (Contributed by Serhiy Storchaka in bpo-37315 [https://bugs.python.org/issue?@action=redirect&bpo=37315].)

The parser and symbol modules are deprecated and will be removed in future versions of Python. For the majority of use cases, users can leverage the Abstract Syntax Tree (AST) generation and compilation stage, using the ast module.

The Public C API functions PyParser_SimpleParseStringFlags(), PyParser_SimpleParseStringFlagsFilename(), PyParser_SimpleParseFileFlags() and PyNode_Compile() are deprecated and will be removed in Python 3.10 together with the old parser.

Using NotImplemented in a boolean context has been deprecated, as it is almost exclusively the result of incorrect rich comparator implementations. It will be made a TypeError in a future version of Python. (Contributed by Josh Rosenberg in bpo-35712 [https://bugs.python.org/issue?@action=redirect&bpo=35712].)

The random module currently accepts any hashable type as a possible seed value. Unfortunately, some of those types are not guaranteed to have a deterministic hash value. After Python 3.9, the module will restrict its seeds to None, int, float, str, bytes, and bytearray.

Opening the GzipFile file for writing without specifying the mode argument is deprecated. In future Python versions it will always be opened for reading by default. Specify the mode argument for opening it for writing and silencing a warning. (Contributed by Serhiy Storchaka in bpo-28286 [https://bugs.python.org/issue?@action=redirect&bpo=28286].)

Deprecated the split() method of _tkinter.TkappType in favour of the splitlist() method which has more consistent and predicable behavior. (Contributed by Serhiy Storchaka in bpo-38371 [https://bugs.python.org/issue?@action=redirect&bpo=38371].)

The explicit passing of coroutine objects to asyncio.wait() has been deprecated and will be removed in version 3.11. (Contributed by Yury Selivanov and Kyle Stanley in bpo-34790 [https://bugs.python.org/issue?@action=redirect&bpo=34790].)

binhex4 and hexbin4 standards are now deprecated. The binhex module and the following binascii functions are now deprecated:

b2a_hqx(), a2b_hqx()

rlecode_hqx(), rledecode_hqx()

(Contributed by Victor Stinner in bpo-39353 [https://bugs.python.org/issue?@action=redirect&bpo=39353].)

ast classes slice, Index and ExtSlice are considered deprecated and will be removed in future Python versions. value itself should be used instead of Index(value). Tuple(slices, Load()) should be used instead of ExtSlice(slices). (Contributed by Serhiy Storchaka in bpo-34822 [https://bugs.python.org/issue?@action=redirect&bpo=34822].)

ast classes Suite, Param, AugLoad and AugStore are considered deprecated and will be removed in future Python versions. They were not generated by the parser and not accepted by the code generator in Python 3. (Contributed by Batuhan Taskaya in bpo-39639 [https://bugs.python.org/issue?@action=redirect&bpo=39639] and bpo-39969 [https://bugs.python.org/issue?@action=redirect&bpo=39969] and Serhiy Storchaka in bpo-39988 [https://bugs.python.org/issue?@action=redirect&bpo=39988].)

The PyEval_InitThreads() and PyEval_ThreadsInitialized() functions are now deprecated and will be removed in Python 3.11. Calling PyEval_InitThreads() now does nothing. The GIL is initialized by Py_Initialize() since Python 3.7. (Contributed by Victor Stinner in bpo-39877 [https://bugs.python.org/issue?@action=redirect&bpo=39877].)

Passing None as the first argument to the shlex.split() function has been deprecated. (Contributed by Zackery Spytz in bpo-33262 [https://bugs.python.org/issue?@action=redirect&bpo=33262].)

smtpd.MailmanProxy() is now deprecated as it is unusable without an external module, mailman. (Contributed by Samuel Colvin in bpo-35800 [https://bugs.python.org/issue?@action=redirect&bpo=35800].)

The lib2to3 module now emits a PendingDeprecationWarning. Python 3.9 switched to a PEG parser (see PEP 617 [https://www.python.org/dev/peps/pep-0617]), and Python 3.10 may include new language syntax that is not parsable by lib2to3’s LL(1) parser. The lib2to3 module may be removed from the standard library in a future Python version. Consider third-party alternatives such as LibCST [https://libcst.readthedocs.io/] or parso [https://parso.readthedocs.io/]. (Contributed by Carl Meyer in bpo-40360 [https://bugs.python.org/issue?@action=redirect&bpo=40360].)

The random parameter of random.shuffle() has been deprecated. (Contributed by Raymond Hettinger in bpo-40465 [https://bugs.python.org/issue?@action=redirect&bpo=40465])

Removed

The erroneous version at unittest.mock.__version__ has been removed.

nntplib.NNTP: xpath() and xgtitle() methods have been removed. These methods are deprecated since Python 3.3. Generally, these extensions are not supported or not enabled by NNTP server administrators. For xgtitle(), please use nntplib.NNTP.descriptions() or nntplib.NNTP.description() instead. (Contributed by Dong-hee Na in bpo-39366 [https://bugs.python.org/issue?@action=redirect&bpo=39366].)

array.array: tostring() and fromstring() methods have been removed. They were aliases to tobytes() and frombytes(), deprecated since Python 3.2. (Contributed by Victor Stinner in bpo-38916 [https://bugs.python.org/issue?@action=redirect&bpo=38916].)

The undocumented sys.callstats() function has been removed. Since Python 3.7, it was deprecated and always returned None. It required a special build option CALL_PROFILE which was already removed in Python 3.7. (Contributed by Victor Stinner in bpo-37414 [https://bugs.python.org/issue?@action=redirect&bpo=37414].)

The sys.getcheckinterval() and sys.setcheckinterval() functions have been removed. They were deprecated since Python 3.2. Use sys.getswitchinterval() and sys.setswitchinterval() instead. (Contributed by Victor Stinner in bpo-37392 [https://bugs.python.org/issue?@action=redirect&bpo=37392].)

The C function PyImport_Cleanup() has been removed. It was documented as: «Empty the module table. For internal use only.» (Contributed by Victor Stinner in bpo-36710 [https://bugs.python.org/issue?@action=redirect&bpo=36710].)

_dummy_thread and dummy_threading modules have been removed. These modules were deprecated since Python 3.7 which requires threading support. (Contributed by Victor Stinner in bpo-37312 [https://bugs.python.org/issue?@action=redirect&bpo=37312].)

aifc.openfp() alias to aifc.open(), sunau.openfp() alias to sunau.open(), and wave.openfp() alias to wave.open() have been removed. They were deprecated since Python 3.7. (Contributed by Victor Stinner in bpo-37320 [https://bugs.python.org/issue?@action=redirect&bpo=37320].)

The isAlive() method of threading.Thread has been removed. It was deprecated since Python 3.8. Use is_alive() instead. (Contributed by Dong-hee Na in bpo-37804 [https://bugs.python.org/issue?@action=redirect&bpo=37804].)

Methods getchildren() and getiterator() of classes ElementTree and Element in the ElementTree module have been removed. They were deprecated in Python 3.2. Use iter(x) or list(x) instead of x.getchildren() and x.iter() or list(x.iter()) instead of x.getiterator(). (Contributed by Serhiy Storchaka in bpo-36543 [https://bugs.python.org/issue?@action=redirect&bpo=36543].)

The old plistlib API has been removed, it was deprecated since Python 3.4. Use the load(), loads(), dump(), and dumps() functions. Additionally, the use_builtin_types parameter was removed, standard bytes objects are always used instead. (Contributed by Jon Janzen in bpo-36409 [https://bugs.python.org/issue?@action=redirect&bpo=36409].)

The C function PyGen_NeedsFinalizing has been removed. It was not documented, tested, or used anywhere within CPython after the implementation of PEP 442 [https://www.python.org/dev/peps/pep-0442]. Patch by Joannah Nanjekye. (Contributed by Joannah Nanjekye in bpo-15088 [https://bugs.python.org/issue?@action=redirect&bpo=15088])

base64.encodestring() and base64.decodestring(), aliases deprecated since Python 3.1, have been removed: use base64.encodebytes() and base64.decodebytes() instead. (Contributed by Victor Stinner in bpo-39351 [https://bugs.python.org/issue?@action=redirect&bpo=39351].)

fractions.gcd() function has been removed, it was deprecated since Python 3.5 (bpo-22486 [https://bugs.python.org/issue?@action=redirect&bpo=22486]): use math.gcd() instead. (Contributed by Victor Stinner in bpo-39350 [https://bugs.python.org/issue?@action=redirect&bpo=39350].)

The buffering parameter of bz2.BZ2File has been removed. Since Python 3.0, it was ignored and using it emitted a DeprecationWarning. Pass an open file object to control how the file is opened. (Contributed by Victor Stinner in bpo-39357 [https://bugs.python.org/issue?@action=redirect&bpo=39357].)

The encoding parameter of json.loads() has been removed. As of Python 3.1, it was deprecated and ignored; using it has emitted a DeprecationWarning since Python 3.8. (Contributed by Inada Naoki in bpo-39377 [https://bugs.python.org/issue?@action=redirect&bpo=39377])

with (await asyncio.lock): and with (yield from asyncio.lock): statements are not longer supported, use async with lock instead. The same is correct for asyncio.Condition and asyncio.Semaphore. (Contributed by Andrew Svetlov in bpo-34793 [https://bugs.python.org/issue?@action=redirect&bpo=34793].)

The sys.getcounts() function, the -X showalloccount command line option and the show_alloc_count field of the C structure PyConfig have been removed. They required a special Python build by defining COUNT_ALLOCS macro. (Contributed by Victor Stinner in bpo-39489 [https://bugs.python.org/issue?@action=redirect&bpo=39489].)

The _field_types attribute of the typing.NamedTuple class has been removed. It was deprecated since Python 3.8. Use the __annotations__ attribute instead. (Contributed by Serhiy Storchaka in bpo-40182 [https://bugs.python.org/issue?@action=redirect&bpo=40182].)

The symtable.SymbolTable.has_exec() method has been removed. It was deprecated since 2006, and only returning False when it’s called. (Contributed by Batuhan Taskaya in bpo-40208 [https://bugs.python.org/issue?@action=redirect&bpo=40208])

The asyncio.Task.current_task() and asyncio.Task.all_tasks() have been removed. They were deprecated since Python 3.7 and you can use asyncio.current_task() and asyncio.all_tasks() instead. (Contributed by Rémi Lapeyre in bpo-40967 [https://bugs.python.org/issue?@action=redirect&bpo=40967])

The unescape() method in the html.parser.HTMLParser class has been removed (it was deprecated since Python 3.4). html.unescape() should be used for converting character references to the corresponding unicode characters.

Porting to Python 3.9

This section lists previously described changes and other bugfixes that may require changes to your code.

Changes in the Python API

__import__() and importlib.util.resolve_name() now raise ImportError where it previously raised ValueError. Callers catching the specific exception type and supporting both Python 3.9 and earlier versions will need to catch both using except (ImportError, ValueError):.

The venv activation scripts no longer special-case when __VENV_PROMPT__ is set to "".

The select.epoll.unregister() method no longer ignores the EBADF error. (Contributed by Victor Stinner in bpo-39239 [https://bugs.python.org/issue?@action=redirect&bpo=39239].)

The compresslevel parameter of bz2.BZ2File became keyword-only, since the buffering parameter has been removed. (Contributed by Victor Stinner in bpo-39357 [https://bugs.python.org/issue?@action=redirect&bpo=39357].)

Simplified AST for subscription. Simple indices will be represented by their value, extended slices will be represented as tuples. Index(value) will return a value itself, ExtSlice(slices) will return Tuple(slices, Load()). (Contributed by Serhiy Storchaka in bpo-34822 [https://bugs.python.org/issue?@action=redirect&bpo=34822].)

The importlib module now ignores the PYTHONCASEOK environment variable when the -E or -I command line options are being used.

The encoding parameter has been added to the classes ftplib.FTP and ftplib.FTP_TLS as a keyword-only parameter, and the default encoding is changed from Latin-1 to UTF-8 to follow RFC 2640 [https://tools.ietf.org/html/rfc2640.html].

asyncio.loop.shutdown_default_executor() has been added to AbstractEventLoop, meaning alternative event loops that inherit from it should have this method defined. (Contributed by Kyle Stanley in bpo-34037 [https://bugs.python.org/issue?@action=redirect&bpo=34037].)

The constant values of future flags in the __future__ module is updated in order to prevent collision with compiler flags. Previously PyCF_ALLOW_TOP_LEVEL_AWAIT was clashing with CO_FUTURE_DIVISION. (Contributed by Batuhan Taskaya in bpo-39562 [https://bugs.python.org/issue?@action=redirect&bpo=39562])

array('u') now uses wchar_t as C type instead of Py_UNICODE. This change doesn’t affect to its behavior because Py_UNICODE is alias of wchar_t since Python 3.3. (Contributed by Inada Naoki in bpo-34538 [https://bugs.python.org/issue?@action=redirect&bpo=34538].)

The logging.getLogger() API now returns the root logger when passed the name 'root', whereas previously it returned a non-root logger named 'root'. This could affect cases where user code explicitly wants a non-root logger named 'root', or instantiates a logger using logging.getLogger(__name__) in some top-level module called 'root.py'. (Contributed by Vinay Sajip in bpo-37742 [https://bugs.python.org/issue?@action=redirect&bpo=37742].)

Division handling of PurePath now returns NotImplemented instead of raising a TypeError when passed something other than an instance of str or PurePath. This allows creating compatible classes that don’t inherit from those mentioned types. (Contributed by Roger Aiudi in bpo-34775 [https://bugs.python.org/issue?@action=redirect&bpo=34775]).

Starting with Python 3.9.5 the ipaddress module no longer accepts any leading zeros in IPv4 address strings. Leading zeros are ambiguous and interpreted as octal notation by some libraries. For example the legacy function socket.inet_aton() treats leading zeros as octal notatation. glibc implementation of modern inet_pton() does not accept any leading zeros. (Contributed by Christian Heimes in bpo-36384 [https://bugs.python.org/issue?@action=redirect&bpo=36384]).

codecs.lookup() now normalizes the encoding name the same way as encodings.normalize_encoding(), except that codecs.lookup() also converts the name to lower case. For example, "latex+latin1" encoding name is now normalized to "latex_latin1". (Contributed by Jordon Xu in bpo-37751 [https://bugs.python.org/issue?@action=redirect&bpo=37751].)

Changes in the C API

Instances of heap-allocated types (such as those created with PyType_FromSpec() and similar APIs) hold a reference to their type object since Python 3.8. As indicated in the «Changes in the C API» of Python 3.8, for the vast majority of cases, there should be no side effect but for types that have a custom tp_traverse function, ensure that all custom tp_traverse functions of heap-allocated types visit the object’s type.

Example:

int
foo_traverse(foo_struct *self, visitproc visit, void *arg) {
// Rest of the traverse function
#if PY_VERSION_HEX >= 0x03090000
    // This was not needed before Python 3.9 (Python issue 35810 and 40217)
    Py_VISIT(Py_TYPE(self));
#endif
}

If your traverse function delegates to tp_traverse of its base class (or another type), ensure that Py_TYPE(self) is visited only once. Note that only heap types are expected to visit the type in tp_traverse.

For example, if your tp_traverse function includes:

base->tp_traverse(self, visit, arg)

then add:

#if PY_VERSION_HEX >= 0x03090000
    // This was not needed before Python 3.9 (Python issue 35810 and 40217)
    if (base->tp_flags & Py_TPFLAGS_HEAPTYPE) {
        // a heap type's tp_traverse already visited Py_TYPE(self)
    } else {
        Py_VISIT(Py_TYPE(self));
    }
#else

(See bpo-35810 [https://bugs.python.org/issue?@action=redirect&bpo=35810] and bpo-40217 [https://bugs.python.org/issue?@action=redirect&bpo=40217] for more information.)

The functions PyEval_CallObject, PyEval_CallFunction, PyEval_CallMethod and PyEval_CallObjectWithKeywords are deprecated. Use PyObject_Call() and its variants instead. (See more details in bpo-29548 [https://bugs.python.org/issue?@action=redirect&bpo=29548].)

CPython bytecode changes

The LOAD_ASSERTION_ERROR opcode was added for handling the assert statement. Previously, the assert statement would not work correctly if the AssertionError exception was being shadowed. (Contributed by Zackery Spytz in bpo-34880 [https://bugs.python.org/issue?@action=redirect&bpo=34880].)

The COMPARE_OP opcode was split into four distinct instructions:

COMPARE_OP for rich comparisons

IS_OP for “is” and “is not” tests

CONTAINS_OP for “in” and “not in” tests

JUMP_IF_NOT_EXC_MATCH for checking exceptions in “try-except” statements.

(Contributed by Mark Shannon in bpo-39156 [https://bugs.python.org/issue?@action=redirect&bpo=39156].)

Build Changes

Added --with-platlibdir option to the configure script: name of the platform-specific library directory, stored in the new sys.platlibdir attribute. See sys.platlibdir attribute for more information. (Contributed by Jan Matějek, Matěj Cepl, Charalampos Stratakis and Victor Stinner in bpo-1294959 [https://bugs.python.org/issue?@action=redirect&bpo=1294959].)

The COUNT_ALLOCS special build macro has been removed. (Contributed by Victor Stinner in bpo-39489 [https://bugs.python.org/issue?@action=redirect&bpo=39489].)

On non-Windows platforms, the setenv() and unsetenv() functions are now required to build Python. (Contributed by Victor Stinner in bpo-39395 [https://bugs.python.org/issue?@action=redirect&bpo=39395].)

On non-Windows platforms, creating bdist_wininst installers is now officially unsupported. (See bpo-10945 [https://bugs.python.org/issue?@action=redirect&bpo=10945] for more details.)

When building Python on macOS from source, _tkinter now links with non-system Tcl and Tk frameworks if they are installed in /Library/Frameworks, as had been the case on older releases of macOS. If a macOS SDK is explicitly configured, by using --enable-universalsdk= or -isysroot, only the SDK itself is searched. The default behavior can still be overridden with --with-tcltk-includes and --with-tcltk-libs. (Contributed by Ned Deily in bpo-34956 [https://bugs.python.org/issue?@action=redirect&bpo=34956].)

Python can now be built for Windows 10 ARM64. (Contributed by Steve Dower in bpo-33125 [https://bugs.python.org/issue?@action=redirect&bpo=33125].)

Some individual tests are now skipped when --pgo is used. The tests in question increased the PGO task time significantly and likely didn’t help improve optimization of the final executable. This speeds up the task by a factor of about 15x. Running the full unit test suite is slow. This change may result in a slightly less optimized build since not as many code branches will be executed. If you are willing to wait for the much slower build, the old behavior can be restored using ./configure [..] PROFILE_TASK="-m test --pgo-extended". We make no guarantees as to which PGO task set produces a faster build. Users who care should run their own relevant benchmarks as results can depend on the environment, workload, and compiler tool chain. (See bpo-36044 [https://bugs.python.org/issue?@action=redirect&bpo=36044] and bpo-37707 [https://bugs.python.org/issue?@action=redirect&bpo=37707] for more details.)

C API Changes

New Features

PEP 573 [https://www.python.org/dev/peps/pep-0573]: Added PyType_FromModuleAndSpec() to associate a module with a class; PyType_GetModule() and PyType_GetModuleState() to retrieve the module and its state; and PyCMethod and METH_METHOD to allow a method to access the class it was defined in. (Contributed by Marcel Plch and Petr Viktorin in bpo-38787 [https://bugs.python.org/issue?@action=redirect&bpo=38787].)

Added PyFrame_GetCode() function: get a frame code. Added PyFrame_GetBack() function: get the frame next outer frame. (Contributed by Victor Stinner in bpo-40421 [https://bugs.python.org/issue?@action=redirect&bpo=40421].)

Added PyFrame_GetLineNumber() to the limited C API. (Contributed by Victor Stinner in bpo-40421 [https://bugs.python.org/issue?@action=redirect&bpo=40421].)

Added PyThreadState_GetInterpreter() and PyInterpreterState_Get() functions to get the interpreter. Added PyThreadState_GetFrame() function to get the current frame of a Python thread state. Added PyThreadState_GetID() function: get the unique identifier of a Python thread state. (Contributed by Victor Stinner in bpo-39947 [https://bugs.python.org/issue?@action=redirect&bpo=39947].)

Added a new public PyObject_CallNoArgs() function to the C API, which calls a callable Python object without any arguments. It is the most efficient way to call a callable Python object without any argument. (Contributed by Victor Stinner in bpo-37194 [https://bugs.python.org/issue?@action=redirect&bpo=37194].)

Changes in the limited C API (if Py_LIMITED_API macro is defined):

Provide Py_EnterRecursiveCall() and Py_LeaveRecursiveCall() as regular functions for the limited API. Previously, there were defined as macros, but these macros didn’t compile with the limited C API which cannot access PyThreadState.recursion_depth field (the structure is opaque in the limited C API).

PyObject_INIT() and PyObject_INIT_VAR() become regular «opaque» function to hide implementation details.

(Contributed by Victor Stinner in bpo-38644 [https://bugs.python.org/issue?@action=redirect&bpo=38644] and bpo-39542 [https://bugs.python.org/issue?@action=redirect&bpo=39542].)

The PyModule_AddType() function is added to help adding a type to a module. (Contributed by Dong-hee Na in bpo-40024 [https://bugs.python.org/issue?@action=redirect&bpo=40024].)

Added the functions PyObject_GC_IsTracked() and PyObject_GC_IsFinalized() to the public API to allow to query if Python objects are being currently tracked or have been already finalized by the garbage collector respectively. (Contributed by Pablo Galindo Salgado in bpo-40241 [https://bugs.python.org/issue?@action=redirect&bpo=40241].)

Added _PyObject_FunctionStr() to get a user-friendly string representation of a function-like object. (Patch by Jeroen Demeyer in bpo-37645 [https://bugs.python.org/issue?@action=redirect&bpo=37645].)

Added PyObject_CallOneArg() for calling an object with one positional argument (Patch by Jeroen Demeyer in bpo-37483 [https://bugs.python.org/issue?@action=redirect&bpo=37483].)

Porting to Python 3.9

PyInterpreterState.eval_frame (PEP 523 [https://www.python.org/dev/peps/pep-0523]) now requires a new mandatory tstate parameter (PyThreadState*). (Contributed by Victor Stinner in bpo-38500 [https://bugs.python.org/issue?@action=redirect&bpo=38500].)

Extension modules: m_traverse, m_clear and m_free functions of PyModuleDef are no longer called if the module state was requested but is not allocated yet. This is the case immediately after the module is created and before the module is executed (Py_mod_exec function). More precisely, these functions are not called if m_size is greater than 0 and the module state (as returned by PyModule_GetState()) is NULL.

Extension modules without module state (m_size <= 0) are not affected.

If Py_AddPendingCall() is called in a subinterpreter, the function is now scheduled to be called from the subinterpreter, rather than being called from the main interpreter. Each subinterpreter now has its own list of scheduled calls. (Contributed by Victor Stinner in bpo-39984 [https://bugs.python.org/issue?@action=redirect&bpo=39984].)

The Windows registry is no longer used to initialize sys.path when the -E option is used (if PyConfig.use_environment is set to 0). This is significant when embedding Python on Windows. (Contributed by Zackery Spytz in bpo-8901 [https://bugs.python.org/issue?@action=redirect&bpo=8901].)

The global variable PyStructSequence_UnnamedField is now a constant and refers to a constant string. (Contributed by Serhiy Storchaka in bpo-38650 [https://bugs.python.org/issue?@action=redirect&bpo=38650].)

The PyGC_Head structure is now opaque. It is only defined in the internal C API (pycore_gc.h). (Contributed by Victor Stinner in bpo-40241 [https://bugs.python.org/issue?@action=redirect&bpo=40241].)

The Py_UNICODE_COPY, Py_UNICODE_FILL, PyUnicode_WSTR_LENGTH, PyUnicode_FromUnicode(), PyUnicode_AsUnicode(), _PyUnicode_AsUnicode, and PyUnicode_AsUnicodeAndSize() are marked as deprecated in C. They have been deprecated by PEP 393 [https://www.python.org/dev/peps/pep-0393] since Python 3.3. (Contributed by Inada Naoki in bpo-36346 [https://bugs.python.org/issue?@action=redirect&bpo=36346].)

The Py_FatalError() function is replaced with a macro which logs automatically the name of the current function, unless the Py_LIMITED_API macro is defined. (Contributed by Victor Stinner in bpo-39882 [https://bugs.python.org/issue?@action=redirect&bpo=39882].)

The vectorcall protocol now requires that the caller passes only strings as keyword names. (See bpo-37540 [https://bugs.python.org/issue?@action=redirect&bpo=37540] for more information.)

Implementation details of a number of macros and functions are now hidden:

PyObject_IS_GC() macro was converted to a function.

The PyObject_NEW() macro becomes an alias to the PyObject_New() macro, and the PyObject_NEW_VAR() macro becomes an alias to the PyObject_NewVar() macro. They no longer access directly the PyTypeObject.tp_basicsize member.

PyObject_GET_WEAKREFS_LISTPTR() macro was converted to a function: the macro accessed directly the PyTypeObject.tp_weaklistoffset member.

PyObject_CheckBuffer() macro was converted to a function: the macro accessed directly the PyTypeObject.tp_as_buffer member.

PyIndex_Check() is now always declared as an opaque function to hide implementation details: removed the PyIndex_Check() macro. The macro accessed directly the PyTypeObject.tp_as_number member.

(See bpo-40170 [https://bugs.python.org/issue?@action=redirect&bpo=40170] for more details.)

Removed

Excluded PyFPE_START_PROTECT() and PyFPE_END_PROTECT() macros of pyfpe.h from the limited C API. (Contributed by Victor Stinner in bpo-38835 [https://bugs.python.org/issue?@action=redirect&bpo=38835].)

The tp_print slot of PyTypeObject has been removed. It was used for printing objects to files in Python 2.7 and before. Since Python 3.0, it has been ignored and unused. (Contributed by Jeroen Demeyer in bpo-36974 [https://bugs.python.org/issue?@action=redirect&bpo=36974].)

Changes in the limited C API (if Py_LIMITED_API macro is defined):

Excluded the following functions from the limited C API:

PyThreadState_DeleteCurrent() (Contributed by Joannah Nanjekye in bpo-37878 [https://bugs.python.org/issue?@action=redirect&bpo=37878].)

_Py_CheckRecursionLimit

_Py_NewReference()

_Py_ForgetReference()

_PyTraceMalloc_NewReference()

_Py_GetRefTotal()

The trashcan mechanism which never worked in the limited C API.

PyTrash_UNWIND_LEVEL

Py_TRASHCAN_BEGIN_CONDITION

Py_TRASHCAN_BEGIN

Py_TRASHCAN_END

Py_TRASHCAN_SAFE_BEGIN

Py_TRASHCAN_SAFE_END

Moved following functions and definitions to the internal C API:

_PyDebug_PrintTotalRefs()

_Py_PrintReferences()

_Py_PrintReferenceAddresses()

_Py_tracemalloc_config

_Py_AddToAllObjects() (specific to Py_TRACE_REFS build)

(Contributed by Victor Stinner in bpo-38644 [https://bugs.python.org/issue?@action=redirect&bpo=38644] and bpo-39542 [https://bugs.python.org/issue?@action=redirect&bpo=39542].)

Removed _PyRuntime.getframe hook and removed _PyThreadState_GetFrame macro which was an alias to _PyRuntime.getframe. They were only exposed by the internal C API. Removed also PyThreadFrameGetter type. (Contributed by Victor Stinner in bpo-39946 [https://bugs.python.org/issue?@action=redirect&bpo=39946].)

Removed the following functions from the C API. Call PyGC_Collect() explicitly to clear all free lists. (Contributed by Inada Naoki and Victor Stinner in bpo-37340 [https://bugs.python.org/issue?@action=redirect&bpo=37340], bpo-38896 [https://bugs.python.org/issue?@action=redirect&bpo=38896] and bpo-40428 [https://bugs.python.org/issue?@action=redirect&bpo=40428].)

PyAsyncGen_ClearFreeLists()

PyContext_ClearFreeList()

PyDict_ClearFreeList()

PyFloat_ClearFreeList()

PyFrame_ClearFreeList()

PyList_ClearFreeList()

PyMethod_ClearFreeList() and PyCFunction_ClearFreeList(): the free lists of bound method objects have been removed.

PySet_ClearFreeList(): the set free list has been removed in Python 3.4.

PyTuple_ClearFreeList()

PyUnicode_ClearFreeList(): the Unicode free list has been removed in Python 3.3.

Removed _PyUnicode_ClearStaticStrings() function. (Contributed by Victor Stinner in bpo-39465 [https://bugs.python.org/issue?@action=redirect&bpo=39465].)

Removed Py_UNICODE_MATCH. It has been deprecated by PEP 393 [https://www.python.org/dev/peps/pep-0393], and broken since Python 3.3. The PyUnicode_Tailmatch() function can be used instead. (Contributed by Inada Naoki in bpo-36346 [https://bugs.python.org/issue?@action=redirect&bpo=36346].)

Cleaned header files of interfaces defined but with no implementation. The public API symbols being removed are: _PyBytes_InsertThousandsGroupingLocale, _PyBytes_InsertThousandsGrouping, _Py_InitializeFromArgs, _Py_InitializeFromWideArgs, _PyFloat_Repr, _PyFloat_Digits, _PyFloat_DigitsInit, PyFrame_ExtendStack, _PyAIterWrapper_Type, PyNullImporter_Type, PyCmpWrapper_Type, PySortWrapper_Type, PyNoArgsFunction. (Contributed by Pablo Galindo Salgado in bpo-39372 [https://bugs.python.org/issue?@action=redirect&bpo=39372].)

Notable changes in Python 3.9.1

typing

The behavior of typing.Literal was changed to conform with PEP 586 [https://www.python.org/dev/peps/pep-0586] and to match the behavior of static type checkers specified in the PEP.

Literal now de-duplicates parameters.

Equality comparisons between Literal objects are now order independent.

Literal comparisons now respect types. For example, Literal[0] == Literal[False] previously evaluated to True. It is now False. To support this change, the internally used type cache now supports differentiating types.

Literal objects will now raise a TypeError exception during equality comparisons if any of their parameters are not hashable. Note that declaring Literal with mutable parameters will not throw an error:

>>> from typing import Literal
>>> Literal[{0}]
>>> Literal[{0}] == Literal[{False}]
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: unhashable type: 'set'

(Contributed by Yurii Karabas in bpo-42345 [https://bugs.python.org/issue?@action=redirect&bpo=42345].)

macOS 11.0 (Big Sur) and Apple Silicon Mac support

As of 3.9.1, Python now fully supports building and running on macOS 11.0 (Big Sur) and on Apple Silicon Macs (based on the ARM64 architecture). A new universal build variant, universal2, is now available to natively support both ARM64 and Intel 64 in one set of executables. Binaries can also now be built on current versions of macOS to be deployed on a range of older macOS versions (tested to 10.9) while making some newer OS functions and options conditionally available based on the operating system version in use at runtime («weaklinking»).

(Contributed by Ronald Oussoren and Lawrence D’Anna in bpo-41100 [https://bugs.python.org/issue?@action=redirect&bpo=41100].)

Notable changes in Python 3.9.2

collections.abc

collections.abc.Callable generic now flattens type parameters, similar to what typing.Callable currently does. This means that collections.abc.Callable[[int, str], str] will have __args__ of (int, str, str); previously this was ([int, str], str). To allow this change, types.GenericAlias can now be subclassed, and a subclass will be returned when subscripting the collections.abc.Callable type. Code which accesses the arguments via typing.get_args() or __args__ need to account for this change. A DeprecationWarning may be emitted for invalid forms of parameterizing collections.abc.Callable which may have passed silently in Python 3.9.1. This DeprecationWarning will become a TypeError in Python 3.10. (Contributed by Ken Jin in bpo-42195 [https://bugs.python.org/issue?@action=redirect&bpo=42195].)

urllib.parse

Earlier Python versions allowed using both ; and & as query parameter separators in urllib.parse.parse_qs() and urllib.parse.parse_qsl(). Due to security concerns, and to conform with newer W3C recommendations, this has been changed to allow only a single separator key, with & as the default. This change also affects cgi.parse() and cgi.parse_multipart() as they use the affected functions internally. For more details, please see their respective documentation. (Contributed by Adam Goldschmidt, Senthil Kumaran and Ken Jin in bpo-42967 [https://bugs.python.org/issue?@action=redirect&bpo=42967].)

Notable changes in Python 3.9.3

A security fix alters the ftplib.FTP behavior to not trust the IPv4 address sent from the remote server when setting up a passive data channel. We reuse the ftp server IP address instead. For unusual code requiring the old behavior, set a trust_server_pasv_ipv4_address attribute on your FTP instance to True. (See bpo-43285 [https://bugs.python.org/issue?@action=redirect&bpo=43285])

Notable changes in Python 3.9.5

urllib.parse

The presence of newline or tab characters in parts of a URL allows for some forms of attacks. Following the WHATWG specification that updates RFC 3986 [https://tools.ietf.org/html/rfc3986.html], ASCII newline \n, \r and tab \t characters are stripped from the URL by the parser in urllib.parse preventing such attacks. The removal characters are controlled by a new module level variable urllib.parse._UNSAFE_URL_BYTES_TO_REMOVE. (See bpo-43882 [https://bugs.python.org/issue?@action=redirect&bpo=43882])

Notable security feature in 3.9.14

Converting between int and str in bases other than 2 (binary), 4, 8 (octal), 16 (hexadecimal), or 32 such as base 10 (decimal) now raises a ValueError if the number of digits in string form is above a limit to avoid potential denial of service attacks due to the algorithmic complexity. This is a mitigation for CVE-2020-10735 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-10735]. This limit can be configured or disabled by environment variable, command line flag, or sys APIs. See the integer string conversion length limitation documentation. The default limit is 4300 digits in string form.

Notable Changes in 3.9.17

tarfile

The extraction methods in tarfile, and shutil.unpack_archive(), have a new a filter argument that allows limiting tar features than may be surprising or dangerous, such as creating files outside the destination directory. See Extraction filters for details. In Python 3.12, use without the filter argument will show a DeprecationWarning. In Python 3.14, the default will switch to 'data'. (Contributed by Petr Viktorin in PEP 706 [https://www.python.org/dev/peps/pep-0706].)

Qué hay de nuevo en Python 3.8

Editor

Raymond Hettinger

Este artículo explica las nuevas características de Python 3.8, en comparación con 3.7. Para obtener los detalles completos, consultar el registro de cambios.

Resumen – Aspectos destacados de la versión

Nuevas características

Expresiones de asignación

La nueva sintaxis := asigna valores a variables como parte de una expresión más grande. Se le conoce cariñosamente como «el operador morsa» debido a su parecido con los ojos y colmillos de una morsa [https://en.wikipedia.org/wiki/Walrus#/media/File:Pacific_Walrus_-_Bull_(8247646168).jpg].

En el siguiente ejemplo, la expresión de asignación ayuda evitando que se tenga que llamar a len() dos veces:

if (n := len(a)) > 10:
    print(f"List is too long ({n} elements, expected <= 10)")

Un beneficio similar surge durante la búsqueda de coincidencias mediante expresiones regulares donde los objetos de coincidencias se necesitan dos veces, una para comprobar si se produjo una coincidencia y otra para extraer un subgrupo:

discount = 0.0
if (mo := re.search(r'(\d+)% discount', advertisement)):
    discount = float(mo.group(1)) / 100.0

El operador también es útil en bucles while que calculan un valor para comprobar la terminación del bucle y posteriormente necesitan nuevamente ese mismo valor en el cuerpo del bucle:

# Loop over fixed length blocks
while (block := f.read(256)) != '':
    process(block)

Otra motivación de uso surge en las listas por comprensión en las que un valor calculado en una condición de filtrado también se necesita en el cuerpo de la expresión:

[clean_name.title() for name in names
 if (clean_name := normalize('NFC', name)) in allowed_names]

Intenta limitar el uso del «operador morsa» a aquellos casos en los que reduce la complejidad y mejora la legibilidad del código.

Consultar PEP 572 [https://www.python.org/dev/peps/pep-0572] para obtener una descripción completa.

(Contribución de Emily Morehouse en bpo-35224 [https://bugs.python.org/issue?@action=redirect&bpo=35224].)

Parámetros solo posicionales

Hay una nueva sintaxis para establecer parámetro de función, /, para indicar que algunos parámetros de función deben especificarse solo posicionalmente y no pueden usarse como argumentos por palabra clave. Esta es la misma notación que muestra help() para las funciones de C anotadas con la herramienta Argument Clinic [https://docs.python.org/3/howto/clinic.html] de Larry Hastings.

En el siguiente ejemplo, los parámetros a y b son solo posicionales, mientras que c o d pueden ser posicionales o por palabra clave y e o f deben proporcionarse por palabra clave exclusivamente:

def f(a, b, /, c, d, *, e, f):
    print(a, b, c, d, e, f)

La siguiente es una invocación válida:

f(10, 20, 30, d=40, e=50, f=60)

Sin embargo, estas son invocaciones inválidas:

f(10, b=20, c=30, d=40, e=50, f=60)   # b cannot be a keyword argument
f(10, 20, 30, 40, 50, f=60)           # e must be a keyword argument

Un caso de uso de esta notación es permitir que las funciones puras de Python emulen completamente los comportamientos de las funciones codificadas en C existentes. Por ejemplo, la función incorporada divmod() no acepta argumentos por palabra clave:

def divmod(a, b, /):
    "Emulate the built in divmod() function"
    return (a // b, a % b)

Otro caso de uso es excluir los argumentos por palabra clave cuando el nombre del parámetro no es útil. Por ejemplo, la función incorporada len() tiene la firma len(obj, /). Esto excluye llamadas inoportunas como:

len(obj='hello')  # The "obj" keyword argument impairs readability

Un beneficio adicional de marcar un parámetro como solo posicional es que permite cambiar el nombre del parámetro en el futuro sin riesgo de romper el código del cliente. Por ejemplo, en el módulo statistics, el nombre del parámetro dist puede cambiarse en el futuro. Esto es posible gracias a la siguiente especificación de función:

def quantiles(dist, /, *, n=4, method='exclusive')
    ...

Dado que los parámetros a la izquierda de / no se exponen como posibles palabras clave, los nombres de los parámetros permanecen disponibles para su uso en **kwargs:

>>> def f(a, b, /, **kwargs):
...     print(a, b, kwargs)
...
>>> f(10, 20, a=1, b=2, c=3)         # a and b are used in two ways
10 20 {'a': 1, 'b': 2, 'c': 3}

Esto simplifica enormemente la implementación de funciones y métodos que necesitan aceptar argumentos por palabra clave arbitrarios. Por ejemplo, aquí hay un extracto del código del módulo collections:

class Counter(dict):

    def __init__(self, iterable=None, /, **kwds):
        # Note "iterable" is a possible keyword argument

Consultar PEP 570 [https://www.python.org/dev/peps/pep-0570] para obtener una descripción completa.

(Contribución de Pablo Galindo en bpo-36540 [https://bugs.python.org/issue?@action=redirect&bpo=36540].)

Caché del sistema de archivos paralelo para archivos de bytecode compilados

La nueva configuración PYTHONPYCACHEPREFIX (también disponible mediante la opción -X pycache_prefix) configura la caché implícita de bytecode para que use un árbol del sistema de archivos paralelo separado, en lugar de los subdirectorios __pycache__ predeterminados dentro cada directorio de origen.

La ubicación de la caché se define en sys.pycache_prefix (None indica la ubicación predeterminada en los subdirectorios __pycache__).

(Contribución de Carl Meyer en bpo-33499 [https://bugs.python.org/issue?@action=redirect&bpo=33499].)

La compilación de depuración usa la misma ABI que la compilación de lanzamiento

Python ahora usa la misma ABI, independientemente de que esté compilado en modo de lanzamiento o de depuración. En Unix, cuando Python se compila en modo de depuración, ahora es posible cargar extensiones C compiladas en modo de lanzamiento y extensiones C compiladas usando la ABI estable.

Las versiones de lanzamiento y las versiones de depuración ahora son ABI compatibles: definir la macro Py_DEBUG ya no implica la macro Py_TRACE_REFS, que introducía la única incompatibilidad de la ABI. La macro Py_TRACE_REFS, que agrega la función sys.getobjects() y la variable de entorno PYTHONDUMPREFS, se puede establecer usando la nueva opción de compilación ./configure --with-trace-refs. (Contribución de Victor Stinner en bpo-36465 [https://bugs.python.org/issue?@action=redirect&bpo=36465].)

En Unix, las extensiones en C ya no están enlazadas a libpython, excepto en Android y Cygwin. Ahora es posible que un intérprete Python enlazado estáticamente cargue una extensión de C creada con una biblioteca dinámica de Python. (Contribución de Victor Stinner en bpo-21536 [https://bugs.python.org/issue?@action=redirect&bpo=21536].)

En Unix, cuando Python se compila en modo de depuración, la importación ahora también busca extensiones C compiladas en modo de lanzamiento y extensiones C compiladas con la ABI estable. (Contribución de Victor Stinner en bpo-36722 [https://bugs.python.org/issue?@action=redirect&bpo=36722].)

Para integrar Python en una aplicación, se debe pasar una nueva opción --embed a python3-config --libs --embed para obtener -lpython3.8 (enlaza la aplicación a libpython ). Para ser compatible con 3.8 y versiones anteriores, prueba primero con python3-config --libs --embed y vuelve a usar python3-config --libs (sin --embed) si falla el comando anterior.

Agrega un módulo pkg-config python-3.8-embed para integrar Python en una aplicación: pkg-config python-3.8-embed --libs incluye -lpython3.8. Para que sea compatible con 3.8 y versiones anteriores, primero intenta usar pkg-config python-X.Y-embed --libs y vuelve a pkg-config python-X.Y --libs (sin --embed) si el comando anterior falla (reemplaza XY con la versión de Python).

Por otro lado, pkg-config python3.8 --libs ya no contiene -lpython3.8. Las extensiones en C no deben estar enlazadas a libpython (excepto en Android y Cygwin, cuyos casos son manejados por el script); este cambio no es retrocompatible a propósito. (Contribución de Victor Stinner en bpo-36721 [https://bugs.python.org/issue?@action=redirect&bpo=36721].)

los f-strings soportan = para expresiones autodocumentadas y depuración

Se ha agregado un especificador = a los f-strings. Un f-string como f'{expr=}' se expandirá al texto de la expresión, seguido de un signo igual y luego la representación de la expresión evaluada. Por ejemplo:

>>> user = 'eric_idle'
>>> member_since = date(1975, 7, 31)
>>> f'{user=} {member_since=}'
"user='eric_idle' member_since=datetime.date(1975, 7, 31)"

Los especificadores de formato de los f-string usuales permiten un mayor control sobre como se muestra el resultado de la expresión:

>>> delta = date.today() - member_since
>>> f'{user=!s}  {delta.days=:,d}'
'user=eric_idle  delta.days=16,075'

El especificador = mostrará la expresión completa para que se puedan mostrar los cálculos:

>>> print(f'{theta=}  {cos(radians(theta))=:.3f}')
theta=30  cos(radians(theta))=0.866

(Contribución de Eric V. Smith y Larry Hastings en bpo-36817 [https://bugs.python.org/issue?@action=redirect&bpo=36817].)

PEP 578: Ganchos de auditoría en tiempo de ejecución de Python

Este PEP agrega un gancho de auditoría y un gancho abierto verificado. Ambos están disponibles desde Python y desde el código nativo, lo que permite que las aplicaciones y los frameworks escritos en código Python puro aprovechen las notificaciones adicionales, al tiempo que permiten a los integradores o administradores de sistemas implementar compilaciones de Python donde la auditoría siempre está habilitada.

Consultar PEP 578 [https://www.python.org/dev/peps/pep-0578] para obtener más detalles.

PEP 587: Configuración de inicialización de Python

El PEP 587 [https://www.python.org/dev/peps/pep-0587] agrega una nueva API de C para configurar la inicialización de Python, proporcionando un control más preciso de toda la configuración y mejores informes de errores.

Nuevas estructuras:

PyConfig

PyPreConfig

PyStatus

PyWideStringList

Nuevas funciones:

PyConfig_Clear()

PyConfig_InitIsolatedConfig()

PyConfig_InitPythonConfig()

PyConfig_Read()

PyConfig_SetArgv()

PyConfig_SetBytesArgv()

PyConfig_SetBytesString()

PyConfig_SetString()

PyPreConfig_InitIsolatedConfig()

PyPreConfig_InitPythonConfig()

PyStatus_Error()

PyStatus_Exception()

PyStatus_Exit()

PyStatus_IsError()

PyStatus_IsExit()

PyStatus_NoMemory()

PyStatus_Ok()

PyWideStringList_Append()

PyWideStringList_Insert()

Py_BytesMain()

Py_ExitStatusException()

Py_InitializeFromConfig()

Py_PreInitialize()

Py_PreInitializeFromArgs()

Py_PreInitializeFromBytesArgs()

Py_RunMain()

Este PEP también agrega los campos _PyRuntimeState.preconfig (tipo PyPreConfig) y PyInterpreterState.config (tipo PyConfig) a estas estructuras internas. PyInterpreterState.config se convierte en la nueva configuración de referencia, reemplazando las variables de configuración globales y otras variables privadas.

Consultar Configuración de inicialización de Python para la documentación.

Consultar PEP 587 [https://www.python.org/dev/peps/pep-0587] para obtener una descripción completa.

(Contribución de Victor Stinner en bpo-36763 [https://bugs.python.org/issue?@action=redirect&bpo=36763].)

PEP 590: Vectorcall: un protocolo de llamada rápida para CPython

El protocolo vectorcall se agrega a la API de Python/C. Está destinado a formalizar las optimizaciones existentes que ya se realizaron para varias clases. Cualquier tipo estático que implemente un invocable puede utilizar este protocolo.

Actualmente es provisional. El objetivo es hacerlo completamente público en Python 3.9.

Consultar PEP 590 [https://www.python.org/dev/peps/pep-0590] para obtener una descripción completa.

(Contribución de Jeroen Demeyer, Mark Shannon y Petr Viktorin en bpo-36974 [https://bugs.python.org/issue?@action=redirect&bpo=36974].)

Protocolo 5 de Pickle con búferes de datos fuera de banda

Cuando pickle se usa para transferir grandes cantidades de datos entre procesos de Python, con la finalidad de aprovechar el procesamiento de múltiples núcleos o máquinas, es importante optimizar la transferencia reduciendo las copias en memoria y posiblemente aplicando técnicas personalizadas, como la compresión dependiente de datos.

El protocolo 5 de pickle introduce soporte para búferes fuera de banda, donde los datos compatibles con PEP 3118 [https://www.python.org/dev/peps/pep-3118] se pueden transmitir separados del flujo principal de pickle, a discreción de la capa de comunicación.

Consultar PEP 574 [https://www.python.org/dev/peps/pep-0574] para obtener una descripción completa.

(Contribución de Antoine Pitrou en bpo-36785 [https://bugs.python.org/issue?@action=redirect&bpo=36785].)

Otros cambios en el lenguaje

La declaración continue era ilegal en la cláusula finally debido a un problema con la implementación. En Python 3.8 se ha eliminado esta restricción. (Contribución de Serhiy Storchaka en bpo-32489 [https://bugs.python.org/issue?@action=redirect&bpo=32489].)

Los tipos bool, int y fractions.Fraction ahora tienen un método as_integer_ratio() como el que se encuentra en float y decimal.Decimal. Esta extensión menor de la API hace posible escribir numerator, denominator = x.as_integer_ratio() y hacer que funcione con múltiples tipos numéricos. (Contribución de Lisa Roach en bpo-33073 [https://bugs.python.org/issue?@action=redirect&bpo=33073] y de Raymond Hettinger en bpo-37819 [https://bugs.python.org/issue?@action=redirect&bpo=37819].)

Los constructores de int, float y complex ahora usarán el método especial __index__(), si está disponible y el método correspondiente __int__(), __float__() o __complex__() no está disponible. (Contribución de Serhiy Storchaka en bpo-20092 [https://bugs.python.org/issue?@action=redirect&bpo=20092].)

Agregado soporte para escapes \N{name} en expresiones regulares:

>>> notice = 'Copyright © 2019'
>>> copyright_year_pattern = re.compile(r'\N{copyright sign}\s*(\d{4})')
>>> int(copyright_year_pattern.search(notice).group(1))
2019

(Contribución de Jonathan Eunice y Serhiy Storchaka in bpo-30688 [https://bugs.python.org/issue?@action=redirect&bpo=30688].)

Los diccionarios y sus vistas ahora se pueden iterar en orden inverso de inserción usando reversed(). (Contribución de Rémi Lapeyre en bpo-33462 [https://bugs.python.org/issue?@action=redirect&bpo=33462].)

La sintaxis permitida para los nombres por palabra clave en las llamadas a funciones se ha restringido aún más. En particular, f((keyword)=arg) ya no está permitido. Nunca se tuvo intención de permitir algo más que un simple nombre en el lado izquierdo de un término de asignación de argumento por palabra clave. (Contribución de Benjamin Peterson en bpo-34641 [https://bugs.python.org/issue?@action=redirect&bpo=34641].)

El desempaquetado de iterables generalizado en declaraciones yield y return ya no requiere ser encerrado entre paréntesis. Esto hace que la sintaxis de yield y return se asemeje más a la sintaxis normal de asignación:

>>> def parse(family):
        lastname, *members = family.split()
        return lastname.upper(), *members

>>> parse('simpsons homer marge bart lisa maggie')
('SIMPSONS', 'homer', 'marge', 'bart', 'lisa', 'maggie')

(Contribución de David Cuthbert y Jordan Chapman en bpo-32117 [https://bugs.python.org/issue?@action=redirect&bpo=32117].)

Cuando falta una coma en el código, como en [(10, 20) (30, 40)], el compilador muestra un SyntaxWarning con una sugerencia útil. Esto representa una mejora con respecto a la implementación previa en la que solo se mostraba un TypeError indicando que la primera tupla no era invocable. (Contribución de Serhiy Storchaka en bpo-15248 [https://bugs.python.org/issue?@action=redirect&bpo=15248].)

Las operaciones aritméticas entre subclases de datetime.date o datetime.datetime y datetime.timedelta ahora retornan una instancia de la subclase, en lugar de la clase base. Esto también afecta al tipo de retorno de las operaciones cuya implementación (directa o indirectamente) usa la aritmética de datetime.timedelta, como astimezone(). (Contribución de Paul Ganssle en bpo-32417 [https://bugs.python.org/issue?@action=redirect&bpo=32417].)

Cuando el intérprete de Python es interrumpido por Ctrl-C (SIGINT) y la excepción KeyboardInterrupt resultante no se detecta, el proceso de Python ahora termina su ejecución a través de una señal SIGINT o con el código de salida correcto, de modo que el proceso que lo invocó puede detectar que murió debido a Ctrl-C. Los shells en POSIX y Windows usan esto para terminar la ejecución de los scripts en sesiones interactivas de forma correcta. (Contribución de Google a través de Gregory P. Smith en bpo-1054041 [https://bugs.python.org/issue?@action=redirect&bpo=1054041].)

Algunos estilos de programación avanzados requieren actualizar el objeto types.CodeType para una función ya existente. Dado que los objetos de código son inmutables, es necesario crear un nuevo objeto de código, que sea modelado a partir del objeto de código existente. Con 19 parámetros, esto era algo tedioso. Ahora, el nuevo método replace() hace posible crear un clon con algunos parámetros alterados.

Aquí hay un ejemplo que modifica la función statistics.mean() para evitar que el parámetro data se use como un argumento por palabra clave:

>>> from statistics import mean
>>> mean(data=[10, 20, 90])
40
>>> mean.__code__ = mean.__code__.replace(co_posonlyargcount=1)
>>> mean(data=[10, 20, 90])
Traceback (most recent call last):
  ...
TypeError: mean() got some positional-only arguments passed as keyword arguments: 'data'

(Contribución de Victor Stinner en bpo-37032 [https://bugs.python.org/issue?@action=redirect&bpo=37032].)

Para enteros, la forma de tres argumentos de la función pow() ahora permite que el exponente sea negativo en el caso de que la base y el módulo sean primos relativos (coprimos). Luego calcula un inverso modular a la base cuando el exponente es -1 y una potencia adecuada de ese inverso en el caso de otros exponentes negativos. Por ejemplo, para calcular el inverso multiplicativo [https://es.wikipedia.org/wiki/Inverso_multiplicativo_(aritm%C3%A9tica_modular)] de 38 módulo 137, escribe:

>>> pow(38, -1, 137)
119
>>> 119 * 38 % 137
1

Los inversos modulares surgen de la solución de ecuaciones diofánticas lineales [https://es.wikipedia.org/wiki/Ecuaci%C3%B3n_diof%C3%A1ntica]. Por ejemplo, para encontrar soluciones enteras para 4258𝑥 + 147𝑦 = 369, primero debes reescribirla como 4258𝑥 ≡ 369 (mod 147) y luego resolver:

>>> x = 369 * pow(4258, -1, 147) % 147
>>> y = (4258 * x - 369) // -147
>>> 4258 * x + 147 * y
369

(Contribución de Mark Dickinson en bpo-36027 [https://bugs.python.org/issue?@action=redirect&bpo=36027].)

Las compresiones de diccionarios se han sincronizado con los literales de diccionario para que primero se calcule la clave y posteriormente el valor:

>>> # Dict comprehension
>>> cast = {input('role? '): input('actor? ') for i in range(2)}
role? King Arthur
actor? Chapman
role? Black Knight
actor? Cleese

>>> # Dict literal
>>> cast = {input('role? '): input('actor? ')}
role? Sir Robin
actor? Eric Idle

Este orden de ejecución garantizado es especialmente útil en las expresiones de asignación porque las variables asignadas en la expresión de la clave estarán disponibles en la expresión del valor:

>>> names = ['Martin von Löwis', 'Łukasz Langa', 'Walter Dörwald']
>>> {(n := normalize('NFC', name)).casefold() : n for name in names}
{'martin von löwis': 'Martin von Löwis',
 'łukasz langa': 'Łukasz Langa',
 'walter dörwald': 'Walter Dörwald'}

(Contribución de Jörn Heissler en bpo-35224 [https://bugs.python.org/issue?@action=redirect&bpo=35224].)

El método object.__reduce__() ahora puede retornar una tupla con una longitud que va desde los dos a los seis elementos. Anteriormente, el límite era cinco. El nuevo sexto elemento opcional es un invocable con una firma (obj, state). Esto permite el control directo sobre el comportamiento de actualización de estado de un objeto específico. Si no es None, este invocable tendrá prioridad sobre el método __setstate__() del objeto. (Contribución de Pierre Glaser y Olivier Grisel en bpo-35900 [https://bugs.python.org/issue?@action=redirect&bpo=35900].)

Nuevos módulos

El nuevo módulo importlib.metadata proporciona soporte (provisional) para leer metadatos de paquetes de terceros. Por ejemplo, puede extraer el número de versión de un paquete instalado, la lista de puntos de entrada y más:

>>> # Note following example requires that the popular "requests"
>>> # package has been installed.
>>>
>>> from importlib.metadata import version, requires, files
>>> version('requests')
'2.22.0'
>>> list(requires('requests'))
['chardet (<3.1.0,>=3.0.2)']
>>> list(files('requests'))[:5]
[PackagePath('requests-2.22.0.dist-info/INSTALLER'),
 PackagePath('requests-2.22.0.dist-info/LICENSE'),
 PackagePath('requests-2.22.0.dist-info/METADATA'),
 PackagePath('requests-2.22.0.dist-info/RECORD'),
 PackagePath('requests-2.22.0.dist-info/WHEEL')]

(Contribución de Barry Warsaw y Jason R. Coombs en bpo-34632 [https://bugs.python.org/issue?@action=redirect&bpo=34632].)

Módulos mejorados

ast

Los nodos de AST ahora disponen de los atributos end_lineno y end_col_offset, que proporcionan la localización precisa del final del nodo. (Esto solo se aplica a los nodos que tienen los atributos lineno y col_offset.)

La nueva función ast.get_source_segment() retorna el código fuente de un nodo AST específico.

(Contribución de Ivan Levkivskyi en bpo-33416 [https://bugs.python.org/issue?@action=redirect&bpo=33416].)

La función ast.parse() tiene algunos flags nuevos:

type_comments=True causa que la función retorne el texto de los comentarios de tipo especificados en PEP 484 [https://www.python.org/dev/peps/pep-0484] y PEP 526 [https://www.python.org/dev/peps/pep-0526] asociados con ciertos nodos AST;

mode='func_type' puede usarse para realizar un análisis sintáctico de los «comentarios de tipo de firma» de PEP 484 [https://www.python.org/dev/peps/pep-0484] (retornados por los nodos AST de definición de funciones);

feature_version=(3, N) permite especificar una versión de Python 3 previa. Por ejemplo, feature_version=(3, 4) hará que se trate a async y await como palabras no reservadas.

(Contribución de Guido van Rossum en bpo-35766 [https://bugs.python.org/issue?@action=redirect&bpo=35766].)

asyncio

asyncio.run() ha pasado de la API provisional a la estable. Esta función se puede utilizar para ejecutar una coroutine y retornar el resultado mientras se gestiona automáticamente el bucle de eventos. Por ejemplo:

import asyncio

async def main():
    await asyncio.sleep(0)
    return 42

asyncio.run(main())

Esto es aproximadamente equivalente a:

import asyncio

async def main():
    await asyncio.sleep(0)
    return 42

loop = asyncio.new_event_loop()
asyncio.set_event_loop(loop)
try:
    loop.run_until_complete(main())
finally:
    asyncio.set_event_loop(None)
    loop.close()

La implementación real es significativamente más compleja. Por lo tanto, asyncio.run() debería ser la forma preferida de ejecutar programas asyncio.

(Contribución de Yury Selivanov en bpo-32314 [https://bugs.python.org/issue?@action=redirect&bpo=32314].)

La ejecución de python -m asyncio lanza un REPL asincrónico de forma nativa. Esto permite una rápida experimentación con código que tiene un nivel await superior. Ya no es necesario llamar directamente a asyncio.run(), lo que generaría un nuevo ciclo de eventos en cada invocación:

$ python -m asyncio
asyncio REPL 3.8.0
Use "await" directly instead of "asyncio.run()".
Type "help", "copyright", "credits" or "license" for more information.
>>> import asyncio
>>> await asyncio.sleep(10, result='hello')
hello

(Contribución de Yury Selivanov en bpo-37028 [https://bugs.python.org/issue?@action=redirect&bpo=37028].)

La excepción asyncio.CancelledError ahora hereda de BaseException en lugar de Exception y ya no hereda de concurrent.futures.CancelledError. (Contribuido por Yury Selivanov en bpo-32528 [https://bugs.python.org/issue?@action=redirect&bpo=32528].)

En Windows, el ciclo de eventos predeterminado ahora es ProactorEventLoop. (Contribución de Victor Stinner en bpo-34687 [https://bugs.python.org/issue?@action=redirect&bpo=34687].)

ProactorEventLoop ahora también es compatible con UDP. (Contribución de Adam Meily y Andrew Svetlov en bpo-29883 [https://bugs.python.org/issue?@action=redirect&bpo=29883].)

ProactorEventLoop ahora puede ser interrumpido por KeyboardInterrupt («CTRL+C»). (Contribución de Vladimir Matveev en bpo-23057 [https://bugs.python.org/issue?@action=redirect&bpo=23057].)

Se ha agregado asyncio.Task.get_coro() para obtener la corrutina envuelta dentro de asyncio.Task. (Contribución de Alex Grönholm en bpo-36999 [https://bugs.python.org/issue?@action=redirect&bpo=36999].)

Las tareas de Asyncio ahora se pueden nombrar, ya sea pasando el argumento por palabra clave name a asyncio.create_task() o al método create_task() del bucle de eventos, o invocando al método set_name() en el objeto de tarea. El nombre de la tarea es visible en la salida de repr() de asyncio.Task y también se puede recuperar usando el método get_name(). (Contribución de Alex Grönholm en bpo-34270 [https://bugs.python.org/issue?@action=redirect&bpo=34270].)

Se agregó soporte para Happy Eyeballs [https://en.wikipedia.org/wiki/Happy_Eyeballs] a asyncio.loop.create_connection(). Para especificar el comportamiento, se han agregado dos nuevos parámetros: happy_eyeballs_delay e interleave. El algoritmo Happy Eyeballs mejora la capacidad de respuesta en aplicaciones que admiten IPv4 e IPv6 al intentar conectarse simultáneamente utilizando ambos. (Contribución de twisteroid ambassador en bpo-33530 [https://bugs.python.org/issue?@action=redirect&bpo=33530].)

builtins

La función incorporada compile() se ha mejorado para que acepte el flag ast.PyCF_ALLOW_TOP_LEVEL_AWAIT. Si se pasa este nuevo flag, compile() permitirá construcciones de nivel superior await, async for y async with, que normalmente se consideran sintaxis inválida. El objeto de código asíncrono marcado con el flag CO_COROUTINE puede ser retornado. (Contribución de Matthias Bussonnier en bpo-34616 [https://bugs.python.org/issue?@action=redirect&bpo=34616].)

collections

El método _asdict() para collections.namedtuple() ahora retorna una instancia de dict en lugar de una de collections.OrderedDict. Esto funciona porque se garantiza que los diccionarios regulares mantienen el orden de inserción desde Python 3.7. Si se requieren las características adicionales de OrderedDict, la solución sugerida es realizar una conversión del resultado al tipo deseado: OrderedDict(nt._asdict()). (Contribución de Raymond Hettinger en bpo-35864 [https://bugs.python.org/issue?@action=redirect&bpo=35864].)

cProfile

La clase cProfile.Profile ahora puede usarse como gestor de contexto. Ahora se puede perfilar un bloque de código ejecutando:

import cProfile

with cProfile.Profile() as profiler:
      # code to be profiled
      ...

(Contribución de Scott Sanderson en bpo-29235 [https://bugs.python.org/issue?@action=redirect&bpo=29235].)

csv

csv.DictReader ahora retorna instancias de dict en lugar de collections.OrderedDict. La herramienta ahora es más rápida y usa menos memoria, mientras conserva el orden de los campos. (Contribución de Michael Selik en bpo-34003 [https://bugs.python.org/issue?@action=redirect&bpo=34003].)

curses

Se agregó una nueva variable que contiene información de versión estructurada para la biblioteca ncurses subyacente: ncurses_version. (Contribución de Serhiy Storchaka en bpo-31680 [https://bugs.python.org/issue?@action=redirect&bpo=31680].)

ctypes

En Windows, CDLL y sus subclases ahora aceptan un parámetro winmode para especificar flags para la invocación subyacente de LoadLibraryEx. Los flags predeterminados están establecidos para cargar solo las dependencias de DLL desde ubicaciones confiables, incluida la ruta donde se almacena la DLL (si se usa una ruta completa o parcial para cargar la DLL inicial) y las rutas agregadas por add_dll_directory() . (Contribución de Steve Dower en bpo-36085 [https://bugs.python.org/issue?@action=redirect&bpo=36085].)

datetime

Se agregaron nuevos constructores alternativos datetime.date.fromisocalendar() y datetime.datetime.fromisocalendar(), que construyen objetos date y datetime respectivamente con el año, número de semana y día de la semana de la fecha del calendario ISO. Estos son el inverso del método isocalendar de cada clase. (Contribución de Paul Ganssle en bpo-36004 [https://bugs.python.org/issue?@action=redirect&bpo=36004].)

functools

functools.lru_cache() ahora se puede usar como un decorador directo en lugar de como una función que retorna un decorador. De forma que ambos son compatibles ahora:

@lru_cache
def f(x):
    ...

@lru_cache(maxsize=256)
def f(x):
    ...

(Contribución de Raymond Hettinger en bpo-36772 [https://bugs.python.org/issue?@action=redirect&bpo=36772].)

Se ha agregado un nuevo decorador functools.cached_property(), para propiedades calculadas almacenadas en caché durante toda la vida útil de la instancia.

import functools
import statistics

class Dataset:
   def __init__(self, sequence_of_numbers):
      self.data = sequence_of_numbers

   @functools.cached_property
   def variance(self):
      return statistics.variance(self.data)

(Contribución de Carl Meyer en bpo-21145 [https://bugs.python.org/issue?@action=redirect&bpo=21145].)

Se ha agregado un nuevo decorador functools.singledispatchmethod() que convierte métodos en funciones genéricas usando single dispatch:

from functools import singledispatchmethod
from contextlib import suppress

class TaskManager:

    def __init__(self, tasks):
        self.tasks = list(tasks)

    @singledispatchmethod
    def discard(self, value):
        with suppress(ValueError):
            self.tasks.remove(value)

    @discard.register(list)
    def _(self, tasks):
        targets = set(tasks)
        self.tasks = [x for x in self.tasks if x not in targets]

(Contribución de Ethan Smith en bpo-32380 [https://bugs.python.org/issue?@action=redirect&bpo=32380])

gc

get_objects() ahora puede recibir un parámetro opcional generation que indica la generación de la que recolectar objetos. (Contribución de Pablo Galindo en bpo-36016 [https://bugs.python.org/issue?@action=redirect&bpo=36016].)

gettext

Agregado pgettext() y sus variantes. (Contribución de Franz Glasner, Éric Araujo y Cheryl Sabella en bpo-2504 [https://bugs.python.org/issue?@action=redirect&bpo=2504].)

gzip

Se ha agregó el parámetro mtime a gzip.compress() para una salida reproducible. (Contribución de Guo Ci Teo en bpo-34898 [https://bugs.python.org/issue?@action=redirect&bpo=34898].)

Una excepción BadGzipFile es lanzada ahora, en lugar de OSError, para ciertos tipos de archivos gzip no válidos o corruptos. (Contribución de Filip Gruszczyński, Michele Orrù y Zackery Spytz en bpo-6584 [https://bugs.python.org/issue?@action=redirect&bpo=6584].)

IDLE e idlelib

Las salidas superiores a N líneas (50 por defecto) se pliegan en un botón. N se puede cambiar en la sección PyShell de la página General del cuadro de diálogo Settings. Se pueden plegar menos líneas, pero posiblemente más largas, haciendo clic derecho en la salida. La salida plegada se puede expandir en su lugar haciendo doble clic en el botón o en el portapapeles o en una ventana separada haciendo clic derecho en el botón. (Contribución de Tal Einat en bpo-1529353 [https://bugs.python.org/issue?@action=redirect&bpo=1529353].)

Se ha agregado «Run Customized» al menú Run para ejecutar un módulo con configuraciones personalizadas. Cualquier argumento de la línea de comandos ingresado se agrega a sys.argv. Además, vuelven a aparecer en el cuadro para la próxima ejecución personalizada. También se puede suprimir el reinicio normal del módulo principal de la Shell. (Contribución de Cheryl Sabella, Terry Jan Reedy y otros en bpo-5680 [https://bugs.python.org/issue?@action=redirect&bpo=5680] y bpo-37627 [https://bugs.python.org/issue?@action=redirect&bpo=37627].)

Se agregaron números de línea opcionales para las ventanas del editor IDLE. Las ventanas se abren sin números de línea, a menos que se establezca lo contrario en la pestaña General del cuadro de diálogo de configuración. Los números de línea de una ventana existente se muestran y ocultan en el menú Options. (Contribución de Tal Einat y Saimadhav Heblikar en bpo-17535 [https://bugs.python.org/issue?@action=redirect&bpo=17535].)

La codificación nativa del sistema operativo ahora se usa para convertir entre cadenas de Python y objetos Tcl. Esto permite que el IDLE funcione con emoji y otros caracteres que no son BMP. Estos caracteres se pueden mostrar o copiar y pegar en ,o desde, el portapapeles. Convertir cadenas de Tcl a Python y viceversa ahora nunca falla. (Mucha gente trabajó en esto durante ocho años, pero el problema finalmente lo resolvió Serhiy Storchaka en bpo-13153 [https://bugs.python.org/issue?@action=redirect&bpo=13153].)

Nuevo en 3.8.1:

Agregue la opción para desactivar el parpadeo del cursor. (Contribuido por Zackery Spytz en bpo-4603 [https://bugs.python.org/issue?@action=redirect&bpo=4603].)

La tecla Escape ahora cierra las ventanas de finalización IDLE. (Contribuido por Johnny Najera en bpo-38944 [https://bugs.python.org/issue?@action=redirect&bpo=38944].)

Los cambios anteriores se han portado a las versiones de mantenimiento de Python 3.7.

Agrega palabras clave a la lista de finalización del nombre del módulo. (Contribución de Terry J. Reedy en bpo-37765 [https://bugs.python.org/issue?@action=redirect&bpo=37765].)

inspect

La función inspect.getdoc() puede ahora encontrar cadenas de documentación para __slots__ si el este atributo es un dict cuyos valores son las cadenas de documentación. Esto proporciona opciones de documentación similares a las que ya tenemos para property(), classmethod() y staticmethod():

class AudioClip:
    __slots__ = {'bit_rate': 'expressed in kilohertz to one decimal place',
                 'duration': 'in seconds, rounded up to an integer'}
    def __init__(self, bit_rate, duration):
        self.bit_rate = round(bit_rate / 1000.0, 1)
        self.duration = ceil(duration)

(Contribución de Raymond Hettinger en bpo-36326 [https://bugs.python.org/issue?@action=redirect&bpo=36326].)

io

En el modo de desarrollo (-X env) y en la compilación de depuración, el finalizador io.IOBase ahora registra la excepción si falla el método close(). La excepción se ignora silenciosamente de forma predeterminada en la compilación de lanzamiento. (Contribución de Victor Stinner en bpo-18748 [https://bugs.python.org/issue?@action=redirect&bpo=18748].)

itertools

Se ha agregado un argumento por palabra clave opcional initial a la función itertools.accumulate() para permitir especificar un valor inicial:

>>> from itertools import accumulate
>>> list(accumulate([10, 5, 30, 15], initial=1000))
[1000, 1010, 1015, 1045, 1060]

(Contribución de Lisa Roach en bpo-34659 [https://bugs.python.org/issue?@action=redirect&bpo=34659].)

json.tool

Agregadas las opciones --json-lines para analizar sintácticamente cada línea de entrada como un objeto JSON separado. (Contribución de Weipeng Hong en bpo-31553 [https://bugs.python.org/issue?@action=redirect&bpo=31553].)

logging

Agregado un argumento por palabra clave force a la función logging.basicConfig(). Cuando se establece en verdadero, cualquier controlador existente adjunto al registrador (logger) raíz se elimina y se cierra antes de realizar la configuración especificada por los otros argumentos.

Esto resuelve un problema de larga data. Una vez que se había invocado a un registrador o a basicConfig(), las invocaciones posteriores a basicConfig() se ignoraban en silencio. Esto dificultaba la actualización, la experimentación o la instrucción de las diversas opciones de configuración de registro mediante el interprete interactivo o el bloc de notas de Jupyter.

(Sugerencia de Raymond Hettinger, implementación de Dong-hee Na y revisión de Vinay Sajip en bpo-33897 [https://bugs.python.org/issue?@action=redirect&bpo=33897].)

math

Se ha agregado la nueva función math.dist() para calcular la distancia euclidiana entre dos puntos. (Contribución de Raymond Hettinger en bpo-33089 [https://bugs.python.org/issue?@action=redirect&bpo=33089].)

Se ha expandido la función math.hypot() para manejar múltiples dimensiones. Anteriormente, solo admitía dos dimensiones. (Contribución de Raymond Hettinger en bpo-33089 [https://bugs.python.org/issue?@action=redirect&bpo=33089].)

Agregada una nueva función, math.prod(), como función análoga a sum(), que retorna el producto de todos los elementos de un iterable de números partiendo de un valor de inicio (start) (por defecto: 1):

>>> prior = 0.8
>>> likelihoods = [0.625, 0.84, 0.30]
>>> math.prod(likelihoods, start=prior)
0.126

(Contribución de Pablo Galindo en bpo-35606 [https://bugs.python.org/issue?@action=redirect&bpo=35606].)

Agregadas dos nuevas funciones combinatorias, math.perm() y math.comb():

>>> math.perm(10, 3)    # Permutations of 10 things taken 3 at a time
720
>>> math.comb(10, 3)    # Combinations of 10 things taken 3 at a time
120

(Contribución de Yash Aggarwal, Keller Fuchs, Serhiy Storchaka y Raymond Hettinger en bpo-37128 [https://bugs.python.org/issue?@action=redirect&bpo=37128], bpo-37178 [https://bugs.python.org/issue?@action=redirect&bpo=37178] y bpo-35431 [https://bugs.python.org/issue?@action=redirect&bpo=35431].)

Se ha agregada una nueva función math.isqrt() para calcular raíces cuadradas enteras precisas sin conversión a coma flotante. La nueva función admite números enteros arbitrariamente grandes. Es más rápida que floor(sqrt(n)) pero más lenta que math.sqrt():

>>> r = 650320427
>>> s = r ** 2
>>> isqrt(s - 1)         # correct
650320426
>>> floor(sqrt(s - 1))   # incorrect
650320427

(Contribución de Mark Dickinson en bpo-36887 [https://bugs.python.org/issue?@action=redirect&bpo=36887].)

La función math.factorial() ya no acepta argumentos que no sean similares a enteros. (Contribución de Pablo Galindo en bpo-33083 [https://bugs.python.org/issue?@action=redirect&bpo=33083].)

mmap

La clase mmap.mmap ahora tiene un método madvise() para acceder a la llamada al sistema madvise(). (Contribución de Zackery Spytz en bpo-32941 [https://bugs.python.org/issue?@action=redirect&bpo=32941].)

multiprocessing

Agregado el nuevo módulo multiprocessing.shared_memory. (Contribución de Davin Potts en bpo-35813 [https://bugs.python.org/issue?@action=redirect&bpo=35813].)

En macOS, el método de inicio spawn se usa ahora por defecto. (Contribución de Victor Stinner en bpo-33725 [https://bugs.python.org/issue?@action=redirect&bpo=33725].)

os

Se agregó una nueva función add_dll_directory() en Windows para proporcionar rutas de búsqueda adicionales para las dependencias nativas al importar módulos de extensión o al cargar archivos DLL utilizando ctypes. (Contribución de Steve Dower en bpo-36085 [https://bugs.python.org/issue?@action=redirect&bpo=36085].)

Se agregó una nueva función os.memfd_create() para envolver la llamada al sistema memfd_create(). (Contribución de Zackery Spytz y Christian Heimes en bpo-26836 [https://bugs.python.org/issue?@action=redirect&bpo=26836].)

En Windows, gran parte de la lógica manual para manejar los puntos de reinterpretación (incluidos los enlaces simbólicos y las uniones de directorios) se ha delegado al sistema operativo. Específicamente, os.stat() ahora se encargará de todo lo que sea compatible con el sistema operativo, mientras que os.lstat() solo abrirá puntos de reinterpretación que se identifican como «sustitutos de nombre» y el resto se abrirán mediante os.stat(). En todos los casos, stat_result.st_mode solo tendrá establecido S_IFLNK para enlaces simbólicos y no para otros tipos de puntos de reinterpretación. Para identificar otros tipos de puntos de reinterpretación, verifica el nuevo atributo stat_result.st_reparse_tag.

En Windows, os.readlink() ahora puede leer uniones de directorio. Ten en cuenta que islink() retornará False para las uniones de directorios, por lo que el código que comprueba en primer lugar islink continuará tratando las uniones como directorios, mientras que el código que maneja los errores de os.readlink() ahora puede tratar las uniones como enlaces.

(Contribución de Steve Dower en bpo-37834 [https://bugs.python.org/issue?@action=redirect&bpo=37834].)

os.path

Las funciones de os.path que retornan un resultado booleano como exists(), lexists(), isdir(), isfile(), islink() e ismount() ahora retornan False en lugar de lanzar una excepción ValueError, o sus subclases UnicodeEncodeError y UnicodeDecodeError, para rutas que contienen caracteres o bytes irrepresentables a nivel del sistema operativo. (Contribución de Serhiy Storchaka en bpo-33721 [https://bugs.python.org/issue?@action=redirect&bpo=33721].)

expanduser() en Windows ahora usa preferentemente la variable de entorno USERPROFILE y no usa HOME, que normalmente no está establecido para cuentas de usuario normales. (Contribución de Anthony Sottile en bpo-36264 [https://bugs.python.org/issue?@action=redirect&bpo=36264].)

isdir() en Windows ya no retorna True para un enlace a un directorio no existente.

realpath() en Windows ahora resuelve puntos de reinterpretación (reparse points), incluidos enlaces simbólicos y uniones de directorio.

(Contribución de Steve Dower en bpo-37834 [https://bugs.python.org/issue?@action=redirect&bpo=37834].)

pathlib

Los métodos del módulo pathlib.Path que retornan un resultado booleano, como exists(), is_dir(), is_file(), is_mount(), is_symlink(), is_block_device(), is_char_device(), is_fifo() o is_socket(), ahora retornan False en vez de lanzar una excepción ValueError o su subclase UnicodeEncodeError para rutas que contienen caracteres no representables a nivel del sistema operativo. (Contribución de Serhiy Storchaka en bpo-33721 [https://bugs.python.org/issue?@action=redirect&bpo=33721].)

Agregado pathlib.Path.link_to() que crea un enlace duro apuntando a una ruta. (Contribución de Joannah Nanjekye en bpo-26978 [https://bugs.python.org/issue?@action=redirect&bpo=26978])

pickle

Las extensiones de pickle que subclasifican la clase optimizada de C Pickler ahora pueden anular la lógica de pickling de funciones y clases definiendo el método especial reducer_override(). (Contribución de Pierre Glaser y Olivier Grisel en bpo-35900 [https://bugs.python.org/issue?@action=redirect&bpo=35900].)

plistlib

Se ha agregado la nueva clase plistlib.UID y se ha habilitado el soporte para leer y escribir plists binarios codificados por NSKeyedArchiver. (Contribución de Jon Janzen en bpo-26707 [https://bugs.python.org/issue?@action=redirect&bpo=26707].)

pprint

Se ha agregado el parámetro sort_dicts a varias funciones del módulo pprint. De forma predeterminada, esas funciones continúan ordenando los diccionarios antes de procesarlos o imprimirlos. Sin embargo, si sort_dicts se establece en falso, los diccionarios conservan el orden en que se insertaron las claves. Esto puede resultar útil para la comparación con entradas JSON durante la depuración.

Además, hay una nueva función de conveniencia, pprint.pp(), que es igual que pprint.pprint() pero con sort_dicts establecido en False por defecto:

>>> from pprint import pprint, pp
>>> d = dict(source='input.txt', operation='filter', destination='output.txt')
>>> pp(d, width=40)                  # Original order
{'source': 'input.txt',
 'operation': 'filter',
 'destination': 'output.txt'}
>>> pprint(d, width=40)              # Keys sorted alphabetically
{'destination': 'output.txt',
 'operation': 'filter',
 'source': 'input.txt'}

(Contribución de Rémi Lapeyre en bpo-30670 [https://bugs.python.org/issue?@action=redirect&bpo=30670].)

py_compile

py_compile.compile() ahora admite el modo silencioso. (Contribución de Joannah Nanjekye en bpo-22640 [https://bugs.python.org/issue?@action=redirect&bpo=22640].)

shlex

La nueva función shlex.join() actúa a la inversa de shlex.split(). (Contribución de Bo Bayles en bpo-32102 [https://bugs.python.org/issue?@action=redirect&bpo=32102].)

shutil

shutil.copytree() ahora acepta el nuevo argumento por palabra clave dirs_exist_ok. (Contribución de Josh Bronson en bpo-20849 [https://bugs.python.org/issue?@action=redirect&bpo=20849].)

shutil.make_archive() ahora usa por defecto el formato pax moderno (POSIX.1-2001) para nuevos archivos para mejorar la portabilidad y la conformidad con los estándares, heredado el cambio correspondiente del módulo tarfile. (Contribución de C.A.M. Gerlach en bpo-30661 [https://bugs.python.org/issue?@action=redirect&bpo=30661].)

shutil.rmtree() en Windows ahora elimina las uniones de directorio sin eliminar recursivamente su contenido primero. (Contribución de Steve Dower en bpo-37834 [https://bugs.python.org/issue?@action=redirect&bpo=37834].)

socket

Se han agregado las funciones de conveniencia create_server() y has_dualstack_ipv6() para automatizar las tareas necesarias involucradas al crear un socket servidor, incluida la aceptación de conexiones IPv4 e IPv6 en el mismo socket . (Contribución de Giampaolo Rodolà en bpo-17561 [https://bugs.python.org/issue?@action=redirect&bpo=17561].)

Las funciones socket.if_nameindex(), socket.if_nametoindex() y socket.if_indextoname() se han implementado en Windows. (Contribución de Zackery Spytz en bpo-37007 [https://bugs.python.org/issue?@action=redirect&bpo=37007].)

ssl

Se ha agregado post_handshake_auth para habilitar y verify_client_post_handshake() para iniciar la autenticación tras el establecimiento de la comunicación en TLS 1.3. (Contribución de Christian Heimes en bpo-34670 [https://bugs.python.org/issue?@action=redirect&bpo=34670].)

statistics

Se ha agregado statistics.fmean() como una variante de punto flotante más rápida de statistics.mean(). (Contribución de Raymond Hettinger y Steven D’Aprano en bpo-35904 [https://bugs.python.org/issue?@action=redirect&bpo=35904].)

Se ha agregado statistics.geometric_mean() (Contribución de Raymond Hettinger en bpo-27181 [https://bugs.python.org/issue?@action=redirect&bpo=27181].)

Se ha agregado statistics.multimode() que retorna una lista con los valores más comunes. (Contribución de Raymond Hettinger en bpo-35892 [https://bugs.python.org/issue?@action=redirect&bpo=35892].)

Se ha agregado statistics.quantiles() que divide datos o una distribución en intervalos equiprobables (por ejemplo, cuartiles, deciles o percentiles). (Contribución de Raymond Hettinger en bpo-36546 [https://bugs.python.org/issue?@action=redirect&bpo=36546].)

Se ha agregado statistics.NormalDist, una herramienta para crear y manipular distribuciones normales de una variable aleatoria. (Contribución de Raymond Hettinger en bpo-36018 [https://bugs.python.org/issue?@action=redirect&bpo=36018].)

>>> temperature_feb = NormalDist.from_samples([4, 12, -3, 2, 7, 14])
>>> temperature_feb.mean
6.0
>>> temperature_feb.stdev
6.356099432828281

>>> temperature_feb.cdf(3)            # Chance of being under 3 degrees
0.3184678262814532
>>> # Relative chance of being 7 degrees versus 10 degrees
>>> temperature_feb.pdf(7) / temperature_feb.pdf(10)
1.2039930378537762

>>> el_niño = NormalDist(4, 2.5)
>>> temperature_feb += el_niño        # Add in a climate effect
>>> temperature_feb
NormalDist(mu=10.0, sigma=6.830080526611674)

>>> temperature_feb * (9/5) + 32      # Convert to Fahrenheit
NormalDist(mu=50.0, sigma=12.294144947901014)
>>> temperature_feb.samples(3)        # Generate random samples
[7.672102882379219, 12.000027119750287, 4.647488369766392]

sys

Se ha agregado la nueva función sys.unraisablehook() que se puede anular para controlar cómo se manejan las «excepciones no lanzables». Se llama cuando se ha producido una excepción, pero Python no tiene forma de manejarla. Por ejemplo, cuando un destructor genera una excepción o durante la recolección de basura (gc.collect()). (Contribución de Victor Stinner en bpo-36829 [https://bugs.python.org/issue?@action=redirect&bpo=36829].)

tarfile

El módulo tarfile ahora tiene por defecto el formato pax moderno (POSIX.1-2001) para nuevos archivos, en lugar del anterior específico de GNU. Esto mejora la portabilidad multiplataforma con una codificación consistente (UTF-8) en un formato estandarizado y extensible, y ofrece otros varios beneficios. (Contribución de C.A.M. Gerlach en bpo-36268 [https://bugs.python.org/issue?@action=redirect&bpo=36268].)

threading

Se ha agregado una nueva función threading.excepthook() que maneja las excepciones threading.Thread.run() no capturadas. Se puede anular para controlar cómo se manejan las excepciones threading.Thread.run() no capturadas. (Contribución de Victor Stinner en bpo-1230540 [https://bugs.python.org/issue?@action=redirect&bpo=1230540].)

Se han agregado una nueva función threading.get_native_id() y un atributo native_id a la clase threading.Thread. Estos retornan el Thread ID nativo integral del hilo actual asignado por el kernel. Esta función solo está disponible en determinadas plataformas, consulta get_native_id para obtener más información. (Contribución de Jake Tesler en bpo-36084 [https://bugs.python.org/issue?@action=redirect&bpo=36084].)

tokenize

El módulo tokenize ahora emite implícitamente un token NEWLINE cuando se le proporciona una entrada sin una nueva línea al final. Este comportamiento ahora coincide con lo que hace internamente el tokenizador de C. (Contribución de Ammar Askar en bpo-33899 [https://bugs.python.org/issue?@action=redirect&bpo=33899].)

tkinter

Se han agregado los métodos selection_from(), selection_present(), selection_range() y selection_to() a la clase tkinter.Spinbox. (Contribución de Juliette Monsel en bpo-34829 [https://bugs.python.org/issue?@action=redirect&bpo=34829].)

Se ha agregado el método moveto() a la clase tkinter.Canvas. (Contribución de Juliette Monsel en bpo-23831 [https://bugs.python.org/issue?@action=redirect&bpo=23831].)

La clase tkinter.PhotoImage ahora dispone de los métodos transparency_get() y transparency_set(). (Contribución de Zackery Spytz en bpo-25451 [https://bugs.python.org/issue?@action=redirect&bpo=25451].)

time

Se ha agregado el nuevo reloj CLOCK_UPTIME_RAW para macOS 10.12. (Contribución de Joannah Nanjekye en bpo-35702 [https://bugs.python.org/issue?@action=redirect&bpo=35702].)

typing

Se han incorporado varias características al módulo typing:

Un tipo de diccionario con tipos para cada clave. Consultar PEP 589 [https://www.python.org/dev/peps/pep-0589] y typing.TypedDict. TypedDict usa solo claves de cadenas de caracteres. De forma predeterminada, se requiere que todas las claves estén presentes. Especifica «total=False» para permitir que las claves sean opcionales:

class Location(TypedDict, total=False):
    lat_long: tuple
    grid_square: str
    xy_coordinate: tuple

Tipos literales. Consultar PEP 586 [https://www.python.org/dev/peps/pep-0586] y typing.Literal. Los tipos literales indican que un parámetro o valor de retorno está restringido a uno o más valores literales específicos:

def get_status(port: int) -> Literal['connected', 'disconnected']:
    ...

Variables, funciones, métodos y clases «finales». Consultar PEP 591 [https://www.python.org/dev/peps/pep-0591], typing.Final y typing.final(). El clasificador final instruye a un validador estático de tipos para restringir la subclasificación, anulación o reasignación:

pi: Final[float] = 3.1415926536

Definiciones de protocolo. Consultar PEP 544 [https://www.python.org/dev/peps/pep-0544], typing.Protocol y typing.runtime_checkable(). ABCs simples como typing.SupportsInt ahora son subclases de Protocol .

Nueva clase protocolo typing.SupportsIndex.

Nuevas funciones typing.get_origin() y typing.get_args().

unicodedata

El módulo unicodedata ha sido actualizado para usar Unicode 12.1.0 [http://blog.unicode.org/2019/05/unicode-12-1-en.html].

La nueva función is_normalized() puede usarse para verificar que una cadena está en una forma normal específica, lo que es a menudo mucho más rápido que normalizar la cadena. (Contribución de Max Belanger, David Euresti y Greg Price en bpo-32285 [https://bugs.python.org/issue?@action=redirect&bpo=32285] y bpo-37966 [https://bugs.python.org/issue?@action=redirect&bpo=37966]).

unittest

Se ha agregado AsyncMock para admitir una versión asincrónica de Mock. También se han agregado nuevas funciones de aserción apropiadas para las pruebas. (Contribución de Lisa Roach en bpo-26467 [https://bugs.python.org/issue?@action=redirect&bpo=26467]).

Se ha agregado addModuleCleanup() y addClassCleanup() a unittest para admitir limpiezas para setUpModule() y setUpClass(). (Contribución de Lisa Roach en bpo-24412 [https://bugs.python.org/issue?@action=redirect&bpo=24412].)

Varias funciones de aserción simulada ahora también imprimen una lista de llamadas reales en caso de fallo. (Contribución de Petter Strandmark en bpo-35047 [https://bugs.python.org/issue?@action=redirect&bpo=35047].)

El módulo unittest ha obtenido soporte para corrutinas que se utilizarán como casos de prueba con unittest.IsolatedAsyncioTestCase. (Contribución de Andrew Svetlov en bpo-32972 [https://bugs.python.org/issue?@action=redirect&bpo=32972].)

Ejemplo:

import unittest

class TestRequest(unittest.IsolatedAsyncioTestCase):

    async def asyncSetUp(self):
        self.connection = await AsyncConnection()

    async def test_get(self):
        response = await self.connection.get("https://example.com")
        self.assertEqual(response.status_code, 200)

    async def asyncTearDown(self):
        await self.connection.close()

if __name__ == "__main__":
    unittest.main()

venv

venv ahora incluye un script Activate.ps1 en todas las plataformas para activar entornos virtuales en PowerShell Core 6.1. (Contribución de Brett Cannon en bpo-32718 [https://bugs.python.org/issue?@action=redirect&bpo=32718].)

weakref

Los objetos proxy retornados por debilref.proxy() ahora admiten los operadores de multiplicación de matrices @ y @=, además de los otros operadores numéricos. (Contribución de Mark Dickinson en bpo-36669 [https://bugs.python.org/issue?@action=redirect&bpo=36669].)

xml

Como mitigación contra DTD y recuperación de entidades externas, los módulos xml.dom.minidom y xml.sax ya no procesan entidades externas de forma predeterminada. (Contribución de Christian Heimes en bpo-17239 [https://bugs.python.org/issue?@action=redirect&bpo=17239].)

Los métodos .find*() del módulo xml.etree.ElementTree admiten búsquedas con comodines, como {*}tag, que ignora el espacio de nombres, y {namespace}*, que retorna todas las etiquetas en el espacio de nombres dado. (Contribución de Stefan Behnel en bpo-28238 [https://bugs.python.org/issue?@action=redirect&bpo=28238].)

El módulo xml.etree.ElementTree proporciona una nueva función –xml.etree.ElementTree.canonicalize() que implementa C14N 2.0. (Contribución de Stefan Behnel en bpo-13611 [https://bugs.python.org/issue?@action=redirect&bpo=13611].)

El objeto de destino de xml.etree.ElementTree.XMLParser puede recibir eventos de declaración de espacio de nombres a través de los nuevos métodos de retrollamada start_ns() y end_ns(). Además, el destino xml.etree.ElementTree.TreeBuilder se puede configurar para procesar eventos sobre comentarios e instrucciones de procesamiento para incluirlos en el árbol generado. (Contribución de Stefan Behnel en bpo-36676 [https://bugs.python.org/issue?@action=redirect&bpo=36676] y bpo-36673 [https://bugs.python.org/issue?@action=redirect&bpo=36673].)

xmlrpc

xmlrpc.client.ServerProxy ahora admite un argumento por palabra clave headers opcional para una secuencia de encabezados HTTP que se enviarán con cada solicitud. Entre otras cosas, esto permite actualizar desde la autenticación básica predeterminada a una autenticación de sesión más rápida. (Contribución de Cédric Krier en bpo-35153 [https://bugs.python.org/issue?@action=redirect&bpo=35153].)

Optimizaciones

El módulo subprocess ahora puede usar en ciertos casos la función os.posix_spawn() para mejorar el rendimiento. Actualmente, solo se usa en macOS y Linux (usando glibc 2.24 o una versión más reciente) y siempre que se cumplan todas estas condiciones:

close_fds es falso;

los parámetros preexec_fn, pass_fds, cwd y start_new_session no están establecidos;

la ruta executable contiene un directorio.

(Contribución de Joannah Nanjekye y Victor Stinner en bpo-35537 [https://bugs.python.org/issue?@action=redirect&bpo=35537].)

shutil.copyfile(), shutil.copy(), shutil.copy2(), shutil.copytree() y shutil.move() usan llamadas al sistema de «copia-rápida» específicas de la plataforma en Linux y macOS, con la finalidad de copiar ficheros más eficientemente. «copia-rápida» significa que la operación de copiado tiene lugar en el propio kernel, evitando que Python haga uso de búferes en el espacio de usuario como «outfd.write(infd.read())». En Windows, shutil.copyfile() usa un tamaño de búfer predeterminado más grande (1 MiB en lugar de 16 KiB) y se usa una variante de shutil.copyfileobj() basada en memoryview(). La aceleración al copiar un archivo de 512 MiB dentro de la misma partición es de aproximadamente +26% en Linux, +50% en macOS y +40% en Windows. Además, se consumen muchos menos ciclos de CPU. Consultar la sección Operaciones de copia eficientes dependientes de la plataforma. (Contribución de Giampaolo Rodolà en bpo-33671 [https://bugs.python.org/issue?@action=redirect&bpo=33671].)

Ahora shutil.copytree() usa la función os.scandir() y todas las funciones de copia que dependen de ella usan el valor en caché de os.stat(). Al copiar un directorio con 8000 archivos, la mejora de velocidad es de +9% en Linux, +20% en Windows y +30% en recursos compartidos de Windows SMB. Además, el número de llamadas al sistema de os.stat() se reduce en un 38%, lo que hace que shutil.copytree() sea más rápida especialmente en sistemas de archivos de red. (Contribución de Giampaolo Rodolà en bpo-33695 [https://bugs.python.org/issue?@action=redirect&bpo=33695].)

El protocolo por defecto del módulo pickle es ahora el Protocolo 4, introducido por primera vez en Python 3.4. Ofrece un mejor desempeño y un menor tamaño, en comparación con el Protocolo 3 disponible desde Python 3.0.

Removed one Py_ssize_t member from PyGC_Head. All GC tracked objects (e.g. tuple, list, dict) size is reduced 4 or 8 bytes. (Contributed by Inada Naoki in bpo-33597 [https://bugs.python.org/issue?@action=redirect&bpo=33597].)

La clase uuid.UUID ahora usa __slots__ para reducir su impacto en la memoria. (Contribución de Wouter Bolsterlee y Tal Einat en bpo-30977 [https://bugs.python.org/issue?@action=redirect&bpo=30977].)

Mejorado el rendimiento de operator.itemgetter() en un 33%. Se ha optimizado el manejo de argumentos y se ha agregado una ruta rápida al caso común de índices enteros no negativos únicos en tuplas (que constituye un caso de uso común en la biblioteca estándar). (Contribución de Raymond Hettinger en bpo-35664 [https://bugs.python.org/issue?@action=redirect&bpo=35664].)

Se han acelerado las búsquedas de campos en collections.namedtuple(). Ahora son más del doble de rápidas, lo que las convierte en la forma más rápida de búsqueda de variables de instancia en Python. (Contribución de Raymond Hettinger, Pablo Galindo, Joe Jevnik y Serhiy Storchaka en bpo-32492 [https://bugs.python.org/issue?@action=redirect&bpo=32492].)

El constructor de list no sobre-asignará el búfer del elemento interno si se conoce la longitud de la entrada iterable (es decir, si la entrada implementa __len__). Esto hace que la lista generada sea, en promedio, un 12% más pequeña. (Contribución de Raymond Hettinger y Pablo Galindo en bpo-33234 [https://bugs.python.org/issue?@action=redirect&bpo=33234].)

De ha duplicado la velocidad de escritura de variables de clase. Antes, cuando se actualizaba un atributo non-dunder, había una llamada innecesaria para actualizar slots. (Contribución de Stefan Behnel, Pablo Galindo Salgado, Raymond Hettinger, Neil Schemenauer y Serhiy Storchaka en bpo-36012 [https://bugs.python.org/issue?@action=redirect&bpo=36012].)

Se ha reducido la sobrecarga de conversión de argumentos pasados a muchas funciones y métodos integrados. Esto acelera la llamada a algunas funciones y métodos incorporados simples hasta un 20-50%. (Contribución de Serhiy Storchaka en bpo-23867 [https://bugs.python.org/issue?@action=redirect&bpo=23867], bpo-35582 [https://bugs.python.org/issue?@action=redirect&bpo=35582] y bpo-36127 [https://bugs.python.org/issue?@action=redirect&bpo=36127].)

La instrucción LOAD_GLOBAL ahora utiliza el nuevo mecanismo «per opcode cache». Ahora es aproximadamente un 40% más rápida. (Contribución de Yury Selivanov e Inada Naoki en bpo-26219 [https://bugs.python.org/issue?@action=redirect&bpo=26219].)

Cambios en la compilación y la API de C

El valor predeterminado para sys.abiflags es ahora una cadena vacía: el flag m para pymalloc se ha vuelto innecesario (las compilaciones con y sin pymalloc son ABI compatibles) y por lo tanto se ha eliminado. (Contribución de Victor Stinner en bpo-36707 [https://bugs.python.org/issue?@action=redirect&bpo=36707].)

Ejemplos del cambio:

Solo el programa python3.8 es instalado, el programa python3.8m se ha eliminado.

Solo el script python3.8-config es instalado, el script python3.8m-config se ha eliminado.

El flag m se ha eliminado del sufijo de los nombres de archivo de las bibliotecas dinámicas: los módulos de extensión de la biblioteca estándar, así como los producidos e instalados por paquetes de terceros, como los descargados desde PyPI. En Linux, por ejemplo, el sufijo .cpython-37m-x86_64-linux-gnu.so en Python 3.7 se ha convertido en .cpython-38-x86_64-linux-gnu.so en Python 3.8.

Los archivos de cabeceras se han reorganizado para separar mejor los diferentes tipos de APIs:

Include/*.h debe ser la API de C portable, pública y estable.

Include/cpython/*.h debe ser la API de C inestable específica de CPython. Una API pública, con alguna API privada marcada con los prefijos _Py o _PY.

Include/internal/*.h es la API de C interna privada, muy específica de CPython. Esta API no tiene retro-compatibilidad garantizada con versiones anteriores y no debe ser usada fuera de CPython. Solo está expuesta para cubrir necesidades muy específicas, como es el caso de depuradores y perfiladores, que necesitan acceder a los componentes internos de CPython sin llamar directamente a las funciones. Esta API es ahora instalada por make install.

(Contribución de Victor Stinner en bpo-35134 [https://bugs.python.org/issue?@action=redirect&bpo=35134] y bpo-35081 [https://bugs.python.org/issue?@action=redirect&bpo=35081], trabajo iniciado por Eric Snow en Python 3.7.)

Algunas macros se han convertido a funciones inline estáticas: los tipos de los parámetros y el tipo de retorno están bien definidos, no entrañan cuestiones que precisen el uso específico de macros y las variables tienen ámbito local. Algunos ejemplos:

Py_INCREF(), Py_DECREF()

Py_XINCREF(), Py_XDECREF()

PyObject_INIT(), PyObject_INIT_VAR()

Funciones privadas: _PyObject_GC_TRACK(), _PyObject_GC_UNTRACK(), _Py_Dealloc()

(Contribución de Victor Stinner en bpo-35059 [https://bugs.python.org/issue?@action=redirect&bpo=35059].)

Las funciones PyByteArray_Init() y PyByteArray_Fini() se han eliminado. No eran de utilidad desde Python 2.7.4 y Python 3.2.0, cuando fueron excluidas de la API limitada (ABI estable) y dejaron de estar documentadas. (Contribución de Victor Stinner en bpo-35713 [https://bugs.python.org/issue?@action=redirect&bpo=35713].)

El resultado de PyExceptionClass_Name() es ahora de tipo const char * en vez de char *. (Contribución de Serhiy Storchaka en bpo-33818 [https://bugs.python.org/issue?@action=redirect&bpo=33818].)

La dualidad conformada por Modules/Setup.dist y Modules/Setup ha sido eliminada. Anteriormente, al actualizar el árbol de fuentes de CPython, se tenía que copiar manualmente Modules/Setup.dist (dentro del árbol de fuentes) a Modules/Setup (dentro del árbol de compilación) para reflejar cualquier cambio en sentido ascendente. Esto suponía un pequeño beneficio para los empaquetadores, a expensas de una frecuente molestia para los desarrolladores de CPython, ya que olvidarse de copiar el archivo podía ocasionar fallos de compilación.

Ahora el sistema de compilación siempre lee desde Modules/Setup dentro del árbol de fuentes. Se recomienda a las personas que deseen personalizar este archivo que mantengan sus cambios en un fork de git de CPython o como archivos de parche, como harían con cualquier otro cambio en el árbol de fuentes.

(Contribución de Antoine Pitrou en bpo-32430 [https://bugs.python.org/issue?@action=redirect&bpo=32430].)

Las funciones que convierten un número de Python a un entero de C, como PyLong_AsLong(), y las funciones de análisis de argumentos como PyArg_ParseTuple() con unidades de formato de conversión de enteros como 'i', ahora usarán el método especial __index__() si está disponible, en lugar de __int__(). Una advertencia de deprecación se emitirá para aquellos objetos que tengan el método __int__() pero no el método __index__() (como Decimal y Fraction). PyNumber_Check() ahora retornará 1 para los objetos que implementen __index__(). PyNumber_Long(), PyNumber_Float() y PyFloat_AsDouble() ahora también usan el método __index__() si está disponible. (Contribución de Serhiy Storchaka en bpo-36048 [https://bugs.python.org/issue?@action=redirect&bpo=36048] y bpo-20092 [https://bugs.python.org/issue?@action=redirect&bpo=20092].)

Los objetos de tipo asignados al montículo ahora aumentarán su recuento de referencias en PyObject_Init() (y en su macro paralela PyObject_INIT) en lugar de en PyType_GenericAlloc(). Es posible que deban ajustarse los tipos que modifican la asignación o desasignación de instancias. (Contribución de Eddie Elizondo en bpo-35810 [https://bugs.python.org/issue?@action=redirect&bpo=35810].)

La nueva función PyCode_NewWithPosOnlyArgs() permite crear objetos de código, al igual que PyCode_New(), pero con un parámetro posonlyargcount extra, que permite indicar el número de argumentos solo posicionales.

Py_SetPath() ahora establece sys.executable en la ruta completa del programa (Py_GetProgramFullPath()), en vez de en el nombre del programa (Py_GetProgramName()). (Contribución de Victor Stinner en bpo-38234 [https://bugs.python.org/issue?@action=redirect&bpo=38234].)

Obsoleto

El comando bdist_wininst de distutils está ahora obsoleto, usar bdist_wheel (paquetes wheel) en su lugar. (Contribución de Victor Stinner en bpo-37481 [https://bugs.python.org/issue?@action=redirect&bpo=37481].)

Los métodos getchildren() y getiterator() del módulo ElementTree ahora emiten una advertencia DeprecationWarning, en lugar de PendingDeprecationWarning. Serán eliminados en Python 3.9. (Contribución de Serhiy Storchaka en bpo-29209 [https://bugs.python.org/issue?@action=redirect&bpo=29209].)

Pasar un objeto a loop.set_default_executor() que no sea una instancia de concurrent.futures.ThreadPoolExecutor está obsoleto y será prohibido en Python 3.9. (Contribución de Elvis Pranskevichus en bpo-34075 [https://bugs.python.org/issue?@action=redirect&bpo=34075].)

Los métodos __getitem__() pertenecientes a las clases xml.dom.pulldom.DOMEventStream, wsgiref.util.FileWrapper y fileinput.FileInput están obsoletos a partir de ahora.

Las implementaciones de estos métodos han estado ignorando su parámetro index y retornando el siguiente item en su lugar. (Contribución de Berker Peksag en bpo-9372 [https://bugs.python.org/issue?@action=redirect&bpo=9372].)

El atributo _field_types de la clase typing.NamedTuple está ahora obsoleto en favor del atributo __annotations__, que contiene la misma información. (Contribución de Raymond Hettinger en bpo-36320 [https://bugs.python.org/issue?@action=redirect&bpo=36320].)

Las clases Num, Str, Bytes, NameConstant y Ellipsis del módulo ast están consideradas obsoletas y serán eliminadas en versiones futuras de Python. La clase Constant debe ser usada en su lugar. (Contribución de Serhiy Storchaka en bpo-32892 [https://bugs.python.org/issue?@action=redirect&bpo=32892].)

Los métodos visit_Num(), visit_Str(), visit_Bytes(), visit_NameConstant() y visit_Ellipsis() de la clase ast.NodeVisitor están obsoletos ahora y serán invocados en versiones futuras de Python. Agregar el método visit_Constant() para manejar todos los nodos constantes. (Contribución de Serhiy Storchaka en bpo-36917 [https://bugs.python.org/issue?@action=redirect&bpo=36917].)

El decorator asyncio.coroutine() está obsoleto y será eliminado en Python 3.10. En lugar de @asyncio.coroutine, se debe usar async def. (Contribución de Andrew Svetlov en bpo-36921 [https://bugs.python.org/issue?@action=redirect&bpo=36921].)

En asyncio, pasar un argumento loop de forma explícita está ahora obsoleto y será eliminado en Python 3.10 para las siguientes funciones y constructores: asyncio.sleep(), asyncio.gather(), asyncio.shield(), asyncio.wait_for(), asyncio.wait(), asyncio.as_completed(), asyncio.Task, asyncio.Lock, asyncio.Event, asyncio.Condition, asyncio.Semaphore, asyncio.BoundedSemaphore, asyncio.Queue, asyncio.create_subprocess_exec() y asyncio.create_subprocess_shell().

El paso explícito de objetos corrutina a asyncio.wait() está ahora obsoleto y será eliminado en Python 3.11. (Contribución de Yury Selivanov en bpo-34790 [https://bugs.python.org/issue?@action=redirect&bpo=34790].)

Las siguientes funciones y métodos del módulo gettext están obsoletos para: lgettext(), ldgettext(), lngettext() y ldngettext(). Retornan bytes codificados y es posible obtener excepciones inesperadas relacionadas con Unicode si hay problemas de codificación con las cadenas traducidas. En Python 3 es mucho mejor usar alternativas que retornen cadenas Unicode. Estas funciones han estado rotas durante mucho tiempo.

Función bind_textdomain_codeset(), métodos output_charset() y set_output_charset(), y el parámetro codeset de las funciones translation() y install() también están en desuso, ya que solo se usan para las funciones l*gettext(). (Contribución de Serhiy Storchaka en bpo-33710 [https://bugs.python.org/issue?@action=redirect&bpo=33710].)

El método isAlive() de la clase threading.Thread está ahora obsoleto. (Contribución de Dong-hee Na en bpo-35283 [https://bugs.python.org/issue?@action=redirect&bpo=35283].)

Muchas funciones incorporadas y de extensión que toman argumentos enteros ahora emitirán una advertencia de deprecación para Decimals, Fractions y cualquier otro objeto que se pueda convertir a enteros solamente con pérdida (por ejemplo, aquellos que tienen el método __int__() pero no el método __index__()). En una versión futura, esto constituirá un error. (Contribución de Serhiy Storchaka en bpo-36048 [https://bugs.python.org/issue?@action=redirect&bpo=36048].)

El paso de los siguientes argumentos como argumentos por palabra clave está ahora obsoleto:

func en functools.partialmethod(), weakref.finalize(), profile.Profile.runcall(), cProfile.Profile.runcall(), bdb.Bdb.runcall(), trace.Trace.runfunc() y curses.wrapper().

function en unittest.TestCase.addCleanup().

fn en el método submit() de las clases concurrent.futures.ThreadPoolExecutor y concurrent.futures.ProcessPoolExecutor.

callback en contextlib.ExitStack.callback(), contextlib.AsyncExitStack.callback() y contextlib.AsyncExitStack.push_async_callback().

c y typeid en el método create() de las clases multiprocessing.managers.Server y multiprocessing.managers.SharedMemoryServer.

obj en weakref.finalize().

En futuros lanzamientos de Python, todos ellos serán argumentos solo posicionales. (Contribución de Serhiy Storchaka en bpo-36492 [https://bugs.python.org/issue?@action=redirect&bpo=36492].)

APIs y características eliminadas

Las siguientes características y APIs se han eliminado de Python 3.8:

A partir de Python 3.3, la importación de ABC desde el módulo collections quedó obsoleta y la importación debe realizarse desde el módulo collections.abc. La posibilidad de importar desde collections se marcó para su eliminación en Python 3.8, pero se ha retrasado a Python 3.9. (Consultar bpo-36952 [https://bugs.python.org/issue?@action=redirect&bpo=36952].)

El módulo macpath, obsoleto desde Python 3.7, ha sido eliminado. (Contribución de Victor Stinner en bpo-35471 [https://bugs.python.org/issue?@action=redirect&bpo=35471].)

La función platform.popen() ha sido eliminada, después de haber estado obsoleta desde Python 3.3: usa os.popen() en su lugar. (Contribución de Victor Stinner en bpo-35345 [https://bugs.python.org/issue?@action=redirect&bpo=35345].)

La función time.clock() ha sido eliminada, después de haber quedado obsoleta desde Python 3.3: usa time.perf_counter() o time.process_time() en su lugar, dependiendo de tus requisitos, para tener un comportamiento bien definido. (Contribución de Matthias Bussonnier en bpo-36895 [https://bugs.python.org/issue?@action=redirect&bpo=36895].)

El script pyvenv se ha eliminado, en favor de python3.8 -m venv, para ayudar a eliminar la confusión sobre a qué intérprete de Python está vinculado el script pyvenv. (Contribución de Brett Cannon en bpo-25427 [https://bugs.python.org/issue?@action=redirect&bpo=25427].)

Las funciones parse_qs, parse_qsl y escape se han eliminado del módulo cgi. Estaban obsoletas desde Python 3.2 o versiones anteriores. En su lugar, deberían ser importadas desde los módulos urllib.parse y html.

La función filemode se ha eliminado del módulo tarfile. Estaba indocumentada y obsoleta desde Python 3.3.

El constructor de XMLParser ya no acepta el argumento html. Nunca tuvo efecto y quedó obsoleto en Python 3.4. Todos los demás parámetros son ahora parámetros solo nombrados. (Contribución de Serhiy Storchaka en bpo-29209 [https://bugs.python.org/issue?@action=redirect&bpo=29209].)

Se ha eliminado el método doctype() de XMLParser. (Contribución de Serhiy Storchaka en bpo-29209 [https://bugs.python.org/issue?@action=redirect&bpo=29209].)

Se ha elimina el códec «unicode_internal». (Contribución de Inada Naoki en bpo-36297 [https://bugs.python.org/issue?@action=redirect&bpo=36297].)

Los objetos Cache y Statement del módulo sqlite3 no estarán expuestos al usuario a partir de ahora. (Contribución de Aviv Palivoda en bpo-30262 [https://bugs.python.org/issue?@action=redirect&bpo=30262].)

El argumento por palabra clave bufsize de fileinput.input() y fileinput.FileInput(), marcado como obsoleto e ignorado desde Python 3.6, ha sido eliminado. bpo-36952 [https://bugs.python.org/issue?@action=redirect&bpo=36952] (Contribución de Matthias Bussonnier.)

Las funciones sys.set_coroutine_wrapper() y sys.get_coroutine_wrapper(), obsoletas desde Python 3.7, han sido eliminadas; bpo-36933 [https://bugs.python.org/issue?@action=redirect&bpo=36933] (Contribución de Matthias Bussonnier.)

Portando a Python 3.8

Esta sección enumera los cambios descritos anteriormente y otras correcciones de errores que pueden requerir cambios en tu código.

Cambios en el comportamiento de Python

Las expresiones yield (tanto la cláusula yield como la cláusula yield from) ahora no están permitidas en comprensiones y expresiones generadoras (excepto en la expresión iterable en la cláusula for situada más a la izquierda). (Contribución de Serhiy Storchaka en bpo-10544 [https://bugs.python.org/issue?@action=redirect&bpo=10544].)

El compilador ahora produce una advertencia SyntaxWarning cuando se utilizan comprobaciones de identidad (is e is not) con ciertos tipos de literales (por ejemplo, cadenas, números). A menudo, estas pueden funcionar accidentalmente en CPython, pero no está garantizado por las especificaciones del lenguaje. La advertencia advierte a los usuarios que utilicen pruebas de igualdad (== y !=) en su lugar. (Contribución de Serhiy Storchaka en bpo-34850 [https://bugs.python.org/issue?@action=redirect&bpo=34850].)

El intérprete de CPython puede tolerar excepciones en algunas circunstancias. En Python 3.8 esto sucederá con menos frecuencia. En particular, las excepciones que se generan al obtener atributos del diccionario de tipos ya no son ignoradas. (Contribución de Serhiy Storchaka en bpo-35459 [https://bugs.python.org/issue?@action=redirect&bpo=35459].)

Se ha eliminado las implementaciones de __str__ para los tipos incorporados bool, int, float, complex y algunas clases de la biblioteca estándar. Ahora heredan el método __str__() de object. Como resultado, definir el método __repr__() en una subclase de estas clases afectará a su representación como cadena de caracteres. (Contribución de Serhiy Storchaka en bpo-36793 [https://bugs.python.org/issue?@action=redirect&bpo=36793].)

En AIX, el atributo sys.platform ya no contiene la versión principal. Es decir, siempre es 'aix', en lugar de 'aix3' .. 'aix7'. Dado que las versiones anteriores de Python incluyen el número de versión, se recomienda usar siempre sys.platform.startswith('aix'). (Contribución de M. Felt en bpo-36588 [https://bugs.python.org/issue?@action=redirect&bpo=36588].)

PyEval_AcquireLock() y PyEval_AcquireThread() ahora terminan el hilo actual si se llaman mientras el intérprete está finalizando, haciéndolos consistentes con PyEval_RestoreThread(), Py_END_ALLOW_THREADS() y PyGILState_Ensure(). Si no se desea este comportamiento, se tiene que proteger la invocación comprobando _Py_IsFinalizing() o sys.is_finalizing(). (Contribución de Joannah Nanjekye en bpo-36475 [https://bugs.python.org/issue?@action=redirect&bpo=36475].)

Cambios en la API de Python

La función os.getcwdb() ahora usa la codificación UTF-8 en Windows, en lugar de la página de códigos ANSI: consultar PEP 529 [https://www.python.org/dev/peps/pep-0529] para el fundamento. La función ya no está obsoleta en Windows. (Contribución de Victor Stinner en bpo-37412 [https://bugs.python.org/issue?@action=redirect&bpo=37412].)

subprocess.Popen ahora puede usar os.posix_spawn() en algunos casos para un mejor rendimiento. En el Subsistema de Windows para Linux y en la Emulación de usuario QEMU, el constructor Popen que usa os.posix_spawn() ya no genera una excepción como «missing program» ante errores. En cambio, el proceso hijo falla con un valor returncode distinto de cero. (Contribución de Joannah Nanjekye y Victor Stinner en bpo-35537 [https://bugs.python.org/issue?@action=redirect&bpo=35537].)

El argumento preexec_fn de subprocess.Popen ya no es compatible con subintérpretes. El uso del parámetro en un subintérprete ahora lanza una excepción RuntimeError. (Contribución de Eric Snow en bpo-34651 [https://bugs.python.org/issue?@action=redirect&bpo=34651], modificado por Christian Heimes en bpo-37951 [https://bugs.python.org/issue?@action=redirect&bpo=37951].)

El método imap.IMAP4.logout() ya no ignora silenciosamente excepciones arbitrarias. (Contribución de Victor Stinner en bpo-36348 [https://bugs.python.org/issue?@action=redirect&bpo=36348].)

La función platform.popen() ha sido eliminada, después de haber estado obsoleta desde Python 3.3: usa os.popen() en su lugar. (Contribución de Victor Stinner en bpo-35345 [https://bugs.python.org/issue?@action=redirect&bpo=35345].)

La función statistics.mode() ya no lanza una excepción cuando se proporcionan datos multimodales. Ahora, en cambio, retorna la primera moda encontrada en los datos de entrada. (Contribución de Raymond Hettinger en bpo-35892 [https://bugs.python.org/issue?@action=redirect&bpo=35892].)

El método selection() de la clase tkinter.ttk.Treeview ya no acepta argumentos. Usarlo con argumentos para cambiar la selección quedó obsoleto en Python 3.6. Utiliza métodos especializados, como selection_set(), para cambiar la selección. (Contribución de Serhiy Storchaka en bpo-31508 [https://bugs.python.org/issue?@action=redirect&bpo=31508].)

Los métodos writexml(), toxml() y toprettyxml() de xml.dom.minidom y el método write() de xml.etree, ahora conservan el orden de los atributos especificado por el usuario. (Contribución de Diego Rojas y Raymond Hettinger en bpo-34160 [https://bugs.python.org/issue?@action=redirect&bpo=34160].)

Una base de datos dbm.dumb abierta con el flag 'r' ahora es de solo lectura. dbm.dumb.open() con los flags 'r' y 'w' ya no crea una base de datos si no existe. (Contribución de Serhiy Storchaka en bpo-32749 [https://bugs.python.org/issue?@action=redirect&bpo=32749].)

El método doctype() definido en una subclase de XMLParser ya no será invocado y emitirá una advertencia RuntimeWarning en lugar de DeprecationWarning. Define el método doctype() en un objetivo para manejar una declaración doctype de XML. (Contribución de Serhiy Storchaka en bpo-29209 [https://bugs.python.org/issue?@action=redirect&bpo=29209].)

Ahora se lanza una excepción RuntimeError cuando la metaclase personalizada no proporciona la entrada __classcell__ en el espacio de nombres pasado a type.__new__. En Python 3.6–3.7. se emitía una advertencia DeprecationWarning (Contribución de Serhiy Storchaka en bpo-23722 [https://bugs.python.org/issue?@action=redirect&bpo=23722].)

La clase cProfile.Profile ahora se puede usar como gestor de contexto. (Contribución de Scott Sanderson en bpo-29235 [https://bugs.python.org/issue?@action=redirect&bpo=29235].)

shutil.copyfile(), shutil.copy(), shutil.copy2(), shutil.copytree() y shutil.move() usan llamadas al sistema de «copia-rápida» específicas de la plataforma. (Consultar la sección Operaciones de copia eficientes dependientes de la plataforma).

El tamaño predeterminado del búfer de shutil.copyfile() en Windows se ha cambiado de 16 KiB a 1 MiB.

La estructura PyGC_Head ha cambiado por completo. Todo código que haga uso de algún miembro de la estructura debe reescribirse. (Consultar bpo-33597 [https://bugs.python.org/issue?@action=redirect&bpo=33597].)

La estructura PyInterpreterState se ha movido a los archivos de cabeceras «internos» (específicamente a Include/internal/pycore_pystate.h). Un PyInterpreterState opaco todavía está disponible como parte de la API pública (y ABI estable). La documentación indica que ninguno de los campos de la estructura es público, por lo que esperamos que nadie los haya estado usando. Sin embargo, si utilizas uno o más de esos campos privados y no tienes otra alternativa, abre una issue BPO. Trabajaremos para ayudarte a adaptarlo (posiblemente incluyendo funciones de acceso a la API pública). (Consultar bpo-35886 [https://bugs.python.org/issue?@action=redirect&bpo=35886].)

El método mmap.flush() ahora retorna None en caso de éxito y lanza una excepción en caso de error, en todas las plataformas. Anteriormente, su comportamiento dependía de la plataforma: en Windows retornaba un valor distinto de cero en caso de éxito y cero ante un error. En Unix se retornaba un valor de cero en caso de éxito y se lanzaba una excepción ante un error. (Contribución de Berker Peksag en bpo-2122 [https://bugs.python.org/issue?@action=redirect&bpo=2122].)

Los módulos xml.dom.minidom y xml.sax ya no procesan entidades externas de forma predeterminada. (Contribución de Christian Heimes en bpo-17239 [https://bugs.python.org/issue?@action=redirect&bpo=17239].)

Eliminar una clave de una base de datos dbm de solo lectura (dbm.dumb, dbm.gnu o dbm.ndbm) lanza una excepción error (dbm.dumb.error, dbm.gnu.error o dbm.ndbm.error) en lugar de KeyError. (Contribución de Xiang Zhang en bpo-33106 [https://bugs.python.org/issue?@action=redirect&bpo=33106].)

AST simplificado para literales. Todas las constantes se representarán como instancias de ast.Constant. La instanciación de las antiguas clases Num, Str, Bytes, NameConstant y Ellipsis retornará ahora una instancia de Constant. (Contribución de Serhiy Storchaka en bpo-32892 [https://bugs.python.org/issue?@action=redirect&bpo=32892].)

expanduser() en Windows ahora usa preferentemente la variable de entorno USERPROFILE y no usa HOME, que normalmente no está establecido para cuentas de usuario normales. (Contribución de Anthony Sottile en bpo-36264 [https://bugs.python.org/issue?@action=redirect&bpo=36264].)

La excepción asyncio.CancelledError ahora hereda de BaseException en lugar de Exception y ya no hereda de concurrent.futures.CancelledError. (Contribuido por Yury Selivanov en bpo-32528 [https://bugs.python.org/issue?@action=redirect&bpo=32528].)

La función asyncio.wait_for() ahora espera correctamente la cancelación cuando se usa una instancia de asyncio.Task. Anteriormente, al alcanzar timeout, se cancelaba y retornaba de inmediato. (Contribución de Elvis Pranskevichus en bpo-32751 [https://bugs.python.org/issue?@action=redirect&bpo=32751].)

La función asyncio.BaseTransport.get_extra_info() ahora retorna un objeto socket seguro cuando se pasa “socket” al parámetro name. (Contribución de Yury Selivanov en bpo-37027 [https://bugs.python.org/issue?@action=redirect&bpo=37027].)

asyncio.BufferedProtocol ha pasado a formar parte de la API estable.

Las dependencias de DLLs para módulos de extensión y DLLs cargadas con ctypes en Windows ahora se resuelven de forma más segura. Solo las rutas del sistema, el directorio que contiene el archivo DLL o PYD y los directorios agregados mediante add_dll_directory() se buscan para las dependencias en tiempo de carga. Específicamente, PATH y el directorio de trabajo actual ya no se utilizan, y las modificaciones de estos ya no tendrán ningún efecto en la resolución normal de la DLL. Si tu aplicación se basa en estos mecanismos, debes buscar add_dll_directory() y, si existe, utilizarlo para agregar tu directorio DLL mientras carga tu biblioteca. Ten en cuenta que los usuarios de Windows 7 deberán asegurarse de que se haya instalado Windows Update KB2533623 (esto también lo verifica el instalador). (Contribución de Steve Dower en bpo-36085 [https://bugs.python.org/issue?@action=redirect&bpo=36085].)

Los archivos de cabeceras y las funciones relacionadas con pgen se han eliminado después de su reemplazo por una implementación pura de Python. (Contribución de Pablo Galindo en bpo-36623 [https://bugs.python.org/issue?@action=redirect&bpo=36623].)

types.CodeType tiene un nuevo parámetro en la segunda posición del constructor (posonlyargcount) para admitir argumentos solo posicionales, definidos en PEP 570 [https://www.python.org/dev/peps/pep-0570]. El primer argumento (argcount) ahora representa el número total de argumentos posicionales (incluidos los argumentos solo posicionales). El nuevo método replace() de types.CodeType se puede utilizar para hacer que el código esté preparado para el futuro.

The parameter digestmod for hmac.new() no longer uses the MD5 digest by default.

Cambios en la API de C

La estructura PyCompilerFlags tiene un nuevo campo cf_feature_version. Debe inicializarse en PY_MINOR_VERSION. El campo se ignora de forma predeterminada y se usa, si y solo si, el flag PyCF_ONLY_AST está establecido en cf_flags. (Contribución de Guido van Rossum en bpo-35766 [https://bugs.python.org/issue?@action=redirect&bpo=35766].)

La función PyEval_ReInitThreads() se ha eliminado de la API de C. No debe llamarse explícitamente: usa PyOS_AfterFork_Child() en su lugar. (Contribución de Victor Stinner en bpo-36728 [https://bugs.python.org/issue?@action=redirect&bpo=36728].)

En Unix, las extensiones de C ya no están vinculadas a libpython, excepto en Android y Cygwin. Cuando Python está integrado, libpython no debe cargarse con RTLD_LOCAL, sino con RTLD_GLOBAL en su lugar. Anteriormente, no era posible usar RTLD_LOCAL para cargar extensiones de C que no estuvieran vinculadas a libpython, como las extensiones de C de la biblioteca estándar construida por la sección *shared* de Modules/Setup. (Contribución de Victor Stinner en bpo-21536 [https://bugs.python.org/issue?@action=redirect&bpo=21536].)

El uso de variantes de formato # en el análisis o la construcción de valores (por ejemplo: PyArg_ParseTuple(), Py_BuildValue(), PyObject_CallFunction(), etc.) sin PY_SSIZE_T_CLEAN definido ahora lanza una advertencia DeprecationWarning. Se eliminará en Python 3.10 ó 4.0. Consultar Analizando argumentos y construyendo valores para más detalles. (Contribución de Inada Naoki en bpo-36381 [https://bugs.python.org/issue?@action=redirect&bpo=36381].)

Las instancias de tipos asignados al montón (como los creados con PyType_FromSpec()) contienen una referencia a su objeto de tipo. El aumento del recuento de referencias de estos objetos de tipo se ha movido de PyType_GenericAlloc() a las funciones de más bajo nivel, PyObject_Init() y PyObject_INIT(). Esto hace que los tipos creados mediante PyType_FromSpec() se comporten como otras clases en el código gestionado.

Los tipos asignados estáticamente no se ven afectados.

Para la gran mayoría de casos, no debería haber efectos secundarios. Sin embargo, los tipos que aumentan manualmente el recuento de referencias después de asignar una instancia (quizás para evitar el error) ahora pueden volverse inmortales. Para evitar esto, estas clases deben llamar a Py_DECREF en el objeto de tipo durante la desasignación de la instancia.

Para portar correctamente estos tipos a Python 3.8, aplica los siguientes cambios:

Elimina Py_INCREF en el objeto de tipo después de asignar una instancia, si la hubiera. Esto puede suceder después de invocar a PyObject_New(), PyObject_NewVar(), PyObject_GC_New(), PyObject_GC_NewVar(), o cualquier otro asignador personalizado que use PyObject_Init() o PyObject_INIT().

Ejemplo:

static foo_struct *
foo_new(PyObject *type) {
    foo_struct *foo = PyObject_GC_New(foo_struct, (PyTypeObject *) type);
    if (foo == NULL)
        return NULL;
#if PY_VERSION_HEX < 0x03080000
    // Workaround for Python issue 35810; no longer necessary in Python 3.8
    PY_INCREF(type)
#endif
    return foo;
}

Asegúrate de que todas las funciones personalizadas tp_dealloc de los tipos asignados al montón disminuyan el recuento de referencias del tipo.

Ejemplo:

static void
foo_dealloc(foo_struct *instance) {
    PyObject *type = Py_TYPE(instance);
    PyObject_GC_Del(instance);
#if PY_VERSION_HEX >= 0x03080000
    // This was not needed before Python 3.8 (Python issue 35810)
    Py_DECREF(type);
#endif
}

(Contribución de Eddie Elizondo en bpo-35810 [https://bugs.python.org/issue?@action=redirect&bpo=35810].)

La macro Py_DEPRECATED() ha sido implementada para MSVC. La macro ahora debe ser colocada antes del nombre del símbolo.

Ejemplo:

Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);

(Contribución de Zackery Spytz en bpo-33407 [https://bugs.python.org/issue?@action=redirect&bpo=33407].)

El intérprete ya no pretende dar suporte nunca más a la compatibilidad binaria de tipos de extensión entre versiones de características. Un PyTypeObject exportado por un módulo de extensión de terceros se supone que tiene todas las ranuras esperadas por la versión actual de Python, incluyendo tp_finalize (Py_TPFLAGS_HAVE_FINALIZE ya no se verifica antes de leer tp_finalize).

(Contribución de Antoine Pitrou en bpo-32388 [https://bugs.python.org/issue?@action=redirect&bpo=32388].)

Las funciones PyNode_AddChild() y PyParser_AddToken() ahora aceptan dos argumentos int adicionales, end_lineno y end_col_offset.

El archivo libpython38.a ya no se incluye en la distribución normal de Windows. Si se necesita este archivo, se puede generar con las herramientas gendef y dlltool, que son parte del paquete binutils de MinGW:

gendef - python38.dll > tmp.def
dlltool --dllname python38.dll --def tmp.def --output-lib libpython38.a

La ubicación de un archivo pythonXY.dll instalado dependerá de las opciones de instalación y de la versión y el idioma de Windows. Consultar Uso de Python en Windows para obtener más información. La biblioteca resultante debe colocarse en el mismo directorio que pythonXY.lib, que generalmente es el directorio libs en tu instalación de Python.

(Contribución de Steve Dower en bpo-37351 [https://bugs.python.org/issue?@action=redirect&bpo=37351].)

Cambios en el bytecode de CPython

El bucle del intérprete se ha simplificado moviendo al compilador la lógica para el desenredo de la pila de bloques. El compilador ahora emite instrucciones explícitas para ajustar la pila de valores y llamar al código de limpieza para break, continue y return.

Eliminados los códigos de operación BREAK_LOOP, CONTINUE_LOOP, SETUP_LOOP y SETUP_EXCEPT. Agregados los nuevos códigos de operación ROT_FOUR, BEGIN_FINALLY, CALL_FINALLY y POP_FINALLY. Modificados los códigos de operación END_FINALLY y WITH_CLEANUP_START.

(Contribución de Mark Shannon, Antoine Pitrou y Serhiy Storchaka en bpo-17611 [https://bugs.python.org/issue?@action=redirect&bpo=17611].)

Agregado el código de operación END_ASYNC_FOR para manejar excepciones lanzadas mientras se espera al siguiente elemento en un ciclo async for. (Contribución de Serhiy Storchaka en bpo-33041 [https://bugs.python.org/issue?@action=redirect&bpo=33041].)

El código de operación MAP_ADD ahora espera el valor como primer elemento de la pila y la clave como segundo elemento. Este cambio se realizó para que la clave siempre se evalúe antes que el valor en los diccionarios por compresión, como se propone en PEP 572 [https://www.python.org/dev/peps/pep-0572]. (Contribución de Jörn Heissler en bpo-35224 [https://bugs.python.org/issue?@action=redirect&bpo=35224].)

Demos y herramientas

Se ha añadido un script de evaluación de rendimiento para cronometrar varias formas de acceder a variables: Tools/scripts/var_access_benchmark.py. (Contribución de Raymond Hettinger en bpo-35884 [https://bugs.python.org/issue?@action=redirect&bpo=35884].)

A continuación, se muestra un resumen de las mejoras de rendimiento desde Python 3.3:

Python version                       3.3     3.4     3.5     3.6     3.7     3.8
--------------                       ---     ---     ---     ---     ---     ---

Variable and attribute read access:
    read_local                       4.0     7.1     7.1     5.4     5.1     3.9
    read_nonlocal                    5.3     7.1     8.1     5.8     5.4     4.4
    read_global                     13.3    15.5    19.0    14.3    13.6     7.6
    read_builtin                    20.0    21.1    21.6    18.5    19.0     7.5
    read_classvar_from_class        20.5    25.6    26.5    20.7    19.5    18.4
    read_classvar_from_instance     18.5    22.8    23.5    18.8    17.1    16.4
    read_instancevar                26.8    32.4    33.1    28.0    26.3    25.4
    read_instancevar_slots          23.7    27.8    31.3    20.8    20.8    20.2
    read_namedtuple                 68.5    73.8    57.5    45.0    46.8    18.4
    read_boundmethod                29.8    37.6    37.9    29.6    26.9    27.7

Variable and attribute write access:
    write_local                      4.6     8.7     9.3     5.5     5.3     4.3
    write_nonlocal                   7.3    10.5    11.1     5.6     5.5     4.7
    write_global                    15.9    19.7    21.2    18.0    18.0    15.8
    write_classvar                  81.9    92.9    96.0   104.6   102.1    39.2
    write_instancevar               36.4    44.6    45.8    40.0    38.9    35.5
    write_instancevar_slots         28.7    35.6    36.1    27.3    26.6    25.7

Data structure read access:
    read_list                       19.2    24.2    24.5    20.8    20.8    19.0
    read_deque                      19.9    24.7    25.5    20.2    20.6    19.8
    read_dict                       19.7    24.3    25.7    22.3    23.0    21.0
    read_strdict                    17.9    22.6    24.3    19.5    21.2    18.9

Data structure write access:
    write_list                      21.2    27.1    28.5    22.5    21.6    20.0
    write_deque                     23.8    28.7    30.1    22.7    21.8    23.5
    write_dict                      25.9    31.4    33.3    29.3    29.2    24.7
    write_strdict                   22.9    28.4    29.9    27.5    25.2    23.1

Stack (or queue) operations:
    list_append_pop                144.2    93.4   112.7    75.4    74.2    50.8
    deque_append_pop                30.4    43.5    57.0    49.4    49.2    42.5
    deque_append_popleft            30.8    43.7    57.3    49.7    49.7    42.8

Timing loop:
    loop_overhead                    0.3     0.5     0.6     0.4     0.3     0.3

Las evaluaciones de rendimiento se realizaron en un procesador Intel® Core™ i7-4960HQ [https://ark.intel.com/content/www/us/en/ark/products/76088/intel-core-i7-4960hq-processor-6m-cache-up-to-3-80-ghz.html] ejecutando las compilaciones de 64-bits para macOS disponibles en python.org [https://www.python.org/downloads/mac-osx/]. El script de evaluación de rendimiento muestra los tiempos en nanosegundos.

Cambios notables en Python 3.8.1

Debido a importantes preocupaciones de seguridad, el parámetro reuse_address de asyncio.loop.create_datagram_endpoint() ya no está soportado. Esto se debe al comportamiento de la opción SO_REUSEADDR del socket en UDP. Para obtener más detalles, consulta la documentación de loop.create_datagram_endpoint(). (Contribución de Kyle Stanley, Antoine Pitrou y Yury Selivanov en bpo-37228 [https://bugs.python.org/issue?@action=redirect&bpo=37228].)

Cambios notables en Python 3.8.8

Las versiones anteriores de Python permitían usar tanto ; como & como separadores de parámetros de consulta en urllib.parse.parse_qs() y urllib.parse.parse_qsl(). Debido a problemas de seguridad y para cumplir con las recomendaciones más recientes del W3C, esto se ha cambiado para permitir solo una clave separadora, con & como valor predeterminado. Este cambio también afecta a cgi.parse() y cgi.parse_multipart() ya que utilizan las funciones afectadas internamente. Para obtener más detalles, consulte su documentación respectiva. (Contribuido por Adam Goldschmidt, Senthil Kumaran y Ken Jin en bpo-42967 [https://bugs.python.org/issue?@action=redirect&bpo=42967].)

Notable changes in Python 3.8.12

Starting with Python 3.8.12 the ipaddress module no longer accepts any leading zeros in IPv4 address strings. Leading zeros are ambiguous and interpreted as octal notation by some libraries. For example the legacy function socket.inet_aton() treats leading zeros as octal notation. glibc implementation of modern inet_pton() does not accept any leading zeros.

(Originally contributed by Christian Heimes in bpo-36384 [https://bugs.python.org/issue?@action=redirect&bpo=36384], and backported to 3.8 by Achraf Merzouki.)

Que hay de nuevo en Python 3.7

Editor

Elvis Pranskevichus <elvis@magic.io>

El artículo explica las nuevas características en Python 3.7, comparado con 3.6. Python 3.7 fue lanzado el 27, Junio, 2018. Para más detalles, consultar la changelog.

Resumen – Lanzamientos Destacados

Sintaxis de nuevas características:

PEP 563, evaluación pospuesta de anotaciones de tipo.

Cambios de sintaxis incompatibles hacia atrás:

async y await ahora son palabras clave reservadas.

Nuevos módulos de biblioteca:

contextvars: PEP 567 – Variables de Contexto

dataclasses: PEP 557 – Clases de Datos

importlib.resources

Nuevas funciones integradas:

PEP 553, la nueva función breakpoint().

Mejoras en el modelo de datos de Python:

PEP 562, personalización del acceso a los atributos del módulo.

PEP 560, soporte básico para módulo de mecanografía y tipos genéricos.

la naturaleza de conservación del orden de inserción de objetos dict han sido declarado [https://mail.python.org/pipermail/python-dev/2017-December/151283.html] para ser una parte oficial de la especificación del lenguaje Python.

Mejoras significativas in la librería estándar:

El modulo asyncio ha recibido nuevas funciones, significativas mejoras de usabilidad y rendimiento.

El modulo time adquirió soporte de funciones con resolución de nanosegundos.

Mejoras en la implementación de CPython:

Evitando el uso de ASCII como codificación de texto predeterminada:

PEP 538, coerción de configuración regional de C heredada

PEP 540, modo de tiempo de ejecución UTF-8 forzado

PEP 552, determinista .pycs

El nuevo modo de ejecución de desarrollo

PEP 565, manejo mejorado DeprecationWarning

Mejoras en la API de C:

PEP 539, nueva API de C para almacenamiento local de subprocesos

Mejoras de Documentación:

PEP 545, Traducción de documentación de Python

Nuevas traducciones de documentación: Japonés [https://docs.python.org/ja/], Francés [https://docs.python.org/fr/], y Coreano [https://docs.python.org/ko/].

Esta versión presenta notables mejoras de rendimiento en muchas áreas. La sección Optimizaciones los enumera en detalle.

Para obtener una lista de cambios que pueden afectar la compatibilidad con versiones anteriores de Python por favor consultar la sección Portando a Python 3.7.

Nuevas Características

PEP 563: Evaluación pospuesta de anotaciones

La llegada de las sugerencias de tipo en Python descubrió dos problemas de usabilidad evidentes con la funcionalidad de las anotaciones agregadas en PEP 3107 [https://www.python.org/dev/peps/pep-3107] y mas refinado en PEP 526 [https://www.python.org/dev/peps/pep-0526]:

las anotaciones solo podían usar nombres que ya estaban disponibles en el alcance actual, en otras palabras, no admitían referencias futuras de ningún tipo; y

anotar el código fuente tuvo efectos adversos en el tiempo de inicio de los programas Python.

Ambos problemas se solucionan posponiendo la evaluación de anotaciones. En lugar de compilar código que ejecuta expresiones en anotaciones en su momento de definición, el compilador almacena la anotación en forma de cadena equivalente al AST de la expresión en cuestión. Si es necesario, las anotaciones se pueden resolver en tiempo de ejecución usando typing.get_type_hints(). En el común de los casos esto no es necesario, las anotaciones son más fáciles de almacenar (dado que las cadenas cortas son internadas por el intérprete.) y hacen que el tiempo de inicio sea mas rápido.

En términos de usabilidad, las anotaciones ahora admiten referencias hacia adelante, lo que hace que la siguiente sintaxis sea válida:

class C:
    @classmethod
    def from_string(cls, source: str) -> C:
        ...

    def validate_b(self, obj: B) -> bool:
        ...

class B:
    ...

Dado que este cambio rompe la compatibilidad, el nuevo comportamiento debe habilitarse por modulo en Python 3.7 usando una importación __future__:

from __future__ import annotations

Se convertirá en el predeterminado en Python 3.10.

Ver también

PEP 563 [https://www.python.org/dev/peps/pep-0563] – Evaluación aplazada de anotaciones

PEP escrito y implementado por Łukasz Langa.

PEP 538: Coerción de configuración regional del Legado de C

Un desafío continuo dentro de la serie Python 3 ha sido determinar una estrategia predeterminada sensata para manejar el supuesto de codificación de texto “ASCII de 7 bits” implícito actualmente en el uso de la configuración regional C o POSIX predeterminada en plataformas que no son Windows.

PEP 538 [https://www.python.org/dev/peps/pep-0538] actualiza la interfaz de línea de comandos del intérprete predeterminada para convertir automáticamente esa configuración regional en una configuración regional basada en UTF-8 disponible, como se describe en la documentación de la nueva variable de entorno PYTHONCOERCECLOCALE. Configurar automáticamente LC_CTYPE de esta manera significa que tanto el intérprete central como las extensiones C que reconocen la configuración regional (por ejemplo readline) asumirá el uso de UTF-8 como codificación de texto predeterminada, en lugar de ASCII.

La definición de soporte de plataforma en PEP 11 [https://www.python.org/dev/peps/pep-0011] también se ha actualizado para limitar la compatibilidad con el manejo de texto completo a configuraciones regionales no basadas en ASCII configuradas adecuadamente.

Como parte de este cambio, el controlador de errores predeterminado para stdin y stdout es ahora surrogateescape (antes que strict) al usar cualquiera de las configuraciones regionales de destino de coerción definidas (actualmente C.UTF-8, C.utf8, y UTF-8). El controlador de errores predeterminado para stderr continua siendo backslashreplace, independientemente de local.

La coerción local es silenciosa de forma predeterminada, pero para ayudar a depurar problemas de integración potencialmente relacionados con la configuración regional, advertencias explícitas (emitido directamente en stderr) se puede solicitar configurando PYTHONCOERCECLOCALE=warn. Esta configuración también hará que el tiempo de ejecución de Python emita una advertencia si la configuración regional C heredada permanece activa cuando se inicializa el intérprete principal.

Mientras la coerción local PEP 538 [https://www.python.org/dev/peps/pep-0538] tiene la ventaja de afectar también a los módulos de extensión (como GNU readline), así como procesos secundarios (incluidos los que ejecutan aplicaciones que no son de Python y versiones anteriores de Python), tiene la desventaja de requerir que esté presente una ubicación de destino adecuada en el sistema en ejecución. Para manejar mejor el caso en el que no hay una configuración regional de destino adecuada disponible (como ocurre en RHEL / CentOS 7, por ejemplo), Python 3.7 también implementa PEP 540: Modo de tiempo de ejecución UTF-8 forzado.

Ver también

PEP 538 [https://www.python.org/dev/peps/pep-0538] – Coaccionar la configuración regional C heredada a una configuración regional basada en UTF-8

PEP escrito y implementado por Nick Coghlan.

PEP 540: Modo de tiempo de ejecución UTF-8 forzado

La nueva opción de lineas de comando -X utf8 y la variable de entorno PYTHONUTF8 se puede utilizar para habilitar el modo CPython modo UTF-8.

Cuando está en modo UTF-8, CPython ignora la configuración regional y usa la codificación UTF-8 de forma predeterminada. Los controladores de errores para los flujos sys.stdin y sys.stdout se establecen en surrogateescape.

El modo UTF-8 forzado se puede usar para cambiar el comportamiento de manejo de texto en un intérprete de Python integrado sin cambiar la configuración regional de una aplicación de inserción.

Mientras el modo UTF-8 PEP 540 [https://www.python.org/dev/peps/pep-0540] tiene la ventaja de funcionar independientemente de las configuraciones regionales disponibles en el sistema en ejecución, tiene la desventaja de no tener ningún efecto en los módulos de extensión (como GNU readline), procesos secundarios que ejecutan aplicaciones que no son de Python y procesos secundarios que ejecutan versiones anteriores de Python. Para reducir el riesgo de dañar los datos de texto al comunicarse con dichos componentes, Python 3.7 también implementa PEP 540: Modo de tiempo de ejecución UTF-8 forzado.

El modo UTF-8 está habilitado de forma predeterminada cuando la configuración regional es C o POSIX, y la función de coerción local PEP 538 [https://www.python.org/dev/peps/pep-0538] no lo cambia a una alternativa basada en UTF-8 (si ese fallo se debe a que se ha establecido PYTHONCOERCECLOCALE=0, LC_ALL se esta configurando, o la falta de un lugar de destino adecuado).

Ver también

PEP 540 [https://www.python.org/dev/peps/pep-0540] – Agrega un nuevo modo UTF-8

PEP escrito y implementado por Victor Stinner

PEP 553: Incorporada en breakpoint()

Python 3.7 incluye la nueva función incorporada breakpoint() como una forma fácil y consistente de ingresar al depurador de Python.

Llamadas breakpoint() incorporadas en sys.breakpointhook(). Por defecto, este último importa pdb y luego llama pdb.set_trace(), pero vinculando sys.breakpointhook() a la función de su elección, breakpoint() puede entrar en cualquier depurador. Adicionalmente, la variable de entorno PYTHONBREAKPOINT se puede configurar como el depurador que elija. Configure PYTHONBREAKPOINT=0 para deshabilitar completamente el breakpoint().

Ver también

PEP 553 [https://www.python.org/dev/peps/pep-0553] – Incorporada en breakpoint()

PEP escrito y implementado por Barry Warsaw

PEP 539: Nueva API C para almacenamiento local de subprocesos

Mientras que Python proporciona una API C para soporte de almacenamiento local de subprocesos; la existencia Almacenamiento local de subprocesos (TLS) API ha usado int para representar llaves TLS a través de todas las plataformas. En general, esto no ha sido un problema para las plataformas de soporte oficial, pero no es compatible con POSIX ni es portátil en ningún sentido práctico.

PEP 539 [https://www.python.org/dev/peps/pep-0539] cambio esto proporcionado un nuevo Almacenamiento especifico de subprocesos (TSS) API para CPython que reemplaza el uso de la API de TLS existente dentro del intérprete de CPython, mientras que desaprueba la API existente. La API de TSS usa un nuevo tipo Py_tss_t en lugar de int para representar llaves TSS — un tipo opaco cuya definición puede depender de la implementación TLS subyacente. Por lo tanto, esto permitirá construir CPython en plataformas dónde la clave TLS nativa está definida de una manera que no se puede convertir de manera segura a int.

Tenga en cuenta que en las plataformas donde la clave TLS nativa se define de una manera que no se puede convertir de forma segura a int, todas las funciones de la API TLS existente serán inactivas y devolverán el error inmediatamente. Esto indica claramente que la API anterior no es compatible con plataformas en las que no se puede usar de manera confiable y que no se hará ningún esfuerzo para agregar dicha compatibilidad.

Ver también

PEP 539 [https://www.python.org/dev/peps/pep-0539] – Un nueva API-C para almacenamiento local de subprocesos en CPython

PEP escrito por Erik M. Bray; implementación por Masayuki Yamamoto.

PEP 562: Personalización del acceso a los atributos del módulo

Python 3.7 permite definir __getattr__() en módulos y lo llamará siempre que no se encuentre un atributo de módulo. Definir __dir__() en modules ahora también esta permitido.

Un ejemplo típico de dónde esto puede ser útil es la desaprobación de los atributos del módulo y la carga diferida.

Ver también

PEP 562 [https://www.python.org/dev/peps/pep-0562] – Módulo __getattr__ y __dir__

PEP escrito y implementado por Ivan Levkivskyi

PEP 564: Nuevas funciones de tiempo con resolución de nanosegundos

La resolución de los relojes en los sistemas modernos puede exceder la precisión limitada de un número de punto flotante devuelto por la función time.time() y sus variantes. Para evitar la pérdida de precisión, PEP 564 [https://www.python.org/dev/peps/pep-0564] agrega seis nuevas variantes de “nanosegundos” de las funciones de temporizador existentes para el módulo time:

time.clock_gettime_ns()

time.clock_settime_ns()

time.monotonic_ns()

time.perf_counter_ns()

time.process_time_ns()

time.time_ns()

Las nuevas funciones devuelven el número de nanosegundos como un valor entero.

Mediciones [https://www.python.org/dev/peps/pep-0564/#annex-clocks-resolution-in-python] se muestra en Linux y Windows la resolución de time.time_ns() es aproximadamente 3 veces mejor que el de time.time().

Ver también

PEP 564 [https://www.python.org/dev/peps/pep-0564] – Agrega nuevas funciones de tiempo y resolución de nanosegundos

PEP escrito y implementado por Victor Stinner

PEP 565: Mostrar DeprecationWarning en __main__

El manejo predeterminado de DeprecationWarning Se ha cambiado de modo que estas advertencias se muestren una vez más de forma predeterminada, pero solo cuando el código que las activa se ejecuta directamente en el módulo __main__. Como resultado, los desarrolladores de scripts de un solo archivo y aquellos que usan Python de forma interactiva deberían comenzar a ver una vez más advertencias de desaprobación para las API que usan, pero las advertencias de desaprobación activadas por la aplicación importada, la biblioteca y los módulos de marco seguirán ocultos de forma predeterminada.

Como resultado de este cambio, la biblioteca estándar ahora permite a los desarrolladores elegir entre tres comportamientos de advertencia de obsolescencia diferentes:

FutureWarning: siempre se muestra por defecto, recomendado para las advertencias destinadas a los usuarios finales de la aplicación (por ejemplo, para los ajustes de configuración de la aplicación obsoletos).

DeprecationWarning: se muestra por defecto solo en __main__ y cuando se ejecutan pruebas, se recomienda para advertencias destinadas a ser vistas por otros desarrolladores de Python donde una actualización de la versión puede resultar en un cambio de comportamiento o un error.

PendingDeprecationWarning: se muestra de forma predeterminada solo cuando se ejecutan pruebas, diseñado para casos en los que una actualización de versión futura cambiará la categoría de advertencia a DeprecationWarning o FutureWarning.

Anteriormente ambos DeprecationWarning y PendingDeprecationWarning solo eran visibles cuando se ejecutaban pruebas, lo que significaba que los desarrolladores que escribían principalmente scripts de un solo archivo o usaban Python de forma interactiva podrían sorprenderse al ver cambios importantes en las API que usaban.

Ver también

PEP 565 [https://www.python.org/dev/peps/pep-0565] – Muestra DeprecationWarning en __main__

PEP escrito y implementado por Nick Coghlan

PEP 560: Soporte básico para el módulo de typing y tipos genéricos

Inicialmente PEP 484 [https://www.python.org/dev/peps/pep-0484] fue diseñado de tal manera que no introduciría * ningún * cambio en el intérprete principal de CPython. Ahora escriba sugerencias y el módulo typing son ampliamente utilizados por la comunidad, por lo que se elimina esta restricción. El PEP introduce dos métodos especiales __class_getitem__() y __mro_entries__, estos métodos ahora son utilizados por la mayoría de las clases y construcciones especiales en typing. Como resultado, la velocidad de varias operaciones con tipos aumentó hasta 7 veces, los tipos genéricos se pueden usar sin conflictos de metaclase, y varios errores de larga data en el módulo typing han sido arreglados.

Ver también

PEP 560 [https://www.python.org/dev/peps/pep-0560] – Soporte básico para el modulo de escritura y tipos genéricos

PEP escrito y implementado por Ivan Levkivskyi

PEP 552: Archivos .pyc basados en hash

Python ha verificado tradicionalmente la actualización de los archivos de caché de código de bytes (es decir, archivos .pyc) comparando los metadatos de origen (marca de tiempo y tamaño de última modificación) con la fuente de metadatos guardados en el encabezado del archivo de caché cuando se generó. Si bien es efectivo, este método de invalidación tiene sus inconvenientes. Cuando las marcas de tiempo del sistema de archivos son demasiado burdas, Python puede perder las actualizaciones de origen, lo que genera confusión en el usuario. Además, tener una marca de tiempo en el archivo de caché es problemático para construir reproducibilidad [https://reproducible-builds.org/] y sistemas de construcción basados en contenido.

PEP 552 [https://www.python.org/dev/peps/pep-0552] extendiendo el formato ppc para permitir que el hash del archivo de origen se utilice para invalidación en lugar de la marca de tiempo de origen. Estos archivos .pyc se denominan “hash-based”. Por defecto, Python todavía usa la invalidación basada en la marca de tiempo y no genera archivos .pyc basados en has de tiempos de ejecución. Los archivos .pyc basados en hash se pueden generar con py_compile o compileall.

Archivos .pyc basados en hash Vienen en dos variantes: marcada y no marcada. Python valida los archivos .pyc basados en hash comprobados con los archivos de origen correspondientes en tiempo de ejecución, pero no lo hace para pycs basados en hash no verificados. Archivos .pyc no comprobados son una optimización de rendimiento útil para entornos donde un sistema externo a Python (por ejemplo, el sistema de compilación) es responsable de mantener actualizados los archivos .pyc.

Consultar Invalidación del código de bytes en caché para mas información.

Ver también

PEP 552 [https://www.python.org/dev/peps/pep-0552] – Pycs deterministas

PEP escrito y implementado por Benjamin Peterson

PEP 545: Traducciones de Documentaciones de Python

PEP 545 [https://www.python.org/dev/peps/pep-0545] describe el proceso de creación y mantenimiento de traducciones de documentación de Python.

Tres nuevas traducciones han sido agregadas:

Japonés: https://docs.python.org/ja/

Francés: https://docs.python.org/fr/

Coreano: https://docs.python.org/ko/

Ver también

PEP 545 [https://www.python.org/dev/peps/pep-0545] – Traducciones de Documentación de Python

PEP escrito y implementado por Julien Palard, Inada Naoki y Victor Stinner.

Modo de desarrollo de Python (-X dev)

La nueva opción -X dev opción de línea de comando o la nueva variable de entorno PYTHONDEVMODE se puede usar para habilitar Python Development Mode. Cuando está en modo de desarrollo, Python realiza comprobaciones de tiempo de ejecución adicionales que son demasiado caras para habilitarse de forma predeterminada. Ver Python Development Mode documentación para la descripción completa.

Otros cambios en el lenguaje

Una expresión await y compresiones que contienen una cláusula async for eran ilegales en las expresiones en formatted string literals debido a un problema con la implementación. En Python 3.7 se eliminó esta restricción.

Ahora se pueden pasar más de 255 argumentos a una función y una función ahora puede tener más de 255 parámetros. (Contribuido por Serhiy Storchaka en bpo-12844 [https://bugs.python.org/issue?@action=redirect&bpo=12844] y bpo-18896 [https://bugs.python.org/issue?@action=redirect&bpo=18896].)

bytes.fromhex() y bytearray.fromhex() ahora ignore todos los espacios en blanco ASCII, no solo los espacios. (Contribuido por Robert Xiao en bpo-28927 [https://bugs.python.org/issue?@action=redirect&bpo=28927].)

str, bytes, y bytearray adquirió soporte para el nuevo método isascii(), que se puede usar para probar si una cadena o bytes contienen solo los caracteres ASCII. (Contribuido por INADA Naoki en bpo-32677 [https://bugs.python.org/issue?@action=redirect&bpo=32677].)

ImportError ahora muestra el nombre del módulo y la ruta del módulo __file__ cuando falla from … import …. (Contribuido por Matthias Bussonnier en bpo-29546 [https://bugs.python.org/issue?@action=redirect&bpo=29546].)

Ahora se admiten las importaciones circulares que involucran importaciones absolutas con un submódulo vinculado a un nombre. (Contribuido por Serhiy Storchaka en bpo-30024 [https://bugs.python.org/issue?@action=redirect&bpo=30024].)

object.__format__(x, ‘’) ahora es equivalente a str(x) antes que format(str(self), ‘’). (Contribuido por Serhiy Storchaka en bpo-28974 [https://bugs.python.org/issue?@action=redirect&bpo=28974].)

Para soportar mejor la creación dinámica de seguimientos de pila, types.TracebackType ahora se puede crear una instancia desde el código Python, y el atributo tb_next en on rastreos ahora se puede escribir. (Contribuido por Nathaniel J. Smith en bpo-30579 [https://bugs.python.org/issue?@action=redirect&bpo=30579].)

Al usar la -m switch, sys.path[0] ahora se expande con entusiasmo a la ruta completa del directorio de inicio, en lugar de dejarse como el directorio vacío (que permite importaciones desde el directorio de trabajo * actual * en el momento en que ocurre una importación) (Contribuido por Nick Coghlan en bpo-33053 [https://bugs.python.org/issue?@action=redirect&bpo=33053].)

The new -X importtime option or the PYTHONPROFILEIMPORTTIME environment variable can be used to show the timing of each module import. (Contributed by Inada Naoki in bpo-31415 [https://bugs.python.org/issue?@action=redirect&bpo=31415].)

Nuevos módulos

contextvars

El nuevo módulo contextvars y un conjunto de nuevas APIs C introducir soporte para variables de contexto. Las variables de contexto son conceptualmente similares a las variables locales del proceso. A diferencia de TLS, las variables de contexto admiten l código asincrónico correctamente.

Los módulos asyncio y decimal se han actualizado para utilizar y admitir variables de contexto listas para usar. En particular, el contexto decimal activo ahora se almacena en una variable de contexto, lo que permite que las operaciones decimales funcionen con el contexto correcto en código asincrónico.

Ver también

PEP 567 [https://www.python.org/dev/peps/pep-0567] – Variables de Contexto

PEP escrito y implementado por Yury Selivanov

dataclasses

El nuevo decorador dataclass() proporciona una forma de declarar data classes. Una clase de datos describe sus atributos usando anotaciones de variables de clase. Su constructor y otros métodos mágicos, como __repr__(), __eq__(), y __hash__() se generan automáticamente.

Ejemplo:

@dataclass
class Point:
    x: float
    y: float
    z: float = 0.0

p = Point(1.5, 2.5)
print(p)   # produces "Point(x=1.5, y=2.5, z=0.0)"

Ver también

PEP 557 [https://www.python.org/dev/peps/pep-0557] – Clases de Datos

PEP escrito y implementado por Eric V. Smith

importlib.resources

El nuevo módulo importlib.resources proporciona varias API nuevas y un ABC nuevo para acceder, abrir y leer * recursos * dentro de los paquetes. Los recursos son más o menos similares a los archivos dentro de los paquetes, pero no es necesario que sean archivos reales en el sistema de archivos físico. Los cargadores de módulos proporcionar una función get_resource_reader() que devuelve una instancia importlib.abc.ResourceReader para admitir esta nueva API. Los cargadores de ruta de archivo integrados y los cargadores de archivos zip admiten esto.

Contribuido por Barry Warsaw y Brett Cannon en bpo-32248 [https://bugs.python.org/issue?@action=redirect&bpo=32248].

Ver también

importlib_resources [http://importlib-resources.readthedocs.io/en/latest/] – un backport de PyPI para versiones anteriores de Python.

Módulos mejorados

argparse

El nuevo método ArgumentParser.parse_intermixed_args() permite permite entremezclar opciones y argumentos posicionales. (Contribuido por paul.j3 en bpo-14191 [https://bugs.python.org/issue?@action=redirect&bpo=14191].)

asyncio

El modulo asyncio ha recibido muchas funciones nuevas, usabilidad y mejoras de rendimiento. Los cambios notables incluyen:

La nueva función provisional asyncio.run() se puede utilizar para ejecutar una corrutina desde código síncrono creando y destruyendo automáticamente el bucle de eventos. (Contribuido por Yury Selivanov en bpo-32314 [https://bugs.python.org/issue?@action=redirect&bpo=32314].)

asyncio adquirió soporte para contextvars. loop.call_soon(), loop.call_soon_threadsafe(), loop.call_later(), loop.call_at(), y Future.add_done_callback() tener un nuevo parámetro opcional * de contexto * solo de palabras clave. Tasks ahora rastrea su contexto automáticamente. Ver PEP 567 [https://www.python.org/dev/peps/pep-0567] para mas detalles. (Contribuido por Yury Selivanov en bpo-32436 [https://bugs.python.org/issue?@action=redirect&bpo=32436].)

La nueva función asyncio.create_task`se ha agregado como un atajo a ``asyncio.get_event_loop().create_task()`(). (Contribuido por Andrew Svetlov en bpo-32311 [https://bugs.python.org/issue?@action=redirect&bpo=32311].)

El nuevo método loop.start_tls() puede ser usado para actualizar una conexión existente para TLS. (Contribuido por Yury Selivanov en bpo-23749 [https://bugs.python.org/issue?@action=redirect&bpo=23749].)

El nuevo método loop.sock_recv_into() permite leer datos de un socket directamente en un búfer proporcionado, lo que permite reducir las copias de datos. (Contribuido por Antoine Pitrou en bpo-31819 [https://bugs.python.org/issue?@action=redirect&bpo=31819].)

La nueva función asyncio.current_task() devuelve la instancia actual en ejecución Task, y la nueva función asyncio.all_tasks() devuelve un conjunto de todas las instancias de Task existentes en un bucle determinado. Los métodos Task.current_task() y Task.all_tasks() han quedado obsoletos. (Contribuido por Andrew Svetlov en bpo-32250 [https://bugs.python.org/issue?@action=redirect&bpo=32250].)

La nueva clase provisional BufferedProtocol permite implementar protocolos de transmisión con control manual sobre el búfer de recepción. (Contribuido por Yury Selivanov en bpo-32251 [https://bugs.python.org/issue?@action=redirect&bpo=32251].)

La nueva función asyncio.get_running_loop() devuelve el bucle que se está ejecutando actualmente, y genera un RuntimeError si el bucle esta corriendo. Esto contrasta con asyncio.get_event_loop(), que * creará * un nuevo bucle de eventos si no se está ejecutando ninguno. (Contribuido por Yury Selivanov en bpo-32269 [https://bugs.python.org/issue?@action=redirect&bpo=32269].)

El nuevo método de rutina StreamWriter.wait_closed() permite esperar hasta que se cierre el escritor de secuencias. El nuevo método StreamWriter.is_closing() puede ser usado para determinar si el escritor esta cerrando. (Contribuido por Andrew Svetlov en bpo-32391 [https://bugs.python.org/issue?@action=redirect&bpo=32391].)

El nuevo método de rutina loop.sock_sendfile() permite enviar archivos usando os.sendfile cuando sea posible. (Contribuido por Andrew Svetlov en bpo-32410 [https://bugs.python.org/issue?@action=redirect&bpo=32410].)

El nuevo método Future.get_loop() y Task.get_loop() devuelve la instancia del bucle en el que se creó una tarea o un futuro. Server.get_loop() permite hacer lo mismo para objetos de asyncio.Server. (Contribuido por Yury Selivanov en bpo-32415 [https://bugs.python.org/issue?@action=redirect&bpo=32415] y Srinivas Reddy Thatiparthy en bpo-32418 [https://bugs.python.org/issue?@action=redirect&bpo=32418].)

Ahora es posible controlar las instancias de asyncio.Server cuando comienzan. Anteriormente, el servidor comenzaba a funcionar inmediatamente cuando se creaba. El nuevo argumento de palabra clave start_serving para loop.create_server() y loop.create_unix_server(), así como Server.start_serving(), y Server.serve_forever() se puede usar para desacoplar la instanciación y el servicio de servidor. El nuevo método Server.is_serving() devuelve True si el servidor esta iniciando. Server los objetos ahora son administradores de contexto asíncronos:

srv = await loop.create_server(...)

async with srv:
    # some code

# At this point, srv is closed and no longer accepts new connections.

(Contribuido por Yury Selivanov en bpo-32662 [https://bugs.python.org/issue?@action=redirect&bpo=32662].)

Objetos de devolución de llamada devueltos por loop.call_later() conseguir el nuevo método when() que devuelve una marca de tiempo de devolución de llamada programada absoluta. (Contribuido por Andrew Svetlov en bpo-32741 [https://bugs.python.org/issue?@action=redirect&bpo=32741].)

El método loop.create_datagram_endpoint() adquirió soporte para sockets UNIX.(Contribuido por Quentin Dawans en bpo-31245 [https://bugs.python.org/issue?@action=redirect&bpo=31245].)

Los métodos asyncio.open_connection(), asyncio.start_server() functions, loop.create_connection(), loop.create_server(), loop.create_accepted_socket() <asyncio.loop.connect_accepted_socket>`y sus correspondientes variantes de socket UNIX ahora aceptan el argumento de palabra clave *ssl_handshake_timeout*. (Contribuido por *Neil Aspinall* en :issue:`29970().)

El nuevo método Handle.cancelled() devuelve True si se canceló la devolución de llamada. (Contribuido por Marat Sharafutdinov en bpo-31943 [https://bugs.python.org/issue?@action=redirect&bpo=31943].)

La fuente asyncio se ha convertido para utilizar la sintaxis async/await. (Contribuido por Andrew Svetlov en bpo-32193 [https://bugs.python.org/issue?@action=redirect&bpo=32193].)

El nuevo método ReadTransport.is_reading() puede ser usado para determinar el estado de lectura del transporte. Adicionalmente, las llamadas a ReadTransport.resume_reading() y ReadTransport.pause_reading() ahora son idempotentes. (Contribuido por Yury Selivanov en bpo-32356 [https://bugs.python.org/issue?@action=redirect&bpo=32356].)

Los métodos de bucle que aceptan rutas de socket ahora admiten el paso objetos con forma de ruta. (Contribuido por Yury Selivanov en bpo-32066 [https://bugs.python.org/issue?@action=redirect&bpo=32066].)

En asyncio, los sockets TCP en Linux ahora son creados con el indicador TCP_NODELAY configurado por defecto. (Contribuido por Yury Selivanov y Victor Stinner en bpo-27456 [https://bugs.python.org/issue?@action=redirect&bpo=27456].)

Las excepciones que ocurren en tareas canceladas ya no se registran. (Contribuido por Yury Selivanov en bpo-30508 [https://bugs.python.org/issue?@action=redirect&bpo=30508].)

Nuevas clases WindowsSelectorEventLoopPolicy y WindowsProactorEventLoopPolicy. (Contribuido por Yury Selivanov en bpo-33792 [https://bugs.python.org/issue?@action=redirect&bpo=33792].)

Varias APIs asyncio se han obsoleta.

binascii

La función b2a_uu() ahora acepta un argumento de palabra clave opcional backtick. Cuando es cierto, los ceros están representados por ’`’ en lugar de espacios. (Contribuido por Xiang Zhang en bpo-30103 [https://bugs.python.org/issue?@action=redirect&bpo=30103].)

calendar

La clase (Contribuido por *Oz Tiram* en :issue:`30095.)

collections

collections.namedtuple() ahora soporta valores por defecto. (Contribuido por Raymond Hettinger en bpo-32320 [https://bugs.python.org/issue?@action=redirect&bpo=32320].)

compileall

compileall.compile_dir() aprendió el nuevo parámetro invalidation_mode, que se puede utilizar para habilitar invalidación de .pyc basada en hash. El modo de invalidación también se puede especificar en la línea de comando usando el nuevo argumento —invalidation-mode. (Contribuido por Benjamin Peterson en bpo-31650 [https://bugs.python.org/issue?@action=redirect&bpo=31650].)

concurrent.futures

ProcessPoolExecutor y ThreadPoolExecutor ahora soporta los nuevos argumentos de constructor initializer y initargs. (Contribuido por Antoine Pitrou en bpo-21423 [https://bugs.python.org/issue?@action=redirect&bpo=21423].)

La ProcessPoolExecutor puede ahora tomar el contexto de multiprocesamiento a través del nuevo argumento mp_context. (Contribuido por Thomas Moreau en bpo-31540 [https://bugs.python.org/issue?@action=redirect&bpo=31540].)

contextlib

El nuevo nullcontext() es un administrador de contexto sin operaciones simple y rápido que ExitStack. (Contribuido por Jesse-Bakker en bpo-10049 [https://bugs.python.org/issue?@action=redirect&bpo=10049].)

Se han añadido los nuevos asynccontextmanager(), AbstractAsyncContextManager, y AsyncExitStack para complementar sus partes sincronicas. (Contribuido por Jelle Zijlstra en bpo-29679 [https://bugs.python.org/issue?@action=redirect&bpo=29679] y bpo-30241 [https://bugs.python.org/issue?@action=redirect&bpo=30241], y por Alexander Mohr y Ilya Kulakov en bpo-29302 [https://bugs.python.org/issue?@action=redirect&bpo=29302].)

cProfile

La linea de comandos cProfile ahora acepta -m module_name como alternativa a la ruta del script. (Contribuido por Sanyam Khurana en bpo-21862 [https://bugs.python.org/issue?@action=redirect&bpo=21862].)

crypt

El módulo crypt ahora es compatible con el método de hash Blowfish. (Contribuido por Serhiy Storchaka en bpo-31664 [https://bugs.python.org/issue?@action=redirect&bpo=31664].)

La función mksalt() ahora permite especificar el número de rondas para el hash. (Contribuido por Serhiy Storchaka en bpo-31702 [https://bugs.python.org/issue?@action=redirect&bpo=31702].)

datetime

Los nuevos objetos datetime.fromisoformat() un método constructor datetime de una cadena en uno de los formatos de salida de datetime.isoformat(). (Contribuido por Paul Ganssle en bpo-15873 [https://bugs.python.org/issue?@action=redirect&bpo=15873].)

La clase tzinfo ahora admite compensaciones de subminutos. (Contribuido por Alexander Belopolsky en bpo-5288 [https://bugs.python.org/issue?@action=redirect&bpo=5288].)

dbm

dbm.dumb ahora admite la lectura de archivos de solo lectura y ya no escribe el archivo de índice cuándo no se cambia.

decimal

El módulo decimal ahora usa variables de contexto para almacenar el contexto decimal. (Contribuido por Yury Selivanov en bpo-32630 [https://bugs.python.org/issue?@action=redirect&bpo=32630].)

dis

La función dis() ahora puede desensamblar objetos de código anidados (el código de comprensiones, expresiones generadoras y funciones anidadas, y el código utilizado para construir clases anidadas). La profundidad máxima de la recursividad de desmontaje se controla mediante el nuevo parámetro * profundidad . (Contribuido por *Serhiy Storchaka en bpo-11822 [https://bugs.python.org/issue?@action=redirect&bpo=11822].)

distutils

README.rst ahora se incluye en la lista de READMEs estándar de distutils y, por lo tanto, se incluye en las distribuciones de código fuente. (Contribuido por Ryan Gonzalez en bpo-11913 [https://bugs.python.org/issue?@action=redirect&bpo=11913].)

enum

La Enum aprendió la nueva propiedad de clase _ignore_, que permite enumerar los nombres de propiedades que no deben convertirse en miembros de enumeración. (Contribuido por Ethan Furman en bpo-31801 [https://bugs.python.org/issue?@action=redirect&bpo=31801].)

En Python 3.8, intentar buscar objetos que no sean Enum en Enum generará un TypeError (por ejemplo, 1 in Color); de manera similar, si se intenta buscar objetos que no sean Flag en un miembro Flag se generará TypeError (por ejemplo, 1 in Perm.RW); actualmente, ambas operaciones devuelven False en su lugar y están obsoletas.

functools

functools.singledispatch() ahora admite el registro de implementaciones mediante anotaciones de tipo. (Contribuido por Łukasz Langa en bpo-32227 [https://bugs.python.org/issue?@action=redirect&bpo=32227].)

gc

La nueva función gc.freeze() permite congelar todos los objetos rastreados por el recolector de basura y excluirlos de colecciones futuras. Esto se puede utilizar antes de llamar POSIX fork() para hacer que la copia en escritura de GC sea amigable o para acelerar la recopilación. La nuevas funciones gc.unfreeze() revierten esta operación. Además, gc.get_freeze_count() se puede utilizar para obtener el número de objetos congelados. (Contribuido por Li Zekun en bpo-31558 [https://bugs.python.org/issue?@action=redirect&bpo=31558].)

hmac

El módulo hmac ahora tiene una función one-shot optimizada digest(), que es hasta tres veces más rápida que HMAC().

http.client

HTTPConnection y HTTPSConnection ahora admite el nuevo argumento * tamaño de bloque * para mejorar el rendimiento de carga. (Contribuido por Nir Soffer en bpo-31945 [https://bugs.python.org/issue?@action=redirect&bpo=31945].)

http.server

SimpleHTTPRequestHandler ahora admite el encabezado HTTP If-Modified-Since. El servidor devuelve el estado de respuesta 304 si el archivo de destino no se modificó después del tiempo especificado en el encabezado. (Contribuido por Pierre Quentel en bpo-29654 [https://bugs.python.org/issue?@action=redirect&bpo=29654].)

SimpleHTTPRequestHandler acepta el nuevo argumento directorio, además del nuevo argumento de línea de comando —directory. Con este parámetro, el servidor sirve el directorio especificado, por defecto usa el directorio de trabajo actual. (Contribuido por Stéphane Wirtel y Julien Palard en bpo-28707 [https://bugs.python.org/issue?@action=redirect&bpo=28707].)

La nueva clase ThreadingHTTPServer usa procesos para manejar solicitudes usando ThreadingMixin. Se usa cuando se ejecuta http.server con -m. (Contribuido por Julien Palard en bpo-31639 [https://bugs.python.org/issue?@action=redirect&bpo=31639].)

idlelib and IDLE

Varias correcciones para autocompletar. (Contribuido por Louie Lu en bpo-15786 [https://bugs.python.org/issue?@action=redirect&bpo=15786].)

El Explorador de módulos (en el menú Archivo, antes llamado Explorador de clases), ahora muestra funciones y clases anidadas además de funciones y clases de nivel superior. (Contribuido por Guilherme Polo, Cheryl Sabella, y Terry Jan Reedy en bpo-1612262 [https://bugs.python.org/issue?@action=redirect&bpo=1612262].)

El cuadro de diálogo Configuración (Opciones, Configurar IDLE) se ha reescrito parcialmente para mejorar tanto la apariencia como la función. (Contribuido por Cheryl Sabella y Terry Jan Reedy en múltiple issues.)

La muestra de fuente ahora incluye una selección de caracteres no latinos para que los usuarios puedan ver mejor el efecto de seleccionar una fuente en particular. (Contribuido por Terry Jan Reedy en bpo-13802 [https://bugs.python.org/issue?@action=redirect&bpo=13802].). La muestra se puede editar para incluir otros caracteres. (Contribuido por Serhiy Storchaka en bpo-31860 [https://bugs.python.org/issue?@action=redirect&bpo=31860].)

Las funciones IDLE implementadas anteriormente como extensiones se han vuelto a implementar como funciones normales. Su configuración se ha movido de la pestaña Extensiones a otras pestañas de diálogo. (Contribuido por Charles Wohlganger y Terry Jan Reedy en bpo-27099 [https://bugs.python.org/issue?@action=redirect&bpo=27099].)

Se revisó la opción de contexto del código del editor. El cuadro muestra todas las líneas de contexto hasta las líneas máximas. Al hacer clic en una línea de contexto, el editor pasa a esa línea. Los colores de contexto para temas personalizados se agregan a la pestaña Destacados del cuadro de diálogo Configuración. (Contribuido por Cheryl Sabella y Terry Jan Reedy en bpo-33642 [https://bugs.python.org/issue?@action=redirect&bpo=33642], bpo-33768 [https://bugs.python.org/issue?@action=redirect&bpo=33768], y bpo-33679 [https://bugs.python.org/issue?@action=redirect&bpo=33679].)

En Windows, una nueva llamada a la API le dice a Windows que tk escala para DPI. En Windows 8.1+ o 10, con las propiedades de compatibilidad de DPI del binario de Python sin cambios y una resolución de monitor superior a 96 DPI, esto debería hacer que el texto y las líneas sean más nítidos. De lo contrario, no debería tener ningún efecto. (Contribuido por Terry Jan Reedy en bpo-33656 [https://bugs.python.org/issue?@action=redirect&bpo=33656].)

Nuevo en 3.7.1:

La salida sobre N líneas (50 por defecto) se reduce a un botón. N se puede cambiar en la sección PyShell de la página General del cuadro de diálogo Configuración. Se pueden comprimir menos líneas, pero posiblemente más largas, haciendo clic derecho en la salida. La salida comprimida se puede expandir en su lugar haciendo doble clic en el botón o en el portapapeles o en una ventana separada haciendo clic derecho en el botón. (Contribuido por Tal Einat en bpo-1529353 [https://bugs.python.org/issue?@action=redirect&bpo=1529353].)

Los cambios anteriores se han actualizado a las versiones de mantenimiento 3.6.

Nuevo en 3.7.4:

Agregado “Run Customized” al menú Correr para ejecutar un módulo con configuraciones personalizadas. Cualquier argumento de línea de comando ingresado se agrega a sys.argv. Vuelven a aparecer en el cuadro para la siguiente ejecución personalizada. También se puede suprimir el reinicio normal del módulo principal de Shell. (Contribuidor por Cheryl Sabella, Terry Jan Reedy, y otros en bpo-5680 [https://bugs.python.org/issue?@action=redirect&bpo=5680] y bpo-37627 [https://bugs.python.org/issue?@action=redirect&bpo=37627].)

Nuevo en 3.7.5:

Agregue números de línea opcionales para las ventanas del editor IDLE. Las ventanas se abren sin números de línea a menos que se establezca lo contrario en la pestaña General del cuadro de diálogo de configuración. Los números de línea de una ventana existente se muestran y ocultan en el menú Opciones. (Contribuido por Tal Einat y Saimadhav Heblikar en bpo-17535 [https://bugs.python.org/issue?@action=redirect&bpo=17535].)

importlib

El importlib.abc.ResourceReader ABC se introdujo para admitir la carga de recursos desde paquetes. Ver también importlib.resources. (Contribuido por Barry Warsaw, Brett Cannon en bpo-32248 [https://bugs.python.org/issue?@action=redirect&bpo=32248].)

importlib.reload() ahora mejora ModuleNotFoundError si el módulo carece de especificación. (Contribuido por Garvit Khatri en bpo-29851 [https://bugs.python.org/issue?@action=redirect&bpo=29851].)

importlib.find_spec() ahora mejora ModuleNotFoundError en lugar de AttributeError si el modulo principal especifico no ese un paquete (es decir, carece de un atributo __path__). (Contribuido por Milan Oberkirch en bpo-30436 [https://bugs.python.org/issue?@action=redirect&bpo=30436].)

La nueva importlib.source_hash() se puede utilizar para calcular el hash de la fuente pasada. Un archivo .pyc basado en hash incrusta el valor devuelto por esta función.

io

El nuevo método TextIOWrapper.reconfigure() se puede utilizar para reconfigurar el flujo de texto con la nueva configuración. (Contribuido por Antoine Pitrou en bpo-30526 [https://bugs.python.org/issue?@action=redirect&bpo=30526] y INADA Naoki en bpo-15216 [https://bugs.python.org/issue?@action=redirect&bpo=15216].)

ipaddress

Los nuevos métodos subnet_of() y supernet_of() de ipaddress.IPv6Network y ipaddress.IPv4Network pueden ser usados para pruebas de contención de redes. (Contribuido por Michel Albert y Cheryl Sabella en bpo-20825 [https://bugs.python.org/issue?@action=redirect&bpo=20825].)

itertools

itertools.islice() ahora acepta integer-like objects como argumentos de inicio, parada y corte. (Contribuido por Will Roberts en bpo-30537 [https://bugs.python.org/issue?@action=redirect&bpo=30537].)

locale

El nuevo argumento * monetario * para locale.format_string() se puede utilizar para hacer que la conversión utilice separadores de miles monetarios y cadenas de agrupación. (Contribuido por Garvit en bpo-10379 [https://bugs.python.org/issue?@action=redirect&bpo=10379].)

La función locale.getpreferredencoding() ahora siempre devuelve ’UTF-8’ en Android o cuando está en el modo UTF-8 forzado.

logging

Logger instancias ahora pueden ser decapadas. (Contribuido por Vinay Sajip en bpo-30520 [https://bugs.python.org/issue?@action=redirect&bpo=30520].)

El nuevo método StreamHandler.setStream() se puede utilizar para reemplazar la secuencia del registrador después de la creación del controlador. (Contribuido por Vinay Sajip en bpo-30522 [https://bugs.python.org/issue?@action=redirect&bpo=30522].)

Ahora es posible especificar argumentos de palabras clave para los constructores de manejadores en la configuración pasada a logging.config.fileConfig(). (Contribuido por Preston Landers en bpo-31080 [https://bugs.python.org/issue?@action=redirect&bpo=31080].)

math

La nueva función math.remainder() implementa la operación de resto de estilo IEEE 754. (Contribuido por Mark Dickinson en bpo-29962 [https://bugs.python.org/issue?@action=redirect&bpo=29962].)

mimetypes

El tipo MIME de .bmp se ha cambiado de ’image/x-ms-bmp’ a ’image/bmp’. (Contribuido por Nitish Chandra en bpo-22589 [https://bugs.python.org/issue?@action=redirect&bpo=22589].)

msilib

El nuevo método Database.Close() se puede utilizar para cerrar la base de datos MSI. (Contribuido por Berker Peksag en bpo-20486 [https://bugs.python.org/issue?@action=redirect&bpo=20486].)

multiprocessing

El nuevo método Process.close() cierra explícitamente el objeto de proceso y libera todos los recursos asociados con él. ValueError se genera si el proceso subyacente aún se está ejecutando. (Contribuido por Antoine Pitrou en bpo-30596 [https://bugs.python.org/issue?@action=redirect&bpo=30596].)

El nuevo método Process.kill() se puede usar para terminar el proceso usando la señal SIGKILL en Unix. (Contribuido por Vitor Pereira en bpo-30794 [https://bugs.python.org/issue?@action=redirect&bpo=30794].)

Subprocesos no demoníacos creados por Process ahora se unen al salir del proceso. (Contribuido por Antoine Pitrou en bpo-18966 [https://bugs.python.org/issue?@action=redirect&bpo=18966].)

os

os.fwalk() ahora acepta el argumento path como bytes. (Contribuido por Serhiy Storchaka en bpo-28682 [https://bugs.python.org/issue?@action=redirect&bpo=28682].)

os.scandir() obtuvo soporte de descriptores de archivo. (Contribuido por Serhiy Storchaka en bpo-25996 [https://bugs.python.org/issue?@action=redirect&bpo=25996].)

La nueva función register_at_fork() permite registrar devoluciones de llamada de Python para que se ejecuten en la bifurcación del proceso. (Contribuido por Antoine Pitrou en bpo-16500 [https://bugs.python.org/issue?@action=redirect&bpo=16500].)

Agrega funciones os.preadv() (combinando la funcionalidad de os.readv() y os.pread()) y os.pwritev() (combinando la funcionalidad de os.writev() y os.pwrite()). (Contribuido por Pablo Galindo en bpo-31368 [https://bugs.python.org/issue?@action=redirect&bpo=31368].)

El argumento de modo de os.makedirs() ya no afecta a los bits de permisos de archivos de los directorios de nivel intermedio recién creados. (Contribuido por Serhiy Storchaka en bpo-19930 [https://bugs.python.org/issue?@action=redirect&bpo=19930].)

os.dup2() ahora retorna el nuevo descriptor de archivo. Previamente, None siempre fue retornado. (Contribuido por Benjamin Peterson en bpo-32441 [https://bugs.python.org/issue?@action=redirect&bpo=32441].)

La estructura retornada por os.stat() ahora contiene el atributo st_fstype en Solaris y sus derivados. (Contribuido por Jesús Cea Avión en bpo-32659 [https://bugs.python.org/issue?@action=redirect&bpo=32659].)

pathlib

El nuevo método Path.is_mount() ahora está disponible en los sistemas POSIX y se puede utilizar para determinar si una ruta es un punto de montaje. (Contribuido por Cooper Ry Lees en bpo-30897 [https://bugs.python.org/issue?@action=redirect&bpo=30897].)

pdb

pdb.set_trace() ahora toma un argumento opcional header solo de palabra clave. Si se proporciona, se imprime en la consola justo antes de que comience la depuración. (Contribuido por Barry Warsaw en bpo-31389 [https://bugs.python.org/issue?@action=redirect&bpo=31389].)

pdb la línea de comando ahora acepta -m module_name como una alternativa al archivo de script. (Contribuido por Mario Corchero en bpo-32206 [https://bugs.python.org/issue?@action=redirect&bpo=32206].)

py_compile

py_compile.compile() — y por extensión, compileall — ahora respeta la variable de entorno SOURCE_DATE_EPOCH creando incondicionalmente archivos .pyc para la validación basada en hash. Esto permite garantizar compilaciones reproducibles [https://reproducible-builds.org/] de archivos .pyc cuando se crean con entusiasmo. (Contribuido por Bernhard M. Wiedemann en bpo-29708 [https://bugs.python.org/issue?@action=redirect&bpo=29708].)

pydoc

El servidor pydoc ahora puede vincularse a un nombre de host arbitrario especificado por el nuevo argumento de línea de comandos -n. (Contribuido por Feanil Patel en bpo-31128 [https://bugs.python.org/issue?@action=redirect&bpo=31128].)

queue

La nueva clase SimpleQueue es una cola ilimitada FIFO. (Contribuido por Antoine Pitrou en bpo-14976 [https://bugs.python.org/issue?@action=redirect&bpo=14976].)

re

Las banderas re.ASCII, re.LOCALE y re.UNICODE se pueden establecer dentro del alcance de un grupo. (Contribuido por Serhiy Storchaka en bpo-31690 [https://bugs.python.org/issue?@action=redirect&bpo=31690].)

re.split() ahora admite la división en un patrón como r’\b’, ’^$’ or (?=-) que coincide con una cadena vacía. (Contribuido por Serhiy Storchaka en bpo-25054 [https://bugs.python.org/issue?@action=redirect&bpo=25054].)

Las expresiones regulares compiladas con el indicador re.LOCALE ya no dependen de la configuración regional en el momento de la compilación. La configuración regional se aplica solo cuando se utiliza la expresión regular compilada. (Contribuido por Serhiy Storchaka en bpo-30215 [https://bugs.python.org/issue?@action=redirect&bpo=30215].)

FutureWarning ahora se emite si una expresión regular contiene construcciones de conjuntos de caracteres que cambiarán semánticamente en el futuro, como conjuntos anidados y operaciones de conjuntos. (Contribuido por Serhiy Storchaka en bpo-30349 [https://bugs.python.org/issue?@action=redirect&bpo=30349].)

Las expresiones regulares compiladas y los objetos coincidentes ahora se pueden copiar usando copy.copy() y copy.deepcopy(). (Contribuido por Serhiy Storchaka en bpo-10076 [https://bugs.python.org/issue?@action=redirect&bpo=10076].)

signal

El nuevo argumento * warn_on_full_buffer * para la función signal.set_wakeup_fd() permite especificar si Python imprime una advertencia en stderr cuando el búfer de activación se desborda. (Contribuido por Nathaniel J. Smith en bpo-30050 [https://bugs.python.org/issue?@action=redirect&bpo=30050].)

socket

El nuevo método socket.getblocking() retorna True si el socket esta en modo bloqueo y False en caso contrario. (Contribuido por Yury Selivanov en bpo-32373 [https://bugs.python.org/issue?@action=redirect&bpo=32373].)

La nueva función socket.close() cierra el descriptor de archivo de socket pasado. Esta función debe usarse en lugar de os.close() para una mejor compatibilidad entre plataformas. (Contribuido por Christian Heimes en bpo-32454 [https://bugs.python.org/issue?@action=redirect&bpo=32454].)

El módulo socket ahora expone las constantes socket.TCP_CONGESTION (Linux 2.6.13), socket.TCP_USER_TIMEOUT (Linux 2.6.37), y socket.TCP_NOTSENT_LOWAT (Linux 3.12). (Contribuido por Omar Sandoval en bpo-26273 [https://bugs.python.org/issue?@action=redirect&bpo=26273] y Nathaniel J. Smith en bpo-29728 [https://bugs.python.org/issue?@action=redirect&bpo=29728].)

Se ha agregado soporte para socket.AF_VSOCK sockets para permitir la comunicación entre las máquinas virtuales y sus hosts. (Contribuido por Cathy Avery en bpo-27584 [https://bugs.python.org/issue?@action=redirect&bpo=27584].)

Los sockets ahora detectan automáticamente la familia, el tipo y el protocolo del descriptor de archivo de forma predeterminada. (Contribuido por Christian Heimes en bpo-28134 [https://bugs.python.org/issue?@action=redirect&bpo=28134].)

socketserver

socketserver.ThreadingMixIn.server_close() ahora espera hasta que se completen todos los subprocesos que no son demonios. socketserver.ForkingMixIn.server_close() ahora espera hasta que se completen todos los procesos secundarios.

Agregue un nuevo atributo de clase socketserver.ForkingMixIn.block_on_close a las clases socketserver.ForkingMixIn y socketserver.ThreadingMixIn. Establece el atributo de clase en False para obtener el comportamiento anterior a 3.7.

sqlite3

sqlite3.Connection ahora expone el método backup() cuando la biblioteca SQLite subyacente está en la versión 3.6.11 o superior. (Contribuido por Lele Gaifax en bpo-27645 [https://bugs.python.org/issue?@action=redirect&bpo=27645].)

El argumento * base de datos * de sqlite3.connect() ahora acepta cualquier path-like object, en lugar de solo una cadena. (Contribuido por Anders Lorentsen en bpo-31843 [https://bugs.python.org/issue?@action=redirect&bpo=31843].)

ssl

El módulo ssl ahora usa la API integrada de OpenSSL en lugar de match_hostname() para comprobar un nombre de host o una dirección IP. Los valores se validan durante el protocolo de enlace TLS. Cualquier error de validación de certificado, incluida la falla en la verificación del nombre de host, ahora aumenta SSLCertVerificationError y aborta el protocolo de enlace con un mensaje de alerta TLS adecuado. La nueva excepción contiene información adicional. La validación del nombre de host se puede personalizar con SSLContext.hostname_checks_common_name. (Contribuido por Christian Heimes en bpo-31399 [https://bugs.python.org/issue?@action=redirect&bpo=31399].)

Nota

La verificación mejorada del nombre de host requiere una implementación libssl compatible con OpenSSL 1.0.2 o 1.1. En consecuencia, OpenSSL 0.9.8 y 1.0.1 ya no son compatibles (consulte Eliminación de soporte de plataforma para más detalles). El módulo ssl es principalmente compatible con LibreSSL 2.7.2 y versiones posteriores.

El módulo ssl ya no envía direcciones IP en la extensión SNI TLS. (Contribuido por Christian Heimes en bpo-32185 [https://bugs.python.org/issue?@action=redirect&bpo=32185].)

match_hostname() ya no admite comodines parciales como www*.example.org. (Contribuido por Mandeep Singh en bpo-23033 [https://bugs.python.org/issue?@action=redirect&bpo=23033] y Christian Heimes en bpo-31399 [https://bugs.python.org/issue?@action=redirect&bpo=31399].)

La selección del conjunto de cifrado predeterminado del módulo ssl ahora usa un enfoque de lista negra en lugar de una lista blanca codificada. Python ya no vuelve a habilitar los cifrados que han sido bloqueados por las actualizaciones de seguridad de OpenSSL. La selección del conjunto de cifrado predeterminado se puede configurar en tiempo de compilación. (Contribuido por Christian Heimes en bpo-31429 [https://bugs.python.org/issue?@action=redirect&bpo=31429].)

Ahora se admite la validación de certificados de servidor que contienen nombres de dominio internacionalizados (IDN). Como parte de este cambio, el atributo SSLSocket.server_hostname ahora almacena el nombre de host esperado en forma de etiqueta A (”xn--pythn-mua.org”), en lugar de la forma de etiqueta U (”pythön.org”). (Contribuido por Nathaniel J. Smith y Christian Heimes en bpo-28414 [https://bugs.python.org/issue?@action=redirect&bpo=28414].)

El módulo ssl tiene soporte preliminar y experimental para TLS 1.3 y OpenSSL 1.1.1. En el momento del lanzamiento de Python 3.7.0, OpenSSL 1.1.1 todavía está en desarrollo y TLS 1.3 aún no se ha finalizado. El protocolo y el protocolo de enlace TLS 1.3 se comportan de forma ligeramente diferente a TLS 1.2 y versiones anteriores, consulte TLS 1.3. (Contribuido por Christian Heimes en bpo-32947 [https://bugs.python.org/issue?@action=redirect&bpo=32947], bpo-20995 [https://bugs.python.org/issue?@action=redirect&bpo=20995], bpo-29136 [https://bugs.python.org/issue?@action=redirect&bpo=29136], bpo-30622 [https://bugs.python.org/issue?@action=redirect&bpo=30622] y bpo-33618 [https://bugs.python.org/issue?@action=redirect&bpo=33618])

SSLSocket y SSLObject ya no tiene un constructor público. La creación de instancias directa nunca fue una característica documentada y compatible. Las instancias deben crearse con métodos SSLContext wrap_socket() y wrap_bio(). (Contribuido por Christian Heimes en bpo-32951 [https://bugs.python.org/issue?@action=redirect&bpo=32951])

Las API de OpenSSL 1.1 para configurar la versión mínima y máxima del protocolo TLS están disponibles como SSLContext.minimum_version y SSLContext.maximum_version. Los protocolos admitidos se indican mediante varios indicadores nuevos, como HAS_TLSv1_1. (Contribuido por Christian Heimes en bpo-32609 [https://bugs.python.org/issue?@action=redirect&bpo=32609].)

string

string.Template ahora le permite modificar opcionalmente el patrón de expresión regular para marcadores de posición reforzados y marcadores de posición no reforzados por separado. (Contribuido por Barry Warsaw en bpo-1198569 [https://bugs.python.org/issue?@action=redirect&bpo=1198569].)

subprocess

La función subprocess.run() acepta el nuevo argumento de palabra clave capture_output. Cuando es verdadero, se capturarán stdout y stderr. Esto es equivalente a pasar subprocess.PIPE como argumentos stdout y stderr. (Contribuido por Bo Bayles en bpo-32102 [https://bugs.python.org/issue?@action=redirect&bpo=32102].)

La función subprocess.run y el constructor subprocess.Popen ahora aceptan la palabra clave del argumento text como un alias para universal_newlines. (Contribuido por Andrew Clegg en bpo-31756 [https://bugs.python.org/issue?@action=redirect&bpo=31756].)

En Windows, el valor predeterminado de close_fds se cambió de False a True al redirigir los identificadores estándar. Ahora es posible establecer close_fds en verdadero al redirigir los identificadores estándar. Ver subprocess.Popen. Esto significa que close_fds ahora tiene el valor predeterminado de True en todas las plataformas compatibles. (Contribuido por Segev Finer en bpo-19764 [https://bugs.python.org/issue?@action=redirect&bpo=19764].)

El módulo de subproceso ahora es más elegante al manejar KeyboardInterrupt durante: subprocess.call(), subprocess.run(), o en un administrador de contexto Popen. Ahora espera un corto período de tiempo para que el niño salga, antes de continuar con el manejo de la excepción KeyboardInterrupt. (Contribuido por Gregory P. Smith en bpo-25942 [https://bugs.python.org/issue?@action=redirect&bpo=25942].)

sys

La nueva función de enganche sys.breakpointhook() es llamada por la incorporada breakpoint(). (Contribuido por Barry Warsaw en bpo-31353 [https://bugs.python.org/issue?@action=redirect&bpo=31353].)

En Android, la nueva sys.getandroidapilevel() devuelve la versión de la API de Android en tiempo de compilación. (Contribuido por Victor Stinner en bpo-28740 [https://bugs.python.org/issue?@action=redirect&bpo=28740].)

La nueva función sys.get_coroutine_origin_tracking_depth() devuelve la profundidad de seguimiento del origen de la corrutina actual, según lo establecido por el nuevo sys.set_coroutine_origin_tracking_depth(). asyncio se ha convertido para usar esta nueva API en lugar de la obsoleta sys.set_coroutine_wrapper(). (Contribuido por Nathaniel J. Smith en bpo-32591 [https://bugs.python.org/issue?@action=redirect&bpo=32591].)

time

PEP 564 [https://www.python.org/dev/peps/pep-0564] añade seis nuevas funciones con resolución de nanosegundos al modulo time:

time.clock_gettime_ns()

time.clock_settime_ns()

time.monotonic_ns()

time.perf_counter_ns()

time.process_time_ns()

time.time_ns()

Se han agregado nuevos identificadores de reloj:

time.CLOCK_BOOTTIME (Linux): Idéntico a time.CLOCK_MONOTONIC, excepto que también incluye cualquier momento en que el sistema esté suspendido.

time.CLOCK_PROF (FreeBSD, NetBSD y OpenBSD): Temporizador de CPU por proceso de alta resolución.

time.CLOCK_UPTIME (FreeBSD, OpenBSD): Hora cuyo valor absoluto es el tiempo que el sistema ha estado funcionando y no suspendido, proporcionando una medición precisa del tiempo de actividad.

La nuevas funciones time.thread_time() y time.thread_time_ns() se puede utilizar para obtener medidas de tiempo de CPU por subproceso. (Contribuido por Antoine Pitrou en bpo-32025 [https://bugs.python.org/issue?@action=redirect&bpo=32025].)

La nueva función time.pthread_getcpuclockid() devuelve el ID de reloj del reloj de tiempo de CPU específico del subproceso.

tkinter

La nueva clase tkinter.ttk.Spinbox esta disponible ahora. (Contribuido por Alan Moore en bpo-32585 [https://bugs.python.org/issue?@action=redirect&bpo=32585].)

tracemalloc

tracemalloc.Traceback se comporta más como rastreos regulares, ordenando los fotogramas del más antiguo al más reciente. Traceback.format() ahora acepta límite negativo, truncando el resultado a los marcos más antiguos de abs(limit). Para obtener el comportamiento anterior, use el nuevo argumento most_recent_first para Traceback.format(). (Contribuido por Jesse Bakker en bpo-32121 [https://bugs.python.org/issue?@action=redirect&bpo=32121].)

types

Las nuevas clases WrapperDescriptorType, MethodWrapperType, MethodDescriptorType, y ClassMethodDescriptorType ahora están disponibles. (Contribuido por Manuel Krebber y Guido van Rossum en bpo-29377 [https://bugs.python.org/issue?@action=redirect&bpo=29377], y Serhiy Storchaka en bpo-32265 [https://bugs.python.org/issue?@action=redirect&bpo=32265].)

La nueva función types.resolve_bases() resuelve las entradas MRO dinámicamente según lo especificado por PEP 560 [https://www.python.org/dev/peps/pep-0560]. (Contribuido por Ivan Levkivskyi en bpo-32717 [https://bugs.python.org/issue?@action=redirect&bpo=32717].)

unicodedata

La base de datos interna unicodedata ha sido actualizada para usar Unicode 11 [http://www.unicode.org/versions/Unicode11.0.0/]. (Contribuido por Benjamin Peterson.)

unittest

La nueva opción de la linea de comandos -k permite filtrar pruebas por una subcadena de nombre o un patrón similar a un shell de Unix. Por ejemplo, python -m unittest -k foo` ejecuta foo_tests.SomeTest.test_something, bar_tests.SomeTest.test_foo, pero no bar_tests.FooTest.test_something. (Contribuido por Jonas Haag en bpo-32071 [https://bugs.python.org/issue?@action=redirect&bpo=32071].)

unittest.mock

Los atributos sentinel ahora preservan su identidad cuando están copied o pickled. (Contribuido por Serhiy Storchaka en bpo-20804 [https://bugs.python.org/issue?@action=redirect&bpo=20804].)

La nueva función seal() permite sellar instancias Mock, que no permitirá la creación de simulacros de atributos. El sello se aplica de forma recursiva a todos los atributos que en sí mismos son burlas. (Contribuido por Mario Corchero en bpo-30541 [https://bugs.python.org/issue?@action=redirect&bpo=30541].)

urllib.parse

urllib.parse.quote() ha sido actualizada desde RFC 2396 [https://tools.ietf.org/html/rfc2396.html] a RFC 3986 [https://tools.ietf.org/html/rfc3986.html], agregado ~ para el conjunto de caracteres que nunca se cotizan por defecto. (Contribuido por Christian Theune y Ratnadeep Debnath en bpo-16285 [https://bugs.python.org/issue?@action=redirect&bpo=16285].)

uu

La nueva función uu.encode() ahora acepta un argumento opcional de palabra clave backtick. Mientras esto se verdadero, los ceros son representados por ’`’ en lugar de espacios. (Contribuido por Xiang Zhang en bpo-30103 [https://bugs.python.org/issue?@action=redirect&bpo=30103].)

uuid

El nuevo atributo UUID.is_safe transmite información de la plataforma sobre si los UUID generados se generan con un método seguro para multiprocesamiento. (Contribuido por Barry Warsaw en bpo-22807 [https://bugs.python.org/issue?@action=redirect&bpo=22807].)

uuid.getnode() ahora prefiere las direcciones MAC administradas universalmente a las direcciones MAC administradas localmente. Esto ofrece una mejor garantía de la unicidad global de los UUID devueltos desde uuid.uuid1(). Si solo hay disponibles direcciones MAC administradas localmente, se devuelve la primera que se encuentre. (Contribuido por Barry Warsaw en bpo-32107 [https://bugs.python.org/issue?@action=redirect&bpo=32107].)

warnings

La inicialización de los filtros de advertencias predeterminados ha cambiado de la siguiente manera:

advertencias habilitadas a través de opciones de línea de comando (incluidos los de -b y la nueva opción específica de CPython -X dev) siempre se pasan a la maquinaria de advertencias a través del atributo sys.warnoptions.

los filtros de advertencias habilitados a través de la línea de comandos o el entorno ahora tienen el siguiente orden de prioridad:

el filtro BytesWarning para -b (o -bb)

cualquier filtro especificado con la opción -W

cualquier filtro especificado con la variable de entorno PYTHONWARNINGS

cualquier otro filtro específico de CPython (por ejemplo, el filtro default agregado para el nuevo modo -X dev)

cualquier filtro implícito definido directamente por la maquinaria de advertencias

en las compilaciones de depuración de CPython, ahora todas las advertencias se muestran de forma predeterminada (la lista de filtros implícitos está vacía)

(Contribuido por Nick Coghlan y Victor Stinner en bpo-20361 [https://bugs.python.org/issue?@action=redirect&bpo=20361], bpo-32043 [https://bugs.python.org/issue?@action=redirect&bpo=32043], and bpo-32230 [https://bugs.python.org/issue?@action=redirect&bpo=32230].)

Las advertencias de obsolescencia se muestran una vez más de forma predeterminada en scripts de un solo archivo y en el indicador interactivo. Consultar PEP 565: Mostrar DeprecationWarning en __main__ para mas detalles. (Contribuido por Nick Coghlan en bpo-31975 [https://bugs.python.org/issue?@action=redirect&bpo=31975].)

xml.etree

ElementPath predicados en los métodos find() ahora pueden comparar el texto del nodo actual con `[. = “text”], no solo texto en niños. Los predicados también permiten agregar espacios para una mejor legibilidad. (Contribuido por Stefan Behnel en bpo-31648 [https://bugs.python.org/issue?@action=redirect&bpo=31648].)

xmlrpc.server

SimpleXMLRPCDispatcher.register_function ahora puede ser usado como un decorador. (Contribuido por Xiang Zhang en bpo-7769 [https://bugs.python.org/issue?@action=redirect&bpo=7769].)

zipapp

Función create_archive() ahora acepta un argumento opcional filter para permitir al usuario seleccionar que archivos deben incluirse en el

Función create_archive() ahora acepta un argumento opcional * comprimido * para generar un archivo comprimido. También se ha agregado una opción de línea de comando —compress para admitir la compresión. (Contribuido por Zhiming Wang en bpo-31638 [https://bugs.python.org/issue?@action=redirect&bpo=31638].)

zipfile

ZipFile ahora acepta el nuevo parámetro compresslevel para controlar el nivel de compresión. (Contribuido por Bo Bayles en bpo-21417 [https://bugs.python.org/issue?@action=redirect&bpo=21417].)

Subdirectorios en archivos creados por ZipFile ahora son guardados en orden alfabético. (Contribuido por Bernhard M. Wiedemann en bpo-30693 [https://bugs.python.org/issue?@action=redirect&bpo=30693].)

Cambios en la API C

Se implementó una nueva API para el almacenamiento local de subprocesos. Ver PEP 539: Nueva API C para almacenamiento local de subprocesos para una descripción general y API de almacenamiento específico de hilo (TSS, Thread Specific Storage) para una referencia completa. (Contribuido por Masayuki Yamamoto en bpo-25658 [https://bugs.python.org/issue?@action=redirect&bpo=25658].)

La nueva funcionalidad variables de contexto expone un numero de nuevas APIs C.

La nueva función PyImport_GetModule() devuelve el módulo previamente importado con el nombre dado. (Contribuido por Eric Snow en bpo-28411 [https://bugs.python.org/issue?@action=redirect&bpo=28411].)

El nuevo macro Py_RETURN_RICHCOMPARE facilita la escritura de funciones de comparación enriquecidas. (Contribuido por Petr Victorin en bpo-23699 [https://bugs.python.org/issue?@action=redirect&bpo=23699].)

El nuevo macro Py_UNREACHABLE se puede utilizar para marcar rutas de código inalcanzables. (Contribuido por Barry Warsaw en bpo-31338 [https://bugs.python.org/issue?@action=redirect&bpo=31338].)

El tracemalloc ahora expone una API C a través de las nuevas funciones PyTraceMalloc_Track() y PyTraceMalloc_Untrack(). (Contribuido por Victor Stinner en bpo-30054 [https://bugs.python.org/issue?@action=redirect&bpo=30054].)

Los nuevos marcadores estáticos import__find__load__start() y import__find__load__done() se pueden usar para rastrear las importaciones de módulos. (Contribuido por Christian Heimes en bpo-31574 [https://bugs.python.org/issue?@action=redirect&bpo=31574].)

Los campos name and doc de estructuras PyMemberDef, PyGetSetDef, PyStructSequence_Field, PyStructSequence_Desc, y wrapperbase ahora son de tipo const char * en lugar de char *. (Contribuido por Serhiy Storchaka en bpo-28761 [https://bugs.python.org/issue?@action=redirect&bpo=28761].)

El resultado de PyUnicode_AsUTF8AndSize() y PyUnicode_AsUTF8() es ahora de tipo const char * en lugar de char *. (Contribuido por Serhiy Storchaka en bpo-28769 [https://bugs.python.org/issue?@action=redirect&bpo=28769].)

El resultado de PyMapping_Keys(), PyMapping_Values() y PyMapping_Items() ahora es siempre una lista, en lugar de una lista o una tupla. (Contribuido por Oren Milman en bpo-28280 [https://bugs.python.org/issue?@action=redirect&bpo=28280].)

Funciones agregadas PySlice_Unpack() y PySlice_AdjustIndices(). (Contribuido por Serhiy Storchaka en bpo-27867 [https://bugs.python.org/issue?@action=redirect&bpo=27867].)

PyOS_AfterFork() está en desuso en favor de las nuevas funciones PyOS_BeforeFork(), PyOS_AfterFork_Parent() y PyOS_AfterFork_Child(). (Contribuido por Antoine Pitrou en bpo-16500 [https://bugs.python.org/issue?@action=redirect&bpo=16500].)

El único PyExc_RecursionErrorInst que formaba parte de la API pública se ha eliminado ya que sus miembros nunca borrados pueden causar un error de segmentación durante la finalización del intérprete. Contribuido por Xavier de Gaye en bpo-22898 [https://bugs.python.org/issue?@action=redirect&bpo=22898] y bpo-30697 [https://bugs.python.org/issue?@action=redirect&bpo=30697].

Se agregó compatibilidad con C API para zonas horarias con constructores de zonas horarias PyTimeZone_FromOffset() and PyTimeZone_FromOffsetAndName(), y acceso único al UTC con PyDateTime_TimeZone_UTC. Contribuido por Paul Ganssle en bpo-10381 [https://bugs.python.org/issue?@action=redirect&bpo=10381].

El tipo de resultados de PyThread_start_new_thread() y PyThread_get_thread_ident(), y el parámetro id de PyThreadState_SetAsyncExc() cambiaron desde long a unsigned long. (Contribuido por Serhiy Storchaka en bpo-6532 [https://bugs.python.org/issue?@action=redirect&bpo=6532].)

PyUnicode_AsWideCharString() ahora genera un ValueError si el segundo argumento es NULL y la cadena wchar_t* contiene caracteres nulos. (Contribuido por Serhiy Storchaka en bpo-30708 [https://bugs.python.org/issue?@action=redirect&bpo=30708].)

Los cambios en la secuencia de inicio y la gestión de los asignadores de memoria dinámica significan que el requisito documentado durante mucho tiempo de llamar Py_Initialize() antes de llamar a la mayoría de las funciones de la API de C, ahora se confía más en él, y no cumplirlo puede provocar errores de segmentación en las aplicaciones integradas. Ver la sección Portando a Python 3.7 en este documento y en la sección Antes de la inicialización de Python en la documentación de la API de C para obtener más detalles.

El nuevo: c: func PyInterpreterState_GetID() devuelve él ID único para un intérprete dado. (Contribuido por Eric Snow en bpo-29102 [https://bugs.python.org/issue?@action=redirect&bpo=29102].)

Py_DecodeLocale(), Py_EncodeLocale() ahora usa la codificación UTF-8 cuando el modo UTF-8 esta habilitado. (Contribuido por Victor Stinner en bpo-29240 [https://bugs.python.org/issue?@action=redirect&bpo=29240].)

PyUnicode_DecodeLocaleAndSize() y PyUnicode_EncodeLocale() ahora usan la codificación local actual para el controlador de errores surrogateescape. (Contribuido por Victor Stinner en bpo-29240 [https://bugs.python.org/issue?@action=redirect&bpo=29240].)

Los parámetros start y end de PyUnicode_FindChar() ahora se ajustan para comportarse como cortes de cuerda. (Contribuido por Xiang Zhang en bpo-28822 [https://bugs.python.org/issue?@action=redirect&bpo=28822].)

Construir cambios

Se ha eliminado el soporte para construir —without-threads. El módulo threading ahora está siempre disponible. (Contribuido por Antoine Pitrou en bpo-31370 [https://bugs.python.org/issue?@action=redirect&bpo=31370].).

Ya no se incluye una copia completa de libffi para su uso al compilar el módulo _ctypes en plataformas que no son OSX UNIX. Ahora se requiere una copia instalada de libffi al construir _ctypes en tales plataformas. (Contribuido por Zachary Ware en bpo-27979 [https://bugs.python.org/issue?@action=redirect&bpo=27979].)

El proceso de compilación de Windows ya no depende de una sub versión para extraer fuentes externas; en su lugar, se usa un script de Python para descargar archivos zip desde GitHub. Si no se encuentra Python 3.6 en el sistema (a través de py -3.6), NuGet se usa para descargar una copia de Python de 32 bits para este propósito. (Contribuido por Zachary Ware en bpo-30450 [https://bugs.python.org/issue?@action=redirect&bpo=30450].)

El módulo ssl requiere libssl compatible con OpenSSL 1.0.2 o 1.1. OpenSSL 1.0.1 llegó al final de su vida útil el 31 de diciembre de 2016 y ya no es compatible. LibreSSL tampoco es compatible temporalmente. Las versiones de LibreSSL hasta la versión 2.6.4 carecen de las API de OpenSSL 1.0.2 necesarias.

Optimizaciones

La sobrecarga de llamar a muchos métodos de varias clases de biblioteca estándar implementadas en C se ha reducido significativamente al portar más código para usar la convención METH_FASTCALL. (Contribuido por Victor Stinner en bpo-29300 [https://bugs.python.org/issue?@action=redirect&bpo=29300], bpo-29507 [https://bugs.python.org/issue?@action=redirect&bpo=29507], bpo-29452 [https://bugs.python.org/issue?@action=redirect&bpo=29452], y bpo-29286 [https://bugs.python.org/issue?@action=redirect&bpo=29286].)

Varias optimizaciones han reducido el tiempo de inicio de Python en un 10% en Linux y hasta en un 30% en macOS. (Contribuido por Victor Stinner, INADA Naoki en bpo-29585 [https://bugs.python.org/issue?@action=redirect&bpo=29585], y Ivan Levkivskyi en bpo-31333 [https://bugs.python.org/issue?@action=redirect&bpo=31333].)

Las llamadas a métodos ahora son hasta un 20% más rápidas debido a los cambios de código de bytes que evitan la creación de instancias de métodos enlazados. (Contribuidos por Yury Selivanov y INADA Naoki en bpo-26110 [https://bugs.python.org/issue?@action=redirect&bpo=26110].)

El módulo asyncio recibió una serie de optimizaciones notables para funciones de uso común:

La función asyncio.get_event_loop() se ha vuelto a implementar en C para hacerlo hasta 15 veces más rápido. (Contribuido por Yury Selivanov en bpo-32296 [https://bugs.python.org/issue?@action=redirect&bpo=32296].)

Se ha optimizado la gestión de devolución de llamada asyncio.Future. (Contribuido por Yury Selivanov en bpo-32348 [https://bugs.python.org/issue?@action=redirect&bpo=32348].)

asyncio.gather() ahora es hasta un 15% más rápido. (Contribuido por Yury Selivanov en bpo-32355 [https://bugs.python.org/issue?@action=redirect&bpo=32355].)

asyncio.sleep() ahora es hasta 2 veces más rápido cuando el argumento delay es cero o negativo. (Contribuido por Andrew Svetlov en bpo-32351 [https://bugs.python.org/issue?@action=redirect&bpo=32351].)

Se ha reducido la sobrecarga de rendimiento del modo de depuración asyncio. (Contribuido por Antoine Pitrou en bpo-31970 [https://bugs.python.org/issue?@action=redirect&bpo=31970].)

Como resultado de PEP 560 trabajo, el tiempo de importación de typing se ha reducido en un factor de 7, y muchas operaciones de mecanografía ahora son más rápidas. (Contribuido por Ivan Levkivskyi en bpo-32226 [https://bugs.python.org/issue?@action=redirect&bpo=32226].)

sorted() y list.sort() se han optimizado para que los casos comunes sean hasta un 40-75% más rápidos. (Contribuido por Elliot Gorokhovsky en bpo-28685 [https://bugs.python.org/issue?@action=redirect&bpo=28685].)

dict.copy() es ahora 5.5 veces más rápido. (Contribuido por Yury Selivanov en bpo-31179 [https://bugs.python.org/issue?@action=redirect&bpo=31179].)

hasattr() y getattr() ahora son aproximadamente 4 veces más rápidos cuando name no se encuentra y obj no se anula object.__getattr__() o object.__getattribute__(). (Contribuido por INADA Naoki en bpo-32544 [https://bugs.python.org/issue?@action=redirect&bpo=32544].)

La búsqueda de ciertos caracteres Unicode (como la mayúscula ucraniana “Є”) en una cadena fue hasta 25 veces más lenta que la búsqueda de otros caracteres. Ahora es solo 3 veces más lento en el peor de los casos. (Contribuido por Serhiy Storchaka en bpo-24821 [https://bugs.python.org/issue?@action=redirect&bpo=24821].)

La fábrica collections.namedtuple() ha sido re-implementada para hacer que la creación de tuplas con nombre sea de 4 a 6 veces más rápida. (Contribuido por Jelle Zijlstra con nuevas mejoras de INADA Naoki, Serhiy Storchaka, y Raymond Hettinger en bpo-28638 [https://bugs.python.org/issue?@action=redirect&bpo=28638].)

date.fromordinal() y date.fromtimestamp() ahora son hasta un 30% más rápidos en el caso común. (Contribuido por Paul Ganssle en bpo-32403 [https://bugs.python.org/issue?@action=redirect&bpo=32403].)

La función os.fwalk() es ahora 2 veces mas rápida gracias al uso de os.scandir(). (Contribuido por Serhiy Storchaka en bpo-25996 [https://bugs.python.org/issue?@action=redirect&bpo=25996].)

La rapidez de la función shutil.rmtree() se ha mejorado en un 20-40% gracias al uso de la función os.scandir(). (Contribuido por Serhiy Storchaka en bpo-28564 [https://bugs.python.org/issue?@action=redirect&bpo=28564].)

Búsqueda y coincidencia optimizadas que no distinguen entre mayúsculas y minúsculas de expresiones regulares. La búsqueda de algunos patrones ahora puede ser hasta 20 veces más rápida. (Contribuido por Serhiy Storchaka en bpo-30285 [https://bugs.python.org/issue?@action=redirect&bpo=30285].)

re.compile() ahora convierte el parámetro flags en un objeto int si es RegexFlag. Ahora es tan rápido como Python 3.5 y más rápido que Python 3.6 en aproximadamente un 10% dependiendo del patrón. (Contribuido por INADA Naoki en bpo-31671 [https://bugs.python.org/issue?@action=redirect&bpo=31671].)

El método modify() de la clase selectors.EpollSelector, selectors.PollSelector y selectors.DevpollSelector puede ser alrededor de un 10% más rápido bajo cargas pesadas. (Contribuido por Giampaolo Rodola en bpo-30014 [https://bugs.python.org/issue?@action=redirect&bpo=30014])

El plegado constante se ha movido del optimizador de mirilla al nuevo optimizador AST, que puede realizar optimizaciones de manera más consistente. (Contribuid por Eugene Toder y INADA Naoki en bpo-29469 [https://bugs.python.org/issue?@action=redirect&bpo=29469] y bpo-11549 [https://bugs.python.org/issue?@action=redirect&bpo=11549].)

La mayoría de funciones y métodos en abc se han reescrito en C. Esto hace que la creación de clases base abstractas y la llamada a isinstance() y issubclass() en ellas sean 1.5 veces más rápidas. Esto también reduce el tiempo de inicio de Python hasta en un 10%. (Contribuido por Ivan Levkivskyi y INADA Naoki en bpo-31333 [https://bugs.python.org/issue?@action=redirect&bpo=31333])

Mejoras significativas de velocidad para constructores alternativos para datetime.date y datetime.datetime mediante el uso de constructores de ruta rápida cuando no se construyen subclases. (Contribuido por Paul Ganssle en bpo-32403 [https://bugs.python.org/issue?@action=redirect&bpo=32403])

La velocidad de comparación de instancias de array.array se ha mejorado considerablemente en determinados casos. Ahora es de 10 a 70 veces más rápido cuando se comparan matrices que contienen valores del mismo tipo de entero. (Contribuido por Adrian Wielgosik en bpo-24700 [https://bugs.python.org/issue?@action=redirect&bpo=24700].)

Las funciones math.erf() y math.erfc() ahora use la implementación de la biblioteca C (más rápida) en la mayoría de las plataformas. (Contribuido por Serhiy Storchaka en bpo-26121 [https://bugs.python.org/issue?@action=redirect&bpo=26121].)

Otros cambios de implementación de CPython

Los ganchos de seguimiento ahora pueden optar por no recibir la linea y optar por recibir los eventos opcode del intérprete configurando los nuevos atributos correspondientes f_trace_lines y f_trace_opcodes en el marco que se está rastreando . (Contribuido por Nick Coghlan en bpo-31344 [https://bugs.python.org/issue?@action=redirect&bpo=31344].)

Se corrigieron algunos problemas de coherencia con los atributos del módulo del paquete de espacio de nombres. Los objetos del módulo de espacio de nombres ahora tienen un __file__ que está configurado como None (previamente no configurado), y su __spec__.origin también está configurado como None (anteriormente la cadena ”espacio de nombres”`). Ver :issue:`32305`. Además, el ``__spec__.loader del objeto del módulo de espacio de nombres se establece en el mismo valor que __loader__ (anteriormente, el primero se estableció en None). Ver bpo-32303 [https://bugs.python.org/issue?@action=redirect&bpo=32303].

El diccionario locals() ahora se muestra en el orden léxico en que se definieron las variables. Anteriormente, el orden no estaba definido. (Contribuido por Raymond Hettinger en bpo-32690 [https://bugs.python.org/issue?@action=redirect&bpo=32690].)

El comando distutils upload ya no intenta cambiar los caracteres de fin de línea de CR a CRLF. Esto soluciona un problema de corrupción con sdists que terminaba con un byte equivalente a CR. (Contribuido por Bo Bayles en bpo-32304 [https://bugs.python.org/issue?@action=redirect&bpo=32304].)

Comportamiento obsoleto de Python

Las expresiones de rendimiento (tanto las cláusulas yield como las cláusulas yield from) ahora están en desuso en las comprensiones y las expresiones generadoras (aparte de la expresión iterable en la cláusula más a la izquierda for). Esto asegura que las comprensiones siempre devuelvan inmediatamente un contenedor del tipo apropiado (en lugar de potencialmente devolver un objeto generator iterator), mientras que las expresiones generadoras no intentarán intercalar su salida implícita con la salida de ninguna expresión de rendimiento explícita. En Python 3.7, tales expresiones emiten DeprecationWarning cuando se compilan, en Python 3.8 será un SyntaxError. (Contribuido por Serhiy Storchaka en bpo-10544 [https://bugs.python.org/issue?@action=redirect&bpo=10544].)

Devolviendo una subclase de complex desde object.__complex__() está obsoleto y será un error en futuras versiones de Python. Esto hace que __complex__() se compatible con object.__int__() y object.__float__(). (Contribuido por Serhiy Storchaka en bpo-28894 [https://bugs.python.org/issue?@action=redirect&bpo=28894].)

Módulos, funciones y métodos de Python obsoletos

aifc

aifc.openfp() ha quedado obsoleto y se eliminará en Python 3.9. En su lugar use aifc.open(). (Contribuido por Brian Curtin en bpo-31985 [https://bugs.python.org/issue?@action=redirect&bpo=31985].)

asyncio

Se ha desaprobado el soporte para instancias en await de asyncio.Lock y otras primitivas de sincronización asyncio directamente. Se debe utilizar un administrador de contexto asincrónico para adquirir y liberar el recurso de sincronización. (Contribuido por Andrew Svetlov en bpo-32253 [https://bugs.python.org/issue?@action=redirect&bpo=32253].)

Los métodos asyncio.Task.current_task() y asyncio.Task.all_tasks() han quedado obsoletos. (Contribuido por Andrew Svetlov en bpo-32250 [https://bugs.python.org/issue?@action=redirect&bpo=32250].)

collections

En Python 3.8, las clases base abstractas en collections.abc ya no estará expuesto en el módulo regular collections. Esto ayudará a crear una distinción más clara entre las clases concretas y las clases base abstractas. (Contribuido por Serhiy Storchaka en bpo-25988 [https://bugs.python.org/issue?@action=redirect&bpo=25988].)

dbm

dbm.dumb ahora admite la lectura de archivos de solo lectura y ya no escribe el archivo de índice cuando no se cambia. Ahora se emite una advertencia de obsolescencia si falta el archivo de índice y se recrea en los modos ’r’ y ’w’ (esto será un error en futuras versiones de Python). (Contribuido por Serhiy Storchaka en bpo-28847 [https://bugs.python.org/issue?@action=redirect&bpo=28847].)

enum

En Python 3.8, intentar buscar objetos que no sean Enum en clases Enum generará un TypeError (por ejemplo, 1 in Color); de manera similar, si se intenta buscar objetos que no sean miembro de la Flag se generará TypeError (por ejemplo, 1 in Perm.RW); actualmente, ambas operaciones devuelven False en su lugar.

gettext

Usando un valor no entero para seleccionar una forma plural en gettext ahora está en desuso. Nunca funcionó correctamente. (Contribuido por Serhiy Storchaka en bpo-28692 [https://bugs.python.org/issue?@action=redirect&bpo=28692].)

importlib

Métodos MetaPathFinder.find_module() (reemplazado por MetaPathFinder.find_spec()) y PathEntryFinder.find_loader() (reemplazado por PathEntryFinder.find_spec()) ambas en desuso en Python 3.4 ahora emiten DeprecationWarning. (Contribuido por Matthias Bussonnier en bpo-29576 [https://bugs.python.org/issue?@action=redirect&bpo=29576])

El importlib.abc.ResourceLoader ABC ha quedado obsoleto en favor de importlib.abc.ResourceReader.

locale

locale.format() ha sido obsoleto, en su lugar use locale.format_string(). (Contribuido por Garvit en bpo-10379 [https://bugs.python.org/issue?@action=redirect&bpo=10379].)

macpath

El macpath esta ahora en desuso y se eliminará en Python 3.8. (Contribuido por Chi Hsuan Yen en bpo-9850 [https://bugs.python.org/issue?@action=redirect&bpo=9850].)

threading

dummy_threading y _dummy_thread han quedado en desuso. ya no es posible compilar Python con el subproceso desactivado. En lugar use threading. (Contribuido por Antoine Pitrou en bpo-31370 [https://bugs.python.org/issue?@action=redirect&bpo=31370].)

socket

El truncamiento del valor del argumento silencioso en socket.htons() y socket.ntohs() ha quedado en desuso. En futuras versiones de Python, si el argumento pasado es mayor de 16 bits, se generará una excepción. (Contribuido por Oren Milman en bpo-28332 [https://bugs.python.org/issue?@action=redirect&bpo=28332].)

ssl

ssl.wrap_socket() esta en desuso. En su lugar use ssl.SSLContext.wrap_socket(). (Contribuido por Christian Heimes en bpo-28124 [https://bugs.python.org/issue?@action=redirect&bpo=28124].)

sunau

sunau.openfp() ha quedado obsoleto y se eliminará en Python 3.9. En lugar use sunau.open(). (Contribuido por Brian Curtin en bpo-31985 [https://bugs.python.org/issue?@action=redirect&bpo=31985].)

sys

sys.set_coroutine_wrapper() y sys.get_coroutine_wrapper() en desuso.

La función indocumentada sys.callstats() ha quedado obsoleto y se eliminará en una futura versión de Python. (Contribuido por Victor Stinner en bpo-28799 [https://bugs.python.org/issue?@action=redirect&bpo=28799].)

wave

wave.openfp() ha quedado obsoleta y sera removida en Python 3.9. En su lugar use wave.open(). (Contribuido por Brian Curtin en bpo-31985 [https://bugs.python.org/issue?@action=redirect&bpo=31985].)

Funciones y tipos obsoletos de la API C

Función PySlice_GetIndicesEx() está en desuso y se reemplaza con una macro si Py_LIMITED_API no está configurado o configurado en un valor en el rango entre 0x03050400``y ``0x03060000 (no incluido), o es 0x03060100 o superior. (Contribuido por Serhiy Storchaka en bpo-27867 [https://bugs.python.org/issue?@action=redirect&bpo=27867].)

PyOS_AfterFork() ha quedado obsoleto. En su lugar usar PyOS_BeforeFork(), PyOS_AfterFork_Parent() o PyOS_AfterFork_Child(). (Contribuido por Antoine Pitrou en bpo-16500 [https://bugs.python.org/issue?@action=redirect&bpo=16500].)

Eliminación de soporte de plataforma

FreeBSD 9 y las versiones anteriores ya no son compatibles oficialmente.

Para una compatibilidad total con Unicode, incluso dentro de los módulos de extensión, ahora se espera que las plataformas *nix proporcionen al menos uno de C.UTF-8 (configuración regional completa), C.utf8``(configuración regional completa) o ``UTF-8 (configuración regional exclusiva de LC_CTYPE) como una alternativa a la configuración regional C heredada basada en ASCII.

OpenSSL 0.9.8 y 1.0.1 ya no son compatibles, lo que significa que la compilación de CPython 3.7 con compatibilidad con SSL / TLS en plataformas más antiguas que aún usan estas versiones requiere opciones de compilación personalizadas que se vinculan a una versión más reciente de OpenSSL.

En particular, este problema afecta a las distribuciones LTS Linux Debian 8 (también conocido como “jessie”) y Ubuntu 14.04 (también conocido como “Trusty”), ya que todavía usan OpenSSL 1.0.1 por defecto.

Debian 9 (“stretch”) y Ubuntu 16.04 (“xenial”), así como las versiones recientes de otras versiones de LTS Linux (por ejemplo, RHEL / CentOS 7.5, SLES 12-SP3), usan OpenSSL 1.0.2 o posterior y siguen siendo compatibles en la configuración de compilación predeterminada.

El propio archivo de configuración CI [https://github.com/python/cpython/tree/3.9/.travis.yml] de CPython proporciona un ejemplo del uso de SSL compatibilidad con la estructura de testing [https://github.com/python/cpython/tree/3.9/Tools/ssl/multissltests.py] en el conjunto de pruebas de CPython para compilar y vincular contra OpenSSL 1.1.0 en lugar de un sistema obsoleto proporcionado OpenSSL.

Eliminaciones de API y funciones

Las siguientes funciones y API se han eliminado de Python 3.7:

La función os.stat_float_times() ha sido removida. Se introdujo en Python 2.3 por compatibilidad con versiones anteriores de Python 2.2 y quedó obsoleto desde Python 3.1.

Los escapes desconocidos que consisten en ’\’ y una letra ASCII en las plantillas de reemplazo para re.sub() quedaron obsoletos en Python 3.5 y ahora causarán un error.

Se eliminó el soporte del argumento * exclude * en tarfile.TarFile.add(). Fue obsoleto en Python 2.7 y 3.2. Utilice el argumento * filtro * en su lugar.

La función splitunc() en el módulo ntpath quedó obsoleto en Python 3.1 y ahora se ha eliminado. Utilice la función splitdrive() en su lugar.

collections.namedtuple() ya no admite el parámetro verbose o el atributo _source que mostraba el código fuente generado para la clase de tupla nombrada. Esto fue parte de una optimización diseñada para acelerar la creación de clases. (Contribuido por Jelle Zijlstra con nuevas mejoras de INADA Naoki, Serhiy Storchaka, y Raymond Hettinger en bpo-28638 [https://bugs.python.org/issue?@action=redirect&bpo=28638].)

Funciones bool(), float(), list() y tuple() ya no aceptan argumentos de palabras clave. El primer argumento de int() ahora solo se puede pasar como argumento posicional.

Eliminado anteriormente en desuso en las clases de Python 2.4 Plist, Dict y _InternalDict en el módulo plistlib. Dictar valores en el resultado de funciones readPlist() y readPlistFromBytes() ahora son dictados normales. Ya no puede utilizar el acceso a atributos para acceder a elementos de estos diccionarios.

La función asyncio.windows_utils.socketpair() ha sido removida. En su lugar use la función socket.socketpair(), está disponible en todas las plataformas desde Python 3.5. asyncio.windows_utils.socketpair era un alias para socket.socketpair en Python 3.5 y mas nuevo.

asyncio ya no exporta el selectors y módulos como _overlapped asyncio.selectors y asyncio._overlapped. reemplazar por from asyncio import selectors y import selectors.

Instanciación directa de objetos ssl.SSLSocket y ssl.SSLObject ahora está prohibido. Los constructores nunca fueron documentados, probados o diseñados como constructores públicos. Se suponía que los usuarios usaban ssl.wrap_socket() o ssl.SSLContext. (Contribuido por Christian Heimes en bpo-32951 [https://bugs.python.org/issue?@action=redirect&bpo=32951].)

El comando no utilizado distutils install_misc ha sido eliminado. (Contribuido por Eric N. Vander Weele en bpo-29218 [https://bugs.python.org/issue?@action=redirect&bpo=29218].)

Eliminaciones de módulos

El modulo fpectl ha sido removido. Nunca se habilitó de forma predeterminada, nunca funcionó correctamente en x86-64 y cambió la ABI de Python de manera que causó la rotura inesperada de las extensiones C. (Contribuido por Nathaniel J. Smith en bpo-29137 [https://bugs.python.org/issue?@action=redirect&bpo=29137].)

Cambios solo en Windows

El lanzador de python, (py.exe), puede aceptar especificadores de 32 y 64 bits sin tener que especificar también una versión secundaria. Entonces, py -3-32 y py -3-64 se vuelven válidos, así como py -3.7-32, también los -m-64 and -m.n-64. Los formularios ahora se aceptan para forzar Python de 64 bits incluso si de otro modo se hubieran utilizado 32 bits. Si la versión especificada no está disponible, py.exe saldrá del error. (Contribuido por Steve Barnes en bpo-30291 [https://bugs.python.org/issue?@action=redirect&bpo=30291].)

El lanzador se puede ejecutar como py -0 para producir una lista de las pitones instaladas, con las marcas predeterminadas con un asterisco. La ejecución de py -0p incluirá las rutas. Si py se ejecuta con un especificador de versión que no puede coincidir, también imprimirá la forma corta lista de especificadores disponibles. (Contribuido por Steve Barnes en bpo-30362 [https://bugs.python.org/issue?@action=redirect&bpo=30362].)

Portando a Python 3.7

Esta sección enumera los cambios descritos anteriormente y otras correcciones de errores que pueden requerir cambios en su código.

Cambios en el comportamiento de Python

async y await los nombres ahora son palabras clave reservadas. El código que usa estos nombres como identificadores generará ahora un SyntaxError. (Contribuido por Jelle Zijlstra en bpo-30406 [https://bugs.python.org/issue?@action=redirect&bpo=30406].)

PEP 479 [https://www.python.org/dev/peps/pep-0479] está habilitado para todo el código en Python 3.7, lo que significa que las excepciones de StopIteration generadas directa o indirectamente en corutinas y generadores se transforman en excepciones de RuntimeError. (Contribuido por Yury Selivanov en bpo-32670 [https://bugs.python.org/issue?@action=redirect&bpo=32670].)

Los métodos object.__aiter__() ya no se pueden declarar cómo asincrónicos. (Contribuido por Yury Selivanov en bpo-31709 [https://bugs.python.org/issue?@action=redirect&bpo=31709].)

Debido a un descuido, las versiones anteriores de Python aceptaron erróneamente la siguiente sintaxis:

f(1 for x in [1],)

class C(1 for x in [1]):
    pass

Python 3.7 ahora levanta correctamente una SyntaxError, como una expresión generadora siempre debe estar directamente dentro de un conjunto de paréntesis y no puede tener una coma a ambos lados, y la duplicación de los paréntesis solo se puede omitir en las llamadas. (Contribuido por Serhiy Storchaka en bpo-32012 [https://bugs.python.org/issue?@action=redirect&bpo=32012] y bpo-32023 [https://bugs.python.org/issue?@action=redirect&bpo=32023].)

Al usar el interruptor -m, el directorio de trabajo inicial ahora se agrega a: data sys.path, en lugar de una cadena vacía (que denota dinámicamente el directorio de trabajo actual en el momento de cada importación). Cualquier programa que esté comprobando la cadena vacía, o que dependa de otro modo del comportamiento anterior, deberá actualizarse en consecuencia (por ejemplo, comprobando también si hay os.getcwd() o os.path.dirname(__main__.__file__), dependiendo de por qué el código buscaba la cadena vacía en primer lugar).

Cambios en la API Python

socketserver.ThreadingMixIn.server_close() ahora espera hasta que se completen todos los subprocesos que no son demonios. Establezca el nuevo atributo de clase socketserver.ThreadingMixIn.block_on_close en False para obtener el comportamiento anterior a 3.7. (Contribuido por Victor Stinner en bpo-31233 [https://bugs.python.org/issue?@action=redirect&bpo=31233] y bpo-33540 [https://bugs.python.org/issue?@action=redirect&bpo=33540].)

socketserver.ForkingMixIn.server_close() ahora espera hasta que se completen todos los procesos secundarios. Establezca el nuevo atributo de clase socketserver.ForkingMixIn.block_on_close en False para obtener el comportamiento anterior a 3.7. (Contribuido por Victor Stinner en bpo-31151 [https://bugs.python.org/issue?@action=redirect&bpo=31151] y bpo-33540 [https://bugs.python.org/issue?@action=redirect&bpo=33540].)

La función locale.localeconv() ahora establece temporalmente la configuración regional LC_CTYPE en el valor de `LC_NUMERIC en algunos casos. (Contribuido por Victor Stinner en bpo-31900 [https://bugs.python.org/issue?@action=redirect&bpo=31900].)

pkgutil.walk_packages() ahora genera un ValueError si la* ruta * es una cadena. Anteriormente se devolvió una lista vacía. (Contribuido por Sanyam Khurana en bpo-24744 [https://bugs.python.org/issue?@action=redirect&bpo=24744].)

Un argumento de cadena de formato para string.Formatter.format() es ahora solo posicional. Pasarlo como un argumento de palabra clave quedó obsoleto en Python 3.5. (Contribuido por Serhiy Storchaka en bpo-29193 [https://bugs.python.org/issue?@action=redirect&bpo=29193].)

Atributos key, value y coded_value de la clase http.cookies.Morsel ahora son de solo lectura. La asignación a ellos quedó obsoleta en Python 3.5. Utilizar el método set() para configurarlos. (Contribuido por Serhiy Storchaka en bpo-29192 [https://bugs.python.org/issue?@action=redirect&bpo=29192].)

El argumento * modo * de os.makedirs() ya no afecta a los bits de permisos de archivos de los directorios de nivel intermedio recién creados. Para configurar sus bits de permiso de archivo, puede configurar la máscara de usuario antes de invocar `makedirs(). (Contribuido por Serhiy Storchaka en bpo-19930 [https://bugs.python.org/issue?@action=redirect&bpo=19930].)

El tipo struct.Struct.format ahora es str en lugar de: class bytes. (Contribuido por Victor Stinner en bpo-21071 [https://bugs.python.org/issue?@action=redirect&bpo=21071].)

parse_multipart() ahora acepta los argumentos * codificación * y * errores * y devuelve los mismos resultados que FieldStorage: para campos que no son de archivo, el valor asociado a una clave es una lista de cadenas, no bytes. (Contribuido por Pierre Quentel en bpo-29979 [https://bugs.python.org/issue?@action=redirect&bpo=29979].)

Debido a cambios internos en socket, llamar socket.fromshare() en un socket creado por socket.share en versiones anteriores de Python no es compatible.

repr para BaseException ha cambiado para no incluir la coma final. La mayoría de las excepciones se ven afectadas por este cambio. (Contribuido por Serhiy Storchaka en bpo-30399 [https://bugs.python.org/issue?@action=redirect&bpo=30399].)

repr para datetime.timedelta ha cambiado para incluir los argumentos de palabras clave en la salida. (Contribuido por Utkarsh Upadhyay en bpo-30302 [https://bugs.python.org/issue?@action=redirect&bpo=30302].)

Debido a que shutil.rmtree() ahora se implementa usando la función os.scandir(), el controlador especificado por el usuario onerror ahora se llama con el primer argumento os.scandir en lugar de os.listdir cuando falla el listado del directorio.

Es posible que en el futuro se agregue soporte para conjuntos anidados y operaciones de conjuntos en expresiones regulares como en Unicode Technical Standard #18 [https://unicode.org/reports/tr18/]. Esto cambiaría la sintaxis. Para facilitar este cambio futuro, por el momento, se planteará un FutureWarning en casos ambiguos. Que incluyen conjuntos que comienzan con un literal ’[‘ o que contienen secuencias de caracteres literales ’—‘, ’&&’, ’~~’, and ’||’. Para evitar una advertencia, escapa de ellos con una barra invertida. (Contribuido por Serhiy Storchaka en bpo-30349 [https://bugs.python.org/issue?@action=redirect&bpo=30349].)

El resultado de dividir una cuerda en un expresión regular que podría coincidir con una cadena vacía. Por ejemplo, dividir en r’\s*’ ahora dividirá no solo en espacios en blanco como lo hizo anteriormente, sino también en cadenas vacías antes de todos los caracteres que no sean espacios en blanco y justo antes del final de la cadena. El comportamiento anterior se puede restaurar cambiando el patrón a r’\s+’. Una FutureWarning se emitió para tales patrones desde Python 3.5.

Para patrones que coinciden con cadenas vacías y no vacías, el resultado de la búsqueda de todas las coincidencias también puede cambiarse en otros casos. Por ejemplo en la cadena ’a\n\n’, el patrón ’\n’ no solo coincidirá con cadenas vacías en las posiciones 2 y 3, sino también la cadena `` ‘n’`` en las posiciones 2–3. Para hacer coincidir solo líneas en blanco, el patrón debe reescribirse como r’(?m)^[^\S\n]*$’.

re.sub() ahora reemplaza las coincidencias vacías adyacentes a una coincidencia anterior no vacía. Por ejemplo re.sub(‘x*’, ‘-‘, ‘abxd’) retorno ahora ’-a-b—d-‘ en lugar de ’-a-b-d-‘ (el primer signo menos entre ‘b’ y ‘d’ reemplaza a ‘x’, y el segundo signo menos reemplaza una cadena vacía entre ‘x’ y ‘d’).

(Contribuido por Serhiy Storchaka en bpo-25054 [https://bugs.python.org/issue?@action=redirect&bpo=25054] y bpo-32308 [https://bugs.python.org/issue?@action=redirect&bpo=32308].)

Cambie re.escape() para escapar solo de los caracteres especiales regex en lugar de escapar de todos los caracteres que no sean letras ASCII, números y ’_’. (Contribuido por Serhiy Storchaka en bpo-29995 [https://bugs.python.org/issue?@action=redirect&bpo=29995].)

Los marcos tracemalloc.Traceback ahora se ordenan del más antiguo al más reciente para ser más coherentes con traceback. (Contribuido por Jesse Bakker en bpo-32121 [https://bugs.python.org/issue?@action=redirect&bpo=32121].)

En sistemas operativos que admiten banderas de bits socket.SOCK_NONBLOCK o socket.SOCK_CLOEXEC, el socket.type ya no los tiene aplicados. Por lo tanto, comprobaciones como if sock.type == socket.SOCK_STREAM funcionan como se espera en todas las plataformas. (Contribuido por Yury Selivanov en bpo-32331 [https://bugs.python.org/issue?@action=redirect&bpo=32331].)

En Windows, el valor predeterminado para el argumento close_fds de subprocess.Popen se cambió de False a True al redirigir los identificadores estándar. Si anteriormente dependía de que los identificadores fueran heredados al usar subprocess.Popen con la redirección estándar de io, tendrá que pasar close_fds=False para preservar el comportamiento anterior, o usar STARTUPINFO.lpAttributeList.

importlib.machinery.PathFinder.invalidate_caches() – que afecta implícitamente a importlib.invalidate_caches() – ahora borra entradas en sys.path_importer_cache que están configuradas en None. (Contribuido por Brett Cannon en bpo-33169 [https://bugs.python.org/issue?@action=redirect&bpo=33169].)

En asyncio, loop.sock_recv(), loop.sock_sendall(), loop.sock_accept(), loop.getaddrinfo(), loop.getnameinfo() se han cambiado para que sean métodos de rutina adecuados para que coincidan con su documentación. Anteriormente, estos métodos devolvían instancias asyncio.Future. (Contribuido por Yury Selivanov en bpo-32327 [https://bugs.python.org/issue?@action=redirect&bpo=32327].)

asyncio.Server.sockets ahora devuelve una copia de la lista interna de sockets del servidor, en lugar de devolverla directamente. (Contribuido por Yury Selivanov en bpo-32662 [https://bugs.python.org/issue?@action=redirect&bpo=32662].)

Struct.format es ahora una instancia str en lugar de una instancia bytes. (Contribuido por Victor Stinner en bpo-21071 [https://bugs.python.org/issue?@action=redirect&bpo=21071].)

argparse subparsers ahora pueden hacerse obligatorios pasando required=True a ArgumentParser.add_subparsers(). (Contribuido por Anthony Sottile en bpo-26510 [https://bugs.python.org/issue?@action=redirect&bpo=26510].)

ast.literal_eval() ahora es más estricto. Ya no se permiten sumas y restas de números arbitrarios. (Contribuido por Serhiy Storchaka en bpo-31778 [https://bugs.python.org/issue?@action=redirect&bpo=31778].)

Calendar.itermonthdates ahora generará una excepción cuando una fecha cae fuera del rango de 0001-01-01 a 9999-12-31. Para admitir aplicaciones que no pueden tolerar tales excepciones, se puede utilizar el nuevo Calendar.itermonthdays3 y Calendar.itermonthdays4. Los nuevos métodos devuelven tuplas y no están restringidos por el rango admitido por datetime.date. (Contribuido por Alexander Belopolsky en bpo-28292 [https://bugs.python.org/issue?@action=redirect&bpo=28292].)

collections.ChainMap ahora conserva el orden de las asignaciones subyacentes. (Contribuido por Raymond Hettinger en bpo-32792 [https://bugs.python.org/issue?@action=redirect&bpo=32792].)

El método submit() de concurrent.futures.ThreadPoolExecutor y concurrent.futures.ProcessPoolExecutor ahora genera un RuntimeError si se llama durante el cierre del intérprete. (Contribuido por Mark Nemec en bpo-33097 [https://bugs.python.org/issue?@action=redirect&bpo=33097].)

El constructor configparser.ConfigParser ahora usa read_dict() para procesar los valores predeterminados, haciendo que su comportamiento sea coherente con el resto del analizador. Las claves y los valores que no son cadenas en el diccionario de valores predeterminados ahora se están convirtiendo implícitamente en cadenas. (Contribuido por James Tocknell en bpo-23835 [https://bugs.python.org/issue?@action=redirect&bpo=23835].)

Se eliminaron varias importaciones internas indocumentadas. Un ejemplo es que os.errno ya no está disponible; use import errno directamente en su lugar. Tenga en cuenta que estas importaciones internas no documentadas pueden eliminarse en cualquier momento sin previo aviso, incluso en las versiones micro.

Cambios en la API de C

La función PySlice_GetIndicesEx() se considera insegura para secuencias de tamaño variable. Si los índices de corte no son instancias de int, sino objetos que implementan el método meth:!__index__, la secuencia se puede cambiar de tamaño después de pasar su longitud a PySlice_GetIndicesEx(). Esto puede llevar a que se devuelvan índices fuera de la longitud de la secuencia. Esto puede llevar a devolver índices fuera de la longitud de la secuencia. Para evitar posibles problemas, use las nuevas funciones PySlice_Unpack() y PySlice_AdjustIndices(). (Contribuido por Serhiy Storchaka en bpo-27867 [https://bugs.python.org/issue?@action=redirect&bpo=27867].)

Cambios en el código de bytes de CPython

Hay dos nuevos códigos de operación: LOAD_METHOD y CALL_METHOD. (Contribuido por Yury Selivanov y INADA Naoki en bpo-26110 [https://bugs.python.org/issue?@action=redirect&bpo=26110].)

El código de operación STORE_ANNOTATION ha sido removido. (Contribuido por Mark Shannon en bpo-32550 [https://bugs.python.org/issue?@action=redirect&bpo=32550].)

Cambios solo en Windows

El archivo utilizado para anular sys.path es ahora llamado <python-executable>._pth en lugar de ’sys.path’. Consultar Encontrar módulos para mas información. (Contribuido por Steve Dower en bpo-28137 [https://bugs.python.org/issue?@action=redirect&bpo=28137].)

Otra implementación de cambios en CPython

En preparación para posibles cambios futuros en la API pública de inicialización del tiempo de ejecución de CPython (ver PEP 432 [https://www.python.org/dev/peps/pep-0432] para un borrador inicial, pero algo desactualizado), La lógica de gestión de configuración y puesta en marcha interna de CPython se ha re-factorizado significativamente. Si bien estas actualizaciones están destinadas a ser completamente transparentes tanto para las aplicaciones integradas como para los usuarios de la CLI de CPython normal, se mencionan aquí ya que la refactorización cambia el orden interno de varias operaciones durante el inicio del intérprete y, por lo tanto, pueden descubrir defectos previamente latentes, ya sea en aplicaciones incrustadas, o en el propio CPython. ( Inicialmente contribuido por Nick Coghlan y Eric Snow como parte de bpo-22257 [https://bugs.python.org/issue?@action=redirect&bpo=22257], y actualizado por Nick, Eric, y Victor Stinner en varios otros números). Algunos detalles conocidos afectados:

PySys_AddWarnOptionUnicode() actualmente no se puede utilizar para incrustar aplicaciones debido al requisito de crear un objeto Unicode antes de llamar Py_Initialize. En su lugar use PySys_AddWarnOption().

filtros de advertencias agregados por una aplicación de incrustación con PySys_AddWarnOption() ahora debería tener prioridad sobre los filtros predeterminados establecidos por el intérprete

Debido a cambios en la forma en que se configuran los filtros de advertencias predeterminados, establecer Py_BytesWarningFlag en un valor mayor que uno ya no es suficiente para que ambos emitan mensajes BytesWarning y los conviertan en excepciones. En su lugar, se debe establecer la bandera (para hacer que las advertencias se emitan en primer lugar) y se debe agregar un filtro de advertencias explícito error::BytesWarning para convertirlas en excepciones.

Debido a un cambio en la forma en que el compilador maneja las cadenas de documentos, el implícito return None en el cuerpo de una función que consiste únicamente en una cadena de documentos ahora se marca como ocurriendo en la misma línea que la cadena de documentos, no en la línea de encabezado de la función.

El estado de excepción actual se ha movido del objeto de trama a la co-rutina. Esto simplificó el intérprete y corrigió un par de errores oscuros causados por tener un estado de excepción de intercambio al ingresar o salir de un generador. (Contribuido por Mark Shannon en bpo-25612 [https://bugs.python.org/issue?@action=redirect&bpo=25612].)

Cambios notables en Python 3.7.1

A partir de 3.7.1, Py_Initialize() ahora lee y respeta constantemente todos los mismos ajustes de entorno que Py_Main() (en versiones anteriores de Python, respetaba un subconjunto mal definido de esas variables de entorno, mientras que en Python 3.7.0 no leyó ninguna de ellas debido a bpo-34247 [https://bugs.python.org/issue?@action=redirect&bpo=34247]). Si este comportamiento no es deseado, establezca Py_IgnoreEnvironmentFlag en 1 antes de llamar a Py_Initialize().

En 3.7.1 la API C para las variables de Contexto ha sido actualizada para usar punteros PyObject. Ver también bpo-34762 [https://bugs.python.org/issue?@action=redirect&bpo=34762].

En 3.7.1 el módulo tokenize ahora emite un token NEWLINE cuando se le proporciona una entrada que no tiene una nueva línea al final. Este comportamiento ahora coincide con lo que hace el tokenizador C internamente. (Contribuido por Ammar Askar en bpo-33899 [https://bugs.python.org/issue?@action=redirect&bpo=33899].)

Cambios notables en Python 3.7.2

En 3.7.2, venv en Windows ya no copia los binarios originales, sino que crea scripts de redireccionamiento llamados python.exe y pythonw.exe en su lugar. Esto resuelve un problema de larga data en el que todos los entornos virtuales tendrían que actualizarse o recrearse con cada actualización de Python. Sin embargo, tenga en cuenta que esta versión aún requerirá la recreación de entornos virtuales para obtener los nuevos scripts.

Cambios notables en Python 3.7.6

Debido a importantes problemas de seguridad, el parámetro reuse_address de asyncio.loop.create_datagram_endpoint() ya no es compatible. Esto se debe al comportamiento de la opción socket SO_REUSEADDR en UDP. Para obtener más detalles, consulte la documentación de loop.create_datagram_endpoint(). (Contribuido por Kyle Stanley, Antoine Pitrou, y Yury Selivanov en bpo-37228 [https://bugs.python.org/issue?@action=redirect&bpo=37228].)

Cambios notables en Python 3.7.10

Las versiones anteriores de Python permitían usar tanto ; como & como separadores de parámetros de consulta en urllib.parse.parse_qs() y urllib.parse.parse_qsl(). Debido a problemas de seguridad y para cumplir con las recomendaciones más recientes del W3C, esto se ha cambiado para permitir solo una clave separadora, con & como valor predeterminado. Este cambio también afecta a cgi.parse() y cgi.parse_multipart() ya que utilizan las funciones afectadas internamente. Para obtener más detalles, consulte su documentación respectiva. (Contribuido por Adam Goldschmidt, Senthil Kumaran y Ken Jin en bpo-42967 [https://bugs.python.org/issue?@action=redirect&bpo=42967].)

What’s New In Python 3.6

Editors

Elvis Pranskevichus <elvis@magic.io>, Yury Selivanov <yury@magic.io>

This article explains the new features in Python 3.6, compared to 3.5. Python 3.6 was released on December 23, 2016.  See the changelog [https://docs.python.org/3.6/whatsnew/changelog.html] for a full list of changes.

Ver también

PEP 494 [https://www.python.org/dev/peps/pep-0494] - Python 3.6 Release Schedule

Summary – Release highlights

New syntax features:

PEP 498, formatted string literals.

PEP 515, underscores in numeric literals.

PEP 526, syntax for variable annotations.

PEP 525, asynchronous generators.

PEP 530: asynchronous comprehensions.

New library modules:

secrets: PEP 506 – Adding A Secrets Module To The Standard Library.

CPython implementation improvements:

The dict type has been reimplemented to use a more compact representation based on a proposal by Raymond Hettinger [https://mail.python.org/pipermail/python-dev/2012-December/123028.html] and similar to the PyPy dict implementation [https://morepypy.blogspot.com/2015/01/faster-more-memory-efficient-and-more.html]. This resulted in dictionaries using 20% to 25% less memory when compared to Python 3.5.

Customization of class creation has been simplified with the new protocol.

The class attribute definition order is now preserved.

The order of elements in **kwargs now corresponds to the order in which keyword arguments were passed to the function.

DTrace and SystemTap probing support has been added.

The new PYTHONMALLOC environment variable can now be used to debug the interpreter memory allocation and access errors.

Significant improvements in the standard library:

The asyncio module has received new features, significant usability and performance improvements, and a fair amount of bug fixes. Starting with Python 3.6 the asyncio module is no longer provisional and its API is considered stable.

A new file system path protocol has been implemented to support path-like objects. All standard library functions operating on paths have been updated to work with the new protocol.

The datetime module has gained support for Local Time Disambiguation.

The typing module received a number of improvements.

The tracemalloc module has been significantly reworked and is now used to provide better output for ResourceWarning as well as provide better diagnostics for memory allocation errors. See the PYTHONMALLOC section for more information.

Security improvements:

The new secrets module has been added to simplify the generation of cryptographically strong pseudo-random numbers suitable for managing secrets such as account authentication, tokens, and similar.

On Linux, os.urandom() now blocks until the system urandom entropy pool is initialized to increase the security. See the PEP 524 [https://www.python.org/dev/peps/pep-0524] for the rationale.

The hashlib and ssl modules now support OpenSSL 1.1.0.

The default settings and feature set of the ssl module have been improved.

The hashlib module received support for the BLAKE2, SHA-3 and SHAKE hash algorithms and the scrypt() key derivation function.

Windows improvements:

PEP 528 and PEP 529, Windows filesystem and console encoding changed to UTF-8.

The py.exe launcher, when used interactively, no longer prefers Python 2 over Python 3 when the user doesn’t specify a version (via command line arguments or a config file). Handling of shebang lines remains unchanged - «python» refers to Python 2 in that case.

python.exe and pythonw.exe have been marked as long-path aware, which means that the 260 character path limit may no longer apply. See removing the MAX_PATH limitation for details.

A ._pth file can be added to force isolated mode and fully specify all search paths to avoid registry and environment lookup. See the documentation for more information.

A python36.zip file now works as a landmark to infer PYTHONHOME. See the documentation for more information.

New Features

PEP 498: Formatted string literals

PEP 498 [https://www.python.org/dev/peps/pep-0498] introduces a new kind of string literals: f-strings, or formatted string literals.

Formatted string literals are prefixed with 'f' and are similar to the format strings accepted by str.format(). They contain replacement fields surrounded by curly braces. The replacement fields are expressions, which are evaluated at run time, and then formatted using the format() protocol:

>>> name = "Fred"
>>> f"He said his name is {name}."
'He said his name is Fred.'
>>> width = 10
>>> precision = 4
>>> value = decimal.Decimal("12.34567")
>>> f"result: {value:{width}.{precision}}"  # nested fields
'result:      12.35'

Ver también

PEP 498 [https://www.python.org/dev/peps/pep-0498] – Literal String Interpolation.

PEP written and implemented by Eric V. Smith.

Feature documentation.

PEP 526: Syntax for variable annotations

PEP 484 [https://www.python.org/dev/peps/pep-0484] introduced the standard for type annotations of function parameters, a.k.a. type hints. This PEP adds syntax to Python for annotating the types of variables including class variables and instance variables:

primes: List[int] = []

captain: str  # Note: no initial value!

class Starship:
    stats: Dict[str, int] = {}

Just as for function annotations, the Python interpreter does not attach any particular meaning to variable annotations and only stores them in the __annotations__ attribute of a class or module.

In contrast to variable declarations in statically typed languages, the goal of annotation syntax is to provide an easy way to specify structured type metadata for third party tools and libraries via the abstract syntax tree and the __annotations__ attribute.

Ver también

PEP 526 [https://www.python.org/dev/peps/pep-0526] – Syntax for variable annotations.

PEP written by Ryan Gonzalez, Philip House, Ivan Levkivskyi, Lisa Roach, and Guido van Rossum. Implemented by Ivan Levkivskyi.

Tools that use or will use the new syntax: mypy [http://www.mypy-lang.org/], pytype [https://github.com/google/pytype], PyCharm, etc.

PEP 515: Underscores in Numeric Literals

PEP 515 [https://www.python.org/dev/peps/pep-0515] adds the ability to use underscores in numeric literals for improved readability. For example:

>>> 1_000_000_000_000_000
1000000000000000
>>> 0x_FF_FF_FF_FF
4294967295

Single underscores are allowed between digits and after any base specifier. Leading, trailing, or multiple underscores in a row are not allowed.

The string formatting language also now has support for the '_' option to signal the use of an underscore for a thousands separator for floating point presentation types and for integer presentation type 'd'. For integer presentation types 'b', 'o', 'x', and 'X', underscores will be inserted every 4 digits:

>>> '{:_}'.format(1000000)
'1_000_000'
>>> '{:_x}'.format(0xFFFFFFFF)
'ffff_ffff'

Ver también

PEP 515 [https://www.python.org/dev/peps/pep-0515] – Underscores in Numeric Literals

PEP written by Georg Brandl and Serhiy Storchaka.

PEP 525: Asynchronous Generators

PEP 492 [https://www.python.org/dev/peps/pep-0492] introduced support for native coroutines and async / await syntax to Python 3.5. A notable limitation of the Python 3.5 implementation is that it was not possible to use await and yield in the same function body. In Python 3.6 this restriction has been lifted, making it possible to define asynchronous generators:

async def ticker(delay, to):
    """Yield numbers from 0 to *to* every *delay* seconds."""
    for i in range(to):
        yield i
        await asyncio.sleep(delay)

The new syntax allows for faster and more concise code.

Ver también

PEP 525 [https://www.python.org/dev/peps/pep-0525] – Asynchronous Generators

PEP written and implemented by Yury Selivanov.

PEP 530: Asynchronous Comprehensions

PEP 530 [https://www.python.org/dev/peps/pep-0530] adds support for using async for in list, set, dict comprehensions and generator expressions:

result = [i async for i in aiter() if i % 2]

Additionally, await expressions are supported in all kinds of comprehensions:

result = [await fun() for fun in funcs if await condition()]

Ver también

PEP 530 [https://www.python.org/dev/peps/pep-0530] – Asynchronous Comprehensions

PEP written and implemented by Yury Selivanov.

PEP 487: Simpler customization of class creation

It is now possible to customize subclass creation without using a metaclass. The new __init_subclass__ classmethod will be called on the base class whenever a new subclass is created:

class PluginBase:
    subclasses = []

    def __init_subclass__(cls, **kwargs):
        super().__init_subclass__(**kwargs)
        cls.subclasses.append(cls)

class Plugin1(PluginBase):
    pass

class Plugin2(PluginBase):
    pass

In order to allow zero-argument super() calls to work correctly from __init_subclass__() implementations, custom metaclasses must ensure that the new __classcell__ namespace entry is propagated to type.__new__ (as described in Creando el objeto de clase).

Ver también

PEP 487 [https://www.python.org/dev/peps/pep-0487] – Simpler customization of class creation

PEP written and implemented by Martin Teichmann.

Feature documentation

PEP 487: Descriptor Protocol Enhancements

PEP 487 [https://www.python.org/dev/peps/pep-0487] extends the descriptor protocol to include the new optional __set_name__() method. Whenever a new class is defined, the new method will be called on all descriptors included in the definition, providing them with a reference to the class being defined and the name given to the descriptor within the class namespace. In other words, instances of descriptors can now know the attribute name of the descriptor in the owner class:

class IntField:
    def __get__(self, instance, owner):
        return instance.__dict__[self.name]

    def __set__(self, instance, value):
        if not isinstance(value, int):
            raise ValueError(f'expecting integer in {self.name}')
        instance.__dict__[self.name] = value

    # this is the new initializer:
    def __set_name__(self, owner, name):
        self.name = name

class Model:
    int_field = IntField()

Ver también

PEP 487 [https://www.python.org/dev/peps/pep-0487] – Simpler customization of class creation

PEP written and implemented by Martin Teichmann.

Feature documentation

PEP 519: Adding a file system path protocol

File system paths have historically been represented as str or bytes objects. This has led to people who write code which operate on file system paths to assume that such objects are only one of those two types (an int representing a file descriptor does not count as that is not a file path). Unfortunately that assumption prevents alternative object representations of file system paths like pathlib from working with pre-existing code, including Python’s standard library.

To fix this situation, a new interface represented by os.PathLike has been defined. By implementing the __fspath__() method, an object signals that it represents a path. An object can then provide a low-level representation of a file system path as a str or bytes object. This means an object is considered path-like if it implements os.PathLike or is a str or bytes object which represents a file system path. Code can use os.fspath(), os.fsdecode(), or os.fsencode() to explicitly get a str and/or bytes representation of a path-like object.

The built-in open() function has been updated to accept os.PathLike objects, as have all relevant functions in the os and os.path modules, and most other functions and classes in the standard library. The os.DirEntry class and relevant classes in pathlib have also been updated to implement os.PathLike.

The hope is that updating the fundamental functions for operating on file system paths will lead to third-party code to implicitly support all path-like objects without any code changes, or at least very minimal ones (e.g. calling os.fspath() at the beginning of code before operating on a path-like object).

Here are some examples of how the new interface allows for pathlib.Path to be used more easily and transparently with pre-existing code:

>>> import pathlib
>>> with open(pathlib.Path("README")) as f:
...     contents = f.read()
...
>>> import os.path
>>> os.path.splitext(pathlib.Path("some_file.txt"))
('some_file', '.txt')
>>> os.path.join("/a/b", pathlib.Path("c"))
'/a/b/c'
>>> import os
>>> os.fspath(pathlib.Path("some_file.txt"))
'some_file.txt'

(Implemented by Brett Cannon, Ethan Furman, Dusty Phillips, and Jelle Zijlstra.)

Ver también

PEP 519 [https://www.python.org/dev/peps/pep-0519] – Adding a file system path protocol

PEP written by Brett Cannon and Koos Zevenhoven.

PEP 495: Local Time Disambiguation

In most world locations, there have been and will be times when local clocks are moved back. In those times, intervals are introduced in which local clocks show the same time twice in the same day. In these situations, the information displayed on a local clock (or stored in a Python datetime instance) is insufficient to identify a particular moment in time.

PEP 495 [https://www.python.org/dev/peps/pep-0495] adds the new fold attribute to instances of datetime.datetime and datetime.time classes to differentiate between two moments in time for which local times are the same:

>>> u0 = datetime(2016, 11, 6, 4, tzinfo=timezone.utc)
>>> for i in range(4):
...     u = u0 + i*HOUR
...     t = u.astimezone(Eastern)
...     print(u.time(), 'UTC =', t.time(), t.tzname(), t.fold)
...
04:00:00 UTC = 00:00:00 EDT 0
05:00:00 UTC = 01:00:00 EDT 0
06:00:00 UTC = 01:00:00 EST 1
07:00:00 UTC = 02:00:00 EST 0

The values of the fold attribute have the value 0 for all instances except those that represent the second (chronologically) moment in time in an ambiguous case.

Ver también

PEP 495 [https://www.python.org/dev/peps/pep-0495] – Local Time Disambiguation

PEP written by Alexander Belopolsky and Tim Peters, implementation by Alexander Belopolsky.

PEP 529: Change Windows filesystem encoding to UTF-8

Representing filesystem paths is best performed with str (Unicode) rather than bytes. However, there are some situations where using bytes is sufficient and correct.

Prior to Python 3.6, data loss could result when using bytes paths on Windows. With this change, using bytes to represent paths is now supported on Windows, provided those bytes are encoded with the encoding returned by sys.getfilesystemencoding(), which now defaults to 'utf-8'.

Applications that do not use str to represent paths should use os.fsencode() and os.fsdecode() to ensure their bytes are correctly encoded. To revert to the previous behaviour, set PYTHONLEGACYWINDOWSFSENCODING or call sys._enablelegacywindowsfsencoding().

See PEP 529 [https://www.python.org/dev/peps/pep-0529] for more information and discussion of code modifications that may be required.

PEP 528: Change Windows console encoding to UTF-8

The default console on Windows will now accept all Unicode characters and provide correctly read str objects to Python code. sys.stdin, sys.stdout and sys.stderr now default to utf-8 encoding.

This change only applies when using an interactive console, and not when redirecting files or pipes. To revert to the previous behaviour for interactive console use, set PYTHONLEGACYWINDOWSSTDIO.

Ver también

PEP 528 [https://www.python.org/dev/peps/pep-0528] – Change Windows console encoding to UTF-8

PEP written and implemented by Steve Dower.

PEP 520: Preserving Class Attribute Definition Order

Attributes in a class definition body have a natural ordering: the same order in which the names appear in the source. This order is now preserved in the new class’s __dict__ attribute.

Also, the effective default class execution namespace (returned from type.__prepare__()) is now an insertion-order-preserving mapping.

Ver también

PEP 520 [https://www.python.org/dev/peps/pep-0520] – Preserving Class Attribute Definition Order

PEP written and implemented by Eric Snow.

PEP 468: Preserving Keyword Argument Order

**kwargs in a function signature is now guaranteed to be an insertion-order-preserving mapping.

Ver también

PEP 468 [https://www.python.org/dev/peps/pep-0468] – Preserving Keyword Argument Order

PEP written and implemented by Eric Snow.

New dict implementation

The dict type now uses a «compact» representation based on a proposal by Raymond Hettinger [https://mail.python.org/pipermail/python-dev/2012-December/123028.html] which was first implemented by PyPy [https://morepypy.blogspot.com/2015/01/faster-more-memory-efficient-and-more.html]. The memory usage of the new dict() is between 20% and 25% smaller compared to Python 3.5.

The order-preserving aspect of this new implementation is considered an implementation detail and should not be relied upon (this may change in the future, but it is desired to have this new dict implementation in the language for a few releases before changing the language spec to mandate order-preserving semantics for all current and future Python implementations; this also helps preserve backwards-compatibility with older versions of the language where random iteration order is still in effect, e.g. Python 3.5).

(Contributed by INADA Naoki in bpo-27350 [https://bugs.python.org/issue?@action=redirect&bpo=27350]. Idea originally suggested by Raymond Hettinger [https://mail.python.org/pipermail/python-dev/2012-December/123028.html].)

PEP 523: Adding a frame evaluation API to CPython

While Python provides extensive support to customize how code executes, one place it has not done so is in the evaluation of frame objects. If you wanted some way to intercept frame evaluation in Python there really wasn’t any way without directly manipulating function pointers for defined functions.

PEP 523 [https://www.python.org/dev/peps/pep-0523] changes this by providing an API to make frame evaluation pluggable at the C level. This will allow for tools such as debuggers and JITs to intercept frame evaluation before the execution of Python code begins. This enables the use of alternative evaluation implementations for Python code, tracking frame evaluation, etc.

This API is not part of the limited C API and is marked as private to signal that usage of this API is expected to be limited and only applicable to very select, low-level use-cases. Semantics of the API will change with Python as necessary.

Ver también

PEP 523 [https://www.python.org/dev/peps/pep-0523] – Adding a frame evaluation API to CPython

PEP written by Brett Cannon and Dino Viehland.

PYTHONMALLOC environment variable

The new PYTHONMALLOC environment variable allows setting the Python memory allocators and installing debug hooks.

It is now possible to install debug hooks on Python memory allocators on Python compiled in release mode using PYTHONMALLOC=debug. Effects of debug hooks:

Newly allocated memory is filled with the byte 0xCB

Freed memory is filled with the byte 0xDB

Detect violations of the Python memory allocator API. For example, PyObject_Free() called on a memory block allocated by PyMem_Malloc().

Detect writes before the start of a buffer (buffer underflows)

Detect writes after the end of a buffer (buffer overflows)

Check that the GIL is held when allocator functions of PYMEM_DOMAIN_OBJ (ex: PyObject_Malloc()) and PYMEM_DOMAIN_MEM (ex: PyMem_Malloc()) domains are called.

Checking if the GIL is held is also a new feature of Python 3.6.

See the PyMem_SetupDebugHooks() function for debug hooks on Python memory allocators.

It is now also possible to force the usage of the malloc() allocator of the C library for all Python memory allocations using PYTHONMALLOC=malloc. This is helpful when using external memory debuggers like Valgrind on a Python compiled in release mode.

On error, the debug hooks on Python memory allocators now use the tracemalloc module to get the traceback where a memory block was allocated.

Example of fatal error on buffer overflow using python3.6 -X tracemalloc=5 (store 5 frames in traces):

Debug memory block at address p=0x7fbcd41666f8: API 'o'
    4 bytes originally requested
    The 7 pad bytes at p-7 are FORBIDDENBYTE, as expected.
    The 8 pad bytes at tail=0x7fbcd41666fc are not all FORBIDDENBYTE (0xfb):
        at tail+0: 0x02 *** OUCH
        at tail+1: 0xfb
        at tail+2: 0xfb
        at tail+3: 0xfb
        at tail+4: 0xfb
        at tail+5: 0xfb
        at tail+6: 0xfb
        at tail+7: 0xfb
    The block was made by call #1233329 to debug malloc/realloc.
    Data at p: 1a 2b 30 00

Memory block allocated at (most recent call first):
  File "test/test_bytes.py", line 323
  File "unittest/case.py", line 600
  File "unittest/case.py", line 648
  File "unittest/suite.py", line 122
  File "unittest/suite.py", line 84

Fatal Python error: bad trailing pad byte

Current thread 0x00007fbcdbd32700 (most recent call first):
  File "test/test_bytes.py", line 323 in test_hex
  File "unittest/case.py", line 600 in run
  File "unittest/case.py", line 648 in __call__
  File "unittest/suite.py", line 122 in run
  File "unittest/suite.py", line 84 in __call__
  File "unittest/suite.py", line 122 in run
  File "unittest/suite.py", line 84 in __call__
  ...

(Contributed by Victor Stinner in bpo-26516 [https://bugs.python.org/issue?@action=redirect&bpo=26516] and bpo-26564 [https://bugs.python.org/issue?@action=redirect&bpo=26564].)

DTrace and SystemTap probing support

Python can now be built --with-dtrace which enables static markers for the following events in the interpreter:

function call/return

garbage collection started/finished

line of code executed.

This can be used to instrument running interpreters in production, without the need to recompile specific debug builds or providing application-specific profiling/debugging code.

More details in Instrumentación de CPython con DTrace y SystemTap.

The current implementation is tested on Linux and macOS. Additional markers may be added in the future.

(Contributed by Łukasz Langa in bpo-21590 [https://bugs.python.org/issue?@action=redirect&bpo=21590], based on patches by Jesús Cea Avión, David Malcolm, and Nikhil Benesch.)

Other Language Changes

Some smaller changes made to the core Python language are:

A global or nonlocal statement must now textually appear before the first use of the affected name in the same scope. Previously this was a SyntaxWarning.

It is now possible to set a special method to None to indicate that the corresponding operation is not available. For example, if a class sets __iter__() to None, the class is not iterable. (Contributed by Andrew Barnert and Ivan Levkivskyi in bpo-25958 [https://bugs.python.org/issue?@action=redirect&bpo=25958].)

Long sequences of repeated traceback lines are now abbreviated as "[Previous line repeated {count} more times]" (see traceback for an example). (Contributed by Emanuel Barry in bpo-26823 [https://bugs.python.org/issue?@action=redirect&bpo=26823].)

Import now raises the new exception ModuleNotFoundError (subclass of ImportError) when it cannot find a module. Code that currently checks for ImportError (in try-except) will still work. (Contributed by Eric Snow in bpo-15767 [https://bugs.python.org/issue?@action=redirect&bpo=15767].)

Class methods relying on zero-argument super() will now work correctly when called from metaclass methods during class creation. (Contributed by Martin Teichmann in bpo-23722 [https://bugs.python.org/issue?@action=redirect&bpo=23722].)

New Modules

secrets

The main purpose of the new secrets module is to provide an obvious way to reliably generate cryptographically strong pseudo-random values suitable for managing secrets, such as account authentication, tokens, and similar.

Advertencia

Note that the pseudo-random generators in the random module should NOT be used for security purposes. Use secrets on Python 3.6+ and os.urandom() on Python 3.5 and earlier.

Ver también

PEP 506 [https://www.python.org/dev/peps/pep-0506] – Adding A Secrets Module To The Standard Library

PEP written and implemented by Steven D’Aprano.

Improved Modules

array

Exhausted iterators of array.array will now stay exhausted even if the iterated array is extended. This is consistent with the behavior of other mutable sequences.

Contributed by Serhiy Storchaka in bpo-26492 [https://bugs.python.org/issue?@action=redirect&bpo=26492].

ast

The new ast.Constant AST node has been added. It can be used by external AST optimizers for the purposes of constant folding.

Contributed by Victor Stinner in bpo-26146 [https://bugs.python.org/issue?@action=redirect&bpo=26146].

asyncio

Starting with Python 3.6 the asyncio module is no longer provisional and its API is considered stable.

Notable changes in the asyncio module since Python 3.5.0 (all backported to 3.5.x due to the provisional status):

The get_event_loop() function has been changed to always return the currently running loop when called from coroutines and callbacks. (Contributed by Yury Selivanov in bpo-28613 [https://bugs.python.org/issue?@action=redirect&bpo=28613].)

The ensure_future() function and all functions that use it, such as loop.run_until_complete(), now accept all kinds of awaitable objects. (Contributed by Yury Selivanov.)

New run_coroutine_threadsafe() function to submit coroutines to event loops from other threads. (Contributed by Vincent Michel.)

New Transport.is_closing() method to check if the transport is closing or closed. (Contributed by Yury Selivanov.)

The loop.create_server() method can now accept a list of hosts. (Contributed by Yann Sionneau.)

New loop.create_future() method to create Future objects. This allows alternative event loop implementations, such as uvloop [https://github.com/MagicStack/uvloop], to provide a faster asyncio.Future implementation. (Contributed by Yury Selivanov in bpo-27041 [https://bugs.python.org/issue?@action=redirect&bpo=27041].)

New loop.get_exception_handler() method to get the current exception handler. (Contributed by Yury Selivanov in bpo-27040 [https://bugs.python.org/issue?@action=redirect&bpo=27040].)

New StreamReader.readuntil() method to read data from the stream until a separator bytes sequence appears. (Contributed by Mark Korenberg.)

The performance of StreamReader.readexactly() has been improved. (Contributed by Mark Korenberg in bpo-28370 [https://bugs.python.org/issue?@action=redirect&bpo=28370].)

The loop.getaddrinfo() method is optimized to avoid calling the system getaddrinfo function if the address is already resolved. (Contributed by A. Jesse Jiryu Davis.)

The loop.stop() method has been changed to stop the loop immediately after the current iteration. Any new callbacks scheduled as a result of the last iteration will be discarded. (Contributed by Guido van Rossum in bpo-25593 [https://bugs.python.org/issue?@action=redirect&bpo=25593].)

Future.set_exception will now raise TypeError when passed an instance of the StopIteration exception. (Contributed by Chris Angelico in bpo-26221 [https://bugs.python.org/issue?@action=redirect&bpo=26221].)

New loop.connect_accepted_socket() method to be used by servers that accept connections outside of asyncio, but that use asyncio to handle them. (Contributed by Jim Fulton in bpo-27392 [https://bugs.python.org/issue?@action=redirect&bpo=27392].)

TCP_NODELAY flag is now set for all TCP transports by default. (Contributed by Yury Selivanov in bpo-27456 [https://bugs.python.org/issue?@action=redirect&bpo=27456].)

New loop.shutdown_asyncgens() to properly close pending asynchronous generators before closing the loop. (Contributed by Yury Selivanov in bpo-28003 [https://bugs.python.org/issue?@action=redirect&bpo=28003].)

Future and Task classes now have an optimized C implementation which makes asyncio code up to 30% faster. (Contributed by Yury Selivanov and INADA Naoki in bpo-26081 [https://bugs.python.org/issue?@action=redirect&bpo=26081] and bpo-28544 [https://bugs.python.org/issue?@action=redirect&bpo=28544].)

binascii

The b2a_base64() function now accepts an optional newline keyword argument to control whether the newline character is appended to the return value. (Contributed by Victor Stinner in bpo-25357 [https://bugs.python.org/issue?@action=redirect&bpo=25357].)

cmath

The new cmath.tau (τ) constant has been added. (Contributed by Lisa Roach in bpo-12345 [https://bugs.python.org/issue?@action=redirect&bpo=12345], see PEP 628 [https://www.python.org/dev/peps/pep-0628] for details.)

New constants: cmath.inf and cmath.nan to match math.inf and math.nan, and also cmath.infj and cmath.nanj to match the format used by complex repr. (Contributed by Mark Dickinson in bpo-23229 [https://bugs.python.org/issue?@action=redirect&bpo=23229].)

collections

The new Collection abstract base class has been added to represent sized iterable container classes. (Contributed by Ivan Levkivskyi, docs by Neil Girdhar in bpo-27598 [https://bugs.python.org/issue?@action=redirect&bpo=27598].)

The new Reversible abstract base class represents iterable classes that also provide the __reversed__() method. (Contributed by Ivan Levkivskyi in bpo-25987 [https://bugs.python.org/issue?@action=redirect&bpo=25987].)

The new AsyncGenerator abstract base class represents asynchronous generators. (Contributed by Yury Selivanov in bpo-28720 [https://bugs.python.org/issue?@action=redirect&bpo=28720].)

The namedtuple() function now accepts an optional keyword argument module, which, when specified, is used for the __module__ attribute of the returned named tuple class. (Contributed by Raymond Hettinger in bpo-17941 [https://bugs.python.org/issue?@action=redirect&bpo=17941].)

The verbose and rename arguments for namedtuple() are now keyword-only. (Contributed by Raymond Hettinger in bpo-25628 [https://bugs.python.org/issue?@action=redirect&bpo=25628].)

Recursive collections.deque instances can now be pickled. (Contributed by Serhiy Storchaka in bpo-26482 [https://bugs.python.org/issue?@action=redirect&bpo=26482].)

concurrent.futures

The ThreadPoolExecutor class constructor now accepts an optional thread_name_prefix argument to make it possible to customize the names of the threads created by the pool. (Contributed by Gregory P. Smith in bpo-27664 [https://bugs.python.org/issue?@action=redirect&bpo=27664].)

contextlib

The contextlib.AbstractContextManager class has been added to provide an abstract base class for context managers. It provides a sensible default implementation for __enter__() which returns self and leaves __exit__() an abstract method. A matching class has been added to the typing module as typing.ContextManager. (Contributed by Brett Cannon in bpo-25609 [https://bugs.python.org/issue?@action=redirect&bpo=25609].)

datetime

The datetime and time classes have the new fold attribute used to disambiguate local time when necessary. Many functions in the datetime have been updated to support local time disambiguation. See Local Time Disambiguation section for more information. (Contributed by Alexander Belopolsky in bpo-24773 [https://bugs.python.org/issue?@action=redirect&bpo=24773].)

The datetime.strftime() and date.strftime() methods now support ISO 8601 date directives %G, %u and %V. (Contributed by Ashley Anderson in bpo-12006 [https://bugs.python.org/issue?@action=redirect&bpo=12006].)

The datetime.isoformat() function now accepts an optional timespec argument that specifies the number of additional components of the time value to include. (Contributed by Alessandro Cucci and Alexander Belopolsky in bpo-19475 [https://bugs.python.org/issue?@action=redirect&bpo=19475].)

The datetime.combine() now accepts an optional tzinfo argument. (Contributed by Alexander Belopolsky in bpo-27661 [https://bugs.python.org/issue?@action=redirect&bpo=27661].)

decimal

New Decimal.as_integer_ratio() method that returns a pair (n, d) of integers that represent the given Decimal instance as a fraction, in lowest terms and with a positive denominator:

>>> Decimal('-3.14').as_integer_ratio()
(-157, 50)

(Contributed by Stefan Krah amd Mark Dickinson in bpo-25928 [https://bugs.python.org/issue?@action=redirect&bpo=25928].)

distutils

The default_format attribute has been removed from distutils.command.sdist.sdist and the formats attribute defaults to ['gztar']. Although not anticipated, any code relying on the presence of default_format may need to be adapted. See bpo-27819 [https://bugs.python.org/issue?@action=redirect&bpo=27819] for more details.

email

The new email API, enabled via the policy keyword to various constructors, is no longer provisional. The email documentation has been reorganized and rewritten to focus on the new API, while retaining the old documentation for the legacy API. (Contributed by R. David Murray in bpo-24277 [https://bugs.python.org/issue?@action=redirect&bpo=24277].)

The email.mime classes now all accept an optional policy keyword. (Contributed by Berker Peksag in bpo-27331 [https://bugs.python.org/issue?@action=redirect&bpo=27331].)

The DecodedGenerator now supports the policy keyword.

There is a new policy attribute, message_factory, that controls what class is used by default when the parser creates new message objects. For the email.policy.compat32 policy this is Message, for the new policies it is EmailMessage. (Contributed by R. David Murray in bpo-20476 [https://bugs.python.org/issue?@action=redirect&bpo=20476].)

encodings

On Windows, added the 'oem' encoding to use CP_OEMCP, and the 'ansi' alias for the existing 'mbcs' encoding, which uses the CP_ACP code page. (Contributed by Steve Dower in bpo-27959 [https://bugs.python.org/issue?@action=redirect&bpo=27959].)

enum

Two new enumeration base classes have been added to the enum module: Flag and IntFlags. Both are used to define constants that can be combined using the bitwise operators. (Contributed by Ethan Furman in bpo-23591 [https://bugs.python.org/issue?@action=redirect&bpo=23591].)

Many standard library modules have been updated to use the IntFlags class for their constants.

The new enum.auto value can be used to assign values to enum members automatically:

>>> from enum import Enum, auto
>>> class Color(Enum):
...     red = auto()
...     blue = auto()
...     green = auto()
...
>>> list(Color)
[<Color.red: 1>, <Color.blue: 2>, <Color.green: 3>]

faulthandler

On Windows, the faulthandler module now installs a handler for Windows exceptions: see faulthandler.enable(). (Contributed by Victor Stinner in bpo-23848 [https://bugs.python.org/issue?@action=redirect&bpo=23848].)

fileinput

hook_encoded() now supports the errors argument. (Contributed by Joseph Hackman in bpo-25788 [https://bugs.python.org/issue?@action=redirect&bpo=25788].)

hashlib

hashlib supports OpenSSL 1.1.0. The minimum recommend version is 1.0.2. (Contributed by Christian Heimes in bpo-26470 [https://bugs.python.org/issue?@action=redirect&bpo=26470].)

BLAKE2 hash functions were added to the module. blake2b() and blake2s() are always available and support the full feature set of BLAKE2. (Contributed by Christian Heimes in bpo-26798 [https://bugs.python.org/issue?@action=redirect&bpo=26798] based on code by Dmitry Chestnykh and Samuel Neves. Documentation written by Dmitry Chestnykh.)

The SHA-3 hash functions sha3_224(), sha3_256(), sha3_384(), sha3_512(), and SHAKE hash functions shake_128() and shake_256() were added. (Contributed by Christian Heimes in bpo-16113 [https://bugs.python.org/issue?@action=redirect&bpo=16113]. Keccak Code Package by Guido Bertoni, Joan Daemen, Michaël Peeters, Gilles Van Assche, and Ronny Van Keer.)

The password-based key derivation function scrypt() is now available with OpenSSL 1.1.0 and newer. (Contributed by Christian Heimes in bpo-27928 [https://bugs.python.org/issue?@action=redirect&bpo=27928].)

http.client

HTTPConnection.request() and endheaders() both now support chunked encoding request bodies. (Contributed by Demian Brecht and Rolf Krahl in bpo-12319 [https://bugs.python.org/issue?@action=redirect&bpo=12319].)

idlelib and IDLE

The idlelib package is being modernized and refactored to make IDLE look and work better and to make the code easier to understand, test, and improve. Part of making IDLE look better, especially on Linux and Mac, is using ttk widgets, mostly in the dialogs. As a result, IDLE no longer runs with tcl/tk 8.4. It now requires tcl/tk 8.5 or 8.6. We recommend running the latest release of either.

“Modernizing” includes renaming and consolidation of idlelib modules. The renaming of files with partial uppercase names is similar to the renaming of, for instance, Tkinter and TkFont to tkinter and tkinter.font in 3.0. As a result, imports of idlelib files that worked in 3.5 will usually not work in 3.6. At least a module name change will be needed (see idlelib/README.txt), sometimes more. (Name changes contributed by Al Swiegart and Terry Reedy in bpo-24225 [https://bugs.python.org/issue?@action=redirect&bpo=24225]. Most idlelib patches since have been and will be part of the process.)

In compensation, the eventual result with be that some idlelib classes will be easier to use, with better APIs and docstrings explaining them. Additional useful information will be added to idlelib when available.

New in 3.6.2:

Multiple fixes for autocompletion. (Contributed by Louie Lu in bpo-15786 [https://bugs.python.org/issue?@action=redirect&bpo=15786].)

New in 3.6.3:

Module Browser (on the File menu, formerly called Class Browser), now displays nested functions and classes in addition to top-level functions and classes. (Contributed by Guilherme Polo, Cheryl Sabella, and Terry Jan Reedy in bpo-1612262 [https://bugs.python.org/issue?@action=redirect&bpo=1612262].)

The IDLE features formerly implemented as extensions have been reimplemented as normal features. Their settings have been moved from the Extensions tab to other dialog tabs. (Contributed by Charles Wohlganger and Terry Jan Reedy in bpo-27099 [https://bugs.python.org/issue?@action=redirect&bpo=27099].)

The Settings dialog (Options, Configure IDLE) has been partly rewritten to improve both appearance and function. (Contributed by Cheryl Sabella and Terry Jan Reedy in multiple issues.)

New in 3.6.4:

The font sample now includes a selection of non-Latin characters so that users can better see the effect of selecting a particular font. (Contributed by Terry Jan Reedy in bpo-13802 [https://bugs.python.org/issue?@action=redirect&bpo=13802].) The sample can be edited to include other characters. (Contributed by Serhiy Storchaka in bpo-31860 [https://bugs.python.org/issue?@action=redirect&bpo=31860].)

New in 3.6.6:

Editor code context option revised. Box displays all context lines up to maxlines. Clicking on a context line jumps the editor to that line. Context colors for custom themes is added to Highlights tab of Settings dialog. (Contributed by Cheryl Sabella and Terry Jan Reedy in bpo-33642 [https://bugs.python.org/issue?@action=redirect&bpo=33642], bpo-33768 [https://bugs.python.org/issue?@action=redirect&bpo=33768], and bpo-33679 [https://bugs.python.org/issue?@action=redirect&bpo=33679].)

On Windows, a new API call tells Windows that tk scales for DPI. On Windows 8.1+ or 10, with DPI compatibility properties of the Python binary unchanged, and a monitor resolution greater than 96 DPI, this should make text and lines sharper. It should otherwise have no effect. (Contributed by Terry Jan Reedy in bpo-33656 [https://bugs.python.org/issue?@action=redirect&bpo=33656].)

New in 3.6.7:

Output over N lines (50 by default) is squeezed down to a button. N can be changed in the PyShell section of the General page of the Settings dialog. Fewer, but possibly extra long, lines can be squeezed by right clicking on the output. Squeezed output can be expanded in place by double-clicking the button or into the clipboard or a separate window by right-clicking the button. (Contributed by Tal Einat in bpo-1529353 [https://bugs.python.org/issue?@action=redirect&bpo=1529353].)

importlib

Import now raises the new exception ModuleNotFoundError (subclass of ImportError) when it cannot find a module. Code that current checks for ImportError (in try-except) will still work. (Contributed by Eric Snow in bpo-15767 [https://bugs.python.org/issue?@action=redirect&bpo=15767].)

importlib.util.LazyLoader now calls create_module() on the wrapped loader, removing the restriction that importlib.machinery.BuiltinImporter and importlib.machinery.ExtensionFileLoader couldn’t be used with importlib.util.LazyLoader.

importlib.util.cache_from_source(), importlib.util.source_from_cache(), and importlib.util.spec_from_file_location() now accept a path-like object.

inspect

The inspect.signature() function now reports the implicit .0 parameters generated by the compiler for comprehension and generator expression scopes as if they were positional-only parameters called implicit0. (Contributed by Jelle Zijlstra in bpo-19611 [https://bugs.python.org/issue?@action=redirect&bpo=19611].)

To reduce code churn when upgrading from Python 2.7 and the legacy inspect.getargspec() API, the previously documented deprecation of inspect.getfullargspec() has been reversed. While this function is convenient for single/source Python 2/3 code bases, the richer inspect.signature() interface remains the recommended approach for new code. (Contributed by Nick Coghlan in bpo-27172 [https://bugs.python.org/issue?@action=redirect&bpo=27172])

json

json.load() and json.loads() now support binary input. Encoded JSON should be represented using either UTF-8, UTF-16, or UTF-32. (Contributed by Serhiy Storchaka in bpo-17909 [https://bugs.python.org/issue?@action=redirect&bpo=17909].)

logging

The new WatchedFileHandler.reopenIfNeeded() method has been added to add the ability to check if the log file needs to be reopened. (Contributed by Marian Horban in bpo-24884 [https://bugs.python.org/issue?@action=redirect&bpo=24884].)

math

The tau (τ) constant has been added to the math and cmath modules. (Contributed by Lisa Roach in bpo-12345 [https://bugs.python.org/issue?@action=redirect&bpo=12345], see PEP 628 [https://www.python.org/dev/peps/pep-0628] for details.)

multiprocessing

Proxy Objects returned by multiprocessing.Manager() can now be nested. (Contributed by Davin Potts in bpo-6766 [https://bugs.python.org/issue?@action=redirect&bpo=6766].)

os

See the summary of PEP 519 for details on how the os and os.path modules now support path-like objects.

scandir() now supports bytes paths on Windows.

A new close() method allows explicitly closing a scandir() iterator. The scandir() iterator now supports the context manager protocol. If a scandir() iterator is neither exhausted nor explicitly closed a ResourceWarning will be emitted in its destructor. (Contributed by Serhiy Storchaka in bpo-25994 [https://bugs.python.org/issue?@action=redirect&bpo=25994].)

On Linux, os.urandom() now blocks until the system urandom entropy pool is initialized to increase the security. See the PEP 524 [https://www.python.org/dev/peps/pep-0524] for the rationale.

The Linux getrandom() syscall (get random bytes) is now exposed as the new os.getrandom() function. (Contributed by Victor Stinner, part of the PEP 524 [https://www.python.org/dev/peps/pep-0524])

pathlib

pathlib now supports path-like objects. (Contributed by Brett Cannon in bpo-27186 [https://bugs.python.org/issue?@action=redirect&bpo=27186].)

See the summary of PEP 519 for details.

pdb

The Pdb class constructor has a new optional readrc argument to control whether .pdbrc files should be read.

pickle

Objects that need __new__ called with keyword arguments can now be pickled using pickle protocols older than protocol version 4. Protocol version 4 already supports this case. (Contributed by Serhiy Storchaka in bpo-24164 [https://bugs.python.org/issue?@action=redirect&bpo=24164].)

pickletools

pickletools.dis() now outputs the implicit memo index for the MEMOIZE opcode. (Contributed by Serhiy Storchaka in bpo-25382 [https://bugs.python.org/issue?@action=redirect&bpo=25382].)

pydoc

The pydoc module has learned to respect the MANPAGER environment variable. (Contributed by Matthias Klose in bpo-8637 [https://bugs.python.org/issue?@action=redirect&bpo=8637].)

help() and pydoc can now list named tuple fields in the order they were defined rather than alphabetically. (Contributed by Raymond Hettinger in bpo-24879 [https://bugs.python.org/issue?@action=redirect&bpo=24879].)

random

The new choices() function returns a list of elements of specified size from the given population with optional weights. (Contributed by Raymond Hettinger in bpo-18844 [https://bugs.python.org/issue?@action=redirect&bpo=18844].)

re

Added support of modifier spans in regular expressions. Examples: '(?i:p)ython' matches 'python' and 'Python', but not 'PYTHON'; '(?i)g(?-i:v)r' matches 'GvR' and 'gvr', but not 'GVR'. (Contributed by Serhiy Storchaka in bpo-433028 [https://bugs.python.org/issue?@action=redirect&bpo=433028].)

Match object groups can be accessed by __getitem__, which is equivalent to group(). So mo['name'] is now equivalent to mo.group('name'). (Contributed by Eric Smith in bpo-24454 [https://bugs.python.org/issue?@action=redirect&bpo=24454].)

Match objects now support index-like objects as group indices. (Contributed by Jeroen Demeyer and Xiang Zhang in bpo-27177 [https://bugs.python.org/issue?@action=redirect&bpo=27177].)

readline

Added set_auto_history() to enable or disable automatic addition of input to the history list. (Contributed by Tyler Crompton in bpo-26870 [https://bugs.python.org/issue?@action=redirect&bpo=26870].)

rlcompleter

Private and special attribute names now are omitted unless the prefix starts with underscores. A space or a colon is added after some completed keywords. (Contributed by Serhiy Storchaka in bpo-25011 [https://bugs.python.org/issue?@action=redirect&bpo=25011] and bpo-25209 [https://bugs.python.org/issue?@action=redirect&bpo=25209].)

shlex

The shlex has much improved shell compatibility through the new punctuation_chars argument to control which characters are treated as punctuation. (Contributed by Vinay Sajip in bpo-1521950 [https://bugs.python.org/issue?@action=redirect&bpo=1521950].)

site

When specifying paths to add to sys.path in a .pth file, you may now specify file paths on top of directories (e.g. zip files). (Contributed by Wolfgang Langner in bpo-26587 [https://bugs.python.org/issue?@action=redirect&bpo=26587]).

sqlite3

sqlite3.Cursor.lastrowid now supports the REPLACE statement. (Contributed by Alex LordThorsen in bpo-16864 [https://bugs.python.org/issue?@action=redirect&bpo=16864].)

socket

The ioctl() function now supports the SIO_LOOPBACK_FAST_PATH control code. (Contributed by Daniel Stokes in bpo-26536 [https://bugs.python.org/issue?@action=redirect&bpo=26536].)

The getsockopt() constants SO_DOMAIN, SO_PROTOCOL, SO_PEERSEC, and SO_PASSSEC are now supported. (Contributed by Christian Heimes in bpo-26907 [https://bugs.python.org/issue?@action=redirect&bpo=26907].)

The setsockopt() now supports the setsockopt(level, optname, None, optlen: int) form. (Contributed by Christian Heimes in bpo-27744 [https://bugs.python.org/issue?@action=redirect&bpo=27744].)

The socket module now supports the address family AF_ALG to interface with Linux Kernel crypto API. ALG_*, SOL_ALG and sendmsg_afalg() were added. (Contributed by Christian Heimes in bpo-27744 [https://bugs.python.org/issue?@action=redirect&bpo=27744] with support from Victor Stinner.)

New Linux constants TCP_USER_TIMEOUT and TCP_CONGESTION were added. (Contributed by Omar Sandoval, issue:26273).

socketserver

Servers based on the socketserver module, including those defined in http.server, xmlrpc.server and wsgiref.simple_server, now support the context manager protocol. (Contributed by Aviv Palivoda in bpo-26404 [https://bugs.python.org/issue?@action=redirect&bpo=26404].)

The wfile attribute of StreamRequestHandler classes now implements the io.BufferedIOBase writable interface. In particular, calling write() is now guaranteed to send the data in full. (Contributed by Martin Panter in bpo-26721 [https://bugs.python.org/issue?@action=redirect&bpo=26721].)

ssl

ssl supports OpenSSL 1.1.0. The minimum recommend version is 1.0.2. (Contributed by Christian Heimes in bpo-26470 [https://bugs.python.org/issue?@action=redirect&bpo=26470].)

3DES has been removed from the default cipher suites and ChaCha20 Poly1305 cipher suites have been added. (Contributed by Christian Heimes in bpo-27850 [https://bugs.python.org/issue?@action=redirect&bpo=27850] and bpo-27766 [https://bugs.python.org/issue?@action=redirect&bpo=27766].)

SSLContext has better default configuration for options and ciphers. (Contributed by Christian Heimes in bpo-28043 [https://bugs.python.org/issue?@action=redirect&bpo=28043].)

SSL session can be copied from one client-side connection to another with the new SSLSession class. TLS session resumption can speed up the initial handshake, reduce latency and improve performance (Contributed by Christian Heimes in bpo-19500 [https://bugs.python.org/issue?@action=redirect&bpo=19500] based on a draft by Alex Warhawk.)

The new get_ciphers() method can be used to get a list of enabled ciphers in order of cipher priority.

All constants and flags have been converted to IntEnum and IntFlags. (Contributed by Christian Heimes in bpo-28025 [https://bugs.python.org/issue?@action=redirect&bpo=28025].)

Server and client-side specific TLS protocols for SSLContext were added. (Contributed by Christian Heimes in bpo-28085 [https://bugs.python.org/issue?@action=redirect&bpo=28085].)

statistics

A new harmonic_mean() function has been added. (Contributed by Steven D’Aprano in bpo-27181 [https://bugs.python.org/issue?@action=redirect&bpo=27181].)

struct

struct now supports IEEE 754 half-precision floats via the 'e' format specifier. (Contributed by Eli Stevens, Mark Dickinson in bpo-11734 [https://bugs.python.org/issue?@action=redirect&bpo=11734].)

subprocess

subprocess.Popen destructor now emits a ResourceWarning warning if the child process is still running. Use the context manager protocol (with proc: ...) or explicitly call the wait() method to read the exit status of the child process. (Contributed by Victor Stinner in bpo-26741 [https://bugs.python.org/issue?@action=redirect&bpo=26741].)

The subprocess.Popen constructor and all functions that pass arguments through to it now accept encoding and errors arguments. Specifying either of these will enable text mode for the stdin, stdout and stderr streams. (Contributed by Steve Dower in bpo-6135 [https://bugs.python.org/issue?@action=redirect&bpo=6135].)

sys

The new getfilesystemencodeerrors() function returns the name of the error mode used to convert between Unicode filenames and bytes filenames. (Contributed by Steve Dower in bpo-27781 [https://bugs.python.org/issue?@action=redirect&bpo=27781].)

On Windows the return value of the getwindowsversion() function now includes the platform_version field which contains the accurate major version, minor version and build number of the current operating system, rather than the version that is being emulated for the process (Contributed by Steve Dower in bpo-27932 [https://bugs.python.org/issue?@action=redirect&bpo=27932].)

telnetlib

Telnet is now a context manager (contributed by Stéphane Wirtel in bpo-25485 [https://bugs.python.org/issue?@action=redirect&bpo=25485]).

time

The struct_time attributes tm_gmtoff and tm_zone are now available on all platforms.

timeit

The new Timer.autorange() convenience method has been added to call Timer.timeit() repeatedly so that the total run time is greater or equal to 200 milliseconds. (Contributed by Steven D’Aprano in bpo-6422 [https://bugs.python.org/issue?@action=redirect&bpo=6422].)

timeit now warns when there is substantial (4x) variance between best and worst times. (Contributed by Serhiy Storchaka in bpo-23552 [https://bugs.python.org/issue?@action=redirect&bpo=23552].)

tkinter

Added methods trace_add(), trace_remove() and trace_info() in the tkinter.Variable class. They replace old methods trace_variable(), trace(), trace_vdelete() and trace_vinfo() that use obsolete Tcl commands and might not work in future versions of Tcl. (Contributed by Serhiy Storchaka in bpo-22115 [https://bugs.python.org/issue?@action=redirect&bpo=22115]).

traceback

Both the traceback module and the interpreter’s builtin exception display now abbreviate long sequences of repeated lines in tracebacks as shown in the following example:

>>> def f(): f()
...
>>> f()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 1, in f
  File "<stdin>", line 1, in f
  File "<stdin>", line 1, in f
  [Previous line repeated 995 more times]
RecursionError: maximum recursion depth exceeded

(Contributed by Emanuel Barry in bpo-26823 [https://bugs.python.org/issue?@action=redirect&bpo=26823].)

tracemalloc

The tracemalloc module now supports tracing memory allocations in multiple different address spaces.

The new DomainFilter filter class has been added to filter block traces by their address space (domain).

(Contributed by Victor Stinner in bpo-26588 [https://bugs.python.org/issue?@action=redirect&bpo=26588].)

typing

Since the typing module is provisional, all changes introduced in Python 3.6 have also been backported to Python 3.5.x.

The typing module has a much improved support for generic type aliases. For example Dict[str, Tuple[S, T]] is now a valid type annotation. (Contributed by Guido van Rossum in Github #195 [https://github.com/python/typing/pull/195].)

The typing.ContextManager class has been added for representing contextlib.AbstractContextManager. (Contributed by Brett Cannon in bpo-25609 [https://bugs.python.org/issue?@action=redirect&bpo=25609].)

The typing.Collection class has been added for representing collections.abc.Collection. (Contributed by Ivan Levkivskyi in bpo-27598 [https://bugs.python.org/issue?@action=redirect&bpo=27598].)

The typing.ClassVar type construct has been added to mark class variables. As introduced in PEP 526 [https://www.python.org/dev/peps/pep-0526], a variable annotation wrapped in ClassVar indicates that a given attribute is intended to be used as a class variable and should not be set on instances of that class. (Contributed by Ivan Levkivskyi in Github #280 [https://github.com/python/typing/pull/280].)

A new TYPE_CHECKING constant that is assumed to be True by the static type checkers, but is False at runtime. (Contributed by Guido van Rossum in Github #230 [https://github.com/python/typing/issues/230].)

A new NewType() helper function has been added to create lightweight distinct types for annotations:

from typing import NewType

UserId = NewType('UserId', int)
some_id = UserId(524313)

The static type checker will treat the new type as if it were a subclass of the original type. (Contributed by Ivan Levkivskyi in Github #189 [https://github.com/python/typing/issues/189].)

unicodedata

The unicodedata module now uses data from Unicode 9.0.0 [http://unicode.org/versions/Unicode9.0.0/]. (Contributed by Benjamin Peterson.)

unittest.mock

The Mock class has the following improvements:

Two new methods, Mock.assert_called() and Mock.assert_called_once() to check if the mock object was called. (Contributed by Amit Saha in bpo-26323 [https://bugs.python.org/issue?@action=redirect&bpo=26323].)

The Mock.reset_mock() method now has two optional keyword only arguments: return_value and side_effect. (Contributed by Kushal Das in bpo-21271 [https://bugs.python.org/issue?@action=redirect&bpo=21271].)

urllib.request

If a HTTP request has a file or iterable body (other than a bytes object) but no Content-Length header, rather than throwing an error, AbstractHTTPHandler now falls back to use chunked transfer encoding. (Contributed by Demian Brecht and Rolf Krahl in bpo-12319 [https://bugs.python.org/issue?@action=redirect&bpo=12319].)

urllib.robotparser

RobotFileParser now supports the Crawl-delay and Request-rate extensions. (Contributed by Nikolay Bogoychev in bpo-16099 [https://bugs.python.org/issue?@action=redirect&bpo=16099].)

venv

venv accepts a new parameter --prompt. This parameter provides an alternative prefix for the virtual environment. (Proposed by Łukasz Balcerzak and ported to 3.6 by Stéphane Wirtel in bpo-22829 [https://bugs.python.org/issue?@action=redirect&bpo=22829].)

warnings

A new optional source parameter has been added to the warnings.warn_explicit() function: the destroyed object which emitted a ResourceWarning. A source attribute has also been added to warnings.WarningMessage (contributed by Victor Stinner in bpo-26568 [https://bugs.python.org/issue?@action=redirect&bpo=26568] and bpo-26567 [https://bugs.python.org/issue?@action=redirect&bpo=26567]).

When a ResourceWarning warning is logged, the tracemalloc module is now used to try to retrieve the traceback where the destroyed object was allocated.

Example with the script example.py:

import warnings

def func():
    return open(__file__)

f = func()
f = None

Output of the command python3.6 -Wd -X tracemalloc=5 example.py:

example.py:7: ResourceWarning: unclosed file <_io.TextIOWrapper name='example.py' mode='r' encoding='UTF-8'>
  f = None
Object allocated at (most recent call first):
  File "example.py", lineno 4
    return open(__file__)
  File "example.py", lineno 6
    f = func()

The «Object allocated at» traceback is new and is only displayed if tracemalloc is tracing Python memory allocations and if the warnings module was already imported.

winreg

Added the 64-bit integer type REG_QWORD. (Contributed by Clement Rouault in bpo-23026 [https://bugs.python.org/issue?@action=redirect&bpo=23026].)

winsound

Allowed keyword arguments to be passed to Beep, MessageBeep, and PlaySound (bpo-27982 [https://bugs.python.org/issue?@action=redirect&bpo=27982]).

xmlrpc.client

The xmlrpc.client module now supports unmarshalling additional data types used by the Apache XML-RPC implementation for numerics and None. (Contributed by Serhiy Storchaka in bpo-26885 [https://bugs.python.org/issue?@action=redirect&bpo=26885].)

zipfile

A new ZipInfo.from_file() class method allows making a ZipInfo instance from a filesystem file. A new ZipInfo.is_dir() method can be used to check if the ZipInfo instance represents a directory. (Contributed by Thomas Kluyver in bpo-26039 [https://bugs.python.org/issue?@action=redirect&bpo=26039].)

The ZipFile.open() method can now be used to write data into a ZIP file, as well as for extracting data. (Contributed by Thomas Kluyver in bpo-26039 [https://bugs.python.org/issue?@action=redirect&bpo=26039].)

zlib

The compress() and decompress() functions now accept keyword arguments. (Contributed by Aviv Palivoda in bpo-26243 [https://bugs.python.org/issue?@action=redirect&bpo=26243] and Xiang Zhang in bpo-16764 [https://bugs.python.org/issue?@action=redirect&bpo=16764] respectively.)

Optimizations

The Python interpreter now uses a 16-bit wordcode instead of bytecode which made a number of opcode optimizations possible. (Contributed by Demur Rumed with input and reviews from Serhiy Storchaka and Victor Stinner in bpo-26647 [https://bugs.python.org/issue?@action=redirect&bpo=26647] and bpo-28050 [https://bugs.python.org/issue?@action=redirect&bpo=28050].)

The asyncio.Future class now has an optimized C implementation. (Contributed by Yury Selivanov and INADA Naoki in bpo-26081 [https://bugs.python.org/issue?@action=redirect&bpo=26081].)

The asyncio.Task class now has an optimized C implementation. (Contributed by Yury Selivanov in bpo-28544 [https://bugs.python.org/issue?@action=redirect&bpo=28544].)

Various implementation improvements in the typing module (such as caching of generic types) allow up to 30 times performance improvements and reduced memory footprint.

The ASCII decoder is now up to 60 times as fast for error handlers surrogateescape, ignore and replace (Contributed by Victor Stinner in bpo-24870 [https://bugs.python.org/issue?@action=redirect&bpo=24870]).

The ASCII and the Latin1 encoders are now up to 3 times as fast for the error handler surrogateescape (Contributed by Victor Stinner in bpo-25227 [https://bugs.python.org/issue?@action=redirect&bpo=25227]).

The UTF-8 encoder is now up to 75 times as fast for error handlers ignore, replace, surrogateescape, surrogatepass (Contributed by Victor Stinner in bpo-25267 [https://bugs.python.org/issue?@action=redirect&bpo=25267]).

The UTF-8 decoder is now up to 15 times as fast for error handlers ignore, replace and surrogateescape (Contributed by Victor Stinner in bpo-25301 [https://bugs.python.org/issue?@action=redirect&bpo=25301]).

bytes % args is now up to 2 times faster. (Contributed by Victor Stinner in bpo-25349 [https://bugs.python.org/issue?@action=redirect&bpo=25349]).

bytearray % args is now between 2.5 and 5 times faster. (Contributed by Victor Stinner in bpo-25399 [https://bugs.python.org/issue?@action=redirect&bpo=25399]).

Optimize bytes.fromhex() and bytearray.fromhex(): they are now between 2x and 3.5x faster. (Contributed by Victor Stinner in bpo-25401 [https://bugs.python.org/issue?@action=redirect&bpo=25401]).

Optimize bytes.replace(b'', b'.') and bytearray.replace(b'', b'.'): up to 80% faster. (Contributed by Josh Snider in bpo-26574 [https://bugs.python.org/issue?@action=redirect&bpo=26574]).

Allocator functions of the PyMem_Malloc() domain (PYMEM_DOMAIN_MEM) now use the pymalloc memory allocator instead of malloc() function of the C library. The pymalloc allocator is optimized for objects smaller or equal to 512 bytes with a short lifetime, and use malloc() for larger memory blocks. (Contributed by Victor Stinner in bpo-26249 [https://bugs.python.org/issue?@action=redirect&bpo=26249]).

pickle.load() and pickle.loads() are now up to 10% faster when deserializing many small objects (Contributed by Victor Stinner in bpo-27056 [https://bugs.python.org/issue?@action=redirect&bpo=27056]).

Passing keyword arguments to a function has an overhead in comparison with passing positional arguments. Now in extension functions implemented with using Argument Clinic this overhead is significantly decreased. (Contributed by Serhiy Storchaka in bpo-27574 [https://bugs.python.org/issue?@action=redirect&bpo=27574]).

Optimized glob() and iglob() functions in the glob module; they are now about 3–6 times faster. (Contributed by Serhiy Storchaka in bpo-25596 [https://bugs.python.org/issue?@action=redirect&bpo=25596]).

Optimized globbing in pathlib by using os.scandir(); it is now about 1.5–4 times faster. (Contributed by Serhiy Storchaka in bpo-26032 [https://bugs.python.org/issue?@action=redirect&bpo=26032]).

xml.etree.ElementTree parsing, iteration and deepcopy performance has been significantly improved. (Contributed by Serhiy Storchaka in bpo-25638 [https://bugs.python.org/issue?@action=redirect&bpo=25638], bpo-25873 [https://bugs.python.org/issue?@action=redirect&bpo=25873], and bpo-25869 [https://bugs.python.org/issue?@action=redirect&bpo=25869].)

Creation of fractions.Fraction instances from floats and decimals is now 2 to 3 times faster. (Contributed by Serhiy Storchaka in bpo-25971 [https://bugs.python.org/issue?@action=redirect&bpo=25971].)

Build and C API Changes

Python now requires some C99 support in the toolchain to build. Most notably, Python now uses standard integer types and macros in place of custom macros like PY_LONG_LONG. For more information, see PEP 7 [https://www.python.org/dev/peps/pep-0007] and bpo-17884 [https://bugs.python.org/issue?@action=redirect&bpo=17884].

Cross-compiling CPython with the Android NDK and the Android API level set to 21 (Android 5.0 Lollipop) or greater runs successfully. While Android is not yet a supported platform, the Python test suite runs on the Android emulator with only about 16 tests failures. See the Android meta-issue bpo-26865 [https://bugs.python.org/issue?@action=redirect&bpo=26865].

The --enable-optimizations configure flag has been added. Turning it on will activate expensive optimizations like PGO. (Original patch by Alecsandru Patrascu of Intel in bpo-26359 [https://bugs.python.org/issue?@action=redirect&bpo=26359].)

The GIL must now be held when allocator functions of PYMEM_DOMAIN_OBJ (ex: PyObject_Malloc()) and PYMEM_DOMAIN_MEM (ex: PyMem_Malloc()) domains are called.

New Py_FinalizeEx() API which indicates if flushing buffered data failed. (Contributed by Martin Panter in bpo-5319 [https://bugs.python.org/issue?@action=redirect&bpo=5319].)

PyArg_ParseTupleAndKeywords() now supports positional-only parameters. Positional-only parameters are defined by empty names. (Contributed by Serhiy Storchaka in bpo-26282 [https://bugs.python.org/issue?@action=redirect&bpo=26282]).

PyTraceback_Print method now abbreviates long sequences of repeated lines as "[Previous line repeated {count} more times]". (Contributed by Emanuel Barry in bpo-26823 [https://bugs.python.org/issue?@action=redirect&bpo=26823].)

The new PyErr_SetImportErrorSubclass() function allows for specifying a subclass of ImportError to raise. (Contributed by Eric Snow in bpo-15767 [https://bugs.python.org/issue?@action=redirect&bpo=15767].)

The new PyErr_ResourceWarning() function can be used to generate a ResourceWarning providing the source of the resource allocation. (Contributed by Victor Stinner in bpo-26567 [https://bugs.python.org/issue?@action=redirect&bpo=26567].)

The new PyOS_FSPath() function returns the file system representation of a path-like object. (Contributed by Brett Cannon in bpo-27186 [https://bugs.python.org/issue?@action=redirect&bpo=27186].)

The PyUnicode_FSConverter() and PyUnicode_FSDecoder() functions will now accept path-like objects.

Other Improvements

When --version (short form: -V) is supplied twice, Python prints sys.version for detailed information.

$ ./python -VV
Python 3.6.0b4+ (3.6:223967b49e49+, Nov 21 2016, 20:55:04)
[GCC 4.2.1 Compatible Apple LLVM 8.0.0 (clang-800.0.42.1)]

Deprecated

New Keywords

async and await are not recommended to be used as variable, class, function or module names. Introduced by PEP 492 [https://www.python.org/dev/peps/pep-0492] in Python 3.5, they will become proper keywords in Python 3.7. Starting in Python 3.6, the use of async or await as names will generate a DeprecationWarning.

Deprecated Python behavior

Raising the StopIteration exception inside a generator will now generate a DeprecationWarning, and will trigger a RuntimeError in Python 3.7. See PEP 479: Cambiar el gestor de StopIteration dentro de generadores for details.

The __aiter__() method is now expected to return an asynchronous iterator directly instead of returning an awaitable as previously. Doing the former will trigger a DeprecationWarning. Backward compatibility will be removed in Python 3.7. (Contributed by Yury Selivanov in bpo-27243 [https://bugs.python.org/issue?@action=redirect&bpo=27243].)

A backslash-character pair that is not a valid escape sequence now generates a DeprecationWarning. Although this will eventually become a SyntaxError, that will not be for several Python releases. (Contributed by Emanuel Barry in bpo-27364 [https://bugs.python.org/issue?@action=redirect&bpo=27364].)

When performing a relative import, falling back on __name__ and __path__ from the calling module when __spec__ or __package__ are not defined now raises an ImportWarning. (Contributed by Rose Ames in bpo-25791 [https://bugs.python.org/issue?@action=redirect&bpo=25791].)

Deprecated Python modules, functions and methods

asynchat

The asynchat has been deprecated in favor of asyncio. (Contributed by Mariatta in bpo-25002 [https://bugs.python.org/issue?@action=redirect&bpo=25002].)

asyncore

The asyncore has been deprecated in favor of asyncio. (Contributed by Mariatta in bpo-25002 [https://bugs.python.org/issue?@action=redirect&bpo=25002].)

dbm

Unlike other dbm implementations, the dbm.dumb module creates databases with the 'rw' mode and allows modifying the database opened with the 'r' mode. This behavior is now deprecated and will be removed in 3.8. (Contributed by Serhiy Storchaka in bpo-21708 [https://bugs.python.org/issue?@action=redirect&bpo=21708].)

distutils

The undocumented extra_path argument to the Distribution constructor is now considered deprecated and will raise a warning if set. Support for this parameter will be removed in a future Python release. See bpo-27919 [https://bugs.python.org/issue?@action=redirect&bpo=27919] for details.

grp

The support of non-integer arguments in getgrgid() has been deprecated. (Contributed by Serhiy Storchaka in bpo-26129 [https://bugs.python.org/issue?@action=redirect&bpo=26129].)

importlib

The importlib.machinery.SourceFileLoader.load_module() and importlib.machinery.SourcelessFileLoader.load_module() methods are now deprecated. They were the only remaining implementations of importlib.abc.Loader.load_module() in importlib that had not been deprecated in previous versions of Python in favour of importlib.abc.Loader.exec_module().

The importlib.machinery.WindowsRegistryFinder class is now deprecated. As of 3.6.0, it is still added to sys.meta_path by default (on Windows), but this may change in future releases.

os

Undocumented support of general bytes-like objects as paths in os functions, compile() and similar functions is now deprecated. (Contributed by Serhiy Storchaka in bpo-25791 [https://bugs.python.org/issue?@action=redirect&bpo=25791] and bpo-26754 [https://bugs.python.org/issue?@action=redirect&bpo=26754].)

re

Support for inline flags (?letters) in the middle of the regular expression has been deprecated and will be removed in a future Python version. Flags at the start of a regular expression are still allowed. (Contributed by Serhiy Storchaka in bpo-22493 [https://bugs.python.org/issue?@action=redirect&bpo=22493].)

ssl

OpenSSL 0.9.8, 1.0.0 and 1.0.1 are deprecated and no longer supported. In the future the ssl module will require at least OpenSSL 1.0.2 or 1.1.0.

SSL-related arguments like certfile, keyfile and check_hostname in ftplib, http.client, imaplib, poplib, and smtplib have been deprecated in favor of context. (Contributed by Christian Heimes in bpo-28022 [https://bugs.python.org/issue?@action=redirect&bpo=28022].)

A couple of protocols and functions of the ssl module are now deprecated. Some features will no longer be available in future versions of OpenSSL. Other features are deprecated in favor of a different API. (Contributed by Christian Heimes in bpo-28022 [https://bugs.python.org/issue?@action=redirect&bpo=28022] and bpo-26470 [https://bugs.python.org/issue?@action=redirect&bpo=26470].)

tkinter

The tkinter.tix module is now deprecated. tkinter users should use tkinter.ttk instead.

venv

The pyvenv script has been deprecated in favour of python3 -m venv. This prevents confusion as to what Python interpreter pyvenv is connected to and thus what Python interpreter will be used by the virtual environment. (Contributed by Brett Cannon in bpo-25154 [https://bugs.python.org/issue?@action=redirect&bpo=25154].)

Deprecated functions and types of the C API

Undocumented functions PyUnicode_AsEncodedObject(), PyUnicode_AsDecodedObject(), PyUnicode_AsEncodedUnicode() and PyUnicode_AsDecodedUnicode() are deprecated now. Use the generic codec based API instead.

Deprecated Build Options

The --with-system-ffi configure flag is now on by default on non-macOS UNIX platforms. It may be disabled by using --without-system-ffi, but using the flag is deprecated and will not be accepted in Python 3.7. macOS is unaffected by this change. Note that many OS distributors already use the --with-system-ffi flag when building their system Python.

Removed

API and Feature Removals

Unknown escapes consisting of '\' and an ASCII letter in regular expressions will now cause an error. In replacement templates for re.sub() they are still allowed, but deprecated. The re.LOCALE flag can now only be used with binary patterns.

inspect.getmoduleinfo() was removed (was deprecated since CPython 3.3). inspect.getmodulename() should be used for obtaining the module name for a given path. (Contributed by Yury Selivanov in bpo-13248 [https://bugs.python.org/issue?@action=redirect&bpo=13248].)

traceback.Ignore class and traceback.usage, traceback.modname, traceback.fullmodname, traceback.find_lines_from_code, traceback.find_lines, traceback.find_strings, traceback.find_executable_lines methods were removed from the traceback module. They were undocumented methods deprecated since Python 3.2 and equivalent functionality is available from private methods.

The tk_menuBar() and tk_bindForTraversal() dummy methods in tkinter widget classes were removed (corresponding Tk commands were obsolete since Tk 4.0).

The open() method of the zipfile.ZipFile class no longer supports the 'U' mode (was deprecated since Python 3.4). Use io.TextIOWrapper for reading compressed text files in universal newlines mode.

The undocumented IN, CDROM, DLFCN, TYPES, CDIO, and STROPTS modules have been removed. They had been available in the platform specific Lib/plat-*/ directories, but were chronically out of date, inconsistently available across platforms, and unmaintained. The script that created these modules is still available in the source distribution at Tools/scripts/h2py.py [https://github.com/python/cpython/tree/3.9/Tools/scripts/h2py.py].

The deprecated asynchat.fifo class has been removed.

Porting to Python 3.6

This section lists previously described changes and other bugfixes that may require changes to your code.

Changes in “python” Command Behavior

The output of a special Python build with defined COUNT_ALLOCS, SHOW_ALLOC_COUNT or SHOW_TRACK_COUNT macros is now off by default. It can be re-enabled using the -X showalloccount option. It now outputs to stderr instead of stdout. (Contributed by Serhiy Storchaka in bpo-23034 [https://bugs.python.org/issue?@action=redirect&bpo=23034].)

Changes in the Python API

open() will no longer allow combining the 'U' mode flag with '+'. (Contributed by Jeff Balogh and John O’Connor in bpo-2091 [https://bugs.python.org/issue?@action=redirect&bpo=2091].)

sqlite3 no longer implicitly commits an open transaction before DDL statements.

On Linux, os.urandom() now blocks until the system urandom entropy pool is initialized to increase the security.

When importlib.abc.Loader.exec_module() is defined, importlib.abc.Loader.create_module() must also be defined.

PyErr_SetImportError() now sets TypeError when its msg argument is not set. Previously only NULL was returned.

The format of the co_lnotab attribute of code objects changed to support a negative line number delta. By default, Python does not emit bytecode with a negative line number delta. Functions using frame.f_lineno, PyFrame_GetLineNumber() or PyCode_Addr2Line() are not affected. Functions directly decoding co_lnotab should be updated to use a signed 8-bit integer type for the line number delta, but this is only required to support applications using a negative line number delta. See Objects/lnotab_notes.txt for the co_lnotab format and how to decode it, and see the PEP 511 [https://www.python.org/dev/peps/pep-0511] for the rationale.

The functions in the compileall module now return booleans instead of 1 or 0 to represent success or failure, respectively. Thanks to booleans being a subclass of integers, this should only be an issue if you were doing identity checks for 1 or 0. See bpo-25768 [https://bugs.python.org/issue?@action=redirect&bpo=25768].

Reading the port attribute of urllib.parse.urlsplit() and urlparse() results now raises ValueError for out-of-range values, rather than returning None. See bpo-20059 [https://bugs.python.org/issue?@action=redirect&bpo=20059].

The imp module now raises a DeprecationWarning instead of PendingDeprecationWarning.

The following modules have had missing APIs added to their __all__ attributes to match the documented APIs: calendar, cgi, csv, ElementTree, enum, fileinput, ftplib, logging, mailbox, mimetypes, optparse, plistlib, smtpd, subprocess, tarfile, threading and wave. This means they will export new symbols when import * is used. (Contributed by Joel Taddei and Jacek Kołodziej in bpo-23883 [https://bugs.python.org/issue?@action=redirect&bpo=23883].)

When performing a relative import, if __package__ does not compare equal to __spec__.parent then ImportWarning is raised. (Contributed by Brett Cannon in bpo-25791 [https://bugs.python.org/issue?@action=redirect&bpo=25791].)

When a relative import is performed and no parent package is known, then ImportError will be raised. Previously, SystemError could be raised. (Contributed by Brett Cannon in bpo-18018 [https://bugs.python.org/issue?@action=redirect&bpo=18018].)

Servers based on the socketserver module, including those defined in http.server, xmlrpc.server and wsgiref.simple_server, now only catch exceptions derived from Exception. Therefore if a request handler raises an exception like SystemExit or KeyboardInterrupt, handle_error() is no longer called, and the exception will stop a single-threaded server. (Contributed by Martin Panter in bpo-23430 [https://bugs.python.org/issue?@action=redirect&bpo=23430].)

spwd.getspnam() now raises a PermissionError instead of KeyError if the user doesn’t have privileges.

The socket.socket.close() method now raises an exception if an error (e.g. EBADF) was reported by the underlying system call. (Contributed by Martin Panter in bpo-26685 [https://bugs.python.org/issue?@action=redirect&bpo=26685].)

The decode_data argument for the smtpd.SMTPChannel and smtpd.SMTPServer constructors is now False by default. This means that the argument passed to process_message() is now a bytes object by default, and process_message() will be passed keyword arguments. Code that has already been updated in accordance with the deprecation warning generated by 3.5 will not be affected.

All optional arguments of the dump(), dumps(), load() and loads() functions and JSONEncoder and JSONDecoder class constructors in the json module are now keyword-only. (Contributed by Serhiy Storchaka in bpo-18726 [https://bugs.python.org/issue?@action=redirect&bpo=18726].)

Subclasses of type which don’t override type.__new__ may no longer use the one-argument form to get the type of an object.

As part of PEP 487 [https://www.python.org/dev/peps/pep-0487], the handling of keyword arguments passed to type (other than the metaclass hint, metaclass) is now consistently delegated to object.__init_subclass__(). This means that type.__new__() and type.__init__() both now accept arbitrary keyword arguments, but object.__init_subclass__() (which is called from type.__new__()) will reject them by default. Custom metaclasses accepting additional keyword arguments will need to adjust their calls to type.__new__() (whether direct or via super) accordingly.

In distutils.command.sdist.sdist, the default_format attribute has been removed and is no longer honored. Instead, the gzipped tarfile format is the default on all platforms and no platform-specific selection is made. In environments where distributions are built on Windows and zip distributions are required, configure the project with a setup.cfg file containing the following:

[sdist]
formats=zip

This behavior has also been backported to earlier Python versions by Setuptools 26.0.0.

In the urllib.request module and the http.client.HTTPConnection.request() method, if no Content-Length header field has been specified and the request body is a file object, it is now sent with HTTP 1.1 chunked encoding. If a file object has to be sent to a HTTP 1.0 server, the Content-Length value now has to be specified by the caller. (Contributed by Demian Brecht and Rolf Krahl with tweaks from Martin Panter in bpo-12319 [https://bugs.python.org/issue?@action=redirect&bpo=12319].)

The DictReader now returns rows of type OrderedDict. (Contributed by Steve Holden in bpo-27842 [https://bugs.python.org/issue?@action=redirect&bpo=27842].)

The crypt.METHOD_CRYPT will no longer be added to crypt.methods if unsupported by the platform. (Contributed by Victor Stinner in bpo-25287 [https://bugs.python.org/issue?@action=redirect&bpo=25287].)

The verbose and rename arguments for namedtuple() are now keyword-only. (Contributed by Raymond Hettinger in bpo-25628 [https://bugs.python.org/issue?@action=redirect&bpo=25628].)

On Linux, ctypes.util.find_library() now looks in LD_LIBRARY_PATH for shared libraries. (Contributed by Vinay Sajip in bpo-9998 [https://bugs.python.org/issue?@action=redirect&bpo=9998].)

The imaplib.IMAP4 class now handles flags containing the ']' character in messages sent from the server to improve real-world compatibility. (Contributed by Lita Cho in bpo-21815 [https://bugs.python.org/issue?@action=redirect&bpo=21815].)

The mmap.write() function now returns the number of bytes written like other write methods. (Contributed by Jakub Stasiak in bpo-26335 [https://bugs.python.org/issue?@action=redirect&bpo=26335].)

The pkgutil.iter_modules() and pkgutil.walk_packages() functions now return ModuleInfo named tuples. (Contributed by Ramchandra Apte in bpo-17211 [https://bugs.python.org/issue?@action=redirect&bpo=17211].)

re.sub() now raises an error for invalid numerical group references in replacement templates even if the pattern is not found in the string. The error message for invalid group references now includes the group index and the position of the reference. (Contributed by SilentGhost, Serhiy Storchaka in bpo-25953 [https://bugs.python.org/issue?@action=redirect&bpo=25953].)

zipfile.ZipFile will now raise NotImplementedError for unrecognized compression values. Previously a plain RuntimeError was raised. Additionally, calling ZipFile methods on a closed ZipFile or calling the write() method on a ZipFile created with mode 'r' will raise a ValueError. Previously, a RuntimeError was raised in those scenarios.

when custom metaclasses are combined with zero-argument super() or direct references from methods to the implicit __class__ closure variable, the implicit __classcell__ namespace entry must now be passed up to type.__new__ for initialisation. Failing to do so will result in a DeprecationWarning in Python 3.6 and a RuntimeError in Python 3.8.

With the introduction of ModuleNotFoundError, import system consumers may start expecting import system replacements to raise that more specific exception when appropriate, rather than the less-specific ImportError. To provide future compatibility with such consumers, implementors of alternative import systems that completely replace __import__() will need to update their implementations to raise the new subclass when a module can’t be found at all. Implementors of compliant plugins to the default import system shouldn’t need to make any changes, as the default import system will raise the new subclass when appropriate.

Changes in the C API

The PyMem_Malloc() allocator family now uses the pymalloc allocator rather than the system malloc(). Applications calling PyMem_Malloc() without holding the GIL can now crash. Set the PYTHONMALLOC environment variable to debug to validate the usage of memory allocators in your application. See bpo-26249 [https://bugs.python.org/issue?@action=redirect&bpo=26249].

Py_Exit() (and the main interpreter) now override the exit status with 120 if flushing buffered data failed. See bpo-5319 [https://bugs.python.org/issue?@action=redirect&bpo=5319].

CPython bytecode changes

There have been several major changes to the bytecode in Python 3.6.

The Python interpreter now uses a 16-bit wordcode instead of bytecode. (Contributed by Demur Rumed with input and reviews from Serhiy Storchaka and Victor Stinner in bpo-26647 [https://bugs.python.org/issue?@action=redirect&bpo=26647] and bpo-28050 [https://bugs.python.org/issue?@action=redirect&bpo=28050].)

The new FORMAT_VALUE and BUILD_STRING opcodes as part of the formatted string literal implementation. (Contributed by Eric Smith in bpo-25483 [https://bugs.python.org/issue?@action=redirect&bpo=25483] and Serhiy Storchaka in bpo-27078 [https://bugs.python.org/issue?@action=redirect&bpo=27078].)

The new BUILD_CONST_KEY_MAP opcode to optimize the creation of dictionaries with constant keys. (Contributed by Serhiy Storchaka in bpo-27140 [https://bugs.python.org/issue?@action=redirect&bpo=27140].)

The function call opcodes have been heavily reworked for better performance and simpler implementation. The MAKE_FUNCTION, CALL_FUNCTION, CALL_FUNCTION_KW and BUILD_MAP_UNPACK_WITH_CALL opcodes have been modified, the new CALL_FUNCTION_EX and BUILD_TUPLE_UNPACK_WITH_CALL have been added, and CALL_FUNCTION_VAR, CALL_FUNCTION_VAR_KW and MAKE_CLOSURE opcodes have been removed. (Contributed by Demur Rumed in bpo-27095 [https://bugs.python.org/issue?@action=redirect&bpo=27095], and Serhiy Storchaka in bpo-27213 [https://bugs.python.org/issue?@action=redirect&bpo=27213], bpo-28257 [https://bugs.python.org/issue?@action=redirect&bpo=28257].)

The new SETUP_ANNOTATIONS and STORE_ANNOTATION opcodes have been added to support the new variable annotation syntax. (Contributed by Ivan Levkivskyi in bpo-27985 [https://bugs.python.org/issue?@action=redirect&bpo=27985].)

Notable changes in Python 3.6.2

New make regen-all build target

To simplify cross-compilation, and to ensure that CPython can reliably be compiled without requiring an existing version of Python to already be available, the autotools-based build system no longer attempts to implicitly recompile generated files based on file modification times.

Instead, a new make regen-all command has been added to force regeneration of these files when desired (e.g. after an initial version of Python has already been built based on the pregenerated versions).

More selective regeneration targets are also defined - see Makefile.pre.in [https://github.com/python/cpython/tree/3.9/Makefile.pre.in] for details.

(Contributed by Victor Stinner in bpo-23404 [https://bugs.python.org/issue?@action=redirect&bpo=23404].)

Nuevo en la versión 3.6.2.

Removal of make touch build target

The make touch build target previously used to request implicit regeneration of generated files by updating their modification times has been removed.

It has been replaced by the new make regen-all target.

(Contributed by Victor Stinner in bpo-23404 [https://bugs.python.org/issue?@action=redirect&bpo=23404].)

Distinto en la versión 3.6.2.

Notable changes in Python 3.6.4

The PyExc_RecursionErrorInst singleton that was part of the public API has been removed as its members being never cleared may cause a segfault during finalization of the interpreter. (Contributed by Xavier de Gaye in bpo-22898 [https://bugs.python.org/issue?@action=redirect&bpo=22898] and bpo-30697 [https://bugs.python.org/issue?@action=redirect&bpo=30697].)

Notable changes in Python 3.6.5

The locale.localeconv() function now sets temporarily the LC_CTYPE locale to the LC_NUMERIC locale in some cases. (Contributed by Victor Stinner in bpo-31900 [https://bugs.python.org/issue?@action=redirect&bpo=31900].)

Notable changes in Python 3.6.7

In 3.6.7 the tokenize module now implicitly emits a NEWLINE token when provided with input that does not have a trailing new line. This behavior now matches what the C tokenizer does internally. (Contributed by Ammar Askar in bpo-33899 [https://bugs.python.org/issue?@action=redirect&bpo=33899].)

Notable changes in Python 3.6.10

Due to significant security concerns, the reuse_address parameter of asyncio.loop.create_datagram_endpoint() is no longer supported. This is because of the behavior of the socket option SO_REUSEADDR in UDP. For more details, see the documentation for loop.create_datagram_endpoint(). (Contributed by Kyle Stanley, Antoine Pitrou, and Yury Selivanov in bpo-37228 [https://bugs.python.org/issue?@action=redirect&bpo=37228].)

Notable changes in Python 3.6.13

Earlier Python versions allowed using both ; and & as query parameter separators in urllib.parse.parse_qs() and urllib.parse.parse_qsl(). Due to security concerns, and to conform with newer W3C recommendations, this has been changed to allow only a single separator key, with & as the default. This change also affects cgi.parse() and cgi.parse_multipart() as they use the affected functions internally. For more details, please see their respective documentation. (Contributed by Adam Goldschmidt, Senthil Kumaran and Ken Jin in bpo-42967 [https://bugs.python.org/issue?@action=redirect&bpo=42967].)

Qué hay de nuevo en Python 3.5

Editores

Elvis Pranskevichus <elvis@magic.io>, Yury Selivanov <yury@magic.io>

Este artículo explica las nuevas características de Python 3.5, en comparación con 3.4. Python 3.5 se publicó el 13 de septiembre de 2015. Consultar el registro de cambios [https://docs.python.org/3.5/whatsnew/changelog.html] para una lista completa de cambios.

Ver también

PEP 478 [https://www.python.org/dev/peps/pep-0478] - Python 3.5 Calendario de lanzamiento de Python 3.5

Resumen – Aspectos destacados de la versión

Nuevas características de sintaxis:

PEP 492, corrutinas con sintaxis async y await.

PEP 465, un nuevo operador de multiplicación de matrices: a @ b.

PEP 448, generalizaciones de desembalaje adicionales.

Nuevos módulos:

typing: PEP 484 – Indicador de tipos.

zipapp: PEP 441 Mejora de soporte de la aplicación Python ZIP.

Nuevas características integradas:

bytes % args, bytearray % args: PEP 461 – Agrega formato % a bytes y bytearray.

Nuevos métodos bytes.hex(), bytearray.hex() y memoryview.hex(). (Contribución de Arnon Yaari en bpo-9951 [https://bugs.python.org/issue?@action=redirect&bpo=9951].)

memoryview ahora admite la indexación de tuplas (incluida la multidimensional). (Contribución de Antoine Pitrou en bpo-23632 [https://bugs.python.org/issue?@action=redirect&bpo=23632].)

Los generadores tienen un nuevo atributo gi_yieldfrom, el cual retorna el objeto que está siendo iterado por expresiones yield from. (Contribución de Benno Leslie y Yury Selivanov en bpo-24450 [https://bugs.python.org/issue?@action=redirect&bpo=24450].)

Ahora se genera una nueva excepción RecursionError cuando se alcanza la profundidad máxima de recursividad. (Contribución de Georg Brandl en bpo-19235 [https://bugs.python.org/issue?@action=redirect&bpo=19235].)

Mejoras en la implementación de CPython:

Cuando la configuración regional LC_TYPE es la configuración regional POSIX (configuración regional C), ahora sys.stdin y sys.stdout usan el controlador de errores surrogateescape, en lugar del controlador de errores strict. (Contribución de Victor Stinner en bpo-19977 [https://bugs.python.org/issue?@action=redirect&bpo=19977].)

Los archivos .pyo ya no se utilizan y han sido reemplazados por un esquema más flexible que incluye el nivel de optimización explícitamente en el nombre .pyc. (Consultar la PEP 488 descripción general.)

Ahora los módulos integrados y de extensión son inicializados en un proceso de múltiples fases, que es similar a cómo los módulos de Python son cargados. (Consultar PEP 489 descripción general.)

Mejoras significativas en la biblioteca estándar:

collections.OrderedDict ahora está implementado en C, que lo hace de 4 a 100 veces más rápido.

El módulo ssl adquirió soporte para la memoria BIO, que desacopla el manejo del protocolo SSL de la red de E/S.

La nueva función os.scandir() proporciona una forma mejor y significativamente más rápida de recorrido de directorio.

functools.lru_cache() ha sido principalmente reimplementado en C, produciendo un rendimiento mucho mejor.

La nueva función subprocess.run() proporciona una forma simplificada de ejecutar subprocesos.

El módulo traceback se ha mejorado significativamente para mejorar el rendimiento y la conveniencia del desarrollador.

Mejoras de seguridad:

Ahora SSLv3 está deshabilitado en toda la biblioteca estándar. Aún se puede habilitar creando una instancia de ssl.SSLContext manualmente. (Consultar bpo-22638 [https://bugs.python.org/issue?@action=redirect&bpo=22638] para más detalles; este cambio fue respaldado a CPython 3.4 y 2.7.)

Ahora el análisis de cookies HTTP es más estricto, con el fin de proteger contra posibles ataques de entrada. (Contribución de Antoine Pitrou en bpo-22796 [https://bugs.python.org/issue?@action=redirect&bpo=22796].)

Mejoras de Windows:

Un nuevo instalador para Windows ha reemplazado al antiguo MSI. Consultar Uso de Python en Windows para más información.

Ahora las compilaciones de Windows usan Microsoft Visual C++ 14.0, y los módulos de extensión deberían utilizar lo mismo.

Por favor sigue leyendo para obtener una lista completa de los cambios que se enfrentan los usuarios, incluidas muchas otras mejoras menores, optimizaciones de CPython, deprecaciones y posibles problemas de portabilidad.

Nuevas características

PEP 492 - Corrutinas con sintaxis async y await

PEP 492 [https://www.python.org/dev/peps/pep-0492] mejora enormemente el soporte para la programación asíncrona en Python al agregar objetos aguardables, funciones corrutina, iteración asincrónica, y gestores asincrónicos de contexto.

Las funciones corrutina se declaran usando la nueva sintaxis async def:

>>> async def coro():
...     return 'spam'

Dentro de una función corrutina, la nueva expresión await puede ser usada para suspender la ejecución de la corrutina hasta que el resultado esté disponible. Cualquier objeto puede ser awaited, siempre que implemente el protocolo awaitable al definir el método __await__().

PEP 492 también agrega la declaración async for para una iteración conveniente sobre iterables asincrónicas.

Un ejemplo de un cliente rudimentario HTTP escrito con la nueva sintaxis:

import asyncio

async def http_get(domain):
    reader, writer = await asyncio.open_connection(domain, 80)

    writer.write(b'\r\n'.join([
        b'GET / HTTP/1.1',
        b'Host: %b' % domain.encode('latin-1'),
        b'Connection: close',
        b'', b''
    ]))

    async for line in reader:
        print('>>>', line)

    writer.close()

loop = asyncio.get_event_loop()
try:
    loop.run_until_complete(http_get('example.com'))
finally:
    loop.close()

De manera similar a la iteración asincrónica, hay una nueva sintaxis para los gestores asincrónicos de contexto. El siguiente script:

import asyncio

async def coro(name, lock):
    print('coro {}: waiting for lock'.format(name))
    async with lock:
        print('coro {}: holding the lock'.format(name))
        await asyncio.sleep(1)
        print('coro {}: releasing the lock'.format(name))

loop = asyncio.get_event_loop()
lock = asyncio.Lock()
coros = asyncio.gather(coro(1, lock), coro(2, lock))
try:
    loop.run_until_complete(coros)
finally:
    loop.close()

saldrá:

coro 2: waiting for lock
coro 2: holding the lock
coro 1: waiting for lock
coro 2: releasing the lock
coro 1: holding the lock
coro 1: releasing the lock

Ten en cuenta que tanto async for como async with solamente pueden ser utilizadas dentro de una función corrutina declarada con async def.

Las funciones corrutina están destinadas para ser ejecutadas dentro de un bucle de eventos compatible, como asyncio loop.

Nota

Distinto en la versión 3.5.2: A partir de CPython 3.5.2, __aiter__ puede retornar directamente iteradores asincrónicos. Retornar un objeto awaitable resultará en PendingDeprecationWarning.

Consultar más detalles en la sección de la documentación Iteradores asíncronos.

Ver también

PEP 492 [https://www.python.org/dev/peps/pep-0492] – Corrutinas con sintaxis async y await

PEP escrito e implementado por Yury Selivanov.

PEP 465 - Un operador infijo dedicado para la multiplicación de matrices

PEP 465 [https://www.python.org/dev/peps/pep-0465] agrega el operador infijo @ para la multiplicación de matrices. Actualmente, ningún tipo de Python incorporado implementa el nuevo operador, sin embargo, puede ser implementado al definir __matmul__(), __rmatmul__(), y __imatmul__() para la multiplicación de matrices regulares, reflejadas e in situ. La semántica de estos métodos es similar a la de los métodos que definen otros operadores infijos aritméticos.

La multiplicación de matrices es una operación notablemente común en muchos campos de las matemáticas, la ciencia, la ingeniería, y la adición de @ permite escribir código más limpio:

S = (H @ beta - r).T @ inv(H @ V @ H.T) @ (H @ beta - r)

en lugar de:

S = dot((dot(H, beta) - r).T,
        dot(inv(dot(dot(H, V), H.T)), dot(H, beta) - r))

NumPy 1.10 tiene soporte para el nuevo operador:

>>> import numpy

>>> x = numpy.ones(3)
>>> x
array([ 1., 1., 1.])

>>> m = numpy.eye(3)
>>> m
array([[ 1., 0., 0.],
       [ 0., 1., 0.],
       [ 0., 0., 1.]])

>>> x @ m
array([ 1., 1., 1.])

Ver también

PEP 465 [https://www.python.org/dev/peps/pep-0465] – Un operador infijo dedicado para la multiplicación de matrices

PEP escrito por Nathaniel J. Smith; implementado por Benjamin Peterson.

PEP 448 - Generalizaciones de desembalaje adicionales

PEP 448 [https://www.python.org/dev/peps/pep-0448] extiende los usos permitidos del operador de desembalaje iterable * y del operador de desembalaje del diccionario **. Ahora es posible utilizar un número arbitrario de desembalajes en llamadas a funciones:

>>> print(*[1], *[2], 3, *[4, 5])
1 2 3 4 5

>>> def fn(a, b, c, d):
...     print(a, b, c, d)
...

>>> fn(**{'a': 1, 'c': 3}, **{'b': 2, 'd': 4})
1 2 3 4

De manera similar, las pantallas de tupla, lista, conjunto y diccionario permiten desembalajes múltiples (consultar Listas de expresiones and Despliegues de diccionario):

>>> *range(4), 4
(0, 1, 2, 3, 4)

>>> [*range(4), 4]
[0, 1, 2, 3, 4]

>>> {*range(4), 4, *(5, 6, 7)}
{0, 1, 2, 3, 4, 5, 6, 7}

>>> {'x': 1, **{'y': 2}}
{'x': 1, 'y': 2}

Ver también

PEP 448 [https://www.python.org/dev/peps/pep-0448] – Generalizaciones de desembalaje adicionales

PEP escrito por Joshua Landau; implementado por Neil Girdhar, Thomas Wouters y Joshua Landau.

PEP 461 - soporte de formateo porcentual para bytes y bytearray

PEP 461 [https://www.python.org/dev/peps/pep-0461] agrega soporte para el operador de interpolación % a bytes y bytearray.

Si bien la interpolación generalmente se considera una operación de cadena de caracteres, hay casos donde la interpolación en bytes o bytearrays tiene sentido y el trabajo necesario para compensar esta funcionalidad faltante resta valor a la legibilidad general del código. Este problema es particularmente importante cuando se trata con protocolos de formato de cable, que a menudo son una mezcla de texto compatible binario y ASCII.

Ejemplos:

>>> b'Hello %b!' % b'World'
b'Hello World!'

>>> b'x=%i y=%f' % (1, 2.5)
b'x=1 y=2.500000'

Unicode no está permitido para %b, pero es aceptado por %a (equivalente a repr(obj).encode('ascii', 'backslashreplace')):

>>> b'Hello %b!' % 'World'
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: %b requires bytes, or an object that implements __bytes__, not 'str'

>>> b'price: %a' % '10€'
b"price: '10\\u20ac'"

Ten en cuenta que los tipos de conversión %s y %r, aunque son compatibles, solo deben usarse en bases de código que necesiten compatibilidad con Python 2.

Ver también

PEP 461 [https://www.python.org/dev/peps/pep-0461] – Agrega formato % a bytes y bytearray

PEP escrito por Ethan Furman; implementado por Neil Schemenauer y Ethan Furman.

PEP 484 - Indicador de tipos

La sintaxis de anotaciones de funciones ha sido una característica de Python desde la versión 3.0 (PEP 3107 [https://www.python.org/dev/peps/pep-3107]), sin embargo, la semántica de anotaciones se ha dejado indefinida.

La experiencia ha mostrado que la mayoría de los usos de las anotaciones de funciones eran para proporcionar el indicador de tipos para los parámetros de función y los valores de retorno. Se hizo evidente que sería beneficioso para los usuarios de Python, si la biblioteca estándar incluyera las definiciones y las herramientas base para las anotaciones de tipo.

PEP 484 [https://www.python.org/dev/peps/pep-0484] introduce un módulo provisional para proporcionar estas definiciones y herramientas estándar, junto con algunas convenciones para situaciones en la que las anotaciones no están disponibles.

Por ejemplo, aquí hay una función simple cuyo argumento y tipo de retorno se declaran en las anotaciones:

def greeting(name: str) -> str:
    return 'Hello ' + name

Si bien estas anotaciones están disponibles en tiempo de ejecución a través del atributo habitual __annotations__, no se realiza ninguna verificación de tipos automática en tiempo de ejecución. En su lugar, se asume que se utilizará un verificador de tipos fuera de línea independiente (p. ej. mypy [http://mypy-lang.org]) para el análisis de código fuente bajo demanda.

El sistema de tipos admite uniones, tipos genéricos y un tipo especial llamado Any el cual es consistente con (esto es asignable desde y hacia) todos los tipos.

Ver también

typing documentación del módulo

PEP 484 [https://www.python.org/dev/peps/pep-0484] – Indicador de tipos

PEP escrito por Guido van Rossum, Jukka Lehtosalo y Łukasz Langa; implementado por Guido van Rossum.

PEP 483 [https://www.python.org/dev/peps/pep-0483] – La teoría del indicador de tipos

PEP escrito por Guido van Rossum

PEP 471 - Función os.scandir() – un iterador de directorio mejor y más rápido

PEP 471 [https://www.python.org/dev/peps/pep-0471] agrega una nueva función de iteración de directorio, os.scandir(), a la biblioteca estándar. Adicionalmente, ahora os.walk() se implementa utilizando scandir, lo que lo hace de 3 a 5 veces más rápido en sistemas POSIX y de 7 a 20 veces más rápido en sistemas Windows. Esto se logra en gran medida al reducir enormemente el número de llamadas necesarias de os.stat() para recorrer un árbol de directorios.

También scandir retorna un iterador, en lugar de retornar una lista de nombres de archivos, lo que mejora la eficiencia de la memoria cuando se itera sobre directorios muy grandes.

El siguiente ejemplo presenta un uso simple de os.scandir() para mostrar todos los archivos (excluyendo directorios) en el path dado que no comienzan con '.'. La llamada a entry.is_file() generalmente no hará una llamada adicional al sistema:

for entry in os.scandir(path):
    if not entry.name.startswith('.') and entry.is_file():
        print(entry.name)

Ver también

PEP 471 [https://www.python.org/dev/peps/pep-0471] – Función os.scandir() – un iterador de directorio mejor y más rápido

PEP escrito e implementado por Ben Hoyt con la ayuda de Victor Stinner.

PEP 475: Reintentar las llamadas al sistema que fallan con EINTR

Se retorna un código de error errno.EINTR siempre que una llamada al sistema, que está esperando E/S, es interrumpida por una señal. Anteriormente, Python generaría InterruptedError en tales casos. Esto significaba que, al escribir una aplicación en Python, el desarrollador tenía dos opciones:

Ignorar el InterruptedError.

Manejar el InterruptedError y probar reiniciar la llamada interrumpida al sistema en cada sitio de llamada.

La primera opción hace que una aplicación falle intermitentemente. La segunda opción agrega una gran cantidad de código repetitivo que hace que el código sea casi ilegible. Compara:

print("Hello World")

y:

while True:
    try:
        print("Hello World")
        break
    except InterruptedError:
        continue

PEP 475 [https://www.python.org/dev/peps/pep-0475] implementa el reintento automático de las llamadas al sistema en EINTR. Esto elimina la carga de lidiar con EINTR o la excepción InterruptedError en el código de usuario en la mayoría de las situaciones y hace que los programas de Python, incluida la biblioteca estándar, sean más robustos. Ten en cuenta que la llamada al sistema sólo se reintenta si el gestor de señales no lanza una excepción.

A continuación se muestra una lista de funciones que ahora se reintentan cuando son interrumpidas por una señal:

open() y io.open();

funciones del módulo faulthandler;

funciones del módulo os: fchdir(), fchmod(), fchown(), fdatasync(), fstat(), fstatvfs(), fsync(), ftruncate(), mkfifo(), mknod(), open(), posix_fadvise(), posix_fallocate(), pread(), pwrite(), read(), readv(), sendfile(), wait3(), wait4(), wait(), waitid(), waitpid(), write(), writev();

casos especiales: ahora os.close() y os.dup2() ignoran errores EINTR; no se reintenta la llamada al sistema (consultar la PEP para la justificación);

funciones del módulo select: devpoll.poll(), epoll.poll(), kqueue.control(), poll.poll(), select();

métodos de la clase socket: accept(), connect() (excepto para sockets sin bloqueo), recv(), recvfrom(), recvmsg(), send(), sendall(), sendmsg(), sendto();

signal.sigtimedwait() y signal.sigwaitinfo();

time.sleep().

Ver también

PEP 475 [https://www.python.org/dev/peps/pep-0475] – Reintentar las llamadas al sistema que fallan con EINTR

PEP e implementación escrita por Charles-François Natali y Victor Stinner, con la ayuda de Antoine Pitrou (la conexión francesa).

PEP 479: Cambiar el gestor de StopIteration dentro de generadores

La interacción de los generadores y StopIteration en las versiones de Python 3.4 y anteriores a veces fue sorprendente y podría ocultar bugs oscuros. Anteriormente, el StopIteration lanzado accidentalmente dentro de una función de generadores se interpretó como el final de la iteración por la construcción de bucle que impulsa el generador.

PEP 479 [https://www.python.org/dev/peps/pep-0479] cambia el comportamiento de los generadores: cuando se lanza una excepción StopIteration dentro de un generador, se reemplaza con una excepción RuntimeError antes de que salga del marco del generador. El objetivo principal de este cambio es facilitar la depuración en la situación en la que una llamada desprotegida a la función next() lanza una excepción StopIteration y hace que la iteración controlada por el generador termine silenciosamente. Esto es particularmente pernicioso en combinación con la construcción yield from.

Este es un cambio incompatible hacia atrás, así que para habilitar el nuevo comportamiento, es necesario importar __future__:

>>> from __future__ import generator_stop

>>> def gen():
...     next(iter([]))
...     yield
...
>>> next(gen())
Traceback (most recent call last):
  File "<stdin>", line 2, in gen
StopIteration

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
RuntimeError: generator raised StopIteration

Si no se importa __future__, se lanzará la excepción PendingDeprecationWarning siempre que se lance una excepción StopIteration dentro de un generador.

Ver también

PEP 479 [https://www.python.org/dev/peps/pep-0479] – Cambiar el gestor de StopIteration dentro de generadores

PEP escrito por Chris Angelico y Guido van Rossum. Implementado por Chris Angelico, Yury Selivanov y Nick Coghlan.

PEP 485: Una función para probar la igualdad aproximada

PEP 485 [https://www.python.org/dev/peps/pep-0485] agrega las funciones math.isclose() y cmath.isclose() que indican si dos valores son aproximadamente iguales o «cercanos» entre sí. Si dos valores se consideran cercanos o no, se determina conforme con las tolerancias absolutas y relativas dadas. La tolerancia relativa es la diferencia máxima permitida entre los argumentos isclose, en relación con el valor absoluto mayor:

>>> import math
>>> a = 5.0
>>> b = 4.99998
>>> math.isclose(a, b, rel_tol=1e-5)
True
>>> math.isclose(a, b, rel_tol=1e-6)
False

También es posible comparar dos valores usando una tolerancia absoluta, que debe ser un valor no negativo:

>>> import math
>>> a = 5.0
>>> b = 4.99998
>>> math.isclose(a, b, abs_tol=0.00003)
True
>>> math.isclose(a, b, abs_tol=0.00001)
False

Ver también

PEP 485 [https://www.python.org/dev/peps/pep-0485] – Una función para probar la igualdad aproximada

PEP escrito por Christopher Barker; implementado por Chris Barker y Tal Einat.

PEP 486: Hacer que el launcher de Python sea consciente de los entornos virtuales

PEP 486 [https://www.python.org/dev/peps/pep-0486] hace que el launcher de Windows (consultar PEP 397 [https://www.python.org/dev/peps/pep-0397]) sea consciente de un entorno virtual activo. Cuando se usa el intérprete predeterminado y se establece la variable de entorno VIRTUAL_ENV está configurado, se utilizará el intérprete en el entorno virtual.

Ver también

PEP 486 [https://www.python.org/dev/peps/pep-0486] – Hacer que el launcher de Python sea consciente de los entornos virtuales

PEP escrito e implementado por Paul Moore.

PEP 488: Eliminación de archivos PYO

PEP 488 [https://www.python.org/dev/peps/pep-0488] elimina el concepto de archivos .pyo. Esto significa que los archivos .pyc representan tanto bytecode optimizado y sin optimizar. Para evitar la necesidad de regenerar constantemente archivos bytecode, ahora los archivos .pyc tienen una etiqueta opcional opt- en su nombre cuando se optimiza el bytecode. Esto tiene el efecto secundario de que no habrá más conflictos de nombres de archivos de bytecode cuando se ejecuta bajo -O o -OO. Por consiguiente, ahora los archivos bytecode generados a partir de -O y -OO pueden existir simultáneamente. importlib.util.cache_from_source() tiene una API actualizada para ayudar con este cambio.

Ver también

PEP 488 [https://www.python.org/dev/peps/pep-0488] – Eliminación de archivos PYO

PEP escrito e implementado por Brett Cannon.

PEP 489: Inicialización del módulo de extensión multifase

PEP 489 [https://www.python.org/dev/peps/pep-0489] actualiza la inicialización del módulo de extensión para aprovechar el mecanismo de carga del módulo de dos pasos introducido por PEP 451 [https://www.python.org/dev/peps/pep-0451] en Python 3.4.

Este cambio acerca la semántica de importación de los módulos de extensión que optan por usar el mecanismo nuevo a la de los módulos fuente y de bytecode de Python, incluida la capacidad de utilizar cualquier identificador válido como un nombre de módulo, en lugar de estar restringido a ASCII.

Ver también

PEP 489 [https://www.python.org/dev/peps/pep-0489] – Inicialización del módulo de extensión multifase

PEP escrito por Petr Viktorin, Stefan Behnel y Nick Coghlan; implementado por Petr Viktorin.

Otros cambios en el lenguaje

Algunos cambios más pequeños que se hicieron en el lenguaje central de Python son:

Se agregaron los gestores de error "namereplace". Ahora los gestores de error "backslashreplace" funcionan con decodificación y traducción. (Contribución de Serhiy Storchaka en bpo-19676 [https://bugs.python.org/issue?@action=redirect&bpo=19676] y bpo-22286 [https://bugs.python.org/issue?@action=redirect&bpo=22286].)

Ahora la opción -b afecta comparaciones de bytes con int. (Contribución de Serhiy Storchaka en bpo-23681 [https://bugs.python.org/issue?@action=redirect&bpo=23681].)

Nuevos códecs Kazakh kz1048 y Tajik koi8_t. (Contribución de Serhiy Storchaka en bpo-22682 [https://bugs.python.org/issue?@action=redirect&bpo=22682] y bpo-22681 [https://bugs.python.org/issue?@action=redirect&bpo=22681].)

Ahora las docstrings de propiedad se pueden escribir. Esto es especialmente útil para las docstrings collections.namedtuple(). (Contribución de Berker Peksag en bpo-24064 [https://bugs.python.org/issue?@action=redirect&bpo=24064].)

Ahora se admiten las importaciones circulares que involucran importaciones relativas. (Contribución de Brett Cannon y Antoine Pitrou en bpo-17636 [https://bugs.python.org/issue?@action=redirect&bpo=17636].)

Nuevos módulos

typing

El módulo nuevo provisional typing proporciona definiciones y herramientas estándar para anotaciones de tipos de funciones. Consultar Indicador de tipos para más información.

zipapp

El módulo nuevo zipapp (especificado en PEP 441 [https://www.python.org/dev/peps/pep-0441]) proporciona una API y una herramienta de línea de comandos para crear aplicaciones Python Zip ejecutables, las cuales se introdujeron en la versión de Python 2.6 en bpo-1739468 [https://bugs.python.org/issue?@action=redirect&bpo=1739468], pero no se publicitaron bien, ni en ese momento ni desde entonces.

Con el módulo nuevo, empaquetar tu aplicación es tan simple como colocar todos los archivos, incluido un archivo __main__.py en un directorio myapp y ejecutar:

$ python -m zipapp myapp
$ python myapp.pyz

La implementación del módulo ha sido contribución de Paul Moore en bpo-23491 [https://bugs.python.org/issue?@action=redirect&bpo=23491].

Ver también

PEP 441 [https://www.python.org/dev/peps/pep-0441] – Mejora de soporte de la aplicación Python ZIP

Módulos mejorados

argparse

Ahora la clase ArgumentParser permite deshabilitar el uso abreviado de opciones largas al establecer allow_abbrev en False. (Contribución de Jonathan Paugh, Steven Bethard, paul j3 y Daniel Eriksson en bpo-14910 [https://bugs.python.org/issue?@action=redirect&bpo=14910].)

asyncio

Ya que el módulo asyncio es provisional, todos los cambios que se introdujeron en Python 3.5 también se han actualizado en Python 3.4.x.

Cambios notables en el módulo asyncio desde Python 3.4.0:

Nuevas API de depuración: métodos loop.set_debug() y loop.get_debug(). (Contribución de Victor Stinner.)

Ahora el ciclo de eventos proactor es compatible con SSL. (Contribución de Antoine Pitrou y Victor Stinner en bpo-22560 [https://bugs.python.org/issue?@action=redirect&bpo=22560].)

Un nuevo método loop.is_closed() para comprobar si el ciclo de eventos está cerrado. (Contribución de Victor Stinner en bpo-21326 [https://bugs.python.org/issue?@action=redirect&bpo=21326].)

Un nuevo método loop.create_task() para crear y programar convenientemente una nueva clase Task para una corrutina. El método create_task también se usa para todas las funciones asyncio que contengan corrutinas en tareas, tales como asyncio.wait(), asyncio.gather(), etc. (Contribución de Victor Stinner.)

Un nuevo método transport.get_write_buffer_limits() para consultar los límites high- (superior) y low- (inferior) del control de flujo. (Contribución de Victor Stinner.)

La función async() está obsoleta en favor de la función ensure_future(). (Contribución de Yury Selivanov.)

Nuevos métodos loop.set_task_factory() y loop.get_task_factory() para personalizar la fábrica de tareas que el método loop.create_task() usa. (Contribución de Yury Selivanov.)

Nuevos métodos de cola Queue.join() y Queue.task_done(). (Contribución de Victor Stinner.)

Se eliminó la clase JoinableQueue, en favor de la clase asyncio.Queue. (Contribución de Victor Stinner.)

Actualizaciones en 3.5.1:

La función ensure_future() y todas las funciones que la utilizan, como el método loop.run_until_complete(), ahora acepta todo tipo de objetos aguardables. (Contribución de Yury Selivanov.)

Nueva función run_coroutine_threadsafe() para enviar corrutinas a bucles de eventos de otros hilos. (Contribución de Vincent Michel.)

Nuevo método Transport.is_closing() para comprobar si el transporte se está cerrando o ya está cerrado. (Contribución de Yury Selivanov.)

Ahora el método loop.create_server() puede aceptar una lista de hosts. (Contribución de Yann Sionneau.)

Actualizaciones en 3.5.2:

Nuevo método loop.create_future() para crear objetos Future. Esto permite implementaciones alternativas de bucles de eventos, como uvloop [https://github.com/MagicStack/uvloop], para proporcionar una implementación más rápida de asyncio.Future. (Contribución de Yury Selivanov.)

Nuevo método loop.get_exception_handler() para obtener el gestor de excepciones actual. (Contribución de Yury Selivanov.)

Nuevo método StreamReader.readuntil() para leer datos de la secuencia hasta que aparezca una secuencia de separador de bytes. (Contribución de Mark Korenberg.)

Se optimizaron los métodos loop.create_connection() y loop.create_server() para evitar llamar al sistema la función getaddrinfo si la dirección ya está resuelta. (Contribución de A. Jesse Jiryu Davis.)

El método loop.sock_connect(sock, address) ya no requiere address para que se resuelva antes de la llamada. (Contribución de A. Jesse Jiryu Davis.)

bz2

Ahora el método BZ2Decompressor.decompress acepta un argumento opcional max_length para limitar el tamaño máximo de datos descomprimidos. (Contribución de Nikolaus Rath en bpo-15955 [https://bugs.python.org/issue?@action=redirect&bpo=15955].)

cgi

Ahora la clase FieldStorage admite el protocolo context manager. (Contribución de Berker Peksag en bpo-20289 [https://bugs.python.org/issue?@action=redirect&bpo=20289].)

cmath

Una nueva función isclose() proporciona una forma de probar la igualdad aproximada. (Contribución de Chris Barker y Tal Einat en bpo-24270 [https://bugs.python.org/issue?@action=redirect&bpo=24270].)

code

Ahora el método InteractiveInterpreter.showtraceback() imprime el rastreo encadenado completo, al igual que el interprete interactivo. (Contribución de Claudiu Popa en bpo-17442 [https://bugs.python.org/issue?@action=redirect&bpo=17442].)

collections

Ahora la clase OrderedDict está implementada en C, lo que la hace de 4 a 100 veces más rápida. (Contribución de Eric Snow en bpo-16991 [https://bugs.python.org/issue?@action=redirect&bpo=16991].)

OrderedDict.items(), OrderedDict.keys(), OrderedDict.values() ahora soportan la iteración reversed(). (Contribución de Serhiy Storchaka en bpo-19505 [https://bugs.python.org/issue?@action=redirect&bpo=19505].)

Ahora la clase deque define index(), insert() y copy(), y soporta los operadores + y *. Esto permite que las deques sean reconocidas como MutableSequence y mejora su sustituibilidad por listas. (Contribución de Raymond Hettinger en bpo-23704 [https://bugs.python.org/issue?@action=redirect&bpo=23704].)

Ahora las docstrings producidas por namedtuple() se pueden actualizar:

Point = namedtuple('Point', ['x', 'y'])
Point.__doc__ += ': Cartesian coodinate'
Point.x.__doc__ = 'abscissa'
Point.y.__doc__ = 'ordinate'

(Contribución de Berker Peksag en bpo-24064 [https://bugs.python.org/issue?@action=redirect&bpo=24064].)

Ahora la clase UserString implementa los métodos __getnewargs__(), __rmod__(), casefold(), format_map(), isprintable() y maketrans() para que coincidan con los métodos correspondientes de str. (Contribución de Joe Jevnik en bpo-22189 [https://bugs.python.org/issue?@action=redirect&bpo=22189].)

collections.abc

Ahora el método Sequence.index() acepta los argumentos start y stop para que coincidan con los métodos correspondientes de tuple, list, etc. (Contribución de Devin Jeanpierre en bpo-23086 [https://bugs.python.org/issue?@action=redirect&bpo=23086].)

Una nueva clase de base abstracta Generator. (Contribución de Stefan Behnel en bpo-24018 [https://bugs.python.org/issue?@action=redirect&bpo=24018].)

Nuevas clases de base abstracta Awaitable, Coroutine, AsyncIterator y AsyncIterable. (Contribución de Yury Selivanov en bpo-24184 [https://bugs.python.org/issue?@action=redirect&bpo=24184].)

Para versiones anteriores de Python, un backport del nuevo ABC está disponible en un paquete PyPI [https://pypi.org/project/backports_abc] externo.

compileall

Una nueva opción compileall, -j N, permite ejecutar N workers simultáneamente para realizar la compilación de bytecode en paralelo. La función compile_dir() tiene un parámetro workers correspondiente. (Contribución de Claudiu Popa en bpo-16104 [https://bugs.python.org/issue?@action=redirect&bpo=16104].)

Otra nueva opción, -r, permite controlar el nivel máximo de recursividad de los subdirectorios. (Contribución de Claudiu Popa en bpo-19628 [https://bugs.python.org/issue?@action=redirect&bpo=19628].)

Ahora la opción de línea de comando -q se puede especificar más de una vez, en cuyo caso todas las salidas, incluyendo errores, se suprimirán. Ahora el parámetro quiet correspondiente en compile_dir(), compile_file() y compile_path() puede aceptar un valor entero que indica el nivel de supresión de salida. (Contribución de Thomas Kluyver en bpo-21338 [https://bugs.python.org/issue?@action=redirect&bpo=21338].)

concurrent.futures

Ahora el método Executor.map() acepta un argumento chunksize para permitir el procesamiento por lotes de tareas para mejorar el desempeño cuando se usa ProcessPoolExecutor(). (Contribución de Dan O’Reilly en bpo-11271 [https://bugs.python.org/issue?@action=redirect&bpo=11271].)

Ahora el número de workers en el constructor ThreadPoolExecutor es opcional. El valor predeterminado es 5 veces el número de CPUs. (Contribución de Claudiu Popa en bpo-21527 [https://bugs.python.org/issue?@action=redirect&bpo=21527].)

configparser

Ahora configparser proporciona una forma de personalizar la conversión de valores al especificar un diccionario de convertidores en el constructor ConfigParser o al definirlos como métodos en las subclases ConfigParser. Los convertidores definidos en una instancia de analizador se heredan por sus proxies de sección.

Ejemplo:

>>> import configparser
>>> conv = {}
>>> conv['list'] = lambda v: [e.strip() for e in v.split() if e.strip()]
>>> cfg = configparser.ConfigParser(converters=conv)
>>> cfg.read_string("""
... [s]
... list = a b c d e f g
... """)
>>> cfg.get('s', 'list')
'a b c d e f g'
>>> cfg.getlist('s', 'list')
['a', 'b', 'c', 'd', 'e', 'f', 'g']
>>> section = cfg['s']
>>> section.getlist('list')
['a', 'b', 'c', 'd', 'e', 'f', 'g']

(Contribución de Łukasz Langa en bpo-18159 [https://bugs.python.org/issue?@action=redirect&bpo=18159].)

contextlib

El nuevo context manager redirect_stderr() (similar a redirect_stdout()) facilita que los scripts de utilidad manejen APIs inflexibles que escriben su salida a sys.stderr y no proporcionen ninguna opción para redirigirlo:

>>> import contextlib, io, logging
>>> f = io.StringIO()
>>> with contextlib.redirect_stderr(f):
...     logging.warning('warning')
...
>>> f.getvalue()
'WARNING:root:warning\n'

(Contribución de Berker Peksag en bpo-22389 [https://bugs.python.org/issue?@action=redirect&bpo=22389].)

csv

Ahora el método writerow() admite iterables arbitrarios, no sólo secuencias. (Contribución de Serhiy Storchaka en bpo-23171 [https://bugs.python.org/issue?@action=redirect&bpo=23171].)

curses

La nueva función update_lines_cols() actualiza las variables de entorno LINES y COLS. Esto es útil para detectar el cambio de tamaño manual de la pantalla. (Contribución de Arnon Yaari en bpo-4254 [https://bugs.python.org/issue?@action=redirect&bpo=4254].)

dbm

dumb.open siempre crea una nueva base de datos cuando la bandera tiene el valor "n". (Contribución de Claudiu Popa en bpo-18039 [https://bugs.python.org/issue?@action=redirect&bpo=18039].)

difflib

Ahora el juego de caracteres de los documentos HTML generado por HtmlDiff.make_file() se puede personalizar usando un nuevo argumento de solo palabras clave charset. El juego de caracteres predeterminado del documento HTML cambió de "ISO-8859-1" a "utf-8". (Contribución de Berker Peksag en bpo-2052 [https://bugs.python.org/issue?@action=redirect&bpo=2052].)

Ahora la función diff_bytes() puede comparar listas de bytes de cadenas de caracteres. Esto arregla una regresión de Python 2. (Contribución de Terry J. Reedy y Greg Ward en bpo-17445 [https://bugs.python.org/issue?@action=redirect&bpo=17445].)

distutils

Ahora los comandos build y build_ext aceptan una opción -j para habilitar la construcción paralela de módulos de extensión. (Contribución de Antoine Pitrou en bpo-5309 [https://bugs.python.org/issue?@action=redirect&bpo=5309].)

Ahora el módulo distutils admite la compresión xz y se puede habilitar pasando xztar como un argumento a bdist --format. (Contribución de Serhiy Storchaka en bpo-16314 [https://bugs.python.org/issue?@action=redirect&bpo=16314].)

doctest

La función DocTestSuite() retorna una clase unittest.TestSuite vacía si module no contiene docstrings, en lugar de lanzar ValueError. (Contribución de Glenn Jones en bpo-15916 [https://bugs.python.org/issue?@action=redirect&bpo=15916].)

email

Una nueva opción de directiva Policy.mangle_from_ controla si las líneas que empiecen o no con "From " en los cuerpos del correo electrónico tienen el prefijo de un caracter ">" por generadores. El valor predeterminado es True para compat32 y False para todas las demás directivas. (Contribución de Milan Oberkirch en bpo-20098 [https://bugs.python.org/issue?@action=redirect&bpo=20098].)

Un nuevo método Message.get_content_disposition() proporciona fácil acceso a un valor canónico para el encabezado Content-Disposition. (Contribución de Abhilash Raj en bpo-21083 [https://bugs.python.org/issue?@action=redirect&bpo=21083].)

Una nueva opción de directiva EmailPolicy.utf8 se puede configurar en True para codificar los encabezados de correo electrónico usando el juego de caracteres UTF-8 en lugar de utilizar palabras codificadas. Esto permite formatear Messages de acuerdo a RFC 6532 [https://tools.ietf.org/html/rfc6532.html] y usarlos con un servidor SMTP que admita la extensión RFC 6531 [https://tools.ietf.org/html/rfc6531.html] SMTPUTF8. (Contribución de R. David Murray en bpo-24211 [https://bugs.python.org/issue?@action=redirect&bpo=24211].)

Ahora el constructor mime.text.MIMEText admite una instancia de charset.Charset. (Contribución de Claude Paroz y Berker Peksag en bpo-16324 [https://bugs.python.org/issue?@action=redirect&bpo=16324].)

enum

La clase invocable Enum tiene un nuevo parámetro start para especificar el número inicial de los valores de enumeración si solo se proporcionan names:

>>> Animal = enum.Enum('Animal', 'cat dog', start=10)
>>> Animal.cat
<Animal.cat: 10>
>>> Animal.dog
<Animal.dog: 11>

(Contribución de Ethan Furman en bpo-21706 [https://bugs.python.org/issue?@action=redirect&bpo=21706].)

faulthandler

Ahora las funciones enable(), register(), dump_traceback() y dump_traceback_later() aceptan descriptores de archivo además de objetos similares a archivos. (Contribución de Wei Wu en bpo-23566 [https://bugs.python.org/issue?@action=redirect&bpo=23566].)

functools

Ahora la mayoría de la maquinaria de lru_cache() se implementa en C, lo que la hace significativamente más rápida. (Contribución de Matt Joiner, Alexey Kachayev y Serhiy Storchaka en bpo-14373 [https://bugs.python.org/issue?@action=redirect&bpo=14373].)

glob

Ahora las funciones iglob() y glob() admiten búsquedas recursivas en subdirectorios usando el patrón "**". (Contribución de Serhiy Storchaka en bpo-13968 [https://bugs.python.org/issue?@action=redirect&bpo=13968].)

gzip

Ahora el argumento mode del constructor de GzipFile acepta "x" para solicitar la creación exclusiva. (Contribución de Tim Heaney en bpo-19222 [https://bugs.python.org/issue?@action=redirect&bpo=19222].)

heapq

Ahora la comparación de elementos en merge() se puede personalizar pasando una key function en un nuevo argumento de palabra clave opcional key, y un nuevo argumento de palabra clave opcional reverse se puede usar para revertir la comparación de elementos:

>>> import heapq
>>> a = ['9', '777', '55555']
>>> b = ['88', '6666']
>>> list(heapq.merge(a, b, key=len))
['9', '88', '777', '6666', '55555']
>>> list(heapq.merge(reversed(a), reversed(b), key=len, reverse=True))
['55555', '6666', '777', '88', '9']

(Contribución de Raymond Hettinger en bpo-13742 [https://bugs.python.org/issue?@action=redirect&bpo=13742].)

http

Una nueva enumeración HTTPStatus que define un conjunto de códigos de estado HTTP, frases de motivo y descripciones largas escritas en inglés. (Contribución de Demian Brecht en bpo-21793 [https://bugs.python.org/issue?@action=redirect&bpo=21793].)

http.client

Ahora HTTPConnection.getresponse() lanza una excepción RemoteDisconnected cuando una conexión de servidor remoto se cierra inesperadamente. Además, si se lanza una excepción ConnectionError (del cual RemoteDisconnected es una subclase), ahora el socket del cliente se cierra automáticamente y se reconectará en la siguiente solicitud:

import http.client
conn = http.client.HTTPConnection('www.python.org')
for retries in range(3):
    try:
        conn.request('GET', '/')
        resp = conn.getresponse()
    except http.client.RemoteDisconnected:
        pass

(Contribución de Martin Panter en bpo-3566 [https://bugs.python.org/issue?@action=redirect&bpo=3566].)

idlelib e IDLE

Desde que idlelib implementa el shell y el editor IDLE y no se destina para ser importado por otros programas, obtiene mejoras con cada versión. Consultar Lib/idlelib/NEWS.txt para una lista acumulativa de cambios desde la 3.4.0, así como los cambios realizados en futuras versiones 3.5.x. Este archivo también está disponible en IDLE Help ‣ About IDLE.

imaplib

Ahora la clase IMAP4 admite el protocolo context manager. Cuando se utiliza en una declaración with, el comando IMAP4 LOGOUT se llamará automáticamente al final del bloque. (Contribución de Tarek Ziadé y Serhiy Storchaka en bpo-4972 [https://bugs.python.org/issue?@action=redirect&bpo=4972].)

Ahora el módulo imaplib admite RFC 5161 [https://tools.ietf.org/html/rfc5161.html] (extensión ENABLE) y RFC 6855 [https://tools.ietf.org/html/rfc6855.html] (soporte UTF-8) a través del método IMAP4.enable(). Un nuevo atributo IMAP4.utf8_enabled rastrea si el soporte con RFC 6855 [https://tools.ietf.org/html/rfc6855.html] está habilitado o no. (Contribución de Milan Oberkirch, R. David Murray y Maciej Szulik en bpo-21800 [https://bugs.python.org/issue?@action=redirect&bpo=21800].)

Ahora el módulo imaplib codifica automáticamente nombres de usuario y contraseñas de cadenas de caracteres no ASCII usando UTF-8, como recomiendan las RFCs. (Contribución de Milan Oberkirch en bpo-21800 [https://bugs.python.org/issue?@action=redirect&bpo=21800].)

imghdr

Ahora la función what() reconoce el formato OpenEXR [http://www.openexr.com] (contribución de Martin Vignali y Claudiu Popa en bpo-20295 [https://bugs.python.org/issue?@action=redirect&bpo=20295]) y el formato WebP [https://en.wikipedia.org/wiki/WebP] (contribución de Fabrice Aneche y Claudiu Popa en bpo-20197 [https://bugs.python.org/issue?@action=redirect&bpo=20197].)

importlib

La clase util.LazyLoader permite la carga lenta de módulos en aplicaciones donde el tiempo de inicio es importante. (Contribución de Brett Cannon en bpo-17621 [https://bugs.python.org/issue?@action=redirect&bpo=17621].)

Ahora el método es abc.InspectLoader.source_to_code() es un método estático. Esto hace más fácil la inicialización de un objeto de módulo con código compilado a partir de una cadena de caracteres ejecutando exec(code, module.__dict__). (Contribución de Brett Cannon en bpo-21156 [https://bugs.python.org/issue?@action=redirect&bpo=21156].)

Ahora la nueva función util.module_from_spec() es la forma preferida para crear un nuevo módulo. A diferencia de crear directamente una instancia types.ModuleType, esta nueva función configurará varios atributos controlados por importación basados en el objeto de especificación pasado. (Contribución de Brett Cannon en bpo-20383 [https://bugs.python.org/issue?@action=redirect&bpo=20383].)

inspect

Ahora las clases Signature y Parameter se pueden seleccionar y manipular. (Contribución de Yury Selivanov en bpo-20726 [https://bugs.python.org/issue?@action=redirect&bpo=20726] y bpo-20334 [https://bugs.python.org/issue?@action=redirect&bpo=20334].)

Un nuevo método BoundArguments.apply_defaults() proporciona una forma de establecer valores predeterminados para los argumentos faltantes:

>>> def foo(a, b='ham', *args): pass
>>> ba = inspect.signature(foo).bind('spam')
>>> ba.apply_defaults()
>>> ba.arguments
OrderedDict([('a', 'spam'), ('b', 'ham'), ('args', ())])

(Contribución de Yury Selivanov en bpo-24190 [https://bugs.python.org/issue?@action=redirect&bpo=24190].)

Un nuevo método de clase Signature.from_callable() facilita la subclasificación de Signature. (Contribución de Yury Selivanov y Eric Snow en bpo-17373 [https://bugs.python.org/issue?@action=redirect&bpo=17373].)

Ahora la función signature() acepta un argumento de palabra clave opcional follow_wrapped, el cual, cuando se establece en False, deshabilita el seguimiento automático de enlaces __wrapped__. (Contribución de Yury Selivanov en bpo-20691 [https://bugs.python.org/issue?@action=redirect&bpo=20691].)

Se ha agregado un conjunto de nuevas funciones para inspeccionar funciones corrutina y objetos corrutina: iscoroutine(), iscoroutinefunction(), isawaitable(), getcoroutinelocals() y getcoroutinestate(). (Contribución de Yury Selivanov en bpo-24017 [https://bugs.python.org/issue?@action=redirect&bpo=24017] y bpo-24400 [https://bugs.python.org/issue?@action=redirect&bpo=24400].)

Ahora las funciones stack(), trace(), getouterframes() y getinnerframes() retornan una lista de tuplas con nombre. (Contribución de Daniel Shahaf en bpo-16808 [https://bugs.python.org/issue?@action=redirect&bpo=16808].)

io

Un nuevo método BufferedIOBase.readinto1(), que usa como mucho una llamada al flujo sin procesar subyacente de los métodos RawIOBase.read() o RawIOBase.readinto(). (Contribución de Nikolaus Rath en bpo-20578 [https://bugs.python.org/issue?@action=redirect&bpo=20578].)

ipaddress

Ahora las clases IPv4Network y IPv6Network aceptan un argumento de tupla (address, netmask), para construir fácilmente objetos de red a partir de direcciones existentes:

>>> import ipaddress
>>> ipaddress.IPv4Network(('127.0.0.0', 8))
IPv4Network('127.0.0.0/8')
>>> ipaddress.IPv4Network(('127.0.0.0', '255.0.0.0'))
IPv4Network('127.0.0.0/8')

(Contribución de Peter Moody y Antoine Pitrou en bpo-16531 [https://bugs.python.org/issue?@action=redirect&bpo=16531].)

Un nuevo atributo reverse_pointer para las clases IPv4Network y IPv6Network retorna el nombre del registro DNS PTR inverso:

>>> import ipaddress
>>> addr = ipaddress.IPv4Address('127.0.0.1')
>>> addr.reverse_pointer
'1.0.0.127.in-addr.arpa'
>>> addr6 = ipaddress.IPv6Address('::1')
>>> addr6.reverse_pointer
'1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa'

(Contribución de Leon Weber en bpo-20480 [https://bugs.python.org/issue?@action=redirect&bpo=20480].)

json

Ahora la interfaz de la línea de comandos json.tool conserva el orden de los nombres en los objetos JSON pasados en la entrada. La nueva opción --sort-keys se puede usar para ordenar los nombres alfabéticamente. (Contribución de Berker Peksag en bpo-21650 [https://bugs.python.org/issue?@action=redirect&bpo=21650].)

Ahora el decodificador JSON lanza JSONDecodeError en lugar de ValueError para proporcionar una mejor información de contexto sobre el error. (Contribución de Serhiy Storchaka en bpo-19361 [https://bugs.python.org/issue?@action=redirect&bpo=19361].)

linecache

Una nueva función lazycache() se puede usar para capturar información sobre un módulo no basado en archivos para permitir obtener sus líneas más tarde a través de getline(). Esto evita hacer E/S hasta que una línea sea realmente necesaria, sin tener que llevar los módulos globales indefinidamente. (Contribución de Robert Collins en bpo-17911 [https://bugs.python.org/issue?@action=redirect&bpo=17911].)

locale

Una nueva función delocalize() se puede usar para convertir una cadena de caracteres en una cadena numérica normalizada, teniendo la configuración LC_NUMERIC en cuenta:

>>> import locale
>>> locale.setlocale(locale.LC_NUMERIC, 'de_DE.UTF-8')
'de_DE.UTF-8'
>>> locale.delocalize('1.234,56')
'1234.56'
>>> locale.setlocale(locale.LC_NUMERIC, 'en_US.UTF-8')
'en_US.UTF-8'
>>> locale.delocalize('1,234.56')
'1234.56'

(Contribución de Cédric Krier en bpo-13918 [https://bugs.python.org/issue?@action=redirect&bpo=13918].)

logging

Ahora todos los métodos del módulo logging (Logger log(), exception(), critical(), debug(), etc.), aceptan instancias de excepción como un argumento exc_info, además de valores booleanos y tuplas de excepción:

>>> import logging
>>> try:
...     1/0
... except ZeroDivisionError as ex:
...     logging.error('exception', exc_info=ex)
ERROR:root:exception

(Contribución de Yury Selivanov en bpo-20537 [https://bugs.python.org/issue?@action=redirect&bpo=20537].)

Ahora la clase handlers.HTTPHandler acepta una instancia opcional ssl.SSLContext para establecer la configuración SSL usada en una conexión HTTP. (Contribución de Alex Gaynor en bpo-22788 [https://bugs.python.org/issue?@action=redirect&bpo=22788].)

Ahora la clase handlers.QueueListener toma un argumento de palabra clave respect_handler_level, el cual, si se establece en True, pasará mensajes a gestores teniendo en cuenta los gestores de niveles. (Contribución de Vinay Sajip.)

lzma

Ahora el método LZMADecompressor.decompress() acepta un argumento opcional max_length para limitar el tamaño máximo de datos descomprimidos. (Contribución de Martin Panter en bpo-15955 [https://bugs.python.org/issue?@action=redirect&bpo=15955].)

math

Se agregaron dos nuevas contantes en el módulo math: inf y nan. (Contribución de Mark Dickinson en bpo-23185 [https://bugs.python.org/issue?@action=redirect&bpo=23185].)

Una nueva función isclose() proporciona una forma de comprobar la igualdad aproximada. (Contribución de Chris Barker y Tal Einat en bpo-24270 [https://bugs.python.org/issue?@action=redirect&bpo=24270].)

Se agregó una nueva función gcd(). Ahora la función fractions.gcd() está obsoleta. (Contribución de Mark Dickinson y Serhiy Storchaka en bpo-22486 [https://bugs.python.org/issue?@action=redirect&bpo=22486].)

multiprocessing

Ahora los objetos sharedctypes.synchronized() admiten el protocolo context manager. (Contribución de Charles-François Natali en bpo-21565 [https://bugs.python.org/issue?@action=redirect&bpo=21565].)

operator

Ahora los objetos attrgetter(), itemgetter() y methodcaller() admiten pickling. (Contribución de Josh Rosenberg y Serhiy Storchaka en bpo-22955 [https://bugs.python.org/issue?@action=redirect&bpo=22955].)

Las nuevas funciones matmul() y imatmul() para realizar multiplicación de matrices. (Contribución de Benjamin Peterson en bpo-21176 [https://bugs.python.org/issue?@action=redirect&bpo=21176].)

os

Se agregó la nueva función scandir() que retorna un iterador de DirEntry. Si es posible, scandir() extrae los atributos del archivo mientras escanea un directorio, eliminando la necesidad de realizar llamadas posteriores al sistema para determinar el tipo de archivo o los atributos, lo que puede mejorar significativamente el rendimiento. (Contribución de Ben Hoyt con la ayuda de Victor Stinner en bpo-22524 [https://bugs.python.org/issue?@action=redirect&bpo=22524].)

En Windows, ahora un nuevo atributo stat_result.st_file_attributes está disponible. Corresponde al miembro dwFileAttributes de la estructura BY_HANDLE_FILE_INFORMATION retornado por GetFileInformationByHandle(). (Contribución de Ben Hoyt en bpo-21719 [https://bugs.python.org/issue?@action=redirect&bpo=21719].)

Ahora la función urandom() usa la llamada al sistema getrandom() en Linux 3.17 o versiones más recientes, y getentropy() en OpenBSD 5.6 y versiones más recientes, eliminando la necesidad de utilizar /dev/urandom y evitando fallas debido al posible agotamiento del descriptor de archivo. (Contribución de Victor Stinner en bpo-22181 [https://bugs.python.org/issue?@action=redirect&bpo=22181].)

Las nuevas funciones get_blocking() y set_blocking() permiten obtener y establecer un modo de bloqueo del descriptor (O_NONBLOCK.) (Contribución de Victor Stinner en bpo-22054 [https://bugs.python.org/issue?@action=redirect&bpo=22054].)

Ahora las funciones truncate() y ftruncate() se admiten en Windows. (Contribución de Steve Dower en bpo-23668 [https://bugs.python.org/issue?@action=redirect&bpo=23668].)

Hay una nueva función os.path.commonpath() que retorna la sub-ruta común más larga de cada nombre de ruta pasado. A diferencia de la función os.path.commonprefix(), siempre retorna una ruta válida:

>>> os.path.commonprefix(['/usr/lib', '/usr/local/lib'])
'/usr/l'

>>> os.path.commonpath(['/usr/lib', '/usr/local/lib'])
'/usr'

(Contribución de Rafik Draoui y Serhiy Storchaka en bpo-10395 [https://bugs.python.org/issue?@action=redirect&bpo=10395].)

pathlib

El nuevo método Path.samefile() se puede usar para verificar si la ruta apunta al mismo archivo que otra ruta, el cual puede ser otro objeto Path o una cadena de caracteres:

>>> import pathlib
>>> p1 = pathlib.Path('/etc/hosts')
>>> p2 = pathlib.Path('/etc/../etc/hosts')
>>> p1.samefile(p2)
True

(Contribución de Vajrasky Kok y Antoine Pitrou en bpo-19775 [https://bugs.python.org/issue?@action=redirect&bpo=19775].)

Ahora el método Path.mkdir() acepta un nuevo argumento opcional exist_ok para que coincida con la funcionalidad mkdir -p y os.makedirs(). (Contribución de Berker Peksag en bpo-21539 [https://bugs.python.org/issue?@action=redirect&bpo=21539].)

Hay un nuevo método Path.expanduser() para expandir los prefijos ~ y ~user. (Contribución de Serhiy Storchaka y Claudiu Popa en bpo-19776 [https://bugs.python.org/issue?@action=redirect&bpo=19776].)

Una nueva clase de método Path.home() se puede usar para obtener una instancia Path que representa el directorio de inicio del usuario. (Contribución de Victor Salgado y Mayank Tripathi en bpo-19777 [https://bugs.python.org/issue?@action=redirect&bpo=19777].)

Los nuevos métodos Path.write_text(), Path.read_text(), Path.write_bytes(), Path.read_bytes() para simplificar la lectura/escritura de operaciones en los archivos.

El siguiente fragmento de código creará o reescribirá el archivo existente ~/spam42:

>>> import pathlib
>>> p = pathlib.Path('~/spam42')
>>> p.expanduser().write_text('ham')
3

(Contribución de Christopher Welborn en bpo-20218 [https://bugs.python.org/issue?@action=redirect&bpo=20218].)

pickle

Ahora los objetos anidados, como los métodos independientes o las clases anidadas, se pueden serializar con pickle usando protocolos pickle anteriores al protocolo de la versión 4. El protocolo de la versión 4 ya admite estos casos. (Contribución de Serhiy Storchaka en bpo-23611 [https://bugs.python.org/issue?@action=redirect&bpo=23611].)

poplib

Un nuevo comando POP3.utf8() habilita el soporte (correo electrónico internacionalizado) RFC 6856 [https://tools.ietf.org/html/rfc6856.html], si un servidor POP lo admite. (Contribución de Milan Oberkirch en bpo-21804 [https://bugs.python.org/issue?@action=redirect&bpo=21804].)

re

Ahora las referencias y referencias condicionales a grupos con longitud fija se permiten en afirmaciones retrospectivas:

>>> import re
>>> pat = re.compile(r'(a|b).(?<=\1)c')
>>> pat.match('aac')
<_sre.SRE_Match object; span=(0, 3), match='aac'>
>>> pat.match('bbc')
<_sre.SRE_Match object; span=(0, 3), match='bbc'>

(Contribución de Serhiy Storchaka en bpo-9179 [https://bugs.python.org/issue?@action=redirect&bpo=9179].)

El número de captura de grupos en expresiones regulares ya no se limita a 100. (Contribución de Serhiy Storchaka en bpo-22437 [https://bugs.python.org/issue?@action=redirect&bpo=22437].)

Ahora las funciones sub() y subn() reemplazan grupos que no coinciden con cadenas de caracteres vacías en lugar de lanzar una excepción. (Contribución de Serhiy Storchaka en bpo-1519638 [https://bugs.python.org/issue?@action=redirect&bpo=1519638].)

Las excepciones re.error tienen nuevos atributos, msg, pattern, pos, lineno y colno, que proporcionan una mejor información de contexto sobre el error:

>>> re.compile("""
...     (?x)
...     .++
... """)
Traceback (most recent call last):
   ...
sre_constants.error: multiple repeat at position 16 (line 3, column 7)

(Contribución de Serhiy Storchaka en bpo-22578 [https://bugs.python.org/issue?@action=redirect&bpo=22578].)

readline

Una nueva función append_history_file() se puede usar para adjuntar el número especificado de los elementos finales en el historial al archivo dado. (Contribución de Bruno Cauet en bpo-22940 [https://bugs.python.org/issue?@action=redirect&bpo=22940].)

selectors

La nueva clase DevpollSelector admite sondeos eficientes /dev/poll en Solaris. (Contribución de Giampaolo Rodola” en bpo-18931 [https://bugs.python.org/issue?@action=redirect&bpo=18931].)

shutil

Ahora la función move() acepta un argumento copy_function, permitiendo, por ejemplo, que se use la función copy() en lugar de la predeterminada copy2() si es necesario ignorar metadatos de archivo al moverlo. (Contribución de Claudiu Popa en bpo-19840 [https://bugs.python.org/issue?@action=redirect&bpo=19840].)

Ahora la función make_archive() admite el formato xztar. (Contribución de Serhiy Storchaka en bpo-5411 [https://bugs.python.org/issue?@action=redirect&bpo=5411].)

signal

En Windows, ahora la función set_wakeup_fd() también admite identificadores de socket. (Contribución de Victor Stinner en bpo-22018 [https://bugs.python.org/issue?@action=redirect&bpo=22018].)

Varias constantes SIG* en el módulo signal se convirtieron en Enums. Esto permite que los nombres significativos se impriman durante la depuración en lugar de «números mágicos» enteros. (Contribución de Giampaolo Rodola” en bpo-21076 [https://bugs.python.org/issue?@action=redirect&bpo=21076].)

smtpd

Ahora las clases SMTPServer y SMTPChannel aceptan un argumento de palabra clave decode_data para determinar si la porción DATA de la transacción SMTP se decodifica usando el códec "utf-8" o en su lugar se proporciona al método SMTPServer.process_message() como un byte de cadena de caracteres. El valor predeterminado es True por razones de compatibilidad con versiones anteriores, pero se cambiará a False en Python 3.6. Si decode_data se establece en False, el método process_message se debe preparar para aceptar argumentos de palabra clave. (Contribución de Maciej Szulik en bpo-19662 [https://bugs.python.org/issue?@action=redirect&bpo=19662].)

Ahora la clase SMTPServer anuncia la extensión 8BITMIME (RFC 6152 [https://tools.ietf.org/html/rfc6152.html]) si decode_data se establece como True. Si el cliente especifica BODY=8BITMIME en el comando MAIL, se pasa al método SMTPServer.process_message() a través de la palabra clave mail_options. (Contribución de Milan Oberkirch y R. David Murray en bpo-21795 [https://bugs.python.org/issue?@action=redirect&bpo=21795].)

Ahora la clase SMTPServer también admite la extensión SMTPUTF8 (RFC 6531 [https://tools.ietf.org/html/rfc6531.html]: correo electrónico internacionalizado). Si el cliente especificó SMTPUTF8 BODY=8BITMIME en el comando MAIL, se pasan al método SMTPServer.process_message() a través de la palabra clave mail_options. Es responsabilidad del método process_message manejar correctamente los datos SMTPUTF8. (Contribución de Milan Oberkirch en bpo-21725 [https://bugs.python.org/issue?@action=redirect&bpo=21725].)

Ahora es posible proporcionar, directamente o mediante resolución de nombres, direcciones IPv6 en el constructor SMTPServer, y hacer que se conecte correctamente. (Contribución de Milan Oberkirch en bpo-14758 [https://bugs.python.org/issue?@action=redirect&bpo=14758].)

smtplib

Un nuevo método SMTP.auth() proporciona una forma conveniente de implementar mecanismos de autenticación personalizados. (Contribución de Milan Oberkirch en bpo-15014 [https://bugs.python.org/issue?@action=redirect&bpo=15014].)

Ahora el método SMTP.set_debuglevel() acepta un nivel de depuración adicional (2), el cual habilita las marcas de tiempo en los mensajes de depuración. (Contribución de Gavin Chappell y Maciej Szulik en bpo-16914 [https://bugs.python.org/issue?@action=redirect&bpo=16914].)

Ahora los métodos SMTP.sendmail() y SMTP.send_message() admiten RFC 6531 [https://tools.ietf.org/html/rfc6531.html] (SMTPUTF8). (Contribución de Milan Oberkirch y R. David Murray en bpo-22027 [https://bugs.python.org/issue?@action=redirect&bpo=22027].)

sndhdr

Ahora las funciones what() y whathdr() retornan una namedtuple(). (Contribución de Claudiu Popa en bpo-18615 [https://bugs.python.org/issue?@action=redirect&bpo=18615].)

socket

Ahora las funciones con tiempo de espera usan un reloj monótono en lugar de un reloj del sistema. (Contribución de Victor Stinner en bpo-22043 [https://bugs.python.org/issue?@action=redirect&bpo=22043].)

Un nuevo método socket.sendfile() permite enviar un archivo a través de un socket usando la función de alto rendimiento os.sendfile() en UNIX, lo que hace que las cargas sean de 2 a 3 veces más rápido que cuando se usa el método simple socket.send(). (Contribución de Giampaolo Rodola” en bpo-17552 [https://bugs.python.org/issue?@action=redirect&bpo=17552].)

El método socket.sendall() ya no reinicia el tiempo de espera del socket cada vez que se reciben o se envían bytes. Ahora el tiempo de espera del socket es la duración total máxima para enviar todos los datos. (Contribución de Victor Stinner en bpo-23853 [https://bugs.python.org/issue?@action=redirect&bpo=23853].)

Ahora el argumento backlog del método socket.listen() es opcional. De forma predeterminada, se establece en SOMAXCONN o en 128, lo que sea menor. (Contribución de Charles-François Natali en bpo-21455 [https://bugs.python.org/issue?@action=redirect&bpo=21455].)

ssl

Soporte de memoria BIO

(Contribución de Geert Jansen en bpo-21965 [https://bugs.python.org/issue?@action=redirect&bpo=21965].)

Se ha agregado la nueva clase SSLObject para proporcionar soporte del protocolo SSL para los casos en que las capacidades de E/S de red de SSLSocket no son necesarias o no son óptimas. SSLObject representa una instancia del protocolo SSL pero no implementa ningún método de E/S de red y, en su lugar, proporciona una interfaz de búfer de memoria. La nueva clase MemoryBIO se puede usar para pasar datos entre Python y una instancia del protocolo SSL.

El soporte de la memoria BIO SSL está destinado principalmente para ser usado en frameworks que implementan E/S asíncronas para las cuales el modelo de preparación («select/poll») de SSLSocket es ineficiente.

Un nuevo método SSLContext.wrap_bio() se puede usar para crear una nueva instancia SSLObject.

Soporte de negociación de protocolo de capa de aplicación

(Contribución de Benjamin Peterson en bpo-20188 [https://bugs.python.org/issue?@action=redirect&bpo=20188].)

Donde está presente el soporte de OpenSSL, ahora el módulo ssl implementa la extensión TLS Application-Layer Protocol Negotiation como se describe en RFC 7301 [https://tools.ietf.org/html/rfc7301.html].

El nuevo método SSLContext.set_alpn_protocols() se puede usar para especificar qué protocolos deben anunciar un socket durante el protocolo de enlace TLS.

El nuevo método SSLSocket.selected_alpn_protocol() retorna el protocolo que se seleccionó durante el protocolo de enlace TLS. La bandera HAS_ALPN indica si el soporte ALPN está presente.

Otros cambios

Hay un nuevo método SSLSocket.version() para consultar la versión actual del protocolo en uso. (Contribución de Antoine Pitrou en bpo-20421 [https://bugs.python.org/issue?@action=redirect&bpo=20421].)

Ahora la clase SSLSocket implementa un método SSLSocket.sendfile(). (Contribución de Giampaolo Rodola” en bpo-17552 [https://bugs.python.org/issue?@action=redirect&bpo=17552].)

Ahora el método SSLSocket.send() lanza la excepción ssl.SSLWantReadError o ssl.SSLWantWriteError en un socket sin bloqueo si la operación se bloquearía. Anteriormente, retornaría 0. (Contribución de Nikolaus Rath en bpo-20951 [https://bugs.python.org/issue?@action=redirect&bpo=20951].)

Ahora la función cert_time_to_seconds() interpreta la hora de entrada como UTC y no como hora local, por RFC 5280 [https://tools.ietf.org/html/rfc5280.html]. Además, el valor de retorno siempre es un int. (Contribución de Akira Li en bpo-19940 [https://bugs.python.org/issue?@action=redirect&bpo=19940].)

Los nuevos métodos SSLObject.shared_ciphers() y SSLSocket.shared_ciphers() retornan la lista de cifrados enviados por el cliente durante el protocolo de enlace. (Contribución de Benjamin Peterson en bpo-23186 [https://bugs.python.org/issue?@action=redirect&bpo=23186].)

Los métodos SSLSocket.do_handshake(), SSLSocket.read(), SSLSocket.shutdown() y SSLSocket.write() de la clase SSLSocket ya no reinician el tiempo de espera del socket cada vez que se reciben o se envían bytes. Ahora el tiempo de espera del socket es la duración total máxima del método. (Contribución de Victor Stinner en bpo-23853 [https://bugs.python.org/issue?@action=redirect&bpo=23853].)

Ahora la función match_hostname() admite la coincidencia de direcciones IP. (Contribución de Antoine Pitrou en bpo-23239 [https://bugs.python.org/issue?@action=redirect&bpo=23239].)

sqlite3

Ahora la clase Row admite totalmente el protocolo de secuencia, en particular la iteración reversed() y la indexación segmentada. (Contribución de Claudiu Popa en bpo-10203 [https://bugs.python.org/issue?@action=redirect&bpo=10203]; de Lucas Sinclair, Jessica McKellar, y Serhiy Storchaka en bpo-13583 [https://bugs.python.org/issue?@action=redirect&bpo=13583].)

subprocess

Se agregó la nueva función run(). Ejecuta el comando especificado y retorna un objeto CompletedProcess, el cual describe un proceso terminado. La nueva API es más consistente y es el enfoque recomendado para invocar subprocesos en código Python que no necesita mantener la compatibilidad con versiones anteriores de Python. (Contribución de Thomas Kluyver en bpo-23342 [https://bugs.python.org/issue?@action=redirect&bpo=23342].)

Ejemplos:

>>> subprocess.run(["ls", "-l"])  # doesn't capture output
CompletedProcess(args=['ls', '-l'], returncode=0)

>>> subprocess.run("exit 1", shell=True, check=True)
Traceback (most recent call last):
  ...
subprocess.CalledProcessError: Command 'exit 1' returned non-zero exit status 1

>>> subprocess.run(["ls", "-l", "/dev/null"], stdout=subprocess.PIPE)
CompletedProcess(args=['ls', '-l', '/dev/null'], returncode=0,
stdout=b'crw-rw-rw- 1 root root 1, 3 Jan 23 16:23 /dev/null\n')

sys

Una nueva función set_coroutine_wrapper() permite configurar un enlace global que será llamado siempre que un objeto corrutina sea creado por una función async def. Una función correspondiente get_coroutine_wrapper() se puede usar para obtener un contenedor configurado actualmente. Ambas funciones son provisionales y se destinan solo para propósitos de depuración. (Contribución de Yury Selivanov en bpo-24017 [https://bugs.python.org/issue?@action=redirect&bpo=24017].)

Una nueva función is_finalizing() se puede usar para verificar si el intérprete de Python se está apagando. (Contribución de Antoine Pitrou en bpo-22696 [https://bugs.python.org/issue?@action=redirect&bpo=22696].)

sysconfig

Ahora el nombre del directorio de los scripts del usuario en Windows incluye los dos primeros componentes de la versión de Python. (Contribución de Paul Moore en bpo-23437 [https://bugs.python.org/issue?@action=redirect&bpo=23437].)

tarfile

Ahora el argumento mode de la función open() acepta "x" para solicitar una creación exclusiva. (Contribución de Berker Peksag en bpo-21717 [https://bugs.python.org/issue?@action=redirect&bpo=21717].)

Ahora los métodos TarFile.extractall() y TarFile.extract() toman un argumento de palabra clave numeric_owner. Si se establece como True, los archivos y directorios extraídos serán propiedad de los números uid y gid del archivo tar. Si se establece como False (el valor predeterminado y el comportamiento en versiones anteriores a la 3.5), serán propiedad del usuario y el grupo nombrados en el archivo tar. (Contribución de Michael Vogt y Eric Smith en bpo-23193 [https://bugs.python.org/issue?@action=redirect&bpo=23193].)

Ahora TarFile.list() acepta un argumento de palabra clave opcional members que se puede establecer en un subconjunto de la lista retornada por TarFile.getmembers(). (Contribución de Serhiy Storchaka en bpo-21549 [https://bugs.python.org/issue?@action=redirect&bpo=21549].)

threading

Ahora los métodos Lock.acquire() y RLock.acquire() usan un reloj monótono para la administración del tiempo de espera. (Contribución de Victor Stinner en bpo-22043 [https://bugs.python.org/issue?@action=redirect&bpo=22043].)

time

Ahora la función monotonic() siempre está disponible. (Contribución de Victor Stinner en bpo-22043 [https://bugs.python.org/issue?@action=redirect&bpo=22043].)

timeit

Una nueva opción de línea de comando -u o --unit=U se puede usar para especificar la unidad de tiempo para la salida del temporizador. Las opciones que se admiten son usec, msec o sec. (Contribución de Julian Gindi en bpo-18983 [https://bugs.python.org/issue?@action=redirect&bpo=18983].)

La función timeit() tiene un nuevo parámetro globals para especificar el espacio de nombres donde el código se ejecutará. (Contribución de Ben Roberts en bpo-2527 [https://bugs.python.org/issue?@action=redirect&bpo=2527].)

tkinter

El módulo tkinter._fix que se usaba para configurar el entorno Tcl/Tk en Windows se reemplazó por una función privada en el módulo _tkinter que no hace cambios permanentes en las variables de entorno. (Contribución de Zachary Ware en bpo-20035 [https://bugs.python.org/issue?@action=redirect&bpo=20035].)

traceback

Las nuevas funciones walk_stack() y walk_tb() atraviesan convenientemente objetos de marco y rastreo. (Contribución de Robert Collins en bpo-17911 [https://bugs.python.org/issue?@action=redirect&bpo=17911].)

Nuevas clases ligeras: TracebackException, StackSummary y FrameSummary. (Contribución de Robert Collins en bpo-17911 [https://bugs.python.org/issue?@action=redirect&bpo=17911].)

Ahora las funciones print_tb() y print_stack() admiten valores negativos para el argumento limit. (Contribución de Dmitry Kazakov en bpo-22619 [https://bugs.python.org/issue?@action=redirect&bpo=22619].)

types

Una nueva función coroutine() para transformar un iterador generador y objetos generator-like en aguardables. (Contribución de Yury Selivanov en bpo-24017 [https://bugs.python.org/issue?@action=redirect&bpo=24017].)

Un nuevo tipo llamado CoroutineType, el cual se usa para objetos coroutine creados por funciones async def. (Contribución de Yury Selivanov en bpo-24400 [https://bugs.python.org/issue?@action=redirect&bpo=24400].)

unicodedata

Ahora el módulo unicodedata usa datos de Unicode 8.0.0 [http://unicode.org/versions/Unicode8.0.0/].

unittest

Ahora el método TestLoader.loadTestsFromModule() acepta un solo argumento de palabra clave pattern que se pasa a load_tests como el tercer argumento. Ahora los paquetes encontrados se verifican en busca de load_tests independientemente de si su ruta coincide con pattern, porque es imposible que el nombre de un paquete coincida con el modelo predeterminado. (Contribución de Robert Collins y Barry A. Warsaw en bpo-16662 [https://bugs.python.org/issue?@action=redirect&bpo=16662].)

Ahora los errores de descubrimiento de unittest se exponen en el atributo TestLoader.errors de la instancia TestLoader. (Contribución de Robert Collins en bpo-19746 [https://bugs.python.org/issue?@action=redirect&bpo=19746].)

Una nueva opción de línea de comando --locals muestra variables locales en rastreo. (Contribución de Robert Collins en bpo-22936 [https://bugs.python.org/issue?@action=redirect&bpo=22936].)

unittest.mock

La clase Mock tiene las siguientes mejoras:

El constructor de la clase tiene un nuevo parámetro unsafe, que hace que los objetos simulados lancen AttributeError en los nombres de atributo que comienzan con "assert". (Contribución de Kushal Das en bpo-21238 [https://bugs.python.org/issue?@action=redirect&bpo=21238].)

Un nuevo método Mock.assert_not_called() para verificar si se llamó el objeto simulado. (Contribución de Kushal Das en bpo-21262 [https://bugs.python.org/issue?@action=redirect&bpo=21262].)

Ahora la clase MagicMock admite los operadores __truediv__(), __divmod__() y __matmul__(). (Contribución de Johannes Baiter en bpo-20968 [https://bugs.python.org/issue?@action=redirect&bpo=20968] y de Håkan Lövdahl en bpo-23581 [https://bugs.python.org/issue?@action=redirect&bpo=23581] y bpo-23568 [https://bugs.python.org/issue?@action=redirect&bpo=23568].)

Ya no es necesario pasar explícitamente create=True a la función patch() cuando se parchean los nombres incorporados. (Contribución de Kushal Das en bpo-17660 [https://bugs.python.org/issue?@action=redirect&bpo=17660].)

urllib

Una nueva clase request.HTTPPasswordMgrWithPriorAuth permite que se administren las credenciales de autenticación básica HTTP para eliminar el manejo innecesario de respuestas 401 o enviar credenciales incondicionalmente en la primera solicitud para comunicarse con los servidores que retornen una respuesta 404 en lugar de un 401 si el encabezado Authorization no se envía. (Contribución de Matej Cepl en bpo-19494 [https://bugs.python.org/issue?@action=redirect&bpo=19494] y de Akshit Khurana en bpo-7159 [https://bugs.python.org/issue?@action=redirect&bpo=7159].)

Un nuevo argumento quote_via para la función parse.urlencode() proporciona una forma de controlar la codificación de las partes de la consulta si es necesario. (Contribución de Samwyse y Arnon Yaari en bpo-13866 [https://bugs.python.org/issue?@action=redirect&bpo=13866].)

La función request.urlopen() acepta un objeto ssl.SSLContext como un argumento context, el cual se usará para la conexión HTTPS. (Contribución de Alex Gaynor en bpo-22366 [https://bugs.python.org/issue?@action=redirect&bpo=22366].)

Se actualizó parse.urljoin() para usar la semántica RFC 3986 [https://tools.ietf.org/html/rfc3986.html] para la resolución de URL relativas, en lugar de RFC 1808 [https://tools.ietf.org/html/rfc1808.html] y RFC 2396 [https://tools.ietf.org/html/rfc2396.html]. (Contribución de Demian Brecht y Senthil Kumaran en bpo-22118 [https://bugs.python.org/issue?@action=redirect&bpo=22118].)

wsgiref

Ahora el argumento headers del constructor de la clase headers.Headers es opcional. (Contribución de Pablo Torres Navarrete y SilentGhost en bpo-5800 [https://bugs.python.org/issue?@action=redirect&bpo=5800].)

xmlrpc

Ahora la clase client.ServerProxy admite el protocolo context manager. (Contribución de Claudiu Popa en bpo-20627 [https://bugs.python.org/issue?@action=redirect&bpo=20627].)

Ahora el constructor de client.ServerProxy acepta una instancia opcional ssl.SSLContext. (Contribución de Alex Gaynor en bpo-22960 [https://bugs.python.org/issue?@action=redirect&bpo=22960].)

xml.sax

Ahora los analizadores SAX admiten un flujo de caracteres del objeto xmlreader.InputSource. (Contribución de Serhiy Storchaka en bpo-2175 [https://bugs.python.org/issue?@action=redirect&bpo=2175].)

Ahora parseString() acepta una instancia str. (Contribución de Serhiy Storchaka en bpo-10590 [https://bugs.python.org/issue?@action=redirect&bpo=10590].)

zipfile

Ahora la salida ZIP se puede escribir en flujos inescrutables. (Contribución de Serhiy Storchaka en bpo-23252 [https://bugs.python.org/issue?@action=redirect&bpo=23252].)

Ahora el argumento mode del método ZipFile.open() acepta "x" para solicitar una creación exclusiva. (Contribución de Serhiy Storchaka en bpo-21717 [https://bugs.python.org/issue?@action=redirect&bpo=21717].)

Otros cambios a nivel de módulo

Ahora muchas funciones en los módulos mmap, ossaudiodev, socket, ssl y codecs aceptan objetos de tipo bytes que se pueden escribir. (Contribución de Serhiy Storchaka en bpo-23001 [https://bugs.python.org/issue?@action=redirect&bpo=23001].)

Optimizaciones

La función os.walk() se aceleró de 3 a 5 veces en los sistemas POSIX y de 7 a 20 veces en Windows. Esto se hizo usando la nueva función os.scandir(), el cual expone la información del archivo de las llamadas al sistema readdir o FindFirstFile/FindNextFile. (Contribución de Ben Hoyt con ayuda de Victor Stinner en bpo-23605 [https://bugs.python.org/issue?@action=redirect&bpo=23605].)

La construcción de bytes(int) (llenado con cero bytes) es más rápida y usa menos memoria para objetos grandes. Se usa calloc() en lugar de malloc() para asignar memoria para estos objetos. (Contribución de Victor Stinner en bpo-21233 [https://bugs.python.org/issue?@action=redirect&bpo=21233].)

Algunas operaciones en ipaddress IPv4Network y IPv6Network se aceleraron masivamente, tal como subnets(), supernet(), summarize_address_range(), collapse_addresses(). La velocidad puede variar de 3 a 15 veces. (Contribución de Antoine Pitrou, Michel Albert y Markus en bpo-21486 [https://bugs.python.org/issue?@action=redirect&bpo=21486], bpo-21487 [https://bugs.python.org/issue?@action=redirect&bpo=21487], bpo-20826 [https://bugs.python.org/issue?@action=redirect&bpo=20826], bpo-23266 [https://bugs.python.org/issue?@action=redirect&bpo=23266].)

Se optimizó pickling de objetos ipaddress para producir una salida significativamente menor. (Contribución de Serhiy Storchaka en bpo-23133 [https://bugs.python.org/issue?@action=redirect&bpo=23133].)

Ahora muchas operaciones en io.BytesIO son de 50% a 100% más rápidas. (Contribución de Serhiy Storchaka en bpo-15381 [https://bugs.python.org/issue?@action=redirect&bpo=15381] y de David Wilson en bpo-22003 [https://bugs.python.org/issue?@action=redirect&bpo=22003].)

Ahora la función marshal.dumps() es más rápida: 65–85% en las versiones 3 y 4, 20–25% en las versiones 0 a 2 con datos típicos, y hasta 5 veces en el mejor de los casos. (Contribución de Serhiy Storchaka en bpo-20416 [https://bugs.python.org/issue?@action=redirect&bpo=20416] y bpo-23344 [https://bugs.python.org/issue?@action=redirect&bpo=23344].)

Ahora el codificador UTF-32 es de 3 a 7 veces más rápido. (Contribución de Serhiy Storchaka en bpo-15027 [https://bugs.python.org/issue?@action=redirect&bpo=15027].)

Ahora las expresiones regulares se analizan hasta un 10% más rápido. (Contribución de Serhiy Storchaka en bpo-19380 [https://bugs.python.org/issue?@action=redirect&bpo=19380].)

Se optimizó la función json.dumps() para ejecutarse con ensure_ascii=False tan rápido como con ensure_ascii=True. (Contribución de Naoki Inada en bpo-23206 [https://bugs.python.org/issue?@action=redirect&bpo=23206].)

Las funciones PyObject_IsInstance() y PyObject_IsSubclass() se aceleraron en el caso común de que el segundo argumento tenga type como su metaclase. (Contribución de Georg Brandl en bpo-22540 [https://bugs.python.org/issue?@action=redirect&bpo=22540].)

Se mejoró ligeramente el almacenamiento en caché del método, lo que arrojó una mejora del rendimiento de hasta un 5% en algunos puntos de referencia. (Contribución de Antoine Pitrou en bpo-22847 [https://bugs.python.org/issue?@action=redirect&bpo=22847].)

Ahora los objetos del módulo random usan un 50% menos de memoria en compilaciones de 64 bits. (Contribución de Serhiy Storchaka en bpo-23488 [https://bugs.python.org/issue?@action=redirect&bpo=23488].)

Las llamadas getter de property() son hasta un 25% más rápidas. (Contribución de Joe Jevnik en bpo-23910 [https://bugs.python.org/issue?@action=redirect&bpo=23910].)

Ahora la instanciación de fractions.Fraction es hasta un 30% más rápida. (Contribución de Stefan Behnel en bpo-22464 [https://bugs.python.org/issue?@action=redirect&bpo=22464].)

Ahora los métodos de cadena de caracteres find(), rfind(), split(), partition() y el operador in son significativamente más rápidos para buscar subcadenas de 1 carácter. (Contribución de Serhiy Storchaka en bpo-23573 [https://bugs.python.org/issue?@action=redirect&bpo=23573].)

Cambios en la compilación y la API de C

Se agregaron las nuevas funciones calloc:

PyMem_RawCalloc(),

PyMem_Calloc(),

PyObject_Calloc().

(Contribución de Victor Stinner en bpo-21233 [https://bugs.python.org/issue?@action=redirect&bpo=21233].)

Nuevas funciones auxiliares de codificación/decodificación:

Py_DecodeLocale() (reemplazó _Py_char2wchar()),

Py_EncodeLocale() (reemplazó _Py_wchar2char()).

(Contribución de Victor Stinner en bpo-18395 [https://bugs.python.org/issue?@action=redirect&bpo=18395].)

Una nueva función PyCodec_NameReplaceErrors() para reemplazar el error de codificación unicode con \N{...} escapes. (Contribución de Serhiy Storchaka en bpo-19676 [https://bugs.python.org/issue?@action=redirect&bpo=19676].)

Una nueva función PyErr_FormatV() similar a PyErr_Format(), pero acepta un argumento va_list. (Contribución de Antoine Pitrou en bpo-18711 [https://bugs.python.org/issue?@action=redirect&bpo=18711].)

Una nueva excepción PyExc_RecursionError. (Contribución de Georg Brandl en bpo-19235 [https://bugs.python.org/issue?@action=redirect&bpo=19235].)

Se introdujeron las nuevas funciones PyModule_FromDefAndSpec(), PyModule_FromDefAndSpec2() y PyModule_ExecDef() por PEP 489 [https://www.python.org/dev/peps/pep-0489] – inicialización del módulo de extensión multifase. (Contribución de Petr Viktorin en bpo-24268 [https://bugs.python.org/issue?@action=redirect&bpo=24268].)

Nuevas funciones PyNumber_MatrixMultiply() y PyNumber_InPlaceMatrixMultiply() para realizar la multiplicación de matrices. (Contribución de Benjamin Peterson en bpo-21176 [https://bugs.python.org/issue?@action=redirect&bpo=21176]. Consultar también PEP 465 [https://www.python.org/dev/peps/pep-0465] para más detalles.)

Ahora el espacio PyTypeObject.tp_finalize es parte de la ABI estable.

Ahora las compilaciones de Windows requieren Microsoft Visual C++ 14.0, que está disponible como parte de Visual Studio 2015 [https://www.visualstudio.com/].

Ahora los módulos de extensión incluyen una etiqueta de información de la plataforma en su nombre de archivo en algunas plataformas (la etiqueta es opcional y CPython importará las extensiones sin ella, aunque si la etiqueta está presente y no coincide, no se cargará la extensión):

En Linux, los nombres de archivo del módulo de extensión termina con .cpython-<major><minor>m-<architecture>-<os>.pyd:

<major> es el número principal de la versión de Python; para Python 3.5 este es 3.

<minor> es el número menor de la versión de Python; para Python 3.5 este es 5.

<architecture> es la arquitectura de hardware para la que se construyó el módulo de extensión. Es más común i386 para plataformas Intel de 32 bits o x86_64 para plataformas Intel (y AMD) de 64 bits.

<os> siempre es linux-gnu, excepto para las extensiones que se crearon para comunicarse con la ABI de 32 bits en plataformas de 64 bits, en cuyo caso es linux-gnu32 (y <architecture> será x86_64).

En Windows, los nombres de archivo del módulo de extensión termina con <debug>.cp<major><minor>-<platform>.pyd:

<major> es el número principal de la versión de Python; para Python 3.5 este es 3.

<minor> es el número menor de la versión de Python; para Python 3.5 este es 5.

<platform> es la plataforma para la que se construyó el módulo de extensión, ya sea win32 para Win32, win_amd64 para Win64, win_ia64 para Windows Itanium 64 y win_arm para Windows con ARM.

Si está integrado en el modo de depuración, <debug> será _d, de lo contrario estará en blanco.

En plataformas OS X, ahora los nombres de archivo del módulo de extensión terminan con -darwin.so.

En todas las demás plataformas, los nombres de archivo del módulo de extensión son los mismos que en Python 3.4.

Obsoleto

Nuevas palabras clave

No se recomienda usarse async y await como nombres de variable, clase, función o módulo. Se introdujo por PEP 492 [https://www.python.org/dev/peps/pep-0492] en Python 3.5, se convertirán en palabras clave adecuadas en Python 3.7.

Comportamiento obsoleto de Python

Al lanzar la excepción StopIteration dentro de un generador ahora se generará un PendingDeprecationWarning silencioso, el cual se convertirá en una advertencia de deprecación no silenciosa en Python 3.6 y activará un RuntimeError en Python 3.7. Consultar PEP 479: Cambiar el gestor de StopIteration dentro de generadores para más detalles.

Sistemas operativos no compatibles

Windows XP ya no es compatible con Microsoft, por lo tanto, según PEP 11 [https://www.python.org/dev/peps/pep-0011], CPython 3.5 oficialmente ya no es compatible con este sistema operativo.

Módulos, funciones y métodos obsoletos de Python

Ahora el módulo formatter se ha graduado a su deprecación completa y aún está programada para su eliminación en Python 3.6.

La función asyncio.async() es obsoleta en favor de ensure_future().

En el pasado, el módulo smtpd siempre ha decodificado la porción DATA de los mensajes de correo electrónico usando el códec utf-8. Ahora esto se puede controlar con la nueva palabra clave decode_data en SMTPServer. El valor predeterminado es True, pero éste está obsoleto. Especificar la palabra clave decode_data con un valor apropiado para evitar la advertencia de deprecación.

Está obsoleto asignar valores directamente en key, value y coded_value en los objetos de http.cookies.Morsel. Usar en su lugar el método set(). Además, el parámetro no documentado LegalChars de set() está obsoleto y ahora se ignora.

Pasar una cadena de caracteres de formato como argumento de palabra clave format_string al método format() de la clase string.Formatter se ha quedado obsoleto. (Contribución de Serhiy Storchaka en bpo-23671 [https://bugs.python.org/issue?@action=redirect&bpo=23671].)

Ahora las funciones platform.dist() y platform.linux_distribution() están obsoletas. Las distribuciones de Linux usan demasiadas formas diferentes de describirse a sí mismas, así que la funcionalidad se deja a un paquete. (Contribución de Vajrasky Kok y Berker Peksag en bpo-1322 [https://bugs.python.org/issue?@action=redirect&bpo=1322].)

Los métodos from_function y from_builtin previamente no documentados de inspect.Signature están obsoletos. Utilizar en su lugar el nuevo método Signature.from_callable(). (Contribución de Yury Selivanov en bpo-24248 [https://bugs.python.org/issue?@action=redirect&bpo=24248].)

La función inspect.getargspec() está obsoleta y programada para ser eliminada en Python 3.6. (Consultar bpo-20438 [https://bugs.python.org/issue?@action=redirect&bpo=20438] para más detalles.)

Las funciones inspect getfullargspec(), getcallargs() y formatargspec() están obsoletas en favor de la API inspect.signature(). (Contribución de Yury Selivanov en bpo-20438 [https://bugs.python.org/issue?@action=redirect&bpo=20438].)

Las funciones getargvalues() y formatargvalues() se marcaron inadvertidamente como obsoletas con el lanzamiento de Python 3.5.0.

Ahora el uso de la bandera re.LOCALE con patrones str o re.ASCII está obsoleto. (Contribución de Serhiy Storchaka en bpo-22407 [https://bugs.python.org/issue?@action=redirect&bpo=22407].)

El uso de secuencias especiales no reconocidas que consisten en '\' y una letra ASCII en patrones de expresión regular y patrones de reemplazo ahora lanza una advertencia de deprecación y estará prohibido en Python 3.6. (Contribución de Serhiy Storchaka en bpo-23622 [https://bugs.python.org/issue?@action=redirect&bpo=23622].)

Ahora el argumento predeterminado no documentado y no oficial use_load_tests del método unittest.TestLoader.loadTestsFromModule() está obsoleto e ignorado. (Contribución de Robert Collins y Barry A. Warsaw en bpo-16662 [https://bugs.python.org/issue?@action=redirect&bpo=16662].)

Eliminado

APIs y características eliminadas

Se eliminaron las siguientes APIs y características obsoletas y anteriormente obsoletas:

Se eliminó el atributo __version__ del paquete de correo electrónico. No se envió el código de correo electrónico por separado de stdlib durante mucho tiempo, y la cadena de caracteres __version__ no se actualizó en las últimas versiones.

La clase interna Netrc en el módulo ftplib quedó obsoleta en la versión 3.4 y ahora se eliminó. (Contribución de Matt Chaput en bpo-6623 [https://bugs.python.org/issue?@action=redirect&bpo=6623].)

Se eliminó el concepto de los archivos .pyo.

La clase JoinableQueue en el módulo provisional asyncio quedó obsoleto en la versión 3.4.4 y ahora se eliminó. (Contribución de A. Jesse Jiryu Davis en bpo-23464 [https://bugs.python.org/issue?@action=redirect&bpo=23464].)

Portando a Python 3.5

Esta sección enumera cambios descritos anteriormente y otras correcciones de errores que pueden requerir cambios en tu código.

Cambios en el comportamiento de Python

Debido a un descuido, erróneamente en anteriores versiones de Python aceptaron la siguiente sintaxis:

f(1 for x in [1], *args)
f(1 for x in [1], **kwargs)

Ahora Python 3.5 lanza correctamente un SyntaxError, ya que las expresiones generadoras deben ponerse entre paréntesis si no son el único argumento de una función.

Cambios en la API de Python

PEP 475 [https://www.python.org/dev/peps/pep-0475]: Ahora se reintentan las llamadas al sistema cuando se interrumpen por una señal en lugar de lanzar InterruptedError si el gestor de señales de Python no lanza una excepción.

Antes de Python 3.5, se consideraba falso un objeto datetime.time si representaba la medianoche en UTC. Este comportamiento se consideraba oscuro y propenso a errores y se eliminó en Python 3.5. Consultar bpo-13936 [https://bugs.python.org/issue?@action=redirect&bpo=13936] para más detalles.

Ahora el método ssl.SSLSocket.send() lanza ya sea ssl.SSLWantReadError o ssl.SSLWantWriteError en un socket sin bloqueo si la operación se bloqueara. Anteriormente, retornaría 0. (Contribución de Nikolaus Rath en bpo-20951 [https://bugs.python.org/issue?@action=redirect&bpo=20951].)

Ahora el atributo __name__ de los generadores se establece desde el nombre de la función en lugar de establecerse desde el nombre del código. Usar gen.gi_code.co_name para recuperar el nombre del código. También los generadores tienen un nuevo atributo __qualname__, el nombre calificado, el cual se utiliza ahora para la representación de un generador (repr(gen)). (Contribución de Victor Stinner en bpo-21205 [https://bugs.python.org/issue?@action=redirect&bpo=21205].)

Se eliminaron el argumento y modo obsoleto «strict» de HTMLParser, HTMLParser.error() y la excepción HTMLParserError. (Contribución de Ezio Melotti en bpo-15114 [https://bugs.python.org/issue?@action=redirect&bpo=15114].) Ahora el argumento convert_charrefs de HTMLParser es True como valor predeterminado. (Contribución de Berker Peksag en bpo-21047 [https://bugs.python.org/issue?@action=redirect&bpo=21047].)

Aunque no es parte formalmente de la API, vale la pena señalar con fines de portabilidad (es decir: pruebas de reparación) que ahora los mensajes de error que anteriormente tenían el formato «“sometype” no es compatible con el protocolo búfer» son del formato «se requiere bytes-like object, no “sometype”». (Contribución de Ezio Melotti en bpo-16518 [https://bugs.python.org/issue?@action=redirect&bpo=16518].)

Si el directorio actual se establece en un directorio que ya no existe entonces ya no se lanzará FileNotFoundError y en su lugar find_spec() retornará None sin almacenamiento en caché None en sys.path_importer_cache, el cual es diferente al caso típico (bpo-22834 [https://bugs.python.org/issue?@action=redirect&bpo=22834]).

El código de estado HTTP y los mensajes de http.client y http.server se refactorizaron en una enumeración HTTPStatus. Los valores en http.client y http.server permanecen disponibles para compatibilidad con versiones anteriores. (Contribución de Demian Brecht en bpo-21793 [https://bugs.python.org/issue?@action=redirect&bpo=21793].)

Cuando un cargador de importación define importlib.machinery.Loader.exec_module(), ahora se espera que también defina create_module() (ahora lanza un DeprecationWarning, será un error en Python 3.6). Si el cargador hereda de importlib.abc.Loader entonces no hay nada que hacer, de lo contrario simplemente defina create_module() para retornar None. (Contribución de Brett Cannon en bpo-23014 [https://bugs.python.org/issue?@action=redirect&bpo=23014].)

La función re.split() siempre ignoraba las coincidencias de patrones vacías, así que el patrón "x*" funcionaba igual que "x+" y el patrón "\b" nunca funcionó. Ahora re.split() lanza una advertencia si el patrón puede coincidir con una cadena de caracteres vacía. Para compatibilidad, usar patrones que nunca coincidan con una cadena vacía (p. ej. "x+" en lugar de "x*"). Ahora los patrones que solo pueden coincidir con una cadena vacía (como "\b") lanzan un error. (Contribución de Serhiy Storchaka en bpo-22818 [https://bugs.python.org/issue?@action=redirect&bpo=22818].)

La interfaz similar a diccionarios http.cookies.Morsel se ha hecho autoconsistente: ahora la comparación de morsel toma en cuenta key y value, ahora copy() da como resultado en una instancia Morsel en lugar de un dict, y ahora update() lanzará una excepción si alguna de las claves del diccionario de actualización no es válida. Además, el parámetro no documentado LegalChars de set() está obsoleto y ahora se ignora. (Contribución de Demian Brecht en bpo-2211 [https://bugs.python.org/issue?@action=redirect&bpo=2211].)

PEP 488 [https://www.python.org/dev/peps/pep-0488] eliminó los archivos .pyo de Python e introdujo la etiqueta opcional opt- en los nombres de archivo .pyc. La función importlib.util.cache_from_source() ganó un parámetro optimization para ayudar a controlar la etiqueta opt-. Debido a esto, ahora el parámetro debug_override de la función está obsoleto. También los archivos .pyo ya no se admiten como un argumento de archivo para el intérprete de Python, y por lo tanto, no tienen ningún propósito cuando se distribuyen por sí mismos (es decir, distribución de código sin fuente). Debido al hecho de que el número mágico para bytecode se cambió en Python 3.5, todos los archivos antiguos .pyo de versiones anteriores de Python no son válidos independientemente de este PEP.

Ahora el módulo socket exporta la constante CAN_RAW_FD_FRAMES en Linux 3.6 y versiones superiores.

Ahora la función ssl.cert_time_to_seconds() interpreta la hora de entrada como UTC y no como hora local, por RFC 5280 [https://tools.ietf.org/html/rfc5280.html]. Además, el valor de retorno siempre es un int. (Contribución de Akira Li en bpo-19940 [https://bugs.python.org/issue?@action=redirect&bpo=19940].)

Ahora la herramienta pygettext.py usa el formato estándar +NNNN para zonas horarias en el encabezado POT-Creation-Date.

Ahora el módulo smtplib usa sys.stderr en lugar de la variable anterior de nivel de módulo stderr para la salida de depuración. Si tu programa (de prueba) depende de parchear la variable de nivel de mundo para capturar la salida de depuración, necesitarás actualizarlo para capturar sys.stderr en su lugar.

Los métodos str.startswith() y str.endswith() ya no retornan True cuando encuentran la cadena de caracteres vacía y los índices están completamente fuera de rango. (Contribución de Serhiy Storchaka en bpo-24284 [https://bugs.python.org/issue?@action=redirect&bpo=24284].)

Ahora la función inspect.getdoc() retorna cadenas de documentación que se heredaron de clases base. Ya no es necesario duplicar las cadenas de documentación si la documentación que se heredó es apropiada. Para suprimir una cadena que se heredó, se debe especificar una cadena vacía (o se puede completar la documentación). Este cambio afecta la salida del módulo pydoc y la función help(). (Contribución de Serhiy Storchaka en bpo-15582 [https://bugs.python.org/issue?@action=redirect&bpo=15582].)

Ahora las llamadas anidadas functools.partial() se aplanan. Si se confiaba en el comportamiento anterior, ahora se puede agregar un atributo a un objeto functools.partial() o se puede crear una subclase de functools.partial(). (Contribución de Alexander Belopolsky en bpo-7830 [https://bugs.python.org/issue?@action=redirect&bpo=7830].)

Cambios en la API de C

Se eliminó el miembro no documentado format de la estructura (no pública) PyMemoryViewObject. Todas las extensiones que se basan en las partes relevantes en memoryobject.h se debe recompilar.

La estructura PyMemAllocator se renombró a PyMemAllocatorEx y se agregó un nuevo campo calloc.

Se eliminó la macro no documentada PyObject_REPR que filtró referencias. Usar el carácter de formato %R en funciones similares a PyUnicode_FromFormat() para formatear repr() del objeto. (Contribución de Serhiy Storchaka en bpo-22453 [https://bugs.python.org/issue?@action=redirect&bpo=22453].)

Debido a que la falta del atributo __module__ rompe pickling y la introspección, ahora se lanza una advertencia de deprecación para los tipos integrados sin el atributo __module__. Este sería un AttributeError en el futuro. (Contribución de Serhiy Storchaka en bpo-20204 [https://bugs.python.org/issue?@action=redirect&bpo=20204].)

Como parte de la implementación de PEP 492 [https://www.python.org/dev/peps/pep-0492], el espacio tp_reserved de PyTypeObject se reemplazó con un espacio tp_as_async. Consultar Objetos corrutina para nuevos tipos, estructuras y funciones.

Cambios notables en Python 3.5.4

Nuevo objetivo de compilación make regen-all

Para simplificar la compilación cruzada y asegurar que CPython se pueda compilar de manera confiable sin requerir que una versión existente de Python ya esté disponible, el sistema de compilación basado en herramientas automáticas ya no intenta volver a compilar implícitamente los archivos generados en función de los tiempos de modificación de los archivos.

En su lugar, se agregó un nuevo comando make regen-all para forzar la regeneración de estos archivos cuando se desee (p. ej. después de que ya se haya creado una versión inicial de Python basada en las versiones pregeneradas).

También se definen objetivos de regeneración más selectivos - consultar Makefile.pre.in [https://github.com/python/cpython/tree/3.9/Makefile.pre.in] para más detalles.

(Contribución de Victor Stinner en bpo-23404 [https://bugs.python.org/issue?@action=redirect&bpo=23404].)

Nuevo en la versión 3.5.4.

Eliminación del objetivo de compilación make touch

Se eliminó el objetivo de compilación make touch que anteriormente se usaba para solicitar la regeneración implícita de los archivos generados mediante la actualización de sus tiempos de modificación.

Se reemplazó por el nuevo objetivo make regen-all.

(Contribución de Victor Stinner en bpo-23404 [https://bugs.python.org/issue?@action=redirect&bpo=23404].)

Distinto en la versión 3.5.4.

What’s New In Python 3.4

Author

R. David Murray <rdmurray@bitdance.com> (Editor)

This article explains the new features in Python 3.4, compared to 3.3. Python 3.4 was released on March 16, 2014. For full details, see the changelog [https://docs.python.org/3.4/whatsnew/changelog.html].

Ver también

PEP 429 [https://www.python.org/dev/peps/pep-0429] – Python 3.4 Release Schedule

Summary – Release Highlights

New syntax features:

No new syntax features were added in Python 3.4.

Other new features:

pip should always be available (PEP 453 [https://www.python.org/dev/peps/pep-0453]).

Newly created file descriptors are non-inheritable (PEP 446 [https://www.python.org/dev/peps/pep-0446]).

command line option for isolated mode (bpo-16499 [https://bugs.python.org/issue?@action=redirect&bpo=16499]).

improvements in the handling of codecs that are not text encodings (multiple issues).

A ModuleSpec Type for the Import System (PEP 451 [https://www.python.org/dev/peps/pep-0451]). (Affects importer authors.)

The marshal format has been made more compact and efficient (bpo-16475 [https://bugs.python.org/issue?@action=redirect&bpo=16475]).

New library modules:

asyncio: New provisional API for asynchronous IO (PEP 3156 [https://www.python.org/dev/peps/pep-3156]).

ensurepip: Bootstrapping the pip installer (PEP 453 [https://www.python.org/dev/peps/pep-0453]).

enum: Support for enumeration types (PEP 435 [https://www.python.org/dev/peps/pep-0435]).

pathlib: Object-oriented filesystem paths (PEP 428 [https://www.python.org/dev/peps/pep-0428]).

selectors: High-level and efficient I/O multiplexing, built upon the select module primitives (part of PEP 3156 [https://www.python.org/dev/peps/pep-3156]).

statistics: A basic numerically stable statistics library (PEP 450 [https://www.python.org/dev/peps/pep-0450]).

tracemalloc: Trace Python memory allocations (PEP 454 [https://www.python.org/dev/peps/pep-0454]).

Significantly improved library modules:

Single-dispatch generic functions in functools (PEP 443 [https://www.python.org/dev/peps/pep-0443]).

New pickle protocol 4 (PEP 3154 [https://www.python.org/dev/peps/pep-3154]).

multiprocessing now has an option to avoid using os.fork on Unix (bpo-8713 [https://bugs.python.org/issue?@action=redirect&bpo=8713]).

email has a new submodule, contentmanager, and a new Message subclass (EmailMessage) that simplify MIME handling (bpo-18891 [https://bugs.python.org/issue?@action=redirect&bpo=18891]).

The inspect and pydoc modules are now capable of correct introspection of a much wider variety of callable objects, which improves the output of the Python help() system.

The ipaddress module API has been declared stable

Security improvements:

Secure and interchangeable hash algorithm (PEP 456 [https://www.python.org/dev/peps/pep-0456]).

Make newly created file descriptors non-inheritable (PEP 446 [https://www.python.org/dev/peps/pep-0446]) to avoid leaking file descriptors to child processes.

New command line option for isolated mode, (bpo-16499 [https://bugs.python.org/issue?@action=redirect&bpo=16499]).

multiprocessing now has an option to avoid using os.fork on Unix. spawn and forkserver are more secure because they avoid sharing data with child processes.

multiprocessing child processes on Windows no longer inherit all of the parent’s inheritable handles, only the necessary ones.

A new hashlib.pbkdf2_hmac() function provides the PKCS#5 password-based key derivation function 2 [https://en.wikipedia.org/wiki/PBKDF2].

TLSv1.1 and TLSv1.2 support for ssl.

Retrieving certificates from the Windows system cert store support for ssl.

Server-side SNI (Server Name Indication) support for ssl.

The ssl.SSLContext class has a lot of improvements.

All modules in the standard library that support SSL now support server certificate verification, including hostname matching (ssl.match_hostname()) and CRLs (Certificate Revocation lists, see ssl.SSLContext.load_verify_locations()).

CPython implementation improvements:

Safe object finalization (PEP 442 [https://www.python.org/dev/peps/pep-0442]).

Leveraging PEP 442 [https://www.python.org/dev/peps/pep-0442], in most cases module globals are no longer set to None during finalization (bpo-18214 [https://bugs.python.org/issue?@action=redirect&bpo=18214]).

Configurable memory allocators (PEP 445 [https://www.python.org/dev/peps/pep-0445]).

Argument Clinic (PEP 436 [https://www.python.org/dev/peps/pep-0436]).

Please read on for a comprehensive list of user-facing changes, including many other smaller improvements, CPython optimizations, deprecations, and potential porting issues.

New Features

PEP 453: Explicit Bootstrapping of PIP in Python Installations

Bootstrapping pip By Default

The new ensurepip module (defined in PEP 453 [https://www.python.org/dev/peps/pep-0453]) provides a standard cross-platform mechanism to bootstrap the pip installer into Python installations and virtual environments. The version of pip included with Python 3.4.0 is pip 1.5.4, and future 3.4.x maintenance releases will update the bundled version to the latest version of pip that is available at the time of creating the release candidate.

By default, the commands pipX and pipX.Y will be installed on all platforms (where X.Y stands for the version of the Python installation), along with the pip Python package and its dependencies. On Windows and in virtual environments on all platforms, the unversioned pip command will also be installed. On other platforms, the system wide unversioned pip command typically refers to the separately installed Python 2 version.

The pyvenv command line utility and the venv module make use of the ensurepip module to make pip readily available in virtual environments. When using the command line utility, pip is installed by default, while when using the venv module API installation of pip must be requested explicitly.

For CPython source builds on POSIX systems, the make install and make altinstall commands bootstrap pip by default. This behaviour can be controlled through configure options, and overridden through Makefile options.

On Windows and Mac OS X, the CPython installers now default to installing pip along with CPython itself (users may opt out of installing it during the installation process). Window users will need to opt in to the automatic PATH modifications to have pip available from the command line by default, otherwise it can still be accessed through the Python launcher for Windows as py -m pip.

As discussed in the PEP [https://www.python.org/dev/peps/pep-0453/#recommendations-for-downstream-distributors], platform packagers may choose not to install these commands by default, as long as, when invoked, they provide clear and simple directions on how to install them on that platform (usually using the system package manager).

Nota

To avoid conflicts between parallel Python 2 and Python 3 installations, only the versioned pip3 and pip3.4 commands are bootstrapped by default when ensurepip is invoked directly - the --default-pip option is needed to also request the unversioned pip command. pyvenv and the Windows installer ensure that the unqualified pip command is made available in those environments, and pip can always be invoked via the -m switch rather than directly to avoid ambiguity on systems with multiple Python installations.

Documentation Changes

As part of this change, the Instalando módulos de Python and Distribuir módulos de Python sections of the documentation have been completely redesigned as short getting started and FAQ documents. Most packaging documentation has now been moved out to the Python Packaging Authority maintained Python Packaging User Guide [https://packaging.python.org] and the documentation of the individual projects.

However, as this migration is currently still incomplete, the legacy versions of those guides remaining available as Instalación de Módulos de Python (versión antigua) and Distribución de módulos de Python (versión heredada).

Ver también

PEP 453 [https://www.python.org/dev/peps/pep-0453] – Explicit bootstrapping of pip in Python installations

PEP written by Donald Stufft and Nick Coghlan, implemented by Donald Stufft, Nick Coghlan, Martin von Löwis and Ned Deily.

PEP 446: Newly Created File Descriptors Are Non-Inheritable

PEP 446 [https://www.python.org/dev/peps/pep-0446] makes newly created file descriptors non-inheritable. In general, this is the behavior an application will want: when launching a new process, having currently open files also open in the new process can lead to all sorts of hard to find bugs, and potentially to security issues.

However, there are occasions when inheritance is desired. To support these cases, the following new functions and methods are available:

os.get_inheritable(), os.set_inheritable()

os.get_handle_inheritable(), os.set_handle_inheritable()

socket.socket.get_inheritable(), socket.socket.set_inheritable()

Ver también

PEP 446 [https://www.python.org/dev/peps/pep-0446] – Make newly created file descriptors non-inheritable

PEP written and implemented by Victor Stinner.

Improvements to Codec Handling

Since it was first introduced, the codecs module has always been intended to operate as a type-neutral dynamic encoding and decoding system. However, its close coupling with the Python text model, especially the type restricted convenience methods on the builtin str, bytes and bytearray types, has historically obscured that fact.

As a key step in clarifying the situation, the codecs.encode() and codecs.decode() convenience functions are now properly documented in Python 2.7, 3.3 and 3.4. These functions have existed in the codecs module (and have been covered by the regression test suite) since Python 2.4, but were previously only discoverable through runtime introspection.

Unlike the convenience methods on str, bytes and bytearray, the codecs convenience functions support arbitrary codecs in both Python 2 and Python 3, rather than being limited to Unicode text encodings (in Python 3) or basestring <-> basestring conversions (in Python 2).

In Python 3.4, the interpreter is able to identify the known non-text encodings provided in the standard library and direct users towards these general purpose convenience functions when appropriate:

>>> b"abcdef".decode("hex")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
LookupError: 'hex' is not a text encoding; use codecs.decode() to handle arbitrary codecs

>>> "hello".encode("rot13")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
LookupError: 'rot13' is not a text encoding; use codecs.encode() to handle arbitrary codecs

>>> open("foo.txt", encoding="hex")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
LookupError: 'hex' is not a text encoding; use codecs.open() to handle arbitrary codecs

In a related change, whenever it is feasible without breaking backwards compatibility, exceptions raised during encoding and decoding operations are wrapped in a chained exception of the same type that mentions the name of the codec responsible for producing the error:

>>> import codecs

>>> codecs.decode(b"abcdefgh", "hex")
Traceback (most recent call last):
  File "/usr/lib/python3.4/encodings/hex_codec.py", line 20, in hex_decode
    return (binascii.a2b_hex(input), len(input))
binascii.Error: Non-hexadecimal digit found

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
binascii.Error: decoding with 'hex' codec failed (Error: Non-hexadecimal digit found)

>>> codecs.encode("hello", "bz2")
Traceback (most recent call last):
  File "/usr/lib/python3.4/encodings/bz2_codec.py", line 17, in bz2_encode
    return (bz2.compress(input), len(input))
  File "/usr/lib/python3.4/bz2.py", line 498, in compress
    return comp.compress(data) + comp.flush()
TypeError: 'str' does not support the buffer interface

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: encoding with 'bz2' codec failed (TypeError: 'str' does not support the buffer interface)

Finally, as the examples above show, these improvements have permitted the restoration of the convenience aliases for the non-Unicode codecs that were themselves restored in Python 3.2. This means that encoding binary data to and from its hexadecimal representation (for example) can now be written as:

>>> from codecs import encode, decode
>>> encode(b"hello", "hex")
b'68656c6c6f'
>>> decode(b"68656c6c6f", "hex")
b'hello'

The binary and text transforms provided in the standard library are detailed in Transformaciones Binarias and Transformaciones de texto.

(Contributed by Nick Coghlan in bpo-7475 [https://bugs.python.org/issue?@action=redirect&bpo=7475], bpo-17827 [https://bugs.python.org/issue?@action=redirect&bpo=17827], bpo-17828 [https://bugs.python.org/issue?@action=redirect&bpo=17828] and bpo-19619 [https://bugs.python.org/issue?@action=redirect&bpo=19619].)

PEP 451: A ModuleSpec Type for the Import System

PEP 451 [https://www.python.org/dev/peps/pep-0451] provides an encapsulation of the information about a module that the import machinery will use to load it (that is, a module specification). This helps simplify both the import implementation and several import-related APIs. The change is also a stepping stone for several future import-related improvements [https://mail.python.org/pipermail/python-dev/2013-November/130111.html].

The public-facing changes from the PEP are entirely backward-compatible. Furthermore, they should be transparent to everyone but importer authors. Key finder and loader methods have been deprecated, but they will continue working. New importers should use the new methods described in the PEP. Existing importers should be updated to implement the new methods. See the Deprecated section for a list of methods that should be replaced and their replacements.

Other Language Changes

Some smaller changes made to the core Python language are:

Unicode database updated to UCD version 6.3.

min() and max() now accept a default keyword-only argument that can be used to specify the value they return if the iterable they are evaluating has no elements. (Contributed by Julian Berman in bpo-18111 [https://bugs.python.org/issue?@action=redirect&bpo=18111].)

Module objects are now weakref’able.

Module __file__ attributes (and related values) should now always contain absolute paths by default, with the sole exception of __main__.__file__ when a script has been executed directly using a relative path. (Contributed by Brett Cannon in bpo-18416 [https://bugs.python.org/issue?@action=redirect&bpo=18416].)

All the UTF-* codecs (except UTF-7) now reject surrogates during both encoding and decoding unless the surrogatepass error handler is used, with the exception of the UTF-16 decoder (which accepts valid surrogate pairs) and the UTF-16 encoder (which produces them while encoding non-BMP characters). (Contributed by Victor Stinner, Kang-Hao (Kenny) Lu and Serhiy Storchaka in bpo-12892 [https://bugs.python.org/issue?@action=redirect&bpo=12892].)

New German EBCDIC codec cp273. (Contributed by Michael Bierenfeld and Andrew Kuchling in bpo-1097797 [https://bugs.python.org/issue?@action=redirect&bpo=1097797].)

New Ukrainian codec cp1125. (Contributed by Serhiy Storchaka in bpo-19668 [https://bugs.python.org/issue?@action=redirect&bpo=19668].)

bytes.join() and bytearray.join() now accept arbitrary buffer objects as arguments. (Contributed by Antoine Pitrou in bpo-15958 [https://bugs.python.org/issue?@action=redirect&bpo=15958].)

The int constructor now accepts any object that has an __index__ method for its base argument. (Contributed by Mark Dickinson in bpo-16772 [https://bugs.python.org/issue?@action=redirect&bpo=16772].)

Frame objects now have a clear() method that clears all references to local variables from the frame. (Contributed by Antoine Pitrou in bpo-17934 [https://bugs.python.org/issue?@action=redirect&bpo=17934].)

memoryview is now registered as a Sequence, and supports the reversed() builtin. (Contributed by Nick Coghlan and Claudiu Popa in bpo-18690 [https://bugs.python.org/issue?@action=redirect&bpo=18690] and bpo-19078 [https://bugs.python.org/issue?@action=redirect&bpo=19078].)

Signatures reported by help() have been modified and improved in several cases as a result of the introduction of Argument Clinic and other changes to the inspect and pydoc modules.

__length_hint__() is now part of the formal language specification (see PEP 424 [https://www.python.org/dev/peps/pep-0424]). (Contributed by Armin Ronacher in bpo-16148 [https://bugs.python.org/issue?@action=redirect&bpo=16148].)

New Modules

asyncio

The new asyncio module (defined in PEP 3156 [https://www.python.org/dev/peps/pep-3156]) provides a standard pluggable event loop model for Python, providing solid asynchronous IO support in the standard library, and making it easier for other event loop implementations to interoperate with the standard library and each other.

For Python 3.4, this module is considered a provisional API.

Ver también

PEP 3156 [https://www.python.org/dev/peps/pep-3156] – Asynchronous IO Support Rebooted: the «asyncio» Module

PEP written and implementation led by Guido van Rossum.

ensurepip

The new ensurepip module is the primary infrastructure for the PEP 453 [https://www.python.org/dev/peps/pep-0453] implementation. In the normal course of events end users will not need to interact with this module, but it can be used to manually bootstrap pip if the automated bootstrapping into an installation or virtual environment was declined.

ensurepip includes a bundled copy of pip, up-to-date as of the first release candidate of the release of CPython with which it ships (this applies to both maintenance releases and feature releases). ensurepip does not access the internet. If the installation has Internet access, after ensurepip is run the bundled pip can be used to upgrade pip to a more recent release than the bundled one. (Note that such an upgraded version of pip is considered to be a separately installed package and will not be removed if Python is uninstalled.)

The module is named ensurepip because if called when pip is already installed, it does nothing. It also has an --upgrade option that will cause it to install the bundled copy of pip if the existing installed version of pip is older than the bundled copy.

enum

The new enum module (defined in PEP 435 [https://www.python.org/dev/peps/pep-0435]) provides a standard implementation of enumeration types, allowing other modules (such as socket) to provide more informative error messages and better debugging support by replacing opaque integer constants with backwards compatible enumeration values.

Ver también

PEP 435 [https://www.python.org/dev/peps/pep-0435] – Adding an Enum type to the Python standard library

PEP written by Barry Warsaw, Eli Bendersky and Ethan Furman, implemented by Ethan Furman.

pathlib

The new pathlib module offers classes representing filesystem paths with semantics appropriate for different operating systems. Path classes are divided between pure paths, which provide purely computational operations without I/O, and concrete paths, which inherit from pure paths but also provide I/O operations.

For Python 3.4, this module is considered a provisional API.

Ver también

PEP 428 [https://www.python.org/dev/peps/pep-0428] – The pathlib module – object-oriented filesystem paths

PEP written and implemented by Antoine Pitrou.

selectors

The new selectors module (created as part of implementing PEP 3156 [https://www.python.org/dev/peps/pep-3156]) allows high-level and efficient I/O multiplexing, built upon the select module primitives.

statistics

The new statistics module (defined in PEP 450 [https://www.python.org/dev/peps/pep-0450]) offers some core statistics functionality directly in the standard library. This module supports calculation of the mean, median, mode, variance and standard deviation of a data series.

Ver también

PEP 450 [https://www.python.org/dev/peps/pep-0450] – Adding A Statistics Module To The Standard Library

PEP written and implemented by Steven D’Aprano

tracemalloc

The new tracemalloc module (defined in PEP 454 [https://www.python.org/dev/peps/pep-0454]) is a debug tool to trace memory blocks allocated by Python. It provides the following information:

Trace where an object was allocated

Statistics on allocated memory blocks per filename and per line number: total size, number and average size of allocated memory blocks

Compute the differences between two snapshots to detect memory leaks

Ver también

PEP 454 [https://www.python.org/dev/peps/pep-0454] – Add a new tracemalloc module to trace Python memory allocations

PEP written and implemented by Victor Stinner

Improved Modules

abc

New function abc.get_cache_token() can be used to know when to invalidate caches that are affected by changes in the object graph. (Contributed by Łukasz Langa in bpo-16832 [https://bugs.python.org/issue?@action=redirect&bpo=16832].)

New class ABC has ABCMeta as its meta class. Using ABC as a base class has essentially the same effect as specifying metaclass=abc.ABCMeta, but is simpler to type and easier to read. (Contributed by Bruno Dupuis in bpo-16049 [https://bugs.python.org/issue?@action=redirect&bpo=16049].)

aifc

The getparams() method now returns a namedtuple rather than a plain tuple. (Contributed by Claudiu Popa in bpo-17818 [https://bugs.python.org/issue?@action=redirect&bpo=17818].)

aifc.open() now supports the context management protocol: when used in a with block, the close() method of the returned object will be called automatically at the end of the block. (Contributed by Serhiy Storchacha in bpo-16486 [https://bugs.python.org/issue?@action=redirect&bpo=16486].)

The writeframesraw() and writeframes() methods now accept any bytes-like object. (Contributed by Serhiy Storchaka in bpo-8311 [https://bugs.python.org/issue?@action=redirect&bpo=8311].)

argparse

The FileType class now accepts encoding and errors arguments, which are passed through to open(). (Contributed by Lucas Maystre in bpo-11175 [https://bugs.python.org/issue?@action=redirect&bpo=11175].)

audioop

audioop now supports 24-bit samples. (Contributed by Serhiy Storchaka in bpo-12866 [https://bugs.python.org/issue?@action=redirect&bpo=12866].)

New byteswap() function converts big-endian samples to little-endian and vice versa. (Contributed by Serhiy Storchaka in bpo-19641 [https://bugs.python.org/issue?@action=redirect&bpo=19641].)

All audioop functions now accept any bytes-like object. Strings are not accepted: they didn’t work before, now they raise an error right away. (Contributed by Serhiy Storchaka in bpo-16685 [https://bugs.python.org/issue?@action=redirect&bpo=16685].)

base64

The encoding and decoding functions in base64 now accept any bytes-like object in cases where it previously required a bytes or bytearray instance. (Contributed by Nick Coghlan in bpo-17839 [https://bugs.python.org/issue?@action=redirect&bpo=17839].)

New functions a85encode(), a85decode(), b85encode(), and b85decode() provide the ability to encode and decode binary data from and to Ascii85 and the git/mercurial Base85 formats, respectively. The a85 functions have options that can be used to make them compatible with the variants of the Ascii85 encoding, including the Adobe variant. (Contributed by Martin Morrison, the Mercurial project, Serhiy Storchaka, and Antoine Pitrou in bpo-17618 [https://bugs.python.org/issue?@action=redirect&bpo=17618].)

collections

The ChainMap.new_child() method now accepts an m argument specifying the child map to add to the chain. This allows an existing mapping and/or a custom mapping type to be used for the child. (Contributed by Vinay Sajip in bpo-16613 [https://bugs.python.org/issue?@action=redirect&bpo=16613].)

colorsys

The number of digits in the coefficients for the RGB — YIQ conversions have been expanded so that they match the FCC NTSC versions. The change in results should be less than 1% and may better match results found elsewhere. (Contributed by Brian Landers and Serhiy Storchaka in bpo-14323 [https://bugs.python.org/issue?@action=redirect&bpo=14323].)

contextlib

The new contextlib.suppress context manager helps to clarify the intent of code that deliberately suppresses exceptions from a single statement. (Contributed by Raymond Hettinger in bpo-15806 [https://bugs.python.org/issue?@action=redirect&bpo=15806] and Zero Piraeus in bpo-19266 [https://bugs.python.org/issue?@action=redirect&bpo=19266].)

The new contextlib.redirect_stdout() context manager makes it easier for utility scripts to handle inflexible APIs that write their output to sys.stdout and don’t provide any options to redirect it. Using the context manager, the sys.stdout output can be redirected to any other stream or, in conjunction with io.StringIO, to a string. The latter can be especially useful, for example, to capture output from a function that was written to implement a command line interface. It is recommended only for utility scripts because it affects the global state of sys.stdout. (Contributed by Raymond Hettinger in bpo-15805 [https://bugs.python.org/issue?@action=redirect&bpo=15805].)

The contextlib documentation has also been updated to include a discussion of the differences between single use, reusable and reentrant context managers.

dbm

dbm.open() objects now support the context management protocol. When used in a with statement, the close method of the database object will be called automatically at the end of the block. (Contributed by Claudiu Popa and Nick Coghlan in bpo-19282 [https://bugs.python.org/issue?@action=redirect&bpo=19282].)

dis

Functions show_code(), dis(), distb(), and disassemble() now accept a keyword-only file argument that controls where they write their output.

The dis module is now built around an Instruction class that provides object oriented access to the details of each individual bytecode operation.

A new method, get_instructions(), provides an iterator that emits the Instruction stream for a given piece of Python code. Thus it is now possible to write a program that inspects and manipulates a bytecode object in ways different from those provided by the dis module itself. For example:

>>> import dis
>>> for instr in dis.get_instructions(lambda x: x + 1):
...     print(instr.opname)
LOAD_FAST
LOAD_CONST
BINARY_ADD
RETURN_VALUE

The various display tools in the dis module have been rewritten to use these new components.

In addition, a new application-friendly class Bytecode provides an object-oriented API for inspecting bytecode in both in human-readable form and for iterating over instructions. The Bytecode constructor takes the same arguments that get_instruction() does (plus an optional current_offset), and the resulting object can be iterated to produce Instruction objects. But it also has a dis method, equivalent to calling dis on the constructor argument, but returned as a multi-line string:

>>> bytecode = dis.Bytecode(lambda x: x + 1, current_offset=3)
>>> for instr in bytecode:
...     print('{} ({})'.format(instr.opname, instr.opcode))
LOAD_FAST (124)
LOAD_CONST (100)
BINARY_ADD (23)
RETURN_VALUE (83)
>>> bytecode.dis().splitlines()
['  1           0 LOAD_FAST                0 (x)',
 '      -->     3 LOAD_CONST               1 (1)',
 '              6 BINARY_ADD',
 '              7 RETURN_VALUE']

Bytecode also has a class method, from_traceback(), that provides the ability to manipulate a traceback (that is, print(Bytecode.from_traceback(tb).dis()) is equivalent to distb(tb)).

(Contributed by Nick Coghlan, Ryan Kelly and Thomas Kluyver in bpo-11816 [https://bugs.python.org/issue?@action=redirect&bpo=11816] and Claudiu Popa in bpo-17916 [https://bugs.python.org/issue?@action=redirect&bpo=17916].)

New function stack_effect() computes the effect on the Python stack of a given opcode and argument, information that is not otherwise available. (Contributed by Larry Hastings in bpo-19722 [https://bugs.python.org/issue?@action=redirect&bpo=19722].)

doctest

A new option flag, FAIL_FAST, halts test running as soon as the first failure is detected. (Contributed by R. David Murray and Daniel Urban in bpo-16522 [https://bugs.python.org/issue?@action=redirect&bpo=16522].)

The doctest command line interface now uses argparse, and has two new options, -o and -f. -o allows doctest options to be specified on the command line, and -f is a shorthand for -o FAIL_FAST (to parallel the similar option supported by the unittest CLI). (Contributed by R. David Murray in bpo-11390 [https://bugs.python.org/issue?@action=redirect&bpo=11390].)

doctest will now find doctests in extension module __doc__ strings. (Contributed by Zachary Ware in bpo-3158 [https://bugs.python.org/issue?@action=redirect&bpo=3158].)

email

as_string() now accepts a policy argument to override the default policy of the message when generating a string representation of it. This means that as_string can now be used in more circumstances, instead of having to create and use a generator in order to pass formatting parameters to its flatten method. (Contributed by R. David Murray in bpo-18600 [https://bugs.python.org/issue?@action=redirect&bpo=18600].)

New method as_bytes() added to produce a bytes representation of the message in a fashion similar to how as_string produces a string representation. It does not accept the maxheaderlen argument, but does accept the unixfrom and policy arguments. The Message __bytes__() method calls it, meaning that bytes(mymsg) will now produce the intuitive result: a bytes object containing the fully formatted message. (Contributed by R. David Murray in bpo-18600 [https://bugs.python.org/issue?@action=redirect&bpo=18600].)

The Message.set_param() message now accepts a replace keyword argument. When specified, the associated header will be updated without changing its location in the list of headers. For backward compatibility, the default is False. (Contributed by R. David Murray in bpo-18891 [https://bugs.python.org/issue?@action=redirect&bpo=18891].)

A pair of new subclasses of Message have been added (EmailMessage and MIMEPart), along with a new sub-module, contentmanager and a new policy attribute content_manager. All documentation is currently in the new module, which is being added as part of email’s new provisional API. These classes provide a number of new methods that make extracting content from and inserting content into email messages much easier. For details, see the contentmanager documentation and the email: Ejemplos. These API additions complete the bulk of the work that was planned as part of the email6 project. The currently provisional API is scheduled to become final in Python 3.5 (possibly with a few minor additions in the area of error handling). (Contributed by R. David Murray in bpo-18891 [https://bugs.python.org/issue?@action=redirect&bpo=18891].)

filecmp

A new clear_cache() function provides the ability to clear the filecmp comparison cache, which uses os.stat() information to determine if the file has changed since the last compare. This can be used, for example, if the file might have been changed and re-checked in less time than the resolution of a particular filesystem’s file modification time field. (Contributed by Mark Levitt in bpo-18149 [https://bugs.python.org/issue?@action=redirect&bpo=18149].)

New module attribute DEFAULT_IGNORES provides the list of directories that are used as the default value for the ignore parameter of the dircmp() function. (Contributed by Eli Bendersky in bpo-15442 [https://bugs.python.org/issue?@action=redirect&bpo=15442].)

functools

The new partialmethod() descriptor brings partial argument application to descriptors, just as partial() provides for normal callables. The new descriptor also makes it easier to get arbitrary callables (including partial() instances) to behave like normal instance methods when included in a class definition. (Contributed by Alon Horev and Nick Coghlan in bpo-4331 [https://bugs.python.org/issue?@action=redirect&bpo=4331].)

The new singledispatch() decorator brings support for single-dispatch generic functions to the Python standard library. Where object oriented programming focuses on grouping multiple operations on a common set of data into a class, a generic function focuses on grouping multiple implementations of an operation that allows it to work with different kinds of data.

Ver también

PEP 443 [https://www.python.org/dev/peps/pep-0443] – Single-dispatch generic functions

PEP written and implemented by Łukasz Langa.

total_ordering() now supports a return value of NotImplemented from the underlying comparison function. (Contributed by Katie Miller in bpo-10042 [https://bugs.python.org/issue?@action=redirect&bpo=10042].)

A pure-python version of the partial() function is now in the stdlib; in CPython it is overridden by the C accelerated version, but it is available for other implementations to use. (Contributed by Brian Thorne in bpo-12428 [https://bugs.python.org/issue?@action=redirect&bpo=12428].)

gc

New function get_stats() returns a list of three per-generation dictionaries containing the collections statistics since interpreter startup. (Contributed by Antoine Pitrou in bpo-16351 [https://bugs.python.org/issue?@action=redirect&bpo=16351].)

glob

A new function escape() provides a way to escape special characters in a filename so that they do not become part of the globbing expansion but are instead matched literally. (Contributed by Serhiy Storchaka in bpo-8402 [https://bugs.python.org/issue?@action=redirect&bpo=8402].)

hashlib

A new hashlib.pbkdf2_hmac() function provides the PKCS#5 password-based key derivation function 2 [https://en.wikipedia.org/wiki/PBKDF2]. (Contributed by Christian Heimes in bpo-18582 [https://bugs.python.org/issue?@action=redirect&bpo=18582].)

The name attribute of hashlib hash objects is now a formally supported interface. It has always existed in CPython’s hashlib (although it did not return lower case names for all supported hashes), but it was not a public interface and so some other Python implementations have not previously supported it. (Contributed by Jason R. Coombs in bpo-18532 [https://bugs.python.org/issue?@action=redirect&bpo=18532].)

hmac

hmac now accepts bytearray as well as bytes for the key argument to the new() function, and the msg parameter to both the new() function and the update() method now accepts any type supported by the hashlib module. (Contributed by Jonas Borgström in bpo-18240 [https://bugs.python.org/issue?@action=redirect&bpo=18240].)

The digestmod argument to the hmac.new() function may now be any hash digest name recognized by hashlib. In addition, the current behavior in which the value of digestmod defaults to MD5 is deprecated: in a future version of Python there will be no default value. (Contributed by Christian Heimes in bpo-17276 [https://bugs.python.org/issue?@action=redirect&bpo=17276].)

With the addition of block_size and name attributes (and the formal documentation of the digest_size attribute), the hmac module now conforms fully to the PEP 247 [https://www.python.org/dev/peps/pep-0247] API. (Contributed by Christian Heimes in bpo-18775 [https://bugs.python.org/issue?@action=redirect&bpo=18775].)

html

New function unescape() function converts HTML5 character references to the corresponding Unicode characters. (Contributed by Ezio Melotti in bpo-2927 [https://bugs.python.org/issue?@action=redirect&bpo=2927].)

HTMLParser accepts a new keyword argument convert_charrefs that, when True, automatically converts all character references. For backward-compatibility, its value defaults to False, but it will change to True in a future version of Python, so you are invited to set it explicitly and update your code to use this new feature. (Contributed by Ezio Melotti in bpo-13633 [https://bugs.python.org/issue?@action=redirect&bpo=13633].)

The strict argument of HTMLParser is now deprecated. (Contributed by Ezio Melotti in bpo-15114 [https://bugs.python.org/issue?@action=redirect&bpo=15114].)

http

send_error() now accepts an optional additional explain parameter which can be used to provide an extended error description, overriding the hardcoded default if there is one. This extended error description will be formatted using the error_message_format attribute and sent as the body of the error response. (Contributed by Karl Cow in bpo-12921 [https://bugs.python.org/issue?@action=redirect&bpo=12921].)

The http.server command line interface now has a -b/--bind option that causes the server to listen on a specific address. (Contributed by Malte Swart in bpo-17764 [https://bugs.python.org/issue?@action=redirect&bpo=17764].)

idlelib and IDLE

Since idlelib implements the IDLE shell and editor and is not intended for import by other programs, it gets improvements with every release. See Lib/idlelib/NEWS.txt for a cumulative list of changes since 3.3.0, as well as changes made in future 3.4.x releases. This file is also available from the IDLE Help ‣ About IDLE dialog.

importlib

The InspectLoader ABC defines a new method, source_to_code() that accepts source data and a path and returns a code object. The default implementation is equivalent to compile(data, path, 'exec', dont_inherit=True). (Contributed by Eric Snow and Brett Cannon in bpo-15627 [https://bugs.python.org/issue?@action=redirect&bpo=15627].)

InspectLoader also now has a default implementation for the get_code() method. However, it will normally be desirable to override the default implementation for performance reasons. (Contributed by Brett Cannon in bpo-18072 [https://bugs.python.org/issue?@action=redirect&bpo=18072].)

The reload() function has been moved from imp to importlib as part of the imp module deprecation. (Contributed by Berker Peksag in bpo-18193 [https://bugs.python.org/issue?@action=redirect&bpo=18193].)

importlib.util now has a MAGIC_NUMBER attribute providing access to the bytecode version number. This replaces the get_magic() function in the deprecated imp module. (Contributed by Brett Cannon in bpo-18192 [https://bugs.python.org/issue?@action=redirect&bpo=18192].)

New importlib.util functions cache_from_source() and source_from_cache() replace the same-named functions in the deprecated imp module. (Contributed by Brett Cannon in bpo-18194 [https://bugs.python.org/issue?@action=redirect&bpo=18194].)

The importlib bootstrap NamespaceLoader now conforms to the InspectLoader ABC, which means that runpy and python -m can now be used with namespace packages. (Contributed by Brett Cannon in bpo-18058 [https://bugs.python.org/issue?@action=redirect&bpo=18058].)

importlib.util has a new function decode_source() that decodes source from bytes using universal newline processing. This is useful for implementing InspectLoader.get_source() methods.

importlib.machinery.ExtensionFileLoader now has a get_filename() method. This was inadvertently omitted in the original implementation. (Contributed by Eric Snow in bpo-19152 [https://bugs.python.org/issue?@action=redirect&bpo=19152].)

inspect

The inspect module now offers a basic command line interface to quickly display source code and other information for modules, classes and functions. (Contributed by Claudiu Popa and Nick Coghlan in bpo-18626 [https://bugs.python.org/issue?@action=redirect&bpo=18626].)

unwrap() makes it easy to unravel wrapper function chains created by functools.wraps() (and any other API that sets the __wrapped__ attribute on a wrapper function). (Contributed by Daniel Urban, Aaron Iles and Nick Coghlan in bpo-13266 [https://bugs.python.org/issue?@action=redirect&bpo=13266].)

As part of the implementation of the new enum module, the inspect module now has substantially better support for custom __dir__ methods and dynamic class attributes provided through metaclasses. (Contributed by Ethan Furman in bpo-18929 [https://bugs.python.org/issue?@action=redirect&bpo=18929] and bpo-19030 [https://bugs.python.org/issue?@action=redirect&bpo=19030].)

getfullargspec() and getargspec() now use the signature() API. This allows them to support a much broader range of callables, including those with __signature__ attributes, those with metadata provided by argument clinic, functools.partial() objects and more. Note that, unlike signature(), these functions still ignore __wrapped__ attributes, and report the already bound first argument for bound methods, so it is still necessary to update your code to use signature() directly if those features are desired. (Contributed by Yury Selivanov in bpo-17481 [https://bugs.python.org/issue?@action=redirect&bpo=17481].)

signature() now supports duck types of CPython functions, which adds support for functions compiled with Cython. (Contributed by Stefan Behnel and Yury Selivanov in bpo-17159 [https://bugs.python.org/issue?@action=redirect&bpo=17159].)

ipaddress

ipaddress was added to the standard library in Python 3.3 as a provisional API. With the release of Python 3.4, this qualification has been removed: ipaddress is now considered a stable API, covered by the normal standard library requirements to maintain backwards compatibility.

A new is_global property is True if an address is globally routeable. (Contributed by Peter Moody in bpo-17400 [https://bugs.python.org/issue?@action=redirect&bpo=17400].)

logging

The TimedRotatingFileHandler has a new atTime parameter that can be used to specify the time of day when rollover should happen. (Contributed by Ronald Oussoren in bpo-9556 [https://bugs.python.org/issue?@action=redirect&bpo=9556].)

SocketHandler and DatagramHandler now support Unix domain sockets (by setting port to None). (Contributed by Vinay Sajip in commit ce46195b56a9.)

fileConfig() now accepts a configparser.RawConfigParser subclass instance for the fname parameter. This facilitates using a configuration file when logging configuration is just a part of the overall application configuration, or where the application modifies the configuration before passing it to fileConfig(). (Contributed by Vinay Sajip in bpo-16110 [https://bugs.python.org/issue?@action=redirect&bpo=16110].)

Logging configuration data received from a socket via the logging.config.listen() function can now be validated before being processed by supplying a verification function as the argument to the new verify keyword argument. (Contributed by Vinay Sajip in bpo-15452 [https://bugs.python.org/issue?@action=redirect&bpo=15452].)

marshal

The default marshal version has been bumped to 3. The code implementing the new version restores the Python2 behavior of recording only one copy of interned strings and preserving the interning on deserialization, and extends this «one copy» ability to any object type (including handling recursive references). This reduces both the size of .pyc files and the amount of memory a module occupies in memory when it is loaded from a .pyc (or .pyo) file. (Contributed by Kristján Valur Jónsson in bpo-16475 [https://bugs.python.org/issue?@action=redirect&bpo=16475], with additional speedups by Antoine Pitrou in bpo-19219 [https://bugs.python.org/issue?@action=redirect&bpo=19219].)

mmap

mmap objects can now be weakrefed. (Contributed by Valerie Lambert in bpo-4885 [https://bugs.python.org/issue?@action=redirect&bpo=4885].)

multiprocessing

On Unix two new start methods, spawn and forkserver, have been added for starting processes using multiprocessing. These make the mixing of processes with threads more robust, and the spawn method matches the semantics that multiprocessing has always used on Windows. New function get_all_start_methods() reports all start methods available on the platform, get_start_method() reports the current start method, and set_start_method() sets the start method. (Contributed by Richard Oudkerk in bpo-8713 [https://bugs.python.org/issue?@action=redirect&bpo=8713].)

multiprocessing also now has the concept of a context, which determines how child processes are created. New function get_context() returns a context that uses a specified start method. It has the same API as the multiprocessing module itself, so you can use it to create Pools and other objects that will operate within that context. This allows a framework and an application or different parts of the same application to use multiprocessing without interfering with each other. (Contributed by Richard Oudkerk in bpo-18999 [https://bugs.python.org/issue?@action=redirect&bpo=18999].)

Except when using the old fork start method, child processes no longer inherit unneeded handles/file descriptors from their parents (part of bpo-8713 [https://bugs.python.org/issue?@action=redirect&bpo=8713]).

multiprocessing now relies on runpy (which implements the -m switch) to initialise __main__ appropriately in child processes when using the spawn or forkserver start methods. This resolves some edge cases where combining multiprocessing, the -m command line switch, and explicit relative imports could cause obscure failures in child processes. (Contributed by Nick Coghlan in bpo-19946 [https://bugs.python.org/issue?@action=redirect&bpo=19946].)

operator

New function length_hint() provides an implementation of the specification for how the __length_hint__() special method should be used, as part of the PEP 424 [https://www.python.org/dev/peps/pep-0424] formal specification of this language feature. (Contributed by Armin Ronacher in bpo-16148 [https://bugs.python.org/issue?@action=redirect&bpo=16148].)

There is now a pure-python version of the operator module available for reference and for use by alternate implementations of Python. (Contributed by Zachary Ware in bpo-16694 [https://bugs.python.org/issue?@action=redirect&bpo=16694].)

os

There are new functions to get and set the inheritable flag of a file descriptor (os.get_inheritable(), os.set_inheritable()) or a Windows handle (os.get_handle_inheritable(), os.set_handle_inheritable()).

New function cpu_count() reports the number of CPUs available on the platform on which Python is running (or None if the count can’t be determined). The multiprocessing.cpu_count() function is now implemented in terms of this function). (Contributed by Trent Nelson, Yogesh Chaudhari, Victor Stinner, and Charles-François Natali in bpo-17914 [https://bugs.python.org/issue?@action=redirect&bpo=17914].)

os.path.samestat() is now available on the Windows platform (and the os.path.samefile() implementation is now shared between Unix and Windows). (Contributed by Brian Curtin in bpo-11939 [https://bugs.python.org/issue?@action=redirect&bpo=11939].)

os.path.ismount() now recognizes volumes mounted below a drive root on Windows. (Contributed by Tim Golden in bpo-9035 [https://bugs.python.org/issue?@action=redirect&bpo=9035].)

os.open() supports two new flags on platforms that provide them, O_PATH (un-opened file descriptor), and O_TMPFILE (unnamed temporary file; as of 3.4.0 release available only on Linux systems with a kernel version of 3.11 or newer that have uapi headers). (Contributed by Christian Heimes in bpo-18673 [https://bugs.python.org/issue?@action=redirect&bpo=18673] and Benjamin Peterson, respectively.)

pdb

pdb has been enhanced to handle generators, yield, and yield from in a more useful fashion. This is especially helpful when debugging asyncio based programs. (Contributed by Andrew Svetlov and Xavier de Gaye in bpo-16596 [https://bugs.python.org/issue?@action=redirect&bpo=16596].)

The print command has been removed from pdb, restoring access to the Python print() function from the pdb command line. Python2’s pdb did not have a print command; instead, entering print executed the print statement. In Python3 print was mistakenly made an alias for the pdb p command. p, however, prints the repr of its argument, not the str like the Python2 print command did. Worse, the Python3 pdb print command shadowed the Python3 print function, making it inaccessible at the pdb prompt. (Contributed by Connor Osborn in bpo-18764 [https://bugs.python.org/issue?@action=redirect&bpo=18764].)

pickle

pickle now supports (but does not use by default) a new pickle protocol, protocol 4. This new protocol addresses a number of issues that were present in previous protocols, such as the serialization of nested classes, very large strings and containers, and classes whose __new__() method takes keyword-only arguments. It also provides some efficiency improvements.

Ver también

PEP 3154 [https://www.python.org/dev/peps/pep-3154] – Pickle protocol 4

PEP written by Antoine Pitrou and implemented by Alexandre Vassalotti.

plistlib

plistlib now has an API that is similar to the standard pattern for stdlib serialization protocols, with new load(), dump(), loads(), and dumps() functions. (The older API is now deprecated.) In addition to the already supported XML plist format (FMT_XML), it also now supports the binary plist format (FMT_BINARY). (Contributed by Ronald Oussoren and others in bpo-14455 [https://bugs.python.org/issue?@action=redirect&bpo=14455].)

poplib

Two new methods have been added to poplib: capa(), which returns the list of capabilities advertised by the POP server, and stls(), which switches a clear-text POP3 session into an encrypted POP3 session if the POP server supports it. (Contributed by Lorenzo Catucci in bpo-4473 [https://bugs.python.org/issue?@action=redirect&bpo=4473].)

pprint

The pprint module’s PrettyPrinter class and its pformat(), and pprint() functions have a new option, compact, that controls how the output is formatted. Currently setting compact to True means that sequences will be printed with as many sequence elements as will fit within width on each (indented) line. (Contributed by Serhiy Storchaka in bpo-19132 [https://bugs.python.org/issue?@action=redirect&bpo=19132].)

Long strings are now wrapped using Python’s normal line continuation syntax. (Contributed by Antoine Pitrou in bpo-17150 [https://bugs.python.org/issue?@action=redirect&bpo=17150].)

pty

pty.spawn() now returns the status value from os.waitpid() on the child process, instead of None. (Contributed by Gregory P. Smith.)

pydoc

The pydoc module is now based directly on the inspect.signature() introspection API, allowing it to provide signature information for a wider variety of callable objects. This change also means that __wrapped__ attributes are now taken into account when displaying help information. (Contributed by Larry Hastings in bpo-19674 [https://bugs.python.org/issue?@action=redirect&bpo=19674].)

The pydoc module no longer displays the self parameter for already bound methods. Instead, it aims to always display the exact current signature of the supplied callable. (Contributed by Larry Hastings in bpo-20710 [https://bugs.python.org/issue?@action=redirect&bpo=20710].)

In addition to the changes that have been made to pydoc directly, its handling of custom __dir__ methods and various descriptor behaviours has also been improved substantially by the underlying changes in the inspect module.

As the help() builtin is based on pydoc, the above changes also affect the behaviour of help().

re

New fullmatch() function and regex.fullmatch() method anchor the pattern at both ends of the string to match. This provides a way to be explicit about the goal of the match, which avoids a class of subtle bugs where $ characters get lost during code changes or the addition of alternatives to an existing regular expression. (Contributed by Matthew Barnett in bpo-16203 [https://bugs.python.org/issue?@action=redirect&bpo=16203].)

The repr of regex objects now includes the pattern and the flags; the repr of match objects now includes the start, end, and the part of the string that matched. (Contributed by Hugo Lopes Tavares and Serhiy Storchaka in bpo-13592 [https://bugs.python.org/issue?@action=redirect&bpo=13592] and bpo-17087 [https://bugs.python.org/issue?@action=redirect&bpo=17087].)

resource

New prlimit() function, available on Linux platforms with a kernel version of 2.6.36 or later and glibc of 2.13 or later, provides the ability to query or set the resource limits for processes other than the one making the call. (Contributed by Christian Heimes in bpo-16595 [https://bugs.python.org/issue?@action=redirect&bpo=16595].)

On Linux kernel version 2.6.36 or later, there are also some new Linux specific constants: RLIMIT_MSGQUEUE, RLIMIT_NICE, RLIMIT_RTPRIO, RLIMIT_RTTIME, and RLIMIT_SIGPENDING. (Contributed by Christian Heimes in bpo-19324 [https://bugs.python.org/issue?@action=redirect&bpo=19324].)

On FreeBSD version 9 and later, there some new FreeBSD specific constants: RLIMIT_SBSIZE, RLIMIT_SWAP, and RLIMIT_NPTS. (Contributed by Claudiu Popa in bpo-19343 [https://bugs.python.org/issue?@action=redirect&bpo=19343].)

select

epoll objects now support the context management protocol. When used in a with statement, the close() method will be called automatically at the end of the block. (Contributed by Serhiy Storchaka in bpo-16488 [https://bugs.python.org/issue?@action=redirect&bpo=16488].)

devpoll objects now have fileno() and close() methods, as well as a new attribute closed. (Contributed by Victor Stinner in bpo-18794 [https://bugs.python.org/issue?@action=redirect&bpo=18794].)

shelve

Shelf instances may now be used in with statements, and will be automatically closed at the end of the with block. (Contributed by Filip Gruszczyński in bpo-13896 [https://bugs.python.org/issue?@action=redirect&bpo=13896].)

shutil

copyfile() now raises a specific Error subclass, SameFileError, when the source and destination are the same file, which allows an application to take appropriate action on this specific error. (Contributed by Atsuo Ishimoto and Hynek Schlawack in bpo-1492704 [https://bugs.python.org/issue?@action=redirect&bpo=1492704].)

smtpd

The SMTPServer and SMTPChannel classes now accept a map keyword argument which, if specified, is passed in to asynchat.async_chat as its map argument. This allows an application to avoid affecting the global socket map. (Contributed by Vinay Sajip in bpo-11959 [https://bugs.python.org/issue?@action=redirect&bpo=11959].)

smtplib

SMTPException is now a subclass of OSError, which allows both socket level errors and SMTP protocol level errors to be caught in one try/except statement by code that only cares whether or not an error occurred. (Contributed by Ned Jackson Lovely in bpo-2118 [https://bugs.python.org/issue?@action=redirect&bpo=2118].)

socket

The socket module now supports the CAN_BCM protocol on platforms that support it. (Contributed by Brian Thorne in bpo-15359 [https://bugs.python.org/issue?@action=redirect&bpo=15359].)

Socket objects have new methods to get or set their inheritable flag, get_inheritable() and set_inheritable().

The socket.AF_* and socket.SOCK_* constants are now enumeration values using the new enum module. This allows meaningful names to be printed during debugging, instead of integer «magic numbers».

The AF_LINK constant is now available on BSD and OSX.

inet_pton() and inet_ntop() are now supported on Windows. (Contributed by Atsuo Ishimoto in bpo-7171 [https://bugs.python.org/issue?@action=redirect&bpo=7171].)

sqlite3

A new boolean parameter to the connect() function, uri, can be used to indicate that the database parameter is a uri (see the SQLite URI documentation [https://www.sqlite.org/uri.html]). (Contributed by poq in bpo-13773 [https://bugs.python.org/issue?@action=redirect&bpo=13773].)

ssl

PROTOCOL_TLSv1_1 and PROTOCOL_TLSv1_2 (TLSv1.1 and TLSv1.2 support) have been added; support for these protocols is only available if Python is linked with OpenSSL 1.0.1 or later. (Contributed by Michele Orrù and Antoine Pitrou in bpo-16692 [https://bugs.python.org/issue?@action=redirect&bpo=16692].)

New function create_default_context() provides a standard way to obtain an SSLContext whose settings are intended to be a reasonable balance between compatibility and security. These settings are more stringent than the defaults provided by the SSLContext constructor, and may be adjusted in the future, without prior deprecation, if best-practice security requirements change. The new recommended best practice for using stdlib libraries that support SSL is to use create_default_context() to obtain an SSLContext object, modify it if needed, and then pass it as the context argument of the appropriate stdlib API. (Contributed by Christian Heimes in bpo-19689 [https://bugs.python.org/issue?@action=redirect&bpo=19689].)

SSLContext method load_verify_locations() accepts a new optional argument cadata, which can be used to provide PEM or DER encoded certificates directly via strings or bytes, respectively. (Contributed by Christian Heimes in bpo-18138 [https://bugs.python.org/issue?@action=redirect&bpo=18138].)

New function get_default_verify_paths() returns a named tuple of the paths and environment variables that the set_default_verify_paths() method uses to set OpenSSL’s default cafile and capath. This can be an aid in debugging default verification issues. (Contributed by Christian Heimes in bpo-18143 [https://bugs.python.org/issue?@action=redirect&bpo=18143].)

SSLContext has a new method, cert_store_stats(), that reports the number of loaded X.509 certs, X.509 CA certs, and certificate revocation lists (crls), as well as a get_ca_certs() method that returns a list of the loaded CA certificates. (Contributed by Christian Heimes in bpo-18147 [https://bugs.python.org/issue?@action=redirect&bpo=18147].)

If OpenSSL 0.9.8 or later is available, SSLContext has a new attribute verify_flags that can be used to control the certificate verification process by setting it to some combination of the new constants VERIFY_DEFAULT, VERIFY_CRL_CHECK_LEAF, VERIFY_CRL_CHECK_CHAIN, or VERIFY_X509_STRICT. OpenSSL does not do any CRL verification by default. (Contributed by Christien Heimes in bpo-8813 [https://bugs.python.org/issue?@action=redirect&bpo=8813].)

New SSLContext method load_default_certs() loads a set of default «certificate authority» (CA) certificates from default locations, which vary according to the platform. It can be used to load both TLS web server authentication certificates (purpose=SERVER_AUTH) for a client to use to verify a server, and certificates for a server to use in verifying client certificates (purpose=CLIENT_AUTH). (Contributed by Christian Heimes in bpo-19292 [https://bugs.python.org/issue?@action=redirect&bpo=19292].)

Two new windows-only functions, enum_certificates() and enum_crls() provide the ability to retrieve certificates, certificate information, and CRLs from the Windows cert store. (Contributed by Christian Heimes in bpo-17134 [https://bugs.python.org/issue?@action=redirect&bpo=17134].)

Support for server-side SNI (Server Name Indication) using the new ssl.SSLContext.set_servername_callback() method. (Contributed by Daniel Black in bpo-8109 [https://bugs.python.org/issue?@action=redirect&bpo=8109].)

The dictionary returned by SSLSocket.getpeercert() contains additional X509v3 extension items: crlDistributionPoints, calIssuers, and OCSP URIs. (Contributed by Christian Heimes in bpo-18379 [https://bugs.python.org/issue?@action=redirect&bpo=18379].)

stat

The stat module is now backed by a C implementation in _stat. A C implementation is required as most of the values aren’t standardized and are platform-dependent. (Contributed by Christian Heimes in bpo-11016 [https://bugs.python.org/issue?@action=redirect&bpo=11016].)

The module supports new ST_MODE flags, S_IFDOOR, S_IFPORT, and S_IFWHT. (Contributed by Christian Hiemes in bpo-11016 [https://bugs.python.org/issue?@action=redirect&bpo=11016].)

struct

New function iter_unpack and a new struct.Struct.iter_unpack() method on compiled formats provide streamed unpacking of a buffer containing repeated instances of a given format of data. (Contributed by Antoine Pitrou in bpo-17804 [https://bugs.python.org/issue?@action=redirect&bpo=17804].)

subprocess

check_output() now accepts an input argument that can be used to provide the contents of stdin for the command that is run. (Contributed by Zack Weinberg in bpo-16624 [https://bugs.python.org/issue?@action=redirect&bpo=16624].)

getstatus() and getstatusoutput() now work on Windows. This change was actually inadvertently made in 3.3.4. (Contributed by Tim Golden in bpo-10197 [https://bugs.python.org/issue?@action=redirect&bpo=10197].)

sunau

The getparams() method now returns a namedtuple rather than a plain tuple. (Contributed by Claudiu Popa in bpo-18901 [https://bugs.python.org/issue?@action=redirect&bpo=18901].)

sunau.open() now supports the context management protocol: when used in a with block, the close method of the returned object will be called automatically at the end of the block. (Contributed by Serhiy Storchaka in bpo-18878 [https://bugs.python.org/issue?@action=redirect&bpo=18878].)

AU_write.setsampwidth() now supports 24 bit samples, thus adding support for writing 24 sample using the module. (Contributed by Serhiy Storchaka in bpo-19261 [https://bugs.python.org/issue?@action=redirect&bpo=19261].)

The writeframesraw() and writeframes() methods now accept any bytes-like object. (Contributed by Serhiy Storchaka in bpo-8311 [https://bugs.python.org/issue?@action=redirect&bpo=8311].)

sys

New function sys.getallocatedblocks() returns the current number of blocks allocated by the interpreter. (In CPython with the default --with-pymalloc setting, this is allocations made through the PyObject_Malloc() API.) This can be useful for tracking memory leaks, especially if automated via a test suite. (Contributed by Antoine Pitrou in bpo-13390 [https://bugs.python.org/issue?@action=redirect&bpo=13390].)

When the Python interpreter starts in interactive mode, it checks for an __interactivehook__ attribute on the sys module. If the attribute exists, its value is called with no arguments just before interactive mode is started. The check is made after the PYTHONSTARTUP file is read, so it can be set there. The site module sets it to a function that enables tab completion and history saving (in ~/.python-history) if the platform supports readline. If you do not want this (new) behavior, you can override it in PYTHONSTARTUP, sitecustomize, or usercustomize by deleting this attribute from sys (or setting it to some other callable). (Contributed by Éric Araujo and Antoine Pitrou in bpo-5845 [https://bugs.python.org/issue?@action=redirect&bpo=5845].)

tarfile

The tarfile module now supports a simple Interfaz de línea de comandos when called as a script directly or via -m. This can be used to create and extract tarfile archives. (Contributed by Berker Peksag in bpo-13477 [https://bugs.python.org/issue?@action=redirect&bpo=13477].)

textwrap

The TextWrapper class has two new attributes/constructor arguments: max_lines, which limits the number of lines in the output, and placeholder, which is a string that will appear at the end of the output if it has been truncated because of max_lines. Building on these capabilities, a new convenience function shorten() collapses all of the whitespace in the input to single spaces and produces a single line of a given width that ends with the placeholder (by default, [...]). (Contributed by Antoine Pitrou and Serhiy Storchaka in bpo-18585 [https://bugs.python.org/issue?@action=redirect&bpo=18585] and bpo-18725 [https://bugs.python.org/issue?@action=redirect&bpo=18725].)

threading

The Thread object representing the main thread can be obtained from the new main_thread() function. In normal conditions this will be the thread from which the Python interpreter was started. (Contributed by Andrew Svetlov in bpo-18882 [https://bugs.python.org/issue?@action=redirect&bpo=18882].)

traceback

A new traceback.clear_frames() function takes a traceback object and clears the local variables in all of the frames it references, reducing the amount of memory consumed. (Contributed by Andrew Kuchling in bpo-1565525 [https://bugs.python.org/issue?@action=redirect&bpo=1565525].)

types

A new DynamicClassAttribute() descriptor provides a way to define an attribute that acts normally when looked up through an instance object, but which is routed to the class __getattr__ when looked up through the class. This allows one to have properties active on a class, and have virtual attributes on the class with the same name (see Enum for an example). (Contributed by Ethan Furman in bpo-19030 [https://bugs.python.org/issue?@action=redirect&bpo=19030].)

urllib

urllib.request now supports data: URLs via the DataHandler class. (Contributed by Mathias Panzenböck in bpo-16423 [https://bugs.python.org/issue?@action=redirect&bpo=16423].)

The http method that will be used by a Request class can now be specified by setting a method class attribute on the subclass. (Contributed by Jason R Coombs in bpo-18978 [https://bugs.python.org/issue?@action=redirect&bpo=18978].)

Request objects are now reusable: if the full_url or data attributes are modified, all relevant internal properties are updated. This means, for example, that it is now possible to use the same Request object in more than one OpenerDirector.open() call with different data arguments, or to modify a Request’s url rather than recomputing it from scratch. There is also a new remove_header() method that can be used to remove headers from a Request. (Contributed by Alexey Kachayev in bpo-16464 [https://bugs.python.org/issue?@action=redirect&bpo=16464], Daniel Wozniak in bpo-17485 [https://bugs.python.org/issue?@action=redirect&bpo=17485], and Damien Brecht and Senthil Kumaran in bpo-17272 [https://bugs.python.org/issue?@action=redirect&bpo=17272].)

HTTPError objects now have a headers attribute that provides access to the HTTP response headers associated with the error. (Contributed by Berker Peksag in bpo-15701 [https://bugs.python.org/issue?@action=redirect&bpo=15701].)

unittest

The TestCase class has a new method, subTest(), that produces a context manager whose with block becomes a «sub-test». This context manager allows a test method to dynamically generate subtests by, say, calling the subTest context manager inside a loop. A single test method can thereby produce an indefinite number of separately-identified and separately-counted tests, all of which will run even if one or more of them fail. For example:

class NumbersTest(unittest.TestCase):
    def test_even(self):
        for i in range(6):
            with self.subTest(i=i):
                self.assertEqual(i % 2, 0)

will result in six subtests, each identified in the unittest verbose output with a label consisting of the variable name i and a particular value for that variable (i=0, i=1, etc). See Distinguiendo iteraciones de tests empleando subtests for the full version of this example. (Contributed by Antoine Pitrou in bpo-16997 [https://bugs.python.org/issue?@action=redirect&bpo=16997].)

unittest.main() now accepts an iterable of test names for defaultTest, where previously it only accepted a single test name as a string. (Contributed by Jyrki Pulliainen in bpo-15132 [https://bugs.python.org/issue?@action=redirect&bpo=15132].)

If SkipTest is raised during test discovery (that is, at the module level in the test file), it is now reported as a skip instead of an error. (Contributed by Zach Ware in bpo-16935 [https://bugs.python.org/issue?@action=redirect&bpo=16935].)

discover() now sorts the discovered files to provide consistent test ordering. (Contributed by Martin Melin and Jeff Ramnani in bpo-16709 [https://bugs.python.org/issue?@action=redirect&bpo=16709].)

TestSuite now drops references to tests as soon as the test has been run, if the test is successful. On Python interpreters that do garbage collection, this allows the tests to be garbage collected if nothing else is holding a reference to the test. It is possible to override this behavior by creating a TestSuite subclass that defines a custom _removeTestAtIndex method. (Contributed by Tom Wardill, Matt McClure, and Andrew Svetlov in bpo-11798 [https://bugs.python.org/issue?@action=redirect&bpo=11798].)

A new test assertion context-manager, assertLogs(), will ensure that a given block of code emits a log message using the logging module. By default the message can come from any logger and have a priority of INFO or higher, but both the logger name and an alternative minimum logging level may be specified. The object returned by the context manager can be queried for the LogRecords and/or formatted messages that were logged. (Contributed by Antoine Pitrou in bpo-18937 [https://bugs.python.org/issue?@action=redirect&bpo=18937].)

Test discovery now works with namespace packages (Contributed by Claudiu Popa in bpo-17457 [https://bugs.python.org/issue?@action=redirect&bpo=17457].)

unittest.mock objects now inspect their specification signatures when matching calls, which means an argument can now be matched by either position or name, instead of only by position. (Contributed by Antoine Pitrou in bpo-17015 [https://bugs.python.org/issue?@action=redirect&bpo=17015].)

mock_open() objects now have readline and readlines methods. (Contributed by Toshio Kuratomi in bpo-17467 [https://bugs.python.org/issue?@action=redirect&bpo=17467].)

venv

venv now includes activation scripts for the csh and fish shells. (Contributed by Andrew Svetlov in bpo-15417 [https://bugs.python.org/issue?@action=redirect&bpo=15417].)

EnvBuilder and the create() convenience function take a new keyword argument with_pip, which defaults to False, that controls whether or not EnvBuilder ensures that pip is installed in the virtual environment. (Contributed by Nick Coghlan in bpo-19552 [https://bugs.python.org/issue?@action=redirect&bpo=19552] as part of the PEP 453 [https://www.python.org/dev/peps/pep-0453] implementation.)

wave

The getparams() method now returns a namedtuple rather than a plain tuple. (Contributed by Claudiu Popa in bpo-17487 [https://bugs.python.org/issue?@action=redirect&bpo=17487].)

wave.open() now supports the context management protocol. (Contributed by Claudiu Popa in bpo-17616 [https://bugs.python.org/issue?@action=redirect&bpo=17616].)

wave can now write output to unseekable files. (Contributed by David Jones, Guilherme Polo, and Serhiy Storchaka in bpo-5202 [https://bugs.python.org/issue?@action=redirect&bpo=5202].)

The writeframesraw() and writeframes() methods now accept any bytes-like object. (Contributed by Serhiy Storchaka in bpo-8311 [https://bugs.python.org/issue?@action=redirect&bpo=8311].)

weakref

New WeakMethod class simulates weak references to bound methods. (Contributed by Antoine Pitrou in bpo-14631 [https://bugs.python.org/issue?@action=redirect&bpo=14631].)

New finalize class makes it possible to register a callback to be invoked when an object is garbage collected, without needing to carefully manage the lifecycle of the weak reference itself. (Contributed by Richard Oudkerk in bpo-15528 [https://bugs.python.org/issue?@action=redirect&bpo=15528].)

The callback, if any, associated with a ref is now exposed via the __callback__ attribute. (Contributed by Mark Dickinson in bpo-17643 [https://bugs.python.org/issue?@action=redirect&bpo=17643].)

xml.etree

A new parser, XMLPullParser, allows a non-blocking applications to parse XML documents. An example can be seen at API de consulta para un procesamiento no bloqueante. (Contributed by Antoine Pitrou in bpo-17741 [https://bugs.python.org/issue?@action=redirect&bpo=17741].)

The xml.etree.ElementTree tostring() and tostringlist() functions, and the ElementTree write() method, now have a short_empty_elements keyword-only parameter providing control over whether elements with no content are written in abbreviated (<tag />) or expanded (<tag></tag>) form. (Contributed by Ariel Poliak and Serhiy Storchaka in bpo-14377 [https://bugs.python.org/issue?@action=redirect&bpo=14377].)

zipfile

The writepy() method of the PyZipFile class has a new filterfunc option that can be used to control which directories and files are added to the archive. For example, this could be used to exclude test files from the archive. (Contributed by Christian Tismer in bpo-19274 [https://bugs.python.org/issue?@action=redirect&bpo=19274].)

The allowZip64 parameter to ZipFile and PyZipfile is now True by default. (Contributed by William Mallard in bpo-17201 [https://bugs.python.org/issue?@action=redirect&bpo=17201].)

CPython Implementation Changes

PEP 445: Customization of CPython Memory Allocators

PEP 445 [https://www.python.org/dev/peps/pep-0445] adds new C level interfaces to customize memory allocation in the CPython interpreter.

Ver también

PEP 445 [https://www.python.org/dev/peps/pep-0445] – Add new APIs to customize Python memory allocators

PEP written and implemented by Victor Stinner.

PEP 442: Safe Object Finalization

PEP 442 [https://www.python.org/dev/peps/pep-0442] removes the current limitations and quirks of object finalization in CPython. With it, objects with __del__() methods, as well as generators with finally clauses, can be finalized when they are part of a reference cycle.

As part of this change, module globals are no longer forcibly set to None during interpreter shutdown in most cases, instead relying on the normal operation of the cyclic garbage collector. This avoids a whole class of interpreter-shutdown-time errors, usually involving __del__ methods, that have plagued Python since the cyclic GC was first introduced.

Ver también

PEP 442 [https://www.python.org/dev/peps/pep-0442] – Safe object finalization

PEP written and implemented by Antoine Pitrou.

PEP 456: Secure and Interchangeable Hash Algorithm

PEP 456 [https://www.python.org/dev/peps/pep-0456] follows up on earlier security fix work done on Python’s hash algorithm to address certain DOS attacks to which public facing APIs backed by dictionary lookups may be subject. (See bpo-14621 [https://bugs.python.org/issue?@action=redirect&bpo=14621] for the start of the current round of improvements.) The PEP unifies CPython’s hash code to make it easier for a packager to substitute a different hash algorithm, and switches Python’s default implementation to a SipHash implementation on platforms that have a 64 bit data type. Any performance differences in comparison with the older FNV algorithm are trivial.

The PEP adds additional fields to the sys.hash_info named tuple to describe the hash algorithm in use by the currently executing binary. Otherwise, the PEP does not alter any existing CPython APIs.

PEP 436: Argument Clinic

«Argument Clinic» (PEP 436 [https://www.python.org/dev/peps/pep-0436]) is now part of the CPython build process and can be used to simplify the process of defining and maintaining accurate signatures for builtins and standard library extension modules implemented in C.

Some standard library extension modules have been converted to use Argument Clinic in Python 3.4, and pydoc and inspect have been updated accordingly.

It is expected that signature metadata for programmatic introspection will be added to additional callables implemented in C as part of Python 3.4 maintenance releases.

Nota

The Argument Clinic PEP is not fully up to date with the state of the implementation. This has been deemed acceptable by the release manager and core development team in this case, as Argument Clinic will not be made available as a public API for third party use in Python 3.4.

Ver también

PEP 436 [https://www.python.org/dev/peps/pep-0436] – The Argument Clinic DSL

PEP written and implemented by Larry Hastings.

Other Build and C API Changes

The new PyType_GetSlot() function has been added to the stable ABI, allowing retrieval of function pointers from named type slots when using the limited API. (Contributed by Martin von Löwis in bpo-17162 [https://bugs.python.org/issue?@action=redirect&bpo=17162].)

The new Py_SetStandardStreamEncoding() pre-initialization API allows applications embedding the CPython interpreter to reliably force a particular encoding and error handler for the standard streams. (Contributed by Bastien Montagne and Nick Coghlan in bpo-16129 [https://bugs.python.org/issue?@action=redirect&bpo=16129].)

Most Python C APIs that don’t mutate string arguments are now correctly marked as accepting const char * rather than char *. (Contributed by Serhiy Storchaka in bpo-1772673 [https://bugs.python.org/issue?@action=redirect&bpo=1772673].)

A new shell version of python-config can be used even when a python interpreter is not available (for example, in cross compilation scenarios).

PyUnicode_FromFormat() now supports width and precision specifications for %s, %A, %U, %V, %S, and %R. (Contributed by Ysj Ray and Victor Stinner in bpo-7330 [https://bugs.python.org/issue?@action=redirect&bpo=7330].)

New function PyStructSequence_InitType2() supplements the existing PyStructSequence_InitType() function. The difference is that it returns 0 on success and -1 on failure.

The CPython source can now be compiled using the address sanity checking features of recent versions of GCC and clang: the false alarms in the small object allocator have been silenced. (Contributed by Dhiru Kholia in bpo-18596 [https://bugs.python.org/issue?@action=redirect&bpo=18596].)

The Windows build now uses Address Space Layout Randomization [https://en.wikipedia.org/wiki/Address_space_layout_randomization] and Data Execution Prevention [https://en.wikipedia.org/wiki/Data_Execution_Prevention]. (Contributed by Christian Heimes in bpo-16632 [https://bugs.python.org/issue?@action=redirect&bpo=16632].)

New function PyObject_LengthHint() is the C API equivalent of operator.length_hint(). (Contributed by Armin Ronacher in bpo-16148 [https://bugs.python.org/issue?@action=redirect&bpo=16148].)

Other Improvements

The python command has a new option, -I, which causes it to run in «isolated mode», which means that sys.path contains neither the script’s directory nor the user’s site-packages directory, and all PYTHON* environment variables are ignored (it implies both -s and -E). Other restrictions may also be applied in the future, with the goal being to isolate the execution of a script from the user’s environment. This is appropriate, for example, when Python is used to run a system script. On most POSIX systems it can and should be used in the #! line of system scripts. (Contributed by Christian Heimes in bpo-16499 [https://bugs.python.org/issue?@action=redirect&bpo=16499].)

Tab-completion is now enabled by default in the interactive interpreter on systems that support readline. History is also enabled by default, and is written to (and read from) the file ~/.python-history. (Contributed by Antoine Pitrou and Éric Araujo in bpo-5845 [https://bugs.python.org/issue?@action=redirect&bpo=5845].)

Invoking the Python interpreter with --version now outputs the version to standard output instead of standard error (bpo-18338 [https://bugs.python.org/issue?@action=redirect&bpo=18338]). Similar changes were made to argparse (bpo-18920 [https://bugs.python.org/issue?@action=redirect&bpo=18920]) and other modules that have script-like invocation capabilities (bpo-18922 [https://bugs.python.org/issue?@action=redirect&bpo=18922]).

The CPython Windows installer now adds .py to the PATHEXT variable when extensions are registered, allowing users to run a python script at the windows command prompt by just typing its name without the .py extension. (Contributed by Paul Moore in bpo-18569 [https://bugs.python.org/issue?@action=redirect&bpo=18569].)

A new make target coverage-report [https://devguide.python.org/coverage/#measuring-coverage-of-c-code-with-gcov-and-lcov] will build python, run the test suite, and generate an HTML coverage report for the C codebase using gcov and lcov [http://ltp.sourceforge.net/coverage/lcov.php].

The -R option to the python regression test suite now also checks for memory allocation leaks, using sys.getallocatedblocks(). (Contributed by Antoine Pitrou in bpo-13390 [https://bugs.python.org/issue?@action=redirect&bpo=13390].)

python -m now works with namespace packages.

The stat module is now implemented in C, which means it gets the values for its constants from the C header files, instead of having the values hard-coded in the python module as was previously the case.

Loading multiple python modules from a single OS module (.so, .dll) now works correctly (previously it silently returned the first python module in the file). (Contributed by Václav Šmilauer in bpo-16421 [https://bugs.python.org/issue?@action=redirect&bpo=16421].)

A new opcode, LOAD_CLASSDEREF, has been added to fix a bug in the loading of free variables in class bodies that could be triggered by certain uses of __prepare__. (Contributed by Benjamin Peterson in bpo-17853 [https://bugs.python.org/issue?@action=redirect&bpo=17853].)

A number of MemoryError-related crashes were identified and fixed by Victor Stinner using his PEP 445 [https://www.python.org/dev/peps/pep-0445]-based pyfailmalloc tool (bpo-18408 [https://bugs.python.org/issue?@action=redirect&bpo=18408], bpo-18520 [https://bugs.python.org/issue?@action=redirect&bpo=18520]).

The pyvenv command now accepts a --copies option to use copies rather than symlinks even on systems where symlinks are the default. (Contributed by Vinay Sajip in bpo-18807 [https://bugs.python.org/issue?@action=redirect&bpo=18807].)

The pyvenv command also accepts a --without-pip option to suppress the otherwise-automatic bootstrapping of pip into the virtual environment. (Contributed by Nick Coghlan in bpo-19552 [https://bugs.python.org/issue?@action=redirect&bpo=19552] as part of the PEP 453 [https://www.python.org/dev/peps/pep-0453] implementation.)

The encoding name is now optional in the value set for the PYTHONIOENCODING environment variable. This makes it possible to set just the error handler, without changing the default encoding. (Contributed by Serhiy Storchaka in bpo-18818 [https://bugs.python.org/issue?@action=redirect&bpo=18818].)

The bz2, lzma, and gzip module open functions now support x (exclusive creation) mode. (Contributed by Tim Heaney and Vajrasky Kok in bpo-19201 [https://bugs.python.org/issue?@action=redirect&bpo=19201], bpo-19222 [https://bugs.python.org/issue?@action=redirect&bpo=19222], and bpo-19223 [https://bugs.python.org/issue?@action=redirect&bpo=19223].)

Significant Optimizations

The UTF-32 decoder is now 3x to 4x faster. (Contributed by Serhiy Storchaka in bpo-14625 [https://bugs.python.org/issue?@action=redirect&bpo=14625].)

The cost of hash collisions for sets is now reduced. Each hash table probe now checks a series of consecutive, adjacent key/hash pairs before continuing to make random probes through the hash table. This exploits cache locality to make collision resolution less expensive. The collision resolution scheme can be described as a hybrid of linear probing and open addressing. The number of additional linear probes defaults to nine. This can be changed at compile-time by defining LINEAR_PROBES to be any value. Set LINEAR_PROBES=0 to turn-off linear probing entirely. (Contributed by Raymond Hettinger in bpo-18771 [https://bugs.python.org/issue?@action=redirect&bpo=18771].)

The interpreter starts about 30% faster. A couple of measures lead to the speedup. The interpreter loads fewer modules on startup, e.g. the re, collections and locale modules and their dependencies are no longer imported by default. The marshal module has been improved to load compiled Python code faster. (Contributed by Antoine Pitrou, Christian Heimes and Victor Stinner in bpo-19219 [https://bugs.python.org/issue?@action=redirect&bpo=19219], bpo-19218 [https://bugs.python.org/issue?@action=redirect&bpo=19218], bpo-19209 [https://bugs.python.org/issue?@action=redirect&bpo=19209], bpo-19205 [https://bugs.python.org/issue?@action=redirect&bpo=19205] and bpo-9548 [https://bugs.python.org/issue?@action=redirect&bpo=9548].)

bz2.BZ2File is now as fast or faster than the Python2 version for most cases. lzma.LZMAFile has also been optimized. (Contributed by Serhiy Storchaka and Nadeem Vawda in bpo-16034 [https://bugs.python.org/issue?@action=redirect&bpo=16034].)

random.getrandbits() is 20%-40% faster for small integers (the most common use case). (Contributed by Serhiy Storchaka in bpo-16674 [https://bugs.python.org/issue?@action=redirect&bpo=16674].)

By taking advantage of the new storage format for strings, pickling of strings is now significantly faster. (Contributed by Victor Stinner and Antoine Pitrou in bpo-15596 [https://bugs.python.org/issue?@action=redirect&bpo=15596].)

A performance issue in io.FileIO.readall() has been solved. This particularly affects Windows, and significantly speeds up the case of piping significant amounts of data through subprocess. (Contributed by Richard Oudkerk in bpo-15758 [https://bugs.python.org/issue?@action=redirect&bpo=15758].)

html.escape() is now 10x faster. (Contributed by Matt Bryant in bpo-18020 [https://bugs.python.org/issue?@action=redirect&bpo=18020].)

On Windows, the native VirtualAlloc is now used instead of the CRT malloc in obmalloc. Artificial benchmarks show about a 3% memory savings.

os.urandom() now uses a lazily-opened persistent file descriptor so as to avoid using many file descriptors when run in parallel from multiple threads. (Contributed by Antoine Pitrou in bpo-18756 [https://bugs.python.org/issue?@action=redirect&bpo=18756].)

Deprecated

This section covers various APIs and other features that have been deprecated in Python 3.4, and will be removed in Python 3.5 or later. In most (but not all) cases, using the deprecated APIs will produce a DeprecationWarning when the interpreter is run with deprecation warnings enabled (for example, by using -Wd).

Deprecations in the Python API

As mentioned in PEP 451: A ModuleSpec Type for the Import System, a number of importlib methods and functions are deprecated: importlib.find_loader() is replaced by importlib.util.find_spec(); importlib.machinery.PathFinder.find_module() is replaced by importlib.machinery.PathFinder.find_spec(); importlib.abc.MetaPathFinder.find_module() is replaced by importlib.abc.MetaPathFinder.find_spec(); importlib.abc.PathEntryFinder.find_loader() and find_module() are replaced by importlib.abc.PathEntryFinder.find_spec(); all of the xxxLoader ABC load_module methods (importlib.abc.Loader.load_module(), importlib.abc.InspectLoader.load_module(), importlib.abc.FileLoader.load_module(), importlib.abc.SourceLoader.load_module()) should no longer be implemented, instead loaders should implement an exec_module method (importlib.abc.Loader.exec_module(), importlib.abc.InspectLoader.exec_module() importlib.abc.SourceLoader.exec_module()) and let the import system take care of the rest; and importlib.abc.Loader.module_repr(), importlib.util.module_for_loader(), importlib.util.set_loader(), and importlib.util.set_package() are no longer needed because their functions are now handled automatically by the import system.

The imp module is pending deprecation. To keep compatibility with Python 2/3 code bases, the module’s removal is currently not scheduled.

The formatter module is pending deprecation and is slated for removal in Python 3.6.

MD5 as the default digestmod for the hmac.new() function is deprecated. Python 3.6 will require an explicit digest name or constructor as digestmod argument.

The internal Netrc class in the ftplib module has been documented as deprecated in its docstring for quite some time. It now emits a DeprecationWarning and will be removed completely in Python 3.5.

The undocumented endtime argument to subprocess.Popen.wait() should not have been exposed and is hopefully not in use; it is deprecated and will mostly likely be removed in Python 3.5.

The strict argument of HTMLParser is deprecated.

The plistlib readPlist(), writePlist(), readPlistFromBytes(), and writePlistToBytes() functions are deprecated in favor of the corresponding new functions load(), dump(), loads(), and dumps(). Data() is deprecated in favor of just using the bytes constructor.

The sysconfig key SO is deprecated, it has been replaced by EXT_SUFFIX.

The U mode accepted by various open functions is deprecated. In Python3 it does not do anything useful, and should be replaced by appropriate uses of io.TextIOWrapper (if needed) and its newline argument.

The parser argument of xml.etree.ElementTree.iterparse() has been deprecated, as has the html argument of XMLParser(). To prepare for the removal of the latter, all arguments to XMLParser should be passed by keyword.

Deprecated Features

Running IDLE with the -n flag (no subprocess) is deprecated. However, the feature will not be removed until bpo-18823 [https://bugs.python.org/issue?@action=redirect&bpo=18823] is resolved.

The site module adding a «site-python» directory to sys.path, if it exists, is deprecated (bpo-19375 [https://bugs.python.org/issue?@action=redirect&bpo=19375]).

Removed

Operating Systems No Longer Supported

Support for the following operating systems has been removed from the source and build tools:

OS/2 (bpo-16135 [https://bugs.python.org/issue?@action=redirect&bpo=16135]).

Windows 2000 (changeset e52df05b496a).

Windows systems where COMSPEC points to command.com (bpo-14470 [https://bugs.python.org/issue?@action=redirect&bpo=14470]).

VMS (bpo-16136 [https://bugs.python.org/issue?@action=redirect&bpo=16136]).

API and Feature Removals

The following obsolete and previously deprecated APIs and features have been removed:

The unmaintained Misc/TextMate and Misc/vim directories have been removed (see the devguide [https://devguide.python.org] for suggestions on what to use instead).

The SO makefile macro is removed (it was replaced by the SHLIB_SUFFIX and EXT_SUFFIX macros) (bpo-16754 [https://bugs.python.org/issue?@action=redirect&bpo=16754]).

The PyThreadState.tick_counter field has been removed; its value has been meaningless since Python 3.2, when the «new GIL» was introduced (bpo-19199 [https://bugs.python.org/issue?@action=redirect&bpo=19199]).

PyLoader and PyPycLoader have been removed from importlib. (Contributed by Taras Lyapun in bpo-15641 [https://bugs.python.org/issue?@action=redirect&bpo=15641].)

The strict argument to HTTPConnection and HTTPSConnection has been removed. HTTP 0.9-style «Simple Responses» are no longer supported.

The deprecated urllib.request.Request getter and setter methods add_data, has_data, get_data, get_type, get_host, get_selector, set_proxy, get_origin_req_host, and is_unverifiable have been removed (use direct attribute access instead).

Support for loading the deprecated TYPE_INT64 has been removed from marshal. (Contributed by Dan Riti in bpo-15480 [https://bugs.python.org/issue?@action=redirect&bpo=15480].)

inspect.Signature: positional-only parameters are now required to have a valid name.

object.__format__() no longer accepts non-empty format strings, it now raises a TypeError instead. Using a non-empty string has been deprecated since Python 3.2. This change has been made to prevent a situation where previously working (but incorrect) code would start failing if an object gained a __format__ method, which means that your code may now raise a TypeError if you are using an 's' format code with objects that do not have a __format__ method that handles it. See bpo-7994 [https://bugs.python.org/issue?@action=redirect&bpo=7994] for background.

difflib.SequenceMatcher.isbjunk() and difflib.SequenceMatcher.isbpopular() were deprecated in 3.2, and have now been removed: use x in sm.bjunk and x in sm.bpopular, where sm is a SequenceMatcher object (bpo-13248 [https://bugs.python.org/issue?@action=redirect&bpo=13248]).

Code Cleanups

The unused and undocumented internal Scanner class has been removed from the pydoc module.

The private and effectively unused _gestalt module has been removed, along with the private platform functions _mac_ver_lookup, _mac_ver_gstalt, and _bcd2str, which would only have ever been called on badly broken OSX systems (see bpo-18393 [https://bugs.python.org/issue?@action=redirect&bpo=18393]).

The hardcoded copies of certain stat constants that were included in the tarfile module namespace have been removed.

Porting to Python 3.4

This section lists previously described changes and other bugfixes that may require changes to your code.

Changes in “python” Command Behavior

In a posix shell, setting the PATH environment variable to an empty value is equivalent to not setting it at all. However, setting PYTHONPATH to an empty value was not equivalent to not setting it at all: setting PYTHONPATH to an empty value was equivalent to setting it to ., which leads to confusion when reasoning by analogy to how PATH works. The behavior now conforms to the posix convention for PATH.

The [X refs, Y blocks] output of a debug (--with-pydebug) build of the CPython interpreter is now off by default. It can be re-enabled using the -X showrefcount option. (Contributed by Ezio Melotti in bpo-17323 [https://bugs.python.org/issue?@action=redirect&bpo=17323].)

The python command and most stdlib scripts (as well as argparse) now output --version information to stdout instead of stderr (for issue list see Other Improvements above).

Changes in the Python API

The ABCs defined in importlib.abc now either raise the appropriate exception or return a default value instead of raising NotImplementedError blindly. This will only affect code calling super() and falling through all the way to the ABCs. For compatibility, catch both NotImplementedError or the appropriate exception as needed.

The module type now initializes the __package__ and __loader__ attributes to None by default. To determine if these attributes were set in a backwards-compatible fashion, use e.g. getattr(module, '__loader__', None) is not None. (bpo-17115 [https://bugs.python.org/issue?@action=redirect&bpo=17115].)

importlib.util.module_for_loader() now sets __loader__ and __package__ unconditionally to properly support reloading. If this is not desired then you will need to set these attributes manually. You can use importlib.util.module_to_load() for module management.

Import now resets relevant attributes (e.g. __name__, __loader__, __package__, __file__, __cached__) unconditionally when reloading. Note that this restores a pre-3.3 behavior in that it means a module is re-found when re-loaded (bpo-19413 [https://bugs.python.org/issue?@action=redirect&bpo=19413]).

Frozen packages no longer set __path__ to a list containing the package name, they now set it to an empty list. The previous behavior could cause the import system to do the wrong thing on submodule imports if there was also a directory with the same name as the frozen package. The correct way to determine if a module is a package or not is to use hasattr(module, '__path__') (bpo-18065 [https://bugs.python.org/issue?@action=redirect&bpo=18065]).

Frozen modules no longer define a __file__ attribute. It’s semantically incorrect for frozen modules to set the attribute as they are not loaded from any explicit location. If you must know that a module comes from frozen code then you can see if the module’s __spec__.location is set to 'frozen', check if the loader is a subclass of importlib.machinery.FrozenImporter, or if Python 2 compatibility is necessary you can use imp.is_frozen().

py_compile.compile() now raises FileExistsError if the file path it would write to is a symlink or a non-regular file. This is to act as a warning that import will overwrite those files with a regular file regardless of what type of file path they were originally.

importlib.abc.SourceLoader.get_source() no longer raises ImportError when the source code being loaded triggers a SyntaxError or UnicodeDecodeError. As ImportError is meant to be raised only when source code cannot be found but it should, it was felt to be over-reaching/overloading of that meaning when the source code is found but improperly structured. If you were catching ImportError before and wish to continue to ignore syntax or decoding issues, catch all three exceptions now.

functools.update_wrapper() and functools.wraps() now correctly set the __wrapped__ attribute to the function being wrapped, even if that function also had its __wrapped__ attribute set. This means __wrapped__ attributes now correctly link a stack of decorated functions rather than every __wrapped__ attribute in the chain referring to the innermost function. Introspection libraries that assumed the previous behaviour was intentional can use inspect.unwrap() to access the first function in the chain that has no __wrapped__ attribute.

inspect.getfullargspec() has been reimplemented on top of inspect.signature() and hence handles a much wider variety of callable objects than it did in the past. It is expected that additional builtin and extension module callables will gain signature metadata over the course of the Python 3.4 series. Code that assumes that inspect.getfullargspec() will fail on non-Python callables may need to be adjusted accordingly.

importlib.machinery.PathFinder now passes on the current working directory to objects in sys.path_hooks for the empty string. This results in sys.path_importer_cache never containing '', thus iterating through sys.path_importer_cache based on sys.path will not find all keys. A module’s __file__ when imported in the current working directory will also now have an absolute path, including when using -m with the interpreter (except for __main__.__file__ when a script has been executed directly using a relative path) (Contributed by Brett Cannon in bpo-18416 [https://bugs.python.org/issue?@action=redirect&bpo=18416]). is specified on the command-line) (bpo-18416 [https://bugs.python.org/issue?@action=redirect&bpo=18416]).

The removal of the strict argument to HTTPConnection and HTTPSConnection changes the meaning of the remaining arguments if you are specifying them positionally rather than by keyword. If you’ve been paying attention to deprecation warnings your code should already be specifying any additional arguments via keywords.

Strings between from __future__ import ... statements now always raise a SyntaxError. Previously if there was no leading docstring, an interstitial string would sometimes be ignored. This brings CPython into compliance with the language spec; Jython and PyPy already were. (bpo-17434 [https://bugs.python.org/issue?@action=redirect&bpo=17434]).

ssl.SSLSocket.getpeercert() and ssl.SSLSocket.do_handshake() now raise an OSError with ENOTCONN when the SSLSocket is not connected, instead of the previous behavior of raising an AttributeError. In addition, getpeercert() will raise a ValueError if the handshake has not yet been done.

base64.b32decode() now raises a binascii.Error when the input string contains non-b32-alphabet characters, instead of a TypeError. This particular TypeError was missed when the other TypeErrors were converted. (Contributed by Serhiy Storchaka in bpo-18011 [https://bugs.python.org/issue?@action=redirect&bpo=18011].) Note: this change was also inadvertently applied in Python 3.3.3.

The file attribute is now automatically closed when the creating cgi.FieldStorage instance is garbage collected. If you were pulling the file object out separately from the cgi.FieldStorage instance and not keeping the instance alive, then you should either store the entire cgi.FieldStorage instance or read the contents of the file before the cgi.FieldStorage instance is garbage collected.

Calling read or write on a closed SSL socket now raises an informative ValueError rather than the previous more mysterious AttributeError (bpo-9177 [https://bugs.python.org/issue?@action=redirect&bpo=9177]).

slice.indices() no longer produces an OverflowError for huge values. As a consequence of this fix, slice.indices() now raises a ValueError if given a negative length; previously it returned nonsense values (bpo-14794 [https://bugs.python.org/issue?@action=redirect&bpo=14794]).

The complex constructor, unlike the cmath functions, was incorrectly accepting float values if an object’s __complex__ special method returned one. This now raises a TypeError. (bpo-16290 [https://bugs.python.org/issue?@action=redirect&bpo=16290].)

The int constructor in 3.2 and 3.3 erroneously accepts float values for the base parameter. It is unlikely anyone was doing this, but if so, it will now raise a TypeError (bpo-16772 [https://bugs.python.org/issue?@action=redirect&bpo=16772]).

Defaults for keyword-only arguments are now evaluated after defaults for regular keyword arguments, instead of before. Hopefully no one wrote any code that depends on the previous buggy behavior (bpo-16967 [https://bugs.python.org/issue?@action=redirect&bpo=16967]).

Stale thread states are now cleared after fork(). This may cause some system resources to be released that previously were incorrectly kept perpetually alive (for example, database connections kept in thread-local storage). (bpo-17094 [https://bugs.python.org/issue?@action=redirect&bpo=17094].)

Parameter names in __annotations__ dicts are now mangled properly, similarly to __kwdefaults__. (Contributed by Yury Selivanov in bpo-20625 [https://bugs.python.org/issue?@action=redirect&bpo=20625].)

hashlib.hash.name now always returns the identifier in lower case. Previously some builtin hashes had uppercase names, but now that it is a formal public interface the naming has been made consistent (bpo-18532 [https://bugs.python.org/issue?@action=redirect&bpo=18532]).

Because unittest.TestSuite now drops references to tests after they are run, test harnesses that re-use a TestSuite to re-run a set of tests may fail. Test suites should not be re-used in this fashion since it means state is retained between test runs, breaking the test isolation that unittest is designed to provide. However, if the lack of isolation is considered acceptable, the old behavior can be restored by creating a TestSuite subclass that defines a _removeTestAtIndex method that does nothing (see TestSuite.__iter__()) (bpo-11798 [https://bugs.python.org/issue?@action=redirect&bpo=11798]).

unittest now uses argparse for command line parsing. There are certain invalid command forms that used to work that are no longer allowed; in theory this should not cause backward compatibility issues since the disallowed command forms didn’t make any sense and are unlikely to be in use.

The re.split(), re.findall(), and re.sub() functions, and the group() and groups() methods of match objects now always return a bytes object when the string to be matched is a bytes-like object. Previously the return type matched the input type, so if your code was depending on the return value being, say, a bytearray, you will need to change your code.

audioop functions now raise an error immediately if passed string input, instead of failing randomly later on (bpo-16685 [https://bugs.python.org/issue?@action=redirect&bpo=16685]).

The new convert_charrefs argument to HTMLParser currently defaults to False for backward compatibility, but will eventually be changed to default to True. It is recommended that you add this keyword, with the appropriate value, to any HTMLParser calls in your code (bpo-13633 [https://bugs.python.org/issue?@action=redirect&bpo=13633]).

Since the digestmod argument to the hmac.new() function will in the future have no default, all calls to hmac.new() should be changed to explicitly specify a digestmod (bpo-17276 [https://bugs.python.org/issue?@action=redirect&bpo=17276]).

Calling sysconfig.get_config_var() with the SO key, or looking SO up in the results of a call to sysconfig.get_config_vars() is deprecated. This key should be replaced by EXT_SUFFIX or SHLIB_SUFFIX, depending on the context (bpo-19555 [https://bugs.python.org/issue?@action=redirect&bpo=19555]).

Any calls to open functions that specify U should be modified. U is ineffective in Python3 and will eventually raise an error if used. Depending on the function, the equivalent of its old Python2 behavior can be achieved using either a newline argument, or if necessary by wrapping the stream in TextIOWrapper to use its newline argument (bpo-15204 [https://bugs.python.org/issue?@action=redirect&bpo=15204]).

If you use pyvenv in a script and desire that pip not be installed, you must add --without-pip to your command invocation.

The default behavior of json.dump() and json.dumps() when an indent is specified has changed: it no longer produces trailing spaces after the item separating commas at the ends of lines. This will matter only if you have tests that are doing white-space-sensitive comparisons of such output (bpo-16333 [https://bugs.python.org/issue?@action=redirect&bpo=16333]).

doctest now looks for doctests in extension module __doc__ strings, so if your doctest test discovery includes extension modules that have things that look like doctests in them you may see test failures you’ve never seen before when running your tests (bpo-3158 [https://bugs.python.org/issue?@action=redirect&bpo=3158]).

The collections.abc module has been slightly refactored as part of the Python startup improvements. As a consequence of this, it is no longer the case that importing collections automatically imports collections.abc. If your program depended on the (undocumented) implicit import, you will need to add an explicit import collections.abc (bpo-20784 [https://bugs.python.org/issue?@action=redirect&bpo=20784]).

Changes in the C API

PyEval_EvalFrameEx(), PyObject_Repr(), and PyObject_Str(), along with some other internal C APIs, now include a debugging assertion that ensures they are not used in situations where they may silently discard a currently active exception. In cases where discarding the active exception is expected and desired (for example, because it has already been saved locally with PyErr_Fetch() or is being deliberately replaced with a different exception), an explicit PyErr_Clear() call will be needed to avoid triggering the assertion when invoking these operations (directly or indirectly) and running against a version of Python that is compiled with assertions enabled.

PyErr_SetImportError() now sets TypeError when its msg argument is not set. Previously only NULL was returned with no exception set.

The result of the PyOS_ReadlineFunctionPointer callback must now be a string allocated by PyMem_RawMalloc() or PyMem_RawRealloc(), or NULL if an error occurred, instead of a string allocated by PyMem_Malloc() or PyMem_Realloc() (bpo-16742 [https://bugs.python.org/issue?@action=redirect&bpo=16742])

PyThread_set_key_value() now always set the value. In Python 3.3, the function did nothing if the key already exists (if the current value is a non-NULL pointer).

The f_tstate (thread state) field of the PyFrameObject structure has been removed to fix a bug: see bpo-14432 [https://bugs.python.org/issue?@action=redirect&bpo=14432] for the rationale.

Changed in 3.4.3

PEP 476: Enabling certificate verification by default for stdlib http clients

http.client and modules which use it, such as urllib.request and xmlrpc.client, will now verify that the server presents a certificate which is signed by a CA in the platform trust store and whose hostname matches the hostname being requested by default, significantly improving security for many applications.

For applications which require the old previous behavior, they can pass an alternate context:

import urllib.request
import ssl

# This disables all verification
context = ssl._create_unverified_context()

# This allows using a specific certificate for the host, which doesn't need
# to be in the trust store
context = ssl.create_default_context(cafile="/path/to/file.crt")

urllib.request.urlopen("https://invalid-cert", context=context)

Que novedades hay en python 3.3

Éste artículo explica las nuevas características en python 3.3, en comparación con la versión 3.2. Python 3.3 se lanzó el 29 de septiembre de 2012. Para más detalles, ver el log de cambios en la dirección <https://docs.python.org/3.3/whatsnew/changelog.html>.

Ver también

PEP 398 [https://www.python.org/dev/peps/pep-0398] - Calendario de Publicación Python 3.3

Resumen – aspectos destacados de la versión

Nuevas características de sintaxis:

Nueva expresión yield from para delegación de generadores.

La sintaxis u'unicode' se acepta de nuevo para los objetos str.

Nuevos módulos de biblioteca:

faulthandler (ayuda a depurar bloqueos de bajo nivel)

ipaddress (Objetos de alto nivel que representan direcciones IP y máscaras)

lzma (comprime datos usando el algoritmo XZ / LZMA)

unittest.mock (Utiliza objetos que simulen partes de tu sistema en ambiente de pruebas)

venv (Python entornos virtuales, como en el paquete original Virtualenv)

Nuevas características incorporadas:

Se re elabora Jerarquía de excepción I/O .

Mejoras de implementación:

Se reescribe Maquinaria de importación con base en importlib.

cadenas de caracteres unicode más compactas.

diccionarios de atributos más compactos.

Módulos de biblioteca con mejoras significativas:

Acelerador de C para el módulo decimal .

Mejor gestión de unicode en el módulo email (provisional).

Mejoras de seguridad:

La aleatoriedad en los hash está habilitada de forma predeterminada.

Por favor continúa leyendo para obtener una lista completa de los cambios de cara al usuario.

PEP 405: Entornos virtuales

Los entornos virtuales ayudan a crear instalaciones individuales de python que comparten la instalación base del sistema, ésto con la finalidad de facilitar el mantenimiento de las aplicaciones. Los entornos virtuales tienen su propio conjunto privado de paquetes de sitio (es decir, bibliotecas instaladas localmente), y opcionalmente van separados de los paquetes de sitio del sistema completo. Su concepto e implementación están inspirados en el popular paquete de terceros virtualenv, pero cuenta con una integración más completa gracias al núcleo del intérprete.

Este PEP agrega el módulo venv para acceso programático, y el script pyvenv para administración y acceso a través de línea de comandos. El intérprete de python busca un archivo llamado pyvenv.cfg, cuya existencia señala la base de un árbol de directorios en el entorno virtual.

Ver también

PEP 405 [https://www.python.org/dev/peps/pep-0405] - Entornos virtuales en python

PEP escrito por Carl Meyer; implementación por Carl Meyer y Vinay Sajip

PEP 420: Paquetes para espacios de nombres implícitos

Soporte nativo para directorios de paquetes que no requieran el archivo __init.py__ y puedan abarcar automáticamente múltiples segmentos de rutas de acceso (Inspirado en varios enfoques de terceros para espacios de nombres de paquetes, tal como está especificado en PEP 420 [https://www.python.org/dev/peps/pep-0420])

Ver también

PEP 420 [https://www.python.org/dev/peps/pep-0420] - Paquetes de espacio de nombres implícitos

PEP escrito por Eric V. Smith; implementación por Eric V. Smith y Barry Warsaw

PEP 3118: Nueva implementación de vista de memoria y en la documentación del protocolo del buffer

La implementación del PEP 3118 [https://www.python.org/dev/peps/pep-3118] ha tenido mejoras significativas.

La nueva implementación de la vista de memoria corrige exhaustivamente todos los problemas de propiedad y duración de los campos asignados dinámicamente en la estructura de Py_buffer que ha dado lugar a varios informes de bloqueo. Además, se han corregido varias funciones que se bloquearon o retornaron resultados incorrectos para entradas no contigua o multidimensional.

El objeto de vista de memoria dispone ahora de PEP-3118 que obedece a getbufferproc(), el cual verifica el tipo de petición del cliente. Se han agregado nuevas características, la mayoría de ellas funcionan generalmente para arrays no contiguos y arrays con subindices.

La documentación se ha actualizado y se han establecido claramente las responsabilidades tanto para los exportadores como para los consumidores. Los indicadores de solicitud de buffer se agrupan en indicadores básicos y compuestos. Se explica el diseño de memoria de matrices de estilo NumPy no contiguas y multidimensionales.

Características

Ahora se admiten todos los especificadores nativos de formato de un solo carácter en la sintaxis del módulo de estructura (opcionalmente con el prefijo “@”).

Con algunas reestricciones, el método cast() permite cambiar el formato y forma de los arrays contiguos.

La representación de listas multidimensionales es aceptada por cualquier tipo de array.

Se admiten comparaciones multidimensionales para cualquier tipo de array.

Los objetos de vista de memoria unidimensionales de tipo hash con formatos B, b, o c ahora son hashables (Contribución por Antoine Pitrou en el issue 13411.)

Se admite el corte arbitrario de cualquier tipo de array unidimensional. Por ejemplo, ahora es posible revertir una vista de memoria en O(1) utilizando un valor negativo para el índice STEP.

Cambios en la API

Oficialmente, se limita el número máximo de dimensiones a 64.

Las formas vacías, pasos, y subíndices ahora son representados por una tupla vacía, en vez de None.

El acceso al elemento de una vista de memoria con formato “B” (bytes sin signo) ahora retorna un entero (de acuerdo con la sintaxis del módulo de estructura). Para retornar un objeto bytes, primero la vista debe ser convertida a «C».

las comparaciones de la vista de memoria ahora utilizan la estructura lógica de los operandos y comparan todos los elementos de array por valor. Se admiten todos los formatos strings en la sintaxis del módulo de estructura. Aún se admiten las vistas con strings que tengan un formato no reconocido, pero siempre se compararan como desiguales, independientemente del contenido de la vista.

Para más cambios, consulte Compilación y cambios en la API de C y Portabilidad del código C.

(Contribución por Stefan Krah en el issue 10181 .)

Ver también

PEP 3118 [https://www.python.org/dev/peps/pep-3118] - Revisando el protocolo de buffer

PEP 393: Representación flexible de cadenas de caracteres

El tipo de cadena Unicode es modificado para admitir múltiples representaciones internas, dependiendo del caracter con el ordinal Unicode más grande (1, 2 o 4 bytes) en la cadena representada. Esto permite una representación que ahorra espacio en casos comunes, pero da acceso a UCS-4 completo en todos los sistemas. Para compatibilidad con APIS existentes, pueden existir varias representaciones en paralelo; con el tiempo, esta compatibilidad debería eliminarse gradualmente.

Por parte de Python, no debería haber inconvenientes por éste cambio.

Por parte de la API de C, PEP 393 [https://www.python.org/dev/peps/pep-0393] es totalmente compatible con versiones anteriores. La API antigua debería quedar disponible al menos por cinco años. Las aplicaciones que usan la API antigua no saldrán beneficiadas por la reducción de memoria, o -peor- podrían usar un bit más de memoria, debido a que python necesitaría mantener dos versiones de cada cadena de caracteres (en el formato antiguo y en el nuevo almacenamiento)

Funcionalidad

Los cambios introducidos en el PEP 393 [https://www.python.org/dev/peps/pep-0393] son los siguientes:

Ahora python admite siempre el rango completo de códigos Unicode, incluyendo los que no son BMP (es decir, U+0000 to U+10FFFF). La distinción entre ancho y angosto ya no existe, y python se comporta ahora como una compilación amplia, incluso en sistemas windows.

Con la eliminación de las construcciones estrechas, han sido solucionados también los problemas específicos referentes a este tipo de construcciones, por ejemplo:

len() Ahora siempre retorna 1 para los caracteres que no son BMP, de modo que len('\U0010FFFF') == 1;

los pares sustitutos no se recombinan en cadenas literales, de modo que '\uDBFF\uDFFF' != '\U0010FFFF';

la indexación o el corte de caracteres que no son BMP, retorna el valor esperado, de modo que '\U0010FFFF'[0] ahora retorna '\U0010FFFF' y no '\uDBFF';

todas las demás funciones en la librería estándar ahora gestionan de forma correcta los puntos de código que no son BMP.

El valor de sys.maxunicode ahora siempre es 1114111 (0x10FFFF en hexadecimal). La función PyUnicode_GetMax() aún retorna el valor 0xFFFF o el valor 0x10FFFF para compatibilidad con versiones anteriores, y no debe usarse con la nueva API Unicode (ver bpo-13054 [https://bugs.python.org/issue?@action=redirect&bpo=13054]).

Se ha eliminado el indicador :file:”./configure” “”–with-wide-unicode””.

Rendimiento y uso de recursos

El almacenamiento de las cadenas Unicode ahora depende del punto de código más alto en la cadena:

las cadenas de caracteres en ASCII puro y Latin1 (U+0000-U+00FF) usan 1 byte por punto de código;

Las cadenas de caracteres BMP (U+0000-U+FFFF) usan 2 bytes por punto de código;

las cadenas de caracteres que no son BMP (U+10000-U+10FFFF) usan 4 bytes por punto de código.

El efecto neto es que para la mayoría de las aplicaciones, el uso de memoria del almacenamiento de cadenas de caracteres debería disminuir significativamente, especialmente en comparación con las construcciones unicode anchas, ya que, en muchos casos, las cadenas serán ASCII puro incluso en contextos internacionales (porque muchas cadenas almacenan datos en lenguaje no humano, tal como fragmentos XML, encabezados HTTP, datos codificados en JSON, etc.). También esperamos que, por las mismas razones, aumente la eficiencia de la caché de la CPU en aplicaciones no triviales. El uso de memoria de Python 3.3 es dos o tres veces más pequeño que Python 3.2, y un poco mejor que Python 2.7, en un punto de referencia de Django (consulte el PEP para obtener más detalles).

Ver también

PEP:393 - Representación flexible de cadenas de caracteres

PEP escrito por Martin von Lowis; implementado por Torsten Becker y Martin von Lowis.

PEP 397: Lanzador de python para windows

El instalador de Python 3.3 para windows ahora incluye una aplicación lanzadora py que puede ser utilizada para ejecutar aplicaciones python de forma independiente de la versión.

Este lanzador se invoca de forma implícita cuando haces doble click en archivos *.py. Si el sistema tiene instalada una única versión de python, ésta versión será usada para ejecutar el archivo. Si hay múltiples versiones instaladas en el sistema, se utilizara por defecto la versión más reciente pero ésto puede ser anulado incluyendo una «línea shebang» estilo Unix en el script de Python.

El lanzador también se puede usar explícitamente desde la línea de comando como la aplicación `` py “”. La ejecución de `` py “” sigue las mismas reglas de selección de versión que la ejecución implícita de scripts, pero se puede seleccionar una versión más específica pasando los argumentos apropiados (como `` -3 “” para solicitar Python 3 cuando Python 2 también está instalado, o `` -2.6 “” para solicitar específicamente una versión anterior de Python cuando se instala una versión más reciente).

Además del lanzador, el instalador de Windows ahora incluye una opción para agregar el Python recién instalado al PATH del sistema. (Contribución de Brian Curtin en bpo-3561 [https://bugs.python.org/issue?@action=redirect&bpo=3561].)

Ver también

PEP 397 [https://www.python.org/dev/peps/pep-0397] - Python Launcher for Windows

PEP escrito por Mark Hammond y Martin v. Löwis; implementado por Vinay Sajip.

Documentación del lanzador: Lanzador de Python para Windows

Modificación de la ruta del instalador: Encontrar el ejecutable de Python

PEP 3151: Reelaborando de la jerarquía de excepciones de IO y OS

La jerarquía de excepciones generada por errores del sistema operativo ahora está simplificada y es más detallada.

No tienes que preocuparte más por cómo elegir el tipo de excepción adecuado entre OSError, IOError, EnvironmentError, WindowsError, mmap.error, socket.error or select.error. Todos estos tipos de excepción son ahora una sola: OSError. Los otros nombres se mantienen como alias por razones de compatibilidad.

Además, ahora es más fácil detectar una condición de error específica. En lugar de inspeccionar el atributo errno (o args[0]) para una constante particular del módulo errno, puede seleccionar la subclase OSError adecuada. Las subclases disponibles son las siguientes:

BlockingIOError

ChildProcessError

ConnectionError

FileExistsError

FileNotFoundError

InterruptedError

IsADirectoryError

NotADirectoryError

PermissionError

ProcessLookupError

TimeoutError

Y el mismo ConnectionError tiene subclases más detalladas:

BrokenPipeError

ConnectionAbortedError

ConnectionRefusedError

ConnectionResetError

Gracias a las nuevas excepciones, los usos comunes de errno ahora se pueden evitar. Por ejemplo, el siguiente código escrito para Python 3.2:

from errno import ENOENT, EACCES, EPERM

try:
    with open("document.txt") as f:
        content = f.read()
except IOError as err:
    if err.errno == ENOENT:
        print("document.txt file is missing")
    elif err.errno in (EACCES, EPERM):
        print("You are not allowed to read document.txt")
    else:
        raise

ahora se pueden escribir sin la importación de errno y sin la inspección manual de atributos de excepción:

try:
    with open("document.txt") as f:
        content = f.read()
except FileNotFoundError:
    print("document.txt file is missing")
except PermissionError:
    print("You are not allowed to read document.txt")

Ver también

PEP 3151 [https://www.python.org/dev/peps/pep-3151] - Re elaboración de la jerarquía de excepciones de IO y OS

PEP escrito e implementado por Antoine Pitrou

PEP 380: Sintaxis para delegar en un subgenerador

PEP 380 agrega la expresión yield from, permitiendo que un generator delegue parte de sus operaciones a otro generador. Esto permite tomar en consideración una sección de código que contenga la palabra yield y ubicarla en otro generador. Además, el subgenerador puede regresar con un valor y el valor se pone a disposición del generador que delega.

Aunque está diseñada principalmente para su uso en la delegación a un subgenerador, la expresión yield from en realidad permite la delegación a subiteradores arbitrarios.

Para iteradores simples, yield from iterable es esencialmente una forma abreviada de for item in iterable: yield item:

>>> def g(x):
...     yield from range(x, 0, -1)
...     yield from range(x)
...
>>> list(g(5))
[5, 4, 3, 2, 1, 0, 1, 2, 3, 4]

Sin embargo, a diferencia de un ciclo ordinario, yield from permite que los subgeneradores reciban valores enviados y lanzados directamente desde el ámbito de la llamada y retornen un valor final al generador externo:

>>> def accumulate():
...     tally = 0
...     while 1:
...         next = yield
...         if next is None:
...             return tally
...         tally += next
...
>>> def gather_tallies(tallies):
...     while 1:
...         tally = yield from accumulate()
...         tallies.append(tally)
...
>>> tallies = []
>>> acc = gather_tallies(tallies)
>>> next(acc)  # Ensure the accumulator is ready to accept values
>>> for i in range(4):
...     acc.send(i)
...
>>> acc.send(None)  # Finish the first tally
>>> for i in range(5):
...     acc.send(i)
...
>>> acc.send(None)  # Finish the second tally
>>> tallies
[6, 10]

Lo más importante de éste cambio es permitir que incluso los generadores que están diseñados para ser usados con los métodos send y throw sean separados en múltiples subgeneradores tan fácilmente como las funciones grandes se pueden dividir en varias subfunciones.

Ver también

PEP 380 [https://www.python.org/dev/peps/pep-0380] - Sintaxis para delegar a un subgenerador

PEP escrito por Greg Ewing; implementación por Greg Ewing, integrado en 3.3 por Renaud Blanch, Ryan Kelly y Nick Coghlan; documentación de Zbigniew Jędrzejewski-Szmek y Nick Coghlan

PEP 409: Suprimir el contexto de excepción

PEP 409 introduce una nueva sintaxis que permite deshabilitar la visualización del contexto de excepción encadenado. Esto permite mensajes de error más limpios en aplicaciones que convierten entre tipos de excepción:

>>> class D:
...     def __init__(self, extra):
...         self._extra_attributes = extra
...     def __getattr__(self, attr):
...         try:
...             return self._extra_attributes[attr]
...         except KeyError:
...             raise AttributeError(attr) from None
...
>>> D({}).x
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 8, in __getattr__
AttributeError: x

Sin el sufijo from None para suprimir la causa, la excepción original se mostraría de forma predeterminada:

>>> class C:
...     def __init__(self, extra):
...         self._extra_attributes = extra
...     def __getattr__(self, attr):
...         try:
...             return self._extra_attributes[attr]
...         except KeyError:
...             raise AttributeError(attr)
...
>>> C({}).x
Traceback (most recent call last):
  File "<stdin>", line 6, in __getattr__
KeyError: 'x'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 8, in __getattr__
AttributeError: x

No se pierde ninguna capacidad de depuración, ya que el contexto de la excepción original permanece disponible en caso de ser necesario (por ejemplo, si una biblioteca suprime detalles importantes y valiosos de forma incorrecta)

>>> try:
...     D({}).x
... except AttributeError as exc:
...     print(repr(exc.__context__))
...
KeyError('x',)

Ver también

PEP 409 [https://www.python.org/dev/peps/pep-0409] - Supresión del contexto de excepción

PEP escrito por Ethan Furman; implementado por Ethan Furman y Nick Coghlan.

PEP 414: Literales Unicode explícitos

Para facilitar la transición de Python 2 para las aplicaciones de Python que reconocen Unicode y que hacen un uso intensivo de literales Unicode, Python 3.3 una vez más admite el prefijo «u» para cadenas literales. Este prefijo no tiene importancia semántica en Python 3, se proporciona únicamente para reducir el número de cambios puramente mecánicos en la migración a Python 3, lo que facilita a los desarrolladores centrarse en los cambios semánticos más significativos (como la separación predeterminada más estricta de binary y datos de texto).

Ver también

PEP 414 [https://www.python.org/dev/peps/pep-0414] - Literales Unicode Explícitos

PEP escrito por Armin Ronacher.

PEP 3155: Nombres calificados para clases y funciones

Las funciones y objetos de clases tienen un nuevo atributo __qualname__, que representa la ruta desde el nivel superior del módulo hasta su definición. Para funciones globales y clases, es lo mismo que __name__. Para otras funciones y clases, éste proporciona mejor información sobre donde han sido definidos realmente y como podrían ser accesibles desde un ámbito global.

Ejemplo con métodos (no vinculados):

>>> class C:
...     def meth(self):
...         pass
>>> C.meth.__name__
'meth'
>>> C.meth.__qualname__
'C.meth'

Ejemplo con clases anidadas:

>>> class C:
...     class D:
...         def meth(self):
...             pass
...
>>> C.D.__name__
'D'
>>> C.D.__qualname__
'C.D'
>>> C.D.meth.__name__
'meth'
>>> C.D.meth.__qualname__
'C.D.meth'

Ejemplo con funciones anidadas:

>>> def outer():
...     def inner():
...         pass
...     return inner
...
>>> outer().__name__
'inner'
>>> outer().__qualname__
'outer.<locals>.inner'

La representación en cadena de estos objetos, también se ha modificado para incluir la información nueva y más precisa:

>>> str(C.D)
"<class '__main__.C.D'>"
>>> str(C.D.meth)
'<function C.D.meth at 0x7f46b9fe31e0>'

Ver también

PEP 3155 [https://www.python.org/dev/peps/pep-3155] - Nombres calificados para clases y funciones

PEP Escrito e implementado por Antoine Pitrou.

PEP 412: Diccionario de intercambio de claves

Los diccionarios usados para almacenar atributos de objetos, ahora pueden compartir parte de su almacenamiento interno entre sí (a saber, la parte que almacena las claves y sus respectivos hashes). Esto reduce el consumo de memoria de programas creando varias instancias de tipos no integrados.

Ver también

PEP 412 [https://www.python.org/dev/peps/pep-0412] -Diccionario de intercambio de claves

PEP escrito e implementado por Mark Shannon.

PEP 362: Objeto de firma de función

Una nueva función inspect.signature() hace que la introspección de las llamadas de Python sea fácil y directa. Se admite una amplia gama de invocables: funciones python, decoradas o no, clases y objetos functools.partial(). Las Nuevas clases inspect.Signature, inspect.Parameter y inspect.BoundArguments contienen información sobre las firmas de llamadas, tales como anotaciones, valores por defecto, tipos de parámetros, y los argumentos vinculados, lo cual simplifica considerablemente la escritura de decoradores y de cualquier código que valide o modifique las firmas de llamadas o argumentos.

Ver también

PEP 362 [https://www.python.org/dev/peps/pep-0362]: - Objeto de firmas de función

PEP escrito por Brett Cannon, Yury Selivanov, Larry Hastings, Jiwon Seo; implementado por Yury Selivanov.

PEP 421: Agregar sys.implementation

Un nuevo atributo en el módulo sys expone detalles específicos de la implementación del intérprete que se ésta ejecutando en el momento actual. El conjunto inicial de atributos en sys.implementation son name, version, hexversion, y cache_tag.

La intención de sys.implementation es consolidar dentro de un espacio de nombres, la implementación específica de datos usado por la biblioteca estándar. Esto permite que diferentes implementaciones de python puedan compartir código de la biblioteca estándar de manera más fácil. En su estado inicial, sys.implementation contiene solo una pequeña porción de los datos específicos de la implementación. Con el tiempo esta proporción cambiará para hacer que la biblioteca estándar sea más portable..

Un ejemplo de mejor portabilidad de la biblioteca estándar es cache_tag. A partir de Python 3.3, sys.implementation.cache_tag es utilizado por importlib para admitir el cumplimiento PEP 3147 [https://www.python.org/dev/peps/pep-3147]. Cualquier implementación de Python que utilice importlib para su sistema de importación integrado puede usar cache_tag para controlar el comportamiento de almacenamiento en caché de los módulos.

SimpleNamespace

La implementación de sys.implementation también trae un nuevo tipo a Python: La clase types.SimpleNamespace. En comparación con un nombre de espacio basado en mapas, como dict, SimpleNamespace es basado en atributos, como object. Sin embargo a diferencia de object, las instancias de SimpleNamespace son editables. Esto significa que puedes agregar, eliminar, y modificar el nombre de espacio a través del acceso normal a los atributos.

Ver también

PEP 421 [https://www.python.org/dev/peps/pep-0421] - Agregar sys.implementation

PEP escrito e implementado por Mark Shannon.

Usar importlib como implementación de Import

bpo-2377 [https://bugs.python.org/issue?@action=redirect&bpo=2377]- Replace__import__w/ importlib.__import__ bpo-13959 [https://bugs.python.org/issue?@action=redirect&bpo=13959] - Re-implementar partes de imp en Python puro bpo-14605 [https://bugs.python.org/issue?@action=redirect&bpo=14605] - Hacer que la maquinaria de importación sea explícita bpo-14646 [https://bugs.python.org/issue?@action=redirect&bpo=14646] - Requerir que los cargadores establezcan __loader__ y __package__

La función __import__() ahora es potenciada por la función importlib.__import__(). Este trabajo conduce a completar la «fase 2» de PEP 302 [https://www.python.org/dev/peps/pep-0302]. Hay múltiples beneficios en éste cambio. En primer lugar, ha permitido que la mayoría de la maquinaria que potencia las importaciones sea expuesta, en vez de estar implícitas y ocultas en el código de C. También proporciona una única implementación para todas las máquinas virtuales de python que admitan el uso de Python 3.3 lo que ayuda a terminar con cualquier desviación específica de VM en la semántica de importación. Y finalmente facilita el mantenimiento de la importación, permitiendo que ocurra un crecimiento futuro.

Para el usuario común, no debería haber cambios visibles en la semántica. Para aquellos cuyo código realmente manipula la importación o las llamadas de importación de forma programática, los cambios de código que posiblemente sean necesarios, se tratan en la sección Porting Python code de éste documento.

Nuevas APIs

Uno de los grandes beneficios de éste trabajo es la exposición de lo que implica hacer que funcione la sentencia de importación. Esto significa que los varios importadores que una vez fueron implícitos, ahora son expuestos completamente como parte del paquete importlib.

Las clases base abstractas definidas en importlib.abc se han expandido para delimitar adecuadamente entre buscadores de rutas meta y buscadores de entrada de rutas al introducir la clase importlib.abc.MetaPathFinder y importlib.abc.PathEntryFinder respectivamente. El antiguo ABC de la clase importlib.abc.Finder ahora solo se proporciona para compatibilidad con versiones anteriores y no exige ningún requisito de método.

En términos de buscadores, importlib.machinery.FileFinder expone el mecanismo utilizado para buscar archivos fuente y de código de bytes de un módulo. Anteriormente, ésta clase era un miembro implícito de sys.path_hooks.

Para los cargadores, la nueva clase base abstracta importlib.abc.FileLoader ayuda a escribir un cargador que usa el sistema de archivos como mecanismo de almacenamiento para el código de un módulo. El cargador de archivos fuente (importlib.machinery.SourceFileLoader), archivos de código byte sin fuente (importlib.machinery.SourcelessFileLoader) y módulos de extensión (importlib.machinery.ExtensionFileLoader) ahora están disponibles para su uso directo.

ImportError ahora tiene los atributos name y path que se establecen cuando hay datos relevantes para proporcionar. También, el mensaje de importaciones fallidas ahora proporcionará el nombre completo del módulo en lugar de solo el final del nombre del mismo.

La función importlib.invalidate_caches() ahora llamará al método con el mismo nombre en todos los buscadores almacenados en sys.path_importer_cache para ayudar a limpiar cualquier estado almacenado según sea necesario.

Cambios visibles

Para conocer los posibles cambios necesarios en el código, consulte la sección Porting Python code .

Más allá de la extensión de lo que ahora expone importlib, hay otros cambios visibles para importar. El más grande es que sys.meta_path y sys.path_hooks ahora almacenan todos los buscadores de rutas meta y los ganchos de entrada de rutas usados por la importación. Anteriormente, los buscadores estaban implícitos y ocultos dentro del código C de importación en lugar de estar expuestos directamente. Esto significa que ahora uno puede eliminar o cambiar fácilmente el orden de los diversos buscadores para satisfacer sus necesidades.

Otro cambio es que todos los módulos tienen un atributo __loader__ que almacena el cargador usado para crear el módulo. La PEP 302 [https://www.python.org/dev/peps/pep-0302] se ha actualizado para hacer que este atributo sea obligatorio para implementar los cargadores, de manera que en el futuro, una vez que los cargadores de terceros hayan sido actualizados, las personas puedan confiar en la existencia de éste atributo. Sin embargo, hasta entonces la importación está configurando la post carga del módulo.

También se espera que ahora los cargadores establezcan el atributo __package__ de PEP 366 [https://www.python.org/dev/peps/pep-0366]. Una vez más, la importación por sí misma ya está configurando ésto en todos los cargadores del módulo importlib y la importación misma está configurando la post carga del atributo.

Ahora se incluye el atributo None dentro de sys.path_importer_cache cuando no se encuentre ningún buscador en sys.path_hooks. Dado que imp.NullImporter no está directamente expuesto en sys.path_hooks, podría no haber una certeza de que esté disponible para su uso como un valor que represente que no se ha encontrado ningún buscador.

Todos los demás cambios se relacionan con los cambios de semántica que deben tomarse en cuenta al actualizar el código a python 3.3, por lo tanto, deben leerse en la sección Portar código Python de este documento.

(Implementación por Brett Cannon)

Otros cambios de idioma

Algunos cambios más pequeños realizados en el lenguaje Python principal son:

Se ha añadido compatibilidad con alias de nombres Unicode y secuencias con nombre. Tanto unicodedata.lookup() como 'N{...}' ahora resuelven los alias de nombre, y unicodedata.lookup() también resuelve las secuencias con nombre.

(Contribución de Ezio Melotti en :issue:”12753”.)

Base de datos Unicode actualizada a la versión 6.1.0 de UCD

Las comparaciones de igualdad en los objetos range() ahora retornan un resultado que refleja la igualdad de las secuencias subyacentes generadas por esos objetos de rango. (bpo-13201 [https://bugs.python.org/issue?@action=redirect&bpo=13201])

Los métodos count(), find(), rfind(), index() y rindex() de los objetos bytes y bytearray ahora aceptan un entero entre 0 y 255 como su primer argumento.

(Contribución por Petri Lehtinen en bpo-12170 [https://bugs.python.org/issue?@action=redirect&bpo=12170].)

Los métodos rjust(), ljust(), y center() de bytes y bytearray ahora aceptan un bytearray para el argumento fill. (Contribución de Petri Lehtinen en bpo-12380 [https://bugs.python.org/issue?@action=redirect&bpo=12380].)

Se han agregado nuevos métodos a list y bytearray: copy() y clear() (bpo-10516 [https://bugs.python.org/issue?@action=redirect&bpo=10516]). En consecuencia, MutableSequence ahora también definen un método clear() (bpo-11388 [https://bugs.python.org/issue?@action=redirect&bpo=11388]).

Los literales de bytes sin formato ahora se pueden escribir rb"..." así como br"...".

(Contribución de Antoine Pitrou en bpo-13748 [https://bugs.python.org/issue?@action=redirect&bpo=13748].)

El método dict.setdefault() ahora solo hace una sola búsqueda de la clave dada, haciéndola atómica cuando se usa con tipos incorporados.

(Contribución de Filip Gruszczyński en bpo-13521 [https://bugs.python.org/issue?@action=redirect&bpo=13521].)

Los mensajes de error producidos cuando la llamada de una función no coincide con la firma han sido mejorados significativamente.

(Contribución de Benjamin Peterson.)

Un bloqueo de importación más detallado

Las versiones anteriores de CPython siempre se han basado en un bloqueo de importación global. Ésto conduce a problemas inesperados tales como bloqueos cuando la importación un módulo debería disparar la ejecución de código en un hilo diferente como un efecto secundario. A veces se empleaban soluciones torpes, como la función de API C PyImport_ImportModuleNoBlock() .

En Python 3.3, la importación de un módulo toma un bloqueo por módulo. Esto serializa correctamente la importación de un módulo determinado a partir de múltiples subprocesos (impidiendo la exposición de módulos inicializados incompletamente), mientras elimina las molestias antes mencionadas.

(Contribución de Antoine Pitrou en bpo-9260 [https://bugs.python.org/issue?@action=redirect&bpo=9260].)

Funciones y tipos incorporados

open() obtiene un nuevo parámetro opener: el descriptor de archivo subyacente para el objeto de archivo se obtiene llamando a opener con (file, flags). Se puede utilizar para utilizar banderas personalizadas como os.O_CLOEXEC, por ejemplo. Se ha añadido el modo 'x' : abierto para la creación exclusiva, fallando si el archivo ya existe.

print(): agregó el argumento de palabra clave flush. Si el argumento de palabra clave flush es verdadero, la secuencia se vacía por la fuerza.

hash(): hash randomization is enabled by default, see object.__hash__() and PYTHONHASHSEED.

El tipo str obtiene un nuevo método casefold(): retorna una copia de la cadena con mayúsculas y minúsculas, las cadenas con mayúsculas y minúsculas se pueden utilizar para la coincidencia sin mayúsculas. Por ejemplo, 'ß'.casefold() retorna 'ss'.

La documentación de secuencia se ha reescrito sustancialmente para explicar mejor la distinción de secuencia binaria/texto y para proporcionar secciones de documentación específicas para los tipos de secuencia individuales integrados(bpo-4966 [https://bugs.python.org/issue?@action=redirect&bpo=4966]).

Nuevos módulos

faulthandler

Este nuevo módulo de depuración faulthandler contiene funciones para volcar los rastreos de Python explícitamente, en una falla (como una falla de segmentación), después de un tiempo de espera o en una señal de usuario. Llame a faulthandler.enable() para instalar controladores de fallas para las señales SIGSEGV, SIGFPE, SIGABRT, SIGBUS, y SIGILL . También puede habilitarlos al inicio configurando la variable de entorno PYTHONFAULTHANDLER o usando la opción de línea de comandos -X faulthandler .

Ejemplo de una falla de segmentación en Linux:

$ python -q -X faulthandler
>>> import ctypes
>>> ctypes.string_at(0)
Fatal Python error: Segmentation fault

Current thread 0x00007fb899f39700:
  File "/home/python/cpython/Lib/ctypes/__init__.py", line 486 in string_at
  File "<stdin>", line 1 in <module>
Segmentation fault

ipaddress

El nuevo módulo ipaddress proporciona herramientas para crear y manipular objetos que representen direcciones, redes e interfaces IPv4 e IPv6 (es decir, alguna dirección IP asociada con una subred IP específica)

(Contribución de Google y Peter Moody en PEP 3144 [https://www.python.org/dev/peps/pep-3144] )

lzma

El módulo recién agregado lzma proporciona compresión y descompresión de datos usando el algoritmo LZMA, incluyendo compatibilidad para los formatos de archivos .xz y .lzma.

(Contribución de Nadeem Vawda y Per Øyvind Karlsen en bpo-6715 [https://bugs.python.org/issue?@action=redirect&bpo=6715].)

Módulos mejorados

abc

Soporte mejorado para las clases base abstractas que contienen descriptores compuestos con métodos abstractos. El enfoque recomendado para declarar descriptores abstractos ahora es proporcionar __isabstractmethod__ como una propiedad actualizada dinámicamente. Los descriptores integrados han sido actualizados en consecuencia.

La clase abc.abstractproperty ha quedado obsoleta, en su lugar use la clase property con abc.abstractmethod().

La clase abc.abstractclassmethod ha quedado obsoleta. En su lugar use el método classmethod with abc.abstractmethod().

abc.abstractstaticmethod ha quedado obsoleta, use staticmethod with abc.abstractmethod().

(Contribución de Darren Dale en bpo-11610 [https://bugs.python.org/issue?@action=redirect&bpo=11610]. )

El método abc.ABCMeta.register() ahora retorna las subclases registradas, lo cual significa que ahora éste puede ser usado como un decorador de clases (bpo-10868 [https://bugs.python.org/issue?@action=redirect&bpo=10868]).

array

El módulo array admite el tipo long long usando los códigos de tipo q y Q.

(Contribución de Oren Tirosh y Hirokazu Yamamoto en bpo-1172711 [https://bugs.python.org/issue?@action=redirect&bpo=1172711].)

base64

Las cadenas Unicode de solo ASCII ahora son aceptadas por las funciones de decodificación de la interfaz moderna base64. Por ejemplo, base64.b64decode ('YWJj') retorna b'abc'. (Contribución por Catalin Iacob en: número: 13641.)

binascii

Además de los objetos binarios que normalmente aceptan, las funciones a2b_ ahora también aceptan cadenas de sólo ASCII como dato de entrada. (Contribución por Antoine Petrou en bpo-13637 [https://bugs.python.org/issue?@action=redirect&bpo=13637].)

bz2

El módulo bz2 ha sido reescrito desde cero. Durante el proceso, han sido agregadas varias características:

Nueva función bz2.open(): abre un archivo comprimido por bzip2, en modo binario o en modo de texto.

bz2.BZ2File ahora puede leer y escribir en objetos de tipo archivo arbitrarios, mediante el argumento fileobj de su constructor.

(Contribución de Nadeem Vawda en bpo-5863 [https://bugs.python.org/issue?@action=redirect&bpo=5863].)

La clase bz2.BZ2File y la función bz2.decompress() ahora descomprimen entradas de flujo múltiple (como las producidas por la herramienta pbzip2). La clase bz2.BZ2File ahora puede ser usada también para crear este tipo de archivos, usando el modo 'a' (agregar).

(Contribución de Nir Aides en bpo-1625 [https://bugs.python.org/issue?@action=redirect&bpo=1625].)

La clase bz2.BZ2File ahora implementa toda la API io.BufferedIOBase, excepto los métodos detach() y truncate().

códecs

El códec mbcs ha sido reescrito para manejar correctamente los controladores de error reemplazar e ignorar en todas las versiones Windows. El códec mbcs ahora admite todos los controladores de error, en lugar de solo replace para codificar e ignore para decodificar.

Ha sido agregado un nuevo códec únicamente para windows: cp65001 (bpo-13216 [https://bugs.python.org/issue?@action=redirect&bpo=13216]). Es la página de códigos de Windows con el código 65001 (Windows UTF-8, CP_UTF8). Por ejemplo, es usado por sys.stdout si la página de códigos de salida de la consola se establece en cp65001 (por ejemplo, usando el comando chcp 65001).

Los decodificadores CJK multibyte ahora se re-sincronizan más rápido. Solo ignoran el primer byte de una secuencia de bytes no válida. Por ejemplo, `` b “xffn”.decode (” gb2312 “,”replace”) `` ahora retorna un \n después del carácter de reemplazo.

(bpo-12016 [https://bugs.python.org/issue?@action=redirect&bpo=12016])

Los codificadores de códec incrementales CJK ya no se restablecen en cada llamada a sus métodos encode(). Por ejemplo:

>>> import codecs
>>> encoder = codecs.getincrementalencoder('hz')('strict')
>>> b''.join(encoder.encode(x) for x in '\u52ff\u65bd\u65bc\u4eba\u3002 Bye.')
b'~{NpJ)l6HK!#~} Bye.'

Este ejemplo resulta b'~{Np~}~{J)~}~{l6~}~{HK~}~{!#~} Bye.' con versiones anteriores de Python.

(bpo-12100 [https://bugs.python.org/issue?@action=redirect&bpo=12100])

El códec unicode_internal ha quedado obsoleto.

colecciones

Adición de una nueva ChainMap para permitir el tratamiento de un número de asignaciones como una sola unidad. (Escrito por Raymond Hettinger para :issue:”11089”, publicado en :issue:”11297”.)

Las clases base abstractas se han movido en un nuevo módulo collections.abc, para diferenciar mejor entre las clases de colecciones abstractas y concretas. Los alias para ABC siguen presentes en el módulo collections para preservar las importaciones existentes. (bpo-11085 [https://bugs.python.org/issue?@action=redirect&bpo=11085])

La clase Counter ahora admite los operadores “”+”” y “”-”” unarios, así como los operadores in situ +=, -=, |=, and &=. (Contribución de Raymond Hettinger en bpo-13121 [https://bugs.python.org/issue?@action=redirect&bpo=13121].)

contextlib

ExitStack ahora proporciona una base sólida para la manipulación programática de los administradores de contexto y una funcionalidad de limpieza similar. A diferencia de la API anterior contextlib.nested (que estaba en desuso y se eliminó), la nueva API está diseñada para funcionar correctamente independientemente de si los administradores de contexto adquieren sus recursos en su método __init__ (por ejemplo, objetos de archivo) o en su método __enter__ (por ejemplo, objetos de sincronización del módulo threading).

(bpo-13585 [https://bugs.python.org/issue?@action=redirect&bpo=13585])

crypt

Adición de sal y formato de cripta modular (método de hashing) y la función mksalt() al módulo crypt.

(bpo-10924 [https://bugs.python.org/issue?@action=redirect&bpo=10924])

curses

Si el módulo curses es vinculado a la nueva librería ncursesw, se usan las funciones Unicode cuando se pasen cadenas o caracteres Unicode (por ejemplo, la función waddwstr()) o en caso contrario, funciones de bytes (e.g. waddstr()).

Usa la codificación local en vez de utf-8 para codificar cadenas Unicode.

La clase curses.window tiene un nuevo atributo curses.window.encoding.

La clase curses.window tiene un nuevo método get_wch() para obtener un caracter ancho

El módulo curses tiene una nueva función unget_wch() para enviar un caracter ancho de manera que el próximo get_wch() lo retorne

(Contribución por Iñigo Serna en bpo-6755 [https://bugs.python.org/issue?@action=redirect&bpo=6755].)

datetime

Las comparaciones de igualdad entre instancias conscientes e ingenuas datetime ahora retornan False en lugar de generar TypeError (bpo-15006 [https://bugs.python.org/issue?@action=redirect&bpo=15006]).

Nuevo método datetime.datetime.timestamp(): Retorna la marca de tiempo POSIX correspondiente a la instancia datetime.

El método datetime.datetime.strftime() admite el formato de años anteriores a 1000.

Ahora se puede llamar al método datetime.datetime.astimezone() sin argumentos para convertir la instancia datetime en la zona horaria del sistema.

decimal

bpo-7652 [https://bugs.python.org/issue?@action=redirect&bpo=7652] - integrar la aritmética decimal nativa rápida.

Módulo C y libmpdec escritos por Stefan Krah.

La nueva versión C del módulo decimal integra la biblioteca libmpdec de alta velocidad para una precisión arbitraria de aritmética de decimales de punto flotante correctamente redondeada. Libmpdec se ajusta a la especificación general aritmética decimal de IBM.

El rango de ganancias del rendimiento va de 10x para las aplicaciones de base de datos, a 100x para aplicaciones numéricamente intensivas. Estos números son ganancias esperadas para las precisiones estándar usadas en la aritmética de punto flotante decimal. Dado que la precisión es configurable por el usuario, las cifras exactas pueden variar. Por ejemplo, en la aritmética de enteros bignum, las diferencias pueden ser significativamente mayores.

La siguiente tabla se entiende como una ilustración. Los puntos de referencia están disponibles en http://www.bytereef.org/mpdecimal/quickstart.html.

decimal.py

_decimal

speedup

pi

42.02s

0.345s

120x

telco

172.19s

5.68s

30x

psycopg

3.57s

0.29s

12x

Características

La señal FloatOperation habilita opcionalmente las semánticas estrictas para mezclar decimales y flotantes.

Si python se compila sin subprocesos, la versión C deshabilita automáticamente la costosa maquinaria de contexto local de subprocesos. En éste caso, la variable HAVE_THREADS se establece en False.

Cambios en la API

El módulo C tiene los siguientes límites de contexto, dependiendo de la arquitectura de la máquina:

32-bit

64-bit

MAX_PREC

425000000

999999999999999999

MAX_EMAX

425000000

999999999999999999

MIN_EMIN

-425000000

-999999999999999999

En las plantillas de contexto (DefaultContext, BasicContext and ExtendedContext) la magnitud de Emax y Emin se ha cambiado a 999999.

El constructor Decimal en decimal.py no observa los límites de contexto y convierte valores con exponentes arbitrarios o precisión exacta. Dado que la versión C tiene límites internos, se usa el siguiente esquema: Si es posible, los valores son convertidos a valores exactos, de lo contrario se genera InvalidOperation y el resultado es NaN. En éste último caso siempre es posible usar create_decimal() para obtener un valor redondeado o inexacto.

La función de potencia en decimal.py siempre es redondeada de forma correcta. En la versión C, se define en términos de las funciones correctamente redondeadas exp() y ln(), pero el resultado final es sólo «casi siempre correctamente redondeado».

En la versión C, el diccionario de contexto que contiene las señales, es una MutableMapping. Por razones de velocidad, flags y traps siempre se refiere a la misma MutableMapping que el contexto con el que se inicializó. Si se asigna un nuevo diccionario de señales, flags y traps son actualizados con los nuevos valores, pero no hacen referencia al diccionario RHS.

Decapar a Context produce una salida diferente para tener un formato de intercambio común para las versiones de Python y C.

El orden de los argumentos en el constructor de la clase Context, ha sido cambiado para que coincida con el orden mostrado por la función repr().

El parámetro watchexp en el método quantize() ha quedado obsoleto.

email

Marco de políticas

El paquete de correo electrónico ahora tiene un marco policy. Un Policy es un objeto con varios métodos y propiedades que controlan el comportamiento del paquete de correo electrónico. La política principal de Python 3.3 es la política Compat32, que proporciona compatibilidad con versiones anteriores del paquete de correo electrónico en Python 3.2. Se puede especificar una policy cuando un mensaje de correo electrónico es analizado por un parser, o cuando se crea un objeto Message, o cuando se serializa un correo electrónico mediante un generator. A menos que se invalide, una política pasada a un parser es heredada por todos los objetos Message y los subobjetos creados por el parser. De forma predeterminada, un generator utilizará la política del objeto Message que está serializando. La directiva predeterminada es compat32.

El conjunto mínimo de controles implementado por todos los objetos policy son:

max_line_length

La longitud máxima, excluyendo el(los) caracter(es) linesep, que las líneas individuales pueden tener cuando un Message se serializa es por defecto de 78.

linesep

El caracter usado para separar las líneas individuales cuando se serializa un Message es por defecto \n.

cte_type

7bit or 8bit. 8bit sólo se aplica a un Bytes generator, y significa que pueden utilizarse «no ASCII» cuando lo permita el protocolo (o cuando exista en la entrada original).

raise_on_defect

Hace que un “”analizador”” genere el error cuando se encuentran defectos en lugar de agregarlos a la lista “”Mensaje”” del objeto “”defectos””.

Una nueva instancia de directiva, con nueva configuración, se crea mediante el método clone() de objetos de política. clone toma cualquiera de los controles anteriores como argumentos de palabra clave. Cualquier control no especificado en la llamada conserva su valor predeterminado. Por lo tanto, puede crear una directiva que utilice caracteres linesep \r\n como este:

mypolicy = compat32.clone(linesep='\r\n')

Las directivas pueden ser usadas para facilitar la generación de mensajes en el formato requerido por la aplicación. En vez de tener que recordar especificar linesep=”rn”` en todos los lugares en donde llamas a generator, puedes especificarlo una sola vez cuando estableces la política usada por el analizador o el Mensaje, el que tu programa utilice para crear los objetos Mensaje. Por otra parte, si necesitas generar mensajes en múltiples formas, aún puedes especificar los parámetros en la llamada al generador apropiado. O puedes tener instancias de política personalizadas para tus distintos casos, y pasarlos al crear el generator.

Política provisional con nueva API de encabezado

Aunque el marco de políticas vale la pena por sí solo, la principal motivación para presentarlo es permitir la creación de nuevas políticas que implementen nuevas características para el paquete de correo electrónico, de modo que mantenga la compatibilidad con versiones anteriores para aquellos quienes no usen las nuevas directivas. Dado que las nuevas políticas introducen una nueva API, estamos lanzándolas en Python 3.3 como una provisional policy. Pueden producirse cambios incompatibles con versiones anteriores (hasta la eliminación del código) si los desarrolladores principales lo consideran necesario.

Las nuevas directivas son instancias de EmailPolicy, y agregan los siguientes controles adicionales:

refold_source

Controla si los encabezados analizados por un parser son replegados por generator. Éste puede ser none, long, o all. El valor por defecto es long, lo que significa que los encabezados principales con una linea más larga que max_line_length se repliegan. none significa que no se repliega ninguna linea, y all significa que todas las lineas son replegadas.

header_factory

Un invocable que toma un `` nombre “” y un `` valor “” y produce un objeto de encabezado personalizado.

El header_factory es la clave a las nuevas características proporcionadas por las nuevas directivas. Cuando se usa una de las nuevas directivas, cualquier encabezado retornado por un objeto Message es un objeto producido por el header_factory, y en cualquier momento que se establece un encabezado en un Message, éste se convierte en un objeto producido por header_factory. Todos éstos objetos de encabezado tienen un atributo name igual al nombre del encabezado. Los encabezados de direcciones y fechas tienen atributos adicionales que te dan acceso a los datos analizados del encabezado. Ésto significa que ahora puedes hacer cosas como ésta:

>>> m = Message(policy=SMTP)
>>> m['To'] = 'Éric <foo@example.com>'
>>> m['to']
'Éric <foo@example.com>'
>>> m['to'].addresses
(Address(display_name='Éric', username='foo', domain='example.com'),)
>>> m['to'].addresses[0].username
'foo'
>>> m['to'].addresses[0].display_name
'Éric'
>>> m['Date'] = email.utils.localtime()
>>> m['Date'].datetime
datetime.datetime(2012, 5, 25, 21, 39, 24, 465484, tzinfo=datetime.timezone(datetime.timedelta(-1, 72000), 'EDT'))
>>> m['Date']
'Fri, 25 May 2012 21:44:27 -0400'
>>> print(m)
To: =?utf-8?q?=C3=89ric?= <foo@example.com>
Date: Fri, 25 May 2012 21:44:27 -0400

Notarás que el nombre de visualización Unicode se codifica automáticamente como utf-8 cuando se serializa el mensaje, pero que cuando se accede al encabezado directamente, obtienes la versión unicode. Ésto elimina cualquier necesidad de lidiar con las funciones email.header decode_header() or make_header().

También puedes crear direcciones a partir de partes:

>>> m['cc'] = [Group('pals', [Address('Bob', 'bob', 'example.com'),
...                           Address('Sally', 'sally', 'example.com')]),
...            Address('Bonzo', addr_spec='bonz@laugh.com')]
>>> print(m)
To: =?utf-8?q?=C3=89ric?= <foo@example.com>
Date: Fri, 25 May 2012 21:44:27 -0400
cc: pals: Bob <bob@example.com>, Sally <sally@example.com>;, Bonzo <bonz@laugh.com>

La decodificación a Unicode se realiza automáticamente:

>>> m2 = message_from_string(str(m))
>>> m2['to']
'Éric <foo@example.com>'

Cuando analizas un mensaje, puedes usar los atributos addresses y groups de los objetos de encabezado, para acceder a los grupos y direcciones individuales:

>>> m2['cc'].addresses
(Address(display_name='Bob', username='bob', domain='example.com'), Address(display_name='Sally', username='sally', domain='example.com'), Address(display_name='Bonzo', username='bonz', domain='laugh.com'))
>>> m2['cc'].groups
(Group(display_name='pals', addresses=(Address(display_name='Bob', username='bob', domain='example.com'), Address(display_name='Sally', username='sally', domain='example.com')), Group(display_name=None, addresses=(Address(display_name='Bonzo', username='bonz', domain='laugh.com'),))

En resumen, si usas una de las nuevas directivas, la manipulación de encabezados funciona del modo que debería: Su aplicación funciona con cadenas unicode, y el paquete de correo electrónico codifica y decodifica de forma transparente el unicode desde y hacia las codificaciones de transferencia de contenido estándar RFC.

Otros cambios en la API

Nuevo BytesHeaderParser, añadido al módulo parser para complementar HeaderParser y completar la API Bytes.

Nuevas funciones de utilidad:

format_datetime(): given a datetime, produce a string formatted for use in an email header.

email.utils.parsedate_to_datetime(): dada una cadena de fecha de un encabezado de correo electrónico, conviértela en un datetime.datetime, o un ingenuo datetime.datetime si el desplazamiento es -0000.

localtime(): With no argument, returns the current local time as an aware datetime using the local timezone. Given an aware datetime, converts it into an aware datetime using the local timezone.

ftplib

ftplib.FTP ahora acepta un argumento de palabra clave source_address para especificar el (host, port) que se usará como dirección de origen en la llamada de enlace al crear el socket saliente. (Contribución de Giampaolo Rodolà en bpo-8594 [https://bugs.python.org/issue?@action=redirect&bpo=8594].)

La clase FTP_TLS ahora proporciona una nueva función ccc() para revertir el canal de control a texto sin formato. Esto puede ser útil para aprovechar los firewalls que saben cómo manejar NAT con FTP no seguro sin abrir puertos fijos. (Contribución de Giampaolo Rodolà en bpo-12139 [https://bugs.python.org/issue?@action=redirect&bpo=12139].)

Añadido el método ftplib.FTP.mlsd() que proporciona un formato de listado de directorios analizable y pone en desuso ftplib.FTP.nlst() y ftplib.FTP.dir(). (Contribución de Giampaolo Rodolà en bpo-11072 [https://bugs.python.org/issue?@action=redirect&bpo=11072].)

functools

El decorador functools.lru_cache() ahora acepta un argumento de palabra clave typed (que por defecto tiene el valor False para asegurar que almacene en caché valores de diferentes tipos que se comparen igual en ranuras separadas de caché. (Contribución de Raymond Hettinger en bpo-13227 [https://bugs.python.org/issue?@action=redirect&bpo=13227].)

gc

Ahora es posible registrar devoluciones de llamadas invocadas por el recolector de basura antes y después de la recolección, utilizando la nueva lista callbacks.

hmac

Se ha agregado una nueva función compare_digest() para prevenir los ataques de canales adyacentes en resúmenes durante el análisis de tiempos. (Contribución de Nick Coghlan y Christian Heimes en bpo-15061 [https://bugs.python.org/issue?@action=redirect&bpo=15061].)

http

http.server.BaseHTTPRequestHandler ahora almacena en buffer los encabezados y los escribe todos a la vez cuando se llama a end_headers(). Se puede usar un nuevo método flush_headers() para administrar directamente cuándo se envían los encabezados acumulados. (Contribución por Andrew Schaaf en bpo-3709 [https://bugs.python.org/issue?@action=redirect&bpo=3709].)

http.server ahora produce una salida HTML 4.01 strict válida. (Contribución de Ezio Melotti in bpo-13295 [https://bugs.python.org/issue?@action=redirect&bpo=13295])

La clase http.client.HTTPResponse ahora tiene un método readinto(), lo que significa que puede ser usado como una clase io.RawIOBase. (Contribución de John Kuhn in bpo-13464 [https://bugs.python.org/issue?@action=redirect&bpo=13464])

html

html.parser.HTMLParser ahora puede analizar el marcado no válido sin generar errores, por lo tanto, el argumento strict del constructor y la excepción HTMLParseError ahora están en desuso. La habilidad de analizar marcado inválido es el resultado de un número de correcciones que también están disponibles en la última versión de solución de bugs de Python 2.7/3.2. (Contribución de Ezio Melotti en bpo-15114 [https://bugs.python.org/issue?@action=redirect&bpo=15114], y bpo-14538 [https://bugs.python.org/issue?@action=redirect&bpo=14538], bpo-13993 [https://bugs.python.org/issue?@action=redirect&bpo=13993], bpo-13960 [https://bugs.python.org/issue?@action=redirect&bpo=13960], bpo-13358 [https://bugs.python.org/issue?@action=redirect&bpo=13358], bpo-1745761 [https://bugs.python.org/issue?@action=redirect&bpo=1745761], bpo-755670 [https://bugs.python.org/issue?@action=redirect&bpo=755670], bpo-13357 [https://bugs.python.org/issue?@action=redirect&bpo=13357], bpo-12629 [https://bugs.python.org/issue?@action=redirect&bpo=12629], bpo-1200313 [https://bugs.python.org/issue?@action=redirect&bpo=1200313], bpo-670664 [https://bugs.python.org/issue?@action=redirect&bpo=670664], bpo-13273 [https://bugs.python.org/issue?@action=redirect&bpo=13273], bpo-12888 [https://bugs.python.org/issue?@action=redirect&bpo=12888], bpo-7311 [https://bugs.python.org/issue?@action=redirect&bpo=7311].)

Se ha agregado un nuevo diccionario html5 que asigna referencias de caracteres con nombre HTML5 a los caracteres Unicode equivalentes (por ejemplo, html5['gt;'] == '>') ha sido agregado al módulo html.entities. El diccionario ahora también es utilizado por HTMLParser. (Contribución por Ezio Melotti en bpo-11113 [https://bugs.python.org/issue?@action=redirect&bpo=11113] y bpo-15156 [https://bugs.python.org/issue?@action=redirect&bpo=15156].)

imaplib

El constructor de IMAP4_SSL ahora acepta un parámetro SSLContext para controlar los parámetros del canal seguro.

(Contribución de Sijin Joseph en bpo-8808 [https://bugs.python.org/issue?@action=redirect&bpo=8808].)

inspect

Se ha añadido una nueva función getclosurevars(). Esta función notifica el enlace actual de todos los nombres a los que se hace referencia desde el cuerpo de la función y dónde se resolvieron esos nombres, lo que facilita la comprobación del estado interno correcto al probar el código que se basa en cierres con estado.

(Contribución de Meador Inge y Nick Coghlan en bpo-13062 [https://bugs.python.org/issue?@action=redirect&bpo=13062].)

Se ha añadido una nueva función getgeneratorlocals(). Esta función informa del enlace actual de variables locales en el marco de pila del generador, lo que facilita la comprobación del estado interno correcto al probar generadores.

(Contribución de Meador Inge en bpo-15153 [https://bugs.python.org/issue?@action=redirect&bpo=15153].)

io

La función open() tiene un nuevo modo 'x' que puede ser usado exclusivamente para crear un nuevo archivo, y lanzar un FileExistsError si el archivo ya existe. Este está basado en el modo C11 “x” para fopen().

(Contribución de David Townsend en bpo-12760 [https://bugs.python.org/issue?@action=redirect&bpo=12760].)

El constructor de la clase TextIOWrapper tiene un nuevo argumento opcional write_through. Si write_through es True, se garantiza que las llamadas a write() no se almacenarán en buffer: Cualquier dato escrito en el objeto TextIOWrapper es llevado inmediatamente a su buffer subyacente.

itertools

accumulate() ahora toma un argumento opcional func para proporcionar una función binaria proporcionada por el usuario.

logging

La función basicConfig() ahora admite un argumento opcional handlers tomando un iterable de manejadores para agregarlo en el registrador raíz.

Un atributo de nivel de la clase append_nul ha sido agregado a la clase SysLogHandler para permitir el control de la adición de NUL (\000) byte a los registros de syslog, dado que para algunos demonios es requerido mientras que para otros se pasa al registro.

math

El módulo math tiene una nueva función, log2(), la cual retorna el logaritmo de x en base 2.

(Escrito por Mark Dickinson en bpo-11888 [https://bugs.python.org/issue?@action=redirect&bpo=11888].)

mmap

El método read() ahora es más compatible con otros objetos similares a archivos: Si se omite el argumento o se especifica como None, retorna los bytes desde la posición actual hasta el final del mapeo. (Contribución de Petri Lehtinen en bpo-12021 [https://bugs.python.org/issue?@action=redirect&bpo=12021].)

multiprocesamiento

La nueva función multiprocessing.connection.wait() permite sondear varios objetos (como conexiones, sockets y tuberías) con un tiempo de espera. (Contribución de Richard Oudkerk en bpo-12328 [https://bugs.python.org/issue?@action=redirect&bpo=12328].)

Los objetos multiprocessing.Connection ahora se pueden transferir a través de conexiones de multiprocesamiento. (Contribución de Richard Oudkerk en bpo-4892 [https://bugs.python.org/issue?@action=redirect&bpo=4892].)

multiprocessing.Process ahora acepta un argumento de palabra clave daemon para invalidar el comportamiento predeterminado de heredar el indicador daemon del proceso primario (bpo-6064 [https://bugs.python.org/issue?@action=redirect&bpo=6064]).

Nuevo atributo multiprocessing.Process.sentinel permite que un programa espere múltiples objetos Process a la vez utilizando las primitivas adecuadas del sistema operativo (por ejemplo, select en sistemas posix).

Los nuevos métodos multiprocessing.pool.Pool.starmap() y starmap_async() proporcionan itertools.starmap() equivalentes a las funciones existentes multiprocessing.pool.Pool.map() y map_async(). (Contribución de Hynek Schlawack en bpo-12708 [https://bugs.python.org/issue?@action=redirect&bpo=12708].)

nntplib

La nntplib.NNTP ahora admite el protocolo de administración de contexto para consumir incondicionalmente las excepciones socket.error y cerrar la conexión NNTP cuando esté listo:

>>> from nntplib import NNTP
>>> with NNTP('news.gmane.org') as n:
...     n.group('gmane.comp.python.committers')
...
('211 1755 1 1755 gmane.comp.python.committers', 1755, 1, 1755, 'gmane.comp.python.committers')
>>>

(Contribución de Giampaolo Rodolà en bpo-9795 [https://bugs.python.org/issue?@action=redirect&bpo=9795].)

os

El módulo os tiene una nueva función pipe2() que hace posible crear una tubería con banderas O_CLOEXEC o O_NONBLOCK establecida automáticamente. Esto es especialmente útil para evitar las condiciones de carrera en programas multi-hilos.

El módulo os tiene una nueva función sendfile() que proporciona una forma eficiente de «copia cero» para copiar datos desde un descriptor de archivo (o socket) a otro. La frase «copia cero» se refiere al hecho de que la copia de los datos entre dos descriptores es realizada en su totalidad por el kernel, sin copiar los datos en los búferes del espacio de usuario. La función sendfile() puede ser usada para copiar datos de forma eficiente desde un archivo en el disco a un conector de red, por ejemplo para descargar un archivo.

(Revisión enviada por Ross Lagerwall y Giampaolo Rodolà en bpo-10882 [https://bugs.python.org/issue?@action=redirect&bpo=10882].)

Para evitar las condiciones de carrera, como los ataques symlink, y errores con archivos temporales y directorios, es preferible (y más rápido) manipular los descriptores de archivos en vez de los nombres de archivos. Python 3.3 mejora las funciones existentes e introduce nuevas funciones para trabajar con los descriptores de archivos (bpo-4761 [https://bugs.python.org/issue?@action=redirect&bpo=4761], bpo-10755 [https://bugs.python.org/issue?@action=redirect&bpo=10755] and bpo-14626 [https://bugs.python.org/issue?@action=redirect&bpo=14626]).

El módulo os tiene una nueva función fwalk() similar a walk() excepto que también incluye descriptores de archivos que se refieren a los directorios visitados. Esto es especialmente útil para prevenir las carreras de enlaces simbólicos.

Las siguientes funciones tienen las nuevas opciones dir_fd (rutas relativas a descriptores de archivos) y/o follow_symlinks (not following symlinks): access(), chflags(), chmod(), chown(), link(), lstat(), mkdir(), mkfifo(), mknod(), open(), readlink(), remove(), rename(), replace(), rmdir(), stat(), symlink(), unlink(), utime(). El soporte de la plataforma para usar éstos parámetros puede verificarse a través de los conjuntos os.supports_dir_fd and os.supports_follows_symlinks.

Las siguientes funciones ahora admiten un descriptor de archivos para su argumento de ruta: chdir(), chmod(), chown(), execve(), listdir(), pathconf(), exists(), stat(), statvfs(), utime(). El soporte de la plataforma para ésto puede ser verificado a través del conjunto os.supports_fd.

access() acepta un argumento de palabra clave effective_ids acepta el uso del uid/gid efectivo en lugar del uid/gid real en la comprobación de acceso. El soporte de la plataforma para ésto, se puede comprobar a través del conjunto supports_effective_ids.

El módulo os tiene dos nuevas funciones getpriority() y setpriority(). Estas pueden ser usadas para establecer o recuperar la prioridad en una forma similar a os.nice() pero extendidos a todos los procesos en vez de solo al proceso actual.

(Revisión enviada por Giampaolo Rodolà en bpo-10784 [https://bugs.python.org/issue?@action=redirect&bpo=10784].)

La nueva función os.replace() permite cambiar el nombre de un archivo entre plataformas sobrescribiendo el destino. Con os.rename(), un archivo de destino existente se sobrescribe bajo POSIX, pero lanza un error en Windows. (Contribución de Antoine Pitrou en bpo-8828 [https://bugs.python.org/issue?@action=redirect&bpo=8828].)

La familia de estadísticas de funciones (stat(), fstat(), y lstat()) ahora admite la lectura de marcas de tiempo de un archivo con precisión de nanosegundos. Simétricamente, utime() ahora puede escribir marcas de tiempo de archivos con precisión de nanosegundos. (Contribución de Larry Hastings en bpo-14127 [https://bugs.python.org/issue?@action=redirect&bpo=14127].)

La nueva función os.get_terminal_size() consulta el tamaño del terminal adjunto al descriptor del archivo. Vea también shutil.get_terminal_size(). (Contribución de Zbigniew Jędrzejewski-Szmek en bpo-13609 [https://bugs.python.org/issue?@action=redirect&bpo=13609]. )

Nuevas funciones para admitir atributos extendidos de Linux. (bpo-12720 [https://bugs.python.org/issue?@action=redirect&bpo=12720]): getxattr(), listxattr(), removexattr(), setxattr().

Nueva interfaz para el planificador. Estas funciones controlan como el sistema operativo le asigna tiempo de CPU a un proceso. Nuevas funciones: sched_get_priority_max(), sched_get_priority_min(), sched_getaffinity(), sched_getparam(), sched_getscheduler(), sched_rr_get_interval(), sched_setaffinity(), sched_setparam(), sched_setscheduler(), sched_yield(),

Nuevas funciones para controlar el sistema de archivos:

posix_fadvise(): Anuncia una intención de acceder a los datos en un patrón específico, permitiendo al kernel hacer optimizaciones.

posix_fallocate(): Garantiza que se asigne el espacio suficiente a un archivo.

sync(): Fuerza la escritura de cualquier cosa en el disco.

Nuevas funciones posix adicionales:

lockf(): Aplicar, probar o eliminar un bloqueo POSIX en un descriptor de archivo abierto.

pread(): Leer desde un descriptor de archivo en un desplazamiento, el desplazamiento del archivo permanece sin cambios.

pwrite(): Escribe en un descriptor de archivo desde un desplazamiento, dejando el desplazamiento del archivo sin cambios.

readv(): Leer desde el descriptor de un archivo en varios búferes editables.

truncate(): Truncar el archivo correspondiente a path, para que tenga como máximo length bytes de tamaño.

waitid(): Espera que se completen uno o más procesos secundarios.

writev(): Escribir los contenidos de buffers a un archivo descriptor, donde buffers es una secuencia arbitraria de buffers.

getgrouplist() (bpo-9344 [https://bugs.python.org/issue?@action=redirect&bpo=9344]): Retorna una lista de ids de grupo al que pertenece el usuario especificado.

times() and uname(): El tipo de retorno cambió de tupla a un objeto tipo tupla con atributos con nombre.

Varias plataformas admiten constantes adicionales para la función lseek(), tal como os.SEEK_HOLE y os.SEEK_DATA.

Nuevas constantes RTLD_LAZY, RTLD_NOW, RTLD_GLOBAL, RTLD_LOCAL, RTLD_NODELETE, RTLD_NOLOAD, and RTLD_DEEPBIND están disponibles en plataformas que las soporten. Éstas son para uso con la función sys.setdlopenflags(), y reemplazan las constantes similares definidas en ctypes and DLFCN. (Contribución de Victor Stinner en bpo-13226 [https://bugs.python.org/issue?@action=redirect&bpo=13226].)

os.symlink() ahora acepta (e ignora) el argumento de palabra clave``target_is_directory`` en plataformas diferentes a windows, para facilitar el soporte multiplataforma.

pdb

La finalización de tabulaciones ahora está disponible no solo para los nombres de los comandos, sino también para sus argumentos. Por ejemplo, para el comando break, se completan las funciones y los nombres de archivo.

(Contribución de Georg Brandl en bpo-14210 [https://bugs.python.org/issue?@action=redirect&bpo=14210])

pickle

Los objetos pickle.Pickler ahora tienen un atributo opcional dispatch_table que permite establecer funciones de reducción por recolector.

(Contribución de Richard Oudkerk in bpo-14166 [https://bugs.python.org/issue?@action=redirect&bpo=14166].)

pydoc

La Tk GUI y la función serve() han sido eliminadas del módulo pydoc: pydoc -g y serve() han quedado obsoletos en Python 3.2.

re

Las expresiones regulares de la clase str ahora admiten escapes de \u and \U .

(Contribución de Serhiy Storchaka en bpo-3665 [https://bugs.python.org/issue?@action=redirect&bpo=3665].)

sched

run() ahora acepta un parámetro blocking que al configurarse en false, hace que el método ejecute los eventos planificados debido a la pronta expiración (si corresponde) y luego responde inmediatamente. Esto es útil en caso de que quieras usar la scheduler en aplicaciones sin bloqueo. (Contribución de Giampaolo Rodolà in bpo-13449 [https://bugs.python.org/issue?@action=redirect&bpo=13449].)

La clase scheduler ahora se puede utilizar de forma segura en entornos multiproceso. (Contribución por Josiah Carlson y Giampaolo Rodolà en bpo-8684 [https://bugs.python.org/issue?@action=redirect&bpo=8684].)

Los parámetros timefunc y delayfunct del constructor de la clase scheduler ahora son opcionales y tienen el valor predeterminado time.time() y time.sleep() respectivamente. (Contribución de Chris Clark en bpo-13245 [https://bugs.python.org/issue?@action=redirect&bpo=13245].)

El parámetro argument de enter() and enterabs() ahora es opcional. (Contribución de Chris Clark en bpo-13245 [https://bugs.python.org/issue?@action=redirect&bpo=13245].)

enter() y enterabs() ahora aceptan un parámetro kwargs. (Contribución de Chris Clark en bpo-13245 [https://bugs.python.org/issue?@action=redirect&bpo=13245].)

select

Solaris y plataformas derivadas tienen una nueva clase select.devpoll para sockets asincrónicos de alto rendimiento a través de /dev/poll. (Contribución de Jesús Cea Avión en bpo-6397 [https://bugs.python.org/issue?@action=redirect&bpo=6397].)

shlex

La función auxiliar previamente indocumentada quote de los módulos pipes se ha movido al módulo shlex y se ha documentado. quote() escapa correctamente a todos los caracteres de una cadena que de otro modo podría tener un significado especial por el shell.

shutil

Nuevas funciones:

disk_usage(): Proporciona estadísticas sobre el espacio total, usado, y libre en el disco. (Contribución de Giampaolo Rodolà in bpo-12442 [https://bugs.python.org/issue?@action=redirect&bpo=12442].)

chown(): Permite cambiar el usuario y/o grupo de las rutas dadas, además de especificar los nombres de usuario/grupo, y no solos sus id’s numèricos. (Contribución de Sandro Tosi in bpo-12191 [https://bugs.python.org/issue?@action=redirect&bpo=12191].)

shutil.get_terminal_size(): Retorna el tamaño de la ventana del terminar a la cual se adjunta el intérprete. (Contribución de Zbigniew Jędrzejewski-Szmek in bpo-13609 [https://bugs.python.org/issue?@action=redirect&bpo=13609]. )

copy2() and copystat() ahora conservan las marcas de tiempo de archivos con precisión de nanosegundos en plataformas que lo soporten. También conservan los «atributos extendidos» de archivo en Linux (Contribución de Larry Hastings en bpo-14127 [https://bugs.python.org/issue?@action=redirect&bpo=14127] y bpo-15238 [https://bugs.python.org/issue?@action=redirect&bpo=15238].)

Algunas funciones ahora toman un argumento opcional de symlinks: Cuando ese parámetro es verdadero, los enlaces simbólicos no se desreferencian y la operación actúa en el enlace simbólico en sí. (o crea uno, si es relevante). (Contribución de Hynek Schlawack in bpo-12715 [https://bugs.python.org/issue?@action=redirect&bpo=12715].)

Al copiar archivos a un sistema de archivos diferente, move() ahora gestiona los enlaces simbólicos de la forma que lo hace el comando mv de posix, recreando el enlace simbólico en vez de copiar el contenido del archivo de destino. (Contribución de Jonathan Niehof en bpo-9993 [https://bugs.python.org/issue?@action=redirect&bpo=9993].) move() ahora también retorna el argumento dst como resultado.

rmtree() ahora es resistente a los ataques de enlaces simbólicos en plataformas que admiten el nuevo parámetro dir_fd en os.open() y os.unlink(). (Contribución de Martin von Löwis and Hynek Schlawack in bpo-4489 [https://bugs.python.org/issue?@action=redirect&bpo=4489].)

signal

El módulo signal tiene nuevas funciones:

pthread_sigmask(): busca y/o cambia la máscara de señal del hilo de llamada (Contribución de Jean-Paul Calderone in bpo-8407 [https://bugs.python.org/issue?@action=redirect&bpo=8407]);

pthread_kill(): Envía una señal a un hilo;

sigpending(): Examina funciones pendientes;

sigwait(): Espera una señal;

sigwaitinfo(): Espera una señal, retornando información detallada sobre ella;

sigtimedwait(): Es similar a sigwaitinfo() pero con un tiempo de espera.

El manejador de señales escribe el número de señal, como un único byte en vez de un byte nulo en el descriptor del archivo de activación. Por lo tanto, es posible esperar más de una señal y saber cuales señales han sido lanzadas.

signal.signal() y signal.siginterrupt() lanzan un OSError, en vez de un RuntimeError: OSError no tiene atributo errno.

smtpd

El módulo smtpd ahora admite RFC 5321 [https://tools.ietf.org/html/rfc5321.html] (SMTP extendido) y RFC 1870 [https://tools.ietf.org/html/rfc1870.html] (Ampliación de tamaño). Por lo general, éstas extensiones están habilitadas si y solo si el cliente inicia la sesión con un comando EHLO.

Soporte inicial de `` ELHO “” de Alberto Treviño. Ampliación de tamaño por Juhana Jauhiainen. Trabajo adicional sustancial en la revisión aportada por Michele Orrù y Dan Boswell. bpo-8739 [https://bugs.python.org/issue?@action=redirect&bpo=8739])

smtplib

Las clases SMTP, SMTP_SSL, y LMTP ahora aceptan un argumento de palabra clave source_address, para especificar el (host, port) a usar como dirección de origen en la llamada de enlace al crear el socket saliente. (Contribución de Paulo Scardine en bpo-11281 [https://bugs.python.org/issue?@action=redirect&bpo=11281].)

SMTP ahora admite el protocolo de administración de contexto, permitiendo usar a una instancia SMTP en una declaración with. (Contribución de Giampaolo Rodolà en bpo-11289 [https://bugs.python.org/issue?@action=redirect&bpo=11289].)

El constructor SMTP_SSL y el método starttls() ahora aceptan un parámetro SSLContext, para controlar los parámetros del canal seguro. (Contribución por Kasun Herath en bpo-8809 [https://bugs.python.org/issue?@action=redirect&bpo=8809].)

socket

La clase socket ahora expone métodos adicionales para procesar datos auxiliares cuando sean compatibles con la plataforma subyacente:

sendmsg()

recvmsg()

recvmsg_into()

(Contribución de David Watson en bpo-6560 [https://bugs.python.org/issue?@action=redirect&bpo=6560], basado en una revisión anterior de Heiko Wundram)

La clase socket ahora admite la familia del protocolo PF_CAN (https://en.wikipedia.org/wiki/Socketcan), en Linux (https://lwn.net/Articles/253425).

(Contribución de Matthias Fuchs, actualizado por Tiago Gonçalves en bpo-10141 [https://bugs.python.org/issue?@action=redirect&bpo=10141].)

La clase socket ahora admite la familia del protocolo PF_RDS (https://en.wikipedia.org/wiki/Reliable_Datagram_Sockets and https://oss.oracle.com/projects/rds/).

La clase socket ahora admite la familia del protocolo PF_SYSTEM en OS X. (Contribución de Michael Goderbauer en bpo-13777 [https://bugs.python.org/issue?@action=redirect&bpo=13777].)

La nueva función sethostname() permite establecer el nombre del host en los sistemas unix si el proceso de llamada tiene suficientes privilegios. (Contribución de Ross Lagerwall en bpo-10866 [https://bugs.python.org/issue?@action=redirect&bpo=10866].)

socketserver

BaseServer ahora tiene un método reemplazable service_actions() que es llamado por el método serve_forever() en el ciclo del servicio. ForkingMixIn ahora usa ésto para limpiar procesos secundarios zombies. (Contribución de Justin Warkentin en bpo-11109 [https://bugs.python.org/issue?@action=redirect&bpo=11109].)

sqlite3

Nuevo método sqlite3.Connection set_trace_callback() puede ser usado para capturar un rastro de todos los comandos sql procesados por sqlite. (Contribución de Torsten Landschoff en bpo-11688 [https://bugs.python.org/issue?@action=redirect&bpo=11688].)

ssl

El módulo ssl tiene dos funciones de generación aleatoria:

RAND_bytes(): genera bytes pseudo-aleatorios criptográficamente fuertes.

RAND_pseudo_bytes(): genera bytes pseudoaleatorios.

(Contribución de Victor Stinner en bpo-12049 [https://bugs.python.org/issue?@action=redirect&bpo=12049].)

El módulo ssl ahora expone una jerarquía de excepciones más detallada para facilitar la inspección de varias clases de errores. (Contribución de Antoine Pitrou en bpo-11183 [https://bugs.python.org/issue?@action=redirect&bpo=11183].)

load_cert_chain() ahora acepta un argumento password que será usado si la clave privada es encriptada. (Contribución de Adam Simpkins en bpo-12803 [https://bugs.python.org/issue?@action=redirect&bpo=12803].)

El intercambio de claves Diffie-Hellman, tanto regular como basado en curvas elípticas, ahora se admite a través de los métodos load_dh_params() y set_ecdh_curve(). (Contribución de Antoine Pitrou en bpo-13626 [https://bugs.python.org/issue?@action=redirect&bpo=13626] y bpo-13627 [https://bugs.python.org/issue?@action=redirect&bpo=13627].)

Los sockets SSL tienen un nuevo método get_channel_binding() que permite la implementación de ciertos mecanismos de autenticación tales como SCRAM-SHA-1-PLUS. (Contribución por Jacek Konieczny en bpo-12551 [https://bugs.python.org/issue?@action=redirect&bpo=12551].)

Puedes consultar el algoritmo de compresión SSL usado por un socket SSL, gracias a su nuevo método compression(). El nuevo atributo OP_NO_COMPRESSION puede ser usado para deshabilitar la compresión. (Contribución de Antoine Pitrou en bpo-13634 [https://bugs.python.org/issue?@action=redirect&bpo=13634].)

Se ha agregado soporte para la extensión Next Protocol Negotiation usando el método ssl.SSLContext.set_npn_protocols(). (Contribución por Colin Marc en bpo-14204 [https://bugs.python.org/issue?@action=redirect&bpo=14204].)

Los errores de SSL ahora pueden introspectarse más fácilmente gracias a los atributos library y reason. (Contribución de Antoine Pitrou en bpo-14837 [https://bugs.python.org/issue?@action=redirect&bpo=14837].)

La función get_server_certificate() ahora admite IPv6. (Contribución por Charles-François Natali en bpo-11811 [https://bugs.python.org/issue?@action=redirect&bpo=11811].)

El nuevo atributo OP_CIPHER_SERVER_PREFERENCE permite configurar los sockets del servidor SSLv3 para usar la preferencia de ordenación de cifrado del servidor en lugar de la del cliente. (bpo-13635 [https://bugs.python.org/issue?@action=redirect&bpo=13635]).

stat

La función indocumentada tarfile.filemode ha sido movida a stat.filemode(). Este puede ser usado para convertir el modo de un archivo a una cadena de la forma “-rwxrwxrwx”.

(Contribución de Giampaolo Rodolà in bpo-14807 [https://bugs.python.org/issue?@action=redirect&bpo=14807].)

struct

El módulo struct ahora admite ssize_t y size_t a través de los nuevos códigos n and N, respectivamente. (Contribución de Antoine Pitrou en bpo-3163 [https://bugs.python.org/issue?@action=redirect&bpo=3163].)

subprocess

Las cadenas de comandos ahora pueden ser objetos de bytes en las plataformas posix. (Contribución de Victor Stinner in bpo-8513 [https://bugs.python.org/issue?@action=redirect&bpo=8513].)

Una nueva constante DEVNULL permite suprimir la salida de forma independiente de la plataforma. (Contribución de Ross Lagerwall en bpo-5870 [https://bugs.python.org/issue?@action=redirect&bpo=5870].)

sys

El módulo sys tiene un nuevo thread_info named tuple que almacena información sobre la implementación del hilo (bpo-11223 [https://bugs.python.org/issue?@action=redirect&bpo=11223]).

tarfile

tarfile ahora admite la codificación lzma a través del módulo lzma. (Contribución de Lars Gustäbel en bpo-5689 [https://bugs.python.org/issue?@action=redirect&bpo=5689].)

tempfile

El método tempfile.SpooledTemporaryFile’s truncate() ahora acepta un parámetro size. (Contribución de Ryan Kelly en bpo-9957 [https://bugs.python.org/issue?@action=redirect&bpo=9957].)

textwrap

El módulo textwrap tiene una nueva función indent() que facilita la adición de un prefijo común para las lineas seleccionadas en un bloque de texto (bpo-13857 [https://bugs.python.org/issue?@action=redirect&bpo=13857]).

threading

threading.Condition, threading.Semaphore, threading.BoundedSemaphore, threading.Event, y threading.Timer, todas las cuales son usadas para ser funciones de fábrica que retornen una instancia de clase, ahora son clases y pueden ser subclasificadas (Contribución de Éric Araujo in bpo-10968 [https://bugs.python.org/issue?@action=redirect&bpo=10968].)

El constructor de la clase threading.Thread ahora acepta un argumento de palabra clave daemon para anular el comportamiento predeterminado de heredar el valor del indicador daemon desde el hilo principal (bpo-6064 [https://bugs.python.org/issue?@action=redirect&bpo=6064]).

La función anteriormente privada _thread.get_ident ahora está disponible como función pública threading.get_ident(). Ésto elimina varios casos de acceso directo al módulo _thread en el stdlib. El código de terceros que usaba _thread.get_ident debería de igual forma ser cambiado para usar la nueva interfaz pública.

time

El PEP 418 [https://www.python.org/dev/peps/pep-0418] agrega nuevas funciones al módulo time:

get_clock_info(): Obtiene información en un reloj.

monotonic(): Reloj monotónico (no se puede retroceder), no se ve afectado por la actualización del reloj del sistema.

perf_counter(): Contador de rendimiento con la más alta resolución disponible para medir una corta duración.

process_time(): Suma del tiempo de CPU del sistema y del usuario del proceso actual.

Otras nuevas funciones:

Las funciones clock_getres(), clock_gettime() y clock_settime() con constantes CLOCK_xxx (Contribución de Victor Stinner in bpo-10278 [https://bugs.python.org/issue?@action=redirect&bpo=10278].)

Para mejorar la consistencia entre plataformas, la función sleep() ahora lanza un ValueError cuando se le pasa un valor negativo. Esto era anteriormente un error en posix, pero producía una suspensión definitiva en windows.

types

Adición de una nueva clase types.MappingProxyType: Proxy de solo lectura de una asignación. (bpo-14386 [https://bugs.python.org/issue?@action=redirect&bpo=14386])

Las nuevas funciones types.new_class() y types.prepare_class() proporcionan soporte para la creación de tipos dinámicos compatibles. (bpo-14588 [https://bugs.python.org/issue?@action=redirect&bpo=14588])

unittest

Los métodos assertRaises(), assertRaisesRegex(), assertWarns(), y assertWarnsRegex() ahora aceptan un argumento de palabra clave msg cuando son usados como administradores de contexto. (Contribución por Ezio Melotti y Winston Ewert en bpo-10775 [https://bugs.python.org/issue?@action=redirect&bpo=10775].)

unittest.TestCase.run() ahora retorna el objeto TestResult.

urllib

La clase Request ahora acepta un argumento method usado por get_method() para determinar que método HTTP debería usarse. Por ejemplo, esto enviará una solicitud 'HEAD':

>>> urlopen(Request('https://www.python.org', method='HEAD'))

(bpo-1673007 [https://bugs.python.org/issue?@action=redirect&bpo=1673007])

webbrowser

El módulo webbrowser admite más «navegadores»: Google Chrome (llamado chrome, chromium, chrome-browser or chromium-browser dependiendo de la versión y del sistema operativo), y los lanzadores genéricos: programa: xdg-open, del proyecto FreeDesktop.org, y gvfs-open, el cual es el controlador URI predeterminado para GNOME3. (El primero agregado por Arnaud Calmettes en: issue:13620, el segundo por Matthias Klose en :issue:14493`.)

xml.etree.ElementTree

El módulo xml.etree.ElementTree ahora importa su acelerador C predeterminado, ya no es necesario importar explícitamente xml.etree.cElementTree (Éste módulo permanece para compatibilidad con versiones anteriores, pero ya está obsoleto). Además, la familia de métodos iter de Element se ha optimizado (Reescrito en C). La documentación del módulo también se ha mejorado mucho, con ejemplos agregados y una referencia más detallada.

zlib

Nuevo atributo zlib.Decompress.eof permite distinguir entre un flujo comprimido, correctamente formado, y uno incompleto o truncado. (Contribución de Nadeem Vawda in bpo-12646 [https://bugs.python.org/issue?@action=redirect&bpo=12646]. )

Nuevo atributo zlib.ZLIB_RUNTIME_VERSION informa la cadena de versión de la biblioteca zlib subyacente que se carga en tiempo de ejecución. (Contribución de Torsten Landschoff en bpo-12306 [https://bugs.python.org/issue?@action=redirect&bpo=12306].)

Optimizaciones

Se han agregado importantes mejoras de rendimiento:

Gracias a PEP 393 [https://www.python.org/dev/peps/pep-0393], algunas operaciones en las cadenas Unicode han sido optimizadas:

la huella de memoria se divide de 2 a 4 según el texto

codificar una cadena ASCII a UTF-8 ya no necesita codificar caracteres, la representación UTF-8 se comparte con la representación ASCII

el codificador UTF-8 ha sido optimizado

repetir una única letra ASCII y obtener una subcadena de una cadena ASCII es 4 veces más rápido

UTF-8 ahora es 2x a 4x más rápido. La codificación UTF-16 ahora es 10x más rápida.

(Contribución de Serhiy Storchaka, bpo-14624 [https://bugs.python.org/issue?@action=redirect&bpo=14624], bpo-14738 [https://bugs.python.org/issue?@action=redirect&bpo=14738] y bpo-15026 [https://bugs.python.org/issue?@action=redirect&bpo=15026].)

Construcción y cambios en la API de C

Los cambios en el proceso de compilación de Python y en la API de C incluyen:

Nueva función relacionada con PEP 3118 [https://www.python.org/dev/peps/pep-3118]:

PyMemoryView_FromMemory()

PEP 393 [https://www.python.org/dev/peps/pep-0393] Agregó nuevos tipos unicode, macros y funciones:

API de alto nivel:

PyUnicode_CopyCharacters()

PyUnicode_FindChar()

PyUnicode_GetLength(), PyUnicode_GET_LENGTH

PyUnicode_New()

PyUnicode_Substring()

PyUnicode_ReadChar(), PyUnicode_WriteChar()

API de bajo nivel:

Tipos Py_UCS1, Py_UCS2, Py_UCS4

Estructuras PyASCIIObject y PyCompactUnicodeObject

PyUnicode_READY

PyUnicode_FromKindAndData()

PyUnicode_AsUCS4(), PyUnicode_AsUCS4Copy()

PyUnicode_DATA, PyUnicode_1BYTE_DATA, PyUnicode_2BYTE_DATA, PyUnicode_4BYTE_DATA

PyUnicode_KIND con PyUnicode_Kind enum: PyUnicode_WCHAR_KIND, PyUnicode_1BYTE_KIND, PyUnicode_2BYTE_KIND, PyUnicode_4BYTE_KIND

PyUnicode_READ, PyUnicode_READ_CHAR, PyUnicode_WRITE

PyUnicode_MAX_CHAR_VALUE

PyArg_ParseTuple ahora acepta un bytearray para el formato c (bpo-12380 [https://bugs.python.org/issue?@action=redirect&bpo=12380]).

Obsoleto

Sistemas operativos no compatibles

OS/2 y VMS no son compatibles debido a la falta de un responsable de mantenimiento.

Windows 2000 y las plataformas windows que establezcan COMSPEC a command.com ya no son compatibles debido a la carga de mantenimiento.

La compatibilidad con OSF, que quedó obsoleta en 3.2, ha sido completamente eliminada.

Módulos , funciones y métodos obsoletos en Python

Pasar una cadena no vacía a object.__format__() está descontinuado, y producirá un TypeError en Python 3.4 (bpo-9856 [https://bugs.python.org/issue?@action=redirect&bpo=9856]).

El códec unicode_internal quedó obsoleto a causa del PEP 393 [https://www.python.org/dev/peps/pep-0393], use UTF-8, UTF-16 (utf-16-le o utf-16-be), o UTF-32 (utf-32-le or utf-32-be)

ftplib.FTP.nlst() y ftplib.FTP.dir(): use ftplib.FTP.mlsd()

platform.popen(): use el módulo subprocess. Verifique especialmente la sección Cómo reemplazar anteriores funciones con el módulo subprocess (bpo-11377 [https://bugs.python.org/issue?@action=redirect&bpo=11377]).

bpo-13374 [https://bugs.python.org/issue?@action=redirect&bpo=13374]: La API de bytes de Windows ha sido descontinuada en el módulo os. Use nombres de archivo Unicode, en vez de nombres de archivo de bytes, para no depender más de la página de códigos ANSI y admitir cualquier nombre de archivo.

bpo-13988 [https://bugs.python.org/issue?@action=redirect&bpo=13988]: El módulo xml.etree.cElementTree ha quedado obsoleto. El acelerador se utiliza automáticamente siempre que esté disponible.

El comportamiento de time.clock() depende de la plataforma: utilice la nueva función time.perf_counter() o time.process_time() en su lugar, dependiendo de sus requerimientos, para tener un comportamiento bien definido.

La función os.stat_float_times() ha quedado obsoleta.

abc module:

La clase abc.abstractproperty ha quedado obsoleta, en su lugar use la clase property con abc.abstractmethod().

La clase abc.abstractclassmethod ha quedado obsoleta. En su lugar use el método classmethod with abc.abstractmethod().

abc.abstractstaticmethod ha quedado obsoleta, use staticmethod with abc.abstractmethod().

paquete importlib:

importlib.abc.SourceLoader.path_mtime() ha quedado obsoleto, a favor de importlib.abc.SourceLoader.path_stats() ya que los archivos de código de bytes ahora almacenan tanto la hora de modificación como el tamaño del archivo fuente desde el cual se compiló el archivo de código de bytes.

Funciones y tipos obsoletos en la API de C

El Py_UNICODE ha quedado obsoleto por PEP 393 [https://www.python.org/dev/peps/pep-0393] y será eliminado en Python 4. Todas las funciones que utilizan éste tipo quedarán en desuso:

Las funciones Unicode, y los métodos que usen los tipos Py_UNICODE and Py_UNICODE*:

PyUnicode_FromUnicode: use PyUnicode_FromWideChar() o PyUnicode_FromKindAndData()

PyUnicode_AS_UNICODE, PyUnicode_AsUnicode(), PyUnicode_AsUnicodeAndSize(): use PyUnicode_AsWideCharString()

PyUnicode_AS_DATA: use PyUnicode_DATA con PyUnicode_READ y PyUnicode_WRITE

PyUnicode_GET_SIZE, PyUnicode_GetSize(): use PyUnicode_GET_LENGTH o PyUnicode_GetLength()

PyUnicode_GET_DATA_SIZE: use PyUnicode_GET_LENGTH(str) * PyUnicode_KIND(str) (sólo funciona en cadenas listas)

PyUnicode_AsUnicodeCopy(): use PyUnicode_AsUCS4Copy() o PyUnicode_AsWideCharString()

PyUnicode_GetMax()

Funciones y macros que manipulen cadenas de caracteres Py_UNICODE*:

Py_UNICODE_strlen: use PyUnicode_GetLength() o PyUnicode_GET_LENGTH

Py_UNICODE_strcat: use PyUnicode_CopyCharacters() o PyUnicode_FromFormat()

Py_UNICODE_strcpy, Py_UNICODE_strncpy, Py_UNICODE_COPY: use PyUnicode_CopyCharacters() o PyUnicode_Substring()

Py_UNICODE_strcmp: use PyUnicode_Compare()

Py_UNICODE_strncmp: use PyUnicode_Tailmatch()

Py_UNICODE_strchr, Py_UNICODE_strrchr: use PyUnicode_FindChar()

Py_UNICODE_FILL: use PyUnicode_Fill()

Py_UNICODE_MATCH

Codificadores:

PyUnicode_Encode(): use PyUnicode_AsEncodedObject()

PyUnicode_EncodeUTF7()

PyUnicode_EncodeUTF8(): use PyUnicode_AsUTF8() o PyUnicode_AsUTF8String()

PyUnicode_EncodeUTF32()

PyUnicode_EncodeUTF16()

PyUnicode_EncodeUnicodeEscape:() use PyUnicode_AsUnicodeEscapeString()

PyUnicode_EncodeRawUnicodeEscape:() use PyUnicode_AsRawUnicodeEscapeString()

PyUnicode_EncodeLatin1(): use PyUnicode_AsLatin1String()

PyUnicode_EncodeASCII(): use PyUnicode_AsASCIIString()

PyUnicode_EncodeCharmap()

PyUnicode_TranslateCharmap()

PyUnicode_EncodeMBCS(): use PyUnicode_AsMBCSString() o PyUnicode_EncodeCodePage() (con CP_ACP code_page)

PyUnicode_EncodeDecimal(), PyUnicode_TransformDecimalToASCII()

Características obsoletas

El código del formato 'u' del módulo array ha quedado obsoleto y será eliminado en Python 4, junto con el resto de la API (Py_UNICODE).

Migración a Python 3.3

Esta sección enumera los cambios descritos previamente y otras correcciones que pueden requerir cambios en su código.

Portando código Python

La aleatoriedad de Hash ha sido habilitada de forma predeterminada. Establezca la variable de entorno PYTHONHASHSEED a 0, para deshabilitar la aleatoriedad de Hash. Vea también el método object.__hash__() method.

bpo-12326 [https://bugs.python.org/issue?@action=redirect&bpo=12326]: En Linux, sys.platform ya no contiene la versión principal. Ahora siempre es “linux”, en vez de “linux2” o “linux3” dependiendo de la versión de Linux usada para compilar Python. Reemplace sys.platform == “linux2” con sys.platform.startswith(“linux”), o directamente sys.platform == “linux” si no necesita admitir versiones anteriores de Python.

bpo-13847 [https://bugs.python.org/issue?@action=redirect&bpo=13847], bpo-14180 [https://bugs.python.org/issue?@action=redirect&bpo=14180]: time and datetime: OverflowError is now raised instead of ValueError if a timestamp is out of range. OSError is now raised if C functions gmtime() or localtime() failed.

Los buscadores predeterminados usados para las importaciones, ahora utilizan un caché de lo que está contenido en un directorio específico. Si crea un archivo fuente de Python o archivo de código de bytes sin fuente, asegúrese de llamar a importlib.invalidate_caches() para limpiar la caché para que los buscadores encuentren el nuevo archivo.

ImportError ahora usa el nombre completo del módulo que se intentó importar. Las pruebas de documentos que verifican el mensaje de “ImportErrors” necesitaran ser actualizados para usar el nombre completo del módulo en vez de sólo la terminación del nombre.

El argumento index para la función __import__() ahora tiene un valor predeterminado de 0, en vez de -1, y ya no admite valores negativos. Ha sido un descuido en la implementación de PEP 328 [https://www.python.org/dev/peps/pep-0328] que el valor predeterminado permaneciera en -1. Si necesita continuar realizando una importación relativa seguida por una importación absoluta, entonces realice la importación relativa usando un índice de 1, seguida por otra importación que use un índice de 0. Sin embargo, es preferible usar importlib.import_module() en vez de llamar a la función __import__() directamente.

__import__() ya no admite usar un valor de índice distinto de 0 para los módulos de alto nivel. Por ejemplo, __import__('sys', level=1) ahora es un error.

Dado que sys.meta_path y sys.path_hooks ahora tienen buscadores por defecto, lo más probable es que desee usar list.insert() en vez de list.append() para agregar a esas listas.

Dado que None ahora ha sido insertado en sys.path_importer_cache, si usted está borrando entradas en el diccionario de rutas que no tienen un buscador, usted necesitará eliminar los pares con valores de None y imp.NullImporter para ser compatible con versiones anteriores. Esto conducirá a una sobrecarga adicional con las versiones más antiguas de Python que re-inserten None dentro de sys.path_importer_cache donde éste represente el uso de buscadores implícitos, pero semánticamente no debería cambiar nada.

importlib.abc.Finder ya no especifica un método abstracto find_module() que deba ser implementado. Si confiaba en subclases para implementar éste método, primero asegúrese de verificar la existencia del método. Sin embargo, probablemente desee verificar primero el find_loader(), en el caso de trabajar con los buscadores de entradas path entry finders.

pkgutil ha sido convertido para usar importlib internamente. Esto elimina varios casos extremos donde el antiguo comportamiento de la emulación de importación PEP 302 [https://www.python.org/dev/peps/pep-0302] fallaba al comparar el comportamiento del sistema real de importación. La emulación de importación en sí aún está presente, pero está en desuso. Las funciones pkgutil.iter_importers() y pkgutil.walk_packages() en un caso especial son los ganchos de importación estándar, por lo que aún son compatibles aunque no proporcionen el método no estándar iter_modules ().

Se ha corregido un error de larga data de cumplimiento de RFC (bpo-1079 [https://bugs.python.org/issue?@action=redirect&bpo=1079]) en el análisis realizado por email.header.decode_header(). El código que usa el lenguaje estándar para convertir encabezados codificados en unicode (str (make_header (decode_header (h))) no verá cambios, pero el código que mira las tuplas individuales retornadas por decode_header verá ese espacio en blanco que precede o sigue las secciones ASCII ahora está incluido en la sección ASCII. El código que crea encabezados usando make_header también debería continuar funcionando sin cambios, ya que make_header continúa agregando espacios en blanco entre Secciones ASCII y no ASCII si aún no está presente en las cadenas de caracteres entrantes.

email.utils.formataddr() ahora realiza la codificación de transferencia de contenido correcta, al pasar nombres para mostrar que no son ASCII. Cualquier código que dependa del comportamiento defectuoso anterior que conservó el unicode que no es ASCII en la cadena de salida formateada deberá cambiarse (bpo-1690608 [https://bugs.python.org/issue?@action=redirect&bpo=1690608]).

poplib.POP3.quit() ahora puede generar errores de protocolos como todos los demás métodos poplib. El código que asume que quit no genera errores poplib.error_proto puede necesitar ser cambiado si una aplicación en particular encuentran errores en quit (bpo-11291 [https://bugs.python.org/issue?@action=redirect&bpo=11291]).

El argumento strict para la clase email.parser.Parser, que quedó obsoleto desde Python 2.4, finalmente ha sido eliminado.

El método unittest.TestCase.assertSameElements que estaba obsoleto, ha sido eliminado.

La variable time.accept2dyear que estaba obsoleta, ha sido eliminada.

El atributo Context._clamp que estaba obsoleto, ha sido eliminado del módulo decimal. Este se reemplazó anteriormente por el atributo público clamp. (Ver bpo-8540 [https://bugs.python.org/issue?@action=redirect&bpo=8540].)

La clase interna auxiliar indocumentada SSLFakeFile, ha sido eliminada de smtplib, dado que su funcionalidad ha sido proporcionada directamente por socket.socket.makefile().

El paso de valores negativos a la función time.sleep() en Windows, ahora lanza un error en vez de detenerse definitivamente. Este siempre ha lanzado un error en posix.

La constante ast.__version__ ha sido eliminada. Si usted necesita tomar decisiones afectadas por la versión AST, use sys.version_info para tomar la decisión.

El código que solía solucionar el hecho de que el módulo threading utilizaba funciones de fábrica mediante la subclase de las clases privadas tendrá que cambiar a la subclase de las clases ahora públicas.

La indocumentada maquinaria de depuración en el módulo threading ha sido eliminada, simplificando el código. Esto no debería tener efecto en el código de producción, pero se menciona aquí en caso de que algún framework de depuración de aplicaciones interactúe con el (bpo-13550 [https://bugs.python.org/issue?@action=redirect&bpo=13550]).

Portando código C

En el curso de cambios a la API del buffer la estructura indocumentada smalltable miembro de Py_buffer ha sido eliminada, y el diseño de PyMemoryViewObject se ha cambiado.

Todas las extensiones que quedan en las partes relevantes de memoryobject.h o object.h deben ser reconstruídas.

Debido a PEP 393, el tipo Py_UNICODE y todas las funciones que lo utilicen han quedado obsoletas (pero seguirán estando disponibles por al menos 5 años). Si usted estuvo usando APIS Unicode de bajo nivel para construir y acceder a objetos unicode, y desea beneficiarse de la reducción de huella de memoria proporcionada por PEP 393 [https://www.python.org/dev/peps/pep-0393], usted debe convertir su código al nuevo Unicode API.

Sin embargo, si sólo ha estado usando funciones de alto nivel como PyUnicode_Concat(), PyUnicode_Join() o PyUnicode_FromFormat(), automáticamente su código se beneficiará de las nuevas representaciones unicode.

PyImport_GetMagicNumber() ahora retorna -1 en caso de falla.

Como valor negativo para el argumento level de la función __import__() ya no es válido, y lo mismo ahora es válido para la función PyImport_ImportModuleLevel(). Esto también significa que el valor de level usado por la función PyImport_ImportModuleEx() ahora es 0 en vez de -1.

Construyendo extensiones C

Se ha reducido el rango de nombres de archivo posibles para las extensiones C. Muy raramente se han suprimido las ortografías utilizadas: en POSIX, los archivos denominados xxxmodule.so, xxxmodule.abi3.so y xxxmodule.cpython-*.so ya no se reconocen como la implementación del módulo xxx. Si ha estado generando estos archivos, tiene que cambiar a las otras ortografías (es decir, eliminar la cadena de caracteres módulo de los nombres de archivo).

(implementado en bpo-14040 [https://bugs.python.org/issue?@action=redirect&bpo=14040].)

Cambios en el conmutador de línea de comandos

Se han quitado el indicador de línea de comandos -Q y los artefactos relacionados. La comprobación de código sys.flags.division_warning tendrá que actualizar.

(bpo-10998 [https://bugs.python.org/issue?@action=redirect&bpo=10998], contribución de Éric Araujo.)

Cuando se inicia python con -S, import site ya no agregará las rutas específicas de sitio al módulo de búsqueda de rutas. En las versiones anteriores si lo hacía.

(bpo-11591 [https://bugs.python.org/issue?@action=redirect&bpo=11591], contribución de Carl Meyer con ediciones de Éric Araujo.)

Qué hay de nuevo en Python 3.2

Autor

Raymond Hettinger

Este artículo explica las nuevas características de Python 3.2 en comparación con 3.1. Se centra en algunos aspectos destacados y ofrece algunos ejemplos. Para obtener detalles completos, consulte el archivo Misc/NEWS [https://github.com/python/cpython/blob/076ca6c3c8df3030307e548d9be792ce3c1c6eea/Misc/NEWS] file.

Ver también

PEP 392 [https://www.python.org/dev/peps/pep-0392] - Calendario de Publicación Python 3.2

PEP 384: Definición de un ABI estable

En el pasado, los módulos de extensión creados para una versión de Python a menudo no se podían usar con otras versiones de Python. Particularmente en Windows, cada lanzamiento de funciones de Python requería reconstruir todos los módulos de extensión que uno quería usar. Este requisito fue el resultado del acceso gratuito a los componentes internos del intérprete de Python que los módulos de extensión podían usar.

Con Python 3.2, está disponible un enfoque alternativo: los módulos de extensión que se restringen a una API limitada (al definir Py_LIMITED_API) no pueden usar muchas de las funciones internas, pero están restringidos a un conjunto de funciones API que se promete serán estables para varias versiones. Como consecuencia, los módulos de extensión creados para 3.2 en ese modo también funcionarán con 3.3, 3.4, etc. Los módulos de extensión que hacen uso de los detalles de las estructuras de memoria aún se pueden construir, pero deberán recompilarse para cada lanzamiento de funciones.

Ver también

PEP 384 [https://www.python.org/dev/peps/pep-0384] - Definición de un ABI estable

PEP escrito por Martin von Löwis.

PEP 389: Módulo de análisis sintáctico (Parser) de línea de comandos Argparse

Se introdujo un nuevo módulo para el análisis de la línea de comandos, argparse, para superar las limitaciones de optparse que no brindaba soporte para argumentos posicionales (no solo opciones), subcomandos, opciones requeridas y otros patrones comunes para especificar y validar opciones.

Este módulo ya ha tenido un éxito generalizado en la comunidad como módulo de terceros. Con más funciones que su predecesor, el módulo argparse es ahora el módulo preferido para el procesamiento de la línea de comandos. El módulo más antiguo todavía se mantiene disponible debido a la gran cantidad de código heredado que depende de él.

Aquí hay un analizador de ejemplo comentado que muestra características de cómo limitar los resultados a un conjunto de opciones, especificar un metavar en la pantalla de ayuda, validar que uno o más argumentos posicionales están presentes y hacer una opción requerida::

import argparse
parser = argparse.ArgumentParser(
            description = 'Manage servers',         # main description for help
            epilog = 'Tested on Solaris and Linux') # displayed after help
parser.add_argument('action',                       # argument name
            choices = ['deploy', 'start', 'stop'],  # three allowed values
            help = 'action on each target')         # help msg
parser.add_argument('targets',
            metavar = 'HOSTNAME',                   # var name used in help msg
            nargs = '+',                            # require one or more targets
            help = 'url for target machines')       # help msg explanation
parser.add_argument('-u', '--user',                 # -u or --user option
            required = True,                        # make it a required argument
            help = 'login as user')

Ejemplo de llamada al analizador en una cadena de caracteres de comandos:

>>> cmd = 'deploy sneezy.example.com sleepy.example.com -u skycaptain'
>>> result = parser.parse_args(cmd.split())
>>> result.action
'deploy'
>>> result.targets
['sneezy.example.com', 'sleepy.example.com']
>>> result.user
'skycaptain'

Ejemplo de ayuda generada automáticamente por el analizador:

>>> parser.parse_args('-h'.split())

usage: manage_cloud.py [-h] -u USER
                       {deploy,start,stop} HOSTNAME [HOSTNAME ...]

Manage servers

positional arguments:
  {deploy,start,stop}   action on each target
  HOSTNAME              url for target machines

optional arguments:
  -h, --help            show this help message and exit
  -u USER, --user USER  login as user

Tested on Solaris and Linux

Una característica especialmente agradable de argparse es la capacidad de definir sub-analizadores (subparsers), cada uno con sus propios patrones de argumentos y pantallas de ayuda:

import argparse
parser = argparse.ArgumentParser(prog='HELM')
subparsers = parser.add_subparsers()

parser_l = subparsers.add_parser('launch', help='Launch Control')   # first subgroup
parser_l.add_argument('-m', '--missiles', action='store_true')
parser_l.add_argument('-t', '--torpedos', action='store_true')

parser_m = subparsers.add_parser('move', help='Move Vessel',        # second subgroup
                                 aliases=('steer', 'turn'))         # equivalent names
parser_m.add_argument('-c', '--course', type=int, required=True)
parser_m.add_argument('-s', '--speed', type=int, default=0)

$ ./helm.py --help                         # top level help (launch and move)
$ ./helm.py launch --help                  # help for launch options
$ ./helm.py launch --missiles              # set missiles=True and torpedos=False
$ ./helm.py steer --course 180 --speed 5   # set movement parameters

Ver también

PEP 389 [https://www.python.org/dev/peps/pep-0389] - Nuevo módulo de análisis de línea de comandos

PEP escrito por Steven Bethard.

Actualizar el código de optparse para obtener detalles sobre las diferencias con optparse.

PEP 391: Configuración basada en diccionario para Logging

El módulo logging proporcionó dos tipos de configuración, un estilo con llamadas de función para cada opción y otro estilo guiado por un archivo externo guardado en formato ConfigParser. Esas opciones no proporcionaron la flexibilidad para crear configuraciones a partir de archivos JSON o YAML, ni admitieron la configuración incremental, que es necesaria para especificar las opciones del logger desde una línea de comandos.

Para permitir un estilo más flexible, el módulo ahora ofrece logging.config.dictConfig() para especificar la configuración de logging con diccionarios simples de Python. Las opciones de configuración incluyen formateadores, gestores, filtros y loggers. Aquí hay un ejemplo funcional de un diccionario de configuración:

{"version": 1,
 "formatters": {"brief": {"format": "%(levelname)-8s: %(name)-15s: %(message)s"},
                "full": {"format": "%(asctime)s %(name)-15s %(levelname)-8s %(message)s"}
                },
 "handlers": {"console": {
                   "class": "logging.StreamHandler",
                   "formatter": "brief",
                   "level": "INFO",
                   "stream": "ext://sys.stdout"},
              "console_priority": {
                   "class": "logging.StreamHandler",
                   "formatter": "full",
                   "level": "ERROR",
                   "stream": "ext://sys.stderr"}
              },
 "root": {"level": "DEBUG", "handlers": ["console", "console_priority"]}}

Si ese diccionario está almacenado en un archivo llamado conf.json, se puede cargar y llamar con un código como este:

>>> import json, logging.config
>>> with open('conf.json') as f:
...     conf = json.load(f)
...
>>> logging.config.dictConfig(conf)
>>> logging.info("Transaction completed normally")
INFO    : root           : Transaction completed normally
>>> logging.critical("Abnormal termination")
2011-02-17 11:14:36,694 root            CRITICAL Abnormal termination

Ver también

PEP 391 [https://www.python.org/dev/peps/pep-0391] - Configuración basada en diccionario para Logging

PEP escrito por Vinay Sajip.

PEP 3148: El módulo concurrent.futures

El código para crear y administrar la concurrencia se está recopilando en un nuevo espacio de nombres de nivel superior, concurrent. Su primer miembro es un paquete futures que proporciona una interfaz uniforme de alto nivel para administrar hilos y procesos.

El diseño de concurrent.futures se inspiró en el paquete java.util.concurrent. En ese modelo, una llamada en ejecución y su resultado están representados por un objeto Future que abstrae características comunes a hilos, procesos y llamadas a procedimientos remotos. Ese objeto admite verificaciones de estado (en ejecución o terminadas), tiempos de espera, cancelaciones, agregar devoluciones de llamada y acceso a resultados o excepciones.

El agregado principal del nuevo módulo es un par de clases ejecutoras para lanzar y administrar llamadas. El objetivo de los ejecutores es facilitar el uso de las herramientas existentes para realizar llamadas en paralelo. Ahorran el esfuerzo necesario para configurar un grupo de recursos, lanzar las llamadas, crear una cola de resultados, agregar gestión de tiempo de espera y limitar la cantidad total de hilos, procesos o llamadas a procedimientos remotos.

Idealmente, cada aplicación debería compartir un solo ejecutor en varios componentes para que los límites de procesos e hilos se puedan administrar de forma centralizada. Esto resuelve el desafío de diseño que surge cuando cada componente tiene su propia estrategia competitiva para la gestión de recursos.

Ambas clases comparten una interfaz común con tres métodos: submit() para programar un invocable y retornar un objeto Future map() para programar muchas llamadas asincrónicas a la vez, y shutdown() para liberar recursos. La clase es un context manager y se puede usar en una declaración with para asegurar que los recursos se liberen automáticamente cuando los futuros actualmente pendientes terminan de ejecutarse.

Un ejemplo simple de ThreadPoolExecutor es un lanzamiento de cuatro hilos paralelos para copiar archivos:

import concurrent.futures, shutil
with concurrent.futures.ThreadPoolExecutor(max_workers=4) as e:
    e.submit(shutil.copy, 'src1.txt', 'dest1.txt')
    e.submit(shutil.copy, 'src2.txt', 'dest2.txt')
    e.submit(shutil.copy, 'src3.txt', 'dest3.txt')
    e.submit(shutil.copy, 'src3.txt', 'dest4.txt')

Ver también

PEP 3148 [https://www.python.org/dev/peps/pep-3148] - Futuros – Ejecutar Cómputos Asincrónicos

PEP escrito por Brian Quinlan.

Código para lecturas de URL en paralelo con grupos de hilos, un ejemplo que usa hilos para buscar varias páginas web en paralelo.

Código para calcular números primos en paralelo, un ejemplo demostrando ProcessPoolExecutor.

PEP 3147: Directorios del repositorio de PYC

El esquema de Python para almacenar en caché bytecode en archivos .pyc no funcionó bien en entornos con múltiples intérpretes de Python. Si un intérprete encontrara un archivo en caché creado por otro intérprete, volvería a compilar la fuente y sobrescribiría el archivo en caché, perdiendo así los beneficios del almacenamiento en caché.

El problema de las «peleas de pyc» se ha vuelto más pronunciado a medida que se ha convertido en un lugar común para las distribuciones de Linux enviadas con múltiples versiones de Python. Estos conflictos también surgen con alternativas de CPython como Unladen Swallow.

Para resolver este problema, el mecanismo de importación de Python se ha ampliado para utilizar nombres de archivo distintos para cada intérprete. En lugar de que Python 3.2 y Python 3.3 y Unladen Swallow compitan por un archivo llamado «mymodule.pyc», ahora buscarán «mymodule.cpython-32.pyc», «mymodule.cpython-33.pyc» y «mymodule .unladen10.pyc». Y para evitar que todos estos nuevos archivos abarroten los directorios de origen, los archivos pyc ahora se recopilan en un directorio «__pycache__» almacenado en el directorio del paquete.

Aparte de los nombres de archivo y directorios de destino, el nuevo esquema tiene algunos aspectos que son visibles para el programador:

Los módulos importados ahora tienen un atributo __cached__ que almacena el nombre del archivo real que se importó:

>>> import collections
>>> collections.__cached__
'c:/py32/lib/__pycache__/collections.cpython-32.pyc'

La etiqueta que es única para cada intérprete es accesible desde el módulo imp:

>>> import imp
>>> imp.get_tag()
'cpython-32'

Los scripts que intentan deducir el nombre del archivo de origen del archivo importado ahora deben ser más inteligentes. Ya no es suficiente simplemente quitar la «c» final del nombre de archivo «.pyc». En su lugar, use las nuevas funciones del módulo imp:

>>> imp.source_from_cache('c:/py32/lib/__pycache__/collections.cpython-32.pyc')
'c:/py32/lib/collections.py'
>>> imp.cache_from_source('c:/py32/lib/collections.py')
'c:/py32/lib/__pycache__/collections.cpython-32.pyc'

Los módulos py_compile y compileall se han actualizado para reflejar la nueva convención de nomenclatura y el directorio de destino. La invocación por línea de comandos de compileall tiene nuevas opciones: -i para especificar una lista de archivos y directorios para compilar y -b que hace que los archivos bytecode se escriban en su ubicación heredada en lugar de __pycache__.

El módulo importlib.abc se ha actualizado con una nueva clase base abstracta para cargar archivos bytecode. Las ABC (por sus siglas en inglés abstract base class) obsoletas, PyLoader y PyPycLoader, han sido deprecadas (las instrucciones sobre cómo mantener la compatibilidad con Python 3.1 se incluyen con la documentación).

Ver también

PEP 3147 [https://www.python.org/dev/peps/pep-3147] - Directorio del repositorio PYC

PEP escrito por Barry Warsaw.

PEP 3149: Archivos .so con etiquetado de versión para ABI

El directorio del repositorio PYC permite la ubicación conjunta de varios archivos de cache bytecode. Este PEP implementa un mecanismo similar para los archivos de objetos compartidos dándoles un directorio común y nombres distintos para cada versión.

El directorio común es «pyshared» y los nombres de los archivos se diferencian identificando la implementación de Python (como CPython, PyPy, Jython, etc.), los números de versión principal y secundaria, y las banderas de compilación opcionales (como «d» para debug, «m» para pymalloc, «u» para ancho-unicode). Para un paquete arbitrario «foo», se verán estos archivos cuando se instala el paquete de distribución:

/usr/share/pyshared/foo.cpython-32m.so
/usr/share/pyshared/foo.cpython-33md.so

En Python mismo, las etiquetas son accesibles desde funciones en el módulo sysconfig:

>>> import sysconfig
>>> sysconfig.get_config_var('SOABI')       # find the version tag
'cpython-32mu'
>>> sysconfig.get_config_var('EXT_SUFFIX')  # find the full filename extension
'.cpython-32mu.so'

Ver también

PEP 3149 [https://www.python.org/dev/peps/pep-3149] - PEP 3149: Archivos .so con etiquetado de versión para ABI

PEP escrito por Barry Warsaw.

PEP 3333: Interfaz de puerta de enlace del servidor web Python v1.0.1

Este PEP informativo aclara cómo el protocolo WSGI debe gestionar los problemas de bytes/texto. El desafío es que el manejo de cadenas de caracteres en Python 3 se maneja de manera más conveniente con el tipo str aunque el protocolo HTTP está orientado a bytes.

El PEP diferencia las llamadas cadenas nativas que se utilizan para los encabezados y metadatos de solicitud/respuesta (request/response) frente a las cadenas de bytes que se utilizan para los cuerpos de las solicitudes y respuestas.

Las cadenas nativas son siempre de tipo str pero están restringidas a puntos de código entre U+0000 * hasta *U+00FF que se pueden traducir a bytes usando la codificación Latin-1. Estas cadenas de caracteres se utilizan para las claves y valores en el diccionario de entorno y para los encabezados y estados de respuesta en la función start_response(). Deben seguir RFC 2616 [https://tools.ietf.org/html/rfc2616.html] con respecto a la codificación. Es decir, deben tener caracteres ISO-8859-1 o utilizar codificación MIME RFC 2047 [https://tools.ietf.org/html/rfc2047.html].

Para los desarrolladores que portan aplicaciones WSGI desde Python 2, estos son los puntos destacados:

Si la aplicación ya usó cadenas para encabezados en Python 2, no es necesario ningún cambio.

Si, en cambio, la aplicación codificó encabezados de salida o decodificó encabezados de entrada, entonces los encabezados deberán volver a codificarse en Latin-1. Por ejemplo, un encabezado de salida codificado en utf-8 usaba h.encode('utf-8'), ahora se necesita convertir de bytes a cadenas nativas usando h.encode('utf-8').decode('latin-1').

Los valores proporcionados por una aplicación o enviados mediante el método write() deben ser cadenas de bytes. La función start_response() y el entorno deben usar cadenas nativas. Los dos no se pueden mezclar.

Para los implementadores de servidores que escriben rutas de CGI a WSGI u otros protocolos de estilo CGI, los usuarios deben poder acceder al entorno utilizando cadenas nativas, aunque la plataforma subyacente pueda tener una convención diferente. Para cerrar esta brecha, el módulo wsgiref tiene una nueva función, wsgiref.handlers.read_environ() para transcodificar variables CGI de os.environ en cadenas nativas y retornar un nuevo diccionario.

Ver también

PEP 3333 [https://www.python.org/dev/peps/pep-3333] - Interfaz de puerta de enlace del servidor web Python v1.0.1

PEP escrito por Phillip Eby.

Otros cambios de lenguaje

Algunos cambios más pequeños realizados en el lenguaje central de Python son:

El formato de cadena de caracteres para format() y str.format() obtuvo nuevas capacidades para el carácter de formato #. Anteriormente, para enteros en binario, octal o hexadecimal, hacía que la salida tuviera el prefijo “0b”, “0o” o “0x” respectivamente. Ahora también puede manejar flotantes, complejos y decimales, lo que hace que la salida siempre tenga un punto decimal, incluso cuando no le siguen dígitos.

>>> format(20, '#o')
'0o24'
>>> format(12.34, '#5.0f')
'  12.'

(Sugerido por Mark Dickinson e implementado por Eric Smith en bpo-7094 [https://bugs.python.org/issue?@action=redirect&bpo=7094].)

También hay un nuevo método str.format_map() que amplía las capacidades del método existente str.format() al aceptar objetos arbitrarios mapping. Este nuevo método hace posible usar formato de cadena de caracteres con cualquiera de los muchos objetos similares a diccionarios de Python, como defaultdict, Shelf, ConfigParser, o dbm. También es útil con subclases personalizadas dict que normalizan claves antes de la búsqueda o que proporcionan un método __missing__() para claves desconocidas:

>>> import shelve
>>> d = shelve.open('tmp.shl')
>>> 'The {project_name} status is {status} as of {date}'.format_map(d)
'The testing project status is green as of February 15, 2011'

>>> class LowerCasedDict(dict):
...     def __getitem__(self, key):
...         return dict.__getitem__(self, key.lower())
>>> lcd = LowerCasedDict(part='widgets', quantity=10)
>>> 'There are {QUANTITY} {Part} in stock'.format_map(lcd)
'There are 10 widgets in stock'

>>> class PlaceholderDict(dict):
...     def __missing__(self, key):
...         return '<{}>'.format(key)
>>> 'Hello {name}, welcome to {location}'.format_map(PlaceholderDict())
'Hello <name>, welcome to <location>'

(Sugerido por Raymond Hettinger e implementado por Eric Smith en bpo-6081 [https://bugs.python.org/issue?@action=redirect&bpo=6081].)

El intérprete ahora puede iniciarse con una opción silenciosa, -q, para evitar que la información de copyright y versión se muestre en el modo interactivo. La opción se puede introspectar usando el atributo sys.flags:

$ python -q
>>> sys.flags
sys.flags(debug=0, division_warning=0, inspect=0, interactive=0,
optimize=0, dont_write_bytecode=0, no_user_site=0, no_site=0,
ignore_environment=0, verbose=0, bytes_warning=0, quiet=1)

(Contribución de Marcin Wojdyr en bpo-1772833 [https://bugs.python.org/issue?@action=redirect&bpo=1772833]).

La función hasattr() funciona llamando a getattr() y detectando si se lanza una excepción. Esta técnica le permite detectar métodos creados dinámicamente por __getattr__() o __getattribute__() que de otra manera estarían ausentes en el diccionario de la clase. Anteriormente, hasattr detectaba cualquier excepción, posiblemente enmascarando errores genuinos. Ahora, hasattr se ha ajustado para capturar solo AttributeError y dejar que otras excepciones pasen:

>>> class A:
...     @property
...     def f(self):
...         return 1 // 0
...
>>> a = A()
>>> hasattr(a, 'f')
Traceback (most recent call last):
  ...
ZeroDivisionError: integer division or modulo by zero

(Descubierto por Yury Selivanov y arreglado por Benjamin Peterson; bpo-9666 [https://bugs.python.org/issue?@action=redirect&bpo=9666].)

La str() de un número flotante o complejo ahora es el mismo que su repr(). Anteriormente, el formulario str() era más corto, pero eso solo causaba confusión y ya no es necesario ahora que el más corto posible repr() se muestra por defecto:

>>> import math
>>> repr(math.pi)
'3.141592653589793'
>>> str(math.pi)
'3.141592653589793'

(Propuesto e implementado por Mark Dickinson; bpo-9337 [https://bugs.python.org/issue?@action=redirect&bpo=9337].)

Los objetos memoryview ahora tienen un método release() y ahora también admiten el protocolo de gestión de contexto. Esto permite la liberación oportuna de los recursos adquiridos al solicitar un búfer del objeto original.

>>> with memoryview(b'abcdefgh') as v:
...     print(v.tolist())
[97, 98, 99, 100, 101, 102, 103, 104]

(Añadido por Antoine Pitrou; bpo-9757 [https://bugs.python.org/issue?@action=redirect&bpo=9757].)

Anteriormente, era ilegal eliminar un nombre del espacio de nombres local si aparece como una variable libre en un bloque anidado:

def outer(x):
    def inner():
        return x
    inner()
    del x

Esto ahora está permitido. Recuerde que el objetivo de una cláusula except se borra, por lo que este código que solía funcionar con Python 2.6, lanza un SyntaxError con Python 3.1 y ahora funciona nuevamente:

def f():
    def print_error():
        print(e)
    try:
        something
    except Exception as e:
        print_error()
        # implicit "del e" here

(Ver bpo-4617 [https://bugs.python.org/issue?@action=redirect&bpo=4617].)

La herramienta interna structsequence ahora crea subclases de tupla. Esto significa que las estructuras C como las retornadas por os.stat(), time.gmtime(), y sys.version_info ahora funcionan como named tuple y ahora trabaja con funciones y métodos que esperan una tupla como argumento. Este es un gran paso adelante para hacer que las estructuras de C sean tan flexibles como sus contrapartes de Python puro:

>>> import sys
>>> isinstance(sys.version_info, tuple)
True
>>> 'Version %d.%d.%d %s(%d)' % sys.version_info
'Version 3.2.0 final(0)'

(Sugerido por Arfrever Frehtes Taifersar Arahesis e implementado por Benjamin Peterson en bpo-8413 [https://bugs.python.org/issue?@action=redirect&bpo=8413].)

Las Warnings ahora son más fáciles de controlar usando la variable de entorno PYTHONWARNINGS como alternativa al uso de -W en la línea de comando:

$ export PYTHONWARNINGS='ignore::RuntimeWarning::,once::UnicodeWarning::'

(Sugerido por Barry Warsaw e implementado por Philip Jenvey en bpo-7301 [https://bugs.python.org/issue?@action=redirect&bpo=7301].)

Se ha agregado una nueva categoría de advertencia, ResourceWarning. Se emite cuando se detectan problemas potenciales con el consumo de recursos o la limpieza. Está silenciado de forma predeterminada en las versiones de lanzamiento normales, pero se puede habilitar a través de los medios proporcionados por el módulo warnings o en la línea de comandos.

Un ResourceWarning se emite en el cierre del intérprete si la lista gc.garbage no está vacía, y si gc.DEBUG_UNCOLLECTABLE está configurado, se imprimen todos los objetos no recolectados. Esto tiene como objetivo informar al programador de que su código contiene problemas de finalización de objetos.

Un ResourceWarning también se emite cuando un file object se destruye sin haber sido cerrado explícitamente. Si bien el desasignador de dicho objeto asegura que cierra el recurso del sistema operativo subyacente (generalmente, un descriptor de archivo), la demora en desasignar el objeto podría producir varios problemas, especialmente en Windows. A continuación, se muestra un ejemplo de cómo habilitar la advertencia desde la línea de comando:

$ python -q -Wdefault
>>> f = open("foo", "wb")
>>> del f
__main__:1: ResourceWarning: unclosed file <_io.BufferedWriter name='foo'>

(Agregado por Antoine Pitrou y Georg Brandl en bpo-10093 [https://bugs.python.org/issue?@action=redirect&bpo=10093] y bpo-477863 [https://bugs.python.org/issue?@action=redirect&bpo=477863].)

Los objetos range ahora admiten los métodos index y count. Esto es parte de un esfuerzo para hacer que más objetos implementen completamente la abstract base class collections.Sequence. Como resultado, el lenguaje tendrá una API más uniforme. Además, los objetos range ahora admiten índices negativos y de corte, incluso con valores mayores que sys.maxsize. Esto hace que range sea más interoperable con listas:

>>> range(0, 100, 2).count(10)
1
>>> range(0, 100, 2).index(10)
5
>>> range(0, 100, 2)[5]
10
>>> range(0, 100, 2)[0:5]
range(0, 10, 2)

(Contribuido por Daniel Stutzbach en bpo-9213 [https://bugs.python.org/issue?@action=redirect&bpo=9213], por Alexander Belopolsky en bpo-2690 [https://bugs.python.org/issue?@action=redirect&bpo=2690], y por Nick Coghlan en bpo-10889 [https://bugs.python.org/issue?@action=redirect&bpo=10889].)

Se resucitó la función incorporada callable() de Py2.x. Proporciona una alternativa concisa y legible al uso de una abstract base class en una expresión como isinstance(x, collections.Callable):

>>> callable(max)
True
>>> callable(20)
False

(Ver bpo-10518 [https://bugs.python.org/issue?@action=redirect&bpo=10518].)

El mecanismo de importación de Python ahora puede cargar módulos instalados en directorios con caracteres no ASCII en el nombre de la ruta. Esto resolvió un problema agravante con los directorios de inicio para los usuarios con caracteres no ASCII en sus nombres de usuario.

(Trabajo extenso requerido por Victor Stinner en bpo-9425 [https://bugs.python.org/issue?@action=redirect&bpo=9425].)

Módulos nuevos, mejorados y obsoletos

La biblioteca estándar de Python ha sido objeto de importantes esfuerzos de mantenimiento y mejoras de calidad.

La mayor novedad para Python 3.2 es que el paquete email, el módulo mailbox y los módulos nntplib ahora funcionan correctamente con el modelo de bytes/texto en Python 3. Por primera vez , existe un manejo correcto de mensajes con codificaciones mixtas.

En toda la biblioteca estándar, se ha prestado más atención a las codificaciones y los problemas de texto frente a bytes. En particular, las interacciones con el sistema operativo ahora son más capaces de intercambiar datos que no son ASCII mediante la codificación MBCS de Windows, codificaciones con reconocimiento de configuración regional o UTF-8.

Otro logro importante es la adición de un soporte sustancialmente mejor para conexiones SSL y certificados de seguridad.

Además, más clases ahora implementan context manager para soportar una conveniente y confiable limpieza de recursos usando una declaración with.

email

La usabilidad del paquete email en Python 3 se ha solucionado principalmente gracias a los amplios esfuerzos de R. David Murray. El problema era que los correos electrónicos generalmente se leen y almacenan en forma de bytes en lugar de texto str, y pueden contener múltiples codificaciones dentro de un solo correo electrónico. Por lo tanto, el paquete email tuvo que ampliarse para analizar y generar mensajes de correo electrónico en formato de bytes.

Nuevas funciones message_from_bytes() y message_from_binary_file(), y nuevas clases BytesFeedParser y BytesParser permiten mensajes de datos en binario para ser analizados (parsed) en objetos modelados.

Dada la entrada de bytes al modelo, get_payload() decodificará por defecto un cuerpo de mensaje que tiene un Content-Transfer-Encoding de 8bit usando el juego de caracteres especificado en el encabezados MIME y retorna la cadena de caracteres resultante.

Dada la entrada de bytes al modelo, Generator convertirá los cuerpos de los mensajes que tengan un Content-Transfer-Encoding de 8bit para tener en su lugar un 7bitContent-Transfer-Encoding.

Los encabezados con bytes no codificados que no sean ASCII se consideran RFC 2047 [https://tools.ietf.org/html/rfc2047.html]-codificados utilizando el juego de caracteres unknown-8bit.

Una nueva clase BytesGenerator produce bytes como salida, conservando cualquier dato no ASCII sin cambios que estuviera presente en la entrada utilizada para construir el modelo, incluidos los cuerpos de los mensajes con un Content-Transfer-Encoding de 8bit.

La clase smtplibSMTP ahora acepta una cadena de bytes para el argumento msg para el método sendmail(), y un nuevo método, send_message() acepta un objeto Message y opcionalmente puede obtener las direcciones from_addr y to_addrs directamente del objeto.

(Propuesto e implementado por R. David Murray, bpo-4661 [https://bugs.python.org/issue?@action=redirect&bpo=4661] y bpo-10321 [https://bugs.python.org/issue?@action=redirect&bpo=10321].)

elementtree

El paquete xml.etree.ElementTree y su contraparte xml.etree.cElementTree se han actualizado a la versión 1.3.

Se han agregado varias nuevas y útiles funciones y métodos:

xml.etree.ElementTree.fromstringlist() que crea un documento XML a partir de una secuencia de fragmentos

xml.etree.ElementTree.register_namespace() para registrar un prefijo de espacio de nombres global

xml.etree.ElementTree.tostringlist() para la representación de cadenas de caracteres, incluidas todas las sublistas

xml.etree.ElementTree.Element.extend() para agregar una secuencia de cero o más elementos

xml.etree.ElementTree.Element.iterfind() busca un elemento y subelementos

xml.etree.ElementTree.Element.itertext() crea un iterador de texto sobre un elemento y sus subelementos

xml.etree.ElementTree.TreeBuilder.end() cierra el elemento actual

xml.etree.ElementTree.TreeBuilder.doctype() gestiona la declaración doctype

Dos métodos que han sido deprecados:

xml.etree.ElementTree.getchildren() usar list(elem) en su lugar.

xml.etree.ElementTree.getiterator() usar Element.iter en su lugar.

For details of the update, see Introducing ElementTree [https://web.archive.org/web/20200703234532/http://effbot.org/zone/elementtree-13-intro.htm] on Fredrik Lundh’s website.

(Contribución de Florent Xicluna y Fredrik Lundh, bpo-6472 [https://bugs.python.org/issue?@action=redirect&bpo=6472].)

functools

El módulo functools incluye un nuevo decorador para almacenar en caché las llamadas a funciones. functools.lru_cache() puede guardar consultas repetidas en un recurso externo siempre que se espere que los resultados sean los mismos.

Por ejemplo, agregar un decorador de almacenamiento en caché a una función de consulta de base de datos puede ahorrar accesos a la base de datos para búsquedas populares:

>>> import functools
>>> @functools.lru_cache(maxsize=300)
... def get_phone_number(name):
...     c = conn.cursor()
...     c.execute('SELECT phonenumber FROM phonelist WHERE name=?', (name,))
...     return c.fetchone()[0]

>>> for name in user_requests:
...     get_phone_number(name)        # cached lookup

Para ayudar a elegir un tamaño de caché efectivo, la función encapsulada está instrumentada para rastrear estadísticas de caché:

>>> get_phone_number.cache_info()
CacheInfo(hits=4805, misses=980, maxsize=300, currsize=300)

Si la tabla phonelist se actualiza, el contenido desactualizado de la caché se puede borrar con:

>>> get_phone_number.cache_clear()

(Contribución de Raymond Hettinger e incorporando ideas de diseño de Jim Baker, Miki Tebeka, y Nick Coghlan; ver recipe 498245 [https://code.activestate.com/recipes/498245], recipe 577479 [https://code.activestate.com/recipes/577479], bpo-10586 [https://bugs.python.org/issue?@action=redirect&bpo=10586], y bpo-10593 [https://bugs.python.org/issue?@action=redirect&bpo=10593].)

El decorador functools.wraps() ahora agrega un atributo __wrapped__ que apunta a la función invocable original. Esto permite la introspección de funciones envueltas (wrapped). También copia __annotations__ si está definido. Y ahora también omite elegantemente los atributos faltantes como __doc__ que podrían no estar definidos para el invocable envuelto.

En el ejemplo anterior, la caché se puede eliminar recuperando la función original:

>>> get_phone_number = get_phone_number.__wrapped__    # uncached function

(Por Nick Coghlan y Terrence Cole; bpo-9567 [https://bugs.python.org/issue?@action=redirect&bpo=9567], bpo-3445 [https://bugs.python.org/issue?@action=redirect&bpo=3445], y bpo-8814 [https://bugs.python.org/issue?@action=redirect&bpo=8814].)

Para ayudar a escribir clases con métodos de comparación enriquecidos, un nuevo decorador functools.total_ordering() usará métodos de igualdad y desigualdad existentes para completar los métodos restantes.

Por ejemplo, suministrar __eq__ y __lt__ permitirá que total_ordering() complete __le__, __gt__ and __ge__:

@total_ordering
class Student:
    def __eq__(self, other):
        return ((self.lastname.lower(), self.firstname.lower()) ==
                (other.lastname.lower(), other.firstname.lower()))

    def __lt__(self, other):
        return ((self.lastname.lower(), self.firstname.lower()) <
                (other.lastname.lower(), other.firstname.lower()))

Con el decorador total_ordering, los métodos de comparación restantes se completan automáticamente.

(Contribución por Raymond Hettinger.)

Para ayudar en la migración de programas desde Python 2, la función functools.cmp_to_key() convierte una función de comparación de estilo antiguo en la nueva key function:

>>> # locale-aware sort order
>>> sorted(iterable, key=cmp_to_key(locale.strcoll))

Para obtener ejemplos de ordenación y un breve tutorial, consulte el tutorial Sorting HowTo [https://wiki.python.org/moin/HowTo/Sorting/].

(Contribución por Raymond Hettinger.)

itertools

El módulo itertools tiene una nueva función accumulate() modelada en el operador scan de APL y la función accumulate de Numpy:

>>> from itertools import accumulate
>>> list(accumulate([8, 2, 50]))
[8, 10, 60]

>>> prob_dist = [0.1, 0.4, 0.2, 0.3]
>>> list(accumulate(prob_dist))      # cumulative probability distribution
[0.1, 0.5, 0.7, 1.0]

Para un ejemplo usando accumulate(), vea los ejemplos para el módulo aleatorio.

(Contribución de Raymond Hettinger e incorporando sugerencias de diseño de Mark Dickinson.)

collections

La clase collections.Counter ahora tiene dos formas de resta in situ, el operador existente -= para saturación de resta [https://es.wikipedia.org/wiki/Aritm%C3%A9tica_de_saturaci%C3%B3n] y el nuevo método subtract() para la resta regular. El primero es adecuado para muticonjunto [https://es.wikipedia.org/wiki/Multiconjunto] que solo tienen recuentos positivos, y el último es más adecuado para casos de uso que permiten recuentos negativos:

>>> from collections import Counter
>>> tally = Counter(dogs=5, cats=3)
>>> tally -= Counter(dogs=2, cats=8)    # saturating subtraction
>>> tally
Counter({'dogs': 3})

>>> tally = Counter(dogs=5, cats=3)
>>> tally.subtract(dogs=2, cats=8)      # regular subtraction
>>> tally
Counter({'dogs': 3, 'cats': -5})

(Contribución por Raymond Hettinger.)

La clase collections.OrderedDict tiene un nuevo método move_to_end() que toma una clave existente y mueve a la primera o última posición de la secuencia ordenada.

El valor predeterminado es mover un elemento a la última posición. Esto es equivalente a renovar una entrada con od[k] = od.pop(k).

Una operación de mover al final rápida es útil para volver a secuenciar entradas. Por ejemplo, se puede usar un diccionario ordenado para rastrear el orden de acceso a las entradas por antigüedad desde la más antigua hasta la más reciente.

>>> from collections import OrderedDict
>>> d = OrderedDict.fromkeys(['a', 'b', 'X', 'd', 'e'])
>>> list(d)
['a', 'b', 'X', 'd', 'e']
>>> d.move_to_end('X')
>>> list(d)
['a', 'b', 'd', 'e', 'X']

(Contribución por Raymond Hettinger.)

La clase collections.deque desarrolló dos métodos nuevos count() y reverse() que los hacen más intercambiables con los objetos list :

>>> from collections import deque
>>> d = deque('simsalabim')
>>> d.count('s')
2
>>> d.reverse()
>>> d
deque(['m', 'i', 'b', 'a', 'l', 'a', 's', 'm', 'i', 's'])

(Contribución por Raymond Hettinger.)

threading

El módulo threading tiene una nueva clase Barrier de sincronización para hacer que varios hilos esperen hasta que todos hayan alcanzado un punto de barrera común. Las barreras son útiles para asegurarse de que una tarea con múltiples condiciones previas no se ejecute hasta que se completen todas las tareas predecesoras.

Las barreras pueden trabajar con un número arbitrario de hilos. Esto es una generalización de barrera informática [https://es.wikipedia.org/wiki/Barrera_(inform%C3%A1tica)] que se define solo para dos hilos.

Implementado como una barrera cíclica de dos fases, los objetos Barrier son adecuados para su uso en bucles. Las fases separadas de llenado y drenaje aseguran que todos los hilos se liberen (drenan) antes de que cualquiera de ellos pueda retornar y volver a entrar en la barrera. La barrera se restablece completamente después de cada ciclo.

Ejemplo de uso de barreras:

from threading import Barrier, Thread

def get_votes(site):
    ballots = conduct_election(site)
    all_polls_closed.wait()        # do not count until all polls are closed
    totals = summarize(ballots)
    publish(site, totals)

all_polls_closed = Barrier(len(sites))
for site in sites:
    Thread(target=get_votes, args=(site,)).start()

En este ejemplo, la barrera impone una regla de que los votos no se pueden contar en ningún lugar de votación hasta que se cierren todas las urnas. Observe cómo una solución con una barrera es similar a una con threading.Thread.join(), pero los hilos se mantienen vivos y continúan trabajando (resumiendo las papeletas) después de que se cruza el punto de la barrera.

Si alguna de las tareas predecesoras puede bloquearse o retrasarse, se puede crear una barrera con un parámetro opcional timeout. Luego, si el período de tiempo de espera transcurre antes de que todas las tareas predecesoras alcancen el punto de barrera, se liberan todos los hilos en espera y se lanza una excepción BrokenBarrierError:

def get_votes(site):
    ballots = conduct_election(site)
    try:
        all_polls_closed.wait(timeout=midnight - time.now())
    except BrokenBarrierError:
        lockbox = seal_ballots(ballots)
        queue.put(lockbox)
    else:
        totals = summarize(ballots)
        publish(site, totals)

En este ejemplo, la barrera impone una regla más sólida. Si algunos sitios electorales no terminan antes de la medianoche, la barrera expira y las boletas se sellan y se depositan en una cola para su posterior manejo.

Consulte Patrones de sincronización de barreras <http://osl.cs.illinois.edu/media/papers/karmani-2009-barrier_synchronization_pattern.pdf> _ para ver más ejemplos de cómo se pueden utilizar las barreras en computación paralela. Además, hay una explicación simple pero completa de las barreras en The Little Book of Semaphores [https://greenteapress.com/semaphores/LittleBookOfSemaphores.pdf], sección 3.6.

(Contribución de Kristján Valur Jónsson con una revisión de API de Jeffrey Yasskin en bpo-8777 [https://bugs.python.org/issue?@action=redirect&bpo=8777].)

datetime and time

El módulo datetime tiene un nuevo tipo timezone que implementa la interfaz tzinfo retornando un desplazamiento fijo desde UTC y un nombre de zona horaria. Esto hace que sea más fácil crear objetos de fecha y hora que tengan en cuenta la zona horaria:

>>> from datetime import datetime, timezone

>>> datetime.now(timezone.utc)
datetime.datetime(2010, 12, 8, 21, 4, 2, 923754, tzinfo=datetime.timezone.utc)

>>> datetime.strptime("01/01/2000 12:00 +0000", "%m/%d/%Y %H:%M %z")
datetime.datetime(2000, 1, 1, 12, 0, tzinfo=datetime.timezone.utc)

Además, los objetos timedelta ahora pueden ser multiplicados por objetos float y divididos por objetos float e int. Y los objetos timedelta ahora se pueden dividir entre sí.

El método datetime.date.strftime() ya no está restringido a años posteriores a 1900. El nuevo rango de años admitido es de 1000 a 9999 inclusive.

Siempre que se utiliza un año de dos dígitos en una tupla de tiempo, la interpretación se rige por time.accept2dyear. El valor predeterminado es True, lo que significa que para un año de dos dígitos, el siglo se calcula de acuerdo con las reglas POSIX que rigen el formato strptime %y.

A partir de Py3.2, el uso de la heurística de adivinación del siglo emitirá un DeprecationWarning. En su lugar, se recomienda que time.accept2dyear se establezca en False para que se puedan usar rangos de fechas grandes sin suposiciones:

>>> import time, warnings
>>> warnings.resetwarnings()      # remove the default warning filters

>>> time.accept2dyear = True      # guess whether 11 means 11 or 2011
>>> time.asctime((11, 1, 1, 12, 34, 56, 4, 1, 0))
Warning (from warnings module):
  ...
DeprecationWarning: Century info guessed for a 2-digit year.
'Fri Jan  1 12:34:56 2011'

>>> time.accept2dyear = False     # use the full range of allowable dates
>>> time.asctime((11, 1, 1, 12, 34, 56, 4, 1, 0))
'Fri Jan  1 12:34:56 11'

Varias funciones ahora tienen rangos de fechas significativamente ampliados. Cuando time.accept2dyear es falso, la función time.asctime() aceptará cualquier año que quepa en un entero C, mientras que las funciones time.mktime() y time.strftime() aceptarán la gama completa admitida por las funciones correspondientes del sistema operativo.

(Contribución de Alexander Belopolsky y Victor Stinner en bpo-1289118 [https://bugs.python.org/issue?@action=redirect&bpo=1289118], bpo-5094 [https://bugs.python.org/issue?@action=redirect&bpo=5094], bpo-6641 [https://bugs.python.org/issue?@action=redirect&bpo=6641], bpo-2706 [https://bugs.python.org/issue?@action=redirect&bpo=2706], bpo-1777412 [https://bugs.python.org/issue?@action=redirect&bpo=1777412], bpo-8013 [https://bugs.python.org/issue?@action=redirect&bpo=8013], y bpo-10827 [https://bugs.python.org/issue?@action=redirect&bpo=10827].)

math

El módulo math se ha actualizado con seis nuevas funciones inspiradas en el estándar C99.

La función isfinite() proporciona una forma rápida y fiable de detectar valores especiales. Retorna True para números regulares y False para Nan o Infinity:

>>> from math import isfinite
>>> [isfinite(x) for x in (123, 4.56, float('Nan'), float('Inf'))]
[True, True, False, False]

La función expm1() calcula e**x-1 para valores pequeños de x sin incurrir en la pérdida de precisión que generalmente acompaña a la resta de cantidades casi iguales:

>>> from math import expm1
>>> expm1(0.013671875)   # more accurate way to compute e**x-1 for a small x
0.013765762467652909

La función erf() calcula una integral de probabilidad o función de error gaussiano [https://es.wikipedia.org/wiki/Funci%C3%B3n_error]. La función de error complementaria, erfc(), es 1 - erf(x):

>>> from math import erf, erfc, sqrt
>>> erf(1.0/sqrt(2.0))   # portion of normal distribution within 1 standard deviation
0.682689492137086
>>> erfc(1.0/sqrt(2.0))  # portion of normal distribution outside 1 standard deviation
0.31731050786291404
>>> erf(1.0/sqrt(2.0)) + erfc(1.0/sqrt(2.0))
1.0

La función gamma() es una extensión continua de la función factorial. Consulte https://es.wikipedia.org/wiki/Funci%C3%B3n_gamma para obtener más detalles. Debido a que la función está relacionada con factoriales, crece incluso para valores pequeños de x, por lo que también hay una función lgamma() para calcular el logaritmo natural de la función gamma:

>>> from math import gamma, lgamma
>>> gamma(7.0)           # six factorial
720.0
>>> lgamma(801.0)        # log(800 factorial)
4551.950730698041

(Contribución de Mark Dickinson.)

abc

El módulo abc ahora admite abstractclassmethod() y abstractstaticmethod().

Estas herramientas permiten definir una abstract base class que requiere un classmethod() o staticmethod() particular para ser implementado:

class Temperature(metaclass=abc.ABCMeta):
    @abc.abstractclassmethod
    def from_fahrenheit(cls, t):
        ...
    @abc.abstractclassmethod
    def from_celsius(cls, t):
        ...

(Parche enviado por Daniel Urban; bpo-5867 [https://bugs.python.org/issue?@action=redirect&bpo=5867].)

io

La clase io.BytesIO tiene un nuevo método, getbuffer(), que proporciona una funcionalidad similar a memoryview(). Crea una vista editable de los datos sin hacer una copia. El acceso aleatorio del búfer y la compatibilidad con la notación de sectores son adecuados para la edición in situ:

>>> REC_LEN, LOC_START, LOC_LEN = 34, 7, 11

>>> def change_location(buffer, record_number, location):
...     start = record_number * REC_LEN + LOC_START
...     buffer[start: start+LOC_LEN] = location

>>> import io

>>> byte_stream = io.BytesIO(
...     b'G3805  storeroom  Main chassis    '
...     b'X7899  shipping   Reserve cog     '
...     b'L6988  receiving  Primary sprocket'
... )
>>> buffer = byte_stream.getbuffer()
>>> change_location(buffer, 1, b'warehouse  ')
>>> change_location(buffer, 0, b'showroom   ')
>>> print(byte_stream.getvalue())
b'G3805  showroom   Main chassis    '
b'X7899  warehouse  Reserve cog     '
b'L6988  receiving  Primary sprocket'

(Contribución de Antoine Pitrou en bpo-5506 [https://bugs.python.org/issue?@action=redirect&bpo=5506].)

reprlib

Al escribir un método __repr__() para un contenedor personalizado, es fácil olvidarse de gestionar el caso en el que un miembro hace referencia al contenedor en sí. Los objetos incorporados de Python como list y set manejan la autorreferencia mostrando «…» en la parte recursiva de la cadena de representación.

Para ayudar a escribir tales métodos __repr__(), el módulo reprlib tiene un nuevo decorador, recursive_repr(), para detectar llamadas recursivas a __repr__() y sustituir una cadena marcadora de posición en su lugar:

>>> class MyList(list):
...     @recursive_repr()
...     def __repr__(self):
...         return '<' + '|'.join(map(repr, self)) + '>'
...
>>> m = MyList('abc')
>>> m.append(m)
>>> m.append('x')
>>> print(m)
<'a'|'b'|'c'|...|'x'>

(Contribución de Raymond Hettinger en bpo-9826 [https://bugs.python.org/issue?@action=redirect&bpo=9826] y bpo-9840 [https://bugs.python.org/issue?@action=redirect&bpo=9840].)

logging

Además de la configuración basada en diccionario descrita anteriormente, el paquete logging tiene muchas otras mejoras.

La documentación de logging se ha aumentado con un tutorial básico, un tutorial avanzado, y un libro de recetas. Estos documentos son la forma más rápida de aprender sobre logging.

La función de configuración logging.basicConfig() adquirió un argumento style para admitir tres tipos diferentes de formato de cadena de caracteres. Su valor predeterminado es «%» para el formato % tradicional, se puede establecer en «{» para el nuevo estilo str.format(), o se puede establecer en «$» para el formato de estilo shell proporcionado por string.Template. Las siguientes tres configuraciones son equivalentes:

>>> from logging import basicConfig
>>> basicConfig(style='%', format="%(name)s -> %(levelname)s: %(message)s")
>>> basicConfig(style='{', format="{name} -> {levelname} {message}")
>>> basicConfig(style='$', format="$name -> $levelname: $message")

Si no se establece ninguna configuración antes de que ocurra un evento de logging, ahora hay una configuración predeterminada que usa una StreamHandler dirigido a sys.stderr para eventos de nivel WARNING o mayor. Anteriormente, un evento que ocurría antes de que se establezca una configuración lanzaba una excepción o eliminaba silenciosamente el evento según el valor de logging.raiseExceptions. El nuevo gestor predeterminado se almacena en logging.lastResort.

El uso de filtros ha sido simplificado. En lugar de crear un objeto Filter, la declaración puede ser cualquier invocable Python que retorna True o False.

Hubo una serie de otras mejoras que agregan flexibilidad y simplifican la configuración. Consulte la documentación del módulo para obtener una lista completa de los cambios en Python 3.2.

csv

El módulo csv ahora admite un nuevo dialecto, unix_dialect, que aplica comillas para todos los campos y un estilo Unix tradicional con '\n' como terminador de línea. El nombre del dialecto registrado es unix.

La clase csv.DictWriter tiene un nuevo método, writeheader() para escribir una fila inicial para documentar los nombres de los campos:

>>> import csv, sys
>>> w = csv.DictWriter(sys.stdout, ['name', 'dept'], dialect='unix')
>>> w.writeheader()
"name","dept"
>>> w.writerows([
...     {'name': 'tom', 'dept': 'accounting'},
...     {'name': 'susan', 'dept': 'Salesl'}])
"tom","accounting"
"susan","sales"

(Nuevo dialecto sugerido por Jay Talbot en bpo-5975 [https://bugs.python.org/issue?@action=redirect&bpo=5975], y el nuevo método sugerido por Ed Abraham en bpo-1537721 [https://bugs.python.org/issue?@action=redirect&bpo=1537721].)

contextlib

Hay una nueva y ligeramente alucinante herramienta ContextDecorator que es útil para crear un context manager que cumple una doble función como decorador de funciones.

Para su comodidad, esta nueva funcionalidad es utilizada por contextmanager() de modo que no se necesita ningún esfuerzo adicional para admitir ambos roles.

La idea básica es que tanto los gestores de contexto como los decoradores de funciones se pueden usar para envoltorios (wrappers) previos y posteriores a la acción. Los gestores de contexto envuelven un grupo de declaraciones usando la declaración with y los decoradores de funciones envuelven un grupo de declaraciones encerradas en una función. Por lo tanto, ocasionalmente es necesario escribir un envoltorio de acción previa o posterior que se pueda usar en cualquiera de los roles.

Por ejemplo, a veces es útil envolver funciones o grupos de declaraciones con un logger que pueda rastrear el tiempo de entrada y el tiempo de salida. En lugar de escribir tanto un decorador de funciones como un gestor de contexto para la tarea, contextmanager() proporciona ambas capacidades en una sola definición:

from contextlib import contextmanager
import logging

logging.basicConfig(level=logging.INFO)

@contextmanager
def track_entry_and_exit(name):
    logging.info('Entering: %s', name)
    yield
    logging.info('Exiting: %s', name)

Anteriormente, esto solo se podía usar como gestor de contexto:

with track_entry_and_exit('widget loader'):
    print('Some time consuming activity goes here')
    load_widget()

Ahora, también se puede usar como decorador:

@track_entry_and_exit('widget loader')
def activity():
    print('Some time consuming activity goes here')
    load_widget()

Tratar de cumplir dos roles a la vez impone algunas limitaciones a la técnica. Los gestores de contexto normalmente tienen la flexibilidad de retornar un argumento utilizable por una instrucción with, pero no hay paralelo para los decoradores de funciones.

En el ejemplo anterior, no hay una forma limpia para que el gestor de contexto track_entry_and_exit retorne una instancia de logging para usar en el cuerpo de las declaraciones adjuntas.

(Contribución de Michael Foord en bpo-9110 [https://bugs.python.org/issue?@action=redirect&bpo=9110].)

decimal and fractions

Mark Dickinson diseñó un esquema elegante y eficiente para asegurar que diferentes tipos de datos numéricos tendrán el mismo valor hash siempre que sus valores reales sean iguales (bpo-8188 [https://bugs.python.org/issue?@action=redirect&bpo=8188]):

assert hash(Fraction(3, 2)) == hash(1.5) == \
       hash(Decimal("1.5")) == hash(complex(1.5, 0))

Algunos de los detalles de hash se exponen a través de un nuevo atributo, sys.hash_info, que describe el ancho de bits del valor hash, el módulo principal, los valores hash para infinity y nan, y el multiplicador utilizado para la parte imaginaria de un número:

>>> sys.hash_info
sys.hash_info(width=64, modulus=2305843009213693951, inf=314159, nan=0, imag=1000003)

Se ha atenuado una decisión temprana para limitar la interoperabilidad de varios tipos numéricos. Todavía no se admite (y es desaconsejable) tener una mezcla implícita en expresiones aritméticas como Decimal('1.1') + float('1.1') porque este último pierde información en el proceso de construcción del float binario. Sin embargo, dado que el valor de punto flotante existente se puede convertir sin pérdidas a una representación decimal o racional, tiene sentido agregarlos al constructor y admitir comparaciones de tipo mixto.

El constructor decimal.Decimal ahora acepta objetos float directamente, por lo que ya no es necesario utilizar el método from_float() (bpo-8257 [https://bugs.python.org/issue?@action=redirect&bpo=8257]).

Las comparaciones de tipos mixto ahora son totalmente compatibles, de modo que los objetos Decimal se pueden comparar directamente con float y fractions.Fraction (bpo-2531 [https://bugs.python.org/issue?@action=redirect&bpo=2531] y bpo-8188 [https://bugs.python.org/issue?@action=redirect&bpo=8188]).

Cambios similares se hicieron en fractions.Fraction por lo que los métodos from_float() y from_decimal() ya no son necesarios (bpo-8294 [https://bugs.python.org/issue?@action=redirect&bpo=8294]):

>>> from decimal import Decimal
>>> from fractions import Fraction
>>> Decimal(1.1)
Decimal('1.100000000000000088817841970012523233890533447265625')
>>> Fraction(1.1)
Fraction(2476979795053773, 2251799813685248)

Otro cambio útil para el módulo decimal es que el atributo Context.clamp ahora es público. Esto es útil para crear contextos que se correspondan con los formatos de intercambio decimal especificados en IEEE 754 (ver :8540).

(Contribución de Mark Dickinson y Raymond Hettinger.)

ftp

La clase ftplib.FTP ahora admite el protocolo de gestor de contexto para consumir incondicionalmente las excepciones socket.error y cerrar la conexión FTP cuando haya terminado:

>>> from ftplib import FTP
>>> with FTP("ftp1.at.proftpd.org") as ftp:
        ftp.login()
        ftp.dir()

'230 Anonymous login ok, restrictions apply.'
dr-xr-xr-x   9 ftp      ftp           154 May  6 10:43 .
dr-xr-xr-x   9 ftp      ftp           154 May  6 10:43 ..
dr-xr-xr-x   5 ftp      ftp          4096 May  6 10:43 CentOS
dr-xr-xr-x   3 ftp      ftp            18 Jul 10  2008 Fedora

Otros objetos similares a archivos como mmap.mmap y fileinput.input() también adquirieron gestores de contexto de cierre automático:

with fileinput.input(files=('log1.txt', 'log2.txt')) as f:
    for line in f:
        process(line)

(Contribución de Tarek Ziadé y Giampaolo Rodolà en bpo-4972 [https://bugs.python.org/issue?@action=redirect&bpo=4972], y por Georg Brandl en bpo-8046 [https://bugs.python.org/issue?@action=redirect&bpo=8046] y bpo-1286 [https://bugs.python.org/issue?@action=redirect&bpo=1286].)

La clase FTP_TLS ahora acepta un parámetro context, que es un objeto ssl.SSLContext que permite agrupar opciones de configuración SSL, certificados y claves privadas en una sola (y potencialmente de larga duración) estructura.

(Contribución de Giampaolo Rodolà; bpo-8806 [https://bugs.python.org/issue?@action=redirect&bpo=8806].)

popen

Las funciones os.popen() y subprocess.Popen() ahora admiten declaraciones with para el cierre automático de los descriptores de archivo.

(Contribución de Antoine Pitrou y Brian Curtin en bpo-7461 [https://bugs.python.org/issue?@action=redirect&bpo=7461] y bpo-10554 [https://bugs.python.org/issue?@action=redirect&bpo=10554].)

select

El módulo select ahora presenta un nuevo atributo constante, PIPE_BUF, que da el número mínimo de bytes que están garantizados para no bloquearse cuando select.select() dice que una tubería está lista para escribir.

>>> import select
>>> select.PIPE_BUF
512

(Disponible en sistemas Unix. Parche de Sébastien Sablé en bpo-9862 [https://bugs.python.org/issue?@action=redirect&bpo=9862])

gzip y zipfile

gzip.GzipFile ahora implementa io.BufferedIOBase clase base abstracta (excepto para truncate()). También tiene un método peek() y admite objetos de archivo con rellenos de ceros y que no se pueden buscar.

El módulo gzip también obtiene las funciones compress() y decompress() para facilitar la compresión y descompresión en memoria. Tenga en cuenta que el texto debe codificarse como bytes antes de comprimir y descomprimir:

>>> import gzip
>>> s = 'Three shall be the number thou shalt count, '
>>> s += 'and the number of the counting shall be three'
>>> b = s.encode()                        # convert to utf-8
>>> len(b)
89
>>> c = gzip.compress(b)
>>> len(c)
77
>>> gzip.decompress(c).decode()[:42]      # decompress and convert to text
'Three shall be the number thou shalt count'

(Contribución de Anand B. Pillai en bpo-3488 [https://bugs.python.org/issue?@action=redirect&bpo=3488]; y de Antoine Pitrou, Nir Aides y Brian Curtin en bpo-9962 [https://bugs.python.org/issue?@action=redirect&bpo=9962], bpo-1675951 [https://bugs.python.org/issue?@action=redirect&bpo=1675951], bpo-7471 [https://bugs.python.org/issue?@action=redirect&bpo=7471] y bpo-2846 [https://bugs.python.org/issue?@action=redirect&bpo=2846].)

Además, la clase zipfile.ZipExtFile se modificó internamente para representar archivos almacenados dentro de un archivo. La nueva implementación es significativamente más rápida y se puede incluir en un objeto io.BufferedReader para obtener más aceleraciones. También resuelve un problema en el que las llamadas intercaladas a read y readline daban resultados incorrectos.

(Parche enviado por Nir Aides en bpo-7610 [https://bugs.python.org/issue?@action=redirect&bpo=7610].)

tarfile

La clase TarFile ahora se puede usar como gestor de contexto. Además, su método add() tiene una nueva opción, filter, que controla qué archivos se agregan y permite editar los metadatos del archivo.

La nueva opción filter reemplaza el parámetro anterior y menos flexible exclude que ahora está deprecado. Si se especifica, el parámetro opcional filter debe ser un keyword argument. La función filter proporcionada por el usuario acepta un objeto TarInfo y retorna un objeto TarInfo actualizado, o si desea que el archivo sea excluido, la función puede retornar None:

>>> import tarfile, glob

>>> def myfilter(tarinfo):
...     if tarinfo.isfile():             # only save real files
...         tarinfo.uname = 'monty'      # redact the user name
...         return tarinfo

>>> with tarfile.open(name='myarchive.tar.gz', mode='w:gz') as tf:
...     for filename in glob.glob('*.txt'):
...         tf.add(filename, filter=myfilter)
...     tf.list()
-rw-r--r-- monty/501        902 2011-01-26 17:59:11 annotations.txt
-rw-r--r-- monty/501        123 2011-01-26 17:59:11 general_questions.txt
-rw-r--r-- monty/501       3514 2011-01-26 17:59:11 prion.txt
-rw-r--r-- monty/501        124 2011-01-26 17:59:11 py_todo.txt
-rw-r--r-- monty/501       1399 2011-01-26 17:59:11 semaphore_notes.txt

(Propuesto por Tarek Ziadé e implementado por Lars Gustäbel en bpo-6856 [https://bugs.python.org/issue?@action=redirect&bpo=6856].)

hashlib

El módulo hashlib tiene dos nuevos atributos constantes que enumeran los algoritmos hash garantizados para estar presentes en todas las implementaciones y los disponibles en la implementación actual:

>>> import hashlib

>>> hashlib.algorithms_guaranteed
{'sha1', 'sha224', 'sha384', 'sha256', 'sha512', 'md5'}

>>> hashlib.algorithms_available
{'md2', 'SHA256', 'SHA512', 'dsaWithSHA', 'mdc2', 'SHA224', 'MD4', 'sha256',
'sha512', 'ripemd160', 'SHA1', 'MDC2', 'SHA', 'SHA384', 'MD2',
'ecdsa-with-SHA1','md4', 'md5', 'sha1', 'DSA-SHA', 'sha224',
'dsaEncryption', 'DSA', 'RIPEMD160', 'sha', 'MD5', 'sha384'}

(Sugerido por Carl Chenet en bpo-7418 [https://bugs.python.org/issue?@action=redirect&bpo=7418].)

ast

El módulo ast tiene una maravillosa herramienta de propósito general para evaluar cadenas de expresión de forma segura utilizando la sintaxis literal de Python. La función ast.literal_eval() sirve como una alternativa segura a la función incorporada eval() la cual se abusa fácilmente. Python 3.2 agrega bytes y set literales a la lista de tipos admitidos: cadenas de caracteres, bytes, números, tuplas, listas, diccionarios, sets, valores booleanos y None.

>>> from ast import literal_eval

>>> request = "{'req': 3, 'func': 'pow', 'args': (2, 0.5)}"
>>> literal_eval(request)
{'args': (2, 0.5), 'req': 3, 'func': 'pow'}

>>> request = "os.system('do something harmful')"
>>> literal_eval(request)
Traceback (most recent call last):
  ...
ValueError: malformed node or string: <_ast.Call object at 0x101739a10>

(Implementado por Benjamin Peterson y Georg Brandl.)

os

Los diferentes sistemas operativos utilizan varias codificaciones para los nombres de archivo y las variables de entorno. El módulo os proporciona dos funciones nuevas, fsencode() y fsdecode(), para codificar y decodificar nombres de archivo:

>>> import os
>>> filename = 'Sehenswürdigkeiten'
>>> os.fsencode(filename)
b'Sehensw\xc3\xbcrdigkeiten'

Algunos sistemas operativos permiten el acceso directo a bytes codificados en el entorno. Si es así, la constante os.supports_bytes_environ será verdadera.

Para acceder directamente a las variables de entorno codificadas (si está disponible), utilice la nueva función os.getenvb() o utilice os.environb, que es una versión en bytes de os.environ.

(Contribución de Victor Stinner.)

shutil

La función shutil.copytree() tiene dos nuevas opciones:

ignore_dangling_symlinks: cuando symlinks=False para que la función copie un archivo apuntado por un enlace simbólico, no el enlace simbólico en sí. Esta opción silenciará el error lanzado si el archivo no existe.

copy_function: es un invocable que se utilizará para copiar archivos. shutil.copy2() se usa por defecto.

(Contribución de Tarek Ziadé.)

Además, el módulo shutil ahora admite operaciones de archivado para archivos zip, archivos tar sin comprimir, archivos tar comprimidos con gzip y archivos tar bzip. Y hay funciones para registrar formatos de archivado de archivo adicionales (como archivos tar comprimidos xz o formatos personalizados).

Las funciones principales son make_archive() y unpack_archive(). Por defecto, ambas operan en el directorio actual (que puede ser configurado por os.chdir()) y en cualquier subdirectorio. El nombre del archivo de almacenamiento debe especificarse con una ruta completa. El paso de archivado no es destructivo (los archivos originales no se modifican).

>>> import shutil, pprint

>>> os.chdir('mydata')  # change to the source directory
>>> f = shutil.make_archive('/var/backup/mydata',
...                         'zip')      # archive the current directory
>>> f                                   # show the name of archive
'/var/backup/mydata.zip'
>>> os.chdir('tmp')                     # change to an unpacking
>>> shutil.unpack_archive('/var/backup/mydata.zip')  # recover the data

>>> pprint.pprint(shutil.get_archive_formats())  # display known formats
[('bztar', "bzip2'ed tar-file"),
 ('gztar', "gzip'ed tar-file"),
 ('tar', 'uncompressed tar file'),
 ('zip', 'ZIP file')]

>>> shutil.register_archive_format(     # register a new archive format
...     name='xz',
...     function=xz.compress,           # callable archiving function
...     extra_args=[('level', 8)],      # arguments to the function
...     description='xz compression'
... )

(Contribución de Tarek Ziadé.)

sqlite3

El módulo sqlite3 se actualizó a la versión 2.6.0 de pysqlite. Tiene dos nuevas capacidades.

El atributo sqlite3.Connection.in_transit es verdadero si hay una transacción activa para cambios no confirmados.

Los métodos sqlite3.Connection.enable_load_extension() y sqlite3.Connection.load_extension() le permiten cargar extensiones SQLite desde archivos «.so». Una extensión conocida es la extensión de búsqueda de texto completo distribuida con SQLite.

(Contribución de R. David Murray y Shashwat Anand; bpo-8845 [https://bugs.python.org/issue?@action=redirect&bpo=8845].)

html

Se introdujo un nuevo módulo html con una sola función, escape(), que se usa para escapar caracteres reservados del marcado HTML:

>>> import html
>>> html.escape('x > 2 && x < 7')
'x &gt; 2 &amp;&amp; x &lt; 7'

socket

El módulo socket tiene dos nuevas mejoras.

Los objetos de socket ahora tienen un método detach() que pone el socket en estado cerrado sin cerrar realmente el descriptor de archivo subyacente. Este último se puede reutilizar para otros fines. (Agregado por Antoine Pitrou; bpo-8524 [https://bugs.python.org/issue?@action=redirect&bpo=8524].)

socket.create_connection() ahora admite el protocolo de administración de contexto para consumir incondicionalmente las excepciones socket.error y cerrar el socket cuando haya terminado. (Contribución de Giampaolo Rodolà; bpo-9794 [https://bugs.python.org/issue?@action=redirect&bpo=9794].)

ssl

El módulo ssl agregó una serie de características para satisfacer los requisitos comunes para conexiones a Internet seguras (encriptadas, autenticadas):

Una nueva clase, SSLContext, sirve como contenedor para datos SSL persistentes, como configuraciones de protocolo, certificados, claves privadas y varias opciones más. Incluye un wrap_socket() para crear un socket SSL a partir de un contexto SSL.

Una nueva función, ssl.match_hostname(), admite la verificación de identidad del servidor para protocolos de nivel superior mediante la implementación de las reglas de HTTPS (de RFC 2818 [https://tools.ietf.org/html/rfc2818.html]) que también son adecuadas para otros protocolos.

La función constructora ssl.wrap_socket() ahora toma un argumento ciphers. La cadena ciphers enumera los algoritmos de cifrado permitidos utilizando el formato descrito en la documentación de OpenSSL [https://www.openssl.org/docs/manmaster/man1/ciphers.html#CIPHER-LIST-FORMAT].

Cuando se vincula con versiones recientes de OpenSSL, el módulo ssl ahora admite la extensión de Server Name Indication (SNI, en español: Indicador del nombre del servidor) para el protocolo TLS, lo que permite que varios» hosts virtuales «utilicen diferentes certificados en un solo puerto IP. Esta extensión solo es compatible en modo cliente y se activa pasando el argumento server_hostname a ssl.SSLContext.wrap_socket().

Se han agregado varias opciones al módulo ssl, como OP_NO_SSLv2 que deshabilita el protocolo SSLv2 inseguro y obsoleto.

La extensión ahora carga todos los algoritmos de resumen y cifrados OpenSSL. Si algunos certificados SSL no se pueden verificar, se notifican como un error de «algoritmo desconocido».

La versión de OpenSSL que se está utilizando ahora es accesible usando los atributos del módulo ssl.OPENSSL_VERSION (una cadena de caracteres), ssl.OPENSSL_VERSION_INFO (una tupla de 5), y ssl.OPENSSL_VERSION_NUMBER (un número entero).

(Contribución de Antoine Pitrou en bpo-8850 [https://bugs.python.org/issue?@action=redirect&bpo=8850], bpo-1589 [https://bugs.python.org/issue?@action=redirect&bpo=1589], bpo-8322 [https://bugs.python.org/issue?@action=redirect&bpo=8322], bpo-5639 [https://bugs.python.org/issue?@action=redirect&bpo=5639], bpo-4870 [https://bugs.python.org/issue?@action=redirect&bpo=4870], bpo-8484 [https://bugs.python.org/issue?@action=redirect&bpo=8484], y bpo-8321 [https://bugs.python.org/issue?@action=redirect&bpo=8321].)

nntp

El módulo nntplib tiene una implementación renovada con mejoras en la semántica de bytes y texto, así como APIs más prácticas. Estas mejoras rompen la compatibilidad con la versión nntplib en Python 3.1, que en sí misma era parcialmente disfuncional.

También se ha agregado soporte para conexiones seguras a través de TLS implícito (usando nntplib.NNTP_SSL) y explícito (usando nntplib.NNTP.starttls()).

(Contribución de Antoine Pitrou en bpo-9360 [https://bugs.python.org/issue?@action=redirect&bpo=9360] y Andrew Vant en bpo-1926 [https://bugs.python.org/issue?@action=redirect&bpo=1926].)

certificados

http.client.HTTPSConnection, urllib.request.HTTPSHandler y urllib.request.urlopen() ahora toman argumentos opcionales para permitir la comprobación del certificado del servidor con un conjunto de Autoridades de Certificación recomendado en usos públicos de HTTPS.

(Agregado por Antoine Pitrou, bpo-9003 [https://bugs.python.org/issue?@action=redirect&bpo=9003].)

imaplib

Se ha agregado soporte para TLS explícito en conexiones IMAP4 estándar a través del nuevo método imaplib.IMAP4.starttls.

(Contribución de Lorenzo M. Catucci y Antoine Pitrou, bpo-4471 [https://bugs.python.org/issue?@action=redirect&bpo=4471].)

http.client

Hubo una serie de pequeñas mejoras de API en el módulo http.client. Las respuestas simples HTTP 0.9 de estilo antiguo ya no son compatibles y el parámetro strict está obsoleto en todas las clases.

Las clases HTTPConnection y HTTPSConnection ahora tienen un parámetro source_address para una tupla (host, port) que indica desde dónde se realiza la conexión HTTP.

Se agregó soporte para verificación de certificados y hosts virtuales HTTPS a HTTPSConnection.

El método request() en los objetos de conexión permitía un argumento body opcional para que un file object pudiera usarse para proporcionar el contenido de la solicitud. Convenientemente, el argumento body ahora también acepta un objeto iterable siempre que incluya un encabezado explícito Content-Length. Esta interfaz ampliada es mucho más flexible que antes.

Para establecer una conexión HTTPS a través de un servidor proxy, existe un nuevo método set_tunnel() que establece el host y el puerto para el túnel HTTP Connect.

Para que coincida con el comportamiento de http.server, la biblioteca de cliente HTTP ahora también codifica encabezados con codificación ISO-8859-1 (Latin-1). Ya lo estaba haciendo para los encabezados entrantes, por lo que ahora el comportamiento es coherente para el tráfico entrante y saliente. (Véase el trabajo de Armin Ronacher en bpo-10980 [https://bugs.python.org/issue?@action=redirect&bpo=10980])

unittest

El módulo unittest tiene una serie de mejoras con soporte para descubrimiento de pruebas para paquetes, una experimentación más sencilla en el indicador interactivo, nuevos métodos de casos de prueba, mensajes de diagnóstico mejorados para fallas en las pruebas y mejores nombres de métodos.

La llamada de línea de comandos python -m unittest ahora puede aceptar rutas de archivo en lugar de nombres de módulo para ejecutar pruebas específicas (bpo-10620 [https://bugs.python.org/issue?@action=redirect&bpo=10620]). El nuevo descubrimiento de pruebas puede encontrar pruebas dentro de paquetes, ubicando cualquier prueba importable desde el directorio de nivel superior. El directorio de nivel superior se puede especificar con la opción -t, un patrón para hacer coincidir archivos con -p y un directorio para iniciar el descubrimiento con -s:

$ python -m unittest discover -s my_proj_dir -p _test.py

(Contribución de Michael Foord.)

La experimentación en el indicador interactivo ahora es más fácil porque la clase unittest.case.TestCase ahora se puede instanciar sin argumentos:

>>> from unittest import TestCase
>>> TestCase().assertEqual(pow(2, 3), 8)

(Contribución de Michael Foord.)

El módulo unittest tiene dos métodos nuevos, assertWarns() y assertWarnsRegex() para verificar que un tipo de advertencia dado es activado por el código bajo prueba:

with self.assertWarns(DeprecationWarning):
    legacy_function('XYZ')

(Contribución de Antoine Pitrou, bpo-9754 [https://bugs.python.org/issue?@action=redirect&bpo=9754].)

Otro método nuevo, assertCountEqual() se usa para comparar dos iterables para determinar si sus conteos de elementos son iguales (si los mismos elementos están presentes con el mismo número de ocurrencias independientemente del orden):

def test_anagram(self):
    self.assertCountEqual('algorithm', 'logarithm')

(Contribución por Raymond Hettinger.)

Una característica principal del módulo unittest es un esfuerzo por producir diagnósticos significativos cuando falla una prueba. Cuando es posible, la falla se registra junto con una diferencia de la salida. Esto es especialmente útil para analizar archivos de registro de ejecuciones de prueba fallidas. Sin embargo, dado que las diferencias en ocasiones pueden ser voluminosas, hay un nuevo atributo maxDiff que establece la longitud máxima de las diferencias mostradas.

Además, los nombres de los métodos en el módulo se han sometido a una serie de limpiezas.

Por ejemplo, assertRegex() es el nuevo nombre de assertRegexpMatches() que fue mal nombrado porque la prueba usa re.search(), no re.match(). Otros métodos que usan expresiones regulares ahora se nombran usando la forma corta «Regex» en lugar de «Regexp» – esto coincide con los nombres usados en otras implementaciones de unittest, coincide con el nombre antiguo de Python para el módulo re, y utiliza inequívocamente camel-case.

(Contribución de Raymond Hettinger e implementado por Ezio Melotti.)

Para mejorar la coherencia, algunos alias de métodos antiguos se están deprecando en favor de los nombres preferidos:

Old Name

Preferred Name

assert_()

assertTrue()

assertEquals()

assertEqual()

assertNotEquals()

assertNotEqual()

assertAlmostEquals()

assertAlmostEqual()

assertNotAlmostEquals()

assertNotAlmostEqual()

Asimismo, se espera que los métodos TestCase.fail* obsoletos en Python 3.1 se eliminen en Python 3.3. También vea la sección Alias obsoletos en la documentación unittest.

(Contribución de Ezio Melotti; bpo-9424 [https://bugs.python.org/issue?@action=redirect&bpo=9424].)

El método assertDictContainsSubset() quedó obsoleto porque porque estaba mal implementado con los argumentos en el orden incorrecto. Esto creó ilusiones ópticas difíciles de depurar en las que pruebas como TestCase().assertDictContainsSubset({'a':1, 'b':2}, {'a':1}) fallarían.

(Contribución por Raymond Hettinger.)

random

Los métodos enteros en el módulo random ahora hacen un mejor trabajo al producir distribuciones uniformes. Anteriormente, calculaban las selecciones con int(n*random()) que tenía un ligero sesgo siempre que n no era una potencia de dos. Ahora, se realizan selecciones múltiples desde un rango hasta la siguiente potencia de dos y una selección se mantiene solo cuando cae dentro del rango 0 <= x < n. Las funciones y métodos afectados son randrange(), randint(), choice(), shuffle() y sample().

(Contribución de Raymond Hettinger; bpo-9025 [https://bugs.python.org/issue?@action=redirect&bpo=9025].)

poplib

POP3_SSL la clase ahora acepta un parámetro context, que es un objeto ssl.SSLContext que permite agrupar opciones de configuración SSL, certificados y claves privadas en una única estructura (potencialmente de larga duración) .

(Contribución de Giampaolo Rodolà; bpo-8807 [https://bugs.python.org/issue?@action=redirect&bpo=8807].)

asyncore

asyncore.dispatcher ahora proporciona un handle_accepted() que devuelve un par (sock, addr) que se llama cuando se ha establecido una conexión con un nuevo extremo remoto . Se supone que debe usarse como reemplazo del viejo handle_accept() y evita que el usuario llame a accept() directamente.

(Contribución de Giampaolo Rodolà; bpo-6706 [https://bugs.python.org/issue?@action=redirect&bpo=6706].)

tempfile

El módulo tempfile tiene un nuevo gestor de contexto, TemporaryDirectory que proporciona una limpieza determinista fácil de directorios temporales

with tempfile.TemporaryDirectory() as tmpdirname:
    print('created temporary dir:', tmpdirname)

(Contribución de Neil Schemenauer y Nick Coghlan; bpo-5178 [https://bugs.python.org/issue?@action=redirect&bpo=5178].)

inspect

El módulo inspect tiene una nueva función getgeneratorstate() para identificar fácilmente el estado actual de un generador iterador:

>>> from inspect import getgeneratorstate
>>> def gen():
...     yield 'demo'
>>> g = gen()
>>> getgeneratorstate(g)
'GEN_CREATED'
>>> next(g)
'demo'
>>> getgeneratorstate(g)
'GEN_SUSPENDED'
>>> next(g, None)
>>> getgeneratorstate(g)
'GEN_CLOSED'

(Contribución de Rodolpho Eckhardt y Nick Coghlan, bpo-10220 [https://bugs.python.org/issue?@action=redirect&bpo=10220].)

Para admitir búsquedas sin la posibilidad de activar un atributo dinámico, el módulo inspect tiene una nueva función, getattr_static(). A diferencia de hasattr(), esta es una verdadera búsqueda de solo lectura, garantizada que no cambiará de estado mientras está buscando:

>>> class A:
...     @property
...     def f(self):
...         print('Running')
...         return 10
...
>>> a = A()
>>> getattr(a, 'f')
Running
10
>>> inspect.getattr_static(a, 'f')
<property object at 0x1022bd788>

(Contribución de Michael Foord.)

pydoc

El módulo pydoc ahora proporciona una interfaz de servidor web muy mejorada, así como una nueva opción de línea de comandos -b para abrir automáticamente una ventana del navegador para mostrar ese servidor:

$ pydoc3.2 -b

(Contribución de Ron Adam; bpo-2001 [https://bugs.python.org/issue?@action=redirect&bpo=2001].)

dis

El módulo dis obtuvo dos nuevas funciones para inspeccionar código, code_info() y show_code(). Ambas proporcionan información detallada del objeto de código para la función, método, cadena de código fuente o objeto de código suministrados. El primero retorna una cadena de caracteres y el segundo la imprime:

>>> import dis, random
>>> dis.show_code(random.choice)
Name:              choice
Filename:          /Library/Frameworks/Python.framework/Versions/3.2/lib/python3.2/random.py
Argument count:    2
Kw-only arguments: 0
Number of locals:  3
Stack size:        11
Flags:             OPTIMIZED, NEWLOCALS, NOFREE
Constants:
   0: 'Choose a random element from a non-empty sequence.'
   1: 'Cannot choose from an empty sequence'
Names:
   0: _randbelow
   1: len
   2: ValueError
   3: IndexError
Variable names:
   0: self
   1: seq
   2: i

Además, la función dis() ahora acepta argumentos de cadena para que el modismo común dis(compile(s, '', 'eval')) se pueda abreviar a dis(s):

>>> dis('3*x+1 if x%2==1 else x//2')
  1           0 LOAD_NAME                0 (x)
              3 LOAD_CONST               0 (2)
              6 BINARY_MODULO
              7 LOAD_CONST               1 (1)
             10 COMPARE_OP               2 (==)
             13 POP_JUMP_IF_FALSE       28
             16 LOAD_CONST               2 (3)
             19 LOAD_NAME                0 (x)
             22 BINARY_MULTIPLY
             23 LOAD_CONST               1 (1)
             26 BINARY_ADD
             27 RETURN_VALUE
        >>   28 LOAD_NAME                0 (x)
             31 LOAD_CONST               0 (2)
             34 BINARY_FLOOR_DIVIDE
             35 RETURN_VALUE

En conjunto, estas mejoras facilitan explorar cómo se implementa CPython y ver por sí mismo qué hace la sintaxis del lenguaje bajo el capó.

(Contribución de Nick Coghlan en bpo-9147 [https://bugs.python.org/issue?@action=redirect&bpo=9147].)

dbm

Todos los módulos de base de datos ahora admiten los métodos get() y setdefault().

(Sugerido por Ray Allen en bpo-9523 [https://bugs.python.org/issue?@action=redirect&bpo=9523].)

ctypes

Un nuevo tipo, ctypes.c_ssize_t representa el tipo de datos C ssize_t.

site

El módulo site tiene tres nuevas funciones útiles para informar sobre los detalles de una determinada instalación de Python.

getsitepackages() enumera todos los directorios de paquetes de sitios globales.

getuserbase() informa sobre el directorio base del usuario donde se pueden almacenar los datos.

getusersitepackages() revela la ruta del directorio de paquetes de sitio específico del usuario.

>>> import site
>>> site.getsitepackages()
['/Library/Frameworks/Python.framework/Versions/3.2/lib/python3.2/site-packages',
 '/Library/Frameworks/Python.framework/Versions/3.2/lib/site-python',
 '/Library/Python/3.2/site-packages']
>>> site.getuserbase()
'/Users/raymondhettinger/Library/Python/3.2'
>>> site.getusersitepackages()
'/Users/raymondhettinger/Library/Python/3.2/lib/python/site-packages'

Convenientemente, se puede acceder a algunas de las funciones del sitio directamente desde la línea de comandos:

$ python -m site --user-base
/Users/raymondhettinger/.local
$ python -m site --user-site
/Users/raymondhettinger/.local/lib/python3.2/site-packages

(Contribución de Tarek Ziadé en bpo-6693 [https://bugs.python.org/issue?@action=redirect&bpo=6693].)

sysconfig

El nuevo módulo sysconfig hace que sea sencillo descubrir rutas de instalación y variables de configuración que varían entre plataformas e instalaciones.

El módulo ofrece acceso a funciones de acceso simple para información de plataforma y versión:

get_platform() retornando valores como linux-i586 o macosx-10.6-ppc.

get_python_version() retorna una cadena de versión de Python como» 3.2 «.

También proporciona acceso a las rutas y variables correspondientes a uno de los siete esquemas con nombre utilizados por distutils. Estos incluyen posix_prefix, posix_home, posix_user, nt, nt_user *, *os2, os2_home:

get_paths() crea un diccionario que contiene las rutas de instalación para el esquema de instalación actual.

get_config_vars() retorna un diccionario de variables específicas de la plataforma.

También hay una conveniente interfaz de línea de comandos:

C:\Python32>python -m sysconfig
Platform: "win32"
Python version: "3.2"
Current installation scheme: "nt"

Paths:
        data = "C:\Python32"
        include = "C:\Python32\Include"
        platinclude = "C:\Python32\Include"
        platlib = "C:\Python32\Lib\site-packages"
        platstdlib = "C:\Python32\Lib"
        purelib = "C:\Python32\Lib\site-packages"
        scripts = "C:\Python32\Scripts"
        stdlib = "C:\Python32\Lib"

Variables:
        BINDIR = "C:\Python32"
        BINLIBDEST = "C:\Python32\Lib"
        EXE = ".exe"
        INCLUDEPY = "C:\Python32\Include"
        LIBDEST = "C:\Python32\Lib"
        SO = ".pyd"
        VERSION = "32"
        abiflags = ""
        base = "C:\Python32"
        exec_prefix = "C:\Python32"
        platbase = "C:\Python32"
        prefix = "C:\Python32"
        projectbase = "C:\Python32"
        py_version = "3.2"
        py_version_nodot = "32"
        py_version_short = "3.2"
        srcdir = "C:\Python32"
        userbase = "C:\Documents and Settings\Raymond\Application Data\Python"

(Sacado de Distutils por Tarek Ziadé.)

pdb

El módulo depurador pdb obtuvo una serie de mejoras de usabilidad:

pdb.py ahora tiene una opción -c que ejecuta comandos como se indica en un archivo de script .pdbrc.

Un archivo de secuencia de comandos .pdbrc puede contener comandos continue y next que continúan depurando.

El constructor de la clase Pdb ahora acepta un argumento nosigint.

Nuevos comandos: l(list), ll(long list) y source para enumerar el código fuente.

Nuevos comandos: display y undisplay para mostrar u ocultar el valor de una expresión si ha cambiado.

Nuevo comando: interact para iniciar un intérprete interactivo que contiene los nombres globales y locales que se encuentran en el alcance actual.

Los puntos de interrupción se pueden borrar por número de punto de interrupción.

(Contribución de Georg Brandl, Antonio Cuni e Ilya Sandler.)

configparser

El módulo configparser se modificó para mejorar la usabilidad y la previsibilidad del analizador predeterminado y su sintaxis INI compatible. La antigua clase ConfigParser fue eliminada en favor de SafeConfigParser que a su vez ha sido renombrada a ConfigParser. La compatibilidad con comentarios en línea ahora está desactivada de forma predeterminada y no se permiten duplicados de secciones u opciones en una única fuente de configuración.

Los analizadores de configuración obtuvieron una nueva API basada en el protocolo de mapeo:

>>> parser = ConfigParser()
>>> parser.read_string("""
... [DEFAULT]
... location = upper left
... visible = yes
... editable = no
... color = blue
...
... [main]
... title = Main Menu
... color = green
...
... [options]
... title = Options
... """)
>>> parser['main']['color']
'green'
>>> parser['main']['editable']
'no'
>>> section = parser['options']
>>> section['title']
'Options'
>>> section['title'] = 'Options (editable: %(editable)s)'
>>> section['title']
'Options (editable: no)'

La nueva API se implementa sobre la API clásica, por lo que las subclases de analizadores personalizados deberían poder usarla sin modificaciones.

La estructura de archivos INI aceptada por los analizadores de configuración ahora se puede personalizar. Los usuarios pueden especificar opciones alternativas/delimitadores de valores y prefijos de comentarios, cambiar el nombre de la sección DEFAULT o cambiar la sintaxis de interpolación.

Hay soporte para la interpolación conectable que incluye un controlador de interpolación adicional ExtendedInterpolation:

>>> parser = ConfigParser(interpolation=ExtendedInterpolation())
>>> parser.read_dict({'buildout': {'directory': '/home/ambv/zope9'},
...                   'custom': {'prefix': '/usr/local'}})
>>> parser.read_string("""
... [buildout]
... parts =
...   zope9
...   instance
... find-links =
...   ${buildout:directory}/downloads/dist
...
... [zope9]
... recipe = plone.recipe.zope9install
... location = /opt/zope
...
... [instance]
... recipe = plone.recipe.zope9instance
... zope9-location = ${zope9:location}
... zope-conf = ${custom:prefix}/etc/zope.conf
... """)
>>> parser['buildout']['find-links']
'\n/home/ambv/zope9/downloads/dist'
>>> parser['instance']['zope-conf']
'/usr/local/etc/zope.conf'
>>> instance = parser['instance']
>>> instance['zope-conf']
'/usr/local/etc/zope.conf'
>>> instance['zope9-location']
'/opt/zope'

También se introdujeron una serie de características más pequeñas, como soporte para especificar codificación en operaciones de lectura, especificar valores de respaldo para funciones de obtención o leer directamente desde diccionarios y cadenas.

(Todos los cambios aportados por Łukasz Langa.)

urllib.parse

Se realizaron varias mejoras de usabilidad para el módulo urllib.parse.

La función urlparse() ahora admite direcciones IPv6 [https://en.wikipedia.org/wiki/IPv6] como se describe en RFC 2732 [https://tools.ietf.org/html/rfc2732.html]:

>>> import urllib.parse
>>> urllib.parse.urlparse('http://[dead:beef:cafe:5417:affe:8FA3:deaf:feed]/foo/')
ParseResult(scheme='http',
            netloc='[dead:beef:cafe:5417:affe:8FA3:deaf:feed]',
            path='/foo/',
            params='',
            query='',
            fragment='')

La función urldefrag() ahora devuelve un named tuple:

>>> r = urllib.parse.urldefrag('http://python.org/about/#target')
>>> r
DefragResult(url='http://python.org/about/', fragment='target')
>>> r[0]
'http://python.org/about/'
>>> r.fragment
'target'

Y, la función urlencode() ahora es mucho más flexible, aceptando un tipo de cadena o bytes para el argumento query. Si es una cadena, entonces los parámetros safe, encoding y error se envían a quote_plus() para codificar:

>>> urllib.parse.urlencode([
...      ('type', 'telenovela'),
...      ('name', '¿Dónde Está Elisa?')],
...      encoding='latin-1')
'type=telenovela&name=%BFD%F3nde+Est%E1+Elisa%3F'

Como se detalla en Análisis de bytes codificados ASCII, todas las funciones urllib.parse ahora aceptan cadenas de bytes codificadas en ASCII como entrada, siempre que no estén mezcladas con cadenas normales. Si se proporcionan cadenas de bytes codificadas en ASCII como parámetros, los tipos de retorno también serán cadenas de bytes codificadas en ASCII:

>>> urllib.parse.urlparse(b'http://www.python.org:80/about/')
ParseResultBytes(scheme=b'http', netloc=b'www.python.org:80',
                 path=b'/about/', params=b'', query=b'', fragment=b'')

(Trabajo de Nick Coghlan, Dan Mahn y Senthil Kumaran en bpo-2987 [https://bugs.python.org/issue?@action=redirect&bpo=2987], bpo-5468 [https://bugs.python.org/issue?@action=redirect&bpo=5468], y bpo-9873 [https://bugs.python.org/issue?@action=redirect&bpo=9873].)

mailbox

Gracias a un esfuerzo concertado de R. David Murray, el módulo mailbox se ha corregido para Python 3.2. El desafío era que el buzón había sido diseñado originalmente con una interfaz de texto, pero los mensajes de correo electrónico se representan mejor con bytes porque varias partes de un mensaje pueden tener diferentes codificaciones.

La solución aprovechó el soporte binario de los paquete email para analizar mensajes de correo electrónico arbitrarios. Además, la solución requirió una serie de cambios en la API.

Como era de esperar, el método add() para los objetos mailbox.Mailbox ahora acepta entrada binaria.

StringIO y la entrada del archivo de texto están en desuso. Además, la entrada de cadenas fallará antes si se utilizan caracteres que no sean ASCII. Anteriormente, fallaba cuando el correo electrónico se procesaba en un paso posterior.

También hay soporte para salida binaria. El método get_file() ahora devuelve un archivo en modo binario (donde solía configurar incorrectamente el archivo en modo texto). También hay un nuevo método get_bytes() que devuelve una representación bytes de un mensaje correspondiente a una key dada.

Todavía es posible obtener una salida no binaria usando el método de la API anterior get_string(), pero ese enfoque no es muy útil. En su lugar, es mejor extraer mensajes de un objeto Message o cargarlos desde una entrada binaria.

(Contribuido por R. David Murray, con esfuerzos de Steffen Daode Nurpmeso y un parche inicial de Victor Stinner en bpo-9124 [https://bugs.python.org/issue?@action=redirect&bpo=9124].)

turtledemo

El código de demostración para el módulo turtle se movió del directorio Demo a la biblioteca principal. Incluye más de una docena de scripts de muestra con pantallas animadas. Al estar en sys.path, ahora se puede ejecutar directamente desde la línea de comandos:

$ python -m turtledemo

(Movido del directorio Demo por Alexander Belopolsky en bpo-10199 [https://bugs.python.org/issue?@action=redirect&bpo=10199].)

Multi-threading

Se ha reescrito el mecanismo para serializar la ejecución de subprocesos de Python que se ejecutan simultáneamente (generalmente conocido como GIL o Global Interpreter Lock). Entre los objetivos estaban los intervalos de conmutación más predecibles y la reducción de la sobrecarga debido a la contención de bloqueo y la cantidad de llamadas al sistema consiguientes. La noción de un «intervalo de verificación» para permitir cambios de hilo ha sido abandonada y reemplazada por una duración absoluta expresada en segundos. Este parámetro se puede ajustar a través de sys.setswitchinterval(). Actualmente, el valor predeterminado es 5 milisegundos.

Se pueden leer detalles adicionales sobre la implementación en un mensaje de lista de correo python-dev mailing-list message [https://mail.python.org/pipermail/python-dev/2009-October/093321.html] (sin embargo, «prioridad las solicitudes» como se expone en este mensaje no se han mantenido para su inclusión).

(Contribución de Antoine Pitrou.)

Los bloqueos regulares y recursivos ahora aceptan un argumento opcional timeout para su método acquire() . (Contribución de Antoine Pitrou; bpo-7316 [https://bugs.python.org/issue?@action=redirect&bpo=7316].)

De manera similar, threading.Semaphore.acquire() también ganó un argumento timeout. (Contribución de Torsten Landschoff; bpo-850728 [https://bugs.python.org/issue?@action=redirect&bpo=850728].)

Las adquisiciones de bloqueos regulares y recursivas ahora pueden ser interrumpidas por señales en plataformas que usan Pthreads. Esto significa que los programas de Python que se bloquean mientras adquieren bloqueos pueden eliminarse con éxito enviando repetidamente SIGINT al proceso (presionando Ctrl+C en la mayoría de los shells). (Contribuido por Reid Kleckner; bpo-8844 [https://bugs.python.org/issue?@action=redirect&bpo=8844].)

Optimizations

Se han agregado una serie de pequeñas mejoras de rendimiento:

El optimizador de mirilla de Python ahora reconoce patrones como x in {1, 2, 3} como una prueba de pertenencia a un conjunto de constantes. El optimizador reformula set como frozenset y almacena la constante preconstruida.

Ahora que la penalización de velocidad se ha ido, es práctico comenzar a escribir pruebas de membresía usando notación de conjuntos. Este estilo es semánticamente claro y operativamente rápido:

extension = name.rpartition('.')[2]
if extension in {'xml', 'html', 'xhtml', 'css'}:
    handle(name)

(Parche y pruebas adicionales aportadas por Dave Malcolm; bpo-6690 [https://bugs.python.org/issue?@action=redirect&bpo=6690]).

Serializar y deserializar datos usando el módulo pickle ahora es varias veces más rápido.

(Contribución de Alexandre Vassalotti, Antoine Pitrou y el equipo de Unladen Swallow en bpo-9410 [https://bugs.python.org/issue?@action=redirect&bpo=9410] y bpo-3873 [https://bugs.python.org/issue?@action=redirect&bpo=3873].)

El algoritmo Timsort algorithm [https://en.wikipedia.org/wiki/Timsort] usado en list.sort() y sorted() ahora se ejecuta más rápido y usa menos memoria cuando se llama con key function. Anteriormente, cada elemento de una lista se envolvía con un objeto temporal que recordaba el valor clave asociado con cada elemento. Ahora, dos matrices de claves y valores se ordenan en paralelo. Esto ahorra la memoria consumida por los contenedores de clasificación y ahorra el tiempo perdido al delegar comparaciones.

(Parche de Daniel Stutzbach en bpo-9915 [https://bugs.python.org/issue?@action=redirect&bpo=9915].)

El rendimiento de la decodificación JSON mejora y el consumo de memoria se reduce siempre que se repite la misma cadena para varias claves. Además, la codificación JSON ahora usa las aceleraciones de C cuando el argumento sort_keys es verdadero.

(Contribución de Antoine Pitrou en bpo-7451 [https://bugs.python.org/issue?@action=redirect&bpo=7451] y Raymond Hettinger y Antoine Pitrou en bpo-10314 [https://bugs.python.org/issue?@action=redirect&bpo=10314].)

Los bloqueos recursivos (creados con la API threading.RLock()) ahora se benefician de una implementación de C que los hace tan rápidos como los bloqueos normales, y entre 10 y 15 veces más rápidos que su anterior implementación pura de Python.

(Contribución de Antoine Pitrou; bpo-3001 [https://bugs.python.org/issue?@action=redirect&bpo=3001].)

El algoritmo de búsqueda rápida en stringlib ahora es usado por los métodos split(), rsplit(), splitlines() y replace() en objetos bytes, bytearray y str. Asimismo, el algoritmo también es utilizado por rfind(), rindex(), rsplit() y rpartition().

(Parche de Florent Xicluna en bpo-7622 [https://bugs.python.org/issue?@action=redirect&bpo=7622] y bpo-7462 [https://bugs.python.org/issue?@action=redirect&bpo=7462].)

Las conversiones de enteros a cadenas de caracteres ahora funcionan con dos «dígitos» a la vez, lo que reduce el número de operaciones de división y módulo.

(bpo-6713 [https://bugs.python.org/issue?@action=redirect&bpo=6713] de Gawain Bolton, Mark Dickinson y Victor Stinner.)

Hubo varias otras optimizaciones menores. Establecer diferencias ahora se ejecuta más rápido cuando un operando es mucho más grande que el otro (parche de Andress Bennetts en bpo-8685 [https://bugs.python.org/issue?@action=redirect&bpo=8685]). El método array.repeat() tiene una implementación más rápida (bpo-1569291 [https://bugs.python.org/issue?@action=redirect&bpo=1569291] de Alexander Belopolsky). El BaseHTTPRequestHandler tiene un almacenamiento en búfer más eficiente (bpo-3709 [https://bugs.python.org/issue?@action=redirect&bpo=3709] por Andrew Schaaf). La función operator.attrgetter() se ha acelerado (bpo-10160 [https://bugs.python.org/issue?@action=redirect&bpo=10160] de Christos Georgiou). Y ConfigParser carga argumentos de varias líneas un poco más rápido (bpo-7113 [https://bugs.python.org/issue?@action=redirect&bpo=7113] de Łukasz Langa).

Unicode

Python se ha actualizado a Unicode 6.0.0 [http://unicode.org/versions/Unicode6.0.0/]. La actualización del estándar agrega más de 2.000 caracteres nuevos, incluidos los símbolos emoji [https://en.wikipedia.org/wiki/Emoji] que son importantes para los teléfonos móviles.

Además, el estándar actualizado ha alterado las propiedades de los caracteres para dos caracteres Kannada (U+0CF1, U+0CF2) y un carácter numérico nuevo Tai Lue (U+19DA), lo que hace que el primero sea elegible para su uso en identificadores y descalifica al segundo. Para obtener más información, consulte Cambios en la base de datos de caracteres Unicode [http://www.unicode.org/versions/Unicode6.0.0/#Database_Changes].

Codecs

Se agregó soporte para cp720 codificación DOS árabe (bpo-1616979 [https://bugs.python.org/issue?@action=redirect&bpo=1616979]).

La codificación MBCS ya no ignora el argumento del controlador de errores. En el modo estricto predeterminado, genera un UnicodeDecodeError cuando encuentra una secuencia de bytes no codificable y un UnicodeEncodeError para un carácter no codificable.

El códec MBCS admite los controladores de errores 'strict' e 'ignore' para la decodificación y 'strict' y 'replace' para la codificación.

Para emular la codificación Python3.1 MBCS, seleccione el controlador 'ignore' para decodificar y el controlador 'replace' para codificar.

En Mac OS X, Python decodifica los argumentos de la línea de comandos con 'utf-8' en lugar de la codificación local.

De forma predeterminada, tarfile usa la codificación 'utf-8'` en Windows (en lugar de ``'mbcs') y el controlador de errores 'surrogateescape' en todos los sistemas operativos.

Documentación

La documentación sigue mejorando.

Se ha agregado una tabla de enlaces rápidos en la parte superior de secciones largas como Funciones Built-in. En el caso de itertools, los enlaces están acompañados de tablas de resúmenes al estilo de una hoja de trucos para proporcionar una descripción general y un cambio de memoria sin tener que leer todos los documentos.

En algunos casos, el código fuente puro de Python puede ser un complemento útil de la documentación, por lo que ahora muchos módulos incluyen enlaces rápidos a la última versión del código fuente. Por ejemplo, la documentación del módulo functools tiene un enlace rápido en la parte superior etiquetado:

Código fuente Lib/functools.py [https://github.com/python/cpython/tree/3.9/Lib/functools.py].

(Contribuido por Raymond Hettinger; ver rationale [https://rhettinger.wordpress.com/2011/01/28/open-your-source-more/].)

Los documentos ahora contienen más ejemplos y recetas. En particular, el módulo re tiene una sección extensa, Ejemplos de expresiones regulares. Asimismo, el módulo itertools continúa siendo actualizado con nuevo Fórmulas con itertools.

El módulo datetime ahora tiene una implementación auxiliar en Python puro. No se modificó ninguna funcionalidad. Esto solo proporciona una implementación alternativa más fácil de leer.

(Contribuido por Alexander Belopolsky en bpo-9528 [https://bugs.python.org/issue?@action=redirect&bpo=9528].)

Se ha eliminado el directorio no mantenido Demo. Algunas demostraciones se integraron en la documentación, otras se movieron al directorio Tools/demo y otras se eliminaron por completo.

(Contribución de Georg Brandl en bpo-7962 [https://bugs.python.org/issue?@action=redirect&bpo=7962].)

IDLE

El menú de formato ahora tiene una opción para limpiar archivos de origen eliminando los espacios en blanco finales.

(Contribución de Raymond Hettinger; bpo-5150 [https://bugs.python.org/issue?@action=redirect&bpo=5150].)

IDLE en Mac OS X ahora funciona con Carbon AquaTk y Cocoa AquaTk.

(Contribución de Kevin Walzer, Ned Deily y Ronald Oussoren; bpo-6075 [https://bugs.python.org/issue?@action=redirect&bpo=6075].)

Repositorio de código

Además del repositorio de código de Subversion existente en http://svn.python.org, ahora hay un repositorio Mercurial [https://www.mercurial-scm.org/] en https://hg.python.org/.

Después de la versión 3.2, hay planes para cambiar a Mercurial como repositorio principal. Este sistema de control de versiones distribuido debería facilitar a los miembros de la comunidad la creación y el intercambio de conjuntos de cambios externos. Consulte PEP 385 [https://www.python.org/dev/peps/pep-0385] para obtener más detalles.

Para aprender a utilizar el nuevo sistema de control de versiones, consulte el Quick Start [https://www.mercurial-scm.org/wiki/QuickStart] o la Guide to Mercurial Workflows [https://www.mercurial-scm.org/guide].

Cambios en la API de construcción y C

Los cambios en el proceso de compilación de Python y en la API de C incluyen:

Los scripts idle, pydoc y 2to3 ahora están instalados con un sufijo específico de la versión en make altinstall (bpo-10679 [https://bugs.python.org/issue?@action=redirect&bpo=10679]).

Las funciones C que acceden a la base de datos Unicode ahora aceptan y retornan caracteres del rango Unicode completo, incluso en compilaciones Unicode estrechas (Py_UNICODE_TOLOWER, Py_UNICODE_ISDECIMAL, y otras). Una diferencia visible en Python es que unicodedata.numeric() ahora devuelve el valor correcto para puntos de código grandes y repr() puede considerar más caracteres como imprimibles.

(Informado por Bupjoe Lee y corregido por Amaury Forgeot D’Arc; bpo-5127 [https://bugs.python.org/issue?@action=redirect&bpo=5127].)

Los gotos calculados ahora están habilitados de forma predeterminada en los compiladores compatibles (que son detectados por el script de configuración). Todavía se pueden desactivar de forma selectiva especificando --without-computed-gotos.

(Contribución de Antoine Pitrou; bpo-9203 [https://bugs.python.org/issue?@action=redirect&bpo=9203].)

Se eliminó la opción --with-wctype-functions. La base de datos unicode incorporada ahora se usa para todas las funciones.

(Contribución de Amaury Forgeot D’Arc; bpo-9210 [https://bugs.python.org/issue?@action=redirect&bpo=9210].)

Los valores hash ahora son valores de un nuevo tipo, Py_hash_t, que se define como del mismo tamaño que un puntero. Anteriormente eran del tipo long, que en algunos sistemas operativos de 64 bits todavía tiene una longitud de solo 32 bits. Como resultado de esta corrección, set y dict ahora pueden contener más de 2**32 entradas en compilaciones con punteros de 64 bits (anteriormente, podían crecer hasta ese tamaño pero su desempeño se degradaba catastróficamente).

(Sugerido por Raymond Hettinger e implementado por Benjamin Peterson; bpo-9778 [https://bugs.python.org/issue?@action=redirect&bpo=9778].)

Una nueva macro Py_VA_COPY copia el estado de la lista de argumentos de la variable. Es equivalente a C99 va_copy pero está disponible en todas las plataformas Python (bpo-2443 [https://bugs.python.org/issue?@action=redirect&bpo=2443]).

Una nueva función de la API de C PySys_SetArgvEx() permite que un intérprete integrado establezca sys.argv sin modificar también sys.path (bpo-5753 [https://bugs.python.org/issue?@action=redirect&bpo=5753]).

PyEval_CallObject ahora solo está disponible en forma de macro. La declaración de función, que se mantuvo por razones de compatibilidad con versiones anteriores, ahora se elimina; la macro se introdujo en 1997 (bpo-8276 [https://bugs.python.org/issue?@action=redirect&bpo=8276]).

Hay una nueva función PyLong_AsLongLongAndOverflow() que es análoga a PyLong_AsLongAndOverflow(). Ambos sirven para convertir Python int en un tipo nativo de ancho fijo al tiempo que brindan detección de casos en los que la conversión no encaja (bpo-7767 [https://bugs.python.org/issue?@action=redirect&bpo=7767]).

La función PyUnicode_CompareWithASCIIString() ahora devuelve not equal si la cadena de Python es NUL terminada.

Hay una nueva función PyErr_NewExceptionWithDoc() que es como PyErr_NewException() pero permite especificar una cadena de documentos. Esto permite que las excepciones de C tengan las mismas capacidades de auto-documentación que sus contrapartes de Python puro (bpo-7033 [https://bugs.python.org/issue?@action=redirect&bpo=7033]).

Cuando se compila con la opción --with-valgrind, el asignador de pymalloc se desactivará automáticamente cuando se ejecute en Valgrind. Esto brinda una detección mejorada de fugas de memoria cuando se ejecuta en Valgrind, mientras se aprovecha pymalloc en otros momentos (bpo-2422 [https://bugs.python.org/issue?@action=redirect&bpo=2422]).

Se eliminó el formato O? De las funciones PyArg_Parse. El formato ya no se usa y nunca se había documentado (bpo-8837 [https://bugs.python.org/issue?@action=redirect&bpo=8837]).

Hubo una serie de otros pequeños cambios en la C-API. Consulte el archivo Misc/NEWS [https://github.com/python/cpython/tree/3.9/Misc/NEWS] para obtener una lista completa.

Además, hubo una serie de actualizaciones para la compilación de Mac OS X, consulte Mac/BuildScript/README.txt [https://github.com/python/cpython/tree/3.9/Mac/BuildScript/README.txt] para obtener más detalles. Para los usuarios que ejecutan una compilación de 32/64 bits, existe un problema conocido con el Tcl/Tk predeterminado en Mac OS X 10.6. En consecuencia, recomendamos instalar una alternativa actualizada como ActiveState Tcl/Tk 8.5.9 [https://www.activestate.com/activetcl/downloads]. Consulte https://www.python.org/download/mac/tcltk/ para obtener detalles adicionales.

Portar a Python 3.2

Esta sección enumera los cambios descritos anteriormente y otras correcciones de errores que pueden requerir cambios en su código:

El módulo configparser tiene una serie de limpiezas. El cambio principal es reemplazar la antigua ConfigParser con la alternativa preferida de larga data SafeConfigParser. Además, hay una serie de incompatibilidades menores:

La sintaxis de interpolación ahora está validada en las operaciones get() y set(). En el esquema de interpolación predeterminado, solo dos tokens con signos de porcentaje son válidos: %(name)s y %%, siendo este último un signo de porcentaje de escape.

Los métodos set() y add_section() ahora verifican que los valores sean cadenas reales. Anteriormente, los tipos no admitidos podían introducirse involuntariamente.

Las secciones u opciones duplicadas de una sola fuente ahora generan DuplicateSectionError o DuplicateOptionError. Anteriormente, los duplicados sobrescribían silenciosamente una entrada anterior.

Los comentarios en línea ahora están deshabilitados de forma predeterminada, por lo que ahora el carácter ; se puede usar de forma segura en los valores.

Los comentarios ahora se pueden sangrar. En consecuencia, para que ; o # aparezcan al principio de una línea en valores multilínea, debe interpolarse. Esto evita que los caracteres de prefijo de comentario en valores se confundan con comentarios.

"" ahora es un valor válido y ya no se convierte automáticamente en una cadena vacía. Para cadenas vacías, use "option =" en una línea.

El módulo nntplib se modificó ampliamente, lo que significa que sus API a menudo son incompatibles con las API 3.1.

bytearray ya no se pueden usar como nombres de archivo; en su lugar, deben convertirse a bytes.

Los array.tostring() y array.fromstring() han sido renombrados a array.tobytes() y array.frombytes() para mayor claridad. Los nombres antiguos han quedado obsoletos. (Ver bpo-8990 [https://bugs.python.org/issue?@action=redirect&bpo=8990].)

Funciones PyArg_Parse*():

Se ha eliminado el formato «t#»: utilice «s#» o «s*» en su lugar

Se han eliminado los formatos «w» y «w #»: utilice «w*» en su lugar

El tipo PyCObject, obsoleto en 3.1, ha sido eliminado. Para envolver punteros C opacos en objetos Python, se debe utilizar la API PyCapsule; el nuevo tipo tiene una interfaz bien definida para pasar información de seguridad de escritura y una firma menos complicada para llamar a un destructor.

La función sys.setfilesystemencoding() se eliminó porque tenía un diseño defectuoso.

La función y el método random.seed() ahora saltan semillas de cadenas con una función hash sha512. Para acceder a la versión anterior de seed para reproducir secuencias de Python 3.1, establezca el argumento version en 1, random.seed(s, version=1).

La función anteriormente obsoleta string.maketrans() ha sido eliminada en favor de los métodos estáticos bytes.maketrans() y bytearray.maketrans(). Este cambio resuelve la confusión sobre qué tipos eran compatibles con el módulo string. Ahora, str, bytes, y bytearray cada uno tiene sus propios métodos maketrans y translate con tablas de traducción intermedias del tipo apropiado.

(Contribución de Georg Brandl; bpo-5675 [https://bugs.python.org/issue?@action=redirect&bpo=5675].)

La función anteriormente obsoleta contextlib.nested() ha sido eliminada en favor de una declaración simple with que puede aceptar múltiples administradores de contexto. La última técnica es más rápida (porque está integrada) y hace un mejor trabajo finalizando múltiples administradores de contexto cuando uno de ellos genera una excepción:

with open('mylog.txt') as infile, open('a.out', 'w') as outfile:
    for line in infile:
        if '<critical>' in line:
            outfile.write(line)

(Contribución de Georg Brandl y Mattias Brändström; appspot issue 53094 [https://codereview.appspot.com/53094].)

struct.pack() ahora permite bytes para el código del paquete de cadenas s. Anteriormente, aceptaba argumentos de texto y los codificaba implícitamente en bytes usando UTF-8. Esto era problemático porque hacía suposiciones sobre la codificación correcta y porque una codificación de longitud variable puede fallar al escribir en un segmento de longitud fija de una estructura.

El código como struct.pack('<6sHHBBB', 'GIF87a', x, y) debe reescribirse para usar bytes en lugar de texto, struct.pack('<6sHHBBB', b'GIF87a', x, y).

(Descubierto por David Beazley y corregido por Victor Stinner; bpo-10783 [https://bugs.python.org/issue?@action=redirect&bpo=10783].)

La clase xml.etree.ElementTree ahora genera un xml.etree.ElementTree.ParseError cuando falla un análisis. Anteriormente generaba un xml.parsers.expat.ExpatError.

El nuevo valor más largo de str() en flotantes puede romper las pruebas de documentación que se basan en el formato de salida anterior.

En subprocess.Popen, el valor predeterminado para close_fds es ahora True en Unix; en Windows, es True si los tres flujos estándar están configurados como None, o False en caso contrario. Anteriormente, close_fds siempre era False de forma predeterminada, lo que producía errores difíciles de resolver o condiciones de carrera cuando los descriptores de archivos abiertos se filtraban en el proceso hijo.

Se ha eliminado la compatibilidad con HTTP 0.9 heredado de urllib.request y http.client. Dicho soporte todavía está presente en el lado del servidor (en http.server).

(Contribución de Antoine Pitrou, bpo-10711 [https://bugs.python.org/issue?@action=redirect&bpo=10711].)

Los sockets SSL en modo de tiempo de espera ahora generan socket.timeout cuando ocurre un tiempo de espera, en lugar de un genérico SSLError.

(Contribución de Antoine Pitrou, bpo-10272 [https://bugs.python.org/issue?@action=redirect&bpo=10272].)

Las funciones engañosas PyEval_AcquireLock() y PyEval_ReleaseLock() han quedado oficialmente obsoletas. Las API que reconocen el estado del hilo (como PyEval_SaveThread() y PyEval_RestoreThread()) deben usarse en su lugar.

Debido a riesgos de seguridad, asyncore.handle_accept() ha quedado obsoleto, y se agregó una nueva función, asyncore.handle_accepted(), para reemplazarlo.

(Contribución de Giampaolo Rodola en bpo-6706 [https://bugs.python.org/issue?@action=redirect&bpo=6706].)

Debido a la nueva implementación de GIL, PyEval_InitThreads() ya no se puede llamar antes Py_Initialize().

Qué hay de nuevo en Python 3.1

Autor

Raymond Hettinger

En este artículo se explican las nuevas características de Python 3.1, en comparación con 3.0.

PEP 372: Diccionarios ordenados

Los diccionarios de Python normales iteran sobre los pares clave/valor en orden arbitrario. A través de los años, varios autores han escrito implementaciones alternativas que recuerdan el orden en el que se insertaron originalmente las claves. Basándose en las experiencias de esas implementaciones, una nueva clase collections.OrderedDict ha sido introducida.

La API de OrderedDict es sustancialmente la misma que la de los diccionarios normales, pero iterará sobre las claves y los valores en un orden garantizado, dependiendo de cuándo se insertó una clave por primera vez. Si una nueva entrada sobrescribe una entrada existente, la posición de inserción original se deja sin cambios. Eliminar una entrada y volver a insertarla la moverá hasta el final.

La biblioteca estándar ahora admite el uso de diccionarios ordenados en varios módulos. El módulo configparser los usa por defecto. Esto permite que los archivos de configuración se lean, modifiquen y luego se vuelvan a escribir en su orden original. El método _asdict() para collections.namedtuple() ahora retorna un diccionario ordenado con los valores que aparecen en el mismo orden que los índices de tupla subyacentes. El módulo json se está construyendo con un object_pairs_hook para permitir que el decodificador construya OrderedDicts. También se agregó soporte para herramientas de terceros como PyYAML [http://pyyaml.org/].

Ver también

PEP 372 [https://www.python.org/dev/peps/pep-0372] - Diccionarios ordenados

PEP escrito por Armin Ronacher y Raymond Hettinger. Implementación escrita por Raymond Hettinger.

PEP 378: Especificador de formato para el separador de miles

La función incorporada format() y el método str.format() usan un mini-lenguaje que ahora incluye una forma simple, que no tiene en cuenta la configuración regional, de formatear un número con un separador de miles. Eso proporciona una manera de humanizar la salida de un programa, mejorando su apariencia profesional y legibilidad:

>>> format(1234567, ',d')
'1,234,567'
>>> format(1234567.89, ',.2f')
'1,234,567.89'
>>> format(12345.6 + 8901234.12j, ',f')
'12,345.600000+8,901,234.120000j'
>>> format(Decimal('1234567.89'), ',f')
'1,234,567.89'

Los tipos soportados son int, float, complex y decimal.Decimal.

Se está discutiendo cómo especificar separadores alternativos como puntos, espacios, apóstrofos o guiones bajos. Las aplicaciones que reconocen la configuración regional deben usar el especificador de formato n existente, que ya es compatible con el separadores de miles.

Ver también

PEP 378 [https://www.python.org/dev/peps/pep-0378] - Especificador de formato para el separador de miles

PEP escrito por Raymond Hettinger e implementado por Eric Smith y Mark Dickinson.

Otros cambios del lenguaje

Algunos cambios pequeños en el núcleo del lenguaje Python son:

Los directorios y archivos zip que contienen un archivo __main__.py pueden ahora ser ejecutados directamente pasando su nombre al intérprete. El directorio/archivo zip es automáticamente insertado como la primera entrada en sys.path. (Sugerencia y parche inicial por Andy Chu; parche revisado por Phillip J. Eby y Nick Coghlan; bpo-1739468 [https://bugs.python.org/issue?@action=redirect&bpo=1739468].)

El tipo int() ganó un método bit_length que retorna el número de bits necesarios para representar sus argumentos en binario:

>>> n = 37
>>> bin(37)
'0b100101'
>>> n.bit_length()
6
>>> n = 2**123-1
>>> n.bit_length()
123
>>> (n+1).bit_length()
124

(Contribución de Fredrik Johansson, Victor Stinner, Raymond Hettinger y Mark Dickinson; bpo-3439 [https://bugs.python.org/issue?@action=redirect&bpo=3439].)

Los campos en las cadenas de formato de format() ahora pueden ser automáticamente numerados:

>>> 'Sir {} of {}'.format('Gallahad', 'Camelot')
'Sir Gallahad of Camelot'

Anteriormente, la cadena requería campos numerados como: 'Sir {0} of {1}'.

(Contribución de Eric Smith; bpo-5237 [https://bugs.python.org/issue?@action=redirect&bpo=5237].)

La función string.maketrans() está en desuso y se reemplaza por nuevos métodos estáticos, bytes.maketrans() y bytearray.maketrans(). Este cambio resuelve la confusión en torno a los tipos que fueron soportados por el módulo string. Ahora, str, bytes y bytearray tienen sus propios métodos maketrans y translate con tablas de traducción intermedias del tipo adecuado.

(Contribución de Georg Brandl; bpo-5675 [https://bugs.python.org/issue?@action=redirect&bpo=5675].)

La sintaxis de la sentencia with ahora permite múltiples gestores de contexto en una sola declaración:

>>> with open('mylog.txt') as infile, open('a.out', 'w') as outfile:
...     for line in infile:
...         if '<critical>' in line:
...             outfile.write(line)

Con la nueva sintaxis, la función contextlib.nested() ya no es necesaria y ahora está obsoleta.

(Contribución de Georg Brandl y Mattias Brändström; appspot issue 53094 [https://codereview.appspot.com/53094].)

round(x, n) ahora retorna un número entero si x es un entero. Anteriormente retornaba un número flotante:

>>> round(1123, -2)
1100

(Contribución de Mark Dickinson; bpo-4707 [https://bugs.python.org/issue?@action=redirect&bpo=4707].)

Python ahora utiliza el algoritmo de David Gay para encontrar la representación de coma flotante más corta que no cambia su valor. Esto debería ayudar a mitigar parte de la confusión que rodea a los números de coma flotante binarios.

La importancia se ve fácilmente con un número como 1.1, que no tiene un equivalente exacto en coma flotante binaria. Puesto que no hay un equivalente exacto, una expresión como float('1.1') se evalúa como el valor representable más cercano, que es 0x1.199999999999ap+0 en hexadecimal o 1.100000000000000088817841970012523233890533447265625 en decimal. Ese valor más cercano fue y todavía es utilizado en los cálculos de coma flotante posteriores.

La novedad es cómo se muestra el número. Anteriormente, Python usaba un enfoque simple. El valor de repr(1.1) se calculaba como format(1.1, '.17g') que era evaluado como '1.1000000000000001'. La ventaja de utilizar 17 dígitos era que se basaba en las garantías de IEEE-754 para asegurar que eval(repr(1.1)) se volviera a redondear exactamente a su valor original. La desventaja es que muchas personas encontraban el resultado confuso (confundiendo las limitaciones intrínsecas de la representación de coma flotante binaria con un problema con Python en sí).

El nuevo algoritmo para repr(1.1) es más inteligente y retorna '1.1'. Efectivamente, busca todas las representaciones de cadenas equivalentes (las que se almacenan con el mismo valor flotante subyacente) y retorna la representación más corta.

El nuevo algoritmo tiende a emitir representaciones más limpias cuando es posible, pero esto no cambia los valores subyacentes. Por lo tanto, todavía se da el caso 1.1 + 2.2 != 3.3, aún cuando las representaciones puedan sugerir lo contrario.

El nuevo algoritmo depende de ciertas características de la implementación de coma flotante subyacente. Si no se encuentran las características necesarias, el algoritmo antiguo seguirá utilizándose. Además, los protocolos de pickle de texto aseguran la portabilidad multiplataforma mediante el algoritmo antiguo.

(Contribución de Eric Smith y Mark Dickinson; bpo-1580 [https://bugs.python.org/issue?@action=redirect&bpo=1580])

Módulos nuevos, mejorados y obsoletos

Se ha añadido una clase collections.Counter para admitir el recuento conveniente de elementos únicos en una secuencia o una iteración:

>>> Counter(['red', 'blue', 'red', 'green', 'blue', 'blue'])
Counter({'blue': 3, 'red': 2, 'green': 1})

(Contribución de Raymond Hettinger; bpo-1696199 [https://bugs.python.org/issue?@action=redirect&bpo=1696199].)

Se ha añadido un nuevo módulo tkinter.ttk para acceder al conjunto de widgets temáticos de Tk. La idea básica de ttk es separar, dentro de lo posible, el código que implementa el comportamiento de un widget del código que implementa su apariencia.

(Contribución de Guilherme Polo; bpo-2983 [https://bugs.python.org/issue?@action=redirect&bpo=2983].)

Las clases gzip.GzipFile y bz2.BZ2File ahora admiten el protocolo de gestión de contexto:

>>> # Automatically close file after writing
>>> with gzip.GzipFile(filename, "wb") as f:
...     f.write(b"xxx")

(Contribución de Antoine Pitrou.)

El módulo decimal ahora admite métodos para crear un objeto decimal de un float binario. La conversión es exacta pero puede ser a veces una sorpresa:

>>> Decimal.from_float(1.1)
Decimal('1.100000000000000088817841970012523233890533447265625')

El resultado decimal largo muestra la fracción binaria real que se almacena para 1.1. La fracción tiene muchos dígitos porque 1.1 no se puede representar exactamente en binario.

(Contribución de Raymond Hettinger y Mark Dickinson.)

El módulo itertools desarrolló dos nuevas funciones. La función itertools.combinations_with_replacement() es una de las cuatro para generar combinatorias que incluyen permutaciones y productos cartesianos. La función itertools.compress() imita su homónimo de APL. Además, la función existente itertools.count() tiene ahora un argumento step opcional y puede aceptar cualquier tipo de secuencia de conteo, incluyendo fractions.Fraction y decimal.Decimal:

>>> [p+q for p,q in combinations_with_replacement('LOVE', 2)]
['LL', 'LO', 'LV', 'LE', 'OO', 'OV', 'OE', 'VV', 'VE', 'EE']

>>> list(compress(data=range(10), selectors=[0,0,1,1,0,1,0,1,0,0]))
[2, 3, 5, 7]

>>> c = count(start=Fraction(1,2), step=Fraction(1,6))
>>> [next(c), next(c), next(c), next(c)]
[Fraction(1, 2), Fraction(2, 3), Fraction(5, 6), Fraction(1, 1)]

(Contribución de Raymond Hettinger.)

collections.namedtuple() ahora admite un argumento de palabra clave rename que permite que los campos de nombre inválidos se conviertan automáticamente en nombres posicionados de la forma _0, _1, etc. Esto es de utilidad cuando los nombres del campo están siendo creados por una fuente externa como un encabezado CSV, una lista de campos SQL, o la entrada del usuario:

>>> query = input()
SELECT region, dept, count(*) FROM main GROUPBY region, dept

>>> cursor.execute(query)
>>> query_fields = [desc[0] for desc in cursor.description]
>>> UserQuery = namedtuple('UserQuery', query_fields, rename=True)
>>> pprint.pprint([UserQuery(*row) for row in cursor])
[UserQuery(region='South', dept='Shipping', _2=185),
 UserQuery(region='North', dept='Accounting', _2=37),
 UserQuery(region='West', dept='Sales', _2=419)]

(Contribución de Raymond Hettinger; bpo-1818 [https://bugs.python.org/issue?@action=redirect&bpo=1818].)

Las funciones re.sub(), re.subn() y re.split() ahora admiten un parámetro flags.

(Contribución de Gregory Smith.)

El módulo logging ahora implementa una clase simple logging.NullHandler para aplicaciones que no utilizan el registro pero llaman al código de una biblioteca que si lo hace. La configuración de un controlador nulo suprimirá las advertencias falsas como «No handlers could be found for logger foo»:

>>> h = logging.NullHandler()
>>> logging.getLogger("foo").addHandler(h)

(Contribución de Vinay Sajip; bpo-4384 [https://bugs.python.org/issue?@action=redirect&bpo=4384]).

El módulo runpy que admite el modificador de línea de comando -m ahora admite la ejecución de paquetes al buscar y ejecutar un submódulo __main__ cuando se proporciona un nombre de paquete.

(Contribución de Andi Vajda; bpo-4195 [https://bugs.python.org/issue?@action=redirect&bpo=4195].)

El módulo pdb puede ahora acceder y mostrar el código fuente cargado a través de zipimport (o cualquier otro cargador conforme PEP 302 [https://www.python.org/dev/peps/pep-0302]).

(Contribución de Alexander Belopolsky; bpo-4201 [https://bugs.python.org/issue?@action=redirect&bpo=4201].)

Los objetos functools.partial pueden ser ahora serializados (pickled).

(Sugerido por Antoine Pitrou y Jesse Noller. Implementado por Jack Diederich; bpo-5228 [https://bugs.python.org/issue?@action=redirect&bpo=5228].)

Se agrega temas de ayuda pydoc para símbolos de modo que help('@') funcione como se espera en un entorno interactivo.

(Contribución de David Laban; bpo-4739 [https://bugs.python.org/issue?@action=redirect&bpo=4739].)

El módulo unittest ahora admite saltear pruebas individuales o clases de pruebas. Y admite marcar una prueba como una falla esperada, una prueba que se sabe que está rota, pero que no debe contarse como una falla en un TestResult:

class TestGizmo(unittest.TestCase):

    @unittest.skipUnless(sys.platform.startswith("win"), "requires Windows")
    def test_gizmo_on_windows(self):
        ...

    @unittest.expectedFailure
    def test_gimzo_without_required_library(self):
        ...

Además, se han creado pruebas de excepciones para trabajar con gestores de contexto usando la declaración with:

def test_division_by_zero(self):
    with self.assertRaises(ZeroDivisionError):
        x / 0

Además, se agregaron varios métodos de aserción nuevos, incluyendo assertSetEqual(), assertDictEqual(), assertDictContainsSubset(), assertListEqual(), assertTupleEqual(), assertSequenceEqual(), assertRaisesRegexp(), assertIsNone(), y assertIsNotNone().

(Contribución de Benjamin Peterson y Antoine Pitrou.)

El módulo io tiene tres nuevas constantes para el método seek(): SEEK_SET, SEEK_CUR y SEEK_END.

La tupla sys.version_info es ahora una tupla nombrada:

>>> sys.version_info
sys.version_info(major=3, minor=1, micro=0, releaselevel='alpha', serial=2)

(Contribución de Ross Light; bpo-4285 [https://bugs.python.org/issue?@action=redirect&bpo=4285].)

Los módulos nntplib y imaplib ahora tienen soporte de IPv6.

(Contribución de Derek Morr; bpo-1655 [https://bugs.python.org/issue?@action=redirect&bpo=1655] y bpo-1664 [https://bugs.python.org/issue?@action=redirect&bpo=1664].)

El módulo pickle ha sido adaptado para una mejor interoperabilidad con 2.x cuando es usado con un protocolo 2 o menor. La reorganización de la biblioteca estándar cambió la referencia formal para varios objetos. Por ejemplo, __builtin__.set en Python 2 es llamado builtins.set en Python 3. Este cambio confundió los esfuerzos de compartir datos entre diferentes versiones de Python. Pero ahora cuando el protocolo 2 o menor es seleccionado, el pickler va a usar automáticamente los nombres antiguos de Python 2 tanto para carga como para volcado. Esta reasignación es activada de manera predeterminada pero puede ser desactivada con la opción fix_imports:

>>> s = {1, 2, 3}
>>> pickle.dumps(s, protocol=0)
b'c__builtin__\nset\np0\n((lp1\nL1L\naL2L\naL3L\natp2\nRp3\n.'
>>> pickle.dumps(s, protocol=0, fix_imports=False)
b'cbuiltins\nset\np0\n((lp1\nL1L\naL2L\naL3L\natp2\nRp3\n.'

Un efecto secundario, desafortunado pero inevitable, de este cambio es que los pickles del protocolo 2 producidos con Python 3.1 no serán legibles con Python 3.0. El protocolo de pickle más reciente, protocolo 3, debe utilizarse al migrar datos entre implementaciones de Python 3.x, ya que no intenta seguir siendo compatible con Python 2.x.

(Contribución de Alexandre Vassalotti y Antoine Pitrou, bpo-6137 [https://bugs.python.org/issue?@action=redirect&bpo=6137].)

Se agregó un nuevo módulo, importlib. Proporciona una implementación de referencia de Python completa, portátil y pura de la instrucción import y su contraparte, la función __import__() . Representa un avance sustancial en la documentación y definición de las acciones que tienen lugar durante las importaciones.

(Contribución de Brett Cannon.)

Optimizaciones

Se han agregado importantes mejoras de rendimiento:

La nueva biblioteca I/O (definida en PEP 3116 [https://www.python.org/dev/peps/pep-3116]) estaba escrita mayormente en Python y rápidamente demostró ser un cuello de botella problemático en Python 3.0. En Python 3.1, la biblioteca I/O ha sido reescrita enteramente en C y es de 2 a 20 veces más rápida dependiendo en la tarea a manejar. La versión puramente en Python está aún disponible para fines experimentales a través del módulo _pyio.

(Contribución de Amaury Forgeot d’Arc y Antoine Pitrou.)

Se ha añadido una heurística para que el recolector de basura no realice el seguimiento de tuplas y diccionarios que contengan solo objetos no rastreables. Esto puede reducir el tamaño de las colecciones y, por lo tanto, la sobrecarga de recolección de elementos no utilizados en programas de larga ejecución, en función de su uso particular de los tipos de datos.

(Contribución de Antoine Pitrou, bpo-4688 [https://bugs.python.org/issue?@action=redirect&bpo=4688].)

Habilitando una opción de configuración llamada --with-computed-gotos en compiladores que la admiten (en particular: gcc, SunPro, icc), el ciclo de evaluación del bytecode se compila con un nuevo mecanismo de despacho que proporciona aceleraciones de hasta un 20% , dependiendo del sistema, del compilador y del punto de referencia.

(Contribución de Antoine Pitrou junto con varios otros participantes, bpo-4753 [https://bugs.python.org/issue?@action=redirect&bpo=4753]).

La decodificación de UTF-8, UTF-16 y LATIN-1 es ahora de dos a cuatro veces más rápida.

(Contribución de Antoine Pitrou y Amaury Forgeot d’Arc, bpo-4868 [https://bugs.python.org/issue?@action=redirect&bpo=4868].)

El módulo json tiene ahora una extensión C para mejorar sustancialmente su desempeño. Además, la API fue modificada para que json trabaje solo con str, no con bytes. Este cambio hace que el módulo coincida con la especificación de JSON [https://www.json.org/json-es.html] que es definida en términos de Unicode.

(Contribución de Bob Ippolito y convertido a Py3.1 por Antoine Pitrou y Benjamin Peterson; bpo-4136 [https://bugs.python.org/issue?@action=redirect&bpo=4136].)

La deserialización (unpickling) ahora interna los nombres de los atributos de los objetos serializados (pickled). Esto ahorra memoria y permite que los pickles sean más pequeños.

(Contribución de Jake McGuire y Antoine Pitrou; bpo-5084 [https://bugs.python.org/issue?@action=redirect&bpo=5084].)

IDLE

El menú de formato del IDLE ahora proporciona una opción para eliminar los espacios en blanco finales de un archivo de código fuente.

(Contribución de Roger D. Serwy; bpo-5150 [https://bugs.python.org/issue?@action=redirect&bpo=5150].)

Cambios en la compilación y la API de C

Los cambios en el proceso de compilación de Python y en la API C incluyen:

Integers are now stored internally either in base 2**15 or in base 2**30, the base being determined at build time. Previously, they were always stored in base 2**15. Using base 2**30 gives significant performance improvements on 64-bit machines, but benchmark results on 32-bit machines have been mixed. Therefore, the default is to use base 2**30 on 64-bit machines and base 2**15 on 32-bit machines; on Unix, there’s a new configure option --enable-big-digits that can be used to override this default.

Aparte de las mejoras de rendimiento, este cambio debería ser invisible para los usuarios finales, con una excepción: para propósitos de prueba y depuración, hay un nuevo sys.int_info que proporciona información sobre el formato interno, dando el número de bits por dígito y el tamaño en bytes del tipo C utilizado para almacenar cada dígito:

>>> import sys
>>> sys.int_info
sys.int_info(bits_per_digit=30, sizeof_digit=4)

(Contribución de Mark Dickinson; bpo-4258 [https://bugs.python.org/issue?@action=redirect&bpo=4258].)

La función PyLong_AsUnsignedLongLong() es ahora capaz de manejar un pylong negativo lanzando una excepción OverflowError en lugar de TypeError.

(Contribución de Mark Dickinson y Lisandro Dalcrin; bpo-5175 [https://bugs.python.org/issue?@action=redirect&bpo=5175].)

PyNumber_Int() está ahora obsoleto. Utilice PyNumber_Long() en su lugar.

(Contribución de Mark Dickinson; bpo-4910 [https://bugs.python.org/issue?@action=redirect&bpo=4910].)

Se agrega una nueva función PyOS_string_to_double() para reemplazar las funciones obsoletas PyOS_ascii_strtod() y PyOS_ascii_atof().

(Contribución de Mark Dickinson; bpo-5914 [https://bugs.python.org/issue?@action=redirect&bpo=5914].)

Se agrega PyCapsule como un reemplazo para la API PyCObject. La principal diferencia es que el nuevo tipo tiene una interfaz bien definida para pasar información de seguridad de escritura y una firma menos complicada para llamar a un destructor. El tipo anterior tenía una API problemática y ahora está obsoleta.

(Contribución de Larry Hastings; bpo-5630 [https://bugs.python.org/issue?@action=redirect&bpo=5630].)

Portando a Python 3.1

Esta sección enumera los cambios descritos anteriormente y otras correcciones de errores que pueden requerir cambios en su código:

Las nuevas representaciones de cadenas de coma flotante pueden romper las pruebas de documentación existentes. Por ejemplo:

def e():
    '''Compute the base of natural logarithms.

    >>> e()
    2.7182818284590451

    '''
    return sum(1/math.factorial(x) for x in reversed(range(30)))

doctest.testmod()

**********************************************************************
Failed example:
    e()
Expected:
    2.7182818284590451
Got:
    2.718281828459045
**********************************************************************

La reasignación automática de nombres en el módulo pickle para el protocolo 2 o inferior puede hacer que los pickles de Python 3.1 sean ilegibles en Python 3.0. Una solución es usar el protocolo 3. Otra solución es establecer la opción fix_imports en False. Consulte la discusión anterior para obtener más detalles.

Qué hay de nuevo en Python 3.0

Autor

Guido van Rossum

En este artículo se explican las nuevas características de Python 3.0, en comparación con las de 2.6. Python 3.0, también conocido como «Python 3000» o «Py3K». Es la primera versión de Python intencionalmente incompatible hacia atrás. Hay más cambios que en una versión típica y más que son importantes para todos los usuarios de Python. Sin embargo, después de digerir los cambios, se comprobará que Python no ha cambiado tanto realmente – en general, estamos arreglando en su mayoría molestias y defectos bien conocidos, y la eliminación de una gran cantidad de sobras antiguas.

Este artículo no intenta proporcionar una especificación completa de todas las características nuevas, sino que intenta proporcionar una visión general conveniente. Para obtener más información, se debe consultar la documentación de Python 3.0 y/o los muchos PEP a los que se hace referencia en el texto. Si se desea comprender la lógica completa de implementación y diseño para una característica determinada, los PEP suelen tener más detalles que la documentación regular, pero téngase en cuenta que los PEP generalmente no se mantienen actualizados una vez que una característica se ha implementado completamente.

Debido a restricciones de tiempo, este documento no es tan completo como debería haber sido. Como siempre para una nueva versión, el archivo Misc/NEWS en la distribución de origen contiene una gran cantidad de información detallada sobre cada pequeña cosa que se cambió.

Escollos comunes

Esta sección contiene esos pequeños cambios que probablemente generarán tropiezos si se está acostumbrado a Python 2.5.

Print es una función

La declaración print se ha sustituido por una función print(), con argumentos de palabra clave para reemplazar la mayor parte de la sintaxis especial de la antigua declaración print (PEP 3105 [https://www.python.org/dev/peps/pep-3105]). Ejemplos:

Old: print "The answer is", 2*2
New: print("The answer is", 2*2)

Old: print x,           # Trailing comma suppresses newline
New: print(x, end=" ")  # Appends a space instead of a newline

Old: print              # Prints a newline
New: print()            # You must call the function!

Old: print >>sys.stderr, "fatal error"
New: print("fatal error", file=sys.stderr)

Old: print (x, y)       # prints repr((x, y))
New: print((x, y))      # Not the same as print(x, y)!

También se puede personalizar el separador entre ítems, por ejemplo:

print("There are <", 2**32, "> possibilities!", sep="")

que genera:

There are <4294967296> possibilities!

Nota:

La función print() no soporta la característica «softspace» de la declaración print vieja. Por ejemplo, en Python 2.x print "A\n", "B" escribiría "A\nB\n"; pero en Python 3.0, print("A\n", "B") escribe "A\n B\n".

Inicialmente, te encontrarás escribiendo mucho la antigua print x en modo interactivo. ¡Es hora de volver a entrenar los dedos para escribir print(x) en su lugar!

En el uso de la herramienta de conversión fuente-a-fuente 2to3, todos las declaraciones print son automáticamente convertidas a una llamada de la función print(), por lo que en general esto no es un problema para proyectos más grandes.

Vistas e iteradores en lugar de listas

Algunas APIs bien conocidas no retornan más listas:

Los métodos dict dict.keys(), dict.items() y dict.values() retornan «vistas» en lugar de listas. Por ejemplo, esto no funciona más: k = d.keys(); k.sort(). Se usa k = sorted(d) en su lugar (esto funciona también en Python 2.5 y es igual de eficiente).

Además, los métodos dict.iterkeys(), dict.iteritems() y dict.itervalues() ya no son compatibles.

map() y filter() retornan iteradores. Si realmente se necesita una lista y las secuencias de entrada son todas de igual longitud, una solución rápida es envolver map() en list(), por ejemplo list(map(...)), pero una mejor solución es a menudo utilizar una lista por comprensión (especialmente cuando el código original utiliza lambda), o reescribir el código para que no necesite una lista en absoluto. Particularmente complicado es map() invocado para los efectos secundarios de la función; la transformación correcta es usar un bucle for normal (ya que crear una lista sería simplemente un desperdicio).

Si las secuencias de entrada no tienen la misma longitud, map() se detendrá en la terminación de la más corta de las secuencias. Para una compatibilidad completa con map() de Python 2.x, también se envuelve las secuencias en itertools.zip_longest(), por ejemplo map(func, *sequences) se convierte en list(map(func, itertools.zip_longest(*sequences))).

range() ahora se comporta como xrange() solía comportarse, excepto que funciona con valores de tamaño arbitrario. Este último ya no existe.

zip() ahora retorna un iterador.

Comparaciones de ordenamiento

Python 3.0 ha simplificado las reglas para las comparaciones de ordenamiento:

Los operadores de comparaciones de ordenamiento (<, <,``”>``, >) lanzan una excepción TypeError cuando los operandos no tienen un orden natural significativo. Por lo tanto, expresiones como 1 < '', 0 > None o len <= len ya no son válidas, y por ejemplo Ninguno < Ninguno lanza TypeError en lugar de retornar False. Un corolario es que ordenar una lista heterogénea ya no tiene sentido – todos los elementos deben ser comparables entre sí. Tener en cuenta que esto no se aplica a los operadores == y !=: los objetos de diferentes tipos incomparables siempre se comparan desiguales entre sí.

builtin.sorted() y list.sort() ya no aceptan el argumento cmp que proporciona una función de comparación. Utilice el argumento key en su lugar. N.B. los argumentos key y reverse ahora son «argumentos por palabra clave».

La función cmp() debe tratarse como quitada, y el método especial __cmp__() ya no es compatible. Utilizar __lt__() para el ordenamiento, __eq__() con __hash__(), y otras comparaciones costosas según sea necesario. (Si realmente se necesita la funcionalidad cmp(), se puede utilizar la expresión (a > b) - (a < b) como el equivalente para cmp(a, b).)

Enteros

PEP 237 [https://www.python.org/dev/peps/pep-0237]: Esencialmente, long renombrado a int. Es decir, solo hay un tipo integral incorporado, denominado int; pero se comporta sobre todo como el viejo tipo long.

PEP 238 [https://www.python.org/dev/peps/pep-0238]: Una expresión como 1/2 retorna un float. Utilizar 1//2 para obtener el comportamiento de truncamiento. (Esta última sintaxis ha existido durante años, al menos desde Python 2.2.)

Se eliminó la constante sys.maxint, ya que ya no hay un límite para el valor de los enteros. Sin embargo, sys.maxsize se puede utilizar como un entero mayor que cualquier lista práctica o índice de cadena de caracteres. Se ajusta al tamaño entero «natural» de la implementación y suele ser el mismo que sys.maxint en versiones anteriores de la misma plataforma (suponiendo las mismas opciones de compilación).

El repr() de un entero largo ya no incluye la L final, por lo que el código que elimina incondicionalmente ese carácter cortará el último dígito en su lugar. (Utilizar str() en su lugar.)

Los literales octales ya no usan la forma 0720; úsese 0o720 en su lugar.

Texto vs. datos en lugar de unicode vs. 8 bits

Todo lo que pensabas saber sobre datos binarios y Unicode ha cambiado.

Python 3.0 utiliza los conceptos de text y datos (binarios) en lugar de cadenas de caracteres Unicode y cadenas de caracteres de 8 bits. Todo el texto es Unicode; sin embargo el Unicode codificado se representa como datos binarios. El tipo utilizado para contener texto es str, el tipo utilizado para contener datos es bytes. La mayor diferencia con la situación 2.x es que cualquier intento de mezclar texto y datos en Python 3.0 lanza un TypeError, mientras que si se mezclan cadenas Unicode y de 8 bits en Python 2.x, funcionaría si la cadena de 8 bits contuviera sólo bytes de 7 bits (ASCII), pero se obtendría un UnicodeDecodeError si contenía valores no ASCII. Este comportamiento específico del valor ha causado numerosas caras tristes a lo largo de los años.

Como consecuencia de este cambio en la filosofía, prácticamente todo el código que utiliza Unicode, codificaciones o datos binarios muy probablemente tiene que cambiar. El cambio es para mejor, ya que en el mundo 2.x había numerosos errores que tenían que ver con la mezcla de texto codificado y sin codificar. Para estar preparado en Python 2.x, comienza a usar unicode para todo el texto sin codificar, y str solo para datos binarios o codificados. Luego , la herramienta 2to3 hará la mayor parte del trabajo por ti.

Ya no se puede utilizar literales u"..." para texto Unicode. Sin embargo, se debe usar literales b"..." para los datos binarios.

Como los tipos str y bytes no se pueden mezclar, siempre se deben convertir explícitamente entre ellos. Utilizar str.encode() para pasar de str a bytes, y bytes.decode() para pasar de bytes a str. También se puede utilizar bytes(s, encoding=...) y str(b, encoding=...), respectivamente.

Al igual que str, el tipo bytes es inmutable. Hay un tipo mutable independiente para contener datos binarios almacenados en búfer, bytearray. Casi todas las API que aceptan bytes también aceptan bytearray. La API mutable se basa en collections. MutableSequence.

Todas las barras invertidas en literales de cadena de caracteres sin formato se interpretan literalmente. Esto significa que los escapes '\U' y '\u' en cadenas de caracteres sin formato no se tratan especialmente. Por ejemplo, r'\u20ac' es una cadena de 6 caracteres en Python 3.0, mientras que en 2.6, ur'\u20ac' era el único carácter «euro». (Por supuesto, este cambio sólo afecta a los literales de cadena de caracteres sin formato; el carácter del euro es '\u20ac' en Python 3.0.)

Se eliminó el tipo abstracto basestring incorporado. Se utiliza str en su lugar. Los tipos str y bytes no tienen suficiente funcionalidad en común para garantizar una clase base compartida. La herramienta 2to3 (ver más abajo) reemplaza cada aparición de basestring por str.

Los archivos abiertos como archivos de texto (todavía el modo predeterminado para open()) siempre utilizan una codificación para asignar entre cadenas de caracteres(en memoria) y bytes (en disco). Los archivos binarios (abiertos con una b en el argumento modo) siempre utilizan bytes en la memoria. Esto significa que si un archivo se abre utilizando un modo o codificación incorrectos, es probable que la E/S falle ruidosamente, en lugar de producir datos incorrectos de forma silenciosa. También significa que incluso los usuarios de Unix tendrán que especificar el modo correcto (texto o binario) al abrir un archivo. Hay una codificación predeterminada dependiente de la plataforma, que en las plataformas Unix se puede establecer con la variable de entorno LANG (y a veces también con algunas otras variables de entorno relacionadas con la configuración regional específicas de la plataforma). En muchos casos, pero no en todos, el valor predeterminado del sistema es UTF-8; nunca se debe contar con este valor predeterminado. Cualquier aplicación que lea o escriba más que texto ASCII puro probablemente debería tener una manera de invalidar la codificación. Ya no es necesario utilizar las secuencias compatibles con la codificación en el módulo codecs.

Los valores iniciales de sys.stdin, sys.stdout y sys.stderr ahora son archivos de texto solo unicode (es decir, son instancias de io.TextIOBase). Para leer y escribir datos de bytes con estas secuencias, se debe usar su atributo io.TextIOBase.buffer.

Los nombres de archivos son pasados y retornados de cadenas desde APIs como cadenas de caracteres (Unicode). Esto puede presentar problemas específicos de plataformas porque en algunas plataformas los nombres de archivos son cadenas de caracteres de bytes arbitrarios. (Por otro lado, en Windows los nombres de archivos son almacenados de forma nativa como Unicode.) Como solución alternativa, la mayoría de las APIs (por ejemplo open() y muchas otras funciones en el módulo os) que toman nombres de archivos aceptan tanto objetos bytes como cadenas de caracteres, y algunas APIs tienen una forma de demandar por un valor de retorno bytes. Por lo tanto, os.listdir() retorna una lista de instancias bytes si el argumento es una instancia bytes, y os.getcwdb() retorna el directorio de trabajo actual como una instancia bytes. Tener en cuenta que cuando os.listdir() retorna una lista de cadenas de caracteres, los nombres de archivo que no se pueden decodificar correctamente se omiten en lugar de lanzar UnicodeError.

Algunas APIs del sistema como os.environ y sys.argv también pueden presentar problemas cuando los bytes puestos a disposición por el sistema no son interpretables usando la codificación predeterminada. Probablemente el mejor abordaje sea asignando la variable LANG y volviendo a ejecutar el programa.

PEP 3138 [https://www.python.org/dev/peps/pep-3138]: El repr() de una cadena de caracteres ya no escapa caracteres no ASCII. Sin embargo, todavía escapa caracteres de control caracteres y puntos de código con estado no imprimible en el estándar the Unicode.

PEP 3120 [https://www.python.org/dev/peps/pep-3120]: La codificación de fuente predeterminada ahora es UTF-8.

PEP 3131 [https://www.python.org/dev/peps/pep-3131]: Letras no ASCII ahora están permitidas en identificadores. (De todas maneras, la librería estándar permanece como sólo ASCII con la excepción de nombres de colaboradores en comentarios.)

Los módulos StringIO and cStringIO ya no están. En su lugar, se importa el módulo the io y se usa io.StringIO o io.BytesIO para texto y datos respectivamente.

Ver también CÓMO (HOWTO) Unicode, que fue actualizado para Python 3.0.

Descripción general de los cambios de sintaxis

Esta sección brinda una descripción general breve de cada cambio sintáctico en Python 3.0.

Nueva sintaxis

PEP 3107 [https://www.python.org/dev/peps/pep-3107]: Argumento de función y anotaciones de valor retornado. Esto proporciona una forma estandarizada de anotar los parámetros y el valor retornado de una función. No hay semántica asociada a estas anotaciones, excepto que se pueden introspeccionar en tiempo de ejecución mediante el atributo __annotations__. La intención es fomentar la experimentación a través de metaclases, decoradores o frameworks.

PEP 3102 [https://www.python.org/dev/peps/pep-3102]: Argumentos de sólo palabra clave. Los parámetros con nombre que se producen después de *args en la lista de parámetros deben especificarse mediante la sintaxis de palabra clave en la llamada. También puede usarse apenas un``*`` sólo en la lista de parámetros para indicar que no se acepta una lista de argumentos de longitud variable, pero se tiene argumentos de sólo palabra clave.

Los argumentos de palabra clave se permiten después de la lista de clases base en una definición de clase. Esto lo usa la nueva convención para especificar una metaclase (consultar la sección siguiente), pero también se puede usar para otros fines, siempre y cuando la metaclase la admita.

PEP 3104 [https://www.python.org/dev/peps/pep-3104]: Declaración nonlocal. Utilizando nonlocal x ahora se puede asignar directamente a una variable en un entorno externo (pero no global). nonlocal es una nueva palabra reservada.

PEP 3132 [https://www.python.org/dev/peps/pep-3132]: Desempaque iterable extendido. Ahora se puede escribir cosas como a, b, *rest = some_sequence. E incluso *rest, a = cosas. El objeto rest es siempre una lista (posiblemente vacía); el lado derecho puede ser cualquier iterable. Ejemplo:

(a, *rest, b) = range(5)

Esto asigna a a 0, b a 4, y rest a [1, 2, 3].

Comprensiones por diccionario: {k: v for k, v in cosas} significa lo mismo que dict(cosas), pero es más flexible. (Esto es PEP 274 [https://www.python.org/dev/peps/pep-0274] reivindicado. :-)

Asignar los literales, por ejemplo, {1, 2}. Tener en cuenta que {} es un diccionario vacío; utilizar set() para un conjunto vacío. También se admiten las comprensiones de conjunto; por ejemplo, x for x in cosas significa lo mismo que set(cosas), pero es más flexible.

Nuevos octales literales, por ejemplo, 0o720 (ya en 2.6). Los octales literales viejos (0720) se eliminaron.

Nuevos literales binarios, por ejemplo, 0b1010 (ya en 2.6), y hay una nueva función incorporada correspondiente, bin().

Los literales de bytes se introducen con un b o B delantero, y hay una nueva función incorporada correspondiente, bytes().

Sintaxis modificada

PEP 3109 [https://www.python.org/dev/peps/pep-3109] y PEP 3134 [https://www.python.org/dev/peps/pep-3134]: Nueva sintaxis de la instrucción raise: raise [expr [from expr]]. Ver a continuación.

as y with ahora son palabras reservadas. (Desde 2.6, de hecho.)

True, False y None son palabras reservadas. (2.6 parcialmente estableció restricciones ya en None.)

Cambio de except exc, var a except exc as var.Ver PEP 3110 [https://www.python.org/dev/peps/pep-3110].

PEP 3115 [https://www.python.org/dev/peps/pep-3115]: Nueva sintaxis de metaclase. En lugar de:

class C:
    __metaclass__ = M
    ...

ahora se debe usar:

class C(metaclass=M):
    ...

Ya no se admite la variable de módulo global __metaclass__. (Era una muleta para facilitar al valor predeterminado a las clases de estilo nuevo sin derivar todas las clases de object.)

Las listas por comprensión ya no admiten la forma sintáctica [... for var in item1, item2, ...]. Utilizar [... forvar in (item1, item2, ...)] en su lugar. También tener en cuenta que las listas por comprensión tienen semántica diferente: están más cerca del azúcar sintáctico para una expresión de generador dentro de un constructor list() y, en particular, las variables de control de bucle ya no se filtran en el ámbito circundante.

La elipsis (...) puede ser utilizada como una expresión atómica en cualquier lugar. (Previamente sólo estaba permitida en segmentos.) Asimismo, esto ahora debe ser escrito como .... (Anteriormente, también podía ser escrito como . . ., por un mero accidente de la gramática.)

Sintaxis eliminada

PEP 3113 [https://www.python.org/dev/peps/pep-3113]: Desempaque de parámetros de tupla eliminados. Ya no se puede escribir def foo(a, (b, c)): .... Utilizar def foo(a, b_c): b, c = b_c en su lugar.

Comillas invertidas eliminadas (usar repr() en su lugar).

Eliminados <> (usar != en su lugar).

Palabra clave eliminada: exec() ya no es una palabra clave; continúa siendo una función. (Afortunadamente la sintaxis de la función también era aceptada en 2.x.) Asimismo, nótese que la exec() ya no toma un argumento de flujo; en lugar de exec(f) se puede utilizar exec(f.read()).

Literales enteros no admiten más l o L finales.

Literales de cadena de caracteres no admiten más u or U iniciales.

La sintaxis from module import * solo se permite en el nivel de módulo, ya no dentro de las funciones.

La única sintaxis aceptable para imports relativos es from .[module] import name. Todos los formularios import que no comienzan con . son interpretados como imports absolutos

Se eliminaron las clases clásicas.

Cambios ya presentes en Python 2.6

Dado que es de suponer que muchos usuarios saltan directamente de Python 2.5 a Python 3.0, esta sección recuerda al lector nuevas características que se diseñaron originalmente para Python 3.0 pero que fueron llevadas hacia atrás a Python 2.6. Las secciones correspondientes en Qué hay de nuevo en Python 2.6 deberían ser consultadas para descripciones más largas.

PEP 343: La sentencia “with”.La declaración with ahora es una característica estándar y ya no necesita ser importada del __future__. También puede revisarse Escribiendo gestores de contexto y El módulo contextlib.

PEP 366: Importaciones relativas explícitas desde un módulo principal. Esto mejora la utilidad de opción -m cuando el módulo al que se hace referencia vive en un paquete.

PEP 370: Directorio de site-packages por usuario.

PEP 371: El paquete multiprocessing.

PEP 3101: Formateo avanzado de cadena de caracteres. Nota: la descripción 2.6 menciona el método format() tanto para cadenas de caracteres 8 bits como de Unicode. En 3.0, solo el tipo str (cadenas de texto con compatibilidad con Unicode) admite este método; el tipo bytes no. El plan es a la larga convertir esta en la única API para el formato de cadena de caracteres y comenzar a dejar de utilizar el operador % en Python 3.1.

PEP 3105: print As a Function. Esta ahora es una característica estándar y ya no necesita ser importada de __future__. Más detalles fueron dados anteriormente.

PEP 3110: Exception-Handling Changes. La sintaxis except exc as var ahora es estándar y except exc, var ya no es compatible. (Por supuesto, la parte as var sigue siendo opcional.)

PEP 3112: Byte Literals. La notación literal de cadena de caracteres b"..." (y sus variantes como b'...', b"""...""", y br"...") ahora genera un literal de tipo bytes.

PEP 3116: New I/O Library. El módulo io ahora es la forma estándar de hacer E/S de archivos. La función incorporada open() ahora es un alias para io.open() y tiene argumentos de palabra clave adicionales encoding, errors, newline y closefd. Tener en cuenta también que un argumento mode inválido ahora lanza ValueError, no IOError. Se puede acceder al objeto de archivo binario subyacente a un objeto de archivo de texto como f.buffer (pero tener en cuenta que el objeto de texto mantiene un búfer de sí mismo para acelerar las operaciones de codificación y descodificación).

PEP 3118: Revised Buffer Protocol. El antiguo buffer() incorporado ahora realmente se ha eliminado; el memoryview() incorporado nuevo proporciona (mayormente) una funcionalidad similar.

PEP 3119: Abstract Base Classes. El módulo abc y los ABC definidos en el módulo collections desempeñan un papel algo más destacado en el lenguaje ahora, y los tipos de colección incorporados como dict y list se ajustan a los ABCs de collections.MutableMapping y collections.MutableSequence, respectivamente.

PEP 3127: Integer Literal Support and Syntax. Como se mencionó anteriormente, la nueva notación literal octal es la única admitida y se han agregado literales binarios.

PEP 3129: Class Decorators.

PEP 3141: A Type Hierarchy for Numbers. El módulo numbers es otro uso nuevo de ABCs, definiendo la «torre numérica» de Python. También tener en cuenta el nuevo módulo fractions que implementa numbers.Rational.

Cambios de biblioteca

Debido a las limitaciones de tiempo, este documento no cubre exhaustivamente los muy extensos cambios en la biblioteca estándar. PEP 3108 [https://www.python.org/dev/peps/pep-3108] es la referencia para los principales cambios en la biblioteca. Aquí hay una revisión de cápsula:

Se eliminaron muchos módulos antiguos. Algunos, como gopherlib (ya no se usa) y md5 (reemplazado por hashlib), ya estaban en desuso por PEP 4 [https://www.python.org/dev/peps/pep-0004]. Otros fueron eliminados como resultado de la eliminación de soporte para varias plataformas como Irix, BeOS y Mac OS 9 (ver PEP 11 [https://www.python.org/dev/peps/pep-0011]). Algunos módulos también fueron seleccionados para su eliminación en Python 3.0 debido a la falta de uso o porque existe un mejor reemplazo. Consultar PEP 3108 [https://www.python.org/dev/peps/pep-3108] para obtener una lista exhaustiva.

El paquete bsddb3 fue eliminado porque su presencia en la biblioteca estándar principal ha demostrado con el tiempo ser una particular carga para los desarrolladores principales, debido a la inestabilidad de las pruebas y la programación del lanzamiento de Berkeley DB. Sin embargo, el paquete está vivo y bien, mantenido externamente en https://www.jcea.es/programacion/pybsddb.htm.

Algunos módulos fueron renombrados porque su antiguo nombre desobedeció PEP 8 [https://www.python.org/dev/peps/pep-0008], o por varias otras razones. Aquí está la lista:

Nombre anterior

Nombre nuevo

_winreg

winreg

ConfigParser

configparser

copy_reg

copyreg

Queue

queue

SocketServer

socketserver

markupbase

_markupbase

repr

reprlib

test.test_support

test.support

Un patrón común en Python 2.x es tener una versión de un módulo implementado en Python puro, con una versión acelerada opcional implementada como una extensión C; por ejemplo, pickle y cPickle. Esto coloca la carga de importar la versión acelerada y volver a caer en la versión de Python pura en cada usuario de estos módulos. En Python 3.0, las versiones aceleradas se consideran detalles de implementación de las versiones puras de Python. Los usuarios siempre deberían importar la versión estándar, que intenta importar la versión acelerada y vuelve a la versión de Python pura. El par pickle / cPickle recibió este tratamiento. El módulo profile está en la lista para 3.1. El módulo StringIO se ha convertido en una clase en el módulo io.

Algunos módulos relacionados se han agrupado en paquetes y, por lo general, los nombres de submódulo se han simplificado. Los nuevos paquetes resultantes son:

dbm (anydbm, dbhash, dbm, dumbdbm, gdbm, whichdb).

html (HTMLParser, htmlentitydefs).

http (httplib, BaseHTTPServer, CGIHTTPServer, SimpleHTTPServer, Cookie, cookielib).

tkinter (todos los módulos relacionados con Tkinter excepto turtle). Al público objetivo de turtle no le interesa realmente tkinter. También tener en cuenta que a partir de Python 2.6, la funcionalidad de turtle se ha mejorado considerablemente.

urllib (urllib, urllib2, urlparse, robotparse).

xmlrpc (xmlrpclib, DocXMLRPCServer, SimpleXMLRPCServer).

Algunos otros cambios a los módulos de la biblioteca estándar, no cubiertos por PEP 3108 [https://www.python.org/dev/peps/pep-3108]:

Quitado sets. Usar la clase incorporada set().

Limpiado el módulo sys: quitado sys.exitfunc(), sys.exc_clear(), sys.exc_type, sys.exc_value, sys.exc_traceback. (Notar que sys.last_type etc. permanece.)

Limpiado del tipo array.array: los métodos read() y write() ya no están; usar fromfile() y tofile() en su lugar. Asimismo, the el código de tipo 'c' para arreglo ya no está– utilizar o bien 'b' para bytes o 'u' para caracteres Unicode.

Limpieza del módulo operator: quitados sequenceIncludes() y isCallable().

Limpieza del módulo thread: acquire_lock() y release_lock() ya no están; utilizar acquire() y release() en su lugar.

Limpieza del módulo random: quitada la API jumpahead().

El módulo new ya no está.

Las funciones os.tmpnam(), os.tempnam() y os.tmpfile() se han eliminado en favor del módulo tempfile.

El módulo tokenize se ha cambiado para trabajar con bytes. El punto de entrada principal es ahora tokenize.tokenize(), en lugar de generate_tokens.

string.letters y sus amigos (string.lowercase and string.uppercase) han sido eliminadas. Utilizar string.ascii_letters etc. en su lugar. (La razón para la eliminación es que string.letters y sus amigos tenían un comportamiento específico de lugar, que es una mala idea para tales «constantes» nombradas atractivamente globales.)

Renombrado el módulo __builtin__ a builtins (quitando los guiones bajos, agregando una “s”). La variable __builtins__ encontrada en la mayoría de los espacios de nombres globales no tiene cambios. Para modificar un builtin, Se debería usar builtins, no __builtins__!

PEP 3101 [https://www.python.org/dev/peps/pep-3101]: Un nuevo enfoque al formateo de cadena de caracteres

Un nuevo sistema para operaciones de formateo de cadenas de caracteres incorporadas reemplaza el operador de formato de cadena de caracteres %. (De todas maneras, el operador % sigue siento soportado; será obsoleto en Python 3.1 y quitado del lenguaje en algún momento más adelante.) Leer PEP 3101 [https://www.python.org/dev/peps/pep-3101] para la primicia completa.

Cambios a excepciones

Las APIs para lanzar y capturar excepciones se limpiaron y se agregaron nuevas características poderosas:

PEP 352 [https://www.python.org/dev/peps/pep-0352]: Todas las excepciones deben derivarse (directa o indirectamente) de BaseException. Esta es la raíz de la jerarquía de excepciones. Esto no es nuevo como recomendación, pero el requisito de heredar de BaseException es nuevo. (Python 2.6 aún permitía que las clases clásicas se lanzaran, y no ponía ninguna restricción en lo que se podía capturar.) Como consecuencia, las excepciones de cadena de caracteres finalmente están verdaderamente y completamente muertas.

Casi todas las excepciones deberían de hecho derivarse de Exception; BaseException sólo debe utilizarse como clase base para las excepciones que solo deben controlarse en el nivel superior, como SystemExit o KeyboardInterrupt. El modismo recomendado para controlar todas las excepciones excepto esta última categoría es usar except Exception.

StandardError fue eliminado.

Las excepciones ya no se comportan como secuencias. Utilizar el atributo args en su lugar.

PEP 3109 [https://www.python.org/dev/peps/pep-3109]: Lanzando excepciones. Ahora se debe usar raise Exception(args) en lugar de raise Exception, args. Adicionalmente, ya no se puede especificar explícitamente un traceback; en su lugar, si se debe hacer esto, se puede asignar directamente al atributo __traceback__ (ver debajo).

PEP 3110 [https://www.python.org/dev/peps/pep-3110]: Atrapando excepciones. Ahora se debe usar except AlgunaExcepcion como variable en lugar de except AlgunaExcepcion, variable. Además, la variable es específicamente eliminada cuando el bloque except se deja.

PEP 3134 [https://www.python.org/dev/peps/pep-3134]: Encadenamiento de excepciones. Hay dos casos: encadenamiento implícito y encadenamiento explícito. El encadenamiento implícito se produce cuando se lanza una excepción en un bloque de controlador except o finally. Esto suele ocurrir debido a un error en el bloque de controlador; llamamos a esto una excepción secundaria. En este caso, la excepción original (que se estaba controlando) se guarda como el atributo __context__ de la excepción secundaria. El encadenamiento explícito se invoca con esta sintaxis:

raise SecondaryException() from primary_exception

(donde primary_exception es cualquier expresión que produce un objeto de excepción, probablemente una excepción que se detectó anteriormente). En este caso, la excepción principal se almacena en el atributo __cause__ de la excepción secundaria. El traceback impreso recorre la cadena de atributos __cause__ y __context__ cuando se produce una excepción no controlada e imprime un traceback independiente para cada componente de la cadena, con la excepción principal en la parte superior. (Los usuarios de Java pueden reconocer este comportamiento.)

PEP 3134 [https://www.python.org/dev/peps/pep-3134]: Los objetos de excepción ahora almacenan su traceback como el atributo __traceback__. Esto significa que un objeto de excepción ahora contiene toda la información relativa a una excepción y hay menos razones para usar sys.exc_info() (aunque este último no se quita).

Algunos mensajes de excepción se mejoraron cuando Windows falla al cargar un módulo de extensión. Por ejemplo, error code 193 ahora es %1 is not a valid Win32 application. Las cadenas de caracteres ahora tratan con configuraciones regionales no inglesas.

Otros cambios diversos

Operadores y métodos especiales

!= ahora retorna lo opuesto de ==, salvo que == retorne NotImplemented.

El concepto de «métodos independientes» fue quitado del lenguaje. Cuando se refiere a un método como atributo de clase, ahora se obtiene un objeto de función simple.

__getslice__(), __setslice__() y __delslice__() se quitaron. La sintaxis``a[i:j]`` ahora se traduce a a.__getitem__(slice(i, j)) (o __setitem__() o __delitem__(), cuando se utiliza como destino de asignación o eliminación, respectivamente).

PEP 3114 [https://www.python.org/dev/peps/pep-3114]: El método estándar next() se ha renombrado como __next__().

Los métodos especiales __oct__() y __hex__() se quitaron – oct() y hex() utilizan __index__() ahora para convertir el argumento a un entero.

Soporte eliminado para __members__ y __methods__.

Se ha cambiado el nombre de los atributos de función denominados func_X para utilizar el formulario __X__, liberando estos nombres en el espacio de nombres de atributo de función para los atributos definidos por el usuario. Es decir, func_closure, func_code, func_defaults, func_dict, func_doc, func_globals, func_name se renombraron a __closure__, __code__, __defaults__, __dict__, __doc__, __globals__, __name__, respectivamente.

__nonzero__() ahora es __bool__().

Incorporados

PEP 3135 [https://www.python.org/dev/peps/pep-3135]: Nuevo super(). Ahora se puede invocar super() sin argumentos y (suponiendo que se encuentra en un método de instancia normal definido dentro de una declaración class) se elegirá automáticamente la clase y la instancia correctas. Con argumentos, el comportamiento de super() no cambia.

PEP 3111 [https://www.python.org/dev/peps/pep-3111]: raw_input() se renombró a input(). Es decir, la nueva función input() lee una línea de sys.stdin y la retorna con la línea final despojada. Lanza EOFError si la entrada se termina prematuramente. Para obtener el comportamiento anterior de input(), utilice eval(input()).

Se añadió una nueva función incorporada next() para llamar al método __next__() sobre un objeto.

La estrategia de redondeo de la función round() y el tipo de retorno han cambiado. Los casos exactamente a mitad de camino ahora se redondean al resultado par más cercano en lugar de alejarse de cero. (Por ejemplo, round(2.5) ahora retorna “”2”” en lugar de 3.) round(x[, n]) ahora delega en x.__round__([n]) en lugar de retornar siempre un float. Por lo general, retorna un entero cuando se llama con un único argumento y un valor del mismo tipo que x cuando se llama con dos argumentos.

Se movió intern() a sys.intern().

Se eliminó: apply(). En lugar de apply(f, args) se utiliza f(*args).

Se eliminó callable(). En lugar de callable(f) se puede utilizar isinstance(f, collections.Callable). La función operator.isCallable() también se quitó.

Se eliminó coerce(). Esta función ya no sirve para nada ahora que las clases clásicas se han quitado.

Se eliminó execfile(). En lugar de execfile(fn) utilizar exec(open(fn).read()).

Se eliminó el tipo file. Se utiliza open(). Ahora hay varios tipos diferentes de secuencias que se abren y pueden retornar en el módulo io.

Se eliminó reduce(). Se puede utilizar functools.reduce() si es realmente necesario; de todas maneras, 99 por ciento del tiempo un bucle for explícito es más legible.

Se eliminó reload(). Se utiliza imp.reload().

Se eliminó dict.has_key() – se utiliza el operador in en su lugar.

Construcción y cambios a la API de C

Debido a restricciones de tiempo, aquí hay una muy incompleta lista de cambios a la API de C.

Se ha eliminado el soporte para varias plataformas, incluyendo pero no limitado a Mac OS 9, BeOS, RISCOS, Irix y Tru64.

PEP 3118 [https://www.python.org/dev/peps/pep-3118]: Nueva API de búfer.

PEP 3121 [https://www.python.org/dev/peps/pep-3121]: Inicialización y finalización de módulos de extensión.

PEP 3123 [https://www.python.org/dev/peps/pep-3123]: Haciendo PyObject_HEAD conforme al estándar C.

No más compatibilidad con API C para ejecución restringida.

Las API C PyNumber_Coerce(), PyNumber_CoerceEx(), PyMember_Get(), y PyMember_Set() se eliminan.

La nueva API C PyImport_ImportModuleNoBlock(), trabaja como PyImport_ImportModule() pero no bloqueará en el bloqueo de importación (en su lugar, retornará un error).

Se renombró la conversión booleana de ranura de nivel C y el método: nb_nonzero ahora es nb_bool.

Se eliminó METH_OLDARGS y WITH_CYCLE_GC de la API C.

Rendimiento

El resultado neto de las generalizaciones 3.0 es que Python 3.0 ejecuta el punto de referencia pystone alrededor de 10% más lenta que Python 2.5. Lo más probable es que la mayor causa sea la eliminación de mayúsculas y minúsculas especiales para enteros pequeños. Hay margen de mejora, ¡pero sucederá después de que se publique 3.0!

Migración a Python 3.0

Para migrar código Python 2.5 o 2.6 existente a Python 3.0, la mejor estrategia es la siguiente:

(Prerrequisito:) Comenzar con excelente cobertura de test.

Migrar a Python 2.6. Esto no debería representar más trabajo que la migración promedio de Python 2.x a Python 2.(x+1). Asegurarse que todos los test pasen.

(Todavía utilizando 2.6:) Activar el modificador de línea de comandos -3. Esto habilita las advertencias sobre las características que se eliminarán (o cambiarán) en 3.0. Ejecutar el conjunto de pruebas de nuevo y corregir el código sobre el que se recibe advertencias hasta que no queden advertencias y todas las pruebas sigan pasando.

Ejecutar el traductor de origen a origen 2to3 sobre el árbol de código fuente. (Consultar 2to3 - Traducción de código Python 2 a 3 para obtener más información sobre esta herramienta.) Ejecutar el resultado de la traducción en Python 3.0. Corregir manualmente los problemas restantes, solucionando problemas hasta que todos las pruebas vuelvan a pasar.

No se recomienda intentar escribir código fuente que se ejecute sin cambios en Python 2.6 y 3.0; se tendría que usar un estilo de codificación muy contorsionado, por ejemplo, evitando las sentencias print, metaclases y mucho más. Si se mantiene una biblioteca que necesita soportar Python 2.6 y Python 3.0, el mejor enfoque es modificar el paso 3 anterior editando la versión 2.6 del código fuente y ejecutando el traductor 2to3 de nuevo, en lugar de editar la versión 3.0 del código fuente.

Para migrar las extensiones C a Python 3.0, por favor ver Portar módulos de extensión a Python 3.

Qué hay de nuevo en Python 2.7

Autor

A.M. Kuchling (amk en amk.ca)

Este articulo explica las nuevas características en Python 2.7. Python 2.7 fue publicado el 3 de Julio de 2010.

El manejo numérico ha sido mejorado en muchas formas, tanto para los números de punto flotante como para la clase Decimal. Hay algunas adiciones útiles a la biblioteca estándar, como una gran mejora al modulo unittest, el modulo argparse para analizar las opciones de la línea de comandos, adecuando las clases OrderedDict y Counter en el modulo collections, y muchas otras mejoras.

Python 2.7 esta previsto que sea el ultimo lanzamiento de la serie 2.x, así que hemos trabajado para que sea una versión a largo plazo. Para ayudar con la migración a Python 3, se han incluido varias características nuevas de la serie Python 3.x en 2.7.

Este articulo no intenta proporcionar una especificación completa de las nuevas características, sino que proporciona una visión general conveniente. Para obtener mas información, debería consultar la documentación de Python 2.7 en https://docs.python.org. Si desea comprender la justificación para el diseño y la implementación, consultar el PEP para una nueva característica particular o el error en el que se discutió un cambio en https://bugs.python.org. Siempre que sea posible, «Que hay de nuevo en Python» enlaza el elemento error/parche para cada cambio.

El futuro de Python 2.x

Python 2.7 is the last major release in the 2.x series, as the Python maintainers have shifted the focus of their new feature development efforts to the Python 3.x series. This means that while Python 2 continues to receive bug fixes, and to be updated to build correctly on new hardware and versions of supported operated systems, there will be no new full feature releases for the language or standard library.

Sin embargo, si bien existe un gran subconjunto común entre Python 2.7 y Python 3, y muchos de los cambios involucrados en la migración a ese subconjunto común, o directamente a Python 3, se pueden automatizar de manera segura, algunos otros cambios (en particular los asociados con el manejo de Unicode) puede requerir una consideración cuidadosa, y preferiblemente conjuntos de pruebas de regresión automatizada robustos, para migrar de manera efectiva.

Esto significa que Python 2.7 permanecerá en su lugar durante un largo tiempo, proporcionando una plataforma base estable y compatible para sistemas de producción que aún no se han adaptado a Python 3. La expectativa completa del ciclo de vida de la versión de Python 2.7 esta detallada en PEP 373 [https://www.python.org/dev/peps/pep-0373].

Algunas consecuencias clave de la importancia a largo plazo de 2.7 son:

Como se señalo anteriormente, la versión 2.7 tiene un período de mantenimiento mucho más largo en comparación con las versiones anteriores 2.x. Actualmente se espera que Python 2.7 siga siendo compatible con el equipo de desarrollo central (recibiendo actualizaciones de seguridad y otras correcciones de errores) al menos hasta 2020 (10 años después de su lanzamiento inicial, comparado con el típico periodo de mantenimiento de 18–24 meses).

A medida que la biblioteca estándar de Python envejece, hacer un uso eficaz del índice de paquetes de Python (ya sea directamente o a través de un distribuidor) se vuelve mas importante para los usuarios de Python 2. Además de una amplia variedad de paquetes de terceros para diversas tareas, los paquetes disponibles incluyen backports de nuevos módulos y características de la biblioteca estándar de Python 3 que son compatibles con Python 2, así como varias herramientas y librerías que pueden hacer mas fácil la migración a Python 3. La Guía de usuario de paquetes de Python [https://packaging.python.org] proporciona un información sobre como descargar e instalar software desde el índice de paquetes de Python.

Aunque el enfoque preferido para mejorar Python 2 es ahora la publicación de nuevos paquetes en el índice de paquetes de Python, este enfoque no necesariamente funciona en todos los casos, especialmente aquellos relacionados a la seguridad de la red. En casos excepcionales que no puedan ser manejados adecuadamente mediante la publicación de nuevos paquetes o actualizaciones en PyPI, el proceso de propuestas de mejoras de Python podría ser usado para crear el caso para añadir nuevas funciones a la librería estándar de Python 2. Dichas adiciones, y las versiones de mantenimiento donde fueron agregadas, se observaran en la sección New Features Added to Python 2.7 Maintenance Releases mas abajo.

Para los proyectos que deseen migrar de Python 2 a Python 3, o para los desarrolladores de frameworks y libreras que deseen dar soporte a usuarios en Python 2 y Python 3, hay una variedad de herramientas y guías disponibles para ayudarles a decidir sobre un enfoque adecuado y manejar algunos de los detalles técnicos involucrados. El punto de partida recomendado es la guía HOWTO Portando código de Python 2 a Python 3.

Cambios en el manejo de las advertencias de desuso

Para Python 2.7, se tomo la decisión de silenciar las advertencias solo de interés para los desarrolladores de manera predeterminada. DeprecationWarning`y sus descendientes son ahora ignoradas a menos que se solicite lo contrario, impidiendo a los usuarios estar viendo las advertencias disparadas por una aplicación. Este cambio se realizo en la rama que se convirtió en Python 3.2. (Discutido en stdlib-sig y llevado a cabo en :issue:`7319).

En versiones previas, los mensajes DeprecationWarning estaban habilitados de manera predeterminada, proporcionando a los desarrolladores de Python una indicación clara de donde podría romperse su código en una futura versión principal de Python.

Sin embargo, cada vez hay más usuarios de aplicaciones basadas en Python que no están directamente involucrados en el desarrollo de esas aplicaciones. Los mensajes DeprecationWarning son irrelevantes para estos usuarios, hacen que se preocupen por una aplicación que realmente está funcionando correctamente y sobrecargando a los desarrolladores de aplicaciones con responder a estas preocupaciones.

Puede volver a habilitar la visualización de los mensajes DeprecationWarning ejecutando Python con el modificador -Wdefault (forma corta: -Wd), o estableciendo la variable de entorno PYTHONWARNINGS en "default" (o "d") antes de ejecutar Python. El código Python también puede volver a habilitarlos llamando a “”warnings.simplefilter(“default”)``.

El módulo unittest también vuelve a instalar automáticamente las advertencias de desuso al ejecutar pruebas.

Características de Python 3.1

Al igual que Python 2.6 incorporó características de Python 3.0, la versión 2.7 incorpora algunas de las nuevas características de Python 3.1. La serie 2.x continúa proporcionando herramientas para migrar a la serie 3.x.

Una lista parcial de características 3.1 que se retro importaron a 2.7:

La sintaxis para establecer literales ({1,2,3} es un conjunto mutable).

Diccionario y establecimiento de compresiones ({i: i*2 for i in range(3)}).

Múltiples administradores de contexto en una sola declaración with.

Una nueva versión para la librería io, rescrito en C para un mejor desempeño.

El tipo de ordenador de diccionario descrito en PEP 372: Adición de un diccionario ordenado a las colecciones.

El nuevo especificador de formato "," descrito en PEP 378: Especificador de formato para separador de miles.

El objeto memoryview.

Un pequeño subconjunto del modulo importlib, descrito abajo.

La repr() de un flotante x es más corto en muchos casos: ahora se basa en la cadena decimal más corta que se garantiza que redondea a x. Como en versiones anteriores de Python, se garantiza que float(repr(x)) devuelva x.

Las conversiones flotante a cadena y cadena a flotante se redondean correctamente. La función round() también ahora se redondea correctamente.

El tipo PyCapsule, utilizado para proporcionar una API de C para módulos de extensión.

La función de API de C PyLong_AsLongAndOverflow().

Otras nuevas advertencias en modo Python3 incluyen:

operator.isCallable() y operator.sequenceIncludes(), que no se admiten en 3.x, ahora activan advertencias.

El modificador -3 ahora habilita automáticamente el modificador -Qwarn que provoca advertencias sobre el uso de la división clásica con enteros y enteros largos.

PEP 372: Adición de un diccionario ordenado a las colecciones

Los diccionarios de python normales recorren en iteración los pares clave/valor en un orden arbitrario. A lo largo de los años, varios autores han escrito implementaciones alternativas que recuerdan el orden en que se insertaron originalmente las claves. Basado en las experiencias de esas implementaciones, 2.7 presenta una nueva clase OrderedDict en el módulo collections.

La API OrderedDict proporciona la misma interfaz que los diccionarios normales, pero recorre en iteración las claves y los valores en un orden garantizado en función de cuándo se insertó una clave por primera vez:

>>> from collections import OrderedDict
>>> d = OrderedDict([('first', 1),
...                  ('second', 2),
...                  ('third', 3)])
>>> d.items()
[('first', 1), ('second', 2), ('third', 3)]

Si una nueva entrada sobrescribe una entrada existente, la posición de inserción original no se modifica:

>>> d['second'] = 4
>>> d.items()
[('first', 1), ('second', 4), ('third', 3)]

Borrando una entrada y luego reinsertándola, moverá la misma al final:

>>> del d['second']
>>> d['second'] = 5
>>> d.items()
[('first', 1), ('third', 3), ('second', 5)]

El método popitem() tiene un argumento last opcional que por defecto esta en True (verdadero). Si last es verdadero, la ultima llave ingresada es regresada y eliminada; si es falso, se selecciona la llave más antigua:

>>> od = OrderedDict([(x,0) for x in range(20)])
>>> od.popitem()
(19, 0)
>>> od.popitem()
(18, 0)
>>> od.popitem(last=False)
(0, 0)
>>> od.popitem(last=False)
(1, 0)

La comparación de dos diccionarios ordenados comprueba tanto las claves como los valores, y requiere que el orden de inserción sea el mismo:

>>> od1 = OrderedDict([('first', 1),
...                    ('second', 2),
...                    ('third', 3)])
>>> od2 = OrderedDict([('third', 3),
...                    ('first', 1),
...                    ('second', 2)])
>>> od1 == od2
False
>>> # Move 'third' key to the end
>>> del od2['third']; od2['third'] = 3
>>> od1 == od2
True

Comparando a un OrderedDict con un diccionario normal ignora el orden de inserción y simplemente compara las llaves y los valores.

¿Cómo funciona OrderedDict? Mantiene una lista doblemente vinculada de claves, añadiendo nuevas claves a la lista a medida que se insertan. Un diccionario secundario asigna las claves a su nodo de lista correspondiente, por lo que la eliminación no tiene que recorrer toda la lista vinculada y, por lo tanto, sigue siendo O(1).

La biblioteca estándar ahora admite el uso de diccionarios ordenados en varios módulos.

El módulo ConfigParser los utiliza de forma predeterminada, lo que significa que los archivos de configuración ahora se pueden leer, modificar y volver a escribir en su orden original.

El método _asdict() para collections.namedtuple() ahora devuelve un diccionario ordenado con los valores que aparecen en el mismo orden que los índices de tupla subyacentes.

El módulo json de la clase constructor JSONDecoder se amplió con un parámetro object_pairs_hook para permitir que el descodificador compilara instancias OrderedDict. También se agregó compatibilidad con herramientas de terceros como PyYAML [http://pyyaml.org/].

Ver también

PEP 372 [https://www.python.org/dev/peps/pep-0372] - Adición de un diccionario ordenado a las collections

PEP escrito por Armin Ronacher y Raymond Hettinger; implementado por Raymond Hettinger.

PEP 378: Especificador de formato para separador de miles

Para que la salida del programa sea más legible, puede ser útil agregar separadores a números grandes, representándolos como 18,446,744,073,709,551,616 en lugar de 18446744073709551616.

La solución totalmente general para hacer esto es el módulo locale, que puede utilizar diferentes separadores («,» en América del Norte, «.» en Europa) y diferentes tamaños de agrupación, pero locale es complicado de usar y no es adecuado para aplicaciones multiproceso donde diferentes hilos están produciendo resultados para diferentes configuraciones regionales.

Por lo tanto, se ha añadido un mecanismo simple de agrupación de comas al mini-lenguaje utilizado por el método str.format(). Al dar formato a un número de punto flotante, simplemente incluya una coma entre el ancho y la precisión:

>>> '{:20,.2f}'.format(18446744073709551616.0)
'18,446,744,073,709,551,616.00'

Al dar formato a un entero, incluya la coma después del ancho:

>>> '{:20,d}'.format(18446744073709551616)
'18,446,744,073,709,551,616'

Este mecanismo no es adaptable en absoluto; Las comas siempre se utilizan como separador y la agrupación siempre está en grupos de tres dígitos. El mecanismo de formato de coma no es tan general como el módulo locale, pero es más fácil de usar.

Ver también

PEP 378 [https://www.python.org/dev/peps/pep-0378] - Especificador de formato para separador de miles

PEP escrito por Raymond Hettinger; implementado por Eric Smith.

PEP 389: El módulo argparse para el análisis de líneas de comando

El módulo argparse para analizar argumentos de línea de comandos se agregó como un reemplazo más potente para el módulo optparse.

Esto significa que Python ahora admite tres módulos diferentes para analizar argumentos de línea de comandos: getopt, optparse, y argparse. El módulo getopt se parece mucho a la función getopt() de la biblioteca C, por lo que sigue siendo útil si estás escribiendo un prototipo de Python que finalmente se reescribe en C. optparse se vuelve redundante, pero no hay planes para eliminarlo porque hay muchos scripts que todavía lo usan, y no hay una manera automatizada de actualizar estos scripts. (Hacer que la API argparse sea coherente con la interfaz de optparse fue discutido pero rechazado como demasiado desordenado y difícil.)

En resumen, si estás escribiendo un nuevo script y no necesitas preocuparte por la compatibilidad con versiones anteriores de Python, usa argparse en lugar de optparse.

Este es un ejemplo:

import argparse

parser = argparse.ArgumentParser(description='Command-line example.')

# Add optional switches
parser.add_argument('-v', action='store_true', dest='is_verbose',
                    help='produce verbose output')
parser.add_argument('-o', action='store', dest='output',
                    metavar='FILE',
                    help='direct output to FILE instead of stdout')
parser.add_argument('-C', action='store', type=int, dest='context',
                    metavar='NUM', default=0,
                    help='display NUM lines of added context')

# Allow any number of additional arguments.
parser.add_argument(nargs='*', action='store', dest='inputs',
                    help='input filenames (default is stdin)')

args = parser.parse_args()
print args.__dict__

A menos que lo reemplace, los modificadores -h y --help se agregan automáticamente, y producen una salida con formato ordenado:

-> ./python.exe argparse-example.py --help
usage: argparse-example.py [-h] [-v] [-o FILE] [-C NUM] [inputs [inputs ...]]

Command-line example.

positional arguments:
  inputs      input filenames (default is stdin)

optional arguments:
  -h, --help  show this help message and exit
  -v          produce verbose output
  -o FILE     direct output to FILE instead of stdout
  -C NUM      display NUM lines of added context

Al igual que con optparse, los modificadores y argumentos de línea de comandos se devuelven como un objeto con atributos denominados por los parámetros dest:

-> ./python.exe argparse-example.py -v
{'output': None,
 'is_verbose': True,
 'context': 0,
 'inputs': []}

-> ./python.exe argparse-example.py -v -o /tmp/output -C 4 file1 file2
{'output': '/tmp/output',
 'is_verbose': True,
 'context': 4,
 'inputs': ['file1', 'file2']}

argparse tiene una validación mucho más fantasiosa que optparse; puede especificar un número exacto de argumentos como un entero, 0 o más argumentos pasando '*', 1 o más pasando '+', o un argumento opcional con '?'. Un analizador de nivel superior puede contener sub analizadores para definir subcomandos que tienen diferentes conjuntos de modificadores, como en svn commit, svn checkout, etc. Puede especificar el tipo de un argumento como FileType, que abrirá automáticamente los archivos y entiende que '-' significa entrada o salida estándar.

Ver también

argparse documentación

La página de documentación del módulo argparse.

Actualizar el código de optparse

Parte de la documentación de Python, que describe cómo convertir código que usa optparse.

PEP 389 [https://www.python.org/dev/peps/pep-0389] - argparse - Nuevo módulo de análisis de línea de comandos

PEP escrito e implementado por Steven Bethard.

PEP 391: Configuración basada en diccionarios para el registro

El módulo logging es muy flexible; las aplicaciones pueden definir un árbol de subsistemas de registro, y cada registrador de este árbol puede filtrar ciertos mensajes, formatearlos de forma diferente y dirigir mensajes a un número variable de controladores.

Toda esta flexibilidad puede requerir mucha configuración. Puede escribir instrucciones Python para crear objetos y establecer sus propiedades, pero una configuración compleja requiere código detallado pero aburrido. logging también es compatible con una función fileConfig() que analiza un archivo, pero el formato de archivo no admite la configuración de filtros, y es más complicado generar mediante programación.

Python 2.7 agrega una función dictConfig() que utiliza un diccionario para configurar el registro. Hay muchas maneras de producir un diccionario de diferentes fuentes: construir uno con código; analizar un archivo que contenga JSON; o utilice una biblioteca de análisis YAML si hay una instalada. Para obtener más información, consulte Funciones de configuración.

En el ejemplo siguiente se configuran dos registradores, el registrador raíz y un registrador denominado «network». Los mensajes enviados al registrador raíz se enviarán al registro del sistema mediante el protocolo syslog, y los mensajes al registrador de la «network» se escribirán en un archivo network.log que se rotará una vez que el registro alcance 1MB.

import logging
import logging.config

configdict = {
 'version': 1,    # Configuration schema in use; must be 1 for now
 'formatters': {
     'standard': {
         'format': ('%(asctime)s %(name)-15s '
                    '%(levelname)-8s %(message)s')}},

 'handlers': {'netlog': {'backupCount': 10,
                     'class': 'logging.handlers.RotatingFileHandler',
                     'filename': '/logs/network.log',
                     'formatter': 'standard',
                     'level': 'INFO',
                     'maxBytes': 1000000},
              'syslog': {'class': 'logging.handlers.SysLogHandler',
                         'formatter': 'standard',
                         'level': 'ERROR'}},

 # Specify all the subordinate loggers
 'loggers': {
             'network': {
                         'handlers': ['netlog']
             }
 },
 # Specify properties of the root logger
 'root': {
          'handlers': ['syslog']
 },
}

# Set up configuration
logging.config.dictConfig(configdict)

# As an example, log two error messages
logger = logging.getLogger('/')
logger.error('Database not found')

netlogger = logging.getLogger('network')
netlogger.error('Connection failed')

Tres mejoras más pequeñas en el módulo logging, todas implementadas por Vinay Sajip, son:

La clase SysLogHandler ahora admite syslogging a través de TCP. El constructor tiene un parámetro socktype que proporciona el tipo de socket que se va a usar, ya sea socket.SOCK_DGRAM para UDP o socket.SOCK_STREAM para TCP. El protocolo predeterminado sigue siendo UDP.

Las instancias Logger ganaron un método getChild() que recupera un registrador descendiente mediante una ruta de acceso relativa. Por ejemplo, una vez que se recupera un registrador haciendo log = getLogger('app'), llamando log.getChild('network.listen') es equivalente a getLogger('app.network.listen').

La clase LoggerAdapter gano un método isEnabledFor() que toma un nivel y devuelve si el registrador subyacente procesará un mensaje de ese nivel de importancia.

Ver también

PEP 391 [https://www.python.org/dev/peps/pep-0391] - Configuración basada en diccionarios para el registro

PEP escrito e implementado por Vinay Sajip.

PEP 3106: Vistas de diccionario

Los métodos de diccionarios keys(), values() y items() son diferentes en Python 3.x. Ellos regresan un objeto llamado view en lugar de una lista completamente materializada.

No es posible cambiar el retorno de valores de los métodos keys(), values() y items() en Python 2.7 porque se rompería demasiado código. En su lugar en las versiones 3.x se fueron agregando bajo los nuevos nombres viewkeys(), viewvalues() y viewitems().

>>> d = dict((i*10, chr(65+i)) for i in range(26))
>>> d
{0: 'A', 130: 'N', 10: 'B', 140: 'O', 20: ..., 250: 'Z'}
>>> d.viewkeys()
dict_keys([0, 130, 10, 140, 20, 150, 30, ..., 250])

Las vistas se pueden iterar, pero las vistas de elementos y claves también se comportan como conjuntos. El operador & realiza la intersección y | realiza una unión:

>>> d1 = dict((i*10, chr(65+i)) for i in range(26))
>>> d2 = dict((i**.5, i) for i in range(1000))
>>> d1.viewkeys() & d2.viewkeys()
set([0.0, 10.0, 20.0, 30.0])
>>> d1.viewkeys() | range(0, 30)
set([0, 1, 130, 3, 4, 5, 6, ..., 120, 250])

La vista realiza un seguimiento del diccionario y su contenido cambia a medida que se modifica el diccionario:

>>> vk = d.viewkeys()
>>> vk
dict_keys([0, 130, 10, ..., 250])
>>> d[260] = '&'
>>> vk
dict_keys([0, 130, 260, 10, ..., 250])

Sin embargo, tenga en cuenta que no puede agregar o eliminar claves mientras está iterando sobre la vista:

>>> for k in vk:
...     d[k*2] = k
...
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
RuntimeError: dictionary changed size during iteration

Puede usar los métodos de vista en el código en Python 2.x, y el convertidor 2to3 los cambiará a los métodos estándar keys(), values() y items().

Ver también

PEP 3106 [https://www.python.org/dev/peps/pep-3106] - Renovación dict.keys(), .values() y .items()

PEP escrito por Guido van Rossum. Portado a 2.7 por Alexandre Vassalotti; bpo-1967 [https://bugs.python.org/issue?@action=redirect&bpo=1967].

PEP 3137: El objeto memoryview

El objeto memoryview proporciona una vista del contenido de la memoria de otro objeto que coincide con la interfaz de tipo bytes.

>>> import string
>>> m = memoryview(string.letters)
>>> m
<memory at 0x37f850>
>>> len(m)           # Returns length of underlying object
52
>>> m[0], m[25], m[26]   # Indexing returns one byte
('a', 'z', 'A')
>>> m2 = m[0:26]         # Slicing returns another memoryview
>>> m2
<memory at 0x37f080>

El contenido de la vista se puede convertir en una cadena de bytes o una lista de números enteros:

>>> m2.tobytes()
'abcdefghijklmnopqrstuvwxyz'
>>> m2.tolist()
[97, 98, 99, 100, 101, 102, 103, ... 121, 122]
>>>

Los objetos memoryview permiten modificar el objeto subyacente si es un objeto mutable.

>>> m2[0] = 75
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: cannot modify read-only memory
>>> b = bytearray(string.letters)  # Creating a mutable object
>>> b
bytearray(b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ')
>>> mb = memoryview(b)
>>> mb[0] = '*'         # Assign to view, changing the bytearray.
>>> b[0:5]              # The bytearray has been changed.
bytearray(b'*bcde')
>>>

Ver también

PEP 3137 [https://www.python.org/dev/peps/pep-3137] - Bytes inmutables y búfer mutable

PEP escrito por Guido van Rossum. Implementado por Travis Oliphant, Antoine Pitrou y otros. Portado a 2.7 por Antoine Pitrou; bpo-2396 [https://bugs.python.org/issue?@action=redirect&bpo=2396].

Otros cambios de lenguaje

Algunos de los cambios mas pequeños hechos al núcleo del lenguaje de Python son:

La sintaxis para literales de conjuntos se ha actualizado desde Python 3.x. Los corchetes se utilizan para rodear el contenido del conjunto mutable resultante; los literales de conjunto se distinguen de los diccionarios por no contener dos puntos ni valores. {} sigue representando un diccionario vacío; use set() para un conjunto vacío.

>>> {1, 2, 3, 4, 5}
set([1, 2, 3, 4, 5])
>>> set() # empty set
set([])
>>> {}    # empty dict
{}

Portado por Alexandre Vassalotti; bpo-2335 [https://bugs.python.org/issue?@action=redirect&bpo=2335].

El diccionario y las comprensiones de conjuntos son otra característica portada desde 3.x, que generaliza las comprensiones de listas / generadores para usar la sintaxis literal para conjuntos y diccionarios.

>>> {x: x*x for x in range(6)}
{0: 0, 1: 1, 2: 4, 3: 9, 4: 16, 5: 25}
>>> {('a'*x) for x in range(6)}
set(['', 'a', 'aa', 'aaa', 'aaaa', 'aaaaa'])

Portado por Alexandre Vassalotti; bpo-2333 [https://bugs.python.org/issue?@action=redirect&bpo=2333].

La declaración with ahora puede usar múltiples administradores de contexto en una declaración. Los administradores de contexto se procesan de izquierda a derecha y cada uno se trata como si comenzara una nueva declaración with. Esto significa que:

with A() as a, B() as b:
    ... suite of statements ...

es equivalente a:

with A() as a:
    with B() as b:
        ... suite of statements ...

La función contextlib.nested() provee una función muy similar, por lo que ya no es necesario y ha quedado obsoleto.

(Propuesta en https://codereview.appspot.com/53094; implementado por Georg Brandl.)

Las conversiones entre números de punto flotante y cadenas ahora se redondean correctamente en la mayoría de las plataformas. Estas conversiones ocurren en muchos lugares diferentes: str() en flotantes y números complejos; los constructores float y complex; formato numérico; serializar y deserializar flotantes y números complejos usando los módulos marshal, pickle y json; análisis de literales flotantes e imaginarios en código Python; y conversión Decimal a flotante.

Relacionado con esto, el repr() de un número de punto flotante x ahora devuelve un resultado basado en la cadena decimal más corta que se garantiza que se redondeará a x con el redondeo correcto (con el modo de redondeo round-half-to-even). Anteriormente, daba una cadena basada en redondear x a 17 dígitos decimales.

La biblioteca de redondeo responsable de esta mejora funciona en Windows y en plataformas Unix utilizando los compiladores gcc, icc o suncc. Puede haber un pequeño número de plataformas donde no se puede garantizar el correcto funcionamiento de este código, por lo que el código no se utiliza en dichos sistemas. Puede averiguar qué código se está utilizando marcando sys.float_repr_style, que será short si el nuevo código está en uso y legacy si no lo está.

Implementado por Eric Smith y Mark Dickinson, utilizando la biblioteca de David Gay’s dtoa.c; bpo-7117 [https://bugs.python.org/issue?@action=redirect&bpo=7117].

Las conversiones de enteros largos y enteros normales a punto flotante ahora redondean de forma diferente, devolviendo el número de punto flotante más cercano al número. Esto no importa para los enteros pequeños que se pueden convertir exactamente, pero para los números grandes que inevitablemente perderán precisión, Python 2.7 ahora se aproxima más de cerca. Por ejemplo, Python 2.6 calculó lo siguiente:

>>> n = 295147905179352891391
>>> float(n)
2.9514790517935283e+20
>>> n - long(float(n))
65535L

El resultado de punto flotante de Python 2.7 es mayor, pero mucho más cerca del valor verdadero:

>>> n = 295147905179352891391
>>> float(n)
2.9514790517935289e+20
>>> n - long(float(n))
-1L

(Implementado por Mark Dickinson; bpo-3166 [https://bugs.python.org/issue?@action=redirect&bpo=3166].)

La división de enteros también es más precisa en sus comportamientos de redondeo. (También implementado por Mark Dickinson; bpo-1811 [https://bugs.python.org/issue?@action=redirect&bpo=1811].)

Se ha eliminado la coerción implícita para números complejos; el intérprete ya no intentará llamar a un método __coerce__() en objetos complejos. (Eliminado por Meador Inge y Mark Dickinson; bpo-5211 [https://bugs.python.org/issue?@action=redirect&bpo=5211].)

El método str.format() ahora admite la numeración automática de los campos de reemplazo. Esto hace que el uso de str.format() se parezca más al uso del formato %s:

>>> '{}:{}:{}'.format(2009, 04, 'Sunday')
'2009:4:Sunday'
>>> '{}:{}:{day}'.format(2009, 4, day='Sunday')
'2009:4:Sunday'

La numeración automática toma los campos de izquierda a derecha, por lo que el primer especificador {...} usará el primer argumento a str.format(), el siguiente especificador usará el siguiente argumento, y así sucesivamente. No puede mezclar la numeración automática y la numeración explícita – o numeran todos los campos especificados o ninguno de ellos – pero puede mezclar la numeración automática y los campos con nombre, como en el segundo ejemplo anterior. (Contribuido por Eric Smith; bpo-5237 [https://bugs.python.org/issue?@action=redirect&bpo=5237].)

Los números complejos ahora admiten correctamente el uso con format() y, por defecto, están alineados a la derecha. Especificar una precisión o separación de comas se aplica a las partes reales e imaginarias del número, pero un ancho de campo y una alineación especificados se aplica a la totalidad de la salida “”1.5+3j”” resultante. (Contribuido por Eric Smith; bpo-1588 [https://bugs.python.org/issue?@action=redirect&bpo=1588] y bpo-7988 [https://bugs.python.org/issue?@action=redirect&bpo=7988].)

El código de formato “F” ahora siempre da formato a su salida utilizando caracteres en mayúsculas, por lo que ahora producirá “INF” y “NAN”. (Contribuido por Eric Smith; bpo-3382 [https://bugs.python.org/issue?@action=redirect&bpo=3382].)

Un cambio de bajo nivel: el método object.__format__() ahora desencadena un PendingDeprecationWarning si se pasa una cadena de formato, porque el método __format__() para object convierte el objeto en una representación de cadena y da formato a eso. Anteriormente, el método aplicaba silenciosamente la cadena de formato a la representación de cadena, pero eso podía ocultar errores en el código de Python. Si proporciona información de formato, como una alineación o una precisión, presumiblemente espera que el formato se aplique de alguna manera específica del objeto. (Arreglado por Eric Smith; bpo-7994 [https://bugs.python.org/issue?@action=redirect&bpo=7994].)

Los tipos int() y long() obtuvieron un método bit_length que devuelve el número de bits necesarios para representar su argumento en binario:

>>> n = 37
>>> bin(n)
'0b100101'
>>> n.bit_length()
6
>>> n = 2**123-1
>>> n.bit_length()
123
>>> (n+1).bit_length()
124

(Contribuido por Fredrik Johansson y Victor Stinner; bpo-3439 [https://bugs.python.org/issue?@action=redirect&bpo=3439].)

La instrucción import ya no intentará una importación absoluta si se produce un error en una importación relativa (por ejemplo, from .os import sep). Esto corrige un error, pero posiblemente podría romper ciertas instrucciones import que solo funcionaban por accidente. (Arreglado por Meador Inge; bpo-7902 [https://bugs.python.org/issue?@action=redirect&bpo=7902].)

Ahora es posible que una subclase del tipo integrado unicode reemplace el método __unicode__(). (Implementado por Victor Stinner; bpo-1583863 [https://bugs.python.org/issue?@action=redirect&bpo=1583863].)

El método translate() del tipo bytearray ahora acepta None como su primer argumento. (Arreglado por Georg Brandl; bpo-4759 [https://bugs.python.org/issue?@action=redirect&bpo=4759].)

Cuando se usa @classmethod y @staticmethod para envolver métodos como clase o métodos estáticos, el objeto decorador ahora expone la función decoradora como su atributo __func__. (Contribuido por Amaury Forgeot d’Arc, después de una sugerencia de George Sakkis; bpo-5982 [https://bugs.python.org/issue?@action=redirect&bpo=5982].)

Cuando se estableció un conjunto restringido de atributos mediante __slots__, eliminar un atributo desarmado no llamaría AttributeError como cabría esperar. Corregido por Benjamin Peterson; bpo-7604 [https://bugs.python.org/issue?@action=redirect&bpo=7604].)

Ahora se admiten dos nuevas codificaciones: «cp720», que se utiliza principalmente para texto árabe; y «cp858», una variante de CP 850 que añade el símbolo del euro. (CP720 contribuido por Alexander Belchenko y Amaury Forgeot d’Arc en bpo-1616979 [https://bugs.python.org/issue?@action=redirect&bpo=1616979]; CP858 contribuido por Tim Hatch en bpo-8016 [https://bugs.python.org/issue?@action=redirect&bpo=8016].)

El objeto file ahora establecerá el atributo filename en la excepción IOError al intentar abrir un directorio en plataformas POSIX (señalada por Jan Kaliszewski; bpo-4764 [https://bugs.python.org/issue?@action=redirect&bpo=4764]), y ahora comprueba explícitamente y prohíbe escribir en objetos de archivo de solo lectura en lugar de confiar en la biblioteca C para detectar e informar del error (arreglado por Stefan Krah; bpo-5677 [https://bugs.python.org/issue?@action=redirect&bpo=5677]).

El tokenizador de Python ahora traduce las terminaciones de línea por sí mismo, por lo que la función integrada compile() ahora acepta código mediante cualquier convención de fin de línea. Además, ya no requiere que el código finalice en una nueva línea.

Los paréntesis adicionales en las definiciones de función son ilegales en Python 3.x, lo que significa que se obtiene un error de sintaxis de def f((x)): pass. En el modo de advertencia Python3, Python 2.7 ahora advertirá sobre este uso no común. (Anotado por James Lingard; :issue:”7362”.)

Ahora es posible crear referencias débiles a objetos de clase de estilo antiguo. Las clases de estilo nuevo siempre eran de referencia débil. (Corregido por Antoine Pitrou; bpo-8268 [https://bugs.python.org/issue?@action=redirect&bpo=8268].)

Cuando se recicla un objeto de módulo, el diccionario del módulo ahora solo se borra si nadie más tiene una referencia al diccionario (bpo-7140 [https://bugs.python.org/issue?@action=redirect&bpo=7140]).

Cambios en el intérprete

Una nueva variable de entorno, PYTHONWARNINGS, permite controlar las advertencias. Debe establecerse en una cadena que contenga la configuración de advertencia, equivalente a las utilizadas con el modificador -W, separado por comas. (Contribuido por Brian Curtin; bpo-7301 [https://bugs.python.org/issue?@action=redirect&bpo=7301].)

Por ejemplo, la siguiente configuración imprimirá advertencias cada vez que se produzcan, pero convertirá las advertencias del módulo Cookie en un error. (La sintaxis exacta para establecer una variable de entorno varía entre sistemas operativos y vaciados.)

export PYTHONWARNINGS=all,error:::Cookie:0

Optimizaciones

Se han añadido varias mejoras de rendimiento:

Se agregó un nuevo código de operación para realizar la configuración inicial de las instrucciones with, buscando los métodos __enter__() y __exit__(). (Contribución de Benjamin Peterson.)

El recolector de elementos no utilizados ahora funciona mejor para un patrón de uso común: cuando se asignan muchos objetos sin desasignar ninguno de ellos. Esto anteriormente tomaría tiempo cuadrático para la recolección de elementos no utilizados, pero ahora el número de colecciones de elementos no utilizados completas se reduce a medida que crece el número de objetos en el montón. La nueva lógica solo realiza un paso completo de recolección de elementos no utilizados cuando la generación media se ha recopilado 10 veces y cuando el número de objetos supervivientes de la generación media supera el 10% del número de objetos de la generación más antigua. (Sugerido por Martin von Löwis e implementado por Antoine Pitrou; bpo-4074 [https://bugs.python.org/issue?@action=redirect&bpo=4074].)

The garbage collector tries to avoid tracking simple containers which can’t be part of a cycle. In Python 2.7, this is now true for tuples and dicts containing atomic types (such as ints, strings, etc.). Transitively, a dict containing tuples of atomic types won’t be tracked either. This helps reduce the cost of each garbage collection by decreasing the number of objects to be considered and traversed by the collector. (Contributed by Antoine Pitrou; bpo-4688 [https://bugs.python.org/issue?@action=redirect&bpo=4688].)

Long integers are now stored internally either in base 2**15 or in base 2**30, the base being determined at build time. Previously, they were always stored in base 2**15. Using base 2**30 gives significant performance improvements on 64-bit machines, but benchmark results on 32-bit machines have been mixed. Therefore, the default is to use base 2**30 on 64-bit machines and base 2**15 on 32-bit machines; on Unix, there’s a new configure option --enable-big-digits that can be used to override this default.

Apart from the performance improvements this change should be invisible to end users, with one exception: for testing and debugging purposes there’s a new structseq sys.long_info that provides information about the internal format, giving the number of bits per digit and the size in bytes of the C type used to store each digit:

>>> import sys
>>> sys.long_info
sys.long_info(bits_per_digit=30, sizeof_digit=4)

(Contributed by Mark Dickinson; bpo-4258 [https://bugs.python.org/issue?@action=redirect&bpo=4258].)

Another set of changes made long objects a few bytes smaller: 2 bytes smaller on 32-bit systems and 6 bytes on 64-bit. (Contributed by Mark Dickinson; bpo-5260 [https://bugs.python.org/issue?@action=redirect&bpo=5260].)

The division algorithm for long integers has been made faster by tightening the inner loop, doing shifts instead of multiplications, and fixing an unnecessary extra iteration. Various benchmarks show speedups of between 50% and 150% for long integer divisions and modulo operations. (Contributed by Mark Dickinson; bpo-5512 [https://bugs.python.org/issue?@action=redirect&bpo=5512].) Bitwise operations are also significantly faster (initial patch by Gregory Smith; bpo-1087418 [https://bugs.python.org/issue?@action=redirect&bpo=1087418]).

The implementation of % checks for the left-side operand being a Python string and special-cases it; this results in a 1–3% performance increase for applications that frequently use % with strings, such as templating libraries. (Implemented by Collin Winter; bpo-5176 [https://bugs.python.org/issue?@action=redirect&bpo=5176].)

List comprehensions with an if condition are compiled into faster bytecode. (Patch by Antoine Pitrou, back-ported to 2.7 by Jeffrey Yasskin; bpo-4715 [https://bugs.python.org/issue?@action=redirect&bpo=4715].)

Converting an integer or long integer to a decimal string was made faster by special-casing base 10 instead of using a generalized conversion function that supports arbitrary bases. (Patch by Gawain Bolton; bpo-6713 [https://bugs.python.org/issue?@action=redirect&bpo=6713].)

The split(), replace(), rindex(), rpartition(), and rsplit() methods of string-like types (strings, Unicode strings, and bytearray objects) now use a fast reverse-search algorithm instead of a character-by-character scan. This is sometimes faster by a factor of 10. (Added by Florent Xicluna; bpo-7462 [https://bugs.python.org/issue?@action=redirect&bpo=7462] and bpo-7622 [https://bugs.python.org/issue?@action=redirect&bpo=7622].)

The pickle and cPickle modules now automatically intern the strings used for attribute names, reducing memory usage of the objects resulting from unpickling. (Contributed by Jake McGuire; bpo-5084 [https://bugs.python.org/issue?@action=redirect&bpo=5084].)

The cPickle module now special-cases dictionaries, nearly halving the time required to pickle them. (Contributed by Collin Winter; bpo-5670 [https://bugs.python.org/issue?@action=redirect&bpo=5670].)

New and Improved Modules

As in every release, Python’s standard library received a number of enhancements and bug fixes. Here’s a partial list of the most notable changes, sorted alphabetically by module name. Consult the Misc/NEWS file in the source tree for a more complete list of changes, or look through the Subversion logs for all the details.

The bdb module’s base debugging class Bdb gained a feature for skipping modules. The constructor now takes an iterable containing glob-style patterns such as django.*; the debugger will not step into stack frames from a module that matches one of these patterns. (Contributed by Maru Newby after a suggestion by Senthil Kumaran; bpo-5142 [https://bugs.python.org/issue?@action=redirect&bpo=5142].)

The binascii module now supports the buffer API, so it can be used with memoryview instances and other similar buffer objects. (Backported from 3.x by Florent Xicluna; bpo-7703 [https://bugs.python.org/issue?@action=redirect&bpo=7703].)

Updated module: the bsddb module has been updated from 4.7.2devel9 to version 4.8.4 of the pybsddb package [https://www.jcea.es/programacion/pybsddb.htm]. The new version features better Python 3.x compatibility, various bug fixes, and adds several new BerkeleyDB flags and methods. (Updated by Jesús Cea Avión; bpo-8156 [https://bugs.python.org/issue?@action=redirect&bpo=8156]. The pybsddb changelog can be read at http://hg.jcea.es/pybsddb/file/tip/ChangeLog.)

The bz2 module’s BZ2File now supports the context management protocol, so you can write with bz2.BZ2File(...) as f:. (Contributed by Hagen Fürstenau; bpo-3860 [https://bugs.python.org/issue?@action=redirect&bpo=3860].)

New class: the Counter class in the collections module is useful for tallying data. Counter instances behave mostly like dictionaries but return zero for missing keys instead of raising a KeyError:

>>> from collections import Counter
>>> c = Counter()
>>> for letter in 'here is a sample of english text':
...   c[letter] += 1
...
>>> c
Counter({' ': 6, 'e': 5, 's': 3, 'a': 2, 'i': 2, 'h': 2,
'l': 2, 't': 2, 'g': 1, 'f': 1, 'm': 1, 'o': 1, 'n': 1,
'p': 1, 'r': 1, 'x': 1})
>>> c['e']
5
>>> c['z']
0

There are three additional Counter methods. most_common() returns the N most common elements and their counts. elements() returns an iterator over the contained elements, repeating each element as many times as its count. subtract() takes an iterable and subtracts one for each element instead of adding; if the argument is a dictionary or another Counter, the counts are subtracted.

>>> c.most_common(5)
[(' ', 6), ('e', 5), ('s', 3), ('a', 2), ('i', 2)]
>>> c.elements() ->
   'a', 'a', ' ', ' ', ' ', ' ', ' ', ' ',
   'e', 'e', 'e', 'e', 'e', 'g', 'f', 'i', 'i',
   'h', 'h', 'm', 'l', 'l', 'o', 'n', 'p', 's',
   's', 's', 'r', 't', 't', 'x'
>>> c['e']
5
>>> c.subtract('very heavy on the letter e')
>>> c['e']    # Count is now lower
-1

Contributed by Raymond Hettinger; bpo-1696199 [https://bugs.python.org/issue?@action=redirect&bpo=1696199].

New class: OrderedDict is described in the earlier section PEP 372: Adición de un diccionario ordenado a las colecciones.

New method: The deque data type now has a count() method that returns the number of contained elements equal to the supplied argument x, and a reverse() method that reverses the elements of the deque in-place. deque also exposes its maximum length as the read-only maxlen attribute. (Both features added by Raymond Hettinger.)

The namedtuple class now has an optional rename parameter. If rename is true, field names that are invalid because they’ve been repeated or aren’t legal Python identifiers will be renamed to legal names that are derived from the field’s position within the list of fields:

>>> from collections import namedtuple
>>> T = namedtuple('T', ['field1', '$illegal', 'for', 'field2'], rename=True)
>>> T._fields
('field1', '_1', '_2', 'field2')

(Added by Raymond Hettinger; bpo-1818 [https://bugs.python.org/issue?@action=redirect&bpo=1818].)

Finally, the Mapping abstract base class now returns NotImplemented if a mapping is compared to another type that isn’t a Mapping. (Fixed by Daniel Stutzbach; bpo-8729 [https://bugs.python.org/issue?@action=redirect&bpo=8729].)

Constructors for the parsing classes in the ConfigParser module now take an allow_no_value parameter, defaulting to false; if true, options without values will be allowed. For example:

>>> import ConfigParser, StringIO
>>> sample_config = """
... [mysqld]
... user = mysql
... pid-file = /var/run/mysqld/mysqld.pid
... skip-bdb
... """
>>> config = ConfigParser.RawConfigParser(allow_no_value=True)
>>> config.readfp(StringIO.StringIO(sample_config))
>>> config.get('mysqld', 'user')
'mysql'
>>> print config.get('mysqld', 'skip-bdb')
None
>>> print config.get('mysqld', 'unknown')
Traceback (most recent call last):
  ...
NoOptionError: No option 'unknown' in section: 'mysqld'

(Contributed by Mats Kindahl; bpo-7005 [https://bugs.python.org/issue?@action=redirect&bpo=7005].)

Deprecated function: contextlib.nested(), which allows handling more than one context manager with a single with statement, has been deprecated, because the with statement now supports multiple context managers.

The cookielib module now ignores cookies that have an invalid version field, one that doesn’t contain an integer value. (Fixed by John J. Lee; bpo-3924 [https://bugs.python.org/issue?@action=redirect&bpo=3924].)

The copy module’s deepcopy() function will now correctly copy bound instance methods. (Implemented by Robert Collins; bpo-1515 [https://bugs.python.org/issue?@action=redirect&bpo=1515].)

The ctypes module now always converts None to a C NULL pointer for arguments declared as pointers. (Changed by Thomas Heller; bpo-4606 [https://bugs.python.org/issue?@action=redirect&bpo=4606].) The underlying libffi library [https://sourceware.org/libffi/] has been updated to version 3.0.9, containing various fixes for different platforms. (Updated by Matthias Klose; bpo-8142 [https://bugs.python.org/issue?@action=redirect&bpo=8142].)

New method: the datetime module’s timedelta class gained a total_seconds() method that returns the number of seconds in the duration. (Contributed by Brian Quinlan; bpo-5788 [https://bugs.python.org/issue?@action=redirect&bpo=5788].)

New method: the Decimal class gained a from_float() class method that performs an exact conversion of a floating-point number to a Decimal. This exact conversion strives for the closest decimal approximation to the floating-point representation’s value; the resulting decimal value will therefore still include the inaccuracy, if any. For example, Decimal.from_float(0.1) returns Decimal('0.1000000000000000055511151231257827021181583404541015625'). (Implemented by Raymond Hettinger; bpo-4796 [https://bugs.python.org/issue?@action=redirect&bpo=4796].)

Comparing instances of Decimal with floating-point numbers now produces sensible results based on the numeric values of the operands. Previously such comparisons would fall back to Python’s default rules for comparing objects, which produced arbitrary results based on their type. Note that you still cannot combine Decimal and floating-point in other operations such as addition, since you should be explicitly choosing how to convert between float and Decimal. (Fixed by Mark Dickinson; bpo-2531 [https://bugs.python.org/issue?@action=redirect&bpo=2531].)

The constructor for Decimal now accepts floating-point numbers (added by Raymond Hettinger; bpo-8257 [https://bugs.python.org/issue?@action=redirect&bpo=8257]) and non-European Unicode characters such as Arabic-Indic digits (contributed by Mark Dickinson; bpo-6595 [https://bugs.python.org/issue?@action=redirect&bpo=6595]).

Most of the methods of the Context class now accept integers as well as Decimal instances; the only exceptions are the canonical() and is_canonical() methods. (Patch by Juan José Conti; bpo-7633 [https://bugs.python.org/issue?@action=redirect&bpo=7633].)

When using Decimal instances with a string’s format() method, the default alignment was previously left-alignment. This has been changed to right-alignment, which is more sensible for numeric types. (Changed by Mark Dickinson; bpo-6857 [https://bugs.python.org/issue?@action=redirect&bpo=6857].)

Comparisons involving a signaling NaN value (or sNAN) now signal InvalidOperation instead of silently returning a true or false value depending on the comparison operator. Quiet NaN values (or NaN) are now hashable. (Fixed by Mark Dickinson; bpo-7279 [https://bugs.python.org/issue?@action=redirect&bpo=7279].)

The difflib module now produces output that is more compatible with modern diff/patch tools through one small change, using a tab character instead of spaces as a separator in the header giving the filename. (Fixed by Anatoly Techtonik; bpo-7585 [https://bugs.python.org/issue?@action=redirect&bpo=7585].)

The Distutils sdist command now always regenerates the MANIFEST file, since even if the MANIFEST.in or setup.py files haven’t been modified, the user might have created some new files that should be included. (Fixed by Tarek Ziadé; bpo-8688 [https://bugs.python.org/issue?@action=redirect&bpo=8688].)

The doctest module’s IGNORE_EXCEPTION_DETAIL flag will now ignore the name of the module containing the exception being tested. (Patch by Lennart Regebro; bpo-7490 [https://bugs.python.org/issue?@action=redirect&bpo=7490].)

The email module’s Message class will now accept a Unicode-valued payload, automatically converting the payload to the encoding specified by output_charset. (Added by R. David Murray; bpo-1368247 [https://bugs.python.org/issue?@action=redirect&bpo=1368247].)

The Fraction class now accepts a single float or Decimal instance, or two rational numbers, as arguments to its constructor. (Implemented by Mark Dickinson; rationals added in bpo-5812 [https://bugs.python.org/issue?@action=redirect&bpo=5812], and float/decimal in bpo-8294 [https://bugs.python.org/issue?@action=redirect&bpo=8294].)

Ordering comparisons (<, <=, >, >=) between fractions and complex numbers now raise a TypeError. This fixes an oversight, making the Fraction match the other numeric types.

New class: FTP_TLS in the ftplib module provides secure FTP connections using TLS encapsulation of authentication as well as subsequent control and data transfers. (Contributed by Giampaolo Rodola; bpo-2054 [https://bugs.python.org/issue?@action=redirect&bpo=2054].)

The storbinary() method for binary uploads can now restart uploads thanks to an added rest parameter (patch by Pablo Mouzo; bpo-6845 [https://bugs.python.org/issue?@action=redirect&bpo=6845].)

New class decorator: total_ordering() in the functools module takes a class that defines an __eq__() method and one of __lt__(), __le__(), __gt__(), or __ge__(), and generates the missing comparison methods. Since the __cmp__() method is being deprecated in Python 3.x, this decorator makes it easier to define ordered classes. (Added by Raymond Hettinger; bpo-5479 [https://bugs.python.org/issue?@action=redirect&bpo=5479].)

New function: cmp_to_key() will take an old-style comparison function that expects two arguments and return a new callable that can be used as the key parameter to functions such as sorted(), min() and max(), etc. The primary intended use is to help with making code compatible with Python 3.x. (Added by Raymond Hettinger.)

New function: the gc module’s is_tracked() returns true if a given instance is tracked by the garbage collector, false otherwise. (Contributed by Antoine Pitrou; bpo-4688 [https://bugs.python.org/issue?@action=redirect&bpo=4688].)

The gzip module’s GzipFile now supports the context management protocol, so you can write with gzip.GzipFile(...) as f: (contributed by Hagen Fürstenau; bpo-3860 [https://bugs.python.org/issue?@action=redirect&bpo=3860]), and it now implements the io.BufferedIOBase ABC, so you can wrap it with io.BufferedReader for faster processing (contributed by Nir Aides; bpo-7471 [https://bugs.python.org/issue?@action=redirect&bpo=7471]). It’s also now possible to override the modification time recorded in a gzipped file by providing an optional timestamp to the constructor. (Contributed by Jacques Frechet; bpo-4272 [https://bugs.python.org/issue?@action=redirect&bpo=4272].)

Files in gzip format can be padded with trailing zero bytes; the gzip module will now consume these trailing bytes. (Fixed by Tadek Pietraszek and Brian Curtin; bpo-2846 [https://bugs.python.org/issue?@action=redirect&bpo=2846].)

New attribute: the hashlib module now has an algorithms attribute containing a tuple naming the supported algorithms. In Python 2.7, hashlib.algorithms contains ('md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512'). (Contributed by Carl Chenet; bpo-7418 [https://bugs.python.org/issue?@action=redirect&bpo=7418].)

The default HTTPResponse class used by the httplib module now supports buffering, resulting in much faster reading of HTTP responses. (Contributed by Kristján Valur Jónsson; bpo-4879 [https://bugs.python.org/issue?@action=redirect&bpo=4879].)

The HTTPConnection and HTTPSConnection classes now support a source_address parameter, a (host, port) 2-tuple giving the source address that will be used for the connection. (Contributed by Eldon Ziegler; bpo-3972 [https://bugs.python.org/issue?@action=redirect&bpo=3972].)

The ihooks module now supports relative imports. Note that ihooks is an older module for customizing imports, superseded by the imputil module added in Python 2.0. (Relative import support added by Neil Schemenauer.)

The imaplib module now supports IPv6 addresses. (Contributed by Derek Morr; bpo-1655 [https://bugs.python.org/issue?@action=redirect&bpo=1655].)

New function: the inspect module’s getcallargs() takes a callable and its positional and keyword arguments, and figures out which of the callable’s parameters will receive each argument, returning a dictionary mapping argument names to their values. For example:

>>> from inspect import getcallargs
>>> def f(a, b=1, *pos, **named):
...     pass
>>> getcallargs(f, 1, 2, 3)
{'a': 1, 'b': 2, 'pos': (3,), 'named': {}}
>>> getcallargs(f, a=2, x=4)
{'a': 2, 'b': 1, 'pos': (), 'named': {'x': 4}}
>>> getcallargs(f)
Traceback (most recent call last):
...
TypeError: f() takes at least 1 argument (0 given)

Contributed by George Sakkis; bpo-3135 [https://bugs.python.org/issue?@action=redirect&bpo=3135].

Updated module: The io library has been upgraded to the version shipped with Python 3.1. For 3.1, the I/O library was entirely rewritten in C and is 2 to 20 times faster depending on the task being performed. The original Python version was renamed to the _pyio module.

One minor resulting change: the io.TextIOBase class now has an errors attribute giving the error setting used for encoding and decoding errors (one of 'strict', 'replace', 'ignore').

The io.FileIO class now raises an OSError when passed an invalid file descriptor. (Implemented by Benjamin Peterson; bpo-4991 [https://bugs.python.org/issue?@action=redirect&bpo=4991].) The truncate() method now preserves the file position; previously it would change the file position to the end of the new file. (Fixed by Pascal Chambon; bpo-6939 [https://bugs.python.org/issue?@action=redirect&bpo=6939].)

New function: itertools.compress(data, selectors) takes two iterators. Elements of data are returned if the corresponding value in selectors is true:

itertools.compress('ABCDEF', [1,0,1,0,1,1]) =>
  A, C, E, F

New function: itertools.combinations_with_replacement(iter, r) returns all the possible r-length combinations of elements from the iterable iter. Unlike combinations(), individual elements can be repeated in the generated combinations:

itertools.combinations_with_replacement('abc', 2) =>
  ('a', 'a'), ('a', 'b'), ('a', 'c'),
  ('b', 'b'), ('b', 'c'), ('c', 'c')

Note that elements are treated as unique depending on their position in the input, not their actual values.

The itertools.count() function now has a step argument that allows incrementing by values other than 1. count() also now allows keyword arguments, and using non-integer values such as floats or Decimal instances. (Implemented by Raymond Hettinger; bpo-5032 [https://bugs.python.org/issue?@action=redirect&bpo=5032].)

itertools.combinations() and itertools.product() previously raised ValueError for values of r larger than the input iterable. This was deemed a specification error, so they now return an empty iterator. (Fixed by Raymond Hettinger; bpo-4816 [https://bugs.python.org/issue?@action=redirect&bpo=4816].)

Updated module: The json module was upgraded to version 2.0.9 of the simplejson package, which includes a C extension that makes encoding and decoding faster. (Contributed by Bob Ippolito; bpo-4136 [https://bugs.python.org/issue?@action=redirect&bpo=4136].)

To support the new collections.OrderedDict type, json.load() now has an optional object_pairs_hook parameter that will be called with any object literal that decodes to a list of pairs. (Contributed by Raymond Hettinger; bpo-5381 [https://bugs.python.org/issue?@action=redirect&bpo=5381].)

The mailbox module’s Maildir class now records the timestamp on the directories it reads, and only re-reads them if the modification time has subsequently changed. This improves performance by avoiding unneeded directory scans. (Fixed by A.M. Kuchling and Antoine Pitrou; bpo-1607951 [https://bugs.python.org/issue?@action=redirect&bpo=1607951], bpo-6896 [https://bugs.python.org/issue?@action=redirect&bpo=6896].)

New functions: the math module gained erf() and erfc() for the error function and the complementary error function, expm1() which computes e**x - 1 with more precision than using exp() and subtracting 1, gamma() for the Gamma function, and lgamma() for the natural log of the Gamma function. (Contributed by Mark Dickinson and nirinA raseliarison; bpo-3366 [https://bugs.python.org/issue?@action=redirect&bpo=3366].)

The multiprocessing module’s Manager* classes can now be passed a callable that will be called whenever a subprocess is started, along with a set of arguments that will be passed to the callable. (Contributed by lekma; bpo-5585 [https://bugs.python.org/issue?@action=redirect&bpo=5585].)

The Pool class, which controls a pool of worker processes, now has an optional maxtasksperchild parameter. Worker processes will perform the specified number of tasks and then exit, causing the Pool to start a new worker. This is useful if tasks may leak memory or other resources, or if some tasks will cause the worker to become very large. (Contributed by Charles Cazabon; bpo-6963 [https://bugs.python.org/issue?@action=redirect&bpo=6963].)

The nntplib module now supports IPv6 addresses. (Contributed by Derek Morr; bpo-1664 [https://bugs.python.org/issue?@action=redirect&bpo=1664].)

New functions: the os module wraps the following POSIX system calls: getresgid() and getresuid(), which return the real, effective, and saved GIDs and UIDs; setresgid() and setresuid(), which set real, effective, and saved GIDs and UIDs to new values; initgroups(), which initialize the group access list for the current process. (GID/UID functions contributed by Travis H.; bpo-6508 [https://bugs.python.org/issue?@action=redirect&bpo=6508]. Support for initgroups added by Jean-Paul Calderone; bpo-7333 [https://bugs.python.org/issue?@action=redirect&bpo=7333].)

The os.fork() function now re-initializes the import lock in the child process; this fixes problems on Solaris when fork() is called from a thread. (Fixed by Zsolt Cserna; bpo-7242 [https://bugs.python.org/issue?@action=redirect&bpo=7242].)

In the os.path module, the normpath() and abspath() functions now preserve Unicode; if their input path is a Unicode string, the return value is also a Unicode string. (normpath() fixed by Matt Giuca in bpo-5827 [https://bugs.python.org/issue?@action=redirect&bpo=5827]; abspath() fixed by Ezio Melotti in bpo-3426 [https://bugs.python.org/issue?@action=redirect&bpo=3426].)

The pydoc module now has help for the various symbols that Python uses. You can now do help('<<') or help('@'), for example. (Contributed by David Laban; bpo-4739 [https://bugs.python.org/issue?@action=redirect&bpo=4739].)

The re module’s split(), sub(), and subn() now accept an optional flags argument, for consistency with the other functions in the module. (Added by Gregory P. Smith.)

New function: run_path() in the runpy module will execute the code at a provided path argument. path can be the path of a Python source file (example.py), a compiled bytecode file (example.pyc), a directory (./package/), or a zip archive (example.zip). If a directory or zip path is provided, it will be added to the front of sys.path and the module __main__ will be imported. It’s expected that the directory or zip contains a __main__.py; if it doesn’t, some other __main__.py might be imported from a location later in sys.path. This makes more of the machinery of runpy available to scripts that want to mimic the way Python’s command line processes an explicit path name. (Added by Nick Coghlan; bpo-6816 [https://bugs.python.org/issue?@action=redirect&bpo=6816].)

New function: in the shutil module, make_archive() takes a filename, archive type (zip or tar-format), and a directory path, and creates an archive containing the directory’s contents. (Added by Tarek Ziadé.)

shutil’s copyfile() and copytree() functions now raise a SpecialFileError exception when asked to copy a named pipe. Previously the code would treat named pipes like a regular file by opening them for reading, and this would block indefinitely. (Fixed by Antoine Pitrou; bpo-3002 [https://bugs.python.org/issue?@action=redirect&bpo=3002].)

The signal module no longer re-installs the signal handler unless this is truly necessary, which fixes a bug that could make it impossible to catch the EINTR signal robustly. (Fixed by Charles-Francois Natali; bpo-8354 [https://bugs.python.org/issue?@action=redirect&bpo=8354].)

New functions: in the site module, three new functions return various site- and user-specific paths. getsitepackages() returns a list containing all global site-packages directories, getusersitepackages() returns the path of the user’s site-packages directory, and getuserbase() returns the value of the USER_BASE environment variable, giving the path to a directory that can be used to store data. (Contributed by Tarek Ziadé; bpo-6693 [https://bugs.python.org/issue?@action=redirect&bpo=6693].)

The site module now reports exceptions occurring when the sitecustomize module is imported, and will no longer catch and swallow the KeyboardInterrupt exception. (Fixed by Victor Stinner; bpo-3137 [https://bugs.python.org/issue?@action=redirect&bpo=3137].)

The create_connection() function gained a source_address parameter, a (host, port) 2-tuple giving the source address that will be used for the connection. (Contributed by Eldon Ziegler; bpo-3972 [https://bugs.python.org/issue?@action=redirect&bpo=3972].)

The recv_into() and recvfrom_into() methods will now write into objects that support the buffer API, most usefully the bytearray and memoryview objects. (Implemented by Antoine Pitrou; bpo-8104 [https://bugs.python.org/issue?@action=redirect&bpo=8104].)

The SocketServer module’s TCPServer class now supports socket timeouts and disabling the Nagle algorithm. The disable_nagle_algorithm class attribute defaults to False; if overridden to be true, new request connections will have the TCP_NODELAY option set to prevent buffering many small sends into a single TCP packet. The timeout class attribute can hold a timeout in seconds that will be applied to the request socket; if no request is received within that time, handle_timeout() will be called and handle_request() will return. (Contributed by Kristján Valur Jónsson; bpo-6192 [https://bugs.python.org/issue?@action=redirect&bpo=6192] and bpo-6267 [https://bugs.python.org/issue?@action=redirect&bpo=6267].)

Updated module: the sqlite3 module has been updated to version 2.6.0 of the pysqlite package [https://github.com/ghaering/pysqlite]. Version 2.6.0 includes a number of bugfixes, and adds the ability to load SQLite extensions from shared libraries. Call the enable_load_extension(True) method to enable extensions, and then call load_extension() to load a particular shared library. (Updated by Gerhard Häring.)

The ssl module’s SSLSocket objects now support the buffer API, which fixed a test suite failure (fix by Antoine Pitrou; bpo-7133 [https://bugs.python.org/issue?@action=redirect&bpo=7133]) and automatically set OpenSSL’s SSL_MODE_AUTO_RETRY, which will prevent an error code being returned from recv() operations that trigger an SSL renegotiation (fix by Antoine Pitrou; bpo-8222 [https://bugs.python.org/issue?@action=redirect&bpo=8222]).

The ssl.wrap_socket() constructor function now takes a ciphers argument that’s a string listing the encryption algorithms to be allowed; the format of the string is described in the OpenSSL documentation [https://www.openssl.org/docs/manmaster/man1/ciphers.html#CIPHER-LIST-FORMAT]. (Added by Antoine Pitrou; bpo-8322 [https://bugs.python.org/issue?@action=redirect&bpo=8322].)

Another change makes the extension load all of OpenSSL’s ciphers and digest algorithms so that they’re all available. Some SSL certificates couldn’t be verified, reporting an «unknown algorithm» error. (Reported by Beda Kosata, and fixed by Antoine Pitrou; bpo-8484 [https://bugs.python.org/issue?@action=redirect&bpo=8484].)

The version of OpenSSL being used is now available as the module attributes ssl.OPENSSL_VERSION (a string), ssl.OPENSSL_VERSION_INFO (a 5-tuple), and ssl.OPENSSL_VERSION_NUMBER (an integer). (Added by Antoine Pitrou; bpo-8321 [https://bugs.python.org/issue?@action=redirect&bpo=8321].)

The struct module will no longer silently ignore overflow errors when a value is too large for a particular integer format code (one of bBhHiIlLqQ); it now always raises a struct.error exception. (Changed by Mark Dickinson; bpo-1523 [https://bugs.python.org/issue?@action=redirect&bpo=1523].) The pack() function will also attempt to use __index__() to convert and pack non-integers before trying the __int__() method or reporting an error. (Changed by Mark Dickinson; bpo-8300 [https://bugs.python.org/issue?@action=redirect&bpo=8300].)

New function: the subprocess module’s check_output() runs a command with a specified set of arguments and returns the command’s output as a string when the command runs without error, or raises a CalledProcessError exception otherwise.

>>> subprocess.check_output(['df', '-h', '.'])
'Filesystem     Size   Used  Avail Capacity  Mounted on\n
/dev/disk0s2    52G    49G   3.0G    94%    /\n'

>>> subprocess.check_output(['df', '-h', '/bogus'])
  ...
subprocess.CalledProcessError: Command '['df', '-h', '/bogus']' returned non-zero exit status 1

(Contributed by Gregory P. Smith.)

The subprocess module will now retry its internal system calls on receiving an EINTR signal. (Reported by several people; final patch by Gregory P. Smith in bpo-1068268 [https://bugs.python.org/issue?@action=redirect&bpo=1068268].)

New function: is_declared_global() in the symtable module returns true for variables that are explicitly declared to be global, false for ones that are implicitly global. (Contributed by Jeremy Hylton.)

The syslog module will now use the value of sys.argv[0] as the identifier instead of the previous default value of 'python'. (Changed by Sean Reifschneider; bpo-8451 [https://bugs.python.org/issue?@action=redirect&bpo=8451].)

The sys.version_info value is now a named tuple, with attributes named major, minor, micro, releaselevel, and serial. (Contributed by Ross Light; bpo-4285 [https://bugs.python.org/issue?@action=redirect&bpo=4285].)

sys.getwindowsversion() also returns a named tuple, with attributes named major, minor, build, platform, service_pack, service_pack_major, service_pack_minor, suite_mask, and product_type. (Contributed by Brian Curtin; bpo-7766 [https://bugs.python.org/issue?@action=redirect&bpo=7766].)

The tarfile module’s default error handling has changed, to no longer suppress fatal errors. The default error level was previously 0, which meant that errors would only result in a message being written to the debug log, but because the debug log is not activated by default, these errors go unnoticed. The default error level is now 1, which raises an exception if there’s an error. (Changed by Lars Gustäbel; bpo-7357 [https://bugs.python.org/issue?@action=redirect&bpo=7357].)

tarfile now supports filtering the TarInfo objects being added to a tar file. When you call add(), you may supply an optional filter argument that’s a callable. The filter callable will be passed the TarInfo for every file being added, and can modify and return it. If the callable returns None, the file will be excluded from the resulting archive. This is more powerful than the existing exclude argument, which has therefore been deprecated. (Added by Lars Gustäbel; bpo-6856 [https://bugs.python.org/issue?@action=redirect&bpo=6856].) The TarFile class also now supports the context management protocol. (Added by Lars Gustäbel; bpo-7232 [https://bugs.python.org/issue?@action=redirect&bpo=7232].)

The wait() method of the threading.Event class now returns the internal flag on exit. This means the method will usually return true because wait() is supposed to block until the internal flag becomes true. The return value will only be false if a timeout was provided and the operation timed out. (Contributed by Tim Lesher; bpo-1674032 [https://bugs.python.org/issue?@action=redirect&bpo=1674032].)

The Unicode database provided by the unicodedata module is now used internally to determine which characters are numeric, whitespace, or represent line breaks. The database also includes information from the Unihan.txt data file (patch by Anders Chrigström and Amaury Forgeot d’Arc; bpo-1571184 [https://bugs.python.org/issue?@action=redirect&bpo=1571184]) and has been updated to version 5.2.0 (updated by Florent Xicluna; bpo-8024 [https://bugs.python.org/issue?@action=redirect&bpo=8024]).

The urlparse module’s urlsplit() now handles unknown URL schemes in a fashion compliant with RFC 3986 [https://tools.ietf.org/html/rfc3986.html]: if the URL is of the form "<something>://...", the text before the :// is treated as the scheme, even if it’s a made-up scheme that the module doesn’t know about. This change may break code that worked around the old behaviour. For example, Python 2.6.4 or 2.5 will return the following:

>>> import urlparse
>>> urlparse.urlsplit('invented://host/filename?query')
('invented', '', '//host/filename?query', '', '')

Python 2.7 (and Python 2.6.5) will return:

>>> import urlparse
>>> urlparse.urlsplit('invented://host/filename?query')
('invented', 'host', '/filename?query', '', '')

(Python 2.7 actually produces slightly different output, since it returns a named tuple instead of a standard tuple.)

The urlparse module also supports IPv6 literal addresses as defined by RFC 2732 [https://tools.ietf.org/html/rfc2732.html] (contributed by Senthil Kumaran; bpo-2987 [https://bugs.python.org/issue?@action=redirect&bpo=2987]).

>>> urlparse.urlparse('http://[1080::8:800:200C:417A]/foo')
ParseResult(scheme='http', netloc='[1080::8:800:200C:417A]',
            path='/foo', params='', query='', fragment='')

New class: the WeakSet class in the weakref module is a set that only holds weak references to its elements; elements will be removed once there are no references pointing to them. (Originally implemented in Python 3.x by Raymond Hettinger, and backported to 2.7 by Michael Foord.)

The ElementTree library, xml.etree, no longer escapes ampersands and angle brackets when outputting an XML processing instruction (which looks like <?xml-stylesheet href="#style1"?>) or comment (which looks like <!-- comment -->). (Patch by Neil Muller; bpo-2746 [https://bugs.python.org/issue?@action=redirect&bpo=2746].)

The XML-RPC client and server, provided by the xmlrpclib and SimpleXMLRPCServer modules, have improved performance by supporting HTTP/1.1 keep-alive and by optionally using gzip encoding to compress the XML being exchanged. The gzip compression is controlled by the encode_threshold attribute of SimpleXMLRPCRequestHandler, which contains a size in bytes; responses larger than this will be compressed. (Contributed by Kristján Valur Jónsson; bpo-6267 [https://bugs.python.org/issue?@action=redirect&bpo=6267].)

The zipfile module’s ZipFile now supports the context management protocol, so you can write with zipfile.ZipFile(...) as f:. (Contributed by Brian Curtin; bpo-5511 [https://bugs.python.org/issue?@action=redirect&bpo=5511].)

zipfile now also supports archiving empty directories and extracts them correctly. (Fixed by Kuba Wieczorek; bpo-4710 [https://bugs.python.org/issue?@action=redirect&bpo=4710].) Reading files out of an archive is faster, and interleaving read() and readline() now works correctly. (Contributed by Nir Aides; bpo-7610 [https://bugs.python.org/issue?@action=redirect&bpo=7610].)

The is_zipfile() function now accepts a file object, in addition to the path names accepted in earlier versions. (Contributed by Gabriel Genellina; bpo-4756 [https://bugs.python.org/issue?@action=redirect&bpo=4756].)

The writestr() method now has an optional compress_type parameter that lets you override the default compression method specified in the ZipFile constructor. (Contributed by Ronald Oussoren; bpo-6003 [https://bugs.python.org/issue?@action=redirect&bpo=6003].)

New module: importlib

Python 3.1 includes the importlib package, a re-implementation of the logic underlying Python’s import statement. importlib is useful for implementors of Python interpreters and to users who wish to write new importers that can participate in the import process. Python 2.7 doesn’t contain the complete importlib package, but instead has a tiny subset that contains a single function, import_module().

import_module(name, package=None) imports a module. name is a string containing the module or package’s name. It’s possible to do relative imports by providing a string that begins with a . character, such as ..utils.errors. For relative imports, the package argument must be provided and is the name of the package that will be used as the anchor for the relative import. import_module() both inserts the imported module into sys.modules and returns the module object.

Here are some examples:

>>> from importlib import import_module
>>> anydbm = import_module('anydbm')  # Standard absolute import
>>> anydbm
<module 'anydbm' from '/p/python/Lib/anydbm.py'>
>>> # Relative import
>>> file_util = import_module('..file_util', 'distutils.command')
>>> file_util
<module 'distutils.file_util' from '/python/Lib/distutils/file_util.pyc'>

importlib was implemented by Brett Cannon and introduced in Python 3.1.

New module: sysconfig

The sysconfig module has been pulled out of the Distutils package, becoming a new top-level module in its own right. sysconfig provides functions for getting information about Python’s build process: compiler switches, installation paths, the platform name, and whether Python is running from its source directory.

Some of the functions in the module are:

get_config_var() returns variables from Python’s Makefile and the pyconfig.h file.

get_config_vars() returns a dictionary containing all of the configuration variables.

get_path() returns the configured path for a particular type of module: the standard library, site-specific modules, platform-specific modules, etc.

is_python_build() returns true if you’re running a binary from a Python source tree, and false otherwise.

Consult the sysconfig documentation for more details and for a complete list of functions.

The Distutils package and sysconfig are now maintained by Tarek Ziadé, who has also started a Distutils2 package (source repository at https://hg.python.org/distutils2/) for developing a next-generation version of Distutils.

ttk: Themed Widgets for Tk

Tcl/Tk 8.5 includes a set of themed widgets that re-implement basic Tk widgets but have a more customizable appearance and can therefore more closely resemble the native platform’s widgets. This widget set was originally called Tile, but was renamed to Ttk (for «themed Tk») on being added to Tcl/Tck release 8.5.

To learn more, read the ttk module documentation. You may also wish to read the Tcl/Tk manual page describing the Ttk theme engine, available at https://www.tcl.tk/man/tcl8.5/TkCmd/ttk_intro.htm. Some screenshots of the Python/Ttk code in use are at https://code.google.com/archive/p/python-ttk/wikis/Screenshots.wiki.

The ttk module was written by Guilherme Polo and added in bpo-2983 [https://bugs.python.org/issue?@action=redirect&bpo=2983]. An alternate version called Tile.py, written by Martin Franklin and maintained by Kevin Walzer, was proposed for inclusion in bpo-2618 [https://bugs.python.org/issue?@action=redirect&bpo=2618], but the authors argued that Guilherme Polo’s work was more comprehensive.

Updated module: unittest

The unittest module was greatly enhanced; many new features were added. Most of these features were implemented by Michael Foord, unless otherwise noted. The enhanced version of the module is downloadable separately for use with Python versions 2.4 to 2.6, packaged as the unittest2 package, from https://pypi.org/project/unittest2.

When used from the command line, the module can automatically discover tests. It’s not as fancy as py.test [http://pytest.org] or nose [https://nose.readthedocs.io/], but provides a simple way to run tests kept within a set of package directories. For example, the following command will search the test/ subdirectory for any importable test files named test*.py:

python -m unittest discover -s test

Consult the unittest module documentation for more details. (Developed in bpo-6001 [https://bugs.python.org/issue?@action=redirect&bpo=6001].)

The main() function supports some other new options:

-b or --buffer will buffer the standard output and standard error streams during each test. If the test passes, any resulting output will be discarded; on failure, the buffered output will be displayed.

-c or --catch will cause the control-C interrupt to be handled more gracefully. Instead of interrupting the test process immediately, the currently running test will be completed and then the partial results up to the interruption will be reported. If you’re impatient, a second press of control-C will cause an immediate interruption.

This control-C handler tries to avoid causing problems when the code being tested or the tests being run have defined a signal handler of their own, by noticing that a signal handler was already set and calling it. If this doesn’t work for you, there’s a removeHandler() decorator that can be used to mark tests that should have the control-C handling disabled.

-f or --failfast makes test execution stop immediately when a test fails instead of continuing to execute further tests. (Suggested by Cliff Dyer and implemented by Michael Foord; bpo-8074 [https://bugs.python.org/issue?@action=redirect&bpo=8074].)

The progress messages now show “x” for expected failures and “u” for unexpected successes when run in verbose mode. (Contributed by Benjamin Peterson.)

Test cases can raise the SkipTest exception to skip a test (bpo-1034053 [https://bugs.python.org/issue?@action=redirect&bpo=1034053]).

The error messages for assertEqual(), assertTrue(), and assertFalse() failures now provide more information. If you set the longMessage attribute of your TestCase classes to true, both the standard error message and any additional message you provide will be printed for failures. (Added by Michael Foord; bpo-5663 [https://bugs.python.org/issue?@action=redirect&bpo=5663].)

The assertRaises() method now returns a context handler when called without providing a callable object to run. For example, you can write this:

with self.assertRaises(KeyError):
    {}['foo']

(Implemented by Antoine Pitrou; bpo-4444 [https://bugs.python.org/issue?@action=redirect&bpo=4444].)

Module- and class-level setup and teardown fixtures are now supported. Modules can contain setUpModule() and tearDownModule() functions. Classes can have setUpClass() and tearDownClass() methods that must be defined as class methods (using @classmethod or equivalent). These functions and methods are invoked when the test runner switches to a test case in a different module or class.

The methods addCleanup() and doCleanups() were added. addCleanup() lets you add cleanup functions that will be called unconditionally (after setUp() if setUp() fails, otherwise after tearDown()). This allows for much simpler resource allocation and deallocation during tests (bpo-5679 [https://bugs.python.org/issue?@action=redirect&bpo=5679]).

A number of new methods were added that provide more specialized tests. Many of these methods were written by Google engineers for use in their test suites; Gregory P. Smith, Michael Foord, and GvR worked on merging them into Python’s version of unittest.

assertIsNone() and assertIsNotNone() take one expression and verify that the result is or is not None.

assertIs() and assertIsNot() take two values and check whether the two values evaluate to the same object or not. (Added by Michael Foord; bpo-2578 [https://bugs.python.org/issue?@action=redirect&bpo=2578].)

assertIsInstance() and assertNotIsInstance() check whether the resulting object is an instance of a particular class, or of one of a tuple of classes. (Added by Georg Brandl; bpo-7031 [https://bugs.python.org/issue?@action=redirect&bpo=7031].)

assertGreater(), assertGreaterEqual(), assertLess(), and assertLessEqual() compare two quantities.

assertMultiLineEqual() compares two strings, and if they’re not equal, displays a helpful comparison that highlights the differences in the two strings. This comparison is now used by default when Unicode strings are compared with assertEqual().

assertRegexpMatches() and assertNotRegexpMatches() checks whether the first argument is a string matching or not matching the regular expression provided as the second argument (bpo-8038 [https://bugs.python.org/issue?@action=redirect&bpo=8038]).

assertRaisesRegexp() checks whether a particular exception is raised, and then also checks that the string representation of the exception matches the provided regular expression.

assertIn() and assertNotIn() tests whether first is or is not in second.

assertItemsEqual() tests whether two provided sequences contain the same elements.

assertSetEqual() compares whether two sets are equal, and only reports the differences between the sets in case of error.

Similarly, assertListEqual() and assertTupleEqual() compare the specified types and explain any differences without necessarily printing their full values; these methods are now used by default when comparing lists and tuples using assertEqual(). More generally, assertSequenceEqual() compares two sequences and can optionally check whether both sequences are of a particular type.

assertDictEqual() compares two dictionaries and reports the differences; it’s now used by default when you compare two dictionaries using assertEqual(). assertDictContainsSubset() checks whether all of the key/value pairs in first are found in second.

assertAlmostEqual() and assertNotAlmostEqual() test whether first and second are approximately equal. This method can either round their difference to an optionally-specified number of places (the default is 7) and compare it to zero, or require the difference to be smaller than a supplied delta value.

loadTestsFromName() properly honors the suiteClass attribute of the TestLoader. (Fixed by Mark Roddy; bpo-6866 [https://bugs.python.org/issue?@action=redirect&bpo=6866].)

A new hook lets you extend the assertEqual() method to handle new data types. The addTypeEqualityFunc() method takes a type object and a function. The function will be used when both of the objects being compared are of the specified type. This function should compare the two objects and raise an exception if they don’t match; it’s a good idea for the function to provide additional information about why the two objects aren’t matching, much as the new sequence comparison methods do.

unittest.main() now takes an optional exit argument. If false, main() doesn’t call sys.exit(), allowing main() to be used from the interactive interpreter. (Contributed by J. Pablo Fernández; bpo-3379 [https://bugs.python.org/issue?@action=redirect&bpo=3379].)

TestResult has new startTestRun() and stopTestRun() methods that are called immediately before and after a test run. (Contributed by Robert Collins; bpo-5728 [https://bugs.python.org/issue?@action=redirect&bpo=5728].)

With all these changes, the unittest.py was becoming awkwardly large, so the module was turned into a package and the code split into several files (by Benjamin Peterson). This doesn’t affect how the module is imported or used.

Ver también

http://www.voidspace.org.uk/python/articles/unittest2.shtml

Describes the new features, how to use them, and the rationale for various design decisions. (By Michael Foord.)

Updated module: ElementTree 1.3

The version of the ElementTree library included with Python was updated to version 1.3. Some of the new features are:

The various parsing functions now take a parser keyword argument giving an XMLParser instance that will be used. This makes it possible to override the file’s internal encoding:

p = ET.XMLParser(encoding='utf-8')
t = ET.XML("""<root/>""", parser=p)

Errors in parsing XML now raise a ParseError exception, whose instances have a position attribute containing a (line, column) tuple giving the location of the problem.

ElementTree’s code for converting trees to a string has been significantly reworked, making it roughly twice as fast in many cases. The ElementTree.write() and Element.write() methods now have a method parameter that can be «xml» (the default), «html», or «text». HTML mode will output empty elements as <empty></empty> instead of <empty/>, and text mode will skip over elements and only output the text chunks. If you set the tag attribute of an element to None but leave its children in place, the element will be omitted when the tree is written out, so you don’t need to do more extensive rearrangement to remove a single element.

Namespace handling has also been improved. All xmlns:<whatever> declarations are now output on the root element, not scattered throughout the resulting XML. You can set the default namespace for a tree by setting the default_namespace attribute and can register new prefixes with register_namespace(). In XML mode, you can use the true/false xml_declaration parameter to suppress the XML declaration.

New Element method: extend() appends the items from a sequence to the element’s children. Elements themselves behave like sequences, so it’s easy to move children from one element to another:

from xml.etree import ElementTree as ET

t = ET.XML("""<list>
  <item>1</item> <item>2</item>  <item>3</item>
</list>""")
new = ET.XML('<root/>')
new.extend(t)

# Outputs <root><item>1</item>...</root>
print ET.tostring(new)

New Element method: iter() yields the children of the element as a generator. It’s also possible to write for child in elem: to loop over an element’s children. The existing method getiterator() is now deprecated, as is getchildren() which constructs and returns a list of children.

New Element method: itertext() yields all chunks of text that are descendants of the element. For example:

t = ET.XML("""<list>
  <item>1</item> <item>2</item>  <item>3</item>
</list>""")

# Outputs ['\n  ', '1', ' ', '2', '  ', '3', '\n']
print list(t.itertext())

Deprecated: using an element as a Boolean (i.e., if elem:) would return true if the element had any children, or false if there were no children. This behaviour is confusing – None is false, but so is a childless element? – so it will now trigger a FutureWarning. In your code, you should be explicit: write len(elem) != 0 if you’re interested in the number of children, or elem is not None.

Fredrik Lundh develops ElementTree and produced the 1.3 version; you can read his article describing 1.3 at https://web.archive.org/web/20200703234532/http://effbot.org/zone/elementtree-13-intro.htm. Florent Xicluna updated the version included with Python, after discussions on python-dev and in bpo-6472 [https://bugs.python.org/issue?@action=redirect&bpo=6472].)

Build and C API Changes

Changes to Python’s build process and to the C API include:

The latest release of the GNU Debugger, GDB 7, can be scripted using Python [https://sourceware.org/gdb/current/onlinedocs/gdb/Python.html]. When you begin debugging an executable program P, GDB will look for a file named P-gdb.py and automatically read it. Dave Malcolm contributed a python-gdb.py that adds a number of commands useful when debugging Python itself. For example, py-up and py-down go up or down one Python stack frame, which usually corresponds to several C stack frames. py-print prints the value of a Python variable, and py-bt prints the Python stack trace. (Added as a result of bpo-8032 [https://bugs.python.org/issue?@action=redirect&bpo=8032].)

If you use the .gdbinit file provided with Python, the «pyo» macro in the 2.7 version now works correctly when the thread being debugged doesn’t hold the GIL; the macro now acquires it before printing. (Contributed by Victor Stinner; bpo-3632 [https://bugs.python.org/issue?@action=redirect&bpo=3632].)

Py_AddPendingCall() is now thread-safe, letting any worker thread submit notifications to the main Python thread. This is particularly useful for asynchronous IO operations. (Contributed by Kristján Valur Jónsson; bpo-4293 [https://bugs.python.org/issue?@action=redirect&bpo=4293].)

New function: PyCode_NewEmpty() creates an empty code object; only the filename, function name, and first line number are required. This is useful for extension modules that are attempting to construct a more useful traceback stack. Previously such extensions needed to call PyCode_New(), which had many more arguments. (Added by Jeffrey Yasskin.)

New function: PyErr_NewExceptionWithDoc() creates a new exception class, just as the existing PyErr_NewException() does, but takes an extra char * argument containing the docstring for the new exception class. (Added by “lekma” on the Python bug tracker; bpo-7033 [https://bugs.python.org/issue?@action=redirect&bpo=7033].)

New function: PyFrame_GetLineNumber() takes a frame object and returns the line number that the frame is currently executing. Previously code would need to get the index of the bytecode instruction currently executing, and then look up the line number corresponding to that address. (Added by Jeffrey Yasskin.)

New functions: PyLong_AsLongAndOverflow() and PyLong_AsLongLongAndOverflow() approximates a Python long integer as a C long or long long. If the number is too large to fit into the output type, an overflow flag is set and returned to the caller. (Contributed by Case Van Horsen; bpo-7528 [https://bugs.python.org/issue?@action=redirect&bpo=7528] and bpo-7767 [https://bugs.python.org/issue?@action=redirect&bpo=7767].)

New function: stemming from the rewrite of string-to-float conversion, a new PyOS_string_to_double() function was added. The old PyOS_ascii_strtod() and PyOS_ascii_atof() functions are now deprecated.

New function: PySys_SetArgvEx() sets the value of sys.argv and can optionally update sys.path to include the directory containing the script named by sys.argv[0] depending on the value of an updatepath parameter.

This function was added to close a security hole for applications that embed Python. The old function, PySys_SetArgv(), would always update sys.path, and sometimes it would add the current directory. This meant that, if you ran an application embedding Python in a directory controlled by someone else, attackers could put a Trojan-horse module in the directory (say, a file named os.py) that your application would then import and run.

If you maintain a C/C++ application that embeds Python, check whether you’re calling PySys_SetArgv() and carefully consider whether the application should be using PySys_SetArgvEx() with updatepath set to false.

Security issue reported as CVE-2008-5983 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2008-5983]; discussed in bpo-5753 [https://bugs.python.org/issue?@action=redirect&bpo=5753], and fixed by Antoine Pitrou.

New macros: the Python header files now define the following macros: Py_ISALNUM, Py_ISALPHA, Py_ISDIGIT, Py_ISLOWER, Py_ISSPACE, Py_ISUPPER, Py_ISXDIGIT, Py_TOLOWER, and Py_TOUPPER. All of these functions are analogous to the C standard macros for classifying characters, but ignore the current locale setting, because in several places Python needs to analyze characters in a locale-independent way. (Added by Eric Smith; bpo-5793 [https://bugs.python.org/issue?@action=redirect&bpo=5793].)

Removed function: PyEval_CallObject is now only available as a macro. A function version was being kept around to preserve ABI linking compatibility, but that was in 1997; it can certainly be deleted by now. (Removed by Antoine Pitrou; bpo-8276 [https://bugs.python.org/issue?@action=redirect&bpo=8276].)

New format codes: the PyFormat_FromString(), PyFormat_FromStringV(), and PyErr_Format() functions now accept %lld and %llu format codes for displaying C’s long long types. (Contributed by Mark Dickinson; bpo-7228 [https://bugs.python.org/issue?@action=redirect&bpo=7228].)

The complicated interaction between threads and process forking has been changed. Previously, the child process created by os.fork() might fail because the child is created with only a single thread running, the thread performing the os.fork(). If other threads were holding a lock, such as Python’s import lock, when the fork was performed, the lock would still be marked as «held» in the new process. But in the child process nothing would ever release the lock, since the other threads weren’t replicated, and the child process would no longer be able to perform imports.

Python 2.7 acquires the import lock before performing an os.fork(), and will also clean up any locks created using the threading module. C extension modules that have internal locks, or that call fork() themselves, will not benefit from this clean-up.

(Fixed by Thomas Wouters; bpo-1590864 [https://bugs.python.org/issue?@action=redirect&bpo=1590864].)

The Py_Finalize() function now calls the internal threading._shutdown() function; this prevents some exceptions from being raised when an interpreter shuts down. (Patch by Adam Olsen; bpo-1722344 [https://bugs.python.org/issue?@action=redirect&bpo=1722344].)

When using the PyMemberDef structure to define attributes of a type, Python will no longer let you try to delete or set a T_STRING_INPLACE attribute.

Global symbols defined by the ctypes module are now prefixed with Py, or with _ctypes. (Implemented by Thomas Heller; bpo-3102 [https://bugs.python.org/issue?@action=redirect&bpo=3102].)

New configure option: the --with-system-expat switch allows building the pyexpat module to use the system Expat library. (Contributed by Arfrever Frehtes Taifersar Arahesis; bpo-7609 [https://bugs.python.org/issue?@action=redirect&bpo=7609].)

New configure option: the --with-valgrind option will now disable the pymalloc allocator, which is difficult for the Valgrind memory-error detector to analyze correctly. Valgrind will therefore be better at detecting memory leaks and overruns. (Contributed by James Henstridge; bpo-2422 [https://bugs.python.org/issue?@action=redirect&bpo=2422].)

New configure option: you can now supply an empty string to --with-dbmliborder= in order to disable all of the various DBM modules. (Added by Arfrever Frehtes Taifersar Arahesis; bpo-6491 [https://bugs.python.org/issue?@action=redirect&bpo=6491].)

The configure script now checks for floating-point rounding bugs on certain 32-bit Intel chips and defines a X87_DOUBLE_ROUNDING preprocessor definition. No code currently uses this definition, but it’s available if anyone wishes to use it. (Added by Mark Dickinson; bpo-2937 [https://bugs.python.org/issue?@action=redirect&bpo=2937].)

configure also now sets a LDCXXSHARED Makefile variable for supporting C++ linking. (Contributed by Arfrever Frehtes Taifersar Arahesis; bpo-1222585 [https://bugs.python.org/issue?@action=redirect&bpo=1222585].)

The build process now creates the necessary files for pkg-config support. (Contributed by Clinton Roy; bpo-3585 [https://bugs.python.org/issue?@action=redirect&bpo=3585].)

The build process now supports Subversion 1.7. (Contributed by Arfrever Frehtes Taifersar Arahesis; bpo-6094 [https://bugs.python.org/issue?@action=redirect&bpo=6094].)

Capsules

Python 3.1 adds a new C datatype, PyCapsule, for providing a C API to an extension module. A capsule is essentially the holder of a C void * pointer, and is made available as a module attribute; for example, the socket module’s API is exposed as socket.CAPI, and unicodedata exposes ucnhash_CAPI. Other extensions can import the module, access its dictionary to get the capsule object, and then get the void * pointer, which will usually point to an array of pointers to the module’s various API functions.

There is an existing data type already used for this, PyCObject, but it doesn’t provide type safety. Evil code written in pure Python could cause a segmentation fault by taking a PyCObject from module A and somehow substituting it for the PyCObject in module B. Capsules know their own name, and getting the pointer requires providing the name:

void *vtable;

if (!PyCapsule_IsValid(capsule, "mymodule.CAPI") {
        PyErr_SetString(PyExc_ValueError, "argument type invalid");
        return NULL;
}

vtable = PyCapsule_GetPointer(capsule, "mymodule.CAPI");

You are assured that vtable points to whatever you’re expecting. If a different capsule was passed in, PyCapsule_IsValid() would detect the mismatched name and return false. Refer to Proporcionar una API C para un módulo de extensión for more information on using these objects.

Python 2.7 now uses capsules internally to provide various extension-module APIs, but the PyCObject_AsVoidPtr() was modified to handle capsules, preserving compile-time compatibility with the CObject interface. Use of PyCObject_AsVoidPtr() will signal a PendingDeprecationWarning, which is silent by default.

Implemented in Python 3.1 and backported to 2.7 by Larry Hastings; discussed in bpo-5630 [https://bugs.python.org/issue?@action=redirect&bpo=5630].

Port-Specific Changes: Windows

The msvcrt module now contains some constants from the crtassem.h header file: CRT_ASSEMBLY_VERSION, VC_ASSEMBLY_PUBLICKEYTOKEN, and LIBRARIES_ASSEMBLY_NAME_PREFIX. (Contributed by David Cournapeau; bpo-4365 [https://bugs.python.org/issue?@action=redirect&bpo=4365].)

The _winreg module for accessing the registry now implements the CreateKeyEx() and DeleteKeyEx() functions, extended versions of previously-supported functions that take several extra arguments. The DisableReflectionKey(), EnableReflectionKey(), and QueryReflectionKey() were also tested and documented. (Implemented by Brian Curtin: bpo-7347 [https://bugs.python.org/issue?@action=redirect&bpo=7347].)

The new _beginthreadex() API is used to start threads, and the native thread-local storage functions are now used. (Contributed by Kristján Valur Jónsson; bpo-3582 [https://bugs.python.org/issue?@action=redirect&bpo=3582].)

The os.kill() function now works on Windows. The signal value can be the constants CTRL_C_EVENT, CTRL_BREAK_EVENT, or any integer. The first two constants will send Control-C and Control-Break keystroke events to subprocesses; any other value will use the TerminateProcess() API. (Contributed by Miki Tebeka; bpo-1220212 [https://bugs.python.org/issue?@action=redirect&bpo=1220212].)

The os.listdir() function now correctly fails for an empty path. (Fixed by Hirokazu Yamamoto; bpo-5913 [https://bugs.python.org/issue?@action=redirect&bpo=5913].)

The mimelib module will now read the MIME database from the Windows registry when initializing. (Patch by Gabriel Genellina; bpo-4969 [https://bugs.python.org/issue?@action=redirect&bpo=4969].)

Port-Specific Changes: Mac OS X

The path /Library/Python/2.7/site-packages is now appended to sys.path, in order to share added packages between the system installation and a user-installed copy of the same version. (Changed by Ronald Oussoren; bpo-4865 [https://bugs.python.org/issue?@action=redirect&bpo=4865].)

Distinto en la versión 2.7.13: As of 2.7.13, this change was removed. /Library/Python/2.7/site-packages, the site-packages directory used by the Apple-supplied system Python 2.7 is no longer appended to sys.path for user-installed Pythons such as from the python.org installers. As of macOS 10.12, Apple changed how the system site-packages directory is configured, which could cause installation of pip components, like setuptools, to fail. Packages installed for the system Python will no longer be shared with user-installed Pythons. (bpo-28440 [https://bugs.python.org/issue?@action=redirect&bpo=28440])

Port-Specific Changes: FreeBSD

FreeBSD 7.1’s SO_SETFIB constant, used with getsockopt()/setsockopt() to select an alternate routing table, is now available in the socket module. (Added by Kyle VanderBeek; bpo-8235 [https://bugs.python.org/issue?@action=redirect&bpo=8235].)

Other Changes and Fixes

Two benchmark scripts, iobench and ccbench, were added to the Tools directory. iobench measures the speed of the built-in file I/O objects returned by open() while performing various operations, and ccbench is a concurrency benchmark that tries to measure computing throughput, thread switching latency, and IO processing bandwidth when performing several tasks using a varying number of threads.

The Tools/i18n/msgfmt.py script now understands plural forms in .po files. (Fixed by Martin von Löwis; bpo-5464 [https://bugs.python.org/issue?@action=redirect&bpo=5464].)

When importing a module from a .pyc or .pyo file with an existing .py counterpart, the co_filename attributes of the resulting code objects are overwritten when the original filename is obsolete. This can happen if the file has been renamed, moved, or is accessed through different paths. (Patch by Ziga Seilnacht and Jean-Paul Calderone; bpo-1180193 [https://bugs.python.org/issue?@action=redirect&bpo=1180193].)

The regrtest.py script now takes a --randseed= switch that takes an integer that will be used as the random seed for the -r option that executes tests in random order. The -r option also reports the seed that was used (Added by Collin Winter.)

Another regrtest.py switch is -j, which takes an integer specifying how many tests run in parallel. This allows reducing the total runtime on multi-core machines. This option is compatible with several other options, including the -R switch which is known to produce long runtimes. (Added by Antoine Pitrou, bpo-6152 [https://bugs.python.org/issue?@action=redirect&bpo=6152].) This can also be used with a new -F switch that runs selected tests in a loop until they fail. (Added by Antoine Pitrou; bpo-7312 [https://bugs.python.org/issue?@action=redirect&bpo=7312].)

When executed as a script, the py_compile.py module now accepts '-' as an argument, which will read standard input for the list of filenames to be compiled. (Contributed by Piotr Ożarowski; bpo-8233 [https://bugs.python.org/issue?@action=redirect&bpo=8233].)

Porting to Python 2.7

This section lists previously described changes and other bugfixes that may require changes to your code:

The range() function processes its arguments more consistently; it will now call __int__() on non-float, non-integer arguments that are supplied to it. (Fixed by Alexander Belopolsky; bpo-1533 [https://bugs.python.org/issue?@action=redirect&bpo=1533].)

The string format() method changed the default precision used for floating-point and complex numbers from 6 decimal places to 12, which matches the precision used by str(). (Changed by Eric Smith; bpo-5920 [https://bugs.python.org/issue?@action=redirect&bpo=5920].)

Because of an optimization for the with statement, the special methods __enter__() and __exit__() must belong to the object’s type, and cannot be directly attached to the object’s instance. This affects new-style classes (derived from object) and C extension types. (bpo-6101 [https://bugs.python.org/issue?@action=redirect&bpo=6101].)

Due to a bug in Python 2.6, the exc_value parameter to __exit__() methods was often the string representation of the exception, not an instance. This was fixed in 2.7, so exc_value will be an instance as expected. (Fixed by Florent Xicluna; bpo-7853 [https://bugs.python.org/issue?@action=redirect&bpo=7853].)

Cuando se estableció un conjunto restringido de atributos mediante __slots__, eliminar un atributo desarmado no llamaría AttributeError como cabría esperar. Corregido por Benjamin Peterson; bpo-7604 [https://bugs.python.org/issue?@action=redirect&bpo=7604].)

In the standard library:

Operations with datetime instances that resulted in a year falling outside the supported range didn’t always raise OverflowError. Such errors are now checked more carefully and will now raise the exception. (Reported by Mark Leander, patch by Anand B. Pillai and Alexander Belopolsky; bpo-7150 [https://bugs.python.org/issue?@action=redirect&bpo=7150].)

When using Decimal instances with a string’s format() method, the default alignment was previously left-alignment. This has been changed to right-alignment, which might change the output of your programs. (Changed by Mark Dickinson; bpo-6857 [https://bugs.python.org/issue?@action=redirect&bpo=6857].)

Comparisons involving a signaling NaN value (or sNAN) now signal InvalidOperation instead of silently returning a true or false value depending on the comparison operator. Quiet NaN values (or NaN) are now hashable. (Fixed by Mark Dickinson; bpo-7279 [https://bugs.python.org/issue?@action=redirect&bpo=7279].)

The ElementTree library, xml.etree, no longer escapes ampersands and angle brackets when outputting an XML processing instruction (which looks like <?xml-stylesheet href=»#style1»?>) or comment (which looks like <!– comment –>). (Patch by Neil Muller; bpo-2746 [https://bugs.python.org/issue?@action=redirect&bpo=2746].)

The readline() method of StringIO objects now does nothing when a negative length is requested, as other file-like objects do. (bpo-7348 [https://bugs.python.org/issue?@action=redirect&bpo=7348]).

The syslog module will now use the value of sys.argv[0] as the identifier instead of the previous default value of 'python'. (Changed by Sean Reifschneider; bpo-8451 [https://bugs.python.org/issue?@action=redirect&bpo=8451].)

The tarfile module’s default error handling has changed, to no longer suppress fatal errors. The default error level was previously 0, which meant that errors would only result in a message being written to the debug log, but because the debug log is not activated by default, these errors go unnoticed. The default error level is now 1, which raises an exception if there’s an error. (Changed by Lars Gustäbel; bpo-7357 [https://bugs.python.org/issue?@action=redirect&bpo=7357].)

The urlparse module’s urlsplit() now handles unknown URL schemes in a fashion compliant with RFC 3986 [https://tools.ietf.org/html/rfc3986.html]: if the URL is of the form "<something>://...", the text before the :// is treated as the scheme, even if it’s a made-up scheme that the module doesn’t know about. This change may break code that worked around the old behaviour. For example, Python 2.6.4 or 2.5 will return the following:

>>> import urlparse
>>> urlparse.urlsplit('invented://host/filename?query')
('invented', '', '//host/filename?query', '', '')

Python 2.7 (and Python 2.6.5) will return:

>>> import urlparse
>>> urlparse.urlsplit('invented://host/filename?query')
('invented', 'host', '/filename?query', '', '')

(Python 2.7 actually produces slightly different output, since it returns a named tuple instead of a standard tuple.)

For C extensions:

C extensions that use integer format codes with the PyArg_Parse* family of functions will now raise a TypeError exception instead of triggering a DeprecationWarning (bpo-5080 [https://bugs.python.org/issue?@action=redirect&bpo=5080]).

Use the new PyOS_string_to_double() function instead of the old PyOS_ascii_strtod() and PyOS_ascii_atof() functions, which are now deprecated.

For applications that embed Python:

The PySys_SetArgvEx() function was added, letting applications close a security hole when the existing PySys_SetArgv() function was used. Check whether you’re calling PySys_SetArgv() and carefully consider whether the application should be using PySys_SetArgvEx() with updatepath set to false.

New Features Added to Python 2.7 Maintenance Releases

New features may be added to Python 2.7 maintenance releases when the situation genuinely calls for it. Any such additions must go through the Python Enhancement Proposal process, and make a compelling case for why they can’t be adequately addressed by either adding the new feature solely to Python 3, or else by publishing it on the Python Package Index.

In addition to the specific proposals listed below, there is a general exemption allowing new -3 warnings to be added in any Python 2.7 maintenance release.

Two new environment variables for debug mode

In debug mode, the [xxx refs] statistic is not written by default, the PYTHONSHOWREFCOUNT environment variable now must also be set. (Contributed by Victor Stinner; bpo-31733 [https://bugs.python.org/issue?@action=redirect&bpo=31733].)

When Python is compiled with COUNT_ALLOC defined, allocation counts are no longer dumped by default anymore: the PYTHONSHOWALLOCCOUNT environment variable must now also be set. Moreover, allocation counts are now dumped into stderr, rather than stdout. (Contributed by Victor Stinner; bpo-31692 [https://bugs.python.org/issue?@action=redirect&bpo=31692].)

Nuevo en la versión 2.7.15.

PEP 434: IDLE Enhancement Exception for All Branches

PEP 434 [https://www.python.org/dev/peps/pep-0434] describes a general exemption for changes made to the IDLE development environment shipped along with Python. This exemption makes it possible for the IDLE developers to provide a more consistent user experience across all supported versions of Python 2 and 3.

For details of any IDLE changes, refer to the NEWS file for the specific release.

PEP 466: Network Security Enhancements for Python 2.7

PEP 466 [https://www.python.org/dev/peps/pep-0466] describes a number of network security enhancement proposals that have been approved for inclusion in Python 2.7 maintenance releases, with the first of those changes appearing in the Python 2.7.7 release.

PEP 466 [https://www.python.org/dev/peps/pep-0466] related features added in Python 2.7.7:

hmac.compare_digest() was backported from Python 3 to make a timing attack resistant comparison operation available to Python 2 applications. (Contributed by Alex Gaynor; bpo-21306 [https://bugs.python.org/issue?@action=redirect&bpo=21306].)

OpenSSL 1.0.1g was upgraded in the official Windows installers published on python.org. (Contributed by Zachary Ware; bpo-21462 [https://bugs.python.org/issue?@action=redirect&bpo=21462].)

PEP 466 [https://www.python.org/dev/peps/pep-0466] related features added in Python 2.7.8:

hashlib.pbkdf2_hmac() was backported from Python 3 to make a hashing algorithm suitable for secure password storage broadly available to Python 2 applications. (Contributed by Alex Gaynor; bpo-21304 [https://bugs.python.org/issue?@action=redirect&bpo=21304].)

OpenSSL 1.0.1h was upgraded for the official Windows installers published on python.org. (contributed by Zachary Ware in bpo-21671 [https://bugs.python.org/issue?@action=redirect&bpo=21671] for CVE-2014-0224)

PEP 466 [https://www.python.org/dev/peps/pep-0466] related features added in Python 2.7.9:

Most of Python 3.4’s ssl module was backported. This means ssl now supports Server Name Indication, TLS1.x settings, access to the platform certificate store, the SSLContext class, and other features. (Contributed by Alex Gaynor and David Reid; bpo-21308 [https://bugs.python.org/issue?@action=redirect&bpo=21308].)

Refer to the «Version added: 2.7.9» notes in the module documentation for specific details.

os.urandom() was changed to cache a file descriptor to /dev/urandom instead of reopening /dev/urandom on every call. (Contributed by Alex Gaynor; bpo-21305 [https://bugs.python.org/issue?@action=redirect&bpo=21305].)

hashlib.algorithms_guaranteed and hashlib.algorithms_available were backported from Python 3 to make it easier for Python 2 applications to select the strongest available hash algorithm. (Contributed by Alex Gaynor in bpo-21307 [https://bugs.python.org/issue?@action=redirect&bpo=21307])

PEP 477: Backport ensurepip (PEP 453) to Python 2.7

PEP 477 [https://www.python.org/dev/peps/pep-0477] approves the inclusion of the PEP 453 [https://www.python.org/dev/peps/pep-0453] ensurepip module and the improved documentation that was enabled by it in the Python 2.7 maintenance releases, appearing first in the Python 2.7.9 release.

Bootstrapping pip By Default

The new ensurepip module (defined in PEP 453 [https://www.python.org/dev/peps/pep-0453]) provides a standard cross-platform mechanism to bootstrap the pip installer into Python installations. The version of pip included with Python 2.7.9 is pip 1.5.6, and future 2.7.x maintenance releases will update the bundled version to the latest version of pip that is available at the time of creating the release candidate.

By default, the commands pip, pipX and pipX.Y will be installed on all platforms (where X.Y stands for the version of the Python installation), along with the pip Python package and its dependencies.

For CPython source builds on POSIX systems, the make install and make altinstall commands do not bootstrap pip by default. This behaviour can be controlled through configure options, and overridden through Makefile options.

On Windows and Mac OS X, the CPython installers now default to installing pip along with CPython itself (users may opt out of installing it during the installation process). Window users will need to opt in to the automatic PATH modifications to have pip available from the command line by default, otherwise it can still be accessed through the Python launcher for Windows as py -m pip.

As discussed in the PEP [https://www.python.org/dev/peps/pep-0477/#disabling-ensurepip-by-downstream-distributors], platform packagers may choose not to install these commands by default, as long as, when invoked, they provide clear and simple directions on how to install them on that platform (usually using the system package manager).

Documentation Changes

As part of this change, the Instalando módulos de Python and Distribuir módulos de Python sections of the documentation have been completely redesigned as short getting started and FAQ documents. Most packaging documentation has now been moved out to the Python Packaging Authority maintained Python Packaging User Guide [http://packaging.python.org] and the documentation of the individual projects.

However, as this migration is currently still incomplete, the legacy versions of those guides remaining available as Instalación de Módulos de Python (versión antigua) and Distribución de módulos de Python (versión heredada).

Ver también

PEP 453 [https://www.python.org/dev/peps/pep-0453] – Explicit bootstrapping of pip in Python installations

PEP written by Donald Stufft and Nick Coghlan, implemented by Donald Stufft, Nick Coghlan, Martin von Löwis and Ned Deily.

PEP 476: Enabling certificate verification by default for stdlib http clients

PEP 476 [https://www.python.org/dev/peps/pep-0476] updated httplib and modules which use it, such as urllib2 and xmlrpclib, to now verify that the server presents a certificate which is signed by a Certificate Authority in the platform trust store and whose hostname matches the hostname being requested by default, significantly improving security for many applications. This change was made in the Python 2.7.9 release.

For applications which require the old previous behavior, they can pass an alternate context:

import urllib2
import ssl

# This disables all verification
context = ssl._create_unverified_context()

# This allows using a specific certificate for the host, which doesn't need
# to be in the trust store
context = ssl.create_default_context(cafile="/path/to/file.crt")

urllib2.urlopen("https://invalid-cert", context=context)

PEP 493: HTTPS verification migration tools for Python 2.7

PEP 493 [https://www.python.org/dev/peps/pep-0493] provides additional migration tools to support a more incremental infrastructure upgrade process for environments containing applications and services relying on the historically permissive processing of server certificates when establishing client HTTPS connections. These additions were made in the Python 2.7.12 release.

These tools are intended for use in cases where affected applications and services can’t be modified to explicitly pass a more permissive SSL context when establishing the connection.

For applications and services which can’t be modified at all, the new PYTHONHTTPSVERIFY environment variable may be set to 0 to revert an entire Python process back to the default permissive behaviour of Python 2.7.8 and earlier.

For cases where the connection establishment code can’t be modified, but the overall application can be, the new ssl._https_verify_certificates() function can be used to adjust the default behaviour at runtime.

New make regen-all build target

To simplify cross-compilation, and to ensure that CPython can reliably be compiled without requiring an existing version of Python to already be available, the autotools-based build system no longer attempts to implicitly recompile generated files based on file modification times.

Instead, a new make regen-all command has been added to force regeneration of these files when desired (e.g. after an initial version of Python has already been built based on the pregenerated versions).

More selective regeneration targets are also defined - see Makefile.pre.in [https://github.com/python/cpython/tree/3.9/Makefile.pre.in] for details.

(Contributed by Victor Stinner in bpo-23404 [https://bugs.python.org/issue?@action=redirect&bpo=23404].)

Nuevo en la versión 2.7.14.

Removal of make touch build target

The make touch build target previously used to request implicit regeneration of generated files by updating their modification times has been removed.

It has been replaced by the new make regen-all target.

(Contributed by Victor Stinner in bpo-23404 [https://bugs.python.org/issue?@action=redirect&bpo=23404].)

Distinto en la versión 2.7.14.

Acknowledgements

The author would like to thank the following people for offering suggestions, corrections and assistance with various drafts of this article: Nick Coghlan, Philip Jenvey, Ryan Lovett, R. David Murray, Hugh Secker-Walker.

Qué hay de nuevo en Python 2.6

Autor

A.M. Kuchling (amk arroba amk.ca)

Este articulo explica las nuevas características en Python 2.6, publicado el 1 de Octubre de 2008. El calendario de publicación se describe en PEP 361 [https://www.python.org/dev/peps/pep-0361].

El tema principal de Python 2.6 es preparar el camino de migración a Python 3.0, un importante rediseño del lenguaje. Siempre que sea posible, Python 2.6 incorpora nuevas características y sintaxis de 3.0 mientras sigue siendo compatible con el código existente al no eliminar características o sintaxis más antiguas. Cuando no es posible hacer eso, Python 2.6 intenta hacer lo que puede, agregando funciones de compatibilidad en el módulo future_builtins y un interruptor -3 para advertir sobre usos que dejarán de ser compatibles en 3.0 .

Se han agregado algunos paquetes nuevos importantes a la biblioteca estándar, como los módulos multiprocessing y json, pero no hay muchas características nuevas que no estén relacionadas con Python 3.0 de alguna manera.

Python 2.6 también incluye una serie de mejoras y correcciones de errores en el código fuente. Una búsqueda en los registros de cambios encuentra que se aplicaron 259 parches y se corrigieron 612 errores entre Python 2.5 y 2.6. Es probable que ambas cifras estén subestimadas.

Este artículo no intenta proporcionar una especificación completa de las nuevas características, sino que proporciona una conveniente descripción general. Para obtener detalles completos, debe consultar la documentación de Python 2.6. Si desea comprender la justificación del diseño y la implementación, consulte el PEP de una característica nueva en particular. Siempre que sea posible, «Qué hay de nuevo en Python» enlaza con el elemento de error / parche para cada cambio.

Python 3.0

El ciclo de desarrollo de las versiones 2.6 y 3.0 de Python se sincronizó, y las versiones alfa y beta de ambos lanzamientos se realizaron los mismos días. El desarrollo de 3.0 ha influido en muchas características de 2.6.

Python 3.0 es un rediseño de Python de gran alcance que rompe la compatibilidad con la serie 2.x. Esto significa que el código Python existente necesitará alguna conversión para poder ejecutarse en Python 3.0. Sin embargo, no todos los cambios en 3.0 rompen necesariamente la compatibilidad. En los casos en que las nuevas funciones no provoquen la rotura del código existente, se han actualizado a 2.6 y se describen en este documento en el lugar correspondiente. Algunas de las características derivadas de 3.0 son:

El método __complex__() para convertir objetos en un número complejo.

Sintaxis alternativa para detectar excepciones: except TypeError as exc.

La adición de functools.reduce() como sinónimo de la función incorporada reduce().

Python 3.0 agrega varias funciones integradas nuevas y cambia la semántica de algunas integradas existentes. Las funciones que son nuevas en 3.0 como bin() simplemente se han agregado a Python 2.6, pero las funciones existentes no se han cambiado; en cambio, el módulo future_builtins tiene versiones con la nueva semántica 3.0. El código escrito puede ser compatible con 3.0 haciendo from future_builtins import hex, map según sea necesario.

Un nuevo modificador de línea de comandos, -3, habilita advertencias sobre características que se eliminarán en Python 3.0. Puede ejecutar código con este modificador para ver cuánto trabajo será necesario para migrar el código a 3.0. El valor de este modificador está disponible para el código Python como la variable booleana sys.py3kwarning, y para el código de extensión C como Py_Py3kWarningFlag.

Ver también

Las series 3xxx de PEP, que contienen propuestas para Python 3.0. PEP 3000 [https://www.python.org/dev/peps/pep-3000] describe el proceso de desarrollo de Python 3.0. Empiece con PEP 3100 [https://www.python.org/dev/peps/pep-3100] que describe los objetivos generales de Python 3.0, y luego explore los PEPS con números más altos que proponen características específicas.

Cambios en el proceso de desarrollo

Mientras se desarrollaba 2.6, el proceso de desarrollo de Python experimentó dos cambios significativos: cambiamos del seguidor de incidentes (issue tracker) de SourceForge a una instalación personalizada de Roundup, y la documentación se convirtió de LaTeX a reStructuredText.

Nuevo seguidor de incidentes: Roundup

Durante mucho tiempo, los desarrolladores de Python estaban cada vez más molestos por el seguidor de errores de SourceForge. La solución alojada en SourceForge no permite mucha personalización; por ejemplo, no fue posible personalizar el ciclo de vida de los problemas.

Por lo tanto, el comité de infraestructura de la Python Software Foundation publicó una convocatoria sobre el seguimiento de incidentes, pidiendo a los voluntarios que configuren diferentes productos e importen algunos de los errores y parches de SourceForge. Se examinaron cuatro seguidores diferentes: Jira <https://www.atlassian.com/software/jira/> __, Launchpad <https://launchpad.net/> __, Roundup [http://roundup.sourceforge.net/] y Trac [https://trac.edgewall.org/]. El comité finalmente se decidió por Jira y Roundup como los dos candidatos. Jira es un producto comercial que ofrece instancias alojadas sin costo para proyectos de software libre; Roundup es un proyecto de código abierto que requiere voluntarios para administrarlo y un servidor para alojarlo.

Después de publicar una llamada para voluntarios, se configuró una nueva instalación de Roundup en https://bugs.python.org. Una instalación de Roundup puede alojar varios seguidores, y este servidor ahora también aloja seguidores de problemas para Jython y para el sitio web de Python. Seguramente encontrará otros usos en el futuro. Siempre que sea posible, esta edición de «Qué hay de nuevo en Python» se vincula al elemento de error/parche para cada cambio.

Upfront Systems <http://www.upfrontsoftware.co.za> __ de Stellenbosch, Sudáfrica, proporciona amablemente el alojamiento del seguidor de errores de Python. Martin von Löwis se esforzó mucho en importar errores y parches existentes desde SourceForge. Sus scripts para esta operación de importación se encuentran en http://svn.python.org/view/tracker/importer/ y pueden ser útiles para otros proyectos que deseen pasar de SourceForge a Roundup.

Ver también

https://bugs.python.org

El seguidor de errores de Python.

http://bugs.jython.org:

El seguidor de errores de Jython.

http://roundup.sourceforge.net/

Descargas y documentación de Roundup.

http://svn.python.org/view/tracker/importer/

Scripts de conversión de Martin von Löwis.

Nuevo formato de documentación: texto reestructurado con Sphinx

La documentación de Python se escribió usando LaTeX desde que el proyecto comenzó alrededor de 1989. En la década de 1980 y principios de la de 1990, la mayor parte de la documentación se imprimió para su estudio posterior, no se vio en línea. LaTeX fue ampliamente utilizado porque proporcionaba una salida impresa atractiva sin dejar de ser sencillo de escribir una vez que se aprendían las reglas básicas de marcado.

Hoy en día, LaTeX todavía se usa para escribir publicaciones destinadas a la impresión, pero el panorama de las herramientas de programación ha cambiado. Ya no imprimimos montones de documentación; en su lugar, lo navegamos en línea y HTML se ha convertido en el formato más importante para dar soporte. Desafortunadamente, convertir LaTeX a HTML es bastante complicado y Fred L. Drake Jr., el editor de documentación de Python desde hace mucho tiempo, pasó mucho tiempo manteniendo el proceso de conversión. De vez en cuando, la gente sugeriría convertir la documentación a SGML y luego a XML, pero realizar una buena conversión es una tarea importante y nadie comprometió el tiempo necesario para terminar el trabajo.

Durante el ciclo de desarrollo 2.6, Georg Brandl se esforzó mucho en crear una nueva cadena de herramientas para procesar la documentación. El paquete resultante se llama Sphinx y está disponible en http://sphinx-doc.org/.

Sphinx se concentra en la salida HTML, produciendo HTML moderno y con un estilo atractivo; la salida impresa todavía se admite mediante la conversión a LaTeX. El formato de entrada es reStructuredText, una sintaxis de marcado que admite extensiones y directivas personalizadas que se usa comúnmente en la comunidad de Python.

Sphinx es un paquete independiente que se puede usar para escribir, y casi dos docenas de otros proyectos (enumerados en el sitio web de Sphinx [https://www.sphinx-doc.org/en/master/examples.html]) han adoptado Sphinx como su herramienta de documentación.

Ver también

Documentando Python [https://devguide.python.org/documenting/]

Describe cómo escribir para la documentación de Python.

Sphinx [http://sphinx-doc.org/]

Documentación y código para la cadena de herramientas Sphinx.

Docutils [http://docutils.sourceforge.net]

El analizador sintáctico y el conjunto de herramientas reStructuredText subyacentes.

PEP 343: La sentencia “with”

La versión anterior, Python 2.5, agregó la instrucción “with” como una característica opcional, para ser habilitada por una directiva from __future__ import with_statement. En 2.6, la instrucción ya no necesita estar habilitada especialmente; esto significa que ahora with es siempre una palabra clave. El resto de esta sección es una copia de la sección correspondiente del documento «Qué hay de nuevo en Python 2.5»; si está familiarizado con la declaración “with” de Python 2.5, puede omitir esta sección.

La sentencia “with” resuelve el código que anteriormente usaría bloques try…finally` para garantizar que el código de limpieza se ejecute. En esta sección, discutiré como se usará comúnmente la declaración. En la siguiente sección, examinaré los detalles de la implementación y mostraré cómo escribir objetos para usar con esta declaración.

La sentencia “with” es una estructura de control de flujo cuya estructura básica es:

with expression [as variable]:
    with-block

La expresión se evalúa y debe dar como resultado un objeto que admita el protocolo de administración de contexto (es decir, tiene los métodos __enter__() y __exit__()).

El objeto __enter__() se llama antes de que se ejecute with-block y, por lo tanto, se puede ejecutar código de configuración. También, si se proporciona, puede retornar un valor que esté vinculado al nombre variable. (Tenga en cuenta que a la variable no se le asigna el resultado de la expression).

Una vez finalizada la ejecución de with-block, se llama al método __exit__() del objeto, incluso si el bloque generó una excepción y, por lo tanto, puede ejecutar código de limpieza.

Algunos objetos estándar de Python ahora admiten el protocolo de administración de contexto y se pueden usar con la sentencia “with”. Los objetos de archivo son un ejemplo:

with open('/etc/passwd', 'r') as f:
    for line in f:
        print line
        ... more processing code ...

Después de que se haya ejecutado esta sentencia, el objeto de archivo en f se habrá cerrado automáticamente, incluso si el bucle for generó una excepción en la mitad del bloque.

Nota

En este caso, f es el mismo objeto creado por open(), porque file.__enter__() retorna self.

Los locks y las condiciones variables del módulo threading también admiten la sentencia “with”:

lock = threading.Lock()
with lock:
    # Critical section of code
    ...

El lock se adquiere antes de que se ejecute el bloque y siempre se libera una vez que este se completa.

La función localcontext() en el módulo decimal facilita guardar y restaurar el contexto decimal actual, que encapsula la precisión deseada y las características de redondeo para los cálculos:

from decimal import Decimal, Context, localcontext

# Displays with default precision of 28 digits
v = Decimal('578')
print v.sqrt()

with localcontext(Context(prec=16)):
    # All code in this block uses a precision of 16 digits.
    # The original context is restored on exiting the block.
    print v.sqrt()

Escribiendo gestores de contexto

Por detrás, la sentencia “with” es bastante complicada. La mayoría de las personas solo usarán “with” en compañía de objetos existentes y no necesitan conocer estos detalles, por lo que puede omitir el resto de esta sección si lo desea. Los autores de nuevos objetos deberán comprender los detalles de la implementación subyacente y deben seguir leyendo.

Una explicación de alto nivel del protocolo de gestor de contexto es:

La expresión se evalúa y debería dar como resultado un objeto llamado «gestor de contexto». El gestor de contexto debe tener los métodos __enter__() y __exit__().

Se llama al método __enter__() del gestor de contexto. El valor retornado se asigna a VAR. Si no hay una cláusula as VAR, el valor simplemente se descarta.

Se ejecuta el código en BLOCK.

Si BLOCK lanza una excepción, se llama al método __exit__() del gestor de contexto con tres argumentos, los detalles de la excepción (type, value, traceback, los mismos valores retornados por sys.exc_info(), que también puede ser None si no se produjo ninguna excepción). El valor de retorno del método controla si se vuelve a generar una excepción: cualquier valor false vuelve a lanzar la excepción, y True resultará en inhibirla. Rara vez querrá suprimir la excepción, porque si lo hace, el autor del código que contenga la sentencia “with” nunca se dará cuenta de que algo salió mal.

Si BLOCK no lanzó una excepción, el método __exit__() continúa llamándose, pero type, value y traceback son todos``None``.

Pensemos en un ejemplo. No presentaré un código detallado, solo bosquejaré los métodos necesarios para una base de datos que admita transacciones.

(Para las personas que no están familiarizadas con la terminología de la base de datos: un conjunto de cambios en la base de datos se agrupa en una transacción. Las transacciones pueden confirmarse, lo que significa que todos los cambios se escriben en la base de datos, o deshacerse, lo que significa que todos los cambios se descartan y la base de datos no ha cambiado. Consulte cualquier libro de texto de base de datos para obtener más información.)

Supongamos que hay un objeto que representa una conexión de base de datos. Nuestro objetivo será permitir que el usuario escriba un código como este:

db_connection = DatabaseConnection()
with db_connection as cursor:
    cursor.execute('insert into ...')
    cursor.execute('delete from ...')
    # ... more operations ...

La transacción debe confirmarse si el código del bloque se ejecuta sin problemas o revertirse si hay una excepción. Aquí está la interfaz básica para DatabaseConnection que asumiré:

class DatabaseConnection:
    # Database interface
    def cursor(self):
        "Returns a cursor object and starts a new transaction"
    def commit(self):
        "Commits current transaction"
    def rollback(self):
        "Rolls back current transaction"

El método __enter__() es bastante fácil, ya que solo tiene que iniciar una nueva transacción. Para esta aplicación, el objeto cursor resultante sería un resultado útil, por lo que el método lo retornará. Luego, el usuario puede agregar as cursor a su sentencia “with” para vincular el cursor a un nombre de variable.

class DatabaseConnection:
    ...
    def __enter__(self):
        # Code to start a new transaction
        cursor = self.cursor()
        return cursor

El método __exit__() es el más complicado porque es donde se debe realizar la mayor parte del trabajo. El método debe verificar si ocurrió una excepción. Si no hubo excepción, la transacción se confirma. La transacción se revierte si hubo una excepción.

En el siguiente código, la ejecución simplemente caerá al final de la función, retornando el valor predeterminado None. None es falso, por lo que la excepción se volverá a lanzar automáticamente. Si lo desea, puede ser más explícito y agregar una sentencia return en la ubicación marcada.

class DatabaseConnection:
    ...
    def __exit__(self, type, value, tb):
        if tb is None:
            # No exception, so commit
            self.commit()
        else:
            # Exception occurred, so rollback.
            self.rollback()
            # return False

El módulo contextlib

El módulo contextlib proporciona algunas funciones y un decorador que son útiles al escribir objetos para usar con la sentencia “with”.

El decorador se llama contextmanager(), y te permite escribir una única función generadora en lugar de definir una clase nueva. El generador debería producir exactamente un valor. El código hasta yield se ejecutará como el método __enter__(), y el valor obtenido será el valor de retorno del método que se vinculará a la variable en la clausula as (si la hay) de la sentencia “with”. El código después de yield se ejecutará en el método __exit__() . Cualquier excepción lanzada en el bloque será generada por la sentencia yield.

Usando este decorador, nuestro ejemplo de base de datos de la sección anterior podría escribirse como:

from contextlib import contextmanager

@contextmanager
def db_transaction(connection):
    cursor = connection.cursor()
    try:
        yield cursor
    except:
        connection.rollback()
        raise
    else:
        connection.commit()

db = DatabaseConnection()
with db_transaction(db) as cursor:
    ...

El módulo contextlib también tiene una función nested(mgr1, mgr2, ...) que combina varios gestores de contexto para que no necesite escribir sentencias “with” anidadas. En este ejemplo, se utiliza una única sentencia “with” que inicia una transacción de base de datos y adquiere un bloqueo del hilo:

lock = threading.Lock()
with nested (db_transaction(db), lock) as (cursor, locked):
    ...

Por último, la función close() retorna su argumento para que pueda vincularse a una variable, y llama al método .close() del argumento al final del bloque.

import urllib, sys
from contextlib import closing

with closing(urllib.urlopen('http://www.yahoo.com')) as f:
    for line in f:
        sys.stdout.write(line)

Ver también

PEP 343 [https://www.python.org/dev/peps/pep-0343] - La sentencia «with»

PEP escrito por Guido van Rossum y Nick Coghlan; implementado por Mike Bland, Guido van Rossum y Neal Norwitz. El PEP muestra el código generado para una sentencia “with”, que puede ser útil para aprender cómo la sentencia funciona.

La documentación para el módulo contextlib.

PEP 366: Importaciones relativas explícitas desde un módulo principal

El modificador de Python -m permite ejecutar un módulo como un script. Cuando ejecutabas un módulo que estaba ubicado dentro de un paquete, las importaciones relativas no funcionaban correctamente.

La corrección para Python 2.6 agrega un atributo __package__ a los módulos. Cuando este atributo está presente, las importaciones relativas serán relativas al valor de este atributo en lugar del atributo __name__.

Las importaciones de estilo PEP 302 pueden configurar __package__ según sea necesario. El módulo runpy que implementa el modificador -m ahora hace esto, por lo que las importaciones relativas ahora funcionarán correctamente en los scripts que se ejecutan desde el interior de un paquete.

PEP 370: Directorio de site-packages por usuario

Cuando ejecutas Python, la ruta de búsqueda del módulo sys.path generalmente incluye un directorio cuya ruta termina en "site-packages". Este directorio está destinado a contener paquetes instalados localmente disponibles para todos los usuarios que utilizan una máquina o un sitio de instalación en particular.

Python 2.6 introduce una convención para directorios de sitios específicos del usuario. El directorio varía según la plataforma:

Unix y Mac OS X: ~/.local/

Windows: %APPDATA%/Python

Dentro de este directorio, habrá subdirectorios específicos de versión, como lib/python2.6/site-packages en Unix/Mac OS y Python26/site-packages en Windows.

Si no le gusta el directorio predeterminado, puede sobrescribirlo mediante una variable de entorno. PYTHONUSERBASE establece el directorio raíz utilizado para todas las versiones de Python que admiten esta función. En Windows, el directorio de datos específicos de la aplicación se puede cambiar configurando la variable de entorno APPDATA. También puede modificar el archivo site.py para su instalación de Python.

La característica se puede desactivar por completo ejecutando Python con la opción -s o seteando la variable de entorno PYTHONNOUSERSITE.

Ver también

PEP 370: Directorio de site-packages por usuario

PEP escrito e implementado por Christian Heimes.

PEP 371: El paquete multiprocessing

El nuevo paquete multiprocessing permite a los programas de Python crear nuevos procesos que realizarán un cálculo y retornaran un resultado al padre. Los procesos padre e hijo pueden comunicarse mediante colas (queues) y tuberías (pipes), sincronizar sus operaciones mediante bloqueos y semáforos, y pueden compartir matrices simples de datos.

El módulo multiprocessing comenzó como una emulación exacta del módulo threading usando procesos en lugar de hilos. Ese objetivo se descartó en el camino a Python 2.6, pero el enfoque general del módulo sigue siendo similar. La clase fundamental es Process, a la que se le pasa un objeto invocable y una colección de argumentos. El método start() establece el invocable ejecutándose en un subproceso, después de lo cual se puede llamar al método is_alive() para verificar si el subproceso aún se está ejecutando y al método join() para esperar al proceso para salir.

Aquí hay un ejemplo simple donde el subproceso calculará un factorial. La función que realiza el cálculo está escrita de forma extraña, por lo que lleva mucho más tiempo cuando el argumento de entrada es un múltiplo de 4.

import time
from multiprocessing import Process, Queue

def factorial(queue, N):
    "Compute a factorial."
    # If N is a multiple of 4, this function will take much longer.
    if (N % 4) == 0:
        time.sleep(.05 * N/4)

    # Calculate the result
    fact = 1L
    for i in range(1, N+1):
        fact = fact * i

    # Put the result on the queue
    queue.put(fact)

if __name__ == '__main__':
    queue = Queue()

    N = 5

    p = Process(target=factorial, args=(queue, N))
    p.start()
    p.join()

    result = queue.get()
    print 'Factorial', N, '=', result

Un Queue se usa para comunicar el resultado del factorial. El objeto Queue se almacena en una variable global. El proceso hijo usará el valor de la variable cuando se creó el hijo; porque es una Queue, padre e hijo pueden usar el objeto para comunicarse. (Si el padre cambiara el valor de la variable global, el valor del hijo no se vería afectado y viceversa).

Otras dos clases, Pool y Manager, proporcionan interfaces de nivel superior. Pool creará un número fijo de procesos de trabajo, y las solicitudes se pueden distribuir a los trabajadores llamando a apply() o apply_async() para agregar una sola solicitud, y map() o map_async() para agregar una serie de solicitudes. El siguiente código usa Pool para distribuir las solicitudes en 5 procesos de trabajo y recuperar una lista de resultados:

from multiprocessing import Pool

def factorial(N, dictionary):
    "Compute a factorial."
    ...
p = Pool(5)
result = p.map(factorial, range(1, 1000, 10))
for v in result:
    print v

Esto produce la siguiente salida:

1
39916800
51090942171709440000
8222838654177922817725562880000000
33452526613163807108170062053440751665152000000000
...

La otra interfaz de alto nivel, la clase Manager, crea un proceso de servidor separado que puede contener copias maestras de las estructuras de datos de Python. Luego, otros procesos pueden acceder y modificar estas estructuras de datos utilizando objetos proxy. El siguiente ejemplo crea un diccionario compartido llamando al método dict(); los procesos de trabajo luego insertan valores en el diccionario. (El bloqueo no se realiza automáticamente, lo cual no importa en este ejemplo. Los métodos de Manager también incluyen Lock(), RLock(), y Semaphore() para crear bloqueos compartidos.)

import time
from multiprocessing import Pool, Manager

def factorial(N, dictionary):
    "Compute a factorial."
    # Calculate the result
    fact = 1L
    for i in range(1, N+1):
        fact = fact * i

    # Store result in dictionary
    dictionary[N] = fact

if __name__ == '__main__':
    p = Pool(5)
    mgr = Manager()
    d = mgr.dict()         # Create shared dictionary

    # Run tasks using the pool
    for N in range(1, 1000, 10):
        p.apply_async(factorial, (N, d))

    # Mark pool as closed -- no more tasks can be added.
    p.close()

    # Wait for tasks to exit
    p.join()

    # Output results
    for k, v in sorted(d.items()):
        print k, v

Esto producirá la salida:

1 1
11 39916800
21 51090942171709440000
31 8222838654177922817725562880000000
41 33452526613163807108170062053440751665152000000000
51 15511187532873822802242430164693032110632597200169861120000...

Ver también

La documentación del módulo multiprocessing.

PEP 371 [https://www.python.org/dev/peps/pep-0371] - Adición del paquete de multiprocesamiento

PEP escrito por Jesse Noller y Richard Oudkerk; implementado por Richard Oudkerk y Jesse Noller.

PEP 3101: Formateo avanzado de cadena de caracteres

En Python 3.0, el operador % se complementa con un método de formato de cadena de caracteres más potente, format(). La compatibilidad con el método str.format() se ha actualizado a Python 2.6.

En 2.6, las cadenas de caracteres de 8 bits y Unicode tienen un método .format() que trata la cadena como una plantilla y toma los argumentos a formatear. La plantilla de formato utiliza llaves ({, }) como caracteres especiales:

>>> # Substitute positional argument 0 into the string.
>>> "User ID: {0}".format("root")
'User ID: root'
>>> # Use the named keyword arguments
>>> "User ID: {uid}   Last seen: {last_login}".format(
...    uid="root",
...    last_login = "5 Mar 2008 07:20")
'User ID: root   Last seen: 5 Mar 2008 07:20'

Las llaves se pueden escapar duplicándose:

>>> "Empty dict: {{}}".format()
"Empty dict: {}"

Los nombres de campo pueden ser números enteros que indican argumentos posicionales, como {0}, {1}, etc. o nombres de argumentos de palabras clave. También puede proporcionar nombres de campos compuestos que lean atributos o accedan a claves de diccionario:

>>> import sys
>>> print 'Platform: {0.platform}\nPython version: {0.version}'.format(sys)
Platform: darwin
Python version: 2.6a1+ (trunk:61261M, Mar  5 2008, 20:29:41)
[GCC 4.0.1 (Apple Computer, Inc. build 5367)]'

>>> import mimetypes
>>> 'Content-type: {0[.mp4]}'.format(mimetypes.types_map)
'Content-type: video/mp4'

Tenga en cuenta que cuando utilice una notación de estilo diccionario como [.mp4], no es necesario poner comillas alrededor de la cadena; se buscará el valor usando .mp4 como clave. Las cadenas de caracteres que comienzan con un número se convertirán en entero. No puede escribir expresiones más complicadas dentro de una cadena de formato.

Hasta ahora hemos mostrado cómo especificar qué campo sustituir en la cadena resultante. El formato preciso utilizado también se puede controlar agregando dos puntos seguidos de un especificador de formato. Por ejemplo:

>>> # Field 0: left justify, pad to 15 characters
>>> # Field 1: right justify, pad to 6 characters
>>> fmt = '{0:15} ${1:>6}'
>>> fmt.format('Registration', 35)
'Registration    $    35'
>>> fmt.format('Tutorial', 50)
'Tutorial        $    50'
>>> fmt.format('Banquet', 125)
'Banquet         $   125'

Los especificadores de formato pueden hacer referencia a otros campos a través del anidamiento:

>>> fmt = '{0:{1}}'
>>> width = 15
>>> fmt.format('Invoice #1234', width)
'Invoice #1234  '
>>> width = 35
>>> fmt.format('Invoice #1234', width)
'Invoice #1234                      '

Se puede especificar la alineación de un campo dentro del ancho deseado:

Carácter

Efecto

< (por defecto)

Alinear a la izquierda

>

Alinear a la derecha

^

Centrado

=

(Solo para tipos numéricos) Relleno después del signo.

Los especificadores de formato también pueden incluir un tipo de presentación, que controla cómo se formatea el valor. Por ejemplo, los números de punto flotante pueden formatearse como un número general o en notación exponencial:

>>> '{0:g}'.format(3.75)
'3.75'
>>> '{0:e}'.format(3.75)
'3.750000e+00'

Hay una variedad de tipos de presentación disponibles. Consulte la documentación 2.6 para obtener una lista completa; aquí hay un ejemplo:

b

Binario. Emite el número en base 2.

c

Character. Converts the integer to the corresponding Unicode character before printing.

d

Decimal Integer. Outputs the number in base 10.

o

Octal format. Outputs the number in base 8.

x

Hex format. Outputs the number in base 16, using lower-case letters for the digits above 9.

e

Exponent notation. Prints the number in scientific notation using the letter “e” to indicate the exponent.

g

General format. This prints the number as a fixed-point number, unless the number is too large, in which case it switches to “e” exponent notation.

n

Number. This is the same as “g” (for floats) or “d” (for integers), except that it uses the current locale setting to insert the appropriate number separator characters.

%

Percentage. Multiplies the number by 100 and displays in fixed (“f”) format, followed by a percent sign.

Classes and types can define a __format__() method to control how they’re formatted. It receives a single argument, the format specifier:

def __format__(self, format_spec):
    if isinstance(format_spec, unicode):
        return unicode(str(self))
    else:
        return str(self)

There’s also a format() builtin that will format a single value. It calls the type’s __format__() method with the provided specifier:

>>> format(75.6564, '.2f')
'75.66'

Ver también

Sintaxis de formateo de cadena

The reference documentation for format fields.

PEP 3101 [https://www.python.org/dev/peps/pep-3101] - Advanced String Formatting

PEP written by Talin. Implemented by Eric Smith.

PEP 3105: print As a Function

The print statement becomes the print() function in Python 3.0. Making print() a function makes it possible to replace the function by doing def print(...) or importing a new function from somewhere else.

Python 2.6 has a __future__ import that removes print as language syntax, letting you use the functional form instead. For example:

>>> from __future__ import print_function
>>> print('# of entries', len(dictionary), file=sys.stderr)

The signature of the new function is:

def print(*args, sep=' ', end='\n', file=None)

The parameters are:

args: positional arguments whose values will be printed out.

sep: the separator, which will be printed between arguments.

end: the ending text, which will be printed after all of the arguments have been output.

file: the file object to which the output will be sent.

Ver también

PEP 3105 [https://www.python.org/dev/peps/pep-3105] - Make print a function

PEP written by Georg Brandl.

PEP 3110: Exception-Handling Changes

One error that Python programmers occasionally make is writing the following code:

try:
    ...
except TypeError, ValueError:  # Wrong!
    ...

The author is probably trying to catch both TypeError and ValueError exceptions, but this code actually does something different: it will catch TypeError and bind the resulting exception object to the local name "ValueError". The ValueError exception will not be caught at all. The correct code specifies a tuple of exceptions:

try:
    ...
except (TypeError, ValueError):
    ...

This error happens because the use of the comma here is ambiguous: does it indicate two different nodes in the parse tree, or a single node that’s a tuple?

Python 3.0 makes this unambiguous by replacing the comma with the word «as». To catch an exception and store the exception object in the variable exc, you must write:

try:
    ...
except TypeError as exc:
    ...

Python 3.0 will only support the use of «as», and therefore interprets the first example as catching two different exceptions. Python 2.6 supports both the comma and «as», so existing code will continue to work. We therefore suggest using «as» when writing new Python code that will only be executed with 2.6.

Ver también

PEP 3110 [https://www.python.org/dev/peps/pep-3110] - Catching Exceptions in Python 3000

PEP written and implemented by Collin Winter.

PEP 3112: Byte Literals

Python 3.0 adopts Unicode as the language’s fundamental string type and denotes 8-bit literals differently, either as b'string' or using a bytes constructor. For future compatibility, Python 2.6 adds bytes as a synonym for the str type, and it also supports the b'' notation.

The 2.6 str differs from 3.0’s bytes type in various ways; most notably, the constructor is completely different. In 3.0, bytes([65, 66, 67]) is 3 elements long, containing the bytes representing ABC; in 2.6, bytes([65, 66, 67]) returns the 12-byte string representing the str() of the list.

The primary use of bytes in 2.6 will be to write tests of object type such as isinstance(x, bytes). This will help the 2to3 converter, which can’t tell whether 2.x code intends strings to contain either characters or 8-bit bytes; you can now use either bytes or str to represent your intention exactly, and the resulting code will also be correct in Python 3.0.

There’s also a __future__ import that causes all string literals to become Unicode strings. This means that \u escape sequences can be used to include Unicode characters:

from __future__ import unicode_literals

s = ('\u751f\u3080\u304e\u3000\u751f\u3054'
     '\u3081\u3000\u751f\u305f\u307e\u3054')

print len(s)               # 12 Unicode characters

At the C level, Python 3.0 will rename the existing 8-bit string type, called PyStringObject in Python 2.x, to PyBytesObject. Python 2.6 uses #define to support using the names PyBytesObject(), PyBytes_Check(), PyBytes_FromStringAndSize(), and all the other functions and macros used with strings.

Instances of the bytes type are immutable just as strings are. A new bytearray type stores a mutable sequence of bytes:

>>> bytearray([65, 66, 67])
bytearray(b'ABC')
>>> b = bytearray(u'\u21ef\u3244', 'utf-8')
>>> b
bytearray(b'\xe2\x87\xaf\xe3\x89\x84')
>>> b[0] = '\xe3'
>>> b
bytearray(b'\xe3\x87\xaf\xe3\x89\x84')
>>> unicode(str(b), 'utf-8')
u'\u31ef \u3244'

Byte arrays support most of the methods of string types, such as startswith()/endswith(), find()/rfind(), and some of the methods of lists, such as append(), pop(), and reverse().

>>> b = bytearray('ABC')
>>> b.append('d')
>>> b.append(ord('e'))
>>> b
bytearray(b'ABCde')

There’s also a corresponding C API, with PyByteArray_FromObject(), PyByteArray_FromStringAndSize(), and various other functions.

Ver también

PEP 3112 [https://www.python.org/dev/peps/pep-3112] - Bytes literals in Python 3000

PEP written by Jason Orendorff; backported to 2.6 by Christian Heimes.

PEP 3116: New I/O Library

Python’s built-in file objects support a number of methods, but file-like objects don’t necessarily support all of them. Objects that imitate files usually support read() and write(), but they may not support readline(), for example. Python 3.0 introduces a layered I/O library in the io module that separates buffering and text-handling features from the fundamental read and write operations.

There are three levels of abstract base classes provided by the io module:

RawIOBase defines raw I/O operations: read(), readinto(), write(), seek(), tell(), truncate(), and close(). Most of the methods of this class will often map to a single system call. There are also readable(), writable(), and seekable() methods for determining what operations a given object will allow.

Python 3.0 has concrete implementations of this class for files and sockets, but Python 2.6 hasn’t restructured its file and socket objects in this way.

BufferedIOBase is an abstract base class that buffers data in memory to reduce the number of system calls used, making I/O processing more efficient. It supports all of the methods of RawIOBase, and adds a raw attribute holding the underlying raw object.

There are five concrete classes implementing this ABC. BufferedWriter and BufferedReader are for objects that support write-only or read-only usage that have a seek() method for random access. BufferedRandom objects support read and write access upon the same underlying stream, and BufferedRWPair is for objects such as TTYs that have both read and write operations acting upon unconnected streams of data. The BytesIO class supports reading, writing, and seeking over an in-memory buffer.

TextIOBase: Provides functions for reading and writing strings (remember, strings will be Unicode in Python 3.0), and supporting universal newlines. TextIOBase defines the readline() method and supports iteration upon objects.

There are two concrete implementations. TextIOWrapper wraps a buffered I/O object, supporting all of the methods for text I/O and adding a buffer attribute for access to the underlying object. StringIO simply buffers everything in memory without ever writing anything to disk.

(In Python 2.6, io.StringIO is implemented in pure Python, so it’s pretty slow. You should therefore stick with the existing StringIO module or cStringIO for now. At some point Python 3.0’s io module will be rewritten into C for speed, and perhaps the C implementation will be backported to the 2.x releases.)

In Python 2.6, the underlying implementations haven’t been restructured to build on top of the io module’s classes. The module is being provided to make it easier to write code that’s forward-compatible with 3.0, and to save developers the effort of writing their own implementations of buffering and text I/O.

Ver también

PEP 3116 [https://www.python.org/dev/peps/pep-3116] - New I/O

PEP written by Daniel Stutzbach, Mike Verdone, and Guido van Rossum. Code by Guido van Rossum, Georg Brandl, Walter Doerwald, Jeremy Hylton, Martin von Löwis, Tony Lownds, and others.

PEP 3118: Revised Buffer Protocol

The buffer protocol is a C-level API that lets Python types exchange pointers into their internal representations. A memory-mapped file can be viewed as a buffer of characters, for example, and this lets another module such as re treat memory-mapped files as a string of characters to be searched.

The primary users of the buffer protocol are numeric-processing packages such as NumPy, which expose the internal representation of arrays so that callers can write data directly into an array instead of going through a slower API. This PEP updates the buffer protocol in light of experience from NumPy development, adding a number of new features such as indicating the shape of an array or locking a memory region.

The most important new C API function is PyObject_GetBuffer(PyObject *obj, Py_buffer *view, int flags), which takes an object and a set of flags, and fills in the Py_buffer structure with information about the object’s memory representation. Objects can use this operation to lock memory in place while an external caller could be modifying the contents, so there’s a corresponding PyBuffer_Release(Py_buffer *view) to indicate that the external caller is done.

The flags argument to PyObject_GetBuffer() specifies constraints upon the memory returned. Some examples are:

PyBUF_WRITABLE indicates that the memory must be writable.

PyBUF_LOCK requests a read-only or exclusive lock on the memory.

PyBUF_C_CONTIGUOUS and PyBUF_F_CONTIGUOUS requests a C-contiguous (last dimension varies the fastest) or Fortran-contiguous (first dimension varies the fastest) array layout.

Two new argument codes for PyArg_ParseTuple(), s* and z*, return locked buffer objects for a parameter.

Ver también

PEP 3118 [https://www.python.org/dev/peps/pep-3118] - Revising the buffer protocol

PEP written by Travis Oliphant and Carl Banks; implemented by Travis Oliphant.

PEP 3119: Abstract Base Classes

Some object-oriented languages such as Java support interfaces, declaring that a class has a given set of methods or supports a given access protocol. Abstract Base Classes (or ABCs) are an equivalent feature for Python. The ABC support consists of an abc module containing a metaclass called ABCMeta, special handling of this metaclass by the isinstance() and issubclass() builtins, and a collection of basic ABCs that the Python developers think will be widely useful. Future versions of Python will probably add more ABCs.

Let’s say you have a particular class and wish to know whether it supports dictionary-style access. The phrase «dictionary-style» is vague, however. It probably means that accessing items with obj[1] works. Does it imply that setting items with obj[2] = value works? Or that the object will have keys(), values(), and items() methods? What about the iterative variants such as iterkeys()? copy() and update()? Iterating over the object with iter()?

The Python 2.6 collections module includes a number of different ABCs that represent these distinctions. Iterable indicates that a class defines __iter__(), and Container means the class defines a __contains__() method and therefore supports x in y expressions. The basic dictionary interface of getting items, setting items, and keys(), values(), and items(), is defined by the MutableMapping ABC.

You can derive your own classes from a particular ABC to indicate they support that ABC’s interface:

import collections

class Storage(collections.MutableMapping):
    ...

Alternatively, you could write the class without deriving from the desired ABC and instead register the class by calling the ABC’s register() method:

import collections

class Storage:
    ...

collections.MutableMapping.register(Storage)

For classes that you write, deriving from the ABC is probably clearer. The register() method is useful when you’ve written a new ABC that can describe an existing type or class, or if you want to declare that some third-party class implements an ABC. For example, if you defined a PrintableType ABC, it’s legal to do:

# Register Python's types
PrintableType.register(int)
PrintableType.register(float)
PrintableType.register(str)

Classes should obey the semantics specified by an ABC, but Python can’t check this; it’s up to the class author to understand the ABC’s requirements and to implement the code accordingly.

To check whether an object supports a particular interface, you can now write:

def func(d):
    if not isinstance(d, collections.MutableMapping):
        raise ValueError("Mapping object expected, not %r" % d)

Don’t feel that you must now begin writing lots of checks as in the above example. Python has a strong tradition of duck-typing, where explicit type-checking is never done and code simply calls methods on an object, trusting that those methods will be there and raising an exception if they aren’t. Be judicious in checking for ABCs and only do it where it’s absolutely necessary.

You can write your own ABCs by using abc.ABCMeta as the metaclass in a class definition:

from abc import ABCMeta, abstractmethod

class Drawable():
    __metaclass__ = ABCMeta

    @abstractmethod
    def draw(self, x, y, scale=1.0):
        pass

    def draw_doubled(self, x, y):
        self.draw(x, y, scale=2.0)

class Square(Drawable):
    def draw(self, x, y, scale):
        ...

In the Drawable ABC above, the draw_doubled() method renders the object at twice its size and can be implemented in terms of other methods described in Drawable. Classes implementing this ABC therefore don’t need to provide their own implementation of draw_doubled(), though they can do so. An implementation of draw() is necessary, though; the ABC can’t provide a useful generic implementation.

You can apply the @abstractmethod decorator to methods such as draw() that must be implemented; Python will then raise an exception for classes that don’t define the method. Note that the exception is only raised when you actually try to create an instance of a subclass lacking the method:

>>> class Circle(Drawable):
...     pass
...
>>> c = Circle()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: Can't instantiate abstract class Circle with abstract methods draw
>>>

Abstract data attributes can be declared using the @abstractproperty decorator:

from abc import abstractproperty
...

@abstractproperty
def readonly(self):
   return self._x

Subclasses must then define a readonly() property.

Ver también

PEP 3119 [https://www.python.org/dev/peps/pep-3119] - Introducing Abstract Base Classes

PEP written by Guido van Rossum and Talin. Implemented by Guido van Rossum. Backported to 2.6 by Benjamin Aranguren, with Alex Martelli.

PEP 3127: Integer Literal Support and Syntax

Python 3.0 changes the syntax for octal (base-8) integer literals, prefixing them with «0o» or «0O» instead of a leading zero, and adds support for binary (base-2) integer literals, signalled by a «0b» or «0B» prefix.

Python 2.6 doesn’t drop support for a leading 0 signalling an octal number, but it does add support for «0o» and «0b»:

>>> 0o21, 2*8 + 1
(17, 17)
>>> 0b101111
47

The oct() builtin still returns numbers prefixed with a leading zero, and a new bin() builtin returns the binary representation for a number:

>>> oct(42)
'052'
>>> future_builtins.oct(42)
'0o52'
>>> bin(173)
'0b10101101'

The int() and long() builtins will now accept the «0o» and «0b» prefixes when base-8 or base-2 are requested, or when the base argument is zero (signalling that the base used should be determined from the string):

>>> int ('0o52', 0)
42
>>> int('1101', 2)
13
>>> int('0b1101', 2)
13
>>> int('0b1101', 0)
13

Ver también

PEP 3127 [https://www.python.org/dev/peps/pep-3127] - Integer Literal Support and Syntax

PEP written by Patrick Maupin; backported to 2.6 by Eric Smith.

PEP 3129: Class Decorators

Decorators have been extended from functions to classes. It’s now legal to write:

@foo
@bar
class A:
  pass

This is equivalent to:

class A:
  pass

A = foo(bar(A))

Ver también

PEP 3129 [https://www.python.org/dev/peps/pep-3129] - Class Decorators

PEP written by Collin Winter.

PEP 3141: A Type Hierarchy for Numbers

Python 3.0 adds several abstract base classes for numeric types inspired by Scheme’s numeric tower. These classes were backported to 2.6 as the numbers module.

The most general ABC is Number. It defines no operations at all, and only exists to allow checking if an object is a number by doing isinstance(obj, Number).

Complex is a subclass of Number. Complex numbers can undergo the basic operations of addition, subtraction, multiplication, division, and exponentiation, and you can retrieve the real and imaginary parts and obtain a number’s conjugate. Python’s built-in complex type is an implementation of Complex.

Real further derives from Complex, and adds operations that only work on real numbers: floor(), trunc(), rounding, taking the remainder mod N, floor division, and comparisons.

Rational numbers derive from Real, have numerator and denominator properties, and can be converted to floats. Python 2.6 adds a simple rational-number class, Fraction, in the fractions module. (It’s called Fraction instead of Rational to avoid a name clash with numbers.Rational.)

Integral numbers derive from Rational, and can be shifted left and right with << and >>, combined using bitwise operations such as & and |, and can be used as array indexes and slice boundaries.

In Python 3.0, the PEP slightly redefines the existing builtins round(), math.floor(), math.ceil(), and adds a new one, math.trunc(), that’s been backported to Python 2.6. math.trunc() rounds toward zero, returning the closest Integral that’s between the function’s argument and zero.

Ver también

PEP 3141 [https://www.python.org/dev/peps/pep-3141] - A Type Hierarchy for Numbers

PEP written by Jeffrey Yasskin.

Scheme’s numerical tower [https://www.gnu.org/software/guile/manual/html_node/Numerical-Tower.html#Numerical-Tower], from the Guile manual.

Scheme’s number datatypes [http://schemers.org/Documents/Standards/R5RS/HTML/r5rs-Z-H-9.html#%_sec_6.2] from the R5RS Scheme specification.

The fractions Module

To fill out the hierarchy of numeric types, the fractions module provides a rational-number class. Rational numbers store their values as a numerator and denominator forming a fraction, and can exactly represent numbers such as 2/3 that floating-point numbers can only approximate.

The Fraction constructor takes two Integral values that will be the numerator and denominator of the resulting fraction.

>>> from fractions import Fraction
>>> a = Fraction(2, 3)
>>> b = Fraction(2, 5)
>>> float(a), float(b)
(0.66666666666666663, 0.40000000000000002)
>>> a+b
Fraction(16, 15)
>>> a/b
Fraction(5, 3)

For converting floating-point numbers to rationals, the float type now has an as_integer_ratio() method that returns the numerator and denominator for a fraction that evaluates to the same floating-point value:

>>> (2.5) .as_integer_ratio()
(5, 2)
>>> (3.1415) .as_integer_ratio()
(7074029114692207L, 2251799813685248L)
>>> (1./3) .as_integer_ratio()
(6004799503160661L, 18014398509481984L)

Note that values that can only be approximated by floating-point numbers, such as 1./3, are not simplified to the number being approximated; the fraction attempts to match the floating-point value exactly.

The fractions module is based upon an implementation by Sjoerd Mullender that was in Python’s Demo/classes/ directory for a long time. This implementation was significantly updated by Jeffrey Yasskin.

Other Language Changes

Some smaller changes made to the core Python language are:

Directories and zip archives containing a __main__.py file can now be executed directly by passing their name to the interpreter. The directory or zip archive is automatically inserted as the first entry in sys.path. (Suggestion and initial patch by Andy Chu, subsequently revised by Phillip J. Eby and Nick Coghlan; bpo-1739468 [https://bugs.python.org/issue?@action=redirect&bpo=1739468].)

The hasattr() function was catching and ignoring all errors, under the assumption that they meant a __getattr__() method was failing somehow and the return value of hasattr() would therefore be False. This logic shouldn’t be applied to KeyboardInterrupt and SystemExit, however; Python 2.6 will no longer discard such exceptions when hasattr() encounters them. (Fixed by Benjamin Peterson; bpo-2196 [https://bugs.python.org/issue?@action=redirect&bpo=2196].)

When calling a function using the ** syntax to provide keyword arguments, you are no longer required to use a Python dictionary; any mapping will now work:

>>> def f(**kw):
...    print sorted(kw)
...
>>> ud=UserDict.UserDict()
>>> ud['a'] = 1
>>> ud['b'] = 'string'
>>> f(**ud)
['a', 'b']

(Contributed by Alexander Belopolsky; bpo-1686487 [https://bugs.python.org/issue?@action=redirect&bpo=1686487].)

It’s also become legal to provide keyword arguments after a *args argument to a function call.

>>> def f(*args, **kw):
...     print args, kw
...
>>> f(1,2,3, *(4,5,6), keyword=13)
(1, 2, 3, 4, 5, 6) {'keyword': 13}

Previously this would have been a syntax error. (Contributed by Amaury Forgeot d’Arc; bpo-3473 [https://bugs.python.org/issue?@action=redirect&bpo=3473].)

A new builtin, next(iterator, [default]) returns the next item from the specified iterator. If the default argument is supplied, it will be returned if iterator has been exhausted; otherwise, the StopIteration exception will be raised. (Backported in bpo-2719 [https://bugs.python.org/issue?@action=redirect&bpo=2719].)

Tuples now have index() and count() methods matching the list type’s index() and count() methods:

>>> t = (0,1,2,3,4,0,1,2)
>>> t.index(3)
3
>>> t.count(0)
2

(Contributed by Raymond Hettinger)

The built-in types now have improved support for extended slicing syntax, accepting various combinations of (start, stop, step). Previously, the support was partial and certain corner cases wouldn’t work. (Implemented by Thomas Wouters.)

Properties now have three attributes, getter, setter and deleter, that are decorators providing useful shortcuts for adding a getter, setter or deleter function to an existing property. You would use them like this:

class C(object):
    @property
    def x(self):
        return self._x

    @x.setter
    def x(self, value):
        self._x = value

    @x.deleter
    def x(self):
        del self._x

class D(C):
    @C.x.getter
    def x(self):
        return self._x * 2

    @x.setter
    def x(self, value):
        self._x = value / 2

Several methods of the built-in set types now accept multiple iterables: intersection(), intersection_update(), union(), update(), difference() and difference_update().

>>> s=set('1234567890')
>>> s.intersection('abc123', 'cdf246')  # Intersection between all inputs
set(['2'])
>>> s.difference('246', '789')
set(['1', '0', '3', '5'])

(Contributed by Raymond Hettinger.)

Many floating-point features were added. The float() function will now turn the string nan into an IEEE 754 Not A Number value, and +inf and -inf into positive or negative infinity. This works on any platform with IEEE 754 semantics. (Contributed by Christian Heimes; bpo-1635 [https://bugs.python.org/issue?@action=redirect&bpo=1635].)

Other functions in the math module, isinf() and isnan(), return true if their floating-point argument is infinite or Not A Number. (bpo-1640 [https://bugs.python.org/issue?@action=redirect&bpo=1640])

Conversion functions were added to convert floating-point numbers into hexadecimal strings (bpo-3008 [https://bugs.python.org/issue?@action=redirect&bpo=3008]). These functions convert floats to and from a string representation without introducing rounding errors from the conversion between decimal and binary. Floats have a hex() method that returns a string representation, and the float.fromhex() method converts a string back into a number:

>>> a = 3.75
>>> a.hex()
'0x1.e000000000000p+1'
>>> float.fromhex('0x1.e000000000000p+1')
3.75
>>> b=1./3
>>> b.hex()
'0x1.5555555555555p-2'

A numerical nicety: when creating a complex number from two floats on systems that support signed zeros (-0 and +0), the complex() constructor will now preserve the sign of the zero. (Fixed by Mark T. Dickinson; bpo-1507 [https://bugs.python.org/issue?@action=redirect&bpo=1507].)

Classes that inherit a __hash__() method from a parent class can set __hash__ = None to indicate that the class isn’t hashable. This will make hash(obj) raise a TypeError and the class will not be indicated as implementing the Hashable ABC.

You should do this when you’ve defined a __cmp__() or __eq__() method that compares objects by their value rather than by identity. All objects have a default hash method that uses id(obj) as the hash value. There’s no tidy way to remove the __hash__() method inherited from a parent class, so assigning None was implemented as an override. At the C level, extensions can set tp_hash to PyObject_HashNotImplemented(). (Fixed by Nick Coghlan and Amaury Forgeot d’Arc; bpo-2235 [https://bugs.python.org/issue?@action=redirect&bpo=2235].)

The GeneratorExit exception now subclasses BaseException instead of Exception. This means that an exception handler that does except Exception: will not inadvertently catch GeneratorExit. (Contributed by Chad Austin; bpo-1537 [https://bugs.python.org/issue?@action=redirect&bpo=1537].)

Generator objects now have a gi_code attribute that refers to the original code object backing the generator. (Contributed by Collin Winter; bpo-1473257 [https://bugs.python.org/issue?@action=redirect&bpo=1473257].)

The compile() built-in function now accepts keyword arguments as well as positional parameters. (Contributed by Thomas Wouters; bpo-1444529 [https://bugs.python.org/issue?@action=redirect&bpo=1444529].)

The complex() constructor now accepts strings containing parenthesized complex numbers, meaning that complex(repr(cplx)) will now round-trip values. For example, complex('(3+4j)') now returns the value (3+4j). (bpo-1491866 [https://bugs.python.org/issue?@action=redirect&bpo=1491866])

The string translate() method now accepts None as the translation table parameter, which is treated as the identity transformation. This makes it easier to carry out operations that only delete characters. (Contributed by Bengt Richter and implemented by Raymond Hettinger; bpo-1193128 [https://bugs.python.org/issue?@action=redirect&bpo=1193128].)

The built-in dir() function now checks for a __dir__() method on the objects it receives. This method must return a list of strings containing the names of valid attributes for the object, and lets the object control the value that dir() produces. Objects that have __getattr__() or __getattribute__() methods can use this to advertise pseudo-attributes they will honor. (bpo-1591665 [https://bugs.python.org/issue?@action=redirect&bpo=1591665])

Instance method objects have new attributes for the object and function comprising the method; the new synonym for im_self is __self__, and im_func is also available as __func__. The old names are still supported in Python 2.6, but are gone in 3.0.

An obscure change: when you use the locals() function inside a class statement, the resulting dictionary no longer returns free variables. (Free variables, in this case, are variables referenced in the class statement that aren’t attributes of the class.)

Optimizaciones

The warnings module has been rewritten in C. This makes it possible to invoke warnings from the parser, and may also make the interpreter’s startup faster. (Contributed by Neal Norwitz and Brett Cannon; bpo-1631171 [https://bugs.python.org/issue?@action=redirect&bpo=1631171].)

Type objects now have a cache of methods that can reduce the work required to find the correct method implementation for a particular class; once cached, the interpreter doesn’t need to traverse base classes to figure out the right method to call. The cache is cleared if a base class or the class itself is modified, so the cache should remain correct even in the face of Python’s dynamic nature. (Original optimization implemented by Armin Rigo, updated for Python 2.6 by Kevin Jacobs; bpo-1700288 [https://bugs.python.org/issue?@action=redirect&bpo=1700288].)

By default, this change is only applied to types that are included with the Python core. Extension modules may not necessarily be compatible with this cache, so they must explicitly add Py_TPFLAGS_HAVE_VERSION_TAG to the module’s tp_flags field to enable the method cache. (To be compatible with the method cache, the extension module’s code must not directly access and modify the tp_dict member of any of the types it implements. Most modules don’t do this, but it’s impossible for the Python interpreter to determine that. See bpo-1878 [https://bugs.python.org/issue?@action=redirect&bpo=1878] for some discussion.)

Function calls that use keyword arguments are significantly faster by doing a quick pointer comparison, usually saving the time of a full string comparison. (Contributed by Raymond Hettinger, after an initial implementation by Antoine Pitrou; bpo-1819 [https://bugs.python.org/issue?@action=redirect&bpo=1819].)

All of the functions in the struct module have been rewritten in C, thanks to work at the Need For Speed sprint. (Contributed by Raymond Hettinger.)

Some of the standard built-in types now set a bit in their type objects. This speeds up checking whether an object is a subclass of one of these types. (Contributed by Neal Norwitz.)

Unicode strings now use faster code for detecting whitespace and line breaks; this speeds up the split() method by about 25% and splitlines() by 35%. (Contributed by Antoine Pitrou.) Memory usage is reduced by using pymalloc for the Unicode string’s data.

The with statement now stores the __exit__() method on the stack, producing a small speedup. (Implemented by Jeffrey Yasskin.)

To reduce memory usage, the garbage collector will now clear internal free lists when garbage-collecting the highest generation of objects. This may return memory to the operating system sooner.

Interpreter Changes

Two command-line options have been reserved for use by other Python implementations. The -J switch has been reserved for use by Jython for Jython-specific options, such as switches that are passed to the underlying JVM. -X has been reserved for options specific to a particular implementation of Python such as CPython, Jython, or IronPython. If either option is used with Python 2.6, the interpreter will report that the option isn’t currently used.

Python can now be prevented from writing .pyc or .pyo files by supplying the -B switch to the Python interpreter, or by setting the PYTHONDONTWRITEBYTECODE environment variable before running the interpreter. This setting is available to Python programs as the sys.dont_write_bytecode variable, and Python code can change the value to modify the interpreter’s behaviour. (Contributed by Neal Norwitz and Georg Brandl.)

The encoding used for standard input, output, and standard error can be specified by setting the PYTHONIOENCODING environment variable before running the interpreter. The value should be a string in the form <encoding> or <encoding>:<errorhandler>. The encoding part specifies the encoding’s name, e.g. utf-8 or latin-1; the optional errorhandler part specifies what to do with characters that can’t be handled by the encoding, and should be one of «error», «ignore», or «replace». (Contributed by Martin von Löwis.)

New and Improved Modules

As in every release, Python’s standard library received a number of enhancements and bug fixes. Here’s a partial list of the most notable changes, sorted alphabetically by module name. Consult the Misc/NEWS file in the source tree for a more complete list of changes, or look through the Subversion logs for all the details.

The asyncore and asynchat modules are being actively maintained again, and a number of patches and bugfixes were applied. (Maintained by Josiah Carlson; see bpo-1736190 [https://bugs.python.org/issue?@action=redirect&bpo=1736190] for one patch.)

The bsddb module also has a new maintainer, Jesús Cea Avión, and the package is now available as a standalone package. The web page for the package is www.jcea.es/programacion/pybsddb.htm [https://www.jcea.es/programacion/pybsddb.htm]. The plan is to remove the package from the standard library in Python 3.0, because its pace of releases is much more frequent than Python’s.

The bsddb.dbshelve module now uses the highest pickling protocol available, instead of restricting itself to protocol 1. (Contributed by W. Barnes.)

The cgi module will now read variables from the query string of an HTTP POST request. This makes it possible to use form actions with URLs that include query strings such as «/cgi-bin/add.py?category=1». (Contributed by Alexandre Fiori and Nubis; bpo-1817 [https://bugs.python.org/issue?@action=redirect&bpo=1817].)

The parse_qs() and parse_qsl() functions have been relocated from the cgi module to the urlparse module. The versions still available in the cgi module will trigger PendingDeprecationWarning messages in 2.6 (bpo-600362 [https://bugs.python.org/issue?@action=redirect&bpo=600362]).

The cmath module underwent extensive revision, contributed by Mark Dickinson and Christian Heimes. Five new functions were added:

polar() converts a complex number to polar form, returning the modulus and argument of the complex number.

rect() does the opposite, turning a modulus, argument pair back into the corresponding complex number.

phase() returns the argument (also called the angle) of a complex number.

isnan() returns True if either the real or imaginary part of its argument is a NaN.

isinf() returns True if either the real or imaginary part of its argument is infinite.

The revisions also improved the numerical soundness of the cmath module. For all functions, the real and imaginary parts of the results are accurate to within a few units of least precision (ulps) whenever possible. See bpo-1381 [https://bugs.python.org/issue?@action=redirect&bpo=1381] for the details. The branch cuts for asinh(), atanh(): and atan() have also been corrected.

The tests for the module have been greatly expanded; nearly 2000 new test cases exercise the algebraic functions.

On IEEE 754 platforms, the cmath module now handles IEEE 754 special values and floating-point exceptions in a manner consistent with Annex “G” of the C99 standard.

A new data type in the collections module: namedtuple(typename, fieldnames) is a factory function that creates subclasses of the standard tuple whose fields are accessible by name as well as index. For example:

>>> var_type = collections.namedtuple('variable',
...             'id name type size')
>>> # Names are separated by spaces or commas.
>>> # 'id, name, type, size' would also work.
>>> var_type._fields
('id', 'name', 'type', 'size')

>>> var = var_type(1, 'frequency', 'int', 4)
>>> print var[0], var.id    # Equivalent
1 1
>>> print var[2], var.type  # Equivalent
int int
>>> var._asdict()
{'size': 4, 'type': 'int', 'id': 1, 'name': 'frequency'}
>>> v2 = var._replace(name='amplitude')
>>> v2
variable(id=1, name='amplitude', type='int', size=4)

Several places in the standard library that returned tuples have been modified to return namedtuple instances. For example, the Decimal.as_tuple() method now returns a named tuple with sign, digits, and exponent fields.

(Contributed by Raymond Hettinger.)

Another change to the collections module is that the deque type now supports an optional maxlen parameter; if supplied, the deque’s size will be restricted to no more than maxlen items. Adding more items to a full deque causes old items to be discarded.

>>> from collections import deque
>>> dq=deque(maxlen=3)
>>> dq
deque([], maxlen=3)
>>> dq.append(1); dq.append(2); dq.append(3)
>>> dq
deque([1, 2, 3], maxlen=3)
>>> dq.append(4)
>>> dq
deque([2, 3, 4], maxlen=3)

(Contributed by Raymond Hettinger.)

The Cookie module’s Morsel objects now support an httponly attribute. In some browsers. cookies with this attribute set cannot be accessed or manipulated by JavaScript code. (Contributed by Arvin Schnell; bpo-1638033 [https://bugs.python.org/issue?@action=redirect&bpo=1638033].)

A new window method in the curses module, chgat(), changes the display attributes for a certain number of characters on a single line. (Contributed by Fabian Kreutz.)

# Boldface text starting at y=0,x=21
# and affecting the rest of the line.
stdscr.chgat(0, 21, curses.A_BOLD)

The Textbox class in the curses.textpad module now supports editing in insert mode as well as overwrite mode. Insert mode is enabled by supplying a true value for the insert_mode parameter when creating the Textbox instance.

The datetime module’s strftime() methods now support a %f format code that expands to the number of microseconds in the object, zero-padded on the left to six places. (Contributed by Skip Montanaro; bpo-1158 [https://bugs.python.org/issue?@action=redirect&bpo=1158].)

The decimal module was updated to version 1.66 of the General Decimal Specification [http://speleotrove.com/decimal/decarith.html]. New features include some methods for some basic mathematical functions such as exp() and log10():

>>> Decimal(1).exp()
Decimal("2.718281828459045235360287471")
>>> Decimal("2.7182818").ln()
Decimal("0.9999999895305022877376682436")
>>> Decimal(1000).log10()
Decimal("3")

The as_tuple() method of Decimal objects now returns a named tuple with sign, digits, and exponent fields.

(Implemented by Facundo Batista and Mark Dickinson. Named tuple support added by Raymond Hettinger.)

The difflib module’s SequenceMatcher class now returns named tuples representing matches, with a, b, and size attributes. (Contributed by Raymond Hettinger.)

An optional timeout parameter, specifying a timeout measured in seconds, was added to the ftplib.FTP class constructor as well as the connect() method. (Added by Facundo Batista.) Also, the FTP class’s storbinary() and storlines() now take an optional callback parameter that will be called with each block of data after the data has been sent. (Contributed by Phil Schwartz; bpo-1221598 [https://bugs.python.org/issue?@action=redirect&bpo=1221598].)

The reduce() built-in function is also available in the functools module. In Python 3.0, the builtin has been dropped and reduce() is only available from functools; currently there are no plans to drop the builtin in the 2.x series. (Patched by Christian Heimes; bpo-1739906 [https://bugs.python.org/issue?@action=redirect&bpo=1739906].)

When possible, the getpass module will now use /dev/tty to print a prompt message and read the password, falling back to standard error and standard input. If the password may be echoed to the terminal, a warning is printed before the prompt is displayed. (Contributed by Gregory P. Smith.)

The glob.glob() function can now return Unicode filenames if a Unicode path was used and Unicode filenames are matched within the directory. (bpo-1001604 [https://bugs.python.org/issue?@action=redirect&bpo=1001604])

A new function in the heapq module, merge(iter1, iter2, ...), takes any number of iterables returning data in sorted order, and returns a new generator that returns the contents of all the iterators, also in sorted order. For example:

>>> list(heapq.merge([1, 3, 5, 9], [2, 8, 16]))
[1, 2, 3, 5, 8, 9, 16]

Another new function, heappushpop(heap, item), pushes item onto heap, then pops off and returns the smallest item. This is more efficient than making a call to heappush() and then heappop().

heapq is now implemented to only use less-than comparison, instead of the less-than-or-equal comparison it previously used. This makes heapq’s usage of a type match the list.sort() method. (Contributed by Raymond Hettinger.)

An optional timeout parameter, specifying a timeout measured in seconds, was added to the httplib.HTTPConnection and HTTPSConnection class constructors. (Added by Facundo Batista.)

Most of the inspect module’s functions, such as getmoduleinfo() and getargs(), now return named tuples. In addition to behaving like tuples, the elements of the return value can also be accessed as attributes. (Contributed by Raymond Hettinger.)

Some new functions in the module include isgenerator(), isgeneratorfunction(), and isabstract().

The itertools module gained several new functions.

izip_longest(iter1, iter2, ...[, fillvalue]) makes tuples from each of the elements; if some of the iterables are shorter than others, the missing values are set to fillvalue. For example:

>>> tuple(itertools.izip_longest([1,2,3], [1,2,3,4,5]))
((1, 1), (2, 2), (3, 3), (None, 4), (None, 5))

product(iter1, iter2, ..., [repeat=N]) returns the Cartesian product of the supplied iterables, a set of tuples containing every possible combination of the elements returned from each iterable.

>>> list(itertools.product([1,2,3], [4,5,6]))
[(1, 4), (1, 5), (1, 6),
 (2, 4), (2, 5), (2, 6),
 (3, 4), (3, 5), (3, 6)]

The optional repeat keyword argument is used for taking the product of an iterable or a set of iterables with themselves, repeated N times. With a single iterable argument, N-tuples are returned:

>>> list(itertools.product([1,2], repeat=3))
[(1, 1, 1), (1, 1, 2), (1, 2, 1), (1, 2, 2),
 (2, 1, 1), (2, 1, 2), (2, 2, 1), (2, 2, 2)]

With two iterables, 2N-tuples are returned.

>>> list(itertools.product([1,2], [3,4], repeat=2))
[(1, 3, 1, 3), (1, 3, 1, 4), (1, 3, 2, 3), (1, 3, 2, 4),
 (1, 4, 1, 3), (1, 4, 1, 4), (1, 4, 2, 3), (1, 4, 2, 4),
 (2, 3, 1, 3), (2, 3, 1, 4), (2, 3, 2, 3), (2, 3, 2, 4),
 (2, 4, 1, 3), (2, 4, 1, 4), (2, 4, 2, 3), (2, 4, 2, 4)]

combinations(iterable, r) returns sub-sequences of length r from the elements of iterable.

>>> list(itertools.combinations('123', 2))
[('1', '2'), ('1', '3'), ('2', '3')]
>>> list(itertools.combinations('123', 3))
[('1', '2', '3')]
>>> list(itertools.combinations('1234', 3))
[('1', '2', '3'), ('1', '2', '4'),
 ('1', '3', '4'), ('2', '3', '4')]

permutations(iter[, r]) returns all the permutations of length r of the iterable’s elements. If r is not specified, it will default to the number of elements produced by the iterable.

>>> list(itertools.permutations([1,2,3,4], 2))
[(1, 2), (1, 3), (1, 4),
 (2, 1), (2, 3), (2, 4),
 (3, 1), (3, 2), (3, 4),
 (4, 1), (4, 2), (4, 3)]

itertools.chain(*iterables) is an existing function in itertools that gained a new constructor in Python 2.6. itertools.chain.from_iterable(iterable) takes a single iterable that should return other iterables. chain() will then return all the elements of the first iterable, then all the elements of the second, and so on.

>>> list(itertools.chain.from_iterable([[1,2,3], [4,5,6]]))
[1, 2, 3, 4, 5, 6]

(All contributed by Raymond Hettinger.)

The logging module’s FileHandler class and its subclasses WatchedFileHandler, RotatingFileHandler, and TimedRotatingFileHandler now have an optional delay parameter to their constructors. If delay is true, opening of the log file is deferred until the first emit() call is made. (Contributed by Vinay Sajip.)

TimedRotatingFileHandler also has a utc constructor parameter. If the argument is true, UTC time will be used in determining when midnight occurs and in generating filenames; otherwise local time will be used.

Several new functions were added to the math module:

isinf() and isnan() determine whether a given float is a (positive or negative) infinity or a NaN (Not a Number), respectively.

copysign() copies the sign bit of an IEEE 754 number, returning the absolute value of x combined with the sign bit of y. For example, math.copysign(1, -0.0) returns -1.0. (Contributed by Christian Heimes.)

factorial() computes the factorial of a number. (Contributed by Raymond Hettinger; bpo-2138 [https://bugs.python.org/issue?@action=redirect&bpo=2138].)

fsum() adds up the stream of numbers from an iterable, and is careful to avoid loss of precision through using partial sums. (Contributed by Jean Brouwers, Raymond Hettinger, and Mark Dickinson; bpo-2819 [https://bugs.python.org/issue?@action=redirect&bpo=2819].)

acosh(), asinh() and atanh() compute the inverse hyperbolic functions.

log1p() returns the natural logarithm of 1+x (base e).

trunc() rounds a number toward zero, returning the closest Integral that’s between the function’s argument and zero. Added as part of the backport of PEP 3141’s type hierarchy for numbers.

The math module has been improved to give more consistent behaviour across platforms, especially with respect to handling of floating-point exceptions and IEEE 754 special values.

Whenever possible, the module follows the recommendations of the C99 standard about 754’s special values. For example, sqrt(-1.) should now give a ValueError across almost all platforms, while sqrt(float('NaN')) should return a NaN on all IEEE 754 platforms. Where Annex “F” of the C99 standard recommends signaling “divide-by-zero” or “invalid”, Python will raise ValueError. Where Annex “F” of the C99 standard recommends signaling “overflow”, Python will raise OverflowError. (See bpo-711019 [https://bugs.python.org/issue?@action=redirect&bpo=711019] and bpo-1640 [https://bugs.python.org/issue?@action=redirect&bpo=1640].)

(Contributed by Christian Heimes and Mark Dickinson.)

mmap objects now have a rfind() method that searches for a substring beginning at the end of the string and searching backwards. The find() method also gained an end parameter giving an index at which to stop searching. (Contributed by John Lenton.)

The operator module gained a methodcaller() function that takes a name and an optional set of arguments, returning a callable that will call the named function on any arguments passed to it. For example:

>>> # Equivalent to lambda s: s.replace('old', 'new')
>>> replacer = operator.methodcaller('replace', 'old', 'new')
>>> replacer('old wine in old bottles')
'new wine in new bottles'

(Contributed by Georg Brandl, after a suggestion by Gregory Petrosyan.)

The attrgetter() function now accepts dotted names and performs the corresponding attribute lookups:

>>> inst_name = operator.attrgetter(
...        '__class__.__name__')
>>> inst_name('')
'str'
>>> inst_name(help)
'_Helper'

(Contributed by Georg Brandl, after a suggestion by Barry Warsaw.)

The os module now wraps several new system calls. fchmod(fd, mode) and fchown(fd, uid, gid) change the mode and ownership of an opened file, and lchmod(path, mode) changes the mode of a symlink. (Contributed by Georg Brandl and Christian Heimes.)

chflags() and lchflags() are wrappers for the corresponding system calls (where they’re available), changing the flags set on a file. Constants for the flag values are defined in the stat module; some possible values include UF_IMMUTABLE to signal the file may not be changed and UF_APPEND to indicate that data can only be appended to the file. (Contributed by M. Levinson.)

os.closerange(low, high) efficiently closes all file descriptors from low to high, ignoring any errors and not including high itself. This function is now used by the subprocess module to make starting processes faster. (Contributed by Georg Brandl; bpo-1663329 [https://bugs.python.org/issue?@action=redirect&bpo=1663329].)

The os.environ object’s clear() method will now unset the environment variables using os.unsetenv() in addition to clearing the object’s keys. (Contributed by Martin Horcicka; bpo-1181 [https://bugs.python.org/issue?@action=redirect&bpo=1181].)

The os.walk() function now has a followlinks parameter. If set to True, it will follow symlinks pointing to directories and visit the directory’s contents. For backward compatibility, the parameter’s default value is false. Note that the function can fall into an infinite recursion if there’s a symlink that points to a parent directory. (bpo-1273829 [https://bugs.python.org/issue?@action=redirect&bpo=1273829])

In the os.path module, the splitext() function has been changed to not split on leading period characters. This produces better results when operating on Unix’s dot-files. For example, os.path.splitext('.ipython') now returns ('.ipython', '') instead of ('', '.ipython'). (bpo-1115886 [https://bugs.python.org/issue?@action=redirect&bpo=1115886])

A new function, os.path.relpath(path, start='.'), returns a relative path from the start path, if it’s supplied, or from the current working directory to the destination path. (Contributed by Richard Barran; bpo-1339796 [https://bugs.python.org/issue?@action=redirect&bpo=1339796].)

On Windows, os.path.expandvars() will now expand environment variables given in the form «%var%», and «~user» will be expanded into the user’s home directory path. (Contributed by Josiah Carlson; bpo-957650 [https://bugs.python.org/issue?@action=redirect&bpo=957650].)

The Python debugger provided by the pdb module gained a new command: «run» restarts the Python program being debugged and can optionally take new command-line arguments for the program. (Contributed by Rocky Bernstein; bpo-1393667 [https://bugs.python.org/issue?@action=redirect&bpo=1393667].)

The pdb.post_mortem() function, used to begin debugging a traceback, will now use the traceback returned by sys.exc_info() if no traceback is supplied. (Contributed by Facundo Batista; bpo-1106316 [https://bugs.python.org/issue?@action=redirect&bpo=1106316].)

The pickletools module now has an optimize() function that takes a string containing a pickle and removes some unused opcodes, returning a shorter pickle that contains the same data structure. (Contributed by Raymond Hettinger.)

A get_data() function was added to the pkgutil module that returns the contents of resource files included with an installed Python package. For example:

>>> import pkgutil
>>> print pkgutil.get_data('test', 'exception_hierarchy.txt')
BaseException
 +-- SystemExit
 +-- KeyboardInterrupt
 +-- GeneratorExit
 +-- Exception
      +-- StopIteration
      +-- StandardError
 ...

(Contributed by Paul Moore; bpo-2439 [https://bugs.python.org/issue?@action=redirect&bpo=2439].)

The pyexpat module’s Parser objects now allow setting their buffer_size attribute to change the size of the buffer used to hold character data. (Contributed by Achim Gaedke; bpo-1137 [https://bugs.python.org/issue?@action=redirect&bpo=1137].)

The Queue module now provides queue variants that retrieve entries in different orders. The PriorityQueue class stores queued items in a heap and retrieves them in priority order, and LifoQueue retrieves the most recently added entries first, meaning that it behaves like a stack. (Contributed by Raymond Hettinger.)

The random module’s Random objects can now be pickled on a 32-bit system and unpickled on a 64-bit system, and vice versa. Unfortunately, this change also means that Python 2.6’s Random objects can’t be unpickled correctly on earlier versions of Python. (Contributed by Shawn Ligocki; bpo-1727780 [https://bugs.python.org/issue?@action=redirect&bpo=1727780].)

The new triangular(low, high, mode) function returns random numbers following a triangular distribution. The returned values are between low and high, not including high itself, and with mode as the most frequently occurring value in the distribution. (Contributed by Wladmir van der Laan and Raymond Hettinger; bpo-1681432 [https://bugs.python.org/issue?@action=redirect&bpo=1681432].)

Long regular expression searches carried out by the re module will check for signals being delivered, so time-consuming searches can now be interrupted. (Contributed by Josh Hoyt and Ralf Schmitt; bpo-846388 [https://bugs.python.org/issue?@action=redirect&bpo=846388].)

The regular expression module is implemented by compiling bytecodes for a tiny regex-specific virtual machine. Untrusted code could create malicious strings of bytecode directly and cause crashes, so Python 2.6 includes a verifier for the regex bytecode. (Contributed by Guido van Rossum from work for Google App Engine; bpo-3487 [https://bugs.python.org/issue?@action=redirect&bpo=3487].)

The rlcompleter module’s Completer.complete() method will now ignore exceptions triggered while evaluating a name. (Fixed by Lorenz Quack; bpo-2250 [https://bugs.python.org/issue?@action=redirect&bpo=2250].)

The sched module’s scheduler instances now have a read-only queue attribute that returns the contents of the scheduler’s queue, represented as a list of named tuples with the fields (time, priority, action, argument). (Contributed by Raymond Hettinger; bpo-1861 [https://bugs.python.org/issue?@action=redirect&bpo=1861].)

The select module now has wrapper functions for the Linux epoll() and BSD kqueue() system calls. modify() method was added to the existing poll objects; pollobj.modify(fd, eventmask) takes a file descriptor or file object and an event mask, modifying the recorded event mask for that file. (Contributed by Christian Heimes; bpo-1657 [https://bugs.python.org/issue?@action=redirect&bpo=1657].)

The shutil.copytree() function now has an optional ignore argument that takes a callable object. This callable will receive each directory path and a list of the directory’s contents, and returns a list of names that will be ignored, not copied.

The shutil module also provides an ignore_patterns() function for use with this new parameter. ignore_patterns() takes an arbitrary number of glob-style patterns and returns a callable that will ignore any files and directories that match any of these patterns. The following example copies a directory tree, but skips both .svn directories and Emacs backup files, which have names ending with “~”:

shutil.copytree('Doc/library', '/tmp/library',
                ignore=shutil.ignore_patterns('*~', '.svn'))

(Contributed by Tarek Ziadé; bpo-2663 [https://bugs.python.org/issue?@action=redirect&bpo=2663].)

Integrating signal handling with GUI handling event loops like those used by Tkinter or GTk+ has long been a problem; most software ends up polling, waking up every fraction of a second to check if any GUI events have occurred. The signal module can now make this more efficient. Calling signal.set_wakeup_fd(fd) sets a file descriptor to be used; when a signal is received, a byte is written to that file descriptor. There’s also a C-level function, PySignal_SetWakeupFd(), for setting the descriptor.

Event loops will use this by opening a pipe to create two descriptors, one for reading and one for writing. The writable descriptor will be passed to set_wakeup_fd(), and the readable descriptor will be added to the list of descriptors monitored by the event loop via select() or poll(). On receiving a signal, a byte will be written and the main event loop will be woken up, avoiding the need to poll.

(Contributed by Adam Olsen; bpo-1583 [https://bugs.python.org/issue?@action=redirect&bpo=1583].)

The siginterrupt() function is now available from Python code, and allows changing whether signals can interrupt system calls or not. (Contributed by Ralf Schmitt.)

The setitimer() and getitimer() functions have also been added (where they’re available). setitimer() allows setting interval timers that will cause a signal to be delivered to the process after a specified time, measured in wall-clock time, consumed process time, or combined process+system time. (Contributed by Guilherme Polo; bpo-2240 [https://bugs.python.org/issue?@action=redirect&bpo=2240].)

The smtplib module now supports SMTP over SSL thanks to the addition of the SMTP_SSL class. This class supports an interface identical to the existing SMTP class. (Contributed by Monty Taylor.) Both class constructors also have an optional timeout parameter that specifies a timeout for the initial connection attempt, measured in seconds. (Contributed by Facundo Batista.)

An implementation of the LMTP protocol (RFC 2033 [https://tools.ietf.org/html/rfc2033.html]) was also added to the module. LMTP is used in place of SMTP when transferring e-mail between agents that don’t manage a mail queue. (LMTP implemented by Leif Hedstrom; bpo-957003 [https://bugs.python.org/issue?@action=redirect&bpo=957003].)

SMTP.starttls() now complies with RFC 3207 [https://tools.ietf.org/html/rfc3207.html] and forgets any knowledge obtained from the server not obtained from the TLS negotiation itself. (Patch contributed by Bill Fenner; bpo-829951 [https://bugs.python.org/issue?@action=redirect&bpo=829951].)

The socket module now supports TIPC (http://tipc.sourceforge.net/), a high-performance non-IP-based protocol designed for use in clustered environments. TIPC addresses are 4- or 5-tuples. (Contributed by Alberto Bertogli; bpo-1646 [https://bugs.python.org/issue?@action=redirect&bpo=1646].)

A new function, create_connection(), takes an address and connects to it using an optional timeout value, returning the connected socket object. This function also looks up the address’s type and connects to it using IPv4 or IPv6 as appropriate. Changing your code to use create_connection() instead of socket(socket.AF_INET, ...) may be all that’s required to make your code work with IPv6.

The base classes in the SocketServer module now support calling a handle_timeout() method after a span of inactivity specified by the server’s timeout attribute. (Contributed by Michael Pomraning.) The serve_forever() method now takes an optional poll interval measured in seconds, controlling how often the server will check for a shutdown request. (Contributed by Pedro Werneck and Jeffrey Yasskin; bpo-742598 [https://bugs.python.org/issue?@action=redirect&bpo=742598], bpo-1193577 [https://bugs.python.org/issue?@action=redirect&bpo=1193577].)

The sqlite3 module, maintained by Gerhard Häring, has been updated from version 2.3.2 in Python 2.5 to version 2.4.1.

The struct module now supports the C99 _Bool type, using the format character '?'. (Contributed by David Remahl.)

The Popen objects provided by the subprocess module now have terminate(), kill(), and send_signal() methods. On Windows, send_signal() only supports the SIGTERM signal, and all these methods are aliases for the Win32 API function TerminateProcess(). (Contributed by Christian Heimes.)

A new variable in the sys module, float_info, is an object containing information derived from the float.h file about the platform’s floating-point support. Attributes of this object include mant_dig (number of digits in the mantissa), epsilon (smallest difference between 1.0 and the next largest value representable), and several others. (Contributed by Christian Heimes; bpo-1534 [https://bugs.python.org/issue?@action=redirect&bpo=1534].)

Another new variable, dont_write_bytecode, controls whether Python writes any .pyc or .pyo files on importing a module. If this variable is true, the compiled files are not written. The variable is initially set on start-up by supplying the -B switch to the Python interpreter, or by setting the PYTHONDONTWRITEBYTECODE environment variable before running the interpreter. Python code can subsequently change the value of this variable to control whether bytecode files are written or not. (Contributed by Neal Norwitz and Georg Brandl.)

Information about the command-line arguments supplied to the Python interpreter is available by reading attributes of a named tuple available as sys.flags. For example, the verbose attribute is true if Python was executed in verbose mode, debug is true in debugging mode, etc. These attributes are all read-only. (Contributed by Christian Heimes.)

A new function, getsizeof(), takes a Python object and returns the amount of memory used by the object, measured in bytes. Built-in objects return correct results; third-party extensions may not, but can define a __sizeof__() method to return the object’s size. (Contributed by Robert Schuppenies; bpo-2898 [https://bugs.python.org/issue?@action=redirect&bpo=2898].)

It’s now possible to determine the current profiler and tracer functions by calling sys.getprofile() and sys.gettrace(). (Contributed by Georg Brandl; bpo-1648 [https://bugs.python.org/issue?@action=redirect&bpo=1648].)

The tarfile module now supports POSIX.1-2001 (pax) tarfiles in addition to the POSIX.1-1988 (ustar) and GNU tar formats that were already supported. The default format is GNU tar; specify the format parameter to open a file using a different format:

tar = tarfile.open("output.tar", "w",
                   format=tarfile.PAX_FORMAT)

The new encoding and errors parameters specify an encoding and an error handling scheme for character conversions. 'strict', 'ignore', and 'replace' are the three standard ways Python can handle errors,; 'utf-8' is a special value that replaces bad characters with their UTF-8 representation. (Character conversions occur because the PAX format supports Unicode filenames, defaulting to UTF-8 encoding.)

The TarFile.add() method now accepts an exclude argument that’s a function that can be used to exclude certain filenames from an archive. The function must take a filename and return true if the file should be excluded or false if it should be archived. The function is applied to both the name initially passed to add() and to the names of files in recursively-added directories.

(All changes contributed by Lars Gustäbel).

An optional timeout parameter was added to the telnetlib.Telnet class constructor, specifying a timeout measured in seconds. (Added by Facundo Batista.)

The tempfile.NamedTemporaryFile class usually deletes the temporary file it created when the file is closed. This behaviour can now be changed by passing delete=False to the constructor. (Contributed by Damien Miller; bpo-1537850 [https://bugs.python.org/issue?@action=redirect&bpo=1537850].)

A new class, SpooledTemporaryFile, behaves like a temporary file but stores its data in memory until a maximum size is exceeded. On reaching that limit, the contents will be written to an on-disk temporary file. (Contributed by Dustin J. Mitchell.)

The NamedTemporaryFile and SpooledTemporaryFile classes both work as context managers, so you can write with tempfile.NamedTemporaryFile() as tmp: .... (Contributed by Alexander Belopolsky; bpo-2021 [https://bugs.python.org/issue?@action=redirect&bpo=2021].)

The test.test_support module gained a number of context managers useful for writing tests. EnvironmentVarGuard() is a context manager that temporarily changes environment variables and automatically restores them to their old values.

Another context manager, TransientResource, can surround calls to resources that may or may not be available; it will catch and ignore a specified list of exceptions. For example, a network test may ignore certain failures when connecting to an external web site:

with test_support.TransientResource(IOError,
                                errno=errno.ETIMEDOUT):
    f = urllib.urlopen('https://sf.net')
    ...

Finally, check_warnings() resets the warning module’s warning filters and returns an object that will record all warning messages triggered (bpo-3781 [https://bugs.python.org/issue?@action=redirect&bpo=3781]):

with test_support.check_warnings() as wrec:
    warnings.simplefilter("always")
    # ... code that triggers a warning ...
    assert str(wrec.message) == "function is outdated"
    assert len(wrec.warnings) == 1, "Multiple warnings raised"

(Contributed by Brett Cannon.)

The textwrap module can now preserve existing whitespace at the beginnings and ends of the newly-created lines by specifying drop_whitespace=False as an argument:

>>> S = """This  sentence  has a bunch   of
...   extra   whitespace."""
>>> print textwrap.fill(S, width=15)
This  sentence
has a bunch
of    extra
whitespace.
>>> print textwrap.fill(S, drop_whitespace=False, width=15)
This  sentence
  has a bunch
   of    extra
   whitespace.
>>>

(Contributed by Dwayne Bailey; bpo-1581073 [https://bugs.python.org/issue?@action=redirect&bpo=1581073].)

The threading module API is being changed to use properties such as daemon instead of setDaemon() and isDaemon() methods, and some methods have been renamed to use underscores instead of camel-case; for example, the activeCount() method is renamed to active_count(). Both the 2.6 and 3.0 versions of the module support the same properties and renamed methods, but don’t remove the old methods. No date has been set for the deprecation of the old APIs in Python 3.x; the old APIs won’t be removed in any 2.x version. (Carried out by several people, most notably Benjamin Peterson.)

The threading module’s Thread objects gained an ident property that returns the thread’s identifier, a nonzero integer. (Contributed by Gregory P. Smith; bpo-2871 [https://bugs.python.org/issue?@action=redirect&bpo=2871].)

The timeit module now accepts callables as well as strings for the statement being timed and for the setup code. Two convenience functions were added for creating Timer instances: repeat(stmt, setup, time, repeat, number) and timeit(stmt, setup, time, number) create an instance and call the corresponding method. (Contributed by Erik Demaine; bpo-1533909 [https://bugs.python.org/issue?@action=redirect&bpo=1533909].)

The Tkinter module now accepts lists and tuples for options, separating the elements by spaces before passing the resulting value to Tcl/Tk. (Contributed by Guilherme Polo; bpo-2906 [https://bugs.python.org/issue?@action=redirect&bpo=2906].)

The turtle module for turtle graphics was greatly enhanced by Gregor Lingl. New features in the module include:

Better animation of turtle movement and rotation.

Control over turtle movement using the new delay(), tracer(), and speed() methods.

The ability to set new shapes for the turtle, and to define a new coordinate system.

Turtles now have an undo() method that can roll back actions.

Simple support for reacting to input events such as mouse and keyboard activity, making it possible to write simple games.

A turtle.cfg file can be used to customize the starting appearance of the turtle’s screen.

The module’s docstrings can be replaced by new docstrings that have been translated into another language.

(bpo-1513695 [https://bugs.python.org/issue?@action=redirect&bpo=1513695])

An optional timeout parameter was added to the urllib.urlopen() function and the urllib.ftpwrapper class constructor, as well as the urllib2.urlopen() function. The parameter specifies a timeout measured in seconds. For example:

>>> u = urllib2.urlopen("http://slow.example.com",
                        timeout=3)
Traceback (most recent call last):
  ...
urllib2.URLError: <urlopen error timed out>
>>>

(Added by Facundo Batista.)

The Unicode database provided by the unicodedata module has been updated to version 5.1.0. (Updated by Martin von Löwis; bpo-3811 [https://bugs.python.org/issue?@action=redirect&bpo=3811].)

The warnings module’s formatwarning() and showwarning() gained an optional line argument that can be used to supply the line of source code. (Added as part of bpo-1631171 [https://bugs.python.org/issue?@action=redirect&bpo=1631171], which re-implemented part of the warnings module in C code.)

A new function, catch_warnings(), is a context manager intended for testing purposes that lets you temporarily modify the warning filters and then restore their original values (bpo-3781 [https://bugs.python.org/issue?@action=redirect&bpo=3781]).

The XML-RPC SimpleXMLRPCServer and DocXMLRPCServer classes can now be prevented from immediately opening and binding to their socket by passing False as the bind_and_activate constructor parameter. This can be used to modify the instance’s allow_reuse_address attribute before calling the server_bind() and server_activate() methods to open the socket and begin listening for connections. (Contributed by Peter Parente; bpo-1599845 [https://bugs.python.org/issue?@action=redirect&bpo=1599845].)

SimpleXMLRPCServer also has a _send_traceback_header attribute; if true, the exception and formatted traceback are returned as HTTP headers «X-Exception» and «X-Traceback». This feature is for debugging purposes only and should not be used on production servers because the tracebacks might reveal passwords or other sensitive information. (Contributed by Alan McIntyre as part of his project for Google’s Summer of Code 2007.)

The xmlrpclib module no longer automatically converts datetime.date and datetime.time to the xmlrpclib.DateTime type; the conversion semantics were not necessarily correct for all applications. Code using xmlrpclib should convert date and time instances. (bpo-1330538 [https://bugs.python.org/issue?@action=redirect&bpo=1330538]) The code can also handle dates before 1900 (contributed by Ralf Schmitt; bpo-2014 [https://bugs.python.org/issue?@action=redirect&bpo=2014]) and 64-bit integers represented by using <i8> in XML-RPC responses (contributed by Riku Lindblad; bpo-2985 [https://bugs.python.org/issue?@action=redirect&bpo=2985]).

The zipfile module’s ZipFile class now has extract() and extractall() methods that will unpack a single file or all the files in the archive to the current directory, or to a specified directory:

z = zipfile.ZipFile('python-251.zip')

# Unpack a single file, writing it relative
# to the /tmp directory.
z.extract('Python/sysmodule.c', '/tmp')

# Unpack all the files in the archive.
z.extractall()

(Contributed by Alan McIntyre; bpo-467924 [https://bugs.python.org/issue?@action=redirect&bpo=467924].)

The open(), read() and extract() methods can now take either a filename or a ZipInfo object. This is useful when an archive accidentally contains a duplicated filename. (Contributed by Graham Horler; bpo-1775025 [https://bugs.python.org/issue?@action=redirect&bpo=1775025].)

Finally, zipfile now supports using Unicode filenames for archived files. (Contributed by Alexey Borzenkov; bpo-1734346 [https://bugs.python.org/issue?@action=redirect&bpo=1734346].)

The ast module

The ast module provides an Abstract Syntax Tree representation of Python code, and Armin Ronacher contributed a set of helper functions that perform a variety of common tasks. These will be useful for HTML templating packages, code analyzers, and similar tools that process Python code.

The parse() function takes an expression and returns an AST. The dump() function outputs a representation of a tree, suitable for debugging:

import ast

t = ast.parse("""
d = {}
for i in 'abcdefghijklm':
    d[i + i] = ord(i) - ord('a') + 1
print d
""")
print ast.dump(t)

This outputs a deeply nested tree:

Module(body=[
  Assign(targets=[
    Name(id='d', ctx=Store())
   ], value=Dict(keys=[], values=[]))
  For(target=Name(id='i', ctx=Store()),
      iter=Str(s='abcdefghijklm'), body=[
    Assign(targets=[
      Subscript(value=
        Name(id='d', ctx=Load()),
          slice=
          Index(value=
            BinOp(left=Name(id='i', ctx=Load()), op=Add(),
             right=Name(id='i', ctx=Load()))), ctx=Store())
     ], value=
     BinOp(left=
      BinOp(left=
       Call(func=
        Name(id='ord', ctx=Load()), args=[
          Name(id='i', ctx=Load())
         ], keywords=[], starargs=None, kwargs=None),
       op=Sub(), right=Call(func=
        Name(id='ord', ctx=Load()), args=[
          Str(s='a')
         ], keywords=[], starargs=None, kwargs=None)),
       op=Add(), right=Num(n=1)))
    ], orelse=[])
   Print(dest=None, values=[
     Name(id='d', ctx=Load())
   ], nl=True)
 ])

The literal_eval() method takes a string or an AST representing a literal expression, parses and evaluates it, and returns the resulting value. A literal expression is a Python expression containing only strings, numbers, dictionaries, etc. but no statements or function calls. If you need to evaluate an expression but cannot accept the security risk of using an eval() call, literal_eval() will handle it safely:

>>> literal = '("a", "b", {2:4, 3:8, 1:2})'
>>> print ast.literal_eval(literal)
('a', 'b', {1: 2, 2: 4, 3: 8})
>>> print ast.literal_eval('"a" + "b"')
Traceback (most recent call last):
  ...
ValueError: malformed string

The module also includes NodeVisitor and NodeTransformer classes for traversing and modifying an AST, and functions for common transformations such as changing line numbers.

The future_builtins module

Python 3.0 makes many changes to the repertoire of built-in functions, and most of the changes can’t be introduced in the Python 2.x series because they would break compatibility. The future_builtins module provides versions of these built-in functions that can be imported when writing 3.0-compatible code.

The functions in this module currently include:

ascii(obj): equivalent to repr(). In Python 3.0, repr() will return a Unicode string, while ascii() will return a pure ASCII bytestring.

filter(predicate, iterable), map(func, iterable1, ...): the 3.0 versions return iterators, unlike the 2.x builtins which return lists.

hex(value), oct(value): instead of calling the __hex__() or __oct__() methods, these versions will call the __index__() method and convert the result to hexadecimal or octal. oct() will use the new 0o notation for its result.

The json module: JavaScript Object Notation

The new json module supports the encoding and decoding of Python types in JSON (Javascript Object Notation). JSON is a lightweight interchange format often used in web applications. For more information about JSON, see http://www.json.org.

json comes with support for decoding and encoding most built-in Python types. The following example encodes and decodes a dictionary:

>>> import json
>>> data = {"spam": "foo", "parrot": 42}
>>> in_json = json.dumps(data) # Encode the data
>>> in_json
'{"parrot": 42, "spam": "foo"}'
>>> json.loads(in_json) # Decode into a Python object
{"spam": "foo", "parrot": 42}

It’s also possible to write your own decoders and encoders to support more types. Pretty-printing of the JSON strings is also supported.

json (originally called simplejson) was written by Bob Ippolito.

The plistlib module: A Property-List Parser

The .plist format is commonly used on Mac OS X to store basic data types (numbers, strings, lists, and dictionaries) by serializing them into an XML-based format. It resembles the XML-RPC serialization of data types.

Despite being primarily used on Mac OS X, the format has nothing Mac-specific about it and the Python implementation works on any platform that Python supports, so the plistlib module has been promoted to the standard library.

Using the module is simple:

import sys
import plistlib
import datetime

# Create data structure
data_struct = dict(lastAccessed=datetime.datetime.now(),
                   version=1,
                   categories=('Personal','Shared','Private'))

# Create string containing XML.
plist_str = plistlib.writePlistToString(data_struct)
new_struct = plistlib.readPlistFromString(plist_str)
print data_struct
print new_struct

# Write data structure to a file and read it back.
plistlib.writePlist(data_struct, '/tmp/customizations.plist')
new_struct = plistlib.readPlist('/tmp/customizations.plist')

# read/writePlist accepts file-like objects as well as paths.
plistlib.writePlist(data_struct, sys.stdout)

ctypes Enhancements

Thomas Heller continued to maintain and enhance the ctypes module.

ctypes now supports a c_bool datatype that represents the C99 bool type. (Contributed by David Remahl; bpo-1649190 [https://bugs.python.org/issue?@action=redirect&bpo=1649190].)

The ctypes string, buffer and array types have improved support for extended slicing syntax, where various combinations of (start, stop, step) are supplied. (Implemented by Thomas Wouters.)

All ctypes data types now support from_buffer() and from_buffer_copy() methods that create a ctypes instance based on a provided buffer object. from_buffer_copy() copies the contents of the object, while from_buffer() will share the same memory area.

A new calling convention tells ctypes to clear the errno or Win32 LastError variables at the outset of each wrapped call. (Implemented by Thomas Heller; bpo-1798 [https://bugs.python.org/issue?@action=redirect&bpo=1798].)

You can now retrieve the Unix errno variable after a function call. When creating a wrapped function, you can supply use_errno=True as a keyword parameter to the DLL() function and then call the module-level methods set_errno() and get_errno() to set and retrieve the error value.

The Win32 LastError variable is similarly supported by the DLL(), OleDLL(), and WinDLL() functions. You supply use_last_error=True as a keyword parameter and then call the module-level methods set_last_error() and get_last_error().

The byref() function, used to retrieve a pointer to a ctypes instance, now has an optional offset parameter that is a byte count that will be added to the returned pointer.

Improved SSL Support

Bill Janssen made extensive improvements to Python 2.6’s support for the Secure Sockets Layer by adding a new module, ssl, that’s built atop the OpenSSL [https://www.openssl.org/] library. This new module provides more control over the protocol negotiated, the X.509 certificates used, and has better support for writing SSL servers (as opposed to clients) in Python. The existing SSL support in the socket module hasn’t been removed and continues to work, though it will be removed in Python 3.0.

To use the new module, you must first create a TCP connection in the usual way and then pass it to the ssl.wrap_socket() function. It’s possible to specify whether a certificate is required, and to obtain certificate info by calling the getpeercert() method.

Ver también

The documentation for the ssl module.

Deprecations and Removals

String exceptions have been removed. Attempting to use them raises a TypeError.

Changes to the Exception interface as dictated by PEP 352 [https://www.python.org/dev/peps/pep-0352] continue to be made. For 2.6, the message attribute is being deprecated in favor of the args attribute.

(3.0-warning mode) Python 3.0 will feature a reorganized standard library that will drop many outdated modules and rename others. Python 2.6 running in 3.0-warning mode will warn about these modules when they are imported.

The list of deprecated modules is: audiodev, bgenlocations, buildtools, bundlebuilder, Canvas, compiler, dircache, dl, fpformat, gensuitemodule, ihooks, imageop, imgfile, linuxaudiodev, mhlib, mimetools, multifile, new, pure, statvfs, sunaudiodev, test.testall, and toaiff.

The gopherlib module has been removed.

The MimeWriter module and mimify module have been deprecated; use the email package instead.

The md5 module has been deprecated; use the hashlib module instead.

The posixfile module has been deprecated; fcntl.lockf() provides better locking.

The popen2 module has been deprecated; use the subprocess module.

The rgbimg module has been removed.

The sets module has been deprecated; it’s better to use the built-in set and frozenset types.

The sha module has been deprecated; use the hashlib module instead.

Build and C API Changes

Changes to Python’s build process and to the C API include:

Python now must be compiled with C89 compilers (after 19 years!). This means that the Python source tree has dropped its own implementations of memmove() and strerror(), which are in the C89 standard library.

Python 2.6 can be built with Microsoft Visual Studio 2008 (version 9.0), and this is the new default compiler. See the PCbuild directory for the build files. (Implemented by Christian Heimes.)

On Mac OS X, Python 2.6 can be compiled as a 4-way universal build. The configure script can take a --with-universal-archs=[32-bit|64-bit|all] switch, controlling whether the binaries are built for 32-bit architectures (x86, PowerPC), 64-bit (x86-64 and PPC-64), or both. (Contributed by Ronald Oussoren.)

The BerkeleyDB module now has a C API object, available as bsddb.db.api. This object can be used by other C extensions that wish to use the bsddb module for their own purposes. (Contributed by Duncan Grisby.)

The new buffer interface, previously described in the PEP 3118 section, adds PyObject_GetBuffer() and PyBuffer_Release(), as well as a few other functions.

Python’s use of the C stdio library is now thread-safe, or at least as thread-safe as the underlying library is. A long-standing potential bug occurred if one thread closed a file object while another thread was reading from or writing to the object. In 2.6 file objects have a reference count, manipulated by the PyFile_IncUseCount() and PyFile_DecUseCount() functions. File objects can’t be closed unless the reference count is zero. PyFile_IncUseCount() should be called while the GIL is still held, before carrying out an I/O operation using the FILE * pointer, and PyFile_DecUseCount() should be called immediately after the GIL is re-acquired. (Contributed by Antoine Pitrou and Gregory P. Smith.)

Importing modules simultaneously in two different threads no longer deadlocks; it will now raise an ImportError. A new API function, PyImport_ImportModuleNoBlock(), will look for a module in sys.modules first, then try to import it after acquiring an import lock. If the import lock is held by another thread, an ImportError is raised. (Contributed by Christian Heimes.)

Several functions return information about the platform’s floating-point support. PyFloat_GetMax() returns the maximum representable floating point value, and PyFloat_GetMin() returns the minimum positive value. PyFloat_GetInfo() returns an object containing more information from the float.h file, such as "mant_dig" (number of digits in the mantissa), "epsilon" (smallest difference between 1.0 and the next largest value representable), and several others. (Contributed by Christian Heimes; bpo-1534 [https://bugs.python.org/issue?@action=redirect&bpo=1534].)

C functions and methods that use PyComplex_AsCComplex() will now accept arguments that have a __complex__() method. In particular, the functions in the cmath module will now accept objects with this method. This is a backport of a Python 3.0 change. (Contributed by Mark Dickinson; bpo-1675423 [https://bugs.python.org/issue?@action=redirect&bpo=1675423].)

Python’s C API now includes two functions for case-insensitive string comparisons, PyOS_stricmp(char*, char*) and PyOS_strnicmp(char*, char*, Py_ssize_t). (Contributed by Christian Heimes; bpo-1635 [https://bugs.python.org/issue?@action=redirect&bpo=1635].)

Many C extensions define their own little macro for adding integers and strings to the module’s dictionary in the init* function. Python 2.6 finally defines standard macros for adding values to a module, PyModule_AddStringMacro and PyModule_AddIntMacro(). (Contributed by Christian Heimes.)

Some macros were renamed in both 3.0 and 2.6 to make it clearer that they are macros, not functions. Py_Size() became Py_SIZE(), Py_Type() became Py_TYPE(), and Py_Refcnt() became Py_REFCNT(). The mixed-case macros are still available in Python 2.6 for backward compatibility. (bpo-1629 [https://bugs.python.org/issue?@action=redirect&bpo=1629])

Distutils now places C extensions it builds in a different directory when running on a debug version of Python. (Contributed by Collin Winter; bpo-1530959 [https://bugs.python.org/issue?@action=redirect&bpo=1530959].)

Several basic data types, such as integers and strings, maintain internal free lists of objects that can be re-used. The data structures for these free lists now follow a naming convention: the variable is always named free_list, the counter is always named numfree, and a macro Py<typename>_MAXFREELIST is always defined.

A new Makefile target, «make patchcheck», prepares the Python source tree for making a patch: it fixes trailing whitespace in all modified .py files, checks whether the documentation has been changed, and reports whether the Misc/ACKS and Misc/NEWS files have been updated. (Contributed by Brett Cannon.)

Another new target, «make profile-opt», compiles a Python binary using GCC’s profile-guided optimization. It compiles Python with profiling enabled, runs the test suite to obtain a set of profiling results, and then compiles using these results for optimization. (Contributed by Gregory P. Smith.)

Port-Specific Changes: Windows

The support for Windows 95, 98, ME and NT4 has been dropped. Python 2.6 requires at least Windows 2000 SP4.

The new default compiler on Windows is Visual Studio 2008 (version 9.0). The build directories for Visual Studio 2003 (version 7.1) and 2005 (version 8.0) were moved into the PC/ directory. The new PCbuild directory supports cross compilation for X64, debug builds and Profile Guided Optimization (PGO). PGO builds are roughly 10% faster than normal builds. (Contributed by Christian Heimes with help from Amaury Forgeot d’Arc and Martin von Löwis.)

The msvcrt module now supports both the normal and wide char variants of the console I/O API. The getwch() function reads a keypress and returns a Unicode value, as does the getwche() function. The putwch() function takes a Unicode character and writes it to the console. (Contributed by Christian Heimes.)

os.path.expandvars() will now expand environment variables in the form «%var%», and «~user» will be expanded into the user’s home directory path. (Contributed by Josiah Carlson; bpo-957650 [https://bugs.python.org/issue?@action=redirect&bpo=957650].)

The socket module’s socket objects now have an ioctl() method that provides a limited interface to the WSAIoctl() system interface.

The _winreg module now has a function, ExpandEnvironmentStrings(), that expands environment variable references such as %NAME% in an input string. The handle objects provided by this module now support the context protocol, so they can be used in with statements. (Contributed by Christian Heimes.)

_winreg also has better support for x64 systems, exposing the DisableReflectionKey(), EnableReflectionKey(), and QueryReflectionKey() functions, which enable and disable registry reflection for 32-bit processes running on 64-bit systems. (bpo-1753245 [https://bugs.python.org/issue?@action=redirect&bpo=1753245])

The msilib module’s Record object gained GetInteger() and GetString() methods that return field values as an integer or a string. (Contributed by Floris Bruynooghe; bpo-2125 [https://bugs.python.org/issue?@action=redirect&bpo=2125].)

Port-Specific Changes: Mac OS X

When compiling a framework build of Python, you can now specify the framework name to be used by providing the --with-framework-name= option to the configure script.

The macfs module has been removed. This in turn required the macostools.touched() function to be removed because it depended on the macfs module. (bpo-1490190 [https://bugs.python.org/issue?@action=redirect&bpo=1490190])

Many other Mac OS modules have been deprecated and will be removed in Python 3.0: _builtinSuites, aepack, aetools, aetypes, applesingle, appletrawmain, appletrunner, argvemulator, Audio_mac, autoGIL, Carbon, cfmfile, CodeWarrior, ColorPicker, EasyDialogs, Explorer, Finder, FrameWork, findertools, ic, icglue, icopen, macerrors, MacOS, macfs, macostools, macresource, MiniAEFrame, Nav, Netscape, OSATerminology, pimp, PixMapWrapper, StdSuites, SystemEvents, Terminal, and terminalcommand.

Port-Specific Changes: IRIX

A number of old IRIX-specific modules were deprecated and will be removed in Python 3.0: al and AL, cd, cddb, cdplayer, CL and cl, DEVICE, ERRNO, FILE, FL and fl, flp, fm, GET, GLWS, GL and gl, IN, IOCTL, jpeg, panelparser, readcd, SV and sv, torgb, videoreader, and WAIT.

Porting to Python 2.6

This section lists previously described changes and other bugfixes that may require changes to your code:

Classes that aren’t supposed to be hashable should set __hash__ = None in their definitions to indicate the fact.

String exceptions have been removed. Attempting to use them raises a TypeError.

The __init__() method of collections.deque now clears any existing contents of the deque before adding elements from the iterable. This change makes the behavior match list.__init__().

object.__init__() previously accepted arbitrary arguments and keyword arguments, ignoring them. In Python 2.6, this is no longer allowed and will result in a TypeError. This will affect __init__() methods that end up calling the corresponding method on object (perhaps through using super()). See bpo-1683368 [https://bugs.python.org/issue?@action=redirect&bpo=1683368] for discussion.

The Decimal constructor now accepts leading and trailing whitespace when passed a string. Previously it would raise an InvalidOperation exception. On the other hand, the create_decimal() method of Context objects now explicitly disallows extra whitespace, raising a ConversionSyntax exception.

Due to an implementation accident, if you passed a file path to the built-in __import__() function, it would actually import the specified file. This was never intended to work, however, and the implementation now explicitly checks for this case and raises an ImportError.

C API: the PyImport_Import() and PyImport_ImportModule() functions now default to absolute imports, not relative imports. This will affect C extensions that import other modules.

C API: extension data types that shouldn’t be hashable should define their tp_hash slot to PyObject_HashNotImplemented().

The socket module exception socket.error now inherits from IOError. Previously it wasn’t a subclass of StandardError but now it is, through IOError. (Implemented by Gregory P. Smith; bpo-1706815 [https://bugs.python.org/issue?@action=redirect&bpo=1706815].)

The xmlrpclib module no longer automatically converts datetime.date and datetime.time to the xmlrpclib.DateTime type; the conversion semantics were not necessarily correct for all applications. Code using xmlrpclib should convert date and time instances. (bpo-1330538 [https://bugs.python.org/issue?@action=redirect&bpo=1330538])

(3.0-warning mode) The Exception class now warns when accessed using slicing or index access; having Exception behave like a tuple is being phased out.

(3.0-warning mode) inequality comparisons between two dictionaries or two objects that don’t implement comparison methods are reported as warnings. dict1 == dict2 still works, but dict1 < dict2 is being phased out.

Comparisons between cells, which are an implementation detail of Python’s scoping rules, also cause warnings because such comparisons are forbidden entirely in 3.0.

Agradecimientos

The author would like to thank the following people for offering suggestions, corrections and assistance with various drafts of this article: Georg Brandl, Steve Brown, Nick Coghlan, Ralph Corderoy, Jim Jewett, Kent Johnson, Chris Lambacher, Martin Michlmayr, Antoine Pitrou, Brian Warner.

Novedades de Python 2.5

Autor

A.M. Kuchling

Este artículo explica las nuevas características de Python 2.5. La versión final de Python 2.5 está prevista para agosto de 2006; PEP 356 [https://www.python.org/dev/peps/pep-0356] describe el calendario de publicación previsto.

Los cambios en Python 2.5 son una interesante mezcla de mejoras en el lenguaje y en las bibliotecas. Las mejoras de la biblioteca serán más importantes para la comunidad de usuarios de Python, creo, porque se han añadido varios paquetes muy útiles. Los nuevos módulos incluyen ElementTree para el procesamiento de XML (xml.etree), el módulo de base de datos SQLite (sqlite), y el módulo ctypes para llamar a funciones C.

Los cambios en el lenguaje son de mediana importancia. Se han añadido algunas características nuevas y agradables, pero la mayoría de ellas no son características que vaya a utilizar todos los días. Las expresiones condicionales fueron finalmente añadidas al lenguaje usando una nueva sintaxis; ver sección PEP 308: Expresiones condicionales. La nueva sentencia “with” facilitará la escritura de código de limpieza (sección PEP 343: La declaración «con). Ahora se pueden pasar valores a los generadores (sección PEP 342: Nuevas funciones del generador). Las importaciones son ahora visibles como absolutas o relativas (sección PEP 328: Importaciones absolutas y relativas). Se han mejorado algunos casos de manejo de excepciones (sección PEP 341: Try/except/finally unificados). Todas estas mejoras merecen la pena, pero son mejoras de una u otra característica específica del lenguaje; ninguna de ellas es una modificación amplia de la semántica de Python.

Además de las adiciones al lenguaje y a la biblioteca, se han realizado otras mejoras y correcciones de errores en todo el árbol de código fuente. Una búsqueda en los registros de cambios del SVN revela que se aplicaron 353 parches y se corrigieron 458 errores entre Python 2.4 y 2.5. (Es probable que ambas cifras estén subestimadas)

Este artículo no pretende ser una especificación completa de las nuevas características; en su lugar, los cambios se introducen brevemente utilizando ejemplos útiles. Para obtener todos los detalles, siempre debes consultar la documentación de Python 2.5 en https://docs.python.org. Si quieres entender la implementación completa y los fundamentos del diseño, consulta el PEP de una nueva característica en particular.

Son bienvenidos los comentarios, las sugerencias y los informes de errores para este documento; por favor, envíelos por correo electrónico al autor o abra un error en el rastreador de errores de Python.

PEP 308: Expresiones condicionales

Durante mucho tiempo, la gente ha solicitado una forma de escribir expresiones condicionales, que son expresiones que devuelven el valor A o el valor B dependiendo de si un valor booleano es verdadero o falso. Una expresión condicional le permite escribir una única sentencia de asignación que tiene el mismo efecto que la siguiente:

if condition:
    x = true_value
else:
    x = false_value

Ha habido interminables y tediosas discusiones sobre la sintaxis tanto en python-dev como en comp.lang.python. Incluso se llevó a cabo una votación en la que se descubrió que la mayoría de los votantes querían expresiones condicionales de alguna forma, pero no había ninguna sintaxis que fuera preferida por una clara mayoría. Los candidatos incluían cond ? true_v : false_v, if cond then true_v else false_v, y otras 16 variaciones.

Guido van Rossum eligió finalmente una sintaxis sorprendente:

x = true_value if condition else false_value

La evaluación sigue siendo perezosa como en las expresiones booleanas existentes, por lo que el orden de evaluación salta un poco. La expresión condición del medio se evalúa primero, y la expresión valor_verdadero se evalúa sólo si la condición es verdadera. Del mismo modo, la expresión valor_falso sólo se evalúa cuando la condición es falsa.

Esta sintaxis puede parecer extraña y retrógrada; ¿por qué la condición va en el medio de la expresión, y no en la parte delantera como en c ? x : y de C? La decisión se comprobó aplicando la nueva sintaxis a los módulos de la biblioteca estándar y viendo cómo se leía el código resultante. En muchos casos en los que se utiliza una expresión condicional, un valor parece ser el «caso común» y otro valor es un «caso excepcional», utilizado sólo en las raras ocasiones en las que no se cumple la condición. La sintaxis condicional hace que este patrón sea un poco más obvio:

contents = ((doc + '\n') if doc else '')

Leo la afirmación anterior en el sentido de que «aquí se asigna a contents un valor de doc+'\n'; a veces doc está vacío, en cuyo caso especial se devuelve una cadena vacía» Dudo que use expresiones condicionales muy a menudo donde no hay un caso común y no común claro.

Hubo alguna discusión sobre si el lenguaje debería requerir rodear las expresiones condicionales con paréntesis. Se tomó la decisión de no requerir paréntesis en la gramática del lenguaje Python, pero como una cuestión de estilo creo que siempre deberías usarlos. Considere estas dos declaraciones:

# First version -- no parens
level = 1 if logging else 0

# Second version -- with parens
level = (1 if logging else 0)

En la primera versión, creo que el ojo de un lector podría agrupar la sentencia en “nivel = 1”, “si registro”, “si no 0”, y pensar que la condición decide si se realiza la asignación a nivel. La segunda versión se lee mejor, en mi opinión, porque deja claro que la asignación se realiza siempre y que se está eligiendo entre dos valores.

Otra razón para incluir los paréntesis: algunas combinaciones extrañas de comprensiones de listas y lambdas podrían parecer expresiones condicionales incorrectas. Véase PEP 308 [https://www.python.org/dev/peps/pep-0308] para algunos ejemplos. Si pone paréntesis alrededor de sus expresiones condicionales, no se encontrará con este caso.

Ver también

PEP 308 [https://www.python.org/dev/peps/pep-0308] - Expresiones condicionales

PEP escrito por Guido van Rossum y Raymond D. Hettinger; implementado por Thomas Wouters.

PEP 309: Aplicación parcial de funciones

El módulo functools está destinado a contener herramientas para la programación de estilo funcional.

Una herramienta útil de este módulo es la función partial(). Para los programas escritos en un estilo funcional, a veces querrá construir variantes de funciones existentes que tengan algunos de los parámetros rellenados. Considere una función Python f(a, b, c); podría crear una nueva función g(b, c) que fuera equivalente a f(1, b, c). Esto se llama «aplicación parcial de funciones».

parcial() toma los argumentos (function, arg1, arg2, ... kwarg1=valor1, kwarg2=valor2). El objeto resultante es invocable, por lo que puedes llamarlo para invocar la función con los argumentos rellenados.

He aquí un pequeño pero realista ejemplo:

import functools

def log (message, subsystem):
    "Write the contents of 'message' to the specified subsystem."
    print '%s: %s' % (subsystem, message)
    ...

server_log = functools.partial(log, subsystem='server')
server_log('Unable to open socket')

Aquí hay otro ejemplo, de un programa que utiliza PyGTK. Aquí se está construyendo dinámicamente un menú emergente sensible al contexto. El callback proporcionado para la opción de menú es una versión parcialmente aplicada del método open_item(), donde se ha proporcionado el primer argumento

...
class Application:
    def open_item(self, path):
       ...
    def init (self):
        open_func = functools.partial(self.open_item, item_path)
        popup_menu.append( ("Open", open_func, 1) )

Otra función del módulo functools es la función update_wrapper(wrapper, wrapped) que le ayuda a escribir decoradores con un buen comportamiento. update_wrapper() copia el nombre, el módulo y el atributo docstring a una función wrapper para que las trazas dentro de la función envuelta sean más fáciles de entender. Por ejemplo, puedes escribir:

def my_decorator(f):
    def wrapper(*args, **kwds):
        print 'Calling decorated function'
        return f(*args, **kwds)
    functools.update_wrapper(wrapper, f)
    return wrapper

wraps() es un decorador que se puede utilizar dentro de sus propios decoradores para copiar la información de la función envuelta. Una versión alternativa del ejemplo anterior sería:

def my_decorator(f):
    @functools.wraps(f)
    def wrapper(*args, **kwds):
        print 'Calling decorated function'
        return f(*args, **kwds)
    return wrapper

Ver también

PEP 309 [https://www.python.org/dev/peps/pep-0309] - Aplicación parcial de funciones

PEP propuesto y escrito por Peter Harris; implementado por Hye-Shik Chang y Nick Coghlan, con adaptaciones de Raymond Hettinger.

PEP 314: Metadatos para paquetes de software Python v1.1

Se ha añadido a Distutils un sencillo soporte de dependencias. La función setup() ahora tiene parámetros de palabras clave requires, provides y obsoletes. Cuando se construye una distribución de origen utilizando el comando sdist, la información de las dependencias se registrará en el archivo PKG-INFO.

Otro nuevo parámetro de palabra clave es download_url, que debe establecerse como una URL para el código fuente del paquete. Esto significa que ahora es posible buscar una entrada en el índice de paquetes, determinar las dependencias de un paquete y descargar los paquetes necesarios.

VERSION = '1.0'
setup(name='PyPackage',
      version=VERSION,
      requires=['numarray', 'zlib (>=1.1.4)'],
      obsoletes=['OldPackage']
      download_url=('http://www.example.com/pypackage/dist/pkg-%s.tar.gz'
                    % VERSION),
     )

Otra nueva mejora en el índice de paquetes de Python en https://pypi.org es el almacenamiento de archivos fuente y binarios de un paquete. El nuevo comando upload de Distutils subirá un paquete al repositorio.

Antes de poder subir un paquete, debes ser capaz de construir una distribución usando el comando sdist de Distutils. Una vez que funcione, puedes ejecutar python setup.py upload para añadir tu paquete al archivo PyPI. Opcionalmente puedes firmar el paquete con GPG suministrando las opciones --sign y --identity.

La carga de paquetes fue implementada por Martin von Löwis y Richard Jones.

Ver también

PEP 314 [https://www.python.org/dev/peps/pep-0314] - Metadatos para paquetes de software Python v1.1

PEP propuesto y redactado por A.M. Kuchling, Richard Jones y Fred Drake; aplicado por Richard Jones y Fred Drake.

PEP 328: Importaciones absolutas y relativas

La parte más sencilla de PEP 328 [https://www.python.org/dev/peps/pep-0328] se implementó en Python 2.4: los paréntesis podían utilizarse ahora para encerrar los nombres importados de un módulo utilizando la sentencia from ... import ..., facilitando la importación de muchos nombres diferentes.

La parte más complicada se ha implementado en Python 2.5: la importación de un módulo puede especificarse para utilizar importaciones absolutas o relativas al paquete. El plan es hacer que las importaciones absolutas sean el valor por defecto en futuras versiones de Python.

Digamos que tienes un directorio de paquetes como este:

pkg/
pkg/__init__.py
pkg/main.py
pkg/string.py

Esto define un paquete llamado pkg que contiene los submódulos pkg.main y pkg.string.

Considera el código del módulo main.py. ¿Qué ocurre si ejecuta la sentencia importar cadena? En Python 2.4 y anteriores, primero buscará en el directorio del paquete para realizar una importación relativa, encuentra pkg/string.py, importa el contenido de ese archivo como el módulo pkg.string, y ese módulo se vincula al nombre string en el espacio de nombres del módulo pkg.main.

Eso está bien si pkg.string era lo que querías. ¿Pero qué pasa si quieres el módulo estándar de Python string? No hay una forma limpia de ignorar pkg.string y buscar el módulo estándar; generalmente tienes que mirar el contenido de sys.modules, lo cual es ligeramente sucio. El paquete py.std de Holger Krekel proporciona una forma más ordenada de realizar importaciones desde la biblioteca estándar, import py; py.std.string.join(), pero ese paquete no está disponible en todas las instalaciones de Python.

La lectura de código que depende de importaciones relativas también es menos clara, porque un lector puede confundirse sobre qué módulo, cadena o cadena.pkg, se pretende utilizar. Los usuarios de Python aprendieron pronto a no duplicar los nombres de los módulos de la biblioteca estándar en los nombres de los submódulos de sus paquetes, pero no puedes protegerte de que el nombre de tu submódulo se utilice para un nuevo módulo añadido en una futura versión de Python.

En Python 2.5, puedes cambiar el comportamiento de import a importaciones absolutas usando una directiva from __future__ import absolute_import. Este comportamiento de importación absoluta será el predeterminado en una versión futura (probablemente Python 2.7). Una vez que las importaciones absolutas sean el valor por defecto, import string siempre encontrará la versión de la biblioteca estándar. Se sugiere que los usuarios comiencen a usar importaciones absolutas tanto como sea posible, así que es preferible comenzar a escribir de pkg import string en su código.

Las importaciones relativas siguen siendo posibles añadiendo un punto inicial al nombre del módulo cuando se utiliza la forma from ... import:

# Import names from pkg.string
from .string import name1, name2
# Import pkg.string
from . import string

Esto importa el módulo string relativo al paquete actual, así que en pkg.main esto importará nombre1 y nombre2 de pkg.string. Los puntos iniciales adicionales realizan la importación relativa empezando por el padre del paquete actual. Por ejemplo, el código en el módulo A.B.C puede hacer:

from . import D                 # Imports A.B.D
from .. import E                # Imports A.E
from ..F import G               # Imports A.F.G

Los puntos suspensivos no pueden usarse con la forma importar nombre de modelo de la sentencia import, sólo con la forma de ... import.

Ver también

PEP 328 [https://www.python.org/dev/peps/pep-0328] - Importaciones: Multilínea y Absoluto/Relativo

PEP escrito por Aahz; implementado por Thomas Wouters.

https://pylib.readthedocs.io/

La biblioteca py de Holger Krekel, que contiene el paquete py.std.

PEP 338: Ejecutando Módulos como Scripts

El conmutador -m añadido en Python 2.4 para ejecutar un módulo como un script ganó algunas habilidades más. En lugar de estar implementado en código C dentro del intérprete de Python, el interruptor ahora utiliza una implementación en un nuevo módulo, runpy.

El módulo runpy implementa un mecanismo de importación más sofisticado de forma que ahora es posible ejecutar módulos en un paquete como pychecker.checker. El módulo también soporta mecanismos de importación alternativos como el módulo zipimport. Esto significa que puede añadir la ruta de un archivo .zip a sys.path y luego utilizar el modificador -m para ejecutar el código del archivo.

Ver también

PEP 338 [https://www.python.org/dev/peps/pep-0338] - Ejecución de módulos como scripts

PEP escrito e implementado por Nick Coghlan.

PEP 341: Try/except/finally unificados

Hasta la versión 2.5 de Python, la sentencia try tenía dos variantes. Podías usar un bloque finally para asegurarte de que el código se ejecutaba siempre, o uno o más bloques except para capturar excepciones específicas. No podías combinar ambos bloques except y un bloque finally, porque generar el bytecode correcto para la versión combinada era complicado y no estaba claro cuál debía ser la semántica de la sentencia combinada.

Guido van Rossum pasó algún tiempo trabajando con Java, que sí soporta el equivalente de combinar bloques except y un bloque finally, y esto aclaró lo que debería significar la declaración. En Python 2.5, ahora se puede escribir:

try:
    block-1 ...
except Exception1:
    handler-1 ...
except Exception2:
    handler-2 ...
else:
    else-block
finally:
    final-block

Se ejecuta el código del bloque-1. Si el código lanza una excepción, se comprueban los distintos bloques except: si la excepción es de clase Exception1, se ejecuta handler-1; en caso contrario, si es de clase Exception2, se ejecuta handler-2, y así sucesivamente. Si no se produce ninguna excepción, se ejecuta el bloque else.

No importa lo que haya sucedido previamente, el bloque final se ejecuta una vez que el bloque de código se ha completado y se han manejado las excepciones planteadas. Incluso si hay un error en un manejador de excepciones o en el bloque else y se lanza una nueva excepción, el código del bloque final se sigue ejecutando.

Ver también

PEP 341 [https://www.python.org/dev/peps/pep-0341] - Unificar try-except y try-finally

PEP escrito por Georg Brandl; implementación por Thomas Lee.

PEP 342: Nuevas funciones del generador

Python 2.5 añade una forma sencilla de pasar valores a un generador. Tal y como se introdujo en Python 2.3, los generadores sólo producen salida; una vez que se invoca el código de un generador para crear un iterador, no hay forma de pasar ninguna información nueva a la función cuando se reanuda su ejecución. A veces, la capacidad de pasar alguna información sería útil. Las soluciones más ingeniosas para esto incluyen hacer que el código del generador mire a una variable global y luego cambie el valor de la variable global, o pasar algún objeto mutable que los llamadores luego modifiquen.

Para refrescar la memoria de los generadores básicos, he aquí un ejemplo sencillo:

def counter (maximum):
    i = 0
    while i < maximum:
        yield i
        i += 1

Cuando se llama a contador(10), el resultado es un iterador que devuelve los valores de 0 a 9. Al encontrar la sentencia yield, el iterador devuelve el valor proporcionado y suspende la ejecución de la función, preservando las variables locales. La ejecución se reanuda en la siguiente llamada al método next() del iterador, retomando después de la sentencia yield.

En Python 2.3, yield era una declaración; no devolvía ningún valor. En 2.5, yield es ahora una expresión, que devuelve un valor que se puede asignar a una variable o que se puede operar de otra manera:

val = (yield i)

Te recomiendo que siempre pongas paréntesis alrededor de una expresión yield cuando estés haciendo algo con el valor devuelto, como en el ejemplo anterior. Los paréntesis no siempre son necesarios, pero es más fácil añadirlos siempre en lugar de tener que recordar cuándo son necesarios.

(PEP 342 [https://www.python.org/dev/peps/pep-0342] explica las reglas exactas, que consisten en que una expresión yielddebe ir siempre entre paréntesis, excepto cuando ocurre en la expresión de nivel superior en el lado derecho de una asignación. Esto significa que puedes escribir val = yield i pero tienes que usar paréntesis cuando hay una operación, como en val = (yield i) + 12)

Los valores se envían a un generador llamando a su método send(value). El código del generador se reanuda y la expresión yield devuelve el valor especificado. Si se llama al método regular next(), la expresión yield devuelve None.

Aquí está el ejemplo anterior, modificado para permitir cambiar el valor del contador interno.

def counter (maximum):
    i = 0
    while i < maximum:
        val = (yield i)
        # If value provided, change counter
        if val is not None:
            i = val
        else:
            i += 1

Y aquí hay un ejemplo de cambio de contador:

>>> it = counter(10)
>>> print it.next()
0
>>> print it.next()
1
>>> print it.send(8)
8
>>> print it.next()
9
>>> print it.next()
Traceback (most recent call last):
  File "t.py", line 15, in ?
    print it.next()
StopIteration

yield normalmente devolverá None, por lo que siempre debes comprobar este caso. No utilices su valor en las expresiones sin más, a menos que estés seguro de que el método send() será el único utilizado para reanudar tu función generadora.

Además de send(), hay otros dos nuevos métodos en los generadores:

throw(type, value=None, traceback=None) se utiliza para lanzar una excepción dentro del generador; la excepción es lanzada por la expresión yield donde la ejecución del generador se pausa.

close() lanza una nueva excepción GeneratorExit dentro del generador para terminar la iteración. Al recibir esta excepción, el código del generador debe lanzar GeneratorExit o StopIteration. Capturar la excepción GeneratorExit y devolver un valor es ilegal y provocará un RuntimeError; si la función lanza alguna otra excepción, esa excepción se propaga a quien la llama. close() también será llamado por el recolector de basura de Python cuando el generador sea recolectado.

Si necesitas ejecutar código de limpieza cuando se produce un GeneratorExit, te sugiero que utilices un conjunto try: ... finally: en lugar de atrapar GeneratorExit.

El efecto acumulativo de estos cambios es que los generadores pasan de ser productores unidireccionales de información a ser tanto productores como consumidores.

Los generadores también se convierten en corutinas, una forma más generalizada de subrutinas. Las subrutinas se introducen en un punto y se salen en otro (la parte superior de la función, y una declaración return), pero las coroutines pueden introducirse, salirse y reanudarse en muchos puntos diferentes (las declaraciones yield). Tendremos que descubrir patrones para usar coroutines de forma efectiva en Python.

La adición del método close() tiene un efecto secundario que no es obvio. close() es llamado cuando un generador es recogido por la basura, lo que significa que el código del generador tiene una última oportunidad de ejecutarse antes de que el generador sea destruido. Esta última oportunidad significa que ahora se puede garantizar que las sentencias intentar...finalmente en los generadores funcionen; la cláusula finally ahora siempre tendrá una oportunidad de ejecutarse. Por lo tanto, se ha eliminado la restricción sintáctica que impedía mezclar sentencias yield con un conjunto try...finally. Esto parece una trivialidad menor del lenguaje, pero el uso de generadores y try...finally es realmente necesario para implementar la sentencia with descrita por PEP 343 [https://www.python.org/dev/peps/pep-0343]. Veré esta nueva sentencia en la siguiente sección.

Otro efecto aún más esotérico de este cambio: antes, el atributo gi_frame de un generador era siempre un objeto frame. Ahora es posible que gi_frame sea None una vez que el generador se ha agotado.

Ver también

PEP 342 [https://www.python.org/dev/peps/pep-0342] - Coroutines mediante generadores mejorados

PEP escrito por Guido van Rossum y Phillip J. Eby; implementado por Phillip J. Eby. Incluye ejemplos de algunos usos más sofisticados de los generadores como coroutines.

Versiones anteriores de estas características fueron propuestas en PEP 288 [https://www.python.org/dev/peps/pep-0288] por Raymond Hettinger y PEP 325 [https://www.python.org/dev/peps/pep-0325] por Samuele Pedroni.

https://en.wikipedia.org/wiki/Coroutine

La entrada de Wikipedia para las coroutines.

http://www.sidhe.org/~dan/blog/archivos/000178.html

Una explicación de las coroutines desde el punto de vista de Perl, escrita por Dan Sugalski.

PEP 343: La declaración «con

La sentencia “with” aclara el código que antes utilizaba bloques try...finally” para asegurar que se ejecuta el código de limpieza. En esta sección, hablaré de la sentencia tal y como se utiliza habitualmente. En la siguiente sección, examinaré los detalles de la implementación y mostraré cómo escribir objetos para usar con esta sentencia.

La declaración “with” es una nueva estructura de flujo de control cuya estructura básica es:

with expression [as variable]:
    with-block

La expresión se evalúa y debe dar como resultado un objeto que soporte el protocolo de gestión de contextos (es decir, que tenga los métodos __enter__() y __exit__()).

El __enter__() del objeto es llamado antes de que se ejecute with-block y por lo tanto puede ejecutar código de configuración. También puede devolver un valor ligado al nombre variable, si se da. (Observe cuidadosamente que a variable no se le asigna el resultado de la expresión)

Una vez finalizada la ejecución del with-block, se llama al método __exit__() del objeto, incluso si el bloque lanzó una excepción, y por lo tanto puede ejecutar código de limpieza.

Para habilitar la declaración en Python 2.5, debe añadir la siguiente directiva a su módulo:

from __future__ import with_statement

La declaración siempre estará habilitada en Python 2.6.

Algunos objetos estándar de Python soportan ahora el protocolo de gestión de contextos y pueden utilizarse con la sentencia “with””. Los objetos de archivo son un ejemplo:

with open('/etc/passwd', 'r') as f:
    for line in f:
        print line
        ... more processing code ...

Después de que esta sentencia se haya ejecutado, el objeto archivo en f se habrá cerrado automáticamente, incluso si el bucle for lanzó una excepción a mitad del bloque.

Nota

En este caso, f es el mismo objeto creado por open(), porque file.__enter__() devuelve self.

Los bloqueos y las variables de condición del módulo threading también soportan la sentencia “with”:

lock = threading.Lock()
with lock:
    # Critical section of code
    ...

El bloqueo se adquiere antes de que se ejecute el bloque y siempre se libera una vez que el bloque se ha completado.

La nueva función localcontext() del módulo decimal facilita el guardado y la restauración del contexto decimal actual, que encapsula las características de precisión y redondeo deseadas para los cálculos:

from decimal import Decimal, Context, localcontext

# Displays with default precision of 28 digits
v = Decimal('578')
print v.sqrt()

with localcontext(Context(prec=16)):
    # All code in this block uses a precision of 16 digits.
    # The original context is restored on exiting the block.
    print v.sqrt()

Redacción de Gestores de Contexto

Bajo el capó, la sentencia “with” es bastante complicada. La mayoría de la gente sólo utilizará “with” en compañía de objetos existentes y no necesita conocer estos detalles, así que puedes saltarte el resto de esta sección si quieres. Los autores de nuevos objetos necesitarán entender los detalles de la implementación subyacente y deberían seguir leyendo.

Una explicación de alto nivel del protocolo de gestión del contexto es:

La expresión se evalúa y debe dar como resultado un objeto llamado «gestor de contexto». El gestor de contexto debe tener métodos __enter__() y __exit__().

Se llama al método __enter__() del gestor de contexto. El valor devuelto se asigna a VAR. Si no está presente la cláusula 'as VAR', el valor simplemente se descarta.

Se ejecuta el código en BLOQUE.

Si BLOCK lanza una excepción, se llama a __exit__(type, value, traceback) con los detalles de la excepción, los mismos valores devueltos por sys.exc_info(). El valor de retorno del método controla si la excepción se vuelve a lanzar: cualquier valor falso vuelve a lanzar la excepción, y True resultará en suprimirla. Sólo en raras ocasiones querrá suprimir la excepción, porque si lo hace el autor del código que contiene la declaración “with” nunca se dará cuenta de que algo ha ido mal.

Si BLOCK no lanzó una excepción, el método __exit__() sigue siendo llamado, pero type, value, y traceback son todos None.

Pensemos en un ejemplo. No presentaré un código detallado, sino que sólo esbozaré los métodos necesarios para una base de datos que soporte transacciones.

(Para quienes no estén familiarizados con la terminología de las bases de datos: un conjunto de cambios en la base de datos se agrupa en una transacción. Las transacciones pueden ser confirmadas, lo que significa que todos los cambios se escriben en la base de datos, o revertidas, lo que significa que todos los cambios se descartan y la base de datos no se modifica. Consulte cualquier libro de texto sobre bases de datos para obtener más información)

Supongamos que hay un objeto que representa una conexión a la base de datos. Nuestro objetivo será permitir que el usuario escriba código como este:

db_connection = DatabaseConnection()
with db_connection as cursor:
    cursor.execute('insert into ...')
    cursor.execute('delete from ...')
    # ... more operations ...

La transacción debe ser confirmada si el código en el bloque se ejecuta sin problemas o revertida si hay una excepción. Aquí está la interfaz básica para DatabaseConnection que voy a asumir:

class DatabaseConnection:
    # Database interface
    def cursor (self):
        "Returns a cursor object and starts a new transaction"
    def commit (self):
        "Commits current transaction"
    def rollback (self):
        "Rolls back current transaction"

El método __enter__() es bastante sencillo, ya que sólo hay que iniciar una nueva transacción. Para esta aplicación el objeto cursor resultante sería un resultado útil, por lo que el método lo devolverá. El usuario puede entonces añadir as cursor a su sentencia “with” para ligar el cursor a un nombre de variable.

class DatabaseConnection:
    ...
    def __enter__ (self):
        # Code to start a new transaction
        cursor = self.cursor()
        return cursor

El método __exit__() es el más complicado porque es donde hay que hacer la mayor parte del trabajo. El método tiene que comprobar si se produjo una excepción. Si no hubo ninguna excepción, la transacción es confirmada. La transacción es revertida si hubo una excepción.

En el código de abajo, la ejecución simplemente caerá al final de la función, devolviendo el valor por defecto de None. None es falso, por lo que la excepción se volverá a lanzar automáticamente. Si lo desea, puede ser más explícito y añadir una declaración return en el lugar marcado.

class DatabaseConnection:
    ...
    def __exit__ (self, type, value, tb):
        if tb is None:
            # No exception, so commit
            self.commit()
        else:
            # Exception occurred, so rollback.
            self.rollback()
            # return False

El módulo contextlib

El nuevo módulo contextlib proporciona algunas funciones y un decorador que son útiles para escribir objetos para usar con la sentencia “with”.

El decorador se llama contextmanager(), y permite escribir una única función generadora en lugar de definir una nueva clase. El generador debe producir exactamente un valor. El código hasta la palabra clave yield se ejecutará como el método __enter__(), y el valor producido será el valor de retorno del método que se vinculará a la variable en la cláusula with de la sentencia as, si existe. El código después de yield se ejecutará en el método __exit__(). Cualquier excepción lanzada en el bloque será lanzada por la sentencia yield.

Nuestro ejemplo de base de datos de la sección anterior podría escribirse utilizando este decorador como:

from contextlib import contextmanager

@contextmanager
def db_transaction (connection):
    cursor = connection.cursor()
    try:
        yield cursor
    except:
        connection.rollback()
        raise
    else:
        connection.commit()

db = DatabaseConnection()
with db_transaction(db) as cursor:
    ...

El módulo contextlib también tiene una función anidada(mgr1, mgr2, ...) que combina varios gestores de contexto para que no sea necesario escribir sentencias “with” anidadas. En este ejemplo, la única sentencia “with` inicia una transacción de base de datos y adquiere un bloqueo de hilo:

lock = threading.Lock()
with nested (db_transaction(db), lock) as (cursor, locked):
    ...

Por último, la función closing(object) devuelve el objeto para que pueda ser vinculado a una variable, y llama a object.close al final del bloque.

import urllib, sys
from contextlib import closing

with closing(urllib.urlopen('http://www.yahoo.com')) as f:
    for line in f:
        sys.stdout.write(line)

Ver también

PEP 343 [https://www.python.org/dev/peps/pep-0343] - La declaración «con»

PEP escrito por Guido van Rossum y Nick Coghlan; implementado por Mike Bland, Guido van Rossum y Neal Norwitz. El PEP muestra el código generado para una sentencia “with”, que puede ser útil para aprender cómo funciona la sentencia.

La documentación del módulo contextlib.

PEP 352: Las excepciones como clases de nuevo estilo

Las clases de excepción ahora pueden ser clases de nuevo estilo, no sólo clases clásicas, y la clase incorporada Exception y todas las excepciones incorporadas estándar (NameError, ValueError, etc.) son ahora clases de nuevo estilo.

La jerarquía de herencia de las excepciones se ha reordenado un poco. En 2.5, las relaciones de herencia son:

BaseException       # New in Python 2.5
|- KeyboardInterrupt
|- SystemExit
|- Exception
   |- (all other current built-in exceptions)

Esta reorganización se hizo porque la gente a menudo quiere atrapar todas las excepciones que indican errores del programa. KeyboardInterrupt y SystemExit no son errores, sin embargo, y por lo general representan una acción explícita como el usuario pulsando Control-C o el código llamando a sys.exit(). Una simple except: atrapará todas las excepciones, por lo que comúnmente se necesita listar KeyboardInterrupt y SystemExit para volver a lanzarlas. El patrón habitual es:

try:
    ...
except (KeyboardInterrupt, SystemExit):
    raise
except:
    # Log error...
    # Continue running program...

En Python 2.5, ahora puedes escribir except Exception para conseguir el mismo resultado, capturando todas las excepciones que suelen indicar errores pero dejando KeyboardInterrupt y SystemExit en paz. Como en versiones anteriores, un except: desnudo sigue capturando todas las excepciones.

El objetivo de Python 3.0 es requerir que cualquier clase lanzada como excepción derive de BaseException o de algún descendiente de BaseException, y las futuras versiones de la serie Python 2.x pueden empezar a imponer esta restricción. Por lo tanto, sugiero que empieces a hacer que todas tus clases de excepción deriven de Exception ahora. Se ha sugerido que la forma desnuda except: sea eliminada en Python 3.0, pero Guido van Rossum no ha decidido si hacerlo o no.

El lanzamiento de cadenas como excepciones, como en la declaración raise "Error occurred", está obsoleto en Python 2.5 y provocará una advertencia. El objetivo es poder eliminar la función de excepción de cadena en algunas versiones.

Ver también

PEP 352 [https://www.python.org/dev/peps/pep-0352] - Superclase necesaria para las excepciones

PEP escrito por Brett Cannon y Guido van Rossum; implementado por Brett Cannon.

PEP 353: Uso de ssize_t como tipo de índice

Un amplio cambio en la API C de Python, que utiliza una nueva definición de tipo Py_ssize_t en lugar de int, permitirá al intérprete manejar más datos en plataformas de 64 bits. Este cambio no afecta a la capacidad de Python en plataformas de 32 bits.

Varias partes del intérprete de Python utilizaban el tipo int de C para almacenar tamaños o recuentos; por ejemplo, el número de elementos de una lista o tupla se almacenaba en un int. Los compiladores de C para la mayoría de las plataformas de 64 bits siguen definiendo int como un tipo de 32 bits, lo que significa que las listas sólo pueden contener hasta 2**31 - 1 = 2147483647 elementos. (En realidad, hay algunos modelos de programación diferentes que los compiladores de C de 64 bits pueden utilizar – véase http://www.unix.org/version2/whatsnew/lp64_wp.html para una discusión – pero el modelo más comúnmente disponible deja int como de 32 bits)

Un límite de 2147483647 elementos no importa realmente en una plataforma de 32 bits porque te quedarás sin memoria antes de alcanzar el límite de longitud. Cada elemento de la lista requiere espacio para un puntero, que es de 4 bytes, más espacio para un PyObject que representa el elemento. 2147483647*4 ya son más bytes de los que puede contener un espacio de direcciones de 32 bits.

Sin embargo, es posible direccionar esa cantidad de memoria en una plataforma de 64 bits. Los punteros para una lista de ese tamaño sólo requerirían 16 GiB de espacio, por lo que no es descabellado que los programadores de Python puedan construir listas tan grandes. Por lo tanto, el intérprete de Python tuvo que ser cambiado para usar algún tipo diferente a int, y este será un tipo de 64 bits en plataformas de 64 bits. El cambio causará incompatibilidades en las máquinas de 64 bits, por lo que se consideró que valía la pena hacer la transición ahora, mientras el número de usuarios de 64 bits es todavía relativamente pequeño. (En 5 o 10 años, puede que todos estemos en máquinas de 64 bits, y la transición sería entonces más dolorosa)

Este cambio afecta en mayor medida a los autores de módulos de extensión de C. Las cadenas de Python y los tipos contenedores como las listas y las tuplas utilizan ahora Py_ssize_t para almacenar su tamaño. Funciones como PyList_Size() ahora devuelven Py_ssize_t. Por lo tanto, el código de los módulos de extensión puede necesitar cambiar algunas variables a Py_ssize_t.

Las funciones PyArg_ParseTuple() y Py_BuildValue() tienen un nuevo código de conversión, n, para Py_ssize_t. Las funciones PyArg_ParseTuple() s# y t# siguen devolviendo int por defecto, pero puedes definir la macro PY_SSIZE_T_CLEAN antes de incluir Python.h para que devuelvan Py_ssize_t.

PEP 353 [https://www.python.org/dev/peps/pep-0353] tiene una sección sobre directrices de conversión que los autores de extensiones deberían leer para aprender a soportar plataformas de 64 bits.

Ver también

PEP 353 [https://www.python.org/dev/peps/pep-0353] - Uso de ssize_t como tipo de índice

PEP escrito y aplicado por Martin von Löwis.

PEP 357: El método “__index__”

Los desarrolladores de NumPy tenían un problema que sólo podía resolverse añadiendo un nuevo método especial, __index__(). Cuando se utiliza la notación de trozos, como en [start:stop:step], los valores de los índices start, stop y step deben ser todos enteros o enteros largos. NumPy define una variedad de tipos de enteros especializados que corresponden a enteros sin signo y con signo de 8, 16, 32 y 64 bits, pero no había forma de señalar que estos tipos pudieran usarse como índices de trozos.

El rebanado no puede utilizar el método __int__() existente porque ese método también se utiliza para implementar la coerción a enteros. Si el rebanado utilizara __int__(), los números de punto flotante también se convertirían en índices de rebanada legales y eso es claramente un comportamiento indeseable.

En su lugar, se ha añadido un nuevo método especial llamado __index__(). No toma argumentos y devuelve un entero que da el índice de corte a utilizar. Por ejemplo:

class C:
    def __index__ (self):
        return self.value

El valor devuelto debe ser un entero de Python o un entero largo. El intérprete comprobará que el tipo devuelto es correcto, y lanza un TypeError si no se cumple este requisito.

Se ha añadido la correspondiente ranura nb_index a la estructura PyNumberMethods de nivel C para que las extensiones C puedan implementar este protocolo. El código de la extensión puede utilizar PyNumber_Index(obj) para llamar a la función __index__() y obtener su resultado.

Ver también

PEP 357 [https://www.python.org/dev/peps/pep-0357] - Permitir el uso de cualquier objeto para rebanar

PEP escrito e implementado por Travis Oliphant.

Otros cambios lingüísticos

Estos son todos los cambios que Python 2.5 introduce en el núcleo del lenguaje Python.

El tipo dict tiene un nuevo gancho para permitir que las subclases proporcionen un valor por defecto cuando una clave no está contenida en el diccionario. Cuando no se encuentre una clave, se llamará al método missing__(key) del diccionario. Este hook se utiliza para implementar la nueva clase defaultdict en el módulo collections. El siguiente ejemplo define un diccionario que devuelve cero para cualquier clave que falte:

class zerodict (dict):
    def __missing__ (self, key):
        return 0

d = zerodict({1:1, 2:2})
print d[1], d[2]   # Prints 1, 2
print d[3], d[4]   # Prints 0, 0

Tanto las cadenas de 8 bits como las de Unicode tienen nuevos métodos partition(sep) y rpartition(sep) que simplifican un caso de uso común.

El método find(S) se utiliza a menudo para obtener un índice que luego se utiliza para cortar la cadena y obtener las piezas que están antes y después del separador. El método partition(sep) condensa este patrón en una sola llamada al método que devuelve una tripleta que contiene la subcadena antes del separador, el propio separador y la subcadena después del separador. Si no se encuentra el separador, el primer elemento de la tupla es la cadena completa y los otros dos elementos están vacíos. rpartition(sep) también devuelve una tupla de 3 elementos, pero empieza a buscar desde el final de la cadena; la r significa «al revés».

Algunos ejemplos:

>>> ('http://www.python.org').partition('://')
('http', '://', 'www.python.org')
>>> ('file:/usr/share/doc/index.html').partition('://')
('file:/usr/share/doc/index.html', '', '')
>>> (u'Subject: a quick question').partition(':')
(u'Subject', u':', u' a quick question')
>>> 'www.python.org'.rpartition('.')
('www.python', '.', 'org')
>>> 'www.python.org'.rpartition(':')
('', '', 'www.python.org')

(Implementado por Fredrik Lundh tras una sugerencia de Raymond Hettinger)

Los métodos startswith() y endswith() de los tipos de cadena aceptan ahora tuplas de cadenas para su comprobación.

def is_image_file (filename):
    return filename.endswith(('.gif', '.jpg', '.tiff'))

(Implementado por Georg Brandl tras una sugerencia de Tom Lynn)

Las funciones incorporadas min() y max() han ganado un parámetro de palabra clave key análogo al argumento key de sort(). Este parámetro proporciona una función que toma un único argumento y es llamada para cada valor de la lista; min()/max() devolverá el elemento con el valor de retorno más pequeño/más grande de esta función. Por ejemplo, para encontrar la cadena más larga de una lista, puede hacer:

L = ['medium', 'longest', 'short']
# Prints 'longest'
print max(L, key=len)
# Prints 'short', because lexicographically 'short' has the largest value
print max(L)

(Contribución de Steven Bethard y Raymond Hettinger)

Dos nuevas funciones incorporadas, any() y all(), evalúan si un iterador contiene algún valor verdadero o falso. any() devuelve True si cualquier valor devuelto por el iterador es verdadero; en caso contrario devolverá False. all() devuelve True sólo si todos los valores devueltos por el iterador se evalúan como verdaderos. (Sugerido por Guido van Rossum, e implementado por Raymond Hettinger)

El resultado del método __hash__() de una clase puede ser ahora un entero largo o un entero normal. Si se devuelve un entero largo, se toma el hash de ese valor. En versiones anteriores se requería que el valor del hash fuera un entero regular, pero en 2.5 el built-in id() se cambió para devolver siempre números no negativos, y los usuarios parecen utilizar a menudo id(self) en los métodos __hash__() (aunque esto se desaconseja).

ASCII es ahora la codificación por defecto para los módulos. Ahora es un error de sintaxis si un módulo contiene literales de cadena con caracteres de 8 bits pero no tiene una declaración de codificación. En Python 2.4 esto provocaba una advertencia, no un error de sintaxis. Vea en PEP 263 [https://www.python.org/dev/peps/pep-0263] cómo declarar la codificación de un módulo; por ejemplo, puede añadir una línea como ésta cerca de la parte superior del fichero fuente:

# -*- coding: latin1 -*-

Una nueva advertencia, UnicodeWarning, se activa cuando se intenta comparar una cadena Unicode y una cadena de 8 bits que no se puede convertir a Unicode utilizando la codificación ASCII por defecto. El resultado de la comparación es falso:

>>> chr(128) == unichr(128)   # Can't convert chr(128) to Unicode
__main__:1: UnicodeWarning: Unicode equal comparison failed
  to convert both arguments to Unicode - interpreting them
  as being unequal
False
>>> chr(127) == unichr(127)   # chr(127) can be converted
True

Anteriormente, esto lanzaba una excepción UnicodeDecodeError, pero en 2.5 esto podía dar lugar a problemas desconcertantes al acceder a un diccionario. Si se buscaba unichr(128) y se utilizaba chr(128) como clave, se producía una excepción UnicodeDecodeError. Otros cambios en la versión 2.5 hicieron que esta excepción se lanzara en lugar de ser suprimida por el código de dictobject.c que implementa los diccionarios.

Lanzar una excepción para tal comparación es estrictamente correcto, pero el cambio podría haber roto el código, así que en su lugar se introdujo UnicodeWarning.

(Implementado por Marc-André Lemburg.)

Un error que a veces cometen los programadores de Python es olvidarse de incluir un módulo __init__.py en el directorio de un paquete. Depurar este error puede ser confuso, y normalmente requiere ejecutar Python con el modificador -v para registrar todas las rutas buscadas. En Python 2.5, una nueva advertencia ImportWarning se activa cuando una importación habría recogido un directorio como paquete pero no se encontró ningún __init__.py. Esta advertencia se ignora silenciosamente por defecto; proporcione la opción -Wd cuando ejecute el ejecutable de Python para mostrar el mensaje de advertencia. (Implementado por Thomas Wouters)</-W>

La lista de clases base en una definición de clase ahora puede estar vacía. Como ejemplo, esto es ahora legal:

class C():
    pass

(Implementado por Brett Cannon.)

Cambios en el intérprete interactivo

En el intérprete interactivo, quit y exit han sido durante mucho tiempo cadenas para que los nuevos usuarios obtengan un mensaje algo útil cuando intenten salir:

>>> quit
'Use Ctrl-D (i.e. EOF) to exit.'

En Python 2.5, quit y exit son ahora objetos que siguen produciendo representaciones de cadena de sí mismos, pero también son invocables. Los novatos que prueben quit() o exit() ahora saldrán del intérprete como se espera. (Implementado por Georg Brandl.)

El ejecutable de Python ahora acepta las opciones largas estándar --help y --version; en Windows, también acepta la opción /? para mostrar un mensaje de ayuda. (Implementado por Georg Brandl)

Optimizaciones

Varias de las optimizaciones se desarrollaron en el sprint NeedForSpeed, un evento celebrado en Reikiavik, Islandia, del 21 al 28 de mayo de 2006. El sprint se centró en las mejoras de velocidad de la implementación de CPython y fue financiado por EWT LLC con el apoyo local de CCP Games. Las optimizaciones añadidas en este sprint están especialmente marcadas en la siguiente lista.

Cuando se introdujeron en Python 2.4, los tipos incorporados set y frozenset se construyeron sobre el tipo diccionario de Python. En 2.5 la estructura de datos interna se ha personalizado para implementar conjuntos, y como resultado los conjuntos utilizarán un tercio menos de memoria y son algo más rápidos. (Implementado por Raymond Hettinger)

Se ha mejorado la velocidad de algunas operaciones Unicode, como la búsqueda de subcadenas, la división de cadenas y la codificación y decodificación de mapas de caracteres. (Las mejoras en la búsqueda de subcadenas y la división fueron añadidas por Fredrik Lundh y Andrew Dalke en el sprint NeedForSpeed. Los mapas de caracteres fueron mejorados por Walter Dörwald y Martin von Löwis)

La función long(str, base) es ahora más rápida en cadenas de dígitos largos porque se calculan menos resultados intermedios. El máximo es para cadenas de alrededor de 800-1000 dígitos, donde la función es 6 veces más rápida. (Aportado por Alan McIntyre y comprometido en el sprint NeedForSpeed)

Ahora es ilegal mezclar la iteración sobre un fichero con for line in file y llamar a los métodos read()/readline()/readlines() del objeto fichero. La iteración utiliza un buffer interno y los métodos read*() no utilizan ese buffer. En su lugar, devolverán los datos que siguen al buffer, haciendo que los datos aparezcan desordenados. Mezclar la iteración y estos métodos provocará ahora un ValueError del método read*(). (Implementado por Thomas Wouters)

El módulo struct ahora compila cadenas de formato de estructura en una representación interna y almacena en caché esta representación, lo que supone una mejora del 20% s. (Contribuido por Bob Ippolito en el sprint NeedForSpeed)

El módulo re obtuvo un 1 o 2% s de velocidad al cambiar a las funciones asignadoras de Python en lugar de las malloc() y free() del sistema. (Contribuido por Jack Diederich en el sprint NeedForSpeed)

El optimizador de la mirilla del generador de código realiza ahora un simple plegado de constantes en las expresiones. Si escribes algo como a = 2+3, el generador de código hará la aritmética y producirá el código correspondiente a a = 5. (Propuesto e implementado por Raymond Hettinger)

Las llamadas a funciones son ahora más rápidas porque los objetos de código guardan ahora el último fotograma terminado (un «fotograma zombi») en un campo interno del objeto de código, reutilizándolo la próxima vez que se invoque el objeto de código. (Parche original de Michael Hudson, modificado por Armin Rigo y Richard Jones; confirmado en el sprint NeedForSpeed) Los objetos marco son también ligeramente más pequeños, lo que puede mejorar la localidad de la caché y reducir un poco el uso de la memoria. (Contribución de Neal Norwitz)

Las excepciones incorporadas en Python son ahora clases de nuevo estilo, un cambio que acelera considerablemente la instanciación. El manejo de excepciones en Python 2.5 es, por tanto, un 30% f más rápido que en 2.4. (Contribución de Richard Jones, Georg Brandl y Sean Reifschneider en el sprint NeedForSpeed)

La importación ahora almacena en caché las rutas intentadas, registrando si existen o no para que el intérprete haga menos llamadas a open() y stat() al iniciar. (Contribución de Martin von Löwis y Georg Brandl)

Módulos nuevos, mejorados y eliminados

La biblioteca estándar ha recibido muchas mejoras y correcciones de errores en Python 2.5. Aquí hay una lista parcial de los cambios más notables, ordenados alfabéticamente por el nombre del módulo. Consulte el archivo Misc/NEWS en el árbol de fuentes para obtener una lista más completa de los cambios, o busque en los registros de SVN para obtener todos los detalles.

El módulo audioop soporta ahora la codificación a-LAW, y se ha mejorado el código para la codificación u-LAW. (Contribución de Lars Immisch)

El módulo codecs ha ganado soporte para códecs incrementales. La función codec.lookup() devuelve ahora una instancia de CodecInfo en lugar de una tupla. Las instancias de CodecInfo se comportan como una cuádruple tupla para preservar la compatibilidad con versiones anteriores, pero también tienen los atributos encode, decode, incrementalencoder, incrementaldecoder, streamwriter y streamreader. Los códecs incrementales pueden recibir la entrada y producir la salida en varios trozos; la salida es la misma que si la entrada completa fuera alimentada por el códec no incremental. Consulte la documentación del módulo codecs para más detalles. (Diseñado e implementado por Walter Dörwald)

El módulo collections ha ganado un nuevo tipo, defaultdict, que subclasifica el tipo estándar dict. El nuevo tipo se comporta principalmente como un diccionario pero construye un valor por defecto cuando una clave no está presente, añadiéndolo automáticamente al diccionario para el valor de la clave solicitada.

El primer argumento del constructor de defaultdict es una función de fábrica que se llama cada vez que se solicita una clave pero no se encuentra. Esta función de fábrica no recibe argumentos, por lo que puede utilizar constructores de tipo incorporado como list() o int(). Por ejemplo, puedes hacer un índice de palabras basado en su letra inicial así:

words = """Nel mezzo del cammin di nostra vita
mi ritrovai per una selva oscura
che la diritta via era smarrita""".lower().split()

index = defaultdict(list)

for w in words:
    init_letter = w[0]
    index[init_letter].append(w)

Al imprimir index se obtiene la siguiente salida:

defaultdict(<type 'list'>, {'c': ['cammin', 'che'], 'e': ['era'],
        'd': ['del', 'di', 'diritta'], 'm': ['mezzo', 'mi'],
        'l': ['la'], 'o': ['oscura'], 'n': ['nel', 'nostra'],
        'p': ['per'], 's': ['selva', 'smarrita'],
        'r': ['ritrovai'], 'u': ['una'], 'v': ['vita', 'via']}

(Contribución de Guido van Rossum.)

El tipo de cola doble deque suministrado por el módulo collections tiene ahora un método remove(value) que elimina la primera aparición de value en la cola, lanzando ValueError si no se encuentra el valor. (Contribución de Raymond Hettinger)

Nuevo módulo: El módulo contextlib contiene funciones de ayuda para usar con la nueva sentencia “with”. Consulte la sección El módulo contextlib para obtener más información sobre este módulo.

Nuevo módulo: El módulo cProfile es una implementación en C del módulo existente profile que tiene una sobrecarga mucho menor. La interfaz del módulo es la misma que la de profile: se ejecuta cProfile.run('main()') para perfilar una función, se pueden guardar los datos del perfil en un archivo, etc. Todavía no se sabe si el perfilador Hotshot, que también está escrito en C pero no coincide con la interfaz del módulo profile, seguirá manteniéndose en futuras versiones de Python. (Contribución de Armin Rigo.)

Además, el módulo pstats para analizar los datos medidos por el perfilador ahora soporta dirigir la salida a cualquier objeto archivo suministrando un argumento stream al constructor Stats. (Contribución de Skip Montanaro)

El módulo csv, que analiza archivos en formato de valores separados por comas, ha recibido varias mejoras y una serie de correcciones de errores. Ahora se puede establecer el tamaño máximo en bytes de un campo llamando a la función csv.field_size_limit(new_limit); si se omite el argumento new_limit se devolverá el límite establecido actualmente. La clase reader tiene ahora un atributo line_num que cuenta el número de líneas físicas leídas de la fuente; los registros pueden abarcar varias líneas físicas, por lo que line_num no es lo mismo que el número de registros leídos.

El analizador CSV es ahora más estricto con los campos entrecomillados de varias líneas. Anteriormente, si una línea terminaba dentro de un campo entre comillas sin un carácter de nueva línea final, se insertaba una nueva línea en el campo devuelto. Este comportamiento causaba problemas cuando se leían archivos que contenían caracteres de retorno de carro dentro de los campos, por lo que se cambió el código para devolver el campo sin insertar nuevas líneas. Como consecuencia, si las nuevas líneas incrustadas dentro de los campos son importantes, la entrada debe dividirse en líneas de manera que se conserven los caracteres de nueva línea.

(Contribución de Skip Montanaro y Andrew McNamara)

La clase datetime del módulo datetime tiene ahora un método strptime(string, format) para analizar cadenas de fechas, aportado por Josh Spoerri. Utiliza los mismos caracteres de formato que time.strptime() y time.strftime():

from datetime import datetime

ts = datetime.strptime('10:13:15 2006-03-07',
                       '%H:%M:%S %Y-%m-%d')

El método SequenceMatcher.get_matching_blocks() del módulo difflib garantiza ahora la devolución de una lista mínima de bloques que describen subsecuencias coincidentes. Anteriormente, el algoritmo rompía ocasionalmente un bloque de elementos coincidentes en dos entradas de la lista. (Mejora realizada por Tim Peters)

El módulo doctest ha ganado una opción SKIP que impide que un ejemplo se ejecute en absoluto. Esto está pensado para los fragmentos de código que son ejemplos de uso destinados al lector y que no son realmente casos de prueba.

Se ha añadido un parámetro encoding a la función testfile() y a la clase DocFileSuite para especificar la codificación del archivo. Esto facilita el uso de caracteres no ASCII en las pruebas contenidas en un docstring. (Contribución de Bjorn Tillenius)

El paquete email ha sido actualizado a la versión 4.0. (Contribución de Barry Warsaw.)

El módulo fileinput se ha hecho más flexible. Ahora se soportan los nombres de archivo Unicode, y se ha añadido un parámetro mode que por defecto es "r" a la función input() para permitir la apertura de archivos en modo binario o universal newlines. Otro nuevo parámetro, openhook, permite utilizar una función distinta de open() para abrir los ficheros de entrada. Una vez que se itera sobre el conjunto de archivos, el nuevo fileno() del objeto FileInput devuelve el descriptor de archivo del archivo actualmente abierto. (Contribuido por Georg Brandl.)

En el módulo gc, la nueva función get_count() devuelve una 3-tupla que contiene los recuentos de recolección actuales para las tres generaciones de GC. Se trata de información contable para el recolector de basura; cuando estos recuentos alcanzan un umbral especificado, se realiza un barrido de recolección de basura. La función gc.collect() existente ahora toma un argumento opcional generación de 0, 1 o 2 para especificar qué generación recoger. (Contribución de Barry Warsaw)

Las funciones nsmallest() y nlargest() del módulo heapq soportan ahora un parámetro de palabra clave key similar al proporcionado por las funciones min()/max() y los métodos sort(). Por ejemplo:

>>> import heapq
>>> L = ["short", 'medium', 'longest', 'longer still']
>>> heapq.nsmallest(2, L)  # Return two lowest elements, lexicographically
['longer still', 'longest']
>>> heapq.nsmallest(2, L, key=len)   # Return two shortest elements
['short', 'medium']

(Contribución de Raymond Hettinger.)

La función itertools.islice() ahora acepta None para los argumentos de inicio y paso. Esto la hace más compatible con los atributos de los objetos slice, por lo que ahora se puede escribir lo siguiente:

s = slice(5)     # Create slice object
itertools.islice(iterable, s.start, s.stop, s.step)

(Contribución de Raymond Hettinger.)

Se ha modificado la función format() del módulo locale y se han añadido dos nuevas funciones, format_string() y currency().

El parámetro val de la función format() podía ser antes una cadena siempre que no apareciera más de un especificador %char; ahora el parámetro debe ser exactamente un especificador %char sin texto alrededor. También se ha añadido un parámetro opcional monetario que, si es Verdadero, utilizará las reglas de la configuración regional para formatear la moneda al colocar un separador entre grupos de tres dígitos.

Para formatear cadenas con múltiples especificadores %char, utilice la nueva función format_string() que funciona como format() pero que también permite mezclar especificadores %char con texto arbitrario.

También se ha añadido una nueva función currency() que formatea un número de acuerdo con la configuración local actual.

(Contribución de Georg Brandl.)

El módulo mailbox ha sido reestructurado de forma masiva para añadir la capacidad de modificar los buzones además de leerlos. Un nuevo conjunto de clases que incluyen mbox, MH, y Maildir se utilizan para leer buzones, y tienen un método add(message) para añadir mensajes, remove(key) para eliminar mensajes, y lock()/unlock() para bloquear/desbloquear el buzón. El siguiente ejemplo convierte un buzón con formato maildir en uno con formato mbox:

import mailbox

# 'factory=None' uses email.Message.Message as the class representing
# individual messages.
src = mailbox.Maildir('maildir', factory=None)
dest = mailbox.mbox('/tmp/mbox')

for msg in src:
    dest.add(msg)

(Contribución de Gregory K. Johnson. La financiación fue proporcionada por el Summer of Code 2005 de Google)

Nuevo módulo: el módulo msilib permite crear archivos .msi de Microsoft Installer y archivos CAB. También se incluye soporte para la lectura de la base de datos .msi. (Contribución de Martin von Löwis)

El módulo nis soporta ahora el acceso a dominios distintos del dominio por defecto del sistema proporcionando un argumento dominio a las funciones nis.match() y nis.maps(). (Contribución de Ben Bell)

Las funciones operator del módulo itemgetter() y attrgetter() ahora soportan múltiples campos. Una llamada como operator.attrgetter('a', 'b') devolverá una función que recupera los atributos a y b. La combinación de esta nueva función con el parámetro key del método sort() permite ordenar fácilmente las listas utilizando varios campos. (Contribución de Raymond Hettinger)

El módulo optparse se ha actualizado a la versión 1.5.1 de la biblioteca Optik. La clase OptionParser obtuvo un atributo epilog, una cadena que se imprimirá después del mensaje de ayuda, y un método destroy() para romper los ciclos de referencia creados por el objeto. (Contribuido por Greg Ward.)

El módulo os ha sufrido varios cambios. La variable stat_float_times ahora está predeterminada a true, lo que significa que os.stat() ahora devolverá los valores de tiempo como flotantes. (Esto no significa necesariamente que os.stat() devolverá tiempos con una precisión de fracciones de segundo; no todos los sistemas soportan dicha precisión)

Se han añadido las constantes os.SEEK_SET, os.SEEK_CUR y os.SEEK_END, que son los parámetros de la función os.lseek(). Dos nuevas constantes para el bloqueo son os.O_SHLOCK y os.O_EXLOCK.

Se han añadido dos nuevas funciones, wait3() y wait4(). Son similares a la función waitpid() que espera la salida de un proceso hijo y devuelve una tupla con el ID del proceso y su estado de salida, pero wait3() y wait4() devuelven información adicional. wait3() no toma un ID de proceso como entrada, por lo que espera a que cualquier proceso hijo salga y devuelve una tupla de id de proceso, estado de salida, uso de recursos tal y como se devuelve desde la función resource.getrusage(). wait4(pid) toma un ID de proceso. (Contribuido por Chad J. Schroeder.)

En FreeBSD, la función os.stat() devuelve ahora tiempos con resolución de nanosegundos, y el objeto devuelto tiene ahora st_gen y st_birthtime. El atributo st_flags también está disponible, si la plataforma lo soporta. (Contribución de Antti Louko y Diego Pettenò)

El depurador de Python proporcionado por el módulo pdb puede ahora almacenar listas de comandos a ejecutar cuando se alcanza un punto de ruptura y se detiene la ejecución. Una vez creado el punto de interrupción nº 1, introduzca comandos 1 e introduzca una serie de comandos a ejecutar, terminando la lista con end. La lista de comandos puede incluir comandos que reanuden la ejecución, como continue o next. (Contribución de Grégoire Dooms.)

Los módulos pickle y cPickle ya no aceptan un valor de retorno de None del método __reduce__(); el método debe devolver una tupla de argumentos. La capacidad de devolver None fue obsoleta en Python 2.4, así que esto completa la eliminación de la función.

El módulo pkgutil, que contiene varias funciones de utilidad para encontrar paquetes, fue mejorado para soportar los ganchos de importación de PEP 302 [https://www.python.org/dev/peps/pep-0302] y ahora también funciona para paquetes almacenados en archivos con formato ZIP. (Contribución de Phillip J. Eby)

El conjunto de pruebas pybench de Marc-André Lemburg se incluye ahora en el directorio Tools/pybench. El conjunto de pruebas pybench es una mejora del programa pystone.py de uso común, ya que pybench proporciona una medición más detallada de la velocidad del intérprete. Calcula el tiempo de determinadas operaciones como las llamadas a funciones, el corte de tuplas, las búsquedas de métodos y las operaciones numéricas, en lugar de realizar muchas operaciones diferentes y reducir el resultado a un único número como hace pystone.py.

El módulo pyexpat utiliza ahora la versión 2.0 del analizador sintáctico Expat. (Contribución de Trent Mick)

La clase Queue proporcionada por el módulo Queue ha ganado dos nuevos métodos. join() bloquea hasta que todos los elementos de la cola han sido recuperados y todo el trabajo de procesamiento de los elementos ha sido completado. Los hilos de trabajo llaman al otro método nuevo, task_done(), para indicar que el procesamiento de un elemento ha finalizado. (Contribución de Raymond Hettinger)

Los antiguos módulos regex y regsub, obsoletos desde Python 2.0, han sido finalmente eliminados. Otros módulos eliminados: statcache, tzparse, whrandom.

También se ha eliminado el directorio lib-old, que incluye módulos antiguos como dircmp y ni. lib-old no estaba en el directorio por defecto sys.path, así que a menos que tus programas añadan explícitamente el directorio a sys.path, esta eliminación no debería afectar a tu código.

El módulo rlcompleter ya no depende de la importación del módulo readline y, por lo tanto, ahora funciona en plataformas no Unix. (Parche de Robert Kiendl.)

Las clases SimpleXMLRPCServer y DocXMLRPCServer tienen ahora un atributo rpc_paths que restringe las operaciones XML-RPC a un conjunto limitado de rutas URL; por defecto sólo se permiten '/' y '/RPC2'. Establecer rpc_paths como None o una tupla vacía desactiva esta comprobación de rutas.

El módulo socket ahora soporta sockets AF_NETLINK en Linux, gracias a un parche de Philippe Biondi. Los sockets Netlink son un mecanismo específico de Linux para las comunicaciones entre un proceso en el espacio del usuario y el código del kernel; hay un artículo introductorio sobre ellos en https://www.linuxjournal.com/article/7356. En el código Python, las direcciones de netlink se representan como una tupla de 2 enteros, (pid, group_mask).

Dos nuevos métodos en objetos socket, recv_into(buffer) y recvrom_into(buffer), almacenan los datos recibidos en un objeto que soporta el protocolo de buffer en lugar de devolver los datos como una cadena. Esto significa que puedes poner los datos directamente en un array o en un archivo mapeado en memoria.

Los objetos Socket también han ganado métodos de acceso getfamily(), gettype() y getproto() para recuperar los valores de familia, tipo y protocolo del socket.

Nuevo módulo: el módulo spwd proporciona funciones para acceder a la base de datos de contraseñas en la sombra en sistemas que soportan contraseñas en la sombra.

El módulo struct es ahora más rápido porque compila cadenas de formato en objetos Struct con métodos pack() y unpack(). Esto es similar a cómo el módulo re permite crear objetos de expresión regular compilados. Puede seguir utilizando las funciones pack() y unpack() a nivel de módulo; éstas crearán objetos Struct y los almacenarán en caché. O puede utilizar directamente las instancias de Struct:

s = struct.Struct('ih3s')

data = s.pack(1972, 187, 'abc')
year, number, name = s.unpack(data)

También puedes empaquetar y desempaquetar datos hacia y desde objetos buffer directamente usando los métodos pack_into(buffer, offset, v1, v2, ...) y unpack_from(buffer, offset). Esto te permite almacenar datos directamente en un array o en un archivo mapeado en memoria.

(Struct objects fueron implementados por Bob Ippolito en el sprint NeedForSpeed. El soporte para los objetos buffer fue añadido por Martin Blais, también en el sprint NeedForSpeed)

Los desarrolladores de Python cambiaron de CVS a Subversion durante el proceso de desarrollo de la versión 2.5. La información sobre la versión exacta de construcción está disponible como la variable sys.subversion, una 3-tupla de (nombre del intérprete, nombre de la rama, rango de revisión). Por ejemplo, en el momento de escribir esto, mi copia de 2.5 informaba de ('CPython', 'trunk', '45313:45315').

Esta información también está disponible para las extensiones de C a través de la función Py_GetBuildInfo() que devuelve una cadena de información de compilación como esta "trunk:45355:45356M, Apr 13 2006, 07:42:19". (Contribuido por Barry Warsaw.)

Otra nueva función, sys._current_frames(), devuelve los marcos de pila actuales para todos los hilos en ejecución como un diccionario que asigna los identificadores de los hilos al marco de pila superior actualmente activo en ese hilo en el momento en que se llama a la función. (Contribuido por Tim Peters.)

La clase TarFile del módulo tarfile tiene ahora un método extractall() que extrae todos los miembros del archivo en el directorio de trabajo actual. También es posible establecer un directorio diferente como destino de la extracción, y desempaquetar sólo un subconjunto de los miembros del archivo.

La compresión utilizada para un archivo tar abierto en modo stream puede ahora ser autodetectada utilizando el modo 'r|*'. (Contribución de Lars Gustäbel)

El módulo threading permite ahora establecer el tamaño de la pila utilizado cuando se crean nuevos hilos. La función stack_size([*size*]) devuelve el tamaño de pila actualmente configurado, y suministrando el parámetro opcional size establece un nuevo valor. No todas las plataformas soportan el cambio del tamaño de la pila, pero Windows, POSIX threading y OS/2 lo hacen. (Contribución de Andrew MacIntyre)

El módulo unicodedata ha sido actualizado para utilizar la versión 4.1.0 de la base de datos de caracteres Unicode. La versión 3.2.0 es requerida por algunas especificaciones, por lo que sigue estando disponible como unicodedata.ucd_3_2_0.

Nuevo módulo: el módulo uuid genera identificadores únicos universales (UUID) de acuerdo con RFC 4122 [https://tools.ietf.org/html/rfc4122.html]. El RFC define varias versiones diferentes de UUID que se generan a partir de una cadena inicial, de propiedades del sistema o de forma puramente aleatoria. Este módulo contiene una clase UUID y funciones llamadas uuid1(), uuid3(), uuid4(), y uuid5() para generar diferentes versiones de UUID. (Los UUID de la versión 2 no se especifican en RFC 4122 [https://tools.ietf.org/html/rfc4122.html] y no están soportados por este módulo)

>>> import uuid
>>> # make a UUID based on the host ID and current time
>>> uuid.uuid1()
UUID('a8098c1a-f86e-11da-bd1a-00112444be1e')

>>> # make a UUID using an MD5 hash of a namespace UUID and a name
>>> uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org')
UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e')

>>> # make a random UUID
>>> uuid.uuid4()
UUID('16fd2706-8baf-433b-82eb-8c7fada847da')

>>> # make a UUID using a SHA-1 hash of a namespace UUID and a name
>>> uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org')
UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d')

(Contribución de Ka-Ping Yee.)

Los tipos weakref del módulo WeakKeyDictionary y WeakValueDictionary han obtenido nuevos métodos para iterar sobre las referencias débiles contenidas en el diccionario. Se han añadido los métodos iterkeyrefs() y keyrefs() a WeakKeyDictionary, y itervaluerefs() y valuerefs() a WeakValueDictionary. (Contribución de Fred L. Drake, Jr.)

El módulo webbrowser ha recibido una serie de mejoras. Ahora se puede utilizar como un script con python -m webbrowser, tomando una URL como argumento; hay una serie de interruptores para controlar el comportamiento (-n para una nueva ventana del navegador, -t para una nueva pestaña). Se han añadido nuevas funciones a nivel de módulo, open_new() y open_new_tab(), para soportar esto. La función open() del módulo soporta una característica adicional, un parámetro autoraise que señala si se debe levantar la ventana abierta cuando sea posible. Se añadieron varios navegadores adicionales a la lista de soportados, como Firefox, Opera, Konqueror y elinks. (Contribución de Oleg Broytmann y Georg Brandl)

El módulo xmlrpclib ahora soporta la devolución de objetos datetime para el tipo de fecha XML-RPC. Proporcione use_datetime=True a la función loads() o a la clase Unmarshaller para activar esta característica. (Contribución de Skip Montanaro)

El módulo zipfile ahora soporta la versión ZIP64 del formato, lo que significa que un archivo .zip ahora puede ser mayor de 4 GiB y puede contener archivos individuales mayores de 4 GiB. (Contribución de Ronald Oussoren)

Los objetos zlib y Decompress del módulo zlib soportan ahora un método copy() que realiza una copia del estado interno del objeto y devuelve un nuevo objeto Compress o Decompress. (Contribución de Chris AtLee)

El paquete ctypes

El paquete ctypes, escrito por Thomas Heller, se ha añadido a la biblioteca estándar. ctypes permite llamar a funciones arbitrarias en bibliotecas compartidas o DLL. Los usuarios veteranos recordarán el módulo dl, que proporciona funciones para cargar bibliotecas compartidas y llamar a las funciones que contienen. El paquete ctypes es mucho más sofisticado.

Para cargar una biblioteca compartida o DLL, debes crear una instancia de la clase CDLL y proporcionar el nombre o la ruta de la biblioteca compartida o DLL. Una vez hecho esto, puedes llamar a funciones arbitrarias accediendo a ellas como atributos del objeto CDLL.

import ctypes

libc = ctypes.CDLL('libc.so.6')
result = libc.printf("Line of output\n")

Se proporcionan constructores de tipos para los distintos tipos de C: c_int(), c_float(), c_double(), c_char_p() (equivalente a char *), etc. A diferencia de los tipos de Python, las versiones de C son todas mutables; puedes asignar a su atributo value para cambiar el valor envuelto. Los enteros y las cadenas de Python se convertirán automáticamente a los tipos C correspondientes, pero para otros tipos debes llamar al constructor de tipo correcto. (Y quiero decir debe; si se equivoca, a menudo el intérprete se bloquea con un fallo de segmentación)

No debería usar c_char_p() con una cadena de Python cuando la función C vaya a modificar el área de memoria, porque se supone que las cadenas de Python son inmutables; romper esta regla causará errores desconcertantes. Cuando necesite un área de memoria modificable, utilice create_string_buffer():

s = "this is a string"
buf = ctypes.create_string_buffer(s)
libc.strfry(buf)

Se supone que las funciones en C devuelven números enteros, pero se puede establecer el atributo restype del objeto de la función para cambiar esto:

>>> libc.atof('2.71828')
-1783957616
>>> libc.atof.restype = ctypes.c_double
>>> libc.atof('2.71828')
2.71828

ctypes también proporciona una envoltura para la API de C de Python como el objeto ctypes.pythonapi. Este objeto no libera el bloqueo global del intérprete antes de llamar a una función, porque el bloqueo debe mantenerse cuando se llama al código del intérprete. Hay un constructor de tipo py_object() que creará un puntero PyObject *. Un uso sencillo:

import ctypes

d = {}
ctypes.pythonapi.PyObject_SetItem(ctypes.py_object(d),
          ctypes.py_object("abc"),  ctypes.py_object(1))
# d is now {'abc', 1}.

No olvides usar py_object(); si se omite acabas con un fallo de segmentación.

ctypes existe desde hace tiempo, pero la gente sigue escribiendo y distribuyendo módulos de extensión codificados a mano porque no se puede confiar en que ctypes esté presente. Quizás los desarrolladores empiecen a escribir envoltorios de Python sobre una biblioteca a la que se accede a través de ctypes en lugar de módulos de extensión, ahora que ctypes está incluido en el núcleo de Python.

Ver también

http://starship.python.net/crew/theller/ctypes/

La página web de ctypes, con un tutorial, referencias y preguntas frecuentes.

La documentación del módulo ctypes.

El paquete ElementTree

Un subconjunto de la biblioteca ElementTree de Fredrik Lundh para el procesamiento de XML se ha añadido a la biblioteca estándar como xml.etree. Los módulos disponibles son ElementTree, ElementPath y ElementInclude de ElementTree 1.2.6. También se incluye el módulo acelerador cElementTree.

The rest of this section will provide a brief overview of using ElementTree. Full documentation for ElementTree is available at https://web.archive.org/web/20201124024954/http://effbot.org/zone/element-index.htm.

ElementTree representa un documento XML como un árbol de nodos de elementos. El contenido de texto del documento se almacena como los atributos text y tail de (Esta es una de las principales diferencias entre ElementTree y el Modelo de Objetos del Documento; en el DOM hay muchos tipos diferentes de nodo, incluyendo TextNode)

La función de análisis más utilizada es parse(), que toma una cadena (se supone que contiene un nombre de archivo) o un objeto similar a un archivo y devuelve una instancia de ElementTree:

from xml.etree import ElementTree as ET

tree = ET.parse('ex-1.xml')

feed = urllib.urlopen(
          'http://planet.python.org/rss10.xml')
tree = ET.parse(feed)

Una vez que tengas una instancia de ElementTree, puedes llamar a su método getroot() para obtener el nodo raíz de Element.

También hay una función XML() que toma un literal de cadena y devuelve un nodo Element (no un ElementTree). Esta función proporciona una forma ordenada de incorporar fragmentos XML, acercándose a la comodidad de un literal XML:

svg = ET.XML("""<svg width="10px" version="1.0">
             </svg>""")
svg.set('height', '320px')
svg.append(elem1)

Cada elemento XML admite algunos métodos de acceso tipo diccionario y otros tipo lista. Las operaciones tipo diccionario se utilizan para acceder a los valores de los atributos, y las operaciones tipo lista se utilizan para acceder a los nodos hijos.

Operación

Resultado

elem[n]

Devuelve el elemento hijo enésimo.

elem[m:n]

Devuelve la lista de m’s a n’s elementos hijos.

len(elem)

Devuelve el número de elementos hijos.

lista(elem)

Devuelve la lista de elementos hijos.

elem.append(elem2)

Añade elemento2 como hijo.

elem.insert(index, elem2)

Inserta elemento2 en el lugar especificado.

del elem[n]

Elimina el elemento hijo enésimo.

elem.keys()

Devuelve la lista de nombres de atributos.

elem.get(name)

Devuelve el valor del atributo nombre.

elem.set(nombre, valor)

Establece el nuevo valor del atributo nombre.

elem.attrib

Recupera el diccionario que contiene los atributos.

del elem.attrib[name]

Borra el atributo nombre.

Los comentarios y las instrucciones de procesamiento también se representan como nodos Element. Para comprobar si un nodo es un comentario o unas instrucciones de procesamiento:

if elem.tag is ET.Comment:
    ...
elif elem.tag is ET.ProcessingInstruction:
    ...

Para generar una salida XML, debes llamar al método ElementTree.write(). Al igual que parse(), puede tomar una cadena o un objeto tipo archivo:

# Encoding is US-ASCII
tree.write('output.xml')

# Encoding is UTF-8
f = open('output.xml', 'w')
tree.write(f, encoding='utf-8')

(Atención: la codificación por defecto utilizada para la salida es ASCII. Para el trabajo general de XML, donde el nombre de un elemento puede contener caracteres Unicode arbitrarios, ASCII no es una codificación muy útil porque lanzará una excepción si el nombre de un elemento contiene cualquier carácter con valores superiores a 127. Por lo tanto, es mejor especificar una codificación diferente, como UTF-8, que puede manejar cualquier carácter Unicode)

Esta sección es sólo una descripción parcial de las interfaces de ElementTree. Por favor, lee la documentación oficial del paquete para más detalles.

Ver también

https://web.archive.org/web/20201124024954/http://effbot.org/zone/element-index.htm

Documentación oficial de ElementTree.

El paquete hashlib

Se ha añadido un nuevo módulo hashlib, escrito por Gregory P. Smith, para sustituir a los módulos md5 y sha. hashlib añade soporte para hashes seguros adicionales (SHA-224, SHA-256, SHA-384 y SHA-512). Cuando está disponible, el módulo utiliza OpenSSL para implementaciones rápidas de algoritmos optimizados para la plataforma.

Los antiguos módulos md5 y sha siguen existiendo como envoltorios de hashlib para preservar la compatibilidad hacia atrás. La interfaz del nuevo módulo es muy parecida a la de los módulos antiguos, pero no es idéntica. La diferencia más significativa es que las funciones constructoras para crear nuevos objetos hashing tienen un nombre diferente

# Old versions
h = md5.md5()
h = md5.new()

# New version
h = hashlib.md5()

# Old versions
h = sha.sha()
h = sha.new()

# New version
h = hashlib.sha1()

# Hash that weren't previously available
h = hashlib.sha224()
h = hashlib.sha256()
h = hashlib.sha384()
h = hashlib.sha512()

# Alternative form
h = hashlib.new('md5')          # Provide algorithm as a string

Una vez que se ha creado un objeto hash, sus métodos son los mismos que antes: actualizar(cadena) convierte la cadena especificada en el estado de resumen actual, digest() y hexdigest() devuelven el valor de resumen como una cadena binaria o una cadena de dígitos hexadecimales, y copiar() devuelve un nuevo objeto hash con el mismo estado de resumen.

Ver también

La documentación del módulo hashlib.

El paquete sqlite3

El módulo pysqlite (http://www.pysqlite.org), una envoltura para la base de datos incrustada SQLite, se ha añadido a la biblioteca estándar bajo el nombre de paquete sqlite3.

SQLite es una biblioteca en C que proporciona una base de datos ligera basada en disco que no requiere un proceso de servidor independiente y permite acceder a la base de datos utilizando una variante no estándar del lenguaje de consulta SQL. Algunas aplicaciones pueden utilizar SQLite para el almacenamiento interno de datos. También es posible crear un prototipo de una aplicación utilizando SQLite y luego portar el código a una base de datos más grande como PostgreSQL u Oracle.

pysqlite fue escrito por Gerhard Häring y proporciona una interfaz SQL que cumple con la especificación DB-API 2.0 descrita por PEP 249 [https://www.python.org/dev/peps/pep-0249].

Si estás compilando el código fuente de Python tú mismo, ten en cuenta que el árbol de código fuente no incluye el código de SQLite, sólo el módulo envolvente. Necesitarás tener las librerías y cabeceras de SQLite instaladas antes de compilar Python, y el proceso de construcción compilará el módulo cuando las cabeceras necesarias estén disponibles.

Para utilizar el módulo, primero hay que crear un objeto Connection que represente la base de datos. Aquí los datos se almacenarán en el archivo /tmp/example:

conn = sqlite3.connect('/tmp/example')

También puede suministrar el nombre especial :memory: para crear una base de datos en la RAM.

Una vez que tengas una Connection, puedes crear un objeto Cursor y llamar a su método execute() para realizar comandos SQL:

c = conn.cursor()

# Create table
c.execute('''create table stocks
(date text, trans text, symbol text,
 qty real, price real)''')

# Insert a row of data
c.execute("""insert into stocks
          values ('2006-01-05','BUY','RHAT',100,35.14)""")

Normalmente tus operaciones SQL necesitarán usar valores de variables de Python. No deberías montar tu consulta usando las operaciones de cadena de Python porque hacerlo es inseguro; hace que tu programa sea vulnerable a un ataque de inyección SQL.

En su lugar, utilice la sustitución de parámetros de la DB-API. Ponga ? como marcador de posición donde quiera usar un valor, y luego proporcione una tupla de valores como segundo argumento al método execute() del cursor. (Otros módulos de base de datos pueden utilizar un marcador de posición diferente, como %s o :1) Por ejemplo:

# Never do this -- insecure!
symbol = 'IBM'
c.execute("... where symbol = '%s'" % symbol)

# Do this instead
t = (symbol,)
c.execute('select * from stocks where symbol=?', t)

# Larger example
for t in (('2006-03-28', 'BUY', 'IBM', 1000, 45.00),
          ('2006-04-05', 'BUY', 'MSOFT', 1000, 72.00),
          ('2006-04-06', 'SELL', 'IBM', 500, 53.00),
         ):
    c.execute('insert into stocks values (?,?,?,?,?)', t)

Para recuperar datos después de ejecutar una sentencia SELECT, puede tratar el cursor como un iterador, llamar al método fetchone() del cursor para recuperar una sola fila que coincida, o llamar a fetchall() para obtener una lista de las filas que coincidan.

Este ejemplo utiliza la forma del iterador:

>>> c = conn.cursor()
>>> c.execute('select * from stocks order by price')
>>> for row in c:
...    print row
...
(u'2006-01-05', u'BUY', u'RHAT', 100, 35.140000000000001)
(u'2006-03-28', u'BUY', u'IBM', 1000, 45.0)
(u'2006-04-06', u'SELL', u'IBM', 500, 53.0)
(u'2006-04-05', u'BUY', u'MSOFT', 1000, 72.0)
>>>

Para más información sobre el dialecto SQL soportado por SQLite, consulte https://www.sqlite.org.

Ver también

http://www.pysqlite.org

La página web de pysqlite.

https://www.sqlite.org

La página web de SQLite; la documentación describe la sintaxis y los tipos de datos disponibles para el dialecto SQL soportado.

La documentación del módulo sqlite3.

PEP 249 [https://www.python.org/dev/peps/pep-0249] - Especificación de la API de la base de datos 2.0

PEP escrito por Marc-André Lemburg.

El paquete wsgiref

La Interfaz de Pasarela del Servidor Web (WSGI) v1.0 define una interfaz estándar entre los servidores web y las aplicaciones web de Python y se describe en PEP 333 [https://www.python.org/dev/peps/pep-0333]. El paquete wsgiref es una implementación de referencia de la especificación WSGI.

El paquete incluye un servidor HTTP básico que ejecutará una aplicación WSGI; este servidor es útil para la depuración pero no está pensado para su uso en producción. La configuración de un servidor sólo requiere unas pocas líneas de código:

from wsgiref import simple_server

wsgi_app = ...

host = ''
port = 8000
httpd = simple_server.make_server(host, port, wsgi_app)
httpd.serve_forever()

Ver también

http://www.wsgi.org

Un sitio web central para los recursos relacionados con WSGI.

PEP 333 [https://www.python.org/dev/peps/pep-0333] - Interfaz del servidor web Python v1.0

PEP escrito por Phillip J. Eby.

Cambios en la API de construcción y C

Los cambios en el proceso de construcción de Python y en la API de C incluyen:

El árbol de fuentes de Python fue convertido de CVS a Subversion, en un complejo procedimiento de migración que fue supervisado y llevado a cabo de forma impecable por Martin von Löwis. El procedimiento se desarrolló como PEP 347 [https://www.python.org/dev/peps/pep-0347].

Coverity, una empresa que comercializa una herramienta de análisis de código fuente llamada Prevent, proporcionó los resultados de su examen del código fuente de Python. El análisis encontró alrededor de 60 errores que fueron rápidamente corregidos. Muchos de los errores eran problemas de recuento, que a menudo se producen en el código de gestión de errores. Consulte las estadísticas en https://scan.coverity.com.

El mayor cambio en la API de C proviene de PEP 353 [https://www.python.org/dev/peps/pep-0353], que modifica el intérprete para utilizar una definición de tipo Py_ssize_t en lugar de int. Vea la sección anterior PEP 353: Uso de ssize_t como tipo de índice para una discusión de este cambio.

El diseño del compilador de código de bytes ha cambiado mucho, ya no genera código de bytes recorriendo el árbol de análisis sintáctico. En su lugar, el árbol de análisis se convierte en un árbol de sintaxis abstracta (o AST), y es el árbol de sintaxis abstracta el que se recorre para producir el código de bytes.

Es posible que el código Python obtenga objetos AST utilizando el built-in compile() y especificando _ast.PyCF_ONLY_AST como valor del parámetro flags:

from _ast import PyCF_ONLY_AST
ast = compile("""a=0
for i in range(10):
    a += i
""", "<string>", 'exec', PyCF_ONLY_AST)

assignment = ast.body[0]
for_loop = ast.body[1]

Todavía no se ha escrito ninguna documentación oficial para el código AST, pero PEP 339 [https://www.python.org/dev/peps/pep-0339] discute el diseño. Para empezar a conocer el código, lea la definición de los distintos nodos AST en Parser/Python.asdl. Un script de Python lee este archivo y genera un conjunto de definiciones de estructuras C en Include/Python-ast.h. Las funciones PyParser_ASTFromString() y PyParser_ASTFromFile(), definidas en Include/pythonrun.h, toman el código fuente de Python como entrada y devuelven la raíz de un AST que representa el contenido. Este AST puede convertirse en un objeto de código mediante PyAST_Compile(). Para más información, lea el código fuente, y luego haga preguntas en python-dev.

El código de la AST fue desarrollado bajo la dirección de Jeremy Hylton, e implementado por (en orden alfabético) Brett Cannon, Nick Coghlan, Grant Edwards, John Ehresman, Kurt Kaiser, Neal Norwitz, Tim Peters, Armin Rigo y Neil Schemenauer, además de los participantes en varios sprints de la AST en conferencias como la PyCon.

Se aplicó el parche de Evan Jones a obmalloc, descrito por primera vez en una charla en la PyCon DC 2005. Python 2.4 asignaba objetos pequeños en arenas de 256K, pero nunca liberaba arenas. Con este parche, Python liberará arenas cuando estén vacías. El efecto neto es que en algunas plataformas, cuando se asignan muchos objetos, el uso de la memoria de Python puede realmente caer cuando se borran y la memoria puede ser devuelta al sistema operativo. (Implementado por Evan Jones, y reelaborado por Tim Peters)

Tenga en cuenta que este cambio significa que los módulos de extensión deben ser más cuidadosos al asignar memoria. La API de Python tiene muchas funciones diferentes para asignar memoria que se agrupan en familias. Por ejemplo, PyMem_Malloc(), PyMem_Realloc(), y PyMem_Free() son una familia que asigna memoria en bruto, mientras que PyObject_Malloc(), PyObject_Realloc(), y PyObject_Free() son otra familia que se supone que se utiliza para crear objetos de Python.

Anteriormente estas diferentes familias se reducían a las funciones malloc() y free() de la plataforma. Esto significaba que no importaba si te equivocabas y asignabas memoria con la función PyMem() pero la liberabas con la función PyObject(). Con los cambios de la versión 2.5 en obmalloc, estas familias hacen ahora cosas diferentes y los desajustes probablemente darán lugar a un fallo de seguridad. Deberías probar cuidadosamente tus módulos de extensión C con Python 2.5.

Los tipos de conjuntos incorporados tienen ahora una API oficial en C. Llame a PySet_New() y PyFrozenSet_New() para crear un nuevo conjunto, PySet_Add() y PySet_Discard() para añadir y eliminar elementos, y PySet_Contains() y PySet_Size() para examinar el estado del conjunto. (Contribución de Raymond Hettinger)

El código C puede ahora obtener información sobre la revisión exacta del intérprete de Python llamando a la función Py_GetBuildInfo() que devuelve una cadena de información de compilación como esta "trunk:45355:45356M, Apr 13 2006, 07:42:19". (Contribuido por Barry Warsaw.)

Se pueden utilizar dos nuevas macros para indicar las funciones C que son locales al fichero actual, de modo que se pueda utilizar una convención de llamada más rápida. Py_LOCAL(type) declara que la función devuelve un valor del tipo especificado y utiliza un calificador de llamada rápida. Py_LOCAL_INLINE(type) hace lo mismo y también solicita que la función sea inline. Si PY_LOCAL_AGGRESSIVE() se define antes de que se incluya python.h, se habilita un conjunto de optimizaciones más agresivas para el módulo; debería comparar los resultados para averiguar si estas optimizaciones realmente hacen el código más rápido. (Contribuido por Fredrik Lundh en el sprint NeedForSpeed)

PyErr_NewException(name, base, dict) ahora puede aceptar una tupla de clases base como su argumento base. (Contribuido por Georg Brandl.)

La función PyErr_Warn() para emitir avisos está ahora obsoleta en favor de PyErr_WarnEx(category, message, stacklevel) que permite especificar el número de marcos de pila que separan esta función y la que la llama. Un stacklevel de 1 es la función que llama a PyErr_WarnEx(), 2 es la función que está por encima, y así sucesivamente. (Añadido por Neal Norwitz.)

El intérprete de CPython sigue estando escrito en C, pero el código ahora puede ser compilado con un compilador de C++ sin errores. (Implementado por Anthony Baxter, Martin von Löwis, Skip Montanaro)

Se ha eliminado la función PyRange_New(). Nunca se documentó, nunca se utilizó en el código del núcleo, y tenía una comprobación de errores peligrosamente laxa. En el improbable caso de que sus extensiones la utilizaran, puede sustituirla por algo como lo siguiente:

range = PyObject_CallFunction((PyObject*) &PyRange_Type, "lll",
                              start, stop, step);

Cambios específicos en los puertos

MacOS X (10.3 y superior): la carga dinámica de módulos utiliza ahora la función dlopen() en lugar de funciones específicas de MacOS.

MacOS X: se ha añadido una opción --enable-universalsdk al script configure que compila el intérprete como un binario universal capaz de funcionar tanto en procesadores PowerPC como Intel. (Contribución de Ronald Oussoren; bpo-2573 [https://bugs.python.org/issue?@action=redirect&bpo=2573].)

Windows: .dll ya no se admite como extensión de nombre de archivo para los módulos de extensión. .pyd es ahora la única extensión de nombre de archivo que se buscará.

Adaptación a Python 2.5

Esta sección enumera los cambios descritos anteriormente que pueden requerir cambios en su código:

ASCII es ahora la codificación por defecto para los módulos. Ahora es un error de sintaxis si un módulo contiene literales de cadena con caracteres de 8 bits pero no tiene una declaración de codificación. En Python 2.4 esto provocaba una advertencia, no un error de sintaxis.

Anteriormente, el atributo gi_frame de un generador era siempre un objeto frame. Debido a los cambios de PEP 342 [https://www.python.org/dev/peps/pep-0342] descritos en la sección PEP 342: Nuevas funciones del generador, ahora es posible que gi_frame sea None.

Una nueva advertencia, UnicodeWarning, se lanza cuando se intenta comparar una cadena Unicode y una cadena de 8 bits que no puede ser convertida a Unicode utilizando la codificación ASCII por defecto. Anteriormente estas comparaciones lanzaban una excepción UnicodeDecodeError.

Biblioteca: el módulo csv es ahora más estricto con los campos citados en varias líneas. Si sus archivos contienen nuevas líneas incrustadas dentro de los campos, la entrada debe dividirse en líneas de manera que se conserven los caracteres de nueva línea.

Biblioteca: la función format() del módulo locale aceptaba antes cualquier cadena siempre que no apareciera más de un especificador %char. En Python 2.5, el argumento debe ser exactamente un especificador %char sin texto alrededor.

Biblioteca: Los módulos pickle y cPickle ya no aceptan un valor de retorno de None del método __reduce__(); el método debe devolver una tupla de argumentos. Los módulos tampoco aceptan ya el parámetro obsoleto de la palabra clave bin.

Biblioteca: Las clases SimpleXMLRPCServer y DocXMLRPCServer tienen ahora un atributo rpc_paths que restringe las operaciones XML-RPC a un conjunto limitado de rutas URL; por defecto sólo se permiten '/' y '/RPC2'. Establecer rpc_paths como None o una tupla vacía desactiva esta comprobación de rutas.

API C: Muchas funciones utilizan ahora Py_ssize_t en lugar de int para permitir el procesamiento de más datos en máquinas de 64 bits. Es posible que el código de las extensiones tenga que hacer el mismo cambio para evitar advertencias y soportar máquinas de 64 bits. Véase la sección anterior PEP 353: Uso de ssize_t como tipo de índice para una discusión de este cambio.

C API: Los cambios en obmalloc significan que debe tener cuidado de no mezclar el uso de las familias de funciones PyMem_*() y PyObject_*(). La memoria asignada con la función *_Malloc() de una familia debe ser liberada con la función *_Free() de la familia correspondiente.

Agradecimientos

El autor desea agradecer a las siguientes personas sus sugerencias, correcciones y ayuda en varios borradores de este artículo: Georg Brandl, Nick Coghlan, Phillip J. Eby, Lars Gustäbel, Raymond Hettinger, Ralf W. Grosse-Kunstleve, Kent Johnson, Iain Lowe, Martin von Löwis, Fredrik Lundh, Andrew McNamara, Skip Montanaro, Gustavo Niemeyer, Paul Prescod, James Pryor, Mike Rovner, Scott Weikart, Barry Warsaw, Thomas Wouters.

What’s New in Python 2.4

Author

A.M. Kuchling

This article explains the new features in Python 2.4.1, released on March 30, 2005.

Python 2.4 is a medium-sized release. It doesn’t introduce as many changes as the radical Python 2.2, but introduces more features than the conservative 2.3 release. The most significant new language features are function decorators and generator expressions; most other changes are to the standard library.

According to the CVS change logs, there were 481 patches applied and 502 bugs fixed between Python 2.3 and 2.4. Both figures are likely to be underestimates.

This article doesn’t attempt to provide a complete specification of every single new feature, but instead provides a brief introduction to each feature. For full details, you should refer to the documentation for Python 2.4, such as the Python Library Reference and the Python Reference Manual. Often you will be referred to the PEP for a particular new feature for explanations of the implementation and design rationale.

PEP 218: Built-In Set Objects

Python 2.3 introduced the sets module. C implementations of set data types have now been added to the Python core as two new built-in types, set(iterable) and frozenset(iterable). They provide high speed operations for membership testing, for eliminating duplicates from sequences, and for mathematical operations like unions, intersections, differences, and symmetric differences.

>>> a = set('abracadabra')              # form a set from a string
>>> 'z' in a                            # fast membership testing
False
>>> a                                   # unique letters in a
set(['a', 'r', 'b', 'c', 'd'])
>>> ''.join(a)                          # convert back into a string
'arbcd'

>>> b = set('alacazam')                 # form a second set
>>> a - b                               # letters in a but not in b
set(['r', 'd', 'b'])
>>> a | b                               # letters in either a or b
set(['a', 'c', 'r', 'd', 'b', 'm', 'z', 'l'])
>>> a & b                               # letters in both a and b
set(['a', 'c'])
>>> a ^ b                               # letters in a or b but not both
set(['r', 'd', 'b', 'm', 'z', 'l'])

>>> a.add('z')                          # add a new element
>>> a.update('wxy')                     # add multiple new elements
>>> a
set(['a', 'c', 'b', 'd', 'r', 'w', 'y', 'x', 'z'])
>>> a.remove('x')                       # take one element out
>>> a
set(['a', 'c', 'b', 'd', 'r', 'w', 'y', 'z'])

The frozenset() type is an immutable version of set(). Since it is immutable and hashable, it may be used as a dictionary key or as a member of another set.

The sets module remains in the standard library, and may be useful if you wish to subclass the Set or ImmutableSet classes. There are currently no plans to deprecate the module.

Ver también

PEP 218 [https://www.python.org/dev/peps/pep-0218] - Adding a Built-In Set Object Type

Originally proposed by Greg Wilson and ultimately implemented by Raymond Hettinger.

PEP 237: Unifying Long Integers and Integers

The lengthy transition process for this PEP, begun in Python 2.2, takes another step forward in Python 2.4. In 2.3, certain integer operations that would behave differently after int/long unification triggered FutureWarning warnings and returned values limited to 32 or 64 bits (depending on your platform). In 2.4, these expressions no longer produce a warning and instead produce a different result that’s usually a long integer.

The problematic expressions are primarily left shifts and lengthy hexadecimal and octal constants. For example, 2 << 32 results in a warning in 2.3, evaluating to 0 on 32-bit platforms. In Python 2.4, this expression now returns the correct answer, 8589934592.

Ver también

PEP 237 [https://www.python.org/dev/peps/pep-0237] - Unifying Long Integers and Integers

Original PEP written by Moshe Zadka and GvR. The changes for 2.4 were implemented by Kalle Svensson.

PEP 289: Generator Expressions

The iterator feature introduced in Python 2.2 and the itertools module make it easier to write programs that loop through large data sets without having the entire data set in memory at one time. List comprehensions don’t fit into this picture very well because they produce a Python list object containing all of the items. This unavoidably pulls all of the objects into memory, which can be a problem if your data set is very large. When trying to write a functionally-styled program, it would be natural to write something like:

links = [link for link in get_all_links() if not link.followed]
for link in links:
    ...

instead of

for link in get_all_links():
    if link.followed:
        continue
    ...

The first form is more concise and perhaps more readable, but if you’re dealing with a large number of link objects you’d have to write the second form to avoid having all link objects in memory at the same time.

Generator expressions work similarly to list comprehensions but don’t materialize the entire list; instead they create a generator that will return elements one by one. The above example could be written as:

links = (link for link in get_all_links() if not link.followed)
for link in links:
    ...

Generator expressions always have to be written inside parentheses, as in the above example. The parentheses signalling a function call also count, so if you want to create an iterator that will be immediately passed to a function you could write:

print sum(obj.count for obj in list_all_objects())

Generator expressions differ from list comprehensions in various small ways. Most notably, the loop variable (obj in the above example) is not accessible outside of the generator expression. List comprehensions leave the variable assigned to its last value; future versions of Python will change this, making list comprehensions match generator expressions in this respect.

Ver también

PEP 289 [https://www.python.org/dev/peps/pep-0289] - Generator Expressions

Proposed by Raymond Hettinger and implemented by Jiwon Seo with early efforts steered by Hye-Shik Chang.

PEP 292: Simpler String Substitutions

Some new classes in the standard library provide an alternative mechanism for substituting variables into strings; this style of substitution may be better for applications where untrained users need to edit templates.

The usual way of substituting variables by name is the % operator:

>>> '%(page)i: %(title)s' % {'page':2, 'title': 'The Best of Times'}
'2: The Best of Times'

When writing the template string, it can be easy to forget the i or s after the closing parenthesis. This isn’t a big problem if the template is in a Python module, because you run the code, get an «Unsupported format character» ValueError, and fix the problem. However, consider an application such as Mailman where template strings or translations are being edited by users who aren’t aware of the Python language. The format string’s syntax is complicated to explain to such users, and if they make a mistake, it’s difficult to provide helpful feedback to them.

PEP 292 adds a Template class to the string module that uses $ to indicate a substitution:

>>> import string
>>> t = string.Template('$page: $title')
>>> t.substitute({'page':2, 'title': 'The Best of Times'})
'2: The Best of Times'

If a key is missing from the dictionary, the substitute() method will raise a KeyError. There’s also a safe_substitute() method that ignores missing keys:

>>> t = string.Template('$page: $title')
>>> t.safe_substitute({'page':3})
'3: $title'

Ver también

PEP 292 [https://www.python.org/dev/peps/pep-0292] - Simpler String Substitutions

Written and implemented by Barry Warsaw.

PEP 318: Decorators for Functions and Methods

Python 2.2 extended Python’s object model by adding static methods and class methods, but it didn’t extend Python’s syntax to provide any new way of defining static or class methods. Instead, you had to write a def statement in the usual way, and pass the resulting method to a staticmethod() or classmethod() function that would wrap up the function as a method of the new type. Your code would look like this:

class C:
   def meth (cls):
       ...

   meth = classmethod(meth)   # Rebind name to wrapped-up class method

If the method was very long, it would be easy to miss or forget the classmethod() invocation after the function body.

The intention was always to add some syntax to make such definitions more readable, but at the time of 2.2’s release a good syntax was not obvious. Today a good syntax still isn’t obvious but users are asking for easier access to the feature; a new syntactic feature has been added to meet this need.

The new feature is called «function decorators». The name comes from the idea that classmethod(), staticmethod(), and friends are storing additional information on a function object; they’re decorating functions with more details.

The notation borrows from Java and uses the '@' character as an indicator. Using the new syntax, the example above would be written:

class C:

   @classmethod
   def meth (cls):
       ...

The @classmethod is shorthand for the meth=classmethod(meth) assignment. More generally, if you have the following:

@A
@B
@C
def f ():
    ...

It’s equivalent to the following pre-decorator code:

def f(): ...
f = A(B(C(f)))

Decorators must come on the line before a function definition, one decorator per line, and can’t be on the same line as the def statement, meaning that @A def f(): ... is illegal. You can only decorate function definitions, either at the module level or inside a class; you can’t decorate class definitions.

A decorator is just a function that takes the function to be decorated as an argument and returns either the same function or some new object. The return value of the decorator need not be callable (though it typically is), unless further decorators will be applied to the result. It’s easy to write your own decorators. The following simple example just sets an attribute on the function object:

>>> def deco(func):
...    func.attr = 'decorated'
...    return func
...
>>> @deco
... def f(): pass
...
>>> f
<function f at 0x402ef0d4>
>>> f.attr
'decorated'
>>>

As a slightly more realistic example, the following decorator checks that the supplied argument is an integer:

def require_int (func):
    def wrapper (arg):
        assert isinstance(arg, int)
        return func(arg)

    return wrapper

@require_int
def p1 (arg):
    print arg

@require_int
def p2(arg):
    print arg*2

An example in PEP 318 [https://www.python.org/dev/peps/pep-0318] contains a fancier version of this idea that lets you both specify the required type and check the returned type.

Decorator functions can take arguments. If arguments are supplied, your decorator function is called with only those arguments and must return a new decorator function; this function must take a single function and return a function, as previously described. In other words, @A @B @C(args) becomes:

def f(): ...
_deco = C(args)
f = A(B(_deco(f)))

Getting this right can be slightly brain-bending, but it’s not too difficult.

A small related change makes the func_name attribute of functions writable. This attribute is used to display function names in tracebacks, so decorators should change the name of any new function that’s constructed and returned.

Ver también

PEP 318 [https://www.python.org/dev/peps/pep-0318] - Decorators for Functions, Methods and Classes

Written by Kevin D. Smith, Jim Jewett, and Skip Montanaro. Several people wrote patches implementing function decorators, but the one that was actually checked in was patch #979728, written by Mark Russell.

https://wiki.python.org/moin/PythonDecoratorLibrary

This Wiki page contains several examples of decorators.

PEP 322: Reverse Iteration

A new built-in function, reversed(seq), takes a sequence and returns an iterator that loops over the elements of the sequence in reverse order.

>>> for i in reversed(xrange(1,4)):
...    print i
...
3
2
1

Compared to extended slicing, such as range(1,4)[::-1], reversed() is easier to read, runs faster, and uses substantially less memory.

Note that reversed() only accepts sequences, not arbitrary iterators. If you want to reverse an iterator, first convert it to a list with list().

>>> input = open('/etc/passwd', 'r')
>>> for line in reversed(list(input)):
...   print line
...
root:*:0:0:System Administrator:/var/root:/bin/tcsh
  ...

Ver también

PEP 322 [https://www.python.org/dev/peps/pep-0322] - Reverse Iteration

Written and implemented by Raymond Hettinger.

PEP 324: New subprocess Module

The standard library provides a number of ways to execute a subprocess, offering different features and different levels of complexity. os.system(command) is easy to use, but slow (it runs a shell process which executes the command) and dangerous (you have to be careful about escaping the shell’s metacharacters). The popen2 module offers classes that can capture standard output and standard error from the subprocess, but the naming is confusing. The subprocess module cleans this up, providing a unified interface that offers all the features you might need.

Instead of popen2’s collection of classes, subprocess contains a single class called Popen whose constructor supports a number of different keyword arguments.

class Popen(args, bufsize=0, executable=None,
            stdin=None, stdout=None, stderr=None,
            preexec_fn=None, close_fds=False, shell=False,
            cwd=None, env=None, universal_newlines=False,
            startupinfo=None, creationflags=0):

args is commonly a sequence of strings that will be the arguments to the program executed as the subprocess. (If the shell argument is true, args can be a string which will then be passed on to the shell for interpretation, just as os.system() does.)

stdin, stdout, and stderr specify what the subprocess’s input, output, and error streams will be. You can provide a file object or a file descriptor, or you can use the constant subprocess.PIPE to create a pipe between the subprocess and the parent.

The constructor has a number of handy options:

close_fds requests that all file descriptors be closed before running the subprocess.

cwd specifies the working directory in which the subprocess will be executed (defaulting to whatever the parent’s working directory is).

env is a dictionary specifying environment variables.

preexec_fn is a function that gets called before the child is started.

universal_newlines opens the child’s input and output using Python’s universal newlines feature.

Once you’ve created the Popen instance, you can call its wait() method to pause until the subprocess has exited, poll() to check if it’s exited without pausing, or communicate(data) to send the string data to the subprocess’s standard input. communicate(data) then reads any data that the subprocess has sent to its standard output or standard error, returning a tuple (stdout_data, stderr_data).

call() is a shortcut that passes its arguments along to the Popen constructor, waits for the command to complete, and returns the status code of the subprocess. It can serve as a safer analog to os.system():

sts = subprocess.call(['dpkg', '-i', '/tmp/new-package.deb'])
if sts == 0:
    # Success
    ...
else:
    # dpkg returned an error
    ...

The command is invoked without use of the shell. If you really do want to use the shell, you can add shell=True as a keyword argument and provide a string instead of a sequence:

sts = subprocess.call('dpkg -i /tmp/new-package.deb', shell=True)

The PEP takes various examples of shell and Python code and shows how they’d be translated into Python code that uses subprocess. Reading this section of the PEP is highly recommended.

Ver también

PEP 324 [https://www.python.org/dev/peps/pep-0324] - subprocess - New process module

Written and implemented by Peter Åstrand, with assistance from Fredrik Lundh and others.

PEP 327: Decimal Data Type

Python has always supported floating-point (FP) numbers, based on the underlying C double type, as a data type. However, while most programming languages provide a floating-point type, many people (even programmers) are unaware that floating-point numbers don’t represent certain decimal fractions accurately. The new Decimal type can represent these fractions accurately, up to a user-specified precision limit.

Why is Decimal needed?

The limitations arise from the representation used for floating-point numbers. FP numbers are made up of three components:

The sign, which is positive or negative.

The mantissa, which is a single-digit binary number followed by a fractional part. For example, 1.01 in base-2 notation is 1 + 0/2 + 1/4, or 1.25 in decimal notation.

The exponent, which tells where the decimal point is located in the number represented.

For example, the number 1.25 has positive sign, a mantissa value of 1.01 (in binary), and an exponent of 0 (the decimal point doesn’t need to be shifted). The number 5 has the same sign and mantissa, but the exponent is 2 because the mantissa is multiplied by 4 (2 to the power of the exponent 2); 1.25 * 4 equals 5.

Modern systems usually provide floating-point support that conforms to a standard called IEEE 754. C’s double type is usually implemented as a 64-bit IEEE 754 number, which uses 52 bits of space for the mantissa. This means that numbers can only be specified to 52 bits of precision. If you’re trying to represent numbers whose expansion repeats endlessly, the expansion is cut off after 52 bits. Unfortunately, most software needs to produce output in base 10, and common fractions in base 10 are often repeating decimals in binary. For example, 1.1 decimal is binary 1.0001100110011 ...; .1 = 1/16 + 1/32 + 1/256 plus an infinite number of additional terms. IEEE 754 has to chop off that infinitely repeated decimal after 52 digits, so the representation is slightly inaccurate.

Sometimes you can see this inaccuracy when the number is printed:

>>> 1.1
1.1000000000000001

The inaccuracy isn’t always visible when you print the number because the FP-to-decimal-string conversion is provided by the C library, and most C libraries try to produce sensible output. Even if it’s not displayed, however, the inaccuracy is still there and subsequent operations can magnify the error.

For many applications this doesn’t matter. If I’m plotting points and displaying them on my monitor, the difference between 1.1 and 1.1000000000000001 is too small to be visible. Reports often limit output to a certain number of decimal places, and if you round the number to two or three or even eight decimal places, the error is never apparent. However, for applications where it does matter, it’s a lot of work to implement your own custom arithmetic routines.

Hence, the Decimal type was created.

The Decimal type

A new module, decimal, was added to Python’s standard library. It contains two classes, Decimal and Context. Decimal instances represent numbers, and Context instances are used to wrap up various settings such as the precision and default rounding mode.

Decimal instances are immutable, like regular Python integers and FP numbers; once it’s been created, you can’t change the value an instance represents. Decimal instances can be created from integers or strings:

>>> import decimal
>>> decimal.Decimal(1972)
Decimal("1972")
>>> decimal.Decimal("1.1")
Decimal("1.1")

You can also provide tuples containing the sign, the mantissa represented as a tuple of decimal digits, and the exponent:

>>> decimal.Decimal((1, (1, 4, 7, 5), -2))
Decimal("-14.75")

Cautionary note: the sign bit is a Boolean value, so 0 is positive and 1 is negative.

Converting from floating-point numbers poses a bit of a problem: should the FP number representing 1.1 turn into the decimal number for exactly 1.1, or for 1.1 plus whatever inaccuracies are introduced? The decision was to dodge the issue and leave such a conversion out of the API. Instead, you should convert the floating-point number into a string using the desired precision and pass the string to the Decimal constructor:

>>> f = 1.1
>>> decimal.Decimal(str(f))
Decimal("1.1")
>>> decimal.Decimal('%.12f' % f)
Decimal("1.100000000000")

Once you have Decimal instances, you can perform the usual mathematical operations on them. One limitation: exponentiation requires an integer exponent:

>>> a = decimal.Decimal('35.72')
>>> b = decimal.Decimal('1.73')
>>> a+b
Decimal("37.45")
>>> a-b
Decimal("33.99")
>>> a*b
Decimal("61.7956")
>>> a/b
Decimal("20.64739884393063583815028902")
>>> a ** 2
Decimal("1275.9184")
>>> a**b
Traceback (most recent call last):
  ...
decimal.InvalidOperation: x ** (non-integer)

You can combine Decimal instances with integers, but not with floating-point numbers:

>>> a + 4
Decimal("39.72")
>>> a + 4.5
Traceback (most recent call last):
  ...
TypeError: You can interact Decimal only with int, long or Decimal data types.
>>>

Decimal numbers can be used with the math and cmath modules, but note that they’ll be immediately converted to floating-point numbers before the operation is performed, resulting in a possible loss of precision and accuracy. You’ll also get back a regular floating-point number and not a Decimal.

>>> import math, cmath
>>> d = decimal.Decimal('123456789012.345')
>>> math.sqrt(d)
351364.18288201344
>>> cmath.sqrt(-d)
351364.18288201344j

Decimal instances have a sqrt() method that returns a Decimal, but if you need other things such as trigonometric functions you’ll have to implement them.

>>> d.sqrt()
Decimal("351364.1828820134592177245001")

The Context type

Instances of the Context class encapsulate several settings for decimal operations:

prec is the precision, the number of decimal places.

rounding specifies the rounding mode. The decimal module has constants for the various possibilities: ROUND_DOWN, ROUND_CEILING, ROUND_HALF_EVEN, and various others.

traps is a dictionary specifying what happens on encountering certain error conditions: either an exception is raised or a value is returned. Some examples of error conditions are division by zero, loss of precision, and overflow.

There’s a thread-local default context available by calling getcontext(); you can change the properties of this context to alter the default precision, rounding, or trap handling. The following example shows the effect of changing the precision of the default context:

>>> decimal.getcontext().prec
28
>>> decimal.Decimal(1) / decimal.Decimal(7)
Decimal("0.1428571428571428571428571429")
>>> decimal.getcontext().prec = 9
>>> decimal.Decimal(1) / decimal.Decimal(7)
Decimal("0.142857143")

The default action for error conditions is selectable; the module can either return a special value such as infinity or not-a-number, or exceptions can be raised:

>>> decimal.Decimal(1) / decimal.Decimal(0)
Traceback (most recent call last):
  ...
decimal.DivisionByZero: x / 0
>>> decimal.getcontext().traps[decimal.DivisionByZero] = False
>>> decimal.Decimal(1) / decimal.Decimal(0)
Decimal("Infinity")
>>>

The Context instance also has various methods for formatting numbers such as to_eng_string() and to_sci_string().

For more information, see the documentation for the decimal module, which includes a quick-start tutorial and a reference.

Ver también

PEP 327 [https://www.python.org/dev/peps/pep-0327] - Decimal Data Type

Written by Facundo Batista and implemented by Facundo Batista, Eric Price, Raymond Hettinger, Aahz, and Tim Peters.

http://www.lahey.com/float.htm

The article uses Fortran code to illustrate many of the problems that floating-point inaccuracy can cause.

http://speleotrove.com/decimal/

A description of a decimal-based representation. This representation is being proposed as a standard, and underlies the new Python decimal type. Much of this material was written by Mike Cowlishaw, designer of the Rexx language.

PEP 328: Multi-line Imports

One language change is a small syntactic tweak aimed at making it easier to import many names from a module. In a from module import names statement, names is a sequence of names separated by commas. If the sequence is very long, you can either write multiple imports from the same module, or you can use backslashes to escape the line endings like this:

from SimpleXMLRPCServer import SimpleXMLRPCServer,\
            SimpleXMLRPCRequestHandler,\
            CGIXMLRPCRequestHandler,\
            resolve_dotted_attribute

The syntactic change in Python 2.4 simply allows putting the names within parentheses. Python ignores newlines within a parenthesized expression, so the backslashes are no longer needed:

from SimpleXMLRPCServer import (SimpleXMLRPCServer,
                                SimpleXMLRPCRequestHandler,
                                CGIXMLRPCRequestHandler,
                                resolve_dotted_attribute)

The PEP also proposes that all import statements be absolute imports, with a leading . character to indicate a relative import. This part of the PEP was not implemented for Python 2.4, but was completed for Python 2.5.

Ver también

PEP 328 [https://www.python.org/dev/peps/pep-0328] - Imports: Multi-Line and Absolute/Relative

Written by Aahz. Multi-line imports were implemented by Dima Dorfman.

PEP 331: Locale-Independent Float/String Conversions

The locale modules lets Python software select various conversions and display conventions that are localized to a particular country or language. However, the module was careful to not change the numeric locale because various functions in Python’s implementation required that the numeric locale remain set to the 'C' locale. Often this was because the code was using the C library’s atof() function.

Not setting the numeric locale caused trouble for extensions that used third-party C libraries, however, because they wouldn’t have the correct locale set. The motivating example was GTK+, whose user interface widgets weren’t displaying numbers in the current locale.

The solution described in the PEP is to add three new functions to the Python API that perform ASCII-only conversions, ignoring the locale setting:

PyOS_ascii_strtod(str, ptr) and PyOS_ascii_atof(str, ptr) both convert a string to a C double.

PyOS_ascii_formatd(buffer, buf_len, format, d) converts a double to an ASCII string.

The code for these functions came from the GLib library (https://developer.gnome.org/glib/stable/), whose developers kindly relicensed the relevant functions and donated them to the Python Software Foundation. The locale module can now change the numeric locale, letting extensions such as GTK+ produce the correct results.

Ver también

PEP 331 [https://www.python.org/dev/peps/pep-0331] - Locale-Independent Float/String Conversions

Written by Christian R. Reis, and implemented by Gustavo Carneiro.

Other Language Changes

Here are all of the changes that Python 2.4 makes to the core Python language.

Decorators for functions and methods were added (PEP 318 [https://www.python.org/dev/peps/pep-0318]).

Built-in set() and frozenset() types were added (PEP 218 [https://www.python.org/dev/peps/pep-0218]). Other new built-ins include the reversed(seq) function (PEP 322 [https://www.python.org/dev/peps/pep-0322]).

Generator expressions were added (PEP 289 [https://www.python.org/dev/peps/pep-0289]).

Certain numeric expressions no longer return values restricted to 32 or 64 bits (PEP 237 [https://www.python.org/dev/peps/pep-0237]).

You can now put parentheses around the list of names in a from module import names statement (PEP 328 [https://www.python.org/dev/peps/pep-0328]).

The dict.update() method now accepts the same argument forms as the dict constructor. This includes any mapping, any iterable of key/value pairs, and keyword arguments. (Contributed by Raymond Hettinger.)

The string methods ljust(), rjust(), and center() now take an optional argument for specifying a fill character other than a space. (Contributed by Raymond Hettinger.)

Strings also gained an rsplit() method that works like the split() method but splits from the end of the string. (Contributed by Sean Reifschneider.)

>>> 'www.python.org'.split('.', 1)
['www', 'python.org']
'www.python.org'.rsplit('.', 1)
['www.python', 'org']

Three keyword parameters, cmp, key, and reverse, were added to the sort() method of lists. These parameters make some common usages of sort() simpler. All of these parameters are optional.

For the cmp parameter, the value should be a comparison function that takes two parameters and returns -1, 0, or +1 depending on how the parameters compare. This function will then be used to sort the list. Previously this was the only parameter that could be provided to sort().

key should be a single-parameter function that takes a list element and returns a comparison key for the element. The list is then sorted using the comparison keys. The following example sorts a list case-insensitively:

>>> L = ['A', 'b', 'c', 'D']
>>> L.sort()                 # Case-sensitive sort
>>> L
['A', 'D', 'b', 'c']
>>> # Using 'key' parameter to sort list
>>> L.sort(key=lambda x: x.lower())
>>> L
['A', 'b', 'c', 'D']
>>> # Old-fashioned way
>>> L.sort(cmp=lambda x,y: cmp(x.lower(), y.lower()))
>>> L
['A', 'b', 'c', 'D']

The last example, which uses the cmp parameter, is the old way to perform a case-insensitive sort. It works but is slower than using a key parameter. Using key calls lower() method once for each element in the list while using cmp will call it twice for each comparison, so using key saves on invocations of the lower() method.

For simple key functions and comparison functions, it is often possible to avoid a lambda expression by using an unbound method instead. For example, the above case-insensitive sort is best written as:

>>> L.sort(key=str.lower)
>>> L
['A', 'b', 'c', 'D']

Finally, the reverse parameter takes a Boolean value. If the value is true, the list will be sorted into reverse order. Instead of L.sort(); L.reverse(), you can now write L.sort(reverse=True).

The results of sorting are now guaranteed to be stable. This means that two entries with equal keys will be returned in the same order as they were input. For example, you can sort a list of people by name, and then sort the list by age, resulting in a list sorted by age where people with the same age are in name-sorted order.

(All changes to sort() contributed by Raymond Hettinger.)

There is a new built-in function sorted(iterable) that works like the in-place list.sort() method but can be used in expressions. The differences are:

the input may be any iterable;

a newly formed copy is sorted, leaving the original intact; and

the expression returns the new sorted copy

>>> L = [9,7,8,3,2,4,1,6,5]
>>> [10+i for i in sorted(L)]       # usable in a list comprehension
[11, 12, 13, 14, 15, 16, 17, 18, 19]
>>> L                               # original is left unchanged
[9,7,8,3,2,4,1,6,5]
>>> sorted('Monty Python')          # any iterable may be an input
[' ', 'M', 'P', 'h', 'n', 'n', 'o', 'o', 't', 't', 'y', 'y']

>>> # List the contents of a dict sorted by key values
>>> colormap = dict(red=1, blue=2, green=3, black=4, yellow=5)
>>> for k, v in sorted(colormap.iteritems()):
...     print k, v
...
black 4
blue 2
green 3
red 1
yellow 5

(Contributed by Raymond Hettinger.)

Integer operations will no longer trigger an OverflowWarning. The OverflowWarning warning will disappear in Python 2.5.

The interpreter gained a new switch, -m, that takes a name, searches for the corresponding module on sys.path, and runs the module as a script. For example, you can now run the Python profiler with python -m profile. (Contributed by Nick Coghlan.)

The eval(expr, globals, locals) and execfile(filename, globals, locals) functions and the exec statement now accept any mapping type for the locals parameter. Previously this had to be a regular Python dictionary. (Contributed by Raymond Hettinger.)

The zip() built-in function and itertools.izip() now return an empty list if called with no arguments. Previously they raised a TypeError exception. This makes them more suitable for use with variable length argument lists:

>>> def transpose(array):
...    return zip(*array)
...
>>> transpose([(1,2,3), (4,5,6)])
[(1, 4), (2, 5), (3, 6)]
>>> transpose([])
[]

(Contributed by Raymond Hettinger.)

Encountering a failure while importing a module no longer leaves a partially-initialized module object in sys.modules. The incomplete module object left behind would fool further imports of the same module into succeeding, leading to confusing errors. (Fixed by Tim Peters.)

None is now a constant; code that binds a new value to the name None is now a syntax error. (Contributed by Raymond Hettinger.)

Optimizations

The inner loops for list and tuple slicing were optimized and now run about one-third faster. The inner loops for dictionaries were also optimized, resulting in performance boosts for keys(), values(), items(), iterkeys(), itervalues(), and iteritems(). (Contributed by Raymond Hettinger.)

The machinery for growing and shrinking lists was optimized for speed and for space efficiency. Appending and popping from lists now runs faster due to more efficient code paths and less frequent use of the underlying system realloc(). List comprehensions also benefit. list.extend() was also optimized and no longer converts its argument into a temporary list before extending the base list. (Contributed by Raymond Hettinger.)

list(), tuple(), map(), filter(), and zip() now run several times faster with non-sequence arguments that supply a __len__() method. (Contributed by Raymond Hettinger.)

The methods list.__getitem__(), dict.__getitem__(), and dict.__contains__() are now implemented as method_descriptor objects rather than wrapper_descriptor objects. This form of access doubles their performance and makes them more suitable for use as arguments to functionals: map(mydict.__getitem__, keylist). (Contributed by Raymond Hettinger.)

Added a new opcode, LIST_APPEND, that simplifies the generated bytecode for list comprehensions and speeds them up by about a third. (Contributed by Raymond Hettinger.)

The peephole bytecode optimizer has been improved to produce shorter, faster bytecode; remarkably, the resulting bytecode is more readable. (Enhanced by Raymond Hettinger.)

String concatenations in statements of the form s = s + "abc" and s += "abc" are now performed more efficiently in certain circumstances. This optimization won’t be present in other Python implementations such as Jython, so you shouldn’t rely on it; using the join() method of strings is still recommended when you want to efficiently glue a large number of strings together. (Contributed by Armin Rigo.)

The net result of the 2.4 optimizations is that Python 2.4 runs the pystone benchmark around 5% faster than Python 2.3 and 35% faster than Python 2.2. (pystone is not a particularly good benchmark, but it’s the most commonly used measurement of Python’s performance. Your own applications may show greater or smaller benefits from Python 2.4.)

New, Improved, and Deprecated Modules

As usual, Python’s standard library received a number of enhancements and bug fixes. Here’s a partial list of the most notable changes, sorted alphabetically by module name. Consult the Misc/NEWS file in the source tree for a more complete list of changes, or look through the CVS logs for all the details.

The asyncore module’s loop() function now has a count parameter that lets you perform a limited number of passes through the polling loop. The default is still to loop forever.

The base64 module now has more complete RFC 3548 [https://tools.ietf.org/html/rfc3548.html] support for Base64, Base32, and Base16 encoding and decoding, including optional case folding and optional alternative alphabets. (Contributed by Barry Warsaw.)

The bisect module now has an underlying C implementation for improved performance. (Contributed by Dmitry Vasiliev.)

The CJKCodecs collections of East Asian codecs, maintained by Hye-Shik Chang, was integrated into 2.4. The new encodings are:

Chinese (PRC): gb2312, gbk, gb18030, big5hkscs, hz

Chinese (ROC): big5, cp950

Japanese: cp932, euc-jis-2004, euc-jp, euc-jisx0213, iso-2022-jp,

iso-2022-jp-1, iso-2022-jp-2, iso-2022-jp-3, iso-2022-jp-ext, iso-2022-jp-2004, shift-jis, shift-jisx0213, shift-jis-2004

Korean: cp949, euc-kr, johab, iso-2022-kr

Some other new encodings were added: HP Roman8, ISO_8859-11, ISO_8859-16, PCTP-154, and TIS-620.

The UTF-8 and UTF-16 codecs now cope better with receiving partial input. Previously the StreamReader class would try to read more data, making it impossible to resume decoding from the stream. The read() method will now return as much data as it can and future calls will resume decoding where previous ones left off. (Implemented by Walter Dörwald.)

There is a new collections module for various specialized collection datatypes. Currently it contains just one type, deque, a double-ended queue that supports efficiently adding and removing elements from either end:

>>> from collections import deque
>>> d = deque('ghi')        # make a new deque with three items
>>> d.append('j')           # add a new entry to the right side
>>> d.appendleft('f')       # add a new entry to the left side
>>> d                       # show the representation of the deque
deque(['f', 'g', 'h', 'i', 'j'])
>>> d.pop()                 # return and remove the rightmost item
'j'
>>> d.popleft()             # return and remove the leftmost item
'f'
>>> list(d)                 # list the contents of the deque
['g', 'h', 'i']
>>> 'h' in d                # search the deque
True

Several modules, such as the Queue and threading modules, now take advantage of collections.deque for improved performance. (Contributed by Raymond Hettinger.)

The ConfigParser classes have been enhanced slightly. The read() method now returns a list of the files that were successfully parsed, and the set() method raises TypeError if passed a value argument that isn’t a string. (Contributed by John Belmonte and David Goodger.)

The curses module now supports the ncurses extension use_default_colors(). On platforms where the terminal supports transparency, this makes it possible to use a transparent background. (Contributed by Jörg Lehmann.)

The difflib module now includes an HtmlDiff class that creates an HTML table showing a side by side comparison of two versions of a text. (Contributed by Dan Gass.)

The email package was updated to version 3.0, which dropped various deprecated APIs and removes support for Python versions earlier than 2.3. The 3.0 version of the package uses a new incremental parser for MIME messages, available in the email.FeedParser module. The new parser doesn’t require reading the entire message into memory, and doesn’t raise exceptions if a message is malformed; instead it records any problems in the defect attribute of the message. (Developed by Anthony Baxter, Barry Warsaw, Thomas Wouters, and others.)

The heapq module has been converted to C. The resulting tenfold improvement in speed makes the module suitable for handling high volumes of data. In addition, the module has two new functions nlargest() and nsmallest() that use heaps to find the N largest or smallest values in a dataset without the expense of a full sort. (Contributed by Raymond Hettinger.)

The httplib module now contains constants for HTTP status codes defined in various HTTP-related RFC documents. Constants have names such as OK, CREATED, CONTINUE, and MOVED_PERMANENTLY; use pydoc to get a full list. (Contributed by Andrew Eland.)

The imaplib module now supports IMAP’s THREAD command (contributed by Yves Dionne) and new deleteacl() and myrights() methods (contributed by Arnaud Mazin).

The itertools module gained a groupby(iterable[, *func*]) function. iterable is something that can be iterated over to return a stream of elements, and the optional func parameter is a function that takes an element and returns a key value; if omitted, the key is simply the element itself. groupby() then groups the elements into subsequences which have matching values of the key, and returns a series of 2-tuples containing the key value and an iterator over the subsequence.

Here’s an example to make this clearer. The key function simply returns whether a number is even or odd, so the result of groupby() is to return consecutive runs of odd or even numbers.

>>> import itertools
>>> L = [2, 4, 6, 7, 8, 9, 11, 12, 14]
>>> for key_val, it in itertools.groupby(L, lambda x: x % 2):
...    print key_val, list(it)
...
0 [2, 4, 6]
1 [7]
0 [8]
1 [9, 11]
0 [12, 14]
>>>

groupby() is typically used with sorted input. The logic for groupby() is similar to the Unix uniq filter which makes it handy for eliminating, counting, or identifying duplicate elements:

>>> word = 'abracadabra'
>>> letters = sorted(word)   # Turn string into a sorted list of letters
>>> letters
['a', 'a', 'a', 'a', 'a', 'b', 'b', 'c', 'd', 'r', 'r']
>>> for k, g in itertools.groupby(letters):
...    print k, list(g)
...
a ['a', 'a', 'a', 'a', 'a']
b ['b', 'b']
c ['c']
d ['d']
r ['r', 'r']
>>> # List unique letters
>>> [k for k, g in groupby(letters)]
['a', 'b', 'c', 'd', 'r']
>>> # Count letter occurrences
>>> [(k, len(list(g))) for k, g in groupby(letters)]
[('a', 5), ('b', 2), ('c', 1), ('d', 1), ('r', 2)]

(Contributed by Hye-Shik Chang.)

itertools also gained a function named tee(iterator, N) that returns N independent iterators that replicate iterator. If N is omitted, the default is 2.

>>> L = [1,2,3]
>>> i1, i2 = itertools.tee(L)
>>> i1,i2
(<itertools.tee object at 0x402c2080>, <itertools.tee object at 0x402c2090>)
>>> list(i1)               # Run the first iterator to exhaustion
[1, 2, 3]
>>> list(i2)               # Run the second iterator to exhaustion
[1, 2, 3]

Note that tee() has to keep copies of the values returned by the iterator; in the worst case, it may need to keep all of them. This should therefore be used carefully if the leading iterator can run far ahead of the trailing iterator in a long stream of inputs. If the separation is large, then you might as well use list() instead. When the iterators track closely with one another, tee() is ideal. Possible applications include bookmarking, windowing, or lookahead iterators. (Contributed by Raymond Hettinger.)

A number of functions were added to the locale module, such as bind_textdomain_codeset() to specify a particular encoding and a family of l*gettext() functions that return messages in the chosen encoding. (Contributed by Gustavo Niemeyer.)

Some keyword arguments were added to the logging package’s basicConfig() function to simplify log configuration. The default behavior is to log messages to standard error, but various keyword arguments can be specified to log to a particular file, change the logging format, or set the logging level. For example:

import logging
logging.basicConfig(filename='/var/log/application.log',
    level=0,  # Log all messages
    format='%(levelname):%(process):%(thread):%(message)')

Other additions to the logging package include a log(level, msg) convenience method, as well as a TimedRotatingFileHandler class that rotates its log files at a timed interval. The module already had RotatingFileHandler, which rotated logs once the file exceeded a certain size. Both classes derive from a new BaseRotatingHandler class that can be used to implement other rotating handlers.

(Changes implemented by Vinay Sajip.)

The marshal module now shares interned strings on unpacking a data structure. This may shrink the size of certain pickle strings, but the primary effect is to make .pyc files significantly smaller. (Contributed by Martin von Löwis.)

The nntplib module’s NNTP class gained description() and descriptions() methods to retrieve newsgroup descriptions for a single group or for a range of groups. (Contributed by Jürgen A. Erhard.)

Two new functions were added to the operator module, attrgetter(attr) and itemgetter(index). Both functions return callables that take a single argument and return the corresponding attribute or item; these callables make excellent data extractors when used with map() or sorted(). For example:

>>> L = [('c', 2), ('d', 1), ('a', 4), ('b', 3)]
>>> map(operator.itemgetter(0), L)
['c', 'd', 'a', 'b']
>>> map(operator.itemgetter(1), L)
[2, 1, 4, 3]
>>> sorted(L, key=operator.itemgetter(1)) # Sort list by second tuple item
[('d', 1), ('c', 2), ('b', 3), ('a', 4)]

(Contributed by Raymond Hettinger.)

The optparse module was updated in various ways. The module now passes its messages through gettext.gettext(), making it possible to internationalize Optik’s help and error messages. Help messages for options can now include the string '%default', which will be replaced by the option’s default value. (Contributed by Greg Ward.)

The long-term plan is to deprecate the rfc822 module in some future Python release in favor of the email package. To this end, the email.Utils.formatdate() function has been changed to make it usable as a replacement for rfc822.formatdate(). You may want to write new e-mail processing code with this in mind. (Change implemented by Anthony Baxter.)

A new urandom(n) function was added to the os module, returning a string containing n bytes of random data. This function provides access to platform-specific sources of randomness such as /dev/urandom on Linux or the Windows CryptoAPI. (Contributed by Trevor Perrin.)

Another new function: os.path.lexists(path) returns true if the file specified by path exists, whether or not it’s a symbolic link. This differs from the existing os.path.exists(path) function, which returns false if path is a symlink that points to a destination that doesn’t exist. (Contributed by Beni Cherniavsky.)

A new getsid() function was added to the posix module that underlies the os module. (Contributed by J. Raynor.)

The poplib module now supports POP over SSL. (Contributed by Hector Urtubia.)

The profile module can now profile C extension functions. (Contributed by Nick Bastin.)

The random module has a new method called getrandbits(N) that returns a long integer N bits in length. The existing randrange() method now uses getrandbits() where appropriate, making generation of arbitrarily large random numbers more efficient. (Contributed by Raymond Hettinger.)

The regular expression language accepted by the re module was extended with simple conditional expressions, written as (?(group)A|B). group is either a numeric group ID or a group name defined with (?P<group>...) earlier in the expression. If the specified group matched, the regular expression pattern A will be tested against the string; if the group didn’t match, the pattern B will be used instead. (Contributed by Gustavo Niemeyer.)

The re module is also no longer recursive, thanks to a massive amount of work by Gustavo Niemeyer. In a recursive regular expression engine, certain patterns result in a large amount of C stack space being consumed, and it was possible to overflow the stack. For example, if you matched a 30000-byte string of a characters against the expression (a|b)+, one stack frame was consumed per character. Python 2.3 tried to check for stack overflow and raise a RuntimeError exception, but certain patterns could sidestep the checking and if you were unlucky Python could segfault. Python 2.4’s regular expression engine can match this pattern without problems.

The signal module now performs tighter error-checking on the parameters to the signal.signal() function. For example, you can’t set a handler on the SIGKILL signal; previous versions of Python would quietly accept this, but 2.4 will raise a RuntimeError exception.

Two new functions were added to the socket module. socketpair() returns a pair of connected sockets and getservbyport(port) looks up the service name for a given port number. (Contributed by Dave Cole and Barry Warsaw.)

The sys.exitfunc() function has been deprecated. Code should be using the existing atexit module, which correctly handles calling multiple exit functions. Eventually sys.exitfunc() will become a purely internal interface, accessed only by atexit.

The tarfile module now generates GNU-format tar files by default. (Contributed by Lars Gustäbel.)

The threading module now has an elegantly simple way to support thread-local data. The module contains a local class whose attribute values are local to different threads.

import threading

data = threading.local()
data.number = 42
data.url = ('www.python.org', 80)

Other threads can assign and retrieve their own values for the number and url attributes. You can subclass local to initialize attributes or to add methods. (Contributed by Jim Fulton.)

The timeit module now automatically disables periodic garbage collection during the timing loop. This change makes consecutive timings more comparable. (Contributed by Raymond Hettinger.)

The weakref module now supports a wider variety of objects including Python functions, class instances, sets, frozensets, deques, arrays, files, sockets, and regular expression pattern objects. (Contributed by Raymond Hettinger.)

The xmlrpclib module now supports a multi-call extension for transmitting multiple XML-RPC calls in a single HTTP operation. (Contributed by Brian Quinlan.)

The mpz, rotor, and xreadlines modules have been removed.

cookielib

The cookielib library supports client-side handling for HTTP cookies, mirroring the Cookie module’s server-side cookie support. Cookies are stored in cookie jars; the library transparently stores cookies offered by the web server in the cookie jar, and fetches the cookie from the jar when connecting to the server. As in web browsers, policy objects control whether cookies are accepted or not.

In order to store cookies across sessions, two implementations of cookie jars are provided: one that stores cookies in the Netscape format so applications can use the Mozilla or Lynx cookie files, and one that stores cookies in the same format as the Perl libwww library.

urllib2 has been changed to interact with cookielib: HTTPCookieProcessor manages a cookie jar that is used when accessing URLs.

This module was contributed by John J. Lee.

doctest

The doctest module underwent considerable refactoring thanks to Edward Loper and Tim Peters. Testing can still be as simple as running doctest.testmod(), but the refactorings allow customizing the module’s operation in various ways

The new DocTestFinder class extracts the tests from a given object’s docstrings:

def f (x, y):
    """>>> f(2,2)
4
>>> f(3,2)
6
    """
    return x*y

finder = doctest.DocTestFinder()

# Get list of DocTest instances
tests = finder.find(f)

The new DocTestRunner class then runs individual tests and can produce a summary of the results:

runner = doctest.DocTestRunner()
for t in tests:
    tried, failed = runner.run(t)

runner.summarize(verbose=1)

The above example produces the following output:

1 items passed all tests:
   2 tests in f
2 tests in 1 items.
2 passed and 0 failed.
Test passed.

DocTestRunner uses an instance of the OutputChecker class to compare the expected output with the actual output. This class takes a number of different flags that customize its behaviour; ambitious users can also write a completely new subclass of OutputChecker.

The default output checker provides a number of handy features. For example, with the doctest.ELLIPSIS option flag, an ellipsis (...) in the expected output matches any substring, making it easier to accommodate outputs that vary in minor ways:

def o (n):
    """>>> o(1)
<__main__.C instance at 0x...>
>>>
"""

Another special string, <BLANKLINE>, matches a blank line:

def p (n):
    """>>> p(1)
<BLANKLINE>
>>>
"""

Another new capability is producing a diff-style display of the output by specifying the doctest.REPORT_UDIFF (unified diffs), doctest.REPORT_CDIFF (context diffs), or doctest.REPORT_NDIFF (delta-style) option flags. For example:

def g (n):
    """>>> g(4)
here
is
a
lengthy
>>>"""
    L = 'here is a rather lengthy list of words'.split()
    for word in L[:n]:
        print word

Running the above function’s tests with doctest.REPORT_UDIFF specified, you get the following output:

**********************************************************************
File "t.py", line 15, in g
Failed example:
    g(4)
Differences (unified diff with -expected +actual):
    @@ -2,3 +2,3 @@
     is
     a
    -lengthy
    +rather
**********************************************************************

Build and C API Changes

Some of the changes to Python’s build process and to the C API are:

Three new convenience macros were added for common return values from extension functions: Py_RETURN_NONE, Py_RETURN_TRUE, and Py_RETURN_FALSE. (Contributed by Brett Cannon.)

Another new macro, Py_CLEAR(obj), decreases the reference count of obj and sets obj to the null pointer. (Contributed by Jim Fulton.)

A new function, PyTuple_Pack(N, obj1, obj2, ..., objN), constructs tuples from a variable length argument list of Python objects. (Contributed by Raymond Hettinger.)

A new function, PyDict_Contains(d, k), implements fast dictionary lookups without masking exceptions raised during the look-up process. (Contributed by Raymond Hettinger.)

The Py_IS_NAN(X) macro returns 1 if its float or double argument X is a NaN. (Contributed by Tim Peters.)

C code can avoid unnecessary locking by using the new PyEval_ThreadsInitialized() function to tell if any thread operations have been performed. If this function returns false, no lock operations are needed. (Contributed by Nick Coghlan.)

A new function, PyArg_VaParseTupleAndKeywords(), is the same as PyArg_ParseTupleAndKeywords() but takes a va_list instead of a number of arguments. (Contributed by Greg Chapman.)

A new method flag, METH_COEXISTS, allows a function defined in slots to co-exist with a PyCFunction having the same name. This can halve the access time for a method such as set.__contains__(). (Contributed by Raymond Hettinger.)

Python can now be built with additional profiling for the interpreter itself, intended as an aid to people developing the Python core. Providing --enable-profiling to the configure script will let you profile the interpreter with gprof, and providing the --with-tsc switch enables profiling using the Pentium’s Time-Stamp-Counter register. Note that the --with-tsc switch is slightly misnamed, because the profiling feature also works on the PowerPC platform, though that processor architecture doesn’t call that register «the TSC register». (Contributed by Jeremy Hylton.)

The tracebackobject type has been renamed to PyTracebackObject.

Port-Specific Changes

The Windows port now builds under MSVC++ 7.1 as well as version 6. (Contributed by Martin von Löwis.)

Porting to Python 2.4

This section lists previously described changes that may require changes to your code:

Left shifts and hexadecimal/octal constants that are too large no longer trigger a FutureWarning and return a value limited to 32 or 64 bits; instead they return a long integer.

Integer operations will no longer trigger an OverflowWarning. The OverflowWarning warning will disappear in Python 2.5.

The zip() built-in function and itertools.izip() now return an empty list instead of raising a TypeError exception if called with no arguments.

You can no longer compare the date and datetime instances provided by the datetime module. Two instances of different classes will now always be unequal, and relative comparisons (<, >) will raise a TypeError.

dircache.listdir() now passes exceptions to the caller instead of returning empty lists.

LexicalHandler.startDTD() used to receive the public and system IDs in the wrong order. This has been corrected; applications relying on the wrong order need to be fixed.

fcntl.ioctl() now warns if the mutate argument is omitted and relevant.

The tarfile module now generates GNU-format tar files by default.

Encountering a failure while importing a module no longer leaves a partially-initialized module object in sys.modules.

None is now a constant; code that binds a new value to the name None is now a syntax error.

The signals.signal() function now raises a RuntimeError exception for certain illegal values; previously these errors would pass silently. For example, you can no longer set a handler on the SIGKILL signal.

Acknowledgements

The author would like to thank the following people for offering suggestions, corrections and assistance with various drafts of this article: Koray Can, Hye-Shik Chang, Michael Dyck, Raymond Hettinger, Brian Hurt, Hamish Lawson, Fredrik Lundh, Sean Reifschneider, Sadruddin Rejeb.

Qué hay de nuevo en Python 2.3

Autor

A.M. Kuchling

Este artículo explica las nuevas características de Python 2.3. Python 2.3 se publicó el 29 de julio de 2003.

Los temas principales de Python 2.3 son el pulido de algunas de las características añadidas en la 2.2, la adición de varias mejoras pequeñas pero útiles al núcleo del lenguaje y la ampliación de la biblioteca estándar. El nuevo modelo de objetos introducido en la versión anterior se ha beneficiado de 18 meses de correcciones de errores y de esfuerzos de optimización que han mejorado el rendimiento de las clases de nuevo estilo. Se han añadido algunas funciones incorporadas, como sum() y enumerate(). El operador in puede utilizarse ahora para búsquedas de subcadenas (por ejemplo, "ab" en "abc" retorna True).

Algunas de las nuevas características de la biblioteca son los tipos de datos booleanos, de conjunto, de montón y de fecha/hora, la posibilidad de importar módulos desde archivos con formato ZIP, el soporte de metadatos para el tan esperado catálogo de Python, una versión actualizada de IDLE y módulos para registrar mensajes, envolver texto, analizar archivos CSV, procesar opciones de línea de comandos, utilizar bases de datos BerkeleyDB… la lista de módulos nuevos y mejorados es larga.

Este artículo no pretende proporcionar una especificación completa de las nuevas características, sino que proporciona una visión general conveniente. Para obtener todos los detalles, debes consultar la documentación de Python 2.3, como la Referencia de la Biblioteca de Python y el Manual de Referencia de Python. Si quieres entender la implementación completa y los fundamentos del diseño, consulta el PEP de una nueva característica en particular.

PEP 218: Un tipo de datos de conjunto estándar

El nuevo módulo sets contiene una implementación de un tipo de datos de conjuntos. La clase Set es para conjuntos mutables, conjuntos a los que se les pueden añadir y eliminar miembros. La clase ImmutableSet es para los conjuntos que no pueden ser modificados, y las instancias de ImmutableSet pueden por lo tanto ser utilizadas como claves de diccionario. Los conjuntos se construyen sobre diccionarios, por lo que los elementos de un conjunto deben ser hashables.

Aquí hay un ejemplo simple:

>>> import sets
>>> S = sets.Set([1,2,3])
>>> S
Set([1, 2, 3])
>>> 1 in S
True
>>> 0 in S
False
>>> S.add(5)
>>> S.remove(3)
>>> S
Set([1, 2, 5])
>>>

La unión y la intersección de los conjuntos pueden calcularse con los métodos union() y intersection(); una notación alternativa utiliza los operadores bitácora & y |. Los conjuntos mutables también tienen versiones in situ de estos métodos, union_update() y intersection_update().

>>> S1 = sets.Set([1,2,3])
>>> S2 = sets.Set([4,5,6])
>>> S1.union(S2)
Set([1, 2, 3, 4, 5, 6])
>>> S1 | S2                  # Alternative notation
Set([1, 2, 3, 4, 5, 6])
>>> S1.intersection(S2)
Set([])
>>> S1 & S2                  # Alternative notation
Set([])
>>> S1.union_update(S2)
>>> S1
Set([1, 2, 3, 4, 5, 6])
>>>

También es posible tomar la diferencia simétrica de dos conjuntos. Este es el conjunto de todos los elementos de la unión que no están en la intersección. Otra forma de decirlo es que la diferencia simétrica contiene todos los elementos que están exactamente en un conjunto. De nuevo, existe una notación alternativa (^), y una versión in-place con el poco agraciado nombre symmetric_difference_update().

>>> S1 = sets.Set([1,2,3,4])
>>> S2 = sets.Set([3,4,5,6])
>>> S1.symmetric_difference(S2)
Set([1, 2, 5, 6])
>>> S1 ^ S2
Set([1, 2, 5, 6])
>>>

También hay métodos issubset() y issuperset() para comprobar si un conjunto es subconjunto o superconjunto de otro:

>>> S1 = sets.Set([1,2,3])
>>> S2 = sets.Set([2,3])
>>> S2.issubset(S1)
True
>>> S1.issubset(S2)
False
>>> S1.issuperset(S2)
True
>>>

Ver también

PEP 218 [https://www.python.org/dev/peps/pep-0218] - Añadiendo un tipo de objeto de conjunto incorporado

PEP escrito por Greg V. Wilson. Implementado por Greg V. Wilson, Alex Martelli y GvR.

PEP 255: Generadores simples

En Python 2.2, los generadores se añadieron como una característica opcional, que se activaba mediante una directiva from __future__ import generators. En 2.3 los generadores ya no necesitan ser habilitados especialmente, y ahora están siempre presentes; esto significa que yield es ahora siempre una palabra clave. El resto de esta sección es una copia de la descripción de los generadores del documento «What’s New in Python 2.2»; si lo leíste cuando salió Python 2.2, puedes saltarte el resto de esta sección.

Sin duda estás familiarizado con cómo funcionan las llamadas a funciones en Python o C. Cuando llamas a una función, ésta obtiene un espacio de nombres privado donde se crean sus variables locales. Cuando la función llega a una declaración return, las variables locales se destruyen y el valor resultante se retorna a quien la llamó. Una llamada posterior a la misma función obtendrá un nuevo conjunto de variables locales. Pero, ¿qué pasaría si las variables locales no se tiraran al salir de una función? ¿Qué pasaría si pudieras reanudar la función donde la dejaste? Esto es lo que proporcionan los generadores; se puede pensar en ellos como funciones reanudables.

Este es el ejemplo más sencillo de una función generadora:

def generate_ints(N):
    for i in range(N):
        yield i

Se ha introducido una nueva palabra clave, yield, para los generadores. Cualquier función que contenga una declaración yield es una función generadora; esto es detectado por el compilador de código de bits de Python que compila la función especialmente como resultado.

Cuando se llama a una función generadora, ésta no retorna un único valor, sino que retorna un objeto generador que soporta el protocolo de los iteradores. Al ejecutar la sentencia yield, el generador retorna el valor de i, de forma similar a una sentencia return. La gran diferencia entre yield y una sentencia return es que al llegar a una sentencia yield se suspende el estado de ejecución del generador y se conservan las variables locales. En la siguiente llamada al método .next() del generador, la función se reanudará la ejecución inmediatamente después de la sentencia yield. (Por razones complicadas, la sentencia yield no está permitida dentro del bloque try de una sentencia try…`; lea PEP 255 [https://www.python.org/dev/peps/pep-0255] para una explicación completa de la interacción entre yield y las excepciones)

Este es un ejemplo de uso del generador generate_ints():

>>> gen = generate_ints(3)
>>> gen
<generator object at 0x8117f90>
>>> gen.next()
0
>>> gen.next()
1
>>> gen.next()
2
>>> gen.next()
Traceback (most recent call last):
  File "stdin", line 1, in ?
  File "stdin", line 2, in generate_ints
StopIteration

También podrías escribir for i in generate_ints(5), o a,b,c = generate_ints(3).

Dentro de una función generadora, la expresión return sólo puede usarse sin un valor, y señala el final de la procesión de valores; después el generador no puede retornar más valores. return con un valor, como return 5, es un error de sintaxis dentro de una función generadora. El final de los resultados del generador también puede indicarse levantando manualmente StopIteration, o simplemente dejando que el flujo de ejecución caiga en el fondo de la función.

Puedes conseguir el efecto de los generadores manualmente escribiendo tu propia clase y almacenando todas las variables locales del generador como variables de instancia. Por ejemplo, la devolución de una lista de enteros podría hacerse estableciendo self.count a 0, y haciendo que el método next() incremente self.count y lo retorne. Sin embargo, para un generador medianamente complicado, escribir la clase correspondiente sería mucho más complicado. Lib/test/test_generators.py contiene varios ejemplos más interesantes. El más sencillo implementa un recorrido en orden de un árbol utilizando generadores de forma recursiva

# A recursive generator that generates Tree leaves in in-order.
def inorder(t):
    if t:
        for x in inorder(t.left):
            yield x
        yield t.label
        for x in inorder(t.right):
            yield x

Otros dos ejemplos en Lib/test/test_generators.py producen soluciones para el problema de las N reinas (colocar $N$ reinas en un tablero de ajedrez $NxN$ de forma que ninguna reina amenace a otra) y el recorrido del caballero (una ruta que lleva a un caballo a cada casilla de un tablero de ajedrez $NxN$ sin visitar ninguna casilla dos veces).

La idea de los generadores proviene de otros lenguajes de programación, especialmente de Icon (https://www.cs.arizona.edu/icon/), donde la idea de los generadores es fundamental. En Icon, cada expresión y llamada a una función se comporta como un generador. Un ejemplo de «An Overview of the Icon Programming Language» en https://www.cs.arizona.edu/icon/docs/ipd266.htm da una idea de cómo es esto:

sentence := "Store it in the neighboring harbor"
if (i := find("or", sentence)) > 5 then write(i)

En Icon la función find() retorna los índices en los que se encuentra la subcadena «o»: 3, 23, 33. En la expresión if, a i se le asigna primero un valor de 3, pero 3 es menor que 5, por lo que la comparación falla, e Icon la reintenta con el segundo valor de 23. 23 es mayor que 5, por lo que la comparación ahora tiene éxito, y el código imprime el valor 23 en la pantalla.

Python no va tan lejos como Icon en la adopción de generadores como concepto central. Los generadores se consideran parte del núcleo del lenguaje Python, pero aprenderlos o utilizarlos no es obligatorio; si no resuelven ningún problema que tengas, siéntete libre de ignorarlos. Una característica novedosa de la interfaz de Python en comparación con la de Icon es que el estado de un generador se representa como un objeto concreto (el iterador) que puede pasarse a otras funciones o almacenarse en una estructura de datos.

Ver también

PEP 255 [https://www.python.org/dev/peps/pep-0255] - Generadores simples

Escrito por Neil Schemenauer, Tim Peters, Magnus Lie Hetland. Implementado principalmente por Neil Schemenauer y Tim Peters, con otras correcciones del equipo de Python Labs.

PEP 263: Codificación del código fuente

Los archivos fuente de Python ahora pueden declararse con diferentes codificaciones de conjuntos de caracteres. Las codificaciones se declaran incluyendo un comentario con formato especial en la primera o segunda línea del archivo fuente. Por ejemplo, un archivo UTF-8 puede declararse con:

#!/usr/bin/env python
# -*- coding: UTF-8 -*-

Sin esta declaración de codificación, la codificación por defecto utilizada es ASCII de 7 bits. Ejecutar o importar módulos que contengan literales de cadena con caracteres de 8 bits y que no tengan una declaración de codificación dará lugar a un DeprecationWarning señalado por Python 2.3; en 2.4 será un error de sintaxis.

La declaración de codificación sólo afecta a los literales de cadena Unicode, que se convertirán a Unicode utilizando la codificación especificada. Ten en cuenta que los identificadores de Python siguen restringidos a caracteres ASCII, por lo que no puedes tener nombres de variables que utilicen caracteres fuera de los alfanuméricos habituales.

Ver también

PEP 263 [https://www.python.org/dev/peps/pep-0263] - Definición de las codificaciones del código fuente de Python

Escrito por Marc-André Lemburg y Martin von Löwis; realizado por Suzuki Hisao y Martin von Löwis.

PEP 273: Importar módulos desde archivos ZIP

El nuevo módulo zipimport añade soporte para importar módulos desde un archivo en formato ZIP. No es necesario importar el módulo explícitamente; se importará automáticamente si se añade el nombre de un archivo ZIP a sys.path. Por ejemplo:

amk@nyman:~/src/python$ unzip -l /tmp/example.zip
Archive:  /tmp/example.zip
  Length     Date   Time    Name
 --------    ----   ----    ----
     8467  11-26-02 22:30   jwzthreading.py
 --------                   -------
     8467                   1 file
amk@nyman:~/src/python$ ./python
Python 2.3 (#1, Aug 1 2003, 19:54:32)
>>> import sys
>>> sys.path.insert(0, '/tmp/example.zip')  # Add .zip file to front of path
>>> import jwzthreading
>>> jwzthreading.__file__
'/tmp/example.zip/jwzthreading.py'
>>>

Una entrada en sys.path puede ser ahora el nombre de un archivo ZIP. El archivo ZIP puede contener cualquier tipo de ficheros, pero sólo se pueden importar los ficheros llamados *.py, *.pyc, o *.pyo. Si un archivo sólo contiene ficheros *.py, Python no intentará modificar el archivo añadiendo el correspondiente fichero *.pyc, lo que significa que si un archivo ZIP no contiene ficheros *.pyc, la importación puede ser bastante lenta.

También se puede especificar una ruta dentro del archivo para importar sólo de un subdirectorio; por ejemplo, la ruta /tmp/example.zip/lib/ sólo importaría del subdirectorio lib/ dentro del archivo.

Ver también

PEP 273 [https://www.python.org/dev/peps/pep-0273] - Importación de módulos desde archivos Zip

Escrito por James C. Ahlstrom, que también proporcionó una implementación. Python 2.3 sigue la especificación en PEP 273 [https://www.python.org/dev/peps/pep-0273], pero utiliza una implementación escrita por Just van Rossum que utiliza los ganchos de importación descritos en PEP 302 [https://www.python.org/dev/peps/pep-0302]. Vea la sección PEP 302: Nuevos ganchos de importación para una descripción de los nuevos ganchos de importación.

PEP 277: Soporte de nombres de archivo Unicode para Windows NT

En Windows NT, 2000 y XP, el sistema almacena los nombres de archivo como cadenas Unicode. Tradicionalmente, Python ha representado los nombres de archivo como cadenas de bytes, lo cual es inadecuado porque hace que algunos nombres de archivo sean inaccesibles.

Python permite ahora utilizar cadenas Unicode arbitrarias (dentro de las limitaciones del sistema de archivos) para todas las funciones que esperan nombres de archivos, sobre todo la función incorporada open(). Si se pasa una cadena Unicode a os.listdir(), Python retorna ahora una lista de cadenas Unicode. Una nueva función, os.getcwdu(), retorna el directorio actual como una cadena Unicode.

Las cadenas de bytes siguen funcionando como nombres de archivo, y en Windows Python las convertirá de forma transparente a Unicode utilizando la codificación mbcs.

Otros sistemas también permiten cadenas Unicode como nombres de archivo, pero las convierten en cadenas de bytes antes de pasarlas al sistema, lo que puede provocar un UnicodeError. Las aplicaciones pueden comprobar si se admiten cadenas Unicode arbitrarias como nombres de archivo comprobando os.path.supports_unicode_filenames, un valor booleano.

En MacOS, os.listdir() ahora puede retornar nombres de archivo Unicode.

Ver también

PEP 277 [https://www.python.org/dev/peps/pep-0277] - Soporte de nombres de archivo Unicode para Windows NT

Escrito por Neil Hodgson; realizado por Neil Hodgson, Martin von Löwis y Mark Hammond.

PEP 278: Soporte universal de nuevas líneas

Los tres principales sistemas operativos que se utilizan hoy en día son Microsoft Windows, el sistema operativo Macintosh de Apple y los diversos derivados de Unix. Una pequeña molestia del trabajo entre plataformas es que estas tres plataformas utilizan diferentes caracteres para marcar el final de las líneas en los archivos de texto. Unix utiliza el salto de línea (carácter ASCII 10), MacOS utiliza el retorno de carro (carácter ASCII 13), y Windows utiliza una secuencia de dos caracteres de un retorno de carro más una nueva línea.

Los objetos de archivo de Python pueden ahora soportar convenciones de fin de línea distintas de la que sigue la plataforma en la que se ejecuta Python. Al abrir un archivo con el modo 'U o 'rU se abrirá un archivo para su lectura en modo universal newlines. Las tres convenciones de final de línea se traducirán a un '\n' en las cadenas retornadas por los distintos métodos de archivo como read() y readline().

El soporte universal de nuevas líneas también se utiliza al importar módulos y al ejecutar un archivo con la función execfile(). Esto significa que los módulos de Python pueden ser compartidos entre los tres sistemas operativos sin necesidad de convertir los finales de línea.

Esta función puede desactivarse al compilar Python especificando la opción --without-universal-newlines al ejecutar el script configure de Python.

Ver también

PEP 278 [https://www.python.org/dev/peps/pep-0278] - Soporte universal de nuevas líneas

Escrito y ejecutado por Jack Jansen.

PEP 279: enumerate()

Una nueva función incorporada, enumerate(), hará que ciertos bucles sean un poco más claros. enumerate(cosa), donde cosa es un iterador o una secuencia, retorna un iterador que retornará (0, cosa[0]), (1, cosa[1]), (2, cosa[2]), y así sucesivamente.

Un modismo común para cambiar cada elemento de una lista tiene el siguiente aspecto:

for i in range(len(L)):
    item = L[i]
    # ... compute some result based on item ...
    L[i] = result

Esto se puede reescribir usando enumerate() como:

for i, item in enumerate(L):
    # ... compute some result based on item ...
    L[i] = result

Ver también

PEP 279 [https://www.python.org/dev/peps/pep-0279] - La función incorporada enumerate()

Escrito y ejecutado por Raymond D. Hettinger.

PEP 282: El paquete de registro

Se ha añadido a Python 2.3 un paquete estándar para escribir registros, logging. Proporciona un mecanismo potente y flexible para generar salidas de registro que pueden ser filtradas y procesadas de varias maneras. Se puede utilizar un archivo de configuración escrito en un formato estándar para controlar el comportamiento de registro de un programa. Python incluye manejadores que escribirán los registros en el error estándar o en un archivo o socket, los enviarán al registro del sistema, o incluso los enviarán por correo electrónico a una dirección particular; por supuesto, también es posible escribir tus propias clases de manejadores.

La clase Logger es la clase principal. La mayoría del código de la aplicación tratará con uno o más objetos Logger, cada uno utilizado por un subsistema particular de la aplicación. Cada Logger se identifica con un nombre, y los nombres se organizan en una jerarquía utilizando . como separador de componentes. Por ejemplo, puedes tener instancias de Logger llamadas servidor, servidor.auth y servidor.network. Estas dos últimas instancias están por debajo de servidor en la jerarquía. Esto significa que si aumentas la verbosidad de servidor o diriges los mensajes de servidor a un gestor diferente, los cambios también se aplicarán a los registros de servidor.auth y servidor.network. También hay un Logger raíz que es el padre de todos los demás loggers.

Para usos sencillos, el paquete logging contiene algunas funciones de conveniencia que siempre utilizan la raíz log:

import logging

logging.debug('Debugging information')
logging.info('Informational message')
logging.warning('Warning:config file %s not found', 'server.conf')
logging.error('Error occurred')
logging.critical('Critical error -- shutting down')

Esto produce la siguiente salida:

WARNING:root:Warning:config file server.conf not found
ERROR:root:Error occurred
CRITICAL:root:Critical error -- shutting down

En la configuración por defecto, los mensajes informativos y de depuración se suprimen y la salida se envía al error estándar. Puede habilitar la visualización de mensajes informativos y de depuración llamando al método setLevel() del registrador raíz.

Observe que la llamada warning() utiliza operadores de formato de cadena; todas las funciones para el registro de mensajes toman los argumentos (msg, arg1, arg2, ...) y registran la cadena resultante de msg % (arg1, arg2, ...).

También hay una función exception() que registra el rastro más reciente. Cualquiera de las otras funciones también registrará el rastro si se especifica un valor verdadero para el argumento de la palabra clave exc_info.

def f():
    try:    1/0
    except: logging.exception('Problem recorded')

f()

Esto produce la siguiente salida:

ERROR:root:Problem recorded
Traceback (most recent call last):
  File "t.py", line 6, in f
    1/0
ZeroDivisionError: integer division or modulo by zero

Los programas un poco más avanzados utilizarán un logger distinto del logger raíz. La función getLogger(nombre) se utiliza para obtener un registro en particular, creándolo si aún no existe. getLogger(None) retorna el logger raíz.

log = logging.getLogger('server')
 ...
log.info('Listening on port %i', port)
 ...
log.critical('Disk full')
 ...

Los registros se suelen propagar hacia arriba en la jerarquía, por lo que un mensaje registrado en servidor.auth también es visto por servidor y root, pero un Logger puede evitar esto estableciendo su atributo propagate a False.

Hay más clases proporcionadas por el paquete logging que pueden ser personalizadas. Cuando una instancia de Logger recibe la orden de registrar un mensaje, crea una instancia de LogRecord que se envía a cualquier número de instancias de Handler diferentes. Los loggers y handlers también pueden tener una lista adjunta de filtros, y cada filtro puede hacer que el LogRecord sea ignorado o puede modificar el registro antes de pasarlo. Cuando finalmente se emiten, las instancias de LogRecord se convierten en texto mediante una clase Formatter. Todas estas clases pueden ser reemplazadas por tus propias clases especialmente escritas.

Con todas estas características, el paquete logging debería proporcionar suficiente flexibilidad incluso para las aplicaciones más complicadas. Esto es sólo un resumen incompleto de sus características, así que por favor consulte la documentación de referencia del paquete para todos los detalles. La lectura de PEP 282 [https://www.python.org/dev/peps/pep-0282] también será útil.

Ver también

PEP 282 [https://www.python.org/dev/peps/pep-0282] - Un sistema de registro

Escrito por Vinay Sajip y Trent Mick; implementado por Vinay Sajip.

PEP 285: Un tipo booleano

Se ha añadido un tipo booleano a Python 2.3. Se añadieron dos nuevas constantes al módulo __builtin__, True y False. (Las constantes True y False se añadieron a los módulos incorporados en Python 2.2.1, pero las versiones de 2.2.1 se ajustan simplemente a valores enteros de 1 y 0 y no son un tipo diferente)

El objeto de tipo para este nuevo tipo se denomina bool; su constructor toma cualquier valor de Python y lo convierte en True o False.

>>> bool(1)
True
>>> bool(0)
False
>>> bool([])
False
>>> bool( (1,) )
True

La mayoría de los módulos de la biblioteca estándar y las funciones incorporadas se han modificado para retornar booleanos.

>>> obj = []
>>> hasattr(obj, 'append')
True
>>> isinstance(obj, list)
True
>>> isinstance(obj, tuple)
False

Los booleanos de Python se añadieron con el objetivo principal de hacer el código más claro. Por ejemplo, si estás leyendo una función y te encuentras con la sentencia return 1, podrías preguntarte si el 1 representa un valor de verdad booleano, un índice o un coeficiente que multiplica alguna otra cantidad. Sin embargo, si la sentencia es return True, el significado del valor de retorno es bastante claro.

Los booleanos de Python no se añadieron en aras de una comprobación de tipos estricta. Un lenguaje muy estricto como Pascal también le impediría realizar aritmética con booleanos, y requeriría que la expresión en una declaración if siempre se evaluara a un resultado booleano. Python no es tan estricto y nunca lo será, como dice explícitamente PEP 285 [https://www.python.org/dev/peps/pep-0285]. Esto significa que puede utilizar cualquier expresión en una sentencia if, incluso las que se evalúan a una lista o tupla o algún objeto aleatorio. El tipo Booleano es una subclase de la clase int por lo que la aritmética que utiliza un Booleano sigue funcionando.

>>> True + 1
2
>>> False + 1
1
>>> False * 75
0
>>> True * 75
75

Para resumir True and False en una frase: son formas alternativas de deletrear los valores enteros 1 y 0, con la única diferencia de que str() y repr() retornan las cadenas Verdadero y Falso en lugar de 1 y 0.

Ver también

PEP 285 [https://www.python.org/dev/peps/pep-0285] - Añadir un tipo booleano

Escrito y ejecutado por GvR.

PEP 293: Llamadas de retorno para el manejo de errores del códec

Al codificar una cadena Unicode en una cadena de bytes, pueden encontrarse caracteres no codificables. Hasta ahora, Python ha permitido especificar el procesamiento del error como «estricto» (lanzando UnicodeError), «ignorar» (saltando el carácter), o «reemplazar» (usando un signo de interrogación en la cadena de salida), siendo «estricto» el comportamiento por defecto. Puede ser deseable especificar un procesamiento alternativo de tales errores, como insertar una referencia de carácter XML o una referencia de entidad HTML en la cadena convertida.

Python tiene ahora un marco flexible para añadir diferentes estrategias de procesamiento. Se pueden añadir nuevos manejadores de errores con codecs.register_error(), y los códecs pueden acceder al manejador de errores con codecs.lookup_error(). Se ha añadido una API en C equivalente para los códecs escritos en C. El gestor de errores obtiene la información de estado necesaria, como la cadena que se está convirtiendo, la posición en la cadena donde se ha detectado el error y la codificación de destino. El controlador puede entonces lanzar una excepción o retornar una cadena de reemplazo.

Se han implementado dos manejadores de error adicionales utilizando este marco: «backslashreplace» utiliza las comillas de barra invertida de Python para representar los caracteres no codificables y «xmlcharrefreplace» emite referencias de caracteres XML.

Ver también

PEP 293 [https://www.python.org/dev/peps/pep-0293] - Retrollamadas de manejo de errores del códec

Escrito y ejecutado por Walter Dörwald.

PEP 301: Índice de paquetes y metadatos para Distutils

La compatibilidad con el catálogo de Python, largamente solicitada, hace su primera aparición en 2.3.

El corazón del catálogo es el nuevo comando register de Distutils. Ejecutando python setup.py register se recogen los metadatos que describen un paquete, como su nombre, versión, mantenedor, descripción, etc., y se envían a un servidor de catálogo central. El catálogo resultante está disponible en https://pypi.org.

Para hacer el catálogo un poco más útil, se ha añadido un nuevo argumento opcional de palabra clave clasificadores a la función Distutils setup(). Se puede suministrar una lista de cadenas de estilo Trove [http://catb.org/~esr/trove/] para ayudar a clasificar el software.

Aquí hay un ejemplo setup.py con clasificadores, escrito para que sea compatible con las versiones más antiguas de Distutils:

from distutils import core
kw = {'name': "Quixote",
      'version': "0.5.1",
      'description': "A highly Pythonic Web application framework",
      # ...
      }

if (hasattr(core, 'setup_keywords') and
    'classifiers' in core.setup_keywords):
    kw['classifiers'] = \
        ['Topic :: Internet :: WWW/HTTP :: Dynamic Content',
         'Environment :: No Input/Output (Daemon)',
         'Intended Audience :: Developers'],

core.setup(**kw)

La lista completa de clasificadores se puede obtener ejecutando python setup.py register --list-classifiers.

Ver también

PEP 301 [https://www.python.org/dev/peps/pep-0301] - Índice de paquetes y metadatos para Distutils

Escrito y ejecutado por Richard Jones.

PEP 302: Nuevos ganchos de importación

Aunque ha sido posible escribir ganchos de importación personalizados desde que se introdujo el módulo ihooks en Python 1.3, nadie ha estado nunca realmente contento con él porque escribir nuevos ganchos de importación es difícil y complicado. Se han propuesto varias alternativas, como los módulos imputil y iu, pero ninguno de ellos ha tenido mucha aceptación, y ninguno era fácilmente utilizable desde el código C.

PEP 302 [https://www.python.org/dev/peps/pep-0302] toma prestadas ideas de sus predecesores, especialmente del módulo iu de Gordon McMillan. Se añaden tres nuevos elementos al módulo sys:

sys.path_hooks es una lista de objetos invocables; la mayoría de las veces serán clases. Cada llamada toma una cadena que contiene una ruta y retorna un objeto importador que manejará las importaciones desde esta ruta o lanza una excepción ImportError si no puede manejar esta ruta.

sys.path_importer_cache almacena en caché los objetos del importador para cada ruta, por lo que sys.path_hooks sólo tendrá que ser recorrido una vez para cada ruta.

sys.meta_path es una lista de objetos importadores que se recorrerán antes de comprobar sys.path. Esta lista está inicialmente vacía, pero el código de usuario puede añadir objetos a ella. Los módulos adicionales incorporados y congelados pueden ser importados por un objeto añadido a esta lista.

Los objetos importadores deben tener un único método, find_module(fullname, path=None). fullname será un nombre de módulo o paquete, por ejemplo string o distutils.core. find_module() debe retornar un objeto cargador que tenga un único método, load_module(fullname), que cree y retorne el objeto módulo correspondiente.

Por lo tanto, el pseudocódigo de la nueva lógica de importación de Python es algo así (simplificado un poco; véase PEP 302 [https://www.python.org/dev/peps/pep-0302] para los detalles completos):

for mp in sys.meta_path:
    loader = mp(fullname)
    if loader is not None:
        <module> = loader.load_module(fullname)

for path in sys.path:
    for hook in sys.path_hooks:
        try:
            importer = hook(path)
        except ImportError:
            # ImportError, so try the other path hooks
            pass
        else:
            loader = importer.find_module(fullname)
            <module> = loader.load_module(fullname)

# Not found!
raise ImportError

Ver también

PEP 302 [https://www.python.org/dev/peps/pep-0302] - Nuevos ganchos de importación

Escrito por Just van Rossum y Paul Moore. Implementado por Just van Rossum.

PEP 305: Archivos separados por comas

Los archivos separados por comas son un formato frecuentemente utilizado para exportar datos de bases de datos y hojas de cálculo. Python 2.3 añade un analizador de archivos separados por comas.

El formato separado por comas es engañosamente sencillo a primera vista:

Costs,150,200,3.95

Leer una línea y llamar a line.split(','): ¿qué puede ser más sencillo? Pero si se añaden datos de cadena que pueden contener comas, las cosas se complican:

"Costs",150,200,3.95,"Includes taxes, shipping, and sundry items"

Una expresión regular grande y fea puede analizar esto, pero usar el nuevo paquete csv es mucho más sencillo:

import csv

input = open('datafile', 'rb')
reader = csv.reader(input)
for line in reader:
    print line

La función reader() admite varias opciones. El separador de campos no se limita a la coma y puede cambiarse por cualquier carácter, al igual que las comillas y el final de línea.

Se pueden definir y registrar diferentes dialectos de archivos separados por comas; actualmente hay dos dialectos, ambos utilizados por Microsoft Excel. Una clase csv.writer independiente generará archivos separados por comas a partir de una sucesión de tuplas o listas, citando cadenas que contengan el delimitador.

Ver también

PEP 305 [https://www.python.org/dev/peps/pep-0305] - API de archivos CSV

Escrito y realizado por Kevin Altis, Dave Cole, Andrew McNamara, Skip Montanaro, Cliff Wells.

PEP 307: Mejoras en Pickle

Los módulos pickle y cPickle recibieron cierta atención durante el ciclo de desarrollo de la 2.3. En 2.2, las clases de estilo nuevo podían ser desempaquetadas sin dificultad, pero no se desempaquetaba de forma muy compacta; PEP 307 [https://www.python.org/dev/peps/pep-0307] cita un ejemplo trivial en el que una clase de estilo nuevo da lugar a una cadena desempaquetada tres veces más larga que la de una clase clásica.

La solución fue inventar un nuevo protocolo pickle. La función pickle.dumps() soporta desde hace tiempo una bandera de texto o binario. En la versión 2.3, esta bandera se ha redefinido, pasando de ser un booleano a un entero: 0 es el antiguo formato pickle en modo texto, 1 es el antiguo formato binario, y ahora 2 es un nuevo formato específico de 2.3. Una nueva constante, pickle.HIGHEST_PROTOCOL, puede utilizarse para seleccionar el protocolo más elegante disponible.

El unpickling ya no se considera una operación segura. El pickle de la versión 2.2 proporcionaba ganchos para tratar de evitar que las clases no seguras fueran deserializadas (específicamente, un atributo __safe_for_unpickling__), pero nada de este código fue nunca auditado y por lo tanto todo ha sido eliminado en la versión 2.3. No se debe deserializar datos no confiables en ninguna versión de Python.

Para reducir la sobrecarga de pickling de las clases de estilo nuevo, se ha añadido una nueva interfaz para personalizar el pickling mediante tres métodos especiales: __getstate__(), __setstate__(), y __getnewargs__(). Consulte PEP 307 [https://www.python.org/dev/peps/pep-0307] para conocer la semántica completa de estos métodos.

Como forma de comprimir aún más los pickles, ahora es posible utilizar códigos enteros en lugar de cadenas largas para identificar las clases serializadas. La Python Software Foundation mantendrá una lista de códigos estandarizados; también hay una gama de códigos para uso privado. Actualmente no se ha especificado ningún código.

Ver también

PEP 307 [https://www.python.org/dev/peps/pep-0307] - Extensiones del protocolo pickle

Escrito y ejecutado por Guido van Rossum y Tim Peters.

Rebanadas ampliadas

Desde la versión 1.4 de Python, la sintaxis de corte admite un tercer argumento opcional «paso» o «zancada». Por ejemplo, estas son todas las sintaxis legales de Python: L[1:10:2], L[:-1:1], L[::-1]. Esto se añadió a Python a petición de los desarrolladores de Numerical Python, que utiliza ampliamente el tercer argumento. Sin embargo, los tipos de secuencias de listas, tuplas y cadenas incorporados en Python nunca han soportado esta característica, y lanzan un TypeError si lo intentas. Michael Hudson ha contribuido con un parche para solucionar este problema.

Por ejemplo, ahora puede extraer fácilmente los elementos de una lista que tengan índices pares:

>>> L = range(10)
>>> L[::2]
[0, 2, 4, 6, 8]

Los valores negativos también sirven para hacer una copia de la misma lista en orden inverso:

>>> L[::-1]
[9, 8, 7, 6, 5, 4, 3, 2, 1, 0]

Esto también funciona para tuplas, arrays y cadenas:

>>> s='abcd'
>>> s[::2]
'ac'
>>> s[::-1]
'dcba'

Si tienes una secuencia mutable, como una lista o un array, puedes asignar o eliminar una rebanada extendida, pero hay algunas diferencias entre la asignación a rebanadas extendidas y regulares. La asignación a una rebanada regular se puede utilizar para cambiar la longitud de la secuencia:

>>> a = range(3)
>>> a
[0, 1, 2]
>>> a[1:3] = [4, 5, 6]
>>> a
[0, 4, 5, 6]

Las rebanadas extendidas no son tan flexibles. Cuando se asigna a una rebanada extendida, la lista a la derecha de la declaración debe contener el mismo número de elementos que la rebanada que está reemplazando:

>>> a = range(4)
>>> a
[0, 1, 2, 3]
>>> a[::2]
[0, 2]
>>> a[::2] = [0, -1]
>>> a
[0, 1, -1, 3]
>>> a[::2] = [0,1,2]
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
ValueError: attempt to assign sequence of size 3 to extended slice of size 2

La eliminación es más sencilla:

>>> a = range(4)
>>> a
[0, 1, 2, 3]
>>> a[::2]
[0, 2]
>>> del a[::2]
>>> a
[1, 3]

Ahora también se pueden pasar objetos slice a los métodos __getitem__() de las secuencias incorporadas:

>>> range(10).__getitem__(slice(0, 5, 2))
[0, 2, 4]

O utilizar los objetos de corte directamente en los subíndices:

>>> range(10)[slice(0, 5, 2)]
[0, 2, 4]

Para simplificar la implementación de secuencias que soportan el corte extendido, los objetos slice tienen ahora un método indices(length) que, dada la longitud de una secuencia, retorna una tupla (start, stop, step) que puede pasarse directamente a range(). indices() maneja los índices omitidos y los que están fuera de los límites de una manera consistente con los slices regulares (¡y esta frase inocua esconde un montón de detalles confusos!). El método está pensado para ser utilizado así:

class FakeSeq:
    ...
    def calc_item(self, i):
        ...
    def __getitem__(self, item):
        if isinstance(item, slice):
            indices = item.indices(len(self))
            return FakeSeq([self.calc_item(i) for i in range(*indices)])
        else:
            return self.calc_item(i)

En este ejemplo también se puede ver que el objeto incorporado slice es ahora el objeto tipo para el tipo slice, y ya no es una función. Esto es consistente con Python 2.2, donde int, str, etc., sufrieron el mismo cambio.

Otros cambios en el lenguaje

Estos son todos los cambios que Python 2.3 introduce en el núcleo del lenguaje Python.

La expresión yield es ahora siempre una palabra clave, como se describe en la sección PEP 255: Generadores simples de este documento.

Se ha añadido una nueva función incorporada enumerate(), como se describe en la sección PEP 279: enumerate() de este documento.

Se han añadido dos nuevas constantes, True y False junto con el tipo incorporado bool, como se describe en la sección PEP 285: Un tipo booleano de este documento.

El constructor de tipo int() ahora retornará un entero largo en lugar de lanzar un OverflowError cuando una cadena o un número de punto flotante es demasiado grande para caber en un entero. Esto puede llevar al resultado paradójico de que isinstance(int(expresión), int) sea falso, pero parece poco probable que cause problemas en la práctica.

Los tipos incorporados ahora soportan la sintaxis de rebanado extendida, como se describe en la sección Rebanadas ampliadas de este documento.

Una nueva función incorporada, suma(iterable, start=0), suma los elementos numéricos en el objeto iterable y retorna su suma. suma() sólo acepta números, lo que significa que no se puede utilizar para concatenar un montón de cadenas. (Contribución de Alex Martelli)

list.insert(pos, valor) solía insertar valor al principio de la lista cuando pos era negativo. El comportamiento ha sido cambiado para ser consistente con la indexación de las rebanadas, así que cuando pos es -1 el valor será insertado antes del último elemento, y así sucesivamente.

list.index(value), que busca valor dentro de la lista y retorna su índice, ahora toma los argumentos opcionales start y stop para limitar la búsqueda sólo a una parte de la lista.

Los diccionarios tienen un nuevo método, pop(key[, *default*]), que retorna el valor correspondiente a key y elimina ese par clave/valor del diccionario. Si la clave solicitada no está presente en el diccionario, se retorna default si está especificada y se lanza KeyError si no lo está:

>>> d = {1:2}
>>> d
{1: 2}
>>> d.pop(4)
Traceback (most recent call last):
  File "stdin", line 1, in ?
KeyError: 4
>>> d.pop(1)
2
>>> d.pop(1)
Traceback (most recent call last):
  File "stdin", line 1, in ?
KeyError: 'pop(): dictionary is empty'
>>> d
{}
>>>

También hay un nuevo método de clase, dict.fromkeys(iterable, value), que crea un diccionario con claves tomadas del iterador iterable suministrado y todos los valores establecidos a value, por defecto a None.

(Parches aportados por Raymond Hettinger)

Además, el constructor dict() ahora acepta argumentos de palabras clave para simplificar la creación de pequeños diccionarios:

>>> dict(red=1, blue=2, green=3, black=4)
{'blue': 2, 'black': 4, 'green': 3, 'red': 1}

(Contribución de Just van Rossum.)

La expresión assert ya no comprueba la bandera debug__, por lo que ya no se pueden desactivar las aserciones asignando a __debug__. Ejecutar Python con la opción -O seguirá generando código que no ejecute ninguna aserción.

La mayoría de los objetos de tipo son ahora invocables, por lo que puedes usarlos para crear nuevos objetos como funciones, clases y módulos. (Esto significa que el módulo new puede quedar obsoleto en una futura versión de Python, porque ahora puedes utilizar los objetos de tipo disponibles en el módulo types) Por ejemplo, puede crear un nuevo objeto de módulo con el siguiente código:

>>> import types
>>> m = types.ModuleType('abc','docstring')
>>> m
<module 'abc' (built-in)>
>>> m.__doc__
'docstring'

Se ha añadido una nueva advertencia, PendingDeprecationWarning para indicar las características que están en proceso de ser obsoletas. La advertencia no se imprimirá por defecto. Para comprobar el uso de funciones que quedarán obsoletas en el futuro, proporcione -Walways::PendingDeprecationWarning:: en la línea de comandos o utilice warnings.filterwarnings().

Ha comenzado el proceso de desaprobación de las excepciones basadas en cadenas, como en lanzamiento de "Error ocurred”. Al lanzar una cadena, ahora se activará PendingDeprecationWarning.

El uso de None como nombre de una variable ahora resultará en una advertencia SyntaxWarning. En una futura versión de Python, None podría convertirse en una palabra clave.

El método xreadlines() de los objetos archivo, introducido en Python 2.1, ya no es necesario porque los archivos se comportan ahora como su propio iterador. xreadlines() se introdujo originalmente como una forma más rápida de recorrer todas las líneas de un archivo, pero ahora se puede escribir simplemente for line in file_obj. Los objetos archivo también tienen un nuevo atributo encoding de sólo lectura que proporciona la codificación utilizada por el archivo; las cadenas Unicode escritas en el archivo se convertirán automáticamente a bytes utilizando la codificación dada.

El orden de resolución de los métodos utilizados por las clases del nuevo estilo ha cambiado, aunque sólo notarás la diferencia si tienes una jerarquía de herencia realmente complicada. Las clases clásicas no se ven afectadas por este cambio. Python 2.2 originalmente utilizaba una ordenación topológica de los ancestros de una clase, pero 2.3 ahora utiliza el algoritmo C3 como se describe en el artículo «A Monotonic Superclass Linearization for Dylan» [http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.19.3910]. Para entender la motivación de este cambio, lea el artículo de Michele Simionato «Python 2.3 Method Resolution Order» [http://www.phyast.pitt.edu/~micheles/mro.html], o lea el hilo en python-dev que comienza con el mensaje en https://mail.python.org/pipermail/python-dev/2002-October/029035.html. Samuele Pedroni fue el primero en señalar el problema y también implementó la solución codificando el algoritmo C3.

Python ejecuta programas multihilo cambiando entre hilos después de ejecutar N bytecodes. El valor por defecto de N se ha incrementado de 10 a 100 bytecodes, acelerando las aplicaciones de un solo hilo al reducir la sobrecarga de cambio. Algunas aplicaciones multihilo pueden sufrir un tiempo de respuesta más lento, pero eso se arregla fácilmente estableciendo el límite a un número menor usando sys.setcheckinterval(N). El límite puede recuperarse con la nueva función sys.getcheckinterval().

Un cambio menor pero de gran alcance es que los nombres de los tipos de extensión definidos por los módulos incluidos con Python ahora contienen el módulo y un .' delante del nombre del tipo. Por ejemplo, en Python 2.2, si creabas un socket e imprimías su __class__, obtendrías esta salida:

>>> s = socket.socket()
>>> s.__class__
<type 'socket'>

En 2.3, se obtiene esto:

>>> s.__class__
<type '_socket.socket'>

Se ha eliminado una de las incompatibilidades señaladas entre las clases de estilo antiguo y las de estilo nuevo: ahora se pueden asignar a los atributos __name__ y __bases__ de las clases de estilo nuevo. Hay algunas restricciones sobre lo que se puede asignar a __bases__ en la línea de las relacionadas con la asignación al atributo __class__ de una instancia.

Cambios en las cadenas de texto

El operador in ahora funciona de forma diferente para las cadenas. Antes, cuando se evaluaba X en Y donde X y Y eran cadenas, X sólo podía ser un único carácter. Esto ha cambiado; X puede ser una cadena de cualquier longitud, y X en Y retornará True si X es una subcadena de Y. Si X es una cadena vacía, el resultado es siempre True.

>>> 'ab' in 'abcd'
True
>>> 'ad' in 'abcd'
False
>>> '' in 'abcd'
True

Tenga en cuenta que esto no le dice dónde empieza la subcadena; si necesita esa información, utilice el método find() string.

Los métodos de cadena strip(), lstrip() y rstrip() tienen ahora un argumento opcional para especificar los caracteres a eliminar. El valor por defecto sigue siendo eliminar todos los caracteres de espacio en blanco:

>>> '   abc '.strip()
'abc'
>>> '><><abc<><><>'.strip('<>')
'abc'
>>> '><><abc<><><>\n'.strip('<>')
'abc<><><>\n'
>>> u'\u4000\u4001abc\u4000'.strip(u'\u4000')
u'\u4001abc'
>>>

(Sugerido por Simon Brunning y aplicado por Walter Dörwald)

Los métodos de cadena startswith() y endswith() ahora aceptan números negativos para los parámetros start y end.

Otro nuevo método de cadena es zfill(), originalmente una función del módulo string. zfill() rellena una cadena numérica con ceros a la izquierda hasta que tenga el ancho especificado. Tenga en cuenta que el operador % sigue siendo más flexible y potente que zfill().

>>> '45'.zfill(4)
'0045'
>>> '12345'.zfill(4)
'12345'
>>> 'goofy'.zfill(6)
'0goofy'

(Contribución de Walter Dörwald.)

Se ha añadido un nuevo tipo de objeto, basestring. Tanto las cadenas de 8 bits como las cadenas Unicode heredan de este tipo, por lo que isinstance(obj, basestring) retornará True para cualquier tipo de cadena. Es un tipo completamente abstracto, por lo que no se pueden crear instancias de basestring.

Las cadenas internas ya no son inmortales y ahora serán recolectadas de la forma habitual cuando la única referencia a ellas sea desde el diccionario interno de cadenas internas. (Implementado por Oren Tirosh)

Optimizaciones

La creación de instancias de clases de estilo nuevo se ha hecho mucho más rápida; ¡ahora son más rápidas que las clases clásicas!

El método sort() de los objetos de la lista ha sido ampliamente reescrito por Tim Peters, y la implementación es significativamente más rápida.

La multiplicación de enteros largos es ahora mucho más rápida gracias a una implementación de la multiplicación Karatsuba, un algoritmo que escala mejor que el O(n*n) requerido para el algoritmo de multiplicación de la escuela primaria. (Parche original de Christopher A. Craig, y reelaborado significativamente por Tim Peters)

El opcode SET_LINENO ha desaparecido. Esto puede proporcionar un pequeño aumento de velocidad, dependiendo de la idiosincrasia de su compilador. Vea la sección Other Changes and Fixes para una explicación más larga. (Eliminado por Michael Hudson)

Los objetos xrange() tienen ahora su propio iterador, haciendo que for i in xrange(n) sea ligeramente más rápido que for i in range(n). (Parche de Raymond Hettinger)

Se han realizado una serie de pequeños reajustes en varios puntos conflictivos para mejorar el rendimiento, como por ejemplo alinear una función o eliminar algo de código. (Implementado principalmente por GvR, pero mucha gente ha contribuido con cambios individuales)

El resultado neto de las optimizaciones de la versión 2.3 es que Python 2.3 ejecuta el benchmark pystone alrededor de un 25% f más rápido que Python 2.2.

Módulos nuevos, mejorados y obsoletos

Como es habitual, la biblioteca estándar de Python ha recibido una serie de mejoras y correcciones de errores. Aquí hay una lista parcial de los cambios más notables, ordenados alfabéticamente por nombre de módulo. Consulte el archivo Misc/NEWS en el árbol de fuentes para obtener una lista más completa de los cambios, o busque en los registros de CVS para obtener todos los detalles.

El módulo array soporta ahora matrices de caracteres Unicode que utilizan el carácter de formato 'u. Las matrices también soportan ahora el uso del operador de asignación += para añadir el contenido de otra matriz, y el operador de asignación *= para repetir una matriz. (Contribución de Jason Orendorff)

El módulo bsddb ha sido reemplazado por la versión 4.1.6 del paquete PyBSDDB [http://pybsddb.sourceforge.net], proporcionando una interfaz más completa para las características transaccionales de la biblioteca BerkeleyDB.

La antigua versión del módulo ha sido renombrada como bsddb185 y ya no se construye automáticamente; tendrás que editar Modules/Setup para activarlo. Ten en cuenta que el nuevo paquete bsddb está pensado para ser compatible con el módulo antiguo, así que asegúrate de enviar errores si descubres alguna incompatibilidad. Al actualizar a Python 2.3, si el nuevo intérprete se compila con una nueva versión de la biblioteca BerkeleyDB subyacente, es casi seguro que tendrá que convertir sus archivos de base de datos a la nueva versión. Puede hacerlo fácilmente con los nuevos scripts db2pickle.py y pickle2db.py que encontrará en el directorio Tools/scripts de la distribución. Si ya ha estado utilizando el paquete PyBSDDB e importándolo como bsddb3, tendrá que cambiar sus sentencias import para importarlo como bsddb.

El nuevo módulo bz2 es una interfaz para la biblioteca de compresión de datos bz2. Los datos comprimidos con bz2 suelen ser más pequeños que los correspondientes datos comprimidos con zlib. (Contribución de Gustavo Niemeyer)

Se ha añadido un conjunto de tipos de fecha/hora estándar en el nuevo módulo datetime. Consulte la siguiente sección para obtener más detalles.

La clase Distutils Extension soporta ahora un argumento constructor extra llamado depends para listar archivos fuente adicionales de los que depende una extensión. Esto permite a Distutils recompilar el módulo si se modifica alguno de los archivos de dependencia. Por ejemplo, si sampmodule.c incluye el fichero de cabecera sample.h, se crearía el objeto Extension así:

ext = Extension("samp",
                sources=["sampmodule.c"],
                depends=["sample.h"])

La modificación de sample.h haría que el módulo se recompilara. (Contribución de Jeremy Hylton)

Otros cambios menores en Distutils: ahora comprueba las variables de entorno CC, CFLAGS, CPP, LDFLAGS y CPPFLAGS, utilizándolas para anular los ajustes de la configuración de Python (contribución de Robert Weber).

Anteriormente el módulo doctest sólo buscaba casos de prueba en los docstrings de los métodos y funciones públicos, pero ahora también examina los privados. La función DocTestSuite() crea un objeto unittest.TestSuite a partir de un conjunto de pruebas doctest.

La nueva función gc.get_referents(object) retorna una lista de todos los objetos referenciados por object.

El módulo getopt ha ganado una nueva función, gnu_getopt(), que admite los mismos argumentos que la función getopt() existente, pero utiliza el modo de exploración al estilo GNU. La función getopt() existente deja de procesar las opciones tan pronto como se encuentra un argumento que no es una opción, pero en el modo GNU el procesamiento continúa, lo que significa que las opciones y los argumentos pueden mezclarse. Por ejemplo:

>>> getopt.getopt(['-f', 'filename', 'output', '-v'], 'f:v')
([('-f', 'filename')], ['output', '-v'])
>>> getopt.gnu_getopt(['-f', 'filename', 'output', '-v'], 'f:v')
([('-f', 'filename'), ('-v', '')], ['output'])

(Contribución de Peter Åstrand.)

Los módulos grp, pwd y resource retornan ahora tuplas mejoradas:

>>> import grp
>>> g = grp.getgrnam('amk')
>>> g.gr_name, g.gr_gid
('amk', 500)

El módulo gzip ahora puede manejar archivos de más de 2 GiB.

El nuevo módulo heapq contiene una implementación de un algoritmo de colas de montón. Un montón es una estructura de datos similar a un array que mantiene los elementos en un orden parcialmente ordenado de forma que, para cada índice k, heap[k] <= heap[2*k+1] y heap[k] <= heap[2*k+2]. Esto hace que sea rápido eliminar el elemento más pequeño, y la inserción de un nuevo elemento manteniendo la propiedad del montón es O(lg n). (Véase https://xlinux.nist.gov/dads//HTML/priorityque.html para más información sobre la estructura de datos de la cola de prioridad)

El módulo heapq proporciona las funciones heappush() y heappop() para añadir y eliminar elementos manteniendo la propiedad del montón sobre algún otro tipo de secuencia mutable de Python. Aquí hay un ejemplo que utiliza una lista de Python:

>>> import heapq
>>> heap = []
>>> for item in [3, 7, 5, 11, 1]:
...    heapq.heappush(heap, item)
...
>>> heap
[1, 3, 5, 11, 7]
>>> heapq.heappop(heap)
1
>>> heapq.heappop(heap)
3
>>> heap
[5, 7, 11]

(Contribución de Kevin O’Connor.)

El entorno de desarrollo integrado IDLE ha sido actualizado utilizando el código del proyecto IDLEfork (http://idlefork.sourceforge.net). La característica más notable es que el código que se está desarrollando se ejecuta ahora en un subproceso, lo que significa que ya no es necesario realizar operaciones manuales de reload(). El código central de IDLE ha sido incorporado a la biblioteca estándar como el paquete idlelib.

The imaplib module now supports IMAP over SSL. (Contributed by Piers Lauder and Tino Lange.)

The itertools contains a number of useful functions for use with iterators, inspired by various functions provided by the ML and Haskell languages. For example, itertools.ifilter(predicate, iterator) returns all elements in the iterator for which the function predicate() returns True, and itertools.repeat(obj, N) returns obj N times. There are a number of other functions in the module; see the package’s reference documentation for details. (Contributed by Raymond Hettinger.)

Two new functions in the math module, degrees(rads) and radians(degs), convert between radians and degrees. Other functions in the math module such as math.sin() and math.cos() have always required input values measured in radians. Also, an optional base argument was added to math.log() to make it easier to compute logarithms for bases other than e and 10. (Contributed by Raymond Hettinger.)

Several new POSIX functions (getpgid(), killpg(), lchown(), loadavg(), major(), makedev(), minor(), and mknod()) were added to the posix module that underlies the os module. (Contributed by Gustavo Niemeyer, Geert Jansen, and Denis S. Otkidach.)

In the os module, the *stat() family of functions can now report fractions of a second in a timestamp. Such time stamps are represented as floats, similar to the value returned by time.time().

During testing, it was found that some applications will break if time stamps are floats. For compatibility, when using the tuple interface of the stat_result time stamps will be represented as integers. When using named fields (a feature first introduced in Python 2.2), time stamps are still represented as integers, unless os.stat_float_times() is invoked to enable float return values:

>>> os.stat("/tmp").st_mtime
1034791200
>>> os.stat_float_times(True)
>>> os.stat("/tmp").st_mtime
1034791200.6335014

In Python 2.4, the default will change to always returning floats.

Application developers should enable this feature only if all their libraries work properly when confronted with floating point time stamps, or if they use the tuple API. If used, the feature should be activated on an application level instead of trying to enable it on a per-use basis.

The optparse module contains a new parser for command-line arguments that can convert option values to a particular Python type and will automatically generate a usage message. See the following section for more details.

The old and never-documented linuxaudiodev module has been deprecated, and a new version named ossaudiodev has been added. The module was renamed because the OSS sound drivers can be used on platforms other than Linux, and the interface has also been tidied and brought up to date in various ways. (Contributed by Greg Ward and Nicholas FitzRoy-Dale.)

The new platform module contains a number of functions that try to determine various properties of the platform you’re running on. There are functions for getting the architecture, CPU type, the Windows OS version, and even the Linux distribution version. (Contributed by Marc-André Lemburg.)

The parser objects provided by the pyexpat module can now optionally buffer character data, resulting in fewer calls to your character data handler and therefore faster performance. Setting the parser object’s buffer_text attribute to True will enable buffering.

The sample(population, k) function was added to the random module. population is a sequence or xrange object containing the elements of a population, and sample() chooses k elements from the population without replacing chosen elements. k can be any value up to len(population). For example:

>>> days = ['Mo', 'Tu', 'We', 'Th', 'Fr', 'St', 'Sn']
>>> random.sample(days, 3)      # Choose 3 elements
['St', 'Sn', 'Th']
>>> random.sample(days, 7)      # Choose 7 elements
['Tu', 'Th', 'Mo', 'We', 'St', 'Fr', 'Sn']
>>> random.sample(days, 7)      # Choose 7 again
['We', 'Mo', 'Sn', 'Fr', 'Tu', 'St', 'Th']
>>> random.sample(days, 8)      # Can't choose eight
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
  File "random.py", line 414, in sample
      raise ValueError, "sample larger than population"
ValueError: sample larger than population
>>> random.sample(xrange(1,10000,2), 10)   # Choose ten odd nos. under 10000
[3407, 3805, 1505, 7023, 2401, 2267, 9733, 3151, 8083, 9195]

The random module now uses a new algorithm, the Mersenne Twister, implemented in C. It’s faster and more extensively studied than the previous algorithm.

(All changes contributed by Raymond Hettinger.)

The readline module also gained a number of new functions: get_history_item(), get_current_history_length(), and redisplay().

The rexec and Bastion modules have been declared dead, and attempts to import them will fail with a RuntimeError. New-style classes provide new ways to break out of the restricted execution environment provided by rexec, and no one has interest in fixing them or time to do so. If you have applications using rexec, rewrite them to use something else.

(Sticking with Python 2.2 or 2.1 will not make your applications any safer because there are known bugs in the rexec module in those versions. To repeat: if you’re using rexec, stop using it immediately.)

The rotor module has been deprecated because the algorithm it uses for encryption is not believed to be secure. If you need encryption, use one of the several AES Python modules that are available separately.

The shutil module gained a move(src, dest) function that recursively moves a file or directory to a new location.

Support for more advanced POSIX signal handling was added to the signal but then removed again as it proved impossible to make it work reliably across platforms.

The socket module now supports timeouts. You can call the settimeout(t) method on a socket object to set a timeout of t seconds. Subsequent socket operations that take longer than t seconds to complete will abort and raise a socket.timeout exception.

The original timeout implementation was by Tim O’Malley. Michael Gilfix integrated it into the Python socket module and shepherded it through a lengthy review. After the code was checked in, Guido van Rossum rewrote parts of it. (This is a good example of a collaborative development process in action.)

On Windows, the socket module now ships with Secure Sockets Layer (SSL) support.

The value of the C PYTHON_API_VERSION macro is now exposed at the Python level as sys.api_version. The current exception can be cleared by calling the new sys.exc_clear() function.

The new tarfile module allows reading from and writing to tar-format archive files. (Contributed by Lars Gustäbel.)

The new textwrap module contains functions for wrapping strings containing paragraphs of text. The wrap(text, width) function takes a string and returns a list containing the text split into lines of no more than the chosen width. The fill(text, width) function returns a single string, reformatted to fit into lines no longer than the chosen width. (As you can guess, fill() is built on top of wrap(). For example:

>>> import textwrap
>>> paragraph = "Not a whit, we defy augury: ... more text ..."
>>> textwrap.wrap(paragraph, 60)
["Not a whit, we defy augury: there's a special providence in",
 "the fall of a sparrow. If it be now, 'tis not to come; if it",
 ...]
>>> print textwrap.fill(paragraph, 35)
Not a whit, we defy augury: there's
a special providence in the fall of
a sparrow. If it be now, 'tis not
to come; if it be not to come, it
will be now; if it be not now, yet
it will come: the readiness is all.
>>>

The module also contains a TextWrapper class that actually implements the text wrapping strategy. Both the TextWrapper class and the wrap() and fill() functions support a number of additional keyword arguments for fine-tuning the formatting; consult the module’s documentation for details. (Contributed by Greg Ward.)

The thread and threading modules now have companion modules, dummy_thread and dummy_threading, that provide a do-nothing implementation of the thread module’s interface for platforms where threads are not supported. The intention is to simplify thread-aware modules (ones that don’t rely on threads to run) by putting the following code at the top:

try:
    import threading as _threading
except ImportError:
    import dummy_threading as _threading

In this example, _threading is used as the module name to make it clear that the module being used is not necessarily the actual threading module. Code can call functions and use classes in _threading whether or not threads are supported, avoiding an if statement and making the code slightly clearer. This module will not magically make multithreaded code run without threads; code that waits for another thread to return or to do something will simply hang forever.

The time module’s strptime() function has long been an annoyance because it uses the platform C library’s strptime() implementation, and different platforms sometimes have odd bugs. Brett Cannon contributed a portable implementation that’s written in pure Python and should behave identically on all platforms.

The new timeit module helps measure how long snippets of Python code take to execute. The timeit.py file can be run directly from the command line, or the module’s Timer class can be imported and used directly. Here’s a short example that figures out whether it’s faster to convert an 8-bit string to Unicode by appending an empty Unicode string to it or by using the unicode() function:

import timeit

timer1 = timeit.Timer('unicode("abc")')
timer2 = timeit.Timer('"abc" + u""')

# Run three trials
print timer1.repeat(repeat=3, number=100000)
print timer2.repeat(repeat=3, number=100000)

# On my laptop this outputs:
# [0.36831796169281006, 0.37441694736480713, 0.35304892063140869]
# [0.17574405670166016, 0.18193507194519043, 0.17565798759460449]

The Tix module has received various bug fixes and updates for the current version of the Tix package.

The Tkinter module now works with a thread-enabled version of Tcl. Tcl’s threading model requires that widgets only be accessed from the thread in which they’re created; accesses from another thread can cause Tcl to panic. For certain Tcl interfaces, Tkinter will now automatically avoid this when a widget is accessed from a different thread by marshalling a command, passing it to the correct thread, and waiting for the results. Other interfaces can’t be handled automatically but Tkinter will now raise an exception on such an access so that you can at least find out about the problem. See https://mail.python.org/pipermail/python-dev/2002-December/031107.html for a more detailed explanation of this change. (Implemented by Martin von Löwis.)

Calling Tcl methods through _tkinter no longer returns only strings. Instead, if Tcl returns other objects those objects are converted to their Python equivalent, if one exists, or wrapped with a _tkinter.Tcl_Obj object if no Python equivalent exists. This behavior can be controlled through the wantobjects() method of tkapp objects.

When using _tkinter through the Tkinter module (as most Tkinter applications will), this feature is always activated. It should not cause compatibility problems, since Tkinter would always convert string results to Python types where possible.

If any incompatibilities are found, the old behavior can be restored by setting the wantobjects variable in the Tkinter module to false before creating the first tkapp object.

import Tkinter
Tkinter.wantobjects = 0

Any breakage caused by this change should be reported as a bug.

The UserDict module has a new DictMixin class which defines all dictionary methods for classes that already have a minimum mapping interface. This greatly simplifies writing classes that need to be substitutable for dictionaries, such as the classes in the shelve module.

Adding the mix-in as a superclass provides the full dictionary interface whenever the class defines __getitem__(), __setitem__(), __delitem__(), and keys(). For example:

>>> import UserDict
>>> class SeqDict(UserDict.DictMixin):
...     """Dictionary lookalike implemented with lists."""
...     def __init__(self):
...         self.keylist = []
...         self.valuelist = []
...     def __getitem__(self, key):
...         try:
...             i = self.keylist.index(key)
...         except ValueError:
...             raise KeyError
...         return self.valuelist[i]
...     def __setitem__(self, key, value):
...         try:
...             i = self.keylist.index(key)
...             self.valuelist[i] = value
...         except ValueError:
...             self.keylist.append(key)
...             self.valuelist.append(value)
...     def __delitem__(self, key):
...         try:
...             i = self.keylist.index(key)
...         except ValueError:
...             raise KeyError
...         self.keylist.pop(i)
...         self.valuelist.pop(i)
...     def keys(self):
...         return list(self.keylist)
...
>>> s = SeqDict()
>>> dir(s)      # See that other dictionary methods are implemented
['__cmp__', '__contains__', '__delitem__', '__doc__', '__getitem__',
 '__init__', '__iter__', '__len__', '__module__', '__repr__',
 '__setitem__', 'clear', 'get', 'has_key', 'items', 'iteritems',
 'iterkeys', 'itervalues', 'keylist', 'keys', 'pop', 'popitem',
 'setdefault', 'update', 'valuelist', 'values']

(Contributed by Raymond Hettinger.)

The DOM implementation in xml.dom.minidom can now generate XML output in a particular encoding by providing an optional encoding argument to the toxml() and toprettyxml() methods of DOM nodes.

The xmlrpclib module now supports an XML-RPC extension for handling nil data values such as Python’s None. Nil values are always supported on unmarshalling an XML-RPC response. To generate requests containing None, you must supply a true value for the allow_none parameter when creating a Marshaller instance.

The new DocXMLRPCServer module allows writing self-documenting XML-RPC servers. Run it in demo mode (as a program) to see it in action. Pointing the Web browser to the RPC server produces pydoc-style documentation; pointing xmlrpclib to the server allows invoking the actual methods. (Contributed by Brian Quinlan.)

Support for internationalized domain names (RFCs 3454, 3490, 3491, and 3492) has been added. The «idna» encoding can be used to convert between a Unicode domain name and the ASCII-compatible encoding (ACE) of that name.

>{}>{}> u"www.Alliancefrançaise.nu".encode("idna")
'www.xn--alliancefranaise-npb.nu'

The socket module has also been extended to transparently convert Unicode hostnames to the ACE version before passing them to the C library. Modules that deal with hostnames such as httplib and ftplib) also support Unicode host names; httplib also sends HTTP Host headers using the ACE version of the domain name. urllib supports Unicode URLs with non-ASCII host names as long as the path part of the URL is ASCII only.

To implement this change, the stringprep module, the mkstringprep tool and the punycode encoding have been added.

Date/Time Type

Date and time types suitable for expressing timestamps were added as the datetime module. The types don’t support different calendars or many fancy features, and just stick to the basics of representing time.

The three primary types are: date, representing a day, month, and year; time, consisting of hour, minute, and second; and datetime, which contains all the attributes of both date and time. There’s also a timedelta class representing differences between two points in time, and time zone logic is implemented by classes inheriting from the abstract tzinfo class.

You can create instances of date and time by either supplying keyword arguments to the appropriate constructor, e.g. datetime.date(year=1972, month=10, day=15), or by using one of a number of class methods. For example, the date.today() class method returns the current local date.

Once created, instances of the date/time classes are all immutable. There are a number of methods for producing formatted strings from objects:

>>> import datetime
>>> now = datetime.datetime.now()
>>> now.isoformat()
'2002-12-30T21:27:03.994956'
>>> now.ctime()  # Only available on date, datetime
'Mon Dec 30 21:27:03 2002'
>>> now.strftime('%Y %d %b')
'2002 30 Dec'

The replace() method allows modifying one or more fields of a date or datetime instance, returning a new instance:

>>> d = datetime.datetime.now()
>>> d
datetime.datetime(2002, 12, 30, 22, 15, 38, 827738)
>>> d.replace(year=2001, hour = 12)
datetime.datetime(2001, 12, 30, 12, 15, 38, 827738)
>>>

Instances can be compared, hashed, and converted to strings (the result is the same as that of isoformat()). date and datetime instances can be subtracted from each other, and added to timedelta instances. The largest missing feature is that there’s no standard library support for parsing strings and getting back a date or datetime.

For more information, refer to the module’s reference documentation. (Contributed by Tim Peters.)

The optparse Module

The getopt module provides simple parsing of command-line arguments. The new optparse module (originally named Optik) provides more elaborate command-line parsing that follows the Unix conventions, automatically creates the output for --help, and can perform different actions for different options.

You start by creating an instance of OptionParser and telling it what your program’s options are.

import sys
from optparse import OptionParser

op = OptionParser()
op.add_option('-i', '--input',
              action='store', type='string', dest='input',
              help='set input filename')
op.add_option('-l', '--length',
              action='store', type='int', dest='length',
              help='set maximum length of output')

Parsing a command line is then done by calling the parse_args() method.

options, args = op.parse_args(sys.argv[1:])
print options
print args

This returns an object containing all of the option values, and a list of strings containing the remaining arguments.

Invoking the script with the various arguments now works as you’d expect it to. Note that the length argument is automatically converted to an integer.

$ ./python opt.py -i data arg1
<Values at 0x400cad4c: {'input': 'data', 'length': None}>
['arg1']
$ ./python opt.py --input=data --length=4
<Values at 0x400cad2c: {'input': 'data', 'length': 4}>
[]
$

The help message is automatically generated for you:

$ ./python opt.py --help
usage: opt.py [options]

options:
  -h, --help            show this help message and exit
  -iINPUT, --input=INPUT
                        set input filename
  -lLENGTH, --length=LENGTH
                        set maximum length of output
$

See the module’s documentation for more details.

Optik was written by Greg Ward, with suggestions from the readers of the Getopt SIG.

Pymalloc: A Specialized Object Allocator

Pymalloc, a specialized object allocator written by Vladimir Marangozov, was a feature added to Python 2.1. Pymalloc is intended to be faster than the system malloc() and to have less memory overhead for allocation patterns typical of Python programs. The allocator uses C’s malloc() function to get large pools of memory and then fulfills smaller memory requests from these pools.

In 2.1 and 2.2, pymalloc was an experimental feature and wasn’t enabled by default; you had to explicitly enable it when compiling Python by providing the --with-pymalloc option to the configure script. In 2.3, pymalloc has had further enhancements and is now enabled by default; you’ll have to supply --without-pymalloc to disable it.

This change is transparent to code written in Python; however, pymalloc may expose bugs in C extensions. Authors of C extension modules should test their code with pymalloc enabled, because some incorrect code may cause core dumps at runtime.

There’s one particularly common error that causes problems. There are a number of memory allocation functions in Python’s C API that have previously just been aliases for the C library’s malloc() and free(), meaning that if you accidentally called mismatched functions the error wouldn’t be noticeable. When the object allocator is enabled, these functions aren’t aliases of malloc() and free() any more, and calling the wrong function to free memory may get you a core dump. For example, if memory was allocated using PyObject_Malloc(), it has to be freed using PyObject_Free(), not free(). A few modules included with Python fell afoul of this and had to be fixed; doubtless there are more third-party modules that will have the same problem.

As part of this change, the confusing multiple interfaces for allocating memory have been consolidated down into two API families. Memory allocated with one family must not be manipulated with functions from the other family. There is one family for allocating chunks of memory and another family of functions specifically for allocating Python objects.

To allocate and free an undistinguished chunk of memory use the «raw memory» family: PyMem_Malloc(), PyMem_Realloc(), and PyMem_Free().

The «object memory» family is the interface to the pymalloc facility described above and is biased towards a large number of «small» allocations: PyObject_Malloc(), PyObject_Realloc(), and PyObject_Free().

To allocate and free Python objects, use the «object» family PyObject_New(), PyObject_NewVar(), and PyObject_Del().

Thanks to lots of work by Tim Peters, pymalloc in 2.3 also provides debugging features to catch memory overwrites and doubled frees in both extension modules and in the interpreter itself. To enable this support, compile a debugging version of the Python interpreter by running configure with --with-pydebug.

To aid extension writers, a header file Misc/pymemcompat.h is distributed with the source to Python 2.3 that allows Python extensions to use the 2.3 interfaces to memory allocation while compiling against any version of Python since 1.5.2. You would copy the file from Python’s source distribution and bundle it with the source of your extension.

Ver también

https://hg.python.org/cpython/file/default/Objects/obmalloc.c

For the full details of the pymalloc implementation, see the comments at the top of the file Objects/obmalloc.c in the Python source code. The above link points to the file within the python.org SVN browser.

Build and C API Changes

Changes to Python’s build process and to the C API include:

The cycle detection implementation used by the garbage collection has proven to be stable, so it’s now been made mandatory. You can no longer compile Python without it, and the --with-cycle-gc switch to configure has been removed.

Python can now optionally be built as a shared library (libpython2.3.so) by supplying --enable-shared when running Python’s configure script. (Contributed by Ondrej Palkovsky.)

The DL_EXPORT and DL_IMPORT macros are now deprecated. Initialization functions for Python extension modules should now be declared using the new macro PyMODINIT_FUNC, while the Python core will generally use the PyAPI_FUNC and PyAPI_DATA macros.

The interpreter can be compiled without any docstrings for the built-in functions and modules by supplying --without-doc-strings to the configure script. This makes the Python executable about 10% smaller, but will also mean that you can’t get help for Python’s built-ins. (Contributed by Gustavo Niemeyer.)

The PyArg_NoArgs() macro is now deprecated, and code that uses it should be changed. For Python 2.2 and later, the method definition table can specify the METH_NOARGS flag, signalling that there are no arguments, and the argument checking can then be removed. If compatibility with pre-2.2 versions of Python is important, the code could use PyArg_ParseTuple(args, "") instead, but this will be slower than using METH_NOARGS.

PyArg_ParseTuple() accepts new format characters for various sizes of unsigned integers: B for unsigned char, H for unsigned short int, I for unsigned int, and K for unsigned long long.

A new function, PyObject_DelItemString(mapping, char *key) was added as shorthand for PyObject_DelItem(mapping, PyString_New(key)).

File objects now manage their internal string buffer differently, increasing it exponentially when needed. This results in the benchmark tests in Lib/test/test_bufio.py speeding up considerably (from 57 seconds to 1.7 seconds, according to one measurement).

It’s now possible to define class and static methods for a C extension type by setting either the METH_CLASS or METH_STATIC flags in a method’s PyMethodDef structure.

Python now includes a copy of the Expat XML parser’s source code, removing any dependence on a system version or local installation of Expat.

If you dynamically allocate type objects in your extension, you should be aware of a change in the rules relating to the __module__ and __name__ attributes. In summary, you will want to ensure the type’s dictionary contains a '__module__' key; making the module name the part of the type name leading up to the final period will no longer have the desired effect. For more detail, read the API reference documentation or the source.

Port-Specific Changes

Support for a port to IBM’s OS/2 using the EMX runtime environment was merged into the main Python source tree. EMX is a POSIX emulation layer over the OS/2 system APIs. The Python port for EMX tries to support all the POSIX-like capability exposed by the EMX runtime, and mostly succeeds; fork() and fcntl() are restricted by the limitations of the underlying emulation layer. The standard OS/2 port, which uses IBM’s Visual Age compiler, also gained support for case-sensitive import semantics as part of the integration of the EMX port into CVS. (Contributed by Andrew MacIntyre.)

On MacOS, most toolbox modules have been weaklinked to improve backward compatibility. This means that modules will no longer fail to load if a single routine is missing on the current OS version. Instead calling the missing routine will raise an exception. (Contributed by Jack Jansen.)

The RPM spec files, found in the Misc/RPM/ directory in the Python source distribution, were updated for 2.3. (Contributed by Sean Reifschneider.)

Other new platforms now supported by Python include AtheOS (http://www.atheos.cx/), GNU/Hurd, and OpenVMS.

Other Changes and Fixes

As usual, there were a bunch of other improvements and bugfixes scattered throughout the source tree. A search through the CVS change logs finds there were 523 patches applied and 514 bugs fixed between Python 2.2 and 2.3. Both figures are likely to be underestimates.

Some of the more notable changes are:

If the PYTHONINSPECT environment variable is set, the Python interpreter will enter the interactive prompt after running a Python program, as if Python had been invoked with the -i option. The environment variable can be set before running the Python interpreter, or it can be set by the Python program as part of its execution.

The regrtest.py script now provides a way to allow «all resources except foo.» A resource name passed to the -u option can now be prefixed with a hyphen ('-') to mean «remove this resource.» For example, the option “-uall,-bsddb” could be used to enable the use of all resources except bsddb.

The tools used to build the documentation now work under Cygwin as well as Unix.

The SET_LINENO opcode has been removed. Back in the mists of time, this opcode was needed to produce line numbers in tracebacks and support trace functions (for, e.g., pdb). Since Python 1.5, the line numbers in tracebacks have been computed using a different mechanism that works with «python -O». For Python 2.3 Michael Hudson implemented a similar scheme to determine when to call the trace function, removing the need for SET_LINENO entirely.

It would be difficult to detect any resulting difference from Python code, apart from a slight speed up when Python is run without -O.

C extensions that access the f_lineno field of frame objects should instead call PyCode_Addr2Line(f->f_code, f->f_lasti). This will have the added effect of making the code work as desired under «python -O» in earlier versions of Python.

A nifty new feature is that trace functions can now assign to the f_lineno attribute of frame objects, changing the line that will be executed next. A jump command has been added to the pdb debugger taking advantage of this new feature. (Implemented by Richie Hindle.)

Porting to Python 2.3

This section lists previously described changes that may require changes to your code:

yield is now always a keyword; if it’s used as a variable name in your code, a different name must be chosen.

For strings X and Y, X in Y now works if X is more than one character long.

The int() type constructor will now return a long integer instead of raising an OverflowError when a string or floating-point number is too large to fit into an integer.

If you have Unicode strings that contain 8-bit characters, you must declare the file’s encoding (UTF-8, Latin-1, or whatever) by adding a comment to the top of the file. See section PEP 263: Codificación del código fuente for more information.

Calling Tcl methods through _tkinter no longer returns only strings. Instead, if Tcl returns other objects those objects are converted to their Python equivalent, if one exists, or wrapped with a _tkinter.Tcl_Obj object if no Python equivalent exists.

Large octal and hex literals such as 0xffffffff now trigger a FutureWarning. Currently they’re stored as 32-bit numbers and result in a negative value, but in Python 2.4 they’ll become positive long integers.

There are a few ways to fix this warning. If you really need a positive number, just add an L to the end of the literal. If you’re trying to get a 32-bit integer with low bits set and have previously used an expression such as ~(1 << 31), it’s probably clearest to start with all bits set and clear the desired upper bits. For example, to clear just the top bit (bit 31), you could write 0xffffffffL &~(1L<<31).

You can no longer disable assertions by assigning to __debug__.

The Distutils setup() function has gained various new keyword arguments such as depends. Old versions of the Distutils will abort if passed unknown keywords. A solution is to check for the presence of the new get_distutil_options() function in your setup.py and only uses the new keywords with a version of the Distutils that supports them:

from distutils import core

kw = {'sources': 'foo.c', ...}
if hasattr(core, 'get_distutil_options'):
    kw['depends'] = ['foo.h']
ext = Extension(**kw)

Using None as a variable name will now result in a SyntaxWarning warning.

Names of extension types defined by the modules included with Python now contain the module and a '.' in front of the type name.

Acknowledgements

The author would like to thank the following people for offering suggestions, corrections and assistance with various drafts of this article: Jeff Bauer, Simon Brunning, Brett Cannon, Michael Chermside, Andrew Dalke, Scott David Daniels, Fred L. Drake, Jr., David Fraser, Kelly Gerber, Raymond Hettinger, Michael Hudson, Chris Lambert, Detlef Lannert, Martin von Löwis, Andrew MacIntyre, Lalo Martins, Chad Netzer, Gustavo Niemeyer, Neal Norwitz, Hans Nowak, Chris Reedy, Francesco Ricciardi, Vinay Sajip, Neil Schemenauer, Roman Suzi, Jason Tishler, Just van Rossum.

Qué hay de nuevo en Python 2.2

Autor

A.M. Kuchling

Introducción

Este artículo explica las nuevas características en Python 2.2.2, publicado el 14 de octubre de 2002. Python 2.2.2 es una versión de corrección de errores de Python 2.2, lanzada originalmente el 21 de diciembre de 2001.

Python 2.2 se puede considerar como la «versión de limpieza». Hay algunas características como los generadores e iteradores que son completamente nuevas, pero la mayoría de los cambios, aunque sean significativos y de gran alcance, tienen como objetivo limpiar las irregularidades y los rincones oscuros del diseño del lenguaje.

Este artículo no procura proporcionar una especificación completa de las nuevas características, pero en su lugar proporciona una descripción general conveniente. Para más detalles, deberías consultar la documentación de Python 2.2, como Python Library Reference [https://docs.python.org/2.2/lib/lib.html] y Python Reference Manual [https://docs.python.org/2.2/ref/ref.html]. Si quieres comprender la justificación completa de la implementación y el diseño de un cambio, consultar la PEP para conocer una característica nueva en particular.

PEPs 252 y 253: Cambios de tipo y clase

Los cambios más grandes y de mayor alcance en Python 2.2 son el modelo de objetos y clases de Python. Los cambios deben ser compatibles con versiones anteriores, por lo que es probable que tu código continuará ejecutándose sin cambios, pero los cambios proporcionan algunas capacidades nuevas increíbles. Antes de comenzar esta, la sección más larga y complicada de este artículo, brindaré una descripción general de los cambios y ofreceré algunos comentarios.

Hace mucho tiempo escribí una página web que enumeraba los defectos en el diseño de Python. Una de las fallas más importantes fue que es imposible subclasificar tipos de Python implementados en C. En particular, no es posible subclasificar tipos incorporados, por lo que no se puede solo subclasificar, digamos, listas para agregar un solo método útil para ellos. El módulo UserList proporciona una clase que admite todos los métodos de listas y que puede subclasificarse aún más, pero hay mucho código C que espera una lista normal de Python y no aceptará una instancia UserList.

Python 2.2 corrige esto y, en el proceso, agrega algunas capacidades nuevas interesantes. Un breve resumen:

Puedes subclasificar tipos incorporados como listas e incluso enteros, y tus subclases deberían funcionar en todos los lugares que requieran el tipo original.

Ahora es posible definir métodos estáticos y de clase, además de los métodos de instancia disponibles en versiones anteriores de Python.

También es posible llamar automáticamente métodos al acceder o configurar un atributo de instancia mediante el uso de un nuevo mecanismo llamado properties. Muchos usos de __getattr__() se pueden reescribir para usar propiedades en su lugar, haciendo que el código resultante sea más simple y rápido. Como un pequeño beneficio secundario, ahora también los atributos pueden tener docstrings.

La lista de atributos legales para una instancia se puede limitar a un conjunto particular usando slots, lo que hace posible protegerse contra errores tipográficos y quizás hacer posibles más optimizaciones en versiones futuras de Python.

Algunos usuarios han expresado preocupación por todos estos cambios. Claro, dicen, las nuevas características son ordenadas y se prestan a todo tipo de trucos que no eran posibles en versiones anteriores de Python, pero también hacen que el lenguaje sea más complicado. Algunas personas han dicho que siempre han recomendado Python por su simplicidad, y sienten que su simplicidad se está perdiendo.

Personalmente. pienso que no hay que preocuparse. Muchas de las nuevas características son bastante esotéricas, y puedes escribir mucho código de Python sin tener que estar al tanto de ellas. Escribir una clase simple no es más difícil de lo que nunca fue, así que no necesitas molestarte en aprender o enseñarlos a menos que realmente sean necesarios. Algunas tareas muy complicadas que antes solo eran posibles desde C ahora serán posibles en Python puro, y en mi opinión, esto es todo para mejor.

No voy a intentar cubrir todas los casos de las esquinas y los pequeños cambios que fueron necesarios para hacer que las nuevas características funcionen. En su lugar, esta sección pintará solo a grandes rasgos. Consultar la sección Enlaces relacionados, «Enlaces relacionados», para más fuentes de información sobre el nuevo modelo de objetos de Python 2.2.

Clases antiguas y nuevas

Primero, debes saber que realmente Python 2.2 tiene dos tipos de clases: clases clásicas o de estilo antiguo y clases de estilo nuevo. El modelo de clase de estilo antiguo exactamente es el mismo que el modelo de clase en versiones anteriores de Python. Todas las nuevas características descritas en esta sección se aplican solo a las clases de estilo nuevo. Esta divergencia no está destinada a durar para siempre; eventualmente las clases de estilo antiguo se eliminarán, posiblemente en Python 3.0.

Entonces, ¿cómo defines una clase de estilo nuevo? Lo haces subclasificando una clases de estilo nuevo existente. La mayoría de los tipos integrados de Python, como enteros, listas, diccionarios e incluso archivos, ahora son clases de estilo nuevo. También se agregó una clase de estilo nuevo llamada object, la clase base para todos los tipos integrados, por lo que si ningún tipo integrado es apropiado, puedes solo subclasificar object:

class C(object):
    def __init__ (self):
        ...
    ...

Esto significa que las declaraciones class que no tienen ninguna clase base siempre son clases clásicas en Python 2.2. (Realmente también puedes cambiar esto configurando una variable de nivel de módulo llamada __metaclass__ — consultar PEP 253 [https://www.python.org/dev/peps/pep-0253] para más detalles — pero es más fácil solo subclasificar object.)

Los objetos de tipo para los tipos integrados están disponibles como incorporados, nombrados mediante un truco inteligente. Python siempre ha tenido funciones incorporadas llamadas int(), float() y str(). En la versión 2.2, ya no son funciones, sino objetos de tipo que se comportan como fábricas cuando se les llaman.

>>> int
<type 'int'>
>>> int('123')
123

Para completar el conjunto de tipos, se agregaron nuevos objetos de tipo como dict() y file(). Aquí hay un ejemplo más interesante, agregando un método lock() a los objetos de archivo:

class LockableFile(file):
    def lock (self, operation, length=0, start=0, whence=0):
        import fcntl
        return fcntl.lockf(self.fileno(), operation,
                           length, start, whence)

El módulo ahora obsoleto posixfile contenía una clase que emulaba todos los métodos de un objeto de archivo y también agregaba un método lock(), pero esta clase no podía pasarse a funciones internas que esperaban un archivo incorporado, algo que es posible con nuestra nueva clase LockableFile.

Descriptores

En versiones anteriores de Python, no había una forma consistente de descubrir qué atributos y métodos eran compatibles con un objeto. Había algunas convenciones informales, como definir atributos __members__ y __methods__ que eran listas de nombres, pero a menudo el autor de un tipo de extensión o una clase no se molestaría en definirlos. Podrías recurrir a inspeccionar el __dict__ de un objeto, pero cuando la herencia de una clase o un gancho arbitrario __getattr__() estuvieran en uso, esto podría ser inexacto.

La única gran idea que subyace al nuevo modelo de clases es que se ha formalizado una API para describir los atributos de un objeto usando descriptors. Los descriptores especifican el valor de un atributo, indicando si es un método o un campo. Con la API de un descriptor, los métodos estáticos y de clase se vuelven posibles, así como constructos más exóticos.

Los descriptores de atributos son objetos que viven dentro de los objetos de clase y tienen algunos atributos propios:

__name__ es el nombre del atributo.

__doc__ es el docstring del atributo.

__get__(object) es un método que recupera el valor del atributo de object.

__set__(object, value) establece el atributo de object en value.

__delete__(object, value) elimina el atributo value de object.

Por ejemplo, cuando escribes obj.x, los pasos que realmente Python realiza son:

descriptor = obj.__class__.x
descriptor.__get__(obj)

Para los métodos, descriptor.__get__() retorna un objeto temporal que se puede llamar y contiene la instancia y el método que se llamará en él. También esto es el por qué los métodos estáticos y de clase ahora son posibles; tienen descriptores que contienen solo el método o el método y la clase. Como una breve explicación de estos tipos nuevos de métodos, los métodos estáticos no se pasan a la instancia y, por lo tanto, se asemejan a funciones regulares. Los métodos de clase se pasan a la clase del objeto, pero no al objeto en sí. Los métodos estáticos y de clase se definen así:

class C(object):
    def f(arg1, arg2):
        ...
    f = staticmethod(f)

    def g(cls, arg1, arg2):
        ...
    g = classmethod(g)

La función staticmethod() toma la función f() y la retorna en un descriptor para que pueda almacenarse en el objeto de clase. Puedes esperar que haya una sintaxis especial para crear tales métodos (def static f, defstatic f() o algo así) pero aún no se ha definido dicha sintaxis; que se ha dejado para versiones futuras de Python.

También se implementan más características nuevas, como ranuras y propiedades, como nuevos tipos de descriptores, y no es difícil escribir una clase de descriptor que haga algo nuevo. Por ejemplo, sería posible escribir una clase de descriptor que hiciera posible escribir condiciones previas al estilo Eiffel y posteriores para un método. Una clase que usó esta característica podría definirse así:

from eiffel import eiffelmethod

class C(object):
    def f(self, arg1, arg2):
        # The actual function
        ...
    def pre_f(self):
        # Check preconditions
        ...
    def post_f(self):
        # Check postconditions
        ...

    f = eiffelmethod(f, pre_f, post_f)

Toma en cuenta que una persona que usa la nueva función eiffelmethod() no tiene que entender nada sobre descriptores. Esta es la razón por la que creo que las nuevas características no incrementan la complejidad básica del lenguaje. Habrá algunos asistentes que necesitarán conocerlo para escribir eiffelmethod() o la ZODB o lo que sea, pero la mayoría de los usuarios solo escribirán código sobre las bibliotecas resultantes e ignorarán los detalles de implementación.

Herencia múltiple: la regla del diamante

La herencia múltiple también se ha hecho más útil al cambiar las reglas bajo las cuales se resuelven los nombres. Considera este conjunto de clases (diagrama tomado de PEP 253 [https://www.python.org/dev/peps/pep-0253] de Guido van Rossum):

      class A:
        ^ ^  def save(self): ...
       /   \
      /     \
     /       \
    /         \
class B     class C:
    ^         ^  def save(self): ...
     \       /
      \     /
       \   /
        \ /
      class D

La regla de búsqueda para clases clásicas es simple pero no muy inteligente; se buscan las clases base primero en profundidad, yendo de izquierda a derecha. Una referencia a D.save() buscará las clases D, B y luego A, donde save() se encontraría y retornaría. C.save() nunca se encontraría en absoluto. Esto es malo, porque si el método save() de C está guardando algún estado interno específico de C, no llamarlo resultará en que este estado nunca se guardará.

Las clases de estilo nuevo siguen un algoritmo diferente que es más complicado de explicar, pero hace lo correcto en esta situación. (Toma en cuenta que Python 2.3 cambia este algoritmo a uno que produce los mismos resultados en la mayoría de los casos, pero produce resultados más útiles para gráficos de herencia realmente complicados.)

Enumera todas las clases base, siguiendo la regla de búsqueda clásica e incluye una clase varias veces si se visita repetidamente. En el ejemplo anterior, la lista de clases visitadas es [D, B, A, C, A].

Escanea la lista en busca de clases duplicadas. Si encuentra alguna, elimina todas menos una, dejando la última en la lista. En el ejemplo anterior, la lista se convierte en [D, B, C, A] después de eliminar las duplicadas.

Siguiendo esta regla, refiriéndose a D.save() retornará C.save(), el cual es el comportamiento que buscamos. Esta regla de búsqueda es la misma que sigue Common Lisp. Una nueva función incorporada, super(), proporciona una forma de acceder a las superclases de una clase sin tener que volver a implementar el algoritmo de Python. La forma más utilizada será super(class, obj), la cual retorna un objeto de superclase vinculado. Esta forma se usará en métodos para llamar a un método en la superclase; por ejemplo, el método save() de D se vería así:

class D (B,C):
    def save (self):
        # Call superclass .save()
        super(D, self).save()
        # Save D's private information here
        ...

También super() puede retornar objetos de superclase no vinculados cuando se llama como super(class) o super(class1, class2), pero probablemente esto no sea útil a menudo.

Acceso a atributos

Un buen número de clases sofisticadas de Python definen ganchos para el acceso de atributos usando __getattr__(); más comúnmente, esto se hace por conveniencia, para hacer que el código sea más legible al mapear automáticamente un acceso de atributo como obj.parent en una llamada de método como obj.get_parent. Python 2.2 agrega algunas formas nuevas de controlar el acceso de atributos.

Primero, __getattr__(attr_name) aún es compatible con las clases de nuevo estilo, y nada al respecto ha cambiado. Como antes, se llamará cuando se intente acceder a obj.foo y no se encuentre ningún atributo llamado foo en el diccionario de la instancia.

Las clases de nuevo estilo también admiten un nuevo método, __getattribute__(attr_name). La diferencia entre los dos métodos es que __getattribute__() siempre se llama cada vez que se accede a cualquier atributo, mientras que el antiguo __getattr__() se llama solo si no se encuentra foo en el diccionario de la instancia.

Sin embargo, el soporte de Python 2.2 para properties será a menudo una forma más simple de atrapar referencias de atributos. Escribir un método __getattr__() es complicado porque para evitar la recursividad no puedes usar accesos regulares a atributos dentro de ellos, y en su lugar tienes que jugar con el contenido de __dict__. Los métodos __getattr__() también terminan siendo llamados por Python cuando busca otros métodos como __repr__() o __coerce__(), por lo que se tienen que escribirse teniendo esto en cuenta. Finalmente, llamar una función en cada acceso de atributo resulta en una pérdida de rendimiento considerable.

property es un nuevo tipo integrado que empaqueta tres funciones obtienen, establecen o eliminan un atributo y una docstring. Por ejemplo, si quieres definir un atributo size que se calcula, pero que también se puede configurar, puedes escribir:

class C(object):
    def get_size (self):
        result = ... computation ...
        return result
    def set_size (self, size):
        ... compute something based on the size
        and set internal state appropriately ...

    # Define a property.  The 'delete this attribute'
    # method is defined as None, so the attribute
    # can't be deleted.
    size = property(get_size, set_size,
                    None,
                    "Storage size of this instance")

Eso es ciertamente más claro y fácil de escribir que un par de métodos __getattr__()/__setattr__() que verifican el atributo size y lo manejan especialmente mientras recuperan todos los demás atributos __dict__ de la instancia. Los accesos a size también son los únicos que tienen que realizar el trabajo de llamar a una función, por lo que las referencias a otros atributos se ejecutan a su velocidad habitual.

Finalmente, es posible restringir la lista de atributos que se pueden referenciar en un objeto usando el nuevo atributo de clase __slots__. Los objetos de Python por lo general son muy dinámicos; en cualquier momento es posible definir un nuevo atributo en una instancia haciendo simplemente obj.new_attr=1. Una clase de estilo nuevo puede definir un atributo de clase llamado __slots__ para limitar los atributos legales a un conjunto particular de nombres. Un ejemplo hará esto claro:

>>> class C(object):
...     __slots__ = ('template', 'name')
...
>>> obj = C()
>>> print obj.template
None
>>> obj.template = 'Test'
>>> print obj.template
Test
>>> obj.newattr = None
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
AttributeError: 'C' object has no attribute 'newattr'

Toma en cuenta cómo obtienes un AttributeError en el intento de asignar a un atributo que no aparece en __slots__.

Enlaces relacionados

Esta sección solo ha sido una descripción rápida de las nuevas características, brindando una explicación suficiente para comenzar a programar, pero muchos detalles se han simplificado o ignorado. ¿Dónde deberías ir para obtener una imagen más completa?

https://docs.python.org/dev/howto/descriptor.html es un extenso tutorial de introducción a las características del descriptor, escrito por Guido van Rossum. Si mi descripción te despertó el apetito, lee este tutorial a continuación, porque entra en mucho más detalle sobre las nuevas características sin dejar de ser bastante fácil de leer.

A continuación, hay dos PEPs relevantes, PEP 252 [https://www.python.org/dev/peps/pep-0252] y PEP 253 [https://www.python.org/dev/peps/pep-0253]. PEP 252 [https://www.python.org/dev/peps/pep-0252] se titula «Hacer que los tipos se parezcan más a las clases», y cubre la API del descriptor. PEP 253 [https://www.python.org/dev/peps/pep-0253] se titula «Subtipado de tipos incorporados», y describe los cambios de los objetos de tipo que hacen posible el subtipo de objetos incorporados. PEP 253 [https://www.python.org/dev/peps/pep-0253] es la PEP más complicada de las dos, y en algunos puntos las explicaciones necesarias de tipos y meta-tipos pueden causar que tu cabeza explote. Ambas PEPs se escribieron e implementaron por Guido van Rossum con la asistencia sustancial del resto del equipo de Zope Corp.

Finalmente, está la máxima autoridad: el código fuente. La mayoría de la maquinaria para el manejo de tipos está en Objects/typeobject.c, pero solo debes recurrir a él después de que se hayan agotado todas las demás vías, incluida la publicación de una pregunta en python-list o python-dev.

PEP 234: Iteradores

Otra adición significativa a la versión 2.2 es una interfaz de iteración tanto a nivel de C como de Python. Los objetos pueden definir cómo pueden ser iterados por quienes los llaman.

En las versiones de Python hasta la 2.1, la forma habitual de hacer que funcione for item in obj es definir un método __getitem__() que se parezca a esto:

def __getitem__(self, index):
    return <next item>

__getitem__() se utiliza más adecuadamente para definir una operación de indexación en un objeto, de modo que se puede escribir obj[5] para recuperar el sexto elemento. Es un poco engañoso cuando se utiliza esto sólo para soportar bucles for. Considere algún objeto tipo archivo que quiera ser revisado en bucle; el parámetro index no tiene sentido, ya que la clase probablemente asume que se hará una serie de llamadas a __getitem__() con index incrementándose en uno cada vez. En otras palabras, la presencia del método __getitem__() no significa que el uso de file[5] para acceder al azar al sexto elemento vaya a funcionar, aunque realmente debería hacerlo.

En Python 2.2, la iteración puede implementarse por separado, y los métodos __getitem__() pueden limitarse a las clases que realmente soportan el acceso aleatorio. La idea básica de los iteradores es simple. Una nueva función incorporada, iter(obj) o iter(C, sentinel), se utiliza para obtener un iterador. iter(obj) retorna un iterador para el objeto obj, mientras que iter(C, sentinel) retorna un iterador que invocará al objeto invocable C hasta que retorne sentinel para señalar que el iterador ha terminado.

Las clases de Python pueden definir un método __iter__(), que debe crear y retornar un nuevo iterador para el objeto; si el objeto es su propio iterador, este método puede simplemente retornar self. En particular, los iteradores suelen ser sus propios iteradores. Los tipos de extensión implementados en C pueden implementar una función tp_iter para retornar un iterador, y los tipos de extensión que quieran comportarse como iteradores pueden definir una función tp_iternext.

Entonces, después de todo esto, ¿qué hacen realmente los iteradores? Tienen un método obligatorio, next(), que no toma argumentos y retorna el siguiente valor. Cuando no hay más valores que retornar, la llamada a next() debería lanzar la excepción StopIteration.

>>> L = [1,2,3]
>>> i = iter(L)
>>> print i
<iterator object at 0x8116870>
>>> i.next()
1
>>> i.next()
2
>>> i.next()
3
>>> i.next()
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
StopIteration
>>>

En 2.2, la sentencia for de Python ya no espera una secuencia; espera algo para lo que iter() retornará un iterador. Por compatibilidad y comodidad, se construye automáticamente un iterador para las secuencias que no implementan __iter__() o una ranura tp_iter, por lo que for i in [1,2,3] seguirá funcionando. Dondequiera que el intérprete de Python haga un bucle sobre una secuencia, se ha cambiado para utilizar el protocolo de los iteradores. Esto significa que puedes hacer cosas como esta:

>>> L = [1,2,3]
>>> i = iter(L)
>>> a,b,c = i
>>> a,b,c
(1, 2, 3)

Se ha añadido soporte de iteradores a algunos de los tipos básicos de Python. Llamar a iter() sobre un diccionario retornará un iterador que hace un bucle sobre sus claves:

>>> m = {'Jan': 1, 'Feb': 2, 'Mar': 3, 'Apr': 4, 'May': 5, 'Jun': 6,
...      'Jul': 7, 'Aug': 8, 'Sep': 9, 'Oct': 10, 'Nov': 11, 'Dec': 12}
>>> for key in m: print key, m[key]
...
Mar 3
Feb 2
Aug 8
Sep 9
May 5
Jun 6
Jul 7
Jan 1
Apr 4
Nov 11
Dec 12
Oct 10

Este es el comportamiento por defecto. Si quieres iterar sobre claves, valores o pares clave/valor, puedes llamar explícitamente a los métodos iterkeys(), itervalues() o iteritems() para obtener un iterador apropiado. En un cambio menor relacionado, el operador in ahora funciona en los diccionarios, por lo que key in dict es ahora equivalente a dict.has_key(key).

Los archivos también proporcionan un iterador, que llama al método readline() hasta que no hay más líneas en el archivo. Esto significa que ahora puede leer cada línea de un archivo utilizando un código como este:

for line in file:
    # do something for each line
    ...

Tenga en cuenta que sólo puede avanzar en un iterador; no hay forma de obtener el elemento anterior, reiniciar el iterador o hacer una copia del mismo. Un objeto iterador podría proporcionar estas capacidades adicionales, pero el protocolo iterador sólo requiere un método next().

Ver también

PEP 234 [https://www.python.org/dev/peps/pep-0234] - Iteradores

Escrito por Ka-Ping Yee y GvR; implementado por el equipo de Python Labs, principalmente por GvR y Tim Peters.

PEP 255: Generadores simples

Los generadores son otra novedad que interactúa con la introducción de los iteradores.

Sin duda estás familiarizado con cómo funcionan las llamadas a funciones en Python o C. Cuando llamas a una función, ésta obtiene un espacio de nombres privado donde se crean sus variables locales. Cuando la función llega a una declaración return, las variables locales se destruyen y el valor resultante se retorna a quien la llamó. Una llamada posterior a la misma función obtendrá un nuevo conjunto de variables locales. Pero, ¿qué pasaría si las variables locales no se tiraran al salir de una función? ¿Qué pasaría si pudieras reanudar la función donde la dejaste? Esto es lo que proporcionan los generadores; se puede pensar en ellos como funciones reanudables.

Este es el ejemplo más sencillo de una función generadora:

def generate_ints(N):
    for i in range(N):
        yield i

Se ha introducido una nueva palabra clave, yield, para los generadores. Cualquier función que contenga una declaración yield es una función generadora; esto es detectado por el compilador de código de bits de Python que compila la función especialmente como resultado. Debido a la introducción de una nueva palabra clave, los generadores deben ser explícitamente habilitados en un módulo incluyendo una declaración from __future__ import generators cerca de la parte superior del código fuente del módulo. En Python 2.3 esta declaración será innecesaria.

Cuando se llama a una función generadora, ésta no retorna un único valor, sino que retorna un objeto generador que soporta el protocolo de los iteradores. Al ejecutar la sentencia yield, el generador retorna el valor de i, de forma similar a una sentencia return. La gran diferencia entre yield y una sentencia return es que al llegar a una sentencia yield se suspende el estado de ejecución del generador y se conservan las variables locales. En la siguiente llamada al método next() del generador, la función se reanudará la ejecución inmediatamente después de la sentencia yield. (Por razones complicadas, la sentencia yield no está permitida dentro del bloque try de una sentencia try…`finally; lea PEP 255 [https://www.python.org/dev/peps/pep-0255] para una explicación completa de la interacción entre yield y las excepciones)

Este es un ejemplo de uso del generador generate_ints():

>>> gen = generate_ints(3)
>>> gen
<generator object at 0x8117f90>
>>> gen.next()
0
>>> gen.next()
1
>>> gen.next()
2
>>> gen.next()
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
  File "<stdin>", line 2, in generate_ints
StopIteration

También podrías escribir for i in generate_ints(5), o a,b,c = generate_ints(3).

Dentro de una función generadora, la sentencia return sólo puede usarse sin un valor, y señala el final de la procesión de valores; después el generador no puede retornar más valores. return con un valor, como return 5, es un error de sintaxis dentro de una función generadora. El final de los resultados del generador también puede indicarse levantando manualmente StopIteration, o simplemente dejando que el flujo de ejecución caiga en el fondo de la función.

Puedes conseguir el efecto de los generadores manualmente escribiendo tu propia clase y almacenando todas las variables locales del generador como variables de instancia. Por ejemplo, la lución de una lista de enteros podría hacerse estableciendo self.count a 0, y haciendo que el método next() incremente self.count y lo retorne. Sin embargo, para un generador medianamente complicado, escribir la clase correspondiente sería mucho más complicado. Lib/test/test_generators.py contiene varios ejemplos más interesantes. El más sencillo implementa un recorrido en orden de un árbol utilizando generadores de forma recursiva

# A recursive generator that generates Tree leaves in in-order.
def inorder(t):
    if t:
        for x in inorder(t.left):
            yield x
        yield t.label
        for x in inorder(t.right):
            yield x

Otros dos ejemplos en Lib/test/test_generators.py producen soluciones para el problema de las N reinas (colocar $N$ reinas en un tablero de ajedrez $NxN$ de forma que ninguna reina amenace a otra) y el recorrido del caballero (una ruta que lleva a un caballo a cada casilla de un tablero de ajedrez $NxN$ sin visitar ninguna casilla dos veces).

La idea de los generadores proviene de otros lenguajes de programación, especialmente de Icon (https://www.cs.arizona.edu/icon/), donde la idea de los generadores es fundamental. En Icon, cada expresión y llamada a una función se comporta como un generador. Un ejemplo de «An Overview of the Icon Programming Language» en https://www.cs.arizona.edu/icon/docs/ipd266.htm da una idea de cómo es esto:

sentence := "Store it in the neighboring harbor"
if (i := find("or", sentence)) > 5 then write(i)

En Icon la función find() retorna los índices en los que se encuentra la subcadena «o»: 3, 23, 33. En la sentencia if, a i se le asigna primero un valor de 3, pero 3 es menor que 5, por lo que la comparación falla, e Icon la reintenta con el segundo valor de 23. 23 es mayor que 5, por lo que la comparación ahora tiene éxito, y el código imprime el valor 23 en la pantalla.

Python no va tan lejos como Icon en la adopción de generadores como concepto central. Los generadores se consideran una nueva parte del núcleo del lenguaje Python, pero aprenderlos o utilizarlos no es obligatorio; si no resuelven ningún problema que tengas, siéntete libre de ignorarlos. Una característica novedosa de la interfaz de Python en comparación con la de Icon es que el estado de un generador se representa como un objeto concreto (el iterador) que puede pasarse a otras funciones o almacenarse en una estructura de datos.

Ver también

PEP 255 [https://www.python.org/dev/peps/pep-0255] - Generadores simples

Escrito por Neil Schemenauer, Tim Peters, Magnus Lie Hetland. Implementado principalmente por Neil Schemenauer y Tim Peters, con otras correcciones del equipo de Python Labs.

PEP 237: Unificación de enteros largos y enteros

En versiones recientes, la distinción entre enteros regulares, que son valores de 32 bits en la mayoría de las máquinas, y enteros largos, que pueden tener un tamaño arbitrario, se estaba convirtiendo en una molestia. Por ejemplo, en las plataformas que soportan archivos de más de 2**32 bytes, el método tell() de los objetos archivo tiene que retornar un entero largo. Sin embargo, había varias partes de Python que esperaban números enteros simples y que daban un error si se proporcionaba un número entero largo en su lugar. Por ejemplo, en Python 1.5, sólo podían usarse enteros normales como índice de corte, y 'abc'[1L:] lanzaba una excepción TypeError con el mensaje “slice index must be int”.

Python 2.2 cambiará los valores de enteros cortos a enteros largos según sea necesario. El sufijo “L” ya no es necesario para indicar un literal entero largo, ya que ahora el compilador elegirá el tipo apropiado. (El uso del sufijo “L” se desaconsejará en futuras versiones 2.x de Python, provocando una advertencia en Python 2.4, y probablemente se eliminará en Python 3.0) Muchas operaciones que solían lanzar un OverflowError ahora retornarán un entero largo como resultado. Por ejemplo:

>>> 1234567890123
1234567890123L
>>> 2 ** 64
18446744073709551616L

En la mayoría de los casos, los enteros y los enteros largos se tratarán ahora de forma idéntica. Todavía se pueden distinguir con la función incorporada type(), pero rara vez se necesita.

Ver también

PEP 237 [https://www.python.org/dev/peps/pep-0237] - Unificación de enteros largos y enteros

Escrito por Moshe Zadka y Guido van Rossum. Implementado principalmente por Guido van Rossum.

PEP 238: Cambio del operador de división

El cambio más controvertido de Python 2.2 anuncia el inicio de un esfuerzo por arreglar un viejo defecto de diseño que ha estado en Python desde el principio. Actualmente, el operador de división de Python, /, se comporta como el operador de división de C cuando se le presentan dos argumentos enteros: retorna un resultado entero que se trunca cuando hay una parte fraccionaria. Por ejemplo, 3/2 es 1, no 1,5, y (-1)/2 es -1, no -0,5. Esto significa que los resultados de la división pueden variar inesperadamente dependiendo del tipo de los dos operandos y, como Python está tipado dinámicamente, puede ser difícil determinar los posibles tipos de los operandos.

(La controversia se centra en si esto es realmente un defecto de diseño, y si vale la pena romper el código existente para arreglarlo. Ha provocado interminables discusiones en python-dev, y en julio de 2001 estalló una tormenta de publicaciones ácidamente sarcásticas en comp.lang.python. No argumentaré aquí a favor de ninguno de los dos bandos y me limitaré a describir lo que se ha implementado en la 2.2. Lea PEP 238 [https://www.python.org/dev/peps/pep-0238] para un resumen de los argumentos y contra-argumentos)

Debido a que este cambio podría romper el código, se está introduciendo de forma muy gradual. Python 2.2 comienza la transición, pero el cambio no será completo hasta Python 3.0.

En primer lugar, tomaré prestada alguna terminología de PEP 238 [https://www.python.org/dev/peps/pep-0238]. La «división verdadera» es la división con la que la mayoría de los no programadores están familiarizados: 3/2 es 1,5, 1/4 es 0,25, y así sucesivamente. La «división por el piso» es lo que hace actualmente el operador / de Python cuando se le dan operandos enteros; el resultado es el piso del valor retornado por la división verdadera. La «división clásica» es el comportamiento mixto actual de /; retorna el resultado de la división por el suelo cuando los operandos son enteros, y retorna el resultado de la división verdadera cuando uno de los operandos es un número de punto flotante.

Estos son los cambios que introduce la versión 2.2:

Un nuevo operador, //, es el operador de división por el suelo. (Sí, ya sabemos que se parece al símbolo de comentario de C++.) // siempre realiza la división por el suelo sin importar los tipos de sus operandos, así que 1 // 2 es 0 y 1.0 // 2.0 también es 0.0.

//` está siempre disponible en Python 2.2; no es necesario habilitarlo mediante una sentencia ``__future__.

Al incluir una declaración from __future__ import division en un módulo, el operador / se cambiará para retornar el resultado de la división verdadera, por lo que 1/2 es 0,5. Sin la declaración __future__, / sigue significando la división clásica. El significado por defecto de / no cambiará hasta Python 3.0.

Las clases pueden definir métodos llamados __truediv__() y __floordiv__() para sobrecargar los dos operadores de división. En el nivel C, también hay ranuras en la estructura PyNumberMethods para que los tipos de extensión puedan definir los dos operadores.

Python 2.2 admite algunos argumentos de línea de comandos para comprobar si el código funcionará con la semántica de división modificada. Ejecutar python con -Q warn hará que se emita una advertencia cada vez que se aplique la división a dos enteros. Puedes usar esto para encontrar el código que está afectado por el cambio y arreglarlo. Por defecto, Python 2.2 simplemente realizará la división clásica sin una advertencia; la advertencia se activará por defecto en Python 2.3.

Ver también

PEP 238 [https://www.python.org/dev/peps/pep-0238] - Cambio del operador de división

Escrito por Moshe Zadka y Guido van Rossum. Implementado por Guido van Rossum..

Cambios en Unicode

El soporte de Unicode de Python se ha mejorado un poco en la versión 2.2. Las cadenas Unicode se almacenan normalmente como UCS-2, como enteros sin signo de 16 bits. Python 2.2 también puede ser compilado para usar UCS-4, enteros sin signo de 32 bits, como su codificación interna suministrando --enable-unicode=ucs4 al script de configuración. (También es posible especificar --disable-unicode para desactivar completamente el soporte de Unicode)

Cuando se compila para usar UCS-4 (un «Python amplio»), el intérprete puede manejar de forma nativa caracteres Unicode desde U+000000 hasta U+110000, por lo que el rango de valores legales para la función unichr() se expande en consecuencia. Utilizando un intérprete compilado para usar UCS-2 (un «Python estrecho»), los valores mayores de 65535 seguirán provocando que unichr() lance una excepción ValueError. Todo esto se describe en PEP 261 [https://www.python.org/dev/peps/pep-0261], «Soporte para caracteres Unicode “anchos”»; consúltelo para más detalles.

Otro cambio es más sencillo de explicar. Desde su introducción, las cadenas Unicode han soportado un método encode() para convertir la cadena a una codificación seleccionada como UTF-8 o Latin-1. Un método simétrico decode([*encoding*]) ha sido añadido a las cadenas de 8 bits (aunque no a las cadenas Unicode) en 2.2. decode() asume que la cadena está en la codificación especificada y la decodifica, retornando lo que sea retornado por el códec.

Gracias a esta nueva función, se han añadido códecs para tareas no relacionadas directamente con Unicode. Por ejemplo, se han añadido códecs para la codificación uu, la codificación base64 de MIME y la compresión con el módulo zlib:

>>> s = """Here is a lengthy piece of redundant, overly verbose,
... and repetitive text.
... """
>>> data = s.encode('zlib')
>>> data
'x\x9c\r\xc9\xc1\r\x80 \x10\x04\xc0?Ul...'
>>> data.decode('zlib')
'Here is a lengthy piece of redundant, overly verbose,\nand repetitive text.\n'
>>> print s.encode('uu')
begin 666 <data>
M2&5R92!I<R!A(&QE;F=T:'D@<&EE8V4@;V8@<F5D=6YD86YT+"!O=F5R;'D@
>=F5R8F]S92P*86YD(')E<&5T:71I=F4@=&5X="X*

end
>>> "sheesh".encode('rot-13')
'furrfu'

Para convertir una instancia de clase a Unicode, se puede definir un método __unicode__() por clase, análogo a __str__().

encode(), decode(), y __unicode__() fueron implementados por Marc-André Lemburg. Los cambios para soportar el uso de UCS-4 internamente fueron implementados por Fredrik Lundh y Martin von Löwis.

Ver también

PEP 261 [https://www.python.org/dev/peps/pep-0261] - Soporte para caracteres Unicode “anchos”

Escrito por Paul Prescod.

PEP 227: Ámbitos anidados

En Python 2.1, los ámbitos anidados estáticamente se añadieron como una característica opcional, que se activaba mediante una directiva from __future__ import nested_scopes. En 2.2 los ámbitos anidados ya no necesitan ser habilitados especialmente, y ahora están siempre presentes. El resto de esta sección es una copia de la descripción de los ámbitos anidados de mi documento «What’s New in Python 2.1»; si lo leíste cuando salió la 2.1, puedes saltarte el resto de esta sección.

El mayor cambio introducido en Python 2.1, y completado en 2.2, es el de las reglas de alcance de Python. En Python 2.0, en cualquier momento hay como máximo tres espacios de nombres utilizados para buscar nombres de variables: local, a nivel de módulo y el espacio de nombres incorporado. Esto a menudo sorprendía a la gente porque no coincidía con sus expectativas intuitivas. Por ejemplo, una definición de función recursiva anidada no funciona:

def f():
    ...
    def g(value):
        ...
        return g(value-1) + 1
    ...

La función g() siempre lanzará una excepción NameError, porque el enlace del nombre g no está ni en su espacio de nombres local ni en el espacio de nombres a nivel de módulo. Esto no es un gran problema en la práctica (¿con qué frecuencia se definen recursivamente funciones interiores como ésta?), pero esto también hacía más torpe el uso de la expresión lambda, y esto era un problema en la práctica. En el código que utiliza lambda a menudo se pueden encontrar variables locales que se copian al pasarlas como valores por defecto de los argumentos.

def find(self, name):
    "Return list of any entries equal to 'name'"
    L = filter(lambda x, name=name: x == name,
               self.list_attribute)
    return L

La legibilidad del código Python escrito en un estilo fuertemente funcional sufre mucho como resultado.

El cambio más significativo de Python 2.2 es que se ha añadido al lenguaje el ámbito estático para solucionar este problema. Como primer efecto, el argumento por defecto name=name es ahora innecesario en el ejemplo anterior. En pocas palabras, cuando a un nombre de variable dado no se le asigna un valor dentro de una función (mediante una asignación, o las sentencias def, class, o import), las referencias a la variable se buscarán en el espacio de nombres local del ámbito que la rodea. Puede encontrar una explicación más detallada de las reglas y una disección de la implementación en el PEP.

Este cambio puede causar algunos problemas de compatibilidad para el código en el que el mismo nombre de variable se utiliza tanto a nivel de módulo como de variable local dentro de una función que contiene otras definiciones de función. Sin embargo, esto parece bastante improbable, ya que dicho código habría sido bastante confuso de leer en primer lugar.

Un efecto secundario del cambio es que las sentencias from module import * y exec se han hecho ilegales dentro del ámbito de una función bajo ciertas condiciones. El manual de referencia de Python ha dicho todo el tiempo que from module import * sólo es legal en el nivel superior de un módulo, pero el intérprete de CPython nunca ha aplicado esto antes. Como parte de la implementación de los ámbitos anidados, el compilador que convierte el código fuente de Python en bytecodes tiene que generar un código diferente para acceder a las variables de un ámbito contenedor. Los códigos from module import * y exec hacen que el compilador no pueda averiguar esto, porque añaden nombres al espacio de nombres local que son desconocidos en tiempo de compilación. Por lo tanto, si una función contiene definiciones de funciones o expresiones lambda con variables libres, el compilador lo señalará lanzando una excepción SyntaxError.

Para que la explicación anterior quede un poco más clara, he aquí un ejemplo:

x = 1
def f():
    # The next line is a syntax error
    exec 'x=2'
    def g():
        return x

La línea 4 que contiene la sentencia exec es un error de sintaxis, ya que exec definiría una nueva variable local llamada x cuyo valor debería ser accedido por g().

Esto no debería ser una gran limitación, ya que exec rara vez se utiliza en la mayoría del código de Python (y cuando se utiliza, a menudo es un signo de un mal diseño de todos modos).

Ver también

PEP 227 [https://www.python.org/dev/peps/pep-0227] - Ámbitos anidados estáticamente

Escrito e implementado por Jeremy Hylton.

Módulos nuevos y mejorados

El módulo xmlrpclib fue aportado a la biblioteca estándar por Fredrik Lundh, proporcionando soporte para escribir clientes XML-RPC. XML-RPC es un sencillo protocolo de llamada a procedimientos remotos construido sobre HTTP y XML. Por ejemplo, el siguiente fragmento recupera una lista de canales RSS de la red O’Reilly y, a continuación, muestra los titulares recientes de un canal:

import xmlrpclib
s = xmlrpclib.Server(
      'http://www.oreillynet.com/meerkat/xml-rpc/server.php')
channels = s.meerkat.getChannels()
# channels is a list of dictionaries, like this:
# [{'id': 4, 'title': 'Freshmeat Daily News'}
#  {'id': 190, 'title': '32Bits Online'},
#  {'id': 4549, 'title': '3DGamers'}, ... ]

# Get the items for one channel
items = s.meerkat.getItems( {'channel': 4} )

# 'items' is another list of dictionaries, like this:
# [{'link': 'http://freshmeat.net/releases/52719/',
#   'description': 'A utility which converts HTML to XSL FO.',
#   'title': 'html2fo 0.3 (Default)'}, ... ]

El módulo SimpleXMLRPCServer facilita la creación de servidores XML-RPC sencillos. Consulte http://xmlrpc.scripting.com/ para obtener más información sobre XML-RPC.

El nuevo módulo hmac implementa el algoritmo HMAC descrito por RFC 2104 [https://tools.ietf.org/html/rfc2104.html]. (Contribución de Gerhard Häring)

Varias funciones que originalmente retornaban tuplas largas ahora retornan pseudo-secuencias que siguen comportándose como tuplas pero que también tienen atributos mnemónicos como memberst_mtime o tm_year. Las funciones mejoradas incluyen stat(), fstat(), statvfs() y fstatvfs() en el módulo os, y localtime(), gmtime() y strptime() en el módulo time.

Por ejemplo, para obtener el tamaño de un archivo utilizando las antiguas tuplas, se terminaba escribiendo algo como tamaño_de_archivo = os.stat(nombre_de_archivo)[stat.ST_SIZE], pero ahora se puede escribir más claramente como tamaño_de_archivo = os.stat(nombre_de_archivo).st_size.

El parche original para esta función fue aportado por Nick Mathewson.

El perfilador de Python ha sido ampliamente revisado y se han corregido varios errores en su salida. (Contribución de Fred L. Drake, Jr. y Tim Peters)

El módulo socket puede ser compilado para soportar IPv6; especifica la opción --enable-ipv6 al script configure de Python. (Contribución de Jun-ichiro «itojun» Hagino)

Se han añadido dos nuevos caracteres de formato al módulo struct para enteros de 64 bits en plataformas que soportan el tipo C long long. q es para un entero de 64 bits con signo, y Q es para uno sin signo. El valor se retorna en el tipo entero largo de Python. (Contribuido por Tim Peters.)

En el modo interactivo del intérprete, hay una nueva función incorporada help() que utiliza el módulo pydoc introducido en Python 2.1 para proporcionar ayuda interactiva. help() sin ningún argumento te sitúa en una utilidad de ayuda online, donde puedes introducir los nombres de las funciones, clases o módulos para leer su texto de ayuda. (Contribuido por Guido van Rossum, usando el módulo pydoc de Ka-Ping Yee)

Se han realizado varias correcciones de errores y mejoras de rendimiento en el motor SRE subyacente al módulo re. Por ejemplo, las funciones re.sub() y re.split() han sido reescritas en C. Otro parche contribuido acelera ciertos rangos de caracteres Unicode por un factor de dos, y un nuevo método finditer() que retorna un iterador sobre todas las coincidencias no superpuestas en una cadena dada. (El mantenimiento de SRE corre a cargo de Fredrik Lundh. El parche BIGCHARSET fue aportado por Martin von Löwis)

El módulo smtplib soporta ahora RFC 2487 [https://tools.ietf.org/html/rfc2487.html], «Secure SMTP over TLS», por lo que ahora es posible cifrar el tráfico SMTP entre un programa Python y el agente de transporte de correo que recibe un mensaje. smtplib también soporta la autenticación SMTP. (Contribución de Gerhard Häring)

El módulo imaplib, mantenido por Piers Lauder, tiene soporte para varias extensiones nuevas: la extensión NAMESPACE definida en RFC 2342 [https://tools.ietf.org/html/rfc2342.html], SORT, GETACL y SETACL. (Contribución de Anthony Baxter y Michel Pelletier)

El módulo rfc822 que analiza las direcciones de correo electrónico cumple ahora con RFC 2822 [https://tools.ietf.org/html/rfc2822.html], una actualización de RFC 822 [https://tools.ietf.org/html/rfc822.html]. (El nombre del módulo no se va a cambiar a rfc2822.) También se ha añadido un nuevo paquete, email, para analizar y generar mensajes de correo electrónico. (Contribuido por Barry Warsaw, y surgido de su trabajo en Mailman)

El módulo difflib contiene ahora una nueva clase Differ para producir listas legibles por humanos de cambios (un «delta») entre dos secuencias de líneas de texto. También hay dos funciones generadoras, ndiff() y restore(), que retornan respectivamente un delta de dos secuencias, o una de las secuencias originales de un delta. (Trabajo de gruñido contribuido por David Goodger, a partir del código ndiff.py de Tim Peters que luego hizo la generización)

Se han añadido las nuevas constantes ascii_letters, ascii_lowercase y ascii_uppercase al módulo string. Había varios módulos en la biblioteca estándar que utilizaban string.letters para referirse a los rangos A-Za-z, pero esa suposición es incorrecta cuando se utilizan locales, porque string.letters varía dependiendo del conjunto de caracteres legales definidos por el local actual. Los módulos con errores se han corregido para que utilicen ascii_letters en su lugar. (Informado por una persona desconocida; corregido por Fred L. Drake, Jr.)

El módulo mimetypes facilita ahora el uso de bases de datos de tipos MIME alternativos mediante la adición de una clase MimeTypes, que toma una lista de nombres de archivo para ser analizados. (Contribución de Fred L. Drake, Jr.)

Se ha añadido una clase Timer al módulo threading que permite programar una actividad para que ocurra en algún momento futuro. (Contribución de Itamar Shtull-Trauring)

Cambios y correcciones en el intérprete

Algunos de los cambios sólo afectan a la gente que trata con el intérprete de Python a nivel de C porque están escribiendo módulos de extensión de Python, incrustando el intérprete, o simplemente hackeando el propio intérprete. Si sólo escribes código Python, ninguno de los cambios descritos aquí te afectará mucho.

Las funciones de perfilado y rastreo pueden implementarse ahora en C, que puede operar a velocidades mucho mayores que las funciones basadas en Python y debería reducir la sobrecarga de perfilado y rastreo. Esto será de interés para los autores de entornos de desarrollo para Python. Se han añadido dos nuevas funciones en C a la API de Python, PyEval_SetProfile() y PyEval_SetTrace(). Las funciones sys.setprofile() y sys.settrace() existentes siguen existiendo, y simplemente se han cambiado para utilizar la nueva interfaz de nivel C. (Contribución de Fred L. Drake, Jr.)

Se ha añadido otra API de bajo nivel, principalmente de interés para los implementadores de depuradores y herramientas de desarrollo de Python. PyInterpreterState_Head() y PyInterpreterState_Next() permiten al usuario recorrer todos los objetos intérpretes existentes; PyInterpreterState_ThreadHead() y PyThreadState_Next() permiten recorrer todos los estados de los hilos de un intérprete dado. (Contribución de David Beazley)

La interfaz a nivel de C para el recolector de basura ha sido cambiada para facilitar la escritura de tipos de extensión que soporten la recolección de basura y para depurar los malos usos de las funciones. Varias funciones tienen una semántica ligeramente diferente, por lo que hubo que cambiar el nombre de un montón de funciones. Las extensiones que utilizan la antigua API seguirán compilando pero no participarán en la recolección de basura, por lo que actualizarlas para la 2.2 debería considerarse de alta prioridad.

Para actualizar un módulo de extensión a la nueva API, realice los siguientes pasos:

Cambia el nombre de Py_TPFLAGS_GC() a PyTPFLAGS_HAVE_GC().

Utilice PyObject_GC_New() o PyObject_GC_NewVar() para asignar

objetos, y PyObject_GC_Del() para desocuparlos.

Cambiar el nombre de PyObject_GC_Init() a PyObject_GC_Track() y

PyObject_GC_Fini() a PyObject_GC_UnTrack().

Eliminar PyGC_HEAD_SIZE() del cálculo del tamaño de los objetos.

Eliminar las llamadas a PyObject_AS_GC() y PyObject_FROM_GC().

Se ha añadido una nueva secuencia de formato et a PyArg_ParseTuple(); et toma tanto un parámetro como un nombre de codificación, y convierte el parámetro a la codificación dada si el parámetro resulta ser una cadena Unicode, o lo deja solo si es una cadena de 8 bits, asumiendo que ya está en la codificación deseada. Esto difiere del carácter de formato es, que asume que las cadenas de 8 bits están en la codificación ASCII por defecto de Python y las convierte a la nueva codificación especificada. (Contribuido por M.-A. Lemburg, y utilizado para el soporte de MBCS en Windows descrito en la siguiente sección)

Se ha añadido una función de análisis de argumentos diferente, PyArg_UnpackTuple(), que es más sencilla y presumiblemente más rápida. En lugar de especificar una cadena de formato, la persona que llama simplemente da el número mínimo y máximo de argumentos esperados, y un conjunto de punteros a variables PyObject* que se rellenarán con los valores de los argumentos.

Dos nuevos indicadores METH_NOARGS y METH_O están disponibles en las tablas de definición de métodos para simplificar la implementación de métodos sin argumentos o con un único argumento no tipado. Llamar a estos métodos es más eficiente que llamar a un método correspondiente que utilice METH_VARARGS. Además, el antiguo estilo METH_OLDARGS de escribir métodos en C está oficialmente en desuso.

Se han añadido dos nuevas funciones de envoltura, PyOS_snprintf() y PyOS_vsnprintf() para proporcionar implementaciones multiplataforma para las relativamente nuevas APIs de la biblioteca C snprintf() y vsnprintf(). A diferencia de las funciones estándar sprintf() y vsprintf(), las versiones de Python comprueban los límites del búfer utilizado para protegerse de los desbordamientos del mismo. (Contribución de M.-A. Lemburg.)

La función _PyTuple_Resize() ha perdido un parámetro que no se utilizaba, por lo que ahora toma 2 parámetros en lugar de 3. El tercer argumento nunca se utilizaba, y puede descartarse simplemente al portar el código de versiones anteriores a Python 2.2.

Otros cambios y correcciones

Como es habitual, hubo un montón de otras mejoras y correcciones de errores repartidas por todo el árbol de fuentes. Una búsqueda en los registros de cambios de CVS revela que se aplicaron 527 parches y se corrigieron 683 errores entre Python 2.1 y 2.2; en 2.2.1 se aplicaron 139 parches y se corrigieron 143 errores; en 2.2.2 se aplicaron 106 parches y se corrigieron 82 errores. Es probable que estas cifras estén subestimadas.

Algunos de los cambios más notables son:

El código del puerto MacOS para Python, mantenido por Jack Jansen, se mantiene ahora en el árbol CVS principal de Python, y se han realizado muchos cambios para soportar MacOS X.

El cambio más significativo es la capacidad de construir Python como un marco de trabajo, que se activa proporcionando la opción --enable-framework al script de configuración cuando se compila Python. Según Jack Jansen, «Esto instala una instalación autónoma de Python más el «pegamento» del framework de OS X en /Library/Frameworks/Python.framework (o en otra ubicación de su elección). Por ahora hay poco beneficio inmediato añadido a esto (en realidad, existe la desventaja de que tienes que cambiar tu PATH para poder encontrar Python), pero es la base para crear una aplicación Python completa, portar el IDE de MacPython, posiblemente usar Python como un lenguaje de scripting estándar de OSA y mucho más.»

La mayoría de los módulos de la caja de herramientas de MacPython, que interactúan con las APIs de MacOS como ventanas, QuickTime, scripts, etc. han sido portados a OS X, pero se han dejado comentados en setup.py. Las personas que quieran experimentar con estos módulos pueden descomentarlos manualmente.

Los argumentos de palabras clave pasados a funciones incorporadas que no los aceptan ahora provocan una excepción TypeError, con el mensaje «function no acepta argumentos de palabras clave».

Las referencias débiles, añadidas en Python 2.1 como un módulo de extensión, son ahora parte del núcleo porque se utilizan en la implementación de clases de nuevo estilo. Por lo tanto, la excepción ReferenceError se ha movido del módulo weakref para convertirse en una excepción incorporada.

Un nuevo script, Tools/scripts/cleanfuture.py de Tim Peters, elimina automáticamente las sentencias __future__ obsoletas del código fuente de Python.

Se ha añadido un argumento adicional flags a la función incorporada compile(), por lo que el comportamiento de las sentencias __future__ puede ahora observarse correctamente en shells simulados, como los presentados por IDLE y otros entornos de desarrollo. Esto se describe en PEP 264 [https://www.python.org/dev/peps/pep-0264]. (Contribución de Michael Hudson)

La nueva licencia introducida con Python 1.6 no era compatible con la GPL. Esto se ha solucionado con algunos cambios textuales menores en la licencia 2.2, de modo que ahora es legal volver a incrustar Python dentro de un programa con licencia GPL. Tenga en cuenta que Python en sí mismo no es GPL, sino que está bajo una licencia que es esencialmente equivalente a la licencia BSD, igual que siempre. Los cambios en la licencia también se aplicaron a las versiones 2.0.1 y 2.1.1 de Python.

Cuando se presenta un nombre de archivo Unicode en Windows, Python ahora lo convertirá en una cadena codificada en MBCS, como la que utilizan las APIs de archivos de Microsoft. Como las APIs de archivos utilizan explícitamente MBCS, la elección de Python de ASCII como codificación por defecto resulta ser una molestia. En Unix, se utiliza el juego de caracteres de la localización si locale.nl_langinfo(CODESET) está disponible. (El soporte de Windows fue contribuido por Mark Hammond con la ayuda de Marc-André Lemburg. El soporte para Unix fue añadido por Martin von Löwis)

La compatibilidad con archivos de gran tamaño ya está activada en Windows. (Contribución de Tim Peters.)

El script Tools/scripts/ftpmirror.py ahora analiza un archivo .netrc, si tiene uno. (Contribución de Mike Romberg)

Algunas características del objeto retornado por la función xrange() están ahora obsoletas, y provocan advertencias cuando se accede a ellas; desaparecerán en Python 2.3. Los objetos xrange intentaban fingir que eran tipos de secuencia completos soportando el troceado, la multiplicación de secuencias y el operador in, pero estas características se utilizaban raramente y, por lo tanto, tenían errores. El método tolist() y los atributos start, stop y step también han quedado obsoletos. A nivel de C, el cuarto argumento de la función PyRange_New(), repeat, también ha quedado obsoleto.

Hubo un montón de parches para la implementación del diccionario, sobre todo para arreglar posibles vertidos del núcleo si un diccionario contiene objetos que cambian furtivamente su valor hash, o mutan el diccionario que contienen. Durante un tiempo python-dev cayó en un suave ritmo de Michael Hudson encontrando un caso que volcaba el núcleo, Tim Peters corrigiendo el error, Michael encontrando otro caso, y así sucesivamente.

En Windows, Python puede ahora compilarse con Borland C gracias a una serie de parches aportados por Stephen Hansen, aunque el resultado aún no es totalmente funcional. (Pero esto es un progreso…)

Otra mejora de Windows: Wise Solutions ofreció generosamente a PythonLabs el uso de su sistema InstallerMaster 8.1. Los anteriores instaladores de PythonLabs para Windows utilizaban Wise 5.0a, que estaba empezando a mostrar su edad. (Empaquetado por Tim Peters)

Los archivos que terminan en .pyw pueden importarse ahora en Windows. .pyw es algo exclusivo de Windows, que se utiliza para indicar que un script debe ejecutarse utilizando PYTHONW.EXE en lugar de PYTHON.EXE para evitar que aparezca una consola DOS para mostrar la salida. Este parche hace posible la importación de tales scripts, en caso de que también se puedan utilizar como módulos. (Implementado por David Bolen)

En las plataformas en las que Python utiliza la función C dlopen() para cargar módulos de extensión, ahora es posible establecer las banderas utilizadas por dlopen() utilizando las funciones sys.getdlopenflags() y sys.setdlopenflags(). (Contribución de Bram Stolk.)

La función incorporada pow() ya no admite 3 argumentos cuando se suministran números de punto flotante. pow(x, y, z) retorna (x**y) % z, pero esto nunca es útil para números de punto flotante, y el resultado final varía de forma impredecible dependiendo de la plataforma. Una llamada como pow(2.0, 8.0, 7.0) lanzará ahora una excepción TypeError.

Agradecimientos

El autor desea agradecer a las siguientes personas sus sugerencias, correcciones y ayuda en varios borradores de este artículo: Fred Bremmer, Keith Briggs, Andrew Dalke, Fred L. Drake, Jr, Carel Fellinger, David Goodger, Mark Hammond, Stephen Hansen, Michael Hudson, Jack Jansen, Marc-André Lemburg, Martin von Löwis, Fredrik Lundh, Michael McLay, Nick Mathewson, Paul Moore, Gustavo Niemeyer, Don O’Donnell, Joonas Paalasma, Tim Peters, Jens Quade, Tom Reinhardt, Neil Schemenauer, Guido van Rossum, Greg Ward, Edward Welbourne.

Novedades de Python 2.1

Autor

A.M. Kuchling

Introducción

This article explains the new features in Python 2.1. While there aren’t as many changes in 2.1 as there were in Python 2.0, there are still some pleasant surprises in store. 2.1 is the first release to be steered through the use of Python Enhancement Proposals, or PEPs, so most of the sizable changes have accompanying PEPs that provide more complete documentation and a design rationale for the change. This article doesn’t attempt to document the new features completely, but simply provides an overview of the new features for Python programmers. Refer to the Python 2.1 documentation, or to the specific PEP, for more details about any new feature that particularly interests you.

Un objetivo reciente del equipo de desarrollo de Python ha sido acelerar el ritmo de las nuevas versiones, con una nueva versión cada 6 a 9 meses. La versión 2.1 es la primera que sale a este ritmo más rápido, con la primera alfa que apareció en enero, 3 meses después de que se publicara la versión final de la 2.0.

La versión final de Python 2.1 se realizó el 17 de abril de 2001.

PEP 227: Ámbitos anidados

The largest change in Python 2.1 is to Python’s scoping rules. In Python 2.0, at any given time there are at most three namespaces used to look up variable names: local, module-level, and the built-in namespace. This often surprised people because it didn’t match their intuitive expectations. For example, a nested recursive function definition doesn’t work:

def f():
    ...
    def g(value):
        ...
        return g(value-1) + 1
    ...

The function g() will always raise a NameError exception, because the binding of the name g isn’t in either its local namespace or in the module-level namespace. This isn’t much of a problem in practice (how often do you recursively define interior functions like this?), but this also made using the lambda expression clumsier, and this was a problem in practice. In code which uses lambda you can often find local variables being copied by passing them as the default values of arguments.

def find(self, name):
    "Return list of any entries equal to 'name'"
    L = filter(lambda x, name=name: x == name,
               self.list_attribute)
    return L

La legibilidad del código Python escrito en un estilo fuertemente funcional sufre mucho como resultado.

The most significant change to Python 2.1 is that static scoping has been added to the language to fix this problem. As a first effect, the name=name default argument is now unnecessary in the above example. Put simply, when a given variable name is not assigned a value within a function (by an assignment, or the def, class, or import statements), references to the variable will be looked up in the local namespace of the enclosing scope. A more detailed explanation of the rules, and a dissection of the implementation, can be found in the PEP.

Este cambio puede causar algunos problemas de compatibilidad para el código en el que el mismo nombre de variable se utiliza tanto a nivel de módulo como de variable local dentro de una función que contiene otras definiciones de función. Sin embargo, esto parece bastante improbable, ya que dicho código habría sido bastante confuso de leer en primer lugar.

One side effect of the change is that the from module import * and exec statements have been made illegal inside a function scope under certain conditions. The Python reference manual has said all along that from module import * is only legal at the top level of a module, but the CPython interpreter has never enforced this before. As part of the implementation of nested scopes, the compiler which turns Python source into bytecodes has to generate different code to access variables in a containing scope. from module import * and exec make it impossible for the compiler to figure this out, because they add names to the local namespace that are unknowable at compile time. Therefore, if a function contains function definitions or lambda expressions with free variables, the compiler will flag this by raising a SyntaxError exception.

Para que la explicación anterior quede un poco más clara, he aquí un ejemplo:

x = 1
def f():
    # The next line is a syntax error
    exec 'x=2'
    def g():
        return x

La línea 4 que contiene la sentencia exec es un error de sintaxis, ya que exec definiría una nueva variable local llamada x cuyo valor debería ser accedido por g().

Esto no debería ser una gran limitación, ya que exec rara vez se utiliza en la mayoría del código de Python (y cuando se utiliza, a menudo es un signo de un mal diseño de todos modos).

Compatibility concerns have led to nested scopes being introduced gradually; in Python 2.1, they aren’t enabled by default, but can be turned on within a module by using a future statement as described in PEP 236 [https://www.python.org/dev/peps/pep-0236]. (See the following section for further discussion of PEP 236 [https://www.python.org/dev/peps/pep-0236].) In Python 2.2, nested scopes will become the default and there will be no way to turn them off, but users will have had all of 2.1’s lifetime to fix any breakage resulting from their introduction.

Ver también

PEP 227 [https://www.python.org/dev/peps/pep-0227] - Ámbitos anidados estáticamente

Escrito e implementado por Jeremy Hylton.

PEP 236: Directivas __future__

The reaction to nested scopes was widespread concern about the dangers of breaking code with the 2.1 release, and it was strong enough to make the Pythoneers take a more conservative approach. This approach consists of introducing a convention for enabling optional functionality in release N that will become compulsory in release N+1.

The syntax uses a from...import statement using the reserved module name __future__. Nested scopes can be enabled by the following statement:

from __future__ import nested_scopes

While it looks like a normal import statement, it’s not; there are strict rules on where such a future statement can be put. They can only be at the top of a module, and must precede any Python code or regular import statements. This is because such statements can affect how the Python bytecode compiler parses code and generates bytecode, so they must precede any statement that will result in bytecodes being produced.

Ver también

PEP 236 [https://www.python.org/dev/peps/pep-0236] - De vuelta al __future__

Escrito por Tim Peters, y ejecutado principalmente por Jeremy Hylton.

PEP 207: Comparaciones Enriquecidas

In earlier versions, Python’s support for implementing comparisons on user-defined classes and extension types was quite simple. Classes could implement a __cmp__() method that was given two instances of a class, and could only return 0 if they were equal or +1 or -1 if they weren’t; the method couldn’t raise an exception or return anything other than a Boolean value. Users of Numeric Python often found this model too weak and restrictive, because in the number-crunching programs that numeric Python is used for, it would be more useful to be able to perform elementwise comparisons of two matrices, returning a matrix containing the results of a given comparison for each element. If the two matrices are of different sizes, then the compare has to be able to raise an exception to signal the error.

In Python 2.1, rich comparisons were added in order to support this need. Python classes can now individually overload each of the <, <=, >, >=, ==, and != operations. The new magic method names are:

Operación

Nombre del método

<

__lt__()

<=

__le__()

>

__gt__()

>=

__ge__()

==

__eq__()

!=

__ne__()

(The magic methods are named after the corresponding Fortran operators .LT.. .LE., &c. Numeric programmers are almost certainly quite familiar with these names and will find them easy to remember.)

Each of these magic methods is of the form method(self, other), where self will be the object on the left-hand side of the operator, while other will be the object on the right-hand side. For example, the expression A < B will cause A.__lt__(B) to be called.

Each of these magic methods can return anything at all: a Boolean, a matrix, a list, or any other Python object. Alternatively they can raise an exception if the comparison is impossible, inconsistent, or otherwise meaningless.

The built-in cmp(A,B) function can use the rich comparison machinery, and now accepts an optional argument specifying which comparison operation to use; this is given as one of the strings "<", "<=", ">", ">=", "==", or "!=". If called without the optional third argument, cmp() will only return -1, 0, or +1 as in previous versions of Python; otherwise it will call the appropriate method and can return any Python object.

There are also corresponding changes of interest to C programmers; there’s a new slot tp_richcmp in type objects and an API for performing a given rich comparison. I won’t cover the C API here, but will refer you to PEP 207 [https://www.python.org/dev/peps/pep-0207], or to 2.1’s C API documentation, for the full list of related functions.

Ver también

PEP 207 [https://www.python.org/dev/peps/pep-0207] - Comparaciones enriquecidas

Escrito por Guido van Rossum, basado en gran medida en un trabajo anterior de David Ascher, e implementado por Guido van Rossum.

PEP 230: Marco de advertencia

Over its 10 years of existence, Python has accumulated a certain number of obsolete modules and features along the way. It’s difficult to know when a feature is safe to remove, since there’s no way of knowing how much code uses it — perhaps no programs depend on the feature, or perhaps many do. To enable removing old features in a more structured way, a warning framework was added. When the Python developers want to get rid of a feature, it will first trigger a warning in the next version of Python. The following Python version can then drop the feature, and users will have had a full release cycle to remove uses of the old feature.

Python 2.1 adds the warning framework to be used in this scheme. It adds a warnings module that provide functions to issue warnings, and to filter out warnings that you don’t want to be displayed. Third-party modules can also use this framework to deprecate old features that they no longer wish to support.

Por ejemplo, en Python 2.1 el módulo regex está obsoleto, por lo que al importarlo se imprime una advertencia:

>>> import regex
__main__:1: DeprecationWarning: the regex module
         is deprecated; please use the re module
>>>

Las advertencias se pueden emitir llamando a la función warnings.warn():

warnings.warn("feature X no longer supported")

El primer parámetro es el mensaje de advertencia; se pueden utilizar otros parámetros opcionales para especificar una categoría de advertencia concreta.

Filters can be added to disable certain warnings; a regular expression pattern can be applied to the message or to the module name in order to suppress a warning. For example, you may have a program that uses the regex module and not want to spare the time to convert it to use the re module right now. The warning can be suppressed by calling

import warnings
warnings.filterwarnings(action = 'ignore',
                        message='.*regex module is deprecated',
                        category=DeprecationWarning,
                        module = '__main__')

This adds a filter that will apply only to warnings of the class DeprecationWarning triggered in the __main__ module, and applies a regular expression to only match the message about the regex module being deprecated, and will cause such warnings to be ignored. Warnings can also be printed only once, printed every time the offending code is executed, or turned into exceptions that will cause the program to stop (unless the exceptions are caught in the usual way, of course).

También se agregaron funciones a la API de C de Python para emitir advertencias; consulte el PEP 230 o la documentación de la API de Python para conocer los detalles.

Ver también

PEP 5 [https://www.python.org/dev/peps/pep-0005] - Directrices para la evolución del lenguaje

Written by Paul Prescod, to specify procedures to be followed when removing old features from Python. The policy described in this PEP hasn’t been officially adopted, but the eventual policy probably won’t be too different from Prescod’s proposal.

PEP 230 [https://www.python.org/dev/peps/pep-0230] - Marco de advertencia

Escrito y ejecutado por Guido van Rossum.

PEP 229: Sistema de construcción nuevo

Al compilar Python, el usuario tenía que entrar y editar el archivo Modules/Setup para habilitar varios módulos adicionales; el conjunto por defecto es relativamente pequeño y se limita a los módulos que se compilan en la mayoría de las plataformas Unix. Esto significa que en plataformas Unix con muchas más características, sobre todo Linux, las instalaciones de Python no suelen contener todos los módulos útiles que podrían.

Python 2.0 added the Distutils, a set of modules for distributing and installing extensions. In Python 2.1, the Distutils are used to compile much of the standard library of extension modules, autodetecting which ones are supported on the current machine. It’s hoped that this will make Python installations easier and more featureful.

Instead of having to edit the Modules/Setup file in order to enable modules, a setup.py script in the top directory of the Python source distribution is run at build time, and attempts to discover which modules can be enabled by examining the modules and header files on the system. If a module is configured in Modules/Setup, the setup.py script won’t attempt to compile that module and will defer to the Modules/Setup file’s contents. This provides a way to specific any strange command-line flags or libraries that are required for a specific platform.

In another far-reaching change to the build mechanism, Neil Schemenauer restructured things so Python now uses a single makefile that isn’t recursive, instead of makefiles in the top directory and in each of the Python/, Parser/, Objects/, and Modules/ subdirectories. This makes building Python faster and also makes hacking the Makefiles clearer and simpler.

Ver también

PEP 229 [https://www.python.org/dev/peps/pep-0229] - Uso de Distutils para construir Python

Escrito y ejecutado por A.M. Kuchling.

PEP 205: Referencias débiles

Las referencias débiles, disponibles a través del módulo weakref, son un nuevo tipo de datos menor pero útil en la caja de herramientas del programador de Python.

Storing a reference to an object (say, in a dictionary or a list) has the side effect of keeping that object alive forever. There are a few specific cases where this behaviour is undesirable, object caches being the most common one, and another being circular references in data structures such as trees.

Por ejemplo, considere una función de memoización que almacena en caché los resultados de otra función f(x) almacenando el argumento de la función y su resultado en un diccionario:

_cache = {}
def memoize(x):
    if _cache.has_key(x):
        return _cache[x]

    retval = f(x)

    # Cache the returned object
    _cache[x] = retval

    return retval

Esta versión funciona para cosas simples como los enteros, pero tiene un efecto secundario; el diccionario _cache mantiene una referencia a los valores retornados, por lo que nunca serán desocupados hasta que el proceso de Python salga y se limpie. Esto no es muy notable para los enteros, pero si f() retorna un objeto, o una estructura de datos que ocupa mucha memoria, esto puede ser un problema.

Weak references provide a way to implement a cache that won’t keep objects alive beyond their time. If an object is only accessible through weak references, the object will be deallocated and the weak references will now indicate that the object it referred to no longer exists. A weak reference to an object obj is created by calling wr = weakref.ref(obj). The object being referred to is returned by calling the weak reference as if it were a function: wr(). It will return the referenced object, or None if the object no longer exists.

Esto hace posible escribir una función memoize() cuya caché no mantenga objetos vivos, almacenando referencias débiles en la caché.

_cache = {}
def memoize(x):
    if _cache.has_key(x):
        obj = _cache[x]()
        # If weak reference object still exists,
        # return it
        if obj is not None: return obj

    retval = f(x)

    # Cache a weak reference
    _cache[x] = weakref.ref(retval)

    return retval

The weakref module also allows creating proxy objects which behave like weak references — an object referenced only by proxy objects is deallocated – but instead of requiring an explicit call to retrieve the object, the proxy transparently forwards all operations to the object as long as the object still exists. If the object is deallocated, attempting to use a proxy will cause a weakref.ReferenceError exception to be raised.

proxy = weakref.proxy(obj)
proxy.attr   # Equivalent to obj.attr
proxy.meth() # Equivalent to obj.meth()
del obj
proxy.attr   # raises weakref.ReferenceError

Ver también

PEP 205 [https://www.python.org/dev/peps/pep-0205] - Referencias débiles

Escrito e implementado por Fred L. Drake, Jr.

PEP 232: Atributos de la función

In Python 2.1, functions can now have arbitrary information attached to them. People were often using docstrings to hold information about functions and methods, because the __doc__ attribute was the only way of attaching any information to a function. For example, in the Zope Web application server, functions are marked as safe for public access by having a docstring, and in John Aycock’s SPARK parsing framework, docstrings hold parts of the BNF grammar to be parsed. This overloading is unfortunate, since docstrings are really intended to hold a function’s documentation; for example, it means you can’t properly document functions intended for private use in Zope.

Ahora se pueden establecer y recuperar atributos arbitrarios en las funciones utilizando la sintaxis normal de Python:

def f(): pass

f.publish = 1
f.secure = 1
f.grammar = "A ::= B (C D)*"

Se puede acceder al diccionario que contiene los atributos como __dict__ de la función. A diferencia del atributo __dict__ de las instancias de clase, en las funciones se puede asignar un nuevo diccionario a __dict__, aunque el nuevo valor está restringido a un diccionario normal de Python; no se puede ser complicado y establecerlo como una instancia de UserDict, o cualquier otro objeto aleatorio que se comporte como un mapeo.

Ver también

PEP 232 [https://www.python.org/dev/peps/pep-0232] - Atributos de la función

Escrito y ejecutado por Barry Warsaw.

PEP 235: Importación de módulos en plataformas que no distinguen entre mayúsculas y minúsculas

Algunos sistemas operativos tienen sistemas de archivos que no distinguen entre mayúsculas y minúsculas, siendo MacOS y Windows los principales ejemplos; en estos sistemas, es imposible distinguir los nombres de archivo FILE.PY y file.py, aunque almacenan el nombre del archivo en su caso original (también preservan las mayúsculas).

In Python 2.1, the import statement will work to simulate case-sensitivity on case-insensitive platforms. Python will now search for the first case-sensitive match by default, raising an ImportError if no such file is found, so import file will not import a module named FILE.PY. Case-insensitive matching can be requested by setting the PYTHONCASEOK environment variable before starting the Python interpreter.

PEP 217: Gancho de pantalla interactivo

Cuando se utiliza el intérprete de Python de forma interactiva, la salida de los comandos se muestra utilizando la función incorporada repr(). En Python 2.1, la variable sys.displayhook() puede establecerse a un objeto invocable que será llamado en lugar de repr(). Por ejemplo, puede establecerla a una función especial de impresión bonita:

>>> # Create a recursive data structure
... L = [1,2,3]
>>> L.append(L)
>>> L # Show Python's default output
[1, 2, 3, [...]]
>>> # Use pprint.pprint() as the display function
... import sys, pprint
>>> sys.displayhook = pprint.pprint
>>> L
[1, 2, 3,  <Recursion on list with id=135143996>]
>>>

Ver también

PEP 217 [https://www.python.org/dev/peps/pep-0217] - Gancho de visualización para uso interactivo

Escrito y ejecutado por Moshe Zadka.

PEP 208: Nuevo modelo de coerción

How numeric coercion is done at the C level was significantly modified. This will only affect the authors of C extensions to Python, allowing them more flexibility in writing extension types that support numeric operations.

Extension types can now set the type flag Py_TPFLAGS_CHECKTYPES in their PyTypeObject structure to indicate that they support the new coercion model. In such extension types, the numeric slot functions can no longer assume that they’ll be passed two arguments of the same type; instead they may be passed two arguments of differing types, and can then perform their own internal coercion. If the slot function is passed a type it can’t handle, it can indicate the failure by returning a reference to the Py_NotImplemented singleton value. The numeric functions of the other type will then be tried, and perhaps they can handle the operation; if the other type also returns Py_NotImplemented, then a TypeError will be raised. Numeric methods written in Python can also return Py_NotImplemented, causing the interpreter to act as if the method did not exist (perhaps raising a TypeError, perhaps trying another object’s numeric methods).

Ver también

PEP 208 [https://www.python.org/dev/peps/pep-0208] - Reformulación del modelo de coerción

Written and implemented by Neil Schemenauer, heavily based upon earlier work by Marc-André Lemburg. Read this to understand the fine points of how numeric operations will now be processed at the C level.

PEP 241: Metadatos en paquetes de Python

A common complaint from Python users is that there’s no single catalog of all the Python modules in existence. T. Middleton’s Vaults of Parnassus at http://www.vex.net/parnassus/ are the largest catalog of Python modules, but registering software at the Vaults is optional, and many people don’t bother.

As a first small step toward fixing the problem, Python software packaged using the Distutils sdist command will include a file named PKG-INFO containing information about the package such as its name, version, and author (metadata, in cataloguing terminology). PEP 241 [https://www.python.org/dev/peps/pep-0241] contains the full list of fields that can be present in the PKG-INFO file. As people began to package their software using Python 2.1, more and more packages will include metadata, making it possible to build automated cataloguing systems and experiment with them. With the result experience, perhaps it’ll be possible to design a really good catalog and then build support for it into Python 2.2. For example, the Distutils sdist and bdist_* commands could support an upload option that would automatically upload your package to a catalog server.

You can start creating packages containing PKG-INFO even if you’re not using Python 2.1, since a new release of the Distutils will be made for users of earlier Python versions. Version 1.0.2 of the Distutils includes the changes described in PEP 241 [https://www.python.org/dev/peps/pep-0241], as well as various bugfixes and enhancements. It will be available from the Distutils SIG at https://www.python.org/community/sigs/current/distutils-sig/.

Ver también

PEP 241 [https://www.python.org/dev/peps/pep-0241] - Metadatos para paquetes de software de Python

Escrito y ejecutado por A.M. Kuchling.

PEP 243 [https://www.python.org/dev/peps/pep-0243] - Mecanismo de carga del repositorio de módulos

Escrito por Sean Reifschneider, este borrador de PEP describe un mecanismo propuesto para subir paquetes de Python a un servidor central.

Módulos nuevos y mejorados

Ka-Ping Yee contributed two new modules: inspect.py, a module for getting information about live Python code, and pydoc.py, a module for interactively converting docstrings to HTML or text. As a bonus, Tools/scripts/pydoc, which is now automatically installed, uses pydoc.py to display documentation given a Python module, package, or class name. For example, pydoc xml.dom displays the following:

Python Library Documentation: package xml.dom in xml

NAME
    xml.dom - W3C Document Object Model implementation for Python.

FILE
    /usr/local/lib/python2.1/xml/dom/__init__.pyc

DESCRIPTION
    The Python mapping of the Document Object Model is documented in the
    Python Library Reference in the section on the xml.dom package.

    This package contains the following modules:
      ...

pydoc also includes a Tk-based interactive help browser. pydoc quickly becomes addictive; try it out!

Two different modules for unit testing were added to the standard library. The doctest module, contributed by Tim Peters, provides a testing framework based on running embedded examples in docstrings and comparing the results against the expected output. PyUnit, contributed by Steve Purcell, is a unit testing framework inspired by JUnit, which was in turn an adaptation of Kent Beck’s Smalltalk testing framework. See http://pyunit.sourceforge.net/ for more information about PyUnit.

The difflib module contains a class, SequenceMatcher, which compares two sequences and computes the changes required to transform one sequence into the other. For example, this module can be used to write a tool similar to the Unix diff program, and in fact the sample program Tools/scripts/ndiff.py demonstrates how to write such a script.

curses.panel, a wrapper for the panel library, part of ncurses and of SYSV curses, was contributed by Thomas Gellekum. The panel library provides windows with the additional feature of depth. Windows can be moved higher or lower in the depth ordering, and the panel library figures out where panels overlap and which sections are visible.

The PyXML package has gone through a few releases since Python 2.0, and Python 2.1 includes an updated version of the xml package. Some of the noteworthy changes include support for Expat 1.2 and later versions, the ability for Expat parsers to handle files in any encoding supported by Python, and various bugfixes for SAX, DOM, and the minidom module.

Ping also contributed another hook for handling uncaught exceptions. sys.excepthook() can be set to a callable object. When an exception isn’t caught by any try…except blocks, the exception will be passed to sys.excepthook(), which can then do whatever it likes. At the Ninth Python Conference, Ping demonstrated an application for this hook: printing an extended traceback that not only lists the stack frames, but also lists the function arguments and the local variables for each frame.

Various functions in the time module, such as asctime() and localtime(), require a floating point argument containing the time in seconds since the epoch. The most common use of these functions is to work with the current time, so the floating point argument has been made optional; when a value isn’t provided, the current time will be used. For example, log file entries usually need a string containing the current time; in Python 2.1, time.asctime() can be used, instead of the lengthier time.asctime(time.localtime(time.time())) that was previously required.

Este cambio fue propuesto y aplicado por Thomas Wouters.

The ftplib module now defaults to retrieving files in passive mode, because passive mode is more likely to work from behind a firewall. This request came from the Debian bug tracking system, since other Debian packages use ftplib to retrieve files and then don’t work from behind a firewall. It’s deemed unlikely that this will cause problems for anyone, because Netscape defaults to passive mode and few people complain, but if passive mode is unsuitable for your application or network setup, call set_pasv(0) on FTP objects to disable passive mode.

Se ha añadido soporte para el acceso a sockets sin procesar en el módulo socket, aportado por Grant Edwards.

The pstats module now contains a simple interactive statistics browser for displaying timing profiles for Python programs, invoked when the module is run as a script. Contributed by Eric S. Raymond.

A new implementation-dependent function, sys._getframe([depth]), has been added to return a given frame object from the current call stack. sys._getframe() returns the frame at the top of the call stack; if the optional integer argument depth is supplied, the function returns the frame that is depth calls below the top of the stack. For example, sys._getframe(1) returns the caller’s frame object.

This function is only present in CPython, not in Jython or the .NET implementation. Use it for debugging, and resist the temptation to put it into production code.

Otros cambios y correcciones

There were relatively few smaller changes made in Python 2.1 due to the shorter release cycle. A search through the CVS change logs turns up 117 patches applied, and 136 bugs fixed; both figures are likely to be underestimates. Some of the more notable changes are:

A specialized object allocator is now optionally available, that should be faster than the system malloc() and have less memory overhead. The allocator uses C’s malloc() function to get large pools of memory, and then fulfills smaller memory requests from these pools. It can be enabled by providing the --with-pymalloc option to the configure script; see Objects/obmalloc.c for the implementation details.

Authors of C extension modules should test their code with the object allocator enabled, because some incorrect code may break, causing core dumps at runtime. There are a bunch of memory allocation functions in Python’s C API that have previously been just aliases for the C library’s malloc() and free(), meaning that if you accidentally called mismatched functions, the error wouldn’t be noticeable. When the object allocator is enabled, these functions aren’t aliases of malloc() and free() any more, and calling the wrong function to free memory will get you a core dump. For example, if memory was allocated using PyMem_New(), it has to be freed using PyMem_Del(), not free(). A few modules included with Python fell afoul of this and had to be fixed; doubtless there are more third-party modules that will have the same problem.

El asignador de objetos fue aportado por Vladimir Marangozov.

The speed of line-oriented file I/O has been improved because people often complain about its lack of speed, and because it’s often been used as a naïve benchmark. The readline() method of file objects has therefore been rewritten to be much faster. The exact amount of the speedup will vary from platform to platform depending on how slow the C library’s getc() was, but is around 66%, and potentially much faster on some particular operating systems. Tim Peters did much of the benchmarking and coding for this change, motivated by a discussion in comp.lang.python.

A new module and method for file objects was also added, contributed by Jeff Epler. The new method, xreadlines(), is similar to the existing xrange() built-in. xreadlines() returns an opaque sequence object that only supports being iterated over, reading a line on every iteration but not reading the entire file into memory as the existing readlines() method does. You’d use it like this:

for line in sys.stdin.xreadlines():
    # ... do something for each line ...
    ...

Para una discusión más completa de los cambios en la línea de E/S, véase el resumen de python-dev del 1 al 15 de enero de 2001 en https://mail.python.org/pipermail/python-dev/2001-January/.

A new method, popitem(), was added to dictionaries to enable destructively iterating through the contents of a dictionary; this can be faster for large dictionaries because there’s no need to construct a list containing all the keys or values. D.popitem() removes a random (key, value) pair from the dictionary D and returns it as a 2-tuple. This was implemented mostly by Tim Peters and Guido van Rossum, after a suggestion and preliminary patch by Moshe Zadka.

Modules can now control which names are imported when from module import * is used, by defining an __all__ attribute containing a list of names that will be imported. One common complaint is that if the module imports other modules such as sys or string, from module import * will add them to the importing module’s namespace. To fix this, simply list the public names in __all__:

# List public names
__all__ = ['Database', 'open']

Una versión más estricta de este parche fue primero sugerida e implementada por Ben Wolfson, pero después de algunas discusiones de python-dev, una versión final más débil fue revisada.

Applying repr() to strings previously used octal escapes for non-printable characters; for example, a newline was '\012'. This was a vestigial trace of Python’s C ancestry, but today octal is of very little practical use. Ka-Ping Yee suggested using hex escapes instead of octal ones, and using the \n, \t, \r escapes for the appropriate characters, and implemented this new formatting.

Los errores de sintaxis detectados en tiempo de compilación pueden ahora lanzar excepciones que contienen el nombre del archivo y el número de línea del error, un agradable efecto secundario de la reorganización del compilador realizada por Jeremy Hylton.

C extensions which import other modules have been changed to use PyImport_ImportModule(), which means that they will use any import hooks that have been installed. This is also encouraged for third-party extensions that need to import some other module from C code.

El tamaño de la base de datos de caracteres Unicode se redujo en otros 340K gracias a Fredrik Lundh.

Se han aportado algunos puertos nuevos: MacOS X (por Steven Majewski), Cygwin (por Jason Tishler); RISCOS (por Dietmar Schwertberger); Unixware 7 (por Billy G. Allie).

Y hay la lista habitual de correcciones de errores menores, fugas de memoria menores, ediciones de docstrings, y otros ajustes, demasiado largos para que valga la pena detallarlos; vea los registros de CVS para los detalles completos si los quiere.

Agradecimientos

El autor desea agradecer a las siguientes personas sus sugerencias sobre varios borradores de este artículo: Graeme Cross, David Goodger, Jay Graves, Michael Hudson, Marc-André Lemburg, Fredrik Lundh, Neil Schemenauer, Thomas Wouters.

Novedades de Python 2.0

Autor

A.M. Kuchling y Moshe Zadka

Introducción

El 16 de octubre de 2000 se publicó una nueva versión de Python, la 2.0. Este artículo cubre las emocionantes nuevas características de la 2.0, destaca algunos otros cambios útiles y señala algunos cambios incompatibles que pueden requerir reescribir el código.

El desarrollo de Python nunca se detiene por completo entre versiones, y siempre se presenta un flujo constante de correcciones de errores y mejoras. Una gran cantidad de correcciones menores, algunas optimizaciones, docstrings adicionales y mejores mensajes de error fueron incluidos en la versión 2.0; sería imposible enumerarlos todos, pero son ciertamente significativos. Consulte los registros CVS disponibles públicamente si desea ver la lista completa. Este progreso se debe a que los cinco desarrolladores que trabajan para PythonLabs reciben ahora una remuneración por pasar sus días arreglando errores, y también a la mejora de la comunicación resultante del traslado a SourceForge.

¿Qué pasa con Python 1.6?

Python 1.6 puede considerarse como la versión de Python de las Obligaciones Contractuales. Después de que el equipo principal de desarrollo dejara el CNRI en mayo de 2000, el CNRI pidió que se creara una versión 1.6 que contuviera todo el trabajo sobre Python que se había realizado en el CNRI. Por lo tanto, Python 1.6 representa el estado del árbol CVS en mayo de 2000, siendo la novedad más importante el soporte de Unicode. El desarrollo continuó después de mayo, por supuesto, así que el árbol 1.6 recibió algunas correcciones para asegurar que es compatible con Python 2.0. 1.Por lo tanto, la 6 es parte de la evolución de Python, y no una rama lateral.

So, should you take much interest in Python 1.6? Probably not. The 1.6final and 2.0beta1 releases were made on the same day (September 5, 2000), the plan being to finalize Python 2.0 within a month or so. If you have applications to maintain, there seems little point in breaking things by moving to 1.6, fixing them, and then having another round of breakage within a month by moving to 2.0; you’re better off just going straight to 2.0. Most of the really interesting features described in this document are only in 2.0, because a lot of work was done between May and September.

Nuevo proceso de desarrollo

El cambio más importante en Python 2.0 puede que no sea en el código en absoluto, sino en la forma de desarrollar Python: en mayo de 2000 los desarrolladores de Python comenzaron a utilizar las herramientas puestas a disposición por SourceForge para almacenar el código fuente, rastrear los informes de errores y gestionar la cola de envíos de parches. Para informar de errores o enviar parches para Python 2.0, utilice las herramientas de seguimiento de errores y gestión de parches disponibles en la página del proyecto Python, situada en https://sourceforge.net/projects/python/.

El más importante de los servicios alojados ahora en SourceForge es el árbol CVS de Python, el repositorio de versiones controladas que contiene el código fuente de Python. Anteriormente, había unas 7 personas que tenían acceso de escritura al árbol CVS, y todos los parches tenían que ser inspeccionados y comprobados por una de las personas de esta corta lista. Obviamente, esto no era muy escalable. Al trasladar el árbol CVS a SourceForge, fue posible conceder acceso de escritura a más personas; en septiembre de 2000 había 27 personas que podían revisar los cambios, un aumento de cuatro veces. Esto hace posible cambios a gran escala que no se intentarían si tuvieran que pasar por el pequeño grupo de desarrolladores del núcleo. Por ejemplo, un día a Peter Schneider-Kamp se le ocurrió dejar de lado la compatibilidad con K&R C y convertir el código fuente de Python a ANSI C. Después de obtener la aprobación en la lista de correo de python-dev, se lanzó a una ráfaga de revisiones que duró aproximadamente una semana, otros desarrolladores se unieron para ayudar, y el trabajo estaba hecho. Si sólo hubiera habido 5 personas con acceso de escritura, probablemente esa tarea habría sido considerada como «agradable, pero no vale la pena el tiempo y el esfuerzo necesarios» y nunca se habría realizado.

El cambio al uso de los servicios de SourceForge ha dado lugar a un notable aumento de la velocidad de desarrollo. Ahora los parches se envían, se comentan, son revisados por otras personas además del remitente original, y van de un lado a otro hasta que se considera que el parche merece ser revisado. Los errores se rastrean en una ubicación central y se pueden asignar a una persona específica para que los corrija, y podemos contar el número de errores abiertos para medir el progreso. Esto no ha tenido un coste: los desarrolladores tienen ahora más correo electrónico con el que lidiar, más listas de correo que seguir, y se han tenido que escribir herramientas especiales para el nuevo entorno. Por ejemplo, SourceForge envía por defecto mensajes de correo electrónico de notificación de parches y errores que son completamente inútiles, por lo que Ka-Ping Yee escribió un raspador de pantalla HTML que envía mensajes más útiles.

The ease of adding code caused a few initial growing pains, such as code was checked in before it was ready or without getting clear agreement from the developer group. The approval process that has emerged is somewhat similar to that used by the Apache group. Developers can vote +1, +0, -0, or -1 on a patch; +1 and -1 denote acceptance or rejection, while +0 and -0 mean the developer is mostly indifferent to the change, though with a slight positive or negative slant. The most significant change from the Apache model is that the voting is essentially advisory, letting Guido van Rossum, who has Benevolent Dictator For Life status, know what the general opinion is. He can still ignore the result of a vote, and approve or reject a change even if the community disagrees with him.

Producir un parche real es el último paso en la adición de una nueva característica, y suele ser fácil en comparación con la tarea anterior de llegar a un buen diseño. Las discusiones sobre nuevas funcionalidades a menudo pueden explotar en largos hilos de la lista de correo, haciendo que la discusión sea difícil de seguir, y nadie puede leer todos los mensajes en python-dev. Por lo tanto, se ha establecido un proceso relativamente formal para escribir Propuestas de Mejora de Python (PEPs), siguiendo el modelo del proceso RFC de Internet. Las PEP son borradores de documentos que describen una nueva característica propuesta, y se revisan continuamente hasta que la comunidad llega a un consenso, aceptando o rechazando la propuesta. Cita de la introducción de PEP 1 [https://www.python.org/dev/peps/pep-0001], «PEP Purpose and Guidelines»:

PEP son las siglas de Python Enhancement Proposal. Un PEP es un documento de diseño que proporciona información a la comunidad de Python, o que describe una nueva característica para Python. El PEP debe proporcionar una especificación técnica concisa de la característica y una justificación de la misma.

Pretendemos que los PEPs sean los mecanismos principales para proponer nuevas características, para recoger las opiniones de la comunidad sobre un tema y para documentar las decisiones de diseño que se han tomado en Python. El autor del PEP es responsable de crear consenso dentro de la comunidad y de documentar las opiniones discrepantes.

Lee el resto de PEP 1 [https://www.python.org/dev/peps/pep-0001] para conocer los detalles del proceso editorial, el estilo y el formato de los PEP. Los PEP se mantienen en el árbol CVS de Python en SourceForge, aunque no forman parte de la distribución de Python 2.0, y también están disponibles en formato HTML en https://www.python.org/dev/peps/. En septiembre de 2000, había 25 PEPS, desde PEP 201 [https://www.python.org/dev/peps/pep-0201], «Lockstep Iteration», hasta PEP 225, «Elementwise/Objectwise Operators».

Unicode

La mayor novedad de Python 2.0 es un nuevo tipo de datos fundamental: Las cadenas Unicode. Unicode utiliza números de 16 bits para representar los caracteres en lugar de los 8 bits utilizados por ASCII, lo que significa que se pueden admitir 65.536 caracteres distintos.

La interfaz final para el soporte de Unicode se alcanzó a través de innumerables discusiones, a menudo tormentosas, en la lista de correo de python-dev, y fue implementada en su mayor parte por Marc-André Lemburg, basándose en una implementación del tipo de cadena Unicode de Fredrik Lundh. Una explicación detallada de la interfaz fue escrita como PEP 100 [https://www.python.org/dev/peps/pep-0100], «Python Unicode Integration». Este artículo se limitará a cubrir los puntos más significativos de las interfaces Unicode.

En el código fuente de Python, las cadenas Unicode se escriben como u "cadena". Los caracteres Unicode arbitrarios pueden escribirse utilizando una nueva secuencia de escape, uHHHH, donde HHHH es un número hexadecimal de 4 dígitos desde 0000 hasta FFFF. También se puede utilizar la secuencia de escape existente xHHHH, y se pueden utilizar escapes octales para caracteres hasta U+01FF, que se representa con 777.

Las cadenas Unicode, al igual que las cadenas normales, son un tipo de secuencia inmutable. Pueden ser indexadas y cortadas, pero no modificadas en su lugar. Las cadenas Unicode tienen un método encode( [encoding] ) que retorna una cadena de 8 bits en la codificación deseada. Las codificaciones son nombradas por cadenas, como 'ascii', 'utf-8', 'iso-8859-1', o lo que sea. Se define una API de códecs para implementar y registrar nuevas codificaciones que luego están disponibles en todo el programa Python. Si no se especifica una codificación, la codificación por defecto suele ser ASCII de 7 bits, aunque puede cambiarse para tu instalación de Python llamando a la función sys.setdefaultencoding(encoding) en una versión personalizada de site.py.

La combinación de cadenas de 8 bits y Unicode siempre fuerza conversión a Unicode, utilizando la codificación ASCII por defecto; el resultado de 'a' + u'bc' es u'abc'.

Se han añadido nuevas funciones incorporadas y se han modificado las existentes para que sean compatibles con Unicode:

unichr(ch) retorna una cadena Unicode de 1 carácter, que contiene el carácter ch.

ord(u), donde u es una cadena regular o Unicode de 1 carácter, retorna el número del carácter como un entero.

unicode(string [, encoding] [, errors] ) crea una cadena Unicode a partir de una cadena de 8 bits. encoding es una cadena que nombra la codificación a utilizar. El parámetro errors especifica el tratamiento de los caracteres que no son válidos para la codificación actual; pasar 'strict como valor hace que se lance una excepción en cualquier error de codificación, mientras que 'ignore hace que los errores se ignoren silenciosamente y 'replace utiliza U+FFFD, el carácter oficial de reemplazo, en caso de cualquier problema.

La sentencia exec, y varias funciones integradas como eval(), getattr(), y setattr() también aceptarán cadenas Unicode así como cadenas regulares. (Es posible que en el proceso de corrección de esto se hayan pasado por alto algunas funciones incorporadas; si encuentra una función incorporada que acepte cadenas pero que no acepte cadenas Unicode en absoluto, por favor, infórmelo como un error)

Un nuevo módulo, unicodedata, proporciona una interfaz para las propiedades de los caracteres Unicode. Por ejemplo, unicodedata.category(u'A') retorna la cadena de 2 caracteres “Lu”, la “L” denota que es una letra, y la “u” significa que es mayúscula. unicodedata.bidirectional(u'\u0660') retorna “AN”, lo que significa que U+0660 es un número árabe.

El módulo codecs contiene funciones para buscar codificaciones existentes y registrar otras nuevas. A menos que quiera implementar una nueva codificación, lo más habitual es que utilice la función codecs.lookup(encoding), que retorna una tupla de 4 elementos: (encode_func, decode_func, stream_reader, stream_writer).

encode_func es una función que toma una cadena Unicode, y retorna una 2-tupla (string, length). string es una cadena de 8 bits que contiene una porción (tal vez toda) de la cadena Unicode convertida a la codificación dada, y longitud indica la cantidad de cadena Unicode convertida.

decode_func es lo opuesto a encode_func, tomando una cadena de 8 bits y retornando una 2-tupla (ustring, length), que consiste en la cadena Unicode resultante ustring y el entero length que dice cuánto de la cadena de 8 bits se consumió.

stream_reader es una clase que soporta la decodificación de la entrada de un flujo. stream_reader(file_obj) retorna un objeto que soporta los métodos read(), readline() y readlines(). Todos estos métodos traducirán desde la codificación dada y retornarán cadenas Unicode.

stream_writer, de forma similar, es una clase que soporta la codificación de la salida a un flujo. stream_writer(file_obj) retorna un objeto que soporta los métodos write() y writelines(). Estos métodos esperan cadenas Unicode, traduciéndolas a la codificación dada en la salida.

Por ejemplo, el siguiente código escribe una cadena Unicode en un archivo, codificándola como UTF-8:

import codecs

unistr = u'\u0660\u2000ab ...'

(UTF8_encode, UTF8_decode,
 UTF8_streamreader, UTF8_streamwriter) = codecs.lookup('UTF-8')

output = UTF8_streamwriter( open( '/tmp/output', 'wb') )
output.write( unistr )
output.close()

El siguiente código leería la entrada UTF-8 del archivo:

input = UTF8_streamreader( open( '/tmp/output', 'rb') )
print repr(input.read())
input.close()

Las expresiones regulares compatibles con Unicode están disponibles a través del módulo re, que tiene una nueva implementación subyacente llamada SRE escrita por Fredrik Lundh de Secret Labs AB.

Se ha añadido una opción de línea de comandos -U que hace que el compilador de Python interprete todos los literales de cadena como literales de cadena Unicode. Esta opción está pensada para ser utilizada en las pruebas y para asegurar el futuro de su código Python, ya que alguna versión futura de Python puede dejar de soportar cadenas de 8 bits y proporcionar sólo cadenas Unicode.

Comprensión de listas

Las listas son un tipo de datos muy útil en Python, y muchos programas manipulan una lista en algún momento. Dos operaciones comunes en las listas son hacer un bucle sobre ellas, y escoger los elementos que cumplen un cierto criterio, o aplicar alguna función a cada elemento. Por ejemplo, dada una lista de cadenas, podrías querer sacar todas las cadenas que contengan una determinada subcadena, o quitar los espacios en blanco de cada línea.

Las funciones map() y filter() existentes pueden usarse para este propósito, pero requieren una función como uno de sus argumentos. Esto está bien si hay una función incorporada que se puede pasar directamente, pero si no la hay, hay que crear una pequeña función para hacer el trabajo requerido, y las reglas de ámbito de Python hacen que el resultado sea feo si la pequeña función necesita información adicional. Tomemos el primer ejemplo del párrafo anterior, encontrar todas las cadenas de la lista que contienen una subcadena dada. Podrías escribir lo siguiente para hacerlo:

# Given the list L, make a list of all strings
# containing the substring S.
sublist = filter( lambda s, substring=S:
                     string.find(s, substring) != -1,
                  L)

Debido a las reglas de ámbito de Python, se utiliza un argumento por defecto para que la función anónima creada por la expresión lambda sepa qué subcadena se está buscando. Las comprensiones de lista hacen esto más limpio:

sublist = [ s for s in L if string.find(s, S) != -1 ]

Las comprensiones de listas tienen la forma:

[ expression for expr in sequence1
             for expr2 in sequence2 ...
             for exprN in sequenceN
             if condition ]

Las cláusulas for…in contienen las secuencias a iterar. Las secuencias no tienen por qué tener la misma longitud, ya que no se itera sobre ellas en paralelo, sino de izquierda a derecha; esto se explica más claramente en los párrafos siguientes. Los elementos de la lista generada serán los valores sucesivos de la expresión. La cláusula final if es opcional; si está presente, la expresión sólo se evalúa y se añade al resultado si la condición es verdadera.

Para dejar muy clara la semántica, una comprensión de lista equivale al siguiente código de Python:

for expr1 in sequence1:
    for expr2 in sequence2:
    ...
        for exprN in sequenceN:
             if (condition):
                  # Append the value of
                  # the expression to the
                  # resulting list.

Esto significa que cuando hay múltiples cláusulas for…in, la lista resultante será igual al producto de las longitudes de todas las secuencias. Si tiene dos listas de longitud 3, la lista de salida tendrá 9 elementos:

seq1 = 'abc'
seq2 = (1,2,3)
>>> [ (x,y) for x in seq1 for y in seq2]
[('a', 1), ('a', 2), ('a', 3), ('b', 1), ('b', 2), ('b', 3), ('c', 1),
('c', 2), ('c', 3)]

Para evitar introducir una ambigüedad en la gramática de Python, si expresión está creando una tupla, debe estar rodeada de paréntesis. La primera comprensión de la lista a continuación es un error de sintaxis, mientras que la segunda es correcta:

# Syntax error
[ x,y for x in seq1 for y in seq2]
# Correct
[ (x,y) for x in seq1 for y in seq2]

La idea de las comprensiones de listas procede originalmente del lenguaje de programación funcional Haskell (https://www.haskell.org). Greg Ewing fue el que más abogó por añadirlas a Python y escribió el parche inicial de comprensión de listas, que luego se discutió durante un tiempo aparentemente interminable en la lista de correo de python-dev y se mantuvo actualizada por Skip Montanaro.

Asignación aumentada

Los operadores de asignación aumentados, otra característica largamente solicitada, han sido añadidos a Python 2.0. Los operadores de asignación aumentados incluyen +=, -=, *=, etc. Por ejemplo, la sentencia a += 2 incrementa el valor de la variable a en 2, lo que equivale a la sentencia algo más larga a = a + 2.

La lista completa de operadores de asignación soportados es +=, -=, *=, /=, %=, **=, &=, |=, ^=, >>=, y <=. Las clases de Python pueden anular los operadores de asignación aumentados definiendo métodos llamados __iadd__(), __isub__(), etc. Por ejemplo, la siguiente clase Number almacena un número y soporta el uso de += para crear una nueva instancia con un valor incrementado.

class Number:
    def __init__(self, value):
        self.value = value
    def __iadd__(self, increment):
        return Number( self.value + increment)

n = Number(5)
n += 3
print n.value

El método especial __iadd__() es llamado con el valor del incremento, y debe retornar una nueva instancia con un valor adecuadamente modificado; este valor de retorno se vincula como el nuevo valor de la variable del lado izquierdo.

Los operadores de asignación aumentada se introdujeron por primera vez en el lenguaje de programación C, y la mayoría de los lenguajes derivados de C, como awk, C++, Java, Perl y PHP también los soportan. El parche de asignación aumentada fue implementado por Thomas Wouters.

Métodos de cadena de caracteres

Hasta ahora, la funcionalidad de manipulación de cadenas de caracteres estaba en el módulo string, que normalmente era un front-end para el módulo strop escrito en C. La adición de Unicode supuso una dificultad para el módulo strop, porque todas las funciones tendrían que ser reescritas para aceptar cadenas de 8 bits o Unicode. Para funciones como string.replace(), que toma 3 argumentos de cadena, eso significa ocho posibles permutaciones, y el correspondiente código complicado.

En cambio, Python 2.0 traslada el problema al tipo de cadena de caracteres, haciendo que la funcionalidad de manipulación de cadenas esté disponible a través de métodos tanto en cadenas de 8 bits como en cadenas Unicode.

>>> 'andrew'.capitalize()
'Andrew'
>>> 'hostname'.replace('os', 'linux')
'hlinuxtname'
>>> 'moshe'.find('sh')
2

Una cosa que no ha cambiado, a pesar de una notable broma de April Fools, es que las cadenas de Python son inmutables. Así, los métodos de cadenas retornan cadenas nuevas, y no modifican la cadena sobre la que operan.

El antiguo módulo string sigue existiendo por compatibilidad con el pasado, pero actúa principalmente como un front-end para los nuevos métodos de cadena de caracteres.

Dos métodos que no tienen paralelo en las versiones anteriores a la 2.0, aunque existieron en JPython durante bastante tiempo, son startswith() y endswith(). s.startswith(t) es equivalente a s[:len(t)] == t, mientras que s.endswith(t) es equivalente a s[-len(t):] == t.

Otro método que merece una mención especial es join(). El método join() de una cadena recibe un parámetro, una secuencia de cadenas, y es equivalente a la función string.join() del antiguo módulo string, con los argumentos invertidos. En otras palabras, s.join(seq) es equivalente a la antigua string.join(seq, s).

Recogida de basura de los ciclos

La implementación en C de Python utiliza el conteo de referencias para implementar la recolección de basura. Cada objeto de Python mantiene un recuento del número de referencias que apuntan a sí mismo, y ajusta el recuento a medida que se crean o destruyen referencias. Una vez que el recuento de referencias llega a cero, el objeto deja de ser accesible, ya que es necesario tener una referencia a un objeto para acceder a él, y si el recuento es cero, ya no existen referencias.

El conteo de referencias tiene algunas propiedades agradables: es fácil de entender e implementar, y la implementación resultante es portable, bastante rápida, y reacciona bien con otras bibliotecas que implementan sus propios esquemas de manejo de memoria. El mayor problema del conteo de referencias es que a veces no se da cuenta de que los objetos ya no son accesibles, lo que provoca una fuga de memoria. Esto ocurre cuando hay ciclos de referencias.

Consideremos el ciclo más simple posible, una instancia de clase que tiene una referencia a sí misma:

instance = SomeClass()
instance.myself = instance

Después de ejecutar las dos líneas de código anteriores, la cuenta de referencias de instance es 2; una referencia es de la variable llamada 'instance, y la otra es del atributo myself de la instancia.

Si la siguiente línea de código es del instance, ¿qué ocurre? La cuenta de referencias de instance se reduce en 1, por lo que tiene una cuenta de referencias de 1; la referencia en el atributo myself sigue existiendo. Sin embargo, la instancia ya no es accesible a través del código de Python, y podría ser eliminada. Varios objetos pueden participar en un ciclo si tienen referencias entre sí, haciendo que todos los objetos se filtren.

Python 2.0 soluciona este problema ejecutando periódicamente un algoritmo de detección de ciclos que busca los ciclos inaccesibles y borra los objetos implicados. Un nuevo módulo gc proporciona funciones para realizar una recolección de basura, obtener estadísticas de depuración y afinar los parámetros del recolector.

Ejecutar el algoritmo de detección de ciclos lleva algo de tiempo, y por lo tanto resultará en una sobrecarga adicional. Se espera que después de que hayamos adquirido experiencia con la recogida de ciclos al utilizar la versión 2.0, Python 2.1 sea capaz de minimizar la sobrecarga con un cuidadoso ajuste. Todavía no es obvio cuánto rendimiento se pierde, porque la evaluación comparativa de esto es difícil y depende crucialmente de la frecuencia con la que el programa crea y destruye objetos. La detección de ciclos puede ser desactivada cuando Python es compilado, si no puede permitirse ni siquiera una pequeña penalización de velocidad o sospecha que la recolección de ciclos es un error, especificando la opción --without-cycle-gc cuando se ejecuta el script configure.

Varias personas abordaron este problema y contribuyeron a una solución. Una primera implementación del enfoque de detección de ciclos fue escrita por Toby Kelsey. El algoritmo actual fue sugerido por Eric Tiedemann durante una visita al CNRI, y Guido van Rossum y Neil Schemenauer escribieron dos implementaciones diferentes, que posteriormente fueron integradas por Neil. Muchas otras personas ofrecieron sugerencias a lo largo del camino; los archivos de marzo de 2000 de la lista de correo python-dev contienen la mayor parte de la discusión relevante, especialmente en los hilos titulados «Colección de ciclos de referencia para Python» y «Finalización de nuevo».

Otros cambios en el núcleo

Se han realizado varios cambios menores en la sintaxis y las funciones incorporadas de Python. Ninguno de los cambios es de gran alcance, pero son conveniencias prácticas.

Cambios menores del lenguaje

Una nueva sintaxis hace más conveniente llamar a una función dada con una tupla de argumentos y/o un diccionario de argumentos de palabras clave. En Python 1.5 y anteriores, se utilizaba la función incorporada apply(): apply(f, args, kw) llama a la función f() con la tupla de argumentos args y los argumentos de palabras clave en el diccionario kw. apply() es lo mismo en 2.0, pero gracias a un parche de Greg Ewing, f(*args, **kw) es una forma más corta y clara de conseguir el mismo efecto. Esta sintaxis es simétrica con la sintaxis para definir funciones:

def f(*args, **kw):
    # args is a tuple of positional args,
    # kw is a dictionary of keyword args
    ...

La sentencia print puede ahora tener su salida dirigida a un objeto tipo archivo siguiendo a print con >> archivo, similar al operador de redirección en los shells de Unix. Antes había que utilizar el método write() del objeto tipo archivo, que carece de la comodidad y simplicidad de print, o bien asignar un nuevo valor a sys.stdout y luego restaurar el valor anterior. Para enviar la salida al error estándar, es mucho más fácil escribir esto:

print >> sys.stderr, "Warning: action field not supplied"

Ahora se puede cambiar el nombre de los módulos al importarlos, utilizando la sintaxis import module as name o from module import name as othername. El parche fue enviado por Thomas Wouters.

Un nuevo estilo de formato está disponible cuando se utiliza el operador %; “%r” insertará el repr() de su argumento. Esto también se añadió por consideraciones de simetría, esta vez por simetría con el estilo de formato existente “%s”, que inserta el str() de su argumento. Por ejemplo, '%r %s' % ('abc', 'abc') retorna una cadena que contiene 'abc' abc.

Anteriormente no había forma de implementar una clase que sobrepasara el operador incorporado de Python in e implementara una versión personalizada.``obj in seq`` retorna verdadero si obj está presente en la secuencia seq; Python lo calcula simplemente probando cada índice de la secuencia hasta que se encuentra obj o se encuentra un IndexError. Moshe Zadka ha contribuido con un parche que añade un método mágico __contains__() para proporcionar una implementación personalizada para in. Además, los nuevos objetos incorporados escritos en C pueden definir lo que in significa para ellos a través de una nueva ranura en el protocolo de secuencia.

Las versiones anteriores de Python utilizaban un algoritmo recursivo para borrar objetos. Las estructuras de datos muy anidadas podían hacer que el intérprete llenara la pila de C y se bloqueara; Christian Tismer reescribió la lógica de borrado para solucionar este problema. En una nota relacionada, la comparación de objetos recursivos se repite infinitamente y se bloquea; Jeremy Hylton reescribió el código para que no se bloquee, produciendo un resultado útil. Por ejemplo, después de este código:

a = []
b = []
a.append(a)
b.append(b)

La comparación a==b retorna verdadero, porque las dos estructuras de datos recursivas son isomorfas. Véase el hilo «trashcan and PR#7» en los archivos de abril de 2000 de la lista de correo de python-dev para la discusión que condujo a esta implementación, y algunos enlaces relevantes útiles. Tenga en cuenta que las comparaciones ahora también pueden generar excepciones. En versiones anteriores de Python, una operación de comparación como cmp(a,b) siempre producía una respuesta, incluso si un método __cmp__() definido por el usuario encontraba un error, ya que la excepción resultante simplemente se tragaba en silencio.

Se ha trabajado en portar Python a Windows de 64 bits en el procesador Itanium, principalmente por Trent Mick de ActiveState. (Confusamente, sys.platform sigue siendo 'win32 en Win64 porque parece que para facilitar la portabilidad, MS Visual C++ trata el código como de 32 bits en Itanium) PythonWin también es compatible con Windows CE; vea la página de Python CE en http://pythonce.sourceforge.net/ para más información.

Otra plataforma nueva es Darwin/MacOS X; el soporte inicial para ella está en Python 2.0. La carga dinámica funciona, si se especifica «configure –with-dyld –with-suffix=.x». Consulte el README de la distribución de fuentes de Python para obtener más instrucciones.

Se ha intentado aliviar uno de los defectos de Python, la a menudo confusa excepción NameError cuando el código hace referencia a una variable local antes de que se le haya asignado un valor. Por ejemplo, el siguiente código lanza una excepción en la sentencia print tanto en 1.5.2 como en 2.0; en 1.5.2 se lanza una excepción NameError, mientras que en 2.0 se lanza una nueva excepción UnboundLocalError. UnboundLocalError es una subclase de NameError, así que cualquier código existente que espere que se lance NameError debería seguir funcionando.

def f():
    print "i=",i
    i = i + 1
f()

Se han introducido dos nuevas excepciones, TabError y IndentationError. Ambas son subclases de SyntaxError, y se lanzan cuando el código Python se encuentra con una sangría incorrecta.

Cambios en las funciones incorporadas

Se ha añadido un nuevo built-in, zip(seq1, seq2, ...). zip() retorna una lista de tuplas donde cada tupla contiene el i-ésimo elemento de cada una de las secuencias del argumento. La diferencia entre zip() y map(None, seq1, seq2) es que map() rellena las secuencias con None si las secuencias no tienen la misma longitud, mientras que zip() trunca la lista retornada a la longitud de la secuencia argumental más corta.

Las funciones int() y long() aceptan ahora un parámetro «base» opcional cuando el primer argumento es una cadena. int(“123”, 10)` retorna 123, mientras que int('123', 16) retorna 291. int(123, 16) lanza una excepción TypeError con el mensaje «no se puede convertir una cadena con base explícita».

Se ha añadido al módulo sys una nueva variable que contiene información más detallada sobre la versión. sys.version_info es una tupla (major, minor, micro, level, serial) Por ejemplo, en una hipotética 2.0.1beta1, sys.version_info sería (2, 0, 1, 'beta', 1). level es una cadena como "alpha", "beta", o "final" para una versión final.

Los diccionarios tienen un nuevo y extraño método, setdefault(key, default), que se comporta de forma similar al método get() existente. Sin embargo, si falta la clave, setdefault() retorna el valor de default como haría get(), y también lo inserta en el diccionario como valor de key. Así, las siguientes líneas de código:

if dict.has_key( key ): return dict[key]
else:
    dict[key] = []
    return dict[key]

puede reducirse a una única sentencia return dict.setdefault(key, []).

El intérprete establece una profundidad de recursión máxima para atrapar la recursión desbocada antes de llenar la pila de C y causar un volcado del núcleo o GPF. Anteriormente este límite se fijaba cuando se compilaba Python, pero en la versión 2.0 la profundidad máxima de recursión puede leerse y modificarse usando sys.getrecursionlimit() y sys.setrecursionlimit(). El valor por defecto es 1000, y se puede encontrar un valor máximo aproximado para una plataforma determinada ejecutando un nuevo script, Misc/find_recursionlimit.py.

Adaptación a la versión 2.0

Las nuevas versiones de Python se esfuerzan por ser compatibles con las anteriores, y el historial ha sido bastante bueno. Sin embargo, algunos cambios se consideran lo suficientemente útiles, normalmente porque corrigen decisiones de diseño iniciales que resultaron ser activamente erróneas, que no siempre se puede evitar romper la compatibilidad hacia atrás. Esta sección enumera los cambios en Python 2.0 que pueden hacer que el código Python antiguo se rompa.

El cambio que probablemente romperá la mayor parte del código es el endurecimiento de los argumentos aceptados por algunos métodos. Algunos métodos tomaban múltiples argumentos y los trataban como una tupla, particularmente varios métodos de lista como append() y insert(). En versiones anteriores de Python, si L es una lista, L.append( 1,2 ) añade la tupla (1,2) a la lista. En Python 2.0 esto provoca una excepción TypeError con el mensaje “append requiere exactamente 1 argumento; se han dado 2”. La solución es simplemente añadir un conjunto extra de paréntesis para pasar ambos valores como una tupla: L.append( (1,2) ).

Las versiones anteriores de estos métodos eran más indulgentes porque utilizaban una antigua función de la interfaz C de Python para analizar sus argumentos; la versión 2.0 los moderniza para utilizar PyArg_ParseTuple(), la función actual de análisis de argumentos, que proporciona mensajes de error más útiles y trata las llamadas con múltiples argumentos como errores. Si es absolutamente necesario usar la versión 2.0 pero no puedes arreglar tu código, puedes editar Objects/listobject.c y definir el símbolo del preprocesador NO_STRICT_LIST_APPEND para preservar el antiguo comportamiento; esto no es recomendable.

Algunas de las funciones del módulo socket siguen siendo indulgentes en este sentido. Por ejemplo, socket.connect( ('hostname', 25) )() es la forma correcta, pasando una tupla que representa una dirección IP, pero socket.connect( 'hostname', 25 )() también funciona. socket.connect_ex() y socket.bind() son igualmente fáciles de usar. 2.0alpha1 endureció estas funciones, pero como la documentación utilizaba la forma errónea de argumentos múltiples, mucha gente escribió código que se rompería con la comprobación más estricta. GvR se echó atrás en los cambios ante la reacción del público, así que para el módulo socket, la documentación se arregló y la forma de argumento múltiple simplemente se marcó como obsoleta; se reforzará de nuevo en una futura versión de Python.

El escape \x en los literales de cadena ahora toma exactamente 2 dígitos hexadecimales. Antes consumía todos los dígitos hexadecimales que seguían a la “x” y tomaba los 8 bits más bajos del resultado, por lo que \x123456 era equivalente a \x56.

Las excepciones AttributeError y NameError tienen un mensaje de error más amigable, cuyo texto será algo así como 'Spam' instance has no attribute 'eggs' o name 'eggs' is not defined. Anteriormente, el mensaje de error era simplemente la falta del nombre del atributo eggs, y el código escrito para aprovechar este hecho se romperá en la versión 2.0.

Se ha trabajado para que los enteros y los enteros largos sean un poco más intercambiables. En la versión 1.5.2, se añadió soporte para archivos grandes en Solaris, para permitir la lectura de archivos de más de 2 GiB; esto hizo que el método tell() de los objetos de archivo retornara un entero largo en lugar de un entero normal. Algunos códigos restaban dos desplazamientos de archivos e intentaban utilizar el resultado para multiplicar una secuencia o cortar una cadena, pero esto generaba un TypeError. En la versión 2.0, los enteros largos pueden utilizarse para multiplicar o cortar una secuencia, y se comportarán como se espera intuitivamente; 3L * 'abc' produce “abcabcabc”, y (0,1,2,3)[2L:4L] produce (2,3). Los enteros largos también pueden utilizarse en varios contextos en los que antes sólo se aceptaban enteros, como en el método seek() de los objetos de archivo, y en los formatos soportados por el operador % (%d, %i, %x, etc.). Por ejemplo, "%d" % 2L**64 producirá la cadena 18446744073709551616.

El cambio más sutil de los enteros largos es que el str() de un entero largo ya no tiene un carácter “L” al final, aunque repr() todavía lo incluye. La “L” molestaba a muchas personas que querían imprimir enteros largos con el mismo aspecto que los enteros normales, ya que tenían que esforzarse por cortar el carácter. Esto ya no es un problema en 2.0, pero el código que hace str(longval)[:-1] y asume que la “L” está ahí, ahora perderá el dígito final.

Tomar el repr() de un flotador utiliza ahora una precisión de formato diferente a la de str(). repr() utiliza la cadena de formato %.17g para el sprintf() de C, mientras que str() utiliza %.12g como antes. El efecto es que repr() puede mostrar ocasionalmente más decimales que str(), para ciertos números. Por ejemplo, el número 8,1 no puede representarse exactamente en binario, por lo que repr(8,1) es '8,09999999999996', mientras que str(8,1) es '8,1'.

La opción de línea de comandos -X, que convertía todas las excepciones estándar en cadenas en lugar de clases, ha sido eliminada; las excepciones estándar serán ahora siempre clases. El módulo exceptions que contiene las excepciones estándar ha sido traducido de Python a un módulo C integrado, escrito por Barry Warsaw y Fredrik Lundh.

Extensión/Incorporación de cambios

Algunos de los cambios están bajo la cubierta, y sólo serán evidentes para la gente que escribe módulos de extensión de C o que incrusta un intérprete de Python en una aplicación más grande. Si no estás tratando con la API de C de Python, puedes saltarte esta sección.

El número de versión de la API C de Python se incrementó, por lo que las extensiones C compiladas para 1.5.2 deben ser recompiladas para que funcionen con 2.0. En Windows, no es posible que Python 2.0 importe una extensión de terceros construida para Python 1.5.x debido a cómo funcionan las DLL de Windows, por lo que Python lanzará una excepción y la importación fallará.

Los usuarios del módulo ExtensionClass de Jim Fulton estarán encantados de saber que se han añadido ganchos para que las ExtensionClasses sean ahora compatibles con isinstance() y issubclass(). Esto significa que ya no tiene que recordar escribir código como if type(obj) == myExtensionClass, sino que puede utilizar el más natural if isinstance(obj, myExtensionClass).

El archivo Python/importdl.c, que era una masa de #ifdefs para soportar la carga dinámica en muchas plataformas diferentes, fue limpiado y reorganizado por Greg Stein. importdl.c es ahora bastante pequeño, y el código específico de la plataforma se ha movido a un montón de archivos Python/dynload_*.c. Otra limpieza: también había una serie de archivos my*.h en el directorio Include/ que contenían varios hacks de portabilidad; se han fusionado en un único archivo, Include/pyport.h.

Se ha completado la tan esperada reestructuración de malloc de Vladimir Marangozov, para facilitar que el intérprete de Python utilice un asignador personalizado en lugar del estándar de C malloc(). Para la documentación, lea los comentarios en Include/pymem.h y Include/objimpl.h. Para ver las largas discusiones durante las cuales se elaboró la interfaz, consulte los archivos web de las listas “patches” y “python-dev” en python.org.

Las versiones recientes del entorno de desarrollo GUSI para MacOS soportan hilos POSIX. Por lo tanto, el soporte de hilos POSIX de Python ahora funciona en Macintosh. También se ha contribuido al soporte de hilos utilizando la biblioteca GNU pth del espacio de usuario.

También se ha mejorado el soporte de hilos en Windows. Windows soporta bloqueos de hilos que utilizan objetos del núcleo sólo en caso de contención; en el caso común cuando no hay contención, utilizan funciones más simples que son un orden de magnitud más rápido. Una versión con hilos de Python 1.5.2 en NT es dos veces más lenta que una versión sin hilos; con los cambios de la 2.0, la diferencia es sólo del 10%. Estas mejoras fueron aportadas por Yakov Markovitch.

El código fuente de Python 2.0 ahora sólo utiliza prototipos ANSI C, por lo que la compilación de Python ahora requiere un compilador ANSI C, y ya no puede hacerse utilizando un compilador que sólo soporte K&R C.

Previously the Python virtual machine used 16-bit numbers in its bytecode, limiting the size of source files. In particular, this affected the maximum size of literal lists and dictionaries in Python source; occasionally people who are generating Python code would run into this limit. A patch by Charles G. Waldman raises the limit from 2**16 to 2**32.

Se han añadido tres nuevas funciones para añadir constantes al diccionario de un módulo en el momento de la inicialización: PyModule_AddObject(), PyModule_AddIntConstant(), y PyModule_AddStringConstant(). Cada una de estas funciones toma un objeto de módulo, una cadena C terminada en cero que contiene el nombre a añadir, y un tercer argumento para el valor a asignar al nombre. Este tercer argumento es, respectivamente, un objeto Python, un C long o una cadena C.

Se ha añadido una API envolvente para los manejadores de señales de estilo Unix. PyOS_getsig() obtiene un manejador de señales y PyOS_setsig() establecerá un nuevo manejador.

Distutils: Facilitando la instalación de módulos

Antes de Python 2.0, la instalación de módulos era un asunto tedioso – no había forma de averiguar automáticamente dónde se instalaba Python, o qué opciones del compilador se debían usar para los módulos de extensión. Los autores de software tenían que pasar por un arduo ritual de edición de Makefiles y archivos de configuración, que sólo funcionaban realmente en Unix y dejaban sin soporte a Windows y MacOS. Los usuarios de Python se enfrentaban a instrucciones de instalación muy diferentes que variaban entre los distintos paquetes de extensión, lo que hacía que la administración de una instalación de Python fuera una tarea ardua.

El SIG de utilidades de distribución, liderado por Greg Ward, ha creado las Distutils, un sistema para facilitar la instalación de paquetes. Forman el paquete distutils, una nueva parte de la biblioteca estándar de Python. En el mejor de los casos, la instalación de un módulo de Python desde el código fuente requerirá los mismos pasos: primero simplemente hay que desempaquetar el archivo tar o zip, y ejecutar «python setup.py install. La plataforma será detectada automáticamente, el compilador será reconocido, los módulos de extensión C serán compilados, y la distribución será instalada en el directorio apropiado. Los argumentos opcionales de la línea de comandos proporcionan más control sobre el proceso de instalación, el paquete distutils ofrece muchos lugares para anular los valores predeterminados - separando la construcción de la instalación, construyendo o instalando en directorios no predeterminados, y más.

Para usar las Distutils, necesitas escribir un script setup.py. Para el caso simple, cuando el software contiene sólo archivos .py, un setup.py mínimo puede tener sólo unas pocas líneas:

from distutils.core import setup
setup (name = "foo", version = "1.0",
       py_modules = ["module1", "module2"])

El archivo setup.py no es mucho más complicado si el software consta de unos pocos paquetes:

from distutils.core import setup
setup (name = "foo", version = "1.0",
       packages = ["package", "package.subpackage"])

Una extensión en C puede ser el caso más complicado; he aquí un ejemplo tomado del paquete PyXML:

from distutils.core import setup, Extension

expat_extension = Extension('xml.parsers.pyexpat',
     define_macros = [('XML_NS', None)],
     include_dirs = [ 'extensions/expat/xmltok',
                      'extensions/expat/xmlparse' ],
     sources = [ 'extensions/pyexpat.c',
                 'extensions/expat/xmltok/xmltok.c',
                 'extensions/expat/xmltok/xmlrole.c', ]
       )
setup (name = "PyXML", version = "0.5.4",
       ext_modules =[ expat_extension ] )

Las Distutils también pueden encargarse de crear distribuciones fuente y binarias. El comando «sdist», ejecutado por «python setup.py sdist, construye una distribución fuente como foo-1.0.tar.gz. Añadir nuevos comandos no es difícil, ya se han aportado los comandos «bdist_rpm» y «bdist_wininst» para crear una distribución RPM y un instalador de Windows para el software, respectivamente. Los comandos para crear otros formatos de distribución, como los paquetes de Debian y los archivos .pkg de Solaris, se encuentran en diversas etapas de desarrollo.

Todo esto está documentado en un nuevo manual, Distribución de módulos de Python, que se une al conjunto básico de documentación de Python.

Módulos XML

La versión 1.5.2 de Python incluía un sencillo analizador XML en forma de módulo xmllib, aportado por Sjoerd Mullender. Desde el lanzamiento de la versión 1.5.2, se han generalizado dos interfaces diferentes para el procesamiento de XML: SAX2 (versión 2 de la API Simple para XML) proporciona una interfaz basada en eventos con algunas similitudes con xmllib, y el DOM (Modelo de Objetos de Documento) proporciona una interfaz basada en un árbol, transformando un documento XML en un árbol de nodos que puede ser atravesado y modificado. Python 2.0 incluye una interfaz SAX2 y una interfaz DOM reducida como parte del paquete xml. Aquí daremos una breve descripción de estas nuevas interfaces; consulte la documentación de Python o el código fuente para obtener detalles completos. El SIG XML de Python también está trabajando en la mejora de la documentación.

Soporte de SAX2

SAX define una interfaz basada en eventos para analizar XML. Para usar SAX, debes escribir una clase manejadora de SAX. Las clases manejadoras heredan de varias clases proporcionadas por SAX, y sobrescriben varios métodos que luego serán llamados por el analizador XML. Por ejemplo, los métodos startElement() y endElement() son llamados para cada etiqueta inicial y final encontrada por el analizador, el método characters() es llamado para cada trozo de datos de caracteres, etc.

La ventaja del enfoque basado en eventos es que todo el documento no tiene que residir en la memoria en un momento dado, lo cual es importante si estás procesando documentos realmente enormes. Sin embargo, escribir la clase manejadora de SAX puede ser muy complicado si se intenta modificar la estructura del documento de alguna manera elaborada.

Por ejemplo, este pequeño programa de ejemplo define un manejador que imprime un mensaje para cada etiqueta inicial y final, y luego analiza el archivo hamlet.xml usándolo:

from xml import sax

class SimpleHandler(sax.ContentHandler):
    def startElement(self, name, attrs):
        print 'Start of element:', name, attrs.keys()

    def endElement(self, name):
        print 'End of element:', name

# Create a parser object
parser = sax.make_parser()

# Tell it what handler to use
handler = SimpleHandler()
parser.setContentHandler( handler )

# Parse a file!
parser.parse( 'hamlet.xml' )

Para más información, consulte la documentación de Python o el XML HOWTO en http://pyxml.sourceforge.net/topics/howto/xml-howto.html.

Soporte DOM

El Modelo de Objetos del Documento es una representación basada en un árbol para un documento XML. Una instancia de Document de nivel superior es la raíz del árbol, y tiene un único hijo que es la instancia de Element de nivel superior. Este Element tiene nodos hijos que representan los datos de los caracteres y cualquier subelemento, que puede tener otros hijos propios, y así sucesivamente. Utilizando el DOM puedes recorrer el árbol resultante como quieras, acceder a los valores de los elementos y atributos, insertar y eliminar nodos y volver a convertir el árbol en XML.

El DOM es útil para modificar documentos XML, porque se puede crear un árbol DOM, modificarlo añadiendo nuevos nodos o reordenando subárboles, y luego producir un nuevo documento XML como salida. También se puede construir un árbol DOM manualmente y convertirlo en XML, lo que puede ser una forma más flexible de producir una salida XML que simplemente escribir <tag1>…</tag1> un archivo.

La implementación del DOM incluida en Python se encuentra en el módulo xml.dom.minidom. Es una implementación ligera del DOM de nivel 1 con soporte para espacios de nombres XML. Las funciones parse() y parseString() se proporcionan para generar un árbol DOM:

from xml.dom import minidom
doc = minidom.parse('hamlet.xml')

doc es una instancia de Document. El Document, al igual que el resto de clases del DOM como el Element y el Text, es una subclase de la clase base Node. Por lo tanto, todos los nodos de un árbol DOM soportan ciertos métodos comunes, como toxml() que retorna una cadena que contiene la representación XML del nodo y sus hijos. Cada clase también tiene métodos especiales propios; por ejemplo, las instancias Element y Document tienen un método para encontrar todos los elementos hijos con un nombre de etiqueta dado. Continuando con el ejemplo anterior de 2 líneas:

perslist = doc.getElementsByTagName( 'PERSONA' )
print perslist[0].toxml()
print perslist[1].toxml()

Para el archivo XML Hamlet, las líneas anteriores dan como resultado:

<PERSONA>CLAUDIUS, king of Denmark. </PERSONA>
<PERSONA>HAMLET, son to the late, and nephew to the present king.</PERSONA>

El elemento raíz del documento está disponible como doc.documentElement, y sus hijos pueden modificarse fácilmente borrando, añadiendo o eliminando nodos:

root = doc.documentElement

# Remove the first child
root.removeChild( root.childNodes[0] )

# Move the new first child to the end
root.appendChild( root.childNodes[0] )

# Insert the new first child (originally,
# the third child) before the 20th child.
root.insertBefore( root.childNodes[0], root.childNodes[20] )

Una vez más, te remito a la documentación de Python para obtener una lista completa de las diferentes clases Node y sus diversos métodos.

Relación con PyXML

El Grupo de Interés Especial XML lleva un tiempo trabajando en código Python relacionado con XML. Su distribución de código, llamada PyXML, está disponible en las páginas web del SIG en https://www.python.org/community/sigs/current/xml-sig. La distribución de PyXML también utiliza el nombre de paquete xml. Si has escrito programas que utilizan PyXML, probablemente te preguntes sobre su compatibilidad con el paquete 2.0 xml.

La respuesta es que el paquete xml de Python 2.0 no es compatible con PyXML, pero puede hacerse compatible instalando una versión reciente de PyXML. Muchas aplicaciones pueden arreglárselas con el soporte XML que se incluye en Python 2.0, pero las aplicaciones más complicadas requerirán que se instale el paquete PyXML completo. Cuando se instala, las versiones 0.6.0 o superiores de PyXML sustituyen al paquete xml que se entrega con Python, y son un estricto superconjunto del paquete estándar, añadiendo un montón de características adicionales. Algunas de las características adicionales de PyXML incluyen:

4DOM, una implementación completa de DOM de FourThought, Inc.

El parser de validación xmlproc, escrito por Lars Marius Garshol.

El módulo acelerador del parser sgmlop, escrito por Fredrik Lundh.

Cambios en los módulos

Se han realizado muchas mejoras y correcciones de errores en la extensa biblioteca estándar de Python; algunos de los módulos afectados son readline, ConfigParser, cgi, calendar, posix, readline, xmllib, aifc, chunk, wave, random, shelve, y nntplib. Consulte los registros de CVS para conocer los detalles exactos parche por parche.

Brian Gallew ha contribuido al soporte de OpenSSL para el módulo socket. OpenSSL es una implementación de Secure Socket Layer, que encripta los datos que se envían a través de un socket. Al compilar Python, puedes editar Modules/Setup para incluir el soporte de SSL, que añade una función adicional al módulo socket: socket.ssl(socket, keyfile, certfile), que toma un objeto socket y retorna un socket SSL. Los módulos httplib y urllib también han sido modificados para soportar URLs https://, aunque nadie ha implementado FTP o SMTP sobre SSL.

El módulo httplib ha sido reescrito por Greg Stein para soportar HTTP/1.1. Se proporciona compatibilidad con la versión 1.5 de httplib, aunque el uso de las características de HTTP/1.1, como el pipelining, requerirá reescribir el código para utilizar un conjunto diferente de interfaces.

El módulo Tkinter soporta ahora la versión 8.1, 8.2 o 8.3 de Tcl/Tk, y se ha eliminado el soporte para las versiones 7.x más antiguas. El módulo Tkinter ahora soporta la visualización de cadenas Unicode en los widgets Tk. Además, Fredrik Lundh ha contribuido con una optimización que hace que operaciones como create_line y create_polygon sean mucho más rápidas, especialmente cuando se utilizan muchas coordenadas.

El módulo curses ha sido ampliado en gran medida, a partir de la versión mejorada de Oliver Andrich, para proporcionar muchas funciones adicionales de los curses ncurses y SYSV, como el color, el soporte de conjuntos de caracteres alternativos, los pads y el soporte de ratón. Esto significa que el módulo ya no es compatible con los sistemas operativos que sólo tienen curses BSD, pero no parece haber ningún sistema operativo actualmente mantenido que caiga en esta categoría.

Como se mencionó en la discusión anterior sobre el soporte Unicode de la 2.0, la implementación subyacente de las expresiones regulares proporcionadas por el módulo re ha sido cambiada. SRE, un nuevo motor de expresiones regulares escrito por Fredrik Lundh y parcialmente financiado por Hewlett Packard, soporta la comparación con cadenas de 8 bits y cadenas Unicode.

Nuevos módulos

Se han añadido varios módulos nuevos. Nos limitaremos a enumerarlos con breves descripciones; consulte la documentación de la versión 2.0 para conocer los detalles de un módulo concreto.

atexit: Para registrar las funciones que serán llamadas antes de que el intérprete de Python salga. El código que actualmente establece sys.exitfunc directamente debe cambiarse para usar el módulo atexit en su lugar, importando atexit y llamando a atexit.register() con la función a llamar al salir. (Contribución de Skip Montanaro)

codecs, encodings, unicodedata: Añadidos como parte del nuevo soporte de Unicode.

filecmp: Sustituye a los antiguos módulos cmp, cmpcache y dircmp, que han quedado obsoletos. (Contribución de Gordon MacMillan y Moshe Zadka)

gettext: Este módulo proporciona soporte de internacionalización (I18N) y localización (L10N) para los programas de Python, proporcionando una interfaz a la biblioteca de catálogo de mensajes GNU gettext. (Integrado por Barry Warsaw, a partir de contribuciones separadas de Martin von Löwis, Peter Funk y James Henstridge)

linuxaudiodev: Soporte para el dispositivo /dev/audio en Linux, un gemelo del módulo existente sunaudiodev. (Contribuido por Peter Bosch, con correcciones de Jeremy Hylton)

mmap: Una interfaz para archivos mapeados en memoria tanto en Windows como en Unix. El contenido de un fichero puede ser mapeado directamente en memoria, en cuyo momento se comporta como una cadena mutable, por lo que su contenido puede ser leído y modificado. Incluso pueden pasarse a funciones que esperan cadenas ordinarias, como el módulo re. (Contribución de Sam Rushing, con algunas extensiones de A.M. Kuchling)

pyexpat: Una interfaz para el analizador XML de Expat. (Contribuido por Paul Prescod.)

robotparser: Analiza un archivo robots.txt, que se utiliza para escribir arañas web que evitan amablemente ciertas áreas de un sitio web. El analizador acepta el contenido de un archivo robots.txt, construye un conjunto de reglas a partir de él y puede responder a preguntas sobre la capacidad de búsqueda de una URL determinada. (Contribución de Skip Montanaro)

tabnanny: Un módulo/script para comprobar el código fuente de Python en busca de sangrías ambiguas. (Contribuido por Tim Peters.)

UserString: Una clase base útil para derivar objetos que se comportan como cadenas.

webbrowser: Un módulo que proporciona una forma independiente de la plataforma para lanzar un navegador web en una URL específica. Para cada plataforma, se prueban varios navegadores en un orden específico. El usuario puede modificar el navegador que se lanza estableciendo la variable de entorno BROWSER. (Originalmente inspirado por el parche de Eric S. Raymond a urllib que añadía una funcionalidad similar, pero el módulo final proviene de un código originalmente implementado por Fred Drake como Tools/idle/BrowserControl.py, y adaptado para la biblioteca estándar por Fred)

_winreg: Una interfaz para el registro de Windows. _winreg es una adaptación de las funciones que han formado parte de PythonWin desde 1995, pero ahora se ha añadido a la distribución principal, y se ha mejorado para soportar Unicode. _winreg fue escrito por Bill Tutt y Mark Hammond.

zipfile: Un módulo para leer y escribir archivos con formato ZIP. Se trata de archivos producidos por PKZIP en DOS/Windows o zip en Unix, que no deben confundirse con los archivos con formato gzip (que son compatibles con el módulo gzip) (Contribución de James C. Ahlstrom.)

imputil: Un módulo que proporciona una forma más sencilla de escribir ganchos de importación personalizados, en comparación con el módulo ihooks existente. (Implementado por Greg Stein, con mucha discusión en python-dev a lo largo del camino)

Mejoras en IDLE

IDLE es el IDE oficial de Python multiplataforma, escrito con Tkinter. Python 2.0 incluye IDLE 0.6, que añade una serie de nuevas características y mejoras. Una lista parcial:

Mejoras y optimizaciones de la interfaz de usuario, especialmente en el área de resaltado de sintaxis y auto-indentación.

El navegador de clases muestra ahora más información, como las funciones de nivel superior de un módulo.

El ancho del tabulador es ahora una opción configurable por el usuario. Al abrir un archivo Python existente, IDLE detecta automáticamente las convenciones de sangría y se adapta.

Ahora hay soporte para llamar a los navegadores en varias plataformas, utilizado para abrir la documentación de Python en un navegador.

IDLE ahora tiene una línea de comandos, que es en gran medida similar al intérprete de Python vainilla.

Se añadieron consejos de llamada en muchos lugares.

Ahora IDLE puede instalarse como un paquete.

En la ventana del editor, ahora hay una barra de líneas/columnas en la parte inferior.

Tres nuevos comandos de teclado: Comprobar módulo (Alt-F5), Importar módulo (F5) y Ejecutar script (Ctrl-F5).

Módulos eliminados y obsoletos

Se han eliminado algunos módulos porque son obsoletos, o porque ahora hay mejores formas de hacer lo mismo. El módulo stdwin ha desaparecido; era para un conjunto de herramientas de ventanas independientes de la plataforma que ya no se desarrolla.

Varios módulos han sido trasladados al subdirectorio lib-old: cmp, cmpcache, dircmp, dump, find, grep, packmail, poly, util, whatsound, zmod. Si tiene código que depende de un módulo que ha sido movido a lib-old, puede simplemente añadir ese directorio a sys.path para recuperarlo, pero se recomienda actualizar cualquier código que utilice estos módulos.

Agradecimientos

Los autores desean agradecer a las siguientes personas sus sugerencias sobre varios borradores de este artículo: David Bolen, Mark Hammond, Gregg Hauser, Jeremy Hylton, Fredrik Lundh, Detlef Lannert, Aahz Maruch, Skip Montanaro, Vladimir Marangozov, Tobias Polzin, Guido van Rossum, Neil Schemenauer y Russ Schmidt.

Changelog

Python next

Release date: XXXX-XX-XX

Security

gh-113659 [https://github.com/python/cpython/issues/113659]: Skip .pth files with names starting with a dot or hidden file attribute.

Core and Builtins

gh-102388 [https://github.com/python/cpython/issues/102388]: Fix a bug where iso2022_jp_3 and iso2022_jp_2004 codecs read out of bounds

Library

gh-81194 [https://github.com/python/cpython/issues/81194]: Fix a crash in socket.if_indextoname() with specific value (UINT_MAX). Fix an integer overflow in socket.if_indextoname() on 64-bit non-Windows platforms.

gh-109858 [https://github.com/python/cpython/issues/109858]: Protect zipfile from «quoted-overlap» zipbomb. It now raises BadZipFile when try to read an entry that overlaps with other entry or central directory.

gh-91133 [https://github.com/python/cpython/issues/91133]: Fix a bug in tempfile.TemporaryDirectory cleanup, which now no longer dereferences symlinks when working around file system permission errors.

Windows

gh-109991 [https://github.com/python/cpython/issues/109991]: Windows builds now use OpenSSL 1.1.1w. Note that OpenSSL 1.1 has reached its end of life and no future fixes will be made, and this version of Python is no longer receiving maintenance fixes and will not be updated to OpenSSL 3.0.

Tools/Demos

gh-109991 [https://github.com/python/cpython/issues/109991]: Update GitHub CI workflows to use OpenSSL 3.0.11 and multissltests to use 1.1.1w and 3.0.11.

Python 3.9.18 final

Release date: 2023-08-24

Security

gh-108310 [https://github.com/python/cpython/issues/108310]: Fixed an issue where instances of ssl.SSLSocket were vulnerable to a bypass of the TLS handshake and included protections (like certificate verification) and treating sent unencrypted data as if it were post-handshake TLS encrypted data. Security issue reported as CVE-2023-40217 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-40217] by Aapo Oksman. Patch by Gregory P. Smith.

Library

gh-107845 [https://github.com/python/cpython/issues/107845]: tarfile.data_filter() now takes the location of symlinks into account when determining their target, so it will no longer reject some valid tarballs with LinkOutsideDestinationError.

Tools/Demos

gh-107565 [https://github.com/python/cpython/issues/107565]: Update multissltests and GitHub CI workflows to use OpenSSL 1.1.1v, 3.0.10, and 3.1.2.

C API

gh-99612 [https://github.com/python/cpython/issues/99612]: Fix PyUnicode_DecodeUTF8Stateful() for ASCII-only data: *consumed was not set.

Python 3.9.17 final

Release date: 2023-06-06

Security

gh-103142 [https://github.com/python/cpython/issues/103142]: The version of OpenSSL used in our binary builds has been upgraded to 1.1.1u to address several CVEs.

gh-99889 [https://github.com/python/cpython/issues/99889]: Fixed a security in flaw in uu.decode() that could allow for directory traversal based on the input if no out_file was specified.

gh-104049 [https://github.com/python/cpython/issues/104049]: Do not expose the local on-disk location in directory indexes produced by http.client.SimpleHTTPRequestHandler.

gh-102153 [https://github.com/python/cpython/issues/102153]: urllib.parse.urlsplit() now strips leading C0 control and space characters following the specification for URLs defined by WHATWG in response to CVE-2023-24329. Patch by Illia Volochii.

gh-101727 [https://github.com/python/cpython/issues/101727]: Updated the OpenSSL version used in Windows and macOS binary release builds to 1.1.1t to address CVE-2023-0286, CVE-2022-4303, and CVE-2022-4303 per the OpenSSL 2023-02-07 security advisory [https://www.openssl.org/news/secadv/20230207.txt].

gh-101283 [https://github.com/python/cpython/issues/101283]: subprocess.Popen now uses a safer approach to find cmd.exe when launching with shell=True. Patch by Eryk Sun, based on a patch by Oleg Iarygin.

Core and Builtins

gh-102126 [https://github.com/python/cpython/issues/102126]: Fix deadlock at shutdown when clearing thread states if any finalizer tries to acquire the runtime head lock. Patch by Kumar Aditya.

gh-100892 [https://github.com/python/cpython/issues/100892]: Fix race while iterating over thread states in clearing threading.local. Patch by Kumar Aditya.

Library

gh-103935 [https://github.com/python/cpython/issues/103935]: Use io.open_code() for files to be executed instead of raw open()

gh-102953 [https://github.com/python/cpython/issues/102953]: The extraction methods in tarfile, and shutil.unpack_archive(), have a new a filter argument that allows limiting tar features than may be surprising or dangerous, such as creating files outside the destination directory. See Extraction filters for details.

gh-101997 [https://github.com/python/cpython/issues/101997]: Upgrade pip wheel bundled with ensurepip (pip 23.0.1)

Windows

gh-100180 [https://github.com/python/cpython/issues/100180]: Update Windows installer to OpenSSL 1.1.1s

macOS

gh-103142 [https://github.com/python/cpython/issues/103142]: Update macOS installer to use OpenSSL 1.1.1u.

Python 3.9.16 final

Release date: 2022-12-06

Security

gh-100001 [https://github.com/python/cpython/issues/100001]: python -m http.server no longer allows terminal control characters sent within a garbage request to be printed to the stderr server log.

This is done by changing the http.server BaseHTTPRequestHandler .log_message method to replace control characters with a \xHH hex escape before printing.

gh-87604 [https://github.com/python/cpython/issues/87604]: Avoid publishing list of active per-interpreter audit hooks via the gc module

gh-98433 [https://github.com/python/cpython/issues/98433]: The IDNA codec decoder used on DNS hostnames by socket or asyncio related name resolution functions no longer involves a quadratic algorithm. This prevents a potential CPU denial of service if an out-of-spec excessive length hostname involving bidirectional characters were decoded. Some protocols such as urllib http 3xx redirects potentially allow for an attacker to supply such a name.

gh-98739 [https://github.com/python/cpython/issues/98739]: Update bundled libexpat to 2.5.0

gh-98517 [https://github.com/python/cpython/issues/98517]: Port XKCP’s fix for the buffer overflows in SHA-3 (CVE-2022-37454).

gh-97514 [https://github.com/python/cpython/issues/97514]: On Linux the multiprocessing module returns to using filesystem backed unix domain sockets for communication with the forkserver process instead of the Linux abstract socket namespace. Only code that chooses to use the «forkserver» start method is affected.

Abstract sockets have no permissions and could allow any user on the system in the same network namespace [https://man7.org/linux/man-pages/man7/network_namespaces.7.html] (often the whole system) to inject code into the multiprocessing forkserver process. This was a potential privilege escalation. Filesystem based socket permissions restrict this to the forkserver process user as was the default in Python 3.8 and earlier.

This prevents Linux CVE-2022-42919 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-42919].

gh-68966 [https://github.com/python/cpython/issues/68966]: The deprecated mailcap module now refuses to inject unsafe text (filenames, MIME types, parameters) into shell commands. Instead of using such text, it will warn and act as if a match was not found (or for test commands, as if the test failed).

Python 3.9.15 final

Release date: 2022-10-11

Security

gh-97616 [https://github.com/python/cpython/issues/97616]: Fix multiplying a list by an integer (list *= int): detect the integer overflow when the new allocated length is close to the maximum size. Issue reported by Jordan Limor. Patch by Victor Stinner.

gh-97612 [https://github.com/python/cpython/issues/97612]: Fix a shell code injection vulnerability in the get-remote-certificate.py example script. The script no longer uses a shell to run openssl commands. Issue reported and initial fix by Caleb Shortt. Patch by Victor Stinner.

Core and Builtins

gh-96848 [https://github.com/python/cpython/issues/96848]: Fix command line parsing: reject -X int_max_str_digits option with no value (invalid) when the PYTHONINTMAXSTRDIGITS environment variable is set to a valid limit. Patch by Victor Stinner.

gh-95778 [https://github.com/python/cpython/issues/95778]: When ValueError is raised if an integer is larger than the limit, mention the sys.set_int_max_str_digits() function in the error message. Patch by Victor Stinner.

Library

gh-97005 [https://github.com/python/cpython/issues/97005]: Update bundled libexpat to 2.4.9

Windows

gh-96577 [https://github.com/python/cpython/issues/96577]: Fixes a potential buffer overrun in msilib.

macOS

gh-97897 [https://github.com/python/cpython/issues/97897]: The macOS 13 SDK includes support for the mkfifoat and mknodat system calls. Using the dir_fd option with either os.mkfifo() or os.mknod() could result in a segfault if cpython is built with the macOS 13 SDK but run on an earlier version of macOS. Prevent this by adding runtime support for detection of these system calls («weaklinking») as is done for other newer syscalls on macOS.

Python 3.9.14 final

Release date: 2022-09-06

Security

gh-95778 [https://github.com/python/cpython/issues/95778]: Converting between int and str in bases other than 2 (binary), 4, 8 (octal), 16 (hexadecimal), or 32 such as base 10 (decimal) now raises a ValueError if the number of digits in string form is above a limit to avoid potential denial of service attacks due to the algorithmic complexity. This is a mitigation for CVE-2020-10735 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-10735].

This new limit can be configured or disabled by environment variable, command line flag, or sys APIs. See the integer string conversion length limitation documentation. The default limit is 4300 digits in string form.

Patch by Gregory P. Smith [Google] and Christian Heimes [Red Hat] with feedback from Victor Stinner, Thomas Wouters, Steve Dower, Ned Deily, and Mark Dickinson.

gh-87389 [https://github.com/python/cpython/issues/87389]: http.server: Fix an open redirection vulnerability in the HTTP server when an URI path starts with //. Vulnerability discovered, and initial fix proposed, by Hamza Avvan.

Core and Builtins

gh-93065 [https://github.com/python/cpython/issues/93065]: Fix contextvars HAMT implementation to handle iteration over deep trees.

The bug was discovered and fixed by Eli Libman. See MagicStack/immutables#84 [https://github.com/MagicStack/immutables/issues/84] for more details.

Library

gh-94821 [https://github.com/python/cpython/issues/94821]: Fix binding of unix socket to empty address on Linux to use an available address from the abstract namespace, instead of «0».

gh-91810 [https://github.com/python/cpython/issues/91810]: Suppress writing an XML declaration in open files in ElementTree.write() with encoding='unicode' and xml_declaration=None.

bpo-45393 [https://bugs.python.org/issue?@action=redirect&bpo=45393]: Fix the formatting for await x and not x in the operator precedence table when using the help() system.

bpo-46197 [https://bugs.python.org/issue?@action=redirect&bpo=46197]: Fix ensurepip environment isolation for subprocess running pip.

Tests

gh-95280 [https://github.com/python/cpython/issues/95280]: Fix problem with test_ssl test_get_ciphers on systems that require perfect forward secrecy (PFS) ciphers.

gh-94208 [https://github.com/python/cpython/issues/94208]: test_ssl is now checking for supported TLS version and protocols in more tests.

bpo-47016 [https://bugs.python.org/issue?@action=redirect&bpo=47016]: Create a GitHub Actions workflow for verifying bundled pip and setuptools. Patch by Illia Volochii and Adam Turner.

Python 3.9.13 final

Release date: 2022-05-17

Core and Builtins

gh-92311 [https://github.com/python/cpython/issues/92311]: Fixed a bug where setting frame.f_lineno to jump over a list comprehension could misbehave or crash.

gh-92112 [https://github.com/python/cpython/issues/92112]: Fix crash triggered by an evil custom mro() on a metaclass.

gh-92036 [https://github.com/python/cpython/issues/92036]: Fix a crash in subinterpreters related to the garbage collector. When a subinterpreter is deleted, untrack all objects tracked by its GC. To prevent a crash in deallocator functions expecting objects to be tracked by the GC, leak a strong reference to these objects on purpose, so they are never deleted and their deallocator functions are not called. Patch by Victor Stinner.

gh-91421 [https://github.com/python/cpython/issues/91421]: Fix a potential integer overflow in _Py_DecodeUTF8Ex.

bpo-46775 [https://bugs.python.org/issue?@action=redirect&bpo=46775]: Some Windows system error codes(>= 10000) are now mapped into the correct errno and may now raise a subclass of OSError. Patch by Dong-hee Na.

bpo-46962 [https://bugs.python.org/issue?@action=redirect&bpo=46962]: Classes and functions that unconditionally declared their docstrings ignoring the --without-doc-strings compilation flag no longer do so.

The classes affected are pickle.PickleBuffer, testcapi.RecursingInfinitelyError, and types.GenericAlias.

The functions affected are 24 methods in ctypes.

Patch by Oleg Iarygin.

bpo-36819 [https://bugs.python.org/issue?@action=redirect&bpo=36819]: Fix crashes in built-in encoders with error handlers that return position less or equal than the starting position of non-encodable characters.

Library

gh-91581 [https://github.com/python/cpython/issues/91581]: utcfromtimestamp() no longer attempts to resolve fold in the pure Python implementation, since the fold is never 1 in UTC. In addition to being slightly faster in the common case, this also prevents some errors when the timestamp is close to datetime.min. Patch by Paul Ganssle.

gh-92530 [https://github.com/python/cpython/issues/92530]: Fix an issue that occurred after interrupting threading.Condition.notify().

gh-92049 [https://github.com/python/cpython/issues/92049]: Forbid pickling constants re._constants.SUCCESS etc. Previously, pickling did not fail, but the result could not be unpickled.

bpo-47029 [https://bugs.python.org/issue?@action=redirect&bpo=47029]: Always close the read end of the pipe used by multiprocessing.Queue after the last write of buffered data to the write end of the pipe to avoid BrokenPipeError at garbage collection and at multiprocessing.Queue.close() calls. Patch by Géry Ogam.

gh-91910 [https://github.com/python/cpython/issues/91910]: Add missing f prefix to f-strings in error messages from the multiprocessing and asyncio modules.

gh-91810 [https://github.com/python/cpython/issues/91810]: ElementTree method write() and function tostring() now use the text file’s encoding («UTF-8» if not available) instead of locale encoding in XML declaration when encoding="unicode" is specified.

gh-91832 [https://github.com/python/cpython/issues/91832]: Add required attribute to argparse.Action repr output.

gh-91734 [https://github.com/python/cpython/issues/91734]: Fix OSS audio support on Solaris.

gh-91700 [https://github.com/python/cpython/issues/91700]: Compilation of regular expression containing a conditional expression (?(group)...) now raises an appropriate re.error if the group number refers to not defined group. Previously an internal RuntimeError was raised.

gh-91676 [https://github.com/python/cpython/issues/91676]: Fix unittest.IsolatedAsyncioTestCase to shutdown the per test event loop executor before returning from its run method so that a not yet stopped or garbage collected executor state does not persist beyond the test.

gh-90568 [https://github.com/python/cpython/issues/90568]: Parsing \N escapes of Unicode Named Character Sequences in a regular expression raises now re.error instead of TypeError.

gh-91595 [https://github.com/python/cpython/issues/91595]: Fix the comparison of character and integer inside Tools.gdb.libpython.write_repr(). Patch by Yu Liu.

gh-90622 [https://github.com/python/cpython/issues/90622]: Worker processes for concurrent.futures.ProcessPoolExecutor are no longer spawned on demand (a feature added in 3.9) when the multiprocessing context start method is "fork" as that can lead to deadlocks in the child processes due to a fork happening while threads are running.

gh-91575 [https://github.com/python/cpython/issues/91575]: Update case-insensitive matching in the re module to the latest Unicode version.

gh-91581 [https://github.com/python/cpython/issues/91581]: Remove an unhandled error case in the C implementation of calls to datetime.fromtimestamp with no time zone (i.e. getting a local time from an epoch timestamp). This should have no user-facing effect other than giving a possibly more accurate error message when called with timestamps that fall on 10000-01-01 in the local time. Patch by Paul Ganssle.

bpo-34480 [https://bugs.python.org/issue?@action=redirect&bpo=34480]: Fix a bug where _markupbase raised an UnboundLocalError when an invalid keyword was found in marked section. Patch by Marek Suscak.

bpo-27929 [https://bugs.python.org/issue?@action=redirect&bpo=27929]: Fix asyncio.loop.sock_connect() to only resolve names for socket.AF_INET or socket.AF_INET6 families. Resolution may not make sense for other families, like socket.AF_BLUETOOTH and socket.AF_UNIX.

bpo-43323 [https://bugs.python.org/issue?@action=redirect&bpo=43323]: Fix errors in the email module if the charset itself contains undecodable/unencodable characters.

bpo-46787 [https://bugs.python.org/issue?@action=redirect&bpo=46787]: Fix concurrent.futures.ProcessPoolExecutor exception memory leak

bpo-46415 [https://bugs.python.org/issue?@action=redirect&bpo=46415]: Fix ipaddress.ip_{address,interface,network} raising TypeError instead of ValueError if given invalid tuple as address parameter.

bpo-44911 [https://bugs.python.org/issue?@action=redirect&bpo=44911]: IsolatedAsyncioTestCase will no longer throw an exception while cancelling leaked tasks. Patch by Bar Harel.

bpo-44493 [https://bugs.python.org/issue?@action=redirect&bpo=44493]: Add missing terminated NUL in sockaddr_un’s length

This was potentially observable when using non-abstract AF_UNIX datagram sockets to processes written in another programming language.

bpo-42627 [https://bugs.python.org/issue?@action=redirect&bpo=42627]: Fix incorrect parsing of Windows registry proxy settings

bpo-36073 [https://bugs.python.org/issue?@action=redirect&bpo=36073]: Raise ProgrammingError instead of segfaulting on recursive usage of cursors in sqlite3 converters. Patch by Sergey Fedoseev.

Documentation

gh-91888 [https://github.com/python/cpython/issues/91888]: Add a new gh role to the documentation to link to GitHub issues.

gh-91783 [https://github.com/python/cpython/issues/91783]: Document security issues concerning the use of the function shutil.unpack_archive()

gh-91547 [https://github.com/python/cpython/issues/91547]: Remove «Undocumented modules» page.

bpo-44347 [https://bugs.python.org/issue?@action=redirect&bpo=44347]: Clarify the meaning of dirs_exist_ok, a kwarg of shutil.copytree().

bpo-38668 [https://bugs.python.org/issue?@action=redirect&bpo=38668]: Update the introduction to documentation for os.path to remove warnings that became irrelevant after the implementations of PEP 383 [https://www.python.org/dev/peps/pep-0383] and PEP 529 [https://www.python.org/dev/peps/pep-0529].

bpo-47138 [https://bugs.python.org/issue?@action=redirect&bpo=47138]: Pin Jinja to a version compatible with Sphinx version 2.4.4.

bpo-46962 [https://bugs.python.org/issue?@action=redirect&bpo=46962]: All docstrings in code snippets are now wrapped into PyDoc_STR() to follow the guideline of PEP 7’s Documentation Strings paragraph [https://www.python.org/dev/peps/pep-0007/#documentation-strings]. Patch by Oleg Iarygin.

bpo-26792 [https://bugs.python.org/issue?@action=redirect&bpo=26792]: Improve the docstrings of runpy.run_module() and runpy.run_path(). Original patch by Andrew Brezovsky.

bpo-45790 [https://bugs.python.org/issue?@action=redirect&bpo=45790]: Adjust inaccurate phrasing in Definición de tipos de extensión: Tutorial about the ob_base field and the macros used to access its contents.

bpo-42340 [https://bugs.python.org/issue?@action=redirect&bpo=42340]: Document that in some circumstances KeyboardInterrupt may cause the code to enter an inconsistent state. Provided a sample workaround to avoid it if needed.

bpo-41233 [https://bugs.python.org/issue?@action=redirect&bpo=41233]: Link the errnos referenced in Doc/library/exceptions.rst to their respective section in Doc/library/errno.rst, and vice versa. Previously this was only done for EINTR and InterruptedError. Patch by Yan «yyyyyyyan» Orestes.

bpo-38056 [https://bugs.python.org/issue?@action=redirect&bpo=38056]: Overhaul the Manejadores de errores documentation in codecs.

bpo-13553 [https://bugs.python.org/issue?@action=redirect&bpo=13553]: Document tkinter.Tk args.

Tests

gh-91607 [https://github.com/python/cpython/issues/91607]: Fix test_concurrent_futures to test the correct multiprocessing start method context in several cases where the test logic mixed this up.

bpo-47205 [https://bugs.python.org/issue?@action=redirect&bpo=47205]: Skip test for sched_getaffinity() and sched_setaffinity() error case on FreeBSD.

bpo-29890 [https://bugs.python.org/issue?@action=redirect&bpo=29890]: Add tests for ipaddress.IPv4Interface and ipaddress.IPv6Interface construction with tuple arguments. Original patch and tests by louisom.

Build

bpo-47103 [https://bugs.python.org/issue?@action=redirect&bpo=47103]: Windows PGInstrument builds now copy a required DLL into the output directory, making it easier to run the profile stage of a PGO build.

Windows

bpo-47194 [https://bugs.python.org/issue?@action=redirect&bpo=47194]: Update zlib to v1.2.12 to resolve CVE-2018-25032.

bpo-46785 [https://bugs.python.org/issue?@action=redirect&bpo=46785]: Fix race condition between os.stat() and unlinking a file on Windows, by using errors codes returned by FindFirstFileW() when appropriate in win32_xstat_impl.

bpo-40859 [https://bugs.python.org/issue?@action=redirect&bpo=40859]: Update Windows build to use xz-5.2.5

Tools/Demos

gh-91583 [https://github.com/python/cpython/issues/91583]: Fix regression in the code generated by Argument Clinic for functions with the defining_class parameter.

Python 3.9.12 final

Release date: 2022-03-23

Core and Builtins

bpo-46968 [https://bugs.python.org/issue?@action=redirect&bpo=46968]: Check for the existence of the «sys/auxv.h» header in faulthandler to avoid compilation problems in systems where this header doesn’t exist. Patch by Pablo Galindo

Library

bpo-47101 [https://bugs.python.org/issue?@action=redirect&bpo=47101]: hashlib.algorithms_available now lists only algorithms that are provided by activated crypto providers on OpenSSL 3.0. Legacy algorithms are not listed unless the legacy provider has been loaded into the default OSSL context.

bpo-23691 [https://bugs.python.org/issue?@action=redirect&bpo=23691]: Protect the re.finditer() iterator from re-entering.

bpo-42369 [https://bugs.python.org/issue?@action=redirect&bpo=42369]: Fix thread safety of zipfile._SharedFile.tell() to avoid a «zipfile.BadZipFile: Bad CRC-32 for file» exception when reading a ZipFile from multiple threads.

bpo-38256 [https://bugs.python.org/issue?@action=redirect&bpo=38256]: Fix binascii.crc32() when it is compiled to use zlib’c crc32 to work properly on inputs 4+GiB in length instead of returning the wrong result. The workaround prior to this was to always feed the function data in increments smaller than 4GiB or to just call the zlib module function.

bpo-39394 [https://bugs.python.org/issue?@action=redirect&bpo=39394]: A warning about inline flags not at the start of the regular expression now contains the position of the flag.

bpo-47061 [https://bugs.python.org/issue?@action=redirect&bpo=47061]: Deprecate the various modules listed by PEP 594 [https://www.python.org/dev/peps/pep-0594]:

aifc, asynchat, asyncore, audioop, cgi, cgitb, chunk, crypt, imghdr, msilib, nntplib, nis, ossaudiodev, pipes, smtpd, sndhdr, spwd, sunau, telnetlib, uu, xdrlib

bpo-2604 [https://bugs.python.org/issue?@action=redirect&bpo=2604]: Fix bug where doctests using globals would fail when run multiple times.

bpo-45997 [https://bugs.python.org/issue?@action=redirect&bpo=45997]: Fix asyncio.Semaphore re-aquiring FIFO order.

bpo-47022 [https://bugs.python.org/issue?@action=redirect&bpo=47022]: The asynchat, asyncore and smtpd modules have been deprecated since at least Python 3.6. Their documentation has now been updated to note they will removed in Python 3.12 (PEP 594 [https://www.python.org/dev/peps/pep-0594]).

bpo-46421 [https://bugs.python.org/issue?@action=redirect&bpo=46421]: Fix a unittest issue where if the command was invoked as python -m unittest and the filename(s) began with a dot (.), a ValueError is returned.

bpo-40296 [https://bugs.python.org/issue?@action=redirect&bpo=40296]: Fix supporting generic aliases in pydoc.

bpo-14156 [https://bugs.python.org/issue?@action=redirect&bpo=14156]: argparse.FileType now supports an argument of “-” in binary mode, returning the .buffer attribute of sys.stdin/sys.stdout as appropriate. Modes including “x” and “a” are treated equivalently to “w” when argument is “-”. Patch contributed by Josh Rosenberg

Python 3.9.11 final

Release date: 2022-03-16

Core and Builtins

bpo-46852 [https://bugs.python.org/issue?@action=redirect&bpo=46852]: Rename the private undocumented float.__set_format__() method to float.__setformat__() to fix a typo introduced in Python 3.7. The method is only used by test_float. Patch by Victor Stinner.

bpo-46794 [https://bugs.python.org/issue?@action=redirect&bpo=46794]: Bump up the libexpat version into 2.4.6

bpo-46762 [https://bugs.python.org/issue?@action=redirect&bpo=46762]: Fix an assert failure in debug builds when a “<”, “>”, or “=” is the last character in an f-string that’s missing a closing right brace.

bpo-46732 [https://bugs.python.org/issue?@action=redirect&bpo=46732]: Correct the docstring for the __bool__() method. Patch by Jelle Zijlstra.

bpo-40479 [https://bugs.python.org/issue?@action=redirect&bpo=40479]: Add a missing call to va_end() in Modules/_hashopenssl.c.

bpo-46615 [https://bugs.python.org/issue?@action=redirect&bpo=46615]: When iterating over sets internally in setobject.c, acquire strong references to the resulting items from the set. This prevents crashes in corner-cases of various set operations where the set gets mutated.

bpo-43721 [https://bugs.python.org/issue?@action=redirect&bpo=43721]: Fix docstrings of getter, setter, and deleter to clarify that they create a new copy of the property.

bpo-46503 [https://bugs.python.org/issue?@action=redirect&bpo=46503]: Fix an assert when parsing some invalid N escape sequences in f-strings.

bpo-46417 [https://bugs.python.org/issue?@action=redirect&bpo=46417]: Fix a race condition on setting a type __bases__ attribute: the internal function add_subclass() now gets the PyTypeObject.tp_subclasses member after calling PyWeakref_NewRef() which can trigger a garbage collection which can indirectly modify PyTypeObject.tp_subclasses. Patch by Victor Stinner.

bpo-46383 [https://bugs.python.org/issue?@action=redirect&bpo=46383]: Fix invalid signature of _zoneinfo’s module_free function to resolve a crash on wasm32-emscripten platform.

Library

bpo-43253 [https://bugs.python.org/issue?@action=redirect&bpo=43253]: Fix a crash when closing transports where the underlying socket handle is already invalid on the Proactor event loop.

bpo-47004 [https://bugs.python.org/issue?@action=redirect&bpo=47004]: Apply bugfixes from importlib_metadata 4.11.3, including bugfix for EntryPoint.extras, which was returning match objects and not the extras strings.

bpo-46985 [https://bugs.python.org/issue?@action=redirect&bpo=46985]: Upgrade pip wheel bundled with ensurepip (pip 22.0.4)

bpo-46968 [https://bugs.python.org/issue?@action=redirect&bpo=46968]: faulthandler: On Linux 5.14 and newer, dynamically determine size of signal handler stack size CPython allocates using getauxval(AT_MINSIGSTKSZ). This changes allows for Python extension’s request to Linux kernel to use AMX_TILE instruction set on Sapphire Rapids Xeon processor to succeed, unblocking use of the ISA in frameworks.

bpo-46955 [https://bugs.python.org/issue?@action=redirect&bpo=46955]: Expose asyncio.base_events.Server as asyncio.Server. Patch by Stefan Zabka.

bpo-46932 [https://bugs.python.org/issue?@action=redirect&bpo=46932]: Update bundled libexpat to 2.4.7

bpo-25707 [https://bugs.python.org/issue?@action=redirect&bpo=25707]: Fixed a file leak in xml.etree.ElementTree.iterparse() when the iterator is not exhausted. Patch by Jacob Walls.

bpo-44886 [https://bugs.python.org/issue?@action=redirect&bpo=44886]: Inherit asyncio proactor datagram transport from asyncio.DatagramTransport.

bpo-46827 [https://bugs.python.org/issue?@action=redirect&bpo=46827]: Support UDP sockets in asyncio.loop.sock_connect() for selector-based event loops. Patch by Thomas Grainger.

bpo-46811 [https://bugs.python.org/issue?@action=redirect&bpo=46811]: Make test suite support Expat >=2.4.5

bpo-46252 [https://bugs.python.org/issue?@action=redirect&bpo=46252]: Raise TypeError if ssl.SSLSocket is passed to transport-based APIs.

bpo-46784 [https://bugs.python.org/issue?@action=redirect&bpo=46784]: Fix libexpat symbols collisions with user dynamically loaded or statically linked libexpat in embedded Python.

bpo-39327 [https://bugs.python.org/issue?@action=redirect&bpo=39327]: shutil.rmtree() can now work with VirtualBox shared folders when running from the guest operating-system.

bpo-46756 [https://bugs.python.org/issue?@action=redirect&bpo=46756]: Fix a bug in urllib.request.HTTPPasswordMgr.find_user_password() and urllib.request.HTTPPasswordMgrWithPriorAuth.is_authenticated() which allowed to bypass authorization. For example, access to URI example.org/foobar was allowed if the user was authorized for URI example.org/foo.

bpo-45863 [https://bugs.python.org/issue?@action=redirect&bpo=45863]: When the tarfile module creates a pax format archive, it will put an integer representation of timestamps in the ustar header (if possible) for the benefit of older unarchivers, in addition to the existing full-precision timestamps in the pax extended header.

bpo-46672 [https://bugs.python.org/issue?@action=redirect&bpo=46672]: Fix NameError in asyncio.gather() when initial type check fails.

bpo-45948 [https://bugs.python.org/issue?@action=redirect&bpo=45948]: Fixed a discrepancy in the C implementation of the xml.etree.ElementTree module. Now, instantiating an xml.etree.ElementTree.XMLParser with a target=None keyword provides a default xml.etree.ElementTree.TreeBuilder target as the Python implementation does.

bpo-46591 [https://bugs.python.org/issue?@action=redirect&bpo=46591]: Make the IDLE doc URL on the About IDLE dialog clickable.

bpo-46400 [https://bugs.python.org/issue?@action=redirect&bpo=46400]: expat: Update libexpat from 2.4.1 to 2.4.4

bpo-46487 [https://bugs.python.org/issue?@action=redirect&bpo=46487]: Add the get_write_buffer_limits method to asyncio.transports.WriteTransport and to the SSL transport.

bpo-46539 [https://bugs.python.org/issue?@action=redirect&bpo=46539]: In typing.get_type_hints(), support evaluating stringified ClassVar and Final annotations inside Annotated. Patch by Gregory Beauregard.

bpo-46491 [https://bugs.python.org/issue?@action=redirect&bpo=46491]: Allow typing.Annotated to wrap typing.Final and typing.ClassVar. Patch by Gregory Beauregard.

bpo-46436 [https://bugs.python.org/issue?@action=redirect&bpo=46436]: Fix command-line option -d/--directory in module http.server which is ignored when combined with command-line option --cgi. Patch by Géry Ogam.

bpo-41403 [https://bugs.python.org/issue?@action=redirect&bpo=41403]: Make mock.patch() raise a TypeError with a relevant error message on invalid arg. Previously it allowed a cryptic AttributeError to escape.

bpo-46474 [https://bugs.python.org/issue?@action=redirect&bpo=46474]: In importlib.metadata.EntryPoint.pattern, avoid potential REDoS by limiting ambiguity in consecutive whitespace.

bpo-46469 [https://bugs.python.org/issue?@action=redirect&bpo=46469]: asyncio generic classes now return types.GenericAlias in __class_getitem__ instead of the same class.

bpo-46434 [https://bugs.python.org/issue?@action=redirect&bpo=46434]: pdb now gracefully handles help when __doc__ is missing, for example when run with pregenerated optimized .pyc files.

bpo-46333 [https://bugs.python.org/issue?@action=redirect&bpo=46333]: The __eq__() and __hash__() methods of typing.ForwardRef now honor the module parameter of typing.ForwardRef. Forward references from different modules are now differentiated.

bpo-43118 [https://bugs.python.org/issue?@action=redirect&bpo=43118]: Fix a bug in inspect.signature() that was causing it to fail on some subclasses of classes with a __text_signature__ referencing module globals. Patch by Weipeng Hong.

bpo-21987 [https://bugs.python.org/issue?@action=redirect&bpo=21987]: Fix an issue with tarfile.TarFile.getmember() getting a directory name with a trailing slash.

bpo-20392 [https://bugs.python.org/issue?@action=redirect&bpo=20392]: Fix inconsistency with uppercase file extensions in MimeTypes.guess_type(). Patch by Kumar Aditya.

bpo-46080 [https://bugs.python.org/issue?@action=redirect&bpo=46080]: Fix exception in argparse help text generation if a argparse.BooleanOptionalAction argument’s default is argparse.SUPPRESS and it has help specified. Patch by Felix Fontein.

bpo-44439 [https://bugs.python.org/issue?@action=redirect&bpo=44439]: Fix .write() method of a member file in ZipFile, when the input data is an object that supports the buffer protocol, the file length may be wrong.

bpo-45703 [https://bugs.python.org/issue?@action=redirect&bpo=45703]: When a namespace package is imported before another module from the same namespace is created/installed in a different sys.path location while the program is running, calling the importlib.invalidate_caches() function will now also guarantee the new module is noticed.

bpo-24959 [https://bugs.python.org/issue?@action=redirect&bpo=24959]: Fix bug where unittest sometimes drops frames from tracebacks of exceptions raised in tests.

Documentation

bpo-46463 [https://bugs.python.org/issue?@action=redirect&bpo=46463]: Fixes escape4chm.py script used when building the CHM documentation file

Tests

bpo-46913 [https://bugs.python.org/issue?@action=redirect&bpo=46913]: Fix test_faulthandler.test_sigfpe() if Python is built with undefined behavior sanitizer (UBSAN): disable UBSAN on the faulthandler_sigfpe() function. Patch by Victor Stinner.

bpo-46708 [https://bugs.python.org/issue?@action=redirect&bpo=46708]: Prevent default asyncio event loop policy modification warning after test_asyncio execution.

bpo-46616 [https://bugs.python.org/issue?@action=redirect&bpo=46616]: Ensures test_importlib.test_windows cleans up registry keys after completion.

bpo-44359 [https://bugs.python.org/issue?@action=redirect&bpo=44359]: test_ftplib now silently ignores socket errors to prevent logging unhandled threading exceptions. Patch by Victor Stinner.

bpo-46542 [https://bugs.python.org/issue?@action=redirect&bpo=46542]: Fix a Python crash in test_lib2to3 when using Python built in debug mode: limit the recursion limit. Patch by Victor Stinner.

bpo-46576 [https://bugs.python.org/issue?@action=redirect&bpo=46576]: test_peg_generator now disables compiler optimization when testing compilation of its own C extensions to significantly speed up the testing on non-debug builds of CPython.

bpo-46542 [https://bugs.python.org/issue?@action=redirect&bpo=46542]: Fix test_json tests checking for RecursionError: modify these tests to use support.infinite_recursion(). Patch by Victor Stinner.

bpo-13886 [https://bugs.python.org/issue?@action=redirect&bpo=13886]: Skip test_builtin PTY tests on non-ASCII characters if the readline module is loaded. The readline module changes input() behavior, but test_builtin is not intented to test the readline module. Patch by Victor Stinner.

Build

bpo-47024 [https://bugs.python.org/issue?@action=redirect&bpo=47024]: Update OpenSSL to 1.1.1n for macOS installers and all Windows builds.

bpo-38472 [https://bugs.python.org/issue?@action=redirect&bpo=38472]: Fix GCC detection in setup.py when cross-compiling. The C compiler is now run with LC_ALL=C. Previously, the detection failed with a German locale.

bpo-46513 [https://bugs.python.org/issue?@action=redirect&bpo=46513]: configure no longer uses AC_C_CHAR_UNSIGNED macro and pyconfig.h no longer defines reserved symbol __CHAR_UNSIGNED__.

bpo-45925 [https://bugs.python.org/issue?@action=redirect&bpo=45925]: Update Windows installer to use SQLite 3.37.2.

bpo-47032 [https://bugs.python.org/issue?@action=redirect&bpo=47032]: Ensure Windows install builds fail correctly with a non-zero exit code when part of the build fails.

Windows

bpo-44549 [https://bugs.python.org/issue?@action=redirect&bpo=44549]: Update bzip2 to 1.0.8 in Windows builds to mitigate CVE-2016-3189 and CVE-2019-12900

bpo-46948 [https://bugs.python.org/issue?@action=redirect&bpo=46948]: Prevent CVE-2022-26488 by ensuring the Add to PATH option in the Windows installer uses the correct path when being repaired.

bpo-46638 [https://bugs.python.org/issue?@action=redirect&bpo=46638]: Ensures registry virtualization is consistently disabled. For 3.10 and earlier, it remains enabled (some registry writes are protected), while for 3.11 and later it is disabled (registry modifications affect all applications).

macOS

bpo-45925 [https://bugs.python.org/issue?@action=redirect&bpo=45925]: Update macOS installer to SQLite 3.37.2.

IDLE

bpo-46630 [https://bugs.python.org/issue?@action=redirect&bpo=46630]: Make query dialogs on Windows start with a cursor in the entry box.

bpo-45296 [https://bugs.python.org/issue?@action=redirect&bpo=45296]: Clarify close, quit, and exit in IDLE. In the File menu, “Close” and “Exit” are now “Close Window” (the current one) and “Exit” is now “Exit IDLE” (by closing all windows). In Shell, “quit()” and “exit()” mean “close Shell”. If there are no other windows, this also exits IDLE.

bpo-45447 [https://bugs.python.org/issue?@action=redirect&bpo=45447]: Apply IDLE syntax highlighting to pyi files. Patch by Alex Waygood and Terry Jan Reedy.

Python 3.9.10 final

Release date: 2022-01-13

Core and Builtins

bpo-46070 [https://bugs.python.org/issue?@action=redirect&bpo=46070]: Py_EndInterpreter() now explicitly untracks all objects currently tracked by the GC. Previously, if an object was used later by another interpreter, calling PyObject_GC_UnTrack() on the object crashed if the previous or the next object of the PyGC_Head structure became a dangling pointer. Patch by Victor Stinner.

bpo-46085 [https://bugs.python.org/issue?@action=redirect&bpo=46085]: Fix iterator cache mechanism of OrderedDict.

bpo-46110 [https://bugs.python.org/issue?@action=redirect&bpo=46110]: Add a maximum recursion check to the PEG parser to avoid stack overflow. Patch by Pablo Galindo

bpo-46000 [https://bugs.python.org/issue?@action=redirect&bpo=46000]: Improve compatibility of the curses module with NetBSD curses.

bpo-45614 [https://bugs.python.org/issue?@action=redirect&bpo=45614]: Fix traceback display for exceptions with invalid module name.

bpo-45806 [https://bugs.python.org/issue?@action=redirect&bpo=45806]: Re-introduced fix that allows recovery from stack overflow without crashing the interpreter. The original fix as part of bpo-42500 [https://bugs.python.org/issue?@action=redirect&bpo=42500] was reverted (see release notes for Python 3.9.4) since it introduced an ABI change in a bugfix release which is not allowed. The new fix doesn’t introduce any ABI changes. Patch by Mark Shannon.

bpo-45822 [https://bugs.python.org/issue?@action=redirect&bpo=45822]: Fixed a bug in the parser that was causing it to not respect PEP 263 [https://www.python.org/dev/peps/pep-0263] coding cookies when no flags are provided. Patch by Pablo Galindo

bpo-45820 [https://bugs.python.org/issue?@action=redirect&bpo=45820]: Fix a segfault when the parser fails without reading any input. Patch by Pablo Galindo

bpo-42540 [https://bugs.python.org/issue?@action=redirect&bpo=42540]: Fix crash when os.fork() is called with an active non-default memory allocator.

Library

bpo-40479 [https://bugs.python.org/issue?@action=redirect&bpo=40479]: Fix hashlib usedforsecurity option to work correctly with OpenSSL 3.0.0 in FIPS mode.

bpo-46070 [https://bugs.python.org/issue?@action=redirect&bpo=46070]: Fix possible segfault when importing the asyncio module from different sub-interpreters in parallel. Patch by Erlend E. Aasland.

bpo-46278 [https://bugs.python.org/issue?@action=redirect&bpo=46278]: Reflect context argument in AbstractEventLoop.call_*() methods. Loop implementations already support it.

bpo-46239 [https://bugs.python.org/issue?@action=redirect&bpo=46239]: Improve error message when importing asyncio.windows_events on non-Windows.

bpo-20369 [https://bugs.python.org/issue?@action=redirect&bpo=20369]: concurrent.futures.wait() no longer blocks forever when given duplicate Futures. Patch by Kumar Aditya.

bpo-46105 [https://bugs.python.org/issue?@action=redirect&bpo=46105]: Honor spec when generating requirement specs with urls and extras (importlib_metadata 4.8.3).

bpo-26952 [https://bugs.python.org/issue?@action=redirect&bpo=26952]: argparse raises ValueError with clear message when trying to render usage for an empty mutually-exclusive group. Previously it raised a cryptic IndexError.

bpo-27718 [https://bugs.python.org/issue?@action=redirect&bpo=27718]: Fix help for the signal module. Some functions (e.g. signal() and getsignal()) were omitted.

bpo-46032 [https://bugs.python.org/issue?@action=redirect&bpo=46032]: The registry() method of functools.singledispatch() functions checks now the first argument or the first parameter annotation and raises a TypeError if it is not supported. Previously unsupported «types» were ignored (e.g. typing.List[int]) or caused an error at calling time (e.g. list[int]).

bpo-46018 [https://bugs.python.org/issue?@action=redirect&bpo=46018]: Ensure that math.expm1() does not raise on underflow.

bpo-27946 [https://bugs.python.org/issue?@action=redirect&bpo=27946]: Fix possible crash when getting an attribute of class:xml.etree.ElementTree.Element simultaneously with replacing the attrib dict.

bpo-13236 [https://bugs.python.org/issue?@action=redirect&bpo=13236]: unittest.TextTestResult and unittest.TextTestRunner flush now the output stream more often.

bpo-37658 [https://bugs.python.org/issue?@action=redirect&bpo=37658]: Fix issue when on certain conditions asyncio.wait_for() may allow a coroutine to complete successfully, but fail to return the result, potentially causing memory leaks or other issues.

bpo-45831 [https://bugs.python.org/issue?@action=redirect&bpo=45831]: faulthandler can now write ASCII-only strings (like filenames and function names) with a single write() syscall when dumping a traceback. It reduces the risk of getting an unreadable dump when two threads or two processes dump a traceback to the same file (like stderr) at the same time. Patch by Victor Stinner.

bpo-41735 [https://bugs.python.org/issue?@action=redirect&bpo=41735]: Fix thread lock in zlib.Decompress.flush() method before PyObject_GetBuffer.

bpo-45664 [https://bugs.python.org/issue?@action=redirect&bpo=45664]: Fix types.resolve_bases() and types.new_class() for types.GenericAlias instance as a base.

bpo-45663 [https://bugs.python.org/issue?@action=redirect&bpo=45663]: Fix dataclasses.is_dataclass() for dataclasses which are subclasses of types.GenericAlias.

bpo-45662 [https://bugs.python.org/issue?@action=redirect&bpo=45662]: Fix the repr of dataclasses.InitVar with a type alias to the built-in class, e.g. InitVar[list[int]].

bpo-43498 [https://bugs.python.org/issue?@action=redirect&bpo=43498]: Avoid a possible «RuntimeError: dictionary changed size during iteration» when adjusting the process count of ProcessPoolExecutor.

bpo-29620 [https://bugs.python.org/issue?@action=redirect&bpo=29620]: assertWarns() no longer raises a RuntimeException when accessing a module’s __warningregistry__ causes importation of a new module, or when a new module is imported in another thread. Patch by Kernc.

Documentation

bpo-19737 [https://bugs.python.org/issue?@action=redirect&bpo=19737]: Update the documentation for the globals() function.

bpo-45840 [https://bugs.python.org/issue?@action=redirect&bpo=45840]: Improve cross-references in the documentation for the data model.

bpo-45788 [https://bugs.python.org/issue?@action=redirect&bpo=45788]: Link doc for sys.prefix to sysconfig doc on installation paths.

bpo-25381 [https://bugs.python.org/issue?@action=redirect&bpo=25381]: In the extending chapter of the extending doc, update a paragraph about the global variables containing exception information.

bpo-43905 [https://bugs.python.org/issue?@action=redirect&bpo=43905]: Expanded astuple() and asdict() docs, warning about deepcopy being applied and providing a workaround.

bpo-41028 [https://bugs.python.org/issue?@action=redirect&bpo=41028]: Language and version switchers, previously maintained in every cpython branches, are now handled by docsbuild-script.

Tests

bpo-46205 [https://bugs.python.org/issue?@action=redirect&bpo=46205]: Fix hang in runtest_mp due to race condition

bpo-46263 [https://bugs.python.org/issue?@action=redirect&bpo=46263]: Fix test_capi on FreeBSD 14-dev: instruct jemalloc to not fill freed memory with junk byte.

bpo-46150 [https://bugs.python.org/issue?@action=redirect&bpo=46150]: Now fakename in test_pathlib.PosixPathTest.test_expanduser is checked to be non-existent.

bpo-46129 [https://bugs.python.org/issue?@action=redirect&bpo=46129]: Rewrite asyncio.locks tests with unittest.IsolatedAsyncioTestCase usage.

bpo-23819 [https://bugs.python.org/issue?@action=redirect&bpo=23819]: Fixed asyncio tests in python optimized mode. Patch by Kumar Aditya.

bpo-46114 [https://bugs.python.org/issue?@action=redirect&bpo=46114]: Fix test case for OpenSSL 3.0.1 version. OpenSSL 3.0 uses 0xMNN00PP0L.

bpo-19460 [https://bugs.python.org/issue?@action=redirect&bpo=19460]: Add new Test for email.mime.nonmultipart.MIMENonMultipart.

bpo-45835 [https://bugs.python.org/issue?@action=redirect&bpo=45835]: Fix race condition in test_queue tests with multiple «feeder» threads.

Build

bpo-46263 [https://bugs.python.org/issue?@action=redirect&bpo=46263]: configure no longer sets MULTIARCH on FreeBSD platforms.

bpo-46106 [https://bugs.python.org/issue?@action=redirect&bpo=46106]: Updated OpenSSL to 1.1.1m in Windows builds, macOS installer builds, and CI. Patch by Kumar Aditya.

bpo-44035 [https://bugs.python.org/issue?@action=redirect&bpo=44035]: CI now verifies that autoconf files have been regenerated with a current and unpatched autoconf package.

bpo-33393 [https://bugs.python.org/issue?@action=redirect&bpo=33393]: Update config.guess to 2021-06-03 and config.sub to 2021-08-14. Makefile now has an update-config target to make updating more convenient.

bpo-45866 [https://bugs.python.org/issue?@action=redirect&bpo=45866]: make regen-all now produces the same output when run from a directory other than the source tree: when building Python out of the source tree. pegen now strips directory of the «generated by pygen from <FILENAME>» header Patch by Victor Stinner.

bpo-41498 [https://bugs.python.org/issue?@action=redirect&bpo=41498]: Python now compiles on platforms without sigset_t. Several functions in signal are not available when sigset_t is missing.

Based on patch by Roman Yurchak for pyodide.

bpo-45881 [https://bugs.python.org/issue?@action=redirect&bpo=45881]: setup.py now uses CC from environment first to discover multiarch and cross compile paths.

Windows

bpo-45901 [https://bugs.python.org/issue?@action=redirect&bpo=45901]: When installed through the Microsoft Store and set as the default app for *.py files, command line arguments will now be passed to Python when invoking a script without explicitly launching Python (that is, script.py args rather than python script.py args).

macOS

bpo-40477 [https://bugs.python.org/issue?@action=redirect&bpo=40477]: The Python Launcher app for macOS now properly launches scripts and, if necessary, the Terminal app when running on recent macOS releases.

bpo-45732 [https://bugs.python.org/issue?@action=redirect&bpo=45732]: Update python.org macOS installer to use Tcl/Tk 8.6.12.

Tools/Demos

bpo-45838 [https://bugs.python.org/issue?@action=redirect&bpo=45838]: Fix line number calculation when debugging Python with GDB.

C API

bpo-39026 [https://bugs.python.org/issue?@action=redirect&bpo=39026]: Fix Python.h to build C extensions with Xcode: remove a relative include from Include/cpython/pystate.h.

Python 3.9.9 final

Release date: 2021-11-15

Core and Builtins

bpo-45738 [https://bugs.python.org/issue?@action=redirect&bpo=45738]: Fix computation of error location for invalid continuation characters in the parser. Patch by Pablo Galindo.

Library

bpo-45235 [https://bugs.python.org/issue?@action=redirect&bpo=45235]: Reverted an argparse bugfix that caused regression in the handling of default arguments for subparsers. This prevented leaf level arguments from taking precedence over root level arguments.

bpo-45765 [https://bugs.python.org/issue?@action=redirect&bpo=45765]: In importlib.metadata, fix distribution discovery for an empty path.

bpo-45644 [https://bugs.python.org/issue?@action=redirect&bpo=45644]: In-place JSON file formatting using python3 -m json.tool infile infile now works correctly, previously it left the file empty. Patch by Chris Wesseling.

Documentation

bpo-45772 [https://bugs.python.org/issue?@action=redirect&bpo=45772]: socket.socket documentation is corrected to a class from a function.

bpo-45392 [https://bugs.python.org/issue?@action=redirect&bpo=45392]: Update the docstring of the type built-in to remove a redundant line and to mention keyword arguments for the constructor.

Windows

bpo-45732 [https://bugs.python.org/issue?@action=redirect&bpo=45732]: Updates bundled Tcl/Tk to 8.6.12.

bpo-45720 [https://bugs.python.org/issue?@action=redirect&bpo=45720]: Internal reference to shlwapi.dll was dropped to help improve startup time. This DLL will no longer be loaded at the start of every Python process.

Python 3.9.8 final

Release date: 2021-11-05

Core and Builtins

bpo-30570 [https://bugs.python.org/issue?@action=redirect&bpo=30570]: Fixed a crash in issubclass() from infinite recursion when searching pathological __bases__ tuples.

bpo-45494 [https://bugs.python.org/issue?@action=redirect&bpo=45494]: Fix parser crash when reporting errors involving invalid continuation characters. Patch by Pablo Galindo.

bpo-45385 [https://bugs.python.org/issue?@action=redirect&bpo=45385]: Fix reference leak from descr_check. Patch by Dong-hee Na.

bpo-45167 [https://bugs.python.org/issue?@action=redirect&bpo=45167]: Fix deepcopying of types.GenericAlias objects.

bpo-44219 [https://bugs.python.org/issue?@action=redirect&bpo=44219]: Release the GIL while performing isatty system calls on arbitrary file descriptors. In particular, this affects os.isatty(), os.device_encoding() and io.TextIOWrapper. By extension, io.open() in text mode is also affected. This change solves a deadlock in os.isatty(). Patch by Vincent Michel in bpo-44219 [https://bugs.python.org/issue?@action=redirect&bpo=44219].

bpo-44959 [https://bugs.python.org/issue?@action=redirect&bpo=44959]: Added fallback to extension modules with “.sl” suffix on HP-UX

bpo-44050 [https://bugs.python.org/issue?@action=redirect&bpo=44050]: Extensions that indicate they use global state (by setting m_size to -1) can again be used in multiple interpreters. This reverts to behavior of Python 3.8.

bpo-45121 [https://bugs.python.org/issue?@action=redirect&bpo=45121]: Fix issue where Protocol.__init__ raises RecursionError when it’s called directly or via super(). Patch provided by Yurii Karabas.

bpo-45083 [https://bugs.python.org/issue?@action=redirect&bpo=45083]: When the interpreter renders an exception, its name now has a complete qualname. Previously only the class name was concatenated to the module name, which sometimes resulted in an incorrect full name being displayed.

(This issue impacted only the C code exception rendering, the traceback module was using qualname already).

Library

bpo-45678 [https://bugs.python.org/issue?@action=redirect&bpo=45678]: Fix bug in Python 3.9 that meant functools.singledispatchmethod failed to properly wrap the attributes of the target method. Patch by Alex Waygood.

bpo-45679 [https://bugs.python.org/issue?@action=redirect&bpo=45679]: Fix caching of multi-value typing.Literal. Literal[True, 2] is no longer equal to Literal[1, 2].

bpo-45438 [https://bugs.python.org/issue?@action=redirect&bpo=45438]: Fix typing.Signature string representation for generic builtin types.

bpo-45581 [https://bugs.python.org/issue?@action=redirect&bpo=45581]: sqlite3.connect() now correctly raises MemoryError if the underlying SQLite API signals memory error. Patch by Erlend E. Aasland.

bpo-39679 [https://bugs.python.org/issue?@action=redirect&bpo=39679]: Fix bug in functools.singledispatchmethod that caused it to fail when attempting to register a classmethod() or staticmethod() using type annotations. Patch contributed by Alex Waygood.

bpo-45515 [https://bugs.python.org/issue?@action=redirect&bpo=45515]: Add references to zoneinfo in the datetime documentation, mostly replacing outdated references to dateutil.tz. Change by Paul Ganssle.

bpo-45467 [https://bugs.python.org/issue?@action=redirect&bpo=45467]: Fix incremental decoder and stream reader in the «raw-unicode-escape» codec. Previously they failed if the escape sequence was split.

bpo-45461 [https://bugs.python.org/issue?@action=redirect&bpo=45461]: Fix incremental decoder and stream reader in the «unicode-escape» codec. Previously they failed if the escape sequence was split.

bpo-45239 [https://bugs.python.org/issue?@action=redirect&bpo=45239]: Fixed email.utils.parsedate_tz() crashing with UnboundLocalError on certain invalid input instead of returning None. Patch by Ben Hoyt.

bpo-44904 [https://bugs.python.org/issue?@action=redirect&bpo=44904]: Fix bug in the doctest module that caused it to fail if a docstring included an example with a classmethod property. Patch by Alex Waygood.

bpo-45406 [https://bugs.python.org/issue?@action=redirect&bpo=45406]: Make inspect.getmodule() catch FileNotFoundError raised by :”func:inspect.getabsfile, and return None to indicate that the module could not be determined.

bpo-45262 [https://bugs.python.org/issue?@action=redirect&bpo=45262]: Prevent use-after-free in asyncio. Make sure the cached running loop holder gets cleared on dealloc to prevent use-after-free in get_running_loop

bpo-45386 [https://bugs.python.org/issue?@action=redirect&bpo=45386]: Make xmlrpc.client more robust to C runtimes where the underlying C strftime function results in a ValueError when testing for year formatting options.

bpo-45371 [https://bugs.python.org/issue?@action=redirect&bpo=45371]: Fix clang rpath issue in distutils. The UnixCCompiler now uses correct clang option to add a runtime library directory (rpath) to a shared library.

bpo-20028 [https://bugs.python.org/issue?@action=redirect&bpo=20028]: Improve error message of csv.Dialect when initializing. Patch by Vajrasky Kok and Dong-hee Na.

bpo-45343 [https://bugs.python.org/issue?@action=redirect&bpo=45343]: Update bundled pip to 21.2.4 and setuptools to 58.1.0

bpo-41710 [https://bugs.python.org/issue?@action=redirect&bpo=41710]: On Unix, if the sem_clockwait() function is available in the C library (glibc 2.30 and newer), the threading.Lock.acquire() method now uses the monotonic clock (time.CLOCK_MONOTONIC) for the timeout, rather than using the system clock (time.CLOCK_REALTIME), to not be affected by system clock changes. Patch by Victor Stinner.

bpo-45328 [https://bugs.python.org/issue?@action=redirect&bpo=45328]: Fixed http.client.HTTPConnection to work properly in OSs that don’t support the TCP_NODELAY socket option.

bpo-1596321 [https://bugs.python.org/issue?@action=redirect&bpo=1596321]: Fix the threading._shutdown() function when the threading module was imported first from a thread different than the main thread: no longer log an error at Python exit.

bpo-45274 [https://bugs.python.org/issue?@action=redirect&bpo=45274]: Fix a race condition in the Thread.join() method of the threading module. If the function is interrupted by a signal and the signal handler raises an exception, make sure that the thread remains in a consistent state to prevent a deadlock. Patch by Victor Stinner.

bpo-45238 [https://bugs.python.org/issue?@action=redirect&bpo=45238]: Fix unittest.IsolatedAsyncioTestCase.debug(): it runs now asynchronous methods and callbacks.

bpo-36674 [https://bugs.python.org/issue?@action=redirect&bpo=36674]: unittest.TestCase.debug() raises now a unittest.SkipTest if the class or the test method are decorated with the skipping decorator.

bpo-45235 [https://bugs.python.org/issue?@action=redirect&bpo=45235]: Fix an issue where argparse would not preserve values in a provided namespace when using a subparser with defaults.

bpo-45234 [https://bugs.python.org/issue?@action=redirect&bpo=45234]: Fixed a regression in copyfile(), copy(), copy2() raising FileNotFoundError when source is a directory, which should raise IsADirectoryError

bpo-45228 [https://bugs.python.org/issue?@action=redirect&bpo=45228]: Fix stack buffer overflow in parsing J1939 network address.

bpo-45192 [https://bugs.python.org/issue?@action=redirect&bpo=45192]: Fix the tempfile._infer_return_type function so that the dir argument of the tempfile functions accepts an object implementing the os.PathLike protocol.

Patch by Kyungmin Lee.

bpo-45160 [https://bugs.python.org/issue?@action=redirect&bpo=45160]: When tracing a tkinter variable used by a ttk OptionMenu, callbacks are no longer made twice.

bpo-35474 [https://bugs.python.org/issue?@action=redirect&bpo=35474]: Calling mimetypes.guess_all_extensions() with strict=False no longer affects the result of the following call with strict=True. Also, mutating the returned list no longer affects the global state.

bpo-45166 [https://bugs.python.org/issue?@action=redirect&bpo=45166]: typing.get_type_hints() now works with Final wrapped in ForwardRef.

bpo-45097 [https://bugs.python.org/issue?@action=redirect&bpo=45097]: Remove deprecation warnings about the loop argument in asyncio incorrectly emitted in cases when the user does not pass the loop argument.

bpo-45081 [https://bugs.python.org/issue?@action=redirect&bpo=45081]: Fix issue when dataclasses that inherit from typing.Protocol subclasses have wrong __init__. Patch provided by Yurii Karabas.

bpo-24444 [https://bugs.python.org/issue?@action=redirect&bpo=24444]: Fixed an error raised in argparse help display when help for an option is set to 1+ blank spaces or when choices arg is an empty container.

bpo-45021 [https://bugs.python.org/issue?@action=redirect&bpo=45021]: Fix a potential deadlock at shutdown of forked children when using concurrent.futures module

bpo-45030 [https://bugs.python.org/issue?@action=redirect&bpo=45030]: Fix integer overflow in pickling and copying the range iterator.

bpo-39039 [https://bugs.python.org/issue?@action=redirect&bpo=39039]: tarfile.open raises ReadError when a zlib error occurs during file extraction.

bpo-44594 [https://bugs.python.org/issue?@action=redirect&bpo=44594]: Fix an edge case of ExitStack and AsyncExitStack exception chaining. They will now match with block behavior when __context__ is explicitly set to None when the exception is in flight.

Documentation

bpo-45726 [https://bugs.python.org/issue?@action=redirect&bpo=45726]: Improve documentation for functools.singledispatch() and functools.singledispatchmethod.

bpo-45680 [https://bugs.python.org/issue?@action=redirect&bpo=45680]: Amend the docs on GenericAlias objects to clarify that non-container classes can also implement __class_getitem__. Patch contributed by Alex Waygood.

bpo-45655 [https://bugs.python.org/issue?@action=redirect&bpo=45655]: Add a new «relevant PEPs» section to the top of the documentation for the typing module. Patch by Alex Waygood.

bpo-45604 [https://bugs.python.org/issue?@action=redirect&bpo=45604]: Add level argument to multiprocessing.log_to_stderr function docs.

bpo-45464 [https://bugs.python.org/issue?@action=redirect&bpo=45464]: Mention in the documentation of Built-in Exceptions that inheriting from multiple exception types in a single subclass is not recommended due to possible memory layout incompatibility.

bpo-45449 [https://bugs.python.org/issue?@action=redirect&bpo=45449]: Add note about PEP 585 [https://www.python.org/dev/peps/pep-0585] in collections.abc.

bpo-45516 [https://bugs.python.org/issue?@action=redirect&bpo=45516]: Add protocol description to the importlib.abc.Traversable documentation.

bpo-20692 [https://bugs.python.org/issue?@action=redirect&bpo=20692]: Add Programming FAQ entry explaining that int literal attribute access requires either a space after or parentheses around the literal.

bpo-45216 [https://bugs.python.org/issue?@action=redirect&bpo=45216]: Remove extra documentation listing methods in difflib. It was rendering twice in pydoc and was outdated in some places.

Tests

bpo-45578 [https://bugs.python.org/issue?@action=redirect&bpo=45578]: Add tests for dis.distb()

bpo-45577 [https://bugs.python.org/issue?@action=redirect&bpo=45577]: Add subtests for all pickle protocols in test_zoneinfo.

bpo-43592 [https://bugs.python.org/issue?@action=redirect&bpo=43592]: test.libregrtest now raises the soft resource limit for the maximum number of file descriptors when the default is too low for our test suite as was often the case on macOS.

bpo-40173 [https://bugs.python.org/issue?@action=redirect&bpo=40173]: Fix test.support.import_helper.import_fresh_module().

bpo-45280 [https://bugs.python.org/issue?@action=redirect&bpo=45280]: Add a test case for empty typing.NamedTuple.

bpo-45269 [https://bugs.python.org/issue?@action=redirect&bpo=45269]: Cover case when invalid markers type is supplied to c_make_encoder.

bpo-45209 [https://bugs.python.org/issue?@action=redirect&bpo=45209]: Fix UserWarning: resource_tracker warning in _test_multiprocessing._TestSharedMemory.test_shared_memory_cleaned_after_process_termination

bpo-45195 [https://bugs.python.org/issue?@action=redirect&bpo=45195]: Fix test_readline.test_nonascii(): sometimes, the newline character is not written at the end, so don’t expect it in the output. Patch by Victor Stinner.

bpo-45156 [https://bugs.python.org/issue?@action=redirect&bpo=45156]: Fixes infinite loop on unittest.mock.seal() of mocks created by create_autospec().

bpo-45042 [https://bugs.python.org/issue?@action=redirect&bpo=45042]: Fixes that test classes decorated with @hashlib_helper.requires_hashdigest were skipped all the time.

Build

bpo-43158 [https://bugs.python.org/issue?@action=redirect&bpo=43158]: setup.py now uses values from configure script to build the _uuid extension module. Configure now detects util-linux’s libuuid, too.

bpo-45571 [https://bugs.python.org/issue?@action=redirect&bpo=45571]: Modules/Setup now use PY_CFLAGS_NODIST instead of PY_CFLAGS to compile shared modules.

bpo-45532 [https://bugs.python.org/issue?@action=redirect&bpo=45532]: Update sys.version to use main as fallback information. Patch by Jeong YunWon.

bpo-45405 [https://bugs.python.org/issue?@action=redirect&bpo=45405]: Prevent internal configure error when running configure with recent versions of non-Apple clang. Patch by David Bohman.

bpo-45220 [https://bugs.python.org/issue?@action=redirect&bpo=45220]: Avoid building with the Windows 11 SDK previews automatically. This may be overridden by setting the DefaultWindowsSDKVersion environment variable before building.

Windows

bpo-45337 [https://bugs.python.org/issue?@action=redirect&bpo=45337]: venv now warns when the created environment may need to be accessed at a different path, due to redirections, links or junctions. It also now correctly installs or upgrades components when the alternate path is required.

macOS

bpo-44828 [https://bugs.python.org/issue?@action=redirect&bpo=44828]: Avoid tkinter file dialog failure on macOS 12 Monterey when using the Tk 8.6.11 provided by python.org macOS installers. Patch by Marc Culler of the Tk project.

IDLE

bpo-45296 [https://bugs.python.org/issue?@action=redirect&bpo=45296]: On Windows, change exit/quit message to suggest Ctrl-D, which works, instead of <Ctrl-Z Return>, which does not work in IDLE.

C API

bpo-44687 [https://bugs.python.org/issue?@action=redirect&bpo=44687]: BufferedReader.peek() no longer raises ValueError when the entire file has already been buffered.

bpo-44751 [https://bugs.python.org/issue?@action=redirect&bpo=44751]: Remove crypt.h include from the public Python.h header.

Python 3.9.7 final

Release date: 2021-08-30

Security

bpo-42278 [https://bugs.python.org/issue?@action=redirect&bpo=42278]: Replaced usage of tempfile.mktemp() with TemporaryDirectory to avoid a potential race condition.

bpo-41180 [https://bugs.python.org/issue?@action=redirect&bpo=41180]: Add auditing events to the marshal module, and stop raising code.__init__ events for every unmarshalled code object. Directly instantiated code objects will continue to raise an event, and audit event handlers should inspect or collect the raw marshal data. This reduces a significant performance overhead when loading from .pyc files.

bpo-44394 [https://bugs.python.org/issue?@action=redirect&bpo=44394]: Update the vendored copy of libexpat to 2.4.1 (from 2.2.8) to get the fix for the CVE-2013-0340 «Billion Laughs» vulnerability. This copy is most used on Windows and macOS.

bpo-43124 [https://bugs.python.org/issue?@action=redirect&bpo=43124]: Made the internal putcmd function in smtplib sanitize input for presence of \r and \n characters to avoid (unlikely) command injection.

Core and Builtins

bpo-45018 [https://bugs.python.org/issue?@action=redirect&bpo=45018]: Fixed pickling of range iterators that iterated for over 2**32 times.

bpo-44962 [https://bugs.python.org/issue?@action=redirect&bpo=44962]: Fix a race in WeakKeyDictionary, WeakValueDictionary and WeakSet when two threads attempt to commit the last pending removal. This fixes asyncio.create_task and fixes a data loss in asyncio.run where shutdown_asyncgens is not run

bpo-44954 [https://bugs.python.org/issue?@action=redirect&bpo=44954]: Fixed a corner case bug where the result of float.fromhex('0x.8p-1074') was rounded the wrong way.

bpo-44947 [https://bugs.python.org/issue?@action=redirect&bpo=44947]: Refine the syntax error for trailing commas in import statements. Patch by Pablo Galindo.

bpo-44698 [https://bugs.python.org/issue?@action=redirect&bpo=44698]: Restore behaviour of complex exponentiation with integer-valued exponent of type float or complex.

bpo-44885 [https://bugs.python.org/issue?@action=redirect&bpo=44885]: Correct the ast locations of f-strings with format specs and repeated expressions. Patch by Pablo Galindo

bpo-44872 [https://bugs.python.org/issue?@action=redirect&bpo=44872]: Use new trashcan macros (Py_TRASHCAN_BEGIN/END) in frameobject.c instead of the old ones (Py_TRASHCAN_SAFE_BEGIN/END).

bpo-33930 [https://bugs.python.org/issue?@action=redirect&bpo=33930]: Fix segmentation fault with deep recursion when cleaning method objects. Patch by Augusto Goulart and Pablo Galindo.

bpo-25782 [https://bugs.python.org/issue?@action=redirect&bpo=25782]: Fix bug where PyErr_SetObject hangs when the current exception has a cycle in its context chain.

bpo-44856 [https://bugs.python.org/issue?@action=redirect&bpo=44856]: Fix reference leaks in the error paths of update_bases() and __build_class__. Patch by Pablo Galindo.

bpo-44698 [https://bugs.python.org/issue?@action=redirect&bpo=44698]: Fix undefined behaviour in complex object exponentiation.

bpo-44562 [https://bugs.python.org/issue?@action=redirect&bpo=44562]: Remove uses of PyObject_GC_Del() in error path when initializing types.GenericAlias.

bpo-44523 [https://bugs.python.org/issue?@action=redirect&bpo=44523]: Remove the pass-through for hash() of weakref.proxy objects to prevent unintended consequences when the original referred object dies while the proxy is part of a hashable object. Patch by Pablo Galindo.

bpo-44472 [https://bugs.python.org/issue?@action=redirect&bpo=44472]: Fix ltrace functionality when exceptions are raised. Patch by Pablo Galindo

bpo-44184 [https://bugs.python.org/issue?@action=redirect&bpo=44184]: Fix a crash at Python exit when a deallocator function removes the last strong reference to a heap type. Patch by Victor Stinner.

bpo-39091 [https://bugs.python.org/issue?@action=redirect&bpo=39091]: Fix crash when using passing a non-exception to a generator’s throw() method. Patch by Noah Oxer

Library

bpo-41620 [https://bugs.python.org/issue?@action=redirect&bpo=41620]: run() now always return a TestResult instance. Previously it returned None if the test class or method was decorated with a skipping decorator.

bpo-43913 [https://bugs.python.org/issue?@action=redirect&bpo=43913]: Fix bugs in cleaning up classes and modules in unittest:

Functions registered with addModuleCleanup() were not called unless the user defines tearDownModule() in their test module.

Functions registered with addClassCleanup() were not called if tearDownClass is set to None.

Buffering in TestResult did not work with functions registered with addClassCleanup() and addModuleCleanup().

Errors in functions registered with addClassCleanup() and addModuleCleanup() were not handled correctly in buffered and debug modes.

Errors in setUpModule() and functions registered with addModuleCleanup() were reported in wrong order.

And several lesser bugs.

bpo-45001 [https://bugs.python.org/issue?@action=redirect&bpo=45001]: Made email date parsing more robust against malformed input, namely a whitespace-only Date: header. Patch by Wouter Bolsterlee.

bpo-44449 [https://bugs.python.org/issue?@action=redirect&bpo=44449]: Fix a crash in the signal handler of the faulthandler module: no longer modify the reference count of frame objects. Patch by Victor Stinner.

bpo-44955 [https://bugs.python.org/issue?@action=redirect&bpo=44955]: Method stopTestRun() is now always called in pair with method startTestRun() for TestResult objects implicitly created in run(). Previously it was not called for test methods and classes decorated with a skipping decorator.

bpo-38956 [https://bugs.python.org/issue?@action=redirect&bpo=38956]: argparse.BooleanOptionalAction’s default value is no longer printed twice when used with argparse.ArgumentDefaultsHelpFormatter.

bpo-44581 [https://bugs.python.org/issue?@action=redirect&bpo=44581]: Upgrade bundled pip to 21.2.3 and setuptools to 57.4.0

bpo-44849 [https://bugs.python.org/issue?@action=redirect&bpo=44849]: Fix the os.set_inheritable() function on FreeBSD 14 for file descriptor opened with the O_PATH flag: ignore the EBADF error on ioctl(), fallback on the fcntl() implementation. Patch by Victor Stinner.

bpo-44605 [https://bugs.python.org/issue?@action=redirect&bpo=44605]: The @functools.total_ordering() decorator now works with metaclasses.

bpo-44822 [https://bugs.python.org/issue?@action=redirect&bpo=44822]: sqlite3 user-defined functions and aggregators returning strings with embedded NUL characters are no longer truncated. Patch by Erlend E. Aasland.

bpo-44815 [https://bugs.python.org/issue?@action=redirect&bpo=44815]: Always show loop= arg deprecations in asyncio.gather() and asyncio.sleep()

bpo-44806 [https://bugs.python.org/issue?@action=redirect&bpo=44806]: Non-protocol subclasses of typing.Protocol ignore now the __init__ method inherited from protocol base classes.

bpo-44667 [https://bugs.python.org/issue?@action=redirect&bpo=44667]: The tokenize.tokenize() doesn’t incorrectly generate a NEWLINE token if the source doesn’t end with a new line character but the last line is a comment, as the function is already generating a NL token. Patch by Pablo Galindo

bpo-42853 [https://bugs.python.org/issue?@action=redirect&bpo=42853]: Fix http.client.HTTPSConnection fails to download >2GiB data.

bpo-44752 [https://bugs.python.org/issue?@action=redirect&bpo=44752]: rcompleter does not call getattr() on property objects to avoid the side-effect of evaluating the corresponding method.

bpo-44720 [https://bugs.python.org/issue?@action=redirect&bpo=44720]: weakref.proxy objects referencing non-iterators now raise TypeError rather than dereferencing the null tp_iternext slot and crashing.

bpo-44704 [https://bugs.python.org/issue?@action=redirect&bpo=44704]: The implementation of collections.abc.Set._hash() now matches that of frozenset.__hash__().

bpo-44666 [https://bugs.python.org/issue?@action=redirect&bpo=44666]: Fixed issue in compileall.compile_file() when sys.stdout is redirected. Patch by Stefan Hölzl.

bpo-40897 [https://bugs.python.org/issue?@action=redirect&bpo=40897]: Give priority to using the current class constructor in inspect.signature(). Patch by Weipeng Hong.

bpo-44608 [https://bugs.python.org/issue?@action=redirect&bpo=44608]: Fix memory leak in _tkinter._flatten() if it is called with a sequence or set, but not list or tuple.

bpo-41928 [https://bugs.python.org/issue?@action=redirect&bpo=41928]: Update shutil.copyfile() to raise FileNotFoundError instead of confusing IsADirectoryError when a path ending with a os.path.sep does not exist; shutil.copy() and shutil.copy2() are also affected.

bpo-44566 [https://bugs.python.org/issue?@action=redirect&bpo=44566]: handle StopIteration subclass raised from @contextlib.contextmanager generator

bpo-44558 [https://bugs.python.org/issue?@action=redirect&bpo=44558]: Make the implementation consistency of indexOf() between C and Python versions. Patch by Dong-hee Na.

bpo-41249 [https://bugs.python.org/issue?@action=redirect&bpo=41249]: Fixes TypedDict to work with typing.get_type_hints() and postponed evaluation of annotations across modules.

bpo-44461 [https://bugs.python.org/issue?@action=redirect&bpo=44461]: Fix bug with pdb’s handling of import error due to a package which does not have a __main__ module

bpo-42892 [https://bugs.python.org/issue?@action=redirect&bpo=42892]: Fixed an exception thrown while parsing a malformed multipart email by email.message.EmailMessage.

bpo-27827 [https://bugs.python.org/issue?@action=redirect&bpo=27827]: pathlib.PureWindowsPath.is_reserved() now identifies a greater range of reserved filenames, including those with trailing spaces or colons.

bpo-34266 [https://bugs.python.org/issue?@action=redirect&bpo=34266]: Handle exceptions from parsing the arg of pdb’s run/restart command.

bpo-27334 [https://bugs.python.org/issue?@action=redirect&bpo=27334]: The sqlite3 context manager now performs a rollback (thus releasing the database lock) if commit failed. Patch by Luca Citi and Erlend E. Aasland.

bpo-43853 [https://bugs.python.org/issue?@action=redirect&bpo=43853]: Improved string handling for sqlite3 user-defined functions and aggregates:

It is now possible to pass strings with embedded null characters to UDFs

Conversion failures now correctly raise MemoryError

Patch by Erlend E. Aasland.

bpo-43048 [https://bugs.python.org/issue?@action=redirect&bpo=43048]: Handle RecursionError in TracebackException’s constructor, so that long exceptions chains are truncated instead of causing traceback formatting to fail.

bpo-41402 [https://bugs.python.org/issue?@action=redirect&bpo=41402]: Fix email.message.EmailMessage.set_content() when called with binary data and 7bit content transfer encoding.

bpo-32695 [https://bugs.python.org/issue?@action=redirect&bpo=32695]: The compresslevel and preset keyword arguments of tarfile.open() are now both documented and tested.

bpo-34990 [https://bugs.python.org/issue?@action=redirect&bpo=34990]: Fixed a Y2k38 bug in the compileall module where it would fail to compile files with a modification time after the year 2038.

bpo-38840 [https://bugs.python.org/issue?@action=redirect&bpo=38840]: Fix test___all__ on platforms lacking a shared memory implementation.

bpo-30256 [https://bugs.python.org/issue?@action=redirect&bpo=30256]: Pass multiprocessing BaseProxy argument manager_owned through AutoProxy.

bpo-27513 [https://bugs.python.org/issue?@action=redirect&bpo=27513]: email.utils.getaddresses() now accepts email.header.Header objects along with string values. Patch by Zackery Spytz.

bpo-33349 [https://bugs.python.org/issue?@action=redirect&bpo=33349]: lib2to3 now recognizes async generators everywhere.

bpo-29298 [https://bugs.python.org/issue?@action=redirect&bpo=29298]: Fix TypeError when required subparsers without dest do not receive arguments. Patch by Anthony Sottile.

Documentation

bpo-44903 [https://bugs.python.org/issue?@action=redirect&bpo=44903]: Removed the othergui.rst file, any references to it, and the list of GUI frameworks in the FAQ. In their place I’ve added links to the Python Wiki page on GUI frameworks.

bpo-44693 [https://bugs.python.org/issue?@action=redirect&bpo=44693]: Update the definition of __future__ in the glossary by replacing the confusing word «pseudo-module» with a more accurate description.

bpo-35183 [https://bugs.python.org/issue?@action=redirect&bpo=35183]: Add typical examples to os.path.splitext docs

bpo-30511 [https://bugs.python.org/issue?@action=redirect&bpo=30511]: Clarify that shutil.make_archive() is not thread-safe due to reliance on changing the current working directory.

bpo-44561 [https://bugs.python.org/issue?@action=redirect&bpo=44561]: Update of three expired hyperlinks in Doc/distributing/index.rst: «Project structure», «Building and packaging the project», and «Uploading the project to the Python Packaging Index».

bpo-42958 [https://bugs.python.org/issue?@action=redirect&bpo=42958]: Updated the docstring and docs of filecmp.cmp() to be more accurate and less confusing especially in respect to shallow arg.

bpo-44558 [https://bugs.python.org/issue?@action=redirect&bpo=44558]: Match the docstring and python implementation of countOf() to the behavior of its c implementation.

bpo-44544 [https://bugs.python.org/issue?@action=redirect&bpo=44544]: List all kwargs for textwrap.wrap(), textwrap.fill(), and textwrap.shorten(). Now, there are nav links to attributes of TextWrap, which makes navigation much easier while minimizing duplication in the documentation.

bpo-38062 [https://bugs.python.org/issue?@action=redirect&bpo=38062]: Clarify that atexit uses equality comparisons internally.

bpo-43066 [https://bugs.python.org/issue?@action=redirect&bpo=43066]: Added a warning to zipfile docs: filename arg with a leading slash may cause archive to be un-openable on Windows systems.

bpo-27752 [https://bugs.python.org/issue?@action=redirect&bpo=27752]: Documentation of csv.Dialect is more descriptive.

bpo-44453 [https://bugs.python.org/issue?@action=redirect&bpo=44453]: Fix documentation for the return type of sysconfig.get_path().

bpo-39498 [https://bugs.python.org/issue?@action=redirect&bpo=39498]: Add a «Security Considerations» index which links to standard library modules that have explicitly documented security considerations.

bpo-33479 [https://bugs.python.org/issue?@action=redirect&bpo=33479]: Remove the unqualified claim that tkinter is threadsafe. It has not been true for several years and likely never was. An explanation of what is true may be added later, after more discussion, and possibly after patching _tkinter.c,

Tests

bpo-25130 [https://bugs.python.org/issue?@action=redirect&bpo=25130]: Add calls of gc.collect() in tests to support PyPy.

bpo-45011 [https://bugs.python.org/issue?@action=redirect&bpo=45011]: Made tests relying on the _asyncio C extension module optional to allow running on alternative Python implementations. Patch by Serhiy Storchaka.

bpo-44949 [https://bugs.python.org/issue?@action=redirect&bpo=44949]: Fix auto history tests of test_readline: sometimes, the newline character is not written at the end, so don’t expect it in the output.

bpo-44852 [https://bugs.python.org/issue?@action=redirect&bpo=44852]: Add ability to wholesale silence DeprecationWarnings while running the regression test suite.

bpo-40928 [https://bugs.python.org/issue?@action=redirect&bpo=40928]: Notify users running test_decimal regression tests on macOS of potential harmless «malloc can’t allocate region» messages spewed by test_decimal.

bpo-44734 [https://bugs.python.org/issue?@action=redirect&bpo=44734]: Fixed floating point precision issue in turtle tests.

bpo-44708 [https://bugs.python.org/issue?@action=redirect&bpo=44708]: Regression tests, when run with -w, are now re-running only the affected test methods instead of re-running the entire test file.

bpo-30256 [https://bugs.python.org/issue?@action=redirect&bpo=30256]: Add test for nested queues when using multiprocessing shared objects AutoProxy[Queue] inside ListProxy and DictProxy

Build

bpo-44535 [https://bugs.python.org/issue?@action=redirect&bpo=44535]: Enable building using a Visual Studio 2022 install on Windows.

bpo-43298 [https://bugs.python.org/issue?@action=redirect&bpo=43298]: Improved error message when building without a Windows SDK installed.

Windows

bpo-45007 [https://bugs.python.org/issue?@action=redirect&bpo=45007]: Update to OpenSSL 1.1.1l in Windows build

bpo-44572 [https://bugs.python.org/issue?@action=redirect&bpo=44572]: Avoid consuming standard input in the platform module

bpo-40263 [https://bugs.python.org/issue?@action=redirect&bpo=40263]: This is a follow-on bug from https://bugs.python.org/issue26903. Once that is applied we run into an off-by-one assertion problem. The assert was not correct.

macOS

bpo-45007 [https://bugs.python.org/issue?@action=redirect&bpo=45007]: Update macOS installer builds to use OpenSSL 1.1.1l.

bpo-44689 [https://bugs.python.org/issue?@action=redirect&bpo=44689]: ctypes.util.find_library() now works correctly on macOS 11 Big Sur even if Python is built on an older version of macOS. Previously, when built on older macOS systems, find_library was not able to find macOS system libraries when running on Big Sur due to changes in how system libraries are stored.

Python 3.9.6 final

Release date: 2021-06-28

Security

bpo-44022 [https://bugs.python.org/issue?@action=redirect&bpo=44022]: mod:http.client now avoids infinitely reading potential HTTP headers after a 100 Continue status response from the server.

Core and Builtins

bpo-44409 [https://bugs.python.org/issue?@action=redirect&bpo=44409]: Fix error location information for tokenizer errors raised on initialization of the tokenizer. Patch by Pablo Galindo.

bpo-43667 [https://bugs.python.org/issue?@action=redirect&bpo=43667]: Improve Unicode support in non-UTF locales on Oracle Solaris. This issue does not affect other Solaris systems.

bpo-44168 [https://bugs.python.org/issue?@action=redirect&bpo=44168]: Fix error message in the parser involving keyword arguments with invalid expressions. Patch by Pablo Galindo

bpo-44114 [https://bugs.python.org/issue?@action=redirect&bpo=44114]: Fix incorrect dictkeys_reversed and dictitems_reversed function signatures in C code, which broke webassembly builds.

bpo-44070 [https://bugs.python.org/issue?@action=redirect&bpo=44070]: No longer eagerly makes import filenames absolute, except for extension modules, which was introduced in 3.9.5.

bpo-28146 [https://bugs.python.org/issue?@action=redirect&bpo=28146]: Fix a confusing error message in str.format().

bpo-11105 [https://bugs.python.org/issue?@action=redirect&bpo=11105]: When compiling ast.AST objects with recursive references through compile(), the interpreter doesn’t crash anymore instead it raises a RecursionError.

Library

bpo-44516 [https://bugs.python.org/issue?@action=redirect&bpo=44516]: Update vendored pip to 21.1.3

bpo-44482 [https://bugs.python.org/issue?@action=redirect&bpo=44482]: Fix very unlikely resource leak in glob in alternate Python implementations.

bpo-44439 [https://bugs.python.org/issue?@action=redirect&bpo=44439]: Fix in bz2.BZ2File.write() / lzma.LZMAFile.write() methods, when the input data is an object that supports the buffer protocol, the file length may be wrong.

bpo-44434 [https://bugs.python.org/issue?@action=redirect&bpo=44434]: _thread.start_new_thread() no longer calls PyThread_exit_thread() explicitly at the thread exit, the call was redundant. On Linux with the glibc, pthread_exit() aborts the whole process if dlopen() fails to open libgcc_s.so file (ex: EMFILE error). Patch by Victor Stinner.

bpo-44422 [https://bugs.python.org/issue?@action=redirect&bpo=44422]: The threading.enumerate() function now uses a reentrant lock to prevent a hang on reentrant call. Patch by Victor Stinner.

bpo-44395 [https://bugs.python.org/issue?@action=redirect&bpo=44395]: Fix as_string() to pass unixfrom properly. Patch by Dong-hee Na.

bpo-44342 [https://bugs.python.org/issue?@action=redirect&bpo=44342]: [Enum] Be more robust in searching for pickle support before making an enum class unpicklable.

bpo-44356 [https://bugs.python.org/issue?@action=redirect&bpo=44356]: [Enum] Allow multiple data-type mixins if they are all the same.

bpo-44254 [https://bugs.python.org/issue?@action=redirect&bpo=44254]: On Mac, give turtledemo button text a color that works on both light or dark background. Programmers cannot control the latter.

bpo-44145 [https://bugs.python.org/issue?@action=redirect&bpo=44145]: hmac computations were not releasing the GIL while calling the OpenSSL HMAC_Update C API (a new feature in 3.9). This unintentionally prevented parallel computation as other hashlib algorithms support.

bpo-37788 [https://bugs.python.org/issue?@action=redirect&bpo=37788]: Fix a reference leak when a Thread object is never joined.

bpo-44061 [https://bugs.python.org/issue?@action=redirect&bpo=44061]: Fix regression in previous release when calling pkgutil.iter_modules() with a list of pathlib.Path objects

bpo-36515 [https://bugs.python.org/issue?@action=redirect&bpo=36515]: The hashlib module no longer does unaligned memory accesses when compiled for ARM platforms.

bpo-44018 [https://bugs.python.org/issue?@action=redirect&bpo=44018]: random.seed() no longer mutates bytearray inputs.

bpo-38352 [https://bugs.python.org/issue?@action=redirect&bpo=38352]: Add IO, BinaryIO, TextIO, Match, and Pattern to typing.__all__. Patch by Jelle Zijlstra.

bpo-43972 [https://bugs.python.org/issue?@action=redirect&bpo=43972]: When http.server.SimpleHTTPRequestHandler sends a 301 (Moved Permanently) for a directory path not ending with /, add a Content-Length: 0 header. This improves the behavior for certain clients.

bpo-28528 [https://bugs.python.org/issue?@action=redirect&bpo=28528]: Fix a bug in pdb where checkline() raises AttributeError if it is called after reset().

bpo-43776 [https://bugs.python.org/issue?@action=redirect&bpo=43776]: When subprocess.Popen args are provided as a string or as pathlib.Path, the Popen instance repr now shows the right thing.

bpo-43666 [https://bugs.python.org/issue?@action=redirect&bpo=43666]: AIX: Lib/_aix_support.get_platform() may fail in an AIX WPAR. The fileset bos.rte appears to have a builddate in both LPAR and WPAR so this fileset is queried rather than bos.mp64. To prevent a similiar situation (no builddate in ODM) a value (9988) sufficient for completing a build is provided. Patch by M Felt.

bpo-43650 [https://bugs.python.org/issue?@action=redirect&bpo=43650]: Fix MemoryError in shutil.unpack_archive() which fails inside shutil._unpack_zipfile() on large files. Patch by Igor Bolshakov.

bpo-43318 [https://bugs.python.org/issue?@action=redirect&bpo=43318]: Fix a bug where pdb does not always echo cleared breakpoints.

bpo-43295 [https://bugs.python.org/issue?@action=redirect&bpo=43295]: datetime.datetime.strptime() now raises ValueError instead of IndexError when matching 'z' with the %z format specifier.

bpo-37022 [https://bugs.python.org/issue?@action=redirect&bpo=37022]: pdb now displays exceptions from repr() with its p and pp commands.

Documentation

bpo-40620 [https://bugs.python.org/issue?@action=redirect&bpo=40620]: Convert examples in tutorial controlflow.rst section 4.3 to be interpreter-demo style.

bpo-13814 [https://bugs.python.org/issue?@action=redirect&bpo=13814]: In the Design FAQ, answer «Why don’t generators support the with statement?»

bpo-44392 [https://bugs.python.org/issue?@action=redirect&bpo=44392]: Added a new section in the C API documentation for types used in type hinting. Documented Py_GenericAlias and Py_GenericAliasType.

bpo-38291 [https://bugs.python.org/issue?@action=redirect&bpo=38291]: Mark typing.io and typing.re as deprecated since Python 3.8 in the documentation. They were never properly supported by type checkers.

bpo-44322 [https://bugs.python.org/issue?@action=redirect&bpo=44322]: Document that SyntaxError args have a details tuple and that details are adjusted for errors in f-string field replacement expressions.

bpo-44195 [https://bugs.python.org/issue?@action=redirect&bpo=44195]: Corrected references to TraversableResources in docs. There is no TraversableReader.

bpo-41963 [https://bugs.python.org/issue?@action=redirect&bpo=41963]: Document that ConfigParser strips off comments when reading configuration files.

bpo-44072 [https://bugs.python.org/issue?@action=redirect&bpo=44072]: Correct where in the numeric ABC hierarchy ** support is added, i.e., in numbers.Complex, not numbers.Integral.

bpo-43558 [https://bugs.python.org/issue?@action=redirect&bpo=43558]: Add the remark to dataclasses documentation that the __init__() of any base class has to be called in __post_init__(), along with a code example.

bpo-41621 [https://bugs.python.org/issue?@action=redirect&bpo=41621]: Document that collections.defaultdict parameter default_factory defaults to None and is positional-only.

Tests

bpo-44287 [https://bugs.python.org/issue?@action=redirect&bpo=44287]: Fix asyncio test_popen() of test_windows_utils by using a longer timeout. Use military grade battle-tested test.support.SHORT_TIMEOUT timeout rather than a hardcoded timeout of 10 seconds: it’s 30 seconds by default, but it is made longer on slow buildbots. Patch by Victor Stinner.

bpo-44363 [https://bugs.python.org/issue?@action=redirect&bpo=44363]: Account for address sanitizer in test_capi. test_capi now passes when run GCC address sanitizer.

Build

bpo-44381 [https://bugs.python.org/issue?@action=redirect&bpo=44381]: The Windows build now accepts EnableControlFlowGuard set to guard to enable CFG.

Windows

bpo-41299 [https://bugs.python.org/issue?@action=redirect&bpo=41299]: Fix 16ms jitter when using timeouts in threading, such as with threading.Lock.acquire() or threading.Condition.wait().

macOS

bpo-43568 [https://bugs.python.org/issue?@action=redirect&bpo=43568]: Relax unnecessarily restrictive MACOSX_DEPLOYMENT_TARGET check when building extension modules for macOS. Patch by Joshua Root.

bpo-43109 [https://bugs.python.org/issue?@action=redirect&bpo=43109]: Allow –with-lto configure option to work with Apple-supplied Xcode or Command Line Tools.

IDLE

bpo-40128 [https://bugs.python.org/issue?@action=redirect&bpo=40128]: Mostly fix completions on macOS when not using tcl/tk 8.6.11 (as with 3.9). The added update_idletask call should be harmless and possibly helpful otherwise.

bpo-33962 [https://bugs.python.org/issue?@action=redirect&bpo=33962]: Move the indent space setting from the Font tab to the new Windows tab. Patch by Mark Roseman and Terry Jan Reedy.

bpo-40468 [https://bugs.python.org/issue?@action=redirect&bpo=40468]: Split the settings dialog General tab into Windows and Shell/ED tabs. Move help sources, which extend the Help menu, to the Extensions tab. Make space for new options and shorten the dialog. The latter makes the dialog better fit small screens.

bpo-41611 [https://bugs.python.org/issue?@action=redirect&bpo=41611]: Avoid uncaught exceptions in AutoCompleteWindow.winconfig_event().

bpo-41611 [https://bugs.python.org/issue?@action=redirect&bpo=41611]: Fix IDLE sometimes freezing upon tab-completion on macOS.

Tools/Demos

bpo-44074 [https://bugs.python.org/issue?@action=redirect&bpo=44074]: Make patchcheck automatically detect the correct base branch name (previously it was hardcoded to “master”)

C API

bpo-44441 [https://bugs.python.org/issue?@action=redirect&bpo=44441]: Py_RunMain() now resets PyImport_Inittab to its initial value at exit. It must be possible to call PyImport_AppendInittab() or PyImport_ExtendInittab() at each Python initialization. Patch by Victor Stinner.

bpo-42083 [https://bugs.python.org/issue?@action=redirect&bpo=42083]: Fix crash in PyStructSequence_NewType() when passed NULL in the documentation string slot.

Python 3.9.5 final

Release date: 2021-05-03

Security

bpo-43434 [https://bugs.python.org/issue?@action=redirect&bpo=43434]: Creating a sqlite3.Connection object now also produces a sqlite3.connect auditing event. Previously this event was only produced by sqlite3.connect() calls. Patch by Erlend E. Aasland.

bpo-43882 [https://bugs.python.org/issue?@action=redirect&bpo=43882]: The presence of newline or tab characters in parts of a URL could allow some forms of attacks.

Following the controlling specification for URLs defined by WHATWG urllib.parse() now removes ASCII newlines and tabs from URLs, preventing such attacks.

bpo-43472 [https://bugs.python.org/issue?@action=redirect&bpo=43472]: Ensures interpreter-level audit hooks receive the cpython.PyInterpreterState_New event when called through the _xxsubinterpreters module.

bpo-36384 [https://bugs.python.org/issue?@action=redirect&bpo=36384]: ipaddress module no longer accepts any leading zeros in IPv4 address strings. Leading zeros are ambiguous and interpreted as octal notation by some libraries. For example the legacy function socket.inet_aton() treats leading zeros as octal notatation. glibc implementation of modern inet_pton() does not accept any leading zeros. For a while the ipaddress module used to accept ambiguous leading zeros.

bpo-43075 [https://bugs.python.org/issue?@action=redirect&bpo=43075]: Fix Regular Expression Denial of Service (ReDoS) vulnerability in urllib.request.AbstractBasicAuthHandler. The ReDoS-vulnerable regex has quadratic worst-case complexity and it allows cause a denial of service when identifying crafted invalid RFCs. This ReDoS issue is on the client side and needs remote attackers to control the HTTP server.

bpo-42800 [https://bugs.python.org/issue?@action=redirect&bpo=42800]: Audit hooks are now fired for frame.f_code, traceback.tb_frame, and generator code/frame attribute access.

Core and Builtins

bpo-43105 [https://bugs.python.org/issue?@action=redirect&bpo=43105]: Importlib now resolves relative paths when creating module spec objects from file locations.

bpo-42924 [https://bugs.python.org/issue?@action=redirect&bpo=42924]: Fix bytearray repetition incorrectly copying data from the start of the buffer, even if the data is offset within the buffer (e.g. after reassigning a slice at the start of the bytearray to a shorter byte string).

Library

bpo-43993 [https://bugs.python.org/issue?@action=redirect&bpo=43993]: Update bundled pip to 21.1.1.

bpo-43937 [https://bugs.python.org/issue?@action=redirect&bpo=43937]: Fixed the turtle module working with non-default root window.

bpo-43930 [https://bugs.python.org/issue?@action=redirect&bpo=43930]: Update bundled pip to 21.1 and setuptools to 56.0.0

bpo-43920 [https://bugs.python.org/issue?@action=redirect&bpo=43920]: OpenSSL 3.0.0: load_verify_locations() now returns a consistent error message when cadata contains no valid certificate.

bpo-43607 [https://bugs.python.org/issue?@action=redirect&bpo=43607]: urllib can now convert Windows paths with \\?\ prefixes into URL paths.

bpo-43284 [https://bugs.python.org/issue?@action=redirect&bpo=43284]: platform.win32_ver derives the windows version from sys.getwindowsversion().platform_version which in turn derives the version from kernel32.dll (which can be of a different version than Windows itself). Therefore change the platform.win32_ver to determine the version using the platform module’s _syscmd_ver private function to return an accurate version.

bpo-42248 [https://bugs.python.org/issue?@action=redirect&bpo=42248]: [Enum] ensure exceptions raised in _missing_ are released.

bpo-43799 [https://bugs.python.org/issue?@action=redirect&bpo=43799]: OpenSSL 3.0.0: define OPENSSL_API_COMPAT 1.1.1 to suppress deprecation warnings. Python requires OpenSSL 1.1.1 APIs.

bpo-43794 [https://bugs.python.org/issue?@action=redirect&bpo=43794]: Add ssl.OP_IGNORE_UNEXPECTED_EOF constants (OpenSSL 3.0.0)

bpo-43789 [https://bugs.python.org/issue?@action=redirect&bpo=43789]: OpenSSL 3.0.0: Don’t call the password callback function a second time when first call has signaled an error condition.

bpo-43788 [https://bugs.python.org/issue?@action=redirect&bpo=43788]: The header files for ssl error codes are now OpenSSL version-specific. Exceptions will now show correct reason and library codes. The make_ssl_data.py script has been rewritten to use OpenSSL’s text file with error codes.

bpo-43655 [https://bugs.python.org/issue?@action=redirect&bpo=43655]: tkinter dialog windows are now recognized as dialogs by window managers on macOS and X Window.

bpo-43534 [https://bugs.python.org/issue?@action=redirect&bpo=43534]: turtle.textinput() and turtle.numinput() create now a transient window working on behalf of the canvas window.

bpo-43522 [https://bugs.python.org/issue?@action=redirect&bpo=43522]: Fix problem with hostname_checks_common_name. OpenSSL does not copy hostflags from struct SSL_CTX to struct SSL.

bpo-42967 [https://bugs.python.org/issue?@action=redirect&bpo=42967]: Allow bytes separator argument in urllib.parse.parse_qs and urllib.parse.parse_qsl when parsing str query strings. Previously, this raised a TypeError.

bpo-43176 [https://bugs.python.org/issue?@action=redirect&bpo=43176]: Fixed processing of a dataclass that inherits from a frozen dataclass with no fields. It is now correctly detected as an error.

bpo-41735 [https://bugs.python.org/issue?@action=redirect&bpo=41735]: Fix thread locks in zlib module may go wrong in rare case. Patch by Ma Lin.

bpo-36470 [https://bugs.python.org/issue?@action=redirect&bpo=36470]: Fix dataclasses with InitVars and replace(). Patch by Claudiu Popa.

bpo-32745 [https://bugs.python.org/issue?@action=redirect&bpo=32745]: Fix a regression in the handling of ctypes” ctypes.c_wchar_p type: embedded null characters would cause a ValueError to be raised. Patch by Zackery Spytz.

Documentation

bpo-43959 [https://bugs.python.org/issue?@action=redirect&bpo=43959]: The documentation on the PyContextVar C-API was clarified.

bpo-43938 [https://bugs.python.org/issue?@action=redirect&bpo=43938]: Update dataclasses documentation to express that FrozenInstanceError is derived from AttributeError.

bpo-43755 [https://bugs.python.org/issue?@action=redirect&bpo=43755]: Update documentation to reflect that unparenthesized lambda expressions can no longer be the expression part in an if clause in comprehensions and generator expressions since Python 3.9.

bpo-43739 [https://bugs.python.org/issue?@action=redirect&bpo=43739]: Fixing the example code in Doc/extending/extending.rst to declare and initialize the pmodule variable to be of the right type.

Tests

bpo-43961 [https://bugs.python.org/issue?@action=redirect&bpo=43961]: Fix test_logging.test_namer_rotator_inheritance() on Windows: use os.replace() rather than os.rename(). Patch by Victor Stinner.

bpo-43842 [https://bugs.python.org/issue?@action=redirect&bpo=43842]: Fix a race condition in the SMTP test of test_logging. Don’t close a file descriptor (socket) from a different thread while asyncore.loop() is polling the file descriptor. Patch by Victor Stinner.

bpo-43811 [https://bugs.python.org/issue?@action=redirect&bpo=43811]: Tests multiple OpenSSL versions on GitHub Actions. Use ccache to speed up testing.

bpo-43791 [https://bugs.python.org/issue?@action=redirect&bpo=43791]: OpenSSL 3.0.0: Disable testing of legacy protocols TLS 1.0 and 1.1. Tests are failing with TLSV1_ALERT_INTERNAL_ERROR.

Windows

bpo-35306 [https://bugs.python.org/issue?@action=redirect&bpo=35306]: Avoid raising errors from pathlib.Path.exists() when passed an invalid filename.

bpo-38822 [https://bugs.python.org/issue?@action=redirect&bpo=38822]: Fixed os.stat() failing on inaccessible directories with a trailing slash, rather than falling back to the parent directory’s metadata. This implicitly affected os.path.exists() and os.path.isdir().

bpo-26227 [https://bugs.python.org/issue?@action=redirect&bpo=26227]: Fixed decoding of host names in socket.gethostbyaddr() and socket.gethostbyname_ex().

bpo-40432 [https://bugs.python.org/issue?@action=redirect&bpo=40432]: Updated pegen regeneration script on Windows to find and use Python 3.8 or higher. Prior to this, pegen regeneration already required 3.8 or higher, but the script may have used lower versions of Python.

bpo-43745 [https://bugs.python.org/issue?@action=redirect&bpo=43745]: Actually updates Windows release to OpenSSL 1.1.1k. Earlier releases were mislabelled and actually included 1.1.1i again.

bpo-43492 [https://bugs.python.org/issue?@action=redirect&bpo=43492]: Upgrade Windows installer to use SQLite 3.35.5.

macOS

bpo-42119 [https://bugs.python.org/issue?@action=redirect&bpo=42119]: Fix check for macOS SDK paths when building Python. Narrow search to match contents of SDKs, namely only files in /System/Library, /System/IOSSupport, and /usr other than /usr/local. Previously, anything under /System was assumed to be in an SDK which causes problems with the new file system layout in 10.15+ where user file systems may appear to be mounted under /System. Paths in /Library were also incorrectly treated as SDK locations.

bpo-44009 [https://bugs.python.org/issue?@action=redirect&bpo=44009]: Provide «python3.x-intel64» executable to allow reliably forcing macOS universal2 framework builds to run under Rosetta 2 Intel-64 emulation on Apple Silicon Macs. This can be useful for testing or when universal2 wheels are not yet available.

bpo-43492 [https://bugs.python.org/issue?@action=redirect&bpo=43492]: Update macOS installer to use SQLite 3.35.4.

IDLE

bpo-43655 [https://bugs.python.org/issue?@action=redirect&bpo=43655]: IDLE dialog windows are now recognized as dialogs by window managers on macOS and X Window.

Python 3.9.4 final

Release date: 2021-04-04

Core and Builtins

bpo-43710 [https://bugs.python.org/issue?@action=redirect&bpo=43710]: Reverted the fix for https://bugs.python.org/issue42500 as it changed the PyThreadState struct size and broke the 3.9.x ABI in the 3.9.3 release (visible on 32-bit platforms using binaries compiled using an earlier version of Python 3.9.x headers).

Library

bpo-26053 [https://bugs.python.org/issue?@action=redirect&bpo=26053]: Fixed bug where the pdb interactive run command echoed the args from the shell command line, even if those have been overridden at the pdb prompt.

Python 3.9.3 final

Release date: 2021-04-02

Security

bpo-42988 [https://bugs.python.org/issue?@action=redirect&bpo=42988]: CVE-2021-3426: Remove the getfile feature of the pydoc module which could be abused to read arbitrary files on the disk (directory traversal vulnerability). Moreover, even source code of Python modules can contain sensitive data like passwords. Vulnerability reported by David Schwörer.

bpo-43285 [https://bugs.python.org/issue?@action=redirect&bpo=43285]: ftplib no longer trusts the IP address value returned from the server in response to the PASV command by default. This prevents a malicious FTP server from using the response to probe IPv4 address and port combinations on the client network.

Code that requires the former vulnerable behavior may set a trust_server_pasv_ipv4_address attribute on their ftplib.FTP instances to True to re-enable it.

bpo-43439 [https://bugs.python.org/issue?@action=redirect&bpo=43439]: Add audit hooks for gc.get_objects(), gc.get_referrers() and gc.get_referents(). Patch by Pablo Galindo.

Core and Builtins

bpo-43660 [https://bugs.python.org/issue?@action=redirect&bpo=43660]: Fix crash that happens when replacing sys.stderr with a callable that can remove the object while an exception is being printed. Patch by Pablo Galindo.

bpo-43555 [https://bugs.python.org/issue?@action=redirect&bpo=43555]: Report the column offset for SyntaxError for invalid line continuation characters. Patch by Pablo Galindo.

bpo-43517 [https://bugs.python.org/issue?@action=redirect&bpo=43517]: Fix misdetection of circular imports when using from pkg.mod import attr, which caused false positives in non-trivial multi-threaded code.

bpo-35883 [https://bugs.python.org/issue?@action=redirect&bpo=35883]: Python no longer fails at startup with a fatal error if a command line argument contains an invalid Unicode character. The Py_DecodeLocale() function now escapes byte sequences which would be decoded as Unicode characters outside the [U+0000; U+10ffff] range.

bpo-43406 [https://bugs.python.org/issue?@action=redirect&bpo=43406]: Fix a possible race condition where PyErr_CheckSignals tries to execute a non-Python signal handler.

bpo-42500 [https://bugs.python.org/issue?@action=redirect&bpo=42500]: Improve handling of exceptions near recursion limit. Converts a number of Fatal Errors in RecursionErrors.

Library

bpo-43433 [https://bugs.python.org/issue?@action=redirect&bpo=43433]: xmlrpc.client.ServerProxy no longer ignores query and fragment in the URL of the server.

bpo-35930 [https://bugs.python.org/issue?@action=redirect&bpo=35930]: Raising an exception raised in a «future» instance will create reference cycles.

bpo-43577 [https://bugs.python.org/issue?@action=redirect&bpo=43577]: Fix deadlock when using ssl.SSLContext debug callback with ssl.SSLContext.sni_callback().

bpo-43521 [https://bugs.python.org/issue?@action=redirect&bpo=43521]: ast.unparse can now render NaNs and empty sets.

bpo-43423 [https://bugs.python.org/issue?@action=redirect&bpo=43423]: subprocess.communicate() no longer raises an IndexError when there is an empty stdout or stderr IO buffer during a timeout on Windows.

bpo-27820 [https://bugs.python.org/issue?@action=redirect&bpo=27820]: Fixed long-standing bug of smtplib.SMTP where doing AUTH LOGIN with initial_response_ok=False will fail.

The cause is that SMTP.auth_login _always_ returns a password if provided with a challenge string, thus non-compliant with the standard for AUTH LOGIN.

Also fixes bug with the test for smtpd.

bpo-43332 [https://bugs.python.org/issue?@action=redirect&bpo=43332]: Improves the networking efficiency of http.client when using a proxy via set_tunnel(). Fewer small send calls are made during connection setup.

bpo-43399 [https://bugs.python.org/issue?@action=redirect&bpo=43399]: Fix ElementTree.extend not working on iterators when using the Python implementation

bpo-43316 [https://bugs.python.org/issue?@action=redirect&bpo=43316]: The python -m gzip command line application now properly fails when detecting an unsupported extension. It exits with a non-zero exit code and prints an error message to stderr.

bpo-43260 [https://bugs.python.org/issue?@action=redirect&bpo=43260]: Fix TextIOWrapper can not flush internal buffer forever after very large text is written.

bpo-42782 [https://bugs.python.org/issue?@action=redirect&bpo=42782]: Fail fast in shutil.move() to avoid creating destination directories on failure.

bpo-37193 [https://bugs.python.org/issue?@action=redirect&bpo=37193]: Fixed memory leak in socketserver.ThreadingMixIn introduced in Python 3.7.

Documentation

bpo-43199 [https://bugs.python.org/issue?@action=redirect&bpo=43199]: Answer «Why is there no goto?» in the Design and History FAQ.

bpo-43407 [https://bugs.python.org/issue?@action=redirect&bpo=43407]: Clarified that a result from time.monotonic(), time.perf_counter(), time.process_time(), or time.thread_time() can be compared with the result from any following call to the same function - not just the next immediate call.

bpo-27646 [https://bugs.python.org/issue?@action=redirect&bpo=27646]: Clarify that “yield from <expr>” works with any iterable, not just iterators.

bpo-36346 [https://bugs.python.org/issue?@action=redirect&bpo=36346]: Update some deprecated unicode APIs which are documented as «will be removed in 4.0» to «3.12». See PEP 623 [https://www.python.org/dev/peps/pep-0623] for detail.

Tests

bpo-37945 [https://bugs.python.org/issue?@action=redirect&bpo=37945]: Fix test_getsetlocale_issue1813() of test_locale: skip the test if setlocale() fails. Patch by Victor Stinner.

bpo-41561 [https://bugs.python.org/issue?@action=redirect&bpo=41561]: Add workaround for Ubuntu’s custom OpenSSL security level policy.

bpo-43288 [https://bugs.python.org/issue?@action=redirect&bpo=43288]: Fix test_importlib to correctly skip Unicode file tests if the fileystem does not support them.

Build

bpo-43631 [https://bugs.python.org/issue?@action=redirect&bpo=43631]: Update macOS, Windows, and CI to OpenSSL 1.1.1k.

bpo-43617 [https://bugs.python.org/issue?@action=redirect&bpo=43617]: Improve configure.ac: Check for presence of autoconf-archive package and remove our copies of M4 macros.

macOS

bpo-41837 [https://bugs.python.org/issue?@action=redirect&bpo=41837]: Update macOS installer build to use OpenSSL 1.1.1j.

IDLE

bpo-42225 [https://bugs.python.org/issue?@action=redirect&bpo=42225]: Document that IDLE can fail on Unix either from misconfigured IP masquerage rules or failure displaying complex colored (non-ascii) characters.

bpo-43283 [https://bugs.python.org/issue?@action=redirect&bpo=43283]: Document why printing to IDLE’s Shell is often slower than printing to a system terminal and that it can be made faster by pre-formatting a single string before printing.

Python 3.9.2 final

Release date: 2021-02-19

Windows

bpo-43155 [https://bugs.python.org/issue?@action=redirect&bpo=43155]: PyCMethod_New() is now present in python3.lib.

Python 3.9.2 release candidate 1

Release date: 2021-02-16

Security

bpo-42967 [https://bugs.python.org/issue?@action=redirect&bpo=42967]: Fix web cache poisoning vulnerability by defaulting the query args separator to &, and allowing the user to choose a custom separator.

bpo-42938 [https://bugs.python.org/issue?@action=redirect&bpo=42938]: Avoid static buffers when computing the repr of ctypes.c_double and ctypes.c_longdouble values.

Core and Builtins

bpo-42819 [https://bugs.python.org/issue?@action=redirect&bpo=42819]: readline: Explicitly disable bracketed paste in the interactive interpreter, even if it’s set in the inputrc, is enabled by default (eg GNU Readline 8.1), or a user calls readline.read_init_file(). The Python REPL has not implemented bracketed paste support. Also, bracketed mode writes the "\x1b[?2004h" escape sequence into stdout which causes test failures in applications that don’t support it. It can still be explicitly enabled by calling readline.parse_and_bind("set enable-bracketed-paste on"). Patch by Dustin Rodrigues.

bpo-42806 [https://bugs.python.org/issue?@action=redirect&bpo=42806]: Fix the column offsets for f-strings ast nodes surrounded by parentheses and for nodes that spawn multiple lines. Patch by Pablo Galindo.

bpo-40631 [https://bugs.python.org/issue?@action=redirect&bpo=40631]: Fix regression where a single parenthesized starred expression was a valid assignment target.

bpo-32381 [https://bugs.python.org/issue?@action=redirect&bpo=32381]: Fix encoding name when running a .pyc file on Windows: PyRun_SimpleFileExFlags() now uses the correct encoding to decode the filename.

bpo-42536 [https://bugs.python.org/issue?@action=redirect&bpo=42536]: Several built-in and standard library types now ensure that their internal result tuples are always tracked by the garbage collector:

collections.OrderedDict.items()

dict.items()

enumerate()

functools.reduce()

itertools.combinations()

itertools.combinations_with_replacement()

itertools.permutations()

itertools.product()

itertools.zip_longest()

zip()

Previously, they could have become untracked by a prior garbage collection. Patch by Brandt Bucher.

bpo-42195 [https://bugs.python.org/issue?@action=redirect&bpo=42195]: The __args__ of the parameterized generics for typing.Callable and collections.abc.Callable are now consistent. The __args__ for collections.abc.Callable are now flattened while typing.Callable’s have not changed. To allow this change, types.GenericAlias can now be subclassed and collections.abc.Callable’s __class_getitem__ will now return a subclass of types.GenericAlias. Tests for typing were also updated to not subclass things like Callable[..., T] as that is not a valid base class. Finally, both types no longer validate their argtypes, in Callable[[argtypes], resulttype] to prepare for PEP 612 [https://www.python.org/dev/peps/pep-0612]. Patch by Ken Jin.

Library

bpo-43102 [https://bugs.python.org/issue?@action=redirect&bpo=43102]: The namedtuple __new__ method had its __builtins__ set to None instead of an actual dictionary. This created problems for introspection tools.

bpo-43108 [https://bugs.python.org/issue?@action=redirect&bpo=43108]: Fixed a reference leak in the curses module. Patch by Pablo Galindo

bpo-42944 [https://bugs.python.org/issue?@action=redirect&bpo=42944]: Fix random.Random.sample when counts argument is not None.

bpo-42931 [https://bugs.python.org/issue?@action=redirect&bpo=42931]: Add randbytes() to random.__all__.

bpo-42780 [https://bugs.python.org/issue?@action=redirect&bpo=42780]: Fix os.set_inheritable() for O_PATH file descriptors on Linux.

bpo-42851 [https://bugs.python.org/issue?@action=redirect&bpo=42851]: remove __init_subclass__ support for Enum members

bpo-41748 [https://bugs.python.org/issue?@action=redirect&bpo=41748]: Fix HTMLParser parsing rules for element attributes containing commas with spaces. Patch by Karl Dubost.

bpo-42759 [https://bugs.python.org/issue?@action=redirect&bpo=42759]: Fixed equality comparison of tkinter.Variable and tkinter.font.Font. Objects which belong to different Tcl interpreters are now always different, even if they have the same name.

bpo-42756 [https://bugs.python.org/issue?@action=redirect&bpo=42756]: Configure LMTP Unix-domain socket to use socket global default timeout when a timeout is not explicitly provided.

bpo-23328 [https://bugs.python.org/issue?@action=redirect&bpo=23328]: Allow / character in username, password fields on _PROXY envars.

bpo-42655 [https://bugs.python.org/issue?@action=redirect&bpo=42655]: subprocess extra_groups is now correctly passed into setgroups() system call.

bpo-42727 [https://bugs.python.org/issue?@action=redirect&bpo=42727]: EnumMeta.__prepare__ now accepts **kwds to properly support __init_subclass__

bpo-42681 [https://bugs.python.org/issue?@action=redirect&bpo=42681]: Fixed range checks for color and pair numbers in curses.

bpo-37961 [https://bugs.python.org/issue?@action=redirect&bpo=37961]: Fix crash in tracemalloc.Traceback.__repr__() (regressed in Python 3.9).

bpo-42630 [https://bugs.python.org/issue?@action=redirect&bpo=42630]: tkinter functions and constructors which need a default root window raise now RuntimeError with descriptive message instead of obscure AttributeError or NameError if it is not created yet or cannot be created automatically.

bpo-42644 [https://bugs.python.org/issue?@action=redirect&bpo=42644]: logging.disable will now validate the types and value of its parameter. It also now accepts strings representing the levels (as does loging.setLevel) instead of only the numerical values.

bpo-36541 [https://bugs.python.org/issue?@action=redirect&bpo=36541]: Fixed lib2to3.pgen2 to be able to parse PEP-570 positional only argument syntax.

bpo-42517 [https://bugs.python.org/issue?@action=redirect&bpo=42517]: Enum: private names will raise a DeprecationWarning; in 3.10 they will become normal attributes

bpo-42678 [https://bugs.python.org/issue?@action=redirect&bpo=42678]: Enum: call __init_subclass__ after members have been added

bpo-42532 [https://bugs.python.org/issue?@action=redirect&bpo=42532]: Remove unexpected call of __bool__ when passing a spec_arg argument to a Mock.

bpo-42388 [https://bugs.python.org/issue?@action=redirect&bpo=42388]: Fix subprocess.check_output(…, input=None) behavior when text=True to be consistent with that of the documentation and universal_newlines=True.

bpo-34463 [https://bugs.python.org/issue?@action=redirect&bpo=34463]: Fixed discrepancy between traceback and the interpreter in formatting of SyntaxError with lineno not set (traceback was changed to match interpreter).

bpo-42375 [https://bugs.python.org/issue?@action=redirect&bpo=42375]: subprocess module update for DragonFlyBSD support.

bpo-42384 [https://bugs.python.org/issue?@action=redirect&bpo=42384]: Make pdb populate sys.path[0] exactly the same as regular python execution.

bpo-42383 [https://bugs.python.org/issue?@action=redirect&bpo=42383]: Fix pdb: previously pdb would fail to restart the debugging target if it was specified using a relative path and the current directory changed.

bpo-42318 [https://bugs.python.org/issue?@action=redirect&bpo=42318]: Fixed support of non-BMP characters in tkinter on macOS.

bpo-42163 [https://bugs.python.org/issue?@action=redirect&bpo=42163]: Restore compatibility for uname_result around deepcopy and _replace.

bpo-39825 [https://bugs.python.org/issue?@action=redirect&bpo=39825]: Windows: Change sysconfig.get_config_var('EXT_SUFFIX') to the expected full platform_tag.extension format. Previously it was hard-coded to .pyd, now it is compatible with distutils.sysconfig and will result in something like .cp38-win_amd64.pyd. This brings windows into conformance with the other platforms.

bpo-42059 [https://bugs.python.org/issue?@action=redirect&bpo=42059]: typing.TypedDict types created using the alternative call-style syntax now correctly respect the total keyword argument when setting their __required_keys__ and __optional_keys__ class attributes.

bpo-39101 [https://bugs.python.org/issue?@action=redirect&bpo=39101]: Fixed tests using IsolatedAsyncioTestCase from hanging on BaseExceptions.

bpo-42005 [https://bugs.python.org/issue?@action=redirect&bpo=42005]: Fix CLI of cProfile and profile to catch BrokenPipeError.

bpo-41907 [https://bugs.python.org/issue?@action=redirect&bpo=41907]: fix format() behavior for IntFlag

bpo-41889 [https://bugs.python.org/issue?@action=redirect&bpo=41889]: Enum: fix regression involving inheriting a multiply-inherited enum

bpo-41891 [https://bugs.python.org/issue?@action=redirect&bpo=41891]: Ensure asyncio.wait_for waits for task completion

bpo-41604 [https://bugs.python.org/issue?@action=redirect&bpo=41604]: Don’t decrement the reference count of the previous user_ptr when set_panel_userptr fails.

bpo-40219 [https://bugs.python.org/issue?@action=redirect&bpo=40219]: Lowered tkinter.ttk.LabeledScale dummy widget to prevent hiding part of the content label.

bpo-40084 [https://bugs.python.org/issue?@action=redirect&bpo=40084]: Fix Enum.__dir__: dir(Enum.member) now includes attributes as well as methods.

bpo-39068 [https://bugs.python.org/issue?@action=redirect&bpo=39068]: Fix initialization race condition in a85encode() and b85encode() in base64. Patch by Brandon Stansbury.

bpo-33289 [https://bugs.python.org/issue?@action=redirect&bpo=33289]: Correct call to tkinter.colorchooser to return RGB triplet of ints instead of floats. Patch by Cheryl Sabella.

Documentation

bpo-40304 [https://bugs.python.org/issue?@action=redirect&bpo=40304]: Fix doc for type(name, bases, dict). Patch by Boris Verkhovskiy and Éric Araujo.

bpo-42811 [https://bugs.python.org/issue?@action=redirect&bpo=42811]: Updated importlib.utils.resolve_name() doc to use __spec__.parent instead of __package__. (Thanks Yair Frid.)

bpo-17140 [https://bugs.python.org/issue?@action=redirect&bpo=17140]: Add documentation for the multiprocessing.pool.ThreadPool class.

Tests

bpo-42794 [https://bugs.python.org/issue?@action=redirect&bpo=42794]: Update test_nntplib to use offical group name of news.aioe.org for testing. Patch by Dong-hee Na.

bpo-40810 [https://bugs.python.org/issue?@action=redirect&bpo=40810]: In sqlite3, fix CheckTraceCallbackContent for SQLite pre 3.7.15.

Build

bpo-43174 [https://bugs.python.org/issue?@action=redirect&bpo=43174]: Windows build now uses /utf-8 compiler option.

bpo-42692 [https://bugs.python.org/issue?@action=redirect&bpo=42692]: Fix __builtin_available check on older compilers. Patch by Joshua Root.

bpo-42604 [https://bugs.python.org/issue?@action=redirect&bpo=42604]: Now all platforms use a value for the «EXT_SUFFIX» build variable derived from SOABI (for instance in freeBSD, «EXT_SUFFIX» is now «.cpython-310d.so» instead of «.so»). Previosuly only Linux, Mac and VxWorks were using a value for «EXT_SUFFIX» that included «SOABI».

bpo-42598 [https://bugs.python.org/issue?@action=redirect&bpo=42598]: Fix implicit function declarations in configure which could have resulted in incorrect configuration checks. Patch contributed by Joshua Root.

bpo-29076 [https://bugs.python.org/issue?@action=redirect&bpo=29076]: Add fish shell support to macOS installer.

Windows

bpo-41837 [https://bugs.python.org/issue?@action=redirect&bpo=41837]: Updated Windows installer to include OpenSSL 1.1.1i

bpo-42584 [https://bugs.python.org/issue?@action=redirect&bpo=42584]: Upgrade Windows installer to use SQLite 3.34.0.

macOS

bpo-42504 [https://bugs.python.org/issue?@action=redirect&bpo=42504]: Ensure that the value of sysconfig.get_config_var(“MACOSX_DEPLOYMENT_TARGET”) is always a string, even in when the value is parsable as an integer.

bpo-42361 [https://bugs.python.org/issue?@action=redirect&bpo=42361]: Update macOS installer build to use Tcl/Tk 8.6.11 (rc2, expected to be final release).

bpo-41837 [https://bugs.python.org/issue?@action=redirect&bpo=41837]: Update macOS installer build to use OpenSSL 1.1.1i.

bpo-42584 [https://bugs.python.org/issue?@action=redirect&bpo=42584]: Update macOS installer to use SQLite 3.34.0.

IDLE

bpo-43008 [https://bugs.python.org/issue?@action=redirect&bpo=43008]: Make IDLE invoke sys.excepthook() in normal, 2-process mode. Patch by Ken Hilton.

bpo-33065 [https://bugs.python.org/issue?@action=redirect&bpo=33065]: Fix problem debugging user classes with __repr__ method.

bpo-23544 [https://bugs.python.org/issue?@action=redirect&bpo=23544]: Disable Debug=>Stack Viewer when user code is running or Debugger is active, to prevent hang or crash. Patch by Zackery Spytz.

bpo-32631 [https://bugs.python.org/issue?@action=redirect&bpo=32631]: Finish zzdummy example extension module: make menu entries work; add docstrings and tests with 100% coverage.

Tools/Demos

bpo-42726 [https://bugs.python.org/issue?@action=redirect&bpo=42726]: Fixed Python 3 compatibility issue with gdb/libpython.py handling of attribute dictionaries.

bpo-42613 [https://bugs.python.org/issue?@action=redirect&bpo=42613]: Fix freeze.py tool to use the prope config and library directories. Patch by Victor Stinner.

C API

bpo-43030 [https://bugs.python.org/issue?@action=redirect&bpo=43030]: Fixed a compiler warning in Py_UNICODE_ISSPACE() on platforms with signed wchar_t.

bpo-42591 [https://bugs.python.org/issue?@action=redirect&bpo=42591]: Export the Py_FrozenMain() function: fix a Python 3.9.0 regression. Python 3.9 uses -fvisibility=hidden and the function was not exported explicitly and so not exported.

bpo-40052 [https://bugs.python.org/issue?@action=redirect&bpo=40052]: Fix an alignment build warning/error in function PyVectorcall_Function(). Patch by Andreas Schneider, Antoine Pitrou and Petr Viktorin.

Python 3.9.1 final

Release date: 2020-12-07

Core and Builtins

bpo-42576 [https://bugs.python.org/issue?@action=redirect&bpo=42576]: types.GenericAlias will now raise a TypeError when attempting to initialize with a keyword argument. Previously, this would cause the interpreter to crash if the interpreter was compiled with debug symbols. This does not affect interpreters compiled for release. Patch by Ken Jin.

Library

bpo-5054 [https://bugs.python.org/issue?@action=redirect&bpo=5054]: CGIHTTPRequestHandler.run_cgi() HTTP_ACCEPT improperly parsed. Replace the special purpose getallmatchingheaders with generic get_all method and add relevant tests.

Original Patch by Martin Panter. Modified by Senthil Kumaran.

bpo-17735 [https://bugs.python.org/issue?@action=redirect&bpo=17735]: inspect.findsource() now raises OSError instead of IndexError when co_lineno of a code object is greater than the file length. This can happen, for example, when a file is edited after it was imported. PR by Irit Katriel.

bpo-42116 [https://bugs.python.org/issue?@action=redirect&bpo=42116]: Fix handling of trailing comments by inspect.getsource().

bpo-42487 [https://bugs.python.org/issue?@action=redirect&bpo=42487]: ChainMap.__iter__ no longer calls __getitem__ on underlying maps

bpo-42482 [https://bugs.python.org/issue?@action=redirect&bpo=42482]: TracebackException no longer holds a reference to the exception’s traceback object. Consequently, instances of TracebackException for equivalent but non-equal exceptions now compare as equal.

bpo-42406 [https://bugs.python.org/issue?@action=redirect&bpo=42406]: We fixed an issue in pickle.whichmodule in which importing multiprocessing could change the how pickle identifies which module an object belongs to, potentially breaking the unpickling of those objects.

bpo-34215 [https://bugs.python.org/issue?@action=redirect&bpo=34215]: Clarify the error message for asyncio.IncompleteReadError when expected is None.

bpo-12800 [https://bugs.python.org/issue?@action=redirect&bpo=12800]: Extracting a symlink from a tarball should succeed and overwrite the symlink if it already exists. The fix is to remove the existing file or symlink before extraction. Based on patch by Chris AtLee, Jeffrey Kintscher, and Senthil Kumaran.

Tests

bpo-41473 [https://bugs.python.org/issue?@action=redirect&bpo=41473]: Reenable test_gdb on gdb 9.2 and newer: https://bugzilla.redhat.com/show_bug.cgi?id=1866884 bug is fixed in gdb 10.1.

bpo-42553 [https://bugs.python.org/issue?@action=redirect&bpo=42553]: Fix test_asyncio.test_call_later() race condition: don’t measure asyncio performance in the call_later() unit test. The test failed randomly on the CI.

macOS

bpo-41116 [https://bugs.python.org/issue?@action=redirect&bpo=41116]: If no explicit macOS SDK was specified, setup.py should check for Tcl and TK frameworks in /Library/Frameworks; the previous commit inadvertently broke that test.

bpo-42504 [https://bugs.python.org/issue?@action=redirect&bpo=42504]: Fix build on macOS Big Sur when MACOSX_DEPLOYMENT_TARGET=11

IDLE

bpo-42508 [https://bugs.python.org/issue?@action=redirect&bpo=42508]: Keep IDLE running on macOS. Remove obsolete workaround that prevented running files with shortcuts when using new universal2 installers built on macOS 11.

Python 3.9.1 release candidate 1

Release date: 2020-11-24

Security

bpo-42103 [https://bugs.python.org/issue?@action=redirect&bpo=42103]: Prevented potential DoS attack via CPU and RAM exhaustion when processing malformed Apple Property List files in binary format.

bpo-42051 [https://bugs.python.org/issue?@action=redirect&bpo=42051]: The plistlib module no longer accepts entity declarations in XML plist files to avoid XML vulnerabilities. This should not affect users as entity declarations are not used in regular plist files.

bpo-40791 [https://bugs.python.org/issue?@action=redirect&bpo=40791]: Add volatile to the accumulator variable in hmac.compare_digest, making constant-time-defeating optimizations less likely.

Core and Builtins

bpo-41686 [https://bugs.python.org/issue?@action=redirect&bpo=41686]: On Windows, the SIGINT event, _PyOS_SigintEvent(), is now created even if Python is configured to not install signal handlers (if PyConfig.install_signal_handlers equals to 0, or Py_InitializeEx(0)).

bpo-42381 [https://bugs.python.org/issue?@action=redirect&bpo=42381]: Allow assignment expressions in set literals and set comprehensions as per PEP 572. Patch by Pablo Galindo.

bpo-42374 [https://bugs.python.org/issue?@action=redirect&bpo=42374]: Fix a regression introduced by the new parser, where an unparenthesized walrus operator was not allowed within generator expressions.

bpo-42296 [https://bugs.python.org/issue?@action=redirect&bpo=42296]: On Windows, fix a regression in signal handling which prevented to interrupt a program using CTRL+C. The signal handler can be run in a thread different than the Python thread, in which case the test deciding if the thread can handle signals is wrong.

bpo-42332 [https://bugs.python.org/issue?@action=redirect&bpo=42332]: types.GenericAlias objects can now be the targets of weakrefs.

bpo-42218 [https://bugs.python.org/issue?@action=redirect&bpo=42218]: Fixed a bug in the PEG parser that was causing crashes in debug mode. Now errors are checked in left-recursive rules to avoid cases where such errors do not get handled in time and appear as long-distance crashes in other places.

bpo-42214 [https://bugs.python.org/issue?@action=redirect&bpo=42214]: Fixed a possible crash in the PEG parser when checking for the “!=” token in the barry_as_flufl rule. Patch by Pablo Galindo.

bpo-42143 [https://bugs.python.org/issue?@action=redirect&bpo=42143]: Fix handling of errors during creation of PyFunctionObject, which resulted in operations on uninitialized memory. Patch by Yonatan Goldschmidt.

bpo-41659 [https://bugs.python.org/issue?@action=redirect&bpo=41659]: Fix a bug in the parser, where a curly brace following a primary didn’t fail immediately. This led to invalid expressions like a {b} to throw a SyntaxError with a wrong offset, or invalid expressions ending with a curly brace like a { to not fail immediately in the REPL.

bpo-42150 [https://bugs.python.org/issue?@action=redirect&bpo=42150]: Fix possible buffer overflow in the new parser when checking for continuation lines. Patch by Pablo Galindo.

bpo-42123 [https://bugs.python.org/issue?@action=redirect&bpo=42123]: Run the parser two times. On the first run, disable all the rules that only generate better error messages to gain performance. If there’s a parse failure, run the parser a second time with those enabled.

bpo-42057 [https://bugs.python.org/issue?@action=redirect&bpo=42057]: Fix peephole optimizer misoptimize conditional jump + JUMP_IF_NOT_EXC_MATCH pair.

bpo-41984 [https://bugs.python.org/issue?@action=redirect&bpo=41984]: The garbage collector now tracks all user-defined classes. Patch by Brandt Bucher.

bpo-41993 [https://bugs.python.org/issue?@action=redirect&bpo=41993]: Fixed potential issues with removing not completely initialized module from sys.modules when import fails.

bpo-41979 [https://bugs.python.org/issue?@action=redirect&bpo=41979]: Star-unpacking is now allowed for with item’s targets in the PEG parser.

bpo-41909 [https://bugs.python.org/issue?@action=redirect&bpo=41909]: Fixed stack overflow in issubclass() and isinstance() when getting the __bases__ attribute leads to infinite recursion.

bpo-41894 [https://bugs.python.org/issue?@action=redirect&bpo=41894]: When loading a native module and a load failure occurs, prevent a possible UnicodeDecodeError when not running in a UTF-8 locale by decoding the load error message using the current locale’s encoding.

bpo-39934 [https://bugs.python.org/issue?@action=redirect&bpo=39934]: Correctly count control blocks in “except” in compiler. Ensures that a syntax error, rather a fatal error, occurs for deeply nested, named exception handlers.

Library

bpo-42328 [https://bugs.python.org/issue?@action=redirect&bpo=42328]: Fixed tkinter.ttk.Style.map(). The function accepts now the representation of the default state as empty sequence (as returned by Style.map()). The structure of the result is now the same on all platform and does not depend on the value of wantobjects.

bpo-42345 [https://bugs.python.org/issue?@action=redirect&bpo=42345]: Fix various issues with typing.Literal parameter handling (flatten, deduplicate, use type to cache key). Patch provided by Yurii Karabas.

bpo-42350 [https://bugs.python.org/issue?@action=redirect&bpo=42350]: Fix the threading.Thread class at fork: do nothing if the thread is already stopped (ex: fork called at Python exit). Previously, an error was logged in the child process.

bpo-42014 [https://bugs.python.org/issue?@action=redirect&bpo=42014]: The onerror callback from shutil.rmtree now receives correct function when os.open fails.

bpo-42237 [https://bugs.python.org/issue?@action=redirect&bpo=42237]: Fix os.sendfile() on illumos.

bpo-42249 [https://bugs.python.org/issue?@action=redirect&bpo=42249]: Fixed writing binary Plist files larger than 4 GiB.

bpo-35455 [https://bugs.python.org/issue?@action=redirect&bpo=35455]: On Solaris, thread_time() is now implemented with gethrvtime() because clock_gettime(CLOCK_THREAD_CPUTIME_ID) is not always available. Patch by Jakub Kulik.

bpo-42233 [https://bugs.python.org/issue?@action=redirect&bpo=42233]: The repr() of typing types containing Generic Alias Types previously did not show the parameterized types in the GenericAlias. They have now been changed to do so.

bpo-41754 [https://bugs.python.org/issue?@action=redirect&bpo=41754]: webbrowser: Ignore NotADirectoryError when calling xdg-settings.

bpo-29566 [https://bugs.python.org/issue?@action=redirect&bpo=29566]: binhex.binhex() consistently writes macOS 9 line endings.

bpo-42183 [https://bugs.python.org/issue?@action=redirect&bpo=42183]: Fix a stack overflow error for asyncio Task or Future repr().

The overflow occurs under some circumstances when a Task or Future recursively returns itself.

bpo-42146 [https://bugs.python.org/issue?@action=redirect&bpo=42146]: Fix memory leak in subprocess.Popen() in case an uid (gid) specified in user (group, extra_groups) overflows uid_t (gid_t).

bpo-42140 [https://bugs.python.org/issue?@action=redirect&bpo=42140]: Improve asyncio.wait function to create the futures set just one time.

bpo-42103 [https://bugs.python.org/issue?@action=redirect&bpo=42103]: InvalidFileException and RecursionError are now the only errors caused by loading malformed binary Plist file (previously ValueError and TypeError could be raised in some specific cases).

bpo-41052 [https://bugs.python.org/issue?@action=redirect&bpo=41052]: Pickling heap types implemented in C with protocols 0 and 1 raises now an error instead of producing incorrect data.

bpo-41491 [https://bugs.python.org/issue?@action=redirect&bpo=41491]: plistlib: fix parsing XML plists with hexadecimal integer values

bpo-42065 [https://bugs.python.org/issue?@action=redirect&bpo=42065]: Fix an incorrectly formatted error from _codecs.charmap_decode() when called with a mapped value outside the range of valid Unicode code points. PR by Max Bernstein.

bpo-41966 [https://bugs.python.org/issue?@action=redirect&bpo=41966]: Fix pickling pure Python datetime.time subclasses. Patch by Dean Inwood.

bpo-41976 [https://bugs.python.org/issue?@action=redirect&bpo=41976]: Fixed a bug that was causing ctypes.util.find_library() to return None when triying to locate a library in an environment when gcc>=9 is available and ldconfig is not. Patch by Pablo Galindo

bpo-41900 [https://bugs.python.org/issue?@action=redirect&bpo=41900]: C14N 2.0 serialisation in xml.etree.ElementTree failed for unprefixed attributes when a default namespace was defined.

bpo-41840 [https://bugs.python.org/issue?@action=redirect&bpo=41840]: Fix a bug in the symtable module that was causing module-scope global variables to not be reported as both local and global. Patch by Pablo Galindo.

bpo-41831 [https://bugs.python.org/issue?@action=redirect&bpo=41831]: str() for the type attribute of the tkinter.Event object always returns now the numeric code returned by Tk instead of the name of the event type.

bpo-41817 [https://bugs.python.org/issue?@action=redirect&bpo=41817]: fix tkinter.EventType Enum so all members are strings, and none are tuples

bpo-41815 [https://bugs.python.org/issue?@action=redirect&bpo=41815]: Fix SQLite3 segfault when backing up closed database. Patch contributed by Peter David McCormick.

bpo-41316 [https://bugs.python.org/issue?@action=redirect&bpo=41316]: Fix the tarfile module to write only basename of TAR file to GZIP compression header.

bpo-16396 [https://bugs.python.org/issue?@action=redirect&bpo=16396]: Allow ctypes.wintypes to be imported on non-Windows systems.

bpo-40592 [https://bugs.python.org/issue?@action=redirect&bpo=40592]: shutil.which() now ignores empty entries in PATHEXT instead of treating them as a match.

bpo-40550 [https://bugs.python.org/issue?@action=redirect&bpo=40550]: Fix time-of-check/time-of-action issue in subprocess.Popen.send_signal.

bpo-40492 [https://bugs.python.org/issue?@action=redirect&bpo=40492]: Fix --outfile for cProfile / profile not writing the output file in the original directory when the program being profiled changes the working directory. PR by Anthony Sottile.

bpo-40105 [https://bugs.python.org/issue?@action=redirect&bpo=40105]: ZipFile truncates files to avoid corruption when a shorter comment is provided in append («a») mode. Patch by Jan Mazur.

bpo-27321 [https://bugs.python.org/issue?@action=redirect&bpo=27321]: Fixed KeyError exception when flattening an email to a string attempts to replace a non-existent Content-Transfer-Encoding header.

Documentation

bpo-42153 [https://bugs.python.org/issue?@action=redirect&bpo=42153]: Fix the URL for the IMAP protocol documents.

bpo-42061 [https://bugs.python.org/issue?@action=redirect&bpo=42061]: Document __format__ functionality for IP addresses.

bpo-41910 [https://bugs.python.org/issue?@action=redirect&bpo=41910]: Document the default implementation of object.__eq__.

bpo-42010 [https://bugs.python.org/issue?@action=redirect&bpo=42010]: Clarify that subscription expressions are also valid for certain classes and types in the standard library, and for user-defined classes and types if the classmethod __class_getitem__() is provided.

bpo-41805 [https://bugs.python.org/issue?@action=redirect&bpo=41805]: Documented generic alias type and types.GenericAlias. Also added an entry in glossary for generic types.

bpo-41774 [https://bugs.python.org/issue?@action=redirect&bpo=41774]: In Programming FAQ «Sequences (Tuples/Lists)» section, add «How do you remove multiple items from a list».

bpo-35293 [https://bugs.python.org/issue?@action=redirect&bpo=35293]: Fix RemovedInSphinx40Warning when building the documentation. Patch by Dong-hee Na.

bpo-41726 [https://bugs.python.org/issue?@action=redirect&bpo=41726]: Update the refcounts info of PyType_FromModuleAndSpec.

bpo-39693 [https://bugs.python.org/issue?@action=redirect&bpo=39693]: Fix tarfile’s extractfile documentation

bpo-39416 [https://bugs.python.org/issue?@action=redirect&bpo=39416]: Document some restrictions on the default string representations of numeric classes.

Tests

bpo-40754 [https://bugs.python.org/issue?@action=redirect&bpo=40754]: Include _testinternalcapi module in Windows installer for test suite

bpo-41739 [https://bugs.python.org/issue?@action=redirect&bpo=41739]: Fix test_logging.test_race_between_set_target_and_flush(): the test now waits until all threads complete to avoid leaking running threads.

bpo-41970 [https://bugs.python.org/issue?@action=redirect&bpo=41970]: Avoid a test failure in test_lib2to3 if the module has already imported at the time the test executes. Patch by Pablo Galindo.

bpo-41944 [https://bugs.python.org/issue?@action=redirect&bpo=41944]: Tests for CJK codecs no longer call eval() on content received via HTTP.

bpo-41939 [https://bugs.python.org/issue?@action=redirect&bpo=41939]: Fix test_site.test_license_exists_at_url(): call urllib.request.urlcleanup() to reset the global urllib.request._opener. Patch by Victor Stinner.

bpo-41561 [https://bugs.python.org/issue?@action=redirect&bpo=41561]: test_ssl: skip test_min_max_version_mismatch when TLS 1.0 is not available

bpo-41602 [https://bugs.python.org/issue?@action=redirect&bpo=41602]: Add tests for SIGINT handling in the runpy module.

bpo-41306 [https://bugs.python.org/issue?@action=redirect&bpo=41306]: Fixed a failure in test_tk.test_widgets.ScaleTest happening when executing the test with Tk 8.6.10.

Build

bpo-42398 [https://bugs.python.org/issue?@action=redirect&bpo=42398]: Fix a race condition in «make regen-all» when make -jN option is used to run jobs in parallel. The clinic.py script now only use atomic write to write files. Moveover, generated files are now left unchanged if the content does not change, to not change the file modification time.

bpo-41617 [https://bugs.python.org/issue?@action=redirect&bpo=41617]: Fix building pycore_bitutils.h internal header on old clang version without __builtin_bswap16() (ex: Xcode 4.6.3 on Mac OS X 10.7). Patch by Joshua Root and Victor Stinner.

bpo-38249 [https://bugs.python.org/issue?@action=redirect&bpo=38249]: Update Py_UNREACHABLE to use __builtin_unreachable() if only the compiler is able to use it. Patch by Dong-hee Na.

bpo-40998 [https://bugs.python.org/issue?@action=redirect&bpo=40998]: Addressed three compiler warnings found by undefined behavior sanitizer (ubsan).

Windows

bpo-42120 [https://bugs.python.org/issue?@action=redirect&bpo=42120]: Remove macro definition of copysign (to _copysign) in headers.

bpo-38439 [https://bugs.python.org/issue?@action=redirect&bpo=38439]: Updates the icons for IDLE in the Windows Store package.

bpo-41744 [https://bugs.python.org/issue?@action=redirect&bpo=41744]: Fixes automatic import of props file when using the Nuget package.

bpo-41557 [https://bugs.python.org/issue?@action=redirect&bpo=41557]: Update Windows installer to use SQLite 3.33.0.

bpo-38324 [https://bugs.python.org/issue?@action=redirect&bpo=38324]: Avoid Unicode errors when accessing certain locale data on Windows.

macOS

bpo-41116 [https://bugs.python.org/issue?@action=redirect&bpo=41116]: Ensure distutils.unixxcompiler.find_library_file can find system provided libraries on macOS 11.

bpo-41100 [https://bugs.python.org/issue?@action=redirect&bpo=41100]: Add support for macOS 11 and Apple Silicon systems.

It is now possible to build «Universal 2» binaries using «–enable-universalsdk –with-universal-archs=universal2».

Binaries build on later macOS versions can be deployed back to older versions (tested up to macOS 10.9), when using the correct deployment target. This is tested using Xcode 11 and later.

bpo-38443 [https://bugs.python.org/issue?@action=redirect&bpo=38443]: The --enable-universalsdk and --with-universal-archs options for the configure script now check that the specified architectures can be used.

bpo-41471 [https://bugs.python.org/issue?@action=redirect&bpo=41471]: Ignore invalid prefix lengths in system proxy excludes.

bpo-41557 [https://bugs.python.org/issue?@action=redirect&bpo=41557]: Update macOS installer to use SQLite 3.33.0.

IDLE

bpo-42426 [https://bugs.python.org/issue?@action=redirect&bpo=42426]: Fix reporting offset of the RE error in searchengine.

bpo-42415 [https://bugs.python.org/issue?@action=redirect&bpo=42415]: Get docstrings for IDLE calltips more often by using inspect.getdoc.

bpo-33987 [https://bugs.python.org/issue?@action=redirect&bpo=33987]: Mostly finish using ttk widgets, mainly for editor, settings, and searches. Some patches by Mark Roseman.

bpo-41775 [https://bugs.python.org/issue?@action=redirect&bpo=41775]: Use “IDLE Shell” as shell title

bpo-35764 [https://bugs.python.org/issue?@action=redirect&bpo=35764]: Rewrite the Calltips doc section.

bpo-40181 [https://bugs.python.org/issue?@action=redirect&bpo=40181]: In calltips, stop reminding that “/” marks the end of positional-only arguments.

bpo-40511 [https://bugs.python.org/issue?@action=redirect&bpo=40511]: Typing opening and closing parentheses inside the parentheses of a function call will no longer cause unnecessary «flashing» off and on of an existing open call-tip, e.g. when typed in a string literal.

bpo-38439 [https://bugs.python.org/issue?@action=redirect&bpo=38439]: Add a 256×256 pixel IDLE icon to the Windows .ico file. Created by Andrew Clover. Remove the low-color gif variations from the .ico file.

C API

bpo-42015 [https://bugs.python.org/issue?@action=redirect&bpo=42015]: Fix potential crash in deallocating method objects when dynamically allocated PyMethodDef’s lifetime is managed through the self argument of a PyCFunction.

bpo-41986 [https://bugs.python.org/issue?@action=redirect&bpo=41986]: Py_FileSystemDefaultEncodeErrors and Py_UTF8Mode are available again in limited API.

Python 3.9.0 final

Release date: 2020-10-04

Library

bpo-41815 [https://bugs.python.org/issue?@action=redirect&bpo=41815]: Fix SQLite3 segfault when backing up closed database. Patch contributed by Peter David McCormick.

bpo-41662 [https://bugs.python.org/issue?@action=redirect&bpo=41662]: No longer override exceptions raised in __len__() of a sequence of parameters in sqlite3 with ProgrammingError.

bpo-41662 [https://bugs.python.org/issue?@action=redirect&bpo=41662]: Fixed crash when mutate list of parameters during iteration in sqlite3.

bpo-39728 [https://bugs.python.org/issue?@action=redirect&bpo=39728]: fix default _missing_ so a duplicate ValueError is not set as the __context__ of the original ValueError

Tests

bpo-41602 [https://bugs.python.org/issue?@action=redirect&bpo=41602]: Add tests for SIGINT handling in the runpy module.

Build

bpo-38249 [https://bugs.python.org/issue?@action=redirect&bpo=38249]: Update Py_UNREACHABLE to use __builtin_unreachable() if only the compiler is able to use it. Patch by Dong-hee Na.

Python 3.9.0 release candidate 2

Release date: 2020-09-16

Core and Builtins

bpo-41780 [https://bugs.python.org/issue?@action=redirect&bpo=41780]: Fix __dir__() of types.GenericAlias. Patch by Batuhan Taskaya.

bpo-41690 [https://bugs.python.org/issue?@action=redirect&bpo=41690]: Fix a possible stack overflow in the parser when parsing functions and classes with a huge ammount of arguments. Patch by Pablo Galindo.

bpo-41681 [https://bugs.python.org/issue?@action=redirect&bpo=41681]: Fixes the wrong error description in the error raised by using 2 , in format string in f-string and str.format().

bpo-41654 [https://bugs.python.org/issue?@action=redirect&bpo=41654]: Fix a crash that occurred when destroying subclasses of MemoryError. Patch by Pablo Galindo.

bpo-41631 [https://bugs.python.org/issue?@action=redirect&bpo=41631]: The _ast module uses again a global state. Using a module state per module instance is causing subtle practical problems. For example, the Mercurial project replaces the __import__() function to implement lazy import, whereas Python expected that import _ast always return a fully initialized _ast module.

bpo-41533 [https://bugs.python.org/issue?@action=redirect&bpo=41533]: Free the stack allocated in va_build_stack if do_mkstack fails and the stack is not a small_stack.

bpo-41531 [https://bugs.python.org/issue?@action=redirect&bpo=41531]: Fix a bug that was dropping keys when compiling dict literals with more than 0xFFFF elements. Patch by Pablo Galindo.

bpo-41525 [https://bugs.python.org/issue?@action=redirect&bpo=41525]: The output of python --help contains now only ASCII characters.

bpo-29590 [https://bugs.python.org/issue?@action=redirect&bpo=29590]: Make the stack trace correct after calling generator.throw() on a generator that has yielded from a yield from.

Library

bpo-41517 [https://bugs.python.org/issue?@action=redirect&bpo=41517]: fix bug allowing Enums to be extended via multiple inheritance

bpo-39587 [https://bugs.python.org/issue?@action=redirect&bpo=39587]: use the correct mix-in data type when constructing Enums

bpo-41789 [https://bugs.python.org/issue?@action=redirect&bpo=41789]: Honor object overrides in Enum class creation (specifically, __str__, __repr__, __format__, and __reduce_ex__).

bpo-39651 [https://bugs.python.org/issue?@action=redirect&bpo=39651]: Fix a race condition in the call_soon_threadsafe() method of asyncio.ProactorEventLoop: do nothing if the self-pipe socket has been closed.

bpo-41720 [https://bugs.python.org/issue?@action=redirect&bpo=41720]: Fixed turtle.Vec2D.__rmul__() for arguments which are not int or float.

bpo-41696 [https://bugs.python.org/issue?@action=redirect&bpo=41696]: Fix handling of debug mode in asyncio.run(). This allows setting PYTHONASYNCIODEBUG or -X dev to enable asyncio debug mode when using asyncio.run().

bpo-41687 [https://bugs.python.org/issue?@action=redirect&bpo=41687]: Fix implementation of sendfile to be compatible with Solaris.

bpo-39010 [https://bugs.python.org/issue?@action=redirect&bpo=39010]: Restarting a ProactorEventLoop on Windows no longer logs spurious ConnectionResetErrors.

bpo-41609 [https://bugs.python.org/issue?@action=redirect&bpo=41609]: The pdb whatis command correctly reports instance methods as “Method” rather than “Function”.

bpo-32751 [https://bugs.python.org/issue?@action=redirect&bpo=32751]: When cancelling the task due to a timeout, asyncio.wait_for() will now wait until the cancellation is complete also in the case when timeout is <= 0, like it does with positive timeouts.

bpo-37658 [https://bugs.python.org/issue?@action=redirect&bpo=37658]: asyncio.wait_for() now properly handles races between cancellation of itself and the completion of the wrapped awaitable.

bpo-40782 [https://bugs.python.org/issue?@action=redirect&bpo=40782]: Change the method asyncio.AbstractEventLoop.run_in_executor to not be a coroutine.

bpo-41520 [https://bugs.python.org/issue?@action=redirect&bpo=41520]: Fix codeop regression that prevented turning compile warnings into errors.

bpo-41503 [https://bugs.python.org/issue?@action=redirect&bpo=41503]: Fixed a race between setTarget and flush in logging.handlers.MemoryHandler.

bpo-41344 [https://bugs.python.org/issue?@action=redirect&bpo=41344]: Prevent creating shared_memory.SharedMemory objects with size=0.

bpo-41025 [https://bugs.python.org/issue?@action=redirect&bpo=41025]: Fixed an issue preventing the C implementation of zoneinfo.ZoneInfo from being subclassed.

bpo-31122 [https://bugs.python.org/issue?@action=redirect&bpo=31122]: ssl.wrap_socket() now raises ssl.SSLEOFError rather than OSError when peer closes connection during TLS negotiation

bpo-33660 [https://bugs.python.org/issue?@action=redirect&bpo=33660]: Fix pathlib.PosixPath to resolve a relative path located on the root directory properly.

Documentation

bpo-37149 [https://bugs.python.org/issue?@action=redirect&bpo=37149]: Change Shipman tkinter doc link from archive.org to TkDocs. (The doc has been removed from the NMT server.) The new link responds much faster and includes a short explanatory note.

bpo-41624 [https://bugs.python.org/issue?@action=redirect&bpo=41624]: Fix the signature of typing.Coroutine.

bpo-40204 [https://bugs.python.org/issue?@action=redirect&bpo=40204]: Enable Sphinx 3.2 c_allow_pre_v3 option and disable c_warn_on_allowed_pre_v3 option to make the documentation compatible with Sphinx 2 and Sphinx 3.

bpo-40979 [https://bugs.python.org/issue?@action=redirect&bpo=40979]: Refactored typing.rst, arranging more than 70 classes, functions, and decorators into new sub-sections.

bpo-39883 [https://bugs.python.org/issue?@action=redirect&bpo=39883]: Make code, examples, and recipes in the Python documentation be licensed under the more permissive BSD0 license in addition to the existing Python 2.0 license.

Tests

bpo-41731 [https://bugs.python.org/issue?@action=redirect&bpo=41731]: Make test_cmd_line_script pass with option “-vv”.

Build

bpo-41617 [https://bugs.python.org/issue?@action=redirect&bpo=41617]: Fix pycore_byteswap.h header file to support old clang versions: __builtin_bswap16() is not available in LLVM clang 3.0.

Windows

bpo-41526 [https://bugs.python.org/issue?@action=redirect&bpo=41526]: Fixed layout of final page of the installer by removing the special thanks to Mark Hammond (with his permission).

C API

bpo-41524 [https://bugs.python.org/issue?@action=redirect&bpo=41524]: Fix bug in PyOS_mystrnicmp and PyOS_mystricmp that incremented pointers beyond the end of a string.

Python 3.9.0 release candidate 1

Release date: 2020-08-11

Core and Builtins

bpo-38156 [https://bugs.python.org/issue?@action=redirect&bpo=38156]: Handle interrupts that come after EOF correctly in PyOS_StdioReadline.

Library

bpo-41497 [https://bugs.python.org/issue?@action=redirect&bpo=41497]: Fix potential UnicodeDecodeError in dis module.

bpo-41490 [https://bugs.python.org/issue?@action=redirect&bpo=41490]: Update ensurepip to install pip 20.2.1 and setuptools 49.2.1.

bpo-41467 [https://bugs.python.org/issue?@action=redirect&bpo=41467]: On Windows, fix asyncio recv_into() return value when the socket/pipe is closed (BrokenPipeError): return 0 rather than an empty byte string (b'').

bpo-41425 [https://bugs.python.org/issue?@action=redirect&bpo=41425]: Make tkinter doc example runnable.

bpo-41384 [https://bugs.python.org/issue?@action=redirect&bpo=41384]: Raise TclError instead of TypeError when an unknown option is passed to tkinter.OptionMenu.

bpo-38731 [https://bugs.python.org/issue?@action=redirect&bpo=38731]: Fix NameError in command-line interface of py_compile.

bpo-41317 [https://bugs.python.org/issue?@action=redirect&bpo=41317]: Use add_done_callback() in asyncio.loop.sock_accept() to unsubscribe reader early on cancellation.

bpo-41364 [https://bugs.python.org/issue?@action=redirect&bpo=41364]: Reduce import overhead of uuid.

bpo-41341 [https://bugs.python.org/issue?@action=redirect&bpo=41341]: Recursive evaluation of typing.ForwardRef in get_type_hints.

bpo-41182 [https://bugs.python.org/issue?@action=redirect&bpo=41182]: selector: use DefaultSelector based upon implementation

bpo-40726 [https://bugs.python.org/issue?@action=redirect&bpo=40726]: Handle cases where the end_lineno is None on ast.increment_lineno().

Documentation

bpo-41045 [https://bugs.python.org/issue?@action=redirect&bpo=41045]: Add documentation for debug feature of f-strings.

bpo-41314 [https://bugs.python.org/issue?@action=redirect&bpo=41314]: Changed the release when from __future__ import annotations becomes the default from 4.0 to 3.10 (following a change in PEP 563).

Windows

bpo-41492 [https://bugs.python.org/issue?@action=redirect&bpo=41492]: Fixes the description that appears in UAC prompts.

bpo-40948 [https://bugs.python.org/issue?@action=redirect&bpo=40948]: Improve post-install message to direct people to the «py» command.

bpo-41412 [https://bugs.python.org/issue?@action=redirect&bpo=41412]: The installer will now fail to install on Windows 7 and Windows 8. Further, the UCRT dependency is now always downloaded on demand.

bpo-40741 [https://bugs.python.org/issue?@action=redirect&bpo=40741]: Update Windows release to include SQLite 3.32.3.

IDLE

bpo-41468 [https://bugs.python.org/issue?@action=redirect&bpo=41468]: Improve IDLE run crash error message (which users should never see).

bpo-41373 [https://bugs.python.org/issue?@action=redirect&bpo=41373]: Save files loaded with no line ending, as when blank, or different line endings, by setting its line ending to the system default. Fix regression in 3.8.4 and 3.9.0b4.

Python 3.9.0 beta 5

Release date: 2020-07-20

Security

bpo-41304 [https://bugs.python.org/issue?@action=redirect&bpo=41304]: Fixes python3x._pth being ignored on Windows, caused by the fix for bpo-29778 [https://bugs.python.org/issue?@action=redirect&bpo=29778] (CVE-2020-15801).

bpo-41162 [https://bugs.python.org/issue?@action=redirect&bpo=41162]: Audit hooks are now cleared later during finalization to avoid missing events.

bpo-29778 [https://bugs.python.org/issue?@action=redirect&bpo=29778]: Ensure python3.dll is loaded from correct locations when Python is embedded (CVE-2020-15523).

bpo-39603 [https://bugs.python.org/issue?@action=redirect&bpo=39603]: Prevent http header injection by rejecting control characters in http.client.putrequest(…).

Core and Builtins

bpo-41295 [https://bugs.python.org/issue?@action=redirect&bpo=41295]: Resolve a regression in CPython 3.8.4 where defining «__setattr__» in a multi-inheritance setup and calling up the hierarchy chain could fail if builtins/extension types were involved in the base types.

bpo-41247 [https://bugs.python.org/issue?@action=redirect&bpo=41247]: Always cache the running loop holder when running asyncio.set_running_loop.

bpo-41252 [https://bugs.python.org/issue?@action=redirect&bpo=41252]: Fix incorrect refcounting in _ssl.c’s _servername_callback().

bpo-41215 [https://bugs.python.org/issue?@action=redirect&bpo=41215]: Use non-NULL default values in the PEG parser keyword list to overcome a bug that was preventing Python from being properly compiled when using the XLC compiler. Patch by Pablo Galindo.

bpo-41218 [https://bugs.python.org/issue?@action=redirect&bpo=41218]: Python 3.8.3 had a regression where compiling with ast.PyCF_ALLOW_TOP_LEVEL_AWAIT would aggressively mark list comprehension with CO_COROUTINE. Now only list comprehension making use of async/await will tagged as so.

bpo-41175 [https://bugs.python.org/issue?@action=redirect&bpo=41175]: Guard against a NULL pointer dereference within bytearrayobject triggered by the bytearray() + bytearray() operation.

bpo-39960 [https://bugs.python.org/issue?@action=redirect&bpo=39960]: The «hackcheck» that prevents sneaking around a type’s __setattr__() by calling the superclass method was rewritten to allow C implemented heap types.

Library

bpo-41288 [https://bugs.python.org/issue?@action=redirect&bpo=41288]: Unpickling invalid NEWOBJ_EX opcode with the C implementation raises now UnpicklingError instead of crashing.

bpo-39017 [https://bugs.python.org/issue?@action=redirect&bpo=39017]: Avoid infinite loop when reading specially crafted TAR files using the tarfile module (CVE-2019-20907).

bpo-41235 [https://bugs.python.org/issue?@action=redirect&bpo=41235]: Fix the error handling in ssl.SSLContext.load_dh_params().

bpo-41207 [https://bugs.python.org/issue?@action=redirect&bpo=41207]: In distutils.spawn, restore expectation that DistutilsExecError is raised when the command is not found.

bpo-39168 [https://bugs.python.org/issue?@action=redirect&bpo=39168]: Remove the __new__ method of typing.Generic.

bpo-41194 [https://bugs.python.org/issue?@action=redirect&bpo=41194]: Fix a crash in the _ast module: it can no longer be loaded more than once. It now uses a global state rather than a module state.

bpo-39384 [https://bugs.python.org/issue?@action=redirect&bpo=39384]: Fixed email.contentmanager to allow set_content() to set a null string.

Documentation

bpo-37703 [https://bugs.python.org/issue?@action=redirect&bpo=37703]: Updated Documentation to comprehensively elaborate on the behaviour of gather.cancel()

macOS

bpo-40741 [https://bugs.python.org/issue?@action=redirect&bpo=40741]: Update macOS installer to use SQLite 3.32.3.

IDLE

bpo-41300 [https://bugs.python.org/issue?@action=redirect&bpo=41300]: Save files with non-ascii chars. Fix regression released in 3.9.0b4 and 3.8.4.

bpo-37765 [https://bugs.python.org/issue?@action=redirect&bpo=37765]: Add keywords to module name completion list. Rewrite Completions section of IDLE doc.

C API

bpo-40170 [https://bugs.python.org/issue?@action=redirect&bpo=40170]: Revert PyType_HasFeature() change: it reads again directly the PyTypeObject.tp_flags member when the limited C API is not used, rather than always calling PyType_GetFlags() which hides implementation details.

Python 3.9.0 beta 4

Release date: 2020-07-02

Security

bpo-41004 [https://bugs.python.org/issue?@action=redirect&bpo=41004]: The __hash__() methods of ipaddress.IPv4Interface and ipaddress.IPv6Interface incorrectly generated constant hash values of 32 and 128 respectively. This resulted in always causing hash collisions. The fix uses hash() to generate hash values for the tuple of (address, mask length, network address).

Core and Builtins

bpo-41094 [https://bugs.python.org/issue?@action=redirect&bpo=41094]: Fix decoding errors with audit when open files with non-ASCII names on non-UTF-8 locale.

bpo-41084 [https://bugs.python.org/issue?@action=redirect&bpo=41084]: Prefix the error message with “f-string: “, when parsing an f-string expression which throws a SyntaxError.

bpo-41076 [https://bugs.python.org/issue?@action=redirect&bpo=41076]: Pre-feed the parser with the location of the f-string expression, not the f-string itself, which allows us to skip the shifting of the AST node locations after the parsing is completed.

bpo-40939 [https://bugs.python.org/issue?@action=redirect&bpo=40939]: Deprecate PyNode_Compile().

bpo-41056 [https://bugs.python.org/issue?@action=redirect&bpo=41056]: Fixes a reference to deallocated stack space during startup when constructing sys.path involving a relative symlink when code was supplied via -c. (discovered via Coverity)

bpo-41061 [https://bugs.python.org/issue?@action=redirect&bpo=41061]: Fix incorrect expressions and asserts in hashtable code and tests.

bpo-41052 [https://bugs.python.org/issue?@action=redirect&bpo=41052]: Opt out serialization/deserialization for _random.Random

bpo-40939 [https://bugs.python.org/issue?@action=redirect&bpo=40939]: Deprecate PyParser_SimpleParseStringFlags(), PyParser_SimpleParseStringFlagsFilename() and PyParser_SimpleParseFileFlags().

bpo-35975 [https://bugs.python.org/issue?@action=redirect&bpo=35975]: Stefan Behnel reported that cf_feature_version is used even when PyCF_ONLY_AST is not set. This is against the intention and against the documented behavior, so it’s been fixed.

bpo-40985 [https://bugs.python.org/issue?@action=redirect&bpo=40985]: Fix a bug that caused the SyntaxError text to be empty when a file ends with a line ending in a line continuation character (i.e. backslash). The error text should contain the text of the last line.

bpo-40958 [https://bugs.python.org/issue?@action=redirect&bpo=40958]: Fix a possible buffer overflow in the PEG parser when gathering information for emitting syntax errors. Patch by Pablo Galindo.

bpo-40957 [https://bugs.python.org/issue?@action=redirect&bpo=40957]: Fix refleak in _Py_fopen_obj() when PySys_Audit() fails

bpo-40947 [https://bugs.python.org/issue?@action=redirect&bpo=40947]: The Python Path Configuration now takes PyConfig.platlibdir in account.

bpo-40847 [https://bugs.python.org/issue?@action=redirect&bpo=40847]: Fix a bug where a line with only a line continuation character is not considered a blank line at tokenizer level. In such cases, more than a single NEWLINE token was emitted. The old parser was working around the issue, but the new parser threw a SyntaxError for valid input due to this. For example, an empty line following a line continuation character was interpreted as a SyntaxError.

bpo-40824 [https://bugs.python.org/issue?@action=redirect&bpo=40824]: Unexpected errors in calling the __iter__ method are no longer masked by TypeError in the in operator and functions contains(), indexOf() and countOf() of the operator module.

bpo-19569 [https://bugs.python.org/issue?@action=redirect&bpo=19569]: Add the private macros _Py_COMP_DIAG_PUSH, _Py_COMP_DIAG_IGNORE_DEPR_DECLS, and _Py_COMP_DIAG_POP.

Library

bpo-41193 [https://bugs.python.org/issue?@action=redirect&bpo=41193]: The write_history() atexit function of the readline completer now ignores any OSError to ignore error if the filesystem is read-only, instead of only ignoring FileNotFoundError and PermissionError.

bpo-41161 [https://bugs.python.org/issue?@action=redirect&bpo=41161]: The decimal module now requires libmpdec-2.5.0. Users of –with-system-libmpdec should update their system library.

bpo-40874 [https://bugs.python.org/issue?@action=redirect&bpo=40874]: The decimal module now requires libmpdec-2.5.0.

bpo-41138 [https://bugs.python.org/issue?@action=redirect&bpo=41138]: Fixed the trace module CLI for Python source files with non-UTF-8 encoding.

bpo-31938 [https://bugs.python.org/issue?@action=redirect&bpo=31938]: Fix default-value signatures of several functions in the select module - by Anthony Sottile.

bpo-41068 [https://bugs.python.org/issue?@action=redirect&bpo=41068]: Fixed reading files with non-ASCII names from ZIP archive directly after writing them.

bpo-41058 [https://bugs.python.org/issue?@action=redirect&bpo=41058]: pdb.find_function() now correctly determines the source file encoding.

bpo-41056 [https://bugs.python.org/issue?@action=redirect&bpo=41056]: Fix a NULL pointer dereference within the ssl module during a MemoryError in the keylog callback. (discovered by Coverity)

bpo-41056 [https://bugs.python.org/issue?@action=redirect&bpo=41056]: Fixed an instance where a MemoryError within the zoneinfo module might not be reported or not reported at its source. (found by Coverity)

bpo-41048 [https://bugs.python.org/issue?@action=redirect&bpo=41048]: mimetypes.read_mime_types() function reads the rule file using UTF-8 encoding, not the locale encoding. Patch by Srinivas Reddy Thatiparthy.

bpo-41043 [https://bugs.python.org/issue?@action=redirect&bpo=41043]: Fixed the use of glob() in the stdlib: literal part of the path is now always correctly escaped.

bpo-40448 [https://bugs.python.org/issue?@action=redirect&bpo=40448]: ensurepip now disables the use of pip cache when installing the bundled versions of pip and setuptools. Patch by Krzysztof Konopko.

bpo-40967 [https://bugs.python.org/issue?@action=redirect&bpo=40967]: Removed asyncio.Task.current_task() and asyncio.Task.all_tasks(). Patch contributed by Rémi Lapeyre.

bpo-40955 [https://bugs.python.org/issue?@action=redirect&bpo=40955]: Fix a minor memory leak in subprocess module when extra_groups was specified.

bpo-40855 [https://bugs.python.org/issue?@action=redirect&bpo=40855]: The standard deviation and variance functions in the statistics module were ignoring their mu and xbar arguments.

bpo-40924 [https://bugs.python.org/issue?@action=redirect&bpo=40924]: Removed support for loaders implementing .files and supplying TraversableResources.

bpo-40939 [https://bugs.python.org/issue?@action=redirect&bpo=40939]: Use the new PEG parser when generating the stdlib keyword module.

bpo-40834 [https://bugs.python.org/issue?@action=redirect&bpo=40834]: Fix truncate when sending str object with_xxsubinterpreters.channel_send.

bpo-26407 [https://bugs.python.org/issue?@action=redirect&bpo=26407]: Unexpected errors in calling the __iter__ method are no longer masked by TypeError in csv.reader(), csv.writer.writerow() and csv.writer.writerows().

bpo-38488 [https://bugs.python.org/issue?@action=redirect&bpo=38488]: Update ensurepip to install pip 20.1.1 and setuptools 47.1.0.

bpo-36543 [https://bugs.python.org/issue?@action=redirect&bpo=36543]: Restored the deprecated xml.etree.cElementTree module.

bpo-34226 [https://bugs.python.org/issue?@action=redirect&bpo=34226]: Fix cgi.parse_multipart without content_length. Patch by Roger Duran

Tests

bpo-41085 [https://bugs.python.org/issue?@action=redirect&bpo=41085]: Fix integer overflow in the array.array.index() method on 64-bit Windows for index larger than 2**31.

bpo-41069 [https://bugs.python.org/issue?@action=redirect&bpo=41069]: test.support.TESTFN and the current directory for tests when run via test.regrtest contain now non-ascii characters if possible.

bpo-38377 [https://bugs.python.org/issue?@action=redirect&bpo=38377]: On Linux, skip tests using multiprocessing if the current user cannot create a file in /dev/shm/ directory. Add the skip_if_broken_multiprocessing_synchronize() function to the test.support module.

bpo-41009 [https://bugs.python.org/issue?@action=redirect&bpo=41009]: Fix use of support.require_{linux|mac|freebsd}_version() decorators as class decorator.

bpo-41003 [https://bugs.python.org/issue?@action=redirect&bpo=41003]: Fix test_copyreg when numpy is installed: test.pickletester now saves/restores warnings filters when importing numpy, to ignore filters installed by numpy.

bpo-40964 [https://bugs.python.org/issue?@action=redirect&bpo=40964]: Disable remote imaplib tests, host cyrus.andrew.cmu.edu is blocking incoming connections.

bpo-40927 [https://bugs.python.org/issue?@action=redirect&bpo=40927]: Fix test_binhex when run twice: it now uses import_fresh_module() to ensure that it raises DeprecationWarning each time.

bpo-34401 [https://bugs.python.org/issue?@action=redirect&bpo=34401]: Make test_gdb properly run on HP-UX. Patch by Michael Osipov.

Build

bpo-40204 [https://bugs.python.org/issue?@action=redirect&bpo=40204]: Pin Sphinx version to 2.3.1 in Doc/Makefile.

Windows

bpo-41074 [https://bugs.python.org/issue?@action=redirect&bpo=41074]: Fixed support of non-ASCII names in functions msilib.OpenDatabase() and msilib.init_database() and non-ASCII SQL in method msilib.Database.OpenView().

bpo-40164 [https://bugs.python.org/issue?@action=redirect&bpo=40164]: Updates Windows OpenSSL to 1.1.1g

bpo-37556 [https://bugs.python.org/issue?@action=redirect&bpo=37556]: Extend py.exe help to mention overrides via venv, shebang, environmental variables & ini files.

macOS

bpo-39580 [https://bugs.python.org/issue?@action=redirect&bpo=39580]: Avoid opening Finder window if running installer from the command line. Patch contributed by Rick Heil.

bpo-41100 [https://bugs.python.org/issue?@action=redirect&bpo=41100]: Fix configure error when building on macOS 11. Note that the current Python release was released shortly after the first developer preview of macOS 11 (Big Sur); there are other known issues with building and running on the developer preview. Big Sur is expected to be fully supported in a future bugfix release of Python 3.8.x and with 3.9.0.

bpo-41005 [https://bugs.python.org/issue?@action=redirect&bpo=41005]: fixed an XDG settings issue not allowing macos to open browser in webbrowser.py

IDLE

bpo-41152 [https://bugs.python.org/issue?@action=redirect&bpo=41152]: The encoding of stdin, stdout and stderr in IDLE is now always UTF-8.

bpo-41144 [https://bugs.python.org/issue?@action=redirect&bpo=41144]: Make Open Module open a special module such as os.path.

C API

bpo-36346 [https://bugs.python.org/issue?@action=redirect&bpo=36346]: Mark Py_UNICODE_COPY, Py_UNICODE_FILL, PyUnicode_WSTR_LENGTH, PyUnicode_FromUnicode, PyUnicode_AsUnicode, _PyUnicode_AsUnicode, and PyUnicode_AsUnicodeAndSize as deprecated in C. Remove Py_UNICODE_MATCH which was deprecated and broken since Python 3.3.

bpo-36020 [https://bugs.python.org/issue?@action=redirect&bpo=36020]: On Windows, #include "pyerrors.h" no longer defines snprintf and vsnprintf macros.

bpo-40703 [https://bugs.python.org/issue?@action=redirect&bpo=40703]: The PyType_FromSpec*() functions no longer overwrite the type’s «__module__» attribute if it is set via «Py_tp_members» or «Py_tp_getset».

Python 3.9.0 beta 3

Release date: 2020-06-09

Library

bpo-40924 [https://bugs.python.org/issue?@action=redirect&bpo=40924]: importlib.resources: Reverted TraversableResources implementations from the built-in loaders (SourceFileLoader and ZipImporter) as it was an incompatible change introduced in 3.9.0 beta 2 causing through a chain of events for root TLS certificates to be missing.

Build

bpo-40684 [https://bugs.python.org/issue?@action=redirect&bpo=40684]: make install now uses the PLATLIBDIR variable for the destination lib-dynload/ directory when ./configure --with-platlibdir is used.

Python 3.9.0 beta 2

Release date: 2020-06-08

Core and Builtins

bpo-40904 [https://bugs.python.org/issue?@action=redirect&bpo=40904]: Fix possible segfault in the new PEG parser when parsing f-string containing yield statements with no value (f"{yield}"). Patch by Pablo Galindo

bpo-40903 [https://bugs.python.org/issue?@action=redirect&bpo=40903]: Fixed a possible segfault in the new PEG parser when producing error messages for invalid assignments of the form p=p=. Patch by Pablo Galindo

bpo-40880 [https://bugs.python.org/issue?@action=redirect&bpo=40880]: Fix invalid memory read in the new parser when checking newlines in string literals. Patch by Pablo Galindo.

bpo-40883 [https://bugs.python.org/issue?@action=redirect&bpo=40883]: Fix memory leak in when parsing f-strings in the new parser. Patch by Pablo Galindo

bpo-40870 [https://bugs.python.org/issue?@action=redirect&bpo=40870]: Raise ValueError when validating custom AST’s where the constants True, False and None are used within a ast.Name node.

bpo-40854 [https://bugs.python.org/issue?@action=redirect&bpo=40854]: Allow overriding sys.platlibdir via a new PYTHONPLATLIBDIR environment variable.

bpo-40826 [https://bugs.python.org/issue?@action=redirect&bpo=40826]: Fix GIL usage in PyOS_Readline(): lock the GIL to set an exception and pass the Python thread state when checking if there is a pending signal.

bpo-40780 [https://bugs.python.org/issue?@action=redirect&bpo=40780]: Fix a corner case where g-style string formatting of a float failed to remove trailing zeros.

bpo-38964 [https://bugs.python.org/issue?@action=redirect&bpo=38964]: When there’s a SyntaxError in the expression part of an fstring, the filename attribute of the SyntaxError gets correctly set to the name of the file the fstring resides in.

bpo-40750 [https://bugs.python.org/issue?@action=redirect&bpo=40750]: Support the «-d» debug flag in the new PEG parser. Patch by Pablo Galindo

bpo-40217 [https://bugs.python.org/issue?@action=redirect&bpo=40217]: Instances of types created with PyType_FromSpecWithBases() will no longer automatically visit their class object when traversing references in the garbage collector. The user is expected to manually visit the object’s class. Patch by Pablo Galindo.

bpo-40696 [https://bugs.python.org/issue?@action=redirect&bpo=40696]: Fix a hang that can arise after generator.throw() due to a cycle in the exception context chain.

Library

bpo-39791 [https://bugs.python.org/issue?@action=redirect&bpo=39791]: Refresh importlib.metadata from importlib_metadata 1.6.1.

bpo-40807 [https://bugs.python.org/issue?@action=redirect&bpo=40807]: Stop codeop._maybe_compile, used by code.InteractiveInterpreter (and IDLE). from from emitting each warning three times.

bpo-39791 [https://bugs.python.org/issue?@action=redirect&bpo=39791]: Built-in loaders (SourceFileLoader and ZipImporter) now supply TraversableResources implementations for ResourceReader, and the fallback function has been removed.

bpo-17005 [https://bugs.python.org/issue?@action=redirect&bpo=17005]: The topological sort functionality that was introduced initially in the functools module has been moved to a new graphlib module to better accommodate the new tools and keep the original scope of the functools module. Patch by Pablo Galindo

bpo-40777 [https://bugs.python.org/issue?@action=redirect&bpo=40777]: Initialize PyDateTime_IsoCalendarDateType.tp_base at run-time to avoid errors on some compilers.

bpo-40767 [https://bugs.python.org/issue?@action=redirect&bpo=40767]: webbrowser now properly finds the default browser in pure Wayland systems by checking the WAYLAND_DISPLAY environment variable. Patch contributed by Jérémy Attali.

bpo-40791 [https://bugs.python.org/issue?@action=redirect&bpo=40791]: hashlib.compare_digest() uses OpenSSL’s CRYPTO_memcmp() function when OpenSSL is available.

bpo-40795 [https://bugs.python.org/issue?@action=redirect&bpo=40795]: ctypes module: If ctypes fails to convert the result of a callback or if a ctypes callback function raises an exception, sys.unraisablehook is now called with an exception set. Previously, the error was logged into stderr by PyErr_Print().

bpo-30008 [https://bugs.python.org/issue?@action=redirect&bpo=30008]: Fix ssl code to be compatible with OpenSSL 1.1.x builds that use no-deprecated and --api=1.1.0.

bpo-30064 [https://bugs.python.org/issue?@action=redirect&bpo=30064]: Fix asyncio loop.sock_* race condition issue

bpo-40759 [https://bugs.python.org/issue?@action=redirect&bpo=40759]: Deprecate the symbol module.

bpo-40737 [https://bugs.python.org/issue?@action=redirect&bpo=40737]: Fix possible reference leak for sqlite3 initialization.

bpo-40698 [https://bugs.python.org/issue?@action=redirect&bpo=40698]: distutils upload creates SHA2-256 and Blake2b-256 digests. MD5 digests is skipped if platform blocks MD5.

bpo-40695 [https://bugs.python.org/issue?@action=redirect&bpo=40695]: hashlib no longer falls back to builtin hash implementations when OpenSSL provides a hash digest and the algorithm is blocked by security policy.

bpo-9216 [https://bugs.python.org/issue?@action=redirect&bpo=9216]: func:hashlib.new passed usedforsecurity to OpenSSL EVP constructor _hashlib.new(). test_hashlib and test_smtplib handle strict security policy better.

bpo-40614 [https://bugs.python.org/issue?@action=redirect&bpo=40614]: ast.parse() will not parse self documenting expressions in f-strings when passed feature_version is less than (3, 8).

bpo-40671 [https://bugs.python.org/issue?@action=redirect&bpo=40671]: Prepare _hashlib for PEP 489 [https://www.python.org/dev/peps/pep-0489] and use PyModule_AddType().

bpo-32309 [https://bugs.python.org/issue?@action=redirect&bpo=32309]: Added a new coroutine asyncio.to_thread(). It is mainly used for running IO-bound functions in a separate thread to avoid blocking the event loop, and essentially works as a high-level version of run_in_executor() that can directly take keyword arguments.

bpo-40630 [https://bugs.python.org/issue?@action=redirect&bpo=40630]: Added tracemalloc.reset_peak() to set the peak size of traced memory blocks to the current size, to measure the peak of specific pieces of code.

bpo-13097 [https://bugs.python.org/issue?@action=redirect&bpo=13097]: ctypes now raises an ArgumentError when a callback is invoked with more than 1024 arguments.

bpo-23082 [https://bugs.python.org/issue?@action=redirect&bpo=23082]: Updated the error message and docs of PurePath.relative_to() to better reflect the function behaviour.

bpo-39244 [https://bugs.python.org/issue?@action=redirect&bpo=39244]: Fixed multiprocessing.context.get_all_start_methods to properly return the default method first on macOS.

bpo-39040 [https://bugs.python.org/issue?@action=redirect&bpo=39040]: Fix parsing of invalid mime headers parameters by collapsing whitespace between encoded words in a bare-quote-string.

bpo-35714 [https://bugs.python.org/issue?@action=redirect&bpo=35714]: struct.error is now raised if there is a null character in a struct format string.

bpo-36290 [https://bugs.python.org/issue?@action=redirect&bpo=36290]: AST nodes are now raising TypeError on conflicting keyword arguments. Patch contributed by Rémi Lapeyre.

Tests

bpo-17258 [https://bugs.python.org/issue?@action=redirect&bpo=17258]: Skip some multiprocessing tests when MD5 hash digest is blocked.

Build

bpo-40514 [https://bugs.python.org/issue?@action=redirect&bpo=40514]: Remove --with-experimental-isolated-subinterpreters configure option in Python 3.9: the experiment continues in the master branch, but it’s no longer needed in 3.9.

bpo-40683 [https://bugs.python.org/issue?@action=redirect&bpo=40683]: Fixed an issue where the zoneinfo module and its tests were not included when Python is installed with make.

Windows

bpo-39631 [https://bugs.python.org/issue?@action=redirect&bpo=39631]: Changes the registered MIME type for .py files on Windows to text/x-python instead of text/plain.

bpo-40677 [https://bugs.python.org/issue?@action=redirect&bpo=40677]: Manually define IO_REPARSE_TAG_APPEXECLINK in case some old Windows SDK doesn’t have it.

macOS

bpo-40741 [https://bugs.python.org/issue?@action=redirect&bpo=40741]: Update macOS installer to use SQLite 3.32.2.

IDLE

bpo-39885 [https://bugs.python.org/issue?@action=redirect&bpo=39885]: Make context menu Cut and Copy work again when right-clicking within a selection.

bpo-40723 [https://bugs.python.org/issue?@action=redirect&bpo=40723]: Make test_idle pass when run after import.

C API

bpo-40910 [https://bugs.python.org/issue?@action=redirect&bpo=40910]: Export explicitly the Py_GetArgcArgv() function to the C API and document the function. Previously, it was exported implicitly which no longer works since Python is built with -fvisibility=hidden.

bpo-40724 [https://bugs.python.org/issue?@action=redirect&bpo=40724]: Allow defining buffer slots in type specs.

bpo-40826 [https://bugs.python.org/issue?@action=redirect&bpo=40826]: PyOS_InterruptOccurred() now fails with a fatal error if it is called with the GIL released.

Python 3.9.0 beta 1

Release date: 2020-05-19

Security

bpo-40501 [https://bugs.python.org/issue?@action=redirect&bpo=40501]: uuid no longer uses ctypes to load libuuid or rpcrt4.dll at runtime.

Core and Builtins

bpo-40663 [https://bugs.python.org/issue?@action=redirect&bpo=40663]: Correctly generate annotations where parentheses are omitted but required (e.g: Type[(str, int, *other))].

bpo-40596 [https://bugs.python.org/issue?@action=redirect&bpo=40596]: Fixed str.isidentifier() for non-canonicalized strings containing non-BMP characters on Windows.

bpo-40593 [https://bugs.python.org/issue?@action=redirect&bpo=40593]: Improved syntax errors for invalid characters in source code.

bpo-40585 [https://bugs.python.org/issue?@action=redirect&bpo=40585]: Fixed a bug when using codeop.compile_command() that was causing exceptions to be swallowed with the new parser. Patch by Pablo Galindo

bpo-40566 [https://bugs.python.org/issue?@action=redirect&bpo=40566]: Apply PEP 573 [https://www.python.org/dev/peps/pep-0573] to abc.

bpo-40502 [https://bugs.python.org/issue?@action=redirect&bpo=40502]: Initialize n->n_col_offset. (Patch by Joannah Nanjekye)

bpo-40527 [https://bugs.python.org/issue?@action=redirect&bpo=40527]: Fix command line argument parsing: no longer write errors multiple times into stderr.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port errno to multiphase initialization (PEP 489 [https://www.python.org/dev/peps/pep-0489]).

bpo-40523 [https://bugs.python.org/issue?@action=redirect&bpo=40523]: Add pass-throughs for hash() and reversed() to weakref.proxy objects. Patch by Pablo Galindo.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port syslog to multiphase initialization (PEP 489 [https://www.python.org/dev/peps/pep-0489]).

bpo-40246 [https://bugs.python.org/issue?@action=redirect&bpo=40246]: Reporting a specialised error message for invalid string prefixes, which was introduced in bpo-40246 [https://bugs.python.org/issue?@action=redirect&bpo=40246], is being reverted due to backwards compatibility concerns for strings that immediately follow a reserved keyword without whitespace between them. Constructs like bg="#d00" if clear else"#fca" were failing to parse, which is not an acceptable breakage on such short notice.

bpo-40417 [https://bugs.python.org/issue?@action=redirect&bpo=40417]: Fix imp module deprecation warning when PyImport_ReloadModule is called. Patch by Robert Rouhani.

bpo-40408 [https://bugs.python.org/issue?@action=redirect&bpo=40408]: Fixed support of nested type variables in GenericAlias (e.g. list[list[T]]).

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _stat module to multiphase initialization (PEP 489 [https://www.python.org/dev/peps/pep-0489]).

bpo-29587 [https://bugs.python.org/issue?@action=redirect&bpo=29587]: Enable implicit exception chaining when calling generator.throw().

bpo-40328 [https://bugs.python.org/issue?@action=redirect&bpo=40328]: Add tools for generating mappings headers for CJKCodecs.

bpo-40228 [https://bugs.python.org/issue?@action=redirect&bpo=40228]: Setting frame.f_lineno is now robust w.r.t. changes in the source-to-bytecode compiler

bpo-38880 [https://bugs.python.org/issue?@action=redirect&bpo=38880]: Added the ability to list interpreters associated with channel ends in the internal subinterpreters module.

bpo-37986 [https://bugs.python.org/issue?@action=redirect&bpo=37986]: Improve performance of PyLong_FromDouble() for values that fit into long.

Library

bpo-40662 [https://bugs.python.org/issue?@action=redirect&bpo=40662]: Fixed ast.get_source_segment() for ast nodes that have incomplete location information. Patch by Irit Katriel.

bpo-40665 [https://bugs.python.org/issue?@action=redirect&bpo=40665]: Convert bisect to use Argument Clinic.

bpo-40536 [https://bugs.python.org/issue?@action=redirect&bpo=40536]: Added the available_timezones() function to the zoneinfo module. Patch by Paul Ganssle.

bpo-40645 [https://bugs.python.org/issue?@action=redirect&bpo=40645]: The hmac.HMAC exposes internal implementation details. The attributes digest_cons, inner, and outer are deprecated and will be removed in the future.

bpo-40645 [https://bugs.python.org/issue?@action=redirect&bpo=40645]: The internal module _hashlib wraps and exposes OpenSSL’s HMAC API. The new code will be used in Python 3.10 after the internal implementation details of the pure Python HMAC module are no longer part of the public API.

bpo-40637 [https://bugs.python.org/issue?@action=redirect&bpo=40637]: Builtin hash modules can now be disabled or selectively enabled with configure --with-builtin-hashlib-hashes=sha3,blake1 or --without-builtin-hashlib-hashes.

bpo-37630 [https://bugs.python.org/issue?@action=redirect&bpo=37630]: The hashlib module can now use SHA3 hashes and SHAKE XOF from OpenSSL when available.

bpo-40479 [https://bugs.python.org/issue?@action=redirect&bpo=40479]: The hashlib now compiles with OpenSSL 3.0.0-alpha2.

bpo-40257 [https://bugs.python.org/issue?@action=redirect&bpo=40257]: Revert changes to inspect.getdoc().

bpo-40607 [https://bugs.python.org/issue?@action=redirect&bpo=40607]: When cancelling a task due to timeout, asyncio.wait_for() will now propagate the exception if an error happens during cancellation. Patch by Roman Skurikhin.

bpo-40612 [https://bugs.python.org/issue?@action=redirect&bpo=40612]: Fix edge cases in SyntaxError formatting. If the offset is <= 0, no caret is printed. If the offset is > line length, the caret is printed pointing just after the last character.

bpo-40597 [https://bugs.python.org/issue?@action=redirect&bpo=40597]: If text content lines are longer than policy.max_line_length, always use a content-encoding to make sure they are wrapped.

bpo-40571 [https://bugs.python.org/issue?@action=redirect&bpo=40571]: Added functools.cache() as a simpler, more discoverable way to access the unbounded cache variant of lru_cache(maxsize=None).

bpo-40503 [https://bugs.python.org/issue?@action=redirect&bpo=40503]: PEP 615 [https://www.python.org/dev/peps/pep-0615], the zoneinfo module. Adds support for the IANA time zone database.

bpo-40397 [https://bugs.python.org/issue?@action=redirect&bpo=40397]: Removed attributes __args__ and __parameters__ from special generic aliases like typing.List (not subscripted).

bpo-40549 [https://bugs.python.org/issue?@action=redirect&bpo=40549]: Convert posixmodule.c («posix» or «nt» module) to the multiphase initialization (PEP 489).

bpo-31033 [https://bugs.python.org/issue?@action=redirect&bpo=31033]: Add a msg argument to Future.cancel() and Task.cancel().

bpo-40541 [https://bugs.python.org/issue?@action=redirect&bpo=40541]: Added an optional counts parameter to random.sample().

bpo-40515 [https://bugs.python.org/issue?@action=redirect&bpo=40515]: The ssl and hashlib modules now actively check that OpenSSL is build with thread support. Python 3.7.0 made thread support mandatory and no longer works safely with a no-thread builds.

bpo-31033 [https://bugs.python.org/issue?@action=redirect&bpo=31033]: When a asyncio.Task is cancelled, the exception traceback now chains all the way back to where the task was first interrupted.

bpo-40504 [https://bugs.python.org/issue?@action=redirect&bpo=40504]: functools.lru_cache() objects can now be the targets of weakrefs.

bpo-40559 [https://bugs.python.org/issue?@action=redirect&bpo=40559]: Fix possible memory leak in the C implementation of asyncio.Task.

bpo-40480 [https://bugs.python.org/issue?@action=redirect&bpo=40480]: fnmatch.fnmatch() could take exponential time in the presence of multiple * pattern characters. This was repaired by generating more elaborate regular expressions to avoid futile backtracking.

bpo-40495 [https://bugs.python.org/issue?@action=redirect&bpo=40495]: compileall is now able to use hardlinks to prevent duplicates in a case when .pyc files for different optimization levels have the same content.

bpo-40457 [https://bugs.python.org/issue?@action=redirect&bpo=40457]: The ssl module now support OpenSSL builds without TLS 1.0 and 1.1 methods.

bpo-40355 [https://bugs.python.org/issue?@action=redirect&bpo=40355]: Improve error reporting in ast.literal_eval() in the presence of malformed ast.Dict nodes instead of silently ignoring any non-conforming elements. Patch by Curtis Bucher.

bpo-40465 [https://bugs.python.org/issue?@action=redirect&bpo=40465]: Deprecated the optional random argument to random.shuffle().

bpo-40459 [https://bugs.python.org/issue?@action=redirect&bpo=40459]: platform.win32_ver() now produces correct ptype strings instead of empty strings.

bpo-39435 [https://bugs.python.org/issue?@action=redirect&bpo=39435]: The first argument of pickle.loads() is now positional-only.

bpo-39305 [https://bugs.python.org/issue?@action=redirect&bpo=39305]: Update nntplib to merge nntplib.NNTP and nntplib._NNTPBase. Patch by Dong-hee Na.

bpo-32494 [https://bugs.python.org/issue?@action=redirect&bpo=32494]: Update dbm.gnu to use gdbm_count if possible when calling len(). Patch by Dong-hee Na.

bpo-40453 [https://bugs.python.org/issue?@action=redirect&bpo=40453]: Add isolated=True keyword-only parameter to _xxsubinterpreters.create(). An isolated subinterpreter cannot spawn threads, spawn a child process or call os.fork().

bpo-40286 [https://bugs.python.org/issue?@action=redirect&bpo=40286]: Remove _random.Random.randbytes(): the C implementation of randbytes(). Implement the method in Python to ease subclassing: randbytes() now directly reuses getrandbits().

bpo-40394 [https://bugs.python.org/issue?@action=redirect&bpo=40394]: Added default arguments to difflib.SequenceMatcher.find_longest_match().

bpo-39995 [https://bugs.python.org/issue?@action=redirect&bpo=39995]: Fix a race condition in concurrent.futures._ThreadWakeup: access to _ThreadWakeup is now protected with the shutdown lock.

bpo-30966 [https://bugs.python.org/issue?@action=redirect&bpo=30966]: Process.shutdown(wait=True) of concurrent.futures now closes explicitly the result queue.

bpo-30966 [https://bugs.python.org/issue?@action=redirect&bpo=30966]: Add a new close() method to the SimpleQueue class to explicitly close the queue.

bpo-39966 [https://bugs.python.org/issue?@action=redirect&bpo=39966]: Revert bpo-25597 [https://bugs.python.org/issue?@action=redirect&bpo=25597]. unittest.mock.MagicMock with wraps” set uses default return values for magic methods.

bpo-39791 [https://bugs.python.org/issue?@action=redirect&bpo=39791]: Added files() function to importlib.resources with support for subdirectories in package data, matching backport in importlib_resources 1.5.

bpo-40375 [https://bugs.python.org/issue?@action=redirect&bpo=40375]: imaplib.IMAP4.unselect() is added. Patch by Dong-hee Na.

bpo-40389 [https://bugs.python.org/issue?@action=redirect&bpo=40389]: repr() now returns typing.Optional[T] when called for typing.Union of two types, one of which is NoneType.

bpo-40291 [https://bugs.python.org/issue?@action=redirect&bpo=40291]: Add support for CAN_J1939 sockets (available on Linux 5.4+)

bpo-40273 [https://bugs.python.org/issue?@action=redirect&bpo=40273]: types.MappingProxyType is now reversible.

bpo-39075 [https://bugs.python.org/issue?@action=redirect&bpo=39075]: The repr for types.SimpleNamespace is now insertion ordered rather than alphabetical.

bpo-40192 [https://bugs.python.org/issue?@action=redirect&bpo=40192]: On AIX, thread_time() is now implemented with thread_cputime() which has nanosecond resolution, rather than clock_gettime(CLOCK_THREAD_CPUTIME_ID) which has a resolution of 10 ms. Patch by Batuhan Taskaya.

bpo-40025 [https://bugs.python.org/issue?@action=redirect&bpo=40025]: Raise TypeError when _generate_next_value_ is defined after members. Patch by Ethan Onstott.

bpo-39058 [https://bugs.python.org/issue?@action=redirect&bpo=39058]: In the argparse module, the repr for Namespace() and other argument holders now displayed in the order attributes were added. Formerly, it displayed in alphabetical order even though argument order is preserved the user visible parts of the module.

bpo-24416 [https://bugs.python.org/issue?@action=redirect&bpo=24416]: The isocalendar() methods of datetime.date and datetime.datetime now return a named tuple instead of a tuple.

Documentation

bpo-34790 [https://bugs.python.org/issue?@action=redirect&bpo=34790]: Add version of removal for explicit passing of coros to asyncio.wait()”s documentation

bpo-40561 [https://bugs.python.org/issue?@action=redirect&bpo=40561]: Provide docstrings for webbrowser open functions.

bpo-40499 [https://bugs.python.org/issue?@action=redirect&bpo=40499]: Mention that asyncio.wait() requires a non-empty set of awaitables.

bpo-39705 [https://bugs.python.org/issue?@action=redirect&bpo=39705]: Tutorial example for sorted() in the Loop Techniques section is given a better explanation. Also a new example is included to explain sorted()”s basic behavior.

bpo-39435 [https://bugs.python.org/issue?@action=redirect&bpo=39435]: Fix an incorrect signature for pickle.loads() in the docs

Tests

bpo-40055 [https://bugs.python.org/issue?@action=redirect&bpo=40055]: distutils.tests now saves/restores warnings filters to leave them unchanged. Importing tests imports docutils which imports pkg_resources which adds a warnings filter.

bpo-40436 [https://bugs.python.org/issue?@action=redirect&bpo=40436]: test_gdb and test.pythoninfo now check gdb command exit code.

Build

bpo-40653 [https://bugs.python.org/issue?@action=redirect&bpo=40653]: Move _dirnameW out of HAVE_SYMLINK to fix a potential compiling issue.

bpo-40514 [https://bugs.python.org/issue?@action=redirect&bpo=40514]: Add --with-experimental-isolated-subinterpreters build option to configure: better isolate subinterpreters, experimental build mode.

Windows

bpo-40650 [https://bugs.python.org/issue?@action=redirect&bpo=40650]: Include winsock2.h in pytime.c for timeval.

bpo-40458 [https://bugs.python.org/issue?@action=redirect&bpo=40458]: Increase reserved stack space to prevent overflow crash on Windows.

bpo-39148 [https://bugs.python.org/issue?@action=redirect&bpo=39148]: Add IPv6 support to asyncio datagram endpoints in ProactorEventLoop. Change the raised exception for unknown address families to ValueError as it’s not coming from Windows API.

macOS

bpo-34956 [https://bugs.python.org/issue?@action=redirect&bpo=34956]: When building Python on macOS from source, _tkinter now links with non-system Tcl and Tk frameworks if they are installed in /Library/Frameworks, as had been the case on older releases of macOS. If a macOS SDK is explicitly configured, by using --enable-universalsdk= or -isysroot, only the SDK itself is searched. The default behavior can still be overridden with --with-tcltk-includes and --with-tcltk-libs.

bpo-35569 [https://bugs.python.org/issue?@action=redirect&bpo=35569]: Expose RFC 3542 IPv6 socket options.

Tools/Demos

bpo-40479 [https://bugs.python.org/issue?@action=redirect&bpo=40479]: Update multissltest helper to test with latest OpenSSL 1.0.2, 1.1.0, 1.1.1, and 3.0.0-alpha.

bpo-40431 [https://bugs.python.org/issue?@action=redirect&bpo=40431]: Fix a syntax typo in turtledemo that now raises a SyntaxError.

bpo-40163 [https://bugs.python.org/issue?@action=redirect&bpo=40163]: Fix multissltest tool. OpenSSL has changed download URL for old releases. The multissltest tool now tries to download from current and old download URLs.

C API

bpo-39465 [https://bugs.python.org/issue?@action=redirect&bpo=39465]: Remove the _PyUnicode_ClearStaticStrings() function from the C API.

bpo-38787 [https://bugs.python.org/issue?@action=redirect&bpo=38787]: Add PyCFunction_CheckExact() macro for exact type checks now that we allow subtypes of PyCFunction, as well as PyCMethod_CheckExact() and PyCMethod_Check() for the new PyCMethod subtype.

bpo-40545 [https://bugs.python.org/issue?@action=redirect&bpo=40545]: Declare _PyErr_GetTopmostException() with PyAPI_FUNC() to properly export the function in the C API. The function remains private (_Py) prefix.

bpo-40412 [https://bugs.python.org/issue?@action=redirect&bpo=40412]: Nullify inittab_copy during finalization, preventing future interpreter initializations in an embedded situation from crashing. Patch by Gregory Szorc.

bpo-40429 [https://bugs.python.org/issue?@action=redirect&bpo=40429]: The PyThreadState_GetFrame() function now returns a strong reference to the frame.

bpo-40428 [https://bugs.python.org/issue?@action=redirect&bpo=40428]: Remove the following functions from the C API. Call PyGC_Collect() explicitly to free all free lists.

PyAsyncGen_ClearFreeLists()

PyContext_ClearFreeList()

PyDict_ClearFreeList()

PyFloat_ClearFreeList()

PyFrame_ClearFreeList()

PyList_ClearFreeList()

PySet_ClearFreeList()

PyTuple_ClearFreeList()

bpo-40421 [https://bugs.python.org/issue?@action=redirect&bpo=40421]: New PyFrame_GetBack() function: get the frame next outer frame.

bpo-40421 [https://bugs.python.org/issue?@action=redirect&bpo=40421]: New PyFrame_GetCode() function: return a borrowed reference to the frame code.

bpo-40217 [https://bugs.python.org/issue?@action=redirect&bpo=40217]: Ensure that instances of types created with PyType_FromSpecWithBases() will visit its class object when traversing references in the garbage collector (implemented as an extension of the provided tp_traverse). Patch by Pablo Galindo.

bpo-38787 [https://bugs.python.org/issue?@action=redirect&bpo=38787]: Module C state is now accessible from C-defined heap type methods (PEP 573 [https://www.python.org/dev/peps/pep-0573]). Patch by Marcel Plch and Petr Viktorin.

Python 3.9.0 alpha 6

Release date: 2020-04-27

Security

bpo-40121 [https://bugs.python.org/issue?@action=redirect&bpo=40121]: Fixes audit events raised on creating a new socket.

bpo-39073 [https://bugs.python.org/issue?@action=redirect&bpo=39073]: Disallow CR or LF in email.headerregistry.Address arguments to guard against header injection attacks.

bpo-39503 [https://bugs.python.org/issue?@action=redirect&bpo=39503]: CVE-2020-8492: The AbstractBasicAuthHandler class of the urllib.request module uses an inefficient regular expression which can be exploited by an attacker to cause a denial of service. Fix the regex to prevent the catastrophic backtracking. Vulnerability reported by Ben Caller and Matt Schwager.

Core and Builtins

bpo-40313 [https://bugs.python.org/issue?@action=redirect&bpo=40313]: Improve the performance of bytes.hex().

bpo-40334 [https://bugs.python.org/issue?@action=redirect&bpo=40334]: Switch to a new parser, based on PEG. For more details see PEP 617. To temporarily switch back to the old parser, use -X oldparser or PYTHONOLDPARSER=1. In Python 3.10 we will remove the old parser completely, including the parser module (already deprecated) and anything that depends on it.

bpo-40267 [https://bugs.python.org/issue?@action=redirect&bpo=40267]: Fix the tokenizer to display the correct error message, when there is a SyntaxError on the last input character and no newline follows. It used to be unexpected EOF while parsing, while it should be invalid syntax.

bpo-39522 [https://bugs.python.org/issue?@action=redirect&bpo=39522]: Correctly unparse explicit u prefix for strings when postponed evaluation for annotations activated. Patch by Batuhan Taskaya.

bpo-40246 [https://bugs.python.org/issue?@action=redirect&bpo=40246]: Report a specialized error message, invalid string prefix, when the tokenizer encounters a string with an invalid prefix.

bpo-40082 [https://bugs.python.org/issue?@action=redirect&bpo=40082]: Fix the signal handler: it now always uses the main interpreter, rather than trying to get the current Python thread state.

bpo-37388 [https://bugs.python.org/issue?@action=redirect&bpo=37388]: str.encode() and str.decode() no longer check the encoding and errors in development mode or in debug mode during Python finalization. The codecs machinery can no longer work on very late calls to str.encode() and str.decode().

bpo-40077 [https://bugs.python.org/issue?@action=redirect&bpo=40077]: Fix possible refleaks in _json, memo of PyScannerObject should be traversed.

bpo-37207 [https://bugs.python.org/issue?@action=redirect&bpo=37207]: Speed up calls to dict() by using the PEP 590 [https://www.python.org/dev/peps/pep-0590] vectorcall calling convention.

bpo-40141 [https://bugs.python.org/issue?@action=redirect&bpo=40141]: Add column and line information to ast.keyword nodes. Patch by Pablo Galindo.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port resource to multiphase initialization (PEP 489 [https://www.python.org/dev/peps/pep-0489]).

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port math to multiphase initialization (PEP 489 [https://www.python.org/dev/peps/pep-0489]).

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _uuid module to multiphase initialization (PEP 489 [https://www.python.org/dev/peps/pep-0489]).

bpo-40077 [https://bugs.python.org/issue?@action=redirect&bpo=40077]: Convert json module to use PyType_FromSpec().

bpo-40067 [https://bugs.python.org/issue?@action=redirect&bpo=40067]: Improve the error message for multiple star expressions in an assignment. Patch by Furkan Onder

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _functools module to multiphase initialization (PEP 489). Patch by Paulo Henrique Silva.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port operator module to multiphase initialization (PEP 489). Patch by Paulo Henrique Silva.

bpo-20526 [https://bugs.python.org/issue?@action=redirect&bpo=20526]: Fix PyThreadState_Clear(). PyThreadState.frame is a borrowed reference, not a strong reference: PyThreadState_Clear() must not call Py_CLEAR(tstate->frame).

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port time module to multiphase initialization (PEP 489 [https://www.python.org/dev/peps/pep-0489]). Patch by Paulo Henrique Silva.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _weakref extension module to multiphase initialization (PEP 489 [https://www.python.org/dev/peps/pep-0489]).

bpo-40020 [https://bugs.python.org/issue?@action=redirect&bpo=40020]: Fix a leak and subsequent crash in parsetok.c caused by realloc misuse on a rare codepath.

bpo-39939 [https://bugs.python.org/issue?@action=redirect&bpo=39939]: Added str.removeprefix and str.removesuffix methods and corresponding bytes, bytearray, and collections.UserString methods to remove affixes from a string if present. See PEP 616 [https://www.python.org/dev/peps/pep-0616] for a full description. Patch by Dennis Sweeney.

bpo-39481 [https://bugs.python.org/issue?@action=redirect&bpo=39481]: Implement PEP 585. This supports list[int], tuple[str, …] etc.

bpo-32894 [https://bugs.python.org/issue?@action=redirect&bpo=32894]: Support unparsing of infinity numbers in postponed annotations. Patch by Batuhan Taşkaya.

bpo-37207 [https://bugs.python.org/issue?@action=redirect&bpo=37207]: Speed up calls to list() by using the PEP 590 [https://www.python.org/dev/peps/pep-0590] vectorcall calling convention. Patch by Mark Shannon.

Library

bpo-40398 [https://bugs.python.org/issue?@action=redirect&bpo=40398]: typing.get_args() now always returns an empty tuple for special generic aliases.

bpo-40396 [https://bugs.python.org/issue?@action=redirect&bpo=40396]: Functions typing.get_origin(), typing.get_args() and typing.get_type_hints() support now generic aliases like list[int].

bpo-38061 [https://bugs.python.org/issue?@action=redirect&bpo=38061]: Optimize the subprocess module on FreeBSD using closefrom(). A single close(fd) syscall is cheap, but when sysconf(_SC_OPEN_MAX) is high, the loop calling close(fd) on each file descriptor can take several milliseconds.

The workaround on FreeBSD to improve performance was to load and mount the fdescfs kernel module, but this is not enabled by default.

Initial patch by Ed Maste (emaste), Conrad Meyer (cem), Kyle Evans (kevans) and Kubilay Kocak (koobs): https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=242274

bpo-38061 [https://bugs.python.org/issue?@action=redirect&bpo=38061]: On FreeBSD, os.closerange(fd_low, fd_high) now calls closefrom(fd_low) if fd_high is greater than or equal to sysconf(_SC_OPEN_MAX).

Initial patch by Ed Maste (emaste), Conrad Meyer (cem), Kyle Evans (kevans) and Kubilay Kocak (koobs): https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=242274

bpo-40360 [https://bugs.python.org/issue?@action=redirect&bpo=40360]: The lib2to3 module is pending deprecation due to PEP 617 [https://www.python.org/dev/peps/pep-0617].

bpo-40138 [https://bugs.python.org/issue?@action=redirect&bpo=40138]: Fix the Windows implementation of os.waitpid() for exit code larger than INT_MAX >> 8. The exit status is now interpreted as an unsigned number.

bpo-39942 [https://bugs.python.org/issue?@action=redirect&bpo=39942]: Set «__main__» as the default module name when «__name__» is missing in typing.TypeVar. Patch by Weipeng Hong.

bpo-40275 [https://bugs.python.org/issue?@action=redirect&bpo=40275]: The logging package is now imported lazily in unittest only when the assertLogs() assertion is used.

bpo-40275 [https://bugs.python.org/issue?@action=redirect&bpo=40275]: The asyncio package is now imported lazily in unittest only when the IsolatedAsyncioTestCase class is used.

bpo-40330 [https://bugs.python.org/issue?@action=redirect&bpo=40330]: In ShareableList.__setitem__(), check the size of a new string item after encoding it to utf-8, not before.

bpo-40148 [https://bugs.python.org/issue?@action=redirect&bpo=40148]: Added pathlib.Path.with_stem() to create a new Path with the stem replaced.

bpo-40325 [https://bugs.python.org/issue?@action=redirect&bpo=40325]: Deprecated support for set objects in random.sample().

bpo-40257 [https://bugs.python.org/issue?@action=redirect&bpo=40257]: Improved help for the typing module. Docstrings are now shown for all special forms and special generic aliases (like Union and List). Using help() with generic alias like List[int] will show the help for the correspondent concrete type (list in this case).

bpo-40257 [https://bugs.python.org/issue?@action=redirect&bpo=40257]: func:inspect.getdoc no longer returns docstring inherited from the type of the object or from parent class if it is a class if it is not defined in the object itself. In pydoc the documentation string is now shown not only for class, function, method etc, but for any object that has its own __doc__ attribute.

bpo-40287 [https://bugs.python.org/issue?@action=redirect&bpo=40287]: Fixed SpooledTemporaryFile.seek() to return the position.

bpo-40290 [https://bugs.python.org/issue?@action=redirect&bpo=40290]: Added zscore() to statistics.NormalDist().

bpo-40282 [https://bugs.python.org/issue?@action=redirect&bpo=40282]: Allow random.getrandbits(0) to succeed and to return 0.

bpo-40286 [https://bugs.python.org/issue?@action=redirect&bpo=40286]: Add random.randbytes() function and random.Random.randbytes() method to generate random bytes.

bpo-40277 [https://bugs.python.org/issue?@action=redirect&bpo=40277]: collections.namedtuple() now provides a human-readable repr for its field accessors.

bpo-40270 [https://bugs.python.org/issue?@action=redirect&bpo=40270]: The included copy of sqlite3 on Windows is now compiled with the json extension. This allows the use of functions such as json_object.

bpo-29255 [https://bugs.python.org/issue?@action=redirect&bpo=29255]: Wait in KqueueSelector.select when no fds are registered

bpo-40260 [https://bugs.python.org/issue?@action=redirect&bpo=40260]: Ensure modulefinder uses io.open_code() and respects coding comments.

bpo-40234 [https://bugs.python.org/issue?@action=redirect&bpo=40234]: Allow again to spawn daemon threads in subinterpreters (revert change which denied them).

bpo-39207 [https://bugs.python.org/issue?@action=redirect&bpo=39207]: Workers in ProcessPoolExecutor are now spawned on demand, only when there are no available idle workers to reuse. This optimizes startup overhead and reduces the amount of lost CPU time to idle workers. Patch by Kyle Stanley.

bpo-40091 [https://bugs.python.org/issue?@action=redirect&bpo=40091]: Fix a hang at fork in the logging module: the new private _at_fork_reinit() method is now used to reinitialize locks at fork in the child process.

bpo-40149 [https://bugs.python.org/issue?@action=redirect&bpo=40149]: Implement traverse and clear slots in _abc._abc_data type.

bpo-40208 [https://bugs.python.org/issue?@action=redirect&bpo=40208]: Remove deprecated symtable.SymbolTable.has_exec().

bpo-40196 [https://bugs.python.org/issue?@action=redirect&bpo=40196]: Fix a bug in the symtable module that was causing incorrectly report global variables as local. Patch by Pablo Galindo.

bpo-40190 [https://bugs.python.org/issue?@action=redirect&bpo=40190]: Add support for _SC_AIX_REALMEM to posix.sysconf().

bpo-40182 [https://bugs.python.org/issue?@action=redirect&bpo=40182]: Removed the _field_types attribute of the typing.NamedTuple class.

bpo-36517 [https://bugs.python.org/issue?@action=redirect&bpo=36517]: Multiple inheritance with typing.NamedTuple now raises an error instead of silently ignoring other types.

bpo-40126 [https://bugs.python.org/issue?@action=redirect&bpo=40126]: Fixed reverting multiple patches in unittest.mock. Patcher’s __exit__() is now never called if its __enter__() is failed. Returning true from __exit__() silences now the exception.

bpo-40094 [https://bugs.python.org/issue?@action=redirect&bpo=40094]: CGIHTTPRequestHandler of http.server now logs the CGI script exit code, rather than the CGI script exit status of os.waitpid(). For example, if the script is killed by signal 11, it now logs: «CGI script exit code -11.»

bpo-40108 [https://bugs.python.org/issue?@action=redirect&bpo=40108]: Improve the error message when triying to import a module using runpy and incorrently use the «.py» extension at the end of the module name. Patch by Pablo Galindo.

bpo-40094 [https://bugs.python.org/issue?@action=redirect&bpo=40094]: Add os.waitstatus_to_exitcode() function: convert a wait status to an exit code.

bpo-40089 [https://bugs.python.org/issue?@action=redirect&bpo=40089]: Fix threading._after_fork(): if fork was not called by a thread spawned by threading.Thread, threading._after_fork() now creates a _MainThread instance for _main_thread, instead of a _DummyThread instance.

bpo-40089 [https://bugs.python.org/issue?@action=redirect&bpo=40089]: Add a private _at_fork_reinit() method to _thread.Lock, _thread.RLock, threading.RLock and threading.Condition classes: reinitialize the lock at fork in the child process, reset the lock to the unlocked state. Rename also the private _reset_internal_locks() method of threading.Event to _at_fork_reinit().

bpo-25780 [https://bugs.python.org/issue?@action=redirect&bpo=25780]: Expose CAN_RAW_JOIN_FILTERS in the socket module.

bpo-39503 [https://bugs.python.org/issue?@action=redirect&bpo=39503]: AbstractBasicAuthHandler of urllib.request now parses all WWW-Authenticate HTTP headers and accepts multiple challenges per header: use the realm of the first Basic challenge.

bpo-39812 [https://bugs.python.org/issue?@action=redirect&bpo=39812]: Removed daemon threads from concurrent.futures by adding an internal threading._register_atexit(), which calls registered functions prior to joining all non-daemon threads. This allows for compatibility with subinterpreters, which don’t support daemon threads.

bpo-40050 [https://bugs.python.org/issue?@action=redirect&bpo=40050]: Fix importlib._bootstrap_external: avoid creating a new winreg builtin module if it’s already available in sys.modules, and remove redundant imports.

bpo-40014 [https://bugs.python.org/issue?@action=redirect&bpo=40014]: Fix os.getgrouplist(): if getgrouplist() function fails because the group list is too small, retry with a larger group list. On failure, the glibc implementation of getgrouplist() sets ngroups to the total number of groups. For other implementations, double the group list size.

bpo-40017 [https://bugs.python.org/issue?@action=redirect&bpo=40017]: Add time.CLOCK_TAI constant if the operating system support it.

bpo-40016 [https://bugs.python.org/issue?@action=redirect&bpo=40016]: In re docstring, clarify the relationship between inline and argument compile flags.

bpo-39953 [https://bugs.python.org/issue?@action=redirect&bpo=39953]: Update internal table of OpenSSL error codes in the ssl module.

bpo-36144 [https://bugs.python.org/issue?@action=redirect&bpo=36144]: Added PEP 584 [https://www.python.org/dev/peps/pep-0584] operators to weakref.WeakValueDictionary.

bpo-36144 [https://bugs.python.org/issue?@action=redirect&bpo=36144]: Added PEP 584 [https://www.python.org/dev/peps/pep-0584] operators to weakref.WeakKeyDictionary.

bpo-38891 [https://bugs.python.org/issue?@action=redirect&bpo=38891]: Fix linear runtime behaviour of the __getitem__ and __setitem__ methods in multiprocessing.shared_memory.ShareableList. This avoids quadratic performance when iterating a ShareableList. Patch by Thomas Krennwallner.

bpo-39682 [https://bugs.python.org/issue?@action=redirect&bpo=39682]: Remove undocumented support for closing a pathlib.Path object via its context manager. The context manager magic methods remain, but they are now a no-op, making Path objects immutable.

bpo-36144 [https://bugs.python.org/issue?@action=redirect&bpo=36144]: Added PEP 584 [https://www.python.org/dev/peps/pep-0584] operators (| and |=) to collections.ChainMap.

bpo-39011 [https://bugs.python.org/issue?@action=redirect&bpo=39011]: Normalization of line endings in ElementTree attributes was removed, as line endings which were replaced by entity numbers should be preserved in original form.

bpo-38410 [https://bugs.python.org/issue?@action=redirect&bpo=38410]: Properly handle sys.audit() failures in sys.set_asyncgen_hooks().

bpo-36541 [https://bugs.python.org/issue?@action=redirect&bpo=36541]: lib2to3 now recognizes named assignment expressions (the walrus operator, :=)

bpo-35967 [https://bugs.python.org/issue?@action=redirect&bpo=35967]: In platform, delay the invocation of “uname -p” until the processor attribute is requested.

bpo-35113 [https://bugs.python.org/issue?@action=redirect&bpo=35113]: inspect.getsource() now returns correct source code for inner class with same name as module level class. Decorators are also returned as part of source of the class. Patch by Karthikeyan Singaravelan.

bpo-33262 [https://bugs.python.org/issue?@action=redirect&bpo=33262]: Deprecate passing None as an argument for shlex.split()”s s parameter. Patch by Zackery Spytz.

bpo-31758 [https://bugs.python.org/issue?@action=redirect&bpo=31758]: Prevent crashes when using an uninitialized _elementtree.XMLParser object. Patch by Oren Milman.

Documentation

bpo-27635 [https://bugs.python.org/issue?@action=redirect&bpo=27635]: The pickle documentation incorrectly claimed that __new__ isn’t called by default when unpickling.

bpo-39879 [https://bugs.python.org/issue?@action=redirect&bpo=39879]: Updated Modelo de datos docs to include dict() insertion order preservation. Patch by Furkan Onder and Samy Lahfa.

bpo-38387 [https://bugs.python.org/issue?@action=redirect&bpo=38387]: Document PyDoc_STRVAR macro in the C-API reference.

bpo-13743 [https://bugs.python.org/issue?@action=redirect&bpo=13743]: Some methods within xml.dom.minidom.Element class are now better documented.

Tests

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Set expected default encoding in test_c_locale_coercion.py for VxWorks RTOS.

bpo-40162 [https://bugs.python.org/issue?@action=redirect&bpo=40162]: Update Travis CI configuration to OpenSSL 1.1.1f.

bpo-40146 [https://bugs.python.org/issue?@action=redirect&bpo=40146]: Update OpenSSL to 1.1.1f in Azure Pipelines.

bpo-40094 [https://bugs.python.org/issue?@action=redirect&bpo=40094]: Add test.support.wait_process() function.

bpo-40003 [https://bugs.python.org/issue?@action=redirect&bpo=40003]: test.bisect_cmd now copies Python command line options like -O or -W. Moreover, emit a warning if test.bisect_cmd is used with -w/--verbose2 option.

bpo-39380 [https://bugs.python.org/issue?@action=redirect&bpo=39380]: Add the encoding in ftplib.FTP and ftplib.FTP_TLS to the constructor as keyword-only and change the default from latin-1 to utf-8 to follow RFC 2640 [https://tools.ietf.org/html/rfc2640.html].

bpo-39793 [https://bugs.python.org/issue?@action=redirect&bpo=39793]: Use the same domain when testing make_msgid. Patch by Batuhan Taskaya.

bpo-1812 [https://bugs.python.org/issue?@action=redirect&bpo=1812]: Fix newline handling in doctest.testfile when loading from a package whose loader has a get_data method. Patch by Peter Donis.

Build

bpo-38360 [https://bugs.python.org/issue?@action=redirect&bpo=38360]: Support single-argument form of macOS -isysroot flag.

bpo-40158 [https://bugs.python.org/issue?@action=redirect&bpo=40158]: Fix CPython MSBuild Properties in NuGet Package (build/native/python.props)

bpo-38527 [https://bugs.python.org/issue?@action=redirect&bpo=38527]: Fix configure check on Solaris for «float word ordering»: sometimes, the correct «grep» command was not being used. Patch by Arnon Yaari.

Windows

bpo-40164 [https://bugs.python.org/issue?@action=redirect&bpo=40164]: Updates Windows to OpenSSL 1.1.1f

bpo-8901 [https://bugs.python.org/issue?@action=redirect&bpo=8901]: Ignore the Windows registry when the -E option is used.

macOS

bpo-38329 [https://bugs.python.org/issue?@action=redirect&bpo=38329]: python.org macOS installers now update the Current version symlink of /Library/Frameworks/Python.framework/Versions for 3.9 installs. Previously, Current was only updated for Python 2.x installs. This should make it easier to embed Python 3 into other macOS applications.

bpo-40164 [https://bugs.python.org/issue?@action=redirect&bpo=40164]: Update macOS installer builds to use OpenSSL 1.1.1g.

IDLE

bpo-38439 [https://bugs.python.org/issue?@action=redirect&bpo=38439]: Add a 256×256 pixel IDLE icon to support more modern environments. Created by Andrew Clover. Delete the unused macOS idle.icns icon file.

bpo-38689 [https://bugs.python.org/issue?@action=redirect&bpo=38689]: IDLE will no longer freeze when inspect.signature fails when fetching a calltip.

Tools/Demos

bpo-40385 [https://bugs.python.org/issue?@action=redirect&bpo=40385]: Removed the checkpyc.py tool. Please see compileall without force mode as a potential alternative.

bpo-40179 [https://bugs.python.org/issue?@action=redirect&bpo=40179]: Fixed translation of #elif in Argument Clinic.

bpo-40094 [https://bugs.python.org/issue?@action=redirect&bpo=40094]: Fix which.py script exit code: it now uses os.waitstatus_to_exitcode() to convert os.system() exit status into an exit code.

C API

bpo-40241 [https://bugs.python.org/issue?@action=redirect&bpo=40241]: Move the PyGC_Head structure to the internal C API.

bpo-40170 [https://bugs.python.org/issue?@action=redirect&bpo=40170]: Convert PyObject_IS_GC() macro to a function to hide implementation details.

bpo-40241 [https://bugs.python.org/issue?@action=redirect&bpo=40241]: Add the functions PyObject_GC_IsTracked() and PyObject_GC_IsFinalized() to the public API to allow to query if Python objects are being currently tracked or have been already finalized by the garbage collector respectively. Patch by Pablo Galindo.

bpo-40170 [https://bugs.python.org/issue?@action=redirect&bpo=40170]: The PyObject_NEW() macro becomes an alias to the PyObject_New() macro, and the PyObject_NEW_VAR() macro becomes an alias to the PyObject_NewVar() macro, to hide implementation details. They no longer access directly the PyTypeObject.tp_basicsize member.

bpo-40170 [https://bugs.python.org/issue?@action=redirect&bpo=40170]: PyType_HasFeature() now always calls PyType_GetFlags() to hide implementation details. Previously, it accessed directly the PyTypeObject.tp_flags member when the limited C API was not used.

bpo-40170 [https://bugs.python.org/issue?@action=redirect&bpo=40170]: Convert the PyObject_GET_WEAKREFS_LISTPTR() macro to a function to hide implementation details: the macro accessed directly to the PyTypeObject.tp_weaklistoffset member.

bpo-40170 [https://bugs.python.org/issue?@action=redirect&bpo=40170]: Convert PyObject_CheckBuffer() macro to a function to hide implementation details: the macro accessed directly the PyTypeObject.tp_as_buffer member.

bpo-40170 [https://bugs.python.org/issue?@action=redirect&bpo=40170]: Always declare PyIndex_Check() as an opaque function to hide implementation details: remove PyIndex_Check() macro. The macro accessed directly the PyTypeObject.tp_as_number member.

bpo-39947 [https://bugs.python.org/issue?@action=redirect&bpo=39947]: Add PyThreadState_GetID() function: get the unique identifier of a Python thread state.

Python 3.9.0 alpha 5

Release date: 2020-03-23

Security

bpo-38576 [https://bugs.python.org/issue?@action=redirect&bpo=38576]: Disallow control characters in hostnames in http.client, addressing CVE-2019-18348. Such potentially malicious header injection URLs now cause a InvalidURL to be raised.

Core and Builtins

bpo-40010 [https://bugs.python.org/issue?@action=redirect&bpo=40010]: Optimize pending calls in multithreaded applications. If a thread different than the main thread schedules a pending call (Py_AddPendingCall()), the bytecode evaluation loop is no longer interrupted at each bytecode instruction to check for pending calls which cannot be executed. Only the main thread can execute pending calls.

Previously, the bytecode evaluation loop was interrupted at each instruction until the main thread executes pending calls.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _weakref extension module to multiphase initialization (PEP 489 [https://www.python.org/dev/peps/pep-0489]).

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _collections module to multiphase initialization (PEP 489 [https://www.python.org/dev/peps/pep-0489]).

bpo-40010 [https://bugs.python.org/issue?@action=redirect&bpo=40010]: Optimize signal handling in multithreaded applications. If a thread different than the main thread gets a signal, the bytecode evaluation loop is no longer interrupted at each bytecode instruction to check for pending signals which cannot be handled. Only the main thread of the main interpreter can handle signals.

Previously, the bytecode evaluation loop was interrupted at each instruction until the main thread handles signals.

bpo-39984 [https://bugs.python.org/issue?@action=redirect&bpo=39984]: If Py_AddPendingCall() is called in a subinterpreter, the function is now scheduled to be called from the subinterpreter, rather than being called from the main interpreter. Each subinterpreter now has its own list of scheduled calls.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _heapq module to multiphase initialization.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port itertools module to multiphase initialization (PEP 489 [https://www.python.org/dev/peps/pep-0489]).

bpo-37207 [https://bugs.python.org/issue?@action=redirect&bpo=37207]: Speed up calls to frozenset() by using the PEP 590 [https://www.python.org/dev/peps/pep-0590] vectorcall calling convention. Patch by Dong-hee Na.

bpo-39984 [https://bugs.python.org/issue?@action=redirect&bpo=39984]: subinterpreters: Move _PyRuntimeState.ceval.tracing_possible to PyInterpreterState.ceval.tracing_possible: each interpreter now has its own variable.

bpo-37207 [https://bugs.python.org/issue?@action=redirect&bpo=37207]: Speed up calls to set() by using the PEP 590 [https://www.python.org/dev/peps/pep-0590] vectorcall calling convention. Patch by Dong-hee Na.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _statistics module to multiphase initialization (PEP 489 [https://www.python.org/dev/peps/pep-0489]).

bpo-39968 [https://bugs.python.org/issue?@action=redirect&bpo=39968]: Use inline function to replace extension modules” get_module_state macros.

bpo-39965 [https://bugs.python.org/issue?@action=redirect&bpo=39965]: Correctly raise SyntaxError if await is used inside non-async functions and PyCF_ALLOW_TOP_LEVEL_AWAIT is set (like in the asyncio REPL). Patch by Pablo Galindo.

bpo-39562 [https://bugs.python.org/issue?@action=redirect&bpo=39562]: Allow executing asynchronous comprehensions on the top level when the PyCF_ALLOW_TOP_LEVEL_AWAIT flag is given. Patch by Batuhan Taskaya.

bpo-37207 [https://bugs.python.org/issue?@action=redirect&bpo=37207]: Speed up calls to tuple() by using the PEP 590 [https://www.python.org/dev/peps/pep-0590] vectorcall calling convention. Patch by Dong-hee Na.

bpo-38373 [https://bugs.python.org/issue?@action=redirect&bpo=38373]: Changed list overallocation strategy. It no longer overallocates if the new size is closer to overalocated size than to the old size and adds padding.

bpo-39926 [https://bugs.python.org/issue?@action=redirect&bpo=39926]: Update Unicode database to Unicode version 13.0.0.

bpo-19466 [https://bugs.python.org/issue?@action=redirect&bpo=19466]: Clear the frames of daemon threads earlier during the Python shutdown to call objects destructors. So «unclosed file» resource warnings are now emitted for daemon threads in a more reliable way.

bpo-38894 [https://bugs.python.org/issue?@action=redirect&bpo=38894]: Fix a bug that was causing incomplete results when calling pathlib.Path.glob in the presence of symlinks that point to files where the user does not have read access. Patch by Pablo Galindo and Matt Wozniski.

bpo-39877 [https://bugs.python.org/issue?@action=redirect&bpo=39877]: Fix PyEval_RestoreThread() random crash at exit with daemon threads. It now accesses the _PyRuntime variable directly instead of using tstate->interp->runtime, since tstate can be a dangling pointer after Py_Finalize() has been called. Moreover, the daemon thread now exits before trying to take the GIL.

bpo-39871 [https://bugs.python.org/issue?@action=redirect&bpo=39871]: Fix a possible SystemError in math.{atan2,copysign,remainder}() when the first argument cannot be converted to a float. Patch by Zackery Spytz.

bpo-39776 [https://bugs.python.org/issue?@action=redirect&bpo=39776]: Fix race condition where threads created by PyGILState_Ensure() could get a duplicate id.

This affects consumers of tstate->id like the contextvar caching machinery, which could return invalid cached objects under heavy thread load (observed in embedded scenarios).

bpo-39778 [https://bugs.python.org/issue?@action=redirect&bpo=39778]: Fixed a crash due to incorrect handling of weak references in collections.OrderedDict classes. Patch by Pablo Galindo.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port audioop extension module to multiphase initialization (PEP 489 [https://www.python.org/dev/peps/pep-0489]).

bpo-39702 [https://bugs.python.org/issue?@action=redirect&bpo=39702]: Relax decorator grammar restrictions to allow any valid expression (PEP 614 [https://www.python.org/dev/peps/pep-0614]).

bpo-38091 [https://bugs.python.org/issue?@action=redirect&bpo=38091]: Tweak import deadlock detection code to not deadlock itself.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _locale extension module to multiphase initialization (PEP 489 [https://www.python.org/dev/peps/pep-0489]).

bpo-39087 [https://bugs.python.org/issue?@action=redirect&bpo=39087]: Optimize PyUnicode_AsUTF8() and PyUnicode_AsUTF8AndSize() slightly when they need to create internal UTF-8 cache.

bpo-39520 [https://bugs.python.org/issue?@action=redirect&bpo=39520]: Fix unparsing of ext slices with no items (foo[:,]). Patch by Batuhan Taskaya.

bpo-39220 [https://bugs.python.org/issue?@action=redirect&bpo=39220]: Do not optimize annotations if “from __future__ import annotations” is used. Patch by Pablo Galindo.

bpo-35712 [https://bugs.python.org/issue?@action=redirect&bpo=35712]: Using NotImplemented in a boolean context has been deprecated. Patch contributed by Josh Rosenberg.

bpo-22490 [https://bugs.python.org/issue?@action=redirect&bpo=22490]: Don’t leak environment variable __PYVENV_LAUNCHER__ into the interpreter session on macOS.

Library

bpo-39830 [https://bugs.python.org/issue?@action=redirect&bpo=39830]: Add zipfile.Path to __all__ in the zipfile module.

bpo-40000 [https://bugs.python.org/issue?@action=redirect&bpo=40000]: Improved error messages for validation of ast.Constant nodes. Patch by Batuhan Taskaya.

bpo-39999 [https://bugs.python.org/issue?@action=redirect&bpo=39999]: __module__ of the AST node classes is now set to «ast» instead of «_ast». Added docstrings for dummy AST node classes and deprecated attributes.

bpo-39991 [https://bugs.python.org/issue?@action=redirect&bpo=39991]: uuid.getnode() now skips IPv6 addresses with the same string length than a MAC address (17 characters): only use MAC addresses.

bpo-39988 [https://bugs.python.org/issue?@action=redirect&bpo=39988]: Deprecated ast.AugLoad and ast.AugStore node classes because they are no longer used.

bpo-39656 [https://bugs.python.org/issue?@action=redirect&bpo=39656]: Ensure bin/python3.# is always present in virtual environments on POSIX platforms - by Anthony Sottile.

bpo-39969 [https://bugs.python.org/issue?@action=redirect&bpo=39969]: Deprecated ast.Param node class because it’s no longer used. Patch by Batuhan Taskaya.

bpo-39360 [https://bugs.python.org/issue?@action=redirect&bpo=39360]: Ensure all workers exit when finalizing a multiprocessing.Pool implicitly via the module finalization handlers of multiprocessing. This fixes a deadlock situation that can be experienced when the Pool is not properly finalized via the context manager or a call to multiprocessing.Pool.terminate. Patch by Batuhan Taskaya and Pablo Galindo.

bpo-35370 [https://bugs.python.org/issue?@action=redirect&bpo=35370]: sys.settrace(), sys.setprofile() and _lsprof.Profiler.enable() now properly report PySys_Audit() error if «sys.setprofile» or «sys.settrace» audit event is denied.

bpo-39936 [https://bugs.python.org/issue?@action=redirect&bpo=39936]: AIX: Fix _aix_support module when the subprocess is not available, when building Python from scratch. It now uses new private _bootsubprocess module, rather than having two implementations depending if subprocess is available or not. So _aix_support.aix_platform() result is now the same if subprocess is available or not.

bpo-36144 [https://bugs.python.org/issue?@action=redirect&bpo=36144]: collections.OrderedDict now implements | and |= (PEP 584 [https://www.python.org/dev/peps/pep-0584]).

bpo-39652 [https://bugs.python.org/issue?@action=redirect&bpo=39652]: The column name found in sqlite3.Cursor.description is now truncated on the first “[” only if the PARSE_COLNAMES option is set.

bpo-39915 [https://bugs.python.org/issue?@action=redirect&bpo=39915]: Ensure unittest.mock.AsyncMock.await_args_list has call objects in the order of awaited arguments instead of using unittest.mock.Mock.call_args which has the last value of the call. Patch by Karthikeyan Singaravelan.

bpo-36144 [https://bugs.python.org/issue?@action=redirect&bpo=36144]: Updated os.environ and os.environb to support PEP 584 [https://www.python.org/dev/peps/pep-0584]’s merge (|) and update (|=) operators.

bpo-38662 [https://bugs.python.org/issue?@action=redirect&bpo=38662]: The ensurepip module now invokes pip via the runpy module. Hence it is no longer tightly coupled with the internal API of the bundled pip version, allowing easier updates to a newer pip version both internally and for distributors.

bpo-38075 [https://bugs.python.org/issue?@action=redirect&bpo=38075]: Fix the random.Random.seed() method when a bool is passed as the seed.

bpo-39916 [https://bugs.python.org/issue?@action=redirect&bpo=39916]: More reliable use of os.scandir() in Path.glob(). It no longer emits a ResourceWarning when interrupted.

bpo-39850 [https://bugs.python.org/issue?@action=redirect&bpo=39850]: multiprocessing now supports abstract socket addresses (if abstract sockets are supported in the running platform). When creating arbitrary addresses (like when default-constructing multiprocessing.connection.Listener objects) abstract sockets are preferred to avoid the case when the temporary-file-generated address is too large for an AF_UNIX socket address. Patch by Pablo Galindo.

bpo-36287 [https://bugs.python.org/issue?@action=redirect&bpo=36287]: ast.dump() no longer outputs optional fields and attributes with default values. The default values for optional fields and attributes of AST nodes are now set as class attributes (e.g. Constant.kind is set to None).

bpo-39889 [https://bugs.python.org/issue?@action=redirect&bpo=39889]: Fixed ast.unparse() for extended slices containing a single element (e.g. a[i:j,]). Remove redundant tuples when index with a tuple (e.g. a[i, j]).

bpo-39828 [https://bugs.python.org/issue?@action=redirect&bpo=39828]: Fix json.tool to catch BrokenPipeError. Patch by Dong-hee Na.

bpo-13487 [https://bugs.python.org/issue?@action=redirect&bpo=13487]: Avoid a possible «RuntimeError: dictionary changed size during iteration» from inspect.getmodule() when it tried to loop through sys.modules.

bpo-39674 [https://bugs.python.org/issue?@action=redirect&bpo=39674]: Revert «bpo-37330 [https://bugs.python.org/issue?@action=redirect&bpo=37330]: open() no longer accept “U” in file mode». The «U» mode of open() is kept in Python 3.9 to ease transition from Python 2.7, but will be removed in Python 3.10.

bpo-28577 [https://bugs.python.org/issue?@action=redirect&bpo=28577]: The hosts method on 32-bit prefix length IPv4Networks and 128-bit prefix IPv6Networks now returns a list containing the single Address instead of an empty list.

bpo-39826 [https://bugs.python.org/issue?@action=redirect&bpo=39826]: Add getConnection method to logging HTTPHandler to enable custom connections.

bpo-39763 [https://bugs.python.org/issue?@action=redirect&bpo=39763]: Reimplement distutils.spawn.spawn() function with the subprocess module.

bpo-39794 [https://bugs.python.org/issue?@action=redirect&bpo=39794]: Add –without-decimal-contextvar build option. This enables a thread-local rather than a coroutine local context.

bpo-36144 [https://bugs.python.org/issue?@action=redirect&bpo=36144]: collections.defaultdict now implements | (PEP 584 [https://www.python.org/dev/peps/pep-0584]).

bpo-39517 [https://bugs.python.org/issue?@action=redirect&bpo=39517]: Fix runpy.run_path() when using pathlike objects

bpo-39775 [https://bugs.python.org/issue?@action=redirect&bpo=39775]: Change inspect.Signature.parameters back to collections.OrderedDict. This was changed to dict in Python 3.9.0a4.

bpo-39678 [https://bugs.python.org/issue?@action=redirect&bpo=39678]: Refactor queue_manager in concurrent.futures.ProcessPoolExecutor to make it easier to maintain.

bpo-39764 [https://bugs.python.org/issue?@action=redirect&bpo=39764]: Fix AttributeError when calling get_stack on a PyAsyncGenObject Task

bpo-39769 [https://bugs.python.org/issue?@action=redirect&bpo=39769]: The compileall.compile_dir() function’s ddir parameter and the compileall command line flag -d no longer write the wrong pathname to the generated pyc file for submodules beneath the root of the directory tree being compiled. This fixes a regression introduced with Python 3.5.

bpo-36144 [https://bugs.python.org/issue?@action=redirect&bpo=36144]: types.MappingProxyType objects now support the merge (|) operator from PEP 584 [https://www.python.org/dev/peps/pep-0584].

bpo-38691 [https://bugs.python.org/issue?@action=redirect&bpo=38691]: The importlib module now ignores the PYTHONCASEOK environment variable when the -E or -I command line options are being used.

bpo-39719 [https://bugs.python.org/issue?@action=redirect&bpo=39719]: Remove tempfile.SpooledTemporaryFile.softspace() as files no longer have the softspace attribute in Python 3. Patch by Shantanu.

bpo-39667 [https://bugs.python.org/issue?@action=redirect&bpo=39667]: Improve pathlib.Path compatibility on zipfile.Path and correct performance degradation as found in zipp 3.0.

bpo-39638 [https://bugs.python.org/issue?@action=redirect&bpo=39638]: Keep ASDL signatures in the docstrings for AST nodes. Patch by Batuhan Taskaya

bpo-39639 [https://bugs.python.org/issue?@action=redirect&bpo=39639]: Deprecated ast.Suite node class because it’s no longer used. Patch by Batuhan Taskaya.

bpo-39609 [https://bugs.python.org/issue?@action=redirect&bpo=39609]: Add thread_name_prefix to default asyncio executor

bpo-39548 [https://bugs.python.org/issue?@action=redirect&bpo=39548]: Fix handling of header in urllib.request.AbstractDigestAuthHandler when the optional qop parameter is not present.

bpo-39509 [https://bugs.python.org/issue?@action=redirect&bpo=39509]: HTTP status codes 103 EARLY_HINTS and 425 TOO_EARLY are added to http.HTTPStatus. Patch by Dong-hee Na.

bpo-39507 [https://bugs.python.org/issue?@action=redirect&bpo=39507]: Adding HTTP status 418 «I’m a Teapot» to HTTPStatus in http library. Patch by Ross Rhodes.

bpo-39495 [https://bugs.python.org/issue?@action=redirect&bpo=39495]: Remove default value from attrs parameter of xml.etree.ElementTree.TreeBuilder.start() for consistency between Python and C implementations.

bpo-38971 [https://bugs.python.org/issue?@action=redirect&bpo=38971]: Open issue in the BPO indicated a desire to make the implementation of codecs.open() at parity with io.open(), which implements a try/except to assure file stream gets closed before an exception is raised.

bpo-38641 [https://bugs.python.org/issue?@action=redirect&bpo=38641]: Added starred expressions support to return and yield statements for lib2to3. Patch by Vlad Emelianov.

bpo-37534 [https://bugs.python.org/issue?@action=redirect&bpo=37534]: When using minidom module to generate XML documents the ability to add Standalone Document Declaration is added. All the changes are made to generate a document in compliance with Extensible Markup Language (XML) 1.0 (Fifth Edition) W3C Recommendation (available here: https://www.w3.org/TR/xml/#sec-prolog-dtd).

bpo-34788 [https://bugs.python.org/issue?@action=redirect&bpo=34788]: Add support for scoped IPv6 addresses to ipaddress. Patch by Oleksandr Pavliuk.

bpo-34822 [https://bugs.python.org/issue?@action=redirect&bpo=34822]: Simplified AST for subscription. Simple indices are now represented by their value, extended slices are represented as tuples. ast classes Index and ExtSlice are considered deprecated and will be removed in future Python versions. In the meantime, Index(value) now returns a value itself, ExtSlice(slices) returns Tuple(slices, Load()).

Documentation

bpo-39868 [https://bugs.python.org/issue?@action=redirect&bpo=39868]: Updated the Language Reference for PEP 572 [https://www.python.org/dev/peps/pep-0572].

bpo-13790 [https://bugs.python.org/issue?@action=redirect&bpo=13790]: Change “string” to “specification” in format doc.

bpo-17422 [https://bugs.python.org/issue?@action=redirect&bpo=17422]: The language reference no longer restricts default class namespaces to dicts only.

bpo-39530 [https://bugs.python.org/issue?@action=redirect&bpo=39530]: Fix misleading documentation about mixed-type numeric comparisons.

bpo-39718 [https://bugs.python.org/issue?@action=redirect&bpo=39718]: Update token documentation to reflect additions in Python 3.8

bpo-39677 [https://bugs.python.org/issue?@action=redirect&bpo=39677]: Changed operand name of MAKE_FUNCTION from argc to flags for module dis

Tests

bpo-40019 [https://bugs.python.org/issue?@action=redirect&bpo=40019]: test_gdb now skips tests if it detects that gdb failed to read debug information because the Python binary is optimized.

bpo-27807 [https://bugs.python.org/issue?@action=redirect&bpo=27807]: test_site.test_startup_imports() is now skipped if a path of sys.path contains a .pth file.

bpo-26067 [https://bugs.python.org/issue?@action=redirect&bpo=26067]: Do not fail test_shutil test_chown test when uid or gid of user cannot be resolved to a name.

bpo-39855 [https://bugs.python.org/issue?@action=redirect&bpo=39855]: test_subprocess.test_user() now skips the test on an user name if the user name doesn’t exist. For example, skip the test if the user «nobody» doesn’t exist on Linux.

Build

bpo-39761 [https://bugs.python.org/issue?@action=redirect&bpo=39761]: Fix build with DTrace but without additional DFLAGS.

bpo-39763 [https://bugs.python.org/issue?@action=redirect&bpo=39763]: setup.py now uses a basic implementation of the subprocess module if the subprocess module is not available: before required C extension modules are built.

bpo-1294959 [https://bugs.python.org/issue?@action=redirect&bpo=1294959]: Add --with-platlibdir option to the configure script: name of the platform-specific library directory, stored in the new sys.platlibdir attribute. It is used to build the path of platform-specific extension modules and the path of the standard library. It is equal to "lib" on most platforms. On Fedora and SuSE, it is equal to "lib64" on 64-bit platforms. Patch by Jan Matějek, Matěj Cepl, Charalampos Stratakis and Victor Stinner.

Windows

bpo-39930 [https://bugs.python.org/issue?@action=redirect&bpo=39930]: Ensures the required vcruntime140.dll is included in install packages.

bpo-39847 [https://bugs.python.org/issue?@action=redirect&bpo=39847]: Avoid hang when computer is hibernated whilst waiting for a mutex (for lock-related objects from threading) around 49-day uptime.

bpo-38597 [https://bugs.python.org/issue?@action=redirect&bpo=38597]: distutils will no longer statically link vcruntime140.dll when a redistributable version is unavailable. All future releases of CPython will include a copy of this DLL to ensure distributed extensions can continue to load.

bpo-38380 [https://bugs.python.org/issue?@action=redirect&bpo=38380]: Update Windows builds to use SQLite 3.31.1

bpo-39789 [https://bugs.python.org/issue?@action=redirect&bpo=39789]: Update Windows release build machines to Visual Studio 2019 (MSVC 14.2).

bpo-34803 [https://bugs.python.org/issue?@action=redirect&bpo=34803]: Package for nuget.org now includes repository reference and bundled icon image.

macOS

bpo-38380 [https://bugs.python.org/issue?@action=redirect&bpo=38380]: Update macOS builds to use SQLite 3.31.1

IDLE

bpo-27115 [https://bugs.python.org/issue?@action=redirect&bpo=27115]: For “Go to Line”, use a Query box subclass with IDLE standard behavior and improved error checking.

bpo-39885 [https://bugs.python.org/issue?@action=redirect&bpo=39885]: Since clicking to get an IDLE context menu moves the cursor, any text selection should be and now is cleared.

bpo-39852 [https://bugs.python.org/issue?@action=redirect&bpo=39852]: Edit «Go to line» now clears any selection, preventing accidental deletion. It also updates Ln and Col on the status bar.

bpo-39781 [https://bugs.python.org/issue?@action=redirect&bpo=39781]: Selecting code context lines no longer causes a jump.

Tools/Demos

bpo-36184 [https://bugs.python.org/issue?@action=redirect&bpo=36184]: Port python-gdb.py to FreeBSD. python-gdb.py now checks for «take_gil» function name to check if a frame tries to acquire the GIL, instead of checking for «pthread_cond_timedwait» which is specific to Linux and can be a different condition than the GIL.

bpo-38080 [https://bugs.python.org/issue?@action=redirect&bpo=38080]: Added support to fix getproxies in the lib2to3.fixes.fix_urllib module. Patch by José Roberto Meza Cabrera.

C API

bpo-40024 [https://bugs.python.org/issue?@action=redirect&bpo=40024]: Add PyModule_AddType() helper function: add a type to a module. Patch by Dong-hee Na.

bpo-39946 [https://bugs.python.org/issue?@action=redirect&bpo=39946]: Remove _PyRuntime.getframe hook and remove _PyThreadState_GetFrame macro which was an alias to _PyRuntime.getframe. They were only exposed by the internal C API. Remove also PyThreadFrameGetter type.

bpo-39947 [https://bugs.python.org/issue?@action=redirect&bpo=39947]: Add PyThreadState_GetFrame() function: get the current frame of a Python thread state.

bpo-37207 [https://bugs.python.org/issue?@action=redirect&bpo=37207]: Add _PyArg_NoKwnames helper function. Patch by Dong-hee Na.

bpo-39947 [https://bugs.python.org/issue?@action=redirect&bpo=39947]: Add PyThreadState_GetInterpreter(): get the interpreter of a Python thread state.

bpo-39947 [https://bugs.python.org/issue?@action=redirect&bpo=39947]: Add PyInterpreterState_Get() function to the limited C API.

bpo-35370 [https://bugs.python.org/issue?@action=redirect&bpo=35370]: If PySys_Audit() fails in PyEval_SetProfile() or PyEval_SetTrace(), log the error as an unraisable exception.

bpo-39947 [https://bugs.python.org/issue?@action=redirect&bpo=39947]: Move the static inline function flavor of Py_EnterRecursiveCall() and Py_LeaveRecursiveCall() to the internal C API: they access PyThreadState attributes. The limited C API provides regular functions which hide implementation details.

bpo-39947 [https://bugs.python.org/issue?@action=redirect&bpo=39947]: Py_TRASHCAN_BEGIN_CONDITION and Py_TRASHCAN_END macro no longer access PyThreadState attributes, but call new private _PyTrash_begin() and _PyTrash_end() functions which hide implementation details.

bpo-39884 [https://bugs.python.org/issue?@action=redirect&bpo=39884]: PyDescr_NewMethod() and PyCFunction_NewEx() now include the method name in the SystemError «bad call flags» error message to ease debug.

bpo-39877 [https://bugs.python.org/issue?@action=redirect&bpo=39877]: Deprecated PyEval_InitThreads() and PyEval_ThreadsInitialized(). Calling PyEval_InitThreads() now does nothing.

bpo-38249 [https://bugs.python.org/issue?@action=redirect&bpo=38249]: Py_UNREACHABLE is now implemented with __builtin_unreachable() and analogs in release mode.

bpo-38643 [https://bugs.python.org/issue?@action=redirect&bpo=38643]: PyNumber_ToBase() now raises a SystemError instead of crashing when called with invalid base.

bpo-39882 [https://bugs.python.org/issue?@action=redirect&bpo=39882]: The Py_FatalError() function is replaced with a macro which logs automatically the name of the current function, unless the Py_LIMITED_API macro is defined.

bpo-39824 [https://bugs.python.org/issue?@action=redirect&bpo=39824]: Extension modules: m_traverse, m_clear and m_free functions of PyModuleDef are no longer called if the module state was requested but is not allocated yet. This is the case immediately after the module is created and before the module is executed (Py_mod_exec function). More precisely, these functions are not called if m_size is greater than 0 and the module state (as returned by PyModule_GetState()) is NULL.

Extension modules without module state (m_size <= 0) are not affected.

bpo-38913 [https://bugs.python.org/issue?@action=redirect&bpo=38913]: Fixed segfault in Py_BuildValue() called with a format containing «#» and undefined PY_SSIZE_T_CLEAN whwn an exception is set.

bpo-38500 [https://bugs.python.org/issue?@action=redirect&bpo=38500]: Add a private API to get and set the frame evaluation function: add _PyInterpreterState_GetEvalFrameFunc() and _PyInterpreterState_SetEvalFrameFunc() C functions. The _PyFrameEvalFunction function type now takes a tstate parameter.

Python 3.9.0 alpha 4

Release date: 2020-02-25

Security

bpo-39184 [https://bugs.python.org/issue?@action=redirect&bpo=39184]: Add audit events to functions in fcntl, msvcrt, os, resource, shutil, signal and syslog.

bpo-39401 [https://bugs.python.org/issue?@action=redirect&bpo=39401]: Avoid unsafe DLL load at startup on Windows 7 and earlier.

bpo-39184 [https://bugs.python.org/issue?@action=redirect&bpo=39184]: Add audit events to command execution functions in os and pty modules.

Core and Builtins

bpo-39382 [https://bugs.python.org/issue?@action=redirect&bpo=39382]: Fix a use-after-free in the single inheritance path of issubclass(), when the __bases__ of an object has a single reference, and so does its first item. Patch by Yonatan Goldschmidt.

bpo-39573 [https://bugs.python.org/issue?@action=redirect&bpo=39573]: Update clinic tool to use Py_IS_TYPE(). Patch by Dong-hee Na.

bpo-39619 [https://bugs.python.org/issue?@action=redirect&bpo=39619]: Enable use of os.chroot() on HP-UX systems.

bpo-39573 [https://bugs.python.org/issue?@action=redirect&bpo=39573]: Add Py_IS_TYPE() static inline function to check whether the object o type is type.

bpo-39606 [https://bugs.python.org/issue?@action=redirect&bpo=39606]: Fix regression caused by fix for bpo-39386 [https://bugs.python.org/issue?@action=redirect&bpo=39386], that prevented calling aclose on an async generator that had already been closed or exhausted.

bpo-39579 [https://bugs.python.org/issue?@action=redirect&bpo=39579]: Change the ending column offset of Attribute nodes constructed in ast_for_dotted_name to point at the end of the current node and not at the end of the last NAME node.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _crypt extension module to multiphase initialization (PEP 489 [https://www.python.org/dev/peps/pep-0489]).

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _contextvars extension module to multiphase initialization (PEP 489 [https://www.python.org/dev/peps/pep-0489]).

bpo-39510 [https://bugs.python.org/issue?@action=redirect&bpo=39510]: Fix segfault in readinto() method on closed BufferedReader.

bpo-39502 [https://bugs.python.org/issue?@action=redirect&bpo=39502]: Fix time.localtime() on 64-bit AIX to support years before 1902 and after 2038. Patch by M Felt.

bpo-39492 [https://bugs.python.org/issue?@action=redirect&bpo=39492]: Fix a reference cycle in the C Pickler that was preventing the garbage collection of deleted, pickled objects.

bpo-39453 [https://bugs.python.org/issue?@action=redirect&bpo=39453]: Fixed a possible crash in list.__contains__() when a list is changed during comparing items. Patch by Dong-hee Na.

bpo-39434 [https://bugs.python.org/issue?@action=redirect&bpo=39434]: floor division of float operation now has a better performance. Also the message of ZeroDivisionError for this operation is updated. Patch by Dong-hee Na.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _codecs extension module to multiphase initialization (PEP 489 [https://www.python.org/dev/peps/pep-0489]).

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _bz2 extension module to multiphase initialization (PEP 489 [https://www.python.org/dev/peps/pep-0489]).

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _abc extension module to multiphase initialization (PEP 489 [https://www.python.org/dev/peps/pep-0489]).

bpo-39320 [https://bugs.python.org/issue?@action=redirect&bpo=39320]: Replace two complex bytecodes for building dicts with two simpler ones. The new bytecodes DICT_MERGE and DICT_UPDATE have been added The old bytecodes BUILD_MAP_UNPACK and BUILD_MAP_UNPACK_WITH_CALL have been removed.

bpo-39219 [https://bugs.python.org/issue?@action=redirect&bpo=39219]: Syntax errors raised in the tokenizer now always set correct «text» and «offset» attributes.

bpo-36051 [https://bugs.python.org/issue?@action=redirect&bpo=36051]: Drop the GIL during large bytes.join operations. Patch by Bruce Merry.

bpo-38960 [https://bugs.python.org/issue?@action=redirect&bpo=38960]: Fix DTrace build issues on FreeBSD. Patch by David Carlier.

bpo-37207 [https://bugs.python.org/issue?@action=redirect&bpo=37207]: Speed up calls to range() by about 30%, by using the PEP 590 vectorcall calling convention. Patch by Mark Shannon.

bpo-36144 [https://bugs.python.org/issue?@action=redirect&bpo=36144]: dict (and collections.UserDict) objects now support PEP 584’s merge (|) and update (|=) operators. Patch by Brandt Bucher.

bpo-32856 [https://bugs.python.org/issue?@action=redirect&bpo=32856]: Optimized the idiom for assignment a temporary variable in comprehensions. Now for y in [expr] in comprehensions is as fast as a simple assignment y = expr.

Library

bpo-30566 [https://bugs.python.org/issue?@action=redirect&bpo=30566]: Fix IndexError when trying to decode an invalid string with punycode codec.

bpo-39649 [https://bugs.python.org/issue?@action=redirect&bpo=39649]: Remove obsolete check for __args__ in bdb.Bdb.format_stack_entry.

bpo-39648 [https://bugs.python.org/issue?@action=redirect&bpo=39648]: Expanded math.gcd() and math.lcm() to handle multiple arguments.

bpo-39681 [https://bugs.python.org/issue?@action=redirect&bpo=39681]: Fix a regression where the C pickle module wouldn’t allow unpickling from a file-like object that doesn’t expose a readinto() method.

bpo-35950 [https://bugs.python.org/issue?@action=redirect&bpo=35950]: Raise io.UnsupportedOperation in io.BufferedReader.truncate() when it is called on a read-only io.BufferedReader instance.

bpo-39479 [https://bugs.python.org/issue?@action=redirect&bpo=39479]: Add math.lcm() function: least common multiple.

bpo-39674 [https://bugs.python.org/issue?@action=redirect&bpo=39674]: Revert «Do not expose abstract collection classes in the collections module» change (bpo-25988 [https://bugs.python.org/issue?@action=redirect&bpo=25988]). Aliases to ABC like collections.Mapping are kept in Python 3.9 to ease transition from Python 2.7, but will be removed in Python 3.10.

bpo-39104 [https://bugs.python.org/issue?@action=redirect&bpo=39104]: Fix hanging ProcessPoolExcutor on shutdown(wait=False) when a task has failed pickling.

bpo-39627 [https://bugs.python.org/issue?@action=redirect&bpo=39627]: Fixed TypedDict totality check for inherited keys.

bpo-39474 [https://bugs.python.org/issue?@action=redirect&bpo=39474]: Fixed starting position of AST for expressions like (a)(b), (a)[b] and (a).b.

bpo-21016 [https://bugs.python.org/issue?@action=redirect&bpo=21016]: The pydoc and trace modules now use the sysconfig module to get the path to the Python standard library, to support uncommon installation path like /usr/lib64/python3.9/ on Fedora. Patch by Jan Matějek.

bpo-39590 [https://bugs.python.org/issue?@action=redirect&bpo=39590]: Collections.deque now holds strong references during deque.__contains__ and deque.count, fixing crashes.

bpo-39586 [https://bugs.python.org/issue?@action=redirect&bpo=39586]: The distutils bdist_msi command is deprecated in Python 3.9, use bdist_wheel (wheel packages) instead.

bpo-39595 [https://bugs.python.org/issue?@action=redirect&bpo=39595]: Improved performance of zipfile.Path for files with a large number of entries. Also improved performance and fixed minor issue as published with importlib_metadata 1.5 [https://importlib-metadata.readthedocs.io/en/latest/changelog%20(links).html#v1-5-0].

bpo-39350 [https://bugs.python.org/issue?@action=redirect&bpo=39350]: Fix regression in fractions.Fraction if the numerator and/or the denominator is an int subclass. The math.gcd() function is now used to normalize the numerator and denominator. math.gcd() always return a int type. Previously, the GCD type depended on numerator and denominator.

bpo-39567 [https://bugs.python.org/issue?@action=redirect&bpo=39567]: Added audit for os.walk(), os.fwalk(), pathlib.Path.glob() and pathlib.Path.rglob().

bpo-39559 [https://bugs.python.org/issue?@action=redirect&bpo=39559]: Remove unused, undocumented argument getters from uuid.getnode()

bpo-38149 [https://bugs.python.org/issue?@action=redirect&bpo=38149]: sys.audit() is now called only once per call of glob.glob() and glob.iglob().

bpo-39546 [https://bugs.python.org/issue?@action=redirect&bpo=39546]: Fix a regression in ArgumentParser where allow_abbrev=False was ignored for long options that used a prefix character other than «-«.

bpo-39450 [https://bugs.python.org/issue?@action=redirect&bpo=39450]: Striped whitespace from docstring before returning it from unittest.case.shortDescription().

bpo-12915 [https://bugs.python.org/issue?@action=redirect&bpo=12915]: A new function resolve_name has been added to the pkgutil module. This resolves a string of the form 'a.b.c.d' or 'a.b:c.d' to an object. In the example, a.b is a package/module and c.d is an object within that package/module reached via recursive attribute access.

bpo-39353 [https://bugs.python.org/issue?@action=redirect&bpo=39353]: The binascii.crc_hqx() function is no longer deprecated.

bpo-39493 [https://bugs.python.org/issue?@action=redirect&bpo=39493]: Mark typing.IO.closed as a property

bpo-39491 [https://bugs.python.org/issue?@action=redirect&bpo=39491]: Add typing.Annotated and include_extras parameter to typing.get_type_hints() as part of PEP 593 [https://www.python.org/dev/peps/pep-0593]. Patch by Till Varoquaux, documentation by Till Varoquaux and Konstantin Kashin.

bpo-39485 [https://bugs.python.org/issue?@action=redirect&bpo=39485]: Fix a bug in unittest.mock.create_autospec() that would complain about the wrong number of arguments for custom descriptors defined in an extension module returning functions.

bpo-38932 [https://bugs.python.org/issue?@action=redirect&bpo=38932]: Mock fully resets child objects on reset_mock(). Patch by Vegard Stikbakke

bpo-39082 [https://bugs.python.org/issue?@action=redirect&bpo=39082]: Allow AsyncMock to correctly patch static/class methods

bpo-39432 [https://bugs.python.org/issue?@action=redirect&bpo=39432]: Implement PEP-489 algorithm for non-ascii «PyInit_…» symbol names in distutils to make it export the correct init symbol also on Windows.

bpo-18819 [https://bugs.python.org/issue?@action=redirect&bpo=18819]: Omit devmajor and devminor fields for non-device files in tarfile archives, enabling bit-for-bit compatibility with GNU tar(1).

bpo-39349 [https://bugs.python.org/issue?@action=redirect&bpo=39349]: Added a new cancel_futures parameter to concurrent.futures.Executor.shutdown() that cancels all pending futures which have not started running, instead of waiting for them to complete before shutting down the executor.

bpo-39274 [https://bugs.python.org/issue?@action=redirect&bpo=39274]: bool(fraction.Fraction) now returns a boolean even if (numerator != 0) does not return a boolean (ex: numpy number).

bpo-34793 [https://bugs.python.org/issue?@action=redirect&bpo=34793]: Remove support for with (await asyncio.lock): and with (yield from asyncio.lock):. The same is correct for asyncio.Condition and asyncio.Semaphore.

bpo-25597 [https://bugs.python.org/issue?@action=redirect&bpo=25597]: Ensure, if wraps is supplied to unittest.mock.MagicMock, it is used to calculate return values for the magic methods instead of using the default return values. Patch by Karthikeyan Singaravelan.

bpo-36350 [https://bugs.python.org/issue?@action=redirect&bpo=36350]: inspect.Signature.parameters and inspect.BoundArguments.arguments are now dicts instead of OrderedDicts. Patch contributed by Rémi Lapeyre.

bpo-35727 [https://bugs.python.org/issue?@action=redirect&bpo=35727]: Fix sys.exit() and sys.exit(None) exit code propagation when used in multiprocessing.Process.

bpo-32173 [https://bugs.python.org/issue?@action=redirect&bpo=32173]: * Add lazycache function to __all__. * Use dict.clear to clear the cache. * Refactoring getline function and checkcache function.

Documentation

bpo-17422 [https://bugs.python.org/issue?@action=redirect&bpo=17422]: The language reference now specifies restrictions on class namespaces. Adapted from a patch by Ethan Furman.

bpo-39572 [https://bugs.python.org/issue?@action=redirect&bpo=39572]: Updated documentation of total flag of TypedDict.

bpo-39654 [https://bugs.python.org/issue?@action=redirect&bpo=39654]: In pyclbr doc, update “class” to “module” where appropriate and add readmodule comment. Patch by Hakan Çelik.

bpo-39153 [https://bugs.python.org/issue?@action=redirect&bpo=39153]: Clarify refcounting semantics for the following functions: - PyObject_SetItem - PyMapping_SetItemString - PyDict_SetItem - PyDict_SetItemString

bpo-39392 [https://bugs.python.org/issue?@action=redirect&bpo=39392]: Explain that when filling with turtle, overlap regions may be left unfilled.

bpo-39369 [https://bugs.python.org/issue?@action=redirect&bpo=39369]: Update mmap readline method description. The fact that the readline method does update the file position should not be ignored since this might give the impression for the programmer that it doesn’t update it.

bpo-9056 [https://bugs.python.org/issue?@action=redirect&bpo=9056]: Include subsection in TOC for PDF version of docs.

Tests

bpo-38325 [https://bugs.python.org/issue?@action=redirect&bpo=38325]: Skip tests on non-BMP characters of test_winconsoleio.

bpo-39502 [https://bugs.python.org/issue?@action=redirect&bpo=39502]: Skip test_zipfile.test_add_file_after_2107() if time.localtime() fails with OverflowError. It is the case on AIX 6.1 for example.

Build

bpo-39489 [https://bugs.python.org/issue?@action=redirect&bpo=39489]: Remove COUNT_ALLOCS special build.

Windows

bpo-39553 [https://bugs.python.org/issue?@action=redirect&bpo=39553]: Delete unused code related to SxS manifests.

bpo-39439 [https://bugs.python.org/issue?@action=redirect&bpo=39439]: Honor the Python path when a virtualenv is active on Windows.

bpo-39393 [https://bugs.python.org/issue?@action=redirect&bpo=39393]: Improve the error message when attempting to load a DLL with unresolved dependencies.

bpo-38883 [https://bugs.python.org/issue?@action=redirect&bpo=38883]: home() and expanduser() on Windows now prefer USERPROFILE and no longer use HOME, which is not normally set for regular user accounts. This makes them again behave like os.path.expanduser(), which was changed to ignore HOME in 3.8, see bpo-36264 [https://bugs.python.org/issue?@action=redirect&bpo=36264].

bpo-39185 [https://bugs.python.org/issue?@action=redirect&bpo=39185]: The build.bat script has additional options for very-quiet output (-q) and very-verbose output (-vv)

IDLE

bpo-39663 [https://bugs.python.org/issue?@action=redirect&bpo=39663]: Add tests for pyparse find_good_parse_start().

bpo-39600 [https://bugs.python.org/issue?@action=redirect&bpo=39600]: In the font configuration window, remove duplicated font names.

bpo-30780 [https://bugs.python.org/issue?@action=redirect&bpo=30780]: Add remaining configdialog tests for buttons and highlights and keys tabs.

bpo-39388 [https://bugs.python.org/issue?@action=redirect&bpo=39388]: IDLE Settings Cancel button now cancels pending changes

bpo-38792 [https://bugs.python.org/issue?@action=redirect&bpo=38792]: Close an IDLE shell calltip if a KeyboardInterrupt or shell restart occurs. Patch by Zackery Spytz.

C API

bpo-35081 [https://bugs.python.org/issue?@action=redirect&bpo=35081]: Move the bytes_methods.h header file to the internal C API as pycore_bytes_methods.h: it only contains private symbols (prefixed by _Py), except of the PyDoc_STRVAR_shared() macro.

bpo-35081 [https://bugs.python.org/issue?@action=redirect&bpo=35081]: Move the dtoa.h header file to the internal C API as pycore_dtoa.h: it only contains private functions (prefixed by _Py). The math and cmath modules must now be compiled with the Py_BUILD_CORE macro defined.

bpo-39573 [https://bugs.python.org/issue?@action=redirect&bpo=39573]: Add Py_SET_SIZE() function to set the size of an object.

bpo-39500 [https://bugs.python.org/issue?@action=redirect&bpo=39500]: PyUnicode_IsIdentifier() does not call Py_FatalError() anymore if the string is not ready.

bpo-39573 [https://bugs.python.org/issue?@action=redirect&bpo=39573]: Add Py_SET_TYPE() function to set the type of an object.

bpo-39573 [https://bugs.python.org/issue?@action=redirect&bpo=39573]: Add a Py_SET_REFCNT() function to set the reference counter of an object.

bpo-39542 [https://bugs.python.org/issue?@action=redirect&bpo=39542]: Convert PyType_HasFeature(), PyType_Check() and PyType_CheckExact() macros to static inline functions.

bpo-39542 [https://bugs.python.org/issue?@action=redirect&bpo=39542]: In the limited C API, PyObject_INIT() and PyObject_INIT_VAR() are now defined as aliases to PyObject_Init() and PyObject_InitVar() to make their implementation opaque. It avoids to leak implementation details in the limited C API. Exclude the following functions from the limited C API: _Py_NewReference(), _Py_ForgetReference(), _PyTraceMalloc_NewReference() and _Py_GetRefTotal().

bpo-39542 [https://bugs.python.org/issue?@action=redirect&bpo=39542]: Exclude trashcan mechanism from the limited C API: it requires access to PyTypeObject and PyThreadState structure fields, whereas these structures are opaque in the limited C API.

bpo-39511 [https://bugs.python.org/issue?@action=redirect&bpo=39511]: The PyThreadState_Clear() function now calls the PyThreadState.on_delete callback. Previously, that happened in PyThreadState_Delete().

bpo-38076 [https://bugs.python.org/issue?@action=redirect&bpo=38076]: Fix to clear the interpreter state only after clearing module globals to guarantee module state access from C Extensions during runtime destruction

bpo-39245 [https://bugs.python.org/issue?@action=redirect&bpo=39245]: The Vectorcall API (PEP 590) was made public, adding the functions PyObject_Vectorcall, PyObject_VectorcallMethod, PyVectorcall_Function, PyObject_CallOneArg, PyObject_CallMethodNoArgs, PyObject_CallMethodOneArg, PyObject_FastCallDict, and the flag Py_TPFLAGS_HAVE_VECTORCALL.

Python 3.9.0 alpha 3

Release date: 2020-01-24

Core and Builtins

bpo-39427 [https://bugs.python.org/issue?@action=redirect&bpo=39427]: Document all possibilities for the -X options in the command line help section. Patch by Pablo Galindo.

bpo-39421 [https://bugs.python.org/issue?@action=redirect&bpo=39421]: Fix possible crashes when operating with the functions in the heapq module and custom comparison operators.

bpo-39386 [https://bugs.python.org/issue?@action=redirect&bpo=39386]: Prevent double awaiting of async iterator.

bpo-17005 [https://bugs.python.org/issue?@action=redirect&bpo=17005]: Add functools.TopologicalSorter to the functools module to offers functionality to perform topological sorting of graphs. Patch by Pablo Galindo, Tim Peters and Larry Hastings.

bpo-39320 [https://bugs.python.org/issue?@action=redirect&bpo=39320]: Replace four complex bytecodes for building sequences with three simpler ones.

The following four bytecodes have been removed:

BUILD_LIST_UNPACK

BUILD_TUPLE_UNPACK

BUILD_SET_UNPACK

BUILD_TUPLE_UNPACK_WITH_CALL

The following three bytecodes have been added:

LIST_TO_TUPLE

LIST_EXTEND

SET_UPDATE

bpo-39336 [https://bugs.python.org/issue?@action=redirect&bpo=39336]: Import loaders which publish immutable module objects can now publish immutable packages in addition to individual modules.

bpo-39322 [https://bugs.python.org/issue?@action=redirect&bpo=39322]: Added a new function gc.is_finalized() to check if an object has been finalized by the garbage collector. Patch by Pablo Galindo.

bpo-39048 [https://bugs.python.org/issue?@action=redirect&bpo=39048]: Improve the displayed error message when incorrect types are passed to async with statements by looking up the __aenter__() special method before the __aexit__() special method when entering an asynchronous context manager. Patch by Géry Ogam.

bpo-39235 [https://bugs.python.org/issue?@action=redirect&bpo=39235]: Fix AST end location for lone generator expression in function call, e.g. f(i for i in a).

bpo-39209 [https://bugs.python.org/issue?@action=redirect&bpo=39209]: Correctly handle multi-line tokens in interactive mode. Patch by Pablo Galindo.

bpo-1635741 [https://bugs.python.org/issue?@action=redirect&bpo=1635741]: Port _json extension module to multiphase initialization (PEP 489 [https://www.python.org/dev/peps/pep-0489]).

bpo-39216 [https://bugs.python.org/issue?@action=redirect&bpo=39216]: Fix constant folding optimization for positional only arguments - by Anthony Sottile.

bpo-39215 [https://bugs.python.org/issue?@action=redirect&bpo=39215]: Fix SystemError when nested function has annotation on positional-only argument - by Anthony Sottile.

bpo-39200 [https://bugs.python.org/issue?@action=redirect&bpo=39200]: Correct the error message when calling the min() or max() with no arguments. Patch by Dong-hee Na.

bpo-39200 [https://bugs.python.org/issue?@action=redirect&bpo=39200]: Correct the error message when trying to construct range objects with no arguments. Patch by Pablo Galindo.

bpo-39166 [https://bugs.python.org/issue?@action=redirect&bpo=39166]: Fix incorrect line execution reporting in trace functions when tracing the last iteration of asynchronous for loops. Patch by Pablo Galindo.

bpo-39114 [https://bugs.python.org/issue?@action=redirect&bpo=39114]: Fix incorrect line execution reporting in trace functions when tracing exception handlers with name binding. Patch by Pablo Galindo.

bpo-39156 [https://bugs.python.org/issue?@action=redirect&bpo=39156]: Split the COMPARE_OP bytecode instruction into four distinct instructions.

COMPARE_OP for rich comparisons

IS_OP for “is” and “is not” tests

CONTAINS_OP for “in” and “is not” tests

JUMP_IF_NOT_EXC_MATCH for checking exceptions in “try-except” statements.

This improves the clarity of the interpreter and should provide a modest speedup.

bpo-38588 [https://bugs.python.org/issue?@action=redirect&bpo=38588]: Fix possible crashes in dict and list when calling PyObject_RichCompareBool().

bpo-13601 [https://bugs.python.org/issue?@action=redirect&bpo=13601]: By default, sys.stderr is line-buffered now, even if stderr is redirected to a file. You can still make sys.stderr unbuffered by passing the -u command-line option or setting the PYTHONUNBUFFERED environment variable.

(Contributed by Jendrik Seipp in bpo-13601 [https://bugs.python.org/issue?@action=redirect&bpo=13601].)

bpo-38610 [https://bugs.python.org/issue?@action=redirect&bpo=38610]: Fix possible crashes in several list methods by holding strong references to list elements when calling PyObject_RichCompareBool().

bpo-32021 [https://bugs.python.org/issue?@action=redirect&bpo=32021]: Include brotli .br encoding in mimetypes encodings_map

Library

bpo-39430 [https://bugs.python.org/issue?@action=redirect&bpo=39430]: Fixed race condition in lazy imports in tarfile.

bpo-39413 [https://bugs.python.org/issue?@action=redirect&bpo=39413]: The os.unsetenv() function is now also available on Windows.

bpo-39390 [https://bugs.python.org/issue?@action=redirect&bpo=39390]: Fixed a regression with the ignore callback of shutil.copytree(). The argument types are now str and List[str] again.

bpo-39395 [https://bugs.python.org/issue?@action=redirect&bpo=39395]: The os.putenv() and os.unsetenv() functions are now always available.

bpo-39406 [https://bugs.python.org/issue?@action=redirect&bpo=39406]: If setenv() C function is available, os.putenv() is now implemented with setenv() instead of putenv(), so Python doesn’t have to handle the environment variable memory.

bpo-39396 [https://bugs.python.org/issue?@action=redirect&bpo=39396]: Fix math.nextafter(-0.0, +0.0) on AIX 7.1.

bpo-29435 [https://bugs.python.org/issue?@action=redirect&bpo=29435]: Allow tarfile.is_tarfile() to be used with file and file-like objects, like zipfile.is_zipfile(). Patch by William Woodruff.

bpo-39377 [https://bugs.python.org/issue?@action=redirect&bpo=39377]: Removed encoding option from json.loads(). It has been deprecated since Python 3.1.

bpo-39389 [https://bugs.python.org/issue?@action=redirect&bpo=39389]: Write accurate compression level metadata in gzip archives, rather than always signaling maximum compression.

bpo-39366 [https://bugs.python.org/issue?@action=redirect&bpo=39366]: The previously deprecated xpath() and xgtitle() methods of nntplib.NNTP have been removed.

bpo-39357 [https://bugs.python.org/issue?@action=redirect&bpo=39357]: Remove the buffering parameter of bz2.BZ2File. Since Python 3.0, it was ignored and using it was emitting DeprecationWarning. Pass an open file object, to control how the file is opened. The compresslevel parameter becomes keyword-only.

bpo-39353 [https://bugs.python.org/issue?@action=redirect&bpo=39353]: Deprecate binhex4 and hexbin4 standards. Deprecate the binhex module and the following binascii functions: b2a_hqx(), a2b_hqx(), rlecode_hqx(), rledecode_hqx(), crc_hqx().

bpo-39351 [https://bugs.python.org/issue?@action=redirect&bpo=39351]: Remove base64.encodestring() and base64.decodestring(), aliases deprecated since Python 3.1: use base64.encodebytes() and base64.decodebytes() instead.

bpo-39350 [https://bugs.python.org/issue?@action=redirect&bpo=39350]: Remove fractions.gcd() function, deprecated since Python 3.5 (bpo-22486 [https://bugs.python.org/issue?@action=redirect&bpo=22486]): use math.gcd() instead.

bpo-39329 [https://bugs.python.org/issue?@action=redirect&bpo=39329]: LMTP constructor now has an optional timeout parameter. Patch by Dong-hee Na.

bpo-39313 [https://bugs.python.org/issue?@action=redirect&bpo=39313]: Add a new exec_function option (–exec-function in the CLI) to RefactoringTool for making exec a function. Patch by Batuhan Taskaya.

bpo-39259 [https://bugs.python.org/issue?@action=redirect&bpo=39259]: FTP_TLS and FTP_TLS now raise a ValueError if the given timeout for their constructor is zero to prevent the creation of a non-blocking socket. Patch by Dong-hee Na.

bpo-39259 [https://bugs.python.org/issue?@action=redirect&bpo=39259]: SMTP and SMTP_SSL now raise a ValueError if the given timeout for their constructor is zero to prevent the creation of a non-blocking socket. Patch by Dong-hee Na.

bpo-39310 [https://bugs.python.org/issue?@action=redirect&bpo=39310]: Add math.ulp(): return the value of the least significant bit of a float.

bpo-39297 [https://bugs.python.org/issue?@action=redirect&bpo=39297]: Improved performance of importlib.metadata distribution discovery and resilients to inaccessible sys.path entries (importlib_metadata v1.4.0).

bpo-39259 [https://bugs.python.org/issue?@action=redirect&bpo=39259]: NNTP and NNTP_SSL now raise a ValueError if the given timeout for their constructor is zero to prevent the creation of a non-blocking socket. Patch by Dong-hee Na.

bpo-38901 [https://bugs.python.org/issue?@action=redirect&bpo=38901]: When you specify prompt=”.” or equivalently python -m venv –prompt . … the basename of the current directory is used to set the created venv’s prompt when it’s activated.

bpo-39288 [https://bugs.python.org/issue?@action=redirect&bpo=39288]: Add math.nextafter(): return the next floating-point value after x towards y.

bpo-39259 [https://bugs.python.org/issue?@action=redirect&bpo=39259]: POP3 and POP3_SSL now raise a ValueError if the given timeout for their constructor is zero to prevent the creation of a non-blocking socket. Patch by Dong-hee Na.

bpo-39242 [https://bugs.python.org/issue?@action=redirect&bpo=39242]: Updated the Gmane domain from news.gmane.org to news.gmane.io which is used for examples of NNTP news reader server and nntplib tests.

bpo-35292 [https://bugs.python.org/issue?@action=redirect&bpo=35292]: Proxy the SimpleHTTPRequestHandler.guess_type to mimetypes.guess_type so the mimetypes.init is called lazily to avoid unnecessary costs when http.server module is imported.

bpo-39239 [https://bugs.python.org/issue?@action=redirect&bpo=39239]: The select.epoll.unregister() method no longer ignores the EBADF error.

bpo-38907 [https://bugs.python.org/issue?@action=redirect&bpo=38907]: In http.server script, restore binding to IPv4 on Windows.

bpo-39152 [https://bugs.python.org/issue?@action=redirect&bpo=39152]: Fix ttk.Scale.configure([name]) to return configuration tuple for name or all options. Giovanni Lombardo contributed part of the patch.

bpo-39198 [https://bugs.python.org/issue?@action=redirect&bpo=39198]: If an exception were to be thrown in Logger.isEnabledFor (say, by asyncio timeouts or stopit) , the logging global lock may not be released appropriately, resulting in deadlock. This change wraps that block of code with try...finally to ensure the lock is released.

bpo-39191 [https://bugs.python.org/issue?@action=redirect&bpo=39191]: Perform a check for running loop before starting a new task in loop.run_until_complete() to fail fast; it prevents the side effect of new task spawning before exception raising.

bpo-38871 [https://bugs.python.org/issue?@action=redirect&bpo=38871]: Correctly parenthesize filter-based statements that contain lambda expressions in mod:lib2to3. Patch by Dong-hee Na.

bpo-39142 [https://bugs.python.org/issue?@action=redirect&bpo=39142]: A change was made to logging.config.dictConfig to avoid converting instances of named tuples to ConvertingTuple. It’s assumed that named tuples are too specialised to be treated like ordinary tuples; if a user of named tuples requires ConvertingTuple functionality, they will have to implement that themselves in their named tuple class.

bpo-39158 [https://bugs.python.org/issue?@action=redirect&bpo=39158]: ast.literal_eval() now supports empty sets.

bpo-39129 [https://bugs.python.org/issue?@action=redirect&bpo=39129]: Fix import path for asyncio.TimeoutError

bpo-39057 [https://bugs.python.org/issue?@action=redirect&bpo=39057]: urllib.request.proxy_bypass_environment() now ignores leading dots and no longer ignores a trailing newline.

bpo-39056 [https://bugs.python.org/issue?@action=redirect&bpo=39056]: Fixed handling invalid warning category in the -W option. No longer import the re module if it is not needed.

bpo-39055 [https://bugs.python.org/issue?@action=redirect&bpo=39055]: base64.b64decode() with validate=True raises now a binascii.Error if the input ends with a single \n.

bpo-21600 [https://bugs.python.org/issue?@action=redirect&bpo=21600]: Fix mock.patch.stopall() to stop active patches that were created with mock.patch.dict().

bpo-39019 [https://bugs.python.org/issue?@action=redirect&bpo=39019]: Implement dummy __class_getitem__ for tempfile.SpooledTemporaryFile.

bpo-39019 [https://bugs.python.org/issue?@action=redirect&bpo=39019]: Implement dummy __class_getitem__ for subprocess.Popen, subprocess.CompletedProcess

bpo-38914 [https://bugs.python.org/issue?@action=redirect&bpo=38914]: Adjusted the wording of the warning issued by distutils” check command when the author and maintainer fields are supplied but no corresponding e-mail field (author_email or maintainer_email) is found. The wording now reflects the fact that these fields are suggested, but not required. Patch by Juergen Gmach.

bpo-38878 [https://bugs.python.org/issue?@action=redirect&bpo=38878]: Fixed __subclasshook__ of os.PathLike to return a correct result upon inheritance. Patch by Bar Harel.

bpo-38615 [https://bugs.python.org/issue?@action=redirect&bpo=38615]: IMAP4 and IMAP4_SSL now have an optional timeout parameter for their constructors. Also, the open() method now has an optional timeout parameter with this change. The overridden methods of IMAP4_SSL and IMAP4_stream were applied to this change. Patch by Dong-hee Na.

bpo-35182 [https://bugs.python.org/issue?@action=redirect&bpo=35182]: Fixed Popen.communicate() subsequent call crash when the child process has already closed any piped standard stream, but still continues to be running. Patch by Andriy Maletsky.

bpo-38630 [https://bugs.python.org/issue?@action=redirect&bpo=38630]: On Unix, subprocess.Popen.send_signal() now polls the process status. Polling reduces the risk of sending a signal to the wrong process if the process completed, the subprocess.Popen.returncode attribute is still None, and the pid has been reassigned (recycled) to a new different process.

bpo-38536 [https://bugs.python.org/issue?@action=redirect&bpo=38536]: Removes trailing space in formatted currency with international=True and a locale with symbol following value. E.g. locale.currency(12.34, international=True) returned '12,34 EUR ' instead of '12,34 EUR'.

bpo-38473 [https://bugs.python.org/issue?@action=redirect&bpo=38473]: Use signature from inner mock for autospecced methods attached with unittest.mock.attach_mock(). Patch by Karthikeyan Singaravelan.

bpo-38361 [https://bugs.python.org/issue?@action=redirect&bpo=38361]: Fixed an issue where ident could include a leading path separator when syslog.openlog() was called without arguments.

bpo-38293 [https://bugs.python.org/issue?@action=redirect&bpo=38293]: Add copy.copy() and copy.deepcopy() support to property() objects.

bpo-37958 [https://bugs.python.org/issue?@action=redirect&bpo=37958]: Added the pstats.Stats.get_profile_dict() method to return the profile data as a StatsProfile instance.

bpo-28367 [https://bugs.python.org/issue?@action=redirect&bpo=28367]: Termios magic constants for the following baud rates: - B500000 - B576000 - B921600 - B1000000 - B1152000 - B1500000 - B2000000 - B2500000 - B3000000 - B3500000 - B4000000 Patch by Andrey Smirnov

Documentation

bpo-39381 [https://bugs.python.org/issue?@action=redirect&bpo=39381]: Mention in docs that asyncio.get_event_loop() implicitly creates new event loop only if called from the main thread.

bpo-38918 [https://bugs.python.org/issue?@action=redirect&bpo=38918]: Add an entry for __module__ in the «function» & «method» sections of the inspect docs types and members table [https://docs.python.org/3/library/inspect.html#types-and-members]

bpo-3530 [https://bugs.python.org/issue?@action=redirect&bpo=3530]: In the ast module documentation, fix a misleading NodeTransformer example and add advice on when to use the fix_missing_locations function.

Build

bpo-39395 [https://bugs.python.org/issue?@action=redirect&bpo=39395]: On non-Windows platforms, the setenv() and unsetenv() functions are now required to build Python.

bpo-39160 [https://bugs.python.org/issue?@action=redirect&bpo=39160]: Updated the documentation in /configure --help to show default values, reference documentation where required and add additional explanation where needed.

bpo-39144 [https://bugs.python.org/issue?@action=redirect&bpo=39144]: The ctags and etags build targets both include Modules/_ctypes and Python standard library source files.

IDLE

bpo-39050 [https://bugs.python.org/issue?@action=redirect&bpo=39050]: Make IDLE Settings dialog Help button work again.

bpo-34118 [https://bugs.python.org/issue?@action=redirect&bpo=34118]: Tag memoryview, range, and tuple as classes, the same as list, etcetera, in the library manual built-in functions list.

bpo-32989 [https://bugs.python.org/issue?@action=redirect&bpo=32989]: Add tests for editor newline_and_indent_event method. Remove dead code from pyparse find_good_parse_start method.

C API

bpo-39372 [https://bugs.python.org/issue?@action=redirect&bpo=39372]: Clean header files of interfaces defined but with no implementation. The public API symbols being removed are: _PyBytes_InsertThousandsGroupingLocale, _PyBytes_InsertThousandsGrouping, _Py_InitializeFromArgs, _Py_InitializeFromWideArgs, _PyFloat_Repr, _PyFloat_Digits, _PyFloat_DigitsInit, PyFrame_ExtendStack, _PyAIterWrapper_Type, PyNullImporter_Type, PyCmpWrapper_Type, PySortWrapper_Type, PyNoArgsFunction.

bpo-39164 [https://bugs.python.org/issue?@action=redirect&bpo=39164]: Add a private _PyErr_GetExcInfo() function to retrieve exception information of the specified Python thread state.

Python 3.9.0 alpha 2

Release date: 2019-12-18

Security

bpo-38945 [https://bugs.python.org/issue?@action=redirect&bpo=38945]: Newline characters have been escaped when performing uu encoding to prevent them from overflowing into to content section of the encoded file. This prevents malicious or accidental modification of data during the decoding process.

bpo-37228 [https://bugs.python.org/issue?@action=redirect&bpo=37228]: Due to significant security concerns, the reuse_address parameter of asyncio.loop.create_datagram_endpoint() is no longer supported. This is because of the behavior of SO_REUSEADDR in UDP. For more details, see the documentation for loop.create_datagram_endpoint(). (Contributed by Kyle Stanley, Antoine Pitrou, and Yury Selivanov in bpo-37228 [https://bugs.python.org/issue?@action=redirect&bpo=37228].)

bpo-38804 [https://bugs.python.org/issue?@action=redirect&bpo=38804]: Fixes a ReDoS vulnerability in http.cookiejar. Patch by Ben Caller.

Core and Builtins

bpo-39028 [https://bugs.python.org/issue?@action=redirect&bpo=39028]: Slightly improve the speed of keyword argument parsing with many kwargs by strengthening the assumption that kwargs are interned strings.

bpo-39080 [https://bugs.python.org/issue?@action=redirect&bpo=39080]: Fix the value of end_col_offset for Starred Expression AST nodes when they are among the elements in the args attribute of Call AST nodes.

bpo-39031 [https://bugs.python.org/issue?@action=redirect&bpo=39031]: When parsing an «elif» node, lineno and col_offset of the node now point to the «elif» keyword and not to its condition, making it consistent with the «if» node. Patch by Lysandros Nikolaou.

bpo-20443 [https://bugs.python.org/issue?@action=redirect&bpo=20443]: In Python 3.9.0a1, sys.argv[0] was made an absolute path if a filename was specified on the command line. Revert this change, since most users expect sys.argv to be unmodified.

bpo-39008 [https://bugs.python.org/issue?@action=redirect&bpo=39008]: PySys_Audit() now requires Py_ssize_t to be used for size arguments in the format string, regardless of whether PY_SSIZE_T_CLEAN was defined at include time.

bpo-38673 [https://bugs.python.org/issue?@action=redirect&bpo=38673]: In REPL mode, don’t switch to PS2 if the line starts with comment or whitespace. Based on work by Batuhan Taşkaya.

bpo-38922 [https://bugs.python.org/issue?@action=redirect&bpo=38922]: Calling replace on a code object now raises the code.__new__ audit event.

bpo-38920 [https://bugs.python.org/issue?@action=redirect&bpo=38920]: Add audit hooks for when sys.excepthook() and sys.unraisablehook() are invoked.

bpo-38892 [https://bugs.python.org/issue?@action=redirect&bpo=38892]: Improve documentation for audit events table and functions.

bpo-38852 [https://bugs.python.org/issue?@action=redirect&bpo=38852]: Set the thread stack size to 8 Mb for debug builds on android platforms.

bpo-38858 [https://bugs.python.org/issue?@action=redirect&bpo=38858]: Each Python subinterpreter now has its own «small integer singletons»: numbers in [-5; 257] range. It is no longer possible to change the number of small integers at build time by overriding NSMALLNEGINTS and NSMALLPOSINTS macros: macros should now be modified manually in pycore_pystate.h header file.

bpo-36854 [https://bugs.python.org/issue?@action=redirect&bpo=36854]: The garbage collector state becomes per interpreter (PyInterpreterState.gc), rather than being global (_PyRuntimeState.gc).

bpo-38835 [https://bugs.python.org/issue?@action=redirect&bpo=38835]: The PyFPE_START_PROTECT() and PyFPE_END_PROTECT() macros are empty: they have been doing nothing for the last year, so stop using them.

bpo-38328 [https://bugs.python.org/issue?@action=redirect&bpo=38328]: Sped up the creation time of constant list and set displays. Patch by Brandt Bucher.

bpo-38707 [https://bugs.python.org/issue?@action=redirect&bpo=38707]: MainThread.native_id is now correctly reset in child processes spawned using multiprocessing.Process, instead of retaining the parent’s value.

bpo-38629 [https://bugs.python.org/issue?@action=redirect&bpo=38629]: Added __floor__ and __ceil__ methods to float object. Patch by Batuhan Taşkaya.

bpo-27145 [https://bugs.python.org/issue?@action=redirect&bpo=27145]: int + int and int - int operators can now return small integer singletons. Patch by hongweipeng.

bpo-38021 [https://bugs.python.org/issue?@action=redirect&bpo=38021]: Provide a platform tag for AIX that is sufficient for PEP425 binary distribution identification. Patch by Michael Felt.

bpo-35409 [https://bugs.python.org/issue?@action=redirect&bpo=35409]: Ignore GeneratorExit exceptions when throwing an exception into the aclose coroutine of an asynchronous generator.

bpo-33387 [https://bugs.python.org/issue?@action=redirect&bpo=33387]: Removed WITH_CLEANUP_START, WITH_CLEANUP_FINISH, BEGIN_FINALLY, END_FINALLY, CALL_FINALLY and POP_FINALLY bytecodes. Replaced with RERAISE and WITH_EXCEPT_START bytecodes. The compiler now generates different code for exceptional and non-exceptional branches for “with” and “try-except” statements. For “try-finally” statements the “finally” block is replicated for each exit from the “try” body.

Library

bpo-39033 [https://bugs.python.org/issue?@action=redirect&bpo=39033]: Fix NameError in zipimport. Patch by Karthikeyan Singaravelan.

bpo-39022 [https://bugs.python.org/issue?@action=redirect&bpo=39022]: Update importlib.metadata to include improvements from importlib_metadata 1.3 including better serialization of EntryPoints and improved documentation for custom finders.

bpo-39006 [https://bugs.python.org/issue?@action=redirect&bpo=39006]: Fix asyncio when the ssl module is missing: only check for ssl.SSLSocket instance if the ssl module is available.

bpo-38708 [https://bugs.python.org/issue?@action=redirect&bpo=38708]: Fix a potential IndexError in email parser when parsing an empty msg-id.

bpo-38698 [https://bugs.python.org/issue?@action=redirect&bpo=38698]: Add a new InvalidMessageID token to email parser to represent invalid Message-ID headers. Also, add defects when there is remaining value after parsing the header.

bpo-38994 [https://bugs.python.org/issue?@action=redirect&bpo=38994]: Implement __class_getitem__ for os.PathLike, pathlib.Path.

bpo-38979 [https://bugs.python.org/issue?@action=redirect&bpo=38979]: Return class from ContextVar.__class_getitem__ to simplify subclassing.

bpo-38978 [https://bugs.python.org/issue?@action=redirect&bpo=38978]: Implement __class_getitem__ on asyncio objects (Future, Task, Queue). Patch by Batuhan Taskaya.

bpo-38916 [https://bugs.python.org/issue?@action=redirect&bpo=38916]: array.array: Remove tostring() and fromstring() methods. They were aliases to tobytes() and frombytes(), deprecated since Python 3.2.

bpo-38986 [https://bugs.python.org/issue?@action=redirect&bpo=38986]: Make repr of C accelerated TaskWakeupMethWrapper the same as of pure Python version.

bpo-38982 [https://bugs.python.org/issue?@action=redirect&bpo=38982]: Fix asyncio PidfdChildWatcher: handle waitpid() error. If waitpid() is called elsewhere, waitpid() call fails with ChildProcessError: use return code 255 in this case, and log a warning. It ensures that the pidfd file descriptor is closed if this error occurs.

bpo-38529 [https://bugs.python.org/issue?@action=redirect&bpo=38529]: Drop too noisy asyncio warning about deletion of a stream without explicit .close() call.

bpo-27413 [https://bugs.python.org/issue?@action=redirect&bpo=27413]: Added ability to pass through ensure_ascii options to json.dumps in the json.tool command-line interface.

bpo-38634 [https://bugs.python.org/issue?@action=redirect&bpo=38634]: The readline module now detects if Python is linked to libedit at runtime on all platforms. Previously, the check was only done on macOS.

bpo-33684 [https://bugs.python.org/issue?@action=redirect&bpo=33684]: Fix json.tool failed to read a JSON file with non-ASCII characters when locale encoding is not UTF-8.

bpo-38698 [https://bugs.python.org/issue?@action=redirect&bpo=38698]: Prevent UnboundLocalError to pop up in parse_message_id.

parse_message_id() was improperly using a token defined inside an exception handler, which was raising UnboundLocalError on parsing an invalid value. Patch by Claudiu Popa.

bpo-38927 [https://bugs.python.org/issue?@action=redirect&bpo=38927]: Use python -m pip instead of pip to upgrade dependencies in venv.

bpo-26730 [https://bugs.python.org/issue?@action=redirect&bpo=26730]: Fix SpooledTemporaryFile.rollover() might corrupt the file when it is in text mode. Patch by Serhiy Storchaka.

bpo-38881 [https://bugs.python.org/issue?@action=redirect&bpo=38881]: random.choices() now raises a ValueError when all the weights are zero.

bpo-38876 [https://bugs.python.org/issue?@action=redirect&bpo=38876]: Raise pickle.UnpicklingError when loading an item from memo for invalid input.

The previous code was raising a KeyError for both the Python and C implementation. This was caused by the specified index of an invalid input which did not exist in the memo structure, where the pickle stores what objects it has seen. The malformed input would have caused either a BINGET or LONG_BINGET load from the memo, leading to a KeyError as the determined index was bogus. Patch by Claudiu Popa

bpo-38688 [https://bugs.python.org/issue?@action=redirect&bpo=38688]: Calling func:shutil.copytree to copy a directory tree from one directory to another subdirectory resulted in an endless loop and a RecursionError. A fix was added to consume an iterator and create the list of the entries to be copied, avoiding the recursion for newly created directories. Patch by Bruno P. Kinoshita.

bpo-38863 [https://bugs.python.org/issue?@action=redirect&bpo=38863]: Improve is_cgi() function in http.server, which enables processing the case that cgi directory is a child of another directory other than root.

bpo-37838 [https://bugs.python.org/issue?@action=redirect&bpo=37838]: typing.get_type_hints() properly handles functions decorated with functools.wraps().

bpo-38870 [https://bugs.python.org/issue?@action=redirect&bpo=38870]: Expose ast.unparse() as a function of the ast module that can be used to unparse an ast.AST object and produce a string with code that would produce an equivalent ast.AST object when parsed. Patch by Pablo Galindo and Batuhan Taskaya.

bpo-38859 [https://bugs.python.org/issue?@action=redirect&bpo=38859]: AsyncMock now returns StopAsyncIteration on the exhaustion of a side_effects iterable. Since PEP-479 its Impossible to raise a StopIteration exception from a coroutine.

bpo-38857 [https://bugs.python.org/issue?@action=redirect&bpo=38857]: AsyncMock fix for return values that are awaitable types. This also covers side_effect iterable values that happened to be awaitable, and wraps callables that return an awaitable type. Before these awaitables were being awaited instead of being returned as is.

bpo-38834 [https://bugs.python.org/issue?@action=redirect&bpo=38834]: typing.TypedDict subclasses now track which keys are optional using the __required_keys__ and __optional_keys__ attributes, to enable runtime validation by downstream projects. Patch by Zac Hatfield-Dodds.

bpo-38821 [https://bugs.python.org/issue?@action=redirect&bpo=38821]: Fix unhandled exceptions in argparse when internationalizing error messages for arguments with nargs set to special (non-integer) values. Patch by Federico Bond.

bpo-38820 [https://bugs.python.org/issue?@action=redirect&bpo=38820]: Make Python compatible with OpenSSL 3.0.0. ssl.SSLSocket.getpeercert() no longer returns IPv6 addresses with a trailing new line.

bpo-38811 [https://bugs.python.org/issue?@action=redirect&bpo=38811]: Fix an unhandled exception in pathlib when os.link() is missing. Patch by Toke Høiland-Jørgensen.

bpo-38686 [https://bugs.python.org/issue?@action=redirect&bpo=38686]: Added support for multiple qop values in urllib.request.AbstractDigestAuthHandler.

bpo-38712 [https://bugs.python.org/issue?@action=redirect&bpo=38712]: Add the Linux-specific signal.pidfd_send_signal() function, which allows sending a signal to a process identified by a file descriptor rather than a pid.

bpo-38348 [https://bugs.python.org/issue?@action=redirect&bpo=38348]: Add -i and --indent (indentation level), and --no-type-comments (type comments) command line options to ast parsing tool.

bpo-37523 [https://bugs.python.org/issue?@action=redirect&bpo=37523]: Change zipfile.ZipExtFile to raise ValueError when trying to access the underlying file object after it has been closed. This new behavior is consistent with how accessing closed files is handled in other parts of Python.

bpo-38045 [https://bugs.python.org/issue?@action=redirect&bpo=38045]: Improve the performance of enum._decompose() in enum. Patch by hongweipeng.

bpo-36820 [https://bugs.python.org/issue?@action=redirect&bpo=36820]: Break cycle generated when saving an exception in socket.py, codeop.py and dyld.py as they keep alive not only the exception but user objects through the __traceback__ attribute. Patch by Mario Corchero.

bpo-36406 [https://bugs.python.org/issue?@action=redirect&bpo=36406]: Handle namespace packages in doctest. Patch by Karthikeyan Singaravelan.

bpo-34776 [https://bugs.python.org/issue?@action=redirect&bpo=34776]: Fix dataclasses to support forward references in type annotations

bpo-20928 [https://bugs.python.org/issue?@action=redirect&bpo=20928]: ElementTree supports recursive XInclude processing. Patch by Stefan Behnel.

bpo-29636 [https://bugs.python.org/issue?@action=redirect&bpo=29636]: Add whitespace options for formatting JSON with the json.tool CLI. The following mutually exclusive options are now supported: --indent for setting the indent level in spaces; --tab for indenting with tabs; --no-indent for suppressing newlines; and --compact for suppressing all whitespace. The default behavior remains the same as --indent=4.

Documentation

bpo-38928 [https://bugs.python.org/issue?@action=redirect&bpo=38928]: Correct when venv’s upgrade_dependencies() and --upgrade-deps are added.

bpo-38899 [https://bugs.python.org/issue?@action=redirect&bpo=38899]: Update documentation to state that to activate virtual environments under fish one should use source, not as documented at https://fishshell.com/docs/current/commands.html#source.

bpo-22377 [https://bugs.python.org/issue?@action=redirect&bpo=22377]: Improves documentation of the values that datetime.datetime.strptime() accepts for %Z. Patch by Karl Dubost.

Tests

bpo-38546 [https://bugs.python.org/issue?@action=redirect&bpo=38546]: Fix test_ressources_gced_in_workers() of test_concurrent_futures: explicitly stop the manager to prevent leaking a child process running in the background after the test completes.

bpo-38546 [https://bugs.python.org/issue?@action=redirect&bpo=38546]: Multiprocessing and concurrent.futures tests now stop the resource tracker process when tests complete.

bpo-38614 [https://bugs.python.org/issue?@action=redirect&bpo=38614]: Replace hardcoded timeout constants in tests with new test.support constants: LOOPBACK_TIMEOUT, INTERNET_TIMEOUT, SHORT_TIMEOUT and LONG_TIMEOUT. It becomes easier to adjust these four timeout constants for all tests at once, rather than having to adjust every single test file.

bpo-38547 [https://bugs.python.org/issue?@action=redirect&bpo=38547]: Fix test_pty: if the process is the session leader, closing the master file descriptor raises a SIGHUP signal: simply ignore SIGHUP when running the tests.

bpo-38992 [https://bugs.python.org/issue?@action=redirect&bpo=38992]: Fix a test for math.fsum() that was failing due to constant folding.

bpo-38991 [https://bugs.python.org/issue?@action=redirect&bpo=38991]: test.support: run_python_until_end(), assert_python_ok() and assert_python_failure() functions no longer strip whitespaces from stderr. Remove test.support.strip_python_stderr() function.

bpo-38965 [https://bugs.python.org/issue?@action=redirect&bpo=38965]: Fix test_faulthandler on GCC 10. Use the «volatile» keyword in faulthandler._stack_overflow() to prevent tail call optimization on any compiler, rather than relying on compiler specific pragma.

bpo-38875 [https://bugs.python.org/issue?@action=redirect&bpo=38875]: test_capi: trashcan tests now require the test «cpu» resource.

bpo-38841 [https://bugs.python.org/issue?@action=redirect&bpo=38841]: Skip asyncio test_create_datagram_endpoint_existing_sock_unix on platforms lacking a functional bind() for named unix domain sockets.

bpo-38692 [https://bugs.python.org/issue?@action=redirect&bpo=38692]: Skip the test_posix.test_pidfd_open() test if os.pidfd_open() fails with a PermissionError. This situation can happen in a Linux sandbox using a syscall whitelist which doesn’t allow the pidfd_open() syscall yet.

bpo-38839 [https://bugs.python.org/issue?@action=redirect&bpo=38839]: Fix some unused functions in tests. Patch by Adam Johnson.

bpo-38669 [https://bugs.python.org/issue?@action=redirect&bpo=38669]: Raise TypeError when passing target as a string with unittest.mock.patch.object().

bpo-37957 [https://bugs.python.org/issue?@action=redirect&bpo=37957]: test.regrtest now can receive a list of test patterns to ignore (using the -i/–ignore argument) or a file with a list of patterns to ignore (using the –ignore-file argument). Patch by Pablo Galindo.

Build

bpo-37404 [https://bugs.python.org/issue?@action=redirect&bpo=37404]: asyncio now raises TyperError when calling incompatible methods with an ssl.SSLSocket socket. Patch by Ido Michael.

bpo-36500 [https://bugs.python.org/issue?@action=redirect&bpo=36500]: Added an optional «regen» project to the Visual Studio solution that will regenerate all grammar, tokens, and opcodes.

Windows

bpo-39007 [https://bugs.python.org/issue?@action=redirect&bpo=39007]: Add auditing events to functions in winreg.

bpo-33125 [https://bugs.python.org/issue?@action=redirect&bpo=33125]: Add support for building and releasing Windows ARM64 packages.

macOS

bpo-37931 [https://bugs.python.org/issue?@action=redirect&bpo=37931]: Fixed a crash on OSX dynamic builds that occurred when re-initializing the posix module after a Py_Finalize if the environment had changed since the previous import posix. Patch by Benoît Hudson.

IDLE

bpo-38944 [https://bugs.python.org/issue?@action=redirect&bpo=38944]: Escape key now closes IDLE completion windows. Patch by Johnny Najera.

bpo-38943 [https://bugs.python.org/issue?@action=redirect&bpo=38943]: Fix IDLE autocomplete windows not always appearing on some systems. Patch by Johnny Najera.

bpo-38862 [https://bugs.python.org/issue?@action=redirect&bpo=38862]: “Strip Trailing Whitespace” on the Format menu removes extra newlines at the end of non-shell files.

bpo-38636 [https://bugs.python.org/issue?@action=redirect&bpo=38636]: Fix IDLE Format menu tab toggle and file indent width. These functions (default shortcuts Alt-T and Alt-U) were mistakenly disabled in 3.7.5 and 3.8.0.

C API

bpo-38896 [https://bugs.python.org/issue?@action=redirect&bpo=38896]: Remove PyUnicode_ClearFreeList() function: the Unicode free list has been removed in Python 3.3.

bpo-37340 [https://bugs.python.org/issue?@action=redirect&bpo=37340]: Remove PyMethod_ClearFreeList() and PyCFunction_ClearFreeList() functions: the free lists of bound method objects have been removed.

bpo-38835 [https://bugs.python.org/issue?@action=redirect&bpo=38835]: Exclude PyFPE_START_PROTECT() and PyFPE_END_PROTECT() macros of pyfpe.h from Py_LIMITED_API (stable API).

Python 3.9.0 alpha 1

Release date: 2019-11-19

Security

bpo-38722 [https://bugs.python.org/issue?@action=redirect&bpo=38722]: runpy now uses io.open_code() to open code files. Patch by Jason Killen.

bpo-38622 [https://bugs.python.org/issue?@action=redirect&bpo=38622]: Add additional audit events for the ctypes module.

bpo-38418 [https://bugs.python.org/issue?@action=redirect&bpo=38418]: Fixes audit event for os.system() to be named os.system.

bpo-38243 [https://bugs.python.org/issue?@action=redirect&bpo=38243]: Escape the server title of xmlrpc.server.DocXMLRPCServer when rendering the document page as HTML. (Contributed by Dong-hee Na in bpo-38243 [https://bugs.python.org/issue?@action=redirect&bpo=38243].)

bpo-38174 [https://bugs.python.org/issue?@action=redirect&bpo=38174]: Update vendorized expat library version to 2.2.8, which resolves CVE-2019-15903.

bpo-37764 [https://bugs.python.org/issue?@action=redirect&bpo=37764]: Fixes email._header_value_parser.get_unstructured going into an infinite loop for a specific case in which the email header does not have trailing whitespace, and the case in which it contains an invalid encoded word. Patch by Ashwin Ramaswami.

bpo-37461 [https://bugs.python.org/issue?@action=redirect&bpo=37461]: Fix an infinite loop when parsing specially crafted email headers. Patch by Abhilash Raj.

bpo-37363 [https://bugs.python.org/issue?@action=redirect&bpo=37363]: Adds audit events for the range of supported run commands (see Línea de comandos y entorno).

bpo-37463 [https://bugs.python.org/issue?@action=redirect&bpo=37463]: ssl.match_hostname() no longer accepts IPv4 addresses with additional text after the address and only quad-dotted notation without trailing whitespaces. Some inet_aton() implementations ignore whitespace and all data after whitespace, e.g. “127.0.0.1 whatever”.

bpo-37363 [https://bugs.python.org/issue?@action=redirect&bpo=37363]: Adds audit events for ensurepip, ftplib, glob, imaplib, nntplib, pdb, poplib, shutil, smtplib, sqlite3, subprocess, telnetlib, tempfile and webbrowser, as well as os.listdir(), os.scandir() and breakpoint().

bpo-37364 [https://bugs.python.org/issue?@action=redirect&bpo=37364]: io.open_code() is now used when reading .pth files.

bpo-34631 [https://bugs.python.org/issue?@action=redirect&bpo=34631]: Updated OpenSSL to 1.1.1c in Windows installer

bpo-34155 [https://bugs.python.org/issue?@action=redirect&bpo=34155]: Fix parsing of invalid email addresses with more than one @ (e.g. a@b@c.com.) to not return the part before 2nd @ as valid email address. Patch by maxking & jpic.

Core and Builtins

bpo-38631 [https://bugs.python.org/issue?@action=redirect&bpo=38631]: Replace Py_FatalError() call with a regular RuntimeError exception in float.__getformat__().

bpo-38639 [https://bugs.python.org/issue?@action=redirect&bpo=38639]: Optimized math.floor(), math.ceil() and math.trunc() for floats.

bpo-38640 [https://bugs.python.org/issue?@action=redirect&bpo=38640]: Fixed a bug in the compiler that was causing to raise in the presence of break statements and continue statements inside always false while loops. Patch by Pablo Galindo.

bpo-38613 [https://bugs.python.org/issue?@action=redirect&bpo=38613]: Optimized some set operations (e.g. |, ^, and -) of dict_keys. d.keys() | other was slower than set(d) | other but they are almost same performance for now.

bpo-28029 [https://bugs.python.org/issue?@action=redirect&bpo=28029]: "".replace("", s, n) now returns s instead of an empty string for all non-zero n. There are similar changes for bytes and bytearray objects.

bpo-38535 [https://bugs.python.org/issue?@action=redirect&bpo=38535]: Fixed line numbers and column offsets for AST nodes for calls without arguments in decorators.

bpo-38525 [https://bugs.python.org/issue?@action=redirect&bpo=38525]: Fix a segmentation fault when using reverse iterators of empty dict objects. Patch by Dong-hee Na and Inada Naoki.

bpo-38465 [https://bugs.python.org/issue?@action=redirect&bpo=38465]: bytearray, array and mmap objects allow now to export more than 2**31 buffers at a time.

bpo-38469 [https://bugs.python.org/issue?@action=redirect&bpo=38469]: Fixed a bug where the scope of named expressions was not being resolved correctly in the presence of the global keyword. Patch by Pablo Galindo.

bpo-38437 [https://bugs.python.org/issue?@action=redirect&bpo=38437]: Activate the GC_DEBUG macro for debug builds of the interpreter (when Py_DEBUG is set). Patch by Pablo Galindo.

bpo-38379 [https://bugs.python.org/issue?@action=redirect&bpo=38379]: When the garbage collector makes a collection in which some objects resurrect (they are reachable from outside the isolated cycles after the finalizers have been executed), do not block the collection of all objects that are still unreachable. Patch by Pablo Galindo and Tim Peters.

bpo-38379 [https://bugs.python.org/issue?@action=redirect&bpo=38379]: When cyclic garbage collection (gc) runs finalizers that resurrect unreachable objects, the current gc run ends, without collecting any cyclic trash. However, the statistics reported by collect() and get_stats() claimed that all cyclic trash found was collected, and that the resurrected objects were collected. Changed the stats to report that none were collected.

bpo-38392 [https://bugs.python.org/issue?@action=redirect&bpo=38392]: In debug mode, PyObject_GC_Track() now calls tp_traverse() of the object type to ensure that the object is valid: test that objects visited by tp_traverse() are valid.

bpo-38210 [https://bugs.python.org/issue?@action=redirect&bpo=38210]: Remove unnecessary intersection and update set operation in dictview with empty set. (Contributed by Dong-hee Na in bpo-38210 [https://bugs.python.org/issue?@action=redirect&bpo=38210].)

bpo-38402 [https://bugs.python.org/issue?@action=redirect&bpo=38402]: Check the error from the system’s underlying crypt or crypt_r.

bpo-37474 [https://bugs.python.org/issue?@action=redirect&bpo=37474]: On FreeBSD, Python no longer calls fedisableexcept() at startup to control the floating point control mode. The call became useless since FreeBSD 6: it became the default mode.

bpo-38006 [https://bugs.python.org/issue?@action=redirect&bpo=38006]: Fix a bug due to the interaction of weakrefs and the cyclic garbage collector. We must clear any weakrefs in garbage in order to prevent their callbacks from executing and causing a crash.

bpo-38317 [https://bugs.python.org/issue?@action=redirect&bpo=38317]: Fix warnings options priority: PyConfig.warnoptions has the highest priority, as stated in the PEP 587 [https://www.python.org/dev/peps/pep-0587].

bpo-38310 [https://bugs.python.org/issue?@action=redirect&bpo=38310]: Predict BUILD_MAP_UNPACK_WITH_CALL -> CALL_FUNCTION_EX opcode pairs in the main interpreter loop. Patch by Brandt Bucher.

bpo-36871 [https://bugs.python.org/issue?@action=redirect&bpo=36871]: Improve error handling for the assert_has_calls and assert_has_awaits methods of mocks. Fixed a bug where any errors encountered while binding the expected calls to the mock’s spec were silently swallowed, leading to misleading error output.

bpo-11410 [https://bugs.python.org/issue?@action=redirect&bpo=11410]: Better control over symbol visibility is provided through use of the visibility attributes available in gcc >= 4.0, provided in a uniform way across POSIX and Windows. The POSIX build files have been updated to compile with -fvisibility=hidden, minimising exported symbols.

bpo-38219 [https://bugs.python.org/issue?@action=redirect&bpo=38219]: Optimized the dict constructor and the update() method for the case when the argument is a dict.

bpo-38236 [https://bugs.python.org/issue?@action=redirect&bpo=38236]: Python now dumps path configuration if it fails to import the Python codecs of the filesystem and stdio encodings.

bpo-38013 [https://bugs.python.org/issue?@action=redirect&bpo=38013]: Allow to call async_generator_athrow().throw(...) even for non-started async generator helper. It fixes annoying warning at the end of asyncio.run() call.

bpo-38124 [https://bugs.python.org/issue?@action=redirect&bpo=38124]: Fix an off-by-one error in PyState_AddModule that could cause out-of-bounds memory access.

bpo-38116 [https://bugs.python.org/issue?@action=redirect&bpo=38116]: The select module is now PEP-384 compliant and no longer has static state

bpo-38113 [https://bugs.python.org/issue?@action=redirect&bpo=38113]: ast module updated to PEP-384 and all statics removed

bpo-38076 [https://bugs.python.org/issue?@action=redirect&bpo=38076]: The struct module is now PEP-384 compatible

bpo-38075 [https://bugs.python.org/issue?@action=redirect&bpo=38075]: The random module is now PEP-384 compatible

bpo-38074 [https://bugs.python.org/issue?@action=redirect&bpo=38074]: zlib module made PEP-384 compatible

bpo-38073 [https://bugs.python.org/issue?@action=redirect&bpo=38073]: Make pwd extension module PEP-384 compatible

bpo-38072 [https://bugs.python.org/issue?@action=redirect&bpo=38072]: grp module made PEP-384 compatible

bpo-38069 [https://bugs.python.org/issue?@action=redirect&bpo=38069]: Make _posixsubprocess PEP-384 compatible

bpo-38071 [https://bugs.python.org/issue?@action=redirect&bpo=38071]: Make termios extension module PEP-384 compatible

bpo-38005 [https://bugs.python.org/issue?@action=redirect&bpo=38005]: Fixed comparing and creating of InterpreterID and ChannelID.

bpo-36946 [https://bugs.python.org/issue?@action=redirect&bpo=36946]: Fix possible signed integer overflow when handling slices. Patch by hongweipeng.

bpo-37994 [https://bugs.python.org/issue?@action=redirect&bpo=37994]: Fixed silencing arbitrary errors if an attribute lookup fails in several sites. Only AttributeError should be silenced.

bpo-8425 [https://bugs.python.org/issue?@action=redirect&bpo=8425]: Optimize set difference_update for the case when the other set is much larger than the base set. (Suggested by Evgeny Kapun with code contributed by Michele Orrù).

bpo-37966 [https://bugs.python.org/issue?@action=redirect&bpo=37966]: The implementation of is_normalized() has been greatly sped up on strings that aren’t normalized, by implementing the full normalization-quick-check algorithm from the Unicode standard.

bpo-37947 [https://bugs.python.org/issue?@action=redirect&bpo=37947]: Adjust correctly the recursion level in the symtable generation for named expressions. Patch by Pablo Galindo.

bpo-37812 [https://bugs.python.org/issue?@action=redirect&bpo=37812]: The CHECK_SMALL_INT macro used inside Object/longobject.c has been replaced with an explicit return at each call site.

bpo-37751 [https://bugs.python.org/issue?@action=redirect&bpo=37751]: Fix codecs.lookup() to normalize the encoding name the same way than encodings.normalize_encoding(), except that codecs.lookup() also converts the name to lower case.

bpo-37830 [https://bugs.python.org/issue?@action=redirect&bpo=37830]: Fixed compilation of break and continue in the finally block when the corresponding try block contains return with a non-constant value.

bpo-20490 [https://bugs.python.org/issue?@action=redirect&bpo=20490]: Improve import error message for partially initialized module on circular from imports - by Anthony Sottile.

bpo-37840 [https://bugs.python.org/issue?@action=redirect&bpo=37840]: Fix handling of negative indices in sq_item of bytearray. Patch by Sergey Fedoseev.

bpo-37802 [https://bugs.python.org/issue?@action=redirect&bpo=37802]: Slightly improve performance of PyLong_FromUnsignedLong(), PyLong_FromUnsignedLongLong() and PyLong_FromSize_t(). Patch by Sergey Fedoseev.

bpo-37409 [https://bugs.python.org/issue?@action=redirect&bpo=37409]: Ensure explicit relative imports from interactive sessions and scripts (having no parent package) always raise ImportError, rather than treating the current module as the package. Patch by Ben Lewis.

bpo-32912 [https://bugs.python.org/issue?@action=redirect&bpo=32912]: Reverted bpo-32912 [https://bugs.python.org/issue?@action=redirect&bpo=32912]: emitting SyntaxWarning instead of DeprecationWarning for invalid escape sequences in string and bytes literals.

bpo-37757 [https://bugs.python.org/issue?@action=redirect&bpo=37757]: PEP 572 [https://www.python.org/dev/peps/pep-0572]: As described in the PEP, assignment expressions now raise SyntaxError when their interaction with comprehension scoping results in an ambiguous target scope.

The TargetScopeError subclass originally proposed by the PEP has been removed in favour of just raising regular syntax errors for the disallowed cases.

bpo-36279 [https://bugs.python.org/issue?@action=redirect&bpo=36279]: Fix potential use of uninitialized memory in os.wait3().

bpo-36311 [https://bugs.python.org/issue?@action=redirect&bpo=36311]: Decoding bytes objects larger than 2GiB is faster and no longer fails when a multibyte characters spans a chunk boundary.

bpo-34880 [https://bugs.python.org/issue?@action=redirect&bpo=34880]: The assert statement now works properly if the AssertionError exception is being shadowed. Patch by Zackery Spytz.

bpo-37340 [https://bugs.python.org/issue?@action=redirect&bpo=37340]: Removed object cache (free_list) for bound method objects. Temporary bound method objects are less used than before thanks to the LOAD_METHOD opcode and the _PyObject_VectorcallMethod C API.

bpo-37648 [https://bugs.python.org/issue?@action=redirect&bpo=37648]: Fixed minor inconsistency in list.__contains__(), tuple.__contains__() and a few other places. The collection’s item is now always at the left and the needle is on the right of ==.

bpo-37444 [https://bugs.python.org/issue?@action=redirect&bpo=37444]: Update differing exception between builtins.__import__() and importlib.__import__().

bpo-37619 [https://bugs.python.org/issue?@action=redirect&bpo=37619]: When adding a wrapper descriptor from one class to a different class (for example, setting __add__ = str.__add__ on an int subclass), an exception is correctly raised when the operator is called.

bpo-37593 [https://bugs.python.org/issue?@action=redirect&bpo=37593]: Swap the positions of the posonlyargs and args parameters in the constructor of ast.parameters nodes.

bpo-37543 [https://bugs.python.org/issue?@action=redirect&bpo=37543]: Optimized pymalloc for non PGO build.

bpo-37537 [https://bugs.python.org/issue?@action=redirect&bpo=37537]: Compute allocated pymalloc blocks inside _Py_GetAllocatedBlocks(). This slows down _Py_GetAllocatedBlocks() but gives a small speedup to _PyObject_Malloc() and _PyObject_Free().

bpo-37467 [https://bugs.python.org/issue?@action=redirect&bpo=37467]: Fix sys.excepthook() and PyErr_Display() if a filename is a bytes string. For example, for a SyntaxError exception where the filename attribute is a bytes string.

bpo-37433 [https://bugs.python.org/issue?@action=redirect&bpo=37433]: Fix SyntaxError indicator printing too many spaces for multi-line strings - by Anthony Sottile.

bpo-37417 [https://bugs.python.org/issue?@action=redirect&bpo=37417]: bytearray.extend() now correctly handles errors that arise during iteration. Patch by Brandt Bucher.

bpo-37414 [https://bugs.python.org/issue?@action=redirect&bpo=37414]: The undocumented sys.callstats() function has been removed. Since Python 3.7, it was deprecated and always returned None. It required a special build option CALL_PROFILE which was already removed in Python 3.7.

bpo-37392 [https://bugs.python.org/issue?@action=redirect&bpo=37392]: Remove sys.getcheckinterval() and sys.setcheckinterval() functions. They were deprecated since Python 3.2. Use sys.getswitchinterval() and sys.setswitchinterval() instead. Remove also check_interval field of the PyInterpreterState structure.

bpo-37388 [https://bugs.python.org/issue?@action=redirect&bpo=37388]: In development mode and in debug build, encoding and errors arguments are now checked on string encoding and decoding operations. Examples: open(), str.encode() and bytes.decode().

By default, for best performances, the errors argument is only checked at the first encoding/decoding error, and the encoding argument is sometimes ignored for empty strings.

bpo-37348 [https://bugs.python.org/issue?@action=redirect&bpo=37348]: Optimized decoding short ASCII string with UTF-8 and ascii codecs. b"foo".decode() is about 15% faster. Patch by Inada Naoki.

bpo-24214 [https://bugs.python.org/issue?@action=redirect&bpo=24214]: Improved support of the surrogatepass error handler in the UTF-8 and UTF-16 incremental decoders.

bpo-37330 [https://bugs.python.org/issue?@action=redirect&bpo=37330]: open(), io.open(), codecs.open() and fileinput.FileInput no longer accept 'U' («universal newline») in the file mode. This flag was deprecated since Python 3.3.

bpo-35224 [https://bugs.python.org/issue?@action=redirect&bpo=35224]: Reverse evaluation order of key: value in dict comprehensions as proposed in PEP 572. I.e. in {k: v for ...}, k will be evaluated before v.

bpo-37316 [https://bugs.python.org/issue?@action=redirect&bpo=37316]: Fix the PySys_Audit() call in mmap.mmap.

bpo-37300 [https://bugs.python.org/issue?@action=redirect&bpo=37300]: Remove an unnecessary Py_XINCREF in classobject.c.

bpo-37269 [https://bugs.python.org/issue?@action=redirect&bpo=37269]: Fix a bug in the peephole optimizer that was not treating correctly constant conditions with binary operators. Patch by Pablo Galindo.

bpo-20443 [https://bugs.python.org/issue?@action=redirect&bpo=20443]: Python now gets the absolute path of the script filename specified on the command line (ex: «python3 script.py»): the __file__ attribute of the __main__ module and sys.path[0] become an absolute path, rather than a relative path.

bpo-37257 [https://bugs.python.org/issue?@action=redirect&bpo=37257]: Python’s small object allocator (obmalloc.c) now allows (no more than) one empty arena to remain available for immediate reuse, without returning it to the OS. This prevents thrashing in simple loops where an arena could be created and destroyed anew on each iteration.

bpo-37231 [https://bugs.python.org/issue?@action=redirect&bpo=37231]: The dispatching of type slots to special methods (for example calling __mul__ when doing x * y) has been made faster.

bpo-36974 [https://bugs.python.org/issue?@action=redirect&bpo=36974]: Implemented separate vectorcall functions for every calling convention of builtin functions and methods. This improves performance for calls.

bpo-37213 [https://bugs.python.org/issue?@action=redirect&bpo=37213]: Handle correctly negative line offsets in the peephole optimizer. Patch by Pablo Galindo.

bpo-37219 [https://bugs.python.org/issue?@action=redirect&bpo=37219]: Remove erroneous optimization for empty set differences.

bpo-15913 [https://bugs.python.org/issue?@action=redirect&bpo=15913]: Implement PyBuffer_SizeFromFormat() function (previously documented but not implemented): call struct.calcsize(). Patch by Joannah Nanjekye.

bpo-36922 [https://bugs.python.org/issue?@action=redirect&bpo=36922]: Slot functions optimize any callable with Py_TPFLAGS_METHOD_DESCRIPTOR instead of only instances of function.

bpo-36974 [https://bugs.python.org/issue?@action=redirect&bpo=36974]: The slot tp_vectorcall_offset is inherited unconditionally to support super().__call__() when the base class uses vectorcall.

bpo-37160 [https://bugs.python.org/issue?@action=redirect&bpo=37160]: threading.get_native_id() now also supports NetBSD.

bpo-37077 [https://bugs.python.org/issue?@action=redirect&bpo=37077]: Add threading.get_native_id() support for AIX. Patch by M. Felt

bpo-36781 [https://bugs.python.org/issue?@action=redirect&bpo=36781]: sum() has been optimized for boolean values.

bpo-34556 [https://bugs.python.org/issue?@action=redirect&bpo=34556]: Add --upgrade-deps to venv module. Patch by Cooper Ry Lees

bpo-20523 [https://bugs.python.org/issue?@action=redirect&bpo=20523]: pdb.Pdb supports ~/.pdbrc in Windows 7. Patch by Tim Hopper and Dan Lidral-Porter.

bpo-35551 [https://bugs.python.org/issue?@action=redirect&bpo=35551]: Updated encodings: - Removed the «tis260» encoding, which was an alias for the nonexistent «tactis» codec. - Added «mac_centeuro» as an alias for the mac_latin2 encoding.

bpo-19072 [https://bugs.python.org/issue?@action=redirect&bpo=19072]: The classmethod decorator can now wrap other descriptors such as property objects. Adapted from a patch written by Graham Dumpleton.

bpo-27575 [https://bugs.python.org/issue?@action=redirect&bpo=27575]: Improve speed of dictview intersection by directly using set intersection logic. Patch by David Su.

bpo-30773 [https://bugs.python.org/issue?@action=redirect&bpo=30773]: Prohibit parallel running of aclose() / asend() / athrow(). Fix ag_running to reflect the actual running status of the AG.

Library

bpo-36589 [https://bugs.python.org/issue?@action=redirect&bpo=36589]: The curses.update_lines_cols() function now returns None instead of 1 on success.

bpo-38807 [https://bugs.python.org/issue?@action=redirect&bpo=38807]: Update TypeError messages for os.path.join() to include os.PathLike objects as acceptable input types.

bpo-38724 [https://bugs.python.org/issue?@action=redirect&bpo=38724]: Add a repr for subprocess.Popen objects. Patch by Andrey Doroschenko.

bpo-38786 [https://bugs.python.org/issue?@action=redirect&bpo=38786]: pydoc now recognizes and parses HTTPS URLs. Patch by python273.

bpo-38785 [https://bugs.python.org/issue?@action=redirect&bpo=38785]: Prevent asyncio from crashing if parent __init__ is not called from a constructor of object derived from asyncio.Future.

bpo-38723 [https://bugs.python.org/issue?@action=redirect&bpo=38723]: pdb now uses io.open_code() to trigger auditing events.

bpo-27805 [https://bugs.python.org/issue?@action=redirect&bpo=27805]: Allow opening pipes and other non-seekable files in append mode with open().

bpo-38438 [https://bugs.python.org/issue?@action=redirect&bpo=38438]: Simplify the argparse usage message for nargs="*".

bpo-38761 [https://bugs.python.org/issue?@action=redirect&bpo=38761]: WeakSet is now registered as a collections.abc.MutableSet.

bpo-38716 [https://bugs.python.org/issue?@action=redirect&bpo=38716]: logging: change RotatingHandler namer and rotator to class-level attributes. This stops __init__ from setting them to None in the case where a subclass defines them with eponymous methods.

bpo-38713 [https://bugs.python.org/issue?@action=redirect&bpo=38713]: Add os.P_PIDFD constant, which may be passed to os.waitid() to wait on a Linux process file descriptor.

bpo-38692 [https://bugs.python.org/issue?@action=redirect&bpo=38692]: Add asyncio.PidfdChildWatcher, a Linux-specific child watcher implementation that polls process file descriptors.

bpo-38692 [https://bugs.python.org/issue?@action=redirect&bpo=38692]: Expose the Linux pidfd_open syscall as os.pidfd_open().

bpo-38602 [https://bugs.python.org/issue?@action=redirect&bpo=38602]: Added constants F_OFD_GETLK, F_OFD_SETLK and F_OFD_SETLKW to the fcntl module. Patch by Dong-hee Na.

bpo-38334 [https://bugs.python.org/issue?@action=redirect&bpo=38334]: Fixed seeking backward on an encrypted zipfile.ZipExtFile.

bpo-38312 [https://bugs.python.org/issue?@action=redirect&bpo=38312]: Add curses.get_escdelay(), curses.set_escdelay(), curses.get_tabsize(), and curses.set_tabsize() functions - by Anthony Sottile.

bpo-38586 [https://bugs.python.org/issue?@action=redirect&bpo=38586]: Now fileConfig() correctly sets the .name of handlers loaded.

bpo-38565 [https://bugs.python.org/issue?@action=redirect&bpo=38565]: Add new cache_parameters() method for functools.lru_cache() to better support pickling.

bpo-34679 [https://bugs.python.org/issue?@action=redirect&bpo=34679]: asynci.ProactorEventLoop.close() now only calls signal.set_wakeup_fd() in the main thread.

bpo-31202 [https://bugs.python.org/issue?@action=redirect&bpo=31202]: The case the result of pathlib.WindowsPath.glob() matches now the case of the pattern for literal parts.

bpo-36321 [https://bugs.python.org/issue?@action=redirect&bpo=36321]: Remove misspelled attribute. The 3.8 changelog noted that this would be removed in 3.9.

bpo-38521 [https://bugs.python.org/issue?@action=redirect&bpo=38521]: Fixed erroneous equality comparison in statistics.NormalDist().

bpo-38493 [https://bugs.python.org/issue?@action=redirect&bpo=38493]: Added CLD_KILLED and CLD_STOPPED for si_code. Patch by Dong-hee Na.

bpo-38478 [https://bugs.python.org/issue?@action=redirect&bpo=38478]: Fixed a bug in inspect.signature.bind() that was causing it to fail when handling a keyword argument with same name as positional-only parameter. Patch by Pablo Galindo.

bpo-33604 [https://bugs.python.org/issue?@action=redirect&bpo=33604]: Fixed hmac.new and hmac.HMAC to raise TypeError instead of ValueError when the digestmod parameter, now required in 3.8, is omitted. Also clarified the hmac module documentation and docstrings.

bpo-38378 [https://bugs.python.org/issue?@action=redirect&bpo=38378]: Parameters out and in of os.sendfile() was renamed to out_fd and in_fd.

bpo-38417 [https://bugs.python.org/issue?@action=redirect&bpo=38417]: Added support for setting the umask in the child process to the subprocess module on POSIX systems.

bpo-38449 [https://bugs.python.org/issue?@action=redirect&bpo=38449]: Revert PR 15522, which introduces a regression in mimetypes.guess_type() due to improper handling of filenames as urls.

bpo-38431 [https://bugs.python.org/issue?@action=redirect&bpo=38431]: Fix __repr__ method for dataclasses.InitVar to support typing objects, patch by Samuel Colvin.

bpo-38109 [https://bugs.python.org/issue?@action=redirect&bpo=38109]: Add missing stat.S_IFDOOR, stat.S_IFPORT, stat.S_IFWHT, stat.S_ISDOOR(), stat.S_ISPORT(), and stat.S_ISWHT() values to the Python implementation of stat.

bpo-38422 [https://bugs.python.org/issue?@action=redirect&bpo=38422]: Clarify docstrings of pathlib suffix(es)

bpo-38405 [https://bugs.python.org/issue?@action=redirect&bpo=38405]: Nested subclasses of typing.NamedTuple are now pickleable.

bpo-38332 [https://bugs.python.org/issue?@action=redirect&bpo=38332]: Prevent KeyError thrown by _encoded_words.decode() when given an encoded-word with invalid content-type encoding from propagating all the way to email.message.get().

bpo-38371 [https://bugs.python.org/issue?@action=redirect&bpo=38371]: Deprecated the split() method in _tkinter.TkappType in favour of the splitlist() method which has more consistent and predicable behavior.

bpo-38341 [https://bugs.python.org/issue?@action=redirect&bpo=38341]: Add smtplib.SMTPNotSupportedError to the smtplib exported names.

bpo-38319 [https://bugs.python.org/issue?@action=redirect&bpo=38319]: sendfile() used in socket and shutil modules was raising OverflowError for files >= 2GiB on 32-bit architectures. (patch by Giampaolo Rodola)

bpo-38242 [https://bugs.python.org/issue?@action=redirect&bpo=38242]: Revert the new asyncio Streams API

bpo-13153 [https://bugs.python.org/issue?@action=redirect&bpo=13153]: OS native encoding is now used for converting between Python strings and Tcl objects. This allows to display, copy and paste to clipboard emoji and other non-BMP characters. Converting strings from Tcl to Python and back now never fails (except MemoryError).

bpo-38019 [https://bugs.python.org/issue?@action=redirect&bpo=38019]: Correctly handle pause/resume reading of closed asyncio unix pipe.

bpo-38163 [https://bugs.python.org/issue?@action=redirect&bpo=38163]: Child mocks will now detect their type as either synchronous or asynchronous, asynchronous child mocks will be AsyncMocks and synchronous child mocks will be either MagicMock or Mock (depending on their parent type).

bpo-38161 [https://bugs.python.org/issue?@action=redirect&bpo=38161]: Removes _AwaitEvent from AsyncMock.

bpo-38216 [https://bugs.python.org/issue?@action=redirect&bpo=38216]: Allow the rare code that wants to send invalid http requests from the http.client library a way to do so. The fixes for bpo-30458 [https://bugs.python.org/issue?@action=redirect&bpo=30458] led to breakage for some projects that were relying on this ability to test their own behavior in the face of bad requests.

bpo-28286 [https://bugs.python.org/issue?@action=redirect&bpo=28286]: Deprecate opening GzipFile for writing implicitly. Always specify the mode argument for writing.

bpo-38108 [https://bugs.python.org/issue?@action=redirect&bpo=38108]: Any synchronous magic methods on an AsyncMock now return a MagicMock. Any asynchronous magic methods on a MagicMock now return an AsyncMock.

bpo-38265 [https://bugs.python.org/issue?@action=redirect&bpo=38265]: Update the length parameter of os.pread() to accept Py_ssize_t instead of int.

bpo-38112 [https://bugs.python.org/issue?@action=redirect&bpo=38112]: compileall has a higher default recursion limit and new command-line arguments for path manipulation, symlinks handling, and multiple optimization levels.

bpo-38248 [https://bugs.python.org/issue?@action=redirect&bpo=38248]: asyncio: Fix inconsistent immediate Task cancellation

bpo-38237 [https://bugs.python.org/issue?@action=redirect&bpo=38237]: The arguments for the builtin pow function are more descriptive. They can now also be passed in as keywords.

bpo-34002 [https://bugs.python.org/issue?@action=redirect&bpo=34002]: Improve efficiency in parts of email package by changing while-pop to a for loop, using isdisjoint instead of set intersections.

bpo-38191 [https://bugs.python.org/issue?@action=redirect&bpo=38191]: Constructors of NamedTuple and TypedDict types now accept arbitrary keyword argument names, including «cls», «self», «typename», «_typename», «fields» and «_fields».

bpo-38155 [https://bugs.python.org/issue?@action=redirect&bpo=38155]: Add __all__ to datetime. Patch by Tahia Khan.

bpo-38185 [https://bugs.python.org/issue?@action=redirect&bpo=38185]: Fixed case-insensitive string comparison in sqlite3.Row indexing.

bpo-38136 [https://bugs.python.org/issue?@action=redirect&bpo=38136]: Changes AsyncMock call count and await count to be two different counters. Now await count only counts when a coroutine has been awaited, not when it has been called, and vice-versa. Update the documentation around this.

bpo-37828 [https://bugs.python.org/issue?@action=redirect&bpo=37828]: Fix default mock name in unittest.mock.Mock.assert_called() exceptions. Patch by Abraham Toriz Cruz.

bpo-38175 [https://bugs.python.org/issue?@action=redirect&bpo=38175]: Fix a memory leak in comparison of sqlite3.Row objects.

bpo-33936 [https://bugs.python.org/issue?@action=redirect&bpo=33936]: _hashlib no longer calls obsolete OpenSSL initialization function with OpenSSL 1.1.0+.

bpo-34706 [https://bugs.python.org/issue?@action=redirect&bpo=34706]: Preserve subclassing in inspect.Signature.from_callable.

bpo-38153 [https://bugs.python.org/issue?@action=redirect&bpo=38153]: Names of hashing algorithms from OpenSSL are now normalized to follow Python’s naming conventions. For example OpenSSL uses sha3-512 instead of sha3_512 or blake2b512 instead of blake2b.

bpo-38115 [https://bugs.python.org/issue?@action=redirect&bpo=38115]: Fix a bug in dis.findlinestarts() where it would return invalid bytecode offsets. Document that a code object’s co_lnotab can contain invalid bytecode offsets.

bpo-38148 [https://bugs.python.org/issue?@action=redirect&bpo=38148]: Add slots to asyncio transport classes, which can reduce memory usage.

bpo-38142 [https://bugs.python.org/issue?@action=redirect&bpo=38142]: The _hashlib OpenSSL wrapper extension module is now PEP-384 compliant.

bpo-9216 [https://bugs.python.org/issue?@action=redirect&bpo=9216]: hashlib constructors now support usedforsecurity flag to signal that a hashing algorithm is not used in a security context.

bpo-36991 [https://bugs.python.org/issue?@action=redirect&bpo=36991]: Fixes a potential incorrect AttributeError exception escaping ZipFile.extract() in some unsupported input error situations.

bpo-38134 [https://bugs.python.org/issue?@action=redirect&bpo=38134]: Remove obsolete copy of PBKDF2_HMAC_fast. All supported OpenSSL versions contain a fast implementation.

bpo-38132 [https://bugs.python.org/issue?@action=redirect&bpo=38132]: The OpenSSL hashlib wrapper uses a simpler implementation. Several Macros and pointless caches are gone. The hash name now comes from OpenSSL’s EVP. The algorithm name stays the same, except it is now always lower case.

bpo-38008 [https://bugs.python.org/issue?@action=redirect&bpo=38008]: Fix parent class check in protocols to correctly identify the module that provides a builtin protocol, instead of assuming they all come from the collections.abc module

bpo-34037 [https://bugs.python.org/issue?@action=redirect&bpo=34037]: For asyncio, add a new coroutine loop.shutdown_default_executor(). The new coroutine provides an API to schedule an executor shutdown that waits on the threadpool to finish closing. Also, asyncio.run() has been updated to utilize the new coroutine. Patch by Kyle Stanley.

bpo-37405 [https://bugs.python.org/issue?@action=redirect&bpo=37405]: Fixed regression bug for socket.getsockname() for non-CAN_ISOTP AF_CAN address family sockets by returning a 1-tuple instead of string.

bpo-38121 [https://bugs.python.org/issue?@action=redirect&bpo=38121]: Update parameter names on functions in importlib.metadata matching the changes in the 0.22 release of importlib_metadata.

bpo-38110 [https://bugs.python.org/issue?@action=redirect&bpo=38110]: The os.closewalk() implementation now uses the libc fdwalk() API on platforms where it is available.

bpo-38093 [https://bugs.python.org/issue?@action=redirect&bpo=38093]: Fixes AsyncMock so it doesn’t crash when used with AsyncContextManagers or AsyncIterators.

bpo-37488 [https://bugs.python.org/issue?@action=redirect&bpo=37488]: Add warning to datetime.utctimetuple(), datetime.utcnow() and datetime.utcfromtimestamp() .

bpo-35640 [https://bugs.python.org/issue?@action=redirect&bpo=35640]: Allow passing a path-like object as directory argument to the http.server.SimpleHTTPRequestHandler class. Patch by Géry Ogam.

bpo-38086 [https://bugs.python.org/issue?@action=redirect&bpo=38086]: Update importlib.metadata with changes from importlib_metadata 0.21 [https://gitlab.com/python-devs/importlib_metadata/blob/0.21/importlib_metadata/docs/changelog.rst].

bpo-37251 [https://bugs.python.org/issue?@action=redirect&bpo=37251]: Remove __code__ check in AsyncMock that incorrectly evaluated function specs as async objects but failed to evaluate classes with __await__ but no __code__ attribute defined as async objects.

bpo-38037 [https://bugs.python.org/issue?@action=redirect&bpo=38037]: Fix reference counters in the signal module.

bpo-38066 [https://bugs.python.org/issue?@action=redirect&bpo=38066]: Hide internal asyncio.Stream methods: feed_eof(), feed_data(), set_exception() and set_transport().

bpo-38059 [https://bugs.python.org/issue?@action=redirect&bpo=38059]: inspect.py now uses sys.exit() instead of exit()

bpo-38049 [https://bugs.python.org/issue?@action=redirect&bpo=38049]: Added command-line interface for the ast module.

bpo-37953 [https://bugs.python.org/issue?@action=redirect&bpo=37953]: In typing, improved the __hash__ and __eq__ methods for ForwardReferences.

bpo-38026 [https://bugs.python.org/issue?@action=redirect&bpo=38026]: Fixed inspect.getattr_static() used isinstance while it should avoid dynamic lookup.

bpo-35923 [https://bugs.python.org/issue?@action=redirect&bpo=35923]: Update importlib.machinery.BuiltinImporter to use loader._ORIGIN instead of a hardcoded value. Patch by Dong-hee Na.

bpo-38010 [https://bugs.python.org/issue?@action=redirect&bpo=38010]: In importlib.metadata sync with importlib_metadata 0.20, clarifying behavior of files() and fixing issue where only one requirement was returned for requires() on dist-info packages.

bpo-38006 [https://bugs.python.org/issue?@action=redirect&bpo=38006]: weakref.WeakValueDictionary defines a local remove() function used as callback for weak references. This function was created with a closure. Modify the implementation to avoid the closure.

bpo-37995 [https://bugs.python.org/issue?@action=redirect&bpo=37995]: Added the indent option to ast.dump() which allows it to produce a multiline indented output.

bpo-34410 [https://bugs.python.org/issue?@action=redirect&bpo=34410]: Fixed a crash in the tee() iterator when re-enter it. RuntimeError is now raised in this case.

bpo-37140 [https://bugs.python.org/issue?@action=redirect&bpo=37140]: Fix a ctypes regression of Python 3.8. When a ctypes.Structure is passed by copy to a function, ctypes internals created a temporary object which had the side effect of calling the structure finalizer (__del__) twice. The Python semantics requires a finalizer to be called exactly once. Fix ctypes internals to no longer call the finalizer twice.

bpo-37587 [https://bugs.python.org/issue?@action=redirect&bpo=37587]: _json.scanstring is now up to 3x faster when there are many backslash escaped characters in the JSON string.

bpo-37834 [https://bugs.python.org/issue?@action=redirect&bpo=37834]: Prevent shutil.rmtree exception when built on non-Windows system without fd system call support, like older versions of macOS.

bpo-10978 [https://bugs.python.org/issue?@action=redirect&bpo=10978]: Semaphores and BoundedSemaphores can now release more than one waiting thread at a time.

bpo-37972 [https://bugs.python.org/issue?@action=redirect&bpo=37972]: Subscripts to the unittest.mock.call objects now receive the same chaining mechanism as any other custom attributes, so that the following usage no longer raises a TypeError:

call().foo().__getitem__(“bar”)

Patch by blhsing

bpo-37965 [https://bugs.python.org/issue?@action=redirect&bpo=37965]: Fix C compiler warning caused by distutils.ccompiler.CCompiler.has_function.

bpo-37964 [https://bugs.python.org/issue?@action=redirect&bpo=37964]: Add F_GETPATH command to fcntl.

bpo-37960 [https://bugs.python.org/issue?@action=redirect&bpo=37960]: repr() of buffered and text streams now silences only expected exceptions when get the value of «name» and «mode» attributes.

bpo-37961 [https://bugs.python.org/issue?@action=redirect&bpo=37961]: Add a total_nframe field to the traces collected by the tracemalloc module. This field indicates the original number of frames before it was truncated.

bpo-37951 [https://bugs.python.org/issue?@action=redirect&bpo=37951]: Most features of the subprocess module now work again in subinterpreters. Only preexec_fn is restricted in subinterpreters.

bpo-36205 [https://bugs.python.org/issue?@action=redirect&bpo=36205]: Fix the rusage implementation of time.process_time() to correctly report the sum of the system and user CPU time.

bpo-37950 [https://bugs.python.org/issue?@action=redirect&bpo=37950]: Fix ast.dump() when call with incompletely initialized node.

bpo-34679 [https://bugs.python.org/issue?@action=redirect&bpo=34679]: Restores instantiation of Windows IOCP event loops from the non-main thread.

bpo-36917 [https://bugs.python.org/issue?@action=redirect&bpo=36917]: Add default implementation of the ast.NodeVisitor.visit_Constant() method which emits a deprecation warning and calls corresponding methody visit_Num(), visit_Str(), etc.

bpo-37798 [https://bugs.python.org/issue?@action=redirect&bpo=37798]: Update test_statistics.py to verify that the statistics module works well for both C and Python implementations. Patch by Dong-hee Na

bpo-26589 [https://bugs.python.org/issue?@action=redirect&bpo=26589]: Added a new status code to the http module: 451 UNAVAILABLE_FOR_LEGAL_REASONS

bpo-37915 [https://bugs.python.org/issue?@action=redirect&bpo=37915]: Fix a segmentation fault that appeared when comparing instances of datetime.timezone and datetime.tzinfo objects. Patch by Pablo Galindo.

bpo-32554 [https://bugs.python.org/issue?@action=redirect&bpo=32554]: Deprecate having random.seed() call hash on arbitrary types.

bpo-9938 [https://bugs.python.org/issue?@action=redirect&bpo=9938]: Add optional keyword argument exit_on_error for ArgumentParser.

bpo-37851 [https://bugs.python.org/issue?@action=redirect&bpo=37851]: The faulthandler module no longer allocates its alternative stack at Python startup. Now the stack is only allocated at the first faulthandler usage.

bpo-32793 [https://bugs.python.org/issue?@action=redirect&bpo=32793]: Fix a duplicated debug message when smtplib.SMTP.connect() is called.

bpo-37885 [https://bugs.python.org/issue?@action=redirect&bpo=37885]: venv: Don’t generate unset variable warning on deactivate.

bpo-37868 [https://bugs.python.org/issue?@action=redirect&bpo=37868]: Fix dataclasses.is_dataclass when given an instance that never raises AttributeError in __getattr__. That is, an object that returns something for __dataclass_fields__ even if it’s not a dataclass.

bpo-37811 [https://bugs.python.org/issue?@action=redirect&bpo=37811]: Fix socket module’s socket.connect(address) function being unable to establish connection in case of interrupted system call. The problem was observed on all OSes which poll(2) system call can take only non-negative integers and -1 as a timeout value.

bpo-37863 [https://bugs.python.org/issue?@action=redirect&bpo=37863]: Optimizations for Fraction.__hash__ suggested by Tim Peters.

bpo-21131 [https://bugs.python.org/issue?@action=redirect&bpo=21131]: Fix faulthandler.register(chain=True) stack. faulthandler now allocates a dedicated stack of SIGSTKSZ*2 bytes, instead of just SIGSTKSZ bytes. Calling the previous signal handler in faulthandler signal handler uses more than SIGSTKSZ bytes of stack memory on some platforms.

bpo-37798 [https://bugs.python.org/issue?@action=redirect&bpo=37798]: Add C fastpath for statistics.NormalDist.inv_cdf() Patch by Dong-hee Na

bpo-37804 [https://bugs.python.org/issue?@action=redirect&bpo=37804]: Remove the deprecated method threading.Thread.isAlive(). Patch by Dong-hee Na.

bpo-37819 [https://bugs.python.org/issue?@action=redirect&bpo=37819]: Add Fraction.as_integer_ratio() to match the corresponding methods in bool, int, float, and decimal.

bpo-14465 [https://bugs.python.org/issue?@action=redirect&bpo=14465]: Add an xml.etree.ElementTree.indent() function for pretty-printing XML trees. Contributed by Stefan Behnel.

bpo-37810 [https://bugs.python.org/issue?@action=redirect&bpo=37810]: Fix difflib ? hint in diff output when dealing with tabs. Patch by Anthony Sottile.

bpo-37772 [https://bugs.python.org/issue?@action=redirect&bpo=37772]: In zipfile.Path, when adding implicit dirs, ensure that ancestral directories are added and that duplicates are excluded.

bpo-18578 [https://bugs.python.org/issue?@action=redirect&bpo=18578]: Renamed and documented test.bytecode_helper as test.support.bytecode_helper. Patch by Joannah Nanjekye.

bpo-37785 [https://bugs.python.org/issue?@action=redirect&bpo=37785]: Fix xgettext warnings in argparse.

bpo-34488 [https://bugs.python.org/issue?@action=redirect&bpo=34488]: writelines() method of io.BytesIO is now slightly faster when many small lines are passed. Patch by Sergey Fedoseev.

bpo-37449 [https://bugs.python.org/issue?@action=redirect&bpo=37449]: ensurepip now uses importlib.resources.read_binary() to read data instead of pkgutil.get_data(). Patch by Joannah Nanjekye.

bpo-28292 [https://bugs.python.org/issue?@action=redirect&bpo=28292]: Mark calendar.py helper functions as being private. The follows PEP 8 guidance to maintain the style conventions in the module and it addresses a known case of user confusion.

bpo-18049 [https://bugs.python.org/issue?@action=redirect&bpo=18049]: Add definition of THREAD_STACK_SIZE for AIX in Python/thread_pthread.h The default thread stacksize caused crashes with the default recursion limit Patch by M Felt

bpo-37742 [https://bugs.python.org/issue?@action=redirect&bpo=37742]: The logging.getLogger() API now returns the root logger when passed the name “root”, whereas previously it returned a non-root logger named “root”. This could affect cases where user code explicitly wants a non-root logger named “root”, or instantiates a logger using logging.getLogger(__name__) in some top-level module called “root.py”.

bpo-37738 [https://bugs.python.org/issue?@action=redirect&bpo=37738]: Fix the implementation of curses addch(str, color_pair): pass the color pair to setcchar(), instead of always passing 0 as the color pair.

bpo-37723 [https://bugs.python.org/issue?@action=redirect&bpo=37723]: Fix performance regression on regular expression parsing with huge character sets. Patch by Yann Vaginay.

bpo-35943 [https://bugs.python.org/issue?@action=redirect&bpo=35943]: The function PyImport_GetModule() now ensures any module it returns is fully initialized. Patch by Joannah Nanjekye.

bpo-32178 [https://bugs.python.org/issue?@action=redirect&bpo=32178]: Fix IndexError in email package when trying to parse invalid address fields starting with :.

bpo-37268 [https://bugs.python.org/issue?@action=redirect&bpo=37268]: The parser module is deprecated and will be removed in future versions of Python.

bpo-11953 [https://bugs.python.org/issue?@action=redirect&bpo=11953]: Completing WSA* error codes in socket.

bpo-37685 [https://bugs.python.org/issue?@action=redirect&bpo=37685]: Fixed comparisons of datetime.timedelta and datetime.timezone.

bpo-37697 [https://bugs.python.org/issue?@action=redirect&bpo=37697]: Synchronize importlib.metadata with importlib_metadata 0.19 [https://gitlab.com/python-devs/importlib_metadata/-/milestones/20], improving handling of EGG-INFO files and fixing a crash when entry point names contained colons.

bpo-37695 [https://bugs.python.org/issue?@action=redirect&bpo=37695]: Correct curses.unget_wch() error message. Patch by Anthony Sottile.

bpo-37689 [https://bugs.python.org/issue?@action=redirect&bpo=37689]: Add is_relative_to() in PurePath to determine whether or not one path is relative to another.

bpo-29553 [https://bugs.python.org/issue?@action=redirect&bpo=29553]: Fixed argparse.ArgumentParser.format_usage() for mutually exclusive groups. Patch by Andrew Nester.

bpo-37691 [https://bugs.python.org/issue?@action=redirect&bpo=37691]: Let math.dist() accept coordinates as sequences (or iterables) rather than just tuples.

bpo-37685 [https://bugs.python.org/issue?@action=redirect&bpo=37685]: Fixed __eq__, __lt__ etc implementations in some classes. They now return NotImplemented for unsupported type of the other operand. This allows the other operand to play role (for example the equality comparison with ANY will return True).

bpo-37354 [https://bugs.python.org/issue?@action=redirect&bpo=37354]: Make Activate.ps1 Powershell script static to allow for signing it.

bpo-37664 [https://bugs.python.org/issue?@action=redirect&bpo=37664]: Update wheels bundled with ensurepip (pip 19.2.3 and setuptools 41.2.0)

bpo-37663 [https://bugs.python.org/issue?@action=redirect&bpo=37663]: Bring consistency to venv shell activation scripts by always using __VENV_PROMPT__.

bpo-37642 [https://bugs.python.org/issue?@action=redirect&bpo=37642]: Allowed the pure Python implementation of datetime.timezone to represent sub-minute offsets close to minimum and maximum boundaries, specifically in the ranges (23:59, 24:00) and (-23:59, 24:00). Patch by Ngalim Siregar

bpo-36161 [https://bugs.python.org/issue?@action=redirect&bpo=36161]: In posix, use ttyname_r instead of ttyname for thread safety.

bpo-36324 [https://bugs.python.org/issue?@action=redirect&bpo=36324]: Make internal attributes for statistics.NormalDist() private.

bpo-37555 [https://bugs.python.org/issue?@action=redirect&bpo=37555]: Fix NonCallableMock._call_matcher returning tuple instead of _Call object when self._spec_signature exists. Patch by Elizabeth Uselton

bpo-29446 [https://bugs.python.org/issue?@action=redirect&bpo=29446]: Make from tkinter import * import only the expected objects.

bpo-16970 [https://bugs.python.org/issue?@action=redirect&bpo=16970]: Adding a value error when an invalid value in passed to nargs Patch by Robert Leenders

bpo-34443 [https://bugs.python.org/issue?@action=redirect&bpo=34443]: Exceptions from enum now use the __qualname of the enum class in the exception message instead of the __name__.

bpo-37491 [https://bugs.python.org/issue?@action=redirect&bpo=37491]: Fix IndexError when parsing email headers with unexpectedly ending bare-quoted string value. Patch by Abhilash Raj.

bpo-37587 [https://bugs.python.org/issue?@action=redirect&bpo=37587]: Make json.loads faster for long strings. (Patch by Marco Paolini)

bpo-18378 [https://bugs.python.org/issue?@action=redirect&bpo=18378]: Recognize «UTF-8» as a valid value for LC_CTYPE in locale._parse_localename.

bpo-37579 [https://bugs.python.org/issue?@action=redirect&bpo=37579]: Return NotImplemented in Python implementation of __eq__ for timedelta and time when the other object being compared is not of the same type to match C implementation. Patch by Karthikeyan Singaravelan.

bpo-21478 [https://bugs.python.org/issue?@action=redirect&bpo=21478]: Record calls to parent when autospecced object is attached to a mock using unittest.mock.attach_mock(). Patch by Karthikeyan Singaravelan.

bpo-37531 [https://bugs.python.org/issue?@action=redirect&bpo=37531]: «python3 -m test -jN –timeout=TIMEOUT» now kills a worker process if it runs longer than TIMEOUT seconds.

bpo-37482 [https://bugs.python.org/issue?@action=redirect&bpo=37482]: Fix serialization of display name in originator or destination address fields with both encoded words and special chars.

bpo-36993 [https://bugs.python.org/issue?@action=redirect&bpo=36993]: Improve error reporting for corrupt zip files with bad zip64 extra data. Patch by Daniel Hillier.

bpo-37502 [https://bugs.python.org/issue?@action=redirect&bpo=37502]: pickle.loads() no longer raises TypeError when the buffers argument is set to None

bpo-37520 [https://bugs.python.org/issue?@action=redirect&bpo=37520]: Correct behavior for zipfile.Path.parent when the path object identifies a subdirectory.

bpo-18374 [https://bugs.python.org/issue?@action=redirect&bpo=18374]: Fix the .col_offset attribute of nested ast.BinOp instances which had a too large value in some situations.

bpo-37424 [https://bugs.python.org/issue?@action=redirect&bpo=37424]: Fixes a possible hang when using a timeout on subprocess.run() while capturing output. If the child process spawned its own children or otherwise connected its stdout or stderr handles with another process, we could hang after the timeout was reached and our child was killed when attempting to read final output from the pipes.

bpo-37421 [https://bugs.python.org/issue?@action=redirect&bpo=37421]: Fix multiprocessing.util.get_temp_dir() finalizer: clear also the “tempdir” configuration of the current process, so next call to get_temp_dir() will create a new temporary directory, rather than reusing the removed temporary directory.

bpo-37481 [https://bugs.python.org/issue?@action=redirect&bpo=37481]: The distutils bdist_wininst command is deprecated in Python 3.8, use bdist_wheel (wheel packages) instead.

bpo-37479 [https://bugs.python.org/issue?@action=redirect&bpo=37479]: When Enum.__str__ is overridden in a derived class, the override will be used by Enum.__format__ regardless of whether mixin classes are present.

bpo-37440 [https://bugs.python.org/issue?@action=redirect&bpo=37440]: http.client now enables TLS 1.3 post-handshake authentication for default context or if a cert_file is passed to HTTPSConnection.

bpo-37437 [https://bugs.python.org/issue?@action=redirect&bpo=37437]: Update vendorized expat version to 2.2.7.

bpo-37428 [https://bugs.python.org/issue?@action=redirect&bpo=37428]: SSLContext.post_handshake_auth = True no longer sets SSL_VERIFY_POST_HANDSHAKE verify flag for client connections. Although the option is documented as ignored for clients, OpenSSL implicitly enables cert chain validation when the flag is set.

bpo-37420 [https://bugs.python.org/issue?@action=redirect&bpo=37420]: os.sched_setaffinity() now correctly handles errors that arise during iteration over its mask argument. Patch by Brandt Bucher.

bpo-37412 [https://bugs.python.org/issue?@action=redirect&bpo=37412]: The os.getcwdb() function now uses the UTF-8 encoding on Windows, rather than the ANSI code page: see PEP 529 [https://www.python.org/dev/peps/pep-0529] for the rationale. The function is no longer deprecated on Windows.

bpo-37406 [https://bugs.python.org/issue?@action=redirect&bpo=37406]: The sqlite3 module now raises TypeError, rather than ValueError, if operation argument type is not str: execute(), executemany() and calling a connection.

bpo-29412 [https://bugs.python.org/issue?@action=redirect&bpo=29412]: Fix IndexError in parsing a header value ending unexpectedly. Patch by Abhilash Raj.

bpo-36546 [https://bugs.python.org/issue?@action=redirect&bpo=36546]: The dist argument for statistics.quantiles() is now positional only. The current name doesn’t reflect that the argument can be either a dataset or a distribution. Marking the parameter as positional avoids confusion and makes it possible to change the name later.

bpo-37394 [https://bugs.python.org/issue?@action=redirect&bpo=37394]: Fix a bug that was causing the queue module to fail if the accelerator module was not available. Patch by Pablo Galindo.

bpo-37376 [https://bugs.python.org/issue?@action=redirect&bpo=37376]: pprint now has support for types.SimpleNamespace. Patch by Carl Bordum Hansen.

bpo-26967 [https://bugs.python.org/issue?@action=redirect&bpo=26967]: An ArgumentParser with allow_abbrev=False no longer disables grouping of short flags, such as -vv, but only disables abbreviation of long flags as documented. Patch by Zac Hatfield-Dodds.

bpo-37212 [https://bugs.python.org/issue?@action=redirect&bpo=37212]: unittest.mock.call() now preserves the order of keyword arguments in repr output. Patch by Karthikeyan Singaravelan.

bpo-37372 [https://bugs.python.org/issue?@action=redirect&bpo=37372]: Fix error unpickling datetime.time objects from Python 2 with seconds>=24. Patch by Justin Blanchard.

bpo-37345 [https://bugs.python.org/issue?@action=redirect&bpo=37345]: Add formal support for UDPLITE sockets. Support was present before, but it is now easier to detect support with hasattr(socket, 'IPPROTO_UDPLITE') and there are constants defined for each of the values needed: socket.IPPROTO_UDPLITE, UDPLITE_SEND_CSCOV, and UDPLITE_RECV_CSCOV. Patch by Gabe Appleton.

bpo-37358 [https://bugs.python.org/issue?@action=redirect&bpo=37358]: Optimized functools.partial by using vectorcall.

bpo-37347 [https://bugs.python.org/issue?@action=redirect&bpo=37347]: sqlite3.Connection.create_aggregate(), sqlite3.Connection.create_function(), sqlite3.Connection.set_authorizer(), sqlite3.Connection.set_progress_handler() sqlite3.Connection.set_trace_callback() methods lead to segfaults if some of these methods are called twice with an equal object but not the same. Now callbacks are stored more carefully. Patch by Aleksandr Balezin.

bpo-37163 [https://bugs.python.org/issue?@action=redirect&bpo=37163]: The obj argument of dataclasses.replace() is positional-only now.

bpo-37085 [https://bugs.python.org/issue?@action=redirect&bpo=37085]: Add the optional Linux SocketCAN Broadcast Manager constants, used as flags to configure the BCM behaviour, in the socket module. Patch by Karl Ding.

bpo-37328 [https://bugs.python.org/issue?@action=redirect&bpo=37328]: HTMLParser.unescape is removed. It was undocumented and deprecated since Python 3.4.

bpo-37305 [https://bugs.python.org/issue?@action=redirect&bpo=37305]: Add .webmanifest -> application/manifest+json to list of recognized file types and content type headers

bpo-37320 [https://bugs.python.org/issue?@action=redirect&bpo=37320]: aifc.openfp() alias to aifc.open(), sunau.openfp() alias to sunau.open(), and wave.openfp() alias to wave.open() have been removed. They were deprecated since Python 3.7.

bpo-37315 [https://bugs.python.org/issue?@action=redirect&bpo=37315]: Deprecated accepting floats with integral value (like 5.0) in math.factorial().

bpo-37312 [https://bugs.python.org/issue?@action=redirect&bpo=37312]: _dummy_thread and dummy_threading modules have been removed. These modules were deprecated since Python 3.7 which requires threading support.

bpo-33972 [https://bugs.python.org/issue?@action=redirect&bpo=33972]: Email with single part but content-type set to multipart/* doesn’t raise AttributeError anymore.

bpo-37280 [https://bugs.python.org/issue?@action=redirect&bpo=37280]: Use threadpool for reading from file for sendfile fallback mode.

bpo-37279 [https://bugs.python.org/issue?@action=redirect&bpo=37279]: Fix asyncio sendfile support when sendfile sends extra data in fallback mode.

bpo-19865 [https://bugs.python.org/issue?@action=redirect&bpo=19865]: ctypes.create_unicode_buffer() now also supports non-BMP characters on platforms with 16-bit wchar_t (for example, Windows and AIX).

bpo-37266 [https://bugs.python.org/issue?@action=redirect&bpo=37266]: In a subinterpreter, spawning a daemon thread now raises an exception. Daemon threads were never supported in subinterpreters. Previously, the subinterpreter finalization crashed with a Python fatal error if a daemon thread was still running.

bpo-37210 [https://bugs.python.org/issue?@action=redirect&bpo=37210]: Allow pure Python implementation of pickle to work even when the C _pickle module is unavailable.

bpo-21872 [https://bugs.python.org/issue?@action=redirect&bpo=21872]: Fix lzma: module decompresses data incompletely. When decompressing a FORMAT_ALONE format file, and it doesn’t have the end marker, sometimes the last one to dozens bytes can’t be output. Patch by Ma Lin.

bpo-35922 [https://bugs.python.org/issue?@action=redirect&bpo=35922]: Fix RobotFileParser.crawl_delay() and RobotFileParser.request_rate() to return None rather than raise AttributeError when no relevant rule is defined in the robots.txt file. Patch by Rémi Lapeyre.

bpo-35766 [https://bugs.python.org/issue?@action=redirect&bpo=35766]: Change the format of feature_version to be a (major, minor) tuple.

bpo-36607 [https://bugs.python.org/issue?@action=redirect&bpo=36607]: Eliminate RuntimeError raised by asyncio.all_tasks() if internal tasks weak set is changed by another thread during iteration.

bpo-18748 [https://bugs.python.org/issue?@action=redirect&bpo=18748]: _pyio.IOBase destructor now does nothing if getting the closed attribute fails to better mimic _io.IOBase finalizer.

bpo-36402 [https://bugs.python.org/issue?@action=redirect&bpo=36402]: Fix a race condition at Python shutdown when waiting for threads. Wait until the Python thread state of all non-daemon threads get deleted (join all non-daemon threads), rather than just wait until non-daemon Python threads complete.

bpo-37206 [https://bugs.python.org/issue?@action=redirect&bpo=37206]: Default values which cannot be represented as Python objects no longer improperly represented as None in function signatures.

bpo-37111 [https://bugs.python.org/issue?@action=redirect&bpo=37111]: Added encoding and errors keyword parameters to logging.basicConfig.

bpo-12144 [https://bugs.python.org/issue?@action=redirect&bpo=12144]: Ensure cookies with expires attribute are handled in CookieJar.make_cookies().

bpo-34886 [https://bugs.python.org/issue?@action=redirect&bpo=34886]: Fix an unintended ValueError from subprocess.run() when checking for conflicting input and stdin or capture_output and stdout or stderr args when they were explicitly provided but with None values within a passed in **kwargs dict rather than as passed directly by name. Patch contributed by Rémi Lapeyre.

bpo-37173 [https://bugs.python.org/issue?@action=redirect&bpo=37173]: The exception message for inspect.getfile() now correctly reports the passed class rather than the builtins module.

bpo-37178 [https://bugs.python.org/issue?@action=redirect&bpo=37178]: Give math.perm() a one argument form that means the same as math.factorial().

bpo-37178 [https://bugs.python.org/issue?@action=redirect&bpo=37178]: For math.perm(n, k), let k default to n, giving the same result as factorial.

bpo-37165 [https://bugs.python.org/issue?@action=redirect&bpo=37165]: Converted _collections._count_elements to use the Argument Clinic.

bpo-34767 [https://bugs.python.org/issue?@action=redirect&bpo=34767]: Do not always create a collections.deque in asyncio.Lock.

bpo-37158 [https://bugs.python.org/issue?@action=redirect&bpo=37158]: Speed-up statistics.fmean() by switching from a function to a generator.

bpo-34282 [https://bugs.python.org/issue?@action=redirect&bpo=34282]: Remove Enum._convert method, deprecated in 3.8.

bpo-37150 [https://bugs.python.org/issue?@action=redirect&bpo=37150]: argparse._ActionsContainer.add_argument now throws error, if someone accidentally pass FileType class object instead of instance of FileType as type argument

bpo-28724 [https://bugs.python.org/issue?@action=redirect&bpo=28724]: The socket module now has the socket.send_fds() and socket.recv.fds() methods. Contributed by Joannah Nanjekye, Shinya Okano and Victor Stinner.

bpo-35621 [https://bugs.python.org/issue?@action=redirect&bpo=35621]: Support running asyncio subprocesses when execution event loop in a thread on UNIX.

bpo-36520 [https://bugs.python.org/issue?@action=redirect&bpo=36520]: Lengthy email headers with UTF-8 characters are now properly encoded when they are folded. Patch by Jeffrey Kintscher.

bpo-30835 [https://bugs.python.org/issue?@action=redirect&bpo=30835]: Fixed a bug in email parsing where a message with invalid bytes in content-transfer-encoding of a multipart message can cause an AttributeError. Patch by Andrew Donnellan.

bpo-31163 [https://bugs.python.org/issue?@action=redirect&bpo=31163]: pathlib.Path instance’s rename and replace methods now return the new Path instance.

bpo-25068 [https://bugs.python.org/issue?@action=redirect&bpo=25068]: urllib.request.ProxyHandler now lowercases the keys of the passed dictionary.

bpo-26185 [https://bugs.python.org/issue?@action=redirect&bpo=26185]: Fix repr() on empty ZipInfo object. Patch by Mickaël Schoentgen.

bpo-21315 [https://bugs.python.org/issue?@action=redirect&bpo=21315]: Email headers containing RFC2047 encoded words are parsed despite the missing whitespace, and a defect registered. Also missing trailing whitespace after encoded words is now registered as a defect.

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Port test_datetime to VxWorks: skip zoneinfo tests on VxWorks

bpo-35805 [https://bugs.python.org/issue?@action=redirect&bpo=35805]: Add parser for Message-ID header and add it to default HeaderRegistry. This should prevent folding of Message-ID using RFC 2048 encoded words.

bpo-36871 [https://bugs.python.org/issue?@action=redirect&bpo=36871]: Ensure method signature is used instead of constructor signature of a class while asserting mock object against method calls. Patch by Karthikeyan Singaravelan.

bpo-35070 [https://bugs.python.org/issue?@action=redirect&bpo=35070]: posix.getgrouplist() now works correctly when the user belongs to NGROUPS_MAX supplemental groups. Patch by Jeffrey Kintscher.

bpo-31783 [https://bugs.python.org/issue?@action=redirect&bpo=31783]: Fix race condition in ThreadPoolExecutor when worker threads are created during interpreter shutdown.

bpo-36582 [https://bugs.python.org/issue?@action=redirect&bpo=36582]: Fix UserString.encode() to correctly return bytes rather than a UserString instance.

bpo-32424 [https://bugs.python.org/issue?@action=redirect&bpo=32424]: Deprecate xml.etree.ElementTree.Element.copy() in favor of copy.copy().

Patch by Gordon P. Hemsley

bpo-36564 [https://bugs.python.org/issue?@action=redirect&bpo=36564]: Fix infinite loop in email header folding logic that would be triggered when an email policy’s max_line_length is not long enough to include the required markup and any values in the message. Patch by Paul Ganssle

bpo-36543 [https://bugs.python.org/issue?@action=redirect&bpo=36543]: Removed methods Element.getchildren(), Element.getiterator() and ElementTree.getiterator() and the xml.etree.cElementTree module.

bpo-36409 [https://bugs.python.org/issue?@action=redirect&bpo=36409]: Remove the old plistlib API deprecated in Python 3.4

bpo-36302 [https://bugs.python.org/issue?@action=redirect&bpo=36302]: distutils sorts source file lists so that Extension .so files build more reproducibly by default

bpo-36250 [https://bugs.python.org/issue?@action=redirect&bpo=36250]: Ignore ValueError from signal with interaction in non-main thread.

bpo-36046 [https://bugs.python.org/issue?@action=redirect&bpo=36046]: Added user, group and extra_groups parameters to the subprocess.Popen constructor. Patch by Patrick McLean.

bpo-32627 [https://bugs.python.org/issue?@action=redirect&bpo=32627]: Fix compile error when _uuid headers conflicting included.

bpo-35800 [https://bugs.python.org/issue?@action=redirect&bpo=35800]: Deprecate smtpd.MailmanProxy ready for future removal.

bpo-35168 [https://bugs.python.org/issue?@action=redirect&bpo=35168]: shlex.shlex.punctuation_chars is now a read-only property.

bpo-8538 [https://bugs.python.org/issue?@action=redirect&bpo=8538]: Add support for boolean actions like --foo and --no-foo to argparse. Patch contributed by Rémi Lapeyre.

bpo-20504 [https://bugs.python.org/issue?@action=redirect&bpo=20504]: Fixes a bug in cgi module when a multipart/form-data request has no Content-Length header.

bpo-25988 [https://bugs.python.org/issue?@action=redirect&bpo=25988]: The abstract base classes in collections.abc no longer are exposed in the regular collections module.

bpo-11122 [https://bugs.python.org/issue?@action=redirect&bpo=11122]: Distutils won’t check for rpmbuild in specified paths only.

bpo-34775 [https://bugs.python.org/issue?@action=redirect&bpo=34775]: Division handling of PurePath now returns NotImplemented instead of raising a TypeError when passed something other than an instance of str or PurePath. Patch by Roger Aiudi.

bpo-34749 [https://bugs.python.org/issue?@action=redirect&bpo=34749]: binascii.a2b_base64() is now up to 2 times faster. Patch by Sergey Fedoseev.

bpo-34519 [https://bugs.python.org/issue?@action=redirect&bpo=34519]: Add additional aliases for HP Roman 8. Patch by Michael Osipov.

bpo-28009 [https://bugs.python.org/issue?@action=redirect&bpo=28009]: Fix uuid.getnode() on platforms with “.” as MAC Addr delimiter as well fix for MAC Addr format that omits a leading 0 in MAC Addr values. Currently, AIX is the only know platform with these settings. Patch by Michael Felt.

bpo-30618 [https://bugs.python.org/issue?@action=redirect&bpo=30618]: Add readlink(). Patch by Girts Folkmanis.

bpo-32498 [https://bugs.python.org/issue?@action=redirect&bpo=32498]: Made urllib.parse.unquote() accept bytes in addition to strings. Patch by Stein Karlsen.

bpo-33348 [https://bugs.python.org/issue?@action=redirect&bpo=33348]: lib2to3 now recognizes expressions after * and ** like in f(*[] or []).

bpo-32689 [https://bugs.python.org/issue?@action=redirect&bpo=32689]: Update shutil.move() function to allow for Path objects to be used as source argument. Patch by Emily Morehouse and Maxwell «5.13b» McKinnon.

bpo-32820 [https://bugs.python.org/issue?@action=redirect&bpo=32820]: Added __format__ to IPv4 and IPv6 classes. Always outputs a fully zero- padded string. Supports b/x/n modifiers (bin/hex/native format). Native format for IPv4 is bin, native format for IPv6 is hex. Also supports “#” and “_” modifiers.

bpo-27657 [https://bugs.python.org/issue?@action=redirect&bpo=27657]: Fix urllib.parse.urlparse() with numeric paths. A string like «path:80» is no longer parsed as a path but as a scheme («path») and a path («80»).

bpo-4963 [https://bugs.python.org/issue?@action=redirect&bpo=4963]: Fixed non-deterministic behavior related to mimetypes extension mapping and module reinitialization.

Documentation

bpo-21767 [https://bugs.python.org/issue?@action=redirect&bpo=21767]: Explicitly mention abc support in functools.singledispatch

bpo-38816 [https://bugs.python.org/issue?@action=redirect&bpo=38816]: Provides more details about the interaction between fork() and CPython’s runtime, focusing just on the C-API. This includes cautions about where fork() should and shouldn’t be called.

bpo-38351 [https://bugs.python.org/issue?@action=redirect&bpo=38351]: Modernize email examples from %-formatting to f-strings.

bpo-38778 [https://bugs.python.org/issue?@action=redirect&bpo=38778]: Document the fact that RuntimeError is raised if os.fork() is called in a subinterpreter.

bpo-38592 [https://bugs.python.org/issue?@action=redirect&bpo=38592]: Add Brazilian Portuguese to the language switcher at Python Documentation website.

bpo-38294 [https://bugs.python.org/issue?@action=redirect&bpo=38294]: Add list of no-longer-escaped chars to re.escape documentation

bpo-38053 [https://bugs.python.org/issue?@action=redirect&bpo=38053]: Modernized the plistlib documentation

bpo-26868 [https://bugs.python.org/issue?@action=redirect&bpo=26868]: Fix example usage of PyModule_AddObject() to properly handle errors.

bpo-36797 [https://bugs.python.org/issue?@action=redirect&bpo=36797]: Fix a dead link in the distutils API Reference.

bpo-37977 [https://bugs.python.org/issue?@action=redirect&bpo=37977]: Warn more strongly and clearly about pickle insecurity

bpo-37979 [https://bugs.python.org/issue?@action=redirect&bpo=37979]: Added a link to dateutil.parser.isoparse in the datetime.fromisoformat documentation. Patch by Paul Ganssle

bpo-12707 [https://bugs.python.org/issue?@action=redirect&bpo=12707]: Deprecate info(), geturl(), getcode() methods in favor of the headers, url, and status properties, respectively, for HTTPResponse and addinfourl. Also deprecate the code attribute of addinfourl in favor of the status attribute. Patch by Ashwin Ramaswami

bpo-37937 [https://bugs.python.org/issue?@action=redirect&bpo=37937]: Mention frame.f_trace in sys.settrace() docs.

bpo-37878 [https://bugs.python.org/issue?@action=redirect&bpo=37878]: Make PyThreadState_DeleteCurrent() Internal.

bpo-37759 [https://bugs.python.org/issue?@action=redirect&bpo=37759]: Beginning edits to Whatsnew 3.8

bpo-37726 [https://bugs.python.org/issue?@action=redirect&bpo=37726]: Stop recommending getopt in the tutorial for command line argument parsing and promote argparse.

bpo-32910 [https://bugs.python.org/issue?@action=redirect&bpo=32910]: Remove implementation-specific behaviour of how venv’s Deactivate works.

bpo-37256 [https://bugs.python.org/issue?@action=redirect&bpo=37256]: Fix wording of arguments for Request in urllib.request

bpo-37284 [https://bugs.python.org/issue?@action=redirect&bpo=37284]: Add a brief note to indicate that any new sys.implementation required attributes must go through the PEP process.

bpo-30088 [https://bugs.python.org/issue?@action=redirect&bpo=30088]: Documented that mailbox.Maildir constructor doesn’t attempt to verify the maildir folder layout correctness. Patch by Sviatoslav Sydorenko.

bpo-37521 [https://bugs.python.org/issue?@action=redirect&bpo=37521]: Fix importlib examples to insert any newly created modules via importlib.util.module_from_spec() immediately into sys.modules instead of after calling loader.exec_module().

Thanks to Benjamin Mintz for finding the bug.

bpo-37456 [https://bugs.python.org/issue?@action=redirect&bpo=37456]: Slash (“/”) is now part of syntax.

bpo-37487 [https://bugs.python.org/issue?@action=redirect&bpo=37487]: Fix PyList_GetItem index description to include 0.

bpo-37149 [https://bugs.python.org/issue?@action=redirect&bpo=37149]: Replace the dead link to the Tkinter 8.5 reference by John Shipman, New Mexico Tech, with a link to the archive.org copy.

bpo-37478 [https://bugs.python.org/issue?@action=redirect&bpo=37478]: Added possible exceptions to the description of os.chdir().

bpo-34903 [https://bugs.python.org/issue?@action=redirect&bpo=34903]: Documented that in datetime.datetime.strptime(), the leading zero in some two-digit formats is optional. Patch by Mike Gleen.

bpo-36260 [https://bugs.python.org/issue?@action=redirect&bpo=36260]: Add decompression pitfalls to zipfile module documentation.

bpo-37004 [https://bugs.python.org/issue?@action=redirect&bpo=37004]: In the documentation for difflib, a note was added explicitly warning that the results of SequenceMatcher’s ratio method may depend on the order of the input strings.

bpo-36960 [https://bugs.python.org/issue?@action=redirect&bpo=36960]: Restructured the datetime docs in the interest of making them more user-friendly and improving readability. Patch by Brad Solomon.

bpo-36487 [https://bugs.python.org/issue?@action=redirect&bpo=36487]: Make C-API docs clear about what the «main» interpreter is.

bpo-23460 [https://bugs.python.org/issue?@action=redirect&bpo=23460]: The documentation for decimal string formatting using the :g specifier has been updated to reflect the correct exponential notation cutoff point. Original patch contributed by Tuomas Suutari.

bpo-35803 [https://bugs.python.org/issue?@action=redirect&bpo=35803]: Document and test that tempfile functions may accept a path-like object for the dir argument. Patch by Anthony Sottile.

bpo-33944 [https://bugs.python.org/issue?@action=redirect&bpo=33944]: Added a note about the intended use of code in .pth files.

bpo-34293 [https://bugs.python.org/issue?@action=redirect&bpo=34293]: Fix the Doc/Makefile regarding PAPER environment variable and PDF builds

bpo-25237 [https://bugs.python.org/issue?@action=redirect&bpo=25237]: Add documentation for tkinter modules

Tests

bpo-38614 [https://bugs.python.org/issue?@action=redirect&bpo=38614]: Fix test_communicate() of test_asyncio.test_subprocess: use support.LONG_TIMEOUT (5 minutes), instead of just 1 minute.

bpo-38614 [https://bugs.python.org/issue?@action=redirect&bpo=38614]: Add timeout constants to test.support: LOOPBACK_TIMEOUT, INTERNET_TIMEOUT, SHORT_TIMEOUT and LONG_TIMEOUT.

bpo-38502 [https://bugs.python.org/issue?@action=redirect&bpo=38502]: test.regrtest now uses process groups in the multiprocessing mode (-jN command line option) if process groups are available: if os.setsid() and os.killpg() functions are available.

bpo-35998 [https://bugs.python.org/issue?@action=redirect&bpo=35998]: Fix a race condition in test_asyncio.test_start_tls_server_1(). Previously, there was a race condition between the test main() function which replaces the protocol and the test ServerProto protocol which sends ANSWER once it gets HELLO. Now, only the test main() function is responsible to send data, ServerProto no longer sends data.

bpo-38470 [https://bugs.python.org/issue?@action=redirect&bpo=38470]: Fix test_compileall.test_compile_dir_maxlevels() on Windows without long path support: only create 3 subdirectories instead of between 20 and 100 subdirectories.

bpo-37531 [https://bugs.python.org/issue?@action=redirect&bpo=37531]: On timeout, regrtest no longer attempts to call popen.communicate() again: it can hang until all child processes using stdout and stderr pipes completes. Kill the worker process and ignores its output. Change also the faulthandler timeout of the main process from 1 minute to 5 minutes, for Python slowest buildbots.

bpo-38239 [https://bugs.python.org/issue?@action=redirect&bpo=38239]: Fix test_gdb for Link Time Optimization (LTO) builds.

bpo-38275 [https://bugs.python.org/issue?@action=redirect&bpo=38275]: test_ssl now handles disabled TLS/SSL versions better. OpenSSL’s crypto policy and run-time settings are recognized and tests for disabled versions are skipped. Tests also accept more TLS minimum_versions for platforms that override OpenSSL’s default with strict settings.

bpo-38271 [https://bugs.python.org/issue?@action=redirect&bpo=38271]: The private keys for test_ssl were encrypted with 3DES in traditional PKCS#5 format. 3DES and the digest algorithm of PKCS#5 are blocked by some strict crypto policies. Use PKCS#8 format with AES256 encryption instead.

bpo-38270 [https://bugs.python.org/issue?@action=redirect&bpo=38270]: test.support now has a helper function to check for availability of a hash digest function. Several tests are refactored avoid MD5 and use SHA256 instead. Other tests are marked to use MD5 and skipped when MD5 is disabled.

bpo-37123 [https://bugs.python.org/issue?@action=redirect&bpo=37123]: Multiprocessing test test_mymanager() now also expects -SIGTERM, not only exitcode 0. BaseManager._finalize_manager() sends SIGTERM to the manager process if it takes longer than 1 second to stop, which happens on slow buildbots.

bpo-38212 [https://bugs.python.org/issue?@action=redirect&bpo=38212]: Multiprocessing tests: increase test_queue_feeder_donot_stop_onexc() timeout from 1 to 60 seconds.

bpo-38117 [https://bugs.python.org/issue?@action=redirect&bpo=38117]: Test with OpenSSL 1.1.1d

bpo-38018 [https://bugs.python.org/issue?@action=redirect&bpo=38018]: Increase code coverage for multiprocessing.shared_memory.

bpo-37805 [https://bugs.python.org/issue?@action=redirect&bpo=37805]: Add tests for json.dump(…, skipkeys=True). Patch by Dong-hee Na.

bpo-37531 [https://bugs.python.org/issue?@action=redirect&bpo=37531]: Enhance regrtest multiprocess timeout: write a message when killing a worker process, catch popen.kill() and popen.wait() exceptions, put a timeout on the second call to popen.communicate().

bpo-37876 [https://bugs.python.org/issue?@action=redirect&bpo=37876]: Add tests for ROT-13 codec.

bpo-36833 [https://bugs.python.org/issue?@action=redirect&bpo=36833]: Added tests for PyDateTime_xxx_GET_xxx() macros of the C API of the datetime module. Patch by Joannah Nanjekye.

bpo-37558 [https://bugs.python.org/issue?@action=redirect&bpo=37558]: Fix test_shared_memory_cleaned_after_process_termination name handling

bpo-37526 [https://bugs.python.org/issue?@action=redirect&bpo=37526]: Add test.support.catch_threading_exception(): context manager catching threading.Thread exception using threading.excepthook().

bpo-37421 [https://bugs.python.org/issue?@action=redirect&bpo=37421]: test_concurrent_futures now explicitly stops the ForkServer instance if it’s running.

bpo-37421 [https://bugs.python.org/issue?@action=redirect&bpo=37421]: multiprocessing tests now stop the ForkServer instance if it’s running: close the «alive» file descriptor to ask the server to stop and then remove its UNIX address.

bpo-37421 [https://bugs.python.org/issue?@action=redirect&bpo=37421]: test_distutils.test_build_ext() is now able to remove the temporary directory on Windows: don’t import the newly built C extension («xx») in the current process, but test it in a separated process.

bpo-37421 [https://bugs.python.org/issue?@action=redirect&bpo=37421]: test_concurrent_futures now cleans up multiprocessing to remove immediately temporary directories created by multiprocessing.util.get_temp_dir().

bpo-37421 [https://bugs.python.org/issue?@action=redirect&bpo=37421]: test_winconsoleio doesn’t leak a temporary file anymore: use tempfile.TemporaryFile() to remove it when the test completes.

bpo-37421 [https://bugs.python.org/issue?@action=redirect&bpo=37421]: multiprocessing tests now explicitly call _run_finalizers() to immediately remove temporary directories created by tests.

bpo-37421 [https://bugs.python.org/issue?@action=redirect&bpo=37421]: urllib.request tests now call urlcleanup() to remove temporary files created by urlretrieve() tests and to clear the _opener global variable set by urlopen() and functions calling indirectly urlopen().

bpo-37472 [https://bugs.python.org/issue?@action=redirect&bpo=37472]: Remove Lib/test/outstanding_bugs.py.

bpo-37199 [https://bugs.python.org/issue?@action=redirect&bpo=37199]: Fix test failures when IPv6 is unavailable or disabled.

bpo-19696 [https://bugs.python.org/issue?@action=redirect&bpo=19696]: Replace deprecated method «random.choose» with «random.choice» in «test_pkg_import.py».

bpo-37335 [https://bugs.python.org/issue?@action=redirect&bpo=37335]: Remove no longer necessary code from c locale coercion tests

bpo-37421 [https://bugs.python.org/issue?@action=redirect&bpo=37421]: Fix test_shutil to no longer leak temporary files.

bpo-37411 [https://bugs.python.org/issue?@action=redirect&bpo=37411]: Fix test_wsgiref.testEnviron() to no longer depend on the environment variables (don’t fail if «X» variable is set).

bpo-37400 [https://bugs.python.org/issue?@action=redirect&bpo=37400]: Fix test_os.test_chown(): use os.getgroups() rather than grp.getgrall() to get groups. Rename also the test to test_chown_gid().

bpo-37359 [https://bugs.python.org/issue?@action=redirect&bpo=37359]: Add –cleanup option to python3 -m test to remove test_python_* directories of previous failed jobs. Add «make cleantest» to run python3 -m test --cleanup.

bpo-37362 [https://bugs.python.org/issue?@action=redirect&bpo=37362]: test_gdb no longer fails if it gets an «unexpected» message on stderr: it now ignores stderr. The purpose of test_gdb is to test that python-gdb.py commands work as expected, not to test gdb.

bpo-35998 [https://bugs.python.org/issue?@action=redirect&bpo=35998]: Avoid TimeoutError in test_asyncio: test_start_tls_server_1()

bpo-37278 [https://bugs.python.org/issue?@action=redirect&bpo=37278]: Fix test_asyncio ProactorLoopCtrlC: join the thread to prevent leaking a running thread and leaking a reference.

bpo-37261 [https://bugs.python.org/issue?@action=redirect&bpo=37261]: Fix test.support.catch_unraisable_exception(): its __exit__() method now ignores unraisable exception raised when clearing its unraisable attribute.

bpo-37069 [https://bugs.python.org/issue?@action=redirect&bpo=37069]: regrtest now uses sys.unraisablehook() to mark a test as «environment altered» (ENV_CHANGED) if it emits an «unraisable exception». Moreover, regrtest logs a warning in this case.

Use python3 -m test --fail-env-changed to catch unraisable exceptions in tests.

bpo-37252 [https://bugs.python.org/issue?@action=redirect&bpo=37252]: Fix assertions in test_close and test_events_mask_overflow devpoll tests.

bpo-37169 [https://bugs.python.org/issue?@action=redirect&bpo=37169]: Rewrite _PyObject_IsFreed() unit tests.

bpo-37153 [https://bugs.python.org/issue?@action=redirect&bpo=37153]: test_venv.test_multiprocessing() now explicitly calls pool.terminate() to wait until the pool completes.

bpo-34001 [https://bugs.python.org/issue?@action=redirect&bpo=34001]: Make test_ssl pass with LibreSSL. LibreSSL handles minimum and maximum TLS version differently than OpenSSL.

bpo-36919 [https://bugs.python.org/issue?@action=redirect&bpo=36919]: Make test_source_encoding.test_issue2301 implementation independent. The test will work now for both CPython and IronPython.

bpo-30202 [https://bugs.python.org/issue?@action=redirect&bpo=30202]: Update test.test_importlib.test_abc to test find_spec().

bpo-28009 [https://bugs.python.org/issue?@action=redirect&bpo=28009]: Modify the test_uuid logic to test when a program is available AND can be used to obtain a MACADDR as basis for an UUID. Patch by M. Felt

bpo-34596 [https://bugs.python.org/issue?@action=redirect&bpo=34596]: Fallback to a default reason when unittest.skip() is uncalled. Patch by Naitree Zhu.

Build

bpo-38809 [https://bugs.python.org/issue?@action=redirect&bpo=38809]: On Windows, build scripts will now recognize and use python.exe from an active virtual env.

bpo-38684 [https://bugs.python.org/issue?@action=redirect&bpo=38684]: Fix _hashlib build when Blake2 is disabled, but OpenSSL supports it.

bpo-38468 [https://bugs.python.org/issue?@action=redirect&bpo=38468]: Misc/python-config.in now uses getvar() for all still existing sysconfig.get_config_var() calls. Patch by Joannah Nanjekye.

bpo-37415 [https://bugs.python.org/issue?@action=redirect&bpo=37415]: Fix stdatomic.h header check for ICC compiler: the ICC implementation lacks atomic_uintptr_t type which is needed by Python.

bpo-38301 [https://bugs.python.org/issue?@action=redirect&bpo=38301]: In Solaris family, we must be sure to use -D_REENTRANT. Patch by Jesús Cea Avión.

bpo-36002 [https://bugs.python.org/issue?@action=redirect&bpo=36002]: Locate llvm-profdata and llvm-ar binaries using AC_PATH_TOOL rather than AC_PATH_TARGET_TOOL.

bpo-37936 [https://bugs.python.org/issue?@action=redirect&bpo=37936]: The .gitignore file systematically keeps «rooted», with a non-trailing slash, all the rules that are meant to apply to files in a specific place in the repo. Previously, when the intended file to ignore happened to be at the root of the repo, we’d most often accidentally also ignore files and directories with the same name anywhere in the tree.

bpo-37760 [https://bugs.python.org/issue?@action=redirect&bpo=37760]: The Tools/unicode/makeunicodedata.py script, which is used for converting information from the Unicode Character Database into generated code and data used by the methods of str and by the unicodedata module, now handles each character’s data as a dataclass with named attributes, rather than a length-18 list of different fields.

bpo-37936 [https://bugs.python.org/issue?@action=redirect&bpo=37936]: The .gitignore file no longer applies to any files that are in fact tracked in the Git repository. Patch by Greg Price.

bpo-37725 [https://bugs.python.org/issue?@action=redirect&bpo=37725]: Change «clean» makefile target to also clean the program guided optimization (PGO) data. Previously you would have to use «make clean» and «make profile-removal», or «make clobber».

bpo-37707 [https://bugs.python.org/issue?@action=redirect&bpo=37707]: Mark some individual tests to skip when –pgo is used. The tests marked increase the PGO task time significantly and likely don’t help improve optimization of the final executable.

bpo-36044 [https://bugs.python.org/issue?@action=redirect&bpo=36044]: Reduce the number of unit tests run for the PGO generation task. This speeds up the task by a factor of about 15x. Running the full unit test suite is slow. This change may result in a slightly less optimized build since not as many code branches will be executed. If you are willing to wait for the much slower build, the old behavior can be restored using “./configure [..] PROFILE_TASK=»-m test –pgo-extended»”. We make no guarantees as to which PGO task set produces a faster build. Users who care should run their own relevant benchmarks as results can depend on the environment, workload, and compiler tool chain.

bpo-37468 [https://bugs.python.org/issue?@action=redirect&bpo=37468]: make install no longer installs wininst-*.exe files used by distutils bdist_wininst: bdist_wininst only works on Windows.

bpo-37189 [https://bugs.python.org/issue?@action=redirect&bpo=37189]: Many PyRun_XXX() functions like PyRun_String() were no longer exported in libpython38.dll by mistake. Export them again to fix the ABI compatibility.

bpo-25361 [https://bugs.python.org/issue?@action=redirect&bpo=25361]: Enables use of SSE2 instructions in Windows 32-bit build.

bpo-36210 [https://bugs.python.org/issue?@action=redirect&bpo=36210]: Update optional extension module detection for AIX. ossaudiodev and spwd are not applicable for AIX, and are no longer reported as missing. 3rd-party packaging of ncurses (with ASIS support) conflicts with officially supported AIX curses library, so configure AIX to use libcurses.a. However, skip trying to build _curses_panel.

patch by M Felt

Windows

bpo-38589 [https://bugs.python.org/issue?@action=redirect&bpo=38589]: Fixes HTML Help shortcut when Windows is not installed to C drive

bpo-38453 [https://bugs.python.org/issue?@action=redirect&bpo=38453]: Ensure ntpath.realpath() correctly resolves relative paths.

bpo-38519 [https://bugs.python.org/issue?@action=redirect&bpo=38519]: Restores the internal C headers that were missing from the nuget.org and Microsoft Store packages.

bpo-38492 [https://bugs.python.org/issue?@action=redirect&bpo=38492]: Remove pythonw.exe dependency on the Microsoft C++ runtime.

bpo-38344 [https://bugs.python.org/issue?@action=redirect&bpo=38344]: Fix error message in activate.bat

bpo-38359 [https://bugs.python.org/issue?@action=redirect&bpo=38359]: Ensures pyw.exe launcher reads correct registry key.

bpo-38355 [https://bugs.python.org/issue?@action=redirect&bpo=38355]: Fixes ntpath.realpath failing on sys.executable.

bpo-38117 [https://bugs.python.org/issue?@action=redirect&bpo=38117]: Update bundled OpenSSL to 1.1.1d

bpo-38092 [https://bugs.python.org/issue?@action=redirect&bpo=38092]: Reduce overhead when using multiprocessing in a Windows virtual environment.

bpo-38133 [https://bugs.python.org/issue?@action=redirect&bpo=38133]: Allow py.exe launcher to locate installations from the Microsoft Store and improve display of active virtual environments.

bpo-38114 [https://bugs.python.org/issue?@action=redirect&bpo=38114]: The pip.ini is no longer included in the Nuget package.

bpo-32592 [https://bugs.python.org/issue?@action=redirect&bpo=32592]: Set Windows 8 as the minimum required version for API support

bpo-36634 [https://bugs.python.org/issue?@action=redirect&bpo=36634]: os.cpu_count() now returns active processors rather than maximum processors.

bpo-36634 [https://bugs.python.org/issue?@action=redirect&bpo=36634]: venv activate.bat now works when the existing variables contain double quote characters.

bpo-38081 [https://bugs.python.org/issue?@action=redirect&bpo=38081]: Prevent error calling os.path.realpath() on 'NUL'.

bpo-38087 [https://bugs.python.org/issue?@action=redirect&bpo=38087]: Fix case sensitivity in test_pathlib and test_ntpath.

bpo-38088 [https://bugs.python.org/issue?@action=redirect&bpo=38088]: Fixes distutils not finding vcruntime140.dll with only the v142 toolset installed.

bpo-37283 [https://bugs.python.org/issue?@action=redirect&bpo=37283]: Ensure command-line and unattend.xml setting override previously detected states in Windows installer.

bpo-38030 [https://bugs.python.org/issue?@action=redirect&bpo=38030]: Fixes os.stat() failing for block devices on Windows

bpo-38020 [https://bugs.python.org/issue?@action=redirect&bpo=38020]: Fixes potential crash when calling os.readlink() (or indirectly through realpath()) on a file that is not a supported link.

bpo-37705 [https://bugs.python.org/issue?@action=redirect&bpo=37705]: Improve the implementation of winerror_to_errno().

bpo-37549 [https://bugs.python.org/issue?@action=redirect&bpo=37549]: os.dup() no longer fails for standard streams on Windows 7.

bpo-1311 [https://bugs.python.org/issue?@action=redirect&bpo=1311]: The nul file on Windows now returns True from exists() and a valid result from os.stat() with S_IFCHR set.

bpo-9949 [https://bugs.python.org/issue?@action=redirect&bpo=9949]: Enable support for following symlinks in os.realpath().

bpo-37834 [https://bugs.python.org/issue?@action=redirect&bpo=37834]: Treat all name surrogate reparse points on Windows in os.lstat() and other reparse points as regular files in os.stat().

bpo-36266 [https://bugs.python.org/issue?@action=redirect&bpo=36266]: Add the module name in the formatted error message when DLL load fail happens during module import in _PyImport_FindSharedFuncptrWindows(). Patch by Srinivas Nyayapati.

bpo-25172 [https://bugs.python.org/issue?@action=redirect&bpo=25172]: Trying to import the crypt module on Windows will result in an ImportError with a message explaining that the module isn’t supported on Windows. On other platforms, if the underlying _crypt module is not available, the ImportError will include a message explaining the problem.

bpo-37778 [https://bugs.python.org/issue?@action=redirect&bpo=37778]: Fixes the icons used for file associations to the Microsoft Store package.

bpo-37734 [https://bugs.python.org/issue?@action=redirect&bpo=37734]: Fix use of registry values to launch Python from Microsoft Store app.

bpo-37702 [https://bugs.python.org/issue?@action=redirect&bpo=37702]: Fix memory leak on Windows in creating an SSLContext object or running urllib.request.urlopen(”https://…”).

bpo-37672 [https://bugs.python.org/issue?@action=redirect&bpo=37672]: Switch Windows Store package’s pip to use bundled pip.ini instead of PIP_USER variable.

bpo-10945 [https://bugs.python.org/issue?@action=redirect&bpo=10945]: Officially drop support for creating bdist_wininst installers on non-Windows systems.

bpo-37445 [https://bugs.python.org/issue?@action=redirect&bpo=37445]: Include the FORMAT_MESSAGE_IGNORE_INSERTS flag in FormatMessageW() calls.

bpo-37369 [https://bugs.python.org/issue?@action=redirect&bpo=37369]: Fixes path for sys.executable when running from the Microsoft Store.

bpo-37380 [https://bugs.python.org/issue?@action=redirect&bpo=37380]: Don’t collect unfinished processes with subprocess._active on Windows to cleanup later. Patch by Ruslan Kuprieiev.

bpo-37351 [https://bugs.python.org/issue?@action=redirect&bpo=37351]: Removes libpython38.a from standard Windows distribution.

bpo-35360 [https://bugs.python.org/issue?@action=redirect&bpo=35360]: Update Windows builds to use SQLite 3.28.0.

bpo-37267 [https://bugs.python.org/issue?@action=redirect&bpo=37267]: On Windows, os.dup() no longer creates an inheritable fd when handling a character file.

bpo-36779 [https://bugs.python.org/issue?@action=redirect&bpo=36779]: Ensure time.tzname is correct on Windows when the active code page is set to CP_UTF7 or CP_UTF8.

bpo-32587 [https://bugs.python.org/issue?@action=redirect&bpo=32587]: Make winreg.REG_MULTI_SZ support zero-length strings.

bpo-28269 [https://bugs.python.org/issue?@action=redirect&bpo=28269]: Replace use of strcasecmp() for the system function _stricmp(). Patch by Minmin Gong.

bpo-36590 [https://bugs.python.org/issue?@action=redirect&bpo=36590]: Add native Bluetooth RFCOMM support to socket module.

macOS

bpo-38117 [https://bugs.python.org/issue?@action=redirect&bpo=38117]: Updated OpenSSL to 1.1.1d in macOS installer.

bpo-38089 [https://bugs.python.org/issue?@action=redirect&bpo=38089]: Move Azure Pipelines to latest VM versions and make macOS tests optional

bpo-18049 [https://bugs.python.org/issue?@action=redirect&bpo=18049]: Increase the default stack size of threads from 5MB to 16MB on macOS, to match the stack size of the main thread. This avoids crashes on deep recursion in threads.

bpo-34602 [https://bugs.python.org/issue?@action=redirect&bpo=34602]: Avoid test suite failures on macOS by no longer calling resource.setrlimit to increase the process stack size limit at runtime. The runtime change is no longer needed since the interpreter is being built with a larger default stack size.

bpo-35360 [https://bugs.python.org/issue?@action=redirect&bpo=35360]: Update macOS installer to use SQLite 3.28.0.

bpo-34631 [https://bugs.python.org/issue?@action=redirect&bpo=34631]: Updated OpenSSL to 1.1.1c in macOS installer.

IDLE

bpo-26353 [https://bugs.python.org/issue?@action=redirect&bpo=26353]: Stop adding newline when saving an IDLE shell window.

bpo-4630 [https://bugs.python.org/issue?@action=redirect&bpo=4630]: Add an option to toggle IDLE’s cursor blink for shell, editor, and output windows. See Settings, General, Window Preferences, Cursor Blink. Patch by Zackery Spytz.

bpo-38598 [https://bugs.python.org/issue?@action=redirect&bpo=38598]: Do not try to compile IDLE shell or output windows

bpo-36698 [https://bugs.python.org/issue?@action=redirect&bpo=36698]: IDLE no longer fails when write non-encodable characters to stderr. It now escapes them with a backslash, as the regular Python interpreter. Added the errors field to the standard streams.

bpo-35379 [https://bugs.python.org/issue?@action=redirect&bpo=35379]: When exiting IDLE, catch any AttributeError. One happens when EditorWindow.close is called twice. Printing a traceback, when IDLE is run from a terminal, is useless and annoying.

bpo-38183 [https://bugs.python.org/issue?@action=redirect&bpo=38183]: To avoid problems, test_idle ignores the user config directory. It no longer tries to create or access .idlerc or any files within. Users must run IDLE to discover problems with saving settings.

bpo-38077 [https://bugs.python.org/issue?@action=redirect&bpo=38077]: IDLE no longer adds “argv” to the user namespace when initializing it. This bug only affected 3.7.4 and 3.8.0b2 to 3.8.0b4.

bpo-38041 [https://bugs.python.org/issue?@action=redirect&bpo=38041]: Shell restart lines now fill the window width, always start with “=”, and avoid wrapping unnecessarily. The line will still wrap if the included file name is long relative to the width.

bpo-35771 [https://bugs.python.org/issue?@action=redirect&bpo=35771]: To avoid occasional spurious test_idle failures on slower machines, increase the hover_delay in test_tooltip.

bpo-37824 [https://bugs.python.org/issue?@action=redirect&bpo=37824]: Properly handle user input warnings in IDLE shell. Cease turning SyntaxWarnings into SyntaxErrors.

bpo-37929 [https://bugs.python.org/issue?@action=redirect&bpo=37929]: IDLE Settings dialog now closes properly when there is no shell window.

bpo-37902 [https://bugs.python.org/issue?@action=redirect&bpo=37902]: Add mousewheel scrolling for IDLE module, path, and stack browsers. Patch by George Zhang.

bpo-37849 [https://bugs.python.org/issue?@action=redirect&bpo=37849]: Fixed completions list appearing too high or low when shown above the current line.

bpo-36419 [https://bugs.python.org/issue?@action=redirect&bpo=36419]: Refactor IDLE autocomplete and improve testing.

bpo-37748 [https://bugs.python.org/issue?@action=redirect&bpo=37748]: Reorder the Run menu. Put the most common choice, Run Module, at the top.

bpo-37692 [https://bugs.python.org/issue?@action=redirect&bpo=37692]: Improve highlight config sample with example shell interaction and better labels for shell elements.

bpo-37628 [https://bugs.python.org/issue?@action=redirect&bpo=37628]: Settings dialog no longer expands with font size.

bpo-37627 [https://bugs.python.org/issue?@action=redirect&bpo=37627]: Initialize the Customize Run dialog with the command line arguments most recently entered before. The user can optionally edit before submitting them.

bpo-33610 [https://bugs.python.org/issue?@action=redirect&bpo=33610]: Fix code context not showing the correct context when first toggled on.

bpo-37530 [https://bugs.python.org/issue?@action=redirect&bpo=37530]: Optimize code context to reduce unneeded background activity. Font and highlight changes now occur along with text changes instead of after a random delay.

bpo-27452 [https://bugs.python.org/issue?@action=redirect&bpo=27452]: Cleanup config.py by inlining RemoveFile and simplifying the handling of file in CreateConfigHandlers.

bpo-37325 [https://bugs.python.org/issue?@action=redirect&bpo=37325]: Fix tab focus traversal order for help source and custom run dialogs.

bpo-37321 [https://bugs.python.org/issue?@action=redirect&bpo=37321]: Both subprocess connection error messages now refer to the “Startup failure” section of the IDLE doc.

bpo-17535 [https://bugs.python.org/issue?@action=redirect&bpo=17535]: Add optional line numbers for IDLE editor windows. Windows open without line numbers unless set otherwise in the General tab of the configuration dialog.

bpo-26806 [https://bugs.python.org/issue?@action=redirect&bpo=26806]: To compensate for stack frames added by IDLE and avoid possible problems with low recursion limits, add 30 to limits in the user code execution process. Subtract 30 when reporting recursion limits to make this addition mostly transparent.

bpo-37177 [https://bugs.python.org/issue?@action=redirect&bpo=37177]: Properly “attach” search dialogs to their main window so that they behave like other dialogs and do not get hidden behind their main window.

bpo-37039 [https://bugs.python.org/issue?@action=redirect&bpo=37039]: Adjust «Zoom Height» to individual screens by momentarily maximizing the window on first use with a particular screen. Changing screen settings may invalidate the saved height. While a window is maximized, «Zoom Height» has no effect.

bpo-35763 [https://bugs.python.org/issue?@action=redirect&bpo=35763]: Make calltip reminder about “/” meaning positional-only less obtrusive by only adding it when there is room on the first line.

bpo-5680 [https://bugs.python.org/issue?@action=redirect&bpo=5680]: Add “Run… Customized” to the Run menu to run a module with customized settings. Any “command line arguments” entered are added to sys.argv. One can suppress the normal Shell main module restart.

bpo-36390 [https://bugs.python.org/issue?@action=redirect&bpo=36390]: Gather Format menu functions into format.py. Combine paragraph.py, rstrip.py, and format methods from editor.py.

Tools/Demos

bpo-38118 [https://bugs.python.org/issue?@action=redirect&bpo=38118]: Update Valgrind suppression file to ignore a false alarm in PyUnicode_Decode() when using GCC builtin strcmp().

bpo-38347 [https://bugs.python.org/issue?@action=redirect&bpo=38347]: pathfix.py: Assume all files that end on “.py” are Python scripts when working recursively.

bpo-37803 [https://bugs.python.org/issue?@action=redirect&bpo=37803]: pdb’s --help and --version long options now work.

bpo-37942 [https://bugs.python.org/issue?@action=redirect&bpo=37942]: Improve ArgumentClinic converter for floats.

bpo-37704 [https://bugs.python.org/issue?@action=redirect&bpo=37704]: Remove Tools/scripts/h2py.py: use cffi to access a C API in Python.

bpo-37675 [https://bugs.python.org/issue?@action=redirect&bpo=37675]: 2to3 now works when run from a zipped standard library.

bpo-37034 [https://bugs.python.org/issue?@action=redirect&bpo=37034]: Argument Clinic now uses the argument name on errors with keyword-only argument instead of their position. Patch contributed by Rémi Lapeyre.

bpo-37064 [https://bugs.python.org/issue?@action=redirect&bpo=37064]: Add option -k to pathscript.py script: preserve shebang flags. Add option -a to pathscript.py script: add flags.

C API

bpo-37633 [https://bugs.python.org/issue?@action=redirect&bpo=37633]: Re-export some function compatibility wrappers for macros in pythonrun.h.

bpo-38644 [https://bugs.python.org/issue?@action=redirect&bpo=38644]: Provide Py_EnterRecursiveCall() and Py_LeaveRecursiveCall() as regular functions for the limited API. Previously, there were defined as macros, but these macros didn’t work with the limited API which cannot access PyThreadState.recursion_depth field. Remove _Py_CheckRecursionLimit from the stable ABI.

bpo-38650 [https://bugs.python.org/issue?@action=redirect&bpo=38650]: The global variable PyStructSequence_UnnamedField is now a constant and refers to a constant string.

bpo-38540 [https://bugs.python.org/issue?@action=redirect&bpo=38540]: Fixed possible leak in PyArg_Parse() and similar functions for format units "es#" and "et#" when the macro PY_SSIZE_T_CLEAN is not defined.

bpo-38395 [https://bugs.python.org/issue?@action=redirect&bpo=38395]: Fix a crash in weakref.proxy objects due to incorrect lifetime management when calling some associated methods that may delete the last reference to object being referenced by the proxy. Patch by Pablo Galindo.

bpo-36389 [https://bugs.python.org/issue?@action=redirect&bpo=36389]: The _PyObject_CheckConsistency() function is now also available in release mode. For example, it can be used to debug a crash in the visit_decref() function of the GC.

bpo-38266 [https://bugs.python.org/issue?@action=redirect&bpo=38266]: Revert the removal of PyThreadState_DeleteCurrent() with documentation.

bpo-38303 [https://bugs.python.org/issue?@action=redirect&bpo=38303]: Update audioop extension module to use the stable ABI (PEP-384). Patch by Tyler Kieft.

bpo-38234 [https://bugs.python.org/issue?@action=redirect&bpo=38234]: Py_SetPath() now sets sys.executable to the program full path (Py_GetProgramFullPath()) rather than to the program name (Py_GetProgramName()).

bpo-38234 [https://bugs.python.org/issue?@action=redirect&bpo=38234]: Python ignored arguments passed to Py_SetPath(), Py_SetPythonHome() and Py_SetProgramName(): fix Python initialization to use specified arguments.

bpo-38205 [https://bugs.python.org/issue?@action=redirect&bpo=38205]: The Py_UNREACHABLE() macro now calls Py_FatalError().

bpo-38140 [https://bugs.python.org/issue?@action=redirect&bpo=38140]: Make dict and weakref offsets opaque for C heap types by passing the offsets through PyMemberDef

bpo-15088 [https://bugs.python.org/issue?@action=redirect&bpo=15088]: The C function PyGen_NeedsFinalizing has been removed. It was not documented, tested or used anywhere within CPython after the implementation of PEP 442 [https://www.python.org/dev/peps/pep-0442]. Patch by Joannah Nanjekye. (Patch by Joannah Nanjekye)

bpo-36763 [https://bugs.python.org/issue?@action=redirect&bpo=36763]: Options added by PySys_AddXOption() are now handled the same way than PyConfig.xoptions and command line -X options.

bpo-37926 [https://bugs.python.org/issue?@action=redirect&bpo=37926]: Fix a crash in PySys_SetArgvEx(0, NULL, 0).

bpo-37879 [https://bugs.python.org/issue?@action=redirect&bpo=37879]: Fix subtype_dealloc to suppress the type decref when the base type is a C heap type

bpo-37645 [https://bugs.python.org/issue?@action=redirect&bpo=37645]: Add _PyObject_FunctionStr() to get a user-friendly string representation of a function-like object. Patch by Jeroen Demeyer.

bpo-29548 [https://bugs.python.org/issue?@action=redirect&bpo=29548]: The functions PyEval_CallObject, PyEval_CallFunction, PyEval_CallMethod and PyEval_CallObjectWithKeywords are deprecated. Use PyObject_Call() and its variants instead.

bpo-37151 [https://bugs.python.org/issue?@action=redirect&bpo=37151]: PyCFunction_Call is now a deprecated alias of PyObject_Call().

bpo-37540 [https://bugs.python.org/issue?@action=redirect&bpo=37540]: The vectorcall protocol now requires that the caller passes only strings as keyword names.

bpo-37207 [https://bugs.python.org/issue?@action=redirect&bpo=37207]: The vectorcall protocol is now enabled for type objects: set tp_vectorcall to a vectorcall function to be used instead of tp_new and tp_init when calling the class itself.

bpo-21120 [https://bugs.python.org/issue?@action=redirect&bpo=21120]: Exclude Python-ast.h, ast.h and asdl.h from the limited API.

bpo-37483 [https://bugs.python.org/issue?@action=redirect&bpo=37483]: Add new function _PyObject_CallOneArg for calling an object with one positional argument.

bpo-36763 [https://bugs.python.org/issue?@action=redirect&bpo=36763]: Add PyConfig_SetWideStringList() function.

bpo-37337 [https://bugs.python.org/issue?@action=redirect&bpo=37337]: Add fast functions for calling methods: _PyObject_VectorcallMethod(), _PyObject_CallMethodNoArgs() and _PyObject_CallMethodOneArg().

bpo-28805 [https://bugs.python.org/issue?@action=redirect&bpo=28805]: The METH_FASTCALL calling convention has been documented.

bpo-37221 [https://bugs.python.org/issue?@action=redirect&bpo=37221]: The new function PyCode_NewWithPosOnlyArgs() allows to create code objects like PyCode_New(), but with an extra posonlyargcount parameter for indicating the number of positonal-only arguments.

bpo-37215 [https://bugs.python.org/issue?@action=redirect&bpo=37215]: Fix dtrace issue introduce by bpo-36842 [https://bugs.python.org/issue?@action=redirect&bpo=36842]

bpo-37194 [https://bugs.python.org/issue?@action=redirect&bpo=37194]: Add a new public PyObject_CallNoArgs() function to the C API: call a callable Python object without any arguments. It is the most efficient way to call a callback without any argument. On x86-64, for example, PyObject_CallFunctionObjArgs(func, NULL) allocates 960 bytes on the stack per call, whereas PyObject_CallNoArgs(func) only allocates 624 bytes per call.

bpo-37170 [https://bugs.python.org/issue?@action=redirect&bpo=37170]: Fix the cast on error in PyLong_AsUnsignedLongLongMask().

bpo-35381 [https://bugs.python.org/issue?@action=redirect&bpo=35381]: Convert posixmodule.c statically allocated types DirEntryType and ScandirIteratorType to heap-allocated types.

bpo-34331 [https://bugs.python.org/issue?@action=redirect&bpo=34331]: Use singular/plural noun in error message when instantiating an abstract class with non-overriden abstract method(s).

Python 3.8.0 beta 1

Release date: 2019-06-04

Security

bpo-35907 [https://bugs.python.org/issue?@action=redirect&bpo=35907]: CVE-2019-9948: Avoid file reading by disallowing local-file:// and local_file:// URL schemes in URLopener().open() and URLopener().retrieve() of urllib.request.

bpo-33529 [https://bugs.python.org/issue?@action=redirect&bpo=33529]: Prevent fold function used in email header encoding from entering infinite loop when there are too many non-ASCII characters in a header.

bpo-33164 [https://bugs.python.org/issue?@action=redirect&bpo=33164]: Updated blake2 implementation which uses secure memset implementation provided by platform.

Core and Builtins

bpo-35814 [https://bugs.python.org/issue?@action=redirect&bpo=35814]: Allow unpacking in the right hand side of annotated assignments. In particular, t: Tuple[int, ...] = x, y, *z is now allowed.

bpo-37126 [https://bugs.python.org/issue?@action=redirect&bpo=37126]: All structseq objects are now tracked by the garbage collector. Patch by Pablo Galindo.

bpo-37122 [https://bugs.python.org/issue?@action=redirect&bpo=37122]: Make the co_argcount attribute of code objects represent the total number of positional arguments (including positional-only arguments). The value of co_posonlyargcount can be used to distinguish which arguments are positional only, and the difference (co_argcount - co_posonlyargcount) is the number of positional-or-keyword arguments. Patch by Pablo Galindo.

bpo-20092 [https://bugs.python.org/issue?@action=redirect&bpo=20092]: Constructors of int, float and complex will now use the __index__() special method, if available and the corresponding method __int__(), __float__() or __complex__() is not available.

bpo-37087 [https://bugs.python.org/issue?@action=redirect&bpo=37087]: Add native thread ID (TID) support to OpenBSD.

bpo-26219 [https://bugs.python.org/issue?@action=redirect&bpo=26219]: Implemented per opcode cache mechanism and LOAD_GLOBAL instruction use it. LOAD_GLOBAL is now about 40% faster. Contributed by Yury Selivanov, and Inada Naoki.

bpo-37072 [https://bugs.python.org/issue?@action=redirect&bpo=37072]: Fix crash in PyAST_FromNodeObject() when flags is NULL.

bpo-37029 [https://bugs.python.org/issue?@action=redirect&bpo=37029]: Freeing a great many small objects could take time quadratic in the number of arenas, due to using linear search to keep obmalloc.c’s list of usable arenas sorted by order of number of free memory pools. This is accomplished without search now, leaving the worst-case time linear in the number of arenas. For programs where this quite visibly matters (typically with more than 100 thousand small objects alive simultaneously), this can greatly reduce the time needed to release their memory.

bpo-26423 [https://bugs.python.org/issue?@action=redirect&bpo=26423]: Fix possible overflow in wrap_lenfunc() when sizeof(long) < sizeof(Py_ssize_t) (e.g., 64-bit Windows).

bpo-37050 [https://bugs.python.org/issue?@action=redirect&bpo=37050]: Improve the AST for «debug» f-strings, which use “=” to print out the source of the expression being evaluated. Delete expr_text from the FormattedValue node, and instead use a Constant string node (possibly merged with adjacent constant expressions inside the f-string).

bpo-22385 [https://bugs.python.org/issue?@action=redirect&bpo=22385]: The bytes.hex, bytearray.hex, and memoryview.hex methods as well as the binascii.hexlify and b2a_hex functions now have the ability to include an optional separator between hex bytes. This functionality was inspired by MicroPython’s hexlify implementation.

bpo-26836 [https://bugs.python.org/issue?@action=redirect&bpo=26836]: Add os.memfd_create().

bpo-37032 [https://bugs.python.org/issue?@action=redirect&bpo=37032]: Added new replace() method to the code type (types.CodeType).

bpo-37007 [https://bugs.python.org/issue?@action=redirect&bpo=37007]: Implement socket.if_nameindex(), socket.if_nametoindex(), and socket.if_indextoname() on Windows.

bpo-36829 [https://bugs.python.org/issue?@action=redirect&bpo=36829]: PyErr_WriteUnraisable() now creates a traceback object if there is no current traceback. Moreover, call PyErr_NormalizeException() and PyException_SetTraceback() to normalize the exception value. Ignore any error.

bpo-36878 [https://bugs.python.org/issue?@action=redirect&bpo=36878]: Only accept text after # type: ignore if the first character is ASCII. This is to disallow things like # type: ignoreé.

bpo-36878 [https://bugs.python.org/issue?@action=redirect&bpo=36878]: Store text appearing after a # type: ignore comment in the AST. For example a type ignore like # type: ignore[E1000] will have the string "[E1000]" stored in its AST node.

bpo-2180 [https://bugs.python.org/issue?@action=redirect&bpo=2180]: Treat line continuation at EOF as a SyntaxError by Anthony Sottile.

bpo-36907 [https://bugs.python.org/issue?@action=redirect&bpo=36907]: Fix a crash when calling a C function with a keyword dict (f(**kwargs)) and changing the dict kwargs while that function is running.

bpo-36946 [https://bugs.python.org/issue?@action=redirect&bpo=36946]: Fix possible signed integer overflow when handling slices.

bpo-36826 [https://bugs.python.org/issue?@action=redirect&bpo=36826]: Add NamedExpression kind support to ast_unparse.c

bpo-1875 [https://bugs.python.org/issue?@action=redirect&bpo=1875]: A SyntaxError is now raised if a code blocks that will be optimized away (e.g. if conditions that are always false) contains syntax errors. Patch by Pablo Galindo.

bpo-36027 [https://bugs.python.org/issue?@action=redirect&bpo=36027]: Allow computation of modular inverses via three-argument pow: the second argument is now permitted to be negative in the case where the first and third arguments are relatively prime.

bpo-36861 [https://bugs.python.org/issue?@action=redirect&bpo=36861]: Update the Unicode database to version 12.1.0.

bpo-28866 [https://bugs.python.org/issue?@action=redirect&bpo=28866]: Avoid caching attributes of classes which type defines mro() to avoid a hard cache invalidation problem.

bpo-36851 [https://bugs.python.org/issue?@action=redirect&bpo=36851]: The FrameType stack is now correctly cleaned up if the execution ends with a return and the stack is not empty.

bpo-34616 [https://bugs.python.org/issue?@action=redirect&bpo=34616]: The compile() builtin functions now support the ast.PyCF_ALLOW_TOP_LEVEL_AWAIT flag, which allow to compile sources that contains top-level await, async with or async for. This is useful to evaluate async-code from with an already async functions; for example in a custom REPL.

bpo-36842 [https://bugs.python.org/issue?@action=redirect&bpo=36842]: Implement PEP 578, adding sys.audit, io.open_code and related APIs.

bpo-27639 [https://bugs.python.org/issue?@action=redirect&bpo=27639]: Correct return type for UserList slicing operations. Patch by Michael Blahay, Erick Cervantes, and vaultah

bpo-36737 [https://bugs.python.org/issue?@action=redirect&bpo=36737]: Move PyRuntimeState.warnings into per-interpreter state (via «module state»).

bpo-36793 [https://bugs.python.org/issue?@action=redirect&bpo=36793]: Removed __str__ implementations from builtin types bool, int, float, complex and few classes from the standard library. They now inherit __str__() from object.

bpo-36817 [https://bugs.python.org/issue?@action=redirect&bpo=36817]: Add a = feature f-strings for debugging. This can precede !s, !r, or !a. It produces the text of the expression, followed by an equal sign, followed by the repr of the value of the expression. So f'{3*9+15=}' would be equal to the string '3*9+15=42'. If = is specified, the default conversion is set to !r, unless a format spec is given, in which case the formatting behavior is unchanged, and __format__ will be used.

bpo-24048 [https://bugs.python.org/issue?@action=redirect&bpo=24048]: Save the live exception during import.c’s remove_module().

bpo-27987 [https://bugs.python.org/issue?@action=redirect&bpo=27987]: pymalloc returns memory blocks aligned by 16 bytes, instead of 8 bytes, on 64-bit platforms to conform x86-64 ABI. Recent compilers assume this alignment more often. Patch by Inada Naoki.

bpo-36601 [https://bugs.python.org/issue?@action=redirect&bpo=36601]: A long-since-meaningless check for getpid() == main_pid was removed from Python’s internal C signal handler.

bpo-36594 [https://bugs.python.org/issue?@action=redirect&bpo=36594]: Fix incorrect use of %p in format strings. Patch by Zackery Spytz.

bpo-36045 [https://bugs.python.org/issue?@action=redirect&bpo=36045]: builtins.help() now prefixes async for async functions

bpo-36084 [https://bugs.python.org/issue?@action=redirect&bpo=36084]: Add native thread ID (TID) to threading.Thread objects (supported platforms: Windows, FreeBSD, Linux, macOS)

bpo-36035 [https://bugs.python.org/issue?@action=redirect&bpo=36035]: Added fix for broken symlinks in combination with pathlib

bpo-35983 [https://bugs.python.org/issue?@action=redirect&bpo=35983]: Added new trashcan macros to deal with a double deallocation that could occur when the tp_dealloc of a subclass calls the tp_dealloc of a base class and that base class uses the trashcan mechanism. Patch by Jeroen Demeyer.

bpo-20602 [https://bugs.python.org/issue?@action=redirect&bpo=20602]: Do not clear sys.flags and sys.float_info during shutdown. Patch by Zackery Spytz.

bpo-26826 [https://bugs.python.org/issue?@action=redirect&bpo=26826]: Expose copy_file_range() as a low level API in the os module.

bpo-32388 [https://bugs.python.org/issue?@action=redirect&bpo=32388]: Remove cross-version binary compatibility requirement in tp_flags.

bpo-31862 [https://bugs.python.org/issue?@action=redirect&bpo=31862]: Port binascii to PEP 489 multiphase initialization. Patch by Marcel Plch.

Library

bpo-37128 [https://bugs.python.org/issue?@action=redirect&bpo=37128]: Added math.perm().

bpo-37120 [https://bugs.python.org/issue?@action=redirect&bpo=37120]: Add SSLContext.num_tickets to control the number of TLSv1.3 session tickets.

bpo-12202 [https://bugs.python.org/issue?@action=redirect&bpo=12202]: Fix the error handling in msilib.SummaryInformation.GetProperty(). Patch by Zackery Spytz.

bpo-26835 [https://bugs.python.org/issue?@action=redirect&bpo=26835]: The fcntl module now contains file sealing constants for sealing of memfds.

bpo-29262 [https://bugs.python.org/issue?@action=redirect&bpo=29262]: Add get_origin() and get_args() introspection helpers to typing module.

bpo-12639 [https://bugs.python.org/issue?@action=redirect&bpo=12639]: msilib.Directory.start_component() no longer fails if keyfile is not None.

bpo-36999 [https://bugs.python.org/issue?@action=redirect&bpo=36999]: Add the asyncio.Task.get_coro() method to publicly expose the tasks’s coroutine object.

bpo-35246 [https://bugs.python.org/issue?@action=redirect&bpo=35246]: Make asyncio.create_subprocess_exec() accept path-like arguments.

bpo-35279 [https://bugs.python.org/issue?@action=redirect&bpo=35279]: Change default max_workers of ThreadPoolExecutor from cpu_count() * 5 to min(32, cpu_count() + 4). Previous value was unreasonably large on many cores machines.

bpo-37076 [https://bugs.python.org/issue?@action=redirect&bpo=37076]: _thread.start_new_thread() now logs uncaught exception raised by the function using sys.unraisablehook(), rather than sys.excepthook(), so the hook gets access to the function which raised the exception.

bpo-33725 [https://bugs.python.org/issue?@action=redirect&bpo=33725]: On macOS, the multiprocessing module now uses spawn start method by default.

bpo-37054 [https://bugs.python.org/issue?@action=redirect&bpo=37054]: Fix destructor _pyio.BytesIO and _pyio.TextIOWrapper: initialize their _buffer attribute as soon as possible (in the class body), because it’s used by __del__() which calls close().

bpo-37058 [https://bugs.python.org/issue?@action=redirect&bpo=37058]: PEP 544: Add Protocol and @runtime_checkable to the typing module.

bpo-36933 [https://bugs.python.org/issue?@action=redirect&bpo=36933]: The functions sys.set_coroutine_wrapper and sys.get_coroutine_wrapper that were deprecated and marked for removal in 3.8 have been removed.

bpo-37047 [https://bugs.python.org/issue?@action=redirect&bpo=37047]: Handle late binding and attribute access in unittest.mock.AsyncMock setup for autospeccing. Document newly implemented async methods in unittest.mock.MagicMock.

bpo-37049 [https://bugs.python.org/issue?@action=redirect&bpo=37049]: PEP 589: Add TypedDict to the typing module.

bpo-37046 [https://bugs.python.org/issue?@action=redirect&bpo=37046]: PEP 586: Add Literal to the typing module.

bpo-37045 [https://bugs.python.org/issue?@action=redirect&bpo=37045]: PEP 591: Add Final qualifier and @final decorator to the typing module.

bpo-37035 [https://bugs.python.org/issue?@action=redirect&bpo=37035]: Don’t log OSError based exceptions if a fatal error has occurred in asyncio transport. Peer can generate almost any OSError, user cannot avoid these exceptions by fixing own code. Errors are still propagated to user code, it’s just logging them is pointless and pollute asyncio logs.

bpo-37001 [https://bugs.python.org/issue?@action=redirect&bpo=37001]: symtable.symtable() now accepts the same input types for source code as the built-in compile() function. Patch by Dino Viehland.

bpo-37028 [https://bugs.python.org/issue?@action=redirect&bpo=37028]: Implement asyncio REPL

bpo-37027 [https://bugs.python.org/issue?@action=redirect&bpo=37027]: Return safe to use proxy socket object from transport.get_extra_info(“socket”)

bpo-32528 [https://bugs.python.org/issue?@action=redirect&bpo=32528]: Make asyncio.CancelledError a BaseException.

This will address the common mistake many asyncio users make: an «except Exception» clause breaking Tasks cancellation.

In addition to this change, we stop inheriting asyncio.TimeoutError and asyncio.InvalidStateError from their concurrent.futures.* counterparts. There’s no point for these exceptions to share the inheritance chain.

bpo-1230540 [https://bugs.python.org/issue?@action=redirect&bpo=1230540]: Add a new threading.excepthook() function which handles uncaught threading.Thread.run() exception. It can be overridden to control how uncaught threading.Thread.run() exceptions are handled.

bpo-36996 [https://bugs.python.org/issue?@action=redirect&bpo=36996]: Handle unittest.mock.patch() used as a decorator on async functions.

bpo-37008 [https://bugs.python.org/issue?@action=redirect&bpo=37008]: Add support for calling next() with the mock resulting from unittest.mock.mock_open()

bpo-27737 [https://bugs.python.org/issue?@action=redirect&bpo=27737]: Allow whitespace only header encoding in email.header - by Batuhan Taskaya

bpo-36969 [https://bugs.python.org/issue?@action=redirect&bpo=36969]: PDB command args now display positional only arguments. Patch contributed by Rémi Lapeyre.

bpo-36969 [https://bugs.python.org/issue?@action=redirect&bpo=36969]: PDB command args now display keyword only arguments. Patch contributed by Rémi Lapeyre.

bpo-36983 [https://bugs.python.org/issue?@action=redirect&bpo=36983]: Add missing names to typing.__all__: ChainMap, ForwardRef, OrderedDict - by Anthony Sottile.

bpo-36972 [https://bugs.python.org/issue?@action=redirect&bpo=36972]: Add SupportsIndex protocol to the typing module to allow type checking to detect classes that can be passed to hex(), oct() and bin().

bpo-32972 [https://bugs.python.org/issue?@action=redirect&bpo=32972]: Implement unittest.IsolatedAsyncioTestCase to help testing asyncio-based code.

bpo-36952 [https://bugs.python.org/issue?@action=redirect&bpo=36952]: fileinput.input() and fileinput.FileInput bufsize argument has been removed (was deprecated and ignored since Python 3.6), and as a result the mode and openhook arguments have been made keyword-only.

bpo-36952 [https://bugs.python.org/issue?@action=redirect&bpo=36952]: Starting with Python 3.3, importing ABCs from collections is deprecated, and import should be done from collections.abc. Still being able to import from collections was marked for removal in 3.8, but has been delayed to 3.9; documentation and DeprecationWarning clarified.

bpo-36949 [https://bugs.python.org/issue?@action=redirect&bpo=36949]: Implement __repr__ for WeakSet objects.

bpo-36948 [https://bugs.python.org/issue?@action=redirect&bpo=36948]: Fix NameError in urllib.request.URLopener.retrieve(). Patch by Karthikeyan Singaravelan.

bpo-33524 [https://bugs.python.org/issue?@action=redirect&bpo=33524]: Fix the folding of email header when the max_line_length is 0 or None and the header contains non-ascii characters. Contributed by Licht Takeuchi (@Licht-T).

bpo-24564 [https://bugs.python.org/issue?@action=redirect&bpo=24564]: shutil.copystat() now ignores errno.EINVAL on os.setxattr() which may occur when copying files on filesystems without extended attributes support.

Original patch by Giampaolo Rodola, updated by Ying Wang.

bpo-36888 [https://bugs.python.org/issue?@action=redirect&bpo=36888]: Python child processes can now access the status of their parent process using multiprocessing.process.parent_process

bpo-36921 [https://bugs.python.org/issue?@action=redirect&bpo=36921]: Deprecate @coroutine for sake of async def.

bpo-25652 [https://bugs.python.org/issue?@action=redirect&bpo=25652]: Fix bug in __rmod__ of UserString - by Batuhan Taskaya.

bpo-36916 [https://bugs.python.org/issue?@action=redirect&bpo=36916]: Remove a message about an unhandled exception in a task when writer.write() is used without await and writer.drain() fails with an exception.

bpo-36889 [https://bugs.python.org/issue?@action=redirect&bpo=36889]: Introduce asyncio.Stream class that merges asyncio.StreamReader and asyncio.StreamWriter functionality. asyncio.Stream can work in readonly, writeonly and readwrite modes. Provide asyncio.connect(), asyncio.connect_unix(), asyncio.connect_read_pipe() and asyncio.connect_write_pipe() factories to open asyncio.Stream connections. Provide asyncio.StreamServer and UnixStreamServer to serve servers with asyncio.Stream API. Modify asyncio.create_subprocess_shell() and asyncio.create_subprocess_exec() to use asyncio.Stream instead of deprecated StreamReader and StreamWriter. Deprecate asyncio.StreamReader and asyncio.StreamWriter. Deprecate usage of private classes, e.g. asyncio.FlowControlMixing and asyncio.StreamReaderProtocol outside of asyncio package.

bpo-36845 [https://bugs.python.org/issue?@action=redirect&bpo=36845]: Added validation of integer prefixes to the construction of IP networks and interfaces in the ipaddress module.

bpo-23378 [https://bugs.python.org/issue?@action=redirect&bpo=23378]: Add an extend action to argparser.

bpo-36867 [https://bugs.python.org/issue?@action=redirect&bpo=36867]: Fix a bug making a SharedMemoryManager instance and its parent process use two separate resource_tracker processes.

bpo-23896 [https://bugs.python.org/issue?@action=redirect&bpo=23896]: Adds a grammar to lib2to3.pygram that contains exec as a function not as statement.

bpo-36895 [https://bugs.python.org/issue?@action=redirect&bpo=36895]: The function time.clock() was deprecated in 3.3 in favor of time.perf_counter() and marked for removal in 3.8, it has removed.

bpo-35545 [https://bugs.python.org/issue?@action=redirect&bpo=35545]: Fix asyncio discarding IPv6 scopes when ensuring hostname resolutions internally

bpo-36887 [https://bugs.python.org/issue?@action=redirect&bpo=36887]: Add new function math.isqrt() to compute integer square roots.

bpo-34632 [https://bugs.python.org/issue?@action=redirect&bpo=34632]: Introduce the importlib.metadata module with (provisional) support for reading metadata from third-party packages.

bpo-36878 [https://bugs.python.org/issue?@action=redirect&bpo=36878]: When using type_comments=True in ast.parse, treat # type: ignore followed by a non-alphanumeric character and then arbitrary text as a type ignore, instead of requiring nothing but whitespace or another comment. This is to permit formations such as # type: ignore[E1000].

bpo-36778 [https://bugs.python.org/issue?@action=redirect&bpo=36778]: cp65001 encoding (Windows code page 65001) becomes an alias to utf_8 encoding.

bpo-36867 [https://bugs.python.org/issue?@action=redirect&bpo=36867]: The multiprocessing.resource_tracker replaces the multiprocessing.semaphore_tracker module. Other than semaphores, resource_tracker also tracks shared_memory segments.

bpo-30262 [https://bugs.python.org/issue?@action=redirect&bpo=30262]: The Cache and Statement objects of the sqlite3 module are not exposed to the user. Patch by Aviv Palivoda.

bpo-24538 [https://bugs.python.org/issue?@action=redirect&bpo=24538]: In shutil.copystat(), first copy extended file attributes and then file permissions, since extended attributes can only be set on the destination while it is still writeable.

bpo-36829 [https://bugs.python.org/issue?@action=redirect&bpo=36829]: Add new sys.unraisablehook() function which can be overridden to control how «unraisable exceptions» are handled. It is called when an exception has occurred but there is no way for Python to handle it. For example, when a destructor raises an exception or during garbage collection (gc.collect()).

bpo-36832 [https://bugs.python.org/issue?@action=redirect&bpo=36832]: Introducing zipfile.Path, a pathlib-compatible wrapper for traversing zip files.

bpo-36814 [https://bugs.python.org/issue?@action=redirect&bpo=36814]: Fix an issue where os.posix_spawnp() would incorrectly raise a TypeError when file_actions is None.

bpo-33110 [https://bugs.python.org/issue?@action=redirect&bpo=33110]: Handle exceptions raised by functions added by concurrent.futures add_done_callback correctly when the Future has already completed.

bpo-26903 [https://bugs.python.org/issue?@action=redirect&bpo=26903]: Limit max_workers in ProcessPoolExecutor to 61 to work around a WaitForMultipleObjects limitation.

bpo-36813 [https://bugs.python.org/issue?@action=redirect&bpo=36813]: Fix QueueListener to call queue.task_done() upon stopping. Patch by Bar Harel.

bpo-36806 [https://bugs.python.org/issue?@action=redirect&bpo=36806]: Forbid creation of asyncio stream objects like StreamReader, StreamWriter, Process, and their protocols outside of asyncio package.

bpo-36802 [https://bugs.python.org/issue?@action=redirect&bpo=36802]: Provide both sync and async calls for StreamWriter.write() and StreamWriter.close()

bpo-36801 [https://bugs.python.org/issue?@action=redirect&bpo=36801]: Properly handle SSL connection closing in asyncio StreamWriter.drain() call.

bpo-36785 [https://bugs.python.org/issue?@action=redirect&bpo=36785]: Implement PEP 574 (pickle protocol 5 with out-of-band buffers).

bpo-36772 [https://bugs.python.org/issue?@action=redirect&bpo=36772]: functools.lru_cache() can now be used as a straight decorator in addition to its existing usage as a function that returns a decorator.

bpo-6584 [https://bugs.python.org/issue?@action=redirect&bpo=6584]: Add a BadGzipFile exception to the gzip module.

bpo-36748 [https://bugs.python.org/issue?@action=redirect&bpo=36748]: Optimized write buffering in C implementation of TextIOWrapper. Writing ASCII string to TextIOWrapper with ascii, latin1, or utf-8 encoding is about 20% faster. Patch by Inada Naoki.

bpo-8138 [https://bugs.python.org/issue?@action=redirect&bpo=8138]: Don’t mark wsgiref.simple_server.SimpleServer as multi-threaded since wsgiref.simple_server.WSGIServer is single-threaded.

bpo-22640 [https://bugs.python.org/issue?@action=redirect&bpo=22640]: py_compile.compile() now supports silent mode. Patch by Joannah Nanjekye

bpo-29183 [https://bugs.python.org/issue?@action=redirect&bpo=29183]: Fix double exceptions in wsgiref.handlers.BaseHandler by calling its close() method only when no exception is raised.

bpo-36548 [https://bugs.python.org/issue?@action=redirect&bpo=36548]: Improved the repr of regular expression flags.

bpo-36542 [https://bugs.python.org/issue?@action=redirect&bpo=36542]: The signature of Python functions can now be overridden by specifying the __text_signature__ attribute.

bpo-36533 [https://bugs.python.org/issue?@action=redirect&bpo=36533]: Reinitialize logging.Handler locks in forked child processes instead of attempting to acquire them all in the parent before forking only to be released in the child process. The acquire/release pattern was leading to deadlocks in code that has implemented any form of chained logging handlers that depend upon one another as the lock acquisition order cannot be guaranteed.

bpo-35252 [https://bugs.python.org/issue?@action=redirect&bpo=35252]: Throw a TypeError instead of an AssertionError when using an invalid type annotation with singledispatch.

bpo-35900 [https://bugs.python.org/issue?@action=redirect&bpo=35900]: Allow reduction methods to return a 6-item tuple where the 6th item specifies a custom state-setting method that’s called instead of the regular __setstate__ method.

bpo-35900 [https://bugs.python.org/issue?@action=redirect&bpo=35900]: enable custom reduction callback registration for functions and classes in _pickle.c, using the new Pickler’s attribute reducer_override

bpo-36368 [https://bugs.python.org/issue?@action=redirect&bpo=36368]: Fix a bug crashing SharedMemoryManager instances in interactive sessions after a ctrl-c (KeyboardInterrupt) was sent

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Fix mmap fail for VxWorks

bpo-27497 [https://bugs.python.org/issue?@action=redirect&bpo=27497]: csv.DictWriter.writeheader() now returns the return value of the underlying csv.Writer.writerow() method. Patch contributed by Ashish Nitin Patil.

bpo-36239 [https://bugs.python.org/issue?@action=redirect&bpo=36239]: Parsing .mo files now ignores comments starting and ending with #-#-#-#-#.

bpo-26707 [https://bugs.python.org/issue?@action=redirect&bpo=26707]: Enable plistlib to read and write binary plist files that were created as a KeyedArchive file. Specifically, this allows the plistlib to process 0x80 tokens as UID objects.

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Add posix module support for VxWorks.

bpo-35125 [https://bugs.python.org/issue?@action=redirect&bpo=35125]: Asyncio: Remove inner callback on outer cancellation in shield

bpo-35721 [https://bugs.python.org/issue?@action=redirect&bpo=35721]: Fix asyncio.SelectorEventLoop.subprocess_exec() leaks file descriptors if Popen fails and called with stdin=subprocess.PIPE. Patch by Niklas Fiekas.

bpo-31855 [https://bugs.python.org/issue?@action=redirect&bpo=31855]: unittest.mock.mock_open() results now respects the argument of read([size]). Patch contributed by Rémi Lapeyre.

bpo-35431 [https://bugs.python.org/issue?@action=redirect&bpo=35431]: Implement math.comb() that returns binomial coefficient, that computes the number of ways to choose k items from n items without repetition and without order. Patch by Yash Aggarwal and Keller Fuchs.

bpo-26660 [https://bugs.python.org/issue?@action=redirect&bpo=26660]: Fixed permission errors in TemporaryDirectory clean up. Previously TemporaryDirectory.cleanup() failed when non-writeable or non-searchable files or directories were created inside a temporary directory.

bpo-34271 [https://bugs.python.org/issue?@action=redirect&bpo=34271]: Add debugging helpers to ssl module. It’s now possible to dump key material and to trace TLS protocol. The default and stdlib contexts also support SSLKEYLOGFILE env var.

bpo-26467 [https://bugs.python.org/issue?@action=redirect&bpo=26467]: Added AsyncMock to support using unittest to mock asyncio coroutines. Patch by Lisa Roach.

bpo-33569 [https://bugs.python.org/issue?@action=redirect&bpo=33569]: dataclasses.InitVar: Exposes the type used to create the init var.

bpo-34424 [https://bugs.python.org/issue?@action=redirect&bpo=34424]: Fix serialization of messages containing encoded strings when the policy.linesep is set to a multi-character string. Patch by Jens Troeger.

bpo-34303 [https://bugs.python.org/issue?@action=redirect&bpo=34303]: Performance of functools.reduce() is slightly improved. Patch by Sergey Fedoseev.

bpo-33361 [https://bugs.python.org/issue?@action=redirect&bpo=33361]: Fix a bug in codecs.StreamRecoder where seeking might leave old data in a buffer and break subsequent read calls. Patch by Ammar Askar.

bpo-22454 [https://bugs.python.org/issue?@action=redirect&bpo=22454]: The shlex module now exposes shlex.join(), the inverse of shlex.split(). Patch by Bo Bayles.

bpo-31922 [https://bugs.python.org/issue?@action=redirect&bpo=31922]: asyncio.AbstractEventLoop.create_datagram_endpoint(): Do not connect UDP socket when broadcast is allowed. This allows to receive replies after a UDP broadcast.

bpo-24882 [https://bugs.python.org/issue?@action=redirect&bpo=24882]: Change ThreadPoolExecutor to use existing idle threads before spinning up new ones.

bpo-31961 [https://bugs.python.org/issue?@action=redirect&bpo=31961]: Added support for bytes and path-like objects in subprocess.Popen() on Windows. The args parameter now accepts a path-like object if shell is False and a sequence containing bytes and path-like objects. The executable parameter now accepts a bytes and path-like object. The cwd parameter now accepts a bytes object. Based on patch by Anders Lorentsen.

bpo-33123 [https://bugs.python.org/issue?@action=redirect&bpo=33123]: pathlib.Path.unlink now accepts a missing_ok parameter to avoid a FileNotFoundError from being raised. Patch by Robert Buchholz.

bpo-32941 [https://bugs.python.org/issue?@action=redirect&bpo=32941]: Allow mmap.mmap objects to access the madvise() system call (through mmap.mmap.madvise()).

bpo-22102 [https://bugs.python.org/issue?@action=redirect&bpo=22102]: Added support for ZIP files with disks set to 0. Such files are commonly created by builtin tools on Windows when use ZIP64 extension. Patch by Francisco Facioni.

bpo-32515 [https://bugs.python.org/issue?@action=redirect&bpo=32515]: trace.py can now run modules via python3 -m trace -t –module module_name

bpo-32299 [https://bugs.python.org/issue?@action=redirect&bpo=32299]: Changed unittest.mock.patch.dict() to return the patched dictionary when used as context manager. Patch by Vadim Tsander.

bpo-27141 [https://bugs.python.org/issue?@action=redirect&bpo=27141]: Added a __copy__() to collections.UserList and collections.UserDict in order to correctly implement shallow copying of the objects. Patch by Bar Harel.

bpo-31829 [https://bugs.python.org/issue?@action=redirect&bpo=31829]: \r, \0 and \x1a (end-of-file on Windows) are now escaped in protocol 0 pickles of Unicode strings. This allows to load them without loss from files open in text mode in Python 2.

bpo-23395 [https://bugs.python.org/issue?@action=redirect&bpo=23395]: _thread.interrupt_main() now avoids setting the Python error status if the SIGINT signal is ignored or not handled by Python.

Documentation

bpo-36896 [https://bugs.python.org/issue?@action=redirect&bpo=36896]: Clarify that some types have unstable constructor signature between Python versions.

bpo-36686 [https://bugs.python.org/issue?@action=redirect&bpo=36686]: Improve documentation of the stdin, stdout, and stderr arguments of the asyncio.subprocess_exec function to specify which values are supported. Also mention that decoding as text is not supported.

Add a few tests to verify that the various values passed to the std* arguments actually work.

bpo-36984 [https://bugs.python.org/issue?@action=redirect&bpo=36984]: Improve version added references in typing module - by Anthony Sottile.

bpo-36868 [https://bugs.python.org/issue?@action=redirect&bpo=36868]: What’s new now mentions SSLContext.hostname_checks_common_name instead of SSLContext.host_flags.

bpo-35924 [https://bugs.python.org/issue?@action=redirect&bpo=35924]: Add a note to the curses.addstr() documentation to warn that multiline strings can cause segfaults because of an ncurses bug.

bpo-36783 [https://bugs.python.org/issue?@action=redirect&bpo=36783]: Added C API Documentation for Time_FromTimeAndFold and PyDateTime_FromDateAndTimeAndFold as per PEP 495. Patch by Edison Abahurire.

bpo-36797 [https://bugs.python.org/issue?@action=redirect&bpo=36797]: More of the legacy distutils documentation has been either pruned, or else more clearly marked as being retained solely until the setuptools documentation covers it independently.

bpo-22865 [https://bugs.python.org/issue?@action=redirect&bpo=22865]: Add detail to the documentation on the pty.spawn function.

bpo-35397 [https://bugs.python.org/issue?@action=redirect&bpo=35397]: Remove deprecation and document urllib.parse.unwrap(). Patch contributed by Rémi Lapeyre.

bpo-32995 [https://bugs.python.org/issue?@action=redirect&bpo=32995]: Added the context variable in glossary.

bpo-33519 [https://bugs.python.org/issue?@action=redirect&bpo=33519]: Clarify that copy() is not part of the MutableSequence ABC.

bpo-33482 [https://bugs.python.org/issue?@action=redirect&bpo=33482]: Make codecs.StreamRecoder.writelines take a list of bytes.

bpo-25735 [https://bugs.python.org/issue?@action=redirect&bpo=25735]: Added documentation for func factorial to indicate that returns integer values

bpo-20285 [https://bugs.python.org/issue?@action=redirect&bpo=20285]: Expand object.__doc__ (docstring) to make it clearer. Modify pydoc.py so that help(object) lists object methods (for other classes, help omits methods of the object base class.)

Tests

bpo-37069 [https://bugs.python.org/issue?@action=redirect&bpo=37069]: Modify test_coroutines, test_cprofile, test_generators, test_raise, test_ssl and test_yield_from to use test.support.catch_unraisable_exception() rather than test.support.captured_stderr().

bpo-37098 [https://bugs.python.org/issue?@action=redirect&bpo=37098]: Fix test_memfd_create on older Linux Kernels.

bpo-37081 [https://bugs.python.org/issue?@action=redirect&bpo=37081]: Test with OpenSSL 1.1.1c

bpo-36829 [https://bugs.python.org/issue?@action=redirect&bpo=36829]: Add test.support.catch_unraisable_exception(): context manager catching unraisable exception using sys.unraisablehook().

bpo-36915 [https://bugs.python.org/issue?@action=redirect&bpo=36915]: The main regrtest process now always removes all temporary directories of worker processes even if they crash or if they are killed on KeyboardInterrupt (CTRL+c).

bpo-36719 [https://bugs.python.org/issue?@action=redirect&bpo=36719]: «python3 -m test -jN …» now continues the execution of next tests when a worker process crash (CHILD_ERROR state). Previously, the test suite stopped immediately. Use –failfast to stop at the first error.

bpo-36816 [https://bugs.python.org/issue?@action=redirect&bpo=36816]: Update Lib/test/selfsigned_pythontestdotnet.pem to match self-signed.pythontest.net’s new TLS certificate.

bpo-35925 [https://bugs.python.org/issue?@action=redirect&bpo=35925]: Skip httplib and nntplib networking tests when they would otherwise fail due to a modern OS or distro with a default OpenSSL policy of rejecting connections to servers with weak certificates.

bpo-36782 [https://bugs.python.org/issue?@action=redirect&bpo=36782]: Add tests for several C API functions in the datetime module. Patch by Edison Abahurire.

bpo-36342 [https://bugs.python.org/issue?@action=redirect&bpo=36342]: Fix test_multiprocessing in test_venv if platform lacks functioning sem_open.

Build

bpo-36721 [https://bugs.python.org/issue?@action=redirect&bpo=36721]: To embed Python into an application, a new --embed option must be passed to python3-config --libs --embed to get -lpython3.8 (link the application to libpython). To support both 3.8 and older, try python3-config --libs --embed first and fallback to python3-config --libs (without --embed) if the previous command fails.

Add a pkg-config python-3.8-embed module to embed Python into an application: pkg-config python-3.8-embed --libs includes -lpython3.8. To support both 3.8 and older, try pkg-config python-X.Y-embed --libs first and fallback to pkg-config python-X.Y --libs (without --embed) if the previous command fails (replace X.Y with the Python version).

On the other hand, pkg-config python3.8 --libs no longer contains -lpython3.8. C extensions must not be linked to libpython (except on Android, case handled by the script); this change is backward incompatible on purpose.

bpo-36786 [https://bugs.python.org/issue?@action=redirect&bpo=36786]: «make install» now runs compileall in parallel.

Windows

bpo-36965 [https://bugs.python.org/issue?@action=redirect&bpo=36965]: include of STATUS_CONTROL_C_EXIT without depending on MSC compiler

bpo-35926 [https://bugs.python.org/issue?@action=redirect&bpo=35926]: Update to OpenSSL 1.1.1b for Windows.

bpo-29883 [https://bugs.python.org/issue?@action=redirect&bpo=29883]: Add Windows support for UDP transports for the Proactor Event Loop. Patch by Adam Meily.

bpo-33407 [https://bugs.python.org/issue?@action=redirect&bpo=33407]: The Py_DEPRECATED() macro has been implemented for MSVC.

macOS

bpo-36231 [https://bugs.python.org/issue?@action=redirect&bpo=36231]: Support building Python on macOS without /usr/include installed. As of macOS 10.14, system header files are only available within an SDK provided by either the Command Line Tools or the Xcode app.

IDLE

bpo-35610 [https://bugs.python.org/issue?@action=redirect&bpo=35610]: Replace now redundant .context_use_ps1 with .prompt_last_line. This finishes change started in bpo-31858 [https://bugs.python.org/issue?@action=redirect&bpo=31858].

bpo-37038 [https://bugs.python.org/issue?@action=redirect&bpo=37038]: Make idlelib.run runnable; add test clause.

bpo-36958 [https://bugs.python.org/issue?@action=redirect&bpo=36958]: Print any argument other than None or int passed to SystemExit or sys.exit().

bpo-36807 [https://bugs.python.org/issue?@action=redirect&bpo=36807]: When saving a file, call os.fsync() so bits are flushed to e.g. USB drive.

bpo-32411 [https://bugs.python.org/issue?@action=redirect&bpo=32411]: In browser.py, remove extraneous sorting by line number since dictionary was created in line number order.

Tools/Demos

bpo-37053 [https://bugs.python.org/issue?@action=redirect&bpo=37053]: Handle strings like u»bar» correctly in Tools/parser/unparse.py. Patch by Chih-Hsuan Yen.

C API

bpo-36763 [https://bugs.python.org/issue?@action=redirect&bpo=36763]: Implement the PEP 587 [https://www.python.org/dev/peps/pep-0587] «Python Initialization Configuration».

bpo-36379 [https://bugs.python.org/issue?@action=redirect&bpo=36379]: Fix crashes when attempting to use the modulo parameter when __ipow__ is implemented in C.

bpo-37107 [https://bugs.python.org/issue?@action=redirect&bpo=37107]: Update PyObject_CallMethodObjArgs() and _PyObject_CallMethodIdObjArgs to use _PyObject_GetMethod to avoid creating a bound method object in many cases. Patch by Michael J. Sullivan.

bpo-36974 [https://bugs.python.org/issue?@action=redirect&bpo=36974]: Implement PEP 590 [https://www.python.org/dev/peps/pep-0590]: Vectorcall: a fast calling protocol for CPython. This is a new protocol to optimize calls of custom callable objects.

bpo-36763 [https://bugs.python.org/issue?@action=redirect&bpo=36763]: Py_Main() now returns the exitcode rather than calling Py_Exit(exitcode) when calling PyErr_Print() if the current exception type is SystemExit.

bpo-36922 [https://bugs.python.org/issue?@action=redirect&bpo=36922]: Add new type flag Py_TPFLAGS_METHOD_DESCRIPTOR for objects behaving like unbound methods. These are objects supporting the optimization given by the LOAD_METHOD/CALL_METHOD opcodes. See PEP 590.

bpo-36728 [https://bugs.python.org/issue?@action=redirect&bpo=36728]: The PyEval_ReInitThreads() function has been removed from the C API. It should not be called explicitly: use PyOS_AfterFork_Child() instead.

Python 3.8.0 alpha 4

Release date: 2019-05-06

Security

bpo-36742 [https://bugs.python.org/issue?@action=redirect&bpo=36742]: Fixes mishandling of pre-normalization characters in urlsplit().

bpo-30458 [https://bugs.python.org/issue?@action=redirect&bpo=30458]: Address CVE-2019-9740 by disallowing URL paths with embedded whitespace or control characters through into the underlying http client request. Such potentially malicious header injection URLs now cause an http.client.InvalidURL exception to be raised.

bpo-35755 [https://bugs.python.org/issue?@action=redirect&bpo=35755]: shutil.which() now uses os.confstr("CS_PATH") if available and if the PATH environment variable is not set. Remove also the current directory from posixpath.defpath. On Unix, shutil.which() and the subprocess module no longer search the executable in the current directory if the PATH environment variable is not set.

Core and Builtins

bpo-36722 [https://bugs.python.org/issue?@action=redirect&bpo=36722]: In debug build, import now also looks for C extensions compiled in release mode and for C extensions compiled in the stable ABI.

bpo-32849 [https://bugs.python.org/issue?@action=redirect&bpo=32849]: Fix Python Initialization code on FreeBSD to detect properly when stdin file descriptor (fd 0) is invalid.

bpo-36623 [https://bugs.python.org/issue?@action=redirect&bpo=36623]: Remove parser headers and related function declarations that lack implementations after the removal of pgen.

bpo-20180 [https://bugs.python.org/issue?@action=redirect&bpo=20180]: dict.pop() is now up to 33% faster thanks to Argument Clinic. Patch by Inada Naoki.

bpo-36611 [https://bugs.python.org/issue?@action=redirect&bpo=36611]: Debug memory allocators: disable serialno field by default from debug hooks on Python memory allocators to reduce the memory footprint by 5%. Enable tracemalloc to get the traceback where a memory block has been allocated when a fatal memory error is logged to decide where to put a breakpoint. Compile Python with PYMEM_DEBUG_SERIALNO defined to get back the field.

bpo-36588 [https://bugs.python.org/issue?@action=redirect&bpo=36588]: On AIX, sys.platform doesn’t contain the major version anymore. Always return 'aix', instead of 'aix3' .. 'aix7'. Since older Python versions include the version number, it is recommended to always use sys.platform.startswith('aix'). Contributed by M. Felt.

bpo-36549 [https://bugs.python.org/issue?@action=redirect&bpo=36549]: Change str.capitalize to use titlecase for the first character instead of uppercase.

bpo-36540 [https://bugs.python.org/issue?@action=redirect&bpo=36540]: Implement PEP 570 [https://www.python.org/dev/peps/pep-0570] (Python positional-only parameters). Patch by Pablo Galindo.

bpo-36475 [https://bugs.python.org/issue?@action=redirect&bpo=36475]: PyEval_AcquireLock() and PyEval_AcquireThread() now terminate the current thread if called while the interpreter is finalizing, making them consistent with PyEval_RestoreThread(), Py_END_ALLOW_THREADS(), and PyGILState_Ensure().

bpo-36504 [https://bugs.python.org/issue?@action=redirect&bpo=36504]: Fix signed integer overflow in _ctypes.c’s PyCArrayType_new().

bpo-20844 [https://bugs.python.org/issue?@action=redirect&bpo=20844]: Fix running script with encoding cookie and LF line ending may fail on Windows.

bpo-24214 [https://bugs.python.org/issue?@action=redirect&bpo=24214]: Fixed support of the surrogatepass error handler in the UTF-8 incremental decoder.

bpo-36452 [https://bugs.python.org/issue?@action=redirect&bpo=36452]: Changing dict keys during iteration of the dict itself, keys(), values(), or items() will now be detected in certain corner cases where keys are deleted/added so that the number of keys isn’t changed. A RuntimeError will be raised after len(dict) iterations. Contributed by Thomas Perl.

bpo-36459 [https://bugs.python.org/issue?@action=redirect&bpo=36459]: Fix a possible double PyMem_FREE() due to tokenizer.c’s tok_nextc().

bpo-36433 [https://bugs.python.org/issue?@action=redirect&bpo=36433]: Fixed TypeError message in classmethoddescr_call.

bpo-36430 [https://bugs.python.org/issue?@action=redirect&bpo=36430]: Fix a possible reference leak in itertools.count().

bpo-36440 [https://bugs.python.org/issue?@action=redirect&bpo=36440]: Include node names in ParserError messages, instead of numeric IDs. Patch by A. Skrobov.

bpo-36143 [https://bugs.python.org/issue?@action=redirect&bpo=36143]: Regenerate keyword from the Grammar and Tokens file using pgen. Patch by Pablo Galindo.

bpo-18372 [https://bugs.python.org/issue?@action=redirect&bpo=18372]: Add missing PyObject_GC_Track() calls in the pickle module. Patch by Zackery Spytz.

Library

bpo-35952 [https://bugs.python.org/issue?@action=redirect&bpo=35952]: Fix pythoninfo when the compiler is missing.

bpo-28238 [https://bugs.python.org/issue?@action=redirect&bpo=28238]: The .find*() methods of xml.etree.ElementTree can now search for wildcards like {*}tag and {ns}* that match a tag in any namespace or all tags in a namespace. Patch by Stefan Behnel.

bpo-26978 [https://bugs.python.org/issue?@action=redirect&bpo=26978]: pathlib.path.link_to() is now implemented. It creates a hard link pointing to a path.

bpo-1613500 [https://bugs.python.org/issue?@action=redirect&bpo=1613500]: fileinput.FileInput now uses the input file mode to correctly set the output file mode (previously it was hardcoded to 'w') when inplace=True is passed to its constructor.

bpo-36734 [https://bugs.python.org/issue?@action=redirect&bpo=36734]: Fix compilation of faulthandler.c on HP-UX. Initialize stack_t current_stack to zero using memset().

bpo-13611 [https://bugs.python.org/issue?@action=redirect&bpo=13611]: The xml.etree.ElementTree packages gained support for C14N 2.0 serialisation. Patch by Stefan Behnel.

bpo-36669 [https://bugs.python.org/issue?@action=redirect&bpo=36669]: Add missing matrix multiplication operator support to weakref.proxy.

bpo-36676 [https://bugs.python.org/issue?@action=redirect&bpo=36676]: The XMLParser() in xml.etree.ElementTree provides namespace prefix context to the parser target if it defines the callback methods «start_ns()» and/or «end_ns()». Patch by Stefan Behnel.

bpo-36673 [https://bugs.python.org/issue?@action=redirect&bpo=36673]: The TreeBuilder and XMLPullParser in xml.etree.ElementTree gained support for parsing comments and processing instructions. Patch by Stefan Behnel.

bpo-36650 [https://bugs.python.org/issue?@action=redirect&bpo=36650]: The C version of functools.lru_cache() was treating calls with an empty **kwargs dictionary as being distinct from calls with no keywords at all. This did not result in an incorrect answer, but it did trigger an unexpected cache miss.

bpo-28552 [https://bugs.python.org/issue?@action=redirect&bpo=28552]: Fix distutils.sysconfig if sys.executable is None or an empty string: use os.getcwd() to initialize project_base. Fix also the distutils build command: don’t use sys.executable if it is None or an empty string.

bpo-35755 [https://bugs.python.org/issue?@action=redirect&bpo=35755]: shutil.which() and distutils.spawn.find_executable() now use os.confstr("CS_PATH") if available instead of os.defpath, if the PATH environment variable is not set. Moreover, don’t use os.confstr("CS_PATH") nor os.defpath if the PATH environment variable is set to an empty string.

bpo-25430 [https://bugs.python.org/issue?@action=redirect&bpo=25430]: improve performance of IPNetwork.__contains__()

bpo-30485 [https://bugs.python.org/issue?@action=redirect&bpo=30485]: Path expressions in xml.etree.ElementTree can now avoid explicit namespace prefixes for tags (or the «{namespace}tag» notation) by passing a default namespace with an empty string prefix.

bpo-36613 [https://bugs.python.org/issue?@action=redirect&bpo=36613]: Fix asyncio wait() not removing callback if exception

bpo-36598 [https://bugs.python.org/issue?@action=redirect&bpo=36598]: Fix isinstance check for Mock objects with spec when the code is executed under tracing. Patch by Karthikeyan Singaravelan.

bpo-18748 [https://bugs.python.org/issue?@action=redirect&bpo=18748]: In development mode (-X dev) and in debug build, the io.IOBase destructor now logs close() exceptions. These exceptions are silent by default in release mode.

bpo-36575 [https://bugs.python.org/issue?@action=redirect&bpo=36575]: The _lsprof module now uses internal timer same to time.perf_counter() by default. gettimeofday(2) was used on Unix. New timer has better resolution on most Unix platforms and timings are no longer impacted by system clock updates since perf_counter() is monotonic. Patch by Inada Naoki.

bpo-33461 [https://bugs.python.org/issue?@action=redirect&bpo=33461]: json.loads now emits DeprecationWarning when encoding option is specified. Patch by Matthias Bussonnier.

bpo-36559 [https://bugs.python.org/issue?@action=redirect&bpo=36559]: The random module now prefers the lean internal _sha512 module over hashlib for seed(version=2) to optimize import time.

bpo-17561 [https://bugs.python.org/issue?@action=redirect&bpo=17561]: Set backlog=None as the default for socket.create_server.

bpo-34373 [https://bugs.python.org/issue?@action=redirect&bpo=34373]: Fix time.mktime() error handling on AIX for year before 1970.

bpo-36232 [https://bugs.python.org/issue?@action=redirect&bpo=36232]: Improve error message when trying to open existing DBM database that actually doesn’t exist. Patch by Marco Rougeth.

bpo-36546 [https://bugs.python.org/issue?@action=redirect&bpo=36546]: Add statistics.quantiles()

bpo-36050 [https://bugs.python.org/issue?@action=redirect&bpo=36050]: Optimized http.client.HTTPResponse.read() for large response. Patch by Inada Naoki.

bpo-36522 [https://bugs.python.org/issue?@action=redirect&bpo=36522]: If debuglevel is set to >0 in http.client, print all values for headers with multiple values for the same header name. Patch by Matt Houglum.

bpo-36492 [https://bugs.python.org/issue?@action=redirect&bpo=36492]: Deprecated passing required arguments like func as keyword arguments in functions which should accept arbitrary keyword arguments and pass them to other function. Arbitrary keyword arguments (even with names «self» and «func») can now be passed to these functions if the required arguments are passed as positional arguments.

bpo-27181 [https://bugs.python.org/issue?@action=redirect&bpo=27181]: Add statistics.geometric_mean().

bpo-30427 [https://bugs.python.org/issue?@action=redirect&bpo=30427]: os.path.normcase() relies on os.fspath() to check the type of its argument. Redundant checks have been removed from its posixpath.normcase() and ntpath.normcase() implementations. Patch by Wolfgang Maier.

bpo-36385 [https://bugs.python.org/issue?@action=redirect&bpo=36385]: Stop rejecting IPv4 octets for being ambiguously octal. Leading zeros are ignored, and no longer are assumed to specify octal octets. Octets are always decimal numbers. Octets must still be no more than three digits, including leading zeroes.

bpo-36434 [https://bugs.python.org/issue?@action=redirect&bpo=36434]: Errors during writing to a ZIP file no longer prevent to properly close it.

bpo-36407 [https://bugs.python.org/issue?@action=redirect&bpo=36407]: Fixed wrong indentation writing for CDATA section in xml.dom.minidom. Patch by Vladimir Surjaninov.

bpo-36326 [https://bugs.python.org/issue?@action=redirect&bpo=36326]: inspect.getdoc() can now find docstrings for member objects when __slots__ is a dictionary.

bpo-36366 [https://bugs.python.org/issue?@action=redirect&bpo=36366]: Calling stop() on an unstarted or stopped unittest.mock.patch() object will now return None instead of raising RuntimeError, making the method idempotent. Patch by Karthikeyan Singaravelan.

bpo-36348 [https://bugs.python.org/issue?@action=redirect&bpo=36348]: The imap.IMAP4.logout() method no longer ignores silently arbitrary exceptions.

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Add time module support and fix test_time faiures for VxWorks.

bpo-36227 [https://bugs.python.org/issue?@action=redirect&bpo=36227]: Added support for keyword arguments default_namespace and xml_declaration in functions ElementTree.tostring() and ElementTree.tostringlist().

bpo-36004 [https://bugs.python.org/issue?@action=redirect&bpo=36004]: Added new alternate constructors datetime.date.fromisocalendar() and datetime.datetime.fromisocalendar(), which construct date objects from ISO year, week number and weekday; these are the inverse of each class’s isocalendar method. Patch by Paul Ganssle.

bpo-35936 [https://bugs.python.org/issue?@action=redirect&bpo=35936]: modulefinder no longer depends on the deprecated imp module, and the initializer for modulefinder.ModuleFinder now has immutable default arguments. Patch by Brandt Bucher.

bpo-35376 [https://bugs.python.org/issue?@action=redirect&bpo=35376]: modulefinder correctly handles modules that have the same name as a bad package. Patch by Brandt Bucher.

bpo-17396 [https://bugs.python.org/issue?@action=redirect&bpo=17396]: modulefinder no longer crashes when encountering syntax errors in followed imports. Patch by Brandt Bucher.

bpo-35934 [https://bugs.python.org/issue?@action=redirect&bpo=35934]: Added create_server() and has_dualstack_ipv6() convenience functions to automate the necessary tasks usually involved when creating a server socket, including accepting both IPv4 and IPv6 connections on the same socket. (Contributed by Giampaolo Rodola in bpo-17561 [https://bugs.python.org/issue?@action=redirect&bpo=17561].)

bpo-23078 [https://bugs.python.org/issue?@action=redirect&bpo=23078]: Add support for classmethod() and staticmethod() to unittest.mock.create_autospec(). Initial patch by Felipe Ochoa.

bpo-35416 [https://bugs.python.org/issue?@action=redirect&bpo=35416]: Fix potential resource warnings in distutils. Patch by Mickaël Schoentgen.

bpo-25451 [https://bugs.python.org/issue?@action=redirect&bpo=25451]: Add transparency methods to tkinter.PhotoImage. Patch by Zackery Spytz.

bpo-35082 [https://bugs.python.org/issue?@action=redirect&bpo=35082]: Don’t return deleted attributes when calling dir on a unittest.mock.Mock.

bpo-34547 [https://bugs.python.org/issue?@action=redirect&bpo=34547]: wsgiref.handlers.BaseHandler now handles abrupt client connection terminations gracefully. Patch by Petter Strandmark.

bpo-31658 [https://bugs.python.org/issue?@action=redirect&bpo=31658]: xml.sax.parse() now supports path-like. Patch by Mickaël Schoentgen.

bpo-34139 [https://bugs.python.org/issue?@action=redirect&bpo=34139]: Remove stale unix datagram socket before binding

bpo-33530 [https://bugs.python.org/issue?@action=redirect&bpo=33530]: Implemented Happy Eyeballs in asyncio.create_connection(). Added two new arguments, happy_eyeballs_delay and interleave, to specify Happy Eyeballs behavior.

bpo-33291 [https://bugs.python.org/issue?@action=redirect&bpo=33291]: Do not raise AttributeError when calling the inspect functions isgeneratorfunction, iscoroutinefunction, isasyncgenfunction on a method created from an arbitrary callable. Instead, return False.

bpo-31310 [https://bugs.python.org/issue?@action=redirect&bpo=31310]: Fix the multiprocessing.semaphore_tracker so it is reused by child processes

bpo-31292 [https://bugs.python.org/issue?@action=redirect&bpo=31292]: Fix setup.py check --restructuredtext for files containing include directives.

Documentation

bpo-36625 [https://bugs.python.org/issue?@action=redirect&bpo=36625]: Remove obsolete comments from docstrings in fractions.Fraction

bpo-30840 [https://bugs.python.org/issue?@action=redirect&bpo=30840]: Document relative imports

bpo-36523 [https://bugs.python.org/issue?@action=redirect&bpo=36523]: Add docstring for io.IOBase.writelines().

bpo-36425 [https://bugs.python.org/issue?@action=redirect&bpo=36425]: New documentation translation: Simplified Chinese [https://docs.python.org/zh-cn/].

bpo-36345 [https://bugs.python.org/issue?@action=redirect&bpo=36345]: Avoid the duplication of code from Tools/scripts/serve.py in using the literalinclude directive for the basic wsgiref-based web server in the documentation of wsgiref. Contributed by Stéphane Wirtel.

bpo-36345 [https://bugs.python.org/issue?@action=redirect&bpo=36345]: Using the code of the Tools/scripts/serve.py script as an example in the wsgiref documentation. Contributed by Stéphane Wirtel.

bpo-36157 [https://bugs.python.org/issue?@action=redirect&bpo=36157]: Added Documention for PyInterpreterState_Main().

bpo-33043 [https://bugs.python.org/issue?@action=redirect&bpo=33043]: Updates the docs.python.org page with the addition of a “Contributing to Docs” link at the end of the page (between “Reporting Bugs” and “About Documentation”). Updates the “Found a Bug” page with additional links and information in the Documentation Bugs section.

bpo-35581 [https://bugs.python.org/issue?@action=redirect&bpo=35581]: @typing.type_check_only now allows type stubs to mark functions and classes not available during runtime.

bpo-33832 [https://bugs.python.org/issue?@action=redirect&bpo=33832]: Add glossary entry for “magic method”.

bpo-32913 [https://bugs.python.org/issue?@action=redirect&bpo=32913]: Added re.Match.groupdict example to regex HOWTO.

Tests

bpo-36719 [https://bugs.python.org/issue?@action=redirect&bpo=36719]: regrtest now always detects uncollectable objects. Previously, the check was only enabled by --findleaks. The check now also works with -jN/--multiprocess N. --findleaks becomes a deprecated alias to --fail-env-changed.

bpo-36725 [https://bugs.python.org/issue?@action=redirect&bpo=36725]: When using multiprocessing mode (-jN), regrtest now better reports errors if a worker process fails, and it exits immediately on a worker thread failure or when interrupted.

bpo-36454 [https://bugs.python.org/issue?@action=redirect&bpo=36454]: Change test_time.test_monotonic() to test only the lower bound of elapsed time after a sleep command rather than the upper bound. This prevents unnecessary test failures on slow buildbots. Patch by Victor Stinner.

bpo-32424 [https://bugs.python.org/issue?@action=redirect&bpo=32424]: Improve test coverage for xml.etree.ElementTree. Patch by Gordon P. Hemsley.

bpo-32424 [https://bugs.python.org/issue?@action=redirect&bpo=32424]: Fix typo in test_cyclic_gc() test for xml.etree.ElementTree. Patch by Gordon P. Hemsley.

bpo-36635 [https://bugs.python.org/issue?@action=redirect&bpo=36635]: Add a new _testinternalcapi module to test the internal C API.

bpo-36629 [https://bugs.python.org/issue?@action=redirect&bpo=36629]: Fix test_imap4_host_default_value() of test_imaplib: catch also errno.ENETUNREACH error.

bpo-36611 [https://bugs.python.org/issue?@action=redirect&bpo=36611]: Fix test_sys.test_getallocatedblocks() when tracemalloc is enabled.

bpo-36560 [https://bugs.python.org/issue?@action=redirect&bpo=36560]: Fix reference leak hunting in regrtest: compute also deltas (of reference count, allocated memory blocks, file descriptor count) during warmup, to ensure that everything is initialized before starting to hunt reference leaks.

bpo-36565 [https://bugs.python.org/issue?@action=redirect&bpo=36565]: Fix reference hunting (python3 -m test -R 3:3) when Python has no built-in abc module.

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Port test_resource to VxWorks: skip tests cases setting RLIMIT_FSIZE and RLIMIT_CPU.

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Fix test_tabnanny on VxWorks: adjust ENOENT error message.

bpo-36436 [https://bugs.python.org/issue?@action=redirect&bpo=36436]: Fix _testcapi.pymem_buffer_overflow(): handle memory allocation failure.

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Fix test_utf8_mode on VxWorks: Python always use UTF-8 on VxWorks.

bpo-36341 [https://bugs.python.org/issue?@action=redirect&bpo=36341]: Fix tests that may fail with PermissionError upon calling bind() on AF_UNIX sockets.

Build

bpo-36747 [https://bugs.python.org/issue?@action=redirect&bpo=36747]: Remove the stale scriptsinstall Makefile target.

bpo-21536 [https://bugs.python.org/issue?@action=redirect&bpo=21536]: On Unix, C extensions are no longer linked to libpython except on Android and Cygwin.

It is now possible for a statically linked Python to load a C extension built using a shared library Python.

When Python is embedded, libpython must not be loaded with RTLD_LOCAL, but RTLD_GLOBAL instead. Previously, using RTLD_LOCAL, it was already not possible to load C extensions which were not linked to libpython, such as C extensions of the standard library built by the *shared* section of Modules/Setup.

distutils, python-config and python-config.py have been modified.

bpo-36707 [https://bugs.python.org/issue?@action=redirect&bpo=36707]: ./configure --with-pymalloc no longer adds the m flag to SOABI (sys.implementation.cache_tag). Enabling or disabling pymalloc has no impact on the ABI.

bpo-36635 [https://bugs.python.org/issue?@action=redirect&bpo=36635]: Change PyAPI_FUNC(type), PyAPI_DATA(type) and PyMODINIT_FUNC macros of pyport.h when Py_BUILD_CORE_MODULE is defined. The Py_BUILD_CORE_MODULE define must be now be used to build a C extension as a dynamic library accessing Python internals: export the PyInit_xxx() function in DLL exports on Windows.

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Don’t build the _crypt extension on VxWorks.

bpo-36618 [https://bugs.python.org/issue?@action=redirect&bpo=36618]: Add -fmax-type-align=8 to CFLAGS when clang compiler is detected. The pymalloc memory allocator aligns memory on 8 bytes. On x86-64, clang expects alignment on 16 bytes by default and so uses MOVAPS instruction which can lead to segmentation fault. Instruct clang that Python is limited to alignment on 8 bytes to use MOVUPS instruction instead: slower but don’t trigger a SIGSEGV if the memory is not aligned on 16 bytes. Sadly, the flag must be added to CFLAGS and not just CFLAGS_NODIST, since third party C extensions can have the same issue.

bpo-36605 [https://bugs.python.org/issue?@action=redirect&bpo=36605]: make tags and make TAGS now also parse Modules/_io/*.c and Modules/_io/*.h.

bpo-36465 [https://bugs.python.org/issue?@action=redirect&bpo=36465]: Release builds and debug builds are now ABI compatible: defining the Py_DEBUG macro no longer implies the Py_TRACE_REFS macro, which introduces the only ABI incompatibility. The Py_TRACE_REFS macro, which adds the sys.getobjects() function and the PYTHONDUMPREFS environment variable, can be set using the new ./configure --with-trace-refs build option.

bpo-36577 [https://bugs.python.org/issue?@action=redirect&bpo=36577]: setup.py now correctly reports missing OpenSSL headers and libraries again.

bpo-36544 [https://bugs.python.org/issue?@action=redirect&bpo=36544]: Fix regression introduced in bpo-36146 [https://bugs.python.org/issue?@action=redirect&bpo=36146] refactoring setup.py

bpo-36508 [https://bugs.python.org/issue?@action=redirect&bpo=36508]: python-config --ldflags no longer includes flags of the LINKFORSHARED variable. The LINKFORSHARED variable must only be used to build executables.

bpo-36503 [https://bugs.python.org/issue?@action=redirect&bpo=36503]: Remove references to «aix3» and «aix4». Patch by M. Felt.

Windows

bpo-35920 [https://bugs.python.org/issue?@action=redirect&bpo=35920]: Added platform.win32_edition() and platform.win32_is_iot(). Added support for cross-compiling packages for Windows ARM32. Skip tests that are not expected to work on Windows IoT Core ARM32.

bpo-36649 [https://bugs.python.org/issue?@action=redirect&bpo=36649]: Remove trailing spaces for registry keys when installed via the Store.

bpo-34144 [https://bugs.python.org/issue?@action=redirect&bpo=34144]: Fixed activate.bat to correctly update codepage when chcp.com returns dots in output. Patch by Lorenz Mende.

bpo-36509 [https://bugs.python.org/issue?@action=redirect&bpo=36509]: Added preset-iot layout for Windows IoT ARM containers. This layout doesn’t contain UI components like tkinter or IDLE. It also doesn’t contain files to support on-target builds since Windows ARM32 builds must be cross-compiled when using MSVC.

bpo-35941 [https://bugs.python.org/issue?@action=redirect&bpo=35941]: enum_certificates function of the ssl module now returns certificates from all available certificate stores inside windows in a query instead of returning only certificates from the system wide certificate store. This includes certificates from these certificate stores: local machine, local machine enterprise, local machine group policy, current user, current user group policy, services, users. ssl.enum_crls() function is changed in the same way to return all certificate revocation lists inside the windows certificate revocation list stores.

bpo-36441 [https://bugs.python.org/issue?@action=redirect&bpo=36441]: Fixes creating a venv when debug binaries are installed.

bpo-36085 [https://bugs.python.org/issue?@action=redirect&bpo=36085]: Enable better DLL resolution on Windows by using safe DLL search paths and adding os.add_dll_directory().

bpo-36010 [https://bugs.python.org/issue?@action=redirect&bpo=36010]: Add the venv standard library module to the nuget distribution for Windows.

bpo-29515 [https://bugs.python.org/issue?@action=redirect&bpo=29515]: Add the following socket module constants on Windows: IPPROTO_AH IPPROTO_CBT IPPROTO_DSTOPTS IPPROTO_EGP IPPROTO_ESP IPPROTO_FRAGMENT IPPROTO_GGP IPPROTO_HOPOPTS IPPROTO_ICLFXBM IPPROTO_ICMPV6 IPPROTO_IDP IPPROTO_IGMP IPPROTO_IGP IPPROTO_IPV4 IPPROTO_IPV6 IPPROTO_L2TP IPPROTO_MAX IPPROTO_ND IPPROTO_NONE IPPROTO_PGM IPPROTO_PIM IPPROTO_PUP IPPROTO_RDP IPPROTO_ROUTING IPPROTO_SCTP IPPROTO_ST

bpo-35947 [https://bugs.python.org/issue?@action=redirect&bpo=35947]: Added current version of libffi to cpython-source-deps. Change _ctypes to use current version of libffi on Windows.

bpo-34060 [https://bugs.python.org/issue?@action=redirect&bpo=34060]: Report system load when running test suite on Windows. Patch by Ammar Askar. Based on prior work by Jeremy Kloth.

bpo-31512 [https://bugs.python.org/issue?@action=redirect&bpo=31512]: With the Windows 10 Creators Update, non-elevated users can now create symlinks as long as the computer has Developer Mode enabled.

macOS

bpo-34602 [https://bugs.python.org/issue?@action=redirect&bpo=34602]: Avoid failures setting macOS stack resource limit with resource.setrlimit. This reverts an earlier fix for bpo-18075 [https://bugs.python.org/issue?@action=redirect&bpo=18075] which forced a non-default stack size when building the interpreter executable on macOS.

IDLE

bpo-36429 [https://bugs.python.org/issue?@action=redirect&bpo=36429]: Fix starting IDLE with pyshell. Add idlelib.pyshell alias at top; remove pyshell alias at bottom. Remove obsolete __name__==”__main__” command.

Tools/Demos

bpo-14546 [https://bugs.python.org/issue?@action=redirect&bpo=14546]: Fix the argument handling in Tools/scripts/lll.py.

C API

bpo-36763 [https://bugs.python.org/issue?@action=redirect&bpo=36763]: Fix memory leak in Py_SetStandardStreamEncoding(): release memory if the function is called twice.

bpo-36641 [https://bugs.python.org/issue?@action=redirect&bpo=36641]: PyDoc_VAR(name) and PyDoc_STRVAR(name,str) now create static const char name[] instead of static char name[]. Patch by Inada Naoki.

bpo-36389 [https://bugs.python.org/issue?@action=redirect&bpo=36389]: Change the value of CLEANBYTE, DEADDYTE and FORBIDDENBYTE internal constants used by debug hooks on Python memory allocators (PyMem_SetupDebugHooks() function). Byte patterns 0xCB, 0xDB and 0xFB have been replaced with 0xCD, 0xDD and 0xFD to use the same values than Windows CRT debug malloc() and free().

bpo-36443 [https://bugs.python.org/issue?@action=redirect&bpo=36443]: Since Python 3.7.0, calling Py_DecodeLocale() before Py_Initialize() produces mojibake if the LC_CTYPE locale is coerced and/or if the UTF-8 Mode is enabled by the user configuration. The LC_CTYPE coercion and UTF-8 Mode are now disabled by default to fix the mojibake issue. They must now be enabled explicitly (opt-in) using the new _Py_PreInitialize() API with _PyPreConfig.

bpo-36025 [https://bugs.python.org/issue?@action=redirect&bpo=36025]: Fixed an accidental change to the datetime C API where the arguments to the PyDate_FromTimestamp() function were incorrectly interpreted as a single timestamp rather than an arguments tuple, which causes existing code to start raising TypeError. The backwards-incompatible change was only present in alpha releases of Python 3.8. Patch by Paul Ganssle.

bpo-35810 [https://bugs.python.org/issue?@action=redirect&bpo=35810]: Modify PyObject_Init to correctly increase the refcount of heap- allocated Type objects. Also fix the refcounts of the heap-allocated types that were either doing this manually or not decreasing the type’s refcount in tp_dealloc

Python 3.8.0 alpha 3

Release date: 2019-03-25

Security

bpo-36216 [https://bugs.python.org/issue?@action=redirect&bpo=36216]: Changes urlsplit() to raise ValueError when the URL contains characters that decompose under IDNA encoding (NFKC-normalization) into characters that affect how the URL is parsed.

bpo-35121 [https://bugs.python.org/issue?@action=redirect&bpo=35121]: Don’t send cookies of domain A without Domain attribute to domain B when domain A is a suffix match of domain B while using a cookiejar with http.cookiejar.DefaultCookiePolicy policy. Patch by Karthikeyan Singaravelan.

Core and Builtins

bpo-36421 [https://bugs.python.org/issue?@action=redirect&bpo=36421]: Fix a possible double decref in _ctypes.c’s PyCArrayType_new().

bpo-36412 [https://bugs.python.org/issue?@action=redirect&bpo=36412]: Fix a possible crash when creating a new dictionary.

bpo-36398 [https://bugs.python.org/issue?@action=redirect&bpo=36398]: Fix a possible crash in structseq_repr().

bpo-36256 [https://bugs.python.org/issue?@action=redirect&bpo=36256]: Fix bug in parsermodule when parsing a state in a DFA that has two or more arcs with labels of the same type. Patch by Pablo Galindo.

bpo-36365 [https://bugs.python.org/issue?@action=redirect&bpo=36365]: repr(structseq) is no longer limited to 512 bytes.

bpo-36374 [https://bugs.python.org/issue?@action=redirect&bpo=36374]: Fix a possible null pointer dereference in merge_consts_recursive(). Patch by Zackery Spytz.

bpo-36236 [https://bugs.python.org/issue?@action=redirect&bpo=36236]: At Python initialization, the current directory is no longer prepended to sys.path if it has been removed.

bpo-36352 [https://bugs.python.org/issue?@action=redirect&bpo=36352]: Python initialization now fails with an error, rather than silently truncating paths, if a path is too long.

bpo-36301 [https://bugs.python.org/issue?@action=redirect&bpo=36301]: Python initialization now fails if decoding pybuilddir.txt configuration file fails at startup.

bpo-36333 [https://bugs.python.org/issue?@action=redirect&bpo=36333]: Fix leak in _PyRuntimeState_Fini. Contributed by Stéphane Wirtel.

bpo-36332 [https://bugs.python.org/issue?@action=redirect&bpo=36332]: The builtin compile() can now handle AST objects that contain assignment expressions. Patch by Pablo Galindo.

bpo-36282 [https://bugs.python.org/issue?@action=redirect&bpo=36282]: Improved error message for too much positional arguments in some builtin functions.

bpo-30040 [https://bugs.python.org/issue?@action=redirect&bpo=30040]: New empty dict uses fewer memory for now. It used more memory than empty dict created by dict.clear(). And empty dict creation and deletion is about 2x faster. Patch by Inada Naoki.

bpo-36262 [https://bugs.python.org/issue?@action=redirect&bpo=36262]: Fix an unlikely memory leak on conversion from string to float in the function _Py_dg_strtod() used by float(str), complex(str), pickle.load(), marshal.load(), etc.

bpo-36252 [https://bugs.python.org/issue?@action=redirect&bpo=36252]: Update Unicode databases to version 12.0.0.

bpo-36218 [https://bugs.python.org/issue?@action=redirect&bpo=36218]: Fix a segfault occurring when sorting a list of heterogeneous values. Patch contributed by Rémi Lapeyre and Elliot Gorokhovsky.

bpo-36188 [https://bugs.python.org/issue?@action=redirect&bpo=36188]: Cleaned up left-over vestiges of Python 2 unbound method handling in method objects and documentation. Patch by Martijn Pieters

bpo-36124 [https://bugs.python.org/issue?@action=redirect&bpo=36124]: Add a new interpreter-specific dict and expose it in the C-API via PyInterpreterState_GetDict(). This parallels PyThreadState_GetDict(). However, extension modules should continue using PyModule_GetState() for their own internal per-interpreter state.

bpo-35975 [https://bugs.python.org/issue?@action=redirect&bpo=35975]: Add a feature_version flag to ast.parse() (documented) and compile() (hidden) that allows tweaking the parser to support older versions of the grammar. In particular, if feature_version is 5 or 6, the hacks for the async and await keyword from PEP 492 are reinstated. (For 7 or higher, these are unconditionally treated as keywords, but they are still special tokens rather than NAME tokens that the parser driver recognizes.)

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Use UTF-8 as the system encoding on VxWorks.

bpo-36048 [https://bugs.python.org/issue?@action=redirect&bpo=36048]: The __index__() special method will be used instead of __int__() for implicit conversion of Python numbers to C integers. Using the __int__() method in implicit conversions has been deprecated.

bpo-35808 [https://bugs.python.org/issue?@action=redirect&bpo=35808]: Retire pgen and use a modified version of pgen2 to generate the parser. Patch by Pablo Galindo.

Library

bpo-36401 [https://bugs.python.org/issue?@action=redirect&bpo=36401]: The class documentation created by pydoc now has a separate section for readonly properties.

bpo-36320 [https://bugs.python.org/issue?@action=redirect&bpo=36320]: The typing.NamedTuple() class has deprecated the _field_types attribute in favor of the __annotations__ attribute which carried the same information. Also, both attributes were converted from OrderedDict to a regular dict.

bpo-34745 [https://bugs.python.org/issue?@action=redirect&bpo=34745]: Fix asyncio ssl memory issues caused by circular references

bpo-36324 [https://bugs.python.org/issue?@action=redirect&bpo=36324]: Add method to statistics.NormalDist for computing the inverse cumulative normal distribution.

bpo-36321 [https://bugs.python.org/issue?@action=redirect&bpo=36321]: collections.namedtuple() misspelled the name of an attribute. To be consistent with typing.NamedTuple, the attribute name should have been «_field_defaults» instead of «_fields_defaults». For backwards compatibility, both spellings are now created. The misspelled version may be removed in the future.

bpo-36297 [https://bugs.python.org/issue?@action=redirect&bpo=36297]: «unicode_internal» codec is removed. It was deprecated since Python 3.3. Patch by Inada Naoki.

bpo-36298 [https://bugs.python.org/issue?@action=redirect&bpo=36298]: Raise ModuleNotFoundError in pyclbr when a module can’t be found. Thanks to “mental” for the bug report.

bpo-36268 [https://bugs.python.org/issue?@action=redirect&bpo=36268]: Switch the default format used for writing tars with mod:tarfile to the modern POSIX.1-2001 pax standard, from the vendor-specific GNU. Contributed by C.A.M. Gerlach.

bpo-36285 [https://bugs.python.org/issue?@action=redirect&bpo=36285]: Fix integer overflows in the array module. Patch by Stephan Hohe.

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Add _signal module support for VxWorks.

bpo-36272 [https://bugs.python.org/issue?@action=redirect&bpo=36272]: logging does not silently ignore RecursionError anymore. Patch contributed by Rémi Lapeyre.

bpo-36280 [https://bugs.python.org/issue?@action=redirect&bpo=36280]: Add a kind field to ast.Constant. It is “u” if the literal has a “u” prefix (i.e. a Python 2 style unicode literal), else None.

bpo-35931 [https://bugs.python.org/issue?@action=redirect&bpo=35931]: The pdb debug command now gracefully handles all exceptions.

bpo-36251 [https://bugs.python.org/issue?@action=redirect&bpo=36251]: Fix format strings used for stderrprinter and re.Match reprs. Patch by Stephan Hohe.

bpo-36235 [https://bugs.python.org/issue?@action=redirect&bpo=36235]: Fix CFLAGS in customize_compiler() of distutils.sysconfig: when the CFLAGS environment variable is defined, don’t override CFLAGS variable with the OPT variable anymore. Initial patch written by David Malcolm.

bpo-35807 [https://bugs.python.org/issue?@action=redirect&bpo=35807]: Update ensurepip to install pip 19.0.3 and setuptools 40.8.0.

bpo-36139 [https://bugs.python.org/issue?@action=redirect&bpo=36139]: Release GIL when closing mmap objects.

bpo-36179 [https://bugs.python.org/issue?@action=redirect&bpo=36179]: Fix two unlikely reference leaks in _hashopenssl. The leaks only occur in out-of-memory cases.

bpo-36169 [https://bugs.python.org/issue?@action=redirect&bpo=36169]: Add overlap() method to statistics.NormalDist. Computes the overlapping coefficient for two normal distributions.

bpo-36103 [https://bugs.python.org/issue?@action=redirect&bpo=36103]: Default buffer size used by shutil.copyfileobj() is changed from 16 KiB to 64 KiB on non-Windows platform to reduce system call overhead. Contributed by Inada Naoki.

bpo-36130 [https://bugs.python.org/issue?@action=redirect&bpo=36130]: Fix pdb with skip=... when stepping into a frame without a __name__ global. Patch by Anthony Sottile.

bpo-35652 [https://bugs.python.org/issue?@action=redirect&bpo=35652]: shutil.copytree(copy_function=…) erroneously pass DirEntry instead of a path string.

bpo-35178 [https://bugs.python.org/issue?@action=redirect&bpo=35178]: Ensure custom warnings.formatwarning() function can receive line as positional argument. Based on patch by Tashrif Billah.

bpo-36106 [https://bugs.python.org/issue?@action=redirect&bpo=36106]: Resolve potential name clash with libm’s sinpi(). Patch by Dmitrii Pasechnik.

bpo-36091 [https://bugs.python.org/issue?@action=redirect&bpo=36091]: Clean up reference to async generator in Lib/types. Patch by Henry Chen.

bpo-36043 [https://bugs.python.org/issue?@action=redirect&bpo=36043]: FileCookieJar supports path-like object. Contributed by Stéphane Wirtel

bpo-35899 [https://bugs.python.org/issue?@action=redirect&bpo=35899]: Enum has been fixed to correctly handle empty strings and strings with non-Latin characters (ie. “α”, “א”) without crashing. Original patch contributed by Maxwell. Assisted by Stéphane Wirtel.

bpo-21269 [https://bugs.python.org/issue?@action=redirect&bpo=21269]: Add args and kwargs properties to mock call objects. Contributed by Kumar Akshay.

bpo-30670 [https://bugs.python.org/issue?@action=redirect&bpo=30670]: pprint.pp has been added to pretty-print objects with dictionary keys being sorted with their insertion order by default. Parameter sort_dicts has been added to pprint.pprint, pprint.pformat and pprint.PrettyPrinter. Contributed by Rémi Lapeyre.

bpo-35843 [https://bugs.python.org/issue?@action=redirect&bpo=35843]: Implement __getitem__ for _NamespacePath. Patch by Anthony Sottile.

bpo-35802 [https://bugs.python.org/issue?@action=redirect&bpo=35802]: Clean up code which checked presence of os.stat / os.lstat / os.chmod which are always present. Patch by Anthony Sottile.

bpo-35715 [https://bugs.python.org/issue?@action=redirect&bpo=35715]: Librates the return value of a ProcessPoolExecutor _process_worker after it’s no longer needed to free memory

bpo-35493 [https://bugs.python.org/issue?@action=redirect&bpo=35493]: Use multiprocessing.connection.wait() instead of polling each 0.2 seconds for worker updates in multiprocessing.Pool. Patch by Pablo Galindo.

bpo-35661 [https://bugs.python.org/issue?@action=redirect&bpo=35661]: Store the venv prompt in pyvenv.cfg.

bpo-35121 [https://bugs.python.org/issue?@action=redirect&bpo=35121]: Don’t set cookie for a request when the request path is a prefix match of the cookie’s path attribute but doesn’t end with «/». Patch by Karthikeyan Singaravelan.

bpo-21478 [https://bugs.python.org/issue?@action=redirect&bpo=21478]: Calls to a child function created with unittest.mock.create_autospec() should propagate to the parent. Patch by Karthikeyan Singaravelan.

bpo-35198 [https://bugs.python.org/issue?@action=redirect&bpo=35198]: Fix C++ extension compilation on AIX

Documentation

bpo-36329 [https://bugs.python.org/issue?@action=redirect&bpo=36329]: Declare the path of the Python binary for the usage of Tools/scripts/serve.py when executing make -C Doc/ serve. Contributed by Stéphane Wirtel

bpo-36138 [https://bugs.python.org/issue?@action=redirect&bpo=36138]: Improve documentation about converting datetime.timedelta to scalars.

bpo-21314 [https://bugs.python.org/issue?@action=redirect&bpo=21314]: A new entry was added to the Core Language Section of the Programming FAQ, which explaines the usage of slash(/) in the signature of a function. Patch by Lysandros Nikolaou

Tests

bpo-36234 [https://bugs.python.org/issue?@action=redirect&bpo=36234]: test_posix.PosixUidGidTests: add tests for invalid uid/gid type (str). Initial patch written by David Malcolm.

bpo-29571 [https://bugs.python.org/issue?@action=redirect&bpo=29571]: Fix test_re.test_locale_flag(): use locale.getpreferredencoding() rather than locale.getlocale() to get the locale encoding. With some locales, locale.getlocale() returns the wrong encoding.

bpo-36123 [https://bugs.python.org/issue?@action=redirect&bpo=36123]: Fix race condition in test_socket.

Build

bpo-36356 [https://bugs.python.org/issue?@action=redirect&bpo=36356]: Fix leaks that led to build failure when configured with address sanitizer.

bpo-36146 [https://bugs.python.org/issue?@action=redirect&bpo=36146]: Add TEST_EXTENSIONS constant to setup.py to allow to not build test extensions like _testcapi.

bpo-36146 [https://bugs.python.org/issue?@action=redirect&bpo=36146]: Fix setup.py on macOS: only add /usr/include/ffi to include directories of _ctypes, not for all extensions.

bpo-31904 [https://bugs.python.org/issue?@action=redirect&bpo=31904]: Enable build system to cross-build for VxWorks RTOS.

Windows

bpo-36312 [https://bugs.python.org/issue?@action=redirect&bpo=36312]: Fixed decoders for the following code pages: 50220, 50221, 50222, 50225, 50227, 50229, 57002 through 57011, 65000 and 42.

bpo-36264 [https://bugs.python.org/issue?@action=redirect&bpo=36264]: Don’t honor POSIX HOME in os.path.expanduser on windows. Patch by Anthony Sottile.

bpo-24643 [https://bugs.python.org/issue?@action=redirect&bpo=24643]: Fix name collisions due to #define timezone _timezone in PC/pyconfig.h.

IDLE

bpo-36405 [https://bugs.python.org/issue?@action=redirect&bpo=36405]: Use dict unpacking in idlelib.

bpo-36396 [https://bugs.python.org/issue?@action=redirect&bpo=36396]: Remove fgBg param of idlelib.config.GetHighlight(). This param was only used twice and changed the return type.

bpo-36176 [https://bugs.python.org/issue?@action=redirect&bpo=36176]: Fix IDLE autocomplete & calltip popup colors. Prevent conflicts with Linux dark themes (and slightly darken calltip background).

bpo-23205 [https://bugs.python.org/issue?@action=redirect&bpo=23205]: For the grep module, add tests for findfiles, refactor findfiles to be a module-level function, and refactor findfiles to use os.walk.

bpo-23216 [https://bugs.python.org/issue?@action=redirect&bpo=23216]: Add docstrings to IDLE search modules.

bpo-36152 [https://bugs.python.org/issue?@action=redirect&bpo=36152]: Remove colorizer.ColorDelegator.close_when_done and the corresponding argument of .close(). In IDLE, both have always been None or False since 2007.

bpo-32129 [https://bugs.python.org/issue?@action=redirect&bpo=32129]: Avoid blurry IDLE application icon on macOS with Tk 8.6. Patch by Kevin Walzer.

bpo-36096 [https://bugs.python.org/issue?@action=redirect&bpo=36096]: Refactor class variables to instance variables in colorizer.

bpo-30348 [https://bugs.python.org/issue?@action=redirect&bpo=30348]: Increase test coverage of idlelib.autocomplete by 30%. Patch by Louie Lu

Tools/Demos

bpo-35132 [https://bugs.python.org/issue?@action=redirect&bpo=35132]: Fix py-list and py-bt commands of python-gdb.py on gdb7.

bpo-32217 [https://bugs.python.org/issue?@action=redirect&bpo=32217]: Fix freeze script on Windows.

C API

bpo-36381 [https://bugs.python.org/issue?@action=redirect&bpo=36381]: Raise DeprecationWarning when “#” formats are used for building or parsing values without PY_SSIZE_T_CLEAN.

bpo-36142 [https://bugs.python.org/issue?@action=redirect&bpo=36142]: The whole coreconfig.h header is now excluded from Py_LIMITED_API. Move functions definitions into a new internal pycore_coreconfig.h header.

Python 3.8.0 alpha 2

Release date: 2019-02-25

Core and Builtins

bpo-36052 [https://bugs.python.org/issue?@action=redirect&bpo=36052]: Raise a SyntaxError when assigning a value to __debug__ with the Assignment Operator. Contributed by Stéphane Wirtel and Pablo Galindo.

bpo-36012 [https://bugs.python.org/issue?@action=redirect&bpo=36012]: Doubled the speed of class variable writes. When a non-dunder attribute was updated, there was an unnecessary call to update slots.

bpo-35942 [https://bugs.python.org/issue?@action=redirect&bpo=35942]: The error message emitted when returning invalid types from __fspath__ in interfaces that allow passing PathLike objects has been improved and now it does explain the origin of the error.

bpo-36016 [https://bugs.python.org/issue?@action=redirect&bpo=36016]: gc.get_objects can now receive an optional parameter indicating a generation to get objects from. Patch by Pablo Galindo.

bpo-1054041 [https://bugs.python.org/issue?@action=redirect&bpo=1054041]: When the main interpreter exits due to an uncaught KeyboardInterrupt, the process now exits in the appropriate manner for its parent process to detect that a SIGINT or ^C terminated the process. This allows shells and batch scripts to understand that the user has asked them to stop.

bpo-35992 [https://bugs.python.org/issue?@action=redirect&bpo=35992]: Fix __class_getitem__() not being called on a class with a custom non-subscriptable metaclass.

bpo-35993 [https://bugs.python.org/issue?@action=redirect&bpo=35993]: Fix a crash on fork when using subinterpreters. Contributed by Stéphane Wirtel

bpo-35991 [https://bugs.python.org/issue?@action=redirect&bpo=35991]: Fix a potential double free in Modules/_randommodule.c.

bpo-35961 [https://bugs.python.org/issue?@action=redirect&bpo=35961]: Fix a crash in slice_richcompare(): use strong references rather than stolen references for the two temporary internal tuples.

bpo-35911 [https://bugs.python.org/issue?@action=redirect&bpo=35911]: Enable the creation of cell objects by adding a cell.__new__ method, and expose the type cell in Lib/types.py under the name CellType. Patch by Pierre Glaser.

bpo-12822 [https://bugs.python.org/issue?@action=redirect&bpo=12822]: Use monotonic clock for pthread_cond_timedwait when pthread_condattr_setclock and CLOCK_MONOTONIC are available.

bpo-15248 [https://bugs.python.org/issue?@action=redirect&bpo=15248]: The compiler emits now syntax warnings in the case when a comma is likely missed before tuple or list.

bpo-35886 [https://bugs.python.org/issue?@action=redirect&bpo=35886]: The implementation of PyInterpreterState has been moved into the internal header files (guarded by Py_BUILD_CORE).

bpo-31506 [https://bugs.python.org/issue?@action=redirect&bpo=31506]: Clarify the errors reported when object.__new__ and object.__init__ receive more than one argument. Contributed by Sanyam Khurana.

bpo-35724 [https://bugs.python.org/issue?@action=redirect&bpo=35724]: Signal-handling is now guaranteed to happen relative to the main interpreter.

bpo-33608 [https://bugs.python.org/issue?@action=redirect&bpo=33608]: We added a new internal _Py_AddPendingCall() that operates relative to the provided interpreter. This allows us to use the existing implementation to ask another interpreter to do work that cannot be done in the current interpreter, like decref an object the other interpreter owns. The existing Py_AddPendingCall() only operates relative to the main interpreter.

bpo-33989 [https://bugs.python.org/issue?@action=redirect&bpo=33989]: Fix a possible crash in list.sort() when sorting objects with ob_type->tp_richcompare == NULL. Patch by Zackery Spytz.

Library

bpo-35512 [https://bugs.python.org/issue?@action=redirect&bpo=35512]: unittest.mock.patch.dict() used as a decorator with string target resolves the target during function call instead of during decorator construction. Patch by Karthikeyan Singaravelan.

bpo-36018 [https://bugs.python.org/issue?@action=redirect&bpo=36018]: Add statistics.NormalDist, a tool for creating and manipulating normal distributions of random variable. Features a composite class that treats the mean and standard deviation of measurement data as single entity.

bpo-35904 [https://bugs.python.org/issue?@action=redirect&bpo=35904]: Added statistics.fmean() as a faster, floating point variant of the existing mean() function.

bpo-35918 [https://bugs.python.org/issue?@action=redirect&bpo=35918]: Removed broken has_key method from multiprocessing.managers.SyncManager.dict. Contributed by Rémi Lapeyre.

bpo-18283 [https://bugs.python.org/issue?@action=redirect&bpo=18283]: Add support for bytes to shutil.which().

bpo-35960 [https://bugs.python.org/issue?@action=redirect&bpo=35960]: Fix dataclasses.field() throwing away empty mapping objects passed as metadata.

bpo-35500 [https://bugs.python.org/issue?@action=redirect&bpo=35500]: Write expected and actual call parameters on separate lines in unittest.mock.Mock.assert_called_with() assertion errors. Contributed by Susan Su.

bpo-35931 [https://bugs.python.org/issue?@action=redirect&bpo=35931]: The pdb debug command now gracefully handles syntax errors.

bpo-24209 [https://bugs.python.org/issue?@action=redirect&bpo=24209]: In http.server script, rely on getaddrinfo to bind to preferred address based on the bind parameter. Now default bind or binding to a name may bind to IPv6 or dual-stack, depending on the environment.

bpo-35321 [https://bugs.python.org/issue?@action=redirect&bpo=35321]: Set __spec__.origin of _frozen_importlib to frozen so that it matches the behavior of _frozen_importlib_external. Patch by Nina Zakharenko.

bpo-35378 [https://bugs.python.org/issue?@action=redirect&bpo=35378]: Fix a reference issue inside multiprocessing.Pool that caused the pool to remain alive if it was deleted without being closed or terminated explicitly. A new strong reference is added to the pool iterators to link the lifetime of the pool to the lifetime of its iterators so the pool does not get destroyed if a pool iterator is still alive.

bpo-34294 [https://bugs.python.org/issue?@action=redirect&bpo=34294]: re module, fix wrong capturing groups in rare cases. re.search(), re.findall(), re.sub() and other functions that scan through string looking for a match, should reset capturing groups between two match attempts. Patch by Ma Lin.

bpo-35615 [https://bugs.python.org/issue?@action=redirect&bpo=35615]: weakref: Fix a RuntimeError when copying a WeakKeyDictionary or a WeakValueDictionary, due to some keys or values disappearing while iterating.

bpo-35606 [https://bugs.python.org/issue?@action=redirect&bpo=35606]: Implement math.prod() as analogous function to sum() that returns the product of a “start” value (default: 1) times an iterable of numbers. Patch by Pablo Galindo.

bpo-32417 [https://bugs.python.org/issue?@action=redirect&bpo=32417]: Performing arithmetic between datetime.datetime subclasses and datetime.timedelta now returns an object of the same type as the datetime.datetime subclass. As a result, datetime.datetime.astimezone() and alternate constructors like datetime.datetime.now() and datetime.fromtimestamp() called with a tz argument now also retain their subclass.

bpo-35153 [https://bugs.python.org/issue?@action=redirect&bpo=35153]: Add headers optional keyword-only parameter to xmlrpc.client.ServerProxy, xmlrpc.client.Transport and xmlrpc.client.SafeTransport. Patch by Cédric Krier.

bpo-34572 [https://bugs.python.org/issue?@action=redirect&bpo=34572]: Fix C implementation of pickle.loads to use importlib’s locking mechanisms, and thereby avoid using partially-loaded modules. Patch by Tim Burgess.

Documentation

bpo-36083 [https://bugs.python.org/issue?@action=redirect&bpo=36083]: Fix formatting of –check-hash-based-pycs options in the manpage Synopsis.

bpo-36007 [https://bugs.python.org/issue?@action=redirect&bpo=36007]: Bump minimum sphinx version to 1.8. Patch by Anthony Sottile.

bpo-22062 [https://bugs.python.org/issue?@action=redirect&bpo=22062]: Update documentation and docstrings for pathlib. Original patch by Mike Short.

Tests

bpo-27313 [https://bugs.python.org/issue?@action=redirect&bpo=27313]: Avoid test_ttk_guionly ComboboxTest failure with macOS Cocoa Tk.

bpo-36019 [https://bugs.python.org/issue?@action=redirect&bpo=36019]: Add test.support.TEST_HTTP_URL and replace references of http://www.example.com by this new constant. Contributed by Stéphane Wirtel.

bpo-36037 [https://bugs.python.org/issue?@action=redirect&bpo=36037]: Fix test_ssl for strict OpenSSL configuration like RHEL8 strict crypto policy. Use older TLS version for minimum TLS version of the server SSL context if needed, to test TLS version older than default minimum TLS version.

bpo-35798 [https://bugs.python.org/issue?@action=redirect&bpo=35798]: Added test.support.check_syntax_warning().

bpo-35505 [https://bugs.python.org/issue?@action=redirect&bpo=35505]: Make test_imap4_host_default_value independent on whether the local IMAP server is running.

bpo-35917 [https://bugs.python.org/issue?@action=redirect&bpo=35917]: multiprocessing: provide unit tests for SyncManager and SharedMemoryManager classes + all the shareable types which are supposed to be supported by them. (patch by Giampaolo Rodola)

bpo-35704 [https://bugs.python.org/issue?@action=redirect&bpo=35704]: Skip test_shutil.test_unpack_archive_xztar to prevent a MemoryError on 32-bit AIX when MAXDATA setting is less than 0x20000000.

Patch by Michael Felt (aixtools)

bpo-34720 [https://bugs.python.org/issue?@action=redirect&bpo=34720]: Assert m_state != NULL to mimic GC traversal functions that do not correctly handle module creation when the module state has not been created.

Windows

bpo-35976 [https://bugs.python.org/issue?@action=redirect&bpo=35976]: Added ARM build support to Windows build files in PCBuild.

bpo-35692 [https://bugs.python.org/issue?@action=redirect&bpo=35692]: pathlib no longer raises when checking file and directory existence on drives that are not ready

bpo-35872 [https://bugs.python.org/issue?@action=redirect&bpo=35872]: Uses the base Python executable when invoking venv in a virtual environment

bpo-35873 [https://bugs.python.org/issue?@action=redirect&bpo=35873]: Prevents venv paths being inherited by child processes

bpo-35299 [https://bugs.python.org/issue?@action=redirect&bpo=35299]: Fix sysconfig detection of the source directory and distutils handling of pyconfig.h during PGO profiling

IDLE

bpo-24310 [https://bugs.python.org/issue?@action=redirect&bpo=24310]: IDLE – Document settings dialog font tab sample.

bpo-35833 [https://bugs.python.org/issue?@action=redirect&bpo=35833]: Revise IDLE doc for control codes sent to Shell. Add a code example block.

bpo-35689 [https://bugs.python.org/issue?@action=redirect&bpo=35689]: Add docstrings and unittests for colorizer.py.

Python 3.8.0 alpha 1

Release date: 2019-02-03

Security

bpo-35746 [https://bugs.python.org/issue?@action=redirect&bpo=35746]: [CVE-2019-5010] Fix a NULL pointer deref in ssl module. The cert parser did not handle CRL distribution points with empty DP or URI correctly. A malicious or buggy certificate can result into segfault. Vulnerability (TALOS-2018-0758) reported by Colin Read and Nicolas Edet of Cisco.

bpo-34812 [https://bugs.python.org/issue?@action=redirect&bpo=34812]: The -I command line option (run Python in isolated mode) is now also copied by the multiprocessing and distutils modules when spawning child processes. Previously, only -E and -s options (enabled by -I) were copied.

bpo-34791 [https://bugs.python.org/issue?@action=redirect&bpo=34791]: The xml.sax and xml.dom.domreg no longer use environment variables to override parser implementations when sys.flags.ignore_environment is set by -E or -I arguments.

bpo-17239 [https://bugs.python.org/issue?@action=redirect&bpo=17239]: The xml.sax and xml.dom.minidom parsers no longer processes external entities by default. External DTD and ENTITY declarations no longer load files or create network connections.

bpo-34623 [https://bugs.python.org/issue?@action=redirect&bpo=34623]: CVE-2018-14647: The C accelerated _elementtree module now initializes hash randomization salt from _Py_HashSecret instead of libexpat’s default CSPRNG.

bpo-34405 [https://bugs.python.org/issue?@action=redirect&bpo=34405]: Updated to OpenSSL 1.1.0i for Windows builds.

bpo-33871 [https://bugs.python.org/issue?@action=redirect&bpo=33871]: Fixed sending the part of the file in os.sendfile() on macOS. Using the trailers argument could cause sending more bytes from the input file than was specified.

bpo-32533 [https://bugs.python.org/issue?@action=redirect&bpo=32533]: Fixed thread-safety of error handling in _ssl.

bpo-33136 [https://bugs.python.org/issue?@action=redirect&bpo=33136]: Harden ssl module against LibreSSL CVE-2018-8970. X509_VERIFY_PARAM_set1_host() is called with an explicit namelen. A new test ensures that NULL bytes are not allowed.

bpo-33001 [https://bugs.python.org/issue?@action=redirect&bpo=33001]: Minimal fix to prevent buffer overrun in os.symlink on Windows

bpo-32981 [https://bugs.python.org/issue?@action=redirect&bpo=32981]: Regexes in difflib and poplib were vulnerable to catastrophic backtracking. These regexes formed potential DOS vectors (REDOS). They have been refactored. This resolves CVE-2018-1060 and CVE-2018-1061. Patch by Jamie Davis.

bpo-28414 [https://bugs.python.org/issue?@action=redirect&bpo=28414]: The ssl module now allows users to perform their own IDN en/decoding when using SNI.

Core and Builtins

bpo-35877 [https://bugs.python.org/issue?@action=redirect&bpo=35877]: Make parenthesis optional for named expressions in while statement. Patch by Karthikeyan Singaravelan.

bpo-35814 [https://bugs.python.org/issue?@action=redirect&bpo=35814]: Allow same right hand side expressions in annotated assignments as in normal ones. In particular, x: Tuple[int, int] = 1, 2 (without parentheses on the right) is now allowed.

bpo-35766 [https://bugs.python.org/issue?@action=redirect&bpo=35766]: Add the option to parse PEP 484 type comments in the ast module. (Off by default.) This is merging the key functionality of the third party fork thereof, [typed_ast](https://github.com/python/typed_ast).

bpo-35713 [https://bugs.python.org/issue?@action=redirect&bpo=35713]: Reorganize Python initialization to get working exceptions and sys.stderr earlier.

bpo-33416 [https://bugs.python.org/issue?@action=redirect&bpo=33416]: Add end line and end column position information to the Python AST nodes. This is a C-level backwards incompatible change.

bpo-35720 [https://bugs.python.org/issue?@action=redirect&bpo=35720]: Fixed a minor memory leak in pymain_parse_cmdline_impl function in Modules/main.c

bpo-35634 [https://bugs.python.org/issue?@action=redirect&bpo=35634]: func(**kwargs) will now raise an error when kwargs is a mapping containing multiple entries with the same key. An error was already raised when other keyword arguments are passed before **kwargs since Python 3.6.

bpo-35623 [https://bugs.python.org/issue?@action=redirect&bpo=35623]: Fix a crash when sorting very long lists. Patch by Stephan Hohe.

bpo-35214 [https://bugs.python.org/issue?@action=redirect&bpo=35214]: clang Memory Sanitizer build instrumentation was added to work around false positives from posix, socket, time, test_io, and test_faulthandler.

bpo-35560 [https://bugs.python.org/issue?@action=redirect&bpo=35560]: Fix an assertion error in format() in debug build for floating point formatting with «n» format, zero padding and small width. Release build is not impacted. Patch by Karthikeyan Singaravelan.

bpo-35552 [https://bugs.python.org/issue?@action=redirect&bpo=35552]: Format characters %s and %V in PyUnicode_FromFormat() and %s in PyBytes_FromFormat() no longer read memory past the limit if precision is specified.

bpo-35504 [https://bugs.python.org/issue?@action=redirect&bpo=35504]: Fix segfaults and SystemErrors when deleting certain attributes. Patch by Zackery Spytz.

bpo-35504 [https://bugs.python.org/issue?@action=redirect&bpo=35504]: Fixed a SystemError when delete the characters_written attribute of an OSError.

bpo-35494 [https://bugs.python.org/issue?@action=redirect&bpo=35494]: Improved syntax error messages for unbalanced parentheses in f-string.

bpo-35444 [https://bugs.python.org/issue?@action=redirect&bpo=35444]: Fixed error handling in pickling methods when fail to look up builtin «getattr». Sped up pickling iterators.

bpo-35436 [https://bugs.python.org/issue?@action=redirect&bpo=35436]: Fix various issues with memory allocation error handling. Patch by Zackery Spytz.

bpo-35423 [https://bugs.python.org/issue?@action=redirect&bpo=35423]: Separate the signal handling trigger in the eval loop from the «pending calls» machinery. There is no semantic change and the difference in performance is insignificant.

bpo-35357 [https://bugs.python.org/issue?@action=redirect&bpo=35357]: Internal attributes” names of unittest.mock._Call and unittest.mock.MagicProxy (name, parent & from_kall) are now prefixed with _mock_ in order to prevent clashes with widely used object attributes. Fixed minor typo in test function name.

bpo-35372 [https://bugs.python.org/issue?@action=redirect&bpo=35372]: Fixed the code page decoder for input longer than 2 GiB containing undecodable bytes.

bpo-35336 [https://bugs.python.org/issue?@action=redirect&bpo=35336]: Fix PYTHONCOERCECLOCALE=1 environment variable: only coerce the C locale if the LC_CTYPE locale is «C».

bpo-31241 [https://bugs.python.org/issue?@action=redirect&bpo=31241]: The lineno and col_offset attributes of AST nodes for list comprehensions, generator expressions and tuples are now point to the opening parenthesis or square brace. For tuples without parenthesis they point to the position of the first item.

bpo-33954 [https://bugs.python.org/issue?@action=redirect&bpo=33954]: For str.format(), float.__format__() and complex.__format__() methods for non-ASCII decimal point when using the «n» formatter.

bpo-35269 [https://bugs.python.org/issue?@action=redirect&bpo=35269]: Fix a possible segfault involving a newly-created coroutine. Patch by Zackery Spytz.

bpo-35224 [https://bugs.python.org/issue?@action=redirect&bpo=35224]: Implement PEP 572 [https://www.python.org/dev/peps/pep-0572] (assignment expressions). Patch by Emily Morehouse.

bpo-32492 [https://bugs.python.org/issue?@action=redirect&bpo=32492]: Speed up namedtuple attribute access by 1.6x using a C fast-path for the name descriptors. Patch by Pablo Galindo.

bpo-35214 [https://bugs.python.org/issue?@action=redirect&bpo=35214]: Fixed an out of bounds memory access when parsing a truncated unicode escape sequence at the end of a string such as '\N'. It would read one byte beyond the end of the memory allocation.

bpo-35214 [https://bugs.python.org/issue?@action=redirect&bpo=35214]: The interpreter and extension modules have had annotations added so that they work properly under clang’s Memory Sanitizer. A new configure flag –with-memory-sanitizer has been added to make test builds of this nature easier to perform.

bpo-35193 [https://bugs.python.org/issue?@action=redirect&bpo=35193]: Fix an off by one error in the bytecode peephole optimizer where it could read bytes beyond the end of bounds of an array when removing unreachable code. This bug was present in every release of Python 3.6 and 3.7 until now.

bpo-35169 [https://bugs.python.org/issue?@action=redirect&bpo=35169]: Improved error messages for forbidden assignments.

bpo-34022 [https://bugs.python.org/issue?@action=redirect&bpo=34022]: Fix handling of hash-based bytecode files in zipimport. Patch by Elvis Pranskevichus.

bpo-28401 [https://bugs.python.org/issue?@action=redirect&bpo=28401]: Debug builds will no longer to attempt to import extension modules built for the ABI as they were never compatible to begin with. Patch by Stefano Rivera.

bpo-29341 [https://bugs.python.org/issue?@action=redirect&bpo=29341]: Clarify in the docstrings of os methods that path-like objects are also accepted as input parameters.

bpo-35050 [https://bugs.python.org/issue?@action=redirect&bpo=35050]: socket: Fix off-by-one bug in length check for AF_ALG name and type.

bpo-29743 [https://bugs.python.org/issue?@action=redirect&bpo=29743]: Raise ValueError instead of OverflowError in case of a negative _length_ in a ctypes.Array subclass. Also raise TypeError instead of AttributeError for non-integer _length_. Original patch by Oren Milman.

bpo-16806 [https://bugs.python.org/issue?@action=redirect&bpo=16806]: Fix lineno and col_offset for multi-line string tokens.

bpo-35029 [https://bugs.python.org/issue?@action=redirect&bpo=35029]: SyntaxWarning raised as an exception at code generation time will be now replaced with a SyntaxError for better error reporting.

bpo-34983 [https://bugs.python.org/issue?@action=redirect&bpo=34983]: Expose symtable.Symbol.is_nonlocal() in the symtable module. Patch by Pablo Galindo.

bpo-34974 [https://bugs.python.org/issue?@action=redirect&bpo=34974]: bytes and bytearray constructors no longer convert unexpected exceptions (e.g. MemoryError and KeyboardInterrupt) to TypeError.

bpo-34939 [https://bugs.python.org/issue?@action=redirect&bpo=34939]: Allow annotated names in module namespace that are declared global before the annotation happens. Patch by Pablo Galindo.

bpo-34973 [https://bugs.python.org/issue?@action=redirect&bpo=34973]: Fixed crash in bytes() when the list argument is mutated while it is iterated.

bpo-34876 [https://bugs.python.org/issue?@action=redirect&bpo=34876]: The lineno and col_offset attributes of the AST for decorated function and class refer now to the position of the corresponding def, async def and class instead of the position of the first decorator. This leads to more correct line reporting in tracing. This is the only case when the position of child AST nodes can precede the position of the parent AST node.

bpo-34879 [https://bugs.python.org/issue?@action=redirect&bpo=34879]: Fix a possible null pointer dereference in bytesobject.c. Patch by Zackery Spytz.

bpo-34784 [https://bugs.python.org/issue?@action=redirect&bpo=34784]: Fix the implementation of PyStructSequence_NewType in order to create heap allocated StructSequences.

bpo-32912 [https://bugs.python.org/issue?@action=redirect&bpo=32912]: A SyntaxWarning is now emitted instead of a DeprecationWarning for invalid escape sequences in string and bytes literals.

bpo-34854 [https://bugs.python.org/issue?@action=redirect&bpo=34854]: Fixed a crash in compiling string annotations containing a lambda with a keyword-only argument that doesn’t have a default value.

bpo-34850 [https://bugs.python.org/issue?@action=redirect&bpo=34850]: The compiler now produces a SyntaxWarning when identity checks (is and is not) are used with certain types of literals (e.g. strings, ints). These can often work by accident in CPython, but are not guaranteed by the language spec. The warning advises users to use equality tests (== and !=) instead.

bpo-34824 [https://bugs.python.org/issue?@action=redirect&bpo=34824]: Fix a possible null pointer dereference in Modules/_ssl.c. Patch by Zackery Spytz.

bpo-30156 [https://bugs.python.org/issue?@action=redirect&bpo=30156]: The C function property_descr_get() uses a «cached» tuple to optimize function calls. But this tuple can be discovered in debug mode with sys.getobjects(). Remove the optimization, it’s not really worth it and it causes 3 different crashes last years.

bpo-34762 [https://bugs.python.org/issue?@action=redirect&bpo=34762]: Fix contextvars C API to use PyObject* pointer types.

bpo-34751 [https://bugs.python.org/issue?@action=redirect&bpo=34751]: The hash function for tuples is now based on xxHash which gives better collision results on (formerly) pathological cases. Additionally, on 64-bit systems it improves tuple hashes in general. Patch by Jeroen Demeyer with substantial contributions by Tim Peters.

bpo-34735 [https://bugs.python.org/issue?@action=redirect&bpo=34735]: Fix a memory leak in Modules/timemodule.c. Patch by Zackery Spytz.

bpo-34683 [https://bugs.python.org/issue?@action=redirect&bpo=34683]: Fixed a bug where some SyntaxError error pointed to locations that were off-by-one.

bpo-34651 [https://bugs.python.org/issue?@action=redirect&bpo=34651]: Only allow the main interpreter to fork. The avoids the possibility of affecting the main interpreter, which is critical to operation of the runtime.

bpo-34653 [https://bugs.python.org/issue?@action=redirect&bpo=34653]: Remove unused function PyParser_SimpleParseStringFilename.

bpo-32236 [https://bugs.python.org/issue?@action=redirect&bpo=32236]: Warn that line buffering is not supported if open() is called with binary mode and buffering=1.

bpo-34641 [https://bugs.python.org/issue?@action=redirect&bpo=34641]: Further restrict the syntax of the left-hand side of keyword arguments in function calls. In particular, f((keyword)=arg) is now disallowed.

bpo-34637 [https://bugs.python.org/issue?@action=redirect&bpo=34637]: Make the start argument to sum() visible as a keyword argument.

bpo-1621 [https://bugs.python.org/issue?@action=redirect&bpo=1621]: Do not assume signed integer overflow behavior (C undefined behavior) when performing set hash table resizing.

bpo-34588 [https://bugs.python.org/issue?@action=redirect&bpo=34588]: Fix an off-by-one in the recursive call pruning feature of traceback formatting.

bpo-34485 [https://bugs.python.org/issue?@action=redirect&bpo=34485]: On Windows, the LC_CTYPE is now set to the user preferred locale at startup. Previously, the LC_CTYPE locale was «C» at startup, but changed when calling setlocale(LC_CTYPE, «») or setlocale(LC_ALL, «»).

bpo-34485 [https://bugs.python.org/issue?@action=redirect&bpo=34485]: Standard streams like sys.stdout now use the «surrogateescape» error handler, instead of «strict», on the POSIX locale (when the C locale is not coerced and the UTF-8 Mode is disabled).

bpo-34485 [https://bugs.python.org/issue?@action=redirect&bpo=34485]: Fix the error handler of standard streams like sys.stdout: PYTHONIOENCODING=»:» is now ignored instead of setting the error handler to «strict».

bpo-34485 [https://bugs.python.org/issue?@action=redirect&bpo=34485]: Python now gets the locale encoding with C code to initialize the encoding of standard streams like sys.stdout. Moreover, the encoding is now initialized to the Python codec name to get a normalized encoding name and to ensure that the codec is loaded. The change avoids importing _bootlocale and _locale modules at startup by default.

bpo-34527 [https://bugs.python.org/issue?@action=redirect&bpo=34527]: On FreeBSD, Py_DecodeLocale() and Py_EncodeLocale() now also forces the ASCII encoding if the LC_CTYPE locale is «POSIX», not only if the LC_CTYPE locale is «C».

bpo-34527 [https://bugs.python.org/issue?@action=redirect&bpo=34527]: The UTF-8 Mode is now also enabled by the «POSIX» locale, not only by the «C» locale.

bpo-34403 [https://bugs.python.org/issue?@action=redirect&bpo=34403]: On HP-UX with C or POSIX locale, sys.getfilesystemencoding() now returns «ascii» instead of «roman8» (when the UTF-8 Mode is disabled and the C locale is not coerced).

bpo-34523 [https://bugs.python.org/issue?@action=redirect&bpo=34523]: The Python filesystem encoding is now read earlier during the Python initialization.

bpo-12458 [https://bugs.python.org/issue?@action=redirect&bpo=12458]: Tracebacks show now correct line number for subexpressions in multiline expressions. Tracebacks show now the line number of the first line for multiline expressions instead of the line number of the last subexpression.

bpo-34408 [https://bugs.python.org/issue?@action=redirect&bpo=34408]: Prevent a null pointer dereference and resource leakage in PyInterpreterState_New().

bpo-34400 [https://bugs.python.org/issue?@action=redirect&bpo=34400]: Fix undefined behavior in parsetok.c. Patch by Zackery Spytz.

bpo-33073 [https://bugs.python.org/issue?@action=redirect&bpo=33073]: Added as_integer_ratio to ints to make them more interoperable with floats.

bpo-34377 [https://bugs.python.org/issue?@action=redirect&bpo=34377]: Update valgrind suppression list to use _PyObject_Free/_PyObject_Realloc instead of PyObject_Free/PyObject_Realloc.

bpo-34353 [https://bugs.python.org/issue?@action=redirect&bpo=34353]: Added the «socket» option in the stat.filemode() Python implementation to match the C implementation.

bpo-34320 [https://bugs.python.org/issue?@action=redirect&bpo=34320]: Fix dict(od) didn’t copy iteration order of OrderedDict.

bpo-34113 [https://bugs.python.org/issue?@action=redirect&bpo=34113]: Fixed crash on debug builds when opcode stack was adjusted with negative numbers. Patch by Constantin Petrisor.

bpo-34100 [https://bugs.python.org/issue?@action=redirect&bpo=34100]: Compiler now merges constants in tuples and frozensets recursively. Code attributes like co_names are merged too.

bpo-34151 [https://bugs.python.org/issue?@action=redirect&bpo=34151]: Performance of list concatenation, repetition and slicing operations is slightly improved. Patch by Sergey Fedoseev.

bpo-34170 [https://bugs.python.org/issue?@action=redirect&bpo=34170]: -X dev: it is now possible to override the memory allocator using PYTHONMALLOC even if the developer mode is enabled.

bpo-33237 [https://bugs.python.org/issue?@action=redirect&bpo=33237]: Improved AttributeError message for partially initialized module.

bpo-34149 [https://bugs.python.org/issue?@action=redirect&bpo=34149]: Fix min and max functions to get default behavior when key is None.

bpo-34125 [https://bugs.python.org/issue?@action=redirect&bpo=34125]: Profiling of unbound built-in methods now works when **kwargs is given.

bpo-34141 [https://bugs.python.org/issue?@action=redirect&bpo=34141]: Optimized pickling atomic types (None, bool, int, float, bytes, str).

bpo-34126 [https://bugs.python.org/issue?@action=redirect&bpo=34126]: Fix crashes when profiling certain invalid calls of unbound methods. Patch by Jeroen Demeyer.

bpo-24618 [https://bugs.python.org/issue?@action=redirect&bpo=24618]: Fixed reading invalid memory when create the code object with too small varnames tuple or too large argument counts.

bpo-34068 [https://bugs.python.org/issue?@action=redirect&bpo=34068]: In io.IOBase.close(), ensure that the closed attribute is not set with a live exception. Patch by Zackery Spytz and Serhiy Storchaka.

bpo-34087 [https://bugs.python.org/issue?@action=redirect&bpo=34087]: Fix buffer overflow while converting unicode to numeric values.

bpo-34080 [https://bugs.python.org/issue?@action=redirect&bpo=34080]: Fixed a memory leak in the compiler when it raised some uncommon errors during tokenizing.

bpo-34066 [https://bugs.python.org/issue?@action=redirect&bpo=34066]: Disabled interruption by Ctrl-C between calling open() and entering a with block in with open().

bpo-34042 [https://bugs.python.org/issue?@action=redirect&bpo=34042]: Fix dict.copy() to maintain correct total refcount (as reported by sys.gettotalrefcount()).

bpo-33418 [https://bugs.python.org/issue?@action=redirect&bpo=33418]: Fix potential memory leak in function object when it creates reference cycle.

bpo-33985 [https://bugs.python.org/issue?@action=redirect&bpo=33985]: Implement contextvars.ContextVar.name attribute.

bpo-33956 [https://bugs.python.org/issue?@action=redirect&bpo=33956]: Update vendored Expat library copy to version 2.2.5.

bpo-24596 [https://bugs.python.org/issue?@action=redirect&bpo=24596]: Decref the module object in PyRun_SimpleFileExFlags() before calling PyErr_Print(). Patch by Zackery Spytz.

bpo-33451 [https://bugs.python.org/issue?@action=redirect&bpo=33451]: Close directly executed pyc files before calling PyEval_EvalCode().

bpo-1617161 [https://bugs.python.org/issue?@action=redirect&bpo=1617161]: The hash of BuiltinMethodType instances (methods of built-in classes) now depends on the hash of the identity of __self__ instead of its value. The hash and equality of ModuleType and MethodWrapperType instances (methods of user-defined classes and some methods of built-in classes like str.__add__) now depend on the hash and equality of the identity of __self__ instead of its value. MethodWrapperType instances no longer support ordering.

bpo-33824 [https://bugs.python.org/issue?@action=redirect&bpo=33824]: Fix «LC_ALL=C python3.7 -V»: reset properly the command line parser when the encoding changes after reading the Python configuration.

bpo-33803 [https://bugs.python.org/issue?@action=redirect&bpo=33803]: Fix a crash in hamt.c caused by enabling GC tracking for an object that hadn’t all of its fields set to NULL.

bpo-33738 [https://bugs.python.org/issue?@action=redirect&bpo=33738]: Seven macro incompatibilities with the Limited API were fixed, and the macros PyIter_Check(), PyIndex_Check() and PyExceptionClass_Name() were added as functions. A script for automatic macro checks was added.

bpo-33786 [https://bugs.python.org/issue?@action=redirect&bpo=33786]: Fix asynchronous generators to handle GeneratorExit in athrow() correctly

bpo-30167 [https://bugs.python.org/issue?@action=redirect&bpo=30167]: PyRun_SimpleFileExFlags removes __cached__ from module in addition to __file__.

bpo-33706 [https://bugs.python.org/issue?@action=redirect&bpo=33706]: Fix a crash in Python initialization when parsing the command line options. Thanks Christoph Gohlke for the bug report and the fix!

bpo-33597 [https://bugs.python.org/issue?@action=redirect&bpo=33597]: Reduce PyGC_Head size from 3 words to 2 words.

bpo-30654 [https://bugs.python.org/issue?@action=redirect&bpo=30654]: Fixed reset of the SIGINT handler to SIG_DFL on interpreter shutdown even when there was a custom handler set previously. Patch by Philipp Kerling.

bpo-33622 [https://bugs.python.org/issue?@action=redirect&bpo=33622]: Fixed a leak when the garbage collector fails to add an object with the __del__ method or referenced by it into the gc.garbage list. PyGC_Collect() can now be called when an exception is set and preserves it.

bpo-33462 [https://bugs.python.org/issue?@action=redirect&bpo=33462]: Make dict and dict views reversible. Patch by Rémi Lapeyre.

bpo-23722 [https://bugs.python.org/issue?@action=redirect&bpo=23722]: A RuntimeError is now raised when the custom metaclass doesn’t provide the __classcell__ entry in the namespace passed to type.__new__. A DeprecationWarning was emitted in Python 3.6–3.7.

bpo-33499 [https://bugs.python.org/issue?@action=redirect&bpo=33499]: Add PYTHONPYCACHEPREFIX environment variable and -X pycache_prefix command-line option to set an alternate root directory for writing module bytecode cache files.

bpo-25711 [https://bugs.python.org/issue?@action=redirect&bpo=25711]: The zipimport module has been rewritten in pure Python.

bpo-33509 [https://bugs.python.org/issue?@action=redirect&bpo=33509]: Fix module_globals parameter of warnings.warn_explicit(): don’t crash if module_globals is not a dict.

bpo-31849 [https://bugs.python.org/issue?@action=redirect&bpo=31849]: Fix signed/unsigned comparison warning in pyhash.c.

bpo-33475 [https://bugs.python.org/issue?@action=redirect&bpo=33475]: Fixed miscellaneous bugs in converting annotations to strings and optimized parentheses in the string representation.

bpo-20104 [https://bugs.python.org/issue?@action=redirect&bpo=20104]: Added support for the setpgroup, resetids, setsigmask, setsigdef and scheduler parameters of posix_spawn. Patch by Pablo Galindo.

bpo-33391 [https://bugs.python.org/issue?@action=redirect&bpo=33391]: Fix a leak in set_symmetric_difference().

bpo-33363 [https://bugs.python.org/issue?@action=redirect&bpo=33363]: Raise a SyntaxError for async with and async for statements outside of async functions.

bpo-28055 [https://bugs.python.org/issue?@action=redirect&bpo=28055]: Fix unaligned accesses in siphash24(). Patch by Rolf Eike Beer.

bpo-33128 [https://bugs.python.org/issue?@action=redirect&bpo=33128]: Fix a bug that causes PathFinder to appear twice on sys.meta_path. Patch by Pablo Galindo Salgado.

bpo-33331 [https://bugs.python.org/issue?@action=redirect&bpo=33331]: Modules imported last are now cleared first at interpreter shutdown.

bpo-33312 [https://bugs.python.org/issue?@action=redirect&bpo=33312]: Fixed clang ubsan (undefined behavior sanitizer) warnings in dictobject.c by adjusting how the internal struct _dictkeysobject shared keys structure is declared.

bpo-33305 [https://bugs.python.org/issue?@action=redirect&bpo=33305]: Improved syntax error messages for invalid numerical literals.

bpo-33306 [https://bugs.python.org/issue?@action=redirect&bpo=33306]: Improved syntax error messages for unbalanced parentheses.

bpo-33234 [https://bugs.python.org/issue?@action=redirect&bpo=33234]: The list constructor will pre-size and not over-allocate when the input length is known.

bpo-33270 [https://bugs.python.org/issue?@action=redirect&bpo=33270]: Intern the names for all anonymous code objects. Patch by Zackery Spytz.

bpo-30455 [https://bugs.python.org/issue?@action=redirect&bpo=30455]: The C and Python code and the documentation related to tokens are now generated from a single source file Grammar/Tokens.

bpo-33176 [https://bugs.python.org/issue?@action=redirect&bpo=33176]: Add a toreadonly() method to memoryviews.

bpo-33231 [https://bugs.python.org/issue?@action=redirect&bpo=33231]: Fix potential memory leak in normalizestring().

bpo-33205 [https://bugs.python.org/issue?@action=redirect&bpo=33205]: Change dict growth function from round_up_to_power_2(used*2+hashtable_size/2) to round_up_to_power_2(used*3). Previously, dict is shrinked only when used == 0. Now dict has more chance to be shrinked.

bpo-29922 [https://bugs.python.org/issue?@action=redirect&bpo=29922]: Improved error messages in “async with” when __aenter__() or __aexit__() return non-awaitable object.

bpo-33199 [https://bugs.python.org/issue?@action=redirect&bpo=33199]: Fix ma_version_tag in dict implementation is uninitialized when copying from key-sharing dict.

bpo-33053 [https://bugs.python.org/issue?@action=redirect&bpo=33053]: When using the -m switch, sys.path[0] is now explicitly expanded as the starting working directory, rather than being left as the empty path (which allows imports from the current working directory at the time of the import)

bpo-33138 [https://bugs.python.org/issue?@action=redirect&bpo=33138]: Changed standard error message for non-pickleable and non-copyable types. It now says «cannot pickle» instead of «can’t pickle» or «cannot serialize».

bpo-33018 [https://bugs.python.org/issue?@action=redirect&bpo=33018]: Improve consistency of errors raised by issubclass() when called with a non-class and an abstract base class as the first and second arguments, respectively. Patch by Josh Bronson.

bpo-33083 [https://bugs.python.org/issue?@action=redirect&bpo=33083]: math.factorial no longer accepts arguments that are not int-like. Patch by Pablo Galindo.

bpo-33041 [https://bugs.python.org/issue?@action=redirect&bpo=33041]: Added new opcode END_ASYNC_FOR and fixes the following issues:

Setting global StopAsyncIteration no longer breaks async for loops.

Jumping into an async for loop is now disabled.

Jumping out of an async for loop no longer corrupts the stack.

bpo-25750 [https://bugs.python.org/issue?@action=redirect&bpo=25750]: Fix rare Python crash due to bad refcounting in type_getattro() if a descriptor deletes itself from the class. Patch by Jeroen Demeyer.

bpo-33041 [https://bugs.python.org/issue?@action=redirect&bpo=33041]: Fixed bytecode generation for «async for» with a complex target. A StopAsyncIteration raised on assigning or unpacking will be now propagated instead of stopping the iteration.

bpo-33026 [https://bugs.python.org/issue?@action=redirect&bpo=33026]: Fixed jumping out of «with» block by setting f_lineno.

bpo-33005 [https://bugs.python.org/issue?@action=redirect&bpo=33005]: Fix a crash on fork when using a custom memory allocator (ex: using PYTHONMALLOC env var). _PyGILState_Reinit() and _PyInterpreterState_Enable() now use the default RAW memory allocator to allocate a new interpreters mutex on fork.

bpo-32911 [https://bugs.python.org/issue?@action=redirect&bpo=32911]: Due to unexpected compatibility issues discovered during downstream beta testing, reverted bpo-29463 [https://bugs.python.org/issue?@action=redirect&bpo=29463]. docstring field is removed from Module, ClassDef, FunctionDef, and AsyncFunctionDef ast nodes which was added in 3.7a1. Docstring expression is restored as a first statement in their body. Based on patch by Inada Naoki.

bpo-17288 [https://bugs.python.org/issue?@action=redirect&bpo=17288]: Prevent jumps from “return” and “exception” trace events.

bpo-32946 [https://bugs.python.org/issue?@action=redirect&bpo=32946]: Importing names from already imported module with «from … import …» is now 30% faster if the module is not a package.

bpo-32932 [https://bugs.python.org/issue?@action=redirect&bpo=32932]: Make error message more revealing when there are non-str objects in __all__.

bpo-32925 [https://bugs.python.org/issue?@action=redirect&bpo=32925]: Optimized iterating and containing test for literal lists consisting of non-constants: x in [a, b] and for x in [a, b]. The case of all constant elements already was optimized.

bpo-32889 [https://bugs.python.org/issue?@action=redirect&bpo=32889]: Update Valgrind suppression list to account for the rename of Py_ADDRESS_IN_RANG to address_in_range.

bpo-32836 [https://bugs.python.org/issue?@action=redirect&bpo=32836]: Don’t use temporary variables in cases of list/dict/set comprehensions

bpo-31356 [https://bugs.python.org/issue?@action=redirect&bpo=31356]: Remove the new API added in bpo-31356 [https://bugs.python.org/issue?@action=redirect&bpo=31356] (gc.ensure_disabled() context manager).

bpo-32305 [https://bugs.python.org/issue?@action=redirect&bpo=32305]: For namespace packages, ensure that both __file__ and __spec__.origin are set to None.

bpo-32303 [https://bugs.python.org/issue?@action=redirect&bpo=32303]: Make sure __spec__.loader matches __loader__ for namespace packages.

bpo-32711 [https://bugs.python.org/issue?@action=redirect&bpo=32711]: Fix the warning messages for Python/ast_unparse.c. Patch by Stéphane Wirtel

bpo-32583 [https://bugs.python.org/issue?@action=redirect&bpo=32583]: Fix possible crashing in builtin Unicode decoders caused by write out-of-bound errors when using customized decode error handlers.

bpo-32489 [https://bugs.python.org/issue?@action=redirect&bpo=32489]: A continue statement is now allowed in the finally clause.

bpo-17611 [https://bugs.python.org/issue?@action=redirect&bpo=17611]: Simplified the interpreter loop by moving the logic of unrolling the stack of blocks into the compiler. The compiler emits now explicit instructions for adjusting the stack of values and calling the cleaning up code for break, continue and return.

Removed opcodes BREAK_LOOP, CONTINUE_LOOP, SETUP_LOOP and SETUP_EXCEPT. Added new opcodes ROT_FOUR, BEGIN_FINALLY and CALL_FINALLY and POP_FINALLY. Changed the behavior of END_FINALLY and WITH_CLEANUP_START.

bpo-32285 [https://bugs.python.org/issue?@action=redirect&bpo=32285]: New function unicodedata.is_normalized, which can check whether a string is in a specific normal form.

bpo-10544 [https://bugs.python.org/issue?@action=redirect&bpo=10544]: Yield expressions are now disallowed in comprehensions and generator expressions except the expression for the outermost iterable.

bpo-32117 [https://bugs.python.org/issue?@action=redirect&bpo=32117]: Iterable unpacking is now allowed without parentheses in yield and return statements, e.g. yield 1, 2, 3, *rest. Thanks to David Cuthbert for the change and Jordan Chapman for added tests.

bpo-31902 [https://bugs.python.org/issue?@action=redirect&bpo=31902]: Fix the col_offset attribute for ast nodes ast.AsyncFor, ast.AsyncFunctionDef, and ast.AsyncWith. Previously, col_offset pointed to the keyword after async.

bpo-25862 [https://bugs.python.org/issue?@action=redirect&bpo=25862]: Fix assertion failures in the tell() method of io.TextIOWrapper. Patch by Zackery Spytz.

bpo-21983 [https://bugs.python.org/issue?@action=redirect&bpo=21983]: Fix a crash in ctypes.cast() in case the type argument is a ctypes structured data type. Patch by Eryk Sun and Oren Milman.

bpo-31577 [https://bugs.python.org/issue?@action=redirect&bpo=31577]: Fix a crash in os.utime() in case of a bad ns argument. Patch by Oren Milman.

bpo-29832 [https://bugs.python.org/issue?@action=redirect&bpo=29832]: Remove references to “getsockaddrarg” from various socket error messages. Patch by Oren Milman.

Library

bpo-35845 [https://bugs.python.org/issue?@action=redirect&bpo=35845]: Add “order” parameter to memoryview.tobytes().

bpo-35864 [https://bugs.python.org/issue?@action=redirect&bpo=35864]: The _asdict() method for collections.namedtuple now returns a regular dict instead of an OrderedDict.

bpo-35537 [https://bugs.python.org/issue?@action=redirect&bpo=35537]: An ExitStack is now used internally within subprocess.POpen to clean up pipe file handles. No behavior change in normal operation. But if closing one handle were ever to cause an exception, the others will now be closed instead of leaked. (patch by Giampaolo Rodola)

bpo-35847 [https://bugs.python.org/issue?@action=redirect&bpo=35847]: RISC-V needed the CTYPES_PASS_BY_REF_HACK. Fixes ctypes Structure test_pass_by_value.

bpo-35813 [https://bugs.python.org/issue?@action=redirect&bpo=35813]: Shared memory submodule added to multiprocessing to avoid need for serialization between processes

bpo-35780 [https://bugs.python.org/issue?@action=redirect&bpo=35780]: Fix lru_cache() errors arising in recursive, reentrant, or multi-threaded code. These errors could result in orphan links and in the cache being trapped in a state with fewer than the specified maximum number of links. Fix handling of negative maxsize which should have been treated as zero. Fix errors in toggling the «full» status flag. Fix misordering of links when errors are encountered. Sync-up the C code and pure Python code for the space saving path in functions with a single positional argument. In this common case, the space overhead of an lru cache entry is reduced by almost half. Fix counting of cache misses. In error cases, the miss count was out of sync with the actual number of times the underlying user function was called.

bpo-35537 [https://bugs.python.org/issue?@action=redirect&bpo=35537]: os.posix_spawn() and os.posix_spawnp() now have a setsid parameter.

bpo-23846 [https://bugs.python.org/issue?@action=redirect&bpo=23846]: asyncio.ProactorEventLoop now catches and logs send errors when the self-pipe is full.

bpo-34323 [https://bugs.python.org/issue?@action=redirect&bpo=34323]: asyncio: Enhance IocpProactor.close() log: wait 1 second before the first log, then log every second. Log also the number of seconds since close() was called.

bpo-35674 [https://bugs.python.org/issue?@action=redirect&bpo=35674]: Add a new os.posix_spawnp() function. Patch by Joannah Nanjekye.

bpo-35733 [https://bugs.python.org/issue?@action=redirect&bpo=35733]: ast.Constant(boolean) no longer an instance of ast.Num. Patch by Anthony Sottile.

bpo-35726 [https://bugs.python.org/issue?@action=redirect&bpo=35726]: QueueHandler.prepare() now makes a copy of the record before modifying and enqueueing it, to avoid affecting other handlers in the chain.

bpo-35719 [https://bugs.python.org/issue?@action=redirect&bpo=35719]: Sped up multi-argument math functions atan2(), copysign(), remainder() and hypot() by 1.3–2.5 times.

bpo-35717 [https://bugs.python.org/issue?@action=redirect&bpo=35717]: Fix KeyError exception raised when using enums and compile. Patch contributed by Rémi Lapeyre.

bpo-35699 [https://bugs.python.org/issue?@action=redirect&bpo=35699]: Fixed detection of Visual Studio Build Tools 2017 in distutils

bpo-32710 [https://bugs.python.org/issue?@action=redirect&bpo=32710]: Fix memory leaks in asyncio ProactorEventLoop on overlapped operation failure.

bpo-35702 [https://bugs.python.org/issue?@action=redirect&bpo=35702]: The time.CLOCK_UPTIME_RAW constant is now available for macOS 10.12.

bpo-32710 [https://bugs.python.org/issue?@action=redirect&bpo=32710]: Fix a memory leak in asyncio in the ProactorEventLoop when ReadFile() or WSASend() overlapped operation fail immediately: release the internal buffer.

bpo-35682 [https://bugs.python.org/issue?@action=redirect&bpo=35682]: Fix asyncio.ProactorEventLoop.sendfile(): don’t attempt to set the result of an internal future if it’s already done.

bpo-35283 [https://bugs.python.org/issue?@action=redirect&bpo=35283]: Add a deprecated warning for the threading.Thread.isAlive() method. Patch by Dong-hee Na.

bpo-35664 [https://bugs.python.org/issue?@action=redirect&bpo=35664]: Improve operator.itemgetter() performance by 33% with optimized argument handling and with adding a fast path for the common case of a single non-negative integer index into a tuple (which is the typical use case in the standard library).

bpo-35643 [https://bugs.python.org/issue?@action=redirect&bpo=35643]: Fixed a SyntaxWarning: invalid escape sequence in Modules/_sha3/cleanup.py. Patch by Mickaël Schoentgen.

bpo-35619 [https://bugs.python.org/issue?@action=redirect&bpo=35619]: Improved support of custom data descriptors in help() and pydoc.

bpo-28503 [https://bugs.python.org/issue?@action=redirect&bpo=28503]: The crypt module now internally uses the crypt_r() library function instead of crypt() when available.

bpo-35614 [https://bugs.python.org/issue?@action=redirect&bpo=35614]: Fixed help() on metaclasses. Patch by Sanyam Khurana.

bpo-35568 [https://bugs.python.org/issue?@action=redirect&bpo=35568]: Expose raise(signum) as raise_signal

bpo-35588 [https://bugs.python.org/issue?@action=redirect&bpo=35588]: The floor division and modulo operations and the divmod() function on fractions.Fraction types are 2–4x faster. Patch by Stefan Behnel.

bpo-35585 [https://bugs.python.org/issue?@action=redirect&bpo=35585]: Speed-up building enums by value, e.g. http.HTTPStatus(200).

bpo-30561 [https://bugs.python.org/issue?@action=redirect&bpo=30561]: random.gammavariate(1.0, beta) now computes the same result as random.expovariate(1.0 / beta). This synchronizes the two algorithms and eliminates some idiosyncrasies in the old implementation. It does however produce a difference stream of random variables than it used to.

bpo-35537 [https://bugs.python.org/issue?@action=redirect&bpo=35537]: The subprocess module can now use the os.posix_spawn() function in some cases for better performance.

bpo-35526 [https://bugs.python.org/issue?@action=redirect&bpo=35526]: Delaying the “joke” of barry_as_FLUFL.mandatory to Python version 4.0

bpo-35523 [https://bugs.python.org/issue?@action=redirect&bpo=35523]: Remove ctypes callback workaround: no longer create a callback at startup. Avoid SELinux alert on import ctypes and import uuid.

bpo-31784 [https://bugs.python.org/issue?@action=redirect&bpo=31784]: uuid.uuid1() now calls time.time_ns() rather than int(time.time() * 1e9).

bpo-35513 [https://bugs.python.org/issue?@action=redirect&bpo=35513]: TextTestRunner of unittest.runner now uses time.perf_counter() rather than time.time() to measure the execution time of a test: time.time() can go backwards, whereas time.perf_counter() is monotonic.

bpo-35502 [https://bugs.python.org/issue?@action=redirect&bpo=35502]: Fixed reference leaks in xml.etree.ElementTree.TreeBuilder in case of unfinished building of the tree (in particular when an error was raised during parsing XML).

bpo-35348 [https://bugs.python.org/issue?@action=redirect&bpo=35348]: Make platform.architecture() parsing of file command output more reliable: add the -b option to the file command to omit the filename, force the usage of the C locale, and search also the «shared object» pattern.

bpo-35491 [https://bugs.python.org/issue?@action=redirect&bpo=35491]: multiprocessing: Add Pool.__repr__() and enhance BaseProcess.__repr__() (add pid and parent pid) to ease debugging. Pool state constant values are now strings instead of integers, for example RUN value becomes 'RUN' instead of 0.

bpo-35477 [https://bugs.python.org/issue?@action=redirect&bpo=35477]: multiprocessing.Pool.__enter__() now fails if the pool is not running: with pool: fails if used more than once.

bpo-31446 [https://bugs.python.org/issue?@action=redirect&bpo=31446]: Copy command line that was passed to CreateProcessW since this function can change the content of the input buffer.

bpo-35471 [https://bugs.python.org/issue?@action=redirect&bpo=35471]: Python 2.4 dropped MacOS 9 support. The macpath module was deprecated in Python 3.7. The module is now removed.

bpo-23057 [https://bugs.python.org/issue?@action=redirect&bpo=23057]: Unblock Proactor event loop when keyboard interrupt is received on Windows

bpo-35052 [https://bugs.python.org/issue?@action=redirect&bpo=35052]: Fix xml.dom.minidom cloneNode() on a document with an entity: pass the correct arguments to the user data handler of an entity.

bpo-20239 [https://bugs.python.org/issue?@action=redirect&bpo=20239]: Allow repeated assignment deletion of unittest.mock.Mock attributes. Patch by Pablo Galindo.

bpo-17185 [https://bugs.python.org/issue?@action=redirect&bpo=17185]: Set __signature__ on mock for inspect to get signature. Patch by Karthikeyan Singaravelan.

bpo-35445 [https://bugs.python.org/issue?@action=redirect&bpo=35445]: Memory errors during creating posix.environ no longer ignored.

bpo-35415 [https://bugs.python.org/issue?@action=redirect&bpo=35415]: Validate fileno= argument to socket.socket().

bpo-35424 [https://bugs.python.org/issue?@action=redirect&bpo=35424]: multiprocessing.Pool destructor now emits ResourceWarning if the pool is still running.

bpo-35330 [https://bugs.python.org/issue?@action=redirect&bpo=35330]: When a Mock instance was used to wrap an object, if side_effect is used in one of the mocks of it methods, don’t call the original implementation and return the result of using the side effect the same way that it is done with return_value.

bpo-35346 [https://bugs.python.org/issue?@action=redirect&bpo=35346]: Drop Mac OS 9 and Rhapsody support from the platform module. Rhapsody last release was in 2000. Mac OS 9 last release was in 2001.

bpo-10496 [https://bugs.python.org/issue?@action=redirect&bpo=10496]: check_environ() of distutils.utils now catches KeyError on calling pwd.getpwuid(): don’t create the HOME environment variable in this case.

bpo-10496 [https://bugs.python.org/issue?@action=redirect&bpo=10496]: posixpath.expanduser() now returns the input path unchanged if the HOME environment variable is not set and the current user has no home directory (if the current user identifier doesn’t exist in the password database). This change fix the site module if the current user doesn’t exist in the password database (if the user has no home directory).

bpo-35389 [https://bugs.python.org/issue?@action=redirect&bpo=35389]: platform.libc_ver() now uses os.confstr('CS_GNU_LIBC_VERSION') if available and the executable parameter is not set.

bpo-35394 [https://bugs.python.org/issue?@action=redirect&bpo=35394]: Add empty slots to asyncio abstract protocols.

bpo-35310 [https://bugs.python.org/issue?@action=redirect&bpo=35310]: Fix a bug in select.select() where, in some cases, the file descriptor sequences were returned unmodified after a signal interruption, even though the file descriptors might not be ready yet. select.select() will now always return empty lists if a timeout has occurred. Patch by Oran Avraham.

bpo-35380 [https://bugs.python.org/issue?@action=redirect&bpo=35380]: Enable TCP_NODELAY on Windows for proactor asyncio event loop.

bpo-35341 [https://bugs.python.org/issue?@action=redirect&bpo=35341]: Add generic version of collections.OrderedDict to the typing module. Patch by Ismo Toijala.

bpo-35371 [https://bugs.python.org/issue?@action=redirect&bpo=35371]: Fixed possible crash in os.utime() on Windows when pass incorrect arguments.

bpo-35346 [https://bugs.python.org/issue?@action=redirect&bpo=35346]: platform.uname() now redirects stderr to os.devnull when running external programs like cmd /c ver.

bpo-35066 [https://bugs.python.org/issue?@action=redirect&bpo=35066]: Previously, calling the strftime() method on a datetime object with a trailing “%” in the format string would result in an exception. However, this only occurred when the datetime C module was being used; the python implementation did not match this behavior. Datetime is now PEP-399 compliant, and will not throw an exception on a trailing “%”.

bpo-35345 [https://bugs.python.org/issue?@action=redirect&bpo=35345]: The function platform.popen has been removed, it was deprecated since Python 3.3: use os.popen() instead.

bpo-35344 [https://bugs.python.org/issue?@action=redirect&bpo=35344]: On macOS, platform.platform() now uses platform.mac_ver(), if it returns a non-empty release string, to get the macOS version rather than the darwin version.

bpo-35312 [https://bugs.python.org/issue?@action=redirect&bpo=35312]: Make lib2to3.pgen2.parse.ParseError round-trip pickle-able. Patch by Anthony Sottile.

bpo-35308 [https://bugs.python.org/issue?@action=redirect&bpo=35308]: Fix regression in webbrowser where default browsers may be preferred over browsers in the BROWSER environment variable.

bpo-24746 [https://bugs.python.org/issue?@action=redirect&bpo=24746]: Avoid stripping trailing whitespace in doctest fancy diff. Original patch by R. David Murray & Jairo Trad. Enhanced by Sanyam Khurana.

bpo-28604 [https://bugs.python.org/issue?@action=redirect&bpo=28604]: locale.localeconv() now sets temporarily the LC_CTYPE locale to the LC_MONETARY locale if the two locales are different and monetary strings are non-ASCII. This temporary change affects other threads.

bpo-35277 [https://bugs.python.org/issue?@action=redirect&bpo=35277]: Update ensurepip to install pip 18.1 and setuptools 40.6.2.

bpo-24209 [https://bugs.python.org/issue?@action=redirect&bpo=24209]: Adds IPv6 support when invoking http.server directly.

bpo-35226 [https://bugs.python.org/issue?@action=redirect&bpo=35226]: Recursively check arguments when testing for equality of unittest.mock.call objects and add note that tracking of parameters used to create ancestors of mocks in mock_calls is not possible.

bpo-29564 [https://bugs.python.org/issue?@action=redirect&bpo=29564]: The warnings module now suggests to enable tracemalloc if the source is specified, the tracemalloc module is available, but tracemalloc is not tracing memory allocations.

bpo-35189 [https://bugs.python.org/issue?@action=redirect&bpo=35189]: Modify the following fnctl function to retry if interrupted by a signal (EINTR): flock, lockf, fnctl

bpo-30064 [https://bugs.python.org/issue?@action=redirect&bpo=30064]: Use add_done_callback() in sock_* asyncio API to unsubscribe reader/writer early on calcellation.

bpo-35186 [https://bugs.python.org/issue?@action=redirect&bpo=35186]: Removed the «built with» comment added when setup.py upload is used with either bdist_rpm or bdist_dumb.

bpo-35152 [https://bugs.python.org/issue?@action=redirect&bpo=35152]: Allow sending more than 2 GB at once on a multiprocessing connection on non-Windows systems.

bpo-35062 [https://bugs.python.org/issue?@action=redirect&bpo=35062]: Fix incorrect parsing of _io.IncrementalNewlineDecoder’s translate argument.

bpo-35065 [https://bugs.python.org/issue?@action=redirect&bpo=35065]: Remove StreamReaderProtocol._untrack_reader. The call to _untrack_reader is currently performed too soon, causing the protocol to forget about the reader before connection_lost can run and feed the EOF to the reader.

bpo-34160 [https://bugs.python.org/issue?@action=redirect&bpo=34160]: ElementTree and minidom now preserve the attribute order specified by the user.

bpo-35079 [https://bugs.python.org/issue?@action=redirect&bpo=35079]: Improve difflib.SequenceManager.get_matching_blocks doc by adding “non-overlapping” and changing “!=” to “<”.

bpo-33710 [https://bugs.python.org/issue?@action=redirect&bpo=33710]: Deprecated l*gettext() functions and methods in the gettext module. They return encoded bytes instead of Unicode strings and are artifacts from Python 2 times. Also deprecated functions and methods related to setting the charset for l*gettext() functions and methods.

bpo-35017 [https://bugs.python.org/issue?@action=redirect&bpo=35017]: socketserver.BaseServer.serve_forever() now exits immediately if it’s shutdown() method is called while it is polling for new events.

bpo-35024 [https://bugs.python.org/issue?@action=redirect&bpo=35024]: importlib no longer logs wrote redundantly after (created|could not create) is already logged. Patch by Quentin Agren.

bpo-35047 [https://bugs.python.org/issue?@action=redirect&bpo=35047]: unittest.mock now includes mock calls in exception messages if assert_not_called, assert_called_once, or assert_called_once_with fails. Patch by Petter Strandmark.

bpo-31047 [https://bugs.python.org/issue?@action=redirect&bpo=31047]: Fix ntpath.abspath regression where it didn’t remove a trailing separator on Windows. Patch by Tim Graham.

bpo-35053 [https://bugs.python.org/issue?@action=redirect&bpo=35053]: tracemalloc now tries to update the traceback when an object is reused from a «free list» (optimization for faster object creation, used by the builtin list type for example).

bpo-31553 [https://bugs.python.org/issue?@action=redirect&bpo=31553]: Add the –json-lines option to json.tool. Patch by hongweipeng.

bpo-34794 [https://bugs.python.org/issue?@action=redirect&bpo=34794]: Fixed a leak in Tkinter when pass the Python wrapper around Tcl_Obj back to Tcl/Tk.

bpo-34909 [https://bugs.python.org/issue?@action=redirect&bpo=34909]: Enum: fix grandchildren subclassing when parent mixed with concrete data types.

bpo-35022 [https://bugs.python.org/issue?@action=redirect&bpo=35022]: unittest.mock.MagicMock now supports the __fspath__ method (from os.PathLike).

bpo-35008 [https://bugs.python.org/issue?@action=redirect&bpo=35008]: Fixed references leaks when call the __setstate__() method of xml.etree.ElementTree.Element in the C implementation for already initialized element.

bpo-23420 [https://bugs.python.org/issue?@action=redirect&bpo=23420]: Verify the value for the parameter “-s” of the cProfile CLI. Patch by Robert Kuska

bpo-33947 [https://bugs.python.org/issue?@action=redirect&bpo=33947]: dataclasses now handle recursive reprs without raising RecursionError.

bpo-34890 [https://bugs.python.org/issue?@action=redirect&bpo=34890]: Make inspect.iscoroutinefunction(), inspect.isgeneratorfunction() and inspect.isasyncgenfunction() work with functools.partial(). Patch by Pablo Galindo.

bpo-34521 [https://bugs.python.org/issue?@action=redirect&bpo=34521]: Use socket.CMSG_SPACE() to calculate ancillary data size instead of socket.CMSG_LEN() in multiprocessing.reduction.recvfds() as RFC 3542 [https://tools.ietf.org/html/rfc3542.html] requires the use of the former for portable applications.

bpo-31522 [https://bugs.python.org/issue?@action=redirect&bpo=31522]: The mailbox.mbox.get_string function from_ parameter can now successfully be set to a non-default value.

bpo-34970 [https://bugs.python.org/issue?@action=redirect&bpo=34970]: Protect tasks weak set manipulation in asyncio.all_tasks()

bpo-34969 [https://bugs.python.org/issue?@action=redirect&bpo=34969]: gzip: Add –fast, –best on the gzip CLI, these parameters will be used for the fast compression method (quick) or the best method compress (slower, but smaller file). Also, change the default compression level to 6 (tradeoff).

bpo-16965 [https://bugs.python.org/issue?@action=redirect&bpo=16965]: The 2to3 execfile fixer now opens the file with mode 'rb'. Patch by Zackery Spytz.

bpo-34966 [https://bugs.python.org/issue?@action=redirect&bpo=34966]: pydoc now supports aliases not only to methods defined in the end class, but also to inherited methods. The docstring is not duplicated for aliases.

bpo-34926 [https://bugs.python.org/issue?@action=redirect&bpo=34926]: mimetypes.MimeTypes.guess_type() now accepts path-like object in addition to url strings. Patch by Mayank Asthana.

bpo-23831 [https://bugs.python.org/issue?@action=redirect&bpo=23831]: Add moveto() method to the tkinter.Canvas widget. Patch by Juliette Monsel.

bpo-34941 [https://bugs.python.org/issue?@action=redirect&bpo=34941]: Methods find(), findtext() and findall() of the Element class in the xml.etree.ElementTree module are now able to find children which are instances of Element subclasses.

bpo-32680 [https://bugs.python.org/issue?@action=redirect&bpo=32680]: smtplib.SMTP objects now always have a sock attribute present

bpo-34769 [https://bugs.python.org/issue?@action=redirect&bpo=34769]: Fix for async generators not finalizing when event loop is in debug mode and garbage collector runs in another thread.

bpo-34936 [https://bugs.python.org/issue?@action=redirect&bpo=34936]: Fix TclError in tkinter.Spinbox.selection_element(). Patch by Juliette Monsel.

bpo-34829 [https://bugs.python.org/issue?@action=redirect&bpo=34829]: Add methods selection_from, selection_range, selection_present and selection_to to the tkinter.Spinbox for consistency with the tkinter.Entry widget. Patch by Juliette Monsel.

bpo-34911 [https://bugs.python.org/issue?@action=redirect&bpo=34911]: Added secure_protocols argument to http.cookiejar.DefaultCookiePolicy to allow for tweaking of protocols and also to add support by default for wss, the secure websocket protocol.

bpo-34922 [https://bugs.python.org/issue?@action=redirect&bpo=34922]: Fixed integer overflow in the digest() and hexdigest() methods for the SHAKE algorithm in the hashlib module.

bpo-34925 [https://bugs.python.org/issue?@action=redirect&bpo=34925]: 25% speedup in argument parsing for the functions in the bisect module.

bpo-34900 [https://bugs.python.org/issue?@action=redirect&bpo=34900]: Fixed unittest.TestCase.debug() when used to call test methods with subtests. Patch by Bruno Oliveira.

bpo-34844 [https://bugs.python.org/issue?@action=redirect&bpo=34844]: logging.Formatter enhancement - Ensure styles and fmt matches in logging.Formatter - Added validate method in each format style class: StrFormatStyle, PercentStyle, StringTemplateStyle. - This method is called in the constructor of logging.Formatter class - Also re-raise the KeyError in the format method of each style class, so it would a bit clear that it’s an error with the invalid format fields.

bpo-34897 [https://bugs.python.org/issue?@action=redirect&bpo=34897]: Adjust test.support.missing_compiler_executable check so that a nominal command name of «» is ignored. Patch by Michael Felt.

bpo-34871 [https://bugs.python.org/issue?@action=redirect&bpo=34871]: Fix inspect module polluted sys.modules when parsing __text_signature__ of callable.

bpo-34898 [https://bugs.python.org/issue?@action=redirect&bpo=34898]: Add mtime argument to gzip.compress for reproducible output. Patch by Guo Ci Teo.

bpo-28441 [https://bugs.python.org/issue?@action=redirect&bpo=28441]: On Cygwin and MinGW, ensure that sys.executable always includes the full filename in the path, including the .exe suffix (unless it is a symbolic link).

bpo-34866 [https://bugs.python.org/issue?@action=redirect&bpo=34866]: Adding max_num_fields to cgi.FieldStorage to make DOS attacks harder by limiting the number of MiniFieldStorage objects created by FieldStorage.

bpo-34711 [https://bugs.python.org/issue?@action=redirect&bpo=34711]: http.server ensures it reports HTTPStatus.NOT_FOUND when the local path ends with «/» and is not a directory, even if the underlying OS (e.g. AIX) accepts such paths as a valid file reference. Patch by Michael Felt.

bpo-34872 [https://bugs.python.org/issue?@action=redirect&bpo=34872]: Fix self-cancellation in C implementation of asyncio.Task

bpo-34849 [https://bugs.python.org/issue?@action=redirect&bpo=34849]: Don’t log waiting for selector.select in asyncio loop iteration. The waiting is pretty normal for any asyncio program, logging its time just adds a noise to logs without any useful information provided.

bpo-34022 [https://bugs.python.org/issue?@action=redirect&bpo=34022]: The SOURCE_DATE_EPOCH environment variable no longer overrides the value of the invalidation_mode argument to py_compile.compile(), and determines its default value instead.

bpo-34819 [https://bugs.python.org/issue?@action=redirect&bpo=34819]: Use a monotonic clock to compute timeouts in Executor.map() and as_completed(), in order to prevent timeouts from deviating when the system clock is adjusted.

bpo-34758 [https://bugs.python.org/issue?@action=redirect&bpo=34758]: Add .wasm -> application/wasm to list of recognized file types and content type headers

bpo-34789 [https://bugs.python.org/issue?@action=redirect&bpo=34789]: xml.sax.make_parser() now accepts any iterable as its parser_list argument. Patch by Andrés Delfino.

bpo-34334 [https://bugs.python.org/issue?@action=redirect&bpo=34334]: In QueueHandler, clear exc_text from LogRecord to prevent traceback from being written twice.

bpo-34687 [https://bugs.python.org/issue?@action=redirect&bpo=34687]: On Windows, asyncio now uses ProactorEventLoop, instead of SelectorEventLoop, by default.

bpo-5950 [https://bugs.python.org/issue?@action=redirect&bpo=5950]: Support reading zip files with archive comments in zipimport.

bpo-32892 [https://bugs.python.org/issue?@action=redirect&bpo=32892]: The parser now represents all constants as ast.Constant instead of using specific constant AST types (Num, Str, Bytes, NameConstant and Ellipsis). These classes are considered deprecated and will be removed in future Python versions.

bpo-34728 [https://bugs.python.org/issue?@action=redirect&bpo=34728]: Add deprecation warning when loop is used in methods: asyncio.sleep, asyncio.wait and asyncio.wait_for.

bpo-34738 [https://bugs.python.org/issue?@action=redirect&bpo=34738]: ZIP files created by distutils will now include entries for directories.

bpo-34659 [https://bugs.python.org/issue?@action=redirect&bpo=34659]: Add an optional initial argument to itertools.accumulate().

bpo-29577 [https://bugs.python.org/issue?@action=redirect&bpo=29577]: Support multiple mixin classes when creating Enums.

bpo-34670 [https://bugs.python.org/issue?@action=redirect&bpo=34670]: Add SSLContext.post_handshake_auth and SSLSocket.verify_client_post_handshake for TLS 1.3’s post handshake authentication feature.

bpo-32718 [https://bugs.python.org/issue?@action=redirect&bpo=32718]: The Activate.ps1 script from venv works with PowerShell Core 6.1 and is now available under all operating systems.

bpo-31177 [https://bugs.python.org/issue?@action=redirect&bpo=31177]: Fix bug that prevented using reset_mock on mock instances with deleted attributes

bpo-34672 [https://bugs.python.org/issue?@action=redirect&bpo=34672]: Add a workaround, so the 'Z' time.strftime() specifier on the musl C library can work in some cases.

bpo-34666 [https://bugs.python.org/issue?@action=redirect&bpo=34666]: Implement asyncio.StreamWriter.awrite and asyncio.StreamWriter.aclose() coroutines. Methods are needed for providing a consistent stream API with control flow switched on by default.

bpo-6721 [https://bugs.python.org/issue?@action=redirect&bpo=6721]: Acquire the logging module’s commonly used internal locks while fork()ing to avoid deadlocks in the child process.

bpo-34658 [https://bugs.python.org/issue?@action=redirect&bpo=34658]: Fix a rare interpreter unhandled exception state SystemError only seen when using subprocess with a preexec_fn while an after_parent handler has been registered with os.register_at_fork and the fork system call fails.

bpo-34652 [https://bugs.python.org/issue?@action=redirect&bpo=34652]: Ensure os.lchmod() is never defined on Linux.

bpo-34638 [https://bugs.python.org/issue?@action=redirect&bpo=34638]: Store a weak reference to stream reader to break strong references loop between reader and protocol. It allows to detect and close the socket if the stream is deleted (garbage collected) without close() call.

bpo-34536 [https://bugs.python.org/issue?@action=redirect&bpo=34536]: Enum._missing_: raise ValueError if None returned and TypeError if non-member is returned.

bpo-34636 [https://bugs.python.org/issue?@action=redirect&bpo=34636]: Speed up re scanning of many non-matching characters for s w and d within bytes objects. (microoptimization)

bpo-24412 [https://bugs.python.org/issue?@action=redirect&bpo=24412]: Add addModuleCleanup() and addClassCleanup() to unittest to support cleanups for setUpModule() and setUpClass(). Patch by Lisa Roach.

bpo-34630 [https://bugs.python.org/issue?@action=redirect&bpo=34630]: Don’t log SSL certificate errors in asyncio code (connection error logging is skipped already).

bpo-32490 [https://bugs.python.org/issue?@action=redirect&bpo=32490]: Prevent filename duplication in subprocess exception messages. Patch by Zackery Spytz.

bpo-34363 [https://bugs.python.org/issue?@action=redirect&bpo=34363]: dataclasses.asdict() and .astuple() now handle namedtuples correctly.

bpo-34625 [https://bugs.python.org/issue?@action=redirect&bpo=34625]: Update vendorized expat library version to 2.2.6.

bpo-32270 [https://bugs.python.org/issue?@action=redirect&bpo=32270]: The subprocess module no longer mistakenly closes redirected fds even when they were in pass_fds when outside of the default {0, 1, 2} set.

bpo-34622 [https://bugs.python.org/issue?@action=redirect&bpo=34622]: Create a dedicated asyncio.CancelledError, asyncio.InvalidStateError and asyncio.TimeoutError exception classes. Inherit them from corresponding exceptions from concurrent.futures package. Extract asyncio exceptions into a separate file.

bpo-34610 [https://bugs.python.org/issue?@action=redirect&bpo=34610]: Fixed iterator of multiprocessing.managers.DictProxy.

bpo-34421 [https://bugs.python.org/issue?@action=redirect&bpo=34421]: Fix distutils logging for non-ASCII strings. This caused installation issues on Windows.

bpo-34604 [https://bugs.python.org/issue?@action=redirect&bpo=34604]: Fix possible mojibake in the error message of pwd.getpwnam and grp.getgrnam using string representation because of invisible characters or trailing whitespaces. Patch by William Grzybowski.

bpo-30977 [https://bugs.python.org/issue?@action=redirect&bpo=30977]: Make uuid.UUID use __slots__ to reduce its memory footprint. Based on original patch by Wouter Bolsterlee.

bpo-34574 [https://bugs.python.org/issue?@action=redirect&bpo=34574]: OrderedDict iterators are not exhausted during pickling anymore. Patch by Sergey Fedoseev.

bpo-8110 [https://bugs.python.org/issue?@action=redirect&bpo=8110]: Refactored subprocess to check for Windows-specific modules rather than sys.platform == 'win32'.

bpo-34530 [https://bugs.python.org/issue?@action=redirect&bpo=34530]: distutils.spawn.find_executable() now falls back on os.defpath if the PATH environment variable is not set.

bpo-34563 [https://bugs.python.org/issue?@action=redirect&bpo=34563]: On Windows, fix multiprocessing.Connection for very large read: fix _winapi.PeekNamedPipe() and _winapi.ReadFile() for read larger than INT_MAX (usually 2**31-1).

bpo-34558 [https://bugs.python.org/issue?@action=redirect&bpo=34558]: Correct typo in Lib/ctypes/_aix.py

bpo-34282 [https://bugs.python.org/issue?@action=redirect&bpo=34282]: Move Enum._convert to EnumMeta._convert_ and fix enum members getting shadowed by parent attributes.

bpo-22872 [https://bugs.python.org/issue?@action=redirect&bpo=22872]: When the queue is closed, ValueError is now raised by multiprocessing.Queue.put() and multiprocessing.Queue.get() instead of AssertionError and OSError, respectively. Patch by Zackery Spytz.

bpo-34515 [https://bugs.python.org/issue?@action=redirect&bpo=34515]: Fix parsing non-ASCII identifiers in lib2to3.pgen2.tokenize (PEP 3131).

bpo-13312 [https://bugs.python.org/issue?@action=redirect&bpo=13312]: Avoids a possible integer underflow (undefined behavior) in the time module’s year handling code when passed a very low negative year value.

bpo-34472 [https://bugs.python.org/issue?@action=redirect&bpo=34472]: Improved compatibility for streamed files in zipfile. Previously an optional signature was not being written and certain ZIP applications were not supported. Patch by Silas Sewell.

bpo-34454 [https://bugs.python.org/issue?@action=redirect&bpo=34454]: Fix the .fromisoformat() methods of datetime types crashing when given unicode with non-UTF-8-encodable code points. Specifically, datetime.fromisoformat() now accepts surrogate unicode code points used as the separator. Report and tests by Alexey Izbyshev, patch by Paul Ganssle.

bpo-6700 [https://bugs.python.org/issue?@action=redirect&bpo=6700]: Fix inspect.getsourcelines for module level frames/tracebacks. Patch by Vladimir Matveev.

bpo-34171 [https://bugs.python.org/issue?@action=redirect&bpo=34171]: Running the trace module no longer creates the trace.cover file.

bpo-34441 [https://bugs.python.org/issue?@action=redirect&bpo=34441]: Fix crash when an ABC-derived class with invalid __subclasses__ is passed as the second argument to issubclass(). Patch by Alexey Izbyshev.

bpo-34427 [https://bugs.python.org/issue?@action=redirect&bpo=34427]: Fix infinite loop in a.extend(a) for MutableSequence subclasses.

bpo-34412 [https://bugs.python.org/issue?@action=redirect&bpo=34412]: Make signal.strsignal() work on HP-UX. Patch by Michael Osipov.

bpo-20849 [https://bugs.python.org/issue?@action=redirect&bpo=20849]: shutil.copytree now accepts a new dirs_exist_ok keyword argument. Patch by Josh Bronson.

bpo-31715 [https://bugs.python.org/issue?@action=redirect&bpo=31715]: Associate .mjs file extension with application/javascript MIME Type.

bpo-34384 [https://bugs.python.org/issue?@action=redirect&bpo=34384]: os.readlink() now accepts path-like and bytes objects on Windows.

bpo-22602 [https://bugs.python.org/issue?@action=redirect&bpo=22602]: The UTF-7 decoder now raises UnicodeDecodeError for ill-formed sequences starting with «+» (as specified in RFC 2152). Patch by Zackery Spytz.

bpo-2122 [https://bugs.python.org/issue?@action=redirect&bpo=2122]: The mmap.flush() method now returns None on success, raises an exception on error under all platforms.

bpo-34341 [https://bugs.python.org/issue?@action=redirect&bpo=34341]: Appending to the ZIP archive with the ZIP64 extension no longer grows the size of extra fields of existing entries.

bpo-34333 [https://bugs.python.org/issue?@action=redirect&bpo=34333]: Fix %-formatting in pathlib.PurePath.with_suffix() when formatting an error message.

bpo-18540 [https://bugs.python.org/issue?@action=redirect&bpo=18540]: The imaplib.IMAP4 and imaplib.IMAP4_SSL classes now resolve to the local host IP correctly when the default value of host parameter ('') is used.

bpo-26502 [https://bugs.python.org/issue?@action=redirect&bpo=26502]: Implement traceback.FrameSummary.__len__() method to preserve compatibility with the old tuple API.

bpo-34318 [https://bugs.python.org/issue?@action=redirect&bpo=34318]: assertRaises(), assertRaisesRegex(), assertWarns() and assertWarnsRegex() no longer success if the passed callable is None. They no longer ignore unknown keyword arguments in the context manager mode. A DeprecationWarning was raised in these cases since Python 3.5.

bpo-9372 [https://bugs.python.org/issue?@action=redirect&bpo=9372]: Deprecate __getitem__() methods of xml.dom.pulldom.DOMEventStream, wsgiref.util.FileWrapper and fileinput.FileInput.

bpo-33613 [https://bugs.python.org/issue?@action=redirect&bpo=33613]: Fix a race condition in multiprocessing.semaphore_tracker when the tracker receives SIGINT before it can register signal handlers for ignoring it.

bpo-34248 [https://bugs.python.org/issue?@action=redirect&bpo=34248]: Report filename in the exception raised when the database file cannot be opened by dbm.gnu.open() and dbm.ndbm.open() due to OS-related error. Patch by Zsolt Cserna.

bpo-33089 [https://bugs.python.org/issue?@action=redirect&bpo=33089]: Add math.dist() to compute the Euclidean distance between two points.

bpo-34246 [https://bugs.python.org/issue?@action=redirect&bpo=34246]: smtplib.SMTP.send_message() no longer modifies the content of the mail_options argument. Patch by Pablo S. Blum de Aguiar.

bpo-31047 [https://bugs.python.org/issue?@action=redirect&bpo=31047]: Fix ntpath.abspath for invalid paths on windows. Patch by Franz Woellert.

bpo-32321 [https://bugs.python.org/issue?@action=redirect&bpo=32321]: Add pure Python fallback for functools.reduce. Patch by Robert Wright.

bpo-34270 [https://bugs.python.org/issue?@action=redirect&bpo=34270]: The default asyncio task class now always has a name which can be get or set using two new methods (get_name() and set_name()) and is visible in the repr() output. An initial name can also be set using the new name keyword argument to asyncio.create_task() or the create_task() method of the event loop. If no initial name is set, the default Task implementation generates a name like Task-1 using a monotonic counter.

bpo-34263 [https://bugs.python.org/issue?@action=redirect&bpo=34263]: asyncio’s event loop will not pass timeouts longer than one day to epoll/select etc.

bpo-34035 [https://bugs.python.org/issue?@action=redirect&bpo=34035]: Fix several AttributeError in zipfile seek() methods. Patch by Mickaël Schoentgen.

bpo-32215 [https://bugs.python.org/issue?@action=redirect&bpo=32215]: Fix performance regression in sqlite3 when a DML statement appeared in a different line than the rest of the SQL query.

bpo-34075 [https://bugs.python.org/issue?@action=redirect&bpo=34075]: Deprecate passing non-ThreadPoolExecutor instances to AbstractEventLoop.set_default_executor().

bpo-34251 [https://bugs.python.org/issue?@action=redirect&bpo=34251]: Restore msilib.Win64 to preserve backwards compatibility since it’s already used by distutils” bdist_msi command.

bpo-19891 [https://bugs.python.org/issue?@action=redirect&bpo=19891]: Ignore errors caused by missing / non-writable homedir while writing history during exit of an interactive session. Patch by Anthony Sottile.

bpo-33089 [https://bugs.python.org/issue?@action=redirect&bpo=33089]: Enhanced math.hypot() to support more than two dimensions.

bpo-34228 [https://bugs.python.org/issue?@action=redirect&bpo=34228]: tracemalloc: PYTHONTRACEMALLOC=0 environment variable and -X tracemalloc=0 command line option are now allowed to disable explicitly tracemalloc at startup.

bpo-13041 [https://bugs.python.org/issue?@action=redirect&bpo=13041]: Use shutil.get_terminal_size() to calculate the terminal width correctly in the argparse.HelpFormatter class. Initial patch by Zbyszek Jędrzejewski-Szmek.

bpo-34213 [https://bugs.python.org/issue?@action=redirect&bpo=34213]: Allow frozen dataclasses to have a field named «object». Previously this conflicted with an internal use of «object».

bpo-34052 [https://bugs.python.org/issue?@action=redirect&bpo=34052]: sqlite3.Connection.create_aggregate(), sqlite3.Connection.create_function(), sqlite3.Connection.set_authorizer(), sqlite3.Connection.set_progress_handler() methods raises TypeError when unhashable objects are passed as callable. These methods now don’t pass such objects to SQLite API. Previous behavior could lead to segfaults. Patch by Sergey Fedoseev.

bpo-34197 [https://bugs.python.org/issue?@action=redirect&bpo=34197]: Attributes skipinitialspace, doublequote and strict of the dialect attribute of the csv reader are now bool instances instead of integers 0 or 1.

bpo-32788 [https://bugs.python.org/issue?@action=redirect&bpo=32788]: Errors other than TypeError raised in methods __adapt__() and __conform__() in the sqlite3 module are now propagated to the user.

bpo-21446 [https://bugs.python.org/issue?@action=redirect&bpo=21446]: The reload fixer now uses importlib.reload() instead of deprecated imp.reload().

bpo-940286 [https://bugs.python.org/issue?@action=redirect&bpo=940286]: pydoc’s Helper.showtopic() method now prints the cross references of a topic correctly.

bpo-34164 [https://bugs.python.org/issue?@action=redirect&bpo=34164]: base64.b32decode() could raise UnboundLocalError or OverflowError for incorrect padding. Now it always raises base64.Error in these cases.

bpo-33729 [https://bugs.python.org/issue?@action=redirect&bpo=33729]: Fixed issues with arguments parsing in hashlib.

bpo-34097 [https://bugs.python.org/issue?@action=redirect&bpo=34097]: ZipFile can zip files older than 1980-01-01 and newer than 2107-12-31 using a new strict_timestamps parameter at the cost of setting the timestamp to the limit.

bpo-34108 [https://bugs.python.org/issue?@action=redirect&bpo=34108]: Remove extraneous CR in 2to3 refactor.

bpo-34070 [https://bugs.python.org/issue?@action=redirect&bpo=34070]: Make sure to only check if the handle is a tty, when opening a file with buffering=-1.

bpo-27494 [https://bugs.python.org/issue?@action=redirect&bpo=27494]: Reverted bpo-27494 [https://bugs.python.org/issue?@action=redirect&bpo=27494]. 2to3 rejects now a trailing comma in generator expressions.

bpo-33967 [https://bugs.python.org/issue?@action=redirect&bpo=33967]: functools.singledispatch now raises TypeError instead of IndexError when no positional arguments are passed.

bpo-34041 [https://bugs.python.org/issue?@action=redirect&bpo=34041]: Add the parameter deterministic to the sqlite3.Connection.create_function() method. Patch by Sergey Fedoseev.

bpo-34056 [https://bugs.python.org/issue?@action=redirect&bpo=34056]: Ensure the loader shim created by imp.load_module always returns bytes from its get_data() function. This fixes using imp.load_module with PEP 552 [https://www.python.org/dev/peps/pep-0552] hash-based pycs.

bpo-34054 [https://bugs.python.org/issue?@action=redirect&bpo=34054]: The multiprocessing module now uses the monotonic clock time.monotonic() instead of the system clock time.time() to implement timeout.

bpo-34043 [https://bugs.python.org/issue?@action=redirect&bpo=34043]: Optimize tarfile uncompress performance about 15% when gzip is used.

bpo-34044 [https://bugs.python.org/issue?@action=redirect&bpo=34044]: subprocess.Popen now copies the startupinfo argument to leave it unchanged: it will modify the copy, so that the same STARTUPINFO object can be used multiple times.

bpo-34010 [https://bugs.python.org/issue?@action=redirect&bpo=34010]: Fixed a performance regression for reading streams with tarfile. The buffered read should use a list, instead of appending to a bytes object.

bpo-34019 [https://bugs.python.org/issue?@action=redirect&bpo=34019]: webbrowser: Correct the arguments passed to Opera Browser when opening a new URL using the webbrowser module. Patch by Bumsik Kim.

bpo-34003 [https://bugs.python.org/issue?@action=redirect&bpo=34003]: csv.DictReader now creates dicts instead of OrderedDicts. Patch by Michael Selik.

bpo-33978 [https://bugs.python.org/issue?@action=redirect&bpo=33978]: Closed existing logging handlers before reconfiguration via fileConfig and dictConfig. Patch by Karthikeyan Singaravelan.

bpo-14117 [https://bugs.python.org/issue?@action=redirect&bpo=14117]: Make minor tweaks to turtledemo. The “wikipedia” example is now “rosette”, describing what it draws. The “penrose” print output is reduced. The’1024” output of “tree” is eliminated.

bpo-33974 [https://bugs.python.org/issue?@action=redirect&bpo=33974]: Fixed passing lists and tuples of strings containing special characters ", \, {, } and \n as options to ttk widgets.

bpo-27500 [https://bugs.python.org/issue?@action=redirect&bpo=27500]: Fix getaddrinfo to resolve IPv6 addresses correctly.

bpo-24567 [https://bugs.python.org/issue?@action=redirect&bpo=24567]: Improve random.choices() to handle subnormal input weights that could occasionally trigger an IndexError.

bpo-33871 [https://bugs.python.org/issue?@action=redirect&bpo=33871]: Fixed integer overflow in os.readv(), os.writev(), os.preadv() and os.pwritev() and in os.sendfile() with headers or trailers arguments (on BSD-based OSes and macOS).

bpo-25007 [https://bugs.python.org/issue?@action=redirect&bpo=25007]: Add copy.copy() and copy.deepcopy() support to zlib compressors and decompressors. Patch by Zackery Spytz.

bpo-33929 [https://bugs.python.org/issue?@action=redirect&bpo=33929]: multiprocessing: Fix a race condition in Popen of multiprocessing.popen_spawn_win32. The child process now duplicates the read end of pipe instead of «stealing» it. Previously, the read end of pipe was «stolen» by the child process, but it leaked a handle if the child process had been terminated before it could steal the handle from the parent process.

bpo-33899 [https://bugs.python.org/issue?@action=redirect&bpo=33899]: Tokenize module now implicitly emits a NEWLINE when provided with input that does not have a trailing new line. This behavior now matches what the C tokenizer does internally. Contributed by Ammar Askar.

bpo-33897 [https://bugs.python.org/issue?@action=redirect&bpo=33897]: Added a “force” keyword argument to logging.basicConfig().

bpo-33695 [https://bugs.python.org/issue?@action=redirect&bpo=33695]: shutil.copytree() uses os.scandir() function and all copy functions depending from it use cached os.stat() values. The speedup for copying a directory with 8000 files is around +9% on Linux, +20% on Windows and + 30% on a Windows SMB share. Also the number of os.stat() syscalls is reduced by 38% making shutil.copytree() especially faster on network filesystems. (Contributed by Giampaolo Rodola” in bpo-33695 [https://bugs.python.org/issue?@action=redirect&bpo=33695].)

bpo-33916 [https://bugs.python.org/issue?@action=redirect&bpo=33916]: bz2 and lzma: When Decompressor.__init__() is called twice, free the old lock to not leak memory.

bpo-32568 [https://bugs.python.org/issue?@action=redirect&bpo=32568]: Make select.epoll() and its documentation consistent regarding sizehint and flags.

bpo-33833 [https://bugs.python.org/issue?@action=redirect&bpo=33833]: Fixed bug in asyncio where ProactorSocketTransport logs AssertionError if force closed during write.

bpo-33663 [https://bugs.python.org/issue?@action=redirect&bpo=33663]: Convert content length to string before putting to header.

bpo-33721 [https://bugs.python.org/issue?@action=redirect&bpo=33721]: os.path functions that return a boolean result like exists(), lexists(), isdir(), isfile(), islink(), and ismount(), and pathlib.Path methods that return a boolean result like exists(), is_dir(), is_file(), is_mount(), is_symlink(), is_block_device(), is_char_device(), is_fifo(), is_socket() now return False instead of raising ValueError or its subclasses UnicodeEncodeError and UnicodeDecodeError for paths that contain characters or bytes unrepresentable at the OS level.

bpo-26544 [https://bugs.python.org/issue?@action=redirect&bpo=26544]: Fixed implementation of platform.libc_ver(). It almost always returned version “2.9” for glibc.

bpo-33843 [https://bugs.python.org/issue?@action=redirect&bpo=33843]: Remove deprecated cgi.escape, cgi.parse_qs and cgi.parse_qsl.

bpo-33842 [https://bugs.python.org/issue?@action=redirect&bpo=33842]: Remove tarfile.filemode which is deprecated since Python 3.3.

bpo-30167 [https://bugs.python.org/issue?@action=redirect&bpo=30167]: Prevent site.main() exception if PYTHONSTARTUP is set. Patch by Steve Weber.

bpo-33805 [https://bugs.python.org/issue?@action=redirect&bpo=33805]: Improve error message of dataclasses.replace() when an InitVar is not specified

bpo-33687 [https://bugs.python.org/issue?@action=redirect&bpo=33687]: Fix the call to os.chmod() for uu.decode() if a mode is given or decoded. Patch by Timo Furrer.

bpo-33812 [https://bugs.python.org/issue?@action=redirect&bpo=33812]: Datetime instance d with non-None tzinfo, but with d.tzinfo.utcoffset(d) returning None is now treated as naive by the astimezone() method.

bpo-32108 [https://bugs.python.org/issue?@action=redirect&bpo=32108]: In configparser, don’t clear section when it is assigned to itself.

bpo-27397 [https://bugs.python.org/issue?@action=redirect&bpo=27397]: Make email module properly handle invalid-length base64 strings.

bpo-33578 [https://bugs.python.org/issue?@action=redirect&bpo=33578]: Implement multibyte encoder/decoder state methods

bpo-30805 [https://bugs.python.org/issue?@action=redirect&bpo=30805]: Avoid race condition with debug logging

bpo-33476 [https://bugs.python.org/issue?@action=redirect&bpo=33476]: Fix _header_value_parser.py when address group is missing final “;”. Contributed by Enrique Perez-Terron

bpo-33694 [https://bugs.python.org/issue?@action=redirect&bpo=33694]: asyncio: Fix a race condition causing data loss on pause_reading()/resume_reading() when using the ProactorEventLoop.

bpo-32493 [https://bugs.python.org/issue?@action=redirect&bpo=32493]: Correct test for uuid_enc_be availability in configure.ac. Patch by Michael Felt.

bpo-33792 [https://bugs.python.org/issue?@action=redirect&bpo=33792]: Add asyncio.WindowsSelectorEventLoopPolicy and asyncio.WindowsProactorEventLoopPolicy.

bpo-33274 [https://bugs.python.org/issue?@action=redirect&bpo=33274]: W3C DOM Level 1 specifies return value of Element.removeAttributeNode() as «The Attr node that was removed.» xml.dom.minidom now complies with this requirement.

bpo-33778 [https://bugs.python.org/issue?@action=redirect&bpo=33778]: Update unicodedata’s database to Unicode version 11.0.0.

bpo-33165 [https://bugs.python.org/issue?@action=redirect&bpo=33165]: Added a stacklevel parameter to logging calls to allow use of wrapper/helper functions for logging APIs.

bpo-33770 [https://bugs.python.org/issue?@action=redirect&bpo=33770]: improve base64 exception message for encoded inputs of invalid length

bpo-33769 [https://bugs.python.org/issue?@action=redirect&bpo=33769]: asyncio/start_tls: Fix error message; cancel callbacks in case of an unhandled error; mark SSLTransport as closed if it is aborted.

bpo-33767 [https://bugs.python.org/issue?@action=redirect&bpo=33767]: The concatenation (+) and repetition (*) sequence operations now raise TypeError instead of SystemError when performed on mmap.mmap objects. Patch by Zackery Spytz.

bpo-33734 [https://bugs.python.org/issue?@action=redirect&bpo=33734]: asyncio/ssl: Fix AttributeError, increase default handshake timeout

bpo-31014 [https://bugs.python.org/issue?@action=redirect&bpo=31014]: Fixed creating a controller for webbrowser when a user specifies a path to an entry in the BROWSER environment variable. Based on patch by John Still.

bpo-2504 [https://bugs.python.org/issue?@action=redirect&bpo=2504]: Add gettext.pgettext() and variants.

bpo-33197 [https://bugs.python.org/issue?@action=redirect&bpo=33197]: Add description property for _ParameterKind

bpo-32751 [https://bugs.python.org/issue?@action=redirect&bpo=32751]: When cancelling the task due to a timeout, asyncio.wait_for() will now wait until the cancellation is complete.

bpo-32684 [https://bugs.python.org/issue?@action=redirect&bpo=32684]: Fix gather to propagate cancellation of itself even with return_exceptions.

bpo-33654 [https://bugs.python.org/issue?@action=redirect&bpo=33654]: Support protocol type switching in SSLTransport.set_protocol().

bpo-33674 [https://bugs.python.org/issue?@action=redirect&bpo=33674]: Pause the transport as early as possible to further reduce the risk of data_received() being called before connection_made().

bpo-33671 [https://bugs.python.org/issue?@action=redirect&bpo=33671]: shutil.copyfile(), shutil.copy(), shutil.copy2(), shutil.copytree() and shutil.move() use platform-specific fast-copy syscalls on Linux and macOS in order to copy the file more efficiently. On Windows shutil.copyfile() uses a bigger default buffer size (1 MiB instead of 16 KiB) and a memoryview()-based variant of shutil.copyfileobj() is used. The speedup for copying a 512MiB file is about +26% on Linux, +50% on macOS and +40% on Windows. Also, much less CPU cycles are consumed. (Contributed by Giampaolo Rodola” in bpo-25427 [https://bugs.python.org/issue?@action=redirect&bpo=25427].)

bpo-33674 [https://bugs.python.org/issue?@action=redirect&bpo=33674]: Fix a race condition in SSLProtocol.connection_made() of asyncio.sslproto: start immediately the handshake instead of using call_soon(). Previously, data_received() could be called before the handshake started, causing the handshake to hang or fail.

bpo-31647 [https://bugs.python.org/issue?@action=redirect&bpo=31647]: Fixed bug where calling write_eof() on a _SelectorSocketTransport after it’s already closed raises AttributeError.

bpo-32610 [https://bugs.python.org/issue?@action=redirect&bpo=32610]: Make asyncio.all_tasks() return only pending tasks.

bpo-32410 [https://bugs.python.org/issue?@action=redirect&bpo=32410]: Avoid blocking on file IO in sendfile fallback code

bpo-33469 [https://bugs.python.org/issue?@action=redirect&bpo=33469]: Fix RuntimeError after closing loop that used run_in_executor

bpo-33672 [https://bugs.python.org/issue?@action=redirect&bpo=33672]: Fix Task.__repr__ crash with Cython’s bogus coroutines

bpo-33654 [https://bugs.python.org/issue?@action=redirect&bpo=33654]: Fix transport.set_protocol() to support switching between asyncio.Protocol and asyncio.BufferedProtocol. Fix loop.start_tls() to work with asyncio.BufferedProtocols.

bpo-33652 [https://bugs.python.org/issue?@action=redirect&bpo=33652]: Pickles of type variables and subscripted generics are now future-proof and compatible with older Python versions.

bpo-32493 [https://bugs.python.org/issue?@action=redirect&bpo=32493]: Fixed uuid.uuid1() on FreeBSD.

bpo-33238 [https://bugs.python.org/issue?@action=redirect&bpo=33238]: Add InvalidStateError to concurrent.futures. Future.set_result and Future.set_exception now raise InvalidStateError if the futures are not pending or running. Patch by Jason Haydaman.

bpo-33618 [https://bugs.python.org/issue?@action=redirect&bpo=33618]: Finalize and document preliminary and experimental TLS 1.3 support with OpenSSL 1.1.1

bpo-33625 [https://bugs.python.org/issue?@action=redirect&bpo=33625]: Release GIL on grp.getgrnam, grp.getgrgid, pwd.getpwnam and pwd.getpwuid if reentrant variants of these functions are available. Patch by William Grzybowski.

bpo-33623 [https://bugs.python.org/issue?@action=redirect&bpo=33623]: Fix possible SIGSGV when asyncio.Future is created in __del__

bpo-11874 [https://bugs.python.org/issue?@action=redirect&bpo=11874]: Use a better regex when breaking usage into wrappable parts. Avoids bogus assertion errors from custom metavar strings.

bpo-30877 [https://bugs.python.org/issue?@action=redirect&bpo=30877]: Fixed a bug in the Python implementation of the JSON decoder that prevented the cache of parsed strings from clearing after finishing the decoding. Based on patch by c-fos.

bpo-33604 [https://bugs.python.org/issue?@action=redirect&bpo=33604]: Remove HMAC default to md5 marked for removal in 3.8 (removal originally planned in 3.6, bump to 3.8 in PR 7062).

bpo-33582 [https://bugs.python.org/issue?@action=redirect&bpo=33582]: Emit a deprecation warning for inspect.formatargspec

bpo-21145 [https://bugs.python.org/issue?@action=redirect&bpo=21145]: Add functools.cached_property decorator, for computed properties cached for the life of the instance.

bpo-33570 [https://bugs.python.org/issue?@action=redirect&bpo=33570]: Change TLS 1.3 cipher suite settings for compatibility with OpenSSL 1.1.1-pre6 and newer. OpenSSL 1.1.1 will have TLS 1.3 ciphers enabled by default.

bpo-28556 [https://bugs.python.org/issue?@action=redirect&bpo=28556]: Do not simplify arguments to typing.Union. Now Union[Manager, Employee] is not simplified to Employee at runtime. Such simplification previously caused several bugs and limited possibilities for introspection.

bpo-12486 [https://bugs.python.org/issue?@action=redirect&bpo=12486]: tokenize.generate_tokens() is now documented as a public API to tokenize unicode strings. It was previously present but undocumented.

bpo-33540 [https://bugs.python.org/issue?@action=redirect&bpo=33540]: Add a new block_on_close class attribute to ForkingMixIn and ThreadingMixIn classes of socketserver.

bpo-33548 [https://bugs.python.org/issue?@action=redirect&bpo=33548]: tempfile._candidate_tempdir_list should consider common TEMP locations

bpo-33109 [https://bugs.python.org/issue?@action=redirect&bpo=33109]: argparse subparsers are once again not required by default, reverting the change in behavior introduced by bpo-26510 [https://bugs.python.org/issue?@action=redirect&bpo=26510] in 3.7.0a2.

bpo-33541 [https://bugs.python.org/issue?@action=redirect&bpo=33541]: Remove unused private method _strptime.LocaleTime.__pad (a.k.a. _LocaleTime__pad).

bpo-33536 [https://bugs.python.org/issue?@action=redirect&bpo=33536]: dataclasses.make_dataclass now checks for invalid field names and duplicate fields. Also, added a check for invalid field specifications.

bpo-33542 [https://bugs.python.org/issue?@action=redirect&bpo=33542]: Prevent uuid.get_node from using a DUID instead of a MAC on Windows. Patch by Zvi Effron

bpo-26819 [https://bugs.python.org/issue?@action=redirect&bpo=26819]: Fix race condition with ReadTransport.resume_reading in Windows proactor event loop.

Fix failure in typing.get_type_hints() when ClassVar was provided as a string forward reference.

bpo-33516 [https://bugs.python.org/issue?@action=redirect&bpo=33516]: unittest.mock.MagicMock now supports the __round__ magic method.

bpo-28612 [https://bugs.python.org/issue?@action=redirect&bpo=28612]: Added support for Site Maps to urllib’s RobotFileParser as RobotFileParser.site_maps(). Patch by Lady Red, based on patch by Peter Wirtz.

bpo-28167 [https://bugs.python.org/issue?@action=redirect&bpo=28167]: Remove platform.linux_distribution, which was deprecated since 3.5.

bpo-33504 [https://bugs.python.org/issue?@action=redirect&bpo=33504]: Switch the default dictionary implementation for configparser from collections.OrderedDict to the standard dict type.

bpo-33505 [https://bugs.python.org/issue?@action=redirect&bpo=33505]: Optimize asyncio.ensure_future() by reordering if checks: 1.17x faster.

bpo-33497 [https://bugs.python.org/issue?@action=redirect&bpo=33497]: Add errors param to cgi.parse_multipart and make an encoding in FieldStorage use the given errors (needed for Twisted). Patch by Amber Brown.

bpo-29235 [https://bugs.python.org/issue?@action=redirect&bpo=29235]: The cProfile.Profile class can now be used as a context manager. Patch by Scott Sanderson.

bpo-33495 [https://bugs.python.org/issue?@action=redirect&bpo=33495]: Change dataclasses.Fields repr to use the repr of each of its members, instead of str. This makes it more clear what each field actually represents. This is especially true for the “type” member.

bpo-26103 [https://bugs.python.org/issue?@action=redirect&bpo=26103]: Correct inspect.isdatadescriptor to look for __set__ or __delete__. Patch by Aaron Hall.

bpo-29209 [https://bugs.python.org/issue?@action=redirect&bpo=29209]: Removed the doctype() method and the html parameter of the constructor of XMLParser. The doctype() method defined in a subclass will no longer be called. Deprecated methods getchildren() and getiterator() in the ElementTree module emit now a DeprecationWarning instead of PendingDeprecationWarning.

bpo-33453 [https://bugs.python.org/issue?@action=redirect&bpo=33453]: Fix dataclasses to work if using literal string type annotations or if using PEP 563 «Postponed Evaluation of Annotations». Only specific string prefixes are detected for both ClassVar («ClassVar» and «typing.ClassVar») and InitVar («InitVar» and «dataclasses.InitVar»).

bpo-28556 [https://bugs.python.org/issue?@action=redirect&bpo=28556]: Minor fixes in typing module: add annotations to NamedTuple.__new__, pass *args and **kwds in Generic.__new__. Original PRs by Paulius Šarka and Chad Dombrova.

bpo-33365 [https://bugs.python.org/issue?@action=redirect&bpo=33365]: Print the header values besides the header keys instead just the header keys if debuglevel is set to >0 in http.client. Patch by Marco Strigl.

bpo-20087 [https://bugs.python.org/issue?@action=redirect&bpo=20087]: Updated alias mapping with glibc 2.27 supported locales.

bpo-33422 [https://bugs.python.org/issue?@action=redirect&bpo=33422]: Fix trailing quotation marks getting deleted when looking up byte/string literals on pydoc. Patch by Andrés Delfino.

bpo-28167 [https://bugs.python.org/issue?@action=redirect&bpo=28167]: The function platform.linux_distribution and platform.dist now trigger a DeprecationWarning and have been marked for removal in Python 3.8

bpo-33281 [https://bugs.python.org/issue?@action=redirect&bpo=33281]: Fix ctypes.util.find_library regression on macOS.

bpo-33311 [https://bugs.python.org/issue?@action=redirect&bpo=33311]: Text and html output generated by cgitb does not display parentheses if the current call is done directly in the module. Patch by Stéphane Blondon.

bpo-27300 [https://bugs.python.org/issue?@action=redirect&bpo=27300]: The file classes in tempfile now accept an errors parameter that complements the already existing encoding. Patch by Stephan Hohe.

bpo-32933 [https://bugs.python.org/issue?@action=redirect&bpo=32933]: unittest.mock.mock_open() now supports iteration over the file contents. Patch by Tony Flury.

bpo-33217 [https://bugs.python.org/issue?@action=redirect&bpo=33217]: Raise TypeError when looking up non-Enum objects in Enum classes and Enum members.

bpo-33197 [https://bugs.python.org/issue?@action=redirect&bpo=33197]: Update error message when constructing invalid inspect.Parameters Patch by Dong-hee Na.

bpo-33383 [https://bugs.python.org/issue?@action=redirect&bpo=33383]: Fixed crash in the get() method of the dbm.ndbm database object when it is called with a single argument.

bpo-33375 [https://bugs.python.org/issue?@action=redirect&bpo=33375]: The warnings module now finds the Python file associated with a warning from the code object, rather than the frame’s global namespace. This is consistent with how tracebacks and pdb find filenames, and should work better for dynamically executed code.

bpo-33336 [https://bugs.python.org/issue?@action=redirect&bpo=33336]: imaplib now allows MOVE command in IMAP4.uid() (RFC 6851: IMAP MOVE Extension) and potentially as a name of supported method of IMAP4 object.

bpo-32455 [https://bugs.python.org/issue?@action=redirect&bpo=32455]: Added jump parameter to dis.stack_effect().

bpo-27485 [https://bugs.python.org/issue?@action=redirect&bpo=27485]: Rename and deprecate undocumented functions in urllib.parse().

bpo-33332 [https://bugs.python.org/issue?@action=redirect&bpo=33332]: Add signal.valid_signals() to expose the POSIX sigfillset() functionality.

bpo-33251 [https://bugs.python.org/issue?@action=redirect&bpo=33251]: ConfigParser.items() was fixed so that key-value pairs passed in via vars are not included in the resulting output.

bpo-33329 [https://bugs.python.org/issue?@action=redirect&bpo=33329]: Fix multiprocessing regression on newer glibcs

bpo-33334 [https://bugs.python.org/issue?@action=redirect&bpo=33334]: dis.stack_effect() now supports all defined opcodes including NOP and EXTENDED_ARG.

bpo-991266 [https://bugs.python.org/issue?@action=redirect&bpo=991266]: Fix quoting of the Comment attribute of http.cookies.SimpleCookie.

bpo-33131 [https://bugs.python.org/issue?@action=redirect&bpo=33131]: Upgrade bundled version of pip to 10.0.1.

bpo-33308 [https://bugs.python.org/issue?@action=redirect&bpo=33308]: Fixed a crash in the parser module when converting an ST object to a tree of tuples or lists with line_info=False and col_info=True.

bpo-23403 [https://bugs.python.org/issue?@action=redirect&bpo=23403]: lib2to3 now uses pickle protocol 4 for pre-computed grammars.

bpo-33266 [https://bugs.python.org/issue?@action=redirect&bpo=33266]: lib2to3 now recognizes rf'...' strings.

bpo-11594 [https://bugs.python.org/issue?@action=redirect&bpo=11594]: Ensure line-endings are respected when using lib2to3.

bpo-33254 [https://bugs.python.org/issue?@action=redirect&bpo=33254]: Have importlib.resources.contents() and importlib.abc.ResourceReader.contents() return an iterable instead of an iterator.

bpo-33265 [https://bugs.python.org/issue?@action=redirect&bpo=33265]: contextlib.ExitStack and contextlib.AsyncExitStack now use a method instead of a wrapper function for exit callbacks.

bpo-33263 [https://bugs.python.org/issue?@action=redirect&bpo=33263]: Fix FD leak in _SelectorSocketTransport Patch by Vlad Starostin.

bpo-33256 [https://bugs.python.org/issue?@action=redirect&bpo=33256]: Fix display of <module> call in the html produced by cgitb.html(). Patch by Stéphane Blondon.

bpo-33144 [https://bugs.python.org/issue?@action=redirect&bpo=33144]: random.Random() and its subclassing mechanism got optimized to check only once at class/subclass instantiation time whether its getrandbits() method can be relied on by other methods, including randrange(), for the generation of arbitrarily large random integers. Patch by Wolfgang Maier.

bpo-33185 [https://bugs.python.org/issue?@action=redirect&bpo=33185]: Fixed regression when running pydoc with the -m switch. (The regression was introduced in 3.7.0b3 by the resolution of bpo-33053 [https://bugs.python.org/issue?@action=redirect&bpo=33053])

This fix also changed pydoc to add os.getcwd() to sys.path when necessary, rather than adding ".".

bpo-29613 [https://bugs.python.org/issue?@action=redirect&bpo=29613]: Added support for the SameSite cookie flag to the http.cookies module.

bpo-33169 [https://bugs.python.org/issue?@action=redirect&bpo=33169]: Delete entries of None in sys.path_importer_cache when importlib.machinery.invalidate_caches() is called.

bpo-33203 [https://bugs.python.org/issue?@action=redirect&bpo=33203]: random.Random.choice() now raises IndexError for empty sequences consistently even when called from subclasses without a getrandbits() implementation.

bpo-33224 [https://bugs.python.org/issue?@action=redirect&bpo=33224]: Update difflib.mdiff() for PEP 479 [https://www.python.org/dev/peps/pep-0479]. Convert an uncaught StopIteration in a generator into a return-statement.

bpo-33209 [https://bugs.python.org/issue?@action=redirect&bpo=33209]: End framing at the end of C implementation of pickle.Pickler.dump().

bpo-32861 [https://bugs.python.org/issue?@action=redirect&bpo=32861]: The urllib.robotparser’s __str__ representation now includes wildcard entries and the «Crawl-delay» and «Request-rate» fields. Also removes extra newlines that were being appended to the end of the string. Patch by Michael Lazar.

bpo-23403 [https://bugs.python.org/issue?@action=redirect&bpo=23403]: DEFAULT_PROTOCOL in pickle was bumped to 4. Protocol 4 is described in PEP 3154 [https://www.python.org/dev/peps/pep-3154] and available since Python 3.4. It offers better performance and smaller size compared to protocol 3 introduced in Python 3.0.

bpo-20104 [https://bugs.python.org/issue?@action=redirect&bpo=20104]: Improved error handling and fixed a reference leak in os.posix_spawn().

bpo-33106 [https://bugs.python.org/issue?@action=redirect&bpo=33106]: Deleting a key from a read-only dbm database raises module specific error instead of KeyError.

bpo-33175 [https://bugs.python.org/issue?@action=redirect&bpo=33175]: In dataclasses, Field.__set_name__ now looks up the __set_name__ special method on the class, not the instance, of the default value.

bpo-32380 [https://bugs.python.org/issue?@action=redirect&bpo=32380]: Create functools.singledispatchmethod to support generic single dispatch on descriptors and methods.

bpo-33141 [https://bugs.python.org/issue?@action=redirect&bpo=33141]: Have Field objects pass through __set_name__ to their default values, if they have their own __set_name__.

bpo-33096 [https://bugs.python.org/issue?@action=redirect&bpo=33096]: Allow ttk.Treeview.insert to insert iid that has a false boolean value. Note iid=0 and iid=False would be same. Patch by Garvit Khatri.

bpo-32873 [https://bugs.python.org/issue?@action=redirect&bpo=32873]: Treat type variables and special typing forms as immutable by copy and pickle. This fixes several minor issues and inconsistencies, and improves backwards compatibility with Python 3.6.

bpo-33134 [https://bugs.python.org/issue?@action=redirect&bpo=33134]: When computing dataclass’s __hash__, use the lookup table to contain the function which returns the __hash__ value. This is an improvement over looking up a string, and then testing that string to see what to do.

bpo-33127 [https://bugs.python.org/issue?@action=redirect&bpo=33127]: The ssl module now compiles with LibreSSL 2.7.1.

bpo-32505 [https://bugs.python.org/issue?@action=redirect&bpo=32505]: Raise TypeError if a member variable of a dataclass is of type Field, but doesn’t have a type annotation.

bpo-33078 [https://bugs.python.org/issue?@action=redirect&bpo=33078]: Fix the failure on OSX caused by the tests relying on sem_getvalue

bpo-33116 [https://bugs.python.org/issue?@action=redirect&bpo=33116]: Add “Field” to dataclasses.__all__.

bpo-32896 [https://bugs.python.org/issue?@action=redirect&bpo=32896]: Fix an error where subclassing a dataclass with a field that uses a default_factory would generate an incorrect class.

bpo-33100 [https://bugs.python.org/issue?@action=redirect&bpo=33100]: Dataclasses: If a field has a default value that’s a MemberDescriptorType, then it’s from that field being in __slots__, not an actual default value.

bpo-32953 [https://bugs.python.org/issue?@action=redirect&bpo=32953]: If a non-dataclass inherits from a frozen dataclass, allow attributes to be added to the derived class. Only attributes from the frozen dataclass cannot be assigned to. Require all dataclasses in a hierarchy to be either all frozen or all non-frozen.

bpo-33097 [https://bugs.python.org/issue?@action=redirect&bpo=33097]: Raise RuntimeError when executor.submit is called during interpreter shutdown.

bpo-32968 [https://bugs.python.org/issue?@action=redirect&bpo=32968]: Modulo and floor division involving Fraction and float should return float.

bpo-33061 [https://bugs.python.org/issue?@action=redirect&bpo=33061]: Add missing NoReturn to __all__ in typing.py

bpo-33078 [https://bugs.python.org/issue?@action=redirect&bpo=33078]: Fix the size handling in multiprocessing.Queue when a pickling error occurs.

bpo-33064 [https://bugs.python.org/issue?@action=redirect&bpo=33064]: lib2to3 now properly supports trailing commas after *args and **kwargs in function signatures.

bpo-33056 [https://bugs.python.org/issue?@action=redirect&bpo=33056]: FIX properly close leaking fds in concurrent.futures.ProcessPoolExecutor.

bpo-33021 [https://bugs.python.org/issue?@action=redirect&bpo=33021]: Release the GIL during fstat() calls, avoiding hang of all threads when calling mmap.mmap(), os.urandom(), and random.seed(). Patch by Nir Soffer.

bpo-31804 [https://bugs.python.org/issue?@action=redirect&bpo=31804]: Avoid failing in multiprocessing.Process if the standard streams are closed or None at exit.

bpo-33034 [https://bugs.python.org/issue?@action=redirect&bpo=33034]: Providing an explicit error message when casting the port property to anything that is not an integer value using urlparse() and urlsplit(). Patch by Matt Eaton.

bpo-30249 [https://bugs.python.org/issue?@action=redirect&bpo=30249]: Improve struct.unpack_from() exception messages for problems with the buffer size and offset.

bpo-33037 [https://bugs.python.org/issue?@action=redirect&bpo=33037]: Skip sending/receiving data after SSL transport closing.

bpo-27683 [https://bugs.python.org/issue?@action=redirect&bpo=27683]: Fix a regression in ipaddress that result of hosts() is empty when the network is constructed by a tuple containing an integer mask and only 1 bit left for addresses.

bpo-22674 [https://bugs.python.org/issue?@action=redirect&bpo=22674]: Add the strsignal() function in the signal module that returns the system description of the given signal, as returned by strsignal(3).

bpo-32999 [https://bugs.python.org/issue?@action=redirect&bpo=32999]: Fix C implementation of ABC.__subclasscheck__(cls, subclass) crashed when subclass is not a type object.

bpo-33009 [https://bugs.python.org/issue?@action=redirect&bpo=33009]: Fix inspect.signature() for single-parameter partialmethods.

bpo-32969 [https://bugs.python.org/issue?@action=redirect&bpo=32969]: Expose several missing constants in zlib and fix corresponding documentation.

bpo-32056 [https://bugs.python.org/issue?@action=redirect&bpo=32056]: Improved exceptions raised for invalid number of channels and sample width when read an audio file in modules aifc, wave and sunau.

bpo-32970 [https://bugs.python.org/issue?@action=redirect&bpo=32970]: Improved disassembly of the MAKE_FUNCTION instruction.

bpo-32844 [https://bugs.python.org/issue?@action=redirect&bpo=32844]: Fix wrong redirection of a low descriptor (0 or 1) to stderr in subprocess if another low descriptor is closed.

bpo-32960 [https://bugs.python.org/issue?@action=redirect&bpo=32960]: For dataclasses, disallow inheriting frozen from non-frozen classes, and also disallow inheriting non-frozen from frozen classes. This restriction will be relaxed at a future date.

bpo-32713 [https://bugs.python.org/issue?@action=redirect&bpo=32713]: Fixed tarfile.itn handling of out-of-bounds float values. Patch by Joffrey Fuhrer.

bpo-32257 [https://bugs.python.org/issue?@action=redirect&bpo=32257]: The ssl module now contains OP_NO_RENEGOTIATION constant, available with OpenSSL 1.1.0h or 1.1.1.

bpo-32951 [https://bugs.python.org/issue?@action=redirect&bpo=32951]: Direct instantiation of SSLSocket and SSLObject objects is now prohibited. The constructors were never documented, tested, or designed as public constructors. Users were suppose to use ssl.wrap_socket() or SSLContext.

bpo-32929 [https://bugs.python.org/issue?@action=redirect&bpo=32929]: Remove the tri-state parameter «hash», and add the boolean «unsafe_hash». If unsafe_hash is True, add a __hash__ function, but if a __hash__ exists, raise TypeError. If unsafe_hash is False, add a __hash__ based on the values of eq= and frozen=. The unsafe_hash=False behavior is the same as the old hash=None behavior. unsafe_hash=False is the default, just as hash=None used to be.

bpo-32947 [https://bugs.python.org/issue?@action=redirect&bpo=32947]: Add OP_ENABLE_MIDDLEBOX_COMPAT and test workaround for TLSv1.3 for future compatibility with OpenSSL 1.1.1.

bpo-32146 [https://bugs.python.org/issue?@action=redirect&bpo=32146]: Document the interaction between frozen executables and the spawn and forkserver start methods in multiprocessing.

bpo-30622 [https://bugs.python.org/issue?@action=redirect&bpo=30622]: The ssl module now detects missing NPN support in LibreSSL.

bpo-32922 [https://bugs.python.org/issue?@action=redirect&bpo=32922]: dbm.open() now encodes filename with the filesystem encoding rather than default encoding.

bpo-32759 [https://bugs.python.org/issue?@action=redirect&bpo=32759]: Free unused arenas in multiprocessing.heap.

bpo-32859 [https://bugs.python.org/issue?@action=redirect&bpo=32859]: In os.dup2, don’t check every call whether the dup3 syscall exists or not.

bpo-32556 [https://bugs.python.org/issue?@action=redirect&bpo=32556]: nt._getfinalpathname, nt._getvolumepathname and nt._getdiskusage now correctly convert from bytes.

bpo-21060 [https://bugs.python.org/issue?@action=redirect&bpo=21060]: Rewrite confusing message from setup.py upload from «No dist file created in earlier command» to the more helpful «Must create and upload files in one command».

bpo-32857 [https://bugs.python.org/issue?@action=redirect&bpo=32857]: In tkinter, after_cancel(None) now raises a ValueError instead of canceling the first scheduled function. Patch by Cheryl Sabella.

bpo-32852 [https://bugs.python.org/issue?@action=redirect&bpo=32852]: Make sure sys.argv remains as a list when running trace.

bpo-31333 [https://bugs.python.org/issue?@action=redirect&bpo=31333]: _abc module is added. It is a speedup module with C implementations for various functions and methods in abc. Creating an ABC subclass and calling isinstance or issubclass with an ABC subclass are up to 1.5x faster. In addition, this makes Python start-up up to 10% faster.

Note that the new implementation hides internal registry and caches, previously accessible via private attributes _abc_registry, _abc_cache, and _abc_negative_cache. There are three debugging helper methods that can be used instead _dump_registry, _abc_registry_clear, and _abc_caches_clear.

bpo-32841 [https://bugs.python.org/issue?@action=redirect&bpo=32841]: Fixed asyncio.Condition issue which silently ignored cancellation after notifying and cancelling a conditional lock. Patch by Bar Harel.

bpo-32819 [https://bugs.python.org/issue?@action=redirect&bpo=32819]: ssl.match_hostname() has been simplified and no longer depends on re and ipaddress module for wildcard and IP addresses. Error reporting for invalid wildcards has been improved.

bpo-19675 [https://bugs.python.org/issue?@action=redirect&bpo=19675]: multiprocessing.Pool no longer leaks processes if its initialization fails.

bpo-32394 [https://bugs.python.org/issue?@action=redirect&bpo=32394]: socket: Remove TCP_FASTOPEN,TCP_KEEPCNT,TCP_KEEPIDLE,TCP_KEEPINTVL flags on older version Windows during run-time.

bpo-31787 [https://bugs.python.org/issue?@action=redirect&bpo=31787]: Fixed refleaks of __init__() methods in various modules. (Contributed by Oren Milman)

bpo-30157 [https://bugs.python.org/issue?@action=redirect&bpo=30157]: Fixed guessing quote and delimiter in csv.Sniffer.sniff() when only the last field is quoted. Patch by Jake Davis.

bpo-30688 [https://bugs.python.org/issue?@action=redirect&bpo=30688]: Added support of \N{name} escapes in regular expressions. Based on patch by Jonathan Eunice.

bpo-32792 [https://bugs.python.org/issue?@action=redirect&bpo=32792]: collections.ChainMap() preserves the order of the underlying mappings.

bpo-32775 [https://bugs.python.org/issue?@action=redirect&bpo=32775]: fnmatch.translate() no longer produces patterns which contain set operations. Sets starting with “[” or containing “–”, “&&”, “~~” or “||” will be interpreted differently in regular expressions in future versions. Currently they emit warnings. fnmatch.translate() now avoids producing patterns containing such sets by accident.

bpo-32622 [https://bugs.python.org/issue?@action=redirect&bpo=32622]: Implement native fast sendfile for Windows proactor event loop.

bpo-32777 [https://bugs.python.org/issue?@action=redirect&bpo=32777]: Fix a rare but potential pre-exec child process deadlock in subprocess on POSIX systems when marking file descriptors inheritable on exec in the child process. This bug appears to have been introduced in 3.4.

bpo-32647 [https://bugs.python.org/issue?@action=redirect&bpo=32647]: The ctypes module used to depend on indirect linking for dlopen. The shared extension is now explicitly linked against libdl on platforms with dl.

bpo-32749 [https://bugs.python.org/issue?@action=redirect&bpo=32749]: A dbm.dumb database opened with flags “r” is now read-only. dbm.dumb.open() with flags “r” and “w” no longer creates a database if it does not exist.

bpo-32741 [https://bugs.python.org/issue?@action=redirect&bpo=32741]: Implement asyncio.TimerHandle.when() method.

bpo-32691 [https://bugs.python.org/issue?@action=redirect&bpo=32691]: Use mod_spec.parent when running modules with pdb

bpo-32734 [https://bugs.python.org/issue?@action=redirect&bpo=32734]: Fixed asyncio.Lock() safety issue which allowed acquiring and locking the same lock multiple times, without it being free. Patch by Bar Harel.

bpo-32727 [https://bugs.python.org/issue?@action=redirect&bpo=32727]: Do not include name field in SMTP envelope from address. Patch by Stéphane Wirtel

bpo-31453 [https://bugs.python.org/issue?@action=redirect&bpo=31453]: Add TLSVersion constants and SSLContext.maximum_version / minimum_version attributes. The new API wraps OpenSSL 1.1 https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_min_proto_version.html feature.

bpo-24334 [https://bugs.python.org/issue?@action=redirect&bpo=24334]: Internal implementation details of ssl module were cleaned up. The SSLSocket has one less layer of indirection. Owner and session information are now handled by the SSLSocket and SSLObject constructor. Channel binding implementation has been simplified.

bpo-31848 [https://bugs.python.org/issue?@action=redirect&bpo=31848]: Fix the error handling in Aifc_read.initfp() when the SSND chunk is not found. Patch by Zackery Spytz.

bpo-32585 [https://bugs.python.org/issue?@action=redirect&bpo=32585]: Add Ttk spinbox widget to tkinter.ttk. Patch by Alan D Moore.

bpo-32512 [https://bugs.python.org/issue?@action=redirect&bpo=32512]: profile CLI accepts -m module_name as an alternative to script path.

bpo-8525 [https://bugs.python.org/issue?@action=redirect&bpo=8525]: help() on a type now displays builtin subclasses. This is intended primarily to help with notification of more specific exception subclasses.

Patch by Sanyam Khurana.

bpo-31639 [https://bugs.python.org/issue?@action=redirect&bpo=31639]: http.server now exposes a ThreadingHTTPServer class and uses it when the module is run with -m to cope with web browsers pre-opening sockets.

bpo-29877 [https://bugs.python.org/issue?@action=redirect&bpo=29877]: compileall: import ProcessPoolExecutor only when needed, preventing hangs on low resource platforms

bpo-32221 [https://bugs.python.org/issue?@action=redirect&bpo=32221]: Various functions returning tuple containing IPv6 addresses now omit %scope part since the same information is already encoded in scopeid tuple item. Especially this speeds up socket.recvfrom() when it receives multicast packet since useless resolving of network interface name is omitted.

bpo-32147 [https://bugs.python.org/issue?@action=redirect&bpo=32147]: binascii.unhexlify() is now up to 2 times faster. Patch by Sergey Fedoseev.

bpo-30693 [https://bugs.python.org/issue?@action=redirect&bpo=30693]: The TarFile class now recurses directories in a reproducible way.

bpo-30693 [https://bugs.python.org/issue?@action=redirect&bpo=30693]: The ZipFile class now recurses directories in a reproducible way.

bpo-31680 [https://bugs.python.org/issue?@action=redirect&bpo=31680]: Added curses.ncurses_version.

bpo-31908 [https://bugs.python.org/issue?@action=redirect&bpo=31908]: Fix output of cover files for trace module command-line tool. Previously emitted cover files only when --missing option was used. Patch by Michael Selik.

bpo-31608 [https://bugs.python.org/issue?@action=redirect&bpo=31608]: Raise a TypeError instead of crashing if a collections.deque subclass returns a non-deque from __new__. Patch by Oren Milman.

bpo-31425 [https://bugs.python.org/issue?@action=redirect&bpo=31425]: Add support for sockets of the AF_QIPCRTR address family, supported by the Linux kernel. This is used to communicate with services, such as GPS or radio, running on Qualcomm devices. Patch by Bjorn Andersson.

bpo-22005 [https://bugs.python.org/issue?@action=redirect&bpo=22005]: Implemented unpickling instances of datetime, date and time pickled by Python 2. encoding='latin1' should be used for successful decoding.

bpo-27645 [https://bugs.python.org/issue?@action=redirect&bpo=27645]: sqlite3.Connection now exposes a backup method, if the underlying SQLite library is at version 3.6.11 or higher. Patch by Lele Gaifax.

bpo-16865 [https://bugs.python.org/issue?@action=redirect&bpo=16865]: Support arrays >=2GiB in ctypes. Patch by Segev Finer.

bpo-31508 [https://bugs.python.org/issue?@action=redirect&bpo=31508]: Removed support of arguments in tkinter.ttk.Treeview.selection. It was deprecated in 3.6. Use specialized methods like selection_set for changing the selection.

bpo-29456 [https://bugs.python.org/issue?@action=redirect&bpo=29456]: Fix bugs in hangul normalization: u1176, u11a7 and u11c3

Documentation

bpo-21257 [https://bugs.python.org/issue?@action=redirect&bpo=21257]: Document http.client.parse_headers().

bpo-34764 [https://bugs.python.org/issue?@action=redirect&bpo=34764]: Improve example of iter() with 2nd sentinel argument.

bpo-35564 [https://bugs.python.org/issue?@action=redirect&bpo=35564]: Explicitly set master_doc variable in conf.py for compliance with Sphinx 2.0

bpo-35511 [https://bugs.python.org/issue?@action=redirect&bpo=35511]: Specified that profile.Profile class doesn’t not support enable or disable methods. Also, elaborated that Profile object as a context manager is only supported in cProfile module.

bpo-10536 [https://bugs.python.org/issue?@action=redirect&bpo=10536]: Enhance the gettext docs. Patch by Éric Araujo

bpo-35089 [https://bugs.python.org/issue?@action=redirect&bpo=35089]: Remove mention of typing.io and typing.re. Their types should be imported from typing directly.

bpo-35038 [https://bugs.python.org/issue?@action=redirect&bpo=35038]: Fix the documentation about an unexisting f_restricted attribute in the frame object. Patch by Stéphane Wirtel

bpo-35042 [https://bugs.python.org/issue?@action=redirect&bpo=35042]: Replace PEP XYZ by the pep role and allow to use the direct links to the PEPs.

bpo-35044 [https://bugs.python.org/issue?@action=redirect&bpo=35044]: Fix the documentation with the role exc for the appropriated exception. Patch by Stéphane Wirtel

bpo-35035 [https://bugs.python.org/issue?@action=redirect&bpo=35035]: Rename documentation for email.utils to email.utils.rst.

bpo-34967 [https://bugs.python.org/issue?@action=redirect&bpo=34967]: Use app.add_object_type() instead of the deprecated Sphinx function app.description_unit()

bpo-34913 [https://bugs.python.org/issue?@action=redirect&bpo=34913]: Add documentation about the new command line interface of the gzip module.

bpo-32174 [https://bugs.python.org/issue?@action=redirect&bpo=32174]: chm document displays non-ASCII charaters properly on some MBCS Windows systems.

bpo-11233 [https://bugs.python.org/issue?@action=redirect&bpo=11233]: Create availability directive for documentation. Original patch by Georg Brandl.

bpo-34790 [https://bugs.python.org/issue?@action=redirect&bpo=34790]: Document how passing coroutines to asyncio.wait() can be confusing.

bpo-34552 [https://bugs.python.org/issue?@action=redirect&bpo=34552]: Make clear that == operator sometimes is equivalent to is. The <, <=, > and >= operators are only defined where they make sense.

bpo-28617 [https://bugs.python.org/issue?@action=redirect&bpo=28617]: Fixed info in the stdtypes docs concerning the types that support membership tests.

bpo-20177 [https://bugs.python.org/issue?@action=redirect&bpo=20177]: Migrate datetime.date.fromtimestamp to Argument Clinic. Patch by Tim Hoffmann.

bpo-34065 [https://bugs.python.org/issue?@action=redirect&bpo=34065]: Fix wrongly written basicConfig documentation markup syntax

bpo-33460 [https://bugs.python.org/issue?@action=redirect&bpo=33460]: replaced ellipsis with correct error codes in tutorial chapter 3.

bpo-33847 [https://bugs.python.org/issue?@action=redirect&bpo=33847]: Add “@” operator entry to index.

bpo-33409 [https://bugs.python.org/issue?@action=redirect&bpo=33409]: Clarified the relationship between PEP 538 [https://www.python.org/dev/peps/pep-0538]’s PYTHONCOERCECLOCALE and PEP 540’s PYTHONUTF8 mode.

bpo-33197 [https://bugs.python.org/issue?@action=redirect&bpo=33197]: Add versionadded tag to the documentation of ParameterKind.description

bpo-17045 [https://bugs.python.org/issue?@action=redirect&bpo=17045]: Improve the C-API doc for PyTypeObject. This includes adding several quick-reference tables and a lot of missing slot/typedef entries. The existing entries were also cleaned up with a slightly more consistent format.

bpo-33736 [https://bugs.python.org/issue?@action=redirect&bpo=33736]: Improve the documentation of asyncio.open_connection(), asyncio.start_server() and their UNIX socket counterparts.

bpo-23859 [https://bugs.python.org/issue?@action=redirect&bpo=23859]: Document that asyncio.wait() does not cancel its futures on timeout.

bpo-32436 [https://bugs.python.org/issue?@action=redirect&bpo=32436]: Document PEP 567 [https://www.python.org/dev/peps/pep-0567] changes to asyncio.

bpo-33604 [https://bugs.python.org/issue?@action=redirect&bpo=33604]: Update HMAC md5 default to a DeprecationWarning, bump removal to 3.8.

bpo-33594 [https://bugs.python.org/issue?@action=redirect&bpo=33594]: Document getargspec, from_function and from_builtin as deprecated in their respective docstring, and include version since deprecation in DeprecationWarning message.

bpo-33503 [https://bugs.python.org/issue?@action=redirect&bpo=33503]: Fix broken pypi link

bpo-33421 [https://bugs.python.org/issue?@action=redirect&bpo=33421]: Add missing documentation for typing.AsyncContextManager.

bpo-33487 [https://bugs.python.org/issue?@action=redirect&bpo=33487]: BZ2file now emit a DeprecationWarning when buffering=None is passed, the deprecation message and documentation also now explicitly state it is deprecated since 3.0.

bpo-33378 [https://bugs.python.org/issue?@action=redirect&bpo=33378]: Add Korean language switcher for https://docs.python.org/3/

bpo-33276 [https://bugs.python.org/issue?@action=redirect&bpo=33276]: Clarify that the __path__ attribute on modules cannot be just any value.

bpo-33201 [https://bugs.python.org/issue?@action=redirect&bpo=33201]: Modernize documentation for writing C extension types.

bpo-33195 [https://bugs.python.org/issue?@action=redirect&bpo=33195]: Deprecate Py_UNICODE usage in c-api/arg document. Py_UNICODE related APIs are deprecated since Python 3.3, but it is missed in the document.

bpo-33126 [https://bugs.python.org/issue?@action=redirect&bpo=33126]: Document PyBuffer_ToContiguous().

bpo-27212 [https://bugs.python.org/issue?@action=redirect&bpo=27212]: Modify documentation for the islice() recipe to consume initial values up to the start index.

bpo-28247 [https://bugs.python.org/issue?@action=redirect&bpo=28247]: Update zipapp documentation to describe how to make standalone applications.

bpo-18802 [https://bugs.python.org/issue?@action=redirect&bpo=18802]: Documentation changes for ipaddress. Patch by Jon Foster and Berker Peksag.

bpo-27428 [https://bugs.python.org/issue?@action=redirect&bpo=27428]: Update documentation to clarify that WindowsRegistryFinder implements MetaPathFinder. (Patch by Himanshu Lakhara)

bpo-28124 [https://bugs.python.org/issue?@action=redirect&bpo=28124]: The ssl module function ssl.wrap_socket() has been de-emphasized and deprecated in favor of the more secure and efficient SSLContext.wrap_socket() method.

bpo-17232 [https://bugs.python.org/issue?@action=redirect&bpo=17232]: Clarify docs for -O and -OO. Patch by Terry Reedy.

bpo-32436 [https://bugs.python.org/issue?@action=redirect&bpo=32436]: Add documentation for the contextvars module (PEP 567).

bpo-32800 [https://bugs.python.org/issue?@action=redirect&bpo=32800]: Update link to w3c doc for xml default namespaces.

bpo-11015 [https://bugs.python.org/issue?@action=redirect&bpo=11015]: Update test.support documentation.

bpo-32613 [https://bugs.python.org/issue?@action=redirect&bpo=32613]: Update the faq/windows.html to use the py command from PEP 397 instead of python.

bpo-8722 [https://bugs.python.org/issue?@action=redirect&bpo=8722]: Document __getattr__() behavior when property get() method raises AttributeError.

bpo-32614 [https://bugs.python.org/issue?@action=redirect&bpo=32614]: Modify RE examples in documentation to use raw strings to prevent DeprecationWarning and add text to REGEX HOWTO to highlight the deprecation.

bpo-20709 [https://bugs.python.org/issue?@action=redirect&bpo=20709]: Remove the paragraph where we explain that os.utime() does not support a directory as path under Windows. Patch by Jan-Philip Gehrcke

bpo-32722 [https://bugs.python.org/issue?@action=redirect&bpo=32722]: Remove the bad example in the tutorial of the Generator Expression. Patch by Stéphane Wirtel

bpo-31972 [https://bugs.python.org/issue?@action=redirect&bpo=31972]: Improve docstrings for pathlib.PurePath subclasses.

bpo-30607 [https://bugs.python.org/issue?@action=redirect&bpo=30607]: Use the externalized python-docs-theme package when building the documentation.

bpo-8243 [https://bugs.python.org/issue?@action=redirect&bpo=8243]: Add a note about curses.addch and curses.addstr exception behavior when writing outside a window, or pad.

bpo-32337 [https://bugs.python.org/issue?@action=redirect&bpo=32337]: Update documentation related with dict order.

bpo-25041 [https://bugs.python.org/issue?@action=redirect&bpo=25041]: Document AF_PACKET in the socket module.

bpo-31432 [https://bugs.python.org/issue?@action=redirect&bpo=31432]: Clarify meaning of CERT_NONE, CERT_OPTIONAL, and CERT_REQUIRED flags for ssl.SSLContext.verify_mode.

Tests

bpo-35772 [https://bugs.python.org/issue?@action=redirect&bpo=35772]: Fix sparse file tests of test_tarfile on ppc64 with the tmpfs filesystem. Fix the function testing if the filesystem supports sparse files: create a file which contains data and «holes», instead of creating a file which contains no data. tmpfs effective block size is a page size (tmpfs lives in the page cache). RHEL uses 64 KiB pages on aarch64, ppc64, ppc64le, only s390x and x86_64 use 4 KiB pages, whereas the test punch holes of 4 KiB.

bpo-35045 [https://bugs.python.org/issue?@action=redirect&bpo=35045]: Make ssl tests less strict and also accept TLSv1 as system default. The changes unbreaks test_min_max_version on Fedora 29.

bpo-32710 [https://bugs.python.org/issue?@action=redirect&bpo=32710]: test_asyncio/test_sendfile.py now resets the event loop policy using tearDownModule() as done in other tests, to prevent a warning when running tests on Windows.

bpo-33717 [https://bugs.python.org/issue?@action=redirect&bpo=33717]: test.pythoninfo now logs information of all clocks, not only time.time() and time.perf_counter().

bpo-35488 [https://bugs.python.org/issue?@action=redirect&bpo=35488]: Add a test to pathlib’s Path.match() to verify it does not support glob-style ** recursive pattern matching.

bpo-31731 [https://bugs.python.org/issue?@action=redirect&bpo=31731]: Fix a race condition in check_interrupted_write() of test_io: create directly the thread with SIGALRM signal blocked, rather than blocking the signal later from the thread. Previously, it was possible that the thread gets the signal before the signal is blocked.

bpo-35424 [https://bugs.python.org/issue?@action=redirect&bpo=35424]: Fix test_multiprocessing_main_handling: use multiprocessing.Pool with a context manager and then explicitly join the pool.

bpo-35519 [https://bugs.python.org/issue?@action=redirect&bpo=35519]: Rename test.bisect module to test.bisect_cmd to avoid conflict with bisect module when running directly a test like ./python Lib/test/test_xmlrpc.py.

bpo-35513 [https://bugs.python.org/issue?@action=redirect&bpo=35513]: Replace time.time() with time.monotonic() in tests to measure time delta.

bpo-34279 [https://bugs.python.org/issue?@action=redirect&bpo=34279]: test.support.run_unittest() no longer raise TestDidNotRun if the test result contains skipped tests. The exception is now only raised if no test have been run and no test have been skipped.

bpo-35412 [https://bugs.python.org/issue?@action=redirect&bpo=35412]: Add testcase to test_future4: check unicode literal.

bpo-26704 [https://bugs.python.org/issue?@action=redirect&bpo=26704]: Added test demonstrating double-patching of an instance method. Patch by Anthony Sottile.

bpo-33725 [https://bugs.python.org/issue?@action=redirect&bpo=33725]: test_multiprocessing_fork may crash on recent versions of macOS. Until the issue is resolved, skip the test on macOS.

bpo-35352 [https://bugs.python.org/issue?@action=redirect&bpo=35352]: Modify test_asyncio to use the certificate set from the test directory.

bpo-35317 [https://bugs.python.org/issue?@action=redirect&bpo=35317]: Fix mktime() overflow error in test_email: run test_localtime_daylight_true_dst_true() and test_localtime_daylight_false_dst_true() with a specific timezone.

bpo-21263 [https://bugs.python.org/issue?@action=redirect&bpo=21263]: After several reports that test_gdb does not work properly on macOS and since gdb is not shipped by default anymore, test_gdb is now skipped on macOS when LLVM Clang has been used to compile Python. Patch by Lysandros Nikolaou

bpo-34279 [https://bugs.python.org/issue?@action=redirect&bpo=34279]: regrtest issue a warning when no tests have been executed in a particular test file. Also, a new final result state is issued if no test have been executed across all test files. Patch by Pablo Galindo.

bpo-34962 [https://bugs.python.org/issue?@action=redirect&bpo=34962]: make docstest in Doc now passes., and is enforced in CI

bpo-23596 [https://bugs.python.org/issue?@action=redirect&bpo=23596]: Use argparse for the command line of the gzip module. Patch by Antony Lee

bpo-34537 [https://bugs.python.org/issue?@action=redirect&bpo=34537]: Fix test_gdb.test_strings() when LC_ALL=C and GDB was compiled with Python 3.6 or earlier.

bpo-34587 [https://bugs.python.org/issue?@action=redirect&bpo=34587]: test_socket: Remove RDSTest.testCongestion(). The test tries to fill the receiver’s socket buffer and expects an error. But the RDS protocol doesn’t require that. Moreover, the Linux implementation of RDS expects that the producer of the messages reduces its rate, it’s not the role of the receiver to trigger an error. The test fails on Fedora 28 by design, so just remove it.

bpo-34661 [https://bugs.python.org/issue?@action=redirect&bpo=34661]: Fix test_shutil if unzip doesn’t support -t.

bpo-34200 [https://bugs.python.org/issue?@action=redirect&bpo=34200]: Fixed non-deterministic flakiness of test_pkg by not using the scary test.support.module_cleanup() logic to save and restore sys.modules contents between test cases.

bpo-34569 [https://bugs.python.org/issue?@action=redirect&bpo=34569]: The experimental PEP 554 data channels now correctly pass negative PyLong objects between subinterpreters on 32-bit systems. Patch by Michael Felt.

bpo-34594 [https://bugs.python.org/issue?@action=redirect&bpo=34594]: Fix usage of hardcoded errno values in the tests.

bpo-34579 [https://bugs.python.org/issue?@action=redirect&bpo=34579]: Fix test_embed for AIX Patch by Michael Felt

bpo-34542 [https://bugs.python.org/issue?@action=redirect&bpo=34542]: Use 3072 RSA keys and SHA-256 signature for test certs and keys.

bpo-11193 [https://bugs.python.org/issue?@action=redirect&bpo=11193]: Remove special condition for AIX in test_subprocess.test_undecodable_env

bpo-34347 [https://bugs.python.org/issue?@action=redirect&bpo=34347]: Fix test_utf8_mode.test_cmd_line for AIX

bpo-34490 [https://bugs.python.org/issue?@action=redirect&bpo=34490]: On AIX with AF_UNIX family sockets getsockname() does not provide “sockname”, so skip calls to transport.get_extra_info(“sockname”)

bpo-34391 [https://bugs.python.org/issue?@action=redirect&bpo=34391]: Fix ftplib test for TLS 1.3 by reading from data socket.

bpo-11192 [https://bugs.python.org/issue?@action=redirect&bpo=11192]: Fix test_socket on AIX 6.1 and later IPv6 zone id supports only supported by inet_pton6_zone() Switch to runtime-based platform.system() to establish current platform rather than build-time based sys.platform()

bpo-34399 [https://bugs.python.org/issue?@action=redirect&bpo=34399]: Update all RSA keys and DH params to use at least 2048 bits.

bpo-34373 [https://bugs.python.org/issue?@action=redirect&bpo=34373]: Fix test_mktime and test_pthread_getcpuclickid tests for AIX Add range checking for _PyTime_localtime for AIX Patch by Michael Felt

bpo-11191 [https://bugs.python.org/issue?@action=redirect&bpo=11191]: Skip the distutils test “test_search_cpp” when using XLC as compiler patch by aixtools (Michael Felt)

Improved an error message when mock assert_has_calls fails.

bpo-33746 [https://bugs.python.org/issue?@action=redirect&bpo=33746]: Fix test_unittest when run in verbose mode.

bpo-33901 [https://bugs.python.org/issue?@action=redirect&bpo=33901]: Fix test_dbm_gnu on macOS with gdbm 1.15: add a larger value to make sure that the file size changes.

bpo-33873 [https://bugs.python.org/issue?@action=redirect&bpo=33873]: Fix a bug in regrtest that caused an extra test to run if –huntrleaks/-R was used. Exit with error in case that invalid parameters are specified to –huntrleaks/-R (at least one warmup run and one repetition must be used).

bpo-33562 [https://bugs.python.org/issue?@action=redirect&bpo=33562]: Check that a global asyncio event loop policy is not left behind by any tests.

bpo-33655 [https://bugs.python.org/issue?@action=redirect&bpo=33655]: Ignore test_posix_fallocate failures on BSD platforms that might be due to running on ZFS.

bpo-32962 [https://bugs.python.org/issue?@action=redirect&bpo=32962]: Fixed test_gdb when Python is compiled with flags -mcet -fcf-protection -O0.

bpo-33358 [https://bugs.python.org/issue?@action=redirect&bpo=33358]: Fix test_embed.test_pre_initialization_sys_options() when the interpreter is built with --enable-shared.

bpo-32872 [https://bugs.python.org/issue?@action=redirect&bpo=32872]: Avoid regrtest compatibility issue with namespace packages.

bpo-32517 [https://bugs.python.org/issue?@action=redirect&bpo=32517]: Fix failing test_asyncio on macOS 10.12.2+ due to transport of KqueueSelector loop was not being closed.

bpo-32663 [https://bugs.python.org/issue?@action=redirect&bpo=32663]: Making sure the SMTPUTF8SimTests class of tests gets run in test_smtplib.py.

bpo-27643 [https://bugs.python.org/issue?@action=redirect&bpo=27643]: Test_C test case needs «signed short» bitfields, but the IBM XLC compiler (on AIX) does not support this Skip the code and test when AIX and XLC are used

Applicable to Python2-2.7 and later

bpo-19417 [https://bugs.python.org/issue?@action=redirect&bpo=19417]: Add test_bdb.py.

bpo-31809 [https://bugs.python.org/issue?@action=redirect&bpo=31809]: Add tests to verify connection with secp ECDH curves.

Build

bpo-34691 [https://bugs.python.org/issue?@action=redirect&bpo=34691]: The _contextvars module is now built into the core Python library on Windows.

bpo-35683 [https://bugs.python.org/issue?@action=redirect&bpo=35683]: Improved Azure Pipelines build steps and now verifying layouts correctly

bpo-35642 [https://bugs.python.org/issue?@action=redirect&bpo=35642]: Remove asynciomodule.c from pythoncore.vcxproj

bpo-35550 [https://bugs.python.org/issue?@action=redirect&bpo=35550]: Fix incorrect Solaris #ifdef checks to look for __sun && __SVR4 instead of sun when compiling.

bpo-35499 [https://bugs.python.org/issue?@action=redirect&bpo=35499]: make profile-opt no longer replaces CFLAGS_NODIST with CFLAGS. It now adds profile-guided optimization (PGO) flags to CFLAGS_NODIST: existing CFLAGS_NODIST flags are kept.

bpo-35257 [https://bugs.python.org/issue?@action=redirect&bpo=35257]: Avoid leaking the linker flags from Link Time Optimizations (LTO) into distutils when compiling C extensions.

bpo-35351 [https://bugs.python.org/issue?@action=redirect&bpo=35351]: When building Python with clang and LTO, LTO flags are no longer passed into CFLAGS to build third-party C extensions through distutils.

bpo-35139 [https://bugs.python.org/issue?@action=redirect&bpo=35139]: Fix a compiler error when statically linking pyexpat in Modules/Setup.

bpo-35059 [https://bugs.python.org/issue?@action=redirect&bpo=35059]: PCbuild: Set InlineFunctionExpansion to OnlyExplicitInline («/Ob1» option) in pyproject.props in Debug mode to expand functions marked as inline. This change should make Python compiled in Debug mode a little bit faster on Windows.

bpo-35011 [https://bugs.python.org/issue?@action=redirect&bpo=35011]: Restores the use of pyexpatns.h to isolate our embedded copy of the expat C library so that its symbols do not conflict at link or dynamic loading time with an embedding application or other extension modules with their own version of libexpat.

bpo-28015 [https://bugs.python.org/issue?@action=redirect&bpo=28015]: Have –with-lto works correctly with clang.

bpo-34765 [https://bugs.python.org/issue?@action=redirect&bpo=34765]: Update the outdated install-sh file to the latest revision from automake v1.16.1

bpo-34585 [https://bugs.python.org/issue?@action=redirect&bpo=34585]: Check for floating-point byte order in configure.ac using compilation tests instead of executing code, so that these checks work in cross-compiled builds.

bpo-34710 [https://bugs.python.org/issue?@action=redirect&bpo=34710]: Fixed SSL module build with OpenSSL & pedantic CFLAGS.

bpo-34582 [https://bugs.python.org/issue?@action=redirect&bpo=34582]: Add JUnit XML output for regression tests and update Azure DevOps builds.

bpo-34081 [https://bugs.python.org/issue?@action=redirect&bpo=34081]: Make Sphinx warnings as errors in the Docs Makefile.

bpo-34555 [https://bugs.python.org/issue?@action=redirect&bpo=34555]: Fix for case where it was not possible to have both HAVE_LINUX_VM_SOCKETS_H and HAVE_SOCKADDR_ALG be undefined.

bpo-33015 [https://bugs.python.org/issue?@action=redirect&bpo=33015]: Fix an undefined behaviour in the pthread implementation of PyThread_start_new_thread(): add a function wrapper to always return NULL.

bpo-34245 [https://bugs.python.org/issue?@action=redirect&bpo=34245]: The Python shared library is now installed with write permission (mode 0755), which is the standard way of installing such libraries.

bpo-34121 [https://bugs.python.org/issue?@action=redirect&bpo=34121]: Fix detection of C11 atomic support on clang.

bpo-32430 [https://bugs.python.org/issue?@action=redirect&bpo=32430]: Rename Modules/Setup.dist to Modules/Setup, and remove the necessity to copy the former manually to the latter when updating the local source tree.

bpo-30345 [https://bugs.python.org/issue?@action=redirect&bpo=30345]: Add -g to LDFLAGS when compiling with LTO to get debug symbols.

bpo-5755 [https://bugs.python.org/issue?@action=redirect&bpo=5755]: Move -Wstrict-prototypes option to CFLAGS_NODIST from OPT. This option emitted annoying warnings when building extension modules written in C++.

bpo-33614 [https://bugs.python.org/issue?@action=redirect&bpo=33614]: Ensures module definition files for the stable ABI on Windows are correctly regenerated.

bpo-33648 [https://bugs.python.org/issue?@action=redirect&bpo=33648]: The –with-c-locale-warning configuration flag has been removed. It has had no effect for about a year.

bpo-33522 [https://bugs.python.org/issue?@action=redirect&bpo=33522]: Enable CI builds on Visual Studio Team Services at https://python.visualstudio.com/cpython

bpo-33512 [https://bugs.python.org/issue?@action=redirect&bpo=33512]: configure’s check for «long double» has been simplified

bpo-33483 [https://bugs.python.org/issue?@action=redirect&bpo=33483]: C compiler is now correctly detected from the standard environment variables. –without-gcc and –with-icc options have been removed.

bpo-33394 [https://bugs.python.org/issue?@action=redirect&bpo=33394]: Enable the verbose build for extension modules, when GNU make is passed macros on the command line.

bpo-33393 [https://bugs.python.org/issue?@action=redirect&bpo=33393]: Update config.guess and config.sub files.

bpo-33377 [https://bugs.python.org/issue?@action=redirect&bpo=33377]: Add new triplets for mips r6 and riscv variants (used in extension suffixes).

bpo-32232 [https://bugs.python.org/issue?@action=redirect&bpo=32232]: By default, modules configured in Modules/Setup are no longer built with -DPy_BUILD_CORE. Instead, modules that specifically need that preprocessor definition include it in their individual entries.

bpo-33182 [https://bugs.python.org/issue?@action=redirect&bpo=33182]: The embedding tests can once again be built with clang 6.0

bpo-33163 [https://bugs.python.org/issue?@action=redirect&bpo=33163]: Upgrade pip to 9.0.3 and setuptools to v39.0.1.

bpo-33012 [https://bugs.python.org/issue?@action=redirect&bpo=33012]: gcc 8 has added a new warning heuristic to detect invalid function casts and a stock python build seems to hit that warning quite often. The most common is the cast of a METH_NOARGS function (that uses just one argument) to a PyCFunction. Fix this by adding a dummy argument to all functions that implement METH_NOARGS.

bpo-32898 [https://bugs.python.org/issue?@action=redirect&bpo=32898]: Fix the python debug build when using COUNT_ALLOCS.

bpo-29442 [https://bugs.python.org/issue?@action=redirect&bpo=29442]: Replace optparse with argparse in setup.py

Windows

bpo-35890 [https://bugs.python.org/issue?@action=redirect&bpo=35890]: Fix API calling consistency of GetVersionEx and wcstok.

bpo-32560 [https://bugs.python.org/issue?@action=redirect&bpo=32560]: The py launcher now forwards its STARTUPINFO structure to child processes.

bpo-35854 [https://bugs.python.org/issue?@action=redirect&bpo=35854]: Fix EnvBuilder and –symlinks in venv on Windows

bpo-35811 [https://bugs.python.org/issue?@action=redirect&bpo=35811]: Avoid propagating venv settings when launching via py.exe

bpo-35797 [https://bugs.python.org/issue?@action=redirect&bpo=35797]: Fix default executable used by the multiprocessing module

bpo-35758 [https://bugs.python.org/issue?@action=redirect&bpo=35758]: Allow building on ARM with MSVC.

bpo-29734 [https://bugs.python.org/issue?@action=redirect&bpo=29734]: Fix handle leaks in os.stat on Windows.

bpo-35596 [https://bugs.python.org/issue?@action=redirect&bpo=35596]: Use unchecked PYCs for the embeddable distro to avoid zipimport restrictions.

bpo-35596 [https://bugs.python.org/issue?@action=redirect&bpo=35596]: Fix vcruntime140.dll being added to embeddable distro multiple times.

bpo-35402 [https://bugs.python.org/issue?@action=redirect&bpo=35402]: Update Windows build to use Tcl and Tk 8.6.9

bpo-35401 [https://bugs.python.org/issue?@action=redirect&bpo=35401]: Updates Windows build to OpenSSL 1.1.0j

bpo-34977 [https://bugs.python.org/issue?@action=redirect&bpo=34977]: venv on Windows will now use a python.exe redirector rather than copying the actual binaries from the base environment.

bpo-34977 [https://bugs.python.org/issue?@action=redirect&bpo=34977]: Adds support for building a Windows App Store package

bpo-35067 [https://bugs.python.org/issue?@action=redirect&bpo=35067]: Remove _distutils_findvs module and use vswhere.exe instead.

bpo-32557 [https://bugs.python.org/issue?@action=redirect&bpo=32557]: Allow shutil.disk_usage to take a file path on Windows

bpo-34770 [https://bugs.python.org/issue?@action=redirect&bpo=34770]: Fix a possible null pointer dereference in pyshellext.cpp.

bpo-34603 [https://bugs.python.org/issue?@action=redirect&bpo=34603]: Fix returning structs from functions produced by MSVC

bpo-34581 [https://bugs.python.org/issue?@action=redirect&bpo=34581]: Guard MSVC-specific code in socketmodule.c with #ifdef _MSC_VER.

bpo-34532 [https://bugs.python.org/issue?@action=redirect&bpo=34532]: Fixes exit code of list version arguments for py.exe.

bpo-34062 [https://bugs.python.org/issue?@action=redirect&bpo=34062]: Fixed the “–list” and “–list-paths” arguments for the py.exe launcher

bpo-34225 [https://bugs.python.org/issue?@action=redirect&bpo=34225]: Ensure INCLUDE and LIB directories do not end with a backslash.

bpo-34011 [https://bugs.python.org/issue?@action=redirect&bpo=34011]: A suite of code has been changed which copied across DLLs and init.tcl from the running Python location into a venv being created. These copies are needed only when running from a Python source build, and the copying code is now only run when that is the case, rather than whenever a venv is created.

bpo-34006 [https://bugs.python.org/issue?@action=redirect&bpo=34006]: Revert line length limit for Windows help docs. The line-length limit is not needed because the pages appear in a separate app rather than on a browser tab. It can also interact badly with the DPI setting.

bpo-31546 [https://bugs.python.org/issue?@action=redirect&bpo=31546]: Restore running PyOS_InputHook while waiting for user input at the prompt. The restores integration of interactive GUI windows (such as Matplotlib figures) with the prompt on Windows.

bpo-30237 [https://bugs.python.org/issue?@action=redirect&bpo=30237]: Output error when ReadConsole is canceled by CancelSynchronousIo instead of crashing.

bpo-33895 [https://bugs.python.org/issue?@action=redirect&bpo=33895]: GIL is released while calling functions that acquire Windows loader lock.

bpo-33720 [https://bugs.python.org/issue?@action=redirect&bpo=33720]: Reduces maximum marshal recursion depth on release builds.

bpo-29097 [https://bugs.python.org/issue?@action=redirect&bpo=29097]: Fix bug where datetime.fromtimestamp() erroneously throws an OSError on Windows for values between 0 and 86400. Patch by Ammar Askar.

bpo-33316 [https://bugs.python.org/issue?@action=redirect&bpo=33316]: PyThread_release_lock always fails

bpo-33184 [https://bugs.python.org/issue?@action=redirect&bpo=33184]: Update Windows installer to use OpenSSL 1.1.0h.

bpo-32890 [https://bugs.python.org/issue?@action=redirect&bpo=32890]: Fix usage of GetLastError() instead of errno in os.execve() and os.truncate().

bpo-33016 [https://bugs.python.org/issue?@action=redirect&bpo=33016]: Fix potential use of uninitialized memory in nt._getfinalpathname

bpo-32903 [https://bugs.python.org/issue?@action=redirect&bpo=32903]: Fix a memory leak in os.chdir() on Windows if the current directory is set to a UNC path.

bpo-32901 [https://bugs.python.org/issue?@action=redirect&bpo=32901]: Update Tcl and Tk versions to 8.6.8

bpo-31966 [https://bugs.python.org/issue?@action=redirect&bpo=31966]: Fixed WindowsConsoleIO.write() for writing empty data.

bpo-32409 [https://bugs.python.org/issue?@action=redirect&bpo=32409]: Ensures activate.bat can handle Unicode contents.

bpo-32457 [https://bugs.python.org/issue?@action=redirect&bpo=32457]: Improves handling of denormalized executable path when launching Python.

bpo-32370 [https://bugs.python.org/issue?@action=redirect&bpo=32370]: Use the correct encoding for ipconfig output in the uuid module. Patch by Segev Finer.

bpo-29248 [https://bugs.python.org/issue?@action=redirect&bpo=29248]: Fix os.readlink() on Windows, which was mistakenly treating the PrintNameOffset field of the reparse data buffer as a number of characters instead of bytes. Patch by Craig Holmquist and SSE4.

bpo-1104 [https://bugs.python.org/issue?@action=redirect&bpo=1104]: Correctly handle string length in msilib.SummaryInfo.GetProperty() to prevent it from truncating the last character.

macOS

bpo-35401 [https://bugs.python.org/issue?@action=redirect&bpo=35401]: Update macOS installer to use OpenSSL 1.1.0j.

bpo-35025 [https://bugs.python.org/issue?@action=redirect&bpo=35025]: Properly guard the use of the CLOCK_GETTIME et al. macros in timemodule on macOS.

bpo-24658 [https://bugs.python.org/issue?@action=redirect&bpo=24658]: On macOS, fix reading from and writing into a file with a size larger than 2 GiB.

bpo-34405 [https://bugs.python.org/issue?@action=redirect&bpo=34405]: Update to OpenSSL 1.1.0i for macOS installer builds.

bpo-33635 [https://bugs.python.org/issue?@action=redirect&bpo=33635]: In macOS stat on some file descriptors (/dev/fd/3 f.e) will result in bad file descriptor OSError. Guard against this exception was added in is_dir, is_file and similar methods. DirEntry.is_dir can also throw this exception so _RecursiveWildcardSelector._iterate_directories was also extended with the same error ignoring pattern.

bpo-13631 [https://bugs.python.org/issue?@action=redirect&bpo=13631]: The .editrc file in user’s home directory is now processed correctly during the readline initialization through editline emulation on macOS.

bpo-33184 [https://bugs.python.org/issue?@action=redirect&bpo=33184]: Update macOS installer build to use OpenSSL 1.1.0h.

bpo-32726 [https://bugs.python.org/issue?@action=redirect&bpo=32726]: Build and link with private copy of Tcl/Tk 8.6 for the macOS 10.6+ installer. The 10.9+ installer variant already does this. This means that the Python 3.7 provided by the python.org macOS installers no longer need or use any external versions of Tcl/Tk, either system-provided or user-installed, such as ActiveTcl.

bpo-32901 [https://bugs.python.org/issue?@action=redirect&bpo=32901]: Update macOS 10.9+ installer to Tcl/Tk 8.6.8.

bpo-31903 [https://bugs.python.org/issue?@action=redirect&bpo=31903]: In _scproxy, drop the GIL when calling into SystemConfiguration to avoid deadlocks.

IDLE

bpo-35770 [https://bugs.python.org/issue?@action=redirect&bpo=35770]: IDLE macosx deletes Options => Configure IDLE. It previously deleted Window => Zoom Height by mistake. (Zoom Height is now on the Options menu). On Mac, the settings dialog is accessed via Preferences on the IDLE menu.

bpo-35769 [https://bugs.python.org/issue?@action=redirect&bpo=35769]: Change IDLE’s new file name from “Untitled” to “untitled”

bpo-35660 [https://bugs.python.org/issue?@action=redirect&bpo=35660]: Fix imports in idlelib.window.

bpo-35641 [https://bugs.python.org/issue?@action=redirect&bpo=35641]: Proper format calltip when the function has no docstring.

bpo-33987 [https://bugs.python.org/issue?@action=redirect&bpo=33987]: Use ttk Frame for ttk widgets.

bpo-34055 [https://bugs.python.org/issue?@action=redirect&bpo=34055]: Fix erroneous “smart” indents and newlines in IDLE Shell.

bpo-35591 [https://bugs.python.org/issue?@action=redirect&bpo=35591]: Find Selection now works when selection not found.

bpo-35196 [https://bugs.python.org/issue?@action=redirect&bpo=35196]: Speed up squeezer line counting.

bpo-35598 [https://bugs.python.org/issue?@action=redirect&bpo=35598]: Update config_key: use PEP 8 names and ttk widgets, make some objects global, and add tests.

bpo-28097 [https://bugs.python.org/issue?@action=redirect&bpo=28097]: Add Previous/Next History entries to Shell menu.

bpo-35208 [https://bugs.python.org/issue?@action=redirect&bpo=35208]: Squeezer now properly counts wrapped lines before newlines.

bpo-35555 [https://bugs.python.org/issue?@action=redirect&bpo=35555]: Gray out Code Context menu entry when it’s not applicable.

bpo-35521 [https://bugs.python.org/issue?@action=redirect&bpo=35521]: Document the IDLE editor code context feature. Add some internal references within the IDLE doc.

bpo-22703 [https://bugs.python.org/issue?@action=redirect&bpo=22703]: The Code Context menu label now toggles between Show/Hide Code Context. The Zoom Height menu now toggles between Zoom/Restore Height. Zoom Height has moved from the Window menu to the Options menu.

bpo-35213 [https://bugs.python.org/issue?@action=redirect&bpo=35213]: Where appropriate, use “macOS” in idlelib.

bpo-34864 [https://bugs.python.org/issue?@action=redirect&bpo=34864]: On macOS, warn if the system preference «Prefer tabs when opening documents» is set to «Always».

bpo-34864 [https://bugs.python.org/issue?@action=redirect&bpo=34864]: Document two IDLE on MacOS issues. The System Preferences Dock «prefer tabs always» setting disables some IDLE features. Menus are a bit different than as described for Windows and Linux.

bpo-35202 [https://bugs.python.org/issue?@action=redirect&bpo=35202]: Remove unused imports from lib/idlelib

bpo-33000 [https://bugs.python.org/issue?@action=redirect&bpo=33000]: Document that IDLE’s shell has no line limit. A program that runs indefinitely can overfill memory.

bpo-23220 [https://bugs.python.org/issue?@action=redirect&bpo=23220]: Explain how IDLE’s Shell displays output.

bpo-35099 [https://bugs.python.org/issue?@action=redirect&bpo=35099]: Improve the doc about IDLE running user code. The section is renamed from «IDLE – console differences» is renamed «Running user code». It mostly covers the implications of using custom sys.stdxxx objects.

bpo-35097 [https://bugs.python.org/issue?@action=redirect&bpo=35097]: Add IDLE doc subsection explaining editor windows. Topics include opening, title and status bar, .py* extension, and running.

bpo-35093 [https://bugs.python.org/issue?@action=redirect&bpo=35093]: Document the IDLE document viewer in the IDLE doc. Add a paragraph in «Help and preferences», «Help sources» subsection.

bpo-35088 [https://bugs.python.org/issue?@action=redirect&bpo=35088]: Update idlelib.help.copy_string docstring. We now use git and backporting instead of hg and forward merging.

bpo-35087 [https://bugs.python.org/issue?@action=redirect&bpo=35087]: Update idlelib help files for the current doc build. The main change is the elimination of chapter-section numbers.

bpo-34548 [https://bugs.python.org/issue?@action=redirect&bpo=34548]: Use configured color theme for read-only text views.

bpo-1529353 [https://bugs.python.org/issue?@action=redirect&bpo=1529353]: Enable «squeezing» of long outputs in the shell, to avoid performance degradation and to clean up the history without losing it. Squeezed outputs may be copied, viewed in a separate window, and «unsqueezed».

bpo-34047 [https://bugs.python.org/issue?@action=redirect&bpo=34047]: Fixed mousewheel scrolling direction on macOS.

bpo-34275 [https://bugs.python.org/issue?@action=redirect&bpo=34275]: Make IDLE calltips always visible on Mac. Some MacOS-tk combinations need .update_idletasks(). Patch by Kevin Walzer.

bpo-34120 [https://bugs.python.org/issue?@action=redirect&bpo=34120]: Fix unresponsiveness after closing certain windows and dialogs.

bpo-33975 [https://bugs.python.org/issue?@action=redirect&bpo=33975]: Avoid small type when running htests. Since part of the purpose of human-viewed tests is to determine that widgets look right, it is important that they look the same for testing as when running IDLE.

bpo-33905 [https://bugs.python.org/issue?@action=redirect&bpo=33905]: Add test for idlelib.stackview.StackBrowser.

bpo-33924 [https://bugs.python.org/issue?@action=redirect&bpo=33924]: Change mainmenu.menudefs key “windows” to “window”. Every other menudef key is lowercase version of main menu entry.

bpo-33906 [https://bugs.python.org/issue?@action=redirect&bpo=33906]: Rename idlelib.windows as window Match Window on the main menu and remove last plural module name.

bpo-33917 [https://bugs.python.org/issue?@action=redirect&bpo=33917]: Fix and document idlelib/idle_test/template.py. The revised file compiles, runs, and tests OK. idle_test/README.txt explains how to use it to create new IDLE test files.

bpo-33904 [https://bugs.python.org/issue?@action=redirect&bpo=33904]: IDLE: In rstrip, rename class RstripExtension as Rstrip

bpo-33907 [https://bugs.python.org/issue?@action=redirect&bpo=33907]: For consistency and clarity, rename an IDLE module and classes. Module calltips and its class CallTips are now calltip and Calltip. In module calltip_w, class CallTip is now CalltipWindow.

bpo-33856 [https://bugs.python.org/issue?@action=redirect&bpo=33856]: Add «help» in the welcome message of IDLE

bpo-33839 [https://bugs.python.org/issue?@action=redirect&bpo=33839]: IDLE: refactor ToolTip and CallTip and add documentation and tests

bpo-33855 [https://bugs.python.org/issue?@action=redirect&bpo=33855]: Minimally test all IDLE modules. Add missing files, import module, instantiate classes, and check coverage. Check existing files.

bpo-33656 [https://bugs.python.org/issue?@action=redirect&bpo=33656]: On Windows, add API call saying that tk scales for DPI. On Windows 8.1+ or 10, with DPI compatibility properties of the Python binary unchanged, and a monitor resolution greater than 96 DPI, this should make text and lines sharper. It should otherwise have no effect.

bpo-33768 [https://bugs.python.org/issue?@action=redirect&bpo=33768]: Clicking on a context line moves that line to the top of the editor window.

bpo-33763 [https://bugs.python.org/issue?@action=redirect&bpo=33763]: IDLE: Use read-only text widget for code context instead of label widget.

bpo-33664 [https://bugs.python.org/issue?@action=redirect&bpo=33664]: Scroll IDLE editor text by lines. Previously, the mouse wheel and scrollbar slider moved text by a fixed number of pixels, resulting in partial lines at the top of the editor box. The change also applies to the shell and grep output windows, but not to read-only text views.

bpo-33679 [https://bugs.python.org/issue?@action=redirect&bpo=33679]: Enable theme-specific color configuration for Code Context. Use the Highlights tab to see the setting for built-in themes or add settings to custom themes.

bpo-33642 [https://bugs.python.org/issue?@action=redirect&bpo=33642]: Display up to maxlines non-blank lines for Code Context. If there is no current context, show a single blank line.

bpo-33628 [https://bugs.python.org/issue?@action=redirect&bpo=33628]: IDLE: Cleanup codecontext.py and its test.

bpo-33564 [https://bugs.python.org/issue?@action=redirect&bpo=33564]: IDLE’s code context now recognizes async as a block opener.

bpo-21474 [https://bugs.python.org/issue?@action=redirect&bpo=21474]: Update word/identifier definition from ascii to unicode. In text and entry boxes, this affects selection by double-click, movement left/right by control-left/right, and deletion left/right by control-BACKSPACE/DEL.

bpo-33204 [https://bugs.python.org/issue?@action=redirect&bpo=33204]: IDLE: consistently color invalid string prefixes. A “u” string prefix cannot be paired with either “r” or “f”. Consistently color as much of the prefix, starting at the right, as is valid. Revise and extend colorizer test.

bpo-32984 [https://bugs.python.org/issue?@action=redirect&bpo=32984]: Set __file__ while running a startup file. Like Python, IDLE optionally runs one startup file in the Shell window before presenting the first interactive input prompt. For IDLE, -s runs a file named in environmental variable IDLESTARTUP or PYTHONSTARTUP; -r file runs file. Python sets __file__ to the startup file name before running the file and unsets it before the first prompt. IDLE now does the same when run normally, without the -n option.

bpo-32940 [https://bugs.python.org/issue?@action=redirect&bpo=32940]: Simplify and rename StringTranslatePseudoMapping in pyparse.

bpo-32916 [https://bugs.python.org/issue?@action=redirect&bpo=32916]: Change str to code in pyparse.

bpo-32905 [https://bugs.python.org/issue?@action=redirect&bpo=32905]: Remove unused code in pyparse module.

bpo-32874 [https://bugs.python.org/issue?@action=redirect&bpo=32874]: Add tests for pyparse.

bpo-32837 [https://bugs.python.org/issue?@action=redirect&bpo=32837]: Using the system and place-dependent default encoding for open() is a bad idea for IDLE’s system and location-independent files.

bpo-32826 [https://bugs.python.org/issue?@action=redirect&bpo=32826]: Add «encoding=utf-8» to open() in IDLE’s test_help_about. GUI test test_file_buttons() only looks at initial ascii-only lines, but failed on systems where open() defaults to “ascii” because readline() internally reads and decodes far enough ahead to encounter a non-ascii character in CREDITS.txt.

bpo-32831 [https://bugs.python.org/issue?@action=redirect&bpo=32831]: Add docstrings and tests for codecontext.

bpo-32765 [https://bugs.python.org/issue?@action=redirect&bpo=32765]: Update configdialog General tab docstring to add new widgets to the widget list.

Tools/Demos

bpo-35884 [https://bugs.python.org/issue?@action=redirect&bpo=35884]: Add a benchmark script for timing various ways to access variables: Tools/scripts/var_access_benchmark.py.

bpo-34989 [https://bugs.python.org/issue?@action=redirect&bpo=34989]: python-gdb.py now handles errors on computing the line number of a Python frame.

bpo-20260 [https://bugs.python.org/issue?@action=redirect&bpo=20260]: Argument Clinic now has non-bitwise unsigned int converters.

bpo-32962 [https://bugs.python.org/issue?@action=redirect&bpo=32962]: python-gdb now catches UnicodeDecodeError exceptions when calling string().

bpo-32962 [https://bugs.python.org/issue?@action=redirect&bpo=32962]: python-gdb now catches ValueError on read_var(): when Python has no debug symbols for example.

bpo-33189 [https://bugs.python.org/issue?@action=redirect&bpo=33189]: pygettext.py now recognizes only literal strings as docstrings and translatable strings, and rejects bytes literals and f-string expressions.

bpo-31920 [https://bugs.python.org/issue?@action=redirect&bpo=31920]: Fixed handling directories as arguments in the pygettext script. Based on patch by Oleg Krasnikov.

bpo-29673 [https://bugs.python.org/issue?@action=redirect&bpo=29673]: Fix pystackv and pystack gdbinit macros.

bpo-25427 [https://bugs.python.org/issue?@action=redirect&bpo=25427]: Remove the pyvenv script in favor of python3 -m venv in order to lower confusion as to what Python interpreter a virtual environment will be created for.

bpo-32885 [https://bugs.python.org/issue?@action=redirect&bpo=32885]: Add an -n flag for Tools/scripts/pathfix.py to disable automatic backup creation (files with ~ suffix).

bpo-32222 [https://bugs.python.org/issue?@action=redirect&bpo=32222]: Fix pygettext not extracting docstrings for functions with type annotated arguments. Patch by Toby Harradine.

bpo-31583 [https://bugs.python.org/issue?@action=redirect&bpo=31583]: Fix 2to3 for using with –add-suffix option but without –output-dir option for relative path to files in current directory.

C API

bpo-35713 [https://bugs.python.org/issue?@action=redirect&bpo=35713]: The PyByteArray_Init() and PyByteArray_Fini() functions have been removed. They did nothing since Python 2.7.4 and Python 3.2.0, were excluded from the limited API (stable ABI), and were not documented.

bpo-33817 [https://bugs.python.org/issue?@action=redirect&bpo=33817]: Fixed _PyBytes_Resize() for empty bytes objects.

bpo-35322 [https://bugs.python.org/issue?@action=redirect&bpo=35322]: Fix memory leak in PyUnicode_EncodeLocale() and PyUnicode_EncodeFSDefault() on error handling.

bpo-35059 [https://bugs.python.org/issue?@action=redirect&bpo=35059]: The following C macros have been converted to static inline functions: Py_INCREF(), Py_DECREF(), Py_XINCREF(), Py_XDECREF(), PyObject_INIT(), PyObject_INIT_VAR().

bpo-35296 [https://bugs.python.org/issue?@action=redirect&bpo=35296]: make install now also installs the internal API: Include/internal/*.h header files.

bpo-35081 [https://bugs.python.org/issue?@action=redirect&bpo=35081]: Internal APIs surrounded by #ifdef Py_BUILD_CORE have been moved from Include/*.h headers to new header files Include/internal/pycore_*.h.

bpo-35259 [https://bugs.python.org/issue?@action=redirect&bpo=35259]: Conditionally declare Py_FinalizeEx() (new in 3.6) based on Py_LIMITED_API. Patch by Arthur Neufeld.

bpo-35081 [https://bugs.python.org/issue?@action=redirect&bpo=35081]: The _PyObject_GC_TRACK() and _PyObject_GC_UNTRACK() macros have been removed from the public C API.

bpo-35134 [https://bugs.python.org/issue?@action=redirect&bpo=35134]: Creation of a new Include/cpython/ subdirectory.

bpo-34725 [https://bugs.python.org/issue?@action=redirect&bpo=34725]: Adds _Py_SetProgramFullPath so embedders may override sys.executable

bpo-34910 [https://bugs.python.org/issue?@action=redirect&bpo=34910]: Ensure that PyObject_Print() always returns -1 on error. Patch by Zackery Spytz.

bpo-34523 [https://bugs.python.org/issue?@action=redirect&bpo=34523]: Py_DecodeLocale() and Py_EncodeLocale() now use the UTF-8 encoding on Windows if Py_LegacyWindowsFSEncodingFlag is zero.

bpo-34193 [https://bugs.python.org/issue?@action=redirect&bpo=34193]: Fix pluralization in TypeError messages in getargs.c and typeobject.c: “1 argument” instead of “1 arguments” and “1 element” instead of “1 elements”.

bpo-34127 [https://bugs.python.org/issue?@action=redirect&bpo=34127]: Return grammatically correct error message based on argument count. Patch by Karthikeyan Singaravelan.

bpo-23927 [https://bugs.python.org/issue?@action=redirect&bpo=23927]: Fixed SystemError in PyArg_ParseTupleAndKeywords() when the w* format unit is used for optional parameter.

bpo-32455 [https://bugs.python.org/issue?@action=redirect&bpo=32455]: Added PyCompile_OpcodeStackEffectWithJump().

bpo-34008 [https://bugs.python.org/issue?@action=redirect&bpo=34008]: Py_Main() can again be called after Py_Initialize(), as in Python 3.6.

bpo-32500 [https://bugs.python.org/issue?@action=redirect&bpo=32500]: Fixed error messages for PySequence_Size(), PySequence_GetItem(), PySequence_SetItem() and PySequence_DelItem() called with a mapping and PyMapping_Size() called with a sequence.

bpo-33818 [https://bugs.python.org/issue?@action=redirect&bpo=33818]: PyExceptionClass_Name() will now return const char * instead of char *.

bpo-33042 [https://bugs.python.org/issue?@action=redirect&bpo=33042]: Embedding applications may once again call PySys_ResetWarnOptions, PySys_AddWarnOption, and PySys_AddXOption prior to calling Py_Initialize.

bpo-32374 [https://bugs.python.org/issue?@action=redirect&bpo=32374]: Document that m_traverse for multi-phase initialized modules can be called with m_state=NULL, and add a sanity check

bpo-30863 [https://bugs.python.org/issue?@action=redirect&bpo=30863]: PyUnicode_AsWideChar() and PyUnicode_AsWideCharString() no longer cache the wchar_t* representation of string objects.

Python 3.7.0 final

Release date: 2018-06-27

Library

bpo-33851 [https://bugs.python.org/issue?@action=redirect&bpo=33851]: Fix ast.get_docstring() for a node that lacks a docstring.

C API

bpo-33932 [https://bugs.python.org/issue?@action=redirect&bpo=33932]: Calling Py_Initialize() twice does nothing, instead of failing with a fatal error: restore the Python 3.6 behaviour.

Python 3.7.0 release candidate 1

Release date: 2018-06-12

Core and Builtins

bpo-33803 [https://bugs.python.org/issue?@action=redirect&bpo=33803]: Fix a crash in hamt.c caused by enabling GC tracking for an object that hadn’t all of its fields set to NULL.

bpo-33706 [https://bugs.python.org/issue?@action=redirect&bpo=33706]: Fix a crash in Python initialization when parsing the command line options. Thanks Christoph Gohlke for the bug report and the fix!

bpo-30654 [https://bugs.python.org/issue?@action=redirect&bpo=30654]: Fixed reset of the SIGINT handler to SIG_DFL on interpreter shutdown even when there was a custom handler set previously. Patch by Philipp Kerling.

bpo-31849 [https://bugs.python.org/issue?@action=redirect&bpo=31849]: Fix signed/unsigned comparison warning in pyhash.c.

Library

bpo-30167 [https://bugs.python.org/issue?@action=redirect&bpo=30167]: Prevent site.main() exception if PYTHONSTARTUP is set. Patch by Steve Weber.

bpo-33812 [https://bugs.python.org/issue?@action=redirect&bpo=33812]: Datetime instance d with non-None tzinfo, but with d.tzinfo.utcoffset(d) returning None is now treated as naive by the astimezone() method.

bpo-30805 [https://bugs.python.org/issue?@action=redirect&bpo=30805]: Avoid race condition with debug logging

bpo-33694 [https://bugs.python.org/issue?@action=redirect&bpo=33694]: asyncio: Fix a race condition causing data loss on pause_reading()/resume_reading() when using the ProactorEventLoop.

bpo-32493 [https://bugs.python.org/issue?@action=redirect&bpo=32493]: Correct test for uuid_enc_be availability in configure.ac. Patch by Michael Felt.

bpo-33792 [https://bugs.python.org/issue?@action=redirect&bpo=33792]: Add asyncio.WindowsSelectorEventLoopPolicy and asyncio.WindowsProactorEventLoopPolicy.

bpo-33778 [https://bugs.python.org/issue?@action=redirect&bpo=33778]: Update unicodedata’s database to Unicode version 11.0.0.

bpo-33770 [https://bugs.python.org/issue?@action=redirect&bpo=33770]: improve base64 exception message for encoded inputs of invalid length

bpo-33769 [https://bugs.python.org/issue?@action=redirect&bpo=33769]: asyncio/start_tls: Fix error message; cancel callbacks in case of an unhandled error; mark SSLTransport as closed if it is aborted.

bpo-33767 [https://bugs.python.org/issue?@action=redirect&bpo=33767]: The concatenation (+) and repetition (*) sequence operations now raise TypeError instead of SystemError when performed on mmap.mmap objects. Patch by Zackery Spytz.

bpo-33734 [https://bugs.python.org/issue?@action=redirect&bpo=33734]: asyncio/ssl: Fix AttributeError, increase default handshake timeout

bpo-11874 [https://bugs.python.org/issue?@action=redirect&bpo=11874]: Use a better regex when breaking usage into wrappable parts. Avoids bogus assertion errors from custom metavar strings.

bpo-33582 [https://bugs.python.org/issue?@action=redirect&bpo=33582]: Emit a deprecation warning for inspect.formatargspec

Documentation

bpo-33409 [https://bugs.python.org/issue?@action=redirect&bpo=33409]: Clarified the relationship between PEP 538 [https://www.python.org/dev/peps/pep-0538]’s PYTHONCOERCECLOCALE and PEP 540’s PYTHONUTF8 mode.

bpo-33736 [https://bugs.python.org/issue?@action=redirect&bpo=33736]: Improve the documentation of asyncio.open_connection(), asyncio.start_server() and their UNIX socket counterparts.

bpo-31432 [https://bugs.python.org/issue?@action=redirect&bpo=31432]: Clarify meaning of CERT_NONE, CERT_OPTIONAL, and CERT_REQUIRED flags for ssl.SSLContext.verify_mode.

Build

bpo-5755 [https://bugs.python.org/issue?@action=redirect&bpo=5755]: Move -Wstrict-prototypes option to CFLAGS_NODIST from OPT. This option emitted annoying warnings when building extension modules written in C++.

Windows

bpo-33720 [https://bugs.python.org/issue?@action=redirect&bpo=33720]: Reduces maximum marshal recursion depth on release builds.

IDLE

bpo-33656 [https://bugs.python.org/issue?@action=redirect&bpo=33656]: On Windows, add API call saying that tk scales for DPI. On Windows 8.1+ or 10, with DPI compatibility properties of the Python binary unchanged, and a monitor resolution greater than 96 DPI, this should make text and lines sharper. It should otherwise have no effect.

bpo-33768 [https://bugs.python.org/issue?@action=redirect&bpo=33768]: Clicking on a context line moves that line to the top of the editor window.

bpo-33763 [https://bugs.python.org/issue?@action=redirect&bpo=33763]: IDLE: Use read-only text widget for code context instead of label widget.

bpo-33664 [https://bugs.python.org/issue?@action=redirect&bpo=33664]: Scroll IDLE editor text by lines. Previously, the mouse wheel and scrollbar slider moved text by a fixed number of pixels, resulting in partial lines at the top of the editor box. The change also applies to the shell and grep output windows, but not to read-only text views.

bpo-33679 [https://bugs.python.org/issue?@action=redirect&bpo=33679]: Enable theme-specific color configuration for Code Context. Use the Highlights tab to see the setting for built-in themes or add settings to custom themes.

bpo-33642 [https://bugs.python.org/issue?@action=redirect&bpo=33642]: Display up to maxlines non-blank lines for Code Context. If there is no current context, show a single blank line.

Python 3.7.0 beta 5

Release date: 2018-05-30

Core and Builtins

bpo-33622 [https://bugs.python.org/issue?@action=redirect&bpo=33622]: Fixed a leak when the garbage collector fails to add an object with the __del__ method or referenced by it into the gc.garbage list. PyGC_Collect() can now be called when an exception is set and preserves it.

bpo-33509 [https://bugs.python.org/issue?@action=redirect&bpo=33509]: Fix module_globals parameter of warnings.warn_explicit(): don’t crash if module_globals is not a dict.

bpo-20104 [https://bugs.python.org/issue?@action=redirect&bpo=20104]: The new os.posix_spawn added in 3.7.0b1 was removed as we are still working on what the API should look like. Expect this in 3.8 instead.

bpo-33475 [https://bugs.python.org/issue?@action=redirect&bpo=33475]: Fixed miscellaneous bugs in converting annotations to strings and optimized parentheses in the string representation.

bpo-33391 [https://bugs.python.org/issue?@action=redirect&bpo=33391]: Fix a leak in set_symmetric_difference().

bpo-28055 [https://bugs.python.org/issue?@action=redirect&bpo=28055]: Fix unaligned accesses in siphash24(). Patch by Rolf Eike Beer.

bpo-32911 [https://bugs.python.org/issue?@action=redirect&bpo=32911]: Due to unexpected compatibility issues discovered during downstream beta testing, reverted bpo-29463 [https://bugs.python.org/issue?@action=redirect&bpo=29463]. docstring field is removed from Module, ClassDef, FunctionDef, and AsyncFunctionDef ast nodes which was added in 3.7a1. Docstring expression is restored as a first statement in their body. Based on patch by Inada Naoki.

bpo-21983 [https://bugs.python.org/issue?@action=redirect&bpo=21983]: Fix a crash in ctypes.cast() in case the type argument is a ctypes structured data type. Patch by Eryk Sun and Oren Milman.

Library

bpo-32751 [https://bugs.python.org/issue?@action=redirect&bpo=32751]: When cancelling the task due to a timeout, asyncio.wait_for() will now wait until the cancellation is complete.

bpo-32684 [https://bugs.python.org/issue?@action=redirect&bpo=32684]: Fix gather to propagate cancellation of itself even with return_exceptions.

bpo-33654 [https://bugs.python.org/issue?@action=redirect&bpo=33654]: Support protocol type switching in SSLTransport.set_protocol().

bpo-33674 [https://bugs.python.org/issue?@action=redirect&bpo=33674]: Pause the transport as early as possible to further reduce the risk of data_received() being called before connection_made().

bpo-33674 [https://bugs.python.org/issue?@action=redirect&bpo=33674]: Fix a race condition in SSLProtocol.connection_made() of asyncio.sslproto: start immediately the handshake instead of using call_soon(). Previously, data_received() could be called before the handshake started, causing the handshake to hang or fail.

bpo-31647 [https://bugs.python.org/issue?@action=redirect&bpo=31647]: Fixed bug where calling write_eof() on a _SelectorSocketTransport after it’s already closed raises AttributeError.

bpo-32610 [https://bugs.python.org/issue?@action=redirect&bpo=32610]: Make asyncio.all_tasks() return only pending tasks.

bpo-32410 [https://bugs.python.org/issue?@action=redirect&bpo=32410]: Avoid blocking on file IO in sendfile fallback code

bpo-33469 [https://bugs.python.org/issue?@action=redirect&bpo=33469]: Fix RuntimeError after closing loop that used run_in_executor

bpo-33672 [https://bugs.python.org/issue?@action=redirect&bpo=33672]: Fix Task.__repr__ crash with Cython’s bogus coroutines

bpo-33654 [https://bugs.python.org/issue?@action=redirect&bpo=33654]: Fix transport.set_protocol() to support switching between asyncio.Protocol and asyncio.BufferedProtocol. Fix loop.start_tls() to work with asyncio.BufferedProtocols.

bpo-33652 [https://bugs.python.org/issue?@action=redirect&bpo=33652]: Pickles of type variables and subscripted generics are now future-proof and compatible with older Python versions.

bpo-32493 [https://bugs.python.org/issue?@action=redirect&bpo=32493]: Fixed uuid.uuid1() on FreeBSD.

bpo-33618 [https://bugs.python.org/issue?@action=redirect&bpo=33618]: Finalize and document preliminary and experimental TLS 1.3 support with OpenSSL 1.1.1

bpo-33623 [https://bugs.python.org/issue?@action=redirect&bpo=33623]: Fix possible SIGSGV when asyncio.Future is created in __del__

bpo-30877 [https://bugs.python.org/issue?@action=redirect&bpo=30877]: Fixed a bug in the Python implementation of the JSON decoder that prevented the cache of parsed strings from clearing after finishing the decoding. Based on patch by c-fos.

bpo-33570 [https://bugs.python.org/issue?@action=redirect&bpo=33570]: Change TLS 1.3 cipher suite settings for compatibility with OpenSSL 1.1.1-pre6 and newer. OpenSSL 1.1.1 will have TLS 1.3 ciphers enabled by default.

bpo-28556 [https://bugs.python.org/issue?@action=redirect&bpo=28556]: Do not simplify arguments to typing.Union. Now Union[Manager, Employee] is not simplified to Employee at runtime. Such simplification previously caused several bugs and limited possibilities for introspection.

bpo-33540 [https://bugs.python.org/issue?@action=redirect&bpo=33540]: Add a new block_on_close class attribute to ForkingMixIn and ThreadingMixIn classes of socketserver.

bpo-33548 [https://bugs.python.org/issue?@action=redirect&bpo=33548]: tempfile._candidate_tempdir_list should consider common TEMP locations

bpo-33109 [https://bugs.python.org/issue?@action=redirect&bpo=33109]: argparse subparsers are once again not required by default, reverting the change in behavior introduced by bpo-26510 [https://bugs.python.org/issue?@action=redirect&bpo=26510] in 3.7.0a2.

bpo-33536 [https://bugs.python.org/issue?@action=redirect&bpo=33536]: dataclasses.make_dataclass now checks for invalid field names and duplicate fields. Also, added a check for invalid field specifications.

bpo-33542 [https://bugs.python.org/issue?@action=redirect&bpo=33542]: Prevent uuid.get_node from using a DUID instead of a MAC on Windows. Patch by Zvi Effron

bpo-26819 [https://bugs.python.org/issue?@action=redirect&bpo=26819]: Fix race condition with ReadTransport.resume_reading in Windows proactor event loop.

Fix failure in typing.get_type_hints() when ClassVar was provided as a string forward reference.

bpo-33505 [https://bugs.python.org/issue?@action=redirect&bpo=33505]: Optimize asyncio.ensure_future() by reordering if checks: 1.17x faster.

bpo-33497 [https://bugs.python.org/issue?@action=redirect&bpo=33497]: Add errors param to cgi.parse_multipart and make an encoding in FieldStorage use the given errors (needed for Twisted). Patch by Amber Brown.

bpo-33495 [https://bugs.python.org/issue?@action=redirect&bpo=33495]: Change dataclasses.Fields repr to use the repr of each of its members, instead of str. This makes it more clear what each field actually represents. This is especially true for the “type” member.

bpo-33453 [https://bugs.python.org/issue?@action=redirect&bpo=33453]: Fix dataclasses to work if using literal string type annotations or if using PEP 563 «Postponed Evaluation of Annotations». Only specific string prefixes are detected for both ClassVar («ClassVar» and «typing.ClassVar») and InitVar («InitVar» and «dataclasses.InitVar»).

bpo-28556 [https://bugs.python.org/issue?@action=redirect&bpo=28556]: Minor fixes in typing module: add annotations to NamedTuple.__new__, pass *args and **kwds in Generic.__new__. Original PRs by Paulius Šarka and Chad Dombrova.

bpo-20087 [https://bugs.python.org/issue?@action=redirect&bpo=20087]: Updated alias mapping with glibc 2.27 supported locales.

bpo-33422 [https://bugs.python.org/issue?@action=redirect&bpo=33422]: Fix trailing quotation marks getting deleted when looking up byte/string literals on pydoc. Patch by Andrés Delfino.

bpo-28167 [https://bugs.python.org/issue?@action=redirect&bpo=28167]: The function platform.linux_distribution and platform.dist now trigger a DeprecationWarning and have been marked for removal in Python 3.8

bpo-33197 [https://bugs.python.org/issue?@action=redirect&bpo=33197]: Update error message when constructing invalid inspect.Parameters Patch by Dong-hee Na.

bpo-33263 [https://bugs.python.org/issue?@action=redirect&bpo=33263]: Fix FD leak in _SelectorSocketTransport Patch by Vlad Starostin.

bpo-32861 [https://bugs.python.org/issue?@action=redirect&bpo=32861]: The urllib.robotparser’s __str__ representation now includes wildcard entries and the «Crawl-delay» and «Request-rate» fields. Patch by Michael Lazar.

bpo-32257 [https://bugs.python.org/issue?@action=redirect&bpo=32257]: The ssl module now contains OP_NO_RENEGOTIATION constant, available with OpenSSL 1.1.0h or 1.1.1.

bpo-16865 [https://bugs.python.org/issue?@action=redirect&bpo=16865]: Support arrays >=2GiB in ctypes. Patch by Segev Finer.

Documentation

bpo-23859 [https://bugs.python.org/issue?@action=redirect&bpo=23859]: Document that asyncio.wait() does not cancel its futures on timeout.

bpo-32436 [https://bugs.python.org/issue?@action=redirect&bpo=32436]: Document PEP 567 [https://www.python.org/dev/peps/pep-0567] changes to asyncio.

bpo-33604 [https://bugs.python.org/issue?@action=redirect&bpo=33604]: Update HMAC md5 default to a DeprecationWarning, bump removal to 3.8.

bpo-33503 [https://bugs.python.org/issue?@action=redirect&bpo=33503]: Fix broken pypi link

bpo-33421 [https://bugs.python.org/issue?@action=redirect&bpo=33421]: Add missing documentation for typing.AsyncContextManager.

Tests

bpo-33655 [https://bugs.python.org/issue?@action=redirect&bpo=33655]: Ignore test_posix_fallocate failures on BSD platforms that might be due to running on ZFS.

bpo-32604 [https://bugs.python.org/issue?@action=redirect&bpo=32604]: Remove the _xxsubinterpreters module (meant for testing) and associated helpers. This module was originally added recently in 3.7b1.

Build

bpo-33614 [https://bugs.python.org/issue?@action=redirect&bpo=33614]: Ensures module definition files for the stable ABI on Windows are correctly regenerated.

bpo-33522 [https://bugs.python.org/issue?@action=redirect&bpo=33522]: Enable CI builds on Visual Studio Team Services at https://python.visualstudio.com/cpython

bpo-33012 [https://bugs.python.org/issue?@action=redirect&bpo=33012]: Add -Wno-cast-function-type for gcc 8 for silencing warnings about function casts like casting to PyCFunction in method definition lists.

macOS

bpo-13631 [https://bugs.python.org/issue?@action=redirect&bpo=13631]: The .editrc file in user’s home directory is now processed correctly during the readline initialization through editline emulation on macOS.

IDLE

bpo-33628 [https://bugs.python.org/issue?@action=redirect&bpo=33628]: IDLE: Cleanup codecontext.py and its test.

bpo-33564 [https://bugs.python.org/issue?@action=redirect&bpo=33564]: IDLE’s code context now recognizes async as a block opener.

bpo-32831 [https://bugs.python.org/issue?@action=redirect&bpo=32831]: Add docstrings and tests for codecontext.

Python 3.7.0 beta 4

Release date: 2018-05-02

Core and Builtins

bpo-33363 [https://bugs.python.org/issue?@action=redirect&bpo=33363]: Raise a SyntaxError for async with and async for statements outside of async functions.

bpo-33128 [https://bugs.python.org/issue?@action=redirect&bpo=33128]: Fix a bug that causes PathFinder to appear twice on sys.meta_path. Patch by Pablo Galindo Salgado.

bpo-33312 [https://bugs.python.org/issue?@action=redirect&bpo=33312]: Fixed clang ubsan (undefined behavior sanitizer) warnings in dictobject.c by adjusting how the internal struct _dictkeysobject shared keys structure is declared.

bpo-33231 [https://bugs.python.org/issue?@action=redirect&bpo=33231]: Fix potential memory leak in normalizestring().

bpo-33205 [https://bugs.python.org/issue?@action=redirect&bpo=33205]: Change dict growth function from round_up_to_power_2(used*2+hashtable_size/2) to round_up_to_power_2(used*3). Previously, dict is shrinked only when used == 0. Now dict has more chance to be shrinked.

bpo-29922 [https://bugs.python.org/issue?@action=redirect&bpo=29922]: Improved error messages in “async with” when __aenter__() or __aexit__() return non-awaitable object.

bpo-33199 [https://bugs.python.org/issue?@action=redirect&bpo=33199]: Fix ma_version_tag in dict implementation is uninitialized when copying from key-sharing dict.

Library

bpo-33281 [https://bugs.python.org/issue?@action=redirect&bpo=33281]: Fix ctypes.util.find_library regression on macOS.

bpo-33383 [https://bugs.python.org/issue?@action=redirect&bpo=33383]: Fixed crash in the get() method of the dbm.ndbm database object when it is called with a single argument.

bpo-33329 [https://bugs.python.org/issue?@action=redirect&bpo=33329]: Fix multiprocessing regression on newer glibcs

bpo-991266 [https://bugs.python.org/issue?@action=redirect&bpo=991266]: Fix quoting of the Comment attribute of http.cookies.SimpleCookie.

bpo-33131 [https://bugs.python.org/issue?@action=redirect&bpo=33131]: Upgrade bundled version of pip to 10.0.1.

bpo-33308 [https://bugs.python.org/issue?@action=redirect&bpo=33308]: Fixed a crash in the parser module when converting an ST object to a tree of tuples or lists with line_info=False and col_info=True.

bpo-33266 [https://bugs.python.org/issue?@action=redirect&bpo=33266]: lib2to3 now recognizes rf'...' strings.

bpo-11594 [https://bugs.python.org/issue?@action=redirect&bpo=11594]: Ensure line-endings are respected when using lib2to3.

bpo-33254 [https://bugs.python.org/issue?@action=redirect&bpo=33254]: Have importlib.resources.contents() and importlib.abc.ResourceReader.contents() return an iterable instead of an iterator.

bpo-33256 [https://bugs.python.org/issue?@action=redirect&bpo=33256]: Fix display of <module> call in the html produced by cgitb.html(). Patch by Stéphane Blondon.

bpo-33185 [https://bugs.python.org/issue?@action=redirect&bpo=33185]: Fixed regression when running pydoc with the -m switch. (The regression was introduced in 3.7.0b3 by the resolution of bpo-33053 [https://bugs.python.org/issue?@action=redirect&bpo=33053]) This fix also changed pydoc to add os.getcwd() to sys.path when necessary, rather than adding ".".

bpo-33169 [https://bugs.python.org/issue?@action=redirect&bpo=33169]: Delete entries of None in sys.path_importer_cache when importlib.machinery.invalidate_caches() is called.

bpo-33217 [https://bugs.python.org/issue?@action=redirect&bpo=33217]: Deprecate looking up non-Enum objects in Enum classes and Enum members (will raise TypeError in 3.8+).

bpo-33203 [https://bugs.python.org/issue?@action=redirect&bpo=33203]: random.Random.choice() now raises IndexError for empty sequences consistently even when called from subclasses without a getrandbits() implementation.

bpo-33224 [https://bugs.python.org/issue?@action=redirect&bpo=33224]: Update difflib.mdiff() for PEP 479 [https://www.python.org/dev/peps/pep-0479]. Convert an uncaught StopIteration in a generator into a return-statement.

bpo-33209 [https://bugs.python.org/issue?@action=redirect&bpo=33209]: End framing at the end of C implementation of pickle.Pickler.dump().

bpo-20104 [https://bugs.python.org/issue?@action=redirect&bpo=20104]: Improved error handling and fixed a reference leak in os.posix_spawn().

bpo-33175 [https://bugs.python.org/issue?@action=redirect&bpo=33175]: In dataclasses, Field.__set_name__ now looks up the __set_name__ special method on the class, not the instance, of the default value.

bpo-33097 [https://bugs.python.org/issue?@action=redirect&bpo=33097]: Raise RuntimeError when executor.submit is called during interpreter shutdown.

bpo-31908 [https://bugs.python.org/issue?@action=redirect&bpo=31908]: Fix output of cover files for trace module command-line tool. Previously emitted cover files only when --missing option was used. Patch by Michael Selik.

Documentation

bpo-33378 [https://bugs.python.org/issue?@action=redirect&bpo=33378]: Add Korean language switcher for https://docs.python.org/3/

bpo-33276 [https://bugs.python.org/issue?@action=redirect&bpo=33276]: Clarify that the __path__ attribute on modules cannot be just any value.

bpo-33201 [https://bugs.python.org/issue?@action=redirect&bpo=33201]: Modernize documentation for writing C extension types.

bpo-33195 [https://bugs.python.org/issue?@action=redirect&bpo=33195]: Deprecate Py_UNICODE usage in c-api/arg document. Py_UNICODE related APIs are deprecated since Python 3.3, but it is missed in the document.

bpo-8243 [https://bugs.python.org/issue?@action=redirect&bpo=8243]: Add a note about curses.addch and curses.addstr exception behavior when writing outside a window, or pad.

bpo-32337 [https://bugs.python.org/issue?@action=redirect&bpo=32337]: Update documentation related with dict order.

Tests

bpo-33358 [https://bugs.python.org/issue?@action=redirect&bpo=33358]: Fix test_embed.test_pre_initialization_sys_options() when the interpreter is built with --enable-shared.

Build

bpo-33394 [https://bugs.python.org/issue?@action=redirect&bpo=33394]: Enable the verbose build for extension modules, when GNU make is passed macros on the command line.

bpo-33393 [https://bugs.python.org/issue?@action=redirect&bpo=33393]: Update config.guess and config.sub files.

bpo-33377 [https://bugs.python.org/issue?@action=redirect&bpo=33377]: Add new triplets for mips r6 and riscv variants (used in extension suffixes).

bpo-32232 [https://bugs.python.org/issue?@action=redirect&bpo=32232]: By default, modules configured in Modules/Setup are no longer built with -DPy_BUILD_CORE. Instead, modules that specifically need that preprocessor definition include it in their individual entries.

bpo-33182 [https://bugs.python.org/issue?@action=redirect&bpo=33182]: The embedding tests can once again be built with clang 6.0

Windows

bpo-33184 [https://bugs.python.org/issue?@action=redirect&bpo=33184]: Update Windows installer to use OpenSSL 1.1.0h.

macOS

bpo-33184 [https://bugs.python.org/issue?@action=redirect&bpo=33184]: Update macOS installer build to use OpenSSL 1.1.0h.

IDLE

bpo-21474 [https://bugs.python.org/issue?@action=redirect&bpo=21474]: Update word/identifier definition from ascii to unicode. In text and entry boxes, this affects selection by double-click, movement left/right by control-left/right, and deletion left/right by control-BACKSPACE/DEL.

bpo-33204 [https://bugs.python.org/issue?@action=redirect&bpo=33204]: IDLE: consistently color invalid string prefixes. A “u” string prefix cannot be paired with either “r” or “f”. Consistently color as much of the prefix, starting at the right, as is valid. Revise and extend colorizer test.

Tools/Demos

bpo-33189 [https://bugs.python.org/issue?@action=redirect&bpo=33189]: pygettext.py now recognizes only literal strings as docstrings and translatable strings, and rejects bytes literals and f-string expressions.

bpo-31920 [https://bugs.python.org/issue?@action=redirect&bpo=31920]: Fixed handling directories as arguments in the pygettext script. Based on patch by Oleg Krasnikov.

bpo-29673 [https://bugs.python.org/issue?@action=redirect&bpo=29673]: Fix pystackv and pystack gdbinit macros.

bpo-31583 [https://bugs.python.org/issue?@action=redirect&bpo=31583]: Fix 2to3 for using with –add-suffix option but without –output-dir option for relative path to files in current directory.

Python 3.7.0 beta 3

Release date: 2018-03-29

Security

bpo-33136 [https://bugs.python.org/issue?@action=redirect&bpo=33136]: Harden ssl module against LibreSSL CVE-2018-8970. X509_VERIFY_PARAM_set1_host() is called with an explicit namelen. A new test ensures that NULL bytes are not allowed.

bpo-33001 [https://bugs.python.org/issue?@action=redirect&bpo=33001]: Minimal fix to prevent buffer overrun in os.symlink on Windows

bpo-32981 [https://bugs.python.org/issue?@action=redirect&bpo=32981]: Regexes in difflib and poplib were vulnerable to catastrophic backtracking. These regexes formed potential DOS vectors (REDOS). They have been refactored. This resolves CVE-2018-1060 and CVE-2018-1061. Patch by Jamie Davis.

Core and Builtins

bpo-33053 [https://bugs.python.org/issue?@action=redirect&bpo=33053]: When using the -m switch, sys.path[0] is now explicitly expanded as the starting working directory, rather than being left as the empty path (which allows imports from the current working directory at the time of the import)

bpo-33018 [https://bugs.python.org/issue?@action=redirect&bpo=33018]: Improve consistency of errors raised by issubclass() when called with a non-class and an abstract base class as the first and second arguments, respectively. Patch by Josh Bronson.

bpo-33041 [https://bugs.python.org/issue?@action=redirect&bpo=33041]: Fixed jumping when the function contains an async for loop.

bpo-33026 [https://bugs.python.org/issue?@action=redirect&bpo=33026]: Fixed jumping out of «with» block by setting f_lineno.

bpo-33005 [https://bugs.python.org/issue?@action=redirect&bpo=33005]: Fix a crash on fork when using a custom memory allocator (ex: using PYTHONMALLOC env var). _PyGILState_Reinit() and _PyInterpreterState_Enable() now use the default RAW memory allocator to allocate a new interpreters mutex on fork.

bpo-17288 [https://bugs.python.org/issue?@action=redirect&bpo=17288]: Prevent jumps from “return” and “exception” trace events.

bpo-32836 [https://bugs.python.org/issue?@action=redirect&bpo=32836]: Don’t use temporary variables in cases of list/dict/set comprehensions

Library

bpo-33141 [https://bugs.python.org/issue?@action=redirect&bpo=33141]: Have Field objects pass through __set_name__ to their default values, if they have their own __set_name__.

bpo-33096 [https://bugs.python.org/issue?@action=redirect&bpo=33096]: Allow ttk.Treeview.insert to insert iid that has a false boolean value. Note iid=0 and iid=False would be same. Patch by Garvit Khatri.

bpo-32873 [https://bugs.python.org/issue?@action=redirect&bpo=32873]: Treat type variables and special typing forms as immutable by copy and pickle. This fixes several minor issues and inconsistencies, and improves backwards compatibility with Python 3.6.

bpo-33134 [https://bugs.python.org/issue?@action=redirect&bpo=33134]: When computing dataclass’s __hash__, use the lookup table to contain the function which returns the __hash__ value. This is an improvement over looking up a string, and then testing that string to see what to do.

bpo-33127 [https://bugs.python.org/issue?@action=redirect&bpo=33127]: The ssl module now compiles with LibreSSL 2.7.1.

bpo-32505 [https://bugs.python.org/issue?@action=redirect&bpo=32505]: Raise TypeError if a member variable of a dataclass is of type Field, but doesn’t have a type annotation.

bpo-33078 [https://bugs.python.org/issue?@action=redirect&bpo=33078]: Fix the failure on OSX caused by the tests relying on sem_getvalue

bpo-33116 [https://bugs.python.org/issue?@action=redirect&bpo=33116]: Add “Field” to dataclasses.__all__.

bpo-32896 [https://bugs.python.org/issue?@action=redirect&bpo=32896]: Fix an error where subclassing a dataclass with a field that uses a default_factory would generate an incorrect class.

bpo-33100 [https://bugs.python.org/issue?@action=redirect&bpo=33100]: Dataclasses: If a field has a default value that’s a MemberDescriptorType, then it’s from that field being in __slots__, not an actual default value.

bpo-32953 [https://bugs.python.org/issue?@action=redirect&bpo=32953]: If a non-dataclass inherits from a frozen dataclass, allow attributes to be added to the derived class. Only attributes from the frozen dataclass cannot be assigned to. Require all dataclasses in a hierarchy to be either all frozen or all non-frozen.

bpo-33061 [https://bugs.python.org/issue?@action=redirect&bpo=33061]: Add missing NoReturn to __all__ in typing.py

bpo-33078 [https://bugs.python.org/issue?@action=redirect&bpo=33078]: Fix the size handling in multiprocessing.Queue when a pickling error occurs.

bpo-33064 [https://bugs.python.org/issue?@action=redirect&bpo=33064]: lib2to3 now properly supports trailing commas after *args and **kwargs in function signatures.

bpo-33056 [https://bugs.python.org/issue?@action=redirect&bpo=33056]: FIX properly close leaking fds in concurrent.futures.ProcessPoolExecutor.

bpo-33021 [https://bugs.python.org/issue?@action=redirect&bpo=33021]: Release the GIL during fstat() calls, avoiding hang of all threads when calling mmap.mmap(), os.urandom(), and random.seed(). Patch by Nir Soffer.

bpo-31804 [https://bugs.python.org/issue?@action=redirect&bpo=31804]: Avoid failing in multiprocessing.Process if the standard streams are closed or None at exit.

bpo-33037 [https://bugs.python.org/issue?@action=redirect&bpo=33037]: Skip sending/receiving data after SSL transport closing.

bpo-27683 [https://bugs.python.org/issue?@action=redirect&bpo=27683]: Fix a regression in ipaddress that result of hosts() is empty when the network is constructed by a tuple containing an integer mask and only 1 bit left for addresses.

bpo-32999 [https://bugs.python.org/issue?@action=redirect&bpo=32999]: Fix C implementation of ABC.__subclasscheck__(cls, subclass) crashed when subclass is not a type object.

bpo-33009 [https://bugs.python.org/issue?@action=redirect&bpo=33009]: Fix inspect.signature() for single-parameter partialmethods.

bpo-32969 [https://bugs.python.org/issue?@action=redirect&bpo=32969]: Expose several missing constants in zlib and fix corresponding documentation.

bpo-32056 [https://bugs.python.org/issue?@action=redirect&bpo=32056]: Improved exceptions raised for invalid number of channels and sample width when read an audio file in modules aifc, wave and sunau.

bpo-32844 [https://bugs.python.org/issue?@action=redirect&bpo=32844]: Fix wrong redirection of a low descriptor (0 or 1) to stderr in subprocess if another low descriptor is closed.

bpo-32857 [https://bugs.python.org/issue?@action=redirect&bpo=32857]: In tkinter, after_cancel(None) now raises a ValueError instead of canceling the first scheduled function. Patch by Cheryl Sabella.

bpo-31639 [https://bugs.python.org/issue?@action=redirect&bpo=31639]: http.server now exposes a ThreadedHTTPServer class and uses it when the module is run with -m to cope with web browsers pre-opening sockets.

bpo-27645 [https://bugs.python.org/issue?@action=redirect&bpo=27645]: sqlite3.Connection now exposes a backup method, if the underlying SQLite library is at version 3.6.11 or higher. Patch by Lele Gaifax.

Documentation

bpo-33126 [https://bugs.python.org/issue?@action=redirect&bpo=33126]: Document PyBuffer_ToContiguous().

bpo-27212 [https://bugs.python.org/issue?@action=redirect&bpo=27212]: Modify documentation for the islice() recipe to consume initial values up to the start index.

bpo-28247 [https://bugs.python.org/issue?@action=redirect&bpo=28247]: Update zipapp documentation to describe how to make standalone applications.

bpo-18802 [https://bugs.python.org/issue?@action=redirect&bpo=18802]: Documentation changes for ipaddress. Patch by Jon Foster and Berker Peksag.

bpo-27428 [https://bugs.python.org/issue?@action=redirect&bpo=27428]: Update documentation to clarify that WindowsRegistryFinder implements MetaPathFinder. (Patch by Himanshu Lakhara)

Tests

bpo-32872 [https://bugs.python.org/issue?@action=redirect&bpo=32872]: Avoid regrtest compatibility issue with namespace packages.

bpo-32517 [https://bugs.python.org/issue?@action=redirect&bpo=32517]: Fix failing test_asyncio on macOS 10.12.2+ due to transport of KqueueSelector loop was not being closed.

bpo-19417 [https://bugs.python.org/issue?@action=redirect&bpo=19417]: Add test_bdb.py.

Build

bpo-33163 [https://bugs.python.org/issue?@action=redirect&bpo=33163]: Upgrade pip to 9.0.3 and setuptools to v39.0.1.

Windows

bpo-33016 [https://bugs.python.org/issue?@action=redirect&bpo=33016]: Fix potential use of uninitialized memory in nt._getfinalpathname

bpo-32903 [https://bugs.python.org/issue?@action=redirect&bpo=32903]: Fix a memory leak in os.chdir() on Windows if the current directory is set to a UNC path.

macOS

bpo-32726 [https://bugs.python.org/issue?@action=redirect&bpo=32726]: Build and link with private copy of Tcl/Tk 8.6 for the macOS 10.6+ installer. The 10.9+ installer variant already does this. This means that the Python 3.7 provided by the python.org macOS installers no longer need or use any external versions of Tcl/Tk, either system-provided or user-installed, such as ActiveTcl.

IDLE

bpo-32984 [https://bugs.python.org/issue?@action=redirect&bpo=32984]: Set __file__ while running a startup file. Like Python, IDLE optionally runs one startup file in the Shell window before presenting the first interactive input prompt. For IDLE, -s runs a file named in environmental variable IDLESTARTUP or PYTHONSTARTUP; -r file runs file. Python sets __file__ to the startup file name before running the file and unsets it before the first prompt. IDLE now does the same when run normally, without the -n option.

bpo-32940 [https://bugs.python.org/issue?@action=redirect&bpo=32940]: Simplify and rename StringTranslatePseudoMapping in pyparse.

Tools/Demos

bpo-32885 [https://bugs.python.org/issue?@action=redirect&bpo=32885]: Add an -n flag for Tools/scripts/pathfix.py to disable automatic backup creation (files with ~ suffix).

C API

bpo-33042 [https://bugs.python.org/issue?@action=redirect&bpo=33042]: Embedding applications may once again call PySys_ResetWarnOptions, PySys_AddWarnOption, and PySys_AddXOption prior to calling Py_Initialize.

bpo-32374 [https://bugs.python.org/issue?@action=redirect&bpo=32374]: Document that m_traverse for multi-phase initialized modules can be called with m_state=NULL, and add a sanity check

Python 3.7.0 beta 2

Release date: 2018-02-27

Security

bpo-28414 [https://bugs.python.org/issue?@action=redirect&bpo=28414]: The ssl module now allows users to perform their own IDN en/decoding when using SNI.

Core and Builtins

bpo-32889 [https://bugs.python.org/issue?@action=redirect&bpo=32889]: Update Valgrind suppression list to account for the rename of Py_ADDRESS_IN_RANG to address_in_range.

bpo-31356 [https://bugs.python.org/issue?@action=redirect&bpo=31356]: Remove the new API added in bpo-31356 [https://bugs.python.org/issue?@action=redirect&bpo=31356] (gc.ensure_disabled() context manager).

bpo-32305 [https://bugs.python.org/issue?@action=redirect&bpo=32305]: For namespace packages, ensure that both __file__ and __spec__.origin are set to None.

bpo-32303 [https://bugs.python.org/issue?@action=redirect&bpo=32303]: Make sure __spec__.loader matches __loader__ for namespace packages.

bpo-32711 [https://bugs.python.org/issue?@action=redirect&bpo=32711]: Fix the warning messages for Python/ast_unparse.c. Patch by Stéphane Wirtel

bpo-32583 [https://bugs.python.org/issue?@action=redirect&bpo=32583]: Fix possible crashing in builtin Unicode decoders caused by write out-of-bound errors when using customized decode error handlers.

Library

bpo-32960 [https://bugs.python.org/issue?@action=redirect&bpo=32960]: For dataclasses, disallow inheriting frozen from non-frozen classes, and also disallow inheriting non-frozen from frozen classes. This restriction will be relaxed at a future date.

bpo-32713 [https://bugs.python.org/issue?@action=redirect&bpo=32713]: Fixed tarfile.itn handling of out-of-bounds float values. Patch by Joffrey Fuhrer.

bpo-32951 [https://bugs.python.org/issue?@action=redirect&bpo=32951]: Direct instantiation of SSLSocket and SSLObject objects is now prohibited. The constructors were never documented, tested, or designed as public constructors. Users were suppose to use ssl.wrap_socket() or SSLContext.

bpo-32929 [https://bugs.python.org/issue?@action=redirect&bpo=32929]: Remove the tri-state parameter «hash», and add the boolean «unsafe_hash». If unsafe_hash is True, add a __hash__ function, but if a __hash__ exists, raise TypeError. If unsafe_hash is False, add a __hash__ based on the values of eq= and frozen=. The unsafe_hash=False behavior is the same as the old hash=None behavior. unsafe_hash=False is the default, just as hash=None used to be.

bpo-32947 [https://bugs.python.org/issue?@action=redirect&bpo=32947]: Add OP_ENABLE_MIDDLEBOX_COMPAT and test workaround for TLSv1.3 for future compatibility with OpenSSL 1.1.1.

bpo-30622 [https://bugs.python.org/issue?@action=redirect&bpo=30622]: The ssl module now detects missing NPN support in LibreSSL.

bpo-32922 [https://bugs.python.org/issue?@action=redirect&bpo=32922]: dbm.open() now encodes filename with the filesystem encoding rather than default encoding.

bpo-32859 [https://bugs.python.org/issue?@action=redirect&bpo=32859]: In os.dup2, don’t check every call whether the dup3 syscall exists or not.

bpo-32556 [https://bugs.python.org/issue?@action=redirect&bpo=32556]: nt._getfinalpathname, nt._getvolumepathname and nt._getdiskusage now correctly convert from bytes.

bpo-25988 [https://bugs.python.org/issue?@action=redirect&bpo=25988]: Emit a DeprecationWarning when using or importing an ABC directly from collections rather than from collections.abc.

bpo-21060 [https://bugs.python.org/issue?@action=redirect&bpo=21060]: Rewrite confusing message from setup.py upload from «No dist file created in earlier command» to the more helpful «Must create and upload files in one command».

bpo-32852 [https://bugs.python.org/issue?@action=redirect&bpo=32852]: Make sure sys.argv remains as a list when running trace.

bpo-31333 [https://bugs.python.org/issue?@action=redirect&bpo=31333]: _abc module is added. It is a speedup module with C implementations for various functions and methods in abc. Creating an ABC subclass and calling isinstance or issubclass with an ABC subclass are up to 1.5x faster. In addition, this makes Python start-up up to 10% faster. Note that the new implementation hides internal registry and caches, previously accessible via private attributes _abc_registry, _abc_cache, and _abc_negative_cache. There are three debugging helper methods that can be used instead _dump_registry, _abc_registry_clear, and _abc_caches_clear.

bpo-32841 [https://bugs.python.org/issue?@action=redirect&bpo=32841]: Fixed asyncio.Condition issue which silently ignored cancellation after notifying and cancelling a conditional lock. Patch by Bar Harel.

bpo-32819 [https://bugs.python.org/issue?@action=redirect&bpo=32819]: ssl.match_hostname() has been simplified and no longer depends on re and ipaddress module for wildcard and IP addresses. Error reporting for invalid wildcards has been improved.

bpo-32394 [https://bugs.python.org/issue?@action=redirect&bpo=32394]: socket: Remove TCP_FASTOPEN,TCP_KEEPCNT,TCP_KEEPIDLE,TCP_KEEPINTVL flags on older version Windows during run-time.

bpo-31787 [https://bugs.python.org/issue?@action=redirect&bpo=31787]: Fixed refleaks of __init__() methods in various modules. (Contributed by Oren Milman)

bpo-30157 [https://bugs.python.org/issue?@action=redirect&bpo=30157]: Fixed guessing quote and delimiter in csv.Sniffer.sniff() when only the last field is quoted. Patch by Jake Davis.

bpo-32792 [https://bugs.python.org/issue?@action=redirect&bpo=32792]: collections.ChainMap() preserves the order of the underlying mappings.

bpo-32775 [https://bugs.python.org/issue?@action=redirect&bpo=32775]: fnmatch.translate() no longer produces patterns which contain set operations. Sets starting with “[” or containing “–”, “&&”, “~~” or “||” will be interpreted differently in regular expressions in future versions. Currently they emit warnings. fnmatch.translate() now avoids producing patterns containing such sets by accident.

bpo-32622 [https://bugs.python.org/issue?@action=redirect&bpo=32622]: Implement native fast sendfile for Windows proactor event loop.

bpo-32777 [https://bugs.python.org/issue?@action=redirect&bpo=32777]: Fix a rare but potential pre-exec child process deadlock in subprocess on POSIX systems when marking file descriptors inheritable on exec in the child process. This bug appears to have been introduced in 3.4.

bpo-32647 [https://bugs.python.org/issue?@action=redirect&bpo=32647]: The ctypes module used to depend on indirect linking for dlopen. The shared extension is now explicitly linked against libdl on platforms with dl.

bpo-32741 [https://bugs.python.org/issue?@action=redirect&bpo=32741]: Implement asyncio.TimerHandle.when() method.

bpo-32691 [https://bugs.python.org/issue?@action=redirect&bpo=32691]: Use mod_spec.parent when running modules with pdb

bpo-32734 [https://bugs.python.org/issue?@action=redirect&bpo=32734]: Fixed asyncio.Lock() safety issue which allowed acquiring and locking the same lock multiple times, without it being free. Patch by Bar Harel.

bpo-32727 [https://bugs.python.org/issue?@action=redirect&bpo=32727]: Do not include name field in SMTP envelope from address. Patch by Stéphane Wirtel

bpo-31453 [https://bugs.python.org/issue?@action=redirect&bpo=31453]: Add TLSVersion constants and SSLContext.maximum_version / minimum_version attributes. The new API wraps OpenSSL 1.1 https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_min_proto_version.html feature.

bpo-24334 [https://bugs.python.org/issue?@action=redirect&bpo=24334]: Internal implementation details of ssl module were cleaned up. The SSLSocket has one less layer of indirection. Owner and session information are now handled by the SSLSocket and SSLObject constructor. Channel binding implementation has been simplified.

bpo-31848 [https://bugs.python.org/issue?@action=redirect&bpo=31848]: Fix the error handling in Aifc_read.initfp() when the SSND chunk is not found. Patch by Zackery Spytz.

bpo-32585 [https://bugs.python.org/issue?@action=redirect&bpo=32585]: Add Ttk spinbox widget to tkinter.ttk. Patch by Alan D Moore.

bpo-32221 [https://bugs.python.org/issue?@action=redirect&bpo=32221]: Various functions returning tuple containing IPv6 addresses now omit %scope part since the same information is already encoded in scopeid tuple item. Especially this speeds up socket.recvfrom() when it receives multicast packet since useless resolving of network interface name is omitted.

bpo-30693 [https://bugs.python.org/issue?@action=redirect&bpo=30693]: The TarFile class now recurses directories in a reproducible way.

bpo-30693 [https://bugs.python.org/issue?@action=redirect&bpo=30693]: The ZipFile class now recurses directories in a reproducible way.

Documentation

bpo-28124 [https://bugs.python.org/issue?@action=redirect&bpo=28124]: The ssl module function ssl.wrap_socket() has been de-emphasized and deprecated in favor of the more secure and efficient SSLContext.wrap_socket() method.

bpo-17232 [https://bugs.python.org/issue?@action=redirect&bpo=17232]: Clarify docs for -O and -OO. Patch by Terry Reedy.

bpo-32436 [https://bugs.python.org/issue?@action=redirect&bpo=32436]: Add documentation for the contextvars module (PEP 567).

bpo-32800 [https://bugs.python.org/issue?@action=redirect&bpo=32800]: Update link to w3c doc for xml default namespaces.

bpo-11015 [https://bugs.python.org/issue?@action=redirect&bpo=11015]: Update test.support documentation.

bpo-8722 [https://bugs.python.org/issue?@action=redirect&bpo=8722]: Document __getattr__() behavior when property get() method raises AttributeError.

bpo-32614 [https://bugs.python.org/issue?@action=redirect&bpo=32614]: Modify RE examples in documentation to use raw strings to prevent DeprecationWarning and add text to REGEX HOWTO to highlight the deprecation.

bpo-31972 [https://bugs.python.org/issue?@action=redirect&bpo=31972]: Improve docstrings for pathlib.PurePath subclasses.

Tests

bpo-31809 [https://bugs.python.org/issue?@action=redirect&bpo=31809]: Add tests to verify connection with secp ECDH curves.

Build

bpo-32898 [https://bugs.python.org/issue?@action=redirect&bpo=32898]: Fix the python debug build when using COUNT_ALLOCS.

Windows

bpo-32901 [https://bugs.python.org/issue?@action=redirect&bpo=32901]: Update Tcl and Tk versions to 8.6.8

bpo-31966 [https://bugs.python.org/issue?@action=redirect&bpo=31966]: Fixed WindowsConsoleIO.write() for writing empty data.

bpo-32409 [https://bugs.python.org/issue?@action=redirect&bpo=32409]: Ensures activate.bat can handle Unicode contents.

bpo-32457 [https://bugs.python.org/issue?@action=redirect&bpo=32457]: Improves handling of denormalized executable path when launching Python.

bpo-32370 [https://bugs.python.org/issue?@action=redirect&bpo=32370]: Use the correct encoding for ipconfig output in the uuid module. Patch by Segev Finer.

bpo-29248 [https://bugs.python.org/issue?@action=redirect&bpo=29248]: Fix os.readlink() on Windows, which was mistakenly treating the PrintNameOffset field of the reparse data buffer as a number of characters instead of bytes. Patch by Craig Holmquist and SSE4.

macOS

bpo-32901 [https://bugs.python.org/issue?@action=redirect&bpo=32901]: Update macOS 10.9+ installer to Tcl/Tk 8.6.8.

IDLE

bpo-32916 [https://bugs.python.org/issue?@action=redirect&bpo=32916]: Change str to code in pyparse.

bpo-32905 [https://bugs.python.org/issue?@action=redirect&bpo=32905]: Remove unused code in pyparse module.

bpo-32874 [https://bugs.python.org/issue?@action=redirect&bpo=32874]: Add tests for pyparse.

bpo-32837 [https://bugs.python.org/issue?@action=redirect&bpo=32837]: Using the system and place-dependent default encoding for open() is a bad idea for IDLE’s system and location-independent files.

bpo-32826 [https://bugs.python.org/issue?@action=redirect&bpo=32826]: Add «encoding=utf-8» to open() in IDLE’s test_help_about. GUI test test_file_buttons() only looks at initial ascii-only lines, but failed on systems where open() defaults to “ascii” because readline() internally reads and decodes far enough ahead to encounter a non-ascii character in CREDITS.txt.

bpo-32765 [https://bugs.python.org/issue?@action=redirect&bpo=32765]: Update configdialog General tab docstring to add new widgets to the widget list.

Tools/Demos

bpo-32222 [https://bugs.python.org/issue?@action=redirect&bpo=32222]: Fix pygettext not extracting docstrings for functions with type annotated arguments. Patch by Toby Harradine.

Python 3.7.0 beta 1

Release date: 2018-01-30

Core and Builtins

bpo-32703 [https://bugs.python.org/issue?@action=redirect&bpo=32703]: Fix coroutine’s ResourceWarning when there’s an active error set when it’s being finalized.

bpo-32650 [https://bugs.python.org/issue?@action=redirect&bpo=32650]: Pdb and other debuggers dependent on bdb.py will correctly step over (next command) native coroutines. Patch by Pablo Galindo.

bpo-28685 [https://bugs.python.org/issue?@action=redirect&bpo=28685]: Optimize list.sort() and sorted() by using type specialized comparisons when possible.

bpo-32685 [https://bugs.python.org/issue?@action=redirect&bpo=32685]: Improve suggestion when the Python 2 form of print statement is either present on the same line as the header of a compound statement or else terminated by a semi-colon instead of a newline. Patch by Nitish Chandra.

bpo-32697 [https://bugs.python.org/issue?@action=redirect&bpo=32697]: Python now explicitly preserves the definition order of keyword-only parameters. It’s always preserved their order, but this behavior was never guaranteed before; this behavior is now guaranteed and tested.

bpo-32690 [https://bugs.python.org/issue?@action=redirect&bpo=32690]: The locals() dictionary now displays in the lexical order that variables were defined. Previously, the order was reversed.

bpo-32677 [https://bugs.python.org/issue?@action=redirect&bpo=32677]: Add .isascii() method to str, bytes and bytearray. It can be used to test that string contains only ASCII characters.

bpo-32670 [https://bugs.python.org/issue?@action=redirect&bpo=32670]: Enforce PEP 479 [https://www.python.org/dev/peps/pep-0479] for all code. This means that manually raising a StopIteration exception from a generator is prohibited for all code, regardless of whether “from __future__ import generator_stop” was used or not.

bpo-32591 [https://bugs.python.org/issue?@action=redirect&bpo=32591]: Added built-in support for tracking the origin of coroutine objects; see sys.set_coroutine_origin_tracking_depth and CoroutineType.cr_origin. This replaces the asyncio debug mode’s use of coroutine wrapping for native coroutine objects.

bpo-31368 [https://bugs.python.org/issue?@action=redirect&bpo=31368]: Expose preadv and pwritev system calls in the os module. Patch by Pablo Galindo

bpo-32544 [https://bugs.python.org/issue?@action=redirect&bpo=32544]: hasattr(obj, name) and getattr(obj, name, default) are about 4 times faster than before when name is not found and obj doesn’t override __getattr__ or __getattribute__.

bpo-26163 [https://bugs.python.org/issue?@action=redirect&bpo=26163]: Improved frozenset() hash to create more distinct hash values when faced with datasets containing many similar values.

bpo-32550 [https://bugs.python.org/issue?@action=redirect&bpo=32550]: Remove the STORE_ANNOTATION bytecode.

bpo-20104 [https://bugs.python.org/issue?@action=redirect&bpo=20104]: Expose posix_spawn as a low level API in the os module. (removed before 3.7.0rc1)

bpo-24340 [https://bugs.python.org/issue?@action=redirect&bpo=24340]: Fixed estimation of the code stack size.

bpo-32436 [https://bugs.python.org/issue?@action=redirect&bpo=32436]: Implement PEP 567 [https://www.python.org/dev/peps/pep-0567] Context Variables.

bpo-18533 [https://bugs.python.org/issue?@action=redirect&bpo=18533]: repr() on a dict containing its own values() or items() no longer raises RecursionError; OrderedDict similarly. Instead, use ..., as for other recursive structures. Patch by Ben North.

bpo-20891 [https://bugs.python.org/issue?@action=redirect&bpo=20891]: Py_Initialize() now creates the GIL. The GIL is no longer created «on demand» to fix a race condition when PyGILState_Ensure() is called in a non-Python thread.

bpo-32028 [https://bugs.python.org/issue?@action=redirect&bpo=32028]: Leading whitespace is now correctly ignored when generating suggestions for converting Py2 print statements to Py3 builtin print function calls. Patch by Sanyam Khurana.

bpo-31179 [https://bugs.python.org/issue?@action=redirect&bpo=31179]: Make dict.copy() up to 5.5 times faster.

bpo-31113 [https://bugs.python.org/issue?@action=redirect&bpo=31113]: Get rid of recursion in the compiler for normal control flow.

Library

bpo-25988 [https://bugs.python.org/issue?@action=redirect&bpo=25988]: Deprecate exposing the contents of collections.abc in the regular collections module.

bpo-31429 [https://bugs.python.org/issue?@action=redirect&bpo=31429]: The default cipher suite selection of the ssl module now uses a blacklist approach rather than a hard-coded whitelist. Python no longer re-enables ciphers that have been blocked by OpenSSL security update. Default cipher suite selection can be configured on compile time.

bpo-30306 [https://bugs.python.org/issue?@action=redirect&bpo=30306]: contextlib.contextmanager now releases the arguments passed to the underlying generator as soon as the context manager is entered. Previously it would keep them alive for as long as the context manager was alive, even when not being used as a function decorator. Patch by Martin Teichmann.

bpo-21417 [https://bugs.python.org/issue?@action=redirect&bpo=21417]: Added support for setting the compression level for zipfile.ZipFile.

bpo-32251 [https://bugs.python.org/issue?@action=redirect&bpo=32251]: Implement asyncio.BufferedProtocol (provisional API).

bpo-32513 [https://bugs.python.org/issue?@action=redirect&bpo=32513]: In dataclasses, allow easier overriding of dunder methods without specifying decorator parameters.

bpo-32660 [https://bugs.python.org/issue?@action=redirect&bpo=32660]: termios makes available FIONREAD, FIONCLEX, FIOCLEX, FIOASYNC and FIONBIO also under Solaris/derivatives.

bpo-27931 [https://bugs.python.org/issue?@action=redirect&bpo=27931]: Fix email address header parsing error when the username is an empty quoted string. Patch by Xiang Zhang.

bpo-32659 [https://bugs.python.org/issue?@action=redirect&bpo=32659]: Under Solaris and derivatives, os.stat_result provides a st_fstype attribute.

bpo-32662 [https://bugs.python.org/issue?@action=redirect&bpo=32662]: Implement Server.start_serving(), Server.serve_forever(), and Server.is_serving() methods. Add “start_serving” keyword parameter to loop.create_server() and loop.create_unix_server().

bpo-32391 [https://bugs.python.org/issue?@action=redirect&bpo=32391]: Implement asyncio.StreamWriter.wait_closed() and asyncio.StreamWriter.is_closing() methods

bpo-32643 [https://bugs.python.org/issue?@action=redirect&bpo=32643]: Make Task._step, Task._wakeup and Future._schedule_callbacks methods private.

bpo-32630 [https://bugs.python.org/issue?@action=redirect&bpo=32630]: Refactor decimal module to use contextvars to store decimal context.

bpo-32622 [https://bugs.python.org/issue?@action=redirect&bpo=32622]: Add asyncio.AbstractEventLoop.sendfile() method.

bpo-32304 [https://bugs.python.org/issue?@action=redirect&bpo=32304]: distutils” upload command no longer corrupts tar files ending with a CR byte, and no longer tries to convert CR to CRLF in any of the upload text fields.

bpo-32502 [https://bugs.python.org/issue?@action=redirect&bpo=32502]: uuid.uuid1 no longer raises an exception if a 64-bit hardware address is encountered.

bpo-32596 [https://bugs.python.org/issue?@action=redirect&bpo=32596]: concurrent.futures imports ThreadPoolExecutor and ProcessPoolExecutor lazily (using PEP 562 [https://www.python.org/dev/peps/pep-0562]). It makes import asyncio about 15% faster because asyncio uses only ThreadPoolExecutor by default.

bpo-31801 [https://bugs.python.org/issue?@action=redirect&bpo=31801]: Add _ignore_ to Enum so temporary variables can be used during class construction without being turned into members.

bpo-32576 [https://bugs.python.org/issue?@action=redirect&bpo=32576]: Use queue.SimpleQueue() in places where it can be invoked from a weakref callback.

bpo-32574 [https://bugs.python.org/issue?@action=redirect&bpo=32574]: Fix memory leak in asyncio.Queue, when the queue has limited size and it is full, the cancelation of queue.put() can cause a memory leak. Patch by: José Melero.

bpo-32521 [https://bugs.python.org/issue?@action=redirect&bpo=32521]: The nis module is now compatible with new libnsl and headers location.

bpo-32467 [https://bugs.python.org/issue?@action=redirect&bpo=32467]: collections.abc.ValuesView now inherits from collections.abc.Collection.

bpo-32473 [https://bugs.python.org/issue?@action=redirect&bpo=32473]: Improve ABCMeta._dump_registry() output readability

bpo-32102 [https://bugs.python.org/issue?@action=redirect&bpo=32102]: New argument capture_output for subprocess.run

bpo-32521 [https://bugs.python.org/issue?@action=redirect&bpo=32521]: glibc has removed Sun RPC. Use replacement libtirpc headers and library in nis module.

bpo-32493 [https://bugs.python.org/issue?@action=redirect&bpo=32493]: UUID module fixes build for FreeBSD/OpenBSD

bpo-32503 [https://bugs.python.org/issue?@action=redirect&bpo=32503]: Pickling with protocol 4 no longer creates too small frames.

bpo-29237 [https://bugs.python.org/issue?@action=redirect&bpo=29237]: Create enum for pstats sorting options

bpo-32454 [https://bugs.python.org/issue?@action=redirect&bpo=32454]: Add close(fd) function to the socket module.

bpo-25942 [https://bugs.python.org/issue?@action=redirect&bpo=25942]: The subprocess module is now more graceful when handling a Ctrl-C KeyboardInterrupt during subprocess.call, subprocess.run, or a Popen context manager. It now waits a short amount of time for the child (presumed to have also gotten the SIGINT) to exit, before continuing the KeyboardInterrupt exception handling. This still includes a SIGKILL in the call() and run() APIs, but at least the child had a chance first.

bpo-32433 [https://bugs.python.org/issue?@action=redirect&bpo=32433]: The hmac module now has hmac.digest(), which provides an optimized HMAC digest.

bpo-28134 [https://bugs.python.org/issue?@action=redirect&bpo=28134]: Sockets now auto-detect family, type and protocol from file descriptor by default.

bpo-32404 [https://bugs.python.org/issue?@action=redirect&bpo=32404]: Fix bug where datetime.datetime.fromtimestamp() did not call __new__ in datetime.datetime subclasses.

bpo-32403 [https://bugs.python.org/issue?@action=redirect&bpo=32403]: Improved speed of datetime.date and datetime.datetime alternate constructors.

bpo-32228 [https://bugs.python.org/issue?@action=redirect&bpo=32228]: Ensure that truncate() preserves the file position (as reported by tell()) after writes longer than the buffer size.

bpo-32410 [https://bugs.python.org/issue?@action=redirect&bpo=32410]: Implement loop.sock_sendfile for asyncio event loop.

bpo-22908 [https://bugs.python.org/issue?@action=redirect&bpo=22908]: Added seek and tell to the ZipExtFile class. This only works if the file object used to open the zipfile is seekable.

bpo-32373 [https://bugs.python.org/issue?@action=redirect&bpo=32373]: Add socket.getblocking() method.

bpo-32248 [https://bugs.python.org/issue?@action=redirect&bpo=32248]: Add importlib.resources and importlib.abc.ResourceReader as the unified API for reading resources contained within packages. Loaders wishing to support resource reading must implement the get_resource_reader() method. File-based and zipimport-based loaders both implement these APIs. importlib.abc.ResourceLoader is deprecated in favor of these new APIs.

bpo-32320 [https://bugs.python.org/issue?@action=redirect&bpo=32320]: collections.namedtuple() now supports default values.

bpo-29302 [https://bugs.python.org/issue?@action=redirect&bpo=29302]: Add contextlib.AsyncExitStack. Patch by Alexander Mohr and Ilya Kulakov.

bpo-31961 [https://bugs.python.org/issue?@action=redirect&bpo=31961]: Removed in Python 3.7.0b2. The args argument of subprocess.Popen can now be a path-like object. If args is given as a sequence, it’s first element can now be a path-like object as well.

bpo-31900 [https://bugs.python.org/issue?@action=redirect&bpo=31900]: The locale.localeconv() function now sets temporarily the LC_CTYPE locale to the LC_NUMERIC locale to decode decimal_point and thousands_sep byte strings if they are non-ASCII or longer than 1 byte, and the LC_NUMERIC locale is different than the LC_CTYPE locale. This temporary change affects other threads. Same change for the str.format() method when formatting a number (int, float, float and subclasses) with the n type (ex: '{:n}'.format(1234)).

bpo-31853 [https://bugs.python.org/issue?@action=redirect&bpo=31853]: Use super().method instead of socket.method in SSLSocket. They were there most likely for legacy reasons.

bpo-31399 [https://bugs.python.org/issue?@action=redirect&bpo=31399]: The ssl module now uses OpenSSL’s X509_VERIFY_PARAM_set1_host() and X509_VERIFY_PARAM_set1_ip() API to verify hostname and IP addresses. Subject common name fallback can be disabled with SSLContext.hostname_checks_common_name.

bpo-14976 [https://bugs.python.org/issue?@action=redirect&bpo=14976]: Add a queue.SimpleQueue class, an unbounded FIFO queue with a reentrant C implementation of put().

Documentation

bpo-32724 [https://bugs.python.org/issue?@action=redirect&bpo=32724]: Add references to some commands in the documentation of Pdb. Patch by Stéphane Wirtel

bpo-32649 [https://bugs.python.org/issue?@action=redirect&bpo=32649]: Complete the C API documentation, profiling and tracing part with the newly added per-opcode events.

bpo-17799 [https://bugs.python.org/issue?@action=redirect&bpo=17799]: Explain real behaviour of sys.settrace and sys.setprofile and their C-API counterparts regarding which type of events are received in each function. Patch by Pablo Galindo Salgado.

Tests

bpo-32721 [https://bugs.python.org/issue?@action=redirect&bpo=32721]: Fix test_hashlib to not fail if the _md5 module is not built.

bpo-28414 [https://bugs.python.org/issue?@action=redirect&bpo=28414]: Add test cases for IDNA 2003 and 2008 host names. IDNA 2003 internationalized host names are working since bpo-31399 [https://bugs.python.org/issue?@action=redirect&bpo=31399] has landed. IDNA 2008 are still broken.

bpo-32604 [https://bugs.python.org/issue?@action=redirect&bpo=32604]: Add a new «_xxsubinterpreters» extension module that exposes the existing subinterpreter C-API and a new cross-interpreter data sharing mechanism. The module is primarily intended for more thorough testing of the existing subinterpreter support. Note that the _xxsubinterpreters module has been removed in 3.7.0rc1.

bpo-32602 [https://bugs.python.org/issue?@action=redirect&bpo=32602]: Add test certs and test for ECDSA cert and EC/RSA dual mode.

bpo-32549 [https://bugs.python.org/issue?@action=redirect&bpo=32549]: On Travis CI, Python now Compiles and uses a local copy of OpenSSL 1.1.0g for testing.

Build

bpo-32635 [https://bugs.python.org/issue?@action=redirect&bpo=32635]: Fix segfault of the crypt module when libxcrypt is provided instead of libcrypt at the system.

bpo-32598 [https://bugs.python.org/issue?@action=redirect&bpo=32598]: Use autoconf to detect OpenSSL libs, headers and supported features. The ax_check_openssl M4 macro uses pkg-config to locate OpenSSL and falls back to manual search.

bpo-32593 [https://bugs.python.org/issue?@action=redirect&bpo=32593]: Drop support of FreeBSD 9 and older.

bpo-29708 [https://bugs.python.org/issue?@action=redirect&bpo=29708]: If the SOURCE_DATE_EPOCH environment variable is set, py_compile will always create hash-based .pyc files.

Windows

bpo-32588 [https://bugs.python.org/issue?@action=redirect&bpo=32588]: Create standalone _distutils_findvs module and add missing _queue module to installer.

bpo-29911 [https://bugs.python.org/issue?@action=redirect&bpo=29911]: Ensure separate Modify and Uninstall buttons are displayed.

bpo-32507 [https://bugs.python.org/issue?@action=redirect&bpo=32507]: Use app-local UCRT install rather than the proper update for old versions of Windows.

macOS

bpo-32726 [https://bugs.python.org/issue?@action=redirect&bpo=32726]: Provide an additional, more modern macOS installer variant that supports macOS 10.9+ systems in 64-bit mode only. Upgrade the supplied third-party libraries to OpenSSL 1.1.0g and to SQLite 3.22.0. The 10.9+ installer now links with and supplies its own copy of Tcl/Tk 8.6.

bpo-28440 [https://bugs.python.org/issue?@action=redirect&bpo=28440]: No longer add /Library/Python/3.x/site-packages to sys.path for macOS framework builds to avoid future conflicts.

C API

bpo-32681 [https://bugs.python.org/issue?@action=redirect&bpo=32681]: Fix uninitialized variable “res” in the C implementation of os.dup2. Patch by Stéphane Wirtel

bpo-10381 [https://bugs.python.org/issue?@action=redirect&bpo=10381]: Add C API access to the datetime.timezone constructor and datetime.timzone.UTC singleton.

Python 3.7.0 alpha 4

Release date: 2018-01-08

Core and Builtins

bpo-31975 [https://bugs.python.org/issue?@action=redirect&bpo=31975]: The default warning filter list now starts with a «default::DeprecationWarning:__main__» entry, so deprecation warnings are once again shown by default in single-file scripts and at the interactive prompt.

bpo-32226 [https://bugs.python.org/issue?@action=redirect&bpo=32226]: __class_getitem__ is now an automatic class method.

bpo-32399 [https://bugs.python.org/issue?@action=redirect&bpo=32399]: Add AIX uuid library support for RFC4122 using uuid_create() in libc.a

bpo-32390 [https://bugs.python.org/issue?@action=redirect&bpo=32390]: Fix the compilation failure on AIX after the f_fsid field has been added to the object returned by os.statvfs() (bpo-32143 [https://bugs.python.org/issue?@action=redirect&bpo=32143]). Original patch by Michael Felt.

bpo-32379 [https://bugs.python.org/issue?@action=redirect&bpo=32379]: Make MRO computation faster when a class inherits from a single base.

bpo-32259 [https://bugs.python.org/issue?@action=redirect&bpo=32259]: The error message of a TypeError raised when unpack non-iterable is now more specific.

bpo-27169 [https://bugs.python.org/issue?@action=redirect&bpo=27169]: The __debug__ constant is now optimized out at compile time. This fixes also bpo-22091 [https://bugs.python.org/issue?@action=redirect&bpo=22091].

bpo-32329 [https://bugs.python.org/issue?@action=redirect&bpo=32329]: The -R option now turns on hash randomization when the PYTHONHASHSEED environment variable is set to 0. Previously, the option was ignored. Moreover, sys.flags.hash_randomization is now properly set to 0 when hash randomization is turned off by PYTHONHASHSEED=0.

bpo-30416 [https://bugs.python.org/issue?@action=redirect&bpo=30416]: The optimizer is now protected from spending much time doing complex calculations and consuming much memory for creating large constants in constant folding. Increased limits for constants that can be produced in constant folding.

bpo-32282 [https://bugs.python.org/issue?@action=redirect&bpo=32282]: Fix an unnecessary ifdef in the include of VersionHelpers.h in socketmodule on Windows.

bpo-30579 [https://bugs.python.org/issue?@action=redirect&bpo=30579]: Implement TracebackType.__new__ to allow Python-level creation of traceback objects, and make TracebackType.tb_next mutable.

bpo-32260 [https://bugs.python.org/issue?@action=redirect&bpo=32260]: Don’t byte swap the input keys to the SipHash algorithm on big-endian platforms. This should ensure siphash gives consistent results across platforms.

bpo-31506 [https://bugs.python.org/issue?@action=redirect&bpo=31506]: Improve the error message logic for object.__new__ and object.__init__. Patch by Sanyam Khurana.

bpo-20361 [https://bugs.python.org/issue?@action=redirect&bpo=20361]: -b and -bb now inject 'default::BytesWarning' and error::BytesWarning entries into sys.warnoptions, ensuring that they take precedence over any other warning filters configured via the -W option or the PYTHONWARNINGS environment variable.

bpo-32230 [https://bugs.python.org/issue?@action=redirect&bpo=32230]: -X dev now injects a 'default' entry into sys.warnoptions, ensuring that it behaves identically to actually passing -Wdefault at the command line.

bpo-29240 [https://bugs.python.org/issue?@action=redirect&bpo=29240]: Add a new UTF-8 mode: implementation of the PEP 540 [https://www.python.org/dev/peps/pep-0540].

bpo-32226 [https://bugs.python.org/issue?@action=redirect&bpo=32226]: PEP 560 [https://www.python.org/dev/peps/pep-0560]: Add support for __mro_entries__ and __class_getitem__. Implemented by Ivan Levkivskyi.

bpo-32225 [https://bugs.python.org/issue?@action=redirect&bpo=32225]: PEP 562 [https://www.python.org/dev/peps/pep-0562]: Add support for module __getattr__ and __dir__. Implemented by Ivan Levkivskyi.

bpo-31901 [https://bugs.python.org/issue?@action=redirect&bpo=31901]: The atexit module now has its callback stored per interpreter.

bpo-31650 [https://bugs.python.org/issue?@action=redirect&bpo=31650]: Implement PEP 552 [https://www.python.org/dev/peps/pep-0552] (Deterministic pycs). Python now supports invalidating bytecode cache files bashed on a source content hash rather than source last-modified time.

bpo-29469 [https://bugs.python.org/issue?@action=redirect&bpo=29469]: Move constant folding from bytecode layer to AST layer. Original patch by Eugene Toder.

Library

bpo-32506 [https://bugs.python.org/issue?@action=redirect&bpo=32506]: Now that dict is defined as keeping insertion order, drop OrderedDict and just use plain dict.

bpo-32279 [https://bugs.python.org/issue?@action=redirect&bpo=32279]: Add params to dataclasses.make_dataclasses(): init, repr, eq, order, hash, and frozen. Pass them through to dataclass().

bpo-32278 [https://bugs.python.org/issue?@action=redirect&bpo=32278]: Make type information optional on dataclasses.make_dataclass(). If omitted, the string “typing.Any” is used.

bpo-32499 [https://bugs.python.org/issue?@action=redirect&bpo=32499]: Add dataclasses.is_dataclass(obj), which returns True if obj is a dataclass or an instance of one.

bpo-32468 [https://bugs.python.org/issue?@action=redirect&bpo=32468]: Improve frame repr() to mention filename, code name and current line number.

bpo-23749 [https://bugs.python.org/issue?@action=redirect&bpo=23749]: asyncio: Implement loop.start_tls()

bpo-32441 [https://bugs.python.org/issue?@action=redirect&bpo=32441]: Return the new file descriptor (i.e., the second argument) from os.dup2. Previously, None was always returned.

bpo-32422 [https://bugs.python.org/issue?@action=redirect&bpo=32422]: functools.lru_cache uses less memory (3 words for each cached key) and takes about 1/3 time for cyclic GC.

bpo-31721 [https://bugs.python.org/issue?@action=redirect&bpo=31721]: Prevent Python crash from happening when Future._log_traceback is set to True manually. Now it can only be set to False, or a ValueError is raised.

bpo-32415 [https://bugs.python.org/issue?@action=redirect&bpo=32415]: asyncio: Add Task.get_loop() and Future.get_loop()

bpo-26133 [https://bugs.python.org/issue?@action=redirect&bpo=26133]: Don’t unsubscribe signals in asyncio UNIX event loop on interpreter shutdown.

bpo-32363 [https://bugs.python.org/issue?@action=redirect&bpo=32363]: Make asyncio.Task.set_exception() and set_result() raise NotImplementedError. Task._step() and Future.__await__() raise proper exceptions when they are in an invalid state, instead of raising an AssertionError.

bpo-32357 [https://bugs.python.org/issue?@action=redirect&bpo=32357]: Optimize asyncio.iscoroutine() and loop.create_task() for non-native coroutines (e.g. async/await compiled with Cython). “loop.create_task(python_coroutine)” used to be 20% faster than “loop.create_task(cython_coroutine)”. Now, the latter is as fast.

bpo-32356 [https://bugs.python.org/issue?@action=redirect&bpo=32356]: asyncio.transport.resume_reading() and pause_reading() are now idempotent. New transport.is_reading() method is added.

bpo-32355 [https://bugs.python.org/issue?@action=redirect&bpo=32355]: Optimize asyncio.gather(); now up to 15% faster.

bpo-32351 [https://bugs.python.org/issue?@action=redirect&bpo=32351]: Use fastpath in asyncio.sleep if delay<0 (2x boost)

bpo-32348 [https://bugs.python.org/issue?@action=redirect&bpo=32348]: Optimize asyncio.Future schedule/add/remove callback. The optimization shows 3-6% performance improvements of async/await code.

bpo-32331 [https://bugs.python.org/issue?@action=redirect&bpo=32331]: Fix socket.settimeout() and socket.setblocking() to keep socket.type as is. Fix socket.socket() constructor to reset any bit flags applied to socket’s type. This change only affects OSes that have SOCK_NONBLOCK and/or SOCK_CLOEXEC.

bpo-32248 [https://bugs.python.org/issue?@action=redirect&bpo=32248]: Add importlib.abc.ResourceReader as an ABC for loaders to provide a unified API for reading resources contained within packages. Also add importlib.resources as the port of importlib_resources.

bpo-32311 [https://bugs.python.org/issue?@action=redirect&bpo=32311]: Implement asyncio.create_task(coro) shortcut

bpo-32327 [https://bugs.python.org/issue?@action=redirect&bpo=32327]: Convert asyncio functions that were documented as coroutines to coroutines. Affected functions: loop.sock_sendall, loop.sock_recv, loop.sock_accept, loop.getaddrinfo, loop.getnameinfo.

bpo-32323 [https://bugs.python.org/issue?@action=redirect&bpo=32323]: urllib.parse.urlsplit() does not convert zone-id (scope) to lower case for scoped IPv6 addresses in hostnames now.

bpo-32302 [https://bugs.python.org/issue?@action=redirect&bpo=32302]: Fix bdist_wininst of distutils for CRT v142: it binary compatible with CRT v140.

bpo-29711 [https://bugs.python.org/issue?@action=redirect&bpo=29711]: Fix stop_serving in asyncio proactor loop kill all listening servers

bpo-32308 [https://bugs.python.org/issue?@action=redirect&bpo=32308]: re.sub() now replaces empty matches adjacent to a previous non-empty match.

bpo-29970 [https://bugs.python.org/issue?@action=redirect&bpo=29970]: Abort asyncio SSLProtocol connection if handshake not complete within 10s

bpo-32314 [https://bugs.python.org/issue?@action=redirect&bpo=32314]: Implement asyncio.run().

bpo-17852 [https://bugs.python.org/issue?@action=redirect&bpo=17852]: Revert incorrect fix based on misunderstanding of _Py_PyAtExit() semantics.

bpo-32296 [https://bugs.python.org/issue?@action=redirect&bpo=32296]: Implement asyncio._get_running_loop() and get_event_loop() in C. This makes them 4x faster.

bpo-32250 [https://bugs.python.org/issue?@action=redirect&bpo=32250]: Implement asyncio.current_task() and asyncio.all_tasks(). Add helpers intended to be used by alternative task implementations: asyncio._register_task, asyncio._enter_task, asyncio._leave_task and asyncio._unregister_task. Deprecate asyncio.Task.current_task() and asyncio.Task.all_tasks().

bpo-32255 [https://bugs.python.org/issue?@action=redirect&bpo=32255]: A single empty field is now always quoted when written into a CSV file. This allows to distinguish an empty row from a row consisting of a single empty field. Patch by Licht Takeuchi.

bpo-32277 [https://bugs.python.org/issue?@action=redirect&bpo=32277]: Raise NotImplementedError instead of SystemError on platforms where chmod(..., follow_symlinks=False) is not supported. Patch by Anthony Sottile.

bpo-30050 [https://bugs.python.org/issue?@action=redirect&bpo=30050]: New argument warn_on_full_buffer to signal.set_wakeup_fd lets you control whether Python prints a warning on stderr when the wakeup fd buffer overflows.

bpo-29137 [https://bugs.python.org/issue?@action=redirect&bpo=29137]: The fpectl library has been removed. It was never enabled by default, never worked correctly on x86-64, and it changed the Python ABI in ways that caused unexpected breakage of C extensions.

bpo-32273 [https://bugs.python.org/issue?@action=redirect&bpo=32273]: Move asyncio.test_utils to test.test_asyncio.

bpo-32272 [https://bugs.python.org/issue?@action=redirect&bpo=32272]: Remove asyncio.async() function.

bpo-32269 [https://bugs.python.org/issue?@action=redirect&bpo=32269]: Add asyncio.get_running_loop() function.

bpo-32265 [https://bugs.python.org/issue?@action=redirect&bpo=32265]: All class and static methods of builtin types now are correctly classified by inspect.classify_class_attrs() and grouped in pydoc ouput. Added types.ClassMethodDescriptorType for unbound class methods of builtin types.

bpo-32253 [https://bugs.python.org/issue?@action=redirect&bpo=32253]: Deprecate yield from lock, await lock, with (yield from lock) and with await lock for asyncio synchronization primitives.

bpo-22589 [https://bugs.python.org/issue?@action=redirect&bpo=22589]: Changed MIME type of .bmp from “image/x-ms-bmp” to “image/bmp”

bpo-32193 [https://bugs.python.org/issue?@action=redirect&bpo=32193]: Convert asyncio to use async/await syntax. Old styled yield from is still supported too.

bpo-32206 [https://bugs.python.org/issue?@action=redirect&bpo=32206]: Add support to run modules with pdb

bpo-32227 [https://bugs.python.org/issue?@action=redirect&bpo=32227]: functools.singledispatch now supports registering implementations using type annotations.

bpo-15873 [https://bugs.python.org/issue?@action=redirect&bpo=15873]: Added new alternate constructors datetime.datetime.fromisoformat(), datetime.time.fromisoformat() and datetime.date.fromisoformat() as the inverse operation of each classes’s respective isoformat methods.

bpo-32199 [https://bugs.python.org/issue?@action=redirect&bpo=32199]: The getnode() ip getter now uses “ip link” instead of “ip link list”.

bpo-32143 [https://bugs.python.org/issue?@action=redirect&bpo=32143]: os.statvfs() includes the f_fsid field from statvfs(2)

bpo-26439 [https://bugs.python.org/issue?@action=redirect&bpo=26439]: Fix ctypes.util.find_library() for AIX by implementing ctypes._aix.find_library() Patch by: Michael Felt

bpo-31993 [https://bugs.python.org/issue?@action=redirect&bpo=31993]: The pickler now uses less memory when serializing large bytes and str objects into a file. Pickles created with protocol 4 will require less memory for unpickling large bytes and str objects.

bpo-27456 [https://bugs.python.org/issue?@action=redirect&bpo=27456]: Ensure TCP_NODELAY is set on Linux. Tests by Victor Stinner.

bpo-31778 [https://bugs.python.org/issue?@action=redirect&bpo=31778]: ast.literal_eval() is now more strict. Addition and subtraction of arbitrary numbers no longer allowed.

bpo-31802 [https://bugs.python.org/issue?@action=redirect&bpo=31802]: Importing native path module (posixpath, ntpath) now works even if the os module still is not imported.

bpo-30241 [https://bugs.python.org/issue?@action=redirect&bpo=30241]: Add contextlib.AbstractAsyncContextManager. Patch by Jelle Zijlstra.

bpo-31699 [https://bugs.python.org/issue?@action=redirect&bpo=31699]: Fix deadlocks in concurrent.futures.ProcessPoolExecutor when task arguments or results cause pickling or unpickling errors. This should make sure that calls to the ProcessPoolExecutor API always eventually return.

bpo-15216 [https://bugs.python.org/issue?@action=redirect&bpo=15216]: TextIOWrapper.reconfigure() supports changing encoding, errors, and newline.

Documentation

bpo-32418 [https://bugs.python.org/issue?@action=redirect&bpo=32418]: Add get_loop() method to Server and AbstractServer classes.

Tests

bpo-32252 [https://bugs.python.org/issue?@action=redirect&bpo=32252]: Fix faulthandler_suppress_crash_report() used to prevent core dump files when testing crashes. getrlimit() returns zero on success.

bpo-32002 [https://bugs.python.org/issue?@action=redirect&bpo=32002]: Adjust C locale coercion testing for the empty locale and POSIX locale cases to more readily adjust to platform dependent behaviour.

Windows

bpo-19764 [https://bugs.python.org/issue?@action=redirect&bpo=19764]: Implement support for subprocess.Popen(close_fds=True) on Windows. Patch by Segev Finer.

Tools/Demos

bpo-24960 [https://bugs.python.org/issue?@action=redirect&bpo=24960]: 2to3 and lib2to3 can now read pickled grammar files using pkgutil.get_data() rather than probing the filesystem. This lets 2to3 and lib2to3 work when run from a zipfile.

C API

bpo-32030 [https://bugs.python.org/issue?@action=redirect&bpo=32030]: Py_Initialize() doesn’t reset the memory allocators to default if the PYTHONMALLOC environment variable is not set.

bpo-29084 [https://bugs.python.org/issue?@action=redirect&bpo=29084]: Undocumented C API for OrderedDict has been excluded from the limited C API. It was added by mistake and actually never worked in the limited C API.

bpo-32264 [https://bugs.python.org/issue?@action=redirect&bpo=32264]: Moved the pygetopt.h header into internal/, since it has no public APIs.

bpo-32241 [https://bugs.python.org/issue?@action=redirect&bpo=32241]: Py_SetProgramName() and Py_SetPythonHome() now take the const wchar * arguments instead of wchar *.

Python 3.7.0 alpha 3

Release date: 2017-12-05

Core and Builtins

bpo-32176 [https://bugs.python.org/issue?@action=redirect&bpo=32176]: co_flags.CO_NOFREE is now always set correctly by the code object constructor based on freevars and cellvars, rather than needing to be set correctly by the caller. This ensures it will be cleared automatically when additional cell references are injected into a modified code object and function.

bpo-10544 [https://bugs.python.org/issue?@action=redirect&bpo=10544]: Yield expressions are now deprecated in comprehensions and generator expressions. They are still permitted in the definition of the outermost iterable, as that is evaluated directly in the enclosing scope.

bpo-32137 [https://bugs.python.org/issue?@action=redirect&bpo=32137]: The repr of deeply nested dict now raises a RecursionError instead of crashing due to a stack overflow.

bpo-32096 [https://bugs.python.org/issue?@action=redirect&bpo=32096]: Revert memory allocator changes in the C API: move structures back from _PyRuntime to Objects/obmalloc.c. The memory allocators are once again initialized statically, and so PyMem_RawMalloc() and Py_DecodeLocale() can be called before _PyRuntime_Initialize().

bpo-32043 [https://bugs.python.org/issue?@action=redirect&bpo=32043]: Add a new «developer mode»: new «-X dev» command line option to enable debug checks at runtime.

bpo-32023 [https://bugs.python.org/issue?@action=redirect&bpo=32023]: SyntaxError is now correctly raised when a generator expression without parenthesis is used instead of an inheritance list in a class definition. The duplication of the parentheses can be omitted only on calls.

bpo-32012 [https://bugs.python.org/issue?@action=redirect&bpo=32012]: SyntaxError is now correctly raised when a generator expression without parenthesis is passed as an argument, but followed by a trailing comma. A generator expression always needs to be directly inside a set of parentheses and cannot have a comma on either side.

bpo-28180 [https://bugs.python.org/issue?@action=redirect&bpo=28180]: A new internal _Py_SetLocaleFromEnv(category) helper function has been added in order to improve the consistency of behaviour across different libc implementations (e.g. Android doesn’t support setting the locale from the environment by default).

bpo-31949 [https://bugs.python.org/issue?@action=redirect&bpo=31949]: Fixed several issues in printing tracebacks (PyTraceBack_Print()). Setting sys.tracebacklimit to 0 or less now suppresses printing tracebacks. Setting sys.tracebacklimit to None now causes using the default limit. Setting sys.tracebacklimit to an integer larger than LONG_MAX now means using the limit LONG_MAX rather than the default limit. Fixed integer overflows in the case of more than 2**31 traceback items on Windows. Fixed output errors handling.

bpo-30696 [https://bugs.python.org/issue?@action=redirect&bpo=30696]: Fix the interactive interpreter looping endlessly when no memory.

bpo-20047 [https://bugs.python.org/issue?@action=redirect&bpo=20047]: Bytearray methods partition() and rpartition() now accept only bytes-like objects as separator, as documented. In particular they now raise TypeError rather of returning a bogus result when an integer is passed as a separator.

bpo-21720 [https://bugs.python.org/issue?@action=redirect&bpo=21720]: BytesWarning no longer emitted when the fromlist argument of __import__() or the __all__ attribute of the module contain bytes instances.

bpo-31845 [https://bugs.python.org/issue?@action=redirect&bpo=31845]: Environment variables are once more read correctly at interpreter startup.

bpo-28936 [https://bugs.python.org/issue?@action=redirect&bpo=28936]: Ensure that lexically first syntax error involving a parameter and global or nonlocal is detected first at a given scope. Patch by Ivan Levkivskyi.

bpo-31825 [https://bugs.python.org/issue?@action=redirect&bpo=31825]: Fixed OverflowError in the “unicode-escape” codec and in codecs.escape_decode() when decode an escaped non-ascii byte.

bpo-31618 [https://bugs.python.org/issue?@action=redirect&bpo=31618]: The per-frame tracing logic added in 3.7a1 has been altered so that frame->f_lineno is updated before either "line" or "opcode" events are emitted. Previously, opcode events were emitted first, and therefore would occasionally see stale line numbers on the frame. The behavior of this feature has changed slightly as a result: when both f_trace_lines and f_trace_opcodes are enabled, line events now occur first.

bpo-28603 [https://bugs.python.org/issue?@action=redirect&bpo=28603]: Print the full context/cause chain of exceptions on interpreter exit, even if an exception in the chain is unhashable or compares equal to later ones. Patch by Zane Bitter.

bpo-31786 [https://bugs.python.org/issue?@action=redirect&bpo=31786]: Fix timeout rounding in the select module to round correctly negative timeouts between -1.0 and 0.0. The functions now block waiting for events as expected. Previously, the call was incorrectly non-blocking. Patch by Pablo Galindo.

bpo-31781 [https://bugs.python.org/issue?@action=redirect&bpo=31781]: Prevent crashes when calling methods of an uninitialized zipimport.zipimporter object. Patch by Oren Milman.

bpo-30399 [https://bugs.python.org/issue?@action=redirect&bpo=30399]: Standard repr() of BaseException with a single argument no longer contains redundant trailing comma.

bpo-31626 [https://bugs.python.org/issue?@action=redirect&bpo=31626]: Fixed a bug in debug memory allocator. There was a write to freed memory after shrinking a memory block.

bpo-30817 [https://bugs.python.org/issue?@action=redirect&bpo=30817]: PyErr_PrintEx() clears now the ignored exception that may be raised by _PySys_SetObjectId(), for example when no memory.

Library

bpo-28556 [https://bugs.python.org/issue?@action=redirect&bpo=28556]: Two minor fixes for typing module: allow shallow copying instances of generic classes, improve interaction of __init_subclass__ with generics. Original PRs by Ivan Levkivskyi.

bpo-32214 [https://bugs.python.org/issue?@action=redirect&bpo=32214]: PEP 557, Data Classes. Provides a decorator which adds boilerplate methods to classes which use type annotations so specify fields.

bpo-27240 [https://bugs.python.org/issue?@action=redirect&bpo=27240]: The header folding algorithm for the new email policies has been rewritten, which also fixes bpo-30788 [https://bugs.python.org/issue?@action=redirect&bpo=30788], bpo-31831 [https://bugs.python.org/issue?@action=redirect&bpo=31831], and bpo-32182 [https://bugs.python.org/issue?@action=redirect&bpo=32182]. In particular, RFC2231 folding is now done correctly.

bpo-32186 [https://bugs.python.org/issue?@action=redirect&bpo=32186]: io.FileIO.readall() and io.FileIO.read() now release the GIL when getting the file size. Fixed hang of all threads with inaccessible NFS server. Patch by Nir Soffer.

bpo-32101 [https://bugs.python.org/issue?@action=redirect&bpo=32101]: Add sys.flags.dev_mode flag

bpo-32154 [https://bugs.python.org/issue?@action=redirect&bpo=32154]: The asyncio.windows_utils.socketpair() function has been removed: use directly socket.socketpair() which is available on all platforms since Python 3.5 (before, it wasn’t available on Windows). asyncio.windows_utils.socketpair() was just an alias to socket.socketpair on Python 3.5 and newer.

bpo-32089 [https://bugs.python.org/issue?@action=redirect&bpo=32089]: warnings: In development (-X dev) and debug mode (pydebug build), use the «default» action for ResourceWarning, rather than the «always» action, in the default warnings filters.

bpo-32107 [https://bugs.python.org/issue?@action=redirect&bpo=32107]: uuid.getnode() now preferentially returns universally administered MAC addresses if available, over locally administered MAC addresses. This makes a better guarantee for global uniqueness of UUIDs returned from uuid.uuid1(). If only locally administered MAC addresses are available, the first such one found is returned.

bpo-23033 [https://bugs.python.org/issue?@action=redirect&bpo=23033]: Wildcard is now supported in hostname when it is one and only character in the left most segment of hostname in second argument of ssl.match_hostname(). Patch by Mandeep Singh.

bpo-12239 [https://bugs.python.org/issue?@action=redirect&bpo=12239]: Make msilib.SummaryInformation.GetProperty() return None when the value of property is VT_EMPTY. Initial patch by Mark Mc Mahon.

bpo-28334 [https://bugs.python.org/issue?@action=redirect&bpo=28334]: Use os.path.expanduser() to find the ~/.netrc file in netrc.netrc. If it does not exist, FileNotFoundError is raised. Patch by Dimitri Merejkowsky.

bpo-32121 [https://bugs.python.org/issue?@action=redirect&bpo=32121]: Made tracemalloc.Traceback behave more like the traceback module, sorting the frames from oldest to most recent. Traceback.format() now accepts negative limit, truncating the result to the abs(limit) oldest frames. To get the old behaviour, one can use the new most_recent_first argument to Traceback.format(). (Patch by Jesse Bakker.)

bpo-31325 [https://bugs.python.org/issue?@action=redirect&bpo=31325]: Fix wrong usage of collections.namedtuple() in the RobotFileParser.parse() method. Initial patch by Robin Wellner.

bpo-12382 [https://bugs.python.org/issue?@action=redirect&bpo=12382]: msilib.OpenDatabase() now raises a better exception message when it couldn’t open or create an MSI file. Initial patch by William Tisäter.

bpo-19610 [https://bugs.python.org/issue?@action=redirect&bpo=19610]: setup() now warns about invalid types for some fields. The distutils.dist.Distribution class now warns when classifiers, keywords and platforms fields are not specified as a list or a string.

bpo-32071 [https://bugs.python.org/issue?@action=redirect&bpo=32071]: Added the -k command-line option to python -m unittest to run only tests that match the given pattern(s).

bpo-10049 [https://bugs.python.org/issue?@action=redirect&bpo=10049]: Added nullcontext no-op context manager to contextlib. This provides a simpler and faster alternative to ExitStack() when handling optional context managers.

bpo-28684 [https://bugs.python.org/issue?@action=redirect&bpo=28684]: The new test.support.skip_unless_bind_unix_socket() decorator is used here to skip asyncio tests that fail because the platform lacks a functional bind() function for unix domain sockets (as it is the case for non root users on the recent Android versions that run now SELinux in enforcing mode).

bpo-32110 [https://bugs.python.org/issue?@action=redirect&bpo=32110]: codecs.StreamReader.read(n) now returns not more than n characters/bytes for non-negative n. This makes it compatible with read() methods of other file-like objects.

bpo-27535 [https://bugs.python.org/issue?@action=redirect&bpo=27535]: The warnings module doesn’t leak memory anymore in the hidden warnings registry for the «ignore» action of warnings filters. warn_explicit() function doesn’t add the warning key to the registry anymore for the «ignore» action.

bpo-32088 [https://bugs.python.org/issue?@action=redirect&bpo=32088]: warnings: When Python is build is debug mode (Py_DEBUG), DeprecationWarning, PendingDeprecationWarning and ImportWarning warnings are now displayed by default.

bpo-1647489 [https://bugs.python.org/issue?@action=redirect&bpo=1647489]: Fixed searching regular expression patterns that could match an empty string. Non-empty string can now be correctly found after matching an empty string.

bpo-25054 [https://bugs.python.org/issue?@action=redirect&bpo=25054]: Added support of splitting on a pattern that could match an empty string.

bpo-32072 [https://bugs.python.org/issue?@action=redirect&bpo=32072]: Fixed issues with binary plists: Fixed saving bytearrays. Identical objects will be saved only once. Equal references will be load as identical objects. Added support for saving and loading recursive data structures.

bpo-32069 [https://bugs.python.org/issue?@action=redirect&bpo=32069]: Drop legacy SSL transport from asyncio, ssl.MemoryBIO is always used anyway.

bpo-32066 [https://bugs.python.org/issue?@action=redirect&bpo=32066]: asyncio: Support pathlib.Path in create_unix_connection; sock arg should be optional

bpo-32046 [https://bugs.python.org/issue?@action=redirect&bpo=32046]: Updates 2to3 to convert from operator.isCallable(obj) to callable(obj). Patch by Dong-hee Na.

bpo-32018 [https://bugs.python.org/issue?@action=redirect&bpo=32018]: inspect.signature should follow PEP 8 [https://www.python.org/dev/peps/pep-0008], if the parameter has an annotation and a default value. Patch by Dong-hee Na.

bpo-32025 [https://bugs.python.org/issue?@action=redirect&bpo=32025]: Add time.thread_time() and time.thread_time_ns()

bpo-32037 [https://bugs.python.org/issue?@action=redirect&bpo=32037]: Integers that fit in a signed 32-bit integer will be now pickled with protocol 0 using the INT opcode. This will decrease the size of a pickle, speed up pickling and unpickling, and make these integers be unpickled as int instances in Python 2.

bpo-32034 [https://bugs.python.org/issue?@action=redirect&bpo=32034]: Make asyncio.IncompleteReadError and LimitOverrunError pickleable.

bpo-32015 [https://bugs.python.org/issue?@action=redirect&bpo=32015]: Fixed the looping of asyncio in the case of reconnection the socket during waiting async read/write from/to the socket.

bpo-32011 [https://bugs.python.org/issue?@action=redirect&bpo=32011]: Restored support of loading marshal files with the TYPE_INT64 code. These files can be produced in Python 2.7.

bpo-28369 [https://bugs.python.org/issue?@action=redirect&bpo=28369]: Enhance add_reader/writer check that socket is not used by some transport. Before, only cases when add_reader/writer were called with an int FD were supported. Now the check is implemented correctly for all file-like objects.

bpo-31976 [https://bugs.python.org/issue?@action=redirect&bpo=31976]: Fix race condition when flushing a file is slow, which can cause a segfault if closing the file from another thread.

bpo-31985 [https://bugs.python.org/issue?@action=redirect&bpo=31985]: Formally deprecated aifc.openfp, sunau.openfp, and wave.openfp. Since change 7bc817d5ba917528e8bd07ec461c635291e7b06a in 1993, openfp in each of the three modules had been pointing to that module’s open function as a matter of backwards compatibility, though it had been both untested and undocumented.

bpo-21862 [https://bugs.python.org/issue?@action=redirect&bpo=21862]: cProfile command line now accepts -m module_name as an alternative to script path. Patch by Sanyam Khurana.

bpo-31970 [https://bugs.python.org/issue?@action=redirect&bpo=31970]: Reduce performance overhead of asyncio debug mode.

bpo-31843 [https://bugs.python.org/issue?@action=redirect&bpo=31843]: database argument of sqlite3.connect() now accepts a path-like object, instead of just a string.

bpo-31945 [https://bugs.python.org/issue?@action=redirect&bpo=31945]: Add Configurable blocksize to HTTPConnection and HTTPSConnection for improved upload throughput. Patch by Nir Soffer.

bpo-31943 [https://bugs.python.org/issue?@action=redirect&bpo=31943]: Add a cancelled() method to asyncio.Handle. Patch by Marat Sharafutdinov.

bpo-9678 [https://bugs.python.org/issue?@action=redirect&bpo=9678]: Fixed determining the MAC address in the uuid module: Using ifconfig on NetBSD and OpenBSD. Using arp on Linux, FreeBSD, NetBSD and OpenBSD. Based on patch by Takayuki Shimizukawa.

bpo-30057 [https://bugs.python.org/issue?@action=redirect&bpo=30057]: Fix potential missed signal in signal.signal().

bpo-31933 [https://bugs.python.org/issue?@action=redirect&bpo=31933]: Fix Blake2 params leaf_size and node_offset on big endian platforms. Patch by Jack O’Connor.

bpo-21423 [https://bugs.python.org/issue?@action=redirect&bpo=21423]: Add an initializer argument to {Process,Thread}PoolExecutor

bpo-31927 [https://bugs.python.org/issue?@action=redirect&bpo=31927]: Fixed compilation of the socket module on NetBSD 8. Fixed assertion failure or reading arbitrary data when parse a AF_BLUETOOTH address on NetBSD and DragonFly BSD.

bpo-27666 [https://bugs.python.org/issue?@action=redirect&bpo=27666]: Fixed stack corruption in curses.box() and curses.ungetmouse() when the size of types chtype or mmask_t is less than the size of C long. curses.box() now accepts characters as arguments. Based on patch by Steve Fink.

bpo-31917 [https://bugs.python.org/issue?@action=redirect&bpo=31917]: Add 3 new clock identifiers: time.CLOCK_BOOTTIME, time.CLOCK_PROF and time.CLOCK_UPTIME.

bpo-31897 [https://bugs.python.org/issue?@action=redirect&bpo=31897]: plistlib now catches more errors when read binary plists and raises InvalidFileException instead of unexpected exceptions.

bpo-25720 [https://bugs.python.org/issue?@action=redirect&bpo=25720]: Fix the method for checking pad state of curses WINDOW. Patch by Masayuki Yamamoto.

bpo-31893 [https://bugs.python.org/issue?@action=redirect&bpo=31893]: Fixed the layout of the kqueue_event structure on OpenBSD and NetBSD. Fixed the comparison of the kqueue_event objects.

bpo-31891 [https://bugs.python.org/issue?@action=redirect&bpo=31891]: Fixed building the curses module on NetBSD.

bpo-31884 [https://bugs.python.org/issue?@action=redirect&bpo=31884]: added required constants to subprocess module for setting priority on windows

bpo-28281 [https://bugs.python.org/issue?@action=redirect&bpo=28281]: Remove year (1-9999) limits on the Calendar.weekday() function. Patch by Mark Gollahon.

bpo-31702 [https://bugs.python.org/issue?@action=redirect&bpo=31702]: crypt.mksalt() now allows to specify the number of rounds for SHA-256 and SHA-512 hashing.

bpo-30639 [https://bugs.python.org/issue?@action=redirect&bpo=30639]: inspect.getfile() no longer computes the repr of unknown objects to display in an error message, to protect against badly behaved custom reprs.

bpo-30768 [https://bugs.python.org/issue?@action=redirect&bpo=30768]: Fix the pthread+semaphore implementation of PyThread_acquire_lock_timed() when called with timeout > 0 and intr_flag=0: recompute the timeout if sem_timedwait() is interrupted by a signal (EINTR). See also the PEP 475 [https://www.python.org/dev/peps/pep-0475].

bpo-31854 [https://bugs.python.org/issue?@action=redirect&bpo=31854]: Add mmap.ACCESS_DEFAULT constant.

bpo-31834 [https://bugs.python.org/issue?@action=redirect&bpo=31834]: Use optimized code for BLAKE2 only with SSSE3+. The pure SSE2 implementation is slower than the pure C reference implementation.

bpo-28292 [https://bugs.python.org/issue?@action=redirect&bpo=28292]: Calendar.itermonthdates() will now consistently raise an exception when a date falls outside of the 0001-01-01 through 9999-12-31 range. To support applications that cannot tolerate such exceptions, the new methods itermonthdays3() and itermonthdays4() are added. The new methods return tuples and are not restricted by the range supported by datetime.date.

bpo-28564 [https://bugs.python.org/issue?@action=redirect&bpo=28564]: The shutil.rmtree() function has been sped up to 20–40%. This was done using the os.scandir() function.

bpo-28416 [https://bugs.python.org/issue?@action=redirect&bpo=28416]: Instances of pickle.Pickler subclass with the persistent_id() method and pickle.Unpickler subclass with the persistent_load() method no longer create reference cycles.

bpo-31653 [https://bugs.python.org/issue?@action=redirect&bpo=31653]: Don’t release the GIL if we can acquire a multiprocessing semaphore immediately.

bpo-28326 [https://bugs.python.org/issue?@action=redirect&bpo=28326]: Fix multiprocessing.Process when stdout and/or stderr is closed or None.

bpo-20825 [https://bugs.python.org/issue?@action=redirect&bpo=20825]: Add subnet_of and superset_of containment tests to ipaddress.IPv6Network and ipaddress.IPv4Network. Patch by Michel Albert and Cheryl Sabella.

bpo-31827 [https://bugs.python.org/issue?@action=redirect&bpo=31827]: Remove the os.stat_float_times() function. It was introduced in Python 2.3 for backward compatibility with Python 2.2, and was deprecated since Python 3.1.

bpo-31756 [https://bugs.python.org/issue?@action=redirect&bpo=31756]: Add a subprocess.Popen(text=False) keyword argument to subprocess functions to be more explicit about when the library should attempt to decode outputs into text. Patch by Andrew Clegg.

bpo-31819 [https://bugs.python.org/issue?@action=redirect&bpo=31819]: Add AbstractEventLoop.sock_recv_into().

bpo-31457 [https://bugs.python.org/issue?@action=redirect&bpo=31457]: If nested log adapters are used, the inner process() methods are no longer omitted.

bpo-31457 [https://bugs.python.org/issue?@action=redirect&bpo=31457]: The manager property on LoggerAdapter objects is now properly settable.

bpo-31806 [https://bugs.python.org/issue?@action=redirect&bpo=31806]: Fix timeout rounding in time.sleep(), threading.Lock.acquire() and socket.socket.settimeout() to round correctly negative timeouts between -1.0 and 0.0. The functions now block waiting for events as expected. Previously, the call was incorrectly non-blocking. Patch by Pablo Galindo.

bpo-31803 [https://bugs.python.org/issue?@action=redirect&bpo=31803]: time.clock() and time.get_clock_info(“clock”) now emit a DeprecationWarning warning.

bpo-31800 [https://bugs.python.org/issue?@action=redirect&bpo=31800]: Extended support for parsing UTC offsets. strptime “%z” can now parse the output generated by datetime.isoformat, including seconds and microseconds.

bpo-28603 [https://bugs.python.org/issue?@action=redirect&bpo=28603]: traceback: Fix a TypeError that occurred during printing of exception tracebacks when either the current exception or an exception in its context/cause chain is unhashable. Patch by Zane Bitter.

bpo-30541 [https://bugs.python.org/issue?@action=redirect&bpo=30541]: Add new function to seal a mock and prevent the automatically creation of child mocks. Patch by Mario Corchero.

bpo-31784 [https://bugs.python.org/issue?@action=redirect&bpo=31784]: Implement the PEP 564 [https://www.python.org/dev/peps/pep-0564], add new 6 new functions with nanosecond resolution to the time module: clock_gettime_ns(), clock_settime_ns(), monotonic_ns(), perf_counter_ns(), process_time_ns(), time_ns().

bpo-30143 [https://bugs.python.org/issue?@action=redirect&bpo=30143]: 2to3 now generates a code that uses abstract collection classes from collections.abc rather than collections.

bpo-31770 [https://bugs.python.org/issue?@action=redirect&bpo=31770]: Prevent a crash when calling the __init__() method of a sqlite3.Cursor object more than once. Patch by Oren Milman.

bpo-31764 [https://bugs.python.org/issue?@action=redirect&bpo=31764]: Prevent a crash in sqlite3.Cursor.close() in case the Cursor object is uninitialized. Patch by Oren Milman.

bpo-31752 [https://bugs.python.org/issue?@action=redirect&bpo=31752]: Fix possible crash in timedelta constructor called with custom integers.

bpo-31620 [https://bugs.python.org/issue?@action=redirect&bpo=31620]: an empty asyncio.Queue now doesn’t leak memory when queue.get pollers timeout

bpo-31690 [https://bugs.python.org/issue?@action=redirect&bpo=31690]: Allow the flags re.ASCII, re.LOCALE, and re.UNICODE to be used as group flags for regular expressions.

bpo-30349 [https://bugs.python.org/issue?@action=redirect&bpo=30349]: FutureWarning is now emitted if a regular expression contains character set constructs that will change semantically in the future (nested sets and set operations).

bpo-31664 [https://bugs.python.org/issue?@action=redirect&bpo=31664]: Added support for the Blowfish hashing in the crypt module.

bpo-31632 [https://bugs.python.org/issue?@action=redirect&bpo=31632]: Fix method set_protocol() of class _SSLProtocolTransport in asyncio module. This method was previously modifying a wrong reference to the protocol.

bpo-15037 [https://bugs.python.org/issue?@action=redirect&bpo=15037]: Added a workaround for getkey() in curses for ncurses 5.7 and earlier.

bpo-31307 [https://bugs.python.org/issue?@action=redirect&bpo=31307]: Allow use of bytes objects for arguments to configparser.ConfigParser.read(). Patch by Vincent Michel.

bpo-31334 [https://bugs.python.org/issue?@action=redirect&bpo=31334]: Fix poll.poll([timeout]) in the select module for arbitrary negative timeouts on all OSes where it can only be a non-negative integer or -1. Patch by Riccardo Coccioli.

bpo-31310 [https://bugs.python.org/issue?@action=redirect&bpo=31310]: multiprocessing’s semaphore tracker should be launched again if crashed.

bpo-31308 [https://bugs.python.org/issue?@action=redirect&bpo=31308]: Make multiprocessing’s forkserver process immune to Ctrl-C and other user interruptions. If it crashes, restart it when necessary.

bpo-31245 [https://bugs.python.org/issue?@action=redirect&bpo=31245]: Added support for AF_UNIX socket in asyncio create_datagram_endpoint.

bpo-30553 [https://bugs.python.org/issue?@action=redirect&bpo=30553]: Add HTTP/2 status code 421 (Misdirected Request) to http.HTTPStatus. Patch by Vitor Pereira.

Documentation

bpo-32105 [https://bugs.python.org/issue?@action=redirect&bpo=32105]: Added asyncio.BaseEventLoop.connect_accepted_socket versionadded marker.

Tests

bpo-31380 [https://bugs.python.org/issue?@action=redirect&bpo=31380]: Skip test_httpservers test_undecodable_file on macOS: fails on APFS.

bpo-31705 [https://bugs.python.org/issue?@action=redirect&bpo=31705]: Skip test_socket.test_sha256() on Linux kernel older than 4.5. The test fails with ENOKEY on kernel 3.10 (on ppc64le). A fix was merged into the kernel 4.5.

bpo-32138 [https://bugs.python.org/issue?@action=redirect&bpo=32138]: Skip on Android test_faulthandler tests that raise SIGSEGV and remove the test.support.requires_android_level decorator.

bpo-32136 [https://bugs.python.org/issue?@action=redirect&bpo=32136]: The runtime embedding tests have been split out from Lib/test/test_capi.py into a new Lib/test/test_embed.py file.

bpo-28668 [https://bugs.python.org/issue?@action=redirect&bpo=28668]: test.support.requires_multiprocessing_queue is removed. Skip tests with test.support.import_module(“multiprocessing.synchronize”) instead when the semaphore implementation is broken or missing.

bpo-32126 [https://bugs.python.org/issue?@action=redirect&bpo=32126]: Skip test_get_event_loop_new_process in test.test_asyncio.test_events when sem_open() is not functional.

bpo-31174 [https://bugs.python.org/issue?@action=redirect&bpo=31174]: Fix test_tools.test_unparse: DirectoryTestCase now stores the names sample to always test the same files. It prevents false alarms when hunting reference leaks.

Build

bpo-28538 [https://bugs.python.org/issue?@action=redirect&bpo=28538]: Revert the previous changes, the if_nameindex structure is defined by Unified Headers.

bpo-28762 [https://bugs.python.org/issue?@action=redirect&bpo=28762]: Revert the last commit, the F_LOCK macro is defined by Android Unified Headers.

bpo-29040 [https://bugs.python.org/issue?@action=redirect&bpo=29040]: Support building Android with Unified Headers. The first NDK release to support Unified Headers is android-ndk-r14.

bpo-32059 [https://bugs.python.org/issue?@action=redirect&bpo=32059]: detect_modules() in setup.py now also searches the sysroot paths when cross-compiling.

bpo-31957 [https://bugs.python.org/issue?@action=redirect&bpo=31957]: Fixes Windows SDK version detection when building for Windows.

bpo-31609 [https://bugs.python.org/issue?@action=redirect&bpo=31609]: Fixes quotes in PCbuild/clean.bat

bpo-31934 [https://bugs.python.org/issue?@action=redirect&bpo=31934]: Abort the build when building out of a not clean source tree.

bpo-31926 [https://bugs.python.org/issue?@action=redirect&bpo=31926]: Fixed Argument Clinic sometimes causing compilation errors when there was more than one function and/or method in a .c file with the same name.

bpo-28791 [https://bugs.python.org/issue?@action=redirect&bpo=28791]: Update Windows builds to use SQLite 3.21.0.

bpo-28791 [https://bugs.python.org/issue?@action=redirect&bpo=28791]: Update OS X installer to use SQLite 3.21.0.

bpo-28643 [https://bugs.python.org/issue?@action=redirect&bpo=28643]: Record profile-opt build progress with stamp files.

bpo-31866 [https://bugs.python.org/issue?@action=redirect&bpo=31866]: Finish removing support for AtheOS.

Windows

bpo-1102 [https://bugs.python.org/issue?@action=redirect&bpo=1102]: Return None when View.Fetch() returns ERROR_NO_MORE_ITEMS instead of raising MSIError. Initial patch by Anthony Tuininga.

bpo-31944 [https://bugs.python.org/issue?@action=redirect&bpo=31944]: Fixes Modify button in Apps and Features dialog.

bpo-20486 [https://bugs.python.org/issue?@action=redirect&bpo=20486]: Implement the Database.Close() method to help closing MSI database objects.

bpo-31857 [https://bugs.python.org/issue?@action=redirect&bpo=31857]: Make the behavior of USE_STACKCHECK deterministic in a multi-threaded environment.

macOS

bpo-31392 [https://bugs.python.org/issue?@action=redirect&bpo=31392]: Update macOS installer to use OpenSSL 1.0.2m

IDLE

bpo-32207 [https://bugs.python.org/issue?@action=redirect&bpo=32207]: Improve tk event exception tracebacks in IDLE. When tk event handling is driven by IDLE’s run loop, a confusing and distracting queue.EMPTY traceback context is no longer added to tk event exception tracebacks. The traceback is now the same as when event handling is driven by user code. Patch based on a suggestion by Serhiy Storchaka.

bpo-32164 [https://bugs.python.org/issue?@action=redirect&bpo=32164]: Delete unused file idlelib/tabbedpages.py. Use of TabbedPageSet in configdialog was replaced by ttk.Notebook.

bpo-32100 [https://bugs.python.org/issue?@action=redirect&bpo=32100]: IDLE: Fix old and new bugs in pathbrowser; improve tests. Patch mostly by Cheryl Sabella.

bpo-31858 [https://bugs.python.org/issue?@action=redirect&bpo=31858]: IDLE – Restrict shell prompt manipulation to the shell. Editor and output windows only see an empty last prompt line. This simplifies the code and fixes a minor bug when newline is inserted. Sys.ps1, if present, is read on Shell start-up, but is not set or changed.

bpo-31860 [https://bugs.python.org/issue?@action=redirect&bpo=31860]: The font sample in the IDLE configuration dialog is now editable. Changes persist while IDLE remains open

bpo-31836 [https://bugs.python.org/issue?@action=redirect&bpo=31836]: Test_code_module now passes if run after test_idle, which sets ps1. The code module uses sys.ps1 if present or sets it to “>>> “ if not. Test_code_module now properly tests both behaviors. Ditto for ps2.

bpo-28603 [https://bugs.python.org/issue?@action=redirect&bpo=28603]: Fix a TypeError that caused a shell restart when printing a traceback that includes an exception that is unhashable. Patch by Zane Bitter.

bpo-13802 [https://bugs.python.org/issue?@action=redirect&bpo=13802]: Use non-Latin characters in the IDLE’s Font settings sample. Even if one selects a font that defines a limited subset of the unicode Basic Multilingual Plane, tcl/tk will use other fonts that define a character. The expanded example give users of non-Latin characters a better idea of what they might see in IDLE’s shell and editors. To make room for the expanded sample, frames on the Font tab are re-arranged. The Font/Tabs help explains a bit about the additions.

Tools/Demos

bpo-32159 [https://bugs.python.org/issue?@action=redirect&bpo=32159]: Remove CVS and Subversion tools: remove svneol.py and treesync.py scripts. CPython migrated from CVS to Subversion, to Mercurial, and then to Git. CVS and Subversion are no longer used to develop CPython.

bpo-30722 [https://bugs.python.org/issue?@action=redirect&bpo=30722]: Make redemo work with Python 3.6 and newer versions. Also, remove the LOCALE option since it doesn’t work with string patterns in Python 3. Patch by Christoph Sarnowski.

C API

bpo-20891 [https://bugs.python.org/issue?@action=redirect&bpo=20891]: Fix PyGILState_Ensure(). When PyGILState_Ensure() is called in a non-Python thread before PyEval_InitThreads(), only call PyEval_InitThreads() after calling PyThreadState_New() to fix a crash.

bpo-32125 [https://bugs.python.org/issue?@action=redirect&bpo=32125]: The Py_UseClassExceptionsFlag flag has been removed. It was deprecated and wasn’t used anymore since Python 2.0.

bpo-25612 [https://bugs.python.org/issue?@action=redirect&bpo=25612]: Move the current exception state from the frame object to the co-routine. This simplifies the interpreter and fixes a couple of obscure bugs caused by having swap exception state when entering or exiting a generator.

bpo-23699 [https://bugs.python.org/issue?@action=redirect&bpo=23699]: Add Py_RETURN_RICHCOMPARE macro to reduce boilerplate code in rich comparison functions.

bpo-30697 [https://bugs.python.org/issue?@action=redirect&bpo=30697]: The PyExc_RecursionErrorInst singleton is removed and PyErr_NormalizeException() does not use it anymore. This singleton is persistent and its members being never cleared may cause a segfault during finalization of the interpreter. See also bpo-22898 [https://bugs.python.org/issue?@action=redirect&bpo=22898].

Python 3.7.0 alpha 2

Release date: 2017-10-16

Core and Builtins

bpo-31558 [https://bugs.python.org/issue?@action=redirect&bpo=31558]: gc.freeze() is a new API that allows for moving all objects currently tracked by the garbage collector to a permanent generation, effectively removing them from future collection events. This can be used to protect those objects from having their PyGC_Head mutated. In effect, this enables great copy-on-write stability at fork().

bpo-31642 [https://bugs.python.org/issue?@action=redirect&bpo=31642]: Restored blocking «from package import module» by setting sys.modules[«package.module»] to None.

bpo-31708 [https://bugs.python.org/issue?@action=redirect&bpo=31708]: Allow use of asynchronous generator expressions in synchronous functions.

bpo-31709 [https://bugs.python.org/issue?@action=redirect&bpo=31709]: Drop support of asynchronous __aiter__.

bpo-30404 [https://bugs.python.org/issue?@action=redirect&bpo=30404]: The -u option now makes the stdout and stderr streams unbuffered rather than line-buffered.

bpo-31619 [https://bugs.python.org/issue?@action=redirect&bpo=31619]: Fixed a ValueError when convert a string with large number of underscores to integer with binary base.

bpo-31602 [https://bugs.python.org/issue?@action=redirect&bpo=31602]: Fix an assertion failure in zipimporter.get_source() in case of a bad zlib.decompress(). Patch by Oren Milman.

bpo-31592 [https://bugs.python.org/issue?@action=redirect&bpo=31592]: Fixed an assertion failure in Python parser in case of a bad unicodedata.normalize(). Patch by Oren Milman.

bpo-31588 [https://bugs.python.org/issue?@action=redirect&bpo=31588]: Raise a TypeError with a helpful error message when class creation fails due to a metaclass with a bad __prepare__() method. Patch by Oren Milman.

bpo-31574 [https://bugs.python.org/issue?@action=redirect&bpo=31574]: Importlib was instrumented with two dtrace probes to profile import timing.

bpo-31566 [https://bugs.python.org/issue?@action=redirect&bpo=31566]: Fix an assertion failure in _warnings.warn() in case of a bad __name__ global. Patch by Oren Milman.

bpo-31506 [https://bugs.python.org/issue?@action=redirect&bpo=31506]: Improved the error message logic for object.__new__ and object.__init__.

bpo-31505 [https://bugs.python.org/issue?@action=redirect&bpo=31505]: Fix an assertion failure in json, in case _json.make_encoder() received a bad encoder() argument. Patch by Oren Milman.

bpo-31492 [https://bugs.python.org/issue?@action=redirect&bpo=31492]: Fix assertion failures in case of failing to import from a module with a bad __name__ attribute, and in case of failing to access an attribute of such a module. Patch by Oren Milman.

bpo-31478 [https://bugs.python.org/issue?@action=redirect&bpo=31478]: Fix an assertion failure in _random.Random.seed() in case the argument has a bad __abs__() method. Patch by Oren Milman.

bpo-31336 [https://bugs.python.org/issue?@action=redirect&bpo=31336]: Speed up class creation by 10-20% by reducing the overhead in the necessary special method lookups. Patch by Stefan Behnel.

bpo-31415 [https://bugs.python.org/issue?@action=redirect&bpo=31415]: Add -X importtime option to show how long each import takes. It can be used to optimize application’s startup time. Support the PYTHONPROFILEIMPORTTIME as an equivalent way to enable this.

bpo-31410 [https://bugs.python.org/issue?@action=redirect&bpo=31410]: Optimized calling wrapper and classmethod descriptors.

bpo-31353 [https://bugs.python.org/issue?@action=redirect&bpo=31353]: PEP 553 [https://www.python.org/dev/peps/pep-0553] - Add a new built-in called breakpoint() which calls sys.breakpointhook(). By default this imports pdb and calls pdb.set_trace(), but users may override sys.breakpointhook() to call whatever debugger they want. The original value of the hook is saved in sys.__breakpointhook__.

bpo-17852 [https://bugs.python.org/issue?@action=redirect&bpo=17852]: Maintain a list of open buffered files, flush them before exiting the interpreter. Based on a patch from Armin Rigo.

bpo-31315 [https://bugs.python.org/issue?@action=redirect&bpo=31315]: Fix an assertion failure in imp.create_dynamic(), when spec.name is not a string. Patch by Oren Milman.

bpo-31311 [https://bugs.python.org/issue?@action=redirect&bpo=31311]: Fix a crash in the __setstate__() method of ctypes._CData, in case of a bad __dict__. Patch by Oren Milman.

bpo-31293 [https://bugs.python.org/issue?@action=redirect&bpo=31293]: Fix crashes in true division and multiplication of a timedelta object by a float with a bad as_integer_ratio() method. Patch by Oren Milman.

bpo-31285 [https://bugs.python.org/issue?@action=redirect&bpo=31285]: Fix an assertion failure in warnings.warn_explicit, when the return value of the received loader’s get_source() has a bad splitlines() method. Patch by Oren Milman.

bpo-30406 [https://bugs.python.org/issue?@action=redirect&bpo=30406]: Make async and await proper keywords, as specified in PEP 492 [https://www.python.org/dev/peps/pep-0492].

Library

bpo-30058 [https://bugs.python.org/issue?@action=redirect&bpo=30058]: Fixed buffer overflow in select.kqueue.control().

bpo-31672 [https://bugs.python.org/issue?@action=redirect&bpo=31672]: idpattern in string.Template matched some non-ASCII characters. Now it uses -i regular expression local flag to avoid non-ASCII characters.

bpo-31701 [https://bugs.python.org/issue?@action=redirect&bpo=31701]: On Windows, faulthandler.enable() now ignores MSC and COM exceptions.

bpo-31728 [https://bugs.python.org/issue?@action=redirect&bpo=31728]: Prevent crashes in _elementtree due to unsafe cleanup of Element.text and Element.tail. Patch by Oren Milman.

bpo-31671 [https://bugs.python.org/issue?@action=redirect&bpo=31671]: Now re.compile() converts passed RegexFlag to normal int object before compiling. bm_regex_compile benchmark shows 14% performance improvements.

bpo-30397 [https://bugs.python.org/issue?@action=redirect&bpo=30397]: The types of compiled regular objects and match objects are now exposed as re.Pattern and re.Match. This adds information in pydoc output for the re module.

bpo-31675 [https://bugs.python.org/issue?@action=redirect&bpo=31675]: Fixed memory leaks in Tkinter’s methods splitlist() and split() when pass a string larger than 2 GiB.

bpo-31673 [https://bugs.python.org/issue?@action=redirect&bpo=31673]: Fixed typo in the name of Tkinter’s method adderrorinfo().

bpo-31648 [https://bugs.python.org/issue?@action=redirect&bpo=31648]: Improvements to path predicates in ElementTree: Allow whitespace around predicate parts, i.e. «[a = “text”]» instead of requiring the less readable «[a=”text”]». Add support for text comparison of the current node, like «[.=”text”]». Patch by Stefan Behnel.

bpo-30806 [https://bugs.python.org/issue?@action=redirect&bpo=30806]: Fix the string representation of a netrc object.

bpo-31638 [https://bugs.python.org/issue?@action=redirect&bpo=31638]: Add optional argument compressed to zipapp.create_archive, and add option --compress to the command line interface of zipapp.

bpo-25351 [https://bugs.python.org/issue?@action=redirect&bpo=25351]: Avoid venv activate failures with undefined variables

bpo-20519 [https://bugs.python.org/issue?@action=redirect&bpo=20519]: Avoid ctypes use (if possible) and improve import time for uuid.

bpo-28293 [https://bugs.python.org/issue?@action=redirect&bpo=28293]: The regular expression cache is no longer completely dumped when it is full.

bpo-31596 [https://bugs.python.org/issue?@action=redirect&bpo=31596]: Added pthread_getcpuclockid() to the time module

bpo-27494 [https://bugs.python.org/issue?@action=redirect&bpo=27494]: Make 2to3 accept a trailing comma in generator expressions. For example, set(x for x in [],) is now allowed.

bpo-30347 [https://bugs.python.org/issue?@action=redirect&bpo=30347]: Stop crashes when concurrently iterate over itertools.groupby() iterators.

bpo-30346 [https://bugs.python.org/issue?@action=redirect&bpo=30346]: An iterator produced by itertools.groupby() iterator now becomes exhausted after advancing the groupby iterator.

bpo-31556 [https://bugs.python.org/issue?@action=redirect&bpo=31556]: Cancel asyncio.wait_for future faster if timeout <= 0

bpo-31540 [https://bugs.python.org/issue?@action=redirect&bpo=31540]: Allow passing a context object in concurrent.futures.ProcessPoolExecutor constructor. Also, free job resources in concurrent.futures.ProcessPoolExecutor earlier to improve memory usage when a worker waits for new jobs.

bpo-31516 [https://bugs.python.org/issue?@action=redirect&bpo=31516]: threading.current_thread() should not return a dummy thread at shutdown.

bpo-31525 [https://bugs.python.org/issue?@action=redirect&bpo=31525]: In the sqlite module, require the sqlite3_prepare_v2 API. Thus, the sqlite module now requires sqlite version at least 3.3.9.

bpo-26510 [https://bugs.python.org/issue?@action=redirect&bpo=26510]: argparse subparsers are now required by default. This matches behaviour in Python 2. For optional subparsers, use the new parameter add_subparsers(required=False). Patch by Anthony Sottile. (As of 3.7.0rc1, the default was changed to not required as had been the case since Python 3.3.)

bpo-27541 [https://bugs.python.org/issue?@action=redirect&bpo=27541]: Reprs of subclasses of some collection and iterator classes (bytearray, array.array, collections.deque, collections.defaultdict, itertools.count, itertools.repeat) now contain actual type name insteads of hardcoded name of the base class.

bpo-31351 [https://bugs.python.org/issue?@action=redirect&bpo=31351]: python -m ensurepip now exits with non-zero exit code if pip bootstrapping has failed.

bpo-31389 [https://bugs.python.org/issue?@action=redirect&bpo=31389]: pdb.set_trace() now takes an optional keyword-only argument header. If given, this is printed to the console just before debugging begins.

Documentation

bpo-31537 [https://bugs.python.org/issue?@action=redirect&bpo=31537]: Fix incorrect usage of get_history_length in readline documentation example code. Patch by Brad Smith.

bpo-30085 [https://bugs.python.org/issue?@action=redirect&bpo=30085]: The operator functions without double underscores are preferred for clarity. The one with underscores are only kept for back-compatibility.

Build

bpo-31696 [https://bugs.python.org/issue?@action=redirect&bpo=31696]: Improve compiler version information in sys.version when Python is built with Clang.

bpo-31625 [https://bugs.python.org/issue?@action=redirect&bpo=31625]: Stop using ranlib on static libraries. Instead, we assume ar supports the “s” flag.

bpo-31624 [https://bugs.python.org/issue?@action=redirect&bpo=31624]: Remove support for BSD/OS.

bpo-22140 [https://bugs.python.org/issue?@action=redirect&bpo=22140]: Prevent double substitution of prefix in python-config.sh.

bpo-31569 [https://bugs.python.org/issue?@action=redirect&bpo=31569]: Correct PCBuild/ case to PCbuild/ in build scripts and documentation.

bpo-31536 [https://bugs.python.org/issue?@action=redirect&bpo=31536]: Avoid wholesale rebuild after make regen-all if nothing changed.

IDLE

bpo-31460 [https://bugs.python.org/issue?@action=redirect&bpo=31460]: Simplify the API of IDLE’s Module Browser. Passing a widget instead of an flist with a root widget opens the option of creating a browser frame that is only part of a window. Passing a full file name instead of pieces assumed to come from a .py file opens the possibility of browsing python files that do not end in .py.

bpo-31649 [https://bugs.python.org/issue?@action=redirect&bpo=31649]: IDLE - Make _htest, _utest parameters keyword only.

bpo-31559 [https://bugs.python.org/issue?@action=redirect&bpo=31559]: Remove test order dependence in idle_test.test_browser.

bpo-31459 [https://bugs.python.org/issue?@action=redirect&bpo=31459]: Rename IDLE’s module browser from Class Browser to Module Browser. The original module-level class and method browser became a module browser, with the addition of module-level functions, years ago. Nested classes and functions were added yesterday. For back-compatibility, the virtual event <<open-class-browser>>, which appears on the Keys tab of the Settings dialog, is not changed. Patch by Cheryl Sabella.

bpo-31500 [https://bugs.python.org/issue?@action=redirect&bpo=31500]: Default fonts now are scaled on HiDPI displays.

bpo-1612262 [https://bugs.python.org/issue?@action=redirect&bpo=1612262]: IDLE module browser now shows nested classes and functions. Original patches for code and tests by Guilherme Polo and Cheryl Sabella, respectively.

C API

bpo-28280 [https://bugs.python.org/issue?@action=redirect&bpo=28280]: Make PyMapping_Keys(), PyMapping_Values() and PyMapping_Items() always return a list (rather than a list or a tuple). Patch by Oren Milman.

bpo-31532 [https://bugs.python.org/issue?@action=redirect&bpo=31532]: Fix memory corruption due to allocator mix in getpath.c between Py_GetPath() and Py_SetPath()

bpo-25658 [https://bugs.python.org/issue?@action=redirect&bpo=25658]: Implement PEP 539 [https://www.python.org/dev/peps/pep-0539] for Thread Specific Storage (TSS) API: it is a new Thread Local Storage (TLS) API to CPython which would supersede use of the existing TLS API within the CPython interpreter, while deprecating the existing API. PEP written by Erik M. Bray, patch by Masayuki Yamamoto.

Python 3.7.0 alpha 1

Release date: 2017-09-19

Security

bpo-29781 [https://bugs.python.org/issue?@action=redirect&bpo=29781]: SSLObject.version() now correctly returns None when handshake over BIO has not been performed yet.

bpo-29505 [https://bugs.python.org/issue?@action=redirect&bpo=29505]: Add fuzz tests for float(str), int(str), unicode(str); for oss-fuzz.

bpo-30947 [https://bugs.python.org/issue?@action=redirect&bpo=30947]: Upgrade libexpat embedded copy from version 2.2.1 to 2.2.3 to get security fixes.

bpo-30730 [https://bugs.python.org/issue?@action=redirect&bpo=30730]: Prevent environment variables injection in subprocess on Windows. Prevent passing other environment variables and command arguments.

bpo-30694 [https://bugs.python.org/issue?@action=redirect&bpo=30694]: Upgrade expat copy from 2.2.0 to 2.2.1 to get fixes of multiple security vulnerabilities including: CVE-2017-9233 (External entity infinite loop DoS), CVE-2016-9063 (Integer overflow, re-fix), CVE-2016-0718 (Fix regression bugs from 2.2.0’s fix to CVE-2016-0718) and CVE-2012-0876 (Counter hash flooding with SipHash). Note: the CVE-2016-5300 (Use os-specific entropy sources like getrandom) doesn’t impact Python, since Python already gets entropy from the OS to set the expat secret using XML_SetHashSalt().

bpo-30500 [https://bugs.python.org/issue?@action=redirect&bpo=30500]: Fix urllib.parse.splithost() to correctly parse fragments. For example, splithost('//127.0.0.1#@evil.com/') now correctly returns the 127.0.0.1 host, instead of treating @evil.com as the host in an authentication (login@host).

bpo-29591 [https://bugs.python.org/issue?@action=redirect&bpo=29591]: Update expat copy from 2.1.1 to 2.2.0 to get fixes of CVE-2016-0718 and CVE-2016-4472. See https://sourceforge.net/p/expat/bugs/537/ for more information.

Core and Builtins

bpo-31490 [https://bugs.python.org/issue?@action=redirect&bpo=31490]: Fix an assertion failure in ctypes class definition, in case the class has an attribute whose name is specified in _anonymous_ but not in _fields_. Patch by Oren Milman.

bpo-31471 [https://bugs.python.org/issue?@action=redirect&bpo=31471]: Fix an assertion failure in subprocess.Popen() on Windows, in case the env argument has a bad keys() method. Patch by Oren Milman.

bpo-31418 [https://bugs.python.org/issue?@action=redirect&bpo=31418]: Fix an assertion failure in PyErr_WriteUnraisable() in case of an exception with a bad __module__ attribute. Patch by Oren Milman.

bpo-31416 [https://bugs.python.org/issue?@action=redirect&bpo=31416]: Fix assertion failures in case of a bad warnings.filters or warnings.defaultaction. Patch by Oren Milman.

bpo-28411 [https://bugs.python.org/issue?@action=redirect&bpo=28411]: Change direct usage of PyInterpreterState.modules to PyImport_GetModuleDict(). Also introduce more uniformity in other code that deals with sys.modules. This helps reduce complications when working on sys.modules.

bpo-28411 [https://bugs.python.org/issue?@action=redirect&bpo=28411]: Switch to the abstract API when dealing with PyInterpreterState.modules. This allows later support for all dict subclasses and other Mapping implementations. Also add a PyImport_GetModule() function to reduce a bunch of duplicated code.

bpo-31411 [https://bugs.python.org/issue?@action=redirect&bpo=31411]: Raise a TypeError instead of SystemError in case warnings.onceregistry is not a dictionary. Patch by Oren Milman.

bpo-31344 [https://bugs.python.org/issue?@action=redirect&bpo=31344]: For finer control of tracing behaviour when testing the interpreter, two new frame attributes have been added to control the emission of particular trace events: f_trace_lines (True by default) to turn off per-line trace events; and f_trace_opcodes (False by default) to turn on per-opcode trace events.

bpo-31373 [https://bugs.python.org/issue?@action=redirect&bpo=31373]: Fix several possible instances of undefined behavior due to floating-point demotions.

bpo-30465 [https://bugs.python.org/issue?@action=redirect&bpo=30465]: Location information (lineno and col_offset) in f-strings is now (mostly) correct. This fixes tools like flake8 from showing warnings on the wrong line (typically the first line of the file).

bpo-30860 [https://bugs.python.org/issue?@action=redirect&bpo=30860]: Consolidate CPython’s global runtime state under a single struct. This improves discoverability of the runtime state.

bpo-31347 [https://bugs.python.org/issue?@action=redirect&bpo=31347]: Fix possible undefined behavior in _PyObject_FastCall_Prepend.

bpo-31343 [https://bugs.python.org/issue?@action=redirect&bpo=31343]: Include sys/sysmacros.h for major(), minor(), and makedev(). GNU C libray plans to remove the functions from sys/types.h.

bpo-31291 [https://bugs.python.org/issue?@action=redirect&bpo=31291]: Fix an assertion failure in zipimport.zipimporter.get_data on Windows, when the return value of pathname.replace('/','\\') isn’t a string. Patch by Oren Milman.

bpo-31271 [https://bugs.python.org/issue?@action=redirect&bpo=31271]: Fix an assertion failure in the write() method of io.TextIOWrapper, when the encoder doesn’t return a bytes object. Patch by Oren Milman.

bpo-31243 [https://bugs.python.org/issue?@action=redirect&bpo=31243]: Fix a crash in some methods of io.TextIOWrapper, when the decoder’s state is invalid. Patch by Oren Milman.

bpo-30721 [https://bugs.python.org/issue?@action=redirect&bpo=30721]: print now shows correct usage hint for using Python 2 redirection syntax. Patch by Sanyam Khurana.

bpo-31070 [https://bugs.python.org/issue?@action=redirect&bpo=31070]: Fix a race condition in importlib _get_module_lock().

bpo-30747 [https://bugs.python.org/issue?@action=redirect&bpo=30747]: Add a non-dummy implementation of _Py_atomic_store and _Py_atomic_load on MSVC.

bpo-31095 [https://bugs.python.org/issue?@action=redirect&bpo=31095]: Fix potential crash during GC caused by tp_dealloc which doesn’t call PyObject_GC_UnTrack().

bpo-31071 [https://bugs.python.org/issue?@action=redirect&bpo=31071]: Avoid masking original TypeError in call with * unpacking when other arguments are passed.

bpo-30978 [https://bugs.python.org/issue?@action=redirect&bpo=30978]: str.format_map() now passes key lookup exceptions through. Previously any exception was replaced with a KeyError exception.

bpo-30808 [https://bugs.python.org/issue?@action=redirect&bpo=30808]: Use _Py_atomic API for concurrency-sensitive signal state.

bpo-30876 [https://bugs.python.org/issue?@action=redirect&bpo=30876]: Relative import from unloaded package now reimports the package instead of failing with SystemError. Relative import from non-package now fails with ImportError rather than SystemError.

bpo-30703 [https://bugs.python.org/issue?@action=redirect&bpo=30703]: Improve signal delivery. Avoid using Py_AddPendingCall from signal handler, to avoid calling signal-unsafe functions. The tests I’m adding here fail without the rest of the patch, on Linux and OS X. This means our signal delivery logic had defects (some signals could be lost).

bpo-30765 [https://bugs.python.org/issue?@action=redirect&bpo=30765]: Avoid blocking in pthread_mutex_lock() when PyThread_acquire_lock() is asked not to block.

bpo-31161 [https://bugs.python.org/issue?@action=redirect&bpo=31161]: Make sure the “Missing parentheses” syntax error message is only applied to SyntaxError, not to subclasses. Patch by Martijn Pieters.

bpo-30814 [https://bugs.python.org/issue?@action=redirect&bpo=30814]: Fixed a race condition when import a submodule from a package.

bpo-30736 [https://bugs.python.org/issue?@action=redirect&bpo=30736]: The internal unicodedata database has been upgraded to Unicode 10.0.

bpo-30604 [https://bugs.python.org/issue?@action=redirect&bpo=30604]: Move co_extra_freefuncs from per-thread to per-interpreter to avoid crashes.

bpo-30597 [https://bugs.python.org/issue?@action=redirect&bpo=30597]: print now shows expected input in custom error message when used as a Python 2 statement. Patch by Sanyam Khurana.

bpo-30682 [https://bugs.python.org/issue?@action=redirect&bpo=30682]: Removed a too-strict assertion that failed for certain f-strings, such as eval(«f”\n”») and eval(«f”\r”»).

bpo-30501 [https://bugs.python.org/issue?@action=redirect&bpo=30501]: The compiler now produces more optimal code for complex condition expressions in the «if», «while» and «assert» statement, the «if» expression, and generator expressions and comprehensions.

bpo-28180 [https://bugs.python.org/issue?@action=redirect&bpo=28180]: Implement PEP 538 [https://www.python.org/dev/peps/pep-0538] (legacy C locale coercion). This means that when a suitable coercion target locale is available, both the core interpreter and locale-aware C extensions will assume the use of UTF-8 as the default text encoding, rather than ASCII.

bpo-30486 [https://bugs.python.org/issue?@action=redirect&bpo=30486]: Allows setting cell values for __closure__. Patch by Lisa Roach.

bpo-30537 [https://bugs.python.org/issue?@action=redirect&bpo=30537]: itertools.islice now accepts integer-like objects (having an __index__ method) as start, stop, and slice arguments

bpo-25324 [https://bugs.python.org/issue?@action=redirect&bpo=25324]: Tokens needed for parsing in Python moved to C. COMMENT, NL and ENCODING. This way the tokens and tok_names in the token module don’t get changed when you import the tokenize module.

bpo-29104 [https://bugs.python.org/issue?@action=redirect&bpo=29104]: Fixed parsing backslashes in f-strings.

bpo-27945 [https://bugs.python.org/issue?@action=redirect&bpo=27945]: Fixed various segfaults with dict when input collections are mutated during searching, inserting or comparing. Based on patches by Duane Griffin and Tim Mitchell.

bpo-25794 [https://bugs.python.org/issue?@action=redirect&bpo=25794]: Fixed type.__setattr__() and type.__delattr__() for non-interned attribute names. Based on patch by Eryk Sun.

bpo-30039 [https://bugs.python.org/issue?@action=redirect&bpo=30039]: If a KeyboardInterrupt happens when the interpreter is in the middle of resuming a chain of nested “yield from” or “await” calls, it’s now correctly delivered to the innermost frame.

bpo-28974 [https://bugs.python.org/issue?@action=redirect&bpo=28974]: object.__format__(x, '') is now equivalent to str(x) rather than format(str(self), '').

bpo-30024 [https://bugs.python.org/issue?@action=redirect&bpo=30024]: Circular imports involving absolute imports with binding a submodule to a name are now supported.

bpo-12414 [https://bugs.python.org/issue?@action=redirect&bpo=12414]: sys.getsizeof() on a code object now returns the sizes which includes the code struct and sizes of objects which it references. Patch by Dong-hee Na.

bpo-29839 [https://bugs.python.org/issue?@action=redirect&bpo=29839]: len() now raises ValueError rather than OverflowError if __len__() returned a large negative integer.

bpo-11913 [https://bugs.python.org/issue?@action=redirect&bpo=11913]: README.rst is now included in the list of distutils standard READMEs and therefore included in source distributions.

bpo-29914 [https://bugs.python.org/issue?@action=redirect&bpo=29914]: Fixed default implementations of __reduce__ and __reduce_ex__(). object.__reduce__() no longer takes arguments, object.__reduce_ex__() now requires one argument.

bpo-29949 [https://bugs.python.org/issue?@action=redirect&bpo=29949]: Fix memory usage regression of set and frozenset object.

bpo-29935 [https://bugs.python.org/issue?@action=redirect&bpo=29935]: Fixed error messages in the index() method of tuple, list and deque when pass indices of wrong type.

bpo-29816 [https://bugs.python.org/issue?@action=redirect&bpo=29816]: Shift operation now has less opportunity to raise OverflowError. ValueError always is raised rather than OverflowError for negative counts. Shifting zero with non-negative count always returns zero.

bpo-24821 [https://bugs.python.org/issue?@action=redirect&bpo=24821]: Fixed the slowing down to 25 times in the searching of some unlucky Unicode characters.

bpo-29102 [https://bugs.python.org/issue?@action=redirect&bpo=29102]: Add a unique ID to PyInterpreterState. This makes it easier to identify each subinterpreter.

bpo-29894 [https://bugs.python.org/issue?@action=redirect&bpo=29894]: The deprecation warning is emitted if __complex__ returns an instance of a strict subclass of complex. In a future versions of Python this can be an error.

bpo-29859 [https://bugs.python.org/issue?@action=redirect&bpo=29859]: Show correct error messages when any of the pthread_* calls in thread_pthread.h fails.

bpo-29849 [https://bugs.python.org/issue?@action=redirect&bpo=29849]: Fix a memory leak when an ImportError is raised during from import.

bpo-28856 [https://bugs.python.org/issue?@action=redirect&bpo=28856]: Fix an oversight that %b format for bytes should support objects follow the buffer protocol.

bpo-29723 [https://bugs.python.org/issue?@action=redirect&bpo=29723]: The sys.path[0] initialization change for bpo-29139 [https://bugs.python.org/issue?@action=redirect&bpo=29139] caused a regression by revealing an inconsistency in how sys.path is initialized when executing __main__ from a zipfile, directory, or other import location. The interpreter now consistently avoids ever adding the import location’s parent directory to sys.path, and ensures no other sys.path entries are inadvertently modified when inserting the import location named on the command line.

bpo-29568 [https://bugs.python.org/issue?@action=redirect&bpo=29568]: Escaped percent «%%» in the format string for classic string formatting no longer allows any characters between two percents.

bpo-29714 [https://bugs.python.org/issue?@action=redirect&bpo=29714]: Fix a regression that bytes format may fail when containing zero bytes inside.

bpo-29695 [https://bugs.python.org/issue?@action=redirect&bpo=29695]: bool(), float(), list() and tuple() no longer take keyword arguments. The first argument of int() can now be passes only as positional argument.

bpo-28893 [https://bugs.python.org/issue?@action=redirect&bpo=28893]: Set correct __cause__ for errors about invalid awaitables returned from __aiter__ and __anext__.

bpo-28876 [https://bugs.python.org/issue?@action=redirect&bpo=28876]: bool(range) works even if len(range) raises OverflowError.

bpo-29683 [https://bugs.python.org/issue?@action=redirect&bpo=29683]: Fixes to memory allocation in _PyCode_SetExtra. Patch by Brian Coleman.

bpo-29684 [https://bugs.python.org/issue?@action=redirect&bpo=29684]: Fix minor regression of PyEval_CallObjectWithKeywords. It should raise TypeError when kwargs is not a dict. But it might cause segv when args=NULL and kwargs is not a dict.

bpo-28598 [https://bugs.python.org/issue?@action=redirect&bpo=28598]: Support __rmod__ for subclasses of str being called before str.__mod__. Patch by Martijn Pieters.

bpo-29607 [https://bugs.python.org/issue?@action=redirect&bpo=29607]: Fix stack_effect computation for CALL_FUNCTION_EX. Patch by Matthieu Dartiailh.

bpo-29602 [https://bugs.python.org/issue?@action=redirect&bpo=29602]: Fix incorrect handling of signed zeros in complex constructor for complex subclasses and for inputs having a __complex__ method. Patch by Serhiy Storchaka.

bpo-29347 [https://bugs.python.org/issue?@action=redirect&bpo=29347]: Fixed possibly dereferencing undefined pointers when creating weakref objects.

bpo-29463 [https://bugs.python.org/issue?@action=redirect&bpo=29463]: Add docstring field to Module, ClassDef, FunctionDef, and AsyncFunctionDef ast nodes. docstring is not first stmt in their body anymore. It affects co_firstlineno and co_lnotab of code object for module and class. (Reverted in bpo-32911 [https://bugs.python.org/issue?@action=redirect&bpo=32911].)

bpo-29438 [https://bugs.python.org/issue?@action=redirect&bpo=29438]: Fixed use-after-free problem in key sharing dict.

bpo-29546 [https://bugs.python.org/issue?@action=redirect&bpo=29546]: Set the “path” and “name” attribute on ImportError for from ... import ....

bpo-29546 [https://bugs.python.org/issue?@action=redirect&bpo=29546]: Improve from-import error message with location

bpo-29478 [https://bugs.python.org/issue?@action=redirect&bpo=29478]: If max_line_length=None is specified while using the Compat32 policy, it is no longer ignored. Patch by Mircea Cosbuc.

bpo-29319 [https://bugs.python.org/issue?@action=redirect&bpo=29319]: Prevent RunMainFromImporter overwriting sys.path[0].

bpo-29337 [https://bugs.python.org/issue?@action=redirect&bpo=29337]: Fixed possible BytesWarning when compare the code objects. Warnings could be emitted at compile time.

bpo-29327 [https://bugs.python.org/issue?@action=redirect&bpo=29327]: Fixed a crash when pass the iterable keyword argument to sorted().

bpo-29034 [https://bugs.python.org/issue?@action=redirect&bpo=29034]: Fix memory leak and use-after-free in os module (path_converter).

bpo-29159 [https://bugs.python.org/issue?@action=redirect&bpo=29159]: Fix regression in bytes(x) when x.__index__() raises Exception.

bpo-29049 [https://bugs.python.org/issue?@action=redirect&bpo=29049]: Call _PyObject_GC_TRACK() lazily when calling Python function. Calling function is up to 5% faster.

bpo-28927 [https://bugs.python.org/issue?@action=redirect&bpo=28927]: bytes.fromhex() and bytearray.fromhex() now ignore all ASCII whitespace, not only spaces. Patch by Robert Xiao.

bpo-28932 [https://bugs.python.org/issue?@action=redirect&bpo=28932]: Do not include <sys/random.h> if it does not exist.

bpo-25677 [https://bugs.python.org/issue?@action=redirect&bpo=25677]: Correct the positioning of the syntax error caret for indented blocks. Based on patch by Michael Layzell.

bpo-29000 [https://bugs.python.org/issue?@action=redirect&bpo=29000]: Fixed bytes formatting of octals with zero padding in alternate form.

bpo-18896 [https://bugs.python.org/issue?@action=redirect&bpo=18896]: Python function can now have more than 255 parameters. collections.namedtuple() now supports tuples with more than 255 elements.

bpo-28596 [https://bugs.python.org/issue?@action=redirect&bpo=28596]: The preferred encoding is UTF-8 on Android. Patch written by Chi Hsuan Yen.

bpo-22257 [https://bugs.python.org/issue?@action=redirect&bpo=22257]: Clean up interpreter startup (see PEP 432 [https://www.python.org/dev/peps/pep-0432]).

bpo-26919 [https://bugs.python.org/issue?@action=redirect&bpo=26919]: On Android, operating system data is now always encoded/decoded to/from UTF-8, instead of the locale encoding to avoid inconsistencies with os.fsencode() and os.fsdecode() which are already using UTF-8.

bpo-28991 [https://bugs.python.org/issue?@action=redirect&bpo=28991]: functools.lru_cache() was susceptible to an obscure reentrancy bug triggerable by a monkey-patched len() function.

bpo-28147 [https://bugs.python.org/issue?@action=redirect&bpo=28147]: Fix a memory leak in split-table dictionaries: setattr() must not convert combined table into split table. Patch written by INADA Naoki.

bpo-28739 [https://bugs.python.org/issue?@action=redirect&bpo=28739]: f-string expressions are no longer accepted as docstrings and by ast.literal_eval() even if they do not include expressions.

bpo-28512 [https://bugs.python.org/issue?@action=redirect&bpo=28512]: Fixed setting the offset attribute of SyntaxError by PyErr_SyntaxLocationEx() and PyErr_SyntaxLocationObject().

bpo-28918 [https://bugs.python.org/issue?@action=redirect&bpo=28918]: Fix the cross compilation of xxlimited when Python has been built with Py_DEBUG defined.

bpo-23722 [https://bugs.python.org/issue?@action=redirect&bpo=23722]: Rather than silently producing a class that doesn’t support zero-argument super() in methods, failing to pass the new __classcell__ namespace entry up to type.__new__ now results in a DeprecationWarning and a class that supports zero-argument super().

bpo-28797 [https://bugs.python.org/issue?@action=redirect&bpo=28797]: Modifying the class __dict__ inside the __set_name__ method of a descriptor that is used inside that class no longer prevents calling the __set_name__ method of other descriptors.

bpo-28799 [https://bugs.python.org/issue?@action=redirect&bpo=28799]: Remove the PyEval_GetCallStats() function and deprecate the untested and undocumented sys.callstats() function. Remove the CALL_PROFILE special build: use the sys.setprofile() function, cProfile or profile to profile function calls.

bpo-12844 [https://bugs.python.org/issue?@action=redirect&bpo=12844]: More than 255 arguments can now be passed to a function.

bpo-28782 [https://bugs.python.org/issue?@action=redirect&bpo=28782]: Fix a bug in the implementation yield from when checking if the next instruction is YIELD_FROM. Regression introduced by WORDCODE (bpo-26647 [https://bugs.python.org/issue?@action=redirect&bpo=26647]).

bpo-28774 [https://bugs.python.org/issue?@action=redirect&bpo=28774]: Fix error position of the unicode error in ASCII and Latin1 encoders when a string returned by the error handler contains multiple non-encodable characters (non-ASCII for the ASCII codec, characters out of the U+0000-U+00FF range for Latin1).

bpo-28731 [https://bugs.python.org/issue?@action=redirect&bpo=28731]: Optimize _PyDict_NewPresized() to create correct size dict. Improve speed of dict literal with constant keys up to 30%.

bpo-28532 [https://bugs.python.org/issue?@action=redirect&bpo=28532]: Show sys.version when -V option is supplied twice.

bpo-27100 [https://bugs.python.org/issue?@action=redirect&bpo=27100]: The with-statement now checks for __enter__ before it checks for __exit__. This gives less confusing error messages when both methods are missing. Patch by Jonathan Ellington.

bpo-28746 [https://bugs.python.org/issue?@action=redirect&bpo=28746]: Fix the set_inheritable() file descriptor method on platforms that do not have the ioctl FIOCLEX and FIONCLEX commands.

bpo-26920 [https://bugs.python.org/issue?@action=redirect&bpo=26920]: Fix not getting the locale’s charset upon initializing the interpreter, on platforms that do not have langinfo.

bpo-28648 [https://bugs.python.org/issue?@action=redirect&bpo=28648]: Fixed crash in Py_DecodeLocale() in debug build on Mac OS X when decode astral characters. Patch by Xiang Zhang.

bpo-28665 [https://bugs.python.org/issue?@action=redirect&bpo=28665]: Improve speed of the STORE_DEREF opcode by 40%.

bpo-19398 [https://bugs.python.org/issue?@action=redirect&bpo=19398]: Extra slash no longer added to sys.path components in case of empty compile-time PYTHONPATH components.

bpo-28621 [https://bugs.python.org/issue?@action=redirect&bpo=28621]: Sped up converting int to float by reusing faster bits counting implementation. Patch by Adrian Wielgosik.

bpo-28580 [https://bugs.python.org/issue?@action=redirect&bpo=28580]: Optimize iterating split table values. Patch by Xiang Zhang.

bpo-28583 [https://bugs.python.org/issue?@action=redirect&bpo=28583]: PyDict_SetDefault didn’t combine split table when needed. Patch by Xiang Zhang.

bpo-28128 [https://bugs.python.org/issue?@action=redirect&bpo=28128]: Deprecation warning for invalid str and byte escape sequences now prints better information about where the error occurs. Patch by Serhiy Storchaka and Eric Smith.

bpo-28509 [https://bugs.python.org/issue?@action=redirect&bpo=28509]: dict.update() no longer allocate unnecessary large memory.

bpo-28426 [https://bugs.python.org/issue?@action=redirect&bpo=28426]: Fixed potential crash in PyUnicode_AsDecodedObject() in debug build.

bpo-28517 [https://bugs.python.org/issue?@action=redirect&bpo=28517]: Fixed of-by-one error in the peephole optimizer that caused keeping unreachable code.

bpo-28214 [https://bugs.python.org/issue?@action=redirect&bpo=28214]: Improved exception reporting for problematic __set_name__ attributes.

bpo-23782 [https://bugs.python.org/issue?@action=redirect&bpo=23782]: Fixed possible memory leak in _PyTraceback_Add() and exception loss in PyTraceBack_Here().

bpo-28183 [https://bugs.python.org/issue?@action=redirect&bpo=28183]: Optimize and cleanup dict iteration.

bpo-26081 [https://bugs.python.org/issue?@action=redirect&bpo=26081]: Added C implementation of asyncio.Future. Original patch by Yury Selivanov.

bpo-28379 [https://bugs.python.org/issue?@action=redirect&bpo=28379]: Added sanity checks and tests for PyUnicode_CopyCharacters(). Patch by Xiang Zhang.

bpo-28376 [https://bugs.python.org/issue?@action=redirect&bpo=28376]: The type of long range iterator is now registered as Iterator. Patch by Oren Milman.

bpo-28376 [https://bugs.python.org/issue?@action=redirect&bpo=28376]: Creating instances of range_iterator by calling range_iterator type now is disallowed. Calling iter() on range instance is the only way. Patch by Oren Milman.

bpo-26906 [https://bugs.python.org/issue?@action=redirect&bpo=26906]: Resolving special methods of uninitialized type now causes implicit initialization of the type instead of a fail.

bpo-18287 [https://bugs.python.org/issue?@action=redirect&bpo=18287]: PyType_Ready() now checks that tp_name is not NULL. Original patch by Niklas Koep.

bpo-24098 [https://bugs.python.org/issue?@action=redirect&bpo=24098]: Fixed possible crash when AST is changed in process of compiling it.

bpo-28201 [https://bugs.python.org/issue?@action=redirect&bpo=28201]: Dict reduces possibility of 2nd conflict in hash table when hashes have same lower bits.

bpo-28350 [https://bugs.python.org/issue?@action=redirect&bpo=28350]: String constants with null character no longer interned.

bpo-26617 [https://bugs.python.org/issue?@action=redirect&bpo=26617]: Fix crash when GC runs during weakref callbacks.

bpo-27942 [https://bugs.python.org/issue?@action=redirect&bpo=27942]: String constants now interned recursively in tuples and frozensets.

bpo-28289 [https://bugs.python.org/issue?@action=redirect&bpo=28289]: ImportError.__init__ now resets not specified attributes.

bpo-21578 [https://bugs.python.org/issue?@action=redirect&bpo=21578]: Fixed misleading error message when ImportError called with invalid keyword args.

bpo-28203 [https://bugs.python.org/issue?@action=redirect&bpo=28203]: Fix incorrect type in complex(1.0, {2:3}) error message. Patch by Soumya Sharma.

bpo-28086 [https://bugs.python.org/issue?@action=redirect&bpo=28086]: Single var-positional argument of tuple subtype was passed unscathed to the C-defined function. Now it is converted to exact tuple.

bpo-28214 [https://bugs.python.org/issue?@action=redirect&bpo=28214]: Now __set_name__ is looked up on the class instead of the instance.

bpo-27955 [https://bugs.python.org/issue?@action=redirect&bpo=27955]: Fallback on reading /dev/urandom device when the getrandom() syscall fails with EPERM, for example when blocked by SECCOMP.

bpo-28192 [https://bugs.python.org/issue?@action=redirect&bpo=28192]: Don’t import readline in isolated mode.

bpo-27441 [https://bugs.python.org/issue?@action=redirect&bpo=27441]: Remove some redundant assignments to ob_size in longobject.c. Thanks Oren Milman.

bpo-27222 [https://bugs.python.org/issue?@action=redirect&bpo=27222]: Clean up redundant code in long_rshift function. Thanks Oren Milman.

Upgrade internal unicode databases to Unicode version 9.0.0.

bpo-28131 [https://bugs.python.org/issue?@action=redirect&bpo=28131]: Fix a regression in zipimport’s compile_source(). zipimport should use the same optimization level as the interpreter.

bpo-28126 [https://bugs.python.org/issue?@action=redirect&bpo=28126]: Replace Py_MEMCPY with memcpy(). Visual Studio can properly optimize memcpy().

bpo-28120 [https://bugs.python.org/issue?@action=redirect&bpo=28120]: Fix dict.pop() for splitted dictionary when trying to remove a «pending key» (Not yet inserted in split-table). Patch by Xiang Zhang.

bpo-26182 [https://bugs.python.org/issue?@action=redirect&bpo=26182]: Raise DeprecationWarning when async and await keywords are used as variable/attribute/class/function name.

bpo-26182 [https://bugs.python.org/issue?@action=redirect&bpo=26182]: Fix a refleak in code that raises DeprecationWarning.

bpo-28721 [https://bugs.python.org/issue?@action=redirect&bpo=28721]: Fix asynchronous generators aclose() and athrow() to handle StopAsyncIteration propagation properly.

bpo-26110 [https://bugs.python.org/issue?@action=redirect&bpo=26110]: Speed-up method calls: add LOAD_METHOD and CALL_METHOD opcodes.

Library

bpo-31499 [https://bugs.python.org/issue?@action=redirect&bpo=31499]: xml.etree: Fix a crash when a parser is part of a reference cycle.

bpo-31482 [https://bugs.python.org/issue?@action=redirect&bpo=31482]: random.seed() now works with bytes in version=1

bpo-28556 [https://bugs.python.org/issue?@action=redirect&bpo=28556]: typing.get_type_hints now finds the right globalns for classes and modules by default (when no globalns was specified by the caller).

bpo-28556 [https://bugs.python.org/issue?@action=redirect&bpo=28556]: Speed improvements to the typing module. Original PRs by Ivan Levkivskyi and Mitar.

bpo-31544 [https://bugs.python.org/issue?@action=redirect&bpo=31544]: The C accelerator module of ElementTree ignored exceptions raised when looking up TreeBuilder target methods in XMLParser().

bpo-31234 [https://bugs.python.org/issue?@action=redirect&bpo=31234]: socket.create_connection() now fixes manually a reference cycle: clear the variable storing the last exception on success.

bpo-31457 [https://bugs.python.org/issue?@action=redirect&bpo=31457]: LoggerAdapter objects can now be nested.

bpo-31431 [https://bugs.python.org/issue?@action=redirect&bpo=31431]: SSLContext.check_hostname now automatically sets SSLContext.verify_mode to ssl.CERT_REQUIRED instead of failing with a ValueError.

bpo-31233 [https://bugs.python.org/issue?@action=redirect&bpo=31233]: socketserver.ThreadingMixIn now keeps a list of non-daemonic threads to wait until all these threads complete in server_close().

bpo-28638 [https://bugs.python.org/issue?@action=redirect&bpo=28638]: Changed the implementation strategy for collections.namedtuple() to substantially reduce the use of exec() in favor of precomputed methods. As a result, the verbose parameter and _source attribute are no longer supported. The benefits include 1) having a smaller memory footprint for applications using multiple named tuples, 2) faster creation of the named tuple class (approx 4x to 6x depending on how it is measured), and 3) minor speed-ups for instance creation using __new__, _make, and _replace. (The primary patch contributor is Jelle Zijlstra with further improvements by INADA Naoki, Serhiy Storchaka, and Raymond Hettinger.)

bpo-31400 [https://bugs.python.org/issue?@action=redirect&bpo=31400]: Improves SSL error handling to avoid losing error numbers.

bpo-27629 [https://bugs.python.org/issue?@action=redirect&bpo=27629]: Make return types of SSLContext.wrap_bio() and SSLContext.wrap_socket() customizable.

bpo-28958 [https://bugs.python.org/issue?@action=redirect&bpo=28958]: ssl.SSLContext() now uses OpenSSL error information when a context cannot be instantiated.

bpo-28182 [https://bugs.python.org/issue?@action=redirect&bpo=28182]: The SSL module now raises SSLCertVerificationError when OpenSSL fails to verify the peer’s certificate. The exception contains more information about the error.

bpo-27340 [https://bugs.python.org/issue?@action=redirect&bpo=27340]: SSLSocket.sendall() now uses memoryview to create slices of data. This fixes support for all bytes-like object. It is also more efficient and avoids costly copies.

bpo-14191 [https://bugs.python.org/issue?@action=redirect&bpo=14191]: A new function argparse.ArgumentParser.parse_intermixed_args provides the ability to parse command lines where there user intermixes options and positional arguments.

bpo-31178 [https://bugs.python.org/issue?@action=redirect&bpo=31178]: Fix string concatenation bug in rare error path in the subprocess module

bpo-31350 [https://bugs.python.org/issue?@action=redirect&bpo=31350]: Micro-optimize asyncio._get_running_loop() to become up to 10% faster.

bpo-31170 [https://bugs.python.org/issue?@action=redirect&bpo=31170]: expat: Update libexpat from 2.2.3 to 2.2.4. Fix copying of partial characters for UTF-8 input (libexpat bug 115): https://github.com/libexpat/libexpat/issues/115

bpo-29136 [https://bugs.python.org/issue?@action=redirect&bpo=29136]: Add TLS 1.3 cipher suites and OP_NO_TLSv1_3.

bpo-1198569 [https://bugs.python.org/issue?@action=redirect&bpo=1198569]: string.Template subclasses can optionally define braceidpattern if they want to specify different placeholder patterns inside and outside the braces. If None (the default) it falls back to idpattern.

bpo-31326 [https://bugs.python.org/issue?@action=redirect&bpo=31326]: concurrent.futures.ProcessPoolExecutor.shutdown() now explicitly closes the call queue. Moreover, shutdown(wait=True) now also join the call queue thread, to prevent leaking a dangling thread.

bpo-27144 [https://bugs.python.org/issue?@action=redirect&bpo=27144]: The map() and as_completed() iterators in concurrent.futures now avoid keeping a reference to yielded objects.

bpo-31281 [https://bugs.python.org/issue?@action=redirect&bpo=31281]: Fix fileinput.FileInput(files, inplace=True) when files contain pathlib.Path objects.

bpo-10746 [https://bugs.python.org/issue?@action=redirect&bpo=10746]: Fix ctypes producing wrong PEP 3118 [https://www.python.org/dev/peps/pep-3118] type codes for integer types.

bpo-27584 [https://bugs.python.org/issue?@action=redirect&bpo=27584]: AF_VSOCK has been added to the socket interface which allows communication between virtual machines and their host.

bpo-22536 [https://bugs.python.org/issue?@action=redirect&bpo=22536]: The subprocess module now sets the filename when FileNotFoundError is raised on POSIX systems due to the executable or cwd not being found.

bpo-29741 [https://bugs.python.org/issue?@action=redirect&bpo=29741]: Update some methods in the _pyio module to also accept integer types. Patch by Oren Milman.

bpo-31249 [https://bugs.python.org/issue?@action=redirect&bpo=31249]: concurrent.futures: WorkItem.run() used by ThreadPoolExecutor now breaks a reference cycle between an exception object and the WorkItem object.

bpo-31247 [https://bugs.python.org/issue?@action=redirect&bpo=31247]: xmlrpc.server now explicitly breaks reference cycles when using sys.exc_info() in code handling exceptions.

bpo-23835 [https://bugs.python.org/issue?@action=redirect&bpo=23835]: configparser: reading defaults in the ConfigParser() constructor is now using read_dict(), making its behavior consistent with the rest of the parser. Non-string keys and values in the defaults dictionary are now being implicitly converted to strings. Patch by James Tocknell.

bpo-31238 [https://bugs.python.org/issue?@action=redirect&bpo=31238]: pydoc: the stop() method of the private ServerThread class now waits until DocServer.serve_until_quit() completes and then explicitly sets its docserver attribute to None to break a reference cycle.

bpo-5001 [https://bugs.python.org/issue?@action=redirect&bpo=5001]: Many asserts in multiprocessing are now more informative, and some error types have been changed to more specific ones.

bpo-31109 [https://bugs.python.org/issue?@action=redirect&bpo=31109]: Convert zipimport to use Argument Clinic.

bpo-30102 [https://bugs.python.org/issue?@action=redirect&bpo=30102]: The ssl and hashlib modules now call OPENSSL_add_all_algorithms_noconf() on OpenSSL < 1.1.0. The function detects CPU features and enables optimizations on some CPU architectures such as POWER8. Patch is based on research from Gustavo Serra Scalet.

bpo-18966 [https://bugs.python.org/issue?@action=redirect&bpo=18966]: Non-daemonic threads created by a multiprocessing.Process are now joined on child exit.

bpo-31183 [https://bugs.python.org/issue?@action=redirect&bpo=31183]: dis now works with asynchronous generator and coroutine objects. Patch by George Collins based on diagnosis by Luciano Ramalho.

bpo-5001 [https://bugs.python.org/issue?@action=redirect&bpo=5001]: There are a number of uninformative asserts in the multiprocessing module, as noted in issue 5001. This change fixes two of the most potentially problematic ones, since they are in error-reporting code, in the multiprocessing.managers.convert_to_error function. (It also makes more informative a ValueError message.) The only potentially problematic change is that the AssertionError is now a TypeError; however, this should also help distinguish it from an AssertionError being reported by the function/its caller (such as in issue 31169). - Patch by Allen W. Smith (drallensmith on github).

bpo-31185 [https://bugs.python.org/issue?@action=redirect&bpo=31185]: Fixed miscellaneous errors in asyncio speedup module.

bpo-31151 [https://bugs.python.org/issue?@action=redirect&bpo=31151]: socketserver.ForkingMixIn.server_close() now waits until all child processes completed to prevent leaking zombie processes.

bpo-31072 [https://bugs.python.org/issue?@action=redirect&bpo=31072]: Add an include_file parameter to zipapp.create_archive()

bpo-24700 [https://bugs.python.org/issue?@action=redirect&bpo=24700]: Optimize array.array comparison. It is now from 10x up to 70x faster when comparing arrays holding values of the same integer type.

bpo-31135 [https://bugs.python.org/issue?@action=redirect&bpo=31135]: ttk: fix the destroy() method of LabeledScale and OptionMenu classes. Call the parent destroy() method even if the used attribute doesn’t exist. The LabeledScale.destroy() method now also explicitly clears label and scale attributes to help the garbage collector to destroy all widgets.

bpo-31107 [https://bugs.python.org/issue?@action=redirect&bpo=31107]: Fix copyreg._slotnames() mangled attribute calculation for classes whose name begins with an underscore. Patch by Shane Harvey.

bpo-31080 [https://bugs.python.org/issue?@action=redirect&bpo=31080]: Allow logging.config.fileConfig to accept kwargs and/or args.

bpo-30897 [https://bugs.python.org/issue?@action=redirect&bpo=30897]: pathlib.Path objects now include an is_mount() method (only implemented on POSIX). This is similar to os.path.ismount(p). Patch by Cooper Ry Lees.

bpo-31061 [https://bugs.python.org/issue?@action=redirect&bpo=31061]: Fixed a crash when using asyncio and threads.

bpo-30987 [https://bugs.python.org/issue?@action=redirect&bpo=30987]: Added support for CAN ISO-TP protocol in the socket module.

bpo-30522 [https://bugs.python.org/issue?@action=redirect&bpo=30522]: Added a setStream method to logging.StreamHandler to allow the stream to be set after creation.

bpo-30502 [https://bugs.python.org/issue?@action=redirect&bpo=30502]: Fix handling of long oids in ssl. Based on patch by Christian Heimes.

bpo-5288 [https://bugs.python.org/issue?@action=redirect&bpo=5288]: Support tzinfo objects with sub-minute offsets.

bpo-30919 [https://bugs.python.org/issue?@action=redirect&bpo=30919]: Fix shared memory performance regression in multiprocessing in 3.x. Shared memory used anonymous memory mappings in 2.x, while 3.x mmaps actual files. Try to be careful to do as little disk I/O as possible.

bpo-26732 [https://bugs.python.org/issue?@action=redirect&bpo=26732]: Fix too many fds in processes started with the «forkserver» method. A child process would inherit as many fds as the number of still-running children.

bpo-29403 [https://bugs.python.org/issue?@action=redirect&bpo=29403]: Fix unittest.mock’s autospec to not fail on method-bound builtin functions. Patch by Aaron Gallagher.

bpo-30961 [https://bugs.python.org/issue?@action=redirect&bpo=30961]: Fix decrementing a borrowed reference in tracemalloc.

bpo-19896 [https://bugs.python.org/issue?@action=redirect&bpo=19896]: Fix multiprocessing.sharedctypes to recognize typecodes 'q' and 'Q'.

bpo-30946 [https://bugs.python.org/issue?@action=redirect&bpo=30946]: Remove obsolete code in readline module for platforms where GNU readline is older than 2.1 or where select() is not available.

bpo-25684 [https://bugs.python.org/issue?@action=redirect&bpo=25684]: Change ttk.OptionMenu radiobuttons to be unique across instances of OptionMenu.

bpo-30886 [https://bugs.python.org/issue?@action=redirect&bpo=30886]: Fix multiprocessing.Queue.join_thread(): it now waits until the thread completes, even if the thread was started by the same process which created the queue.

bpo-29854 [https://bugs.python.org/issue?@action=redirect&bpo=29854]: Fix segfault in readline when using readline’s history-size option. Patch by Nir Soffer.

bpo-30794 [https://bugs.python.org/issue?@action=redirect&bpo=30794]: Added multiprocessing.Process.kill method to terminate using the SIGKILL signal on Unix.

bpo-30319 [https://bugs.python.org/issue?@action=redirect&bpo=30319]: socket.close() now ignores ECONNRESET error.

bpo-30828 [https://bugs.python.org/issue?@action=redirect&bpo=30828]: Fix out of bounds write in asyncio.CFuture.remove_done_callback().

bpo-30302 [https://bugs.python.org/issue?@action=redirect&bpo=30302]: Use keywords in the repr of datetime.timedelta.

bpo-30807 [https://bugs.python.org/issue?@action=redirect&bpo=30807]: signal.setitimer() may disable the timer when passed a tiny value. Tiny values (such as 1e-6) are valid non-zero values for setitimer(), which is specified as taking microsecond-resolution intervals. However, on some platform, our conversion routine could convert 1e-6 into a zero interval, therefore disabling the timer instead of (re-)scheduling it.

bpo-30441 [https://bugs.python.org/issue?@action=redirect&bpo=30441]: Fix bug when modifying os.environ while iterating over it

bpo-29585 [https://bugs.python.org/issue?@action=redirect&bpo=29585]: Avoid importing sysconfig from site to improve startup speed. Python startup is about 5% faster on Linux and 30% faster on macOS.

bpo-29293 [https://bugs.python.org/issue?@action=redirect&bpo=29293]: Add missing parameter «n» on multiprocessing.Condition.notify(). The doc claims multiprocessing.Condition behaves like threading.Condition, but its notify() method lacked the optional «n» argument (to specify the number of sleepers to wake up) that threading.Condition.notify() accepts.

bpo-30532 [https://bugs.python.org/issue?@action=redirect&bpo=30532]: Fix email header value parser dropping folding white space in certain cases.

bpo-30596 [https://bugs.python.org/issue?@action=redirect&bpo=30596]: Add a close() method to multiprocessing.Process.

bpo-9146 [https://bugs.python.org/issue?@action=redirect&bpo=9146]: Fix a segmentation fault in _hashopenssl when standard hash functions such as md5 are not available in the linked OpenSSL library. As in some special FIPS-140 build environments.

bpo-29169 [https://bugs.python.org/issue?@action=redirect&bpo=29169]: Update zlib to 1.2.11.

bpo-30119 [https://bugs.python.org/issue?@action=redirect&bpo=30119]: ftplib.FTP.putline() now throws ValueError on commands that contains CR or LF. Patch by Dong-hee Na.

bpo-30879 [https://bugs.python.org/issue?@action=redirect&bpo=30879]: os.listdir() and os.scandir() now emit bytes names when called with bytes-like argument.

bpo-30746 [https://bugs.python.org/issue?@action=redirect&bpo=30746]: Prohibited the “=” character in environment variable names in os.putenv() and os.spawn*().

bpo-30664 [https://bugs.python.org/issue?@action=redirect&bpo=30664]: The description of a unittest subtest now preserves the order of keyword arguments of TestCase.subTest().

bpo-21071 [https://bugs.python.org/issue?@action=redirect&bpo=21071]: struct.Struct.format type is now str instead of bytes.

bpo-29212 [https://bugs.python.org/issue?@action=redirect&bpo=29212]: Fix concurrent.futures.thread.ThreadPoolExecutor threads to have a non repr() based thread name by default when no thread_name_prefix is supplied. They will now identify themselves as «ThreadPoolExecutor-y_n».

bpo-29755 [https://bugs.python.org/issue?@action=redirect&bpo=29755]: Fixed the lgettext() family of functions in the gettext module. They now always return bytes.

bpo-30616 [https://bugs.python.org/issue?@action=redirect&bpo=30616]: Functional API of enum allows to create empty enums. Patched by Dong-hee Na

bpo-30038 [https://bugs.python.org/issue?@action=redirect&bpo=30038]: Fix race condition between signal delivery and wakeup file descriptor. Patch by Nathaniel Smith.

bpo-23894 [https://bugs.python.org/issue?@action=redirect&bpo=23894]: lib2to3 now recognizes rb'...' and f'...' strings.

bpo-24744 [https://bugs.python.org/issue?@action=redirect&bpo=24744]: pkgutil.walk_packages function now raises ValueError if path is a string. Patch by Sanyam Khurana.

bpo-24484 [https://bugs.python.org/issue?@action=redirect&bpo=24484]: Avoid race condition in multiprocessing cleanup.

bpo-30589 [https://bugs.python.org/issue?@action=redirect&bpo=30589]: Fix multiprocessing.Process.exitcode to return the opposite of the signal number when the process is killed by a signal (instead of 255) when using the «forkserver» method.

bpo-28994 [https://bugs.python.org/issue?@action=redirect&bpo=28994]: The traceback no longer displayed for SystemExit raised in a callback registered by atexit.

bpo-30508 [https://bugs.python.org/issue?@action=redirect&bpo=30508]: Don’t log exceptions if Task/Future «cancel()» method was called.

bpo-30645 [https://bugs.python.org/issue?@action=redirect&bpo=30645]: Fix path calculation in imp.load_package(), fixing it for cases when a package is only shipped with bytecodes. Patch by Alexandru Ardelean.

bpo-11822 [https://bugs.python.org/issue?@action=redirect&bpo=11822]: The dis.dis() function now is able to disassemble nested code objects.

bpo-30624 [https://bugs.python.org/issue?@action=redirect&bpo=30624]: selectors does not take KeyboardInterrupt and SystemExit into account, leaving a fd in a bad state in case of error. Patch by Giampaolo Rodola”.

bpo-30595 [https://bugs.python.org/issue?@action=redirect&bpo=30595]: multiprocessing.Queue.get() with a timeout now polls its reader in non-blocking mode if it succeeded to acquire the lock but the acquire took longer than the timeout.

bpo-28556 [https://bugs.python.org/issue?@action=redirect&bpo=28556]: Updates to typing module: Add generic AsyncContextManager, add support for ContextManager on all versions. Original PRs by Jelle Zijlstra and Ivan Levkivskyi

bpo-30605 [https://bugs.python.org/issue?@action=redirect&bpo=30605]: re.compile() no longer raises a BytesWarning when compiling a bytes instance with misplaced inline modifier. Patch by Roy Williams.

bpo-29870 [https://bugs.python.org/issue?@action=redirect&bpo=29870]: Fix ssl sockets leaks when connection is aborted in asyncio/ssl implementation. Patch by Michaël Sghaïer.

bpo-29743 [https://bugs.python.org/issue?@action=redirect&bpo=29743]: Closing transport during handshake process leaks open socket. Patch by Nikolay Kim

bpo-27585 [https://bugs.python.org/issue?@action=redirect&bpo=27585]: Fix waiter cancellation in asyncio.Lock. Patch by Mathieu Sornay.

bpo-30014 [https://bugs.python.org/issue?@action=redirect&bpo=30014]: modify() method of poll(), epoll() and devpoll() based classes of selectors module is around 10% faster. Patch by Giampaolo Rodola”.

bpo-30418 [https://bugs.python.org/issue?@action=redirect&bpo=30418]: On Windows, subprocess.Popen.communicate() now also ignore EINVAL on stdin.write() if the child process is still running but closed the pipe.

bpo-30463 [https://bugs.python.org/issue?@action=redirect&bpo=30463]: Addded empty __slots__ to abc.ABC. This allows subclassers to deny __dict__ and __weakref__ creation. Patch by Aaron Hall.

bpo-30520 [https://bugs.python.org/issue?@action=redirect&bpo=30520]: Loggers are now pickleable.

bpo-30557 [https://bugs.python.org/issue?@action=redirect&bpo=30557]: faulthandler now correctly filters and displays exception codes on Windows

bpo-30526 [https://bugs.python.org/issue?@action=redirect&bpo=30526]: Add TextIOWrapper.reconfigure() and a TextIOWrapper.write_through attribute.

bpo-30245 [https://bugs.python.org/issue?@action=redirect&bpo=30245]: Fix possible overflow when organize struct.pack_into error message. Patch by Yuan Liu.

bpo-30378 [https://bugs.python.org/issue?@action=redirect&bpo=30378]: Fix the problem that logging.handlers.SysLogHandler cannot handle IPv6 addresses.

bpo-16500 [https://bugs.python.org/issue?@action=redirect&bpo=16500]: Allow registering at-fork handlers.

bpo-30470 [https://bugs.python.org/issue?@action=redirect&bpo=30470]: Deprecate invalid ctypes call protection on Windows. Patch by Mariatta Wijaya.

bpo-30414 [https://bugs.python.org/issue?@action=redirect&bpo=30414]: multiprocessing.Queue._feed background running thread do not break from main loop on exception.

bpo-30003 [https://bugs.python.org/issue?@action=redirect&bpo=30003]: Fix handling escape characters in HZ codec. Based on patch by Ma Lin.

bpo-30149 [https://bugs.python.org/issue?@action=redirect&bpo=30149]: inspect.signature() now supports callables with variable-argument parameters wrapped with partialmethod. Patch by Dong-hee Na.

bpo-30436 [https://bugs.python.org/issue?@action=redirect&bpo=30436]: importlib.find_spec() raises ModuleNotFoundError instead of AttributeError if the specified parent module is not a package (i.e. lacks a __path__ attribute).

bpo-30301 [https://bugs.python.org/issue?@action=redirect&bpo=30301]: Fix AttributeError when using SimpleQueue.empty() under spawn and forkserver start methods.

bpo-30375 [https://bugs.python.org/issue?@action=redirect&bpo=30375]: Warnings emitted when compile a regular expression now always point to the line in the user code. Previously they could point into inners of the re module if emitted from inside of groups or conditionals.

bpo-30329 [https://bugs.python.org/issue?@action=redirect&bpo=30329]: imaplib and poplib now catch the Windows socket WSAEINVAL error (code 10022) on shutdown(SHUT_RDWR): An invalid operation was attempted. This error occurs sometimes on SSL connections.

bpo-29196 [https://bugs.python.org/issue?@action=redirect&bpo=29196]: Removed previously deprecated in Python 2.4 classes Plist, Dict and _InternalDict in the plistlib module. Dict values in the result of functions readPlist() and readPlistFromBytes() are now normal dicts. You no longer can use attribute access to access items of these dictionaries.

bpo-9850 [https://bugs.python.org/issue?@action=redirect&bpo=9850]: The macpath is now deprecated and will be removed in Python 3.8.

bpo-30299 [https://bugs.python.org/issue?@action=redirect&bpo=30299]: Compiling regular expression in debug mode on CPython now displays the compiled bytecode in human readable form.

bpo-30048 [https://bugs.python.org/issue?@action=redirect&bpo=30048]: Fixed Task.cancel() can be ignored when the task is running coroutine and the coroutine returned without any more await.

bpo-30266 [https://bugs.python.org/issue?@action=redirect&bpo=30266]: contextlib.AbstractContextManager now supports anti-registration by setting __enter__ = None or __exit__ = None, following the pattern introduced in bpo-25958 [https://bugs.python.org/issue?@action=redirect&bpo=25958]. Patch by Jelle Zijlstra.

bpo-30340 [https://bugs.python.org/issue?@action=redirect&bpo=30340]: Enhanced regular expressions optimization. This increased the performance of matching some patterns up to 25 times.

bpo-30298 [https://bugs.python.org/issue?@action=redirect&bpo=30298]: Weaken the condition of deprecation warnings for inline modifiers. Now allowed several subsequential inline modifiers at the start of the pattern (e.g. '(?i)(?s)...'). In verbose mode whitespaces and comments now are allowed before and between inline modifiers (e.g. '(?x) (?i) (?s)...').

bpo-30285 [https://bugs.python.org/issue?@action=redirect&bpo=30285]: Optimized case-insensitive matching and searching of regular expressions.

bpo-29990 [https://bugs.python.org/issue?@action=redirect&bpo=29990]: Fix range checking in GB18030 decoder. Original patch by Ma Lin.

bpo-29979 [https://bugs.python.org/issue?@action=redirect&bpo=29979]: rewrite cgi.parse_multipart, reusing the FieldStorage class and making its results consistent with those of FieldStorage for multipart/form-data requests. Patch by Pierre Quentel.

bpo-30243 [https://bugs.python.org/issue?@action=redirect&bpo=30243]: Removed the __init__ methods of _json’s scanner and encoder. Misusing them could cause memory leaks or crashes. Now scanner and encoder objects are completely initialized in the __new__ methods.

bpo-30215 [https://bugs.python.org/issue?@action=redirect&bpo=30215]: Compiled regular expression objects with the re.LOCALE flag no longer depend on the locale at compile time. Only the locale at matching time affects the result of matching.

bpo-30185 [https://bugs.python.org/issue?@action=redirect&bpo=30185]: Avoid KeyboardInterrupt tracebacks in forkserver helper process when Ctrl-C is received.

bpo-30103 [https://bugs.python.org/issue?@action=redirect&bpo=30103]: binascii.b2a_uu() and uu.encode() now support using '`' as zero instead of space.

bpo-28556 [https://bugs.python.org/issue?@action=redirect&bpo=28556]: Various updates to typing module: add typing.NoReturn type, use WrapperDescriptorType, minor bug-fixes. Original PRs by Jim Fasarakis-Hilliard and Ivan Levkivskyi.

bpo-30205 [https://bugs.python.org/issue?@action=redirect&bpo=30205]: Fix getsockname() for unbound AF_UNIX sockets on Linux.

bpo-30228 [https://bugs.python.org/issue?@action=redirect&bpo=30228]: The seek() and tell() methods of io.FileIO now set the internal seekable attribute to avoid one syscall on open() (in buffered or text mode).

bpo-30190 [https://bugs.python.org/issue?@action=redirect&bpo=30190]: unittest’s assertAlmostEqual and assertNotAlmostEqual provide a better message in case of failure which includes the difference between left and right arguments. (patch by Giampaolo Rodola”)

bpo-30101 [https://bugs.python.org/issue?@action=redirect&bpo=30101]: Add support for curses.A_ITALIC.

bpo-29822 [https://bugs.python.org/issue?@action=redirect&bpo=29822]: inspect.isabstract() now works during __init_subclass__. Patch by Nate Soares.

bpo-29960 [https://bugs.python.org/issue?@action=redirect&bpo=29960]: Preserve generator state when _random.Random.setstate() raises an exception. Patch by Bryan Olson.

bpo-30070 [https://bugs.python.org/issue?@action=redirect&bpo=30070]: Fixed leaks and crashes in errors handling in the parser module.

bpo-22352 [https://bugs.python.org/issue?@action=redirect&bpo=22352]: Column widths in the output of dis.dis() are now adjusted for large line numbers and instruction offsets.

bpo-30061 [https://bugs.python.org/issue?@action=redirect&bpo=30061]: Fixed crashes in IOBase methods __next__() and readlines() when readline() or __next__() respectively return non-sizeable object. Fixed possible other errors caused by not checking results of PyObject_Size(), PySequence_Size(), or PyMapping_Size().

bpo-30218 [https://bugs.python.org/issue?@action=redirect&bpo=30218]: Fix PathLike support for shutil.unpack_archive. Patch by Jelle Zijlstra.

bpo-10076 [https://bugs.python.org/issue?@action=redirect&bpo=10076]: Compiled regular expression and match objects in the re module now support copy.copy() and copy.deepcopy() (they are considered atomic).

bpo-30068 [https://bugs.python.org/issue?@action=redirect&bpo=30068]: _io._IOBase.readlines will check if it’s closed first when hint is present.

bpo-29694 [https://bugs.python.org/issue?@action=redirect&bpo=29694]: Fixed race condition in pathlib mkdir with flags parents=True. Patch by Armin Rigo.

bpo-29692 [https://bugs.python.org/issue?@action=redirect&bpo=29692]: Fixed arbitrary unchaining of RuntimeError exceptions in contextlib.contextmanager. Patch by Siddharth Velankar.

bpo-26187 [https://bugs.python.org/issue?@action=redirect&bpo=26187]: Test that sqlite3 trace callback is not called multiple times when schema is changing. Indirectly fixed by switching to use sqlite3_prepare_v2() in bpo-9303 [https://bugs.python.org/issue?@action=redirect&bpo=9303]. Patch by Aviv Palivoda.

bpo-30017 [https://bugs.python.org/issue?@action=redirect&bpo=30017]: Allowed calling the close() method of the zip entry writer object multiple times. Writing to a closed writer now always produces a ValueError.

bpo-29998 [https://bugs.python.org/issue?@action=redirect&bpo=29998]: Pickling and copying ImportError now preserves name and path attributes.

bpo-29995 [https://bugs.python.org/issue?@action=redirect&bpo=29995]: re.escape() now escapes only regex special characters.

bpo-29962 [https://bugs.python.org/issue?@action=redirect&bpo=29962]: Add math.remainder operation, implementing remainder as specified in IEEE 754.

bpo-29649 [https://bugs.python.org/issue?@action=redirect&bpo=29649]: Improve struct.pack_into() exception messages for problems with the buffer size and offset. Patch by Andrew Nester.

bpo-29654 [https://bugs.python.org/issue?@action=redirect&bpo=29654]: Support If-Modified-Since HTTP header (browser cache). Patch by Pierre Quentel.

bpo-29931 [https://bugs.python.org/issue?@action=redirect&bpo=29931]: Fixed comparison check for ipaddress.ip_interface objects. Patch by Sanjay Sundaresan.

bpo-29953 [https://bugs.python.org/issue?@action=redirect&bpo=29953]: Fixed memory leaks in the replace() method of datetime and time objects when pass out of bound fold argument.

bpo-29942 [https://bugs.python.org/issue?@action=redirect&bpo=29942]: Fix a crash in itertools.chain.from_iterable when encountering long runs of empty iterables.

bpo-10030 [https://bugs.python.org/issue?@action=redirect&bpo=10030]: Sped up reading encrypted ZIP files by 2 times.

bpo-29204 [https://bugs.python.org/issue?@action=redirect&bpo=29204]: Element.getiterator() and the html parameter of XMLParser() were deprecated only in the documentation (since Python 3.2 and 3.4 correspondingly). Now using them emits a deprecation warning.

bpo-27863 [https://bugs.python.org/issue?@action=redirect&bpo=27863]: Fixed multiple crashes in ElementTree caused by race conditions and wrong types.

bpo-25996 [https://bugs.python.org/issue?@action=redirect&bpo=25996]: Added support of file descriptors in os.scandir() on Unix. os.fwalk() is sped up by 2 times by using os.scandir().

bpo-28699 [https://bugs.python.org/issue?@action=redirect&bpo=28699]: Fixed a bug in pools in multiprocessing.pool that raising an exception at the very first of an iterable may swallow the exception or make the program hang. Patch by Davin Potts and Xiang Zhang.

bpo-23890 [https://bugs.python.org/issue?@action=redirect&bpo=23890]: unittest.TestCase.assertRaises() now manually breaks a reference cycle to not keep objects alive longer than expected.

bpo-29901 [https://bugs.python.org/issue?@action=redirect&bpo=29901]: The zipapp module now supports general path-like objects, not just pathlib.Path.

bpo-25803 [https://bugs.python.org/issue?@action=redirect&bpo=25803]: Avoid incorrect errors raised by Path.mkdir(exist_ok=True) when the OS gives priority to errors such as EACCES over EEXIST.

bpo-29861 [https://bugs.python.org/issue?@action=redirect&bpo=29861]: Release references to tasks, their arguments and their results as soon as they are finished in multiprocessing.Pool.

bpo-19930 [https://bugs.python.org/issue?@action=redirect&bpo=19930]: The mode argument of os.makedirs() no longer affects the file permission bits of newly-created intermediate-level directories.

bpo-29884 [https://bugs.python.org/issue?@action=redirect&bpo=29884]: faulthandler: Restore the old sigaltstack during teardown. Patch by Christophe Zeitouny.

bpo-25455 [https://bugs.python.org/issue?@action=redirect&bpo=25455]: Fixed crashes in repr of recursive buffered file-like objects.

bpo-29800 [https://bugs.python.org/issue?@action=redirect&bpo=29800]: Fix crashes in partial.__repr__ if the keys of partial.keywords are not strings. Patch by Michael Seifert.

bpo-8256 [https://bugs.python.org/issue?@action=redirect&bpo=8256]: Fixed possible failing or crashing input() if attributes «encoding» or «errors» of sys.stdin or sys.stdout are not set or are not strings.

bpo-28692 [https://bugs.python.org/issue?@action=redirect&bpo=28692]: Using non-integer value for selecting a plural form in gettext is now deprecated.

bpo-26121 [https://bugs.python.org/issue?@action=redirect&bpo=26121]: Use C library implementation for math functions erf() and erfc().

bpo-29619 [https://bugs.python.org/issue?@action=redirect&bpo=29619]: os.stat() and os.DirEntry.inode() now convert inode (st_ino) using unsigned integers.

bpo-28298 [https://bugs.python.org/issue?@action=redirect&bpo=28298]: Fix a bug that prevented array “Q”, “L” and “I” from accepting big intables (objects that have __int__) as elements.

bpo-29645 [https://bugs.python.org/issue?@action=redirect&bpo=29645]: Speed up importing the webbrowser module. webbrowser.register() is now thread-safe.

bpo-28231 [https://bugs.python.org/issue?@action=redirect&bpo=28231]: The zipfile module now accepts path-like objects for external paths.

bpo-26915 [https://bugs.python.org/issue?@action=redirect&bpo=26915]: index() and count() methods of collections.abc.Sequence now check identity before checking equality when do comparisons.

bpo-28682 [https://bugs.python.org/issue?@action=redirect&bpo=28682]: Added support for bytes paths in os.fwalk().

bpo-29728 [https://bugs.python.org/issue?@action=redirect&bpo=29728]: Add new socket.TCP_NOTSENT_LOWAT (Linux 3.12) constant. Patch by Nathaniel J. Smith.

bpo-29623 [https://bugs.python.org/issue?@action=redirect&bpo=29623]: Allow use of path-like object as a single argument in ConfigParser.read(). Patch by David Ellis.

bpo-9303 [https://bugs.python.org/issue?@action=redirect&bpo=9303]: Migrate sqlite3 module to _v2 API. Patch by Aviv Palivoda.

bpo-28963 [https://bugs.python.org/issue?@action=redirect&bpo=28963]: Fix out of bound iteration in asyncio.Future.remove_done_callback implemented in C.

bpo-29704 [https://bugs.python.org/issue?@action=redirect&bpo=29704]: asyncio.subprocess.SubprocessStreamProtocol no longer closes before all pipes are closed.

bpo-29271 [https://bugs.python.org/issue?@action=redirect&bpo=29271]: Fix Task.current_task and Task.all_tasks implemented in C to accept None argument as their pure Python implementation.

bpo-29703 [https://bugs.python.org/issue?@action=redirect&bpo=29703]: Fix asyncio to support instantiation of new event loops in child processes.

bpo-29615 [https://bugs.python.org/issue?@action=redirect&bpo=29615]: SimpleXMLRPCDispatcher no longer chains KeyError (or any other exception) to exception(s) raised in the dispatched methods. Patch by Petr Motejlek.

bpo-7769 [https://bugs.python.org/issue?@action=redirect&bpo=7769]: Method register_function() of xmlrpc.server.SimpleXMLRPCDispatcher and its subclasses can now be used as a decorator.

bpo-29376 [https://bugs.python.org/issue?@action=redirect&bpo=29376]: Fix assertion error in threading._DummyThread.is_alive().

bpo-28624 [https://bugs.python.org/issue?@action=redirect&bpo=28624]: Add a test that checks that cwd parameter of Popen() accepts PathLike objects. Patch by Sayan Chowdhury.

bpo-28518 [https://bugs.python.org/issue?@action=redirect&bpo=28518]: Start a transaction implicitly before a DML statement. Patch by Aviv Palivoda.

bpo-29742 [https://bugs.python.org/issue?@action=redirect&bpo=29742]: get_extra_info() raises exception if get called on closed ssl transport. Patch by Nikolay Kim.

bpo-16285 [https://bugs.python.org/issue?@action=redirect&bpo=16285]: urllib.parse.quote is now based on RFC 3986 and hence includes “~” in the set of characters that is not quoted by default. Patch by Christian Theune and Ratnadeep Debnath.

bpo-29532 [https://bugs.python.org/issue?@action=redirect&bpo=29532]: Altering a kwarg dictionary passed to functools.partial() no longer affects a partial object after creation.

bpo-29110 [https://bugs.python.org/issue?@action=redirect&bpo=29110]: Fix file object leak in aifc.open() when file is given as a filesystem path and is not in valid AIFF format. Patch by Anthony Zhang.

bpo-22807 [https://bugs.python.org/issue?@action=redirect&bpo=22807]: Add uuid.SafeUUID and uuid.UUID.is_safe to relay information from the platform about whether generated UUIDs are generated with a multiprocessing safe method.

bpo-29576 [https://bugs.python.org/issue?@action=redirect&bpo=29576]: Improve some deprecations in importlib. Some deprecated methods now emit DeprecationWarnings and have better descriptive messages.

bpo-29534 [https://bugs.python.org/issue?@action=redirect&bpo=29534]: Fixed different behaviour of Decimal.from_float() for _decimal and _pydecimal. Thanks Andrew Nester.

bpo-10379 [https://bugs.python.org/issue?@action=redirect&bpo=10379]: locale.format_string now supports the “monetary” keyword argument, and locale.format is deprecated.

bpo-29851 [https://bugs.python.org/issue?@action=redirect&bpo=29851]: importlib.reload() now raises ModuleNotFoundError if the module lacks a spec.

bpo-28556 [https://bugs.python.org/issue?@action=redirect&bpo=28556]: Various updates to typing module: typing.Counter, typing.ChainMap, improved ABC caching, etc. Original PRs by Jelle Zijlstra, Ivan Levkivskyi, Manuel Krebber, and Łukasz Langa.

bpo-29100 [https://bugs.python.org/issue?@action=redirect&bpo=29100]: Fix datetime.fromtimestamp() regression introduced in Python 3.6.0: check minimum and maximum years.

bpo-29416 [https://bugs.python.org/issue?@action=redirect&bpo=29416]: Prevent infinite loop in pathlib.Path.mkdir

bpo-29444 [https://bugs.python.org/issue?@action=redirect&bpo=29444]: Fixed out-of-bounds buffer access in the group() method of the match object. Based on patch by WGH.

bpo-29377 [https://bugs.python.org/issue?@action=redirect&bpo=29377]: Add WrapperDescriptorType, MethodWrapperType, and MethodDescriptorType built-in types to types module. Original patch by Manuel Krebber.

bpo-29218 [https://bugs.python.org/issue?@action=redirect&bpo=29218]: Unused install_misc command is now removed. It has been documented as unused since 2000. Patch by Eric N. Vander Weele.

bpo-29368 [https://bugs.python.org/issue?@action=redirect&bpo=29368]: The extend() method is now called instead of the append() method when unpickle collections.deque and other list-like objects. This can speed up unpickling to 2 times.

bpo-29338 [https://bugs.python.org/issue?@action=redirect&bpo=29338]: The help of a builtin or extension class now includes the constructor signature if __text_signature__ is provided for the class.

bpo-29335 [https://bugs.python.org/issue?@action=redirect&bpo=29335]: Fix subprocess.Popen.wait() when the child process has exited to a stopped instead of terminated state (ex: when under ptrace).

bpo-29290 [https://bugs.python.org/issue?@action=redirect&bpo=29290]: Fix a regression in argparse that help messages would wrap at non-breaking spaces.

bpo-28735 [https://bugs.python.org/issue?@action=redirect&bpo=28735]: Fixed the comparison of mock.MagickMock with mock.ANY.

bpo-29197 [https://bugs.python.org/issue?@action=redirect&bpo=29197]: Removed deprecated function ntpath.splitunc().

bpo-29210 [https://bugs.python.org/issue?@action=redirect&bpo=29210]: Removed support of deprecated argument «exclude» in tarfile.TarFile.add().

bpo-29219 [https://bugs.python.org/issue?@action=redirect&bpo=29219]: Fixed infinite recursion in the repr of uninitialized ctypes.CDLL instances.

bpo-29192 [https://bugs.python.org/issue?@action=redirect&bpo=29192]: Removed deprecated features in the http.cookies module.

bpo-29193 [https://bugs.python.org/issue?@action=redirect&bpo=29193]: A format string argument for string.Formatter.format() is now positional-only.

bpo-29195 [https://bugs.python.org/issue?@action=redirect&bpo=29195]: Removed support of deprecated undocumented keyword arguments in methods of regular expression objects.

bpo-28969 [https://bugs.python.org/issue?@action=redirect&bpo=28969]: Fixed race condition in C implementation of functools.lru_cache. KeyError could be raised when cached function with full cache was simultaneously called from different threads with the same uncached arguments.

bpo-20804 [https://bugs.python.org/issue?@action=redirect&bpo=20804]: The unittest.mock.sentinel attributes now preserve their identity when they are copied or pickled.

bpo-29142 [https://bugs.python.org/issue?@action=redirect&bpo=29142]: In urllib.request, suffixes in no_proxy environment variable with leading dots could match related hostnames again (e.g. .b.c matches a.b.c). Patch by Milan Oberkirch.

bpo-28961 [https://bugs.python.org/issue?@action=redirect&bpo=28961]: Fix unittest.mock._Call helper: don’t ignore the name parameter anymore. Patch written by Jiajun Huang.

bpo-15812 [https://bugs.python.org/issue?@action=redirect&bpo=15812]: inspect.getframeinfo() now correctly shows the first line of a context. Patch by Sam Breese.

bpo-28985 [https://bugs.python.org/issue?@action=redirect&bpo=28985]: Update authorizer constants in sqlite3 module. Patch by Dingyuan Wang.

bpo-29079 [https://bugs.python.org/issue?@action=redirect&bpo=29079]: Prevent infinite loop in pathlib.resolve() on Windows

bpo-13051 [https://bugs.python.org/issue?@action=redirect&bpo=13051]: Fixed recursion errors in large or resized curses.textpad.Textbox. Based on patch by Tycho Andersen.

bpo-9770 [https://bugs.python.org/issue?@action=redirect&bpo=9770]: curses.ascii predicates now work correctly with negative integers.

bpo-28427 [https://bugs.python.org/issue?@action=redirect&bpo=28427]: old keys should not remove new values from WeakValueDictionary when collecting from another thread.

bpo-28923 [https://bugs.python.org/issue?@action=redirect&bpo=28923]: Remove editor artifacts from Tix.py.

bpo-28871 [https://bugs.python.org/issue?@action=redirect&bpo=28871]: Fixed a crash when deallocate deep ElementTree.

bpo-19542 [https://bugs.python.org/issue?@action=redirect&bpo=19542]: Fix bugs in WeakValueDictionary.setdefault() and WeakValueDictionary.pop() when a GC collection happens in another thread.

bpo-20191 [https://bugs.python.org/issue?@action=redirect&bpo=20191]: Fixed a crash in resource.prlimit() when passing a sequence that doesn’t own its elements as limits.

bpo-16255 [https://bugs.python.org/issue?@action=redirect&bpo=16255]: subprocess.Popen uses /system/bin/sh on Android as the shell, instead of /bin/sh.

bpo-28779 [https://bugs.python.org/issue?@action=redirect&bpo=28779]: multiprocessing.set_forkserver_preload() would crash the forkserver process if a preloaded module instantiated some multiprocessing objects such as locks.

bpo-26937 [https://bugs.python.org/issue?@action=redirect&bpo=26937]: The chown() method of the tarfile.TarFile class does not fail now when the grp module cannot be imported, as for example on Android platforms.

bpo-28847 [https://bugs.python.org/issue?@action=redirect&bpo=28847]: dbm.dumb now supports reading read-only files and no longer writes the index file when it is not changed. A deprecation warning is now emitted if the index file is missed and recreated in the “r” and “w” modes (will be an error in future Python releases).

bpo-27030 [https://bugs.python.org/issue?@action=redirect&bpo=27030]: Unknown escapes consisting of '\' and an ASCII letter in re.sub() replacement templates regular expressions now are errors.

bpo-28835 [https://bugs.python.org/issue?@action=redirect&bpo=28835]: Fix a regression introduced in warnings.catch_warnings(): call warnings.showwarning() if it was overridden inside the context manager.

bpo-27172 [https://bugs.python.org/issue?@action=redirect&bpo=27172]: To assist with upgrades from 2.7, the previously documented deprecation of inspect.getfullargspec() has been reversed. This decision may be revisited again after the Python 2.7 branch is no longer officially supported.

bpo-28740 [https://bugs.python.org/issue?@action=redirect&bpo=28740]: Add sys.getandroidapilevel(): return the build time API version of Android as an integer. Function only available on Android.

bpo-26273 [https://bugs.python.org/issue?@action=redirect&bpo=26273]: Add new socket.TCP_CONGESTION (Linux 2.6.13) and socket.TCP_USER_TIMEOUT (Linux 2.6.37) constants. Patch written by Omar Sandoval.

bpo-28752 [https://bugs.python.org/issue?@action=redirect&bpo=28752]: Restored the __reduce__() methods of datetime objects.

bpo-28727 [https://bugs.python.org/issue?@action=redirect&bpo=28727]: Regular expression patterns, _sre.SRE_Pattern objects created by re.compile(), become comparable (only x==y and x!=y operators). This change should fix the bpo-18383 [https://bugs.python.org/issue?@action=redirect&bpo=18383]: don’t duplicate warning filters when the warnings module is reloaded (thing usually only done in unit tests).

bpo-20572 [https://bugs.python.org/issue?@action=redirect&bpo=20572]: Remove the subprocess.Popen.wait endtime parameter. It was deprecated in 3.4 and undocumented prior to that.

bpo-25659 [https://bugs.python.org/issue?@action=redirect&bpo=25659]: In ctypes, prevent a crash calling the from_buffer() and from_buffer_copy() methods on abstract classes like Array.

bpo-28548 [https://bugs.python.org/issue?@action=redirect&bpo=28548]: In the «http.server» module, parse the protocol version if possible, to avoid using HTTP 0.9 in some error responses.

bpo-19717 [https://bugs.python.org/issue?@action=redirect&bpo=19717]: Makes Path.resolve() succeed on paths that do not exist. Patch by Vajrasky Kok

bpo-28563 [https://bugs.python.org/issue?@action=redirect&bpo=28563]: Fixed possible DoS and arbitrary code execution when handle plural form selections in the gettext module. The expression parser now supports exact syntax supported by GNU gettext.

bpo-28387 [https://bugs.python.org/issue?@action=redirect&bpo=28387]: Fixed possible crash in _io.TextIOWrapper deallocator when the garbage collector is invoked in other thread. Based on patch by Sebastian Cufre.

bpo-27517 [https://bugs.python.org/issue?@action=redirect&bpo=27517]: LZMA compressor and decompressor no longer raise exceptions if given empty data twice. Patch by Benjamin Fogle.

bpo-28549 [https://bugs.python.org/issue?@action=redirect&bpo=28549]: Fixed segfault in curses’s addch() with ncurses6.

bpo-28449 [https://bugs.python.org/issue?@action=redirect&bpo=28449]: tarfile.open() with mode «r» or «r:» now tries to open a tar file with compression before trying to open it without compression. Otherwise it had 50% chance failed with ignore_zeros=True.

bpo-23262 [https://bugs.python.org/issue?@action=redirect&bpo=23262]: The webbrowser module now supports Firefox 36+ and derived browsers. Based on patch by Oleg Broytman.

bpo-24241 [https://bugs.python.org/issue?@action=redirect&bpo=24241]: The webbrowser in an X environment now prefers using the default browser directly. Also, the webbrowser register() function now has a documented “preferred” argument, to specify browsers to be returned by get() with no arguments. Patch by David Steele

bpo-27939 [https://bugs.python.org/issue?@action=redirect&bpo=27939]: Fixed bugs in tkinter.ttk.LabeledScale and tkinter.Scale caused by representing the scale as float value internally in Tk. tkinter.IntVar now works if float value is set to underlying Tk variable.

bpo-28255 [https://bugs.python.org/issue?@action=redirect&bpo=28255]: calendar.TextCalendar.prweek() no longer prints a space after a weeks’s calendar. calendar.TextCalendar.pryear() no longer prints redundant newline after a year’s calendar. Based on patch by Xiang Zhang.

bpo-28255 [https://bugs.python.org/issue?@action=redirect&bpo=28255]: calendar.TextCalendar.prmonth() no longer prints a space at the start of new line after printing a month’s calendar. Patch by Xiang Zhang.

bpo-20491 [https://bugs.python.org/issue?@action=redirect&bpo=20491]: The textwrap.TextWrapper class now honors non-breaking spaces. Based on patch by Kaarle Ritvanen.

bpo-28353 [https://bugs.python.org/issue?@action=redirect&bpo=28353]: os.fwalk() no longer fails on broken links.

bpo-28430 [https://bugs.python.org/issue?@action=redirect&bpo=28430]: Fix iterator of C implemented asyncio.Future doesn’t accept non-None value is passed to it.send(val).

bpo-27025 [https://bugs.python.org/issue?@action=redirect&bpo=27025]: Generated names for Tkinter widgets now start by the «!» prefix for readability.

bpo-25464 [https://bugs.python.org/issue?@action=redirect&bpo=25464]: Fixed HList.header_exists() in tkinter.tix module by addin a workaround to Tix library bug.

bpo-28488 [https://bugs.python.org/issue?@action=redirect&bpo=28488]: shutil.make_archive() no longer adds entry «./» to ZIP archive.

bpo-25953 [https://bugs.python.org/issue?@action=redirect&bpo=25953]: re.sub() now raises an error for invalid numerical group reference in replacement template even if the pattern is not found in the string. Error message for invalid group reference now includes the group index and the position of the reference. Based on patch by SilentGhost.

bpo-28469 [https://bugs.python.org/issue?@action=redirect&bpo=28469]: timeit now uses the sequence 1, 2, 5, 10, 20, 50,… instead of 1, 10, 100,… for autoranging.

bpo-28115 [https://bugs.python.org/issue?@action=redirect&bpo=28115]: Command-line interface of the zipfile module now uses argparse. Added support of long options.

bpo-18219 [https://bugs.python.org/issue?@action=redirect&bpo=18219]: Optimize csv.DictWriter for large number of columns. Patch by Mariatta Wijaya.

bpo-28448 [https://bugs.python.org/issue?@action=redirect&bpo=28448]: Fix C implemented asyncio.Future didn’t work on Windows.

bpo-23214 [https://bugs.python.org/issue?@action=redirect&bpo=23214]: In the «io» module, the argument to BufferedReader and BytesIO’s read1() methods is now optional and can be -1, matching the BufferedIOBase specification.

bpo-28480 [https://bugs.python.org/issue?@action=redirect&bpo=28480]: Fix error building socket module when multithreading is disabled.

bpo-28240 [https://bugs.python.org/issue?@action=redirect&bpo=28240]: timeit: remove -c/--clock and -t/--time command line options which were deprecated since Python 3.3.

bpo-28240 [https://bugs.python.org/issue?@action=redirect&bpo=28240]: timeit now repeats the benchmarks 5 times instead of only 3 to make benchmarks more reliable.

bpo-28240 [https://bugs.python.org/issue?@action=redirect&bpo=28240]: timeit autorange now uses a single loop iteration if the benchmark takes less than 10 seconds, instead of 10 iterations. «python3 -m timeit -s “import time” “time.sleep(1)”» now takes 4 seconds instead of 40 seconds.

Distutils.sdist now looks for README and setup.py files with case sensitivity. This behavior matches that found in Setuptools 6.0 and later. See setuptools 100 [https://github.com/pypa/setuptools/issues/100] for rationale.

bpo-24452 [https://bugs.python.org/issue?@action=redirect&bpo=24452]: Make webbrowser support Chrome on Mac OS X. Patch by Ned Batchelder.

bpo-20766 [https://bugs.python.org/issue?@action=redirect&bpo=20766]: Fix references leaked by pdb in the handling of SIGINT handlers.

bpo-27998 [https://bugs.python.org/issue?@action=redirect&bpo=27998]: Fixed bytes path support in os.scandir() on Windows. Patch by Eryk Sun.

bpo-28317 [https://bugs.python.org/issue?@action=redirect&bpo=28317]: The disassembler now decodes FORMAT_VALUE argument.

bpo-28380 [https://bugs.python.org/issue?@action=redirect&bpo=28380]: unittest.mock Mock autospec functions now properly support assert_called, assert_not_called, and assert_called_once.

bpo-28229 [https://bugs.python.org/issue?@action=redirect&bpo=28229]: lzma module now supports pathlib.

bpo-28321 [https://bugs.python.org/issue?@action=redirect&bpo=28321]: Fixed writing non-BMP characters with binary format in plistlib.

bpo-28225 [https://bugs.python.org/issue?@action=redirect&bpo=28225]: bz2 module now supports pathlib. Initial patch by Ethan Furman.

bpo-28227 [https://bugs.python.org/issue?@action=redirect&bpo=28227]: gzip now supports pathlib. Patch by Ethan Furman.

bpo-28332 [https://bugs.python.org/issue?@action=redirect&bpo=28332]: Deprecated silent truncations in socket.htons and socket.ntohs. Original patch by Oren Milman.

bpo-27358 [https://bugs.python.org/issue?@action=redirect&bpo=27358]: Optimized merging var-keyword arguments and improved error message when passing a non-mapping as a var-keyword argument.

bpo-28257 [https://bugs.python.org/issue?@action=redirect&bpo=28257]: Improved error message when passing a non-iterable as a var-positional argument. Added opcode BUILD_TUPLE_UNPACK_WITH_CALL.

bpo-28322 [https://bugs.python.org/issue?@action=redirect&bpo=28322]: Fixed possible crashes when unpickle itertools objects from incorrect pickle data. Based on patch by John Leitch.

bpo-28228 [https://bugs.python.org/issue?@action=redirect&bpo=28228]: imghdr now supports pathlib.

bpo-28226 [https://bugs.python.org/issue?@action=redirect&bpo=28226]: compileall now supports pathlib.

bpo-28314 [https://bugs.python.org/issue?@action=redirect&bpo=28314]: Fix function declaration (C flags) for the getiterator() method of xml.etree.ElementTree.Element.

bpo-28148 [https://bugs.python.org/issue?@action=redirect&bpo=28148]: Stop using localtime() and gmtime() in the time module. Introduced platform independent _PyTime_localtime API that is similar to POSIX localtime_r, but available on all platforms. Patch by Ed Schouten.

bpo-28253 [https://bugs.python.org/issue?@action=redirect&bpo=28253]: Fixed calendar functions for extreme months: 0001-01 and 9999-12. Methods itermonthdays() and itermonthdays2() are reimplemented so that they don’t call itermonthdates() which can cause datetime.date under/overflow.

bpo-28275 [https://bugs.python.org/issue?@action=redirect&bpo=28275]: Fixed possible use after free in the decompress() methods of the LZMADecompressor and BZ2Decompressor classes. Original patch by John Leitch.

bpo-27897 [https://bugs.python.org/issue?@action=redirect&bpo=27897]: Fixed possible crash in sqlite3.Connection.create_collation() if pass invalid string-like object as a name. Patch by Xiang Zhang.

bpo-18844 [https://bugs.python.org/issue?@action=redirect&bpo=18844]: random.choices() now has k as a keyword-only argument to improve the readability of common cases and come into line with the signature used in other languages.

bpo-18893 [https://bugs.python.org/issue?@action=redirect&bpo=18893]: Fix invalid exception handling in Lib/ctypes/macholib/dyld.py. Patch by Madison May.

bpo-27611 [https://bugs.python.org/issue?@action=redirect&bpo=27611]: Fixed support of default root window in the tkinter.tix module. Added the master parameter in the DisplayStyle constructor.

bpo-27348 [https://bugs.python.org/issue?@action=redirect&bpo=27348]: In the traceback module, restore the formatting of exception messages like «Exception: None». This fixes a regression introduced in 3.5a2.

bpo-25651 [https://bugs.python.org/issue?@action=redirect&bpo=25651]: Allow falsy values to be used for msg parameter of subTest().

bpo-27778 [https://bugs.python.org/issue?@action=redirect&bpo=27778]: Fix a memory leak in os.getrandom() when the getrandom() is interrupted by a signal and a signal handler raises a Python exception.

bpo-28200 [https://bugs.python.org/issue?@action=redirect&bpo=28200]: Fix memory leak on Windows in the os module (fix path_converter() function).

bpo-25400 [https://bugs.python.org/issue?@action=redirect&bpo=25400]: RobotFileParser now correctly returns default values for crawl_delay and request_rate. Initial patch by Peter Wirtz.

bpo-27932 [https://bugs.python.org/issue?@action=redirect&bpo=27932]: Prevent memory leak in win32_ver().

Fix UnboundLocalError in socket._sendfile_use_sendfile.

bpo-28075 [https://bugs.python.org/issue?@action=redirect&bpo=28075]: Check for ERROR_ACCESS_DENIED in Windows implementation of os.stat(). Patch by Eryk Sun.

bpo-22493 [https://bugs.python.org/issue?@action=redirect&bpo=22493]: Warning message emitted by using inline flags in the middle of regular expression now contains a (truncated) regex pattern. Patch by Tim Graham.

bpo-25270 [https://bugs.python.org/issue?@action=redirect&bpo=25270]: Prevent codecs.escape_encode() from raising SystemError when an empty bytestring is passed.

bpo-28181 [https://bugs.python.org/issue?@action=redirect&bpo=28181]: Get antigravity over HTTPS. Patch by Kaartic Sivaraam.

bpo-25895 [https://bugs.python.org/issue?@action=redirect&bpo=25895]: Enable WebSocket URL schemes in urllib.parse.urljoin. Patch by Gergely Imreh and Markus Holtermann.

bpo-28114 [https://bugs.python.org/issue?@action=redirect&bpo=28114]: Fix a crash in parse_envlist() when env contains byte strings. Patch by Eryk Sun.

bpo-27599 [https://bugs.python.org/issue?@action=redirect&bpo=27599]: Fixed buffer overrun in binascii.b2a_qp() and binascii.a2b_qp().

bpo-27906 [https://bugs.python.org/issue?@action=redirect&bpo=27906]: Fix socket accept exhaustion during high TCP traffic. Patch by Kevin Conway.

bpo-28174 [https://bugs.python.org/issue?@action=redirect&bpo=28174]: Handle when SO_REUSEPORT isn’t properly supported. Patch by Seth Michael Larson.

bpo-26654 [https://bugs.python.org/issue?@action=redirect&bpo=26654]: Inspect functools.partial in asyncio.Handle.__repr__. Patch by iceboy.

bpo-26909 [https://bugs.python.org/issue?@action=redirect&bpo=26909]: Fix slow pipes IO in asyncio. Patch by INADA Naoki.

bpo-28176 [https://bugs.python.org/issue?@action=redirect&bpo=28176]: Fix callbacks race in asyncio.SelectorLoop.sock_connect.

bpo-27759 [https://bugs.python.org/issue?@action=redirect&bpo=27759]: Fix selectors incorrectly retain invalid file descriptors. Patch by Mark Williams.

bpo-28325 [https://bugs.python.org/issue?@action=redirect&bpo=28325]: Remove vestigial MacOS 9 macurl2path module and its tests.

bpo-28368 [https://bugs.python.org/issue?@action=redirect&bpo=28368]: Refuse monitoring processes if the child watcher has no loop attached. Patch by Vincent Michel.

bpo-28369 [https://bugs.python.org/issue?@action=redirect&bpo=28369]: Raise RuntimeError when transport’s FD is used with add_reader, add_writer, etc.

bpo-28370 [https://bugs.python.org/issue?@action=redirect&bpo=28370]: Speedup asyncio.StreamReader.readexactly. Patch by Коренберг Марк.

bpo-28371 [https://bugs.python.org/issue?@action=redirect&bpo=28371]: Deprecate passing asyncio.Handles to run_in_executor.

bpo-28372 [https://bugs.python.org/issue?@action=redirect&bpo=28372]: Fix asyncio to support formatting of non-python coroutines.

bpo-28399 [https://bugs.python.org/issue?@action=redirect&bpo=28399]: Remove UNIX socket from FS before binding. Patch by Коренберг Марк.

bpo-27972 [https://bugs.python.org/issue?@action=redirect&bpo=27972]: Prohibit Tasks to await on themselves.

bpo-24142 [https://bugs.python.org/issue?@action=redirect&bpo=24142]: Reading a corrupt config file left configparser in an invalid state. Original patch by Florian Höch.

bpo-29581 [https://bugs.python.org/issue?@action=redirect&bpo=29581]: ABCMeta.__new__ now accepts **kwargs, allowing abstract base classes to use keyword parameters in __init_subclass__. Patch by Nate Soares.

bpo-25532 [https://bugs.python.org/issue?@action=redirect&bpo=25532]: inspect.unwrap() will now only try to unwrap an object sys.getrecursionlimit() times, to protect against objects which create a new object on every attribute access.

bpo-30177 [https://bugs.python.org/issue?@action=redirect&bpo=30177]: path.resolve(strict=False) no longer cuts the path after the first element not present in the filesystem. Patch by Antoine Pietri.

Documentation

bpo-31294 [https://bugs.python.org/issue?@action=redirect&bpo=31294]: Fix incomplete code snippet in the ZeroMQSocketListener and ZeroMQSocketHandler examples and adapt them to Python 3.

bpo-21649 [https://bugs.python.org/issue?@action=redirect&bpo=21649]: Add RFC 7525 and Mozilla server side TLS links to SSL documentation.

bpo-31128 [https://bugs.python.org/issue?@action=redirect&bpo=31128]: Allow the pydoc server to bind to arbitrary hostnames.

bpo-30803 [https://bugs.python.org/issue?@action=redirect&bpo=30803]: Clarify doc on truth value testing. Original patch by Peter Thomassen.

bpo-30176 [https://bugs.python.org/issue?@action=redirect&bpo=30176]: Add missing attribute related constants in curses documentation.

bpo-30052 [https://bugs.python.org/issue?@action=redirect&bpo=30052]: the link targets for bytes() and bytearray() are now their respective type definitions, rather than the corresponding builtin function entries. Use bytes and bytearray to reference the latter. In order to ensure this and future cross-reference updates are applied automatically, the daily documentation builds now disable the default output caching features in Sphinx.

bpo-26985 [https://bugs.python.org/issue?@action=redirect&bpo=26985]: Add missing info of code object in inspect documentation.

bpo-19824 [https://bugs.python.org/issue?@action=redirect&bpo=19824]: Improve the documentation for, and links to, template strings by emphasizing their utility for internationalization, and by clarifying some usage constraints. (See also: bpo-20314 [https://bugs.python.org/issue?@action=redirect&bpo=20314], bpo-12518 [https://bugs.python.org/issue?@action=redirect&bpo=12518])

bpo-28929 [https://bugs.python.org/issue?@action=redirect&bpo=28929]: Link the documentation to its source file on GitHub.

bpo-25008 [https://bugs.python.org/issue?@action=redirect&bpo=25008]: Document smtpd.py as effectively deprecated and add a pointer to aiosmtpd, a third-party asyncio-based replacement.

bpo-26355 [https://bugs.python.org/issue?@action=redirect&bpo=26355]: Add canonical header link on each page to corresponding major version of the documentation. Patch by Matthias Bussonnier.

bpo-29349 [https://bugs.python.org/issue?@action=redirect&bpo=29349]: Fix Python 2 syntax in code for building the documentation.

bpo-23722 [https://bugs.python.org/issue?@action=redirect&bpo=23722]: The data model reference and the porting section in the 3.6 What’s New guide now cover the additional __classcell__ handling needed for custom metaclasses to fully support PEP 487 [https://www.python.org/dev/peps/pep-0487] and zero-argument super().

bpo-28513 [https://bugs.python.org/issue?@action=redirect&bpo=28513]: Documented command-line interface of zipfile.

Tests

bpo-29639 [https://bugs.python.org/issue?@action=redirect&bpo=29639]: test.support.HOST is now «localhost», a new HOSTv4 constant has been added for your 127.0.0.1 needs, similar to the existing HOSTv6 constant.

bpo-31320 [https://bugs.python.org/issue?@action=redirect&bpo=31320]: Silence traceback in test_ssl

bpo-31346 [https://bugs.python.org/issue?@action=redirect&bpo=31346]: Prefer PROTOCOL_TLS_CLIENT and PROTOCOL_TLS_SERVER protocols for SSLContext.

bpo-25674 [https://bugs.python.org/issue?@action=redirect&bpo=25674]: Remove sha256.tbs-internet.com ssl test

bpo-30715 [https://bugs.python.org/issue?@action=redirect&bpo=30715]: Address ALPN callback changes for OpenSSL 1.1.0f. The latest version behaves like OpenSSL 1.0.2 and no longer aborts handshake.

bpo-30822 [https://bugs.python.org/issue?@action=redirect&bpo=30822]: regrtest: Exclude tzdata from regrtest –all. When running the test suite using –use=all / -u all, exclude tzdata since it makes test_datetime too slow (15-20 min on some buildbots) which then times out on some buildbots. Fix also regrtest command line parser to allow passing -u extralargefile to run test_zipfile64.

bpo-30695 [https://bugs.python.org/issue?@action=redirect&bpo=30695]: Add the set_nomemory(start, stop) and remove_mem_hooks() functions to the _testcapi module.

bpo-30357 [https://bugs.python.org/issue?@action=redirect&bpo=30357]: test_thread: setUp() now uses support.threading_setup() and support.threading_cleanup() to wait until threads complete to avoid random side effects on following tests. Initial patch written by Grzegorz Grzywacz.

bpo-30197 [https://bugs.python.org/issue?@action=redirect&bpo=30197]: Enhanced functions swap_attr() and swap_item() in the test.support module. They now work when delete replaced attribute or item inside the with statement. The old value of the attribute or item (or None if it doesn’t exist) now will be assigned to the target of the «as» clause, if there is one.

bpo-24932 [https://bugs.python.org/issue?@action=redirect&bpo=24932]: Use proper command line parsing in _testembed

bpo-28950 [https://bugs.python.org/issue?@action=redirect&bpo=28950]: Disallow -j0 to be combined with -T/-l in regrtest command line arguments.

bpo-28683 [https://bugs.python.org/issue?@action=redirect&bpo=28683]: Fix the tests that bind() a unix socket and raise PermissionError on Android for a non-root user.

bpo-26936 [https://bugs.python.org/issue?@action=redirect&bpo=26936]: Fix the test_socket failures on Android - getservbyname(), getservbyport() and getaddrinfo() are broken on some Android API levels.

bpo-28666 [https://bugs.python.org/issue?@action=redirect&bpo=28666]: Now test.support.rmtree is able to remove unwritable or unreadable directories.

bpo-23839 [https://bugs.python.org/issue?@action=redirect&bpo=23839]: Various caches now are cleared before running every test file.

bpo-26944 [https://bugs.python.org/issue?@action=redirect&bpo=26944]: Fix test_posix for Android where “id -G” is entirely wrong or missing the effective gid.

bpo-28409 [https://bugs.python.org/issue?@action=redirect&bpo=28409]: regrtest: fix the parser of command line arguments.

bpo-28217 [https://bugs.python.org/issue?@action=redirect&bpo=28217]: Adds _testconsole module to test console input.

bpo-26939 [https://bugs.python.org/issue?@action=redirect&bpo=26939]: Add the support.setswitchinterval() function to fix test_functools hanging on the Android armv7 qemu emulator.

Build

bpo-31354 [https://bugs.python.org/issue?@action=redirect&bpo=31354]: Allow –with-lto to be used on all builds, not just make profile-opt.

bpo-31370 [https://bugs.python.org/issue?@action=redirect&bpo=31370]: Remove support for building –without-threads. This option is not really useful anymore in the 21st century. Removing lots of conditional paths allows us to simplify the code base, including in difficult to maintain low-level internal code.

bpo-31341 [https://bugs.python.org/issue?@action=redirect&bpo=31341]: Per PEP 11 [https://www.python.org/dev/peps/pep-0011], support for the IRIX operating system was removed.

bpo-30854 [https://bugs.python.org/issue?@action=redirect&bpo=30854]: Fix compile error when compiling –without-threads. Patch by Masayuki Yamamoto.

bpo-30687 [https://bugs.python.org/issue?@action=redirect&bpo=30687]: Locate msbuild.exe on Windows when building rather than vcvarsall.bat

bpo-20210 [https://bugs.python.org/issue?@action=redirect&bpo=20210]: Support the disabled marker in Setup files. Extension modules listed after this marker are not built at all, neither by the Makefile nor by setup.py.

bpo-29941 [https://bugs.python.org/issue?@action=redirect&bpo=29941]: Add --with-assertions configure flag to explicitly enable C assert() checks. Defaults to off. --with-pydebug implies --with-assertions.

bpo-28787 [https://bugs.python.org/issue?@action=redirect&bpo=28787]: Fix out-of-tree builds of Python when configured with --with--dtrace.

bpo-29243 [https://bugs.python.org/issue?@action=redirect&bpo=29243]: Prevent unnecessary rebuilding of Python during make test, make install and some other make targets when configured with --enable-optimizations.

bpo-23404 [https://bugs.python.org/issue?@action=redirect&bpo=23404]: Don’t regenerate generated files based on file modification time anymore: the action is now explicit. Replace make touch with make regen-all.

bpo-29643 [https://bugs.python.org/issue?@action=redirect&bpo=29643]: Fix --enable-optimization didn’t work.

bpo-27593 [https://bugs.python.org/issue?@action=redirect&bpo=27593]: sys.version and the platform module python_build(), python_branch(), and python_revision() functions now use git information rather than hg when building from a repo.

bpo-29572 [https://bugs.python.org/issue?@action=redirect&bpo=29572]: Update Windows build and OS X installers to use OpenSSL 1.0.2k.

bpo-27659 [https://bugs.python.org/issue?@action=redirect&bpo=27659]: Prohibit implicit C function declarations: use -Werror=implicit-function-declaration when possible (GCC and Clang, but it depends on the compiler version). Patch written by Chi Hsuan Yen.

bpo-29384 [https://bugs.python.org/issue?@action=redirect&bpo=29384]: Remove old Be OS helper scripts.

bpo-26851 [https://bugs.python.org/issue?@action=redirect&bpo=26851]: Set Android compilation and link flags.

bpo-28768 [https://bugs.python.org/issue?@action=redirect&bpo=28768]: Fix implicit declaration of function _setmode. Patch by Masayuki Yamamoto

bpo-29080 [https://bugs.python.org/issue?@action=redirect&bpo=29080]: Removes hard dependency on hg.exe from PCBuild/build.bat

bpo-23903 [https://bugs.python.org/issue?@action=redirect&bpo=23903]: Added missed names to PC/python3.def.

bpo-28762 [https://bugs.python.org/issue?@action=redirect&bpo=28762]: lockf() is available on Android API level 24, but the F_LOCK macro is not defined in android-ndk-r13.

bpo-28538 [https://bugs.python.org/issue?@action=redirect&bpo=28538]: Fix the compilation error that occurs because if_nameindex() is available on Android API level 24, but the if_nameindex structure is not defined.

bpo-20211 [https://bugs.python.org/issue?@action=redirect&bpo=20211]: Do not add the directory for installing C header files and the directory for installing object code libraries to the cross compilation search paths. Original patch by Thomas Petazzoni.

bpo-28849 [https://bugs.python.org/issue?@action=redirect&bpo=28849]: Do not define sys.implementation._multiarch on Android.

bpo-10656 [https://bugs.python.org/issue?@action=redirect&bpo=10656]: Fix out-of-tree building on AIX. Patch by Tristan Carel and Michael Haubenwallner.

bpo-26359 [https://bugs.python.org/issue?@action=redirect&bpo=26359]: Rename –with-optimiations to –enable-optimizations.

bpo-28444 [https://bugs.python.org/issue?@action=redirect&bpo=28444]: Fix missing extensions modules when cross compiling.

bpo-28208 [https://bugs.python.org/issue?@action=redirect&bpo=28208]: Update Windows build and OS X installers to use SQLite 3.14.2.

bpo-28248 [https://bugs.python.org/issue?@action=redirect&bpo=28248]: Update Windows build and OS X installers to use OpenSSL 1.0.2j.

bpo-21124 [https://bugs.python.org/issue?@action=redirect&bpo=21124]: Fix building the _struct module on Cygwin by passing NULL instead of &PyType_Type to PyVarObject_HEAD_INIT. Patch by Masayuki Yamamoto.

bpo-13756 [https://bugs.python.org/issue?@action=redirect&bpo=13756]: Fix building extensions modules on Cygwin. Patch by Roumen Petrov, based on original patch by Jason Tishler.

bpo-21085 [https://bugs.python.org/issue?@action=redirect&bpo=21085]: Add configure check for siginfo_t.si_band, which Cygwin does not provide. Patch by Masayuki Yamamoto with review and rebase by Erik Bray.

bpo-28258 [https://bugs.python.org/issue?@action=redirect&bpo=28258]: Fixed build with Estonian locale (python-config and distclean targets in Makefile). Patch by Arfrever Frehtes Taifersar Arahesis.

bpo-26661 [https://bugs.python.org/issue?@action=redirect&bpo=26661]: setup.py now detects system libffi with multiarch wrapper.

bpo-27979 [https://bugs.python.org/issue?@action=redirect&bpo=27979]: A full copy of libffi is no longer bundled for use when building _ctypes on non-OSX UNIX platforms. An installed copy of libffi is now required when building _ctypes on such platforms.

bpo-15819 [https://bugs.python.org/issue?@action=redirect&bpo=15819]: Remove redundant include search directory option for building outside the source tree.

bpo-28676 [https://bugs.python.org/issue?@action=redirect&bpo=28676]: Prevent missing “getentropy” declaration warning on macOS. Patch by Gareth Rees.

Windows

bpo-31392 [https://bugs.python.org/issue?@action=redirect&bpo=31392]: Update Windows build to use OpenSSL 1.1.0f

bpo-30389 [https://bugs.python.org/issue?@action=redirect&bpo=30389]: Adds detection of Visual Studio 2017 to distutils on Windows.

bpo-31358 [https://bugs.python.org/issue?@action=redirect&bpo=31358]: zlib is no longer bundled in the CPython source, instead it is downloaded on demand just like bz2, lzma, OpenSSL, Tcl/Tk, and SQLite.

bpo-31340 [https://bugs.python.org/issue?@action=redirect&bpo=31340]: Change to building with MSVC v141 (included with Visual Studio 2017)

bpo-30581 [https://bugs.python.org/issue?@action=redirect&bpo=30581]: os.cpu_count() now returns the correct number of processors on Windows when the number of logical processors is greater than 64.

bpo-30916 [https://bugs.python.org/issue?@action=redirect&bpo=30916]: Pre-build OpenSSL, Tcl and Tk and include the binaries in the build.

bpo-30731 [https://bugs.python.org/issue?@action=redirect&bpo=30731]: Add a missing xmlns to python.manifest so that it matches the schema.

bpo-30291 [https://bugs.python.org/issue?@action=redirect&bpo=30291]: Allow requiring 64-bit interpreters from py.exe using -64 suffix. Contributed by Steve (Gadget) Barnes.

bpo-30362 [https://bugs.python.org/issue?@action=redirect&bpo=30362]: Adds list options (-0, -0p) to py.exe launcher. Contributed by Steve Barnes.

bpo-23451 [https://bugs.python.org/issue?@action=redirect&bpo=23451]: Fix socket deprecation warnings in socketmodule.c. Patch by Segev Finer.

bpo-30450 [https://bugs.python.org/issue?@action=redirect&bpo=30450]: The build process on Windows no longer depends on Subversion, instead pulling external code from GitHub via a Python script. If Python 3.6 is not found on the system (via py -3.6), NuGet is used to download a copy of 32-bit Python.

bpo-29579 [https://bugs.python.org/issue?@action=redirect&bpo=29579]: Removes readme.txt from the installer.

bpo-25778 [https://bugs.python.org/issue?@action=redirect&bpo=25778]: winreg does not truncate string correctly (Patch by Eryk Sun)

bpo-28896 [https://bugs.python.org/issue?@action=redirect&bpo=28896]: Deprecate WindowsRegistryFinder and disable it by default

bpo-28522 [https://bugs.python.org/issue?@action=redirect&bpo=28522]: Fixes mishandled buffer reallocation in getpathp.c

bpo-28402 [https://bugs.python.org/issue?@action=redirect&bpo=28402]: Adds signed catalog files for stdlib on Windows.

bpo-28333 [https://bugs.python.org/issue?@action=redirect&bpo=28333]: Enables Unicode for ps1/ps2 and input() prompts. (Patch by Eryk Sun)

bpo-28251 [https://bugs.python.org/issue?@action=redirect&bpo=28251]: Improvements to help manuals on Windows.

bpo-28110 [https://bugs.python.org/issue?@action=redirect&bpo=28110]: launcher.msi has different product codes between 32-bit and 64-bit

bpo-28161 [https://bugs.python.org/issue?@action=redirect&bpo=28161]: Opening CON for write access fails

bpo-28162 [https://bugs.python.org/issue?@action=redirect&bpo=28162]: WindowsConsoleIO readall() fails if first line starts with Ctrl+Z

bpo-28163 [https://bugs.python.org/issue?@action=redirect&bpo=28163]: WindowsConsoleIO fileno() passes wrong flags to _open_osfhandle

bpo-28164 [https://bugs.python.org/issue?@action=redirect&bpo=28164]: _PyIO_get_console_type fails for various paths

bpo-28137 [https://bugs.python.org/issue?@action=redirect&bpo=28137]: Renames Windows path file to ._pth

bpo-28138 [https://bugs.python.org/issue?@action=redirect&bpo=28138]: Windows ._pth file should allow import site

IDLE

bpo-31493 [https://bugs.python.org/issue?@action=redirect&bpo=31493]: IDLE code context – fix code update and font update timers. Canceling timers prevents a warning message when test_idle completes.

bpo-31488 [https://bugs.python.org/issue?@action=redirect&bpo=31488]: IDLE - Update non-key options in former extension classes. When applying configdialog changes, call .reload for each feature class. Change ParenMatch so updated options affect existing instances attached to existing editor windows.

bpo-31477 [https://bugs.python.org/issue?@action=redirect&bpo=31477]: IDLE - Improve rstrip entry in doc. Strip trailing whitespace strips more than blank spaces. Multiline string literals are not skipped.

bpo-31480 [https://bugs.python.org/issue?@action=redirect&bpo=31480]: IDLE - make tests pass with zzdummy extension disabled by default.

bpo-31421 [https://bugs.python.org/issue?@action=redirect&bpo=31421]: Document how IDLE runs tkinter programs. IDLE calls tcl/tk update in the background in order to make live interaction and experimentation with tkinter applications much easier.

bpo-31414 [https://bugs.python.org/issue?@action=redirect&bpo=31414]: IDLE – fix tk entry box tests by deleting first. Adding to an int entry is not the same as deleting and inserting because int(“”) will fail.

bpo-31051 [https://bugs.python.org/issue?@action=redirect&bpo=31051]: Rearrange IDLE configdialog GenPage into Window, Editor, and Help sections.

bpo-30617 [https://bugs.python.org/issue?@action=redirect&bpo=30617]: IDLE - Add docstrings and tests for outwin subclass of editor. Move some data and functions from the class to module level. Patch by Cheryl Sabella.

bpo-31287 [https://bugs.python.org/issue?@action=redirect&bpo=31287]: IDLE - Do not modify tkinter.message in test_configdialog.

bpo-27099 [https://bugs.python.org/issue?@action=redirect&bpo=27099]: Convert IDLE’s built-in “extensions” to regular features. About 10 IDLE features were implemented as supposedly optional extensions. Their different behavior could be confusing or worse for users and not good for maintenance. Hence the conversion. The main difference for users is that user configurable key bindings for builtin features are now handled uniformly. Now, editing a binding in a keyset only affects its value in the keyset. All bindings are defined together in the system-specific default keysets in config-extensions.def. All custom keysets are saved as a whole in config-extension.cfg. All take effect as soon as one clicks Apply or Ok. The affected events are “<<force-open-completions>>”, “<<expand-word>>”, “<<force-open-calltip>>”, “<<flash-paren>>”, “<<format-paragraph>>”, “<<run-module>>”, “<<check-module>>”, and “<<zoom-height>>”. Any (global) customizations made before 3.6.3 will not affect their keyset-specific customization after 3.6.3. and vice versa. Initial patch by Charles Wohlganger.

bpo-31206 [https://bugs.python.org/issue?@action=redirect&bpo=31206]: IDLE: Factor HighPage(Frame) class from ConfigDialog. Patch by Cheryl Sabella.

bpo-31001 [https://bugs.python.org/issue?@action=redirect&bpo=31001]: Add tests for configdialog highlight tab. Patch by Cheryl Sabella.

bpo-31205 [https://bugs.python.org/issue?@action=redirect&bpo=31205]: IDLE: Factor KeysPage(Frame) class from ConfigDialog. The slightly modified tests continue to pass. Patch by Cheryl Sabella.

bpo-31130 [https://bugs.python.org/issue?@action=redirect&bpo=31130]: IDLE – stop leaks in test_configdialog. Initial patch by Victor Stinner.

bpo-31002 [https://bugs.python.org/issue?@action=redirect&bpo=31002]: Add tests for configdialog keys tab. Patch by Cheryl Sabella.

bpo-19903 [https://bugs.python.org/issue?@action=redirect&bpo=19903]: IDLE: Calltips use inspect.signature instead of inspect.getfullargspec. This improves calltips for builtins converted to use Argument Clinic. Patch by Louie Lu.

bpo-31083 [https://bugs.python.org/issue?@action=redirect&bpo=31083]: IDLE - Add an outline of a TabPage class in configdialog. Update existing classes to match outline. Initial patch by Cheryl Sabella.

bpo-31050 [https://bugs.python.org/issue?@action=redirect&bpo=31050]: Factor GenPage(Frame) class from ConfigDialog. The slightly modified tests continue to pass. Patch by Cheryl Sabella.

bpo-31004 [https://bugs.python.org/issue?@action=redirect&bpo=31004]: IDLE - Factor FontPage(Frame) class from ConfigDialog. Slightly modified tests continue to pass. Fix General tests. Patch mostly by Cheryl Sabella.

bpo-30781 [https://bugs.python.org/issue?@action=redirect&bpo=30781]: IDLE - Use ttk widgets in ConfigDialog. Patches by Terry Jan Reedy and Cheryl Sabella.

bpo-31060 [https://bugs.python.org/issue?@action=redirect&bpo=31060]: IDLE - Finish rearranging methods of ConfigDialog Grouping methods pertaining to each tab and the buttons will aid writing tests and improving the tabs and will enable splitting the groups into classes.

bpo-30853 [https://bugs.python.org/issue?@action=redirect&bpo=30853]: IDLE – Factor a VarTrace class out of ConfigDialog. Instance tracers manages pairs consisting of a tk variable and a callback function. When tracing is turned on, setting the variable calls the function. Test coverage for the new class is 100%.

bpo-31003 [https://bugs.python.org/issue?@action=redirect&bpo=31003]: IDLE: Add more tests for General tab.

bpo-30993 [https://bugs.python.org/issue?@action=redirect&bpo=30993]: IDLE - Improve configdialog font page and tests. In configdialog: Document causal pathways in create_font_tab docstring. Simplify some attribute names. Move set_samples calls to var_changed_font (idea from Cheryl Sabella). Move related functions to positions after the create widgets function. In test_configdialog: Fix test_font_set so not order dependent. Fix renamed test_indent_scale so it tests the widget. Adjust tests for movement of set_samples call. Add tests for load functions. Put all font tests in one class and tab indent tests in another. Except for two lines, these tests completely cover the related functions.

bpo-30981 [https://bugs.python.org/issue?@action=redirect&bpo=30981]: IDLE – Add more configdialog font page tests.

bpo-28523 [https://bugs.python.org/issue?@action=redirect&bpo=28523]: IDLE: replace “colour” with “color” in configdialog.

bpo-30917 [https://bugs.python.org/issue?@action=redirect&bpo=30917]: Add tests for idlelib.config.IdleConf. Increase coverage from 46% to 96%. Patch by Louie Lu.

bpo-30934 [https://bugs.python.org/issue?@action=redirect&bpo=30934]: Document coverage details for idlelib tests. Add section to idlelib/idle-test/README.txt. Include check that branches are taken both ways. Exclude IDLE-specific code that does not run during unit tests.

bpo-30913 [https://bugs.python.org/issue?@action=redirect&bpo=30913]: IDLE: Document ConfigDialog tk Vars, methods, and widgets in docstrings This will facilitate improving the dialog and splitting up the class. Original patch by Cheryl Sabella.

bpo-30899 [https://bugs.python.org/issue?@action=redirect&bpo=30899]: IDLE: Add tests for ConfigParser subclasses in config. Patch by Louie Lu.

bpo-30881 [https://bugs.python.org/issue?@action=redirect&bpo=30881]: IDLE: Add docstrings to browser.py. Patch by Cheryl Sabella.

bpo-30851 [https://bugs.python.org/issue?@action=redirect&bpo=30851]: IDLE: Remove unused variables in configdialog. One is a duplicate, one is set but cannot be altered by users. Patch by Cheryl Sabella.

bpo-30870 [https://bugs.python.org/issue?@action=redirect&bpo=30870]: IDLE: In Settings dialog, select font with Up, Down keys as well as mouse. Initial patch by Louie Lu.

bpo-8231 [https://bugs.python.org/issue?@action=redirect&bpo=8231]: IDLE: call config.IdleConf.GetUserCfgDir only once.

bpo-30779 [https://bugs.python.org/issue?@action=redirect&bpo=30779]: IDLE: Factor ConfigChanges class from configdialog, put in config; test. * In config, put dump test code in a function; run it and unittest in “if __name__ == “__main__”. * Add class config.ConfigChanges based on changes_class_v4.py on bpo issue. * Add class test_config.ChangesTest, partly using configdialog_tests_v1.py. * Revise configdialog to use ConfigChanges; see tracker msg297804. * Revise test_configdialog to match configdialog changes. * Remove configdialog functions unused or moved to ConfigChanges. Cheryl Sabella contributed parts of the patch.

bpo-30777 [https://bugs.python.org/issue?@action=redirect&bpo=30777]: IDLE: configdialog - Add docstrings and fix comments. Patch by Cheryl Sabella.

bpo-30495 [https://bugs.python.org/issue?@action=redirect&bpo=30495]: IDLE: Improve textview with docstrings, PEP8 names, and more tests. Patch by Cheryl Sabella.

bpo-30723 [https://bugs.python.org/issue?@action=redirect&bpo=30723]: IDLE: Make several improvements to parenmatch. Add “parens” style to highlight both opener and closer. Make “default” style, which is not default, a synonym for “opener”. Make time-delay work the same with all styles. Add help for config dialog extensions tab, including help for parenmatch. Add new tests. Original patch by Charles Wohlganger.

bpo-30674 [https://bugs.python.org/issue?@action=redirect&bpo=30674]: IDLE: add docstrings to grep module. Patch by Cheryl Sabella

bpo-21519 [https://bugs.python.org/issue?@action=redirect&bpo=21519]: IDLE’s basic custom key entry dialog now detects duplicates properly. Original patch by Saimadhav Heblikar.

bpo-29910 [https://bugs.python.org/issue?@action=redirect&bpo=29910]: IDLE no longer deletes a character after commenting out a region by a key shortcut. Add return 'break' for this and other potential conflicts between IDLE and default key bindings.

bpo-30728 [https://bugs.python.org/issue?@action=redirect&bpo=30728]: Review and change idlelib.configdialog names. Lowercase method and attribute names. Replace “colour” with “color”, expand overly cryptic names, delete unneeded underscores. Replace import * with specific imports. Patches by Cheryl Sabella.

bpo-6739 [https://bugs.python.org/issue?@action=redirect&bpo=6739]: IDLE: Verify user-entered key sequences by trying to bind them with tk. Add tests for all 3 validation functions. Original patch by G Polo. Tests added by Cheryl Sabella.

bpo-15786 [https://bugs.python.org/issue?@action=redirect&bpo=15786]: Fix several problems with IDLE’s autocompletion box. The following should now work: clicking on selection box items; using the scrollbar; selecting an item by hitting Return. Hangs on MacOSX should no longer happen. Patch by Louie Lu.

bpo-25514 [https://bugs.python.org/issue?@action=redirect&bpo=25514]: Add doc subsubsection about IDLE failure to start. Popup no-connection message directs users to this section.

bpo-30642 [https://bugs.python.org/issue?@action=redirect&bpo=30642]: Fix reference leaks in IDLE tests. Patches by Louie Lu and Terry Jan Reedy.

bpo-30495 [https://bugs.python.org/issue?@action=redirect&bpo=30495]: Add docstrings for textview.py and use PEP8 names. Patches by Cheryl Sabella and Terry Jan Reedy.

bpo-30290 [https://bugs.python.org/issue?@action=redirect&bpo=30290]: Help-about: use pep8 names and add tests. Increase coverage to 100%. Patches by Louie Lu, Cheryl Sabella, and Terry Jan Reedy.

bpo-30303 [https://bugs.python.org/issue?@action=redirect&bpo=30303]: Add _utest option to textview; add new tests. Increase coverage to 100%. Patches by Louie Lu and Terry Jan Reedy.

bpo-29071 [https://bugs.python.org/issue?@action=redirect&bpo=29071]: IDLE colors f-string prefixes (but not invalid ur prefixes).

bpo-28572 [https://bugs.python.org/issue?@action=redirect&bpo=28572]: Add 10% to coverage of IDLE’s test_configdialog. Update and augment description of the configuration system.

Tools/Demos

bpo-30983 [https://bugs.python.org/issue?@action=redirect&bpo=30983]: gdb integration commands (py-bt, etc.) work on optimized shared builds now, too. PEP 523 [https://www.python.org/dev/peps/pep-0523] introduced _PyEval_EvalFrameDefault which inlines PyEval_EvalFrameEx on non-debug shared builds. This broke the ability to use py-bt, py-up, and a few other Python-specific gdb integrations. The problem is fixed by only looking for _PyEval_EvalFrameDefault frames in python-gdb.py. Original patch by Bruno «Polaco» Penteado.

bpo-29748 [https://bugs.python.org/issue?@action=redirect&bpo=29748]: Added the slice index converter in Argument Clinic.

bpo-24037 [https://bugs.python.org/issue?@action=redirect&bpo=24037]: Argument Clinic now uses the converter bool(accept={int}) rather than int for semantical booleans. This avoids repeating the default value for Python and C and will help in converting to bool in future.

bpo-29367 [https://bugs.python.org/issue?@action=redirect&bpo=29367]: python-gdb.py now supports also method-wrapper (wrapperobject) objects.

bpo-28023 [https://bugs.python.org/issue?@action=redirect&bpo=28023]: Fix python-gdb.py didn’t support new dict implementation.

bpo-15369 [https://bugs.python.org/issue?@action=redirect&bpo=15369]: The pybench and pystone microbenchmark have been removed from Tools. Please use the new Python benchmark suite https://github.com/python/performance which is more reliable and includes a portable version of pybench working on Python 2 and Python 3.

bpo-28102 [https://bugs.python.org/issue?@action=redirect&bpo=28102]: The zipfile module CLI now prints usage to stderr. Patch by Stephen J. Turnbull.

C API

bpo-31338 [https://bugs.python.org/issue?@action=redirect&bpo=31338]: Added the Py_UNREACHABLE() macro for code paths which are never expected to be reached. This and a few other useful macros are now documented in the C API manual.

bpo-30832 [https://bugs.python.org/issue?@action=redirect&bpo=30832]: Remove own implementation for thread-local storage. CPython has provided the own implementation for thread-local storage (TLS) on Python/thread.c, it’s used in the case which a platform has not supplied native TLS. However, currently all supported platforms (Windows and pthreads) have provided native TLS and defined the Py_HAVE_NATIVE_TLS macro with unconditional in any case.

bpo-30708 [https://bugs.python.org/issue?@action=redirect&bpo=30708]: PyUnicode_AsWideCharString() now raises a ValueError if the second argument is NULL and the wchar_t* string contains null characters.

bpo-16500 [https://bugs.python.org/issue?@action=redirect&bpo=16500]: Deprecate PyOS_AfterFork() and add PyOS_BeforeFork(), PyOS_AfterFork_Parent() and PyOS_AfterFork_Child().

bpo-6532 [https://bugs.python.org/issue?@action=redirect&bpo=6532]: The type of results of PyThread_start_new_thread() and PyThread_get_thread_ident(), and the id parameter of PyThreadState_SetAsyncExc() changed from «long» to «unsigned long».

bpo-27867 [https://bugs.python.org/issue?@action=redirect&bpo=27867]: Function PySlice_GetIndicesEx() is deprecated and replaced with a macro if Py_LIMITED_API is not set or set to the value between 0x03050400 and 0x03060000 (not including) or 0x03060100 or higher. Added functions PySlice_Unpack() and PySlice_AdjustIndices().

bpo-29083 [https://bugs.python.org/issue?@action=redirect&bpo=29083]: Fixed the declaration of some public API functions. PyArg_VaParse() and PyArg_VaParseTupleAndKeywords() were not available in limited API. PyArg_ValidateKeywordArguments(), PyArg_UnpackTuple() and Py_BuildValue() were not available in limited API of version < 3.3 when PY_SSIZE_T_CLEAN is defined.

bpo-28769 [https://bugs.python.org/issue?@action=redirect&bpo=28769]: The result of PyUnicode_AsUTF8AndSize() and PyUnicode_AsUTF8() is now of type const char * rather of char *.

bpo-29058 [https://bugs.python.org/issue?@action=redirect&bpo=29058]: All stable API extensions added after Python 3.2 are now available only when Py_LIMITED_API is set to the PY_VERSION_HEX value of the minimum Python version supporting this API.

bpo-28822 [https://bugs.python.org/issue?@action=redirect&bpo=28822]: The index parameters start and end of PyUnicode_FindChar() are now adjusted to behave like str[start:end].

bpo-28808 [https://bugs.python.org/issue?@action=redirect&bpo=28808]: PyUnicode_CompareWithASCIIString() now never raises exceptions.

bpo-28761 [https://bugs.python.org/issue?@action=redirect&bpo=28761]: The fields name and doc of structures PyMemberDef, PyGetSetDef, PyStructSequence_Field, PyStructSequence_Desc, and wrapperbase are now of type const char * rather of char *.

bpo-28748 [https://bugs.python.org/issue?@action=redirect&bpo=28748]: Private variable _Py_PackageContext is now of type const char * rather of char *.

bpo-19569 [https://bugs.python.org/issue?@action=redirect&bpo=19569]: Compiler warnings are now emitted if use most of deprecated functions.

bpo-28426 [https://bugs.python.org/issue?@action=redirect&bpo=28426]: Deprecated undocumented functions PyUnicode_AsEncodedObject(), PyUnicode_AsDecodedObject(), PyUnicode_AsDecodedUnicode() and PyUnicode_AsEncodedUnicode().

Python 3.6.6 final

Release date: 2018-06-27

There were no new changes in version 3.6.6.

Python 3.6.6 release candidate 1

Release date: 2018-06-11

Core and Builtins

bpo-33786 [https://bugs.python.org/issue?@action=redirect&bpo=33786]: Fix asynchronous generators to handle GeneratorExit in athrow() correctly

bpo-30654 [https://bugs.python.org/issue?@action=redirect&bpo=30654]: Fixed reset of the SIGINT handler to SIG_DFL on interpreter shutdown even when there was a custom handler set previously. Patch by Philipp Kerling.

bpo-33622 [https://bugs.python.org/issue?@action=redirect&bpo=33622]: Fixed a leak when the garbage collector fails to add an object with the __del__ method or referenced by it into the gc.garbage list. PyGC_Collect() can now be called when an exception is set and preserves it.

bpo-31849 [https://bugs.python.org/issue?@action=redirect&bpo=31849]: Fix signed/unsigned comparison warning in pyhash.c.

bpo-33391 [https://bugs.python.org/issue?@action=redirect&bpo=33391]: Fix a leak in set_symmetric_difference().

bpo-28055 [https://bugs.python.org/issue?@action=redirect&bpo=28055]: Fix unaligned accesses in siphash24(). Patch by Rolf Eike Beer.

bpo-33231 [https://bugs.python.org/issue?@action=redirect&bpo=33231]: Fix potential memory leak in normalizestring().

bpo-29922 [https://bugs.python.org/issue?@action=redirect&bpo=29922]: Improved error messages in “async with” when __aenter__() or __aexit__() return non-awaitable object.

bpo-33199 [https://bugs.python.org/issue?@action=redirect&bpo=33199]: Fix ma_version_tag in dict implementation is uninitialized when copying from key-sharing dict.

bpo-33041 [https://bugs.python.org/issue?@action=redirect&bpo=33041]: Fixed jumping when the function contains an async for loop.

bpo-32282 [https://bugs.python.org/issue?@action=redirect&bpo=32282]: Fix an unnecessary ifdef in the include of VersionHelpers.h in socketmodule on Windows.

bpo-21983 [https://bugs.python.org/issue?@action=redirect&bpo=21983]: Fix a crash in ctypes.cast() in case the type argument is a ctypes structured data type. Patch by Eryk Sun and Oren Milman.

Library

bpo-30167 [https://bugs.python.org/issue?@action=redirect&bpo=30167]: Prevent site.main() exception if PYTHONSTARTUP is set. Patch by Steve Weber.

bpo-33812 [https://bugs.python.org/issue?@action=redirect&bpo=33812]: Datetime instance d with non-None tzinfo, but with d.tzinfo.utcoffset(d) returning None is now treated as naive by the astimezone() method.

bpo-30805 [https://bugs.python.org/issue?@action=redirect&bpo=30805]: Avoid race condition with debug logging

bpo-33767 [https://bugs.python.org/issue?@action=redirect&bpo=33767]: The concatenation (+) and repetition (*) sequence operations now raise TypeError instead of SystemError when performed on mmap.mmap objects. Patch by Zackery Spytz.

bpo-32684 [https://bugs.python.org/issue?@action=redirect&bpo=32684]: Fix gather to propagate cancellation of itself even with return_exceptions.

bpo-33674 [https://bugs.python.org/issue?@action=redirect&bpo=33674]: Fix a race condition in SSLProtocol.connection_made() of asyncio.sslproto: start immediately the handshake instead of using call_soon(). Previously, data_received() could be called before the handshake started, causing the handshake to hang or fail.

bpo-31647 [https://bugs.python.org/issue?@action=redirect&bpo=31647]: Fixed bug where calling write_eof() on a _SelectorSocketTransport after it’s already closed raises AttributeError.

bpo-33672 [https://bugs.python.org/issue?@action=redirect&bpo=33672]: Fix Task.__repr__ crash with Cython’s bogus coroutines

bpo-33469 [https://bugs.python.org/issue?@action=redirect&bpo=33469]: Fix RuntimeError after closing loop that used run_in_executor

bpo-11874 [https://bugs.python.org/issue?@action=redirect&bpo=11874]: Use a better regex when breaking usage into wrappable parts. Avoids bogus assertion errors from custom metavar strings.

bpo-30877 [https://bugs.python.org/issue?@action=redirect&bpo=30877]: Fixed a bug in the Python implementation of the JSON decoder that prevented the cache of parsed strings from clearing after finishing the decoding. Based on patch by c-fos.

bpo-33548 [https://bugs.python.org/issue?@action=redirect&bpo=33548]: tempfile._candidate_tempdir_list should consider common TEMP locations

bpo-33542 [https://bugs.python.org/issue?@action=redirect&bpo=33542]: Prevent uuid.get_node from using a DUID instead of a MAC on Windows. Patch by Zvi Effron

bpo-26819 [https://bugs.python.org/issue?@action=redirect&bpo=26819]: Fix race condition with ReadTransport.resume_reading in Windows proactor event loop.

bpo-28556 [https://bugs.python.org/issue?@action=redirect&bpo=28556]: Minor fixes in typing module: add annotations to NamedTuple.__new__, pass *args and **kwds in Generic.__new__. Original PRs by Paulius Šarka and Chad Dombrova.

bpo-20087 [https://bugs.python.org/issue?@action=redirect&bpo=20087]: Updated alias mapping with glibc 2.27 supported locales.

bpo-33422 [https://bugs.python.org/issue?@action=redirect&bpo=33422]: Fix trailing quotation marks getting deleted when looking up byte/string literals on pydoc. Patch by Andrés Delfino.

bpo-33197 [https://bugs.python.org/issue?@action=redirect&bpo=33197]: Update error message when constructing invalid inspect.Parameters Patch by Dong-hee Na.

bpo-33383 [https://bugs.python.org/issue?@action=redirect&bpo=33383]: Fixed crash in the get() method of the dbm.ndbm database object when it is called with a single argument.

bpo-33329 [https://bugs.python.org/issue?@action=redirect&bpo=33329]: Fix multiprocessing regression on newer glibcs

bpo-991266 [https://bugs.python.org/issue?@action=redirect&bpo=991266]: Fix quoting of the Comment attribute of http.cookies.SimpleCookie.

bpo-33131 [https://bugs.python.org/issue?@action=redirect&bpo=33131]: Upgrade bundled version of pip to 10.0.1.

bpo-33308 [https://bugs.python.org/issue?@action=redirect&bpo=33308]: Fixed a crash in the parser module when converting an ST object to a tree of tuples or lists with line_info=False and col_info=True.

bpo-33263 [https://bugs.python.org/issue?@action=redirect&bpo=33263]: Fix FD leak in _SelectorSocketTransport Patch by Vlad Starostin.

bpo-33256 [https://bugs.python.org/issue?@action=redirect&bpo=33256]: Fix display of <module> call in the html produced by cgitb.html(). Patch by Stéphane Blondon.

bpo-33203 [https://bugs.python.org/issue?@action=redirect&bpo=33203]: random.Random.choice() now raises IndexError for empty sequences consistently even when called from subclasses without a getrandbits() implementation.

bpo-33224 [https://bugs.python.org/issue?@action=redirect&bpo=33224]: Update difflib.mdiff() for PEP 479 [https://www.python.org/dev/peps/pep-0479]. Convert an uncaught StopIteration in a generator into a return-statement.

bpo-33209 [https://bugs.python.org/issue?@action=redirect&bpo=33209]: End framing at the end of C implementation of pickle.Pickler.dump().

bpo-32861 [https://bugs.python.org/issue?@action=redirect&bpo=32861]: The urllib.robotparser’s __str__ representation now includes wildcard entries and the «Crawl-delay» and «Request-rate» fields. Patch by Michael Lazar.

bpo-33096 [https://bugs.python.org/issue?@action=redirect&bpo=33096]: Allow ttk.Treeview.insert to insert iid that has a false boolean value. Note iid=0 and iid=False would be same. Patch by Garvit Khatri.

bpo-33127 [https://bugs.python.org/issue?@action=redirect&bpo=33127]: The ssl module now compiles with LibreSSL 2.7.1.

bpo-33021 [https://bugs.python.org/issue?@action=redirect&bpo=33021]: Release the GIL during fstat() calls, avoiding hang of all threads when calling mmap.mmap(), os.urandom(), and random.seed(). Patch by Nir Soffer.

bpo-27683 [https://bugs.python.org/issue?@action=redirect&bpo=27683]: Fix a regression in ipaddress that result of hosts() is empty when the network is constructed by a tuple containing an integer mask and only 1 bit left for addresses.

bpo-32844 [https://bugs.python.org/issue?@action=redirect&bpo=32844]: Fix wrong redirection of a low descriptor (0 or 1) to stderr in subprocess if another low descriptor is closed.

bpo-31908 [https://bugs.python.org/issue?@action=redirect&bpo=31908]: Fix output of cover files for trace module command-line tool. Previously emitted cover files only when --missing option was used. Patch by Michael Selik.

bpo-31457 [https://bugs.python.org/issue?@action=redirect&bpo=31457]: If nested log adapters are used, the inner process() methods are no longer omitted.

bpo-16865 [https://bugs.python.org/issue?@action=redirect&bpo=16865]: Support arrays >=2GiB in ctypes. Patch by Segev Finer.

bpo-31238 [https://bugs.python.org/issue?@action=redirect&bpo=31238]: pydoc: the stop() method of the private ServerThread class now waits until DocServer.serve_until_quit() completes and then explicitly sets its docserver attribute to None to break a reference cycle.

Documentation

bpo-33503 [https://bugs.python.org/issue?@action=redirect&bpo=33503]: Fix broken pypi link

bpo-33421 [https://bugs.python.org/issue?@action=redirect&bpo=33421]: Add missing documentation for typing.AsyncContextManager.

bpo-33378 [https://bugs.python.org/issue?@action=redirect&bpo=33378]: Add Korean language switcher for https://docs.python.org/3/

bpo-33276 [https://bugs.python.org/issue?@action=redirect&bpo=33276]: Clarify that the __path__ attribute on modules cannot be just any value.

bpo-33201 [https://bugs.python.org/issue?@action=redirect&bpo=33201]: Modernize documentation for writing C extension types.

bpo-33195 [https://bugs.python.org/issue?@action=redirect&bpo=33195]: Deprecate Py_UNICODE usage in c-api/arg document. Py_UNICODE related APIs are deprecated since Python 3.3, but it is missed in the document.

bpo-33126 [https://bugs.python.org/issue?@action=redirect&bpo=33126]: Document PyBuffer_ToContiguous().

bpo-27212 [https://bugs.python.org/issue?@action=redirect&bpo=27212]: Modify documentation for the islice() recipe to consume initial values up to the start index.

bpo-28247 [https://bugs.python.org/issue?@action=redirect&bpo=28247]: Update zipapp documentation to describe how to make standalone applications.

bpo-18802 [https://bugs.python.org/issue?@action=redirect&bpo=18802]: Documentation changes for ipaddress. Patch by Jon Foster and Berker Peksag.

bpo-27428 [https://bugs.python.org/issue?@action=redirect&bpo=27428]: Update documentation to clarify that WindowsRegistryFinder implements MetaPathFinder. (Patch by Himanshu Lakhara)

bpo-8243 [https://bugs.python.org/issue?@action=redirect&bpo=8243]: Add a note about curses.addch and curses.addstr exception behavior when writing outside a window, or pad.

bpo-31432 [https://bugs.python.org/issue?@action=redirect&bpo=31432]: Clarify meaning of CERT_NONE, CERT_OPTIONAL, and CERT_REQUIRED flags for ssl.SSLContext.verify_mode.

Tests

bpo-33655 [https://bugs.python.org/issue?@action=redirect&bpo=33655]: Ignore test_posix_fallocate failures on BSD platforms that might be due to running on ZFS.

bpo-19417 [https://bugs.python.org/issue?@action=redirect&bpo=19417]: Add test_bdb.py.

Build

bpo-5755 [https://bugs.python.org/issue?@action=redirect&bpo=5755]: Move -Wstrict-prototypes option to CFLAGS_NODIST from OPT. This option emitted annoying warnings when building extension modules written in C++.

bpo-33614 [https://bugs.python.org/issue?@action=redirect&bpo=33614]: Ensures module definition files for the stable ABI on Windows are correctly regenerated.

bpo-33522 [https://bugs.python.org/issue?@action=redirect&bpo=33522]: Enable CI builds on Visual Studio Team Services at https://python.visualstudio.com/cpython

bpo-33012 [https://bugs.python.org/issue?@action=redirect&bpo=33012]: Add -Wno-cast-function-type for gcc 8 for silencing warnings about function casts like casting to PyCFunction in method definition lists.

bpo-33394 [https://bugs.python.org/issue?@action=redirect&bpo=33394]: Enable the verbose build for extension modules, when GNU make is passed macros on the command line.

Windows

bpo-33184 [https://bugs.python.org/issue?@action=redirect&bpo=33184]: Update Windows installer to OpenSSL 1.0.2o.

macOS

bpo-33184 [https://bugs.python.org/issue?@action=redirect&bpo=33184]: Update macOS installer build to use OpenSSL 1.0.2o.

IDLE

bpo-33656 [https://bugs.python.org/issue?@action=redirect&bpo=33656]: On Windows, add API call saying that tk scales for DPI. On Windows 8.1+ or 10, with DPI compatibility properties of the Python binary unchanged, and a monitor resolution greater than 96 DPI, this should make text and lines sharper. It should otherwise have no effect.

bpo-33768 [https://bugs.python.org/issue?@action=redirect&bpo=33768]: Clicking on a context line moves that line to the top of the editor window.

bpo-33763 [https://bugs.python.org/issue?@action=redirect&bpo=33763]: IDLE: Use read-only text widget for code context instead of label widget.

bpo-33664 [https://bugs.python.org/issue?@action=redirect&bpo=33664]: Scroll IDLE editor text by lines. Previously, the mouse wheel and scrollbar slider moved text by a fixed number of pixels, resulting in partial lines at the top of the editor box. The change also applies to the shell and grep output windows, but not to read-only text views.

bpo-33679 [https://bugs.python.org/issue?@action=redirect&bpo=33679]: Enable theme-specific color configuration for Code Context. Use the Highlights tab to see the setting for built-in themes or add settings to custom themes.

bpo-33642 [https://bugs.python.org/issue?@action=redirect&bpo=33642]: Display up to maxlines non-blank lines for Code Context. If there is no current context, show a single blank line.

bpo-33628 [https://bugs.python.org/issue?@action=redirect&bpo=33628]: IDLE: Cleanup codecontext.py and its test.

bpo-33564 [https://bugs.python.org/issue?@action=redirect&bpo=33564]: IDLE’s code context now recognizes async as a block opener.

bpo-29706 [https://bugs.python.org/issue?@action=redirect&bpo=29706]: IDLE now colors async and await as keywords in 3.6. They become full keywords in 3.7.

bpo-21474 [https://bugs.python.org/issue?@action=redirect&bpo=21474]: Update word/identifier definition from ascii to unicode. In text and entry boxes, this affects selection by double-click, movement left/right by control-left/right, and deletion left/right by control-BACKSPACE/DEL.

bpo-33204 [https://bugs.python.org/issue?@action=redirect&bpo=33204]: IDLE: consistently color invalid string prefixes. A “u” string prefix cannot be paired with either “r” or “f”. Consistently color as much of the prefix, starting at the right, as is valid. Revise and extend colorizer test.

bpo-32831 [https://bugs.python.org/issue?@action=redirect&bpo=32831]: Add docstrings and tests for codecontext.

Tools/Demos

bpo-33189 [https://bugs.python.org/issue?@action=redirect&bpo=33189]: pygettext.py now recognizes only literal strings as docstrings and translatable strings, and rejects bytes literals and f-string expressions.

bpo-31920 [https://bugs.python.org/issue?@action=redirect&bpo=31920]: Fixed handling directories as arguments in the pygettext script. Based on patch by Oleg Krasnikov.

bpo-29673 [https://bugs.python.org/issue?@action=redirect&bpo=29673]: Fix pystackv and pystack gdbinit macros.

bpo-32885 [https://bugs.python.org/issue?@action=redirect&bpo=32885]: Add an -n flag for Tools/scripts/pathfix.py to disable automatic backup creation (files with ~ suffix).

bpo-31583 [https://bugs.python.org/issue?@action=redirect&bpo=31583]: Fix 2to3 for using with –add-suffix option but without –output-dir option for relative path to files in current directory.

C API

bpo-32374 [https://bugs.python.org/issue?@action=redirect&bpo=32374]: Document that m_traverse for multi-phase initialized modules can be called with m_state=NULL, and add a sanity check

Python 3.6.5 final

Release date: 2018-03-28

Tests

bpo-32872 [https://bugs.python.org/issue?@action=redirect&bpo=32872]: Avoid regrtest compatibility issue with namespace packages.

Build

bpo-33163 [https://bugs.python.org/issue?@action=redirect&bpo=33163]: Upgrade pip to 9.0.3 and setuptools to v39.0.1.

Python 3.6.5 release candidate 1

Release date: 2018-03-13

Security

bpo-33001 [https://bugs.python.org/issue?@action=redirect&bpo=33001]: Minimal fix to prevent buffer overrun in os.symlink on Windows

bpo-32981 [https://bugs.python.org/issue?@action=redirect&bpo=32981]: Regexes in difflib and poplib were vulnerable to catastrophic backtracking. These regexes formed potential DOS vectors (REDOS). They have been refactored. This resolves CVE-2018-1060 and CVE-2018-1061. Patch by Jamie Davis.

Core and Builtins

bpo-33026 [https://bugs.python.org/issue?@action=redirect&bpo=33026]: Fixed jumping out of «with» block by setting f_lineno.

bpo-17288 [https://bugs.python.org/issue?@action=redirect&bpo=17288]: Prevent jumps from “return” and “exception” trace events.

bpo-32889 [https://bugs.python.org/issue?@action=redirect&bpo=32889]: Update Valgrind suppression list to account for the rename of Py_ADDRESS_IN_RANG to address_in_range.

bpo-32650 [https://bugs.python.org/issue?@action=redirect&bpo=32650]: Pdb and other debuggers dependent on bdb.py will correctly step over (next command) native coroutines. Patch by Pablo Galindo.

bpo-32685 [https://bugs.python.org/issue?@action=redirect&bpo=32685]: Improve suggestion when the Python 2 form of print statement is either present on the same line as the header of a compound statement or else terminated by a semi-colon instead of a newline. Patch by Nitish Chandra.

bpo-32583 [https://bugs.python.org/issue?@action=redirect&bpo=32583]: Fix possible crashing in builtin Unicode decoders caused by write out-of-bound errors when using customized decode error handlers.

bpo-26163 [https://bugs.python.org/issue?@action=redirect&bpo=26163]: Improved frozenset() hash to create more distinct hash values when faced with datasets containing many similar values.

bpo-27169 [https://bugs.python.org/issue?@action=redirect&bpo=27169]: The __debug__ constant is now optimized out at compile time. This fixes also bpo-22091 [https://bugs.python.org/issue?@action=redirect&bpo=22091].

bpo-32329 [https://bugs.python.org/issue?@action=redirect&bpo=32329]: sys.flags.hash_randomization is now properly set to 0 when hash randomization is turned off by PYTHONHASHSEED=0.

bpo-30416 [https://bugs.python.org/issue?@action=redirect&bpo=30416]: The optimizer is now protected from spending much time doing complex calculations and consuming much memory for creating large constants in constant folding.

bpo-18533 [https://bugs.python.org/issue?@action=redirect&bpo=18533]: repr() on a dict containing its own values() or items() no longer raises RecursionError; OrderedDict similarly. Instead, use ..., as for other recursive structures. Patch by Ben North.

bpo-32028 [https://bugs.python.org/issue?@action=redirect&bpo=32028]: Leading whitespace is now correctly ignored when generating suggestions for converting Py2 print statements to Py3 builtin print function calls. Patch by Sanyam Khurana.

bpo-32137 [https://bugs.python.org/issue?@action=redirect&bpo=32137]: The repr of deeply nested dict now raises a RecursionError instead of crashing due to a stack overflow.

Library

bpo-33064 [https://bugs.python.org/issue?@action=redirect&bpo=33064]: lib2to3 now properly supports trailing commas after *args and **kwargs in function signatures.

bpo-31804 [https://bugs.python.org/issue?@action=redirect&bpo=31804]: Avoid failing in multiprocessing.Process if the standard streams are closed or None at exit.

bpo-33037 [https://bugs.python.org/issue?@action=redirect&bpo=33037]: Skip sending/receiving data after SSL transport closing.

bpo-30353 [https://bugs.python.org/issue?@action=redirect&bpo=30353]: Fix ctypes pass-by-value for structs on 64-bit Cygwin/MinGW.

bpo-33009 [https://bugs.python.org/issue?@action=redirect&bpo=33009]: Fix inspect.signature() for single-parameter partialmethods.

bpo-32969 [https://bugs.python.org/issue?@action=redirect&bpo=32969]: Expose several missing constants in zlib and fix corresponding documentation.

bpo-32713 [https://bugs.python.org/issue?@action=redirect&bpo=32713]: Fixed tarfile.itn handling of out-of-bounds float values. Patch by Joffrey Fuhrer.

bpo-30622 [https://bugs.python.org/issue?@action=redirect&bpo=30622]: The ssl module now detects missing NPN support in LibreSSL.

bpo-32922 [https://bugs.python.org/issue?@action=redirect&bpo=32922]: dbm.open() now encodes filename with the filesystem encoding rather than default encoding.

bpo-32859 [https://bugs.python.org/issue?@action=redirect&bpo=32859]: In os.dup2, don’t check every call whether the dup3 syscall exists or not.

bpo-21060 [https://bugs.python.org/issue?@action=redirect&bpo=21060]: Rewrite confusing message from setup.py upload from «No dist file created in earlier command» to the more helpful «Must create and upload files in one command».

bpo-32857 [https://bugs.python.org/issue?@action=redirect&bpo=32857]: In tkinter, after_cancel(None) now raises a ValueError instead of canceling the first scheduled function. Patch by Cheryl Sabella.

bpo-32852 [https://bugs.python.org/issue?@action=redirect&bpo=32852]: Make sure sys.argv remains as a list when running trace.

bpo-32841 [https://bugs.python.org/issue?@action=redirect&bpo=32841]: Fixed asyncio.Condition issue which silently ignored cancellation after notifying and cancelling a conditional lock. Patch by Bar Harel.

bpo-31787 [https://bugs.python.org/issue?@action=redirect&bpo=31787]: Fixed refleaks of __init__() methods in various modules. (Contributed by Oren Milman)

bpo-30157 [https://bugs.python.org/issue?@action=redirect&bpo=30157]: Fixed guessing quote and delimiter in csv.Sniffer.sniff() when only the last field is quoted. Patch by Jake Davis.

bpo-32394 [https://bugs.python.org/issue?@action=redirect&bpo=32394]: socket: Remove TCP_FASTOPEN, TCP_KEEPCNT flags on older version Windows during run-time.

bpo-32777 [https://bugs.python.org/issue?@action=redirect&bpo=32777]: Fix a rare but potential pre-exec child process deadlock in subprocess on POSIX systems when marking file descriptors inheritable on exec in the child process. This bug appears to have been introduced in 3.4.

bpo-32647 [https://bugs.python.org/issue?@action=redirect&bpo=32647]: The ctypes module used to depend on indirect linking for dlopen. The shared extension is now explicitly linked against libdl on platforms with dl.

bpo-32734 [https://bugs.python.org/issue?@action=redirect&bpo=32734]: Fixed asyncio.Lock() safety issue which allowed acquiring and locking the same lock multiple times, without it being free. Patch by Bar Harel.

bpo-32727 [https://bugs.python.org/issue?@action=redirect&bpo=32727]: Do not include name field in SMTP envelope from address. Patch by Stéphane Wirtel

bpo-27931 [https://bugs.python.org/issue?@action=redirect&bpo=27931]: Fix email address header parsing error when the username is an empty quoted string. Patch by Xiang Zhang.

bpo-32304 [https://bugs.python.org/issue?@action=redirect&bpo=32304]: distutils” upload command no longer corrupts tar files ending with a CR byte, and no longer tries to convert CR to CRLF in any of the upload text fields.

bpo-32502 [https://bugs.python.org/issue?@action=redirect&bpo=32502]: uuid.uuid1 no longer raises an exception if a 64-bit hardware address is encountered.

bpo-31848 [https://bugs.python.org/issue?@action=redirect&bpo=31848]: Fix the error handling in Aifc_read.initfp() when the SSND chunk is not found. Patch by Zackery Spytz.

bpo-32555 [https://bugs.python.org/issue?@action=redirect&bpo=32555]: On FreeBSD and Solaris, os.strerror() now always decode the byte string from the current locale encoding, rather than using ASCII/surrogateescape in some cases.

bpo-32521 [https://bugs.python.org/issue?@action=redirect&bpo=32521]: The nis module is now compatible with new libnsl and headers location.

bpo-32473 [https://bugs.python.org/issue?@action=redirect&bpo=32473]: Improve ABCMeta._dump_registry() output readability

bpo-32521 [https://bugs.python.org/issue?@action=redirect&bpo=32521]: glibc has removed Sun RPC. Use replacement libtirpc headers and library in nis module.

bpo-32228 [https://bugs.python.org/issue?@action=redirect&bpo=32228]: Ensure that truncate() preserves the file position (as reported by tell()) after writes longer than the buffer size.

bpo-26133 [https://bugs.python.org/issue?@action=redirect&bpo=26133]: Don’t unsubscribe signals in asyncio UNIX event loop on interpreter shutdown.

bpo-32185 [https://bugs.python.org/issue?@action=redirect&bpo=32185]: The SSL module no longer sends IP addresses in SNI TLS extension on platforms with OpenSSL 1.0.2+ or inet_pton.

bpo-32323 [https://bugs.python.org/issue?@action=redirect&bpo=32323]: urllib.parse.urlsplit() does not convert zone-id (scope) to lower case for scoped IPv6 addresses in hostnames now.

bpo-32302 [https://bugs.python.org/issue?@action=redirect&bpo=32302]: Fix bdist_wininst of distutils for CRT v142: it binary compatible with CRT v140.

bpo-32255 [https://bugs.python.org/issue?@action=redirect&bpo=32255]: A single empty field is now always quoted when written into a CSV file. This allows to distinguish an empty row from a row consisting of a single empty field. Patch by Licht Takeuchi.

bpo-32277 [https://bugs.python.org/issue?@action=redirect&bpo=32277]: Raise NotImplementedError instead of SystemError on platforms where chmod(..., follow_symlinks=False) is not supported. Patch by Anthony Sottile.

bpo-32199 [https://bugs.python.org/issue?@action=redirect&bpo=32199]: The getnode() ip getter now uses “ip link” instead of “ip link list”.

bpo-27456 [https://bugs.python.org/issue?@action=redirect&bpo=27456]: Ensure TCP_NODELAY is set on Linux. Tests by Victor Stinner.

bpo-31900 [https://bugs.python.org/issue?@action=redirect&bpo=31900]: The locale.localeconv() function now sets temporarily the LC_CTYPE locale to the LC_NUMERIC locale to decode decimal_point and thousands_sep byte strings if they are non-ASCII or longer than 1 byte, and the LC_NUMERIC locale is different than the LC_CTYPE locale. This temporary change affects other threads. Same change for the str.format() method when formatting a number (int, float, float and subclasses) with the n type (ex: '{:n}'.format(1234)).

bpo-31802 [https://bugs.python.org/issue?@action=redirect&bpo=31802]: Importing native path module (posixpath, ntpath) now works even if the os module still is not imported.

Documentation

bpo-17232 [https://bugs.python.org/issue?@action=redirect&bpo=17232]: Clarify docs for -O and -OO. Patch by Terry Reedy.

bpo-32800 [https://bugs.python.org/issue?@action=redirect&bpo=32800]: Update link to w3c doc for xml default namespaces.

bpo-8722 [https://bugs.python.org/issue?@action=redirect&bpo=8722]: Document __getattr__() behavior when property get() method raises AttributeError.

bpo-32614 [https://bugs.python.org/issue?@action=redirect&bpo=32614]: Modify RE examples in documentation to use raw strings to prevent DeprecationWarning and add text to REGEX HOWTO to highlight the deprecation.

bpo-31972 [https://bugs.python.org/issue?@action=redirect&bpo=31972]: Improve docstrings for pathlib.PurePath subclasses.

bpo-17799 [https://bugs.python.org/issue?@action=redirect&bpo=17799]: Explain real behaviour of sys.settrace and sys.setprofile and their C-API counterparts regarding which type of events are received in each function. Patch by Pablo Galindo Salgado.

Tests

bpo-32517 [https://bugs.python.org/issue?@action=redirect&bpo=32517]: Fix failing test_asyncio on macOS 10.12.2+ due to transport of KqueueSelector loop was not being closed.

bpo-32721 [https://bugs.python.org/issue?@action=redirect&bpo=32721]: Fix test_hashlib to not fail if the _md5 module is not built.

bpo-32252 [https://bugs.python.org/issue?@action=redirect&bpo=32252]: Fix faulthandler_suppress_crash_report() used to prevent core dump files when testing crashes. getrlimit() returns zero on success.

bpo-31518 [https://bugs.python.org/issue?@action=redirect&bpo=31518]: Debian Unstable has disabled TLS 1.0 and 1.1 for SSLv23_METHOD(). Change TLS/SSL protocol of some tests to PROTOCOL_TLS or PROTOCOL_TLSv1_2 to make them pass on Debian.

Build

bpo-32635 [https://bugs.python.org/issue?@action=redirect&bpo=32635]: Fix segfault of the crypt module when libxcrypt is provided instead of libcrypt at the system.

Windows

bpo-33016 [https://bugs.python.org/issue?@action=redirect&bpo=33016]: Fix potential use of uninitialized memory in nt._getfinalpathname

bpo-32903 [https://bugs.python.org/issue?@action=redirect&bpo=32903]: Fix a memory leak in os.chdir() on Windows if the current directory is set to a UNC path.

bpo-31966 [https://bugs.python.org/issue?@action=redirect&bpo=31966]: Fixed WindowsConsoleIO.write() for writing empty data.

bpo-32409 [https://bugs.python.org/issue?@action=redirect&bpo=32409]: Ensures activate.bat can handle Unicode contents.

bpo-32457 [https://bugs.python.org/issue?@action=redirect&bpo=32457]: Improves handling of denormalized executable path when launching Python.

bpo-32370 [https://bugs.python.org/issue?@action=redirect&bpo=32370]: Use the correct encoding for ipconfig output in the uuid module. Patch by Segev Finer.

bpo-29248 [https://bugs.python.org/issue?@action=redirect&bpo=29248]: Fix os.readlink() on Windows, which was mistakenly treating the PrintNameOffset field of the reparse data buffer as a number of characters instead of bytes. Patch by Craig Holmquist and SSE4.

bpo-32588 [https://bugs.python.org/issue?@action=redirect&bpo=32588]: Create standalone _distutils_findvs module.

macOS

bpo-32726 [https://bugs.python.org/issue?@action=redirect&bpo=32726]: Provide an additional, more modern macOS installer variant that supports macOS 10.9+ systems in 64-bit mode only. Upgrade the supplied third-party libraries to OpenSSL 1.0.2n, XZ 5.2.3, and SQLite 3.22.0. The 10.9+ installer now links with and supplies its own copy of Tcl/Tk 8.6.8.

IDLE

bpo-32984 [https://bugs.python.org/issue?@action=redirect&bpo=32984]: Set __file__ while running a startup file. Like Python, IDLE optionally runs one startup file in the Shell window before presenting the first interactive input prompt. For IDLE, -s runs a file named in environmental variable IDLESTARTUP or PYTHONSTARTUP; -r file runs file. Python sets __file__ to the startup file name before running the file and unsets it before the first prompt. IDLE now does the same when run normally, without the -n option.

bpo-32940 [https://bugs.python.org/issue?@action=redirect&bpo=32940]: Simplify and rename StringTranslatePseudoMapping in pyparse.

bpo-32916 [https://bugs.python.org/issue?@action=redirect&bpo=32916]: Change str to code in pyparse.

bpo-32905 [https://bugs.python.org/issue?@action=redirect&bpo=32905]: Remove unused code in pyparse module.

bpo-32874 [https://bugs.python.org/issue?@action=redirect&bpo=32874]: Add tests for pyparse.

bpo-32837 [https://bugs.python.org/issue?@action=redirect&bpo=32837]: Using the system and place-dependent default encoding for open() is a bad idea for IDLE’s system and location-independent files.

bpo-32826 [https://bugs.python.org/issue?@action=redirect&bpo=32826]: Add «encoding=utf-8» to open() in IDLE’s test_help_about. GUI test test_file_buttons() only looks at initial ascii-only lines, but failed on systems where open() defaults to “ascii” because readline() internally reads and decodes far enough ahead to encounter a non-ascii character in CREDITS.txt.

bpo-32765 [https://bugs.python.org/issue?@action=redirect&bpo=32765]: Update configdialog General tab docstring to add new widgets to the widget list.

Tools/Demos

bpo-24960 [https://bugs.python.org/issue?@action=redirect&bpo=24960]: 2to3 and lib2to3 can now read pickled grammar files using pkgutil.get_data() rather than probing the filesystem. This lets 2to3 and lib2to3 work when run from a zipfile.

bpo-32222 [https://bugs.python.org/issue?@action=redirect&bpo=32222]: Fix pygettext not extracting docstrings for functions with type annotated arguments. Patch by Toby Harradine.

C API

bpo-29084 [https://bugs.python.org/issue?@action=redirect&bpo=29084]: Undocumented C API for OrderedDict has been excluded from the limited C API. It was added by mistake and actually never worked in the limited C API.

Python 3.6.4 final

Release date: 2017-12-18

There were no new code changes in version 3.6.4 since v3.6.4rc1.

Python 3.6.4 release candidate 1

Release date: 2017-12-05

Core and Builtins

bpo-32176 [https://bugs.python.org/issue?@action=redirect&bpo=32176]: co_flags.CO_NOFREE is now always set correctly by the code object constructor based on freevars and cellvars, rather than needing to be set correctly by the caller. This ensures it will be cleared automatically when additional cell references are injected into a modified code object and function.

bpo-31949 [https://bugs.python.org/issue?@action=redirect&bpo=31949]: Fixed several issues in printing tracebacks (PyTraceBack_Print()). Setting sys.tracebacklimit to 0 or less now suppresses printing tracebacks. Setting sys.tracebacklimit to None now causes using the default limit. Setting sys.tracebacklimit to an integer larger than LONG_MAX now means using the limit LONG_MAX rather than the default limit. Fixed integer overflows in the case of more than 2**31 traceback items on Windows. Fixed output errors handling.

bpo-30696 [https://bugs.python.org/issue?@action=redirect&bpo=30696]: Fix the interactive interpreter looping endlessly when no memory.

bpo-20047 [https://bugs.python.org/issue?@action=redirect&bpo=20047]: Bytearray methods partition() and rpartition() now accept only bytes-like objects as separator, as documented. In particular they now raise TypeError rather of returning a bogus result when an integer is passed as a separator.

bpo-31852 [https://bugs.python.org/issue?@action=redirect&bpo=31852]: Fix a segmentation fault caused by a combination of the async soft keyword and continuation lines.

bpo-21720 [https://bugs.python.org/issue?@action=redirect&bpo=21720]: BytesWarning no longer emitted when the fromlist argument of __import__() or the __all__ attribute of the module contain bytes instances.

bpo-31825 [https://bugs.python.org/issue?@action=redirect&bpo=31825]: Fixed OverflowError in the “unicode-escape” codec and in codecs.escape_decode() when decode an escaped non-ascii byte.

bpo-28603 [https://bugs.python.org/issue?@action=redirect&bpo=28603]: Print the full context/cause chain of exceptions on interpreter exit, even if an exception in the chain is unhashable or compares equal to later ones. Patch by Zane Bitter.

bpo-31786 [https://bugs.python.org/issue?@action=redirect&bpo=31786]: Fix timeout rounding in the select module to round correctly negative timeouts between -1.0 and 0.0. The functions now block waiting for events as expected. Previously, the call was incorrectly non-blocking. Patch by Pablo Galindo.

bpo-31642 [https://bugs.python.org/issue?@action=redirect&bpo=31642]: Restored blocking «from package import module» by setting sys.modules[«package.module»] to None.

bpo-31626 [https://bugs.python.org/issue?@action=redirect&bpo=31626]: Fixed a bug in debug memory allocator. There was a write to freed memory after shrinking a memory block.

bpo-31619 [https://bugs.python.org/issue?@action=redirect&bpo=31619]: Fixed a ValueError when convert a string with large number of underscores to integer with binary base.

bpo-31592 [https://bugs.python.org/issue?@action=redirect&bpo=31592]: Fixed an assertion failure in Python parser in case of a bad unicodedata.normalize(). Patch by Oren Milman.

bpo-31588 [https://bugs.python.org/issue?@action=redirect&bpo=31588]: Raise a TypeError with a helpful error message when class creation fails due to a metaclass with a bad __prepare__() method. Patch by Oren Milman.

bpo-31566 [https://bugs.python.org/issue?@action=redirect&bpo=31566]: Fix an assertion failure in _warnings.warn() in case of a bad __name__ global. Patch by Oren Milman.

bpo-31505 [https://bugs.python.org/issue?@action=redirect&bpo=31505]: Fix an assertion failure in json, in case _json.make_encoder() received a bad encoder() argument. Patch by Oren Milman.

bpo-31492 [https://bugs.python.org/issue?@action=redirect&bpo=31492]: Fix assertion failures in case of failing to import from a module with a bad __name__ attribute, and in case of failing to access an attribute of such a module. Patch by Oren Milman.

bpo-31490 [https://bugs.python.org/issue?@action=redirect&bpo=31490]: Fix an assertion failure in ctypes class definition, in case the class has an attribute whose name is specified in _anonymous_ but not in _fields_. Patch by Oren Milman.

bpo-31478 [https://bugs.python.org/issue?@action=redirect&bpo=31478]: Fix an assertion failure in _random.Random.seed() in case the argument has a bad __abs__() method. Patch by Oren Milman.

bpo-31315 [https://bugs.python.org/issue?@action=redirect&bpo=31315]: Fix an assertion failure in imp.create_dynamic(), when spec.name is not a string. Patch by Oren Milman.

bpo-31311 [https://bugs.python.org/issue?@action=redirect&bpo=31311]: Fix a crash in the __setstate__() method of ctypes._CData, in case of a bad __dict__. Patch by Oren Milman.

bpo-31293 [https://bugs.python.org/issue?@action=redirect&bpo=31293]: Fix crashes in true division and multiplication of a timedelta object by a float with a bad as_integer_ratio() method. Patch by Oren Milman.

bpo-31285 [https://bugs.python.org/issue?@action=redirect&bpo=31285]: Fix an assertion failure in warnings.warn_explicit, when the return value of the received loader’s get_source() has a bad splitlines() method. Patch by Oren Milman.

bpo-30817 [https://bugs.python.org/issue?@action=redirect&bpo=30817]: PyErr_PrintEx() clears now the ignored exception that may be raised by _PySys_SetObjectId(), for example when no memory.

Library

bpo-28556 [https://bugs.python.org/issue?@action=redirect&bpo=28556]: Two minor fixes for typing module: allow shallow copying instances of generic classes, improve interaction of __init_subclass__ with generics. Original PRs by Ivan Levkivskyi.

bpo-27240 [https://bugs.python.org/issue?@action=redirect&bpo=27240]: The header folding algorithm for the new email policies has been rewritten, which also fixes bpo-30788 [https://bugs.python.org/issue?@action=redirect&bpo=30788], bpo-31831 [https://bugs.python.org/issue?@action=redirect&bpo=31831], and bpo-32182 [https://bugs.python.org/issue?@action=redirect&bpo=32182]. In particular, RFC2231 folding is now done correctly.

bpo-32186 [https://bugs.python.org/issue?@action=redirect&bpo=32186]: io.FileIO.readall() and io.FileIO.read() now release the GIL when getting the file size. Fixed hang of all threads with inaccessible NFS server. Patch by Nir Soffer.

bpo-12239 [https://bugs.python.org/issue?@action=redirect&bpo=12239]: Make msilib.SummaryInformation.GetProperty() return None when the value of property is VT_EMPTY. Initial patch by Mark Mc Mahon.

bpo-31325 [https://bugs.python.org/issue?@action=redirect&bpo=31325]: Fix wrong usage of collections.namedtuple() in the RobotFileParser.parse() method. Initial patch by Robin Wellner.

bpo-12382 [https://bugs.python.org/issue?@action=redirect&bpo=12382]: msilib.OpenDatabase() now raises a better exception message when it couldn’t open or create an MSI file. Initial patch by William Tisäter.

bpo-32110 [https://bugs.python.org/issue?@action=redirect&bpo=32110]: codecs.StreamReader.read(n) now returns not more than n characters/bytes for non-negative n. This makes it compatible with read() methods of other file-like objects.

bpo-32072 [https://bugs.python.org/issue?@action=redirect&bpo=32072]: Fixed issues with binary plists: Fixed saving bytearrays. Identical objects will be saved only once. Equal references will be load as identical objects. Added support for saving and loading recursive data structures.

bpo-32034 [https://bugs.python.org/issue?@action=redirect&bpo=32034]: Make asyncio.IncompleteReadError and LimitOverrunError pickleable.

bpo-32015 [https://bugs.python.org/issue?@action=redirect&bpo=32015]: Fixed the looping of asyncio in the case of reconnection the socket during waiting async read/write from/to the socket.

bpo-32011 [https://bugs.python.org/issue?@action=redirect&bpo=32011]: Restored support of loading marshal files with the TYPE_INT64 code. These files can be produced in Python 2.7.

bpo-31970 [https://bugs.python.org/issue?@action=redirect&bpo=31970]: Reduce performance overhead of asyncio debug mode.

bpo-9678 [https://bugs.python.org/issue?@action=redirect&bpo=9678]: Fixed determining the MAC address in the uuid module: Using ifconfig on NetBSD and OpenBSD. Using arp on Linux, FreeBSD, NetBSD and OpenBSD. Based on patch by Takayuki Shimizukawa.

bpo-30057 [https://bugs.python.org/issue?@action=redirect&bpo=30057]: Fix potential missed signal in signal.signal().

bpo-31933 [https://bugs.python.org/issue?@action=redirect&bpo=31933]: Fix Blake2 params leaf_size and node_offset on big endian platforms. Patch by Jack O’Connor.

bpo-31927 [https://bugs.python.org/issue?@action=redirect&bpo=31927]: Fixed compilation of the socket module on NetBSD 8. Fixed assertion failure or reading arbitrary data when parse a AF_BLUETOOTH address on NetBSD and DragonFly BSD.

bpo-27666 [https://bugs.python.org/issue?@action=redirect&bpo=27666]: Fixed stack corruption in curses.box() and curses.ungetmouse() when the size of types chtype or mmask_t is less than the size of C long. curses.box() now accepts characters as arguments. Based on patch by Steve Fink.

bpo-31897 [https://bugs.python.org/issue?@action=redirect&bpo=31897]: plistlib now catches more errors when read binary plists and raises InvalidFileException instead of unexpected exceptions.

bpo-25720 [https://bugs.python.org/issue?@action=redirect&bpo=25720]: Fix the method for checking pad state of curses WINDOW. Patch by Masayuki Yamamoto.

bpo-31893 [https://bugs.python.org/issue?@action=redirect&bpo=31893]: Fixed the layout of the kqueue_event structure on OpenBSD and NetBSD. Fixed the comparison of the kqueue_event objects.

bpo-31891 [https://bugs.python.org/issue?@action=redirect&bpo=31891]: Fixed building the curses module on NetBSD.

bpo-28416 [https://bugs.python.org/issue?@action=redirect&bpo=28416]: Instances of pickle.Pickler subclass with the persistent_id() method and pickle.Unpickler subclass with the persistent_load() method no longer create reference cycles.

bpo-28326 [https://bugs.python.org/issue?@action=redirect&bpo=28326]: Fix multiprocessing.Process when stdout and/or stderr is closed or None.

bpo-31457 [https://bugs.python.org/issue?@action=redirect&bpo=31457]: If nested log adapters are used, the inner process() methods are no longer omitted.

bpo-31457 [https://bugs.python.org/issue?@action=redirect&bpo=31457]: The manager property on LoggerAdapter objects is now properly settable.

bpo-31806 [https://bugs.python.org/issue?@action=redirect&bpo=31806]: Fix timeout rounding in time.sleep(), threading.Lock.acquire() and socket.socket.settimeout() to round correctly negative timeouts between -1.0 and 0.0. The functions now block waiting for events as expected. Previously, the call was incorrectly non-blocking. Patch by Pablo Galindo.

bpo-28603 [https://bugs.python.org/issue?@action=redirect&bpo=28603]: traceback: Fix a TypeError that occurred during printing of exception tracebacks when either the current exception or an exception in its context/cause chain is unhashable. Patch by Zane Bitter.

bpo-30058 [https://bugs.python.org/issue?@action=redirect&bpo=30058]: Fixed buffer overflow in select.kqueue.control().

bpo-31770 [https://bugs.python.org/issue?@action=redirect&bpo=31770]: Prevent a crash when calling the __init__() method of a sqlite3.Cursor object more than once. Patch by Oren Milman.

bpo-31672 [https://bugs.python.org/issue?@action=redirect&bpo=31672]: idpattern in string.Template matched some non-ASCII characters. Now it uses -i regular expression local flag to avoid non-ASCII characters.

bpo-31764 [https://bugs.python.org/issue?@action=redirect&bpo=31764]: Prevent a crash in sqlite3.Cursor.close() in case the Cursor object is uninitialized. Patch by Oren Milman.

bpo-31752 [https://bugs.python.org/issue?@action=redirect&bpo=31752]: Fix possible crash in timedelta constructor called with custom integers.

bpo-31701 [https://bugs.python.org/issue?@action=redirect&bpo=31701]: On Windows, faulthandler.enable() now ignores MSC and COM exceptions.

bpo-31728 [https://bugs.python.org/issue?@action=redirect&bpo=31728]: Prevent crashes in _elementtree due to unsafe cleanup of Element.text and Element.tail. Patch by Oren Milman.

bpo-31620 [https://bugs.python.org/issue?@action=redirect&bpo=31620]: an empty asyncio.Queue now doesn’t leak memory when queue.get pollers timeout

bpo-31632 [https://bugs.python.org/issue?@action=redirect&bpo=31632]: Fix method set_protocol() of class _SSLProtocolTransport in asyncio module. This method was previously modifying a wrong reference to the protocol.

bpo-31675 [https://bugs.python.org/issue?@action=redirect&bpo=31675]: Fixed memory leaks in Tkinter’s methods splitlist() and split() when pass a string larger than 2 GiB.

bpo-31673 [https://bugs.python.org/issue?@action=redirect&bpo=31673]: Fixed typo in the name of Tkinter’s method adderrorinfo().

bpo-30806 [https://bugs.python.org/issue?@action=redirect&bpo=30806]: Fix the string representation of a netrc object.

bpo-15037 [https://bugs.python.org/issue?@action=redirect&bpo=15037]: Added a workaround for getkey() in curses for ncurses 5.7 and earlier.

bpo-25351 [https://bugs.python.org/issue?@action=redirect&bpo=25351]: Avoid venv activate failures with undefined variables

bpo-25532 [https://bugs.python.org/issue?@action=redirect&bpo=25532]: inspect.unwrap() will now only try to unwrap an object sys.getrecursionlimit() times, to protect against objects which create a new object on every attribute access.

bpo-30347 [https://bugs.python.org/issue?@action=redirect&bpo=30347]: Stop crashes when concurrently iterate over itertools.groupby() iterators.

bpo-31516 [https://bugs.python.org/issue?@action=redirect&bpo=31516]: threading.current_thread() should not return a dummy thread at shutdown.

bpo-31351 [https://bugs.python.org/issue?@action=redirect&bpo=31351]: python -m ensurepip now exits with non-zero exit code if pip bootstrapping has failed.

bpo-31482 [https://bugs.python.org/issue?@action=redirect&bpo=31482]: random.seed() now works with bytes in version=1

bpo-31334 [https://bugs.python.org/issue?@action=redirect&bpo=31334]: Fix poll.poll([timeout]) in the select module for arbitrary negative timeouts on all OSes where it can only be a non-negative integer or -1. Patch by Riccardo Coccioli.

bpo-31310 [https://bugs.python.org/issue?@action=redirect&bpo=31310]: multiprocessing’s semaphore tracker should be launched again if crashed.

bpo-31308 [https://bugs.python.org/issue?@action=redirect&bpo=31308]: Make multiprocessing’s forkserver process immune to Ctrl-C and other user interruptions. If it crashes, restart it when necessary.

Documentation

bpo-32105 [https://bugs.python.org/issue?@action=redirect&bpo=32105]: Added asyncio.BaseEventLoop.connect_accepted_socket versionadded marker.

bpo-31537 [https://bugs.python.org/issue?@action=redirect&bpo=31537]: Fix incorrect usage of get_history_length in readline documentation example code. Patch by Brad Smith.

bpo-30085 [https://bugs.python.org/issue?@action=redirect&bpo=30085]: The operator functions without double underscores are preferred for clarity. The one with underscores are only kept for back-compatibility.

Tests

bpo-31380 [https://bugs.python.org/issue?@action=redirect&bpo=31380]: Skip test_httpservers test_undecodable_file on macOS: fails on APFS.

bpo-31705 [https://bugs.python.org/issue?@action=redirect&bpo=31705]: Skip test_socket.test_sha256() on Linux kernel older than 4.5. The test fails with ENOKEY on kernel 3.10 (on ppc64le). A fix was merged into the kernel 4.5.

bpo-31174 [https://bugs.python.org/issue?@action=redirect&bpo=31174]: Fix test_tools.test_unparse: DirectoryTestCase now stores the names sample to always test the same files. It prevents false alarms when hunting reference leaks.

bpo-30695 [https://bugs.python.org/issue?@action=redirect&bpo=30695]: Add the set_nomemory(start, stop) and remove_mem_hooks() functions to the _testcapi module.

Build

bpo-32059 [https://bugs.python.org/issue?@action=redirect&bpo=32059]: detect_modules() in setup.py now also searches the sysroot paths when cross-compiling.

bpo-31957 [https://bugs.python.org/issue?@action=redirect&bpo=31957]: Fixes Windows SDK version detection when building for Windows.

bpo-31609 [https://bugs.python.org/issue?@action=redirect&bpo=31609]: Fixes quotes in PCbuild/clean.bat

bpo-31934 [https://bugs.python.org/issue?@action=redirect&bpo=31934]: Abort the build when building out of a not clean source tree.

bpo-31926 [https://bugs.python.org/issue?@action=redirect&bpo=31926]: Fixed Argument Clinic sometimes causing compilation errors when there was more than one function and/or method in a .c file with the same name.

bpo-28791 [https://bugs.python.org/issue?@action=redirect&bpo=28791]: Update Windows builds to use SQLite 3.21.0.

bpo-28791 [https://bugs.python.org/issue?@action=redirect&bpo=28791]: Update OS X installer to use SQLite 3.21.0.

bpo-22140 [https://bugs.python.org/issue?@action=redirect&bpo=22140]: Prevent double substitution of prefix in python-config.sh.

bpo-31536 [https://bugs.python.org/issue?@action=redirect&bpo=31536]: Avoid wholesale rebuild after make regen-all if nothing changed.

Windows

bpo-1102 [https://bugs.python.org/issue?@action=redirect&bpo=1102]: Return None when View.Fetch() returns ERROR_NO_MORE_ITEMS instead of raising MSIError. Initial patch by Anthony Tuininga.

bpo-31944 [https://bugs.python.org/issue?@action=redirect&bpo=31944]: Fixes Modify button in Apps and Features dialog.

macOS

bpo-31392 [https://bugs.python.org/issue?@action=redirect&bpo=31392]: Update macOS installer to use OpenSSL 1.0.2m

IDLE

bpo-32207 [https://bugs.python.org/issue?@action=redirect&bpo=32207]: Improve tk event exception tracebacks in IDLE. When tk event handling is driven by IDLE’s run loop, a confusing and distracting queue.EMPTY traceback context is no longer added to tk event exception tracebacks. The traceback is now the same as when event handling is driven by user code. Patch based on a suggestion by Serhiy Storchaka.

bpo-32164 [https://bugs.python.org/issue?@action=redirect&bpo=32164]: Delete unused file idlelib/tabbedpages.py. Use of TabbedPageSet in configdialog was replaced by ttk.Notebook.

bpo-32100 [https://bugs.python.org/issue?@action=redirect&bpo=32100]: IDLE: Fix old and new bugs in pathbrowser; improve tests. Patch mostly by Cheryl Sabella.

bpo-31858 [https://bugs.python.org/issue?@action=redirect&bpo=31858]: IDLE – Restrict shell prompt manipulation to the shell. Editor and output windows only see an empty last prompt line. This simplifies the code and fixes a minor bug when newline is inserted. Sys.ps1, if present, is read on Shell start-up, but is not set or changed.

bpo-31860 [https://bugs.python.org/issue?@action=redirect&bpo=31860]: The font sample in the IDLE configuration dialog is now editable. Changes persist while IDLE remains open

bpo-31836 [https://bugs.python.org/issue?@action=redirect&bpo=31836]: Test_code_module now passes if run after test_idle, which sets ps1. The code module uses sys.ps1 if present or sets it to “>>> “ if not. Test_code_module now properly tests both behaviors. Ditto for ps2.

bpo-28603 [https://bugs.python.org/issue?@action=redirect&bpo=28603]: Fix a TypeError that caused a shell restart when printing a traceback that includes an exception that is unhashable. Patch by Zane Bitter.

bpo-13802 [https://bugs.python.org/issue?@action=redirect&bpo=13802]: Use non-Latin characters in the IDLE’s Font settings sample. Even if one selects a font that defines a limited subset of the unicode Basic Multilingual Plane, tcl/tk will use other fonts that define a character. The expanded example give users of non-Latin characters a better idea of what they might see in IDLE’s shell and editors. To make room for the expanded sample, frames on the Font tab are re-arranged. The Font/Tabs help explains a bit about the additions.

bpo-31460 [https://bugs.python.org/issue?@action=redirect&bpo=31460]: Simplify the API of IDLE’s Module Browser. Passing a widget instead of an flist with a root widget opens the option of creating a browser frame that is only part of a window. Passing a full file name instead of pieces assumed to come from a .py file opens the possibility of browsing python files that do not end in .py.

bpo-31649 [https://bugs.python.org/issue?@action=redirect&bpo=31649]: IDLE - Make _htest, _utest parameters keyword only.

bpo-31559 [https://bugs.python.org/issue?@action=redirect&bpo=31559]: Remove test order dependence in idle_test.test_browser.

bpo-31459 [https://bugs.python.org/issue?@action=redirect&bpo=31459]: Rename IDLE’s module browser from Class Browser to Module Browser. The original module-level class and method browser became a module browser, with the addition of module-level functions, years ago. Nested classes and functions were added yesterday. For back-compatibility, the virtual event <<open-class-browser>>, which appears on the Keys tab of the Settings dialog, is not changed. Patch by Cheryl Sabella.

bpo-31500 [https://bugs.python.org/issue?@action=redirect&bpo=31500]: Default fonts now are scaled on HiDPI displays.

bpo-1612262 [https://bugs.python.org/issue?@action=redirect&bpo=1612262]: IDLE module browser now shows nested classes and functions. Original patches for code and tests by Guilherme Polo and Cheryl Sabella, respectively.

Tools/Demos

bpo-30722 [https://bugs.python.org/issue?@action=redirect&bpo=30722]: Make redemo work with Python 3.6 and newer versions. Also, remove the LOCALE option since it doesn’t work with string patterns in Python 3. Patch by Christoph Sarnowski.

C API

bpo-20891 [https://bugs.python.org/issue?@action=redirect&bpo=20891]: Fix PyGILState_Ensure(). When PyGILState_Ensure() is called in a non-Python thread before PyEval_InitThreads(), only call PyEval_InitThreads() after calling PyThreadState_New() to fix a crash.

bpo-31532 [https://bugs.python.org/issue?@action=redirect&bpo=31532]: Fix memory corruption due to allocator mix in getpath.c between Py_GetPath() and Py_SetPath()

bpo-30697 [https://bugs.python.org/issue?@action=redirect&bpo=30697]: The PyExc_RecursionErrorInst singleton is removed and PyErr_NormalizeException() does not use it anymore. This singleton is persistent and its members being never cleared may cause a segfault during finalization of the interpreter. See also bpo-22898 [https://bugs.python.org/issue?@action=redirect&bpo=22898].

Python 3.6.3 final

Release date: 2017-10-03

Library

bpo-31641 [https://bugs.python.org/issue?@action=redirect&bpo=31641]: Re-allow arbitrary iterables in concurrent.futures.as_completed(). Fixes regression in 3.6.3rc1.

Build

bpo-31662 [https://bugs.python.org/issue?@action=redirect&bpo=31662]: Fix typos in Windows uploadrelease.bat script. Fix Windows Doc build issues in Doc/make.bat.

bpo-31423 [https://bugs.python.org/issue?@action=redirect&bpo=31423]: Fix building the PDF documentation with newer versions of Sphinx.

Python 3.6.3 release candidate 1

Release date: 2017-09-18

Security

bpo-29781 [https://bugs.python.org/issue?@action=redirect&bpo=29781]: SSLObject.version() now correctly returns None when handshake over BIO has not been performed yet.

bpo-30947 [https://bugs.python.org/issue?@action=redirect&bpo=30947]: Upgrade libexpat embedded copy from version 2.2.1 to 2.2.3 to get security fixes.

Core and Builtins

bpo-31471 [https://bugs.python.org/issue?@action=redirect&bpo=31471]: Fix an assertion failure in subprocess.Popen() on Windows, in case the env argument has a bad keys() method. Patch by Oren Milman.

bpo-31418 [https://bugs.python.org/issue?@action=redirect&bpo=31418]: Fix an assertion failure in PyErr_WriteUnraisable() in case of an exception with a bad __module__ attribute. Patch by Oren Milman.

bpo-31416 [https://bugs.python.org/issue?@action=redirect&bpo=31416]: Fix assertion failures in case of a bad warnings.filters or warnings.defaultaction. Patch by Oren Milman.

bpo-31411 [https://bugs.python.org/issue?@action=redirect&bpo=31411]: Raise a TypeError instead of SystemError in case warnings.onceregistry is not a dictionary. Patch by Oren Milman.

bpo-31373 [https://bugs.python.org/issue?@action=redirect&bpo=31373]: Fix several possible instances of undefined behavior due to floating-point demotions.

bpo-30465 [https://bugs.python.org/issue?@action=redirect&bpo=30465]: Location information (lineno and col_offset) in f-strings is now (mostly) correct. This fixes tools like flake8 from showing warnings on the wrong line (typically the first line of the file).

bpo-31343 [https://bugs.python.org/issue?@action=redirect&bpo=31343]: Include sys/sysmacros.h for major(), minor(), and makedev(). GNU C libray plans to remove the functions from sys/types.h.

bpo-31291 [https://bugs.python.org/issue?@action=redirect&bpo=31291]: Fix an assertion failure in zipimport.zipimporter.get_data on Windows, when the return value of pathname.replace('/','\\') isn’t a string. Patch by Oren Milman.

bpo-31271 [https://bugs.python.org/issue?@action=redirect&bpo=31271]: Fix an assertion failure in the write() method of io.TextIOWrapper, when the encoder doesn’t return a bytes object. Patch by Oren Milman.

bpo-31243 [https://bugs.python.org/issue?@action=redirect&bpo=31243]: Fix a crash in some methods of io.TextIOWrapper, when the decoder’s state is invalid. Patch by Oren Milman.

bpo-30721 [https://bugs.python.org/issue?@action=redirect&bpo=30721]: print now shows correct usage hint for using Python 2 redirection syntax. Patch by Sanyam Khurana.

bpo-31070 [https://bugs.python.org/issue?@action=redirect&bpo=31070]: Fix a race condition in importlib _get_module_lock().

bpo-31095 [https://bugs.python.org/issue?@action=redirect&bpo=31095]: Fix potential crash during GC caused by tp_dealloc which doesn’t call PyObject_GC_UnTrack().

bpo-31071 [https://bugs.python.org/issue?@action=redirect&bpo=31071]: Avoid masking original TypeError in call with * unpacking when other arguments are passed.

bpo-30978 [https://bugs.python.org/issue?@action=redirect&bpo=30978]: str.format_map() now passes key lookup exceptions through. Previously any exception was replaced with a KeyError exception.

bpo-30808 [https://bugs.python.org/issue?@action=redirect&bpo=30808]: Use _Py_atomic API for concurrency-sensitive signal state.

bpo-30876 [https://bugs.python.org/issue?@action=redirect&bpo=30876]: Relative import from unloaded package now reimports the package instead of failing with SystemError. Relative import from non-package now fails with ImportError rather than SystemError.

bpo-30703 [https://bugs.python.org/issue?@action=redirect&bpo=30703]: Improve signal delivery. Avoid using Py_AddPendingCall from signal handler, to avoid calling signal-unsafe functions. The tests I’m adding here fail without the rest of the patch, on Linux and OS X. This means our signal delivery logic had defects (some signals could be lost).

bpo-30765 [https://bugs.python.org/issue?@action=redirect&bpo=30765]: Avoid blocking in pthread_mutex_lock() when PyThread_acquire_lock() is asked not to block.

bpo-31161 [https://bugs.python.org/issue?@action=redirect&bpo=31161]: Make sure the “Missing parentheses” syntax error message is only applied to SyntaxError, not to subclasses. Patch by Martijn Pieters.

bpo-30814 [https://bugs.python.org/issue?@action=redirect&bpo=30814]: Fixed a race condition when import a submodule from a package.

bpo-30597 [https://bugs.python.org/issue?@action=redirect&bpo=30597]: print now shows expected input in custom error message when used as a Python 2 statement. Patch by Sanyam Khurana.

Library

bpo-31499 [https://bugs.python.org/issue?@action=redirect&bpo=31499]: xml.etree: Fix a crash when a parser is part of a reference cycle.

bpo-28556 [https://bugs.python.org/issue?@action=redirect&bpo=28556]: typing.get_type_hints now finds the right globalns for classes and modules by default (when no globalns was specified by the caller).

bpo-28556 [https://bugs.python.org/issue?@action=redirect&bpo=28556]: Speed improvements to the typing module. Original PRs by Ivan Levkivskyi and Mitar.

bpo-31544 [https://bugs.python.org/issue?@action=redirect&bpo=31544]: The C accelerator module of ElementTree ignored exceptions raised when looking up TreeBuilder target methods in XMLParser().

bpo-31234 [https://bugs.python.org/issue?@action=redirect&bpo=31234]: socket.create_connection() now fixes manually a reference cycle: clear the variable storing the last exception on success.

bpo-31457 [https://bugs.python.org/issue?@action=redirect&bpo=31457]: LoggerAdapter objects can now be nested.

bpo-31400 [https://bugs.python.org/issue?@action=redirect&bpo=31400]: Improves SSL error handling to avoid losing error numbers.

bpo-28958 [https://bugs.python.org/issue?@action=redirect&bpo=28958]: ssl.SSLContext() now uses OpenSSL error information when a context cannot be instantiated.

bpo-27340 [https://bugs.python.org/issue?@action=redirect&bpo=27340]: SSLSocket.sendall() now uses memoryview to create slices of data. This fixes support for all bytes-like object. It is also more efficient and avoids costly copies.

bpo-31178 [https://bugs.python.org/issue?@action=redirect&bpo=31178]: Fix string concatenation bug in rare error path in the subprocess module

bpo-31350 [https://bugs.python.org/issue?@action=redirect&bpo=31350]: Micro-optimize asyncio._get_running_loop() to become up to 10% faster.

bpo-31170 [https://bugs.python.org/issue?@action=redirect&bpo=31170]: expat: Update libexpat from 2.2.3 to 2.2.4. Fix copying of partial characters for UTF-8 input (libexpat bug 115): https://github.com/libexpat/libexpat/issues/115

bpo-29136 [https://bugs.python.org/issue?@action=redirect&bpo=29136]: Add TLS 1.3 cipher suites and OP_NO_TLSv1_3.

bpo-29212 [https://bugs.python.org/issue?@action=redirect&bpo=29212]: Fix concurrent.futures.thread.ThreadPoolExecutor threads to have a non repr() based thread name by default when no thread_name_prefix is supplied. They will now identify themselves as «ThreadPoolExecutor-y_n».

bpo-9146 [https://bugs.python.org/issue?@action=redirect&bpo=9146]: Fix a segmentation fault in _hashopenssl when standard hash functions such as md5 are not available in the linked OpenSSL library. As in some special FIPS-140 build environments.

bpo-27144 [https://bugs.python.org/issue?@action=redirect&bpo=27144]: The map() and as_completed() iterators in concurrent.futures now avoid keeping a reference to yielded objects.

bpo-10746 [https://bugs.python.org/issue?@action=redirect&bpo=10746]: Fix ctypes producing wrong PEP 3118 [https://www.python.org/dev/peps/pep-3118] type codes for integer types.

bpo-22536 [https://bugs.python.org/issue?@action=redirect&bpo=22536]: The subprocess module now sets the filename when FileNotFoundError is raised on POSIX systems due to the executable or cwd not being found.

bpo-31249 [https://bugs.python.org/issue?@action=redirect&bpo=31249]: concurrent.futures: WorkItem.run() used by ThreadPoolExecutor now breaks a reference cycle between an exception object and the WorkItem object.

bpo-31247 [https://bugs.python.org/issue?@action=redirect&bpo=31247]: xmlrpc.server now explicitly breaks reference cycles when using sys.exc_info() in code handling exceptions.

bpo-30102 [https://bugs.python.org/issue?@action=redirect&bpo=30102]: The ssl and hashlib modules now call OPENSSL_add_all_algorithms_noconf() on OpenSSL < 1.1.0. The function detects CPU features and enables optimizations on some CPU architectures such as POWER8. Patch is based on research from Gustavo Serra Scalet.

bpo-31185 [https://bugs.python.org/issue?@action=redirect&bpo=31185]: Fixed miscellaneous errors in asyncio speedup module.

bpo-31135 [https://bugs.python.org/issue?@action=redirect&bpo=31135]: ttk: fix the destroy() method of LabeledScale and OptionMenu classes. Call the parent destroy() method even if the used attribute doesn’t exist. The LabeledScale.destroy() method now also explicitly clears label and scale attributes to help the garbage collector to destroy all widgets.

bpo-31107 [https://bugs.python.org/issue?@action=redirect&bpo=31107]: Fix copyreg._slotnames() mangled attribute calculation for classes whose name begins with an underscore. Patch by Shane Harvey.

bpo-31061 [https://bugs.python.org/issue?@action=redirect&bpo=31061]: Fixed a crash when using asyncio and threads.

bpo-30502 [https://bugs.python.org/issue?@action=redirect&bpo=30502]: Fix handling of long oids in ssl. Based on patch by Christian Heimes.

bpo-30119 [https://bugs.python.org/issue?@action=redirect&bpo=30119]: ftplib.FTP.putline() now throws ValueError on commands that contains CR or LF. Patch by Dong-hee Na.

bpo-30595 [https://bugs.python.org/issue?@action=redirect&bpo=30595]: multiprocessing.Queue.get() with a timeout now polls its reader in non-blocking mode if it succeeded to acquire the lock but the acquire took longer than the timeout.

bpo-29403 [https://bugs.python.org/issue?@action=redirect&bpo=29403]: Fix unittest.mock’s autospec to not fail on method-bound builtin functions. Patch by Aaron Gallagher.

bpo-30961 [https://bugs.python.org/issue?@action=redirect&bpo=30961]: Fix decrementing a borrowed reference in tracemalloc.

bpo-25684 [https://bugs.python.org/issue?@action=redirect&bpo=25684]: Change ttk.OptionMenu radiobuttons to be unique across instances of OptionMenu.

bpo-30886 [https://bugs.python.org/issue?@action=redirect&bpo=30886]: Fix multiprocessing.Queue.join_thread(): it now waits until the thread completes, even if the thread was started by the same process which created the queue.

bpo-29854 [https://bugs.python.org/issue?@action=redirect&bpo=29854]: Fix segfault in readline when using readline’s history-size option. Patch by Nir Soffer.

bpo-30319 [https://bugs.python.org/issue?@action=redirect&bpo=30319]: socket.close() now ignores ECONNRESET error.

bpo-30828 [https://bugs.python.org/issue?@action=redirect&bpo=30828]: Fix out of bounds write in asyncio.CFuture.remove_done_callback().

bpo-30807 [https://bugs.python.org/issue?@action=redirect&bpo=30807]: signal.setitimer() may disable the timer when passed a tiny value. Tiny values (such as 1e-6) are valid non-zero values for setitimer(), which is specified as taking microsecond-resolution intervals. However, on some platform, our conversion routine could convert 1e-6 into a zero interval, therefore disabling the timer instead of (re-)scheduling it.

bpo-30441 [https://bugs.python.org/issue?@action=redirect&bpo=30441]: Fix bug when modifying os.environ while iterating over it

bpo-30532 [https://bugs.python.org/issue?@action=redirect&bpo=30532]: Fix email header value parser dropping folding white space in certain cases.

bpo-30879 [https://bugs.python.org/issue?@action=redirect&bpo=30879]: os.listdir() and os.scandir() now emit bytes names when called with bytes-like argument.

bpo-30746 [https://bugs.python.org/issue?@action=redirect&bpo=30746]: Prohibited the “=” character in environment variable names in os.putenv() and os.spawn*().

bpo-29755 [https://bugs.python.org/issue?@action=redirect&bpo=29755]: Fixed the lgettext() family of functions in the gettext module. They now always return bytes.

Documentation

bpo-31294 [https://bugs.python.org/issue?@action=redirect&bpo=31294]: Fix incomplete code snippet in the ZeroMQSocketListener and ZeroMQSocketHandler examples and adapt them to Python 3.

bpo-21649 [https://bugs.python.org/issue?@action=redirect&bpo=21649]: Add RFC 7525 and Mozilla server side TLS links to SSL documentation.

bpo-30803 [https://bugs.python.org/issue?@action=redirect&bpo=30803]: Clarify doc on truth value testing. Original patch by Peter Thomassen.

Tests

bpo-31320 [https://bugs.python.org/issue?@action=redirect&bpo=31320]: Silence traceback in test_ssl

bpo-25674 [https://bugs.python.org/issue?@action=redirect&bpo=25674]: Remove sha256.tbs-internet.com ssl test

bpo-30715 [https://bugs.python.org/issue?@action=redirect&bpo=30715]: Address ALPN callback changes for OpenSSL 1.1.0f. The latest version behaves like OpenSSL 1.0.2 and no longer aborts handshake.

bpo-30822 [https://bugs.python.org/issue?@action=redirect&bpo=30822]: regrtest: Exclude tzdata from regrtest –all. When running the test suite using –use=all / -u all, exclude tzdata since it makes test_datetime too slow (15-20 min on some buildbots) which then times out on some buildbots. Fix also regrtest command line parser to allow passing -u extralargefile to run test_zipfile64.

Build

bpo-30854 [https://bugs.python.org/issue?@action=redirect&bpo=30854]: Fix compile error when compiling –without-threads. Patch by Masayuki Yamamoto.

Windows

bpo-30389 [https://bugs.python.org/issue?@action=redirect&bpo=30389]: Adds detection of Visual Studio 2017 to distutils on Windows.

bpo-31340 [https://bugs.python.org/issue?@action=redirect&bpo=31340]: Change to building with MSVC v141 (included with Visual Studio 2017)

bpo-30581 [https://bugs.python.org/issue?@action=redirect&bpo=30581]: os.cpu_count() now returns the correct number of processors on Windows when the number of logical processors is greater than 64.

bpo-30731 [https://bugs.python.org/issue?@action=redirect&bpo=30731]: Add a missing xmlns to python.manifest so that it matches the schema.

IDLE

bpo-31493 [https://bugs.python.org/issue?@action=redirect&bpo=31493]: IDLE code context – fix code update and font update timers. Canceling timers prevents a warning message when test_idle completes.

bpo-31488 [https://bugs.python.org/issue?@action=redirect&bpo=31488]: IDLE - Update non-key options in former extension classes. When applying configdialog changes, call .reload for each feature class. Change ParenMatch so updated options affect existing instances attached to existing editor windows.

bpo-31477 [https://bugs.python.org/issue?@action=redirect&bpo=31477]: IDLE - Improve rstrip entry in doc. Strip trailing whitespace strips more than blank spaces. Multiline string literals are not skipped.

bpo-31480 [https://bugs.python.org/issue?@action=redirect&bpo=31480]: IDLE - make tests pass with zzdummy extension disabled by default.

bpo-31421 [https://bugs.python.org/issue?@action=redirect&bpo=31421]: Document how IDLE runs tkinter programs. IDLE calls tcl/tk update in the background in order to make live interaction and experimentation with tkinter applications much easier.

bpo-31414 [https://bugs.python.org/issue?@action=redirect&bpo=31414]: IDLE – fix tk entry box tests by deleting first. Adding to an int entry is not the same as deleting and inserting because int(“”) will fail.

bpo-31051 [https://bugs.python.org/issue?@action=redirect&bpo=31051]: Rearrange IDLE configdialog GenPage into Window, Editor, and Help sections.

bpo-30617 [https://bugs.python.org/issue?@action=redirect&bpo=30617]: IDLE - Add docstrings and tests for outwin subclass of editor. Move some data and functions from the class to module level. Patch by Cheryl Sabella.

bpo-31287 [https://bugs.python.org/issue?@action=redirect&bpo=31287]: IDLE - Do not modify tkinter.message in test_configdialog.

bpo-27099 [https://bugs.python.org/issue?@action=redirect&bpo=27099]: Convert IDLE’s built-in “extensions” to regular features. About 10 IDLE features were implemented as supposedly optional extensions. Their different behavior could be confusing or worse for users and not good for maintenance. Hence the conversion. The main difference for users is that user configurable key bindings for builtin features are now handled uniformly. Now, editing a binding in a keyset only affects its value in the keyset. All bindings are defined together in the system-specific default keysets in config-extensions.def. All custom keysets are saved as a whole in config-extension.cfg. All take effect as soon as one clicks Apply or Ok. The affected events are “<<force-open-completions>>”, “<<expand-word>>”, “<<force-open-calltip>>”, “<<flash-paren>>”, “<<format-paragraph>>”, “<<run-module>>”, “<<check-module>>”, and “<<zoom-height>>”. Any (global) customizations made before 3.6.3 will not affect their keyset-specific customization after 3.6.3. and vice versa. Initial patch by Charles Wohlganger.

bpo-31206 [https://bugs.python.org/issue?@action=redirect&bpo=31206]: IDLE: Factor HighPage(Frame) class from ConfigDialog. Patch by Cheryl Sabella.

bpo-31001 [https://bugs.python.org/issue?@action=redirect&bpo=31001]: Add tests for configdialog highlight tab. Patch by Cheryl Sabella.

bpo-31205 [https://bugs.python.org/issue?@action=redirect&bpo=31205]: IDLE: Factor KeysPage(Frame) class from ConfigDialog. The slightly modified tests continue to pass. Patch by Cheryl Sabella.

bpo-31130 [https://bugs.python.org/issue?@action=redirect&bpo=31130]: IDLE – stop leaks in test_configdialog. Initial patch by Victor Stinner.

bpo-31002 [https://bugs.python.org/issue?@action=redirect&bpo=31002]: Add tests for configdialog keys tab. Patch by Cheryl Sabella.

bpo-19903 [https://bugs.python.org/issue?@action=redirect&bpo=19903]: IDLE: Calltips use inspect.signature instead of inspect.getfullargspec. This improves calltips for builtins converted to use Argument Clinic. Patch by Louie Lu.

bpo-31083 [https://bugs.python.org/issue?@action=redirect&bpo=31083]: IDLE - Add an outline of a TabPage class in configdialog. Update existing classes to match outline. Initial patch by Cheryl Sabella.

bpo-31050 [https://bugs.python.org/issue?@action=redirect&bpo=31050]: Factor GenPage(Frame) class from ConfigDialog. The slightly modified tests continue to pass. Patch by Cheryl Sabella.

bpo-31004 [https://bugs.python.org/issue?@action=redirect&bpo=31004]: IDLE - Factor FontPage(Frame) class from ConfigDialog. Slightly modified tests continue to pass. Fix General tests. Patch mostly by Cheryl Sabella.

bpo-30781 [https://bugs.python.org/issue?@action=redirect&bpo=30781]: IDLE - Use ttk widgets in ConfigDialog. Patches by Terry Jan Reedy and Cheryl Sabella.

bpo-31060 [https://bugs.python.org/issue?@action=redirect&bpo=31060]: IDLE - Finish rearranging methods of ConfigDialog Grouping methods pertaining to each tab and the buttons will aid writing tests and improving the tabs and will enable splitting the groups into classes.

bpo-30853 [https://bugs.python.org/issue?@action=redirect&bpo=30853]: IDLE – Factor a VarTrace class out of ConfigDialog. Instance tracers manages pairs consisting of a tk variable and a callback function. When tracing is turned on, setting the variable calls the function. Test coverage for the new class is 100%.

bpo-31003 [https://bugs.python.org/issue?@action=redirect&bpo=31003]: IDLE: Add more tests for General tab.

bpo-30993 [https://bugs.python.org/issue?@action=redirect&bpo=30993]: IDLE - Improve configdialog font page and tests. In configdialog: Document causal pathways in create_font_tab docstring. Simplify some attribute names. Move set_samples calls to var_changed_font (idea from Cheryl Sabella). Move related functions to positions after the create widgets function. In test_configdialog: Fix test_font_set so not order dependent. Fix renamed test_indent_scale so it tests the widget. Adjust tests for movement of set_samples call. Add tests for load functions. Put all font tests in one class and tab indent tests in another. Except for two lines, these tests completely cover the related functions.

bpo-30981 [https://bugs.python.org/issue?@action=redirect&bpo=30981]: IDLE – Add more configdialog font page tests.

bpo-28523 [https://bugs.python.org/issue?@action=redirect&bpo=28523]: IDLE: replace “colour” with “color” in configdialog.

bpo-30917 [https://bugs.python.org/issue?@action=redirect&bpo=30917]: Add tests for idlelib.config.IdleConf. Increase coverage from 46% to 96%. Patch by Louie Lu.

bpo-30934 [https://bugs.python.org/issue?@action=redirect&bpo=30934]: Document coverage details for idlelib tests. Add section to idlelib/idle-test/README.txt. Include check that branches are taken both ways. Exclude IDLE-specific code that does not run during unit tests.

bpo-30913 [https://bugs.python.org/issue?@action=redirect&bpo=30913]: IDLE: Document ConfigDialog tk Vars, methods, and widgets in docstrings This will facilitate improving the dialog and splitting up the class. Original patch by Cheryl Sabella.

bpo-30899 [https://bugs.python.org/issue?@action=redirect&bpo=30899]: IDLE: Add tests for ConfigParser subclasses in config. Patch by Louie Lu.

bpo-30881 [https://bugs.python.org/issue?@action=redirect&bpo=30881]: IDLE: Add docstrings to browser.py. Patch by Cheryl Sabella.

bpo-30851 [https://bugs.python.org/issue?@action=redirect&bpo=30851]: IDLE: Remove unused variables in configdialog. One is a duplicate, one is set but cannot be altered by users. Patch by Cheryl Sabella.

bpo-30870 [https://bugs.python.org/issue?@action=redirect&bpo=30870]: IDLE: In Settings dialog, select font with Up, Down keys as well as mouse. Initial patch by Louie Lu.

bpo-8231 [https://bugs.python.org/issue?@action=redirect&bpo=8231]: IDLE: call config.IdleConf.GetUserCfgDir only once.

bpo-30779 [https://bugs.python.org/issue?@action=redirect&bpo=30779]: IDLE: Factor ConfigChanges class from configdialog, put in config; test. * In config, put dump test code in a function; run it and unittest in “if __name__ == “__main__”. * Add class config.ConfigChanges based on changes_class_v4.py on bpo issue. * Add class test_config.ChangesTest, partly using configdialog_tests_v1.py. * Revise configdialog to use ConfigChanges; see tracker msg297804. * Revise test_configdialog to match configdialog changes. * Remove configdialog functions unused or moved to ConfigChanges. Cheryl Sabella contributed parts of the patch.

bpo-30777 [https://bugs.python.org/issue?@action=redirect&bpo=30777]: IDLE: configdialog - Add docstrings and fix comments. Patch by Cheryl Sabella.

bpo-30495 [https://bugs.python.org/issue?@action=redirect&bpo=30495]: IDLE: Improve textview with docstrings, PEP8 names, and more tests. Patch by Cheryl Sabella.

bpo-30723 [https://bugs.python.org/issue?@action=redirect&bpo=30723]: IDLE: Make several improvements to parenmatch. Add “parens” style to highlight both opener and closer. Make “default” style, which is not default, a synonym for “opener”. Make time-delay work the same with all styles. Add help for config dialog extensions tab, including help for parenmatch. Add new tests. Original patch by Charles Wohlganger.

bpo-30674 [https://bugs.python.org/issue?@action=redirect&bpo=30674]: IDLE: add docstrings to grep module. Patch by Cheryl Sabella

bpo-21519 [https://bugs.python.org/issue?@action=redirect&bpo=21519]: IDLE’s basic custom key entry dialog now detects duplicates properly. Original patch by Saimadhav Heblikar.

bpo-29910 [https://bugs.python.org/issue?@action=redirect&bpo=29910]: IDLE no longer deletes a character after commenting out a region by a key shortcut. Add return 'break' for this and other potential conflicts between IDLE and default key bindings.

bpo-30728 [https://bugs.python.org/issue?@action=redirect&bpo=30728]: Review and change idlelib.configdialog names. Lowercase method and attribute names. Replace “colour” with “color”, expand overly cryptic names, delete unneeded underscores. Replace import * with specific imports. Patches by Cheryl Sabella.

bpo-6739 [https://bugs.python.org/issue?@action=redirect&bpo=6739]: IDLE: Verify user-entered key sequences by trying to bind them with tk. Add tests for all 3 validation functions. Original patch by G Polo. Tests added by Cheryl Sabella.

Tools/Demos

bpo-30983 [https://bugs.python.org/issue?@action=redirect&bpo=30983]: gdb integration commands (py-bt, etc.) work on optimized shared builds now, too. PEP 523 [https://www.python.org/dev/peps/pep-0523] introduced _PyEval_EvalFrameDefault which inlines PyEval_EvalFrameEx on non-debug shared builds. This broke the ability to use py-bt, py-up, and a few other Python-specific gdb integrations. The problem is fixed by only looking for _PyEval_EvalFrameDefault frames in python-gdb.py. Original patch by Bruno «Polaco» Penteado.

Python 3.6.2 final

Release date: 2017-07-17

No changes since release candidate 2

Python 3.6.2 release candidate 2

Release date: 2017-07-07

Security

bpo-30730 [https://bugs.python.org/issue?@action=redirect&bpo=30730]: Prevent environment variables injection in subprocess on Windows. Prevent passing other environment variables and command arguments.

bpo-30694 [https://bugs.python.org/issue?@action=redirect&bpo=30694]: Upgrade expat copy from 2.2.0 to 2.2.1 to get fixes of multiple security vulnerabilities including: CVE-2017-9233 (External entity infinite loop DoS), CVE-2016-9063 (Integer overflow, re-fix), CVE-2016-0718 (Fix regression bugs from 2.2.0’s fix to CVE-2016-0718) and CVE-2012-0876 (Counter hash flooding with SipHash). Note: the CVE-2016-5300 (Use os-specific entropy sources like getrandom) doesn’t impact Python, since Python already gets entropy from the OS to set the expat secret using XML_SetHashSalt().

bpo-30500 [https://bugs.python.org/issue?@action=redirect&bpo=30500]: Fix urllib.parse.splithost() to correctly parse fragments. For example, splithost('//127.0.0.1#@evil.com/') now correctly returns the 127.0.0.1 host, instead of treating @evil.com as the host in an authentication (login@host).

Python 3.6.2 release candidate 1

Release date: 2017-06-17

Security

bpo-29591 [https://bugs.python.org/issue?@action=redirect&bpo=29591]: Update expat copy from 2.1.1 to 2.2.0 to get fixes of CVE-2016-0718 and CVE-2016-4472. See https://sourceforge.net/p/expat/bugs/537/ for more information.

Core and Builtins

bpo-30682 [https://bugs.python.org/issue?@action=redirect&bpo=30682]: Removed a too-strict assertion that failed for certain f-strings, such as eval(«f”\n”») and eval(«f”\r”»).

bpo-30604 [https://bugs.python.org/issue?@action=redirect&bpo=30604]: Move co_extra_freefuncs to not be per-thread to avoid crashes

bpo-29104 [https://bugs.python.org/issue?@action=redirect&bpo=29104]: Fixed parsing backslashes in f-strings.

bpo-27945 [https://bugs.python.org/issue?@action=redirect&bpo=27945]: Fixed various segfaults with dict when input collections are mutated during searching, inserting or comparing. Based on patches by Duane Griffin and Tim Mitchell.

bpo-25794 [https://bugs.python.org/issue?@action=redirect&bpo=25794]: Fixed type.__setattr__() and type.__delattr__() for non-interned attribute names. Based on patch by Eryk Sun.

bpo-30039 [https://bugs.python.org/issue?@action=redirect&bpo=30039]: If a KeyboardInterrupt happens when the interpreter is in the middle of resuming a chain of nested “yield from” or “await” calls, it’s now correctly delivered to the innermost frame.

bpo-12414 [https://bugs.python.org/issue?@action=redirect&bpo=12414]: sys.getsizeof() on a code object now returns the sizes which includes the code struct and sizes of objects which it references. Patch by Dong-hee Na.

bpo-29949 [https://bugs.python.org/issue?@action=redirect&bpo=29949]: Fix memory usage regression of set and frozenset object.

bpo-29935 [https://bugs.python.org/issue?@action=redirect&bpo=29935]: Fixed error messages in the index() method of tuple, list and deque when pass indices of wrong type.

bpo-29859 [https://bugs.python.org/issue?@action=redirect&bpo=29859]: Show correct error messages when any of the pthread_* calls in thread_pthread.h fails.

bpo-28876 [https://bugs.python.org/issue?@action=redirect&bpo=28876]: bool(range) works even if len(range) raises OverflowError.

bpo-29600 [https://bugs.python.org/issue?@action=redirect&bpo=29600]: Fix wrapping coroutine return values in StopIteration.

bpo-28856 [https://bugs.python.org/issue?@action=redirect&bpo=28856]: Fix an oversight that %b format for bytes should support objects follow the buffer protocol.

bpo-29714 [https://bugs.python.org/issue?@action=redirect&bpo=29714]: Fix a regression that bytes format may fail when containing zero bytes inside.

bpo-29478 [https://bugs.python.org/issue?@action=redirect&bpo=29478]: If max_line_length=None is specified while using the Compat32 policy, it is no longer ignored. Patch by Mircea Cosbuc.

Library

bpo-30616 [https://bugs.python.org/issue?@action=redirect&bpo=30616]: Functional API of enum allows to create empty enums. Patched by Dong-hee Na

bpo-30038 [https://bugs.python.org/issue?@action=redirect&bpo=30038]: Fix race condition between signal delivery and wakeup file descriptor. Patch by Nathaniel Smith.

bpo-23894 [https://bugs.python.org/issue?@action=redirect&bpo=23894]: lib2to3 now recognizes rb'...' and f'...' strings.

bpo-23890 [https://bugs.python.org/issue?@action=redirect&bpo=23890]: unittest.TestCase.assertRaises() now manually breaks a reference cycle to not keep objects alive longer than expected.

bpo-30149 [https://bugs.python.org/issue?@action=redirect&bpo=30149]: inspect.signature() now supports callables with variable-argument parameters wrapped with partialmethod. Patch by Dong-hee Na.

bpo-30645 [https://bugs.python.org/issue?@action=redirect&bpo=30645]: Fix path calculation in imp.load_package(), fixing it for cases when a package is only shipped with bytecodes. Patch by Alexandru Ardelean.

bpo-29931 [https://bugs.python.org/issue?@action=redirect&bpo=29931]: Fixed comparison check for ipaddress.ip_interface objects. Patch by Sanjay Sundaresan.

bpo-30605 [https://bugs.python.org/issue?@action=redirect&bpo=30605]: re.compile() no longer raises a BytesWarning when compiling a bytes instance with misplaced inline modifier. Patch by Roy Williams.

bpo-24484 [https://bugs.python.org/issue?@action=redirect&bpo=24484]: Avoid race condition in multiprocessing cleanup (#2159)

bpo-28994 [https://bugs.python.org/issue?@action=redirect&bpo=28994]: The traceback no longer displayed for SystemExit raised in a callback registered by atexit.

bpo-30508 [https://bugs.python.org/issue?@action=redirect&bpo=30508]: Don’t log exceptions if Task/Future «cancel()» method was called.

bpo-28556 [https://bugs.python.org/issue?@action=redirect&bpo=28556]: Updates to typing module: Add generic AsyncContextManager, add support for ContextManager on all versions. Original PRs by Jelle Zijlstra and Ivan Levkivskyi

bpo-29870 [https://bugs.python.org/issue?@action=redirect&bpo=29870]: Fix ssl sockets leaks when connection is aborted in asyncio/ssl implementation. Patch by Michaël Sghaïer.

bpo-29743 [https://bugs.python.org/issue?@action=redirect&bpo=29743]: Closing transport during handshake process leaks open socket. Patch by Nikolay Kim

bpo-27585 [https://bugs.python.org/issue?@action=redirect&bpo=27585]: Fix waiter cancellation in asyncio.Lock. Patch by Mathieu Sornay.

bpo-30418 [https://bugs.python.org/issue?@action=redirect&bpo=30418]: On Windows, subprocess.Popen.communicate() now also ignore EINVAL on stdin.write() if the child process is still running but closed the pipe.

bpo-29822 [https://bugs.python.org/issue?@action=redirect&bpo=29822]: inspect.isabstract() now works during __init_subclass__. Patch by Nate Soares.

bpo-29581 [https://bugs.python.org/issue?@action=redirect&bpo=29581]: ABCMeta.__new__ now accepts **kwargs, allowing abstract base classes to use keyword parameters in __init_subclass__. Patch by Nate Soares.

bpo-30557 [https://bugs.python.org/issue?@action=redirect&bpo=30557]: faulthandler now correctly filters and displays exception codes on Windows

bpo-30378 [https://bugs.python.org/issue?@action=redirect&bpo=30378]: Fix the problem that logging.handlers.SysLogHandler cannot handle IPv6 addresses.

bpo-29960 [https://bugs.python.org/issue?@action=redirect&bpo=29960]: Preserve generator state when _random.Random.setstate() raises an exception. Patch by Bryan Olson.

bpo-30414 [https://bugs.python.org/issue?@action=redirect&bpo=30414]: multiprocessing.Queue._feed background running thread do not break from main loop on exception.

bpo-30003 [https://bugs.python.org/issue?@action=redirect&bpo=30003]: Fix handling escape characters in HZ codec. Based on patch by Ma Lin.

bpo-30301 [https://bugs.python.org/issue?@action=redirect&bpo=30301]: Fix AttributeError when using SimpleQueue.empty() under spawn and forkserver start methods.

bpo-30329 [https://bugs.python.org/issue?@action=redirect&bpo=30329]: imaplib and poplib now catch the Windows socket WSAEINVAL error (code 10022) on shutdown(SHUT_RDWR): An invalid operation was attempted. This error occurs sometimes on SSL connections.

bpo-30375 [https://bugs.python.org/issue?@action=redirect&bpo=30375]: Warnings emitted when compile a regular expression now always point to the line in the user code. Previously they could point into inners of the re module if emitted from inside of groups or conditionals.

bpo-30048 [https://bugs.python.org/issue?@action=redirect&bpo=30048]: Fixed Task.cancel() can be ignored when the task is running coroutine and the coroutine returned without any more await.

bpo-30266 [https://bugs.python.org/issue?@action=redirect&bpo=30266]: contextlib.AbstractContextManager now supports anti-registration by setting __enter__ = None or __exit__ = None, following the pattern introduced in bpo-25958 [https://bugs.python.org/issue?@action=redirect&bpo=25958]. Patch by Jelle Zijlstra.

bpo-30298 [https://bugs.python.org/issue?@action=redirect&bpo=30298]: Weaken the condition of deprecation warnings for inline modifiers. Now allowed several subsequential inline modifiers at the start of the pattern (e.g. '(?i)(?s)...'). In verbose mode whitespaces and comments now are allowed before and between inline modifiers (e.g. '(?x) (?i) (?s)...').

bpo-29990 [https://bugs.python.org/issue?@action=redirect&bpo=29990]: Fix range checking in GB18030 decoder. Original patch by Ma Lin.

bpo-26293 [https://bugs.python.org/issue?@action=redirect&bpo=26293]: Change resulted because of zipfile breakage. (See also: bpo-29094 [https://bugs.python.org/issue?@action=redirect&bpo=29094])

bpo-30243 [https://bugs.python.org/issue?@action=redirect&bpo=30243]: Removed the __init__ methods of _json’s scanner and encoder. Misusing them could cause memory leaks or crashes. Now scanner and encoder objects are completely initialized in the __new__ methods.

bpo-30185 [https://bugs.python.org/issue?@action=redirect&bpo=30185]: Avoid KeyboardInterrupt tracebacks in forkserver helper process when Ctrl-C is received.

bpo-28556 [https://bugs.python.org/issue?@action=redirect&bpo=28556]: Various updates to typing module: add typing.NoReturn type, use WrapperDescriptorType, minor bug-fixes. Original PRs by Jim Fasarakis-Hilliard and Ivan Levkivskyi.

bpo-30205 [https://bugs.python.org/issue?@action=redirect&bpo=30205]: Fix getsockname() for unbound AF_UNIX sockets on Linux.

bpo-30070 [https://bugs.python.org/issue?@action=redirect&bpo=30070]: Fixed leaks and crashes in errors handling in the parser module.

bpo-30061 [https://bugs.python.org/issue?@action=redirect&bpo=30061]: Fixed crashes in IOBase methods __next__() and readlines() when readline() or __next__() respectively return non-sizeable object. Fixed possible other errors caused by not checking results of PyObject_Size(), PySequence_Size(), or PyMapping_Size().

bpo-30017 [https://bugs.python.org/issue?@action=redirect&bpo=30017]: Allowed calling the close() method of the zip entry writer object multiple times. Writing to a closed writer now always produces a ValueError.

bpo-30068 [https://bugs.python.org/issue?@action=redirect&bpo=30068]: _io._IOBase.readlines will check if it’s closed first when hint is present.

bpo-29694 [https://bugs.python.org/issue?@action=redirect&bpo=29694]: Fixed race condition in pathlib mkdir with flags parents=True. Patch by Armin Rigo.

bpo-29692 [https://bugs.python.org/issue?@action=redirect&bpo=29692]: Fixed arbitrary unchaining of RuntimeError exceptions in contextlib.contextmanager. Patch by Siddharth Velankar.

bpo-29998 [https://bugs.python.org/issue?@action=redirect&bpo=29998]: Pickling and copying ImportError now preserves name and path attributes.

bpo-29953 [https://bugs.python.org/issue?@action=redirect&bpo=29953]: Fixed memory leaks in the replace() method of datetime and time objects when pass out of bound fold argument.

bpo-29942 [https://bugs.python.org/issue?@action=redirect&bpo=29942]: Fix a crash in itertools.chain.from_iterable when encountering long runs of empty iterables.

bpo-27863 [https://bugs.python.org/issue?@action=redirect&bpo=27863]: Fixed multiple crashes in ElementTree caused by race conditions and wrong types.

bpo-28699 [https://bugs.python.org/issue?@action=redirect&bpo=28699]: Fixed a bug in pools in multiprocessing.pool that raising an exception at the very first of an iterable may swallow the exception or make the program hang. Patch by Davin Potts and Xiang Zhang.

bpo-25803 [https://bugs.python.org/issue?@action=redirect&bpo=25803]: Avoid incorrect errors raised by Path.mkdir(exist_ok=True) when the OS gives priority to errors such as EACCES over EEXIST.

bpo-29861 [https://bugs.python.org/issue?@action=redirect&bpo=29861]: Release references to tasks, their arguments and their results as soon as they are finished in multiprocessing.Pool.

bpo-29884 [https://bugs.python.org/issue?@action=redirect&bpo=29884]: faulthandler: Restore the old sigaltstack during teardown. Patch by Christophe Zeitouny.

bpo-25455 [https://bugs.python.org/issue?@action=redirect&bpo=25455]: Fixed crashes in repr of recursive buffered file-like objects.

bpo-29800 [https://bugs.python.org/issue?@action=redirect&bpo=29800]: Fix crashes in partial.__repr__ if the keys of partial.keywords are not strings. Patch by Michael Seifert.

bpo-29742 [https://bugs.python.org/issue?@action=redirect&bpo=29742]: get_extra_info() raises exception if get called on closed ssl transport. Patch by Nikolay Kim.

bpo-8256 [https://bugs.python.org/issue?@action=redirect&bpo=8256]: Fixed possible failing or crashing input() if attributes «encoding» or «errors» of sys.stdin or sys.stdout are not set or are not strings.

bpo-28298 [https://bugs.python.org/issue?@action=redirect&bpo=28298]: Fix a bug that prevented array “Q”, “L” and “I” from accepting big intables (objects that have __int__) as elements. Patch by Oren Milman.

bpo-28231 [https://bugs.python.org/issue?@action=redirect&bpo=28231]: The zipfile module now accepts path-like objects for external paths.

bpo-26915 [https://bugs.python.org/issue?@action=redirect&bpo=26915]: index() and count() methods of collections.abc.Sequence now check identity before checking equality when do comparisons.

bpo-29615 [https://bugs.python.org/issue?@action=redirect&bpo=29615]: SimpleXMLRPCDispatcher no longer chains KeyError (or any other exception) to exception(s) raised in the dispatched methods. Patch by Petr Motejlek.

bpo-30177 [https://bugs.python.org/issue?@action=redirect&bpo=30177]: path.resolve(strict=False) no longer cuts the path after the first element not present in the filesystem. Patch by Antoine Pietri.

IDLE

bpo-15786 [https://bugs.python.org/issue?@action=redirect&bpo=15786]: Fix several problems with IDLE’s autocompletion box. The following should now work: clicking on selection box items; using the scrollbar; selecting an item by hitting Return. Hangs on MacOSX should no longer happen. Patch by Louie Lu.

bpo-25514 [https://bugs.python.org/issue?@action=redirect&bpo=25514]: Add doc subsubsection about IDLE failure to start. Popup no-connection message directs users to this section.

bpo-30642 [https://bugs.python.org/issue?@action=redirect&bpo=30642]: Fix reference leaks in IDLE tests. Patches by Louie Lu and Terry Jan Reedy.

bpo-30495 [https://bugs.python.org/issue?@action=redirect&bpo=30495]: Add docstrings for textview.py and use PEP8 names. Patches by Cheryl Sabella and Terry Jan Reedy.

bpo-30290 [https://bugs.python.org/issue?@action=redirect&bpo=30290]: Help-about: use pep8 names and add tests. Increase coverage to 100%. Patches by Louie Lu, Cheryl Sabella, and Terry Jan Reedy.

bpo-30303 [https://bugs.python.org/issue?@action=redirect&bpo=30303]: Add _utest option to textview; add new tests. Increase coverage to 100%. Patches by Louie Lu and Terry Jan Reedy.

C API

bpo-27867 [https://bugs.python.org/issue?@action=redirect&bpo=27867]: Function PySlice_GetIndicesEx() no longer replaced with a macro if Py_LIMITED_API is not set.

Build

bpo-29941 [https://bugs.python.org/issue?@action=redirect&bpo=29941]: Add --with-assertions configure flag to explicitly enable C assert() checks. Defaults to off. --with-pydebug implies --with-assertions.

bpo-28787 [https://bugs.python.org/issue?@action=redirect&bpo=28787]: Fix out-of-tree builds of Python when configured with --with--dtrace.

bpo-29243 [https://bugs.python.org/issue?@action=redirect&bpo=29243]: Prevent unnecessary rebuilding of Python during make test, make install and some other make targets when configured with --enable-optimizations.

bpo-23404 [https://bugs.python.org/issue?@action=redirect&bpo=23404]: Don’t regenerate generated files based on file modification time anymore: the action is now explicit. Replace make touch with make regen-all.

bpo-29643 [https://bugs.python.org/issue?@action=redirect&bpo=29643]: Fix --enable-optimization didn’t work.

Documentation

bpo-30176 [https://bugs.python.org/issue?@action=redirect&bpo=30176]: Add missing attribute related constants in curses documentation.

bpo-30052 [https://bugs.python.org/issue?@action=redirect&bpo=30052]: the link targets for bytes() and bytearray() are now their respective type definitions, rather than the corresponding builtin function entries. Use bytes and bytearray to reference the latter. In order to ensure this and future cross-reference updates are applied automatically, the daily documentation builds now disable the default output caching features in Sphinx.

bpo-26985 [https://bugs.python.org/issue?@action=redirect&bpo=26985]: Add missing info of code object in inspect documentation.

Tools/Demos

bpo-29367 [https://bugs.python.org/issue?@action=redirect&bpo=29367]: python-gdb.py now supports also method-wrapper (wrapperobject) objects.

Tests

bpo-30357 [https://bugs.python.org/issue?@action=redirect&bpo=30357]: test_thread: setUp() now uses support.threading_setup() and support.threading_cleanup() to wait until threads complete to avoid random side effects on following tests. Initial patch written by Grzegorz Grzywacz.

bpo-30197 [https://bugs.python.org/issue?@action=redirect&bpo=30197]: Enhanced functions swap_attr() and swap_item() in the test.support module. They now work when delete replaced attribute or item inside the with statement. The old value of the attribute or item (or None if it doesn’t exist) now will be assigned to the target of the «as» clause, if there is one.

Windows

bpo-30687 [https://bugs.python.org/issue?@action=redirect&bpo=30687]: Locate msbuild.exe on Windows when building rather than vcvarsall.bat

bpo-30450 [https://bugs.python.org/issue?@action=redirect&bpo=30450]: The build process on Windows no longer depends on Subversion, instead pulling external code from GitHub via a Python script. If Python 3.6 is not found on the system (via py -3.6), NuGet is used to download a copy of 32-bit Python.

Python 3.6.1 final

Release date: 2017-03-21

Core and Builtins

bpo-29723 [https://bugs.python.org/issue?@action=redirect&bpo=29723]: The sys.path[0] initialization change for bpo-29139 [https://bugs.python.org/issue?@action=redirect&bpo=29139] caused a regression by revealing an inconsistency in how sys.path is initialized when executing __main__ from a zipfile, directory, or other import location. The interpreter now consistently avoids ever adding the import location’s parent directory to sys.path, and ensures no other sys.path entries are inadvertently modified when inserting the import location named on the command line.

Build

bpo-27593 [https://bugs.python.org/issue?@action=redirect&bpo=27593]: fix format of git information used in sys.version

Fix incompatible comment in python.h

Python 3.6.1 release candidate 1

Release date: 2017-03-04

Core and Builtins

bpo-28893 [https://bugs.python.org/issue?@action=redirect&bpo=28893]: Set correct __cause__ for errors about invalid awaitables returned from __aiter__ and __anext__.

bpo-29683 [https://bugs.python.org/issue?@action=redirect&bpo=29683]: Fixes to memory allocation in _PyCode_SetExtra. Patch by Brian Coleman.

bpo-29684 [https://bugs.python.org/issue?@action=redirect&bpo=29684]: Fix minor regression of PyEval_CallObjectWithKeywords. It should raise TypeError when kwargs is not a dict. But it might cause segv when args=NULL and kwargs is not a dict.

bpo-28598 [https://bugs.python.org/issue?@action=redirect&bpo=28598]: Support __rmod__ for subclasses of str being called before str.__mod__. Patch by Martijn Pieters.

bpo-29607 [https://bugs.python.org/issue?@action=redirect&bpo=29607]: Fix stack_effect computation for CALL_FUNCTION_EX. Patch by Matthieu Dartiailh.

bpo-29602 [https://bugs.python.org/issue?@action=redirect&bpo=29602]: Fix incorrect handling of signed zeros in complex constructor for complex subclasses and for inputs having a __complex__ method. Patch by Serhiy Storchaka.

bpo-29347 [https://bugs.python.org/issue?@action=redirect&bpo=29347]: Fixed possibly dereferencing undefined pointers when creating weakref objects.

bpo-29438 [https://bugs.python.org/issue?@action=redirect&bpo=29438]: Fixed use-after-free problem in key sharing dict.

bpo-29319 [https://bugs.python.org/issue?@action=redirect&bpo=29319]: Prevent RunMainFromImporter overwriting sys.path[0].

bpo-29337 [https://bugs.python.org/issue?@action=redirect&bpo=29337]: Fixed possible BytesWarning when compare the code objects. Warnings could be emitted at compile time.

bpo-29327 [https://bugs.python.org/issue?@action=redirect&bpo=29327]: Fixed a crash when pass the iterable keyword argument to sorted().

bpo-29034 [https://bugs.python.org/issue?@action=redirect&bpo=29034]: Fix memory leak and use-after-free in os module (path_converter).

bpo-29159 [https://bugs.python.org/issue?@action=redirect&bpo=29159]: Fix regression in bytes(x) when x.__index__() raises Exception.

bpo-28932 [https://bugs.python.org/issue?@action=redirect&bpo=28932]: Do not include <sys/random.h> if it does not exist.

bpo-25677 [https://bugs.python.org/issue?@action=redirect&bpo=25677]: Correct the positioning of the syntax error caret for indented blocks. Based on patch by Michael Layzell.

bpo-29000 [https://bugs.python.org/issue?@action=redirect&bpo=29000]: Fixed bytes formatting of octals with zero padding in alternate form.

bpo-26919 [https://bugs.python.org/issue?@action=redirect&bpo=26919]: On Android, operating system data is now always encoded/decoded to/from UTF-8, instead of the locale encoding to avoid inconsistencies with os.fsencode() and os.fsdecode() which are already using UTF-8.

bpo-28991 [https://bugs.python.org/issue?@action=redirect&bpo=28991]: functools.lru_cache() was susceptible to an obscure reentrancy bug triggerable by a monkey-patched len() function.

bpo-28739 [https://bugs.python.org/issue?@action=redirect&bpo=28739]: f-string expressions are no longer accepted as docstrings and by ast.literal_eval() even if they do not include expressions.

bpo-28512 [https://bugs.python.org/issue?@action=redirect&bpo=28512]: Fixed setting the offset attribute of SyntaxError by PyErr_SyntaxLocationEx() and PyErr_SyntaxLocationObject().

bpo-28918 [https://bugs.python.org/issue?@action=redirect&bpo=28918]: Fix the cross compilation of xxlimited when Python has been built with Py_DEBUG defined.

bpo-28731 [https://bugs.python.org/issue?@action=redirect&bpo=28731]: Optimize _PyDict_NewPresized() to create correct size dict. Improve speed of dict literal with constant keys up to 30%.

Library

bpo-29169 [https://bugs.python.org/issue?@action=redirect&bpo=29169]: Update zlib to 1.2.11.

bpo-29623 [https://bugs.python.org/issue?@action=redirect&bpo=29623]: Allow use of path-like object as a single argument in ConfigParser.read(). Patch by David Ellis.

bpo-28963 [https://bugs.python.org/issue?@action=redirect&bpo=28963]: Fix out of bound iteration in asyncio.Future.remove_done_callback implemented in C.

bpo-29704 [https://bugs.python.org/issue?@action=redirect&bpo=29704]: asyncio.subprocess.SubprocessStreamProtocol no longer closes before all pipes are closed.

bpo-29271 [https://bugs.python.org/issue?@action=redirect&bpo=29271]: Fix Task.current_task and Task.all_tasks implemented in C to accept None argument as their pure Python implementation.

bpo-29703 [https://bugs.python.org/issue?@action=redirect&bpo=29703]: Fix asyncio to support instantiation of new event loops in child processes.

bpo-29376 [https://bugs.python.org/issue?@action=redirect&bpo=29376]: Fix assertion error in threading._DummyThread.is_alive().

bpo-28624 [https://bugs.python.org/issue?@action=redirect&bpo=28624]: Add a test that checks that cwd parameter of Popen() accepts PathLike objects. Patch by Sayan Chowdhury.

bpo-28518 [https://bugs.python.org/issue?@action=redirect&bpo=28518]: Start a transaction implicitly before a DML statement. Patch by Aviv Palivoda.

bpo-29532 [https://bugs.python.org/issue?@action=redirect&bpo=29532]: Altering a kwarg dictionary passed to functools.partial() no longer affects a partial object after creation.

bpo-29110 [https://bugs.python.org/issue?@action=redirect&bpo=29110]: Fix file object leak in aifc.open() when file is given as a filesystem path and is not in valid AIFF format. Patch by Anthony Zhang.

bpo-28556 [https://bugs.python.org/issue?@action=redirect&bpo=28556]: Various updates to typing module: typing.Counter, typing.ChainMap, improved ABC caching, etc. Original PRs by Jelle Zijlstra, Ivan Levkivskyi, Manuel Krebber, and Łukasz Langa.

bpo-29100 [https://bugs.python.org/issue?@action=redirect&bpo=29100]: Fix datetime.fromtimestamp() regression introduced in Python 3.6.0: check minimum and maximum years.

bpo-29519 [https://bugs.python.org/issue?@action=redirect&bpo=29519]: Fix weakref spewing exceptions during interpreter shutdown when used with a rare combination of multiprocessing and custom codecs.

bpo-29416 [https://bugs.python.org/issue?@action=redirect&bpo=29416]: Prevent infinite loop in pathlib.Path.mkdir

bpo-29444 [https://bugs.python.org/issue?@action=redirect&bpo=29444]: Fixed out-of-bounds buffer access in the group() method of the match object. Based on patch by WGH.

bpo-29335 [https://bugs.python.org/issue?@action=redirect&bpo=29335]: Fix subprocess.Popen.wait() when the child process has exited to a stopped instead of terminated state (ex: when under ptrace).

bpo-29290 [https://bugs.python.org/issue?@action=redirect&bpo=29290]: Fix a regression in argparse that help messages would wrap at non-breaking spaces.

bpo-28735 [https://bugs.python.org/issue?@action=redirect&bpo=28735]: Fixed the comparison of mock.MagickMock with mock.ANY.

bpo-29316 [https://bugs.python.org/issue?@action=redirect&bpo=29316]: Restore the provisional status of typing module, add corresponding note to documentation. Patch by Ivan L.

bpo-29219 [https://bugs.python.org/issue?@action=redirect&bpo=29219]: Fixed infinite recursion in the repr of uninitialized ctypes.CDLL instances.

bpo-29011 [https://bugs.python.org/issue?@action=redirect&bpo=29011]: Fix an important omission by adding Deque to the typing module.

bpo-28969 [https://bugs.python.org/issue?@action=redirect&bpo=28969]: Fixed race condition in C implementation of functools.lru_cache. KeyError could be raised when cached function with full cache was simultaneously called from different threads with the same uncached arguments.

bpo-29142 [https://bugs.python.org/issue?@action=redirect&bpo=29142]: In urllib.request, suffixes in no_proxy environment variable with leading dots could match related hostnames again (e.g. .b.c matches a.b.c). Patch by Milan Oberkirch.

bpo-28961 [https://bugs.python.org/issue?@action=redirect&bpo=28961]: Fix unittest.mock._Call helper: don’t ignore the name parameter anymore. Patch written by Jiajun Huang.

bpo-29203 [https://bugs.python.org/issue?@action=redirect&bpo=29203]: functools.lru_cache() now respects PEP 468 [https://www.python.org/dev/peps/pep-0468] and preserves the order of keyword arguments. f(a=1, b=2) is now cached separately from f(b=2, a=1) since both calls could potentially give different results.

bpo-15812 [https://bugs.python.org/issue?@action=redirect&bpo=15812]: inspect.getframeinfo() now correctly shows the first line of a context. Patch by Sam Breese.

bpo-29094 [https://bugs.python.org/issue?@action=redirect&bpo=29094]: Offsets in a ZIP file created with extern file object and modes «w» and «x» now are relative to the start of the file.

bpo-29085 [https://bugs.python.org/issue?@action=redirect&bpo=29085]: Allow random.Random.seed() to use high quality OS randomness rather than the pid and time.

bpo-29061 [https://bugs.python.org/issue?@action=redirect&bpo=29061]: Fixed bug in secrets.randbelow() which would hang when given a negative input. Patch by Brendan Donegan.

bpo-29079 [https://bugs.python.org/issue?@action=redirect&bpo=29079]: Prevent infinite loop in pathlib.resolve() on Windows

bpo-13051 [https://bugs.python.org/issue?@action=redirect&bpo=13051]: Fixed recursion errors in large or resized curses.textpad.Textbox. Based on patch by Tycho Andersen.

bpo-29119 [https://bugs.python.org/issue?@action=redirect&bpo=29119]: Fix weakrefs in the pure python version of collections.OrderedDict move_to_end() method. Contributed by Andra Bogildea.

bpo-9770 [https://bugs.python.org/issue?@action=redirect&bpo=9770]: curses.ascii predicates now work correctly with negative integers.

bpo-28427 [https://bugs.python.org/issue?@action=redirect&bpo=28427]: old keys should not remove new values from WeakValueDictionary when collecting from another thread.

bpo-28923 [https://bugs.python.org/issue?@action=redirect&bpo=28923]: Remove editor artifacts from Tix.py.

bpo-29055 [https://bugs.python.org/issue?@action=redirect&bpo=29055]: Neaten-up empty population error on random.choice() by suppressing the upstream exception.

bpo-28871 [https://bugs.python.org/issue?@action=redirect&bpo=28871]: Fixed a crash when deallocate deep ElementTree.

bpo-19542 [https://bugs.python.org/issue?@action=redirect&bpo=19542]: Fix bugs in WeakValueDictionary.setdefault() and WeakValueDictionary.pop() when a GC collection happens in another thread.

bpo-20191 [https://bugs.python.org/issue?@action=redirect&bpo=20191]: Fixed a crash in resource.prlimit() when passing a sequence that doesn’t own its elements as limits.

bpo-28779 [https://bugs.python.org/issue?@action=redirect&bpo=28779]: multiprocessing.set_forkserver_preload() would crash the forkserver process if a preloaded module instantiated some multiprocessing objects such as locks.

bpo-28847 [https://bugs.python.org/issue?@action=redirect&bpo=28847]: dbm.dumb now supports reading read-only files and no longer writes the index file when it is not changed.

bpo-26937 [https://bugs.python.org/issue?@action=redirect&bpo=26937]: The chown() method of the tarfile.TarFile class does not fail now when the grp module cannot be imported, as for example on Android platforms.

IDLE

bpo-29071 [https://bugs.python.org/issue?@action=redirect&bpo=29071]: IDLE colors f-string prefixes (but not invalid ur prefixes).

bpo-28572 [https://bugs.python.org/issue?@action=redirect&bpo=28572]: Add 10% to coverage of IDLE’s test_configdialog. Update and augment description of the configuration system.

Windows

bpo-29579 [https://bugs.python.org/issue?@action=redirect&bpo=29579]: Removes readme.txt from the installer

bpo-29326 [https://bugs.python.org/issue?@action=redirect&bpo=29326]: Ignores blank lines in ._pth files (Patch by Alexey Izbyshev)

bpo-28164 [https://bugs.python.org/issue?@action=redirect&bpo=28164]: Correctly handle special console filenames (patch by Eryk Sun)

bpo-29409 [https://bugs.python.org/issue?@action=redirect&bpo=29409]: Implement PEP 529 [https://www.python.org/dev/peps/pep-0529] for io.FileIO (Patch by Eryk Sun)

bpo-29392 [https://bugs.python.org/issue?@action=redirect&bpo=29392]: Prevent crash when passing invalid arguments into msvcrt module.

bpo-25778 [https://bugs.python.org/issue?@action=redirect&bpo=25778]: winreg does not truncate string correctly (Patch by Eryk Sun)

bpo-28896 [https://bugs.python.org/issue?@action=redirect&bpo=28896]: Deprecate WindowsRegistryFinder and disable it by default.

C API

bpo-27867 [https://bugs.python.org/issue?@action=redirect&bpo=27867]: Function PySlice_GetIndicesEx() is replaced with a macro if Py_LIMITED_API is not set or set to the value between 0x03050400 and 0x03060000 (not including) or 0x03060100 or higher.

bpo-29083 [https://bugs.python.org/issue?@action=redirect&bpo=29083]: Fixed the declaration of some public API functions. PyArg_VaParse() and PyArg_VaParseTupleAndKeywords() were not available in limited API. PyArg_ValidateKeywordArguments(), PyArg_UnpackTuple() and Py_BuildValue() were not available in limited API of version < 3.3 when PY_SSIZE_T_CLEAN is defined.

bpo-29058 [https://bugs.python.org/issue?@action=redirect&bpo=29058]: All stable API extensions added after Python 3.2 are now available only when Py_LIMITED_API is set to the PY_VERSION_HEX value of the minimum Python version supporting this API.

Documentation

bpo-28929 [https://bugs.python.org/issue?@action=redirect&bpo=28929]: Link the documentation to its source file on GitHub.

bpo-25008 [https://bugs.python.org/issue?@action=redirect&bpo=25008]: Document smtpd.py as effectively deprecated and add a pointer to aiosmtpd, a third-party asyncio-based replacement.

bpo-26355 [https://bugs.python.org/issue?@action=redirect&bpo=26355]: Add canonical header link on each page to corresponding major version of the documentation. Patch by Matthias Bussonnier.

bpo-29349 [https://bugs.python.org/issue?@action=redirect&bpo=29349]: Fix Python 2 syntax in code for building the documentation.

Tests

bpo-28087 [https://bugs.python.org/issue?@action=redirect&bpo=28087]: Skip test_asyncore and test_eintr poll failures on macOS. Skip some tests of select.poll when running on macOS due to unresolved issues with the underlying system poll function on some macOS versions.

bpo-29571 [https://bugs.python.org/issue?@action=redirect&bpo=29571]: to match the behaviour of the re.LOCALE flag, test_re.test_locale_flag now uses locale.getpreferredencoding(False) to determine the candidate encoding for the test regex (allowing it to correctly skip the test when the default locale encoding is a multi-byte encoding)

bpo-28950 [https://bugs.python.org/issue?@action=redirect&bpo=28950]: Disallow -j0 to be combined with -T/-l in regrtest command line arguments.

bpo-28683 [https://bugs.python.org/issue?@action=redirect&bpo=28683]: Fix the tests that bind() a unix socket and raise PermissionError on Android for a non-root user.

bpo-26939 [https://bugs.python.org/issue?@action=redirect&bpo=26939]: Add the support.setswitchinterval() function to fix test_functools hanging on the Android armv7 qemu emulator.

Build

bpo-27593 [https://bugs.python.org/issue?@action=redirect&bpo=27593]: sys.version and the platform module python_build(), python_branch(), and python_revision() functions now use git information rather than hg when building from a repo.

bpo-29572 [https://bugs.python.org/issue?@action=redirect&bpo=29572]: Update Windows build and OS X installers to use OpenSSL 1.0.2k.

bpo-26851 [https://bugs.python.org/issue?@action=redirect&bpo=26851]: Set Android compilation and link flags.

bpo-28768 [https://bugs.python.org/issue?@action=redirect&bpo=28768]: Fix implicit declaration of function _setmode. Patch by Masayuki Yamamoto

bpo-29080 [https://bugs.python.org/issue?@action=redirect&bpo=29080]: Removes hard dependency on hg.exe from PCBuild/build.bat

bpo-23903 [https://bugs.python.org/issue?@action=redirect&bpo=23903]: Added missed names to PC/python3.def.

bpo-28762 [https://bugs.python.org/issue?@action=redirect&bpo=28762]: lockf() is available on Android API level 24, but the F_LOCK macro is not defined in android-ndk-r13.

bpo-28538 [https://bugs.python.org/issue?@action=redirect&bpo=28538]: Fix the compilation error that occurs because if_nameindex() is available on Android API level 24, but the if_nameindex structure is not defined.

bpo-20211 [https://bugs.python.org/issue?@action=redirect&bpo=20211]: Do not add the directory for installing C header files and the directory for installing object code libraries to the cross compilation search paths. Original patch by Thomas Petazzoni.

bpo-28849 [https://bugs.python.org/issue?@action=redirect&bpo=28849]: Do not define sys.implementation._multiarch on Android.

Python 3.6.0 final

Release date: 2016-12-23

No changes since release candidate 2

Python 3.6.0 release candidate 2

Release date: 2016-12-16

Core and Builtins

bpo-28147 [https://bugs.python.org/issue?@action=redirect&bpo=28147]: Fix a memory leak in split-table dictionaries: setattr() must not convert combined table into split table. Patch written by INADA Naoki.

bpo-28990 [https://bugs.python.org/issue?@action=redirect&bpo=28990]: Fix asyncio SSL hanging if connection is closed before handshake is completed. (Patch by HoHo-Ho)

Tools/Demos

bpo-28770 [https://bugs.python.org/issue?@action=redirect&bpo=28770]: Fix python-gdb.py for fastcalls.

Windows

bpo-28896 [https://bugs.python.org/issue?@action=redirect&bpo=28896]: Deprecate WindowsRegistryFinder.

Build

bpo-28898 [https://bugs.python.org/issue?@action=redirect&bpo=28898]: Prevent gdb build errors due to HAVE_LONG_LONG redefinition.

Python 3.6.0 release candidate 1

Release date: 2016-12-06

Core and Builtins

bpo-23722 [https://bugs.python.org/issue?@action=redirect&bpo=23722]: Rather than silently producing a class that doesn’t support zero-argument super() in methods, failing to pass the new __classcell__ namespace entry up to type.__new__ now results in a DeprecationWarning and a class that supports zero-argument super().

bpo-28797 [https://bugs.python.org/issue?@action=redirect&bpo=28797]: Modifying the class __dict__ inside the __set_name__ method of a descriptor that is used inside that class no longer prevents calling the __set_name__ method of other descriptors.

bpo-28782 [https://bugs.python.org/issue?@action=redirect&bpo=28782]: Fix a bug in the implementation yield from when checking if the next instruction is YIELD_FROM. Regression introduced by WORDCODE (bpo-26647 [https://bugs.python.org/issue?@action=redirect&bpo=26647]).

Library

bpo-27030 [https://bugs.python.org/issue?@action=redirect&bpo=27030]: Unknown escapes in re.sub() replacement template are allowed again. But they still are deprecated and will be disabled in 3.7.

bpo-28835 [https://bugs.python.org/issue?@action=redirect&bpo=28835]: Fix a regression introduced in warnings.catch_warnings(): call warnings.showwarning() if it was overridden inside the context manager.

bpo-27172 [https://bugs.python.org/issue?@action=redirect&bpo=27172]: To assist with upgrades from 2.7, the previously documented deprecation of inspect.getfullargspec() has been reversed. This decision may be revisited again after the Python 2.7 branch is no longer officially supported.

bpo-26273 [https://bugs.python.org/issue?@action=redirect&bpo=26273]: Add new socket.TCP_CONGESTION (Linux 2.6.13) and socket.TCP_USER_TIMEOUT (Linux 2.6.37) constants. Patch written by Omar Sandoval.

bpo-24142 [https://bugs.python.org/issue?@action=redirect&bpo=24142]: Reading a corrupt config file left configparser in an invalid state. Original patch by Florian Höch.

bpo-28843 [https://bugs.python.org/issue?@action=redirect&bpo=28843]: Fix asyncio C Task to handle exceptions __traceback__.

C API

bpo-28808 [https://bugs.python.org/issue?@action=redirect&bpo=28808]: PyUnicode_CompareWithASCIIString() now never raises exceptions.

Documentation

bpo-23722 [https://bugs.python.org/issue?@action=redirect&bpo=23722]: The data model reference and the porting section in the What’s New guide now cover the additional __classcell__ handling needed for custom metaclasses to fully support PEP 487 [https://www.python.org/dev/peps/pep-0487] and zero-argument super().

Tools/Demos

bpo-28023 [https://bugs.python.org/issue?@action=redirect&bpo=28023]: Fix python-gdb.py didn’t support new dict implementation.

Python 3.6.0 beta 4

Release date: 2016-11-21

Core and Builtins

bpo-28532 [https://bugs.python.org/issue?@action=redirect&bpo=28532]: Show sys.version when -V option is supplied twice.

bpo-27100 [https://bugs.python.org/issue?@action=redirect&bpo=27100]: The with-statement now checks for __enter__ before it checks for __exit__. This gives less confusing error messages when both methods are missing. Patch by Jonathan Ellington.

bpo-28746 [https://bugs.python.org/issue?@action=redirect&bpo=28746]: Fix the set_inheritable() file descriptor method on platforms that do not have the ioctl FIOCLEX and FIONCLEX commands.

bpo-26920 [https://bugs.python.org/issue?@action=redirect&bpo=26920]: Fix not getting the locale’s charset upon initializing the interpreter, on platforms that do not have langinfo.

bpo-28648 [https://bugs.python.org/issue?@action=redirect&bpo=28648]: Fixed crash in Py_DecodeLocale() in debug build on Mac OS X when decode astral characters. Patch by Xiang Zhang.

bpo-19398 [https://bugs.python.org/issue?@action=redirect&bpo=19398]: Extra slash no longer added to sys.path components in case of empty compile-time PYTHONPATH components.

bpo-28665 [https://bugs.python.org/issue?@action=redirect&bpo=28665]: Improve speed of the STORE_DEREF opcode by 40%.

bpo-28583 [https://bugs.python.org/issue?@action=redirect&bpo=28583]: PyDict_SetDefault didn’t combine split table when needed. Patch by Xiang Zhang.

bpo-27243 [https://bugs.python.org/issue?@action=redirect&bpo=27243]: Change PendingDeprecationWarning -> DeprecationWarning. As it was agreed in the issue, __aiter__ returning an awaitable should result in PendingDeprecationWarning in 3.5 and in DeprecationWarning in 3.6.

bpo-26182 [https://bugs.python.org/issue?@action=redirect&bpo=26182]: Fix a refleak in code that raises DeprecationWarning.

bpo-28721 [https://bugs.python.org/issue?@action=redirect&bpo=28721]: Fix asynchronous generators aclose() and athrow() to handle StopAsyncIteration propagation properly.

Library

bpo-28752 [https://bugs.python.org/issue?@action=redirect&bpo=28752]: Restored the __reduce__() methods of datetime objects.

bpo-28727 [https://bugs.python.org/issue?@action=redirect&bpo=28727]: Regular expression patterns, _sre.SRE_Pattern objects created by re.compile(), become comparable (only x==y and x!=y operators). This change should fix the bpo-18383 [https://bugs.python.org/issue?@action=redirect&bpo=18383]: don’t duplicate warning filters when the warnings module is reloaded (thing usually only done in unit tests).

bpo-20572 [https://bugs.python.org/issue?@action=redirect&bpo=20572]: The subprocess.Popen.wait method’s undocumented endtime parameter now raises a DeprecationWarning.

bpo-25659 [https://bugs.python.org/issue?@action=redirect&bpo=25659]: In ctypes, prevent a crash calling the from_buffer() and from_buffer_copy() methods on abstract classes like Array.

bpo-19717 [https://bugs.python.org/issue?@action=redirect&bpo=19717]: Makes Path.resolve() succeed on paths that do not exist. Patch by Vajrasky Kok

bpo-28563 [https://bugs.python.org/issue?@action=redirect&bpo=28563]: Fixed possible DoS and arbitrary code execution when handle plural form selections in the gettext module. The expression parser now supports exact syntax supported by GNU gettext.

bpo-28387 [https://bugs.python.org/issue?@action=redirect&bpo=28387]: Fixed possible crash in _io.TextIOWrapper deallocator when the garbage collector is invoked in other thread. Based on patch by Sebastian Cufre.

bpo-28600 [https://bugs.python.org/issue?@action=redirect&bpo=28600]: Optimize loop.call_soon.

bpo-28613 [https://bugs.python.org/issue?@action=redirect&bpo=28613]: Fix get_event_loop() return the current loop if called from coroutines/callbacks.

bpo-28634 [https://bugs.python.org/issue?@action=redirect&bpo=28634]: Fix asyncio.isfuture() to support unittest.Mock.

bpo-26081 [https://bugs.python.org/issue?@action=redirect&bpo=26081]: Fix refleak in _asyncio.Future.__iter__().throw.

bpo-28639 [https://bugs.python.org/issue?@action=redirect&bpo=28639]: Fix inspect.isawaitable to always return bool Patch by Justin Mayfield.

bpo-28652 [https://bugs.python.org/issue?@action=redirect&bpo=28652]: Make loop methods reject socket kinds they do not support.

bpo-28653 [https://bugs.python.org/issue?@action=redirect&bpo=28653]: Fix a refleak in functools.lru_cache.

bpo-28703 [https://bugs.python.org/issue?@action=redirect&bpo=28703]: Fix asyncio.iscoroutinefunction to handle Mock objects.

bpo-28704 [https://bugs.python.org/issue?@action=redirect&bpo=28704]: Fix create_unix_server to support Path-like objects (PEP 519).

bpo-28720 [https://bugs.python.org/issue?@action=redirect&bpo=28720]: Add collections.abc.AsyncGenerator.

Documentation

bpo-28513 [https://bugs.python.org/issue?@action=redirect&bpo=28513]: Documented command-line interface of zipfile.

Tests

bpo-28666 [https://bugs.python.org/issue?@action=redirect&bpo=28666]: Now test.support.rmtree is able to remove unwritable or unreadable directories.

bpo-23839 [https://bugs.python.org/issue?@action=redirect&bpo=23839]: Various caches now are cleared before running every test file.

Build

bpo-10656 [https://bugs.python.org/issue?@action=redirect&bpo=10656]: Fix out-of-tree building on AIX. Patch by Tristan Carel and Michael Haubenwallner.

bpo-26359 [https://bugs.python.org/issue?@action=redirect&bpo=26359]: Rename –with-optimiations to –enable-optimizations.

bpo-28676 [https://bugs.python.org/issue?@action=redirect&bpo=28676]: Prevent missing “getentropy” declaration warning on macOS. Patch by Gareth Rees.

Python 3.6.0 beta 3

Release date: 2016-10-31

Core and Builtins

bpo-28128 [https://bugs.python.org/issue?@action=redirect&bpo=28128]: Deprecation warning for invalid str and byte escape sequences now prints better information about where the error occurs. Patch by Serhiy Storchaka and Eric Smith.

bpo-28509 [https://bugs.python.org/issue?@action=redirect&bpo=28509]: dict.update() no longer allocate unnecessary large memory.

bpo-28426 [https://bugs.python.org/issue?@action=redirect&bpo=28426]: Fixed potential crash in PyUnicode_AsDecodedObject() in debug build.

bpo-28517 [https://bugs.python.org/issue?@action=redirect&bpo=28517]: Fixed of-by-one error in the peephole optimizer that caused keeping unreachable code.

bpo-28214 [https://bugs.python.org/issue?@action=redirect&bpo=28214]: Improved exception reporting for problematic __set_name__ attributes.

bpo-23782 [https://bugs.python.org/issue?@action=redirect&bpo=23782]: Fixed possible memory leak in _PyTraceback_Add() and exception loss in PyTraceBack_Here().

bpo-28471 [https://bugs.python.org/issue?@action=redirect&bpo=28471]: Fix «Python memory allocator called without holding the GIL» crash in socket.setblocking.

Library

bpo-27517 [https://bugs.python.org/issue?@action=redirect&bpo=27517]: LZMA compressor and decompressor no longer raise exceptions if given empty data twice. Patch by Benjamin Fogle.

bpo-28549 [https://bugs.python.org/issue?@action=redirect&bpo=28549]: Fixed segfault in curses’s addch() with ncurses6.

bpo-28449 [https://bugs.python.org/issue?@action=redirect&bpo=28449]: tarfile.open() with mode «r» or «r:» now tries to open a tar file with compression before trying to open it without compression. Otherwise it had 50% chance failed with ignore_zeros=True.

bpo-23262 [https://bugs.python.org/issue?@action=redirect&bpo=23262]: The webbrowser module now supports Firefox 36+ and derived browsers. Based on patch by Oleg Broytman.

bpo-27939 [https://bugs.python.org/issue?@action=redirect&bpo=27939]: Fixed bugs in tkinter.ttk.LabeledScale and tkinter.Scale caused by representing the scale as float value internally in Tk. tkinter.IntVar now works if float value is set to underlying Tk variable.

bpo-18844 [https://bugs.python.org/issue?@action=redirect&bpo=18844]: The various ways of specifying weights for random.choices() now produce the same result sequences.

bpo-28255 [https://bugs.python.org/issue?@action=redirect&bpo=28255]: calendar.TextCalendar().prmonth() no longer prints a space at the start of new line after printing a month’s calendar. Patch by Xiang Zhang.

bpo-20491 [https://bugs.python.org/issue?@action=redirect&bpo=20491]: The textwrap.TextWrapper class now honors non-breaking spaces. Based on patch by Kaarle Ritvanen.

bpo-28353 [https://bugs.python.org/issue?@action=redirect&bpo=28353]: os.fwalk() no longer fails on broken links.

bpo-28430 [https://bugs.python.org/issue?@action=redirect&bpo=28430]: Fix iterator of C implemented asyncio.Future doesn’t accept non-None value is passed to it.send(val).

bpo-27025 [https://bugs.python.org/issue?@action=redirect&bpo=27025]: Generated names for Tkinter widgets now start by the «!» prefix for readability.

bpo-25464 [https://bugs.python.org/issue?@action=redirect&bpo=25464]: Fixed HList.header_exists() in tkinter.tix module by addin a workaround to Tix library bug.

bpo-28488 [https://bugs.python.org/issue?@action=redirect&bpo=28488]: shutil.make_archive() no longer adds entry «./» to ZIP archive.

bpo-25953 [https://bugs.python.org/issue?@action=redirect&bpo=25953]: re.sub() now raises an error for invalid numerical group reference in replacement template even if the pattern is not found in the string. Error message for invalid group reference now includes the group index and the position of the reference. Based on patch by SilentGhost.

bpo-18219 [https://bugs.python.org/issue?@action=redirect&bpo=18219]: Optimize csv.DictWriter for large number of columns. Patch by Mariatta Wijaya.

bpo-28448 [https://bugs.python.org/issue?@action=redirect&bpo=28448]: Fix C implemented asyncio.Future didn’t work on Windows.

bpo-28480 [https://bugs.python.org/issue?@action=redirect&bpo=28480]: Fix error building socket module when multithreading is disabled.

bpo-24452 [https://bugs.python.org/issue?@action=redirect&bpo=24452]: Make webbrowser support Chrome on Mac OS X.

bpo-20766 [https://bugs.python.org/issue?@action=redirect&bpo=20766]: Fix references leaked by pdb in the handling of SIGINT handlers.

bpo-28492 [https://bugs.python.org/issue?@action=redirect&bpo=28492]: Fix how StopIteration exception is raised in _asyncio.Future.

bpo-28500 [https://bugs.python.org/issue?@action=redirect&bpo=28500]: Fix asyncio to handle async gens GC from another thread.

bpo-26923 [https://bugs.python.org/issue?@action=redirect&bpo=26923]: Fix asyncio.Gather to refuse being cancelled once all children are done. Patch by Johannes Ebke.

bpo-26796 [https://bugs.python.org/issue?@action=redirect&bpo=26796]: Don’t configure the number of workers for default threadpool executor. Initial patch by Hans Lawrenz.

bpo-28544 [https://bugs.python.org/issue?@action=redirect&bpo=28544]: Implement asyncio.Task in C.

Windows

bpo-28522 [https://bugs.python.org/issue?@action=redirect&bpo=28522]: Fixes mishandled buffer reallocation in getpathp.c

Build

bpo-28444 [https://bugs.python.org/issue?@action=redirect&bpo=28444]: Fix missing extensions modules when cross compiling.

bpo-28208 [https://bugs.python.org/issue?@action=redirect&bpo=28208]: Update Windows build and OS X installers to use SQLite 3.14.2.

bpo-28248 [https://bugs.python.org/issue?@action=redirect&bpo=28248]: Update Windows build and OS X installers to use OpenSSL 1.0.2j.

Tests

bpo-26944 [https://bugs.python.org/issue?@action=redirect&bpo=26944]: Fix test_posix for Android where “id -G” is entirely wrong or missing the effective gid.

bpo-28409 [https://bugs.python.org/issue?@action=redirect&bpo=28409]: regrtest: fix the parser of command line arguments.

Python 3.6.0 beta 2

Release date: 2016-10-10

Core and Builtins

bpo-28183 [https://bugs.python.org/issue?@action=redirect&bpo=28183]: Optimize and cleanup dict iteration.

bpo-26081 [https://bugs.python.org/issue?@action=redirect&bpo=26081]: Added C implementation of asyncio.Future. Original patch by Yury Selivanov.

bpo-28379 [https://bugs.python.org/issue?@action=redirect&bpo=28379]: Added sanity checks and tests for PyUnicode_CopyCharacters(). Patch by Xiang Zhang.

bpo-28376 [https://bugs.python.org/issue?@action=redirect&bpo=28376]: The type of long range iterator is now registered as Iterator. Patch by Oren Milman.

bpo-28376 [https://bugs.python.org/issue?@action=redirect&bpo=28376]: Creating instances of range_iterator by calling range_iterator type now is deprecated. Patch by Oren Milman.

bpo-28376 [https://bugs.python.org/issue?@action=redirect&bpo=28376]: The constructor of range_iterator now checks that step is not 0. Patch by Oren Milman.

bpo-26906 [https://bugs.python.org/issue?@action=redirect&bpo=26906]: Resolving special methods of uninitialized type now causes implicit initialization of the type instead of a fail.

bpo-18287 [https://bugs.python.org/issue?@action=redirect&bpo=18287]: PyType_Ready() now checks that tp_name is not NULL. Original patch by Niklas Koep.

bpo-24098 [https://bugs.python.org/issue?@action=redirect&bpo=24098]: Fixed possible crash when AST is changed in process of compiling it.

bpo-28201 [https://bugs.python.org/issue?@action=redirect&bpo=28201]: Dict reduces possibility of 2nd conflict in hash table when hashes have same lower bits.

bpo-28350 [https://bugs.python.org/issue?@action=redirect&bpo=28350]: String constants with null character no longer interned.

bpo-26617 [https://bugs.python.org/issue?@action=redirect&bpo=26617]: Fix crash when GC runs during weakref callbacks.

bpo-27942 [https://bugs.python.org/issue?@action=redirect&bpo=27942]: String constants now interned recursively in tuples and frozensets.

bpo-21578 [https://bugs.python.org/issue?@action=redirect&bpo=21578]: Fixed misleading error message when ImportError called with invalid keyword args.

bpo-28203 [https://bugs.python.org/issue?@action=redirect&bpo=28203]: Fix incorrect type in complex(1.0, {2:3}) error message. Patch by Soumya Sharma.

bpo-28086 [https://bugs.python.org/issue?@action=redirect&bpo=28086]: Single var-positional argument of tuple subtype was passed unscathed to the C-defined function. Now it is converted to exact tuple.

bpo-28214 [https://bugs.python.org/issue?@action=redirect&bpo=28214]: Now __set_name__ is looked up on the class instead of the instance.

bpo-27955 [https://bugs.python.org/issue?@action=redirect&bpo=27955]: Fallback on reading /dev/urandom device when the getrandom() syscall fails with EPERM, for example when blocked by SECCOMP.

bpo-28192 [https://bugs.python.org/issue?@action=redirect&bpo=28192]: Don’t import readline in isolated mode.

Upgrade internal unicode databases to Unicode version 9.0.0.

bpo-28131 [https://bugs.python.org/issue?@action=redirect&bpo=28131]: Fix a regression in zipimport’s compile_source(). zipimport should use the same optimization level as the interpreter.

bpo-28126 [https://bugs.python.org/issue?@action=redirect&bpo=28126]: Replace Py_MEMCPY with memcpy(). Visual Studio can properly optimize memcpy().

bpo-28120 [https://bugs.python.org/issue?@action=redirect&bpo=28120]: Fix dict.pop() for splitted dictionary when trying to remove a «pending key» (Not yet inserted in split-table). Patch by Xiang Zhang.

bpo-26182 [https://bugs.python.org/issue?@action=redirect&bpo=26182]: Raise DeprecationWarning when async and await keywords are used as variable/attribute/class/function name.

Library

bpo-27998 [https://bugs.python.org/issue?@action=redirect&bpo=27998]: Fixed bytes path support in os.scandir() on Windows. Patch by Eryk Sun.

bpo-28317 [https://bugs.python.org/issue?@action=redirect&bpo=28317]: The disassembler now decodes FORMAT_VALUE argument.

bpo-26293 [https://bugs.python.org/issue?@action=redirect&bpo=26293]: Fixed writing ZIP files that starts not from the start of the file. Offsets in ZIP file now are relative to the start of the archive in conforming to the specification.

bpo-28380 [https://bugs.python.org/issue?@action=redirect&bpo=28380]: unittest.mock Mock autospec functions now properly support assert_called, assert_not_called, and assert_called_once.

bpo-27181 [https://bugs.python.org/issue?@action=redirect&bpo=27181]: remove statistics.geometric_mean and defer until 3.7.

bpo-28229 [https://bugs.python.org/issue?@action=redirect&bpo=28229]: lzma module now supports pathlib.

bpo-28321 [https://bugs.python.org/issue?@action=redirect&bpo=28321]: Fixed writing non-BMP characters with binary format in plistlib.

bpo-28225 [https://bugs.python.org/issue?@action=redirect&bpo=28225]: bz2 module now supports pathlib. Initial patch by Ethan Furman.

bpo-28227 [https://bugs.python.org/issue?@action=redirect&bpo=28227]: gzip now supports pathlib. Patch by Ethan Furman.

bpo-27358 [https://bugs.python.org/issue?@action=redirect&bpo=27358]: Optimized merging var-keyword arguments and improved error message when passing a non-mapping as a var-keyword argument.

bpo-28257 [https://bugs.python.org/issue?@action=redirect&bpo=28257]: Improved error message when passing a non-iterable as a var-positional argument. Added opcode BUILD_TUPLE_UNPACK_WITH_CALL.

bpo-28322 [https://bugs.python.org/issue?@action=redirect&bpo=28322]: Fixed possible crashes when unpickle itertools objects from incorrect pickle data. Based on patch by John Leitch.

bpo-28228 [https://bugs.python.org/issue?@action=redirect&bpo=28228]: imghdr now supports pathlib.

bpo-28226 [https://bugs.python.org/issue?@action=redirect&bpo=28226]: compileall now supports pathlib.

bpo-28314 [https://bugs.python.org/issue?@action=redirect&bpo=28314]: Fix function declaration (C flags) for the getiterator() method of xml.etree.ElementTree.Element.

bpo-28148 [https://bugs.python.org/issue?@action=redirect&bpo=28148]: Stop using localtime() and gmtime() in the time module. Introduced platform independent _PyTime_localtime API that is similar to POSIX localtime_r, but available on all platforms. Patch by Ed Schouten.

bpo-28253 [https://bugs.python.org/issue?@action=redirect&bpo=28253]: Fixed calendar functions for extreme months: 0001-01 and 9999-12. Methods itermonthdays() and itermonthdays2() are reimplemented so that they don’t call itermonthdates() which can cause datetime.date under/overflow.

bpo-28275 [https://bugs.python.org/issue?@action=redirect&bpo=28275]: Fixed possible use after free in the decompress() methods of the LZMADecompressor and BZ2Decompressor classes. Original patch by John Leitch.

bpo-27897 [https://bugs.python.org/issue?@action=redirect&bpo=27897]: Fixed possible crash in sqlite3.Connection.create_collation() if pass invalid string-like object as a name. Patch by Xiang Zhang.

bpo-18844 [https://bugs.python.org/issue?@action=redirect&bpo=18844]: random.choices() now has k as a keyword-only argument to improve the readability of common cases and come into line with the signature used in other languages.

bpo-18893 [https://bugs.python.org/issue?@action=redirect&bpo=18893]: Fix invalid exception handling in Lib/ctypes/macholib/dyld.py. Patch by Madison May.

bpo-27611 [https://bugs.python.org/issue?@action=redirect&bpo=27611]: Fixed support of default root window in the tkinter.tix module. Added the master parameter in the DisplayStyle constructor.

bpo-27348 [https://bugs.python.org/issue?@action=redirect&bpo=27348]: In the traceback module, restore the formatting of exception messages like «Exception: None». This fixes a regression introduced in 3.5a2.

bpo-25651 [https://bugs.python.org/issue?@action=redirect&bpo=25651]: Allow falsy values to be used for msg parameter of subTest().

bpo-27778 [https://bugs.python.org/issue?@action=redirect&bpo=27778]: Fix a memory leak in os.getrandom() when the getrandom() is interrupted by a signal and a signal handler raises a Python exception.

bpo-28200 [https://bugs.python.org/issue?@action=redirect&bpo=28200]: Fix memory leak on Windows in the os module (fix path_converter() function).

bpo-25400 [https://bugs.python.org/issue?@action=redirect&bpo=25400]: RobotFileParser now correctly returns default values for crawl_delay and request_rate. Initial patch by Peter Wirtz.

bpo-27932 [https://bugs.python.org/issue?@action=redirect&bpo=27932]: Prevent memory leak in win32_ver().

Fix UnboundLocalError in socket._sendfile_use_sendfile.

bpo-28075 [https://bugs.python.org/issue?@action=redirect&bpo=28075]: Check for ERROR_ACCESS_DENIED in Windows implementation of os.stat(). Patch by Eryk Sun.

bpo-22493 [https://bugs.python.org/issue?@action=redirect&bpo=22493]: Warning message emitted by using inline flags in the middle of regular expression now contains a (truncated) regex pattern. Patch by Tim Graham.

bpo-25270 [https://bugs.python.org/issue?@action=redirect&bpo=25270]: Prevent codecs.escape_encode() from raising SystemError when an empty bytestring is passed.

bpo-28181 [https://bugs.python.org/issue?@action=redirect&bpo=28181]: Get antigravity over HTTPS. Patch by Kaartic Sivaraam.

bpo-25895 [https://bugs.python.org/issue?@action=redirect&bpo=25895]: Enable WebSocket URL schemes in urllib.parse.urljoin. Patch by Gergely Imreh and Markus Holtermann.

bpo-28114 [https://bugs.python.org/issue?@action=redirect&bpo=28114]: Fix a crash in parse_envlist() when env contains byte strings. Patch by Eryk Sun.

bpo-27599 [https://bugs.python.org/issue?@action=redirect&bpo=27599]: Fixed buffer overrun in binascii.b2a_qp() and binascii.a2b_qp().

bpo-27906 [https://bugs.python.org/issue?@action=redirect&bpo=27906]: Fix socket accept exhaustion during high TCP traffic. Patch by Kevin Conway.

bpo-28174 [https://bugs.python.org/issue?@action=redirect&bpo=28174]: Handle when SO_REUSEPORT isn’t properly supported. Patch by Seth Michael Larson.

bpo-26654 [https://bugs.python.org/issue?@action=redirect&bpo=26654]: Inspect functools.partial in asyncio.Handle.__repr__. Patch by iceboy.

bpo-26909 [https://bugs.python.org/issue?@action=redirect&bpo=26909]: Fix slow pipes IO in asyncio. Patch by INADA Naoki.

bpo-28176 [https://bugs.python.org/issue?@action=redirect&bpo=28176]: Fix callbacks race in asyncio.SelectorLoop.sock_connect.

bpo-27759 [https://bugs.python.org/issue?@action=redirect&bpo=27759]: Fix selectors incorrectly retain invalid file descriptors. Patch by Mark Williams.

bpo-28368 [https://bugs.python.org/issue?@action=redirect&bpo=28368]: Refuse monitoring processes if the child watcher has no loop attached. Patch by Vincent Michel.

bpo-28369 [https://bugs.python.org/issue?@action=redirect&bpo=28369]: Raise RuntimeError when transport’s FD is used with add_reader, add_writer, etc.

bpo-28370 [https://bugs.python.org/issue?@action=redirect&bpo=28370]: Speedup asyncio.StreamReader.readexactly. Patch by Коренберг Марк.

bpo-28371 [https://bugs.python.org/issue?@action=redirect&bpo=28371]: Deprecate passing asyncio.Handles to run_in_executor.

bpo-28372 [https://bugs.python.org/issue?@action=redirect&bpo=28372]: Fix asyncio to support formatting of non-python coroutines.

bpo-28399 [https://bugs.python.org/issue?@action=redirect&bpo=28399]: Remove UNIX socket from FS before binding. Patch by Коренберг Марк.

bpo-27972 [https://bugs.python.org/issue?@action=redirect&bpo=27972]: Prohibit Tasks to await on themselves.

Windows

bpo-28402 [https://bugs.python.org/issue?@action=redirect&bpo=28402]: Adds signed catalog files for stdlib on Windows.

bpo-28333 [https://bugs.python.org/issue?@action=redirect&bpo=28333]: Enables Unicode for ps1/ps2 and input() prompts. (Patch by Eryk Sun)

bpo-28251 [https://bugs.python.org/issue?@action=redirect&bpo=28251]: Improvements to help manuals on Windows.

bpo-28110 [https://bugs.python.org/issue?@action=redirect&bpo=28110]: launcher.msi has different product codes between 32-bit and 64-bit

bpo-28161 [https://bugs.python.org/issue?@action=redirect&bpo=28161]: Opening CON for write access fails

bpo-28162 [https://bugs.python.org/issue?@action=redirect&bpo=28162]: WindowsConsoleIO readall() fails if first line starts with Ctrl+Z

bpo-28163 [https://bugs.python.org/issue?@action=redirect&bpo=28163]: WindowsConsoleIO fileno() passes wrong flags to _open_osfhandle

bpo-28164 [https://bugs.python.org/issue?@action=redirect&bpo=28164]: _PyIO_get_console_type fails for various paths

bpo-28137 [https://bugs.python.org/issue?@action=redirect&bpo=28137]: Renames Windows path file to ._pth

bpo-28138 [https://bugs.python.org/issue?@action=redirect&bpo=28138]: Windows ._pth file should allow import site

C API

bpo-28426 [https://bugs.python.org/issue?@action=redirect&bpo=28426]: Deprecated undocumented functions PyUnicode_AsEncodedObject(), PyUnicode_AsDecodedObject(), PyUnicode_AsDecodedUnicode() and PyUnicode_AsEncodedUnicode().

Build

bpo-28258 [https://bugs.python.org/issue?@action=redirect&bpo=28258]: Fixed build with Estonian locale (python-config and distclean targets in Makefile). Patch by Arfrever Frehtes Taifersar Arahesis.

bpo-26661 [https://bugs.python.org/issue?@action=redirect&bpo=26661]: setup.py now detects system libffi with multiarch wrapper.

bpo-15819 [https://bugs.python.org/issue?@action=redirect&bpo=15819]: Remove redundant include search directory option for building outside the source tree.

Tests

bpo-28217 [https://bugs.python.org/issue?@action=redirect&bpo=28217]: Adds _testconsole module to test console input.

Python 3.6.0 beta 1

Release date: 2016-09-12

Core and Builtins

bpo-23722 [https://bugs.python.org/issue?@action=redirect&bpo=23722]: The __class__ cell used by zero-argument super() is now initialized from type.__new__ rather than __build_class__, so class methods relying on that will now work correctly when called from metaclass methods during class creation. Patch by Martin Teichmann.

bpo-25221 [https://bugs.python.org/issue?@action=redirect&bpo=25221]: Fix corrupted result from PyLong_FromLong(0) when Python is compiled with NSMALLPOSINTS = 0.

bpo-27080 [https://bugs.python.org/issue?@action=redirect&bpo=27080]: Implement formatting support for PEP 515 [https://www.python.org/dev/peps/pep-0515]. Initial patch by Chris Angelico.

bpo-27199 [https://bugs.python.org/issue?@action=redirect&bpo=27199]: In tarfile, expose copyfileobj bufsize to improve throughput. Patch by Jason Fried.

bpo-27948 [https://bugs.python.org/issue?@action=redirect&bpo=27948]: In f-strings, only allow backslashes inside the braces (where the expressions are). This is a breaking change from the 3.6 alpha releases, where backslashes are allowed anywhere in an f-string. Also, require that expressions inside f-strings be enclosed within literal braces, and not escapes like f'\x7b"hi"\x7d'.

bpo-28046 [https://bugs.python.org/issue?@action=redirect&bpo=28046]: Remove platform-specific directories from sys.path.

bpo-28071 [https://bugs.python.org/issue?@action=redirect&bpo=28071]: Add early-out for differencing from an empty set.

bpo-25758 [https://bugs.python.org/issue?@action=redirect&bpo=25758]: Prevents zipimport from unnecessarily encoding a filename (patch by Eryk Sun)

bpo-25856 [https://bugs.python.org/issue?@action=redirect&bpo=25856]: The __module__ attribute of extension classes and functions now is interned. This leads to more compact pickle data with protocol 4.

bpo-27213 [https://bugs.python.org/issue?@action=redirect&bpo=27213]: Rework CALL_FUNCTION* opcodes to produce shorter and more efficient bytecode. Patch by Demur Rumed, design by Serhiy Storchaka, reviewed by Serhiy Storchaka and Victor Stinner.

bpo-26331 [https://bugs.python.org/issue?@action=redirect&bpo=26331]: Implement tokenizing support for PEP 515 [https://www.python.org/dev/peps/pep-0515]. Patch by Georg Brandl.

bpo-27999 [https://bugs.python.org/issue?@action=redirect&bpo=27999]: Make «global after use» a SyntaxError, and ditto for nonlocal. Patch by Ivan Levkivskyi.

bpo-28003 [https://bugs.python.org/issue?@action=redirect&bpo=28003]: Implement PEP 525 [https://www.python.org/dev/peps/pep-0525] – Asynchronous Generators.

bpo-27985 [https://bugs.python.org/issue?@action=redirect&bpo=27985]: Implement PEP 526 [https://www.python.org/dev/peps/pep-0526] – Syntax for Variable Annotations. Patch by Ivan Levkivskyi.

bpo-26058 [https://bugs.python.org/issue?@action=redirect&bpo=26058]: Add a new private version to the builtin dict type, incremented at each dictionary creation and at each dictionary change. Implementation of the PEP 509.

bpo-27364 [https://bugs.python.org/issue?@action=redirect&bpo=27364]: A backslash-character pair that is not a valid escape sequence now generates a DeprecationWarning. Patch by Emanuel Barry.

bpo-27350 [https://bugs.python.org/issue?@action=redirect&bpo=27350]: dict implementation is changed like PyPy. It is more compact and preserves insertion order. (Concept developed by Raymond Hettinger and patch by Inada Naoki.)

bpo-27911 [https://bugs.python.org/issue?@action=redirect&bpo=27911]: Remove unnecessary error checks in exec_builtin_or_dynamic().

bpo-27078 [https://bugs.python.org/issue?@action=redirect&bpo=27078]: Added BUILD_STRING opcode. Optimized f-strings evaluation.

bpo-17884 [https://bugs.python.org/issue?@action=redirect&bpo=17884]: Python now requires systems with inttypes.h and stdint.h

bpo-27961 [https://bugs.python.org/issue?@action=redirect&bpo=27961]: Require platforms to support long long. Python hasn’t compiled without long long for years, so this is basically a formality.

bpo-27355 [https://bugs.python.org/issue?@action=redirect&bpo=27355]: Removed support for Windows CE. It was never finished, and Windows CE is no longer a relevant platform for Python.

Implement PEP 523 [https://www.python.org/dev/peps/pep-0523].

bpo-27870 [https://bugs.python.org/issue?@action=redirect&bpo=27870]: A left shift of zero by a large integer no longer attempts to allocate large amounts of memory.

bpo-25402 [https://bugs.python.org/issue?@action=redirect&bpo=25402]: In int-to-decimal-string conversion, improve the estimate of the intermediate memory required, and remove an unnecessarily strict overflow check. Patch by Serhiy Storchaka.

bpo-27214 [https://bugs.python.org/issue?@action=redirect&bpo=27214]: In long_invert, be more careful about modifying object returned by long_add, and remove an unnecessary check for small longs. Thanks Oren Milman for analysis and patch.

bpo-27506 [https://bugs.python.org/issue?@action=redirect&bpo=27506]: Support passing the bytes/bytearray.translate() «delete» argument by keyword.

bpo-27812 [https://bugs.python.org/issue?@action=redirect&bpo=27812]: Properly clear out a generator’s frame’s backreference to the generator to prevent crashes in frame.clear().

bpo-27811 [https://bugs.python.org/issue?@action=redirect&bpo=27811]: Fix a crash when a coroutine that has not been awaited is finalized with warnings-as-errors enabled.

bpo-27587 [https://bugs.python.org/issue?@action=redirect&bpo=27587]: Fix another issue found by PVS-Studio: Null pointer check after use of “def” in _PyState_AddModule(). Initial patch by Christian Heimes.

bpo-27792 [https://bugs.python.org/issue?@action=redirect&bpo=27792]: The modulo operation applied to bool and other int subclasses now always returns an int. Previously the return type depended on the input values. Patch by Xiang Zhang.

bpo-26984 [https://bugs.python.org/issue?@action=redirect&bpo=26984]: int() now always returns an instance of exact int.

bpo-25604 [https://bugs.python.org/issue?@action=redirect&bpo=25604]: Fix a minor bug in integer true division; this bug could potentially have caused off-by-one-ulp results on platforms with unreliable ldexp implementations.

bpo-24254 [https://bugs.python.org/issue?@action=redirect&bpo=24254]: Make class definition namespace ordered by default.

bpo-27662 [https://bugs.python.org/issue?@action=redirect&bpo=27662]: Fix an overflow check in List_New: the original code was checking against Py_SIZE_MAX instead of the correct upper bound of Py_SSIZE_T_MAX. Patch by Xiang Zhang.

bpo-27782 [https://bugs.python.org/issue?@action=redirect&bpo=27782]: Multi-phase extension module import now correctly allows the m_methods field to be used to add module level functions to instances of non-module types returned from Py_create_mod. Patch by Xiang Zhang.

bpo-27936 [https://bugs.python.org/issue?@action=redirect&bpo=27936]: The round() function accepted a second None argument for some types but not for others. Fixed the inconsistency by accepting None for all numeric types.

bpo-27487 [https://bugs.python.org/issue?@action=redirect&bpo=27487]: Warn if a submodule argument to «python -m» or runpy.run_module() is found in sys.modules after parent packages are imported, but before the submodule is executed.

bpo-27157 [https://bugs.python.org/issue?@action=redirect&bpo=27157]: Make only type() itself accept the one-argument form. Patch by Eryk Sun and Emanuel Barry.

bpo-27558 [https://bugs.python.org/issue?@action=redirect&bpo=27558]: Fix a SystemError in the implementation of «raise» statement. In a brand new thread, raise a RuntimeError since there is no active exception to reraise. Patch written by Xiang Zhang.

bpo-28008 [https://bugs.python.org/issue?@action=redirect&bpo=28008]: Implement PEP 530 [https://www.python.org/dev/peps/pep-0530] – asynchronous comprehensions.

bpo-27942 [https://bugs.python.org/issue?@action=redirect&bpo=27942]: Fix memory leak in codeobject.c

Library

bpo-28732 [https://bugs.python.org/issue?@action=redirect&bpo=28732]: Fix crash in os.spawnv() with no elements in args

bpo-28485 [https://bugs.python.org/issue?@action=redirect&bpo=28485]: Always raise ValueError for negative compileall.compile_dir(workers=…) parameter, even when multithreading is unavailable.

bpo-28037 [https://bugs.python.org/issue?@action=redirect&bpo=28037]: Use sqlite3_get_autocommit() instead of setting Connection->inTransaction manually.

bpo-25283 [https://bugs.python.org/issue?@action=redirect&bpo=25283]: Attributes tm_gmtoff and tm_zone are now available on all platforms in the return values of time.localtime() and time.gmtime().

bpo-24454 [https://bugs.python.org/issue?@action=redirect&bpo=24454]: Regular expression match object groups are now accessible using __getitem__. «mo[x]» is equivalent to «mo.group(x)».

bpo-10740 [https://bugs.python.org/issue?@action=redirect&bpo=10740]: sqlite3 no longer implicitly commit an open transaction before DDL statements.

bpo-17941 [https://bugs.python.org/issue?@action=redirect&bpo=17941]: Add a module parameter to collections.namedtuple().

bpo-22493 [https://bugs.python.org/issue?@action=redirect&bpo=22493]: Inline flags now should be used only at the start of the regular expression. Deprecation warning is emitted if uses them in the middle of the regular expression.

bpo-26885 [https://bugs.python.org/issue?@action=redirect&bpo=26885]: xmlrpc now supports unmarshalling additional data types used by Apache XML-RPC implementation for numerics and None.

bpo-28070 [https://bugs.python.org/issue?@action=redirect&bpo=28070]: Fixed parsing inline verbose flag in regular expressions.

bpo-19500 [https://bugs.python.org/issue?@action=redirect&bpo=19500]: Add client-side SSL session resumption to the ssl module.

bpo-28022 [https://bugs.python.org/issue?@action=redirect&bpo=28022]: Deprecate ssl-related arguments in favor of SSLContext. The deprecation include manual creation of SSLSocket and certfile/keyfile (or similar) in ftplib, httplib, imaplib, smtplib, poplib and urllib.

bpo-28043 [https://bugs.python.org/issue?@action=redirect&bpo=28043]: SSLContext has improved default settings: OP_NO_SSLv2, OP_NO_SSLv3, OP_NO_COMPRESSION, OP_CIPHER_SERVER_PREFERENCE, OP_SINGLE_DH_USE, OP_SINGLE_ECDH_USE and HIGH ciphers without MD5.

bpo-24693 [https://bugs.python.org/issue?@action=redirect&bpo=24693]: Changed some RuntimeError’s in the zipfile module to more appropriate types. Improved some error messages and debugging output.

bpo-17909 [https://bugs.python.org/issue?@action=redirect&bpo=17909]: json.load and json.loads now support binary input encoded as UTF-8, UTF-16 or UTF-32. Patch by Serhiy Storchaka.

bpo-27137 [https://bugs.python.org/issue?@action=redirect&bpo=27137]: the pure Python fallback implementation of functools.partial now matches the behaviour of its accelerated C counterpart for subclassing, pickling and text representation purposes. Patch by Emanuel Barry and Serhiy Storchaka.

Fix possible integer overflows and crashes in the mmap module with unusual usage patterns.

bpo-1703178 [https://bugs.python.org/issue?@action=redirect&bpo=1703178]: Fix the ability to pass the –link-objects option to the distutils build_ext command.

bpo-28019 [https://bugs.python.org/issue?@action=redirect&bpo=28019]: itertools.count() no longer rounds non-integer step in range between 1.0 and 2.0 to 1.

bpo-18401 [https://bugs.python.org/issue?@action=redirect&bpo=18401]: Pdb now supports the “readrc” keyword argument to control whether .pdbrc files should be read. Patch by Martin Matusiak and Sam Kimbrel.

bpo-25969 [https://bugs.python.org/issue?@action=redirect&bpo=25969]: Update the lib2to3 grammar to handle the unpacking generalizations added in 3.5.

bpo-14977 [https://bugs.python.org/issue?@action=redirect&bpo=14977]: mailcap now respects the order of the lines in the mailcap files («first match»), as required by RFC 1542. Patch by Michael Lazar.

bpo-28082 [https://bugs.python.org/issue?@action=redirect&bpo=28082]: Convert re flag constants to IntFlag.

bpo-28025 [https://bugs.python.org/issue?@action=redirect&bpo=28025]: Convert all ssl module constants to IntEnum and IntFlags. SSLContext properties now return flags and enums.

bpo-23591 [https://bugs.python.org/issue?@action=redirect&bpo=23591]: Add Flag, IntFlag, and auto() to enum module.

bpo-433028 [https://bugs.python.org/issue?@action=redirect&bpo=433028]: Added support of modifier spans in regular expressions.

bpo-24594 [https://bugs.python.org/issue?@action=redirect&bpo=24594]: Validates persist parameter when opening MSI database

bpo-17582 [https://bugs.python.org/issue?@action=redirect&bpo=17582]: xml.etree.ElementTree nows preserves whitespaces in attributes (Patch by Duane Griffin. Reviewed and approved by Stefan Behnel.)

bpo-28047 [https://bugs.python.org/issue?@action=redirect&bpo=28047]: Fixed calculation of line length used for the base64 CTE in the new email policies.

bpo-27576 [https://bugs.python.org/issue?@action=redirect&bpo=27576]: Fix call order in OrderedDict.__init__().

email.generator.DecodedGenerator now supports the policy keyword.

bpo-28027 [https://bugs.python.org/issue?@action=redirect&bpo=28027]: Remove undocumented modules from Lib/plat-*: IN, CDROM, DLFCN, TYPES, CDIO, and STROPTS.

bpo-27445 [https://bugs.python.org/issue?@action=redirect&bpo=27445]: Don’t pass str(_charset) to MIMEText.set_payload(). Patch by Claude Paroz.

bpo-24277 [https://bugs.python.org/issue?@action=redirect&bpo=24277]: The new email API is no longer provisional, and the docs have been reorganized and rewritten to emphasize the new API.

bpo-22450 [https://bugs.python.org/issue?@action=redirect&bpo=22450]: urllib now includes an Accept: */* header among the default headers. This makes the results of REST API requests more consistent and predictable especially when proxy servers are involved.

lib2to3.pgen3.driver.load_grammar() now creates a stable cache file between runs given the same Grammar.txt input regardless of the hash randomization setting.

bpo-28005 [https://bugs.python.org/issue?@action=redirect&bpo=28005]: Allow ImportErrors in encoding implementation to propagate.

bpo-26667 [https://bugs.python.org/issue?@action=redirect&bpo=26667]: Support path-like objects in importlib.util.

bpo-27570 [https://bugs.python.org/issue?@action=redirect&bpo=27570]: Avoid zero-length memcpy() etc calls with null source pointers in the «ctypes» and «array» modules.

bpo-22233 [https://bugs.python.org/issue?@action=redirect&bpo=22233]: Break email header lines only on the RFC specified CR and LF characters, not on arbitrary unicode line breaks. This also fixes a bug in HTTP header parsing.

bpo-27331 [https://bugs.python.org/issue?@action=redirect&bpo=27331]: The email.mime classes now all accept an optional policy keyword.

bpo-27988 [https://bugs.python.org/issue?@action=redirect&bpo=27988]: Fix email iter_attachments incorrect mutation of payload list.

bpo-16113 [https://bugs.python.org/issue?@action=redirect&bpo=16113]: Add SHA-3 and SHAKE support to hashlib module.

Eliminate a tautological-pointer-compare warning in _scproxy.c.

bpo-27776 [https://bugs.python.org/issue?@action=redirect&bpo=27776]: The os.urandom() function does now block on Linux 3.17 and newer until the system urandom entropy pool is initialized to increase the security. This change is part of the PEP 524 [https://www.python.org/dev/peps/pep-0524].

bpo-27778 [https://bugs.python.org/issue?@action=redirect&bpo=27778]: Expose the Linux getrandom() syscall as a new os.getrandom() function. This change is part of the PEP 524 [https://www.python.org/dev/peps/pep-0524].

bpo-27691 [https://bugs.python.org/issue?@action=redirect&bpo=27691]: Fix ssl module’s parsing of GEN_RID subject alternative name fields in X.509 certs.

bpo-18844 [https://bugs.python.org/issue?@action=redirect&bpo=18844]: Add random.choices().

bpo-25761 [https://bugs.python.org/issue?@action=redirect&bpo=25761]: Improved error reporting about truncated pickle data in C implementation of unpickler. UnpicklingError is now raised instead of AttributeError and ValueError in some cases.

bpo-26798 [https://bugs.python.org/issue?@action=redirect&bpo=26798]: Add BLAKE2 (blake2b and blake2s) to hashlib.

bpo-26032 [https://bugs.python.org/issue?@action=redirect&bpo=26032]: Optimized globbing in pathlib by using os.scandir(); it is now about 1.5–4 times faster.

bpo-25596 [https://bugs.python.org/issue?@action=redirect&bpo=25596]: Optimized glob() and iglob() functions in the glob module; they are now about 3–6 times faster.

bpo-27928 [https://bugs.python.org/issue?@action=redirect&bpo=27928]: Add scrypt (password-based key derivation function) to hashlib module (requires OpenSSL 1.1.0).

bpo-27850 [https://bugs.python.org/issue?@action=redirect&bpo=27850]: Remove 3DES from ssl module’s default cipher list to counter measure sweet32 attack (CVE-2016-2183).

bpo-27766 [https://bugs.python.org/issue?@action=redirect&bpo=27766]: Add ChaCha20 Poly1305 to ssl module’s default cipher list. (Required OpenSSL 1.1.0 or LibreSSL).

bpo-25387 [https://bugs.python.org/issue?@action=redirect&bpo=25387]: Check return value of winsound.MessageBeep.

bpo-27866 [https://bugs.python.org/issue?@action=redirect&bpo=27866]: Add SSLContext.get_ciphers() method to get a list of all enabled ciphers.

bpo-27744 [https://bugs.python.org/issue?@action=redirect&bpo=27744]: Add AF_ALG (Linux Kernel crypto) to socket module.

bpo-26470 [https://bugs.python.org/issue?@action=redirect&bpo=26470]: Port ssl and hashlib module to OpenSSL 1.1.0.

bpo-11620 [https://bugs.python.org/issue?@action=redirect&bpo=11620]: Fix support for SND_MEMORY in winsound.PlaySound. Based on a patch by Tim Lesher.

bpo-11734 [https://bugs.python.org/issue?@action=redirect&bpo=11734]: Add support for IEEE 754 half-precision floats to the struct module. Based on a patch by Eli Stevens.

bpo-27919 [https://bugs.python.org/issue?@action=redirect&bpo=27919]: Deprecated extra_path distribution option in distutils packaging.

bpo-23229 [https://bugs.python.org/issue?@action=redirect&bpo=23229]: Add new cmath constants: cmath.inf and cmath.nan to match math.inf and math.nan, and also cmath.infj and cmath.nanj to match the format used by complex repr.

bpo-27842 [https://bugs.python.org/issue?@action=redirect&bpo=27842]: The csv.DictReader now returns rows of type OrderedDict. (Contributed by Steve Holden.)

Remove support for passing a file descriptor to os.access. It never worked but previously didn’t raise.

bpo-12885 [https://bugs.python.org/issue?@action=redirect&bpo=12885]: Fix error when distutils encounters symlink.

bpo-27881 [https://bugs.python.org/issue?@action=redirect&bpo=27881]: Fixed possible bugs when setting sqlite3.Connection.isolation_level. Based on patch by Xiang Zhang.

bpo-27861 [https://bugs.python.org/issue?@action=redirect&bpo=27861]: Fixed a crash in sqlite3.Connection.cursor() when a factory creates not a cursor. Patch by Xiang Zhang.

bpo-19884 [https://bugs.python.org/issue?@action=redirect&bpo=19884]: Avoid spurious output on OS X with Gnu Readline.

bpo-27706 [https://bugs.python.org/issue?@action=redirect&bpo=27706]: Restore deterministic behavior of random.Random().seed() for string seeds using seeding version 1. Allows sequences of calls to random() to exactly match those obtained in Python 2. Patch by Nofar Schnider.

bpo-10513 [https://bugs.python.org/issue?@action=redirect&bpo=10513]: Fix a regression in Connection.commit(). Statements should not be reset after a commit.

bpo-12319 [https://bugs.python.org/issue?@action=redirect&bpo=12319]: Chunked transfer encoding support added to http.client.HTTPConnection requests. The urllib.request.AbstractHTTPHandler class does not enforce a Content-Length header any more. If a HTTP request has a file or iterable body, but no Content-Length header, the library now falls back to use chunked transfer-encoding.

A new version of typing.py from https://github.com/python/typing: - Collection (only for 3.6) (bpo-27598 [https://bugs.python.org/issue?@action=redirect&bpo=27598]) - Add FrozenSet to __all__ (upstream #261) - fix crash in _get_type_vars() (upstream #259) - Remove the dict constraint in ForwardRef._eval_type (upstream #252)

bpo-27832 [https://bugs.python.org/issue?@action=redirect&bpo=27832]: Make _normalize parameter to Fraction constructor keyword-only, so that Fraction(2, 3, 4) now raises TypeError.

bpo-27539 [https://bugs.python.org/issue?@action=redirect&bpo=27539]: Fix unnormalised Fraction.__pow__ result in the case of negative exponent and negative base.

bpo-21718 [https://bugs.python.org/issue?@action=redirect&bpo=21718]: cursor.description is now available for queries using CTEs.

bpo-27819 [https://bugs.python.org/issue?@action=redirect&bpo=27819]: In distutils sdists, simply produce the «gztar» (gzipped tar format) distributions on all platforms unless «formats» is supplied.

bpo-2466 [https://bugs.python.org/issue?@action=redirect&bpo=2466]: posixpath.ismount now correctly recognizes mount points which the user does not have permission to access.

bpo-9998 [https://bugs.python.org/issue?@action=redirect&bpo=9998]: On Linux, ctypes.util.find_library now looks in LD_LIBRARY_PATH for shared libraries.

bpo-27573 [https://bugs.python.org/issue?@action=redirect&bpo=27573]: exit message for code.interact is now configurable.

bpo-27930 [https://bugs.python.org/issue?@action=redirect&bpo=27930]: Improved behaviour of logging.handlers.QueueListener. Thanks to Paulo Andrade and Petr Viktorin for the analysis and patch.

bpo-6766 [https://bugs.python.org/issue?@action=redirect&bpo=6766]: Distributed reference counting added to multiprocessing to support nesting of shared values / proxy objects.

bpo-21201 [https://bugs.python.org/issue?@action=redirect&bpo=21201]: Improves readability of multiprocessing error message. Thanks to Wojciech Walczak for patch.

asyncio: Add set_protocol / get_protocol to Transports.

bpo-27456 [https://bugs.python.org/issue?@action=redirect&bpo=27456]: asyncio: Set TCP_NODELAY by default.

IDLE

bpo-15308 [https://bugs.python.org/issue?@action=redirect&bpo=15308]: Add “interrupt execution” (^C) to Shell menu. Patch by Roger Serwy, updated by Bayard Randel.

bpo-27922 [https://bugs.python.org/issue?@action=redirect&bpo=27922]: Stop IDLE tests from “flashing” gui widgets on the screen.

bpo-27891 [https://bugs.python.org/issue?@action=redirect&bpo=27891]: Consistently group and sort imports within idlelib modules.

bpo-17642 [https://bugs.python.org/issue?@action=redirect&bpo=17642]: add larger font sizes for classroom projection.

Add version to title of IDLE help window.

bpo-25564 [https://bugs.python.org/issue?@action=redirect&bpo=25564]: In section on IDLE – console differences, mention that using exec means that __builtins__ is defined for each statement.

bpo-27821 [https://bugs.python.org/issue?@action=redirect&bpo=27821]: Fix 3.6.0a3 regression that prevented custom key sets from being selected when no custom theme was defined.

C API

bpo-26900 [https://bugs.python.org/issue?@action=redirect&bpo=26900]: Excluded underscored names and other private API from limited API.

bpo-26027 [https://bugs.python.org/issue?@action=redirect&bpo=26027]: Add support for path-like objects in PyUnicode_FSConverter() & PyUnicode_FSDecoder().

Tests

bpo-27427 [https://bugs.python.org/issue?@action=redirect&bpo=27427]: Additional tests for the math module. Patch by Francisco Couzo.

bpo-27953 [https://bugs.python.org/issue?@action=redirect&bpo=27953]: Skip math and cmath tests that fail on OS X 10.4 due to a poor libm implementation of tan.

bpo-26040 [https://bugs.python.org/issue?@action=redirect&bpo=26040]: Improve test_math and test_cmath coverage and rigour. Patch by Jeff Allen.

bpo-27787 [https://bugs.python.org/issue?@action=redirect&bpo=27787]: Call gc.collect() before checking each test for «dangling threads», since the dangling threads are weak references.

Build

bpo-27566 [https://bugs.python.org/issue?@action=redirect&bpo=27566]: Fix clean target in freeze makefile (patch by Lisa Roach)

bpo-27705 [https://bugs.python.org/issue?@action=redirect&bpo=27705]: Update message in validate_ucrtbase.py

bpo-27976 [https://bugs.python.org/issue?@action=redirect&bpo=27976]: Deprecate building _ctypes with the bundled copy of libffi on non-OSX UNIX platforms.

bpo-27983 [https://bugs.python.org/issue?@action=redirect&bpo=27983]: Cause lack of llvm-profdata tool when using clang as required for PGO linking to be a configure time error rather than make time when --with-optimizations is enabled. Also improve our ability to find the llvm-profdata tool on MacOS and some Linuxes.

bpo-21590 [https://bugs.python.org/issue?@action=redirect&bpo=21590]: Support for DTrace and SystemTap probes.

bpo-26307 [https://bugs.python.org/issue?@action=redirect&bpo=26307]: The profile-opt build now applies PGO to the built-in modules.

bpo-26359 [https://bugs.python.org/issue?@action=redirect&bpo=26359]: Add the –with-optimizations flag to turn on LTO and PGO build support when available.

bpo-27917 [https://bugs.python.org/issue?@action=redirect&bpo=27917]: Set platform triplets for Android builds.

bpo-25825 [https://bugs.python.org/issue?@action=redirect&bpo=25825]: Update references to the $(LIBPL) installation path on AIX. This path was changed in 3.2a4.

Update OS X installer to use SQLite 3.14.1 and XZ 5.2.2.

bpo-21122 [https://bugs.python.org/issue?@action=redirect&bpo=21122]: Fix LTO builds on OS X.

bpo-17128 [https://bugs.python.org/issue?@action=redirect&bpo=17128]: Build OS X installer with a private copy of OpenSSL. Also provide a sample Install Certificates command script to install a set of root certificates from the third-party certifi module.

Tools/Demos

bpo-27952 [https://bugs.python.org/issue?@action=redirect&bpo=27952]: Get Tools/scripts/fixcid.py working with Python 3 and the current «re» module, avoid invalid Python backslash escapes, and fix a bug parsing escaped C quote signs.

Windows

bpo-28065 [https://bugs.python.org/issue?@action=redirect&bpo=28065]: Update xz dependency to 5.2.2 and build it from source.

bpo-25144 [https://bugs.python.org/issue?@action=redirect&bpo=25144]: Ensures TargetDir is set before continuing with custom install.

bpo-1602 [https://bugs.python.org/issue?@action=redirect&bpo=1602]: Windows console doesn’t input or print Unicode (PEP 528)

bpo-27781 [https://bugs.python.org/issue?@action=redirect&bpo=27781]: Change file system encoding on Windows to UTF-8 (PEP 529)

bpo-27731 [https://bugs.python.org/issue?@action=redirect&bpo=27731]: Opt-out of MAX_PATH on Windows 10

bpo-6135 [https://bugs.python.org/issue?@action=redirect&bpo=6135]: Adds encoding and errors parameters to subprocess.

bpo-27959 [https://bugs.python.org/issue?@action=redirect&bpo=27959]: Adds oem encoding, alias ansi to mbcs, move aliasmbcs to codec lookup.

bpo-27982 [https://bugs.python.org/issue?@action=redirect&bpo=27982]: The functions of the winsound module now accept keyword arguments.

bpo-20366 [https://bugs.python.org/issue?@action=redirect&bpo=20366]: Build full text search support into SQLite on Windows.

bpo-27756 [https://bugs.python.org/issue?@action=redirect&bpo=27756]: Adds new icons for Python files and processes on Windows. Designs by Cherry Wang.

bpo-27883 [https://bugs.python.org/issue?@action=redirect&bpo=27883]: Update sqlite to 3.14.1.0 on Windows.

Python 3.6.0 alpha 4

Release date: 2016-08-15

Core and Builtins

bpo-27704 [https://bugs.python.org/issue?@action=redirect&bpo=27704]: Optimized creating bytes and bytearray from byte-like objects and iterables. Speed up to 3 times for short objects. Original patch by Naoki Inada.

bpo-26823 [https://bugs.python.org/issue?@action=redirect&bpo=26823]: Large sections of repeated lines in tracebacks are now abbreviated as «[Previous line repeated {count} more times]» by the builtin traceback rendering. Patch by Emanuel Barry.

bpo-27574 [https://bugs.python.org/issue?@action=redirect&bpo=27574]: Decreased an overhead of parsing keyword arguments in functions implemented with using Argument Clinic.

bpo-22557 [https://bugs.python.org/issue?@action=redirect&bpo=22557]: Now importing already imported modules is up to 2.5 times faster.

bpo-17596 [https://bugs.python.org/issue?@action=redirect&bpo=17596]: Include <wincrypt.h> to help with Min GW building.

bpo-17599 [https://bugs.python.org/issue?@action=redirect&bpo=17599]: On Windows, rename the privately defined REPARSE_DATA_BUFFER structure to avoid conflicting with the definition from Min GW.

bpo-27507 [https://bugs.python.org/issue?@action=redirect&bpo=27507]: Add integer overflow check in bytearray.extend(). Patch by Xiang Zhang.

bpo-27581 [https://bugs.python.org/issue?@action=redirect&bpo=27581]: Don’t rely on wrapping for overflow check in PySequence_Tuple(). Patch by Xiang Zhang.

bpo-1621 [https://bugs.python.org/issue?@action=redirect&bpo=1621]: Avoid signed integer overflow in list and tuple operations. Patch by Xiang Zhang.

bpo-27419 [https://bugs.python.org/issue?@action=redirect&bpo=27419]: Standard __import__() no longer look up «__import__» in globals or builtins for importing submodules or «from import». Fixed a crash if raise a warning about unabling to resolve package from __spec__ or __package__.

bpo-27083 [https://bugs.python.org/issue?@action=redirect&bpo=27083]: Respect the PYTHONCASEOK environment variable under Windows.

bpo-27514 [https://bugs.python.org/issue?@action=redirect&bpo=27514]: Make having too many statically nested blocks a SyntaxError instead of SystemError.

bpo-27366 [https://bugs.python.org/issue?@action=redirect&bpo=27366]: Implemented PEP 487 [https://www.python.org/dev/peps/pep-0487] (Simpler customization of class creation). Upon subclassing, the __init_subclass__ classmethod is called on the base class. Descriptors are initialized with __set_name__ after class creation.

Library

bpo-26027 [https://bugs.python.org/issue?@action=redirect&bpo=26027]: Add PEP 519 [https://www.python.org/dev/peps/pep-0519]/__fspath__() support to the os and os.path modules. Includes code from Jelle Zijlstra. (See also: bpo-27524 [https://bugs.python.org/issue?@action=redirect&bpo=27524])

bpo-27598 [https://bugs.python.org/issue?@action=redirect&bpo=27598]: Add Collections to collections.abc. Patch by Ivan Levkivskyi, docs by Neil Girdhar.

bpo-25958 [https://bugs.python.org/issue?@action=redirect&bpo=25958]: Support «anti-registration» of special methods from various ABCs, like __hash__, __iter__ or __len__. All these (and several more) can be set to None in an implementation class and the behavior will be as if the method is not defined at all. (Previously, this mechanism existed only for __hash__, to make mutable classes unhashable.) Code contributed by Andrew Barnert and Ivan Levkivskyi.

bpo-16764 [https://bugs.python.org/issue?@action=redirect&bpo=16764]: Support keyword arguments to zlib.decompress(). Patch by Xiang Zhang.

bpo-27736 [https://bugs.python.org/issue?@action=redirect&bpo=27736]: Prevent segfault after interpreter re-initialization due to ref count problem introduced in code for bpo-27038 [https://bugs.python.org/issue?@action=redirect&bpo=27038] in 3.6.0a3. Patch by Xiang Zhang.

bpo-25628 [https://bugs.python.org/issue?@action=redirect&bpo=25628]: The verbose and rename parameters for collections.namedtuple are now keyword-only.

bpo-12345 [https://bugs.python.org/issue?@action=redirect&bpo=12345]: Add mathematical constant tau to math and cmath. See also PEP 628 [https://www.python.org/dev/peps/pep-0628].

bpo-26823 [https://bugs.python.org/issue?@action=redirect&bpo=26823]: traceback.StackSummary.format now abbreviates large sections of repeated lines as «[Previous line repeated {count} more times]» (this change then further affects other traceback display operations in the module). Patch by Emanuel Barry.

bpo-27664 [https://bugs.python.org/issue?@action=redirect&bpo=27664]: Add to concurrent.futures.thread.ThreadPoolExecutor() the ability to specify a thread name prefix.

bpo-27181 [https://bugs.python.org/issue?@action=redirect&bpo=27181]: Add geometric_mean and harmonic_mean to statistics module.

bpo-27573 [https://bugs.python.org/issue?@action=redirect&bpo=27573]: code.interact now prints an message when exiting.

bpo-6422 [https://bugs.python.org/issue?@action=redirect&bpo=6422]: Add autorange method to timeit.Timer objects.

bpo-27773 [https://bugs.python.org/issue?@action=redirect&bpo=27773]: Correct some memory management errors server_hostname in _ssl.wrap_socket().

bpo-26750 [https://bugs.python.org/issue?@action=redirect&bpo=26750]: unittest.mock.create_autospec() now works properly for subclasses of property() and other data descriptors. Removes the never publicly used, never documented unittest.mock.DescriptorTypes tuple.

bpo-26754 [https://bugs.python.org/issue?@action=redirect&bpo=26754]: Undocumented support of general bytes-like objects as path in compile() and similar functions is now deprecated.

bpo-26800 [https://bugs.python.org/issue?@action=redirect&bpo=26800]: Undocumented support of general bytes-like objects as paths in os functions is now deprecated.

bpo-26981 [https://bugs.python.org/issue?@action=redirect&bpo=26981]: Add _order_ compatibility shim to enum.Enum for Python 2/3 code bases.

bpo-27661 [https://bugs.python.org/issue?@action=redirect&bpo=27661]: Added tzinfo keyword argument to datetime.combine.

In the curses module, raise an error if window.getstr() or window.instr() is passed a negative value.

bpo-27783 [https://bugs.python.org/issue?@action=redirect&bpo=27783]: Fix possible usage of uninitialized memory in operator.methodcaller.

bpo-27774 [https://bugs.python.org/issue?@action=redirect&bpo=27774]: Fix possible Py_DECREF on unowned object in _sre.

bpo-27760 [https://bugs.python.org/issue?@action=redirect&bpo=27760]: Fix possible integer overflow in binascii.b2a_qp.

bpo-27758 [https://bugs.python.org/issue?@action=redirect&bpo=27758]: Fix possible integer overflow in the _csv module for large record lengths.

bpo-27568 [https://bugs.python.org/issue?@action=redirect&bpo=27568]: Prevent HTTPoxy attack (CVE-2016-1000110). Ignore the HTTP_PROXY variable when REQUEST_METHOD environment is set, which indicates that the script is in CGI mode.

bpo-7063 [https://bugs.python.org/issue?@action=redirect&bpo=7063]: Remove dead code from the «array» module’s slice handling. Patch by Chuck.

bpo-27656 [https://bugs.python.org/issue?@action=redirect&bpo=27656]: Do not assume sched.h defines any SCHED_* constants.

bpo-27130 [https://bugs.python.org/issue?@action=redirect&bpo=27130]: In the «zlib» module, fix handling of large buffers (typically 4 GiB) when compressing and decompressing. Previously, inputs were limited to 4 GiB, and compression and decompression operations did not properly handle results of 4 GiB.

bpo-24773 [https://bugs.python.org/issue?@action=redirect&bpo=24773]: Implemented PEP 495 [https://www.python.org/dev/peps/pep-0495] (Local Time Disambiguation).

Expose the EPOLLEXCLUSIVE constant (when it is defined) in the select module.

bpo-27567 [https://bugs.python.org/issue?@action=redirect&bpo=27567]: Expose the EPOLLRDHUP and POLLRDHUP constants in the select module.

bpo-1621 [https://bugs.python.org/issue?@action=redirect&bpo=1621]: Avoid signed int negation overflow in the «audioop» module.

bpo-27533 [https://bugs.python.org/issue?@action=redirect&bpo=27533]: Release GIL in nt._isdir

bpo-17711 [https://bugs.python.org/issue?@action=redirect&bpo=17711]: Fixed unpickling by the persistent ID with protocol 0. Original patch by Alexandre Vassalotti.

bpo-27522 [https://bugs.python.org/issue?@action=redirect&bpo=27522]: Avoid an unintentional reference cycle in email.feedparser.

bpo-27512 [https://bugs.python.org/issue?@action=redirect&bpo=27512]: Fix a segfault when os.fspath() called an __fspath__() method that raised an exception. Patch by Xiang Zhang.

IDLE

bpo-27714 [https://bugs.python.org/issue?@action=redirect&bpo=27714]: text_textview and test_autocomplete now pass when re-run in the same process. This occurs when test_idle fails when run with the -w option but without -jn. Fix warning from test_config.

bpo-27621 [https://bugs.python.org/issue?@action=redirect&bpo=27621]: Put query response validation error messages in the query box itself instead of in a separate messagebox. Redo tests to match. Add Mac OSX refinements. Original patch by Mark Roseman.

bpo-27620 [https://bugs.python.org/issue?@action=redirect&bpo=27620]: Escape key now closes Query box as cancelled.

bpo-27609 [https://bugs.python.org/issue?@action=redirect&bpo=27609]: IDLE: tab after initial whitespace should tab, not autocomplete. This fixes problem with writing docstrings at least twice indented.

bpo-27609 [https://bugs.python.org/issue?@action=redirect&bpo=27609]: Explicitly return None when there are also non-None returns. In a few cases, reverse a condition and eliminate a return.

bpo-25507 [https://bugs.python.org/issue?@action=redirect&bpo=25507]: IDLE no longer runs buggy code because of its tkinter imports. Users must include the same imports required to run directly in Python.

bpo-27173 [https://bugs.python.org/issue?@action=redirect&bpo=27173]: Add “IDLE Modern Unix” to the built-in key sets. Make the default key set depend on the platform. Add tests for the changes to the config module.

bpo-27452 [https://bugs.python.org/issue?@action=redirect&bpo=27452]: add line counter and crc to IDLE configHandler test dump.

Tests

bpo-25805 [https://bugs.python.org/issue?@action=redirect&bpo=25805]: Skip a test in test_pkgutil as needed that doesn’t work when __name__ == __main__. Patch by SilentGhost.

bpo-27472 [https://bugs.python.org/issue?@action=redirect&bpo=27472]: Add test.support.unix_shell as the path to the default shell.

bpo-27369 [https://bugs.python.org/issue?@action=redirect&bpo=27369]: In test_pyexpat, avoid testing an error message detail that changed in Expat 2.2.0.

bpo-27594 [https://bugs.python.org/issue?@action=redirect&bpo=27594]: Prevent assertion error when running test_ast with coverage enabled: ensure code object has a valid first line number. Patch suggested by Ivan Levkivskyi.

Windows

bpo-27647 [https://bugs.python.org/issue?@action=redirect&bpo=27647]: Update bundled Tcl/Tk to 8.6.6.

bpo-27610 [https://bugs.python.org/issue?@action=redirect&bpo=27610]: Adds PEP 514 [https://www.python.org/dev/peps/pep-0514] metadata to Windows installer

bpo-27469 [https://bugs.python.org/issue?@action=redirect&bpo=27469]: Adds a shell extension to the launcher so that drag and drop works correctly.

bpo-27309 [https://bugs.python.org/issue?@action=redirect&bpo=27309]: Enables proper Windows styles in python[w].exe manifest.

Build

bpo-27713 [https://bugs.python.org/issue?@action=redirect&bpo=27713]: Suppress spurious build warnings when updating importlib’s bootstrap files. Patch by Xiang Zhang

bpo-25825 [https://bugs.python.org/issue?@action=redirect&bpo=25825]: Correct the references to Modules/python.exp, which is required on AIX. The references were accidentally changed in 3.5.0a1.

bpo-27453 [https://bugs.python.org/issue?@action=redirect&bpo=27453]: CPP invocation in configure must use CPPFLAGS. Patch by Chi Hsuan Yen.

bpo-27641 [https://bugs.python.org/issue?@action=redirect&bpo=27641]: The configure script now inserts comments into the makefile to prevent the pgen and _freeze_importlib executables from being cross-compiled.

bpo-26662 [https://bugs.python.org/issue?@action=redirect&bpo=26662]: Set PYTHON_FOR_GEN in configure as the Python program to be used for file generation during the build.

bpo-10910 [https://bugs.python.org/issue?@action=redirect&bpo=10910]: Avoid C++ compilation errors on FreeBSD and OS X. Also update FreedBSD version checks for the original ctype UTF-8 workaround.

Python 3.6.0 alpha 3

Release date: 2016-07-11

Security

bpo-27278 [https://bugs.python.org/issue?@action=redirect&bpo=27278]: Fix os.urandom() implementation using getrandom() on Linux. Truncate size to INT_MAX and loop until we collected enough random bytes, instead of casting a directly Py_ssize_t to int.

bpo-22636 [https://bugs.python.org/issue?@action=redirect&bpo=22636]: Avoid shell injection problems with ctypes.util.find_library().

Core and Builtins

bpo-27473 [https://bugs.python.org/issue?@action=redirect&bpo=27473]: Fixed possible integer overflow in bytes and bytearray concatenations. Patch by Xiang Zhang.

bpo-23034 [https://bugs.python.org/issue?@action=redirect&bpo=23034]: The output of a special Python build with defined COUNT_ALLOCS, SHOW_ALLOC_COUNT or SHOW_TRACK_COUNT macros is now off by default. It can be re-enabled using the «-X showalloccount» option. It now outputs to stderr instead of stdout.

bpo-27443 [https://bugs.python.org/issue?@action=redirect&bpo=27443]: __length_hint__() of bytearray iterators no longer return a negative integer for a resized bytearray.

bpo-27007 [https://bugs.python.org/issue?@action=redirect&bpo=27007]: The fromhex() class methods of bytes and bytearray subclasses now return an instance of corresponding subclass.

Library

bpo-26844 [https://bugs.python.org/issue?@action=redirect&bpo=26844]: Fix error message for imp.find_module() to refer to “path” instead of “name”. Patch by Lev Maximov.

bpo-23804 [https://bugs.python.org/issue?@action=redirect&bpo=23804]: Fix SSL zero-length recv() calls to not block and not raise an error about unclean EOF.

bpo-27466 [https://bugs.python.org/issue?@action=redirect&bpo=27466]: Change time format returned by http.cookie.time2netscape, confirming the netscape cookie format and making it consistent with documentation.

bpo-21708 [https://bugs.python.org/issue?@action=redirect&bpo=21708]: Deprecated dbm.dumb behavior that differs from common dbm behavior: creating a database in “r” and “w” modes and modifying a database in “r” mode.

bpo-26721 [https://bugs.python.org/issue?@action=redirect&bpo=26721]: Change the socketserver.StreamRequestHandler.wfile attribute to implement BufferedIOBase. In particular, the write() method no longer does partial writes.

bpo-22115 [https://bugs.python.org/issue?@action=redirect&bpo=22115]: Added methods trace_add, trace_remove and trace_info in the tkinter.Variable class. They replace old methods trace_variable, trace, trace_vdelete and trace_vinfo that use obsolete Tcl commands and might not work in future versions of Tcl. Fixed old tracing methods: trace_vdelete() with wrong mode no longer break tracing, trace_vinfo() now always returns a list of pairs of strings, tracing in the «u» mode now works.

bpo-26243 [https://bugs.python.org/issue?@action=redirect&bpo=26243]: Only the level argument to zlib.compress() is keyword argument now. The first argument is positional-only.

bpo-27038 [https://bugs.python.org/issue?@action=redirect&bpo=27038]: Expose the DirEntry type as os.DirEntry. Code patch by Jelle Zijlstra.

bpo-27186 [https://bugs.python.org/issue?@action=redirect&bpo=27186]: Update os.fspath()/PyOS_FSPath() to check the return value of __fspath__() to be either str or bytes.

bpo-18726 [https://bugs.python.org/issue?@action=redirect&bpo=18726]: All optional parameters of the dump(), dumps(), load() and loads() functions and JSONEncoder and JSONDecoder class constructors in the json module are now keyword-only.

bpo-27319 [https://bugs.python.org/issue?@action=redirect&bpo=27319]: Methods selection_set(), selection_add(), selection_remove() and selection_toggle() of ttk.TreeView now allow passing multiple items as multiple arguments instead of passing them as a tuple. Deprecated undocumented ability of calling the selection() method with arguments.

bpo-27079 [https://bugs.python.org/issue?@action=redirect&bpo=27079]: Fixed curses.ascii functions isblank(), iscntrl() and ispunct().

bpo-27294 [https://bugs.python.org/issue?@action=redirect&bpo=27294]: Numerical state in the repr for Tkinter event objects is now represented as a combination of known flags.

bpo-27177 [https://bugs.python.org/issue?@action=redirect&bpo=27177]: Match objects in the re module now support index-like objects as group indices. Based on patches by Jeroen Demeyer and Xiang Zhang.

bpo-26754 [https://bugs.python.org/issue?@action=redirect&bpo=26754]: Some functions (compile() etc) accepted a filename argument encoded as an iterable of integers. Now only strings and byte-like objects are accepted.

bpo-26536 [https://bugs.python.org/issue?@action=redirect&bpo=26536]: socket.ioctl now supports SIO_LOOPBACK_FAST_PATH. Patch by Daniel Stokes.

bpo-27048 [https://bugs.python.org/issue?@action=redirect&bpo=27048]: Prevents distutils failing on Windows when environment variables contain non-ASCII characters

bpo-27330 [https://bugs.python.org/issue?@action=redirect&bpo=27330]: Fixed possible leaks in the ctypes module.

bpo-27238 [https://bugs.python.org/issue?@action=redirect&bpo=27238]: Got rid of bare excepts in the turtle module. Original patch by Jelle Zijlstra.

bpo-27122 [https://bugs.python.org/issue?@action=redirect&bpo=27122]: When an exception is raised within the context being managed by a contextlib.ExitStack() and one of the exit stack generators catches and raises it in a chain, do not re-raise the original exception when exiting, let the new chained one through. This avoids the PEP 479 [https://www.python.org/dev/peps/pep-0479] bug described in issue25782.

bpo-16864 [https://bugs.python.org/issue?@action=redirect&bpo=16864]: sqlite3.Cursor.lastrowid now supports REPLACE statement. Initial patch by Alex LordThorsen.

bpo-26386 [https://bugs.python.org/issue?@action=redirect&bpo=26386]: Fixed ttk.TreeView selection operations with item id’s containing spaces.

bpo-8637 [https://bugs.python.org/issue?@action=redirect&bpo=8637]: Honor a pager set by the env var MANPAGER (in preference to one set by the env var PAGER).

bpo-16182 [https://bugs.python.org/issue?@action=redirect&bpo=16182]: Fix various functions in the «readline» module to use the locale encoding, and fix get_begidx() and get_endidx() to return code point indexes.

bpo-27392 [https://bugs.python.org/issue?@action=redirect&bpo=27392]: Add loop.connect_accepted_socket(). Patch by Jim Fulton.

IDLE

bpo-27477 [https://bugs.python.org/issue?@action=redirect&bpo=27477]: IDLE search dialogs now use ttk widgets.

bpo-27173 [https://bugs.python.org/issue?@action=redirect&bpo=27173]: Add “IDLE Modern Unix” to the built-in key sets. Make the default key set depend on the platform. Add tests for the changes to the config module.

bpo-27452 [https://bugs.python.org/issue?@action=redirect&bpo=27452]: make command line «idle-test> python test_help.py» work. __file__ is relative when python is started in the file’s directory.

bpo-27452 [https://bugs.python.org/issue?@action=redirect&bpo=27452]: add line counter and crc to IDLE configHandler test dump.

bpo-27380 [https://bugs.python.org/issue?@action=redirect&bpo=27380]: IDLE: add query.py with base Query dialog and ttk widgets. Module had subclasses SectionName, ModuleName, and HelpSource, which are used to get information from users by configdialog and file =>Load Module. Each subclass has itw own validity checks. Using ModuleName allows users to edit bad module names instead of starting over. Add tests and delete the two files combined into the new one.

bpo-27372 [https://bugs.python.org/issue?@action=redirect&bpo=27372]: Test_idle no longer changes the locale.

bpo-27365 [https://bugs.python.org/issue?@action=redirect&bpo=27365]: Allow non-ascii chars in IDLE NEWS.txt, for contributor names.

bpo-27245 [https://bugs.python.org/issue?@action=redirect&bpo=27245]: IDLE: Cleanly delete custom themes and key bindings. Previously, when IDLE was started from a console or by import, a cascade of warnings was emitted. Patch by Serhiy Storchaka.

bpo-24137 [https://bugs.python.org/issue?@action=redirect&bpo=24137]: Run IDLE, test_idle, and htest with tkinter default root disabled. Fix code and tests that fail with this restriction. Fix htests to not create a second and redundant root and mainloop.

bpo-27310 [https://bugs.python.org/issue?@action=redirect&bpo=27310]: Fix IDLE.app failure to launch on OS X due to vestigial import.

C API

bpo-26754 [https://bugs.python.org/issue?@action=redirect&bpo=26754]: PyUnicode_FSDecoder() accepted a filename argument encoded as an iterable of integers. Now only strings and byte-like objects are accepted.

Build

bpo-28066 [https://bugs.python.org/issue?@action=redirect&bpo=28066]: Fix the logic that searches build directories for generated include files when building outside the source tree.

bpo-27442 [https://bugs.python.org/issue?@action=redirect&bpo=27442]: Expose the Android API level that python was built against, in sysconfig.get_config_vars() as “ANDROID_API_LEVEL”.

bpo-27434 [https://bugs.python.org/issue?@action=redirect&bpo=27434]: The interpreter that runs the cross-build, found in PATH, must now be of the same feature version (e.g. 3.6) as the source being built.

bpo-26930 [https://bugs.python.org/issue?@action=redirect&bpo=26930]: Update Windows builds to use OpenSSL 1.0.2h.

bpo-23968 [https://bugs.python.org/issue?@action=redirect&bpo=23968]: Rename the platform directory from plat-$(MACHDEP) to plat-$(PLATFORM_TRIPLET). Rename the config directory (LIBPL) from config-$(LDVERSION) to config-$(LDVERSION)-$(PLATFORM_TRIPLET). Install the platform specific _sysconfigdata module into the platform directory and rename it to include the ABIFLAGS.

Don’t use largefile support for GNU/Hurd.

Tools/Demos

bpo-27332 [https://bugs.python.org/issue?@action=redirect&bpo=27332]: Fixed the type of the first argument of module-level functions generated by Argument Clinic. Patch by Petr Viktorin.

bpo-27418 [https://bugs.python.org/issue?@action=redirect&bpo=27418]: Fixed Tools/importbench/importbench.py.

Documentation

bpo-19489 [https://bugs.python.org/issue?@action=redirect&bpo=19489]: Moved the search box from the sidebar to the header and footer of each page. Patch by Ammar Askar.

bpo-27285 [https://bugs.python.org/issue?@action=redirect&bpo=27285]: Update documentation to reflect the deprecation of pyvenv and normalize on the term «virtual environment». Patch by Steve Piercy.

Tests

bpo-27027 [https://bugs.python.org/issue?@action=redirect&bpo=27027]: Added test.support.is_android that is True when this is an Android build.

Python 3.6.0 alpha 2

Release date: 2016-06-13

Security

bpo-26556 [https://bugs.python.org/issue?@action=redirect&bpo=26556]: Update expat to 2.1.1, fixes CVE-2015-1283.

Fix TLS stripping vulnerability in smtplib, CVE-2016-0772. Reported by Team Oststrom.

bpo-26839 [https://bugs.python.org/issue?@action=redirect&bpo=26839]: On Linux, os.urandom() now calls getrandom() with GRND_NONBLOCK to fall back on reading /dev/urandom if the urandom entropy pool is not initialized yet. Patch written by Colm Buckley.

Core and Builtins

bpo-27095 [https://bugs.python.org/issue?@action=redirect&bpo=27095]: Simplified MAKE_FUNCTION and removed MAKE_CLOSURE opcodes. Patch by Demur Rumed.

bpo-27190 [https://bugs.python.org/issue?@action=redirect&bpo=27190]: Raise NotSupportedError if sqlite3 is older than 3.3.1. Patch by Dave Sawyer.

bpo-27286 [https://bugs.python.org/issue?@action=redirect&bpo=27286]: Fixed compiling BUILD_MAP_UNPACK_WITH_CALL opcode. Calling function with generalized unpacking (PEP 448) and conflicting keyword names could cause undefined behavior.

bpo-27140 [https://bugs.python.org/issue?@action=redirect&bpo=27140]: Added BUILD_CONST_KEY_MAP opcode.

bpo-27186 [https://bugs.python.org/issue?@action=redirect&bpo=27186]: Add support for os.PathLike objects to open() (part of PEP 519 [https://www.python.org/dev/peps/pep-0519]).

bpo-27066 [https://bugs.python.org/issue?@action=redirect&bpo=27066]: Fixed SystemError if a custom opener (for open()) returns a negative number without setting an exception.

bpo-26983 [https://bugs.python.org/issue?@action=redirect&bpo=26983]: float() now always return an instance of exact float. The deprecation warning is emitted if __float__ returns an instance of a strict subclass of float. In a future versions of Python this can be an error.

bpo-27097 [https://bugs.python.org/issue?@action=redirect&bpo=27097]: Python interpreter is now about 7% faster due to optimized instruction decoding. Based on patch by Demur Rumed.

bpo-26647 [https://bugs.python.org/issue?@action=redirect&bpo=26647]: Python interpreter now uses 16-bit wordcode instead of bytecode. Patch by Demur Rumed.

bpo-23275 [https://bugs.python.org/issue?@action=redirect&bpo=23275]: Allow assigning to an empty target list in round brackets: () = iterable.

bpo-27243 [https://bugs.python.org/issue?@action=redirect&bpo=27243]: Update the __aiter__ protocol: instead of returning an awaitable that resolves to an asynchronous iterator, the asynchronous iterator should be returned directly. Doing the former will trigger a PendingDeprecationWarning.

Library

Comment out socket (SO_REUSEPORT) and posix (O_SHLOCK, O_EXLOCK) constants exposed on the API which are not implemented on GNU/Hurd. They would not work at runtime anyway.

bpo-27025 [https://bugs.python.org/issue?@action=redirect&bpo=27025]: Generated names for Tkinter widgets are now more meaningful and recognizable.

bpo-25455 [https://bugs.python.org/issue?@action=redirect&bpo=25455]: Fixed crashes in repr of recursive ElementTree.Element and functools.partial objects.

bpo-27294 [https://bugs.python.org/issue?@action=redirect&bpo=27294]: Improved repr for Tkinter event objects.

bpo-20508 [https://bugs.python.org/issue?@action=redirect&bpo=20508]: Improve exception message of IPv{4,6}Network.__getitem__. Patch by Gareth Rees.

bpo-21386 [https://bugs.python.org/issue?@action=redirect&bpo=21386]: Implement missing IPv4Address.is_global property. It was documented since 07a5610bae9d. Initial patch by Roger Luethi.

bpo-27029 [https://bugs.python.org/issue?@action=redirect&bpo=27029]: Removed deprecated support of universal newlines mode from ZipFile.open().

bpo-27030 [https://bugs.python.org/issue?@action=redirect&bpo=27030]: Unknown escapes consisting of '\' and an ASCII letter in regular expressions now are errors. The re.LOCALE flag now can be used only with bytes patterns.

bpo-27186 [https://bugs.python.org/issue?@action=redirect&bpo=27186]: Add os.PathLike support to DirEntry (part of PEP 519 [https://www.python.org/dev/peps/pep-0519]). Initial patch by Jelle Zijlstra.

bpo-20900 [https://bugs.python.org/issue?@action=redirect&bpo=20900]: distutils register command now decodes HTTP responses correctly. Initial patch by ingrid.

bpo-27186 [https://bugs.python.org/issue?@action=redirect&bpo=27186]: Add os.PathLike support to pathlib, removing its provisional status (part of PEP 519). Initial patch by Dusty Phillips.

bpo-27186 [https://bugs.python.org/issue?@action=redirect&bpo=27186]: Add support for os.PathLike objects to os.fsencode() and os.fsdecode() (part of PEP 519 [https://www.python.org/dev/peps/pep-0519]).

bpo-27186 [https://bugs.python.org/issue?@action=redirect&bpo=27186]: Introduce os.PathLike and os.fspath() (part of PEP 519 [https://www.python.org/dev/peps/pep-0519]).

A new version of typing.py provides several new classes and features: @overload outside stubs, Reversible, DefaultDict, Text, ContextManager, Type[], NewType(), TYPE_CHECKING, and numerous bug fixes (note that some of the new features are not yet implemented in mypy or other static analyzers). Also classes for PEP 492 [https://www.python.org/dev/peps/pep-0492] (Awaitable, AsyncIterable, AsyncIterator) have been added (in fact they made it into 3.5.1 but were never mentioned).

bpo-25738 [https://bugs.python.org/issue?@action=redirect&bpo=25738]: Stop http.server.BaseHTTPRequestHandler.send_error() from sending a message body for 205 Reset Content. Also, don’t send Content header fields in responses that don’t have a body. Patch by Susumu Koshiba.

bpo-21313 [https://bugs.python.org/issue?@action=redirect&bpo=21313]: Fix the «platform» module to tolerate when sys.version contains truncated build information.

bpo-23883 [https://bugs.python.org/issue?@action=redirect&bpo=23883]: Added missing APIs to __all__ to match the documented APIs for the following modules: cgi, mailbox, mimetypes, plistlib and smtpd. Patches by Jacek Kołodziej.

bpo-27164 [https://bugs.python.org/issue?@action=redirect&bpo=27164]: In the zlib module, allow decompressing raw Deflate streams with a predefined zdict. Based on patch by Xiang Zhang.

bpo-24291 [https://bugs.python.org/issue?@action=redirect&bpo=24291]: Fix wsgiref.simple_server.WSGIRequestHandler to completely write data to the client. Previously it could do partial writes and truncate data. Also, wsgiref.handler.ServerHandler can now handle stdout doing partial writes, but this is deprecated.

bpo-21272 [https://bugs.python.org/issue?@action=redirect&bpo=21272]: Use _sysconfigdata.py to initialize distutils.sysconfig.

bpo-19611 [https://bugs.python.org/issue?@action=redirect&bpo=19611]: inspect now reports the implicit .0 parameters generated by the compiler for comprehension and generator expression scopes as if they were positional-only parameters called implicit0. Patch by Jelle Zijlstra.

bpo-26809 [https://bugs.python.org/issue?@action=redirect&bpo=26809]: Add __all__ to string. Patch by Emanuel Barry.

bpo-26373 [https://bugs.python.org/issue?@action=redirect&bpo=26373]: subprocess.Popen.communicate now correctly ignores BrokenPipeError when the child process dies before .communicate() is called in more/all circumstances.

signal, socket, and ssl module IntEnum constant name lookups now return a consistent name for values having multiple names. Ex: signal.Signals(6) now refers to itself as signal.SIGALRM rather than flipping between that and signal.SIGIOT based on the interpreter’s hash randomization seed.

bpo-27167 [https://bugs.python.org/issue?@action=redirect&bpo=27167]: Clarify the subprocess.CalledProcessError error message text when the child process died due to a signal.

bpo-25931 [https://bugs.python.org/issue?@action=redirect&bpo=25931]: Don’t define socketserver.Forking* names on platforms such as Windows that do not support os.fork().

bpo-21776 [https://bugs.python.org/issue?@action=redirect&bpo=21776]: distutils.upload now correctly handles HTTPError. Initial patch by Claudiu Popa.

bpo-26526 [https://bugs.python.org/issue?@action=redirect&bpo=26526]: Replace custom parse tree validation in the parser module with a simple DFA validator.

bpo-27114 [https://bugs.python.org/issue?@action=redirect&bpo=27114]: Fix SSLContext._load_windows_store_certs fails with PermissionError

bpo-18383 [https://bugs.python.org/issue?@action=redirect&bpo=18383]: Avoid creating duplicate filters when using filterwarnings and simplefilter. Based on patch by Alex Shkop.

bpo-23026 [https://bugs.python.org/issue?@action=redirect&bpo=23026]: winreg.QueryValueEx() now return an integer for REG_QWORD type.

bpo-26741 [https://bugs.python.org/issue?@action=redirect&bpo=26741]: subprocess.Popen destructor now emits a ResourceWarning warning if the child process is still running.

bpo-27056 [https://bugs.python.org/issue?@action=redirect&bpo=27056]: Optimize pickle.load() and pickle.loads(), up to 10% faster to deserialize a lot of small objects.

bpo-21271 [https://bugs.python.org/issue?@action=redirect&bpo=21271]: New keyword only parameters in reset_mock call.

IDLE

bpo-5124 [https://bugs.python.org/issue?@action=redirect&bpo=5124]: Paste with text selected now replaces the selection on X11. This matches how paste works on Windows, Mac, most modern Linux apps, and ttk widgets. Original patch by Serhiy Storchaka.

bpo-24750 [https://bugs.python.org/issue?@action=redirect&bpo=24750]: Switch all scrollbars in IDLE to ttk versions. Where needed, minimal tests are added to cover changes.

bpo-24759 [https://bugs.python.org/issue?@action=redirect&bpo=24759]: IDLE requires tk 8.5 and availability ttk widgets. Delete now unneeded tk version tests and code for older versions. Add test for IDLE syntax colorizer.

bpo-27239 [https://bugs.python.org/issue?@action=redirect&bpo=27239]: idlelib.macosx.isXyzTk functions initialize as needed.

bpo-27262 [https://bugs.python.org/issue?@action=redirect&bpo=27262]: move Aqua unbinding code, which enable context menus, to macosx.

bpo-24759 [https://bugs.python.org/issue?@action=redirect&bpo=24759]: Make clear in idlelib.idle_test.__init__ that the directory is a private implementation of test.test_idle and tool for maintainers.

bpo-27196 [https://bugs.python.org/issue?@action=redirect&bpo=27196]: Stop “ThemeChanged” warnings when running IDLE tests. These persisted after other warnings were suppressed in #20567. Apply Serhiy Storchaka’s update_idletasks solution to four test files. Record this additional advice in idle_test/README.txt

bpo-20567 [https://bugs.python.org/issue?@action=redirect&bpo=20567]: Revise idle_test/README.txt with advice about avoiding tk warning messages from tests. Apply advice to several IDLE tests.

bpo-24225 [https://bugs.python.org/issue?@action=redirect&bpo=24225]: Update idlelib/README.txt with new file names and event handlers.

bpo-27156 [https://bugs.python.org/issue?@action=redirect&bpo=27156]: Remove obsolete code not used by IDLE.

bpo-27117 [https://bugs.python.org/issue?@action=redirect&bpo=27117]: Make colorizer htest and turtledemo work with dark themes. Move code for configuring text widget colors to a new function.

bpo-24225 [https://bugs.python.org/issue?@action=redirect&bpo=24225]: Rename many idlelib/*.py and idle_test/test_*.py files. Edit files to replace old names with new names when the old name referred to the module rather than the class it contained. See the issue and IDLE section in What’s New in 3.6 for more.

bpo-26673 [https://bugs.python.org/issue?@action=redirect&bpo=26673]: When tk reports font size as 0, change to size 10. Such fonts on Linux prevented the configuration dialog from opening.

bpo-21939 [https://bugs.python.org/issue?@action=redirect&bpo=21939]: Add test for IDLE’s percolator. Original patch by Saimadhav Heblikar.

bpo-21676 [https://bugs.python.org/issue?@action=redirect&bpo=21676]: Add test for IDLE’s replace dialog. Original patch by Saimadhav Heblikar.

bpo-18410 [https://bugs.python.org/issue?@action=redirect&bpo=18410]: Add test for IDLE’s search dialog. Original patch by Westley Martínez.

bpo-21703 [https://bugs.python.org/issue?@action=redirect&bpo=21703]: Add test for undo delegator. Patch mostly by Saimadhav Heblikar .

bpo-27044 [https://bugs.python.org/issue?@action=redirect&bpo=27044]: Add ConfigDialog.remove_var_callbacks to stop memory leaks.

bpo-23977 [https://bugs.python.org/issue?@action=redirect&bpo=23977]: Add more asserts to test_delegator.

Documentation

bpo-16484 [https://bugs.python.org/issue?@action=redirect&bpo=16484]: Change the default PYTHONDOCS URL to «https:», and fix the resulting links to use lowercase. Patch by Sean Rodman, test by Kaushik Nadikuditi.

bpo-24136 [https://bugs.python.org/issue?@action=redirect&bpo=24136]: Document the new PEP 448 [https://www.python.org/dev/peps/pep-0448] unpacking syntax of 3.5.

bpo-22558 [https://bugs.python.org/issue?@action=redirect&bpo=22558]: Add remaining doc links to source code for Python-coded modules. Patch by Yoni Lavi.

Tests

bpo-25285 [https://bugs.python.org/issue?@action=redirect&bpo=25285]: regrtest now uses subprocesses when the -j1 command line option is used: each test file runs in a fresh child process. Before, the -j1 option was ignored.

bpo-25285 [https://bugs.python.org/issue?@action=redirect&bpo=25285]: Tools/buildbot/test.bat script now uses -j1 by default to run each test file in fresh child process.

Windows

bpo-27064 [https://bugs.python.org/issue?@action=redirect&bpo=27064]: The py.exe launcher now defaults to Python 3. The Windows launcher py.exe no longer prefers an installed Python 2 version over Python 3 by default when used interactively.

bpo-17500 [https://bugs.python.org/issue?@action=redirect&bpo=17500]: Remove unused and outdated icons. (See also: https://github.com/python/pythondotorg/issues/945)

Build

bpo-27229 [https://bugs.python.org/issue?@action=redirect&bpo=27229]: Fix the cross-compiling pgen rule for in-tree builds. Patch by Xavier de Gaye.

bpo-26930 [https://bugs.python.org/issue?@action=redirect&bpo=26930]: Update OS X 10.5+ 32-bit-only installer to build and link with OpenSSL 1.0.2h.

C API

bpo-27186 [https://bugs.python.org/issue?@action=redirect&bpo=27186]: Add the PyOS_FSPath() function (part of PEP 519 [https://www.python.org/dev/peps/pep-0519]).

bpo-26282 [https://bugs.python.org/issue?@action=redirect&bpo=26282]: PyArg_ParseTupleAndKeywords() now supports positional-only parameters.

Tools/Demos

bpo-26282 [https://bugs.python.org/issue?@action=redirect&bpo=26282]: Argument Clinic now supports positional-only and keyword parameters in the same function.

Python 3.6.0 alpha 1

Release date: 2016-05-16

Security

bpo-26657 [https://bugs.python.org/issue?@action=redirect&bpo=26657]: Fix directory traversal vulnerability with http.server on Windows. This fixes a regression that was introduced in 3.3.4rc1 and 3.4.0rc1. Based on patch by Philipp Hagemeister.

bpo-26313 [https://bugs.python.org/issue?@action=redirect&bpo=26313]: ssl.py _load_windows_store_certs fails if windows cert store is empty. Patch by Baji.

bpo-25939 [https://bugs.python.org/issue?@action=redirect&bpo=25939]: On Windows open the cert store readonly in ssl.enum_certificates.

Core and Builtins

bpo-20041 [https://bugs.python.org/issue?@action=redirect&bpo=20041]: Fixed TypeError when frame.f_trace is set to None. Patch by Xavier de Gaye.

bpo-26168 [https://bugs.python.org/issue?@action=redirect&bpo=26168]: Fixed possible refleaks in failing Py_BuildValue() with the «N» format unit.

bpo-26991 [https://bugs.python.org/issue?@action=redirect&bpo=26991]: Fix possible refleak when creating a function with annotations.

bpo-27039 [https://bugs.python.org/issue?@action=redirect&bpo=27039]: Fixed bytearray.remove() for values greater than 127. Based on patch by Joe Jevnik.

bpo-23640 [https://bugs.python.org/issue?@action=redirect&bpo=23640]: int.from_bytes() no longer bypasses constructors for subclasses.

bpo-27005 [https://bugs.python.org/issue?@action=redirect&bpo=27005]: Optimized the float.fromhex() class method for exact float. It is now 2 times faster.

bpo-18531 [https://bugs.python.org/issue?@action=redirect&bpo=18531]: Single var-keyword argument of dict subtype was passed unscathed to the C-defined function. Now it is converted to exact dict.

bpo-26811 [https://bugs.python.org/issue?@action=redirect&bpo=26811]: gc.get_objects() no longer contains a broken tuple with NULL pointer.

bpo-20120 [https://bugs.python.org/issue?@action=redirect&bpo=20120]: Use RawConfigParser for .pypirc parsing, removing support for interpolation unintentionally added with move to Python 3. Behavior no longer does any interpolation in .pypirc files, matching behavior in Python 2.7 and Setuptools 19.0.

bpo-26249 [https://bugs.python.org/issue?@action=redirect&bpo=26249]: Memory functions of the PyMem_Malloc() domain (PYMEM_DOMAIN_MEM) now use the pymalloc allocator rather than system malloc(). Applications calling PyMem_Malloc() without holding the GIL can now crash: use PYTHONMALLOC=debug environment variable to validate the usage of memory allocators in your application.

bpo-26802 [https://bugs.python.org/issue?@action=redirect&bpo=26802]: Optimize function calls only using unpacking like func(*tuple) (no other positional argument, no keyword): avoid copying the tuple. Patch written by Joe Jevnik.

bpo-26659 [https://bugs.python.org/issue?@action=redirect&bpo=26659]: Make the builtin slice type support cycle collection.

bpo-26718 [https://bugs.python.org/issue?@action=redirect&bpo=26718]: super.__init__ no longer leaks memory if called multiple times. NOTE: A direct call of super.__init__ is not endorsed!

bpo-27138 [https://bugs.python.org/issue?@action=redirect&bpo=27138]: Fix the doc comment for FileFinder.find_spec().

bpo-27147 [https://bugs.python.org/issue?@action=redirect&bpo=27147]: Mention PEP 420 [https://www.python.org/dev/peps/pep-0420] in the importlib docs.

bpo-25339 [https://bugs.python.org/issue?@action=redirect&bpo=25339]: PYTHONIOENCODING now has priority over locale in setting the error handler for stdin and stdout.

bpo-26494 [https://bugs.python.org/issue?@action=redirect&bpo=26494]: Fixed crash on iterating exhausting iterators. Affected classes are generic sequence iterators, iterators of str, bytes, bytearray, list, tuple, set, frozenset, dict, OrderedDict, corresponding views and os.scandir() iterator.

bpo-26574 [https://bugs.python.org/issue?@action=redirect&bpo=26574]: Optimize bytes.replace(b'', b'.') and bytearray.replace(b'', b'.'). Patch written by Josh Snider.

bpo-26581 [https://bugs.python.org/issue?@action=redirect&bpo=26581]: If coding cookie is specified multiple times on a line in Python source code file, only the first one is taken to account.

bpo-19711 [https://bugs.python.org/issue?@action=redirect&bpo=19711]: Add tests for reloading namespace packages.

bpo-21099 [https://bugs.python.org/issue?@action=redirect&bpo=21099]: Switch applicable importlib tests to use PEP 451 [https://www.python.org/dev/peps/pep-0451] API.

bpo-26563 [https://bugs.python.org/issue?@action=redirect&bpo=26563]: Debug hooks on Python memory allocators now raise a fatal error if functions of the PyMem_Malloc() family are called without holding the GIL.

bpo-26564 [https://bugs.python.org/issue?@action=redirect&bpo=26564]: On error, the debug hooks on Python memory allocators now use the tracemalloc module to get the traceback where a memory block was allocated.

bpo-26558 [https://bugs.python.org/issue?@action=redirect&bpo=26558]: The debug hooks on Python memory allocator PyObject_Malloc() now detect when functions are called without holding the GIL.

bpo-26516 [https://bugs.python.org/issue?@action=redirect&bpo=26516]: Add PYTHONMALLOC environment variable to set the Python memory allocators and/or install debug hooks.

bpo-26516 [https://bugs.python.org/issue?@action=redirect&bpo=26516]: The PyMem_SetupDebugHooks() function can now also be used on Python compiled in release mode.

bpo-26516 [https://bugs.python.org/issue?@action=redirect&bpo=26516]: The PYTHONMALLOCSTATS environment variable can now also be used on Python compiled in release mode. It now has no effect if set to an empty string.

bpo-26516 [https://bugs.python.org/issue?@action=redirect&bpo=26516]: In debug mode, debug hooks are now also installed on Python memory allocators when Python is configured without pymalloc.

bpo-26464 [https://bugs.python.org/issue?@action=redirect&bpo=26464]: Fix str.translate() when string is ASCII and first replacements removes character, but next replacement uses a non-ASCII character or a string longer than 1 character. Regression introduced in Python 3.5.0.

bpo-22836 [https://bugs.python.org/issue?@action=redirect&bpo=22836]: Ensure exception reports from PyErr_Display() and PyErr_WriteUnraisable() are sensible even when formatting them produces secondary errors. This affects the reports produced by sys.__excepthook__() and when __del__() raises an exception.

bpo-26302 [https://bugs.python.org/issue?@action=redirect&bpo=26302]: Correct behavior to reject comma as a legal character for cookie names.

bpo-26136 [https://bugs.python.org/issue?@action=redirect&bpo=26136]: Upgrade the warning when a generator raises StopIteration from PendingDeprecationWarning to DeprecationWarning. Patch by Anish Shah.

bpo-26204 [https://bugs.python.org/issue?@action=redirect&bpo=26204]: The compiler now ignores all constant statements: bytes, str, int, float, complex, name constants (None, False, True), Ellipsis and ast.Constant; not only str and int. For example, 1.0 is now ignored in def f(): 1.0.

bpo-4806 [https://bugs.python.org/issue?@action=redirect&bpo=4806]: Avoid masking the original TypeError exception when using star (*) unpacking in function calls. Based on patch by Hagen Fürstenau and Daniel Urban.

bpo-26146 [https://bugs.python.org/issue?@action=redirect&bpo=26146]: Add a new kind of AST node: ast.Constant. It can be used by external AST optimizers, but the compiler does not emit directly such node.

bpo-23601 [https://bugs.python.org/issue?@action=redirect&bpo=23601]: Sped-up allocation of dict key objects by using Python’s small object allocator. (Contributed by Julian Taylor.)

bpo-18018 [https://bugs.python.org/issue?@action=redirect&bpo=18018]: Import raises ImportError instead of SystemError if a relative import is attempted without a known parent package.

bpo-25843 [https://bugs.python.org/issue?@action=redirect&bpo=25843]: When compiling code, don’t merge constants if they are equal but have a different types. For example, f1, f2 = lambda: 1, lambda: 1.0 is now correctly compiled to two different functions: f1() returns 1 (int) and f2() returns 1.0 (float), even if 1 and 1.0 are equal.

bpo-26107 [https://bugs.python.org/issue?@action=redirect&bpo=26107]: The format of the co_lnotab attribute of code objects changes to support negative line number delta.

bpo-26154 [https://bugs.python.org/issue?@action=redirect&bpo=26154]: Add a new private _PyThreadState_UncheckedGet() function to get the current Python thread state, but don’t issue a fatal error if it is NULL. This new function must be used instead of accessing directly the _PyThreadState_Current variable. The variable is no more exposed since Python 3.5.1 to hide the exact implementation of atomic C types, to avoid compiler issues.

bpo-25791 [https://bugs.python.org/issue?@action=redirect&bpo=25791]: If __package__ != __spec__.parent or if neither __package__ or __spec__ are defined then ImportWarning is raised.

bpo-22995 [https://bugs.python.org/issue?@action=redirect&bpo=22995]: [UPDATE] Comment out the one of the pickleability tests in _PyObject_GetState() due to regressions observed in Cython-based projects.

bpo-25961 [https://bugs.python.org/issue?@action=redirect&bpo=25961]: Disallowed null characters in the type name.

bpo-25973 [https://bugs.python.org/issue?@action=redirect&bpo=25973]: Fix segfault when an invalid nonlocal statement binds a name starting with two underscores.

bpo-22995 [https://bugs.python.org/issue?@action=redirect&bpo=22995]: Instances of extension types with a state that aren’t subclasses of list or dict and haven’t implemented any pickle-related methods (__reduce__, __reduce_ex__, __getnewargs__, __getnewargs_ex__, or __getstate__), can no longer be pickled. Including memoryview.

bpo-20440 [https://bugs.python.org/issue?@action=redirect&bpo=20440]: Massive replacing unsafe attribute setting code with special macro Py_SETREF.

bpo-25766 [https://bugs.python.org/issue?@action=redirect&bpo=25766]: Special method __bytes__() now works in str subclasses.

bpo-25421 [https://bugs.python.org/issue?@action=redirect&bpo=25421]: __sizeof__ methods of builtin types now use dynamic basic size. This allows sys.getsize() to work correctly with their subclasses with __slots__ defined.

bpo-25709 [https://bugs.python.org/issue?@action=redirect&bpo=25709]: Fixed problem with in-place string concatenation and utf-8 cache.

bpo-5319 [https://bugs.python.org/issue?@action=redirect&bpo=5319]: New Py_FinalizeEx() API allowing Python to set an exit status of 120 on failure to flush buffered streams.

bpo-25485 [https://bugs.python.org/issue?@action=redirect&bpo=25485]: telnetlib.Telnet is now a context manager.

bpo-24097 [https://bugs.python.org/issue?@action=redirect&bpo=24097]: Fixed crash in object.__reduce__() if slot name is freed inside __getattr__.

bpo-24731 [https://bugs.python.org/issue?@action=redirect&bpo=24731]: Fixed crash on converting objects with special methods __bytes__, __trunc__, and __float__ returning instances of subclasses of bytes, int, and float to subclasses of bytes, int, and float correspondingly.

bpo-25630 [https://bugs.python.org/issue?@action=redirect&bpo=25630]: Fix a possible segfault during argument parsing in functions that accept filesystem paths.

bpo-23564 [https://bugs.python.org/issue?@action=redirect&bpo=23564]: Fixed a partially broken sanity check in the _posixsubprocess internals regarding how fds_to_pass were passed to the child. The bug had no actual impact as subprocess.py already avoided it.

bpo-25388 [https://bugs.python.org/issue?@action=redirect&bpo=25388]: Fixed tokenizer crash when processing undecodable source code with a null byte.

bpo-25462 [https://bugs.python.org/issue?@action=redirect&bpo=25462]: The hash of the key now is calculated only once in most operations in C implementation of OrderedDict.

bpo-22995 [https://bugs.python.org/issue?@action=redirect&bpo=22995]: Default implementation of __reduce__ and __reduce_ex__ now rejects builtin types with not defined __new__.

bpo-24802 [https://bugs.python.org/issue?@action=redirect&bpo=24802]: Avoid buffer overreads when int(), float(), compile(), exec() and eval() are passed bytes-like objects. These objects are not necessarily terminated by a null byte, but the functions assumed they were.

bpo-25555 [https://bugs.python.org/issue?@action=redirect&bpo=25555]: Fix parser and AST: fill lineno and col_offset of «arg» node when compiling AST from Python objects.

bpo-24726 [https://bugs.python.org/issue?@action=redirect&bpo=24726]: Fixed a crash and leaking NULL in repr() of OrderedDict that was mutated by direct calls of dict methods.

bpo-25449 [https://bugs.python.org/issue?@action=redirect&bpo=25449]: Iterating OrderedDict with keys with unstable hash now raises KeyError in C implementations as well as in Python implementation.

bpo-25395 [https://bugs.python.org/issue?@action=redirect&bpo=25395]: Fixed crash when highly nested OrderedDict structures were garbage collected.

bpo-25401 [https://bugs.python.org/issue?@action=redirect&bpo=25401]: Optimize bytes.fromhex() and bytearray.fromhex(): they are now between 2x and 3.5x faster.

bpo-25399 [https://bugs.python.org/issue?@action=redirect&bpo=25399]: Optimize bytearray % args using the new private _PyBytesWriter API. Formatting is now between 2.5 and 5 times faster.

bpo-25274 [https://bugs.python.org/issue?@action=redirect&bpo=25274]: sys.setrecursionlimit() now raises a RecursionError if the new recursion limit is too low depending at the current recursion depth. Modify also the «lower-water mark» formula to make it monotonic. This mark is used to decide when the overflowed flag of the thread state is reset.

bpo-24402 [https://bugs.python.org/issue?@action=redirect&bpo=24402]: Fix input() to prompt to the redirected stdout when sys.stdout.fileno() fails.

bpo-25349 [https://bugs.python.org/issue?@action=redirect&bpo=25349]: Optimize bytes % args using the new private _PyBytesWriter API. Formatting is now up to 2 times faster.

bpo-24806 [https://bugs.python.org/issue?@action=redirect&bpo=24806]: Prevent builtin types that are not allowed to be subclassed from being subclassed through multiple inheritance.

bpo-25301 [https://bugs.python.org/issue?@action=redirect&bpo=25301]: The UTF-8 decoder is now up to 15 times as fast for error handlers: ignore, replace and surrogateescape.

bpo-24848 [https://bugs.python.org/issue?@action=redirect&bpo=24848]: Fixed a number of bugs in UTF-7 decoding of misformed data.

bpo-25267 [https://bugs.python.org/issue?@action=redirect&bpo=25267]: The UTF-8 encoder is now up to 75 times as fast for error handlers: ignore, replace, surrogateescape, surrogatepass. Patch co-written with Serhiy Storchaka.

bpo-25280 [https://bugs.python.org/issue?@action=redirect&bpo=25280]: Import trace messages emitted in verbose (-v) mode are no longer formatted twice.

bpo-25227 [https://bugs.python.org/issue?@action=redirect&bpo=25227]: Optimize ASCII and latin1 encoders with the surrogateescape error handler: the encoders are now up to 3 times as fast. Initial patch written by Serhiy Storchaka.

bpo-25003 [https://bugs.python.org/issue?@action=redirect&bpo=25003]: On Solaris 11.3 or newer, os.urandom() now uses the getrandom() function instead of the getentropy() function. The getentropy() function is blocking to generate very good quality entropy, os.urandom() doesn’t need such high-quality entropy.

bpo-9232 [https://bugs.python.org/issue?@action=redirect&bpo=9232]: Modify Python’s grammar to allow trailing commas in the argument list of a function declaration. For example, «def f(*, a = 3,): pass» is now legal. Patch from Mark Dickinson.

bpo-24965 [https://bugs.python.org/issue?@action=redirect&bpo=24965]: Implement PEP 498 [https://www.python.org/dev/peps/pep-0498] «Literal String Interpolation». This allows you to embed expressions inside f-strings, which are converted to normal strings at run time. Given x=3, then f’value={x}” == “value=3”. Patch by Eric V. Smith.

bpo-26478 [https://bugs.python.org/issue?@action=redirect&bpo=26478]: Fix semantic bugs when using binary operators with dictionary views and tuples.

bpo-26171 [https://bugs.python.org/issue?@action=redirect&bpo=26171]: Fix possible integer overflow and heap corruption in zipimporter.get_data().

bpo-25660 [https://bugs.python.org/issue?@action=redirect&bpo=25660]: Fix TAB key behaviour in REPL with readline.

bpo-26288 [https://bugs.python.org/issue?@action=redirect&bpo=26288]: Optimize PyLong_AsDouble.

bpo-26289 [https://bugs.python.org/issue?@action=redirect&bpo=26289]: Optimize floor and modulo division for single-digit longs. Microbenchmarks show 2-2.5x improvement. Built-in “divmod” function is now also ~10% faster. (See also: bpo-26315 [https://bugs.python.org/issue?@action=redirect&bpo=26315])

bpo-25887 [https://bugs.python.org/issue?@action=redirect&bpo=25887]: Raise a RuntimeError when a coroutine object is awaited more than once.

Library

bpo-27057 [https://bugs.python.org/issue?@action=redirect&bpo=27057]: Fix os.set_inheritable() on Android, ioctl() is blocked by SELinux and fails with EACCESS. The function now falls back to fcntl(). Patch written by Michał Bednarski.

bpo-27014 [https://bugs.python.org/issue?@action=redirect&bpo=27014]: Fix infinite recursion using typing.py. Thanks to Kalle Tuure!

bpo-27031 [https://bugs.python.org/issue?@action=redirect&bpo=27031]: Removed dummy methods in Tkinter widget classes: tk_menuBar() and tk_bindForTraversal().

bpo-14132 [https://bugs.python.org/issue?@action=redirect&bpo=14132]: Fix urllib.request redirect handling when the target only has a query string. Original fix by Ján Janech.

bpo-17214 [https://bugs.python.org/issue?@action=redirect&bpo=17214]: The «urllib.request» module now percent-encodes non-ASCII bytes found in redirect target URLs. Some servers send Location header fields with non-ASCII bytes, but «http.client» requires the request target to be ASCII-encodable, otherwise a UnicodeEncodeError is raised. Based on patch by Christian Heimes.

bpo-27033 [https://bugs.python.org/issue?@action=redirect&bpo=27033]: The default value of the decode_data parameter for smtpd.SMTPChannel and smtpd.SMTPServer constructors is changed to False.

bpo-27034 [https://bugs.python.org/issue?@action=redirect&bpo=27034]: Removed deprecated class asynchat.fifo.

bpo-26870 [https://bugs.python.org/issue?@action=redirect&bpo=26870]: Added readline.set_auto_history(), which can stop entries being automatically added to the history list. Based on patch by Tyler Crompton.

bpo-26039 [https://bugs.python.org/issue?@action=redirect&bpo=26039]: zipfile.ZipFile.open() can now be used to write data into a ZIP file, as well as for extracting data. Patch by Thomas Kluyver.

bpo-26892 [https://bugs.python.org/issue?@action=redirect&bpo=26892]: Honor debuglevel flag in urllib.request.HTTPHandler. Patch contributed by Chi Hsuan Yen.

bpo-22274 [https://bugs.python.org/issue?@action=redirect&bpo=22274]: In the subprocess module, allow stderr to be redirected to stdout even when stdout is not redirected. Patch by Akira Li.

bpo-26807 [https://bugs.python.org/issue?@action=redirect&bpo=26807]: mock_open “files” no longer error on readline at end of file. Patch from Yolanda Robla.

bpo-25745 [https://bugs.python.org/issue?@action=redirect&bpo=25745]: Fixed leaking a userptr in curses panel destructor.

bpo-26977 [https://bugs.python.org/issue?@action=redirect&bpo=26977]: Removed unnecessary, and ignored, call to sum of squares helper in statistics.pvariance.

bpo-26002 [https://bugs.python.org/issue?@action=redirect&bpo=26002]: Use bisect in statistics.median instead of a linear search. Patch by Upendra Kuma.

bpo-25974 [https://bugs.python.org/issue?@action=redirect&bpo=25974]: Make use of new Decimal.as_integer_ratio() method in statistics module. Patch by Stefan Krah.

bpo-26996 [https://bugs.python.org/issue?@action=redirect&bpo=26996]: Add secrets module as described in PEP 506 [https://www.python.org/dev/peps/pep-0506].

bpo-26881 [https://bugs.python.org/issue?@action=redirect&bpo=26881]: The modulefinder module now supports extended opcode arguments.

bpo-23815 [https://bugs.python.org/issue?@action=redirect&bpo=23815]: Fixed crashes related to directly created instances of types in _tkinter and curses.panel modules.

bpo-17765 [https://bugs.python.org/issue?@action=redirect&bpo=17765]: weakref.ref() no longer silently ignores keyword arguments. Patch by Georg Brandl.

bpo-26873 [https://bugs.python.org/issue?@action=redirect&bpo=26873]: xmlrpc now raises ResponseError on unsupported type tags instead of silently return incorrect result.

bpo-26915 [https://bugs.python.org/issue?@action=redirect&bpo=26915]: The __contains__ methods in the collections ABCs now check for identity before checking equality. This better matches the behavior of the concrete classes, allows sensible handling of NaNs, and makes it easier to reason about container invariants.

bpo-26711 [https://bugs.python.org/issue?@action=redirect&bpo=26711]: Fixed the comparison of plistlib.Data with other types.

bpo-24114 [https://bugs.python.org/issue?@action=redirect&bpo=24114]: Fix an uninitialized variable in ctypes.util. The bug only occurs on SunOS when the ctypes implementation searches for the crle program. Patch by Xiang Zhang. Tested on SunOS by Kees Bos.

bpo-26864 [https://bugs.python.org/issue?@action=redirect&bpo=26864]: In urllib.request, change the proxy bypass host checking against no_proxy to be case-insensitive, and to not match unrelated host names that happen to have a bypassed hostname as a suffix. Patch by Xiang Zhang.

bpo-24902 [https://bugs.python.org/issue?@action=redirect&bpo=24902]: Print server URL on http.server startup. Initial patch by Felix Kaiser.

bpo-25788 [https://bugs.python.org/issue?@action=redirect&bpo=25788]: fileinput.hook_encoded() now supports an «errors» argument for passing to open. Original patch by Joseph Hackman.

bpo-26634 [https://bugs.python.org/issue?@action=redirect&bpo=26634]: recursive_repr() now sets __qualname__ of wrapper. Patch by Xiang Zhang.

bpo-26804 [https://bugs.python.org/issue?@action=redirect&bpo=26804]: urllib.request will prefer lower_case proxy environment variables over UPPER_CASE or Mixed_Case ones. Patch contributed by Hans-Peter Jansen.

bpo-26837 [https://bugs.python.org/issue?@action=redirect&bpo=26837]: assertSequenceEqual() now correctly outputs non-stringified differing items (like bytes in the -b mode). This affects assertListEqual() and assertTupleEqual().

bpo-26041 [https://bugs.python.org/issue?@action=redirect&bpo=26041]: Remove «will be removed in Python 3.7» from deprecation messages of platform.dist() and platform.linux_distribution(). Patch by Kumaripaba Miyurusara Athukorala.

bpo-26822 [https://bugs.python.org/issue?@action=redirect&bpo=26822]: itemgetter, attrgetter and methodcaller objects no longer silently ignore keyword arguments.

bpo-26733 [https://bugs.python.org/issue?@action=redirect&bpo=26733]: Disassembling a class now disassembles class and static methods. Patch by Xiang Zhang.

bpo-26801 [https://bugs.python.org/issue?@action=redirect&bpo=26801]: Fix error handling in shutil.get_terminal_size(), catch AttributeError instead of NameError. Patch written by Emanuel Barry.

bpo-24838 [https://bugs.python.org/issue?@action=redirect&bpo=24838]: tarfile’s ustar and gnu formats now correctly calculate name and link field limits for multibyte character encodings like utf-8.

bpo-26717 [https://bugs.python.org/issue?@action=redirect&bpo=26717]: Stop encoding Latin-1-ized WSGI paths with UTF-8. Patch by Anthony Sottile.

bpo-26782 [https://bugs.python.org/issue?@action=redirect&bpo=26782]: Add STARTUPINFO to subprocess.__all__ on Windows.

bpo-26404 [https://bugs.python.org/issue?@action=redirect&bpo=26404]: Add context manager to socketserver. Patch by Aviv Palivoda.

bpo-26735 [https://bugs.python.org/issue?@action=redirect&bpo=26735]: Fix os.urandom() on Solaris 11.3 and newer when reading more than 1,024 bytes: call getrandom() multiple times with a limit of 1024 bytes per call.

bpo-26585 [https://bugs.python.org/issue?@action=redirect&bpo=26585]: Eliminate http.server._quote_html() and use html.escape(quote=False). Patch by Xiang Zhang.

bpo-26685 [https://bugs.python.org/issue?@action=redirect&bpo=26685]: Raise OSError if closing a socket fails.

bpo-16329 [https://bugs.python.org/issue?@action=redirect&bpo=16329]: Add .webm to mimetypes.types_map. Patch by Giampaolo Rodola”.

bpo-13952 [https://bugs.python.org/issue?@action=redirect&bpo=13952]: Add .csv to mimetypes.types_map. Patch by Geoff Wilson.

bpo-26587 [https://bugs.python.org/issue?@action=redirect&bpo=26587]: the site module now allows .pth files to specify files to be added to sys.path (e.g. zip files).

bpo-25609 [https://bugs.python.org/issue?@action=redirect&bpo=25609]: Introduce contextlib.AbstractContextManager and typing.ContextManager.

bpo-26709 [https://bugs.python.org/issue?@action=redirect&bpo=26709]: Fixed Y2038 problem in loading binary PLists.

bpo-23735 [https://bugs.python.org/issue?@action=redirect&bpo=23735]: Handle terminal resizing with Readline 6.3+ by installing our own SIGWINCH handler. Patch by Eric Price.

bpo-25951 [https://bugs.python.org/issue?@action=redirect&bpo=25951]: Change SSLSocket.sendall() to return None, as explicitly documented for plain socket objects. Patch by Aviv Palivoda.

bpo-26586 [https://bugs.python.org/issue?@action=redirect&bpo=26586]: In http.server, respond with «413 Request header fields too large» if there are too many header fields to parse, rather than killing the connection and raising an unhandled exception. Patch by Xiang Zhang.

bpo-26676 [https://bugs.python.org/issue?@action=redirect&bpo=26676]: Added missing XMLPullParser to ElementTree.__all__.

bpo-22854 [https://bugs.python.org/issue?@action=redirect&bpo=22854]: Change BufferedReader.writable() and BufferedWriter.readable() to always return False.

bpo-26492 [https://bugs.python.org/issue?@action=redirect&bpo=26492]: Exhausted iterator of array.array now conforms with the behavior of iterators of other mutable sequences: it lefts exhausted even if iterated array is extended.

bpo-26641 [https://bugs.python.org/issue?@action=redirect&bpo=26641]: doctest.DocFileTest and doctest.testfile() now support packages (module splitted into multiple directories) for the package parameter.

bpo-25195 [https://bugs.python.org/issue?@action=redirect&bpo=25195]: Fix a regression in mock.MagicMock. _Call is a subclass of tuple (changeset 3603bae63c13 only works for classes) so we need to implement __ne__ ourselves. Patch by Andrew Plummer.

bpo-26644 [https://bugs.python.org/issue?@action=redirect&bpo=26644]: Raise ValueError rather than SystemError when a negative length is passed to SSLSocket.recv() or read().

bpo-23804 [https://bugs.python.org/issue?@action=redirect&bpo=23804]: Fix SSL recv(0) and read(0) methods to return zero bytes instead of up to 1024.

bpo-26616 [https://bugs.python.org/issue?@action=redirect&bpo=26616]: Fixed a bug in datetime.astimezone() method.

bpo-26637 [https://bugs.python.org/issue?@action=redirect&bpo=26637]: The importlib module now emits an ImportError rather than a TypeError if __import__() is tried during the Python shutdown process but sys.path is already cleared (set to None).

bpo-21925 [https://bugs.python.org/issue?@action=redirect&bpo=21925]: warnings.formatwarning() now catches exceptions when calling linecache.getline() and tracemalloc.get_object_traceback() to be able to log ResourceWarning emitted late during the Python shutdown process.

bpo-23848 [https://bugs.python.org/issue?@action=redirect&bpo=23848]: On Windows, faulthandler.enable() now also installs an exception handler to dump the traceback of all Python threads on any Windows exception, not only on UNIX signals (SIGSEGV, SIGFPE, SIGABRT).

bpo-26530 [https://bugs.python.org/issue?@action=redirect&bpo=26530]: Add C functions _PyTraceMalloc_Track() and _PyTraceMalloc_Untrack() to track memory blocks using the tracemalloc module. Add _PyTraceMalloc_GetTraceback() to get the traceback of an object.

bpo-26588 [https://bugs.python.org/issue?@action=redirect&bpo=26588]: The _tracemalloc now supports tracing memory allocations of multiple address spaces (domains).

bpo-24266 [https://bugs.python.org/issue?@action=redirect&bpo=24266]: Ctrl+C during Readline history search now cancels the search mode when compiled with Readline 7.

bpo-26590 [https://bugs.python.org/issue?@action=redirect&bpo=26590]: Implement a safe finalizer for the _socket.socket type. It now releases the GIL to close the socket.

bpo-18787 [https://bugs.python.org/issue?@action=redirect&bpo=18787]: spwd.getspnam() now raises a PermissionError if the user doesn’t have privileges.

bpo-26560 [https://bugs.python.org/issue?@action=redirect&bpo=26560]: Avoid potential ValueError in BaseHandler.start_response. Initial patch by Peter Inglesby.

bpo-26567 [https://bugs.python.org/issue?@action=redirect&bpo=26567]: Add a new function PyErr_ResourceWarning() function to pass the destroyed object. Add a source attribute to warnings.WarningMessage. Add warnings._showwarnmsg() which uses tracemalloc to get the traceback where source object was allocated.

bpo-26569 [https://bugs.python.org/issue?@action=redirect&bpo=26569]: Fix pyclbr.readmodule() and pyclbr.readmodule_ex() to support importing packages.

bpo-26499 [https://bugs.python.org/issue?@action=redirect&bpo=26499]: Account for remaining Content-Length in HTTPResponse.readline() and read1(). Based on patch by Silent Ghost. Also document that HTTPResponse now supports these methods.

bpo-25320 [https://bugs.python.org/issue?@action=redirect&bpo=25320]: Handle sockets in directories unittest discovery is scanning. Patch from Victor van den Elzen.

bpo-16181 [https://bugs.python.org/issue?@action=redirect&bpo=16181]: cookiejar.http2time() now returns None if year is higher than datetime.MAXYEAR.

bpo-26513 [https://bugs.python.org/issue?@action=redirect&bpo=26513]: Fixes platform module detection of Windows Server

bpo-23718 [https://bugs.python.org/issue?@action=redirect&bpo=23718]: Fixed parsing time in week 0 before Jan 1. Original patch by Tamás Bence Gedai.

bpo-26323 [https://bugs.python.org/issue?@action=redirect&bpo=26323]: Add Mock.assert_called() and Mock.assert_called_once() methods to unittest.mock. Patch written by Amit Saha.

bpo-20589 [https://bugs.python.org/issue?@action=redirect&bpo=20589]: Invoking Path.owner() and Path.group() on Windows now raise NotImplementedError instead of ImportError.

bpo-26177 [https://bugs.python.org/issue?@action=redirect&bpo=26177]: Fixed the keys() method for Canvas and Scrollbar widgets.

bpo-15068 [https://bugs.python.org/issue?@action=redirect&bpo=15068]: Got rid of excessive buffering in fileinput. The bufsize parameter is now deprecated and ignored.

bpo-19475 [https://bugs.python.org/issue?@action=redirect&bpo=19475]: Added an optional argument timespec to the datetime isoformat() method to choose the precision of the time component.

bpo-2202 [https://bugs.python.org/issue?@action=redirect&bpo=2202]: Fix UnboundLocalError in AbstractDigestAuthHandler.get_algorithm_impls. Initial patch by Mathieu Dupuy.

bpo-26167 [https://bugs.python.org/issue?@action=redirect&bpo=26167]: Minimized overhead in copy.copy() and copy.deepcopy(). Optimized copying and deepcopying bytearrays, NotImplemented, slices, short lists, tuples, dicts, sets.

bpo-25718 [https://bugs.python.org/issue?@action=redirect&bpo=25718]: Fixed pickling and copying the accumulate() iterator with total is None.

bpo-26475 [https://bugs.python.org/issue?@action=redirect&bpo=26475]: Fixed debugging output for regular expressions with the (?x) flag.

bpo-26482 [https://bugs.python.org/issue?@action=redirect&bpo=26482]: Allowed pickling recursive dequeues.

bpo-26335 [https://bugs.python.org/issue?@action=redirect&bpo=26335]: Make mmap.write() return the number of bytes written like other write methods. Patch by Jakub Stasiak.

bpo-26457 [https://bugs.python.org/issue?@action=redirect&bpo=26457]: Fixed the subnets() methods in IP network classes for the case when resulting prefix length is equal to maximal prefix length. Based on patch by Xiang Zhang.

bpo-26385 [https://bugs.python.org/issue?@action=redirect&bpo=26385]: Remove the file if the internal open() call in NamedTemporaryFile() fails. Patch by Silent Ghost.

bpo-26402 [https://bugs.python.org/issue?@action=redirect&bpo=26402]: Fix XML-RPC client to retry when the server shuts down a persistent connection. This was a regression related to the new http.client.RemoteDisconnected exception in 3.5.0a4.

bpo-25913 [https://bugs.python.org/issue?@action=redirect&bpo=25913]: Leading <~ is optional now in base64.a85decode() with adobe=True. Patch by Swati Jaiswal.

bpo-26186 [https://bugs.python.org/issue?@action=redirect&bpo=26186]: Remove an invalid type check in importlib.util.LazyLoader.

bpo-26367 [https://bugs.python.org/issue?@action=redirect&bpo=26367]: importlib.__import__() raises ImportError like builtins.__import__() when level is specified but without an accompanying package specified.

bpo-26309 [https://bugs.python.org/issue?@action=redirect&bpo=26309]: In the «socketserver» module, shut down the request (closing the connected socket) when verify_request() returns false. Patch by Aviv Palivoda.

bpo-23430 [https://bugs.python.org/issue?@action=redirect&bpo=23430]: Change the socketserver module to only catch exceptions raised from a request handler that are derived from Exception (instead of BaseException). Therefore SystemExit and KeyboardInterrupt no longer trigger the handle_error() method, and will now to stop a single-threaded server.

bpo-25995 [https://bugs.python.org/issue?@action=redirect&bpo=25995]: os.walk() no longer uses FDs proportional to the tree depth.

bpo-25994 [https://bugs.python.org/issue?@action=redirect&bpo=25994]: Added the close() method and the support of the context manager protocol for the os.scandir() iterator.

bpo-23992 [https://bugs.python.org/issue?@action=redirect&bpo=23992]: multiprocessing: make MapResult not fail-fast upon exception.

bpo-26243 [https://bugs.python.org/issue?@action=redirect&bpo=26243]: Support keyword arguments to zlib.compress(). Patch by Aviv Palivoda.

bpo-26117 [https://bugs.python.org/issue?@action=redirect&bpo=26117]: The os.scandir() iterator now closes file descriptor not only when the iteration is finished, but when it was failed with error.

bpo-25949 [https://bugs.python.org/issue?@action=redirect&bpo=25949]: __dict__ for an OrderedDict instance is now created only when needed.

bpo-25911 [https://bugs.python.org/issue?@action=redirect&bpo=25911]: Restored support of bytes paths in os.walk() on Windows.

bpo-26045 [https://bugs.python.org/issue?@action=redirect&bpo=26045]: Add UTF-8 suggestion to error message when posting a non-Latin-1 string with http.client.

bpo-26039 [https://bugs.python.org/issue?@action=redirect&bpo=26039]: Added zipfile.ZipInfo.from_file() and zipinfo.ZipInfo.is_dir(). Patch by Thomas Kluyver.

bpo-12923 [https://bugs.python.org/issue?@action=redirect&bpo=12923]: Reset FancyURLopener’s redirect counter even if there is an exception. Based on patches by Brian Brazil and Daniel Rocco.

bpo-25945 [https://bugs.python.org/issue?@action=redirect&bpo=25945]: Fixed a crash when unpickle the functools.partial object with wrong state. Fixed a leak in failed functools.partial constructor. «args» and «keywords» attributes of functools.partial have now always types tuple and dict correspondingly.

bpo-26202 [https://bugs.python.org/issue?@action=redirect&bpo=26202]: copy.deepcopy() now correctly copies range() objects with non-atomic attributes.

bpo-23076 [https://bugs.python.org/issue?@action=redirect&bpo=23076]: Path.glob() now raises a ValueError if it’s called with an invalid pattern. Patch by Thomas Nyberg.

bpo-19883 [https://bugs.python.org/issue?@action=redirect&bpo=19883]: Fixed possible integer overflows in zipimport.

bpo-26227 [https://bugs.python.org/issue?@action=redirect&bpo=26227]: On Windows, getnameinfo(), gethostbyaddr() and gethostbyname_ex() functions of the socket module now decode the hostname from the ANSI code page rather than UTF-8.

bpo-26099 [https://bugs.python.org/issue?@action=redirect&bpo=26099]: The site module now writes an error into stderr if sitecustomize module can be imported but executing the module raise an ImportError. Same change for usercustomize.

bpo-26147 [https://bugs.python.org/issue?@action=redirect&bpo=26147]: xmlrpc now works with strings not encodable with used non-UTF-8 encoding.

bpo-25935 [https://bugs.python.org/issue?@action=redirect&bpo=25935]: Garbage collector now breaks reference loops with OrderedDict.

bpo-16620 [https://bugs.python.org/issue?@action=redirect&bpo=16620]: Fixed AttributeError in msilib.Directory.glob().

bpo-26013 [https://bugs.python.org/issue?@action=redirect&bpo=26013]: Added compatibility with broken protocol 2 pickles created in old Python 3 versions (3.4.3 and lower).

bpo-26129 [https://bugs.python.org/issue?@action=redirect&bpo=26129]: Deprecated accepting non-integers in grp.getgrgid().

bpo-25850 [https://bugs.python.org/issue?@action=redirect&bpo=25850]: Use cross-compilation by default for 64-bit Windows.

bpo-25822 [https://bugs.python.org/issue?@action=redirect&bpo=25822]: Add docstrings to the fields of urllib.parse results. Patch contributed by Swati Jaiswal.

bpo-22642 [https://bugs.python.org/issue?@action=redirect&bpo=22642]: Convert trace module option parsing mechanism to argparse. Patch contributed by SilentGhost.

bpo-24705 [https://bugs.python.org/issue?@action=redirect&bpo=24705]: Fix sysconfig._parse_makefile not expanding ${} vars appearing before $() vars.

bpo-26069 [https://bugs.python.org/issue?@action=redirect&bpo=26069]: Remove the deprecated apis in the trace module.

bpo-22138 [https://bugs.python.org/issue?@action=redirect&bpo=22138]: Fix mock.patch behavior when patching descriptors. Restore original values after patching. Patch contributed by Sean McCully.

bpo-25672 [https://bugs.python.org/issue?@action=redirect&bpo=25672]: In the ssl module, enable the SSL_MODE_RELEASE_BUFFERS mode option if it is safe to do so.

bpo-26012 [https://bugs.python.org/issue?@action=redirect&bpo=26012]: Don’t traverse into symlinks for ** pattern in pathlib.Path.[r]glob().

bpo-24120 [https://bugs.python.org/issue?@action=redirect&bpo=24120]: Ignore PermissionError when traversing a tree with pathlib.Path.[r]glob(). Patch by Ulrich Petri.

bpo-21815 [https://bugs.python.org/issue?@action=redirect&bpo=21815]: Accept ] characters in the data portion of imap responses, in order to handle the flags with square brackets accepted and produced by servers such as gmail.

bpo-25447 [https://bugs.python.org/issue?@action=redirect&bpo=25447]: fileinput now uses sys.stdin as-is if it does not have a buffer attribute (restores backward compatibility).

bpo-25971 [https://bugs.python.org/issue?@action=redirect&bpo=25971]: Optimized creating Fractions from floats by 2 times and from Decimals by 3 times.

bpo-25802 [https://bugs.python.org/issue?@action=redirect&bpo=25802]: Document as deprecated the remaining implementations of importlib.abc.Loader.load_module().

bpo-25928 [https://bugs.python.org/issue?@action=redirect&bpo=25928]: Add Decimal.as_integer_ratio().

bpo-25447 [https://bugs.python.org/issue?@action=redirect&bpo=25447]: Copying the lru_cache() wrapper object now always works, independently from the type of the wrapped object (by returning the original object unchanged).

bpo-25768 [https://bugs.python.org/issue?@action=redirect&bpo=25768]: Have the functions in compileall return booleans instead of ints and add proper documentation and tests for the return values.

bpo-24103 [https://bugs.python.org/issue?@action=redirect&bpo=24103]: Fixed possible use after free in ElementTree.XMLPullParser.

bpo-25860 [https://bugs.python.org/issue?@action=redirect&bpo=25860]: os.fwalk() no longer skips remaining directories when error occurs. Original patch by Samson Lee.

bpo-25914 [https://bugs.python.org/issue?@action=redirect&bpo=25914]: Fixed and simplified OrderedDict.__sizeof__.

bpo-25869 [https://bugs.python.org/issue?@action=redirect&bpo=25869]: Optimized deepcopying ElementTree; it is now 20 times faster.

bpo-25873 [https://bugs.python.org/issue?@action=redirect&bpo=25873]: Optimized iterating ElementTree. Iterating elements Element.iter() is now 40% faster, iterating text Element.itertext() is now up to 2.5 times faster.

bpo-25902 [https://bugs.python.org/issue?@action=redirect&bpo=25902]: Fixed various refcount issues in ElementTree iteration.

bpo-22227 [https://bugs.python.org/issue?@action=redirect&bpo=22227]: The TarFile iterator is reimplemented using generator. This implementation is simpler that using class.

bpo-25638 [https://bugs.python.org/issue?@action=redirect&bpo=25638]: Optimized ElementTree.iterparse(); it is now 2x faster. Optimized ElementTree parsing; it is now 10% faster.

bpo-25761 [https://bugs.python.org/issue?@action=redirect&bpo=25761]: Improved detecting errors in broken pickle data.

bpo-25717 [https://bugs.python.org/issue?@action=redirect&bpo=25717]: Restore the previous behaviour of tolerating most fstat() errors when opening files. This was a regression in 3.5a1, and stopped anonymous temporary files from working in special cases.

bpo-24903 [https://bugs.python.org/issue?@action=redirect&bpo=24903]: Fix regression in number of arguments compileall accepts when “-d” is specified. The check on the number of arguments has been dropped completely as it never worked correctly anyway.

bpo-25764 [https://bugs.python.org/issue?@action=redirect&bpo=25764]: In the subprocess module, preserve any exception caused by fork() failure when preexec_fn is used.

bpo-25771 [https://bugs.python.org/issue?@action=redirect&bpo=25771]: Tweak the exception message for importlib.util.resolve_name() when “package” isn’t specified but necessary.

bpo-6478 [https://bugs.python.org/issue?@action=redirect&bpo=6478]: _strptime’s regexp cache now is reset after changing timezone with time.tzset().

bpo-14285 [https://bugs.python.org/issue?@action=redirect&bpo=14285]: When executing a package with the «python -m package» option, and package initialization fails, a proper traceback is now reported. The «runpy» module now lets exceptions from package initialization pass back to the caller, rather than raising ImportError.

bpo-19771 [https://bugs.python.org/issue?@action=redirect&bpo=19771]: Also in runpy and the «-m» option, omit the irrelevant message «… is a package and cannot be directly executed» if the package could not even be initialized (e.g. due to a bad *.pyc file).

bpo-25177 [https://bugs.python.org/issue?@action=redirect&bpo=25177]: Fixed problem with the mean of very small and very large numbers. As a side effect, statistics.mean and statistics.variance should be significantly faster.

bpo-25718 [https://bugs.python.org/issue?@action=redirect&bpo=25718]: Fixed copying object with state with boolean value is false.

bpo-10131 [https://bugs.python.org/issue?@action=redirect&bpo=10131]: Fixed deep copying of minidom documents. Based on patch by Marian Ganisin.

bpo-7990 [https://bugs.python.org/issue?@action=redirect&bpo=7990]: dir() on ElementTree.Element now lists properties: «tag», «text», «tail» and «attrib». Original patch by Santoso Wijaya.

bpo-25725 [https://bugs.python.org/issue?@action=redirect&bpo=25725]: Fixed a reference leak in pickle.loads() when unpickling invalid data including tuple instructions.

bpo-25663 [https://bugs.python.org/issue?@action=redirect&bpo=25663]: In the Readline completer, avoid listing duplicate global names, and search the global namespace before searching builtins.

bpo-25688 [https://bugs.python.org/issue?@action=redirect&bpo=25688]: Fixed file leak in ElementTree.iterparse() raising an error.

bpo-23914 [https://bugs.python.org/issue?@action=redirect&bpo=23914]: Fixed SystemError raised by unpickler on broken pickle data.

bpo-25691 [https://bugs.python.org/issue?@action=redirect&bpo=25691]: Fixed crash on deleting ElementTree.Element attributes.

bpo-25624 [https://bugs.python.org/issue?@action=redirect&bpo=25624]: ZipFile now always writes a ZIP_STORED header for directory entries. Patch by Dingyuan Wang.

bpo-25626 [https://bugs.python.org/issue?@action=redirect&bpo=25626]: Change three zlib functions to accept sizes that fit in Py_ssize_t, but internally cap those sizes to UINT_MAX. This resolves a regression in 3.5 where GzipFile.read() failed to read chunks larger than 2 or 4 GiB. The change affects the zlib.Decompress.decompress() max_length parameter, the zlib.decompress() bufsize parameter, and the zlib.Decompress.flush() length parameter.

bpo-25583 [https://bugs.python.org/issue?@action=redirect&bpo=25583]: Avoid incorrect errors raised by os.makedirs(exist_ok=True) when the OS gives priority to errors such as EACCES over EEXIST.

bpo-25593 [https://bugs.python.org/issue?@action=redirect&bpo=25593]: Change semantics of EventLoop.stop() in asyncio.

bpo-6973 [https://bugs.python.org/issue?@action=redirect&bpo=6973]: When we know a subprocess.Popen process has died, do not allow the send_signal(), terminate(), or kill() methods to do anything as they could potentially signal a different process.

bpo-23883 [https://bugs.python.org/issue?@action=redirect&bpo=23883]: Added missing APIs to __all__ to match the documented APIs for the following modules: calendar, csv, enum, fileinput, ftplib, logging, optparse, tarfile, threading and wave. Also added a test.support.check__all__() helper. Patches by Jacek Kołodziej, Mauro S. M. Rodrigues and Joel Taddei.

bpo-25590 [https://bugs.python.org/issue?@action=redirect&bpo=25590]: In the Readline completer, only call getattr() once per attribute. Also complete names of attributes such as properties and slots which are listed by dir() but not yet created on an instance.

bpo-25498 [https://bugs.python.org/issue?@action=redirect&bpo=25498]: Fix a crash when garbage-collecting ctypes objects created by wrapping a memoryview. This was a regression made in 3.5a1. Based on patch by Eryksun.

bpo-25584 [https://bugs.python.org/issue?@action=redirect&bpo=25584]: Added «escape» to the __all__ list in the glob module.

bpo-25584 [https://bugs.python.org/issue?@action=redirect&bpo=25584]: Fixed recursive glob() with patterns starting with **.

bpo-25446 [https://bugs.python.org/issue?@action=redirect&bpo=25446]: Fix regression in smtplib’s AUTH LOGIN support.

bpo-18010 [https://bugs.python.org/issue?@action=redirect&bpo=18010]: Fix the pydoc web server’s module search function to handle exceptions from importing packages.

bpo-25554 [https://bugs.python.org/issue?@action=redirect&bpo=25554]: Got rid of circular references in regular expression parsing.

bpo-18973 [https://bugs.python.org/issue?@action=redirect&bpo=18973]: Command-line interface of the calendar module now uses argparse instead of optparse.

bpo-25510 [https://bugs.python.org/issue?@action=redirect&bpo=25510]: fileinput.FileInput.readline() now returns b”” instead of “” at the end if the FileInput was opened with binary mode. Patch by Ryosuke Ito.

bpo-25503 [https://bugs.python.org/issue?@action=redirect&bpo=25503]: Fixed inspect.getdoc() for inherited docstrings of properties. Original patch by John Mark Vandenberg.

bpo-25515 [https://bugs.python.org/issue?@action=redirect&bpo=25515]: Always use os.urandom as a source of randomness in uuid.uuid4.

bpo-21827 [https://bugs.python.org/issue?@action=redirect&bpo=21827]: Fixed textwrap.dedent() for the case when largest common whitespace is a substring of smallest leading whitespace. Based on patch by Robert Li.

bpo-25447 [https://bugs.python.org/issue?@action=redirect&bpo=25447]: The lru_cache() wrapper objects now can be copied and pickled (by returning the original object unchanged).

bpo-25390 [https://bugs.python.org/issue?@action=redirect&bpo=25390]: typing: Don’t crash on Union[str, Pattern].

bpo-25441 [https://bugs.python.org/issue?@action=redirect&bpo=25441]: asyncio: Raise error from drain() when socket is closed.

bpo-25410 [https://bugs.python.org/issue?@action=redirect&bpo=25410]: Cleaned up and fixed minor bugs in C implementation of OrderedDict.

bpo-25411 [https://bugs.python.org/issue?@action=redirect&bpo=25411]: Improved Unicode support in SMTPHandler through better use of the email package. Thanks to user simon04 for the patch.

Move the imp module from a PendingDeprecationWarning to DeprecationWarning.

bpo-25407 [https://bugs.python.org/issue?@action=redirect&bpo=25407]: Remove mentions of the formatter module being removed in Python 3.6.

bpo-25406 [https://bugs.python.org/issue?@action=redirect&bpo=25406]: Fixed a bug in C implementation of OrderedDict.move_to_end() that caused segmentation fault or hang in iterating after moving several items to the start of ordered dict.

bpo-25382 [https://bugs.python.org/issue?@action=redirect&bpo=25382]: pickletools.dis() now outputs implicit memo index for the MEMOIZE opcode.

bpo-25357 [https://bugs.python.org/issue?@action=redirect&bpo=25357]: Add an optional newline parameter to binascii.b2a_base64(). base64.b64encode() uses it to avoid a memory copy.

bpo-24164 [https://bugs.python.org/issue?@action=redirect&bpo=24164]: Objects that need calling __new__ with keyword arguments, can now be pickled using pickle protocols older than protocol version 4.

bpo-25364 [https://bugs.python.org/issue?@action=redirect&bpo=25364]: zipfile now works in threads disabled builds.

bpo-25328 [https://bugs.python.org/issue?@action=redirect&bpo=25328]: smtpd’s SMTPChannel now correctly raises a ValueError if both decode_data and enable_SMTPUTF8 are set to true.

bpo-16099 [https://bugs.python.org/issue?@action=redirect&bpo=16099]: RobotFileParser now supports Crawl-delay and Request-rate extensions. Patch by Nikolay Bogoychev.

bpo-25316 [https://bugs.python.org/issue?@action=redirect&bpo=25316]: distutils raises OSError instead of DistutilsPlatformError when MSVC is not installed.

bpo-25380 [https://bugs.python.org/issue?@action=redirect&bpo=25380]: Fixed protocol for the STACK_GLOBAL opcode in pickletools.opcodes.

bpo-23972 [https://bugs.python.org/issue?@action=redirect&bpo=23972]: Updates asyncio datagram create method allowing reuseport and reuseaddr socket options to be set prior to binding the socket. Mirroring the existing asyncio create_server method the reuseaddr option for datagram sockets defaults to True if the O/S is “posix” (except if the platform is Cygwin). Patch by Chris Laws.

bpo-25304 [https://bugs.python.org/issue?@action=redirect&bpo=25304]: Add asyncio.run_coroutine_threadsafe(). This lets you submit a coroutine to a loop from another thread, returning a concurrent.futures.Future. By Vincent Michel.

bpo-25232 [https://bugs.python.org/issue?@action=redirect&bpo=25232]: Fix CGIRequestHandler to split the query from the URL at the first question mark (?) rather than the last. Patch from Xiang Zhang.

bpo-24657 [https://bugs.python.org/issue?@action=redirect&bpo=24657]: Prevent CGIRequestHandler from collapsing slashes in the query part of the URL as if it were a path. Patch from Xiang Zhang.

bpo-25287 [https://bugs.python.org/issue?@action=redirect&bpo=25287]: Don’t add crypt.METHOD_CRYPT to crypt.methods if it’s not supported. Check if it is supported, it may not be supported on OpenBSD for example.

bpo-23600 [https://bugs.python.org/issue?@action=redirect&bpo=23600]: Default implementation of tzinfo.fromutc() was returning wrong results in some cases.

bpo-25203 [https://bugs.python.org/issue?@action=redirect&bpo=25203]: Failed readline.set_completer_delims() no longer left the module in inconsistent state.

bpo-25011 [https://bugs.python.org/issue?@action=redirect&bpo=25011]: rlcompleter now omits private and special attribute names unless the prefix starts with underscores.

bpo-25209 [https://bugs.python.org/issue?@action=redirect&bpo=25209]: rlcompleter now can add a space or a colon after completed keyword.

bpo-22241 [https://bugs.python.org/issue?@action=redirect&bpo=22241]: timezone.utc name is now plain “UTC”, not “UTC-00:00”.

bpo-23517 [https://bugs.python.org/issue?@action=redirect&bpo=23517]: fromtimestamp() and utcfromtimestamp() methods of datetime.datetime now round microseconds to nearest with ties going to nearest even integer (ROUND_HALF_EVEN), as round(float), instead of rounding towards -Infinity (ROUND_FLOOR).

bpo-23552 [https://bugs.python.org/issue?@action=redirect&bpo=23552]: Timeit now warns when there is substantial (4x) variance between best and worst times. Patch from Serhiy Storchaka.

bpo-24633 [https://bugs.python.org/issue?@action=redirect&bpo=24633]: site-packages/README -> README.txt.

bpo-24879 [https://bugs.python.org/issue?@action=redirect&bpo=24879]: help() and pydoc can now list named tuple fields in the order they were defined rather than alphabetically. The ordering is determined by the _fields attribute if present.

bpo-24874 [https://bugs.python.org/issue?@action=redirect&bpo=24874]: Improve speed of itertools.cycle() and make its pickle more compact.

Fix crash in itertools.cycle.__setstate__() when the first argument wasn’t a list.

bpo-20059 [https://bugs.python.org/issue?@action=redirect&bpo=20059]: urllib.parse raises ValueError on all invalid ports. Patch by Martin Panter.

bpo-24360 [https://bugs.python.org/issue?@action=redirect&bpo=24360]: Improve __repr__ of argparse.Namespace() for invalid identifiers. Patch by Matthias Bussonnier.

bpo-23426 [https://bugs.python.org/issue?@action=redirect&bpo=23426]: run_setup was broken in distutils. Patch from Alexander Belopolsky.

bpo-13938 [https://bugs.python.org/issue?@action=redirect&bpo=13938]: 2to3 converts StringTypes to a tuple. Patch from Mark Hammond.

bpo-2091 [https://bugs.python.org/issue?@action=redirect&bpo=2091]: open() accepted a “U” mode string containing “+”, but “U” can only be used with “r”. Patch from Jeff Balogh and John O’Connor.

bpo-8585 [https://bugs.python.org/issue?@action=redirect&bpo=8585]: improved tests for zipimporter2. Patch from Mark Lawrence.

bpo-18622 [https://bugs.python.org/issue?@action=redirect&bpo=18622]: unittest.mock.mock_open().reset_mock would recurse infinitely. Patch from Nicola Palumbo and Laurent De Buyst.

bpo-24426 [https://bugs.python.org/issue?@action=redirect&bpo=24426]: Fast searching optimization in regular expressions now works for patterns that starts with capturing groups. Fast searching optimization now can’t be disabled at compile time.

bpo-23661 [https://bugs.python.org/issue?@action=redirect&bpo=23661]: unittest.mock side_effects can now be exceptions again. This was a regression vs Python 3.4. Patch from Ignacio Rossi

bpo-13248 [https://bugs.python.org/issue?@action=redirect&bpo=13248]: Remove deprecated inspect.getmoduleinfo function.

bpo-25578 [https://bugs.python.org/issue?@action=redirect&bpo=25578]: Fix (another) memory leak in SSLSocket.getpeercer().

bpo-25530 [https://bugs.python.org/issue?@action=redirect&bpo=25530]: Disable the vulnerable SSLv3 protocol by default when creating ssl.SSLContext.

bpo-25569 [https://bugs.python.org/issue?@action=redirect&bpo=25569]: Fix memory leak in SSLSocket.getpeercert().

bpo-25471 [https://bugs.python.org/issue?@action=redirect&bpo=25471]: Sockets returned from accept() shouldn’t appear to be nonblocking.

bpo-25319 [https://bugs.python.org/issue?@action=redirect&bpo=25319]: When threading.Event is reinitialized, the underlying condition should use a regular lock rather than a recursive lock.

Skip getaddrinfo if host is already resolved. Patch by A. Jesse Jiryu Davis.

bpo-26050 [https://bugs.python.org/issue?@action=redirect&bpo=26050]: Add asyncio.StreamReader.readuntil() method. Patch by Марк Коренберг.

bpo-25924 [https://bugs.python.org/issue?@action=redirect&bpo=25924]: Avoid unnecessary serialization of getaddrinfo(3) calls on OS X versions 10.5 or higher. Original patch by A. Jesse Jiryu Davis.

bpo-26406 [https://bugs.python.org/issue?@action=redirect&bpo=26406]: Avoid unnecessary serialization of getaddrinfo(3) calls on current versions of OpenBSD and NetBSD. Patch by A. Jesse Jiryu Davis.

bpo-26848 [https://bugs.python.org/issue?@action=redirect&bpo=26848]: Fix asyncio/subprocess.communicate() to handle empty input. Patch by Jack O’Connor.

bpo-27040 [https://bugs.python.org/issue?@action=redirect&bpo=27040]: Add loop.get_exception_handler method

bpo-27041 [https://bugs.python.org/issue?@action=redirect&bpo=27041]: asyncio: Add loop.create_future method

IDLE

bpo-20640 [https://bugs.python.org/issue?@action=redirect&bpo=20640]: Add tests for idlelib.configHelpSourceEdit. Patch by Saimadhav Heblikar.

In the “IDLE-console differences” section of the IDLE doc, clarify how running with IDLE affects sys.modules and the standard streams.

bpo-25507 [https://bugs.python.org/issue?@action=redirect&bpo=25507]: fix incorrect change in IOBinding that prevented printing. Augment IOBinding htest to include all major IOBinding functions.

bpo-25905 [https://bugs.python.org/issue?@action=redirect&bpo=25905]: Revert unwanted conversion of “ to ’ RIGHT SINGLE QUOTATION MARK in README.txt and open this and NEWS.txt with “ascii”. Re-encode CREDITS.txt to utf-8 and open it with “utf-8”.

bpo-15348 [https://bugs.python.org/issue?@action=redirect&bpo=15348]: Stop the debugger engine (normally in a user process) before closing the debugger window (running in the IDLE process). This prevents the RuntimeErrors that were being caught and ignored.

bpo-24455 [https://bugs.python.org/issue?@action=redirect&bpo=24455]: Prevent IDLE from hanging when a) closing the shell while the debugger is active (15347); b) closing the debugger with the [X] button (15348); and c) activating the debugger when already active (24455). The patch by Mark Roseman does this by making two changes. 1. Suspend and resume the gui.interaction method with the tcl vwait mechanism intended for this purpose (instead of root.mainloop & .quit). 2. In gui.run, allow any existing interaction to terminate first.

Change “The program” to “Your program” in an IDLE “kill program?” message to make it clearer that the program referred to is the currently running user program, not IDLE itself.

bpo-24750 [https://bugs.python.org/issue?@action=redirect&bpo=24750]: Improve the appearance of the IDLE editor window status bar. Patch by Mark Roseman.

bpo-25313 [https://bugs.python.org/issue?@action=redirect&bpo=25313]: Change the handling of new built-in text color themes to better address the compatibility problem introduced by the addition of IDLE Dark. Consistently use the revised idleConf.CurrentTheme everywhere in idlelib.

bpo-24782 [https://bugs.python.org/issue?@action=redirect&bpo=24782]: Extension configuration is now a tab in the IDLE Preferences dialog rather than a separate dialog. The former tabs are now a sorted list. Patch by Mark Roseman.

bpo-22726 [https://bugs.python.org/issue?@action=redirect&bpo=22726]: Re-activate the config dialog help button with some content about the other buttons and the new IDLE Dark theme.

bpo-24820 [https://bugs.python.org/issue?@action=redirect&bpo=24820]: IDLE now has an “IDLE Dark” built-in text color theme. It is more or less IDLE Classic inverted, with a cobalt blue background. Strings, comments, keywords, … are still green, red, orange, … . To use it with IDLEs released before November 2015, hit the “Save as New Custom Theme” button and enter a new name, such as “Custom Dark”. The custom theme will work with any IDLE release, and can be modified.

bpo-25224 [https://bugs.python.org/issue?@action=redirect&bpo=25224]: README.txt is now an idlelib index for IDLE developers and curious users. The previous user content is now in the IDLE doc chapter. “IDLE” now means “Integrated Development and Learning Environment”.

bpo-24820 [https://bugs.python.org/issue?@action=redirect&bpo=24820]: Users can now set breakpoint colors in Settings -> Custom Highlighting. Original patch by Mark Roseman.

bpo-24972 [https://bugs.python.org/issue?@action=redirect&bpo=24972]: Inactive selection background now matches active selection background, as configured by users, on all systems. Found items are now always highlighted on Windows. Initial patch by Mark Roseman.

bpo-24570 [https://bugs.python.org/issue?@action=redirect&bpo=24570]: Idle: make calltip and completion boxes appear on Macs affected by a tk regression. Initial patch by Mark Roseman.

bpo-24988 [https://bugs.python.org/issue?@action=redirect&bpo=24988]: Idle ScrolledList context menus (used in debugger) now work on Mac Aqua. Patch by Mark Roseman.

bpo-24801 [https://bugs.python.org/issue?@action=redirect&bpo=24801]: Make right-click for context menu work on Mac Aqua. Patch by Mark Roseman.

bpo-25173 [https://bugs.python.org/issue?@action=redirect&bpo=25173]: Associate tkinter messageboxes with a specific widget. For Mac OSX, make them a “sheet”. Patch by Mark Roseman.

bpo-25198 [https://bugs.python.org/issue?@action=redirect&bpo=25198]: Enhance the initial html viewer now used for Idle Help. Properly indent fixed-pitch text (patch by Mark Roseman). Give code snippet a very Sphinx-like light blueish-gray background. Re-use initial width and height set by users for shell and editor. When the Table of Contents (TOC) menu is used, put the section header at the top of the screen.

bpo-25225 [https://bugs.python.org/issue?@action=redirect&bpo=25225]: Condense and rewrite Idle doc section on text colors.

bpo-21995 [https://bugs.python.org/issue?@action=redirect&bpo=21995]: Explain some differences between IDLE and console Python.

bpo-22820 [https://bugs.python.org/issue?@action=redirect&bpo=22820]: Explain need for print when running file from Idle editor.

bpo-25224 [https://bugs.python.org/issue?@action=redirect&bpo=25224]: Doc: augment Idle feature list and no-subprocess section.

bpo-25219 [https://bugs.python.org/issue?@action=redirect&bpo=25219]: Update doc for Idle command line options. Some were missing and notes were not correct.

bpo-24861 [https://bugs.python.org/issue?@action=redirect&bpo=24861]: Most of idlelib is private and subject to change. Use idleib.idle.* to start Idle. See idlelib.__init__.__doc__.

bpo-25199 [https://bugs.python.org/issue?@action=redirect&bpo=25199]: Idle: add synchronization comments for future maintainers.

bpo-16893 [https://bugs.python.org/issue?@action=redirect&bpo=16893]: Replace help.txt with help.html for Idle doc display. The new idlelib/help.html is rstripped Doc/build/html/library/idle.html. It looks better than help.txt and will better document Idle as released. The tkinter html viewer that works for this file was written by Rose Roseman. The now unused EditorWindow.HelpDialog class and helt.txt file are deprecated.

bpo-24199 [https://bugs.python.org/issue?@action=redirect&bpo=24199]: Deprecate unused idlelib.idlever with possible removal in 3.6.

bpo-24790 [https://bugs.python.org/issue?@action=redirect&bpo=24790]: Remove extraneous code (which also create 2 & 3 conflicts).

Documentation

bpo-26736 [https://bugs.python.org/issue?@action=redirect&bpo=26736]: Used HTTPS for external links in the documentation if possible.

bpo-6953 [https://bugs.python.org/issue?@action=redirect&bpo=6953]: Rework the Readline module documentation to group related functions together, and add more details such as what underlying Readline functions and variables are accessed.

bpo-23606 [https://bugs.python.org/issue?@action=redirect&bpo=23606]: Adds note to ctypes documentation regarding cdll.msvcrt.

bpo-24952 [https://bugs.python.org/issue?@action=redirect&bpo=24952]: Clarify the default size argument of stack_size() in the «threading» and «_thread» modules. Patch from Mattip.

bpo-26014 [https://bugs.python.org/issue?@action=redirect&bpo=26014]: Update 3.x packaging documentation: * «See also» links to the new docs are now provided in the legacy pages * links to setuptools documentation have been updated

Tests

bpo-21916 [https://bugs.python.org/issue?@action=redirect&bpo=21916]: Added tests for the turtle module. Patch by ingrid, Gregory Loyse and Jelle Zijlstra.

bpo-26295 [https://bugs.python.org/issue?@action=redirect&bpo=26295]: When using «python3 -m test –testdir=TESTDIR», regrtest doesn’t add «test.» prefix to test module names.

bpo-26523 [https://bugs.python.org/issue?@action=redirect&bpo=26523]: The multiprocessing thread pool (multiprocessing.dummy.Pool) was untested.

bpo-26015 [https://bugs.python.org/issue?@action=redirect&bpo=26015]: Added new tests for pickling iterators of mutable sequences.

bpo-26325 [https://bugs.python.org/issue?@action=redirect&bpo=26325]: Added test.support.check_no_resource_warning() to check that no ResourceWarning is emitted.

bpo-25940 [https://bugs.python.org/issue?@action=redirect&bpo=25940]: Changed test_ssl to use its internal local server more. This avoids relying on svn.python.org, which recently changed root certificate.

bpo-25616 [https://bugs.python.org/issue?@action=redirect&bpo=25616]: Tests for OrderedDict are extracted from test_collections into separate file test_ordered_dict.

bpo-25449 [https://bugs.python.org/issue?@action=redirect&bpo=25449]: Added tests for OrderedDict subclasses.

bpo-25188 [https://bugs.python.org/issue?@action=redirect&bpo=25188]: Add -P/–pgo to test.regrtest to suppress error output when running the test suite for the purposes of a PGO build. Initial patch by Alecsandru Patrascu.

bpo-22806 [https://bugs.python.org/issue?@action=redirect&bpo=22806]: Add python -m test --list-tests command to list tests.

bpo-18174 [https://bugs.python.org/issue?@action=redirect&bpo=18174]: python -m test --huntrleaks ... now also checks for leak of file descriptors. Patch written by Richard Oudkerk.

bpo-25260 [https://bugs.python.org/issue?@action=redirect&bpo=25260]: Fix python -m test --coverage on Windows. Remove the list of ignored directories.

PCbuild\rt.bat now accepts an unlimited number of arguments to pass along to regrtest.py. Previously there was a limit of 9.

bpo-26583 [https://bugs.python.org/issue?@action=redirect&bpo=26583]: Skip test_timestamp_overflow in test_import if bytecode files cannot be written.

Build

bpo-21277 [https://bugs.python.org/issue?@action=redirect&bpo=21277]: Don’t try to link _ctypes with a ffi_convenience library.

bpo-26884 [https://bugs.python.org/issue?@action=redirect&bpo=26884]: Fix linking extension modules for cross builds. Patch by Xavier de Gaye.

bpo-26932 [https://bugs.python.org/issue?@action=redirect&bpo=26932]: Fixed support of RTLD_* constants defined as enum values, not via macros (in particular on Android). Patch by Chi Hsuan Yen.

bpo-22359 [https://bugs.python.org/issue?@action=redirect&bpo=22359]: Disable the rules for running _freeze_importlib and pgen when cross-compiling. The output of these programs is normally saved with the source code anyway, and is still regenerated when doing a native build. Patch by Xavier de Gaye.

bpo-21668 [https://bugs.python.org/issue?@action=redirect&bpo=21668]: Link audioop, _datetime, _ctypes_test modules to libm, except on Mac OS X. Patch written by Chi Hsuan Yen.

bpo-25702 [https://bugs.python.org/issue?@action=redirect&bpo=25702]: A –with-lto configure option has been added that will enable link time optimizations at build time during a make profile-opt. Some compilers and toolchains are known to not produce stable code when using LTO, be sure to test things thoroughly before relying on it. It can provide a few % speed up over profile-opt alone.

bpo-26624 [https://bugs.python.org/issue?@action=redirect&bpo=26624]: Adds validation of ucrtbase[d].dll version with warning for old versions.

bpo-17603 [https://bugs.python.org/issue?@action=redirect&bpo=17603]: Avoid error about nonexistent fileblocks.o file by using a lower-level check for st_blocks in struct stat.

bpo-26079 [https://bugs.python.org/issue?@action=redirect&bpo=26079]: Fixing the build output folder for tix-8.4.3.6. Patch by Bjoern Thiel.

bpo-26465 [https://bugs.python.org/issue?@action=redirect&bpo=26465]: Update Windows builds to use OpenSSL 1.0.2g.

bpo-25348 [https://bugs.python.org/issue?@action=redirect&bpo=25348]: Added --pgo and --pgo-job arguments to PCbuild\build.bat for building with Profile-Guided Optimization. The old PCbuild\build_pgo.bat script is removed.

bpo-25827 [https://bugs.python.org/issue?@action=redirect&bpo=25827]: Add support for building with ICC to configure, including a new --with-icc flag.

bpo-25696 [https://bugs.python.org/issue?@action=redirect&bpo=25696]: Fix installation of Python on UNIX with make -j9.

bpo-24986 [https://bugs.python.org/issue?@action=redirect&bpo=24986]: It is now possible to build Python on Windows without errors when external libraries are not available.

bpo-24421 [https://bugs.python.org/issue?@action=redirect&bpo=24421]: Compile Modules/_math.c once, before building extensions. Previously it could fail to compile properly if the math and cmath builds were concurrent.

bpo-26465 [https://bugs.python.org/issue?@action=redirect&bpo=26465]: Update OS X 10.5+ 32-bit-only installer to build and link with OpenSSL 1.0.2g.

bpo-26268 [https://bugs.python.org/issue?@action=redirect&bpo=26268]: Update Windows builds to use OpenSSL 1.0.2f.

bpo-25136 [https://bugs.python.org/issue?@action=redirect&bpo=25136]: Support Apple Xcode 7’s new textual SDK stub libraries.

bpo-24324 [https://bugs.python.org/issue?@action=redirect&bpo=24324]: Do not enable unreachable code warnings when using gcc as the option does not work correctly in older versions of gcc and has been silently removed as of gcc-4.5.

Windows

bpo-27053 [https://bugs.python.org/issue?@action=redirect&bpo=27053]: Updates make_zip.py to correctly generate library ZIP file.

bpo-26268 [https://bugs.python.org/issue?@action=redirect&bpo=26268]: Update the prepare_ssl.py script to handle OpenSSL releases that don’t include the contents of the include directory (that is, 1.0.2e and later).

bpo-26071 [https://bugs.python.org/issue?@action=redirect&bpo=26071]: bdist_wininst created binaries fail to start and find 32bit Python

bpo-26073 [https://bugs.python.org/issue?@action=redirect&bpo=26073]: Update the list of magic numbers in launcher

bpo-26065 [https://bugs.python.org/issue?@action=redirect&bpo=26065]: Excludes venv from library when generating embeddable distro.

bpo-25022 [https://bugs.python.org/issue?@action=redirect&bpo=25022]: Removed very outdated PC/example_nt/ directory.

Tools/Demos

bpo-26799 [https://bugs.python.org/issue?@action=redirect&bpo=26799]: Fix python-gdb.py: don’t get C types once when the Python code is loaded, but get C types on demand. The C types can change if python-gdb.py is loaded before the Python executable. Patch written by Thomas Ilsche.

bpo-26271 [https://bugs.python.org/issue?@action=redirect&bpo=26271]: Fix the Freeze tool to properly use flags passed through configure. Patch by Daniel Shaulov.

bpo-26489 [https://bugs.python.org/issue?@action=redirect&bpo=26489]: Add dictionary unpacking support to Tools/parser/unparse.py. Patch by Guo Ci Teo.

bpo-26316 [https://bugs.python.org/issue?@action=redirect&bpo=26316]: Fix variable name typo in Argument Clinic.

bpo-25440 [https://bugs.python.org/issue?@action=redirect&bpo=25440]: Fix output of python-config –extension-suffix.

bpo-25154 [https://bugs.python.org/issue?@action=redirect&bpo=25154]: The pyvenv script has been deprecated in favour of python3 -m venv.

C API

bpo-26312 [https://bugs.python.org/issue?@action=redirect&bpo=26312]: SystemError is now raised in all programming bugs with using PyArg_ParseTupleAndKeywords(). RuntimeError did raised before in some programming bugs.

bpo-26198 [https://bugs.python.org/issue?@action=redirect&bpo=26198]: ValueError is now raised instead of TypeError on buffer overflow in parsing «es#» and «et#» format units. SystemError is now raised instead of TypeError on programmatical error in parsing format string.

Python 3.5.5 final

Release date: 2018-02-04

There were no new changes in version 3.5.5.

Python 3.5.5 release candidate 1

Release date: 2018-01-23

Security

bpo-32551 [https://bugs.python.org/issue?@action=redirect&bpo=32551]: The sys.path[0] initialization change for bpo-29139 [https://bugs.python.org/issue?@action=redirect&bpo=29139] caused a regression by revealing an inconsistency in how sys.path is initialized when executing __main__ from a zipfile, directory, or other import location. This is considered a potential security issue, as it may lead to privileged processes unexpectedly loading code from user controlled directories in situations where that was not previously the case. The interpreter now consistently avoids ever adding the import location’s parent directory to sys.path, and ensures no other sys.path entries are inadvertently modified when inserting the import location named on the command line. (Originally reported as bpo-29723 [https://bugs.python.org/issue?@action=redirect&bpo=29723] against Python 3.6rc1, but it was missed at the time that the then upcoming Python 3.5.4 release would also be affected)

bpo-30657 [https://bugs.python.org/issue?@action=redirect&bpo=30657]: Fixed possible integer overflow in PyBytes_DecodeEscape, CVE-2017-1000158. Original patch by Jay Bosamiya; rebased to Python 3 by Miro Hrončok.

bpo-30947 [https://bugs.python.org/issue?@action=redirect&bpo=30947]: Upgrade libexpat embedded copy from version 2.2.1 to 2.2.3 to get security fixes.

Core and Builtins

bpo-31095 [https://bugs.python.org/issue?@action=redirect&bpo=31095]: Fix potential crash during GC caused by tp_dealloc which doesn’t call PyObject_GC_UnTrack().

Library

bpo-32072 [https://bugs.python.org/issue?@action=redirect&bpo=32072]: Fixed issues with binary plists: Fixed saving bytearrays. Identical objects will be saved only once. Equal references will be load as identical objects. Added support for saving and loading recursive data structures.

bpo-31170 [https://bugs.python.org/issue?@action=redirect&bpo=31170]: expat: Update libexpat from 2.2.3 to 2.2.4. Fix copying of partial characters for UTF-8 input (libexpat bug 115): https://github.com/libexpat/libexpat/issues/115

Python 3.5.4 final

Release date: 2017-08-07

Library

bpo-30119 [https://bugs.python.org/issue?@action=redirect&bpo=30119]: ftplib.FTP.putline() now throws ValueError on commands that contains CR or LF. Patch by Dong-hee Na.

Python 3.5.4 release candidate 1

Release date: 2017-07-23

Security

bpo-30730 [https://bugs.python.org/issue?@action=redirect&bpo=30730]: Prevent environment variables injection in subprocess on Windows. Prevent passing other environment variables and command arguments.

bpo-30694 [https://bugs.python.org/issue?@action=redirect&bpo=30694]: Upgrade expat copy from 2.2.0 to 2.2.1 to get fixes of multiple security vulnerabilities including: CVE-2017-9233 (External entity infinite loop DoS), CVE-2016-9063 (Integer overflow, re-fix), CVE-2016-0718 (Fix regression bugs from 2.2.0’s fix to CVE-2016-0718) and CVE-2012-0876 (Counter hash flooding with SipHash). Note: the CVE-2016-5300 (Use os-specific entropy sources like getrandom) doesn’t impact Python, since Python already gets entropy from the OS to set the expat secret using XML_SetHashSalt().

bpo-30500 [https://bugs.python.org/issue?@action=redirect&bpo=30500]: Fix urllib.parse.splithost() to correctly parse fragments. For example, splithost('//127.0.0.1#@evil.com/') now correctly returns the 127.0.0.1 host, instead of treating @evil.com as the host in an authentication (login@host).

bpo-29591 [https://bugs.python.org/issue?@action=redirect&bpo=29591]: Update expat copy from 2.1.1 to 2.2.0 to get fixes of CVE-2016-0718 and CVE-2016-4472. See https://sourceforge.net/p/expat/bugs/537/ for more information.

Core and Builtins

bpo-30876 [https://bugs.python.org/issue?@action=redirect&bpo=30876]: Relative import from unloaded package now reimports the package instead of failing with SystemError. Relative import from non-package now fails with ImportError rather than SystemError.

bpo-30765 [https://bugs.python.org/issue?@action=redirect&bpo=30765]: Avoid blocking in pthread_mutex_lock() when PyThread_acquire_lock() is asked not to block.

bpo-27945 [https://bugs.python.org/issue?@action=redirect&bpo=27945]: Fixed various segfaults with dict when input collections are mutated during searching, inserting or comparing. Based on patches by Duane Griffin and Tim Mitchell.

bpo-25794 [https://bugs.python.org/issue?@action=redirect&bpo=25794]: Fixed type.__setattr__() and type.__delattr__() for non-interned attribute names. Based on patch by Eryk Sun.

bpo-29935 [https://bugs.python.org/issue?@action=redirect&bpo=29935]: Fixed error messages in the index() method of tuple, list and deque when pass indices of wrong type.

bpo-28876 [https://bugs.python.org/issue?@action=redirect&bpo=28876]: bool(range) works even if len(range) raises OverflowError.

bpo-29600 [https://bugs.python.org/issue?@action=redirect&bpo=29600]: Fix wrapping coroutine return values in StopIteration.

bpo-29537 [https://bugs.python.org/issue?@action=redirect&bpo=29537]: Restore runtime compatibility with bytecode files generated by CPython 3.5.0 to 3.5.2, and adjust the eval loop to avoid the problems that could be caused by the malformed variant of the BUILD_MAP_UNPACK_WITH_CALL opcode that they may contain. Patch by Petr Viktorin, Serhiy Storchaka, and Nick Coghlan.

bpo-28598 [https://bugs.python.org/issue?@action=redirect&bpo=28598]: Support __rmod__ for subclasses of str being called before str.__mod__. Patch by Martijn Pieters.

bpo-29602 [https://bugs.python.org/issue?@action=redirect&bpo=29602]: Fix incorrect handling of signed zeros in complex constructor for complex subclasses and for inputs having a __complex__ method. Patch by Serhiy Storchaka.

bpo-29347 [https://bugs.python.org/issue?@action=redirect&bpo=29347]: Fixed possibly dereferencing undefined pointers when creating weakref objects.

bpo-29438 [https://bugs.python.org/issue?@action=redirect&bpo=29438]: Fixed use-after-free problem in key sharing dict.

bpo-29319 [https://bugs.python.org/issue?@action=redirect&bpo=29319]: Prevent RunMainFromImporter overwriting sys.path[0].

bpo-29337 [https://bugs.python.org/issue?@action=redirect&bpo=29337]: Fixed possible BytesWarning when compare the code objects. Warnings could be emitted at compile time.

bpo-29478 [https://bugs.python.org/issue?@action=redirect&bpo=29478]: If max_line_length=None is specified while using the Compat32 policy, it is no longer ignored. Patch by Mircea Cosbuc.

Library

bpo-29403 [https://bugs.python.org/issue?@action=redirect&bpo=29403]: Fix unittest.mock’s autospec to not fail on method-bound builtin functions. Patch by Aaron Gallagher.

bpo-30961 [https://bugs.python.org/issue?@action=redirect&bpo=30961]: Fix decrementing a borrowed reference in tracemalloc.

bpo-30886 [https://bugs.python.org/issue?@action=redirect&bpo=30886]: Fix multiprocessing.Queue.join_thread(): it now waits until the thread completes, even if the thread was started by the same process which created the queue.

bpo-29854 [https://bugs.python.org/issue?@action=redirect&bpo=29854]: Fix segfault in readline when using readline’s history-size option. Patch by Nir Soffer.

bpo-30807 [https://bugs.python.org/issue?@action=redirect&bpo=30807]: signal.setitimer() may disable the timer when passed a tiny value. Tiny values (such as 1e-6) are valid non-zero values for setitimer(), which is specified as taking microsecond-resolution intervals. However, on some platform, our conversion routine could convert 1e-6 into a zero interval, therefore disabling the timer instead of (re-)scheduling it.

bpo-30441 [https://bugs.python.org/issue?@action=redirect&bpo=30441]: Fix bug when modifying os.environ while iterating over it

bpo-30532 [https://bugs.python.org/issue?@action=redirect&bpo=30532]: Fix email header value parser dropping folding white space in certain cases.

bpo-29169 [https://bugs.python.org/issue?@action=redirect&bpo=29169]: Update zlib to 1.2.11.

bpo-30879 [https://bugs.python.org/issue?@action=redirect&bpo=30879]: os.listdir() and os.scandir() now emit bytes names when called with bytes-like argument.

bpo-30746 [https://bugs.python.org/issue?@action=redirect&bpo=30746]: Prohibited the “=” character in environment variable names in os.putenv() and os.spawn*().

bpo-29755 [https://bugs.python.org/issue?@action=redirect&bpo=29755]: Fixed the lgettext() family of functions in the gettext module. They now always return bytes.

bpo-30645 [https://bugs.python.org/issue?@action=redirect&bpo=30645]: Fix path calculation in imp.load_package(), fixing it for cases when a package is only shipped with bytecodes. Patch by Alexandru Ardelean.

bpo-23890 [https://bugs.python.org/issue?@action=redirect&bpo=23890]: unittest.TestCase.assertRaises() now manually breaks a reference cycle to not keep objects alive longer than expected.

bpo-30149 [https://bugs.python.org/issue?@action=redirect&bpo=30149]: inspect.signature() now supports callables with variable-argument parameters wrapped with partialmethod. Patch by Dong-hee Na.

bpo-29931 [https://bugs.python.org/issue?@action=redirect&bpo=29931]: Fixed comparison check for ipaddress.ip_interface objects. Patch by Sanjay Sundaresan.

bpo-24484 [https://bugs.python.org/issue?@action=redirect&bpo=24484]: Avoid race condition in multiprocessing cleanup.

bpo-28994 [https://bugs.python.org/issue?@action=redirect&bpo=28994]: The traceback no longer displayed for SystemExit raised in a callback registered by atexit.

bpo-30508 [https://bugs.python.org/issue?@action=redirect&bpo=30508]: Don’t log exceptions if Task/Future «cancel()» method was called.

bpo-28556 [https://bugs.python.org/issue?@action=redirect&bpo=28556]: Updates to typing module: Add generic AsyncContextManager, add support for ContextManager on all versions. Original PRs by Jelle Zijlstra and Ivan Levkivskyi

bpo-29870 [https://bugs.python.org/issue?@action=redirect&bpo=29870]: Fix ssl sockets leaks when connection is aborted in asyncio/ssl implementation. Patch by Michaël Sghaïer.

bpo-29743 [https://bugs.python.org/issue?@action=redirect&bpo=29743]: Closing transport during handshake process leaks open socket. Patch by Nikolay Kim

bpo-27585 [https://bugs.python.org/issue?@action=redirect&bpo=27585]: Fix waiter cancellation in asyncio.Lock. Patch by Mathieu Sornay.

bpo-30418 [https://bugs.python.org/issue?@action=redirect&bpo=30418]: On Windows, subprocess.Popen.communicate() now also ignore EINVAL on stdin.write() if the child process is still running but closed the pipe.

bpo-30378 [https://bugs.python.org/issue?@action=redirect&bpo=30378]: Fix the problem that logging.handlers.SysLogHandler cannot handle IPv6 addresses.

bpo-29960 [https://bugs.python.org/issue?@action=redirect&bpo=29960]: Preserve generator state when _random.Random.setstate() raises an exception. Patch by Bryan Olson.

bpo-30414 [https://bugs.python.org/issue?@action=redirect&bpo=30414]: multiprocessing.Queue._feed background running thread do not break from main loop on exception.

bpo-30003 [https://bugs.python.org/issue?@action=redirect&bpo=30003]: Fix handling escape characters in HZ codec. Based on patch by Ma Lin.

bpo-30301 [https://bugs.python.org/issue?@action=redirect&bpo=30301]: Fix AttributeError when using SimpleQueue.empty() under spawn and forkserver start methods.

bpo-30329 [https://bugs.python.org/issue?@action=redirect&bpo=30329]: imaplib and poplib now catch the Windows socket WSAEINVAL error (code 10022) on shutdown(SHUT_RDWR): An invalid operation was attempted. This error occurs sometimes on SSL connections.

bpo-30375 [https://bugs.python.org/issue?@action=redirect&bpo=30375]: Warnings emitted when compile a regular expression now always point to the line in the user code. Previously they could point into inners of the re module if emitted from inside of groups or conditionals.

bpo-30048 [https://bugs.python.org/issue?@action=redirect&bpo=30048]: Fixed Task.cancel() can be ignored when the task is running coroutine and the coroutine returned without any more await.

bpo-29990 [https://bugs.python.org/issue?@action=redirect&bpo=29990]: Fix range checking in GB18030 decoder. Original patch by Ma Lin.

bpo-26293 [https://bugs.python.org/issue?@action=redirect&bpo=26293]: Change resulted because of zipfile breakage. (See also: bpo-29094 [https://bugs.python.org/issue?@action=redirect&bpo=29094])

bpo-30243 [https://bugs.python.org/issue?@action=redirect&bpo=30243]: Removed the __init__ methods of _json’s scanner and encoder. Misusing them could cause memory leaks or crashes. Now scanner and encoder objects are completely initialized in the __new__ methods.

bpo-30185 [https://bugs.python.org/issue?@action=redirect&bpo=30185]: Avoid KeyboardInterrupt tracebacks in forkserver helper process when Ctrl-C is received.

bpo-28556 [https://bugs.python.org/issue?@action=redirect&bpo=28556]: Various updates to typing module: add typing.NoReturn type, use WrapperDescriptorType, minor bug-fixes. Original PRs by Jim Fasarakis-Hilliard and Ivan Levkivskyi.

bpo-30205 [https://bugs.python.org/issue?@action=redirect&bpo=30205]: Fix getsockname() for unbound AF_UNIX sockets on Linux.

bpo-30070 [https://bugs.python.org/issue?@action=redirect&bpo=30070]: Fixed leaks and crashes in errors handling in the parser module.

bpo-30061 [https://bugs.python.org/issue?@action=redirect&bpo=30061]: Fixed crashes in IOBase methods __next__() and readlines() when readline() or __next__() respectively return non-sizeable object. Fixed possible other errors caused by not checking results of PyObject_Size(), PySequence_Size(), or PyMapping_Size().

bpo-30068 [https://bugs.python.org/issue?@action=redirect&bpo=30068]: _io._IOBase.readlines will check if it’s closed first when hint is present.

bpo-29694 [https://bugs.python.org/issue?@action=redirect&bpo=29694]: Fixed race condition in pathlib mkdir with flags parents=True. Patch by Armin Rigo.

bpo-29692 [https://bugs.python.org/issue?@action=redirect&bpo=29692]: Fixed arbitrary unchaining of RuntimeError exceptions in contextlib.contextmanager. Patch by Siddharth Velankar.

bpo-29998 [https://bugs.python.org/issue?@action=redirect&bpo=29998]: Pickling and copying ImportError now preserves name and path attributes.

bpo-29942 [https://bugs.python.org/issue?@action=redirect&bpo=29942]: Fix a crash in itertools.chain.from_iterable when encountering long runs of empty iterables.

bpo-27863 [https://bugs.python.org/issue?@action=redirect&bpo=27863]: Fixed multiple crashes in ElementTree caused by race conditions and wrong types.

bpo-28699 [https://bugs.python.org/issue?@action=redirect&bpo=28699]: Fixed a bug in pools in multiprocessing.pool that raising an exception at the very first of an iterable may swallow the exception or make the program hang. Patch by Davin Potts and Xiang Zhang.

bpo-25803 [https://bugs.python.org/issue?@action=redirect&bpo=25803]: Avoid incorrect errors raised by Path.mkdir(exist_ok=True) when the OS gives priority to errors such as EACCES over EEXIST.

bpo-29861 [https://bugs.python.org/issue?@action=redirect&bpo=29861]: Release references to tasks, their arguments and their results as soon as they are finished in multiprocessing.Pool.

bpo-29884 [https://bugs.python.org/issue?@action=redirect&bpo=29884]: faulthandler: Restore the old sigaltstack during teardown. Patch by Christophe Zeitouny.

bpo-25455 [https://bugs.python.org/issue?@action=redirect&bpo=25455]: Fixed crashes in repr of recursive buffered file-like objects.

bpo-29800 [https://bugs.python.org/issue?@action=redirect&bpo=29800]: Fix crashes in partial.__repr__ if the keys of partial.keywords are not strings. Patch by Michael Seifert.

bpo-29742 [https://bugs.python.org/issue?@action=redirect&bpo=29742]: get_extra_info() raises exception if get called on closed ssl transport. Patch by Nikolay Kim.

bpo-8256 [https://bugs.python.org/issue?@action=redirect&bpo=8256]: Fixed possible failing or crashing input() if attributes «encoding» or «errors» of sys.stdin or sys.stdout are not set or are not strings.

bpo-28298 [https://bugs.python.org/issue?@action=redirect&bpo=28298]: Fix a bug that prevented array “Q”, “L” and “I” from accepting big intables (objects that have __int__) as elements. Patch by Oren Milman.

bpo-29615 [https://bugs.python.org/issue?@action=redirect&bpo=29615]: SimpleXMLRPCDispatcher no longer chains KeyError (or any other exception) to exception(s) raised in the dispatched methods. Patch by Petr Motejlek.

bpo-29704 [https://bugs.python.org/issue?@action=redirect&bpo=29704]: asyncio.subprocess.SubprocessStreamProtocol no longer closes before all pipes are closed.

bpo-29703 [https://bugs.python.org/issue?@action=redirect&bpo=29703]: Fix asyncio to support instantiation of new event loops in child processes.

bpo-29376 [https://bugs.python.org/issue?@action=redirect&bpo=29376]: Fix assertion error in threading._DummyThread.is_alive().

bpo-29110 [https://bugs.python.org/issue?@action=redirect&bpo=29110]: Fix file object leak in aifc.open() when file is given as a filesystem path and is not in valid AIFF format. Patch by Anthony Zhang.

bpo-28961 [https://bugs.python.org/issue?@action=redirect&bpo=28961]: Fix unittest.mock._Call helper: don’t ignore the name parameter anymore. Patch written by Jiajun Huang.

bpo-29532 [https://bugs.python.org/issue?@action=redirect&bpo=29532]: Altering a kwarg dictionary passed to functools.partial() no longer affects a partial object after creation.

bpo-28556 [https://bugs.python.org/issue?@action=redirect&bpo=28556]: Various updates to typing module: typing.Counter, typing.ChainMap, improved ABC caching, etc. Original PRs by Jelle Zijlstra, Ivan Levkivskyi, Manuel Krebber, and Łukasz Langa.

bpo-29100 [https://bugs.python.org/issue?@action=redirect&bpo=29100]: Fix datetime.fromtimestamp() regression introduced in Python 3.6.0: check minimum and maximum years.

bpo-29519 [https://bugs.python.org/issue?@action=redirect&bpo=29519]: Fix weakref spewing exceptions during interpreter shutdown when used with a rare combination of multiprocessing and custom codecs.

bpo-29416 [https://bugs.python.org/issue?@action=redirect&bpo=29416]: Prevent infinite loop in pathlib.Path.mkdir

bpo-29444 [https://bugs.python.org/issue?@action=redirect&bpo=29444]: Fixed out-of-bounds buffer access in the group() method of the match object. Based on patch by WGH.

bpo-29335 [https://bugs.python.org/issue?@action=redirect&bpo=29335]: Fix subprocess.Popen.wait() when the child process has exited to a stopped instead of terminated state (ex: when under ptrace).

bpo-29290 [https://bugs.python.org/issue?@action=redirect&bpo=29290]: Fix a regression in argparse that help messages would wrap at non-breaking spaces.

bpo-28735 [https://bugs.python.org/issue?@action=redirect&bpo=28735]: Fixed the comparison of mock.MagickMock with mock.ANY.

bpo-29011 [https://bugs.python.org/issue?@action=redirect&bpo=29011]: Fix an important omission by adding Deque to the typing module.

bpo-29219 [https://bugs.python.org/issue?@action=redirect&bpo=29219]: Fixed infinite recursion in the repr of uninitialized ctypes.CDLL instances.

bpo-28969 [https://bugs.python.org/issue?@action=redirect&bpo=28969]: Fixed race condition in C implementation of functools.lru_cache. KeyError could be raised when cached function with full cache was simultaneously called from different threads with the same uncached arguments.

bpo-29142 [https://bugs.python.org/issue?@action=redirect&bpo=29142]: In urllib.request, suffixes in no_proxy environment variable with leading dots could match related hostnames again (e.g. .b.c matches a.b.c). Patch by Milan Oberkirch.

Documentation

bpo-30176 [https://bugs.python.org/issue?@action=redirect&bpo=30176]: Add missing attribute related constants in curses documentation.

bpo-26985 [https://bugs.python.org/issue?@action=redirect&bpo=26985]: Add missing info of code object in inspect documentation.

bpo-28929 [https://bugs.python.org/issue?@action=redirect&bpo=28929]: Link the documentation to its source file on GitHub.

bpo-25008 [https://bugs.python.org/issue?@action=redirect&bpo=25008]: Document smtpd.py as effectively deprecated and add a pointer to aiosmtpd, a third-party asyncio-based replacement.

bpo-26355 [https://bugs.python.org/issue?@action=redirect&bpo=26355]: Add canonical header link on each page to corresponding major version of the documentation. Patch by Matthias Bussonnier.

bpo-29349 [https://bugs.python.org/issue?@action=redirect&bpo=29349]: Fix Python 2 syntax in code for building the documentation.

Tests

bpo-30822 [https://bugs.python.org/issue?@action=redirect&bpo=30822]: Fix regrtest command line parser to allow passing -u extralargefile to run test_zipfile64.

bpo-30383 [https://bugs.python.org/issue?@action=redirect&bpo=30383]: regrtest: Enhance regrtest and backport features from the master branch. Add options: –coverage, –testdir, –list-tests (list test files, don’t run them), –list-cases (list test identifiers, don’t run them, bpo-30523 [https://bugs.python.org/issue?@action=redirect&bpo=30523]), –matchfile (load a list of test filters from a text file, bpo-30540 [https://bugs.python.org/issue?@action=redirect&bpo=30540]), –slowest (alias to –slow). Enhance output: add timestamp, test result, currently running tests, «Tests result: xxx» summary with total duration, etc. Fix reference leak hunting in regrtest, –huntrleaks: regrtest now warms up caches, create explicitly all internal singletons which are created on demand to prevent false positives when checking for reference leaks. (bpo-30675 [https://bugs.python.org/issue?@action=redirect&bpo=30675]).

bpo-30357 [https://bugs.python.org/issue?@action=redirect&bpo=30357]: test_thread: setUp() now uses support.threading_setup() and support.threading_cleanup() to wait until threads complete to avoid random side effects on following tests. Initial patch written by Grzegorz Grzywacz.

bpo-28087 [https://bugs.python.org/issue?@action=redirect&bpo=28087]: Skip test_asyncore and test_eintr poll failures on macOS. Skip some tests of select.poll when running on macOS due to unresolved issues with the underlying system poll function on some macOS versions.

bpo-30197 [https://bugs.python.org/issue?@action=redirect&bpo=30197]: Enhanced functions swap_attr() and swap_item() in the test.support module. They now work when delete replaced attribute or item inside the with statement. The old value of the attribute or item (or None if it doesn’t exist) now will be assigned to the target of the «as» clause, if there is one.

bpo-29571 [https://bugs.python.org/issue?@action=redirect&bpo=29571]: to match the behaviour of the re.LOCALE flag, test_re.test_locale_flag now uses locale.getpreferredencoding(False) to determine the candidate encoding for the test regex (allowing it to correctly skip the test when the default locale encoding is a multi-byte encoding)

Build

bpo-29243 [https://bugs.python.org/issue?@action=redirect&bpo=29243]: Prevent unnecessary rebuilding of Python during make test, make install and some other make targets when configured with --enable-optimizations.

bpo-23404 [https://bugs.python.org/issue?@action=redirect&bpo=23404]: Don’t regenerate generated files based on file modification time anymore: the action is now explicit. Replace make touch with make regen-all.

bpo-29643 [https://bugs.python.org/issue?@action=redirect&bpo=29643]: Fix --enable-optimization didn’t work.

Windows

bpo-30687 [https://bugs.python.org/issue?@action=redirect&bpo=30687]: Locate msbuild.exe on Windows when building rather than vcvarsall.bat

bpo-29392 [https://bugs.python.org/issue?@action=redirect&bpo=29392]: Prevent crash when passing invalid arguments into msvcrt module.

C API

bpo-27867 [https://bugs.python.org/issue?@action=redirect&bpo=27867]: Function PySlice_GetIndicesEx() is replaced with a macro if Py_LIMITED_API is set to the value between 0x03050400 and 0x03060000 (not including) or 0x03060100 or higher.

bpo-29083 [https://bugs.python.org/issue?@action=redirect&bpo=29083]: Fixed the declaration of some public API functions. PyArg_VaParse() and PyArg_VaParseTupleAndKeywords() were not available in limited API. PyArg_ValidateKeywordArguments(), PyArg_UnpackTuple() and Py_BuildValue() were not available in limited API of version < 3.3 when PY_SSIZE_T_CLEAN is defined.

Python 3.5.3 final

Release date: 2017-01-17

There were no code changes between 3.5.3rc1 and 3.5.3 final.

Python 3.5.3 release candidate 1

Release date: 2017-01-02

Security

bpo-27278 [https://bugs.python.org/issue?@action=redirect&bpo=27278]: Fix os.urandom() implementation using getrandom() on Linux. Truncate size to INT_MAX and loop until we collected enough random bytes, instead of casting a directly Py_ssize_t to int.

bpo-22636 [https://bugs.python.org/issue?@action=redirect&bpo=22636]: Avoid shell injection problems with ctypes.util.find_library().

Core and Builtins

bpo-29073 [https://bugs.python.org/issue?@action=redirect&bpo=29073]: bytearray formatting no longer truncates on first null byte.

bpo-28932 [https://bugs.python.org/issue?@action=redirect&bpo=28932]: Do not include <sys/random.h> if it does not exist.

bpo-28147 [https://bugs.python.org/issue?@action=redirect&bpo=28147]: Fix a memory leak in split-table dictionaries: setattr() must not convert combined table into split table.

bpo-25677 [https://bugs.python.org/issue?@action=redirect&bpo=25677]: Correct the positioning of the syntax error caret for indented blocks. Based on patch by Michael Layzell.

bpo-29000 [https://bugs.python.org/issue?@action=redirect&bpo=29000]: Fixed bytes formatting of octals with zero padding in alternate form.

bpo-28512 [https://bugs.python.org/issue?@action=redirect&bpo=28512]: Fixed setting the offset attribute of SyntaxError by PyErr_SyntaxLocationEx() and PyErr_SyntaxLocationObject().

bpo-28991 [https://bugs.python.org/issue?@action=redirect&bpo=28991]: functools.lru_cache() was susceptible to an obscure reentrancy bug caused by a monkey-patched len() function.

bpo-28648 [https://bugs.python.org/issue?@action=redirect&bpo=28648]: Fixed crash in Py_DecodeLocale() in debug build on Mac OS X when decode astral characters. Patch by Xiang Zhang.

bpo-19398 [https://bugs.python.org/issue?@action=redirect&bpo=19398]: Extra slash no longer added to sys.path components in case of empty compile-time PYTHONPATH components.

bpo-28426 [https://bugs.python.org/issue?@action=redirect&bpo=28426]: Fixed potential crash in PyUnicode_AsDecodedObject() in debug build.

bpo-23782 [https://bugs.python.org/issue?@action=redirect&bpo=23782]: Fixed possible memory leak in _PyTraceback_Add() and exception loss in PyTraceBack_Here().

bpo-28379 [https://bugs.python.org/issue?@action=redirect&bpo=28379]: Added sanity checks and tests for PyUnicode_CopyCharacters(). Patch by Xiang Zhang.

bpo-28376 [https://bugs.python.org/issue?@action=redirect&bpo=28376]: The type of long range iterator is now registered as Iterator. Patch by Oren Milman.

bpo-28376 [https://bugs.python.org/issue?@action=redirect&bpo=28376]: The constructor of range_iterator now checks that step is not 0. Patch by Oren Milman.

bpo-26906 [https://bugs.python.org/issue?@action=redirect&bpo=26906]: Resolving special methods of uninitialized type now causes implicit initialization of the type instead of a fail.

bpo-18287 [https://bugs.python.org/issue?@action=redirect&bpo=18287]: PyType_Ready() now checks that tp_name is not NULL. Original patch by Niklas Koep.

bpo-24098 [https://bugs.python.org/issue?@action=redirect&bpo=24098]: Fixed possible crash when AST is changed in process of compiling it.

bpo-28350 [https://bugs.python.org/issue?@action=redirect&bpo=28350]: String constants with null character no longer interned.

bpo-26617 [https://bugs.python.org/issue?@action=redirect&bpo=26617]: Fix crash when GC runs during weakref callbacks.

bpo-27942 [https://bugs.python.org/issue?@action=redirect&bpo=27942]: String constants now interned recursively in tuples and frozensets.

bpo-21578 [https://bugs.python.org/issue?@action=redirect&bpo=21578]: Fixed misleading error message when ImportError called with invalid keyword args.

bpo-28203 [https://bugs.python.org/issue?@action=redirect&bpo=28203]: Fix incorrect type in error message from complex(1.0, {2:3}). Patch by Soumya Sharma.

bpo-27955 [https://bugs.python.org/issue?@action=redirect&bpo=27955]: Fallback on reading /dev/urandom device when the getrandom() syscall fails with EPERM, for example when blocked by SECCOMP.

bpo-28131 [https://bugs.python.org/issue?@action=redirect&bpo=28131]: Fix a regression in zipimport’s compile_source(). zipimport should use the same optimization level as the interpreter.

bpo-25221 [https://bugs.python.org/issue?@action=redirect&bpo=25221]: Fix corrupted result from PyLong_FromLong(0) when Python is compiled with NSMALLPOSINTS = 0.

bpo-25758 [https://bugs.python.org/issue?@action=redirect&bpo=25758]: Prevents zipimport from unnecessarily encoding a filename (patch by Eryk Sun)

bpo-28189 [https://bugs.python.org/issue?@action=redirect&bpo=28189]: dictitems_contains no longer swallows compare errors. (Patch by Xiang Zhang)

bpo-27812 [https://bugs.python.org/issue?@action=redirect&bpo=27812]: Properly clear out a generator’s frame’s backreference to the generator to prevent crashes in frame.clear().

bpo-27811 [https://bugs.python.org/issue?@action=redirect&bpo=27811]: Fix a crash when a coroutine that has not been awaited is finalized with warnings-as-errors enabled.

bpo-27587 [https://bugs.python.org/issue?@action=redirect&bpo=27587]: Fix another issue found by PVS-Studio: Null pointer check after use of “def” in _PyState_AddModule(). Initial patch by Christian Heimes.

bpo-26020 [https://bugs.python.org/issue?@action=redirect&bpo=26020]: set literal evaluation order did not match documented behaviour.

bpo-27782 [https://bugs.python.org/issue?@action=redirect&bpo=27782]: Multi-phase extension module import now correctly allows the m_methods field to be used to add module level functions to instances of non-module types returned from Py_create_mod. Patch by Xiang Zhang.

bpo-27936 [https://bugs.python.org/issue?@action=redirect&bpo=27936]: The round() function accepted a second None argument for some types but not for others. Fixed the inconsistency by accepting None for all numeric types.

bpo-27487 [https://bugs.python.org/issue?@action=redirect&bpo=27487]: Warn if a submodule argument to «python -m» or runpy.run_module() is found in sys.modules after parent packages are imported, but before the submodule is executed.

bpo-27558 [https://bugs.python.org/issue?@action=redirect&bpo=27558]: Fix a SystemError in the implementation of «raise» statement. In a brand new thread, raise a RuntimeError since there is no active exception to reraise. Patch written by Xiang Zhang.

bpo-27419 [https://bugs.python.org/issue?@action=redirect&bpo=27419]: Standard __import__() no longer look up «__import__» in globals or builtins for importing submodules or «from import». Fixed handling an error of non-string package name.

bpo-27083 [https://bugs.python.org/issue?@action=redirect&bpo=27083]: Respect the PYTHONCASEOK environment variable under Windows.

bpo-27514 [https://bugs.python.org/issue?@action=redirect&bpo=27514]: Make having too many statically nested blocks a SyntaxError instead of SystemError.

bpo-27473 [https://bugs.python.org/issue?@action=redirect&bpo=27473]: Fixed possible integer overflow in bytes and bytearray concatenations. Patch by Xiang Zhang.

bpo-27507 [https://bugs.python.org/issue?@action=redirect&bpo=27507]: Add integer overflow check in bytearray.extend(). Patch by Xiang Zhang.

bpo-27581 [https://bugs.python.org/issue?@action=redirect&bpo=27581]: Don’t rely on wrapping for overflow check in PySequence_Tuple(). Patch by Xiang Zhang.

bpo-27443 [https://bugs.python.org/issue?@action=redirect&bpo=27443]: __length_hint__() of bytearray iterators no longer return a negative integer for a resized bytearray.

bpo-27942 [https://bugs.python.org/issue?@action=redirect&bpo=27942]: Fix memory leak in codeobject.c

Library

bpo-15812 [https://bugs.python.org/issue?@action=redirect&bpo=15812]: inspect.getframeinfo() now correctly shows the first line of a context. Patch by Sam Breese.

bpo-29094 [https://bugs.python.org/issue?@action=redirect&bpo=29094]: Offsets in a ZIP file created with extern file object and modes «w» and «x» now are relative to the start of the file.

bpo-13051 [https://bugs.python.org/issue?@action=redirect&bpo=13051]: Fixed recursion errors in large or resized curses.textpad.Textbox. Based on patch by Tycho Andersen.

bpo-29119 [https://bugs.python.org/issue?@action=redirect&bpo=29119]: Fix weakrefs in the pure python version of collections.OrderedDict move_to_end() method. Contributed by Andra Bogildea.

bpo-9770 [https://bugs.python.org/issue?@action=redirect&bpo=9770]: curses.ascii predicates now work correctly with negative integers.

bpo-28427 [https://bugs.python.org/issue?@action=redirect&bpo=28427]: old keys should not remove new values from WeakValueDictionary when collecting from another thread.

bpo-28923 [https://bugs.python.org/issue?@action=redirect&bpo=28923]: Remove editor artifacts from Tix.py.

bpo-28871 [https://bugs.python.org/issue?@action=redirect&bpo=28871]: Fixed a crash when deallocate deep ElementTree.

bpo-19542 [https://bugs.python.org/issue?@action=redirect&bpo=19542]: Fix bugs in WeakValueDictionary.setdefault() and WeakValueDictionary.pop() when a GC collection happens in another thread.

bpo-20191 [https://bugs.python.org/issue?@action=redirect&bpo=20191]: Fixed a crash in resource.prlimit() when pass a sequence that doesn’t own its elements as limits.

bpo-28779 [https://bugs.python.org/issue?@action=redirect&bpo=28779]: multiprocessing.set_forkserver_preload() would crash the forkserver process if a preloaded module instantiated some multiprocessing objects such as locks.

bpo-28847 [https://bugs.python.org/issue?@action=redirect&bpo=28847]: dbm.dumb now supports reading read-only files and no longer writes the index file when it is not changed.

bpo-25659 [https://bugs.python.org/issue?@action=redirect&bpo=25659]: In ctypes, prevent a crash calling the from_buffer() and from_buffer_copy() methods on abstract classes like Array.

bpo-28732 [https://bugs.python.org/issue?@action=redirect&bpo=28732]: Fix crash in os.spawnv() with no elements in args

bpo-28485 [https://bugs.python.org/issue?@action=redirect&bpo=28485]: Always raise ValueError for negative compileall.compile_dir(workers=…) parameter, even when multithreading is unavailable.

bpo-28387 [https://bugs.python.org/issue?@action=redirect&bpo=28387]: Fixed possible crash in _io.TextIOWrapper deallocator when the garbage collector is invoked in other thread. Based on patch by Sebastian Cufre.

bpo-27517 [https://bugs.python.org/issue?@action=redirect&bpo=27517]: LZMA compressor and decompressor no longer raise exceptions if given empty data twice. Patch by Benjamin Fogle.

bpo-28549 [https://bugs.python.org/issue?@action=redirect&bpo=28549]: Fixed segfault in curses’s addch() with ncurses6.

bpo-28449 [https://bugs.python.org/issue?@action=redirect&bpo=28449]: tarfile.open() with mode «r» or «r:» now tries to open a tar file with compression before trying to open it without compression. Otherwise it had 50% chance failed with ignore_zeros=True.

bpo-23262 [https://bugs.python.org/issue?@action=redirect&bpo=23262]: The webbrowser module now supports Firefox 36+ and derived browsers. Based on patch by Oleg Broytman.

bpo-27939 [https://bugs.python.org/issue?@action=redirect&bpo=27939]: Fixed bugs in tkinter.ttk.LabeledScale and tkinter.Scale caused by representing the scale as float value internally in Tk. tkinter.IntVar now works if float value is set to underlying Tk variable.

bpo-28255 [https://bugs.python.org/issue?@action=redirect&bpo=28255]: calendar.TextCalendar().prmonth() no longer prints a space at the start of new line after printing a month’s calendar. Patch by Xiang Zhang.

bpo-20491 [https://bugs.python.org/issue?@action=redirect&bpo=20491]: The textwrap.TextWrapper class now honors non-breaking spaces. Based on patch by Kaarle Ritvanen.

bpo-28353 [https://bugs.python.org/issue?@action=redirect&bpo=28353]: os.fwalk() no longer fails on broken links.

bpo-25464 [https://bugs.python.org/issue?@action=redirect&bpo=25464]: Fixed HList.header_exists() in tkinter.tix module by addin a workaround to Tix library bug.

bpo-28488 [https://bugs.python.org/issue?@action=redirect&bpo=28488]: shutil.make_archive() no longer add entry «./» to ZIP archive.

bpo-24452 [https://bugs.python.org/issue?@action=redirect&bpo=24452]: Make webbrowser support Chrome on Mac OS X.

bpo-20766 [https://bugs.python.org/issue?@action=redirect&bpo=20766]: Fix references leaked by pdb in the handling of SIGINT handlers.

bpo-26293 [https://bugs.python.org/issue?@action=redirect&bpo=26293]: Fixed writing ZIP files that starts not from the start of the file. Offsets in ZIP file now are relative to the start of the archive in conforming to the specification.

bpo-28321 [https://bugs.python.org/issue?@action=redirect&bpo=28321]: Fixed writing non-BMP characters with binary format in plistlib.

bpo-28322 [https://bugs.python.org/issue?@action=redirect&bpo=28322]: Fixed possible crashes when unpickle itertools objects from incorrect pickle data. Based on patch by John Leitch.

Fix possible integer overflows and crashes in the mmap module with unusual usage patterns.

bpo-1703178 [https://bugs.python.org/issue?@action=redirect&bpo=1703178]: Fix the ability to pass the –link-objects option to the distutils build_ext command.

bpo-28253 [https://bugs.python.org/issue?@action=redirect&bpo=28253]: Fixed calendar functions for extreme months: 0001-01 and 9999-12. Methods itermonthdays() and itermonthdays2() are reimplemented so that they don’t call itermonthdates() which can cause datetime.date under/overflow.

bpo-28275 [https://bugs.python.org/issue?@action=redirect&bpo=28275]: Fixed possible use after free in the decompress() methods of the LZMADecompressor and BZ2Decompressor classes. Original patch by John Leitch.

bpo-27897 [https://bugs.python.org/issue?@action=redirect&bpo=27897]: Fixed possible crash in sqlite3.Connection.create_collation() if pass invalid string-like object as a name. Patch by Xiang Zhang.

bpo-18893 [https://bugs.python.org/issue?@action=redirect&bpo=18893]: Fix invalid exception handling in Lib/ctypes/macholib/dyld.py. Patch by Madison May.

bpo-27611 [https://bugs.python.org/issue?@action=redirect&bpo=27611]: Fixed support of default root window in the tkinter.tix module.

bpo-27348 [https://bugs.python.org/issue?@action=redirect&bpo=27348]: In the traceback module, restore the formatting of exception messages like «Exception: None». This fixes a regression introduced in 3.5a2.

bpo-25651 [https://bugs.python.org/issue?@action=redirect&bpo=25651]: Allow falsy values to be used for msg parameter of subTest().

bpo-27932 [https://bugs.python.org/issue?@action=redirect&bpo=27932]: Prevent memory leak in win32_ver().

Fix UnboundLocalError in socket._sendfile_use_sendfile.

bpo-28075 [https://bugs.python.org/issue?@action=redirect&bpo=28075]: Check for ERROR_ACCESS_DENIED in Windows implementation of os.stat(). Patch by Eryk Sun.

bpo-25270 [https://bugs.python.org/issue?@action=redirect&bpo=25270]: Prevent codecs.escape_encode() from raising SystemError when an empty bytestring is passed.

bpo-28181 [https://bugs.python.org/issue?@action=redirect&bpo=28181]: Get antigravity over HTTPS. Patch by Kaartic Sivaraam.

bpo-25895 [https://bugs.python.org/issue?@action=redirect&bpo=25895]: Enable WebSocket URL schemes in urllib.parse.urljoin. Patch by Gergely Imreh and Markus Holtermann.

bpo-27599 [https://bugs.python.org/issue?@action=redirect&bpo=27599]: Fixed buffer overrun in binascii.b2a_qp() and binascii.a2b_qp().

bpo-19003 [https://bugs.python.org/issue?@action=redirect&bpo=19003]: m email.generator now replaces only \r and/or \n line endings, per the RFC, instead of all unicode line endings.

bpo-28019 [https://bugs.python.org/issue?@action=redirect&bpo=28019]: itertools.count() no longer rounds non-integer step in range between 1.0 and 2.0 to 1.

bpo-25969 [https://bugs.python.org/issue?@action=redirect&bpo=25969]: Update the lib2to3 grammar to handle the unpacking generalizations added in 3.5.

bpo-14977 [https://bugs.python.org/issue?@action=redirect&bpo=14977]: mailcap now respects the order of the lines in the mailcap files («first match»), as required by RFC 1542. Patch by Michael Lazar.

bpo-24594 [https://bugs.python.org/issue?@action=redirect&bpo=24594]: Validates persist parameter when opening MSI database

bpo-17582 [https://bugs.python.org/issue?@action=redirect&bpo=17582]: xml.etree.ElementTree nows preserves whitespaces in attributes (Patch by Duane Griffin. Reviewed and approved by Stefan Behnel.)

bpo-28047 [https://bugs.python.org/issue?@action=redirect&bpo=28047]: Fixed calculation of line length used for the base64 CTE in the new email policies.

bpo-27445 [https://bugs.python.org/issue?@action=redirect&bpo=27445]: Don’t pass str(_charset) to MIMEText.set_payload(). Patch by Claude Paroz.

bpo-22450 [https://bugs.python.org/issue?@action=redirect&bpo=22450]: urllib now includes an Accept: */* header among the default headers. This makes the results of REST API requests more consistent and predictable especially when proxy servers are involved.

lib2to3.pgen3.driver.load_grammar() now creates a stable cache file between runs given the same Grammar.txt input regardless of the hash randomization setting.

bpo-27570 [https://bugs.python.org/issue?@action=redirect&bpo=27570]: Avoid zero-length memcpy() etc calls with null source pointers in the «ctypes» and «array» modules.

bpo-22233 [https://bugs.python.org/issue?@action=redirect&bpo=22233]: Break email header lines only on the RFC specified CR and LF characters, not on arbitrary unicode line breaks. This also fixes a bug in HTTP header parsing.

bpo-27988 [https://bugs.python.org/issue?@action=redirect&bpo=27988]: Fix email iter_attachments incorrect mutation of payload list.

bpo-27691 [https://bugs.python.org/issue?@action=redirect&bpo=27691]: Fix ssl module’s parsing of GEN_RID subject alternative name fields in X.509 certs.

bpo-27850 [https://bugs.python.org/issue?@action=redirect&bpo=27850]: Remove 3DES from ssl module’s default cipher list to counter measure sweet32 attack (CVE-2016-2183).

bpo-27766 [https://bugs.python.org/issue?@action=redirect&bpo=27766]: Add ChaCha20 Poly1305 to ssl module’s default cipher list. (Required OpenSSL 1.1.0 or LibreSSL).

bpo-26470 [https://bugs.python.org/issue?@action=redirect&bpo=26470]: Port ssl and hashlib module to OpenSSL 1.1.0.

Remove support for passing a file descriptor to os.access. It never worked but previously didn’t raise.

bpo-12885 [https://bugs.python.org/issue?@action=redirect&bpo=12885]: Fix error when distutils encounters symlink.

bpo-27881 [https://bugs.python.org/issue?@action=redirect&bpo=27881]: Fixed possible bugs when setting sqlite3.Connection.isolation_level. Based on patch by Xiang Zhang.

bpo-27861 [https://bugs.python.org/issue?@action=redirect&bpo=27861]: Fixed a crash in sqlite3.Connection.cursor() when a factory creates not a cursor. Patch by Xiang Zhang.

bpo-19884 [https://bugs.python.org/issue?@action=redirect&bpo=19884]: Avoid spurious output on OS X with Gnu Readline.

bpo-27706 [https://bugs.python.org/issue?@action=redirect&bpo=27706]: Restore deterministic behavior of random.Random().seed() for string seeds using seeding version 1. Allows sequences of calls to random() to exactly match those obtained in Python 2. Patch by Nofar Schnider.

bpo-10513 [https://bugs.python.org/issue?@action=redirect&bpo=10513]: Fix a regression in Connection.commit(). Statements should not be reset after a commit.

A new version of typing.py from https://github.com/python/typing: Collection (only for 3.6) (bpo-27598 [https://bugs.python.org/issue?@action=redirect&bpo=27598]). Add FrozenSet to __all__ (upstream #261). Fix crash in _get_type_vars() (upstream #259). Remove the dict constraint in ForwardRef._eval_type (upstream #252).

bpo-27539 [https://bugs.python.org/issue?@action=redirect&bpo=27539]: Fix unnormalised Fraction.__pow__ result in the case of negative exponent and negative base.

bpo-21718 [https://bugs.python.org/issue?@action=redirect&bpo=21718]: cursor.description is now available for queries using CTEs.

bpo-2466 [https://bugs.python.org/issue?@action=redirect&bpo=2466]: posixpath.ismount now correctly recognizes mount points which the user does not have permission to access.

bpo-27773 [https://bugs.python.org/issue?@action=redirect&bpo=27773]: Correct some memory management errors server_hostname in _ssl.wrap_socket().

bpo-26750 [https://bugs.python.org/issue?@action=redirect&bpo=26750]: unittest.mock.create_autospec() now works properly for subclasses of property() and other data descriptors.

In the curses module, raise an error if window.getstr() or window.instr() is passed a negative value.

bpo-27783 [https://bugs.python.org/issue?@action=redirect&bpo=27783]: Fix possible usage of uninitialized memory in operator.methodcaller.

bpo-27774 [https://bugs.python.org/issue?@action=redirect&bpo=27774]: Fix possible Py_DECREF on unowned object in _sre.

bpo-27760 [https://bugs.python.org/issue?@action=redirect&bpo=27760]: Fix possible integer overflow in binascii.b2a_qp.

bpo-27758 [https://bugs.python.org/issue?@action=redirect&bpo=27758]: Fix possible integer overflow in the _csv module for large record lengths.

bpo-27568 [https://bugs.python.org/issue?@action=redirect&bpo=27568]: Prevent HTTPoxy attack (CVE-2016-1000110). Ignore the HTTP_PROXY variable when REQUEST_METHOD environment is set, which indicates that the script is in CGI mode.

bpo-27656 [https://bugs.python.org/issue?@action=redirect&bpo=27656]: Do not assume sched.h defines any SCHED_* constants.

bpo-27130 [https://bugs.python.org/issue?@action=redirect&bpo=27130]: In the «zlib» module, fix handling of large buffers (typically 4 GiB) when compressing and decompressing. Previously, inputs were limited to 4 GiB, and compression and decompression operations did not properly handle results of 4 GiB.

bpo-27533 [https://bugs.python.org/issue?@action=redirect&bpo=27533]: Release GIL in nt._isdir

bpo-17711 [https://bugs.python.org/issue?@action=redirect&bpo=17711]: Fixed unpickling by the persistent ID with protocol 0. Original patch by Alexandre Vassalotti.

bpo-27522 [https://bugs.python.org/issue?@action=redirect&bpo=27522]: Avoid an unintentional reference cycle in email.feedparser.

bpo-26844 [https://bugs.python.org/issue?@action=redirect&bpo=26844]: Fix error message for imp.find_module() to refer to “path” instead of “name”. Patch by Lev Maximov.

bpo-23804 [https://bugs.python.org/issue?@action=redirect&bpo=23804]: Fix SSL zero-length recv() calls to not block and not raise an error about unclean EOF.

bpo-27466 [https://bugs.python.org/issue?@action=redirect&bpo=27466]: Change time format returned by http.cookie.time2netscape, confirming the netscape cookie format and making it consistent with documentation.

bpo-26664 [https://bugs.python.org/issue?@action=redirect&bpo=26664]: Fix activate.fish by removing mis-use of $.

bpo-22115 [https://bugs.python.org/issue?@action=redirect&bpo=22115]: Fixed tracing Tkinter variables: trace_vdelete() with wrong mode no longer break tracing, trace_vinfo() now always returns a list of pairs of strings, tracing in the «u» mode now works.

Fix a scoping issue in importlib.util.LazyLoader which triggered an UnboundLocalError when lazy-loading a module that was already put into sys.modules.

bpo-27079 [https://bugs.python.org/issue?@action=redirect&bpo=27079]: Fixed curses.ascii functions isblank(), iscntrl() and ispunct().

bpo-26754 [https://bugs.python.org/issue?@action=redirect&bpo=26754]: Some functions (compile() etc) accepted a filename argument encoded as an iterable of integers. Now only strings and byte-like objects are accepted.

bpo-27048 [https://bugs.python.org/issue?@action=redirect&bpo=27048]: Prevents distutils failing on Windows when environment variables contain non-ASCII characters

bpo-27330 [https://bugs.python.org/issue?@action=redirect&bpo=27330]: Fixed possible leaks in the ctypes module.

bpo-27238 [https://bugs.python.org/issue?@action=redirect&bpo=27238]: Got rid of bare excepts in the turtle module. Original patch by Jelle Zijlstra.

bpo-27122 [https://bugs.python.org/issue?@action=redirect&bpo=27122]: When an exception is raised within the context being managed by a contextlib.ExitStack() and one of the exit stack generators catches and raises it in a chain, do not re-raise the original exception when exiting, let the new chained one through. This avoids the PEP 479 [https://www.python.org/dev/peps/pep-0479] bug described in issue25782.

bpo-26386 [https://bugs.python.org/issue?@action=redirect&bpo=26386]: Fixed ttk.TreeView selection operations with item id’s containing spaces.

bpo-16182 [https://bugs.python.org/issue?@action=redirect&bpo=16182]: Fix various functions in the «readline» module to use the locale encoding, and fix get_begidx() and get_endidx() to return code point indexes.

bpo-27392 [https://bugs.python.org/issue?@action=redirect&bpo=27392]: Add loop.connect_accepted_socket(). Patch by Jim Fulton.

bpo-27930 [https://bugs.python.org/issue?@action=redirect&bpo=27930]: Improved behaviour of logging.handlers.QueueListener. Thanks to Paulo Andrade and Petr Viktorin for the analysis and patch.

bpo-21201 [https://bugs.python.org/issue?@action=redirect&bpo=21201]: Improves readability of multiprocessing error message. Thanks to Wojciech Walczak for patch.

bpo-27456 [https://bugs.python.org/issue?@action=redirect&bpo=27456]: asyncio: Set TCP_NODELAY by default.

bpo-27906 [https://bugs.python.org/issue?@action=redirect&bpo=27906]: Fix socket accept exhaustion during high TCP traffic. Patch by Kevin Conway.

bpo-28174 [https://bugs.python.org/issue?@action=redirect&bpo=28174]: Handle when SO_REUSEPORT isn’t properly supported. Patch by Seth Michael Larson.

bpo-26654 [https://bugs.python.org/issue?@action=redirect&bpo=26654]: Inspect functools.partial in asyncio.Handle.__repr__. Patch by iceboy.

bpo-26909 [https://bugs.python.org/issue?@action=redirect&bpo=26909]: Fix slow pipes IO in asyncio. Patch by INADA Naoki.

bpo-28176 [https://bugs.python.org/issue?@action=redirect&bpo=28176]: Fix callbacks race in asyncio.SelectorLoop.sock_connect.

bpo-27759 [https://bugs.python.org/issue?@action=redirect&bpo=27759]: Fix selectors incorrectly retain invalid file descriptors. Patch by Mark Williams.

bpo-28368 [https://bugs.python.org/issue?@action=redirect&bpo=28368]: Refuse monitoring processes if the child watcher has no loop attached. Patch by Vincent Michel.

bpo-28369 [https://bugs.python.org/issue?@action=redirect&bpo=28369]: Raise RuntimeError when transport’s FD is used with add_reader, add_writer, etc.

bpo-28370 [https://bugs.python.org/issue?@action=redirect&bpo=28370]: Speedup asyncio.StreamReader.readexactly. Patch by Коренберг Марк.

bpo-28371 [https://bugs.python.org/issue?@action=redirect&bpo=28371]: Deprecate passing asyncio.Handles to run_in_executor.

bpo-28372 [https://bugs.python.org/issue?@action=redirect&bpo=28372]: Fix asyncio to support formatting of non-python coroutines.

bpo-28399 [https://bugs.python.org/issue?@action=redirect&bpo=28399]: Remove UNIX socket from FS before binding. Patch by Коренберг Марк.

bpo-27972 [https://bugs.python.org/issue?@action=redirect&bpo=27972]: Prohibit Tasks to await on themselves.

bpo-26923 [https://bugs.python.org/issue?@action=redirect&bpo=26923]: Fix asyncio.Gather to refuse being cancelled once all children are done. Patch by Johannes Ebke.

bpo-26796 [https://bugs.python.org/issue?@action=redirect&bpo=26796]: Don’t configure the number of workers for default threadpool executor. Initial patch by Hans Lawrenz.

bpo-28600 [https://bugs.python.org/issue?@action=redirect&bpo=28600]: Optimize loop.call_soon().

bpo-28613 [https://bugs.python.org/issue?@action=redirect&bpo=28613]: Fix get_event_loop() return the current loop if called from coroutines/callbacks.

bpo-28639 [https://bugs.python.org/issue?@action=redirect&bpo=28639]: Fix inspect.isawaitable to always return bool Patch by Justin Mayfield.

bpo-28652 [https://bugs.python.org/issue?@action=redirect&bpo=28652]: Make loop methods reject socket kinds they do not support.

bpo-28653 [https://bugs.python.org/issue?@action=redirect&bpo=28653]: Fix a refleak in functools.lru_cache.

bpo-28703 [https://bugs.python.org/issue?@action=redirect&bpo=28703]: Fix asyncio.iscoroutinefunction to handle Mock objects.

bpo-24142 [https://bugs.python.org/issue?@action=redirect&bpo=24142]: Reading a corrupt config file left the parser in an invalid state. Original patch by Florian Höch.

bpo-28990 [https://bugs.python.org/issue?@action=redirect&bpo=28990]: Fix SSL hanging if connection is closed before handshake completed. (Patch by HoHo-Ho)

IDLE

bpo-15308 [https://bugs.python.org/issue?@action=redirect&bpo=15308]: Add “interrupt execution” (^C) to Shell menu. Patch by Roger Serwy, updated by Bayard Randel.

bpo-27922 [https://bugs.python.org/issue?@action=redirect&bpo=27922]: Stop IDLE tests from “flashing” gui widgets on the screen.

Add version to title of IDLE help window.

bpo-25564 [https://bugs.python.org/issue?@action=redirect&bpo=25564]: In section on IDLE – console differences, mention that using exec means that __builtins__ is defined for each statement.

bpo-27714 [https://bugs.python.org/issue?@action=redirect&bpo=27714]: text_textview and test_autocomplete now pass when re-run in the same process. This occurs when test_idle fails when run with the -w option but without -jn. Fix warning from test_config.

bpo-25507 [https://bugs.python.org/issue?@action=redirect&bpo=25507]: IDLE no longer runs buggy code because of its tkinter imports. Users must include the same imports required to run directly in Python.

bpo-27452 [https://bugs.python.org/issue?@action=redirect&bpo=27452]: add line counter and crc to IDLE configHandler test dump.

bpo-27365 [https://bugs.python.org/issue?@action=redirect&bpo=27365]: Allow non-ascii chars in IDLE NEWS.txt, for contributor names.

bpo-27245 [https://bugs.python.org/issue?@action=redirect&bpo=27245]: IDLE: Cleanly delete custom themes and key bindings. Previously, when IDLE was started from a console or by import, a cascade of warnings was emitted. Patch by Serhiy Storchaka.

C API

bpo-28808 [https://bugs.python.org/issue?@action=redirect&bpo=28808]: PyUnicode_CompareWithASCIIString() now never raises exceptions.

bpo-26754 [https://bugs.python.org/issue?@action=redirect&bpo=26754]: PyUnicode_FSDecoder() accepted a filename argument encoded as an iterable of integers. Now only strings and bytes-like objects are accepted.

Documentation

bpo-28513 [https://bugs.python.org/issue?@action=redirect&bpo=28513]: Documented command-line interface of zipfile.

Tests

bpo-28950 [https://bugs.python.org/issue?@action=redirect&bpo=28950]: Disallow -j0 to be combined with -T/-l/-M in regrtest command line arguments.

bpo-28666 [https://bugs.python.org/issue?@action=redirect&bpo=28666]: Now test.support.rmtree is able to remove unwritable or unreadable directories.

bpo-23839 [https://bugs.python.org/issue?@action=redirect&bpo=23839]: Various caches now are cleared before running every test file.

bpo-28409 [https://bugs.python.org/issue?@action=redirect&bpo=28409]: regrtest: fix the parser of command line arguments.

bpo-27787 [https://bugs.python.org/issue?@action=redirect&bpo=27787]: Call gc.collect() before checking each test for «dangling threads», since the dangling threads are weak references.

bpo-27369 [https://bugs.python.org/issue?@action=redirect&bpo=27369]: In test_pyexpat, avoid testing an error message detail that changed in Expat 2.2.0.

Tools/Demos

bpo-27952 [https://bugs.python.org/issue?@action=redirect&bpo=27952]: Get Tools/scripts/fixcid.py working with Python 3 and the current «re» module, avoid invalid Python backslash escapes, and fix a bug parsing escaped C quote signs.

bpo-27332 [https://bugs.python.org/issue?@action=redirect&bpo=27332]: Fixed the type of the first argument of module-level functions generated by Argument Clinic. Patch by Petr Viktorin.

bpo-27418 [https://bugs.python.org/issue?@action=redirect&bpo=27418]: Fixed Tools/importbench/importbench.py.

Windows

bpo-28251 [https://bugs.python.org/issue?@action=redirect&bpo=28251]: Improvements to help manuals on Windows.

bpo-28110 [https://bugs.python.org/issue?@action=redirect&bpo=28110]: launcher.msi has different product codes between 32-bit and 64-bit

bpo-25144 [https://bugs.python.org/issue?@action=redirect&bpo=25144]: Ensures TargetDir is set before continuing with custom install.

bpo-27469 [https://bugs.python.org/issue?@action=redirect&bpo=27469]: Adds a shell extension to the launcher so that drag and drop works correctly.

bpo-27309 [https://bugs.python.org/issue?@action=redirect&bpo=27309]: Enabled proper Windows styles in python[w].exe manifest.

Build

bpo-29080 [https://bugs.python.org/issue?@action=redirect&bpo=29080]: Removes hard dependency on hg.exe from PCBuild/build.bat

bpo-23903 [https://bugs.python.org/issue?@action=redirect&bpo=23903]: Added missed names to PC/python3.def.

bpo-10656 [https://bugs.python.org/issue?@action=redirect&bpo=10656]: Fix out-of-tree building on AIX. Patch by Tristan Carel and Michael Haubenwallner.

bpo-26359 [https://bugs.python.org/issue?@action=redirect&bpo=26359]: Rename –with-optimiations to –enable-optimizations.

bpo-28444 [https://bugs.python.org/issue?@action=redirect&bpo=28444]: Fix missing extensions modules when cross compiling.

bpo-28248 [https://bugs.python.org/issue?@action=redirect&bpo=28248]: Update Windows build and OS X installers to use OpenSSL 1.0.2j.

bpo-28258 [https://bugs.python.org/issue?@action=redirect&bpo=28258]: Fixed build with Estonian locale (python-config and distclean targets in Makefile). Patch by Arfrever Frehtes Taifersar Arahesis.

bpo-26661 [https://bugs.python.org/issue?@action=redirect&bpo=26661]: setup.py now detects system libffi with multiarch wrapper.

bpo-28066 [https://bugs.python.org/issue?@action=redirect&bpo=28066]: Fix the logic that searches build directories for generated include files when building outside the source tree.

bpo-15819 [https://bugs.python.org/issue?@action=redirect&bpo=15819]: Remove redundant include search directory option for building outside the source tree.

bpo-27566 [https://bugs.python.org/issue?@action=redirect&bpo=27566]: Fix clean target in freeze makefile (patch by Lisa Roach)

bpo-27705 [https://bugs.python.org/issue?@action=redirect&bpo=27705]: Update message in validate_ucrtbase.py

bpo-27983 [https://bugs.python.org/issue?@action=redirect&bpo=27983]: Cause lack of llvm-profdata tool when using clang as required for PGO linking to be a configure time error rather than make time when –with-optimizations is enabled. Also improve our ability to find the llvm-profdata tool on MacOS and some Linuxes.

bpo-26307 [https://bugs.python.org/issue?@action=redirect&bpo=26307]: The profile-opt build now applies PGO to the built-in modules.

bpo-26359 [https://bugs.python.org/issue?@action=redirect&bpo=26359]: Add the –with-optimizations configure flag.

bpo-27713 [https://bugs.python.org/issue?@action=redirect&bpo=27713]: Suppress spurious build warnings when updating importlib’s bootstrap files. Patch by Xiang Zhang

bpo-25825 [https://bugs.python.org/issue?@action=redirect&bpo=25825]: Correct the references to Modules/python.exp and ld_so_aix, which are required on AIX. This updates references to an installation path that was changed in 3.2a4, and undoes changed references to the build tree that were made in 3.5.0a1.

bpo-27453 [https://bugs.python.org/issue?@action=redirect&bpo=27453]: CPP invocation in configure must use CPPFLAGS. Patch by Chi Hsuan Yen.

bpo-27641 [https://bugs.python.org/issue?@action=redirect&bpo=27641]: The configure script now inserts comments into the makefile to prevent the pgen and _freeze_importlib executables from being cross-compiled.

bpo-26662 [https://bugs.python.org/issue?@action=redirect&bpo=26662]: Set PYTHON_FOR_GEN in configure as the Python program to be used for file generation during the build.

bpo-10910 [https://bugs.python.org/issue?@action=redirect&bpo=10910]: Avoid C++ compilation errors on FreeBSD and OS X. Also update FreedBSD version checks for the original ctype UTF-8 workaround.

bpo-28676 [https://bugs.python.org/issue?@action=redirect&bpo=28676]: Prevent missing “getentropy” declaration warning on macOS. Patch by Gareth Rees.

Python 3.5.2 final

Release date: 2016-06-26

Core and Builtins

bpo-26930 [https://bugs.python.org/issue?@action=redirect&bpo=26930]: Update Windows builds to use OpenSSL 1.0.2h.

Tests

bpo-26867 [https://bugs.python.org/issue?@action=redirect&bpo=26867]: Ubuntu’s openssl OP_NO_SSLv3 is forced on by default; fix test.

IDLE

bpo-27365 [https://bugs.python.org/issue?@action=redirect&bpo=27365]: Allow non-ascii in idlelib/NEWS.txt - minimal part for 3.5.2.

Python 3.5.2 release candidate 1

Release date: 2016-06-12

Security

bpo-26556 [https://bugs.python.org/issue?@action=redirect&bpo=26556]: Update expat to 2.1.1, fixes CVE-2015-1283.

Fix TLS stripping vulnerability in smtplib, CVE-2016-0772. Reported by Team Oststrom

bpo-26839 [https://bugs.python.org/issue?@action=redirect&bpo=26839]: On Linux, os.urandom() now calls getrandom() with GRND_NONBLOCK to fall back on reading /dev/urandom if the urandom entropy pool is not initialized yet. Patch written by Colm Buckley.

bpo-26657 [https://bugs.python.org/issue?@action=redirect&bpo=26657]: Fix directory traversal vulnerability with http.server on Windows. This fixes a regression that was introduced in 3.3.4rc1 and 3.4.0rc1. Based on patch by Philipp Hagemeister.

bpo-26313 [https://bugs.python.org/issue?@action=redirect&bpo=26313]: ssl.py _load_windows_store_certs fails if windows cert store is empty. Patch by Baji.

bpo-25939 [https://bugs.python.org/issue?@action=redirect&bpo=25939]: On Windows open the cert store readonly in ssl.enum_certificates.

Core and Builtins

bpo-27066 [https://bugs.python.org/issue?@action=redirect&bpo=27066]: Fixed SystemError if a custom opener (for open()) returns a negative number without setting an exception.

bpo-20041 [https://bugs.python.org/issue?@action=redirect&bpo=20041]: Fixed TypeError when frame.f_trace is set to None. Patch by Xavier de Gaye.

bpo-26168 [https://bugs.python.org/issue?@action=redirect&bpo=26168]: Fixed possible refleaks in failing Py_BuildValue() with the «N» format unit.

bpo-26991 [https://bugs.python.org/issue?@action=redirect&bpo=26991]: Fix possible refleak when creating a function with annotations.

bpo-27039 [https://bugs.python.org/issue?@action=redirect&bpo=27039]: Fixed bytearray.remove() for values greater than 127. Patch by Joe Jevnik.

bpo-23640 [https://bugs.python.org/issue?@action=redirect&bpo=23640]: int.from_bytes() no longer bypasses constructors for subclasses.

bpo-26811 [https://bugs.python.org/issue?@action=redirect&bpo=26811]: gc.get_objects() no longer contains a broken tuple with NULL pointer.

bpo-20120 [https://bugs.python.org/issue?@action=redirect&bpo=20120]: Use RawConfigParser for .pypirc parsing, removing support for interpolation unintentionally added with move to Python 3. Behavior no longer does any interpolation in .pypirc files, matching behavior in Python 2.7 and Setuptools 19.0.

bpo-26659 [https://bugs.python.org/issue?@action=redirect&bpo=26659]: Make the builtin slice type support cycle collection.

bpo-26718 [https://bugs.python.org/issue?@action=redirect&bpo=26718]: super.__init__ no longer leaks memory if called multiple times. NOTE: A direct call of super.__init__ is not endorsed!

bpo-25339 [https://bugs.python.org/issue?@action=redirect&bpo=25339]: PYTHONIOENCODING now has priority over locale in setting the error handler for stdin and stdout.

bpo-26494 [https://bugs.python.org/issue?@action=redirect&bpo=26494]: Fixed crash on iterating exhausting iterators. Affected classes are generic sequence iterators, iterators of str, bytes, bytearray, list, tuple, set, frozenset, dict, OrderedDict, corresponding views and os.scandir() iterator.

bpo-26581 [https://bugs.python.org/issue?@action=redirect&bpo=26581]: If coding cookie is specified multiple times on a line in Python source code file, only the first one is taken to account.

bpo-26464 [https://bugs.python.org/issue?@action=redirect&bpo=26464]: Fix str.translate() when string is ASCII and first replacements removes character, but next replacement uses a non-ASCII character or a string longer than 1 character. Regression introduced in Python 3.5.0.

bpo-22836 [https://bugs.python.org/issue?@action=redirect&bpo=22836]: Ensure exception reports from PyErr_Display() and PyErr_WriteUnraisable() are sensible even when formatting them produces secondary errors. This affects the reports produced by sys.__excepthook__() and when __del__() raises an exception.

bpo-26302 [https://bugs.python.org/issue?@action=redirect&bpo=26302]: Correct behavior to reject comma as a legal character for cookie names.

bpo-4806 [https://bugs.python.org/issue?@action=redirect&bpo=4806]: Avoid masking the original TypeError exception when using star (*) unpacking in function calls. Based on patch by Hagen Fürstenau and Daniel Urban.

bpo-27138 [https://bugs.python.org/issue?@action=redirect&bpo=27138]: Fix the doc comment for FileFinder.find_spec().

bpo-26154 [https://bugs.python.org/issue?@action=redirect&bpo=26154]: Add a new private _PyThreadState_UncheckedGet() function to get the current Python thread state, but don’t issue a fatal error if it is NULL. This new function must be used instead of accessing directly the _PyThreadState_Current variable. The variable is no more exposed since Python 3.5.1 to hide the exact implementation of atomic C types, to avoid compiler issues.

bpo-26194 [https://bugs.python.org/issue?@action=redirect&bpo=26194]: Deque.insert() gave odd results for bounded deques that had reached their maximum size. Now an IndexError will be raised when attempting to insert into a full deque.

bpo-25843 [https://bugs.python.org/issue?@action=redirect&bpo=25843]: When compiling code, don’t merge constants if they are equal but have a different types. For example, f1, f2 = lambda: 1, lambda: 1.0 is now correctly compiled to two different functions: f1() returns 1 (int) and f2() returns 1.0 (int), even if 1 and 1.0 are equal.

bpo-22995 [https://bugs.python.org/issue?@action=redirect&bpo=22995]: [UPDATE] Comment out the one of the pickleability tests in _PyObject_GetState() due to regressions observed in Cython-based projects.

bpo-25961 [https://bugs.python.org/issue?@action=redirect&bpo=25961]: Disallowed null characters in the type name.

bpo-25973 [https://bugs.python.org/issue?@action=redirect&bpo=25973]: Fix segfault when an invalid nonlocal statement binds a name starting with two underscores.

bpo-22995 [https://bugs.python.org/issue?@action=redirect&bpo=22995]: Instances of extension types with a state that aren’t subclasses of list or dict and haven’t implemented any pickle-related methods (__reduce__, __reduce_ex__, __getnewargs__, __getnewargs_ex__, or __getstate__), can no longer be pickled. Including memoryview.

bpo-20440 [https://bugs.python.org/issue?@action=redirect&bpo=20440]: Massive replacing unsafe attribute setting code with special macro Py_SETREF.

bpo-25766 [https://bugs.python.org/issue?@action=redirect&bpo=25766]: Special method __bytes__() now works in str subclasses.

bpo-25421 [https://bugs.python.org/issue?@action=redirect&bpo=25421]: __sizeof__ methods of builtin types now use dynamic basic size. This allows sys.getsize() to work correctly with their subclasses with __slots__ defined.

bpo-25709 [https://bugs.python.org/issue?@action=redirect&bpo=25709]: Fixed problem with in-place string concatenation and utf-8 cache.

bpo-27147 [https://bugs.python.org/issue?@action=redirect&bpo=27147]: Mention PEP 420 [https://www.python.org/dev/peps/pep-0420] in the importlib docs.

bpo-24097 [https://bugs.python.org/issue?@action=redirect&bpo=24097]: Fixed crash in object.__reduce__() if slot name is freed inside __getattr__.

bpo-24731 [https://bugs.python.org/issue?@action=redirect&bpo=24731]: Fixed crash on converting objects with special methods __bytes__, __trunc__, and __float__ returning instances of subclasses of bytes, int, and float to subclasses of bytes, int, and float correspondingly.

bpo-26478 [https://bugs.python.org/issue?@action=redirect&bpo=26478]: Fix semantic bugs when using binary operators with dictionary views and tuples.

bpo-26171 [https://bugs.python.org/issue?@action=redirect&bpo=26171]: Fix possible integer overflow and heap corruption in zipimporter.get_data().

bpo-25660 [https://bugs.python.org/issue?@action=redirect&bpo=25660]: Fix TAB key behaviour in REPL with readline.

bpo-25887 [https://bugs.python.org/issue?@action=redirect&bpo=25887]: Raise a RuntimeError when a coroutine object is awaited more than once.

bpo-27243 [https://bugs.python.org/issue?@action=redirect&bpo=27243]: Update the __aiter__ protocol: instead of returning an awaitable that resolves to an asynchronous iterator, the asynchronous iterator should be returned directly. Doing the former will trigger a PendingDeprecationWarning.

Library

bpo-21386 [https://bugs.python.org/issue?@action=redirect&bpo=21386]: Implement missing IPv4Address.is_global property. It was documented since 07a5610bae9d. Initial patch by Roger Luethi.

bpo-20900 [https://bugs.python.org/issue?@action=redirect&bpo=20900]: distutils register command now decodes HTTP responses correctly. Initial patch by ingrid.

A new version of typing.py provides several new classes and features: @overload outside stubs, Reversible, DefaultDict, Text, ContextManager, Type[], NewType(), TYPE_CHECKING, and numerous bug fixes (note that some of the new features are not yet implemented in mypy or other static analyzers). Also classes for PEP 492 [https://www.python.org/dev/peps/pep-0492] (Awaitable, AsyncIterable, AsyncIterator) have been added (in fact they made it into 3.5.1 but were never mentioned).

bpo-25738 [https://bugs.python.org/issue?@action=redirect&bpo=25738]: Stop http.server.BaseHTTPRequestHandler.send_error() from sending a message body for 205 Reset Content. Also, don’t send Content header fields in responses that don’t have a body. Patch by Susumu Koshiba.

bpo-21313 [https://bugs.python.org/issue?@action=redirect&bpo=21313]: Fix the «platform» module to tolerate when sys.version contains truncated build information.

bpo-27164 [https://bugs.python.org/issue?@action=redirect&bpo=27164]: In the zlib module, allow decompressing raw Deflate streams with a predefined zdict. Based on patch by Xiang Zhang.

bpo-24291 [https://bugs.python.org/issue?@action=redirect&bpo=24291]: Fix wsgiref.simple_server.WSGIRequestHandler to completely write data to the client. Previously it could do partial writes and truncate data. Also, wsgiref.handler.ServerHandler can now handle stdout doing partial writes, but this is deprecated.

bpo-26809 [https://bugs.python.org/issue?@action=redirect&bpo=26809]: Add __all__ to string. Patch by Emanuel Barry.

bpo-26373 [https://bugs.python.org/issue?@action=redirect&bpo=26373]: subprocess.Popen.communicate now correctly ignores BrokenPipeError when the child process dies before .communicate() is called in more/all circumstances.

bpo-21776 [https://bugs.python.org/issue?@action=redirect&bpo=21776]: distutils.upload now correctly handles HTTPError. Initial patch by Claudiu Popa.

bpo-27114 [https://bugs.python.org/issue?@action=redirect&bpo=27114]: Fix SSLContext._load_windows_store_certs fails with PermissionError

bpo-18383 [https://bugs.python.org/issue?@action=redirect&bpo=18383]: Avoid creating duplicate filters when using filterwarnings and simplefilter. Based on patch by Alex Shkop.

bpo-27057 [https://bugs.python.org/issue?@action=redirect&bpo=27057]: Fix os.set_inheritable() on Android, ioctl() is blocked by SELinux and fails with EACCESS. The function now falls back to fcntl(). Patch written by Michał Bednarski.

bpo-27014 [https://bugs.python.org/issue?@action=redirect&bpo=27014]: Fix infinite recursion using typing.py. Thanks to Kalle Tuure!

bpo-14132 [https://bugs.python.org/issue?@action=redirect&bpo=14132]: Fix urllib.request redirect handling when the target only has a query string. Original fix by Ján Janech.

bpo-17214 [https://bugs.python.org/issue?@action=redirect&bpo=17214]: The «urllib.request» module now percent-encodes non-ASCII bytes found in redirect target URLs. Some servers send Location header fields with non-ASCII bytes, but «http.client» requires the request target to be ASCII-encodable, otherwise a UnicodeEncodeError is raised. Based on patch by Christian Heimes.

bpo-26892 [https://bugs.python.org/issue?@action=redirect&bpo=26892]: Honor debuglevel flag in urllib.request.HTTPHandler. Patch contributed by Chi Hsuan Yen.

bpo-22274 [https://bugs.python.org/issue?@action=redirect&bpo=22274]: In the subprocess module, allow stderr to be redirected to stdout even when stdout is not redirected. Patch by Akira Li.

bpo-26807 [https://bugs.python.org/issue?@action=redirect&bpo=26807]: mock_open “files” no longer error on readline at end of file. Patch from Yolanda Robla.

bpo-25745 [https://bugs.python.org/issue?@action=redirect&bpo=25745]: Fixed leaking a userptr in curses panel destructor.

bpo-26977 [https://bugs.python.org/issue?@action=redirect&bpo=26977]: Removed unnecessary, and ignored, call to sum of squares helper in statistics.pvariance.

bpo-26881 [https://bugs.python.org/issue?@action=redirect&bpo=26881]: The modulefinder module now supports extended opcode arguments.

bpo-23815 [https://bugs.python.org/issue?@action=redirect&bpo=23815]: Fixed crashes related to directly created instances of types in _tkinter and curses.panel modules.

bpo-17765 [https://bugs.python.org/issue?@action=redirect&bpo=17765]: weakref.ref() no longer silently ignores keyword arguments. Patch by Georg Brandl.

bpo-26873 [https://bugs.python.org/issue?@action=redirect&bpo=26873]: xmlrpc now raises ResponseError on unsupported type tags instead of silently return incorrect result.

bpo-26711 [https://bugs.python.org/issue?@action=redirect&bpo=26711]: Fixed the comparison of plistlib.Data with other types.

bpo-24114 [https://bugs.python.org/issue?@action=redirect&bpo=24114]: Fix an uninitialized variable in ctypes.util. The bug only occurs on SunOS when the ctypes implementation searches for the crle program. Patch by Xiang Zhang. Tested on SunOS by Kees Bos.

bpo-26864 [https://bugs.python.org/issue?@action=redirect&bpo=26864]: In urllib.request, change the proxy bypass host checking against no_proxy to be case-insensitive, and to not match unrelated host names that happen to have a bypassed hostname as a suffix. Patch by Xiang Zhang.

bpo-26634 [https://bugs.python.org/issue?@action=redirect&bpo=26634]: recursive_repr() now sets __qualname__ of wrapper. Patch by Xiang Zhang.

bpo-26804 [https://bugs.python.org/issue?@action=redirect&bpo=26804]: urllib.request will prefer lower_case proxy environment variables over UPPER_CASE or Mixed_Case ones. Patch contributed by Hans-Peter Jansen.

bpo-26837 [https://bugs.python.org/issue?@action=redirect&bpo=26837]: assertSequenceEqual() now correctly outputs non-stringified differing items (like bytes in the -b mode). This affects assertListEqual() and assertTupleEqual().

bpo-26041 [https://bugs.python.org/issue?@action=redirect&bpo=26041]: Remove «will be removed in Python 3.7» from deprecation messages of platform.dist() and platform.linux_distribution(). Patch by Kumaripaba Miyurusara Athukorala.

bpo-26822 [https://bugs.python.org/issue?@action=redirect&bpo=26822]: itemgetter, attrgetter and methodcaller objects no longer silently ignore keyword arguments.

bpo-26733 [https://bugs.python.org/issue?@action=redirect&bpo=26733]: Disassembling a class now disassembles class and static methods. Patch by Xiang Zhang.

bpo-26801 [https://bugs.python.org/issue?@action=redirect&bpo=26801]: Fix error handling in shutil.get_terminal_size(), catch AttributeError instead of NameError. Patch written by Emanuel Barry.

bpo-24838 [https://bugs.python.org/issue?@action=redirect&bpo=24838]: tarfile’s ustar and gnu formats now correctly calculate name and link field limits for multibyte character encodings like utf-8.

bpo-26717 [https://bugs.python.org/issue?@action=redirect&bpo=26717]: Stop encoding Latin-1-ized WSGI paths with UTF-8. Patch by Anthony Sottile.

bpo-26735 [https://bugs.python.org/issue?@action=redirect&bpo=26735]: Fix os.urandom() on Solaris 11.3 and newer when reading more than 1,024 bytes: call getrandom() multiple times with a limit of 1024 bytes per call.

bpo-16329 [https://bugs.python.org/issue?@action=redirect&bpo=16329]: Add .webm to mimetypes.types_map. Patch by Giampaolo Rodola”.

bpo-13952 [https://bugs.python.org/issue?@action=redirect&bpo=13952]: Add .csv to mimetypes.types_map. Patch by Geoff Wilson.

bpo-26709 [https://bugs.python.org/issue?@action=redirect&bpo=26709]: Fixed Y2038 problem in loading binary PLists.

bpo-23735 [https://bugs.python.org/issue?@action=redirect&bpo=23735]: Handle terminal resizing with Readline 6.3+ by installing our own SIGWINCH handler. Patch by Eric Price.

bpo-26586 [https://bugs.python.org/issue?@action=redirect&bpo=26586]: In http.server, respond with «413 Request header fields too large» if there are too many header fields to parse, rather than killing the connection and raising an unhandled exception. Patch by Xiang Zhang.

bpo-22854 [https://bugs.python.org/issue?@action=redirect&bpo=22854]: Change BufferedReader.writable() and BufferedWriter.readable() to always return False.

bpo-25195 [https://bugs.python.org/issue?@action=redirect&bpo=25195]: Fix a regression in mock.MagicMock. _Call is a subclass of tuple (changeset 3603bae63c13 only works for classes) so we need to implement __ne__ ourselves. Patch by Andrew Plummer.

bpo-26644 [https://bugs.python.org/issue?@action=redirect&bpo=26644]: Raise ValueError rather than SystemError when a negative length is passed to SSLSocket.recv() or read().

bpo-23804 [https://bugs.python.org/issue?@action=redirect&bpo=23804]: Fix SSL recv(0) and read(0) methods to return zero bytes instead of up to 1024.

bpo-26616 [https://bugs.python.org/issue?@action=redirect&bpo=26616]: Fixed a bug in datetime.astimezone() method.

bpo-21925 [https://bugs.python.org/issue?@action=redirect&bpo=21925]: warnings.formatwarning() now catches exceptions on linecache.getline(...) to be able to log ResourceWarning emitted late during the Python shutdown process.

bpo-24266 [https://bugs.python.org/issue?@action=redirect&bpo=24266]: Ctrl+C during Readline history search now cancels the search mode when compiled with Readline 7.

bpo-26560 [https://bugs.python.org/issue?@action=redirect&bpo=26560]: Avoid potential ValueError in BaseHandler.start_response. Initial patch by Peter Inglesby.

bpo-26569 [https://bugs.python.org/issue?@action=redirect&bpo=26569]: Fix pyclbr.readmodule() and pyclbr.readmodule_ex() to support importing packages.

bpo-26499 [https://bugs.python.org/issue?@action=redirect&bpo=26499]: Account for remaining Content-Length in HTTPResponse.readline() and read1(). Based on patch by Silent Ghost. Also document that HTTPResponse now supports these methods.

bpo-25320 [https://bugs.python.org/issue?@action=redirect&bpo=25320]: Handle sockets in directories unittest discovery is scanning. Patch from Victor van den Elzen.

bpo-16181 [https://bugs.python.org/issue?@action=redirect&bpo=16181]: cookiejar.http2time() now returns None if year is higher than datetime.MAXYEAR.

bpo-26513 [https://bugs.python.org/issue?@action=redirect&bpo=26513]: Fixes platform module detection of Windows Server

bpo-23718 [https://bugs.python.org/issue?@action=redirect&bpo=23718]: Fixed parsing time in week 0 before Jan 1. Original patch by Tamás Bence Gedai.

bpo-20589 [https://bugs.python.org/issue?@action=redirect&bpo=20589]: Invoking Path.owner() and Path.group() on Windows now raise NotImplementedError instead of ImportError.

bpo-26177 [https://bugs.python.org/issue?@action=redirect&bpo=26177]: Fixed the keys() method for Canvas and Scrollbar widgets.

bpo-15068 [https://bugs.python.org/issue?@action=redirect&bpo=15068]: Got rid of excessive buffering in the fileinput module. The bufsize parameter is no longer used.

bpo-2202 [https://bugs.python.org/issue?@action=redirect&bpo=2202]: Fix UnboundLocalError in AbstractDigestAuthHandler.get_algorithm_impls. Initial patch by Mathieu Dupuy.

bpo-25718 [https://bugs.python.org/issue?@action=redirect&bpo=25718]: Fixed pickling and copying the accumulate() iterator with total is None.

bpo-26475 [https://bugs.python.org/issue?@action=redirect&bpo=26475]: Fixed debugging output for regular expressions with the (?x) flag.

bpo-26457 [https://bugs.python.org/issue?@action=redirect&bpo=26457]: Fixed the subnets() methods in IP network classes for the case when resulting prefix length is equal to maximal prefix length. Based on patch by Xiang Zhang.

bpo-26385 [https://bugs.python.org/issue?@action=redirect&bpo=26385]: Remove the file if the internal open() call in NamedTemporaryFile() fails. Patch by Silent Ghost.

bpo-26402 [https://bugs.python.org/issue?@action=redirect&bpo=26402]: Fix XML-RPC client to retry when the server shuts down a persistent connection. This was a regression related to the new http.client.RemoteDisconnected exception in 3.5.0a4.

bpo-25913 [https://bugs.python.org/issue?@action=redirect&bpo=25913]: Leading <~ is optional now in base64.a85decode() with adobe=True. Patch by Swati Jaiswal.

bpo-26186 [https://bugs.python.org/issue?@action=redirect&bpo=26186]: Remove an invalid type check in importlib.util.LazyLoader.

bpo-26367 [https://bugs.python.org/issue?@action=redirect&bpo=26367]: importlib.__import__() raises SystemError like builtins.__import__() when level is specified but without an accompanying package specified.

bpo-26309 [https://bugs.python.org/issue?@action=redirect&bpo=26309]: In the «socketserver» module, shut down the request (closing the connected socket) when verify_request() returns false. Patch by Aviv Palivoda.

bpo-25995 [https://bugs.python.org/issue?@action=redirect&bpo=25995]: os.walk() no longer uses FDs proportional to the tree depth.

bpo-26117 [https://bugs.python.org/issue?@action=redirect&bpo=26117]: The os.scandir() iterator now closes file descriptor not only when the iteration is finished, but when it was failed with error.

bpo-25911 [https://bugs.python.org/issue?@action=redirect&bpo=25911]: Restored support of bytes paths in os.walk() on Windows.

bpo-26045 [https://bugs.python.org/issue?@action=redirect&bpo=26045]: Add UTF-8 suggestion to error message when posting a non-Latin-1 string with http.client.

bpo-12923 [https://bugs.python.org/issue?@action=redirect&bpo=12923]: Reset FancyURLopener’s redirect counter even if there is an exception. Based on patches by Brian Brazil and Daniel Rocco.

bpo-25945 [https://bugs.python.org/issue?@action=redirect&bpo=25945]: Fixed a crash when unpickle the functools.partial object with wrong state. Fixed a leak in failed functools.partial constructor. «args» and «keywords» attributes of functools.partial have now always types tuple and dict correspondingly.

bpo-26202 [https://bugs.python.org/issue?@action=redirect&bpo=26202]: copy.deepcopy() now correctly copies range() objects with non-atomic attributes.

bpo-23076 [https://bugs.python.org/issue?@action=redirect&bpo=23076]: Path.glob() now raises a ValueError if it’s called with an invalid pattern. Patch by Thomas Nyberg.

bpo-19883 [https://bugs.python.org/issue?@action=redirect&bpo=19883]: Fixed possible integer overflows in zipimport.

bpo-26227 [https://bugs.python.org/issue?@action=redirect&bpo=26227]: On Windows, getnameinfo(), gethostbyaddr() and gethostbyname_ex() functions of the socket module now decode the hostname from the ANSI code page rather than UTF-8.

bpo-26147 [https://bugs.python.org/issue?@action=redirect&bpo=26147]: xmlrpc now works with strings not encodable with used non-UTF-8 encoding.

bpo-25935 [https://bugs.python.org/issue?@action=redirect&bpo=25935]: Garbage collector now breaks reference loops with OrderedDict.

bpo-16620 [https://bugs.python.org/issue?@action=redirect&bpo=16620]: Fixed AttributeError in msilib.Directory.glob().

bpo-26013 [https://bugs.python.org/issue?@action=redirect&bpo=26013]: Added compatibility with broken protocol 2 pickles created in old Python 3 versions (3.4.3 and lower).

bpo-25850 [https://bugs.python.org/issue?@action=redirect&bpo=25850]: Use cross-compilation by default for 64-bit Windows.

bpo-17633 [https://bugs.python.org/issue?@action=redirect&bpo=17633]: Improve zipimport’s support for namespace packages.

bpo-24705 [https://bugs.python.org/issue?@action=redirect&bpo=24705]: Fix sysconfig._parse_makefile not expanding ${} vars appearing before $() vars.

bpo-22138 [https://bugs.python.org/issue?@action=redirect&bpo=22138]: Fix mock.patch behavior when patching descriptors. Restore original values after patching. Patch contributed by Sean McCully.

bpo-25672 [https://bugs.python.org/issue?@action=redirect&bpo=25672]: In the ssl module, enable the SSL_MODE_RELEASE_BUFFERS mode option if it is safe to do so.

bpo-26012 [https://bugs.python.org/issue?@action=redirect&bpo=26012]: Don’t traverse into symlinks for ** pattern in pathlib.Path.[r]glob().

bpo-24120 [https://bugs.python.org/issue?@action=redirect&bpo=24120]: Ignore PermissionError when traversing a tree with pathlib.Path.[r]glob(). Patch by Ulrich Petri.

bpo-25447 [https://bugs.python.org/issue?@action=redirect&bpo=25447]: fileinput now uses sys.stdin as-is if it does not have a buffer attribute (restores backward compatibility).

bpo-25447 [https://bugs.python.org/issue?@action=redirect&bpo=25447]: Copying the lru_cache() wrapper object now always works, independently from the type of the wrapped object (by returning the original object unchanged).

bpo-24103 [https://bugs.python.org/issue?@action=redirect&bpo=24103]: Fixed possible use after free in ElementTree.XMLPullParser.

bpo-25860 [https://bugs.python.org/issue?@action=redirect&bpo=25860]: os.fwalk() no longer skips remaining directories when error occurs. Original patch by Samson Lee.

bpo-25914 [https://bugs.python.org/issue?@action=redirect&bpo=25914]: Fixed and simplified OrderedDict.__sizeof__.

bpo-25902 [https://bugs.python.org/issue?@action=redirect&bpo=25902]: Fixed various refcount issues in ElementTree iteration.

bpo-25717 [https://bugs.python.org/issue?@action=redirect&bpo=25717]: Restore the previous behaviour of tolerating most fstat() errors when opening files. This was a regression in 3.5a1, and stopped anonymous temporary files from working in special cases.

bpo-24903 [https://bugs.python.org/issue?@action=redirect&bpo=24903]: Fix regression in number of arguments compileall accepts when “-d” is specified. The check on the number of arguments has been dropped completely as it never worked correctly anyway.

bpo-25764 [https://bugs.python.org/issue?@action=redirect&bpo=25764]: In the subprocess module, preserve any exception caused by fork() failure when preexec_fn is used.

bpo-6478 [https://bugs.python.org/issue?@action=redirect&bpo=6478]: _strptime’s regexp cache now is reset after changing timezone with time.tzset().

bpo-14285 [https://bugs.python.org/issue?@action=redirect&bpo=14285]: When executing a package with the «python -m package» option, and package initialization fails, a proper traceback is now reported. The «runpy» module now lets exceptions from package initialization pass back to the caller, rather than raising ImportError.

bpo-19771 [https://bugs.python.org/issue?@action=redirect&bpo=19771]: Also in runpy and the «-m» option, omit the irrelevant message «… is a package and cannot be directly executed» if the package could not even be initialized (e.g. due to a bad *.pyc file).

bpo-25177 [https://bugs.python.org/issue?@action=redirect&bpo=25177]: Fixed problem with the mean of very small and very large numbers. As a side effect, statistics.mean and statistics.variance should be significantly faster.

bpo-25718 [https://bugs.python.org/issue?@action=redirect&bpo=25718]: Fixed copying object with state with boolean value is false.

bpo-10131 [https://bugs.python.org/issue?@action=redirect&bpo=10131]: Fixed deep copying of minidom documents. Based on patch by Marian Ganisin.

bpo-25725 [https://bugs.python.org/issue?@action=redirect&bpo=25725]: Fixed a reference leak in pickle.loads() when unpickling invalid data including tuple instructions.

bpo-25663 [https://bugs.python.org/issue?@action=redirect&bpo=25663]: In the Readline completer, avoid listing duplicate global names, and search the global namespace before searching builtins.

bpo-25688 [https://bugs.python.org/issue?@action=redirect&bpo=25688]: Fixed file leak in ElementTree.iterparse() raising an error.

bpo-23914 [https://bugs.python.org/issue?@action=redirect&bpo=23914]: Fixed SystemError raised by unpickler on broken pickle data.

bpo-25691 [https://bugs.python.org/issue?@action=redirect&bpo=25691]: Fixed crash on deleting ElementTree.Element attributes.

bpo-25624 [https://bugs.python.org/issue?@action=redirect&bpo=25624]: ZipFile now always writes a ZIP_STORED header for directory entries. Patch by Dingyuan Wang.

Skip getaddrinfo if host is already resolved. Patch by A. Jesse Jiryu Davis.

bpo-26050 [https://bugs.python.org/issue?@action=redirect&bpo=26050]: Add asyncio.StreamReader.readuntil() method. Patch by Марк Коренберг.

bpo-25924 [https://bugs.python.org/issue?@action=redirect&bpo=25924]: Avoid unnecessary serialization of getaddrinfo(3) calls on OS X versions 10.5 or higher. Original patch by A. Jesse Jiryu Davis.

bpo-26406 [https://bugs.python.org/issue?@action=redirect&bpo=26406]: Avoid unnecessary serialization of getaddrinfo(3) calls on current versions of OpenBSD and NetBSD. Patch by A. Jesse Jiryu Davis.

bpo-26848 [https://bugs.python.org/issue?@action=redirect&bpo=26848]: Fix asyncio/subprocess.communicate() to handle empty input. Patch by Jack O’Connor.

bpo-27040 [https://bugs.python.org/issue?@action=redirect&bpo=27040]: Add loop.get_exception_handler method

bpo-27041 [https://bugs.python.org/issue?@action=redirect&bpo=27041]: asyncio: Add loop.create_future method

bpo-27223 [https://bugs.python.org/issue?@action=redirect&bpo=27223]: asyncio: Fix _read_ready and _write_ready to respect _conn_lost. Patch by Łukasz Langa.

bpo-22970 [https://bugs.python.org/issue?@action=redirect&bpo=22970]: asyncio: Fix inconsistency cancelling Condition.wait. Patch by David Coles.

IDLE

bpo-5124 [https://bugs.python.org/issue?@action=redirect&bpo=5124]: Paste with text selected now replaces the selection on X11. This matches how paste works on Windows, Mac, most modern Linux apps, and ttk widgets. Original patch by Serhiy Storchaka.

bpo-24759 [https://bugs.python.org/issue?@action=redirect&bpo=24759]: Make clear in idlelib.idle_test.__init__ that the directory is a private implementation of test.test_idle and tool for maintainers.

bpo-27196 [https://bugs.python.org/issue?@action=redirect&bpo=27196]: Stop “ThemeChanged” warnings when running IDLE tests. These persisted after other warnings were suppressed in #20567. Apply Serhiy Storchaka’s update_idletasks solution to four test files. Record this additional advice in idle_test/README.txt

bpo-20567 [https://bugs.python.org/issue?@action=redirect&bpo=20567]: Revise idle_test/README.txt with advice about avoiding tk warning messages from tests. Apply advice to several IDLE tests.

bpo-27117 [https://bugs.python.org/issue?@action=redirect&bpo=27117]: Make colorizer htest and turtledemo work with dark themes. Move code for configuring text widget colors to a new function.

bpo-26673 [https://bugs.python.org/issue?@action=redirect&bpo=26673]: When tk reports font size as 0, change to size 10. Such fonts on Linux prevented the configuration dialog from opening.

bpo-21939 [https://bugs.python.org/issue?@action=redirect&bpo=21939]: Add test for IDLE’s percolator. Original patch by Saimadhav Heblikar.

bpo-21676 [https://bugs.python.org/issue?@action=redirect&bpo=21676]: Add test for IDLE’s replace dialog. Original patch by Saimadhav Heblikar.

bpo-18410 [https://bugs.python.org/issue?@action=redirect&bpo=18410]: Add test for IDLE’s search dialog. Original patch by Westley Martínez.

bpo-21703 [https://bugs.python.org/issue?@action=redirect&bpo=21703]: Add test for IDLE’s undo delegator. Original patch by Saimadhav Heblikar .

bpo-27044 [https://bugs.python.org/issue?@action=redirect&bpo=27044]: Add ConfigDialog.remove_var_callbacks to stop memory leaks.

bpo-23977 [https://bugs.python.org/issue?@action=redirect&bpo=23977]: Add more asserts to test_delegator.

bpo-20640 [https://bugs.python.org/issue?@action=redirect&bpo=20640]: Add tests for idlelib.configHelpSourceEdit. Patch by Saimadhav Heblikar.

In the “IDLE-console differences” section of the IDLE doc, clarify how running with IDLE affects sys.modules and the standard streams.

bpo-25507 [https://bugs.python.org/issue?@action=redirect&bpo=25507]: fix incorrect change in IOBinding that prevented printing. Augment IOBinding htest to include all major IOBinding functions.

bpo-25905 [https://bugs.python.org/issue?@action=redirect&bpo=25905]: Revert unwanted conversion of “ to ’ RIGHT SINGLE QUOTATION MARK in README.txt and open this and NEWS.txt with “ascii”. Re-encode CREDITS.txt to utf-8 and open it with “utf-8”.

Documentation

bpo-19489 [https://bugs.python.org/issue?@action=redirect&bpo=19489]: Moved the search box from the sidebar to the header and footer of each page. Patch by Ammar Askar.

bpo-24136 [https://bugs.python.org/issue?@action=redirect&bpo=24136]: Document the new PEP 448 [https://www.python.org/dev/peps/pep-0448] unpacking syntax of 3.5.

bpo-26736 [https://bugs.python.org/issue?@action=redirect&bpo=26736]: Used HTTPS for external links in the documentation if possible.

bpo-6953 [https://bugs.python.org/issue?@action=redirect&bpo=6953]: Rework the Readline module documentation to group related functions together, and add more details such as what underlying Readline functions and variables are accessed.

bpo-23606 [https://bugs.python.org/issue?@action=redirect&bpo=23606]: Adds note to ctypes documentation regarding cdll.msvcrt.

bpo-25500 [https://bugs.python.org/issue?@action=redirect&bpo=25500]: Fix documentation to not claim that __import__ is searched for in the global scope.

bpo-26014 [https://bugs.python.org/issue?@action=redirect&bpo=26014]: Update 3.x packaging documentation: * «See also» links to the new docs are now provided in the legacy pages * links to setuptools documentation have been updated

Tests

bpo-21916 [https://bugs.python.org/issue?@action=redirect&bpo=21916]: Added tests for the turtle module. Patch by ingrid, Gregory Loyse and Jelle Zijlstra.

bpo-26523 [https://bugs.python.org/issue?@action=redirect&bpo=26523]: The multiprocessing thread pool (multiprocessing.dummy.Pool) was untested.

bpo-26015 [https://bugs.python.org/issue?@action=redirect&bpo=26015]: Added new tests for pickling iterators of mutable sequences.

bpo-26325 [https://bugs.python.org/issue?@action=redirect&bpo=26325]: Added test.support.check_no_resource_warning() to check that no ResourceWarning is emitted.

bpo-25940 [https://bugs.python.org/issue?@action=redirect&bpo=25940]: Changed test_ssl to use self-signed.pythontest.net. This avoids relying on svn.python.org, which recently changed root certificate.

bpo-25616 [https://bugs.python.org/issue?@action=redirect&bpo=25616]: Tests for OrderedDict are extracted from test_collections into separate file test_ordered_dict.

bpo-26583 [https://bugs.python.org/issue?@action=redirect&bpo=26583]: Skip test_timestamp_overflow in test_import if bytecode files cannot be written.

Build

bpo-26884 [https://bugs.python.org/issue?@action=redirect&bpo=26884]: Fix linking extension modules for cross builds. Patch by Xavier de Gaye.

bpo-22359 [https://bugs.python.org/issue?@action=redirect&bpo=22359]: Disable the rules for running _freeze_importlib and pgen when cross-compiling. The output of these programs is normally saved with the source code anyway, and is still regenerated when doing a native build. Patch by Xavier de Gaye.

bpo-27229 [https://bugs.python.org/issue?@action=redirect&bpo=27229]: Fix the cross-compiling pgen rule for in-tree builds. Patch by Xavier de Gaye.

bpo-21668 [https://bugs.python.org/issue?@action=redirect&bpo=21668]: Link audioop, _datetime, _ctypes_test modules to libm, except on Mac OS X. Patch written by Xavier de Gaye.

bpo-25702 [https://bugs.python.org/issue?@action=redirect&bpo=25702]: A –with-lto configure option has been added that will enable link time optimizations at build time during a make profile-opt. Some compilers and toolchains are known to not produce stable code when using LTO, be sure to test things thoroughly before relying on it. It can provide a few % speed up over profile-opt alone.

bpo-26624 [https://bugs.python.org/issue?@action=redirect&bpo=26624]: Adds validation of ucrtbase[d].dll version with warning for old versions.

bpo-17603 [https://bugs.python.org/issue?@action=redirect&bpo=17603]: Avoid error about nonexistent fileblocks.o file by using a lower-level check for st_blocks in struct stat.

bpo-26079 [https://bugs.python.org/issue?@action=redirect&bpo=26079]: Fixing the build output folder for tix-8.4.3.6. Patch by Bjoern Thiel.

bpo-26465 [https://bugs.python.org/issue?@action=redirect&bpo=26465]: Update Windows builds to use OpenSSL 1.0.2g.

bpo-24421 [https://bugs.python.org/issue?@action=redirect&bpo=24421]: Compile Modules/_math.c once, before building extensions. Previously it could fail to compile properly if the math and cmath builds were concurrent.

bpo-25348 [https://bugs.python.org/issue?@action=redirect&bpo=25348]: Added --pgo and --pgo-job arguments to PCbuild\build.bat for building with Profile-Guided Optimization. The old PCbuild\build_pgo.bat script is now deprecated, and simply calls PCbuild\build.bat --pgo %*.

bpo-25827 [https://bugs.python.org/issue?@action=redirect&bpo=25827]: Add support for building with ICC to configure, including a new --with-icc flag.

bpo-25696 [https://bugs.python.org/issue?@action=redirect&bpo=25696]: Fix installation of Python on UNIX with make -j9.

bpo-26930 [https://bugs.python.org/issue?@action=redirect&bpo=26930]: Update OS X 10.5+ 32-bit-only installer to build and link with OpenSSL 1.0.2h.

bpo-26268 [https://bugs.python.org/issue?@action=redirect&bpo=26268]: Update Windows builds to use OpenSSL 1.0.2f.

bpo-25136 [https://bugs.python.org/issue?@action=redirect&bpo=25136]: Support Apple Xcode 7’s new textual SDK stub libraries.

bpo-24324 [https://bugs.python.org/issue?@action=redirect&bpo=24324]: Do not enable unreachable code warnings when using gcc as the option does not work correctly in older versions of gcc and has been silently removed as of gcc-4.5.

Windows

bpo-27053 [https://bugs.python.org/issue?@action=redirect&bpo=27053]: Updates make_zip.py to correctly generate library ZIP file.

bpo-26268 [https://bugs.python.org/issue?@action=redirect&bpo=26268]: Update the prepare_ssl.py script to handle OpenSSL releases that don’t include the contents of the include directory (that is, 1.0.2e and later).

bpo-26071 [https://bugs.python.org/issue?@action=redirect&bpo=26071]: bdist_wininst created binaries fail to start and find 32bit Python

bpo-26073 [https://bugs.python.org/issue?@action=redirect&bpo=26073]: Update the list of magic numbers in launcher

bpo-26065 [https://bugs.python.org/issue?@action=redirect&bpo=26065]: Excludes venv from library when generating embeddable distro.

bpo-17500 [https://bugs.python.org/issue?@action=redirect&bpo=17500]: Remove unused and outdated icons. (See also: https://github.com/python/pythondotorg/issues/945)

Tools/Demos

bpo-26799 [https://bugs.python.org/issue?@action=redirect&bpo=26799]: Fix python-gdb.py: don’t get C types once when the Python code is loaded, but get C types on demand. The C types can change if python-gdb.py is loaded before the Python executable. Patch written by Thomas Ilsche.

bpo-26271 [https://bugs.python.org/issue?@action=redirect&bpo=26271]: Fix the Freeze tool to properly use flags passed through configure. Patch by Daniel Shaulov.

bpo-26489 [https://bugs.python.org/issue?@action=redirect&bpo=26489]: Add dictionary unpacking support to Tools/parser/unparse.py. Patch by Guo Ci Teo.

bpo-26316 [https://bugs.python.org/issue?@action=redirect&bpo=26316]: Fix variable name typo in Argument Clinic.

Python 3.5.1 final

Release date: 2015-12-06

Core and Builtins

bpo-25709 [https://bugs.python.org/issue?@action=redirect&bpo=25709]: Fixed problem with in-place string concatenation and utf-8 cache.

Windows

bpo-25715 [https://bugs.python.org/issue?@action=redirect&bpo=25715]: Python 3.5.1 installer shows wrong upgrade path and incorrect logic for launcher detection.

Python 3.5.1 release candidate 1

Release date: 2015-11-22

Core and Builtins

bpo-25630 [https://bugs.python.org/issue?@action=redirect&bpo=25630]: Fix a possible segfault during argument parsing in functions that accept filesystem paths.

bpo-23564 [https://bugs.python.org/issue?@action=redirect&bpo=23564]: Fixed a partially broken sanity check in the _posixsubprocess internals regarding how fds_to_pass were passed to the child. The bug had no actual impact as subprocess.py already avoided it.

bpo-25388 [https://bugs.python.org/issue?@action=redirect&bpo=25388]: Fixed tokenizer crash when processing undecodable source code with a null byte.

bpo-25462 [https://bugs.python.org/issue?@action=redirect&bpo=25462]: The hash of the key now is calculated only once in most operations in C implementation of OrderedDict.

bpo-22995 [https://bugs.python.org/issue?@action=redirect&bpo=22995]: Default implementation of __reduce__ and __reduce_ex__ now rejects builtin types with not defined __new__.

bpo-25555 [https://bugs.python.org/issue?@action=redirect&bpo=25555]: Fix parser and AST: fill lineno and col_offset of «arg» node when compiling AST from Python objects.

bpo-24802 [https://bugs.python.org/issue?@action=redirect&bpo=24802]: Avoid buffer overreads when int(), float(), compile(), exec() and eval() are passed bytes-like objects. These objects are not necessarily terminated by a null byte, but the functions assumed they were.

bpo-24726 [https://bugs.python.org/issue?@action=redirect&bpo=24726]: Fixed a crash and leaking NULL in repr() of OrderedDict that was mutated by direct calls of dict methods.

bpo-25449 [https://bugs.python.org/issue?@action=redirect&bpo=25449]: Iterating OrderedDict with keys with unstable hash now raises KeyError in C implementations as well as in Python implementation.

bpo-25395 [https://bugs.python.org/issue?@action=redirect&bpo=25395]: Fixed crash when highly nested OrderedDict structures were garbage collected.

bpo-25274 [https://bugs.python.org/issue?@action=redirect&bpo=25274]: sys.setrecursionlimit() now raises a RecursionError if the new recursion limit is too low depending at the current recursion depth. Modify also the «lower-water mark» formula to make it monotonic. This mark is used to decide when the overflowed flag of the thread state is reset.

bpo-24402 [https://bugs.python.org/issue?@action=redirect&bpo=24402]: Fix input() to prompt to the redirected stdout when sys.stdout.fileno() fails.

bpo-24806 [https://bugs.python.org/issue?@action=redirect&bpo=24806]: Prevent builtin types that are not allowed to be subclassed from being subclassed through multiple inheritance.

bpo-24848 [https://bugs.python.org/issue?@action=redirect&bpo=24848]: Fixed a number of bugs in UTF-7 decoding of misformed data.

bpo-25280 [https://bugs.python.org/issue?@action=redirect&bpo=25280]: Import trace messages emitted in verbose (-v) mode are no longer formatted twice.

bpo-25003 [https://bugs.python.org/issue?@action=redirect&bpo=25003]: On Solaris 11.3 or newer, os.urandom() now uses the getrandom() function instead of the getentropy() function. The getentropy() function is blocking to generate very good quality entropy, os.urandom() doesn’t need such high-quality entropy.

bpo-25182 [https://bugs.python.org/issue?@action=redirect&bpo=25182]: The stdprinter (used as sys.stderr before the io module is imported at startup) now uses the backslashreplace error handler.

bpo-25131 [https://bugs.python.org/issue?@action=redirect&bpo=25131]: Make the line number and column offset of set/dict literals and comprehensions correspond to the opening brace.

bpo-25150 [https://bugs.python.org/issue?@action=redirect&bpo=25150]: Hide the private _Py_atomic_xxx symbols from the public Python.h header to fix a compilation error with OpenMP. PyThreadState_GET() becomes an alias to PyThreadState_Get() to avoid ABI incompatibilities.

Library

bpo-25626 [https://bugs.python.org/issue?@action=redirect&bpo=25626]: Change three zlib functions to accept sizes that fit in Py_ssize_t, but internally cap those sizes to UINT_MAX. This resolves a regression in 3.5 where GzipFile.read() failed to read chunks larger than 2 or 4 GiB. The change affects the zlib.Decompress.decompress() max_length parameter, the zlib.decompress() bufsize parameter, and the zlib.Decompress.flush() length parameter.

bpo-25583 [https://bugs.python.org/issue?@action=redirect&bpo=25583]: Avoid incorrect errors raised by os.makedirs(exist_ok=True) when the OS gives priority to errors such as EACCES over EEXIST.

bpo-25593 [https://bugs.python.org/issue?@action=redirect&bpo=25593]: Change semantics of EventLoop.stop() in asyncio.

bpo-6973 [https://bugs.python.org/issue?@action=redirect&bpo=6973]: When we know a subprocess.Popen process has died, do not allow the send_signal(), terminate(), or kill() methods to do anything as they could potentially signal a different process.

bpo-25590 [https://bugs.python.org/issue?@action=redirect&bpo=25590]: In the Readline completer, only call getattr() once per attribute.

bpo-25498 [https://bugs.python.org/issue?@action=redirect&bpo=25498]: Fix a crash when garbage-collecting ctypes objects created by wrapping a memoryview. This was a regression made in 3.5a1. Based on patch by Eryksun.

bpo-25584 [https://bugs.python.org/issue?@action=redirect&bpo=25584]: Added «escape» to the __all__ list in the glob module.

bpo-25584 [https://bugs.python.org/issue?@action=redirect&bpo=25584]: Fixed recursive glob() with patterns starting with **.

bpo-25446 [https://bugs.python.org/issue?@action=redirect&bpo=25446]: Fix regression in smtplib’s AUTH LOGIN support.

bpo-18010 [https://bugs.python.org/issue?@action=redirect&bpo=18010]: Fix the pydoc web server’s module search function to handle exceptions from importing packages.

bpo-25554 [https://bugs.python.org/issue?@action=redirect&bpo=25554]: Got rid of circular references in regular expression parsing.

bpo-25510 [https://bugs.python.org/issue?@action=redirect&bpo=25510]: fileinput.FileInput.readline() now returns b”” instead of “” at the end if the FileInput was opened with binary mode. Patch by Ryosuke Ito.

bpo-25503 [https://bugs.python.org/issue?@action=redirect&bpo=25503]: Fixed inspect.getdoc() for inherited docstrings of properties. Original patch by John Mark Vandenberg.

bpo-25515 [https://bugs.python.org/issue?@action=redirect&bpo=25515]: Always use os.urandom as a source of randomness in uuid.uuid4.

bpo-21827 [https://bugs.python.org/issue?@action=redirect&bpo=21827]: Fixed textwrap.dedent() for the case when largest common whitespace is a substring of smallest leading whitespace. Based on patch by Robert Li.

bpo-25447 [https://bugs.python.org/issue?@action=redirect&bpo=25447]: The lru_cache() wrapper objects now can be copied and pickled (by returning the original object unchanged).

bpo-25390 [https://bugs.python.org/issue?@action=redirect&bpo=25390]: typing: Don’t crash on Union[str, Pattern].

bpo-25441 [https://bugs.python.org/issue?@action=redirect&bpo=25441]: asyncio: Raise error from drain() when socket is closed.

bpo-25410 [https://bugs.python.org/issue?@action=redirect&bpo=25410]: Cleaned up and fixed minor bugs in C implementation of OrderedDict.

bpo-25411 [https://bugs.python.org/issue?@action=redirect&bpo=25411]: Improved Unicode support in SMTPHandler through better use of the email package. Thanks to user simon04 for the patch.

bpo-25407 [https://bugs.python.org/issue?@action=redirect&bpo=25407]: Remove mentions of the formatter module being removed in Python 3.6.

bpo-25406 [https://bugs.python.org/issue?@action=redirect&bpo=25406]: Fixed a bug in C implementation of OrderedDict.move_to_end() that caused segmentation fault or hang in iterating after moving several items to the start of ordered dict.

bpo-25364 [https://bugs.python.org/issue?@action=redirect&bpo=25364]: zipfile now works in threads disabled builds.

bpo-25328 [https://bugs.python.org/issue?@action=redirect&bpo=25328]: smtpd’s SMTPChannel now correctly raises a ValueError if both decode_data and enable_SMTPUTF8 are set to true.

bpo-25316 [https://bugs.python.org/issue?@action=redirect&bpo=25316]: distutils raises OSError instead of DistutilsPlatformError when MSVC is not installed.

bpo-25380 [https://bugs.python.org/issue?@action=redirect&bpo=25380]: Fixed protocol for the STACK_GLOBAL opcode in pickletools.opcodes.

bpo-23972 [https://bugs.python.org/issue?@action=redirect&bpo=23972]: Updates asyncio datagram create method allowing reuseport and reuseaddr socket options to be set prior to binding the socket. Mirroring the existing asyncio create_server method the reuseaddr option for datagram sockets defaults to True if the O/S is “posix” (except if the platform is Cygwin). Patch by Chris Laws.

bpo-25304 [https://bugs.python.org/issue?@action=redirect&bpo=25304]: Add asyncio.run_coroutine_threadsafe(). This lets you submit a coroutine to a loop from another thread, returning a concurrent.futures.Future. By Vincent Michel.

bpo-25232 [https://bugs.python.org/issue?@action=redirect&bpo=25232]: Fix CGIRequestHandler to split the query from the URL at the first question mark (?) rather than the last. Patch from Xiang Zhang.

bpo-24657 [https://bugs.python.org/issue?@action=redirect&bpo=24657]: Prevent CGIRequestHandler from collapsing slashes in the query part of the URL as if it were a path. Patch from Xiang Zhang.

bpo-24483 [https://bugs.python.org/issue?@action=redirect&bpo=24483]: C implementation of functools.lru_cache() now calculates key’s hash only once.

bpo-22958 [https://bugs.python.org/issue?@action=redirect&bpo=22958]: Constructor and update method of weakref.WeakValueDictionary now accept the self and the dict keyword arguments.

bpo-22609 [https://bugs.python.org/issue?@action=redirect&bpo=22609]: Constructor of collections.UserDict now accepts the self keyword argument.

bpo-25111 [https://bugs.python.org/issue?@action=redirect&bpo=25111]: Fixed comparison of traceback.FrameSummary.

bpo-25262 [https://bugs.python.org/issue?@action=redirect&bpo=25262]: Added support for BINBYTES8 opcode in Python implementation of unpickler. Highest 32 bits of 64-bit size for BINUNICODE8 and BINBYTES8 opcodes no longer silently ignored on 32-bit platforms in C implementation.

bpo-25034 [https://bugs.python.org/issue?@action=redirect&bpo=25034]: Fix string.Formatter problem with auto-numbering and nested format_specs. Patch by Anthon van der Neut.

bpo-25233 [https://bugs.python.org/issue?@action=redirect&bpo=25233]: Rewrite the guts of asyncio.Queue and asyncio.Semaphore to be more understandable and correct.

bpo-25203 [https://bugs.python.org/issue?@action=redirect&bpo=25203]: Failed readline.set_completer_delims() no longer left the module in inconsistent state.

bpo-23600 [https://bugs.python.org/issue?@action=redirect&bpo=23600]: Default implementation of tzinfo.fromutc() was returning wrong results in some cases.

bpo-23329 [https://bugs.python.org/issue?@action=redirect&bpo=23329]: Allow the ssl module to be built with older versions of LibreSSL.

Prevent overflow in _Unpickler_Read.

bpo-25047 [https://bugs.python.org/issue?@action=redirect&bpo=25047]: The XML encoding declaration written by Element Tree now respects the letter case given by the user. This restores the ability to write encoding names in uppercase like «UTF-8», which worked in Python 2.

bpo-25135 [https://bugs.python.org/issue?@action=redirect&bpo=25135]: Make deque_clear() safer by emptying the deque before clearing. This helps avoid possible reentrancy issues.

bpo-19143 [https://bugs.python.org/issue?@action=redirect&bpo=19143]: platform module now reads Windows version from kernel32.dll to avoid compatibility shims.

bpo-25092 [https://bugs.python.org/issue?@action=redirect&bpo=25092]: Fix datetime.strftime() failure when errno was already set to EINVAL.

bpo-23517 [https://bugs.python.org/issue?@action=redirect&bpo=23517]: Fix rounding in fromtimestamp() and utcfromtimestamp() methods of datetime.datetime: microseconds are now rounded to nearest with ties going to nearest even integer (ROUND_HALF_EVEN), instead of being rounding towards minus infinity (ROUND_FLOOR). It’s important that these methods use the same rounding mode than datetime.timedelta to keep the property: (datetime(1970,1,1) + timedelta(seconds=t)) == datetime.utcfromtimestamp(t). It also the rounding mode used by round(float) for example.

bpo-25155 [https://bugs.python.org/issue?@action=redirect&bpo=25155]: Fix datetime.datetime.now() and datetime.datetime.utcnow() on Windows to support date after year 2038. It was a regression introduced in Python 3.5.0.

bpo-25108 [https://bugs.python.org/issue?@action=redirect&bpo=25108]: Omitted internal frames in traceback functions print_stack(), format_stack(), and extract_stack() called without arguments.

bpo-25118 [https://bugs.python.org/issue?@action=redirect&bpo=25118]: Fix a regression of Python 3.5.0 in os.waitpid() on Windows.

bpo-24684 [https://bugs.python.org/issue?@action=redirect&bpo=24684]: socket.socket.getaddrinfo() now calls PyUnicode_AsEncodedString() instead of calling the encode() method of the host, to handle correctly custom string with an encode() method which doesn’t return a byte string. The encoder of the IDNA codec is now called directly instead of calling the encode() method of the string.

bpo-25060 [https://bugs.python.org/issue?@action=redirect&bpo=25060]: Correctly compute stack usage of the BUILD_MAP opcode.

bpo-24857 [https://bugs.python.org/issue?@action=redirect&bpo=24857]: Comparing call_args to a long sequence now correctly returns a boolean result instead of raising an exception. Patch by A Kaptur.

bpo-23144 [https://bugs.python.org/issue?@action=redirect&bpo=23144]: Make sure that HTMLParser.feed() returns all the data, even when convert_charrefs is True.

bpo-24982 [https://bugs.python.org/issue?@action=redirect&bpo=24982]: shutil.make_archive() with the «zip» format now adds entries for directories (including empty directories) in ZIP file.

bpo-25019 [https://bugs.python.org/issue?@action=redirect&bpo=25019]: Fixed a crash caused by setting non-string key of expat parser. Based on patch by John Leitch.

bpo-16180 [https://bugs.python.org/issue?@action=redirect&bpo=16180]: Exit pdb if file has syntax error, instead of trapping user in an infinite loop. Patch by Xavier de Gaye.

bpo-24891 [https://bugs.python.org/issue?@action=redirect&bpo=24891]: Fix a race condition at Python startup if the file descriptor of stdin (0), stdout (1) or stderr (2) is closed while Python is creating sys.stdin, sys.stdout and sys.stderr objects. These attributes are now set to None if the creation of the object failed, instead of raising an OSError exception. Initial patch written by Marco Paolini.

bpo-24992 [https://bugs.python.org/issue?@action=redirect&bpo=24992]: Fix error handling and a race condition (related to garbage collection) in collections.OrderedDict constructor.

bpo-24881 [https://bugs.python.org/issue?@action=redirect&bpo=24881]: Fixed setting binary mode in Python implementation of FileIO on Windows and Cygwin. Patch from Akira Li.

bpo-25578 [https://bugs.python.org/issue?@action=redirect&bpo=25578]: Fix (another) memory leak in SSLSocket.getpeercer().

bpo-25530 [https://bugs.python.org/issue?@action=redirect&bpo=25530]: Disable the vulnerable SSLv3 protocol by default when creating ssl.SSLContext.

bpo-25569 [https://bugs.python.org/issue?@action=redirect&bpo=25569]: Fix memory leak in SSLSocket.getpeercert().

bpo-25471 [https://bugs.python.org/issue?@action=redirect&bpo=25471]: Sockets returned from accept() shouldn’t appear to be nonblocking.

bpo-25319 [https://bugs.python.org/issue?@action=redirect&bpo=25319]: When threading.Event is reinitialized, the underlying condition should use a regular lock rather than a recursive lock.

bpo-21112 [https://bugs.python.org/issue?@action=redirect&bpo=21112]: Fix regression in unittest.expectedFailure on subclasses. Patch from Berker Peksag.

bpo-24764 [https://bugs.python.org/issue?@action=redirect&bpo=24764]: cgi.FieldStorage.read_multi() now ignores the Content-Length header in part headers. Patch written by Peter Landry and reviewed by Pierre Quentel.

bpo-24913 [https://bugs.python.org/issue?@action=redirect&bpo=24913]: Fix overrun error in deque.index(). Found by John Leitch and Bryce Darling.

bpo-24774 [https://bugs.python.org/issue?@action=redirect&bpo=24774]: Fix docstring in http.server.test. Patch from Chiu-Hsiang Hsu.

bpo-21159 [https://bugs.python.org/issue?@action=redirect&bpo=21159]: Improve message in configparser.InterpolationMissingOptionError. Patch from Łukasz Langa.

bpo-20362 [https://bugs.python.org/issue?@action=redirect&bpo=20362]: Honour TestCase.longMessage correctly in assertRegex. Patch from Ilia Kurenkov.

bpo-23572 [https://bugs.python.org/issue?@action=redirect&bpo=23572]: Fixed functools.singledispatch on classes with falsy metaclasses. Patch by Ethan Furman.

asyncio: ensure_future() now accepts awaitable objects.

IDLE

bpo-15348 [https://bugs.python.org/issue?@action=redirect&bpo=15348]: Stop the debugger engine (normally in a user process) before closing the debugger window (running in the IDLE process). This prevents the RuntimeErrors that were being caught and ignored.

bpo-24455 [https://bugs.python.org/issue?@action=redirect&bpo=24455]: Prevent IDLE from hanging when a) closing the shell while the debugger is active (15347); b) closing the debugger with the [X] button (15348); and c) activating the debugger when already active (24455). The patch by Mark Roseman does this by making two changes. 1. Suspend and resume the gui.interaction method with the tcl vwait mechanism intended for this purpose (instead of root.mainloop & .quit). 2. In gui.run, allow any existing interaction to terminate first.

Change “The program” to “Your program” in an IDLE “kill program?” message to make it clearer that the program referred to is the currently running user program, not IDLE itself.

bpo-24750 [https://bugs.python.org/issue?@action=redirect&bpo=24750]: Improve the appearance of the IDLE editor window status bar. Patch by Mark Roseman.

bpo-25313 [https://bugs.python.org/issue?@action=redirect&bpo=25313]: Change the handling of new built-in text color themes to better address the compatibility problem introduced by the addition of IDLE Dark. Consistently use the revised idleConf.CurrentTheme everywhere in idlelib.

bpo-24782 [https://bugs.python.org/issue?@action=redirect&bpo=24782]: Extension configuration is now a tab in the IDLE Preferences dialog rather than a separate dialog. The former tabs are now a sorted list. Patch by Mark Roseman.

bpo-22726 [https://bugs.python.org/issue?@action=redirect&bpo=22726]: Re-activate the config dialog help button with some content about the other buttons and the new IDLE Dark theme.

bpo-24820 [https://bugs.python.org/issue?@action=redirect&bpo=24820]: IDLE now has an “IDLE Dark” built-in text color theme. It is more or less IDLE Classic inverted, with a cobalt blue background. Strings, comments, keywords, … are still green, red, orange, … . To use it with IDLEs released before November 2015, hit the “Save as New Custom Theme” button and enter a new name, such as “Custom Dark”. The custom theme will work with any IDLE release, and can be modified.

bpo-25224 [https://bugs.python.org/issue?@action=redirect&bpo=25224]: README.txt is now an idlelib index for IDLE developers and curious users. The previous user content is now in the IDLE doc chapter. “IDLE” now means “Integrated Development and Learning Environment”.

bpo-24820 [https://bugs.python.org/issue?@action=redirect&bpo=24820]: Users can now set breakpoint colors in Settings -> Custom Highlighting. Original patch by Mark Roseman.

bpo-24972 [https://bugs.python.org/issue?@action=redirect&bpo=24972]: Inactive selection background now matches active selection background, as configured by users, on all systems. Found items are now always highlighted on Windows. Initial patch by Mark Roseman.

bpo-24570 [https://bugs.python.org/issue?@action=redirect&bpo=24570]: Idle: make calltip and completion boxes appear on Macs affected by a tk regression. Initial patch by Mark Roseman.

bpo-24988 [https://bugs.python.org/issue?@action=redirect&bpo=24988]: Idle ScrolledList context menus (used in debugger) now work on Mac Aqua. Patch by Mark Roseman.

bpo-24801 [https://bugs.python.org/issue?@action=redirect&bpo=24801]: Make right-click for context menu work on Mac Aqua. Patch by Mark Roseman.

bpo-25173 [https://bugs.python.org/issue?@action=redirect&bpo=25173]: Associate tkinter messageboxes with a specific widget. For Mac OSX, make them a “sheet”. Patch by Mark Roseman.

bpo-25198 [https://bugs.python.org/issue?@action=redirect&bpo=25198]: Enhance the initial html viewer now used for Idle Help. Properly indent fixed-pitch text (patch by Mark Roseman). Give code snippet a very Sphinx-like light blueish-gray background. Re-use initial width and height set by users for shell and editor. When the Table of Contents (TOC) menu is used, put the section header at the top of the screen.

bpo-25225 [https://bugs.python.org/issue?@action=redirect&bpo=25225]: Condense and rewrite Idle doc section on text colors.

bpo-21995 [https://bugs.python.org/issue?@action=redirect&bpo=21995]: Explain some differences between IDLE and console Python.

bpo-22820 [https://bugs.python.org/issue?@action=redirect&bpo=22820]: Explain need for print when running file from Idle editor.

bpo-25224 [https://bugs.python.org/issue?@action=redirect&bpo=25224]: Doc: augment Idle feature list and no-subprocess section.

bpo-25219 [https://bugs.python.org/issue?@action=redirect&bpo=25219]: Update doc for Idle command line options. Some were missing and notes were not correct.

bpo-24861 [https://bugs.python.org/issue?@action=redirect&bpo=24861]: Most of idlelib is private and subject to change. Use idleib.idle.* to start Idle. See idlelib.__init__.__doc__.

bpo-25199 [https://bugs.python.org/issue?@action=redirect&bpo=25199]: Idle: add synchronization comments for future maintainers.

bpo-16893 [https://bugs.python.org/issue?@action=redirect&bpo=16893]: Replace help.txt with help.html for Idle doc display. The new idlelib/help.html is rstripped Doc/build/html/library/idle.html. It looks better than help.txt and will better document Idle as released. The tkinter html viewer that works for this file was written by Mark Roseman. The now unused EditorWindow.HelpDialog class and helt.txt file are deprecated.

bpo-24199 [https://bugs.python.org/issue?@action=redirect&bpo=24199]: Deprecate unused idlelib.idlever with possible removal in 3.6.

bpo-24790 [https://bugs.python.org/issue?@action=redirect&bpo=24790]: Remove extraneous code (which also create 2 & 3 conflicts).

Documentation

bpo-22558 [https://bugs.python.org/issue?@action=redirect&bpo=22558]: Add remaining doc links to source code for Python-coded modules. Patch by Yoni Lavi.

bpo-12067 [https://bugs.python.org/issue?@action=redirect&bpo=12067]: Rewrite Comparisons section in the Expressions chapter of the language reference. Some of the details of comparing mixed types were incorrect or ambiguous. NotImplemented is only relevant at a lower level than the Expressions chapter. Added details of comparing range() objects, and default behaviour and consistency suggestions for user-defined classes. Patch from Andy Maier.

bpo-24952 [https://bugs.python.org/issue?@action=redirect&bpo=24952]: Clarify the default size argument of stack_size() in the «threading» and «_thread» modules. Patch from Mattip.

bpo-23725 [https://bugs.python.org/issue?@action=redirect&bpo=23725]: Overhaul tempfile docs. Note deprecated status of mktemp. Patch from Zbigniew Jędrzejewski-Szmek.

bpo-24808 [https://bugs.python.org/issue?@action=redirect&bpo=24808]: Update the types of some PyTypeObject fields. Patch by Joseph Weston.

bpo-22812 [https://bugs.python.org/issue?@action=redirect&bpo=22812]: Fix unittest discovery examples. Patch from Pam McA’Nulty.

Tests

bpo-25449 [https://bugs.python.org/issue?@action=redirect&bpo=25449]: Added tests for OrderedDict subclasses.

bpo-25099 [https://bugs.python.org/issue?@action=redirect&bpo=25099]: Make test_compileall not fail when an entry on sys.path cannot be written to (commonly seen in administrative installs on Windows).

bpo-23919 [https://bugs.python.org/issue?@action=redirect&bpo=23919]: Prevents assert dialogs appearing in the test suite.

PCbuild\rt.bat now accepts an unlimited number of arguments to pass along to regrtest.py. Previously there was a limit of 9.

Build

bpo-24915 [https://bugs.python.org/issue?@action=redirect&bpo=24915]: Add LLVM support for PGO builds and use the test suite to generate the profile data. Initial patch by Alecsandru Patrascu of Intel.

bpo-24910 [https://bugs.python.org/issue?@action=redirect&bpo=24910]: Windows MSIs now have unique display names.

bpo-24986 [https://bugs.python.org/issue?@action=redirect&bpo=24986]: It is now possible to build Python on Windows without errors when external libraries are not available.

Windows

bpo-25450 [https://bugs.python.org/issue?@action=redirect&bpo=25450]: Updates shortcuts to start Python in installation directory.

bpo-25164 [https://bugs.python.org/issue?@action=redirect&bpo=25164]: Changes default all-users install directory to match per-user directory.

bpo-25143 [https://bugs.python.org/issue?@action=redirect&bpo=25143]: Improves installer error messages for unsupported platforms.

bpo-25163 [https://bugs.python.org/issue?@action=redirect&bpo=25163]: Display correct directory in installer when using non-default settings.

bpo-25361 [https://bugs.python.org/issue?@action=redirect&bpo=25361]: Disables use of SSE2 instructions in Windows 32-bit build

bpo-25089 [https://bugs.python.org/issue?@action=redirect&bpo=25089]: Adds logging to installer for case where launcher is not selected on upgrade.

bpo-25165 [https://bugs.python.org/issue?@action=redirect&bpo=25165]: Windows uninstallation should not remove launcher if other versions remain

bpo-25112 [https://bugs.python.org/issue?@action=redirect&bpo=25112]: py.exe launcher is missing icons

bpo-25102 [https://bugs.python.org/issue?@action=redirect&bpo=25102]: Windows installer does not precompile for -O or -OO.

bpo-25081 [https://bugs.python.org/issue?@action=redirect&bpo=25081]: Makes Back button in installer go back to upgrade page when upgrading.

bpo-25091 [https://bugs.python.org/issue?@action=redirect&bpo=25091]: Increases font size of the installer.

bpo-25126 [https://bugs.python.org/issue?@action=redirect&bpo=25126]: Clarifies that the non-web installer will download some components.

bpo-25213 [https://bugs.python.org/issue?@action=redirect&bpo=25213]: Restores requestedExecutionLevel to manifest to disable UAC virtualization.

bpo-25022 [https://bugs.python.org/issue?@action=redirect&bpo=25022]: Removed very outdated PC/example_nt/ directory.

Tools/Demos

bpo-25440 [https://bugs.python.org/issue?@action=redirect&bpo=25440]: Fix output of python-config –extension-suffix.

Python 3.5.0 final

Release date: 2015-09-13

Build

bpo-25071 [https://bugs.python.org/issue?@action=redirect&bpo=25071]: Windows installer should not require TargetDir parameter when installing quietly.

Python 3.5.0 release candidate 4

Release date: 2015-09-09

Library

bpo-25029 [https://bugs.python.org/issue?@action=redirect&bpo=25029]: Fixes MemoryError in test_strptime.

Build

bpo-25027 [https://bugs.python.org/issue?@action=redirect&bpo=25027]: Reverts partial-static build options and adds vcruntime140.dll to Windows installation.

Python 3.5.0 release candidate 3

Release date: 2015-09-07

Core and Builtins

bpo-24305 [https://bugs.python.org/issue?@action=redirect&bpo=24305]: Prevent import subsystem stack frames from being counted by the warnings.warn(stacklevel=) parameter.

bpo-24912 [https://bugs.python.org/issue?@action=redirect&bpo=24912]: Prevent __class__ assignment to immutable built-in objects.

bpo-24975 [https://bugs.python.org/issue?@action=redirect&bpo=24975]: Fix AST compilation for PEP 448 [https://www.python.org/dev/peps/pep-0448] syntax.

Library

bpo-24917 [https://bugs.python.org/issue?@action=redirect&bpo=24917]: time_strftime() buffer over-read.

bpo-24748 [https://bugs.python.org/issue?@action=redirect&bpo=24748]: To resolve a compatibility problem found with py2exe and pywin32, imp.load_dynamic() once again ignores previously loaded modules to support Python modules replacing themselves with extension modules. Patch by Petr Viktorin.

bpo-24635 [https://bugs.python.org/issue?@action=redirect&bpo=24635]: Fixed a bug in typing.py where isinstance([], typing.Iterable) would return True once, then False on subsequent calls.

bpo-24989 [https://bugs.python.org/issue?@action=redirect&bpo=24989]: Fixed buffer overread in BytesIO.readline() if a position is set beyond size. Based on patch by John Leitch.

bpo-24913 [https://bugs.python.org/issue?@action=redirect&bpo=24913]: Fix overrun error in deque.index(). Found by John Leitch and Bryce Darling.

Python 3.5.0 release candidate 2

Release date: 2015-08-25

Core and Builtins

bpo-24769 [https://bugs.python.org/issue?@action=redirect&bpo=24769]: Interpreter now starts properly when dynamic loading is disabled. Patch by Petr Viktorin.

bpo-21167 [https://bugs.python.org/issue?@action=redirect&bpo=21167]: NAN operations are now handled correctly when python is compiled with ICC even if -fp-model strict is not specified.

bpo-24492 [https://bugs.python.org/issue?@action=redirect&bpo=24492]: A «package» lacking a __name__ attribute when trying to perform a from .. import ... statement will trigger an ImportError instead of an AttributeError.

Library

bpo-24847 [https://bugs.python.org/issue?@action=redirect&bpo=24847]: Removes vcruntime140.dll dependency from Tcl/Tk.

bpo-24839 [https://bugs.python.org/issue?@action=redirect&bpo=24839]: platform._syscmd_ver raises DeprecationWarning

bpo-24867 [https://bugs.python.org/issue?@action=redirect&bpo=24867]: Fix Task.get_stack() for “async def” coroutines

Python 3.5.0 release candidate 1

Release date: 2015-08-09

Core and Builtins

bpo-24667 [https://bugs.python.org/issue?@action=redirect&bpo=24667]: Resize odict in all cases that the underlying dict resizes.

Library

bpo-24824 [https://bugs.python.org/issue?@action=redirect&bpo=24824]: Signatures of codecs.encode() and codecs.decode() now are compatible with pydoc.

bpo-24634 [https://bugs.python.org/issue?@action=redirect&bpo=24634]: Importing uuid should not try to load libc on Windows

bpo-24798 [https://bugs.python.org/issue?@action=redirect&bpo=24798]: _msvccompiler.py doesn’t properly support manifests

bpo-4395 [https://bugs.python.org/issue?@action=redirect&bpo=4395]: Better testing and documentation of binary operators. Patch by Martin Panter.

bpo-23973 [https://bugs.python.org/issue?@action=redirect&bpo=23973]: Update typing.py from GitHub repo.

bpo-23004 [https://bugs.python.org/issue?@action=redirect&bpo=23004]: mock_open() now reads binary data correctly when the type of read_data is bytes. Initial patch by Aaron Hill.

bpo-23888 [https://bugs.python.org/issue?@action=redirect&bpo=23888]: Handle fractional time in cookie expiry. Patch by ssh.

bpo-23652 [https://bugs.python.org/issue?@action=redirect&bpo=23652]: Make it possible to compile the select module against the libc headers from the Linux Standard Base, which do not include some EPOLL macros. Patch by Matt Frank.

bpo-22932 [https://bugs.python.org/issue?@action=redirect&bpo=22932]: Fix timezones in email.utils.formatdate. Patch from Dmitry Shachnev.

bpo-23779 [https://bugs.python.org/issue?@action=redirect&bpo=23779]: imaplib raises TypeError if authenticator tries to abort. Patch from Craig Holmquist.

bpo-23319 [https://bugs.python.org/issue?@action=redirect&bpo=23319]: Fix ctypes.BigEndianStructure, swap correctly bytes. Patch written by Matthieu Gautier.

bpo-23254 [https://bugs.python.org/issue?@action=redirect&bpo=23254]: Document how to close the TCPServer listening socket. Patch from Martin Panter.

bpo-19450 [https://bugs.python.org/issue?@action=redirect&bpo=19450]: Update Windows and OS X installer builds to use SQLite 3.8.11.

bpo-17527 [https://bugs.python.org/issue?@action=redirect&bpo=17527]: Add PATCH to wsgiref.validator. Patch from Luca Sbardella.

bpo-24791 [https://bugs.python.org/issue?@action=redirect&bpo=24791]: Fix grammar regression for call syntax: “g(*a or b)”.

IDLE

bpo-23672 [https://bugs.python.org/issue?@action=redirect&bpo=23672]: Allow Idle to edit and run files with astral chars in name. Patch by Mohd Sanad Zaki Rizvi.

bpo-24745 [https://bugs.python.org/issue?@action=redirect&bpo=24745]: Idle editor default font. Switch from Courier to platform-sensitive TkFixedFont. This should not affect current customized font selections. If there is a problem, edit $HOME/.idlerc/config-main.cfg and remove “fontxxx” entries from [Editor Window]. Patch by Mark Roseman.

bpo-21192 [https://bugs.python.org/issue?@action=redirect&bpo=21192]: Idle editor. When a file is run, put its name in the restart bar. Do not print false prompts. Original patch by Adnan Umer.

bpo-13884 [https://bugs.python.org/issue?@action=redirect&bpo=13884]: Idle menus. Remove tearoff lines. Patch by Roger Serwy.

Documentation

bpo-24129 [https://bugs.python.org/issue?@action=redirect&bpo=24129]: Clarify the reference documentation for name resolution. This includes removing the assumption that readers will be familiar with the name resolution scheme Python used prior to the introduction of lexical scoping for function namespaces. Patch by Ivan Levkivskyi.

bpo-20769 [https://bugs.python.org/issue?@action=redirect&bpo=20769]: Improve reload() docs. Patch by Dorian Pula.

bpo-23589 [https://bugs.python.org/issue?@action=redirect&bpo=23589]: Remove duplicate sentence from the FAQ. Patch by Yongzhi Pan.

bpo-24729 [https://bugs.python.org/issue?@action=redirect&bpo=24729]: Correct IO tutorial to match implementation regarding encoding parameter to open function.

Tests

bpo-24751 [https://bugs.python.org/issue?@action=redirect&bpo=24751]: When running regrtest with the -w command line option, a test run is no longer marked as a failure if all tests succeed when re-run.

Python 3.5.0 beta 4

Release date: 2015-07-26

Core and Builtins

bpo-23573 [https://bugs.python.org/issue?@action=redirect&bpo=23573]: Restored optimization of bytes.rfind() and bytearray.rfind() for single-byte argument on Linux.

bpo-24569 [https://bugs.python.org/issue?@action=redirect&bpo=24569]: Make PEP 448 [https://www.python.org/dev/peps/pep-0448] dictionary evaluation more consistent.

bpo-24583 [https://bugs.python.org/issue?@action=redirect&bpo=24583]: Fix crash when set is mutated while being updated.

bpo-24407 [https://bugs.python.org/issue?@action=redirect&bpo=24407]: Fix crash when dict is mutated while being updated.

bpo-24619 [https://bugs.python.org/issue?@action=redirect&bpo=24619]: New approach for tokenizing async/await. As a consequence, it is now possible to have one-line “async def foo(): await ..” functions.

bpo-24687 [https://bugs.python.org/issue?@action=redirect&bpo=24687]: Plug refleak on SyntaxError in function parameters annotations.

bpo-15944 [https://bugs.python.org/issue?@action=redirect&bpo=15944]: memoryview: Allow arbitrary formats when casting to bytes. Patch by Martin Panter.

Library

bpo-23441 [https://bugs.python.org/issue?@action=redirect&bpo=23441]: rcompleter now prints a tab character instead of displaying possible completions for an empty word. Initial patch by Martin Sekera.

bpo-24683 [https://bugs.python.org/issue?@action=redirect&bpo=24683]: Fixed crashes in _json functions called with arguments of inappropriate type.

bpo-21697 [https://bugs.python.org/issue?@action=redirect&bpo=21697]: shutil.copytree() now correctly handles symbolic links that point to directories. Patch by Eduardo Seabra and Thomas Kluyver.

bpo-14373 [https://bugs.python.org/issue?@action=redirect&bpo=14373]: Fixed segmentation fault when gc.collect() is called during constructing lru_cache (C implementation).

bpo-24695 [https://bugs.python.org/issue?@action=redirect&bpo=24695]: Fix a regression in traceback.print_exception(). If exc_traceback is None we shouldn’t print a traceback header like described in the documentation.

bpo-24620 [https://bugs.python.org/issue?@action=redirect&bpo=24620]: Random.setstate() now validates the value of state last element.

bpo-22485 [https://bugs.python.org/issue?@action=redirect&bpo=22485]: Fixed an issue that caused inspect.getsource to return incorrect results on nested functions.

bpo-22153 [https://bugs.python.org/issue?@action=redirect&bpo=22153]: Improve unittest docs. Patch from Martin Panter and evilzero.

bpo-24580 [https://bugs.python.org/issue?@action=redirect&bpo=24580]: Symbolic group references to open group in re patterns now are explicitly forbidden as well as numeric group references.

bpo-24206 [https://bugs.python.org/issue?@action=redirect&bpo=24206]: Fixed __eq__ and __ne__ methods of inspect classes.

bpo-24631 [https://bugs.python.org/issue?@action=redirect&bpo=24631]: Fixed regression in the timeit module with multiline setup.

bpo-18622 [https://bugs.python.org/issue?@action=redirect&bpo=18622]: unittest.mock.mock_open().reset_mock would recurse infinitely. Patch from Nicola Palumbo and Laurent De Buyst.

bpo-23661 [https://bugs.python.org/issue?@action=redirect&bpo=23661]: unittest.mock side_effects can now be exceptions again. This was a regression vs Python 3.4. Patch from Ignacio Rossi

bpo-24608 [https://bugs.python.org/issue?@action=redirect&bpo=24608]: chunk.Chunk.read() now always returns bytes, not str.

bpo-18684 [https://bugs.python.org/issue?@action=redirect&bpo=18684]: Fixed reading out of the buffer in the re module.

bpo-24259 [https://bugs.python.org/issue?@action=redirect&bpo=24259]: tarfile now raises a ReadError if an archive is truncated inside a data segment.

bpo-15014 [https://bugs.python.org/issue?@action=redirect&bpo=15014]: SMTP.auth() and SMTP.login() now support RFC 4954’s optional initial-response argument to the SMTP AUTH command.

bpo-24669 [https://bugs.python.org/issue?@action=redirect&bpo=24669]: Fix inspect.getsource() for “async def” functions. Patch by Kai Groner.

bpo-24688 [https://bugs.python.org/issue?@action=redirect&bpo=24688]: ast.get_docstring() for “async def” functions.

Build

bpo-24603 [https://bugs.python.org/issue?@action=redirect&bpo=24603]: Update Windows builds and OS X 10.5 installer to use OpenSSL 1.0.2d.

Python 3.5.0 beta 3

Release date: 2015-07-05

Core and Builtins

bpo-24467 [https://bugs.python.org/issue?@action=redirect&bpo=24467]: Fixed possible buffer over-read in bytearray. The bytearray object now always allocates place for trailing null byte and it’s buffer now is always null-terminated.

Upgrade to Unicode 8.0.0.

bpo-24345 [https://bugs.python.org/issue?@action=redirect&bpo=24345]: Add Py_tp_finalize slot for the stable ABI.

bpo-24400 [https://bugs.python.org/issue?@action=redirect&bpo=24400]: Introduce a distinct type for PEP 492 [https://www.python.org/dev/peps/pep-0492] coroutines; add types.CoroutineType, inspect.getcoroutinestate, inspect.getcoroutinelocals; coroutines no longer use CO_GENERATOR flag; sys.set_coroutine_wrapper works only for “async def” coroutines; inspect.iscoroutine no longer uses collections.abc.Coroutine, it’s intended to test for pure “async def” coroutines only; add new opcode: GET_YIELD_FROM_ITER; fix generators wrapper used in types.coroutine to be instance of collections.abc.Generator; collections.abc.Awaitable and collections.abc.Coroutine can no longer be used to detect generator-based coroutines–use inspect.isawaitable instead.

bpo-24450 [https://bugs.python.org/issue?@action=redirect&bpo=24450]: Add gi_yieldfrom to generators and cr_await to coroutines. Contributed by Benno Leslie and Yury Selivanov.

bpo-19235 [https://bugs.python.org/issue?@action=redirect&bpo=19235]: Add new RecursionError exception. Patch by Georg Brandl.

Library

bpo-21750 [https://bugs.python.org/issue?@action=redirect&bpo=21750]: mock_open.read_data can now be read from each instance, as it could in Python 3.3.

bpo-24552 [https://bugs.python.org/issue?@action=redirect&bpo=24552]: Fix use after free in an error case of the _pickle module.

bpo-24514 [https://bugs.python.org/issue?@action=redirect&bpo=24514]: tarfile now tolerates number fields consisting of only whitespace.

bpo-19176 [https://bugs.python.org/issue?@action=redirect&bpo=19176]: Fixed doctype() related bugs in C implementation of ElementTree. A deprecation warning no longer issued by XMLParser subclass with default doctype() method. Direct call of doctype() now issues a warning. Parser’s doctype() now is not called if target’s doctype() is called. Based on patch by Martin Panter.

bpo-20387 [https://bugs.python.org/issue?@action=redirect&bpo=20387]: Restore semantic round-trip correctness in tokenize/untokenize for tab-indented blocks.

bpo-24456 [https://bugs.python.org/issue?@action=redirect&bpo=24456]: Fixed possible buffer over-read in adpcm2lin() and lin2adpcm() functions of the audioop module.

bpo-24336 [https://bugs.python.org/issue?@action=redirect&bpo=24336]: The contextmanager decorator now works with functions with keyword arguments called «func» and «self». Patch by Martin Panter.

bpo-24522 [https://bugs.python.org/issue?@action=redirect&bpo=24522]: Fix possible integer overflow in json accelerator module.

bpo-24489 [https://bugs.python.org/issue?@action=redirect&bpo=24489]: ensure a previously set C errno doesn’t disturb cmath.polar().

bpo-24408 [https://bugs.python.org/issue?@action=redirect&bpo=24408]: Fixed AttributeError in measure() and metrics() methods of tkinter.Font.

bpo-14373 [https://bugs.python.org/issue?@action=redirect&bpo=14373]: C implementation of functools.lru_cache() now can be used with methods.

bpo-24347 [https://bugs.python.org/issue?@action=redirect&bpo=24347]: Set KeyError if PyDict_GetItemWithError returns NULL.

bpo-24348 [https://bugs.python.org/issue?@action=redirect&bpo=24348]: Drop superfluous incref/decref.

bpo-24359 [https://bugs.python.org/issue?@action=redirect&bpo=24359]: Check for changed OrderedDict size during iteration.

bpo-24368 [https://bugs.python.org/issue?@action=redirect&bpo=24368]: Support keyword arguments in OrderedDict methods.

bpo-24362 [https://bugs.python.org/issue?@action=redirect&bpo=24362]: Simplify the C OrderedDict fast nodes resize logic.

bpo-24377 [https://bugs.python.org/issue?@action=redirect&bpo=24377]: Fix a ref leak in OrderedDict.__repr__.

bpo-24369 [https://bugs.python.org/issue?@action=redirect&bpo=24369]: Defend against key-changes during iteration.

Tests

bpo-24373 [https://bugs.python.org/issue?@action=redirect&bpo=24373]: _testmultiphase and xxlimited now use tp_traverse and tp_finalize to avoid reference leaks encountered when combining tp_dealloc with PyType_FromSpec (see bpo-16690 [https://bugs.python.org/issue?@action=redirect&bpo=16690] for details)

Documentation

bpo-24458 [https://bugs.python.org/issue?@action=redirect&bpo=24458]: Update documentation to cover multi-phase initialization for extension modules (PEP 489). Patch by Petr Viktorin.

bpo-24351 [https://bugs.python.org/issue?@action=redirect&bpo=24351]: Clarify what is meant by «identifier» in the context of string.Template instances.

Build

bpo-24432 [https://bugs.python.org/issue?@action=redirect&bpo=24432]: Update Windows builds and OS X 10.5 installer to use OpenSSL 1.0.2c.

Python 3.5.0 beta 2

Release date: 2015-05-31

Core and Builtins

bpo-24284 [https://bugs.python.org/issue?@action=redirect&bpo=24284]: The startswith and endswith methods of the str class no longer return True when finding the empty string and the indexes are completely out of range.

bpo-24115 [https://bugs.python.org/issue?@action=redirect&bpo=24115]: Update uses of PyObject_IsTrue(), PyObject_Not(), PyObject_IsInstance(), PyObject_RichCompareBool() and _PyDict_Contains() to check for and handle errors correctly.

bpo-24328 [https://bugs.python.org/issue?@action=redirect&bpo=24328]: Fix importing one character extension modules.

bpo-11205 [https://bugs.python.org/issue?@action=redirect&bpo=11205]: In dictionary displays, evaluate the key before the value.

bpo-24285 [https://bugs.python.org/issue?@action=redirect&bpo=24285]: Fixed regression that prevented importing extension modules from inside packages. Patch by Petr Viktorin.

Library

bpo-23247 [https://bugs.python.org/issue?@action=redirect&bpo=23247]: Fix a crash in the StreamWriter.reset() of CJK codecs.

bpo-24270 [https://bugs.python.org/issue?@action=redirect&bpo=24270]: Add math.isclose() and cmath.isclose() functions as per PEP 485 [https://www.python.org/dev/peps/pep-0485]. Contributed by Chris Barker and Tal Einat.

bpo-5633 [https://bugs.python.org/issue?@action=redirect&bpo=5633]: Fixed timeit when the statement is a string and the setup is not.

bpo-24326 [https://bugs.python.org/issue?@action=redirect&bpo=24326]: Fixed audioop.ratecv() with non-default weightB argument. Original patch by David Moore.

bpo-16991 [https://bugs.python.org/issue?@action=redirect&bpo=16991]: Add a C implementation of OrderedDict.

bpo-23934 [https://bugs.python.org/issue?@action=redirect&bpo=23934]: Fix inspect.signature to fail correctly for builtin types lacking signature information. Initial patch by James Powell.

Python 3.5.0 beta 1

Release date: 2015-05-24

Core and Builtins

bpo-24276 [https://bugs.python.org/issue?@action=redirect&bpo=24276]: Fixed optimization of property descriptor getter.

bpo-24268 [https://bugs.python.org/issue?@action=redirect&bpo=24268]: PEP 489: Multi-phase extension module initialization. Patch by Petr Viktorin.

bpo-23955 [https://bugs.python.org/issue?@action=redirect&bpo=23955]: Add pyvenv.cfg option to suppress registry/environment lookup for generating sys.path on Windows.

bpo-24257 [https://bugs.python.org/issue?@action=redirect&bpo=24257]: Fixed system error in the comparison of faked types.SimpleNamespace.

bpo-22939 [https://bugs.python.org/issue?@action=redirect&bpo=22939]: Fixed integer overflow in iterator object. Patch by Clement Rouault.

bpo-23985 [https://bugs.python.org/issue?@action=redirect&bpo=23985]: Fix a possible buffer overrun when deleting a slice from the front of a bytearray and then appending some other bytes data.

bpo-24102 [https://bugs.python.org/issue?@action=redirect&bpo=24102]: Fixed exception type checking in standard error handlers.

bpo-15027 [https://bugs.python.org/issue?@action=redirect&bpo=15027]: The UTF-32 encoder is now 3x to 7x faster.

bpo-23290 [https://bugs.python.org/issue?@action=redirect&bpo=23290]: Optimize set_merge() for cases where the target is empty. (Contributed by Serhiy Storchaka.)

bpo-2292 [https://bugs.python.org/issue?@action=redirect&bpo=2292]: PEP 448: Additional Unpacking Generalizations.

bpo-24096 [https://bugs.python.org/issue?@action=redirect&bpo=24096]: Make warnings.warn_explicit more robust against mutation of the warnings.filters list.

bpo-23996 [https://bugs.python.org/issue?@action=redirect&bpo=23996]: Avoid a crash when a delegated generator raises an unnormalized StopIteration exception. Patch by Stefan Behnel.

bpo-23910 [https://bugs.python.org/issue?@action=redirect&bpo=23910]: Optimize property() getter calls. Patch by Joe Jevnik.

bpo-23911 [https://bugs.python.org/issue?@action=redirect&bpo=23911]: Move path-based importlib bootstrap code to a separate frozen module.

bpo-24192 [https://bugs.python.org/issue?@action=redirect&bpo=24192]: Fix namespace package imports.

bpo-24022 [https://bugs.python.org/issue?@action=redirect&bpo=24022]: Fix tokenizer crash when processing undecodable source code.

bpo-9951 [https://bugs.python.org/issue?@action=redirect&bpo=9951]: Added a hex() method to bytes, bytearray, and memoryview.

bpo-22906 [https://bugs.python.org/issue?@action=redirect&bpo=22906]: PEP 479: Change StopIteration handling inside generators.

bpo-24017 [https://bugs.python.org/issue?@action=redirect&bpo=24017]: PEP 492: Coroutines with async and await syntax.

Library

bpo-14373 [https://bugs.python.org/issue?@action=redirect&bpo=14373]: Added C implementation of functools.lru_cache(). Based on patches by Matt Joiner and Alexey Kachayev.

bpo-24230 [https://bugs.python.org/issue?@action=redirect&bpo=24230]: The tempfile module now accepts bytes for prefix, suffix and dir parameters and returns bytes in such situations (matching the os module APIs).

bpo-22189 [https://bugs.python.org/issue?@action=redirect&bpo=22189]: collections.UserString now supports __getnewargs__(), __rmod__(), casefold(), format_map(), isprintable(), and maketrans(). Patch by Joe Jevnik.

bpo-24244 [https://bugs.python.org/issue?@action=redirect&bpo=24244]: Prevents termination when an invalid format string is encountered on Windows in strftime.

bpo-23973 [https://bugs.python.org/issue?@action=redirect&bpo=23973]: PEP 484: Add the typing module.

bpo-23086 [https://bugs.python.org/issue?@action=redirect&bpo=23086]: The collections.abc.Sequence() abstract base class added start and stop parameters to the index() mixin. Patch by Devin Jeanpierre.

bpo-20035 [https://bugs.python.org/issue?@action=redirect&bpo=20035]: Replaced the tkinter._fix module used for setting up the Tcl/Tk environment on Windows with a private function in the _tkinter module that makes no permanent changes to the environment.

bpo-24257 [https://bugs.python.org/issue?@action=redirect&bpo=24257]: Fixed segmentation fault in sqlite3.Row constructor with faked cursor type.

bpo-15836 [https://bugs.python.org/issue?@action=redirect&bpo=15836]: assertRaises(), assertRaisesRegex(), assertWarns() and assertWarnsRegex() assertments now check the type of the first argument to prevent possible user error. Based on patch by Daniel Wagner-Hall.

bpo-9858 [https://bugs.python.org/issue?@action=redirect&bpo=9858]: Add missing method stubs to _io.RawIOBase. Patch by Laura Rupprecht.

bpo-22955 [https://bugs.python.org/issue?@action=redirect&bpo=22955]: attrgetter, itemgetter and methodcaller objects in the operator module now support pickling. Added readable and evaluable repr for these objects. Based on patch by Josh Rosenberg.

bpo-22107 [https://bugs.python.org/issue?@action=redirect&bpo=22107]: tempfile.gettempdir() and tempfile.mkdtemp() now try again when a directory with the chosen name already exists on Windows as well as on Unix. tempfile.mkstemp() now fails early if parent directory is not valid (not exists or is a file) on Windows.

bpo-23780 [https://bugs.python.org/issue?@action=redirect&bpo=23780]: Improved error message in os.path.join() with single argument.

bpo-6598 [https://bugs.python.org/issue?@action=redirect&bpo=6598]: Increased time precision and random number range in email.utils.make_msgid() to strengthen the uniqueness of the message ID.

bpo-24091 [https://bugs.python.org/issue?@action=redirect&bpo=24091]: Fixed various crashes in corner cases in C implementation of ElementTree.

bpo-21931 [https://bugs.python.org/issue?@action=redirect&bpo=21931]: msilib.FCICreate() now raises TypeError in the case of a bad argument instead of a ValueError with a bogus FCI error number. Patch by Jeffrey Armstrong.

bpo-13866 [https://bugs.python.org/issue?@action=redirect&bpo=13866]: quote_via argument added to urllib.parse.urlencode.

bpo-20098 [https://bugs.python.org/issue?@action=redirect&bpo=20098]: New mangle_from policy option for email, default True for compat32, but False for all other policies.

bpo-24211 [https://bugs.python.org/issue?@action=redirect&bpo=24211]: The email library now supports RFC 6532: it can generate headers using utf-8 instead of encoded words.

bpo-16314 [https://bugs.python.org/issue?@action=redirect&bpo=16314]: Added support for the LZMA compression in distutils.

bpo-21804 [https://bugs.python.org/issue?@action=redirect&bpo=21804]: poplib now supports RFC 6856 (UTF8).

bpo-18682 [https://bugs.python.org/issue?@action=redirect&bpo=18682]: Optimized pprint functions for builtin scalar types.

bpo-22027 [https://bugs.python.org/issue?@action=redirect&bpo=22027]: smtplib now supports RFC 6531 (SMTPUTF8).

bpo-23488 [https://bugs.python.org/issue?@action=redirect&bpo=23488]: Random generator objects now consume 2x less memory on 64-bit.

bpo-1322 [https://bugs.python.org/issue?@action=redirect&bpo=1322]: platform.dist() and platform.linux_distribution() functions are now deprecated. Initial patch by Vajrasky Kok.

bpo-22486 [https://bugs.python.org/issue?@action=redirect&bpo=22486]: Added the math.gcd() function. The fractions.gcd() function now is deprecated. Based on patch by Mark Dickinson.

bpo-24064 [https://bugs.python.org/issue?@action=redirect&bpo=24064]: Property() docstrings are now writeable. (Patch by Berker Peksag.)

bpo-22681 [https://bugs.python.org/issue?@action=redirect&bpo=22681]: Added support for the koi8_t encoding.

bpo-22682 [https://bugs.python.org/issue?@action=redirect&bpo=22682]: Added support for the kz1048 encoding.

bpo-23796 [https://bugs.python.org/issue?@action=redirect&bpo=23796]: peek and read1 methods of BufferedReader now raise ValueError if they called on a closed object. Patch by John Hergenroeder.

bpo-21795 [https://bugs.python.org/issue?@action=redirect&bpo=21795]: smtpd now supports the 8BITMIME extension whenever the new decode_data constructor argument is set to False.

bpo-24155 [https://bugs.python.org/issue?@action=redirect&bpo=24155]: optimize heapq.heapify() for better cache performance when heapifying large lists.

bpo-21800 [https://bugs.python.org/issue?@action=redirect&bpo=21800]: imaplib now supports RFC 5161 (enable), RFC 6855 (utf8/internationalized email) and automatically encodes non-ASCII usernames and passwords to UTF8.

bpo-20274 [https://bugs.python.org/issue?@action=redirect&bpo=20274]: When calling a _sqlite.Connection, it now complains if passed any keyword arguments. Previously it silently ignored them.

bpo-20274 [https://bugs.python.org/issue?@action=redirect&bpo=20274]: Remove ignored and erroneous «kwargs» parameters from three METH_VARARGS methods on _sqlite.Connection.

bpo-24134 [https://bugs.python.org/issue?@action=redirect&bpo=24134]: assertRaises(), assertRaisesRegex(), assertWarns() and assertWarnsRegex() checks now emits a deprecation warning when callable is None or keyword arguments except msg is passed in the context manager mode.

bpo-24018 [https://bugs.python.org/issue?@action=redirect&bpo=24018]: Add a collections.abc.Generator abstract base class. Contributed by Stefan Behnel.

bpo-23880 [https://bugs.python.org/issue?@action=redirect&bpo=23880]: Tkinter’s getint() and getdouble() now support Tcl_Obj. Tkinter’s getdouble() now supports any numbers (in particular int).

bpo-22619 [https://bugs.python.org/issue?@action=redirect&bpo=22619]: Added negative limit support in the traceback module. Based on patch by Dmitry Kazakov.

bpo-24094 [https://bugs.python.org/issue?@action=redirect&bpo=24094]: Fix possible crash in json.encode with poorly behaved dict subclasses.

bpo-9246 [https://bugs.python.org/issue?@action=redirect&bpo=9246]: On POSIX, os.getcwd() now supports paths longer than 1025 bytes. Patch written by William Orr.

bpo-17445 [https://bugs.python.org/issue?@action=redirect&bpo=17445]: add difflib.diff_bytes() to support comparison of byte strings (fixes a regression from Python 2).

bpo-23917 [https://bugs.python.org/issue?@action=redirect&bpo=23917]: Fall back to sequential compilation when ProcessPoolExecutor doesn’t exist. Patch by Claudiu Popa.

bpo-23008 [https://bugs.python.org/issue?@action=redirect&bpo=23008]: Fixed resolving attributes with boolean value is False in pydoc.

Fix asyncio issue 235: LifoQueue and PriorityQueue’s put didn’t increment unfinished tasks (this bug was introduced when JoinableQueue was merged with Queue).

bpo-23908 [https://bugs.python.org/issue?@action=redirect&bpo=23908]: os functions now reject paths with embedded null character on Windows instead of silently truncating them.

bpo-23728 [https://bugs.python.org/issue?@action=redirect&bpo=23728]: binascii.crc_hqx() could return an integer outside of the range 0-0xffff for empty data.

bpo-23887 [https://bugs.python.org/issue?@action=redirect&bpo=23887]: urllib.error.HTTPError now has a proper repr() representation. Patch by Berker Peksag.

asyncio: New event loop APIs: set_task_factory() and get_task_factory().

asyncio: async() function is deprecated in favour of ensure_future().

bpo-24178 [https://bugs.python.org/issue?@action=redirect&bpo=24178]: asyncio.Lock, Condition, Semaphore, and BoundedSemaphore support new “async with” syntax. Contributed by Yury Selivanov.

bpo-24179 [https://bugs.python.org/issue?@action=redirect&bpo=24179]: Support “async for” for asyncio.StreamReader. Contributed by Yury Selivanov.

bpo-24184 [https://bugs.python.org/issue?@action=redirect&bpo=24184]: Add AsyncIterator and AsyncIterable ABCs to collections.abc. Contributed by Yury Selivanov.

bpo-22547 [https://bugs.python.org/issue?@action=redirect&bpo=22547]: Implement informative __repr__ for inspect.BoundArguments. Contributed by Yury Selivanov.

bpo-24190 [https://bugs.python.org/issue?@action=redirect&bpo=24190]: Implement inspect.BoundArgument.apply_defaults() method. Contributed by Yury Selivanov.

bpo-20691 [https://bugs.python.org/issue?@action=redirect&bpo=20691]: Add “follow_wrapped” argument to inspect.Signature.from_callable() and inspect.signature(). Contributed by Yury Selivanov.

bpo-24248 [https://bugs.python.org/issue?@action=redirect&bpo=24248]: Deprecate inspect.Signature.from_function() and inspect.Signature.from_builtin().

bpo-23898 [https://bugs.python.org/issue?@action=redirect&bpo=23898]: Fix inspect.classify_class_attrs() to support attributes with overloaded __eq__ and __bool__. Patch by Mike Bayer.

bpo-24298 [https://bugs.python.org/issue?@action=redirect&bpo=24298]: Fix inspect.signature() to correctly unwrap wrappers around bound methods.

IDLE

bpo-23184 [https://bugs.python.org/issue?@action=redirect&bpo=23184]: remove unused names and imports in idlelib. Initial patch by Al Sweigart.

Tests

bpo-21520 [https://bugs.python.org/issue?@action=redirect&bpo=21520]: test_zipfile no longer fails if the word “bad” appears anywhere in the name of the current directory.

bpo-9517 [https://bugs.python.org/issue?@action=redirect&bpo=9517]: Move script_helper into the support package. Patch by Christie Wilson.

Documentation

bpo-22155 [https://bugs.python.org/issue?@action=redirect&bpo=22155]: Add File Handlers subsection with createfilehandler to tkinter doc. Remove obsolete example from FAQ. Patch by Martin Panter.

bpo-24029 [https://bugs.python.org/issue?@action=redirect&bpo=24029]: Document the name binding behavior for submodule imports.

bpo-24077 [https://bugs.python.org/issue?@action=redirect&bpo=24077]: Fix typo in man page for -I command option: -s, not -S

Tools/Demos

bpo-24000 [https://bugs.python.org/issue?@action=redirect&bpo=24000]: Improved Argument Clinic’s mapping of converters to legacy «format units». Updated the documentation to match.

bpo-24001 [https://bugs.python.org/issue?@action=redirect&bpo=24001]: Argument Clinic converters now use accept={type} instead of types={“type”} to specify the types the converter accepts.

bpo-23330 [https://bugs.python.org/issue?@action=redirect&bpo=23330]: h2py now supports arbitrary filenames in #include.

bpo-24031 [https://bugs.python.org/issue?@action=redirect&bpo=24031]: make patchcheck now supports git checkouts, too.

Python 3.5.0 alpha 4

Release date: 2015-04-19

Core and Builtins

bpo-22980 [https://bugs.python.org/issue?@action=redirect&bpo=22980]: Under Linux, GNU/KFreeBSD and the Hurd, C extensions now include the architecture triplet in the extension name, to make it easy to test builds for different ABIs in the same working tree. Under OS X, the extension name now includes PEP 3149 [https://www.python.org/dev/peps/pep-3149]-style information.

bpo-22631 [https://bugs.python.org/issue?@action=redirect&bpo=22631]: Added Linux-specific socket constant CAN_RAW_FD_FRAMES. Patch courtesy of Joe Jevnik.

bpo-23731 [https://bugs.python.org/issue?@action=redirect&bpo=23731]: Implement PEP 488 [https://www.python.org/dev/peps/pep-0488]: removal of .pyo files.

bpo-23726 [https://bugs.python.org/issue?@action=redirect&bpo=23726]: Don’t enable GC for user subclasses of non-GC types that don’t add any new fields. Patch by Eugene Toder.

bpo-23309 [https://bugs.python.org/issue?@action=redirect&bpo=23309]: Avoid a deadlock at shutdown if a daemon thread is aborted while it is holding a lock to a buffered I/O object, and the main thread tries to use the same I/O object (typically stdout or stderr). A fatal error is emitted instead.

bpo-22977 [https://bugs.python.org/issue?@action=redirect&bpo=22977]: Fixed formatting Windows error messages on Wine. Patch by Martin Panter.

bpo-23466 [https://bugs.python.org/issue?@action=redirect&bpo=23466]: %c, %o, %x, and %X in bytes formatting now raise TypeError on non-integer input.

bpo-24044 [https://bugs.python.org/issue?@action=redirect&bpo=24044]: Fix possible null pointer dereference in list.sort in out of memory conditions.

bpo-21354 [https://bugs.python.org/issue?@action=redirect&bpo=21354]: PyCFunction_New function is exposed by python DLL again.

Library

bpo-23840 [https://bugs.python.org/issue?@action=redirect&bpo=23840]: tokenize.open() now closes the temporary binary file on error to fix a resource warning.

bpo-16914 [https://bugs.python.org/issue?@action=redirect&bpo=16914]: new debuglevel 2 in smtplib adds timestamps to debug output.

bpo-7159 [https://bugs.python.org/issue?@action=redirect&bpo=7159]: urllib.request now supports sending auth credentials automatically after the first 401. This enhancement is a superset of the enhancement from bpo-19494 [https://bugs.python.org/issue?@action=redirect&bpo=19494] and supersedes that change.

bpo-23703 [https://bugs.python.org/issue?@action=redirect&bpo=23703]: Fix a regression in urljoin() introduced in 901e4e52b20a. Patch by Demian Brecht.

bpo-4254 [https://bugs.python.org/issue?@action=redirect&bpo=4254]: Adds _curses.update_lines_cols(). Patch by Arnon Yaari

bpo-19933 [https://bugs.python.org/issue?@action=redirect&bpo=19933]: Provide default argument for ndigits in round. Patch by Vajrasky Kok.

bpo-23193 [https://bugs.python.org/issue?@action=redirect&bpo=23193]: Add a numeric_owner parameter to tarfile.TarFile.extract and tarfile.TarFile.extractall. Patch by Michael Vogt and Eric Smith.

bpo-23342 [https://bugs.python.org/issue?@action=redirect&bpo=23342]: Add a subprocess.run() function than returns a CalledProcess instance for a more consistent API than the existing call* functions.

bpo-21217 [https://bugs.python.org/issue?@action=redirect&bpo=21217]: inspect.getsourcelines() now tries to compute the start and end lines from the code object, fixing an issue when a lambda function is used as decorator argument. Patch by Thomas Ballinger and Allison Kaptur.

bpo-24521 [https://bugs.python.org/issue?@action=redirect&bpo=24521]: Fix possible integer overflows in the pickle module.

bpo-22931 [https://bugs.python.org/issue?@action=redirect&bpo=22931]: Allow “[” and “]” in cookie values.

The keywords attribute of functools.partial is now always a dictionary.

bpo-23811 [https://bugs.python.org/issue?@action=redirect&bpo=23811]: Add missing newline to the PyCompileError error message. Patch by Alex Shkop.

bpo-21116 [https://bugs.python.org/issue?@action=redirect&bpo=21116]: Avoid blowing memory when allocating a multiprocessing shared array that’s larger than 50% of the available RAM. Patch by Médéric Boquien.

bpo-22982 [https://bugs.python.org/issue?@action=redirect&bpo=22982]: Improve BOM handling when seeking to multiple positions of a writable text file.

bpo-23464 [https://bugs.python.org/issue?@action=redirect&bpo=23464]: Removed deprecated asyncio JoinableQueue.

bpo-23529 [https://bugs.python.org/issue?@action=redirect&bpo=23529]: Limit the size of decompressed data when reading from GzipFile, BZ2File or LZMAFile. This defeats denial of service attacks using compressed bombs (i.e. compressed payloads which decompress to a huge size). Patch by Martin Panter and Nikolaus Rath.

bpo-21859 [https://bugs.python.org/issue?@action=redirect&bpo=21859]: Added Python implementation of io.FileIO.

bpo-23865 [https://bugs.python.org/issue?@action=redirect&bpo=23865]: close() methods in multiple modules now are idempotent and more robust at shutdown. If they need to release multiple resources, all are released even if errors occur.

bpo-23400 [https://bugs.python.org/issue?@action=redirect&bpo=23400]: Raise same exception on both Python 2 and 3 if sem_open is not available. Patch by Davin Potts.

bpo-10838 [https://bugs.python.org/issue?@action=redirect&bpo=10838]: The subprocess now module includes SubprocessError and TimeoutError in its list of exported names for the users wild enough to use from subprocess import *.

bpo-23411 [https://bugs.python.org/issue?@action=redirect&bpo=23411]: Added DefragResult, ParseResult, SplitResult, DefragResultBytes, ParseResultBytes, and SplitResultBytes to urllib.parse.__all__. Patch by Martin Panter.

bpo-23881 [https://bugs.python.org/issue?@action=redirect&bpo=23881]: urllib.request.ftpwrapper constructor now closes the socket if the FTP connection failed to fix a ResourceWarning.

bpo-23853 [https://bugs.python.org/issue?@action=redirect&bpo=23853]: socket.socket.sendall() does no more reset the socket timeout each time data is sent successfully. The socket timeout is now the maximum total duration to send all data.

bpo-22721 [https://bugs.python.org/issue?@action=redirect&bpo=22721]: An order of multiline pprint output of set or dict containing orderable and non-orderable elements no longer depends on iteration order of set or dict.

bpo-15133 [https://bugs.python.org/issue?@action=redirect&bpo=15133]: _tkinter.tkapp.getboolean() now supports Tcl_Obj and always returns bool. tkinter.BooleanVar now validates input values (accepted bool, int, str, and Tcl_Obj). tkinter.BooleanVar.get() now always returns bool.

bpo-10590 [https://bugs.python.org/issue?@action=redirect&bpo=10590]: xml.sax.parseString() now supports string argument.

bpo-23338 [https://bugs.python.org/issue?@action=redirect&bpo=23338]: Fixed formatting ctypes error messages on Cygwin. Patch by Makoto Kato.

bpo-15582 [https://bugs.python.org/issue?@action=redirect&bpo=15582]: inspect.getdoc() now follows inheritance chains.

bpo-2175 [https://bugs.python.org/issue?@action=redirect&bpo=2175]: SAX parsers now support a character stream of InputSource object.

bpo-16840 [https://bugs.python.org/issue?@action=redirect&bpo=16840]: Tkinter now supports 64-bit integers added in Tcl 8.4 and arbitrary precision integers added in Tcl 8.5.

bpo-23834 [https://bugs.python.org/issue?@action=redirect&bpo=23834]: Fix socket.sendto(), use the C Py_ssize_t type to store the result of sendto() instead of the C int type.

bpo-23618 [https://bugs.python.org/issue?@action=redirect&bpo=23618]: socket.socket.connect() now waits until the connection completes instead of raising InterruptedError if the connection is interrupted by signals, signal handlers don’t raise an exception and the socket is blocking or has a timeout. socket.socket.connect() still raise InterruptedError for non-blocking sockets.

bpo-21526 [https://bugs.python.org/issue?@action=redirect&bpo=21526]: Tkinter now supports new boolean type in Tcl 8.5.

bpo-23836 [https://bugs.python.org/issue?@action=redirect&bpo=23836]: Fix the faulthandler module to handle reentrant calls to its signal handlers.

bpo-23838 [https://bugs.python.org/issue?@action=redirect&bpo=23838]: linecache now clears the cache and returns an empty result on MemoryError.

bpo-10395 [https://bugs.python.org/issue?@action=redirect&bpo=10395]: Added os.path.commonpath(). Implemented in posixpath and ntpath. Based on patch by Rafik Draoui.

bpo-23611 [https://bugs.python.org/issue?@action=redirect&bpo=23611]: Serializing more «lookupable» objects (such as unbound methods or nested classes) now are supported with pickle protocols < 4.

bpo-13583 [https://bugs.python.org/issue?@action=redirect&bpo=13583]: sqlite3.Row now supports slice indexing.

bpo-18473 [https://bugs.python.org/issue?@action=redirect&bpo=18473]: Fixed 2to3 and 3to2 compatible pickle mappings. Fixed ambiguous reverse mappings. Added many new mappings. Import mapping is no longer applied to modules already mapped with full name mapping.

bpo-23485 [https://bugs.python.org/issue?@action=redirect&bpo=23485]: select.select() is now retried automatically with the recomputed timeout when interrupted by a signal, except if the signal handler raises an exception. This change is part of the PEP 475 [https://www.python.org/dev/peps/pep-0475].

bpo-23752 [https://bugs.python.org/issue?@action=redirect&bpo=23752]: When built from an existing file descriptor, io.FileIO() now only calls fstat() once. Before fstat() was called twice, which was not necessary.

bpo-23704 [https://bugs.python.org/issue?@action=redirect&bpo=23704]: collections.deque() objects now support __add__, __mul__, and __imul__().

bpo-23171 [https://bugs.python.org/issue?@action=redirect&bpo=23171]: csv.Writer.writerow() now supports arbitrary iterables.

bpo-23745 [https://bugs.python.org/issue?@action=redirect&bpo=23745]: The new email header parser now handles duplicate MIME parameter names without error, similar to how get_param behaves.

bpo-22117 [https://bugs.python.org/issue?@action=redirect&bpo=22117]: Fix os.utime(), it now rounds the timestamp towards minus infinity (-inf) instead of rounding towards zero.

bpo-23310 [https://bugs.python.org/issue?@action=redirect&bpo=23310]: Fix MagicMock’s initializer to work with __methods__, just like configure_mock(). Patch by Kasia Jachim.

Build

bpo-23817 [https://bugs.python.org/issue?@action=redirect&bpo=23817]: FreeBSD now uses «1.0» in the SOVERSION as other operating systems, instead of just «1».

bpo-23501 [https://bugs.python.org/issue?@action=redirect&bpo=23501]: Argument Clinic now generates code into separate files by default.

Tests

bpo-23799 [https://bugs.python.org/issue?@action=redirect&bpo=23799]: Added test.support.start_threads() for running and cleaning up multiple threads.

bpo-22390 [https://bugs.python.org/issue?@action=redirect&bpo=22390]: test.regrtest now emits a warning if temporary files or directories are left after running a test.

Tools/Demos

bpo-18128 [https://bugs.python.org/issue?@action=redirect&bpo=18128]: pygettext now uses standard +NNNN format in the POT-Creation-Date header.

bpo-23935 [https://bugs.python.org/issue?@action=redirect&bpo=23935]: Argument Clinic’s understanding of format units accepting bytes, bytearrays, and buffers is now consistent with both the documentation and the implementation.

bpo-23944 [https://bugs.python.org/issue?@action=redirect&bpo=23944]: Argument Clinic now wraps long impl prototypes at column 78.

bpo-20586 [https://bugs.python.org/issue?@action=redirect&bpo=20586]: Argument Clinic now ensures that functions without docstrings have signatures.

bpo-23492 [https://bugs.python.org/issue?@action=redirect&bpo=23492]: Argument Clinic now generates argument parsing code with PyArg_Parse instead of PyArg_ParseTuple if possible.

bpo-23500 [https://bugs.python.org/issue?@action=redirect&bpo=23500]: Argument Clinic is now smarter about generating the «#ifndef» (empty) definition of the methoddef macro: it’s only generated once, even if Argument Clinic processes the same symbol multiple times, and it’s emitted at the end of all processing rather than immediately after the first use.

C API

bpo-23998 [https://bugs.python.org/issue?@action=redirect&bpo=23998]: PyImport_ReInitLock() now checks for lock allocation error

Python 3.5.0 alpha 3

Release date: 2015-03-28

Core and Builtins

bpo-23573 [https://bugs.python.org/issue?@action=redirect&bpo=23573]: Increased performance of string search operations (str.find, str.index, str.count, the in operator, str.split, str.partition) with arguments of different kinds (UCS1, UCS2, UCS4).

bpo-23753 [https://bugs.python.org/issue?@action=redirect&bpo=23753]: Python doesn’t support anymore platforms without stat() or fstat(), these functions are always required.

bpo-23681 [https://bugs.python.org/issue?@action=redirect&bpo=23681]: The -b option now affects comparisons of bytes with int.

bpo-23632 [https://bugs.python.org/issue?@action=redirect&bpo=23632]: Memoryviews now allow tuple indexing (including for multi-dimensional memoryviews).

bpo-23192 [https://bugs.python.org/issue?@action=redirect&bpo=23192]: Fixed generator lambdas. Patch by Bruno Cauet.

bpo-23629 [https://bugs.python.org/issue?@action=redirect&bpo=23629]: Fix the default __sizeof__ implementation for variable-sized objects.

Library

bpo-14260 [https://bugs.python.org/issue?@action=redirect&bpo=14260]: The groupindex attribute of regular expression pattern object now is non-modifiable mapping.

bpo-23792 [https://bugs.python.org/issue?@action=redirect&bpo=23792]: Ignore KeyboardInterrupt when the pydoc pager is active. This mimics the behavior of the standard unix pagers, and prevents pipepager from shutting down while the pager itself is still running.

bpo-23775 [https://bugs.python.org/issue?@action=redirect&bpo=23775]: pprint() of OrderedDict now outputs the same representation as repr().

bpo-23765 [https://bugs.python.org/issue?@action=redirect&bpo=23765]: Removed IsBadStringPtr calls in ctypes

bpo-22364 [https://bugs.python.org/issue?@action=redirect&bpo=22364]: Improved some re error messages using regex for hints.

bpo-23742 [https://bugs.python.org/issue?@action=redirect&bpo=23742]: ntpath.expandvars() no longer loses unbalanced single quotes.

bpo-21717 [https://bugs.python.org/issue?@action=redirect&bpo=21717]: The zipfile.ZipFile.open function now supports “x” (exclusive creation) mode.

bpo-21802 [https://bugs.python.org/issue?@action=redirect&bpo=21802]: The reader in BufferedRWPair now is closed even when closing writer failed in BufferedRWPair.close().

bpo-23622 [https://bugs.python.org/issue?@action=redirect&bpo=23622]: Unknown escapes in regular expressions that consist of '\' and ASCII letter now raise a deprecation warning and will be forbidden in Python 3.6.

bpo-23671 [https://bugs.python.org/issue?@action=redirect&bpo=23671]: string.Template now allows specifying the «self» parameter as a keyword argument. string.Formatter now allows specifying the «self» and the «format_string» parameters as keyword arguments.

bpo-23502 [https://bugs.python.org/issue?@action=redirect&bpo=23502]: The pprint module now supports mapping proxies.

bpo-17530 [https://bugs.python.org/issue?@action=redirect&bpo=17530]: pprint now wraps long bytes objects and bytearrays.

bpo-22687 [https://bugs.python.org/issue?@action=redirect&bpo=22687]: Fixed some corner cases in breaking words in tetxtwrap. Got rid of quadratic complexity in breaking long words.

bpo-4727 [https://bugs.python.org/issue?@action=redirect&bpo=4727]: The copy module now uses pickle protocol 4 (PEP 3154) and supports copying of instances of classes whose __new__ method takes keyword-only arguments.

bpo-23491 [https://bugs.python.org/issue?@action=redirect&bpo=23491]: Added a zipapp module to support creating executable zip file archives of Python code. Registered «.pyz» and «.pyzw» extensions on Windows for these archives (PEP 441).

bpo-23657 [https://bugs.python.org/issue?@action=redirect&bpo=23657]: Avoid explicit checks for str in zipapp, adding support for pathlib.Path objects as arguments.

bpo-23688 [https://bugs.python.org/issue?@action=redirect&bpo=23688]: Added support of arbitrary bytes-like objects and avoided unnecessary copying of memoryview in gzip.GzipFile.write(). Original patch by Wolfgang Maier.

bpo-23252 [https://bugs.python.org/issue?@action=redirect&bpo=23252]: Added support for writing ZIP files to unseekable streams.

bpo-23647 [https://bugs.python.org/issue?@action=redirect&bpo=23647]: Increase imaplib’s MAXLINE to accommodate modern mailbox sizes.

bpo-23539 [https://bugs.python.org/issue?@action=redirect&bpo=23539]: If body is None, http.client.HTTPConnection.request now sets Content-Length to 0 for PUT, POST, and PATCH headers to avoid 411 errors from some web servers.

bpo-22351 [https://bugs.python.org/issue?@action=redirect&bpo=22351]: The nntplib.NNTP constructor no longer leaves the connection and socket open until the garbage collector cleans them up. Patch by Martin Panter.

bpo-23704 [https://bugs.python.org/issue?@action=redirect&bpo=23704]: collections.deque() objects now support methods for index(), insert(), and copy(). This allows deques to be registered as a MutableSequence and it improves their substitutability for lists.

bpo-23715 [https://bugs.python.org/issue?@action=redirect&bpo=23715]: signal.sigwaitinfo() and signal.sigtimedwait() are now retried when interrupted by a signal not in the sigset parameter, if the signal handler does not raise an exception. signal.sigtimedwait() recomputes the timeout with a monotonic clock when it is retried.

bpo-23001 [https://bugs.python.org/issue?@action=redirect&bpo=23001]: Few functions in modules mmap, ossaudiodev, socket, ssl, and codecs, that accepted only read-only bytes-like object now accept writable bytes-like object too.

bpo-23646 [https://bugs.python.org/issue?@action=redirect&bpo=23646]: If time.sleep() is interrupted by a signal, the sleep is now retried with the recomputed delay, except if the signal handler raises an exception (PEP 475).

bpo-23136 [https://bugs.python.org/issue?@action=redirect&bpo=23136]: _strptime now uniformly handles all days in week 0, including Dec 30 of previous year. Based on patch by Jim Carroll.

bpo-23700 [https://bugs.python.org/issue?@action=redirect&bpo=23700]: Iterator of NamedTemporaryFile now keeps a reference to NamedTemporaryFile instance. Patch by Bohuslav Kabrda.

bpo-22903 [https://bugs.python.org/issue?@action=redirect&bpo=22903]: The fake test case created by unittest.loader when it fails importing a test module is now picklable.

bpo-22181 [https://bugs.python.org/issue?@action=redirect&bpo=22181]: On Linux, os.urandom() now uses the new getrandom() syscall if available, syscall introduced in the Linux kernel 3.17. It is more reliable and more secure, because it avoids the need of a file descriptor and waits until the kernel has enough entropy.

bpo-2211 [https://bugs.python.org/issue?@action=redirect&bpo=2211]: Updated the implementation of the http.cookies.Morsel class. Setting attributes key, value and coded_value directly now is deprecated. update() and setdefault() now transform and check keys. Comparing for equality now takes into account attributes key, value and coded_value. copy() now returns a Morsel, not a dict. repr() now contains all attributes. Optimized checking keys and quoting values. Added new tests. Original patch by Demian Brecht.

bpo-18983 [https://bugs.python.org/issue?@action=redirect&bpo=18983]: Allow selection of output units in timeit. Patch by Julian Gindi.

bpo-23631 [https://bugs.python.org/issue?@action=redirect&bpo=23631]: Fix traceback.format_list when a traceback has been mutated.

bpo-23568 [https://bugs.python.org/issue?@action=redirect&bpo=23568]: Add rdivmod support to MagicMock() objects. Patch by Håkan Lövdahl.

bpo-2052 [https://bugs.python.org/issue?@action=redirect&bpo=2052]: Add charset parameter to HtmlDiff.make_file().

bpo-23668 [https://bugs.python.org/issue?@action=redirect&bpo=23668]: Support os.truncate and os.ftruncate on Windows.

bpo-23138 [https://bugs.python.org/issue?@action=redirect&bpo=23138]: Fixed parsing cookies with absent keys or values in cookiejar. Patch by Demian Brecht.

bpo-23051 [https://bugs.python.org/issue?@action=redirect&bpo=23051]: multiprocessing.Pool methods imap() and imap_unordered() now handle exceptions raised by an iterator. Patch by Alon Diamant and Davin Potts.

bpo-23581 [https://bugs.python.org/issue?@action=redirect&bpo=23581]: Add matmul support to MagicMock. Patch by Håkan Lövdahl.

bpo-23566 [https://bugs.python.org/issue?@action=redirect&bpo=23566]: enable(), register(), dump_traceback() and dump_traceback_later() functions of faulthandler now accept file descriptors. Patch by Wei Wu.

bpo-22928 [https://bugs.python.org/issue?@action=redirect&bpo=22928]: Disabled HTTP header injections in http.client. Original patch by Demian Brecht.

bpo-23615 [https://bugs.python.org/issue?@action=redirect&bpo=23615]: Modules bz2, tarfile and tokenize now can be reloaded with imp.reload(). Patch by Thomas Kluyver.

bpo-23605 [https://bugs.python.org/issue?@action=redirect&bpo=23605]: os.walk() now calls os.scandir() instead of os.listdir(). The usage of os.scandir() reduces the number of calls to os.stat(). Initial patch written by Ben Hoyt.

Build

bpo-23585 [https://bugs.python.org/issue?@action=redirect&bpo=23585]: make patchcheck will ensure the interpreter is built.

Tests

bpo-23583 [https://bugs.python.org/issue?@action=redirect&bpo=23583]: Added tests for standard IO streams in IDLE.

bpo-22289 [https://bugs.python.org/issue?@action=redirect&bpo=22289]: Prevent test_urllib2net failures due to ftp connection timeout.

Tools/Demos

bpo-22826 [https://bugs.python.org/issue?@action=redirect&bpo=22826]: The result of open() in Tools/freeze/bkfile.py is now better compatible with regular files (in particular it now supports the context management protocol).

Python 3.5.0 alpha 2

Release date: 2015-03-09

Core and Builtins

bpo-23571 [https://bugs.python.org/issue?@action=redirect&bpo=23571]: PyObject_Call() and PyCFunction_Call() now raise a SystemError if a function returns a result and raises an exception. The SystemError is chained to the previous exception.

Library

bpo-22524 [https://bugs.python.org/issue?@action=redirect&bpo=22524]: New os.scandir() function, part of the PEP 471 [https://www.python.org/dev/peps/pep-0471]: «os.scandir() function – a better and faster directory iterator». Patch written by Ben Hoyt.

bpo-23103 [https://bugs.python.org/issue?@action=redirect&bpo=23103]: Reduced the memory consumption of IPv4Address and IPv6Address.

bpo-21793 [https://bugs.python.org/issue?@action=redirect&bpo=21793]: BaseHTTPRequestHandler again logs response code as numeric, not as stringified enum. Patch by Demian Brecht.

bpo-23476 [https://bugs.python.org/issue?@action=redirect&bpo=23476]: In the ssl module, enable OpenSSL’s X509_V_FLAG_TRUSTED_FIRST flag on certificate stores when it is available.

bpo-23576 [https://bugs.python.org/issue?@action=redirect&bpo=23576]: Avoid stalling in SSL reads when EOF has been reached in the SSL layer but the underlying connection hasn’t been closed.

bpo-23504 [https://bugs.python.org/issue?@action=redirect&bpo=23504]: Added an __all__ to the types module.

bpo-23563 [https://bugs.python.org/issue?@action=redirect&bpo=23563]: Optimized utility functions in urllib.parse.

bpo-7830 [https://bugs.python.org/issue?@action=redirect&bpo=7830]: Flatten nested functools.partial.

bpo-20204 [https://bugs.python.org/issue?@action=redirect&bpo=20204]: Added the __module__ attribute to _tkinter classes.

bpo-19980 [https://bugs.python.org/issue?@action=redirect&bpo=19980]: Improved help() for non-recognized strings. help(“”) now shows the help on str. help(“help”) now shows the help on help(). Original patch by Mark Lawrence.

bpo-23521 [https://bugs.python.org/issue?@action=redirect&bpo=23521]: Corrected pure python implementation of timedelta division. Eliminated OverflowError from timedelta * float for some floats; Corrected rounding in timedelta true division.

bpo-21619 [https://bugs.python.org/issue?@action=redirect&bpo=21619]: Popen objects no longer leave a zombie after exit in the with statement if the pipe was broken. Patch by Martin Panter.

bpo-22936 [https://bugs.python.org/issue?@action=redirect&bpo=22936]: Make it possible to show local variables in tracebacks for both the traceback module and unittest.

bpo-15955 [https://bugs.python.org/issue?@action=redirect&bpo=15955]: Add an option to limit the output size in bz2.decompress(). Patch by Nikolaus Rath.

bpo-6639 [https://bugs.python.org/issue?@action=redirect&bpo=6639]: Module-level turtle functions no longer raise TclError after closing the window.

bpo-814253 [https://bugs.python.org/issue?@action=redirect&bpo=814253]: Group references and conditional group references now work in lookbehind assertions in regular expressions. (See also: bpo-9179 [https://bugs.python.org/issue?@action=redirect&bpo=9179])

bpo-23215 [https://bugs.python.org/issue?@action=redirect&bpo=23215]: Multibyte codecs with custom error handlers that ignores errors consumed too much memory and raised SystemError or MemoryError. Original patch by Aleksi Torhamo.

bpo-5700 [https://bugs.python.org/issue?@action=redirect&bpo=5700]: io.FileIO() called flush() after closing the file. flush() was not called in close() if closefd=False.

bpo-23374 [https://bugs.python.org/issue?@action=redirect&bpo=23374]: Fixed pydoc failure with non-ASCII files when stdout encoding differs from file system encoding (e.g. on Mac OS).

bpo-23481 [https://bugs.python.org/issue?@action=redirect&bpo=23481]: Remove RC4 from the SSL module’s default cipher list.

bpo-21548 [https://bugs.python.org/issue?@action=redirect&bpo=21548]: Fix pydoc.synopsis() and pydoc.apropos() on modules with empty docstrings.

bpo-22885 [https://bugs.python.org/issue?@action=redirect&bpo=22885]: Fixed arbitrary code execution vulnerability in the dbm.dumb module. Original patch by Claudiu Popa.

bpo-23239 [https://bugs.python.org/issue?@action=redirect&bpo=23239]: ssl.match_hostname() now supports matching of IP addresses.

bpo-23146 [https://bugs.python.org/issue?@action=redirect&bpo=23146]: Fix mishandling of absolute Windows paths with forward slashes in pathlib.

bpo-23096 [https://bugs.python.org/issue?@action=redirect&bpo=23096]: Pickle representation of floats with protocol 0 now is the same for both Python and C implementations.

bpo-19105 [https://bugs.python.org/issue?@action=redirect&bpo=19105]: pprint now more efficiently uses free space at the right.

bpo-14910 [https://bugs.python.org/issue?@action=redirect&bpo=14910]: Add allow_abbrev parameter to argparse.ArgumentParser. Patch by Jonathan Paugh, Steven Bethard, paul j3 and Daniel Eriksson.

bpo-21717 [https://bugs.python.org/issue?@action=redirect&bpo=21717]: tarfile.open() now supports “x” (exclusive creation) mode.

bpo-23344 [https://bugs.python.org/issue?@action=redirect&bpo=23344]: marshal.dumps() is now 20-25% faster on average.

bpo-20416 [https://bugs.python.org/issue?@action=redirect&bpo=20416]: marshal.dumps() with protocols 3 and 4 is now 40-50% faster on average.

bpo-23421 [https://bugs.python.org/issue?@action=redirect&bpo=23421]: Fixed compression in tarfile CLI. Patch by wdv4758h.

bpo-23367 [https://bugs.python.org/issue?@action=redirect&bpo=23367]: Fix possible overflows in the unicodedata module.

bpo-23361 [https://bugs.python.org/issue?@action=redirect&bpo=23361]: Fix possible overflow in Windows subprocess creation code.

logging.handlers.QueueListener now takes a respect_handler_level keyword argument which, if set to True, will pass messages to handlers taking handler levels into account.

bpo-19705 [https://bugs.python.org/issue?@action=redirect&bpo=19705]: turtledemo now has a visual sorting algorithm demo. Original patch from Jason Yeo.

bpo-23801 [https://bugs.python.org/issue?@action=redirect&bpo=23801]: Fix issue where cgi.FieldStorage did not always ignore the entire preamble to a multipart body.

Build

bpo-23445 [https://bugs.python.org/issue?@action=redirect&bpo=23445]: pydebug builds now use «gcc -Og» where possible, to make the resulting executable faster.

bpo-23686 [https://bugs.python.org/issue?@action=redirect&bpo=23686]: Update OS X 10.5 installer build to use OpenSSL 1.0.2a.

C API

bpo-20204 [https://bugs.python.org/issue?@action=redirect&bpo=20204]: Deprecation warning is now raised for builtin types without the __module__ attribute.

Windows

bpo-23465 [https://bugs.python.org/issue?@action=redirect&bpo=23465]: Implement PEP 486 [https://www.python.org/dev/peps/pep-0486] - Make the Python Launcher aware of virtual environments. Patch by Paul Moore.

bpo-23437 [https://bugs.python.org/issue?@action=redirect&bpo=23437]: Make user scripts directory versioned on Windows. Patch by Paul Moore.

Python 3.5.0 alpha 1

Release date: 2015-02-08

Core and Builtins

bpo-23285 [https://bugs.python.org/issue?@action=redirect&bpo=23285]: PEP 475 - EINTR handling.

bpo-22735 [https://bugs.python.org/issue?@action=redirect&bpo=22735]: Fix many edge cases (including crashes) involving custom mro() implementations.

bpo-22896 [https://bugs.python.org/issue?@action=redirect&bpo=22896]: Avoid using PyObject_AsCharBuffer(), PyObject_AsReadBuffer() and PyObject_AsWriteBuffer().

bpo-21295 [https://bugs.python.org/issue?@action=redirect&bpo=21295]: Revert some changes (bpo-16795 [https://bugs.python.org/issue?@action=redirect&bpo=16795]) to AST line numbers and column offsets that constituted a regression.

bpo-22986 [https://bugs.python.org/issue?@action=redirect&bpo=22986]: Allow changing an object’s __class__ between a dynamic type and static type in some cases.

bpo-15859 [https://bugs.python.org/issue?@action=redirect&bpo=15859]: PyUnicode_EncodeFSDefault(), PyUnicode_EncodeMBCS() and PyUnicode_EncodeCodePage() now raise an exception if the object is not a Unicode object. For PyUnicode_EncodeFSDefault(), it was already the case on platforms other than Windows. Patch written by Campbell Barton.

bpo-21408 [https://bugs.python.org/issue?@action=redirect&bpo=21408]: The default __ne__() now returns NotImplemented if __eq__() returned NotImplemented. Original patch by Martin Panter.

bpo-23321 [https://bugs.python.org/issue?@action=redirect&bpo=23321]: Fixed a crash in str.decode() when error handler returned replacement string longer than malformed input data.

bpo-22286 [https://bugs.python.org/issue?@action=redirect&bpo=22286]: The «backslashreplace» error handlers now works with decoding and translating.

bpo-23253 [https://bugs.python.org/issue?@action=redirect&bpo=23253]: Delay-load ShellExecute[AW] in os.startfile for reduced startup overhead on Windows.

bpo-22038 [https://bugs.python.org/issue?@action=redirect&bpo=22038]: pyatomic.h now uses stdatomic.h or GCC built-in functions for atomic memory access if available. Patch written by Vitor de Lima and Gustavo Temple.

bpo-20284 [https://bugs.python.org/issue?@action=redirect&bpo=20284]: %-interpolation (aka printf) formatting added for bytes and bytearray.

bpo-23048 [https://bugs.python.org/issue?@action=redirect&bpo=23048]: Fix jumping out of an infinite while loop in the pdb.

bpo-20335 [https://bugs.python.org/issue?@action=redirect&bpo=20335]: bytes constructor now raises TypeError when encoding or errors is specified with non-string argument. Based on patch by Renaud Blanch.

bpo-22834 [https://bugs.python.org/issue?@action=redirect&bpo=22834]: If the current working directory ends up being set to a non-existent directory then import will no longer raise FileNotFoundError.

bpo-22869 [https://bugs.python.org/issue?@action=redirect&bpo=22869]: Move the interpreter startup & shutdown code to a new dedicated pylifecycle.c module

bpo-22847 [https://bugs.python.org/issue?@action=redirect&bpo=22847]: Improve method cache efficiency.

bpo-22335 [https://bugs.python.org/issue?@action=redirect&bpo=22335]: Fix crash when trying to enlarge a bytearray to 0x7fffffff bytes on a 32-bit platform.

bpo-22653 [https://bugs.python.org/issue?@action=redirect&bpo=22653]: Fix an assertion failure in debug mode when doing a reentrant dict insertion in debug mode.

bpo-22643 [https://bugs.python.org/issue?@action=redirect&bpo=22643]: Fix integer overflow in Unicode case operations (upper, lower, title, swapcase, casefold).

bpo-17636 [https://bugs.python.org/issue?@action=redirect&bpo=17636]: Circular imports involving relative imports are now supported.

bpo-22604 [https://bugs.python.org/issue?@action=redirect&bpo=22604]: Fix assertion error in debug mode when dividing a complex number by (nan+0j).

bpo-21052 [https://bugs.python.org/issue?@action=redirect&bpo=21052]: Do not raise ImportWarning when sys.path_hooks or sys.meta_path are set to None.

bpo-16518 [https://bugs.python.org/issue?@action=redirect&bpo=16518]: Use “bytes-like object required” in error messages that previously used the far more cryptic «“x” does not support the buffer protocol.

bpo-22470 [https://bugs.python.org/issue?@action=redirect&bpo=22470]: Fixed integer overflow issues in «backslashreplace», «xmlcharrefreplace», and «surrogatepass» error handlers.

bpo-22540 [https://bugs.python.org/issue?@action=redirect&bpo=22540]: speed up PyObject_IsInstance and PyObject_IsSubclass in the common case that the second argument has metaclass type.

bpo-18711 [https://bugs.python.org/issue?@action=redirect&bpo=18711]: Add a new PyErr_FormatV function, similar to PyErr_Format but accepting a va_list argument.

bpo-22520 [https://bugs.python.org/issue?@action=redirect&bpo=22520]: Fix overflow checking when generating the repr of a unicode object.

bpo-22519 [https://bugs.python.org/issue?@action=redirect&bpo=22519]: Fix overflow checking in PyBytes_Repr.

bpo-22518 [https://bugs.python.org/issue?@action=redirect&bpo=22518]: Fix integer overflow issues in latin-1 encoding.

bpo-16324 [https://bugs.python.org/issue?@action=redirect&bpo=16324]: _charset parameter of MIMEText now also accepts email.charset.Charset instances. Initial patch by Claude Paroz.

bpo-1764286 [https://bugs.python.org/issue?@action=redirect&bpo=1764286]: Fix inspect.getsource() to support decorated functions. Patch by Claudiu Popa.

bpo-18554 [https://bugs.python.org/issue?@action=redirect&bpo=18554]: os.__all__ includes posix functions.

bpo-21391 [https://bugs.python.org/issue?@action=redirect&bpo=21391]: Use os.path.abspath in the shutil module.

bpo-11471 [https://bugs.python.org/issue?@action=redirect&bpo=11471]: avoid generating a JUMP_FORWARD instruction at the end of an if-block if there is no else-clause. Original patch by Eugene Toder.

bpo-22215 [https://bugs.python.org/issue?@action=redirect&bpo=22215]: Now ValueError is raised instead of TypeError when str or bytes argument contains not permitted null character or byte.

bpo-22258 [https://bugs.python.org/issue?@action=redirect&bpo=22258]: Fix the internal function set_inheritable() on Illumos. This platform exposes the function ioctl(FIOCLEX), but calling it fails with errno is ENOTTY: «Inappropriate ioctl for device». set_inheritable() now falls back to the slower fcntl() (F_GETFD and then F_SETFD).

bpo-21389 [https://bugs.python.org/issue?@action=redirect&bpo=21389]: Displaying the __qualname__ of the underlying function in the repr of a bound method.

bpo-22206 [https://bugs.python.org/issue?@action=redirect&bpo=22206]: Using pthread, PyThread_create_key() now sets errno to ENOMEM and returns -1 (error) on integer overflow.

bpo-20184 [https://bugs.python.org/issue?@action=redirect&bpo=20184]: Argument Clinic based signature introspection added for 30 of the builtin functions.

bpo-22116 [https://bugs.python.org/issue?@action=redirect&bpo=22116]: C functions and methods (of the “builtin_function_or_method” type) can now be weakref’ed. Patch by Wei Wu.

bpo-22077 [https://bugs.python.org/issue?@action=redirect&bpo=22077]: Improve index error messages for bytearrays, bytes, lists, and tuples by adding “or slices”. Added “, not <typename>” for bytearrays. Original patch by Claudiu Popa.

bpo-20179 [https://bugs.python.org/issue?@action=redirect&bpo=20179]: Apply Argument Clinic to bytes and bytearray. Patch by Tal Einat.

bpo-22082 [https://bugs.python.org/issue?@action=redirect&bpo=22082]: Clear interned strings in slotdefs.

Upgrade Unicode database to Unicode 7.0.0.

bpo-21897 [https://bugs.python.org/issue?@action=redirect&bpo=21897]: Fix a crash with the f_locals attribute with closure variables when frame.clear() has been called.

bpo-21205 [https://bugs.python.org/issue?@action=redirect&bpo=21205]: Add a new __qualname__ attribute to generator, the qualified name, and use it in the representation of a generator (repr(gen)). The default name of the generator (__name__ attribute) is now get from the function instead of the code. Use gen.gi_code.co_name to get the name of the code.

bpo-21669 [https://bugs.python.org/issue?@action=redirect&bpo=21669]: With the aid of heuristics in SyntaxError.__init__, the parser now attempts to generate more meaningful (or at least more search engine friendly) error messages when «exec» and «print» are used as statements.

bpo-21642 [https://bugs.python.org/issue?@action=redirect&bpo=21642]: In the conditional if-else expression, allow an integer written with no space between itself and the else keyword (e.g. True if 42else False) to be valid syntax.

bpo-21523 [https://bugs.python.org/issue?@action=redirect&bpo=21523]: Fix over-pessimistic computation of the stack effect of some opcodes in the compiler. This also fixes a quadratic compilation time issue noticeable when compiling code with a large number of «and» and «or» operators.

bpo-21418 [https://bugs.python.org/issue?@action=redirect&bpo=21418]: Fix a crash in the builtin function super() when called without argument and without current frame (ex: embedded Python).

bpo-21425 [https://bugs.python.org/issue?@action=redirect&bpo=21425]: Fix flushing of standard streams in the interactive interpreter.

bpo-21435 [https://bugs.python.org/issue?@action=redirect&bpo=21435]: In rare cases, when running finalizers on objects in cyclic trash a bad pointer dereference could occur due to a subtle flaw in internal iteration logic.

bpo-21377 [https://bugs.python.org/issue?@action=redirect&bpo=21377]: PyBytes_Concat() now tries to concatenate in-place when the first argument has a reference count of 1. Patch by Nikolaus Rath.

bpo-20355 [https://bugs.python.org/issue?@action=redirect&bpo=20355]: -W command line options now have higher priority than the PYTHONWARNINGS environment variable. Patch by Arfrever.

bpo-21274 [https://bugs.python.org/issue?@action=redirect&bpo=21274]: Define PATH_MAX for GNU/Hurd in Python/pythonrun.c.

bpo-20904 [https://bugs.python.org/issue?@action=redirect&bpo=20904]: Support setting FPU precision on m68k.

bpo-21209 [https://bugs.python.org/issue?@action=redirect&bpo=21209]: Fix sending tuples to custom generator objects with the yield from syntax.

bpo-21193 [https://bugs.python.org/issue?@action=redirect&bpo=21193]: pow(a, b, c) now raises ValueError rather than TypeError when b is negative. Patch by Josh Rosenberg.

bpo-21176 [https://bugs.python.org/issue?@action=redirect&bpo=21176]: PEP 465: Add the “@” operator for matrix multiplication.

bpo-21134 [https://bugs.python.org/issue?@action=redirect&bpo=21134]: Fix segfault when str is called on an uninitialized UnicodeEncodeError, UnicodeDecodeError, or UnicodeTranslateError object.

bpo-19537 [https://bugs.python.org/issue?@action=redirect&bpo=19537]: Fix PyUnicode_DATA() alignment under m68k. Patch by Andreas Schwab.

bpo-20929 [https://bugs.python.org/issue?@action=redirect&bpo=20929]: Add a type cast to avoid shifting a negative number.

bpo-20731 [https://bugs.python.org/issue?@action=redirect&bpo=20731]: Properly position in source code files even if they are opened in text mode. Patch by Serhiy Storchaka.

bpo-20637 [https://bugs.python.org/issue?@action=redirect&bpo=20637]: Key-sharing now also works for instance dictionaries of subclasses. Patch by Peter Ingebretson.

bpo-8297 [https://bugs.python.org/issue?@action=redirect&bpo=8297]: Attributes missing from modules now include the module name in the error text. Original patch by ysj.ray.

bpo-19995 [https://bugs.python.org/issue?@action=redirect&bpo=19995]: %c, %o, %x, and %X now raise TypeError on non-integer input.

bpo-19655 [https://bugs.python.org/issue?@action=redirect&bpo=19655]: The ASDL parser - used by the build process to generate code for managing the Python AST in C - was rewritten. The new parser is self contained and does not require to carry long the spark.py parser-generator library; spark.py was removed from the source base.

bpo-12546 [https://bugs.python.org/issue?@action=redirect&bpo=12546]: Allow \x00 to be used as a fill character when using str, int, float, and complex __format__ methods.

bpo-20480 [https://bugs.python.org/issue?@action=redirect&bpo=20480]: Add ipaddress.reverse_pointer. Patch by Leon Weber.

bpo-13598 [https://bugs.python.org/issue?@action=redirect&bpo=13598]: Modify string.Formatter to support auto-numbering of replacement fields. It now matches the behavior of str.format() in this regard. Patches by Phil Elson and Ramchandra Apte.

bpo-8931 [https://bugs.python.org/issue?@action=redirect&bpo=8931]: Make alternate formatting (“#”) for type “c” raise an exception. In versions prior to 3.5, “#” with “c” had no effect. Now specifying it is an error. Patch by Torsten Landschoff.

bpo-23165 [https://bugs.python.org/issue?@action=redirect&bpo=23165]: Perform overflow checks before allocating memory in the _Py_char2wchar function.

Library

bpo-23399 [https://bugs.python.org/issue?@action=redirect&bpo=23399]: pyvenv creates relative symlinks where possible.

bpo-20289 [https://bugs.python.org/issue?@action=redirect&bpo=20289]: cgi.FieldStorage() now supports the context management protocol.

bpo-13128 [https://bugs.python.org/issue?@action=redirect&bpo=13128]: Print response headers for CONNECT requests when debuglevel > 0. Patch by Demian Brecht.

bpo-15381 [https://bugs.python.org/issue?@action=redirect&bpo=15381]: Optimized io.BytesIO to make less allocations and copyings.

bpo-22818 [https://bugs.python.org/issue?@action=redirect&bpo=22818]: Splitting on a pattern that could match an empty string now raises a warning. Patterns that can only match empty strings are now rejected.

bpo-23099 [https://bugs.python.org/issue?@action=redirect&bpo=23099]: Closing io.BytesIO with exported buffer is rejected now to prevent corrupting exported buffer.

bpo-23326 [https://bugs.python.org/issue?@action=redirect&bpo=23326]: Removed __ne__ implementations. Since fixing default __ne__ implementation in bpo-21408 [https://bugs.python.org/issue?@action=redirect&bpo=21408] they are redundant.

bpo-23363 [https://bugs.python.org/issue?@action=redirect&bpo=23363]: Fix possible overflow in itertools.permutations.

bpo-23364 [https://bugs.python.org/issue?@action=redirect&bpo=23364]: Fix possible overflow in itertools.product.

bpo-23366 [https://bugs.python.org/issue?@action=redirect&bpo=23366]: Fixed possible integer overflow in itertools.combinations.

bpo-23369 [https://bugs.python.org/issue?@action=redirect&bpo=23369]: Fixed possible integer overflow in _json.encode_basestring_ascii.

bpo-23353 [https://bugs.python.org/issue?@action=redirect&bpo=23353]: Fix the exception handling of generators in PyEval_EvalFrameEx(). At entry, save or swap the exception state even if PyEval_EvalFrameEx() is called with throwflag=0. At exit, the exception state is now always restored or swapped, not only if why is WHY_YIELD or WHY_RETURN. Patch co-written with Antoine Pitrou.

bpo-14099 [https://bugs.python.org/issue?@action=redirect&bpo=14099]: Restored support of writing ZIP files to tellable but non-seekable streams.

bpo-14099 [https://bugs.python.org/issue?@action=redirect&bpo=14099]: Writing to ZipFile and reading multiple ZipExtFiles is threadsafe now.

bpo-19361 [https://bugs.python.org/issue?@action=redirect&bpo=19361]: JSON decoder now raises JSONDecodeError instead of ValueError.

bpo-18518 [https://bugs.python.org/issue?@action=redirect&bpo=18518]: timeit now rejects statements which can’t be compiled outside a function or a loop (e.g. «return» or «break»).

bpo-23094 [https://bugs.python.org/issue?@action=redirect&bpo=23094]: Fixed readline with frames in Python implementation of pickle.

bpo-23268 [https://bugs.python.org/issue?@action=redirect&bpo=23268]: Fixed bugs in the comparison of ipaddress classes.

bpo-21408 [https://bugs.python.org/issue?@action=redirect&bpo=21408]: Removed incorrect implementations of __ne__() which didn’t returned NotImplemented if __eq__() returned NotImplemented. The default __ne__() now works correctly.

bpo-19996 [https://bugs.python.org/issue?@action=redirect&bpo=19996]: email.feedparser.FeedParser now handles (malformed) headers with no key rather than assuming the body has started.

bpo-20188 [https://bugs.python.org/issue?@action=redirect&bpo=20188]: Support Application-Layer Protocol Negotiation (ALPN) in the ssl module.

bpo-23133 [https://bugs.python.org/issue?@action=redirect&bpo=23133]: Pickling of ipaddress objects now produces more compact and portable representation.

bpo-23248 [https://bugs.python.org/issue?@action=redirect&bpo=23248]: Update ssl error codes from latest OpenSSL git master.

bpo-23266 [https://bugs.python.org/issue?@action=redirect&bpo=23266]: Much faster implementation of ipaddress.collapse_addresses() when there are many non-consecutive addresses.

bpo-23098 [https://bugs.python.org/issue?@action=redirect&bpo=23098]: 64-bit dev_t is now supported in the os module.

bpo-21817 [https://bugs.python.org/issue?@action=redirect&bpo=21817]: When an exception is raised in a task submitted to a ProcessPoolExecutor, the remote traceback is now displayed in the parent process. Patch by Claudiu Popa.

bpo-15955 [https://bugs.python.org/issue?@action=redirect&bpo=15955]: Add an option to limit output size when decompressing LZMA data. Patch by Nikolaus Rath and Martin Panter.

bpo-23250 [https://bugs.python.org/issue?@action=redirect&bpo=23250]: In the http.cookies module, capitalize «HttpOnly» and «Secure» as they are written in the standard.

bpo-23063 [https://bugs.python.org/issue?@action=redirect&bpo=23063]: In the distutils” check command, fix parsing of reST with code or code-block directives.

bpo-23209 [https://bugs.python.org/issue?@action=redirect&bpo=23209]: selectors.BaseSelector.get_key() now raises a RuntimeError if the selector is closed. And selectors.BaseSelector.close() now clears its internal reference to the selector mapping to break a reference cycle. Initial patch written by Martin Richard. (See also: bpo-23225 [https://bugs.python.org/issue?@action=redirect&bpo=23225])

bpo-17911 [https://bugs.python.org/issue?@action=redirect&bpo=17911]: Provide a way to seed the linecache for a PEP-302 module without actually loading the code.

bpo-17911 [https://bugs.python.org/issue?@action=redirect&bpo=17911]: Provide a new object API for traceback, including the ability to not lookup lines at all until the traceback is actually rendered, without any trace of the original objects being kept alive.

bpo-19777 [https://bugs.python.org/issue?@action=redirect&bpo=19777]: Provide a home() classmethod on Path objects. Contributed by Victor Salgado and Mayank Tripathi.

bpo-23206 [https://bugs.python.org/issue?@action=redirect&bpo=23206]: Make json.dumps(..., ensure_ascii=False) as fast as the default case of ensure_ascii=True. Patch by Naoki Inada.

bpo-23185 [https://bugs.python.org/issue?@action=redirect&bpo=23185]: Add math.inf and math.nan constants.

bpo-23186 [https://bugs.python.org/issue?@action=redirect&bpo=23186]: Add ssl.SSLObject.shared_ciphers() and ssl.SSLSocket.shared_ciphers() to fetch the client’s list ciphers sent at handshake.

bpo-23143 [https://bugs.python.org/issue?@action=redirect&bpo=23143]: Remove compatibility with OpenSSLs older than 0.9.8.

bpo-23132 [https://bugs.python.org/issue?@action=redirect&bpo=23132]: Improve performance and introspection support of comparison methods created by functool.total_ordering.

bpo-19776 [https://bugs.python.org/issue?@action=redirect&bpo=19776]: Add an expanduser() method on Path objects.

bpo-23112 [https://bugs.python.org/issue?@action=redirect&bpo=23112]: Fix SimpleHTTPServer to correctly carry the query string and fragment when it redirects to add a trailing slash.

bpo-21793 [https://bugs.python.org/issue?@action=redirect&bpo=21793]: Added http.HTTPStatus enums (i.e. HTTPStatus.OK, HTTPStatus.NOT_FOUND). Patch by Demian Brecht.

bpo-23093 [https://bugs.python.org/issue?@action=redirect&bpo=23093]: In the io, module allow more operations to work on detached streams.

bpo-23111 [https://bugs.python.org/issue?@action=redirect&bpo=23111]: In the ftplib, make ssl.PROTOCOL_SSLv23 the default protocol version.

bpo-22585 [https://bugs.python.org/issue?@action=redirect&bpo=22585]: On OpenBSD 5.6 and newer, os.urandom() now calls getentropy(), instead of reading /dev/urandom, to get pseudo-random bytes.

bpo-19104 [https://bugs.python.org/issue?@action=redirect&bpo=19104]: pprint now produces evaluable output for wrapped strings.

bpo-23071 [https://bugs.python.org/issue?@action=redirect&bpo=23071]: Added missing names to codecs.__all__. Patch by Martin Panter.

bpo-22783 [https://bugs.python.org/issue?@action=redirect&bpo=22783]: Pickling now uses the NEWOBJ opcode instead of the NEWOBJ_EX opcode if possible.

bpo-15513 [https://bugs.python.org/issue?@action=redirect&bpo=15513]: Added a __sizeof__ implementation for pickle classes.

bpo-19858 [https://bugs.python.org/issue?@action=redirect&bpo=19858]: pickletools.optimize() now aware of the MEMOIZE opcode, can produce more compact result and no longer produces invalid output if input data contains MEMOIZE opcodes together with PUT or BINPUT opcodes.

bpo-22095 [https://bugs.python.org/issue?@action=redirect&bpo=22095]: Fixed HTTPConnection.set_tunnel with default port. The port value in the host header was set to «None». Patch by Demian Brecht.

bpo-23016 [https://bugs.python.org/issue?@action=redirect&bpo=23016]: A warning no longer produces an AttributeError when the program is run with pythonw.exe.

bpo-21775 [https://bugs.python.org/issue?@action=redirect&bpo=21775]: shutil.copytree(): fix crash when copying to VFAT. An exception handler assumed that OSError objects always have a “winerror” attribute. That is not the case, so the exception handler itself raised AttributeError when run on Linux (and, presumably, any other non-Windows OS). Patch by Greg Ward.

bpo-1218234 [https://bugs.python.org/issue?@action=redirect&bpo=1218234]: Fix inspect.getsource() to load updated source of reloaded module. Initial patch by Berker Peksag.

bpo-21740 [https://bugs.python.org/issue?@action=redirect&bpo=21740]: Support wrapped callables in doctest. Patch by Claudiu Popa.

bpo-23009 [https://bugs.python.org/issue?@action=redirect&bpo=23009]: Make sure selectors.EpollSelector.select() works when no FD is registered.

bpo-22959 [https://bugs.python.org/issue?@action=redirect&bpo=22959]: In the constructor of http.client.HTTPSConnection, prefer the context’s check_hostname attribute over the check_hostname parameter.

bpo-22696 [https://bugs.python.org/issue?@action=redirect&bpo=22696]: Add function sys.is_finalizing() to know about interpreter shutdown.

bpo-16043 [https://bugs.python.org/issue?@action=redirect&bpo=16043]: Add a default limit for the amount of data xmlrpclib.gzip_decode will return. This resolves CVE-2013-1753.

bpo-14099 [https://bugs.python.org/issue?@action=redirect&bpo=14099]: ZipFile.open() no longer reopen the underlying file. Objects returned by ZipFile.open() can now operate independently of the ZipFile even if the ZipFile was created by passing in a file-like object as the first argument to the constructor.

bpo-22966 [https://bugs.python.org/issue?@action=redirect&bpo=22966]: Fix __pycache__ pyc file name clobber when pyc_compile is asked to compile a source file containing multiple dots in the source file name.

bpo-21971 [https://bugs.python.org/issue?@action=redirect&bpo=21971]: Update turtledemo doc and add module to the index.

bpo-21032 [https://bugs.python.org/issue?@action=redirect&bpo=21032]: Fixed socket leak if HTTPConnection.getresponse() fails. Original patch by Martin Panter.

bpo-22407 [https://bugs.python.org/issue?@action=redirect&bpo=22407]: Deprecated the use of re.LOCALE flag with str patterns or re.ASCII. It was newer worked.

bpo-22902 [https://bugs.python.org/issue?@action=redirect&bpo=22902]: The «ip» command is now used on Linux to determine MAC address in uuid.getnode(). Pach by Bruno Cauet.

bpo-22960 [https://bugs.python.org/issue?@action=redirect&bpo=22960]: Add a context argument to xmlrpclib.ServerProxy constructor.

bpo-22389 [https://bugs.python.org/issue?@action=redirect&bpo=22389]: Add contextlib.redirect_stderr().

bpo-21356 [https://bugs.python.org/issue?@action=redirect&bpo=21356]: Make ssl.RAND_egd() optional to support LibreSSL. The availability of the function is checked during the compilation. Patch written by Bernard Spil.

bpo-22915 [https://bugs.python.org/issue?@action=redirect&bpo=22915]: SAX parser now supports files opened with file descriptor or bytes path.

bpo-22609 [https://bugs.python.org/issue?@action=redirect&bpo=22609]: Constructors and update methods of mapping classes in the collections module now accept the self keyword argument.

bpo-22940 [https://bugs.python.org/issue?@action=redirect&bpo=22940]: Add readline.append_history_file.

bpo-19676 [https://bugs.python.org/issue?@action=redirect&bpo=19676]: Added the «namereplace» error handler.

bpo-22788 [https://bugs.python.org/issue?@action=redirect&bpo=22788]: Add context parameter to logging.handlers.HTTPHandler.

bpo-22921 [https://bugs.python.org/issue?@action=redirect&bpo=22921]: Allow SSLContext to take the hostname parameter even if OpenSSL doesn’t support SNI.

bpo-22894 [https://bugs.python.org/issue?@action=redirect&bpo=22894]: TestCase.subTest() would cause the test suite to be stopped when in failfast mode, even in the absence of failures.

bpo-22796 [https://bugs.python.org/issue?@action=redirect&bpo=22796]: HTTP cookie parsing is now stricter, in order to protect against potential injection attacks.

bpo-22370 [https://bugs.python.org/issue?@action=redirect&bpo=22370]: Windows detection in pathlib is now more robust.

bpo-22841 [https://bugs.python.org/issue?@action=redirect&bpo=22841]: Reject coroutines in asyncio add_signal_handler(). Patch by Ludovic.Gasc.

bpo-19494 [https://bugs.python.org/issue?@action=redirect&bpo=19494]: Added urllib.request.HTTPBasicPriorAuthHandler. Patch by Matej Cepl.

bpo-22578 [https://bugs.python.org/issue?@action=redirect&bpo=22578]: Added attributes to the re.error class.

bpo-22849 [https://bugs.python.org/issue?@action=redirect&bpo=22849]: Fix possible double free in the io.TextIOWrapper constructor.

bpo-12728 [https://bugs.python.org/issue?@action=redirect&bpo=12728]: Different Unicode characters having the same uppercase but different lowercase are now matched in case-insensitive regular expressions.

bpo-22821 [https://bugs.python.org/issue?@action=redirect&bpo=22821]: Fixed fcntl() with integer argument on 64-bit big-endian platforms.

bpo-21650 [https://bugs.python.org/issue?@action=redirect&bpo=21650]: Add an --sort-keys option to json.tool CLI.

bpo-22824 [https://bugs.python.org/issue?@action=redirect&bpo=22824]: Updated reprlib output format for sets to use set literals. Patch contributed by Berker Peksag.

bpo-22824 [https://bugs.python.org/issue?@action=redirect&bpo=22824]: Updated reprlib output format for arrays to display empty arrays without an unnecessary empty list. Suggested by Serhiy Storchaka.

bpo-22406 [https://bugs.python.org/issue?@action=redirect&bpo=22406]: Fixed the uu_codec codec incorrectly ported to 3.x. Based on patch by Martin Panter.

bpo-17293 [https://bugs.python.org/issue?@action=redirect&bpo=17293]: uuid.getnode() now determines MAC address on AIX using netstat. Based on patch by Aivars Kalvāns.

bpo-22769 [https://bugs.python.org/issue?@action=redirect&bpo=22769]: Fixed ttk.Treeview.tag_has() when called without arguments.

bpo-22417 [https://bugs.python.org/issue?@action=redirect&bpo=22417]: Verify certificates by default in httplib (PEP 476).

bpo-22775 [https://bugs.python.org/issue?@action=redirect&bpo=22775]: Fixed unpickling of http.cookies.SimpleCookie with protocol 2 and above. Patch by Tim Graham.

bpo-22776 [https://bugs.python.org/issue?@action=redirect&bpo=22776]: Brought excluded code into the scope of a try block in SysLogHandler.emit().

bpo-22665 [https://bugs.python.org/issue?@action=redirect&bpo=22665]: Add missing get_terminal_size and SameFileError to shutil.__all__.

bpo-6623 [https://bugs.python.org/issue?@action=redirect&bpo=6623]: Remove deprecated Netrc class in the ftplib module. Patch by Matt Chaput.

bpo-17381 [https://bugs.python.org/issue?@action=redirect&bpo=17381]: Fixed handling of case-insensitive ranges in regular expressions.

bpo-22410 [https://bugs.python.org/issue?@action=redirect&bpo=22410]: Module level functions in the re module now cache compiled locale-dependent regular expressions taking into account the locale.

bpo-22759 [https://bugs.python.org/issue?@action=redirect&bpo=22759]: Query methods on pathlib.Path() (exists(), is_dir(), etc.) now return False when the underlying stat call raises NotADirectoryError.

bpo-8876 [https://bugs.python.org/issue?@action=redirect&bpo=8876]: distutils now falls back to copying files when hard linking doesn’t work. This allows use with special filesystems such as VirtualBox shared folders.

bpo-22217 [https://bugs.python.org/issue?@action=redirect&bpo=22217]: Implemented reprs of classes in the zipfile module.

bpo-22457 [https://bugs.python.org/issue?@action=redirect&bpo=22457]: Honour load_tests in the start_dir of discovery.

bpo-18216 [https://bugs.python.org/issue?@action=redirect&bpo=18216]: gettext now raises an error when a .mo file has an unsupported major version number. Patch by Aaron Hill.

bpo-13918 [https://bugs.python.org/issue?@action=redirect&bpo=13918]: Provide a locale.delocalize() function which can remove locale-specific number formatting from a string representing a number, without then converting it to a specific type. Patch by Cédric Krier.

bpo-22676 [https://bugs.python.org/issue?@action=redirect&bpo=22676]: Make the pickling of global objects which don’t have a __module__ attribute less slow.

bpo-18853 [https://bugs.python.org/issue?@action=redirect&bpo=18853]: Fixed ResourceWarning in shlex.__nain__.

bpo-9351 [https://bugs.python.org/issue?@action=redirect&bpo=9351]: Defaults set with set_defaults on an argparse subparser are no longer ignored when also set on the parent parser.

bpo-7559 [https://bugs.python.org/issue?@action=redirect&bpo=7559]: unittest test loading ImportErrors are reported as import errors with their import exception rather than as attribute errors after the import has already failed.

bpo-19746 [https://bugs.python.org/issue?@action=redirect&bpo=19746]: Make it possible to examine the errors from unittest discovery without executing the test suite. The new errors attribute on TestLoader exposes these non-fatal errors encountered during discovery.

bpo-21991 [https://bugs.python.org/issue?@action=redirect&bpo=21991]: Make email.headerregistry’s header “params” attributes be read-only (MappingProxyType). Previously the dictionary was modifiable but a new one was created on each access of the attribute.

bpo-22638 [https://bugs.python.org/issue?@action=redirect&bpo=22638]: SSLv3 is now disabled throughout the standard library. It can still be enabled by instantiating a SSLContext manually.

bpo-22641 [https://bugs.python.org/issue?@action=redirect&bpo=22641]: In asyncio, the default SSL context for client connections is now created using ssl.create_default_context(), for stronger security.

bpo-17401 [https://bugs.python.org/issue?@action=redirect&bpo=17401]: Include closefd in io.FileIO repr.

bpo-21338 [https://bugs.python.org/issue?@action=redirect&bpo=21338]: Add silent mode for compileall. quiet parameters of compile_{dir, file, path} functions now have a multilevel value. Also, -q option of the CLI now have a multilevel value. Patch by Thomas Kluyver.

bpo-20152 [https://bugs.python.org/issue?@action=redirect&bpo=20152]: Convert the array and cmath modules to Argument Clinic.

bpo-18643 [https://bugs.python.org/issue?@action=redirect&bpo=18643]: Add socket.socketpair() on Windows.

bpo-22435 [https://bugs.python.org/issue?@action=redirect&bpo=22435]: Fix a file descriptor leak when socketserver bind fails.

bpo-13096 [https://bugs.python.org/issue?@action=redirect&bpo=13096]: Fixed segfault in CTypes POINTER handling of large values.

bpo-11694 [https://bugs.python.org/issue?@action=redirect&bpo=11694]: Raise ConversionError in xdrlib as documented. Patch by Filip Gruszczyński and Claudiu Popa.

bpo-19380 [https://bugs.python.org/issue?@action=redirect&bpo=19380]: Optimized parsing of regular expressions.

bpo-1519638 [https://bugs.python.org/issue?@action=redirect&bpo=1519638]: Now unmatched groups are replaced with empty strings in re.sub() and re.subn().

bpo-18615 [https://bugs.python.org/issue?@action=redirect&bpo=18615]: sndhdr.what/whathdr now return a namedtuple.

bpo-22462 [https://bugs.python.org/issue?@action=redirect&bpo=22462]: Fix pyexpat’s creation of a dummy frame to make it appear in exception tracebacks.

bpo-21965 [https://bugs.python.org/issue?@action=redirect&bpo=21965]: Add support for in-memory SSL to the ssl module. Patch by Geert Jansen.

bpo-21173 [https://bugs.python.org/issue?@action=redirect&bpo=21173]: Fix len() on a WeakKeyDictionary when .clear() was called with an iterator alive.

bpo-11866 [https://bugs.python.org/issue?@action=redirect&bpo=11866]: Eliminated race condition in the computation of names for new threads.

bpo-21905 [https://bugs.python.org/issue?@action=redirect&bpo=21905]: Avoid RuntimeError in pickle.whichmodule() when sys.modules is mutated while iterating. Patch by Olivier Grisel.

bpo-11271 [https://bugs.python.org/issue?@action=redirect&bpo=11271]: concurrent.futures.Executor.map() now takes a chunksize argument to allow batching of tasks in child processes and improve performance of ProcessPoolExecutor. Patch by Dan O’Reilly.

bpo-21883 [https://bugs.python.org/issue?@action=redirect&bpo=21883]: os.path.join() and os.path.relpath() now raise a TypeError with more helpful error message for unsupported or mismatched types of arguments.

bpo-22219 [https://bugs.python.org/issue?@action=redirect&bpo=22219]: The zipfile module CLI now adds entries for directories (including empty directories) in ZIP file.

bpo-22449 [https://bugs.python.org/issue?@action=redirect&bpo=22449]: In the ssl.SSLContext.load_default_certs, consult the environmental variables SSL_CERT_DIR and SSL_CERT_FILE on Windows.

bpo-22508 [https://bugs.python.org/issue?@action=redirect&bpo=22508]: The email.__version__ variable has been removed; the email code is no longer shipped separately from the stdlib, and __version__ hasn’t been updated in several releases.

bpo-20076 [https://bugs.python.org/issue?@action=redirect&bpo=20076]: Added non derived UTF-8 aliases to locale aliases table.

bpo-20079 [https://bugs.python.org/issue?@action=redirect&bpo=20079]: Added locales supported in glibc 2.18 to locale alias table.

bpo-20218 [https://bugs.python.org/issue?@action=redirect&bpo=20218]: Added convenience methods read_text/write_text and read_bytes/ write_bytes to pathlib.Path objects.

bpo-22396 [https://bugs.python.org/issue?@action=redirect&bpo=22396]: On 32-bit AIX platform, don’t expose os.posix_fadvise() nor os.posix_fallocate() because their prototypes in system headers are wrong.

bpo-22517 [https://bugs.python.org/issue?@action=redirect&bpo=22517]: When an io.BufferedRWPair object is deallocated, clear its weakrefs.

bpo-22437 [https://bugs.python.org/issue?@action=redirect&bpo=22437]: Number of capturing groups in regular expression is no longer limited by 100.

bpo-17442 [https://bugs.python.org/issue?@action=redirect&bpo=17442]: InteractiveInterpreter now displays the full chained traceback in its showtraceback method, to match the built in interactive interpreter.

bpo-23392 [https://bugs.python.org/issue?@action=redirect&bpo=23392]: Added tests for marshal C API that works with FILE*.

bpo-10510 [https://bugs.python.org/issue?@action=redirect&bpo=10510]: distutils register and upload methods now use HTML standards compliant CRLF line endings.

bpo-9850 [https://bugs.python.org/issue?@action=redirect&bpo=9850]: Fixed macpath.join() for empty first component. Patch by Oleg Oshmyan.

bpo-5309 [https://bugs.python.org/issue?@action=redirect&bpo=5309]: distutils” build and build_ext commands now accept a -j option to enable parallel building of extension modules.

bpo-22448 [https://bugs.python.org/issue?@action=redirect&bpo=22448]: Improve canceled timer handles cleanup to prevent unbound memory usage. Patch by Joshua Moore-Oliva.

bpo-22427 [https://bugs.python.org/issue?@action=redirect&bpo=22427]: TemporaryDirectory no longer attempts to clean up twice when used in the with statement in generator.

bpo-22362 [https://bugs.python.org/issue?@action=redirect&bpo=22362]: Forbidden ambiguous octal escapes out of range 0-0o377 in regular expressions.

bpo-20912 [https://bugs.python.org/issue?@action=redirect&bpo=20912]: Now directories added to ZIP file have correct Unix and MS-DOS directory attributes.

bpo-21866 [https://bugs.python.org/issue?@action=redirect&bpo=21866]: ZipFile.close() no longer writes ZIP64 central directory records if allowZip64 is false.

bpo-22278 [https://bugs.python.org/issue?@action=redirect&bpo=22278]: Fix urljoin problem with relative urls, a regression observed after changes to issue22118 were submitted.

bpo-22415 [https://bugs.python.org/issue?@action=redirect&bpo=22415]: Fixed debugging output of the GROUPREF_EXISTS opcode in the re module. Removed trailing spaces in debugging output.

bpo-22423 [https://bugs.python.org/issue?@action=redirect&bpo=22423]: Unhandled exception in thread no longer causes unhandled AttributeError when sys.stderr is None.

bpo-21332 [https://bugs.python.org/issue?@action=redirect&bpo=21332]: Ensure that bufsize=1 in subprocess.Popen() selects line buffering, rather than block buffering. Patch by Akira Li.

bpo-21091 [https://bugs.python.org/issue?@action=redirect&bpo=21091]: Fix API bug: email.message.EmailMessage.is_attachment is now a method.

bpo-21079 [https://bugs.python.org/issue?@action=redirect&bpo=21079]: Fix email.message.EmailMessage.is_attachment to return the correct result when the header has parameters as well as a value.

bpo-22247 [https://bugs.python.org/issue?@action=redirect&bpo=22247]: Add NNTPError to nntplib.__all__.

bpo-22366 [https://bugs.python.org/issue?@action=redirect&bpo=22366]: urllib.request.urlopen will accept a context object (SSLContext) as an argument which will then be used for HTTPS connection. Patch by Alex Gaynor.

bpo-4180 [https://bugs.python.org/issue?@action=redirect&bpo=4180]: The warnings registries are now reset when the filters are modified.

bpo-22419 [https://bugs.python.org/issue?@action=redirect&bpo=22419]: Limit the length of incoming HTTP request in wsgiref server to 65536 bytes and send a 414 error code for higher lengths. Patch contributed by Devin Cook.

Lax cookie parsing in http.cookies could be a security issue when combined with non-standard cookie handling in some Web browsers. Reported by Sergey Bobrov.

bpo-20537 [https://bugs.python.org/issue?@action=redirect&bpo=20537]: logging methods now accept an exception instance as well as a Boolean value or exception tuple. Thanks to Yury Selivanov for the patch.

bpo-22384 [https://bugs.python.org/issue?@action=redirect&bpo=22384]: An exception in Tkinter callback no longer crashes the program when it is run with pythonw.exe.

bpo-22168 [https://bugs.python.org/issue?@action=redirect&bpo=22168]: Prevent turtle AttributeError with non-default Canvas on OS X.

bpo-21147 [https://bugs.python.org/issue?@action=redirect&bpo=21147]: sqlite3 now raises an exception if the request contains a null character instead of truncating it. Based on patch by Victor Stinner.

bpo-13968 [https://bugs.python.org/issue?@action=redirect&bpo=13968]: The glob module now supports recursive search in subdirectories using the ** pattern.

bpo-21951 [https://bugs.python.org/issue?@action=redirect&bpo=21951]: Fixed a crash in Tkinter on AIX when called Tcl command with empty string or tuple argument.

bpo-21951 [https://bugs.python.org/issue?@action=redirect&bpo=21951]: Tkinter now most likely raises MemoryError instead of crash if the memory allocation fails.

bpo-22338 [https://bugs.python.org/issue?@action=redirect&bpo=22338]: Fix a crash in the json module on memory allocation failure.

bpo-12410 [https://bugs.python.org/issue?@action=redirect&bpo=12410]: imaplib.IMAP4 now supports the context management protocol. Original patch by Tarek Ziadé.

bpo-21270 [https://bugs.python.org/issue?@action=redirect&bpo=21270]: We now override tuple methods in mock.call objects so that they can be used as normal call attributes.

bpo-16662 [https://bugs.python.org/issue?@action=redirect&bpo=16662]: load_tests() is now unconditionally run when it is present in a package’s __init__.py. TestLoader.loadTestsFromModule() still accepts use_load_tests, but it is deprecated and ignored. A new keyword-only attribute pattern is added and documented. Patch given by Robert Collins, tweaked by Barry Warsaw.

bpo-22226 [https://bugs.python.org/issue?@action=redirect&bpo=22226]: First letter no longer is stripped from the «status» key in the result of Treeview.heading().

bpo-19524 [https://bugs.python.org/issue?@action=redirect&bpo=19524]: Fixed resource leak in the HTTP connection when an invalid response is received. Patch by Martin Panter.

bpo-20421 [https://bugs.python.org/issue?@action=redirect&bpo=20421]: Add a .version() method to SSL sockets exposing the actual protocol version in use.

bpo-19546 [https://bugs.python.org/issue?@action=redirect&bpo=19546]: configparser exceptions no longer expose implementation details. Chained KeyErrors are removed, which leads to cleaner tracebacks. Patch by Claudiu Popa.

bpo-22051 [https://bugs.python.org/issue?@action=redirect&bpo=22051]: turtledemo no longer reloads examples to re-run them. Initialization of variables and gui setup should be done in main(), which is called each time a demo is run, but not on import.

bpo-21933 [https://bugs.python.org/issue?@action=redirect&bpo=21933]: Turtledemo users can change the code font size with a menu selection or control(command) “-” or “+” or control-mousewheel. Original patch by Lita Cho.

bpo-21597 [https://bugs.python.org/issue?@action=redirect&bpo=21597]: The separator between the turtledemo text pane and the drawing canvas can now be grabbed and dragged with a mouse. The code text pane can be widened to easily view or copy the full width of the text. The canvas can be widened on small screens. Original patches by Jan Kanis and Lita Cho.

bpo-18132 [https://bugs.python.org/issue?@action=redirect&bpo=18132]: Turtledemo buttons no longer disappear when the window is shrunk. Original patches by Jan Kanis and Lita Cho.

bpo-22043 [https://bugs.python.org/issue?@action=redirect&bpo=22043]: time.monotonic() is now always available. threading.Lock.acquire(), threading.RLock.acquire() and socket operations now use a monotonic clock, instead of the system clock, when a timeout is used.

bpo-21527 [https://bugs.python.org/issue?@action=redirect&bpo=21527]: Add a default number of workers to ThreadPoolExecutor equal to 5 times the number of CPUs. Patch by Claudiu Popa.

bpo-22216 [https://bugs.python.org/issue?@action=redirect&bpo=22216]: smtplib now resets its state more completely after a quit. The most obvious consequence of the previous behavior was a STARTTLS failure during a connect/starttls/quit/connect/starttls sequence.

bpo-22098 [https://bugs.python.org/issue?@action=redirect&bpo=22098]: ctypes” BigEndianStructure and LittleEndianStructure now define an empty __slots__ so that subclasses don’t always get an instance dict. Patch by Claudiu Popa.

bpo-22185 [https://bugs.python.org/issue?@action=redirect&bpo=22185]: Fix an occasional RuntimeError in threading.Condition.wait() caused by mutation of the waiters queue without holding the lock. Patch by Doug Zongker.

bpo-22287 [https://bugs.python.org/issue?@action=redirect&bpo=22287]: On UNIX, _PyTime_gettimeofday() now uses clock_gettime(CLOCK_REALTIME) if available. As a side effect, Python now depends on the librt library on Solaris and on Linux (only with glibc older than 2.17).

bpo-22182 [https://bugs.python.org/issue?@action=redirect&bpo=22182]: Use e.args to unpack exceptions correctly in distutils.file_util.move_file. Patch by Claudiu Popa.

The webbrowser module now uses subprocess’s start_new_session=True rather than a potentially risky preexec_fn=os.setsid call.

bpo-22042 [https://bugs.python.org/issue?@action=redirect&bpo=22042]: signal.set_wakeup_fd(fd) now raises an exception if the file descriptor is in blocking mode.

bpo-16808 [https://bugs.python.org/issue?@action=redirect&bpo=16808]: inspect.stack() now returns a named tuple instead of a tuple. Patch by Daniel Shahaf.

bpo-22236 [https://bugs.python.org/issue?@action=redirect&bpo=22236]: Fixed Tkinter images copying operations in NoDefaultRoot mode.

bpo-2527 [https://bugs.python.org/issue?@action=redirect&bpo=2527]: Add a globals argument to timeit functions, in order to override the globals namespace in which the timed code is executed. Patch by Ben Roberts.

bpo-22118 [https://bugs.python.org/issue?@action=redirect&bpo=22118]: Switch urllib.parse to use RFC 3986 semantics for the resolution of relative URLs, rather than RFCs 1808 and 2396. Patch by Demian Brecht.

bpo-21549 [https://bugs.python.org/issue?@action=redirect&bpo=21549]: Added the «members» parameter to TarFile.list().

bpo-19628 [https://bugs.python.org/issue?@action=redirect&bpo=19628]: Allow compileall recursion depth to be specified with a -r option.

bpo-15696 [https://bugs.python.org/issue?@action=redirect&bpo=15696]: Add a __sizeof__ implementation for mmap objects on Windows.

bpo-22068 [https://bugs.python.org/issue?@action=redirect&bpo=22068]: Avoided reference loops with Variables and Fonts in Tkinter.

bpo-22165 [https://bugs.python.org/issue?@action=redirect&bpo=22165]: SimpleHTTPRequestHandler now supports undecodable file names.

bpo-15381 [https://bugs.python.org/issue?@action=redirect&bpo=15381]: Optimized line reading in io.BytesIO.

bpo-8797 [https://bugs.python.org/issue?@action=redirect&bpo=8797]: Raise HTTPError on failed Basic Authentication immediately. Initial patch by Sam Bull.

bpo-20729 [https://bugs.python.org/issue?@action=redirect&bpo=20729]: Restored the use of lazy iterkeys()/itervalues()/iteritems() in the mailbox module.

bpo-21448 [https://bugs.python.org/issue?@action=redirect&bpo=21448]: Changed FeedParser feed() to avoid O(N²) behavior when parsing long line. Original patch by Raymond Hettinger.

bpo-22184 [https://bugs.python.org/issue?@action=redirect&bpo=22184]: The functools LRU Cache decorator factory now gives an earlier and clearer error message when the user forgets the required parameters.

bpo-17923 [https://bugs.python.org/issue?@action=redirect&bpo=17923]: glob() patterns ending with a slash no longer match non-dirs on AIX. Based on patch by Delhallt.

bpo-21725 [https://bugs.python.org/issue?@action=redirect&bpo=21725]: Added support for RFC 6531 (SMTPUTF8) in smtpd.

bpo-22176 [https://bugs.python.org/issue?@action=redirect&bpo=22176]: Update the ctypes module’s libffi to v3.1. This release adds support for the Linux AArch64 and POWERPC ELF ABIv2 little endian architectures.

bpo-5411 [https://bugs.python.org/issue?@action=redirect&bpo=5411]: Added support for the «xztar» format in the shutil module.

bpo-21121 [https://bugs.python.org/issue?@action=redirect&bpo=21121]: Don’t force 3rd party C extensions to be built with -Werror=declaration-after-statement.

bpo-21975 [https://bugs.python.org/issue?@action=redirect&bpo=21975]: Fixed crash when using uninitialized sqlite3.Row (in particular when unpickling pickled sqlite3.Row). sqlite3.Row is now initialized in the __new__() method.

bpo-20170 [https://bugs.python.org/issue?@action=redirect&bpo=20170]: Convert posixmodule to use Argument Clinic.

bpo-21539 [https://bugs.python.org/issue?@action=redirect&bpo=21539]: Add an exists_ok argument to Pathlib.mkdir() to mimic mkdir -p and os.makedirs() functionality. When true, ignore FileExistsErrors. Patch by Berker Peksag.

bpo-22127 [https://bugs.python.org/issue?@action=redirect&bpo=22127]: Bypass IDNA for pure-ASCII host names in the socket module (in particular for numeric IPs).

bpo-21047 [https://bugs.python.org/issue?@action=redirect&bpo=21047]: set the default value for the convert_charrefs argument of HTMLParser to True. Patch by Berker Peksag.

Add an __all__ to html.entities.

bpo-15114 [https://bugs.python.org/issue?@action=redirect&bpo=15114]: the strict mode and argument of HTMLParser, HTMLParser.error, and the HTMLParserError exception have been removed.

bpo-22085 [https://bugs.python.org/issue?@action=redirect&bpo=22085]: Dropped support of Tk 8.3 in Tkinter.

bpo-21580 [https://bugs.python.org/issue?@action=redirect&bpo=21580]: Now Tkinter correctly handles bytes arguments passed to Tk. In particular this allows initializing images from binary data.

bpo-22003 [https://bugs.python.org/issue?@action=redirect&bpo=22003]: When initialized from a bytes object, io.BytesIO() now defers making a copy until it is mutated, improving performance and memory use on some use cases. Patch by David Wilson.

bpo-22018 [https://bugs.python.org/issue?@action=redirect&bpo=22018]: On Windows, signal.set_wakeup_fd() now also supports sockets. A side effect is that Python depends to the WinSock library.

bpo-22054 [https://bugs.python.org/issue?@action=redirect&bpo=22054]: Add os.get_blocking() and os.set_blocking() functions to get and set the blocking mode of a file descriptor (False if the O_NONBLOCK flag is set, True otherwise). These functions are not available on Windows.

bpo-17172 [https://bugs.python.org/issue?@action=redirect&bpo=17172]: Make turtledemo start as active on OS X even when run with subprocess. Patch by Lita Cho.

bpo-21704 [https://bugs.python.org/issue?@action=redirect&bpo=21704]: Fix build error for _multiprocessing when semaphores are not available. Patch by Arfrever Frehtes Taifersar Arahesis.

bpo-20173 [https://bugs.python.org/issue?@action=redirect&bpo=20173]: Convert sha1, sha256, sha512 and md5 to ArgumentClinic. Patch by Vajrasky Kok.

Fix repr(_socket.socket) on Windows 64-bit: don’t fail with OverflowError on closed socket. repr(socket.socket) already works fine.

bpo-22033 [https://bugs.python.org/issue?@action=redirect&bpo=22033]: Reprs of most Python implemented classes now contain actual class name instead of hardcoded one.

bpo-21947 [https://bugs.python.org/issue?@action=redirect&bpo=21947]: The dis module can now disassemble generator-iterator objects based on their gi_code attribute. Patch by Clement Rouault.

bpo-16133 [https://bugs.python.org/issue?@action=redirect&bpo=16133]: The asynchat.async_chat.handle_read() method now ignores BlockingIOError exceptions.

bpo-22044 [https://bugs.python.org/issue?@action=redirect&bpo=22044]: Fixed premature DECREF in call_tzinfo_method. Patch by Tom Flanagan.

bpo-19884 [https://bugs.python.org/issue?@action=redirect&bpo=19884]: readline: Disable the meta modifier key if stdout is not a terminal to not write the ANSI sequence "\033[1034h" into stdout. This sequence is used on some terminal (ex: TERM=xterm-256color») to enable support of 8 bit characters.

bpo-4350 [https://bugs.python.org/issue?@action=redirect&bpo=4350]: Removed a number of out-of-dated and non-working for a long time Tkinter methods.

bpo-6167 [https://bugs.python.org/issue?@action=redirect&bpo=6167]: Scrollbar.activate() now returns the name of active element if the argument is not specified. Scrollbar.set() now always accepts only 2 arguments.

bpo-15275 [https://bugs.python.org/issue?@action=redirect&bpo=15275]: Clean up and speed up the ntpath module.

bpo-21888 [https://bugs.python.org/issue?@action=redirect&bpo=21888]: plistlib’s load() and loads() now work if the fmt parameter is specified.

bpo-22032 [https://bugs.python.org/issue?@action=redirect&bpo=22032]: __qualname__ instead of __name__ is now always used to format fully qualified class names of Python implemented classes.

bpo-22031 [https://bugs.python.org/issue?@action=redirect&bpo=22031]: Reprs now always use hexadecimal format with the «0x» prefix when contain an id in form » at 0x…».

bpo-22018 [https://bugs.python.org/issue?@action=redirect&bpo=22018]: signal.set_wakeup_fd() now raises an OSError instead of a ValueError on fstat() failure.

bpo-21044 [https://bugs.python.org/issue?@action=redirect&bpo=21044]: tarfile.open() now handles fileobj with an integer “name” attribute. Based on patch by Antoine Pietri.

bpo-21966 [https://bugs.python.org/issue?@action=redirect&bpo=21966]: Respect -q command-line option when code module is ran.

bpo-19076 [https://bugs.python.org/issue?@action=redirect&bpo=19076]: Don’t pass the redundant “file” argument to self.error().

bpo-16382 [https://bugs.python.org/issue?@action=redirect&bpo=16382]: Improve exception message of warnings.warn() for bad category. Initial patch by Phil Elson.

bpo-21932 [https://bugs.python.org/issue?@action=redirect&bpo=21932]: os.read() now uses a Py_ssize_t() type instead of int for the size to support reading more than 2 GB at once. On Windows, the size is truncated to INT_MAX. As any call to os.read(), the OS may read less bytes than the number of requested bytes.

bpo-21942 [https://bugs.python.org/issue?@action=redirect&bpo=21942]: Fixed source file viewing in pydoc’s server mode on Windows.

bpo-11259 [https://bugs.python.org/issue?@action=redirect&bpo=11259]: asynchat.async_chat().set_terminator() now raises a ValueError if the number of received bytes is negative.

bpo-12523 [https://bugs.python.org/issue?@action=redirect&bpo=12523]: asynchat.async_chat.push() now raises a TypeError if it doesn’t get a bytes string

bpo-21707 [https://bugs.python.org/issue?@action=redirect&bpo=21707]: Add missing kwonlyargcount argument to ModuleFinder.replace_paths_in_code().

bpo-20639 [https://bugs.python.org/issue?@action=redirect&bpo=20639]: calling Path.with_suffix(“”) allows removing the suffix again. Patch by July Tikhonov.

bpo-21714 [https://bugs.python.org/issue?@action=redirect&bpo=21714]: Disallow the construction of invalid paths using Path.with_name(). Original patch by Antony Lee.

bpo-15014 [https://bugs.python.org/issue?@action=redirect&bpo=15014]: Added “auth” method to smtplib to make implementing auth mechanisms simpler, and used it internally in the login method.

bpo-21151 [https://bugs.python.org/issue?@action=redirect&bpo=21151]: Fixed a segfault in the winreg module when None is passed as a REG_BINARY value to SetValueEx. Patch by John Ehresman.

bpo-21090 [https://bugs.python.org/issue?@action=redirect&bpo=21090]: io.FileIO.readall() does not ignore I/O errors anymore. Before, it ignored I/O errors if at least the first C call read() succeed.

bpo-5800 [https://bugs.python.org/issue?@action=redirect&bpo=5800]: headers parameter of wsgiref.headers.Headers is now optional. Initial patch by Pablo Torres Navarrete and SilentGhost.

bpo-21781 [https://bugs.python.org/issue?@action=redirect&bpo=21781]: ssl.RAND_add() now supports strings longer than 2 GB.

bpo-21679 [https://bugs.python.org/issue?@action=redirect&bpo=21679]: Prevent extraneous fstat() calls during open(). Patch by Bohuslav Kabrda.

bpo-21863 [https://bugs.python.org/issue?@action=redirect&bpo=21863]: cProfile now displays the module name of C extension functions, in addition to their own name.

bpo-11453 [https://bugs.python.org/issue?@action=redirect&bpo=11453]: asyncore: emit a ResourceWarning when an unclosed file_wrapper object is destroyed. The destructor now closes the file if needed. The close() method can now be called twice: the second call does nothing.

bpo-21858 [https://bugs.python.org/issue?@action=redirect&bpo=21858]: Better handling of Python exceptions in the sqlite3 module.

bpo-21476 [https://bugs.python.org/issue?@action=redirect&bpo=21476]: Make sure the email.parser.BytesParser TextIOWrapper is discarded after parsing, so the input file isn’t unexpectedly closed.

bpo-20295 [https://bugs.python.org/issue?@action=redirect&bpo=20295]: imghdr now recognizes OpenEXR format images.

bpo-21729 [https://bugs.python.org/issue?@action=redirect&bpo=21729]: Used the «with» statement in the dbm.dumb module to ensure files closing. Patch by Claudiu Popa.

bpo-21491 [https://bugs.python.org/issue?@action=redirect&bpo=21491]: socketserver: Fix a race condition in child processes reaping.

bpo-21719 [https://bugs.python.org/issue?@action=redirect&bpo=21719]: Added the st_file_attributes field to os.stat_result on Windows.

bpo-21832 [https://bugs.python.org/issue?@action=redirect&bpo=21832]: Require named tuple inputs to be exact strings.

bpo-21722 [https://bugs.python.org/issue?@action=redirect&bpo=21722]: The distutils «upload» command now exits with a non-zero return code when uploading fails. Patch by Martin Dengler.

bpo-21723 [https://bugs.python.org/issue?@action=redirect&bpo=21723]: asyncio.Queue: support any type of number (ex: float) for the maximum size. Patch written by Vajrasky Kok.

bpo-21711 [https://bugs.python.org/issue?@action=redirect&bpo=21711]: support for «site-python» directories has now been removed from the site module (it was deprecated in 3.4).

bpo-17552 [https://bugs.python.org/issue?@action=redirect&bpo=17552]: new socket.sendfile() method allowing a file to be sent over a socket by using high-performance os.sendfile() on UNIX. Patch by Giampaolo Rodola”.

bpo-18039 [https://bugs.python.org/issue?@action=redirect&bpo=18039]: dbm.dump.open() now always creates a new database when the flag has the value “n”. Patch by Claudiu Popa.

bpo-21326 [https://bugs.python.org/issue?@action=redirect&bpo=21326]: Add a new is_closed() method to asyncio.BaseEventLoop. run_forever() and run_until_complete() methods of asyncio.BaseEventLoop now raise an exception if the event loop was closed.

bpo-21766 [https://bugs.python.org/issue?@action=redirect&bpo=21766]: Prevent a security hole in CGIHTTPServer by URL unquoting paths before checking for a CGI script at that path.

bpo-21310 [https://bugs.python.org/issue?@action=redirect&bpo=21310]: Fixed possible resource leak in failed open().

bpo-21256 [https://bugs.python.org/issue?@action=redirect&bpo=21256]: Printout of keyword args should be in deterministic order in a mock function call. This will help to write better doctests.

bpo-21677 [https://bugs.python.org/issue?@action=redirect&bpo=21677]: Fixed chaining nonnormalized exceptions in io close() methods.

bpo-11709 [https://bugs.python.org/issue?@action=redirect&bpo=11709]: Fix the pydoc.help function to not fail when sys.stdin is not a valid file.

bpo-21515 [https://bugs.python.org/issue?@action=redirect&bpo=21515]: tempfile.TemporaryFile now uses os.O_TMPFILE flag is available.

bpo-13223 [https://bugs.python.org/issue?@action=redirect&bpo=13223]: Fix pydoc.writedoc so that the HTML documentation for methods that use “self” in the example code is generated correctly.

bpo-21463 [https://bugs.python.org/issue?@action=redirect&bpo=21463]: In urllib.request, fix pruning of the FTP cache.

bpo-21618 [https://bugs.python.org/issue?@action=redirect&bpo=21618]: The subprocess module could fail to close open fds that were inherited by the calling process and already higher than POSIX resource limits would otherwise allow. On systems with a functioning /proc/self/fd or /dev/fd interface the max is now ignored and all fds are closed.

bpo-20383 [https://bugs.python.org/issue?@action=redirect&bpo=20383]: Introduce importlib.util.module_from_spec() as the preferred way to create a new module.

bpo-21552 [https://bugs.python.org/issue?@action=redirect&bpo=21552]: Fixed possible integer overflow of too long string lengths in the tkinter module on 64-bit platforms.

bpo-14315 [https://bugs.python.org/issue?@action=redirect&bpo=14315]: The zipfile module now ignores extra fields in the central directory that are too short to be parsed instead of letting a struct.unpack error bubble up as this «bad data» appears in many real world zip files in the wild and is ignored by other zip tools.

bpo-13742 [https://bugs.python.org/issue?@action=redirect&bpo=13742]: Added «key» and «reverse» parameters to heapq.merge(). (First draft of patch contributed by Simon Sapin.)

bpo-21402 [https://bugs.python.org/issue?@action=redirect&bpo=21402]: tkinter.ttk now works when default root window is not set.

bpo-3015 [https://bugs.python.org/issue?@action=redirect&bpo=3015]: _tkinter.create() now creates tkapp object with wantobject=1 by default.

bpo-10203 [https://bugs.python.org/issue?@action=redirect&bpo=10203]: sqlite3.Row now truly supports sequence protocol. In particular it supports reverse() and negative indices. Original patch by Claudiu Popa.

bpo-18807 [https://bugs.python.org/issue?@action=redirect&bpo=18807]: If copying (no symlinks) specified for a venv, then the python interpreter aliases (python, python3) are now created by copying rather than symlinking.

bpo-20197 [https://bugs.python.org/issue?@action=redirect&bpo=20197]: Added support for the WebP image type in the imghdr module. Patch by Fabrice Aneche and Claudiu Popa.

bpo-21513 [https://bugs.python.org/issue?@action=redirect&bpo=21513]: Speedup some properties of IP addresses (IPv4Address, IPv6Address) such as .is_private or .is_multicast.

bpo-21137 [https://bugs.python.org/issue?@action=redirect&bpo=21137]: Improve the repr for threading.Lock() and its variants by showing the «locked» or «unlocked» status. Patch by Berker Peksag.

bpo-21538 [https://bugs.python.org/issue?@action=redirect&bpo=21538]: The plistlib module now supports loading of binary plist files when reference or offset size is not a power of two.

bpo-21455 [https://bugs.python.org/issue?@action=redirect&bpo=21455]: Add a default backlog to socket.listen().

bpo-21525 [https://bugs.python.org/issue?@action=redirect&bpo=21525]: Most Tkinter methods which accepted tuples now accept lists too.

bpo-22166 [https://bugs.python.org/issue?@action=redirect&bpo=22166]: With the assistance of a new internal _codecs._forget_codec helping function, test_codecs now clears the encoding caches to avoid the appearance of a reference leak

bpo-22236 [https://bugs.python.org/issue?@action=redirect&bpo=22236]: Tkinter tests now don’t reuse default root window. New root window is created for every test class.

bpo-10744 [https://bugs.python.org/issue?@action=redirect&bpo=10744]: Fix PEP 3118 [https://www.python.org/dev/peps/pep-3118] format strings on ctypes objects with a nontrivial shape.

bpo-20826 [https://bugs.python.org/issue?@action=redirect&bpo=20826]: Optimize ipaddress.collapse_addresses().

bpo-21487 [https://bugs.python.org/issue?@action=redirect&bpo=21487]: Optimize ipaddress.summarize_address_range() and ipaddress.{IPv4Network,IPv6Network}.subnets().

bpo-21486 [https://bugs.python.org/issue?@action=redirect&bpo=21486]: Optimize parsing of netmasks in ipaddress.IPv4Network and ipaddress.IPv6Network.

bpo-13916 [https://bugs.python.org/issue?@action=redirect&bpo=13916]: Disallowed the surrogatepass error handler for non UTF-* encodings.

bpo-20998 [https://bugs.python.org/issue?@action=redirect&bpo=20998]: Fixed re.fullmatch() of repeated single character pattern with ignore case. Original patch by Matthew Barnett.

bpo-21075 [https://bugs.python.org/issue?@action=redirect&bpo=21075]: fileinput.FileInput now reads bytes from standard stream if binary mode is specified. Patch by Sam Kimbrel.

bpo-19775 [https://bugs.python.org/issue?@action=redirect&bpo=19775]: Add a samefile() method to pathlib Path objects. Initial patch by Vajrasky Kok.

bpo-21226 [https://bugs.python.org/issue?@action=redirect&bpo=21226]: Set up modules properly in PyImport_ExecCodeModuleObject (and friends).

bpo-21398 [https://bugs.python.org/issue?@action=redirect&bpo=21398]: Fix a unicode error in the pydoc pager when the documentation contains characters not encodable to the stdout encoding.

bpo-16531 [https://bugs.python.org/issue?@action=redirect&bpo=16531]: ipaddress.IPv4Network and ipaddress.IPv6Network now accept an (address, netmask) tuple argument, so as to easily construct network objects from existing addresses.

bpo-21156 [https://bugs.python.org/issue?@action=redirect&bpo=21156]: importlib.abc.InspectLoader.source_to_code() is now a staticmethod.

bpo-21424 [https://bugs.python.org/issue?@action=redirect&bpo=21424]: Simplified and optimized heaqp.nlargest() and nmsmallest() to make fewer tuple comparisons.

bpo-21396 [https://bugs.python.org/issue?@action=redirect&bpo=21396]: Fix TextIOWrapper(…, write_through=True) to not force a flush() on the underlying binary stream. Patch by akira.

bpo-18314 [https://bugs.python.org/issue?@action=redirect&bpo=18314]: Unlink now removes junctions on Windows. Patch by Kim Gräsman

bpo-21088 [https://bugs.python.org/issue?@action=redirect&bpo=21088]: Bugfix for curses.window.addch() regression in 3.4.0. In porting to Argument Clinic, the first two arguments were reversed.

bpo-21407 [https://bugs.python.org/issue?@action=redirect&bpo=21407]: _decimal: The module now supports function signatures.

bpo-10650 [https://bugs.python.org/issue?@action=redirect&bpo=10650]: Remove the non-standard “watchexp” parameter from the Decimal.quantize() method in the Python version. It had never been present in the C version.

bpo-21469 [https://bugs.python.org/issue?@action=redirect&bpo=21469]: Reduced the risk of false positives in robotparser by checking to make sure that robots.txt has been read or does not exist prior to returning True in can_fetch().

bpo-19414 [https://bugs.python.org/issue?@action=redirect&bpo=19414]: Have the OrderedDict mark deleted links as unusable. This gives an early failure if the link is deleted during iteration.

bpo-21421 [https://bugs.python.org/issue?@action=redirect&bpo=21421]: Add __slots__ to the MappingViews ABC. Patch by Josh Rosenberg.

bpo-21101 [https://bugs.python.org/issue?@action=redirect&bpo=21101]: Eliminate double hashing in the C speed-up code for collections.Counter().

bpo-21321 [https://bugs.python.org/issue?@action=redirect&bpo=21321]: itertools.islice() now releases the reference to the source iterator when the slice is exhausted. Patch by Anton Afanasyev.

bpo-21057 [https://bugs.python.org/issue?@action=redirect&bpo=21057]: TextIOWrapper now allows the underlying binary stream’s read() or read1() method to return an arbitrary bytes-like object (such as a memoryview). Patch by Nikolaus Rath.

bpo-20951 [https://bugs.python.org/issue?@action=redirect&bpo=20951]: SSLSocket.send() now raises either SSLWantReadError or SSLWantWriteError on a non-blocking socket if the operation would block. Previously, it would return 0. Patch by Nikolaus Rath.

bpo-13248 [https://bugs.python.org/issue?@action=redirect&bpo=13248]: removed previously deprecated asyncore.dispatcher __getattr__ cheap inheritance hack.

bpo-9815 [https://bugs.python.org/issue?@action=redirect&bpo=9815]: assertRaises now tries to clear references to local variables in the exception’s traceback.

bpo-19940 [https://bugs.python.org/issue?@action=redirect&bpo=19940]: ssl.cert_time_to_seconds() now interprets the given time string in the UTC timezone (as specified in RFC 5280), not the local timezone.

bpo-13204 [https://bugs.python.org/issue?@action=redirect&bpo=13204]: Calling sys.flags.__new__ would crash the interpreter, now it raises a TypeError.

bpo-19385 [https://bugs.python.org/issue?@action=redirect&bpo=19385]: Make operations on a closed dbm.dumb database always raise the same exception.

bpo-21207 [https://bugs.python.org/issue?@action=redirect&bpo=21207]: Detect when the os.urandom cached fd has been closed or replaced, and open it anew.

bpo-21291 [https://bugs.python.org/issue?@action=redirect&bpo=21291]: subprocess’s Popen.wait() is now thread safe so that multiple threads may be calling wait() or poll() on a Popen instance at the same time without losing the Popen.returncode value.

bpo-21127 [https://bugs.python.org/issue?@action=redirect&bpo=21127]: Path objects can now be instantiated from str subclass instances (such as numpy.str_).

bpo-15002 [https://bugs.python.org/issue?@action=redirect&bpo=15002]: urllib.response object to use _TemporaryFileWrapper (and _TemporaryFileCloser) facility. Provides a better way to handle file descriptor close. Patch contributed by Christian Theune.

bpo-12220 [https://bugs.python.org/issue?@action=redirect&bpo=12220]: mindom now raises a custom ValueError indicating it doesn’t support spaces in URIs instead of letting a “split” ValueError bubble up.

bpo-21068 [https://bugs.python.org/issue?@action=redirect&bpo=21068]: The ssl.PROTOCOL* constants are now enum members.

bpo-21276 [https://bugs.python.org/issue?@action=redirect&bpo=21276]: posixmodule: Don’t define USE_XATTRS on KFreeBSD and the Hurd.

bpo-21262 [https://bugs.python.org/issue?@action=redirect&bpo=21262]: New method assert_not_called for Mock. It raises AssertionError if the mock has been called.

bpo-21238 [https://bugs.python.org/issue?@action=redirect&bpo=21238]: New keyword argument unsafe to Mock. It raises AttributeError incase of an attribute startswith assert or assret.

bpo-20896 [https://bugs.python.org/issue?@action=redirect&bpo=20896]: ssl.get_server_certificate() now uses PROTOCOL_SSLv23, not PROTOCOL_SSLv3, for maximum compatibility.

bpo-21239 [https://bugs.python.org/issue?@action=redirect&bpo=21239]: patch.stopall() didn’t work deterministically when the same name was patched more than once.

bpo-21203 [https://bugs.python.org/issue?@action=redirect&bpo=21203]: Updated fileConfig and dictConfig to remove inconsistencies. Thanks to Jure Koren for the patch.

bpo-21222 [https://bugs.python.org/issue?@action=redirect&bpo=21222]: Passing name keyword argument to mock.create_autospec now works.

bpo-21197 [https://bugs.python.org/issue?@action=redirect&bpo=21197]: Add lib64 -> lib symlink in venvs on 64-bit non-OS X POSIX.

bpo-17498 [https://bugs.python.org/issue?@action=redirect&bpo=17498]: Some SMTP servers disconnect after certain errors, violating strict RFC conformance. Instead of losing the error code when we issue the subsequent RSET, smtplib now returns the error code and defers raising the SMTPServerDisconnected error until the next command is issued.

bpo-17826 [https://bugs.python.org/issue?@action=redirect&bpo=17826]: setting an iterable side_effect on a mock function created by create_autospec now works. Patch by Kushal Das.

bpo-7776 [https://bugs.python.org/issue?@action=redirect&bpo=7776]: Fix Host: header and reconnection when using http.client.HTTPConnection.set_tunnel(). Patch by Nikolaus Rath.

bpo-20968 [https://bugs.python.org/issue?@action=redirect&bpo=20968]: unittest.mock.MagicMock now supports division. Patch by Johannes Baiter.

bpo-21529 [https://bugs.python.org/issue?@action=redirect&bpo=21529]: Fix arbitrary memory access in JSONDecoder.raw_decode with a negative second parameter. Bug reported by Guido Vranken. (See also: CVE-2014-4616)

bpo-21169 [https://bugs.python.org/issue?@action=redirect&bpo=21169]: getpass now handles non-ascii characters that the input stream encoding cannot encode by re-encoding using the replace error handler.

bpo-21171 [https://bugs.python.org/issue?@action=redirect&bpo=21171]: Fixed undocumented filter API of the rot13 codec. Patch by Berker Peksag.

bpo-20539 [https://bugs.python.org/issue?@action=redirect&bpo=20539]: Improved math.factorial error message for large positive inputs and changed exception type (OverflowError -> ValueError) for large negative inputs.

bpo-21172 [https://bugs.python.org/issue?@action=redirect&bpo=21172]: isinstance check relaxed from dict to collections.Mapping.

bpo-21155 [https://bugs.python.org/issue?@action=redirect&bpo=21155]: asyncio.EventLoop.create_unix_server() now raises a ValueError if path and sock are specified at the same time.

bpo-21136 [https://bugs.python.org/issue?@action=redirect&bpo=21136]: Avoid unnecessary normalization of Fractions resulting from power and other operations. Patch by Raymond Hettinger.

bpo-17621 [https://bugs.python.org/issue?@action=redirect&bpo=17621]: Introduce importlib.util.LazyLoader.

bpo-21076 [https://bugs.python.org/issue?@action=redirect&bpo=21076]: signal module constants were turned into enums. Patch by Giampaolo Rodola”.

bpo-20636 [https://bugs.python.org/issue?@action=redirect&bpo=20636]: Improved the repr of Tkinter widgets.

bpo-19505 [https://bugs.python.org/issue?@action=redirect&bpo=19505]: The items, keys, and values views of OrderedDict now support reverse iteration using reversed().

bpo-21149 [https://bugs.python.org/issue?@action=redirect&bpo=21149]: Improved thread-safety in logging cleanup during interpreter shutdown. Thanks to Devin Jeanpierre for the patch.

bpo-21058 [https://bugs.python.org/issue?@action=redirect&bpo=21058]: Fix a leak of file descriptor in tempfile.NamedTemporaryFile(), close the file descriptor if io.open() fails

bpo-21200 [https://bugs.python.org/issue?@action=redirect&bpo=21200]: Return None from pkgutil.get_loader() when __spec__ is missing.

bpo-21013 [https://bugs.python.org/issue?@action=redirect&bpo=21013]: Enhance ssl.create_default_context() when used for server side sockets to provide better security by default.

bpo-20145 [https://bugs.python.org/issue?@action=redirect&bpo=20145]: assertRaisesRegex and assertWarnsRegex now raise a TypeError if the second argument is not a string or compiled regex.

bpo-20633 [https://bugs.python.org/issue?@action=redirect&bpo=20633]: Replace relative import by absolute import.

bpo-20980 [https://bugs.python.org/issue?@action=redirect&bpo=20980]: Stop wrapping exception when using ThreadPool.

bpo-21082 [https://bugs.python.org/issue?@action=redirect&bpo=21082]: In os.makedirs, do not set the process-wide umask. Note this changes behavior of makedirs when exist_ok=True.

bpo-20990 [https://bugs.python.org/issue?@action=redirect&bpo=20990]: Fix issues found by pyflakes for multiprocessing.

bpo-21015 [https://bugs.python.org/issue?@action=redirect&bpo=21015]: SSL contexts will now automatically select an elliptic curve for ECDH key exchange on OpenSSL 1.0.2 and later, and otherwise default to «prime256v1».

bpo-21000 [https://bugs.python.org/issue?@action=redirect&bpo=21000]: Improve the command-line interface of json.tool.

bpo-20995 [https://bugs.python.org/issue?@action=redirect&bpo=20995]: Enhance default ciphers used by the ssl module to enable better security and prioritize perfect forward secrecy.

bpo-20884 [https://bugs.python.org/issue?@action=redirect&bpo=20884]: Don’t assume that __file__ is defined on importlib.__init__.

bpo-21499 [https://bugs.python.org/issue?@action=redirect&bpo=21499]: Ignore __builtins__ in several test_importlib.test_api tests.

bpo-20627 [https://bugs.python.org/issue?@action=redirect&bpo=20627]: xmlrpc.client.ServerProxy is now a context manager.

bpo-19165 [https://bugs.python.org/issue?@action=redirect&bpo=19165]: The formatter module now raises DeprecationWarning instead of PendingDeprecationWarning.

bpo-13936 [https://bugs.python.org/issue?@action=redirect&bpo=13936]: Remove the ability of datetime.time instances to be considered false in boolean contexts.

bpo-18931 [https://bugs.python.org/issue?@action=redirect&bpo=18931]: selectors module now supports /dev/poll on Solaris. Patch by Giampaolo Rodola”.

bpo-19977 [https://bugs.python.org/issue?@action=redirect&bpo=19977]: When the LC_TYPE locale is the POSIX locale (C locale), sys.stdin and sys.stdout are now using the surrogateescape error handler, instead of the strict error handler.

bpo-20574 [https://bugs.python.org/issue?@action=redirect&bpo=20574]: Implement incremental decoder for cp65001 code (Windows code page 65001, Microsoft UTF-8).

bpo-20879 [https://bugs.python.org/issue?@action=redirect&bpo=20879]: Delay the initialization of encoding and decoding tables for base32, ascii85 and base85 codecs in the base64 module, and delay the initialization of the unquote_to_bytes() table of the urllib.parse module, to not waste memory if these modules are not used.

bpo-19157 [https://bugs.python.org/issue?@action=redirect&bpo=19157]: Include the broadcast address in the usuable hosts for IPv6 in ipaddress.

bpo-11599 [https://bugs.python.org/issue?@action=redirect&bpo=11599]: When an external command (e.g. compiler) fails, distutils now prints out the whole command line (instead of just the command name) if the environment variable DISTUTILS_DEBUG is set.

bpo-4931 [https://bugs.python.org/issue?@action=redirect&bpo=4931]: distutils should not produce unhelpful «error: None» messages anymore. distutils.util.grok_environment_error is kept but doc-deprecated.

bpo-20875 [https://bugs.python.org/issue?@action=redirect&bpo=20875]: Prevent possible gzip «“read” is not defined» NameError. Patch by Claudiu Popa.

bpo-11558 [https://bugs.python.org/issue?@action=redirect&bpo=11558]: email.message.Message.attach now returns a more useful error message if attach is called on a message for which is_multipart is False.

bpo-20283 [https://bugs.python.org/issue?@action=redirect&bpo=20283]: RE pattern methods now accept the string keyword parameters as documented. The pattern and source keyword parameters are left as deprecated aliases.

bpo-20778 [https://bugs.python.org/issue?@action=redirect&bpo=20778]: Fix modulefinder to work with bytecode-only modules.

bpo-20791 [https://bugs.python.org/issue?@action=redirect&bpo=20791]: copy.copy() now doesn’t make a copy when the input is a bytes object. Initial patch by Peter Otten.

bpo-19748 [https://bugs.python.org/issue?@action=redirect&bpo=19748]: On AIX, time.mktime() now raises an OverflowError for year outsize range [1902; 2037].

bpo-19573 [https://bugs.python.org/issue?@action=redirect&bpo=19573]: inspect.signature: Use enum for parameter kind constants.

bpo-20726 [https://bugs.python.org/issue?@action=redirect&bpo=20726]: inspect.signature: Make Signature and Parameter picklable.

bpo-17373 [https://bugs.python.org/issue?@action=redirect&bpo=17373]: Add inspect.Signature.from_callable method.

bpo-20378 [https://bugs.python.org/issue?@action=redirect&bpo=20378]: Improve repr of inspect.Signature and inspect.Parameter.

bpo-20816 [https://bugs.python.org/issue?@action=redirect&bpo=20816]: Fix inspect.getcallargs() to raise correct TypeError for missing keyword-only arguments. Patch by Jeremiah Lowin.

bpo-20817 [https://bugs.python.org/issue?@action=redirect&bpo=20817]: Fix inspect.getcallargs() to fail correctly if more than 3 arguments are missing. Patch by Jeremiah Lowin.

bpo-6676 [https://bugs.python.org/issue?@action=redirect&bpo=6676]: Ensure a meaningful exception is raised when attempting to parse more than one XML document per pyexpat xmlparser instance. (Original patches by Hirokazu Yamamoto and Amaury Forgeot d’Arc, with suggested wording by David Gutteridge)

bpo-21117 [https://bugs.python.org/issue?@action=redirect&bpo=21117]: Fix inspect.signature to better support functools.partial. Due to the specifics of functools.partial implementation, positional-or-keyword arguments passed as keyword arguments become keyword-only.

bpo-20334 [https://bugs.python.org/issue?@action=redirect&bpo=20334]: inspect.Signature and inspect.Parameter are now hashable. Thanks to Antony Lee for bug reports and suggestions.

bpo-15916 [https://bugs.python.org/issue?@action=redirect&bpo=15916]: doctest.DocTestSuite returns an empty unittest.TestSuite instead of raising ValueError if it finds no tests

bpo-21209 [https://bugs.python.org/issue?@action=redirect&bpo=21209]: Fix asyncio.tasks.CoroWrapper to workaround a bug in yield-from implementation in CPythons prior to 3.4.1.

asyncio: Add gi_{frame,running,code} properties to CoroWrapper (upstream bpo-163 [https://bugs.python.org/issue?@action=redirect&bpo=163]).

bpo-21311 [https://bugs.python.org/issue?@action=redirect&bpo=21311]: Avoid exception in _osx_support with non-standard compiler configurations. Patch by John Szakmeister.

bpo-11571 [https://bugs.python.org/issue?@action=redirect&bpo=11571]: Ensure that the turtle window becomes the topmost window when launched on OS X.

bpo-21801 [https://bugs.python.org/issue?@action=redirect&bpo=21801]: Validate that __signature__ is None or an instance of Signature.

bpo-21923 [https://bugs.python.org/issue?@action=redirect&bpo=21923]: Prevent AttributeError in distutils.sysconfig.customize_compiler due to possible uninitialized _config_vars.

bpo-21323 [https://bugs.python.org/issue?@action=redirect&bpo=21323]: Fix http.server to again handle scripts in CGI subdirectories, broken by the fix for security bpo-19435 [https://bugs.python.org/issue?@action=redirect&bpo=19435]. Patch by Zach Byrne.

bpo-22733 [https://bugs.python.org/issue?@action=redirect&bpo=22733]: Fix ffi_prep_args not zero-extending argument values correctly on 64-bit Windows.

bpo-23302 [https://bugs.python.org/issue?@action=redirect&bpo=23302]: Default to TCP_NODELAY=1 upon establishing an HTTPConnection. Removed use of hard-coded MSS as it’s an optimization that’s no longer needed with Nagle disabled.

IDLE

bpo-20577 [https://bugs.python.org/issue?@action=redirect&bpo=20577]: Configuration of the max line length for the FormatParagraph extension has been moved from the General tab of the Idle preferences dialog to the FormatParagraph tab of the Config Extensions dialog. Patch by Tal Einat.

bpo-16893 [https://bugs.python.org/issue?@action=redirect&bpo=16893]: Update Idle doc chapter to match current Idle and add new information.

bpo-3068 [https://bugs.python.org/issue?@action=redirect&bpo=3068]: Add Idle extension configuration dialog to Options menu. Changes are written to HOME/.idlerc/config-extensions.cfg. Original patch by Tal Einat.

bpo-16233 [https://bugs.python.org/issue?@action=redirect&bpo=16233]: A module browser (File : Class Browser, Alt+C) requires an editor window with a filename. When Class Browser is requested otherwise, from a shell, output window, or “Untitled” editor, Idle no longer displays an error box. It now pops up an Open Module box (Alt+M). If a valid name is entered and a module is opened, a corresponding browser is also opened.

bpo-4832 [https://bugs.python.org/issue?@action=redirect&bpo=4832]: Save As to type Python files automatically adds .py to the name you enter (even if your system does not display it). Some systems automatically add .txt when type is Text files.

bpo-21986 [https://bugs.python.org/issue?@action=redirect&bpo=21986]: Code objects are not normally pickled by the pickle module. To match this, they are no longer pickled when running under Idle.

bpo-17390 [https://bugs.python.org/issue?@action=redirect&bpo=17390]: Adjust Editor window title; remove “Python”, move version to end.

bpo-14105 [https://bugs.python.org/issue?@action=redirect&bpo=14105]: Idle debugger breakpoints no longer disappear when inserting or deleting lines.

bpo-17172 [https://bugs.python.org/issue?@action=redirect&bpo=17172]: Turtledemo can now be run from Idle. Currently, the entry is on the Help menu, but it may move to Run. Patch by Ramchandra Apt and Lita Cho.

bpo-21765 [https://bugs.python.org/issue?@action=redirect&bpo=21765]: Add support for non-ascii identifiers to HyperParser.

bpo-21940 [https://bugs.python.org/issue?@action=redirect&bpo=21940]: Add unittest for WidgetRedirector. Initial patch by Saimadhav Heblikar.

bpo-18592 [https://bugs.python.org/issue?@action=redirect&bpo=18592]: Add unittest for SearchDialogBase. Patch by Phil Webster.

bpo-21694 [https://bugs.python.org/issue?@action=redirect&bpo=21694]: Add unittest for ParenMatch. Patch by Saimadhav Heblikar.

bpo-21686 [https://bugs.python.org/issue?@action=redirect&bpo=21686]: add unittest for HyperParser. Original patch by Saimadhav Heblikar.

bpo-12387 [https://bugs.python.org/issue?@action=redirect&bpo=12387]: Add missing upper(lower)case versions of default Windows key bindings for Idle so Caps Lock does not disable them. Patch by Roger Serwy.

bpo-21695 [https://bugs.python.org/issue?@action=redirect&bpo=21695]: Closing a Find-in-files output window while the search is still in progress no longer closes Idle.

bpo-18910 [https://bugs.python.org/issue?@action=redirect&bpo=18910]: Add unittest for textView. Patch by Phil Webster.

bpo-18292 [https://bugs.python.org/issue?@action=redirect&bpo=18292]: Add unittest for AutoExpand. Patch by Saihadhav Heblikar.

bpo-18409 [https://bugs.python.org/issue?@action=redirect&bpo=18409]: Add unittest for AutoComplete. Patch by Phil Webster.

bpo-21477 [https://bugs.python.org/issue?@action=redirect&bpo=21477]: htest.py - Improve framework, complete set of tests. Patches by Saimadhav Heblikar

bpo-18104 [https://bugs.python.org/issue?@action=redirect&bpo=18104]: Add idlelib/idle_test/htest.py with a few sample tests to begin consolidating and improving human-validated tests of Idle. Change other files as needed to work with htest. Running the module as __main__ runs all tests.

bpo-21139 [https://bugs.python.org/issue?@action=redirect&bpo=21139]: Change default paragraph width to 72, the PEP 8 [https://www.python.org/dev/peps/pep-0008] recommendation.

bpo-21284 [https://bugs.python.org/issue?@action=redirect&bpo=21284]: Paragraph reformat test passes after user changes reformat width.

bpo-17654 [https://bugs.python.org/issue?@action=redirect&bpo=17654]: Ensure IDLE menus are customized properly on OS X for non-framework builds and for all variants of Tk.

bpo-23180 [https://bugs.python.org/issue?@action=redirect&bpo=23180]: Rename IDLE «Windows» menu item to «Window». Patch by Al Sweigart.

Build

bpo-15506 [https://bugs.python.org/issue?@action=redirect&bpo=15506]: Use standard PKG_PROG_PKG_CONFIG autoconf macro in the configure script.

bpo-22935 [https://bugs.python.org/issue?@action=redirect&bpo=22935]: Allow the ssl module to be compiled if openssl doesn’t support SSL 3.

bpo-22592 [https://bugs.python.org/issue?@action=redirect&bpo=22592]: Drop support of the Borland C compiler to build Python. The distutils module still supports it to build extensions.

bpo-22591 [https://bugs.python.org/issue?@action=redirect&bpo=22591]: Drop support of MS-DOS, especially of the DJGPP compiler (MS-DOS port of GCC).

bpo-16537 [https://bugs.python.org/issue?@action=redirect&bpo=16537]: Check whether self.extensions is empty in setup.py. Patch by Jonathan Hosmer.

bpo-22359 [https://bugs.python.org/issue?@action=redirect&bpo=22359]: Remove incorrect uses of recursive make. Patch by Jonas Wagner.

bpo-21958 [https://bugs.python.org/issue?@action=redirect&bpo=21958]: Define HAVE_ROUND when building with Visual Studio 2013 and above. Patch by Zachary Turner.

bpo-18093 [https://bugs.python.org/issue?@action=redirect&bpo=18093]: the programs that embed the CPython runtime are now in a separate «Programs» directory, rather than being kept in the Modules directory.

bpo-15759 [https://bugs.python.org/issue?@action=redirect&bpo=15759]: «make suspicious», «make linkcheck» and «make doctest» in Doc/ now display special message when and only when there are failures.

bpo-21141 [https://bugs.python.org/issue?@action=redirect&bpo=21141]: The Windows build process no longer attempts to find Perl, instead relying on OpenSSL source being configured and ready to build. The PCbuild\build_ssl.py script has been re-written and re-named to PCbuild\prepare_ssl.py, and takes care of configuring OpenSSL source for both 32 and 64 bit platforms. OpenSSL sources obtained from svn.python.org will always be pre-configured and ready to build.

bpo-21037 [https://bugs.python.org/issue?@action=redirect&bpo=21037]: Add a build option to enable AddressSanitizer support.

bpo-19962 [https://bugs.python.org/issue?@action=redirect&bpo=19962]: The Windows build process now creates «python.bat» in the root of the source tree, which passes all arguments through to the most recently built interpreter.

bpo-21285 [https://bugs.python.org/issue?@action=redirect&bpo=21285]: Refactor and fix curses configure check to always search in a ncursesw directory.

bpo-15234 [https://bugs.python.org/issue?@action=redirect&bpo=15234]: For BerkeleyDB and Sqlite, only add the found library and include directories if they aren’t already being searched. This avoids an explicit runtime library dependency.

bpo-17861 [https://bugs.python.org/issue?@action=redirect&bpo=17861]: Tools/scripts/generate_opcode_h.py automatically regenerates Include/opcode.h from Lib/opcode.py if the latter gets any change.

bpo-20644 [https://bugs.python.org/issue?@action=redirect&bpo=20644]: OS X installer build support for documentation build changes in 3.4.1: assume externally supplied sphinx-build is available in /usr/bin.

bpo-20022 [https://bugs.python.org/issue?@action=redirect&bpo=20022]: Eliminate use of deprecated bundlebuilder in OS X builds.

bpo-15968 [https://bugs.python.org/issue?@action=redirect&bpo=15968]: Incorporated Tcl, Tk, and Tix builds into the Windows build solution.

bpo-17095 [https://bugs.python.org/issue?@action=redirect&bpo=17095]: Fix Modules/Setup shared support.

bpo-21811 [https://bugs.python.org/issue?@action=redirect&bpo=21811]: Anticipated fixes to support OS X versions > 10.9.

bpo-21166 [https://bugs.python.org/issue?@action=redirect&bpo=21166]: Prevent possible segfaults and other random failures of python –generate-posix-vars in pybuilddir.txt build target.

bpo-18096 [https://bugs.python.org/issue?@action=redirect&bpo=18096]: Fix library order returned by python-config.

bpo-17219 [https://bugs.python.org/issue?@action=redirect&bpo=17219]: Add library build dir for Python extension cross-builds.

bpo-22919 [https://bugs.python.org/issue?@action=redirect&bpo=22919]: Windows build updated to support VC 14.0 (Visual Studio 2015), which will be used for the official release.

bpo-21236 [https://bugs.python.org/issue?@action=redirect&bpo=21236]: Build _msi.pyd with cabinet.lib instead of fci.lib

bpo-17128 [https://bugs.python.org/issue?@action=redirect&bpo=17128]: Use private version of OpenSSL for OS X 10.5+ installer.

C API

bpo-14203 [https://bugs.python.org/issue?@action=redirect&bpo=14203]: Remove obsolete support for view==NULL in PyBuffer_FillInfo(), bytearray_getbuffer(), bytesiobuf_getbuffer() and array_buffer_getbuf(). All functions now raise BufferError in that case.

bpo-22445 [https://bugs.python.org/issue?@action=redirect&bpo=22445]: PyBuffer_IsContiguous() now implements precise contiguity tests, compatible with NumPy’s NPY_RELAXED_STRIDES_CHECKING compilation flag. Previously the function reported false negatives for corner cases.

bpo-22079 [https://bugs.python.org/issue?@action=redirect&bpo=22079]: PyType_Ready() now checks that statically allocated type has no dynamically allocated bases.

bpo-22453 [https://bugs.python.org/issue?@action=redirect&bpo=22453]: Removed non-documented macro PyObject_REPR().

bpo-18395 [https://bugs.python.org/issue?@action=redirect&bpo=18395]: Rename _Py_char2wchar() to Py_DecodeLocale(), rename _Py_wchar2char() to Py_EncodeLocale(), and document these functions.

bpo-21233 [https://bugs.python.org/issue?@action=redirect&bpo=21233]: Add new C functions: PyMem_RawCalloc(), PyMem_Calloc(), PyObject_Calloc(), _PyObject_GC_Calloc(). bytes(int) is now using calloc() instead of malloc() for large objects which is faster and use less memory.

bpo-20942 [https://bugs.python.org/issue?@action=redirect&bpo=20942]: PyImport_ImportFrozenModuleObject() no longer sets __file__ to match what importlib does; this affects _frozen_importlib as well as any module loaded using imp.init_frozen().

Documentation

bpo-19548 [https://bugs.python.org/issue?@action=redirect&bpo=19548]: Update the codecs module documentation to better cover the distinction between text encodings and other codecs, together with other clarifications. Patch by Martin Panter.

bpo-22394 [https://bugs.python.org/issue?@action=redirect&bpo=22394]: Doc/Makefile now supports make venv PYTHON=../python to create a venv for generating the documentation, e.g., make html PYTHON=venv/bin/python3.

bpo-21514 [https://bugs.python.org/issue?@action=redirect&bpo=21514]: The documentation of the json module now refers to new JSON RFC 7159 instead of obsoleted RFC 4627.

bpo-21777 [https://bugs.python.org/issue?@action=redirect&bpo=21777]: The binary sequence methods on bytes and bytearray are now documented explicitly, rather than assuming users will be able to derive the expected behaviour from the behaviour of the corresponding str methods.

bpo-6916 [https://bugs.python.org/issue?@action=redirect&bpo=6916]: undocument deprecated asynchat.fifo class.

bpo-17386 [https://bugs.python.org/issue?@action=redirect&bpo=17386]: Expanded functionality of the Doc/make.bat script to make it much more comparable to Doc/Makefile.

bpo-21312 [https://bugs.python.org/issue?@action=redirect&bpo=21312]: Update the thread_foobar.h template file to include newer threading APIs. Patch by Jack McCracken.

bpo-21043 [https://bugs.python.org/issue?@action=redirect&bpo=21043]: Remove the recommendation for specific CA organizations and to mention the ability to load the OS certificates.

bpo-20765 [https://bugs.python.org/issue?@action=redirect&bpo=20765]: Add missing documentation for PurePath.with_name() and PurePath.with_suffix().

bpo-19407 [https://bugs.python.org/issue?@action=redirect&bpo=19407]: New package installation and distribution guides based on the Python Packaging Authority tools. Existing guides have been retained as legacy links from the distutils docs, as they still contain some required reference material for tool developers that isn’t recorded anywhere else.

bpo-19697 [https://bugs.python.org/issue?@action=redirect&bpo=19697]: Document cases where __main__.__spec__ is None.

Tests

bpo-18982 [https://bugs.python.org/issue?@action=redirect&bpo=18982]: Add tests for CLI of the calendar module.

bpo-19548 [https://bugs.python.org/issue?@action=redirect&bpo=19548]: Added some additional checks to test_codecs to ensure that statements in the updated documentation remain accurate. Patch by Martin Panter.

bpo-22838 [https://bugs.python.org/issue?@action=redirect&bpo=22838]: All test_re tests now work with unittest test discovery.

bpo-22173 [https://bugs.python.org/issue?@action=redirect&bpo=22173]: Update lib2to3 tests to use unittest test discovery.

bpo-16000 [https://bugs.python.org/issue?@action=redirect&bpo=16000]: Convert test_curses to use unittest.

bpo-21456 [https://bugs.python.org/issue?@action=redirect&bpo=21456]: Skip two tests in test_urllib2net.py if _ssl module not present. Patch by Remi Pointel.

bpo-20746 [https://bugs.python.org/issue?@action=redirect&bpo=20746]: Fix test_pdb to run in refleak mode (-R). Patch by Xavier de Gaye.

bpo-22060 [https://bugs.python.org/issue?@action=redirect&bpo=22060]: test_ctypes has been somewhat cleaned up and simplified; it now uses unittest test discovery to find its tests.

bpo-22104 [https://bugs.python.org/issue?@action=redirect&bpo=22104]: regrtest.py no longer holds a reference to the suite of tests loaded from test modules that don’t define test_main().

bpo-22111 [https://bugs.python.org/issue?@action=redirect&bpo=22111]: Assorted cleanups in test_imaplib. Patch by Milan Oberkirch.

bpo-22002 [https://bugs.python.org/issue?@action=redirect&bpo=22002]: Added load_package_tests function to test.support and used it to implement/augment test discovery in test_asyncio, test_email, test_importlib, test_json, and test_tools.

bpo-21976 [https://bugs.python.org/issue?@action=redirect&bpo=21976]: Fix test_ssl to accept LibreSSL version strings. Thanks to William Orr.

bpo-21918 [https://bugs.python.org/issue?@action=redirect&bpo=21918]: Converted test_tools from a module to a package containing separate test files for each tested script.

bpo-9554 [https://bugs.python.org/issue?@action=redirect&bpo=9554]: Use modern unittest features in test_argparse. Initial patch by Denver Coneybeare and Radu Voicilas.

bpo-20155 [https://bugs.python.org/issue?@action=redirect&bpo=20155]: Changed HTTP method names in failing tests in test_httpservers so that packet filtering software (specifically Windows Base Filtering Engine) does not interfere with the transaction semantics expected by the tests.

bpo-19493 [https://bugs.python.org/issue?@action=redirect&bpo=19493]: Refactored the ctypes test package to skip tests explicitly rather than silently.

bpo-18492 [https://bugs.python.org/issue?@action=redirect&bpo=18492]: All resources are now allowed when tests are not run by regrtest.py.

bpo-21634 [https://bugs.python.org/issue?@action=redirect&bpo=21634]: Fix pystone micro-benchmark: use floor division instead of true division to benchmark integers instead of floating point numbers. Set pystone version to 1.2. Patch written by Lennart Regebro.

bpo-21605 [https://bugs.python.org/issue?@action=redirect&bpo=21605]: Added tests for Tkinter images.

bpo-21493 [https://bugs.python.org/issue?@action=redirect&bpo=21493]: Added test for ntpath.expanduser(). Original patch by Claudiu Popa.

bpo-19925 [https://bugs.python.org/issue?@action=redirect&bpo=19925]: Added tests for the spwd module. Original patch by Vajrasky Kok.

bpo-21522 [https://bugs.python.org/issue?@action=redirect&bpo=21522]: Added Tkinter tests for Listbox.itemconfigure(), PanedWindow.paneconfigure(), and Menu.entryconfigure().

bpo-17756 [https://bugs.python.org/issue?@action=redirect&bpo=17756]: Fix test_code test when run from the installed location.

bpo-17752 [https://bugs.python.org/issue?@action=redirect&bpo=17752]: Fix distutils tests when run from the installed location.

bpo-18604 [https://bugs.python.org/issue?@action=redirect&bpo=18604]: Consolidated checks for GUI availability. All platforms now at least check whether Tk can be instantiated when the GUI resource is requested.

bpo-21275 [https://bugs.python.org/issue?@action=redirect&bpo=21275]: Fix a socket test on KFreeBSD.

bpo-21223 [https://bugs.python.org/issue?@action=redirect&bpo=21223]: Pass test_site/test_startup_imports when some of the extensions are built as builtins.

bpo-20635 [https://bugs.python.org/issue?@action=redirect&bpo=20635]: Added tests for Tk geometry managers.

Add test case for freeze.

bpo-20743 [https://bugs.python.org/issue?@action=redirect&bpo=20743]: Fix a reference leak in test_tcl.

bpo-21097 [https://bugs.python.org/issue?@action=redirect&bpo=21097]: Move test_namespace_pkgs into test_importlib.

bpo-21503 [https://bugs.python.org/issue?@action=redirect&bpo=21503]: Use test_both() consistently in test_importlib.

bpo-20939 [https://bugs.python.org/issue?@action=redirect&bpo=20939]: Avoid various network test failures due to new redirect of http://www.python.org/ to https://www.python.org: use http://www.example.com instead.

bpo-20668 [https://bugs.python.org/issue?@action=redirect&bpo=20668]: asyncio tests no longer rely on tests.txt file. (Patch by Vajrasky Kok)

bpo-21093 [https://bugs.python.org/issue?@action=redirect&bpo=21093]: Prevent failures of ctypes test_macholib on OS X if a copy of libz exists in $HOME/lib or /usr/local/lib.

bpo-22770 [https://bugs.python.org/issue?@action=redirect&bpo=22770]: Prevent some Tk segfaults on OS X when running gui tests.

bpo-23211 [https://bugs.python.org/issue?@action=redirect&bpo=23211]: Workaround test_logging failure on some OS X 10.6 systems.

bpo-23345 [https://bugs.python.org/issue?@action=redirect&bpo=23345]: Prevent test_ssl failures with large OpenSSL patch level values (like 0.9.8zc).

Tools/Demos

bpo-22314 [https://bugs.python.org/issue?@action=redirect&bpo=22314]: pydoc now works when the LINES environment variable is set.

bpo-22615 [https://bugs.python.org/issue?@action=redirect&bpo=22615]: Argument Clinic now supports the «type» argument for the int converter. This permits using the int converter with enums and typedefs.

bpo-20076 [https://bugs.python.org/issue?@action=redirect&bpo=20076]: The makelocalealias.py script no longer ignores UTF-8 mapping.

bpo-20079 [https://bugs.python.org/issue?@action=redirect&bpo=20079]: The makelocalealias.py script now can parse the SUPPORTED file from glibc sources and supports command line options for source paths.

bpo-22201 [https://bugs.python.org/issue?@action=redirect&bpo=22201]: Command-line interface of the zipfile module now correctly extracts ZIP files with directory entries. Patch by Ryan Wilson.

bpo-22120 [https://bugs.python.org/issue?@action=redirect&bpo=22120]: For functions using an unsigned integer return converter, Argument Clinic now generates a cast to that type for the comparison to -1 in the generated code. (This suppresses a compilation warning.)

bpo-18974 [https://bugs.python.org/issue?@action=redirect&bpo=18974]: Tools/scripts/diff.py now uses argparse instead of optparse.

bpo-21906 [https://bugs.python.org/issue?@action=redirect&bpo=21906]: Make Tools/scripts/md5sum.py work in Python 3. Patch by Zachary Ware.

bpo-21629 [https://bugs.python.org/issue?@action=redirect&bpo=21629]: Fix Argument Clinic’s «–converters» feature.

Add support for yield from to 2to3.

Add support for the PEP 465 [https://www.python.org/dev/peps/pep-0465] matrix multiplication operator to 2to3.

bpo-16047 [https://bugs.python.org/issue?@action=redirect&bpo=16047]: Fix module exception list and __file__ handling in freeze. Patch by Meador Inge.

bpo-11824 [https://bugs.python.org/issue?@action=redirect&bpo=11824]: Consider ABI tags in freeze. Patch by Meador Inge.

bpo-20535 [https://bugs.python.org/issue?@action=redirect&bpo=20535]: PYTHONWARNING no longer affects the run_tests.py script. Patch by Arfrever Frehtes Taifersar Arahesis.

Windows

bpo-23260 [https://bugs.python.org/issue?@action=redirect&bpo=23260]: Update Windows installer

The bundled version of Tcl/Tk has been updated to 8.6.3. The most visible result of this change is the addition of new native file dialogs when running on Windows Vista or newer. See Tcl/Tk’s TIP 432 for more information. Also, this version of Tcl/Tk includes support for Windows 10.

bpo-17896 [https://bugs.python.org/issue?@action=redirect&bpo=17896]: The Windows build scripts now expect external library sources to be in PCbuild\..\externals rather than PCbuild\..\...

bpo-17717 [https://bugs.python.org/issue?@action=redirect&bpo=17717]: The Windows build scripts now use a copy of NASM pulled from svn.python.org to build OpenSSL.

bpo-21907 [https://bugs.python.org/issue?@action=redirect&bpo=21907]: Improved the batch scripts provided for building Python.

bpo-22644 [https://bugs.python.org/issue?@action=redirect&bpo=22644]: The bundled version of OpenSSL has been updated to 1.0.1j.

bpo-10747 [https://bugs.python.org/issue?@action=redirect&bpo=10747]: Use versioned labels in the Windows start menu. Patch by Olive Kilburn.

bpo-22980 [https://bugs.python.org/issue?@action=redirect&bpo=22980]: .pyd files with a version and platform tag (for example, «.cp35-win32.pyd») will now be loaded in preference to those without tags.

(For information about older versions, consult the HISTORY file.)

Tutorial de Python

Python es un lenguaje de programación potente y fácil de aprender. Tiene estructuras de datos de alto nivel eficientes y un simple pero efectivo sistema de programación orientado a objetos. La elegante sintaxis de Python y su tipado dinámico, junto a su naturaleza interpretada lo convierten en un lenguaje ideal para scripting y desarrollo rápido de aplicaciones en muchas áreas, para la mayoría de plataformas.

El intérprete de Python y la extensiva librería estándar se encuentran disponibles libremente en código fuente y forma binaria para la mayoría de plataformas desde la Web de Python, https://www.python.org/, y se pueden distribuir libremente. El mismo sitio contiene distribuciones y direcciones a muchos módulos de Python de terceras partes, programas, herramientas y adicionalmente documentación.

El intérprete de Python es fácilmente extensible con funciones y tipos de datos implementados en C o C++ (o otros lenguajes que permitan ser llamados desde C). Python también es apropiado como un lenguaje para extender aplicaciones modificables.

Este tutorial introduce al lector informalmente a los conceptos básicos y las funcionalidades del lenguaje de programación Python y a su sistema. Ayuda a tener un interprete de Python accesible para una experiencia práctica, todos los ejemplos son auto-contenidos, permitiendo utilizar el tutorial sin conexión.

Para una descripción de los objetos estándar y de los módulos, ver La Biblioteca Estándar de Python. Referencia del Lenguaje Python dónde se ofrece una definición más formal del lenguaje. Para escribir extensiones en C o C++, leer Ampliación e incrustación del intérprete de Python y Manual de referencia de la API en C de Python. Existen diversos libros que cubren Python en detalle.

Este tutorial no pretende ser comprensible y cubrir todas las funcionalidades, o incluso ni las más utilizadas. Pretende introducir muchas de las funcionalidades más notables y dar una idea del estilo y el tipo de lenguaje. Después de leerlo podrás leer y escribir módulos y programas en Python y estarás listo para aprender sobre varias librerías y módulos descritos en La Biblioteca Estándar de Python.

Es interesante leer el Glosario.

1. Abriendo el apetito

2. Usando el intérprete de Python

2.1. Invocando al intérprete

2.1.1. Paso de argumentos

2.1.2. Modo interactivo

2.2. El intérprete y su entorno

2.2.1. Codificación del código fuente

3. Una introducción informal a Python

3.1. Usando Python como una calculadora

3.1.1. Números

3.1.2. Cadenas de caracteres

3.1.3. Listas

3.2. Primeros pasos hacia la programación

4. Más herramientas para control de flujo

4.1. La sentencia if

4.2. La sentencia for

4.3. La función range()

4.4. Las sentencias break, continue, y else en bucles

4.5. La sentencia pass

4.6. Definiendo funciones

4.7. Más sobre definición de funciones

4.7.1. Argumentos con valores por omisión

4.7.2. Palabras claves como argumentos

4.7.3. Parámetros especiales

4.7.3.1. Argumentos posicionales o de palabras claves

4.7.3.2. Parámetros únicamente posicionales

4.7.3.3. Argumentos únicamente de palabras clave

4.7.3.4. Ejemplos de Funciones

4.7.3.5. Resumen

4.7.4. Listas de argumentos arbitrarios

4.7.5. Desempaquetando una lista de argumentos

4.7.6. Expresiones lambda

4.7.7. Cadenas de texto de documentación

4.7.8. Anotación de funciones

4.8. Intermezzo: Estilo de codificación

5. Estructuras de datos

5.1. Más sobre listas

5.1.1. Usando listas como pilas

5.1.2. Usando listas como colas

5.1.3. Comprensión de listas

5.1.4. Listas por comprensión anidadas

5.2. La instrucción del

5.3. Tuplas y secuencias

5.4. Conjuntos

5.5. Diccionarios

5.6. Técnicas de iteración

5.7. Más acerca de condiciones

5.8. Comparando secuencias y otros tipos

6. Módulos

6.1. Más sobre los módulos

6.1.1. Ejecutando módulos como scripts

6.1.2. El camino de búsqueda de los módulos

6.1.3. Archivos «compilados» de Python

6.2. Módulos estándar

6.3. La función dir()

6.4. Paquetes

6.4.1. Importando * desde un paquete

6.4.2. Referencias internas en paquetes

6.4.3. Paquetes en múltiples directorios

7. Entrada y salida

7.1. Formateo elegante de la salida

7.1.1. Formatear cadenas literales

7.1.2. El método format() de cadenas

7.1.3. Formateo manual de cadenas

7.1.4. Viejo formateo de cadenas

7.2. Leyendo y escribiendo archivos

7.2.1. Métodos de los objetos Archivo

7.2.2. Guardar datos estructurados con json

8. Errores y excepciones

8.1. Errores de sintaxis

8.2. Excepciones

8.3. Gestionando excepciones

8.4. Lanzando excepciones

8.5. Encadenamiento de excepciones

8.6. Excepciones definidas por el usuario

8.7. Definiendo acciones de limpieza

8.8. Acciones predefinidas de limpieza

9. Clases

9.1. Unas palabras sobre nombres y objetos

9.2. Ámbitos y espacios de nombres en Python

9.2.1. Ejemplo de ámbitos y espacios de nombre

9.3. Un primer vistazo a las clases

9.3.1. Sintaxis de definición de clases

9.3.2. Objetos clase

9.3.3. Objetos instancia

9.3.4. Objetos método

9.3.5. Variables de clase y de instancia

9.4. Algunas observaciones

9.5. Herencia

9.5.1. Herencia múltiple

9.6. Variables privadas

9.7. Cambalache

9.8. Iteradores

9.9. Generadores

9.10. Expresiones generadoras

10. Pequeño paseo por la Biblioteca Estándar

10.1. Interfaz al sistema operativo

10.2. Comodines de archivos

10.3. Argumentos de linea de órdenes

10.4. Redirigir la salida de error y finalización del programa

10.5. Coincidencia en patrones de cadenas

10.6. Matemática

10.7. Acceso a Internet

10.8. Fechas y tiempos

10.9. Compresión de datos

10.10. Medición de rendimiento

10.11. Control de calidad

10.12. Las pilas incluidas

11. Pequeño paseo por la Biblioteca Estándar— Parte II

11.1. Formato de salida

11.2. Plantillas

11.3. Trabajar con registros estructurados conteniendo datos binarios

11.4. Multi-hilos

11.5. Registrando

11.6. Referencias débiles

11.7. Herramientas para trabajar con listas

11.8. Aritmética de punto flotante decimal

12. Entornos Virtuales y Paquetes

12.1. Introducción

12.2. Creando Entornos Virtuales

12.3. Manejando paquetes con pip

13. ¿Y ahora qué?

14. Edición de entrada interactiva y sustitución de historial

14.1. Autocompletado con tab e historial de edición

14.2. Alternativas al intérprete interactivo

15. Aritmética de Punto Flotante: Problemas y Limitaciones

15.1. Error de Representación

16. Apéndice

16.1. Modo interactivo

16.1.1. Manejo de errores

16.1.2. Programas ejecutables de Python

16.1.3. El archivo de inicio interactivo

16.1.4. Los módulos de customización

1. Abriendo el apetito

Si trabajas mucho con ordenadores, en algún momento encontrarás que hay alguna tarea que quieres automatizar. Por ejemplo, quizás quieres buscar y remplazar un texto en muchos ficheros o renombrar y reordenar un montón de imágenes de forma complicada. Quizás lo que quieres es escribir una pequeña base de datos personalizada, una interfaz gráfica o un juego simple.

Si eres un desarrollador profesional, quizás quieres trabajar con varias librerías de C/C++/Java pero encuentras el ciclo de escribir/compilar/probar/recompilar bastante lento. Quizás estás escribiendo una serie de pruebas para éstas librerías y te parece tedioso escribir el código de pruebas. O quizás has escrito un programa que puede utilizar un lenguaje como extensión y no quieres diseñar e implementar un lenguaje entero para tu aplicación.

Python es justo el lenguaje para ti.

You could write a Unix shell script or Windows batch files for some of these tasks, but shell scripts are best at moving around files and changing text data, not well-suited for GUI applications or games. You could write a C/C++/Java program, but it can take a lot of development time to get even a first-draft program. Python is simpler to use, available on Windows, macOS, and Unix operating systems, and will help you get the job done more quickly.

Python es fácil de utilizar siendo un lenguaje de programación real ofreciendo mucha más estructura y soporte para programas grandes que la que ofrecen shell scripts o ficheros batch. Por otro lado, Python también ofrece mayor comprobación de errores que C y siendo un lenguaje de muy alto nivel tiene tipos de datos de alto nivel incorporados como listas flexibles y diccionarios. Debido a sus tipos de datos más generales, Python es aplicable a más dominios que Awk o Perl, aunque hay muchas cosas que son tan sencillas en Python como en esos lenguajes.

Python te permite dividir tu programa en módulos que pueden reutilizarse en otros programas de Python. Tiene una gran colección de módulos estándar que puedes utilizar como la base de tus programas o como ejemplos para empezar a aprender Python. Algunos de estos módulos proporcionan cosas como entrada/salida de ficheros, llamadas a sistema, sockets e incluso interfaces a herramientas de interfaz gráfica como Tk.

Python es un lenguaje interpretado, lo cual puede ahorrarte mucho tiempo durante el desarrollo ya que no es necesario compilar ni enlazar. El intérprete puede usarse interactivamente, lo que facilita experimentar con características del lenguaje, escribir programas desechables o probar funciones cuando se hace desarrollo de programas de abajo hacia arriba. Es también una calculadora de escritorio práctica.

Python permite escribir programas compactos y legibles. Los programas en Python son típicamente más cortos que sus programas equivalentes en C, C++ o Java por varios motivos:

los tipos de datos de alto nivel permiten expresar operaciones complejas en una sola instrucción;

la agrupación de instrucciones se hace mediante indentación en vez de llaves de apertura y cierre;

no es necesario declarar variables ni argumentos.

Python es extensible: si ya sabes programar en C es fácil añadir nuevas funciones o módulos al intérprete, ya sea para realizar operaciones críticas a velocidad máxima, o para enlazar programas de Python con bibliotecas que tal vez sólo estén disponibles de forma binaria (por ejemplo bibliotecas gráficas específicas de un fabricante). Una vez estés realmente entusiasmado, puedes enlazar el intérprete Python en una aplicación hecha en C y usarlo como lenguaje de extensión o de comando para esa aplicación.

Por cierto, el lenguaje recibe su nombre del programa de televisión de la BBC «Monty Python’s Flying Circus» y no tiene nada que ver con reptiles. Hacer referencias sobre Monty Python en la documentación no sólo esta permitido, ¡sino que también está bien visto!

Ahora que estás emocionado con Python, querrás verlo en más detalle. Como la mejor forma de aprender un lenguaje es usarlo, el tutorial te invita a que juegues con el intérprete de Python a medida que vas leyendo.

En el próximo capítulo se explicará la mecánica de uso del intérprete. Esta es información bastante mundana, pero es esencial para poder probar los ejemplos que aparecerán más adelante.

El resto del tutorial introduce varias características del lenguaje y el sistema Python a través de ejemplos, empezando con expresiones, instrucciones y tipos de datos simples, pasando por funciones y módulos, y finalmente tocando conceptos avanzados como excepciones y clases definidas por el usuario.

2. Usando el intérprete de Python

2.1. Invocando al intérprete

El intérprete de Python generalmente se instala como /usr/local/bin/python3.9 en aquellas máquinas donde está disponible; poner /usr/local/bin en la ruta de búsqueda de su shell de Unix hace posible iniciarlo escribiendo el comando:

python3.9

en el terminal 1. Ya que la elección del directorio dónde vivirá el intérprete es una opción del proceso de instalación, puede estar en otros lugares; consulta a tu experto Python local o administrador de sistemas. (Por ejemplo, /usr/local/python es una alternativa popular).

En máquinas Windows en las que haya instalado Python desde Microsoft Store, el comando python3.9 estará disponible. Si tiene instalado py.exe launcher, puede usar el comando py. Consulte Excurso: configurar variables de entorno para conocer otras formas de iniciar Python.

Se puede salir del intérprete con estado de salida cero ingresando el carácter de fin de archivo (Control-D en Unix, Control-Z en Windows). Si eso no funciona, puedes salir del intérprete escribiendo el comando: quit().

Las características para edición de líneas del intérprete incluyen edición interactiva, sustitución de historial y completado de código en sistemas que soportan GNU Readline [https://tiswww.case.edu/php/chet/readline/rltop.html] librería. Quizás la forma más rápida para comprobar si las características de edición se encuentran disponibles es escribir Control-P en el primer prompt de Python que aparezca. Si se escucha un sonido, tienes edición de línea de comandos; ver Apéndice Edición de entrada interactiva y sustitución de historial para una introducción a las teclas. Si no parece que ocurra nada, o si se muestra ^P, estas características no están disponibles; solo vas a poder usar la tecla de retroceso (backspace) para borrar los caracteres de la línea actual.

El intérprete funciona de manera similar al shell de Unix: cuando se le llama con una entrada estándar conectada a un terminal, lee y ejecuta comandos de manera interactiva; cuando se le llama con un argumento de nombre de archivo o con un archivo como entrada estándar, lee y ejecuta un script desde ese archivo.

Una segunda forma de iniciar el intérprete es python -c comando [arg] ..., que ejecuta las sentencias en comando, similar a la opción de shell -c . Como las sentencias de Python a menudo contienen espacios u otros caracteres que son especiales para el shell, generalmente se recomienda citar comando con comillas simples.

Algunos módulos de Python también son útiles como scripts. Estos pueden invocarse utilizando python -m module [arg] ..., que ejecuta el archivo fuente para module como si se hubiera escrito el nombre completo en la línea de comandos.

Cuando se usa un script, a veces es útil poder ejecutar el script y luego ingresar al modo interactivo. Esto se puede hacer pasando la -i antes del nombre del script.

Todas las opciones de la línea de comandos se describen en Línea de comandos y entorno.

2.1.1. Paso de argumentos

Cuando son conocidos por el intérprete, el nombre del script y los argumentos adicionales se convierten a una lista de cadenas de texto asignada a la variable argv del módulo sys. Puedes acceder a esta lista haciendo import sys. La longitud de la lista es al menos uno; cuando no se utiliza ningún script o argumento, sys.argv[0] es una cadena vacía. Cuando se pasa el nombre del script con '-' (lo que significa la entrada estándar), sys.argv[0] vale '-'. Cuando se usa -c comando, sys.argv[0] vale '-c'. Cuando se usa -m módulo, sys.argv[0] contiene el valor del nombre completo del módulo. Las opciones encontradas después de -c comand o -m módulo no son consumidas por el procesador de opciones de Python pero de todas formas se almacenan en sys.argv para ser manejadas por el comando o módulo.

2.1.2. Modo interactivo

Cuando se leen los comandos desde un terminal, se dice que el intérprete está en modo interactivo. En este modo, espera el siguiente comando con el prompt primario, generalmente tres signos de mayor que (>>>); para las líneas de continuación, aparece el prompt secundario, por defecto tres puntos (...). El intérprete imprime un mensaje de bienvenida que indica su número de versión y un aviso de copyright antes de imprimir el primer prompt primario:

$ python3.9
Python 3.9 (default, June 4 2019, 09:25:04)
[GCC 4.8.2] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>

Las líneas de continuación son necesarias cuando se ingresa una construcción multilínea. Como ejemplo, echa un vistazo a la sentencia if:

>>> the_world_is_flat = True
>>> if the_world_is_flat:
...     print("Be careful not to fall off!")
...
Be careful not to fall off!

Para más información sobre el modo interactivo, ver Modo interactivo.

2.2. El intérprete y su entorno

2.2.1. Codificación del código fuente

De forma predeterminada, los archivos fuente de Python se tratan como codificados en UTF-8. En esa codificación, los caracteres de la mayoría de los idiomas del mundo se pueden usar simultáneamente en literales, identificadores y comentarios, aunque la biblioteca estándar solo usa caracteres ASCII para los identificadores, una convención que debería seguir cualquier código que sea portable.Para mostrar todos estos caracteres correctamente, tu editor debe reconocer que el archivo es UTF-8, y debe usar una fuente que admita todos los caracteres del archivo.

Para declarar una codificación que no sea la predeterminada, se debe agregar una línea de comentario especial como la primera línea del archivo. La sintaxis es la siguiente:

# -*- coding: encoding -*-

donde codificación es uno de los codecs soportados por Python.

Por ejemplo, para declarar que se utilizará la codificación de Windows-1252, la primera línea del archivo de código fuente debe ser:

# -*- coding: cp1252 -*-

Una excepción a la regla de primera línea es cuando el código fuente comienza con una línea UNIX «shebang» line. En ese caso, la declaración de codificación debe agregarse como la segunda línea del archivo. Por ejemplo:

#!/usr/bin/env python3
# -*- coding: cp1252 -*-

Notas al pie

1

En Unix, el intérprete de Python 3.x no está instalado por defecto con el ejecutable llamado python, por lo que no entra en conflicto con un ejecutable de Python 2.x instalado simultáneamente.

3. Una introducción informal a Python

En los siguientes ejemplos, la entrada y la salida se distinguen por la presencia o ausencia de prompts (>>> y …): para repetir el ejemplo, escribe todo después del prompt, cuando aparece; las líneas que no comienzan con un prompt son emitidas desde el intérprete. Ten en cuenta que un prompt secundario solo en una linea de ejemplo significa que debes escribir una línea en blanco. Esto se utiliza para finalizar un comando multilínea.

You can toggle the display of prompts and output by clicking on >>> in the upper-right corner of an example box. If you hide the prompts and output for an example, then you can easily copy and paste the input lines into your interpreter.

Muchos de los ejemplos de este manual, incluso aquellos ingresados en el prompt interactivo, incluyen comentarios. Los comentarios en Python comienzan con el carácter numeral, #, y se extienden hasta el final visible de la línea. Un comentario quizás aparezca al comienzo de la línea o seguido de espacios en blanco o código, pero no dentro de una cadena de caracteres. Un carácter numeral dentro de una cadena de caracteres es sólo un carácter numeral. Ya que los comentarios son para aclarar código y no son interpretados por Python, pueden omitirse cuando se escriben los ejemplos.

Algunos ejemplos:

# this is the first comment
spam = 1  # and this is the second comment
          # ... and now a third!
text = "# This is not a comment because it's inside quotes."

3.1. Usando Python como una calculadora

Probemos algunos comandos simples de Python. Inicia el intérprete y espere el prompt primario, >>>. (No debería tardar mucho.)

3.1.1. Números

El intérprete puede utilizarse como una simple calculadora; puedes introducir una expresión y este escribirá los valores. La sintaxis es sencilla: los operadores +, -, * y /``funcionan como en la mayoría de los lenguajes (por ejemplo, Pascal o C); los paréntesis (``()) pueden ser usados para agrupar. Por ejemplo:

>>> 2 + 2
4
>>> 50 - 5*6
20
>>> (50 - 5*6) / 4
5.0
>>> 8 / 5  # division always returns a floating point number
1.6

Los números enteros (ej. 2, 4, 20) tienen tipo int, los que tienen una parte fraccionaria (por ejemplo 5.0, 1.6) tiene el tipo float. Vamos a ver más acerca de los tipos numéricos más adelante en el tutorial.

La división (/) siempre retorna un punto flotante. Para hacer floor division y obtener un resultado entero (descartando cualquier resultado fraccionario) puede usarse el operador //; para calcular el resto puedes usar %:

>>> 17 / 3  # classic division returns a float
5.666666666666667
>>>
>>> 17 // 3  # floor division discards the fractional part
5
>>> 17 % 3  # the % operator returns the remainder of the division
2
>>> 5 * 3 + 2  # floored quotient * divisor + remainder
17

Con Python, es posible usar el operador ** para calcular potencias 1:

>>> 5 ** 2  # 5 squared
25
>>> 2 ** 7  # 2 to the power of 7
128

El signo igual (=) se usa para asignar un valor a una variable. Ningún resultado se mostrará antes del siguiente prompt interactivo:

>>> width = 20
>>> height = 5 * 9
>>> width * height
900

Si una variable no está «definida» (no se le ha asignado un valor), al intentar usarla dará un error:

>>> n  # try to access an undefined variable
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'n' is not defined

Hay soporte completo de punto flotante; operadores con operando mezclados convertirán los enteros a punto flotante:

>>> 4 * 3.75 - 1
14.0

En el modo interactivo, la última expresión impresa se asigna a la variable _. Esto significa que cuando se está utilizando Python como calculadora, es más fácil seguir calculando, por ejemplo:

>>> tax = 12.5 / 100
>>> price = 100.50
>>> price * tax
12.5625
>>> price + _
113.0625
>>> round(_, 2)
113.06

Esta variable debe ser tratada como de sólo lectura por el usuario. No le asignes explícitamente un valor; crearás una variable local independiente con el mismo nombre enmascarando la variable con el comportamiento mágico.

Además de int y float, Python admite otros tipos de números, como Decimal y Fraction. Python también tiene soporte incorporado para complex numbers, y usa el sufijo j o J para indicar la parte imaginaria (por ejemplo, 3+5j).

3.1.2. Cadenas de caracteres

Además de números, Python puede manipular cadenas de texto, las cuales pueden ser expresadas de distintas formas. Pueden estar encerradas en comillas simples ('...') o dobles ("...") con el mismo resultado 2. \ puede ser usado para escapar comillas:

>>> 'spam eggs'  # single quotes
'spam eggs'
>>> 'doesn\'t'  # use \' to escape the single quote...
"doesn't"
>>> "doesn't"  # ...or use double quotes instead
"doesn't"
>>> '"Yes," they said.'
'"Yes," they said.'
>>> "\"Yes,\" they said."
'"Yes," they said.'
>>> '"Isn\'t," they said.'
'"Isn\'t," they said.'

En el intérprete interactivo, la salida de caracteres está encerrada en comillas y los caracteres especiales se escapan con barras invertidas. Aunque esto a veces se vea diferente de la entrada (las comillas que encierran pueden cambiar), las dos cadenas son equivalentes. La cadena se encierra en comillas dobles si la cadena contiene una comilla simple y ninguna doble, de lo contrario es encerrada en comillas simples. La función print() produce una salida más legible, omitiendo las comillas que la encierran e imprimiendo caracteres especiales y escapados:

>>> '"Isn\'t," they said.'
'"Isn\'t," they said.'
>>> print('"Isn\'t," they said.')
"Isn't," they said.
>>> s = 'First line.\nSecond line.'  # \n means newline
>>> s  # without print(), \n is included in the output
'First line.\nSecond line.'
>>> print(s)  # with print(), \n produces a new line
First line.
Second line.

Si no quieres que los caracteres precedidos por \ se interpreten como caracteres especiales, puedes usar cadenas sin formato agregando una r antes de la primera comilla:

>>> print('C:\some\name')  # here \n means newline!
C:\some
ame
>>> print(r'C:\some\name')  # note the r before the quote
C:\some\name

Las cadenas de texto literales pueden contener múltiples líneas. Una forma es usar triples comillas: """...""" o '''...'''. Los fin de línea son incluidos automáticamente, pero es posible prevenir esto agregando una \ al final de la línea. Por ejemplo:

print("""\
Usage: thingy [OPTIONS]
     -h                        Display this usage message
     -H hostname               Hostname to connect to
""")

produce la siguiente salida (tened en cuenta que la línea inicial no está incluida):

Usage: thingy [OPTIONS]
     -h                        Display this usage message
     -H hostname               Hostname to connect to

Las cadenas se pueden concatenar (pegar juntas) con el operador + y se pueden repetir con *:

>>> # 3 times 'un', followed by 'ium'
>>> 3 * 'un' + 'ium'
'unununium'

Dos o más cadenas literales (es decir, las encerradas entre comillas) una al lado de la otra se concatenan automáticamente.

>>> 'Py' 'thon'
'Python'

Esta característica es particularmente útil cuando quieres dividir cadenas largas:

>>> text = ('Put several strings within parentheses '
...         'to have them joined together.')
>>> text
'Put several strings within parentheses to have them joined together.'

Esto solo funciona con dos literales, no con variables ni expresiones:

>>> prefix = 'Py'
>>> prefix 'thon'  # can't concatenate a variable and a string literal
  File "<stdin>", line 1
    prefix 'thon'
                ^
SyntaxError: invalid syntax
>>> ('un' * 3) 'ium'
  File "<stdin>", line 1
    ('un' * 3) 'ium'
                   ^
SyntaxError: invalid syntax

Si quieres concatenar variables o una variable y un literal, usa +:

>>> prefix + 'thon'
'Python'

Las cadenas de texto se pueden indexar (subíndices), el primer carácter de la cadena tiene el índice 0. No hay un tipo de dato diferente para los caracteres; un carácter es simplemente una cadena de longitud uno:

>>> word = 'Python'
>>> word[0]  # character in position 0
'P'
>>> word[5]  # character in position 5
'n'

Los índices quizás sean números negativos, para empezar a contar desde la derecha:

>>> word[-1]  # last character
'n'
>>> word[-2]  # second-last character
'o'
>>> word[-6]
'P'

Nota que -0 es lo mismo que 0, los índice negativos comienzan desde -1.

Además de los índices, las rebanadas también están soportadas. Mientras que los índices se utilizar para obtener caracteres individuales, las rebanadas te permiten obtener partes de las cadenas de texto:

>>> word[0:2]  # characters from position 0 (included) to 2 (excluded)
'Py'
>>> word[2:5]  # characters from position 2 (included) to 5 (excluded)
'tho'

Los índices de las rebanadas tienen valores por defecto útiles; el valor por defecto para el primer índice es cero, el valor por defecto para el segundo índice es la longitud de la cadena a rebanar.

>>> word[:2]   # character from the beginning to position 2 (excluded)
'Py'
>>> word[4:]   # characters from position 4 (included) to the end
'on'
>>> word[-2:]  # characters from the second-last (included) to the end
'on'

Nota cómo el inicio siempre se incluye y el final siempre se excluye. Esto asegura que s[:i] + s[i:] siempre sea igual a s:

>>> word[:2] + word[2:]
'Python'
>>> word[:4] + word[4:]
'Python'

Una forma de recordar cómo funcionan las rebanadas es pensar que los índices apuntan entre caracteres, con el borde izquierdo del primer carácter numerado 0. Luego, el punto derecho del último carácter de una cadena de n caracteres tiene un índice n, por ejemplo

 +---+---+---+---+---+---+
 | P | y | t | h | o | n |
 +---+---+---+---+---+---+
 0   1   2   3   4   5   6
-6  -5  -4  -3  -2  -1

La primera fila de números da la posición de los índices 0…6 en la cadena; La segunda fila da los correspondientes indices negativos. La rebanada desde i hasta j consta de todos los caracteres entre los bordes etiquetados i y j, respectivamente.

Para índices no negativos, la longitud de la rebanada es la diferencia de los índices, si ambos están dentro de los límites. Por ejemplo, la longitud de word[1:3] es 2.

Intentar usar un índice que es muy grande resultará en un error:

>>> word[42]  # the word only has 6 characters
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
IndexError: string index out of range

Sin embargo, los índices de rebanadas fuera de rango se manejan satisfactoriamente cuando se usan para rebanar:

>>> word[4:42]
'on'
>>> word[42:]
''

Las cadenas de Python no se pueden modificar, son immutable. Por eso, asignar a una posición indexada de la cadena resulta en un error:

>>> word[0] = 'J'
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: 'str' object does not support item assignment
>>> word[2:] = 'py'
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: 'str' object does not support item assignment

Si necesitas una cadena diferente, deberías crear una nueva:

>>> 'J' + word[1:]
'Jython'
>>> word[:2] + 'py'
'Pypy'

La función incorporada len() retorna la longitud de una cadena:

>>> s = 'supercalifragilisticexpialidocious'
>>> len(s)
34

Ver también

Cadenas de caracteres — str

Las cadenas de texto son ejemplos de tipos secuencias y soportan las operaciones comunes para esos tipos.

Métodos de las cadenas de caracteres

Las cadenas de texto soportan una gran cantidad de métodos para transformaciones básicas y búsqueda.

Literales de cadena formateados

Literales de cadena que tienen expresiones embebidas.

Sintaxis de formateo de cadena

Aquí se da información sobre formateo de cadenas de texto con str.format().

Formateo de cadenas al estilo *printf*

Aquí se describen con más detalle las antiguas operaciones para formateo utilizadas cuando una cadena de texto está a la izquierda del operador %.

3.1.3. Listas

Python tiene varios tipos de datos compuestos, utilizados para agrupar otros valores. El más versátil es la lista, la cual puede ser escrita como una lista de valores separados por coma (ítems) entre corchetes. Las listas pueden contener ítems de diferentes tipos, pero usualmente los ítems son del mismo tipo.

>>> squares = [1, 4, 9, 16, 25]
>>> squares
[1, 4, 9, 16, 25]

Al igual que las cadenas (y todas las demás tipos integrados sequence), las listas se pueden indexar y segmentar:

>>> squares[0]  # indexing returns the item
1
>>> squares[-1]
25
>>> squares[-3:]  # slicing returns a new list
[9, 16, 25]

Todas las operaciones de rebanado retornan una nueva lista que contiene los elementos pedidos. Esto significa que la siguiente rebanada retorna una shallow copy de la lista:

>>> squares[:]
[1, 4, 9, 16, 25]

Las listas también admiten operaciones como concatenación:

>>> squares + [36, 49, 64, 81, 100]
[1, 4, 9, 16, 25, 36, 49, 64, 81, 100]

A diferencia de las cadenas, que son immutable, las listas son de tipo mutable, es decir, es posible cambiar su contenido:

>>> cubes = [1, 8, 27, 65, 125]  # something's wrong here
>>> 4 ** 3  # the cube of 4 is 64, not 65!
64
>>> cubes[3] = 64  # replace the wrong value
>>> cubes
[1, 8, 27, 64, 125]

También puede agregar nuevos elementos al final de la lista, utilizando el método append() (vamos a ver más sobre los métodos luego):

>>> cubes.append(216)  # add the cube of 6
>>> cubes.append(7 ** 3)  # and the cube of 7
>>> cubes
[1, 8, 27, 64, 125, 216, 343]

También es posible asignar a una rebanada, y esto incluso puede cambiar la longitud de la lista o vaciarla totalmente:

>>> letters = ['a', 'b', 'c', 'd', 'e', 'f', 'g']
>>> letters
['a', 'b', 'c', 'd', 'e', 'f', 'g']
>>> # replace some values
>>> letters[2:5] = ['C', 'D', 'E']
>>> letters
['a', 'b', 'C', 'D', 'E', 'f', 'g']
>>> # now remove them
>>> letters[2:5] = []
>>> letters
['a', 'b', 'f', 'g']
>>> # clear the list by replacing all the elements with an empty list
>>> letters[:] = []
>>> letters
[]

La función predefinida len() también sirve para las listas

>>> letters = ['a', 'b', 'c', 'd']
>>> len(letters)
4

Es posible anidar listas (crear listas que contengan otras listas), por ejemplo:

>>> a = ['a', 'b', 'c']
>>> n = [1, 2, 3]
>>> x = [a, n]
>>> x
[['a', 'b', 'c'], [1, 2, 3]]
>>> x[0]
['a', 'b', 'c']
>>> x[0][1]
'b'

3.2. Primeros pasos hacia la programación

Por supuesto, podemos usar Python para tareas más complicadas que sumar dos y dos. Por ejemplo, podemos escribir una parte inicial de la serie de Fibonacci <https://en.wikipedia.org/wiki/Fibonacci_number>`_ así:

>>> # Fibonacci series:
... # the sum of two elements defines the next
... a, b = 0, 1
>>> while a < 10:
...     print(a)
...     a, b = b, a+b
...
0
1
1
2
3
5
8

Este ejemplo introduce varias características nuevas.

La primera línea contiene una asignación múltiple: las variables a y b obtienen simultáneamente los nuevos valores 0 y 1. En la última línea esto se usa nuevamente, demostrando que las expresiones de la derecha son evaluadas primero antes de que se realice cualquiera de las asignaciones. Las expresiones del lado derecho se evalúan de izquierda a derecha.

El bucle while se ejecuta mientras la condición (aquí: a < 10) sea verdadera. En Python, como en C, cualquier valor entero que no sea cero es verdadero; cero es falso. La condición también puede ser una cadena de texto o una lista, de hecho, cualquier secuencia; cualquier cosa con una longitud distinta de cero es verdadera, las secuencias vacías son falsas. La prueba utilizada en el ejemplo es una comparación simple. Los operadores de comparación estándar se escriben igual que en C: < (menor que), > (mayor que), == (igual a), <= (menor que o igual a), >= (mayor que o igual a) y != (distinto a).

El cuerpo del bucle está indentado: la indentación es la forma que usa Python para agrupar declaraciones. En el intérprete interactivo debes teclear un tabulador o espacio(s) para cada línea indentada. En la práctica vas a preparar entradas más complicadas para Python con un editor de texto; todos los editores de texto modernos tienen la facilidad de agregar la indentación automáticamente. Cuando se ingresa una instrucción compuesta de forma interactiva, se debe finalizar con una línea en blanco para indicar que está completa (ya que el analizador no puede adivinar cuando tecleaste la última línea). Nota que cada línea de un bloque básico debe estar sangrada de la misma forma.

La función print() escribe el valor de los argumentos que se le dan. Difiere de simplemente escribir la expresión que se quiere mostrar (como hicimos antes en los ejemplos de la calculadora) en la forma en que maneja múltiples argumentos, cantidades de punto flotante y cadenas. Las cadenas de texto son impresas sin comillas y un espacio en blanco se inserta entre los elementos, así puedes formatear cosas de una forma agradable:

>>> i = 256*256
>>> print('The value of i is', i)
The value of i is 65536

El parámetro nombrado end puede usarse para evitar el salto de linea al final de la salida, o terminar la salida con una cadena diferente:

>>> a, b = 0, 1
>>> while a < 1000:
...     print(a, end=',')
...     a, b = b, a+b
...
0,1,1,2,3,5,8,13,21,34,55,89,144,233,377,610,987,

Notas al pie

1

Debido a que ** tiene una prioridad mayor que `-, -3**2 se interpretará como -(3**2), por lo tanto dará como resultado -9. Para evitar esto y obtener 9, puedes usar (-3)**2.

2

A diferencia de otros lenguajes, caracteres especiales como \n tienen el mismo significado con simple('...') y dobles ("...") comillas. La única diferencia entre las dos es que dentro de las comillas simples no existe la necesidad de escapar " (pero tienes que escapar \') y viceversa.

4. Más herramientas para control de flujo

Además de la sentencia while que acabamos de introducir, Python soporta las sentencias de control de flujo que podemos encontrar en otros lenguajes, con algunos cambios.

4.1. La sentencia if

Tal vez el tipo más conocido de sentencia sea el if. Por ejemplo:

>>> x = int(input("Please enter an integer: "))
Please enter an integer: 42
>>> if x < 0:
...     x = 0
...     print('Negative changed to zero')
... elif x == 0:
...     print('Zero')
... elif x == 1:
...     print('Single')
... else:
...     print('More')
...
More

Puede haber cero o más bloques elif, y el bloque else es opcional. La palabra reservada “elif’es una abreviación de “else if”, y es útil para evitar un sangrado excesivo. Una secuencia if … elif … elif … sustituye las sentencias switch o case encontradas en otros lenguajes.

4.2. La sentencia for

La sentencia for en Python difiere un poco de lo que uno puede estar acostumbrado en lenguajes como C o Pascal. En lugar de siempre iterar sobre una progresión aritmética de números (como en Pascal) o darle al usuario la posibilidad de definir tanto el paso de la iteración como la condición de fin (como en C), la sentencia for de Python itera sobre los ítems de cualquier secuencia (una lista o una cadena de texto), en el orden que aparecen en la secuencia. Por ejemplo:

>>> # Measure some strings:
... words = ['cat', 'window', 'defenestrate']
>>> for w in words:
...     print(w, len(w))
...
cat 3
window 6
defenestrate 12

Código que modifica una colección mientras se itera sobre la misma colección puede ser complejo de hacer bien. Sin embargo, suele ser más directo iterar sobre una copia de la colección o crear una nueva colección:

# Strategy:  Iterate over a copy
for user, status in users.copy().items():
    if status == 'inactive':
        del users[user]

# Strategy:  Create a new collection
active_users = {}
for user, status in users.items():
    if status == 'active':
        active_users[user] = status

4.3. La función range()

Si se necesita iterar sobre una secuencia de números, es apropiado utilizar la función integrada range(), la cual genera progresiones aritméticas:

>>> for i in range(5):
...     print(i)
...
0
1
2
3
4

El valor final dado nunca es parte de la secuencia; range(10) genera 10 valores, los índices correspondientes para los ítems de una secuencia de longitud 10. Es posible hacer que el rango empiece con otro número, o especificar un incremento diferente (incluso negativo; algunas veces se lo llama “paso”):

>>> list(range(5, 10))
[5, 6, 7, 8, 9]

>>> list(range(0, 10, 3))
[0, 3, 6, 9]

>>> list(range(-10, -100, -30))
[-10, -40, -70]

Para iterar sobre los índices de una secuencia, puedes combinar range() y len() así:

>>> a = ['Mary', 'had', 'a', 'little', 'lamb']
>>> for i in range(len(a)):
...     print(i, a[i])
...
0 Mary
1 had
2 a
3 little
4 lamb

En la mayoría de los casos, sin embargo, conviene usar la función enumerate(), mira Técnicas de iteración.

Algo extraño sucede si muestras un ` range`:

>>> range(10)
range(0, 10)

De muchas maneras el objeto retornado por range() se comporta como si fuera una lista, pero no lo es. Es un objeto que retorna los ítems sucesivos de la secuencia deseada cuando iteras sobre él, pero realmente no construye la lista, ahorrando entonces espacio.

Decimos que tal objeto es iterable; esto es, que se puede usar en funciones y construcciones que esperan algo de lo cual obtener ítems sucesivos hasta que se termine. Hemos visto que la declaración for es una de esas construcciones, mientras que un ejemplo de función que toma un iterable es la función sum():

>>> sum(range(4))  # 0 + 1 + 2 + 3
6

Later we will see more functions that return iterables and take iterables as arguments. In chapter Estructuras de datos, we will discuss in more detail about list().

4.4. Las sentencias break, continue, y else en bucles

La sentencia break, como en C, termina el bucle for o while más anidado.

Las sentencias de bucle pueden tener una cláusula`!else` que es ejecutada cuando el bucle termina, después de agotar el iterable (con for) o cuando la condición se hace falsa (con while), pero no cuando el bucle se termina con la sentencia break. Se puede ver el ejemplo en el siguiente bucle, que busca números primos:

>>> for n in range(2, 10):
...     for x in range(2, n):
...         if n % x == 0:
...             print(n, 'equals', x, '*', n//x)
...             break
...     else:
...         # loop fell through without finding a factor
...         print(n, 'is a prime number')
...
2 is a prime number
3 is a prime number
4 equals 2 * 2
5 is a prime number
6 equals 2 * 3
7 is a prime number
8 equals 2 * 4
9 equals 3 * 3

(Sí, este es el código correcto. Fíjate bien: el else pertenece al ciclo for, no al if.)

Cuando se usa con un bucle, la cláusula else tiene más en común con el else de una sentencia try que con el de un if: en una sentencia try la cláusula else se ejecuta cuando no se genera ninguna excepción, y el else de un bucle se ejecuta cuando no hay ningún break. Para más sobre la declaración try y excepciones, mira Gestionando excepciones.

La declaración continue, también tomada de C, continua con la siguiente iteración del ciclo:

>>> for num in range(2, 10):
...     if num % 2 == 0:
...         print("Found an even number", num)
...         continue
...     print("Found an odd number", num)
...
Found an even number 2
Found an odd number 3
Found an even number 4
Found an odd number 5
Found an even number 6
Found an odd number 7
Found an even number 8
Found an odd number 9

4.5. La sentencia pass

La sentencia pass no hace nada. Se puede usar cuando una sentencia es requerida por la sintaxis pero el programa no requiere ninguna acción. Por ejemplo:

>>> while True:
...     pass  # Busy-wait for keyboard interrupt (Ctrl+C)
...

Se usa normalmente para crear clases en su mínima expresión:

>>> class MyEmptyClass:
...     pass
...

Otro lugar donde se puede usar pass es como una marca de lugar para una función o un cuerpo condicional cuando estás trabajando en código nuevo, lo cual te permite pensar a un nivel de abstracción mayor. El pass se ignora silenciosamente:

>>> def initlog(*args):
...     pass   # Remember to implement this!
...

4.6. Definiendo funciones

Podemos crear una función que escriba la serie de Fibonacci hasta un límite determinado:

>>> def fib(n):    # write Fibonacci series up to n
...     """Print a Fibonacci series up to n."""
...     a, b = 0, 1
...     while a < n:
...         print(a, end=' ')
...         a, b = b, a+b
...     print()
...
>>> # Now call the function we just defined:
... fib(2000)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597

La palabra reservada def se usa para definir funciones. Debe seguirle el nombre de la función y la lista de parámetros formales entre paréntesis. Las sentencias que forman el cuerpo de la función empiezan en la línea siguiente, y deben estar con sangría.

La primera sentencia del cuerpo de la función puede ser opcionalmente una cadena de texto literal; esta es la cadena de texto de documentación de la función, o docstring. (Puedes encontrar más acerca de docstrings en la sección Cadenas de texto de documentación.). Existen herramientas que usan las docstrings para producir documentación imprimible o disponible en línea, o para dejar que los usuarios busquen interactivamente a través del código; es una buena práctica incluir docstrings en el código que escribes, y hacerlo un buen hábito.

La ejecución de una función introduce una nueva tabla de símbolos usada para las variables locales de la función. Más precisamente, todas las asignaciones de variables en la función almacenan el valor en la tabla de símbolos local; así mismo la referencia a variables primero mira la tabla de símbolos local, luego en la tabla de símbolos local de las funciones externas, luego la tabla de símbolos global, y finalmente la tabla de nombres predefinidos. Así, a variables globales y a variables de funciones que engloban a una función no se les puede asignar directamente un valor dentro de una función (a menos que se las nombre en la sentencia global, o mediante la sentencia nonlocal para variables de funciones que engloban la función local), aunque si pueden ser referenciadas.

Los parámetros (argumentos) reales para una llamada de función se introducen en la tabla de símbolos local de la función llamada cuando se llama; por lo tanto, los argumentos se pasan usando llamada por valor (donde el valor es siempre un objeto referencia, no el valor del objeto). 1 Cuando una función llama a otra función, o se llama a sí misma de forma recursiva, se crea una nueva tabla de símbolos locales para esa llamada.

Una definición de función asocia el nombre de la función con el objeto de función en la tabla de símbolos actual. El intérprete reconoce el objeto al que apunta ese nombre como una función definida por el usuario. Otros nombres también pueden apuntar a ese mismo objeto de función y también se pueden usar para acceder a la función:

>>> fib
<function fib at 10042ed0>
>>> f = fib
>>> f(100)
0 1 1 2 3 5 8 13 21 34 55 89

Viniendo de otros lenguajes, puedes objetar que fib no es una función, sino un procedimiento, porque no retorna un valor. De hecho, técnicamente hablando, los procedimientos sin return sí retornan un valor, aunque uno aburrido. Este valor se llama None (es un nombre predefinido). El intérprete por lo general no escribe el valor None si va a ser el único valor escrito. Si realmente se quiere, se puede verlo usando la función print()

>>> fib(0)
>>> print(fib(0))
None

Es simple escribir una función que retorne una lista con los números de la serie de Fibonacci en lugar de imprimirlos:

>>> def fib2(n):  # return Fibonacci series up to n
...     """Return a list containing the Fibonacci series up to n."""
...     result = []
...     a, b = 0, 1
...     while a < n:
...         result.append(a)    # see below
...         a, b = b, a+b
...     return result
...
>>> f100 = fib2(100)    # call it
>>> f100                # write the result
[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]

Este ejemplo, como es usual, demuestra algunas características más de Python:

La sentencia return retorna un valor en una función. return sin una expresión como argumento retorna None. Si se alcanza el final de una función, también se retorna None.

La sentencia result.append(a) llama a un método del objeto lista result. Un método es una función que “pertenece” a un objeto y se nombra obj.methodname, dónde obj es algún objeto (puede ser una expresión), y methodname es el nombre del método que está definido por el tipo del objeto. Distintos tipos definen distintos métodos. Métodos de diferentes tipos pueden tener el mismo nombre sin causar ambigüedad. (Es posible definir tipos de objetos propios, y métodos, usando clases, mira Clases). El método append() mostrado en el ejemplo está definido para objetos lista; añade un nuevo elemento al final de la lista. En este ejemplo es equivalente a result = result + [a], pero más eficiente.

4.7. Más sobre definición de funciones

También es posible definir funciones con un número variable de argumentos. Hay tres formas que pueden ser combinadas.

4.7.1. Argumentos con valores por omisión

La forma más útil es especificar un valor por omisión para uno o más argumentos. Esto crea una función que puede ser llamada con menos argumentos que los que permite. Por ejemplo:

def ask_ok(prompt, retries=4, reminder='Please try again!'):
    while True:
        ok = input(prompt)
        if ok in ('y', 'ye', 'yes'):
            return True
        if ok in ('n', 'no', 'nop', 'nope'):
            return False
        retries = retries - 1
        if retries < 0:
            raise ValueError('invalid user response')
        print(reminder)

Esta función puede ser llamada de distintas maneras:

pasando sólo el argumento obligatorio: ask_ok('Do you really want to quit?')

pasando uno de los argumentos opcionales: ask_ok('OK to overwrite the file?', 2)

o pasando todos los argumentos: ask_ok('OK to overwrite the file?', 2, 'Come on, only yes or no!')

Este ejemplo también introduce la palabra reservada in, la cual prueba si una secuencia contiene o no un determinado valor.

Los valores por omisión son evaluados en el momento de la definición de la función, en el ámbito de la definición, entonces:

i = 5

def f(arg=i):
    print(arg)

i = 6
f()

…imprimirá `5.

Advertencia importante: El valor por omisión es evaluado solo una vez. Existe una diferencia cuando el valor por omisión es un objeto mutable como una lista, diccionario, o instancia de la mayoría de las clases. Por ejemplo, la siguiente función acumula los argumentos que se le pasan en subsiguientes llamadas:

def f(a, L=[]):
    L.append(a)
    return L

print(f(1))
print(f(2))
print(f(3))

Imprimirá

[1]
[1, 2]
[1, 2, 3]

Si no se quiere que el valor por omisión sea compartido entre subsiguientes llamadas, se pueden escribir la función así:

def f(a, L=None):
    if L is None:
        L = []
    L.append(a)
    return L

4.7.2. Palabras claves como argumentos

Las funciones también puede ser llamadas usando argumentos de palabras clave (o argumentos nombrados) de la forma kwarg=value. Por ejemplo, la siguiente función:

def parrot(voltage, state='a stiff', action='voom', type='Norwegian Blue'):
    print("-- This parrot wouldn't", action, end=' ')
    print("if you put", voltage, "volts through it.")
    print("-- Lovely plumage, the", type)
    print("-- It's", state, "!")

…acepta un argumento obligatorio (voltage)) y tres argumentos opcionales (state, action, y type). Esta función puede llamarse de cualquiera de las siguientes maneras:

parrot(1000)                                          # 1 positional argument
parrot(voltage=1000)                                  # 1 keyword argument
parrot(voltage=1000000, action='VOOOOOM')             # 2 keyword arguments
parrot(action='VOOOOOM', voltage=1000000)             # 2 keyword arguments
parrot('a million', 'bereft of life', 'jump')         # 3 positional arguments
parrot('a thousand', state='pushing up the daisies')  # 1 positional, 1 keyword

…pero estas otras llamadas serían todas inválidas:

parrot()                     # required argument missing
parrot(voltage=5.0, 'dead')  # non-keyword argument after a keyword argument
parrot(110, voltage=220)     # duplicate value for the same argument
parrot(actor='John Cleese')  # unknown keyword argument

En una llamada a una función, los argumentos nombrados deben seguir a los argumentos posicionales. Cada uno de los argumentos nombrados pasados deben coincidir con un argumento aceptado por la función (por ejemplo, actor no es un argumento válido para la función parrot), y el orden de los mismos no es importante. Esto también se aplica a los argumentos obligatorios (por ejemplo, parrot(voltage=1000) también es válido). Ningún argumento puede recibir más de un valor al mismo tiempo. Aquí hay un ejemplo que falla debido a esta restricción:

>>> def function(a):
...     pass
...
>>> function(0, a=0)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: function() got multiple values for argument 'a'

Cuando un parámetro formal de la forma **name está presente al final, recibe un diccionario (ver Tipos Mapa — dict) conteniendo todos los argumentos nombrados excepto aquellos correspondientes a un parámetro formal. Esto puede ser combinado con un parámetro formal de la forma *name (descrito en la siguiente sección) que recibe una tuple conteniendo los argumentos posicionales además de la lista de parámetros formales. (*name debe ocurrir antes de **name). Por ejemplo, si definimos una función así:

def cheeseshop(kind, *arguments, **keywords):
    print("-- Do you have any", kind, "?")
    print("-- I'm sorry, we're all out of", kind)
    for arg in arguments:
        print(arg)
    print("-" * 40)
    for kw in keywords:
        print(kw, ":", keywords[kw])

Puede ser llamada así:

cheeseshop("Limburger", "It's very runny, sir.",
           "It's really very, VERY runny, sir.",
           shopkeeper="Michael Palin",
           client="John Cleese",
           sketch="Cheese Shop Sketch")

…y por supuesto imprimirá:

-- Do you have any Limburger ?
-- I'm sorry, we're all out of Limburger
It's very runny, sir.
It's really very, VERY runny, sir.
----------------------------------------
shopkeeper : Michael Palin
client : John Cleese
sketch : Cheese Shop Sketch

Se debe notar que el orden en el cual los argumentos nombrados son impresos está garantizado para coincidir con el orden en el cual fueron provistos en la llamada a la función.

4.7.3. Parámetros especiales

Por defecto, los argumentos pueden enviarse a una función Python o bien por posición o explícitamente por clave. Para legibilidad y rendimiento tiene sentido restringir como se pueden enviar los argumentos, así un desarrollador necesitará mirar solamente la definición de la función para determinar si los argumentos se deben enviar por posición, por posición o clave, o por clave.

La definición de una función puede ser como la siguiente:

def f(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):
      -----------    ----------     ----------
        |             |                  |
        |        Positional or keyword   |
        |                                - Keyword only
         -- Positional only

donde / y * son posicionales. Si se utilizan, esos símbolos indican el tipo de parámetro por como los argumentos deben enviarse a la función: solo por posición (positional-only), por posición o clave (positional-or-keyword) y solo por clave (keyword-only). Parámetros por clave pueden también denominarse parámetros por nombre o nombrados.

4.7.3.1. Argumentos posicionales o de palabras claves

Si / y * no están presentes en la definición de la función, los parámetros pueden ser pasados a una función posicionalmente o por palabra clave.

4.7.3.2. Parámetros únicamente posicionales

En detalle, es posible señalar algunos parámetros como únicamente posicionales.. En ese caso el orden de los parámetros es importante, y los parámetros no pueden ser indicados utilizando palabras claves. Parámetros únicamente posicionales son ubicados antes de una / (barra). La / es utilizada para separar lógicamente parámetros únicamente posicionales del resto. Si no existe una / en la definición de la función, no existen parámetros únicamente posicionales.

Los parámetros luego de una / pueden ser únicamente posicionales o unicamente de palabras claves.

4.7.3.3. Argumentos únicamente de palabras clave

Para señalar parámetros como unicamente de palabras clave, indicando que los parámetros deben ser pasados con una palabra clave, indiqué un * en la lista de argumentos antes del primer parámetro únicamente de palabras clave.

4.7.3.4. Ejemplos de Funciones

Considere el siguiente ejemplo de definiciones de funciones prestando especial atención a los marcadores / y *:

>>> def standard_arg(arg):
...     print(arg)
...
>>> def pos_only_arg(arg, /):
...     print(arg)
...
>>> def kwd_only_arg(*, arg):
...     print(arg)
...
>>> def combined_example(pos_only, /, standard, *, kwd_only):
...     print(pos_only, standard, kwd_only)

La primer definición de función, standard_arg, la forma mas familiar, no indica ninguna restricción en las condiciones para llamarla y los parámetros deben ser pasados por posición o utilizando palabras clave:

>>> standard_arg(2)
2

>>> standard_arg(arg=2)
2

La segunda función pos_only_arg está restringida a utilizar únicamente parámetros posicionales ya que existe una / en la definición de la función:

>>> pos_only_arg(1)
1

>>> pos_only_arg(arg=1)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: pos_only_arg() got some positional-only arguments passed as keyword arguments: 'arg'

La tercer función kwd_only_args solo permite parámetros con palabras clave, indicado por un * en la definición de la función:

>>> kwd_only_arg(3)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: kwd_only_arg() takes 0 positional arguments but 1 was given

>>> kwd_only_arg(arg=3)
3

La última utiliza las tres convenciones en una misma definición de función:

>>> combined_example(1, 2, 3)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: combined_example() takes 2 positional arguments but 3 were given

>>> combined_example(1, 2, kwd_only=3)
1 2 3

>>> combined_example(1, standard=2, kwd_only=3)
1 2 3

>>> combined_example(pos_only=1, standard=2, kwd_only=3)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: combined_example() got some positional-only arguments passed as keyword arguments: 'pos_only'

Finalmente, considere esta definición de función que contiene una colisión potencial entre los parámetros posicionales name y **kwds que incluye name como una clave:

def foo(name, **kwds):
    return 'name' in kwds

No hay una llamada posible que lo haga retornar True ya que la palabra clave 'name' siempre se vinculará al primer parámetro. Por ejemplo:

>>> foo(1, **{'name': 2})
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: foo() got multiple values for argument 'name'
>>>

Pero utilizando / (parámetros únicamente posicionales), es posible ya que permite utilizar name como un parámetro posicional y name como un parámetro de palabras clave:

def foo(name, /, **kwds):
    return 'name' in kwds
>>> foo(1, **{'name': 2})
True

En otras palabras, los nombres de parámetros únicamente posicionales pueden ser utilizados en **kwds sin ambigüedad.

4.7.3.5. Resumen

El caso de uso determinará qué parámetros utilizar en una definición de función:

def f(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):

A modo de guía:

Utilice únicamente posicionales si quiere que el nombre del parámetro esté disponible para el usuario. Esto es útil cuando el nombre del parámetro no tiene un significado real, si se quiere imponer el orden de los parámetros cuando una función es llamada o si necesita tomar algunos parámetros posicionales y palabras claves arbitrarias.

Utilice parámetros únicamente de palabras clave cuando los nombres de los parámetros tienen un significado y la definición de la función será más entendible usando nombres explícitos o cuando desea evitar que los usuarios dependan de la posición de los parámetros que se pasan.

En el caso de una API, use solo posicional para evitar que se rompan los cambios de la API si el nombre del parámetro se modifica en el futuro.

4.7.4. Listas de argumentos arbitrarios

Finalmente, la opción menos frecuentemente usada es especificar que una función puede ser llamada con un número arbitrario de argumentos. Estos argumentos serán organizados en una tupla (mira Tuplas y secuencias). Antes del número variable de argumentos, cero o más argumentos normales pueden estar presentes.:

def write_multiple_items(file, separator, *args):
    file.write(separator.join(args))

Normally, these variadic arguments will be last in the list of formal parameters, because they scoop up all remaining input arguments that are passed to the function. Any formal parameters which occur after the *args parameter are “keyword-only” arguments, meaning that they can only be used as keywords rather than positional arguments.

>>> def concat(*args, sep="/"):
...     return sep.join(args)
...
>>> concat("earth", "mars", "venus")
'earth/mars/venus'
>>> concat("earth", "mars", "venus", sep=".")
'earth.mars.venus'

4.7.5. Desempaquetando una lista de argumentos

La situación inversa ocurre cuando los argumentos ya están en una lista o tupla pero necesitan ser desempaquetados para llamar a una función que requiere argumentos posicionales separados. Por ejemplo, la función predefinida range() espera los parámetros inicio y fin. Si estos no están disponibles en forma separada, se puede escribir la llamada a la función con el operador * para desempaquetar argumentos desde una lista o una tupla:

>>> list(range(3, 6))            # normal call with separate arguments
[3, 4, 5]
>>> args = [3, 6]
>>> list(range(*args))            # call with arguments unpacked from a list
[3, 4, 5]

Del mismo modo, los diccionarios pueden entregar argumentos nombrados con el operador **:

>>> def parrot(voltage, state='a stiff', action='voom'):
...     print("-- This parrot wouldn't", action, end=' ')
...     print("if you put", voltage, "volts through it.", end=' ')
...     print("E's", state, "!")
...
>>> d = {"voltage": "four million", "state": "bleedin' demised", "action": "VOOM"}
>>> parrot(**d)
-- This parrot wouldn't VOOM if you put four million volts through it. E's bleedin' demised !

4.7.6. Expresiones lambda

Pequeñas funciones anónimas pueden ser creadas con la palabra reservada lambda. Esta función retorna la suma de sus dos argumentos: lambda a, b: a+b Las funciones Lambda pueden ser usadas en cualquier lugar donde sea requerido un objeto de tipo función. Están sintácticamente restringidas a una sola expresión. Semánticamente, son solo azúcar sintáctica para definiciones normales de funciones. Al igual que las funciones anidadas, las funciones lambda pueden hacer referencia a variables desde el ámbito que la contiene:

>>> def make_incrementor(n):
...     return lambda x: x + n
...
>>> f = make_incrementor(42)
>>> f(0)
42
>>> f(1)
43

El ejemplo anterior muestra el uso de una expresión lambda para retornar una función. Otro uso es para pasar pequeñas funciones como argumentos

>>> pairs = [(1, 'one'), (2, 'two'), (3, 'three'), (4, 'four')]
>>> pairs.sort(key=lambda pair: pair[1])
>>> pairs
[(4, 'four'), (1, 'one'), (3, 'three'), (2, 'two')]

4.7.7. Cadenas de texto de documentación

Acá hay algunas convenciones sobre el contenido y formato de las cadenas de texto de documentación.

La primera línea debe ser siempre un resumen corto y conciso del propósito del objeto. Para ser breve, no se debe mencionar explícitamente el nombre o tipo del objeto, ya que estos están disponibles de otros modos (excepto si el nombre es un verbo que describe el funcionamiento de la función). Esta línea debe empezar con una letra mayúscula y terminar con un punto.

Si hay más líneas en la cadena de texto de documentación, la segunda línea debe estar en blanco, separando visualmente el resumen del resto de la descripción. Las líneas siguientes deben ser uno o más párrafos describiendo las convenciones para llamar al objeto, efectos secundarios, etc.

El analizador de Python no quita el sangrado de las cadenas de texto literales multi-líneas, entonces las herramientas que procesan documentación tienen que quitarlo si así lo desean. Esto se hace mediante la siguiente convención. La primera línea que no está en blanco siguiente a la primer línea de la cadena determina la cantidad de sangría para toda la cadena de documentación. (No podemos usar la primer línea ya que generalmente es adyacente a las comillas de apertura de la cadena y el sangrado no se nota en la cadena de texto). Los espacios en blanco «equivalentes» a este sangrado son luego quitados del comienzo de cada línea en la cadena. No deberían haber líneas con una sangría menor, pero si las hay todos los espacios en blanco del comienzo deben ser quitados. La equivalencia de espacios en blanco debe ser verificada luego de la expansión de tabuladores (a 8 espacios, normalmente).

Este es un ejemplo de un docstring multi-línea:

>>> def my_function():
...     """Do nothing, but document it.
...
...     No, really, it doesn't do anything.
...     """
...     pass
...
>>> print(my_function.__doc__)
Do nothing, but document it.

    No, really, it doesn't do anything.

4.7.8. Anotación de funciones

Las anotaciones de funciones son información completamente opcional sobre los tipos usadas en funciones definidas por el usuario (ver PEP 484 para más información).

Annotations are stored in the __annotations__ attribute of the function as a dictionary and have no effect on any other part of the function. Parameter annotations are defined by a colon after the parameter name, followed by an expression evaluating to the value of the annotation. Return annotations are defined by a literal ->, followed by an expression, between the parameter list and the colon denoting the end of the def statement. The following example has a required argument, an optional argument, and the return value annotated:

>>> def f(ham: str, eggs: str = 'eggs') -> str:
...     print("Annotations:", f.__annotations__)
...     print("Arguments:", ham, eggs)
...     return ham + ' and ' + eggs
...
>>> f('spam')
Annotations: {'ham': <class 'str'>, 'return': <class 'str'>, 'eggs': <class 'str'>}
Arguments: spam eggs
'spam and eggs'

4.8. Intermezzo: Estilo de codificación

Ahora que estás a punto de escribir piezas de Python más largas y complejas, es un buen momento para hablar sobre estilo de codificación. La mayoría de los lenguajes pueden ser escritos (o mejor dicho, formateados) con diferentes estilos; algunos son mas fáciles de leer que otros. Hacer que tu código sea más fácil de leer por otros es siempre una buena idea, y adoptar un buen estilo de codificación ayuda tremendamente a lograrlo.

Para Python, PEP 8 [https://www.python.org/dev/peps/pep-0008] se erigió como la guía de estilo a la que más proyectos adhirieron; promueve un estilo de codificación fácil de leer y visualmente agradable. Todos los desarrolladores Python deben leerlo en algún momento; aquí están extraídos los puntos más importantes:

Usar sangrías de 4 espacios, no tabuladores.

4 espacios son un buen compromiso entre una sangría pequeña (permite mayor nivel de sangrado)y una sangría grande (más fácil de leer). Los tabuladores introducen confusión y es mejor dejarlos de lado.

Recortar las líneas para que no superen los 79 caracteres.

Esto ayuda a los usuarios con pantallas pequeñas y hace posible tener varios archivos de código abiertos, uno al lado del otro, en pantallas grandes.

Usar líneas en blanco para separar funciones y clases, y bloques grandes de código dentro de funciones.

Cuando sea posible, poner comentarios en una sola línea.

Usar docstrings.

Usar espacios alrededor de operadores y luego de las comas, pero no directamente dentro de paréntesis: a = f(1, 2) + g(3, 4).

Nombrar las clases y funciones consistentemente; la convención es usar NotacionCamello para clases y minusculas_con_guiones_bajos para funciones y métodos. Siempre usa self como el nombre para el primer argumento en los métodos (mirar Un primer vistazo a las clases para más información sobre clases y métodos).

No uses codificaciones estrafalarias si esperas usar el código en entornos internacionales. El default de Python, UTF-8, o incluso ASCII plano funcionan bien en la mayoría de los casos.

De la misma manera, no uses caracteres no-ASCII en los identificadores si hay incluso una pequeñísima chance de que gente que hable otro idioma tenga que leer o mantener el código.

Notas al pie

1

En realidad, llamadas por referencia de objeto sería una mejor descripción, ya que si se pasa un objeto mutable, quien realiza la llamada verá cualquier cambio que se realice sobre el mismo (por ejemplo ítems insertados en una lista).

5. Estructuras de datos

Este capítulo describe algunas cosas que ya has aprendido en más detalle y agrega algunas cosas nuevas también.

5.1. Más sobre listas

El tipo de dato lista tiene algunos métodos más. Aquí están todos los métodos de los objetos lista:

list.append(x)

Agrega un ítem al final de la lista. Equivale a a[len(a):] = [x].

list.extend(iterable)

Extiende la lista agregándole todos los ítems del iterable. Equivale a a[len(a):] = iterable.

list.insert(i, x)

Inserta un ítem en una posición dada. El primer argumento es el índice del ítem delante del cual se insertará, por lo tanto a.insert(0, x) inserta al principio de la lista y a.insert(len(a), x) equivale a a.append(x).

list.remove(x)

Quita el primer ítem de la lista cuyo valor sea x. Lanza un ValueError si no existe tal ítem.

list.pop([i])

Quita el ítem en la posición dada de la lista y lo retorna. Si no se especifica un índice, a.pop() quita y retorna el último elemento de la lista. (Los corchetes que encierran a i en la firma del método denotan que el parámetro es opcional, no que deberías escribir corchetes en esa posición. Verás esta notación con frecuencia en la Referencia de la Biblioteca de Python.)

list.clear()

Elimina todos los elementos de la lista. Equivalente a del a[:].

list.index(x[, start[, end]])

Retorna el índice basado en cero del primer elemento cuyo valor sea igual a x. Lanza una excepción ValueError si no existe tal elemento.

Los argumentos opcionales start y end son interpretados como la notación de rebanadas y se usan para limitar la búsqueda a un segmento particular de la lista. El índice retornado se calcula de manera relativa al inicio de la secuencia completa en lugar de con respecto al argumento start.

list.count(x)

Retorna el número de veces que x aparece en la lista.

list.sort(*, key=None, reverse=False)

Ordena los elementos de la lista in situ (los argumentos pueden ser usados para personalizar el orden de la lista, ver sorted() para su explicación).

list.reverse()

Invierte los elementos de la lista in situ.

list.copy()

Retorna una copia superficial de la lista. Equivalente a a[:].

Un ejemplo que usa la mayoría de los métodos de la lista:

>>> fruits = ['orange', 'apple', 'pear', 'banana', 'kiwi', 'apple', 'banana']
>>> fruits.count('apple')
2
>>> fruits.count('tangerine')
0
>>> fruits.index('banana')
3
>>> fruits.index('banana', 4)  # Find next banana starting a position 4
6
>>> fruits.reverse()
>>> fruits
['banana', 'apple', 'kiwi', 'banana', 'pear', 'apple', 'orange']
>>> fruits.append('grape')
>>> fruits
['banana', 'apple', 'kiwi', 'banana', 'pear', 'apple', 'orange', 'grape']
>>> fruits.sort()
>>> fruits
['apple', 'apple', 'banana', 'banana', 'grape', 'kiwi', 'orange', 'pear']
>>> fruits.pop()
'pear'

Quizás hayas notado que métodos como insert`, remove o sort que únicamente modifican la lista no tienen impreso un valor de retorno – retornan el valor por defecto None. 1 Esto es un principio de diseño para todas las estructuras de datos mutables en Python.

Otra cosa que puedes observar es que no todos los datos se pueden ordenar o comparar. Por ejemplo, [None, 'hello', 10] no se puede ordenar ya que los enteros no se pueden comparar con strings y None no se puede comparar con los otros tipos. También hay algunos tipos que no tienen una relación de orden definida. Por ejemplo, 3+4j < 5+7j no es una comparación válida.

5.1.1. Usando listas como pilas

Los métodos de lista hacen que resulte muy fácil usar una lista como una pila, donde el último elemento añadido es el primer elemento retirado («último en entrar, primero en salir»). Para agregar un elemento a la cima de la pila, utiliza append(). Para retirar un elemento de la cima de la pila, utiliza pop() sin un índice explícito. Por ejemplo:

>>> stack = [3, 4, 5]
>>> stack.append(6)
>>> stack.append(7)
>>> stack
[3, 4, 5, 6, 7]
>>> stack.pop()
7
>>> stack
[3, 4, 5, 6]
>>> stack.pop()
6
>>> stack.pop()
5
>>> stack
[3, 4]

5.1.2. Usando listas como colas

También es posible usar una lista como una cola, donde el primer elemento añadido es el primer elemento retirado («primero en entrar, primero en salir»); sin embargo, las listas no son eficientes para este propósito. Agregar y sacar del final de la lista es rápido, pero insertar o sacar del comienzo de una lista es lento (porque todos los otros elementos tienen que ser desplazados por uno).

Para implementar una cola, utiliza collections.deque el cual fue diseñado para añadir y quitar de ambas puntas de forma rápida. Por ejemplo:

>>> from collections import deque
>>> queue = deque(["Eric", "John", "Michael"])
>>> queue.append("Terry")           # Terry arrives
>>> queue.append("Graham")          # Graham arrives
>>> queue.popleft()                 # The first to arrive now leaves
'Eric'
>>> queue.popleft()                 # The second to arrive now leaves
'John'
>>> queue                           # Remaining queue in order of arrival
deque(['Michael', 'Terry', 'Graham'])

5.1.3. Comprensión de listas

Las comprensiones de listas ofrecen una manera concisa de crear listas. Sus usos comunes son para hacer nuevas listas donde cada elemento es el resultado de algunas operaciones aplicadas a cada miembro de otra secuencia o iterable, o para crear un segmento de la secuencia de esos elementos para satisfacer una condición determinada.

Por ejemplo, asumamos que queremos crear una lista de cuadrados, como:

>>> squares = []
>>> for x in range(10):
...     squares.append(x**2)
...
>>> squares
[0, 1, 4, 9, 16, 25, 36, 49, 64, 81]

Nota que esto crea (o sobreescribe) una variable llamada x que sigue existiendo luego de que el bucle haya terminado. Podemos calcular la lista de cuadrados sin ningún efecto secundario haciendo:

squares = list(map(lambda x: x**2, range(10)))

o, un equivalente:

squares = [x**2 for x in range(10)]

que es más conciso y legible.

Una lista de comprensión consiste de corchetes rodeando una expresión seguida de la declaración for y luego cero o más declaraciones for o if. El resultado será una nueva lista que sale de evaluar la expresión en el contexto de los for o if que le siguen. Por ejemplo, esta lista de comprensión combina los elementos de dos listas si no son iguales:

>>> [(x, y) for x in [1,2,3] for y in [3,1,4] if x != y]
[(1, 3), (1, 4), (2, 3), (2, 1), (2, 4), (3, 1), (3, 4)]

y es equivalente a:

>>> combs = []
>>> for x in [1,2,3]:
...     for y in [3,1,4]:
...         if x != y:
...             combs.append((x, y))
...
>>> combs
[(1, 3), (1, 4), (2, 3), (2, 1), (2, 4), (3, 1), (3, 4)]

Notá como el orden de los for y if es el mismo en ambos pedacitos de código.

Si la expresión es una tupla (como el (x, y) en el ejemplo anterior), debe estar entre paréntesis.

>>> vec = [-4, -2, 0, 2, 4]
>>> # create a new list with the values doubled
>>> [x*2 for x in vec]
[-8, -4, 0, 4, 8]
>>> # filter the list to exclude negative numbers
>>> [x for x in vec if x >= 0]
[0, 2, 4]
>>> # apply a function to all the elements
>>> [abs(x) for x in vec]
[4, 2, 0, 2, 4]
>>> # call a method on each element
>>> freshfruit = ['  banana', '  loganberry ', 'passion fruit  ']
>>> [weapon.strip() for weapon in freshfruit]
['banana', 'loganberry', 'passion fruit']
>>> # create a list of 2-tuples like (number, square)
>>> [(x, x**2) for x in range(6)]
[(0, 0), (1, 1), (2, 4), (3, 9), (4, 16), (5, 25)]
>>> # the tuple must be parenthesized, otherwise an error is raised
>>> [x, x**2 for x in range(6)]
  File "<stdin>", line 1, in <module>
    [x, x**2 for x in range(6)]
               ^
SyntaxError: invalid syntax
>>> # flatten a list using a listcomp with two 'for'
>>> vec = [[1,2,3], [4,5,6], [7,8,9]]
>>> [num for elem in vec for num in elem]
[1, 2, 3, 4, 5, 6, 7, 8, 9]

Las comprensiones de listas pueden contener expresiones complejas y funciones anidadas:

>>> from math import pi
>>> [str(round(pi, i)) for i in range(1, 6)]
['3.1', '3.14', '3.142', '3.1416', '3.14159']

5.1.4. Listas por comprensión anidadas

La expresión inicial de una comprensión de listas puede ser cualquier expresión arbitraria, incluyendo otra comprensión de listas.

Considerá el siguiente ejemplo de una matriz de 3x4 implementada como una lista de tres listas de largo 4:

>>> matrix = [
...     [1, 2, 3, 4],
...     [5, 6, 7, 8],
...     [9, 10, 11, 12],
... ]

La siguiente comprensión de lista transpondrá las filas y columnas:

>>> [[row[i] for row in matrix] for i in range(4)]
[[1, 5, 9], [2, 6, 10], [3, 7, 11], [4, 8, 12]]

Como vimos en la sección anterior, la lista de comprensión anidada se evalúa en el contexto del for que lo sigue, por lo que este ejemplo equivale a:

>>> transposed = []
>>> for i in range(4):
...     transposed.append([row[i] for row in matrix])
...
>>> transposed
[[1, 5, 9], [2, 6, 10], [3, 7, 11], [4, 8, 12]]

el cual, a la vez, es lo mismo que:

>>> transposed = []
>>> for i in range(4):
...     # the following 3 lines implement the nested listcomp
...     transposed_row = []
...     for row in matrix:
...         transposed_row.append(row[i])
...     transposed.append(transposed_row)
...
>>> transposed
[[1, 5, 9], [2, 6, 10], [3, 7, 11], [4, 8, 12]]

En el mundo real, deberías preferir funciones predefinidas a declaraciones con flujo complejo. La función zip() haría un buen trabajo para este caso de uso:

>>> list(zip(*matrix))
[(1, 5, 9), (2, 6, 10), (3, 7, 11), (4, 8, 12)]

Ver Desempaquetando una lista de argumentos para detalles en el asterisco de esta línea.

5.2. La instrucción del

Hay una manera de quitar un ítem de una lista dado su índice en lugar de su valor: la instrucción del. Esta es diferente del método pop(), el cual retorna un valor. La instrucción del también puede usarse para quitar secciones de una lista o vaciar la lista completa (lo que hacíamos antes asignando una lista vacía a la sección). Por ejemplo:

>>> a = [-1, 1, 66.25, 333, 333, 1234.5]
>>> del a[0]
>>> a
[1, 66.25, 333, 333, 1234.5]
>>> del a[2:4]
>>> a
[1, 66.25, 1234.5]
>>> del a[:]
>>> a
[]

del puede usarse también para eliminar variables:

>>> del a

Hacer referencia al nombre a de aquí en más es un error (al menos hasta que se le asigne otro valor). Veremos otros usos para del más adelante.

5.3. Tuplas y secuencias

Vimos que las listas y cadenas tienen propiedades en común, como el indizado y las operaciones de seccionado. Estas son dos ejemplos de datos de tipo secuencia (ver Tipos secuencia — list, tuple, range). Como Python es un lenguaje en evolución, otros datos de tipo secuencia pueden agregarse. Existe otro dato de tipo secuencia estándar: la tupla.

Una tupla consiste de un número de valores separados por comas, por ejemplo:

>>> t = 12345, 54321, 'hello!'
>>> t[0]
12345
>>> t
(12345, 54321, 'hello!')
>>> # Tuples may be nested:
... u = t, (1, 2, 3, 4, 5)
>>> u
((12345, 54321, 'hello!'), (1, 2, 3, 4, 5))
>>> # Tuples are immutable:
... t[0] = 88888
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: 'tuple' object does not support item assignment
>>> # but they can contain mutable objects:
... v = ([1, 2, 3], [3, 2, 1])
>>> v
([1, 2, 3], [3, 2, 1])

Como puedes ver, en la salida las tuplas siempre se encierran entre paréntesis, para que las tuplas anidadas puedan interpretarse correctamente; pueden ingresarse con o sin paréntesis, aunque a menudo los paréntesis son necesarios de todas formas (si la tupla es parte de una expresión más grande). No es posible asignar a los ítems individuales de una tupla, pero sin embargo sí se puede crear tuplas que contengan objetos mutables, como las listas.

A pesar de que las tuplas puedan parecerse a las listas, frecuentemente se utilizan en distintas situaciones y para distintos propósitos. Las tuplas son immutable y normalmente contienen una secuencia heterogénea de elementos que son accedidos al desempaquetar (ver más adelante en esta sección) o indizar (o incluso acceder por atributo en el caso de las namedtuples). Las listas son mutable, y sus elementos son normalmente homogéneos y se acceden iterando a la lista.

Un problema particular es la construcción de tuplas que contengan 0 o 1 ítem: la sintaxis presenta algunas peculiaridades para estos casos. Las tuplas vacías se construyen mediante un par de paréntesis vacío; una tupla con un ítem se construye poniendo una coma a continuación del valor (no alcanza con encerrar un único valor entre paréntesis). Feo, pero efectivo. Por ejemplo:

>>> empty = ()
>>> singleton = 'hello',    # <-- note trailing comma
>>> len(empty)
0
>>> len(singleton)
1
>>> singleton
('hello',)

La declaración t = 12345, 54321, 'hola!' es un ejemplo de empaquetado de tuplas: los valores 12345, 54321 y 'hola!' se empaquetan juntos en una tupla. La operación inversa también es posible:

>>> x, y, z = t

Esto se llama, apropiadamente, desempaquetado de secuencias, y funciona para cualquier secuencia en el lado derecho del igual. El desempaquetado de secuencias requiere que la cantidad de variables a la izquierda del signo igual sea el tamaño de la secuencia. Notá que la asignación múltiple es en realidad sólo una combinación de empaquetado de tuplas y desempaquetado de secuencias.

5.4. Conjuntos

Python también incluye un tipo de dato para conjuntos. Un conjunto es una colección no ordenada y sin elementos repetidos. Los usos básicos de éstos incluyen verificación de pertenencia y eliminación de entradas duplicadas. Los conjuntos también soportan operaciones matemáticas como la unión, intersección, diferencia, y diferencia simétrica.

Las llaves o la función set() pueden usarse para crear conjuntos. Notá que para crear un conjunto vacío tenés que usar set(), no {}; esto último crea un diccionario vacío, una estructura de datos que discutiremos en la sección siguiente.

Una pequeña demostración:

>>> basket = {'apple', 'orange', 'apple', 'pear', 'orange', 'banana'}
>>> print(basket)                      # show that duplicates have been removed
{'orange', 'banana', 'pear', 'apple'}
>>> 'orange' in basket                 # fast membership testing
True
>>> 'crabgrass' in basket
False

>>> # Demonstrate set operations on unique letters from two words
...
>>> a = set('abracadabra')
>>> b = set('alacazam')
>>> a                                  # unique letters in a
{'a', 'r', 'b', 'c', 'd'}
>>> a - b                              # letters in a but not in b
{'r', 'd', 'b'}
>>> a | b                              # letters in a or b or both
{'a', 'c', 'r', 'd', 'b', 'm', 'z', 'l'}
>>> a & b                              # letters in both a and b
{'a', 'c'}
>>> a ^ b                              # letters in a or b but not both
{'r', 'd', 'b', 'm', 'z', 'l'}

De forma similar a las comprensiones de listas, está también soportada la comprensión de conjuntos:

>>> a = {x for x in 'abracadabra' if x not in 'abc'}
>>> a
{'r', 'd'}

5.5. Diccionarios

Otro tipo de dato útil incluido en Python es el diccionario (ver Tipos Mapa — dict). Los diccionarios se encuentran a veces en otros lenguajes como «memorias asociativas» o «arreglos asociativos». A diferencia de las secuencias, que se indexan mediante un rango numérico, los diccionarios se indexan con claves, que pueden ser cualquier tipo inmutable; las cadenas y números siempre pueden ser claves. Las tuplas pueden usarse como claves si solamente contienen cadenas, números o tuplas; si una tupla contiene cualquier objeto mutable directa o indirectamente, no puede usarse como clave. No podés usar listas como claves, ya que las listas pueden modificarse usando asignación por índice, asignación por sección, o métodos como append() y extend().

Es mejor pensar en un diccionario como un conjunto de pares clave:valor con el requerimiento de que las claves sean únicas (dentro de un diccionario). Un par de llaves crean un diccionario vacío: {}. Colocar una lista de pares clave:valor separada por comas dentro de las llaves agrega, de inicio, pares clave:valor al diccionario; esta es, también, la forma en que los diccionarios se muestran en la salida.

Las operaciones principales sobre un diccionario son guardar un valor con una clave y extraer ese valor dada la clave. También es posible borrar un par clave:valor con del. Si usás una clave que ya está en uso para guardar un valor, el valor que estaba asociado con esa clave se pierde. Es un error extraer un valor usando una clave no existente.

Ejecutando list(d) en un diccionario retornará una lista con todas las claves usadas en el diccionario, en el orden de inserción (si deseas que esté ordenada simplemente usa sorted(d) en su lugar). Para comprobar si una clave está en el diccionario usa la palabra clave in.

Un pequeño ejemplo de uso de un diccionario:

>>> tel = {'jack': 4098, 'sape': 4139}
>>> tel['guido'] = 4127
>>> tel
{'jack': 4098, 'sape': 4139, 'guido': 4127}
>>> tel['jack']
4098
>>> del tel['sape']
>>> tel['irv'] = 4127
>>> tel
{'jack': 4098, 'guido': 4127, 'irv': 4127}
>>> list(tel)
['jack', 'guido', 'irv']
>>> sorted(tel)
['guido', 'irv', 'jack']
>>> 'guido' in tel
True
>>> 'jack' not in tel
False

El constructor dict() crea un diccionario directamente desde secuencias de pares clave-valor:

>>> dict([('sape', 4139), ('guido', 4127), ('jack', 4098)])
{'sape': 4139, 'guido': 4127, 'jack': 4098}

Además, las comprensiones de diccionarios se pueden usar para crear diccionarios desde expresiones arbitrarias de clave y valor:

>>> {x: x**2 for x in (2, 4, 6)}
{2: 4, 4: 16, 6: 36}

Cuando las claves son cadenas simples, a veces resulta más fácil especificar los pares usando argumentos por palabra clave:

>>> dict(sape=4139, guido=4127, jack=4098)
{'sape': 4139, 'guido': 4127, 'jack': 4098}

5.6. Técnicas de iteración

Cuando iteramos sobre diccionarios, se pueden obtener al mismo tiempo la clave y su valor correspondiente usando el método items().

>>> knights = {'gallahad': 'the pure', 'robin': 'the brave'}
>>> for k, v in knights.items():
...     print(k, v)
...
gallahad the pure
robin the brave

Cuando se itera sobre una secuencia, se puede obtener el índice de posición junto a su valor correspondiente usando la función enumerate().

>>> for i, v in enumerate(['tic', 'tac', 'toe']):
...     print(i, v)
...
0 tic
1 tac
2 toe

Para iterar sobre dos o más secuencias al mismo tiempo, los valores pueden emparejarse con la función zip().

>>> questions = ['name', 'quest', 'favorite color']
>>> answers = ['lancelot', 'the holy grail', 'blue']
>>> for q, a in zip(questions, answers):
...     print('What is your {0}?  It is {1}.'.format(q, a))
...
What is your name?  It is lancelot.
What is your quest?  It is the holy grail.
What is your favorite color?  It is blue.

Para iterar sobre una secuencia en orden inverso, se especifica primero la secuencia al derecho y luego se llama a la función reversed().

>>> for i in reversed(range(1, 10, 2)):
...     print(i)
...
9
7
5
3
1

Para iterar sobre una secuencia ordenada, se utiliza la función sorted() la cual retorna una nueva lista ordenada dejando a la original intacta.

>>> basket = ['apple', 'orange', 'apple', 'pear', 'orange', 'banana']
>>> for i in sorted(basket):
...     print(i)
...
apple
apple
banana
orange
orange
pear

El uso de set() en una secuencia elimina los elementos duplicados. El uso de sorted() en combinación con set() sobre una secuencia es una forma idiomática de recorrer elementos únicos de la secuencia en orden ordenado.

>>> basket = ['apple', 'orange', 'apple', 'pear', 'orange', 'banana']
>>> for f in sorted(set(basket)):
...     print(f)
...
apple
banana
orange
pear

A veces uno intenta cambiar una lista mientras la está iterando; sin embargo, a menudo es más simple y seguro crear una nueva lista:

>>> import math
>>> raw_data = [56.2, float('NaN'), 51.7, 55.3, 52.5, float('NaN'), 47.8]
>>> filtered_data = []
>>> for value in raw_data:
...     if not math.isnan(value):
...         filtered_data.append(value)
...
>>> filtered_data
[56.2, 51.7, 55.3, 52.5, 47.8]

5.7. Más acerca de condiciones

Las condiciones usadas en las instrucciones while e if pueden contener cualquier operador, no sólo comparaciones.

The comparison operators in and not in check whether a value occurs (does not occur) in a sequence. The operators is and is not compare whether two objects are really the same object. All comparison operators have the same priority, which is lower than that of all numerical operators.

Las comparaciones pueden encadenarse. Por ejemplo, a < b == c verifica si a es menor que b y además si b es igual a c.

Las comparaciones pueden combinarse mediante los operadores booleanos and y or, y el resultado de una comparación (o de cualquier otra expresión booleana) puede negarse con not. Estos tienen prioridades menores que los operadores de comparación; entre ellos not tiene la mayor prioridad y or la menor, o sea que A and not B or C equivale a (A and (not B)) or C. Como siempre, los paréntesis pueden usarse para expresar la composición deseada.

Los operadores booleanos and y or son los llamados operadores cortocircuito: sus argumentos se evalúan de izquierda a derecha, y la evaluación se detiene en el momento en que se determina su resultado. Por ejemplo, si A y C son verdaderas pero B es falsa, en A and B and C no se evalúa la expresión C. Cuando se usa como un valor general y no como un booleano, el valor retornado de un operador cortocircuito es el último argumento evaluado.

Es posible asignar el resultado de una comparación u otra expresión booleana a una variable. Por ejemplo,

>>> string1, string2, string3 = '', 'Trondheim', 'Hammer Dance'
>>> non_null = string1 or string2 or string3
>>> non_null
'Trondheim'

Nota que en Python, a diferencia de C, asignaciones dentro de expresiones deben realizarse explícitamente con walrus operator :=. Esto soluciona algunos problemas comunes encontrados en C: escribiendo = en una expresión cuando se intentaba escribir ==.

5.8. Comparando secuencias y otros tipos

Las secuencias pueden compararse con otros objetos del mismo tipo de secuencia. La comparación usa orden lexicográfico: primero se comparan los dos primeros ítems, si son diferentes esto ya determina el resultado de la comparación; si son iguales, se comparan los siguientes dos ítems, y así sucesivamente hasta llegar al final de alguna de las secuencias. Si dos ítems a comparar son ambos secuencias del mismo tipo, la comparación lexicográfica es recursiva. Si todos los ítems de dos secuencias resultan iguales, se considera que las secuencias son iguales. Si una secuencia es la parte inicial de la otra, la secuencia más corta es la más pequeña. El orden lexicográfico de los strings utiliza el punto de código Unicode para ordenar caracteres individuales. Algunos ejemplos de comparación entre secuencias del mismo tipo:

(1, 2, 3)              < (1, 2, 4)
[1, 2, 3]              < [1, 2, 4]
'ABC' < 'C' < 'Pascal' < 'Python'
(1, 2, 3, 4)           < (1, 2, 4)
(1, 2)                 < (1, 2, -1)
(1, 2, 3)             == (1.0, 2.0, 3.0)
(1, 2, ('aa', 'ab'))   < (1, 2, ('abc', 'a'), 4)

Observá que comparar objetos de diferentes tipos con < o > es legal siempre y cuando los objetas tenga los métodos de comparación apropiados. Por ejemplo, los tipos de números mezclados son comparados de acuerdo a su valor numérico, o sea 0 es igual a 0.0, etc. Si no es el caso, en lugar de proveer un ordenamiento arbitrario, el intérprete generará una excepción TypeError.

Notas al pie

1

Otros lenguajes podrían retornar un objeto mutado, que permite encadenamiento de métodos como d->insert("a")->remove("b")->sort();.

6. Módulos

Si sales del intérprete de Python y vuelves a entrar, las definiciones que habías hecho (funciones y variables) se pierden. Por lo tanto, si quieres escribir un programa más o menos largo, es mejor que utilices un editor de texto para preparar la entrada para el intérprete y ejecutarlo con ese archivo como entrada. Esto se conoce como crear un script. A medida que tu programa crezca, quizás quieras separarlo en varios archivos para que el mantenimiento sea más sencillo. Quizás también quieras usar una función útil que has escrito en distintos programas sin copiar su definición en cada programa.

Para soportar esto, Python tiene una manera de poner definiciones en un archivo y usarlos en un script o en una instancia del intérprete. Este tipo de ficheros se llama módulo; las definiciones de un módulo pueden ser importadas a otros módulos o al módulo principal (la colección de variables a las que tienes acceso en un script ejecutado en el nivel superior y en el modo calculadora).

Un módulo es un fichero conteniendo definiciones y declaraciones de Python. El nombre de archivo es el nombre del módulo con el sufijo .py agregado. Dentro de un módulo, el nombre del mismo módulo (como cadena) está disponible en el valor de la variable global __name__. Por ejemplo, utiliza tu editor de texto favorito para crear un archivo llamado fibo.py en el directorio actual, con el siguiente contenido:

# Fibonacci numbers module

def fib(n):    # write Fibonacci series up to n
    a, b = 0, 1
    while a < n:
        print(a, end=' ')
        a, b = b, a+b
    print()

def fib2(n):   # return Fibonacci series up to n
    result = []
    a, b = 0, 1
    while a < n:
        result.append(a)
        a, b = b, a+b
    return result

Ahora entra en el intérprete de Python e importa este modulo con el siguiente comando:

>>> import fibo

Esto no añade los nombres de las funciones definidas en fibo directamente en el espacio de nombres actual; sólo añade el nombre del módulo fibo. Usando el nombre del módulo puedes acceder a las funciones:

>>> fibo.fib(1000)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
>>> fibo.fib2(100)
[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
>>> fibo.__name__
'fibo'

Si pretendes utilizar una función frecuentemente puedes asignarla a un nombre local:

>>> fib = fibo.fib
>>> fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

6.1. Más sobre los módulos

Un módulo puede contener tanto declaraciones ejecutables como definiciones de funciones. Estas declaraciones están pensadas para inicializar el módulo. Se ejecutan únicamente la primera vez que el módulo se encuentra en una declaración import. 1 (También se ejecutan si el archivo se ejecuta como script.)

Cada módulo tiene su propio espacio de nombres, el cual es usado como espacio de nombres global para todas las funciones definidas en el módulo. Por lo tanto, el autor de un módulo puede usar variables globales en el módulo sin preocuparse acerca de conflictos con una variable global del usuario. Por otro lado, si sabes lo que estás haciendo puedes acceder a las variables globales de un módulo con la misma notación usada para referirte a sus funciones, nombremodulo.nombreitem.

Los módulos pueden importar otros módulos. Es costumbre pero no obligatorio ubicar todas las declaraciones import al principio del módulo (o script, para el caso). Los nombres de los módulos importados son ubicados en el espacio de nombres global del módulo que hace la importación.

Hay una variante de la declaración import que importa nos nombres de un módulo directamente al espacio de nombres del módulo que hace la importación. Por ejemplo:

>>> from fibo import fib, fib2
>>> fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

Esto no introduce en el espacio de nombres local el nombre del módulo desde el cual se está importando (por lo tanto, en el ejemplo, fibo no esta definido).

Hay incluso una variante para importar todos los nombres que un módulo define:

>>> from fibo import *
>>> fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

Esto importa todos los nombres excepto los que inician con un guión bajo (_). La mayoría de las veces los programadores de Python no usan esto ya que introduce en el intérprete un conjunto de nombres desconocido, posiblemente escondiendo algunas de las definiciones previas.

Nota que en general la práctica de importar * de un módulo o paquete está muy mal vista, ya que frecuentemente genera código poco legible. Sin embargo, está bien usarlo para ahorrar tecleo en sesiones interactivas.

Si el nombre del módulo es seguido por as, el nombre siguiendo as queda ligado directamente al módulo importado.

>>> import fibo as fib
>>> fib.fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

Esto es básicamente importar el módulo de la misma forma que se haría con import fibo, con la única diferencia en que se encuentra accesible como fib.

También se puede utilizar cuando se utiliza from con efectos similares:

>>> from fibo import fib as fibonacci
>>> fibonacci(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

Nota

Por razones de eficiencia, cada módulo es importado solo una vez por sesión del intérprete. Por lo tanto, si cambias tus módulos, debes reiniciar el interprete – ó, si es un solo módulo que quieres probar de forma interactiva, usa importlib.reload(), por ejemplo: import importlib; importlib.reload(modulename).

6.1.1. Ejecutando módulos como scripts

Cuando ejecutes un módulo de Python con

python fibo.py <arguments>

el código en el módulo será ejecutado, tal como si lo hubieses importado, pero con __name__ con el valor de "__main__". Eso significa que agregando este código al final de tu módulo:

if __name__ == "__main__":
    import sys
    fib(int(sys.argv[1]))

puedes hacer que el archivo sea utilizable tanto como script, como módulo importable, porque el código que analiza la línea de órdenes sólo se ejecuta si el módulo es ejecutado como archivo principal:

$ python fibo.py 50
0 1 1 2 3 5 8 13 21 34

Si el módulo se importa, ese código no se ejecuta:

>>> import fibo
>>>

Esto es frecuentemente usado para proveer al módulo una interfaz de usuario conveniente, o para propósitos de prueba (ejecutar el módulo como un script ejecuta el juego de pruebas).

6.1.2. El camino de búsqueda de los módulos

When a module named spam is imported, the interpreter first searches for a built-in module with that name. These module names are listed in sys.builtin_module_names. If not found, it then searches for a file named spam.py in a list of directories given by the variable sys.path. sys.path is initialized from these locations:

El directorio que contiene el script de entrada (o el directorio actual cuando no se especifica archivo).

PYTHONPATH (una lista de nombres de directorios, con la misma sintaxis que la variable de la terminal PATH).

The installation-dependent default (by convention including a site-packages directory, handled by the site module).

Nota

En los sistemas de archivo que soportan enlaces simbólicos, el directorio que contiene el script de entrada es calculado luego de seguir el enlace simbólico. En otras palabras, el directorio que contiene el enlace simbólico no es agregado al camino de búsqueda del módulo.

Luego de la inicialización, los programas Python pueden modificar sys.path. El directorio que contiene el script que se está ejecutando se ubica al principio de la búsqueda, adelante de la biblioteca estándar. Esto significa que se cargarán scripts en ese directorio en lugar de módulos de la biblioteca estándar con el mismo nombre. Esto es un error a menos que se esté reemplazando intencionalmente. Mirá la sección Módulos estándar para más información.

6.1.3. Archivos «compilados» de Python

Para acelerar la carga de módulos, Python cachea las versiones compiladas de cada módulo en el directorio __pycache__ bajo el nombre module.version.pyc, dónde la versión codifica el formato del archivo compilado; generalmente contiene el número de versión de Python. Por ejemplo, en CPython release 3.3 la versión compilada de spam.py sería cacheada como __pycache__/spam.cpython-33.pyc. Este convención de nombre permite compilar módulos desde diferentes releases y versiones de Python para coexistir.

Python chequea la fecha de modificación de la fuente contra la versión compilada para ver si esta es obsoleta y necesita ser recompilada. Esto es un proceso completamente automático. También, los módulos compilados son independientes de la plataforma, así que la misma biblioteca puede ser compartida a través de sistemas con diferentes arquitecturas.

Python no chequea el caché en dos circunstancias. Primero, siempre recompila y no graba el resultado del módulo que es cargado directamente desde la línea de comando. Segundo, no chequea el caché si no hay módulo fuente. Para soportar una distribución sin fuente (solo compilada), el módulo compilado debe estar en el directorio origen, y no debe haber un módulo fuente.

Algunos consejos para expertos:

Puedes usar los modificadores -O o -OO en el comando de Python para reducir el tamaño del módulo compilado. El modificador -O remueve las declaraciones assert, el modificador -OO remueve declaraciones assert y cadenas __doc__. Dado que algunos programas pueden confiar en tenerlos disponibles, solo deberías usar esta opción si conoces lo que estás haciendo. Los módulos «optimizados» tienen una etiqueta opt- y generalmente son mas pequeños. Releases futuras pueden cambiar los efectos de la optimización.

Un programa no se ejecuta mas rápido cuando es leído de un archivo .pyc que cuando es leído de un archivo .py; la única cosa que es mas rápida en los archivos .pyc es la velocidad con la cual son cargados.

El módulo compileall puede crear archivos .pyc para todos los módulos en un directorio.

Hay mas detalle de este proceso, incluyendo un diagrama de flujo de decisiones, en PEP 3147 [https://www.python.org/dev/peps/pep-3147].

6.2. Módulos estándar

Python viene con una biblioteca de módulos estándar, descrita en un documento separado, la Referencia de la Biblioteca de Python (de aquí en más, «Referencia de la Biblioteca»). Algunos módulos se integran en el intérprete; estos proveen acceso a operaciones que no son parte del núcleo del lenguaje pero que sin embargo están integrados, tanto por eficiencia como para proveer acceso a primitivas del sistema operativo, como llamadas al sistema. El conjunto de tales módulos es una opción de configuración el cual también depende de la plataforma subyacente. Por ejemplo, el módulo winreg sólo se provee en sistemas Windows. Un módulo en particular merece algo de atención: sys, el que está integrado en todos los intérpretes de Python. Las variables sys.ps1 y sys.ps2 definen las cadenas usadas como cursores primarios y secundarios:

>>> import sys
>>> sys.ps1
'>>> '
>>> sys.ps2
'... '
>>> sys.ps1 = 'C> '
C> print('Yuck!')
Yuck!
C>

Estas dos variables están solamente definidas si el intérprete está en modo interactivo.

La variable sys.path es una lista de cadenas que determinan el camino de búsqueda del intérprete para los módulos. Se inicializa por omisión a un camino tomado de la variable de entorno PYTHONPATH, o a un valor predefinido en el intérprete si PYTHONPATH no está configurada. Lo puedes modificar usando las operaciones estándar de listas:

>>> import sys
>>> sys.path.append('/ufs/guido/lib/python')

6.3. La función dir()

La función integrada dir() se usa para encontrar qué nombres define un módulo. Retorna una lista ordenada de cadenas:

>>> import fibo, sys
>>> dir(fibo)
['__name__', 'fib', 'fib2']
>>> dir(sys)
['__breakpointhook__', '__displayhook__', '__doc__', '__excepthook__',
 '__interactivehook__', '__loader__', '__name__', '__package__', '__spec__',
 '__stderr__', '__stdin__', '__stdout__', '__unraisablehook__',
 '_clear_type_cache', '_current_frames', '_debugmallocstats', '_framework',
 '_getframe', '_git', '_home', '_xoptions', 'abiflags', 'addaudithook',
 'api_version', 'argv', 'audit', 'base_exec_prefix', 'base_prefix',
 'breakpointhook', 'builtin_module_names', 'byteorder', 'call_tracing',
 'callstats', 'copyright', 'displayhook', 'dont_write_bytecode', 'exc_info',
 'excepthook', 'exec_prefix', 'executable', 'exit', 'flags', 'float_info',
 'float_repr_style', 'get_asyncgen_hooks', 'get_coroutine_origin_tracking_depth',
 'getallocatedblocks', 'getdefaultencoding', 'getdlopenflags',
 'getfilesystemencodeerrors', 'getfilesystemencoding', 'getprofile',
 'getrecursionlimit', 'getrefcount', 'getsizeof', 'getswitchinterval',
 'gettrace', 'hash_info', 'hexversion', 'implementation', 'int_info',
 'intern', 'is_finalizing', 'last_traceback', 'last_type', 'last_value',
 'maxsize', 'maxunicode', 'meta_path', 'modules', 'path', 'path_hooks',
 'path_importer_cache', 'platform', 'prefix', 'ps1', 'ps2', 'pycache_prefix',
 'set_asyncgen_hooks', 'set_coroutine_origin_tracking_depth', 'setdlopenflags',
 'setprofile', 'setrecursionlimit', 'setswitchinterval', 'settrace', 'stderr',
 'stdin', 'stdout', 'thread_info', 'unraisablehook', 'version', 'version_info',
 'warnoptions']

Sin argumentos, dir() lista los nombres que tienes actualmente definidos:

>>> a = [1, 2, 3, 4, 5]
>>> import fibo
>>> fib = fibo.fib
>>> dir()
['__builtins__', '__name__', 'a', 'fib', 'fibo', 'sys']

Note que lista todos los tipos de nombres: variables, módulos, funciones, etc.

dir() no lista los nombres de las funciones y variables integradas. Si quieres una lista de esos, están definidos en el módulo estándar builtins:

>>> import builtins
>>> dir(builtins)
['ArithmeticError', 'AssertionError', 'AttributeError', 'BaseException',
 'BlockingIOError', 'BrokenPipeError', 'BufferError', 'BytesWarning',
 'ChildProcessError', 'ConnectionAbortedError', 'ConnectionError',
 'ConnectionRefusedError', 'ConnectionResetError', 'DeprecationWarning',
 'EOFError', 'Ellipsis', 'EnvironmentError', 'Exception', 'False',
 'FileExistsError', 'FileNotFoundError', 'FloatingPointError',
 'FutureWarning', 'GeneratorExit', 'IOError', 'ImportError',
 'ImportWarning', 'IndentationError', 'IndexError', 'InterruptedError',
 'IsADirectoryError', 'KeyError', 'KeyboardInterrupt', 'LookupError',
 'MemoryError', 'NameError', 'None', 'NotADirectoryError', 'NotImplemented',
 'NotImplementedError', 'OSError', 'OverflowError',
 'PendingDeprecationWarning', 'PermissionError', 'ProcessLookupError',
 'ReferenceError', 'ResourceWarning', 'RuntimeError', 'RuntimeWarning',
 'StopIteration', 'SyntaxError', 'SyntaxWarning', 'SystemError',
 'SystemExit', 'TabError', 'TimeoutError', 'True', 'TypeError',
 'UnboundLocalError', 'UnicodeDecodeError', 'UnicodeEncodeError',
 'UnicodeError', 'UnicodeTranslateError', 'UnicodeWarning', 'UserWarning',
 'ValueError', 'Warning', 'ZeroDivisionError', '_', '__build_class__',
 '__debug__', '__doc__', '__import__', '__name__', '__package__', 'abs',
 'all', 'any', 'ascii', 'bin', 'bool', 'bytearray', 'bytes', 'callable',
 'chr', 'classmethod', 'compile', 'complex', 'copyright', 'credits',
 'delattr', 'dict', 'dir', 'divmod', 'enumerate', 'eval', 'exec', 'exit',
 'filter', 'float', 'format', 'frozenset', 'getattr', 'globals', 'hasattr',
 'hash', 'help', 'hex', 'id', 'input', 'int', 'isinstance', 'issubclass',
 'iter', 'len', 'license', 'list', 'locals', 'map', 'max', 'memoryview',
 'min', 'next', 'object', 'oct', 'open', 'ord', 'pow', 'print', 'property',
 'quit', 'range', 'repr', 'reversed', 'round', 'set', 'setattr', 'slice',
 'sorted', 'staticmethod', 'str', 'sum', 'super', 'tuple', 'type', 'vars',
 'zip']

6.4. Paquetes

Los Paquetes son una forma de estructurar el espacio de nombres de módulos de Python usando «nombres de módulo con puntos». Por ejemplo, el nombre del módulo A.B designa un submódulo B en un paquete llamado A. Así como el uso de módulos salva a los autores de diferentes módulos de tener que preocuparse por los nombres de las variables globales de cada uno, el uso de nombres de módulo con puntos salva a los autores de paquetes con múltiples módulos, como NumPy o Pillow de preocupaciones por los nombres de los módulos de cada uno.

Supongamos que quieres designar una colección de módulos (un «paquete») para el manejo uniforme de archivos y datos de sonidos. Hay diferentes formatos de archivos de sonido (normalmente reconocidos por su extensión, por ejemplo: .wav, .aiff, .au), por lo que tienes que crear y mantener una colección siempre creciente de módulos para la conversión entre los distintos formatos de archivos. Hay muchas operaciones diferentes que quizás quieras ejecutar en los datos de sonido (como mezclarlos, añadir eco, aplicar una función ecualizadora, crear un efecto estéreo artificial), por lo que además estarás escribiendo una lista sin fin de módulos para realizar estas operaciones. Aquí hay una posible estructura para tu paquete (expresados en términos de un sistema jerárquico de archivos):

sound/                          Top-level package
      __init__.py               Initialize the sound package
      formats/                  Subpackage for file format conversions
              __init__.py
              wavread.py
              wavwrite.py
              aiffread.py
              aiffwrite.py
              auread.py
              auwrite.py
              ...
      effects/                  Subpackage for sound effects
              __init__.py
              echo.py
              surround.py
              reverse.py
              ...
      filters/                  Subpackage for filters
              __init__.py
              equalizer.py
              vocoder.py
              karaoke.py
              ...

Al importar el paquete, Python busca a través de los directorios en sys.path, buscando el sub-directorio del paquete.

Los archivos __init__.py son obligatorios para que Python trate los directorios que contienen los archivos como paquetes. Esto evita que los directorios con un nombre común, como string, oculten involuntariamente módulos válidos que se producen luego en el camino de búsqueda del módulo. En el caso mas simple, __init__.py puede ser solo un archivo vacío, pero también puede ejecutar código de inicialización para el paquete o el conjunto de variables __all__, descriptas luego.

Los usuarios del paquete pueden importar módulos individuales del mismo, por ejemplo:

import sound.effects.echo

Esto carga el submódulo sound.effects.echo. Debe hacerse referencia al mismo con el nombre completo.

sound.effects.echo.echofilter(input, output, delay=0.7, atten=4)

Otra alternativa para importar el submódulo es:

from sound.effects import echo

Esto también carga el submódulo echo, y lo deja disponible sin su prefijo de paquete, por lo que puede usarse así:

echo.echofilter(input, output, delay=0.7, atten=4)

Otra variación más es importar la función o variable deseadas directamente:

from sound.effects.echo import echofilter

De nuevo, esto carga el submódulo echo, pero deja directamente disponible a la función echofilter():

echofilter(input, output, delay=0.7, atten=4)

Note que al usar from package import item, el ítem puede ser tanto un submódulo (o subpaquete) del paquete, o algún otro nombre definido en el paquete, como una función, clase, o variable. La declaración import primero verifica si el ítem está definido en el paquete; si no, asume que es un módulo y trata de cargarlo. Si no lo puede encontrar, se genera una excepción ImportError.

Por otro lado, cuando se usa la sintaxis como import item.subitem.subsubitem, cada ítem excepto el último debe ser un paquete; el mismo puede ser un módulo o un paquete pero no puede ser una clase, función o variable definida en el ítem previo.

6.4.1. Importando * desde un paquete

Ahora, ¿qué sucede cuando el usuario escribe from sound.effects import *? Idealmente, uno esperaría que esto de alguna manera vaya al sistema de archivos, encuentre cuales submódulos están presentes en el paquete, y los importe a todos. Esto puede tardar mucho y el importar sub-módulos puede tener efectos secundarios no deseados que sólo deberían ocurrir cuando se importe explícitamente el sub-módulo.

La única solución es que el autor del paquete provea un índice explícito del paquete. La declaración import usa la siguiente convención: si el código del __init__.py de un paquete define una lista llamada __all__, se toma como la lista de los nombres de módulos que deberían ser importados cuando se hace from package import *. Es tarea del autor del paquete mantener actualizada esta lista cuando se libera una nueva versión del paquete. Los autores de paquetes podrían decidir no soportarlo, si no ven un uso para importar * en sus paquetes. Por ejemplo, el archivo sound/effects/__init__.py podría contener el siguiente código:

__all__ = ["echo", "surround", "reverse"]

This would mean that from sound.effects import * would import the three named submodules of the sound.effects package.

Si no se define __all__, la declaración from sound.effects import * no importa todos los submódulos del paquete sound.effects al espacio de nombres actual; sólo se asegura que se haya importado el paquete sound.effects (posiblemente ejecutando algún código de inicialización que haya en __init__.py) y luego importa aquellos nombres que estén definidos en el paquete. Esto incluye cualquier nombre definido (y submódulos explícitamente cargados) por __init__.py. También incluye cualquier submódulo del paquete que pudiera haber sido explícitamente cargado por declaraciones import previas. Considere este código:

import sound.effects.echo
import sound.effects.surround
from sound.effects import *

En este ejemplo, los módulos echo y surround se importan en el espacio de nombre actual porque están definidos en el paquete sound.effects cuando se ejecuta la declaración from...import. (Esto también funciona cuando se define __all__).

A pesar de que ciertos módulos están diseñados para exportar solo nombres que siguen ciertos patrones cuando uses import *, también se considera una mala práctica en código de producción.

Recuerda, ¡no hay nada malo al usar from package import specific_submodule! De hecho, esta es la notación recomendada a menos que el módulo que importamos necesite usar submódulos con el mismo nombre desde un paquete diferente.

6.4.2. Referencias internas en paquetes

Cuando se estructuran los paquetes en sub-paquetes (como en el ejemplo sound), puedes usar import absolutos para referirte a submódulos de paquetes hermanos. Por ejemplo, si el módulo sound.filters.vocoder necesita usar el módulo echo en el paquete sound.effects, puede hacer from sound.effects import echo.

También puedes escribir import relativos con la forma from module import name. Estos imports usan puntos adelante para indicar los paquetes actuales o paquetes padres involucrados en el import relativo. En el ejemplo surround, podrías hacer:

from . import echo
from .. import formats
from ..filters import equalizer

Note que los imports relativos se basan en el nombre del módulo actual. Ya que el nombre del módulo principal es siempre "__main__", los módulos pensados para usarse como módulo principal de una aplicación Python siempre deberían usar import absolutos.

6.4.3. Paquetes en múltiples directorios

Los paquetes soportan un atributo especial más, __path__. Este se inicializa a una lista que contiene el nombre del directorio donde está el archivo __init__.py del paquete, antes de que el código en ese archivo se ejecute. Esta variable puede modificarse, afectando búsquedas futuras de módulos y subpaquetes contenidos en el paquete.

Aunque esta característica no se necesita frecuentemente, puede usarse para extender el conjunto de módulos que se encuentran en el paquete.

Notas al pie

1

De hecho, las definiciones de funciones también son «declaraciones» que se «ejecutan»; la ejecución de una definición de función a nivel de módulo, ingresa el nombre de la función en el espacio de nombres global del módulo.

7. Entrada y salida

Hay diferentes métodos de presentar la salida de un programa; los datos pueden ser impresos de una forma legible por humanos, o escritos a un archivo para uso futuro. Este capítulo discutirá algunas de las posibilidades.

7.1. Formateo elegante de la salida

Hasta ahora encontramos dos maneras de escribir valores: declaraciones de expresión y la función print(). (Una tercera manera es usando el método write() de los objetos tipo archivo; el archivo de salida estándar puede referenciarse como sys.stdout. Mirá la Referencia de la Biblioteca para más información sobre esto).

A menudo se querrá tener más control sobre el formato de la salida, y no simplemente imprimir valores separados por espacios. Para ello, hay varias maneras de dar formato a la salida.

Para usar formatted string literals, comience una cadena con f o F antes de la comilla de apertura o comillas triples. Dentro de esta cadena, se puede escribir una expresión de Python entre los caracteres { y } que pueden hacer referencia a variables o valores literales.

>>> year = 2016
>>> event = 'Referendum'
>>> f'Results of the {year} {event}'
'Results of the 2016 Referendum'

El método str.format() requiere más esfuerzo manual. Se seguirá usando { y } para marcar dónde se sustituirá una variable y puede proporcionar directivas de formato detalladas, pero también se debe proporcionar la información de lo que se va a formatear.

>>> yes_votes = 42_572_654
>>> no_votes = 43_132_495
>>> percentage = yes_votes / (yes_votes + no_votes)
>>> '{:-9} YES votes  {:2.2%}'.format(yes_votes, percentage)
' 42572654 YES votes  49.67%'

Por último, puede realizar todo el control de cadenas usted mismo mediante operaciones de concatenación y segmentación de cadenas para crear cualquier diseño que se pueda imaginar. El tipo de cadena tiene algunos métodos que realizan operaciones útiles para rellenar cadenas a un ancho de columna determinado.

Cuando no necesita una salida elegante, pero solo desea una visualización rápida de algunas variables con fines de depuración, puede convertir cualquier valor en una cadena con las funciones repr() o str().

La función str() retorna representaciones de los valores que son bastante legibles por humanos, mientras que repr() genera representaciones que pueden ser leídas por el intérprete (o forzarían un SyntaxError si no hay sintaxis equivalente). Para objetos que no tienen una representación en particular para consumo humano, str() retornará el mismo valor que repr(). Muchos valores, como números o estructuras como listas y diccionarios, tienen la misma representación usando cualquiera de las dos funciones. Las cadenas, en particular, tienen dos representaciones distintas.

Algunos ejemplos:

>>> s = 'Hello, world.'
>>> str(s)
'Hello, world.'
>>> repr(s)
"'Hello, world.'"
>>> str(1/7)
'0.14285714285714285'
>>> x = 10 * 3.25
>>> y = 200 * 200
>>> s = 'The value of x is ' + repr(x) + ', and y is ' + repr(y) + '...'
>>> print(s)
The value of x is 32.5, and y is 40000...
>>> # The repr() of a string adds string quotes and backslashes:
... hello = 'hello, world\n'
>>> hellos = repr(hello)
>>> print(hellos)
'hello, world\n'
>>> # The argument to repr() may be any Python object:
... repr((x, y, ('spam', 'eggs')))
"(32.5, 40000, ('spam', 'eggs'))"

El módulo string contiene una clase Template que ofrece otra forma de sustituir valores en cadenas, utilizando marcadores de posición como $x` y reemplazarlos con valores desde un diccionario, pero esto ofrece mucho menos control en el formato.

7.1.1. Formatear cadenas literales

Formatted string literals (también llamados f-strings para abreviar) le permiten incluir el valor de las expresiones de Python dentro de una cadena prefijando la cadena con f o F y escribiendo expresiones como {expresion}.

La expresión puede ir seguida de un especificador de formato opcional . Esto permite un mayor control sobre cómo se formatea el valor. En el ejemplo siguiente se redondea pi a tres lugares después del decimal:

>>> import math
>>> print(f'The value of pi is approximately {math.pi:.3f}.')
The value of pi is approximately 3.142.

Pasar un entero después de ':' hará que ese campo sea un número mínimo de caracteres de ancho. Esto es útil para hacer que las columnas se alineen.

>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 7678}
>>> for name, phone in table.items():
...     print(f'{name:10} ==> {phone:10d}')
...
Sjoerd     ==>       4127
Jack       ==>       4098
Dcab       ==>       7678

Se pueden utilizar otros modificadores para convertir el valor antes de formatearlo. '!a' se aplica ascii(), '!s' se aplica str(), y '!r' se aplica repr():

>>> animals = 'eels'
>>> print(f'My hovercraft is full of {animals}.')
My hovercraft is full of eels.
>>> print(f'My hovercraft is full of {animals!r}.')
My hovercraft is full of 'eels'.

Para obtener una referencia sobre estas especificaciones de formato, consulte la guía de referencia para Especificación de formato Mini-Lenguaje.

7.1.2. El método format() de cadenas

El uso básico del método str.format() es como esto:

>>> print('We are the {} who say "{}!"'.format('knights', 'Ni'))
We are the knights who say "Ni!"

Las llaves y caracteres dentro de las mismas (llamados campos de formato) son reemplazadas con los objetos pasados en el método str.format(). Un número en las llaves se refiere a la posición del objeto pasado en el método str.format().

>>> print('{0} and {1}'.format('spam', 'eggs'))
spam and eggs
>>> print('{1} and {0}'.format('spam', 'eggs'))
eggs and spam

Si se usan argumentos nombrados en el método str.format(), sus valores se referencian usando el nombre del argumento.

>>> print('This {food} is {adjective}.'.format(
...       food='spam', adjective='absolutely horrible'))
This spam is absolutely horrible.

Se pueden combinar arbitrariamente argumentos posicionales y nombrados:

>>> print('The story of {0}, {1}, and {other}.'.format('Bill', 'Manfred',
                                                       other='Georg'))
The story of Bill, Manfred, and Georg.

Si tiene una cadena de caracteres de formato realmente larga que no desea dividir, sería bueno si pudiera hacer referencia a las variables que se formatearán por nombre en lugar de por posición. Esto se puede hacer simplemente pasando el dict y usando corchetes '[]' para acceder a las claves.

>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
>>> print('Jack: {0[Jack]:d}; Sjoerd: {0[Sjoerd]:d}; '
...       'Dcab: {0[Dcab]:d}'.format(table))
Jack: 4098; Sjoerd: 4127; Dcab: 8637678

Esto se podría hacer, también, pasando la tabla como argumentos nombrados con la notación “**”.

>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
>>> print('Jack: {Jack:d}; Sjoerd: {Sjoerd:d}; Dcab: {Dcab:d}'.format(**table))
Jack: 4098; Sjoerd: 4127; Dcab: 8637678

Esto es particularmente útil en combinación con la función integrada vars(), que retorna un diccionario conteniendo todas las variables locales.

Como ejemplo, las siguientes lineas producen un conjunto de columnas alineadas ordenadamente que dan enteros y sus cuadrados y cubos:

>>> for x in range(1, 11):
...     print('{0:2d} {1:3d} {2:4d}'.format(x, x*x, x*x*x))
...
 1   1    1
 2   4    8
 3   9   27
 4  16   64
 5  25  125
 6  36  216
 7  49  343
 8  64  512
 9  81  729
10 100 1000

Para una completa descripción del formateo de cadenas con str.format(), mirá en Formato de cadena de caracteres personalizado.

7.1.3. Formateo manual de cadenas

Aquí está la misma tabla de cuadrados y cubos, formateados manualmente:

>>> for x in range(1, 11):
...     print(repr(x).rjust(2), repr(x*x).rjust(3), end=' ')
...     # Note use of 'end' on previous line
...     print(repr(x*x*x).rjust(4))
...
 1   1    1
 2   4    8
 3   9   27
 4  16   64
 5  25  125
 6  36  216
 7  49  343
 8  64  512
 9  81  729
10 100 1000

(Resaltar que el espacio existente entre cada columna es añadido debido a como funciona print(): siempre añade espacios entre sus argumentos.)

El método str.rjust() de los objetos cadena justifica a la derecha en un campo de anchura predeterminada rellenando con espacios a la izquierda. Métodos similares a este son str.ljust() y str.center(). Estos métodos no escriben nada, simplemente retornan una nueva cadena. Si la cadena de entrada es demasiado larga no la truncarán sino que la retornarán sin cambios; esto desordenará la disposición de la columna que es, normalmente, mejor que la alternativa, la cual podría dejar sin usar un valor. (Si realmente deseas truncado siempre puedes añadir una operación de rebanado, como en x.ljust(n)[:n].)

Hay otro método, str.zfill(), el cual rellena una cadena numérica a la izquierda con ceros. Entiende signos positivos y negativos:

>>> '12'.zfill(5)
'00012'
>>> '-3.14'.zfill(7)
'-003.14'
>>> '3.14159265359'.zfill(5)
'3.14159265359'

7.1.4. Viejo formateo de cadenas

El operador % (módulo) también se puede utilizar para formatear cadenas de caracteres. Dados los 'cadena de caracteres' % valores, las instancias de % en cadena de caracteres se reemplazan con cero o más elementos de valores. Esta operación se conoce comúnmente como interpolación de cadenas. Por ejemplo:

>>> import math
>>> print('The value of pi is approximately %5.3f.' % math.pi)
The value of pi is approximately 3.142.

Podés encontrar más información en la sección Formateo de cadenas al estilo *printf*.

7.2. Leyendo y escribiendo archivos

open() returns a file object, and is most commonly used with two positional arguments and one keyword argument: open(filename, mode, encoding=None)

>>> f = open('workfile', 'w', encoding="utf-8")

El primer argumento es una cadena que contiene el nombre del fichero. El segundo argumento es otra cadena que contiene unos pocos caracteres describiendo la forma en que el fichero será usado. mode puede ser 'r' cuando el fichero solo se leerá, 'w' para solo escritura (un fichero existente con el mismo nombre se borrará) y 'a' abre el fichero para agregar.; cualquier dato que se escribe en el fichero se añade automáticamente al final. 'r+' abre el fichero tanto para lectura como para escritura. El argumento mode es opcional; se asume que se usará 'r' si se omite.

Normally, files are opened in text mode, that means, you read and write strings from and to the file, which are encoded in a specific encoding. If encoding is not specified, the default is platform dependent (see open()). Because UTF-8 is the modern de-facto standard, encoding="utf-8" is recommended unless you know that you need to use a different encoding. Appending a 'b' to the mode opens the file in binary mode. Binary mode data is read and written as bytes objects. You can not specify encoding when opening file in binary mode.

Cuando se lee en modo texto, por defecto se convierten los fines de lineas que son específicos a las plataformas (\n en Unix, \r\n en Windows) a solamente \n. Cuando se escribe en modo texto, por defecto se convierten los \n a los finales de linea específicos de la plataforma. Este cambio automático está bien para archivos de texto, pero corrompería datos binarios como los de archivos JPEG o EXE. Asegurate de usar modo binario cuando leas y escribas tales archivos.

Es una buena práctica usar la declaración with cuando manejamos objetos archivo. Tiene la ventaja que el archivo es cerrado apropiadamente luego de que el bloque termina, incluso si se generó una excepción. También es mucho más corto que escribir los equivalentes bloques try-finally

>>> with open('workfile', encoding="utf-8") as f:
...     read_data = f.read()

>>> # We can check that the file has been automatically closed.
>>> f.closed
True

Si no está utilizando la palabra clave with, entonces debe llamar a f.close() para cerrar el archivo y liberar inmediatamente los recursos del sistema utilizados por él.

Advertencia

Al llamar a f.write() sin usar la palabra clave :keyword::!with o llamar a f.close() podría dar como resultado los argumentos de f.write() no se escribe completamente en el disco, incluso si el programa se cierra correctamente.

Después de que un objeto de archivo es cerrado, ya sea por with o llamando a f.close(), intentar volver a utilizarlo fallará automáticamente:

>>> f.close()
>>> f.read()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: I/O operation on closed file.

7.2.1. Métodos de los objetos Archivo

El resto de los ejemplos en esta sección asumirán que ya se creó un objeto archivo llamado f.

Para leer el contenido de una archivo utiliza f.read(size), el cual lee alguna cantidad de datos y los retorna como una cadena de (en modo texto) o un objeto de bytes (en modo binario). size es un argumento numérico opcional. Cuando se omite size o es negativo, el contenido entero del archivo será leído y retornado; es tu problema si el archivo es el doble de grande que la memoria de tu máquina. De otra manera, como máximo size caracteres (en modo texto) o size bytes (en modo binario) son leídos y retornados. Si se alcanzó el fin del archivo, f.read() retornará una cadena vacía ('').

>>> f.read()
'This is the entire file.\n'
>>> f.read()
''

f.readline() lee una sola linea del archivo; el carácter de fin de linea (\n) se deja al final de la cadena, y sólo se omite en la última linea del archivo si el mismo no termina en un fin de linea. Esto hace que el valor de retorno no sea ambiguo; si f.readline() retorna una cadena vacía, es que se alcanzó el fin del archivo, mientras que una linea en blanco es representada por '\n', una cadena conteniendo sólo un único fin de linea.

>>> f.readline()
'This is the first line of the file.\n'
>>> f.readline()
'Second line of the file\n'
>>> f.readline()
''

Para leer líneas de un archivo, podés iterar sobre el objeto archivo. Esto es eficiente en memoria, rápido, y conduce a un código más simple:

>>> for line in f:
...     print(line, end='')
...
This is the first line of the file.
Second line of the file

Si querés leer todas las líneas de un archivo en una lista también podés usar list(f) o f.readlines().

f.write(cadena) escribe el contenido de la cadena al archivo, retornando la cantidad de caracteres escritos.

>>> f.write('This is a test\n')
15

Otros tipos de objetos necesitan ser convertidos – tanto a una cadena (en modo texto) o a un objeto de bytes (en modo binario) – antes de escribirlos:

>>> value = ('the answer', 42)
>>> s = str(value)  # convert the tuple to string
>>> f.write(s)
18

f.tell() retorna un entero que indica la posición actual en el archivo representada como número de bytes desde el comienzo del archivo en modo binario y un número opaco en modo texto.

Para cambiar la posición del objeto archivo, utiliza f.seek(offset, whence). La posición es calculada agregando el offset a un punto de referencia; el punto de referencia se selecciona del argumento whence. Un valor whence de 0 mide desde el comienzo del archivo, 1 usa la posición actual del archivo, y 2 usa el fin del archivo como punto de referencia. whence puede omitirse, el valor por defecto es 0, usando el comienzo del archivo como punto de referencia.

>>> f = open('workfile', 'rb+')
>>> f.write(b'0123456789abcdef')
16
>>> f.seek(5)      # Go to the 6th byte in the file
5
>>> f.read(1)
b'5'
>>> f.seek(-3, 2)  # Go to the 3rd byte before the end
13
>>> f.read(1)
b'd'

En los archivos de texto (aquellos que se abrieron sin una b en el modo), se permiten solamente desplazamientos con seek relativos al comienzo (con la excepción de ir justo al final con seek(0, 2)) y los únicos valores de desplazamiento válidos son aquellos retornados por f.tell(), o cero. Cualquier otro valor de desplazamiento produce un comportamiento indefinido.

Los objetos archivo tienen algunos métodos más, como isatty() y truncate() que son usados menos frecuentemente; consultá la Referencia de la Biblioteca para una guía completa sobre los objetos archivo.

7.2.2. Guardar datos estructurados con json

Las cadenas pueden fácilmente escribirse y leerse de un archivo. Los números toman algo más de esfuerzo, ya que el método read() sólo retorna cadenas, que tendrán que ser pasadas a una función como int(), que toma una cadena como '123' y retorna su valor numérico 123. Sin embargo, cuando querés grabar tipos de datos más complejos como listas, diccionarios, o instancias de clases, las cosas se ponen más complicadas.

En lugar de tener a los usuarios constantemente escribiendo y debugueando código para grabar tipos de datos complicados, Python te permite usar formato intercambiable de datos popular llamado JSON (JavaScript Object Notation) [http://json.org]. El módulo estándar llamado json puede tomar datos de Python con una jerarquía, y convertirlo a representaciones de cadena de caracteres; este proceso es llamado serializing. Reconstruir los datos desde la representación de cadena de caracteres es llamado deserializing. Entre serialización y deserialización, la cadena de caracteres representando el objeto quizás haya sido guardado en un archivo o datos, o enviado a una máquina distante por una conexión de red.

Nota

El formato JSON es comúnmente usando por aplicaciones modernas para permitir el intercambio de datos. Muchos programadores ya están familiarizados con él, lo cual lo convierte en una buena opción para la interoperabilidad.

Si tienes un objeto x, puedes ver su representación JSON con una simple línea de código:

>>> import json
>>> x = [1, 'simple', 'list']
>>> json.dumps(x)
'[1, "simple", "list"]'

Otra variante de la función dumps(), llamada dump(), simplemente serializa el objeto a un archivo de texto. Así que, si f es un objeto archivo de texto abierto para escritura, podemos hacer:

json.dump(x, f)

To decode the object again, if f is a binary file or text file object which has been opened for reading:

x = json.load(f)

Nota

JSON files must be encoded in UTF-8. Use encoding="utf-8" when opening JSON file as a text file for both of reading and writing.

La simple técnica de serialización puede manejar listas y diccionarios, pero serializar instancias de clases arbitrarias en JSON requiere un poco de esfuerzo extra. La referencia del módulo json contiene una explicación de esto.

Ver también

pickle - El módulo pickle

Contrariamente a JSON, pickle es un protocolo que permite la serialización de objetos Python arbitrariamente complejos. Como tal, es específico de Python y no se puede utilizar para comunicarse con aplicaciones escritas en otros idiomas. También es inseguro de forma predeterminada: deserializar los datos de pickle procedentes de un origen que no es de confianza puede ejecutar código arbitrario, si los datos fueron creados por un atacante experto.

8. Errores y excepciones

Hasta ahora los mensajes de error apenas habían sido mencionados, pero si has probado los ejemplos anteriores probablemente hayas visto algunos. Hay (al menos) dos tipos diferentes de errores: errores de sintaxis y excepciones.

8.1. Errores de sintaxis

Los errores de sintaxis, también conocidos como errores de interpretación, son quizás el tipo de queja más común que tenés cuando todavía estás aprendiendo Python:

>>> while True print('Hello world')
  File "<stdin>", line 1
    while True print('Hello world')
                   ^
SyntaxError: invalid syntax

El intérprete reproduce la línea responsable del error y muestra una pequeña “flecha” que apunta al primer lugar donde se detectó el error. El error ha sido provocado (o al menos detectado) en el elemento que precede a la flecha: en el ejemplo, el error se detecta en la función print(), ya que faltan dos puntos (':') antes del mismo. Se muestran el nombre del archivo y el número de línea para que sepas dónde mirar en caso de que la entrada venga de un programa.

8.2. Excepciones

Incluso si una declaración o expresión es sintácticamente correcta, puede generar un error cuando se intenta ejecutar. Los errores detectados durante la ejecución se llaman excepciones, y no son incondicionalmente fatales: pronto aprenderás a gestionarlos en programas Python. Sin embargo, la mayoría de las excepciones no son gestionadas por el código, y resultan en mensajes de error como los mostrados aquí:

>>> 10 * (1/0)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ZeroDivisionError: division by zero
>>> 4 + spam*3
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'spam' is not defined
>>> '2' + 2
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: can only concatenate str (not "int") to str

La última línea de los mensajes de error indica qué ha sucedido. Hay excepciones de diferentes tipos, y el tipo se imprime como parte del mensaje: los tipos en el ejemplo son: ZeroDivisionError, NameError y TypeError. La cadena mostrada como tipo de la excepción es el nombre de la excepción predefinida que ha ocurrido. Esto es válido para todas las excepciones predefinidas del intérprete, pero no tiene por que ser así para excepciones definidas por el usuario (aunque es una convención útil). Los nombres de las excepciones estándar son identificadores incorporados al intérprete (no son palabras clave reservadas).

El resto de la línea provee información basado en el tipo de la excepción y qué la causó.

La parte anterior del mensaje de error muestra el contexto donde ocurrió la excepción, en forma de seguimiento de pila. En general, contiene un seguimiento de pila que enumera las líneas de origen; sin embargo, no mostrará las líneas leídas desde la entrada estándar.

Excepciones incorporadas lista las excepciones predefinidas y sus significados.

8.3. Gestionando excepciones

Es posible escribir programas que gestionen determinadas excepciones. Véase el siguiente ejemplo, que le pide al usuario una entrada hasta que ingrese un entero válido, pero permite al usuario interrumpir el programa (usando Control-C o lo que soporte el sistema operativo); nótese que una interrupción generada por el usuario es señalizada generando la excepción KeyboardInterrupt.

>>> while True:
...     try:
...         x = int(input("Please enter a number: "))
...         break
...     except ValueError:
...         print("Oops!  That was no valid number.  Try again...")
...

La sentencia try funciona de la siguiente manera.

Primero, se ejecuta la cláusula try (la(s) linea(s) entre las palabras reservadas try y la except).

Si no ocurre ninguna excepción, la cláusula except se omite y la ejecución de la cláusula try finaliza.

Si ocurre una excepción durante la ejecución de la cláusula try el resto de la cláusula se omite. Entonces, si el tipo de excepción coincide con la excepción indicada después de la except, la cláusula except se ejecuta, y la ejecución continua después de la try.

Si ocurre una excepción que no coincide con la indicada en la cláusula except se pasa a los try más externos; si no se encuentra un gestor, se genera una unhandled exception (excepción no gestionada) y la ejecución se interrumpe con un mensaje como el que se muestra arriba.

Una declaración try puede tener más de un except, para especificar gestores para distintas excepciones. A lo sumo un bloque será ejecutado. Sólo se gestionarán excepciones que ocurren en el correspondiente try, no en otros bloques del mismo try. Un except puede nombrar múltiples excepciones usando paréntesis, por ejemplo:

... except (RuntimeError, TypeError, NameError):
...     pass

Una clase en una cláusula except es compatible con una excepción si es de la misma clase o de una clase derivada de la misma (pero no de la otra manera — una cláusula except listando una clase derivada no es compatible con una clase base). Por ejemplo, el siguiente código imprimirá B, C y D, en ese orden:

class B(Exception):
    pass

class C(B):
    pass

class D(C):
    pass

for cls in [B, C, D]:
    try:
        raise cls()
    except D:
        print("D")
    except C:
        print("C")
    except B:
        print("B")

Nótese que si las cláusulas except estuvieran invertidas (con except B primero), habría impreso B, B, B — se usa la primera cláusula except coincidente.

El último except puede omitir el nombre de la excepción capturada y servir como comodín. Se debe usar esta posibilidad con extremo cuidado, ya que de esta manera es fácil ocultar un error real de programación. También puede usarse para mostrar un mensaje de error y luego re-generar la excepción (permitiéndole al que llama, gestionar también la excepción):

import sys

try:
    f = open('myfile.txt')
    s = f.readline()
    i = int(s.strip())
except OSError as err:
    print("OS error: {0}".format(err))
except ValueError:
    print("Could not convert data to an integer.")
except:
    print("Unexpected error:", sys.exc_info()[0])
    raise

Las declaraciones try … except tienen un bloque else opcional, el cual, cuando está presente, debe seguir a los except. Es útil para aquel código que debe ejecutarse si el bloque try no genera una excepción. Por ejemplo:

for arg in sys.argv[1:]:
    try:
        f = open(arg, 'r')
    except OSError:
        print('cannot open', arg)
    else:
        print(arg, 'has', len(f.readlines()), 'lines')
        f.close()

El uso de la cláusula else es mejor que agregar código adicional en la cláusula try porque evita capturar accidentalmente una excepción que no fue generada por el código que está protegido por la declaración try … except.

Cuando ocurre una excepción, puede tener un valor asociado, también conocido como el argumento de la excepción. La presencia y el tipo de argumento depende del tipo de excepción.

La cláusula except puede especificar una variable después del nombre de excepción. La variable se vincula a una instancia de la excepción con los argumentos almacenados en instance.args. Por conveniencia, la instancia de excepción define __str__() para que se pueda mostrar los argumentos directamente, sin necesidad de hacer referencia a .args. También se puede instanciar la excepción primero, antes de generarla, y agregarle los atributos que se desee:

>>> try:
...     raise Exception('spam', 'eggs')
... except Exception as inst:
...     print(type(inst))    # the exception instance
...     print(inst.args)     # arguments stored in .args
...     print(inst)          # __str__ allows args to be printed directly,
...                          # but may be overridden in exception subclasses
...     x, y = inst.args     # unpack args
...     print('x =', x)
...     print('y =', y)
...
<class 'Exception'>
('spam', 'eggs')
('spam', 'eggs')
x = spam
y = eggs

Si una excepción tiene argumentos, estos se imprimen como en la parte final (el “detalle”) del mensaje para las excepciones no gestionadas (”Unhandled exception”).

Los gestores de excepciones no se encargan solamente de las excepciones que ocurren en el bloque try, también gestionan las excepciones que ocurren dentro de las funciones que se llaman (inclusive indirectamente) dentro del bloque try. Por ejemplo:

>>> def this_fails():
...     x = 1/0
...
>>> try:
...     this_fails()
... except ZeroDivisionError as err:
...     print('Handling run-time error:', err)
...
Handling run-time error: division by zero

8.4. Lanzando excepciones

La declaración raise permite al programador forzar a que ocurra una excepción específica. Por ejemplo:

>>> raise NameError('HiThere')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: HiThere

El único argumento de raise indica la excepción a generarse. Tiene que ser o una instancia de excepción, o una clase de excepción (una clase que hereda de Exception). Si se pasa una clase de excepción, la misma será instanciada implícitamente llamando a su constructor sin argumentos:

raise ValueError  # shorthand for 'raise ValueError()'

Si es necesario determinar si una excepción fue lanzada pero sin intención de gestionarla, una versión simplificada de la instrucción raise te permite relanzarla:

>>> try:
...     raise NameError('HiThere')
... except NameError:
...     print('An exception flew by!')
...     raise
...
An exception flew by!
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
NameError: HiThere

8.5. Encadenamiento de excepciones

The raise statement allows an optional from which enables chaining exceptions. For example:

# exc must be exception instance or None.
raise RuntimeError from exc

Esto puede resultar útil cuando está transformando excepciones. Por ejemplo:

>>> def func():
...     raise IOError
...
>>> try:
...     func()
... except IOError as exc:
...     raise RuntimeError('Failed to open database') from exc
...
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
  File "<stdin>", line 2, in func
OSError

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "<stdin>", line 4, in <module>
RuntimeError: Failed to open database

El encadenamiento de excepciones ocurre automáticamente cuando se genera una excepción dentro de una sección palabra clave except o finally. El encadenamiento de excepciones se puede deshabilitar usando el modismo from None:

>>> try:
...     open('database.sqlite')
... except OSError:
...     raise RuntimeError from None
...
Traceback (most recent call last):
  File "<stdin>", line 4, in <module>
RuntimeError

Para obtener más información sobre la mecánica del encadenamiento, consulte Excepciones incorporadas.

8.6. Excepciones definidas por el usuario

Los programas pueden nombrar sus propias excepciones creando una nueva clase excepción (mirá Clases para más información sobre las clases de Python). Las excepciones, típicamente, deberán derivar de la clase Exception, directa o indirectamente.

Exception classes can be defined which do anything any other class can do, but are usually kept simple, often only offering a number of attributes that allow information about the error to be extracted by handlers for the exception.

La mayoría de las excepciones se definen con nombres acabados en «Error», de manera similar a la nomenclatura de las excepciones estándar.

Muchos módulos estándar definen sus propias excepciones para reportar errores que pueden ocurrir en funciones propias. Se puede encontrar más información sobre clases en el capítulo Clases.

8.7. Definiendo acciones de limpieza

La declaración try tiene otra cláusula opcional cuyo propósito es definir acciones de limpieza que serán ejecutadas bajo ciertas circunstancias. Por ejemplo:

>>> try:
...     raise KeyboardInterrupt
... finally:
...     print('Goodbye, world!')
...
Goodbye, world!
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
KeyboardInterrupt

Si una cláusula finally está presente, el bloque finally se ejecutará al final antes de que todo el bloque try se complete. La cláusula finally se ejecuta independientemente de que la cláusula try produzca o no una excepción. Los siguientes puntos explican casos más complejos en los que se produce una excepción:

Si ocurre una excepción durante la ejecución de la cláusula try, la excepción podría ser gestionada por una cláusula except. Si la excepción no es gestionada por una cláusula except, la excepción es relanzada después de que se ejecute el bloque de la cláusula finally.

Podría aparecer una excepción durante la ejecución de una cláusula except o else. De nuevo, la excepción será relanzada después de que el bloque de la cláusula finally se ejecute.

If the finally clause executes a break, continue or return statement, exceptions are not re-raised.

Si el bloque try llega a una sentencia break, continue o return, la cláusula finally se ejecutará justo antes de la ejecución de dicha sentencia.

Si una cláusula finally incluye una sentencia return, el valor retornado será el de la cláusula finally, no la del de la sentencia return de la cláusula try.

Por ejemplo:

>>> def bool_return():
...     try:
...         return True
...     finally:
...         return False
...
>>> bool_return()
False

Un ejemplo más complicado:

>>> def divide(x, y):
...     try:
...         result = x / y
...     except ZeroDivisionError:
...         print("division by zero!")
...     else:
...         print("result is", result)
...     finally:
...         print("executing finally clause")
...
>>> divide(2, 1)
result is 2.0
executing finally clause
>>> divide(2, 0)
division by zero!
executing finally clause
>>> divide("2", "1")
executing finally clause
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 3, in divide
TypeError: unsupported operand type(s) for /: 'str' and 'str'

Como se puede ver, la cláusula finally siempre se ejecuta. La excepción TypeError lanzada al dividir dos cadenas de texto no es gestionado por la cláusula except y por lo tanto es relanzada luego de que se ejecuta la cláusula finally.

En aplicaciones reales, la cláusula finally es útil para liberar recursos externos (como archivos o conexiones de red), sin importar si el uso del recurso fue exitoso.

8.8. Acciones predefinidas de limpieza

Algunos objetos definen acciones de limpieza estándar para llevar a cabo cuando el objeto ya no necesario, independientemente de que las operaciones sobre el objeto hayan sido exitosas o no. Véase el siguiente ejemplo, que intenta abrir un archivo e imprimir su contenido en la pantalla.

for line in open("myfile.txt"):
    print(line, end="")

El problema con este código es que deja el archivo abierto por un periodo de tiempo indeterminado luego de que esta parte termine de ejecutarse. Esto no es un problema en scripts simples, pero puede ser un problema en aplicaciones más grandes. La declaración with permite que los objetos como archivos sean usados de una forma que asegure que siempre se los libera rápido y en forma correcta.:

with open("myfile.txt") as f:
    for line in f:
        print(line, end="")

Una vez que la declaración se ejecuta, el fichero f siempre se cierra, incluso si aparece algún error durante el procesado de las líneas. Los objetos que, como los ficheros, posean acciones predefinidas de limpieza lo indicarán en su documentación.

9. Clases

Las clases proveen una forma de empaquetar datos y funcionalidad juntos. Al crear una nueva clase, se crea un nuevo tipo de objeto, permitiendo crear nuevas instancias de ese tipo. Cada instancia de clase puede tener atributos adjuntos para mantener su estado. Las instancias de clase también pueden tener métodos (definidos por su clase) para modificar su estado.

Comparado con otros lenguajes de programación, el mecanismo de clases de Python agrega clases con un mínimo de nuevas sintaxis y semánticas. Es una mezcla de los mecanismos de clases encontrados en C++ y Modula-3. Las clases de Python proveen todas las características normales de la Programación Orientada a Objetos: el mecanismo de la herencia de clases permite múltiples clases base, una clase derivada puede sobre escribir cualquier método de su(s) clase(s) base, y un método puede llamar al método de la clase base con el mismo nombre. Los objetos pueden tener una cantidad arbitraria de datos de cualquier tipo. Igual que con los módulos, las clases participan de la naturaleza dinámica de Python: se crean en tiempo de ejecución, y pueden modificarse luego de la creación.

En terminología de C++, normalmente los miembros de las clases (incluyendo los miembros de datos), son públicos (excepto ver abajo Variables privadas), y todas las funciones miembro son virtuales. Como en Modula-3, no hay atajos para hacer referencia a los miembros del objeto desde sus métodos: la función método se declara con un primer argumento explícito que representa al objeto, el cual se provee implícitamente por la llamada. Como en Smalltalk, las clases mismas son objetos. Esto provee una semántica para importar y renombrar. A diferencia de C++ y Modula-3, los tipos de datos integrados pueden usarse como clases base para que el usuario los extienda. También, como en C++ pero a diferencia de Modula-3, la mayoría de los operadores integrados con sintaxis especial (operadores aritméticos, de sub-índice, etc.) pueden volver a ser definidos por instancias de la clase.

(Sin haber una terminología universalmente aceptada sobre clases, haré uso ocasional de términos de Smalltalk y C++. Usaría términos de Modula-3, ya que su semántica orientada a objetos es más cercana a Python que C++, pero no espero que muchos lectores hayan escuchado hablar de él.)

9.1. Unas palabras sobre nombres y objetos

Los objetos tienen individualidad, y múltiples nombres (en muchos ámbitos) pueden vincularse al mismo objeto. Esto se conoce como aliasing en otros lenguajes. Normalmente no se aprecia esto a primera vista en Python, y puede ignorarse sin problemas cuando se maneja tipos básicos inmutables (números, cadenas, tuplas). Sin embargo, el aliasing, o renombrado, tiene un efecto posiblemente sorpresivo sobre la semántica de código Python que involucra objetos mutables como listas, diccionarios, y la mayoría de otros tipos. Esto se usa normalmente para beneficio del programa, ya que los renombres funcionan como punteros en algunos aspectos. Por ejemplo, pasar un objeto es barato ya que la implementación solamente pasa el puntero; y si una función modifica el objeto que fue pasado, el que la llama verá el cambio; esto elimina la necesidad de tener dos formas diferentes de pasar argumentos, como en Pascal.

9.2. Ámbitos y espacios de nombres en Python

Antes de ver clases, primero debo decirte algo acerca de las reglas de ámbito de Python. Las definiciones de clases hacen unos lindos trucos con los espacios de nombres, y necesitás saber cómo funcionan los alcances y espacios de nombres para entender por completo cómo es la cosa. De paso, los conocimientos en este tema son útiles para cualquier programador Python avanzado.

Comencemos con unas definiciones.

Un espacio de nombres es una relación de nombres a objetos. Muchos espacios de nombres están implementados en este momento como diccionarios de Python, pero eso no se nota para nada (excepto por el desempeño), y puede cambiar en el futuro. Como ejemplos de espacios de nombres tenés: el conjunto de nombres incluidos (conteniendo funciones como abs(), y los nombres de excepciones integradas); los nombres globales en un módulo; y los nombres locales en la invocación a una función. Lo que es importante saber de los espacios de nombres es que no hay relación en absoluto entre los nombres de espacios de nombres distintos; por ejemplo, dos módulos diferentes pueden tener definidos los dos una función maximizar sin confusión; los usuarios de los módulos deben usar el nombre del módulo como prefijo.

Por cierto, yo uso la palabra atributo para cualquier cosa después de un punto; por ejemplo, en la expresión z.real, real es un atributo del objeto z. Estrictamente hablando, las referencias a nombres en módulos son referencias a atributos: en la expresión modulo.funcion, modulo es un objeto módulo y funcion es un atributo de éste. En este caso hay una relación directa entre los atributos del módulo y los nombres globales definidos en el módulo: ¡están compartiendo el mismo espacio de nombres! 1

Los atributos pueden ser de sólo lectura, o de escritura. En el último caso es posible la asignación a atributos. Los atributos de módulo pueden escribirse: modulo.la_respuesta = 42. Los atributos de escritura se pueden borrar también con la declaración del. Por ejemplo, del modulo.la_respuesta va a eliminar el atributo la_respuesta del objeto con nombre modulo.

Los espacios de nombres se crean en diferentes momentos y con diferentes tiempos de vida. El espacio de nombres que contiene los nombres incluidos se crea cuando se inicia el intérprete, y nunca se borra. El espacio de nombres global de un módulo se crea cuando se lee la definición de un módulo; normalmente, los espacios de nombres de módulos también duran hasta que el intérprete finaliza. Las instrucciones ejecutadas en el nivel de llamadas superior del intérprete, ya sea desde un script o interactivamente, se consideran parte del módulo llamado __main__, por lo tanto tienen su propio espacio de nombres global. (Los nombres incluidos en realidad también viven en un módulo; este se llama builtins.)

El espacio de nombres local a una función se crea cuando la función es llamada, y se elimina cuando la función retorna o lanza una excepción que no se maneje dentro de la función. (Podríamos decir que lo que pasa en realidad es que ese espacio de nombres se «olvida».) Por supuesto, las llamadas recursivas tienen cada una su propio espacio de nombres local.

Un ámbito es una región textual de un programa en Python donde un espacio de nombres es accesible directamente. «Accesible directamente» significa que una referencia sin calificar a un nombre intenta encontrar dicho nombre dentro del espacio de nombres.

Aunque los alcances se determinan de forma estática, se utilizan de forma dinámica. En cualquier momento durante la ejecución, hay 3 o 4 ámbitos anidados cuyos espacios de nombres son directamente accesibles:

el alcance más interno, que es inspeccionado primero, contiene los nombres locales

los alcances de las funciones que encierran a la función actual, que son inspeccionados a partir del alcance más cercano, contienen nombres no locales, pero también no globales

el penúltimo alcance contiene nombres globales del módulo actual

el alcance más externo (el último inspeccionado) es el espacio de nombres que contiene los nombres integrados

Si un nombre se declara como global, entonces todas las referencias y asignaciones al mismo van directo al ámbito intermedio que contiene los nombres globales del módulo. Para reasignar nombres encontrados afuera del ámbito más interno, se puede usar la declaración nonlocal; si no se declara nonlocal, esas variables serán de sólo lectura (un intento de escribir a esas variables simplemente crea una nueva variable local en el ámbito interno, dejando intacta la variable externa del mismo nombre).

Habitualmente, el ámbito local referencia los nombres locales de la función actual. Fuera de una función, el ámbito local referencia al mismo espacio de nombres que el ámbito global: el espacio de nombres del módulo. Las definiciones de clases crean un espacio de nombres más en el ámbito local.

Es importante notar que los alcances se determinan textualmente: el ámbito global de una función definida en un módulo es el espacio de nombres de ese módulo, no importa desde dónde o con qué alias se llame a la función. Por otro lado, la búsqueda de nombres se hace dinámicamente, en tiempo de ejecución; sin embargo, la definición del lenguaje está evolucionando a hacer resolución de nombres estáticamente, en tiempo de «compilación», ¡así que no te confíes de la resolución de nombres dinámica! (De hecho, las variables locales ya se determinan estáticamente.)

Una peculiaridad especial de Python es que, si no hay una declaración global o nonlocal en efecto, las asignaciones a nombres siempre van al ámbito interno. Las asignaciones no copian datos, solamente asocian nombres a objetos. Lo mismo cuando se borra: la declaración del x quita la asociación de x del espacio de nombres referenciado por el ámbito local. De hecho, todas las operaciones que introducen nuevos nombres usan el ámbito local: en particular, las instrucciones import y las definiciones de funciones asocian el módulo o nombre de la función al espacio de nombres en el ámbito local.

La declaración global puede usarse para indicar que ciertas variables viven en el ámbito global y deberían reasignarse allí; la declaración nonlocal indica que ciertas variables viven en un ámbito encerrado y deberían reasignarse allí.

9.2.1. Ejemplo de ámbitos y espacios de nombre

Este es un ejemplo que muestra como hacer referencia a distintos ámbitos y espacios de nombres, y cómo las declaraciones global y nonlocal afectan la asignación de variables:

def scope_test():
    def do_local():
        spam = "local spam"

    def do_nonlocal():
        nonlocal spam
        spam = "nonlocal spam"

    def do_global():
        global spam
        spam = "global spam"

    spam = "test spam"
    do_local()
    print("After local assignment:", spam)
    do_nonlocal()
    print("After nonlocal assignment:", spam)
    do_global()
    print("After global assignment:", spam)

scope_test()
print("In global scope:", spam)

El resultado del código ejemplo es:

After local assignment: test spam
After nonlocal assignment: nonlocal spam
After global assignment: nonlocal spam
In global scope: global spam

Notá como la asignación local (que es el comportamiento normal) no cambió la vinculación de algo de prueba_ambitos. La asignación nonlocal cambió la vinculación de algo de prueba_ambitos, y la asignación global cambió la vinculación a nivel de módulo.

También podés ver que no había vinculación para algo antes de la asignación global.

9.3. Un primer vistazo a las clases

Las clases introducen un poquito de sintaxis nueva, tres nuevos tipos de objetos y algo de semántica nueva.

9.3.1. Sintaxis de definición de clases

La forma más sencilla de definición de una clase se ve así:

class ClassName:
    <statement-1>
    .
    .
    .
    <statement-N>

Las definiciones de clases, al igual que las definiciones de funciones (instrucciones def) deben ejecutarse antes de que tengan efecto alguno. (Es concebible poner una definición de clase dentro de una rama de un if, o dentro de una función.)

En la práctica, las declaraciones dentro de una clase son definiciones de funciones, pero otras declaraciones son permitidas, y a veces resultan útiles; veremos esto más adelante. Las definiciones de funciones dentro de una clase normalmente tienen una lista de argumentos peculiar, dictada por las convenciones de invocación de métodos; a esto también lo veremos más adelante.

Cuando se ingresa una definición de clase, se crea un nuevo espacio de nombres, el cual se usa como ámbito local; por lo tanto, todas las asignaciones a variables locales van a este nuevo espacio de nombres. En particular, las definiciones de funciones asocian el nombre de las funciones nuevas allí.

Cuando una definición de clase se finaliza normalmente se crea un objeto clase. Básicamente, este objeto envuelve los contenidos del espacio de nombres creado por la definición de la clase; aprenderemos más acerca de los objetos clase en la sección siguiente. El ámbito local original (el que tenía efecto justo antes de que ingrese la definición de la clase) es restablecido, y el objeto clase se asocia allí al nombre que se le puso a la clase en el encabezado de su definición (Clase en el ejemplo).

9.3.2. Objetos clase

Los objetos clase soportan dos tipos de operaciones: hacer referencia a atributos e instanciación.

Para hacer referencia a atributos se usa la sintaxis estándar de todas las referencias a atributos en Python: objeto.nombre. Los nombres de atributo válidos son todos los nombres que estaban en el espacio de nombres de la clase cuando ésta se creó. Por lo tanto, si la definición de la clase es así:

class MyClass:
    """A simple example class"""
    i = 12345

    def f(self):
        return 'hello world'

…entonces MiClase.i y MiClase.f son referencias de atributos válidas, que retornan un entero y un objeto función respectivamente. Los atributos de clase también pueden ser asignados, o sea que podés cambiar el valor de MiClase.i mediante asignación. __doc__ también es un atributo válido, que retorna la documentación asociada a la clase: "Simple clase de ejemplo".

La instanciación de clases usa la notación de funciones. Hacé de cuenta que el objeto de clase es una función sin parámetros que retorna una nueva instancia de la clase. Por ejemplo (para la clase de más arriba):

x = MyClass()

…crea una nueva instancia de la clase y asigna este objeto a la variable local x.

La operación de instanciación («llamar» a un objeto clase) crea un objeto vacío. Muchas clases necesitan crear objetos con instancias en un estado inicial particular. Por lo tanto una clase puede definir un método especial llamado __init__(), de esta forma:

def __init__(self):
    self.data = []

Cuando una clase define un método __init__(), la instanciación de la clase automáticamente invoca a __init__() para la instancia recién creada. Entonces, en este ejemplo, una instancia nueva e inicializada se puede obtener haciendo:

x = MyClass()

Por supuesto, el método __init__() puede tener argumentos para mayor flexibilidad. En ese caso, los argumentos que se pasen al operador de instanciación de la clase van a parar al método __init__(). Por ejemplo,

>>> class Complex:
...     def __init__(self, realpart, imagpart):
...         self.r = realpart
...         self.i = imagpart
...
>>> x = Complex(3.0, -4.5)
>>> x.r, x.i
(3.0, -4.5)

9.3.3. Objetos instancia

Ahora, ¿Qué podemos hacer con los objetos instancia? La única operación que es entendida por los objetos instancia es la referencia de atributos. Hay dos tipos de nombres de atributos válidos, atributos de datos y métodos.

Los atributos de datos se corresponden con las «variables de instancia» en Smalltalk, y con las «variables miembro» en C++. Los atributos de datos no necesitan ser declarados; tal como las variables locales son creados la primera vez que se les asigna algo. Por ejemplo, si x es la instancia de MiClase creada más arriba, el siguiente pedazo de código va a imprimir el valor 16, sin dejar ningún rastro:

x.counter = 1
while x.counter < 10:
    x.counter = x.counter * 2
print(x.counter)
del x.counter

El otro tipo de atributo de instancia es el método. Un método es una función que «pertenece a» un objeto. En Python, el término método no está limitado a instancias de clase: otros tipos de objetos pueden tener métodos también. Por ejemplo, los objetos lista tienen métodos llamados append, insert, remove, sort, y así sucesivamente. Pero, en la siguiente explicación, usaremos el término método para referirnos exclusivamente a métodos de objetos instancia de clase, a menos que se especifique explícitamente lo contrario.

Los nombres válidos de métodos de un objeto instancia dependen de su clase. Por definición, todos los atributos de clase que son objetos funciones definen métodos correspondientes de sus instancias. Entonces, en nuestro ejemplo, x.f es una referencia a un método válido, dado que MiClase.f es una función, pero x.i no lo es, dado que MiClase.i no lo es. Pero x.f no es la misma cosa que MiClase.f; es un objeto método, no un objeto función.

9.3.4. Objetos método

Generalmente, un método es llamado luego de ser vinculado:

x.f()

En el ejemplo MiClase, esto retorna la cadena 'hola mundo'. Pero no es necesario llamar al método justo en ese momento: x.f es un objeto método, y puede ser guardado y llamado más tarde. Por ejemplo:

xf = x.f
while True:
    print(xf())

…continuará imprimiendo hola mundo hasta el fin de los días.

¿Qué sucede exactamente cuando un método es llamado? Debés haber notado que x.f() fue llamado más arriba sin ningún argumento, a pesar de que la definición de función de f() especificaba un argumento. ¿Qué pasó con ese argumento? Seguramente Python levanta una excepción cuando una función que requiere un argumento es llamada sin ninguno, aún si el argumento no es utilizado…

De hecho, tal vez hayas adivinado la respuesta: lo que tienen de especial los métodos es que el objeto es pasado como el primer argumento de la función. En nuestro ejemplo, la llamada x.f() es exactamente equivalente a MiClase.f(x). En general, llamar a un método con una lista de n argumentos es equivalente a llamar a la función correspondiente con una lista de argumentos que es creada insertando el objeto del método antes del primer argumento.

Si todavía no entiendes como funcionan los métodos, una mirada a su implementación quizás pueda aclarar dudas. Cuando un atributo sin datos de una instancia es referenciado, la clase de la instancia es accedida. Si el nombre indica un atributo de clase válido que sea un objeto función, se crea un objeto método empaquetando (apunta a) la instancia y al objeto función, juntados en un objeto abstracto: este es el objeto método. Cuando el objeto método es llamado con una lista de argumentos, se crea una nueva lista de argumentos a partir del objeto instancia y la lista de argumentos. Finalmente el objeto función es llamado con esta nueva lista de argumentos.

9.3.5. Variables de clase y de instancia

En general, las variables de instancia son para datos únicos de cada instancia y las variables de clase son para atributos y métodos compartidos por todas las instancias de la clase:

class Dog:

    kind = 'canine'         # class variable shared by all instances

    def __init__(self, name):
        self.name = name    # instance variable unique to each instance

>>> d = Dog('Fido')
>>> e = Dog('Buddy')
>>> d.kind                  # shared by all dogs
'canine'
>>> e.kind                  # shared by all dogs
'canine'
>>> d.name                  # unique to d
'Fido'
>>> e.name                  # unique to e
'Buddy'

Como se vio en Unas palabras sobre nombres y objetos, los datos compartidos pueden tener efectos inesperados que involucren objetos mutable como ser listas y diccionarios. Por ejemplo, la lista trucos en el siguiente código no debería ser usada como variable de clase porque una sola lista sería compartida por todos las instancias de Perro:

class Dog:

    tricks = []             # mistaken use of a class variable

    def __init__(self, name):
        self.name = name

    def add_trick(self, trick):
        self.tricks.append(trick)

>>> d = Dog('Fido')
>>> e = Dog('Buddy')
>>> d.add_trick('roll over')
>>> e.add_trick('play dead')
>>> d.tricks                # unexpectedly shared by all dogs
['roll over', 'play dead']

El diseño correcto de esta clase sería usando una variable de instancia:

class Dog:

    def __init__(self, name):
        self.name = name
        self.tricks = []    # creates a new empty list for each dog

    def add_trick(self, trick):
        self.tricks.append(trick)

>>> d = Dog('Fido')
>>> e = Dog('Buddy')
>>> d.add_trick('roll over')
>>> e.add_trick('play dead')
>>> d.tricks
['roll over']
>>> e.tricks
['play dead']

9.4. Algunas observaciones

Si el mismo nombre de atributo aparece tanto en la instancia como en la clase, la búsqueda del atributo prioriza la instancia:

>>> class Warehouse:
        purpose = 'storage'
        region = 'west'

>>> w1 = Warehouse()
>>> print(w1.purpose, w1.region)
storage west
>>> w2 = Warehouse()
>>> w2.region = 'east'
>>> print(w2.purpose, w2.region)
storage east

A los atributos de datos los pueden hacer referencia tanto los métodos como los usuarios («clientes») ordinarios de un objeto. En otras palabras, las clases no se usan para implementar tipos de datos abstractos puros. De hecho, en Python no hay nada que haga cumplir el ocultar datos; todo se basa en convención. (Por otro lado, la implementación de Python, escrita en C, puede ocultar por completo detalles de implementación y el control de acceso a un objeto si es necesario; esto se puede usar en extensiones a Python escritas en C.)

Los clientes deben usar los atributos de datos con cuidado; éstos pueden romper invariantes que mantienen los métodos si pisan los atributos de datos. Observá que los clientes pueden añadir sus propios atributos de datos a una instancia sin afectar la validez de sus métodos, siempre y cuando se eviten conflictos de nombres; de nuevo, una convención de nombres puede ahorrar un montón de dolores de cabeza.

No hay un atajo para hacer referencia a atributos de datos (¡u otros métodos!) desde dentro de un método. A mi parecer, esto en realidad aumenta la legibilidad de los métodos: no existe posibilidad alguna de confundir variables locales con variables de instancia cuando repasamos un método.

A menudo, el primer argumento de un método se llama self (uno mismo). Esto no es nada más que una convención: el nombre self no significa nada en especial para Python. Observá que, sin embargo, si no seguís la convención tu código puede resultar menos legible a otros programadores de Python, y puede llegar a pasar que un programa navegador de clases pueda escribirse de una manera que dependa de dicha convención.

Cualquier objeto función que es un atributo de clase define un método para instancias de esa clase. No es necesario que el la definición de la función esté textualmente dentro de la definición de la clase: asignando un objeto función a una variable local en la clase también está bien. Por ejemplo:

# Function defined outside the class
def f1(self, x, y):
    return min(x, x+y)

class C:
    f = f1

    def g(self):
        return 'hello world'

    h = g

Ahora f, g y h son todos atributos de la clase C que hacen referencia a objetos función, y consecuentemente son todos métodos de las instancias de C; h siendo exactamente equivalente a g. Fijate que esta práctica normalmente sólo sirve para confundir al que lea un programa.

Los métodos pueden llamar a otros métodos de la instancia usando el argumento self:

class Bag:
    def __init__(self):
        self.data = []

    def add(self, x):
        self.data.append(x)

    def addtwice(self, x):
        self.add(x)
        self.add(x)

Los métodos pueden hacer referencia a nombres globales de la misma manera que lo hacen las funciones comunes. El ámbito global asociado a un método es el módulo que contiene su definición. (Una clase nunca se usa como un ámbito global.) Si bien es raro encontrar una buena razón para usar datos globales en un método, hay muchos usos legítimos del ámbito global: por lo menos, las funciones y módulos importados en el ámbito global pueden usarse por los métodos, al igual que las funciones y clases definidas en él. Habitualmente, la clase que contiene el método está definida en este ámbito global, y en la siguiente sección veremos algunas buenas razones por las que un método querría hacer referencia a su propia clase.

Todo valor es un objeto, y por lo tanto tiene una clase (también llamado su tipo). Ésta se almacena como objeto.__class__.

9.5. Herencia

Por supuesto, una característica del lenguaje no sería digna del nombre «clase» si no soportara herencia. La sintaxis para una definición de clase derivada se ve así:

class DerivedClassName(BaseClassName):
    <statement-1>
    .
    .
    .
    <statement-N>

El nombre ClaseBase debe estar definido en un ámbito que contenga a la definición de la clase derivada. En el lugar del nombre de la clase base se permiten otras expresiones arbitrarias. Esto puede ser útil, por ejemplo, cuando la clase base está definida en otro módulo:

class DerivedClassName(modname.BaseClassName):

La ejecución de una definición de clase derivada procede de la misma forma que una clase base. Cuando el objeto clase se construye, se tiene en cuenta a la clase base. Esto se usa para resolver referencias a atributos: si un atributo solicitado no se encuentra en la clase, la búsqueda continúa por la clase base. Esta regla se aplica recursivamente si la clase base misma deriva de alguna otra clase.

No hay nada en especial en la instanciación de clases derivadas: ClaseDerivada() crea una nueva instancia de la clase. Las referencias a métodos se resuelven de la siguiente manera: se busca el atributo de clase correspondiente, descendiendo por la cadena de clases base si es necesario, y la referencia al método es válida si se entrega un objeto función.

Las clases derivadas pueden redefinir métodos de su clase base. Como los métodos no tienen privilegios especiales cuando llaman a otros métodos del mismo objeto, un método de la clase base que llame a otro método definido en la misma clase base puede terminar llamando a un método de la clase derivada que lo haya redefinido. (Para los programadores de C++: en Python todos los métodos son en efecto virtuales.)

Un método redefinido en una clase derivada puede de hecho querer extender en vez de simplemente reemplazar al método de la clase base con el mismo nombre. Hay una manera simple de llamar al método de la clase base directamente: simplemente llamás a ClaseBase.metodo(self, argumentos). En ocasiones esto es útil para los clientes también. (Observá que esto sólo funciona si la clase base es accesible como ClaseBase en el ámbito global.)

Python tiene dos funciones integradas que funcionan con herencia:

Usar isinstance() para verificar el tipo de una instancia: isinstance(obj, int) será True sólo si obj.__class__ es int o alguna clase derivada de int.

Usar issubclass() para verificar la herencia de clases: issubclass(bool, int) es True ya que bool es una subclase de int. Sin embargo, issubclass(float, int) es False ya que float no es una subclase de int.

9.5.1. Herencia múltiple

Python también soporta una forma de herencia múltiple. Una definición de clase con múltiples clases base se ve así:

class DerivedClassName(Base1, Base2, Base3):
    <statement-1>
    .
    .
    .
    <statement-N>

Para la mayoría de los propósitos, en los casos más simples, podés pensar en la búsqueda de los atributos heredados de clases padres como primero en profundidad, de izquierda a derecha, sin repetir la misma clase cuando está dos veces en la jerarquía. Por lo tanto, si un atributo no se encuentra en ClaseDerivada, se busca en Base1, luego (recursivamente) en las clases base de Base1, y sólo si no se encuentra allí se lo busca en Base2, y así sucesivamente.

En realidad es un poco más complejo que eso; el orden de resolución de métodos cambia dinámicamente para soportar las llamadas cooperativas a super(). Este enfoque es conocido en otros lenguajes con herencia múltiple como «llámese al siguiente método» y es más poderoso que la llamada al superior que se encuentra en lenguajes con sólo herencia simple.

El ordenamiento dinámico es necesario porque todos los casos de herencia múltiple exhiben una o más relaciones en diamante (cuando se puede llegar al menos a una de las clases base por distintos caminos desde la clase de más abajo). Por ejemplo, todas las clases heredan de object, por lo tanto cualquier caso de herencia múltiple provee más de un camino para llegar a object. Para que las clases base no sean accedidas más de una vez, el algoritmo dinámico hace lineal el orden de búsqueda de manera que se preserve el orden de izquierda a derecha especificado en cada clase, que se llame a cada clase base sólo una vez, y que sea monótona (lo cual significa que una clase puede tener clases derivadas sin afectar el orden de precedencia de sus clases bases). En conjunto, estas propiedades hacen posible diseñar clases confiables y extensibles con herencia múltiple. Para más detalles mirá https://www.python.org/download/releases/2.3/mro/.

9.6. Variables privadas

Las variables «privadas» de instancia, que no pueden accederse excepto desde dentro de un objeto, no existen en Python. Sin embargo, hay una convención que se sigue en la mayoría del código Python: un nombre prefijado con un guión bajo (por ejemplo, _spam) debería tratarse como una parte no pública de la API (más allá de que sea una función, un método, o un dato). Debería considerarse un detalle de implementación y que está sujeto a cambios sin aviso.

Ya que hay un caso de uso válido para los identificadores privados de clase (a saber: colisión de nombres con nombres definidos en las subclases), hay un soporte limitado para este mecanismo. Cualquier identificador con la forma __spam (al menos dos guiones bajos al principio, como mucho un guión bajo al final) es textualmente reemplazado por _nombredeclase__spam, donde nombredeclase es el nombre de clase actual al que se le sacan guiones bajos del comienzo (si los tuviera). Se modifica el nombre del identificador sin importar su posición sintáctica, siempre y cuando ocurra dentro de la definición de una clase.

La modificación de nombres es útil para dejar que las subclases sobreescriban los métodos sin romper las llamadas a los métodos desde la misma clase. Por ejemplo:

class Mapping:
    def __init__(self, iterable):
        self.items_list = []
        self.__update(iterable)

    def update(self, iterable):
        for item in iterable:
            self.items_list.append(item)

    __update = update   # private copy of original update() method

class MappingSubclass(Mapping):

    def update(self, keys, values):
        # provides new signature for update()
        # but does not break __init__()
        for item in zip(keys, values):
            self.items_list.append(item)

El ejemplo de arriba funcionaría incluso si MappingSubclass introdujera un identificador __update ya que se reemplaza con _Mapping__update en la clase Mapping y _MappingSubclass__update en la clase MappingSubclass respectivamente.

Hay que aclarar que las reglas de modificación de nombres están diseñadas principalmente para evitar accidentes; es posible acceder o modificar una variable que es considerada como privada. Esto hasta puede resultar útil en circunstancias especiales, tales como en el depurador.

Notar que el código pasado a exec o eval() no considera que el nombre de clase de la clase que invoca sea la clase actual; esto es similar al efecto de la sentencia global, efecto que es de similar manera restringido a código que es compilado en conjunto. La misma restricción aplica a getattr(), setattr() y delattr(), así como cuando se referencia a __dict__ directamente.

9.7. Cambalache

A veces es útil tener un tipo de datos similar al «registro» de Pascal o la «estructura» de C, que sirva para juntar algunos pocos ítems con nombre. Una definición de clase vacía funcionará perfecto:

class Employee:
    pass

john = Employee()  # Create an empty employee record

# Fill the fields of the record
john.name = 'John Doe'
john.dept = 'computer lab'
john.salary = 1000

Algún código Python que espera un tipo abstracto de datos en particular puede frecuentemente recibir en cambio una clase que emula los métodos de aquel tipo de datos. Por ejemplo, si tenés una función que formatea algunos datos a partir de un objeto archivo, podés definir una clase con métodos read() y readline() que obtengan los datos de alguna cadena en memoria intermedia, y pasarlo como argumento.

Los objetos método de instancia tienen atributos también: m.__self__ es el objeto instancia con el método m(), y m.__func__ es el objeto función correspondiente al método.

9.8. Iteradores

Es probable que hayas notado que la mayoría de los objetos contenedores pueden ser recorridos usando una sentencia for:

for element in [1, 2, 3]:
    print(element)
for element in (1, 2, 3):
    print(element)
for key in {'one':1, 'two':2}:
    print(key)
for char in "123":
    print(char)
for line in open("myfile.txt"):
    print(line, end='')

Este estilo de acceso es limpio, conciso y conveniente. El uso de iteradores está impregnado y unifica a Python. En bambalinas, la sentencia for llama a iter() en el objeto contenedor. La función retorna un objeto iterador que define el método __next__() que accede elementos en el contenedor de a uno por vez. Cuando no hay más elementos, __next__() levanta una excepción StopIteration que le avisa al bucle del for que hay que terminar. Podés llamar al método __next__() usando la función integrada next(); este ejemplo muestra como funciona todo esto:

>>> s = 'abc'
>>> it = iter(s)
>>> it
<str_iterator object at 0x10c90e650>
>>> next(it)
'a'
>>> next(it)
'b'
>>> next(it)
'c'
>>> next(it)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
    next(it)
StopIteration

Habiendo visto la mecánica del protocolo de iteración, es fácil agregar comportamiento de iterador a tus clases. Definí un método __iter__() que retorne un objeto con un método __next__(). Si la clase define __next__(), entonces alcanza con que __iter__() retorne self:

class Reverse:
    """Iterator for looping over a sequence backwards."""
    def __init__(self, data):
        self.data = data
        self.index = len(data)

    def __iter__(self):
        return self

    def __next__(self):
        if self.index == 0:
            raise StopIteration
        self.index = self.index - 1
        return self.data[self.index]

>>> rev = Reverse('spam')
>>> iter(rev)
<__main__.Reverse object at 0x00A1DB50>
>>> for char in rev:
...     print(char)
...
m
a
p
s

9.9. Generadores

Generators son una herramienta simple y poderosa para crear iteradores. Están escritas como funciones regulares pero usan la palabra clave yield siempre que quieran retornar datos. Cada vez que se llama a next(), el generador se reanuda donde lo dejó (recuerda todos los valores de datos y qué instrucción se ejecutó por última vez). Un ejemplo muestra que los generadores pueden ser trivialmente fáciles de crear:

def reverse(data):
    for index in range(len(data)-1, -1, -1):
        yield data[index]

>>> for char in reverse('golf'):
...     print(char)
...
f
l
o
g

Todo lo que puede ser hecho con generadores también puede ser hecho con iteradores basados en clases, como se describe en la sección anterior. Lo que hace que los generadores sean tan compactos es que los métodos __iter__() y __next__() son creados automáticamente.

Otra característica clave es que las variables locales y el estado de la ejecución son guardados automáticamente entre llamadas. Esto hace que la función sea más fácil de escribir y quede mucho más claro que hacerlo usando variables de instancia tales como self.indice y self.datos.

Además de la creación automática de métodos y el guardar el estado del programa, cuando los generadores terminan automáticamente levantan StopIteration. Combinadas, estas características facilitan la creación de iteradores, y hacen que no sea más esfuerzo que escribir una función regular.

9.10. Expresiones generadoras

Algunos generadores simples pueden ser escritos de manera concisa como expresiones usando una sintaxis similar a las comprensiones de listas pero con paréntesis en lugar de corchetes. Estas expresiones están hechas para situaciones donde el generador es utilizado de inmediato por la función que lo encierra. Las expresiones generadoras son más compactas pero menos versátiles que las definiciones completas de generadores y tienden a ser más amigables con la memoria que sus comprensiones de listas equivalentes.

Ejemplos:

>>> sum(i*i for i in range(10))                 # sum of squares
285

>>> xvec = [10, 20, 30]
>>> yvec = [7, 5, 3]
>>> sum(x*y for x,y in zip(xvec, yvec))         # dot product
260

>>> unique_words = set(word for line in page  for word in line.split())

>>> valedictorian = max((student.gpa, student.name) for student in graduates)

>>> data = 'golf'
>>> list(data[i] for i in range(len(data)-1, -1, -1))
['f', 'l', 'o', 'g']

Notas al pie

1

Excepto por una cosa. Los objetos módulo tienen un atributo de sólo lectura secreto llamado __dict__ que retorna el diccionario usado para implementar el espacio de nombres del módulo; el nombre __dict__ es un atributo pero no un nombre global. Obviamente, usar esto viola la abstracción de la implementación del espacio de nombres, y debería ser restringido a cosas como depuradores post-mortem.

10. Pequeño paseo por la Biblioteca Estándar

10.1. Interfaz al sistema operativo

El módulo os provee docenas de funciones para interactuar con el sistema operativo:

>>> import os
>>> os.getcwd()      # Return the current working directory
'C:\\Python39'
>>> os.chdir('/server/accesslogs')   # Change current working directory
>>> os.system('mkdir today')   # Run the command mkdir in the system shell
0

Asegúrate de usar el estilo import os en lugar de from os import *. Esto evitará que os.open() oculte a la función integrada open(), que trabaja bastante diferente.

Las funciones integradas dir() y help() son útiles como ayudas interactivas para trabajar con módulos grandes como os:

>>> import os
>>> dir(os)
<returns a list of all module functions>
>>> help(os)
<returns an extensive manual page created from the module's docstrings>

Para tareas diarias de administración de archivos y directorios, el módulo shutil provee una interfaz de más alto nivel que es más fácil de usar:

>>> import shutil
>>> shutil.copyfile('data.db', 'archive.db')
'archive.db'
>>> shutil.move('/build/executables', 'installdir')
'installdir'

10.2. Comodines de archivos

El módulo glob provee una función para hacer listas de archivos a partir de búsquedas con comodines en directorios:

>>> import glob
>>> glob.glob('*.py')
['primes.py', 'random.py', 'quote.py']

10.3. Argumentos de linea de órdenes

Los programas frecuentemente necesitan procesar argumentos de linea de órdenes. Estos argumentos se almacenan en el atributo argv del módulo sys como una lista. Por ejemplo, la siguiente salida resulta de ejecutar python demo.py uno dos tres en la línea de órdenes:

>>> import sys
>>> print(sys.argv)
['demo.py', 'one', 'two', 'three']

El modulo argparse provee un mecanismo más sofisticado para procesar argumentos recibidos vía línea de comandos. El siguiente script extrae uno o más nombres de archivos y un número opcional de líneas para mostrar:

import argparse

parser = argparse.ArgumentParser(
    prog='top',
    description='Show top lines from each file')
parser.add_argument('filenames', nargs='+')
parser.add_argument('-l', '--lines', type=int, default=10)
args = parser.parse_args()
print(args)

Cuando se ejecuta por línea de comandos haciendo python top.py --lines=5 alpha.txt beta.txt, el script establece args.lines a 5 y args.filenames a ['alpha.txt', 'beta.txt'].

10.4. Redirigir la salida de error y finalización del programa

El módulo sys también tiene atributos para stdin, stdout, y stderr. Este último es útil para emitir mensajes de alerta y error para que se vean incluso cuando se haya redirigido stdout:

>>> sys.stderr.write('Warning, log file not found starting a new one\n')
Warning, log file not found starting a new one

La forma más directa de terminar un programa es usar sys.exit().

10.5. Coincidencia en patrones de cadenas

El módulo re provee herramientas de expresiones regulares para un procesamiento avanzado de cadenas. Para manipulación y coincidencias complejas, las expresiones regulares ofrecen soluciones concisas y optimizadas:

>>> import re
>>> re.findall(r'\bf[a-z]*', 'which foot or hand fell fastest')
['foot', 'fell', 'fastest']
>>> re.sub(r'(\b[a-z]+) \1', r'\1', 'cat in the the hat')
'cat in the hat'

Cuando se necesita algo más sencillo solamente, se prefieren los métodos de las cadenas porque son más fáciles de leer y depurar:

>>> 'tea for too'.replace('too', 'two')
'tea for two'

10.6. Matemática

El módulo math permite el acceso a las funciones de la biblioteca C subyacente para la matemática de punto flotante:

>>> import math
>>> math.cos(math.pi / 4)
0.70710678118654757
>>> math.log(1024, 2)
10.0

El módulo random provee herramientas para realizar selecciones al azar:

>>> import random
>>> random.choice(['apple', 'pear', 'banana'])
'apple'
>>> random.sample(range(100), 10)   # sampling without replacement
[30, 83, 16, 4, 8, 81, 41, 50, 18, 33]
>>> random.random()    # random float
0.17970987693706186
>>> random.randrange(6)    # random integer chosen from range(6)
4

El módulo statistics calcula propiedades de estadística básica (la media, mediana, varianza, etc) de datos numéricos:

>>> import statistics
>>> data = [2.75, 1.75, 1.25, 0.25, 0.5, 1.25, 3.5]
>>> statistics.mean(data)
1.6071428571428572
>>> statistics.median(data)
1.25
>>> statistics.variance(data)
1.3720238095238095

El proyecto SciPy <https://scipy.org> tiene muchos otros módulos para cálculos numéricos.

10.7. Acceso a Internet

Hay varios módulos para acceder a Internet y procesar sus protocolos. Dos de los más simples son urllib.request para traer data de URLs y smtplib para mandar correos:

>>> from urllib.request import urlopen
>>> with urlopen('http://worldtimeapi.org/api/timezone/etc/UTC.txt') as response:
...     for line in response:
...         line = line.decode()             # Convert bytes to a str
...         if line.startswith('datetime'):
...             print(line.rstrip())         # Remove trailing newline
...
datetime: 2022-01-01T01:36:47.689215+00:00

>>> import smtplib
>>> server = smtplib.SMTP('localhost')
>>> server.sendmail('soothsayer@example.org', 'jcaesar@example.org',
... """To: jcaesar@example.org
... From: soothsayer@example.org
...
... Beware the Ides of March.
... """)
>>> server.quit()

(Notá que el segundo ejemplo necesita un servidor de correo corriendo en la máquina local)

10.8. Fechas y tiempos

El módulo datetime ofrece clases para gestionar fechas y tiempos tanto de manera simple como compleja. Aunque soporta aritmética sobre fechas y tiempos, el foco de la implementación es en la extracción eficiente de partes para gestionarlas o formatear la salida. El módulo también soporta objetos que son conscientes de la zona horaria.

>>> # dates are easily constructed and formatted
>>> from datetime import date
>>> now = date.today()
>>> now
datetime.date(2003, 12, 2)
>>> now.strftime("%m-%d-%y. %d %b %Y is a %A on the %d day of %B.")
'12-02-03. 02 Dec 2003 is a Tuesday on the 02 day of December.'

>>> # dates support calendar arithmetic
>>> birthday = date(1964, 7, 31)
>>> age = now - birthday
>>> age.days
14368

10.9. Compresión de datos

Los formatos para archivar y comprimir datos se soportan directamente con los módulos: zlib, gzip, bz2, lzma, zipfile y tarfile.

>>> import zlib
>>> s = b'witch which has which witches wrist watch'
>>> len(s)
41
>>> t = zlib.compress(s)
>>> len(t)
37
>>> zlib.decompress(t)
b'witch which has which witches wrist watch'
>>> zlib.crc32(s)
226805979

10.10. Medición de rendimiento

Algunos usuarios de Python desarrollan un profundo interés en saber el rendimiento relativo de las diferentes soluciones al mismo problema. Python provee una herramienta de medición que responde esas preguntas inmediatamente.

Por ejemplo, puede ser tentador usar la característica de empaquetado y desempaquetado de las tuplas en lugar de la solución tradicional para intercambiar argumentos. El módulo timeit muestra rápidamente una modesta ventaja de rendimiento:

>>> from timeit import Timer
>>> Timer('t=a; a=b; b=t', 'a=1; b=2').timeit()
0.57535828626024577
>>> Timer('a,b = b,a', 'a=1; b=2').timeit()
0.54962537085770791

En contraste con el fino nivel de medición del módulo timeit, los módulos profile y pstats proveen herramientas para identificar secciones críticas de tiempo en bloques de código más grandes.

10.11. Control de calidad

Una forma para desarrollar software de alta calidad es escribir pruebas para cada función mientras se la desarrolla, y correr esas pruebas frecuentemente durante el proceso de desarrollo.

El módulo doctest provee una herramienta para revisar un módulo y validar las pruebas integradas en las cadenas de documentación (o docstring) del programa. La construcción de las pruebas es tan sencillo como cortar y pegar una ejecución típica junto con sus resultados en los docstrings. Esto mejora la documentación al proveer al usuario un ejemplo y permite que el módulo doctest se asegure que el código permanece fiel a la documentación:

def average(values):
    """Computes the arithmetic mean of a list of numbers.

    >>> print(average([20, 30, 70]))
    40.0
    """
    return sum(values) / len(values)

import doctest
doctest.testmod()   # automatically validate the embedded tests

El módulo unittest necesita más esfuerzo que el módulo doctest, pero permite que se mantenga en un archivo separado un conjunto más comprensivo de pruebas:

import unittest

class TestStatisticalFunctions(unittest.TestCase):

    def test_average(self):
        self.assertEqual(average([20, 30, 70]), 40.0)
        self.assertEqual(round(average([1, 5, 7]), 1), 4.3)
        with self.assertRaises(ZeroDivisionError):
            average([])
        with self.assertRaises(TypeError):
            average(20, 30, 70)

unittest.main()  # Calling from the command line invokes all tests

10.12. Las pilas incluidas

Python tiene una filosofía de «pilas incluidas». Esto se ve mejor en las capacidades robustas y sofisticadas de sus paquetes más grandes. Por ejemplo:

The xmlrpc.client and xmlrpc.server modules make implementing remote procedure calls into an almost trivial task. Despite the modules” names, no direct knowledge or handling of XML is needed.

El paquete email es una biblioteca para administrar mensajes de correo electrónico, incluidos MIME y otros documentos de mensajes basados en RFC 2822 [https://tools.ietf.org/html/rfc2822.html]. A diferencia de smtplib y poplib que realmente envían y reciben mensajes, el paquete de correo electrónico tiene un conjunto de herramientas completo para crear o decodificar estructuras de mensajes complejas (incluidos los archivos adjuntos) y para implementar protocolos de codificación y encabezado de Internet.

El paquete json proporciona un sólido soporte para analizar este popular formato de intercambio de datos. El módulo csv admite la lectura y escritura directa de archivos en formato de valor separado por comas, comúnmente compatible con bases de datos y hojas de cálculo. El procesamiento XML es compatible con los paquetes xml.etree.ElementTree, xml.dom y xml.sax. Juntos, estos módulos y paquetes simplifican en gran medida el intercambio de datos entre aplicaciones de Python y otras herramientas.

El módulo sqlite3 es un wrapper para la biblioteca de bases de datos SQLite, proporcionando una base de datos persistente que se puede actualizar y acceder mediante una sintaxis SQL ligeramente no estándar.

La internacionalización es compatible con una serie de módulos, incluyendo gettext, locale, y el paquete codecs.

11. Pequeño paseo por la Biblioteca Estándar— Parte II

Este segundo paseo cubre módulos más avanzados que facilitan necesidades de programación complejas. Estos módulos raramente se usan en scripts cortos.

11.1. Formato de salida

El módulo reprlib provee una versión de repr() ajustada para mostrar contenedores grandes o profundamente anidados, en forma abreviada:

>>> import reprlib
>>> reprlib.repr(set('supercalifragilisticexpialidocious'))
"{'a', 'c', 'd', 'e', 'f', 'g', ...}"

El módulo pprint ofrece un control más sofisticado de la forma en que se imprimen tanto los objetos predefinidos como los objetos definidos por el usuario, de manera que sean legibles por el intérprete. Cuando el resultado ocupa más de una línea, el generador de «impresiones lindas» agrega saltos de línea y sangrías para mostrar la estructura de los datos más claramente:

>>> import pprint
>>> t = [[[['black', 'cyan'], 'white', ['green', 'red']], [['magenta',
...     'yellow'], 'blue']]]
...
>>> pprint.pprint(t, width=30)
[[[['black', 'cyan'],
   'white',
   ['green', 'red']],
  [['magenta', 'yellow'],
   'blue']]]

El módulo textwrap formatea párrafos de texto para que quepan dentro de cierto ancho de pantalla:

>>> import textwrap
>>> doc = """The wrap() method is just like fill() except that it returns
... a list of strings instead of one big string with newlines to separate
... the wrapped lines."""
...
>>> print(textwrap.fill(doc, width=40))
The wrap() method is just like fill()
except that it returns a list of strings
instead of one big string with newlines
to separate the wrapped lines.

El módulo locale accede a una base de datos de formatos específicos a una cultura. El atributo grouping de la función format permite una forma directa de formatear números con separadores de grupo:

>>> import locale
>>> locale.setlocale(locale.LC_ALL, 'English_United States.1252')
'English_United States.1252'
>>> conv = locale.localeconv()          # get a mapping of conventions
>>> x = 1234567.8
>>> locale.format("%d", x, grouping=True)
'1,234,567'
>>> locale.format_string("%s%.*f", (conv['currency_symbol'],
...                      conv['frac_digits'], x), grouping=True)
'$1,234,567.80'

11.2. Plantillas

El módulo string incluye una clase versátil Template (plantilla) con una sintaxis simplificada apta para ser editada por usuarios finales. Esto permite que los usuarios personalicen sus aplicaciones sin necesidad de modificar la aplicación en sí.

El formato usa marcadores cuyos nombres se forman con $ seguido de identificadores Python válidos (caracteres alfanuméricos y guión de subrayado). Si se los encierra entre llaves, pueden seguir más caracteres alfanuméricos sin necesidad de dejar espacios en blanco. $$ genera un $:

>>> from string import Template
>>> t = Template('${village}folk send $$10 to $cause.')
>>> t.substitute(village='Nottingham', cause='the ditch fund')
'Nottinghamfolk send $10 to the ditch fund.'

El método substitute() lanza KeyError cuando no se suministra ningún valor para un marcador mediante un diccionario o argumento por nombre. Para algunas aplicaciones los datos suministrados por el usuario puede ser incompletos, y el método safe_substitute() puede ser más apropiado: deja los marcadores inalterados cuando falten datos:

>>> t = Template('Return the $item to $owner.')
>>> d = dict(item='unladen swallow')
>>> t.substitute(d)
Traceback (most recent call last):
  ...
KeyError: 'owner'
>>> t.safe_substitute(d)
'Return the unladen swallow to $owner.'

Las subclases de Template pueden especificar un delimitador propio. Por ejemplo, una utilidad de renombrado por lotes para una galería de fotos puede escoger usar signos de porcentaje para los marcadores tales como la fecha actual, el número de secuencia de la imagen, o el formato de archivo:

>>> import time, os.path
>>> photofiles = ['img_1074.jpg', 'img_1076.jpg', 'img_1077.jpg']
>>> class BatchRename(Template):
...     delimiter = '%'
>>> fmt = input('Enter rename style (%d-date %n-seqnum %f-format):  ')
Enter rename style (%d-date %n-seqnum %f-format):  Ashley_%n%f

>>> t = BatchRename(fmt)
>>> date = time.strftime('%d%b%y')
>>> for i, filename in enumerate(photofiles):
...     base, ext = os.path.splitext(filename)
...     newname = t.substitute(d=date, n=i, f=ext)
...     print('{0} --> {1}'.format(filename, newname))

img_1074.jpg --> Ashley_0.jpg
img_1076.jpg --> Ashley_1.jpg
img_1077.jpg --> Ashley_2.jpg

Las plantillas también pueden ser usadas para separar la lógica del programa de los detalles de múltiples formatos de salida. Esto permite sustituir plantillas específicas para archivos XML, reportes en texto plano, y reportes web en HTML.

11.3. Trabajar con registros estructurados conteniendo datos binarios

El módulo struct provee las funciones pack() y unpack() para trabajar con formatos de registros binarios de longitud variable. El siguiente ejemplo muestra cómo recorrer la información de encabezado en un archivo ZIP sin usar el módulo zipfile. Los códigos "H" e "I" representan números sin signo de dos y cuatro bytes respectivamente. El "<" indica que son de tamaño estándar y los bytes tienen ordenamiento little-endian:

import struct

with open('myfile.zip', 'rb') as f:
    data = f.read()

start = 0
for i in range(3):                      # show the first 3 file headers
    start += 14
    fields = struct.unpack('<IIIHH', data[start:start+16])
    crc32, comp_size, uncomp_size, filenamesize, extra_size = fields

    start += 16
    filename = data[start:start+filenamesize]
    start += filenamesize
    extra = data[start:start+extra_size]
    print(filename, hex(crc32), comp_size, uncomp_size)

    start += extra_size + comp_size     # skip to the next header

11.4. Multi-hilos

La técnica de multi-hilos (o multi-threading) permite desacoplar tareas que no tienen dependencia secuencial. Los hilos se pueden usar para mejorar el grado de reacción de las aplicaciones que aceptan entradas del usuario mientras otras tareas se ejecutan en segundo plano. Un caso de uso relacionado es ejecutar E/S en paralelo con cálculos en otro hilo.

El código siguiente muestra cómo el módulo de alto nivel threading puede ejecutar tareas en segundo plano mientras el programa principal continúa su ejecución:

import threading, zipfile

class AsyncZip(threading.Thread):
    def __init__(self, infile, outfile):
        threading.Thread.__init__(self)
        self.infile = infile
        self.outfile = outfile

    def run(self):
        f = zipfile.ZipFile(self.outfile, 'w', zipfile.ZIP_DEFLATED)
        f.write(self.infile)
        f.close()
        print('Finished background zip of:', self.infile)

background = AsyncZip('mydata.txt', 'myarchive.zip')
background.start()
print('The main program continues to run in foreground.')

background.join()    # Wait for the background task to finish
print('Main program waited until background was done.')

El desafío principal de las aplicaciones multi-hilo es la coordinación entre los hilos que comparten datos u otros recursos. A ese fin, el módulo threading provee una serie de primitivas de sincronización que incluyen bloqueos, eventos, variables de condición, y semáforos.

Aún cuando esas herramientas son poderosas, pequeños errores de diseño pueden resultar en problemas difíciles de reproducir. La forma preferida de coordinar tareas es concentrar todos los accesos a un recurso en un único hilo y después usar el módulo queue para alimentar dicho hilo con pedidos desde otros hilos. Las aplicaciones que usan objetos Queue para comunicación y coordinación entre hilos son más fáciles de diseñar, más legibles, y más confiables.

11.5. Registrando

El módulo logging ofrece un sistema de registros (logs) completo y flexible. En su forma más simple, los mensajes de registro se envían a un archivo o a sys.stderr:

import logging
logging.debug('Debugging information')
logging.info('Informational message')
logging.warning('Warning:config file %s not found', 'server.conf')
logging.error('Error occurred')
logging.critical('Critical error -- shutting down')

Ésta es la salida obtenida:

WARNING:root:Warning:config file server.conf not found
ERROR:root:Error occurred
CRITICAL:root:Critical error -- shutting down

De forma predeterminada, los mensajes de depuración e informativos se suprimen, y la salida se envía al error estándar. Otras opciones de salida incluyen mensajes de enrutamiento a través de correo electrónico, datagramas, sockets, o un servidor HTTP. Nuevos filtros pueden seleccionar diferentes rutas basadas en la prioridad del mensaje: DEBUG, INFO, WARNING, ERROR, y CRITICAL (Depuración, Informativo, Atención, Error y Crítico respectivamente)

El sistema de registro puede configurarse directamente desde Python o puede cargarse la configuración desde un archivo modificable por el usuario para personalizar el registro sin alterar la aplicación.

11.6. Referencias débiles

Python realiza administración de memoria automática (cuenta de referencias para la mayoría de los objetos, y garbage collection para eliminar ciclos). La memoria se libera poco después de que la última referencia a la misma haya sido eliminada.

Este enfoque funciona bien para la mayoría de las aplicaciones pero de vez en cuando existe la necesidad de controlar objetos sólo mientras estén siendo utilizados por otra cosa. Desafortunadamente, el sólo hecho de controlarlos crea una referencia que los convierte en permanentes. El módulo weakref provee herramientas para controlar objetos sin crear una referencia. Cuando el objeto no se necesita mas, es removido automáticamente de una tabla de referencias débiles y se dispara una callback para objetos weakref. Comúnmente las aplicaciones incluyen cacheo de objetos que son costosos de crear:

>>> import weakref, gc
>>> class A:
...     def __init__(self, value):
...         self.value = value
...     def __repr__(self):
...         return str(self.value)
...
>>> a = A(10)                   # create a reference
>>> d = weakref.WeakValueDictionary()
>>> d['primary'] = a            # does not create a reference
>>> d['primary']                # fetch the object if it is still alive
10
>>> del a                       # remove the one reference
>>> gc.collect()                # run garbage collection right away
0
>>> d['primary']                # entry was automatically removed
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
    d['primary']                # entry was automatically removed
  File "C:/python39/lib/weakref.py", line 46, in __getitem__
    o = self.data[key]()
KeyError: 'primary'

11.7. Herramientas para trabajar con listas

Muchas necesidades de estructuras de datos pueden ser satisfechas con el tipo integrado lista. Sin embargo, a veces se hacen necesarias implementaciones alternativas con rendimientos distintos.

El módulo array provee un objeto array() (vector) que es como una lista que almacena sólo datos homogéneos y de una manera más compacta. Los ejemplos a continuación muestran un vector de números guardados como dos números binarios sin signo de dos bytes (código de tipo "H") en lugar de los 16 bytes por elemento habituales en listas de objetos int de Python:

>>> from array import array
>>> a = array('H', [4000, 10, 700, 22222])
>>> sum(a)
26932
>>> a[1:3]
array('H', [10, 700])

El módulo collections provee un objeto deque() que es como una lista más rápida para agregar y quitar elementos por el lado izquierdo pero con búsquedas más lentas por el medio. Estos objetos son adecuados para implementar colas y árboles de búsqueda a lo ancho:

>>> from collections import deque
>>> d = deque(["task1", "task2", "task3"])
>>> d.append("task4")
>>> print("Handling", d.popleft())
Handling task1

unsearched = deque([starting_node])
def breadth_first_search(unsearched):
    node = unsearched.popleft()
    for m in gen_moves(node):
        if is_goal(m):
            return m
        unsearched.append(m)

Además de las implementaciones alternativas de listas, la biblioteca ofrece otras herramientas como el módulo bisect con funciones para manipular listas ordenadas:

>>> import bisect
>>> scores = [(100, 'perl'), (200, 'tcl'), (400, 'lua'), (500, 'python')]
>>> bisect.insort(scores, (300, 'ruby'))
>>> scores
[(100, 'perl'), (200, 'tcl'), (300, 'ruby'), (400, 'lua'), (500, 'python')]

El módulo heapq provee funciones para implementar pilas (heaps) basados en listas comunes. El menor valor ingresado se mantiene en la posición cero. Esto es útil para aplicaciones que acceden a menudo al elemento más chico pero no quieren hacer un orden completo de la lista:

>>> from heapq import heapify, heappop, heappush
>>> data = [1, 3, 5, 7, 9, 2, 4, 6, 8, 0]
>>> heapify(data)                      # rearrange the list into heap order
>>> heappush(data, -5)                 # add a new entry
>>> [heappop(data) for i in range(3)]  # fetch the three smallest entries
[-5, 0, 1]

11.8. Aritmética de punto flotante decimal

El módulo decimal provee un tipo de dato Decimal para soportar aritmética de punto flotante decimal. Comparado con float, la implementación de punto flotante binario incluida, la clase es muy útil especialmente para

aplicaciones financieras y otros usos que requieren representación decimal exacta,

control sobre la precisión,

control sobre el redondeo para cumplir requisitos legales,

seguimiento de dígitos decimales significativos, o

aplicaciones donde el usuario espera que los resultados coincidan con cálculos hecho a mano.

Por ejemplo, calcular un impuesto del 5% de una tarifa telefónica de 70 centavos da resultados distintos con punto flotante decimal y punto flotante binario. La diferencia se vuelve significativa si los resultados se redondean al centavo más próximo:

>>> from decimal import *
>>> round(Decimal('0.70') * Decimal('1.05'), 2)
Decimal('0.74')
>>> round(.70 * 1.05, 2)
0.73

El resultado con Decimal conserva un cero al final, calculando automáticamente cuatro cifras significativas a partir de los multiplicandos con dos cifras significativas. Decimal reproduce la matemática como se la hace a mano, y evita problemas que pueden surgir cuando el punto flotante binario no puede representar exactamente cantidades decimales.

La representación exacta permite a la clase Decimal hacer cálculos de modulo y pruebas de igualdad que son inadecuadas para punto flotante binario:

>>> Decimal('1.00') % Decimal('.10')
Decimal('0.00')
>>> 1.00 % 0.10
0.09999999999999995

>>> sum([Decimal('0.1')]*10) == Decimal('1.0')
True
>>> sum([0.1]*10) == 1.0
False

El módulo decimal provee aritmética con tanta precisión como haga falta:

>>> getcontext().prec = 36
>>> Decimal(1) / Decimal(7)
Decimal('0.142857142857142857142857142857142857')

12. Entornos Virtuales y Paquetes

12.1. Introducción

Las aplicaciones en Python usualmente hacen uso de paquetes y módulos que no forman parte de la librería estándar. Las aplicaciones a veces necesitan una versión específica de una librería, debido a que dicha aplicación requiere que un bug particular haya sido solucionado o bien la aplicación ha sido escrita usando una versión obsoleta de la interfaz de la librería.

Esto significa que tal vez no sea posible para una instalación de Python cumplir los requerimientos de todas las aplicaciones. Si la aplicación A necesita la versión 1.0 de un módulo particular y la aplicación B necesita la versión 2.0, entonces los requerimientos entran en conflicto e instalar la versión 1.0 o 2.0 dejará una de las aplicaciones sin funcionar.

La solución a este problema es crear un entorno virtual, un directorio que contiene una instalación de Python de una versión en particular, además de unos cuantos paquetes adicionales.

Diferentes aplicaciones pueden entonces usar entornos virtuales diferentes. Para resolver el ejemplo de requerimientos en conflicto citado anteriormente, la aplicación A puede tener su propio entorno virtual con la versión 1.0 instalada mientras que la aplicación B tiene otro entorno virtual con la versión 2.0. Si la aplicación B requiere que actualizar la librería a la versión 3.0, ésto no afectará el entorno virtual de la aplicación A.

12.2. Creando Entornos Virtuales

El script usado para crear y manejar entornos virtuales es pyvenv. pyvenv normalmente instalará la versión mas reciente de Python que tengas disponible; el script también es instalado con un número de versión, con lo que si tienes múltiples versiones de Python en tu sistema puedes seleccionar una versión de Python específica ejecutando python3 o la versión que desees.

Para crear un entorno virtual, decide en que carpeta quieres crearlo y ejecuta el módulo venv como script con la ruta a la carpeta:

python3 -m venv tutorial-env

Esto creará la carpeta tutorial-env si no existe, y también creará las subcarpetas conteniendo la copia del intérprete Python, la librería estándar y los archivos de soporte.

Una ruta común para el directorio de un entorno virtual es .venv. Ese nombre mantiene el directorio típicamente escondido en la consola y fuera de vista mientras le da un nombre que explica cuál es el motivo de su existencia. También permite que no colisione con los ficheros de definición de variables de entorno .env que algunas herramientas soportan.

Una vez creado el entorno virtual, podrás activarlo.

En Windows, ejecuta:

tutorial-env\Scripts\activate.bat

En Unix o MacOS, ejecuta:

source tutorial-env/bin/activate

(Este script está escrito para la consola bash. Si usas las consolas csh or fish, hay scripts alternativos activate.csh y activate.fish que deberá usar en su lugar.)

Activar el entorno virtual cambiará el prompt de tu consola para mostrar que entorno virtual está usando, y modificará el entorno para que al ejecutar python sea con esa versión e instalación en particular. Por ejemplo:

$ source ~/envs/tutorial-env/bin/activate
(tutorial-env) $ python
Python 3.5.1 (default, May  6 2016, 10:59:36)
  ...
>>> import sys
>>> sys.path
['', '/usr/local/lib/python35.zip', ...,
'~/envs/tutorial-env/lib/python3.5/site-packages']
>>>

12.3. Manejando paquetes con pip

You can install, upgrade, and remove packages using a program called pip. By default pip will install packages from the Python Package Index, <https://pypi.org>. You can browse the Python Package Index by going to it in your web browser.

pip has a number of subcommands: «install», «uninstall», «freeze», etc. (Consult the Instalando módulos de Python guide for complete documentation for pip.)

Se puede instalar la última versión de un paquete especificando el nombre del paquete:

(tutorial-env) $ python -m pip install novas
Collecting novas
  Downloading novas-3.1.1.3.tar.gz (136kB)
Installing collected packages: novas
  Running setup.py install for novas
Successfully installed novas-3.1.1.3

También se puede instalar una versión específica de un paquete ingresando el nombre del paquete seguido de == y el número de versión:

(tutorial-env) $ python -m pip install requests==2.6.0
Collecting requests==2.6.0
  Using cached requests-2.6.0-py2.py3-none-any.whl
Installing collected packages: requests
Successfully installed requests-2.6.0

Si se re-ejecuta el comando, pip detectará que la versión ya está instalada y no hará nada. Se puede ingresar un número de versión diferente para instalarlo, o se puede ejecutar pip install --upgrade para actualizar el paquete a la última versión:

(tutorial-env) $ python -m pip install --upgrade requests
Collecting requests
Installing collected packages: requests
  Found existing installation: requests 2.6.0
    Uninstalling requests-2.6.0:
      Successfully uninstalled requests-2.6.0
Successfully installed requests-2.7.0

pip uninstall seguido de uno o varios nombres de paquetes eliminará los paquetes del entorno virtual.

pip show mostrará información de un paquete en particular:

(tutorial-env) $ pip show requests
---
Metadata-Version: 2.0
Name: requests
Version: 2.7.0
Summary: Python HTTP for Humans.
Home-page: http://python-requests.org
Author: Kenneth Reitz
Author-email: me@kennethreitz.com
License: Apache 2.0
Location: /Users/akuchling/envs/tutorial-env/lib/python3.4/site-packages
Requires:

pip list mostrará todos los paquetes instalados en el entorno virtual:

(tutorial-env) $ pip list
novas (3.1.1.3)
numpy (1.9.2)
pip (7.0.3)
requests (2.7.0)
setuptools (16.0)

pip freeze retorna una lista de paquetes instalados similar, pero el formato de salida es el requerido por pip install. Una convención común es poner esta lista en un archivo requirements.txt:

(tutorial-env) $ pip freeze > requirements.txt
(tutorial-env) $ cat requirements.txt
novas==3.1.1.3
numpy==1.9.2
requests==2.7.0

El archivo requirements.txt entonces puede ser agregado a nuestro control de versiones y distribuido como parte de la aplicación. Los usuarios pueden entonces instalar todos los paquetes necesarios con install -r:

(tutorial-env) $ python -m pip install -r requirements.txt
Collecting novas==3.1.1.3 (from -r requirements.txt (line 1))
  ...
Collecting numpy==1.9.2 (from -r requirements.txt (line 2))
  ...
Collecting requests==2.7.0 (from -r requirements.txt (line 3))
  ...
Installing collected packages: novas, numpy, requests
  Running setup.py install for novas
Successfully installed novas-3.1.1.3 numpy-1.9.2 requests-2.7.0

pip tiene muchas más opciones. Consulte la guía Instalando módulos de Python para obtener documentación completa de pip. Cuando haya escrito un paquete y desee que esté disponible en el índice de paquetes de Python, consulte la guía Distribuir módulos de Python.

13. ¿Y ahora qué?

Leer este tutorial probablemente reforzó tu interés por usar Python, deberías estar ansioso por aplicar Python a la resolución de tus problemas reales. ¿A dónde deberías ir para aprender más?

Este tutorial forma parte del conjunto de documentación de Python. Algunos otros documentos que encontrarás en este conjunto son:

La Biblioteca Estándar de Python:

Deberías navegar a través de este manual, que da una completa pero breve referencia sobre los tipos, funciones y módulos en la librería estándar. La distribución estándar de Python incluye mucho más código adicional. Hay módulos para leer buzones Unix, obtener documentos vía HTTP, generar números aleatorios, analizar opciones de línea de comandos, escribir programas CGI, comprimir datos y muchas más tareas. Echar una ojeada a la Librería de Referencia te dará una idea de lo que está disponible.

Instalando módulos de Python explica como instalar módulos adicionales escritos por otros usuarios de Python.

Referencia del Lenguaje Python: Una explicación detallada de la sintaxis y la semántica de Python. Es una lectura pesada, pero es muy útil como guía complete del lenguaje.

Más recursos sobre Python:

https://www.python.org: El mayor sitio web de Python. Contiene código, documentación, y enlaces a páginas web relacionadas con Python. Esta web está replicada en varios sitios alrededor del mundo, como Europa, Japón y Australia; una réplica puede ser más rápida que el sitio principal, dependiendo de tu localización geográfica.

https://docs.python.org: Acceso rápido a la documentación de Python.

https://pypi.org: El Python Package Index, apodado previamente la Tienda de Queso 1, es un índice de módulos de Python creados por usuarios que están disponibles para su descarga. Cuando empiezas a distribuir código, lo puedes registrar allí para que otros lo encuentren.

https://code.activestate.com/recipes/langs/python/: El Python Cookbook es una gran colección de ejemplos de código, módulos grandes y scripts útiles. Las contribuciones más notables también están recogidas en un libro titulado Python Cookbook (O’Reilly & Associates, ISBN 0-596-00797-3.)

http://www.pyvideo.org recoge enlaces a vídeos relacionados con Python provenientes de conferencias y de reuniones de grupos de usuarios.

https://scipy.org: El proyecto de Python científico incluye módulos para el cálculo rápido de operaciones y manipulaciones sobre arrays además de muchos paquetes para cosas como Álgebra Lineal, Transformadas de Fourier, solucionadores de sistemas no-lineales, distribuciones de números aleatorios, análisis estadísticos y otras herramientas.

Para preguntas relacionadas con Python y reportes de problemas puedes escribir al grupo de noticias comp.lang.python, o enviarlas a la lista de correo que hay en python-list@python.org. El grupo de noticias y la lista de correo están conectados, por lo que los mensajes enviados a uno serán retransmitidos al otro. Hay alrededor de cientos de mensajes diarios (con picos de hasta varios cientos), haciendo (y respondiendo) preguntas, sugiriendo nuevas características, y anunciando nuevos módulos. Los archivos de la lista de correos están disponibles en https://mail.python.org/pipermail/.

Antes de escribir, asegúrate de haber revisado la lista de Frequently Asked Questions (también llamado el FAQ). Muchas veces responde las preguntas que se hacen una y otra vez, y quizás contenga la solución a tu problema.

Notas al pie

1

La tienda de queso, Cheese Shop, es un chiste de Monty Python: un cliente entra a una tienda de queso pero para cualquier queso que pide, el vendedor le dice que no lo tienen.

14. Edición de entrada interactiva y sustitución de historial

Algunas versiones del intérprete de Python permiten editar la línea de entrada actual, y sustituir en base al historial, de forma similar a las capacidades del intérprete de comandos Korn y el GNU bash. Esto se implementa con la biblioteca GNU Readline [https://tiswww.case.edu/php/chet/readline/rltop.html], que soporta varios estilos de edición. Esta biblioteca tiene su propia documentación la cuál no vamos a duplicar aquí.

14.1. Autocompletado con tab e historial de edición

El autocompletado de variables y nombres de módulos es automatically enabled al iniciar el intérprete, por lo tanto la tecla Tab invoca la función de autocompletado; ésta mira en los nombres de sentencia, las variables locales y los nombres de módulos disponibles. Para expresiones con puntos como string.a, va a evaluar la expresión hasta el '.' final y entonces sugerir autocompletado para los atributos del objeto resultante. Nota que esto quizás ejecute código de aplicaciones definidas si un objeto con un método __getattr__() es parte de la expresión. La configuración por omisión también guarda tu historial en un archivo llamado .python_history en tu directorio de usuario. El historial estará disponible durante la próxima sesión interactiva del intérprete.

14.2. Alternativas al intérprete interactivo

Esta funcionalidad es un paso enorme hacia adelante comparado con versiones anteriores del interprete; de todos modos, quedan pendientes algunos deseos: sería bueno que el sangrado correcto se sugiriera en las lineas de continuación (el parser sabe si se requiere un sangrado a continuación). El mecanismo de completado podría usar la tabla de símbolos del intérprete. Un comando para verificar (o incluso sugerir) coincidencia de paréntesis, comillas, etc. también sería útil.

Un intérprete interactivo mejorado alternativo que está dando vueltas desde hace rato es IPython [https://ipython.org/], que ofrece completado por tab, exploración de objetos, y administración avanzada del historial. También puede ser configurado en profundidad, e integrarse en otras aplicaciones. Otro entorno interactivo mejorado similar es bpython [https://www.bpython-interpreter.org/].

15. Aritmética de Punto Flotante: Problemas y Limitaciones

Los números de punto flotante se representan en el hardware de la computadora en fracciones en base 2 (binario). Por ejemplo, la fracción decimal

0.125

…tiene el valor 1/10 + 2/100 + 5/1000, y de la misma manera la fracción binaria

0.001

…tiene el valor 0/2 + 0/4 + 1/8. Estas dos fracciones tienen valores idénticos, la única diferencia real es que la primera está escrita en notación fraccional en base 10 y la segunda en base 2.

Desafortunadamente, la mayoría de las fracciones decimales no pueden representarse exactamente como fracciones binarias. Como consecuencia, en general los números de punto flotante decimal que ingresás en la computadora son sólo aproximados por los números de punto flotante binario que realmente se guardan en la máquina.

El problema es más fácil de entender primero en base 10. Considerá la fracción 1/3. Podés aproximarla como una fracción de base 10

0.3

…o, mejor,

0.33

…o, mejor,

0.333

…y así. No importa cuantos dígitos desees escribir, el resultado nunca será exactamente 1/3, pero será una aproximación cada vez mejor de 1/3.

De la misma manera, no importa cuantos dígitos en base 2 quieras usar, el valor decimal 0.1 no puede representarse exactamente como una fracción en base 2. En base 2, 1/10 es la siguiente fracción que se repite infinitamente:

0.0001100110011001100110011001100110011001100110011...

Frená en cualquier número finito de bits, y tendrás una aproximación. En la mayoría de las máquinas hoy en día, los float se aproximan usando una fracción binaria con el numerador usando los primeros 53 bits con el bit más significativos y el denominador como una potencia de dos. En el caso de 1/10, la fracción binaria es 3602879701896397 / 2 ** 55 que está cerca pero no es exactamente el valor verdadero de 1/10.

La mayoría de los usuarios no son conscientes de esta aproximación por la forma en que se muestran los valores. Python solamente muestra una aproximación decimal al valor verdadero decimal de la aproximación binaria almacenada por la máquina. En la mayoría de las máquinas, si Python fuera a imprimir el verdadero valor decimal de la aproximación binaria almacenada para 0.1, debería mostrar

>>> 0.1
0.1000000000000000055511151231257827021181583404541015625

Esos son más dígitos que lo que la mayoría de la gente encuentra útil, por lo que Python mantiene manejable la cantidad de dígitos al mostrar en su lugar un valor redondeado

>>> 1 / 10
0.1

Sólo recordá que, a pesar de que el valor mostrado resulta ser exactamente 1/10, el valor almacenado realmente es la fracción binaria más cercana posible.

Interesantemente, hay varios números decimales que comparten la misma fracción binaria más aproximada. Por ejemplo, los números 0.1, 0.10000000000000001 y 0.1000000000000000055511151231257827021181583404541015625 son todos aproximados por 3602879701896397 / 2 ** 55. Ya que todos estos valores decimales comparten la misma aproximación, se podría mostrar cualquiera de ellos para preservar el invariante eval(repr(x)) == x.

Históricamente, el prompt de Python y la función integrada repr() eligieron el valor con los 17 dígitos, 0.10000000000000001. Desde Python 3.1, en la mayoría de los sistemas Python ahora es capaz de elegir la forma más corta de ellos y mostrar 0.1.

Notá que esta es la verdadera naturaleza del punto flotante binario: no es un error de Python, y tampoco es un error en tu código. Verás lo mismo en todos los lenguajes que soportan la aritmética de punto flotante de tu hardware (a pesar de que en algunos lenguajes por omisión no muestren la diferencia, o no lo hagan en todos los modos de salida).

Para una salida más elegante, quizás quieras usar el formateo de cadenas de texto para generar un número limitado de dígitos significativos:

>>> format(math.pi, '.12g')  # give 12 significant digits
'3.14159265359'

>>> format(math.pi, '.2f')   # give 2 digits after the point
'3.14'

>>> repr(math.pi)
'3.141592653589793'

Es importante darse cuenta que esto es, realmente, una ilusión: estás simplemente redondeando al mostrar el valor verdadero de la máquina.

Una ilusión puede generar otra. Por ejemplo, ya que 0.1 no es exactamente 1/10, sumar tres veces 0.1 podría también no generar exactamente 0.3:

>>> .1 + .1 + .1 == .3
False

También, ya que 0.1 no puede acercarse más al valor exacto de 1/10 y 0.3 no puede acercarse más al valor exacto de 3/10, redondear primero con la función round() no puede ayudar:

>>> round(.1, 1) + round(.1, 1) + round(.1, 1) == round(.3, 1)
False

A pesar que los números no pueden acercarse a los valores exactos que pretendemos, la función round() puede ser útil para redondear a posteriori, para que los resultados con valores inexactos se puedan comparar entre sí:

>>> round(.1 + .1 + .1, 10) == round(.3, 10)
True

Binary floating-point arithmetic holds many surprises like this. The problem with «0.1» is explained in precise detail below, in the «Representation Error» section. See The Perils of Floating Point [https://www.lahey.com/float.htm] for a more complete account of other common surprises.

Como dice cerca del final, «no hay respuestas fáciles». A pesar de eso, ¡no le tengas mucho miedo al punto flotante! Los errores en las operaciones flotantes de Python se heredan del hardware de punto flotante, y en la mayoría de las máquinas están en el orden de no más de una 1 parte en 2**53 por operación. Eso es más que adecuado para la mayoría de las tareas, pero necesitás tener en cuenta que no es aritmética decimal, y que cada operación de punto flotante sufre un nuevo error de redondeo.

A pesar de que existen casos patológicos, para la mayoría de usos casuales de la aritmética de punto flotante al final verás el resultado que esperás si simplemente redondeás lo que mostrás de tus resultados finales al número de dígitos decimales que esperás. str() es normalmente suficiente, y para un control más fino mirá los parámetros del método de formateo str.format() en Formato de cadena de caracteres personalizado.

Para los casos de uso que necesitan una representación decimal exacta, probá el módulo decimal, que implementa aritmética decimal útil para aplicaciones de contabilidad y de alta precisión.

El módulo fractions soporta otra forma de aritmética exacta, ya que implementa aritmética basada en números racionales (por lo que números como 1/3 pueden ser representados exactamente).

If you are a heavy user of floating point operations you should take a look at the NumPy package and many other packages for mathematical and statistical operations supplied by the SciPy project. See <https://scipy.org>.

Python provee herramientas que pueden ayudar en esas raras ocasiones cuando realmente querés saber el valor exacto de un float. El método float.as_integer_ratio() expresa el valor del float como una fracción:

>>> x = 3.14159
>>> x.as_integer_ratio()
(3537115888337719, 1125899906842624)

Ya que la fracción es exacta, se puede usar para recrear sin pérdidas el valor original:

>>> x == 3537115888337719 / 1125899906842624
True

El método float.hex() expresa un float en hexadecimal (base 16), nuevamente retornando el valor exacto almacenado por tu computadora:

>>> x.hex()
'0x1.921f9f01b866ep+1'

Esta representación hexadecimal precisa se puede usar para reconstruir el valor exacto del float:

>>> x == float.fromhex('0x1.921f9f01b866ep+1')
True

Ya que la representación es exacta, es útil para portar valores a través de diferentes versiones de Python de manera confiable (independencia de plataformas) e intercambiar datos con otros lenguajes que soportan el mismo formato (como Java y C99).

Otra herramienta útil es la función math.fsum() que ayuda a mitigar la pérdida de precisión durante la suma. Esta función lleva la cuenta de «dígitos perdidos» mientras se suman los valores en un total. Eso puede hacer una diferencia en la exactitud de lo que se va sumando para que los errores no se acumulen al punto en que afecten el total final:

>>> sum([0.1] * 10) == 1.0
False
>>> math.fsum([0.1] * 10) == 1.0
True

15.1. Error de Representación

Esta sección explica el ejemplo «0.1» en detalle, y muestra como en la mayoría de los casos vos mismo podés realizar un análisis exacto como este. Se asume un conocimiento básico de la representación de punto flotante binario.

Error de representación se refiere al hecho de que algunas (la mayoría) de las fracciones decimales no pueden representarse exactamente como fracciones binarias (en base 2). Esta es la razón principal de por qué Python (o Perl, C, C++, Java, Fortran, y tantos otros) frecuentemente no mostrarán el número decimal exacto que esperás.

¿Por qué es eso? 1/10 no es representable exactamente como una fracción binaria. Casi todas las máquinas de hoy en día (Noviembre del 2000) usan aritmética de punto flotante IEEE-754, y casi todas las plataformas mapean los flotantes de Python al «doble precisión» de IEEE-754. Estos «dobles» tienen 53 bits de precisión, por lo tanto en la entrada la computadora intenta convertir 0.1 a la fracción más cercana que puede de la forma J/2***N* donde J es un entero que contiene exactamente 53 bits. Reescribiendo

1 / 10 ~= J / (2**N)

…como

J ~= 2**N / 10

…y recordando que J tiene exactamente 53 bits (es >= 2**52 pero < 2**53), el mejor valor para N es 56:

>>> 2**52 <=  2**56 // 10  < 2**53
True

O sea, 56 es el único valor para N que deja J con exactamente 53 bits. El mejor valor posible para J es entonces el cociente redondeado:

>>> q, r = divmod(2**56, 10)
>>> r
6

Ya que el resto es más que la mitad de 10, la mejor aproximación se obtiene redondeándolo:

>>> q+1
7205759403792794

Por lo tanto la mejor aproximación a 1/10 en doble precisión 754 es:

7205759403792794 / 2 ** 56

El dividir tanto el numerador como el denominador reduce la fracción a:

3602879701896397 / 2 ** 55

Notá que como lo redondeamos, esto es un poquito más grande que 1/10; si no lo hubiéramos redondeado, el cociente hubiese sido un poquito menor que 1/10. ¡Pero no hay caso en que sea exactamente 1/10!

Entonces la computadora nunca «ve» 1/10: lo que ve es la fracción exacta de arriba, la mejor aproximación al flotante doble de 754 que puede obtener:

>>> 0.1 * 2 ** 55
3602879701896397.0

Si multiplicamos esa fracción por 10**55, podemos ver el valor hasta los 55 dígitos decimales:

>>> 3602879701896397 * 10 ** 55 // 2 ** 55
1000000000000000055511151231257827021181583404541015625

…lo que significa que el valor exacto almacenado en la computadora es igual al valor decimal 0.1000000000000000055511151231257827021181583404541015625. En lugar de mostrar el valor decimal completo, muchos lenguajes (incluyendo versiones más viejas de Python), redondean el resultado a 17 dígitos significativos:

>>> format(0.1, '.17f')
'0.10000000000000001'

Los módulos fractions y decimal hacen fácil estos cálculos:

>>> from decimal import Decimal
>>> from fractions import Fraction

>>> Fraction.from_float(0.1)
Fraction(3602879701896397, 36028797018963968)

>>> (0.1).as_integer_ratio()
(3602879701896397, 36028797018963968)

>>> Decimal.from_float(0.1)
Decimal('0.1000000000000000055511151231257827021181583404541015625')

>>> format(Decimal.from_float(0.1), '.17')
'0.10000000000000001'

16. Apéndice

16.1. Modo interactivo

16.1.1. Manejo de errores

Cuando ocurre un error, el intérprete imprime un mensaje de error y la traza del error. En el modo interactivo, luego retorna al prompt primario; cuando la entrada viene de un archivo, el programa termina con código de salida distinto a cero luego de imprimir la traza del error. (Las excepciones manejadas por una clausula except en una sentencia try no son errores en este contexto). Algunos errores son incondicionalmente fatales y causan una terminación con código de salida distinto de cero; esto se debe a inconsistencias internas o a que el intérprete se queda sin memoria. Todos los mensajes de error se escriben en el flujo de errores estándar; las salidas normales de comandos ejecutados se escriben en la salida estándar.

Al ingresar el carácter de interrupción (por lo general Control-C o Supr) en el prompt primario o secundario, se cancela la entrada y retorna al prompt primario. 1 Tipear una interrupción mientras un comando se están ejecutando lanza la excepción KeyboardInterrupt, que puede ser manejada con una sentencia try.

16.1.2. Programas ejecutables de Python

En los sistemas Unix y tipo BSD, los programas Python pueden convertirse directamente en ejecutables, como programas del intérprete de comandos, poniendo la linea:

#!/usr/bin/env python3.5

…al principio del script y dándole al archivo permisos de ejecución (asumiendo que el intérprete están en la variable de entorno PATH del usuario). #! deben ser los primeros dos caracteres del archivo. En algunas plataformas, la primera línea debe terminar al estilo Unix ('\n'), no como en Windows ('\r\n'). Notá que el carácter numeral '#' se usa en Python para comenzar un comentario.

Se le puede dar permisos de ejecución al script usando el comando chmod.

$ chmod +x myscript.py

En sistemas Windows, no existe la noción de «modo ejecutable». El instalador de Python asocia automáticamente la extensión .py con python.exe para que al hacerle doble clic a un archivo Python se corra el script. La extensión también puede ser .pyw, en este caso se omite la ventana con la consola que normalmente aparece.

16.1.3. El archivo de inicio interactivo

Cuando usas Python en forma interactiva, suele ser útil que algunos comandos estándar se ejecuten cada vez que el intérprete se inicia. Puedes hacer esto configurando la variable de entorno PYTHONSTARTUP con el nombre de un archivo que contenga tus comandos de inicio. Esto es similar al archivo .profile en los intérpretes de comandos de Unix.

Este archivo es solo leído en las sesiones interactivas del intérprete, no cuando Python lee comandos de un script ni cuando /dev/tty se explicita como una fuente de comandos (que de otro modo se comporta como una sesión interactiva). Se ejecuta en el mismo espacio de nombres en el que los comandos interactivos se ejecutan, entonces los objetos que define o importa pueden ser usados sin cualificaciones en la sesión interactiva. En este archivo también puedes cambiar los prompts sys.ps1 y sys.ps2.

Si quieres leer un archivo de inicio adicional desde el directorio actual, puedes programarlo en el archivo de inicio global usando algo como if os.path.isfile('.pythonrc.py'): exec(open('.pythonrc.py').read()). Si quieres usar el archivo de inicio en un script, tienes que hacer lo siguiente de forma explícita en el script:

import os
filename = os.environ.get('PYTHONSTARTUP')
if filename and os.path.isfile(filename):
    with open(filename) as fobj:
        startup_file = fobj.read()
    exec(startup_file)

16.1.4. Los módulos de customización

Python provee dos formas para customizarlo: sitecustomize y usercustomize. Para ver cómo funciona, necesitas primero encontrar dónde está tu directorio para tu usuario de paquetes del sistema. Inicia Python y ejecuta el siguiente código:

>>> import site
>>> site.getusersitepackages()
'/home/user/.local/lib/python3.5/site-packages'

Ahora puedes crear un archivo llamado usercustomize.py en ese directorio y poner lo que quieras en él. Eso afectará cada ejecución de Python, a menos que se inicie con la opción -s para deshabilitar esta importación automática.

sitecustomize funciona de la misma manera, pero normalmente lo crea el administrador de la computadora en el directorio global de paquetes para el sistema, y se importa antes que usercustomize. Para más detalles, mira la documentación del módulo site.

Notas al pie

1

Un problema con el paquete GNU Readline puede prevenir esto.

Configuración y Uso de Python

Esta parte de la documentación está dedicada a información general sobre la configuración del entorno Python en diferentes plataformas, la invocación del intérprete y cosas que facilitan el trabajo con Python.

1. Línea de comandos y entorno

1.1. Línea de comando

1.1.1. Opciones de interfaz

1.1.2. Opciones genéricas

1.1.3. Opciones diversas

1.1.4. Opciones que no debe usar

1.2. Variables de entorno

1.2.1. Variables de modo de depuración

2. Uso de Python en plataformas Unix

2.1. Obteniendo e instalando la última versión de Python

2.1.1. En Linux

2.1.2. En FreeBSD y OpenBSD

2.1.3. En OpenSolaris

2.2. Construyendo Python

2.3. Rutas y archivos relacionados con Python

2.4. Miscelánea

3. Uso de Python en Windows

3.1. El instalador completo

3.1.1. Pasos para la instalación

3.1.2. Quitar el límite de MAX_PATH

3.1.3. Instalación sin interfaz de usuario

3.1.4. Instalación sin descargas

3.1.5. Modificar una instalación

3.2. El paquete Microsoft Store

3.2.1. Problemas conocidos

3.3. El paquete de nuget.org

3.4. El paquete incrustable

3.4.1. Aplicación Python

3.4.2. Incrustar Python

3.5. Distribuciones alternativas

3.6. Configuración de Python

3.6.1. Excurso: configurar variables de entorno

3.6.2. Encontrar el ejecutable de Python

3.7. Modo UTF-8

3.8. Lanzador de Python para Windows

3.8.1. Comenzar

3.8.1.1. Desde la línea de comandos

3.8.1.2. Entornos virtuales

3.8.1.3. Desde un script

3.8.1.4. Desde asociaciones de archivos

3.8.2. Líneas shebang

3.8.3. Argumentos en líneas shebang

3.8.4. Personalización

3.8.4.1. Personalización con archivos INI

3.8.4.2. Personalizar las versiones de Python predeterminadas

3.8.5. Diagnóstico

3.9. Encontrar módulos

3.10. Módulos adicionales

3.10.1. PyWin32

3.10.2. cx_Freeze

3.11. Compilar Python en Windows

3.12. Otras plataformas

4. Using Python on a Mac

4.1. Obteniendo e instalando MacPython

4.1.1. Cómo ejecutar un script de Python

4.1.2. Ejecutar scripts con una GUI

4.1.3. Configuración

4.2. El IDE

4.3. Instalación de paquetes adicionales de Python

4.4. Programación de GUI en Mac

4.5. Distribuyendo aplicaciones de Python en la Mac

4.6. Otros recursos

5. Editores e IDEs

1. Línea de comandos y entorno

El intérprete de CPython analiza la línea de comandos y el entorno en busca de varias configuraciones.

CPython implementation detail: Los esquemas de línea de comandos de otras implementaciones pueden diferir. Véase Implementaciones alternativas para obtener más recursos.

1.1. Línea de comando

Al invocar Python, puede especificar cualquiera de estas opciones:

python [-bBdEhiIOqsSuvVWx?] [-c command | -m module-name | script | - ] [args]

El caso de uso más común es, por supuesto, una simple invocación de un script:

python myscript.py

1.1.1. Opciones de interfaz

La interfaz del intérprete es similar a la del shell UNIX, pero proporciona algunos métodos adicionales de invocación:

Cuando se llama con entrada estándar conectada a un dispositivo tty, solicita comandos y los ejecuta hasta que se lea un EOF (un carácter de fin de archivo, puede producirlo con Ctrl-D en UNIX o Ctrl-Z, Enter en Windows).

Cuando se llama con un argumento de nombre de archivo o con un archivo como entrada estándar, lee y ejecuta un script de ese archivo.

Cuando se llama con un argumento de nombre de directorio, lee y ejecuta un script con el nombre adecuado desde ese directorio.

Cuando se llama con -c comando, ejecuta las instrucciones de Python dadas como command. Aquí comando puede contener varias instrucciones separadas por nuevas líneas. ¡El espacio en blanco principal es significativo en las instrucciones de Python!

Cuando se llama con -m module-name, el módulo dado se encuentra en la ruta del módulo Python y se ejecuta como un script.

En el modo no interactivo, toda la entrada se analiza antes de ejecutarse.

Una opción de interfaz termina la lista de opciones consumidas por el intérprete, todos los argumentos consecutivos terminarán en sys.argv – tenga en cuenta que el primer elemento, subíndice cero (sys.argv[0]), es una cadena que refleja el origen del programa.

-c <command>

Ejecute el código de Python en comando. comando puede ser una o más sentencias separadas por nuevas líneas, con espacio en blanco inicial significativo como en el código normal del módulo.

Si se proporciona esta opción, el primer elemento de sys.argv será "-c" y el directorio actual se agregará al inicio de sys.path (permitiendo que los módulos de ese directorio se importen como módulos de nivel superior).

Lanza un auditing event cpython.run_command con el argumento command.

-m <module-name>

Busque sys.path para el módulo con nombre y ejecute su contenido como el módulo __main__.

Dado que el argumento es un nombre módulo, no debe dar una extensión de archivo (.py). El nombre del módulo debe ser un nombre de módulo Python absoluto válido, pero es posible que la implementación no siempre lo aplique (por ejemplo, puede permitirle usar un nombre que incluya un guión).

También se permiten los nombres de paquetes (incluidos los paquetes de espacio de nombres). Cuando se proporciona un nombre de paquete en lugar de un módulo normal, el intérprete ejecutará <pkg>.__main__ como módulo principal. Este comportamiento es deliberadamente similar al manejo de directorios y archivos zip que se pasan al intérprete como argumento del script.

Nota

Esta opción no se puede utilizar con módulos integrados y módulos de extensión escritos en C, ya que no tienen archivos de módulo Python. Sin embargo, todavía se puede utilizar para módulos precompilados, incluso si el archivo de origen original no está disponible.

Si se da esta opción, el primer elemento de sys.argv será la ruta de acceso completa al archivo de módulo (mientras se encuentra el archivo de módulo, el primer elemento se establecerá en "-m"). Al igual que con la opción -c, el directorio actual se agregará al inicio de sys.path.

-I se puede utilizar para ejecutar el script en modo aislado donde sys.path no contiene ni el directorio actual ni el directorio site-packages del usuario. También se omiten todas las variables de entorno PYTHON*.

Muchos módulos de biblioteca estándar contienen código que se invoca en su ejecución como script. Un ejemplo es el módulo timeit:

python -m timeit -s 'setup here' 'benchmarked code here'
python -m timeit -h # for details

Retorna un auditing event cpython.run_module con el argumento nombre-módulo.

Ver también

runpy.run_module()

Funcionalidad equivalente directamente disponible para el código Python

PEP 338 [https://www.python.org/dev/peps/pep-0338] – Ejecución de módulos como scripts

Distinto en la versión 3.1: Proporcione el nombre del paquete para ejecutar un submódulo __main__.

Distinto en la versión 3.4: paquetes de espacio de nombres también son compatibles

-

Leer comandos de entrada estándar (sys.stdin). Si la entrada estándar es un terminal, -i está implícita.

Si se da esta opción, el primer elemento de sys.argv será "-" y el directorio actual se agregará al inicio de sys.path.

Genera un evento auditing event cpython.run_stdin sin argumentos.

<script>

Ejecute el código Python contenido en script, que debe ser una ruta de acceso del sistema de archivos (absoluta o relativa) que haga referencia a un archivo Python, un directorio que contenga un archivo __main__.py o un archivo zip que contenga un archivo __main__.py.

Si se proporciona esta opción, el primer elemento de sys.argv será el nombre del script como se indica en la línea de comandos.

Si el nombre del script hace referencia directamente a un archivo Python, el directorio que contiene ese archivo se agrega al inicio de sys.path, y el archivo se ejecuta como el módulo __main__.

Si el nombre del script hace referencia a un directorio o zipfile, el nombre del script se agrega al inicio de sys.path y el archivo __main__.py en esa ubicación se ejecuta como el módulo __main__.

-I se puede utilizar para ejecutar el script en modo aislado donde sys.path no contiene ni el directorio del script ni el directorio site-packages del usuario. También se omiten todas las variables de entorno PYTHON*.

Lanza un auditing event cpython.run_file con el argumento filename.

Ver también

runpy.run_path()

Funcionalidad equivalente directamente disponible para el código Python

Si no se da ninguna opción de interfaz, -i está implícita, sys.argv[0] es una cadena vacía (") y el directorio actual se agregará al inicio de sys.path. Además, la finalización de tabulación y la edición del historial se habilitan automáticamente, si están disponibles en su plataforma (consulte Configuración de Readline).

Ver también

Invocando al intérprete

Distinto en la versión 3.4: Habilitación automática de la finalización de pestañas y edición del historial.

1.1.2. Opciones genéricas

-?

-h

--help

Imprima una breve descripción de todas las opciones de la línea de comandos.

-V

--version

Imprima el número de versión de Python y salga. Ejemplo de salida podría ser:

Python 3.8.0b2+

Cuando se le dé dos veces, imprima más información sobre la compilación, como:

Python 3.8.0b2+ (3.8:0c076caaa8, Apr 20 2019, 21:55:00)
[GCC 6.2.0 20161005]

Nuevo en la versión 3.6: La opción -VV.

1.1.3. Opciones diversas

-b

Emitir una advertencia al comparar bytes o bytearray con str o bytes con int. Emitir un error cuando la opción se da dos veces (-bb).

Distinto en la versión 3.5: Afecta a las comparaciones de bytes con int.

-B

Si se da, Python no intentará escribir archivos .pyc en la importación de módulos de origen. Véase también PYTHONDONTWRITEBYTECODE.

--check-hash-based-pycs default|always|never

Controle el comportamiento de validación de los archivos .pyc basados en hash. Véase Invalidación del código de bytes en caché. Cuando se establece en default, los archivos de caché de código de bytes basados en hash marcados y desmarcados se validan según su semántica predeterminada. Cuando se establece en always, todos los archivos basados en hash .pyc, ya estén marcados o desmarcados, se validan con su archivo de origen correspondiente. Cuando se establece en never, los archivos basados en hash .pyc no se validan con sus archivos de origen correspondientes.

Esta opción no afecta a la semántica de los archivos .pyc basados en la marca de tiempo.

-d

Active la salida de depuración del analizador (solo para expertos, dependiendo de las opciones de compilación). Véase también PYTHONDEBUG.

-E

Ignore todas las variables de entorno PYTHON*, por ejemplo PYTHONPATH y PYTHONHOME, que podrían establecerse.

-i

Cuando se pasa un script como primer argumento o se utiliza la opción -c, entre en modo interactivo después de ejecutar el script o el comando, incluso cuando sys.stdin no parece ser un terminal. El archivo PYTHONSTARTUP no se lee.

Esto puede ser útil para inspeccionar variables globales o un seguimiento de pila cuando un script genera una excepción. Véase también PYTHONINSPECT.

-I

Ejecute Python en modo aislado. Esto también implica -E y -s. En modo aislado sys.path no contiene ni el directorio del script ni el directorio site-packages del usuario. También se omiten todas las variables de entorno PYTHON*. Se pueden imponer restricciones adicionales para evitar que el usuario inyecte código malicioso.

Nuevo en la versión 3.4.

-O

Quite las instrucciones assert y cualquier código condicionado al valor de __debug__. Aumente el nombre de archivo para los archivos compilados (bytecode) agregando .opt-1 antes de la extensión .pyc (consulte PEP 488 [https://www.python.org/dev/peps/pep-0488]). Véase también PYTHONOPTIMIZE.

Distinto en la versión 3.5: Modifique los nombres de archivo .pyc según PEP 488 [https://www.python.org/dev/peps/pep-0488].

-OO

Haga -O y también deseche las docstrings. Aumente el nombre de archivo para los archivos compilados (bytecode) agregando .opt-2 antes de la extensión .pyc (consulte PEP 488 [https://www.python.org/dev/peps/pep-0488]).

Distinto en la versión 3.5: Modifique los nombres de archivo .pyc según PEP 488 [https://www.python.org/dev/peps/pep-0488].

-q

No muestres los mensajes de copyright y versión incluso en modo interactivo.

Nuevo en la versión 3.2.

-R

Active la aleatorización de hash. Esta opción solo tiene efecto si la variable de entorno PYTHONHASHSEED está establecida en 0, ya que la aleatorización de hash está habilitada de forma predeterminada.

En versiones anteriores de Python, esta opción activa la aleatorización de hash, de modo que los valores __hash__() de los objetos str y bytes son «saladas» con un valor aleatorio impredecible. Aunque permanecen constantes dentro de un proceso de Python individual, no son predecibles entre invocaciones repetidas de Python.

Hash randomization is intended to provide protection against a denial-of-service caused by carefully-chosen inputs that exploit the worst case performance of a dict construction, O(n²) complexity. See http://www.ocert.org/advisories/ocert-2011-003.html for details.

PYTHONHASHSEED le permite establecer un valor fijo para el secreto de inicialización hash.

Distinto en la versión 3.7: La opción ya no se omite.

Nuevo en la versión 3.2.3.

-s

No agregue el user site-packages directory a sys.path.

Ver también

PEP 370 [https://www.python.org/dev/peps/pep-0370] – Directorio de paquetes de sitio por usuario

-S

Deshabilite la importación del módulo site y las manipulaciones dependientes del sitio de sys.path que conlleva. También deshabilite estas manipulaciones si site se importa explícitamente más tarde (llame a site.main() si desea que se activen).

-u

Forzar que las corrientes stdout y stderr no estén en búfer. Esta opción no tiene ningún efecto en la secuencia stdin.

Véase también PYTHONUNBUFFERED.

Distinto en la versión 3.7: La capa de texto de las secuencias stdout y stderr ahora no está en búfer.

-v

Imprima un mensaje cada vez que se inicialice un módulo, mostrando el lugar (nombre de archivo o módulo integrado) desde el que se carga. Cuando se le da dos veces (-vv), imprima un mensaje para cada archivo que se comprueba al buscar un módulo. También proporciona información sobre la limpieza del módulo en la salida. Véase también PYTHONVERBOSE.

-W arg

Control de advertencia. La maquinaria de advertencia de Python por defecto imprime mensajes de advertencia en sys.stderr. Un mensaje de advertencia típico tiene el siguiente formulario:

file:line: category: message

De forma predeterminada, cada advertencia se imprime una vez para cada línea de origen donde se produce. Esta opción controla la frecuencia con la que se imprimen las advertencias.

Se pueden dar varias opciones -W; cuando una advertencia coincide con más de una opción, se realiza la acción para la última opción de coincidencia. No se omiten las opciones -W (aunque se imprime un mensaje de advertencia sobre opciones no válidas cuando se emite la primera advertencia).

Las advertencias también se pueden controlar utilizando la variable de entorno PYTHONWARNINGS y desde un programa Python utilizando el módulo warnings.

La configuración más sencilla aplica una acción determinada incondicionalmente a todas las advertencias emitidas por un proceso (incluso aquellas que de otro modo se ignoran de forma predeterminada):

-Wdefault  # Warn once per call location
-Werror    # Convert to exceptions
-Walways   # Warn every time
-Wmodule   # Warn once per calling module
-Wonce     # Warn once per Python process
-Wignore   # Never warn

Los nombres de acción se pueden abreviar como se desee (por ejemplo, -Wi, -Wd, -Wa, -We) y el intérprete los resolverá con el nombre de acción adecuado.

Consulte El filtro de advertencias y Descripción de los filtros de advertencia para obtener más detalles.

-x

Omita la primera línea de la fuente, permitiendo el uso de formas que no sean de Unix de #!cmd. Esto está destinado a un hackeo específico de DOS solamente.

-X

Reservado para varias opciones específicas de la implementación. CPython define actualmente los siguientes valores posibles:

-X faulthandler para habilitar faulthandler;

-X oldparser: habilita el analizador tradicional LL(1). Vea también PYTHONOLDPARSER y PEP 617 [https://www.python.org/dev/peps/pep-0617].

-X showrefcount para generar el recuento total de referencias y el número de bloques de memoria utilizados cuando finalice el programa o después de cada instrucción en el intérprete interactivo. Esto sólo funciona en compilaciones de depuración.

-X tracemalloc para iniciar el seguimiento de las asignaciones de memoria de Python mediante el módulo tracemalloc. De forma predeterminada, solo el marco más reciente se almacena en un seguimiento de un seguimiento. Utilice -X tracemalloc-NFRAME para iniciar el seguimiento con un límite de rastreo de marcos NFRAME. Consulte el tracemalloc.start() para obtener más información.

-X int_max_str_digits configures the integer string conversion length limitation. See also PYTHONINTMAXSTRDIGITS.

-X importtime para mostrar cuánto tiempo tarda cada importación. Muestra el nombre del módulo, el tiempo acumulado (incluidas las importaciones anidadas) y el tiempo de autoestima (excluyendo las importaciones anidadas). Tenga en cuenta que su salida puede romperse en aplicaciones multiproceso. El uso típico es python3 -X importtime -c 'import asyncio'. Véase también PYTHONPROFILEIMPORTTIME.

-X dev: habilita Python Development Mode, introduciendo comprobaciones de tiempo de ejecución adicionales que son demasiado caras para habilitarse de forma predeterminada.

-X utf8 habilita el modo UTF-8 para las interfaces del sistema operativo, reemplazando el modo predeterminado compatible con la configuración regional. -X utf8-0 desactiva explícitamente el modo UTF-8 (incluso cuando de lo contrario se activaría automáticamente). Consulte PYTHONUTF8 para obtener más detalles.

-X pycache_prefix=PATH permite escribir archivos .pyc en un árbol paralelo enraizado en el directorio dado en lugar de en el árbol de código. Véase también PYTHONPYCACHEPREFIX.

También permite pasar valores arbitrarios y recuperarlos a través del diccionario sys._xoptions.

Distinto en la versión 3.2: Se ha añadido la opción -X.

Nuevo en la versión 3.3: La opción -X faulhandler.

Nuevo en la versión 3.4: Las opciones -X showrefcount y -X tracemalloc.

Nuevo en la versión 3.6: La opción -X showalloccount.

Nuevo en la versión 3.7: Las opciones -X importtime, -X dev y -X utf8.

Nuevo en la versión 3.8: La opción -X pycache_prefix. La opción -X dev ahora registra las excepciones close() en el destructor io.IOBase.

Distinto en la versión 3.9: Usando la opción -X dev, verifique encoding y errors argumentos en las operaciones de codificación y decodificación de cadenas de caracteres.

Se ha eliminado la opción -X showalloccount.

Nuevo en la versión 3.9.14: The -X int_max_str_digits option.

Deprecated since version 3.9, will be removed in version 3.10: La opción -X analizador antiguo.

1.1.4. Opciones que no debe usar

-J

Reservado para su uso por Jython [http://www.jython.org/].

1.2. Variables de entorno

Estas variables de entorno influyen en el comportamiento de Python, se procesan antes de que los modificadores de línea de comandos distintos de -E o -I. Es habitual que los modificadores de línea de comandos anulen variables de entorno donde hay un conflicto.

PYTHONHOME

Cambie la ubicación de las bibliotecas estándar de Python. De forma predeterminada, las bibliotecas se buscan en prefix/lib/pythonversion y exec_prefix/lib/pythonversion, donde prefix y exec_prefix son directorios dependientes de la instalación, ambos predeterminados: file:/usr/local.

Cuando PYTHONHOME se establece en un único directorio, su valor reemplaza tanto al prefix como a exec_prefix. Para especificar valores diferentes para estos, establezca PYTHONHOME en prefix:exec_prefix.

PYTHONPATH

Aumente la ruta de búsqueda predeterminada para los archivos de módulo. El formato es el mismo que el de shell PATH: uno o más nombres de ruta de directorio separados por os.pathsep (por ejemplo, dos puntos en Unix o punto y coma en Windows). Los directorios inexistentes se omiten silenciosamente.

Además de los directorios normales, las entradas individuales PYTHONPATH pueden referirse a archivos zip que contienen módulos Python puros (ya sea en forma de origen o compilado). Los módulos de extensión no se pueden importar desde zipfiles.

La ruta de búsqueda predeterminada depende de la instalación, pero generalmente comienza con prefix/lib/pythonversion (consulte PYTHONHOME arriba). Es always anexado a PYTHONPATH.

Se insertará un directorio adicional en la ruta de búsqueda delante de PYTHONPATH como se describió anteriormente en Opciones de interfaz. La ruta de búsqueda se puede manipular desde un programa Python como la variable sys.path.

PYTHONPLATLIBDIR

Si se establece en una cadena no vacía, anula el valor sys.platlibdir.

Nuevo en la versión 3.9.

PYTHONSTARTUP

Si este es el nombre de un archivo legible, los comandos de Python de ese archivo se ejecutan antes de que el primer mensaje se muestre en modo interactivo. El archivo se ejecuta en el mismo espacio de nombres donde se ejecutan comandos interactivos para que los objetos definidos o importados en él se puedan usar sin calificación en la sesión interactiva. También puede cambiar las solicitudes sys.ps1 y sys.ps2 y el enlace sys.__interactivehook__ en este archivo.

Lanza auditing event cpython.run_startup con el argumento filename.

PYTHONOPTIMIZE

Si se establece en una cadena no vacía, equivale a especificar la opción -O. Si se establece en un entero, es equivalente a especificar -O varias veces.

PYTHONBREAKPOINT

Si se establece, nombra un nombre que se puede llamar mediante la notación de trayecto de puntos. El módulo que contiene el invocable se importará y, a continuación, el invocable se ejecutará por la implementación predeterminada de sys.breakpointhook() que a su vez se llama por incorporado breakpoint(). Si no se establece o se establece en la cadena vacía, es equivalente al valor «pdb.set_trace». Establecer esto en la cadena «0» hace que la implementación predeterminada de sys.breakpointhook() no haga nada más que retornar inmediatamente.

Nuevo en la versión 3.7.

PYTHONDEBUG

Si se establece en una cadena no vacía, equivale a especificar la opción -d. Si se establece en un entero, equivale a especificar -d varias veces.

PYTHONOLDPARSER

Si se establece en una cadena no vacía, habilite el analizador tradicional LL(1).

Vea también la opción -X oldparser y PEP 617 [https://www.python.org/dev/peps/pep-0617].

Deprecated since version 3.9, will be removed in version 3.10.

PYTHONINSPECT

Si se establece en una cadena no vacía, equivale a especificar la opción -i.

Esta variable también se puede modificar mediante código Python mediante os.environ para forzar el modo de inspección en la terminación del programa.

PYTHONUNBUFFERED

Si se establece en una cadena no vacía, equivale a especificar la opción -u.

PYTHONVERBOSE

Si se establece en una cadena no vacía, equivale a especificar la opción -v. Si se establece en un entero, equivale a especificar -v varias veces.

PYTHONCASEOK

If this is set, Python ignores case in import statements. This only works on Windows and macOS.

PYTHONDONTWRITEBYTECODE

Si se establece en una cadena no vacía, Python no intentará escribir archivos .pyc en la importación de módulos de origen. Esto equivale a especificar la opción -B.

PYTHONPYCACHEPREFIX

Si se establece, Python escribirá archivos .pyc en un árbol de directorios reflejado en esta ruta de acceso, en lugar de en directorios __pycache__ dentro del árbol de origen. Esto equivale a especificar la opción -X pycache_prefix=PATH.

Nuevo en la versión 3.8.

PYTHONHASHSEED

Si esta variable no se establece o se establece en random, se utiliza un valor aleatorio para sembrar los hashes de los objetos str y bytes.

Si PYTHONHASHSEED se establece en un valor entero, se utiliza como una semilla fija para generar el hash() de los tipos cubiertos por la aleatorización hash.

Su propósito es permitir el hash repetible, como para las autocomprobaciónes para el propio intérprete, o permitir que un grupo de procesos python comparta valores hash.

El entero debe ser un número decimal en el intervalo [0,4294967295]. Especificar el valor 0 deshabilitará la aleatorización de hash.

Nuevo en la versión 3.2.3.

PYTHONINTMAXSTRDIGITS

If this variable is set to an integer, it is used to configure the interpreter’s global integer string conversion length limitation.

Nuevo en la versión 3.9.14.

PYTHONIOENCODING

Si se establece antes de ejecutar el intérprete, invalida la codificación utilizada para stdin/stdout/stderr, en la sintaxis encodingname:errorhandler. Tanto las partes encodingname como :errorhandler son opcionales y tienen el mismo significado que en str.encode().

Para stderr, se omite la parte :errorhandler; el manejador siempre será 'backslashreplace'.

Distinto en la versión 3.4: La parte encodingname ahora es opcional.

Distinto en la versión 3.6: En Windows, la codificación especificada por esta variable se omite para los búferes de consola interactivos a menos que también se especifique PYTHONLEGACYWINDOWSSTDIO. Los archivos y canalizaciones redirigidos a través de las corrientes estándar no se ven afectados.

PYTHONNOUSERSITE

Si se establece, Python no agregará user site-packages directory a sys.path.

Ver también

PEP 370 [https://www.python.org/dev/peps/pep-0370] – Directorio de paquetes de sitio por usuario

PYTHONUSERBASE

Define el user base directory, que se utiliza para calcular la ruta de acceso de user site-packages directory y Distutils installation paths para python setup.py install --user.

Ver también

PEP 370 [https://www.python.org/dev/peps/pep-0370] – Directorio de paquetes de sitio por usuario

PYTHONEXECUTABLE

If this environment variable is set, sys.argv[0] will be set to its value instead of the value got through the C runtime. Only works on macOS.

PYTHONWARNINGS

Esto es equivalente a la opción -W. Si se establece en una cadena separada por comas, es equivalente a especificar -W varias veces, con filtros más adelante en la lista que tienen prioridad sobre los anteriores de la lista.

La configuración más sencilla aplica una acción determinada incondicionalmente a todas las advertencias emitidas por un proceso (incluso aquellas que de otro modo se ignoran de forma predeterminada):

PYTHONWARNINGS=default  # Warn once per call location
PYTHONWARNINGS=error    # Convert to exceptions
PYTHONWARNINGS=always   # Warn every time
PYTHONWARNINGS=module   # Warn once per calling module
PYTHONWARNINGS=once     # Warn once per Python process
PYTHONWARNINGS=ignore   # Never warn

Consulte El filtro de advertencias y Descripción de los filtros de advertencia para obtener más detalles.

PYTHONFAULTHANDLER

Si esta variable de entorno se establece en una cadena no vacía, se llama a faulthandler.enable() al inicio: instale un controlador para SIGSEGV, SIGFPE, SIGABRT, SIGBUS y SIGILL para volcar el seguimiento de Python. Esto es equivalente a la opción -X faulthandler.

Nuevo en la versión 3.3.

PYTHONTRACEMALLOC

Si esta variable de entorno se establece en una cadena no vacía, comience a trazar las asignaciones de memoria de Python mediante el módulo tracemalloc. El valor de la variable es el número máximo de marcos almacenados en un rastreo de un seguimiento. Por ejemplo, PYTHONTRACEMALLOC=1 almacena sólo el marco más reciente. Consulte el tracemalloc.start() para obtener más información.

Nuevo en la versión 3.4.

PYTHONPROFILEIMPORTTIME

Si esta variable de entorno se establece en una cadena no vacía, Python mostrará cuánto tiempo tarda cada importación. Esto equivale exactamente a establecer -X importtime en la línea de comandos.

Nuevo en la versión 3.7.

PYTHONASYNCIODEBUG

Si esta variable de entorno se establece en una cadena no vacía, habilite el modo debug mode del módulo asyncio.

Nuevo en la versión 3.4.

PYTHONMALLOC

Establezca los asignadores de memoria de Python y/o instale enlaces de depuración.

Establezca la familia de asignadores de memoria utilizados por Python:

default: utilice default memory allocators.

malloc: utilice la función malloc() de la biblioteca C para todos los dominios (PYMEM_DOMAIN_RAW, PYMEM_DOMAIN_MEM, PYMEM_DOMAIN_OBJ).

pymalloc: utilice los dominios pymalloc allocator para PYMEM_DOMAIN_MEM y PYMEM_DOMAIN_OBJ y utilice la función malloc() para el dominio PYMEM_DOMAIN_RAW.

Instale los ganchos del debug:

debug: instale los enlaces de depuración encima de default memory allocators.

malloc_debug: igual que malloc pero también instalar ganchos de depuración.

pymalloc_debug: igual que pymalloc pero también instalar enlaces de depuración.

Consulte default memory allocators y la función PyMem_SetupDebugHooks() (instalar enlaces de depuración en los asignadores de memoria de Python).

Distinto en la versión 3.7: Se ha añadido el asignador "predeterminado".

Nuevo en la versión 3.6.

PYTHONMALLOCSTATS

Si se establece en una cadena no vacía, Python imprimirá estadísticas de pymalloc memory allocator cada vez que se crea una nueva arena de objetos pymalloc y al apagarse.

Esta variable se omite si la variable de entorno PYTHONMALLOC se utiliza para forzar el asignador malloc() de la biblioteca C, o si Python está configurado sin compatibilidad con pymalloc.

Distinto en la versión 3.6: Esta variable ahora también se puede utilizar en Python compilado en modo de versión. Ahora no tiene ningún efecto si se establece en una cadena vacía.

PYTHONLEGACYWINDOWSFSENCODING

Si se establece en una cadena no vacía, el modo de codificación y errores del sistema de archivos predeterminado volverá a sus valores pre-3.6 de mbcs y replace, respectivamente. De lo contrario, se utilizan los nuevos valores predeterminados utf-8 y surrogatepass.

Esto también se puede habilitar en tiempo de ejecución con sys._enablelegacywindowsfsencoding().

Availability: Windows.

Nuevo en la versión 3.6: Consulte PEP 529 [https://www.python.org/dev/peps/pep-0529] para obtener más detalles.

PYTHONLEGACYWINDOWSSTDIO

Si se establece en una cadena no vacía, no utiliza el nuevo lector y escritor de consola. Esto significa que los caracteres Unicode se codificarán de acuerdo con la página de códigos de la consola activa, en lugar de usar utf-8.

Esta variable se omite si se redirigen las secuencias estándar (a archivos o canalizaciones) en lugar de hacer referencia a búferes de consola.

Availability: Windows.

Nuevo en la versión 3.6.

PYTHONCOERCECLOCALE

Si se establece en el valor 0, hace que la aplicación principal de línea de comandos de Python omita la coerción de las configuraciones regionales C y POSIX basadas en ASCII heredadas a una alternativa basada en UTF-8 más capaz.

Si esta variable es no establecida (o se establece en un valor distinto de 0), tampoco se establece la variable de entorno de invalidación local LC_ALL, y la configuración local actual notificada para la categoría LC_CTYPE es la configuración local C predeterminada, o bien la configuración local basada explícitamente en ASCII POSIX, entonces la CLI de Python intentará configurar las siguientes configuraciones locales para la categoría LC_CTYPE en el orden indicado antes de cargar el tiempo de ejecución del intérprete:

C.UTF-8

C.utf8

UTF-8

Si la configuración de una de estas categorías de configuración local se realiza correctamente, la variable de entorno LC_CTYPE también se establecerá en consecuencia en el entorno de proceso actual antes de que se inicialice el tiempo de ejecución de Python. Esto garantiza que, además de ser visto tanto por el propio intérprete como por otros componentes compatibles con la configuración local que se ejecutan en el mismo proceso (como la biblioteca GNU readline), la configuración actualizada también se ve en los subprocesos (independientemente de si esos procesos están ejecutando o no un intérprete de Python), así como en las operaciones que consultan el entorno en lugar de la configuración regional de C actual (como la propia de Python locale.getdefaultlocale()).

La configuración de una de estas configuraciones regionales (ya sea explícitamente o a través de la coerción de configuración regional implícita anterior) habilita automáticamente el surrogateescape error handler para sys.stdin y sys.stdout (sys.stderr continúa utilizando backslashreplace como lo hace en cualquier otra configuración local). Este comportamiento de control de secuencias se puede invalidar mediante PYTHONIOENCODING como de costumbre.

Para fines de depuración, establecer PYTHONCOERCECLOCALE-warn hará que Python emita mensajes de advertencia en stderr si se activa la coerción de configuración regional, o si una configuración regional que would ha activado la coerción sigue activa cuando se inicializa el tiempo de ejecución de Python.

También tenga en cuenta que incluso cuando la coerción de configuración regional está desactivada, o cuando no puede encontrar una configuración regional de destino adecuada, PYTHONUTF8 se activará de forma predeterminada en las configuraciones regionales heredadas basadas en ASCII. Ambas funciones deben estar deshabilitadas para obligar al intérprete a usar ASCII en lugar de UTF-8 para las interfaces del sistema.

Availability: *nix.

Nuevo en la versión 3.7: Consulte PEP 538 [https://www.python.org/dev/peps/pep-0538] para obtener más detalles.

PYTHONDEVMODE

Si esta variable de entorno se establece en una cadena no vacía, habilite Python Development Mode, introduciendo comprobaciones de tiempo de ejecución adicionales que son demasiado caras para habilitarse de forma predeterminada.

Nuevo en la versión 3.7.

PYTHONUTF8

Si se establece en 1, habilita el modo UTF-8 del intérprete, donde UTF-8 se utiliza como codificación de texto para las interfaces del sistema, independientemente de la configuración regional actual.

Esto significa que:

sys.getfilesystemencoding() devuelve 'UTF-8' (se omite la codificación de configuración local).

locale.getpreferredencoding() devuelve 'UTF-8' (se omite la codificación de configuración regional y el parámetro do_setlocale de la función no tiene ningún efecto).

sys.stdin, sys.stdout, y sys.stderr todos usan UTF-8 como su codificación de texto, con el surrogateescape error handler que se habilita para sys.stdin y sys.stdout (sys.stderr continúa utilizando backslashreplace como lo hace en el modo predeterminado de configuración local)

Como consecuencia de los cambios en esas API de nivel inferior, otras API de nivel superior también presentan diferentes comportamientos predeterminados:

Los argumentos de línea de comandos, las variables de entorno y los nombres de archivo se descodifican en texto mediante la codificación UTF-8.

os.fsdecode() y os.fsencode() utilizan la codificación UTF-8.

open(), io.open(), y codecs.open() utilizan la codificación UTF-8 de forma predeterminada. Sin embargo, siguen usando el controlador de errores estricto de forma predeterminada para que intentar abrir un archivo binario en modo de texto sea probable que genere una excepción en lugar de producir datos sin sentido.

Tenga en cuenta que la configuración de secuencia estándar en modo UTF-8 se puede invalidar por PYTHONIOENCODING (igual que pueden estar en el modo predeterminado de configuración local).

Si se establece en 0, el intérprete se ejecuta en su modo predeterminado compatible con la configuración local.

Establecer cualquier otra cadena no vacía produce un error durante la inicialización del intérprete.

Si esta variable de entorno no se establece en absoluto, el intérprete utiliza de forma predeterminada la configuración regional actual, a menos que la configuración regional actual se identifique como una configuración regional basada en ASCII heredada (como se describe para PYTHONCOERCECLOCALE) y la coerción de configuración regional está deshabilitada o se produce un error. En estas configuraciones regionales heredadas, el intérprete habilitará de forma predeterminada el modo UTF-8 a menos que se indique explícitamente que no lo haga.

También disponible como la opción -X utf8.

Nuevo en la versión 3.7: Consulte PEP 540 [https://www.python.org/dev/peps/pep-0540] para obtener más detalles.

1.2.1. Variables de modo de depuración

Establecer estas variables solo tiene un efecto en una compilación de depuración de Python.

PYTHONTHREADDEBUG

Si se establece, Python imprimirá información de depuración de subprocesos.

Necesita configurar Python con la opción de compilación --with-pydebug.

PYTHONDUMPREFS

Si se establece, Python volcará objetos y recuentos de referencias aún vivos después de apagar el intérprete.

Necesita Python configurado con la opción de compilación --with-trace-refs.

2. Uso de Python en plataformas Unix

2.1. Obteniendo e instalando la última versión de Python

2.1.1. En Linux

Python viene preinstalado en la mayoría de distribuciones Linux, y también está disponible como paquete en el resto. Sin embargo, hay determinadas características que puede que quiera usar y no están disponibles en tu paquete de distribución. Puedes compilar fácilmente la última versión de Python de la fuente.

En caso de que Python no venga preinstalado y tampoco se encuentre en los repositorios, puede crear fácilmente paquetes para su propia distribución. Eche un vistazo a los siguientes enlaces:

Ver también

https://www.debian.org/doc/manuals/maint-guide/first.en.html

para usuarios de Debian

https://en.opensuse.org/Portal:Packaging

para los usuarios de OpenSuse

https://docs-old.fedoraproject.org/en-US/Fedora_Draft_Documentation/0.1/html/RPM_Guide/ch-creating-rpms.html

para los usuarios de Fedora

http://www.slackbook.org/html/package-management-making-packages.html

para los usuarios de Slackware

2.1.2. En FreeBSD y OpenBSD

Usuarios FreeBSD, para añadir al paquete use:

pkg install python3

Usuarios OpenBSD, para añadir al paquete use:

pkg_add -r python

pkg_add ftp://ftp.openbsd.org/pub/OpenBSD/4.2/packages/<insert your architecture here>/python-<version>.tgz

Por ejemplo, los usuarios de i386 obtienen la versión 2.5.1 de Python usando:

pkg_add ftp://ftp.openbsd.org/pub/OpenBSD/4.2/packages/i386/python-2.5.1p2.tgz

2.1.3. En OpenSolaris

Puede obtener Python de OpenCSW [https://www.opencsw.org/]. Varias versiones de Python están disponibles y pueden ser instaladas, por ejemplo: pkgutil -i python27.

2.2. Construyendo Python

Si quisiera compilar CPython por sí mismo, lo primero que debería hacer es obtener la fuente [https://www.python.org/downloads/source/]. Puede descargar la fuente de la última versión o simplemente obtener un nuevo clon [https://devguide.python.org/setup/#getting-the-source-code]. Si desea contribuir con parches, necesitará un clon.

El proceso de construcción consta de los comandos habituales:

./configure
make
make install

Las opciones de configuración y las advertencias para plataformas Unix específicas están ampliamente documentadas en el fichero README.rst [https://github.com/python/cpython/tree/3.9/README.rst] del árbol de origen.

Advertencia

make install puede sobreescribir o enmascarar el binario python3. Por lo tanto se recomienda make altinstall en lugar de make install debido a que sólo instala exec_prefix/bin/pythonversion.

2.3. Rutas y archivos relacionados con Python

Estos están sujetos a diferencias según las convenciones de instalación locales; prefix (${prefix}) y exec_prefix (${exec_prefix}) son dependientes de la instalación y deben interpretarse como software GNU; deben ser iguales.

Por ejemplo, en la mayoría de los sistemas Linux, el valor predeterminado para ambos es /usr.

Archivo/directorio

Significado

exec_prefix/bin/python3

Ubicación recomendada del intérprete.

prefix/lib/pythonversion, exec_prefix/lib/pythonversion

Ubicaciones recomendadas de los directorios que contienen los módulos estándar.

prefix/include/pythonversion, exec_prefix/include/pythonversion

Ubicaciones recomendadas de los directorios que contienen los archivos de inclusión necesarios para desarrollar extensiones de Python e incrustar el intérprete.

2.4. Miscelánea

Para usar fácilmente los scripts de Python en Unix, debe hacerlos ejecutables, p. ej. con

$ chmod +x script

y coloque una línea Shebang adecuada en la parte superior del script. Una buena opción es usualmente

#!/usr/bin/env python3

que busca el intérprete de Python en el conjunto PATH. Sin embargo, algunos Unices puede que no tengan el comando env, por lo que es posible que deba codificar /usr/bin/python3 como la ruta intérprete.

Para usar comandos de shell en sus scripts de Python, mire el módulo subprocess.

3. Uso de Python en Windows

Este documento pretende dar una visión general del comportamiento específico de Windows que se debería conocer al usar Python en Microsoft Windows.

A diferencia de la mayoría de sistemas y servicios Unix, Windows no incluye una instalación de Python soportada por el sistema. Para hacer que Python esté disponible, el equipo de CPython ha compilado instaladores de Windows (paquetes MSI) con cada lanzamiento [https://www.python.org/download/releases/] durante muchos años. Estos instaladores están destinados principalmente a agregar una instalación de Python para cada usuario, con el intérprete principal y la biblioteca para ser usados por un solo usuario. El instalador también es capaz de hacer la instalación para todos los usuarios de una única máquina, y un archivo ZIP separado está disponible para distribuciones locales (específicas) para cada aplicación.

Como se especifica en PEP 11 [https://www.python.org/dev/peps/pep-0011], una versión de Python solo admite una plataforma Windows, mientras que Microsoft considera la plataforma con soporte extendido. Esto significa que Python | versión | es compatible con Windows 8.1 y versiones posteriores. Si necesita compatibilidad con Windows 7, instale Python 3.8.

Hay varios instaladores diferentes disponibles para Windows, cada uno con determinados beneficios y desventajas.

El instalador completo contiene todos los componentes y es la mejor opción para desarrolladores que usan Python para cualquier clase de proyecto.

El paquete Microsoft Store es una instalación simple de Python que es adecuada para ejecutar scripts y paquetes, y para usar IDLE u otros entornos de desarrollo. Requiere Windows 10, pero la instalación puede hacerse de forma segura sin corromper otros programas. También proporciona muchos comandos convenientes para lanzar Python y sus herramientas.

El paquete de nuget.org son instalaciones ligeras destinadas a sistemas de integración continua. Puede ser usada para crear paquetes de Python o para ejecutar scripts, pero no es actualizable y no posee herramientas de interfaz de usuario.

El paquete incrustable es un paquete de Python mínimo que es adecuado para incrustar en una aplicación más grande.

3.1. El instalador completo

3.1.1. Pasos para la instalación

Cuatro instaladores de Python 3.9 están disponibles para descargar - dos por cada una de las versiones de 32-bit y 64-bit del intérprete. El instalador web es una pequeña descarga inicial que automáticamente descargará los componentes requeridos cuando sea necesario. El instalador fuera de línea incluye los componentes necesarios para una instalación por defecto y solo requiere de una conexión a internet para características opcionales. Consultar Instalación sin descargas para conocer otras formas de evitar descargas durante la instalación.

Luego de iniciar el instalador, se puede seleccionar una de estas dos opciones:

Si se selecciona «Install Now»:

No necesitarás ser administrador (a menos que se requiera una actualización de sistema para C Runtime Library o se necesite instalar el Lanzador de Python para Windows para todos los usuarios)

Python será instalado en su directorio de usuario

El Lanzador de Python para Windows será instalado de acuerdo con la opción en la parte inferior de la primera página

La biblioteca estándar, conjunto de pruebas, lanzador y pip serán instalados

Si se selecciona, el directorio de instalación se agregará a su PATH

Los accesos directos solo serán visibles para al usuario actual

Si selecciona «Customize installation» podrá elegir qué funciones instalar, el destino de la instalación y otras opciones o acciones posinstalación. Para instalar símbolos de depuración o binarios, necesitará usar esta opción.

Para realizar una instalación para todos los usuarios, deberá seleccionar «Customize installation». En este caso:

Es posible que deba proporcionar credenciales administrativas o aprobación

Python será instalado en el directorio Program Files

El Lanzador de Python para Windows será instalado en el directorio Windows

Se pueden seleccionar características opcionales durante la instalación

La biblioteca estándar puede ser precompilada a bytecode

Si se selecciona, el directorio de instalación será agregado al PATH del sistema

Los accesos directos están disponibles para todos los usuarios

3.1.2. Quitar el límite de MAX_PATH

Windows históricamente ha limitado la longitud de las rutas a 260 caracteres. Esto significaba que rutas de mayor longitud no resolverían y se producirían errores.

En las últimas versiones de Windows, esta limitación se puede ampliar a aproximadamente 32.000 caracteres. Su administrador deberá activar la política de grupo «Habilitar rutas largas de Win32» o establecer LongPathsEnabled en 1 en la clave de registro HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem.

Esto permite que la función open(), el módulo os y la mayoría de las demás funciones de ruta acepten y devuelvan rutas de más de 260 caracteres.

Luego de cambiar la opción anterior, no es necesaria ninguna otra configuración.

Distinto en la versión 3.6: Se habilitó el soporte para rutas largas en Python.

3.1.3. Instalación sin interfaz de usuario

Todas las opciones disponibles desde la interfaz de usuario del instalador también pueden especificarse desde la línea de comandos, lo cual permite que instaladores mediante scripts repliquen una instalación en muchas máquinas sin la interacción del usuario. Estas opciones también pueden ser configuradas sin anular la interfaz de usuario con el fin de cambiar alguno de los valores predeterminados.

To completely hide the installer UI and install Python silently, pass the /quiet option. To skip past the user interaction but still display progress and errors, pass the /passive option. The /uninstall option may be passed to immediately begin removing Python - no confirmation prompt will be displayed.

Todas las otras opciones se especifican con la forma nombre=valor, siendo el valor usualmente 0 para deshabilitar una funcionalidad, 1 para habilitar una funcionalidad, o una ruta. La lista completa de opciones disponibles se muestra a continuación.

Nombre

Descripción

Predeterminado

InstallAllUsers

Realizar una instalación en todo el sistema.

0

TargetDir

El directorio de instalación

Seleccionado de acuerdo a InstallAllUsers

DefaultAllUsersTargetDir

El directorio predeterminado de instalación cuando se instala para todos los usuarios

%ProgramFiles%\Python X.Y o %ProgramFiles(x86)%\Python X.Y

DefaultJustForMeTargetDir

El directorio predeterminado de instalación para instalaciones del usuario actual solamente

%LocalAppData%\Programs\PythonXY o %LocalAppData%\Programs\PythonXY-32 o %LocalAppData%\Programs\PythonXY-64

DefaultCustomTargetDir

El valor predeterminado de directorio de instalación personalizado que se muestra en la interfaz de usuario

(vacío)

AssociateFiles

Crear asociaciones de archivos si el lanzador también es instalado.

1

CompileAll

Compilar todos los archivos .py a .pyc.

0

PrependPath

Agregar directorios de instalación y Scripts a PATH y .PY a PATHEXT

0

Shortcuts

Crear accesos directos para el intérprete, documentación e IDLE si está instalado.

1

Include_doc

Instalar el manual de Python

1

Include_debug

Instalar los binarios de depuración

0

Include_dev

Instalar encabezados y bibliotecas de desarrollo

1

Include_exe

Instalar python.exe y archivos relacionados

1

Include_launcher

Instalar Lanzador de Python para Windows.

1

InstallLauncherAllUsers

Instalar Lanzador de Python para Windows para todos los usuarios.

1

Include_lib

Instalar la biblioteca estándar y los módulos de extensión

1

Include_pip

Instalar los paquetes pip y setuptools

1

Include_symbols

Instalar los símbolos de depuración (*.pdb)

0

Include_tcltk

Instalar IDLE y soporte para Tcl/Tk

1

Include_test

Instalar el conjunto de pruebas de la biblioteca estándar

1

Include_tools

Instalar scripts de utilidades

1

LauncherOnly

Instalar solo el lanzador. Esto anulará la mayoría de las otras opciones.

0

SimpleInstall

Deshabilitar muchas de las partes de la interfaz de usuario

0

SimpleInstallDescription

Un mensaje personalizado para mostrar cuando se use la versión simplificada de la interfaz de usuario de instalación.

(vacío)

Por ejemplo, para realizar de forma silenciosa una instalación predeterminada de Python para todo el sistema, se puede usar el siguiente comando (desde un símbolo del sistema con privilegios elevados):

python-3.9.0.exe /quiet InstallAllUsers=1 PrependPath=1 Include_test=0

Para permitir que los usuarios instalen fácilmente una copia personal de Python sin el conjunto de pruebas, se puede proporcionar un acceso directo con el siguiente comando. Esto mostrará una página inicial simplificada y no permitirá la personalización:

python-3.9.0.exe InstallAllUsers=0 Include_launcher=0 Include_test=0
    SimpleInstall=1 SimpleInstallDescription="Just for me, no test suite."

(Tener en cuenta que al omitir el lanzador también se omiten las asociaciones de archivos y solo es recomendable hacerlo para instalaciones por usuario cuando ya hay una instalación en todo el sistema que incluye el lanzador.)

Las opciones enumeradas anteriormente también se pueden proporcionar en un archivo de nombre unattend.xml junto al ejecutable. Este archivo especifica una lista de opciones y valores. Cuando un valor se proporciona como un atributo, se convertirá a número si es posible. Los valores proporcionados como elementos de texto siempre se dejan como cadenas. Este archivo de ejemplo configura las mismas opciones que el ejemplo anterior:

<Options>
    <Option Name="InstallAllUsers" Value="no" />
    <Option Name="Include_launcher" Value="0" />
    <Option Name="Include_test" Value="no" />
    <Option Name="SimpleInstall" Value="yes" />
    <Option Name="SimpleInstallDescription">Just for me, no test suite</Option>
</Options>

3.1.4. Instalación sin descargas

Como algunas características de Python no se incluyen con la descarga inicial del instalador, la selección de estas características podría requerir de una conexión a internet. Para evitar esta necesidad, todos los posibles componentes pueden ser descargados a pedido para crear una estructura que no necesitará una conexión a internet, independientemente de las características que se seleccionen. Tener en cuenta que esta descarga puede ser más grande de lo necesario, pero si se va a realizar un gran número de instalaciones es muy útil tener una copia en la caché local.

Ejecute el siguiente comando desde el símbolo del sistema para descargar todos los archivos necesarios posibles. Recuerde sustituir python-3.9.0.exe por el nombre real de su instalador y crear diseños en sus propios directorios para evitar colisiones entre archivos con el mismo nombre.

python-3.9.0.exe /layout [optional target directory]

También se puede especificar la opción /quiet para no mostrar el progreso.

3.1.5. Modificar una instalación

Una vez que Python ha sido instalado, se puede agregar o quitar funciones a través de la herramienta Programas y características que es parte de Windows. Seleccionar la entrada Python y elegir «Desinstalar/Cambiar» para abrir el instalador en modo mantenimiento.

«Cambiar» permite agregar o eliminar características modificando las casillas de verificación - aquellas casillas que no se cambien no agregarán ni quitarán nada. Algunas opciones no pueden cambiarse de esta forma, como el directorio de instalación; para modificarlas es necesario eliminar y reinstalar Python completamente.

«Reparar» verificará todos los archivos que deben instalarse con la configuración actual y reemplazará los que se hayan eliminado o modificado.

«Desinstalar» eliminará Python completamente, a excepción del Lanzador de Python para Windows, el cual posee su propia entrada en Programas y características.

3.2. El paquete Microsoft Store

Nuevo en la versión 3.7.2.

El paquete de Microsoft Store es un intérprete de Python fácilmente instalable destinado principalmente al uso interactivo, por ejemplo, por estudiantes.

Para instalar el paquete, asegúrate de tener las últimas actualizaciones de Windows 10 y busca «Python 3.9» en Microsoft Store. Comprueba que la aplicación que seleccionas es una publicación de la Python Software Foundation y procede a instalarla.

Advertencia

Python siempre estará disponible de forma gratuita en Microsoft Store. Si se te solicita que pagues por él, entonces el paquete seleccionado no es el correcto.

Luego de la instalación, Python puede iniciarse a través del menú de Inicio. Como alternativa, también estará disponible desde cualquier símbolo del sistema o sesión de PowerShell al escribir python. Además, pip e IDLE pueden ser usados escribiendo pip o idle. IDLE también puede ser encontrado en el Inicio.

Los tres comandos también están disponibles con el número de versión como sufijo, por ejemplo, como python3.exe y python3.x.exe así como también python.exe (donde 3.x es la versión específica que se quiera iniciar, como 3.9). Abrir «Administrar alias de ejecución de aplicaciones» a través del menú de Inicio para seleccionar cuál versión de Python se asocia con cada comando. Se recomienda asegurarse de que pip e idle sean consistentes con la versión de python que esté seleccionada.

Los entornos virtuales se pueden crear con python -m venv y se activan y usan normalmente.

Si ha instalado otra versión de Python que se haya agregado a la variable``PATH``, estará disponible como python.exe en lugar de la de Microsoft Store. Para acceder a la nueva instalación, use python3.exe o python3.x.exe.

El lanzador py.exe detectará esta instalación de Python, pero priorizará instalaciones realizadas con el instalador tradicional.

Para eliminar Python, abra Configuración y utilice Aplicaciones y características, o encuentre Python en el Inicio y mediante click derecho seleccione Desinstalar. La desinstalación eliminará todos los paquetes instalados directamente en esta instalación de Python, pero no eliminará ningún entorno virtual

3.2.1. Problemas conocidos

Debido a restricciones en las aplicaciones de Microsoft Store, los scripts de Python podrían no tener acceso completo de escritura en ubicaciones compartidas como TEMP o el registro. En su lugar, se escribirá en una copia privada. Si sus scripts deben modificar las ubicaciones compartidas, necesitará instalar el instalador completo.

Para obtener más detalles sobre la base técnica de estas limitaciones, consulte la documentación de Microsoft sobre aplicaciones empaquetadas de plena confianza, actualmente disponible en docs.microsoft.com/en-us/windows/msix/desktop/desktop-to-uwp-behind-the-scenes [https://docs.microsoft.com/en-us/windows/msix/desktop/desktop-to-uwp-behind-the-scenes]

3.3. El paquete de nuget.org

Nuevo en la versión 3.5.2.

El paquete de nuget.org es un entorno Python de tamaño reducido destinado a usarse en sistemas de integración continua y compilación que no posean una instalación de Python a nivel de sistema. Si bien nuget es «el administrador de paquetes para .NET», también funciona perfectamente para paquetes que contienen herramientas de tiempo de compilación.

Visite nuget.org [https://www.nuget.org/] para obtener la información más actualizada sobre cómo usar nuget. Lo que sigue es un resumen que es suficiente para desarrolladores Python.

La herramienta de línea de comandos nuget.exe puede ser descargada directamente desde https://aka.ms/nugetclidl, por ejemplo usando curl o PowerShell. Con esta herramienta, la última versión de Python para máquinas de 64 o 32 bit se instala con:

nuget.exe install python -ExcludeVersion -OutputDirectory .
nuget.exe install pythonx86 -ExcludeVersion -OutputDirectory .

To select a particular version, add a -Version 3.x.y. The output directory may be changed from ., and the package will be installed into a subdirectory. By default, the subdirectory is named the same as the package, and without the -ExcludeVersion option this name will include the specific version installed. Inside the subdirectory is a tools directory that contains the Python installation:

# Without -ExcludeVersion
> .\python.3.5.2\tools\python.exe -V
Python 3.5.2

# With -ExcludeVersion
> .\python\tools\python.exe -V
Python 3.5.2

En general, los paquetes nuget no son actualizables, y versiones más nuevas deben ser instaladas en paralelo y referenciadas usando la ruta completa. Otra opción es borrar el directorio del paquete de forma manual e instalarlo de nuevo. Muchos sistemas de CI harán esto automáticamente si no mantienen archivos entre compilaciones.

Junto al directorio tools está el directorio build\native. Este contiene un archivo de propiedades MSBuild Python.props que puede ser usado en un proyecto C++ para referenciar la instalación de Python. Al incluir las configuraciones, automáticamente se usarán los encabezados y se importarán las bibliotecas en la compilación.

Las páginas de información del paquete en nuget.org son www.nuget.org/packages/python [https://www.nuget.org/packages/python] para la versión de 64 bit y www.nuget.org/packages/pythonx86 [https://www.nuget.org/packages/pythonx86] para la versión de 32 bit.

3.4. El paquete incrustable

Nuevo en la versión 3.5.

La distribución incrustable consiste en un archivo ZIP que contiene un mínimo entorno de Python. Está destinado a ser usado como parte de otra aplicación, en lugar de ser accedido directamente por los usuarios finales.

Al ser extraída, la distribución incrustable está (casi) completamente aislada del sistema del usuario, incluyendo variables de entorno, configuraciones del registro del sistema y paquetes instalados. La biblioteca estándar se incluye como archivos .pyc precompilados y optimizados dentro de un ZIP, y python3.dll, python37.dll, python.exe y pythonw.exe están todos proporcionados. Tcl/tk (incluidos sus dependientes, como Idle), pip y la documentación de Python no están incluidos.

Nota

The embedded distribution does not include the Microsoft C Runtime [https://docs.microsoft.com/en-US/cpp/windows/latest-supported-vc-redist#visual-studio-2015-2017-2019-and-2022] and it is the responsibility of the application installer to provide this. The runtime may have already been installed on a user’s system previously or automatically via Windows Update, and can be detected by finding ucrtbase.dll in the system directory.

Los paquetes de terceros deben ser instalados por el instalador de la aplicación junto a la distribución incrustada. El uso de pip para administrar dependencias como en una instalación de Python regular no es soportado por esta distribución, aunque con cierto cuidado es posible incluir y usar pip para automatizar las actualizaciones. En general, los paquetes de terceros deben ser tratados como parte de la aplicación («vendoring») para que el desarrollador pueda asegurar la compatibilidad con las nuevas versiones antes de proporcionar actualizaciones a los usuarios.

Los dos casos de uso recomendados para esta distribución se describen a continuación.

3.4.1. Aplicación Python

Una aplicación escrita en Python no necesariamente requiere que los usuarios sean conscientes de ese hecho. La distribución incrustada puede ser usada en este caso para incluir una versión privada de Python en un paquete de instalación. Dependiendo de lo transparente que deba ser (o por el contrario, de lo profesional que deba parecer), hay dos opciones.

El uso de un ejecutable especializado como lanzador requiere algo de código, pero proporciona la experiencia más transparente para los usuarios. Con un lanzador personalizado, no hay indicadores obvios de que el programa se ejecuta en Python: los íconos pueden ser personalizados, se puede especificar información de la compañía y de la versión, y las asociaciones de archivos se comportan correctamente. En la mayoría de los casos, un lanzador personalizado debería simplemente poder invocar Py_Main utilizando una línea de comandos codificada.

El enfoque más simple es proporcionar un archivo por lotes o un acceso directo generado que directamente invoque python.exe o pythonw.exe con los argumentos de línea de comandos requeridos. En este caso, la aplicación aparecerá como Python y no con su nombre real, y los usuarios podrían tener problemas para distinguirla de otros procesos Python en ejecución o asociaciones de archivos.

Con este último enfoque, los paquetes deben instalarse como directorios junto al ejecutable de Python para asegurar su disponibilidad en la ruta. Con el lanzador especializado, los paquetes pueden encontrarse en otras ubicaciones ya que hay oportunidad de especificar la ruta de búsqueda antes de iniciar la aplicación.

3.4.2. Incrustar Python

Las aplicaciones escritas en código nativo frecuentemente requieren algún tipo de lenguaje de scripting, y la distribución de Python incrustada puede ser utilizada con ese propósito. En general, la mayoría de la aplicación utiliza código nativo, y alguna parte invocará python.exe o usará python3.dll directamente. Para cualquiera de estos casos, la extracción de la distribución incrustable a un subdirectorio de la instalación de la aplicación es suficiente para proporcionar un intérprete de Python invocable.

Al igual que con el uso de la aplicación, los paquetes pueden ser instalados en cualquier ubicación, ya que existe la posibilidad de especificar rutas de búsqueda antes de inicializar el intérprete. Más allá de esto, no existen diferencias fundamentales entre el uso de la distribución incrustada y una instalación normal.

3.5. Distribuciones alternativas

Además de la distribución estándar de CPython, hay paquetes modificados que incluyen funcionalidad adicional. La siguiente es una lista de versiones populares y sus características clave:

ActivePython [https://www.activestate.com/activepython/]

Instalador compatible con múltiples plataformas, documentación, PyWin32

Anaconda [https://www.anaconda.com/download/]

Módulos científicos populares (como numpy, scipy y pandas) y el gestor de paquetes conda.

Canopy [https://www.enthought.com/product/canopy/]

Un «entorno de análisis integral de Python» con editores y otras herramientas de desarrollo.

WinPython [https://winpython.github.io/]

Distribución específica para Windows con paquetes científicos precompilados y herramientas para construir paquetes.

Tenga en cuenta que estos paquetes pueden no incluir la última versión de Python u otras bibliotecas, y no son mantenidos ni respaldados por el equipo central de Python.

3.6. Configuración de Python

Para ejecutar Python convenientemente desde el símbolo del sistema, puede considerar cambiar algunas variables de entorno predeterminadas de Windows. Si bien el instalador proporciona una opción para configurar las variables PATH y PATHEXT, esto solo es confiable para una única instalación en todo el sistema. Si utiliza varias versiones de Python con regularidad, considere usar el Lanzador de Python para Windows.

3.6.1. Excurso: configurar variables de entorno

Windows permite configurar las variables de entorno de forma permanente a nivel de usuario y a nivel de sistema, o temporalmente en el símbolo del sistema.

Para configurar una variable de entorno temporal, abra el símbolo del sistema y utilice el comando set:

C:\>set PATH=C:\Program Files\Python 3.9;%PATH%
C:\>set PYTHONPATH=%PYTHONPATH%;C:\My_python_lib
C:\>python

Estos cambios serán aplicados a cualquier comando que de aquí en más se ejecute en esa consola, y serán heredados por cualquier aplicación iniciada desde esa consola.

Si se incluye el nombre de la variable entre signos de porcentaje, esta se expande al valor existente, permitiendo agregar un nuevo valor tanto al principio como al final. Modificar PATH agregando el directorio que contiene python.exe al comienzo es una forma común de asegurar que se ejecuta la versión correcta de Python.

Para modificar permanentemente las variables de entorno predeterminadas, haga click en Inicio y busque “editar las variables de entorno”, o abra Sistema, Configuración avanzada del sistema y haga click en el botón Variables de entorno. En este diálogo, se pueden agregar o modificar variables del usuario o del sistema. Para cambiar variables del sistema, se necesita acceso no restringido al equipo (por ej. con credenciales de administrador).

Nota

Windows concatenará las variables de usuario luego de las variables del sistema, lo cual puede causar resultados inesperados cuando se modifica PATH.

The PYTHONPATH variable is used by all versions of Python, so you should not permanently configure it unless the listed paths only include code that is compatible with all of your installed Python versions.

Ver también

https://docs.microsoft.com/en-us/windows/win32/procthread/environment-variables

Overview of environment variables on Windows

https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1

The set command, for temporarily modifying environment variables

https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/setx

The setx command, for permanently modifying environment variables

3.6.2. Encontrar el ejecutable de Python

Distinto en la versión 3.5.

Además de utilizar la entrada para el intérprete de Python creada automáticamente en el menú de Inicio, es posible que desee iniciar Python desde el símbolo del sistema. El instalador posee una opción para realizar esa configuración.

En la primera página del instalador, la opción llamada «Add Python to PATH» puede ser seleccionada para que el instalador agregue la ubicación de instalación a PATH. La ubicación del directorio Scripts\ también es agregada. Esto permite escribir python para iniciar el intérprete, y pip para el instalador de paquetes. De esta manera los scripts también pueden ser ejecutados con opciones de línea de comandos, consulte la documentación de Línea de comando.

Si no se activa esta opción durante la instalación, en cualquier momento se puede ejecutar nuevamente el instalador, seleccionar Modify, y activarla. Otra alternativa es modificar PATH manualmente siguiendo las instrucciones en Excurso: configurar variables de entorno. Se necesita configurar la variable de entorno PATH para que incluya el directorio de instalación de Python, separándolo con punto y coma (;) de las otras entradas. Una variable de ejemplo pude verse así (suponiendo que las dos primeras entradas ya existían):

C:\WINDOWS\system32;C:\WINDOWS;C:\Program Files\Python 3.9

3.7. Modo UTF-8

Nuevo en la versión 3.7.

Windows aún utiliza codificación heredada para la codificación del sistema (la página de códigos ANSI). Python la utiliza para la codificación por defecto de archivos de texto (por ej. locale.getpreferredencoding()).

Esto puede causar problemas porque UTF-8 es ampliamente utilizado en internet y en la mayoría de los sistemas Unix, incluido WSL (subsistema de Windows para Linux).

Se puede utilizar el modo UTF-8 para cambiar la codificación predeterminada a UTF-8. El modo UTF-8 se puede activar mediante la opción de línea de comandos -X utf-8, o con la variable de entorno PYTHONUTF8=1. Consulte PYTHONUTF8 para activar el modo UTF-8, y Excurso: configurar variables de entorno para saber cómo modificar las variables de entorno.

Cuando el modo UTF-8 está activado:

locale.getpreferredencoding() retorna 'UTF-8' en lugar de la codificación del sistema. Esta función es utilizada como la codificación de texto predeterminada en muchos lugares, incluidos open(), Popen, Path.read_text(), etc.

sys.stdin, sys.stdout, y sys.stderr utilizan la codificación de texto UTF-8.

Siempre se puede utilizar la codificación del sistema mediante el códec «mbcs».

Tenga en cuenta que agregar PYTHONUTF8=1 a las variables de entorno predeterminadas afectará a todas las aplicaciones de Python 3.7+ en el sistema. Si utiliza alguna aplicación de Python 3.7+ que depende de la codificación heredada del sistema, se recomienda que se configure la variable de entorno solo temporalmente o se use la opción de línea de comandos -X utf8.

Nota

Aún con el modo UTF-8 desactivado, Python utiliza UTF-8 de forma predeterminada en Windows para:

E/S de consola, incluida la E/S estándar (consultar PEP 528 [https://www.python.org/dev/peps/pep-0528] para más detalles).

Codificación del sistema de archivos (ver PEP 529 [https://www.python.org/dev/peps/pep-0529] para más detalles).

3.8. Lanzador de Python para Windows

Nuevo en la versión 3.3.

El lanzador de Python para Windows es una utilidad que ayuda en la ubicación y ejecución de diferentes versiones de Python. Este permite que los scripts (o la línea de comandos) indiquen preferencia por una versión específica de Python, y ubicará y ejecutará esa versión.

A diferencia de la variable PATH, el lanzador seleccionará correctamente la versión más apropiada de Python. Priorizará instalaciones del usuario por sobre instalaciones de todo el sistema, y ordenará por versión del lenguaje en lugar de utilizar la más recientemente instalada.

El lanzador se especificó originalmente en PEP 397 [https://www.python.org/dev/peps/pep-0397].

3.8.1. Comenzar

3.8.1.1. Desde la línea de comandos

Distinto en la versión 3.6.

System-wide installations of Python 3.3 and later will put the launcher on your PATH. The launcher is compatible with all available versions of Python, so it does not matter which version is installed. To check that the launcher is available, execute the following command in Command Prompt:

py

Debería suceder que se inicia la última versión de Python instalada - se puede cerrar normalmente, y todo argumento adicional especificado por línea de comandos será enviado directamente a Python.

If you have multiple versions of Python installed (e.g., 3.7 and 3.9) you will have noticed that Python 3.9 was started - to launch Python 3.7, try the command:

py -3.7

If you want the latest version of Python 2 you have installed, try the command:

py -2

You should find the latest version of Python 3.x starts.

If you see the following error, you do not have the launcher installed:

'py' is not recognized as an internal or external command,
operable program or batch file.

Las instalaciones por usuario de Python no agregan la ubicación del lanzador a PATH a menos que la opción haya sido seleccionada durante la instalación.

The command:

py --list

displays the currently installed version(s) of Python.

3.8.1.2. Entornos virtuales

Nuevo en la versión 3.5.

Si el lanzador es ejecutado sin explícita especificación de la versión de Python, y un entorno virtual se encuentra activo (creado con el módulo venv de la biblioteca estándar o con la herramienta externa virtualenv), el lanzador ejecutará el intérprete del entorno virtual en lugar del global. Para ejecutar el intérprete global, desactive el entorno virtual o especifique explícitamente la versión global de Python.

3.8.1.3. Desde un script

Vamos a crear un script de Python para una prueba - cree un archivo llamado hello.py con el siguiente contenido

#! python
import sys
sys.stdout.write("hello from Python %s\n" % (sys.version,))

From the directory in which hello.py lives, execute the command:

py hello.py

Debería notar que se imprime el número de versión de la última instalación de Python 2.x. Ahora pruebe cambiando la primera línea por:

#! python3

Re-executing the command should now print the latest Python 3.x information. As with the above command-line examples, you can specify a more explicit version qualifier. Assuming you have Python 3.7 installed, try changing the first line to #! python3.7 and you should find the 3.9 version information printed.

Tenga en cuenta que a diferencia del uso interactivo, el comando «python» (a secas) utilizará la última versión de Python 2.x que esté instalada. Esto es así por compatibilidad con versiones anteriores y por compatibilidad con Unix, donde el comando python usualmente refiere a Python 2.

3.8.1.4. Desde asociaciones de archivos

El lanzador debería haber sido asociado con archivos de Python (por ej. archivos .py, .pyw y .pyc) cuando fue instalado. Esto significa que cuando se haga doble click sobre alguno de estos archivos desde el explorador de Windows se utilizará el lanzador, por lo que se pueden utilizar las mismas funciones descritas anteriormente para que el script especifique la versión que debería usarse.

El beneficio clave de esto es que un único lanzador puede soportar múltiples versiones de Python al mismo tiempo dependiendo del contenido de la primera línea.

3.8.2. Líneas shebang

Si la primera línea de un script comienza con #!, esta se denomina línea «shebang». Linux y otros sistemas operativos tipo Unix soportan de forma nativa este tipo de líneas y son comúnmente utilizadas en dichos sistemas para indicar cómo debería ser ejecutado un script. Este lanzador permite que la misma funcionalidad pueda ser utilizada con scripts de Python en Windows, y los ejemplos anteriores demuestran su uso.

Para permitir que las líneas shebang de scripts de Python sean trasladables entre Unix y Windows, este lanzador soporta varios comandos “virtuales” para especificar qué intérprete utilizar. Los comandos virtuales soportados son:

/usr/bin/env python

/usr/bin/python

/usr/local/bin/python

python

Por ejemplo, si la primera línea del script comienza con

#! /usr/bin/python

La versión de Python predeterminada será ubicada y utilizada. Como muchos scripts de Python escritos para funcionar en Unix tienen esta línea, debería suceder que estos scripts pueden ser utilizados por el lanzador sin modificaciones. Si está escribiendo un nuevo script en Windows que espera que sea útil en Unix, debería utilizar una de las líneas shebang que comienza con /usr.

Any of the above virtual commands can be suffixed with an explicit version (either just the major version, or the major and minor version). Furthermore the 32-bit version can be requested by adding «-32» after the minor version. I.e. /usr/bin/python3.7-32 will request usage of the 32-bit python 3.7.

Nuevo en la versión 3.7: Desde la versión 3.7 del lanzador de Python es posible solicitar la versión de 64 bit con el sufijo «-64». Además es posible especificar una versión mayor y la arquitectura sin la versión menor (por ej. /usr/bin/python3-64).

La forma /usr/bin/env de la línea shebang tiene un significado especial más. Antes de buscar intérpretes de Python instalados, esta forma buscará el ejecutable de Python en PATH. Esto se corresponde con el comportamiento en Unix del programa env, el cual realiza una búsqueda en PATH.

3.8.3. Argumentos en líneas shebang

Las líneas shebang también pueden especificar opciones adicionales para que sean pasadas al intérprete de Python. Por ej. si se tiene esta línea shebang:

#! /usr/bin/python -v

Entonces Python se iniciará con la opción -v

3.8.4. Personalización

3.8.4.1. Personalización con archivos INI

El lanzador buscará dos archivos .ini - py.ini en el directorio de «datos de aplicación» del usuario actual (esto es el directorio retornado por el llamado a la función de Windows SHGetFolderPath con CSIDL_LOCAL_APPDATA) y py.ini en el directorio del lanzador. Los mismos archivos .ini son usados por la versión “consola” del lanzador (py.exe) y por la versión “ventana” (pyw.exe).

La personalización especificada en el «directorio de aplicación» tendrá precedencia por sobre la que esté junto al ejecutable, por lo que un usuario, que podría no tener acceso de escritura al archivo .ini que está junto al lanzador, puede sobrescribir comandos en ese archivo .ini global.

3.8.4.2. Personalizar las versiones de Python predeterminadas

En algunos casos, un calificador de versión puede ser incluido en un comando para dictar qué versión de Python será utilizada por dicho comando. Un calificador de versión comienza con el número mayor de la versión y pude ser seguido opcionalmente por un punto (“.”) y el número menor de la versión. Además es posible especificar si se solicita una implementación de 32 o 64 bit agregando «-32» o «-64».

Por ejemplo, una línea shebang como #!python no posee calificador de versión, mientras que #!python3 sí tiene un calificador de versión el cual especifica solo el número mayor de la versión.

Si no se encuentra un calificador de versión en el comando, la variable de entorno PY_PYTHON puede configurarse para especificar un calificador de versión predeterminado. Si esta no está configurada, por defecto es «3». La variable puede especificar cualquier valor que pueda ser pasado por línea de comandos, como «3», «3.7», «3.7-32» o «3.7-64». (Tener en cuenta que la opción «-64» solo está disponible con el lanzador incluido con Python 3.7 o versiones posteriores.)

Si no se encuentra ningún calificador de versión menor, la variable de entorno PY_PYTHON{major} (donde {major} es el actual calificador de versión mayor según lo determinado antes) puede ser configurada para especificar la versión completa. Si dicha opción no se encuentra, el lanzador enumerará las versiones de Python instaladas y utilizará la última versión menor encontrada para la versión mayor, la cual es probable, aunque no se garantiza, que sea la versión más recientemente instalada de esa familia.

En un Windows de 64 bit con ambas implementaciones de 32 y 64 bit de la misma versión (mayor.menor) de Python instaladas, la versión de 64 bit siempre tendrá precedencia. Esto se cumple para ambas implementaciones de 32 y 64 bit del lanzador - un lanzador de 32 bit priorizará ejecutar una instalación de Python de 64 bit de la versión especificada si está disponible. Esto es así para que el comportamiento del lanzador pueda ser predecible sabiendo solamente qué versiones están instaladas en la PC y sin importar el orden en el cual fueron instaladas (esto es, sin saber si una versión de Python de 32 o 64 bit y su correspondiente lanzador fue la última instalada). Como se especificó antes, el sufijo «-32» o «-64» puede ser utilizado en el especificador de versión para cambiar este comportamiento.

Ejemplos:

Si no se configura ninguna opción relevante, los comandos python y python2 utilizarán la última versión de Python 2.x instalada y el comando python3 utilizará el último Python 3.x instalado.

The command python3.7 will not consult any options at all as the versions are fully specified.

Si PY_PYTHON=3, los comandos python y python3 utilizarán ambos la última versión instalada de Python 3.

If PY_PYTHON=3.7-32, the command python will use the 32-bit implementation of 3.7 whereas the command python3 will use the latest installed Python (PY_PYTHON was not considered at all as a major version was specified.)

If PY_PYTHON=3 and PY_PYTHON3=3.7, the commands python and python3 will both use specifically 3.7

Además de las variables de entorno, las mismas configuraciones pueden realizarse desde el archivo .INI utilizado por el lanzador. La sección en el archivo INI se llama [defaults] y el nombre de cada clave será igual al de la variable de entorno pero sin el prefijo PY_ (tenga en cuenta que los nombres de clave en el archivo INI son indiferentes a mayúsculas y minúsculas). El contenido de las variables de entorno sobrescribirá los valores especificados en el archivo INI.

Por ejemplo:

Setting PY_PYTHON=3.7 is equivalent to the INI file containing:

[defaults]
python=3.7

Setting PY_PYTHON=3 and PY_PYTHON3=3.7 is equivalent to the INI file containing:

[defaults]
python=3
python3=3.7

3.8.5. Diagnóstico

Si se configura la variable de entorno PYLAUNCH_DEBUG (con cualquier valor), el lanzador imprimirá información de diagnóstico a stderr (en la consola). Aunque esta información es a la vez detallada y concisa, debería permitirle ver qué versiones de Python fueron encontradas, por qué se eligió una versión particular y la línea de comandos exacta que fue utilizada para ejecutar el Python escogido.

3.9. Encontrar módulos

Python generalmente almacena su biblioteca (y por lo tanto el directorio site-packages) en el directorio de instalación. Por lo tanto si Python fue instalado en C:\Python\, la biblioteca predeterminada residirá en C:\Python\Lib\ y los módulos de terceros deberían almacenarse en C:\Python\Lib\site-packages\.

Para sobrescribir sys.path completamente, crear un archivo ._pth con el mismo nombre que la DLL (python37._pth) o el ejecutable (python._pth) y especificar una línea por cada ruta a agregar a sys.path. El archivo basado en el nombre de la DLL tiene precedencia sobre el basado en el ejecutable, lo que permite restringir las rutas para cualquier programa que cargue el tiempo de ejecución si se desea.

Cuando el archivo existe, se ignoran todas las variables de entorno y del registro, se activa el modo aislado, y no se importa site a menos que una línea en el archivo especifique import site. Rutas en blanco y líneas que comiencen con # son ignoradas. Cada ruta puede ser absoluta o relativa a la ubicación del archivo. No se permiten declaraciones de importación más que la de site, y no se puede especificar código arbitrario.

Tenga en cuenta que los archivos .pth (sin guion bajo al inicio) serán procesados normalmente por el módulo site cuando import site haya sido especificado.

Cuando no se encuentre ningún archivo ._pth, así es como sys.path es completado en Windows:

Se agrega una entrada vacía al comienzo, que corresponde al directorio actual.

Si existe la variable de entorno PYTHONPATH, de acuerdo a lo descrito en Variables de entorno, sus entradas se agregan a continuación. Tenga en cuenta que en Windows, las rutas en esta variable deben estar separadas por punto y coma (;), para distinguirlas de los dos puntos utilizados en los identificadores de disco (C:\, etc.).

Se pueden agregar al registro «rutas de aplicación» adicionales como subclaves de \SOFTWARE\Python\PythonCore{version}\PythonPath bajo los subárboles HKEY_CURRENT_USER y HKEY_LOCAL_MACHINE. Las subclaves que contienen un valor por defecto compuesto por cadenas de ruta separadas por punto y coma causan que cada una de esas rutas sea agregada a sys.path. (Tenga en cuenta que todos los instaladores conocidos solo utilizan HKLM, por lo que HKCU comúnmente se encuentra vacío.)

Si se configura la variable de entorno PYTHONHOME, es asumida como el «Python Home» (el directorio de origen de Python). De lo contrario, la ruta del ejecutable principal de Python es utilizada para ubicar un «archivo de referencia» (ya sea Lib\os.py o pythonXY.zip) para deducir el «Python Home». Si el directorio de origen de Python es encontrado, los subdirectorios relevantes que se agregan a sys.path (Lib, plat-win, etc.) se basan en ese directorio. Por el contrario, la ruta principal de Python se construye a partir del PythonPath guardado en el registro.

Si el Python Home no puede ser ubicado, PYTHONPATH no está especificado en el entorno y no se encuentra ninguna entrada en el registro, se usa una ruta predeterminada con entradas relativas (por ej. .\Lib;.\plat-win, etc.).

Si se encuentra el archivo pyvenv.cfg junto al ejecutable principal o en el directorio un nivel arriba del ejecutable, se aplica la siguiente variación:

Si home es una ruta absoluta y PYTHONHOME no está configurada, se usa esta ruta en lugar de la ruta al ejecutable principal para deducir la ubicación del directorio de origen.

El resultado final de todo esto es:

Cuando se ejecuta python.exe, o cualquier otro .exe en el directorio principal de Python (tanto la versión instalada como directamente desde el directorio PCbuild), se deduce la ruta principal, y se ignoran las rutas principales en el registro. Siempre se leen otras «rutas de aplicación» del registro.

Cuando se aloja Python en otro .exe (distinto directorio, incrustado mediante COM, etc.), el «Python Home» no se deduce, y se utiliza la ruta principal del registro. Siempre se leen otras «rutas de aplicación» del registro.

Si Python no puede encontrar su directorio de origen y no hay valores en el registro (un .exe congelado, una muy rara configuración de instalación) se obtiene una ruta relativa predeterminada.

Para aquellos que quieran incluir Python en su aplicación o distribución, los siguientes consejos evitarán conflictos con otras instalaciones:

Incluya un archivo ._pth junto al ejecutable, que contenga los directorios a incluir. Esto hará que se ignoren las rutas enumeradas en el registro y en las variables de entorno, y que también se ignore site a menos que se especifique import site.

Si se carga python3.dll o python37.dll desde un ejecutable propio, invocar explícitamente Py_SetPath() o (al menos) Py_SetProgramName() antes de Py_Initialize().

Limpie y/o sobrescriba PYTHONPATH y configure PYTHONHOME antes de iniciar python.exe desde su aplicación.

Si no se pueden utilizar las sugerencias previas (por ejemplo, en una distribución que permite a los usuarios ejecutar python.exe directamente), hay que asegurarse de que el archivo de referencia (Lib\os.py) exista en el directorio de instalación. (Tener en cuenta que este no será detectado dentro de un archivo ZIP, pero si se detectará un ZIP correctamente nombrado.)

Esto asegura que los archivos de una instalación del sistema no tendrán precedencia por sobre la copia de la biblioteca estándar incluida en su aplicación. De otra manera, los usuarios podrían experimentar problemas al utilizar su aplicación. Tenga en cuenta que la primera sugerencia es la mejor, ya que las otras aún pueden ser afectadas por rutas no estándar en el registro y en el site-packages del usuario.

Distinto en la versión 3.6:

Agrega soporte para archivos ._pth y elimina la opción applocal de pyvenv.cfg.

Agrega pythonXX.zip como un potencial archivo de referencia cuando se encuentra junto al ejecutable.

Obsoleto desde la versión 3.6:

Los módulos especificados en el registro bajo Modules (no PythonPath) pueden ser importados por importlib.machinery.WindowsRegistryFinder. Este buscador está habilitado en Windows en la versión 3.6.0 y anteriores, pero es posible que deba agregarse explícitamente a sys.meta_path en el futuro.

3.10. Módulos adicionales

Aunque Python pretende ser portátil entre todas las plataformas, hay características que son exclusivas de Windows. Existen un par de módulos, de la biblioteca estándar y externos, y fragmentos de código para utilizar estas funciones.

Los módulos estándar específicos para Windows se encuentran documentados en Servicios Específicos para MS Windows.

3.10.1. PyWin32

El módulo PyWin32 [https://pypi.org/project/pywin32] de Mark Hammond es una colección de módulos para soporte avanzado específico para Windows. Este incluye utilidades para:

Component Object Model [https://docs.microsoft.com/en-us/windows/win32/com/component-object-model--com--portal] (COM)

Invocación de la API Win32

Registro

Registro de eventos

Microsoft Foundation Classes [https://docs.microsoft.com/en-us/cpp/mfc/mfc-desktop-applications] (MFC) user interfaces

PythonWin [https://web.archive.org/web/20060524042422/https://www.python.org/windows/pythonwin/] es una aplicación MFC de muestra distribuida con PyWin32. Es un IDE incrustable con depurador incorporado.

Ver también

Win32 How Do I…? [http://timgolden.me.uk/python/win32_how_do_i.html]

por Tim Golden

Python and COM [https://www.boddie.org.uk/python/COM.html]

por David y Paul Boddie

3.10.2. cx_Freeze

cx_Freeze [https://cx-freeze.readthedocs.io/en/latest/] is a distutils extension (see Extendiendo Distutils) which wraps Python scripts into executable Windows programs (*.exe files). When you have done this, you can distribute your application without requiring your users to install Python.

3.11. Compilar Python en Windows

Si desea compilar CPython por su cuenta, lo primero que debe hacer es obtener el código fuente [https://www.python.org/downloads/source/]. Puede descargar el código fuente de la última versión o simplemente obtener una nueva copia [https://devguide.python.org/setup/#getting-the-source-code].

The source tree contains a build solution and project files for Microsoft Visual Studio, which is the compiler used to build the official Python releases. These files are in the PCbuild directory.

Consulte PCbuild/readme.txt para obtener información general acerca del proceso de compilación.

Para módulos de extensión, consulte Creación de extensiones C y C++ en Windows.

3.12. Otras plataformas

Con el continuo desarrollo de Python, algunas plataformas que solían ser compatibles ya no lo son (debido a la falta de usuarios o desarrolladores). Consulte PEP 11 [https://www.python.org/dev/peps/pep-0011] para detalles sobre las plataformas no soportadas.

Windows CE [http://pythonce.sourceforge.net/] is no longer supported [https://github.com/python/cpython/issues/71542] since Python 3 (if it ever was).

The Cygwin [https://cygwin.com/] installer offers to install the Python interpreter [https://cygwin.com/packages/summary/python3.html] as well

Para obtener información detallada acerca de las plataformas con instaladores precompilados consulte Python for Windows [https://www.python.org/downloads/windows/].

4. Using Python on a Mac

Autor

Bob Savage <bobsavage@mac.com>

Python on a Mac running macOS is in principle very similar to Python on any other Unix platform, but there are a number of additional features such as the IDE and the Package Manager that are worth pointing out.

4.1. Obteniendo e instalando MacPython

macOS since version 10.8 comes with Python 2.7 pre-installed by Apple. If you wish, you are invited to install the most recent version of Python 3 from the Python website (https://www.python.org). A current «universal binary» build of Python, which runs natively on the Mac’s new Intel and legacy PPC CPU’s, is available there.

Lo que obtienes después de instalar es una serie de cosas:

Una carpeta Python 3.9 en su carpeta Applications. Aquí encontrará IDLE, el entorno de desarrollo que es una parte estándar de las distribuciones oficiales de Python; y PythonLauncher, que se encarga de hacer doble clic en los scripts de Python desde el Finder.

Un framework /Library/Frameworks/Python.framework, el cual incluye los ejecutables y librerías de Python. El instalador añade esta ubicación a su variable de entorno. Para desinstalar MacPython, usted puede simplemente remover estas tres cosas. Un enlace simbólico al ejecutable de Python es colocado en /usr/local/bin/.

La compilación proporcionada por Apple de Python se instala en /System/Library/Frameworks/Python.framework y /usr/bin/python, respectivamente. Nunca debe modificarlos ni eliminarlos, ya que están controlados por Apple y son utilizados por software de Apple o de terceros. Recuerde que si elige instalar una versión más reciente de Python desde python.org, tendrá dos instalaciones de Python diferentes pero funcionales en su computadora, por lo que será importante que sus rutas y usos sean consistentes con lo que desea hacer.

IDLE incluye un menú de ayuda que le permite acceder a la documentación de Python. Si es completamente nuevo en Python, debe comenzar a leer la introducción del tutorial en ese documento.

Si está familiarizado con Python en otras plataformas Unix, debe leer la sección sobre cómo ejecutar scripts Python desde el shell de Unix.

4.1.1. Cómo ejecutar un script de Python

Your best way to get started with Python on macOS is through the IDLE integrated development environment, see section El IDE and use the Help menu when the IDE is running.

If you want to run Python scripts from the Terminal window command line or from the Finder you first need an editor to create your script. macOS comes with a number of standard Unix command line editors, vim and emacs among them. If you want a more Mac-like editor, BBEdit or TextWrangler from Bare Bones Software (see http://www.barebones.com/products/bbedit/index.html) are good choices, as is TextMate (see https://macromates.com/). Other editors include Gvim (http://macvim-dev.github.io/macvim/) and Aquamacs (http://aquamacs.org/).

Para ejecutar su script desde la ventana Terminal, debe asegurarse de que: /usr/local/bin esté en su ruta de búsqueda de shell.

Para ejecutar su script desde el Finder, tiene dos opciones:

Arrástrelo a PythonLauncher

Seleccione PythonLauncher como aplicación predeterminada para abrir su script (o cualquier script .py) a través de la ventana de información del buscador y haga doble clic en ella. PythonLauncher tiene varias preferencias para controlar cómo se inicia su secuencia de comandos. La opción de arrastrar le permite cambiarlos para una invocación, o usar su menú de Preferencias para cambiar las cosas globalmente.

4.1.2. Ejecutar scripts con una GUI

With older versions of Python, there is one macOS quirk that you need to be aware of: programs that talk to the Aqua window manager (in other words, anything that has a GUI) need to be run in a special way. Use pythonw instead of python to start such scripts.

Con Python 3.9, usted podrá utilizar ya sea python o pythonw.

4.1.3. Configuración

Python on macOS honors all standard Unix environment variables such as PYTHONPATH, but setting these variables for programs started from the Finder is non-standard as the Finder does not read your .profile or .cshrc at startup. You need to create a file ~/.MacOSX/environment.plist. See Apple’s Technical Document QA1067 for details.

Para obtener más información sobre la instalación de paquetes de Python en MacPython, consulte la sección Instalación de paquetes adicionales de Python.

4.2. El IDE

MacPython se entrega con el entorno de desarrollo IDLE estándar. Se puede encontrar una buena introducción al uso de IDLE en http://www.hashcollision.org/hkn/python/idle_intro/index.html.

4.3. Instalación de paquetes adicionales de Python

Existen varios métodos para instalar paquetes Python adicionales:

Los paquetes se pueden instalar a través del modo distutils estándar de Python (python setup.py install).

Muchos paquetes también se pueden instalar a través de la extensión setuptools o el wrapper pip, consulte https://pip.pypa.io/.

4.4. Programación de GUI en Mac

Hay varias opciones para crear aplicaciones GUI en Mac con Python.

PyObjC es un enlace de Python al framework Objective-C/Cocoa de Apple, que es la base del desarrollo más moderno de Mac. La información sobre PyObjC está disponible en https://pypi.org/project/pyobjc/.

El kit de herramientas estándar de Python GUI es tkinter, basado en el kit de herramientas Tk multiplataforma (https://www.tcl.tk). Apple incluye una versión nativa de Aqua de Tk, y la última versión puede ser descargada e instalada desde https://www.activestate.com; También se puede incorporar desde la fuente.

wxPython is another popular cross-platform GUI toolkit that runs natively on macOS. Packages and documentation are available from https://www.wxpython.org.

PyQt is another popular cross-platform GUI toolkit that runs natively on macOS. More information can be found at https://riverbankcomputing.com/software/pyqt/intro.

4.5. Distribuyendo aplicaciones de Python en la Mac

The standard tool for deploying standalone Python applications on the Mac is py2app. More information on installing and using py2app can be found at https://pypi.org/project/py2app/.

4.6. Otros recursos

La lista de correo de MacPython es un excelente recurso de soporte para usuarios y desarrolladores de Python en Mac:

https://www.python.org/community/sigs/current/pythonmac-sig/

Otro recurso útil es el wiki de MacPython:

https://wiki.python.org/moin/MacPython

5. Editores e IDEs

Existen numerosos IDEs que admiten el lenguaje de programación Python. Muchos editores e IDEs proporcionan resaltado de sintaxis, herramientas de depuración y comprobaciones de PEP 8 [https://www.python.org/dev/peps/pep-0008].

Diríjase a Python Editors [https://wiki.python.org/moin/PythonEditors] y a Integrated Development Environments [https://wiki.python.org/moin/IntegratedDevelopmentEnvironments] para obtener una lista completa.

Referencia del Lenguaje Python

Este manual de referencia describe la sintaxis y la «semántica base» del lenguaje. Es conciso, pero intenta ser exacto y completo. La semántica de los tipos de objetos integrados no esenciales y de las funciones y módulos integrados están descritos en La Biblioteca Estándar de Python. Para obtener una introducción informal al lenguaje, consulte Tutorial de Python. Para programadores C o C++, existen dos manuales adicionales: Ampliación e incrustación del intérprete de Python describe detalladamente cómo escribir un módulo de extensión de Python, y Manual de referencia de la API en C de Python describe en detalle las interfaces disponibles para los programadores C/C++.

1. Introducción

1.1. Implementaciones alternativas

1.2. Notación

2. Análisis léxico

2.1. Estructura de línea

2.2. Otros tokens

2.3. Identificadores y palabras clave

2.4. Literales

2.5. Operadores

2.6. Delimitadores

3. Modelo de datos

3.1. Objetos, valores y tipos

3.2. Jerarquía de tipos estándar

3.3. Nombres especiales de método

3.4. Corrutinas

4. Modelo de ejecución

4.1. Estructura de un programa

4.2. Nombres y vínculos

4.3. Excepciones

5. El sistema de importación

5.1. importlib

5.2. Paquetes

5.3. Buscando

5.4. Cargando

5.5. El buscador basado en rutas

5.6. Reemplazando el sistema de importación estándar

5.7. Paquete Importaciones relativas

5.8. Consideraciones especiales para __main__

5.9. Problemas sin resolver

5.10. Referencias

6. Expresiones

6.1. Conversiones aritméticas

6.2. Átomos

6.3. Primarios

6.4. Expresión await

6.5. El operador de potencia

6.6. Aritmética unaria y operaciones bit a bit

6.7. Operaciones aritméticas binarias

6.8. Operaciones de desplazamiento

6.9. Operaciones bit a bit binarias

6.10. Comparaciones

6.11. Operaciones booleanas

6.12. Expresiones de asignación

6.13. Expresiones condicionales

6.14. Lambdas

6.15. Listas de expresiones

6.16. Orden de evaluación

6.17. Prioridad de operador

7. Declaraciones simples

7.1. Declaraciones de tipo expresión

7.2. Declaraciones de asignación

7.3. La declaración assert

7.4. La declaración pass

7.5. La declaración del

7.6. La declaración return

7.7. La declaración yield

7.8. La declaración raise

7.9. La declaración break

7.10. La declaración continue

7.11. La declaración import

7.12. La declaración global

7.13. La declaración nonlocal

8. Sentencias compuestas

8.1. La sentencia if

8.2. La sentencia while

8.3. La sentencia for

8.4. La sentencia try

8.5. La sentencia with

8.6. Definiciones de funciones

8.7. Definiciones de clase

8.8. Corrutinas

9. Componentes de nivel superior

9.1. Programas completos de Python

9.2. Entrada de archivo

9.3. Entrada interactiva

9.4. Entrada de expresión

10. Especificación completa de la gramática

1. Introducción

Este manual de referencia describe el lenguaje de programación Python. No pretende ser un tutorial.

Aunque intento ser lo más preciso posible, prefiero usar español en lugar de especificaciones formales para todo excepto para la sintaxis y el análisis léxico. Ésto debería hacer el documento más comprensible para el lector promedio, pero deja espacio para ambigüedades. De esta manera, si vinieras de Marte e intentases implementar Python utilizando únicamente este documento, tendrías que deducir cosas y, de hecho, probablemente acabarías implementando un lenguaje diferente. Por otro lado, si estás usando Python y te preguntas cuáles son las reglas concretas acerca de un área específica del lenguaje, definitivamente las encontrarás aquí. Si te gustaría ver una definición más formal del lenguaje, tal vez podrías dedicar, voluntariamente, algo de tu tiempo… O inventar una máquina de clonar :-).

Es peligroso añadir muchos detalles de implementación en un documento de referencia: la implementación puede cambiar y otras implementaciones del lenguaje pueden funcionar de forma diferente. Por otro lado, CPython es la implementación de Python más usada (aunque implementaciones alternativas están ganando soporte), y es importante mencionar sus detalles particulares especialmente donde la implementación impone limitaciones adicionales. Por lo tanto, encontrarás pequeñas «notas sobre la implementación» repartidas por todo el texto.

Cada implementación de Python viene con un número de módulos estándar incorporados. Éstos están documentados en La Biblioteca Estándar de Python. Unos pocos de estos módulos son citados cuando interactúan de forma significativa con la definición del lenguaje.

1.1. Implementaciones alternativas

Aunque hay una implementación de Python que es, de lejos, la más popular, hay otras implementaciones alternativas que pueden ser de particular interés para diferentes audiencias.

Las implementaciones conocidas incluyen:

CPython

Es la implementación original, y la más mantenida, de Python y está escrita en C. Las nuevas características del lenguaje normalmente aparecen primero aquí.

Jython

Python implementado en Java. Esta implementación se puede usar como lenguaje de scripting para aplicaciones Java o se puede usar para crear aplicaciones usando las librerías de clases de Java. A menudo se usa para crear pruebas para librerías de Java. Se puede hallar más información en el sitio web de Jython [http://jython.org].

Python for .NET

Esta implementación, de hecho, usa la implementación CPython, pero es una aplicación .NET gestionada y usa librerías .NET. Ha sido creada por Brian Lloyd. Para más información ir al sitio web de Python for .NET [https://pythonnet.github.io/].

IronPython

Un Python alternativo para .NET. Al contrario que Python.NET, esta es una implementación completa de Python que genera lenguaje intermedio (IL) y compila el código directamente en ensamblados de .NET. Ha sido creado por Jim Hugunin, el creador original de Jython. Para más información ver el sitio web de IronPython [http://ironpython.net/].

PyPy

Una implementación de Python escrita completamente en Python. Soporta varias características avanzadas que no se encuentran en otras implementaciones como el soporte stackless y un compilador Just in Time. Una de las metas del proyecto es animar a la experimentación con el lenguaje mismo haciendo más fácil la modificación del intérprete (ya que está escrito en Python). Hay información adicional disponible en el sitio web del proyecto PyPy [http://pypy.org/].

Cada una de estas implementaciones varía de una forma u otra del lenguaje tal y como está documentado en este manual, o introduce información específica más allá de lo cubierto por la documentación estándar de Python. Por favor, consulte la documentación específica de cada implementación para saber qué tienes que saber acerca de la implementación específica que uses.

1.2. Notación

Las descripciones del análisis léxico y sintáctico usan una notación gramatical BNF modificada. De tal forma, utilizan el siguiente estilo de definición:

name      ::=  lc_letter (lc_letter | "_")*
lc_letter ::=  "a"..."z"

La primera línea dice que un name es una lc_letter seguida de una secuencia de cero o más lc_letters y guiones bajos. Una lc_letter es, a su vez, cualquiera de los caracteres de la 'a' a la 'z'. (Esta regla se cumple realmente para los nombres definidos en las reglas léxicas y gramaticales en este documento.)

Cada regla empieza con un nombre (que es el nombre definido por la regla) y ::=. Una barra vertical (|) se usa para separar alternativas; es el operador menos vinculante en esta notación. Un asterisco (*) significa cero o más repeticiones del elemento anterior; del mismo modo, un signo más (+) significa una o más repeticiones, y una frase entre corchetes ([]) significa cero o una ocurrencia (en otras palabras, la frase adjunta es opcional). Los operadores * y + se vinculan lo más firmemente posible; los paréntesis se usan para agrupar. Las cadenas de caracteres literales están entre comillas. El espacio en blanco sólo es útil para separar tokens. Las reglas normalmente están contenidas en una sola línea; las reglas con varias alternativas se pueden formatear, de forma alternativa, con una barra vertical con cada línea después del primer comienzo.

En las definiciones léxicas (como en el ejemplo anterior), se utilizan dos convenciones más: dos caracteres literales separados por tres puntos significan la elección de cualquier carácter individual en el rango (inclusivo) de caracteres ASCII dado. Una frase entre paréntesis angulares (<...>) da una definición informal del símbolo definido; por ejemplo, ésto se puede usar, si fuera necesario, para describir la noción de “carácter de control”.

Aunque la notación usada es casi la misma, hay una gran diferencia entre el significado de las definiciones léxicas y sintácticas: una definición léxica opera en los caracteres individuales de la fuente de entrada mientras que una definición sintáctica opera en el flujo de tokens generados por el análisis léxico. Todos los usos de BNF en el siguiente capítulo («Análisis Léxico») son definiciones léxicas. Usos en capítulos posteriores son definiciones sintácticas.

2. Análisis léxico

Un programa de Python es leído por un parser (analizador sintáctico). Los datos introducidos en el analizador son un flujo de tokens, generados por el analizador léxico. Este capítulo describe cómo el analizador léxico desglosa un archivo en tokens.

Python lee el texto del programa como puntos de código Unicode; la codificación de un archivo fuente puede ser dada por una declaración de codificación y por defecto es UTF-8, ver PEP 3120 [https://www.python.org/dev/peps/pep-3120] para más detalles. Si el archivo fuente no puede ser decodificado, se genera un SyntaxError.

2.1. Estructura de línea

Un programa Python se divide en un número de líneas lógicas.

2.1.1. Líneas lógicas

El final de una línea lógica está representado por el token NEWLINE (nueva línea). Las declaraciones no pueden cruzar los límites de la línea lógica, excepto cuando la sintaxis permite la utilización de NEWLINE (por ejemplo, entre declaraciones en declaraciones compuestas). Una línea lógica se construye a partir de una o más líneas físicas siguiendo las reglas explícitas o implícitas de unión de líneas.

2.1.2. Líneas físicas

Una línea física es una secuencia de caracteres terminada por una secuencia de final de línea. En los archivos fuente y las cadenas, se puede utilizar cualquiera de las secuencias de terminación de línea de la plataforma estándar: el formulario Unix que utiliza ASCII LF (salto de línea, por el inglés linefeed), el formulario Windows que utiliza la secuencia ASCII CR LF (retorno seguido de salto de línea), o el antiguo formulario Macintosh que utiliza el carácter ASCII CR (retorno). Todas estas formas pueden ser utilizadas por igual, independientemente de la plataforma. El final de la introducción de datos también sirve como un terminador implícito para la línea física final.

Al incrustar Python, las cadenas de código fuente deben ser pasadas a las APIs de Python usando las convenciones estándar de C para los caracteres de nueva línea (el carácter \n, que representa ASCII LF, es el terminador de línea).

2.1.3. Comentarios

Un comentario comienza con un carácter de almohadilla (#) que no es parte de un literal de cadena, y termina al final de la línea física. Un comentario implica el final de la línea lógica, a menos que se invoque la regla implícita de unión de líneas. Los comentarios son ignorados por la sintaxis.

2.1.4. Declaración de Codificación

Si un comentario en la primera o segunda línea del script de Python coincide con la expresión regular coding[=:]\s*([-\w.]+), este comentario se procesa como una declaración de codificación; el primer grupo de esta expresión denomina la codificación del archivo de código fuente. La declaración de codificación debe aparecer en una línea propia. Si se trata de la segunda línea, la primera línea debe ser también una línea solamente de comentario. Las formas recomendadas de una expresión de codificación son

# -*- coding: <encoding-name> -*-

que también es reconocido por GNU Emacs y

# vim:fileencoding=<encoding-name>

que es reconocido por el VIM de Bram Moolenaar.

Si no se encuentra una declaración de codificación, la codificación por defecto es UTF-8. Además, si los primeros bytes del archivo son la marca de orden de bytes UTF-8 (b'\xef\xbb\xbf'), la codificación declarada del archivo es UTF-8 (esto está soportado, entre otros, por el programa notepad de Microsoft).

If an encoding is declared, the encoding name must be recognized by Python (see Codificaciones estándar). The encoding is used for all lexical analysis, including string literals, comments and identifiers.

2.1.5. Unión explícita de líneas

Dos o más líneas físicas pueden unirse en líneas lógicas utilizando caracteres de barra invertida (\), de la siguiente manera: cuando una línea física termina en una barra invertida que no es parte de literal de cadena o de un comentario, se une con la siguiente formando una sola línea lógica, borrando la barra invertida y el siguiente carácter de fin de línea. Por ejemplo:

if 1900 < year < 2100 and 1 <= month <= 12 \
   and 1 <= day <= 31 and 0 <= hour < 24 \
   and 0 <= minute < 60 and 0 <= second < 60:   # Looks like a valid date
        return 1

Una línea que termina en una barra invertida no puede llevar un comentario. Una barra invertida no continúa un comentario. Una barra invertida no continúa un token excepto para los literales de la cadena (es decir, los tokens que no sean literales de la cadena no pueden ser divididos a través de líneas físicas usando una barra invertida). La barra invertida es ilegal en cualquier parte de una línea fuera del literal de la cadena.

2.1.6. Unión implícita de líneas

Las expresiones entre paréntesis, entre corchetes o entre rizos pueden dividirse en más de una línea física sin usar barras invertidas. Por ejemplo:

month_names = ['Januari', 'Februari', 'Maart',      # These are the
               'April',   'Mei',      'Juni',       # Dutch names
               'Juli',    'Augustus', 'September',  # for the months
               'Oktober', 'November', 'December']   # of the year

Las líneas continuas implícitas pueden llevar comentarios. La sangría de las líneas de continuación no es importante. Se permiten líneas de continuación en blanco. No hay ningún token NEWLINE (nueva línea) entre las líneas de continuación implícitas. Las líneas de continuación implícitas también pueden aparecer dentro de cadenas de triple comilla ( ver más adelante); en ese caso no pueden llevar comentarios.

2.1.7. Líneas en blanco

Una línea lógica que contiene sólo espacios, tabulaciones, saltos de página y posiblemente un comentario, es ignorada (es decir, no se genera un símbolo de NEWLINE). Durante la introducción interactiva de declaraciones, el manejo de una línea en blanco puede variar dependiendo de la implementación del bucle de read-eval-print (lectura-evaluación-impresión). En el intérprete interactivo estándar, una línea lógica completamente en blanco (es decir, una que no contiene ni siquiera un espacio en blanco o un comentario) termina una declaración de varias líneas.

2.1.8. Sangría

El espacio en blanco ( espacios y tabulaciones) al principio de una línea lógica se utiliza para calcular el nivel de sangría de la línea, que a su vez se utiliza para determinar la agrupación de las declaraciones.

Los tabuladores se sustituyen (de izquierda a derecha) por uno a ocho espacios, de manera que el número total de caracteres hasta el reemplazo inclusive es un múltiplo de ocho (se pretende que sea la misma regla que la utilizada por Unix). El número total de espacios que preceden al primer carácter no en blanco determina entonces la sangría de la línea. La sangría no puede dividirse en múltiples líneas físicas utilizando barras invertidas; el espacio en blanco hasta la primera barra invertida determina la sangría.

La indentación se rechaza como inconsistente si un archivo fuente mezcla tabulaciones y espacios de manera que el significado depende del valor de una tabulación en los espacios; un TabError se produce en ese caso.

Nota de compatibilidad entre plataformas: debido a la naturaleza de los editores de texto en plataformas que no sean UNIX, no es aconsejable utilizar una mezcla de espacios y tabuladores para la sangría en un solo archivo de origen. También debe tenerse en cuenta que las diferentes plataformas pueden limitar explícitamente el nivel máximo de sangría.

Un carácter formfeed puede estar presente al comienzo de la línea; será ignorado para los cálculos de sangría anteriores. Los caracteres formfeed que aparecen en otras partes del espacio en blanco inicial tienen un efecto indefinido (por ejemplo, pueden poner a cero el recuento de espacio).

Los niveles de sangría de las líneas consecutivas se utilizan para generar tokens INDENT y DEDENT, utilizando una pila, de la siguiente manera.

Antes de que se lea la primera línea del archivo, se empuja un solo cero en la pila; esto no volverá a saltar. Los números empujados en la pila siempre irán aumentando estrictamente de abajo hacia arriba. Al principio de cada línea lógica, el nivel de sangría de la línea se compara con la parte superior de la pila. Si es igual, no pasa nada. Si es mayor, se empuja en la pila, y se genera un token INDENT. Si es más pequeño, debe ser uno de los números de la pila; todos los números de la pila que son más grandes se sacan, y por cada número sacado se genera un token DEDENT. Al final del archivo, se genera un token DEDENT por cada número restante de la pila que sea mayor que cero.

Aquí hay un ejemplo de un código de Python con una correcta (aunque no tan clara) sangría:

def perm(l):
        # Compute the list of all permutations of l
    if len(l) <= 1:
                  return [l]
    r = []
    for i in range(len(l)):
             s = l[:i] + l[i+1:]
             p = perm(s)
             for x in p:
              r.append(l[i:i+1] + x)
    return r

El siguiente ejemplo muestra varios errores de sangría:

 def perm(l):                       # error: first line indented
for i in range(len(l)):             # error: not indented
    s = l[:i] + l[i+1:]
        p = perm(l[:i] + l[i+1:])   # error: unexpected indent
        for x in p:
                r.append(l[i:i+1] + x)
            return r                # error: inconsistent dedent

(En realidad, los tres primeros errores son detectados por el analizador; sólo el último error es encontrado por el analizador léxico — la sangría de return r no coincide con un nivel sacado de la pila.)

2.1.9. Espacios en blanco entre tokens

A excepción del comienzo de una línea lógica o en los literales de cadenas, los caracteres de espacio en blanco, tabulación y formfeed pueden utilizarse indistintamente para separar tokens. Los espacios en blanco se necesitan entre dos tokens sólo si su concatenación podría interpretarse de otra manera como un token diferente (por ejemplo, ab es un token, pero a b corresponde a dos tokens).

2.2. Otros tokens

Además de NEWLINE, INDENT y DEDENT, existen las siguientes categorías de fichas: identifiers (identificadores), keywords (palabras clave), literals (literales), operators (operadores) y delimiters (delimitadores). Los caracteres de espacio en blanco (distintos de los terminadores de línea, discutidos anteriormente) no son tokens, pero sirven para delimitarlos. En los casos en que exista ambigüedad, un token comprende la cadena más larga posible que forma un token legal cuando se lee de izquierda a derecha.

2.3. Identificadores y palabras clave

Los identificadores (también denominados nombres) se describen mediante las siguientes definiciones léxicas.

La sintaxis de los identificadores en Python se basa en el anexo estándar de Unicode UAX-31, con la elaboración y los cambios que se definen a continuación; ver también PEP 3131 [https://www.python.org/dev/peps/pep-3131] para más detalles.

Dentro del rango ASCII (U+0001..U+007F), los caracteres válidos para los identificadores son los mismos que en Python 2.x: las letras mayúsculas y minúsculas A hasta Z, el guión bajo _ y los dígitos 0 hasta 9, salvo el primer carácter.

Python 3.0 introduce caracteres adicionales fuera del rango ASCII (ver PEP 3131 [https://www.python.org/dev/peps/pep-3131]). Para estos caracteres, la clasificación utiliza la versión de la base de datos de caracteres Unicode incluida en el módulo unicodedata.

Los identificadores son de extensión ilimitada. Las mayúsculas y minúsculas son significativas.

identifier   ::=  xid_start xid_continue*
id_start     ::=  <all characters in general categories Lu, Ll, Lt, Lm, Lo, Nl, the underscore, and characters with the Other_ID_Start property>
id_continue  ::=  <all characters in id_start, plus characters in the categories Mn, Mc, Nd, Pc and others with the Other_ID_Continue property>
xid_start    ::=  <all characters in id_start whose NFKC normalization is in "id_start xid_continue*">
xid_continue ::=  <all characters in id_continue whose NFKC normalization is in "id_continue*">

Los códigos de la categoría Unicode mencionados anteriormente representan:

Lu - letras mayúsculas

Ll - letras minúsculas

Lt - letras de titlecase

Lm - letras modificadoras

Lo - otras letras

Nl - números de letra

Mn - marcas sin separación

Mc - marcas de combinación de separación

Nd - números decimales

Pc - puntuaciones conectoras

Other_ID_Start - lista explícita de caracteres en PropList.txt [http://www.unicode.org/Public/12.1.0/ucd/PropList.txt] para apoyar la compatibilidad hacia atrás

Other_ID_Continue - Así mismo

Todos los identificadores se convierten en la forma normal NFKC mientras se analizan; la comparación de los identificadores se basa en NFKC.

Puede encontrar un archivo HTML no normativo que enumera todos los caracteres identificadores válidos para Unicode 4.1 en https://www.unicode.org/Public/13.0.0/ucd/DerivedCoreProperties.txt

2.3.1. Palabras clave

Los siguientes identificadores se utilizan como palabras reservadas, o palabras clave del idioma, y no pueden utilizarse como identificadores ordinarios. Deben escribirse exactamente como están escritas aquí:

False      await      else       import     pass
None       break      except     in         raise
True       class      finally    is         return
and        continue   for        lambda     try
as         def        from       nonlocal   while
assert     del        global     not        with
async      elif       if         or         yield

2.3.2. Clases reservadas de identificadores

Ciertas clases de identificadores (además de las palabras clave) tienen significados especiales. Estas clases se identifican por los patrones de los caracteres de guión bajo que van delante y detrás:

_*

No importado por from module import *. El identificador especial _ se utiliza en el intérprete interactivo para almacenar el resultado de la última evaluación; se almacena en el módulo builtins. Cuando no está en modo interactivo, _ no tiene un significado especial y no está definido. Ver la sección La declaración import.

Nota

El nombre _ se usa a menudo en conjunción con la internacionalización; consultar la documentación del módulo gettext` para más información sobre esta convención.

__*__

Nombres definidos por el sistema, conocidos informalmente como nombres «dunder». Estos nombres son definidos por el intérprete y su aplicación (incluida la biblioteca estándar). Los nombres actuales del sistema se discuten en la sección Nombres especiales de método y en otros lugares. Es probable que se definan más en futuras versiones de Python. Cualquier uso de nombres __*__, en cualquier contexto, que no siga un uso explícitamente documentado, está sujeto a que se rompa sin previo aviso.

__*

Nombres de clase privada. Los nombres de esta categoría, cuando se utilizan en el contexto de una definición de clase, se reescriben para utilizar una forma desfigurada que ayude a evitar conflictos de nombres entre los atributos «privados» de las clases base y derivadas. Ver la sección Identificadores (Nombres).

2.4. Literales

Los literales son notaciones para los valores constantes de algunos tipos incorporados.

2.4.1. Literales de cadenas y bytes

Los literales de cadena se describen mediante las siguientes definiciones léxicas:

stringliteral   ::=  [stringprefix](shortstring | longstring)
stringprefix    ::=  "r" | "u" | "R" | "U" | "f" | "F"
                     | "fr" | "Fr" | "fR" | "FR" | "rf" | "rF" | "Rf" | "RF"
shortstring     ::=  "'" shortstringitem* "'" | '"' shortstringitem* '"'
longstring      ::=  "'''" longstringitem* "'''" | '"""' longstringitem* '"""'
shortstringitem ::=  shortstringchar | stringescapeseq
longstringitem  ::=  longstringchar | stringescapeseq
shortstringchar ::=  <any source character except "\" or newline or the quote>
longstringchar  ::=  <any source character except "\">
stringescapeseq ::=  "\" <any source character>

bytesliteral   ::=  bytesprefix(shortbytes | longbytes)
bytesprefix    ::=  "b" | "B" | "br" | "Br" | "bR" | "BR" | "rb" | "rB" | "Rb" | "RB"
shortbytes     ::=  "'" shortbytesitem* "'" | '"' shortbytesitem* '"'
longbytes      ::=  "'''" longbytesitem* "'''" | '"""' longbytesitem* '"""'
shortbytesitem ::=  shortbyteschar | bytesescapeseq
longbytesitem  ::=  longbyteschar | bytesescapeseq
shortbyteschar ::=  <any ASCII character except "\" or newline or the quote>
longbyteschar  ::=  <any ASCII character except "\">
bytesescapeseq ::=  "\" <any ASCII character>

Una restricción sintáctica que no se indica en estas producciones es que no se permiten espacios en blanco entre el stringprefix o bytesprefix y el resto del literal. El conjunto de caracteres fuente está definido por la declaración de codificación; es UTF-8 si no se da una declaración de codificación en el archivo fuente; ver la sección Declaración de Codificación.

In plain English: Both types of literals can be enclosed in matching single quotes (') or double quotes ("). They can also be enclosed in matching groups of three single or double quotes (these are generally referred to as triple-quoted strings). The backslash (\) character is used to give special meaning to otherwise ordinary characters like n, which means “newline” when escaped (\n). It can also be used to escape characters that otherwise have a special meaning, such as newline, backslash itself, or the quote character. See escape sequences below for examples.

Los literales de bytes siempre se prefijan con 'b' o 'B'; producen una instancia del tipo bytes en lugar del tipo str. Sólo pueden contener caracteres ASCII; los bytes con un valor numérico de 128 o mayor deben ser expresados con escapes.

Tanto los literales de cadena como de bytes pueden ser prefijados con una letra 'r' o 'R'; tales cadenas se llaman raw strings y consideran las barras inversas como caracteres literales. Como resultado, en las cadenas literales, los escapes de '\U' y '\u' en las cadenas sin procesar no son tratados de manera especial. Dado que los literales raw de unicode de Python 2.x se comportan de manera diferente a los de Python 3.x, la sintaxis de 'ur' no está soportada.

Nuevo en la versión 3.3: El prefijo 'rb' de literales de bytes raw se ha añadido como sinónimo de 'br'.

Nuevo en la versión 3.3: Se reintrodujo el soporte para el legado unicode literal (u'value') para simplificar el mantenimiento de las bases de código dual Python 2.x y 3.x. Ver PEP 414 [https://www.python.org/dev/peps/pep-0414] para más información.

Un literal de cadena con 'f' o 'F' en su prefijo es un formatted string literal; ver Literales de cadena formateados. La 'f' puede combinarse con la 'r', pero no con la 'b' o 'u', por lo que las cadenas raw formateadas son posibles, pero los literales de bytes formateados no lo son.

En los literales de triple cita, se permiten (y se retienen) nuevas líneas y citas no escapadas, excepto cuando tres citas no escapadas seguidas finalizan el literal. (Una «cita» es el carácter utilizado para abrir el literal, es decir, ya sea ' o ".)

A menos que un prefijo 'r' o 'R' esté presente, las secuencias de escape en literales de cadena y bytes se interpretan según reglas similares a las usadas por C estándar. Las secuencias de escape reconocidas son:

Secuencia de escape

Significado

Notas

\newline

Barra inversa y línea nueva ignoradas

\\

Barra inversa (\)

\'

Comilla simple (')

\"

Comilla doble (")

\a

ASCII Bell (BEL)

\b

ASCII Retroceso (BS)

\f

ASCII Formfeed (FF)

\n

ASCII Linefeed (LF)

\r

ASCII Retorno de carro (CR)

\t

ASCII Sangría horizontal (TAB)

\v

ASCII Sangría vertical (VT)

\ooo

Carácter con valor octal ooo

(1,3)

\xhh

Carácter con valor hexadecimal hh

(2,3)

Las secuencias de escape que sólo se reconocen en los literales de cadena son:

Secuencia de escape

Significado

Notas

\N{name}

El carácter llamado name en la base de datos de Unicode

(4)

\uxxxx

Carácter con valor hexadecimal de 16 bits xxxx

(5)

\Uxxxxxxxx

Carácter con valor hexadecimal de 32 bits xxxxxxxx

(6)

Notas:

Como en C estándar, se aceptan hasta tres dígitos octales.

A diferencia de C estándar, se requieren exactamente dos dígitos hexadecimales.

En un literal de bytes, los escapes hexadecimal y octal denotan el byte con el valor dado. En un literal de cadena, estos escapes denotan un carácter Unicode con el valor dado.

Distinto en la versión 3.3: Se ha añadido el soporte para los alias de nombres 1.

Se requieren exactamente cuatro dígitos hexadecimales.

Cualquier carácter Unicode puede ser codificado de esta manera. Se requieren exactamente ocho dígitos hexadecimales.

A diferencia de C estándar, todas las secuencias de escape no reconocidas se dejan en la cadena sin cambios, es decir, la barra invertida se deja en el resultado. (Este comportamiento es útil para la depuración: si una secuencia de escape se escribe mal, la salida resultante se reconoce más fácilmente como rota). También es importante señalar que las secuencias de escape sólo reconocidas en los literales de cadena caen en la categoría de escapes no reconocidos para los literales de bytes.

Distinto en la versión 3.6: Las secuencias de escape no reconocidas producen un DeprecationWarning. En una futura versión de Python serán un SyntaxWarning y eventualmente un SyntaxError.

Incluso en un literal raw, las comillas se pueden escapar con una barra inversa, pero la barra inversa permanece en el resultado; por ejemplo, r"\"" es un literal de cadena válido que consiste en dos caracteres: una barra inversa y una comilla doble; r"\" no es un literal de cadena válido (incluso una cadena en bruto no puede terminar en un número impar de barras inversas). Específicamente, un literal raw no puede terminar en una sola barra inversa (ya que la barra inversa se escaparía del siguiente carácter de comillas). Nótese también que una sola barra inversa seguida de una nueva línea se interpreta como esos dos caracteres como parte del literal, no como una continuación de línea.

2.4.2. Concatenación de literales de cadena

Se permiten múltiples literales de cadenas o bytes adyacentes (delimitados por espacios en blanco), posiblemente utilizando diferentes convenciones de citas, y su significado es el mismo que su concatenación. Por lo tanto, "hola" 'mundo' es equivalente a "holamundo". Esta característica puede ser utilizada para reducir el número de barras inversas necesarias, para dividir largas cadenas convenientemente a través de largas líneas, o incluso para añadir comentarios a partes de las cadenas, por ejemplo:

re.compile("[A-Za-z_]"       # letter or underscore
           "[A-Za-z0-9_]*"   # letter, digit or underscore
          )

Téngase en cuenta que esta característica se define a nivel sintáctico, pero se implementa en el momento de la compilación. El operador “+” debe ser usado para concatenar expresiones de cadena al momento de la ejecución. Observar también que la concatenación de literales puede utilizar diferentes estilos de citas para cada componente (incluso mezclando cadenas raw y cadenas con triple comilla), y los literales de cadena formateados pueden ser concatenados con los literales de cadena simples.

2.4.3. Literales de cadena formateados

Nuevo en la versión 3.6.

Un formatted string literal o f-string es un literal de cadena que se prefija con 'f' o 'F'. Estas cadenas pueden contener campos de reemplazo, que son expresiones delimitadas por llaves {}. Mientras que otros literales de cadena siempre tienen un valor constante, las cadenas formateadas son realmente expresiones evaluadas en tiempo de ejecución.

Las secuencias de escape se decodifican como en los literales de cadena ordinarios (excepto cuando un literal también se marca como cadena raw). Después de la decodificación, la gramática para el contenido de la cadena es:

f_string          ::=  (literal_char | "{{" | "}}" | replacement_field)*
replacement_field ::=  "{" f_expression ["="] ["!" conversion] [":" format_spec] "}"
f_expression      ::=  (conditional_expression | "*" or_expr)
                         ("," conditional_expression | "," "*" or_expr)* [","]
                       | yield_expression
conversion        ::=  "s" | "r" | "a"
format_spec       ::=  (literal_char | NULL | replacement_field)*
literal_char      ::=  <any code point except "{", "}" or NULL>

Las partes de la cadena fuera de las llaves se tratan literalmente, excepto que las llaves dobles '{{' o '}}' se reemplazan con la llave simple correspondiente. Un solo corchete de apertura '{' marca un campo de reemplazo, que comienza con una expresión de Python. Para mostrar tanto el texto de la expresión como su valor después de la evaluación (útil en la depuración), se puede agregar un signo igual '=' después de la expresión. Puede seguir un campo de conversión, introducido por un signo de exclamación '!'. También se puede agregar un especificador de formato, introducido por dos puntos ':'. Un campo de reemplazo termina con un corchete de cierre '}'.

Las expresiones en literales de cadena formateados se tratan como expresiones regulares de Python rodeadas de paréntesis, con algunas excepciones. Una expresión vacía no está permitida, y tanto lambda como las expresiones de asignación := deben estar rodeadas de paréntesis explícitos. Las expresiones de sustitución pueden contener saltos de línea (por ejemplo, en cadenas de tres comillas), pero no pueden contener comentarios. Cada expresión se evalúa en el contexto en el que aparece el literal de cadena formateado, en orden de izquierda a derecha.

Distinto en la versión 3.7: Antes de Python 3.7, una expresión await y comprensiones que contenían una cláusula async for eran ilegales en las expresiones en literales de cadenas formateadas debido a un problema con la implementación.

Cuando se proporciona el signo igual '=', la salida tendrá el texto de expresión, el '=' y el valor evaluado. Los espacios después de la llave de apertura '{', dentro de la expresión y después de '=' se conservan en la salida. Por defecto, el '=' hace que se proporcione repr() de la expresión, a menos que haya un formato especificado. Cuando se especifica un formato, el valor predeterminado es str() de la expresión a menos que se declare una conversión '!r'.

Nuevo en la versión 3.8: El símbolo igual '='.

Si se especifica una conversión, el resultado de la evaluación de la expresión se convierte antes del formateo. La conversión `!s' llama str() al resultado, `!r' llama repr(), y `!a' llama ascii().

El resultado es entonces formateado usando el protocolo format(). El especificador de formato se pasa al método __format__() del resultado de la expresión o conversión. Se pasa una cadena vacía cuando se omite el especificador de formato. El resultado formateado se incluye entonces en el valor final de toda la cadena.

Los especificadores de formato de nivel superior pueden incluir campos de reemplazo anidados. Estos campos anidados pueden incluir sus propios campos de conversión y especificadores de formato, pero pueden no incluir campos de reemplazo más anidados. El especificador de formato mini-lenguaje es el mismo que el utilizado por el método str.format().

Los literales de cadena formateados pueden ser concatenados, pero los campos de reemplazo no pueden ser divididos entre los literales.

Algunos ejemplos de literales de cadena formateados:

>>> name = "Fred"
>>> f"He said his name is {name!r}."
"He said his name is 'Fred'."
>>> f"He said his name is {repr(name)}."  # repr() is equivalent to !r
"He said his name is 'Fred'."
>>> width = 10
>>> precision = 4
>>> value = decimal.Decimal("12.34567")
>>> f"result: {value:{width}.{precision}}"  # nested fields
'result:      12.35'
>>> today = datetime(year=2017, month=1, day=27)
>>> f"{today:%B %d, %Y}"  # using date format specifier
'January 27, 2017'
>>> f"{today=:%B %d, %Y}" # using date format specifier and debugging
'today=January 27, 2017'
>>> number = 1024
>>> f"{number:#0x}"  # using integer format specifier
'0x400'
>>> foo = "bar"
>>> f"{ foo = }" # preserves whitespace
" foo = 'bar'"
>>> line = "The mill's closed"
>>> f"{line = }"
'line = "The mill\'s closed"'
>>> f"{line = :20}"
"line = The mill's closed   "
>>> f"{line = !r:20}"
'line = "The mill\'s closed" '

Una consecuencia de compartir la misma sintaxis que los literales de cadena regulares es que los caracteres en los campos de reemplazo no deben entrar en conflicto con la comilla usada en el literal de cadena formateado exterior:

f"abc {a["x"]} def"    # error: outer string literal ended prematurely
f"abc {a['x']} def"    # workaround: use different quoting

Las barras inversas no están permitidas en las expresiones de formato y generarán un error:

f"newline: {ord('\n')}"  # raises SyntaxError

Para incluir un valor en el que se requiere un escape de barra inversa, hay que crear una variable temporal.

>>> newline = ord('\n')
>>> f"newline: {newline}"
'newline: 10'

Los literales de cadena formateados no pueden ser usados como cadenas de documentos (docstrings), aunque no incluyan expresiones.

>>> def foo():
...     f"Not a docstring"
...
>>> foo.__doc__ is None
True

Ver también PEP 498 [https://www.python.org/dev/peps/pep-0498] para la propuesta que añadió literales de cadenas formateados, y str.format(), que utiliza un mecanismo de cadenas formateadas relacionado.

2.4.4. Literales numéricos

Hay tres tipos de literales numéricos: números enteros, números de punto flotante y números imaginarios. No hay literales complejos (los números complejos pueden formarse sumando un número real y un número imaginario).

Nótese que los literales numéricos no incluyen un signo; una frase como -1 es en realidad una expresión compuesta por el operador unario “-” y el literal 1.

2.4.5. Literales enteros

Los literales enteros se describen mediante las siguientes definiciones léxicas:

integer      ::=  decinteger | bininteger | octinteger | hexinteger
decinteger   ::=  nonzerodigit (["_"] digit)* | "0"+ (["_"] "0")*
bininteger   ::=  "0" ("b" | "B") (["_"] bindigit)+
octinteger   ::=  "0" ("o" | "O") (["_"] octdigit)+
hexinteger   ::=  "0" ("x" | "X") (["_"] hexdigit)+
nonzerodigit ::=  "1"..."9"
digit        ::=  "0"..."9"
bindigit     ::=  "0" | "1"
octdigit     ::=  "0"..."7"
hexdigit     ::=  digit | "a"..."f" | "A"..."F"

No hay límite para la longitud de los literales enteros aparte de lo que se puede almacenar en la memoria disponible.

Los guiones bajos se ignoran para determinar el valor numérico del literal. Se pueden utilizar para agrupar los dígitos para mejorar la legibilidad. Un guión bajo puede ocurrir entre dígitos y después de especificadores de base como 0x.

Nótese que no se permiten los ceros a la izquierda en un número decimal que no sea cero. Esto es para desambiguar con los literales octales de estilo C, que Python usaba antes de la versión 3.0.

Algunos ejemplos de literales enteros:

7     2147483647                        0o177    0b100110111
3     79228162514264337593543950336     0o377    0xdeadbeef
      100_000_000_000                   0b_1110_0101

Distinto en la versión 3.6: Los guiones bajos están ahora permitidos para agrupar en literales.

2.4.6. Literales de punto flotante

Los literales de punto flotante se describen en las siguientes definiciones léxicas:

floatnumber   ::=  pointfloat | exponentfloat
pointfloat    ::=  [digitpart] fraction | digitpart "."
exponentfloat ::=  (digitpart | pointfloat) exponent
digitpart     ::=  digit (["_"] digit)*
fraction      ::=  "." digitpart
exponent      ::=  ("e" | "E") ["+" | "-"] digitpart

Nótese que las partes enteras y exponentes siempre se interpretan usando el radix 10. Por ejemplo, 077e010 es legal, y denota el mismo número que 77e10. El rango permitido de los literales de punto flotante depende de la implementación. Al igual que en los literales enteros, se admiten guiones bajos para la agrupación de dígitos.

Algunos ejemplos de literales de punto flotante:

3.14    10.    .001    1e100    3.14e-10    0e0    3.14_15_93

Distinto en la versión 3.6: Los guiones bajos están ahora permitidos para agrupar en literales.

2.4.7. Literales imaginarios

Los literales imaginarios se describen en las siguientes definiciones léxicas:

imagnumber ::=  (floatnumber | digitpart) ("j" | "J")

Un literal imaginario da un número complejo con una parte real de 0.0. Los números complejos se representan como un par de números de punto flotante y tienen las mismas restricciones en su rango. Para crear un número complejo con una parte real distinta de cero, añada un número de punto flotante, por ejemplo, (3+4j). Algunos ejemplos de literales imaginarios:

3.14j   10.j    10j     .001j   1e100j   3.14e-10j   3.14_15_93j

2.5. Operadores

Los siguientes tokens son operadores:

+       -       *       **      /       //      %      @
<<      >>      &       |       ^       ~       :=
<       >       <=      >=      ==      !=

2.6. Delimitadores

Los siguientes tokens sirven como delimitadores en la gramática:

(       )       [       ]       {       }
,       :       .       ;       @       =       ->
+=      -=      *=      /=      //=     %=      @=
&=      |=      ^=      >>=     <<=     **=

El punto también puede ocurrir en los literales de punto flotante e imaginarios. Una secuencia de tres períodos tiene un significado especial como un literal de elipsis. La segunda mitad de la lista, los operadores de asignación aumentada, sirven léxicamente como delimitadores, pero también realizan una operación.

Los siguientes caracteres ASCII de impresión tienen un significado especial como parte de otros tokens o son de alguna manera significativos para el analizador léxico:

'       "       #       \

Los siguientes caracteres ASCII de impresión no se utilizan en Python. Su presencia fuera de las cadenas de caracteres y comentarios es un error incondicional:

$       ?       `

Notas al pie de página

1

https://www.unicode.org/Public/11.0.0/ucd/NameAliases.txt

3. Modelo de datos

3.1. Objetos, valores y tipos

Objects son la abstracción de Python para los datos. Todos los datos en un programa Python están representados por objetos o por relaciones entre objetos. (En cierto sentido y de conformidad con el modelo de Von Neumann de una «programa almacenado de computadora», el código también está representado por objetos.)

Cada objeto tiene una identidad, un tipo y un valor. La identidad de un objeto nunca cambia una vez que ha sido creado; puede pensar en ello como la dirección del objeto en la memoria. El operador “is” compara la identidad de dos objetos; la función id() retorna un número entero que representa su identidad.

CPython implementation detail: Para CPython, id(x) es la dirección de memoria donde se almacena x.

El tipo de un objeto determina las operaciones que admite el objeto (por ejemplo, «¿tiene una longitud?») y también define los posibles valores para los objetos de ese tipo. La función type() retorna el tipo de un objeto (que es un objeto en sí mismo). Al igual que su identidad, también el type de un objeto es inmutable. 1

El valor de algunos objetos puede cambiar. Se dice que los objetos cuyo valor puede cambiar son mutables; Los objetos cuyo valor no se puede modificar una vez que se crean se denominan inmutables. (El valor de un objeto contenedor inmutable que contiene una referencia a un objeto mutable puede cambiar cuando se cambia el valor de este último; sin embargo, el contenedor todavía se considera inmutable, porque la colección de objetos que contiene no se puede cambiar. Por lo tanto, la inmutabilidad no es estrictamente lo mismo que tener un valor inmutable, es más sutil). La mutabilidad de un objeto está determinada por su tipo; por ejemplo, los números, las cadenas de caracteres y las tuplas son inmutables, mientras que los diccionarios y las listas son mutables.

Los objetos nunca se destruyen explícitamente; sin embargo, cuando se vuelven inalcanzables, se pueden recolectar basura. Se permite a una implementación posponer la recolección de basura u omitirla por completo; es una cuestión de calidad de la implementación cómo se implementa la recolección de basura, siempre que no se recolecten objetos que todavía sean accesibles.

CPython implementation detail: CPython actualmente utiliza un esquema de conteo de referencias con detección retardada (opcional) de basura enlazada cíclicamente, que recolecta la mayoría de los objetos tan pronto como se vuelven inalcanzables, pero no se garantiza que recolecte basura que contenga referencias circulares. Vea la documentación del módulo gc para información sobre el control de la recolección de basura cíclica. Otras implementaciones actúan de manera diferente y CPython puede cambiar. No dependa de la finalización inmediata de los objetos cuando se vuelvan inalcanzables (por lo que siempre debe cerrar los archivos explícitamente).

Tenga en cuenta que el uso de las funciones de rastreo o depuración de la implementación puede mantener activos los objetos que normalmente serían coleccionables. También tenga en cuenta que la captura de una excepción con una sentencia “try…except” puede mantener objetos activos.

Algunos objetos contienen referencias a recursos «externos» como archivos abiertos o ventanas. Se entiende que estos recursos se liberan cuando el objeto es eliminado por el recolector de basura, pero como no se garantiza que la recolección de basura suceda, dichos objetos también proporcionan una forma explícita de liberar el recurso externo, generalmente un método close(). Se recomienda encarecidamente a los programas cerrar explícitamente dichos objetos. La declaración “try…finally” y la declaración “with” proporcionan formas convenientes de hacer esto.

Algunos objetos contienen referencias a otros objetos; estos se llaman contenedores. Ejemplos de contenedores son tuplas, listas y diccionarios. Las referencias son parte del valor de un contenedor. En la mayoría de los casos, cuando hablamos del valor de un contenedor, implicamos los valores, no las identidades de los objetos contenidos; sin embargo, cuando hablamos de la mutabilidad de un contenedor, solo se implican las identidades de los objetos contenidos inmediatamente. Entonces, si un contenedor inmutable (como una tupla) contiene una referencia a un objeto mutable, su valor cambia si se cambia ese objeto mutable.

Los tipos afectan a casi todos los aspectos del comportamiento del objeto. Incluso la importancia de la identidad del objeto se ve afectada en cierto sentido: para los tipos inmutables, las operaciones que calculan nuevos valores en realidad pueden retornar una referencia a cualquier objeto existente con el mismo tipo y valor, mientras que para los objetos mutables esto no está permitido. Por ejemplo, al hacer a = 1; b = 1, a y b puede o no referirse al mismo objeto con el valor 1, dependiendo de la implementación, pero al hacer c = []; d = [], c y d se garantiza que se refieren a dos listas vacías diferentes, únicas y recién creadas. (Tenga en cuenta que c = d = [] asigna el mismo objeto a ambos c y d.)

3.2. Jerarquía de tipos estándar

A continuación se muestra una lista de los tipos integrados en Python. Los módulos de extensión (escritos en C, Java u otros lenguajes, dependiendo de la implementación) pueden definir tipos adicionales. Las versiones futuras de Python pueden agregar tipos a la jerarquía de tipos (por ejemplo, números racionales, matrices de enteros almacenados de manera eficiente, etc.), aunque tales adiciones a menudo se proporcionarán a través de la biblioteca estándar.

Algunas de las descripciones de tipos a continuación contienen un párrafo que enumera “atributos especiales”. Estos son atributos que proporcionan acceso a la implementación y no están destinados para uso general. Su definición puede cambiar en el futuro.

None

Este tipo tiene un solo valor. Hay un solo objeto con este valor. Se accede a este objeto a través del nombre incorporado None. Se utiliza para indicar la ausencia de un valor en muchas situaciones, por ejemplo, se retorna desde funciones que no retornan nada explícitamente. Su valor de verdad es falso.

NotImplemented

Este tipo tiene un solo valor. Hay un solo objeto con este valor. Se accede a este objeto a través del nombre integrado NotImplemented. Los métodos numéricos y los métodos de comparación enriquecidos deben devolver este valor si no implementan la operación para los operandos proporcionados. (El intérprete intentará entonces la operación reflejada, o alguna otra alternativa, dependiendo del operador). No debe evaluarse en un contexto booleano.

Vea Implementar operaciones aritméticas para más detalles.

Distinto en la versión 3.9: La evaluación de NotImplemented en un contexto booleano está en desuso. Si bien actualmente se evalúa como verdadero, lanzará un DeprecationWarning. Lanzará un TypeError en una versión futura de Python.

Elipsis

Este tipo tiene un solo valor. Hay un solo objeto con este valor. Se accede a este objeto a través del literal ... o el nombre incorporado Ellipsis. Su valor de verdad es verdadero.

numbers.Number

Estos son creados por literales numéricos y retornados como resultados por operadores aritméticos y funciones aritméticas integradas. Los objetos numéricos son inmutables; una vez creado su valor nunca cambia. Los números de Python están, por supuesto, fuertemente relacionados con los números matemáticos, pero están sujetos a las limitaciones de la representación numérica en las computadoras.

The string representations of the numeric classes, computed by __repr__() and __str__(), have the following properties:

Son literales numéricos válidos que, cuando se pasan a su constructor de clase, producen un objeto que tiene el valor del numérico original.

La representación está en base 10, cuando sea posible.

Los ceros iniciales, posiblemente excepto un solo cero antes de un punto decimal, no se muestran.

Los ceros finales, posiblemente excepto un solo cero después de un punto decimal, no se muestran.

Solo se muestra un signo cuando el número es negativo.

Python distingue entre números enteros, números de coma flotante y números complejos:

numbers.Integral

Estos representan elementos del conjunto matemático de números enteros (positivo y negativo).

Hay dos tipos de números enteros:

Enteros (int)

Estos representan números en un rango ilimitado, sujetos solo a la memoria (virtual) disponible. Para las operaciones de desplazamiento y máscara, se asume una representación binaria, y los números negativos se representan en una variante del complemento de 2 que da la ilusión de una cadena de caracteres infinita de bits con signo que se extiende hacia la izquierda.

Booleanos (bool)

Estos representan los valores de verdad Falso y Verdadero. Los dos objetos que representan los valores False y True son los únicos objetos booleanos. El tipo booleano es un subtipo del tipo entero y los valores booleanos se comportan como los valores 0 y 1 respectivamente, en casi todos los contextos, con la excepción de que cuando se convierten en una cadena de caracteres, las cadenas de caracteres "False" o "True" son retornadas respectivamente.

Las reglas para la representación de enteros están destinadas a dar la interpretación más significativa de las operaciones de cambio y máscara que involucran enteros negativos.

numbers.Real (float)

Estos representan números de punto flotante de precisión doble a nivel de máquina. Está a merced de la arquitectura de la máquina subyacente (y la implementación de C o Java) para el rango aceptado y el manejo del desbordamiento. Python no admite números de coma flotante de precisión simple; el ahorro en el uso del procesador y la memoria, que generalmente son la razón para usarlos, se ven reducidos por la sobrecarga del uso de objetos en Python, por lo que no hay razón para complicar el lenguaje con dos tipos de números de coma flotante.

numbers.Complex (complex)

Estos representan números complejos como un par de números de coma flotante de precisión doble a nivel de máquina. Se aplican las mismas advertencias que para los números de coma flotante. Las partes reales e imaginarias de un número complejo z se pueden obtener a través de los atributos de solo lectura z.real y z.imag.

Secuencias

Estos representan conjuntos ordenados finitos indexados por números no negativos. La función incorporada len() retorna el número de elementos de una secuencia. Cuando la longitud de una secuencia es n, el conjunto de índices contiene los números 0, 1, …, n-1. El elemento i de la secuencia a se selecciona mediante a[i].

Las secuencias también admiten segmentación: a[i:j] selecciona todos los elementos con índice k de modo que i <= k < j. Cuando se usa como una expresión, un segmento es una secuencia del mismo tipo. Esto implica que el conjunto de índices se vuelve a enumerar para que comience en 0.

Algunas secuencias también admiten «segmentación extendida» con un tercer parámetro «paso» : a[i:j:k] selecciona todos los elementos de a con índice x donde x = i + n*k, n >= 0 y i <= x < j.

Las secuencias se distinguen según su mutabilidad:

Secuencias inmutables

Un objeto de un tipo de secuencia inmutable no puede cambiar una vez que se crea. (Si el objeto contiene referencias a otros objetos, estos otros objetos pueden ser mutables y pueden cambiarse; sin embargo, la colección de objetos a los que hace referencia directamente un objeto inmutable no puede cambiar).

Los siguientes tipos son secuencias inmutables:

Cadenas de caracteres

Una cadena de caracteres es una secuencia de valores que representan puntos de código Unicode. Todos los puntos de código en el rango U+0000 - U+10FFFF se puede representar en una cadena de caracteres. Python no tiene un tipo char; en cambio, cada punto de código en la cadena de caracteres se representa como un objeto de cadena de caracteres con longitud 1. La función incorporada ord() convierte un punto de código de su forma de cadena de caracteres a un entero en el rango 0 - 10FFFF; la función chr() convierte un entero en el rango 0 - 10FFFF a la cadena de caracteres correspondiente de longitud 1. str.encode() se puede usar para convertir un objeto de tipo str a bytes usando la codificación de texto dada, y bytes.decode() se puede usar para lograr el caso inverso.

Tuplas

Los elementos de una tupla son objetos arbitrarios de Python. Las tuplas de dos o más elementos están formadas por listas de expresiones separadas por comas. Se puede formar una tupla de un elemento (un “singleton”) al colocar una coma en una expresión (una expresión en sí misma no crea una tupla, ya que los paréntesis deben ser utilizables para agrupar expresiones). Una tupla vacía puede estar formada por un par de paréntesis vacío.

Bytes

Un objeto de bytes es una colección inmutable. Los elementos son bytes de 8 bits, representados por enteros en el rango 0 <= x <256. Literales de bytes (como b'abc') y el constructor incorporado bytes() se puede utilizar para crear objetos de bytes. Además, los objetos de bytes se pueden decodificar en cadenas de caracteres a través del método decode().

Secuencias mutables

Las secuencias mutables se pueden cambiar después de su creación. Las anotaciones de suscripción y segmentación se pueden utilizar como el objetivo de asignaciones y declaraciones del (eliminar).

Actualmente hay dos tipos intrínsecos de secuencias mutable:

Listas

Los elementos de una lista son objetos de Python arbitrarios. Las listas se forman colocando una lista de expresiones separadas por comas entre corchetes. (Tome en cuenta que no hay casos especiales necesarios para formar listas de longitud 0 o 1.)

Colecciones de bytes

Un objeto bytearray es una colección mutable. Son creados por el constructor incorporado bytearray(). Además de ser mutables (y, por lo tanto, inquebrantable), las colecciones de bytes proporcionan la misma interfaz y funcionalidad que los objetos inmutables bytes.

El módulo de extensión array proporciona un ejemplo adicional de un tipo de secuencia mutable, al igual que el módulo collections.

Tipos de conjuntos

Estos representan conjuntos finitos no ordenados de objetos únicos e inmutables. Como tal, no pueden ser indexados por ningún subscript. Sin embargo, pueden repetirse y la función incorporada len() retorna el número de elementos en un conjunto. Los usos comunes de los conjuntos son pruebas rápidas de membresía, eliminación de duplicados de una secuencia y cálculo de operaciones matemáticas como intersección, unión, diferencia y diferencia simétrica.

Para elementos del conjunto, se aplican las mismas reglas de inmutabilidad que para las claves de diccionario. Tenga en cuenta que los tipos numéricos obedecen las reglas normales para la comparación numérica: si dos números se comparan igual (por ejemplo, 1 y 1.0), solo uno de ellos puede estar contenido en un conjunto.

Actualmente hay dos tipos de conjuntos intrínsecos:

Conjuntos

Estos representan un conjunto mutable. Son creados por el constructor incorporado set() y puede ser modificado posteriormente por varios métodos, como add().

Conjuntos congelados

Estos representan un conjunto inmutable. Son creados por el constructor incorporado frozenset(). Como un conjunto congelado es inmutable y hashable, se puede usar nuevamente como un elemento de otro conjunto o como una clave de un diccionario.

Mapeos

Estos representan conjuntos finitos de objetos indexados por conjuntos de índices arbitrarios. La notación de subíndice a[k] selecciona el elemento indexado por k del mapeo a; esto se puede usar en expresiones y como el objetivo de asignaciones o declaraciones del. La función incorporada len() retorna el número de elementos en un mapeo.

Actualmente hay un único tipo de mapeo intrínseco:

Diccionarios

Estos representan conjuntos finitos de objetos indexados por valores casi arbitrarios. Los únicos tipos de valores no aceptables como claves son valores que contienen listas o diccionarios u otros tipos mutables que se comparan por valor en lugar de por identidad de objeto, la razón es que la implementación eficiente de los diccionarios requiere que el valor hash de una clave permanezca constante. Los tipos numéricos utilizados para las claves obedecen las reglas normales para la comparación numérica: si dos números se comparan igual (por ejemplo, 1 y 1.0) entonces se pueden usar indistintamente para indexar la misma entrada del diccionario.

Los diccionarios conservan el orden de inserción, lo que significa que las claves se mantendrán en el mismo orden en que se agregaron secuencialmente sobre el diccionario. Reemplazar una clave existente no cambia el orden, sin embargo, eliminar una clave y volver a insertarla la agregará al final en lugar de mantener su lugar anterior.

Los diccionarios son mutables; pueden ser creados por la notación {...} (vea la sección Despliegues de diccionario).

Los módulos de extensión dbm.ndbm y dbm.gnu proporcionan ejemplos adicionales de tipos de mapeo, al igual que el módulo collections.

Distinto en la versión 3.7: Los diccionarios no conservaban el orden de inserción en las versiones de Python anteriores a 3.6. En CPython 3.6, el orden de inserción se conserva, pero se consideró un detalle de implementación en ese momento en lugar de una garantía de idioma.

Tipos invocables

Estos son los tipos a los que la operación de llamada de función (vea la sección Invocaciones) puede ser aplicado:

Funciones definidas por el usuario

Un objeto función definido por el usuario, es creado por un definición de función (vea la sección Definiciones de funciones). Debe llamarse con una lista de argumentos que contenga el mismo número de elementos que la lista de parámetros formales de la función.

Atributos especiales:

Atributo

Significado

__doc__

El texto de documentación de la función, o None si no está disponible; no heredado por subclases.

Escribible

__name__

El nombre de la función.

Escribible

__qualname__

Las funciones qualified name.

Nuevo en la versión 3.3.

Escribible

__module__

El nombre del módulo en el que se definió la función, o None si no está disponible.

Escribible

__defaults__

Una tupla que contiene valores de argumento predeterminados para aquellos argumentos que tienen valores predeterminados, o None si ningún argumento tiene un valor predeterminado.

Escribible

__code__

El objeto de código que representa el cuerpo de la función compilada.

Escribible

__globals__

Una referencia al diccionario que contiene las variables globales de la función — el espacio de nombres global del módulo en el que se definió la función.

Solo lectura

__dict__

El espacio de nombres que admite atributos de funciones arbitrarias.

Escribible

__closure__

None o una tupla de celdas que contienen enlaces para las variables libres de la función. Vea a continuación para obtener información sobre el atributo cell_contents.

Solo lectura

__annotations__

Un diccionario que contiene anotaciones de parámetros. Las claves del dict son los nombres de los parámetros, y 'return' para la anotación de retorno, si se proporciona.

Escribible

__kwdefaults__

Un diccionario que contiene valores predeterminados para parámetros de solo palabras clave.

Escribible

La mayoría de los atributos etiquetados «Escribible» verifican el tipo del valor asignado.

Los objetos de función también admiten la obtención y configuración de atributos arbitrarios, que se pueden usar, por ejemplo, para adjuntar metadatos a funciones. La notación de puntos de atributo regular se utiliza para obtener y establecer dichos atributos. Tenga en cuenta que la implementación actual solo admite atributos de función en funciones definidas por el usuario. Los atributos de función en funciones integradas pueden ser compatibles en el futuro.

Un objeto de celda tiene el atributo cell_contents. Esto se puede usar para obtener el valor de la celda, así como para establecer el valor.

Se puede recuperar información adicional sobre la definición de una función desde su objeto de código; Vea la descripción de los tipos internos a continuación. El tipo cell puede ser accedido en el módulo types.

Métodos de instancia

Un objeto de método de instancia combina una clase, una instancia de clase y cualquier objeto invocable (normalmente una función definida por el usuario).

Atributos especiales de solo lectura: __self__ es el objeto de instancia de clase, __func__ es el objeto de función; __doc__ es la documentación del método (al igual que __func__.__doc__); __name__ es el nombre del método (al igual que __func__.__name__); __module__ es el nombre del módulo en el que el método fue definido, o None si no se encuentra disponible.

Los métodos también admiten obtener (más no establecer) los atributos arbitrarios de la función en el objeto de función subyacente.

Los objetos de métodos definidos por usuarios pueden ser creados al obtener el atributo de una clase (probablemente a través de la instancia de dicha clase), si tal atributo es el objeto de una función definida por el usuario o el objeto del método de una clase.

Cuando un objeto de instancia de método es creado al obtener un objeto de función definida por el usuario desde una clase a través de una de sus instancias, su atributo __self__ es la instancia, y el objeto de método se dice que está enlazado. El nuevo atributo de método __func__ es el objeto de función original.

Cuando un objeto de instancia de método es creado al obtener un objeto de método de clase a partir de una clase o instancia, su atributo __self__ es la clase misma, y su atributo __func__ es el objeto de función subyacente al método de la clase.

Cuando el objeto de la instancia de método es invocado, la función subyacente (__func__) es llamada, insertando la instancia de clase (__self__) delante de la lista de argumentos. Por ejemplo, cuando C es una clase que contiene la definición de una función f(), y x es una instancia de C, invocar x.f(1) es equivalente a invocar C.f(x, 1).

Cuando el objeto de instancia de método es derivado del objeto del método de clase, la “instancia de clase” almacenada en __self__ en realidad será la clase misma, de manera que invocar ya sea x.f(1)``o ``C.f(1) es equivalente a invocar f(C,1) donde f es la función subyacente.

Tome en cuenta que la transformación de objeto de función a objeto de método de instancia ocurre cada vez que el atributo es obtenido de la instancia. En algunos casos, una optimización fructífera es asignar el atributo a una variable local e invocarla. Note también que esta transformación únicamente ocurre con funciones definidas por usuario; otros objetos invocables (y todos los objetos no invocables) son obtenidos sin transformación. También es importante mencionar que las funciones definidas por el usuario, que son atributos de la instancia de una clase no son convertidos a métodos enlazados; esto ocurre únicamente cuando la función es un atributo de la clase.

Funciones generadoras

Una función o método que utiliza la declaración yield (ver sección La declaración yield) se llama generator function. Dicha función, cuando es invocada, siempre retorna un objeto iterador que puede ser utilizado para ejecutar el cuerpo de la función: invocando el método iterador iterator.__next__() hará que la función se ejecute hasta proporcionar un valor utilizando la declaración yield. Cuando la función ejecuta una declaración return o llega hasta el final, una excepción StopIteration es lanzada y el iterador habrá llegado al final del conjunto de valores a ser retornados.

Funciones de corrutina

Una función o método que es definido utilizando async def se llama coroutine function. Dicha función, cuando es invocada, retorna un objeto coroutine. Éste puede contener expresiones await, así como declaraciones async with y async for. Ver también la sección Objetos de Corrutina.

Funciones generadoras asincrónicas

Una función o método que es definido usando async def y que utiliza la declaración yield se llama asynchronous generator function. Dicha función, al ser invocada, retorna un objeto iterador asincrónico que puede ser utilizado en una declaración async for para ejecutar el cuerpo de la función.

Calling the asynchronous iterator’s aiterator.__anext__ method will return an awaitable which when awaited will execute until it provides a value using the yield expression. When the function executes an empty return statement or falls off the end, a StopAsyncIteration exception is raised and the asynchronous iterator will have reached the end of the set of values to be yielded.

Funciones incorporadas

Un objeto de función incorporada es un envoltorio (wrapper) alrededor de una función C. Ejemplos de funciones incorporadas son len() y math.sin() (math es un módulo estándar incorporado). El número y tipo de argumentos son determinados por la función C. Atributos especiales de solo lectura: __doc__ es la cadena de documentación de la función, o None si no se encuentra disponible; __name__ es el nombre de la función; __init__ es establecido como None (sin embargo ver el siguiente elemento); __module__ es el nombre del módulo en el que la función fue definida o None si no se encuentra disponible.

Métodos incorporados

Éste es realmente un disfraz distinto de una función incorporada, esta vez teniendo un objeto que se pasa a la función C como un argumento extra implícito. Un ejemplo de un método incorporado es alist.append(), asumiendo que alist es un objeto de lista. En este caso, el atributo especial de solo lectura __self__ es establecido al objeto indicado por alist.

Clases

Classes are callable. These objects normally act as factories for new instances of themselves, but variations are possible for class types that override __new__(). The arguments of the call are passed to __new__() and, in the typical case, to __init__() to initialize the new instance.

Instancias de clases

Instances of arbitrary classes can be made callable by defining a __call__() method in their class.

Módulos

Los módulos son una unidad básica organizacional en código Python, y son creados por el import system al ser invocados ya sea por la declaración import, o invocando funciones como importlib.import_module() y la incorporada __import__(). Un objeto de módulo tiene un espacio de nombres implementado por un objeto de diccionario (éste es el diccionario al que hace referencia el atributo de funciones __globals__ definido en el módulo). Las referencias de atributos son traducidas a búsquedas en este diccionario, p. ej., m.x es equivalente a m.__dict__[“x”]. Un objeto de módulo no contiene el objeto de código utilizado para iniciar el módulo (ya que no es necesario una vez que la inicialización es realizada).

La asignación de atributos actualiza el diccionario de espacio de nombres del módulo, p. ej., m.x = 1 es equivalente a m.__dict__[“x”] = 1.

Atributos predefinidos (escribibles): __name__ es el nombre del módulo; __doc__ es la cadena de documentación del módulo, o None si no se encuentra disponible; __annotations__ (opcional) es un diccionario que contiene variable annotations recolectado durante la ejecución del cuerpo del módulo; __file__ es el nombre de ruta del archivo en el cual el módulo fue cargado, si fue cargado desde un archivo. El atributo __file__ puede faltar para ciertos tipos de módulos, tal como módulos C que son vinculados estáticamente al intérprete; para módulos de extensión cargados dinámicamente desde una librería compartida, es el nombre de ruta del archivo de la librería compartida.

El atributo especial de solo lectura __dict__ es el espacio de nombres del módulo como un objeto de diccionario.

CPython implementation detail: Debido a la manera en la que CPython limpia los diccionarios de módulo, el diccionario de módulo será limpiado cuando el módulo se encuentra fuera de alcance, incluso si el diccionario aún tiene referencias existentes. Para evitar esto, copie el diccionario o mantenga el módulo cerca mientras usa el diccionario directamente.

Clases personalizadas

Los tipos de clases personalizadas son normalmente creadas por definiciones de clases (ver sección Definiciones de clase). Una clase tiene implementado un espacio de nombres por un objeto de diccionario. Las referencias de atributos de clase son traducidas a búsquedas en este diccionario, p. ej., C.x es traducido a C.__dict__[“x”] (aunque hay una serie de enlaces que permiten la ubicación de atributos por otros medios). Cuando el nombre de atributo no es encontrado ahí, la búsqueda de atributo continúa en las clases base. Esta búsqueda de las clases base utiliza la orden de resolución de métodos C3 que se comporta correctamente aún en la presencia de estructuras de herencia ‘diamante’ donde existen múltiples rutas de herencia que llevan a un ancestro común. Detalles adicionales en el MRO C3 utilizados por Python pueden ser encontrados en la documentación correspondiente a la versión 2.3 en https://www.python.org/download/releases/2.3/mro/.

Cuando la referencia de un atributo de clase (digamos, para la clase C) produce un objeto de método de clase, éste es transformado a un objeto de método de instancia cuyo atributo __self__ es C. Cuando produce un objeto de un método estático, éste es transformado al objeto envuelto por el objeto de método estático. Ver sección Implementando Descriptores para otra manera en la que los atributos obtenidos de una clase pueden diferir de los que en realidad están contenidos en su __dict__.

Las asignaciones de atributos de clase actualizan el diccionario de la clase, nunca el diccionario de la clase base.

Un objeto de clase puede ser invocado (ver arriba) para producir una instancia de clase (ver a continuación).

Atributos especiales: __name__ es el nombre de la clase; __module__ es el nombre del módulo en el que la clase fue definida; __dict__ es el diccionario que contiene el espacio de nombres de la clase; __bases__ es una tupla que contiene las clases base, en orden de ocurrencia en la lista de clases base; __doc__ es la cadena de documentación de la clase, o None si no está definida; __annotations__ (opcional) es un diccionario que contiene variable annotations recolectado durante la ejecución del cuerpo de la clase.

Instancias de clase

A class instance is created by calling a class object (see above). A class instance has a namespace implemented as a dictionary which is the first place in which attribute references are searched. When an attribute is not found there, and the instance’s class has an attribute by that name, the search continues with the class attributes. If a class attribute is found that is a user-defined function object, it is transformed into an instance method object whose __self__ attribute is the instance. Static method and class method objects are also transformed; see above under «Classes». See section Implementando Descriptores for another way in which attributes of a class retrieved via its instances may differ from the objects actually stored in the class’s __dict__. If no class attribute is found, and the object’s class has a __getattr__() method, that is called to satisfy the lookup.

Attribute assignments and deletions update the instance’s dictionary, never a class’s dictionary. If the class has a __setattr__() or __delattr__() method, this is called instead of updating the instance dictionary directly.

Instancias de clases pueden pretender ser números, secuencias o mapeos si tienen métodos con ciertos nombres especiales. Ver sección Nombres especiales de método.

Atributos especiales: __dict__ es el diccionario de atributos; __class__ es la clase de la instancia.

Objetos E/S (también conocidos como objetos de archivo)

Un file object representa un archivo abierto. Diversos accesos directos se encuentran disponibles para crear objetos de archivo: la función incorporada open(), así como os.popen(), os.fdopen(), y el método de objetos socket makefile() (y quizás por otras funciones y métodos proporcionados por módulos de extensión).

Los objetos sys.stdin, sys.stdout y sys.stderr son iniciados a objetos de archivos correspondientes a la entrada y salida estándar del intérprete, así como flujos de error; todos ellos están abiertos en el modo de texto y por lo tanto siguen la interface definida por la clase abstracta io.TextIOBase.

Tipos internos

Algunos tipos utilizados internamente por el intérprete son expuestos al usuario. Sus definiciones pueden cambiar en futuras versiones del intérprete, pero son mencionadas aquí para complementar.

Objetos de código

Los objetos de código representan código de Python ejecutable compilado por bytes, o bytecode. La diferencia entre un objeto de código y un objeto de función es que el objeto de función contiene una referencia explícita a los globales de la función (el módulo en el que fue definido), mientras el objeto de código no contiene contexto; de igual manera los valores por defecto de los argumentos son almacenados en el objeto de función, no en el objeto de código (porque representan valores calculados en tiempo de ejecución). A diferencia de objetos de función, los objetos de código son inmutables y no contienen referencias (directas o indirectas) a objetos mutables.

Atributos especiales de solo lectura: co_name da el nombre de la función; co_argcount es el número total de argumentos posicionales (incluyendo argumentos únicamente posicionales y argumentos con valores por default); co_posonlyargcount es el número de argumentos únicamente posicionales (incluyendo argumentos con valores por default); co_kwonlyargcountp es el número de argumentos solo de palabra clave (incluyendo argumentos con valores por default); co_nlocals es el número de variables usadas por la función (incluyendo argumentos); co_varnames es una tupla que contiene los nombres con las variables locales (empezando con los nombres de argumento); co_cellvars es una tupla que contiene los nombres de variables locales que son referenciadas por funciones anidadas; co_freevars es una tupla que contiene los nombres de variables libres; co_code es una cadena que representa la secuencia de instrucciones de bytecode; co_consts es una tupla que contiene las literales usadas por el bytecode; co_names es una tupla que contiene los nombres usados por el bytecode; co_filename es el nombre de archivo de donde el código fue compilado; co_firstlineno es el primer número de línea de la función; co_lnotab es una cadena codificando el mapeo desde el desplazamiento de bytecode al número de líneas (ver el código fuente del intérprete para más detalles); co_stacksize es el tamaño de pila requerido; co_flags es un entero codificando el número de banderas para el intérprete.

Los siguientes bits de bandera son definidos por co_flags : bit 0x04 es establecido si la función utiliza la sintaxis *arguments para aceptar un número arbitrario de argumentos posicionales; bit 0x08 es establecido si la función utiliza la sintaxis **keywords para aceptar argumentos de palabras clave arbitrarios; bit 0x20 es establecido si la función es un generador.

Declaraciones de características futuras (from __future__ import division) también utiliza bits en co_flags para indicar si el objeto de código fue compilado con alguna característica particular habilitada: el bit 0x2000 es establecido si la función fue compilada con división futura habilitada; los bits 0x10 y 0x1000 fueron utilizados en versiones previas de Python.

Otros bits en co_flags son reservados para uso interno.

Si un objeto de código representa una función, el primer elemento en co_consts es la cadena de documentación de la función, o None si no está definido.

Objetos de marco

Los objetos de marco representan marcos de ejecución. Pueden ocurrir en objetos de rastreo (ver a continuación), y son también pasados hacia funciones de rastreo registradas.

Atributos especiales de solo lectura: f_back es para el marco de pila anterior (hacia quien produce el llamado), o None si éste es el marco de pila inferior; f_code es el objeto de código ejecutado en este marco; f_locals es el diccionario utilizado para buscar variables locales; f_globals es usado por las variables globales; f_builtins es utilizado por nombres incorporados (intrínsecos); f_lasti da la instrucción precisa (éste es un índice dentro de la cadena de bytecode del objeto de código).

Accessing f_code raises an auditing event object.__getattr__ with arguments obj and "f_code".

Atributos especiales escribibles: f_trace, de lo contrario None, es una función llamada por distintos eventos durante la ejecución del código (éste es utilizado por el depurador). Normalmente un evento es desencadenado por cada una de las líneas fuente - esto puede ser deshabilitado estableciendo f_trace_lines a False.

Las implementaciones pueden permitir que eventos por código de operación sean solicitados estableciendo f_trace_opcodes a True. Tenga en cuenta que esto puede llevar a un comportamiento indefinido del intérprete si se levantan excepciones por la función de rastreo escape hacia la función que está siendo rastreada.

f_lineno es el número de línea actual del marco — escribiendo a esta forma dentro de una función de rastreo salta a la línea dada (solo para el último marco). Un depurador puede implementar un comando de salto (Jump) (también conocido como Set Next Statement) al escribir en f_lineno.

Objetos de marco soportan un método:

frame.clear()

Este método limpia todas las referencias a variables locales mantenidas por el marco. También, si el marco pertenecía a un generador, éste es finalizado. Esto ayuda a interrumpir los ciclos de referencia que involucran objetos de marco (por ejemplo al detectar una excepción y almacenando su rastro para uso posterior).

RuntimeError es lanzado si el marco se encuentra en ejecución.

Nuevo en la versión 3.4.

Objetos de seguimiento de pila (traceback)

Los objetos de seguimiento de pila representan el trazo de pila (stack trace) de una excepción. Un objeto de rastreo es creado de manera implícita cuando se da una excepción, y puede ser creada de manera explícita al llamar types.TracebackType.

Para seguimientos de pila (tracebacks) creados de manera implícita, cuando la búsqueda por un manejo de excepciones desenvuelve la pila de ejecución, en cada nivel de desenvolvimiento se inserta un objeto de rastreo al frente del rastreo actual. Cuando se entra a un manejo de excepción, la pila de rastreo se vuelve disponible para el programa. (Ver sección La sentencia try.) Es accesible como el tercer elemento de la tupla retornada por sys.exc_info(), y como el atributo __traceback__ de la excepción capturada.

Cuando el programa no contiene un gestor apropiado, el trazo de pila es escrito (muy bien formateado) a la secuencia de error estándar; si el intérprete es interactivo, también se vuelve disponible al usuario como sys.last_traceback.

Para seguimientos de pila creados de forma explícita, depende de su creador determinar cómo los atributos tb_next deberían ser ligados para formar un trazo de pila completo (full stack trace).

Atributos especiales de solo lectura: tb_frame apunta al marco de ejecución del nivel actual; tb_lineno da el número de línea donde ocurrió la excepción; tb_lasti indica la instrucción precisa. El número de línea y la última instrucción en el seguimiento de pila puede diferir del número de línea de su objeto de marco si la excepción ocurrió en una declaración try sin una cláusula de excepción (except) correspondiente o con una cláusula finally.

Accessing tb_frame raises an auditing event object.__getattr__ with arguments obj and "tb_frame".

Atributo especial escribible: tb_next es el siguiente nivel en el trazo de pila (hacia el marco en donde ocurrió la excepción), o None si no existe un siguiente nivel.

Distinto en la versión 3.7: Los objetos de seguimiento de pila ya pueden ser instanciados de manera explícita desde código de Python, y el atributo tb_next de instancias existentes puede ser actualizado.

Objetos de segmento (Slice objects)

Slice objects are used to represent slices for __getitem__() methods. They are also created by the built-in slice() function.

Atributos especiales de solo lectura: start es el límite inferior; stop es el límite superior; step es el valor de paso; cada uno es None si es omitido. Estos atributos pueden ser de cualquier tipo.

Los objetos de segmento soportan un método:

slice.indices(self, length)

Este método toma un argumento length de entero simple y calcula información relacionada con el segmento que el mismo describiría si fuera aplicado a una secuencia de elementos length. Retorna una tupla de tres enteros; respectivamente estos son los índices start y stop y el step o longitud del paso del segmento. Índices faltantes o fuera de los límites son manipulados de manera consistente con segmentos regulares.

Objetos de método estático

Los objetos de método estático proveen una forma de anular la transformación de objetos de función a objetos de método descritos anteriormente. Un objeto de método estático es una envoltura (wrapper) alrededor de cualquier otro objeto, usualmente un objeto de método definido por usuario. Cuando un objeto de método estático es obtenido desde una clase o una instancia de clase, usualmente el objeto retornado es el objeto envuelto, el cual no está objeto a ninguna transformación adicional. Los objetos de método estático no pueden ser llamados, aunque generalmente los objetos que estos envuelven sí. Los objetos de método estático son creados por el constructor incorporado staticmethod().

Objetos de método de clase

Un objeto de método de clase, igual que un objeto de método estático, es un envoltorio (wrapper) alrededor de otro objeto que altera la forma en la que el objeto es obtenido desde las clases y las instancias de clase. El comportamiento de los objetos de método de clase sobre tal obtención es descrita más arriba, debajo de “Métodos definidos por usuario”. Objetos de clase de método son creados por el constructor incorporado classmethod().

3.3. Nombres especiales de método

A class can implement certain operations that are invoked by special syntax (such as arithmetic operations or subscripting and slicing) by defining methods with special names. This is Python’s approach to operator overloading, allowing classes to define their own behavior with respect to language operators. For instance, if a class defines a method named __getitem__(), and x is an instance of this class, then x[i] is roughly equivalent to type(x).__getitem__(x, i). Except where mentioned, attempts to execute an operation raise an exception when no appropriate method is defined (typically AttributeError or TypeError).

Setting a special method to None indicates that the corresponding operation is not available. For example, if a class sets __iter__() to None, the class is not iterable, so calling iter() on its instances will raise a TypeError (without falling back to __getitem__()). 2

Cuando se implementa una clase que emula cualquier tipo incorporado, es importante que la emulación solo sea implementado al grado que hace sentido para el objeto que está siendo modelado. Por ejemplo, algunas secuencias pueden trabajar bien con la obtención de elementos individuales, pero extraer un segmento puede no tener mucho sentido. (Un ejemplo de esto es la interfaz NodeList, en el Modelo de Objetos del Documento del W3C.)

3.3.1. Personalización básica

object.__new__(cls[, ...])

Es llamado para crear una nueva instancia de clase cls. __new__() es un método estático (como un caso especial, así que no se necesita declarar como tal) que toma la clase de donde fue solicitada una instancia como su primer argumento. Los argumentos restantes son aquellos que se pasan a la expresión del constructor de objetos (para llamar a la clase). El valor retornado de __new__() deberá ser la nueva instancia de objeto (normalmente una instancia de cls).

Implementaciones típicas crean una nueva instancia de la clase invocando el método __new__() de la súper clase utilizando super().__new__(cls[, …]) con argumentos apropiados y después modificando la recién creada instancia como necesaria antes de retornarla.

If __new__() is invoked during object construction and it returns an instance of cls, then the new instance’s __init__() method will be invoked like __init__(self[, ...]), where self is the new instance and the remaining arguments are the same as were passed to the object constructor.

Si __new__() no retorna una instancia de cls, entonces el nuevo método __init__() de la instancia no será invocado.

__new__() es destinado principalmente para permitir a subclases de tipos inmutables (como int, str, o tuple) personalizar la creación de instancias. También es comúnmente anulado en metaclases personalizadas con el fin de personalizar la creación de clase.

object.__init__(self[, ...])

Llamado después de que la instancia ha sido creada (por __new__()), pero antes es retornada a quien produce la llamada. Los argumentos son aquellos pasados a la expresión del constructor de la clase. Si una clase base tiene un método __init__(), el método __init__() de clase derivada, de existir, debe llamarlo explícitamente para asegurar la inicialización apropiada de la clase base que es parte de la instancia; por ejemplo: super().__init__([args…]).

Debido a que __new__() y __init__() trabajan juntos construyendo objetos (__new__() para crearlo y __init__() para personalizarlo), ningún valor distinto a None puede ser retornado por __init__(); hacer esto puede causar que se lance una excepción TypeError en tiempo de ejecución.

object.__del__(self)

Llamado cuando la instancia es a punto de ser destruida. Esto también es llamado finalizador o (indebidamente) destructor. Si una clase base tiene un método __del__() el método __del__() de la clase derivada, de existir, debe llamarlo explícitamente para asegurar la eliminación adecuada de la parte de la clase base de la instancia.

Es posible (¡aunque no recomendable!) para el método __del__() posponer la destrucción de la instancia al crear una nueva referencia hacia ésta. Esto es llamado resurrección de objeto. Es dependiente de la implementación si __del__() es llamado una segunda vez cuando un objeto resucitado está por ser destruido; la implementación CPython actual únicamente lo llama una vez.

No está garantizado que los métodos __del__() sean llamados para objetos que aún existen cuando el intérprete se cierra.

Nota

del x no llama directamente x.__del__() — el primero disminuye el conteo de referencia para x uno por uno, y el segundo es llamado únicamente cuando el conteo de referencias de x llega a cero.

CPython implementation detail: It is possible for a reference cycle to prevent the reference count of an object from going to zero. In this case, the cycle will be later detected and deleted by the cyclic garbage collector. A common cause of reference cycles is when an exception has been caught in a local variable. The frame’s locals then reference the exception, which references its own traceback, which references the locals of all frames caught in the traceback.

Ver también

Documentación para el módulo gc.

Advertencia

Debido a las circunstancias inciertas bajo las que los métodos __del__() son invocados, las excepciones que ocurren durante su ejecución son ignoradas, y una advertencia es mostrada hacia sys.stderr. En particular:

__del__() puede ser invocado cuando código arbitrario es ejecutado, incluyendo el de cualquier hilo arbitrario. Si __del__() necesita realizar un cierre de exclusión mutua (lock) o invocar cualquier otro recurso que lo esté bloqueando, podría provocar un bloqueo muto (deadlock) ya que el recurso podría estar siendo utilizado por el código que se interrumpe al ejecutar __del__().

__del__() puede ser ejecutado durante el cierre del intérprete. Como consecuencia, las variables globales que necesita para acceder (incluyendo otros módulos) podrían haber sido borradas o establecidas a None. Python garantiza que los globales cuyo nombre comienza con un guión bajo simple sean borrados de su módulo antes que los globales sean borrados; si no existen otras referencias a dichas globales, esto puede ayudar asegurando que los módulos importados aún se encuentren disponibles al momento de llamar al método __del__().

object.__repr__(self)

Llamado por la función incorporada repr() para calcular la cadena “oficial” de representación de un objeto. Si es posible, esto debería verse como una expresión de Python válida que puede ser utilizada para recrear un objeto con el mismo valor (bajo el ambiente adecuado). Si no es posible, una cadena con la forma <…some useful description…> debe ser retornada. El valor de retorno debe ser un objeto de cadena (string). Si una clase define __repr__() pero no __str__(), entonces __repr__() también es utilizado cuando una cadena “informal” de representación de instancias de esas clases son requeridas.

Esto es típicamente utilizado para depurar, así que es importante que la representación sea rica en información e inequívoca.

object.__str__(self)

Llamado por str(object) y las funciones incorporadas format() y print() para calcular la “informal” o bien mostrada cadena de representación de un objeto. El valor de retorno debe ser un objeto string.

Este método difiere de object.__repr__() en que no hay expectativas de que __str__() retorne una expresión de Python válida: una representación más conveniente o concisa pueda ser utilizada.

La implementación por defecto definida por el tipo incorporado object llama a object.__repr__().

object.__bytes__(self)

Llamado por bytes para calcular la representación de la cadena de byte de un objeto. Este deberá retornar un objeto bytes.

object.__format__(self, format_spec)

Llamado por la función incorporada format(), y por extensión, la evaluación de formatted string literals y el método str.format(), para producir la representación “formateada” de un objeto. El argumento format_spec es una cadena que contiene una descripción de las opciones de formato deseadas. La interpretación del argumento format_spec depende del tipo que implementa __format__(), sin embargo, ya sea que la mayoría de las clases deleguen el formato a uno de los tipos incorporados, o utilicen una sintaxis de opción de formato similar.

Ver Especificación de formato Mini-Lenguaje para una descripción de la sintaxis de formato estándar.

El valor de retorno debe ser un objeto de cadena.

Distinto en la versión 3.4: El método __format__ del mismo object lanza un TypeError si se la pasa una cadena no vacía.

Distinto en la versión 3.7: object.__format__(x, ‘’) es ahora equivalente a str(x) en lugar de format(str(self), ‘’).

object.__lt__(self, other)

object.__le__(self, other)

object.__eq__(self, other)

object.__ne__(self, other)

object.__gt__(self, other)

object.__ge__(self, other)

Estos son los llamados métodos de comparación rich. La correspondencia entre símbolos de operador y los nombres de método es de la siguiente manera: x<y llama x.__lt__(y), x<=y llama x.__le__(y), x==y llama x.__eq__(y), x!=y llama x.__ne__(y), x>y llama x.__gt__(y), y x>=y llama x.__ge__(y).

Un método de comparación rich puede retornar el único NotImplemented si no implementa la operación para un par de argumentos dados. Por convención, False y True son retornados para una comparación exitosa. Sin embargo, estos métodos pueden retornar cualquier valor, así que si el operador de comparación es utilizado en un contexto Booleano (p. ej. en la condición de una sentencia if), Python llamará bool() en dicho valor para determinar si el resultado es verdadero (true) o falso (false).

Por defecto, object implementa __eq__() usando is, retornando NotImplemented en el caso de una comparación falsa: True if x is y else NotImplemented. Para __ne__(), por defecto delega a __eq__() e invierte el resultado a menos que sea NotImplemented. No hay otras relaciones implícitas entre los operadores de comparación o implementaciones predeterminadas; por ejemplo, la verdad de (x <y o x == y) no implica x <= y. Para generar automáticamente operaciones de pedido a partir de una sola operación raíz, consulte functools.total_ordering().

Ver el párrafo sobre __hash__() para más notas importantes sobre la creación de objetos hashable que soportan operaciones de comparación personalizadas y son utilizables como llaves de diccionario.

No existen versiones con argumento intercambiado de estos métodos (a ser utilizados cuando el argumento de la izquierda no soporta la operación pero el de la derecha sí); más bien, __lt__() y __gt__() son el reflejo del otro, __le__() y __ge__() son un reflejo del otro, y __eq__() y __ne__() son su propio reflejo. Si los operandos son de tipos distintos, y el tipo de operando de la derecha es una clase directa o indirecta del tipo de operando de la izquierda, el método reflejado del operando de la derecha tiene prioridad, de otro modo el método del operando de la izquierda tiene prioridad. Subclases virtuales no son consideradas.

object.__hash__(self)

Called by built-in function hash() and for operations on members of hashed collections including set, frozenset, and dict. The __hash__() method should return an integer. The only required property is that objects which compare equal have the same hash value; it is advised to mix together the hash values of the components of the object that also play a part in comparison of objects by packing them into a tuple and hashing the tuple. Example:

def __hash__(self):
    return hash((self.name, self.nick, self.color))

Nota

hash() trunca el valor retornado del método personalizado __hash__() del objeto al tamaño de Py_ssize_t. Esto normalmente son 8 bytes en estructuras de 64-bits y 4 bytes en estructuras de 32 bits. Si el __hash__() de un objeto debe interoperar en estructuras de tamaños de bits diferentes, asegúrese de revisar la amplitud en todas las estructuras soportadas. Una forma fácil de hacer esto es con python -c “import sys; print(sys.hash_info.width)”.

Si una clase no define un método __eq__(), tampoco debe definir una operación __hash__(); si define a __eq__() pero no a __hash__(), sus instancias no serán utilizables como elementos en colecciones hash. Si la clase define objetos mutables e implementa un método __eq__(), éste no deberá implementar __hash__(), ya que la implementación de colecciones hash requiere que la llave de un valor hash no sea mutable (si el valor del objeto hash cambia, estará en el cubo de hash equivocado).

Clases definidas por usuario tienen los métodos __eq__() y __hash__() por defecto; con ellos, todos los objetos se comparan de manera desigual (excepto con ellos mismos) y x.__hash__() retorna un valor apropiado tal que x == y implique que x es y y hash(x) == hash(y).

Una clase que anula __eq__() y no define __hash__() tendrá implícito su __hash__() establecido a None. Cuando el método __hash__() de una clase es None, instancias de la clase lanzarán un TypeError cuando el programa intente obtener el valor del hash, y también será correctamente identificado como de hash no calculable cuando se verifique isinstance(obj, collections.abc.Hashable).

Si una clase que anula __eq__() necesita conservar la implementación de __hash__() de una clase padre, al intérprete se le debe informar explícitamente estableciendo __hash__ = <ParentClass>.__hash__.

Si una clase que no anula __eq__() desea eliminar el soporte de hash, debe incluir __hash__ = None en la definición de clase. Una clase que define su propio __hash__() y que explícitamente lanza un TypeError será identificado de manera incorrecta como de hash calculable por una llamada isinstance(obj, collections.abc.Hashable).

Nota

Por defecto los valores de objetos str y bytes de __hash__() son “salados” con un valor aleatorio impredecible. Aunque se mantienen constantes dentro de un proceso Python particular, no son predecibles entre invocaciones repetidas de Python.

This is intended to provide protection against a denial-of-service caused by carefully-chosen inputs that exploit the worst case performance of a dict insertion, O(n²) complexity. See http://www.ocert.org/advisories/ocert-2011-003.html for details.

Cambiar los valores hash afectan el orden de la iteración de los sets. Python nunca ha dado garantías en relación a este orden (y típicamente varía entre estructuras de 32-bits y 64-bits).

Ver también PYTHONHASHSEED.

Distinto en la versión 3.3: La aleatorización de hash es habilitada por defecto.

object.__bool__(self)

Es llamado para implementar pruebas de valores de verdad y la operación incorporada bool(); debe retornar False o True. Cuando este método no es definido, __len__() es llamado, si es definido, y el objeto es considerado verdadero (true) si el resultado es diferente de zero. Si la clase no define __len__() ni __bool__(), todas sus instancias son consideradas verdaderas (true).

3.3.2. Personalizando acceso a atributos

Los siguientes métodos pueden ser definidos para personalizar el significado de acceso a atributos (uso de, asignación a, o borrado de x.name) para instancias de clase.

object.__getattr__(self, name)

Es llamado cuando el acceso a atributos por defecto falla con un AttributeError (ya sea que __getattribute__() lanza una excepción AttributeError porque name no es un atributo de instancia o un atributo en el árbol de clase para self; o el __get__() de la propiedad de name lanza una excepción AttributeError). Este método debe retornar el valor de atributo (calculado) o lanzar una excepción AttributeError.

Tome en cuenta que si el atributo es encontrado a través del mecanismo normal, __getattr__() no es llamado. (Esto es una desigualdad intencional entre __getattr__() y __setattr__().) Esto es realizado tanto por motivos de eficiencia y porque de otra manera __getattr__() no tendría manera de acceder a otros atributos de la instancia. Tome en cuenta que al menos para variables de instancia, se puede fingir control total al no insertar ningún valor en el diccionario de atributo de instancia (sino insertándolos en otro objeto). Ver el método __getattribute__() a continuación para una forma de tener control total sobre el acceso de atributo.

object.__getattribute__(self, name)

Es llamado incondicionalmente para implementar acceso de atributo por instancias de clase. Si la clase también define __getattr__(), éste no será llamado a menos que __getattribute__() lo llame de manera explícita o lance una excepción AttributeError. Este método deberá retornar el valor de atributo (calculado) o lanzar una excepción AttributeError. Para evitar la recursividad infinita en este método, su implementación deberá siempre llamar al método de la clase base con el mismo nombre para acceder cualquier atributo que necesite, por ejemplo, object.__getattribute__(self, name).

Nota

Este método aún puede ser sobrepasado cuando se buscan métodos especiales como resultado de una invocación implícita a través de sintaxis de lenguaje o funciones implícitas. Ver Búsqueda de método especial.

Lanza un evento de auditoría object.__getattr__ con argumentos obj, name.

object.__setattr__(self, name, value)

Es llamado cuando se intenta la asignación de atributos. Éste es llamado en lugar del mecanismo normal (p. ej. guardar el valor en el diccionario de instancias). name es el nombre de atributo, value es el valor que se le asigna.

Si __setattr__() quiere asignar a un atributo de instancia, debe llamar al método de la clase base con el mismo nombre, por ejemplo, object.__setattr__(self, name, value).

Lanza un evento de auditoría object.__setattr__ con argumentos obj, name, value.

object.__delattr__(self, name)

Al igual que __setattr__() pero para borrado de atributos en lugar de establecerlos. Esto solo de ser implementado si del obj.name es significativo para el objeto.

Lanza un evento de auditoría object.__delattr__ con argumentos obj, name.

object.__dir__(self)

Es llamado cuando dir() es llamado en el objeto. Una secuencia debe ser retornada. dir() convierte la secuencia retornada a una lista y la ordena.

3.3.2.1. Personalizando acceso a atributos de módulo

Nombres especiales __getattr__ y __dir__ también pueden ser utilizados para personalizar acceso a atributos de módulo. La función __getattr__ a nivel del módulo debe aceptar un argumento que es el nombre del atributo y retornar el valor calculado o lanzar una excepción AttributeError. Si un atributo no es encontrado en el objeto de módulo a través de una búsqueda normal, p. ej. object.__getattribute__(), entonces __getattr__ es buscado en el módulo __dict__ antes de lanzar una excepción AttributeError. Si es encontrado, es llamado con el nombre de atributo y el resultado es retornado.

La función __dir__ debe no aceptar argumentos y retornar una secuencia de cadena de caracteres que representan los nombres accesibles en el módulo. De existir, esta función anula la búsqueda estándar dir() en un módulo.

Para una personalización más precisa sobre el comportamiento del módulo (estableciendo atributos, propiedades, etc.), se puede establecer el atributo __class__ de un objeto de módulo a una subclase de types.ModuleType. Por ejemplo:

import sys
from types import ModuleType

class VerboseModule(ModuleType):
    def __repr__(self):
        return f'Verbose {self.__name__}'

    def __setattr__(self, attr, value):
        print(f'Setting {attr}...')
        super().__setattr__(attr, value)

sys.modules[__name__].__class__ = VerboseModule

Nota

Definiendo un módulo __getattr__ y estableciendo un módulo __class__ solo afecta búsquedas que utilizan la sintaxis de acceso a atributo – acceder directamente a las globales del módulo (ya sea por código dentro del módulo, o a través de una referencia al diccionario de globales del módulo) no se ve afectado.

Distinto en la versión 3.5: El atributo de módulo __class__ es ahora escribible.

Nuevo en la versión 3.7: Atributos de módulo __getattr__ y __dir__.

Ver también

PEP 562 [https://www.python.org/dev/peps/pep-0562] - Módulos __getattr__ y __dir__

Describe las funciones __getattr__ y __dir__ en módulos.

3.3.2.2. Implementando Descriptores

Los siguientes métodos solo aplican cuando una instancia de clase que contiene el método (llamado clase descriptora) aparece en una clase propietaria (el descriptor debe estar en el diccionario de clase del propietario o en el diccionario de clase de alguno de sus padres). En los ejemplos a continuación, “el atributo” se refiere al atributo cuyo nombre es la llave de la propiedad en la clase propietaria __dict__.

object.__get__(self, instance, owner=None)

Es llamado para obtener el atributo de la clase propietaria (acceso a atributos de clase) o de una instancia de dicha clase (acceso a atributos de instancia). El argumento opcional owner es la clase propietaria, mientras que instance es la instancia a través de la cual el atributo fue accedido, o None cuando el atributo es accedido a través de owner.

Este método debe retornar el valor de atributo calculado o lanzar una excepción AttributeError.

PEP 252 [https://www.python.org/dev/peps/pep-0252] especifica que __get__() puede ser llamado con uno o dos argumentos. Los propios descriptores incorporados de Python soportan esta especificación; sin embargo, es probable que algunas herramientas de terceros tengan descriptores que requieran ambos argumentos. La propia implementación de __getattribute__() en Python siempre pasa ambos argumentos si son requeridos o no.

object.__set__(self, instance, value)

Es llamado para establecer el atributo en una instancia instance de la clase propietaria a un nuevo valor value.

Nota, agregar __set__() o __delete__() cambia el tipo de descriptor a un “descriptor de datos”. Ver Invocando Descriptores para más detalles.

object.__delete__(self, instance)

Es llamado para borrar el atributo en una instancia instance de la clase propietaria.

object.__set_name__(self, owner, name)

Es llamado al momento en el que se crea la clase propietaria owner. El descriptor es asignado a name.

Nota

__set_name__() solo es llamado implícitamente como parte del constructor type, así que será necesario llamarlo explícitamente con los parámetros apropiados cuando un descriptor se agrega a la clase después de su creación inicial:

class A:
   pass
descr = custom_descriptor()
A.attr = descr
descr.__set_name__(A, 'attr')

Ver Creando el objeto de clase para más detalles.

Nuevo en la versión 3.6.

El atributo __objclass__ es interpretado por el módulo inspect como la especificación de la clase donde el objeto fue definido (establecer esto adecuadamente puede ayudar en introspección de atributos dinámicos de clases en tiempo de ejecución). Para invocables, puede indicar que una instancia de un tipo (o subclase) dado es esperado o requerido como el primero argumento posicional (por ejemplo, CPython establece este atributo para métodos independientes que son implementados en C).

3.3.2.3. Invocando Descriptores

In general, a descriptor is an object attribute with «binding behavior», one whose attribute access has been overridden by methods in the descriptor protocol: __get__(), __set__(), and __delete__(). If any of those methods are defined for an object, it is said to be a descriptor.

El comportamiento por defecto para atributos de acceso es obtener (get), establecer (set) o borrar (delete) el atributo del diccionario del objeto. Por ejemplo, a.x tiene una cadena de búsqueda que comienza con a.__dict__[‘x’], luego type(a).__dict__[‘x’], y continúa por las clases base de type(a) excluyendo metaclases.

Sin embargo, si el valor buscado es un objeto definiendo uno de los métodos del descriptor, entonces Python puede anular el comportamiento por defecto e invocar al método del descriptor en su lugar. Dónde ocurre esto en la cadena de precedencia depende de qué métodos de descriptor fueron definidos y cómo son llamados.

El punto de inicio por invocación de descriptor es un enlace a.x. Cómo los argumentos son ensamblados dependen de a:

Llamado Directo

El llamado más simple y menos común es cuando el código de usuario invoca directamente un método descriptor: x.__get__(a).

Enlace de Instancia

Al enlazar a una instancia de objeto, a es transformado en un llamado: type(a).__dict__[‘x’].__get__(a, type(a)).

Enlace de Clase

Al enlazar a una clase, A.x es transformado en un llamado: A.__dict__[‘x’].__get__(None, A).

Súper Enlace

If a is an instance of super, then the binding super(B, obj).m() searches obj.__class__.__mro__ for the base class A immediately following B and then invokes the descriptor with the call: A.__dict__['m'].__get__(obj, obj.__class__).

For instance bindings, the precedence of descriptor invocation depends on which descriptor methods are defined. A descriptor can define any combination of __get__(), __set__() and __delete__(). If it does not define __get__(), then accessing the attribute will return the descriptor object itself unless there is a value in the object’s instance dictionary. If the descriptor defines __set__() and/or __delete__(), it is a data descriptor; if it defines neither, it is a non-data descriptor. Normally, data descriptors define both __get__() and __set__(), while non-data descriptors have just the __get__() method. Data descriptors with __get__() and __set__() (and/or __delete__()) defined always override a redefinition in an instance dictionary. In contrast, non-data descriptors can be overridden by instances.

Python methods (including those decorated with @staticmethod and @classmethod) are implemented as non-data descriptors. Accordingly, instances can redefine and override methods. This allows individual instances to acquire behaviors that differ from other instances of the same class.

La función property() es implementada como un descriptor de datos. Por lo tanto, las instancias no pueden anular el comportamiento de una propiedad.

3.3.2.4. __slots__

__slots__ allow us to explicitly declare data members (like properties) and deny the creation of __dict__ and __weakref__ (unless explicitly declared in __slots__ or available in a parent.)

The space saved over using __dict__ can be significant. Attribute lookup speed can be significantly improved as well.

object.__slots__

This class variable can be assigned a string, iterable, or sequence of strings with variable names used by instances. __slots__ reserves space for the declared variables and prevents the automatic creation of __dict__ and __weakref__ for each instance.

3.3.2.4.1. Notas sobre el uso de __slots__

When inheriting from a class without __slots__, the __dict__ and __weakref__ attribute of the instances will always be accessible.

Without a __dict__ variable, instances cannot be assigned new variables not listed in the __slots__ definition. Attempts to assign to an unlisted variable name raises AttributeError. If dynamic assignment of new variables is desired, then add '__dict__' to the sequence of strings in the __slots__ declaration.

Without a __weakref__ variable for each instance, classes defining __slots__ do not support weak references to its instances. If weak reference support is needed, then add '__weakref__' to the sequence of strings in the __slots__ declaration.

__slots__ are implemented at the class level by creating descriptors for each variable name. As a result, class attributes cannot be used to set default values for instance variables defined by __slots__; otherwise, the class attribute would overwrite the descriptor assignment.

The action of a __slots__ declaration is not limited to the class where it is defined. __slots__ declared in parents are available in child classes. However, child subclasses will get a __dict__ and __weakref__ unless they also define __slots__ (which should only contain names of any additional slots).

Si una clase define un espacio (slot) también definido en una clase base, la variable de instancia definida por el espacio de la clase base es inaccesible (excepto al obtener su descriptor directamente de la clase base). Esto hace que el significado del programa sea indefinido. En el futuro se podría agregar una verificación para prevenir esto.

__slots__ no vacíos no funcionan para clases derivadas de tipos incorporados de “longitud variable” como int, bytes y tuple.

Any non-string iterable may be assigned to __slots__.

If a dictionary is used to assign __slots__, the dictionary keys will be used as the slot names. The values of the dictionary can be used to provide per-attribute docstrings that will be recognised by inspect.getdoc() and displayed in the output of help().

__class__ assignment works only if both classes have the same __slots__.

Multiple inheritance with multiple slotted parent classes can be used, but only one parent is allowed to have attributes created by slots (the other bases must have empty slot layouts) - violations raise TypeError.

If an iterator is used for __slots__ then a descriptor is created for each of the iterator’s values. However, the __slots__ attribute will be an empty iterator.

3.3.3. Personalización de creación de clases

Whenever a class inherits from another class, __init_subclass__() is called on the parent class. This way, it is possible to write classes which change the behavior of subclasses. This is closely related to class decorators, but where class decorators only affect the specific class they’re applied to, __init_subclass__ solely applies to future subclasses of the class defining the method.

classmethod object.__init_subclass__(cls)

Este método es llamado siempre que la clase que lo contiene sea heredada. cls es entonces, la nueva subclase. Si se define como un método de instancia normal, éste es convertido de manera implícita a un método de clase.

Los argumentos de palabra clave que fueron dados a una nueva clase, son pasados a la clase __init_subclass__ del padre. Por temas de compatibilidad con otras clases que usan __init_subclass__, uno debería quitar los argumentos de palabra clave y pasar los otros a la clase base, como en:

class Philosopher:
    def __init_subclass__(cls, /, default_name, **kwargs):
        super().__init_subclass__(**kwargs)
        cls.default_name = default_name

class AustralianPhilosopher(Philosopher, default_name="Bruce"):
    pass

La implementación por defecto object.__init_subclass__ no hace nada, pero lanza un error si es llamado con cualquier argumento.

Nota

La sugerencia de metaclase metaclass es consumido por el resto de la maquinaria de tipos, y nunca se pasa a las implementaciones __init_subclass__. La clase meta actual (más que la sugerencia explícita) puede ser accedida como type(cls).

Nuevo en la versión 3.6.

3.3.3.1. Metaclases

Por defecto, las clases son construidas usando type(). El cuerpo de la clase es ejecutado en un nuevo espacio de nombres y el nombre de la clase es ligado de forma local al resultado de type(name, bases, namespace).

El proceso de creación de clase puede ser personalizado pasando el argumento de palabra clave metaclass en la línea de definición de la clase, o al heredar de una clase existente que incluya dicho argumento. En el siguiente ejemplo, ambos MyClass y MySubclass son instancias de Meta:

class Meta(type):
    pass

class MyClass(metaclass=Meta):
    pass

class MySubclass(MyClass):
    pass

Cualquier otro argumento de palabra clave que sea especificado en la definición de clase es pasado mediante todas las operaciones de metaclase descritas a continuación.

Cuando una definición de clase es ejecutada, los siguientes pasos ocurren:

Entradas de la Orden de Resolución de Método (MRU) son resueltas;

se determina la metaclase adecuada;

se prepara el espacio de nombres de clase;

se ejecuta el cuerpo de la clase;

se crea el objeto de clase.

3.3.3.2. Resolviendo entradas de la Orden de Resolución de Métodos (MRU)

Si una base que aparece en la definición de una clase no es una instancia de type, entonces el método __mro_entries__ se busca en ella. Si es encontrado, se llama con la tupla de bases originales. Este método debe retornar una tupla de clases que será utilizado en lugar de esta base. La tupla puede estar vacía, en cuyo caso la base original es ignorada.

Ver también

PEP 560 [https://www.python.org/dev/peps/pep-0560] - Soporte central para módulos de clasificación y tipos genéricos

3.3.3.3. Determinando la metaclase adecuada

La metaclase adecuada para la definición de una clase es determinada de la siguiente manera:

si no se dan bases ni metaclases explícitas, entonces se utiliza type();

si se da una metaclase explícita y no es una instancia de type(), entonces se utiliza directamente como la metaclase;

si se da una instancia de type() como la metaclase explícita, o se definen bases, entonces se utiliza la metaclase más derivada.

La metaclase más derivada es elegida de la metaclase especificada explícitamente (si existe) y de la metaclase (p. ej. type(cls)) de todas las clases base especificadas.

3.3.3.4. Preparando el espacio de nombres de la clase

Once the appropriate metaclass has been identified, then the class namespace is prepared. If the metaclass has a __prepare__ attribute, it is called as namespace = metaclass.__prepare__(name, bases, **kwds) (where the additional keyword arguments, if any, come from the class definition). The __prepare__ method should be implemented as a classmethod. The namespace returned by __prepare__ is passed in to __new__, but when the final class object is created the namespace is copied into a new dict.

Si la metaclase no tiene atributo __prepare__, entonces el espacio de nombres de clase es iniciado como un mapeo vacío ordenado.

Ver también

PEP 3115 [https://www.python.org/dev/peps/pep-3115] - Metaclases en Python 3000

Introduce el enlace de espacio de nombres __prepare__

3.3.3.5. Ejecutando el cuerpo de la clase

El cuerpo de la clase es ejecutado como exec(body, globals(), namespace) (aproximadamente). La diferencia clave con un llamado normal a exec() es que el alcance léxico permite que el cuerpo de la clase (incluyendo cualquier método) haga referencia a nombres de los alcances actuales y externos cuando la definición de clase sucede dentro de la función.

Sin embargo, aún cuando la definición de clase sucede dentro de la función, los métodos definidos dentro de la clase aún no pueden ver nombres definidos dentro del alcance de la clase. Variables de clase deben ser accedidas a través del primer parámetro de instancia o métodos de clase, o a través de la referencia al léxico implícito __class__ descrita en la siguiente sección.

3.3.3.6. Creando el objeto de clase

Una vez que el espacio de nombres de la clase ha sido poblado al ejecutar el cuerpo de la clase, el objeto de clase es creado al llamar metaclass(name, bases, namespace, **kwds) (las palabras clave adicionales que se pasan aquí, son las mismas que aquellas pasadas en __prepare__).

Este objeto de clase es el que será referenciado por la forma sin argumentos de super(). __class__ es una referencia de cierre implícita creada por el compilador si cualquier método en el cuerpo de una clase se refiere tanto a __class__ o super. Esto permite que la forma sin argumentos de super() identifique correctamente la clase definida en base al alcance léxico, mientras la clase o instancia que fue utilizada para hacer el llamado actual es identificado en base al primer argumento que se pasa al método.

CPython implementation detail: En CPython 3.6 y posterior, la celda __class__ se pasa a la metaclase como una entrada __classcell__ en el espacio de nombres de la clase. En caso de existir, esto debe ser propagado hacia el llamado type.__new__ para que la clase se inicie correctamente. No hacerlo resultará en un error RuntimeError en Python 3.8.

Cuando se utiliza la metaclase por defecto type, o cualquier otra metaclase que finalmente llama a type.__new__, los siguientes pasos de personalización adicional son invocados después de crear el objeto de clase:

primero, type.__new__ recolecta todos los descriptores en el espacio de nombres de la clase que definen un método __set_name__();

segundo, todos esos métodos __set_name__ son llamados con la clase definida y el nombre de un descriptor particular asignado;

finalmente, el enlace __init_subclass__() llama al padre inmediato de la nueva clase en su orden de resolución del método.

Después de que el objeto de clase es creado, se pasa al decorador de clase incluido en su definición (si existe) y el objeto resultante es enlazado en el espacio de nombres local como la clase definida.

Cuando una nueva clase es creada por type.__new__, el objeto proporcionado como el parámetro de espacio de nombres es copiado a un trazado ordenado y el objeto original es descartado. La nueva copia es envuelta en un proxy de solo lectura, que se convierte en el atributo __dict__ del objeto de clase.

Ver también

PEP 3135 [https://www.python.org/dev/peps/pep-3135] - Nuevo súper

Describe la referencia de cierre implícita __class__

3.3.3.7. Usos para metaclases

Los usos potenciales para metaclases son ilimitados. Algunas ideas que ya han sido exploradas incluyen enumeración, registros, revisión de interface, delegación automática, creación de propiedades automática, proxy, infraestructuras, y bloqueo/sincronización automática de recursos.

3.3.4. Personalizando revisiones de instancia y subclase

Los siguientes métodos son utilizados para anular el comportamiento por defecto de las funciones incorporadas isinstance() y issubclass().

En particular, la metaclase abc.ABCMeta implementa estos métodos para permitir la adición de Clases Base Abstractas (ABCs, por su nombre en inglés Abstract Base Clases) como “clases base virtuales” a cualquier clase o tipo (incluyendo tipos incorporados), incluyendo otros ABCs.

class.__instancecheck__(self, instance)

Retorna true si la instancia instance debe ser considerada una instancia (directa o indirecta) de clase class. De ser definida, es llamado para implementar isinstance(instance, class).

class.__subclasscheck__(self, subclass)

Retorna true si la subclase subclass debe ser considerada una subclase (directa o indirecta) de clase class. De ser definida, es llamado para implementar issubclass(subclass, class).

Tome en cuenta que estos métodos son buscados en el tipo (metaclase) de una clase. No pueden ser definidos como métodos de clase en la clase actual. Esto es consistente con la búsqueda de métodos especiales que son llamados en instancias, solo en este caso la instancia es por sí misma una clase.

Ver también

PEP 3119 [https://www.python.org/dev/peps/pep-3119] - Introducción a Clases Base Abstractas (Abstract Base Classes)

Incluye la especificación para personalizar el comportamiento de isinstance() y issubclass() a través de __instancecheck__() y __subclasscheck__(), con motivación para esta funcionalidad en el contexto de agregar Clases Base Abstractas (ver el módulo abc) al lenguaje.

3.3.5. Emulando tipos genéricos

When using type annotations, it is often useful to parameterize a generic type using Python’s square-brackets notation. For example, the annotation list[int] might be used to signify a list in which all the elements are of type int.

Ver también

PEP 484 [https://www.python.org/dev/peps/pep-0484] - Type Hints

Introducing Python’s framework for type annotations

Generic Alias Types

Documentation for objects representing parameterized generic classes

Genéricos, user-defined generics and typing.Generic

Documentation on how to implement generic classes that can be parameterized at runtime and understood by static type-checkers.

A class can generally only be parameterized if it defines the special class method __class_getitem__().

classmethod object.__class_getitem__(cls, key)

Retornar un objeto representando la especialización de una clase genérica por argumentos de tipo encontrados en key.

When defined on a class, __class_getitem__() is automatically a class method. As such, there is no need for it to be decorated with @classmethod when it is defined.

3.3.5.1. The purpose of __class_getitem__

The purpose of __class_getitem__() is to allow runtime parameterization of standard-library generic classes in order to more easily apply type hints to these classes.

To implement custom generic classes that can be parameterized at runtime and understood by static type-checkers, users should either inherit from a standard library class that already implements __class_getitem__(), or inherit from typing.Generic, which has its own implementation of __class_getitem__().

Custom implementations of __class_getitem__() on classes defined outside of the standard library may not be understood by third-party type-checkers such as mypy. Using __class_getitem__() on any class for purposes other than type hinting is discouraged.

3.3.5.2. __class_getitem__ versus __getitem__

Usually, the subscription of an object using square brackets will call the __getitem__() instance method defined on the object’s class. However, if the object being subscribed is itself a class, the class method __class_getitem__() may be called instead. __class_getitem__() should return a GenericAlias object if it is properly defined.

Presented with the expression obj[x], the Python interpreter follows something like the following process to decide whether __getitem__() or __class_getitem__() should be called:

from inspect import isclass

def subscribe(obj, x):
    """Return the result of the expression `obj[x]`"""

    class_of_obj = type(obj)

    # If the class of obj defines __getitem__,
    # call class_of_obj.__getitem__(obj, x)
    if hasattr(class_of_obj, '__getitem__'):
        return class_of_obj.__getitem__(obj, x)

    # Else, if obj is a class and defines __class_getitem__,
    # call obj.__class_getitem__(x)
    elif isclass(obj) and hasattr(obj, '__class_getitem__'):
        return obj.__class_getitem__(x)

    # Else, raise an exception
    else:
        raise TypeError(
            f"'{class_of_obj.__name__}' object is not subscriptable"
        )

In Python, all classes are themselves instances of other classes. The class of a class is known as that class’s metaclass, and most classes have the type class as their metaclass. type does not define __getitem__(), meaning that expressions such as list[int], dict[str, float] and tuple[str, bytes] all result in __class_getitem__() being called:

>>> # list has class "type" as its metaclass, like most classes:
>>> type(list)
<class 'type'>
>>> type(dict) == type(list) == type(tuple) == type(str) == type(bytes)
True
>>> # "list[int]" calls "list.__class_getitem__(int)"
>>> list[int]
list[int]
>>> # list.__class_getitem__ returns a GenericAlias object:
>>> type(list[int])
<class 'types.GenericAlias'>

However, if a class has a custom metaclass that defines __getitem__(), subscribing the class may result in different behaviour. An example of this can be found in the enum module:

>>> from enum import Enum
>>> class Menu(Enum):
...     """A breakfast menu"""
...     SPAM = 'spam'
...     BACON = 'bacon'
...
>>> # Enum classes have a custom metaclass:
>>> type(Menu)
<class 'enum.EnumMeta'>
>>> # EnumMeta defines __getitem__,
>>> # so __class_getitem__ is not called,
>>> # and the result is not a GenericAlias object:
>>> Menu['SPAM']
<Menu.SPAM: 'spam'>
>>> type(Menu['SPAM'])
<enum 'Menu'>

Ver también

PEP 560 [https://www.python.org/dev/peps/pep-0560] - Core Support for typing module and generic types

Introducing __class_getitem__(), and outlining when a subscription results in __class_getitem__() being called instead of __getitem__()

3.3.6. Emulando objetos que se pueden llamar

object.__call__(self[, args...])

Es llamado cuando la instancia es “llamada” como una función; si este método es definido, x(arg1, arg2, …) es una clave corta para x.__call__(arg1, arg2, …).

3.3.7. Emulando tipos de contenedores

The following methods can be defined to implement container objects. Containers usually are sequences (such as lists or tuples) or mappings (like dictionaries), but can represent other containers as well. The first set of methods is used either to emulate a sequence or to emulate a mapping; the difference is that for a sequence, the allowable keys should be the integers k for which 0 <= k < N where N is the length of the sequence, or slice objects, which define a range of items. It is also recommended that mappings provide the methods keys(), values(), items(), get(), clear(), setdefault(), pop(), popitem(), copy(), and update() behaving similar to those for Python’s standard dictionary objects. The collections.abc module provides a MutableMapping abstract base class to help create those methods from a base set of __getitem__(), __setitem__(), __delitem__(), and keys(). Mutable sequences should provide methods append(), count(), index(), extend(), insert(), pop(), remove(), reverse() and sort(), like Python standard list objects. Finally, sequence types should implement addition (meaning concatenation) and multiplication (meaning repetition) by defining the methods __add__(), __radd__(), __iadd__(), __mul__(), __rmul__() and __imul__() described below; they should not define other numerical operators. It is recommended that both mappings and sequences implement the __contains__() method to allow efficient use of the in operator; for mappings, in should search the mapping’s keys; for sequences, it should search through the values. It is further recommended that both mappings and sequences implement the __iter__() method to allow efficient iteration through the container; for mappings, __iter__() should iterate through the object’s keys; for sequences, it should iterate through the values.

object.__len__(self)

Es llamado para implementar la función incorporada len(). Debe retornar la longitud del objeto, un entero >= 0. También, un objeto que no define un método __bool__() y cuyo método __len__() retorna cero, es considerado como falso en un contexto booleano.

CPython implementation detail: En CPython, se requiere que la longitud sea como mucho sys.maxsize. Si la longitud es más grande que sys.maxsize algunas características (como len()) pueden lanzar una excepción OverflowError. Para prevenir lanzar una excepción OverflowError al validar la verdad de un valor, un objeto debe definir un método __bool__().

object.__length_hint__(self)

Es llamado para implementar operator.length_hint(). Debe retornar una longitud estimada para el objeto (que puede ser mayor o menor que la longitud actual). La longitud debe ser un entero >= 0. El valor de retorno también debe ser NotImplemented el cual es tratado de igual forma a que si el método __length_hint__ no existiera en absoluto. Este método es puramente una optimización y nunca es requerido para precisión.

Nuevo en la versión 3.4.

Nota

La segmentación se hace exclusivamente con los siguientes tres métodos. Un llamado como

a[1:2] = b

es traducido a

a[slice(1, 2, None)] = b

etcétera. Elementos faltantes de segmentos siempre son llenados con None.

object.__getitem__(self, key)

Called to implement evaluation of self[key]. For sequence types, the accepted keys should be integers and slice objects. Note that the special interpretation of negative indexes (if the class wishes to emulate a sequence type) is up to the __getitem__() method. If key is of an inappropriate type, TypeError may be raised; if of a value outside the set of indexes for the sequence (after any special interpretation of negative values), IndexError should be raised. For mapping types, if key is missing (not in the container), KeyError should be raised.

Nota

ciclos for esperan que una excepción IndexError sea lanzada para que índices ilegales permitan la detección adecuada del fin de una secuencia.

Nota

When subscripting a class, the special class method __class_getitem__() may be called instead of __getitem__(). See __class_getitem__ versus __getitem__ for more details.

object.__setitem__(self, key, value)

Es llamado para implementar la asignación a self[key]. Lo mismo con respecto a __getitem__(). Esto solo debe ser implementado para mapeos si los objetos permiten cambios a los valores de las llaves, o si nuevas llaves pueden ser añadidas, o para secuencias si los elementos pueden ser reemplazados. Las mismas excepciones deben ser lanzadas para valores de key inadecuados con respecto al método __getitem__().

object.__delitem__(self, key)

Es llamado para implementar el borrado de self[key]. Lo mismo con respecto a __getitem__(). Esto solo debe ser implementado para mapeos si los objetos permiten el borrado de llaves, o para secuencias si los elementos pueden ser eliminados de la secuencia. Las mismas excepciones deben ser lanzadas por valores de key inapropiados con respecto al método __getitem__().

object.__missing__(self, key)

Es llamado por dict.__getitem__() para implementar self[key] para subclases de diccionarios cuando la llave no se encuentra en el diccionario.

object.__iter__(self)

Este método es llamado cuando se requiere un iterador para un contenedor. Este método debe retornar un nuevo objeto iterador que pueda iterar todos los objetos del contenedor. Para mapeos, debe iterar sobre las llaves del contenedor.

Objetos iteradores también necesitan implementar este método; son requeridos para retornarse a sí mismos. Para mayor información sobre objetos iteradores, ver Tipos de iteradores.

object.__reversed__(self)

Es llamado (si existe) por la función incorporada reversed() para implementar una interacción invertida. Debe retornar un nuevo objeto iterador que itere sobre todos los objetos en el contenedor en orden inverso.

Si el método __reversed__() no es proporcionado, la función incorporada reversed() recurrirá a utilizar el protocolo de secuencia (__len__() y __getitem__()). Objetos que permiten el protocolo de secuencia deben únicamente proporcionar __reversed__() si no pueden proporcionar una implementación que sea más eficiente que la proporcionada por reversed().

Los operadores de prueba de pertenencia (in and not in) son normalmente implementados como una iteración sobre un contenedor. Sin embargo, los objetos de contenedor pueden proveer el siguiente método especial con una implementación más eficiente, que tampoco requiere que el objeto sea iterable.

object.__contains__(self, item)

Es llamado para implementar operadores de prueba de pertenencia. Deben retornar true si item se encuentra en self, de lo contrario false. Para objetos de mapeo, estos debe considerar las llaves del mapeo en lugar de los valores o los pares de llave-valor.

Para objetos que no definen __contains__(), la prueba de pertenencia primero intenta la iteración a través de __iter__(), y luego el antiguo protocolo de iteración de secuencia a través de __getitem__(), ver esta sección en la referencia del lenguaje.

3.3.8. Emulando tipos numéricos

Los siguientes métodos pueden ser definidos para emular objetos numéricos. Métodos que corresponden a operaciones que no son permitidas por el número particular implementado (por ejemplo, operaciones bit a bit para números no enteros) se deben dejar sin definir.

object.__add__(self, other)

object.__sub__(self, other)

object.__mul__(self, other)

object.__matmul__(self, other)

object.__truediv__(self, other)

object.__floordiv__(self, other)

object.__mod__(self, other)

object.__divmod__(self, other)

object.__pow__(self, other[, modulo])

object.__lshift__(self, other)

object.__rshift__(self, other)

object.__and__(self, other)

object.__xor__(self, other)

object.__or__(self, other)

Estos métodos son llamados para implementar las operaciones aritméticas binarias (+, -, *, @, /, //, %, divmod(), pow(), **, <<, >>, &, ^, |). Por ejemplo, para evaluar la expresión x + y, donde x es instancia de una clase que tiene un método __add__(), x.__add__(y) es llamado. El método __divmod__() debe ser el equivalente a usar __floordiv__() y __mod__(); no debe ser relacionado a __truediv__(). Se debe tomar en cuenta que __pow__() debe ser definido para aceptar un tercer argumento opcional si la versión ternaria de la función incorporada pow() es soportada.

Si alguno de esos métodos no permiten la operación con los argumentos suministrados, debe retornar NotImplemented.

object.__radd__(self, other)

object.__rsub__(self, other)

object.__rmul__(self, other)

object.__rmatmul__(self, other)

object.__rtruediv__(self, other)

object.__rfloordiv__(self, other)

object.__rmod__(self, other)

object.__rdivmod__(self, other)

object.__rpow__(self, other[, modulo])

object.__rlshift__(self, other)

object.__rrshift__(self, other)

object.__rand__(self, other)

object.__rxor__(self, other)

object.__ror__(self, other)

Estos métodos son llamados para implementar las operaciones aritméticas binarias (+, -, *, @, /, //, %, divmod(), pow(), **, <<, >>, &, ^, |) con operandos reflejados (intercambiados). Estas funciones son llamadas únicamente si el operando izquierdo no soporta la operación correspondiente 3 y los operandos son de tipos diferentes. 4 Por ejemplo, para evaluar la expresión x - y, donde y es instancia de una clase que tiene un método __rsub__(), y.__rsub__(x) es llamado si x.__sub__(y) retorna NotImplemented.

Se debe tomar en cuenta que la función ternaria pow() no intentará llamar a __rpow__() (las reglas de coerción se volverían demasiado complicadas).

Nota

Si el tipo del operando de la derecha es una subclase del tipo del operando de la izquierda y esa subclase proporciona el método reflejado para la operación, este método será llamado antes del método no reflejado del operando izquierdo. Este comportamiento permite que las subclases anulen las operaciones de sus predecesores.

object.__iadd__(self, other)

object.__isub__(self, other)

object.__imul__(self, other)

object.__imatmul__(self, other)

object.__itruediv__(self, other)

object.__ifloordiv__(self, other)

object.__imod__(self, other)

object.__ipow__(self, other[, modulo])

object.__ilshift__(self, other)

object.__irshift__(self, other)

object.__iand__(self, other)

object.__ixor__(self, other)

object.__ior__(self, other)

Estos métodos son llamados para implementar las asignaciones aritméticas aumentadas (+=, -=, *=, @=, /=, //=, %=, **=, <<=, >>=, &=, ^=, |=). Estos métodos deben intentar realizar la operación in-place (modificando self) y retornar el resultado (que puede, pero no tiene que ser self). Si un método específico no es definido, la asignación aumentada regresa a los métodos normales. Por ejemplo, si x es la instancia de una clase con el método __iadd__(), x += y es equivalente a x = x.__iadd__(y). De lo contrario x.__add__(y) y y.__radd__(x) se consideran al igual que con la evaluación de x + y. En ciertas situaciones, asignaciones aumentadas pueden resultar en errores no esperados (ver ¿Por qué hacer lo siguiente, a_tuple[i] += ['item'], lanza una excepción cuando la suma funciona?), pero este comportamiento es en realidad parte del modelo de datos.

Nota

Debido a un error en el mecanismo de envío de **=, una clase que define __ipow__() pero retorna NotImplemented no podría volver a x.__pow__(y) y y.__rpow__(x). Este error se corrigió en Python 3.10.

object.__neg__(self)

object.__pos__(self)

object.__abs__(self)

object.__invert__(self)

Es llamado para implementar las operaciones aritméticas unarias (-, +, abs() and ~).

object.__complex__(self)

object.__int__(self)

object.__float__(self)

Es llamado para implementar las funciones incorporadas complex(), int() y float(). Debe retornar un valor del tipo apropiado.

object.__index__(self)

Es llamado para implementar operator.index(), y cuando sea que Python necesite convertir sin pérdidas el objeto numérico a un objeto entero (tal como en la segmentación o slicing, o las funciones incorporadas bin(), hex() y oct()). La presencia de este método indica que el objeto numérico es un tipo entero. Debe retornar un entero.

Si __int__(), __float__() y __complex__() no son definidos, entonces todas las funciones incorporadas correspondientes int(), float() y complex() vuelven a __index__().

object.__round__(self[, ndigits])

object.__trunc__(self)

object.__floor__(self)

object.__ceil__(self)

Es llamado para implementar la función incorporada round() y las funciones math trunc(), floor() y ceil(). A menos que ndigits sea pasado a __round__() todos estos métodos deben retornar el valor del objeto truncado a Integral (normalmente int).

The built-in function int() falls back to __trunc__() if neither __int__() nor __index__() is defined.

3.3.9. Gestores de Contexto en la Declaración with

Un context manager es un objeto que define el contexto en tiempo de ejecución a ser establecido cuando se ejecuta una declaración with. El gestor de contexto maneja la entrada y la salida del contexto en tiempo de ejecución deseado para la ejecución del bloque de código. Los gestores de contexto son normalmente invocados utilizando la declaración with (descritos en la sección La sentencia with), pero también pueden ser utilizados al invocar directamente sus métodos.

Usos típicos de los gestores de contexto incluyen guardar y restablecer diversos tipos de declaraciones globales, bloquear y desbloquear recursos, cerrar archivos abiertos, etc.

Para más información sobre gestores de contexto, ver Tipos Gestores de Contexto.

object.__enter__(self)

Ingresa al contexto en tiempo de ejecución relacionado con este objeto. La declaración with ligará el valor de retorno de este método al objetivo especificado en cláusula as de la declaración, en caso de existir.

object.__exit__(self, exc_type, exc_value, traceback)

Sale del contexto en tiempo de ejecución relacionado a este objeto. Los parámetros describen la excepción que causa la salida del contexto. Si éste se termina sin excepción, los tres argumentos serán None.

Si se proporciona una excepción, y el método desea eliminarla (por ejemplo, prevenir que sea propagada), debe retornar un valor verdadero. De lo contrario, la excepción será procesada de forma normal al salir de este método.

Se debe tomar en cuenta que los métodos __exit__() no deben lanzar de nuevo la excepción que se pasa; esto es la responsabilidad de quien hace el llamado.

Ver también

PEP 343 [https://www.python.org/dev/peps/pep-0343] - La declaración “with”

La especificación, el antecedente, y los ejemplos para la declaración de Python with.

3.3.10. Búsqueda de método especial

Para clases personalizadas, invocaciones implícitas de métodos especiales solo están garantizados para trabajar correctamente si son definidos en un tipo de objeto, no en el diccionario de instancia del objeto. Ese comportamiento es la razón por la que el siguiente código lanza una excepción:

>>> class C:
...     pass
...
>>> c = C()
>>> c.__len__ = lambda: 5
>>> len(c)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: object of type 'C' has no len()

The rationale behind this behaviour lies with a number of special methods such as __hash__() and __repr__() that are implemented by all objects, including type objects. If the implicit lookup of these methods used the conventional lookup process, they would fail when invoked on the type object itself:

>>> 1 .__hash__() == hash(1)
True
>>> int.__hash__() == hash(int)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: descriptor '__hash__' of 'int' object needs an argument

Intentar invocar de manera incorrecta el método no ligado de una clase de esta forma a veces es denominado como ‘confusión de metaclase’, y se evita sobrepasando la instancia al buscar métodos especiales:

>>> type(1).__hash__(1) == hash(1)
True
>>> type(int).__hash__(int) == hash(int)
True

In addition to bypassing any instance attributes in the interest of correctness, implicit special method lookup generally also bypasses the __getattribute__() method even of the object’s metaclass:

>>> class Meta(type):
...     def __getattribute__(*args):
...         print("Metaclass getattribute invoked")
...         return type.__getattribute__(*args)
...
>>> class C(object, metaclass=Meta):
...     def __len__(self):
...         return 10
...     def __getattribute__(*args):
...         print("Class getattribute invoked")
...         return object.__getattribute__(*args)
...
>>> c = C()
>>> c.__len__()                 # Explicit lookup via instance
Class getattribute invoked
10
>>> type(c).__len__(c)          # Explicit lookup via type
Metaclass getattribute invoked
10
>>> len(c)                      # Implicit lookup
10

Bypassing the __getattribute__() machinery in this fashion provides significant scope for speed optimisations within the interpreter, at the cost of some flexibility in the handling of special methods (the special method must be set on the class object itself in order to be consistently invoked by the interpreter).

3.4. Corrutinas

3.4.1. Objetos Esperables

An awaitable object generally implements an __await__() method. Coroutine objects returned from async def functions are awaitable.

Nota

The generator iterator objects returned from generators decorated with types.coroutine() or asyncio.coroutine() are also awaitable, but they do not implement __await__().

object.__await__(self)

Debe retornar un iterator. Debe ser utilizado para implementar objetos awaitable. Por ejemplo, asyncio.Future implementa este método para ser compatible con la expresión await.

Nuevo en la versión 3.5.

Ver también

PEP 492 [https://www.python.org/dev/peps/pep-0492] para información adicional sobre objetos esperables.

3.4.2. Objetos de Corrutina

Coroutine objects are awaitable objects. A coroutine’s execution can be controlled by calling __await__() and iterating over the result. When the coroutine has finished executing and returns, the iterator raises StopIteration, and the exception’s value attribute holds the return value. If the coroutine raises an exception, it is propagated by the iterator. Coroutines should not directly raise unhandled StopIteration exceptions.

Las corrutinas también tienen los métodos mencionados a continuación, los cuales son análogos a los de los generadores. (ver Métodos generador-iterador). Sin embargo, a diferencia de los generadores, las corrutinas no soportan directamente iteración.

Distinto en la versión 3.5.2: Es un error RuntimeError esperar a una corrutina más de una vez.

coroutine.send(value)

Starts or resumes execution of the coroutine. If value is None, this is equivalent to advancing the iterator returned by __await__(). If value is not None, this method delegates to the send() method of the iterator that caused the coroutine to suspend. The result (return value, StopIteration, or other exception) is the same as when iterating over the __await__() return value, described above.

coroutine.throw(value)

coroutine.throw(type[, value[, traceback]])

Raises the specified exception in the coroutine. This method delegates to the throw() method of the iterator that caused the coroutine to suspend, if it has such a method. Otherwise, the exception is raised at the suspension point. The result (return value, StopIteration, or other exception) is the same as when iterating over the __await__() return value, described above. If the exception is not caught in the coroutine, it propagates back to the caller.

coroutine.close()

Causa que la corrutina misma se borre a sí misma y termine su ejecución. Si la corrutina es suspendida, este método primero delega a close(), si existe, del iterador que causó la suspensión de la corrutina. Luego lanza una excepción GeneratorExit en el punto de suspensión, causando que la corrutina se borre a sí misma. Finalmente, la corrutina es marcada como completada, aún si nunca inició.

Objetos de corrutina son cerrados automáticamente utilizando el proceso anterior cuando están a punto de ser destruidos.

3.4.3. Iteradores asíncronos

Un iterador asíncrono puede llamar código asíncrono en su método __anext__.

Iteradores asíncronos pueden ser utilizados en la declaración async for.

object.__aiter__(self)

Debe retornar un objeto de iterador asíncrono.

object.__anext__(self)

Debe retornar un esperable (awaitable) resultante en el siguiente valor del iterador. Debe levantar una excepción StopAsyncIteration cuando la iteración termina.

Un ejemplo de objeto iterable asíncrono:

class Reader:
    async def readline(self):
        ...

    def __aiter__(self):
        return self

    async def __anext__(self):
        val = await self.readline()
        if val == b'':
            raise StopAsyncIteration
        return val

Nuevo en la versión 3.5.

Distinto en la versión 3.7: Prior to Python 3.7, __aiter__() could return an awaitable that would resolve to an asynchronous iterator.

Starting with Python 3.7, __aiter__() must return an asynchronous iterator object. Returning anything else will result in a TypeError error.

3.4.4. Gestores de Contexto Asíncronos

Un gestor de contexto asíncrono es un gestor de contexto que puede suspender la ejecución en sus métodos __aenter__ y __aexit__.

Los gestores de contexto asíncronos pueden ser utilizados en una declaración async with.

object.__aenter__(self)

Semánticamente similar a __enter__(), siendo la única diferencia que debe retorna un esperable.

object.__aexit__(self, exc_type, exc_value, traceback)

Semánticamente similar a __exit__(), siendo la única diferencia que debe retornar un esperable.

Un ejemplo de una clase de gestor de contexto asíncrono:

class AsyncContextManager:
    async def __aenter__(self):
        await log('entering context')

    async def __aexit__(self, exc_type, exc, tb):
        await log('exiting context')

Nuevo en la versión 3.5.

Notas a pie de página

1

Es posible cambiar en algunos casos un tipo de objeto bajo ciertas circunstancias controladas. Generalmente no es buena idea, ya que esto puede llevar a un comportamiento bastante extraño de no ser tratado correctamente.

2

The __hash__(), __iter__(), __reversed__(), and __contains__() methods have special handling for this; others will still raise a TypeError, but may do so by relying on the behavior that None is not callable.

3

“No soporta” aquí significa que la clase no tiene tal método, o el método retorna NotImplemented. No establecer el método a None si se quiere forzar el retroceso al método reflejado del operando correcto—eso, por el contrario, tendrá un efecto opuesto de bloquear explícitamente dicho retroceso.

4

For operands of the same type, it is assumed that if the non-reflected method – such as __add__() – fails then the overall operation is not supported, which is why the reflected method is not called.

4. Modelo de ejecución

4.1. Estructura de un programa

Un programa de Python se construye a partir de bloques de código. Un block es una parte del texto del programa Python que se ejecuta como una unidad. Los siguientes son bloques: un módulo, un cuerpo de función y una definición de clase. Cada comando escrito de forma interactiva es un bloque. Un archivo de secuencia de comandos (un archivo proporcionado como entrada estándar al intérprete o especificado como un argumento de línea de comando para el intérprete) es un bloque de código. Un comando de secuencia de comandos (un comando especificado en la línea de comandos del intérprete con la opción: -c) es un bloque de código. Un módulo que se ejecuta como un script de nivel superior (como módulo __main__) desde la línea de comando usando un argumento -m también es un bloque de código. El argumento de cadena pasado a las funciones integradas eval() y exec() es un bloque de código.

Un bloque de código se ejecuta en un execution frame. Un marco contiene alguna información administrativa (que se usa para depuración) y determina dónde y cómo continuará la ejecución una vez que el bloque de código se haya completado.

4.2. Nombres y vínculos

4.2.1. Vinculación de nombres

Los Names refieren a objetos. Los nombres se introducen por las operaciones de vinculación de nombre (name binding operations).

Las siguientes construcciones vinculan nombres: parámetros formales a las funciones, declaraciones import, definiciones de función y de clase (éstas vinculan el nombre de la clase o función en el bloque de definición), y objetivos que son identificadores si ocurren en una asignación, encabezados de bucles for, o luego de as en una declaración with o una cláusula except. La declaración import de la forma from ... import * vincula todos los nombres definidos en el módulo importado, excepto aquellos que comienzan con un guión bajo. Esta forma solamente puede ser usada a nivel de módulo.

Un objetivo que aparece en una sentencia del también se considera vinculado para este propósito (aunque la semántica real es desvincular el nombre).

Cada declaración de asignación o importación ocurre dentro de un bloque determinado por una definición de clase o de función, o a nivel de módulo (el bloque de código de máximo nivel).

Si un nombre está vinculado en un bloque, es una variable local en ese bloque, salvo que sea declarado como nonlocal o global. Si un nombre está vinculado a nivel de módulo, es una variable global. (Las variables del bloque de código del módulo son locales y globales.) Si una variable se una en un bloque de código pero no está definida ahí, es una free variable.

Cada ocurrencia de un nombre en el texto del programa se refiere al binding de ese nombre, establecido por las siguientes reglas de resolución de nombres.

4.2.2. Resolución de nombres

Un scope define la visibilidad de un nombre en un bloque. Si una variable local se define en un bloque, su ámbito (scope) incluye ese bloque. Si la definición ocurre en un bloque de función, el ámbito se extiende a cualquier bloque contenido en el bloque en donde está la definición, a menos que uno de los bloques contenidos introduzca un vínculo diferente para el nombre.

Cuando un nombre es utilizado en un bloque de código, se resuelve utilizando el ámbito de cierre más cercano. El conjunto de todos esos ámbitos visibles para un bloque de código se llama el environment del bloque.

Cuando un nombre no se encuentra, se lanza una excepción NameError. Si el ámbito actual es una función, y el nombre se refiere a una variable local que todavía no ha sido vinculada a un valor en el punto en el que nombre es utilizado, se lanza una excepción UnboundLocalError. UnboundLocalError es una subclase de NameError.

Si una operación de vinculación de nombre ocurre en cualquier parte dentro de un bloque de código, todos los usos del nombre dentro de ese bloque son tratados como referencias al bloque actual. Esto puede llevar a errores cuando el nombre es utilizado dentro del bloque antes de su vinculación. Esta regla es sutil. Python carece de declaraciones y permite que las operaciones de vinculación de nombres ocurran en cualquier lugar dentro del bloque de código. Las variables locales de un bloque de código pueden determinarse buscando operaciones de vinculación de nombres en el texto completo del bloque.

If the global statement occurs within a block, all uses of the names specified in the statement refer to the bindings of those names in the top-level namespace. Names are resolved in the top-level namespace by searching the global namespace, i.e. the namespace of the module containing the code block, and the builtins namespace, the namespace of the module builtins. The global namespace is searched first. If the names are not found there, the builtins namespace is searched. The global statement must precede all uses of the listed names.

La declaración global tiene el mismo ámbito que una operación de vinculación de nombre en el mismo bloque. Si el ámbito de cierre más cercano para una variable libre contiene una declaración global, se trata a la variable libre como global.

La declaración nonlocal causa que los nombre correspondientes se refieran a variables previamente vinculadas en el ámbito de la función de cierre más cercano. Se lanza un SyntaxError en tiempo de compilación si el nombre dado no existe en ningún ámbito de las funciones dentro de las cuales está.

El espacio de nombres (namespace) para un módulo se crea automáticamente la primera vez que se importa el módulo. El módulo principal de un script siempre se llama __main__.

Los bloques de definición de clase y los argumentos para exec() y eval() son especiales en el contexto de la resolución de nombres. Una definición de clase es una declaración ejecutable que puede usar y definir nombres. Estas referencias siguen las reglas normales para la resolución de nombres con la excepción de que se buscan las variables locales no vinculadas en el espacio de nombres global. El espacio de nombres de la definición de clase se vuelve el diccionario de atributos de la clase. El ámbito de nombres definido en un bloque de clase está limitado a dicho bloque; no se extiende a los bloques de código de los métodos. Esto incluye las comprensiones y las expresiones generadoras (generator expressions), dado que están implementadas usando el alcance de función. Esto implica que lo siguiente fallará:

class A:
    a = 42
    b = list(a + i for i in range(10))

4.2.3. Integraciones y ejecución restringida

CPython implementation detail: Los usuarios no deberían tocar __builtins__; es un detalle de la implementación en sentido estricto. Los usuarios que quieran sobreescribir valores en los espacios de nombres incorporados deberían usar import con el módulo builtins y modificar sus atributos de un modo adecuado.

El espacio de nombres incorporado (builtin namespace) asociado a la ejecución de un bloque de código es encontrado buscando el nombre __builtins__ en su espacio de nombres global; debería ser un diccionario o un módulo (en este último caso, se usa el diccionario del módulo). Por defecto, en el módulo __main__, __builtins__ es el módulo builtins. En cualquier otro módulo, __builtins__ es un alias para el diccionario del propio módulo builtins.

4.2.4. Interacción con funcionalidades dinámicas

La resolución de variables libres sucede en tiempo de ejecución, no en tiempo de compilación. Esto significa que el siguiente código va a mostrar 42:

i = 10
def f():
    print(i)
i = 42
f()

Las funciones eval() y exec() no tienen acceso al entorno completo para resolver nombres. Los nombres pueden resolverse en los espacios de nombres locales y globales de la persona que llama. Las variables libres no se resuelven en el espacio de nombres adjunto más cercano, sino en el espacio de nombres global. 1 Las funciones exec() y eval() tienen argumentos opcionales para anular el espacio de nombres global y local. Si solo se especifica un espacio de nombres, se usa para ambos.

4.3. Excepciones

Las excepciones son un medio para salir del flujo de control normal de un bloque de código, para gestionar errores u otras condiciones excepcionales. Una excepción es lanzada (raised) en el momento en que se detecta el error; puede ser gestionada (handled) por el bloque de código que la rodea o por cualquier bloque de código que directa o indirectamente ha invocado al bloque de código en el que ocurrió el error.

El intérprete Python lanza una excepción cuando detecta un error en tiempo de ejecución (como una división por cero). Un programa Python también puede lanzar una excepción explícitamente, con la declaración raise. Los gestores de excepciones se especifican con la declaración try … except. La cláusula finally de tales declaraciones puede utilizarse para especificar código de limpieza que no es el que gestiona la excepción, sino que se ejecutará en cualquier caso, tanto cuando la excepción ha ocurrido en el código que la precede, como cuando esto no ha sucedido.

Python usa el modelo de gestión de errores de «terminación» (»termination»): un gestor de excepción puede descubrir qué sucedió y continuar la ejecución en un nivel exterior, pero no puede reparar la causa del error y reintentar la operación que ha fallado (excepto que se reingrese al trozo de código fallido desde su inicio).

Cuando una excepción no está gestionada en absoluto, el intérprete termina la ejecución del programa, o retorna a su bucle principal interactivo. En cualquier caso, imprime un seguimiento de pila, excepto cuando la excepción es SystemExit.

Exceptions are identified by class instances. The except clause is selected depending on the class of the instance: it must reference the class of the instance or a non-virtual base class thereof. The instance can be received by the handler and can carry additional information about the exceptional condition.

Nota

Los mensajes de excepción no forman parte de la API Python. Su contenido puede cambiar entre una versión de Python y la siguiente sin ningún tipo de advertencia; el código que corre bajo múltiples versiones del intérprete no debería basarse en estos mensajes.

Mira también la descripción de la declaración try en la sección La sentencia try, y la declaración raise en la sección La declaración raise.

Notas al pie

1

Esta limitación se da porque el código ejecutado por estas operaciones no está disponible en el momento en que se compila el módulo.

5. El sistema de importación

El código Python en un módulo obtiene acceso al código en otro módulo por el proceso de importarlo. La instrucción import es la forma más común de invocar la maquinaria de importación, pero no es la única manera. Funciones como importlib.import_module() y built-in __import__() también se pueden utilizar para invocar la maquinaria de importación.

La instrucción import combina dos operaciones; busca el módulo con nombre y, a continuación, enlaza los resultados de esa búsqueda a un nombre en el ámbito local. La operación de búsqueda de la instrucción import se define como una llamada a la función __import__(), con los argumentos adecuados. El valor retornado de __import__() se utiliza para realizar la operación de enlace de nombre de la instrucción import. Consulte la instrucción import para obtener los detalles exactos de esa operación de enlace de nombres.

Una llamada directa a __import__() realiza solo la búsqueda del módulo y, si se encuentra, la operación de creación del módulo. Aunque pueden producirse ciertos efectos secundarios, como la importación de paquetes primarios y la actualización de varias memorias caché (incluidas sys.modules), solo la instrucción import realiza una operación de enlace de nombres.

Cuando se ejecuta una instrucción import, se llama a la función estándar incorporada __import__(). Otros mecanismos para invocar el sistema de importación (como importlib.import_module()) pueden optar por omitir __import__() y utilizar sus propias soluciones para implementar la semántica de importación.

Cuando se importa un módulo por primera vez, Python busca el módulo y, si se encuentra, crea un objeto de módulo 1, inicializándolo. Si no se encuentra el módulo con nombre, se genera un ModuleNotFoundError. Python implementa varias estrategias para buscar el módulo con nombre cuando se invoca la maquinaria de importación. Estas estrategias se pueden modificar y ampliar mediante el uso de varios ganchos descritos en las secciones siguientes.

Distinto en la versión 3.3: El sistema de importación se ha actualizado para aplicar plenamente la segunda fase de PEP 302 [https://www.python.org/dev/peps/pep-0302]. Ya no hay ninguna maquinaria de importación implícita: todo el sistema de importación se expone a través de sys.meta_path. Además, se ha implementado la compatibilidad con paquetes de espacio de nombres nativos (consulte PEP 420 [https://www.python.org/dev/peps/pep-0420]).

5.1. importlib

El módulo importlib proporciona una API enriquecida para interactuar con el sistema de importación. Por ejemplo importlib.import_module() proporciona una API recomendada y más sencilla que la integrada __import__() para invocar la maquinaria de importación. Consulte la documentación de la biblioteca importlib para obtener más detalles.

5.2. Paquetes

Python sólo tiene un tipo de objeto módulo, y todos los módulos son de este tipo, independientemente de si el módulo está implementado en Python, C, o en cualquier otro lenguaje. Para ayudar a organizar los módulos y proporcionar una jerarquía de nombres, Python tiene un concepto de paquete.

Puedes pensar en los paquetes como los directorios de un sistema de archivos y en los módulos como archivos dentro de los directorios, pero no te tomes esta analogía demasiado literalmente, ya que los paquetes y los módulos no tienen por qué originarse en el sistema de archivos. Para los propósitos de esta documentación, usaremos esta conveniente analogía de directorios y archivos. Al igual que los directorios del sistema de archivos, los paquetes están organizados de forma jerárquica, y los paquetes pueden contener subpaquetes, así como módulos regulares.

Es importante tener en cuenta que todos los paquetes son módulos, pero no todos los módulos son paquetes. O dicho de otro modo, los paquetes son sólo un tipo especial de módulo. Específicamente, cualquier módulo que contenga un atributo __path__ se considera un paquete.

All modules have a name. Subpackage names are separated from their parent package name by a dot, akin to Python’s standard attribute access syntax. Thus you might have a package called email, which in turn has a subpackage called email.mime and a module within that subpackage called email.mime.text.

5.2.1. Paquetes regulares

Python define dos tipos de paquetes, paquetes regulares y paquetes de espacio de nombres. Los paquetes regulares son los paquetes tradicionales tal y como existían en Python 3.2 y anteriores. Un paquete regular se implementa típicamente como un directorio que contiene un archivo init__.py. Cuando se importa un paquete regular, este archivo __init__.py se ejecuta implícitamente, y los objetos que define están vinculados a nombres en el espacio de nombres del paquete. El archivo __init__.py puede contener el mismo código Python que puede contener cualquier otro módulo, y Python añadirá algunos atributos adicionales al módulo cuando se importe.

Por ejemplo, la siguiente disposición del sistema de archivos define un paquete parent de nivel superior con tres subpaquetes:

parent/
    __init__.py
    one/
        __init__.py
    two/
        __init__.py
    three/
        __init__.py

Importando parent.one se ejecutará implícitamente parent/__init__.py y parent/one/__init__.py. La importación posterior de parent.two o parent.three ejecutará parent/two/__init__.py y parent/three/__init__.py respectivamente.

5.2.2. Paquetes de espacio de nombres

Un paquete de espacio de nombres es un compuesto de varias porciones, donde cada porción contribuye con un subpaquete al paquete padre. Las porciones pueden residir en diferentes lugares del sistema de archivos. Las porciones también pueden encontrarse en archivos zip, en la red, o en cualquier otro lugar que Python busque durante la importación. Los paquetes de espacios de nombres pueden corresponder o no directamente a objetos del sistema de archivos; pueden ser módulos virtuales que no tienen una representación concreta.

Los paquetes de espacios de nombres no usan una lista ordinaria para su atributo __path__. En su lugar utilizan un tipo iterable personalizado que realizará automáticamente una nueva búsqueda de porciones de paquete en el siguiente intento de importación dentro de ese paquete si la ruta de su paquete padre (o sys.path` para un paquete de nivel superior) cambia.

Con los paquetes de espacio de nombres, no hay ningún archivo parent/__init__.py. De hecho, puede haber varios directorios padre encontrados durante la búsqueda de importación, donde cada uno de ellos es proporcionado por una parte diferente. Por lo tanto, padre/one no puede estar físicamente situado junto a padre/two. En este caso, Python creará un paquete de espacio de nombres para el paquete parent de nivel superior siempre que se importe él o uno de sus subpaquetes.

Consulte también PEP 420 [https://www.python.org/dev/peps/pep-0420] para conocer la especificación del paquete de espacio de nombres.

5.3. Buscando

Para comenzar la búsqueda, Python necesita el nombre totalmente calificado del módulo (o paquete, pero para los fines de esta discusión, la diferencia es irrelevante) que se está importando. Este nombre puede provenir de varios argumentos a la instrucción import, o de los parámetros de las funciones importlib.import_module() o __import__().

Este nombre se utilizará en varias fases de la búsqueda de importación, y puede ser la ruta de acceso punteada a un submódulo, por ejemplo, foo.bar.baz. En este caso, Python primero intenta importar foo, luego foo.bar, y finalmente foo.bar.baz. Si se produce un error en cualquiera de las importaciones intermedias, se genera un ModuleNotFoundError.

5.3.1. La caché del módulo

El primer lugar comprobado durante la búsqueda de importación es sys.modules. Esta asignación sirve como caché de todos los módulos que se han importado previamente, incluidas las rutas intermedias. Por lo tanto, si foo.bar.baz se importó previamente, sys.modules contendrá entradas para foo, foo.bar, y foo.bar.baz. Cada clave tendrá como valor el objeto de módulo correspondiente.

Durante la importación, el nombre del módulo se busca en sys.modules y si está presente, el valor asociado es el módulo que satisface la importación y el proceso se completa. Sin embargo, si el valor es None, se genera un ModuleNotFoundError. Si falta el nombre del módulo, Python continuará buscando el módulo.

sys.modules se puede escribir. La eliminación de una clave no puede destruir el módulo asociado (ya que otros módulos pueden contener referencias a él), pero invalidará la entrada de caché para el módulo con nombre, lo que hará que Python busque de nuevo el módulo con nombre en su próxima importación. La clave también se puede asignar a None, lo que obliga a la siguiente importación del módulo a dar como resultado un ModuleNotFoundError.

Tenga cuidado, sin embargo, como si mantiene una referencia al objeto module, invalide su entrada de caché en sys.modules y, a continuación, vuelva a importar el módulo con nombre, los dos objetos de módulo no serán los mismos. Por el contrario, importlib.reload() reutilizará el objeto de módulo same y simplemente reinicializará el contenido del módulo volviendo a ejecutar el código del módulo.

5.3.2. Buscadores y cargadores

Si el módulo con nombre no se encuentra en sys.modules, se invoca el protocolo de importación de Python para buscar y cargar el módulo. Este protocolo consta de dos objetos conceptuales, buscadores y cargadores. El trabajo de un buscador es determinar si puede encontrar el módulo con nombre utilizando cualquier estrategia que conozca. Los objetos que implementan ambas interfaces se conocen como importadores se retornan a sí mismos cuando descubren que pueden cargar el módulo solicitado.

Python incluye una serie de buscadores e importadores predeterminados. El primero sabe cómo localizar módulos integrados, y el segundo sabe cómo localizar módulos congelados. Un tercer buscador predeterminado busca módulos en import path. El import path es una lista de ubicaciones que pueden nombrar rutas del sistema de archivos o archivos zip. También se puede ampliar para buscar cualquier recurso localizable, como los identificados por las direcciones URL.

La maquinaria de importación es extensible, por lo que se pueden añadir nuevos buscadores para ampliar el alcance y el alcance de la búsqueda de módulos.

En realidad, los buscadores no cargan módulos. Si pueden encontrar el módulo con nombre, retornan un module spec, una encapsulación de la información relacionada con la importación del módulo, que la maquinaria de importación utiliza al cargar el módulo.

En las secciones siguientes se describe el protocolo para buscadores y cargadores con más detalle, incluido cómo puede crear y registrar otros nuevos para ampliar la maquinaria de importación.

Distinto en la versión 3.4: En versiones anteriores de Python, los buscadores retornaban cargadores directamente, mientras que ahora retornen especificaciones de módulo que contienen cargadores. Los cargadores todavía se utilizan durante la importación, pero tienen menos responsabilidades.

5.3.3. Ganchos de importación

La maquinaria de importación está diseñada para ser extensible; el mecanismo principal para esto son los ganchos de importación (import hooks). Hay dos tipos de ganchos de importación: meta hooks (meta ganchos) y import path hooks (ganchos de ruta de acceso de importación).

Los meta ganchos se llaman al inicio del procesamiento de importación, antes de que se haya producido cualquier otro procesamiento de importación, que no sea búsqueda de caché de sys.modules. Esto permite que los metaganchos reemplacen el procesamiento de sys.path, módulos congelados o incluso módulos integrados. Los meta ganchos se registran agregando nuevos objetos de buscador a sys.meta_path, como se describe a continuación.

Los ganchos de ruta de acceso de importación se invocan como parte del procesamiento sys.path (o package.__path__), en el punto donde se encuentra su elemento de ruta de acceso asociado. Los ganchos de ruta de acceso de importación se registran agregando nuevos invocables a sys.path_hooks como se describe a continuación.

5.3.4. La meta ruta (path)

Cuando el módulo con nombre no se encuentra en sys.modules, Python busca a continuación sys.meta_path, que contiene una lista de objetos buscadores de metarutas. Estos buscadores se consultan para ver si saben cómo manejar el módulo nombrado. Los buscadores de rutas de meta deben implementar un método llamado find_spec() que toma tres argumentos: un nombre, una ruta de importación y (opcionalmente) un módulo de destino. El buscador de metarutas puede usar cualquier estrategia que desee para determinar si puede manejar el módulo con nombre o no.

Si el buscador de metarutas sabe cómo controlar el módulo con nombre, retorna un objeto de especificación. Si no puede controlar el módulo con nombre, retorna None. Si el procesamiento de sys.meta_path llega al final de su lista sin retornar una especificación, se genera un ModuleNotFoundError. Cualquier otra excepción provocada simplemente se propaga hacia arriba, anulando el proceso de importación.

El método de los buscadores de metarutas de find_spec() se llama con dos o tres argumentos. El primero es el nombre completo del módulo que se está importando, por ejemplo foo.bar.baz. El segundo argumento son las entradas de ruta de acceso que se utilizarán para la búsqueda de módulos. Para los módulos de nivel superior, el segundo argumento es None, pero para submódulos o subpaquetes, el segundo argumento es el valor del atributo __path__ del paquete primario. Si no se puede tener acceso al atributo __path__ adecuado, se genera un ModuleNotFoundError. El tercer argumento es un objeto de módulo existente que será el destino de la carga más adelante. El sistema de importación pasa un módulo de destino solo durante la recarga.

La metaruta se puede recorrer varias veces para una sola solicitud de importación. Por ejemplo, suponiendo que ninguno de los módulos implicados ya se haya almacenado en caché, la importación de foo.bar.baz realizará primero una importación de nivel superior, llamando a mpf.find_spec("foo", None, None) en cada buscador de metarutas (mpf). Después de importar foo , foo.bar se importará atravesando la meta ruta por segunda vez, llamando a mpf.find_spec("foo.bar", foo.__path__, None). Una vez importado foo.bar, el recorrido final llamará a mpf.find_spec("foo.bar.baz", foo.bar.__path__, None).

Algunos buscadores de metarutas solo admiten importaciones de nivel superior. Estos importadores siempre retornarán None cuando se pase algo distinto de None como segundo argumento.

El valor predeterminado de Python sys.meta_path tiene tres buscadores de metarutas, uno que sabe cómo importar módulos integrados, uno que sabe cómo importar módulos congelados y otro que sabe cómo importar módulos desde un import path (es decir, el path based finder).

Distinto en la versión 3.4: El método find_spec() de los buscadores de metarutas de la ruta de acceso reemplazó find_module(), que ahora está en desuso. Aunque seguirá funcionando sin cambios, la maquinaria de importación sólo lo intentará si el buscador no implementa find_spec().

5.4. Cargando

Si se encuentra una especificación de módulo, la maquinaria de importación la utilizará (y el cargador que contiene) al cargar el módulo. Aquí está una aproximación de lo que sucede durante la porción de carga de la importación:

module = None
if spec.loader is not None and hasattr(spec.loader, 'create_module'):
    # It is assumed 'exec_module' will also be defined on the loader.
    module = spec.loader.create_module(spec)
if module is None:
    module = ModuleType(spec.name)
# The import-related module attributes get set here:
_init_module_attrs(spec, module)

if spec.loader is None:
    # unsupported
    raise ImportError
if spec.origin is None and spec.submodule_search_locations is not None:
    # namespace package
    sys.modules[spec.name] = module
elif not hasattr(spec.loader, 'exec_module'):
    module = spec.loader.load_module(spec.name)
    # Set __loader__ and __package__ if missing.
else:
    sys.modules[spec.name] = module
    try:
        spec.loader.exec_module(module)
    except BaseException:
        try:
            del sys.modules[spec.name]
        except KeyError:
            pass
        raise
return sys.modules[spec.name]

Tenga en cuenta los siguientes detalles:

Si hay un objeto de módulo existente con el nombre dado en sys.modules, la importación ya lo habrá retornado.

El módulo existirá en sys.modules antes de que el cargador ejecute el código del módulo. Esto es crucial porque el código del módulo puede (directa o indirectamente) importarse a sí mismo; agregándolo a sys.modules de antemano evita la recursividad sin límites en el peor de los casos y la carga múltiple en el mejor.

Si se produce un error en la carga, el módulo con errores – y solo el módulo con errores – se elimina de sys.modules. Cualquier módulo que ya esté en la caché de sys.modules y cualquier módulo que se haya cargado correctamente como efecto secundario, debe permanecer en la memoria caché. Esto contrasta con la recarga donde incluso el módulo que falla se deja en sys.modules.

Después de crear el módulo pero antes de la ejecución, la maquinaria de importación establece los atributos del módulo relacionados con la importación («_init_module_attrs» en el ejemplo de pseudocódigo anterior), como se resume en una sección posterior.

La ejecución del módulo es el momento clave de la carga en el que se rellena el espacio de nombres del módulo. La ejecución se delega por completo en el cargador, lo que llega a decidir qué se rellena y cómo.

El módulo creado durante la carga y pasado a exec_module() puede no ser el que se retorna al final de la importación 2.

Distinto en la versión 3.4: El sistema de importación se ha hecho cargo de las responsabilidades reutilizables de los cargadores. Estos fueron realizados previamente por el método importlib.abc.Loader.load_module().

5.4.1. Cargadores

Los cargadores de módulos proporcionan la función crítica de carga: ejecución del módulo. La maquinaria de importación llama al método importlib.abc.Loader.exec_module() con un único argumento, el objeto module que se va a ejecutar. Se omite cualquier valor retornado de exec_module().

Los cargadores deben cumplir los siguientes requisitos:

Si el módulo es un módulo Python (a diferencia de un módulo integrado o una extensión cargada dinámicamente), el cargador debe ejecutar el código del módulo en el espacio de nombres global del módulo (module.__dict__).

Si el cargador no puede ejecutar el módulo, debe generar un ImportError, aunque se propagará cualquier otra excepción provocada durante exec_module().

En muchos casos, el buscador y el cargador pueden ser el mismo objeto; en tales casos, el método find_spec() simplemente retornaría una especificación con el cargador establecido en self.

Los cargadores de módulos pueden optar por crear el objeto de módulo durante la carga mediante la implementación de un método create_module(). Toma un argumento, la especificación del módulo, y retorna el nuevo objeto de módulo que se usará durante la carga. create_module() no necesita establecer ningún atributo en el objeto module. Si el método retorna None, la maquinaria de importación creará el nuevo módulo en sí.

Nuevo en la versión 3.4: El método de cargadores create_module().

Distinto en la versión 3.4: El método load_module() fue reemplazado por exec_module() y la maquinaria de importación asumió todas las responsabilidades reutilizables de la carga.

Para la compatibilidad con los cargadores existentes, la maquinaria de importación utilizará el método de cargadores load_module() si existe y el cargador no implementa también exec_module(). Sin embargo, load_module() ha quedado obsoleto y los cargadores deben implementar exec_module() en su lugar.

El método load_module() debe implementar toda la funcionalidad de carga reutilizable descrita anteriormente, además de ejecutar el módulo. Se aplican todas las mismas restricciones, con algunas aclaraciones adicionales:

Si hay un objeto de módulo existente con el nombre dado en sys.modules, el cargador debe utilizar ese módulo existente. (De lo contrario, importlib.reload() no funcionará correctamente.) Si el módulo con nombre no existe en sys.modules, el cargador debe crear un nuevo objeto de módulo y agregarlo a sys.modules.

El módulo debe existir en sys.modules antes de que el cargador ejecute el código del módulo, para evitar la recursividad sin límites o la carga múltiple.

Si se produce un error en la carga, el cargador debe quitar los módulos que ha insertado en sys.modules, pero debe quitar solo los módulos con errores, y solo si el propio cargador ha cargado los módulos explícitamente.

Distinto en la versión 3.5: A DeprecationWarning se genera cuando se define exec_module() pero create_module() no lo es.

Distinto en la versión 3.6: Un ImportError se genera cuando exec_module() está definido, pero create_module() no lo es.

5.4.2. Submódulos

Cuando se carga un submódulo mediante cualquier mecanismo (por ejemplo, API importlib, las instrucciones import o import-from, o __import__()) integradas, se coloca un enlace en el espacio de nombres del módulo primario al objeto submodule. Por ejemplo, si el paquete spam tiene un submódulo foo, después de importar spam.foo, spam tendrá un atributo foo que está enlazado al submódulo. Supongamos que tiene la siguiente estructura de directorios:

spam/
    __init__.py
    foo.py

and spam/__init__.py has the following line in it:

from .foo import Foo

then executing the following puts name bindings for foo and Foo in the spam module:

>>> import spam
>>> spam.foo
<module 'spam.foo' from '/tmp/imports/spam/foo.py'>
>>> spam.Foo
<class 'spam.foo.Foo'>

Dadas las reglas de enlace de nombres familiares de Python, esto puede parecer sorprendente, pero en realidad es una característica fundamental del sistema de importación. La retención invariable es que si tiene sys.modules[`spam`] y sys.modules[`spam.foo`] (como lo haría después de la importación anterior), este último debe aparecer como el atributo foo de la primera.

5.4.3. Especificaciones del módulo

La maquinaria de importación utiliza una variedad de información sobre cada módulo durante la importación, especialmente antes de la carga. La mayor parte de la información es común a todos los módulos. El propósito de las especificaciones de un módulo es encapsular esta información relacionada con la importación por módulo.

El uso de una especificación durante la importación permite transferir el estado entre los componentes del sistema de importación, por ejemplo, entre el buscador que crea la especificación del módulo y el cargador que la ejecuta. Lo más importante es que permite a la maquinaria de importación realizar las operaciones de caldera de carga, mientras que sin una especificación de módulo el cargador tenía esa responsabilidad.

La especificación del módulo se expone como el atributo __spec__ en un objeto de módulo. Consulte ModuleSpec para obtener más información sobre el contenido de la especificación del módulo.

Nuevo en la versión 3.4.

5.4.4. Atributos de módulo relacionados con la importación

La máquina de importación rellena estos atributos en cada objeto de módulo durante la carga, en función de las especificaciones del módulo, antes de que el cargador ejecute el módulo.

__name__

El atributo __name__ debe establecerse en el nombre completo del módulo. Este nombre se utiliza para identificar de forma única el módulo en el sistema de importación.

__loader__

El atributo __loader__ debe establecerse en el objeto de cargador que utilizó la máquina de importación al cargar el módulo. Esto es principalmente para la introspección, pero se puede utilizar para la funcionalidad específica del cargador adicional, por ejemplo, obtener datos asociados con un cargador.

__package__

Se debe establecer el atributo __package__ del módulo. Su valor debe ser una cadena, pero puede ser el mismo valor que su __name__. Cuando el módulo es un paquete, su valor __package__ debe establecerse en su __name__. Cuando el módulo no es un paquete, __package__ debe establecerse en la cadena vacía para los módulos de nivel superior, o para los submódulos, en el nombre del paquete primario. Consulte PEP 366 [https://www.python.org/dev/peps/pep-0366] para obtener más detalles.

Este atributo se utiliza en lugar de __name__ para calcular importaciones relativas explícitas para los módulos principales, tal como se define en PEP 366 [https://www.python.org/dev/peps/pep-0366]. Se espera que tenga el mismo valor que __spec__.parent.

Distinto en la versión 3.6: Se espera que el valor de __package__ sea el mismo que __spec__.parent.

__spec__

El atributo __spec__ debe establecerse en la especificación de módulo que se utilizó al importar el módulo. Establecer __spec__ se aplica correctamente por igual a módulos inicializados durante el inicio del intérprete. La única excepción es __main__, donde __spec__ es establecido None en algunos casos.

Cuando __package__ no está definido, __spec__.parent se utiliza como reserva.

Nuevo en la versión 3.4.

Distinto en la versión 3.6: __spec__.parent se utiliza como reserva cuando __package__` no está definido.

__path__

Si el módulo es un paquete (normal o espacio de nombres), se debe establecer el atributo __path__ del objeto de módulo. El valor debe ser iterable, pero puede estar vacío si __path__ no tiene más importancia. Si __path__ no está vacío, debe producir cadenas cuando se itera. Más detalles sobre la semántica de __path__ se dan below.

Los módulos que no son de paquete no deben tener un atributo __path__.

__file__

__cached__

__file__ es opcional. Si se establece, el valor de este atributo debe ser una cadena. El sistema de importación puede optar por dejar __file__ sin establecer si no tiene un significado semántico (por ejemplo, un módulo cargado desde una base de datos).

Si se establece __file__, también puede ser apropiado establecer el atributo __cached__, que es la ruta de acceso a cualquier versión compilada del código (por ejemplo, archivo compilado por bytes). No es necesario que exista el archivo para establecer este atributo; la ruta de acceso puede simplemente apuntar a donde existiría el archivo compilado (consulte PEP 3147 [https://www.python.org/dev/peps/pep-3147]).

También es apropiado establecer __cached__ cuando __file__ no está establecido. Sin embargo, ese escenario es bastante atípico. En última instancia, el cargador es lo que hace uso de __file__ y/o __cached__. Por lo tanto, si un cargador puede cargar desde un módulo almacenado en caché pero no se carga desde un archivo, ese escenario atípico puede ser adecuado.

5.4.5. module.__path__

Por definición, si un módulo tiene un atributo __path__, es un paquete.

El atributo __path__ de un paquete se utiliza durante las importaciones de sus subpaquetes. Dentro de la maquinaria de importación, funciona de la misma manera que sys.path, es decir, proporcionando una lista de ubicaciones para buscar módulos durante la importación. Sin embargo, __path__ suele estar mucho más restringido que sys.path.

__path__ debe ser un iterable de cadenas, pero puede estar vacío. Las mismas reglas utilizadas para sys.path también se aplican a la __path__ de un paquete, y sys.path_hooks (descrito a continuación) se consultan al recorrer el __path__ de un paquete.

El archivo __init__.py de un paquete puede establecer o modificar el atributo __path__ del paquete, y esta era normalmente la forma en que los paquetes de espacio de nombres se implementaban antes de PEP 420 [https://www.python.org/dev/peps/pep-0420]. Con la adopción de PEP 420 [https://www.python.org/dev/peps/pep-0420], los paquetes de espacio de nombres ya no necesitan proporcionar archivos __init__.py que contienen solo el código de manipulación __path__; la máquina de importación establece automáticamente __path__ correctamente para el paquete de espacio de nombres.

5.4.6. Representación (Reprs) de módulos

De forma predeterminada, todos los módulos tienen un repr utilizable, sin embargo, dependiendo de los atributos establecidos anteriormente, y en las especificaciones del módulo, puede controlar más explícitamente el repr de los objetos de módulo.

Si el módulo tiene una especificación (__spec__), la maquinaria de importación intentará generar un repr a partir de él. Si eso falla o no hay ninguna especificación, el sistema de importación creará un repr predeterminado usando cualquier información disponible en el módulo. Intentará utilizar el module.__name__, module.__file__ y module.__loader__ como entrada en el repr, con valores predeterminados para cualquier información que falte.

Aquí están las reglas exactas utilizadas:

Si el módulo tiene un atributo __spec__, la información de la especificación se utiliza para generar el repr. Se consultan los atributos «name», «loader», «origin» y «has_location».

Si el módulo tiene un atributo __file__, se utiliza como parte del repr del módulo.

Si el módulo no tiene __file__ pero tiene un __loader__ que no es None, entonces el repr del cargador se utiliza como parte del repr del módulo.

De lo contrario, sólo tiene que utilizar el __name__ del módulo en el repr.

Distinto en la versión 3.4: El uso de loader.module_repr() ha quedado obsoleto y la máquina de importación utiliza ahora la especificación del módulo para generar un repr de módulo.

Para la compatibilidad con versiones anteriores de Python 3.3, el repr del módulo se generará llamando al método module_repr() del cargador, si se define, antes de probar cualquiera de los enfoques descritos anteriormente. Sin embargo, el método está en desuso.

5.4.7. Invalidación del código de bytes en caché

Antes de que Python cargue el código de bytes en caché de un archivo .pyc, verifica si el caché está actualizado con el archivo .py de origen. De forma predeterminada, Python hace esto almacenando la marca de tiempo y el tamaño de la última modificación de la fuente en el archivo de caché al escribirlo. En tiempo de ejecución, el sistema de importación valida el archivo de caché comprobando los metadatos almacenados en el archivo de caché con los metadatos de la fuente.

Python también admite archivos de caché «basados en hash», que almacenan un hash del contenido del archivo de origen en lugar de sus metadatos. Hay dos variantes de archivos .pyc` basados en hash: marcados y desmarcados. Para los archivos ``.pyc marcados basados en hash, Python valida el archivo de caché mediante el hash del archivo de origen y la comparación del hash resultante con el hash en el archivo de caché. Si se encuentra que un archivo de caché basado en hash comprobado no es válido, Python lo regenera y escribe un nuevo archivo de caché basado en hash comprobado. Para los archivos .pyc sin marcar en hash, Python simplemente asume que el archivo de caché es válido si existe. El comportamiento de validación de archivos basado en hash .pyc se puede invalidar con el indicador --check-hash-based-pycs.

Distinto en la versión 3.7: Se han añadido archivos .pyc basados en hash. Anteriormente, Python solo admitía la invalidación basada en la marca de tiempo de la caché del código de bytes.

5.5. El buscador basado en rutas

Como se mencionó anteriormente, Python viene con varios buscadores de meta rutas predeterminados. Uno de ellos, llamado el buscador path based finder (PathFinder), busca una import path, que contiene una lista de entradas de ruta. Cada entrada de ruta de acceso nombra una ubicación para buscar módulos.

El buscador basado en rutas en sí no sabe cómo importar nada. En su lugar, atraviesa las entradas de ruta individuales, asociando cada una de ellas con un buscador de entrada de ruta que sabe cómo manejar ese tipo particular de ruta de acceso.

El conjunto predeterminado de buscadores de entradas de ruta implementa toda la semántica para encontrar módulos en el sistema de archivos, controlando tipos de archivos especiales como el código fuente de Python (archivos `.py), el código de bytes de Python (archivos .pyc) y las bibliotecas compartidas (por ejemplo, archivos .so`). Cuando es compatible con el módulo zipimport en la biblioteca estándar, los buscadores de entradas de ruta de acceso predeterminados también controlan la carga de todos estos tipos de archivo (excepto las bibliotecas compartidas) desde zipfiles.

Las entradas de ruta de acceso no deben limitarse a las ubicaciones del sistema de archivos. Pueden hacer referencia a direcciones URL, consultas de base de datos o cualquier otra ubicación que se pueda especificar como una cadena.

El buscador basado en rutas proporciona enlaces y protocolos adicionales para que pueda ampliar y personalizar los tipos de entradas de ruta de acceso que se pueden buscar. Por ejemplo, si desea admitir entradas de ruta de acceso como direcciones URL de red, podría escribir un enlace que implemente la semántica HTTP para buscar módulos en la web. Este gancho (un al que se puede llamar) retornaría un path entry finder compatible con el protocolo descrito a continuación, que luego se utilizó para obtener un cargador para el módulo de la web.

Una palabra de advertencia: esta sección y la anterior utilizan el término finder, distinguiendo entre ellos utilizando los términos meta path finder y path entry finder. Estos dos tipos de buscadores son muy similares, admiten protocolos similares y funcionan de maneras similares durante el proceso de importación, pero es importante tener en cuenta que son sutilmente diferentes. En particular, los buscadores de meta path operan al principio del proceso de importación, como se indica en el recorrido sys.meta_path.

Por el contrario, los buscadores de entradas de ruta son en cierto sentido un detalle de implementación del buscador basado en rutas y, de hecho, si el buscador basado en rutas se eliminara de sys.meta_path, no se invocaría ninguna semántica del buscador de entradas de ruta.

5.5.1. Buscadores de entradas de ruta

El path based finder es responsable de encontrar y cargar módulos y paquetes de Python cuya ubicación se especifica con una cadena path entry. La mayoría de las ubicaciones de nombres de entradas de ruta de acceso en el sistema de archivos, pero no es necesario limitarlas a esto.

Como buscador de meta rutas, el buscador path based finder implementa el protocolo find_spec() descrito anteriormente, sin embargo, expone enlaces adicionales que se pueden usar para personalizar cómo se encuentran y cargan los módulos desde la ruta import path.

Tres variables son usadas por path based finder, sys.path, sys.path_hooks y sys.path_importer_cache. También se utilizan los atributos __path__ en los objetos de paquete. Estos proporcionan formas adicionales de personalizar la maquinaria de importación.

sys.path contiene una lista de cadenas que proporcionan ubicaciones de búsqueda para módulos y paquetes. Se inicializa a partir de la variable de entorno PYTHONPATH y varios otros valores predeterminados específicos de la instalación e implementación. Las entradas de sys.path pueden nombrar directorios en el sistema de archivos, archivos zip y potencialmente otras «ubicaciones» (consulte el módulo site) que se deben buscar para módulos, como direcciones URL o consultas de base de datos. Solo las cadenas y bytes deben estar presentes en sys.path; todos los demás tipos de datos se omiten. La codificación de las entradas de bytes viene determinada por los buscadores de entrada de ruta.

El buscador path based finder es un meta path finder, por lo que la maquinaria de importación comienza la búsqueda import path llamando al método find_spec() basado en la ruta de acceso, tal como se describió anteriormente. Cuando se proporciona el argumento path a find_spec(), será una lista de rutas de acceso de cadena para recorrer - normalmente el atributo __path__ de un paquete para una importación dentro de ese paquete. Si el argumento path es None, esto indica una importación de nivel superior y se utiliza sys.path.

El buscador basado en rutas de acceso recorre en iteración cada entrada de la ruta de búsqueda y, para cada una de ellas, busca un path entry finder adecuado (PathEntryFinder) para la entrada de ruta de acceso. Dado que esto puede ser una operación costosa (por ejemplo, puede haber sobrecargas de llamadas stat() para esta búsqueda), el buscador basado en rutas mantiene una ruta de acceso de asignación de caché entradas a los buscadores de entrada de ruta. Esta memoria caché se mantiene en sys.path_importer_cache (a pesar del nombre, esta caché almacena realmente objetos de buscador en lugar de limitarse a objetos importer). De esta manera, la costosa búsqueda de una ubicación en particular path entry path entry finder solo debe hacerse una vez. El código de usuario es libre de eliminar las entradas de caché de sys.path_importer_cache obligando al buscador basado en ruta de acceso a realizar de nuevo la búsqueda de entrada de ruta 3.

Si la entrada de ruta de acceso no está presente en la memoria caché, el buscador basado en rutas de acceso recorre en iteración cada llamada que se puede llamar en sys.path_hooks. Cada uno de los enlaces de ganchos de rutas de entrada en esta lista se llama con un solo argumento, la entrada de ruta de acceso que se va a buscar. Esta invocable puede retornar un path entry finder que puede controlar la entrada de ruta de acceso, o puede generar ImportError. Un ImportError es utilizado por el buscador basado en ruta para indicar que el gancho no puede encontrar un path entry finder para eso entrada de ruta. Se omite la excepción y la iteración import path continúa. El enlace debe esperar un objeto de rutas o bytes; la codificación de objetos bytes está hasta el enlace (por ejemplo, puede ser una codificación del sistema de archivos, UTF-8, o algo más), y si el gancho no puede decodificar el argumento, debe generar ImportError.

Si la iteración sys.path_hooks termina sin que se retorne ningún valor path entry finder, a continuación, el método de búsqueda basado en la ruta de acceso find_spec() almacenará None en sys.path_importer_cache (para indicar que no hay ningún buscador para esta entrada de ruta) y retornará None, lo que indica que este meta path finder no pudo encontrar el módulo.

Si un path entry finder is retornado por uno de los path entry hook invocables en sys.path_hooks, entonces el siguiente protocolo se utiliza para pedir al buscador una especificación de módulo, que luego se utiliza al cargar el módulo.

El directorio de trabajo actual, denotado por una cadena vacía, se controla de forma ligeramente diferente de otras entradas de sys.path. En primer lugar, si se encuentra que el directorio de trabajo actual no existe, no se almacena ningún valor en sys.path_importer_cache. En segundo lugar, el valor del directorio de trabajo actual se busca actualizado para cada búsqueda de módulo. En tercer lugar, la ruta de acceso utilizada para sys.path_importer_cache y retornada por importlib.machinery.PathFinder.find_spec() será el directorio de trabajo actual real y no la cadena vacía.

5.5.2. Buscadores de entradas de ruta

Para admitir las importaciones de módulos y paquetes inicializados y también para contribuir con partes a paquetes de espacio de nombres, los buscadores de entradas de ruta de acceso deben implementar el método importlib.abc.PathEntryFinder.find_spec().

importlib.abc.PathEntryFinder.find_spec`() toma dos argumentos: el nombre completo del módulo que se va a importar y el módulo de destino (opcional). find_spec() retorna una especificación completamente poblada para el módulo. Esta especificación siempre tendrá «cargador» establecido (con una excepción).

Para indicar a la maquinaria de importación que la especificación representa un espacio de nombres portion, el buscador de entrada de ruta establece «submodule_search_locations» en una lista que contiene la porción.

Distinto en la versión 3.4: find_spec() reemplazó a find_loader() y find_module(), los cuales ahora están en desuso, pero se utilizarán si find_spec() no está definido.

Los buscadores de entradas de ruta más antiguos pueden implementar uno de estos dos métodos en desuso en lugar de find_spec(). Los métodos todavía se respetan en aras de la compatibilidad con versiones anteriores. Sin embargo, si find_spec() se implementa en el buscador de entrada de ruta, se omiten los métodos heredados.

find_loader() toma un argumento, el nombre completo del módulo que se está importando. find_loader() devuelve una 2-tupla donde el primer elemento es el cargador y el segundo elemento es un espacio de nombres portion.

Para la compatibilidad con versiones anteriores con otras implementaciones del protocolo de importación, muchos buscadores de entradas de ruta de acceso también admiten el mismo método tradicional find_module() que admiten los buscadores de rutas de acceso meta. Sin embargo, nunca se llama a los métodos del buscador de entradas de ruta find_module() con un argumento path (se espera que registren la información de ruta adecuada desde la llamada inicial al enlace de ruta).

El método find_module() en los buscadores de entrada de ruta está en desuso, ya que no permite que el buscador de entradas de ruta de acceso aporte partes a paquetes de espacio de nombres. Si existen tanto find_loader() como find_module() en un buscador de entrada de ruta, el sistema de importación siempre llamará a find_loader() en lugar de find_module().

5.6. Reemplazando el sistema de importación estándar

El mecanismo más confiable para reemplazar todo el sistema de importación es eliminar el contenido predeterminado de sys.meta_path, sustituyéndolos por completo por un enlace de meta path personalizado.

Si es aceptable alterar únicamente el comportamiento de las declaraciones de importación sin afectar a otras API que acceden al sistema de importación, puede ser suficiente reemplazar la función incorporada __import__(). Esta técnica también puede emplearse a nivel de módulo para alterar únicamente el comportamiento de las declaraciones de importación dentro de ese módulo.

Para evitar selectivamente la importación de algunos módulos de un enlace al principio de la meta path (en lugar de deshabilitar completamente el sistema de importación estándar), es suficiente elevar ModuleNotFoundError directamente desde find_spec() en lugar de retornar None. Este último indica que la búsqueda de meta path debe continuar, mientras que la generación de una excepción termina inmediatamente.

5.7. Paquete Importaciones relativas

Las importaciones relativas utilizan puntos iniciales. Un único punto inicial indica una importación relativa, empezando por el paquete actual. Dos o más puntos iniciales indican una importación relativa a los elementos primarios del paquete actual, un nivel por punto después del primero. Por ejemplo, dado el siguiente diseño de paquete:

package/
    __init__.py
    subpackage1/
        __init__.py
        moduleX.py
        moduleY.py
    subpackage2/
        __init__.py
        moduleZ.py
    moduleA.py

En subpackage1/moduleX.py o subpackage1/__init__.py, las siguientes son importaciones relativas válidas:

from .moduleY import spam
from .moduleY import spam as ham
from . import moduleY
from ..subpackage1 import moduleY
from ..subpackage2.moduleZ import eggs
from ..moduleA import foo

Las importaciones absolutas pueden utilizar la sintaxis import <> o from <> import <>, pero las importaciones relativas solo pueden usar el segundo formulario; la razón de esto es que:

import XXX.YYY.ZZZ

debe exponer XXX. Yyy. ZZZ como una expresión utilizable, pero .moduleY no es una expresión válida.

5.8. Consideraciones especiales para __main__

El módulo __main__ es un caso especial relativo al sistema de importación de Python. Como se señaló elsewhere, el módulo __main__ se inicializa directamente al inicio del intérprete, al igual que sys y builtins. Sin embargo, a diferencia de esos dos, no califica estrictamente como un módulo integrado. Esto se debe a que la forma en que se inicializa __main__ depende de las marcas y otras opciones con las que se invoca el intérprete.

5.8.1. __main__.__spec__

Dependiendo de cómo se inicializa __main__, __main__.__spec__ se establece correctamente o en None.

Cuando Python se inicia con la opción -m, __spec__ se establece en la especificación de módulo del módulo o paquete correspondiente. __spec__ también se rellena cuando el módulo __main__ se carga como parte de la ejecución de un directorio, zipfile u otro sys.path entrada.

En los casos restantes __main__.__spec__ se establece en None, ya que el código utilizado para rellenar el __main__ no se corresponde directamente con un módulo importable:

mensaje interactivo

opción -c

ejecutando desde stdin

que se ejecuta directamente desde un archivo de código fuente o de código de bytes

Tenga en cuenta que __main__.__spec__ siempre es None en el último caso, incluso si el archivo técnicamente podría importarse directamente como un módulo en su lugar. Utilice el modificador -m si se desean metadatos de módulo válidos en __main__.

Tenga en cuenta también que incluso cuando __main__ corresponde a un módulo importable y __main__.__spec__ se establece en consecuencia, todavía se consideran módulos distinct. Esto se debe al hecho de que los bloques protegidos por las comprobaciones if __name__ == "__main__": solo se ejecutan cuando el módulo se utiliza para rellenar el espacio de nombres __main__, y no durante la importación normal.

5.9. Problemas sin resolver

XXX Sería muy agradable tener un diagrama.

XXX * (import_machinery.rst) ¿qué tal una sección dedicada sólo a los atributos de módulos y paquetes, tal vez ampliando o suplantando las entradas relacionadas en la página de referencia del modelo de datos?

XXX runpy, pkgutil, et al en el manual de la biblioteca deben obtener enlaces «Ver también» en la parte superior que apuntan a la nueva sección del sistema de importación.

XXX Añadir más explicación con respecto a las diferentes formas en que __main__ se inicializa?

XXX Añadir más información sobre las peculiaridades/trampas __main__ (es decir, copia de PEP 395 [https://www.python.org/dev/peps/pep-0395]).

5.10. Referencias

La maquinaria de importación ha evolucionado considerablemente desde los primeros días de Python. La especificación original para paquetes [https://www.python.org/doc/essays/packages/] todavía está disponible para leer, aunque algunos detalles han cambiado desde la escritura de ese documento.

La especificación original de sys.meta_path era PEP 302 [https://www.python.org/dev/peps/pep-0302], con posterior extensión en PEP 420 [https://www.python.org/dev/peps/pep-0420].

PEP 420 [https://www.python.org/dev/peps/pep-0420] introdujo paquetes de espacio de nombres para Python 3.3. PEP 420 [https://www.python.org/dev/peps/pep-0420] también introdujo el protocolo find_loader() como alternativa a find_module().

PEP 366 [https://www.python.org/dev/peps/pep-0366] describe la adición del atributo __package__ para las importaciones relativas explícitas en los módulos principales.

PEP 328 [https://www.python.org/dev/peps/pep-0328] introdujo importaciones relativas absolutas y explícitas e inicialmente propuestas __name__ para la semántica PEP 366 [https://www.python.org/dev/peps/pep-0366] eventualmente especificaría para __package__.

PEP 338 [https://www.python.org/dev/peps/pep-0338] define la ejecución de módulos como scripts.

PEP 451 [https://www.python.org/dev/peps/pep-0451] agrega la encapsulación del estado de importación por módulo en los objetos de especificación. También descargara la mayoría de las responsabilidades de los cargadores en la maquinaria de importación. Estos cambios permiten el desuso de varias API en el sistema de importación y también la adición de nuevos métodos a los buscadores y cargadores.

Notas al Pie de Pagina

1

Véase types. ModuleType.

2

La implementación de importlib evita usar el valor retornado directamente. En su lugar, obtiene el objeto module buscando el nombre del módulo en sys.modules. El efecto indirecto de esto es que un módulo importado puede sustituirse a sí mismo en sys.modules. Este es un comportamiento específico de la implementación que no se garantiza que funcione en otras implementaciones de Python.

3

En el código heredado, es posible encontrar instancias de imp. NullImporter en el sys.path_importer_cache. Se recomienda cambiar el código para usar None en su lugar. Consulte Portando código Python para obtener más detalles.

6. Expresiones

Este capítulo explica el significado de los elementos de expresiones en Python.

Notas de Sintaxis: En este y los siguientes capítulos será usada notación BNF extendida para describir sintaxis, no análisis léxico. Cuando (una alternativa de) una regla de sintaxis tiene la forma

name ::=  othername

y no han sido dadas semánticas, las semánticas de esta forma de name son las mismas que para othername.

6.1. Conversiones aritméticas

Cuando una descripción de un operador aritmético a continuación usa la frase «los argumentos numéricos son convertidos a un tipo común», esto significa que la implementación de operador para tipos incorporados funciona de la siguiente forma:

Si cualquiera de los argumentos es un número complejo, el otro es convertido a complejo;

de otra forma, si cualquier de los argumentos es un número de punto flotante, el otro es convertido a punto flotante;

de otra forma, ambos deben ser enteros y no se necesita conversión.

Algunas reglas adicionales aplican para ciertos operadores (ej., una cadena de caracteres como argumento a la izquierda del operador “%”). Las extensiones deben definir su comportamiento de conversión.

6.2. Átomos

Los átomos son los elementos más básicos de las expresiones. Los átomos más simples son identificadores o literales. Las formas encerradas en paréntesis, corchetes o llaves son también sintácticamente categorizadas como átomos. La sintaxis para átomos es:

atom      ::=  identifier | literal | enclosure
enclosure ::=  parenth_form | list_display | dict_display | set_display
               | generator_expression | yield_atom

6.2.1. Identificadores (Nombres)

Un identificador encontrándose como un átomo es un nombre. Vea la sección Identificadores y palabras clave para la definición léxica y la sección Nombres y vínculos para documentación de nombrar y vincular.

Cuando el nombre es vinculado a un objeto, la evaluación del átomo produce ese objeto. Cuando un nombre no es vinculado, un intento de evaluarlo genera una excepción NameError.

Alteración de nombre privado: Cuando un identificador que ocurre textualmente en una definición de clase comienza con dos o más caracteres de guión bajo y no termina en dos o más guiones bajos, es considerado un private name de esa clase. Los nombres privados son transformados a una forma más larga antes de que sea generado código para ellos. La transformación inserta el nombre de clase, con los guiones bajos iniciales eliminados y un solo guión bajo insertado, delante del nombre. Por ejemplo, el identificador __spam que se encuentra en una clase denominada Ham será transformado a _Ham__spam. Esta transformación es independiente del contexto sintáctico en el cual es usado el identificador. Si el nombre transformado es extremadamente largo (más largo que 255 caracteres), puede ocurrir el truncamiento definido por la implementación. Si el nombre de clase consiste únicamente de guiones bajos, no se realiza transformación.

6.2.2. Literales

Python soporta literales de cadenas de caracteres y bytes y varios literales numéricos:

literal ::=  stringliteral | bytesliteral
             | integer | floatnumber | imagnumber

La evaluación de un literal produce un objeto del tipo dado (cadena de caracteres, bytes, entero, número de punto flotante, número complejo) con el valor dado. El valor puede ser aproximado en el caso de literales de número de punto flotante e imaginarios (complejos). Vea la sección Literales para más detalles.

Todos los literales corresponden a tipos de datos inmutables y, por lo tanto, la identidad del objeto es menos importante que su valor. Múltiples evaluaciones de literales con el mismo valor (ya sea la misma ocurrencia en el texto del programa o una ocurrencia diferente) pueden obtener el mismo objeto o un objeto diferente con el mismo valor.

6.2.3. Formas entre paréntesis

Una forma entre paréntesis es una lista de expresiones opcionales encerradas entre paréntesis:

parenth_form ::=  "(" [starred_expression] ")"

Una expresión entre paréntesis produce lo que la lista de expresión produce: si la lista contiene al menos una coma, produce una tupla; en caso contrario, produce la única expresión que que forma la lista de expresiones.

Un par de paréntesis vacío producen un objeto de tupla vacío. Debido a que las tuplas son inmutables, se aplican las mismas reglas que aplican para literales (ej., dos ocurrencias de una tupla vacía puede o no producir el mismo objeto).

Note que las tuplas no son formadas por los paréntesis, sino más bien mediante el uso del operador de coma. La excepción es la tupla vacía, para la cual los paréntesis son requeridos – permitir «nada» sin paréntesis en expresiones causaría ambigüedades y permitiría que errores tipográficos comunes pasaran sin ser detectados.

6.2.4. Despliegues para listas, conjuntos y diccionarios

Para construir una lista, un conjunto o un diccionario, Python provee sintaxis especial denominada «despliegue», cada una de ellas en dos sabores:

los contenidos del contenedor son listados explícitamente o

son calculados mediante un conjunto de instrucciones de bucle y filtrado, denominadas una comprehension.

Los elementos comunes de sintaxis para las comprensiones son:

comprehension ::=  assignment_expression comp_for
comp_for      ::=  ["async"] "for" target_list "in" or_test [comp_iter]
comp_iter     ::=  comp_for | comp_if
comp_if       ::=  "if" or_test [comp_iter]

La comprensión consiste en una única expresión seguida por al menos una cláusula for y cero o más cláusulas for o if. En este caso, los elementos del nuevo contenedor son aquellos que serían producidos mediante considerar cada una de las cláusulas for o if un bloque, anidado de izquierda a derecha y evaluando la expresión para producir un elemento cada vez que se alcanza el bloque más interno.

Sin embargo, aparte de la expresión iterable en la cláusula for más a la izquierda, la comprensión es ejecutada en un alcance separado implícitamente anidado. Esto asegura que los nombres asignados a en la lista objetiva no se «filtren» en el alcance adjunto.

La expresión iterable en la cláusula más a la izquierda for es evaluada directamente en el alcance anidado y luego pasada como un argumento al alcance implícitamente anidado. Subsecuentes cláusulas for y cualquier condición de filtro en la cláusula for más a la izquierda no pueden ser evaluadas en el alcance adjunto ya que pueden depender de los valores obtenidos del iterable de más a la izquierda. Por ejemplo, [x*y for x in range(10) for y in range(x, x+10)].

Para asegurar que la comprensión siempre resulta en un contenedor del tipo apropiado, las expresiones yield y yield from están prohibidas en el alcance implícitamente anidado.

A partir de Python 3.6, en una función async def, una cláusula async for puede ser usada para iterar sobre un asynchronous iterator. Una comprensión en una función async def puede consistir en una cláusula for o async for siguiendo la expresión inicial, puede contener cláusulas adicionales for o async for y también pueden usar expresiones await. Si una comprensión contiene cláusulas async for o expresiones await es denominada una asynchronous comprehension. Una comprensión asincrónica puede suspender la ejecución de la función de corrutina en la cual aparece. Vea también PEP 530 [https://www.python.org/dev/peps/pep-0530].

Nuevo en la versión 3.6: Fueron introducidas las comprensiones asincrónicas.

Distinto en la versión 3.8: Prohibidas yield y yield from en el alcance implícitamente anidado.

6.2.5. Despliegues de lista

Un despliegue de lista es una serie de expresiones posiblemente vacía encerrada entre corchetes:

list_display ::=  "[" [starred_list | comprehension] "]"

Un despliegue de lista produce un nuevo objeto lista, el contenido se especifica por una lista de expresiones o una comprensión. Cuando se proporciona una lista de expresiones, sus elementos son evaluados desde la izquierda a la derecha y colocados en el objeto lista en ese orden. Cuando se proporciona una comprensión, la lista es construida desde los elementos resultantes de la comprensión.

6.2.6. Despliegues de conjuntos

Un despliegue de conjunto se denota mediante llaves y se distinguen de los despliegues de diccionarios por la ausencia de caracteres de doble punto separando claves y valores:

set_display ::=  "{" (starred_list | comprehension) "}"

Un despliegue de conjunto produce un nuevo objeto conjunto mutable, el contenido se especifica mediante una secuencia de expresiones o una comprensión. Cuando se proporciona una lista de expresiones separadas por comas, sus elementos son evaluados desde la izquierda a la derecha y añadidos al objeto de conjunto. Cuando se proporciona una comprensión, el conjunto es construido de los elementos resultantes de la comprensión.

Un conjunto vacío no puede ser construido con {}; este literal construye un diccionario vacío.

6.2.7. Despliegues de diccionario

Un despliegue de diccionario es una serie posiblemente vacía de pares clave/datos encerrados entre llaves:

dict_display       ::=  "{" [key_datum_list | dict_comprehension] "}"
key_datum_list     ::=  key_datum ("," key_datum)* [","]
key_datum          ::=  expression ":" expression | "**" or_expr
dict_comprehension ::=  expression ":" expression comp_for

Un despliegue de diccionario produce un nuevo objeto diccionario.

Si es dada una secuencia separada por comas de pares clave/datos, son evaluadas desde la izquierda a la derecha para definir las entradas del diccionario: cada objeto clave es usado como una clave dentro del diccionario para almacenar el dato correspondiente. Esto significa que puedes especificar la misma clave múltiples veces en la lista clave/datos y el valor final del diccionario para esa clave será la última dada.

Un doble asterisco ** denota dictionary unpacking. Su operando debe ser un mapping. Cada elemento de mapeo es añadido al nuevo diccionario. Valores más tardíos remplazan los valores ya establecidos para los pares clave/dato y para los desempaquetados de diccionario anteriores.

Nuevo en la versión 3.5: Desempaquetar en despliegues de diccionarios, originalmente propuesto por PEP 448 [https://www.python.org/dev/peps/pep-0448].

Una comprensión de diccionario, en contraste a las compresiones de lista y conjunto, necesita dos expresiones separadas con un caracter de doble punto seguido por las cláusulas usuales «for» e «if». Cuando la comprensión se ejecuta, los elementos resultantes clave y valor son insertados en el nuevo diccionario en el orden que son producidos.

Las restricciones de los tipos de los valores de clave son listados anteriormente en la sección Jerarquía de tipos estándar. (Para resumir, el tipo de la clave debe ser hashable, el cual excluye todos los objetos mutables.) No se detectan choques entre claves duplicadas; el último dato (textualmente el más a la derecha en el despliegue) almacenado para una clave dada prevalece.

Distinto en la versión 3.8: Antes de Python 3.8, en las comprensiones de diccionarios, el orden de evaluación de clave y valor no fue bien definido. En CPython, el valor fue evaluado antes de la clave. A partir de 3.8, la clave es evaluada antes que el valor, como fue propuesto por PEP 572 [https://www.python.org/dev/peps/pep-0572].

6.2.8. Expresiones de generador

Una expresión de generador es una notación compacta de generador en paréntesis:

generator_expression ::=  "(" expression comp_for ")"

Una expresión de generador produce un nuevo objeto generador. Su sintaxis es la misma que para las comprensiones, excepto que es encerrado en paréntesis en lugar de corchetes o llaves.

Las variables usadas en la expresión de generador son evaluadas perezosamente cuando se ejecuta el método __next__() para el objeto generador (de la misma forma que los generadores normales). Sin embargo, la expresión iterable en la cláusula for más a la izquierda es inmediatamente evaluada, de forma que un error producido por ella será emitido en el punto en el que se define la expresión de generador, en lugar de en el punto donde se obtiene el primer valor. Subsecuentes cláusulas for y cualquier condición en la cláusula for más a la izquierda no pueden ser evaluadas en el alcance adjunto, ya que puede depender de los valores obtenidos por el iterable de más a la izquierda. Por ejemplo: (x*y for x in range(10) for y in range(x, x+10)).

Los paréntesis pueden ser omitidos en ejecuciones con un solo argumento. Vea la sección Invocaciones para más detalles.

Para evitar interferir con la operación esperada de la expresión misma del generador, las expresiones yield y yield from están prohibidas en el generador definido implícitamente.

Si una expresión de generador contiene cláusulas async for o expresiones await, se ejecuta una asynchronous generator expression. Una expresión de generador asincrónica retorna un nuevo objeto de generador asincrónico, el cual es un iterador asincrónico (ver Iteradores asíncronos).

Nuevo en la versión 3.6: Las expresiones de generador asincrónico fueron introducidas.

Distinto en la versión 3.7: Antes de Python 3.7, las expresiones de generador asincrónico podrían aparecer sólo en corrutinas async def. Desde 3.7, cualquier función puede usar expresiones de generador asincrónico.

Distinto en la versión 3.8: Prohibidas yield y yield from en el alcance implícitamente anidado.

6.2.9. Expresiones yield

yield_atom       ::=  "(" yield_expression ")"
yield_expression ::=  "yield" [expression_list | "from" expression]

The yield expression is used when defining a generator function or an asynchronous generator function and thus can only be used in the body of a function definition. Using a yield expression in a function’s body causes that function to be a generator function, and using it in an async def function’s body causes that coroutine function to be an asynchronous generator function. For example:

def gen():  # defines a generator function
    yield 123

async def agen(): # defines an asynchronous generator function
    yield 123

Debido a sus efectos secundarios sobre el alcance contenedor, las expresiones yield no están permitidas como parte de los alcances implícitamente definidos usados para implementar comprensiones y expresiones de generador.

Distinto en la versión 3.8: Expresiones yield prohibidas en los ámbitos anidados implícitamente utilizados para implementar comprensiones y expresiones de generador.

Las funciones generadoras son descritas a continuación, mientras que las funciones generadoras asincrónicas son descritas separadamente en la sección Funciones generadoras asincrónicas.

Cuando una función generadora es invocada, retorna un iterador conocido como un generador. Este generador controla la ejecución de la función generadora. La ejecución empieza cuando uno de los métodos del generador es invocado. En ese momento, la ejecución procede a la primera expresión yield, donde es suspendida de nuevo, retornando el valor de expression_list al invocador del generador. Por suspendido, nos referimos a que se retiene todo el estado local, incluyendo los enlaces actuales de variables locales, el puntero de instrucción, la pila de evaluación interna y el estado de cualquier manejo de excepción. Cuando la ejecución se reanuda al invocar uno de los métodos del generador, la función puede proceder como si la expresión yield fuera sólo otra invocación externa. El valor de la expresión yield después de la reanudación depende del método que ha reanudado la ejecución. Si se usa __next__() (típicamente mediante un for o la función incorporada next()) entonces el resultado es None. De otra forma, si se usa send(), entonces el resultado será el valor pasado a ese método.

Todo este hace a las funciones generadores similar a las corrutinas; producen múltiples veces, tienen más de un punto de entrada y su ejecución puede ser suspendida. La única diferencia es que una función generadora no puede controlar si la ejecución debe continuar después de producir; el control siempre es transferido al invocador del generador.

Las expresiones yield están permitidas en cualquier lugar en un constructo try. Si el generador no es reanudado antes de finalizar (alcanzando un recuento de referencia cero o colectando basura), el método generador-iterador close() será invocado, permitiendo la ejecución de cualquier cláusula finally pendiente.

Cuando se usa yield from <expr>, la expresión proporcionada debe ser iterable. Los valores producidos al iterar ese iterable se pasan directamente al llamador de los métodos del generador actual. Cualquier valor pasado con send() y cualquier excepción pasada con throw() se pasan al iterador subyacente si tiene los métodos apropiados. Si este no es el caso, entonces send() generará AttributeError o TypeError, mientras que throw() solo generará la excepción pasada inmediatamente.

Cuando el iterador subyacente está completo, el atributo value de la instancia StopIteration generada se convierte en el valor de la expresión yield. Puede ser establecido explícitamente al generar StopIteration o automáticamente cuando el subiterador es un generador (retornando un valor del subgenerador).

Distinto en la versión 3.3: Añadido yield from <expr> para delegar el control de flujo a un subiterador.

Los paréntesis pueden ser omitidos cuando la expresión yield es la única expresión en el lado derecho de una sentencia de asignación.

Ver también

PEP 255 [https://www.python.org/dev/peps/pep-0255] - Generadores Simples

La propuesta para añadir generadores y la sentencia yield a Python.

PEP 342 [https://www.python.org/dev/peps/pep-0342] - Corrutinas mediante Generadores Mejorados

La propuesta para mejorar la API y la sintaxis de generadores, haciéndolos utilizables como corrutinas simples.

PEP 380 [https://www.python.org/dev/peps/pep-0380] - Sintaxis para Delegar a un Subgenerador

La propuesta para introducir la sintaxis yield_from, facilitando la delegación a subgeneradores.

PEP 525 [https://www.python.org/dev/peps/pep-0525]- Generadores Asincrónicos

La propuesta que expandió PEP 492 [https://www.python.org/dev/peps/pep-0492] añadiendo capacidades de generador a las funciones corrutina.

6.2.9.1. Métodos generador-iterador

Esta subsección describe los métodos de un generador iterador. Estos pueden ser usados para controlar la ejecución de una función generadora.

Tenga en cuenta que invocar cualquiera de los métodos de generador siguientes cuando el generador está todavía en ejecución genera una excepción ValueError.

generator.__next__()

Comienza la ejecución de una función generadora o la reanuda en la última expresión yield ejecutada. Cuando una función generadora es reanudada con un método __next__(), la expresión yield actual siempre evalúa a None. La ejecución entonces continúa a la siguiente expresión yield, donde el generador se suspende de nuevo y el valor de expression_list se retorna al invocador de __next__(). Si el generador termina sin producir otro valor, se genera una excepción StopIteration.

Este método es normalmente invocado implícitamente, por ejemplo, por un bucle for o por la función incorporada next().

generator.send(value)

Reanuda la ejecución y «envía» un valor dentro de la función generadora. El argumento value se convierte en el resultado de la expresión yield actual. El método send() retorna el siguiente valor producido por el generador o genera StopIteration si el generador termina sin producir otro valor. Cuando se ejecuta send() para comenzar el generador, debe ser invocado con None como el argumento, debido a que no hay expresión yield que pueda recibir el valor.

generator.throw(value)

generator.throw(type[, value[, traceback]])

Raises an exception at the point where the generator was paused, and returns the next value yielded by the generator function. If the generator exits without yielding another value, a StopIteration exception is raised. If the generator function does not catch the passed-in exception, or raises a different exception, then that exception propagates to the caller.

In typical use, this is called with a single exception instance similar to the way the raise keyword is used.

For backwards compatability, however, the second signature is supported, following a convention from older versions of Python. The type argument should be an exception class, and value should be an exception instance. If the value is not provided, the type constructor is called to get an instance. If traceback is provided, it is set on the exception, otherwise any existing __traceback__ attribute stored in value may be cleared.

generator.close()

Genera GeneratorExit en el punto donde la función generadora fue pausada. Si la función generadora termina sin errores, está ya cerrada o genera GeneratorExit (sin cazar la excepción), close retorna a su invocador. Si el generador produce un valor, se genera un RuntimeError. Si el generador genera cualquier otra excepción, es propagado al invocador. close() no hace nada si el generador ya fue terminado debido a una excepción o una salida normal.

6.2.9.2. Ejemplos

Aquí hay un ejemplo simple que demuestra el comportamiento de generadores y funciones generadoras:

>>> def echo(value=None):
...     print("Execution starts when 'next()' is called for the first time.")
...     try:
...         while True:
...             try:
...                 value = (yield value)
...             except Exception as e:
...                 value = e
...     finally:
...         print("Don't forget to clean up when 'close()' is called.")
...
>>> generator = echo(1)
>>> print(next(generator))
Execution starts when 'next()' is called for the first time.
1
>>> print(next(generator))
None
>>> print(generator.send(2))
2
>>> generator.throw(TypeError, "spam")
TypeError('spam',)
>>> generator.close()
Don't forget to clean up when 'close()' is called.

Para ejemplos usando yield from, ver PEP 380: Sintaxis para delegar en un subgenerador en «Qué es nuevo en Python.»

6.2.9.3. Funciones generadoras asincrónicas

La presencia de una expresión yield en una función o método definido usando async def adicionalmente define la función como una función asynchronous generator.

Cuando se invoca una función generadora asincrónica, retorna un iterador asincrónico conocido como un objeto generador asincrónico. Este objeto entonces controla la ejecución de la función generadora. Un objeto generador asincrónico se usa típicamente en una sentencia async for en una función corrutina análogamente a como sería usado un objeto generador en una sentencia for.

Invocar uno de los métodos de un generador asincrónico retorna un objeto awaitable y la ejecución comienza cuando este objeto es esperado. En ese momento, la ejecución avanza a la primera expresión yield, donde es suspendida de nuevo, retornando el valor de expression_list a la corrutina en espera. Como con un generador, la suspensión significa que todo el estado local es retenido, incluyendo los enlaces actuales de variables locales, el puntero de instrucción, la pila de evaluación interna y el estado de cualquier manejo de excepción. Cuando se reanuda la ejecución al espera al siguiente objeto retornado por los métodos del generador asincrónico, la función puede avanzar exactamente igual que si la expresión yield fuera otra invocación externa. El valor de la expresión yield después de la reanudación dependen del método que ha resumido la ejecución. Si se usa __anext__() entonces el resultado es None. De otra forma, si se usa asend(), entonces el resultado será el valor pasado a ese método.

En una función generadora asincrónica, las expresiones yield están permitidas en cualquier lugar de un constructo try. Sin embargo, si un generador asincrónico no es reanudado antes de finalizar (alcanzando un contador de referencia cero o recogiendo basura), entonces una expresión yield dentro de un constructo try podría fallar al ejecutar cláusulas finally pendientes. En este caso, es responsabilidad del bucle de eventos o del planificador ejecutando el generador asincrónico invocar el método aclose() del generador-iterador asincrónico y ejecutar el objeto corrutina resultante, permitiendo así la ejecución de cualquier cláusula finally pendiente.

Para encargarse de la finalización, un bucle de eventos debe definir una función finalizadora la cual toma un generador-iterador asincrónico y presumiblemente invoca aclose() y ejecuta la corrutina. Este finalizador puede ser registrado invocando sys.set_asyncgen_hooks(). Cuando es iterada por primera vez, un generador-iterador asincrónico almacenará el finalizador registrado para ser invocado en la finalización. Para un ejemplo de referencia de un método finalizador vea la implementación de asyncio.Loop.shutdown_asyncgens en Lib/asyncio/base_events.py [https://github.com/python/cpython/tree/3.9/Lib/asyncio/base_events.py].

La expresión yield from <expr> es un error de sintaxis cuando es usada en una función generadora asincrónica.

6.2.9.4. Métodos asincrónicos de generador-iterador

Esta subsección describe los métodos de un generador iterador asincrónico, los cuales son usados para controlar la ejecución de una función generadora.

coroutine agen.__anext__()

Retorna un esperable el cual, cuando corre, comienza a ejecutar el generador asincrónico o lo reanuda en la última expresión yield ejecutada. Cuando se reanuda una función generadora asincrónica con un método __anext__(), la expresión yield actual siempre evalúa a None en el esperable retornado, el cual cuando corre continuará a la siguiente expresión yield. El valor de expression_list de la expresión yield es el valor de la excepción StopIteration generada por la corrutina completa. Si el generador asincrónico termina sin producir otro valor, el esperable en su lugar genera una excepción StopAsyncIteration, señalando que la iteración asincrónica se ha completado.

Este método es invocado normalmente de forma implícita por un bucle async for.

coroutine agen.asend(value)

Retorna un esperable el cual cuando corre reanuda la ejecución del generador asincrónico. Como el método send() para un generador, este «envía» un valor a la función generadora asincrónica y el argumento value se convierte en el resultado de la expresión yield actual. El esperable retornado por el método asend() retornará el siguiente valor producido por el generador como el valor de la StopIteration generada o genera StopAsyncIteration si el generador asincrónico termina sin producir otro valor. Cuando se invoca asend() para empezar el generador asincrónico, debe ser invocado con None como argumento, porque no hay expresión yield que pueda recibir el valor.

coroutine agen.athrow(value)

coroutine agen.athrow(type[, value[, traceback]])

Retorna un esperable que genera una excepción de tipo type en el punto donde el generador asincrónico fue pausado y retorna el siguiente valor producido por la función generadora como el valor de la excepción StopIteration generada. Si el generador asincrónico termina sin producir otro valor, el esperable genera una excepción StopAsyncIteration. Si la función generadora no caza la excepción pasada o genera una excepción diferente, entonces cuando se ejecuta el esperable esa excepción se propaga al invocador del esperable.

coroutine agen.aclose()

Retorna un esperable que cuando corre lanza un GeneratorExit a la función generadora asincrónica en el punto donde fue pausada. Si la función generadora asincrónica termina exitosamente, ya está cerrada o genera GeneratorExit (sin cazar la excepción), el esperable retornado generará una excepción StopIteration. Otros esperables retornados por subsecuentes invocaciones al generador asincrónico generarán una excepción StopAsyncIteration. Si el generador asincrónico produce un valor, el esperable genera un RuntimeError. Si el generador asincrónico genera cualquier otra excepción, esta es propagada al invocador del esperable. Si el generador asincrónico ha terminado debido a una excepción o una terminación normal, entonces futuras invocaciones a aclose() retornarán un esperable que no hace nada.

6.3. Primarios

Los primarios representan las operaciones más fuertemente ligadas al lenguaje. Su sintaxis es:

primary ::=  atom | attributeref | subscription | slicing | call

6.3.1. Referencias de atributos

Una referencia de atributo es un primario seguido de un punto y un nombre:

attributeref ::=  primary "." identifier

El primario debe evaluar a un objeto de un tipo que soporte referencias de atributos, lo cual la mayoría de los objetos soportan. Luego se le pide a este objeto que produzca el atributo cuyo nombre es el identificador. Esta producción puede ser personalizada sobrescribiendo el método __getattr__(). Si este atributo no es esperable, se genera la excepción AtributeError. De otra forma, el tipo y el valor del objeto producido es determinado por el objeto. Múltiples evaluaciones la misma referencia de atributo pueden producir diferentes objetos.

6.3.2. Suscripciones

The subscription of an instance of a container class will generally select an element from the container. The subscription of a generic class will generally return a GenericAlias object.

subscription ::=  primary "[" expression_list "]"

When an object is subscripted, the interpreter will evaluate the primary and the expression list.

The primary must evaluate to an object that supports subscription. An object may support subscription through defining one or both of __getitem__() and __class_getitem__(). When the primary is subscripted, the evaluated result of the expression list will be passed to one of these methods. For more details on when __class_getitem__ is called instead of __getitem__, see __class_getitem__ versus __getitem__.

If the expression list contains at least one comma, it will evaluate to a tuple containing the items of the expression list. Otherwise, the expression list will evaluate to the value of the list’s sole member.

For built-in objects, there are two types of objects that support subscription via __getitem__():

Mappings. If the primary is a mapping, the expression list must evaluate to an object whose value is one of the keys of the mapping, and the subscription selects the value in the mapping that corresponds to that key. An example of a builtin mapping class is the dict class.

Sequences. If the primary is a sequence, the expression list must evaluate to an int or a slice (as discussed in the following section). Examples of builtin sequence classes include the str, list and tuple classes.

The formal syntax makes no special provision for negative indices in sequences. However, built-in sequences all provide a __getitem__() method that interprets negative indices by adding the length of the sequence to the index so that, for example, x[-1] selects the last item of x. The resulting value must be a nonnegative integer less than the number of items in the sequence, and the subscription selects the item whose index is that value (counting from zero). Since the support for negative indices and slicing occurs in the object’s __getitem__() method, subclasses overriding this method will need to explicitly add that support.

A string is a special kind of sequence whose items are characters. A character is not a separate data type but a string of exactly one character.

6.3.3. Segmentos

Un segmento selecciona un rango de elementos en una objeto secuencia (ej., una cadena de caracteres, tupla o lista). Los segmentos pueden ser usados como expresiones o como objetivos en asignaciones o sentencias del. La sintaxis para un segmento:

slicing      ::=  primary "[" slice_list "]"
slice_list   ::=  slice_item ("," slice_item)* [","]
slice_item   ::=  expression | proper_slice
proper_slice ::=  [lower_bound] ":" [upper_bound] [ ":" [stride] ]
lower_bound  ::=  expression
upper_bound  ::=  expression
stride       ::=  expression

Hay ambigüedad en la sintaxis formal aquí: todo lo que parezca una expresión de lista también parece una segmento de lista, así que cualquier subscripción puede ser interpretada como un segmento. En lugar de complicar aún más la sintaxis, esta es desambiguada definiendo que en este caso la interpretación como una subscripción toma prioridad sobre la interpretación como un segmento (este es el caso si el segmento de lista no contiene un segmento adecuado).

Las semánticas para un segmento son las siguientes. El primario es indexado (usando el mismo método __getitem__() de una subscripción normal) con una clave que se construye del segmento de lista, tal como sigue. Si el segmento de lista contiene al menos una coma, la clave es una tupla que contiene la conversión de los elementos del segmento; de otra forma, la conversión del segmento de lista solitario es la clave. La conversión de un elemento de segmento que es una expresión es esa expresión. La conversión de un segmento apropiado es un objeto segmento (ver sección Jerarquía de tipos estándar) cuyos atributos start, stop y step son los valores de las expresiones dadas como límite inferior, límite superior y paso, respectivamente, substituyendo None para las expresiones faltantes.

6.3.4. Invocaciones

Una invocación invoca un objeto invocable (ej., una function) con una serie posiblemente vacía de argumentos:

call                 ::=  primary "(" [argument_list [","] | comprehension] ")"
argument_list        ::=  positional_arguments ["," starred_and_keywords]
                            ["," keywords_arguments]
                          | starred_and_keywords ["," keywords_arguments]
                          | keywords_arguments
positional_arguments ::=  positional_item ("," positional_item)*
positional_item      ::=  assignment_expression | "*" expression
starred_and_keywords ::=  ("*" expression | keyword_item)
                          ("," "*" expression | "," keyword_item)*
keywords_arguments   ::=  (keyword_item | "**" expression)
                          ("," keyword_item | "," "**" expression)*
keyword_item         ::=  identifier "=" expression

Una coma final opcional puede estar presente después de los argumentos posicionales y de palabra clave pero no afecta a las semánticas.

La clave primaria debe evaluar a un objeto invocable (funciones definidas por el usuario, funciones incorporadas, métodos de objetos incorporados, métodos de instancias de clases y todos los objetos que tienen un método __call__() son invocables). Todas las expresiones de argumento son evaluadas antes de que la invocación sea intentada. Por favor, refiera a la sección Definiciones de funciones para la sintaxis formal de listas de parameter.

Si hay argumentos de palabra clave, primero se convierten en argumentos posicionales, como se indica a continuación. En primer lugar, se crea una lista de ranuras sin rellenar para los parámetros formales. Si hay N argumentos posicionales, se colocan en las primeras N ranuras. A continuación, para cada argumento de palabra clave, el identificador se utiliza para determinar la ranura correspondiente (si el identificador es el mismo que el primer nombre de parámetro formal, se utiliza la primera ranura, etc.). Si la ranura ya está llena, se genera una excepción TypeError. De lo contrario, el valor del argumento se coloca en la ranura, llenándolo (incluso si la expresión es None, esta llena la ranura). Cuando se han procesado todos los argumentos, las ranuras que aún no han sido rellenadas se rellenan con el valor predeterminado correspondiente de la definición de función. (Los valores predeterminados son calculados una vez, cuando se define la función; por lo tanto, un objeto mutable como una lista o diccionario utilizado como valor predeterminado será compartido por todas las llamadas que no especifican un valor de argumento para la ranura correspondiente; esto normalmente debe ser evitado.) Si hay ranuras sin rellenar para las que no se especifica ningún valor predeterminado, se genera una excepción TypeError. De lo contrario, la lista de ranuras rellenas se utiliza como la lista de argumentos para la llamada.

CPython implementation detail: Una implementación puede proveer funciones incorporadas cuyos argumentos posicionales no tienen nombres, incluso si son «nombrados» a efectos de documentación y los cuales por consiguiente no pueden ser suplidos por palabras clave. En CPython, este es el caso para funciones implementadas en C que usan PyArg_ParseTuple() para analizar sus argumentos.

Si hay más argumentos posicionales que ranuras formales de parámetros, se genera una excepción TypeError, a no ser que un parámetro formal usando la sintaxis *identifier se encuentre presente; en este caso, ese parámetro formal recibe una tupla conteniendo los argumentos posicionales sobrantes (o una tupla vacía su no hay argumentos posicionales sobrantes).

Si un argumento de palabra clave no corresponde a un nombre de parámetro formal, se genera una excepción TypeError, a no ser que un parámetro formal usando la sintaxis **identifier esté presente; en este caso, ese parámetro formal recibe un diccionario que contiene los argumentos de palabra clave sobrantes (usando las palabras clave como claves y los valores de argumento como sus valores correspondientes), o un (nuevo) diccionario vacío si no hay argumentos de palabra clave sobrantes.

Si la sintaxis *expression aparece en la invocación de función, expression debe evaluar a un iterable. Elementos de esos iterables son tratados como si fueran argumentos posicionales adicionales. Para la invocación f(x1, x2, *y, x3, x4), si y evalúa a una secuencia y1, …, yM, equivale a una invocación con M+4 argumentos posicionales x1, x2, y1, …, yM, x3, x4.

Una consecuencia de esto es que aunque la sintaxis *expression puede aparecer después de argumentos de palabra clave explícitos, es procesada antes de los argumentos de palabra clave (y cualquiera de los argumentos *expression – ver abajo). Así que:

>>> def f(a, b):
...     print(a, b)
...
>>> f(b=1, *(2,))
2 1
>>> f(a=1, *(2,))
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: f() got multiple values for keyword argument 'a'
>>> f(1, *(2,))
1 2

Es inusual usar en la misma invocación tanto argumentos de palabra clave como la sintaxis *expression, así que en la práctica no surge esta confusión.

Si la sintaxis *expression aparece en la invocación de función, expression debe evaluar a un mapping, los contenidos del mismo son tratados como argumentos de palabra clave adicionales. Si una palabra clave está ya presente (como un argumento de palabra clave explícito o desde otro desempaquetado), se genera una excepción TypeError.

No pueden ser usados parámetros formales usando la sintaxis *identifier o **identifier como ranuras de argumentos posicionales o como nombres de argumentos de palabra clave.

Distinto en la versión 3.5: Las invocaciones de función aceptan cualquier número de desempaquetados * y **, los argumentos posicionales pueden seguir a desempaquetados de iterable (*) y los argumentos de palabra clave pueden seguir a desempaquetados de diccionario (*). Originalmente propuesto por PEP 448 [https://www.python.org/dev/peps/pep-0448].

Una invocación siempre retorna algún valor, posiblemente None, a no ser que genere una excepción. Cómo se calcula este valor depende del tipo del objeto invocable.

Si es—

una función definida por el usuario:

Se ejecuta el bloque de código para la función, pasándole la lista de argumentos. Lo primero que hace el bloque de código es enlazar los parámetros formales a los argumentos; esto es descrito en la sección Definiciones de funciones. Cuando el bloque de código ejecuta una sentencia return, esto especifica el valor de retorno de la invocación de función.

una función o método incorporado:

El resultado depende del intérprete; ver Funciones Built-in para las descripciones de funciones y métodos incorporados.

un objeto de clase:

Se retorna una nueva instancia de esa clase.

un método de una instancia de clase:

Se invoca la función definida por el usuario correspondiente, con una lista de argumentos con un largo uno mayor que la lista de argumentos de la invocación: la instancia se convierte en el primer argumento.

una instancia de clase:

La clase debe definir un método __call__(); el efecto es entonces el mismo que si ese método fuera invocado.

6.4. Expresión await

Suspende la ejecución de coroutine o un objeto awaitable. Puede ser usado sólo dentro de una coroutine function.

await_expr ::=  "await" primary

Nuevo en la versión 3.5.

6.5. El operador de potencia

El operador de potencia se vincula más estrechamente que los operadores unarios a su izquierda; se vincula con menos fuerza que los operadores unarios a su derecha. La sintaxis es:

power ::=  (await_expr | primary) ["**" u_expr]

Por lo tanto, en una secuencia sin paréntesis de operadores unarios y de potencia, los operadores son evaluados desde la derecha a la izquierda (este no se constriñe al orden de evaluación para los operandos): -1**2 resulta en -1.

El operador de potencia tiene las mismas semánticas que la función incorporada pow() cuando se invoca con dos argumentos: este produce su argumento de la izquierda elevado a la potencia de su argumento de la derecha. Los argumentos numéricos se convierten primero en un tipo común y el resultado es de ese tipo.

Para operandos int, el resultado tiene el mismo tipo que los operandos a no ser que el segundo argumento sea negativo; en ese caso, todos los argumentos son convertidos a float y se entrega un resultado float. Por ejemplo, 10**2 retorna 100, pero 10**-2 retorna 0.01.

Elevar 0.0 a una potencia negativa resulta en un ZeroDivisionError. Elevar un número negativo a una potencia fraccional resulta en un número complex. (En versiones anteriores se genera un ValueError.)

This operation can be customized using the special __pow__() method.

6.6. Aritmética unaria y operaciones bit a bit

Toda la aritmética unaria y las operaciones bit a bit tienen la misma prioridad:

u_expr ::=  power | "-" u_expr | "+" u_expr | "~" u_expr

The unary - (minus) operator yields the negation of its numeric argument; the operation can be overridden with the __neg__() special method.

The unary + (plus) operator yields its numeric argument unchanged; the operation can be overridden with the __pos__() special method.

The unary ~ (invert) operator yields the bitwise inversion of its integer argument. The bitwise inversion of x is defined as -(x+1). It only applies to integral numbers or to custom objects that override the __invert__() special method.

En todos los tres casos, si el argumento no tiene el tipo apropiado, se genera una excepción TypeError.

6.7. Operaciones aritméticas binarias

Las operaciones aritméticas binarias tienen los niveles convencionales de prioridad. Tenga en cuenta que algunas de esas operaciones también aplican a ciertos tipos no numéricos. Aparte del operador de potencia, hay sólo dos niveles, uno para operadores multiplicativos y uno para aditivos:

m_expr ::=  u_expr | m_expr "*" u_expr | m_expr "@" m_expr |
            m_expr "//" u_expr | m_expr "/" u_expr |
            m_expr "%" u_expr
a_expr ::=  m_expr | a_expr "+" m_expr | a_expr "-" m_expr

El operador * (multiplicación) produce el producto de sus argumentos. Los argumentos pueden ser ambos números, o un argumento debe ser un entero y el otro debe ser una secuencia. En el primer caso, los números se convierten a un tipo común y luego son multiplicados. En el segundo caso, se realiza una repetición de secuencia; un factor de repetición negativo produce una secuencia vacía.

This operation can be customized using the special __mul__() and __rmul__() methods.

El operador @ (en) está destinado a ser usado para multiplicación de matrices. Ningún tipo incorporado en Python implementa este operador.

Nuevo en la versión 3.5.

Los operadores / (división) y // (división de redondeo) producen el cociente de sus argumentos. Los argumentos numéricos son primero convertidos a un tipo común. La división de enteros producen un número de punto flotante, mientras que la división redondeada de enteros resulta en un entero; el resultado es aquel de una división matemática con la función “floor” aplicada al resultado. Dividir entre 0 genera la excepción ZeroDivisionError.

This operation can be customized using the special __truediv__() and __floordiv__() methods.

El operador % (módulo) produce el resto de la división del primer argumento entre el segundo. Los argumentos numéricos son primero convertidos a un tipo común. Un argumento a la derecha cero genera la excepción ZeroDivisionError. Los argumentos pueden ser números de punto flotante, ej., 3.14%0.7 es igual a 0.34 (ya que 3.14 es igual a 4*0.7 + 0.34.) El operador módulo siempre produce un resultado con el mismo signo que su segundo operando (o cero); el valor absoluto del resultado es estrictamente más pequeño que el valor absoluto del segundo operando 1.

Los operadores de división de redondeo y módulo están conectados por la siguiente identidad: x == (x//y)*y + (x%y). La división de redondeo y el módulo también están conectadas por la función incorporada divmod(): divmod(x, y) == (x//y, x%y). 2.

Adicionalmente a realizar la operación módulo en números, el operador % también está sobrecargado por objetos cadena de caracteres para realizar formateo de cadenas al estilo antiguo (también conocido como interpolación). La sintaxis para el formateo de cadenas está descrita en la Referencia de la Biblioteca de Python, sección Formateo de cadenas al estilo *printf*.

The modulo operation can be customized using the special __mod__() method.

El operador de división de redondeo, el operador módulo y la función divmod() no están definidas para números complejos. En su lugar, convierta a un número de punto flotante usando la función abs() si es apropiado.

El operador + (adición) produce la suma de sus argumentos. Los argumentos deben ser ambos números o ambos secuencias del mismo tipo. En el primer caso, los números son convertidos a un tipo común y luego sumados. En el segundo caso, las secuencias son concatenadas.

This operation can be customized using the special __add__() and __radd__() methods.

El operador - (resta) produce la diferencia de sus argumentos. Los argumentos numéricos son primero convertidos a un tipo común.

This operation can be customized using the special __sub__() method.

6.8. Operaciones de desplazamiento

Las operaciones de desplazamiento tienen menos prioridad que las operaciones aritméticas:

shift_expr ::=  a_expr | shift_expr ("<<" | ">>") a_expr

Estos operadores aceptan enteros como argumentos. Ellos desplazan el primer argumento a la izquierda o derecha el número de dígitos dados por el segundo argumento.

This operation can be customized using the special __lshift__() and __rshift__() methods.

Un desplazamiento de n bits hacia la derecha está definido como una división de redondeo entre pow(2,n). Un desplazamiento de n bits hacia la izquierda está definido como una multiplicación por pow(2,n).

6.9. Operaciones bit a bit binarias

Cada una de las tres operaciones de bits binarias tienen diferente nivel de prioridad:

and_expr ::=  shift_expr | and_expr "&" shift_expr
xor_expr ::=  and_expr | xor_expr "^" and_expr
or_expr  ::=  xor_expr | or_expr "|" xor_expr

The & operator yields the bitwise AND of its arguments, which must be integers or one of them must be a custom object overriding __and__() or __rand__() special methods.

The ^ operator yields the bitwise XOR (exclusive OR) of its arguments, which must be integers or one of them must be a custom object overriding __xor__() or __rxor__() special methods.

The | operator yields the bitwise (inclusive) OR of its arguments, which must be integers or one of them must be a custom object overriding __or__() or __ror__() special methods.

6.10. Comparaciones

A diferencia de C, todas las operaciones de comparación en Python tienen la misma prioridad, la cual es menor que la de cualquier operación aritmética, de desplazamiento o bit a bit. También, a diferencia de C, expresiones como a < b < c tienen la interpretación convencional en matemáticas:

comparison    ::=  or_expr (comp_operator or_expr)*
comp_operator ::=  "<" | ">" | "==" | ">=" | "<=" | "!="
                   | "is" ["not"] | ["not"] "in"

Comparisons yield boolean values: True or False. Custom rich comparison methods may return non-boolean values. In this case Python will call bool() on such value in boolean contexts.

Las comparaciones pueden ser encadenadas arbitrariamente, ej., x < y <= z es equivalente a x < y and y <= z, excepto que y es evaluado sólo una vez (pero en ambos casos z no es evaluado para nada cuando x < y se encuentra que es falso).

Formalmente, si a, b, c, …, y, z son expresiones y op1, op2, …, opN son operadores de comparación, entonces a op1 b op2 c ... y opN z es equivalente a a op1 b and b op2 c and ... y opN z, excepto que cada expresión es evaluada como mucho una vez.

Tenga en cuenta que a op1 b op2 c no implica ningún tipo de comparación entre a y c, por lo que, por ejemplo, x < y > z es perfectamente legal (aunque quizás no es bonito).

6.10.1. Comparaciones de valor

Los operadores <, >, ==, >=, <=, y != comparan los valores de dos objetos. Los objetos no necesitan ser del mismo tipo.

El capítulo Objetos, valores y tipos afirma que los objetos tienen un valor (en adición al tipo e identidad). El valor de un objeto es una noción bastante abstracta en Python: Por ejemplo, no existe un método de acceso canónico para el valor de un objeto. Además, no se requiere que el valor de un objeto deba ser construido de una forma particular, ej. compuesto de todos sus atributos de datos. Los operadores de comparación implementan una noción particular de lo que es el valor de un objeto. Uno puede pensar en ellos definiendo el valor de un objeto indirectamente, mediante su implementación de comparación.

Debido a que todos los tipos son subtipos (directos o indirectos) de object, ellos heredan el comportamiento de comparación predeterminado desde object. Los tipos pueden personalizar su comportamiento de comparación implementando rich comparison methods como __lt__(), descritos en Personalización básica.

El comportamiento predeterminado para comparación de igualdad (== y !=) se basa en la identidad de los objetos. Por lo tanto, la comparación de instancias con la misma identidad resulta en igualdad, y la comparación de igualdad de instancias con diferentes entidades resulta en desigualdad. Una motivación para este comportamiento predeterminado es el deseo de que todos los objetos sean reflexivos (ej. x is y implica x == y).

No se provee un orden de comparación por defecto (<, >, <=, and >=); un intento genera TypeError. Una motivación para este comportamiento predeterminado es la falta de una invariante similar como para la igualdad.

El comportamiento de la comparación de igualdad predeterminado, que instancias con diferentes identidades siempre son desiguales, puede estar en contraste a que los tipos que necesitarán que tengan una definición sensata de valor de objeto e igualdad basada en el valor. Tales tipos necesitarán personalizar su comportamiento de comparación y, de hecho, un número de tipos incorporados lo han realizado.

La siguiente lista describe el comportamiento de comparación de los tipos incorporados más importantes.

Números de tipos numéricos incorporadas (Tipos numéricos — int, float, complex) y tipos de la biblioteca estándar fractions.Fraction y decimal.Decimal pueden ser comparados consigo mismos y entre sus tipos, con la restricción de que números complejos no soportan orden de comparación. Dentro de los límites de los tipos involucrados, se comparan matemáticamente (algorítmicamente) correctos sin pérdida de precisión.

Los valores no-un-número float('NaN') y decimal.Decimal('NaN') son especiales. Cualquier comparación ordenada de un número a un no-un-número es falsa. Una implicación contraintuitiva es que los valores no-un-número son son iguales a sí mismos. Por ejemplo, si x = float('NaN'), 3 < x, x < 3 y x == x son todos falso, mientras x != x es verdadero. Este comportamiento cumple con IEEE 754.

None y NotImplemented son singletons. PEP 8 [https://www.python.org/dev/peps/pep-0008] avisa que las comparaciones para singletons deben ser realizadas siempre con is o is not, nunca los operadores de igualdad.

Las secuencias binarias (instancias de bytes o bytearray) pueden ser comparadas entre sí y con otros tipos. Ellas comparan lexicográficamente utilizando los valores numéricos de sus elementos.

Las cadenas de caracteres (instancias de str) comparan lexicográficamente usando los puntos de códigos numéricos Unicode (el resultado de la función incorporada ord()) o sus caracteres. 3

Las cadenas de caracteres y las secuencias binarias no pueden ser comparadas directamente.

Las secuencias (instancias de tuple, list, o range) pueden ser comparadas sólo entre cada uno de sus tipos, con la restricción de que los rangos no soportan comparación de orden. Comparación de igualdad entre esos tipos resulta en desigualdad y la comparación de orden entre esos tipos genera TypeError.

Las secuencias comparan lexicográficamente usando comparación de sus correspondientes elementos. Los contenedores incorporados asumen que los objetos idénticos son iguales a sí mismos. Eso les permite omitir las pruebas de igualdad para objetos idénticos para mejorar el rendimiento y mantener sus invariantes internos.

La comparación lexicográfica entre colecciones incorporadas funciona de la siguiente forma:

Para que dos colecciones sean comparadas iguales, ellas deben ser del mismo tipo, tener el mismo largo, y cada para de elementos correspondientes deben comparar iguales (por ejemplo, [1,2] == (1,2) es falso debido a que el tipo no es el mismo).

Las colecciones que soportan comparación de orden son ordenadas igual que sus primeros elementos desiguales (por ejemplo, [1,2,x] <= [1,2,y] tiene el mismo valor que x <= y). Si un elemento correspondiente no existe, la colección más corta es ordenada primero (por ejemplo, [1,2] < [1,2,3] es verdadero).

Los mapeos (instancias de dict) comparan igual si y sólo si tienen pares (clave, valor) iguales. La comparación de igualdad de claves y valores refuerza la reflexibilidad.

Comparaciones de orden (<, >, <=, and >=) generan TypeError.

Conjuntos (instancias de set o frozenset) pueden ser comparadas entre sí y entre sus tipos.

Ellas definen operadores de comparación de orden con la intención de comprobar subconjuntos y superconjuntos. Tales relaciones no definen ordenaciones completas (por ejemplo, los dos conjuntos {1,2} y {2,3} no son iguales, ni subconjuntos ni superconjuntos uno de otro). Acordemente, los conjuntos no son argumentos apropiados para funciones que dependen de ordenación completa (por ejemplo, min(), max() y sorted() producen resultados indefinidos dados una lista de conjuntos como entradas).

La comparación de conjuntos refuerza la reflexibilidad de sus elementos.

La mayoría de los otros tipos incorporados no tienen métodos de comparación implementados, por lo que ellos heredan el comportamiento de comparación predeterminado.

Las clases definidas por el usuario que personalizan su comportamiento de comparación deben seguir algunas reglas de consistencia, si es posible:

La comparación de igualdad debe ser reflexiva. En otras palabras, los objetos idénticos deben comparar iguales:

x is y implica x == y

La comparación debe ser simétrica. En otras palabras, las siguientes expresiones deben tener el mismo resultado:

x == y y y == x

x != y y y != x

x < y y y > x

x <= y y y >= x

La comparación debe ser transitiva. Los siguientes ejemplos (no exhaustivos) ilustran esto:

x > y and y > z implica x > z

x < y and y <= z implica x < z

La comparación inversa debe resultar en la negación booleana. En otras palabras, las siguientes expresiones deben tener el mismo resultado:

x == y y not x != y

x < y y not x >= y (para ordenación completa)

x > y y not x <= y (para ordenación completa)

Las últimas dos expresiones aplican a colecciones completamente ordenadas (ej. a secuencias, pero no a conjuntos o mapeos). Vea también el decorador total_ordering().

La función hash() debe ser consistente con la igualdad. Los objetos que son iguales deben tener el mismo valor de hash o ser marcados como inhashables.

Python no fuerza a cumplir esas reglas de coherencia. De hecho, los valores no-un-número son u ejemplo para no seguir esas reglas.

6.10.2. Operaciones de prueba de membresía

Los operadores in y not in comprueban membresía. x in s evalúa a True si x es un miembro de s y False en caso contrario. x not in s retorna la negación de x in s. Todas las secuencias incorporadas y tipos conjuntos soportan esto, así como diccionarios, para los cuales in comprueba si un diccionario tiene una clave dada. Para tipos contenedores como list, tuple, set, frozenset, dict o collections.deque, la expresión x in y es equivalente a any(x is e or x == e for e in y).

Para los tipos cadenas de caracteres y bytes, x in y es True si y sólo si x es una subcadena de y. Una comprobación equivalente es y.find(x) != -1. Las cadenas de caracteres vacías siempre son consideradas como subcadenas de cualquier otra cadena de caracteres, por lo que "" in "abc" retornará True.

Para clases definidas por el usuario las cuales definen el método __contains__(), x in y retorna True si y.__contains__(x) retorna un valor verdadero y False si no.

Para clases definidas por el usuario las cuales no definen __contains__() pero definen __iter__(), x in y es True si algún valor z, para el cual la expresión x is z or x == z es verdadera, es producido iterando sobre y. Si una excepción es generada durante la iteración, es como si in hubiera generado esa excepción.

Por último, se intenta el protocolo de iteración al estilo antiguo: si una clase define __getitem__(), x in y es True si y sólo si hay un índice entero no negativo i tal que x is y[i] or x == y[i] y ningún entero menor genera la excepción IndexError. (Si cualquier otra excepción es generada, es como si in hubiera generado esa excepción).

El operador not in es definido para tener el valor de veracidad inverso de in.

6.10.3. Comparaciones de identidad

Los operadores is y is not comprueban la identidad de un objeto. x is y es verdadero si y sólo si x e y son el mismo objeto. La identidad de un Objeto se determina usando la función id(). x is not y produce el valor de veracidad inverso. 4

6.11. Operaciones booleanas

or_test  ::=  and_test | or_test "or" and_test
and_test ::=  not_test | and_test "and" not_test
not_test ::=  comparison | "not" not_test

En el contexto de las operaciones booleanas y también cuando sentencias de control de flujo usan expresiones, los siguientes valores se interpretan como falsos: False, None, ceros numéricos de todos los tipos y cadenas de caracteres y contenedores vacíos (incluyendo cadenas de caracteres, tuplas, diccionarios, conjuntos y conjuntos congelados). Todos los otros valores son interpretados como verdaderos. Los objetos definidos por el usuario pueden personalizar su valor de veracidad proveyendo un método __bool__().

El operador not produce True si su argumento es falso, False si no.

La expresión x and y primero evalúa x; si x es falso, se retorna su valor; de otra forma, y es evaluado y se retorna el valor resultante.

La expresión x or y primero evalúa x; si x es verdadero, se retorna su valor; de otra forma, y es evaluado y se retorna el valor resultante.

Tenga en cuenta que ni and ni or restringen el valor y el tipo que retornan a False y True, sino retornan el último argumento evaluado. Esto es útil a veces, ej., si s es una cadena de caracteres que debe ser remplazada por un valor predeterminado si está vacía, la expresión s or 'foo' produce el valor deseado. Debido a que not tiene que crear un nuevo valor, retorna un valor booleano indiferentemente del tipo de su argumento (por ejemplo, not 'foo' produce False en lugar de ''.)

6.12. Expresiones de asignación

assignment_expression ::=  [identifier ":="] expression

Una expresión de asignación (a veces también llamada «expresión con nombre» o «walrus») asigna un expression a un identifier, mientras que también retorna el valor de expression.

Un caso de uso común es cuando se manejan expresiones regulares coincidentes:

if matching := pattern.search(data):
    do_something(matching)

O, al procesar un flujo de archivos en fragmentos:

while chunk := file.read(9000):
    process(chunk)

Nuevo en la versión 3.8: Vea PEP 572 [https://www.python.org/dev/peps/pep-0572] para más detalles sobre las expresiones de asignación.

6.13. Expresiones condicionales

conditional_expression ::=  or_test ["if" or_test "else" expression]
expression             ::=  conditional_expression | lambda_expr

Las expresiones condicionales (a veces denominadas un «operador ternario») tienen la prioridad más baja que todas las operaciones de Python.

La expresión x if C else y primero evalúa la condición, C en lugar de x. Si C es verdadero, x es evaluado y se retorna su valor; en caso contrario, y es evaluado y se retorna su valor.

Vea PEP 308 [https://www.python.org/dev/peps/pep-0308] para más detalles sobre expresiones condicionales.

6.14. Lambdas

lambda_expr ::=  "lambda" [parameter_list] ":" expression

Las expresiones lambda (a veces denominadas formas lambda) son usadas para crear funciones anónimas. La expresión lambda parameters: expression produce un objeto de función. El objeto sin nombre se comporta como un objeto función con:

def <lambda>(parameters):
    return expression

Vea la sección Definiciones de funciones para la sintaxis de listas de parámetros. Tenga en cuenta que las funciones creadas con expresiones lambda no pueden contener sentencias ni anotaciones.

6.15. Listas de expresiones

expression_list    ::=  expression ("," expression)* [","]
starred_list       ::=  starred_item ("," starred_item)* [","]
starred_expression ::=  expression | (starred_item ",")* [starred_item]
starred_item       ::=  assignment_expression | "*" or_expr

Excepto cuando son parte de un despliegue de lista o conjunto, una lista de expresión conteniendo al menos una coma produce una tupla. El largo de la tupla es el número de expresiones en la lista. Las expresiones son evaluadas de izquierda a derecha.

Un asterisco * denota iterable unpacking. Su operando deben ser un iterable. El iterable es expandido en una secuencia de elementos, los cuales son incluidos en la nueva tupla, lista o conjunto en el lugar del desempaquetado.

Nuevo en la versión 3.5: Desempaquetado iterable en listas de expresiones, originalmente propuesto por PEP 488 [https://www.python.org/dev/peps/pep-0488].

La coma final sólo es requerida para crear una tupla única (también denominada un singleton); es opcional en todos los otros casos. Una única expresión sin una coma final no crea una tupla, si no produce el valor de esa expresión. (Para crear una tupla vacía, usa un par de paréntesis vacío: ().)

6.16. Orden de evaluación

Python evalúa las expresiones de izquierda a derecha. Note que mientras se evalúa una asignación, la parte derecha es evaluada antes que la parte izquierda.

En las siguientes líneas, las expresiones serán evaluadas en el orden aritmético de sus sufijos:

expr1, expr2, expr3, expr4
(expr1, expr2, expr3, expr4)
{expr1: expr2, expr3: expr4}
expr1 + expr2 * (expr3 - expr4)
expr1(expr2, expr3, *expr4, **expr5)
expr3, expr4 = expr1, expr2

6.17. Prioridad de operador

The following table summarizes the operator precedence in Python, from highest precedence (most binding) to lowest precedence (least binding). Operators in the same box have the same precedence. Unless the syntax is explicitly given, operators are binary. Operators in the same box group left to right (except for exponentiation, which groups from right to left).

Tenga en cuenta que las comparaciones, comprobaciones de membresía y las comprobaciones de identidad tienen la misma prioridad y una característica de encadenado de izquierda a derecha como son descritas en la sección Comparaciones.

Operador

Descripción

(expressions...),

[expressions...], {key: value...}, {expressions...}

Expresión de enlace o entre paréntesis, despliegues de lista, diccionario y conjunto

x[index], x[index:index], x(arguments...), x.attribute

Subscripción, segmentación, invocación, referencia de atributo

await x

Expresión await

**

Exponenciación 5

+x, -x, ~x

NOT positivo, negativo, bit a bit

*, @, /, //, %

Multiplicación, multiplicación de matrices, división, división de redondeo, resto 6

+, -

Adición y sustracción

<<, >>

Desplazamientos

&

AND bit a bit

^

XOR bit a bit

|

OR bit a bit

in, not in, is, is not, <, <=, >, >=, !=, ==

Comparaciones, incluyendo comprobaciones de membresía y de identidad

not x

Booleano NOT

and

Booleano AND

or

Booleano OR

if – else

Expresión condicional

lambda

Expresión lambda

:=

Expresión de asignación

Notas al pie

1

Mientras abs(x%y) < abs(y) es matemáticamente verdadero, para números de punto flotante puede no ser verdadero numéricamente debido al redondeo. Por ejemplo, y asumiendo una plataforma en la cual un número de punto flotante de Python es un número de doble precisión IEEE 754, a fin de que -1e-100 % 1e100 tenga el mismo signo que 1e100, el resultado calculado es -1e-100 + 1e100, el cual es numéricamente exactamente igual a 1e100. La función math.fmod() retorna un resultado cuyo signo concuerda con el signo del primer argumento en su lugar, y por ello retorna -1e-100 en este caso. La aproximación más apropiada depende de su aplicación.

2

Si x está muy cerca de un entero exacto múltiple de y, es posible para x//y que sea uno mayor que (x-x%y)//y debido al redondeo. En tales casos, Python retorna el último resultado, a fin de preservar que divmod(x,y)[0] * y + x % y sea muy cercano a x.

3

El estándar Unicode distingue entre code points (ej. U+0041) y abstract characters (ej. «LETRA MAYÚSCULA LATINA A»). Mientras la mayoría de caracteres abstractos en Unicode sólo son representados usando un punto de código, hay un número de caracteres abstractos que pueden adicionalmente ser representados usado una secuencia de más de un punto de código. Por ejemplo, el caracter abstracto «LETRA MAYÚSCULA C LATINA CON CEDILLA» puede ser representado como un único precomposed character en la posición de código U+00C7, o como una secuencia de un base character en la posición de código U+0043 (LETRA MAYÚSCULA C LATINA), seguida de un combining character en la posición de código U+0327 (CEDILLA COMBINADA).

Los operadores de comparación comparan en cadenas de caracteres al nivel de puntos de código Unicode. Esto puede ser contraintuitivo para humanos. Por ejemplo, "\u00C7" == "\u0043\u0327" es False, incluso aunque ambas cadenas presenten el mismo caracter abstracto «LETRA MAYÚSCULA C LATINA CON CEDILLA».

Para comparar cadenas al nivel de caracteres abstractos (esto es, de una forma intuitiva para humanos), usa unicodedata.normalize().

4

Debido a la recolección automática de basura, listas libres y a la naturaleza dinámica de los descriptores, puede notar un comportamiento aparentemente inusual en ciertos usos del operador is, como aquellos involucrando comparaciones entre métodos de instancia, o constantes. Compruebe su documentación para más información.

5

El operador de potencia ** vincula con menos fuerza que un operador unario aritmético uno bit a bit en su derecha, esto significa que 2**-1 is 0.5.

6

El operador % también es usado para formateo de cadenas; aplica la misma prioridad.

7. Declaraciones simples

Una declaración simple se compone dentro de una sola línea lógica. Pueden producirse varias declaraciones simples en una sola línea separada por punto y coma. La sintaxis de las declaraciones simples es:

simple_stmt ::=  expression_stmt
                 | assert_stmt
                 | assignment_stmt
                 | augmented_assignment_stmt
                 | annotated_assignment_stmt
                 | pass_stmt
                 | del_stmt
                 | return_stmt
                 | yield_stmt
                 | raise_stmt
                 | break_stmt
                 | continue_stmt
                 | import_stmt
                 | future_stmt
                 | global_stmt
                 | nonlocal_stmt

7.1. Declaraciones de tipo expresión

Las declaraciones de tipo expresión son usadas (en su mayoría interactivamente) para computar y escribir un valor, o (usualmente) para llamar a un método (una función que no retorna un resultado significativo; en Python, los métodos retornan el valor None). Otros usos de las declaraciones de tipo expresión son permitidas y ocasionalmente útiles. La sintaxis para una declaración de tipo expresión es:

expression_stmt ::=  starred_expression

Una declaración de tipo expresión evalúa la lista de expresiones (que puede ser una única expresión).

En modo interactivo, si el valor no es None, es convertido a cadena de caracteres usando la función built-in repr() y la cadena resultante es escrita en la salida estándar en una línea por si sola (excepto si el resultado es None, entonces el procedimiento llamado no produce ninguna salida.)

7.2. Declaraciones de asignación

Las declaraciones de asignación son usadas para (volver a) unir nombres a valores y para modificar atributos o elementos de objetos mutables:

assignment_stmt ::=  (target_list "=")+ (starred_expression | yield_expression)
target_list     ::=  target ("," target)* [","]
target          ::=  identifier
                     | "(" [target_list] ")"
                     | "[" [target_list] "]"
                     | attributeref
                     | subscription
                     | slicing
                     | "*" target

(Ver sección Primarios para las definiciones de sintaxis para attributeref, subscription, y slicing.)

Una declaración de asignación evalúa la lista de expresiones (recuerda que ésta puede ser una única expresión o una lista separada por comas, la última produce una tupla) y asigna el único objeto resultante a cada una de las listas de objetivos, de izquierda a derecha.

Las asignaciones son definidas recursivamente dependiendo de la forma del objetivo (lista). Cuando el objetivo es parte de un objeto mutable (una referencia a un atributo, una subscripción o un segmento), el objeto mutable finalmente debe realizar la asignación y decidir sobre su validez, y puede lanzar una excepción si la asignación no es aceptable. Las reglas observadas por varios tipos y las excepciones lanzadas se dan con la definición de los tipos de objeto (ver sección Jerarquía de tipos estándar).

La asignación de un objeto a una lista de destino, opcionalmente entre paréntesis o corchetes, se define de forma recursiva de la siguiente manera.

Si la lista de destino es un único objeto sin terminar en coma, opcionalmente entre paréntesis, el objeto es asignado a ese objetivo.

Else:

Si la lista de objetivos contiene un objetivo prefijado con un asterisco, llamado objetivo “destacado”: El objeto debe ser iterable con al menos tantos elementos como objetivos en la lista de objetivos, menos uno. Los primeros elementos del iterable se asignan, de izquierda a derecha, a los objetivos antes del objetivo destacado. Los elementos finales del iterable se asignan a los objetivos después del objetivo destacado. Luego se asigna una lista de los elementos restantes en el iterable al objetivo destacado (la lista puede estar vacía).

Sino: el objeto debe ser iterable con el mismo número de elementos que los elementos en la lista de objetivos, y los elementos son asignados a sus respectivos objetivos de izquierda a derecha.

La asignación de un objeto a un único objetivo se define a continuación de manera recursiva.

Si el objetivo es un identificador (nombre):

Si el nombre no ocurre en una declaración global o nonlocal en el actual bloque de código: el nombre es unido al objeto del actual espacio de nombres local.

Por otra parte: el nombre es unido al objeto en el nombre de espacio global o el nombre de espacio exterior determinado por nonlocal, respectivamente.

El nombre se vuelve a unir si ya ha estado unido. Esto puede hacer que el recuento de referencia para el objeto previamente vinculado al nombre llegue a cero, provocando que el objeto se desasigne y se llame a su destructor (si tiene uno).

Si el destino es una referencia de atributo: se evalúa la expresión primaria en la referencia. Debe producir un objeto con atributos asignables; si este no es el caso, una excepción TypeError es lanzada. Luego se le pide a ese objeto que asigne el objeto asignado al atributo dado; si no puede realizar la tarea, lanza una excepción (generalmente pero no necesariamente AttributeError).

Nota: Si el objeto es una instancia de clase y la referencia de atributo ocurre en ambos lados del operador de asignación, la expresión del lado derecho, a.x puede acceder a un atributo de instancia o (si no existe un atributo de instancia) a una clase atributo. El objetivo del lado izquierdo a.x siempre se establece como un atributo de instancia, creándolo si es necesario. Por lo tanto, las dos ocurrencias de a.x no necesariamente se refieren al mismo atributo: si la expresión del lado derecho se refiere a un atributo de clase, el lado izquierdo crea un nuevo atributo de instancia como el objetivo de la asignación:

class Cls:
    x = 3             # class variable
inst = Cls()
inst.x = inst.x + 1   # writes inst.x as 4 leaving Cls.x as 3

Esta descripción no se aplica necesariamente a los atributos del descriptor, como las propiedades creadas con property().

Si el objetivo es una suscripción: se evalúa la expresión primaria en la referencia. Debe producir un objeto de secuencia mutable (como una lista) o un objeto de mapeo (como un diccionario). A continuación, se evalúa la expresión del subíndice.

Si el primario es un objeto de secuencia mutable (como una lista), el subíndice debe producir un número entero. Si es negativo, se le suma la longitud de la secuencia. El valor resultante debe ser un número entero no negativo menor que la longitud de la secuencia, y se le pide a la secuencia que asigne el objeto asignado a su elemento con ese índice. Si el índice está fuera de rango, IndexError se lanza (la asignación a una secuencia suscrita no puede agregar nuevos elementos a una lista).

Si el principal es un objeto de mapeo (como un diccionario), el subíndice debe tener un tipo compatible con el tipo de clave del mapeo, y luego se le pide al mapeo que cree un par clave / dato que mapee el subíndice al objeto asignado. Esto puede reemplazar un par clave / valor existente con el mismo valor clave o insertar un nuevo par clave / valor (si no existía ninguna clave con el mismo valor).

Para objetos definidos por el usuario, se llama al método __setitem__() con los argumentos apropiados.

Si el destino es un rebanado (slicing): la expresión principal de la referencia es evaluada. Debería producir un objeto de secuencia mutable (como una lista). El objeto asignado debe ser un objeto de secuencia del mismo tipo. A continuación, se evalúan las expresiones de límite superior e inferior, en la medida en que estén presentes; los valores predeterminados son cero y la longitud de la secuencia. Los límites deben evaluarse a números enteros. Si alguno de los límites es negativo, se le suma la longitud de la secuencia. Los límites resultantes se recortan para que se encuentren entre cero y la longitud de la secuencia, inclusive. Finalmente, se solicita al objeto de secuencia que reemplace el segmento con los elementos de la secuencia asignada. La longitud del corte puede ser diferente de la longitud de la secuencia asignada, cambiando así la longitud de la secuencia objetivo, si la secuencia objetivo lo permite.

CPython implementation detail: En la implementación actual, se considera que la sintaxis de los objetivos es la misma que la de las expresiones y se rechaza la sintaxis no válida durante la fase de generación del código, lo que genera mensajes de error menos detallados.

Aunque la definición de asignación implica que las superposiciones entre el lado izquierdo y el lado derecho son ‘simultáneas’ (por ejemplo, a, b = b, a intercambia dos variables), las superposiciones dentro de la colección de las variables asignadas ocurren de izquierda a derecha, lo que a veces genera confusión. Por ejemplo, el siguiente programa imprime [0, 2]:

x = [0, 1]
i = 0
i, x[i] = 1, 2         # i is updated, then x[i] is updated
print(x)

Ver también

PEP 3132 [https://www.python.org/dev/peps/pep-3132] - Desembalaje Iterable Extendido

La especificación para la función *target.

7.2.1. Declaraciones de asignación aumentada

La asignación aumentada es la combinación, en una sola declaración, de una operación binaria y una declaración de asignación:

augmented_assignment_stmt ::=  augtarget augop (expression_list | yield_expression)
augtarget                 ::=  identifier | attributeref | subscription | slicing
augop                     ::=  "+=" | "-=" | "*=" | "@=" | "/=" | "//=" | "%=" | "**="
                               | ">>=" | "<<=" | "&=" | "^=" | "|="

(Ver sección Primarios para la definición de la sintaxis de los tres últimos símbolos.)

Una asignación aumentada evalúa el destino (que, a diferencia de las declaraciones de asignación normales, no puede ser un desempaquetado) y la lista de expresiones, realiza la operación binaria específica del tipo de asignación en los dos operandos y asigna el resultado al destino original. El objetivo sólo se evalúa una vez.

Una declaración de asignación aumentada como x += 1 puede ser reescriba como x = x + 1 para alcanzar un efecto similar pero no exactamente igual. En la versión aumentada, x es evaluada una única vez. Además, cuando es posible, la operación real se realiza in-place, lo que significa que en lugar de crear un nuevo objeto y asignarlo al objetivo, el objeto anterior se modifica.

A diferencia de las asignaciones normales, las asignaciones aumentadas evalúan el lado izquierdo antes de evaluar el lado derecho. Por ejemplo, a[i] += f(x) primero busca a[i], entonces evalúa f(x) y realiza la suma, y finalmente, vuelve a escribir el resultado en a[i].

Con la excepción de la asignación a tuplas y múltiples objetivos en una sola instrucción, la asignación realizada por las instrucciones de asignación aumentada se maneja de la misma manera que las asignaciones normales. De manera similar, con la excepción del posible comportamiento in situ, la operación binaria realizada por la asignación aumentada es la misma que las operaciones binarias normales.

Para destinos que son referencias a atributos, lo mismo que caveat about class and instance attributes se aplica para asignaciones regulares.

7.2.2. Declaraciones de asignación anotadas

Asignación Annotation es la combinación, en una única declaración, de una variable o anotación de atributo y una declaración de asignación opcional:

annotated_assignment_stmt ::=  augtarget ":" expression
                               ["=" (starred_expression | yield_expression)]

La diferencia respecto a Declaraciones de asignación normal es que sólo se permite un único objetivo.

Para nombres simples como destinos de asignación, si están en el ámbito de clase o módulo, las anotaciones se evalúan y almacenan en una clase especial o atributo de módulo __annotations__ que es una asignación de diccionario de nombres de variables (alterados si son privados) a anotaciones evaluadas. Este atributo se puede escribir y se crea automáticamente al comienzo de la ejecución del cuerpo del módulo o la clase, si las anotaciones se encuentran estáticamente.

Para expresiones como destinos de asignaciones, las anotaciones se evalúan si están en ámbitos de clase o módulo pero no se almacenan.

Si se anota un nombre en el ámbito de una función, este nombre es local para ese ámbito. Las anotaciones nunca se evalúan y almacenan en ámbitos de función.

Si el lado derecho está presente, una tarea anotada realiza la tarea real antes de evaluar las anotaciones (cuando corresponda). Si el lado derecho no está presente para un destino de expresión, entonces el intérprete evalúa el destino excepto por la última llamada __setitem__() o __setattr__().

Ver también

PEP 526 [https://www.python.org/dev/peps/pep-0526] - Sintaxis para anotaciones de variable

La propuesta que agregó sintaxis para anotar los tipos de variables (incluidas variables de clase y variables de instancia), en lugar de expresarlas a través de comentarios.

PEP 484 [https://www.python.org/dev/peps/pep-0484] - Indicadores de tipo

La propuesta que agregó el módulo typing para proporcionar una sintaxis estándar para las anotaciones de tipo para ser utilizadas en herramientas de análisis estático e IDEs.

Distinto en la versión 3.8: Ahora, las asignaciones anotadas permiten las mismas expresiones en el lado derecho que las asignaciones regulares. Anteriormente, algunas expresiones (como las expresiones de tupla sin paréntesis) provocaban un error de sintaxis.

7.3. La declaración assert

Las declaraciones de afirmación son una forma conveniente de insertar afirmaciones de depuración en un programa:

assert_stmt ::=  "assert" expression ["," expression]

La forma simple, assert expressionn, es equivalente a

if __debug__:
    if not expression: raise AssertionError

La forma extendida, assert expression1, expression2, es equivalente a

if __debug__:
    if not expression1: raise AssertionError(expression2)

Estas equivalencias asumen que __debug__ y AssertionError se refieren a las variables integradas con esos nombres. En la implementación actual, la variable incorporada __debug__ es True en circunstancias normales, False cuando se solicita la optimización (opción de línea de comando -O). El generador de código actual no emite código para una declaración de aserción cuando se solicita la optimización en tiempo de compilación. Tenga en cuenta que no es necesario incluir el código fuente de la expresión que falló en el mensaje de error; se mostrará como parte del seguimiento de la pila.

Asignaciones a __debug__ son ilegales. El valor para la variable se determina cuando arranca el intérprete.

7.4. La declaración pass

pass_stmt ::=  "pass"

pass es una operación nula — cuando se ejecuta, no sucede nada. Es útil como marcador de posición cuando se requiere una declaración sintácticamente, pero no es necesario ejecutar código, por ejemplo:

def f(arg): pass    # a function that does nothing (yet)

class C: pass       # a class with no methods (yet)

7.5. La declaración del

del_stmt ::=  "del" target_list

La eliminación se define de forma recursiva de manera muy similar a la forma en que se define la asignación. En lugar de explicarlo con todos los detalles, aquí hay algunas sugerencias.

La eliminación de una lista de objetivos elimina cada objetivo de forma recursiva, de izquierda a derecha.

La eliminación de un nombre elimina la vinculación de ese nombre del espacio de nombres local o global, dependiendo de si el nombre aparece en una declaración global en el mismo bloque de código. Si el nombre no está vinculado, se lanzará una excepción NameError.

La supresión de referencias de atributo, suscripciones y rebanadas se pasa al objeto primario involucrado; la eliminación de una rebanada es en general equivalente a la asignación de una rebanada vacía del tipo correcto (pero incluso esto está determinado por el objeto rebanado).

Distinto en la versión 3.2: Anteriormente era ilegal eliminar un nombre del espacio de nombres local si aparece como una variable libre en un bloque anidado.

7.6. La declaración return

return_stmt ::=  "return" [expression_list]

El return sólo puede ocurrir sintácticamente anidado en una definición de función, no dentro de una definición de clase anidada.

Si una lista de expresiones es presente, ésta es evaluada, sino es substituida por None .

return deja la llamada a la función actual con la lista de expresiones (o None) como valor de retorno.

Cuando return pasa el control de una sentencia try con una cláusula finally, esa cláusula finally se ejecuta antes de dejar realmente la función.

En una función generadora, la declaración return indica que el generador ha acabado y hará que StopIteration se lance. El valor retornado (si lo hay) se utiliza como argumento para construir StopIteration y se convierte en el atributo StopIteration.value.

En una función de generador asíncrono, una declaración return vacía indica que el generador asíncrono ha acabado y va a lanzar un StopAsyncIteration. Una declaración return no vacía es un error de sintaxis en una función generadora asíncrona.

7.7. La declaración yield

yield_stmt ::=  yield_expression

La declaración yield es semánticamente equivalente a yield expression. Una declaración de producción se puede utilizar para omitir los paréntesis que de otro modo serían necesarios en la declaración de expresión de producción equivalente. Por ejemplo, las declaraciones de producción

yield <expr>
yield from <expr>

son equivalentes a las funciones que producen declaraciones

(yield <expr>)
(yield from <expr>)

Expresiones y declaraciones productoras se usan únicamente para definir una función generator, y son utilizadas únicamente en el cuerpo de una función generadora. Usar producción en una definición de función es suficiente para hacer que esa definición cree una función generadora en lugar de una función normal.

Para todos los detalles de la semántica de yield, referirse a la sección Expresiones yield.

7.8. La declaración raise

raise_stmt ::=  "raise" [expression ["from" expression]]

If no expressions are present, raise re-raises the exception that is currently being handled, which is also known as the active exception. If there isn’t currently an active exception, a RuntimeError exception is raised indicating that this is an error.

De lo contrario, raise evalúa la primera expresión como el objeto de excepción. Debe ser una subclase o una instancia de BaseException. Si es una clase, la instancia de excepción se obtendrá cuando sea necesario creando una instancia de la clase sin argumentos.

El type de la excepción es la instancia de la clase excepción, el value es la propia instancia.

A traceback object is normally created automatically when an exception is raised and attached to it as the __traceback__ attribute, which is writable. You can create an exception and set your own traceback in one step using the with_traceback() exception method (which returns the same exception instance, with its traceback set to its argument), like so:

raise Exception("foo occurred").with_traceback(tracebackobj)

The from clause is used for exception chaining: if given, the second expression must be another exception class or instance. If the second expression is an exception instance, it will be attached to the raised exception as the __cause__ attribute (which is writable). If the expression is an exception class, the class will be instantiated and the resulting exception instance will be attached to the raised exception as the __cause__ attribute. If the raised exception is not handled, both exceptions will be printed:

>>> try:
...     print(1 / 0)
... except Exception as exc:
...     raise RuntimeError("Something bad happened") from exc
...
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
ZeroDivisionError: division by zero

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "<stdin>", line 4, in <module>
RuntimeError: Something bad happened

A similar mechanism works implicitly if a new exception is raised when an exception is already being handled. An exception may be handled when an except or finally clause, or a with statement, is used. The previous exception is then attached as the new exception’s __context__ attribute:

>>> try:
...     print(1 / 0)
... except:
...     raise RuntimeError("Something bad happened")
...
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
ZeroDivisionError: division by zero

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "<stdin>", line 4, in <module>
RuntimeError: Something bad happened

El encadenamiento de excepciones se puede suprimir explícitamente especificando None en la cláusula from:

>>> try:
...     print(1 / 0)
... except:
...     raise RuntimeError("Something bad happened") from None
...
Traceback (most recent call last):
  File "<stdin>", line 4, in <module>
RuntimeError: Something bad happened

Se puede encontrar información adicional sobre excepciones en la sección Excepciones, e información sobre manejo de excepciones en la sección La sentencia try.

Distinto en la versión 3.3: None ahora es permitido como Y en raise X from Y.

Nuevo en la versión 3.3: El atributo __suppress_context__ para suprimir la visualización automática del contexto de excepción.

7.9. La declaración break

break_stmt ::=  "break"

break solo puede ocurrir sintácticamente anidado en un bucle for o while, pero no anidado en una función o definición de clase dentro de ese bucle.

Termina el bucle adjunto más cercano, omitiendo la cláusula else opcional si el bucle tiene una.

Si un bucle for es terminado por break, el objetivo de control de bucle mantiene su valor actual.

Cuando break pasa el control de una sentencia try con una cláusula finally, esa cláusula finally se ejecuta antes de dejar realmente el bucle.

7.10. La declaración continue

continue_stmt ::=  "continue"

continue sólo puede ocurrir sintácticamente anidado en el ciclo for o while, pero no anidado en una función o definición de clase dentro de ese ciclo. Continúa con la siguiente iteración del bucle envolvente más cercano.

Cuando continue pasa el control de una sentencia try con una cláusula finally, esa cláusula finally se ejecuta antes de empezar realmente el siguiente ciclo del bucle.

7.11. La declaración import

import_stmt     ::=  "import" module ["as" identifier] ("," module ["as" identifier])*
                     | "from" relative_module "import" identifier ["as" identifier]
                     ("," identifier ["as" identifier])*
                     | "from" relative_module "import" "(" identifier ["as" identifier]
                     ("," identifier ["as" identifier])* [","] ")"
                     | "from" relative_module "import" "*"
module          ::=  (identifier ".")* identifier
relative_module ::=  "."* module | "."+

La declaración básica de importación (sin la cláusula from) es ejecutada en 2 pasos:

encontrar un módulo, cargarlo e inicializarlo en caso de ser necesario

define un nombre o nombres en el espacio de nombres local para el alcance donde ocurre la instrucción import.

Cuando la declaración contiene varias cláusulas (separadas por comas), los dos pasos se llevan a cabo por separado para cada cláusula, como si las cláusulas se hubieran separado en declaraciones de importación individuales.

Los detalles del primer paso, búsqueda y carga de módulos se describen con mayor detalle en la sección sobre el import system, que también describe los distintos tipos de paquetes y módulos que se pueden importar, así como todos los ganchos que se puede utilizar para personalizar el sistema de importación. Tenga en cuenta que las fallas en este paso pueden indicar que el módulo no se pudo ubicar, o que ocurrió un error al inicializar el módulo, que incluye la ejecución del código del módulo.

Si el módulo solicitado se recupera correctamente, estará disponible en el espacio de nombres local de una de estas tres formas:

Si el nombre del módulo va seguido de as`, entonces el nombre siguiente as está vinculado directamente al módulo importado.

Si no se especifica ningún otro nombre y el módulo que se está importando es un módulo de nivel superior, el nombre del módulo se enlaza en el espacio de nombres local como una referencia al módulo importado

Si el módulo que se está importando no es un módulo de nivel superior, entonces el nombre del paquete de nivel superior que contiene el módulo se enlaza en el espacio de nombres local como una referencia al paquete de nivel superior. Se debe acceder al módulo importado utilizando su nombre calificado completo en lugar de directamente

La forma from usa un complejo un poco más complicado:

encuentra el módulo especificado en la cláusula from, cargando e inicializándolo si es necesario;

para cada uno de los identificadores especificados en la cláusula import:

compruebe si el módulo importado tiene un atributo con ese nombre

de lo contrario, intente importar un submódulo con ese nombre y luego verifique el módulo importado nuevamente para ese atributo

si el atributo no se encuentra, ImportError es lanzada.

de lo contrario, una referencia a ese valor se almacena en el espacio de nombres local, usando el nombre en la cláusula as si ésta está presente, de lo contrario usando el nombre del atributo

Ejemplos:

import foo                 # foo imported and bound locally
import foo.bar.baz         # foo, foo.bar, and foo.bar.baz imported, foo bound locally
import foo.bar.baz as fbb  # foo, foo.bar, and foo.bar.baz imported, foo.bar.baz bound as fbb
from foo.bar import baz    # foo, foo.bar, and foo.bar.baz imported, foo.bar.baz bound as baz
from foo import attr       # foo imported and foo.attr bound as attr

Si la lista de identificadores se reemplaza por una estrella (’*’), todos los nombres públicos definidos en el módulo se enlazan en el espacio de nombres local para el ámbito donde ocurre la declaración import.

Los nombres públicos definidos por un módulo se determinan al verificar el espacio de nombres del módulo en busca de una variable llamada __all__; si se define, debe ser una secuencia de cadenas que son nombres definidos o importados por ese módulo. Los nombres dados en __all__ se consideran públicos y se requiere que existan. Si __all__ no está definido, el conjunto de nombres públicos incluye todos los nombres que se encuentran en el espacio de nombres del módulo que no comienzan con un carácter de subrayado (’_’). __all__ debe contener la API pública completa. Su objetivo es evitar la exportación accidental de elementos que no forman parte de la API (como los módulos de biblioteca que se importaron y utilizaron dentro del módulo).

La forma de importación comodín — from module import * — sólo se permite a nivel módulo. Intentar usarlo en una definición de clase o función lanza una SyntaxError.

Al especificar qué módulo importar, no es necesario especificar el nombre absoluto del módulo. Cuando un módulo o paquete está contenido dentro de otro paquete, es posible realizar una importación relativa dentro del mismo paquete superior sin tener que mencionar el nombre del paquete. Al usar puntos iniciales en el módulo o paquete especificado después de from, puede especificar qué tan alto recorrer la jerarquía actual del paquete sin especificar nombres exactos. Un punto inicial significa el paquete actual donde existe el módulo que realiza la importación. Dos puntos significan un nivel de paquete. Tres puntos son dos niveles, etc. Entonces, si ejecuta from . import mod de un módulo en el paquete pkg terminará importando``pkg.mod``. Si ejecuta from ..subpkg2 import mod desde dentro de pkg.subpkg1, importará pkg.subpkg2.mod. La especificación para las importaciones relativas está contenida en la sección Paquete Importaciones relativas.

importlib.import_module() se proporciona para soportar aplicaciones que determinan dinámicamente los módulos a cargar.

Lanza un auditing event import con argumentos module, filename, sys.path, sys.meta_path, sys.path_hooks.

7.11.1. Declaraciones Futuras

Una future statement es una directiva para el compilador para indicar que un módulo en particular debe compilarse usando la sintaxis o semántica que estará disponible en una versión futura específica de Python donde la característica se convierte en estándar.

La declaración futura está destinada a facilitar la migración a futuras versiones de Python que introducen cambios incompatibles en el lenguaje. Permite el uso de las nuevas funciones por módulo antes del lanzamiento en el que la función se convierte en estándar.

future_stmt ::=  "from" "__future__" "import" feature ["as" identifier]
                 ("," feature ["as" identifier])*
                 | "from" "__future__" "import" "(" feature ["as" identifier]
                 ("," feature ["as" identifier])* [","] ")"
feature     ::=  identifier

Una declaración futura debe aparecer cerca de la parte superior del módulo. Las únicas líneas que pueden aparecer antes de una declaración futura son:

el docstring del módulo (si hay),

comentarios,

lineas en blanco, y

otras declaraciones futuras.

La única característica en Python 3.7 que requiere el uso la declaración futuro es annotations.

108/5000 Python 3 aún reconoce todas las características históricas habilitadas por la declaración futura. La lista incluye absolute_import, division, generators, generator_stop, unicode_literals, print_function, nested_scopes y with_statement. Todos son redundantes porque siempre están habilitados y solo se conservan para compatibilidad con versiones anteriores.

Una declaración futura se reconoce y se trata especialmente en el momento de la compilación: los cambios en la semántica de las construcciones centrales a menudo se implementan generando código diferente. Incluso puede darse el caso de que una nueva característica introduzca una nueva sintaxis incompatible (como una nueva palabra reservada), en cuyo caso el compilador puede necesitar analizar el módulo de manera diferente. Tales decisiones no pueden postergarse hasta el tiempo de ejecución.

Para cualquier versión dada, el compilador sabe qué nombres de características se han definido y lanza un error en tiempo de compilación si una declaración futura contiene una característica que no conoce.

La semántica del tiempo de ejecución directo es la misma que para cualquier declaración de importación: hay un módulo estándar __future__, que se describe más adelante, y se importará de la forma habitual en el momento en que se ejecute la declaración futura.

La interesante semántica del tiempo de ejecución depende de la característica específica habilitada por la declaración futura.

Notar que no hay nada especial a cerca de la declaración:

import __future__ [as name]

Esa no es una declaración futura; es una declaración de importación ordinaria sin restricciones especiales de semántica o sintaxis.

El código compilado por llamadas a las funciones integradas exec() y compile() que ocurren en un módulo M que contiene una declaración futura usará, por defecto, la nueva sintaxis o semántica asociada con la declaración futura. Esto se puede controlar mediante argumentos opcionales para compile() — consulte la documentación de esa función para obtener más detalles.

Una declaración futura escrita en una prompt interactiva del intérprete entrará en vigencia durante el resto de la sesión de dicho intérprete. Si un intérprete se inicia con la opción -i, se le pasa un nombre de script para ejecutar, y el script incluye una declaración futura, ésta estará en efecto en la sesión interactiva iniciada después de que se ejecute el script.

Ver también

PEP 236 [https://www.python.org/dev/peps/pep-0236] - Vuelta al __future__

La propuesta original para el mecanismo __future__.

7.12. La declaración global

global_stmt ::=  "global" identifier ("," identifier)*

La declaración global es una declaración que se aplica a todo el bloque de código actual. Significa que los identificadores enumerados deben interpretarse como globales. Sería imposible asignar a una variable global sin global, aunque las variables libres pueden referirse a globales sin ser declaradas globales.

Los nombres enumerados en una declaración global no deben usarse en el mismo bloque de código que precede textualmente a la declaración global.

Los nombres enumerados en una declaración global no deben definirse como parámetros formales o en un objetivo de control de bucle for, definición de class, definición de función, declaración import o anotación de variable.

CPython implementation detail: La implementación actual no hace cumplir algunas de estas restricciones, pero los programas no deben abusar de esta libertad, ya que las implementaciones futuras pueden imponerlas o cambiar silenciosamente el significado del programa.

** Nota del programador: ** global es una directiva para el analizador. Se aplica solo al código analizado al mismo tiempo que la declaración global. En particular, una declaración global contenida en una cadena u objeto de código suministrado a la función incorporada exec() no afecta el bloque de código que contiene la llamada a la función, y el código contenido en dicha función una cadena no se ve afectada por la declaración keyword:!global en el código que contiene la llamada a la función. Lo mismo se aplica a las funciones eval() y compile().

7.13. La declaración nonlocal

nonlocal_stmt ::=  "nonlocal" identifier ("," identifier)*

La declaración nonlocal hace que los identificadores enumerados se refieran a variables vinculadas previamente en el ámbito circundante más cercano excluyendo globales. Esto es importante porque el comportamiento predeterminado para el enlace es buscar primero en el espacio de nombres local. La declaración permite que el código encapsulado vuelva a vincular variables fuera del ámbito local además del ámbito global (módulo).

Los nombres enumerados en una instrucción nonlocal, a diferencia de los enumerados en una instrucción global, deben hacer referencia a enlaces preexistentes en un ámbito adjunto (no se puede determinar el ámbito en el que se debe crear un nuevo enlace inequívocamente).

Los nombres enumerados en la declaración nonlocal no deben colisionar con las enlaces preexistentes en el ámbito local.

Ver también

PEP 3104 [https://www.python.org/dev/peps/pep-3104] - Acceso a Nombres de Ámbitos externos

La especificación para la declaración nonlocal.

8. Sentencias compuestas

Las sentencias compuestas contienen (grupos de) otras sentencias; estas afectan o controlan la ejecución de esas otras sentencias de alguna manera. En general, las sentencias compuestas abarcan varias líneas, aunque en representaciones simples una sentencia compuesta completa puede estar contenida en una línea.

Las sentencias if, while y for implementan construcciones de control de flujo tradicionales. try especifica gestores de excepción o código de limpieza para un grupo de sentencias, mientras que las sentencias with permite la ejecución del código de inicialización y finalización alrededor de un bloque de código. Las definiciones de función y clase también son sentencias sintácticamente compuestas.

Una sentencia compuesta consta de una o más “cláusulas”. Una cláusula consta de un encabezado y una “suite”. Los encabezados de cláusula de una declaración compuesta particular están todos en el mismo nivel de indentación. Cada encabezado de cláusula comienza con una palabra clave de identificación única y termina con dos puntos. Una suite es un grupo de sentencias controladas por una cláusula. Una suite puede ser una o más sentencias simples separadas por punto y coma en la misma línea como el encabezado, siguiendo los dos puntos del encabezado, o puede ser una o puede ser una o más declaraciones indentadas en líneas posteriores. Solo la última forma de una suite puede contener sentencias compuestas anidadas; lo siguiente es ilegal, principalmente porque no estaría claro a qué cláusula if seguido de la cláusula else hace referencia:

if test1: if test2: print(x)

También tenga en cuenta que el punto y coma se une más apretado que los dos puntos en este contexto, de modo que en el siguiente ejemplo, todas o ninguna de las llamadas print() se ejecutan:

if x < y < z: print(x); print(y); print(z)

Resumiendo:

compound_stmt ::=  if_stmt
                   | while_stmt
                   | for_stmt
                   | try_stmt
                   | with_stmt
                   | funcdef
                   | classdef
                   | async_with_stmt
                   | async_for_stmt
                   | async_funcdef
suite         ::=  stmt_list NEWLINE | NEWLINE INDENT statement+ DEDENT
statement     ::=  stmt_list NEWLINE | compound_stmt
stmt_list     ::=  simple_stmt (";" simple_stmt)* [";"]

Tenga en cuenta que las sentencias siempre terminan en un NEWLINE posiblemente seguida de DEDENT. También tenga en cuenta que las cláusulas de continuación opcionales siempre comienzan con una palabra clave que no puede iniciar una sentencia, por lo tanto, no hay ambigüedades (el problema de “colgado if” se resuelve en Python al requerir que las sentencias anidadas if deben estar indentadas).

El formato de las reglas gramaticales en las siguientes secciones coloca cada cláusula en una línea separada para mayor claridad.

8.1. La sentencia if

La sentencia if se usa para la ejecución condicional:

if_stmt ::=  "if" assignment_expression ":" suite
             ("elif" assignment_expression ":" suite)*
             ["else" ":" suite]

Selecciona exactamente una de las suites evaluando las expresiones una por una hasta que se encuentre una verdadera (vea la sección Operaciones booleanas para la definición de verdadero y falso); entonces esa suite se ejecuta (y ninguna otra parte de la sentencia if se ejecuta o evalúa). Si todas las expresiones son falsas, se ejecuta la suite de cláusulas else, si está presente.

8.2. La sentencia while

La sentencia while se usa para la ejecución repetida siempre que una expresión sea verdadera:

while_stmt ::=  "while" assignment_expression ":" suite
                ["else" ":" suite]

Esto prueba repetidamente la expresión y, si es verdadera, ejecuta la primera suite; si la expresión es falsa (que puede ser la primera vez que se prueba), se ejecuta el conjunto de cláusulas else, si está presente, y el bucle termina.

La sentencia break ejecutada en la primer suite termina el bucle sin ejecutar la suite de cláusulas else. La sentencia continue ejecutada en la primera suite omite el resto de la suite y vuelve a probar la expresión.

8.3. La sentencia for

La sentencia for se usa para iterar sobre los elementos de una secuencia (como una cadena de caracteres, tupla o lista) u otro objeto iterable:

for_stmt ::=  "for" target_list "in" expression_list ":" suite
              ["else" ":" suite]

La lista de expresiones se evalúa una vez; debería producir un objeto iterable. Se crea un iterador para el resultado de la expression_list. La suite se ejecuta una vez para cada elemento proporcionado por el iterador, en el orden retornado por el iterador. Cada elemento a su vez se asigna a la lista utilizando las reglas estándar para las asignaciones (ver Declaraciones de asignación), y luego se ejecuta la suite. Cuando los elementos están agotados (que es inmediatamente cuando la secuencia está vacía o un iterador genera una excepción del tipo StopIteration), la suite en la cláusula else, si está presente, se ejecuta y el bucle termina.

La sentencia break ejecutada en la primera suite termina el bucle sin ejecutar el conjunto de cláusulas else. La sentencia continue ejecutada en la primera suite omite el resto de las cláusulas y continúa con el siguiente elemento, o con la cláusula else si no hay un elemento siguiente.

El bucle for realiza asignaciones a las variables en la lista. Esto sobrescribe todas las asignaciones anteriores a esas variables, incluidas las realizadas en la suite del bucle for:

for i in range(10):
    print(i)
    i = 5             # this will not affect the for-loop
                      # because i will be overwritten with the next
                      # index in the range

Los nombres en la lista no se eliminan cuando finaliza el bucle, pero si la secuencia está vacía, el bucle no les habrá asignado nada. Sugerencia: la función incorporada range() retorna un iterador de enteros adecuado para emular el efecto de Pascal for i := a to b do; por ejemplo, list(range(3)) retorna la lista [0, 1, 2].

Nota

Hay una sutileza cuando la secuencia está siendo modificada por el bucle (esto solo puede ocurrir para secuencias mutables, por ejemplo, listas). Se utiliza un contador interno para realizar un seguimiento de qué elemento se usa a continuación, y esto se incrementa en cada iteración. Cuando este contador ha alcanzado la longitud de la secuencia, el bucle termina. Esto significa que si la suite elimina el elemento actual (o anterior) de la secuencia, se omitirá el siguiente elemento (ya que obtiene el índice del elemento actual que ya ha sido tratado). Del mismo modo, si la suite inserta un elemento en la secuencia anterior al elemento actual, el elemento actual será tratado nuevamente la próxima vez a través del bucle. Esto puede conducir a errores graves que se pueden evitar haciendo una copia temporal usando una porción de la secuencia completa, por ejemplo,

for x in a[:]:
    if x < 0: a.remove(x)

8.4. La sentencia try

La sentencia try es especifica para gestionar excepciones o código de limpieza para un grupo de sentencias:

try_stmt  ::=  try1_stmt | try2_stmt
try1_stmt ::=  "try" ":" suite
               ("except" [expression ["as" identifier]] ":" suite)+
               ["else" ":" suite]
               ["finally" ":" suite]
try2_stmt ::=  "try" ":" suite
               "finally" ":" suite

The except clause(s) specify one or more exception handlers. When no exception occurs in the try clause, no exception handler is executed. When an exception occurs in the try suite, a search for an exception handler is started. This search inspects the except clauses in turn until one is found that matches the exception. An expression-less except clause, if present, must be last; it matches any exception. For an except clause with an expression, that expression is evaluated, and the clause matches the exception if the resulting object is «compatible» with the exception. An object is compatible with an exception if the object is the class or a non-virtual base class of the exception object, or a tuple containing an item that is the class or a non-virtual base class of the exception object.

Si ninguna cláusula except coincide con la excepción, la búsqueda de un gestor de excepciones continúa en el código circundante y en la pila de invocación. 1

Si la evaluación de una expresión en el encabezado de una cláusula except genera una excepción, la búsqueda original de un gestor se cancela y se inicia la búsqueda de la nueva excepción en el código circundante y en la pila de llamadas (se trata como si toda la sentencia try provocó la excepción).

Cuando se encuentra una cláusula except coincidente, la excepción se asigna al destino especificado después de la palabra clave as en esa cláusula except, si está presente, y se ejecuta la suite de cláusulas except. Todas las cláusulas except deben tener un bloque ejecutable. Cuando se alcanza el final de este bloque, la ejecución continúa normalmente después de toda la sentencia try. (Esto significa que si existen dos gestores de errores anidados para la misma excepción, y la excepción ocurre en la cláusula try del gestor interno, el gestor externo no gestionará la excepción).

Cuando se ha asignado una excepción usando as target, se borra al final de la cláusula except. Esto es como si

except E as N:
    foo

fue traducido a

except E as N:
    try:
        foo
    finally:
        del N

Esto significa que la excepción debe asignarse a un nombre diferente para poder referirse a ella después de la cláusula except. Las excepciones se borran porque con el seguimiento vinculado a ellas, forman un bucle de referencia con el marco de la pila, manteniendo activos todos los locales en esa pila hasta que ocurra la próxima recolección de basura.

Antes de que se ejecute un conjunto de cláusulas except, los detalles sobre la excepción se almacenan en el módulo sys y se puede acceder a través de sys.exc_info(). sys.exc_info() retorna 3 tuplas que consisten en la clase de excepción, la instancia de excepción y un objeto de rastreo (ver sección Jerarquía de tipos estándar) que identifica el punto en el programa donde ocurrió la excepción. Lo valores sys.exc_info() se restauran a sus valores anteriores (antes de la llamada) al regresar de una función que manejó una excepción.

La cláusula opcional else se ejecuta si el flujo de control sale de la suite try, no se produjo ninguna excepción, y no se ejecutó la sentencia return, continue o break. Las excepciones en la cláusula else no se gestionaron con las cláusulas precedentes except.

Si está presente finally, esto especifica un gestor de “limpieza”. La cláusula try se ejecuta, incluidas las cláusulas except y else. Si se produce una excepción en cualquiera de las cláusulas y no se maneja, la excepción se guarda temporalmente. Se ejecuta la cláusula finally. Si hay una excepción guardada, se vuelve a generar al final de la cláusula finally. Si la cláusula finally genera otra excepción, la excepción guardada se establece como el contexto de la nueva excepción. Si la cláusula finally ejecuta una sentencia return, break o continue, la excepción guardada se descarta:

>>> def f():
...     try:
...         1/0
...     finally:
...         return 42
...
>>> f()
42

La información de excepción no está disponible para el programa durante la ejecución de la cláusula finally.

Cuando se ejecuta una sentencia return, break o continue en la suite try de un try…la sentencia finally, la cláusula finally también se ejecuta “al salir”.

El valor de retorno de una función está determinado por la última sentencia return ejecutada. Dado que la cláusula finally siempre se ejecuta, una sentencia return ejecutada en la cláusula finally siempre será la última ejecutada:

>>> def foo():
...     try:
...         return 'try'
...     finally:
...         return 'finally'
...
>>> foo()
'finally'

Se puede encontrar información adicional sobre las excepciones en la sección Excepciones, e información sobre el uso de la sentencia raise, para generar excepciones se puede encontrar en la sección La declaración raise.

Distinto en la versión 3.8: Antes de Python 3.8, una sentencia continue era ilegal en la cláusula finally debido a un problema con la implementación.

8.5. La sentencia with

La sentencia with se usa para ajustar la ejecución de un bloque con métodos definidos por un administrador de contexto (ver sección Gestores de Contexto en la Declaración with). Esto permite que los patrones de uso comunes try…except…finally se encapsulen para una reutilización conveniente.

with_stmt ::=  "with" with_item ("," with_item)* ":" suite
with_item ::=  expression ["as" target]

La ejecución de la sentencia with con un «item» se realiza de la siguiente manera:

La expresión de contexto (la expresión dada en with_item) se evalúa para obtener un administrador de contexto.

El administrador de contexto __enter__() se carga para su uso posterior.

El administrador de contexto __exit__() se carga para su uso posterior.

Se invoca el método del administrador de contexto __enter__().

Si se incluyó el destino en la sentencia with, se le asigna el valor de retorno de __enter__().

Nota

La sentencia with garantiza que si el método __enter__() regresa sin error, entonces siempre se llamará a __exit__(). Por lo tanto, si se produce un error durante la asignación a la lista de destino, se tratará de la misma manera que si se produciría un error dentro de la suite. Vea el paso 6 a continuación.

La suite se ejecuta.

Se invoca el método del administrador de contexto __exit__(). Si una excepción causó la salida de la suite, su tipo, valor y rastreo se pasan como argumentos a __exit__(). De lo contrario, se proporcionan tres argumentos None.

Si se salió de la suite debido a una excepción, y el valor de retorno del método __exit__() fue falso, la excepción se vuelve a plantear. Si el valor de retorno era verdadero, la excepción se suprime y la ejecución continúa con la sentencia que sigue a la sentencia with.

Si se salió de la suite por cualquier motivo que no sea una excepción, el valor de retorno de __exit__() se ignora y la ejecución continúa en la ubicación normal para el tipo de salida que se tomó.

El siguiente código:

with EXPRESSION as TARGET:
    SUITE

es semánticamente equivalente a:

manager = (EXPRESSION)
enter = type(manager).__enter__
exit = type(manager).__exit__
value = enter(manager)
hit_except = False

try:
    TARGET = value
    SUITE
except:
    hit_except = True
    if not exit(manager, *sys.exc_info()):
        raise
finally:
    if not hit_except:
        exit(manager, None, None, None)

Con más de un elemento, los administradores de contexto se procesan como si varias sentencias with estuvieran anidadas:

with A() as a, B() as b:
    SUITE

es semánticamente equivalente a:

with A() as a:
    with B() as b:
        SUITE

Distinto en la versión 3.1: Soporte para múltiples expresiones de contexto.

Ver también

PEP 343 [https://www.python.org/dev/peps/pep-0343] - La sentencia «with»

La especificación, antecedentes y ejemplos de la sentencia de Python with.

8.6. Definiciones de funciones

Una definición de función define una función objeto determinada por el usuario (consulte la sección Jerarquía de tipos estándar):

funcdef                   ::=  [decorators] "def" funcname "(" [parameter_list] ")"
                               ["->" expression] ":" suite
decorators                ::=  decorator+
decorator                 ::=  "@" assignment_expression NEWLINE
parameter_list            ::=  defparameter ("," defparameter)* "," "/" ["," [parameter_list_no_posonly]]
                                 | parameter_list_no_posonly
parameter_list_no_posonly ::=  defparameter ("," defparameter)* ["," [parameter_list_starargs]]
                               | parameter_list_starargs
parameter_list_starargs   ::=  "*" [parameter] ("," defparameter)* ["," ["**" parameter [","]]]
                               | "**" parameter [","]
parameter                 ::=  identifier [":" expression]
defparameter              ::=  parameter ["=" expression]
funcname                  ::=  identifier

Una definición de función es una sentencia ejecutable. Su ejecución vincula el nombre de la función en el espacio de nombres local actual a un objeto de función (un contenedor alrededor del código ejecutable para la función). Este objeto de función contiene una referencia al espacio de nombres global actual como el espacio de nombres global que se utilizará cuando se llama a la función.

La definición de la función no ejecuta el cuerpo de la función; esto se ejecuta solo cuando se llama a la función. 2

Una definición de función puede estar envuelta por una o más expresiones decorator. Las expresiones de decorador se evalúan cuando se define la función, en el ámbito que contiene la definición de la función. El resultado debe ser invocable, la cual se invoca con el objeto de función como único argumento. El valor retornado está vinculado al nombre de la función en lugar del objeto de la función. Se aplican múltiples decoradores de forma anidada. Por ejemplo, el siguiente código

@f1(arg)
@f2
def func(): pass

es más o menos equivalente a

def func(): pass
func = f1(arg)(f2(func))

excepto que la función original no está vinculada temporalmente al nombre func.

Distinto en la versión 3.9: Las funciones se pueden decorar con cualquier token válido assignment_expression. Anteriormente, la gramática era mucho más restrictiva; ver PEP 614 [https://www.python.org/dev/peps/pep-0614] para más detalles.

Cuando uno o más parameters tienen la forma parameter = expression, se dice que la función tiene «valores de parámetros predeterminados». Para un parámetro con un valor predeterminado, el correspondiente argument puede omitirse desde una llamada, en cuyo caso se sustituye el valor predeterminado del parámetro. Si un parámetro tiene un valor predeterminado, todos los parámetros siguientes hasta el «*» también deben tener un valor predeterminado — esta es una restricción sintáctica que la gramática no expresa.

Los valores de los parámetros predeterminados se evalúan de izquierda a derecha cuando se ejecuta la definición de la función. Esto significa que la expresión se evalúa una vez, cuando se define la función, y que se utiliza el mismo valor «precalculado» para cada llamada . Esto es especialmente importante para entender cuando un parámetro predeterminado es un objeto mutable, como una lista o un diccionario: si la función modifica el objeto (por ejemplo, al agregar un elemento a una lista), el valor predeterminado está en efecto modificado. Esto generalmente no es lo que se pretendía. Una forma de evitar esto es usar None como valor predeterminado y probarlo explícitamente en el cuerpo de la función, por ejemplo:

def whats_on_the_telly(penguin=None):
    if penguin is None:
        penguin = []
    penguin.append("property of the zoo")
    return penguin

Function call semantics are described in more detail in section Invocaciones. A function call always assigns values to all parameters mentioned in the parameter list, either from positional arguments, from keyword arguments, or from default values. If the form «*identifier» is present, it is initialized to a tuple receiving any excess positional parameters, defaulting to the empty tuple. If the form «**identifier» is present, it is initialized to a new ordered mapping receiving any excess keyword arguments, defaulting to a new empty mapping of the same type. Parameters after «*» or «*identifier» are keyword-only parameters and may only be passed by keyword arguments. Parameters before «/» are positional-only parameters and may only be passed by positional arguments.

Distinto en la versión 3.8: The / function parameter syntax may be used to indicate positional-only parameters. See PEP 570 [https://www.python.org/dev/peps/pep-0570] for details.

Los parámetros pueden tener annotation de la forma «: expression» que sigue al nombre del parámetro. Cualquier parámetro puede tener una anotación, incluso las de la forma *identifier o ** identifier. Las funciones pueden tener una anotación «return» de la forma «-> expression» después de la lista de parámetros. Estas anotaciones pueden ser cualquier expresión válida de Python. La presencia de anotaciones no cambia la semántica de una función. Los valores de anotación están disponibles como valores de un diccionario con los nombres de los parámetros en el atributo __annotations__ del objeto de la función. Si se usa annotations importada desde __future__, las anotaciones se conservan como cadenas de caracteres en tiempo de ejecución que permiten la evaluación pospuesta. De lo contrario, se evalúan cuando se ejecuta la definición de la función. En este caso, las anotaciones pueden evaluarse en un orden diferente al que aparecen en el código fuente.

También es posible crear funciones anónimas (funciones no vinculadas a un nombre), para uso inmediato en expresiones. Utiliza expresiones lambda, descritas en la sección Lambdas. Tenga en cuenta que la expresión lambda es simplemente una abreviatura para una definición de función simplificada; una función definida en una sentencia «def» puede pasarse o asignarse a otro nombre al igual que una función definida por una expresión lambda. La forma «def» es en realidad más poderosa ya que permite la ejecución de múltiples sentencias y anotaciones.

Nota del programador: Las funciones son objetos de la primera-clase. Una sentencia «def» ejecutada dentro de una definición de función define una función local que se puede retornar o pasar. Las variables libres utilizadas en la función anidada pueden acceder a las variables locales de la función que contiene el def. Vea la sección Nombres y vínculos para más detalles.

Ver también

PEP 3107 [https://www.python.org/dev/peps/pep-3107] - Anotaciones de funciones

La especificación original para anotaciones de funciones.

PEP 484 [https://www.python.org/dev/peps/pep-0484] - Sugerencias de tipo

Definición de un significado estándar para anotaciones: sugerencias de tipo.

PEP 526 [https://www.python.org/dev/peps/pep-0526] - Sintaxis para anotaciones variables

Capacidad para escribir declaraciones de variables indirectas, incluidas variables de clase y variables de instancia

PEP 563 [https://www.python.org/dev/peps/pep-0563] - Evaluación pospuesta de anotaciones

Admite referencias directas dentro de las anotaciones conservando las anotaciones en forma de cadena de caracteres en tiempo de ejecución en lugar de una evaluación apresurada.

8.7. Definiciones de clase

Una definición de clase define un objeto de clase (ver sección Jerarquía de tipos estándar):

classdef    ::=  [decorators] "class" classname [inheritance] ":" suite
inheritance ::=  "(" [argument_list] ")"
classname   ::=  identifier

Una definición de clase es una sentencia ejecutable. La lista de herencia generalmente proporciona una lista de clases base (consulte Metaclases para usos más avanzados), por lo que cada elemento de la lista debe evaluar a un objeto de clase que permita la subclasificación. Las clases sin una lista de herencia heredan, por defecto, de la clase base object; por lo tanto,

class Foo:
    pass

es equivalente a

class Foo(object):
    pass

La suite de la clase se ejecuta en un nuevo marco de ejecución (ver Nombres y vínculos), usando un espacio de nombres local recién creado y el espacio de nombres global original. (Por lo general, el bloque contiene principalmente definiciones de funciones). Cuando la suite de la clase finaliza la ejecución, su marco de ejecución se descarta pero se guarda su espacio de nombres local. 3 Luego se crea un objeto de clase utilizando la lista de herencia para las clases base y el espacio de nombres local guardado para el diccionario de atributos. El nombre de la clase está vinculado a este objeto de clase en el espacio de nombres local original.

El orden en que se definen los atributos en el cuerpo de la clase se conserva en el __dict__ de la nueva clase. Tenga en cuenta que esto es confiable solo justo después de crear la clase y solo para las clases que se definieron utilizando la sintaxis de definición.

La creación de clases se puede personalizar en gran medida usando metaclasses.

Las clases también se pueden decorar: al igual que cuando se decoran funciones,

@f1(arg)
@f2
class Foo: pass

es más o menos equivalente a

class Foo: pass
Foo = f1(arg)(f2(Foo))

Las reglas de evaluación para las expresiones de decorador son las mismas que para los decoradores de funciones. El resultado se vincula al nombre de la clase.

Distinto en la versión 3.9: Las clases se pueden decorar con cualquier token válido assignment_expression. Anteriormente, la gramática era mucho más restrictiva; ver PEP 614 [https://www.python.org/dev/peps/pep-0614] para más detalles.

** Nota del programador: ** Las variables definidas en la definición de la clase son atributos de clase; son compartidos por instancias. Los atributos de instancia se pueden establecer en un método con self.name = value. Se puede acceder a los atributos de clase e instancia a través de la notación «self.name», y un atributo de instancia oculta un atributo de clase con el mismo nombre cuando se accede de esta manera. Los atributos de clase se pueden usar como valores predeterminados para los atributos de instancia, pero el uso de valores mutables puede generar resultados inesperados. Descriptors se puede usar para crear variables de instancia con diferentes detalles de implementación.

Ver también

PEP 3115 [https://www.python.org/dev/peps/pep-3115] - Metaclases en Python 3000

La propuesta que cambió la declaración de metaclases a la sintaxis actual y la semántica de cómo se construyen las clases con metaclases.

PEP 3129 [https://www.python.org/dev/peps/pep-3129] - Decoradores de clase

La propuesta que agregó decoradores de clase. Los decoradores de funciones y métodos se introdujeron en PEP 318 [https://www.python.org/dev/peps/pep-0318].

8.8. Corrutinas

Nuevo en la versión 3.5.

8.8.1. Definición de la función corrutina

async_funcdef ::=  [decorators] "async" "def" funcname "(" [parameter_list] ")"
                   ["->" expression] ":" suite

La ejecución de las corrutinas de Python puede suspenderse y reanudarse en muchos puntos (ver coroutine). Dentro del cuerpo de una función de corrutina, los identificadores await y async se convierten en palabras claves reservadas; las expresiones await, async for y async with solo se puede usar en los cuerpos de funciones de corrutina.

Las funciones definidas con la sintaxis async def siempre son funciones de corrutina, incluso si no contienen palabras claves await o async.

Es un error del tipo SyntaxError usar una expresión yield from dentro del cuerpo de una función de corrutina.

Un ejemplo de una función corrutina:

async def func(param1, param2):
    do_stuff()
    await some_coroutine()

8.8.2. La sentencia async for

async_for_stmt ::=  "async" for_stmt

Un asynchronous iterable proporciona un método __aiter__ que retorna directamente un asynchronous iterator, que puede llamar a código asincrónico en su método __anext__.

La sentencia async for permite una iteración apropiada sobre iteradores asincrónicos.

El siguiente código:

async for TARGET in ITER:
    SUITE
else:
    SUITE2

Es semánticamente equivalente a:

iter = (ITER)
iter = type(iter).__aiter__(iter)
running = True

while running:
    try:
        TARGET = await type(iter).__anext__(iter)
    except StopAsyncIteration:
        running = False
    else:
        SUITE
else:
    SUITE2

Ver también __aiter__() y __anext__() para más detalles.

Es un error del tipo SyntaxError usar una sentencia async for fuera del cuerpo de una función de corrutina.

8.8.3. La sentencia async with

async_with_stmt ::=  "async" with_stmt

Un asynchronous context manager es un context manager que puede suspender la ejecución en sus métodos enter y exit.

El siguiente código:

async with EXPRESSION as TARGET:
    SUITE

es semánticamente equivalente a:

manager = (EXPRESSION)
aenter = type(manager).__aenter__
aexit = type(manager).__aexit__
value = await aenter(manager)
hit_except = False

try:
    TARGET = value
    SUITE
except:
    hit_except = True
    if not await aexit(manager, *sys.exc_info()):
        raise
finally:
    if not hit_except:
        await aexit(manager, None, None, None)

Ver también __aenter__() y __aexit__() para más detalles.

Es un error del tipo SyntaxError usar una sentencia async with fuera del cuerpo de una función de corrutina.

Ver también

PEP 492 [https://www.python.org/dev/peps/pep-0492] - Corrutinas con sintaxis async y await

La propuesta que convirtió a las corrutinas en un concepto independiente adecuado en Python, y agregó una sintaxis de soporte.

Notas al pie

1

La excepción se propaga a la pila de invocación a menos que haya una cláusula finally que provoque otra excepción. Esa nueva excepción hace que se pierda la anterior.

2

Una cadena de caracteres literal que aparece como la primera sentencia en el cuerpo de la función se transforma en el atributo __doc__ de la función y, por lo tanto, en funciones docstring.

3

Una cadena de caracteres literal que aparece como la primera sentencia en el cuerpo de la clase se transforma en el elemento del espacio de nombre __doc__ y, por lo tanto, de la clase docstring.

9. Componentes de nivel superior

El intérprete de Python puede obtener su entrada de varias fuentes: de un script que se le pasa como entrada estándar o como argumento del programa, escrito interactivamente, de un archivo fuente de módulo, etc. Este capítulo proporciona la sintaxis utilizada en estos casos.

9.1. Programas completos de Python

Si bien una especificación de lenguaje no necesita prescribir cómo se invoca al intérprete de lenguaje, es útil tener una noción de un programa completo de Python. Un programa completo de Python se ejecuta en un entorno mínimamente inicializado: todos los módulos estándar e integrados están disponibles, pero ninguno ha sido inicializado, excepto sys (varios servicios del sistema), builtins (funciones integradas, excepciones y Ninguno) y __main__. Este último se utiliza para proporcionar el espacio de nombres local y global para la ejecución del programa completo.

La sintaxis de un programa completo de Python es la entrada de archivos, que se describe en la siguiente sección.

El intérprete también puede invocarse en modo interactivo; en este caso, no lee ni ejecuta un programa completo, sino que lee y ejecuta una instrucción (posiblemente compuesta) a la vez. El entorno inicial es idéntico al de un programa completo; cada instrucción se ejecuta en el espacio de nombres de __main__.

Se puede pasar un programa completo al intérprete en tres formas: con la opción -c string de línea de comando, como un archivo pasado como primer argumento de línea de comando o como entrada estándar. Si el archivo o la entrada estándar es un dispositivo tty, el intérprete ingresa al modo interactivo; de lo contrario, ejecuta el archivo como un programa completo.

9.2. Entrada de archivo

Todas las entradas leídas de archivos no interactivos tienen la misma forma:

file_input ::=  (NEWLINE | statement)*

Esta sintaxis se utiliza en las siguientes situaciones:

al analizar un programa completo de Python (desde un archivo o desde una cadena);

al analizar un módulo;

al analizar una cadena pasada a la función: exec();

9.3. Entrada interactiva

La entrada en modo interactivo se analiza utilizando la siguiente gramática:

interactive_input ::=  [stmt_list] NEWLINE | compound_stmt NEWLINE

Tenga en cuenta que una declaración compuesta (de nivel superior) debe ir seguida de una línea en blanco en modo interactivo; esto es necesario para ayudar al analizador sintáctico a detectar el final de la entrada.

9.4. Entrada de expresión

eval() se utiliza para la entrada de expresiones. Ignora los espacios en blanco iniciales. El argumento de cadena para eval() debe tener la siguiente forma:

eval_input ::=  expression_list NEWLINE*

10. Especificación completa de la gramática

Esta es la gramática completa de Python, derivada directamente de la gramática utilizada para generar el analizador CPython (ver Grammar/python.gram [https://github.com/python/cpython/tree/3.9/Grammar/python.gram]). La versión aquí omite detalles relacionados con la generación de código y la recuperación de errores.

La notación es una mezcla de EBNF [https://es.wikipedia.org/wiki/BNF_extendido] y PEG [https://en.wikipedia.org/wiki/Parsing_expression_grammar]. En particular, & seguido de un símbolo, ficha o grupo entre paréntesis indica una anticipación positiva (es decir, se requiere que coincida pero no se consume), mientras que ! Indica una anticipación negativa (es decir, se requiere _no_ para partido). Usamos el separador | para referirnos a la «elección ordenada» de PEG (escrito como / en las gramáticas tradicionales de PEG).

# PEG grammar for Python

file: [statements] ENDMARKER
interactive: statement_newline
eval: expressions NEWLINE* ENDMARKER
func_type: '(' [type_expressions] ')' '->' expression NEWLINE* ENDMARKER
fstring: star_expressions

# type_expressions allow */** but ignore them
type_expressions:
    | ','.expression+ ',' '*' expression ',' '**' expression
    | ','.expression+ ',' '*' expression
    | ','.expression+ ',' '**' expression
    | '*' expression ',' '**' expression
    | '*' expression
    | '**' expression
    | ','.expression+

statements: statement+
statement: compound_stmt  | simple_stmt
statement_newline:
    | compound_stmt NEWLINE
    | simple_stmt
    | NEWLINE
    | ENDMARKER
simple_stmt:
    | small_stmt !';' NEWLINE  # Not needed, there for speedup
    | ';'.small_stmt+ [';'] NEWLINE
# NOTE: assignment MUST precede expression, else parsing a simple assignment
# will throw a SyntaxError.
small_stmt:
    | assignment
    | star_expressions
    | return_stmt
    | import_stmt
    | raise_stmt
    | 'pass'
    | del_stmt
    | yield_stmt
    | assert_stmt
    | 'break'
    | 'continue'
    | global_stmt
    | nonlocal_stmt
compound_stmt:
    | function_def
    | if_stmt
    | class_def
    | with_stmt
    | for_stmt
    | try_stmt
    | while_stmt

# NOTE: annotated_rhs may start with 'yield'; yield_expr must start with 'yield'
assignment:
    | NAME ':' expression ['=' annotated_rhs ]
    | ('(' single_target ')'
         | single_subscript_attribute_target) ':' expression ['=' annotated_rhs ]
    | (star_targets '=' )+ (yield_expr | star_expressions) !'=' [TYPE_COMMENT]
    | single_target augassign ~ (yield_expr | star_expressions)

augassign:
    | '+='
    | '-='
    | '*='
    | '@='
    | '/='
    | '%='
    | '&='
    | '|='
    | '^='
    | '<<='
    | '>>='
    | '**='
    | '//='

global_stmt: 'global' ','.NAME+
nonlocal_stmt: 'nonlocal' ','.NAME+

yield_stmt: yield_expr

assert_stmt: 'assert' expression [',' expression ]

del_stmt:
    | 'del' del_targets &(';' | NEWLINE)

import_stmt: import_name | import_from
import_name: 'import' dotted_as_names
# note below: the ('.' | '...') is necessary because '...' is tokenized as ELLIPSIS
import_from:
    | 'from' ('.' | '...')* dotted_name 'import' import_from_targets
    | 'from' ('.' | '...')+ 'import' import_from_targets
import_from_targets:
    | '(' import_from_as_names [','] ')'
    | import_from_as_names !','
    | '*'
import_from_as_names:
    | ','.import_from_as_name+
import_from_as_name:
    | NAME ['as' NAME ]
dotted_as_names:
    | ','.dotted_as_name+
dotted_as_name:
    | dotted_name ['as' NAME ]
dotted_name:
    | dotted_name '.' NAME
    | NAME

if_stmt:
    | 'if' named_expression ':' block elif_stmt
    | 'if' named_expression ':' block [else_block]
elif_stmt:
    | 'elif' named_expression ':' block elif_stmt
    | 'elif' named_expression ':' block [else_block]
else_block: 'else' ':' block

while_stmt:
    | 'while' named_expression ':' block [else_block]

for_stmt:
    | 'for' star_targets 'in' ~ star_expressions ':' [TYPE_COMMENT] block [else_block]
    | ASYNC 'for' star_targets 'in' ~ star_expressions ':' [TYPE_COMMENT] block [else_block]

with_stmt:
    | 'with' '(' ','.with_item+ ','? ')' ':' block
    | 'with' ','.with_item+ ':' [TYPE_COMMENT] block
    | ASYNC 'with' '(' ','.with_item+ ','? ')' ':' block
    | ASYNC 'with' ','.with_item+ ':' [TYPE_COMMENT] block
with_item:
    | expression 'as' star_target &(',' | ')' | ':')
    | expression

try_stmt:
    | 'try' ':' block finally_block
    | 'try' ':' block except_block+ [else_block] [finally_block]
except_block:
    | 'except' expression ['as' NAME ] ':' block
    | 'except' ':' block
finally_block: 'finally' ':' block

return_stmt:
    | 'return' [star_expressions]

raise_stmt:
    | 'raise' expression ['from' expression ]
    | 'raise'

function_def:
    | decorators function_def_raw
    | function_def_raw

function_def_raw:
    | 'def' NAME '(' [params] ')' ['->' expression ] ':' [func_type_comment] block
    | ASYNC 'def' NAME '(' [params] ')' ['->' expression ] ':' [func_type_comment] block
func_type_comment:
    | NEWLINE TYPE_COMMENT &(NEWLINE INDENT)   # Must be followed by indented block
    | TYPE_COMMENT

params:
    | parameters

parameters:
    | slash_no_default param_no_default* param_with_default* [star_etc]
    | slash_with_default param_with_default* [star_etc]
    | param_no_default+ param_with_default* [star_etc]
    | param_with_default+ [star_etc]
    | star_etc

# Some duplication here because we can't write (',' | &')'),
# which is because we don't support empty alternatives (yet).
#
slash_no_default:
    | param_no_default+ '/' ','
    | param_no_default+ '/' &')'
slash_with_default:
    | param_no_default* param_with_default+ '/' ','
    | param_no_default* param_with_default+ '/' &')'

star_etc:
    | '*' param_no_default param_maybe_default* [kwds]
    | '*' ',' param_maybe_default+ [kwds]
    | kwds

kwds: '**' param_no_default

# One parameter.  This *includes* a following comma and type comment.
#
# There are three styles:
# - No default
# - With default
# - Maybe with default
#
# There are two alternative forms of each, to deal with type comments:
# - Ends in a comma followed by an optional type comment
# - No comma, optional type comment, must be followed by close paren
# The latter form is for a final parameter without trailing comma.
#
param_no_default:
    | param ',' TYPE_COMMENT?
    | param TYPE_COMMENT? &')'
param_with_default:
    | param default ',' TYPE_COMMENT?
    | param default TYPE_COMMENT? &')'
param_maybe_default:
    | param default? ',' TYPE_COMMENT?
    | param default? TYPE_COMMENT? &')'
param: NAME annotation?

annotation: ':' expression
default: '=' expression

decorators: ('@' named_expression NEWLINE )+

class_def:
    | decorators class_def_raw
    | class_def_raw
class_def_raw:
    | 'class' NAME ['(' [arguments] ')' ] ':' block

block:
    | NEWLINE INDENT statements DEDENT
    | simple_stmt

star_expressions:
    | star_expression (',' star_expression )+ [',']
    | star_expression ','
    | star_expression
star_expression:
    | '*' bitwise_or
    | expression

star_named_expressions: ','.star_named_expression+ [',']
star_named_expression:
    | '*' bitwise_or
    | named_expression
named_expression:
    | NAME ':=' ~ expression
    | expression !':='

annotated_rhs: yield_expr | star_expressions

expressions:
    | expression (',' expression )+ [',']
    | expression ','
    | expression
expression:
    | disjunction 'if' disjunction 'else' expression
    | disjunction
    | lambdef

lambdef:
    | 'lambda' [lambda_params] ':' expression

lambda_params:
    | lambda_parameters

# lambda_parameters etc. duplicates parameters but without annotations
# or type comments, and if there's no comma after a parameter, we expect
# a colon, not a close parenthesis.  (For more, see parameters above.)
#
lambda_parameters:
    | lambda_slash_no_default lambda_param_no_default* lambda_param_with_default* [lambda_star_etc]
    | lambda_slash_with_default lambda_param_with_default* [lambda_star_etc]
    | lambda_param_no_default+ lambda_param_with_default* [lambda_star_etc]
    | lambda_param_with_default+ [lambda_star_etc]
    | lambda_star_etc

lambda_slash_no_default:
    | lambda_param_no_default+ '/' ','
    | lambda_param_no_default+ '/' &':'
lambda_slash_with_default:
    | lambda_param_no_default* lambda_param_with_default+ '/' ','
    | lambda_param_no_default* lambda_param_with_default+ '/' &':'

lambda_star_etc:
    | '*' lambda_param_no_default lambda_param_maybe_default* [lambda_kwds]
    | '*' ',' lambda_param_maybe_default+ [lambda_kwds]
    | lambda_kwds

lambda_kwds: '**' lambda_param_no_default

lambda_param_no_default:
    | lambda_param ','
    | lambda_param &':'
lambda_param_with_default:
    | lambda_param default ','
    | lambda_param default &':'
lambda_param_maybe_default:
    | lambda_param default? ','
    | lambda_param default? &':'
lambda_param: NAME

disjunction:
    | conjunction ('or' conjunction )+
    | conjunction
conjunction:
    | inversion ('and' inversion )+
    | inversion
inversion:
    | 'not' inversion
    | comparison
comparison:
    | bitwise_or compare_op_bitwise_or_pair+
    | bitwise_or
compare_op_bitwise_or_pair:
    | eq_bitwise_or
    | noteq_bitwise_or
    | lte_bitwise_or
    | lt_bitwise_or
    | gte_bitwise_or
    | gt_bitwise_or
    | notin_bitwise_or
    | in_bitwise_or
    | isnot_bitwise_or
    | is_bitwise_or
eq_bitwise_or: '==' bitwise_or
noteq_bitwise_or:
    | ('!=' ) bitwise_or
lte_bitwise_or: '<=' bitwise_or
lt_bitwise_or: '<' bitwise_or
gte_bitwise_or: '>=' bitwise_or
gt_bitwise_or: '>' bitwise_or
notin_bitwise_or: 'not' 'in' bitwise_or
in_bitwise_or: 'in' bitwise_or
isnot_bitwise_or: 'is' 'not' bitwise_or
is_bitwise_or: 'is' bitwise_or

bitwise_or:
    | bitwise_or '|' bitwise_xor
    | bitwise_xor
bitwise_xor:
    | bitwise_xor '^' bitwise_and
    | bitwise_and
bitwise_and:
    | bitwise_and '&' shift_expr
    | shift_expr
shift_expr:
    | shift_expr '<<' sum
    | shift_expr '>>' sum
    | sum

sum:
    | sum '+' term
    | sum '-' term
    | term
term:
    | term '*' factor
    | term '/' factor
    | term '//' factor
    | term '%' factor
    | term '@' factor
    | factor
factor:
    | '+' factor
    | '-' factor
    | '~' factor
    | power
power:
    | await_primary '**' factor
    | await_primary
await_primary:
    | AWAIT primary
    | primary
primary:
    | primary '.' NAME
    | primary genexp
    | primary '(' [arguments] ')'
    | primary '[' slices ']'
    | atom

slices:
    | slice !','
    | ','.slice+ [',']
slice:
    | [expression] ':' [expression] [':' [expression] ]
    | expression
atom:
    | NAME
    | 'True'
    | 'False'
    | 'None'
    | '__peg_parser__'
    | strings
    | NUMBER
    | (tuple | group | genexp)
    | (list | listcomp)
    | (dict | set | dictcomp | setcomp)
    | '...'

strings: STRING+
list:
    | '[' [star_named_expressions] ']'
listcomp:
    | '[' named_expression ~ for_if_clauses ']'
tuple:
    | '(' [star_named_expression ',' [star_named_expressions]  ] ')'
group:
    | '(' (yield_expr | named_expression) ')'
genexp:
    | '(' named_expression ~ for_if_clauses ')'
set: '{' star_named_expressions '}'
setcomp:
    | '{' named_expression ~ for_if_clauses '}'
dict:
    | '{' [double_starred_kvpairs] '}'
dictcomp:
    | '{' kvpair for_if_clauses '}'
double_starred_kvpairs: ','.double_starred_kvpair+ [',']
double_starred_kvpair:
    | '**' bitwise_or
    | kvpair
kvpair: expression ':' expression
for_if_clauses:
    | for_if_clause+
for_if_clause:
    | ASYNC 'for' star_targets 'in' ~ disjunction ('if' disjunction )*
    | 'for' star_targets 'in' ~ disjunction ('if' disjunction )*

yield_expr:
    | 'yield' 'from' expression
    | 'yield' [star_expressions]

arguments:
    | args [','] &')'
args:
    | ','.(starred_expression | named_expression !'=')+ [',' kwargs ]
    | kwargs
kwargs:
    | ','.kwarg_or_starred+ ',' ','.kwarg_or_double_starred+
    | ','.kwarg_or_starred+
    | ','.kwarg_or_double_starred+
starred_expression:
    | '*' expression
kwarg_or_starred:
    | NAME '=' expression
    | starred_expression
kwarg_or_double_starred:
    | NAME '=' expression
    | '**' expression

# NOTE: star_targets may contain *bitwise_or, targets may not.
star_targets:
    | star_target !','
    | star_target (',' star_target )* [',']
star_targets_list_seq: ','.star_target+ [',']
star_targets_tuple_seq:
    | star_target (',' star_target )+ [',']
    | star_target ','
star_target:
    | '*' (!'*' star_target)
    | target_with_star_atom
target_with_star_atom:
    | t_primary '.' NAME !t_lookahead
    | t_primary '[' slices ']' !t_lookahead
    | star_atom
star_atom:
    | NAME
    | '(' target_with_star_atom ')'
    | '(' [star_targets_tuple_seq] ')'
    | '[' [star_targets_list_seq] ']'

single_target:
    | single_subscript_attribute_target
    | NAME
    | '(' single_target ')'
single_subscript_attribute_target:
    | t_primary '.' NAME !t_lookahead
    | t_primary '[' slices ']' !t_lookahead

del_targets: ','.del_target+ [',']
del_target:
    | t_primary '.' NAME !t_lookahead
    | t_primary '[' slices ']' !t_lookahead
    | del_t_atom
del_t_atom:
    | NAME
    | '(' del_target ')'
    | '(' [del_targets] ')'
    | '[' [del_targets] ']'

t_primary:
    | t_primary '.' NAME &t_lookahead
    | t_primary '[' slices ']' &t_lookahead
    | t_primary genexp &t_lookahead
    | t_primary '(' [arguments] ')' &t_lookahead
    | atom &t_lookahead
t_lookahead: '(' | '[' | '.'

La Biblioteca Estándar de Python

Aunque Referencia del Lenguaje Python describe la sintaxis y semántica precisa del lenguaje Python, este manual de referencia de la biblioteca describe la biblioteca estándar que se distribuye con Python. También describe algunos componentes opcionales que son usualmente incluidos en las distribuciones de Python.

La biblioteca estándar de Python es muy amplia, y ofrece una gran cantidad de producciones como puede verse en la larga lista de contenidos. La biblioteca contiene módulos incorporados (escritos en C) que brindan acceso a las funcionalidades del sistema como entrada y salida de archivos que serían de otra forma inaccesibles para los programadores en Python, así como módulos escritos en Python que proveen soluciones estandarizadas para los diversos problemas que pueden ocurrir en el día a día en la programación. Algunos de éstos módulos están diseñados explícitamente para alentar y reforzar la portabilidad de los programas en Python abstrayendo especificidades de las plataformas para lograr APIs neutrales a la plataforma.

Los instaladores de Python para la plataforma Windows frecuentemente incluyen la biblioteca estándar completa y suelen también incluir muchos componentes adicionales. Para los sistemas operativos tipo Unix Python suele ser provisto como una colección de paquetes, así que puede requerirse usar las herramientas de empaquetado disponibles en los sistemas operativos para obtener algunos o todos los componentes opcionales.

Además de la biblioteca estándar, existe un colección creciente de varios miles de componentes (abarcando módulos o programas individuales, paquetes o frameworks completos de desarrollo de aplicaciones), disponibles en el Python Package Index [https://pypi.org].

Introducción

Notas sobre la disponibilidad

Funciones Built-in

Constantes incorporadas

Constantes agregadas por el módulo site

Tipos Integrados

Evaluar como valor verdadero/falso

Operaciones booleanas — and, or, not

Comparaciones

Tipos numéricos — int, float, complex

Tipos de iteradores

Tipos secuencia — list, tuple, range

Cadenas de caracteres — str

Tipos de secuencias binarias — bytes, bytearray y memoryview

Conjuntos — set, frozenset

Tipos Mapa — dict

Tipos Gestores de Contexto

Tipo Alias Genérico

Otros tipos predefinidos

Atributos especiales

Integer string conversion length limitation

Excepciones incorporadas

Exception context

Inheriting from built-in exceptions

Clases base

Excepciones específicas

Advertencias

Jerarquía de excepción

Servicios de procesamiento de texto

string — Operaciones comunes de cadena de caracteres

re — Operaciones con expresiones regulares

difflib — Funciones auxiliares para calcular deltas

textwrap — Envoltura y relleno de texto

unicodedata — Base de datos Unicode

stringprep — Preparación de cadenas de Internet

readline — Interfaz readline de GNU

rlcompleter — Función de completado para GNU readline

Servicios de datos binarios

struct — Interpreta bytes como paquetes de datos binarios

codecs — Registro de códec y clases base

Tipos de datos

datetime — Tipos básicos de fecha y hora

zoneinfo — Soporte de zona horaria IANA

calendar — Funciones generales relacionadas con el calendario

collections — Tipos de datos contenedor

collections.abc — Clases Base Abstractas para Contenedores

heapq — Algoritmo de colas montículos (heap)

bisect — Algoritmo de bisección de arreglos

array — Arreglos eficientes de valores numéricos

weakref — Referencias débiles

types — Creación de tipos dinámicos y nombres para tipos integrados

copy — Operaciones de copia superficial y profunda

pprint — Impresión bonita de datos

reprlib — Implementación repr() alternativa

enum — Soporte para enumeraciones

graphlib — Functionality to operate with graph-like structures

Módulos numéricos y matemáticos

numbers — Clase base abstracta numérica

math — Funciones matemáticas

cmath – Función matemática para números complejos

decimal — Aritmética decimal de coma fija y coma flotante

fractions — Números racionales

random —Generar números pseudoaleatorios

statistics — Funciones de estadística matemática

Módulos de programación funcional

itertools — Funciones que crean iteradores para bucles eficientes

functools — Funciones de orden superior y operaciones sobre objetos invocables

operator — Operadores estándar como funciones

Acceso a archivos y directorios

pathlib — Object-oriented filesystem paths

os.path — Manipulaciones comunes de nombre de ruta

fileinput — Iterar sobre líneas de múltiples flujos de entrada

stat — Interpretación de los resultados de stat()

filecmp— Comparaciones de Archivo y Directorio

tempfile — Generar archivos y directorios temporales

glob — Expansión del patrón de nombres de ruta de estilo Unix

fnmatch — Coincidencia de patrones de nombre de archivos Unix

linecache — Acceso aleatorio a líneas de texto

shutil — Operaciones de archivos de alto nivel

Persistencia de datos

pickle — Serialización de objetos Python

copyreg — Registrar funciones de soporte de pickle

shelve — Persistencia de objetos de Python

marshal — Serialización interna de objetos Python

dbm — Interfaces para «bases de datos» de Unix

sqlite3 — DB-API 2.0 interfaz para bases de datos SQLite

Compresión de datos y archivado

zlib — Compresión compatible con gzip

gzip — Soporte para archivos gzip

bz2 — Soporte para compresión bzip2

lzma — Compresión utilizando el algoritmo LZMA

zipfile — Trabajar con archivos ZIP

tarfile — Leer y escribir archivos tar

Formatos de archivo

csv — Lectura y escritura de archivos CSV

configparser — Parser para archivos de configuración

netrc — procesado del fichero netrc

plistlib — Genera y analiza archivos .plist de Apple

Servicios Criptográficos

hashlib — Hashes seguros y resúmenes de mensajes

hmac — Hash con clave para autenticación de mensajes

secrets — Genera números aleatorios seguros para trabajar con secretos criptográficos

Servicios genéricos del sistema operativo

os — Interfaces misceláneas del sistema operativo

io — Herramientas principales para trabajar con streams

time — Tiempo de acceso y conversiones

argparse — Analizador sintáctico (Parser) para las opciones, argumentos y sub-comandos de la línea de comandos

getopt — Analizador de estilo C para opciones de línea de comando

logging — Instalación de logging para Python

logging.config — Configuración de registro

logging.handlers — Gestores de logging

getpass — Entrada de contraseña portátil

curses — Manejo de terminales para pantallas de celdas de caracteres

curses.textpad— Widget de entrada de texto para programas de curses

curses.ascii — Utilidades para los caracteres ASCII

curses.panel — Una extensión de pila de panel para curses

platform — Acceso a los datos identificativos de la plataforma subyacente

errno — Símbolos estándar del sistema errno

ctypes — Una biblioteca de funciones foráneas para Python

Ejecución concurrente

threading — Paralelismo basado en hilos

multiprocessing — Paralelismo basado en procesos

multiprocessing.shared_memory — Proporciona memoria compartida para acceso directo a través de procesos

El paquete concurrent

concurrent.futures — Lanzamiento de tareas paralelas

subprocess — Gestión de subprocesos

sched — Eventos del planificador

queue — clase de cola sincronizada

contextvars — Variables de Contexto

_thread — API de bajo nivel para manejo de hilos

Comunicación en redes y entre procesos

asyncio — E/S Asíncrona

socket — interfaz de red de bajo nivel

ssl —Empaquetador o wrapper TLS/SSL para objetos de tipo socket

select — Esperando la finalización de E/S

selectors — Multiplexación de E/S de alto nivel

signal — Establece gestores para eventos asíncronos

mmap — Soporte de archivos mapeados en memoria

Manejo de Datos de Internet

email — Un paquete de manejo de correo electrónico y MIME

json — Codificador y decodificador JSON

mailbox — Manipular buzones de correo en varios formatos

mimetypes — Mapea nombres de archivo a tipos MIME

base64 — Codificaciones de datos Base16, Base32, Base64, y Base85

binhex — Codificar y decodificar archivos binhex4

binascii — Convertir entre binario y ASCII

quopri — Codificar y decodificar datos MIME imprimibles entre comillas

Herramientas Para Procesar Formatos de Marcado Estructurado

html — Compatibilidad con el Lenguaje de marcado de hipertexto

html.parser — Analizador simple de HTML y XHTML

html.entities — Definiciones de entidades generales HTML

Módulos de procesamiento XML

xml.etree.ElementTree — La API XML de ElementTree

xml.dom — El API del Modelo de Objetos del Documento

xml.dom.minidom — Implementación mínima del DOM

xml.dom.pulldom — Soporte para la construcción parcial de árboles DOM

XML.sax— Soporte para analizadores SAX2

xml.sax.handler — Clases base para los handlers SAX

xml.sax.saxutils — Utilidades SAX

xml.sax.xmlreader — Interfaz para analizadores XML

xml.parsers.expat — Análisis rápido XML usando Expat

Protocolos y soporte de Internet

webbrowser — Cómodo controlador de navegador web

wsgiref — Utilidades WSGI e implementación de referencia

urllib — URL módulos de manipulación

urllib.request — Biblioteca extensible para abrir URLs

urllib.response — Clases de respuesta usadas por urllib

urllib.parse — Analiza URL en componentes

urllib.error — Clases de excepción lanzadas por urllib.request

urllib.robotparser — Analizador para robots.txt

http — Módulos HTTP

http.client — Cliente de protocolo HTTP

ftplib — cliente de protocolo FTP

poplib — Cliente de protocolo POP3

imaplib — Protocolo del cliente IMAP4

smtplib — Cliente de protocolo SMTP

uuid — objetos UUID según RFC 4122

socketserver — Un framework para servidores de red

http.server — Servidores HTTP

http.cookies — Gestión del estado HTTP

http.cookiejar — Manejo de cookies para clientes HTTP

xmlrpc — Módulos XMLRPC para cliente y servidor

xmlrpc.client — acceso cliente XML-RPC

xmlrpc.server — Servidores básicos XML-RPC

ipaddress — Biblioteca de manipulación IPv4/IPv6

Servicios Multimedia

wave — Leer y escribir archivos WAV

colorsys — Conversiones entre sistemas de color

Internacionalización

gettext — Servicios de internacionalización multilingües

locale — Servicios de internacionalización

Frameworks de programa

turtle — Gráficos con Turtle

cmd — Soporte para intérpretes orientados a línea de comandos

shlex — Análisis léxico simple

Interfaces gráficas de usuario con Tk

tkinter — Interface de Python para Tcl/Tk

tkinter.colorchooser — Diálogo de elección de color

tkinter.font — Envoltorio de fuente Tkinter

Diálogos Tkinter

tkinter.messagebox — Indicadores de mensajes de Tkinter

tkinter.scrolledtext — Widget de texto desplazado

tkinter.dnd — Soporte de arrastrar y soltar

tkinter.ttk — Tk widgets temáticos

tkinter.tix — Ampliación de widgets para Tk

IDLE

Herramientas de desarrollo

typing — Soporte para type hints

pydoc — Generador de documentación y Sistema de ayuda en línea

Modo de desarrollo de Python

Efectos del modo de desarrollo de Python

Ejemplo de ResourceWarning

Ejemplo de error de descriptor de archivo incorrecto

doctest – Prueba ejemplos interactivos de Python

unittest — Infraestructura de tests unitarios

unittest.mock — Biblioteca de objetos simulados

unittest.mock — primeros pasos

2to3 - Traducción de código Python 2 a 3

test — Paquete de pruebas de regresión para Python

test.support — Utilidades para el conjunto de pruebas de Python

test.support.socket_helper — Utilidades para pruebas de socket

test.support.script_helper —Utilidades para las pruebas de ejecución de Python

test.support.bytecode_helper — Herramientas de apoyo para comprobar la correcta generación de bytecode

Depuración y perfilado

Tabla de auditoría de eventos

bdb — Framework de depuración

faulthandler — Volcar el rastreo de Python

pdb — El Depurador de Python

Los perfiladores de Python

timeit — Mide el tiempo de ejecución de pequeños fragmentos de código

trace — Rastrear la ejecución de la declaración de Python

tracemalloc— Rastrea la asignación de memoria

Empaquetado y distribución de software

distutils — Creación e instalación de módulos Python

ensurepip — Ejecutando el instalador pip

venv — Creación de entornos virtuales

zipapp — Gestiona archivadores zip ejecutables de Python

Servicios en tiempo de ejecución de Python

sys — Parámetros y funciones específicos del sistema

sysconfig — Proporciona acceso a la información de configuración de Python

builtins — Objetos incorporados

__main__ — Entorno de script del nivel superior

warnings — Control de advertencias

dataclasses — Clases de datos

contextlib — Utilidades para declaraciones de contexto with

abc — Clases de Base Abstracta

atexit — Gestores de Salida

traceback — Imprimir o recuperar un seguimiento de pila

__future__ — Definiciones de declaraciones futuras

gc — Interfaz del recolector de basura

inspect — Inspeccionar objetos vivos

site — Enlace (hook) de configuración específico del sitio

Intérpretes de Python personalizados

code — Clases básicas de intérpretes

codeop — Compila código Python

Importando módulos

zipimport — Importar módulos desde archivos zip

pkgutil — Utilidad de extensión de paquete

modulefinder — Buscar módulos usados por un script

runpy — Localización y ejecución de módulos Python

importlib — La implementación de import

Usando importlib.metadata

Servicios del lenguaje Python

parser — Acceder a árboles de análisis sintáctico de Python

ast — Árboles de sintaxis abstracta

symtable — Acceso a la tabla de símbolos del compilador

symbol — Constantes utilizadas con árboles de análisis de Python

token— Constantes usadas con árboles de sintaxis de Python

keyword — Pruebas para palabras clave en Python

tokenize — Conversor a tokens para código Python

tabnanny — Detección de indentación ambigua

pyclbr — Soporte para navegador de módulos Python

py_compile` — Compila archivos fuente Python

compileall — Bibliotecas de Python de compilación de bytes

dis — Desensamblador para bytecode de Python

pickletools — Herramientas para desarrolladores pickle

Servicios varios

formatter — Formateo de salida genérica

Servicios Específicos para MS Windows

msvcrt — Rutinas útiles del entorno de ejecución MS VC++

winreg — Acceso al registro de Windows

:mod:”winsound” — Interfaz de reproducción de sonido para Windows

Servicios específicos de Unix

posix — Las llamadas más comunes al sistema POSIX

pwd — La base de datos de contraseñas

grp — La base de datos de grupo

termios —Control tty estilo POSIX

tty — Funciones de control de terminal

pty — Utilidades para Pseudo-terminal

fcntl — Las llamadas a sistema fcntl y ioctl

resource — Información sobre el uso de recursos

syslog — Rutinas de la biblioteca syslog de Unix

Módulos Reemplazados

aifc — Lee y escribe archivos AIFF y AIFC

asynchat — Gestor de comandos/respuestas en sockets asíncronos

asyncore — controlador de socket asincrónico

audioop — Manipula datos de audio sin procesar

cgi — Soporte de Interfaz de Entrada Común (CGI)

cgitb — Administrador traceback para scripts CGI.

chunk — Lee los datos de los trozos de IFF

crypt — Función para verificar contraseñas Unix

:mod:”imghdr” — Determinar el tipo de imagen

imp — Acceda a import internamente

mailcap — Manejo de archivos Mailcap

msilib — Leer y escribir archivos Microsoft Installer

nis — Interfaz a Sun’s NIS (Páginas amarillas)

nntplib — Protocolo de cliente NNTP

optparse — Analizador sintáctico (parser) para opciones de línea de comandos

ossaudiodev — Acceso a dispositivos de audio compatibles con OSS

pipes — Interfaz para tuberías de shell

smtpd — Servidor SMTP

sndhdr — Determinar el tipo de archivo de sonido

spwd — La base de datos de contraseñas ocultas

sunau — Lectura y escritura de ficheros Sun AU

telnetlib — cliente Telnet

uu — Codifica y decodifica archivos UUEncode

xdrlib — Codificar y decodificar datos XDR

Security Considerations

Introducción

La «biblioteca Python» contiene varios tipos de componentes diferentes.

Contiene tipos de datos que normalmente se considerarían parte del «núcleo» de un lenguaje, como números y listas. Para estos tipos, el núcleo del lenguaje Python define la forma de los literales y coloca algunas restricciones a su semántica, pero no define completamente la semántica. (Por otro lado, el núcleo del lenguaje sí define propiedades sintácticas como la ortografía y las prioridades de los operadores.)

La biblioteca también contiene funciones y excepciones incorporadas — objetos que pueden ser utilizados por todo código Python sin la necesidad de una declaración import. Algunas de ellos están definidas por el núcleo del lenguaje, pero muchos no son esenciales para la semántica del núcleo y sólo se describen aquí.

La mayor parte de la biblioteca, sin embargo, consiste en una colección de módulos. Hay muchas maneras de diseccionar esta colección. Algunos módulos están escritos en C y fueron incorporados en el intérprete de Python; otros están escritos en Python y se importan en código fuente. Algunos módulos proporcionan interfaces muy específicas de Python, como la impresión de un stack trace; otros proporcionan interfaces que son específicas para determinados sistemas operativos, como el acceso a hardware específico; otros proveen interfaces específicas para un dominio de aplicación concreto, como la World Wide Web. Algunos módulos están disponibles en todas las versiones y plataformas de Python; otros sólo están disponibles cuando el sistema subyacente los soporta o los requiere; otros solo están disponibles cuando se ha elegido una opción de configuración particular en el momento en que compiló e instaló Python.

Este manual está organizado «desde adentro hacia afuera:» primero describe las funciones integradas, los tipos de datos y las excepciones, y finalmente describe los módulos, agrupados en capítulos de módulos relacionados.

Esto significa que si comienza a leer este manual desde el principio, y salta al siguiente capítulo cuando se aburra, obtendrá una visión general razonable de los módulos y áreas de aplicación disponibles que son soportados por la biblioteca de Python. Por supuesto, no tienes que leerlo necesariamente como una novela — sino que también puedes navegar por la tabla de contenidos (al principio del manual), o buscar una función, módulo o término específico en el glosario (en la parte final del manual). Y por último, si disfruta aprender sobre diferentes temas de manera aleatoria, puede escoger un número de página al azar (ver módulo random) y leer una o dos secciones. Independientemente del orden en que lea las secciones de este manual, es útil comenzar con el capítulo Funciones Built-in, ya que el resto del manual asume la familiaridad con este material.

¡Que comience el espectáculo!

Notas sobre la disponibilidad

Una nota de «Disponibilidad: Unix» significa que esta función se encuentra comúnmente en los sistemas Unix. Pero no hace ninguna afirmación sobre su existencia en un sistema operativo específico.

If not separately noted, all functions that claim «Availability: Unix» are supported on macOS, which builds on a Unix core.

Funciones Built-in

El intérprete de Python tiene una serie de funciones y tipos incluidos en él que están siempre disponibles. Están listados aquí en orden alfabético.

Funciones Built-in

abs()

delattr()

hash()

memoryview()

set()

all()

dict()

help()

min()

setattr()

any()

dir()

hex()

next()

slice()

ascii()

divmod()

id()

object()

sorted()

bin()

enumerate()

input()

oct()

staticmethod()

bool()

eval()

int()

open()

str()

breakpoint()

exec()

isinstance()

ord()

sum()

bytearray()

filter()

issubclass()

pow()

super()

bytes()

float()

iter()

print()

tuple()

callable()

format()

len()

property()

type()

chr()

frozenset()

list()

range()

vars()

classmethod()

getattr()

locals()

repr()

zip()

compile()

globals()

map()

reversed()

__import__()

complex()

hasattr()

max()

round()

abs(x)

Retorna el valor absoluto de un número. El argumento puede ser un número entero, un número de coma flotante o un objeto que implemente __abs__(). Si el argumento es un número complejo, se retorna su magnitud.

all(iterable)

Retorna True si todos los elementos del iterable son verdaderos (o si el iterable está vacío). Equivalente a:

def all(iterable):
    for element in iterable:
        if not element:
            return False
    return True

any(iterable)

Retorna True si un elemento cualquiera del iterable es verdadero. Si el iterable está vacío, retorna False. Equivalente a:

def any(iterable):
    for element in iterable:
        if element:
            return True
    return False

ascii(object)

Como repr(), retorna una cadena que contiene una representación imprimible de un objeto, pero que escapa los caracteres no-ASCII que repr() retorna usando \x, \u or \U. Esto genera una cadena similar a la retornada por repr() en Python 2.

bin(x)

Convierte un número entero a una cadena binaria con prefijo «0b». El resultado es una expresión de Python válida. Si x no es un objeto de clase int en Python, tiene que definir un método __index__() que retorne un entero. Algunos ejemplos:

>>> bin(3)
'0b11'
>>> bin(-10)
'-0b1010'

Según se desee o no el prefijo «0b», se puede usar uno u otro de las siguientes maneras.

>>> format(14, '#b'), format(14, 'b')
('0b1110', '1110')
>>> f'{14:#b}', f'{14:b}'
('0b1110', '1110')

Véase también format() para más información.

class bool([x])

Retorna un booleano, es decir, o bien True o False. x es convertido usando el estándar truth testing procedure. Si x es falso u omitido, retorna False; en caso contrario retorna True. La clase bool es una subclase de int (véase Tipos numéricos — int, float, complex). De ella no pueden derivarse más subclases. Sus únicas instancias son False y True (véase Valores booleanos).

Distinto en la versión 3.7: x es ahora un argumento solo de posición.

breakpoint(*args, **kws)

Esta función te lleva al depurador en el sitio donde se produce la llamada. Específicamente, llama a sys.breakpointhook(), pasando args y kws directamente. Por defecto, sys.breakpointhook() llama a pdb.set_trace() sin esperar argumentos. En este caso, es puramente una función de conveniencia para evitar el importe explícito de pdb o tener que escribir tanto código para entrar al depurador. Sin embargo, sys.breakpointhook() puede ser configurado a otra función y breakpoint() llamará automáticamente a esta, permitiendo entrar al depurador elegido.

Lanza un evento de auditoría builtins.breakpoint con breakpointhook como argumento.

Nuevo en la versión 3.7.

class bytearray([source[, encoding[, errors]]])

Retorna un nuevo array de bytes. La clase bytearray es una secuencia mutable de enteros en el rango 0 <= x < 256. Tiene la mayoría de los métodos comunes en las secuencias mutables, descritos en Tipos de secuencia mutables, así como la mayoría de los métodos que la clase bytes tiene, véase Operaciones de bytes y bytearray.

El parámetro opcional source puede ser empleado para inicializar el vector (array) de varias maneras distintas:

Si es una string, debes proporcionar también el parámetro encoding (y opcionalmente, errors; entonces bytearray() convierte la cadena a bytes empleando str.encode().

Si es un integer, el array tendrá ese tamaño y será inicializado con bytes nulos.

Si es un objeto conforme a interfaz de búfer, se utilizará un búfer de solo lectura del objeto para inicializar el arreglo de bytes.

Si es un iterable, debe ser un iterable de enteros en el rango 0 <= x < 256, que son usados como los contenidos iniciales del array.

Sin argumento, se crea un array de tamaño 0.

Ver también: Tipos de secuencias binarias — bytes, bytearray y memoryview y Objetos de tipo Bytearray.

class bytes([source[, encoding[, errors]]])

Retorna un nuevo objeto bytes, que es una secuencia inmutable de enteros en el rango 0 <= x < 256. bytes es una versión inmutable de bytearray — tiene los mismos métodos no-mutables y el mismo comportamiento en términos de indexación y segmentación.

En consecuencia, los argumentos del constructor son interpretados como los de bytearray().

Los objetos de bytes también pueden ser creados con literales, ver Literales de cadenas y bytes.

Ver también Tipos de secuencias binarias — bytes, bytearray y memoryview, Objetos de tipo Bytes, y Operaciones de bytes y bytearray.

callable(object)

Retorna True si el argumento object parece invocable, y False sino. Si retorna True, aun es posible que la invocación falle, pero si es False, invocar el object no funcionará nunca. Hay que tener en cuenta que las clases son invocables (ya que llamarlas retorna una instancia nueva); y que las instancias lo serán si su clase tiene un método __call__().

Nuevo en la versión 3.2: Está función fue eliminada en Python 3.0 pero traída de vuelta en Python 3.2.

chr(i)

Retorna la cadena que representa un carácter cuyo código Unicode es el entero i. Por ejemplo, chr(97) retorna la cadena ’a’, mientras que chr(8364) retorna la cadena ’€’. Esta función es la inversa de ord().

El rango válido para el argumento i es desde 0 a 1,114,111 (0x10FFFF en base 16). Se lanzará una excepción ValueError si i está fuera de ese rango.

@classmethod

Transforma un método en un método de clase.

Un método de clase recibe la clase como primer argumento implícito, de la misma forma que un método de instancia recibe la instancia. Para declarar un método de clase, emplea la siguiente expresión:

class C:
    @classmethod
    def f(cls, arg1, arg2): ...

La forma @classmethod es una función decorator — ver Definiciones de funciones para más detalles.

Un método de clase puede ser llamado en la clase (como C.f()) o en la instancia (como C().f()). La instancia es ignorada salvo por su clase. Si un método de clase es llamado desde una clase derivada, entonces el objeto de la clase derivada se pasa como primer argumento implícito.

Los métodos de clase son diferentes a los métodos estáticos de C++ o Java. Si los desea, consulte staticmethod() en esta sección. Para obtener más información sobre los métodos de clase, consulte Jerarquía de tipos estándar.

Distinto en la versión 3.9: Los métodos de clase ahora pueden envolver otros descriptores como property().

compile(source, filename, mode, flags=0, dont_inherit=False, optimize=-1)

Compila el source en código o en un objeto AST (Abstract Syntax Tree, árbol de sintaxis abstracta). Los objetos código pueden ser ejecutados por las funciones exec() or eval(). source puede ser una cadena normal, una cadena de bytes o un objeto AST. Para más información sobre cómo trabajar con objetos AST, revisa la documentación del módulo ast.

El argumento filename debería dar el fichero desde el que el código fue leído; pasará un valor reconocible en caso este no fuera leído de un fichero (’<string>’ es usado comúnmente para esto).

El argumento mode especifica que tipo de código debe ser compilado; puede ser ’exec’ si source consiste en una secuencia de declaraciones, ’eval’ si consiste de una expresión sencilla, o ’single’ si consiste en una declaración única interactiva (en este último caso, las declaraciones de expresiones que evalúen a algo distinto de None serán impresas).

Los argumentos opcionales flags y dont_inherit controlan qué opciones del compilador deben activarse y cuáles características futuras deben permitirse. Si ninguno está presente (o ambos son cero), el código se compila con los mismos flags que afectan al código que llama compile(). Si se proporciona el argumento flags y dont_inherit no es (o es cero), las opciones del compilador y las declaraciones futuras especificadas por el argumento flags se utilizan además de las que se utilizarían de todos modos. Si dont_inherit es un número entero distinto de cero, entonces el argumento flags lo es: los indicadores (características futuras y opciones del compilador) en el código circundante se ignoran.

Las opciones del compilador y las declaraciones futuras se especifican mediante bits que pueden combinarse mediante OR bit a bit para especificar varias opciones. El campo de bits requerido para especificar una característica futura dada se puede encontrar como el atributo compiler_flag en la instancia _Feature en el módulo __future__. Las flags del compilador se pueden encontrar en el módulo ast, con el prefijo PyCF_.

El argumento optimize especifica el nivel de optimización del compilador; el valor por defecto de -1 selecciona el nivel de optimización del intérprete de la misma forma que las opciones -O. Los niveles explícitos son 0 (sin optimización; __debug__ es true), 1 (se eliminan los asserts, __debug__ es false) or 2 (las docstrings también son eliminadas).

Esta función lanza un SyntaxError si el código compilado es inválido, y un ValueError si contiene bytes nulos.

Si quieres transformar código Python a su representación AST, revisa ast.parse().

Lanza un evento de auditoría compile con argumentos source, filename.

Nota

Cuando se compile una cadena multilínea de código en los modos ’single’ o ’eval’, la entrada debe terminar con un carácter de nueva línea como mínimo. Esto facilita la detección de declaraciones completas e incompletas en el módulo code.

Advertencia

Con una cadena lo suficientemente larga o compleja, al compilar a un objeto AST es posible que el intérprete de Python pare inesperadamente debido a las limitaciones de la profundidad de la pila en el compilador del AST de Python.

Distinto en la versión 3.2: Permite el uso de caracteres de nueva línea de Windows y Mac. También, la entrada en el modo ’exec’ no tiene porque terminar en una nueva línea. Se añade el parámetro optimize.

Distinto en la versión 3.5: Anteriormente, un TypeError era lanzado cuando se encontraban bytes nulos en source.

Nuevo en la versión 3.8: ast.PyCF_ALLOW_TOP_LEVEL_AWAIT puede ahora ser pasado en flags para permitir el soporte de await, async for, y async with en niveles superiores.

class complex([real[, imag]])

Retorna el número complejo con el valor real + imag*1j o convierte una cadena o un número a un número complejo. Si el primer parámetro es una cadena, será interpretada como un número complejo y la función debe ser llamada sin un segundo parámetro. El segundo parámetro nunca puede ser una cadena. Cada argumento puede ser de cualquier tipo numérico (incluyendo complex). Si se omite imag, su valor por defecto es cero y el constructor sirve como un conversor numérico como int y float. Si ambos argumentos son omitidos, retorna 0j.

Para un objeto general de Python x, complex(x) delega a x.__complex__(). Si __complex__() no está definida, entonces llama a __float__(). Si __float__() no está definida, entonces llama a __index__().

Nota

Cuando se convierte desde una cadena, la cadena no debe contener espacios en blanco alrededor de los operadores centrales + or -. Por ejemplo, complex(‘1+2j’) es correcto, pero complex(‘1 + 2j’) lanza ValueError.

El tipo complejo está descrito en Tipos numéricos — int, float, complex.

Distinto en la versión 3.6: Agrupar dígitos con guiones bajos como en los literales de código está permitido.

Distinto en la versión 3.8: Recurre a __index__() si __complex__() y __float__() no están definidos.

delattr(object, name)

Esta función está emparentada con setattr(). Los argumentos son un objeto y una cadena. La cadena debe ser el mismo nombre que alguno de los atributos del objeto. La función elimina el atributo nombrado, si es que el objeto lo permite. Por ejemplo delattr(x, ‘foobar’) es equivalente a del x.foobar.

class dict(**kwarg)

class dict(mapping, **kwarg)

class dict(iterable, **kwarg)

Crea un nuevo diccionario. El objeto dict es la clase diccionario. Véase dict y Tipos Mapa — dict para más información sobre esta clase.

Para otros contenedores véase las clases incorporadas (built-in) list, set, y tuple, así como el módulo collections.

dir([object])

Sin argumentos, retorna la lista de nombres en el ámbito local. Con un argumento, intenta retornar una lista de atributos válidos para ese objeto.

Si el objeto tiene un método llamado __dir__(), éste será llamado y debe retornar la lista de atributos. Esto permite que los objetos que implementan una función personalizada __getattr__() o __getattribute__() puedan decidir la manera en la que dir() reporta sus atributos.

Si el objeto no provee de un método __dir__(), la función intenta obtener la información del atributo __dict__ del objeto, si está definido, y de su objeto tipo. La lista resultante no está necesariamente completa, y puede ser inexacta cuando el objeto tiene una función __getattr__() implementada.

El mecanismo por defecto de dir() se comporta de forma distinta con diferentes tipos de objeto, ya que intenta producir la información más relevante en vez de la más completa:

Si el objeto es un módulo, la lista contiene los nombres de los atributos del módulo.

Si el objeto es un tipo o una clase, la lista contiene los nombres de sus atributos, y recursivamente la de los atributos de sus clases base.

En cualquier otro caso, la lista contiene los nombres de los atributos del objeto, los nombres de los atributos de su clase, y recursivamente los atributos de sus clases base.

La lista resultante está ordenada alfabéticamente. Por ejemplo:

>>> import struct
>>> dir()   # show the names in the module namespace
['__builtins__', '__name__', 'struct']
>>> dir(struct)   # show the names in the struct module
['Struct', '__all__', '__builtins__', '__cached__', '__doc__', '__file__',
 '__initializing__', '__loader__', '__name__', '__package__',
 '_clearcache', 'calcsize', 'error', 'pack', 'pack_into',
 'unpack', 'unpack_from']
>>> class Shape:
...     def __dir__(self):
...         return ['area', 'perimeter', 'location']
>>> s = Shape()
>>> dir(s)
['area', 'location', 'perimeter']

Nota

Ya que dir() se ofrece como una herramienta para uso en una terminal de forma interactiva, intenta ofrecer un grupo interesante de nombres más que un uno rigurosamente definido, y su comportamiento detallado puede cambiar entre versiones. Por ejemplo, los atributos de metaclase no están en la lista resultante cuando el argumento es una clase.

divmod(a, b)

Toma dos números (no complejos) como argumentos y retorna un par de números consistentes en su cociente y su resto al emplear división de enteros. Con operandos de tipos diferentes, se aplican las reglas de los operadores aritméticos binarios. Para enteros, el resultado es el mismo que (a // b, a % b). Para números de punto flotante el resultado es (q, a % b), donde q normalmente es math.floor(a / b) pero puede ser 1 menos que eso. En cualquier caso q * b + a % b es muy cercano a a, si a % b es distinto de cero y tiene el mismo signo que b, y 0 <= abs(a % b) < abs(b).

enumerate(iterable, start=0)

Retorna un objeto enumerador. iterable tiene que ser una secuencia, un iterator, o algún otro objeto que soporte la iteración. El método __next__() del iterador retornado por la función enumerate() retorna una tupla que contiene un contador (desde start, cuyo valor por defecto es 0) y los valores obtenidos al iterar sobre iterable.

>>> seasons = ['Spring', 'Summer', 'Fall', 'Winter']
>>> list(enumerate(seasons))
[(0, 'Spring'), (1, 'Summer'), (2, 'Fall'), (3, 'Winter')]
>>> list(enumerate(seasons, start=1))
[(1, 'Spring'), (2, 'Summer'), (3, 'Fall'), (4, 'Winter')]

Equivalente a:

def enumerate(sequence, start=0):
    n = start
    for elem in sequence:
        yield n, elem
        n += 1

eval(expression[, globals[, locals]])

Los argumentos son una cadena y opcionalmente, globales y locales. Si se introduce, globals tiene que ser un diccionario, y locals puede ser cualquier objeto de mapeo.

El argumento expression se parsea y evalúa como una expresión de Python (técnicamente, una lista de condiciones), usando los diccionarios globals y locals como espacios de nombres globales y locales. Si el diccionario globals está presente y no contiene un valor para la clave __builtins__, se inserta bajo esa clave una referencia al diccionario del módulo incorporado builtins antes de que la expression sea parseada. Esto significa que en condiciones normales expression tiene acceso total al módulo estándar builtins y los entornos restringidos son propagados. Si el diccionario locals es omitido entonces su valor por defecto es el diccionario globals. Si ambos diccionarios son omitidos, la expresión es ejecutada con las globals y locals del entorno en el que eval() es llamada. Tenga en cuenta que eval() no tiene acceso al alcances anidados (no-locales) en el entorno que lo contiene.

El valor que retorna es el resultado de la expresión evaluada. Los errores de sintaxis son reportados como excepciones. Por ejemplo:

>>> x = 1
>>> eval('x+1')
2

La función también puede ser utilizada para ejecutar objetos código arbitrario (como los que crea la función compile()). En este caso, se pasa un objeto código en vez de una cadena. Si el objeto código ha sido compilado usando 'exec' como el argumento mode, el valor que retornará eval()será None.

Pista: la ejecución dinámica de declaraciones está soportada por la función exec(). Las funciones globals() y locals() retornan los diccionarios global y local en ese momento, lo cual puede ser útil para su uso en eval() o exec().

Véase ast.literal_eval(), una función que puede evaluar de forma segura cadenas con expresiones que contienen solo literales.

Lanza un evento de auditoría exec con un argumento code_object.

exec(object[, globals[, locals]])

This function supports dynamic execution of Python code. object must be either a string or a code object. If it is a string, the string is parsed as a suite of Python statements which is then executed (unless a syntax error occurs). 1 If it is a code object, it is simply executed. In all cases, the code that’s executed is expected to be valid as file input (see the section Entrada de archivo in the Reference Manual). Be aware that the nonlocal, yield, and return statements may not be used outside of function definitions even within the context of code passed to the exec() function. The return value is None.

En todos los casos, si las partes opcionales son omitidas, el código es ejecutado en el ámbito actual. Si solo se indica globals, debe ser un diccionario (y no una subclase de diccionario), que será usada tanto para las variables locales como las globales. Si se indican tanto globals como locals, son usadas para las variables globales y locales respectivamente. Si se indican, locals puede ser cualquier objeto de mapeo. Recuerda que a nivel de módulo, globals y locals son el mismo diccionario. Si exec recibe dos objetos separados como globals y locals, el código será ejecutado como si estuviera incorporado en una definición de clase.

Si el diccionario globals no contiene un valor para la clave __builtins__, una referencia al diccionario del módulo built-in builtins se inserta bajo esa clave. De esta forma puedes controlar que builtins están disponibles para el código ejecutado insertando tu propio diccionario __builtins__ en globals antes de pasárselo a exec().

Lanza un evento de auditoría exec con un argumento code_object.

Nota

Las funciones built-in globals() y locals() Retornan el diccionario local y global actual, respectivamente, lo que puede ser útil para pasarlo y emplearlo como el segundo y el tercer argumento de exec().

Nota

El locals por defecto actúa de la forma descrita para la función locals() más abajo: no se deben intentar modificaciones sobre el diccionario locals por defecto. Pasa un diccionario explícito locals si necesitas ver los efectos del código en locals después de que la función exec() retorne.

filter(function, iterable)

Construye un iterador a partir de aquellos elementos de iterable para los cuales function retorna true. iterable puede ser una secuencia, un contenedor que soporta iteración, o un iterador. Si function es None, se asume la función identidad, es decir, todos los elementos de iterable que son false son eliminados.

Ten en cuenta que filter(function, iterable) es equivalente a la expresión de un generador (item for item in iterable if function(item)) si function no es None y a (item for item in iterable if item) si function es None.

Ver itertools.filterfalse() para la función complementaria que retorna los elementos de iterable para los cuales function retorna false.

class float([x])

Retorna un número de punto flotante construido a partir de un número o una cadena x.

Si el argumento es una cadena, debe contener un número decimal, opcionalmente precedido de un signo, y opcionalmente entre espacios en blanco. El signo opcional puede ser ’+’ o ’-‘; un signo ’+’ no tiene efecto en el valor producido. El argumento puede ser también una cadena representando un NaN (no es un número), o un infinito positivo o negativo. Más concretamente, el argumento debe adecuarse a la siguiente gramática una vez eliminados de la cadena los caracteres en blanco por delante o detrás:

sign           ::=  "+" | "-"
infinity       ::=  "Infinity" | "inf"
nan            ::=  "nan"
numeric_value  ::=  floatnumber | infinity | nan
numeric_string ::=  [sign] numeric_value

Aquí floatnumber es el formato de un literal de punto flotante de Python, tal y como está descrito en Literales de punto flotante. No es relevante si los caracteres son mayúsculas o minúsculas, de forma que «inf», «Inf», «INFINITY» e «iNfINity» son todas formas aceptables de escribir el infinito positivo.

Sino, en caso de que el argumento sea un entero o un decimal de punto flotante, se retorna un número de punto flotante del mismo valor (dentro de la precisión de punto flotante de Python). Si el argumento está fuera del rango de un punto flotante de Python, se generará una excepción OverflowError.

Para el objeto general de Python x, float(x) delega a x.__float__(). Si __float__() no está definido entonces recurre a __index__().

Si no se le da un argumento, retorna 0.0.

Ejemplos:

>>> float('+1.23')
1.23
>>> float('   -12345\n')
-12345.0
>>> float('1e-003')
0.001
>>> float('+1E6')
1000000.0
>>> float('-Infinity')
-inf

El tipo float está descrito en Tipos numéricos — int, float, complex.

Distinto en la versión 3.6: Agrupar dígitos con guiones bajos como en los literales de código está permitido.

Distinto en la versión 3.7: x es ahora un argumento solo de posición.

Distinto en la versión 3.8: Recurre a __index__() si __float__() no está definido.

format(value[, format_spec])

Convierte value a su representación «con formato», de forma controlada por format_spec. La interpretación de format_spec dependerá del tipo del argumento value. Sin embargo, hay una sintaxis estándar de formato que emplean la mayoría de los tipos built-in: Especificación de formato Mini-Lenguaje.

El format_spec por defecto es una cadena vacía que normalmente produce el mismo efecto que llamar a str(value).

Una llamada a format(value, format_spec) se traduce a type(value).__format__(value, format_spec) , que sortea el diccionario de la instancia cuando busca por el método __format__() del valor. Una excepción TypeError será lanzada si la búsqueda del método llega a object y format_spec no está vacío, o si format_spec o el valor de retorno no son cadenas.

Distinto en la versión 3.4: object().__format__(format_spec) lanza TypeError si format_spec no es una cadena vacía.

class frozenset([iterable])

Retorna un nuevo objeto frozenset , opcionalmente con elementos tomados de iterable. frozenset es una clase built-in. Ver frozenset y Conjuntos — set, frozenset para documentación sobre esta clase.

Para otro tipo de contenedores, ver las clases built-in set, list, tuple, y dict, así como el módulo collections.

getattr(object, name[, default])

Retorna el valor del atributo nombrado de object. name debe ser una cadena. Si la cadena es el nombre de uno de los atributos del objeto, el resultado es el valor de ese atributo. Por ejemplo, getattr(x, ‘foobar’) es equivalente a x.foobar. Si el atributo nombrado no existe, se retorna default si ha sido proporcionado como argumento, y sino se lanza una excepción AttributeError.

Nota

Since private name mangling happens at compilation time, one must manually mangle a private attribute’s (attributes with two leading underscores) name in order to retrieve it with getattr().

globals()

Return the dictionary implementing the current module namespace. For code within functions, this is set when the function is defined and remains the same regardless of where the function is called.

hasattr(object, name)

Los argumentos son un objeto y una cadena. El resultado es True si la cadena es el nombre de uno de los atributos del objeto, y False en caso contrario. (Está implementado mediante una llamada a getattr(object, name) que comprueba si se lanza una excepción AttributeError o no).

hash(object)

Retorna el valor hash del objeto (si tiene uno). Los valores hash son enteros. Se usan para comparar de forma rápida claves de diccionarios durante las operaciones de búsqueda. Valores numéricos que son iguales tienen el mismo valor hash (incluso si son de tipos diferentes, como es el caso para 1 y 1.0).

Nota

Para objetos que implementan métodos __hash__(), ten en cuenta que hash() trunca el valor de retorno en base a la tasa de bits de la máquina host. Ver __hash__() para más detalles.

help([object])

Invoca el sistema de ayuda integrado (built-in). (Esta función está indicada para su uso interactivo). Si no se le da argumento, el sistema interactivo de ayuda se inicia en la consola del intérprete. Si el argumento es una cadena, entonces es buscada como nombre de un módulo, función, clase, método, palabra clave o tema de documentación, y una página de ayuda es impresa en la consola. Si el argumento es cualquier otro tipo de objeto, una página de ayuda sobre el objeto es generada.

Ten en cuenta que si una barra(/) aparece en la lista de parámetros de una función, al invocar help() significa que los parámetros anteriores a la barra son solo posicionales. Para más información, puedes ver the FAQ entry on positional-only parameters.

Esta función se añade al espacio de nombres built-in a través del módulo site.

Distinto en la versión 3.4: Cambios a los módulos pydoc y inspect implican que las signaturas reportadas para objetos invocables son más completas y consistentes.

hex(x)

Convierte un número entero a una cadena hexadecimal de minúsculas con el prefijo «0x». Si x no es un objeto de la clase Python int, tiene que definir un método __index__() que retorne un entero. Algunos ejemplos:

>>> hex(255)
'0xff'
>>> hex(-42)
'-0x2a'

Si quieres convertir un número entero a una cadena hexadecimal de mayúsculas o minúsculas con prefijo o sin el, puedes usar cualquiera de las siguientes formas:

>>> '%#x' % 255, '%x' % 255, '%X' % 255
('0xff', 'ff', 'FF')
>>> format(255, '#x'), format(255, 'x'), format(255, 'X')
('0xff', 'ff', 'FF')
>>> f'{255:#x}', f'{255:x}', f'{255:X}'
('0xff', 'ff', 'FF')

Véase también format() para más información.

Ver también int() para convertir una cadena hexadecimal a un entero usando una base de 16.

Nota

Para obtener una cadena hexadecimal que represente un punto flotante, utiliza el método float.hex().

id(object)

Retorna la «identidad» de un objeto. Esto es un entero que está garantizado que es único y constante para este objeto durante toda su existencia. Dos objetos con existencias en el tiempo que no coincidan pueden tener el mismo valor de id().

CPython implementation detail: This is the address of the object in memory.

Lanza un evento de auditoría builtins.id con el argumento id.

input([prompt])

Si el argumento prompt está presente, se escribe a la salida estándar sin una nueva línea a continuación. La función lee entonces una línea de la entrada, la convierte en una cadena (eliminando la nueva línea), y retorna eso. Cuando se lee EOF, se lanza una excepción EOFError. Ejemplo:

>>> s = input('--> ')
--> Monty Python's Flying Circus
>>> s
"Monty Python's Flying Circus"

Si el módulo readline estaba cargado, entonces input() lo usará para proporcionar características más elaboradas de edición de líneas e historiales.

Lanza un evento de auditoría builtins.input con el argumento prompt.

Lanza un evento de auditoría builtins.input/result con el resultado justo después de haber leído con éxito la entrada.

class int([x])

class int(x, base=10)

Retorna un objeto entero construido desde un número o cadena x, o retorna 0 si no se le proporcionan argumentos. Si x define __int__(), int(x) retorna x.__int__(). Si x define __index__(), retorna x.__index__(). Si x define __trunc__(), retorna x.__trunc__(). Para números de punto flotante, los valores serán truncados hacia cero.

Si x no es un número o si se indica base, entonces x debe ser una cadena, una instancia de bytes, o una de bytearray que representa un integer literal de base base. Opcionalmente, el literal puede ser precedido de + or - (sin espacios entre el número y el signo) y rodeados por espacio en blanco. Un literal de base-n consiste en los dígitos de 0 a n-1, con valores entre 10 y 35 para los caracteres de a a z (o de A a Z). La base por defecto es 10. Los valores permitidos son 0 y 2–36. Los literales de base-2, -8 y -16 pueden incluir opcionalmente un prefijo 0b/0B, 0o/0O, o 0x/0X, de igual forma que los literales enteros en el código. Base-0 indica que se debe interpretar exactamente como un literal de código, de forma que la base real es 2, 8, 10 o 16, y que int('010', 0) no sea legal, mientras que int('010') sí lo es, así como int('010', 8).

El tipo entero se describe en Tipos numéricos — int, float, complex.

Distinto en la versión 3.4: Si base no es una instancia de int y el objeto base tiene un método base.__index__, ese método es llamado para obtener un entero para esa base. En versiones anteriores se empleaba base.__int__ en vez de base.__index__.

Distinto en la versión 3.6: Agrupar dígitos con guiones bajos como en los literales de código está permitido.

Distinto en la versión 3.7: x es ahora un argumento solo de posición.

Distinto en la versión 3.8: Recurre a __index__() si no está definido __int__().

Distinto en la versión 3.9.14: int string inputs and string representations can be limited to help avoid denial of service attacks. A ValueError is raised when the limit is exceeded while converting a string x to an int or when converting an int into a string would exceed the limit. See the integer string conversion length limitation documentation.

isinstance(object, classinfo)

Retorna True si el argumento object es una instancia del argumento classinfo, o de una subclase (directa, indirecta o virtual) del mismo. Si object no es un objeto del tipo indicado, esta función siempre retorna False. Si classinfo es una tupla de objetos de tipo (o recursivamente, otras tuplas lo son), retorna True si object es una instancia de alguno de los tipos. Si classinfo no es un tipo, una tupla de tipos, ó una tupla de tuplas de tipos, una excepción TypeError es lanzada.

issubclass(class, classinfo)

Return True if class is a subclass (direct, indirect or virtual) of classinfo. A class is considered a subclass of itself. classinfo may be a tuple of class objects (or recursively, other such tuples), in which case return True if class is a subclass of any entry in classinfo. In any other case, a TypeError exception is raised.

iter(object[, sentinel])

Retorna un objeto iterator. El primer argumento se interpreta de forma muy diferente en función de la presencia del segundo. Sin un segundo argumento, object debe ser un objeto collection que soporte el protocolo de iteración (el método __iter__()), o debe soportar el protocolo de secuencia (el método __getitem__() con argumentos enteros comenzando en 0). Si no soporta ninguno de esos protocolos, se lanza una excepción TypeError. Si el segundo argumento, sentinel, es indicado, entonces object debe ser un objeto invocable. El iterador creado en ese caso llamará a object sin argumentos para cada invocación a su método __next__() ; si el valor retornado es igual a sentinel, una StopIteration será lanzada, de lo contrario el valor será retornado.

Ver también Tipos de iteradores.

Una aplicación muy útil de la segunda forma de iter() es la construcción de un lector de bloques. Por ejemplo, leer bloques de ancho fijo de una base de datos binaria hasta que el fin del fichero sea alcanzado:

from functools import partial
with open('mydata.db', 'rb') as f:
    for block in iter(partial(f.read, 64), b''):
        process_block(block)

len(s)

Retorna el tamaño (el número de elementos) de un objeto. El argumento puede ser una secuencia (como una cadena, un objeto byte, una tupla, lista o rango) o una colección (como un diccionario, un set o un frozen set).

CPython implementation detail: len aumenta OverflowError en longitudes mayores que sys.maxsize, como range(2 ** 100).

class list([iterable])

Más que una función, list es realmente un tipo de secuencia mutable, como está documentado en Listas y Tipos secuencia — list, tuple, range.

locals()

Actualiza y retorna un diccionario representando la tabla de símbolos locales actual. Las variables libres son retornadas por locals() cuando ésta es llamada en bloques de funciones, pero no en bloques de clases. Nótese que a nivel de módulo, locals() y globals() son el mismo diccionario.

Nota

Los contenidos de este diccionario no deben ser modificados; sus cambios no afectarán los valores de las variables locales y libres utilizadas por el intérprete.

map(function, iterable, ...)

Retorna un iterador que aplica function a cada elemento de iterable, retornando el resultado. Si se le pasan argumentos adicionales de tipo iterable, function debe tomar la misma cantidad de argumentos y es aplicado a los elementos de todos ellos en paralelo. Con iterables múltiples, el iterador se detiene cuando el iterable más corto se agota. Para casos donde las entradas de la función ya están organizadas como tuplas de argumentos, ver itertools.starmap().

max(iterable, *[, key, default])

max(arg1, arg2, *args[, key])

Retorna el elemento mayor en un iterable o el mayor de dos o más argumentos.

Si un argumento posicional es dado, debe ser un iterable. El elemento mayor en el iterable es retornado. Si dos o más argumentos posicionales son indicados, el mayor de los argumentos posicionales será retornado.

Hay dos argumentos de solo palabra clave que son opcionales. El argumento key especifica una función de ordenación de un sólo argumento, como la usada para list.sort(). El argumento default especifica un objeto a retornar si el iterable proporcionado está vacío. Si el iterable está vacío y default no ha sido indicado, se lanza un ValueError.

Si hay múltiples elementos con el valor máximo, la función retorna el primero que ha encontrado. Esto es consistente con otras herramientas para preservar la estabilidad de la ordenación como sorted(iterable, key=keyfunc, reverse=True)[0] y heapq.nlargest(1, iterable, key=keyfunc).

Nuevo en la versión 3.4: El argumento default sólo por palabra clave.

Distinto en la versión 3.8: key puede ser None.

class memoryview(object)

Retorna un objeto «memory view» creado a partir del argumento indicado. Para más información ver Vistas de memoria.

min(iterable, *[, key, default])

min(arg1, arg2, *args[, key])

Retorna el menor elemento en un iterable o el menor de dos o más argumentos.

Si se le indica un argumento posicional, debe ser un iterable. El menor elemento del iterable es retornado. Si dos o más argumentos posicionales son indicados, el menor de los argumentos posicionales es retornado.

Hay dos argumentos de solo palabra clave que son opcionales. El argumento key especifica una función de ordenación de un sólo argumento, como la usada para list.sort(). El argumento default especifica un objeto a retornar si el iterable proporcionado está vacío. Si el iterable está vacío y default no ha sido indicado, se lanza un ValueError.

Si hay múltiples elementos con el valor mínimo, la función retorna el primero que encuentra. Esto es consistente con otras herramientas que preservan la estabilidad de la ordenación como sorted(iterable, key=keyfunc)[0] y heapq.nsmallest(1, iterable, key=keyfunc).

Nuevo en la versión 3.4: El argumento default sólo por palabra clave.

Distinto en la versión 3.8: key puede ser None.

next(iterator[, default])

Extrae el siguiente elemento de iterator llamando a su método __next__(). Si se le indica default, éste será retornado si se agota el iterador, de lo contrario, se lanza un StopIteration.

class object

Retorna un nuevo objeto indiferenciado. object es la base de todas las clases. Tiene todos los métodos que son comunes a todas las instancias de clases de Python. Esta función no acepta ningún argumento.

Nota

object no tiene un __dict__, así que no puedes asignar atributos arbitrarios a una instancia de la clase object.

oct(x)

Convierte un número entero a una cadena octal con prefijo «0o». El resultado es una expresión válida de Python. Si x no es un objeto de la clase Python int, tiene que tener definido un método __index__() que retorne un entero. Por ejemplo:

>>> oct(8)
'0o10'
>>> oct(-56)
'-0o70'

Si quieres convertir un número entero a una cadena octal, tanto con prefijo «0o» como sin el, puedes usar cualquiera de las siguientes formas.

>>> '%#o' % 10, '%o' % 10
('0o12', '12')
>>> format(10, '#o'), format(10, 'o')
('0o12', '12')
>>> f'{10:#o}', f'{10:o}'
('0o12', '12')

Véase también format() para más información.

open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)

Abre file y retorna un file object correspondiente. Si el archivo no se puede abrir, se lanza un OSError. Consulte Leyendo y escribiendo archivos para obtener más ejemplos de cómo utilizar esta función.

file es un path-like object que da la ruta (absoluta o relativa al directorio de trabajo actual) del fichero a ser abierto o un descriptor de fichero entero del fichero a ser envuelto. (Si un descriptor de fichero es dado, será cerrado cuando el objeto de entrada-salida sea cerrado, a menos que closefd esté puesto a False.)

mode es una cadena opcional que especifica el modo en el cual el fichero es abierto. Su valor por defecto es 'r' que significa que está abierto para lectura en modo texto. Otros valores comunes son ’w’ para escritura (truncando el fichero si ya existe), ’x’ para creación en exclusiva y ’a’ para añadir (lo que en algunos sistemas Unix implica que toda la escritura añade al final del fichero independientemente de la posición de búsqueda actual). En modo texto, si no se especifica encoding entonces la codificación empleada es dependiente de plataforma: se invoca a locale.getpreferredencoding(False) para obtener la codificación regional actual. (Para lectura y escritura de bytes en crudo usa el modo binario y deja encoding sin especificar). Los modos disponibles son:

Carácter

Significado

’r’

abierto para lectura (por defecto)

'w'

abierto para escritura, truncando primero el fichero

'x'

abierto para creación en exclusiva, falla si el fichero ya existe

’a’

abierto para escritura, añadiendo al final del fichero si este existe

'b'

modo binario

’t’

modo texto (por defecto)

’+’

abierto para actualizar (lectura y escritura)

El modo por defecto es ’r’ (abierto para lectura de texto, sinónimo de ’rt’. Los modos ’w+’ y ’w+b’ abren y truncan el fichero. Los modos ’r+’ y ’r+b’ abren el fichero sin truncarlo.

Como se menciona en Resumen, Python distingue entre I/O binario y de texto. Los ficheros abiertos en modo binario (incluyendo ’b’ en el argumento mode) retornan su contenido como objetos de bytes sin ninguna descodificación. En modo de texto (por defecto, o cuando se incluye ’t’ en el argumento mode), los contenidos del fichero se retornan como str, tras descodificar los bytes usando una codificación dependiente de plataforma o usando el encoding especificado como argumento.

Hay un carácter adicional permitido para indicar un modo, ’U’, que ya no tiene ningún efecto y que se considera obsoleto. Permitía anteriormente en modo texto universal newlines, lo que se convirtió en el comportamiento por defecto en Python 3.0. Para más detalles, referirse a la documentación del parámetro newline.

Nota

Python no depende de la noción de ficheros de texto del sistema operativo subyacente; todo el procesado lo hace Python, y es por tanto independiente de plataforma.

buffering is an optional integer used to set the buffering policy. Pass 0 to switch buffering off (only allowed in binary mode), 1 to select line buffering (only usable in text mode), and an integer > 1 to indicate the size in bytes of a fixed-size chunk buffer. Note that specifying a buffer size this way applies for binary buffered I/O, but TextIOWrapper (i.e., files opened with mode='r+') would have another buffering. To disable buffering in TextIOWrapper, consider using the write_through flag for io.TextIOWrapper.reconfigure(). When no buffering argument is given, the default buffering policy works as follows:

Los ficheros binarios son transmitidos por búferes con tamaños fijos de bloque; el tamaño del búfer es escogido usando un intento heurístico para determinar el tamaño de bloque del dispositivo y recurriendo sino a io.DEFAULT_BUFFER_SIZE. En muchos sistemas, el búfer tendrá normalmente un tamaño de 4096 o 8192 bytes.

Los ficheros de texto «interactivos» (ficheros para los cuales isatty() retorna True) usan buffering por líneas. Otros ficheros de texto emplean la norma descrita anteriormente para ficheros binarios.

encoding es el nombre de la codificación empleada con el fichero. Esto solo debe ser usado en el modo texto. La codificación por defecto es dependiente de plataforma (aquello que retorna locale.getpreferredencoding()), pero puede emplearse cualquier text encoding soportado por Python. Véase el módulo codecs para la lista de codificaciones soportadas.

errors es una cadena opcional que especifica como deben manejarse los errores de codificación y descodificación – esto no puede ser usado en modo binario. Están disponibles varios gestores de error (listados en Manejadores de errores), pero también es válido cualquier nombre de gestión de error registrado con codecs.register_error(). Los nombres estándar incluyen:

'strict' para lanzar una excepción ValueError si hay un error de codificación. El valor por defecto, None, produce el mismo efecto.

'ignore' ignora los errores. Nótese que ignorar errores de codificación puede conllevar la pérdida de datos.

'replace' provoca que se inserte un marcador de reemplazo (como '?') en aquellos sitios donde hay datos malformados.

'surrogateescape' will represent any incorrect bytes as low surrogate code units ranging from U+DC80 to U+DCFF. These surrogate code units will then be turned back into the same bytes when the surrogateescape error handler is used when writing data. This is useful for processing files in an unknown encoding.

'xmlcharrefreplace' está soportado solamente cuando se escribe a un fichero. Los caracteres que no estén soportados por la codificación son reemplazados por la referencia al carácter XML apropiado &#nnn;.

'backslashreplace' reemplaza datos malformados con las secuencias de escapes de barra invertida de Python.

'namereplace' reemplaza caracteres no soportados con secuencias de escape \N{...} (y también está sólo soportado en escritura).

newline controla cómo funciona el modo universal newlines (solo aplica a modo texto). Puede ser None, '', '\n', '\r', y '\r\n'. Funciona de la siguiente manera:

Cuando se está leyendo entrada desde el flujo, si newline es None, el modo universal newlines es activado. Las líneas en la entrada pueden terminar en '\n', '\r', o '\r\n', y serán traducidas a '\n' antes de ser retornadas a la entidad que llama. Si es '', el modo universal newlines estará activado pero los finales de línea se retornan sin traducir a la entidad que llama. Si tiene cualquiera de los otros valoras válidos, las líneas de entrada estarán terminadas sólo por la cadena dada, y los finales de línea serán retornados sin traducir a la entidad que llama.

Cuando se escribe salida al flujo, si newline es None, cualquier carácter '\n' escrito es traducido al separador de línea por defecto en el sistema, os.linesep. Si newline es '' o '\n', entonces no se produce ninguna traducción. Si newline toma cualquiera de los otros valores válidos, entonces cualquier carácter '\n' escrito es traducido a la cadena indicada.

Si closefd es False y se indica un descriptor de fichero en vez de un nombre de fichero, el descriptor se mantendrá abierto cuando se cierre el fichero. Si se indica un nombre de fichero, closefd debe ser True (lo es por defecto), ya que de otra forma se lanzará un error.

Un abridor personalizado puede emplearse pasando un invocable como opener. El descriptor de fichero del objeto se obtiene llamando a opener con (file, flags). opener debe retornar un descriptor de fichero abierto (pasando os.open como opener resulta en una funcionalidad similar a None).

El nuevo fichero creado es no-heredable.

El siguiente ejemplo emplea el parámetro dir_fd de la función os.open() para abrir un fichero relativo a un directorio dado:

>>> import os
>>> dir_fd = os.open('somedir', os.O_RDONLY)
>>> def opener(path, flags):
...     return os.open(path, flags, dir_fd=dir_fd)
...
>>> with open('spamspam.txt', 'w', opener=opener) as f:
...     print('This will be written to somedir/spamspam.txt', file=f)
...
>>> os.close(dir_fd)  # don't leak a file descriptor

El tipo de file object retornado por la función open() depende del modo. Cuando se emplea open() para abrir un fichero en modo texto ('w', 'r', 'wt', 'rt', etc.), retorna una subclase de io.TextIOBase (específicamente io.TextIOWrapper). Cuando se emplea para abrir un fichero en modo binario con buffering, la clase retornada es una subclase de io.BufferedIOBase. La clase exacta varía: en modo binario de lectura, retorna io.BufferedReader; en modo de escritura y adición en binario, retorna io.BufferedWriter, y en modo de escritura/lectura, retorna io.BufferedRandom. Si el buffering está desactivado, el flujo en crudo, una subclase de io.RawIOBase, io.FileIO, es retornada.

Véase también los módulos para manejo de ficheros, como fileinput, io (donde es declarada open()), os, os.path, tempfile, y shutil.

Lanza un evento de auditoría open con los argumentos file, mode, flags.

Los argumentos mode y flags pueden haber sido modificados o inferidos de la llamada original.

Distinto en la versión 3.3:

El parámetro opener fue añadido.

El modo 'x' fue añadido.

IOError era la excepción lanzada anteriormente, ahora es un alias de OSError.

Se lanza FileExistsError si ya existe el fichero abierto en modo de creación exclusiva ('x').

Distinto en la versión 3.4:

El fichero ahora es no-heredable.

Deprecated since version 3.4, will be removed in version 3.10: El modo 'U'.

Distinto en la versión 3.5:

Si la llamada al sistema es interrumpida y el gestor de señales no lanza una excepción, ahora la función reintenta la llamada de sistema en vez de lanzar una excepción InterruptedError (véase PEP 475 [https://www.python.org/dev/peps/pep-0475] para la justificación).

El gestor de errores 'namereplace' fue añadido.

Distinto en la versión 3.6:

Añadido el soporte para aceptar objetos que implementan os.PathLike.

En Windows, abrir un búfer en la consola puede retornar una subclase de io.RawIOBase en vez de io.FileIO.

ord(c)

Al proporcionarle una cadena representando un carácter Unicode, retorna un entero que representa el código Unicode de ese carácter. Por ejemplo, ord('a') retorna el entero 97 y ord('€') (símbolo del Euro) retorna 8364. Esta es la función inversa de chr().

pow(base, exp[, mod])

Retorna base elevado a exp; si mod está presente, retorna base elevado a exp, módulo mod (calculado de manera más eficiente que pow(base, exp) % mod). La forma con dos argumentos pow(base, exp) es equivalente a usar el operador potencia: base**exp.

The arguments must have numeric types. With mixed operand types, the coercion rules for binary arithmetic operators apply. For int operands, the result has the same type as the operands (after coercion) unless the second argument is negative; in that case, all arguments are converted to float and a float result is delivered. For example, pow(10, 2) returns 100, but pow(10, -2) returns 0.01. For a negative base of type int or float and a non-integral exponent, a complex result is delivered. For example, pow(-9, 0.5) returns a value close to 3j.

Para operandos int como base y exp, si mod está presente, mod debe ser también de tipo entero y distinto de cero. Si mod está presente y exp es negativo, base debe ser un número primo relativo a mod. En ese caso, se retorna pow(inv_base, -exp, mod), dónde inv_base es la inversa al módulo mod de base.

Aquí tienes un ejemplo de cómo calcular la inversa de 38 módulo 97:

>>> pow(38, -1, mod=97)
23
>>> 23 * 38 % 97 == 1
True

Distinto en la versión 3.8: Para operandos int, la forma de pow con tres argumentos acepta ahora que el segundo argumento sea negativo, lo que permite el cálculo de inversos modulares.

Distinto en la versión 3.8: Permite argumentos de palabra clave. Anteriormente, solo se soportaba el uso de argumentos posicionales.

print(*objects, sep=' ', end='\n', file=sys.stdout, flush=False)

Imprime objects al flujo de texto file, separándolos por sep y seguidos por end. sep, end, file y flush, si están presentes, deben ser dados como argumentos por palabra clave.

Todos los argumentos que no son por palabra clave se convierten a cadenas tal y como str() hace y se escriben al flujo, separados por sep y seguidos por end. Tanto sep como end deben ser cadenas; también pueden ser None, lo cual significa que se empleen los valores por defecto. Si no se indica objects, print() escribirá end.

El argumento file debe ser un objeto que implemente un método write(string); si éste no está presente o es None, se usará sys.stdout. Dado que los argumentos mostrados son convertidos a cadenas de texto, print() no puede ser utilizada con objetos fichero en modo binario. Para esos, utiliza en cambio file.write(…).

Que la salida sea en búfer o no suele estar determinado por file, pero si el argumento por palabra clave flush se emplea, el flujo se descarga forzosamente.

Distinto en la versión 3.3: Añadido el argumento por palabra clave flush.

class property(fget=None, fset=None, fdel=None, doc=None)

Retorna un atributo propiedad.

fget es una función para obtener el valor de un atributo. fset es una función para asignar el valor de un atributo. fdel es una función para eliminar el valor de un atributo. Y doc crea un docstring para el atributo.

Un caso de uso típico es la definición de un atributo gestionado x:

class C:
    def __init__(self):
        self._x = None

    def getx(self):
        return self._x

    def setx(self, value):
        self._x = value

    def delx(self):
        del self._x

    x = property(getx, setx, delx, "I'm the 'x' property.")

Si c es una instancia de C, c.x invocará el obtenedor (getter), c.x = value invocará el asignador (setter) y del c.x el suprimidor (deleter).

Si está indicada, doc será la docstring del atributo propiedad. En caso contrario, la propiedad copiará la dosctring de fget si ésta existe. Esto permite crear propiedades de sólo lectura de forma fácil empleando property() como decorator:

class Parrot:
    def __init__(self):
        self._voltage = 100000

    @property
    def voltage(self):
        """Get the current voltage."""
        return self._voltage

El decorador @property convierte el método voltage() en un «getter» para un atributo de sólo lectura con el mismo nombre, y asigna «Get the current voltage.» como la docstring de voltage.

Un objeto propiedad tiene métodos getter, setter, y deleter que pueden usarse como decoradores que crean una copia de la propiedad con su correspondiente función de acceso asignada a la función decorada. Esto se explica mejor con un ejemplo:

class C:
    def __init__(self):
        self._x = None

    @property
    def x(self):
        """I'm the 'x' property."""
        return self._x

    @x.setter
    def x(self, value):
        self._x = value

    @x.deleter
    def x(self):
        del self._x

Este código equivale exactamente al primer ejemplo. Asegúrese de otorgarle a las funciones adicionales el mismo nombre que la propiedad original (x en este caso.)

El objeto propiedad retornado tiene también los atributos fget, fset, y fdel correspondientes a los argumentos del constructor.

Distinto en la versión 3.5: Las docstrings de los objetos propiedad son escribibles.

class range(stop)

class range(start, stop[, step])

range, más que una función, es en realidad un tipo de secuencia inmutable, tal y como está documentado en Rangos y Tipos secuencia — list, tuple, range.

repr(object)

Retorna una cadena que contiene una representación imprimible de un objeto. Para muchos tipos, esta función intenta retornar la cadena que retornaría el objeto con el mismo valor cuando es pasado a eval(), de lo contrario la representación es una cadena entre corchetes angulares («<>») que contiene el nombre del tipo del objeto junto con información adicional que incluye a menudo el nombre y la dirección del objeto. Una clase puede controlar lo que esta función retorna definiendo un método __repr__().

reversed(seq)

Retorna un iterator reverso. seq debe ser un objeto que tenga un método __reversed__() o que soporte el protocolo de secuencia (el método __len__() y el método __getitem__() con argumentos enteros comenzando en 0).

round(number[, ndigits])

Retorna number redondeado a ndigits de precisión después del punto decimal. Si ndigits es omitido o es None, retorna el entero más cercano a su entrada.

Para los tipos integrados (built-in) que soportan round(), los valores son redondeados al múltiplo de 10 más cercano a la potencia menos ndigits; si dos múltiplos están igual de cerca, el redondeo se hace hacia la opción par (así que por ejemplo tanto round(0.5) como round(-0.5) son 0, y round(1.5) es 2).

Para un objeto number general de Python, round delega a number.__round__.

Nota

El comportamiento de round() para flotantes puede ser sorprendente: por ejemplo, round(2.675, 2) da 2.67 en vez de los 2.68 esperados. Esto no es un error: es el resultado del hecho de que la mayoría de fracciones decimales no se puede representar de forma exacta como flotantes. Véase Aritmética de Punto Flotante: Problemas y Limitaciones para más información.

class set([iterable])

Retorna un nuevo objeto set , opcionalmente con elementos tomados de iterable. set es una clase integrada (built-in). Véase set y Conjuntos — set, frozenset para documentación sobre esta clase.

Para otros contenedores ver las clases integradas (built-in) frozenset, list, tuple, y dict, así como el módulo collections.

setattr(object, name, value)

Es la función complementaria a getattr(). Los argumentos son un objeto, una cadena, y un valor arbitrario. La cadena puede nombrar un atributo existente o uno nuevo. La función asigna el valor al atributo si el objeto lo permite. Por ejemplo, setattr(x, 'foobar', 123) es equivalente a x.foobar = 123.

Nota

Since private name mangling happens at compilation time, one must manually mangle a private attribute’s (attributes with two leading underscores) name in order to set it with setattr().

class slice(stop)

class slice(start, stop[, step])

Return a slice object representing the set of indices specified by range(start, stop, step). The start and step arguments default to None. Slice objects have read-only data attributes start, stop and step which merely return the argument values (or their default). They have no other explicit functionality; however they are used by NumPy and other third party packages. Slice objects are also generated when extended indexing syntax is used. For example: a[start:stop:step] or a[start:stop, i]. See itertools.islice() for an alternate version that returns an iterator.

sorted(iterable, /, *, key=None, reverse=False)

Retorna una nueva lista ordenada a partir de los elementos en iterable.

Tiene dos argumentos opcionales que deben ser especificados como argumentos de palabra clave.

key especifica una función de un argumento que es empleada para extraer una clave de comparación de cada elemento en iterable (por ejemplo, key=str.lower`). El valor por defecto es ``None (compara los elementos directamente).

reverse es un valor boleado. Si está puesto a True, entonces la lista de elementos se ordena como si cada comparación fuera reversa.

Puedes usar functools.cmp_to_key() para convertir las funciones cmp a la antigua usanza en funciones key.

La función built-in sorted() está garantizada en cuanto a su estabilidad. Un ordenamiento es estable si garantiza que no cambia el orden relativo de elementos que resultan igual en la comparación — esto es de gran ayuda para ordenar en múltiples pases (por ejemplo, ordenar por departamento, después por el escalafón de salario).

The sort algorithm uses only < comparisons between items. While defining an __lt__() method will suffice for sorting, PEP 8 [https://www.python.org/dev/peps/pep-0008] recommends that all six rich comparisons be implemented. This will help avoid bugs when using the same data with other ordering tools such as max() that rely on a different underlying method. Implementing all six comparisons also helps avoid confusion for mixed type comparisons which can call reflected the __gt__() method.

Para ejemplos de ordenamiento y para un breve tutorial sobre ello, ver HOW TO - Ordenar.

@staticmethod

Transforma un método en un método estático.

Un método estático no recibe un primer argumento implícito. Para declarar un método estático, utiliza esta expresión:

class C:
    @staticmethod
    def f(arg1, arg2, ...): ...

La forma @staticmethod es una función decorator — ver Definiciones de funciones para más detalles.

Un método estático puede ser llamado sobre la clase (como C.f()) o sobre una instancia (como C().f()`).

Los métodos estáticos en Python son similares a los que se encuentran en Java o C++. Ver también classmethod() para una variante que es útil para crear constructores de clase alternativos.

Como todos los decoradores, es también posible llamar a staticmethod como una función normal y hacer algo con su resultado. Esto es necesario a veces cuando necesitas una referencia a una función desde el cuerpo de una clase y quieres evitar la transformación automática a un método de la instancia. Para dichos casos, emplea esta expresión:

class C:
    builtin_open = staticmethod(open)

Para más información sobre métodos estáticos, ver Jerarquía de tipos estándar.

class str(object='')

class str(object=b'', encoding='utf-8', errors='strict')

Retorna una versión str del object. Ver str() para más detalles.

str es la class cadena built-in . Para información general sobre strings, ver Cadenas de caracteres — str.

sum(iterable, /, start=0)

Suma start y los elementos de un iterable de izquierda a derecha y Retorna el total. Los elementos del iterable son normalmente números, y el valor start no puede ser una cadena.

Para algunos casos de uso, hay buenas alternativas a sum(). La manera preferente y más rápida de concatenar secuencias de cadenas es llamado a ’’.join(sequence). Para añadir valores de punto flotante con precisión extendida, ver math.fsum(). Para concatenar series de iterabais, considera usar itertools.chain().

Distinto en la versión 3.8: El parámetro start puede ser especificado como un argumento de palabra clave.

super([type[, object-or-type]])

Retorna un objeto proxy que delega las llamadas de métodos a clases padre o hermanas de type. Esto es útil para acceder métodos heredados que han sido invalidados en una clase.

object-or-type determina el method resolution order a ser buscado. La búsqueda empieza desde la clase justo después de type.

Por ejemplo __mro__ de object-or-type es D -> B -> C -> A -> object y el valor de type es B, entonces super() busca C -> A -> object.

El atributo __mro__ de object-or-type lista el orden de búsqueda del método de solución empleado por getattr() y super(). El atributo es dinámico y puede cambiar en cuanto la jerarquía de herencia se actualiza.

Si se omite el segundo argumento, el objeto super retornado no está vinculado. Si el segundo argumento es un objeto, isinstance(obj, type) debe ser verdadero. Si el segundo argumento es un tipo, issubclass(type2, type) debe ser verdadero (esto es útil para classmethods).

Hay dos casos de uso típicos para super. En una jerarquía de clases con herencia única, super puede ser utilizado para referirse a las clases padre sin llamarlas explícitamente, haciendo el código más sencillo de mantener. Este uso es muy similar al de super en otros lenguajes de programación.

The second use case is to support cooperative multiple inheritance in a dynamic execution environment. This use case is unique to Python and is not found in statically compiled languages or languages that only support single inheritance. This makes it possible to implement «diamond diagrams» where multiple base classes implement the same method. Good design dictates that such implementations have the same calling signature in every case (because the order of calls is determined at runtime, because that order adapts to changes in the class hierarchy, and because that order can include sibling classes that are unknown prior to runtime).

Para ambos casos, la llamada típica de una superclase se parece a:

class C(B):
    def method(self, arg):
        super().method(arg)    # This does the same thing as:
                               # super(C, self).method(arg)

Además de para los métodos de búsqueda, super() también funciona para búsquedas de atributos. Un caso de uso posible para esto es llamar a descriptores en una clase padre o hermana.

Nótese que super() se implementa como parte del proceso vinculante para búsquedas de atributos explícitos punteados tales como super().__getitem__(name). Lo hace implementando su propio método __getattribute__() para buscar clases en un orden predecible que soporte herencia múltiple cooperativa. De la misma manera, super() no está definida para búsquedas implícitas usando declaraciones o operadores como super()[name].

Nótese también, que aparte de en su forma sin argumentos, super() no está limitada a su uso dentro de métodos. La forma con dos argumentos especifica de forma exacta los argumentos y hace las referencias apropiadas. La forma sin argumentos solo funciona dentro de una definición de clase, ya que el compilador completa los detalles necesarios para obtener correctamente la clase que está siendo definida, así como accediendo a la instancia actual para métodos ordinarios.

Para sugerencias prácticas sobre como diseñas clases cooperativas usando super(), véase guía de uso de super() [https://rhettinger.wordpress.com/2011/05/26/super-considered-super/].

class tuple([iterable])

Más que una función, tuple es en realidad un tipo de secuencia inmutable, tal y como está documentado en Tuplas y Tipos secuencia — list, tuple, range.

class type(object)

class type(name, bases, dict, **kwds)

Con un argumento, retorna el tipo de un object. El valor de retorno es un objeto tipo y generalmente el mismo objeto que el retornado por object.__class__.

La función integrada isinstance() es la recomendada para testear el tipo de un objeto, ya que tiene en cuenta las subclases.

Con tres argumentos, retorna un nuevo tipo objeto. Esta es esencialmente una forma dinámica de la declaración class. La cadena de caracteres name es el nombre de la clase y se convierte en el atributo __name__. La tupla bases contiene las clases base y se convierte en el atributo __bases__; si está vacío, se agrega object, la base última de todas las clases. El diccionario dict contiene definiciones de métodos y atributos para el cuerpo de la clase; se puede copiar o ajustar antes de convertirse en el atributo __dict__. Las siguientes dos declaraciones crean objetos idénticos type:

>>> class X:
...     a = 1
...
>>> X = type('X', (), dict(a=1))

Ver también Objetos Tipo.

Keyword arguments provided to the three argument form are passed to the appropriate metaclass machinery (usually __init_subclass__()) in the same way that keywords in a class definition (besides metaclass) would.

See also Personalización de creación de clases.

Distinto en la versión 3.6: Subclases de type que no sobrecarguen type.__new__ ya no pueden usar la forma con un argumento para obtener el tipo de un objeto.

vars([object])

Retorna el atributo __dict__ para un módulo, clase, instancia o cualquier otro objeto con un atributo __dict__.

Los objetos como módulos o instancias tienen un atributo actualizable __dict__; sin embargo, otros objetos pueden tener restricciones de escritura en sus atributos __dict__ (por ejemplo, hay clases que usan types.MappingProxyType para evitar actualizaciones directas del diccionario).

Sin un argumento, vars() funciona como locals(). Ten en cuenta que el diccionario de locals solo es útil para lecturas ya que las actualizaciones del diccionario de locals son ignoradas.

Una excepción TypeError se genera si se especifica un objeto pero no tiene un atributo __dict__ (por ejemplo, si su clase define el atributo __slots__).

zip(*iterables)

Produce un iterador que agrega elementos de cada uno de los iterables.

Retorna un iterador de tuplas, donde el i-ésimo elemento de la tupla contiene el i-ésimo elemento de cada una de las secuencias o iterables en los argumentos. El iterador para cuando se agota el iterable de entrada más corto. Con un sólo argumento iterable, retorna un iterador de 1 tupla. Sin argumentos, retorna un iterador vacío. Es equivalente a:

def zip(*iterables):
    # zip('ABCD', 'xy') --> Ax By
    sentinel = object()
    iterators = [iter(it) for it in iterables]
    while iterators:
        result = []
        for it in iterators:
            elem = next(it, sentinel)
            if elem is sentinel:
                return
            result.append(elem)
        yield tuple(result)

La evaluación de izquierda a derecha de los iterables está garantizada. Esto permite emplear una expresión idiomática para agregar una serie de datos en grupos de tamaño n usando zip(*[iter(s)]*n). Esto repite el mismo iterador n veces de forma que cada tupla de salida tiene el resultado de n llamadas al iterador. Esto tiene el efecto de dividir la entrada en trozos de longitud n.

zip() solo debería utilizarse con tamaños de entrada diferentes en el caso de que no te importe que haya valores sin agrupar de los iterables más largos. Si en cambio esos valores son importantes, utiliza en cambio itertools.zip_longest().

zip() en conjunción con el operador * puede usar para descomprimir (unzip) una lista:

>>> x = [1, 2, 3]
>>> y = [4, 5, 6]
>>> zipped = zip(x, y)
>>> list(zipped)
[(1, 4), (2, 5), (3, 6)]
>>> x2, y2 = zip(*zip(x, y))
>>> x == list(x2) and y == list(y2)
True

__import__(name, globals=None, locals=None, fromlist=(), level=0)

Nota

Ésta es una función avanzada que no se necesita en el uso cotidiano de programación en Python, a diferencia de importlib.import_module().

Esta función es invocada por la declaración import. Puede ser reemplazada para cambiar la semántica de la declaración import (mediante la importación del módulo builtins y su asignación a builtins.__import__), pero esto está fuertemente no recomendado ya que es normalmente mucho más simple usar ganchos (hooks) de importación (ver PEP 302 [https://www.python.org/dev/peps/pep-0302]) para obtener los mismos objetivos y sin causar problemas en código que asume que la implementación por defecto de importaciones está siendo utilizada. El uso directo de __import__() tampoco está recomendado y se prefiere importlib.import_module().

La función importa el módulo name, usando potencialmente las globals y locals indicadas para determinar como interpretar el nombre en el contexto de un paquete. fromlist indica los nombres de objetos o submódulos que deberían ser importados del módulo indicado por name. La implementación estándar no utiliza su argumento locals para nada, y usa globals solo para determinar el contexto en un paquete de la declaración import.

level especifica si usar importaciones absolutas o relativas. 0 (por defecto) significa sólo realizar importaciones absolutas. Valores positivos de level indican el número de directorios progenitores relativos al del módulo para buscar llamando a __import__() (ver PEP 328 [https://www.python.org/dev/peps/pep-0328] para los detalles).

Cuando la variable name tiene la forma package.module, normalmente el paquete del nivel más alto (el nombre hasta el primer punto) se retorna, no el modulo llamado por name. Sin embargo, cuando un argumento fromlist no vacío es indicado, el módulo llamado por name es retornado.

Por ejemplo, la declaración import spam resulta en un bytecode similar al siguiente código:

spam = __import__('spam', globals(), locals(), [], 0)

La declaración import spam.ham resulta en esta llamada:

spam = __import__('spam.ham', globals(), locals(), [], 0)

Nótese cómo __import__() retorna el módulo del nivel superior en este caso porque este es el objeto que está enlazado a un nombre por la declaración import.

Por otra parte, la declaración from spam.ham import eggs, sausage as saus resulta en

_temp = __import__('spam.ham', globals(), locals(), ['eggs', 'sausage'], 0)
eggs = _temp.eggs
saus = _temp.sausage

Aquí, el módulo spam.ham es retornado desde __import__(). Desde este objeto, los nombres a importar son obtenidos y asignados a sus nombres respectivos.

Si simplemente quieres importar un módulo (potencialmente dentro de un paquete) por nombre, usa importlib.import_module().

Distinto en la versión 3.3: Valores negativos para level ya no están soportados (lo que también cambia el valor por defecto a 0).

Distinto en la versión 3.9: Cuando se utilizan las opciones de línea de comando -E o -I, la variable de entorno PYTHONCASEOK ahora se ignora.

Notas al pie

1

Ten en cuenta que el parser sólo acepta la convención de final de línea de tipo Unix. Si estás leyendo el código de un fichero, asegúrate de usar la el modo de conversión de nueva línea para convertir las líneas de tipo Windows o Mac.

Constantes incorporadas

Un pequeño número de constantes viven en el espacio de nombres incorporado. Ellas son:

False

El valor falso del tipo bool. Las asignaciones a False son ilegales y generan un SyntaxError.

True

El valor verdadero del tipo bool. Las asignaciones a True son ilegales y generan un SyntaxError.

None

El único valor del tipo NoneType. None se utiliza con frecuencia para representar la ausencia de un valor, como cuando los argumentos predeterminados no se pasan a una función. Las asignaciones a None son ilegales y generan un SyntaxError.

NotImplemented

Valor especial que debe ser retornado por los métodos especiales binarios (por ejemplo __eq__(), __lt__(), __add__(), __rsub__(), etc.) para indicar que la operación es no implementado con respecto al otro tipo; puede ser retornado por los métodos especiales binarios in situ (por ejemplo __imul__(), __iand__(), etc.) con el mismo propósito. No debe evaluarse en un contexto booleano.

Nota

Cuando un método binario (o in situ) retorna NotImplemented, el intérprete intentará la operación reflejada en el otro tipo (o algún otro recurso alternativo, según el operador). Si todos los intentos retornan NotImplemented, el intérprete lanzará una excepción apropiada. Retornar incorrectamente NotImplemented dará como resultado un mensaje de error engañoso o el valor de NotImplemented se retornará al código Python.

Consulte Implementar operaciones aritméticas para ver ejemplos.

Nota

NotImplementedError y NotImplemented no son lo mismo, aunque tengan nombres y propósitos similares. Consulte NotImplementedError para obtener más información sobre cuándo usarlo.

Distinto en la versión 3.9: La evaluación de NotImplemented en un contexto booleano está en desuso. Si bien actualmente se evalúa como verdadero, emitirá un DeprecationWarning. Lanzará un TypeError en una versión futura de Python.

Ellipsis

Lo mismo que la elipsis literal «...». Valor especial que se utiliza principalmente junto con la sintaxis de segmentación extendida para tipos de datos de contenedor definidos por el usuario.

__debug__

Esta constante es verdadera si Python no se inició con una opción -O. Vea también la instrucción assert.

Nota

Los nombres: None, False, True y __debug__ no se pueden reasignar (asignaciones a ellos, incluso como un nombre de atributo, lanza SyntaxError ), por lo que pueden considerarse constantes «verdaderas».

Constantes agregadas por el módulo site

El módulo site (que se importa automáticamente durante el inicio, excepto si se proporciona la opción -S en la línea de comandos) agrega varias constantes al espacio de nombres integrado. Son útiles para el intérprete interactivo y no deben usarse en programas.

quit(code=None)

exit(code=None)

Objetos que cuando se imprimen, muestra un mensaje como «Use quit() o Ctrl-D (i.e. EOF) to exit», y cuando se llama, lanza SystemExit con el código de salida especificado.

copyright

credits

Objetos que al ser impresos o llamados imprimen el texto de derechos de autor o créditos, respectivamente.

license

Objeto que cuando se imprime, muestra el mensaje «Escriba licencia () para ver el texto completo de la licencia», y cuando se le llama, muestra el texto completo de la licencia en forma de buscapersonas (una pantalla a la vez).

Tipos Integrados

Esta sección describe los tipos de datos estándar que vienen incluidos en el intérprete.

Los principales tipos de datos son: numéricos, secuencias, mapas, clases, instancias y excepciones.

Algunas clases de tipo colección son mutables. Los métodos que añaden, retiran u ordenan los contenidos lo hacen internamente, y a no ser que retornen un elemento concreto, nunca retornan la propia instancia contenedora, sino None.

Algunas operaciones son soportadas por varios tipos de objetos diferentes; por ejemplo, prácticamente todos los objetos pueden ser comparados por igualdad, evaluados para ser considerados como valores booleanos, o representarse en forma de cadena de caracteres (Ya sea con la función repr() o la ligeramente diferente str()). Esta última es la usada implícitamente por la función print().

Evaluar como valor verdadero/falso

Cualquier objeto puede ser evaluado como si fuera un valor verdadero o falso, para ser usado directamente en sentencias if o while, o como un operador en una operación booleana como las que veremos más adelante.

Por defecto, un objeto se considera verdadero a no ser que su clase defina o bien un método __bool__() que retorna False o un método __len__() que retorna cero, cuando se invoque desde ese objeto. 1 Aquí están listados la mayoría de los objetos predefinidos que se evalúan como falsos:

constantes definidas para tener valor falso: None y False.

cero en cualquiera de los diferentes tipos numéricos: 0, 0.0, 0j, Decimal(0), Fraction(0, 1)

cualquier colección o secuencia vacía: '', (), [], {}, set(), range(0)

Las operaciones y funciones predefinidas que retornan como resultado un booleano siempre retornan 0 o False para un valor falso, y 1 o True para un valor verdadero, a no ser que se indique otra cosa (Hay una excepción importante: Los operadores booleanos or y and siempre retornan uno de los dos operadores).

Operaciones booleanas — and, or, not

Estas son las operaciones booleanas, ordenadas de menor a mayor prioridad:

Operación

Resultado

Notas

x or y

si x es falso, entonces y, si no, x

(1)

x and y

si x es falso, entonces x, si no, y

(2)

not x

si x es falso, entonces True, si no, False

(3)

Notas:

Este operador usar lógica cortocircuitada, por lo que solo evalúa el segundo argumentos si el primero es falso.

Este operador usa lógica cortocircuitada, por lo que solo evalúa el segundo argumentos si el primero es verdadero.

El operador not tiene menos prioridad que los operadores no booleanos, así que not a == b se interpreta como not (a == b)`, y ``a == not b es un error sintáctico.

Comparaciones

Existen ocho operadores de comparación en Python. Todos comparten el mismo nivel de prioridad (que es mayor que el nivel de las operaciones booleanas). Las comparaciones pueden encadenarse de cualquier manera; por ejemplo, x < y <= z equivale a x < y and y <= z, excepto porque y solo se evalúa una vez (No obstante, en ambos casos z no se evalúa si no es verdad que x < y).

Esta tabla resumen las operaciones de comparación:

Operación

Significado

<

estrictamente menor que

<=

menor o igual que

>

estrictamente mayor que

>=

mayor o igual que

==

igual que

!=

diferente que

is

igualdad a nivel de identidad (Son el mismo objeto)

is not

desigualdad a nivel de identidad (no son el mismo objeto)

Nunca se consideran iguales objetos que son de tipos diferentes, con la excepción de los tipos numéricos. El operador == siempre está definido, pero en algunos tipos de objetos (Como por ejemplo, las clases) es equivalente al operador is. Los operadores <, <=, > y >= solo están definidos cuando tienen sentido; por ejemplo, si uno de los operadores es un número complejo, la comparación lanzará una excepción de tipo TypeError.

Non-identical instances of a class normally compare as non-equal unless the class defines the __eq__() method.

Instances of a class cannot be ordered with respect to other instances of the same class, or other types of object, unless the class defines enough of the methods __lt__(), __le__(), __gt__(), and __ge__() (in general, __lt__() and __eq__() are sufficient, if you want the conventional meanings of the comparison operators).

El comportamiento de los operadores is e is not no se puede personalizar; además, nunca lanzarán una excepción, no importa que dos objetos se comparen.

Hay otras dos operaciones con la misma prioridad sintáctica: in y not in, que son soportadas por aquellos tipos de datos que son de tipo iterable o que implementen el método __contains__().

Tipos numéricos — int, float, complex

Hay tres tipos numéricos distintos: enteros, números en coma flotante`y :dfn:`números complejos. Además, los booleanos son un subtipo de los enteros. Los enteros tiene precisión ilimitada. Los números en coma flotante se implementan normalmente usando el tipo double de C; Hay más información sobre la precisión y la representación interna de los números en coma flotante usadas por la máquina sobre la que se ejecuta tu programa en sys.float_info. Los números complejos tienen una parte real y otra imaginaria, ambas representadas con números en coma flotante. Para extraer estas partes del número complejo z se usan los métodos z.real y z.imag. (La librería estándar incluye tipos numéricos adicionales: fractions.Fraction para números racionales y decimal.Decimal para números en coma flotante con precisión definida por el usuario).

Los números se crean a partir de una expresión literal, o como resultado de una combinación de funciones predefinidas y operadores. Expresiones literales de números (incluyendo números expresados en hexadecimal, octal o binario) producen enteros. Si la expresión literal contiene un punto decimal o un signo de exponente, se genera un número en coma flotante. Si se añade como sufijo una 'j' o una 'J' a un literal numérico, se genera un número imaginario puro (Un número complejo con la parte real a cero), que se puede sumar a un número entero o de coma flotante para obtener un número complejo con parte real e imaginaria.

Python soporta completamente una aritmética mixta: Cuando un operador binario de tipo aritmético se encuentra con que los operadores son de tipos diferentes, el operando con el tipo de dato más «estrecho» o restrictivo se convierte o amplia hasta el nivel del otro operando. Los enteros son más «estrechos» que los de coma flotante, que a su vez son más estrechos que los números complejos. Las comparaciones entre números de diferentes tipos se comportan como si se compararan los valores exactos de estos. 2

Las funciones constructoras int(), float() y complex() se pueden usar para generar números de cada tipo determinado.

Todos los tipos numéricos (menos los complejos) soportan las siguientes operaciones (Para las prioridades de las operaciones, véase Prioridad de operador):

Operación

Resultado

Notas

Documentación completa

x + y

suma de x e y

x - y

resta de x e y

x * y

multiplicación de x por y

x / y

división de x por y

x // y

división entera de x por y

(1)

x % y

resto o residuo de x por y

(2)

-x

valor de x, negado

+x

valor de x, sin cambiar

abs(x)

valor absoluto de la magnitud de x

abs()

int(x)

valor de x convertido a entero

(3)(6)

int()

float(x)

valor de x convertido a número de punto flotante

(4)(6)

float()

complex(re, im)

un número complejo, con parte real re y parte imaginaria im. El valor de im por defecto vale cero.

(6)

complex()

c.conjugate()

conjugado del número complejo c

divmod(x, y)

el par de valores (x // y, x % y)

(2)

divmod()

pow(x, y)

x elevado a y

(5)

pow()

x ** y

x elevado a y

(5)

Notas:

También conocida como división entera. El resultado es un número entero en el sentido matemático, pero no necesariamente de tipo entero. El resultado se redondea de forma automática hacia menos infinito: 1//2 es 0, (-1)//2 es -1, 1//(-2) es -1 y (-1)//(-2) es 0.

No es apropiada para números complejos. Es preferible convertir a valores en coma flotante usando la función abs() si fuera apropiado.

Conversiones desde coma flotante a entero pueden redondearse o truncarse como en C; véanse las funciones math.floor() y math.ceil() para un mayor control.

float también acepta las cadenas de caracteres «nan» e «inf», con un prefijo opcional «+» o «-», para los valores Not a Number (NaN) e infinito positivo o negativo.

Python define pow(0, 0) y 0 ** 0 para que valgan 1, como es práctica habitual en los lenguajes de programación.

Los literales numéricos aceptables incluyen los dígitos desde el 0 hasta el 9, así como cualquier carácter Unicode equivalente (puntos de código con la propiedad Nd).

En https://www.unicode.org/Public/13.0.0/ucd/extracted/DerivedNumericType.txt se puede consultar una lista completa de los puntos de código con la propiedad Nd.

Todas las clases derivadas de numbers.Real (int y float) también soportan las siguientes operaciones:

Operación

Resultado

math.trunc(x)

x truncado a Integral

round(x[, n])

El valor de x redondeado a n dígitos, redondeando la mitad al número par más cercano (Redondeo del banquero). Si no se especifica valor para n, se asume 0.

math.floor(x)

el mayor número Integral que sea <= x

math.ceil(x)

el menor número Integral que sea >= x

Para más operaciones numéricas consulta los módulos math y cmath.

Operaciones de bits en números enteros

Las operaciones a nivel de bit solo tienen sentido con números enteros. El resultado de una de estas operaciones se calcula como si se hubiera realizado en una representación en complemento a dos que tuviera un número infinito de bits de signo.

La prioridad de todas las operaciones de bits son menores que las operaciones numéricas, pero mayores que las comparaciones; la operación unaria ~ tiene la misma prioridad que las otras operaciones unarias numéricas (+ y -).

Esta tabla lista las operaciones de bits, ordenadas de menor a mayor prioridad:

Operación

Resultado

Notas

x | y

la operación or entre x e y

(4)

x ^ y

la operación exclusive or entre x e y

(4)

x & y

la operación and entre x e y

(4)

x << n

El valor x desplazado a la izquierda n bits

(1)(2)

x >> n

valor de x desplazado a la derecha n bits

(1)(3)

~x

invierte los bits de x

Notas:

Los desplazamientos negativos son ilegales y lanzarán una excepción de tipo ValeError.

Un desplazamiento de n bits a la izquierda es equivalente a multiplicar por pow(2, n).

Un desplazamiento de n bits a la derecha es equivalente a efectuar la división de parte entera (floor) por pow(2, n).

Realizar estos cálculos con al menos un bit extra de signo en una representación finita de un número en complemento a dos (Un ancho de bits de trabajo de 1 + max(x.bit_length(), y.bit_length()) o más) es suficiente para obtener el mismo resultado que si se hubiera realizado con un número infinito de bits de signo.

Métodos adicionales de los enteros

El tipo int implementa la clase base abstracta numbers.Integral. Además, proporciona los siguientes métodos:

int.bit_length()

Retorna el número de bits necesarios para representar un número entero, excluyendo el bit de signo y los ceros a la izquierda:

>>> n = -37
>>> bin(n)
'-0b100101'
>>> n.bit_length()
6

De forma más precisa, si x es distinto de cero, entonces x.bit_length() es el único número entero positivo k tal que 2**(k-1) <= abs(x) < 2**k. De igual manera, cuando abs(x) es lo suficientemente pequeño para tener un logaritmo redondeado correctamente, entonces k = 1 + int(log(abs*x), 2)). Si x es cero, entonces x.bit_length() retorna 0.

Equivale a:

def bit_length(self):
    s = bin(self)       # binary representation:  bin(-37) --> '-0b100101'
    s = s.lstrip('-0b') # remove leading zeros and minus sign
    return len(s)       # len('100101') --> 6

Nuevo en la versión 3.1.

int.to_bytes(length, byteorder, *, signed=False)

Retorna un array de bytes que representan el número entero.

>>> (1024).to_bytes(2, byteorder='big')
b'\x04\x00'
>>> (1024).to_bytes(10, byteorder='big')
b'\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00'
>>> (-1024).to_bytes(10, byteorder='big', signed=True)
b'\xff\xff\xff\xff\xff\xff\xff\xff\xfc\x00'
>>> x = 1000
>>> x.to_bytes((x.bit_length() + 7) // 8, byteorder='little')
b'\xe8\x03'

El número entero se representa usando el número de bits indicados con length. Se lanzará la excepción OverflowError si no se puede representar el valor con ese número de bits.

El argumento byteorder determina el orden de representación del número entero. Si byteorder es "big", el byte más significativo ocupa la primera posición en el vector. Si byteorder es "little", el byte más significativo estará en la última posición. Para indicar que queremos usar el ordenamiento propio de la plataforma, podemos usar sys.byteorder como valor del argumento.

El parámetro signed determina si se usa el complemento a dos para representar los números enteros. Si signed es False, y se usa un valor entero negativo, se lanzará la excepción OverflowError. El valor por defecto para signed es False.

Nuevo en la versión 3.2.

classmethod int.from_bytes(bytes, byteorder, *, signed=False)

Retorna el número entero representado por el vector de bytes.

>>> int.from_bytes(b'\x00\x10', byteorder='big')
16
>>> int.from_bytes(b'\x00\x10', byteorder='little')
4096
>>> int.from_bytes(b'\xfc\x00', byteorder='big', signed=True)
-1024
>>> int.from_bytes(b'\xfc\x00', byteorder='big', signed=False)
64512
>>> int.from_bytes([255, 0, 0], byteorder='big')
16711680

El argumento bytes debe ser o bien un objeto tipo binario o un iterable que produzca bytes.

El argumento byteorder determina el orden de representación del número entero. Si byteorder es "big", el byte más significativo ocupa la primera posición en el vector. Si byteorder es "little", el byte más significativo estará en la última posición. Para indicar que queremos usar el ordenamiento propio de la plataforma, podemos usar sys.byteorder como valor del argumento.

El argumento signed determina si se representará el número entero usando complemento a dos.

Nuevo en la versión 3.2.

int.as_integer_ratio()

Retorna una pareja de números enteros cuya proporción es igual a la del numero entero original, y con un denominador positivo. En el caso de números enteros, la proporción siempre es el número original y 1 en el denominador.

Nuevo en la versión 3.8.

Métodos adicionales de Float

El tipo float implementa la clase numbers.Real clase base abstracta. Los números float tienen además los siguientes métodos.

float.as_integer_ratio()

Retorna una pareja de números enteros cuya proporción es exactamente igual que la del valor en punto flotante original, con un denominador positivo. Si se llama con valores infinitos lanza una excepción de tipo OverflowError y si se llama con NaN (Not A Number) eleva una excepción de tipo ValueError.

float.is_integer()

Retorna True si el valor en coma flotante se puede representar sin perdida con un número entero, y False si no se puede:

>>> (-2.0).is_integer()
True
>>> (3.2).is_integer()
False

Hay dos métodos que convierten desde y hacia cadenas de caracteres en hexadecimal. Como los valores en coma flotante en Python se almacenan internamente en binario, las conversiones desde o hacia cadenas decimales pueden implicar un pequeño error de redondeo. Pero con cadenas de texto en hexadecimal, las cadenas se corresponden y permiten representar de forma exacta los números en coma flotante. Esto puede ser útil, ya sea a la hora de depurar errores, o en procesos numéricos.

float.hex()

Retorna la representación de un valor en coma flotante en forma de cadena de texto en hexadecimal. Para números finitos, la representación siempre empieza con el prefijo 0x, y con una p justo antes del exponente.

classmethod float.fromhex(s)

Método de clase que retorna el valor en coma flotante representado por la cadena de caracteres en hexadecimal en s. La cadena s puede tener espacios en blanco al principio o al final.

Nótese que float.hex() es un método de instancia, mientras que float.fromhex() es un método de clase.

Una cadena de caracteres en hexadecimal sigue este formato:

[sign] ['0x'] integer ['.' fraction] ['p' exponent]

donde el componente opcional sign puede ser o bien + o -. Las componentes integer y fraction son cadenas de caracteres que solo usan dígitos hexadecimales, y exponent es un número decimal, precedido con un signo opcional. No se distingue entre mayúsculas y minúsculas, y debe haber al menos un dígito hexadecimal tanto en la parte entera como en la fracción. Esta sintaxis es similar a la sintaxis especificada en la sección 6.4.4.2 del estándar C99, y es también la sintaxis usada en Java desde la versión 1.5. En particular, la salida de float.hex() se puede usar como una cadena de caracteres en hexadecimal en código C o Java, y las cadenas de caracteres hexadecimal producidas por el carácter de formato %a``en C, o por el método Java, ``Double.toHexString, son aceptadas por float.fromhex().

Nótese que el valor del exponente está expresado en decimal, no en hexadecimal, e indica la potencia de 2 por la que debemos multiplicar el coeficiente. Por ejemplo, la cadena de caracteres hexadecimal 0x3.a7p10 representa el número en coma flotante (3 + 10./16 + 7./16**2) * 2.0**10, o 3740.0:

>>> float.fromhex('0x3.a7p10')
3740.0

Si aplicamos la operación inversa a 3740.0 retorna una cadena de caracteres hexadecimal diferente que, aun así, representa el mismo número:

>>> float.hex(3740.0)
'0x1.d380000000000p+11'

Calculo del hash de tipos numéricos

For numbers x and y, possibly of different types, it’s a requirement that hash(x) == hash(y) whenever x == y (see the __hash__() method documentation for more details). For ease of implementation and efficiency across a variety of numeric types (including int, float, decimal.Decimal and fractions.Fraction) Python’s hash for numeric types is based on a single mathematical function that’s defined for any rational number, and hence applies to all instances of int and fractions.Fraction, and all finite instances of float and decimal.Decimal. Essentially, this function is given by reduction modulo P for a fixed prime P. The value of P is made available to Python as the modulus attribute of sys.hash_info.

CPython implementation detail: Actualmente, el número primo usado es P = 2**31 - 1 para máquinas de 32 bits, y P = 2**61 - 1 en máquinas de 64 bits.

Aquí están las reglas en detalle:

Si x = m / n es un número racional no negativo y n no es divisible por P, se define hash(x) como m * invmod(n, P) % P, donde invmod(n, P) retorna la inversa de n modulo P.

Si x = m / n es un número racional no negativo y n es divisible por P (Pero no así m), entonces n no tiene módulo inverso de P y no se puede aplicar la regla anterior; en este caso, hash(x)``retorna el valor constante definido en ``sys.hash_info.inf.

Si x = m / n es un número racional negativo se define hash(x) como -hash(x). Si el resultado fuera -1, lo cambia por -2.

Los valores concretos sys.hash_info.inf, -sys.hash_info.inf y sys.hash_info.nan se usan como valores hash de infinito positivo, infinito negativo y NaN (Not a Number), respectivamente. (Todos los valores NaN comparten el mismo valor de hash).

Para un número complejo z (Una instancia de la clase complex), el valor de hash se calcula combinando los valores de hash de la parte real e imaginaria, usando la fórmula hash(z.real) + sys.hash_info.imag * hash(z.imag), módulo reducido 2**sys.hash_info.width, de forma que el valor obtenido esté en en rango range(-2**(sys.hash_info.width - 1), 2**(sys.hash_info.width - 1)). De nuevo, si el resultado fuera -1, se reemplaza por -2.

Para clarificar las reglas previas, aquí mostramos un ejemplo de código Python, equivalente al cálculo realizado en la función hash, para calcular el hash de un número racional, de tipo float, o complex:

import sys, math

def hash_fraction(m, n):
    """Compute the hash of a rational number m / n.

    Assumes m and n are integers, with n positive.
    Equivalent to hash(fractions.Fraction(m, n)).

    """
    P = sys.hash_info.modulus
    # Remove common factors of P.  (Unnecessary if m and n already coprime.)
    while m % P == n % P == 0:
        m, n = m // P, n // P

    if n % P == 0:
        hash_value = sys.hash_info.inf
    else:
        # Fermat's Little Theorem: pow(n, P-1, P) is 1, so
        # pow(n, P-2, P) gives the inverse of n modulo P.
        hash_value = (abs(m) % P) * pow(n, P - 2, P) % P
    if m < 0:
        hash_value = -hash_value
    if hash_value == -1:
        hash_value = -2
    return hash_value

def hash_float(x):
    """Compute the hash of a float x."""

    if math.isnan(x):
        return sys.hash_info.nan
    elif math.isinf(x):
        return sys.hash_info.inf if x > 0 else -sys.hash_info.inf
    else:
        return hash_fraction(*x.as_integer_ratio())

def hash_complex(z):
    """Compute the hash of a complex number z."""

    hash_value = hash_float(z.real) + sys.hash_info.imag * hash_float(z.imag)
    # do a signed reduction modulo 2**sys.hash_info.width
    M = 2**(sys.hash_info.width - 1)
    hash_value = (hash_value & (M - 1)) - (hash_value & M)
    if hash_value == -1:
        hash_value = -2
    return hash_value

Tipos de iteradores

Python soporta el concepto de iteradores sobre contenedores. Esto se implementa usando dos métodos diferentes: Estos son usados por las clases definidas por el usuario para soportar iteración. Las secuencias, que se describirán con mayor detalle, siempre soportan la iteración.

Para que un objeto contenedor soporte iteración, debe definir un método:

container.__iter__()

Retorna un objeto iterador. Este objeto es requerido para soportar el protocolo de iteración que se describe a continuación. Si un contenedor soporta diferentes tipos de iteración, se pueden implementar métodos adicionales para estos iteradores (por ejemplo, un tipo de contenedor que puede soportar distintas formas de iteración podría ser una estructura de tipo árbol que proporcione a la vez un recorrido en profundidad o en anchura). Este método se corresponde al slot tp_iter de la estructura usada para los objetos Python en la API Python/C.

Los objetos iteradores en si necesitan definir los siguientes dos métodos, que forma juntos el protocolo iterador:

iterator.__iter__()

Retorna el propio objeto iterador. Este método es necesario para permitir tanto a los contenedores como a los iteradores usar la palabras clave for o in. Este método se corresponde con el slot tp_iter de la estructura usada para los objetos Python en la API Python/C.

iterator.__next__()

Retorna el siguiente elemento del contenedor. Si no hubiera más elementos, lanza la excepción StopIteration. Este método se corresponde con el slot tp_iternext de la estructura usada para los objetos Python en la API Python/C.

Python define varios objetos iteradores que permiten iterar sobre las secuencias, ya sean generales o específicas, diccionarios y otras estructuras de datos especializadas. Los tipos específicos no son tan importantes como la implementación del protocolo iterador.

Una vez que la ejecución del método __next__() lanza la excepción StopIteration, debe continuar haciéndolo en subsiguientes llamadas al método. Si una implementación no cumple esto, se considera rota.

Tipos Generador

Los generator de Python proporcionan una manera cómoda de implementar el protocolo iterador. Si un objeto de tipo contenedor implementa el método __iter__() como un generador, de forma automática este retornará un objeto iterador (Técnicamente, un objeto generador) que implementa los métodos __iter__() y __next__(). Se puede obtener más información acerca de los generadores en la documentación de la expresión yield.

Tipos secuencia — list, tuple, range

Hay tres tipos básicos de secuencia: listas, tuplas y objetos de tipo rango. Existen tipos de secuencia especiales usados para el procesado de datos binarios y cadenas de caracteres que se describirán en secciones específicas.

Operaciones comunes de las secuencias

Las operaciones de la siguiente tabla están soportadas por la mayoría de los tipos secuencia, tanto mutables como inmutables. La clase ABC collections.abc.Sequence se incluye para facilitar la implementación correcta de estas operaciones en nuestros propios tipos de secuencias.

La tabla lista las operaciones ordenadas de menor a mayor prioridad. En la tabla, s y t representan secuencias del mismo tipo, n, i, j y k son números enteros y x es un objeto arbitrario que cumple con cualquier restricción de tipo o valor impuesta por s.

Las operaciones in y not in tienen la misma prioridad que los operadores de comparación. Las operaciones + (Concatenación) y * (Repetición) tienen la misma prioridad que sus equivalentes numéricos 3

Operación

Resultado

Notas

x in s

True si un elemento de s es igual a x, False en caso contrario

(1)

x not in s

False si un elemento de s es igual a x, True en caso contrario

(1)

s + t

la concatenación de s y t

(6)(7)

s * n o n * s

equivale a concatenar s consigo mismo n veces

(2)(7)

s[i]

El elemento i-esimo de s, empezando a contar en 0

(3)

s[i:j]

la rebanada de s desde i hasta j

(3)(4)

s[i:j:k]

la rebanada de s desde i hasta j, con paso j

(3)(5)

len(s)

longitud de s

min(s)

el elemento más pequeño de s

max(s)

el elemento más grande de s

s.index(x[, i[, j]])

índice de la primera ocurrencia de x en s (en la posición i o superior, y antes de j)

(8)

s.count(x)

número total de ocurrencias de x en s

También se pueden comparar secuencias del mismo tipo. En particular, las tuplas y las listas se comparan por orden lexicográfico, comparando los elementos en la misma posición. Esto significa que, para que se consideren iguales, todos los elementos correspondientes deben ser iguales entre si, y las dos secuencias deben ser del mismo tipo y de la misma longitud (Para más detalles, véase Comparaciones en la referencia del lenguaje).

Notas:

Aunque las operaciones in y not in se usan generalmente para comprobar si un elemento está dentro de un contenedor, en algunas secuencias especializadas (Como str, bytes y bytearray) también se pueden usar para comprobar si está incluida una secuencia:

>>> "gg" in "eggs"
True

Valores de n menores que 0 se consideran como 0 (Que produce una secuencia vacía del mismo tipo que s). Nótese que los elementos de la secuencia s no se copian, sino que se referencian múltiples veces. Esto a menudo confunde a programadores noveles de Python; considérese:

>>> lists = [[]] * 3
>>> lists
[[], [], []]
>>> lists[0].append(3)
>>> lists
[[3], [3], [3]]

Lo que ha pasado es que [[]] es una lista de un elemento, siendo este elemento una lista vacía, así que los tres elementos de [[]] * 3 son referencias a la misma lista vacía. Modificar cualquiera de los elementos de lists modifica la lista inicial. Para crear una lista de listas independientes entre si, se puede hacer:

>>> lists = [[] for i in range(3)]
>>> lists[0].append(3)
>>> lists[1].append(5)
>>> lists[2].append(7)
>>> lists
[[3], [5], [7]]

Se puede consultar una explicación más completa en esta entrada de la lista de preguntas más frecuentes ¿Cómo puedo crear una lista multidimensional?.

Si i o j es negativo, el índice es relativo al final de la secuencia s: Se realiza la sustitución len(s) + i o len(s) + j. Nótese que -0 sigue siendo 0.

La rebanada de s desde i a j se define como la secuencia de elementos con índice k, de forma que i <= k < j. Si i o j es mayor que len(s) se usa len(s). Si i se omite o es None, se usa 0. Si j se omite o es None, se usa len(s). Si i es mayor o igual a j, la rebanada estaría vacía.

La rebanada de s, desde i hasta j con paso k, se define como la secuencia de elementos con índice x = i + n*k tal que 0 <= n < (j-i)/k. En otras palabras, los índices son i, i+k, i+2*k, i+3*k y así consecutivamente, hasta que se alcance el valor de j (Pero sin incluir nunca j). Cuando k es positivo, i y j se limitan al valor de len(s), si fueran mayores. Si k es negativo, i y j se reducen de len(s) - 1. Si i o j se omiten o su valor es None, se convierten es valores «finales» (Donde el sentido de final depende del signo de k). Nótese que k no puede valer 0. Si k vale None, se considera como 1.

La concatenación de secuencias inmutables siempre produce un nuevo objeto. Esto significa que construir una secuencia usando la concatenación tiene un coste en ejecución cuadrático respecto al tamaño de la secuencia final. Para obtener un rendimiento lineal, se puede optar por una de las alternativas siguientes:

en vez de concatenar objetos de tipo str, se puede construir una lista y usar finalmente el método str.join(), o bien utilizar una instancia de la clase io.StringIO y recuperar el valor final completo

de forma similar, en vez de concatenar objetos de tipo bytes se puede usar el método bytes.join(), la clase io.BytesIO, o se puede realizar una modificación interna usando un objeto de la clase bytearray. Los objetos de tipo bytearray son mutables y tienen un mecanismo interno de gestión muy eficiente

en vez de concatenar tuplas (Instancias de tuple), usar una lista (list) y expandirla

para otros tipos, investiga la documentación relevante de la clase

Algunos tipos de secuencia (como la clase range) solo soportan elementos que siguen un patrón específico, y por tanto no soportan la concatenación ni la repetición.

El método index lanza la excepción ValueError si x no se encuentra en s. No todas las implementaciones soportan los parámetros opcionales i y j. Estos parámetros permiten una búsqueda eficiente de partes de una secuencia. Usar estos parámetros es más o menos equivalente a usar s[i:j].index(x), pero sin copiar ningún dato y con el valor de índice retornado como valor relativo al inicio de la secuencia, en vez de al inicio de la rebanada.

Tipos de secuencia inmutables

La única operación que las secuencias inmutables implementan generalmente, y que no esta definida también en las secuencias mutables, es el soporte para el cálculo de la función predefinida hash().

Este soporte permite usar secuencias inmutables, como por ejemplo las instancias de la clase tuple, como claves para diccionarios (dict), así como ser almacenadas en conjuntos (set) o conjuntos congelados (frozenset).

Intentar calcular el hash de una secuencia inmutable que contenga objetos mutables producirá una excepción de tipo TypeError.

Tipos de secuencia mutables

Las operaciones de la siguiente tabla están definidas para todas los tipos de secuencia mutables. La clase ABC collections.abc.MutableSequence se incluye para facilitar la implementación correcta de un tipo de secuencia propio.

En la tabla, s es una instancia de una secuencia de tipo mutable, t es cualquier objeto iterable y x es un objeto arbitrario que cumple las restricciones de tipo y valor que vengan impuestas por s (Como ejemplo, la clase bytearray solo acepta enteros que cumplan la condición 0 <= x <= 255).

Operación

Resultado

Notas

s[i] = x

el elemento i de s es reemplazado por x

s[i:j] = t

la rebanada de valores de s que van de i a j es reemplazada por el contenido del iterador t

del s[i:j]

equivalente a s[i:j] = []

s[i:j:k] = t

los elementos de s[i:j:k] son reemplazados por los elementos de t

(1)

del s[i:j:k]

borra los elementos de s[i:j:k] de la lista

s.append(x)

añade x al final de la secuencia (Equivale a s[len(s):len(s)] = [x])

s.clear()

elimina todos los elementos de s (Equivale a del s[:])

(5)

s.copy()

crea una copia superficial de s (Equivale a s[:])

(5)

s.extend(t) o s += t

extiende s con los contenidos de t (En la mayoría de los casos equivale a s[len(s):len(s)] = t)

s *= n

actualiza s con su contenido repetido n veces

(6)

s.insert(i, x)

inserta x en s en la posición indicada por el índice i (Equivale a s[i:i] = [x])

s.pop() or s.pop(i)

retorna el elemento en la posición indicada por i, y a la vez lo elimina de la secuencia s

(2)

s.remove(x)

elimina el primer elemento de s tal que s[i] sea igual a x

(3)

s.reverse()

invierte el orden de los elementos de s, a nivel interno

(4)

Notas:

La secuencia t debe tener la misma longitud que la rebanada a la que reemplaza.

El parámetro opcional i tiene un valor por defecto de -1, así que si no se especifica se retorna el último valor y este se elimina de la secuencia.

El método remove() lanza la excepción ValueError cuando no se encuentra x en s.

El método reverse() modifica la secuencia internamente, por motivos de eficiencia espacial para secuencias muy grandes. Como recordatorio al usuario de que el método produce un efecto secundario, no se retorna la secuencia invertida.

Ambos métodos clear() y copy() se incluyen por consistencia con las interfaces de clases que no soportan operaciones de rebanado (Como las clases dict y set). El método copy() no es parte de la clase ABC collections.abc.MutableSequence, pero la mayoría de las clases finales de tipo secuencia mutable lo incluyen.

Nuevo en la versión 3.3: Los métodos clear() y copy().

El valor de n es un entero, o un objeto que implemente el método __index__(). Los valores negativos, junto con el cero, producen una lista vacía. Los elementos de la secuencia no son copiados, sino que se referencian múltiples veces, tal y como se explicó para s * n en Operaciones comunes de las secuencias.

Listas

Las listas son secuencia mutables, usadas normalmente para almacenar colecciones de elementos homogéneos (Donde el grado de similitud de los mismo depende de la aplicación).

class list([iterable])

Las listas se pueden construir de diferentes formas:

Usando un par de corchetes para definir una lista vacía: []

Usando corchetes, separando los elementos incluidos con comas: [a], [a, b, c]

Usando una lista intensiva o por comprensión: [x for x in iterable]

Usando el constructor de tipo: list() o list(iterable)

La lista se construye con los mismos elementos y en el mismo orden que iterable, donde iterable puede ser una secuencia, un contenedor que soporta iteración, o un objeto iterador. Si iterable es de por si una lista, se construye y retorna una copia, como si se hubiera llamado a iterable[:]. Por ejemplo, list('abc') retorna ['a', 'b', 'c'] y list( (1, 2, 3) ) retorna [1, 2, 3]. Si no se pasan parámetros, se construye una nueva lista vacía, [].

Muchas otras operaciones también producen listas, incluyendo la función básica sorted().

Las listas implementan todas las operaciones comunes y mutables propias de las secuencias. Además, las listas incorporan los siguientes métodos:

sort(*, key=None, reverse=False)

Este método ordena la lista in situ (se modifica internamente), usando unicamente comparaciones de tipo <. Las excepciones no son capturadas internamente: si alguna comparación falla, la operación entera de ordenación falla (Y la lista probablemente haya quedado modificada parcialmente).

El método sort() acepta dos parámetros, que solo pueden pasarse por nombre (keyword-only arguments):

El parámetro key especifica una función de un argumento que se usa para obtener, para cada elemento de la lista, un valor concreto o clave (key) a usar en las operaciones de comparación (Por ejemplo, key=str.lower). El elemento clave para cada elemento se calcula una única vez y se reutiliza para todo el proceso de ordenamiento. El valor por defecto, None, hace que la lista se ordene comparando directamente los elementos, sin obtener valores clave.

La utilidad functools.cmp_to_key() se puede usar para convertir una función cmp del estilo de la versión 2.x a una función key.

El valor de reverse es un valor booleano. Si se define como True, entonces los elementos de la lista se ordenan como si las operaciones de comparación se hubiesen invertido.

Este método modifica la lista in situ, para ahorrar espacio cuando se ordena una secuencia muy grande. Para recordar a los usuarios que funciona de esta manera, no se retorna la secuencia ordenada (Puedes usar sorted() para obtener de forma explicita una nueva secuencia ordenada).

El método sort() es estable. Una algoritmo de ordenación es estable si garantiza que no se cambia el orden relativo que mantienen inicialmente los elementos que se consideran iguales — Esto es útil para realizar ordenaciones en múltiples fases (Por ejemplo, ordenar por departamento y después por salario).

Para ver ejemplos de ordenación y un breve tutorial sobre el tema, véase HOW TO - Ordenar.

CPython implementation detail: Mientras una lista está siendo ordenada, los efectos de intentar modificarla, o incluso examinarla, no están definidos. La implementación en C de Python hace que la lista parezca vacía durante la ordenación, y lanza una excepción del tipo ValueError si detecta un cambio en la lista durante el proceso de ordenación.

Tuplas

Las tuplas son secuencias inmutables, usadas normalmente para almacenar colecciones de datos heterogéneos (Como las duplas o tuplas de dos elementos producidas por la función básica enumerate()). También son usadas en aquellos casos donde se necesite una secuencia inmutable de datos heterogéneos (Como por ejemplo permitir el almacenamiento en un objeto de tipo set o dict).

class tuple([iterable])

Las tuplas se pueden construir de diferentes maneras:

Usando un par de símbolos de paréntesis, para indicar una tupla vacía: ()

Usando una coma al final, para crear una tupla de un único elemento: a, o (a,)

Separando los elementos por comas: a, b, c o (a, b, c)

Usando la función básica tuple() built-in: tuple() o tuple(iterable)

El constructor genera una tupla cuyos elementos son los mismos y están en el mismo orden que los elementos del iterable, donde iterable puede ser una secuencia, un contenedor que soporta iteración, o un objeto de tipo iterator. Si iterable es ya de por si una tupla, se retorna sin cambiar. Por ejemplo, tuple('abc') retorna ('a', 'b', 'c') y tuple( [1, 2, 3] ) retorna (1, 2, 3). Si no se indica ningún parámetro, el constructor creará una nueva tupla vacía. ().

Nótese que es la coma la que realmente construye la tupla, no los paréntesis. Los paréntesis son opcionales, excepto en el caso de la tupla vacía, o cuando se necesitan para evitar una ambigüedad sintáctica. Por ejemplo, f(a, b, c) es una llamada a una función con tres parámetros, pero f((a, b, c)) es una llamada a una función con un único parámetro, en este caso una tupla de tres elementos.

Las tuplas implementan todas las operaciones de secuencia common.

Para colecciones de datos heterogéneos donde el acceso por nombre resulta más claro que por índice, quizá crear una tupla con nombres (collections.namedtuple()) pueden ser más apropiado.

Rangos

Los objetos de tipo range representan una secuencia inmutable de números y se usan habitualmente para ejecutar un bucle for un número determinado de veces.

class range(stop)

class range(start, stop[, step])

The arguments to the range constructor must be integers (either built-in int or any object that implements the __index__() special method). If the step argument is omitted, it defaults to 1. If the start argument is omitted, it defaults to 0. If step is zero, ValueError is raised.

Para un valor positivo de step, el contenido del rango r viene determinado por la fórmula r[i] = start + step*i donde i >= 0 y r[i] < stop.

Para un valor negativo de step, el contenido del rango sigue estando determinado por la fórmula r[i] = start + step*i, pero las restricciones ahora son i >= 0 y r[i] > stop.

Un objeto de tipo rango se considera vacío si r[0] no cumple con las restricciones de valor. Los rangos soportan índices negativos, pero estos son interpretados como índices considerados desde el final de la secuencia determinada por los índices positivos.

Los rangos que contengan valores mayores que sys.maxsize se permiten, pero algunas capacidades (como la función len()) pueden lanzar una excepción de tipo OverflowError.

Ejemplos de rangos:

>>> list(range(10))
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
>>> list(range(1, 11))
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
>>> list(range(0, 30, 5))
[0, 5, 10, 15, 20, 25]
>>> list(range(0, 10, 3))
[0, 3, 6, 9]
>>> list(range(0, -10, -1))
[0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
>>> list(range(0))
[]
>>> list(range(1, 0))
[]

Los rangos implementan todas las operaciones comunes de las secuencias, excepto la concatenación y la repetición (Esto es porque los objetos de tipo rango solamente pueden representar secuencias que siguen un patrón estricto, y tanto la repetición como la concatenación pueden romperlo).

start

El valor del parámetro start (0 si no se utiliza el parámetro)

stop

El valor del parámetro stop

step

El valor del parámetro step (1 si no se utiliza el parámetro)

La ventaja de usar un objeto de tipo range en vez de uno de tipo list o tuple es que con range siempre se usa una cantidad fija (y pequeña) de memoria, independientemente del rango que represente (Ya que solamente necesita almacenar los valores para start, stop y step, y calcula los valores intermedios a medida que los va necesitando).

Los objetos rango implementan la clase ABC collections.abc.Sequence, y proporcionan capacidades como comprobación de inclusión, búsqueda de elementos por índice, operaciones de rebanadas y soporte de índices negativos (Véase Tipos secuencia — list, tuple, range):

>>> r = range(0, 20, 2)
>>> r
range(0, 20, 2)
>>> 11 in r
False
>>> 10 in r
True
>>> r.index(10)
5
>>> r[5]
10
>>> r[:5]
range(0, 10, 2)
>>> r[-1]
18

La comparación entre rangos usando los operadores == y != se realiza como con las secuencias. Esto es, dos rangos se consideran iguales si representan exactamente la misma secuencia de elementos. (Fíjate que, según esta definición, dos rangos pueden considerarse iguales aunque tengan diferentes valores para start, stop y step, por ejemplo range(0) == range(2, 1, 3) y range(0, 3, 2) == range(0, 4, 2)).

Distinto en la versión 3.2: Implementa la clase abstracta Sequence. Soportan operaciones de rebanado e índices negativos. Comprobar si un entero de tipo int está incluido en un rango se realiza en un tiempo constante, no se realiza una iteración a través de todos los elementos.

Distinto en la versión 3.3: Define los operadores “==” y “!=” para comparar rangos en base a la secuencia de valores que definen (En vez de compararse en base a la identidad).

Nuevo en la versión 3.3: Los atributos start, stop y step.

Ver también

En linspace recipe [http://code.activestate.com/recipes/579000/] se muestra como implementar una versión lazy o perezosa de una función para range que funciona con valores en coma flotante.

Cadenas de caracteres — str

La información textual se representa en Python con objetos de tipo str, normalmente llamados cadenas de caracteres o simplemente cadenas. Las cadenas de caracteres son secuencias inmutables de puntos de código Unicode. Las cadenas se pueden definir de diferentes maneras:

Comillas simples: 'permite incluir comillas "dobles"'

Double quotes: "allows embedded 'single' quotes"

Triples comillas: ya sea con comillas simples '''Triples comillas simples''' o dobles """Triples comillas dobles"""

Las cadenas definidas con comillas tripes pueden incluir varias líneas. Todos los espacios en blancos incluidos se incorporan a la cadena de forma literal.

Cadenas literales que forman parte de una expresión y que solo estén separados por espacios en blanco, se convertirán implícitamente a una única cadena. Esto es, ("spam " "eggs") == "spam eggs".

Véase Literales de cadenas y bytes para más información acerca de las diferentes formas de expresar cadenas de forma literal, incluidos los caracteres de escape, y del prefijo r (»raw») que deshabilita el procesamiento de la mayoría de dichas secuencias de escape.

Las cadenas de caracteres también se pueden crear usando el constructor str.

Como no hay un tipo separado para los caracteres, indexar una cadena produce una cadena de longitud 1. Esto es, para una cadena de caracteres no vacía s, s[0] == s[0:1].

Tampoco hay una versión mutable de las cadenas de caracteres, pero el método str.join() o la clase io.StringIO pueden usarse para construir de forma eficiente una cadena de caracteres a partir de fragmentos.

Distinto en la versión 3.3: Para facilitar la compatibilidad hacia atrás con la versión 2, el prefijo u se permite en las cadenas de caracteres. No tiene ningún efecto en la interpretación del literal y no se puede combinar con el prefijo r.

class str(object='')

class str(object=b'', encoding='utf-8', errors='strict')

Retorna una representación en forma de cadena de caracteres de object. Si no se proporciona ningún valor, retorna una cadena vacía. Si se proporciona, el comportamiento de str() depende de los valores pasados en los parámetros encoding y errors, como veremos.

If neither encoding nor errors is given, str(object) returns type(object).__str__(object), which is the «informal» or nicely printable string representation of object. For string objects, this is the string itself. If object does not have a __str__() method, then str() falls back to returning repr(object).

Si se indica alguno de los dos parámetros encoding o errors, entonces object debe ser un objeto binario o similar (bytes-like object, es decir, una instancia de bytes o bytearray). En este caso, si object es de tipo bytes o bytearray, la llamada a str(bytes, encoding, errors) es equivalente a bytes.decode(encoding, errors). Si no, el objeto de tipo bytes que esta subyacente en el objeto buffer se obtiene mediante una llamada a bytes.decode(). Véase Tipos de secuencias binarias — bytes, bytearray y memoryview y Protocolo Búfer para más información sobre los objetos buffer.

Si se pasa un objeto de tipo bytes a la función str() sin especificar o bien el parámetro encoding o bien el errors, se vuelve al caso normal donde se retorna la representación informal (Véase también la -b de las opciones de línea de órdenes de Python). Por ejemplo:

>>> str(b'Zoot!')
"b'Zoot!'"

Para más información sobre la clase str y sus métodos, consulta Cadenas de caracteres — str y la sección Métodos de las cadenas de caracteres a continuación. Para las opciones de formateo de cadenas, lee las secciones Literales de cadena formateados y Sintaxis de formateo de cadena. También puedes consultar la sección Servicios de procesamiento de texto.

Métodos de las cadenas de caracteres

Todas las cadenas de caracteres implementan las operaciones comunes de las secuencias, junto con los métodos descritos a continuación.

Las cadenas soportan dos estilos de formateo, uno proporciona un grado muy completo de flexibilidad y personalización (Véase str.format(), Sintaxis de formateo de cadena y Formato de cadena de caracteres personalizado) mientras que el otro se basa en la función C printf, que soporta un menor número de tipos y es ligeramente más complicada de usar, pero es a menudo más rápida para los casos que puede manejar (Formateo de cadenas al estilo *printf*).

La sección Servicios de procesamiento de texto de la librería estándar cubre una serie de módulos que proporcionan varias utilidades para trabajar con textos (Incluyendo las expresiones regulares en el módulo re).

str.capitalize()

Retorna una copia de la cadena con el primer carácter en mayúsculas y el resto en minúsculas.

Distinto en la versión 3.8: El primer carácter se pasa ahora a título, más que a mayúsculas. Esto significa que caracteres como dígrafos solo tendrán la primera letra en mayúsculas, en ves de todo el carácter.

str.casefold()

Retorna el texto de la cadena, normalizado a minúsculas. Los textos así normalizados pueden usarse para realizar búsquedas textuales independientes de mayúsculas y minúsculas.

El texto normalizado a minúsculas es más agresivo que el texto en minúsculas normal, porque se intenta unificar todas las grafías distintas de la letras. Por ejemplo, En Alemán la letra minúscula 'ß' equivale a "ss". Como ya está en minúsculas, el método lower() no modifica 'ß', pero el método casefold() lo convertirá a "ss".

El algoritmo de normalización a minúsculas se describe en la sección 3.13 del estándar Unicode.

Nuevo en la versión 3.3.

str.center(width[, fillchar])

Retorna el texto de la cadena, centrado en una cadena de longitud width. El relleno a izquierda y derecha se realiza usando el carácter definido por el parámetro fillchar (Por defecto se usa el carácter espacio ASCII). Si la cadena original tiene una longitud len(s) igual o superior a width, se retorna el texto sin modificar.

str.count(sub[, start[, end]])

Retorna el número de ocurrencias no solapadas de la cadena sub en el rango [start, end]. Los parámetros opcionales start y end Se interpretan como en una expresión de rebanada.

str.encode(encoding="utf-8", errors="strict")

Retorna una versión codificada en forma de bytes. La codificación por defecto es 'utf-8'. El parámetro errors permite especificar diferentes esquemas de gestión de errores. El valor por defecto de errors es 'strict', que significa que cualquier error en la codificación lanza una excepción de tipo UnicodeError. Otros valores posibles son 'ignore', 'replace', 'xmlcharrefreplace', 'backslashreplace' y cualquier otro nombre que se haya registrado mediante la función codecs.register_error(), véase la sección Manejadores de errores. Para una lista de los posibles sistemas de codificación, véase la sección Codificaciones estándar.

Por defecto, el argumento errors no se verifica para mejor rendimiento, solo se usa con el primer error de codificación encontrado. Se puede habilitar el Modo de Desarrollo de Python, o utilizar una construcción de depuración para verificar errors.

Distinto en la versión 3.1: Añade soporte para el uso de parámetros por nombre.

Distinto en la versión 3.9: El argumento errors ahora se verifica en modo de desarrollo y en modo de depuración.

str.endswith(suffix[, start[, end]])

Retorna True si la cadena termina con el sufijo especificado con el parámetro prefix, y False en caso contrario. También podemos usar suffix para pasar una tupla de sufijos a buscar. Si especificamos el parámetro opcional start, la comprobación empieza en esa posición. Con el parámetro opcional stop, la comprobación termina en esa posición.

str.expandtabs(tabsize=8)

Retorna una copia de la cadena, con todos los caracteres de tipo tabulador reemplazados por uno o más espacios, dependiendo de la columna actual y del tamaño definido para el tabulador. Las posiciones de tabulación ocurren cada tabsize caracteres (Siendo el valor por defecto de tabsize 8, lo que produce las posiciones de tabulación 0, 8, 16,…). Para expandir la cadena, la columna actual se pone a cero y se va examinando el texto carácter a carácter. Si se encuentra un tabulador, (\t), se insertan uno o más espacios hasta que sea igual a la siguiente posición de tabulación (El carácter tabulador en sí es descartado). Si el carácter en un indicador de salto de línea (\n) o de retorno (\r), se copia y el valor de columna actual se vuelve a poner a cero. Cualquier otro carácter es copiado sin cambios y hace que el contador de columna se incremente en 1, sin tener en cuenta como se representa gráficamente el carácter.

>>> '01\t012\t0123\t01234'.expandtabs()
'01      012     0123    01234'
>>> '01\t012\t0123\t01234'.expandtabs(4)
'01  012 0123    01234'

str.find(sub[, start[, end]])

Retorna el menor índice de la cadena s donde se puede encontrar la cadena sub, considerando solo el intervalo s[start:end]. Los parámetros opcionales start y end se interpretan como si fueran “indices de una rebanada. retorna -1 si no se encuentra la cadena.

Nota

El método find() se debe usar solo si se necesita saber la posición de la cadena sub. Si solo se necesita comprobar si sub es una parte de s, es mejor usar el operador in:

>>> 'Py' in 'Python'
True

str.format(*args, **kwargs)

Realiza una operación de formateo. La cadena de caracteres sobre la que se está ejecutando este método puede contener texto literal y también marcas de reemplazo de texto definidas mediante llaves {}. Cada sección a reemplazar contiene o bien un índice numérico que hace referencia a un parámetro por posición, o el nombre de un parámetro por nombre. retorna una copia de la cadena donde se han sustituido las marcas de reemplazo por los valores correspondientes pasados como parámetros.

>>> "The sum of 1 + 2 is {0}".format(1+2)
'The sum of 1 + 2 is 3'

Véase Sintaxis de formateo de cadena para una descripción de las distintas opciones de formateo que se pueden usar.

Nota

Cuando se formatea un número (int, float, complex, decimal.Decimal y clases derivadas) usando la n (Por ejemplo, '{:n}'.format(1234)), las función ajusta temporalmente el valor de la variable de entorno local LC_TYPE a LC_NUMERIC para decodificar los campos *decimal_point* y *thousands_sep* de la función localeconv(), si usan caracteres que no son ASCII o si ocupan más de un byte, y el valor definido en LC_NUMERIC es diferente del definido en LC_CTYPE. Estos cambios temporales pueden afectar a otros threads.

Distinto en la versión 3.7: Cuando se formatea un número usando la n, la función puede asignar de forma temporal la variable LC_CTYPE.

str.format_map(mapping)

Similar a str.format(**mapping)`, pero se usa ``*mapping* de forma directa y no se copia a una diccionario. Esto es útil si *mapping* es, por ejemplo, una instancia de una subclase de dict:

>>> class Default(dict):
...     def __missing__(self, key):
...         return key
...
>>> '{name} was born in {country}'.format_map(Default(name='Guido'))
'Guido was born in country'

Nuevo en la versión 3.2.

str.index(sub[, start[, end]])

Como find(), pero lanza una excepción de tipo ValueError si no se encuentra la cadena a buscar.

str.isalnum()

Retorna True si todos los caracteres de la cadena son alfanuméricos y hay, al menos, un carácter. En caso contrario, retorna False. Un carácter c se considera alfanumérico si alguna de las siguientes funciones retorna True: c.isalpha(), c.isdecimal(), c.isdigit() o c.isnumeric().

str.isalpha()

Retorna True si todos los caracteres de la cadena son alfabéticos y hay, al menos, un carácter. En caso contrario, retorna False. Los caracteres alfabéticos son aquellos definidos en la base de datos de Unicode como «*Letter*, es decir, aquellos cuya propiedad categoría general es «Lm», «Lt», «Lu», «Ll» o «Lo». Nótese que esta definición de «Alfabético» es diferente de la que usa el estándar Unicode.

str.isascii()

Retorna True si la cadena de caracteres está vacía, o si todos los caracteres de la cadena son ASCII. En caso contrario, retorna False. Los caracteres ASCII son aquellos cuyos puntos de código Unicode están en el rango U+0000-U+007F.

Nuevo en la versión 3.7.

str.isdecimal()

Retorna True si todos los caracteres de la cadena son caracteres decimales y hay, al menos, un carácter. En caso contrario, retorna False. Los caracteres decimales son aquellos que se pueden usar para formar números en base 10, por ejemplo, U+0660, ARABIC-INDIC DIGIT ZERO. Formalmente, un carácter decimal es un carácter en la categoría general «Nd» de Unicode.

str.isdigit()

Retorna True si todos los caracteres de la cadena son dígitos y hay, al menos, un carácter. En caso contrario, retorna False. Los dígitos incluyen los caracteres decimales y dígitos que requieren un tratamiento especial, como por ejemplo los usados para superíndices. Esto incluye dígitos que no pueden ser usados para formar números en base 10, como los números Kharosthi. Formalmente, un dígito es un carácter que tiene la propiedad *Numeric_Type* definida como *Digit* o *Decimal*.

str.isidentifier()

Retorna True si la cadena de caracteres es un identificar válido de acuerdo a la especificación del lenguaje, véase Identificadores y palabras clave.

Se puede usar la función keyword.iskeyword() para comprobar si la cadena s es una palabra reservada, como def o class.

Ejemplo:

>>> from keyword import iskeyword

>>> 'hello'.isidentifier(), iskeyword('hello')
(True, False)
>>> 'def'.isidentifier(), iskeyword('def')
(True, True)

str.islower()

Retorna True si todos los caracteres de la cadena que tengan formas en mayúsculas y minúsculas 4 están en minúsculas y hay, al menos, un carácter de ese tipo. En caso contrario, retorna False.

str.isnumeric()

Retorna True si todos los caracteres de la cadena son caracteres numéricos y hay, al menos, un carácter. En caso contrario, retorna False. Los caracteres numéricos incluyen los dígitos, y todos los caracteres Unicode que tiene definida la propiedad valor numérico, por ejemplo U+2155, VULGAR FRACTION ONE FIFTH. Formalmente, los caracteres numéricos son aquellos que la propiedad Numeric_Type definida como Digit, Decimal o Numeric.

str.isprintable()

Retorna True si todos los caracteres de la cadena son imprimibles o si la cadena está vacía. En caso contrario, retorna False. Los caracteres no imprimibles son aquellos definidos en la base de datos de Unicode como «other» o «Separator», con la excepción del carácter ASCII «espacio» (0x20), que se considera imprimible (Nótese que en este contexto, imprimible son aquellos caracteres que no necesitan ser escapados cuando se imprimen con la función repr(). No tiene relevancia en cadenas escritas a sys.stdout o sys.stderr).

str.isspace()

Retorna True si todos los caracteres de la cadena son espacios en blanco y hay, al menos, un carácter. En caso contrario, retorna False.

Un carácter se considera espacio en blanco si, en la base de datos de Unicode (Véase unicodedata), está clasificado en la categoría general Zs``("Espacio, separador") o la clase bidireccional es ``WS, B, or S.

str.istitle()

Retorna True si las palabras en la cadena tiene forma de título y hay, al menos, un carácter, por ejemplo una mayúscula solo puede aparecer al principio o después de un carácter que no tenga formas alternativas mayúsculas-minúsculas, y las minúsculas solo después de carácter que si tiene formas alternativas mayúsculas-minúsculas. En caso contrario, retorna False.

str.isupper()

Retorna True si todos los caracteres de la cadena que tengan formas en mayúsculas y minúsculas 4 están en mayúsculas y hay, al menos, un carácter de ese tipo. En caso contrario, retorna False.

>>> 'BANANA'.isupper()
True
>>> 'banana'.isupper()
False
>>> 'baNana'.isupper()
False
>>> ' '.isupper()
False

str.join(iterable)

Retorna una cadena de caracteres formada por la concatenación de las cadenas en el iterable. Se lanza una excepción de tipo TypeError si alguno de los elementos en el iterable no es una cadena, incluyendo objetos de tipo bytes. Se usa como separador entre los elementos la cadena de caracteres pasada como parámetro.

str.ljust(width[, fillchar])

Retorna el texto de la cadena, justificado a la izquierda en una cadena de longitud width. El carácter de relleno a usar viene definido por el parámetro fillchar (Por defecto se usa el carácter espacio ASCII). Si la cadena original tiene una longitud len(s) igual o superior a width, se Retorna el texto sin modificar.

str.lower()

Retorna una copia de la cadena de caracteres con todas las letras en minúsculas 4.

El algoritmo usado para la conversión a minúsculas está descrito en la sección 3..13 del estándar Unicode.

str.lstrip([chars])

Retorna una copia de la cadena, eliminado determinados caracteres si se encuentren al principio. El parámetro chars especifica el conjunto de caracteres a eliminar. Si se omite o si se especifica None, se eliminan todos los espacios en blanco. No debe entenderse el valor de chars como un prefijo, sino que se elimina cualquier combinación de sus caracteres:

>>> '   spacious   '.lstrip()
'spacious   '
>>> 'www.example.com'.lstrip('cmowz.')
'example.com'

Véase str.removeprefix() para un método que removerá una única cadena de prefijo en lugar de todas las ocurrencias dentro de un set de caracteres. Por ejemplo:

>>> 'Arthur: three!'.lstrip('Arthur: ')
'ee!'
>>> 'Arthur: three!'.removeprefix('Arthur: ')
'three!'

static str.maketrans(x[, y[, z]])

Este método estático retorna una tabla de traducción apta para ser usada por el método str.translate().

Si solo se usa un parámetro, este debe ser un diccionario que mapea valores de punto Unicode (enteros) o caracteres (Cadenas de longitud 1) a valores Unicode, cadenas (De cualquier longitud) o None. Las claves se convertirán a ordinales.

Si se pasan dos parámetros, deben ser cadenas de la misma longitud, y en la tabla resultante, cada carácter en x se mapea al carácter en la misma posición en y. Si se añade un tercer parámetro, debe ser una cadena de caracteres, todos los cuales se mapearán a None en la tabla resultante.

str.partition(sep)

Divide la cadena en la primera ocurrencia de sep, y retorna una tupla de tres elementos, conteniendo la parte anterior al separador, el separador en sí y la parte posterior al separador. Si no se encuentra el separador, Retorna una tupla de tres elementos, el primero la cadena original y los dos siguientes son cadenas vacías.

str.removeprefix(prefix, /)

Si la cadena de caracteres empieza con la cadena prefix, retorna string[len(prefix):]. De otra manera, retorna una copia de la cadena original:

>>> 'TestHook'.removeprefix('Test')
'Hook'
>>> 'BaseTestCase'.removeprefix('Test')
'BaseTestCase'

Nuevo en la versión 3.9.

str.removesuffix(suffix, /)

Si la cadena de caracteres termina con la cadena suffix, retorna string[:-len(suffix)]. De otra manera, retorna una copia de la cadena original:

>>> 'MiscTests'.removesuffix('Tests')
'Misc'
>>> 'TmpDirMixin'.removesuffix('Tests')
'TmpDirMixin'

Nuevo en la versión 3.9.

str.replace(old, new[, count])

Retorna una copia de la cadena con todas las ocurrencias de la cadena old sustituidas por new. Si se utiliza el parámetro count, solo se cambian las primeras count ocurrencias.

str.rfind(sub[, start[, end]])

Retorna el mayor índice dentro de la cadena s donde se puede encontrar la cadena sub, estando sub incluida en s[start:end]. Los parámetros opcionales start y end se interpretan igual que en las operaciones de rebanado. retorna -1 si no se encuentra sub.

str.rindex(sub[, start[, end]])

Como el método rfind(), pero lanza la excepción ValueError si no se encuentra la cadena sub.

str.rjust(width[, fillchar])

Retorna el texto de la cadena, justificado a la derecha en una cadena de longitud width. El carácter de relleno a usar viene definido por el parámetro fillchar (Por defecto se usa el carácter espacio ASCII). Si width es menor o igual que len(s), se retorna el texto sin modificar.

str.rpartition(sep)

Divide la cadena en la última ocurrencia de sep, y retorna una tupla de tres elementos, conteniendo la parte anterior al separador, el separador en sí y la parte posterior al separador. Si no se encuentra el separador, Retorna una tupla de tres elementos, los dos primeras posiciones con cadenas vacías y en la tercera la cadena original.

str.rsplit(sep=None, maxsplit=-1)

Retorna una lista con las palabras que componen la cadena de caracteres original, usando como separador el valor de sep. Si se utiliza el parámetro maxsplit, se realizan como máximo maxsplit divisiones, retornando los que están más a la derecha. Si no se especifica sep o se pasa con valor None, se usa como separador cualquier carácter de espacio en blanco. Si no contamos la diferencia de empezar las divisiones desde la derecha, el comportamiento de este método rsplit() es equivalente al de split(), que se describe con detalle más adelante.

str.rstrip([chars])

Retorna una copia de la cadena, eliminado determinados caracteres si se encuentren al final. El parámetro chars especifica el conjunto de caracteres a eliminar. Si se omite o si se especifica None, se eliminan todos los espacios en blanco. No debe entenderse el valor de chars como un prefijo, sino que se elimina cualquier combinación de sus caracteres:

>>> '   spacious   '.rstrip()
'   spacious'
>>> 'mississippi'.rstrip('ipz')
'mississ'

Véase str.removesuffix() para un método que removerá una única cadena de sufijo en lugar de de todas las ocurrencias dentro de un set de caracteres. Por ejemplo:

>>> 'Monty Python'.rstrip(' Python')
'M'
>>> 'Monty Python'.removesuffix(' Python')
'Monty'

str.split(sep=None, maxsplit=-1)

Retorna una lista con las palabras que componen la cadena de caracteres original, usando como separador el valor de sep. Si se utiliza el parámetro maxsplit, se realizan como máximo maxsplit divisiones, (Por tanto, la lista resultante tendrá maxsplit+1 elementos). Si no se especifica maxsplit o se pasa con valor -1, entonces no hay límite al número de divisiones a realizar (Se harán todas las que se puedan).

Si se especifica sep, las repeticiones de caracteres delimitadores no se agrupan juntos, sino que se considera que están delimitando cadenas vacías (Por ejemplo, '1,,2'.split(',') retorna ['1', '', '2']). El parámetro sep puede contener más de un carácter (Por ejemplo, '1<>2<>3'.split('<>') retorna ['1', '2', '3']). Dividir una cadena vacía con un separador determinado retornará [''].

Por ejemplo:

>>> '1,2,3'.split(',')
['1', '2', '3']
>>> '1,2,3'.split(',', maxsplit=1)
['1', '2,3']
>>> '1,2,,3,'.split(',')
['1', '2', '', '3', '']

Si no se especifica sep o es None, se usa un algoritmo de división diferente: Secuencias consecutivas de caracteres de espacio en blanco se consideran como un único separador, y el resultado no contendrá cadenas vacías ni al principio ni al final de la lista, aunque la cadena original tuviera espacios en blanco al principio o al final. En consecuencia, dividir una cadena vacía o una cadena que solo contenga espacios en blanco usando None como separador siempre retornará una lista vacía [].

Por ejemplo:

>>> '1 2 3'.split()
['1', '2', '3']
>>> '1 2 3'.split(maxsplit=1)
['1', '2 3']
>>> '   1   2   3   '.split()
['1', '2', '3']

str.splitlines(keepends=False)

Retorna una lista con las líneas en la cadena, dividiendo por los saltos de línea. Los caracteres de salto de línea en sí no se incluyen a no ser que se especifique lo contrario pasando el valor True en al parámetro keepends.

Este método considera como saltos de línea los siguientes caracteres. En concreto, estos son un superconjunto de los saltos de líneas universales.

Representación

Descripción

\n

Salto de línea

\r

Retorno de carro

\r\n

Retorno de carro + salto de línea

\v o \x0b

Tabulación de línea

\f o \x0c

Avance de página

\x1c

Separador de archivo

\x1d

Separador de grupo

\x1e

Separador de registro

\x85

Siguiente línea (Código de control C1)

\u2028

Separador de línea

\u2029

Separador de párrafo

Distinto en la versión 3.2: Se añaden \v y \f a la lista de separadores.

Por ejemplo:

>>> 'ab c\n\nde fg\rkl\r\n'.splitlines()
['ab c', '', 'de fg', 'kl']
>>> 'ab c\n\nde fg\rkl\r\n'.splitlines(keepends=True)
['ab c\n', '\n', 'de fg\r', 'kl\r\n']

Al contrario que con split(), cuando se especifica una cadena con sep, el método retorna una lista vacía para la cadena vacía, y un salto de línea al final del texto no produce una línea extra:

>>> "".splitlines()
[]
>>> "One line\n".splitlines()
['One line']

Por comparación, split('\n') entrega:

>>> ''.split('\n')
['']
>>> 'Two lines\n'.split('\n')
['Two lines', '']

str.startswith(prefix[, start[, end]])

Retorna True si la cadena empieza por prefix, en caso contrario Retorna False. El valor de prefix puede ser también una tupla de prefijos por los que buscar. Con el parámetro opcional start, la comprobación empieza en esa posición de la cadena.

str.strip([chars])

Retorna una copia de la cadena con los caracteres indicados eliminados, tanto si están al principio como al final de la cadena. El parámetro opcional chars es una cadena que especifica el conjunto de caracteres a eliminar. Si se omite o se usa None, se eliminan los caracteres de espacio en blanco. No debe entenderse el valor de chars como un prefijo, sino que se elimina cualquier combinación de sus caracteres:

>>> '   spacious   '.strip()
'spacious'
>>> 'www.example.com'.strip('cmowz.')
'example'

Los caracteres indicados por chars se eliminan de los extremos al principio y al final de la cadena. Se elimina los caracteres del inicio hasta que se encuentra un carácter que no esté incluido en el conjunto definido por chars. Se procede de manera similar para los caracteres al final. Por ejemplo:

>>> comment_string = '#....... Section 3.2.1 Issue #32 .......'
>>> comment_string.strip('.#! ')
'Section 3.2.1 Issue #32'

str.swapcase()

Retorna una copia de la cadena con los caracteres en mayúsculas convertidos a minúsculas, y viceversa. Nótese que no es necesariamente cierto que s.swapcase().swapcase() == s.

str.title()

Retorna una versión en forma de título de la cadena, con la primera letra de cada palabra en mayúsculas y el resto en minúsculas.

Por ejemplo:

>>> 'Hello world'.title()
'Hello World'

El algoritmo usa una definición sencilla e independiente del lenguaje, consistente en considerar una palabra como un grupo de letras consecutivas. Esta definición funciona en varios entornos, pero implica que, por ejemplo en inglés, los apóstrofos en las contracciones y en los posesivos constituyen una separación entre palabras, que puede que no sea el efecto deseado:

>>> "they're bill's friends from the UK".title()
"They'Re Bill'S Friends From The Uk"

The string.capwords() function does not have this problem, as it splits words on spaces only.

Alternatively, a workaround for apostrophes can be constructed using regular expressions:

>>> import re
>>> def titlecase(s):
...     return re.sub(r"[A-Za-z]+('[A-Za-z]+)?",
...                   lambda mo: mo.group(0).capitalize(),
...                   s)
...
>>> titlecase("they're bill's friends.")
"They're Bill's Friends."

str.translate(table)

Retorna una copia de la cadena en la que cada carácter ha sido sustituido por su equivalente definido en la tabla de traducción dada. La tabla puede ser cualquier objeto que soporta el acceso mediante índices implementado en método __getitem__(), normalmente un objeto de tipo mapa o secuencia. Cuando se accede como índice con un código Unicode (Un entero), el objeto tabla puede hacer una de las siguientes cosas: retornar otro código Unicode o retornar una cadena de caracteres, de forma que se usaran uno u otro como reemplazo en la cadena de salida; retornar None para eliminar el carácter en la cadena de salida, o lanzar una excepción de tipo LookupError, que hará que el carácter se copie igual en la cadena de salida.

Se puede usar str.maketrans() para crear un mapa de traducción carácter a carácter de diferentes formas.

Véase también el módulo codecs para una aproximación más flexible al mapeo de caracteres.

str.upper()

Retorna una copia de la cadena, con todos los caracteres con formas mayúsculas/minúsculas 4 pasados a minúsculas. Nótese que s.upper().isupper() puede retornar falso si s contiene caracteres que no tengan las dos formas, o si la categoría Unicode del carácter o caracteres resultantes no es «Lu» (Letra, mayúsculas), sino, por ejemplo, «Lt» (Letra, Título).

El algoritmo de paso a mayúsculas es el descrito en la sección 3.13 del estándar Unicode.

str.zfill(width)

Retorna una copia de la cadena, rellena por la izquierda con los carácter ASCII '0' necesarios para conseguir una cadena de longitud width. El carácter prefijo de signo ('+'/'-') se gestiona insertando el relleno después del carácter de signo en vez de antes. Si width es menor o igual que len(s), se retorna la cadena original.

Por ejemplo:

>>> "42".zfill(5)
'00042'
>>> "-42".zfill(5)
'-0042'

Formateo de cadenas al estilo *printf*

Nota

Las operaciones de formateo explicadas aquí tienen una serie de peculiaridades que conducen a ciertos errores comunes (Como fallar al representar tuplas y diccionarios correctamente). Se pueden evitar estos errores usando las nuevas cadenas de caracteres con formato, el método str.format(), o plantillas de cadenas de caracteres. Cada una de estas alternativas proporcionan sus propios compromisos entre facilidad de uso, flexibilidad y capacidad de extensión.

Las cadenas de caracteres tienen una operación básica: El operador % (módulo). Esta operación se conoce también como formateo de cadenas y operador de interpolación. Dada la expresión formato % valores (Donde formato es una cadena), las especificaciones de conversión indicadas en la cadena con el símbolo % son reemplazadas por cero o más elementos de valores. El efecto es similar a usar la función del lenguaje C sprintf().

Si formato tiene un único marcador, valores puede ser un objeto sencillo, no una tupla. 5 En caso contrario, valores debe ser una tupla con exactamente el mismo número de elementos que marcadores usados en la cadena de formato, o un único objeto de tipo mapa (Por ejemplo, un diccionario).

Un especificador de conversión consiste en dos o más caracteres y tiene los siguientes componentes, que deben aparecer en el siguiente orden:

El carácter '%', que identifica el inicio del marcador.

Una clave de mapeo (opcional), consistente en una secuencia de caracteres entre paréntesis, como por ejemplo, (somename).

Indicador de conversión (opcional), que afecta el resultado de ciertas conversiones de tipos.

Valor de ancho mínimo (opcional). Si se especifica un '*' (asterisco), el ancho real se lee del siguiente elemento de la tupla valores, y el objeto a convertir viene después del ancho mínimo, con un indicador de precisión opcional.

Precisión (Opcional), en la forma '.' (punto) seguido de la precisión. Si se especifica un '*' (Asterisco), el valor de precisión real se lee del siguiente elemento de la tupla valores, y el valor a convertir viene después de la precisión.

Modificador de longitud (Opcional).

Tipo de conversión.

Cuando el operador derecho es un diccionario (o cualquier otro objeto de tipo mapa), los marcadores en la cadena deben incluir un valor de clave entre paréntesis, inmediatamente después del carácter '%'. El valor de la clave se usa para seleccionar el valor a formatear desde el mapa. Por ejemplo:

>>> print('%(language)s has %(number)03d quote types.' %
...       {'language': "Python", "number": 2})
Python has 002 quote types.

En este caso, no se pueden usar el especificador * en la cadena de formato (Dado que requiere una lista secuencial de parámetros).

Los indicadores de conversión son:

Flag

Significado

'#'

El valor a convertir usara la «forma alternativa» (Que se definirá más adelante)

'0'

La conversión rellena con ceros por la izquierda para valores numéricos.

'-'

El valor convertido se ajusta a la izquierda (Sobreescribe la conversión '0' si se especifican los dos)

' '

(Un espacio) Se deba añadir un espacio en blanco antes de un número positivo (O una cadena vacía) si se usa una conversión con signo.

'+'

Un carácter signo ('+' o '-') precede a la conversión (Sobreescribe el indicador de «espacio»)

Puede estar presente un modificador de longitud (h, l o L), pero se ignora y no es necesario para Python – por lo que, por ejemplo, la salida de %ld es idéntica a %d.

Los tipos de conversión son:

Conversión

Significado

Notas

'd'

Entero decimal con signo.

'i'

Entero decimal con signo.

'o'

Valor octal con signo.

(1)

'u'

Obsoleto – es idéntico a 'd'.

(6)

'x'

Hexadecimal con signo (En minúsculas)

(2)

'X'

Hexadecimal con signo (En mayúsculas)

(2)

'e'

Formato en coma flotante exponencial (En minúsculas).

(3)

'E'

Formato en coma flotante exponencial (En mayúsculas).

(3)

'f'

Formato en coma flotante decimal.

(3)

'F'

Formato en coma flotante decimal.

(3)

'g'

Formato en coma flotante. Usa formato exponencial con minúsculas si el exponente es menor que -4 o no es menor que la precisión, en caso contrario usa el formato decimal.

(4)

'G'

Formato en coma flotante. Usa formato exponencial con mayúsculas si el exponente es menor que -4 o no es menor que la precisión, en caso contrario usa el formato decimal.

(4)

'c'

Un único carácter (Acepta números enteros o cadenas de caracteres de longitud 1)

'r'

Cadena de texto (Representará cualquier objeto usando la función repr()).

(5)

's'

Cadena de texto (Representará cualquier objeto usando la función str()).

(5)

'a'

Cadena de texto (Representará cualquier objeto usando la función ascii()).

(5)

'%'

No se representa ningún argumento, obteniéndose en el resultado la cadena '%'.

Notas:

La forma alternativa hace que se inserte antes del primer dígito un prefijo indicativo del formato octal ('0o')

La forma alternativa hace que se inserte antes del primer dígito uno de los dos prefijos indicativos del formato hexadecimal '0x' or '0X' (Que se use uno u otro depende de que indicador de formato se haya usado, 'x' or 'X').

La forma alternativa hace que se incluya siempre el símbolo del punto o coma decimal, incluso si no hubiera dígitos después.

La precisión determina el número de dígitos que vienen después del punto decimal, y por defecto es 6.

La forma alternativa hace que se incluya siempre el símbolo del punto o coma decimal, y los ceros a su derecha no se eliminan, como seria el caso en la forma normal.

La precisión determina el número de dígitos significativos que vienen antes y después del punto decimal, y por defecto es 6.

Si la precisión es N, la salida se trunca a N caracteres.

Véase PEP 237 [https://www.python.org/dev/peps/pep-0237].

Como en Python las cadenas de caracteres tiene una longitud explícita, la conversión de %s no requiere que la cadena termine con '\0'.

Distinto en la versión 3.1: Las conversiones %f para números con valores absolutos mayores que 1e50 ya no son reemplazadas por conversiones %g.

Tipos de secuencias binarias — bytes, bytearray y memoryview

Los tipos básicos para trabajar con datos binarios son las clases bytes y bytearray. Ambas pueden ser usadas por la clase memoryview, que usa el protocolo buffer para acceder a la memoria de otros objetos binarios sin necesidad de hacer una copia.

El módulo array soporta un almacenamiento eficiente de tipos de datos básicos como enteros de 32 bits o números en formato de doble precisión en coma flotante IEEE754.

Objetos de tipo Bytes

Los objetos bytes son secuencias inmutables de bytes. Como muchos de los protocolos binarios más usados se basan en la codificación ASCII para texto, los objetos bytes ofrecen varios métodos que solo son válidos cuando se trabaja con datos compatibles ASCII y son, en varios aspectos, muy cercanos a los cadenas de texto.

class bytes([source[, encoding[, errors]]])

Para empezar, la sintaxis de los valores literales de bytes son prácticamente iguales que para las cadenas de texto, con la diferencia de que se añade el carácter b como prefijo:

Comillas sencillas: b'Se siguen aceptando comillas "dobles" embebidas'

Double quotes: b"still allows embedded 'single' quotes"

Comillas triples: b'''3 comillas simples''', b"""3 comillas dobles"""

Solo se admiten caracteres ASCII en representaciones literales de bytes (Con independencia del tipo de codificación declarado). Cualquier valor por encima de 127 debe ser definido usando su secuencia de escape.

Al igual que con las cadenas, los literales de bytes pueden usar el prefijo r para deshabilitar el procesado de las secuencias de escape. Véase Literales de cadenas y bytes para más información acerca de los diferentes formas de expresar bytes de forma literal, incluyendo el soporte de secuencias de escape.

Aunque las secuencias de bytes y sus representaciones se basen en texto ASCII, los objetos bytes se comportan más como secuencias inmutables de números enteros, donde cada elemento de la secuencia está restringido a los valores de x tal que 0 <= x < 256 (Si se intenta violar esta restricción se elevará una excepción de tipo ValueError). Esto se ha hecho de forma intencionada para enfatizar que, aunque muchos formatos binarios incluyen elementos basados en caracteres ASCII y pueden ser manipulados mediante algunas técnicas de procesado de textos, este no es el caso general para los datos binarios (Aplicar algoritmos pensados para proceso de textos a datos binarios que no se compatibles con ASCII normalmente corromperán dichos datos.

Además de con literales, se pueden crear objetos de tipo byte de las siguientes maneras:

Un secuencia de una longitud especificada rellena con ceros: bytes(10)

A partir de un iterable de números enteros: bytes(range(20))

Copiando datos binarios ya existentes mediante el protocolo buffer: bytes(obj)

Véase además la función básica bytes.

Como dos dígitos hexadecimales se corresponden exactamente con un byte, suelen usase números hexadecimales para describir datos binarios. Por ello, los objetos de tipo byte disponen de un método adicional para leer datos en ese formato:

classmethod fromhex(string)

Este método de clase de bytes retorna un objeto binario, decodificado a partir de la cadena suministrada como parámetro. La cadena de texto debe consistir en dos dígitos hexadecimales por cada byte, ignorándose los caracteres ASCII de espacio en blanco, si los hubiera.

>>> bytes.fromhex('2Ef0 F1f2  ')
b'.\xf0\xf1\xf2'

Distinto en la versión 3.7: El método bytes.fromhex() ignora ahora todos los caracteres ASCII de espacio en blanco, no solo el carácter espacio.

Existe una función que realiza la operación inversa, es decir, transforma un objeto binario en una representación textual usando hexadecimal.

hex([sep[, bytes_per_sep]])

Retorna una cadena de texto que contiene dos dígitos hexadecimales por cada byte de la instancia.

>>> b'\xf0\xf1\xf2'.hex()
'f0f1f2'

Si quieres que la cadena en hexadecimal sea más fácil de leer, se puede especificar un único carácter separador con el parámetro sep para que se añada a la salida. Un segundo parámetro opcional, bytes_per_sep, controla los espacios. Valores positivos calculan la posición del separador desde la derecha, los negativos lo hacen desde la izquierda.

>>> value = b'\xf0\xf1\xf2'
>>> value.hex('-')
'f0-f1-f2'
>>> value.hex('_', 2)
'f0_f1f2'
>>> b'UUDDLRLRAB'.hex(' ', -4)
'55554444 4c524c52 4142'

Nuevo en la versión 3.5.

Distinto en la versión 3.8: El método bytes.hex() ahora soporta los parámetros opcionales sep y bytes_per_sep, que permiten insertar separadores entre los bytes de la cadena de salida.

Como los objetos de tipo bytes son secuencias de números enteros (Similares a tuplas), para un objeto binario b, b[0] retorna un entero, mientras que b[0:1] retorna un objeto de tipo bytes de longitud 1 (Mientras que las cadenas de texto siempre retornan una cadena de longitud 1, ya sea accediendo por índice o mediante una operación de rebanada).

La representación de los objetos tipo bytes usa el formato literal (b'...') ya que es, por lo general, más útil que, digamos, bytes([46, 46, 46]). Siempre se puede convertir un objeto binario en una lista de enteros usando list(b).

Objetos de tipo Bytearray

Los objetos de tipo bytearray son versiones mutables de los objetos de tipo bytes.

class bytearray([source[, encoding[, errors]]])

No existe una sintaxis específica para crear objetos de tipo bytearray, hay que crearlos siempre llamando a su constructor:

Creando una secuencia vacía: bytearray()

Creando una instancia de una longitud determinada, rellena con ceros: bytearray(10)

A partir de un iterable de números enteros: bytearray(range(20))

Copiando datos binarios ya existentes mediante el protocolo buffer: bytearray(b'Hi!')

Como los objetos bytearray son mutables, soportan todas las operaciones aplicables a tipos mutables, además de las operaciones propias de los bytearrays descritas en Operaciones de bytes y bytearray.

Véase también la función básica bytearray.

Como dos dígitos hexadecimales se corresponden exactamente con un byte, suelen usase números hexadecimales para describir datos binarios. Por ello, los objetos de tipo bytearray disponen de un método de clase adicional para leer datos en ese formato:

classmethod fromhex(string)

Este método de clase de bytes retorna un objeto bytearray, decodificado a partir de la cadena suministrada como parámetro. La cadena de texto debe consistir en dos dígitos hexadecimales por cada byte, ignorándose los caracteres ASCII de espacio en blanco, si los hubiera.

>>> bytearray.fromhex('2Ef0 F1f2  ')
bytearray(b'.\xf0\xf1\xf2')

Distinto en la versión 3.7: El método bytearray.fromhex() ignora ahora todos los caracteres ASCII de espacio en blanco, no solo el carácter espacio.

Existe una función que realiza la operación inversa, es decir, transforma un objeto bytearray en una representación textual usando hexadecimal.

hex([sep[, bytes_per_sep]])

Retorna una cadena de texto que contiene dos dígitos hexadecimales por cada byte de la instancia.

>>> bytearray(b'\xf0\xf1\xf2').hex()
'f0f1f2'

Nuevo en la versión 3.5.

Distinto en la versión 3.8: De forma similar a bytes.hex(), bytearray.hex() soporta ahora los parámetros opcionales sep y bytes_per_sep para insertar separadores entre los bytes en la cadena hexadecimal de salida.

Como los objetos de tipo bytearray son secuencias de números enteros (Similares a listas), para un objeto bytearray b, b[0] retorna un entero, mientras que b[0:1] retorna un objeto de tipo bytearray de longitud 1 (Mientras que las cadenas de texto siempre retornan una cadena de longitud 1, ya sea accediendo por índice o mediante una operación de rebanada).

La representación de los objetos tipo bytearray usa el formato literal (bytearray(b'...')) ya que es, por lo general, más útil que, digamos, bytearray([46, 46, 46]). Siempre se puede convertir un objeto bytearray en una lista de enteros usando list(b).

Operaciones de bytes y bytearray

Ambos tipos, bytes y bytearray soportan las operaciones comunes de las secuencias. Los operadores no funcionan solo con operandos del mismo tipo, sino con cualquier objeto tipo binario. Gracias a esta flexibilidad, estos tipos pueden combinarse libremente en expresiones sin que se produzcan errores. Sin embargo, el tipo del valor resultante puede depender del orden de los operandos.

Nota

Los métodos de objetos de tipo bytes y bytesarray no aceptan cadenas de caracteres como parámetros, de la misma manera que los métodos de las cadenas tampoco aceptan bytes como parámetros. Por ejemplo, debes escribir:

a = "abc"
b = a.replace("a", "f")

y:

a = b"abc"
b = a.replace(b"a", b"f")

Algunas operaciones de bytes y bytearrays asumen el uso de formatos binarios compatibles ASCII, y por tanto deben ser evitadas cuando trabajamos con datos binarios arbitrarios. Estas restricciones se explican a continuación.

Nota

Usar estas operaciones basadas en ASCII para manipular datos binarios que no se almacenan en un formato basado en ASCII pueden producir corrupción de datos.

Los siguientes métodos de bytes y bytearrays pueden ser usados con datos en formatos binarios arbitrarios.

bytes.count(sub[, start[, end]])

bytearray.count(sub[, start[, end]])

Retorna el número de secuencias no solapadas de la subsecuencia sub en el rango [start, end]. Los parámetros opcionales start y end se interpretan como en las operaciones de rebanado.

La subsecuencia a buscar puede ser cualquier objeto tipo binario o un número entero entre 0 y 255.

Distinto en la versión 3.3: También acepta como subsecuencia un número entero entre 0 y 255.

bytes.removeprefix(prefix, /)

bytearray.removeprefix(prefix, /)

Si los datos binarios comienzan con la cadena prefix, retorna bytes[len(prefix):]. De otra manera, retorna una copia de los datos binarios originales:

>>> b'TestHook'.removeprefix(b'Test')
b'Hook'
>>> b'BaseTestCase'.removeprefix(b'Test')
b'BaseTestCase'

El argumento prefix puede ser cualquier objeto tipo binario.

Nota

La versión bytearray de este método no modifica los valores internamente (no opera in place): siempre produce un nuevo objeto, aun si no se hubiera realizado ningún cambio.

Nuevo en la versión 3.9.

bytes.removesuffix(suffix, /)

bytearray.removesuffix(suffix, /)

Si los datos binarios terminan con la cadena expresada en suffix y el argumento suffix no está vacío, retorna bytes[:-len(suffix)]. De otra manera, retorna una copia de los datos binarios originales:

>>> b'MiscTests'.removesuffix(b'Tests')
b'Misc'
>>> b'TmpDirMixin'.removesuffix(b'Tests')
b'TmpDirMixin'

El argumento suffix puede ser cualquier objeto tipo binario.

Nota

La versión bytearray de este método no modifica los valores internamente (no opera in place): siempre produce un nuevo objeto, aun si no se hubiera realizado ningún cambio.

Nuevo en la versión 3.9.

bytes.decode(encoding="utf-8", errors="strict")

bytearray.decode(encoding="utf-8", errors="strict")

Retorna una cadena de caracteres decodificada a partir de la secuencia de bytes. La codificación por defecto es 'utf-8'. El parámetro errors puede definir diferentes estrategias de gestión de errores. El valor por defecto de errors es 'strict', que hace que cualquier error de la decodificación lanza una excepción de tipo UnicodeError. Otros valores posibles son``”ignore”, ``'replace' y cualquier otro nombre definido mediante la función codecs.register_error(), véase la sección Manejadores de errores. Para un listado de todos los valores de codificación posibles, véase Codificaciones estándar.

Por defecto, el argumento errors no se verifica para mejor rendimiento, solo se usa con el primer error de codificación encontrado. Se puede habilitar el Modo de Desarrollo de Python, o utilizar una construcción de depuración para verificar errors.

Nota

Pasando el parámetro encoding a la clase str permite decodificar cualquier objeto tipo binario directamente, sin necesidad de crear una objeto temporal de tipo bytes o bytearray.

Distinto en la versión 3.1: Añadido soporte para poder usar parámetros por nombre.

Distinto en la versión 3.9: El argumento errors ahora se verifica en modo de desarrollo y en modo de depuración.

bytes.endswith(suffix[, start[, end]])

bytearray.endswith(suffix[, start[, end]])

Retorna True si los datos binarios acaban con el valor indicado por suffix, en caso contrario retorna False. El valor de suffix puede ser también una tupla de sufijos para buscar. Con el parámetro opcional start, la comparación empieza a partir de esa posición. Si se especifica el parámetro opcional end, la comparación termina en esa posición.

El sufijo (o sufijos) a buscar puede ser cualquier objeto tipo binario.

bytes.find(sub[, start[, end]])

bytearray.find(sub[, start[, end]])

Retorna el mínimo índice dentro de los datos donde se ha encontrado la subsecuencia sub, de forma que sub está contenida en la rebanada s[start:end]. Los parámetros opcionales start y end se interpretan como en las operaciones de rebanadas. retorna -1 si no se puede encontrar sub.

La subsecuencia a buscar puede ser cualquier objeto tipo binario o un número entero entre 0 y 255.

Nota

El método find() se debe usar solo si se necesita saber la posición de sub. Si solo se necesita comprobar si sub es una parte de s, es mejor usar el operador in:

>>> b'Py' in b'Python'
True

Distinto en la versión 3.3: También acepta como subsecuencia un número entero entre 0 y 255.

bytes.index(sub[, start[, end]])

bytearray.index(sub[, start[, end]])

Como find(), pero lanza una excepción de tipo ValueError si no se encuentra la subsecuencia a buscar.

La subsecuencia a buscar puede ser cualquier objeto tipo binario o un número entero entre 0 y 255.

Distinto en la versión 3.3: También acepta como subsecuencia un número entero entre 0 y 255.

bytes.join(iterable)

bytearray.join(iterable)

Retorna un objeto de tipo bytes o bytearray que es la concatenación de las secuencias binarias en iterable. Si alguno de los objetos de la secuencia no es un objeto tipo binario se lanza la excepción TypeError, incluso si son cadenas de caracteres (objetos str). El separador entre los distintos elementos es el contenido del objeto bytes o bytearray usando para invocar el método.

static bytes.maketrans(from, to)

static bytearray.maketrans(from, to)

Este método estático retorna una tabla de traducción apta para ser usada por el método bytes.translate(), que mapea cada carácter en from en la misma posición en to; tanto from como to debe ser objetos tipo binario y deben tener la misma longitud.

Nuevo en la versión 3.1.

bytes.partition(sep)

bytearray.partition(sep)

Retorna la secuencia en la primera ocurrencia de sep, y retorna una tupla de tres elementos que contiene la parte antes del separador, el separador en sí o una copia de tipo bytearray y la parte después del separador. Si no se encuentra el separador, retorna una tupla de tres elementos, con la primera posición ocupada por la secuencia original, y las dos posiciones siguientes rellenas con objetos bytes o bytearray vacíos.

El separador a buscar puede ser cualquier objeto tipo binario.

bytes.replace(old, new[, count])

bytearray.replace(old, new[, count])

Retorna una copia de la secuencia con todas las ocurrencias de old sustituidas por new. Si se utiliza el parámetro count, solo se cambian las primeras count ocurrencias.

La subsecuencia a buscar y su reemplazo puede ser cualquier objeto tipo binario.

Nota

La versión bytearray de este método no modifica los valores internamente (no opera in place): siempre produce un nuevo objeto, aun si no se hubiera realizado ningún cambio.

bytes.rfind(sub[, start[, end]])

bytearray.rfind(sub[, start[, end]])

Retorna el mayor índice dentro de la secuencia s donde se puede encontrar sub, estando sub incluida en s[start:end]. Los parámetros opcionales start y end se interpretan igual que en las operaciones de rebanado. Retorna -1 si no se encuentra sub.

La subsecuencia a buscar puede ser cualquier objeto tipo binario o un número entero entre 0 y 255.

Distinto en la versión 3.3: También acepta como subsecuencia un número entero entre 0 y 255.

bytes.rindex(sub[, start[, end]])

bytearray.rindex(sub[, start[, end]])

Como el método rfind(), pero lanza la excepción ValueError si no se encuentra sub.

La subsecuencia a buscar puede ser cualquier objeto tipo binario o un número entero entre 0 y 255.

Distinto en la versión 3.3: También acepta como subsecuencia un número entero entre 0 y 255.

bytes.rpartition(sep)

bytearray.rpartition(sep)

Divide la secuencia en la primera ocurrencia de sep, y retorna una tupla de tres elementos que contiene la parte antes del separador, el separador en sí o una copia de tipo bytearray y la parte después del separador. Si no se encuentra el separador, retorna una tupla de tres elementos, con las dos primeras posiciones rellenas con objetos bytes o bytearray vacíos, y la tercera posición ocupada por la secuencia original.

El separador a buscar puede ser cualquier objeto tipo binario.

bytes.startswith(prefix[, start[, end]])

bytearray.startswith(prefix[, start[, end]])

Retorna True si los datos binarios empiezan con el valor indicado por prefix, en caso contrario retorna False. El valor de prefix puede ser también una tupla de prefijos para buscar. Con el parámetro opcional start, la comparación empieza a partir de esa posición. Si se especifica el parámetro opcional end, la comparación termina en esa posición.

El prefijo (o prefijos) a buscar puede ser cualquier objeto tipo binario.

bytes.translate(table, /, delete=b'')

bytearray.translate(table, /, delete=b'')

Retorna una copia del objeto bytes o bytearray donde todas las ocurrencias de bytes especificados en el parámetro delete han sido borrados, y el resto han sido mapeados a través de la tabla de traducción indicada, que debe ser un objeto de tipo bytes con una longitud de 256 elementos.

Puedes usar el método bytes.maketrans() para crear la tabla de traducción.

Se puede ajustar el parámetro table a None para conseguir una traducción que solo borra caracteres:

>>> b'read this short text'.translate(None, b'aeiou')
b'rd ths shrt txt'

Distinto en la versión 3.6: El parámetro delete se puede ahora especificar por nombre.

Los siguientes métodos de los objetos bytes y bytearray presentan un comportamiento por defecto que asume el uso de formatos binarios compatibles con ASCII, pero aun así pueden ser usados con datos binarios arbitrarios usando los parámetros apropiados. Nótese que todos los métodos de bytearray en esta sección nunca modifican los datos internamente, sino que siempre retornan objetos nuevos.

bytes.center(width[, fillbyte])

bytearray.center(width[, fillbyte])

Retorna una copia del objeto centrado en una secuencia de longitud width. El relleno se realiza usando el valor definido en el parámetro fillbyte (Por defecto, el carácter espacio en ASCII). Para los objetos de tipo bytes, se retorna la secuencia original intacta si width es menor o igual que len(s).

Nota

La versión bytearray de este método no modifica los valores internamente (no opera in place): siempre produce un nuevo objeto, aun si no se hubiera realizado ningún cambio.

bytes.ljust(width[, fillbyte])

bytearray.ljust(width[, fillbyte])

Retorna una copia del objeto justificado por la izquierda en una secuencia de longitud width. El relleno se realiza usando el valor definido en el parámetro fillbyte (Por defecto, el carácter espacio en ASCII). Para los objetos de tipo bytes, se retorna la secuencia original intacta si width es menor o igual que len(s).

Nota

La versión bytearray de este método no modifica los valores internamente (no opera in place): siempre produce un nuevo objeto, aun si no se hubiera realizado ningún cambio.

bytes.lstrip([chars])

bytearray.lstrip([chars])

Retorna una copia de la secuencia con los caracteres iniciales especificados eliminados. El parámetro chars es una secuencia binaria que especifica el conjunto bytes a ser eliminados; el nombre hace referencia a que este método se usa normalmente con secuencias de caracteres ASCII. Si no se indica o si se especifica None, el comportamiento por defecto será eliminar los caracteres de espacio ASCII. No debe entenderse el valor de chars como un prefijo, sino que se elimina cualquier combinación de sus caracteres:

>>> b'   spacious   '.lstrip()
b'spacious   '
>>> b'www.example.com'.lstrip(b'cmowz.')
b'example.com'

La secuencia binaria que especifica el conjunto bytes a ser eliminados puede ser cualquier objeto de tipo binario. Véase removeprefix() para un método que removerá una única cadena de prefijo en lugar de de todas las ocurrencias dentro de un set de caracteres. Por ejemplo:

>>> b'Arthur: three!'.lstrip(b'Arthur: ')
b'ee!'
>>> b'Arthur: three!'.removeprefix(b'Arthur: ')
b'three!'

Nota

La versión bytearray de este método no modifica los valores internamente (no opera in place): siempre produce un nuevo objeto, aun si no se hubiera realizado ningún cambio.

bytes.rjust(width[, fillbyte])

bytearray.rjust(width[, fillbyte])

Retorna una copia del objeto justificado por la derecha en una secuencia de longitud width. El relleno se realiza usando el valor definido en el parámetro fillbyte (Por defecto, el carácter espacio en ASCII). Para los objetos de tipo bytes, se retorna la secuencia original intacta si width es menor o igual que len(s).

Nota

La versión bytearray de este método no modifica los valores internamente (no opera in place): siempre produce un nuevo objeto, aun si no se hubiera realizado ningún cambio.

bytes.rsplit(sep=None, maxsplit=-1)

bytearray.rsplit(sep=None, maxsplit=-1)

Divide una secuencia binaria en subsecuencias del mismo tipo, usando como separador el valor de sep. Si se utiliza el parámetro maxsplit, se realizan como máximo maxsplit divisiones, retornando los que están más a la derecha. Si no se especifica sep o se pasa con valor None, se usa como separador el carácter espacio en ASCII. Si no contamos la diferencia de empezar las divisiones desde la derecha, el comportamiento de este método rsplit() es equivalente al de split(), que se describe con detalle más adelante.

bytes.rstrip([chars])

bytearray.rstrip([chars])

Retorna una copia de la cadena, eliminado determinados bytes si se encuentren al final. El parámetro chars es una secuencia binaria que especifica el conjunto de bytes a eliminar; el nombre hace referencia a que este método se usa normalmente con secuencias de caracteres ASCII. Si se omite o si se especifica None, se eliminan los caracteres espacio en ASCII. No debe entenderse el valor de chars como un prefijo, sino que se elimina cualquier combinación de sus caracteres:

>>> b'   spacious   '.rstrip()
b'   spacious'
>>> b'mississippi'.rstrip(b'ipz')
b'mississ'

La secuencia binaria que especifica el conjunto bytes a ser eliminados puede ser cualquier objeto de tipo binario. Véase removesuffix() para un método que removerá una única cadena de sufijo en lugar de de todas las ocurrencias dentro de un set de caracteres. Por ejemplo:

>>> b'Monty Python'.rstrip(b' Python')
b'M'
>>> b'Monty Python'.removesuffix(b' Python')
b'Monty'

Nota

La versión bytearray de este método no modifica los valores internamente (no opera in place): siempre produce un nuevo objeto, aun si no se hubiera realizado ningún cambio.

bytes.split(sep=None, maxsplit=-1)

bytearray.split(sep=None, maxsplit=-1)

Divide una secuencia binaria en subsecuencias del mismo tipo, usando como separador el valor de sep. Si se utiliza el parámetro maxsplit y es un número positivo, se realizan como máximo maxsplit divisiones (Resultando en una secuencia de como mucho maxsplit+1 elementos). Si no se especifica sep o se pasa '1, no hay límite al número de divisiones.

Si se especifica sep, las repeticiones de caracteres delimitadores no se agrupan juntos, sino que se considera que están delimitando cadenas vacías (Por ejemplo, b'1,,2'.split(b',') retorna [b'1', b'', b'2']). El parámetro sep puede contener más de un carácter (Por ejemplo, b'1<>2<>3'.split(b'<>') retorna [b'1', b'2', b'3']). Dividir una cadena vacía con un separador determinado retornará [b''] o [bytearray(b'')] dependiendo del tipo de objeto dividido. El parámetro sep puede ser cualquier objeto tipo binario.

Por ejemplo:

>>> b'1,2,3'.split(b',')
[b'1', b'2', b'3']
>>> b'1,2,3'.split(b',', maxsplit=1)
[b'1', b'2,3']
>>> b'1,2,,3,'.split(b',')
[b'1', b'2', b'', b'3', b'']

Si no se especifica sep o es None, se usa un algoritmo de división diferente: Secuencias consecutivas de caracteres de espacio en ASCII se consideran como un único separador, y el resultado no contendrá cadenas vacías ni al principio ni al final de la lista, aunque la cadena original tuviera espacios en blanco al principio o al final. En consecuencia, dividir una secuencia vacía o que solo contenga espacios en blanco usando None como separador siempre retornará una lista vacía [].

Por ejemplo:

>>> b'1 2 3'.split()
[b'1', b'2', b'3']
>>> b'1 2 3'.split(maxsplit=1)
[b'1', b'2 3']
>>> b'   1   2   3   '.split()
[b'1', b'2', b'3']

bytes.strip([chars])

bytearray.strip([chars])

Retorna una copia de la secuencia con los bytes indicados eliminados, tanto si están al principio como al final de la cadena. El parámetro opcional chars es una secuencia de bytes que especifica el conjunto de caracteres a eliminar; el nombre hace referencia a que este método se usa normalmente con secuencias de caracteres ASCII. Si se omite o se usa None, se eliminan los caracteres de espacio ASCII. No debe entenderse el valor de chars como un prefijo o sufijo, sino que se elimina cualquier combinación de sus valores:

>>> b'   spacious   '.strip()
b'spacious'
>>> b'www.example.com'.strip(b'cmowz.')
b'example'

La secuencia binaria de bytes a eliminar deber ser un objeto tipo binario.

Nota

La versión bytearray de este método no modifica los valores internamente (no opera in place): siempre produce un nuevo objeto, aun si no se hubiera realizado ningún cambio.

Los siguientes métodos de los objetos bytes y bytearray asumen el uso de formatos binarios compatibles con ASCII, y no deben ser usados con datos binarios arbitrarios. Nótese que todos los métodos de bytearray en esta sección nunca modifican los datos internamente, sino que siempre retornan objetos nuevos.

bytes.capitalize()

bytearray.capitalize()

Retorna una copia de la secuencia con cada byte interpretado como un carácter ASCII, y el primer byte en mayúsculas y el resto en minúsculas. Los valores que no sean ASCII no se ven modificados.

Nota

La versión bytearray de este método no modifica los valores internamente (no opera in place): siempre produce un nuevo objeto, aun si no se hubiera realizado ningún cambio.

bytes.expandtabs(tabsize=8)

bytearray.expandtabs(tabsize=8)

Retorna una copia de la secuencia, con todos los caracteres ASCII tab/ reemplazados por uno o más espacios ASCII, dependiendo de la columna actual y del tamaño definido para el tabulador. Las posiciones de tabulación ocurren cada tabsize caracteres (Siendo el valor por defecto de tabsize 8, lo que produce las posiciones de tabulación 0, 8, 16,…). Para expandir la secuencia, la columna actual se pone a cero y se va examinando byte a byte. Si se encuentra un tabulador, (b'\t'), se insertan uno o más espacios hasta que sea igual a la siguiente posición de tabulación (El carácter tabulador en sí es descartado). Si el byte en un indicador de salto de línea (b'\n') o de retorno (b'\r'), se copia y el valor de columna actual se vuelve a poner a cero. Cualquier otro carácter es copiado sin cambios y hace que el contador de columna se incremente en 1, sin tener en cuenta como se representa impreso el byte:

>>> b'01\t012\t0123\t01234'.expandtabs()
b'01      012     0123    01234'
>>> b'01\t012\t0123\t01234'.expandtabs(4)
b'01  012 0123    01234'

Nota

La versión bytearray de este método no modifica los valores internamente (no opera in place): siempre produce un nuevo objeto, aun si no se hubiera realizado ningún cambio.

bytes.isalnum()

bytearray.isalnum()

Retorna True si todos los bytes de la secuencia son caracteres alfabéticos ASCII o caracteres decimales ASCII y la secuencia no está vacía. En cualquier otro caso retorna False. Los caracteres alfabéticos ASCII son los bytes incluidos en la secuencia b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'. Los caracteres decimales ASCII son los bytes incluidos en la secuencia b'0123456789'.

Por ejemplo:

>>> b'ABCabc1'.isalnum()
True
>>> b'ABC abc1'.isalnum()
False

bytes.isalpha()

bytearray.isalpha()

Retorna True si todos los bytes de la secuencia son caracteres alfabéticos ASCII y la secuencia no está vacía. En cualquier otro caso Retorna False. Los caracteres alfabéticos ASCII son los bytes incluidos en la secuencia b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'.

Por ejemplo:

>>> b'ABCabc'.isalpha()
True
>>> b'ABCabc1'.isalpha()
False

bytes.isascii()

bytearray.isascii()

Retorna True si la secuencia está vacía o si todos los bytes de la secuencia son caracteres ASCII. En cualquier otro caso retorna False. Los caracteres ASCII son los bytes incluidos en el rango 0-0x7F.

Nuevo en la versión 3.7.

bytes.isdigit()

bytearray.isdigit()

Retorna True si todos los bytes de la secuencia son caracteres decimales ASCII y la secuencia no está vacía. En cualquier otro caso retorna False. Los caracteres decimales ASCII son los bytes incluidos en la secuencia b'0123456789'.

Por ejemplo:

>>> b'1234'.isdigit()
True
>>> b'1.23'.isdigit()
False

bytes.islower()

bytearray.islower()

Retorna True si hay al menos un carácter ASCII en minúsculas, y no hay ningún carácter ASCII en mayúsculas. En cualquier otro caso retorna False.

Por ejemplo:

>>> b'hello world'.islower()
True
>>> b'Hello world'.islower()
False

Los caracteres ASCII en minúsculas son los bytes incluidos en la secuencia b'abcdefghijklmnopqrstuvwxyz'. los caracteres ASCII en mayúsculas son los bytes en la secuencia b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.

bytes.isspace()

bytearray.isspace()

Retorna True si todos los bytes de la secuencia son caracteres ASCII de espacio en blanco y la secuencia no está vacía. En cualquier otro caso Retorna False. Los caracteres de espacio en blanco ASCII son los bytes incluidos en la secuencia b' \t\n\r\x0b\f' (Espacio, tabulador, nueva línea, retorno de carro, tabulador vertical y avance de página).

bytes.istitle()

bytearray.istitle()

Retorna True si la secuencia ASCII está en forma de título, y la secuencio no está vacía. En cualquier otro caso retorna False. Véase el método bytes.title() para más detalles en la definición de «En forma de título».

Por ejemplo:

>>> b'Hello World'.istitle()
True
>>> b'Hello world'.istitle()
False

bytes.isupper()

bytearray.isupper()

Retorna True si hay al menos un carácter ASCII en mayúsculas, y no hay ningún carácter ASCII en minúsculas. En cualquier otro caso retorna False.

Por ejemplo:

>>> b'HELLO WORLD'.isupper()
True
>>> b'Hello world'.isupper()
False

Los caracteres ASCII en minúsculas son los bytes incluidos en la secuencia b'abcdefghijklmnopqrstuvwxyz'. los caracteres ASCII en mayúsculas son los bytes en la secuencia b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.

bytes.lower()

bytearray.lower()

Retorna una copia de la secuencia con todos los caracteres ASCII en mayúsculas sustituidos por su versión correspondiente en minúsculas.

Por ejemplo:

>>> b'Hello World'.lower()
b'hello world'

Los caracteres ASCII en minúsculas son los bytes incluidos en la secuencia b'abcdefghijklmnopqrstuvwxyz'. los caracteres ASCII en mayúsculas son los bytes en la secuencia b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.

Nota

La versión bytearray de este método no modifica los valores internamente (no opera in place): siempre produce un nuevo objeto, aun si no se hubiera realizado ningún cambio.

bytes.splitlines(keepends=False)

bytearray.splitlines(keepends=False)

Retorna una lista de las líneas en la secuencia binaría, usando como separadores los saltos de líneas universales. Los caracteres usados como separadores no se incluyen en la lista de resultados a no ser que se pase el parámetro keepends a True.

Por ejemplo:

>>> b'ab c\n\nde fg\rkl\r\n'.splitlines()
[b'ab c', b'', b'de fg', b'kl']
>>> b'ab c\n\nde fg\rkl\r\n'.splitlines(keepends=True)
[b'ab c\n', b'\n', b'de fg\r', b'kl\r\n']

Al contrario que el método split(), cuando se especifica una cadena delimitadora con el parámetro sep, este método retorna una lista vacía para la cadena vacía, y un carácter de salto de línea al final de la secuencia no resulta en una línea extra:

>>> b"".split(b'\n'), b"Two lines\n".split(b'\n')
([b''], [b'Two lines', b''])
>>> b"".splitlines(), b"One line\n".splitlines()
([], [b'One line'])

bytes.swapcase()

bytearray.swapcase()

Retorna una copia de la secuencia con todos los caracteres ASCII en minúsculas sustituidos por su versión correspondiente en mayúsculas, y viceversa.

Por ejemplo:

>>> b'Hello World'.swapcase()
b'hELLO wORLD'

Los caracteres ASCII en minúsculas son los bytes incluidos en la secuencia b'abcdefghijklmnopqrstuvwxyz'. los caracteres ASCII en mayúsculas son los bytes en la secuencia b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.

Al contrario que la función str.swapcase(), en este caso siempre se cumple que bin.swapcase().swapcase() == bin para las versiones binarias. La conversión de mayúsculas a minúsculas son simétricas en ASCII, aunque esto no es el caso general para códigos de punto Unicode.

Nota

La versión bytearray de este método no modifica los valores internamente (no opera in place): siempre produce un nuevo objeto, aun si no se hubiera realizado ningún cambio.

bytes.title()

bytearray.title()

Retorna una versión en forma de título de la secuencia binaria, con la primera letra de cada palabra en mayúsculas y el resto en minúsculas.

Por ejemplo:

>>> b'Hello world'.title()
b'Hello World'

Los caracteres ASCII en minúsculas son los bytes incluidos en la secuencia b'abcdefghijklmnopqrstuvwxyz'. los caracteres ASCII en mayúsculas son los bytes en la secuencia b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'. El resto de los caracteres no presentan diferencias entre mayúsculas y minúsculas.

El algoritmo usa una definición sencilla e independiente del lenguaje, consistente en considerar una palabra como un grupo de letras consecutivas. Esta definición funciona en varios entornos, pero implica que, por ejemplo en inglés, los apóstrofos en las contracciones y en los posesivos constituyen una separación entre palabras, que puede que no sea el efecto deseado:

>>> b"they're bill's friends from the UK".title()
b"They'Re Bill'S Friends From The Uk"

Se puede solucionar parcialmente el problema de los apóstrofos usando expresiones regulares:

>>> import re
>>> def titlecase(s):
...     return re.sub(rb"[A-Za-z]+('[A-Za-z]+)?",
...                   lambda mo: mo.group(0)[0:1].upper() +
...                              mo.group(0)[1:].lower(),
...                   s)
...
>>> titlecase(b"they're bill's friends.")
b"They're Bill's Friends."

Nota

La versión bytearray de este método no modifica los valores internamente (no opera in place): siempre produce un nuevo objeto, aun si no se hubiera realizado ningún cambio.

bytes.upper()

bytearray.upper()

Retorna una copia de la secuencia con todos los caracteres ASCII en minúsculas sustituidos por su versión correspondiente en mayúsculas.

Por ejemplo:

>>> b'Hello World'.upper()
b'HELLO WORLD'

Los caracteres ASCII en minúsculas son los bytes incluidos en la secuencia b'abcdefghijklmnopqrstuvwxyz'. los caracteres ASCII en mayúsculas son los bytes en la secuencia b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.

Nota

La versión bytearray de este método no modifica los valores internamente (no opera in place): siempre produce un nuevo objeto, aun si no se hubiera realizado ningún cambio.

bytes.zfill(width)

bytearray.zfill(width)

Retorna una copia de la secuencia rellenada por la izquierda con los caracteres ASCII b'0' necesarios para conseguir una cadena de longitud width. El carácter prefijo de signo (b'+'/b'-') se gestiona insertando el relleno después del carácter de signo en vez de antes.Para objetos bytes, se retorna la secuencia original si width es menor o igual que len(s).

Por ejemplo:

>>> b"42".zfill(5)
b'00042'
>>> b"-42".zfill(5)
b'-0042'

Nota

La versión bytearray de este método no modifica los valores internamente (no opera in place): siempre produce un nuevo objeto, aun si no se hubiera realizado ningún cambio.

Usando el formateo tipo printf con bytes

Nota

Las operaciones de formateo explicadas aquí tienen una serie de peculiaridades que conducen a ciertos errores comunes (Como fallar al representar tuplas y diccionarios correctamente). Si el valor a representar es una tupla o un diccionario, hay que envolverlos en una tupla.

Los objetos binarios (bytes/bytearray) tienen una operación básica: El operador % (módulo). Esta operación se conoce también como operador de formateo o de interpolación. Dada la expresión formato % valores (Donde formato es un objeto binario), las especificaciones de conversión indicadas en la cadena con el símbolo % son reemplazadas por cero o más elementos de valores. El efecto es similar a usar la función del lenguaje C sprintf().

Si formato tiene un único marcador, valores puede ser un objeto sencillo, no una tupla. 5 En caso contrario, valores debe ser una tupla con exactamente el mismo número de elementos que marcadores usados en el objeto binario, o un único objeto de tipo mapa (Por ejemplo, un diccionario).

Un especificador de conversión consiste en dos o más caracteres y tiene los siguientes componentes, que deben aparecer en el siguiente orden:

El carácter '%', que identifica el inicio del marcador.

Una clave de mapeo (opcional), consistente en una secuencia de caracteres entre paréntesis, como por ejemplo, (somename).

Indicador de conversión (opcional), que afecta el resultado de ciertas conversiones de tipos.

Valor de ancho mínimo (opcional). Si se especifica un '*' (asterisco), el ancho real se lee del siguiente elemento de la tupla valores, y el objeto a convertir viene después del ancho mínimo, con un indicador de precisión opcional.

Precisión (Opcional), en la forma '.' (punto) seguido de la precisión. Si se especifica un '*' (Asterisco), el valor de precisión real se lee del siguiente elemento de la tupla valores, y el valor a convertir viene después de la precisión.

Modificador de longitud (Opcional).

Tipo de conversión.

Cuando el operador derecho es un diccionario (o cualquier otro objeto de tipo mapa), los marcadores en el objeto binario deben incluir un valor de clave entre paréntesis, inmediatamente después del carácter '%'. El valor de la clave se usa para seleccionar el valor a formatear desde el mapa. Por ejemplo:

>>> print(b'%(language)s has %(number)03d quote types.' %
...       {b'language': b"Python", b"number": 2})
b'Python has 002 quote types.'

En este caso, no se pueden usar el especificador * en la cadena de formato (Dado que requiere una lista secuencial de parámetros).

Los indicadores de conversión son:

Flag

Significado

'#'

El valor a convertir usara la «forma alternativa» (Que se definirá más adelante)

'0'

La conversión rellena con ceros por la izquierda para valores numéricos.

'-'

El valor convertido se ajusta a la izquierda (Sobreescribe la conversión '0' si se especifican los dos)

' '

(Un espacio) Se deba añadir un espacio en blanco antes de un número positivo (O una cadena vacía) si se usa una conversión con signo.

'+'

Un carácter signo ('+' o '-') precede a la conversión (Sobreescribe el indicador de «espacio»)

Puede estar presente un modificador de longitud (h, l o L), pero se ignora y no es necesario para Python – por lo que, por ejemplo, la salida de %ld es idéntica a %d.

Los tipos de conversión son:

Conversión

Significado

Notas

'd'

Entero decimal con signo.

'i'

Entero decimal con signo.

'o'

Valor octal con signo.

(1)

'u'

Obsoleto – es idéntico a 'd'.

(8)

'x'

Hexadecimal con signo (En minúsculas)

(2)

'X'

Hexadecimal con signo (En mayúsculas)

(2)

'e'

Formato en coma flotante exponencial (En minúsculas).

(3)

'E'

Formato en coma flotante exponencial (En mayúsculas).

(3)

'f'

Formato en coma flotante decimal.

(3)

'F'

Formato en coma flotante decimal.

(3)

'g'

Formato en coma flotante. Usa formato exponencial con minúsculas si el exponente es menor que -4 o no es menor que la precisión, en caso contrario usa el formato decimal.

(4)

'G'

Formato en coma flotante. Usa formato exponencial con mayúsculas si el exponente es menor que -4 o no es menor que la precisión, en caso contrario usa el formato decimal.

(4)

'c'

Byte único (Acepta números enteros o binarios de un único byte)

'b'

Bytes (Cualquier objeto que siga el protocolo de objetos de tipo binario o implemente el método __bytes__()).

(5)

's'

's' es un alias de 'b' y solo debe ser usado para bases de código Python2/3.

(6)

'a'

Bytes (converts any Python object using repr(obj).encode('ascii', 'backslashreplace')).

(5)

'r'

'r' es un alias de 'a' y solo debe ser usado para bases de código Python2/3.

(7)

'%'

No se representa ningún argumento, obteniéndose en el resultado la cadena '%'.

Notas:

La forma alternativa hace que se inserte antes del primer dígito un prefijo indicativo del formato octal ('0o')

La forma alternativa hace que se inserte antes del primer dígito uno de los dos prefijos indicativos del formato hexadecimal '0x' or '0X' (Que se use uno u otro depende de que indicador de formato se haya usado, 'x' or 'X').

La forma alternativa hace que se incluya siempre el símbolo del punto o coma decimal, incluso si no hubiera dígitos después.

La precisión determina el número de dígitos que vienen después del punto decimal, y por defecto es 6.

La forma alternativa hace que se incluya siempre el símbolo del punto o coma decimal, y los ceros a su derecha no se eliminan, como seria el caso en la forma normal.

La precisión determina el número de dígitos significativos que vienen antes y después del punto decimal, y por defecto es 6.

Si la precisión es N, la salida se trunca a N caracteres.

b'%s' está obsoleto, pero no se retirará durante la serie 3.x.

b'%r' está obsoleto, pero no se retirará durante la serie 3.x.

Véase PEP 237 [https://www.python.org/dev/peps/pep-0237].

Nota

La versión bytearray de este método no modifica los valores internamente (no opera in place): siempre produce un nuevo objeto, aun si no se hubiera realizado ningún cambio.

Ver también

PEP 461 [https://www.python.org/dev/peps/pep-0461] - Añadir formato usando % con bytes y bytearray

Nuevo en la versión 3.5.

Vistas de memoria

Los objetos de tipo memoryview permiten al código Python acceder a los datos internos de objetos que soporten el protocolo buffer sin necesidad de hacer copias.

class memoryview(object)

Create a memoryview that references object. object must support the buffer protocol. Built-in objects that support the buffer protocol include bytes and bytearray.

A memoryview has the notion of an element, which is the atomic memory unit handled by the originating object. For many simple types such as bytes and bytearray, an element is a single byte, but other types such as array.array may have bigger elements.

El resultado de len(view) es igual a la longitud de tolist. Si view.ndim = 0, la longitud es 1. Si view.ndim = 1, la longitud es igual al número de elementos en la vista. Para dimensiones superiores, la longitud es igual a la de la representación como lista anidada de la vista. El atributo itemsize contiene el número de bytes que ocupa un único elemento.

Un objeto de tipo memoryview soporta operaciones de rebanado y acceso por índices a sus datos. Un rebanado unidimensional producirá una sub-vista:

>>> v = memoryview(b'abcefg')
>>> v[1]
98
>>> v[-1]
103
>>> v[1:4]
<memory at 0x7f3ddc9f4350>
>>> bytes(v[1:4])
b'bce'

Si format es uno de los especificadores de formato nativos del módulo struct, el indexado con un número entero o una tupla de números enteros también es posible, y retorna un único elemento con el tipo adecuado. Objetos memoryview unidimensionales pueden ser indexados con un entero o con una tupla de enteros. Los memoryview con múltiples dimensiones pueden ser indexados con tuplas de exactamente ndim enteros, donde ndim es el número de dimensiones. Vistas memoryviews con cero dimensiones pueden ser indexados con una tupla vacía.

Aquí hay un ejemplo con un formato que no es un byte:

>>> import array
>>> a = array.array('l', [-11111111, 22222222, -33333333, 44444444])
>>> m = memoryview(a)
>>> m[0]
-11111111
>>> m[-1]
44444444
>>> m[::2].tolist()
[-11111111, -33333333]

Si el objeto usado para crear la vista es modificable, la vista memoryview soporta asignación unidimensional mediante rebanadas. Sin embargo, no se permite el cambio de tamaño:

>>> data = bytearray(b'abcefg')
>>> v = memoryview(data)
>>> v.readonly
False
>>> v[0] = ord(b'z')
>>> data
bytearray(b'zbcefg')
>>> v[1:4] = b'123'
>>> data
bytearray(b'z123fg')
>>> v[2:3] = b'spam'
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: memoryview assignment: lvalue and rvalue have different structures
>>> v[2:6] = b'spam'
>>> data
bytearray(b'z1spam')

Los objetos memoryviews de una única dimensión que contienen tipos de datos hashables (De solo lectura) con formatos 'B', 'b' o 'c' son también hashables. El hash se define como hash(m) == hash(m.tobytes()):

>>> v = memoryview(b'abcefg')
>>> hash(v) == hash(b'abcefg')
True
>>> hash(v[2:4]) == hash(b'ce')
True
>>> hash(v[::-2]) == hash(b'abcefg'[::-2])
True

Distinto en la versión 3.3: Los objetos memoryviews de una única dimensión pueden ahora ser usados con operaciones de rebanado. Los objetos memoryviews de una única dimensión con formatos 'B', 'b' o 'c' son ahora hashables.

Distinto en la versión 3.4: los objetos memoryview son registrados automáticamente con la clase collections.abc.Sequence

Distinto en la versión 3.5: los objetos memoryviews se pueden ahora acceder usando como índices una tupla de números enteros.

La clase memoryview tiene varios métodos:

__eq__(exporter)

Un objeto memoryview y un exportador PEP 3118 [https://www.python.org/dev/peps/pep-3118] son iguales si sus formas son equivalentes y todos los valores correspondientes son iguales cuando los formatos respectivos de los operandos son interpretados usando la sintaxis de struct.

Para el subconjunto de formatos de struct soportados actualmente por tolist(), v y w son iguales si v.tolist() == w.tolist():

>>> import array
>>> a = array.array('I', [1, 2, 3, 4, 5])
>>> b = array.array('d', [1.0, 2.0, 3.0, 4.0, 5.0])
>>> c = array.array('b', [5, 3, 1])
>>> x = memoryview(a)
>>> y = memoryview(b)
>>> x == a == y == b
True
>>> x.tolist() == a.tolist() == y.tolist() == b.tolist()
True
>>> z = y[::-2]
>>> z == c
True
>>> z.tolist() == c.tolist()
True

Si cualquiera de las cadenas de formato no es soportada por el módulo struct, entonces la comparación de los objetos siempre los considerará diferentes (Incluso si las cadenas de formato y el contenido del buffer son idénticos):

>>> from ctypes import BigEndianStructure, c_long
>>> class BEPoint(BigEndianStructure):
...     _fields_ = [("x", c_long), ("y", c_long)]
...
>>> point = BEPoint(100, 200)
>>> a = memoryview(point)
>>> b = memoryview(point)
>>> a == point
False
>>> a == b
False

Nótese que, al igual que con los números en coma flotante, v is w no implica que v == w para objetos del tipo memoryview.

Distinto en la versión 3.3: Versiones previas comparaban la memoria directamente, sin considerar ni el formato de los elementos ni la estructura lógica de array.

tobytes(order=None)

Retorna los datos en el buffer en forma de cadena de bytes. Equivale a llamar al constructor de la clase bytes en el objeto memoryview:

>>> m = memoryview(b"abc")
>>> m.tobytes()
b'abc'
>>> bytes(m)
b'abc'

Para arrays no contiguos el resultado es igual a la representación en forma de lista aplanada, con todos los elementos convertidos a bytes. El método tobytes() soporta todos los formatos de texto, incluidos aquellos que no se encuentran en la sintaxis del módulo struct.

Nuevo en la versión 3.8: El valor de order puede ser {“C”, “F”, “A”}. Cuando order es “C” o “F”, los datos en el array original se convierten al orden de C o Fortran. Para vistas contiguas, “A” retorna una copia exacta de la memoria física. En particular, el orden en memoria de Fortran se mantiene inalterado. Para vista no contiguas, los datos se convierten primero a C. Definir order=None es lo mismo que order=”C”.

hex([sep[, bytes_per_sep]])

Retorna una cadena de caracteres que contiene dos dígitos hexadecimales por cada byte en el buffer:

>>> m = memoryview(b"abc")
>>> m.hex()
'616263'

Nuevo en la versión 3.5.

Distinto en la versión 3.8: De forma similar a bytes.hex(), memoryview.hex() soporta ahora los parámetros opcionales sep y bytes_per_sep para insertar separadores entre los bytes en la cadena hexadecimal de salida.

tolist()

Retorna los datos en el buffer como una lista de elementos.

>>> memoryview(b'abc').tolist()
[97, 98, 99]
>>> import array
>>> a = array.array('d', [1.1, 2.2, 3.3])
>>> m = memoryview(a)
>>> m.tolist()
[1.1, 2.2, 3.3]

Distinto en la versión 3.3: El método tolist() soporta ahora todos los formatos nativos de un solo carácter definidos en el módulo struct, así como las representaciones de múltiples dimensiones.

toreadonly()

Retorna una versión de solo lectura del objeto memoryview. El objeto original permanece inalterado:

>>> m = memoryview(bytearray(b'abc'))
>>> mm = m.toreadonly()
>>> mm.tolist()
[89, 98, 99]
>>> mm[0] = 42
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: cannot modify read-only memory
>>> m[0] = 43
>>> mm.tolist()
[43, 98, 99]

Nuevo en la versión 3.8.

release()

Libera el buffer subyacente expuesto por el objeto memoryview. Muchos objetos realizan operaciones especiales cuando una vista los está conteniendo (Por ejemplo, un objeto bytearray temporalmente prohíbe el cambio de tamaño); la llamada a release() sirve para eliminar estas restricciones (Así como para tratar con los recursos pendientes) lo más pronto posible.

Después de que se ha llamado a este método, cualquier operación posterior sobre la vista lanzará una excepción de tipo ValueError (Excepto por el propio método release(), que puede ser llamado las veces que se quiera):

>>> m = memoryview(b'abc')
>>> m.release()
>>> m[0]
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: operation forbidden on released memoryview object

El protocolo de gestión de contexto puede ser usado para obtener un efecto similar, usando la sentencia with:

>>> with memoryview(b'abc') as m:
...     m[0]
...
97
>>> m[0]
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: operation forbidden on released memoryview object

Nuevo en la versión 3.2.

cast(format[, shape])

Transforma el formato o el tamaño de un objeto memoryview. El parámetro shape por defecto vale [byte_length//new_itemsize], lo que significa que el resultado será unidimensional. El valor de retorno es un nuevo objeto de tipo memoryview, pero el buffer en sí no se copia. Las transformaciones pueden ser 1D -> C-contiguo y C-contiguo -> 1D.

El formato de destino está restringido a un único elemento de formato nativo en la sintaxis de struct. Uno de los formatos debe ser un formato de byte ('B', 'b' o 'c'). La longitud en bytes del resultado debe coincidir con la longitud original.

Transforma de 1D/long a bytes 1D/unsigned:

>>> import array
>>> a = array.array('l', [1,2,3])
>>> x = memoryview(a)
>>> x.format
'l'
>>> x.itemsize
8
>>> len(x)
3
>>> x.nbytes
24
>>> y = x.cast('B')
>>> y.format
'B'
>>> y.itemsize
1
>>> len(y)
24
>>> y.nbytes
24

Transforma de 1D/unsigned a bytes 1D/char:

>>> b = bytearray(b'zyz')
>>> x = memoryview(b)
>>> x[0] = b'a'
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: memoryview: invalid value for format "B"
>>> y = x.cast('c')
>>> y[0] = b'a'
>>> b
bytearray(b'ayz')

Transforma de 1D/bytes a 3D/ints a caracteres 1D/signed:

>>> import struct
>>> buf = struct.pack("i"*12, *list(range(12)))
>>> x = memoryview(buf)
>>> y = x.cast('i', shape=[2,2,3])
>>> y.tolist()
[[[0, 1, 2], [3, 4, 5]], [[6, 7, 8], [9, 10, 11]]]
>>> y.format
'i'
>>> y.itemsize
4
>>> len(y)
2
>>> y.nbytes
48
>>> z = y.cast('b')
>>> z.format
'b'
>>> z.itemsize
1
>>> len(z)
48
>>> z.nbytes
48

Transforma de long 1D/unsigned a long 2D/unsigned:

>>> buf = struct.pack("L"*6, *list(range(6)))
>>> x = memoryview(buf)
>>> y = x.cast('L', shape=[2,3])
>>> len(y)
2
>>> y.nbytes
48
>>> y.tolist()
[[0, 1, 2], [3, 4, 5]]

Nuevo en la versión 3.3.

Distinto en la versión 3.5: El formato de origen ya no está restringido cuando se transforma a una vista de bytes.

Hay disponibles varios atributos de solo lectura:

obj

El objeto subyacente del memoryview:

>>> b  = bytearray(b'xyz')
>>> m = memoryview(b)
>>> m.obj is b
True

Nuevo en la versión 3.3.

nbytes

nbytes == product(shape) * itemsize == len(m.tobytes()). Este es el espacio, medido en bytes, que usará el array en una representación continua. No tiene que ser necesariamente igual a len(m):

>>> import array
>>> a = array.array('i', [1,2,3,4,5])
>>> m = memoryview(a)
>>> len(m)
5
>>> m.nbytes
20
>>> y = m[::2]
>>> len(y)
3
>>> y.nbytes
12
>>> len(y.tobytes())
12

Matrices de múltiples dimensiones:

>>> import struct
>>> buf = struct.pack("d"*12, *[1.5*x for x in range(12)])
>>> x = memoryview(buf)
>>> y = x.cast('d', shape=[3,4])
>>> y.tolist()
[[0.0, 1.5, 3.0, 4.5], [6.0, 7.5, 9.0, 10.5], [12.0, 13.5, 15.0, 16.5]]
>>> len(y)
3
>>> y.nbytes
96

Nuevo en la versión 3.3.

readonly

Un booleano que indica si la memoria es de solo lectura.

format

Una cadena de caracteres que contiene el formato (En el estilo del módulo struct) para cada elemento de la vista. Un objeto memoryview se puede crear a partir de un exportador con textos de formato arbitrarios, pero algunos métodos (Como, por ejemplo, tolist()) están restringidos a usar formatos de elementos nativos sencillos.

Distinto en la versión 3.3: el formato 'B' se gestiona ahora de acuerdo a la sintaxis descrita en el módulo struct. Esto significa que memoryview(b'abc')[0] == b'abc'[0] == 97.

itemsize

El tamaño en bytes de cada elemento del objeto memoryview:

>>> import array, struct
>>> m = memoryview(array.array('H', [32000, 32001, 32002]))
>>> m.itemsize
2
>>> m[0]
32000
>>> struct.calcsize('H') == m.itemsize
True

ndim

Un número entero que indica cuantas dimensiones de una matriz multi-dimensional representa la memoria.

shape

Una tupla de números enteros, de longitud ndim, que indica la forma de la memoria en una matriz de N dimensiones.

Distinto en la versión 3.3: Una tupla vacía, en vez de None, cuando ndom = 0.

strides

Una tupla de números enteros, de longitud ndim, que indica el tamaño en bytes para acceder a cada dimensión de la matriz.

Distinto en la versión 3.3: Una tupla vacía, en vez de None, cuando ndom = 0.

suboffsets

De uso interno para las matrices estilo PIL. El valor es solo informativo.

c_contiguous

Un booleano que indica si la memoria es contiguous al estilo C.

Nuevo en la versión 3.3.

f_contiguous

Un booleano que indica si la memoria es contiguous al estilo Fortran.

Nuevo en la versión 3.3.

contiguous

Un booleano que indica si la memoria es contiguous.

Nuevo en la versión 3.3.

Conjuntos — set, frozenset

Un objeto de tipo conjunto o set es una colección no ordenada de distintos objetos hashable. Los casos de uso habituales incluyen comprobar la pertenencia al conjunto de un elemento, eliminar duplicados de una secuencia y realizar operaciones matemáticas como la intersección, la unión, la diferencia o la diferencia simétrica (Para otros tipos de contenedores véanse las clases básicas dict, list, y tuple, así como el módulo collections).

Como otras colecciones, los conjuntos soportan x in set, len(set) y for x in set. Como es una colección sin orden, los conjuntos no registran ni la posición ni el orden de inserción de los elementos. Por lo mismo, los conjuntos no soportan indexado, ni operaciones de rebanadas, ni otras capacidades propias de las secuencias.

En la actualidad hay dos tipos básicos de conjuntos: set y frozenset. La clase set es mutable, es decir, el contenido del conjunto puede ser modificado con métodos como add() y remove(). Como es mutable, no tiene un valor de hash y no pueden ser usados como claves de diccionarios ni como elementos de otros conjuntos. La clase frozenset es inmutable y hashable, es decir, que sus contenidos no pueden ser modificados después de creados. Puede ser usado, por tanto, como claves de diccionario o como elemento de otro conjunto.

Se pueden crear conjuntos no vacíos (sets, no frozensets) escribiendo una lista de elementos separados por comas, entre llaves, por ejemplo {'jack', 'sjoerd'}, además de con el constructor de la clase set.

El constructor para ambas clases se usa de la misma forma:

class set([iterable])

class frozenset([iterable])

Retorna un nuevo set o frozenset, tomando los elementos a partir de iterable. Los elementos de un conjunto tienen que tener la propiedad de ser hashable. Para representar conjuntos anidados, o conjuntos de conjuntos, los conjuntos interiores tienen que ser instancias de frozenset. Si no se especifica el parámetro iterable, se retorna un conjunto vacío.

Los conjuntos (sets) se pueden construir de diferentes formas:

Usando una lista de elementos separados por coma entre corchetes: {'jack', 'sjoerd'}

Usando un set comprehention: {c for c in 'abracadabra' if c not in 'abc'}

Usando un constructor de tipo: set(), set('foobar'), set(['a', 'b', 'foo'])

Las instancias de set y frozenset proporcionan las siguientes operaciones:

len(s)

Retorna el número de elementos en el conjunto s (Cardinalidad de s)

x in s

Comprueba que el elemento x está incluido en s.

x not in s

Comprueba que el elemento x no está incluido en s.

isdisjoint(other)

Retorna True si el conjunto no tienen ningún elemento en común con other. Dos conjuntos son disjuntos si y solo si su intersección es el conjunto vacío.

issubset(other)

set <= other

Comprueba si cada elemento del conjunto también se encuentra en other.

set < other

Comprueba si el conjunto es un subconjunto propio de other, es decir, set <= other and set != other.

issuperset(other)

set >= other

Comprueba que cada elemento de other está incluido en el conjunto.

set > other

Comprueba si el conjunto es un superconjunto propio de other, es decir, set >= other and set != other.

union(*others)

set | other | ...

Retorna un conjunto nuevo que contiene todos los elementos del conjunto y de others.

intersection(*others)

set & other & ...

Retorna un conjunto nuevo que contiene todos los elementos que están a la vez en conjunto y en others.

difference(*others)

set - other - ...

Retorna un conjunto nuevo que contiene todos los elementos del conjunto y que no están incluidos en others.

symmetric_difference(other)

set ^ other

Retorna un conjunto nuevo que contiene elementos que están incluidos en el conjunto o en others, pero no en los dos a la vez.

copy()

Retorna una copia superficial del conjunto.

Hay que señalar que las versiones de las operaciones que son métodos (no los operadores) como union(), intersection(), difference(), symmetric_difference(), issubset(), y issuperset() aceptan cualquier iterable como parámetro. Por el contrario, los operadores requieren que los argumentos sean siempre conjuntos. Esto evita ciertas construcciones propensas a errores como set('abc') & 'cbs', favoreciendo el uso formas más legibles como set('abc').intersection('cbs').

Ambas clases set y frozenset soportan comparaciones entre si. Dos conjuntos son iguales si y solo si cada elemento de cada conjunto está incluido en el otro (Cada uno de ellos es subconjunto del otro). Un conjunto es menor que otro si y solo si el primero es un subconjunto propio del segundo (Es un subconjunto, pero no son iguales). Un conjunto es mayor que otro si y solo si el primero en un superconjunto propio del segundo (Es un superconjunto, pero no son iguales).

Las instancias de set se comparan con las instancias de frozenset en base a sus elementos. Por ejemplo set('abc') == frozenset('abc') retorna True y lo mismo hace set('abc') in set([frozenset('abc')]).

Las comparaciones de subconjunto e igualdad no son tan generales que permitan una función de ordenación total. Por ejemplo, dos conjuntos cualesquiera que no estén vacíos y que sean disjuntos no son iguales y tampoco son subconjuntos uno del otro, así que todas estas operaciones retornan False: a<b, a==b, or a>b.

Como los conjuntos solo definen un orden parcial (Relaciones de conjuntos), la salida del método list.sort() no está definida para listas de conjuntos.

Los elementos de un conjunto, al igual que las claves de un diccionario, deben ser hashable.

Las operaciones binarias que mezclan instancias de set y frozenset retornan el tipo del primer operando. Por ejemplo frozenset('ab') | set('bc') retornará una instancia de frozenset.

La siguiente tabla muestra las operaciones disponibles para la clase set que no son aplicables a los conjuntos inmutables frozenset:

update(*others)

set |= other | ...

Actualiza el conjunto, añadiendo los elementos que se encuentren en others.

intersection_update(*others)

set &= other & ...

Actualiza el conjunto, manteniendo solo los elementos que se encuentren en si mismo y en others.

difference_update(*others)

set -= other | ...

Actualiza el conjunto, eliminado los elementos que se encuentren en others.

symmetric_difference_update(other)

set ^= other

Actualiza el conjunto, manteniendo solo los elementos que se encuentren en el conjunto o en others, pero no en los dos a la vez.

add(elem)

Añade al conjunto el elemento elem.

remove(elem)

Elimina del conjunto el elemento elem. Lanza la excepción KeyError si elem no estaba incluido en el conjunto.

discard(elem)

Elimina del conjunto el elemento elem, si estuviera incluido.

pop()

Elimina y retorna un elemento cualquiera del conjunto. Lanza la excepción KeyError si el conjunto estaba vacío.

clear()

Elimina todos los elementos del conjunto.

Hay que señalar que los métodos (no los operadores) update(), intersection_update(), difference_update(), y symmetric_difference_update() aceptan cualquier iterable como parámetro.

Nótese que el parámetro elem de los métodos __contains__(), remove() y discard() puede ser un conjunto. Para soportar la búsqueda por un frozenset equivalente se crea uno temporal a partir de elem.

Tipos Mapa — dict

Un objeto de tipo mapping relaciona valores (que deben ser hashable) con objetos de cualquier tipo. Los mapas son objetos mutables. En este momento solo hay un tipo estándar de mapa, los diccionarios (Para otros tipos contenedores, véanse las clases básicas list, set, y tuple, así como el módulo collections).

Las claves de un diccionario pueden ser casi de cualquier tipo. Los valores que no son hashable, como por ejemplo valores que contengan listas, diccionarios u otros tipo mutables (que son comparados por valor, no por referencia) no se pueden usar como claves. Los tipos numéricos, cuando se usan como claves siguen las reglas habituales de la comparación numérica: Si dos números se consideran iguales (Como 1 y 1.0), ambos valores pueden ser usados indistintamente para acceder al mismo valor (Pero hay que tener en cuenta que los ordenadores almacenan algunos números en coma flotante como aproximaciones, por lo que normalmente no es recomendable usarlos como claves).

class dict(**kwargs)

class dict(mapping, **kwargs)

class dict(iterable, **kwargs)

Retorna un diccionario creado a partir de un parámetro opcional por posición, y por una serie de parámetros por nombre, también opcionales.

Los diccionarios se pueden construir de diferentes formas:

Usando una lista separada por comas de pares key: value entre llaves:{'jack': 4098, 'sjoerd': 4127} or {4098: 'jack', 4127: 'sjoerd'}

Usando una comprensión de diccionario: {}, {x: x ** 2 for x in range(10)}

Usando un constructor de tipo: dict(), dict([('foo', 100), ('bar', 200)]), dict(foo=100, bar=200)

Si no se especifica el parámetro por posición, se crea un diccionario vacío. Si se pasa un parámetro por posición y es un objeto de tipo mapa, se crear el diccionario a partir de las parejas clave-valor definidos en el mapa. Si no fuera un mapa, se espera que el parámetro sea un objeto iterable. Cada elemento del iterable debe ser una dupla (Una tupla de dos elementos); el primer componente de la dupla se usará como clave y el segundo como valor a almacenar en el nuevo diccionario. Si una clave aparece más de una vez, el último valor será el que se almacene en el diccionario resultante.

Si se usan parámetros por nombre, los nombres de los parámetros y los valores asociados se añaden al diccionario creado a partir del parámetro por posición. Si un valor de clave ya estaba presente, el valor pasado con el parámetro por nombre reemplazara el valor del parámetro por posición.

A modo de ejemplo, los siguientes ejemplo retornan todos el mismo diccionario {"one": 1, "two": 2, "three": 3}:

>>> a = dict(one=1, two=2, three=3)
>>> b = {'one': 1, 'two': 2, 'three': 3}
>>> c = dict(zip(['one', 'two', 'three'], [1, 2, 3]))
>>> d = dict([('two', 2), ('one', 1), ('three', 3)])
>>> e = dict({'three': 3, 'one': 1, 'two': 2})
>>> f = dict({'one': 1, 'three': 3}, two=2)
>>> a == b == c == d == e == f
True

Si queremos definir claves con parámetros por nombre, como en el primer ejemplo, entonces los valores de clave solo puede ser cadenas de texto conteniendo identificadores de Python válidos. En los otros casos, se puede usar cualquier valor como clave.

Estas son las operaciones soportados por los diccionarios (Y que, por tanto, deberían ser soportados por los tipos de mapa personalizados):

list(d)

Retorna una lista de todas las claves usadas en el diccionario d.

len(d)

Retorna el número de elementos almacenados en el diccionario d.

d[key]

Retorna el elemento dentro de d almacenado bajo la clave key. Lanza una excepción de tipo KeyError si la clave key no se encuentra en el diccionario d.

Si una subclase de un diccionario define el método __missing__() y key no está presente, la operación d[key] llama a este método pasando como parámetro el valor de key. La operación d[key] o bien retorna un valor o lanza la excepción que sea retornada por la llamada a __missing__(key). Ninguna otra operación o método llama a __missing__(). Si el método __missing__() no está definido, se eleva KeyError. Si se define __missing__(), debe ser de forma obligatoria un método, no puede ser una variable de instancia:

>>> class Counter(dict):
...     def __missing__(self, key):
...         return 0
>>> c = Counter()
>>> c['red']
0
>>> c['red'] += 1
>>> c['red']
1

El ejemplo anterior muestra parte de la implementación de la clase collections.Counter. Otro ejemplo de uso del método __missing__ se puede encontrar en la clase collections.defaultdict.

d[key] = value

Asigna el valor value a d[key].

del d[key]

Elimina d[key] de d. Lanza una excepción KeyError si key no está en el mapa.

key in d

Retorna True si d tiene una entrada en la clave key, False en caso contrario.

key not in d

Equivale a not key in d.

iter(d)

Retorna un iterador que recorre todas las claves de un diccionario. Es una forma abreviada de iter(d.keys()).

clear()

Elimina todos los contenidos del diccionario.

copy()

Retorna una copia superficial del diccionario.

classmethod fromkeys(iterable[, value])

Crea un nuevo diccionario con las claves obtenidos a partir del iterable y con valor value.

El método fromkeys() es un método de clase que retorna un diccionario nuevo. El valor de value por defecto es None. Todos los valores harán referencia a una única instancia, por lo que en general no tiene sentido que value sea un objeto mutable, como una lista vacía. Para poder obtener valores diferentes, se puede usar mejor un diccionario por comprensión.

get(key[, default])

Retorna el elemento dentro de d almacenado bajo la clave key, si key está en el diccionario; si no, retorna default. El valor de default por defecto es None, por lo que esta función nunca lanza la excepción KeyError.

items()

Retorna una nueva vista de los contenidos del diccionario (Pares (key, value)). Vea documentación de los objetos vistas.

keys()

Retorna una nueva vista de las claves del diccionario. Véase la documentación de las vistas.

pop(key[, default])

Si key está en el diccionario, lo elimina del diccionario y retorna su valor; si no está, retorna default. Si no se especifica valor para default y la clave no se encuentra en el diccionario, se lanza la excepción KeyError.

popitem()

Elimina y retorna una pareja (key, value) del diccionario. Las parejas se retornan en el orden LIFO.

El método popitem() es útil para recorrer y a la vez vaciar un diccionario, un proceso usado a menudo en algoritmos de conjuntos. Si el diccionario está vacío, llamar a popitem() lanza la excepción KeyError.

Distinto en la versión 3.7: El orden LIFO ahora está garantizado. En versiones anteriores, el método popitem() retorna una pareja clave/valor arbitraria.

reversed(d)

Retorna un iterador que recorre las claves en orden inverso. Es una forma abreviada de reversed(d.keys()).

Nuevo en la versión 3.8.

setdefault(key[, default])

Si key está incluida en el diccionario, retorna el valor almacenado. Si no, inserta con la clave key el valor definido en default y retorna default. El valor por defecto de default es None.

update([other])

Actualiza el diccionario con las parejas clave/valor obtenidas de other, escribiendo encima de las claves existentes. retorna None.

El método update() acepta tanto un diccionario como un iterable que Retorna parejas de claves, valor (ya sea como tuplas o como otros iterables de longitud 2). Si se especifican parámetros por nombre, el diccionario se actualiza con esas combinaciones de clave y valor: d.update(red=1, blue=2).

values()

Retorna una nueva vista de los valores del diccionario. Véase la documentación sobre objetos vistas.

Una comparación de igualdad entre una vista dict.values() y otra siempre retornará False. Esto también pasa cuando se compara dict.values() consigo mismo:

>>> d = {'a': 1}
>>> d.values() == d.values()
False

d | other

Crea un nuevo diccionario con las claves y valores fusionados de d y other, por lo cual ambos deben ser diccionarios. Los valores de other tienen prioridad cuando d y other tienen claves compartidas.

Nuevo en la versión 3.9.

d |= other

Actualiza el diccionario d con las claves y valores de other, el cual podría ser ya sea un a mapping o un iterable de pares clave/valor. Los valores de other tienen prioridad cuando d y other tienen claves compartidas.

Nuevo en la versión 3.9.

Los diccionarios se consideran iguales si y solo si tienen el mismo conjunto de parejas (key, value) (Independiente de su orden). Los intentos de comparar usando los operadores “<”, “<=”, “>=”, “>” lanzan una excepción de tipo TypeError.

Los diccionarios mantiene de forma interna el orden de inserción. Actualizar una entrada no modifica ese orden. Las claves que vuelven a ser insertadas después de haber sido borradas se añaden al final.:

>>> d = {"one": 1, "two": 2, "three": 3, "four": 4}
>>> d
{'one': 1, 'two': 2, 'three': 3, 'four': 4}
>>> list(d)
['one', 'two', 'three', 'four']
>>> list(d.values())
[1, 2, 3, 4]
>>> d["one"] = 42
>>> d
{'one': 42, 'two': 2, 'three': 3, 'four': 4}
>>> del d["two"]
>>> d["two"] = None
>>> d
{'one': 42, 'three': 3, 'four': 4, 'two': None}

Distinto en la versión 3.7: Se garantiza que el orden del diccionario es el de inserción. Este comportamiento era un detalle de implementación en CPython desde la versión 3.6.

Tanto los diccionarios como las vistas basadas en diccionarios son reversibles:

>>> d = {"one": 1, "two": 2, "three": 3, "four": 4}
>>> d
{'one': 1, 'two': 2, 'three': 3, 'four': 4}
>>> list(reversed(d))
['four', 'three', 'two', 'one']
>>> list(reversed(d.values()))
[4, 3, 2, 1]
>>> list(reversed(d.items()))
[('four', 4), ('three', 3), ('two', 2), ('one', 1)]

Distinto en la versión 3.8: Los diccionarios son ahora reversibles.

Ver también

Se puede usar un objeto de tipo types.MappingProxyType para crear una vista de solo lectura de un objeto dict.

Objetos tipos vista de diccionario

Los objetos retornados por los métodos dict.keys(), dict.values() y dict.items() son objetos tipo vista o view. Estos objetos proporcionan una vista dinámica del contenido del diccionario, lo que significa que si el diccionario cambia, las vistas reflejan estos cambios.

Las vistas de un diccionario pueden ser iteradas para retornar sus datos respectivos, y soportan operaciones de comprobación de pertenencia:

len(dictview)

Retorna el número de entradas en un diccionario.

iter(dictview)

Retorna un iterador sobre las claves, valores o elementos (representados en forma de tuplas (key, value)) de un diccionario.

Las claves y los valores se iteran en orden de inserción. Esto permite la creación de parejas (value, key) usando la función zip(): pairs = zip(d.values(), d.keys()). Otra forma de crear la misma lista es pairs = [(v, k) for (k, v) in d.items()].

Iterar sobre un diccionario a la vez que se borran o añaden entradas puede lanzar una excepción de tipo RuntimeError, o puede provocar que no se iteren sobre todas las entradas.

Distinto en la versión 3.7: Se garantiza que el orden de los diccionarios es el de inserción.

x in dictview

Retorna True si x está incluido en las claves, los valores o los elementos del diccionario. En el último caso, x debe ser una tupla (key, value).

reversed(dictview)

Retorna un iterador inverso sobre las claves y valores del diccionario. El orden de la vista sera el inverso del orden de inserción.

Distinto en la versión 3.8: Las vistas de un diccionario no son reversibles.

Las vistas de claves son similares a conjuntos, dado que todas las claves deben ser únicas y hashables. Si todos los valores son también hashables, de forma que las parejas (key, value) son también únicas y hashables, entonces la vista items es también similar a un conjunto (La vista values no son consideradas similar a un conjunto porque las valores almacenados en el diccionario no tiene que ser únicos). Las vistas similares a conjuntos pueden usar todas las operaciones definidas en la clase abstracta collections.abc.Set, como por ejemplo ==, <, or ^.

Un ejemplo de uso de una vista de diccionario:

>>> dishes = {'eggs': 2, 'sausage': 1, 'bacon': 1, 'spam': 500}
>>> keys = dishes.keys()
>>> values = dishes.values()

>>> # iteration
>>> n = 0
>>> for val in values:
...     n += val
>>> print(n)
504

>>> # keys and values are iterated over in the same order (insertion order)
>>> list(keys)
['eggs', 'sausage', 'bacon', 'spam']
>>> list(values)
[2, 1, 1, 500]

>>> # view objects are dynamic and reflect dict changes
>>> del dishes['eggs']
>>> del dishes['sausage']
>>> list(keys)
['bacon', 'spam']

>>> # set operations
>>> keys & {'eggs', 'bacon', 'salad'}
{'bacon'}
>>> keys ^ {'sausage', 'juice'}
{'juice', 'sausage', 'bacon', 'spam'}

Tipos Gestores de Contexto

La expresión with de Python soporta el concepto de un contexto en tiempo de ejecución definido mediante un gestor de contexto. Para implementar esto, se permite al usuario crear clases para definir estos contextos definiendo dos métodos, uno a ejecutar ante de entrar del bloque de código y otro a ejecutar justo después de salir del mismo:

contextmanager.__enter__()

Entra en el contexto en tiempo de ejecución, y retorna o bien este objeto u otro relacionado con el contexto. El valor retornado por este método se vincula al identificador que viene tras la palabra clave as usada en la sentencia with que define el contexto.

Un ejemplo de gestor de contexto que se retorna a si mismo es un objeto de tipo file object. Los objetos de tipo File se retornan a si mismo en la llamada a __enter__(), lo que permite que open() sea usado como gestores de contexto en una sentencia with.

Un ejemplo de gestor de contexto que retorna otro objeto relacionado en el que define la función decimal.localcontext(). Este gestor define el contexto de uso en operaciones decimales a partir de una copia del contexto original, y retorna esa copia. De esta manera se puede cambiar el contexto decimal dentro del cuerpo del with sin afectar al código fuera del mismo.

contextmanager.__exit__(exc_type, exc_val, exc_tb)

Sale del contexto y retorna un indicador booleano que indica si se debe ignorar cualquier posible excepción que hubiera ocurrido dentro del mismo. Si se produce una excepción mientras se ejecutan las sentencias definidas en el cuerpo de la sentencia with, los parámetros de esta función contienen el tipo y valor de la excepción, así como la información relativa a la traza de ejecución. Si no se produce ninguna excepción, los tres parámetros valen None.

Si este método retorna un valor True, la sentencia with ignora la excepción y el flujo del programa continua con la primera sentencia inmediatamente después del cuerpo. En caso contrario la excepción producida continua propagándose después de que este método termine de ejecutarse. Cualquier excepción que pudieran producirse dentro de este método reemplaza a la excepción que se hubiera producido en el cuerpo del with.

La excepción pasada nunca debe volver a lanzarse explícitamente; en vez de eso, el método debería retornar un valor falso para indicar que el método ha terminado de ejecutarse sin problemas y que no se desea suprimir la excepción. Esto permite a los gestores de contexto detectar fácilmente si el método __exit__() ha podido terminar o no.

Python define varios gestores de contexto para facilitar la sincronía entre hilos, asegurarse del cierre de ficheros y otros objetos similares y para modificar de forma simple el contexto para las expresiones aritméticas con decimales.Los tipos específicos no se tratan especialmente fuera de su implementación del protocolo de administración de contexto.Ver el módulo contextlib para algunos ejemplos.

Python’s generators and the contextlib.contextmanager decorator provide a convenient way to implement these protocols. If a generator function is decorated with the contextlib.contextmanager decorator, it will return a context manager implementing the necessary __enter__() and __exit__() methods, rather than the iterator produced by an undecorated generator function.

Nótese que no hay una ranura específica para ninguno de estos métodos en la estructura usada para los objetos Python en el nivel de la API C. Objetos que quieran definir estos métodos deben implementarlos como métodos normales de Python. Comparado con la complejidad de definir un contexto en tiempo de ejecución, lo complejidad de una búsqueda simple en un diccionario es mínima.

Tipo Alias Genérico

GenericAlias objects are generally created by subscripting a class. They are most often used with container classes, such as list or dict. For example, list[int] is a GenericAlias object created by subscripting the list class with the argument int. GenericAlias objects are intended primarily for use with type annotations.

Nota

It is generally only possible to subscript a class if the class implements the special method __class_getitem__().

A GenericAlias object acts as a proxy for a generic type, implementing parameterized generics.

For a container class, the argument(s) supplied to a subscription of the class may indicate the type(s) of the elements an object contains. For example, set[bytes] can be used in type annotations to signify a set in which all the elements are of type bytes.

For a class which defines __class_getitem__() but is not a container, the argument(s) supplied to a subscription of the class will often indicate the return type(s) of one or more methods defined on an object. For example, regular expressions can be used on both the str data type and the bytes data type:

If x = re.search('foo', 'foo'), x will be a re.Match object where the return values of x.group(0) and x[0] will both be of type str. We can represent this kind of object in type annotations with the GenericAlias re.Match[str].

If y = re.search(b'bar', b'bar'), (note the b for bytes), y will also be an instance of re.Match, but the return values of y.group(0) and y[0] will both be of type bytes. In type annotations, we would represent this variety of re.Match objects with re.Match[bytes].

GenericAlias objects are instances of the class types.GenericAlias, which can also be used to create GenericAlias objects directly.

T[X, Y, ...]

Creates a GenericAlias representing a type T parameterized by types X, Y, and more depending on the T used. For example, a function expecting a list containing float elements:

def average(values: list[float]) -> float:
    return sum(values) / len(values)

Otro ejemplo para el mapping de objetos, usando un dict, el cual es un tipo genérico que espera dos parámetros de tipo que representan el tipo de la clave y el tipo del valor. En este ejemplo, la función espera un dict con claves de tipo str y valores de tipo int:

def send_post_request(url: str, body: dict[str, int]) -> None:
    ...

Las funciones integradas isinstance() y issubclass() no aceptan tipos GenericAlias como segundo argumento:

>>> isinstance([1, 2], list[str])
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: isinstance() argument 2 cannot be a parameterized generic

The Python runtime does not enforce type annotations. This extends to generic types and their type parameters. When creating a container object from a GenericAlias, the elements in the container are not checked against their type. For example, the following code is discouraged, but will run without errors:

>>> t = list[str]
>>> t([1, 2, 3])
[1, 2, 3]

Además, los tipos de los parámetros de tipos genéricos se borran durante la creación de objetos:

>>> t = list[str]
>>> type(t)
<class 'types.GenericAlias'>

>>> l = t()
>>> type(l)
<class 'list'>

Llamando a repr() o str() en un genérico se muestra el tipo parametrizado:

>>> repr(list[int])
'list[int]'

>>> str(list[int])
'list[int]'

The __getitem__() method of generic containers will raise an exception to disallow mistakes like dict[str][str]:

>>> dict[str][str]
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: There are no type variables left in dict[str]

However, such expressions are valid when type variables are used. The index must have as many elements as there are type variable items in the GenericAlias object’s __args__.

>>> from typing import TypeVar
>>> Y = TypeVar('Y')
>>> dict[str, Y][int]
dict[str, int]

Standard Generic Classes

The following standard library classes support parameterized generics. This list is non-exhaustive.

tuple

list

dict

set

frozenset

type

collections.deque

collections.defaultdict

collections.OrderedDict

collections.Counter

collections.ChainMap

collections.abc.Awaitable

collections.abc.Coroutine

collections.abc.AsyncIterable

collections.abc.AsyncIterator

collections.abc.AsyncGenerator

collections.abc.Iterable

collections.abc.Iterator

collections.abc.Generator

collections.abc.Reversible

collections.abc.Container

collections.abc.Collection

collections.abc.Callable

collections.abc.Set

collections.abc.MutableSet

collections.abc.Mapping

collections.abc.MutableMapping

collections.abc.Sequence

collections.abc.MutableSequence

collections.abc.ByteString

collections.abc.MappingView

collections.abc.KeysView

collections.abc.ItemsView

collections.abc.ValuesView

contextlib.AbstractContextManager

contextlib.AbstractAsyncContextManager

dataclasses.Field

functools.cached_property

functools.partialmethod

os.PathLike

queue.LifoQueue

queue.Queue

queue.PriorityQueue

queue.SimpleQueue

re.Pattern

re.Match

shelve.BsdDbShelf

shelve.DbfilenameShelf

shelve.Shelf

types.MappingProxyType

weakref.WeakKeyDictionary

weakref.WeakMethod

weakref.WeakSet

weakref.WeakValueDictionary

Special Attributes of GenericAlias objects

Todos los genéricos parametrizados implementan atributos especiales de solo lectura.

genericalias.__origin__

Este atributo apunta a la clase genérica no parametrizada:

>>> list[int].__origin__
<class 'list'>

genericalias.__args__

This attribute is a tuple (possibly of length 1) of generic types passed to the original __class_getitem__() of the generic class:

>>> dict[str, list[int]].__args__
(<class 'str'>, list[int])

genericalias.__parameters__

Este atributo es una tupla (posiblemente vacía) computada perezosamente con las variables de tipo únicas encontradas en __args__:

>>> from typing import TypeVar

>>> T = TypeVar('T')
>>> list[T].__parameters__
(~T,)

Ver también

PEP 484 [https://www.python.org/dev/peps/pep-0484] - Type Hints

Introducing Python’s framework for type annotations.

PEP 585 [https://www.python.org/dev/peps/pep-0585] - Type Hinting Generics In Standard Collections

Introducing the ability to natively parameterize standard-library classes, provided they implement the special class method __class_getitem__().

Genéricos, user-defined generics and typing.Generic

Documentation on how to implement generic classes that can be parameterized at runtime and understood by static type-checkers.

Nuevo en la versión 3.9.

Otros tipos predefinidos

El intérprete soporta otros tipos de objetos variados. La mayoría de ellos solo implementan una o dos operaciones.

Módulos

La única operación especial que implementan los módulos es el acceso como atributos: m.name, donde m es un módulo y name accede a un nombre definido en la tabla de símbolos del módulo m. También se puede asignar valores a los atributos de un módulo (Nótese que la sentencia import no es, estrictamente hablando, una operación del objeto de tipo módulo. La sentencia import foo no requiere la existencia de un módulo llamado foo, sino una definición (externa) de un módulo foo en alguna parte).

Un atributo especial de cada módulo es __dict__. Es un diccionario que contiene la tabla de símbolos del módulo. Cambiar el diccionario cambiará por tanto el contenido de la tabla de símbolos, pero no es posible realizar una asignación directa al atributo __dict__ (Se puede realizar una asignación como m.__dict__['a'] = 1, que define el valor de m.a como 1, pero no se puede hacer m.__dict__ = {}). No se recomiendo manipular los contenidos del atributo __dict__ directamente.

Los módulos incluidos en el intérprete se escriben así: <module 'sys' (built-in)>. Si se cargan desde un archivo, se escriben como <module 'os' from '/usr/local/lib/pythonX.Y/os.pyc'>.

Clases e instancias de clase

Véase Objetos, valores y tipos y Definiciones de clase para más información.

Funciones

Los objetos de tipo función se crean mediante definiciones de función. La única operación posible con un objeto de tipo función en llamarla: func(argument-list).

Hay dos tipos de funciones: Las funciones básicas o predefinidas y las funciones definidas por el usuario. Las dos soportan la misma operación (ser llamadas), pero la implementación es diferente, de ahí que se consideren de distintos tipo.

Véase Definiciones de funciones para más información.

Métodos

Los métodos son funciones que se llaman usando la notación de atributos. Hay de dos tipos: métodos básicos o predefinidos (Como el método append() en las listas) y métodos de instancia de clase. Los métodos básicos o predefinidos se describen junto con los tipos que los soportan.

Si se accede a un método (Una función definida dentro de un espacio de nombres de una clase) a través de una instancia,se obtiene un objeto especial, un método ligado (También llamado método de instancia). Cuando se llama, se añade automáticamente el parámetro self a la lista de parámetros. Los métodos ligados tienen dos atributos especiales de solo lectura: m.__self__ es el objeto sobre el que está operando el método, y m.__func__ es la función que implementa el método.

Al igual que los objetos de tipo función, los métodos ligados o de instancia soportan asignación de atributos arbitrarios. Sin embargo, como los atributos de los métodos se almacenan en la función subyacente (meth.__func__), definir cualquier atributo en métodos ligados está desaconsejado. Intentar asignar un atributo a un método produce que se lance una excepción de tipo AttributeError. Para poder definir un atributo a un método, este debe ser definido explícitamente en la función subyacente:

>>> class C:
...     def method(self):
...         pass
...
>>> c = C()
>>> c.method.whoami = 'my name is method'  # can't set on the method
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'method' object has no attribute 'whoami'
>>> c.method.__func__.whoami = 'my name is method'
>>> c.method.whoami
'my name is method'

Véase Jerarquía de tipos estándar para más información.

Objetos código

Los objetos de tipo código son usados por la implementación del lenguaje para representar código ejecutable «pseudo-compilado», como por ejemplo el cuerpo de una función. A diferencia de los objetos de tipo función, no contienen una referencia a un entorno global de ejecución. Los objetos de tipo código se pueden obtener usando la función básica compile() o se pueden extraer a partir de objetos de tipo función a través de su atributo __code__. Para más detalle véase el módulo code.

Accessing __code__ raises an auditing event object.__getattr__ with arguments obj and "__code__".

Un objeto de tipo código puede ser evaluado o ejecutando pasándolo como parámetros a las funciones básicas exec() o eval() (Que también aceptan código Python en forma de cadena de texto).

Véase Jerarquía de tipos estándar para más información.

Objetos Tipo

Los objetos de tipo Tipo (Type) representan a los distintos tipos de datos. El tipo de un objeto particular puede ser consultado usando la función básica type(). Los objetos Tipo no tienen ninguna operación especial. El módulo types define nombres para todos los tipos básicos definidos en la biblioteca estándar.

Los tipos se escriben de la siguiente forma: <class 'int'>.

El objeto nulo (Null)

Todas las funciones que no definen de forma explícita un valor de retorno retornan este objeto. Los objetos nulos no soportan ninguna operación especial. Solo existe un único objeto nulo, llamado None (Un nombre predefinido o básico). La expresión type(None)() produce el mismo objeto None, esto se conoce como Singleton.

Se escribe None.

El objeto puntos suspensivos (Ellipsis)

Este objeto es usado a menudo en operaciones de rebanadas (Véase Segmentos). No soporta ninguna operación especial. Solo existe un único objeto de puntos suspensivos, llamado Ellipsis (Un nombre predefinido o básico). La expresión type(Ellipsis)() produce el mismo objeto Ellipsis, esto se conoce como Singleton.

Se puede escribir como Ellipsis o ....

El objeto NotImplemented

Este objeto se retorna en todas las operaciones binarias y comparaciones cuando se intenta operar con tipos que no están soportados. Véase Comparaciones para más información. Solo existe un objeto de tipo NotImplemented. La expresión type(NotImplemented)() produce el mismo objeto, esto se conoce como Singleton.

Se escribe NotImplemented.

Valores booleanos

Los valores booleanos o lógicos son los dos objetos constantes False y True. Su usan para representar valores de verdad (Aunque otros valores pueden ser considerados también como verdaderos o falsos). En contextos numéricos (Por ejemplo, cuando se usan como argumentos de una operación aritmética) se comportan como los números enteros 0 y 1 respectivamente. Se puede usar la función incorporada bool() para convertir valores de cualquiera tipo a Booleanos, si dicho valor puede ser interpretado como valores verdaderos/falsos (Véase la sección Evaluar como valor verdadero/falso anterior).

Se escriben False y True respectivamente.

Objetos internos

Véase la sección Jerarquía de tipos estándar para saber más de estos objetos. Se describen los objetos marco de pila, los objetos de traza de ejecución (traceback) y los objetos de tipo rebanada (slice).

Atributos especiales

La implementación añade unos cuantos atributos de solo lectura a varios tipos de objetos, cuando resulta relevante. Algunos de estos atributos son reportados por la función incorporada dir().

object.__dict__

Un diccionario u otro tipo de mapa usado para almacenar los atributos de un objeto (Si son modificables).

instance.__class__

La clase a la que pertenece una instancia.

class.__bases__

La tupla de clases base de las que deriva una clase.

definition.__name__

El nombre de la clase, función, método, descriptor o instancia generadora.

definition.__qualname__

El nombre calificado (qualified name) de la clase, función, método, descriptor o instancia generadora.

Nuevo en la versión 3.3.

class.__mro__

Este atributo es una tupla de las clases que serán consideradas cuando se busque en las clases base para resolver un método.

class.mro()

Este método puede ser reescrito por una metaclase para personalizar el orden de resolución de métodos para sus instancias. Es llamado en la creación de la clase, y el resultado se almacena en el atributo __mro__.

class.__subclasses__()

Cada clase mantiene una lista de referencias débiles a sus subclase inmediatamente anteriores. Este método retorna una lista de todas las referencias que todavía estén vivas. La lista está en orden de definición. Por ejemplo:

>>> int.__subclasses__()
[<class 'bool'>]

Integer string conversion length limitation

CPython has a global limit for converting between int and str to mitigate denial of service attacks. This limit only applies to decimal or other non-power-of-two number bases. Hexadecimal, octal, and binary conversions are unlimited. The limit can be configured.

The int type in CPython is an arbitrary length number stored in binary form (commonly known as a «bignum»). There exists no algorithm that can convert a string to a binary integer or a binary integer to a string in linear time, unless the base is a power of 2. Even the best known algorithms for base 10 have sub-quadratic complexity. Converting a large value such as int('1' * 500_000) can take over a second on a fast CPU.

Limiting conversion size offers a practical way to avoid CVE-2020-10735 [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-10735].

The limit is applied to the number of digit characters in the input or output string when a non-linear conversion algorithm would be involved. Underscores and the sign are not counted towards the limit.

When an operation would exceed the limit, a ValueError is raised:

>>> import sys
>>> sys.set_int_max_str_digits(4300)  # Illustrative, this is the default.
>>> _ = int('2' * 5432)
Traceback (most recent call last):
...
ValueError: Exceeds the limit (4300) for integer string conversion: value has 5432 digits; use sys.set_int_max_str_digits() to increase the limit.
>>> i = int('2' * 4300)
>>> len(str(i))
4300
>>> i_squared = i*i
>>> len(str(i_squared))
Traceback (most recent call last):
...
ValueError: Exceeds the limit (4300) for integer string conversion: value has 8599 digits; use sys.set_int_max_str_digits() to increase the limit.
>>> len(hex(i_squared))
7144
>>> assert int(hex(i_squared), base=16) == i*i  # Hexadecimal is unlimited.

The default limit is 4300 digits as provided in sys.int_info.default_max_str_digits. The lowest limit that can be configured is 640 digits as provided in sys.int_info.str_digits_check_threshold.

Verification:

>>> import sys
>>> assert sys.int_info.default_max_str_digits == 4300, sys.int_info
>>> assert sys.int_info.str_digits_check_threshold == 640, sys.int_info
>>> msg = int('578966293710682886880994035146873798396722250538762761564'
...           '9252925514383915483333812743580549779436104706260696366600'
...           '571186405732').to_bytes(53, 'big')
...

Nuevo en la versión 3.9.14.

Affected APIs

The limitation only applies to potentially slow conversions between int and str or bytes:

int(string) with default base 10.

int(string, base) for all bases that are not a power of 2.

str(integer).

repr(integer).

any other string conversion to base 10, for example f"{integer}", "{}".format(integer), or b"%d" % integer.

The limitations do not apply to functions with a linear algorithm:

int(string, base) with base 2, 4, 8, 16, or 32.

int.from_bytes() and int.to_bytes().

hex(), oct(), bin().

Especificación de formato Mini-Lenguaje for hex, octal, and binary numbers.

str to float.

str to decimal.Decimal.

Configuring the limit

Before Python starts up you can use an environment variable or an interpreter command line flag to configure the limit:

PYTHONINTMAXSTRDIGITS, e.g. PYTHONINTMAXSTRDIGITS=640 python3 to set the limit to 640 or PYTHONINTMAXSTRDIGITS=0 python3 to disable the limitation.

-X int_max_str_digits, e.g. python3 -X int_max_str_digits=640

sys.flags.int_max_str_digits contains the value of PYTHONINTMAXSTRDIGITS or -X int_max_str_digits. If both the env var and the -X option are set, the -X option takes precedence. A value of -1 indicates that both were unset, thus a value of sys.int_info.default_max_str_digits was used during initialization.

From code, you can inspect the current limit and set a new one using these sys APIs:

sys.get_int_max_str_digits() and sys.set_int_max_str_digits() are a getter and setter for the interpreter-wide limit. Subinterpreters have their own limit.

Information about the default and minimum can be found in sys.int_info:

sys.int_info.default_max_str_digits is the compiled-in default limit.

sys.int_info.str_digits_check_threshold is the lowest accepted value for the limit (other than 0 which disables it).

Nuevo en la versión 3.9.14.

Prudencia

Setting a low limit can lead to problems. While rare, code exists that contains integer constants in decimal in their source that exceed the minimum threshold. A consequence of setting the limit is that Python source code containing decimal integer literals longer than the limit will encounter an error during parsing, usually at startup time or import time or even at installation time - anytime an up to date .pyc does not already exist for the code. A workaround for source that contains such large constants is to convert them to 0x hexadecimal form as it has no limit.

Test your application thoroughly if you use a low limit. Ensure your tests run with the limit set early via the environment or flag so that it applies during startup and even during any installation step that may invoke Python to precompile .py sources to .pyc files.

Recommended configuration

The default sys.int_info.default_max_str_digits is expected to be reasonable for most applications. If your application requires a different limit, set it from your main entry point using Python version agnostic code as these APIs were added in security patch releases in versions before 3.11.

Example:

>>> import sys
>>> if hasattr(sys, "set_int_max_str_digits"):
...     upper_bound = 68000
...     lower_bound = 4004
...     current_limit = sys.get_int_max_str_digits()
...     if current_limit == 0 or current_limit > upper_bound:
...         sys.set_int_max_str_digits(upper_bound)
...     elif current_limit < lower_bound:
...         sys.set_int_max_str_digits(lower_bound)

If you need to disable it entirely, set it to 0.

Notas al pie

1

Se puede consultar información adicional sobre estos métodos especiales en el Manual de Referencia de Python (Personalización básica).

2

En consecuencia, la lista [1, 2] se considera igual que [1.0, 2.0], y de forma similar para las tuplas.

3

Deben haberlo hecho, ya que el analizador no puede decir el tipo de operandos.

4(1,2,3,4)

Los caracteres con versiones mayúsculas/minúsculas son aquellos cuya categoría general corresponde con «Lu» (Letra, Mayúscula), «Ll» (Letra, minúscula) o «Lt» (Letra, titlecase).

5(1,2)

Para formatear solo una tupla se debe, por tanto, usar una tupla conteniendo un único elemento, que sería la tupla a ser formateada.

Excepciones incorporadas

En Python, todas las excepciones deben ser instancias de una clase que se derive de BaseException. En una instrucción try con una cláusula except que menciona una clase determinada, esa cláusula también controla las clases de excepción derivadas de esa clase (excepto las clases de excepción de las que se deriva it). Dos clases de excepción que no están relacionadas mediante subclases nunca son equivalentes, incluso si tienen el mismo nombre.

Las excepciones predefinidas enumeradas a continuación pueden ser generadas por el intérprete o funciones predefinidas. Excepto donde se mencione lo contrario, tienen un associated value que indica la causa detallada del error. Esto podría una cadena de caracteres o una tupla elementos con grandes elementos de información (por ejemplo, un código de error y una cadena que explica el código). El valor asociado generalmente se pasa como argumentos al constructor de la clase de excepción.

El código de usuario puede generar excepciones predefinidas. Esto puede ser usado para probar un gestor de excepciones o para notificar una condición de error «igual» a la situación en la cual el intérprete lance la misma excepción; pero tenga en cuenta que no hay nada que impida que el código del usuario produzca un error inapropiado.

Las clases de excepción predefinidas pueden ser usadas como subclases para definir otras nuevas; se recomienda a los programadores que deriven nuevas excepciones a partir de la clase Exception o de una de sus subclases, y no de BaseException. Hay disponible más información sobre la definición de excepciones en el Tutorial de Python en Excepciones definidas por el usuario.

Exception context

When raising a new exception while another exception is already being handled, the new exception’s __context__ attribute is automatically set to the handled exception. An exception may be handled when an except or finally clause, or a with statement, is used.

This implicit exception context can be supplemented with an explicit cause by using from with raise:

raise new_exc from original_exc

The expression following from must be an exception or None. It will be set as __cause__ on the raised exception. Setting __cause__ also implicitly sets the __suppress_context__ attribute to True, so that using raise new_exc from None effectively replaces the old exception with the new one for display purposes (e.g. converting KeyError to AttributeError), while leaving the old exception available in __context__ for introspection when debugging.

La visualización por defecto de la traza de error muestra estas excepciones encadenadas además de la traza de la propia excepción. Siempre se muestra una excepción encadenada explícitamente en __cause__ cuando está presente. Una excepción implícitamente encadenada en __context__ solo se muestra si __cause__ es None y __suppress_context__ es falso.

En cualquier caso, la excepción en sí siempre se muestra después de cualquier excepción encadenada para que la línea final del seguimiento siempre muestre la última excepción que se generó.

Inheriting from built-in exceptions

User code can create subclasses that inherit from an exception type. It’s recommended to only subclass one exception type at a time to avoid any possible conflicts between how the bases handle the args attribute, as well as due to possible memory layout incompatibilities.

CPython implementation detail: Most built-in exceptions are implemented in C for efficiency, see: Objects/exceptions.c [https://github.com/python/cpython/tree/3.9/Objects/exceptions.c]. Some have custom memory layouts which makes it impossible to create a subclass that inherits from multiple exception types. The memory layout of a type is an implementation detail and might change between Python versions, leading to new conflicts in the future. Therefore, it’s recommended to avoid subclassing multiple exception types altogether.

Clases base

Las siguientes excepciones se utilizan principalmente como clases base para otras excepciones.

exception BaseException

La clase base para todas las excepciones predefinidas. No está pensada para ser heredada directamente por las clases definidas por el usuario (para eso, use Exception). Si se llama a str() en una instancia de esta clase, se retorna la representación de los argumentos de la instancia o la cadena vacía cuando no había argumentos.

args

La tupla de argumentos dada al constructor de excepción. Algunas excepciones predefinidas (como OSError) esperan un cierto número de argumentos y asignan un significado especial a los elementos de esta tupla, mientras que otras normalmente se llaman solo con una sola cadena que da un mensaje de error.

with_traceback(tb)

Este método establece tb como el nuevo traceback para la excepción y retorna el objeto de excepción. Normalmente se utiliza en código de control de excepciones como este:

try:
    ...
except SomeException:
    tb = sys.exc_info()[2]
    raise OtherException(...).with_traceback(tb)

exception Exception

Todas las excepciones predefinidas non-system-exiting, que no salen del sistema se derivan de esta clase. Todas las excepciones definidas por el usuario también deben derivarse de esta clase.

exception ArithmeticError

La clase base para las excepciones predefinidas que se generan para varios errores aritméticos: OverflowError, ZeroDivisionError, FloatingPointError.

exception BufferError

Se genera cuando buffer no se puede realizar una operación relacionada.

exception LookupError

La clase base para las excepciones que se generan cuando una clave o índice utilizado en un mapa o secuencia que no es válido: IndexError, KeyError. Esto se puede generar directamente por codecs.lookup().

Excepciones específicas

Las siguientes excepciones son las excepciones que normalmente se generan.

exception AssertionError

Se genera cuando se produce un error en una instrucción assert.

exception AttributeError

Se genera cuando se produce un error en una referencia de atributo (ver Referencias de atributos) o la asignación falla. (Cuando un objeto no admite referencias de atributos o asignaciones de atributos en absoluto, se genera TypeError.)

exception EOFError

Se genera cuando la función input() alcanza una condición de fin de archivo (EOF) sin leer ningún dato. (Note que el io. IOBase.read() y io.IOBase.readline() retornan una cadena vacía cuando llegan a EOF.)

exception FloatingPointError

No se usa actualmente.

exception GeneratorExit

Se genera cuando un generator o coroutine está cerrado; ver generator.close() y coroutine.close(). Hereda directamente de BaseException en lugar de Exception ya que técnicamente no es un error.

exception ImportError

Se genera cuando la instrucción import tiene problemas al intentar cargar un módulo. También se produce cuando la from list en from ... import tiene un nombre que no se puede encontrar.

Los atributos name y path solo se pueden establecer utilizando argumentos de palabra clave en el constructor. Cuando se establece, representan el nombre del módulo que se intentó importar y la ruta de acceso a cualquier archivo que desencadenó la excepción, respectivamente.

Distinto en la versión 3.3: Se han añadido los atributos name y path.

exception ModuleNotFoundError

Una subclase de ImportError que se genera mediante import cuando no se pudo encontrar un módulo. También se genera cuando None se encuentra en sys.modules.

Nuevo en la versión 3.6.

exception IndexError

Se genera cuando un subíndice de secuencia está fuera del rango. (Los índices de la rebanada son truncados silenciosamente para caer en el intervalo permitido; si un índice no es un entero, se genera TypeError.)

exception KeyError

Se genera cuando no se encuentra una clave de asignación (diccionario) en el conjunto de claves existentes (mapa).

exception KeyboardInterrupt

Se genera cuando el usuario pulsa la tecla de interrupción (normalmente Control-C o Delete). Durante la ejecución, se realiza una comprobación de interrupciones con regularidad. La excepción hereda de BaseException para no ser detectada de forma accidental por Exception y, por lo tanto, prevenir que el intérprete salga.

Nota

Catching a KeyboardInterrupt requires special consideration. Because it can be raised at unpredictable points, it may, in some circumstances, leave the running program in an inconsistent state. It is generally best to allow KeyboardInterrupt to end the program as quickly as possible or avoid raising it entirely. (See Note on Signal Handlers and Exceptions.)

exception MemoryError

Se genera cuando una operación se queda sin memoria pero la situación aún puede ser recuperada (eliminando algunos objetos). El valor asociado es una cadena que indica que tipo de operación (interna) se quedó sin memoria. Tenga en cuenta que debido a la arquitectura de administración de memoria (función malloc() de C), el intérprete no siempre puede recuperarse completamente de esta situación; sin embargo, plantea una excepción para que se pueda imprimir un seguimiento de la pila, en caso de que un programa fuera de servicio fuera lo causa.

exception NameError

Se genera cuando no se encuentra un nombre local o global. Esto se aplica solo a nombres no calificados. El valor asociado es un mensaje de error que incluye el nombre que no se pudo encontrar.

exception NotImplementedError

Esta excepción se deriva de RuntimeError. En las clases base definidas por el usuario, los métodos abstractos deberían generar esta excepción cuando requieren clases derivadas para anular el método, o mientras se desarrolla la clase para indicar que la implementación real aún necesita ser agregada.

Nota

No debe usarse para indicar que un operador o método no debe ser admitido en absoluto – en ese caso, deje el operador / método sin definir o, si es una subclase, se establece en None.

Nota

NotImplementedError y NotImplemented no son intercambiables, a pesar de que tienen nombres y propósitos similares. Consulte NotImplemented para obtener detalles sobre cuándo usarlo.

exception OSError([arg])

exception OSError(errno, strerror[, filename[, winerror[, filename2]]])

Esta excepción se produce cuando una función del sistema retorna un error relacionado con el sistema, que incluye fallas de E/S como file not found o disk full (no para tipos de argumentos ilegales u otros errores incidentales).

La segunda forma del constructor establece los atributos correspondientes, que se describen a continuación. Los atributos predeterminados son None si no se especifican. Para compatibilidad con versiones anteriores, si se pasan tres argumentos, el atributo args contiene solo una tupla de 2 de los dos primeros argumentos del constructor.

El constructor a menudo retorna una subclase de OSError, como se describe en OS exceptions a continuación. La subclase particular depende del valor final errno. Este comportamiento solo ocurre cuando se construye OSError directamente o mediante un alias, y no se hereda al derivar.

errno

Un código de error numérico de la variable C, errno.

winerror

En Windows, esto le proporciona el código de error nativo de Windows. El atributo errno es entonces una traducción aproximada, en términos POSIX, de ese código de error nativo.

En Windows, si el argumento del constructor winerror es un entero, el atributo errno se determina a partir del código de error de Windows y el argumento errno se ignora. En otras plataformas, el argumento winerror se ignora y el atributo winerror no existe.

strerror

El mensaje de error correspondiente, tal como lo proporciona el sistema operativo. Está formateado por las funciones de C, perror() en POSIX, y FormatMessage() en Windows.

filename

filename2

Para las excepciones que involucran una ruta del sistema de archivos (como open() o os.unlink()), filename es el nombre del archivo pasado a la función. Para las funciones que involucran dos rutas del sistema de archivos (como os.rename()), filename2 corresponde al segundo nombre de archivo pasado a la función.

Distinto en la versión 3.3: EnvironmentError, IOError, WindowsError, socket.error, select.error y mmap.error se han fusionado en OSError, y el constructor puede retornar una subclase.

Distinto en la versión 3.4: El atributo filename es ahora el nombre del archivo original pasado a la función, en lugar del nombre codificado o descodificado de la codificación del sistema de archivos. Además, se agregó el argumento constructor filename2 y el atributo.

exception OverflowError

Se genera cuando el resultado de una operación aritmética es demasiado grande para ser representado. Esto no puede ocurrir para los enteros (para lo cual es mejor elevar MemoryError que darse por vencido). Sin embargo, por razones históricas, OverflowError a veces se genera para enteros que están fuera del rango requerido. Debido a la falta de estandarización del manejo de excepciones de coma flotante en C, la mayoría de las operaciones de coma flotante no se verifican.

exception RecursionError

Esta excepción se deriva de RuntimeError. Se eleva cuando el intérprete detecta que se excede la profundidad máxima de recursión (ver sys.getrecursionlimit()).

Nuevo en la versión 3.5: Anteriormente, se planteó un simple RuntimeError.

exception ReferenceError

Esta excepción se produce cuando un proxy de referencia débil, creado por la función weakref.proxy(), se utiliza para acceder a un atributo del referente después de que se ha recolectado basura. Para obtener más información sobre referencias débiles, consulte el módulo weakref .

exception RuntimeError

Se genera cuando se detecta un error que no corresponde a ninguna de las otras categorías. El valor asociado es una cadena que indica exactamente qué salió mal.

exception StopIteration

Generado por la función incorporada next() y un iterator’s __next__() para indicar que no hay más elementos producidos por el iterador.

El objeto de excepción tiene un solo atributo value, que se proporciona como argumento al construir la excepción, y por defecto es None.

Cuando se retorna una función generator o coroutine, se genera una nueva instancia StopIteration, y el valor retornado por la función se utiliza como parámetro value para constructor de la excepción.

Si un generador lanza directa o indirectamente StopIteration, se convierte en RuntimeError (conservando StopIteration como la causa de la nueva excepción).

Distinto en la versión 3.3: Se agregó el atributo *value* y la capacidad de las funciones del generador de usarlo para retornar un valor.

Distinto en la versión 3.5: Introdujo la transformación RuntimeError a través de from __future__ import generator_stop, ver PEP 479 [https://www.python.org/dev/peps/pep-0479].

Distinto en la versión 3.7: Habilitar PEP 479 [https://www.python.org/dev/peps/pep-0479] para todo el código por defecto: a StopIteration generado en un generador se transforma en RuntimeError.

exception StopAsyncIteration

Se debe generar mediante __anext__() de un objeto asynchronous iterator para detener la iteración.

Nuevo en la versión 3.5.

exception SyntaxError(message, details)

Raised when the parser encounters a syntax error. This may occur in an import statement, in a call to the built-in functions compile(), exec(), or eval(), or when reading the initial script or standard input (also interactively).

The str() of the exception instance returns only the error message. Details is a tuple whose members are also available as separate attributes.

filename

The name of the file the syntax error occurred in.

lineno

Which line number in the file the error occurred in. This is 1-indexed: the first line in the file has a lineno of 1.

offset

The column in the line where the error occurred. This is 1-indexed: the first character in the line has an offset of 1.

text

The source code text involved in the error.

For errors in f-string fields, the message is prefixed by «f-string: » and the offsets are offsets in a text constructed from the replacement expression. For example, compiling f’Bad {a b} field” results in this args attribute: (“f-string: …”, (“”, 1, 4, “(a b)n”)).

exception IndentationError

Clase base para errores de sintaxis relacionados con sangría incorrecta. Esta es una subclase de SyntaxError.

exception TabError

Se genera cuando la sangría contiene un uso inconsistente de pestañas y espacios. Esta es una subclase de IndentationError.

exception SystemError

Se genera cuando el intérprete encuentra un error interno, pero la situación no parece tan grave como para abandonar toda esperanza. El valor asociado es una cadena que indica qué salió mal (a bajo nivel).

Debe informar esto al autor o responsable de su intérprete de Python. Asegúrese de informar la versión del intérprete de Python (sys.version; también se imprime al comienzo de una sesión interactiva de Python), el mensaje de error exacto (el valor asociado de la excepción) y, si es posible, la fuente del programa que activó el error.

exception SystemExit

Esta excepción es provocada por la función sys.exit(). Hereda de BaseException en lugar de Exception para que no sea gestionada accidentalmente por el código que captura Exception. Esto permite que la excepción se propague correctamente y que el intérprete salga. Cuando no se maneja, el intérprete de Python sale; no se imprime el seguimiento de pila. El constructor acepta el mismo argumento opcional pasado a sys.exit(). Si el valor es un entero, especifica el estado de salida del sistema (se pasa a la función exit() de C); si es None, el estado de salida es cero; Si tiene otro tipo (como una cadena), se imprime el valor del objeto y el estado de salida es uno.

Una llamada sys.exit() se traduce en una excepción para que los gestores de limpieza (finally cláusulas de try) puedan ejecutarse, y para que un depurador pueda ejecutar un script sin correr el riesgo de perder el control. La función os._exit() se puede usar si es absolutamente necesario salir (por ejemplo, en el proceso secundario después de una llamada a os.fork()).

code

El estado de salida o mensaje de error que se pasa al constructor. (El valor predeterminado es None.)

exception TypeError

Se genera cuando una operación o función se aplica a un objeto de tipo inapropiado. El valor asociado es una cadena que proporciona detalles sobre la falta de coincidencia de tipos.

El código de usuario puede generar esta excepción para indicar que un intento de operación en un objeto no es compatible y no debe serlo. Si un objeto está destinado a soportar una operación dada pero aún no ha proporcionado una implementación, NotImplementedError es la excepción adecuada para generar.

Pasar argumentos del tipo incorrecto (por ejemplo, pasar a list cuando se espera un int) debería dar como resultado TypeError, pero pasar argumentos con el valor incorrecto (por ejemplo, un número fuera límites esperados) debería dar como resultado ValueError.

exception UnboundLocalError

Se genera cuando se hace referencia a una variable local en una función o método, pero no se ha vinculado ningún valor a esa variable. Esta es una subclase de NameError.

exception UnicodeError

Se genera cuando se produce un error de codificación o decodificación relacionado con Unicode. Es una subclase de ValueError.

UnicodeError tiene atributos que describen el error de codificación o decodificación. Por ejemplo, err.object[err.start:err.end] proporciona la entrada inválida particular en la que falló el códec.

encoding

El nombre de la codificación que provocó el error.

reason

Una cadena que describe el error de códec específico.

object

El objeto que el códec intentaba codificar o decodificar.

start

El primer índice de datos no válidos en object.

end

El índice después de los últimos datos no válidos en object.

exception UnicodeEncodeError

Se genera cuando se produce un error relacionado con Unicode durante la codificación. Es una subclase de UnicodeError.

exception UnicodeDecodeError

Se genera cuando se produce un error relacionado con Unicode durante la codificación. Es una subclase de UnicodeError.

exception UnicodeTranslateError

Se genera cuando se produce un error relacionado con Unicode durante la codificación. Es una subclase de UnicodeError.

exception ValueError

Se genera cuando una operación o función recibe un argumento que tiene el tipo correcto pero un valor inapropiado, y la situación no se describe con una excepción más precisa como IndexError.

exception ZeroDivisionError

Se genera cuando el segundo argumento de una operación de división o módulo es cero. El valor asociado es una cadena que indica el tipo de operandos y la operación.

Las siguientes excepciones se mantienen por compatibilidad con versiones anteriores; a partir de Python 3.3, son alias de OSError.

exception EnvironmentError

exception IOError

exception WindowsError

Solo disponible en Windows.

Excepciones del sistema operativo

Las siguientes excepciones son subclases de OSError, se generan según el código de error del sistema.

exception BlockingIOError

Raised when an operation would block on an object (e.g. socket) set for non-blocking operation. Corresponds to errno EAGAIN, EALREADY, EWOULDBLOCK and EINPROGRESS.

Además de los de OSError, BlockingIOError puede tener un atributo más:

characters_written

Un entero que contiene el número de caracteres escritos en la secuencia antes de que se bloquee. Este atributo está disponible cuando se utilizan las clases de E/S almacenadas en el modulo io.

exception ChildProcessError

Raised when an operation on a child process failed. Corresponds to errno ECHILD.

exception ConnectionError

Una clase base para problemas relacionados con la conexión.

Las subclases son BrokenPipeError, ConnectionAbortedError, ConnectionRefusedError y ConnectionResetError.

exception BrokenPipeError

A subclass of ConnectionError, raised when trying to write on a pipe while the other end has been closed, or trying to write on a socket which has been shutdown for writing. Corresponds to errno EPIPE and ESHUTDOWN.

exception ConnectionAbortedError

A subclass of ConnectionError, raised when a connection attempt is aborted by the peer. Corresponds to errno ECONNABORTED.

exception ConnectionRefusedError

A subclass of ConnectionError, raised when a connection attempt is refused by the peer. Corresponds to errno ECONNREFUSED.

exception ConnectionResetError

A subclass of ConnectionError, raised when a connection is reset by the peer. Corresponds to errno ECONNRESET.

exception FileExistsError

Raised when trying to create a file or directory which already exists. Corresponds to errno EEXIST.

exception FileNotFoundError

Raised when a file or directory is requested but doesn’t exist. Corresponds to errno ENOENT.

exception InterruptedError

Se genera cuando una llamada entrante interrumpe una llamada del sistema. Corresponde a errno EINTR.

Distinto en la versión 3.5: Python ahora vuelve a intentar las llamadas del sistema cuando una señal interrumpe un syscall, excepto si el gestor señala generar una excepción (ver PEP 475 [https://www.python.org/dev/peps/pep-0475] para la justificación), en lugar de lanzar InterruptedError.

exception IsADirectoryError

Raised when a file operation (such as os.remove()) is requested on a directory. Corresponds to errno EISDIR.

exception NotADirectoryError

Raised when a directory operation (such as os.listdir()) is requested on something which is not a directory. On most POSIX platforms, it may also be raised if an operation attempts to open or traverse a non-directory file as if it were a directory. Corresponds to errno ENOTDIR.

exception PermissionError

Raised when trying to run an operation without the adequate access rights - for example filesystem permissions. Corresponds to errno EACCES and EPERM.

exception ProcessLookupError

Raised when a given process doesn’t exist. Corresponds to errno ESRCH.

exception TimeoutError

Raised when a system function timed out at the system level. Corresponds to errno ETIMEDOUT.

Nuevo en la versión 3.3: Por lo anterior se agregaron las subclases OSError.

Ver también

PEP 3151 [https://www.python.org/dev/peps/pep-3151] - Reelaborando el sistema operativo y la jerarquía de excepciones E/S

Advertencias

Las siguientes excepciones se utilizan como categorías de advertencia; consulte la documentación de Categorías de advertencia para obtener más detalles.

exception Warning

Clase base para categorías de advertencia.

exception UserWarning

Clase base para advertencias generadas por código de usuario.

exception DeprecationWarning

Clase base para advertencias sobre características obsoletas cuando esas advertencias están destinadas a otros desarrolladores de Python.

Ignorado por los filtros de advertencia predeterminados, excepto en el módulo __main__ (PEP 565 [https://www.python.org/dev/peps/pep-0565]). Habilitando Modo Desarrollo de Python muestra esta advertencia.

The deprecation policy is described in PEP 387 [https://www.python.org/dev/peps/pep-0387].

exception PendingDeprecationWarning

Clase base para advertencias sobre características que están obsoletas y que se espera que sean obsoletas en el futuro, pero que no lo son en este momento.

Esta clase rara vez se usa para emitir una advertencia sobre una posible desaprobación próxima es inusual, y DeprecationWarning se prefiere para las desaprobaciones ya activas.

Ignorado por los filtros de advertencia predeterminados. Habilitando Modo Desarrollo de Python muestra esta advertencia.

The deprecation policy is described in PEP 387 [https://www.python.org/dev/peps/pep-0387].

exception SyntaxWarning

Clase base para advertencias sobre sintaxis dudosa.

exception RuntimeWarning

Clase base para advertencias sobre comportamiento dudoso en tiempo de ejecución.

exception FutureWarning

Clase base para advertencias sobre características en desuso cuando esas advertencias están destinadas a usuarios finales de aplicaciones escritas en Python.

exception ImportWarning

Clase base para advertencias sobre posibles errores en la importación de módulos.

Ignorado por los filtros de advertencia predeterminados. Habilitando Modo Desarrollo de Python muestra esta advertencia.

exception UnicodeWarning

Clase base para advertencias relacionadas con Unicode.

exception BytesWarning

Clase base para advertencias relacionadas con bytes y bytearray.

exception ResourceWarning

Clase base para advertencias relacionadas con el uso de recursos.

Ignorado por los filtros de advertencia predeterminados. Habilitando Modo Desarrollo de Python muestra esta advertencia.

Nuevo en la versión 3.2.

Jerarquía de excepción

La jerarquía de clases para las excepciones incorporadas es:

BaseException
 +-- SystemExit
 +-- KeyboardInterrupt
 +-- GeneratorExit
 +-- Exception
      +-- StopIteration
      +-- StopAsyncIteration
      +-- ArithmeticError
      |    +-- FloatingPointError
      |    +-- OverflowError
      |    +-- ZeroDivisionError
      +-- AssertionError
      +-- AttributeError
      +-- BufferError
      +-- EOFError
      +-- ImportError
      |    +-- ModuleNotFoundError
      +-- LookupError
      |    +-- IndexError
      |    +-- KeyError
      +-- MemoryError
      +-- NameError
      |    +-- UnboundLocalError
      +-- OSError
      |    +-- BlockingIOError
      |    +-- ChildProcessError
      |    +-- ConnectionError
      |    |    +-- BrokenPipeError
      |    |    +-- ConnectionAbortedError
      |    |    +-- ConnectionRefusedError
      |    |    +-- ConnectionResetError
      |    +-- FileExistsError
      |    +-- FileNotFoundError
      |    +-- InterruptedError
      |    +-- IsADirectoryError
      |    +-- NotADirectoryError
      |    +-- PermissionError
      |    +-- ProcessLookupError
      |    +-- TimeoutError
      +-- ReferenceError
      +-- RuntimeError
      |    +-- NotImplementedError
      |    +-- RecursionError
      +-- SyntaxError
      |    +-- IndentationError
      |         +-- TabError
      +-- SystemError
      +-- TypeError
      +-- ValueError
      |    +-- UnicodeError
      |         +-- UnicodeDecodeError
      |         +-- UnicodeEncodeError
      |         +-- UnicodeTranslateError
      +-- Warning
           +-- DeprecationWarning
           +-- PendingDeprecationWarning
           +-- RuntimeWarning
           +-- SyntaxWarning
           +-- UserWarning
           +-- FutureWarning
           +-- ImportWarning
           +-- UnicodeWarning
           +-- BytesWarning
           +-- ResourceWarning

Servicios de procesamiento de texto

Los módulos descritos en este capítulo proporcionan una amplia gama de operaciones de manipulación de cadenas de texto y otros servicios de procesamiento de texto.

El módulo codecs descrito en Servicios de datos binarios también es muy relevante para el procesamiento de texto. Además, consulta la documentación para el tipo string de Python en Cadenas de caracteres — str.

string — Operaciones comunes de cadena de caracteres

Constantes de cadenas

Formato de cadena de caracteres personalizado

Sintaxis de formateo de cadena

Especificación de formato Mini-Lenguaje

Ejemplos de formateo

Cadenas de plantillas

Funciones de ayuda

re — Operaciones con expresiones regulares

Sintaxis de expresiones regulares

Contenidos del módulo

Objetos expresión regular

Objetos de coincidencia

Ejemplos de expresiones regulares

Buscando un par

Simular scanf()

search() vs. match()

Haciendo una guía telefónica

Mungear texto

Encontrar todos los adverbios

Encontrar todos los adverbios y sus posiciones

Notación de cadena raw

Escribir un Tokenizador

difflib — Funciones auxiliares para calcular deltas

Objetos SequenceMatcher

SequenceMatcher Ejemplos

Objetos Differ

Ejemplo de Differ

Una interfaz de línea de comandos para difflib

textwrap — Envoltura y relleno de texto

unicodedata — Base de datos Unicode

stringprep — Preparación de cadenas de Internet

readline — Interfaz readline de GNU

Archivo de inicio

Búfer de línea

Archivo de historial

Lista del historial

Ganchos (hooks) de inicialización

Terminación

Ejemplo

rlcompleter — Función de completado para GNU readline

Objetos de Completado

string — Operaciones comunes de cadena de caracteres

Source code: Lib/string.py [https://github.com/python/cpython/tree/3.9/Lib/string.py]

Ver también

Cadenas de caracteres — str

Métodos de las cadenas de caracteres

Constantes de cadenas

Las constantes definidas en este módulo son:

string.ascii_letters

La concatenación de las constantes abajo descriptas ascii_lowercase y ascii_uppercase. Este valor es independiente de la configuración regional.

string.ascii_lowercase

Las letras minúsculas 'abcdefghijklmnopqrstuvwxyz'. Este valor es independiente de la configuración regional y no cambiará.

string.ascii_uppercase

Las letras mayúsculas 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'. Este valor es independiente de la configuración regional y no cambiará.

string.digits

La cadena '0123456789'.

string.hexdigits

La cadena '0123456789abcdefABCDEF'.

string.octdigits

La cadena de caracteres '01234567'.

string.punctuation

Cadena de caracteres ASCII que se consideran caracteres de puntuación en la configuración regional C: !" #$%&'()*+,-./:;<=>?@[\]^_`{|} ~.

string.printable

Cadena de caracteres ASCII que se consideran imprimibles. Esta es una combinación de digits, ascii_letters, punctuation, y whitespace.

string.whitespace

Una cadena cuyos caracteres ASCII se consideran todos espacios en blanco. Esto incluye los caracteres espacio, tabulador, salto de línea, retorno, salto de página y tabulador vertical.

Formato de cadena de caracteres personalizado

La clase cadena es una clase incorporada (built-in) que proporciona la capacidad de realizar sustituciones complejas de variables y formateo de valor a través del método format() descrito en PEP 3101 [https://www.python.org/dev/peps/pep-3101]. La clase Formatter del módulo string permite crear y personalizar sus propios comportamientos de formateo de cadena utilizando la misma implementación que el método integrado format().

class string.Formatter

La clase Formatter tiene los siguientes métodos públicos:

format(format_string, /, *args, **kwargs)

Método principal de la API. Recibe una cadena de formato y argumentos posicionales y de palabra clave arbitrarios. Es sólo un envoltorio que llama a vformat().

Distinto en la versión 3.7: Un argumento de cadena de formato ahora es solo posicional.

vformat(format_string, args, kwargs)

Esta función realiza es la que realmente hace el trabajo de formateo. Se expone como una función independiente para los casos en los que desea pasar un diccionario predefinido de argumentos, en lugar de desempaquetar y volver a empaquetar el diccionario como argumentos individuales mediante la sintaxis *args y **kwargs. vformat() hace el trabajo de dividir la cadena de formato en datos de caracteres y campos de reemplazo. Llama a los diversos métodos descritos a continuación.

Además de eso, la clase Formatter define varios métodos que se espera sean reemplazados por las subclases:

parse(format_string)

Itera sobre format_string y retorna un iterable de tuplas (literal_text, field_name, format_spec, conversion). Es usado por vformat() para dividir la cadena de caracteres en texto literal o en campos de reemplazo.

Los valores en la tupla representan conceptualmente un intervalo de texto literal seguido por un único campo de reemplazo. Si no hay ningún texto literal (lo cual puede darse si dos campos de reemplazo ocurren consecutivamente), literal_text será una cadena de caracteres de longitud cero. Si no hay ningún campo de reemplazo, los valores de field_name, format_spec y conversion serán None.

get_field(field_name, args, kwargs)

Dado un field_name retornado por parse() (véase arriba), el mismo es convertido a un objeto a formatear. retorna una tupla (obj, used_key). La versión por defecto toma cadenas de caracteres acorde a lo definido en PEP 3101 [https://www.python.org/dev/peps/pep-3101], tales como «0[name]» o «label.title». args y kwargs se pasan al método vformat(). El valor retornado used_key tiene el mismo significado que el parámetro key para get_value().

get_value(key, args, kwargs)

Recuperar un valor de campo determinado. El argumento key será un entero o una cadena de caracteres. Si es un entero, representa el índice del argumento posicional en args; si es una cadena, representa un argumento definido en kwargs.

El parámetro args se establece como lista de argumentos posicionales en vformat(), y el parámetro kwargs se establece como diccionario de argumentos de palabra clave.

Para nombres de campo compuesto, estas funciones son únicamente llamadas para el primer componente del campo. Los componentes que le siguen son tratados a través de operaciones normales de atributo e indexación.

Por ejemplo, la expresión de campo “0.name” haría que get_value() se llame con un argumento key igual a 0. El atributo “”name”” se buscará después del retorno de get_value() llamando a la función incorporada getattr().

Si el índice o la palabra clave hace referencia a un elemento que no existe, se debe generar un IndexError o un KeyError.

check_unused_args(used_args, args, kwargs)

Implementa el chequeo de argumentos no utilizados si así se desea. Los argumentos de esta función son el conjunto de todas las claves de argumento a las que se hizo referencia en la cadena de formato (enteros para argumentos posicionales y cadenas de caracteres para argumentos con nombre) y una referencia a los args y kwargs que se pasaron a vformat. El conjunto de args no utilizados se puede calcular a partir de estos parámetros. se asume que check_unused_args() genera una excepción si se produce un error en el chequeo.

format_field(value, format_spec)

format_field() simplemente llama a la función incorporada format(). El método se proporciona para que las subclases puedan sobrescribirlo.

convert_field(value, conversion)

Convierte el valor (retornado por get_field()) dado un tipo de conversión (tal como la tupla retornada por el método parse()). La versión por defecto entiende los tipos de conversión “s” (str), “r” (repr) y “a” (ascii).

Sintaxis de formateo de cadena

The str.format() method and the Formatter class share the same syntax for format strings (although in the case of Formatter, subclasses can define their own format string syntax). The syntax is related to that of formatted string literals, but it is less sophisticated and, in particular, does not support arbitrary expressions.

Las cadenas de caracteres de formato contienen «campos de reemplazo» rodeados de llaves {}. Todo lo que no está contenido entre llaves se considera texto literal, que se copia sin cambios en la salida. Si se necesita incluir un carácter de llave en el texto literal, se puede escapar duplicando: {{ and }}.

La gramática para un campo de reemplazo es la siguiente:

replacement_field ::=  "{" [field_name] ["!" conversion] [":" format_spec] "}"
field_name        ::=  arg_name ("." attribute_name | "[" element_index "]")*
arg_name          ::=  [identifier | digit+]
attribute_name    ::=  identifier
element_index     ::=  digit+ | index_string
index_string      ::=  <any source character except "]"> +
conversion        ::=  "r" | "s" | "a"
format_spec       ::=  <described in the next section>

En términos menos formales, el campo de reemplazo puede comenzar con un field_name (nombre de campo) que especifica el objeto cuyo valor se va a formatear e insertar en la salida en lugar del campo de reemplazo. El nombre de campo (field_name) va seguido opcionalmente de un campo conversion (conversión), que va precedido de un signo de exclamación '!', y un format_spec, que va precedido de dos puntos ':'. Estos especifican un formato no predeterminado para el valor de reemplazo.

Véase también la sección Especificación de formato Mini-Lenguaje.

El field_name (nombre de campo) comienza con un arg_name que es un número o una palabra clave. Si es un número, hace referencia a un argumento posicional y, si es una palabra clave, hace referencia a un argumento de palabra clave. Si los arg_names numéricos en una cadena de caracteres de formato son una secuencia como 0, 1, 2, …, todos pueden ser omitidos (no sólo algunos) y los números 0, 1, 2, … se insertarán automáticamente en ese orden. Dado que arg_name no está delimitado por comillas, no es posible especificar claves de diccionario arbitrarias (por ejemplo, las cadenas '10' or ':-]') dentro de una cadena de caracteres de formato. El arg_name puede ir seguido de cualquier número de expresiones de índice o atributo. Una expresión con forma '.name' selecciona el atributo con nombre mediante getattr(), mientras que una expresión con forma '[index]' realiza una búsqueda de índice mediante __getitem__().

Distinto en la versión 3.1: Los especificadores de argumentos posicionales pueden ser omitidos en str.format(), así '{} {}'.format(a, b) es equivalente a '{0} {1}'.format(a, b).

Distinto en la versión 3.4: Para la clase Formatter, los especificadores de argumento posicional pueden ser omitidos.

Algunos ejemplos simples de cadena de formato:

"First, thou shalt count to {0}"  # References first positional argument
"Bring me a {}"                   # Implicitly references the first positional argument
"From {} to {}"                   # Same as "From {0} to {1}"
"My quest is {name}"              # References keyword argument 'name'
"Weight in tons {0.weight}"       # 'weight' attribute of first positional arg
"Units destroyed: {players[0]}"   # First element of keyword argument 'players'.

El campo conversion causa una coerción de tipo antes del formateo. Normalmente, el formateo es hecho el método __format__() del valor mismo. Sin embargo, en algunos es deseable forzar el tipo a ser formateado como una cadena de caracteres, sobrescribiendo su propia definición de formateo. Cuando se convierte el valor a una cadena de caracteres antes de llamar al método __format__(), la lógica normal de formateo es evitada.

Tres banderas de conversión son admitidas actualmente: '!s', que llama a str() con el valor; '!r', que llama a repr(); y '!a' que llama a ascii().

Algunos ejemplos:

"Harold's a clever {0!s}"        # Calls str() on the argument first
"Bring out the holy {name!r}"    # Calls repr() on the argument first
"More {!a}"                      # Calls ascii() on the argument first

El campo format_spec contiene la especificación de cómo presentar el valor, incluyendo detalles como ancho del campo, alineación, relleno, precisión decimal, etc. Cada tipo de valor puede definir su propio «mini lenguaje de formateo» o interpretación de format_spec.

La mayoría de los tipos integrados admiten un formateo común de mini-idioma descrito en la siguiente sección.

Un campo format_spec también puede incluir campos de reemplazo anidados dentro de él. Estos campos de reemplazo anidados pueden contener un nombre de campo, una bandera de conversión y una especificación de formato, pero no se permite anidamiento más profundo. Los campos de reemplazo dentro de format_spec se sustituyen antes de que la cadena format_spec se interprete. Esto permite especificar dinámicamente el formato de un valor.

Para más ejemplos, véase la sección Ejemplos de formateo.

Especificación de formato Mini-Lenguaje

Las «especificaciones de formato» son usadas dentro de campos de reemplazo contenidos en una cadena de formateo para definir como se presentan los valores individuales (véase Sintaxis de formateo de cadena y Literales de cadena formateados). Los mismos pueden también ser pasados directamente a la función incorporada format(). Cada tipo formateable puede definir cómo interpretar la especificación de formato.

La mayoría de los tipos integrados implementan las siguientes opciones para especificaciones de formato, aunque algunas de las opciones de formateo sólo son posibles con los tipos numéricos.

Una convención general es que una especificación de formato vacía produce el mismo resultado que llamar a la función str() con el valor. Una especificación no vacía típicamente modifica el resultado.

La forma general de un especificador estándar de formato es:

format_spec     ::=  [[fill]align][sign][#][0][width][grouping_option][.precision][type]
fill            ::=  <any character>
align           ::=  "<" | ">" | "=" | "^"
sign            ::=  "+" | "-" | " "
width           ::=  digit+
grouping_option ::=  "_" | ","
precision       ::=  digit+
type            ::=  "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"

Si se especifica un valor align válido, puede ir precedido por un carácter fill, que puede ser cualquier carácter y cuyo valor predeterminado es un espacio si se omite. No es posible utilizar una llave literal (»{» or «}») como el carácter fill en un formato literal de cadena o cuando se utiliza el método str.format(). Sin embargo, es posible insertar una llave con un campo de reemplazo anidado. Esta limitación no afecta a la función format().

El significado de las distintas opciones de alineación es el siguiente:

Opción

Significado

'<'

Fuerza el campo a ser alineado a la izquierda dentro del espacio disponible (éste es el comportamiento por defecto para la mayoría de los objetos).

'>'

Fuerza el campo a ser alineado a la derecha dentro del espacio disponible (éste es el comportamiento por defecto para números).

'='

Fuerza el relleno a ser colocarlo después del signo (si existe) pero antes de los dígitos. Esto se utiliza para imprimir campos con el formato “+000000120”. Esta opción de alineación solo es válida para tipos numéricos. Se convierte en el valor predeterminado cuando “0” precede inmediatamente al ancho del campo.

'^'

Fuerza el centrado del campo dentro del espacio disponible.

Notar que, a menos que se defina un ancho de campo mínimo, el ancho del campo siempre tendrá el mismo tamaño que los datos para rellenarlo, de modo que la opción de alineación no tiene ningún significado en este caso.

La opción sign (signo) sólo es válida para los tipos numéricos y puede ser una de las siguientes:

Opción

Significado

'+'

indica que el signo debe ser usado tanto para los números positivos como negativos.

'-'

indica que el signo debe ser usado sólo para números negativos (éste es el comportamiento por defecto).

espacio

indica que el espacio inicial debe ser usado para números positivos y el signo menos para números negativos.

The '#' option causes the «alternate form» to be used for the conversion. The alternate form is defined differently for different types. This option is only valid for integer, float and complex types. For integers, when binary, octal, or hexadecimal output is used, this option adds the respective prefix '0b', '0o', '0x', or '0X' to the output value. For float and complex the alternate form causes the result of the conversion to always contain a decimal-point character, even if no digits follow it. Normally, a decimal-point character appears in the result of these conversions only if a digit follows it. In addition, for 'g' and 'G' conversions, trailing zeros are not removed from the result.

La opción ',' señala el uso de una coma como separador de miles. En cambio, para un separador consciente de localización (local aware), usar el tipo de presentación de enteros 'n'.

Distinto en la versión 3.1: Se agregó la opción ',' (véase también PEP 378 [https://www.python.org/dev/peps/pep-0378]).

La opción '_' señaliza el uso del guión bajo como separador de miles para tipos de presentación de punto flotante y para tipos de presentación de enteros 'd'. Para los tipos de presentación de enteros 'b', 'o', 'x' y 'X', el guión bajo se insertará cada 4 dígitos. Para otros tipos de presentación, especificar esta opción es un error.

Distinto en la versión 3.6: Se agregó la opción '_' (véase también PEP 515 [https://www.python.org/dev/peps/pep-0515]).

width es un entero decimal que define el ancho total de campo mínimo, incluyendo prefijos, separadores y otros caracteres de formateo. Si no se especifica, el ancho de campo será determinado por el contenido.

Cuando no se proporciona ninguna alineación explícita, si el campo width es precedido por un carácter cero ('0'), se habilita el relleno cero con reconocimiento de signos para los tipos numéricos. Esto equivale a un carácter fill de '0' con un tipo de alignment de '='.

The precision is a decimal integer indicating how many digits should be displayed after the decimal point for presentation types 'f' and 'F', or before and after the decimal point for presentation types 'g' or 'G'. For string presentation types the field indicates the maximum field size - in other words, how many characters will be used from the field content. The precision is not allowed for integer presentation types.

Finalmente, type (el tipo) determina como presentar los datos.

Los tipos de presentación cadena disponibles son:

Tipo

Significado

's'

Formato de cadena de caracteres. Éste es el tipo por defecto y puede ser omitido.

None

Lo mismo que 's'.

Los tipos disponibles para la presentación de enteros son:

Tipo

Significado

'b'

Formato binario. retorna el número en base 2.

'c'

Carácter. Convierte el entero en el carácter unicode correspondiente antes de imprimirlo.

'd'

Decimal entero. retorna el número en base 10.

'o'

Formato octal. retorna el número en base 8.

'x'

Formato hexadecimal. retorna el número en base 16, utilizando letras minúsculas para los dígitos superiores a 9.

'X'

Hex format. Outputs the number in base 16, using upper-case letters for the digits above 9. In case '#' is specified, the prefix '0x' will be upper-cased to '0X' as well.

'n'

Número. Es lo mismo que 'd', excepto que usa la configuración regional actual para insertar el número apropiado de caracteres separadores.

None

Lo mismo que 'd'.

Además de los tipos de presentación arriba expuestos, los enteros se pueden formatear con los tipos de presentación de punto flotante enumerados a continuación (excepto 'n'``y ``None). Al hacerlo, float() se utiliza para convertir el entero en un número de punto flotante antes de ser formateado.

Los tipos de presentación disponibles para valores float y Decimal son:

Tipo

Significado

'e'

Notación científica. Para una precisión dada p, formatea el número en notación científica con la letra e separando el coeficiente del exponente. El coeficiente tiene un dígito antes, y p dígitos después, del punto decimal, para un total de p + 1 dígitos significativos. Cuando se no da una precisión, usa una precisión de 6 dígitos después del punto decimal para float, y muestra todos los dígitos del coeficiente para Decimal. Si no hay dígitos después del punto decimal, el punto decimal también es removido a no ser que se use la opción #.

'E'

Notación científica. Igual que 'e' excepto que utiliza una “E” mayúscula como carácter separador.

'f'

Notación de punto fijo. Para una precisión dada p, formatea el número como un valor decimal con exactamente p dígitos siguiendo el punto decimal. Cuando no se da una precisión, usa una precisión de 6 dígitos después del punto decimal para float, y usa una precisión tan grande como sea necesaria para mostrar todos los dígitos del coeficiente para Decimal. Si no hay dígitos después del punto decimal, el punto decimal también es removido a no ser que se use la opción #.

'F'

Notación de punto fijo. Igual que 'f', pero convierte (nulos) nan a NAN e inf a INF.

'g'

Formato general. Para una precisión dada p >= 1, redondea el número a p dígitos significativos y luego formatea el resultado como formato de punto fijo o en notación científica, dependiendo de su magnitud. Una precisión de 0 es tratada como equivalente a una precisión de 1.

Las reglas precisas son las siguientes: supongamos que el resultado formateado con el tipo de presentación 'e' y la precisión p-1 tiene exponente exp. Entonces, si m <= exp < p, donde m es -4 para floats y -6 para Decimals, el número se formatea con el tipo de presentación 'f' y la precisión p-1-exp. De lo contrario, el número se formatea con el tipo de presentación 'e' y precisión p-1. En ambos casos, los ceros finales insignificantes se eliminan del significado, y el punto decimal también se elimina si no hay dígitos restantes que lo sigan, a menos que se utilice la opción '#'.

Si no se da una precisión, usa una precisión de 6 dígitos significativos para float. Para Decimal el coeficiente del resultado se construye usando los dígitos del coeficiente del valor; se usa notación científica para valores menores a 1e-6 en valor absoluto y valores donde el valor posicional del dígito menos significativo es mayor a 1, de otra forma se usa notación de punto fijo.

Infinito positivo y negativo, cero positivo y negativo, y nulos (nans) son respectivamente formateados como inf, -inf, 0, -0 y nan, independientemente de la precisión.

'G'

Formato general. Igual que 'g' excepto que cambia a 'E' si el número se vuelve muy grande. Las representaciones de infinito y NaN también se convierten a mayúsculas.

'n'

Número. Es lo mismo que 'g', excepto que usa la configuración local para insertar los caracteres separadores de número apropiados.

'%'

Porcentaje. Multiplica el número por 100 y lo muestra en formato fijo ('f') seguido del signo porcentaje.

None

Para float esto es lo mismo que 'g', excepto que cuando se usa notación de punto fijo para formatear el resultado, siempre incluye al menos un dígito pasado el punto decimal. La precisión usada es tan larga como sea necesaria para representar el valor dado fielmente.

Para Decimal, esto es lo mismo que 'g' o 'G' dependiendo del valor de context.capitals para el contexto decimal actual.

El efecto general es el de igualar la salida de str() al ser alterada por los otros modificadores de formato.

Ejemplos de formateo

Esta sección contiene ejemplos de la sintaxis str.format() y comparaciones con el antiguo método de formateo usando %.

En la mayoría de los casos, la sintaxis es similar al antiguo formato %, con la adición de {} y con : utilizado en lugar de %. Por ejemplo, '%03.2f' puede ser traducido como '{:03.2f}'.

La nueva sintaxis de formato también soporta opciones diferentes y nuevas que se muestran en los ejemplos siguientes.

Accediendo argumentos por posición:

>>> '{0}, {1}, {2}'.format('a', 'b', 'c')
'a, b, c'
>>> '{}, {}, {}'.format('a', 'b', 'c')  # 3.1+ only
'a, b, c'
>>> '{2}, {1}, {0}'.format('a', 'b', 'c')
'c, b, a'
>>> '{2}, {1}, {0}'.format(*'abc')      # unpacking argument sequence
'c, b, a'
>>> '{0}{1}{0}'.format('abra', 'cad')   # arguments' indices can be repeated
'abracadabra'

Accediendo argumentos por nombre:

>>> 'Coordinates: {latitude}, {longitude}'.format(latitude='37.24N', longitude='-115.81W')
'Coordinates: 37.24N, -115.81W'
>>> coord = {'latitude': '37.24N', 'longitude': '-115.81W'}
>>> 'Coordinates: {latitude}, {longitude}'.format(**coord)
'Coordinates: 37.24N, -115.81W'

Accediendo los atributos de los argumentos:

>>> c = 3-5j
>>> ('The complex number {0} is formed from the real part {0.real} '
...  'and the imaginary part {0.imag}.').format(c)
'The complex number (3-5j) is formed from the real part 3.0 and the imaginary part -5.0.'
>>> class Point:
...     def __init__(self, x, y):
...         self.x, self.y = x, y
...     def __str__(self):
...         return 'Point({self.x}, {self.y})'.format(self=self)
...
>>> str(Point(4, 2))
'Point(4, 2)'

Accediendo ítems de los argumentos:

>>> coord = (3, 5)
>>> 'X: {0[0]};  Y: {0[1]}'.format(coord)
'X: 3;  Y: 5'

Reemplazar %s y %r:

>>> "repr() shows quotes: {!r}; str() doesn't: {!s}".format('test1', 'test2')
"repr() shows quotes: 'test1'; str() doesn't: test2"

Alinear el texto y especificar el ancho:

>>> '{:<30}'.format('left aligned')
'left aligned                  '
>>> '{:>30}'.format('right aligned')
'                 right aligned'
>>> '{:^30}'.format('centered')
'           centered           '
>>> '{:*^30}'.format('centered')  # use '*' as a fill char
'***********centered***********'

Reemplazar %+f, %-f, y % f y especificar el signo:

>>> '{:+f}; {:+f}'.format(3.14, -3.14)  # show it always
'+3.140000; -3.140000'
>>> '{: f}; {: f}'.format(3.14, -3.14)  # show a space for positive numbers
' 3.140000; -3.140000'
>>> '{:-f}; {:-f}'.format(3.14, -3.14)  # show only the minus -- same as '{:f}; {:f}'
'3.140000; -3.140000'

Reemplazando %x y %o y convirtiendo el valor a diferentes bases:

>>> # format also supports binary numbers
>>> "int: {0:d};  hex: {0:x};  oct: {0:o};  bin: {0:b}".format(42)
'int: 42;  hex: 2a;  oct: 52;  bin: 101010'
>>> # with 0x, 0o, or 0b as prefix:
>>> "int: {0:d};  hex: {0:#x};  oct: {0:#o};  bin: {0:#b}".format(42)
'int: 42;  hex: 0x2a;  oct: 0o52;  bin: 0b101010'

Usando la coma como separador de los miles:

>>> '{:,}'.format(1234567890)
'1,234,567,890'

Expresar un porcentaje:

>>> points = 19
>>> total = 22
>>> 'Correct answers: {:.2%}'.format(points/total)
'Correct answers: 86.36%'

Uso del formateo específico de tipo:

>>> import datetime
>>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)
>>> '{:%Y-%m-%d %H:%M:%S}'.format(d)
'2010-07-04 12:15:58'

Anidando argumentos y ejemplos más complejos:

>>> for align, text in zip('<^>', ['left', 'center', 'right']):
...     '{0:{fill}{align}16}'.format(text, fill=align, align=align)
...
'left<<<<<<<<<<<<'
'^^^^^center^^^^^'
'>>>>>>>>>>>right'
>>>
>>> octets = [192, 168, 0, 1]
>>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets)
'C0A80001'
>>> int(_, 16)
3232235521
>>>
>>> width = 5
>>> for num in range(5,12):
...     for base in 'dXob':
...         print('{0:{width}{base}}'.format(num, base=base, width=width), end=' ')
...     print()
...
    5     5     5   101
    6     6     6   110
    7     7     7   111
    8     8    10  1000
    9     9    11  1001
   10     A    12  1010
   11     B    13  1011

Cadenas de plantillas

Las cadenas de caracteres de plantilla proporcionan sustituciones de cadenas más sencillas como se describe en PEP 292 [https://www.python.org/dev/peps/pep-0292]. Un caso de uso principal para las cadenas de plantilla es la internacionalización (i18n) ya que en ese contexto, la sintaxis y la funcionalidad más sencillas hacen la traducción más fácil que otras instalaciones de formato de cadena integradas en Python. Como ejemplo de una biblioteca creada sobre cadenas de caracteres de plantilla para i18n, véase el paquete flufl.i18n [http://flufli18n.readthedocs.io/en/latest/].

Las cadenas de caracteres de plantilla admiten sustituciones basadas en $ de acuerdo a las siguientes reglas:

$$ es un escape. Es reemplazado con un único $.

$identifier (identificador) nombra un comodín de sustitución que coincide con una clave de asignación de "identifier" (identificador). De forma predeterminada, "identifier" está restringido a cualquier cadena alfanumérica ASCII (insensible a mayúsculas/minúsculas e incluyendo los guiones bajos) que comience con un guión bajo o una letra ASCII. El primer carácter no identificador después del carácter $ termina esta especificación de comodín.

${*identifier*} (identificador) es equivalente a $identifier. Es requerido cuando caracteres identificadores válidos siguen al comodín pero no son parte de él, por ejemplo "${noun}ification".

Cualquier otra aparición de $ en la cadena de caracteres resultará en una excepción ValueError.

El módulo string provee una clase Template que implementa esas reglas. Los métodos de Template son:

class string.Template(template)

El constructor sólo lleva un argumento, la cadena plantilla.

substitute(mapping={}, /, **kwds)

Realiza la sustitución de plantilla y retorna una nueva cadena de caracteres. mapping (mapeo) es un objeto tipo diccionario con claves (keys) que coinciden con los placeholders (comodines) de la plantilla. Como alternativa, es posible pasar argumentos de palabra clave cuyas palabras clave son los placeholders (comodines). Cuando mapping y kwds son dados y hay elementos duplicados, los placeholders (comodines) de kwds tienen prioridad.

safe_substitute(mapping={}, /, **kwds)

Igual que substitute(), excepto que si faltan comodines de mapping y kwds, en lugar de generar una excepción KeyError, el comodín original aparecerá en la cadena de caracteres resultante intacta. Además, a diferencia de substitute(), cualquier otra aparición de $ simplemente retornará $ en lugar de generar ValueError.

Mientras que otras excepciones aún pueden ocurrir, este método es llamado «seguro» (safe) porque siempre intenta retornar una cadena de caracteres que pueda ser usada en lugar de levantar una excepción. Desde otro punto de vista, el método safe_substitute() es en realidad para nada seguro, dado que ignorará plantillas defectuosas con delimitadores colgados, llaves sin cerrar, o comodines que no son identificadores válidos en Python.

Las instancias de Template también proporcionan un atributo de datos públicos:

template

Éste es el objeto que se le pasa como argumento template al constructor. En general, no debería ser modificado, pero el acceso de sólo lectura (read-only) no es impuesto.

Aquí un ejemplo de cómo usar una plantilla (Template):

>>> from string import Template
>>> s = Template('$who likes $what')
>>> s.substitute(who='tim', what='kung pao')
'tim likes kung pao'
>>> d = dict(who='tim')
>>> Template('Give $who $100').substitute(d)
Traceback (most recent call last):
...
ValueError: Invalid placeholder in string: line 1, col 11
>>> Template('$who likes $what').substitute(d)
Traceback (most recent call last):
...
KeyError: 'what'
>>> Template('$who likes $what').safe_substitute(d)
'tim likes $what'

Uso avanzado: es posible derivar subclases de Template para personalizar la sintaxis de placeholder, caracteres de delimitación, o bien la expresión regular entera usada para procesar cadenas de plantillas. Para ello, es posible sobrescribir los siguientes atributos de clase:

delimiter: es la cadena de caracteres literal que describe al delimitador que introduce un comodín. El valor predeterminado es $. Notar que esto no debe ser una expresión regular, ya que la implementación llamará a re.escape() en esta cadena de caracteres según sea necesario. Tener en cuenta además, que se no puede cambiar el delimitador después haber creado la clase (es decir, se debe establecer un delimitador diferente en el espacio de nombres de la subclase).

idpattern – Esta es la expresión regular que describe el patrón para comodines fuera de las llaves. El valor predeterminado es la expresión regular (?a:[_a-z][_a-z0-9]*). Si se proporciona este argumento y braceidpattern es None este patrón también se aplicará a los comodines entre llaves.

Nota

Dado que el valor predeterminado de flags es re.IGNORECASE, el patrón [a-z] puede coincidir con algunos caracteres que no son ASCII. Por ello se utiliza aquí la bandera local a.

Distinto en la versión 3.7: braceidpattern puede ser usado para definir patrones separados, usados dentro y fuera de los corchetes.

braceidpattern – Es como idpattern pero describe el patrón para comodines entre llaves. El valor por defecto es None, lo que significa volver a idpattern (es decir, el mismo patrón se utiliza tanto dentro como fuera de las llaves). Si se proporciona, esto le permite definir diferentes patrones para comodines dentro y fuera de las llaves.

Nuevo en la versión 3.7.

flags – Banderas de expresión regular que se aplicarán al compilar la expresión regular utilizada para reconocer sustituciones. El valor por defecto es re.IGNORECASE. Téngase en cuenta que re.VERBOSE siempre se agregará a las banderas, por lo que idpattern (s) personalizado(s) debe(n) seguir las convenciones de expresiones regulares detalladas.

Nuevo en la versión 3.2.

Como alternativa, se puede proporcionar el patrón de expresión regular completo, reemplazando así el atributo de clase pattern. Si eso ocurre, el valor debe ser un objeto de expresión regular con cuatro grupos de captura con nombre. Los grupos de captura corresponden a las reglas indicadas anteriormente, junto con la regla de marcador de posición no válida:

escaped – Este grupo coincide con la secuencia de escape en el patrón predeterminado, por ejemplo, $$.

named – Este grupo coincide con el nombre comodín fuera de las llaves. No debe incluir el delimitador del grupo de captura.

braced – Este grupo coincide con el nombre del comodín adjunto; no debe incluir ni el delimitador ni las llaves en el grupo de captura.

invalid – Este grupo se empareja con cualquier otro patrón de delimitación (usualmente un único carácter) y debe ser lo último en aparecer en la expresión regular.

Funciones de ayuda

string.capwords(s, sep=None)

Separa el argumento en dos palabras utilizando el método str.split(), convierte a mayúsculas vía str.capitalize() y une las palabras en mayúscula con el método str.join(). Si el segundo argumento opcional sep está ausente o es None, los espacios en blanco se reemplazarán con un único espacio y los espacios en blanco iniciales y finales se eliminarán; caso contrario, sep se usa para separar y unir las palabras.

re — Operaciones con expresiones regulares

Código fuente: Lib/re.py [https://github.com/python/cpython/tree/3.9/Lib/re.py]

Este módulo proporciona operaciones de coincidencia de expresiones regulares similares a las encontradas en Perl.

Tanto los patrones como las cadenas de texto a buscar pueden ser cadenas de Unicode (str) así como cadenas de 8 bits (bytes). Sin embargo, las cadenas Unicode y las cadenas de 8 bits no se pueden mezclar: es decir, no se puede hacer coincidir una cadena Unicode con un patrón de bytes o viceversa; del mismo modo, al pedir una sustitución, la cadena de sustitución debe ser del mismo tipo que el patrón y la cadena de búsqueda.

Las expresiones regulares usan el carácter de barra inversa ('\') para indicar formas especiales o para permitir el uso de caracteres especiales sin invocar su significado especial. Esto choca con el uso de Python de este carácter para el mismo propósito con los literales de cadena; por ejemplo, para hacer coincidir una barra inversa literal, se podría escribir '\\\\' como patrón, porque la expresión regular debe ser \\, y cada barra inversa debe ser expresada como \\ dentro de un literal de cadena regular de Python. También, notar que cualquier secuencia de escape inválida mientras se use la barra inversa de Python en los literales de cadena ahora genera un DeprecationWarning y en el futuro esto se convertirá en un SyntaxError. Este comportamiento ocurrirá incluso si es una secuencia de escape válida para una expresión regular.

La solución es usar la notación de cadena raw de Python para los patrones de expresiones regulares; las barras inversas no se manejan de ninguna manera especial en un literal de cadena prefijado con 'r'. Así que r"\n" es una cadena de dos caracteres que contiene '\' y 'n', mientras que "\n" es una cadena de un carácter que contiene una nueva línea. Normalmente los patrones se expresan en código Python usando esta notación de cadena raw.

Es importante señalar que la mayoría de las operaciones de expresiones regulares están disponibles como funciones y métodos a nivel de módulo en expresiones regulares compiladas (expresiones regulares compiladas). Las funciones son atajos que no requieren de compilar un objeto regex primero, aunque pasan por alto algunos parámetros de ajuste.

Ver también

El módulo de terceros regex [https://pypi.org/project/regex/] , cuenta con una API compatible con el módulo de la biblioteca estándar re, el cual ofrece una funcionalidad adicional y un soporte Unicode más completo.

Sintaxis de expresiones regulares

Una expresión regular (o RE, por sus siglas en inglés) especifica un conjunto de cadenas que coinciden con ella; las funciones de este módulo permiten comprobar si una determinada cadena coincide con una expresión regular dada (o si una expresión regular dada coincide con una determinada cadena, que se reduce a lo mismo).

Las expresiones regulares pueden ser concatenadas para formar nuevas expresiones regulares; si A y B son ambas expresiones regulares, entonces AB es también una expresión regular. En general, si una cadena p coincide con A y otra cadena q coincide con B, la cadena porque coincidirá con AB. Esto se mantiene a menos que A o B contengan operaciones de baja precedencia; condiciones límite entre A y B; o tengan referencias de grupo numeradas. Así, las expresiones complejas pueden construirse fácilmente a partir de expresiones primitivas más simples como las que se describen aquí. Para detalles de la teoría e implementación de las expresiones regulares, consulte el libro de Friedl [Frie09], o casi cualquier libro de texto sobre la construcción de compiladores.

A continuación se explica brevemente el formato de las expresiones regulares. Para más información y una presentación más amena, consultar la Expresiones regulares COMOS (HOWTO).

Las expresiones regulares pueden contener tanto caracteres especiales como ordinarios. La mayoría de los caracteres ordinarios, como 'A', 'a', o '0' son las expresiones regulares más sencillas; simplemente se ajustan a sí mismas. Se pueden concatenar caracteres ordinarios, así que last coincide con la cadena 'last'. (En el resto de esta sección, se escribirán los RE en este estilo especial, normalmente sin comillas, y las cadenas que deban coincidir 'entre comillas simples'.)

Algunos caracteres, como '|' o '(', son especiales. Los caracteres especiales representan clases de caracteres ordinarios, o afectan a la forma en que se interpretan las expresiones regulares que los rodean.

Los delimitadores de repetición (*, +, ?, {m,n}, etc.) no pueden ser anidados directamente. Esto evita la ambigüedad con el sufijo modificador no greedy (codiciosos) ?, y con otros modificadores en otras implementaciones. Para aplicar una segunda repetición a una repetición interna, se pueden usar paréntesis. Por ejemplo, la expresión (?:a{6})* coincide con cualquier múltiplo de seis caracteres 'a'.

Los caracteres especiales son:

.

(Punto.) En el modo predeterminado, esto coincide con cualquier carácter excepto con una nueva línea. Si se ha especificado el indicador DOTALL, esto coincide con cualquier carácter que incluya una nueva línea.

^

(Circunflejo.) Coincide con el comienzo de la cadena, y en modo MULTILINE también coincide inmediatamente después de cada nueva línea.

$

Coincide con el final de la cadena o justo antes de la nueva línea al final de la cadena, y en modo MULTILINE también coincide antes de una nueva línea. foo coincide con “foo” y “foobar”, mientras que la expresión regular foo$ sólo coincide con “foo”. Más interesante aún, al buscar foo.$ en 'foo1\nfoo2\n' coincide con “foo2” normalmente, pero solo “foo1” en MULTILINE`; si busca un solo $ en 'foo\n' encontrará dos coincidencias (vacías): una justo antes de una nueva línea, y otra al final de la cadena.

*

Hace que el RE resultante coincida con 0 o más repeticiones del RE precedente, tantas repeticiones como sean posibles. ab* coincidirá con “a”, “ab” o “a” seguido de cualquier número de “b”.

+

Hace que la RE resultante coincida con 1 o más repeticiones de la RE precedente. ab+ coincidirá con “a” seguido de cualquier número distinto de cero de “b”; no coincidirá solo con “a”.

?

Hace que la RE resultante coincida con 0 o 1 repeticiones de la RE precedente. ab? coincidirá con “a” o “ab”.

*?, +?, ??

Los delimitadores «*», «+» y «*» son todos greedy (codiciosos); coinciden con la mayor cantidad de texto posible. A veces este comportamiento no es deseado; si el RE <.*> se utiliza para coincidir con '<a> b <c>', coincidirá con toda la cadena, y no sólo con '<a>'. Añadiendo ? después del delimitador hace que se realice la coincidencia de manera non-greedy o minimal; coincidirá la mínima cantidad de caracteres como sea posible. Usando el RE <.*?> sólo coincidirá con '<a>'.

{m}

Especifica que exactamente m copias de la RE anterior deben coincidir; menos coincidencias hacen que la RE entera no coincida. Por ejemplo, a{6} coincidirá exactamente con seis caracteres 'a', pero no con cinco.

{m,n}

Hace que el RE resultante coincida de m a n repeticiones del RE precedente, tratando de coincidir con el mayor número de repeticiones posible. Por ejemplo, a{3,5} coincidirá de 3 a 5 caracteres 'a'. Omitiendo m se especifica un límite inferior de cero, y omitiendo n se especifica un límite superior infinito. Por ejemplo, a{4,}b coincidirá con 'aaaab' o mil caracteres 'a' seguidos de una 'b', pero no 'aaab'. La coma no puede ser omitida o el modificador se confundiría con la forma descrita anteriormente.

{m,n}?

Hace que el RE resultante coincida de m a n repeticiones del RE precedente, tratando de coincidir con el mínimo de repeticiones posible. Esta es la versión non-greedy (no codiciosa) del delimitador anterior. Por ejemplo, en la cadena de 6 caracteres 'aaaaaaa', a{3,5} coincidirá con 5 caracteres 'a', mientras que a{3,5}? solo coincidirá con 3 caracteres.

\

O bien se escapan a los caracteres especiales (lo que le permite hacer coincidir caracteres como '*', '?', y así sucesivamente), o se señala una secuencia especial; las secuencias especiales se explican más adelante.

Si no se utiliza una cadena raw para expresar el patrón, recuerde que Python también utiliza la barra inversa como secuencia de escape en los literales de la cadena; si el analizador sintáctico de Python no reconoce la secuencia de escape, la barra inversa y el carácter subsiguiente se incluyen en la cadena resultante. Sin embargo, si Python quisiera reconocer la secuencia resultante, la barra inversa debería repetirse dos veces. Esto es complicado y difícil de entender, por lo que se recomienda encarecidamente utilizar cadenas raw para todas las expresiones salvo las más simples.

[]

Se utiliza para indicar un conjunto de caracteres. En un conjunto:

Los caracteres pueden ser listados individualmente, ej. [amk] coincidirá con 'a', 'm', o 'k'.

Los rangos de caracteres se pueden indicar mediante dos caracteres y separándolos con un '-'. Por ejemplo, [a-z] coincidirá con cualquier letra ASCII en minúscula, [0-5][0-9] coincidirá con todos los números de dos dígitos desde el 00 hasta el 59, y [0-9A-Fa-f] coincidirá con cualquier dígito hexadecimal. Si se escapa - (por ejemplo, [a\-z]) o si se coloca como el primer o el último carácter (por ejemplo, [-a] o [a-]), coincidirá con un literal '-'.

Los caracteres especiales pierden su significado especial dentro de los sets. Por ejemplo, [(+*)] coincidirá con cualquiera de los caracteres literales '(', '+', '*', o ')'.

Las clases de caracteres como \w o \S (definidas más adelante) también se aceptan dentro de un conjunto, aunque los caracteres que coinciden dependen de si el modo ASCII o LOCALE está activo.

Los caracteres que no están dentro de un rango pueden ser coincidentes con complementing el conjunto. Si el primer carácter del conjunto es '^', todos los caracteres que no están en el conjunto coincidirán. Por ejemplo, [^5] coincidirá con cualquier carácter excepto con '5', y [^^] coincidirá con cualquier carácter excepto con '^'. ^ no tiene un significado especial si no es el primer carácter del conjunto.

Para coincidir con un ']' literal dentro de un set, se debe preceder con una barra inversa, o colocarlo al principio del set. Por ejemplo, tanto [()[\][{}] como []()[{}] coincidirá con los paréntesis, corchetes y llaves.

El soporte de conjuntos anidados y operaciones de conjuntos como en Unicode Technical Standard #18 [https://unicode.org/reports/tr18/] podría ser añadido en el futuro. Esto cambiaría la sintaxis, así que por el momento se planteará un FutureWarning en casos ambiguos para facilitar este cambio. Ello incluye conjuntos que empiecen con un literal '[' o que contengan secuencias de caracteres literales '—', '&&', '~~' y '||'. Para evitar una advertencia, utilizar el código de escape con una barra inversa.

Distinto en la versión 3.7: FutureWarning se genera si un conjunto de caracteres contiene construcciones que cambiarán semánticamente en el futuro.

|

A|B, donde A y B pueden ser RE arbitrarias, crea una expresión regular que coincidirá con A or B. Un número arbitrario de RE puede ser separado por '|' de esta manera. Esto puede también ser usado dentro de grupos (ver más adelante). Cuando la cadena de destino es procesada, los RE separados por '|' son probados de izquierda a derecha. Cuando un patrón coincide completamente, esa rama es aceptada. Esto significa que una vez que A coincida, B no se comprobará más, incluso si se produce una coincidencia general más larga. En otras palabras, el operador de '|' nunca es codicioso. Para emparejar un literal '|', se usa \|, o se envuelve dentro de una clase de caracteres, como en [|].

(...)

Coincide con cualquier expresión regular que esté dentro de los paréntesis, e indica el comienzo y el final de un grupo; el contenido de un grupo puede ser recuperado después de que se haya realizado una coincidencia, y puede coincidir más adelante en la cadena con la secuencia especial \number, que se describe más adelante. Para hacer coincidir los literales `'(' o ')', se usa \( o \), o se envuelve dentro de una clase de caracteres: [(], [)].

(?...)

Esta es una notación de extensión (un '?' después de un '(' no tiene ningún otro significado). El primer carácter después de '?' determina el significado y la sintaxis de la construcción. Las extensiones normalmente no crean un nuevo grupo; (?P<name>…) es la única excepción a esta regla. A continuación se muestran las extensiones actualmente soportadas.

(?aiLmsux)

(Una o más letras del conjunto 'a', 'i', 'L', 'm', 's', 'u', 'x'.) El grupo coincide con la cadena vacía; las letras ponen los indicadores correspondientes: re.A (coincidencia sólo en ASCII), re.I (ignorar mayúsculas o minúsculas), re. L (dependiente de la configuración regional), re.M (multilínea), re.S (el punto coincide con todo), re.U (coincidencia con Unicode), y re.X (modo verbose), para toda la expresión regular. (Los indicadores se describen en Contenidos del módulo.) Esto es útil si se desea incluir los indicadores como parte de la expresión regular, en lugar de pasar un argumento flag (indicador) a la función re.compile(). Los indicadores deben ser usados primero en la cadena de expresión.

(?:...)

Una versión no capturable de los paréntesis regulares. Hace coincidir cualquier expresión regular que esté dentro de los paréntesis, pero la subcadena coincidente con el grupo no puede ser recuperada después de realizar una coincidencia o referenciada más adelante en el patrón.

(?aiLmsux-imsx:...)

(Cero o más letras del conjunto 'a', 'i', 'L', 'm', 's', 'u', 'x', opcionalmente seguido de '-' seguido de una o más letras de 'i', 'm', 's', 'x'.) Las letras ponen o quitan los indicadores correspondientes: re.A (coincidencia sólo en ASCII), re.I (ignorar mayúsculas o minúsculas), re. L (dependiente de la configuración regional), re.M (multilínea), re.S (el punto coincide con todo), re.U (coincidencia con Unicode), y re.X (modo verbose) para la parte de la expresión. (Los indicadores se describen en Contenidos del módulo.)

Las letras 'a', 'L' y 'u' se excluyen mutuamente cuando se usan como indicadores en línea, así que no pueden combinarse o ser seguidos por '-'. En cambio, cuando uno de ellos aparece en un grupo dentro de la línea, anula el modo de coincidencia en el grupo que lo rodea. En los patrones Unicode, (?a:…) cambia al modo de concordancia sólo en ASCII, y (?u:…) cambia al modo de concordancia Unicode (por defecto). En el patrón de bytes (?L:…) se cambia a una correspondencia en función de la configuración regional, y (?a:…) se cambia a una correspondencia sólo en ASCII (predeterminado). Esta anulación sólo tiene efecto para el grupo de línea restringida, y el modo de coincidencia original se restaura fuera del grupo.

Nuevo en la versión 3.6.

Distinto en la versión 3.7: Las letras 'a', 'L' y 'u' también pueden ser usadas en un grupo.

(?P<name>...)

Similar a los paréntesis regulares, pero la subcadena coincidente con el grupo es accesible a través del nombre simbólico del grupo, name . Los nombres de grupo deben ser identificadores válidos de Python, y cada nombre de grupo debe ser definido sólo una vez dentro de una expresión regular. Un grupo simbólico es también un grupo numerado, del mismo modo que si el grupo no tuviera nombre.

Los grupos con nombre pueden ser referenciados en tres contextos. Si el patrón es (?P<quote>['"]).*?(?P=quote) (es decir, hacer coincidir una cadena citada con comillas simples o dobles):

Contexto de la referencia al grupo quote (cita)

Formas de hacer referencia

en el mismo patrón en sí mismo

(?P=quote) (como se muestra)

\1

cuando se procesa el objeto de la coincidencia m

m.group('quote')

m.end('quote') (etc.)

en una cadena pasada al argumento repl de re.sub()

\g<quote>

\g<1>

\1

(?P=name)

Una referencia inversa a un grupo nombrado; coincide con cualquier texto correspondido por el grupo anterior llamado name.

(?#...)

Un comentario; el contenido de los paréntesis es simplemente ignorado.

(?=...)

Coincide si … coincide con el siguiente patrón, pero no procesa nada de la cadena. Esto se llama una lookahead assertion (aserción de búsqueda anticipada). Por ejemplo, Isaac (?=Asimov) coincidirá con 'Isaac ' sólo si va seguido de 'Asimov'.

(?!...)

Coincide si … no coincide con el siguiente. Esta es una negative lookahead assertion (aserción negativa de búsqueda anticipada). Por ejemplo, Isaac (?!Asimov) coincidirá con 'Isaac ' sólo si no es seguido por 'Asimov'.

(?<=...)

Coincide si la posición actual en la cadena es precedida por una coincidencia para … que termina en la posición actual. Esto se llama una positive lookbehind assertion (aserciones positivas de búsqueda tardía). (?<=abc)def encontrará una coincidencia en 'abcdef', ya que la búsqueda tardía hará una copia de seguridad de 3 caracteres y comprobará si el patrón contenido coincide. El patrón contenido sólo debe coincidir con cadenas de alguna longitud fija, lo que significa que abc o a|b están permitidas, pero a* y a{3,4} no lo están. Hay que tener en cuenta que los patrones que empiezan con aserciones positivas de búsqueda tardía no coincidirán con el principio de la cadena que se está buscando; lo más probable es que se quiera usar la función search() en lugar de la función match():

>>> import re
>>> m = re.search('(?<=abc)def', 'abcdef')
>>> m.group(0)
'def'

Este ejemplo busca una palabra seguida de un guión:

>>> m = re.search(r'(?<=-)\w+', 'spam-egg')
>>> m.group(0)
'egg'

Distinto en la versión 3.5: Se añadió soporte a las referencias de grupo de longitud fija.

(?<!...)

Coincide si la posición actual en la cadena no está precedida por una coincidencia de «…». Esto se llama una negative lookbehind assertion (Aserciones negativas de búsqueda tardía). Similar a las aserciones positivas de búsqueda tardía, el patrón contenido sólo debe coincidir con cadenas de alguna longitud fija. Los patrones que empiezan con aserciones negativas pueden coincidir al principio de la cadena que se busca.

(?(id/name)yes-pattern|no-pattern)

Tratará de coincidir con el yes-pattern (con patrón) si el grupo con un id o nombre existe, y con el no-pattern (sin patrón) si no existe. El no-pattern es opcional y puede ser omitido. Por ejemplo, (<)?(\w+@\w+(?:\.\w+)+)(?(1)>||$) es un patrón de coincidencia de correo electrónico deficiente, ya que coincidirá con '<user@host.com>' así como con 'user@host.com', pero no con '<user@host.com' ni con 'user@host.com>'.

Las secuencias especiales consisten en '\' y un carácter de la lista que aparece más adelante. Si el carácter ordinario no es un dígito ASCII o una letra ASCII, entonces el RE resultante coincidirá con el segundo carácter. Por ejemplo, \$ coincide con el carácter '$'.

\number

Coincide con el contenido del grupo del mismo número. Los grupos se numeran empezando por el 1. Por ejemplo, (.+) \1 coincide con 'el el' o '55 55', pero no con 'elel' (notar el espacio después del grupo). Esta secuencia especial sólo puede ser usada para hacer coincidir uno de los primeros 99 grupos. Si el primer dígito del número es 0, o el número tiene 3 dígitos octales, no se interpretará como una coincidencia de grupo, sino como el carácter con valor octal número. Dentro de los '[' y ']' de una clase de caracteres, todos los escapes numéricos son tratados como caracteres.

\A

Coincide sólo al principio de la cadena.

\b

Coincide con la cadena vacía, pero sólo al principio o al final de una palabra. Una palabra se define como una secuencia de caracteres de palabras. Notar que formalmente, \b se define como el límite entre un carácter \w y un carácter \W (o viceversa), o entre \w y el principio/fin de la cadena. Esto significa que r'\bfoo\b' coincide con 'foo', 'foo.', '(foo)', 'bar foo baz' pero no 'foobar' o 'foo3'.

Por defecto, los alfanuméricos Unicode son los que se usan en los patrones Unicode, pero esto se puede cambiar usando el indicador ASCII. Los límites de las palabras están determinados por la configuración regional actual si se usa el indicador LOCALE. Dentro de un rango de caracteres, \b representa el carácter de retroceso (backspace), para compatibilidad con los literales de las cadenas de Python.

\B

Coincide con la cadena vacía, pero sólo cuando no está al principio o al final de una palabra. Esto significa que r'py\B' coincide con 'python', 'py3', 'py2', pero no con 'py', 'py.' o 'py!'. \B es justo lo opuesto a \b, por lo que los caracteres de las palabras en los patrones de Unicode son alfanuméricos o el subrayado, aunque esto puede ser cambiado usando el indicador ASCII. Los límites de las palabras están determinados por la configuración regional actual si se usa el indicador LOCALE.

\d

Para los patrones de Unicode (str):

Coincide con cualquier dígito decimal de Unicode (es decir, cualquier carácter de la categoría de caracteres de Unicode [Nd]). Esto incluye a [0-9], y también muchos otros caracteres de dígitos. Si se usa el indicador ASCII, sólo coincide con [0-9].

Para patrones de 8 bits (bytes):

Coincide con cualquier dígito decimal; esto equivale a [0-9].

\D

Coincide con cualquier carácter que no sea un dígito decimal. Esto es lo opuesto a \d. Si se usa el indicador ASCII esto se convierte en el equivalente a [^0-9].

\s

Para los patrones de Unicode (str):

Coincide con los caracteres de los espacios en blanco de Unicode (que incluye [ \t\n\r\f\v], y también muchos otros caracteres, por ejemplo los espacios duros exigidos por las reglas tipográficas en muchos idiomas). Si se usa el indicador ASCII`, sólo [ \t\n\r\f\v] coincide.

Para patrones de 8 bits (bytes):

Coincide con los caracteres considerados como espacios en blanco en el conjunto de caracteres ASCII, lo que equivale a [ \t\n\r\f\v].

\S

Coincide con cualquier carácter que no sea un carácter de espacio en blanco. Esto es lo opuesto a \s. Si se usa el indicador ASCII se convierte en el equivalente a [^ tnrfv].

\w

Para los patrones de Unicode (str):

Coincide con los caracteres de palabras de Unicode; esto incluye la mayoría de los caracteres que pueden formar parte de una palabra en cualquier idioma, así como los números y el guión bajo. Si se usa el indicador ASCII, sólo coincide con [a-zA-Z0-9_].

Para patrones de 8 bits (bytes):

Coincide con los caracteres considerados alfanuméricos en el conjunto de caracteres ASCII; esto equivale a [a-zA-Z0-9_]. Si se usa el indicador LOCALE, coincide con los caracteres considerados alfanuméricos en la configuración regional actual y el guión bajo.

\W

Coincide con cualquier carácter que no sea un carácter de una palabra. Esto es lo opuesto a \w. Si se usa el indicador ASCII esto se convierte en el equivalente a [^a-zA-Z0-9_]. Si se usa el indicador LOCALE, coincide con los caracteres que no son ni alfanuméricos en la configuración regional actual ni con el guión bajo.

\Z

Coincide sólo el final de la cadena.

La mayoría de los escapes estándar soportados por los literales de la cadena de Python también son aceptados por el analizador de expresiones regulares:

\a      \b      \f      \n
\N      \r      \t      \u
\U      \v      \x      \\

(Notar que \b se usa para representar los límites de las palabras, y significa «retroceso» (backspace) sólo dentro de las clases de caracteres.)

Las secuencias de escape '\u', '\U' y '\N' sólo se reconocen en los patrones Unicode. En los patrones de bytes son errores. Los escapes desconocidos de las letras ASCII se reservan para su uso posterior y se consideran errores.

Los escapes octales se incluyen en una forma limitada. Si el primer dígito es un 0, o si hay tres dígitos octales, se considera un escape octal. De lo contrario, es una referencia de grupo. En cuanto a los literales de cadena, los escapes octales siempre tienen como máximo tres dígitos de longitud.

Distinto en la versión 3.3: Se han añadido las secuencias de escape '\u' y '\U'.

Distinto en la versión 3.6: Los escapes desconocidos que consisten en '\' y una letra ASCII ahora son errores.

Distinto en la versión 3.8: Se añadió la secuencia de escape '\N{name}'. Como en los literales de cadena, se expande al carácter Unicode nombrado (por ej. '\N{EM DASH}').

Contenidos del módulo

El módulo define varias funciones, constantes y una excepción. Algunas de las funciones son versiones simplificadas de los métodos completos de las expresiones regulares compiladas. La mayoría de las aplicaciones no triviales utilizan siempre la forma compilada.

Distinto en la versión 3.6: Ahora las constantes de indicadores son instancias de RegexFlag, que es una subclase de enum.IntFlag.

re.compile(pattern, flags=0)

Compila un patrón de expresión regular en un objeto de expresión regular, que puede ser usado para las coincidencias usando match(), search() y otros métodos, descritos más adelante.

El comportamiento de la expresión puede modificarse especificando un valor de indicadores. Los valores pueden ser cualquiera de las siguientes variables, combinadas usando el operador OR (el operador |).

La secuencia

prog = re.compile(pattern)
result = prog.match(string)

es equivalente a

result = re.match(pattern, string)

pero usando re.compile() y guardando el objeto resultante de la expresión regular para su reutilización es más eficiente cuando la expresión será usada varias veces en un solo programa.

Nota

Las versiones compiladas de los patrones más recientes pasaron a re.compile() y las funciones de coincidencia a nivel de módulo están en caché, así que los programas que usan sólo unas pocas expresiones regulares a la vez no tienen que preocuparse de compilar expresiones regulares.

re.A

re.ASCII

Hace que \w, \W, \b, \B, \d, \D, \s y \S realicen una coincidencia ASCII en lugar de una concordancia Unicode. Esto sólo tiene sentido para los patrones de Unicode, y se ignora para los patrones de bytes. Corresponde al indicador en línea (?a).

Notar que para la compatibilidad con versiones anteriores, el indicador re.U todavía existe (así como su sinónimo re.UNICODE y su contraparte incrustada (?u)), pero estos son redundantes en Python 3 ya que las coincidencias son Unicode por defecto para las cadenas (y no se permite la coincidencia Unicode para los bytes).

re.DEBUG

Muestra información de depuración (debug) sobre la expresión compilada. No hay un indicador en línea que corresponda.

re.I

re.IGNORECASE

Realiza una coincidencia insensible a las mayúsculas y minúsculas; expresiones como [A-Z] también coincidirán con las minúsculas. La coincidencia completa de Unicode (como Ü coincidencia ü) también funciona a menos que el indicador re.ASCII se utilice para desactivar las coincidencias que no sean ASCII. La configuración regional vigente no cambia el efecto de este indicador a menos que también se use el indicador re.LOCALE. Corresponde al indicador en línea (?i).

Notar que cuando los patrones Unicode [a-z] o [A-Z] se usan en combinación con el flag IGNORECASE`, coincidirán con las 52 letras ASCII y 4 letras adicionales no ASCII: “İ” (U+0130, letra mayúscula latina I con punto arriba), “ı” (U+0131, letra minúscula latina sin punto i), “ſ” (U+017F, letra minúscula latina s larga) y “K” (U+212A, signo Kelvin). Si se usa el indicador ASCII, sólo las letras de la “a” a la “z” y de la “A” a la “Z” coinciden.

re.L

re.LOCALE

Hace que las coincidencias \w, \W, \b, \B y las coincidencias insensibles a mayúsculas y minúsculas dependan de la configuración regional vigente. Este indicador sólo puede ser usado con patrones de bytes. Se desaconseja su uso ya que el mecanismo de configuración regional no es fiable, sólo maneja una «cultura» a la vez, y sólo funciona con localizaciones de 8 bits. La coincidencia Unicode ya está activada por defecto en Python 3 para los patrones Unicode (str), y es capaz de manejar diferentes localizaciones/idiomas. Corresponde al indicador en línea (?L).

Distinto en la versión 3.6: re.LOCALE sólo se puede usar con patrones de bytes y no es compatible con re.ASCII.

Distinto en la versión 3.7: Los objetos expresión regular compilados con el indicador re.LOCALE ya no dependen del lugar en el momento de la compilación. Sólo la configuración regional durante la coincidencia afecta al resultado obtenido.

re.M

re.MULTILINE

Cuando se especifica, el patrón de caracteres '^' coincide al principio de la cadena y al principio de cada línea (inmediatamente después de cada nueva línea); y el patrón de caracteres '$' coincide al final de la cadena y al final de cada línea (inmediatamente antes de cada nueva línea). Por defecto, '^' coincide sólo al principio de la cadena, y '$' sólo al final de la cadena e inmediatamente antes de la nueva línea (si la hay) al final de la cadena. Corresponde al indicador en línea (?m).

re.S

re.DOTALL

Hace que el carácter especial '.' coincida con cualquier carácter, incluyendo una nueva línea. Sin este indicador, '.' coincidirá con cualquier cosa, excepto con una nueva línea. Corresponde al indicador en línea (?s).

re.X

re.VERBOSE

Este indicador permite escribir expresiones regulares que se ven mejor y son más legibles al facilitar la separación visual de las secciones lógicas del patrón y añadir comentarios. Los espacios en blanco dentro del patrón se ignoran, excepto cuando están en una clase de caracteres, o cuando están precedidos por una barra inversa no escapada, o dentro de fichas como *?, (?: o (?P<...>. Cuando una línea contiene un # que no está en una clase de caracteres y no está precedida por una barra inversa no escapada, se ignoran todos los caracteres desde el más a la izquierda (como #) hasta el final de la línea.

Esto significa que los dos siguientes objetos expresión regular que coinciden con un número decimal son funcionalmente iguales:

a = re.compile(r"""\d +  # the integral part
                   \.    # the decimal point
                   \d *  # some fractional digits""", re.X)
b = re.compile(r"\d+\.\d*")

Corresponde al indicador en línea (?x).

re.search(pattern, string, flags=0)

Examina a través de la string («cadena») buscando el primer lugar donde el pattern («patrón») de la expresión regular produce una coincidencia, y retorna un objeto match correspondiente. Retorna None si ninguna posición en la cadena coincide con el patrón; notar que esto es diferente a encontrar una coincidencia de longitud cero en algún punto de la cadena.

re.match(pattern, string, flags=0)

Si cero o más caracteres al principio de la string («cadena») coinciden con el pattern («patrón») de la expresión regular, retorna un objeto match correspondiente. Retorna None si la cadena no coincide con el patrón; notar que esto es diferente de una coincidencia de longitud cero.

Notar que incluso en el modo MULTILINE, re.match() sólo coincidirá al principio de la cadena y no al principio de cada línea.

Si se quiere localizar una coincidencia en cualquier lugar de la string («cadena»), se utiliza search() en su lugar (ver también search() vs. match()).

re.fullmatch(pattern, string, flags=0)

Si toda la string («cadena») coincide con el pattern («patrón») de la expresión regular, retorna un correspondiente objeto match. Retorna None si la cadena no coincide con el patrón; notar que esto es diferente de una coincidencia de longitud cero.

Nuevo en la versión 3.4.

re.split(pattern, string, maxsplit=0, flags=0)

Divide la string («cadena») por el número de ocurrencias del pattern («patrón»). Si se utilizan paréntesis de captura en pattern, entonces el texto de todos los grupos en el patrón también se retornan como parte de la lista resultante. Si maxsplit (máxima divisibilidad) es distinta de cero, como mucho se producen maxsplit divisiones, y el resto de la cadena se retorna como elemento final de la lista.

>>> re.split(r'\W+', 'Words, words, words.')
['Words', 'words', 'words', '']
>>> re.split(r'(\W+)', 'Words, words, words.')
['Words', ', ', 'words', ', ', 'words', '.', '']
>>> re.split(r'\W+', 'Words, words, words.', 1)
['Words', 'words, words.']
>>> re.split('[a-f]+', '0a3B9', flags=re.IGNORECASE)
['0', '3', '9']

Si hay grupos de captura en el separador y coincide al principio de la cadena, el resultado comenzará con una cadena vacía. Lo mismo ocurre con el final de la cadena:

>>> re.split(r'(\W+)', '...words, words...')
['', '...', 'words', ', ', 'words', '...', '']

De esa manera, los componentes de los separadores se encuentran siempre en los mismos índices relativos dentro de la lista de resultados.

Las coincidencias vacías para el patrón dividen la cadena sólo cuando no están adyacentes a una coincidencia vacía anterior.

>>> re.split(r'\b', 'Words, words, words.')
['', 'Words', ', ', 'words', ', ', 'words', '.']
>>> re.split(r'\W*', '...words...')
['', '', 'w', 'o', 'r', 'd', 's', '', '']
>>> re.split(r'(\W*)', '...words...')
['', '...', '', '', 'w', '', 'o', '', 'r', '', 'd', '', 's', '...', '', '', '']

Distinto en la versión 3.1: Se añadió el argumento de los indicadores opcionales.

Distinto en la versión 3.7: Se añadió el soporte de la división en un patrón que podría coincidir con una cadena vacía.

re.findall(pattern, string, flags=0)

Return all non-overlapping matches of pattern in string, as a list of strings or tuples. The string is scanned left-to-right, and matches are returned in the order found. Empty matches are included in the result.

The result depends on the number of capturing groups in the pattern. If there are no groups, return a list of strings matching the whole pattern. If there is exactly one group, return a list of strings matching that group. If multiple groups are present, return a list of tuples of strings matching the groups. Non-capturing groups do not affect the form of the result.

>>> re.findall(r'\bf[a-z]*', 'which foot or hand fell fastest')
['foot', 'fell', 'fastest']
>>> re.findall(r'(\w+)=(\d+)', 'set width=20 and height=10')
[('width', '20'), ('height', '10')]

Distinto en la versión 3.7: Las coincidencias no vacías ahora pueden empezar justo después de una coincidencia vacía anterior.

re.finditer(pattern, string, flags=0)

Retorna un iterator que produce objetos de coincidencia sobre todas las coincidencias no superpuestas para pattern («patrón») de RE en la string («cadena»). La string es examinada de izquierda a derecha, y las coincidencias son retornadas en el orden en que se encuentran. Las coincidencias vacías se incluyen en el resultado.

Distinto en la versión 3.7: Las coincidencias no vacías ahora pueden empezar justo después de una coincidencia vacía anterior.

re.sub(pattern, repl, string, count=0, flags=0)

Retorna la cadena obtenida reemplazando las ocurrencias no superpuestas del pattern («patrón») en la string («cadena») por el reemplazo de repl. Si el patrón no se encuentra, se retorna string sin cambios. repl puede ser una cadena o una función; si es una cadena, cualquier barra inversa escapada en ella es procesada. Es decir, \n se convierte en un carácter de una sola línea nueva, \r se convierte en un retorno de carro, y así sucesivamente. Los escapes desconocidos de las letras ASCII se reservan para un uso futuro y se tratan como errores. Otros escapes desconocidos como \& no se utilizan. Las referencias inversas, como \6, se reemplazan por la subcadena que corresponde al grupo 6 del patrón. Por ejemplo:

>>> re.sub(r'def\s+([a-zA-Z_][a-zA-Z_0-9]*)\s*\(\s*\):',
...        r'static PyObject*\npy_\1(void)\n{',
...        'def myfunc():')
'static PyObject*\npy_myfunc(void)\n{'

Si repl es una función, se llama para cada ocurrencia no superpuesta de pattern. La función toma un solo argumento objeto match, y retorna la cadena de sustitución. Por ejemplo:

>>> def dashrepl(matchobj):
...     if matchobj.group(0) == '-': return ' '
...     else: return '-'
>>> re.sub('-{1,2}', dashrepl, 'pro----gram-files')
'pro--gram files'
>>> re.sub(r'\sAND\s', ' & ', 'Baked Beans And Spam', flags=re.IGNORECASE)
'Baked Beans & Spam'

El patrón puede ser una cadena o un objeto patrón.

El argumento opcional count («recuento») es el número máximo de ocurrencias de patrones a ser reemplazados; count debe ser un número entero no negativo. Si se omite o es cero, todas las ocurrencias serán reemplazadas. Las coincidencias vacías del patrón se reemplazan sólo cuando no están adyacentes a una coincidencia vacía anterior, así que sub('x*', '-', 'abxd') retorna '-a-b--d-'.

En los argumentos repl de tipo cadena, además de los escapes de caracteres y las referencias inversas descritas anteriormente, \g<name> usará la subcadena coincidente con el grupo llamado name, como se define en la sintaxis (?P<name>...). \g<number> utiliza el número de grupo correspondiente; \g<2> es por lo tanto equivalente a \2, pero no es ambiguo en un reemplazo como sucede con \g<2>0. \20 se interpretaría como una referencia al grupo 20, no como una referencia al grupo 2 seguido del carácter literal '0'. La referencia inversa \g<0> sustituye en toda la subcadena coincidente con la RE.

Distinto en la versión 3.1: Se añadió el argumento de los indicadores opcionales.

Distinto en la versión 3.5: Los grupos no coincidentes son reemplazados por una cadena vacía.

Distinto en la versión 3.6: Los escapes desconocidos en el pattern que consisten en '\' y una letra ASCII ahora son errores.

Distinto en la versión 3.7: Los escapes desconocidos en repl que consisten en '\' y una letra ASCII ahora son errores.

Distinto en la versión 3.7: Las coincidencias vacías para el patrón se reemplazan cuando están adyacentes a una coincidencia anterior no vacía.

re.subn(pattern, repl, string, count=0, flags=0)

Realiza la misma operación que sub(), pero retorna una tupla (new_string, number_of_subs_made).

Distinto en la versión 3.1: Se añadió el argumento de los indicadores opcionales.

Distinto en la versión 3.5: Los grupos no coincidentes son reemplazados por una cadena vacía.

re.escape(pattern)

Caracteres de escape especiales en pattern (» patrón»). Esto es útil si quieres hacer coincidir una cadena literal arbitraria que puede tener metacaracteres de expresión regular en ella. Por ejemplo:

>>> print(re.escape('https://www.python.org'))
https://www\.python\.org

>>> legal_chars = string.ascii_lowercase + string.digits + "!#$%&'*+-.^_`|~:"
>>> print('[%s]+' % re.escape(legal_chars))
[abcdefghijklmnopqrstuvwxyz0123456789!\#\$%\&'\*\+\-\.\^_`\|\~:]+

>>> operators = ['+', '-', '*', '/', '**']
>>> print('|'.join(map(re.escape, sorted(operators, reverse=True))))
/|\-|\+|\*\*|\*

Esta función no debe usarse para la cadena de reemplazo en sub() y subn(), sólo deben escaparse las barras inversas. Por ejemplo:

>>> digits_re = r'\d+'
>>> sample = '/usr/sbin/sendmail - 0 errors, 12 warnings'
>>> print(re.sub(digits_re, digits_re.replace('\\', r'\\'), sample))
/usr/sbin/sendmail - \d+ errors, \d+ warnings

Distinto en la versión 3.3: El carácter de '_' ya no se escapa.

Distinto en la versión 3.7: Sólo se escapan los caracteres que pueden tener un significado especial en una expresión regular. Como resultado, '!', '"', '%', "'", ',', '/', ':', ';', '<', '=', '>', '@' y "`" ya no se escapan.

re.purge()

Despeja la caché de expresión regular.

exception re.error(msg, pattern=None, pos=None)

Excepción señalada cuando una cadena enviada a una de las funciones descritas aquí no es una expresión regular válida (por ejemplo, podría contener paréntesis no coincidentes) o cuando se produce algún otro error durante la compilación o la coincidencia. Nunca es un error si una cadena no contiene ninguna coincidencia para un patrón. La instancia de error tiene los siguientes atributos adicionales:

msg

El mensaje de error sin formato.

pattern

El patrón de expresión regular.

pos

El índice en pattern («patrón») donde la compilación falló (puede ser None).

lineno

La línea correspondiente a pos (puede ser None).

colno

La columna correspondiente a pos (puede ser None).

Distinto en la versión 3.5: Se añadieron atributos adicionales.

Objetos expresión regular

Los objetos expresión regular compilados soportan los siguientes métodos y atributos:

Pattern.search(string[, pos[, endpos]])

Escanea a través de la string («cadena») buscando la primera ubicación donde esta expresión regular produce una coincidencia, y retorna un objeto match correspondiente. Retorna None si ninguna posición en la cadena coincide con el patrón; notar que esto es diferente a encontrar una coincidencia de longitud cero en algún punto de la cadena.

El segundo parámetro opcional pos proporciona un índice en la cadena donde la búsqueda debe comenzar; por defecto es 0. Esto no es completamente equivalente a dividir la cadena; el patrón de carácter '^' coincide en el inicio real de la cadena y en las posiciones justo después de una nueva línea, pero no necesariamente en el índice donde la búsqueda va a comenzar.

El parámetro opcional endpos limita hasta dónde se buscará la cadena; será como si la cadena fuera de endpos caracteres de largo, por lo que sólo se buscará una coincidencia entre los caracteres de pos a endpos - 1. Si endpos es menor que pos, no se encontrará ninguna coincidencia; de lo contrario, si rx es un objeto de expresión regular compilado, rx.search(string, 0, 50) es equivalente a rx.search(string[:50], 0).

>>> pattern = re.compile("d")
>>> pattern.search("dog")     # Match at index 0
<re.Match object; span=(0, 1), match='d'>
>>> pattern.search("dog", 1)  # No match; search doesn't include the "d"

Pattern.match(string[, pos[, endpos]])

Si cero o más caracteres en el beginning («comienzo») de la string («cadena») coinciden con esta expresión regular, retorna un objeto match correspondiente. Retorna None si la cadena no coincide con el patrón; notar que esto es diferente de una coincidencia de longitud cero.

Los parámetros opcionales pos y endpos tienen el mismo significado que para el método search().

>>> pattern = re.compile("o")
>>> pattern.match("dog")      # No match as "o" is not at the start of "dog".
>>> pattern.match("dog", 1)   # Match as "o" is the 2nd character of "dog".
<re.Match object; span=(1, 2), match='o'>

Si se quiere encontrar una coincidencia en cualquier lugar de string, utilizar search() en su lugar (ver también search() vs. match()).

Pattern.fullmatch(string[, pos[, endpos]])

Si toda la string («cadena») coincide con esta expresión regular, retorna un objeto match correspondiente. Retorna None si la cadena no coincide con el patrón; notar que esto es diferente de una coincidencia de longitud cero.

Los parámetros opcionales pos y endpos tienen el mismo significado que para el método search().

>>> pattern = re.compile("o[gh]")
>>> pattern.fullmatch("dog")      # No match as "o" is not at the start of "dog".
>>> pattern.fullmatch("ogre")     # No match as not the full string matches.
>>> pattern.fullmatch("doggie", 1, 3)   # Matches within given limits.
<re.Match object; span=(1, 3), match='og'>

Nuevo en la versión 3.4.

Pattern.split(string, maxsplit=0)

Idéntico a la función split(), usando el patrón compilado.

Pattern.findall(string[, pos[, endpos]])

Similar a la función findall(), usando el patrón compilado, pero también acepta parámetros opcionales pos y endpos que limitan la región de búsqueda como para search().

Pattern.finditer(string[, pos[, endpos]])

Similar a la función finditer(), usando el patrón compilado, pero también acepta parámetros opcionales pos y endpos que limitan la región de búsqueda como para search().

Pattern.sub(repl, string, count=0)

Idéntico a la función sub(), usando el patrón compilado.

Pattern.subn(repl, string, count=0)

Idéntico a la función subn(), usando el patrón compilado.

Pattern.flags

Los indicadores regex de coincidencia. Esta es una combinación de los indicadores dados a compile(), cualquier indicador (?...) en línea en el patrón, y los indicadores implícitos como UNICODE si el patrón es una cadena de Unicode.

Pattern.groups

El número de grupos de captura en el patrón.

Pattern.groupindex

Un diccionario que mapea cualquier nombre de grupo simbólico definido por (?P<id>) para agrupar números. El diccionario está vacío si no se utilizaron grupos simbólicos en el patrón.

Pattern.pattern

La cadena de patrones a partir de la cual el objeto de patrón fue compilado.

Distinto en la versión 3.7: Se añadió el soporte de copy.copy() y copy.deepcopy(). Los objetos expresión regular compilados se consideran atómicos.

Objetos de coincidencia

Los objetos de coincidencia siempre tienen un valor booleano de True («Verdadero»). Ya que match() y search() retornan None cuando no hay coincidencia. Se puede probar si hubo una coincidencia con una simple declaración if:

match = re.search(pattern, string)
if match:
    process(match)

Los objetos de coincidencia admiten los siguientes métodos y atributos:

Match.expand(template)

Retorna la cadena obtenida al hacer la sustitución de la barra inversa en la cadena de la plantilla template, como se hace con el método sub(). Escapes como \n son convertidos a los caracteres apropiados, y las referencias inversas numéricas (\1, \2) y las referencias inversas con nombre (\g<1>, \g<name>) son reemplazadas por el contenido del grupo correspondiente.

Distinto en la versión 3.5: Los grupos no coincidentes son reemplazados por una cadena vacía.

Match.group([group1, ...])

Retorna uno o más subgrupos de la coincidencia. Si hay un solo argumento, el resultado es una sola cadena; si hay múltiples argumentos, el resultado es una tupla con un elemento por argumento. Sin argumentos, group1 tiene un valor por defecto de cero (se retorna la coincidencia completa). Si un argumento groupN es cero, el valor de retorno correspondiente es toda la cadena coincidente; si está en el rango inclusivo [1..99], es la cadena coincidente con el grupo correspondiente entre paréntesis. Si un número de grupo es negativo o mayor que el número de grupos definidos en el patrón, se produce una excepción IndexError. Si un grupo está contenido en una parte del patrón que no coincidió, el resultado correspondiente es None. Si un grupo está contenido en una parte del patrón que coincidió varias veces, se retorna la última coincidencia.

>>> m = re.match(r"(\w+) (\w+)", "Isaac Newton, physicist")
>>> m.group(0)       # The entire match
'Isaac Newton'
>>> m.group(1)       # The first parenthesized subgroup.
'Isaac'
>>> m.group(2)       # The second parenthesized subgroup.
'Newton'
>>> m.group(1, 2)    # Multiple arguments give us a tuple.
('Isaac', 'Newton')

Si la expresión regular usa la sintaxis (?P<name>...), los argumentos groupN también pueden ser cadenas que identifican a los grupos por su nombre de grupo. Si un argumento de cadena no se usa como nombre de grupo en el patrón, se produce una excepción IndexError.

Un ejemplo moderadamente complicado:

>>> m = re.match(r"(?P<first_name>\w+) (?P<last_name>\w+)", "Malcolm Reynolds")
>>> m.group('first_name')
'Malcolm'
>>> m.group('last_name')
'Reynolds'

Los grupos nombrados también pueden ser referidos por su índice:

>>> m.group(1)
'Malcolm'
>>> m.group(2)
'Reynolds'

Si un grupo coincide varias veces, sólo se puede acceder a la última coincidencia:

>>> m = re.match(r"(..)+", "a1b2c3")  # Matches 3 times.
>>> m.group(1)                        # Returns only the last match.
'c3'

Match.__getitem__(g)

Esto es idéntico a m.group(g). Esto permite un acceso más fácil a un grupo individual de una coincidencia:

>>> m = re.match(r"(\w+) (\w+)", "Isaac Newton, physicist")
>>> m[0]       # The entire match
'Isaac Newton'
>>> m[1]       # The first parenthesized subgroup.
'Isaac'
>>> m[2]       # The second parenthesized subgroup.
'Newton'

Nuevo en la versión 3.6.

Match.groups(default=None)

Retorna una tupla que contenga todos los subgrupos de la coincidencia, desde 1 hasta tantos grupos como haya en el patrón. El argumento default («por defecto») se utiliza para los grupos que no participaron en la coincidencia; por defecto es None.

Por ejemplo:

>>> m = re.match(r"(\d+)\.(\d+)", "24.1632")
>>> m.groups()
('24', '1632')

Si hacemos que el decimal y todo lo que sigue sea opcional, no todos los grupos podrían participar en la coincidencia. Estos grupos serán por defecto None a menos que se utilice el argumento default:

>>> m = re.match(r"(\d+)\.?(\d+)?", "24")
>>> m.groups()      # Second group defaults to None.
('24', None)
>>> m.groups('0')   # Now, the second group defaults to '0'.
('24', '0')

Match.groupdict(default=None)

Retorna un diccionario que contiene todos los subgrupos nombrados de la coincidencia, tecleado por el nombre del subgrupo. El argumento por defecto se usa para los grupos que no participaron en la coincidencia; por defecto es None. Por ejemplo:

>>> m = re.match(r"(?P<first_name>\w+) (?P<last_name>\w+)", "Malcolm Reynolds")
>>> m.groupdict()
{'first_name': 'Malcolm', 'last_name': 'Reynolds'}

Match.start([group])

Match.end([group])

Retorna los índices del comienzo y el final de la subcadena coincidiendo con el group; el group por defecto es cero (es decir, toda la subcadena coincidente). Retorna -1 si grupo existe pero no ha contribuido a la coincidencia. Para un objeto coincidente m, y un grupo g que sí contribuyó a la coincidencia, la subcadena coincidente con el grupo g (equivalente a m.group(g)) es

m.string[m.start(g):m.end(g)]

Notar que m.start(group) será igual a m.end(group) si group coincidió con una cadena nula. Por ejemplo, después de m = re.search('b(c?)', 'cba'), m.start(0) es 1, m.end(0) es 2, m.start(1) y m.end(1) son ambos 2, y m.start(2) produce una excepción IndexError.

Un ejemplo que eliminará remove_this («quita esto») de las direcciones de correo electrónico:

>>> email = "tony@tiremove_thisger.net"
>>> m = re.search("remove_this", email)
>>> email[:m.start()] + email[m.end():]
'tony@tiger.net'

Match.span([group])

Para una coincidencia m, retorna la tupla-2 (m.inicio(grupo), m.fin(grupo)). Notar que si group no contribuyó a la coincidencia, esto es (-1, -1). group por se convierte a cero para toda la coincidencia.

Match.pos

El valor de pos que fue pasado al método search() o match() de un objeto regex. Este es el índice de la cadena en la que el motor RE comenzó a buscar una coincidencia.

Match.endpos

El valor de endpos que se pasó al método search() o match() de un objeto regex. Este es el índice de la cadena más allá de la cual el motor RE no irá.

Match.lastindex

El índice entero del último grupo de captura coincidente, o``None`` si no hay ningún grupo coincidente. Por ejemplo, las expresiones (a)b, ((a)(b)) y ((ab)) tendrán lastindex == 1 si se aplican a la cadena 'ab', mientras que la expresión (a)(b) tendrá lastindex == 2, si se aplica a la misma cadena.

Match.lastgroup

El nombre del último grupo capturador coincidente, o``None`` si el grupo no tenía nombre, o si no había ningún grupo coincidente.

Match.re

El objeto de expresión regular cuyo método match() o search() produce esta instancia de coincidencia.

Match.string

La cadena pasada a match() o search().

Distinto en la versión 3.7: Se añadió el soporte de copy.copy() y copy.deepcopy(). Los objetos de coincidencia se consideran atómicos.

Ejemplos de expresiones regulares

Buscando un par

En este ejemplo, se utilizará la siguiente función de ayuda para mostrar los objetos de coincidencia con un poco más de elegancia:

def displaymatch(match):
    if match is None:
        return None
    return '<Match: %r, groups=%r>' % (match.group(), match.groups())

Supongamos que se está escribiendo un programa de póquer en el que la mano de un jugador se representa como una cadena de 5 caracteres en la que cada carácter representa una carta, «a» para el as, «k» para el rey, «q» para la reina, «j» para la jota, «t» para el 10, y del » 2» al «9» representando la carta con ese valor.

Para ver si una cadena dada es una mano válida, se podría hacer lo siguiente:

>>> valid = re.compile(r"^[a2-9tjqk]{5}$")
>>> displaymatch(valid.match("akt5q"))  # Valid.
"<Match: 'akt5q', groups=()>"
>>> displaymatch(valid.match("akt5e"))  # Invalid.
>>> displaymatch(valid.match("akt"))    # Invalid.
>>> displaymatch(valid.match("727ak"))  # Valid.
"<Match: '727ak', groups=()>"

Esa última mano, "727ak", contenía un par, o dos de las mismas cartas de valor. Para igualar esto con una expresión regular, se podrían usar referencias inversas como tales:

>>> pair = re.compile(r".*(.).*\1")
>>> displaymatch(pair.match("717ak"))     # Pair of 7s.
"<Match: '717', groups=('7',)>"
>>> displaymatch(pair.match("718ak"))     # No pairs.
>>> displaymatch(pair.match("354aa"))     # Pair of aces.
"<Match: '354aa', groups=('a',)>"

Para averiguar en qué carta consiste el par, se podría utilizar el método group() del objeto de coincidencia de la siguiente manera:

>>> pair = re.compile(r".*(.).*\1")
>>> pair.match("717ak").group(1)
'7'

# Error because re.match() returns None, which doesn't have a group() method:
>>> pair.match("718ak").group(1)
Traceback (most recent call last):
  File "<pyshell#23>", line 1, in <module>
    re.match(r".*(.).*\1", "718ak").group(1)
AttributeError: 'NoneType' object has no attribute 'group'

>>> pair.match("354aa").group(1)
'a'

Simular scanf()

Python no tiene actualmente un equivalente a scanf(). Las expresiones regulares son generalmente más poderosas, aunque también más verbosas, que las cadenas de formato scanf(). La tabla siguiente ofrece algunos mapeos más o menos equivalentes entre tokens de formato scanf() y expresiones regulares.

Token scanf()

Expresión regular

%c

.

%5c

.{5}

%d

[-+]?\d+

%e, %E, %f, %g

[-+]?(\d+(\.\d*)?|\.\d+)([eE][-+]?\d+)?

%i

[-+]?(0[xX][\dA-Fa-f]+|0[0-7]*|\d+)

%o

[-+]?[0-7]+

%s

\S+

%u

\d+

%x, %X

[-+]?(0[xX])?[\dA-Fa-f]+

Para extraer el nombre de archivo y los números de una cadena como

/usr/sbin/sendmail - 0 errors, 4 warnings

se usaría un formato scanf() como

%s - %d errors, %d warnings

La expresión regular equivalente sería

(\S+) - (\d+) errors, (\d+) warnings

search() vs. match()

Python ofrece dos operaciones primitivas diferentes basadas en expresiones regulares: re.match() comprueba si hay una coincidencia sólo al principio de la cadena, mientras que re.search() comprueba si hay una coincidencia en cualquier parte de la cadena (esto es lo que hace Perl por defecto).

Por ejemplo:

>>> re.match("c", "abcdef")    # No match
>>> re.search("c", "abcdef")   # Match
<re.Match object; span=(2, 3), match='c'>

Las expresiones regulares que comienzan con '^' pueden ser usadas con search() para restringir la coincidencia al principio de la cadena:

>>> re.match("c", "abcdef")    # No match
>>> re.search("^c", "abcdef")  # No match
>>> re.search("^a", "abcdef")  # Match
<re.Match object; span=(0, 1), match='a'>

Notar, sin embargo, que en el modo MULTILINE match() sólo coincide al principio de la cadena, mientras que usando search() con una expresión regular que comienza con '^' coincidirá al principio de cada línea.

>>> re.match('X', 'A\nB\nX', re.MULTILINE)  # No match
>>> re.search('^X', 'A\nB\nX', re.MULTILINE)  # Match
<re.Match object; span=(4, 5), match='X'>

Haciendo una guía telefónica

split() divide una cadena en una lista delimitada por el patrón recibido. El método es muy útil para convertir datos textuales en estructuras de datos que pueden ser fácilmente leídas y modificadas por Python, como se demuestra en el siguiente ejemplo en el que se crea una guía telefónica.

Primero, aquí está la información. Normalmente puede venir de un archivo, aquí se usa la sintaxis de cadena de triple comilla

>>> text = """Ross McFluff: 834.345.1254 155 Elm Street
...
... Ronald Heathmore: 892.345.3428 436 Finley Avenue
... Frank Burger: 925.541.7625 662 South Dogwood Way
...
...
... Heather Albrecht: 548.326.4584 919 Park Place"""

Las entradas (entries) están separadas por una o más líneas nuevas. Ahora se convierte la cadena en una lista en la que cada línea no vacía tiene su propia entrada:

>>> entries = re.split("\n+", text)
>>> entries
['Ross McFluff: 834.345.1254 155 Elm Street',
'Ronald Heathmore: 892.345.3428 436 Finley Avenue',
'Frank Burger: 925.541.7625 662 South Dogwood Way',
'Heather Albrecht: 548.326.4584 919 Park Place']

Finalmente, se divide cada entrada en una lista con nombre, apellido, número de teléfono y dirección. Se utiliza el parámetro maxsplit (división máxima) de split() porque la dirección tiene espacios dentro del patrón de división:

>>> [re.split(":? ", entry, 3) for entry in entries]
[['Ross', 'McFluff', '834.345.1254', '155 Elm Street'],
['Ronald', 'Heathmore', '892.345.3428', '436 Finley Avenue'],
['Frank', 'Burger', '925.541.7625', '662 South Dogwood Way'],
['Heather', 'Albrecht', '548.326.4584', '919 Park Place']]

El patrón :? coincide con los dos puntos después del apellido, de manera que no aparezca en la lista de resultados. Con maxsplit de 4, se podría separar el número de casa del nombre de la calle:

>>> [re.split(":? ", entry, 4) for entry in entries]
[['Ross', 'McFluff', '834.345.1254', '155', 'Elm Street'],
['Ronald', 'Heathmore', '892.345.3428', '436', 'Finley Avenue'],
['Frank', 'Burger', '925.541.7625', '662', 'South Dogwood Way'],
['Heather', 'Albrecht', '548.326.4584', '919', 'Park Place']]

Mungear texto

sub() reemplaza cada ocurrencia de un patrón con una cadena o el resultado de una función. Este ejemplo demuestra el uso de sub() con una función para «mungear» (munge) el texto, o aleatorizar el orden de todos los caracteres en cada palabra de una frase excepto el primer y último carácter:

>>> def repl(m):
...     inner_word = list(m.group(2))
...     random.shuffle(inner_word)
...     return m.group(1) + "".join(inner_word) + m.group(3)
>>> text = "Professor Abdolmalek, please report your absences promptly."
>>> re.sub(r"(\w)(\w+)(\w)", repl, text)
'Poefsrosr Aealmlobdk, pslaee reorpt your abnseces plmrptoy.'
>>> re.sub(r"(\w)(\w+)(\w)", repl, text)
'Pofsroser Aodlambelk, plasee reoprt yuor asnebces potlmrpy.'

Encontrar todos los adverbios

findall() coincide con todas las ocurrencias de un patrón, no sólo con la primera, como lo hace search(). Por ejemplo, si un escritor quisiera encontrar todos los adverbios en algún texto, podría usar findall() de la siguiente manera:

>>> text = "He was carefully disguised but captured quickly by police."
>>> re.findall(r"\w+ly\b", text)
['carefully', 'quickly']

Encontrar todos los adverbios y sus posiciones

Si uno quiere más información sobre todas las coincidencias de un patrón en lugar del texto coincidente, finditer() es útil ya que proporciona objetos de coincidencia en lugar de cadenas. Continuando con el ejemplo anterior, si un escritor quisiera encontrar todos los adverbios y sus posiciones en algún texto, usaría finditer() de la siguiente manera:

>>> text = "He was carefully disguised but captured quickly by police."
>>> for m in re.finditer(r"\w+ly\b", text):
...     print('%02d-%02d: %s' % (m.start(), m.end(), m.group(0)))
07-16: carefully
40-47: quickly

Notación de cadena raw

La notación de cadena raw (r "text") permite escribir expresiones regulares razonables. Sin ella, para «escapar» cada barra inversa ('\') en una expresión regular tendría que ser precedida por otra. Por ejemplo, las dos siguientes líneas de código son funcionalmente idénticas:

>>> re.match(r"\W(.)\1\W", " ff ")
<re.Match object; span=(0, 4), match=' ff '>
>>> re.match("\\W(.)\\1\\W", " ff ")
<re.Match object; span=(0, 4), match=' ff '>

Cuando uno quiere igualar una barra inversa literal, debe escaparse en la expresión regular. Con la notación de cadena raw, esto significa r"\\". Sin la notación de cadena, uno debe usar "\\\\", haciendo que las siguientes líneas de código sean funcionalmente idénticas:

>>> re.match(r"\\", r"\\")
<re.Match object; span=(0, 1), match='\\'>
>>> re.match("\\\\", r"\\")
<re.Match object; span=(0, 1), match='\\'>

Escribir un Tokenizador

Un tokenizador o analizador léxico [https://es.wikipedia.org/wiki/Analizador_léxico] analiza una cadena para categorizar grupos de caracteres. Este es un primer paso útil para escribir un compilador o intérprete.

Las categorías de texto se especifican con expresiones regulares. La técnica consiste en combinarlas en una única expresión regular maestra y en hacer un bucle sobre las sucesivas coincidencias:

from typing import NamedTuple
import re

class Token(NamedTuple):
    type: str
    value: str
    line: int
    column: int

def tokenize(code):
    keywords = {'IF', 'THEN', 'ENDIF', 'FOR', 'NEXT', 'GOSUB', 'RETURN'}
    token_specification = [
        ('NUMBER',   r'\d+(\.\d*)?'),  # Integer or decimal number
        ('ASSIGN',   r':='),           # Assignment operator
        ('END',      r';'),            # Statement terminator
        ('ID',       r'[A-Za-z]+'),    # Identifiers
        ('OP',       r'[+\-*/]'),      # Arithmetic operators
        ('NEWLINE',  r'\n'),           # Line endings
        ('SKIP',     r'[ \t]+'),       # Skip over spaces and tabs
        ('MISMATCH', r'.'),            # Any other character
    ]
    tok_regex = '|'.join('(?P<%s>%s)' % pair for pair in token_specification)
    line_num = 1
    line_start = 0
    for mo in re.finditer(tok_regex, code):
        kind = mo.lastgroup
        value = mo.group()
        column = mo.start() - line_start
        if kind == 'NUMBER':
            value = float(value) if '.' in value else int(value)
        elif kind == 'ID' and value in keywords:
            kind = value
        elif kind == 'NEWLINE':
            line_start = mo.end()
            line_num += 1
            continue
        elif kind == 'SKIP':
            continue
        elif kind == 'MISMATCH':
            raise RuntimeError(f'{value!r} unexpected on line {line_num}')
        yield Token(kind, value, line_num, column)

statements = '''
    IF quantity THEN
        total := total + price * quantity;
        tax := price * 0.05;
    ENDIF;
'''

for token in tokenize(statements):
    print(token)

El tokenizador produce el siguiente resultado:

Token(type='IF', value='IF', line=2, column=4)
Token(type='ID', value='quantity', line=2, column=7)
Token(type='THEN', value='THEN', line=2, column=16)
Token(type='ID', value='total', line=3, column=8)
Token(type='ASSIGN', value=':=', line=3, column=14)
Token(type='ID', value='total', line=3, column=17)
Token(type='OP', value='+', line=3, column=23)
Token(type='ID', value='price', line=3, column=25)
Token(type='OP', value='*', line=3, column=31)
Token(type='ID', value='quantity', line=3, column=33)
Token(type='END', value=';', line=3, column=41)
Token(type='ID', value='tax', line=4, column=8)
Token(type='ASSIGN', value=':=', line=4, column=12)
Token(type='ID', value='price', line=4, column=15)
Token(type='OP', value='*', line=4, column=21)
Token(type='NUMBER', value=0.05, line=4, column=23)
Token(type='END', value=';', line=4, column=27)
Token(type='ENDIF', value='ENDIF', line=5, column=4)
Token(type='END', value=';', line=5, column=9)

Frie09

Friedl, Jeffrey. Mastering Regular Expressions. 3a ed., O’Reilly Media, 2009. La tercera edición del libro ya no abarca a Python en absoluto, pero la primera edición cubría la escritura de buenos patrones de expresiones regulares con gran detalle.

difflib — Funciones auxiliares para calcular deltas

Código fuente: Lib/difflib.py [https://github.com/python/cpython/tree/3.9/Lib/difflib.py]

Este módulo proporciona clases y funciones para comparar secuencias. Se puede utilizar, por ejemplo, para comparar archivos y puede producir información sobre diferencias de archivo en varios formatos, incluidos HTML y contexto y diferencias unificadas. Para comparar directorios y archivos, consulte también el módulo filecmp.

class difflib.SequenceMatcher

Esta es una clase flexible para comparar pares de secuencias de cualquier tipo, siempre que los elementos de la secuencia sean hashable. El algoritmo básico es anterior, y un poco mas agradable, que el publicado a fines de los 80” por Ratcliff y Obershelp, bajo el nombre hiperbólico de «gestalt pattern matching». La idea es encontrar la subsecuencia coincidente contigua mas larga que no contenga elementos «no deseados»; estos elementos «no deseados» son aquellos que no son de interés por algún motivo, como ser lineas en blanco o espacios. (El tratamiento de elementos no deseados es una extensión al algoritmo de Ratcliff y Obershelp). La misma idea se aplica recursivamente a las partes de la secuencia a la derecha e izquierda de cada subsecuencia correspondiente. Esto no proporciona secuencias de edición mínimas, pero tiende a producir coincidencias que «parecen correctas» a las personas.

Complejidad temporal: En el peor de los casos el algoritmo Ratcliff-Obershelp básico es de complejidad cúbica y de complejidad temporal cuadrática en el caso esperado. SequenceMatcher es de complejidad temporal cuadrática en el peor de los casos y el comportamiento del caso esperado depende de manera complicada de cuántos elementos tienen en común las secuencias; en el mejor de los casos la complejidad temporal es lineal.

Heurística automática de elementos no deseados: SequenceMatcher implementa un método heurístico que identifica automáticamente a ciertos elementos como no deseados. El método heurístico consiste en contar cuantas veces aparece cada elemento en la secuencia. Si las apariciones del duplicado de un elemento (después del primero) contabilizan mas del 1% de la secuencia, y a su vez la secuencia contiene mas de 200 elementos, este es identificado como «popular» y es considerado no deseado. Este método heurístico puede desactivarse estableciendo el argumento autojunk como False al crear la clase SequenceMatcher.

Nuevo en la versión 3.2: El parámetro autojunk.

class difflib.Differ

Esta clase se utiliza para comparar secuencias de lineas de texto y producir diferencias o deltas en una forma legible por humanos. Differ usa SequenceMatcher tanto para comparar secuencias de lineas, como para comparar secuencias de caracteres entre lineas similares.

Cada linea de un delta de Differ comienza con un código de dos letras:

Código

Significado

'- '

línea única para la secuencia 1

'+ '

línea única para la secuencia 2

'  '

línea común a ambas secuencias

'? '

línea ausente en todas las secuencias de entrada

Las líneas que empiezan con “?” intentan guiar al ojo hacia las diferencias intralíneas, y no estuvieron presentes en ninguna de las secuencias de entrada. Estas líneas pueden ser confusas si la secuencia contiene caracteres de tabulación.

class difflib.HtmlDiff

Esta clase puede ser usada para crear una tabla HTML (o un archivo HTML completo que contenga la tabla) mostrando comparaciones lado a lado y linea por linea del texto, con cambios interlineales e intralineales. La tabla se puede generar en modo de diferencia completa o contextual.

El constructor de esta clase es:

__init__(tabsize=8, wrapcolumn=None, linejunk=None, charjunk=IS_CHARACTER_JUNK)

Inicializa una instancia de HtmlDiff.

tabsize es un argumento por palabra clave opcional para especificar el espaciado de tabulación. Su valor predeterminado es 8.

wrapcolumn es un argumento por palabra clave opcional para especificar el número de columnas donde las lineas serán divididas y ajustadas al ancho de columna, su valor por defecto es None, donde las lineas no son ajustadas.

linejunk y charjunk son argumentos por palabra clave opcionales que serán pasados a ndiff() (que es utilizado por HtmlDiff para generar las diferencias lado a lado en HTML). Refiérase a la documentación de ndiff() para conocer los detalles y valores por defecto de sus argumentos.

Los siguientes métodos son públicos:

make_file(fromlines, tolines, fromdesc='', todesc='', context=False, numlines=5, *, charset='utf-8')

Compara fromlines y tolines (listas de cadenas de texto) y retorna una cadena de caracteres que representa un archivo HTML completo que contiene una tabla mostrando diferencias línea por línea del texto con cambios interlineales e intralineales resaltados.

fromdesc y todesc son argumentos por palabra clave opcionales para especificar los encabezados de las columnas desde fromdesc hasta todesc en el archivo (ambas cadenas están vacías por defecto).

context y numlines son parámetros opcionales. Establezca context como True para mostrar diferencias contextuales, de lo contrario su valor por defecto es False que muestra los archivos completos. El valor por defecto de numlines es 5. Cuando context es True, numlines controla el número de lineas de contexto que rodean las diferencias resaltadas. Cuando context es False, numlines controla el número de líneas que se muestran antes de una diferencia resaltada cuando se usan los hipervínculos «next» (un valor de cero produce que los hipervínculos «next» ubiquen el siguiente resaltado en la parte superior del navegador, sin ningún contexto principal).

Nota

fromdesc y todesc se interpretan como HTML no escapado y se deben escapar correctamente si los datos son recibidos de fuentes no confiables.

Distinto en la versión 3.5: Se agregó el argumento sólo de palabra clave charset. La codificación de caracteres por defecto para documentos HTML se cambió de 'ISO-8859-1' a 'utf-8'.

make_table(fromlines, tolines, fromdesc='', todesc='', context=False, numlines=5)

Compara fromlines y tolines (listas de cadenas de texto) y retorna una cadena de caracteres que representa una tabla HTML mostrando comparaciones lado a lado y línea por línea del texto con cambios interlineales e intralineales.

Los argumentos para este método son los mismos que los del método make_file().

Tools/scripts/diff.py es una herramienta de línea de comandos para esta clase y contiene un buen ejemplo sobre su uso.

difflib.context_diff(a, b, fromfile='', tofile='', fromfiledate='', tofiledate='', n=3, lineterm='\n')

Compara a y b (listas de cadenas de texto); retorna un delta (un generator que genera las lineas delta) en formato de diferencias de contexto.

El formato de diferencias de contexto es una forma compacta de mostrar solamente las líneas que fueron modificadas y algunas líneas adicionales de contexto. Los cambios son mostrados utilizando el estilo antes/después. El número de líneas de contexto es determinado por n, cuyo valor por defecto es 3.

Por defecto, las líneas de control (aquellas que comienzan con *** o ---) son creadas con una línea nueva. Esto es de ayuda para que las entradas creadas por io.IOBase.readlines() generen diferencias que puedan ser utilizadas con io.IOBase.writelines() ya que ambas, la entrada y la salida, tienen líneas nuevas al final.

Para entradas que no tienen nuevas líneas finales, establezca el argumento lineterm como "" de forma que la salida sea uniforme y libre de nuevas líneas.

El formato de diferencias de contexto normalmente tiene un encabezado para nombres de archivos y tiempos de modificaciones. Alguno o todos estos debe ser especificado utilizando las cadenas de texto para fromfile, tofile, fromfiledate y tofiledate. Los tiempos de modificación son normalmente expresados en formato ISO 8601. Si no es especificado las cadenas por defecto son espacios en blanco.

>>> s1 = ['bacon\n', 'eggs\n', 'ham\n', 'guido\n']
>>> s2 = ['python\n', 'eggy\n', 'hamster\n', 'guido\n']
>>> sys.stdout.writelines(context_diff(s1, s2, fromfile='before.py', tofile='after.py'))
*** before.py
--- after.py
***************
*** 1,4 ****
! bacon
! eggs
! ham
  guido
--- 1,4 ----
! python
! eggy
! hamster
  guido

Vea Una interfaz de línea de comandos para difflib para un ejemplo mas detallado.

difflib.get_close_matches(word, possibilities, n=3, cutoff=0.6)

Retorna una lista de las mejores coincidencias «lo suficientemente buenas». word es una secuencia para la cual coincidencias cercanas son deseadas (usualmente una cadena de texto), y possibilities es una lista de secuencias contra la cual se compara word (comúnmente una lista de cadenas de caracteres).

Argumento opcional n (por defecto 3) es el máximo número de coincidencias cercanas a retornar; n debe ser mayor que 0.

Argumento opcional cutoff (por defecto 0.6) es un flotante en el rango [0, 1]. Las posibilidades que no alcanzan un puntaje al menos similar al de word son ignoradas.

Las mejores (no mas de n) coincidencias entre las posibilidades son retornadas en una lista, ordenadas por similitud de puntaje, las mas similares primero.

>>> get_close_matches('appel', ['ape', 'apple', 'peach', 'puppy'])
['apple', 'ape']
>>> import keyword
>>> get_close_matches('wheel', keyword.kwlist)
['while']
>>> get_close_matches('pineapple', keyword.kwlist)
[]
>>> get_close_matches('accept', keyword.kwlist)
['except']

difflib.ndiff(a, b, linejunk=None, charjunk=IS_CHARACTER_JUNK)

Compara a y b (listas de cadenas de texto); retorna un delta del estilo Differ (un generator que genera los deltas de las líneas).

Parámetros de palabra clave opcional linejunk y charjunk son funciones de filtrado (o None):

linejunk: Una función que acepta una sola cadena de caracteres como argumento, y retorna verdadero si la cadena de texto es un elemento no deseado, o falso si no lo es. Su valor por defecto es None. Hay también una función a nivel del módulo IS_LINE_JUNK(), que filtra líneas sin caracteres visibles, excepto como mucho un carácter de libra ('#') – de cualquier forma la clase subyacente SequenceMatcher realiza un análisis dinámico sobre cuáles lineas son tan frecuentes como para constituir ruido, y esto usualmente funciona mejor que utilizando esta función.

charjunk: Una función que acepta un carácter (una cadena de caracteres de longitud 1) como argumento, y retorna True si el carácter es un elemento no deseado, o False si no lo es. El valor por defecto es una función a nivel del módulo IS_CHARACTER_JUNK(), que filtra caracteres de espacios en blanco (un espacio en blanco o tabulación; es una mala idea incluir saltos de lineas en esto!)

Tools/scripts/ndiff.py es una interfaz de línea de comandos para esta función.

>>> diff = ndiff('one\ntwo\nthree\n'.splitlines(keepends=True),
...              'ore\ntree\nemu\n'.splitlines(keepends=True))
>>> print(''.join(diff), end="")
- one
?  ^
+ ore
?  ^
- two
- three
?  -
+ tree
+ emu

difflib.restore(sequence, which)

Retorna uno de las dos secuencias que generaron un delta.

Dada una sequence producida por Differ.compare() o ndiff(), extrae las líneas originadas por el archivo 1 o 2 (parámetro which), quitando los prefijos de la línea.

Ejemplo:

>>> diff = ndiff('one\ntwo\nthree\n'.splitlines(keepends=True),
...              'ore\ntree\nemu\n'.splitlines(keepends=True))
>>> diff = list(diff) # materialize the generated delta into a list
>>> print(''.join(restore(diff, 1)), end="")
one
two
three
>>> print(''.join(restore(diff, 2)), end="")
ore
tree
emu

difflib.unified_diff(a, b, fromfile='', tofile='', fromfiledate='', tofiledate='', n=3, lineterm='\n')

Compara a y b (listas de cadenas de caracteres); retorna un delta (un generator que genera los delta de líneas) en formato de diferencias unificado.

Las diferencias unificadas son una forma compacta de mostrar sólo las líneas que presentan cambios y algunas líneas de contexto adicionales. Los cambios son mostrados en una sola línea (en lugar de bloques separados antes y después). El número de líneas de contexto se establece mediante n, cuyo valor por defecto es tres.

Por defecto, las líneas de control de diferencias (aquellas con ---, +++, o @@) son creadas con un salto de línea nuevo. Esto es de ayuda para que las entradas creadas por io.IOBase.readlines() generen diferencias que puedan ser utilizadas con io.IOBase.writelines() ya que ambas, la entrada y la salida, tienen líneas nuevas al final.

Para entradas que no tienen nuevas líneas finales, establezca el argumento lineterm como "" de forma que la salida sea uniforme y libre de nuevas líneas.

El formato de diferencias de contexto normalmente tiene un encabezado para nombres de archivos y tiempos de modificaciones. Alguno o todos estos debe ser especificado utilizando las cadenas de texto para fromfile, tofile, fromfiledate y tofiledate. Los tiempos de modificación son normalmente expresados en formato ISO 8601. Si no es especificado las cadenas por defecto son espacios en blanco.

>>> s1 = ['bacon\n', 'eggs\n', 'ham\n', 'guido\n']
>>> s2 = ['python\n', 'eggy\n', 'hamster\n', 'guido\n']
>>> sys.stdout.writelines(unified_diff(s1, s2, fromfile='before.py', tofile='after.py'))
--- before.py
+++ after.py
@@ -1,4 +1,4 @@
-bacon
-eggs
-ham
+python
+eggy
+hamster
 guido

Vea Una interfaz de línea de comandos para difflib para un ejemplo mas detallado.

difflib.diff_bytes(dfunc, a, b, fromfile=b'', tofile=b'', fromfiledate=b'', tofiledate=b'', n=3, lineterm=b'\n')

Compara a y b (listas de objetos de bytes) usando dfunc; produce una secuencia de líneas delta (también bytes) en el formato retornado por dfunc. dfunc debe ser invocable, comúnmente cualquiera de unified_diff() o context_diff().

Permite comparar datos con codificación desconocida o inconsistente. Todas las entradas, excepto n, deben ser objetos de bytes, no cadenas de texto. Funciona convirtiendo sin pérdidas todas las entradas (excepto n) a cadenas de texto, e invoca dfunc(a, b, fromfile, tofile, fromfiledate, tofiledate, n, lineterm). La salida de dfunc es entonces convertida nuevamente a bytes, de forma que las líneas delta que son recibidas tienen la misma codificación desconocida/inconsistente que a y b.

Nuevo en la versión 3.5.

difflib.IS_LINE_JUNK(line)

Retorna True para líneas que deben ser ignoradas. La línea line es ignorada si line es un espacio vacío o contiene un solo '#', en cualquier otro caso no es ignorado. Es usado como valor por defecto para el parámetro linejunk por ndiff() en versiones anteriores.

difflib.IS_CHARACTER_JUNK(ch)

Retorna True para los caracteres que deben ser ignorados. El carácter ch es ignorado si ch es un espacio en blanco o tabulación, en cualquier otro caso no es ignorado. Es utilizado como valor por defecto para el parámetro charjunk en ndiff().

Ver también

Pattern Matching: The Gestalt Approach [http://www.drdobbs.com/database/pattern-matching-the-gestalt-approach/184407970]

Discusión de un algoritmo similar por John W. Ratcliff y D. E. Metzener. Esto fue publicado en Dr. Dobb’s Journal [http://www.drdobbs.com/] en Julio de 1988.

Objetos SequenceMatcher

La clase SequenceMatcher tiene este constructor:

class difflib.SequenceMatcher(isjunk=None, a='', b='', autojunk=True)

El argumento opcional isjunk debe ser None (que es su valor por defecto) o una función de un solo argumento que reciba un elemento de la secuencia y retorne verdadero si y solo si el elemento es no deseado y deba ser ignorado. Pasar el argumento isjunk como None es equivalente a pasar lambda x: False; en otras palabras, ningún elemento es ignorado. Por ejemplo, pasar:

lambda x: x in " \t"

si se están comparando líneas como secuencias de caracteres, y no se quiere sincronizar en espacios blancos o tabulaciones.

Los argumentos opcionales a y b son las secuencias a comparar; ambos tienen como valor por defecto una cadena de texto vacía. Los elementos de ambas secuencias deben ser hashable.

El argumento opcional autojunk puede ser usado para deshabilitar la heurística automática de elementos no deseados.

Nuevo en la versión 3.2: El parámetro autojunk.

Los objetos SequenceMatcher reciben tres atributos: bjunk es el conjunto de elementos de b para los cuales isjunk es True; bpopular es el set de elementos que no son basura considerados populares por la heurística (si no es que fue deshabilitada); b2j es un diccionario que mapea elementos de b a una lista de posiciones donde estos ocurren. Los tres atributos son reseteados cuando b es reseteado mediante set_seqs() o set_seq2().

Nuevo en la versión 3.2: Los atributos bjunk y bpopular.

Los objetos SequenceMatcher tienen los siguientes métodos:

set_seqs(a, b)

Establece las dos secuencias a ser comparadas.

SequenceMatcher calcula y almacena información detallada sobre la segunda secuencia, con lo cual si quieres comparar una secuencia contra muchas otras, usa set_seq2() para establecer la secuencia común una sola vez y llamar set_seq1() repetidamente, una vez por cada una de las otras secuencias.

set_seq1(a)

Establece la primer secuencia a ser comparada. La segunda secuencia a ser comparada no es modificada.

set_seq2(b)

Establece la segunda secuencia a ser comparada. La primera secuencia a ser comparada no es modificada.

find_longest_match(alo=0, ahi=None, blo=0, bhi=None)

Encuentra el bloque de coincidencia mas largo en a[alo:ahi] y b[blo:bhi].

Si isjunk fue omitido o es None, find_longest_match() retorna (i, j, k) tal que a[i:i+k] es igual a b[j:j+k], donde alo <= i <= i+k <= ahi y blo <= j <= j+k <= bhi. Para todo (i', j', k') cumpliendo esas condiciones, las condiciones adicionales k >= k', i <= i', y si i == i', j <= j' también se cumplen. En otras palabras, de todos los bloques coincidentes máximos, retorna aquel que comienza antes en a, y de todos esos bloques coincidentes máximos que comienzan antes en a, retorna aquel que comienza antes en b.

>>> s = SequenceMatcher(None, " abcd", "abcd abcd")
>>> s.find_longest_match(0, 5, 0, 9)
Match(a=0, b=4, size=5)

Si se porporcionó isjunk, primero se determina el bloque coincidente mas largo como fue indicado anteriormente, pero con la restricción adicional de que no aparezca ningún elemento no deseado en el bloque. Entonces, ese bloque se extiende tan lejos como sea posible haciendo coincidir (solo) elementos no deseados de ambos lados. Por lo tanto, el bloque resultante nunca hará coincidir ningún elemento no deseado, excepto que un elemento no deseado idéntico pase a ser adyacente a una coincidencia interesante.

Este es el mismo ejemplo que el mostrado anteriormente, pero considerando elementos en blanco como no deseados. Esto previene que ' abcd' sea coincidente con 'abcd' en el final de la segunda secuencia directamente. En cambio, sólo el 'abcd' puede coincidir, y coincide con el 'abcd' que se encuentre mas a la izquierda en la segunda secuencia:

>>> s = SequenceMatcher(lambda x: x==" ", " abcd", "abcd abcd")
>>> s.find_longest_match(0, 5, 0, 9)
Match(a=1, b=0, size=4)

Si no coincide ningún bloque, esto retorna (alo, blo, 0).

Este método retorna un named tuple Match(a, b, size).

Distinto en la versión 3.9: Se agregaron argumentos predeterminados.

get_matching_blocks()

Retorna una lista de triplas (tuplas de tres elementos) describiendo subsecuencias coincidentes no superpuestas. Cada tripla sigue el formato (i, j, n), y significa que a[i:i+n] == b[j:j+n]. Las triplas son monótonamente crecientes en i y j.

La última tripla es un objeto ficticio (dummy), y tiene el valor (len(a), len(b), 0). Es la única tripla con n == 0. Si (i, j, n) y (i', j', n') son triplas adyacentes en la lista, y la segunda no es el último elemento de la lista, entonces i+n < i' o j+n < j'; en otras palabras, las triplas adyacentes describen bloques iguales no adyacentes.

>>> s = SequenceMatcher(None, "abxcd", "abcd")
>>> s.get_matching_blocks()
[Match(a=0, b=0, size=2), Match(a=3, b=2, size=2), Match(a=5, b=4, size=0)]

get_opcodes()

Retorna una lista de quíntuplas (tuplas de cinco elementos) describiendo como convertir a en b. Cada tupla tiene la forma (tag, i1, i2, j1, j2). En la primer tupla se cumple que i1 == j1 == 0, y las tuplas restantes tienen i1 igual al i2 de la tupla precedente, y de igual manera, j1 igual al j2 de la tupla anterior.

Los valores de tag son cadenas de caracteres, con el siguiente significado:

Valor

Significado

'replace'

a[i1:i2] debe ser reemplazado por b[j1:j2].

'delete'

a[i1:i2] debe ser eliminado. Nótese que en este caso j1 == j2.

'insert'

b[j1:j2] debe ser insertado en a[i1:i1]. Nótese que en este caso i1 == i2.

'equal'

a[i1:i2] == b[j1:j2] (las subsecuencias son iguales).

Por ejemplo:

>>> a = "qabxcd"
>>> b = "abycdf"
>>> s = SequenceMatcher(None, a, b)
>>> for tag, i1, i2, j1, j2 in s.get_opcodes():
...     print('{:7}   a[{}:{}] --> b[{}:{}] {!r:>8} --> {!r}'.format(
...         tag, i1, i2, j1, j2, a[i1:i2], b[j1:j2]))
delete    a[0:1] --> b[0:0]      'q' --> ''
equal     a[1:3] --> b[0:2]     'ab' --> 'ab'
replace   a[3:4] --> b[2:3]      'x' --> 'y'
equal     a[4:6] --> b[3:5]     'cd' --> 'cd'
insert    a[6:6] --> b[5:6]       '' --> 'f'

get_grouped_opcodes(n=3)

Retorna un generator de grupos de hasta n líneas de contexto.

Empezando con los grupos retornados por get_opcodes(), este método separa grupos con cambios menores y elimina los rangos intermedios que no tienen cambios.

Los grupos son retornados en el mismo formato que get_opcodes().

ratio()

Retorna una medida de la similitud de las secuencias como un flotante en el rango [0, 1].

Donde T es el número total de elementos en ambas secuencias y M es el número de coincidencias, esto es 2.0*M / T. Nótese que esto es 1.0 si las secuencias son idénticas y 0.0 si no tienen nada en común.

Esto es computacionalmente costoso si get_matching_blocks() o get_opcodes() no fueron ejecutados, in tal caso deberías considerar primero quick_ratio() o real_quick_ratio() para obtener un límite superior.

Nota

Precaución: El resultado de una llamada a ratio() puede depender del orden de los argumentos. Por ejemplo:

>>> SequenceMatcher(None, 'tide', 'diet').ratio()
0.25
>>> SequenceMatcher(None, 'diet', 'tide').ratio()
0.5

quick_ratio()

Retorna un límite superior en ratio() relativamente rápido.

real_quick_ratio()

Retorna un límite superior en ratio() muy rápido.

Los tres métodos que retornan la proporción de coincidencias con el total de caracteres pueden dar diferentes resultados debido a los distintos niveles de aproximación, a pesar de que quick_ratio() y real_quick_ratio() son siempre al menos tan grandes como ratio():

>>> s = SequenceMatcher(None, "abcd", "bcde")
>>> s.ratio()
0.75
>>> s.quick_ratio()
0.75
>>> s.real_quick_ratio()
1.0

SequenceMatcher Ejemplos

Este ejemplo compara dos cadenas de texto, considerando los espacios en blanco como caracteres no deseados:

>>> s = SequenceMatcher(lambda x: x == " ",
...                     "private Thread currentThread;",
...                     "private volatile Thread currentThread;")

ratio() retorna un flotante en el rango [0, 1], cuantificando la similitud entre las secuencias. Siguiendo la regla del pulgar, un ratio() por encima de 0.6 significa que las secuencias son coincidencias cercanas:

>>> print(round(s.ratio(), 3))
0.866

Si solamente estás interesado en cuándo las secuencias coinciden, get_matching_blocks() es útil:

>>> for block in s.get_matching_blocks():
...     print("a[%d] and b[%d] match for %d elements" % block)
a[0] and b[0] match for 8 elements
a[8] and b[17] match for 21 elements
a[29] and b[38] match for 0 elements

Nótese que la última tupla retornada por get_matching_blocks() es siempre un objeto ficticio (dummy), (len(a), len(b), 0), y este es el único caso en el cual el último elemento de la tupla (el número de elementos coincidentes) es 0.

Si quieres saber como cambiar la primer secuencia con la segunda, usa get_opcodes():

>>> for opcode in s.get_opcodes():
...     print("%6s a[%d:%d] b[%d:%d]" % opcode)
 equal a[0:8] b[0:8]
insert a[8:8] b[8:17]
 equal a[8:29] b[17:38]

Ver también

La función get_close_matches() en este módulo que muestra lo simple que es el código que construye SequenceMatcher puede ser utilizada para hacer un trabajo útil.

Una receta simple de un controlador de versiones [https://code.activestate.com/recipes/576729/] para una aplicación pequeña construida con SequenceMatcher.

Objetos Differ

Nótese que los deltas generados por Differ no dicen ser diferencias mínimas. Todo lo contrario, las diferencias mínimas suelen ser contra-intuitivas, ya que se sincronizan en cualquier lugar posible, a veces coinciden accidentalmente con 100 páginas de diferencia. Restringiendo los puntos de sincronización a coincidencias contiguas se preserva cierta noción de cercanía, con el costo adicional de producir diferencias mas largas.

La clase Differ tiene el siguiente constructor:

class difflib.Differ(linejunk=None, charjunk=None)

Parámetros de palabra clave opcionales linejunk y charjunk son para funciones de filtrado (o None):

linejunk: Una función que acepta una sola cadena de texto como argumento y retorna verdadero si la cadena de texto es un elemento no deseado. Su valor por defecto es None, lo que significa que ninguna línea es considerada no deseada.

charjunk: Una función que acepta un solo carácter como argumento (una cadena de caracteres de longitud 1) y retorna verdadero si el carácter es un elemento no deseado. Su valor por defecto es None, lo que significa que ningún carácter es considerado no deseado.

Estas funciones de elementos no deseados aceleran la coincidencia para encontrar diferencies y no hacen que se ignoren líneas o caracteres diferentes. Lea la descripción del parámetro isjunk en el método find_longest_match() para una explicación mas detallada.

Los objetos Differ son usados (una vez generados los deltas) mediante un solo método:

compare(a, b)

Compara dos secuencias de líneas y genera el delta correspondiente (una secuencia de líneas).

Cada secuencia debe contener cadenas de texto individuales de una sola linea terminadas con una línea nueva. Este tipo de secuencias pueden ser obtenidas mediante el método readlines() de objetos de tipo archivo. Los delta generados consisten también en cadenas de texto terminadas en nuevas lineas, listas para imprimirse tal cual a través del método writelines() de un objeto de tipo archivo.

Ejemplo de Differ

Este ejemplo compara dos textos. Primero preparamos los textos, secuencias de cadenas de texto individuales de una sola línea terminadas con una línea nueva (este tipo de secuencias también pueden ser obtenidas mediante el método readlines() de objetos de tipo archivo):

>>> text1 = '''  1. Beautiful is better than ugly.
...   2. Explicit is better than implicit.
...   3. Simple is better than complex.
...   4. Complex is better than complicated.
... '''.splitlines(keepends=True)
>>> len(text1)
4
>>> text1[0][-1]
'\n'
>>> text2 = '''  1. Beautiful is better than ugly.
...   3.   Simple is better than complex.
...   4. Complicated is better than complex.
...   5. Flat is better than nested.
... '''.splitlines(keepends=True)

Luego instanciamos el objeto Differ:

>>> d = Differ()

Nótese que cuando instanciamos un objeto Differ deberíamos pasar funciones para filtrar lineas y caracteres no deseados. Consulte el constructor de Differ() para mas detalles.

Finalmente, comparamos las dos:

>>> result = list(d.compare(text1, text2))

result es una lista de cadenas de caracteres, entonces vamos a mostrarlo de una forma elegante:

>>> from pprint import pprint
>>> pprint(result)
['    1. Beautiful is better than ugly.\n',
 '-   2. Explicit is better than implicit.\n',
 '-   3. Simple is better than complex.\n',
 '+   3.   Simple is better than complex.\n',
 '?     ++\n',
 '-   4. Complex is better than complicated.\n',
 '?            ^                     ---- ^\n',
 '+   4. Complicated is better than complex.\n',
 '?           ++++ ^                      ^\n',
 '+   5. Flat is better than nested.\n']

Representado como una sola cadena de caracteres de múltiples líneas se ve así:

>>> import sys
>>> sys.stdout.writelines(result)
    1. Beautiful is better than ugly.
-   2. Explicit is better than implicit.
-   3. Simple is better than complex.
+   3.   Simple is better than complex.
?     ++
-   4. Complex is better than complicated.
?            ^                     ---- ^
+   4. Complicated is better than complex.
?           ++++ ^                      ^
+   5. Flat is better than nested.

Una interfaz de línea de comandos para difflib

Este ejemplo muestra como usar difflib para crear una herramienta de diferencias. También puedes encontrarla en la distribución estándar de Python como Tools/scripts/diff.py.

#!/usr/bin/env python3
""" Command line interface to difflib.py providing diffs in four formats:

* ndiff:    lists every line and highlights interline changes.
* context:  highlights clusters of changes in a before/after format.
* unified:  highlights clusters of changes in an inline format.
* html:     generates side by side comparison with change highlights.

"""

import sys, os, difflib, argparse
from datetime import datetime, timezone

def file_mtime(path):
    t = datetime.fromtimestamp(os.stat(path).st_mtime,
                               timezone.utc)
    return t.astimezone().isoformat()

def main():

    parser = argparse.ArgumentParser()
    parser.add_argument('-c', action='store_true', default=False,
                        help='Produce a context format diff (default)')
    parser.add_argument('-u', action='store_true', default=False,
                        help='Produce a unified format diff')
    parser.add_argument('-m', action='store_true', default=False,
                        help='Produce HTML side by side diff '
                             '(can use -c and -l in conjunction)')
    parser.add_argument('-n', action='store_true', default=False,
                        help='Produce a ndiff format diff')
    parser.add_argument('-l', '--lines', type=int, default=3,
                        help='Set number of context lines (default 3)')
    parser.add_argument('fromfile')
    parser.add_argument('tofile')
    options = parser.parse_args()

    n = options.lines
    fromfile = options.fromfile
    tofile = options.tofile

    fromdate = file_mtime(fromfile)
    todate = file_mtime(tofile)
    with open(fromfile) as ff:
        fromlines = ff.readlines()
    with open(tofile) as tf:
        tolines = tf.readlines()

    if options.u:
        diff = difflib.unified_diff(fromlines, tolines, fromfile, tofile, fromdate, todate, n=n)
    elif options.n:
        diff = difflib.ndiff(fromlines, tolines)
    elif options.m:
        diff = difflib.HtmlDiff().make_file(fromlines,tolines,fromfile,tofile,context=options.c,numlines=n)
    else:
        diff = difflib.context_diff(fromlines, tolines, fromfile, tofile, fromdate, todate, n=n)

    sys.stdout.writelines(diff)

if __name__ == '__main__':
    main()

textwrap — Envoltura y relleno de texto

Source code: Lib/textwrap.py [https://github.com/python/cpython/tree/3.9/Lib/textwrap.py]

El módulo textwrap proporciona algunas funciones de conveniencia, así como TextWrapper, la clase que hace todo el trabajo. Si sólo estás envolviendo o rellenando una o dos cadenas de texto, las funciones de conveniencia deberían ser lo suficientemente buenas; de lo contrario, deberías usar una instancia de TextWrapper para mayor eficiencia.

textwrap.wrap(text, width=70, *, initial_indent="", subsequent_indent="", expand_tabs=True, replace_whitespace=True, fix_sentence_endings=False, break_long_words=True, drop_whitespace=True, break_on_hyphens=True, tabsize=8, max_lines=None, placeholder=' [...]')

Envuelve el párrafo individual en text (una cadena) para que cada línea tenga como máximo width de caracteres de largo. Retorna una lista de líneas de salida, sin las nuevas líneas finales.

Optional keyword arguments correspond to the instance attributes of TextWrapper, documented below.

Ver el método TextWrapper.wrap() para más detalles sobre el comportamiento de wrap().

textwrap.fill(text, width=70, *, initial_indent="", subsequent_indent="", expand_tabs=True, replace_whitespace=True, fix_sentence_endings=False, break_long_words=True, drop_whitespace=True, break_on_hyphens=True, tabsize=8, max_lines=None, placeholder=' [...]')

Envuelve el único párrafo en text, y retorna una sola cadena que contiene el párrafo envuelto. fill() es la abreviatura de

"\n".join(wrap(text, ...))

En particular, fill() acepta exactamente los mismos argumentos de palabras clave que wrap().

textwrap.shorten(text, width, *, fix_sentence_endings=False, break_long_words=True, break_on_hyphens=True, placeholder=' [...]')

Colapsa y trunca el text dado para que encaje en el width dado.

Primero el espacio blanco en text se colapsa (todos los espacios blancos son reemplazados por espacios sencillos). Si el resultado cabe en el width, se retorna. En caso contrario, se eliminan suficientes palabras del final para que las palabras restantes más el placeholder encajen dentro de width:

>>> textwrap.shorten("Hello  world!", width=12)
'Hello world!'
>>> textwrap.shorten("Hello  world!", width=11)
'Hello [...]'
>>> textwrap.shorten("Hello world", width=10, placeholder="...")
'Hello...'

Los argumentos opcionales de las palabras clave corresponden a los atributos de la instancia de TextWrapper, documentados a continuación. Observe que el espacio en blanco se colapsa antes de pasar el texto a la función TextWrapper fill(), por lo que cambiar el valor de tabsize, expand_tabs, drop_whitespace, y replace_whitespace no tendrá ningún efecto.

Nuevo en la versión 3.4.

textwrap.dedent(text)

Elimina cualquier espacio en blanco común de cada línea de text.

Esto puede utilizarse para hacer que las cadenas con comillas triples se alineen con el borde izquierdo de la pantalla, mientras que se siguen presentando en el código fuente en forma indentada.

Nótese que los tabuladores y los espacios se tratan como espacios en blanco, pero no son iguales: las líneas "  hello" y "\thello" se consideran que no tienen un espacio en blanco común.

Las líneas que sólo contienen espacios en blanco se ignoran en la entrada y se normalizan a un solo carácter de nueva línea en la salida.

Por ejemplo:

def test():
    # end first line with \ to avoid the empty line!
    s = '''\
    hello
      world
    '''
    print(repr(s))          # prints '    hello\n      world\n    '
    print(repr(dedent(s)))  # prints 'hello\n  world\n'

textwrap.indent(text, prefix, predicate=None)

Añade prefix al principio de las líneas seleccionadas en text.

Las líneas se separan llamando a text.splitlines(True).

Por defecto, se añade prefix a todas las líneas que no consisten únicamente en espacios en blanco (incluyendo cualquier terminación de línea).

Por ejemplo:

>>> s = 'hello\n\n \nworld'
>>> indent(s, '  ')
'  hello\n\n \n  world'

El argumento opcional predicate puede ser usado para controlar qué líneas están indentadas. Por ejemplo, es fácil añadir prefix incluso a las líneas vacías y de espacio en blanco:

>>> print(indent(s, '+ ', lambda line: True))
+ hello
+
+
+ world

Nuevo en la versión 3.3.

wrap(), fill() y shorten() funcionan creando una instancia TextWrapper y llamando a un solo método en ella. Esa instancia no se reutiliza, por lo que para las aplicaciones que procesan muchas cadenas de texto usando wrap() y/o fill(), puede ser más eficiente crear su propio objeto TextWrapper.

El texto se envuelve preferentemente en espacios en blanco y justo después de los guiones en palabras con guión; sólo entonces se romperán las palabras largas si es necesario, a menos que TextWrapper.break_long_words sea falso.

class textwrap.TextWrapper(**kwargs)

El constructor TextWrapper acepta un número de argumentos de palabras clave opcionales. Cada argumento de palabra clave corresponde a un atributo de la instancia, por ejemplo

wrapper = TextWrapper(initial_indent="* ")

es lo mismo que

wrapper = TextWrapper()
wrapper.initial_indent = "* "

Puedes reutilizar el mismo objeto TextWrapper muchas veces, y puedes cambiar cualquiera de sus opciones a través de la asignación directa de atributos de instancia entre usos.

Los atributos de la instancia TextWrapper (y los argumentos de las palabras clave para el constructor) son los siguientes:

width

(default: 70) La longitud máxima de las líneas envueltas. Mientras no haya palabras individuales en el texto de entrada más largas que width, TextWrapper garantiza que ninguna línea de salida será más larga que los caracteres width.

expand_tabs

(default: True) Si es verdadero, entonces todos los caracteres de tabulación en text serán expandidos a espacios usando el método expandtabs() de text.

tabsize

(default: 8) Si expand_tabs es verdadero, entonces todos los caracteres de tabulación en text se expandirán a cero o más espacios, dependiendo de la columna actual y el tamaño de tabulación dado.

Nuevo en la versión 3.3.

replace_whitespace

(default: True) Si es verdadero, después de la expansión por tabulador pero antes de envolver, el método wrap() reemplazará cada carácter de espacio en blanco con un espacio sencillo. Los caracteres de los espacios en blanco reemplazados son los siguientes: tab, nueva línea, tab vertical, formfeed y carriage return ('\t\n\v\f\r').

Nota

Si expand_tabs es falso y replace_whitespace es verdadero, cada carácter del tabulador será reemplazado por un solo espacio, que no es lo mismo que la expansión del tabulador.

Nota

Si replace_whitespace es falso, las nuevas líneas pueden aparecer en medio de una línea y causar una salida extraña. Por esta razón, el texto debe ser dividido en párrafos (usando str.splitlines() o similar) que se envuelven por separado.

drop_whitespace

(default: True) Si es verdadero, se eliminan los espacios en blanco al principio y al final de cada línea (después de la envoltura pero antes del indentado). Sin embargo, el espacio en blanco al principio del párrafo no se elimina si lo sigue un espacio en blanco. Si el espacio blanco que se deja caer ocupa una línea entera, se deja caer toda la línea.

initial_indent

(default: '') Cadena que será preparada para la primera línea de salida envuelta. Cuenta hacia la longitud de la primera línea. La cadena vacía no está indentada.

subsequent_indent

(default: '') Cadena que se preparará para todas las líneas de salida envueltas excepto la primera. Cuenta hacia la longitud de cada línea excepto la primera.

fix_sentence_endings

(default: False) Si es verdadero, TextWrapper intenta detectar los finales de las frases y asegurarse de que las frases estén siempre separadas por dos espacios exactos. Esto es generalmente deseado para el texto en una fuente monoespaciada. Sin embargo, el algoritmo de detección de oraciones es imperfecto: asume que el final de una oración consiste en una letra minúscula seguida de una de '.', '!', o '?', posiblemente seguida de una de '"' o "'", seguida de un espacio. Un problema de este algoritmo es que no puede detectar la diferencia entre «Dr.» en

[...] Dr. Frankenstein's monster [...]

y «Spot.» en:

[...] See Spot. See Spot run [...]

fix_sentence_endings es falso por defecto.

Dado que el algoritmo de detección de oraciones se basa en string.lowercase para la definición de «letra en minúscula», y en la convención de utilizar dos espacios después de un punto para separar las oraciones en la misma línea, es específico para los textos en inglés.

break_long_words

(default: True) Si es verdadero, entonces las palabras más largas que width se romperán para asegurar que ninguna línea sea más larga que width. Si es falso, las palabras largas no se romperán, y algunas líneas pueden ser más largas que width. (Las palabras largas se pondrán en una línea por sí mismas, para minimizar la cantidad en que se excede width).

break_on_hyphens

(predeterminado: True) Si es verdadero, el ajuste se producirá preferiblemente en espacios en blanco y justo después de los guiones en palabras compuestas, como es habitual en inglés. Si es falso, solo los espacios en blanco se considerarán lugares potencialmente buenos para los saltos de línea, pero debe establecer break_long_words en falso si desea palabras verdaderamente insecables. El comportamiento predeterminado en versiones anteriores era permitir siempre romper palabras con guiones.

max_lines

(default: None) Si es None, entonces la salida contendrá como máximo max_lines, con un placeholder que aparecerá al final de la salida.

Nuevo en la versión 3.4.

placeholder

(default: ' [...]') Cadena que aparecerá al final del texto de salida si ha sido truncado.

Nuevo en la versión 3.4.

TextWrapper también proporciona algunos métodos públicos, análogos a las funciones de conveniencia a nivel de módulo:

wrap(text)

Envuelve el párrafo individual en text (una cadena) para que cada línea tenga como máximo width caracteres de largo. Todas las opciones de envoltura se toman de los atributos de la instancia TextWrapper. Retorna una lista de líneas de salida, sin las nuevas líneas finales. Si la salida envuelta no tiene contenido, la lista retornada estará vacía.

fill(text)

Envuelve el único párrafo en text, y retorna una única cadena que contiene el párrafo envuelto.

unicodedata — Base de datos Unicode

Este módulo proporciona acceso a la base de datos de caracteres Unicode (UCD), que define las propiedades de todos los caracteres Unicode. Los datos contenidos en esta base de datos se compilan a partir de la UCD versión 13.0.0 [https://www.unicode.org/Public/13.0.0/ucd].

El módulo utiliza los mismos nombres y símbolos definidos por el Anexo #44 del estándar Unicode de la «Base de datos de caracteres Unicode» [https://www.unicode.org/reports/tr44/]. Define las siguientes funciones:

unicodedata.lookup(name)

Busca el carácter por su nombre. Si se encuentra un carácter con el nombre proporcionado, retornará el carácter correspondiente. Si no se encuentra, se lanza una excepción KeyError.

Distinto en la versión 3.3: Se ha agregado soporte para alias de nombre 1 y secuencias con nombre 2.

unicodedata.name(chr[, default])

Retorna el nombre asignado al carácter chr como una cadena de caracteres. Si no se define ningún nombre, se retorna default o, si no se proporciona, se lanza una excepción ValueError.

unicodedata.decimal(chr[, default])

Retorna el valor decimal asignado al carácter chr como un entero. Si no se define dicho valor, se retorna default o, si no se proporciona, se lanza una excepción ValueError.

unicodedata.digit(chr[, default])

Retorna el valor del dígito asignado al carácter chr como un entero. Si no se define dicho valor, se retorna default o, si no se proporciona, se genera una excepción ValueError.

unicodedata.numeric(chr[, default])

Retorna el valor numérico asignado al carácter chr como un flotante. Si no se define dicho valor, se retorna default o, si no se proporciona, se lanza una excepción ValueError.

unicodedata.category(chr)

Retorna la categoría general asignada al carácter chr como una cadena de caracteres.

unicodedata.bidirectional(chr)

Retorna la clase bidireccional asignada al carácter chr como una cadena de caracteres. Si no se define tal valor, se retorna una cadena de caracteres vacía.

unicodedata.combining(chr)

Retorna la clase de combinación canónica asignada al carácter chr como un entero. Retorna 0 si no se define ninguna clase de combinación.

unicodedata.east_asian_width(chr)

Retorna el ancho asignado al carácter chr para el este asiático como una cadena de caracteres.

unicodedata.mirrored(chr)

Retorna la propiedad reflejada asignada al carácter chr como un entero. Retorna 1 si el carácter se ha identificado como un carácter «reflejado» en texto bidireccional y 0 en caso contrario.

unicodedata.decomposition(chr)

Retorna el mapeo de descomposición de caracteres asignado al carácter chr como una cadena de caracteres. Se retorna una cadena de caracteres vacía en caso de que no se defina tal mapeo.

unicodedata.normalize(form, unistr)

Retorna la forma normalizada form para la cadena Unicode unistr. Los valores válidos para form son “NFC”, “NFKC”, “NFD” y “NFKD”.

El estándar Unicode define varias formas de normalización de una cadena Unicode, basándose en la definición de equivalencia canónica y equivalencia de compatibilidad. En Unicode, varios caracteres se pueden expresar de diversas formas. Por ejemplo, el carácter U+00C7 (LETRA C LATINA MAYÚSCULA CON CEDILLA) también se puede expresar con la secuencia U+0043 (LETRA C LATINA MAYÚSCULA) U+0327 (CEDILLA COMBINABLE).

Para cada carácter, hay dos formas normalizadas: la forma normal C y la forma normal D. La forma normal D (NFD) también se conoce como descomposición canónica y traduce cada carácter a su forma descompuesta. La forma normal C (NFC) primero aplica una descomposición canónica y luego vuelve a componer los caracteres combinados previamente.

Además de las dos anteriores, hay dos formas normalizadas adicionales basadas en la equivalencia de compatibilidad. En Unicode, se admiten ciertos caracteres que normalmente se unificarán con otros caracteres. Por ejemplo, U+2160 (NUMERAL ROMANO UNO) es realmente lo mismo que U+0049 (LETRA LATINA MAYÚSCULA I). Sin embargo, esta característica está soportada por Unicode para ser compatible con los conjuntos de caracteres existentes (por ejemplo, gb2312).

La forma normalizada KD (NFKD) aplicará la descomposición de compatibilidad, es decir, reemplazará todos los caracteres de compatibilidad con sus equivalentes. La forma normalizada KC (NFKC) primero aplica la descomposición de compatibilidad, seguida de la composición canónica.

Incluso si dos cadenas Unicode están normalizadas y parecen iguales para un lector humano, si una tiene caracteres combinados y la otra no, es posible que no se comparen como iguales.

unicodedata.is_normalized(form, unistr)

Retorna si la cadena Unicode unistr está en la forma normalizada form. Los valores válidos para form son “NFC”, “NFKC”, “NFD” y “NFKD”.

Nuevo en la versión 3.8.

Además, el módulo expone las siguientes constantes:

unicodedata.unidata_version

La versión de la base de datos Unicode usada en este módulo.

unicodedata.ucd_3_2_0

Este es un objeto que tiene los mismos métodos que el módulo completo, pero usa la versión 3.2 de la base de datos Unicode en su lugar. Es útil para aplicaciones que requieren esta versión específica de la base de datos Unicode (como IDNA).

Ejemplos:

>>> import unicodedata
>>> unicodedata.lookup('LEFT CURLY BRACKET')
'{'
>>> unicodedata.name('/')
'SOLIDUS'
>>> unicodedata.decimal('9')
9
>>> unicodedata.decimal('a')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: not a decimal
>>> unicodedata.category('A')  # 'L'etter, 'u'ppercase
'Lu'
>>> unicodedata.bidirectional('\u0660') # 'A'rabic, 'N'umber
'AN'

Notas al pie

1

https://www.unicode.org/Public/13.0.0/ucd/NameAliases.txt

2

https://www.unicode.org/Public/13.0.0/ucd/NamedSequences.txt

stringprep — Preparación de cadenas de Internet

Código fuente: Lib/stringprep.py [https://github.com/python/cpython/tree/3.9/Lib/stringprep.py]

Cuando se quiere identificar cosas (como nombres de host) en internet, generalmente es necesario comparar tales identificaciones para «igualdad». La manera en la que esta comparación se ejecuta dependerá del dominio de la aplicación, ej. si tiene o no tiene que distinguir entre mayúsculas y minúsculas. Además, en algunos casos será necesario restringir las posibles identificaciones, de tal manera que solo se permitan identificadores de caracteres que se puedan «imprimir».

RFC 3454 [https://tools.ietf.org/html/rfc3454.html] define el proceso para la «preparación» de cadenas Unicode para protocolos de internet. Antes de pasar cadenas a un cable, se procesan con el proceso de preparación, después del cual tienen una forma normalizada. El RFC define un conjunto de tablas, que pueden ser combinadas en perfiles. Cada perfil debe definir qué tablas usa, y que partes opcionales del proceso stringprep son parte del perfil. Un ejemplo de perfil de stringprep es nameprep, que se usa para nombres de dominios internacionalizados.

El modulo stringprep solo expone las tablas de RFC 3454 [https://tools.ietf.org/html/rfc3454.html]. Como estas tablas serían muy grandes para representarlas como diccionarios o listas, el módulo usa la base de datos de los caracteres de Unicode de manera interna. El código fuente del módulo en sí ha sido generado usando la herramienta mkstringprep.py

Como resultado, estas tablas son presentadas como funciones, no como estructuras de datos. Hay dos tipos de tablas en el RFC: conjuntos y mapeos. Para un conjunto, stringprep proporciona una «función característica», es decir, la función retorna True si el parámetro es parte del conjunto. Para los mapas, proporciona una función de mapeado: dada una clave, retorna el valor asociado. Abajo se encuentra una lista con todas las funciones disponibles para este módulo.

stringprep.in_table_a1(code)

Determina si code está en la tablaA.1 (Puntos de Código sin asignar en Unicode 3.2).

stringprep.in_table_b1(code)

Determina si code está en la tablaB.1 (Generalmente mapeado a nada).

stringprep.map_table_b2(code)

Retorna el valor mapeado para code de acuerdo a la tablaB.2 (Mapeo para case-folding usado con NFKC).

stringprep.map_table_b3(code)

Retorna el valor mapeado para code de acuerdo a tablaB.3 (Mapeo para case-folding usado sin normalización).

stringprep.in_table_c11(code)

Determina si code está en la tablaC.1.1 (Caracteres de espacio ASCII).

stringprep.in_table_c12(code)

Determina si code está en la tablaC.1.2 (Caracteres de espacio no-ASCII).

stringprep.in_table_c11_c12(code)

Determina si code está en la tablaC.1 (Caracteres de espacio, unión de C.1.1 y C.1.2).

stringprep.in_table_c21(code)

Determina si code está en la tablaC.2.1 (Caracteres de control ASCII).

stringprep.in_table_c22(code)

Determina si code está en la tablaC.2.2 (Caracteres de control no ASCII).

stringprep.in_table_c21_c22(code)

Determina si code está en la tablaC.2 (Caracteres de control, unión de C.2.1 y C.2.2).

stringprep.in_table_c3(code)

Determina si code está en la tablaC.3 (Uso privado).

stringprep.in_table_c4(code)

Determina si code está en la tablaC.4 (Puntos de código sin caracteres)

stringprep.in_table_c5(code)

Determina si code está en la tablaC.5 (Códigos surrogados).

stringprep.in_table_c6(code)

Determina si code está en la tablaC.6 (Inadecuado para texto plano).

stringprep.in_table_c7(code)

Determina si code está en la tablaC.7 (Inadecuado para la representación canónica).

stringprep.in_table_c8(code)

Determina si code está en la tablaC.8 (Cambia las propiedades de apariencia o están obsoletas).

stringprep.in_table_c9(code)

Determina si code está en la tablaC.9 (Caracteres de etiquetado).

stringprep.in_table_d1(code)

Determina si code está en la tablaD.1 (Caracteres con propiedad bidireccional «R» o «AL»).

stringprep.in_table_d2(code)

Determina si code está en la tablaD.2 (Caracteres con propiedad bidireccional «L»).

readline — Interfaz readline de GNU

El módulo readline define una serie de funciones para facilitar la finalización y lectura/escritura de archivos de historial desde el intérprete de Python. Este módulo se puede usar directamente o mediante el módulo rlcompleter, que administra la finalización de identificadores de Python en la solicitud interactiva. Los ajustes realizados con este módulo afectan el comportamiento tanto del aviso interactivo del intérprete como de los avisos ofrecidos por la función incorporada input().

Las combinaciones de teclas de Readline se pueden configurar mediante un archivo de inicialización, generalmente .inputrc en su directorio de inicio. Consulte Readline Init File [https://tiswww.cwru.edu/php/chet/readline/rluserman.html#SEC9] en el manual de GNU Readline para obtener información sobre el formato y las construcciones permitidas de ese archivo, y las capacidades de la biblioteca Readline en general.

Nota

La API de la biblioteca utilizada por Readline puede implementarse mediante la biblioteca libedit en lugar de readline de GNU. En macOS, el módulo readline detecta qué biblioteca se está utilizando en tiempo de ejecución.

El archivo de configuración para libedit es diferente del readline de GNU. Si carga cadenas de caracteres de configuración mediante programación, puede verificar el texto «libedit» en readline.__ doc__ para diferenciar entre readline de GNU y libedit.

Si usa emulación readline editline/libedit en macOS, el archivo de inicialización ubicado en su directorio de inicio se llama .editrc. Por ejemplo, el siguiente contenido en ~/.editrc activa atajos del teclado de vi y completado con TAB:

python:bind -v
python:bind ^I rl_complete

Archivo de inicio

Las siguientes funciones se relacionan con el archivo de inicio y la configuración del usuario:

readline.parse_and_bind(string)

Ejecuta la línea de inicio proporcionada en el argumento string. Esto llama a la función rl_parse_and_bind() de la biblioteca subyacente.

readline.read_init_file([filename])

Ejecuta un archivo de inicialización readline. El nombre de archivo predeterminado es el último nombre de archivo utilizado. Esto llama a la función rl_read_init_file() de la biblioteca subyacente.

Búfer de línea

Las siguientes funciones operan en el búfer de línea:

readline.get_line_buffer()

Retorna el contenido actual del búfer de línea (rl_line_buffer en la biblioteca subyacente).

readline.insert_text(string)

Inserta texto en el búfer de línea en la posición del cursor. Esto llama a la función rl_insert_text() de la biblioteca subyacente, pero ignora el valor de retorno.

readline.redisplay()

Cambia lo que se muestra en la pantalla para reflejar el contenido actual del búfer de línea. Esto llama a la función rl_redisplay() de la biblioteca subyacente.

Archivo de historial

Las siguientes funciones operan en un archivo de historial:

readline.read_history_file([filename])

Carga un archivo de historial readline y lo adjunta a la lista de historial. El nombre de archivo predeterminado es ~/.history. Esto llama a la función read_history() de la biblioteca subyacente.

readline.write_history_file([filename])

Guarda la lista de historial en un archivo de historial readline, sobrescribiendo cualquier archivo existente. El nombre de archivo predeterminado es ~/.history. Esto llama a la función write_history() de la biblioteca subyacente.

readline.append_history_file(nelements[, filename])

Agrega los últimos nelements del historial a un archivo. El nombre de archivo predeterminado es ~/.history. El archivo ya debe existir. Esto llama a la función append_history() de la biblioteca subyacente. Esta función solo existe si Python se compiló para una versión de la biblioteca que lo admita.

Nuevo en la versión 3.5.

readline.get_history_length()

readline.set_history_length(length)

Establece o retorna el número deseado de líneas para guardar en el archivo de historial. La función write_history_file() usa este valor para truncar el archivo de historial, llamando a la función history_truncate_file() en la biblioteca subyacente. Los valores negativos implican un tamaño de archivo de historial ilimitado.

Lista del historial

Las siguientes funciones operan en una lista de historial global:

readline.clear_history()

Borra el historial actual. Esto llama a la función clear_history() en la biblioteca subyacente. La función de Python solo existe si Python se compiló para una versión de la biblioteca que lo admita.

readline.get_current_history_length()

Retorna el número de elementos actuales en el historial. (Esto es diferente de la función get_history_length(), que retorna el número máximo de líneas que se escribirán en un archivo de historial).

readline.get_history_item(index)

Retorna el contenido actual de historial en index. El índice comienza en 1. Esto llama a la función history_get() en la biblioteca subyacente.

readline.remove_history_item(pos)

Elimina el objeto del historial definido por su posición del historial. La posición comienza en cero. Esto llama a la función remove_history() en la biblioteca subyacente.

readline.replace_history_item(pos, line)

Reemplaza el elemento del historial especificado por su posición con line. La posición comienza en cero. Esto llama a la función replace_history_entry() en la biblioteca subyacente.

readline.add_history(line)

Agrega line al búfer de historial, como si fuera la última línea escrita. Esto llama a la función add_history() en la biblioteca subyacente.

readline.set_auto_history(enabled)

Habilita o deshabilita las llamadas automáticas a la función add_history() al leer la entrada a través de readline. El argumento enabled debe ser un valor booleano que cuando es verdadero, habilita el historial automático, y que cuando es falso, desactiva el historial automático.

Nuevo en la versión 3.6.

CPython implementation detail: Auto history is enabled by default, and changes to this do not persist across multiple sessions.

Ganchos (hooks) de inicialización

readline.set_startup_hook([function])

Establece o elimina la función invocada por la función de retorno rl_startup_hook de la biblioteca subyacente. Si se especifica function, se utilizará como la nueva función de enlace; Si se omite o es None, se elimina cualquier función ya instalada. La función de devolución de llamada se llama sin argumentos justo antes de que readline muestre el primer símbolo del sistema.

readline.set_pre_input_hook([function])

Establece o elimina la función invocada por la función de retorno rl_pre_input_hook de la biblioteca subyacente. Si se especifica function, se utilizará como la nueva función de devolución de llamada; Si se omite o es None, se elimina cualquier función ya instalada. La función de devolución de llamada se llama sin argumentos después de que se haya visualizado el primer símbolo del sistema y justo antes de que readline comience a leer los caracteres ingresados. Esta función solo existe si Python se ha compilado para una versión de la biblioteca que lo admite.

Terminación

Las siguientes funciones se relacionan con la implementación de una función de finalización de palabra personalizada. Esto típicamente es operado por la tecla Tab y puede sugerir y completar automáticamente una palabra que se está escribiendo. Por defecto, Readline está configurado para ser utilizado por rlcompleter para completar los identificadores de Python para el intérprete interactivo. Si el módulo readline se va a utilizar con una terminación específica, se debe definir un conjunto de palabras delimitadoras.

readline.set_completer([function])

Establece o elimina la función de finalización. Si se especifica function, se usará como la nueva función de finalización; Si se omite o es None, se elimina cualquier función de finalización ya instalada. La función completa se llama como function(text, state), para state en 0, 1, 2, …, hasta que retorna un valor que no es una cadena de caracteres. Debería retornar las siguientes terminaciones posibles comenzando con text.

La función de finalización instalada es invocada por la función de retorno entry_func que se pasa a rl_completion_matches() en la biblioteca subyacente. La cadena de texto va desde el primer parámetro a la función de retorno rl_attempted_completion_function de la biblioteca subyacente.

readline.get_completer()

Obtiene la función de finalización o None si no se ha definido ninguna función de finalización.

readline.get_completion_type()

Obtiene el tipo de finalización que se está intentando. Esto retorna la variable rl_completion_type en la biblioteca subyacente como un entero.

readline.get_begidx()

readline.get_endidx()

Obtiene el índice inicial o final de un contexto de finalización. Estos índices son los argumentos start y end pasados ​​a la función de retorno rl_attempted_completion_function de la biblioteca subyacente.

readline.set_completer_delims(string)

readline.get_completer_delims()

Define o recupera palabras delimitadoras para completar. Estos determinan el comienzo de la palabra que se considerará para su finalización (el contexto de finalización). Estas funciones acceden a la variable rl_completer_word_break_characters desde la biblioteca subyacente.

readline.set_completion_display_matches_hook([function])

Establece o elimina la función de visualización de finalización. Si se especifica function, se utilizará como una nueva función de visualización de finalización; si se omite o es None, se elimina cualquier función de finalización ya instalada. Esto establece o elimina la función de retorno rl_completion_display_matches_hook de la biblioteca subyacente. La función de visualización de finalización se llama tal como la function(substitution, [matches], longest_match_length) solo una vez cuando se muestran las coincidencias.

Ejemplo

El siguiente ejemplo muestra cómo usar las funciones de lectura y escritura del historial del módulo readline para cargar o guardar automáticamente un archivo de historial llamado .python_history desde el directorio de inicio del usuario. El siguiente código normalmente debe ejecutarse automáticamente durante una sesión interactiva desde el archivo de usuario PYTHONSTARTUP.

import atexit
import os
import readline

histfile = os.path.join(os.path.expanduser("~"), ".python_history")
try:
    readline.read_history_file(histfile)
    # default history len is -1 (infinite), which may grow unruly
    readline.set_history_length(1000)
except FileNotFoundError:
    pass

atexit.register(readline.write_history_file, histfile)

Este código se ejecuta automáticamente cuando Python se ejecuta en modo interactivo (ver Configuración de Readline).

El siguiente ejemplo logra el mismo objetivo pero administra sesiones interactivas concurrentes, agregando solo el nuevo historial.

import atexit
import os
import readline
histfile = os.path.join(os.path.expanduser("~"), ".python_history")

try:
    readline.read_history_file(histfile)
    h_len = readline.get_current_history_length()
except FileNotFoundError:
    open(histfile, 'wb').close()
    h_len = 0

def save(prev_h_len, histfile):
    new_h_len = readline.get_current_history_length()
    readline.set_history_length(1000)
    readline.append_history_file(new_h_len - prev_h_len, histfile)
atexit.register(save, h_len, histfile)

El siguiente ejemplo amplía la clase code.InteractiveConsole para administrar el guardado/restauración del historial.

import atexit
import code
import os
import readline

class HistoryConsole(code.InteractiveConsole):
    def __init__(self, locals=None, filename="<console>",
                 histfile=os.path.expanduser("~/.console-history")):
        code.InteractiveConsole.__init__(self, locals, filename)
        self.init_history(histfile)

    def init_history(self, histfile):
        readline.parse_and_bind("tab: complete")
        if hasattr(readline, "read_history_file"):
            try:
                readline.read_history_file(histfile)
            except FileNotFoundError:
                pass
            atexit.register(self.save_history, histfile)

    def save_history(self, histfile):
        readline.set_history_length(1000)
        readline.write_history_file(histfile)

rlcompleter — Función de completado para GNU readline

Código fuente: Lib/rlcompleter.py [https://github.com/python/cpython/tree/3.9/Lib/rlcompleter.py]

El módulo rlcompleter define una función de completado adecuada para el módulo readline completando los identificadores y las palabras clave de Python válidas.

Cuando este módulo es importado en una plataforma Unix con el módulo readline disponible, una instancia de la clase Completer es automáticamente creada y su método complete() es fijado como el método de completado de readline.

Ejemplo:

>>> import rlcompleter
>>> import readline
>>> readline.parse_and_bind("tab: complete")
>>> readline. <TAB PRESSED>
readline.__doc__          readline.get_line_buffer(  readline.read_init_file(
readline.__file__         readline.insert_text(      readline.set_completer(
readline.__name__         readline.parse_and_bind(
>>> readline.

El módulo rlcompleter está diseñado para usarse con el modo interactivo de Python. A menos que Python sea ejecutado con la opción -S, el módulo es automáticamente importado y configurado (ver Configuración de Readline).

En plataformas sin readline, la clase Completer definida por este módulo puede ser usada igualmente para fines personalizados.

Objetos de Completado

Los objetos de completado tienen el siguiente método:

Completer.complete(text, state)

Retorna el completado nº state para text.

Si es invocado para text que no incluye un caracter de punto ('.'), este completará con nombres actualmente definidos en __main__, builtins y las palabras clave (tal y como están definidas en el módulo keyword).

Si es invocado para un nombre con punto, este tratará de evaluar cualquier cosa sin efectos secundarios obvios (las funciones no serán evaluadas, pero puede generar invocaciones a __getattr__()) hasta la última parte, y encontrar coincidencias para el resto mediante la función dir(), Cualquier excepción ocurrida durante la evaluación de la expresión es cazada, silenciada y se retorna None.

Servicios de datos binarios

Los módulos descritos en este capítulo proporcionan algunas operaciones básicas de servicios para la manipulación de datos binarios. Otras operaciones sobre datos binarios específicamente relacionadas con formatos de archivo y protocolos de red están descritas en las secciones relevantes.

Algunas bibliotecas descritas bajo Servicios de procesamiento de texto también funcionan o bien sobre formatos binarios compatibles con ASCII (por ejemplo re), o bien sobre todos los datos binarios (por ejemplo difflib).

Adicionalmente, véase la documentación para los tipos de datos binarios incorporados en Python en Tipos de secuencias binarias — bytes, bytearray y memoryview.

struct — Interpreta bytes como paquetes de datos binarios

Funciones y Excepciones

Cadenas de Formato

Orden de Bytes, Tamaño y Alineación

Formato de caracteres

Ejemplos

Clases

codecs — Registro de códec y clases base

Clases Base de Códec

Manejadores de errores

Codificación y decodificación sin estado

Codificación y decodificación incrementales

Objetos IncrementalEncoder

Objetos IncrementalDecoder

Codificación y decodificación de flujos

Objetos StreamWriter

Objetos StreamReader

Objetos StreamReaderWriter

Objetos StreamRecoder

Codificaciones y Unicode

Codificaciones estándar

Codificaciones específicas de Python

Codificaciones de texto

Transformaciones Binarias

Transformaciones de texto

encodings.idna — Nombres de dominio internacionalizados en aplicaciones

encodings.mbcs — Página de códigos ANSI de Windows

encodings.utf_8_sig — Códec UTF-8 con firma BOM

struct — Interpreta bytes como paquetes de datos binarios

Código fuente: Lib/struct.py [https://github.com/python/cpython/tree/3.9/Lib/struct.py]

Este módulo realiza conversiones entre valores de Python y estructuras C representadas como objetos bytes de Python. Se puede utilizar para el tratamiento de datos binarios almacenados en archivos o desde conexiones de red, entre otras fuentes. Utiliza Cadenas de Formato como descripciones compactas del diseño de las estructuras C y la conversión prevista a/desde valores de Python.

Nota

Por defecto, el resultado de empaquetar una estructura C determinada incluye bytes de relleno para mantener la alineación adecuada para los tipos correspondientes en C; del mismo modo, la alineación se tiene en cuenta al desempaquetar. Este comportamiento se elige para que los bytes de una estructura empaquetada se correspondan exactamente con el diseño en memoria de la estructura C correspondiente. Para tratar formatos de datos que sean independientes de la plataforma u omitir bytes de relleno implícitos, utiliza el tamaño y la alineación estándar en lugar del nativo: ver Orden de Bytes, Tamaño y Alineación para obtener más información.

Varias funciones struct (y métodos de Struct) toman un argumento buffer. Esto hace referencia a los objetos que implementan Protocolo Búfer y proporcionan un búfer de lectura o de lectura/escritura. Los tipos más comunes utilizados para ese propósito son bytes y bytearray, pero muchos otros tipos que se pueden ver como una lista de bytes implementan el protocolo de búfer, para que se puedan leer/rellenar sin necesidad de copiar a partir de un objeto bytes.

Funciones y Excepciones

El módulo define la siguiente excepción y funciones:

exception struct.error

Excepción lanzada en varias ocasiones; el argumento es una string que describe lo que está mal.

struct.pack(format, v1, v2, ...)

Retorna un objeto bytes que contiene los valores v1, v2, … empaquetado de acuerdo con la cadena de formato format. Los argumentos deben coincidir exactamente con los valores requeridos por el formato.

struct.pack_into(format, buffer, offset, v1, v2, ...)

Empaqueta los valores v1, v2, … de acuerdo con la cadena de formato format y escribe los bytes empaquetados en el búfer de escritura buffer comenzando en la posición offset. Nota: offset es un argumento obligatorio.

struct.unpack(format, buffer)

Desempaqueta del búfer buffer (normalmente empaquetado por pack(format, ...)) según la cadena de formato format. El resultado es una tupla incluso si contiene un solo elemento. El tamaño del búfer en bytes debe coincidir con el tamaño requerido por el formato, como se refleja en calcsize().

struct.unpack_from(format, /, buffer, offset=0)

Desempaqueta del buffer comenzando en la posición offset, según la cadena de formato format. El resultado es una tupla incluso si contiene un solo elemento. El tamaño del búfer en bytes, comenzando en la posición offset, debe tener al menos el tamaño requerido por el formato, como se refleja en calcsize().

struct.iter_unpack(format, buffer)

Desempaqueta de manera iterativa desde el búfer buffer según la cadena de formato format. Esta función retorna un iterador que leerá fragmentos de igual tamaño desde el búfer hasta que se haya consumido todo su contenido. El tamaño del búfer en bytes debe ser un múltiplo del tamaño requerido por el formato, como se refleja en calcsize().

Cada iteración produce una tupla según lo especificado por la cadena de formato.

Nuevo en la versión 3.4.

struct.calcsize(format)

Retorna el tamaño de la estructura (y, por lo tanto, del objeto bytes generado por pack(format, ...)) correspondiente a la cadena de formato format.

Cadenas de Formato

Las cadenas de formato son el mecanismo utilizado para especificar el diseño esperado al empaquetar y desempaquetar datos. Se crean a partir de Formato de caracteres, que especifican el tipo de datos que se empaquetan/desempaquetan. Además, hay caracteres especiales para controlar Orden de Bytes, Tamaño y Alineación.

Orden de Bytes, Tamaño y Alineación

Por defecto, los tipos C se representan en el formato nativo y el orden de bytes de la máquina, y se alinean correctamente omitiendo bytes de relleno si es necesario (según las reglas utilizadas por el compilador de C).

Como alternativa, el primer carácter de la cadena de formato se puede utilizar para indicar el orden de bytes, el tamaño y la alineación de los datos empaquetados, según la tabla siguiente:

Caracter

Orden de Bytes

Tamaño

Alineamiento

@

nativo

nativo

nativo

=

nativo

standard

none

<

little-endian

standard

none

>

big-endian

standard

none

!

red (= big-endian)

standard

none

Si el primer carácter no es uno de estos, se asume '@'.

El orden de bytes nativo es big-endian o little-endian, dependiendo del sistema host. Por ejemplo, Intel x86 y AMD64 (x86-64) son little-endian; Motorola 68000 y PowerPC G5 son big-endian; ARM e Intel Itanium tienen la propiedad de trabajar con ambos formatos (middle-endian). Utiliza sys.byteorder para comprobar la endianness («extremidad») de su sistema.

El tamaño y la alineación nativos se determinan mediante la expresión sizeof del compilador de C. Esto siempre se combina con el orden de bytes nativo.

El tamaño estándar depende únicamente del carácter de formato; ver la tabla en la sección Formato de caracteres.

Nótese la diferencia entre '@' y '=' : ambos utilizan el orden de bytes nativo, pero el tamaño y la alineación de este último está estandarizado.

The form '!' represents the network byte order which is always big-endian as defined in IETF RFC 1700 [https://tools.ietf.org/html/rfc1700].

No hay manera de indicar el orden de bytes no nativo (forzar el intercambio de bytes); utiliza la elección adecuada de '<' o '>'.

Notas:

El relleno solo se agrega automáticamente entre los miembros sucesivos de la estructura. No se agrega ningún relleno al principio o al final de la estructura codificada.

No se añade ningún relleno cuando se utiliza el tamaño y la alineación no nativos, por ejemplo, con “<”, “>”, “=” y “!”.

Para alinear el final de una estructura con el requisito de alineación de un tipo determinado, termina el formato con el código de ese tipo con un dos ceros. Véase Ejemplos.

Formato de caracteres

Los caracteres de formato tienen el siguiente significado; la conversión entre los valores C y Python debe ser obvia dados sus tipos. La columna “Tamaño estándar” hace referencia al tamaño del valor empaquetado en bytes cuando se utiliza el tamaño estándar; es decir, cuando la cadena de formato comienza con uno de '<', '>', '!' o '='. Cuando se utiliza el tamaño nativo, el tamaño del valor empaquetado depende de la plataforma.

Formato

Tipo C

Tipo Python

Tamaño estándar

Notas

x

byte de relleno

sin valor

c

char

bytes de longitud 1

1

b

signed char

integer

1

(1), (2)

B

unsigned char

integer

1

(2)

(2)

_Bool

bool

1

(1)

h

short

integer

2

(2)

H

unsigned short

integer

2

(2)

i

int

integer

4

(2)

I

unsigned int

integer

4

(2)

l

long

integer

4

(2)

L

unsigned long

integer

4

(2)

q

long long

integer

8

(2)

Q

unsigned long long

integer

8

(2)

n

ssize_t

integer

(3)

N

size_t

integer

(3)

e

(6)

float

2

(4)

f

float

float

4

(4)

d

double

float

8

(4)

s

char[]

bytes

p

char[]

bytes

P

void *

integer

(5)

Distinto en la versión 3.3: Soporte añadido para los formatos 'n' y 'N'.

Distinto en la versión 3.6: Soporte añadido para el formato 'e'.

Notas:

El código de conversión '?' corresponde al tipo _Bool definido por C99. Si este tipo no está disponible, se simula mediante un char. En el modo estándar, siempre se representa mediante un byte.

Al intentar empaquetar un no entero mediante cualquiera de los códigos de conversión de enteros, si el no entero tiene un método __index__(), se llama a ese método para convertir el argumento en un entero antes de empaquetar.

Distinto en la versión 3.2: Added use of the __index__() method for non-integers.

Los códigos de conversión 'n' y 'N' solo están disponibles para el tamaño nativo (seleccionado como predeterminado o con el carácter de orden de bytes '@'). Para el tamaño estándar, puedes usar cualquiera de los otros formatos enteros que se ajusten a tu aplicación.

Para los códigos de conversión 'f', 'd' y 'e', la representación empaquetada utiliza el formato IEEE 754 binary32, binary64 o binary16 (para 'f', 'd' o 'e' respectivamente), independientemente del formato de punto flotante utilizado por la plataforma.

El carácter de formato 'P' solo está disponible para el orden de bytes nativo (seleccionado como predeterminado o con el carácter de orden de bytes '@'). El carácter de orden de bytes '=' elige utilizar el orden little- o big-endian basado en el sistema host. El módulo struct no interpreta esto como un orden nativo, por lo que el formato 'P' no está disponible.

El tipo IEEE 754 binary16 «half precision» se introdujo en la revisión de 2008 del IEEE 754 estándar [https://en.wikipedia.org/wiki/IEEE_floating_point#IEEE_754-2008]. Tiene un bit de signo, un exponente de 5 bits y una precisión de 11 bits (con 10 bits almacenados explícitamente) y puede representar números entre aproximadamente 6.1e-05 y 6.5e+04 con total precisión. Este tipo no es ampliamente compatible con los compiladores de C: en un equipo típico, un unsigned short se puede usar para el almacenamiento, pero no para las operaciones matemáticas. Consulte la página de Wikipedia en el formato de punto flotante de media precisión [https://en.wikipedia.org/wiki/Half-precision_floating-point_format] para obtener más información.

Un carácter de formato puede ir precedido de un número de recuento que repite tantas veces el carácter. Por ejemplo, la cadena de formato '4h' significa exactamente lo mismo que 'hhhh' .

Se omiten los caracteres de espacio entre formatos; sin embargo, un recuento y su formato no deben contener espacios en blanco.

Para el carácter de formato 's', el recuento se interpreta como la longitud de los bytes, no un recuento de repetición como para los otros caracteres de formato; por ejemplo, '10s' significa una sola cadena de 10 bytes, mientras que '10c' significa 10 caracteres. Si no se da un recuento, el valor predeterminado es 1. Para el empaquetado, la cadena es truncada o rellenada con bytes nulos según corresponda para que se ajuste. Para desempaquetar, el objeto bytes resultante siempre tiene exactamente el número especificado de bytes. Como caso especial, '0s' significa una sola cadena vacía (mientras que '0c' significa 0 caracteres).

Al empaquetar un valor x utilizando uno de los formatos enteros ('b', 'B', 'h', 'H', 'i', 'I', 'l', 'L', 'q', 'Q'), si x está fuera de un rango válido para ese formato, entonces se lanza la excepción struct.error.

Distinto en la versión 3.1: Previously, some of the integer formats wrapped out-of-range values and raised DeprecationWarning instead of struct.error.

El carácter de formato 'p' codifica una «cadena de Pascal», lo que significa una cadena de longitud variable corta almacenada en un número fijo de bytes, dado por el recuento. El primer byte almacenado es el valor mínimo entre la longitud de la cadena o 255. A continuación se encuentran los bytes de la cadena. Si la cadena pasada a pack() es demasiado larga (más larga que la cuenta menos 1), solo se almacenan los bytes iniciales count-1 de la cadena. Si la cadena es más corta que count-1, se rellena con bytes nulos para que se utilicen exactamente los bytes de recuento en total. Tenga en cuenta que para unpack(), el carácter de formato 'p' consume bytes count, pero que la cadena retornada nunca puede contener más de 255 bytes.

Para el carácter de formato '?', el valor retornado es True o False. Al empaquetar, se utiliza el valor verdadero del objeto del argumento. Se empaquetará 0 o 1 en la representación bool nativa o estándar, y cualquier valor distinto de cero será True al desempaquetar.

Ejemplos

Nota

Todos los ejemplos asumen un orden de bytes tamaño y alineación nativos, con una máquina big-endian.

Un ejemplo básico de empaquetado/desempaquetado de tres enteros:

>>> from struct import *
>>> pack('hhl', 1, 2, 3)
b'\x00\x01\x00\x02\x00\x00\x00\x03'
>>> unpack('hhl', b'\x00\x01\x00\x02\x00\x00\x00\x03')
(1, 2, 3)
>>> calcsize('hhl')
8

Los campos desempaquetados se pueden nombrar asignándolos a variables o ajustando el resultado en una tupla con nombre:

>>> record = b'raymond   \x32\x12\x08\x01\x08'
>>> name, serialnum, school, gradelevel = unpack('<10sHHb', record)

>>> from collections import namedtuple
>>> Student = namedtuple('Student', 'name serialnum school gradelevel')
>>> Student._make(unpack('<10sHHb', record))
Student(name=b'raymond   ', serialnum=4658, school=264, gradelevel=8)

El orden de los caracteres de formato puede tener un impacto en el tamaño ya que el relleno necesario para satisfacer los requisitos de alineación es diferente:

>>> pack('ci', b'*', 0x12131415)
b'*\x00\x00\x00\x12\x13\x14\x15'
>>> pack('ic', 0x12131415, b'*')
b'\x12\x13\x14\x15*'
>>> calcsize('ci')
8
>>> calcsize('ic')
5

El siguiente formato 'llh0l' especifica dos bytes de relleno al final, suponiendo que los tipos longs están alineados en los límites de 4 bytes:

>>> pack('llh0l', 1, 2, 3)
b'\x00\x00\x00\x01\x00\x00\x00\x02\x00\x03\x00\x00'

Esto solo funciona cuando el tamaño y la alineación nativos tienen efecto; el tamaño estándar y la alineación no imponen ninguna alineación.

Ver también

Módulo array

Almacenamiento binario empaquetado de datos homogéneos.

Módulo xdrlib

Empaquetar y desempaquetar datos XDR.

Clases

El módulo struct también define el siguiente tipo:

class struct.Struct(format)

Retorna un nuevo objeto Struct que escribe y lee datos binarios según la cadena de formato format. Crear un objeto Struct una vez y llamar a sus métodos es más eficaz que llamar a las funciones struct con el mismo formato, ya que la cadena de formato solo se compila una vez en ese caso.

Nota

Las versiones compiladas de las cadenas de formato más recientes pasadas a Struct y las funciones de nivel de módulo se almacenan en caché, por lo que los programas que utilizan solo unas pocas cadenas de formato no necesitan preocuparse por volver a usar una sola instancia Struct.

Los objetos Struct compilados admiten los siguientes métodos y atributos:

pack(v1, v2, ...)

Idéntico a la función pack(), utilizando el formato compilado. (len(result) será igual a size.)

pack_into(buffer, offset, v1, v2, ...)

Idéntico a la función pack_into(), utilizando el formato compilado.

unpack(buffer)

Idéntico a la función unpack(), utilizando el formato compilado. El tamaño del búfer en bytes debe ser igual a size.

unpack_from(buffer, offset=0)

Idéntico a la función unpack_from(), utilizando el formato compilado. El tamaño del búfer en bytes, comenzando en la posición offset, debe ser al menos size.

iter_unpack(buffer)

Idéntico a la función iter_unpack(), utilizando el formato compilado. El tamaño del búfer en bytes debe ser un múltiplo de size.

Nuevo en la versión 3.4.

format

Cadena de formato utilizada para construir este objeto Struct.

Distinto en la versión 3.7: El tipo de cadena de formato es ahora str en lugar de bytes.

size

El tamaño calculado de la estructura (y, por lo tanto, del objeto bytes generado por el método pack()) correspondiente a format.

codecs — Registro de códec y clases base

Código fuente: Lib/codecs.py [https://github.com/python/cpython/tree/3.9/Lib/codecs.py]

This module defines base classes for standard Python codecs (encoders and decoders) and provides access to the internal Python codec registry, which manages the codec and error handling lookup process. Most standard codecs are text encodings, which encode text to bytes (and decode bytes to text), but there are also codecs provided that encode text to text, and bytes to bytes. Custom codecs may encode and decode between arbitrary types, but some module features are restricted to be used specifically with text encodings or with codecs that encode to bytes.

El módulo define las siguientes funciones para codificar y decodificar con cualquier códec:

codecs.encode(obj, encoding='utf-8', errors='strict')

Codifica obj utilizando el códec registrado para encoding.

Se pueden dar errors para establecer el esquema de manejo de errores deseado. El controlador de errores predeterminado es 'estricto', lo que significa que los errores de codificación provocan ValueError (o una subclase más específica del códec, como UnicodeEncodeError). Consulte Clases Base de Códec para obtener más información sobre el manejo de errores de códec.

codecs.decode(obj, encoding='utf-8', errors='strict')

Decodifica obj utilizando el códec registrado para encoding.

Se pueden dar errors para establecer el esquema de manejo de errores deseado. El controlador de errores predeterminado es 'estricto', lo que significa que los errores de decodificación generan ValueError (o una subclase más específica de códec, como UnicodeDecodeError). Consulte Clases Base de Códec para obtener más información sobre el manejo de errores de códec.

Los detalles completos de cada códec también se pueden consultar directamente:

codecs.lookup(encoding)

Busca la información de códec en el registro de códec de Python y retorna un objeto CodecInfo como se define a continuación.

Las codificaciones se buscan primero en la memoria caché del registro. Si no se encuentran, se explora la lista de funciones de búsqueda registradas. Si no se encuentran objetos CodecInfo, se lanza un LookupError. De lo contrario, el objeto CodecInfo se almacena en la memoria caché y se retorna a quien llama.

class codecs.CodecInfo(encode, decode, streamreader=None, streamwriter=None, incrementalencoder=None, incrementaldecoder=None, name=None)

Detalles de códec al buscar el registro de códec. Los argumentos del constructor se almacenan en atributos del mismo nombre:

name

El nombre de la codificación.

encode

decode

Las funciones de codificación y decodificación sin estado. Deben ser funciones o métodos que tengan la misma interfaz que los métodos encode() y decode() de instancias de Codec (ver Codec Interface). Se espera que las funciones o métodos funcionen en modo sin estado.

incrementalencoder

incrementaldecoder

Clases de codificación y decodificación incremental o funciones de fábrica. Deben proporcionar la interfaz definida por las clases base IncrementalEncoder y IncrementalDecoder, respectivamente. Los códecs incrementales pueden mantener el estado.

streamwriter

streamreader

Las clases stream, tanto writer como reader o funciones de fábrica. Estos tienen que proporcionar la interfaz definida por las clases base StreamWriter y StreamReader, respectivamente. Los códecs de flujo pueden mantener el estado.

Para simplificar el acceso a los diversos componentes de códec, el módulo proporciona estas funciones adicionales que utilizan lookup() para la búsqueda de códec:

codecs.getencoder(encoding)

Busca el códec para la codificación dada y retorna su función de codificador.

Lanza un LookupError en caso de que no se encuentre la codificación.

codecs.getdecoder(encoding)

Busca el códec para la codificación dada y retorna su función de decodificador.

Lanza un LookupError en caso de que no se encuentre la codificación.

codecs.getincrementalencoder(encoding)

Busca el códec para la codificación dada y retorna su clase de codificador incremental o función de fábrica.

Lanza un LookupError en caso de que no se encuentre la codificación o el códec no admita un codificador incremental.

codecs.getincrementaldecoder(encoding)

Busca el códec para la codificación dada y retorna su clase de decodificador incremental o función de fábrica.

Lanza un LookupError en caso de que no se encuentre la codificación o el códec no admita un decodificador incremental.

codecs.getreader(encoding)

Busca el códec para la codificación dada y retorna su clase StreamReader o función de fábrica.

Lanza un LookupError en caso de que no se encuentre la codificación.

codecs.getwriter(encoding)

Busca el códec para la codificación dada y retorna su clase StreamWriter o función de fábrica.

Lanza un LookupError en caso de que no se encuentre la codificación.

Los códecs personalizados se ponen a disposición registrando una función de búsqueda de códecs adecuada:

codecs.register(search_function)

Register a codec search function. Search functions are expected to take one argument, being the encoding name in all lower case letters with hyphens and spaces converted to underscores, and return a CodecInfo object. In case a search function cannot find a given encoding, it should return None.

Distinto en la versión 3.9: Hyphens and spaces are converted to underscore.

Nota

El registro de la función de búsqueda no es reversible actualmente, lo que puede causar problemas en algunos casos, como pruebas unitarias o recarga de módulos.

Mientras que la función incorporada open() y el módulo asociado io son el enfoque recomendado para trabajar con archivos de texto codificados, este módulo proporciona funciones y clases de utilidad adicionales que permiten el uso de una gama más amplia de códecs cuando se trabaja con archivos binarios:

codecs.open(filename, mode='r', encoding=None, errors='strict', buffering=-1)

Abre un archivo codificado utilizando el mode dado y retorna una instancia de StreamReaderWriter, proporcionando codificación/decodificación transparente. El modo de archivo predeterminado es 'r', que significa abrir el archivo en modo de lectura.

Nota

Los archivos codificados subyacentes siempre se abren en modo binario. No se realiza la conversión automática de '\n' en lectura y escritura. El argumento mode puede ser cualquier modo binario aceptable para la función incorporada open(); la 'b' se agrega automáticamente.

encoding especifica la codificación que se utilizará para el archivo. Se permite cualquier codificación que codifique y decodifique desde bytes, y los tipos de datos admitidos por los métodos de archivo dependen del códec utilizado.

errors puede darse para definir el manejo de errores. El valor predeterminado es 'estricto', lo que hace que se genere un ValueError en caso de que ocurra un error de codificación.

buffering tiene el mismo significado que para la función incorporada open(). Su valor predeterminado es -1, lo que significa que se utilizará el tamaño predeterminado del búfer.

codecs.EncodedFile(file, data_encoding, file_encoding=None, errors='strict')

Retorna una instancia de StreamRecoder, una versión envuelta de file que proporciona transcodificación transparente. El archivo original se cierra cuando se cierra la versión empaquetada.

Los datos escritos en el archivo empaquetado se decodifican de acuerdo con la data_encoding dada y luego se escriben en el archivo original como bytes usando file_encoding. Los bytes leídos del archivo original se decodifican según file_encoding, y el resultado se codifica utilizando data_encoding.

Si no se proporciona file_encoding, el valor predeterminado es data_encoding.

Se pueden dar errors para definir el manejo de errores. Su valor predeterminado es 'estricto', lo que hace que se genere ValueError en caso de que ocurra un error de codificación.

codecs.iterencode(iterator, encoding, errors='strict', **kwargs)

Utiliza un codificador incremental para codificar iterativamente la entrada proporcionada por iterator. Esta función es un generator. El argumento errors (así como cualquier otro argumento de palabra clave) se pasa al codificador incremental.

Esta función requiere que el códec acepte texto en objetos str para codificar. Por lo tanto, no admite codificadores de bytes a bytes, como base64_codec.

codecs.iterdecode(iterator, encoding, errors='strict', **kwargs)

Utiliza un decodificador incremental para decodificar iterativamente la entrada proporcionada por iterator. Esta función es un generator. El argumento errors (así como cualquier otro argumento de palabra clave) se pasa al decodificador incremental.

Esta función requiere que el códec acepte objetos bytes para decodificar. Por lo tanto, no admite codificadores de texto a texto como rot_13, aunque rot_13 puede usarse de manera equivalente con iterencode().

El módulo también proporciona las siguientes constantes que son útiles para leer y escribir en archivos dependientes de la plataforma:

codecs.BOM

codecs.BOM_BE

codecs.BOM_LE

codecs.BOM_UTF8

codecs.BOM_UTF16

codecs.BOM_UTF16_BE

codecs.BOM_UTF16_LE

codecs.BOM_UTF32

codecs.BOM_UTF32_BE

codecs.BOM_UTF32_LE

Estas constantes definen varias secuencias de bytes, que son marcas de orden de bytes Unicode (BOM) para varias codificaciones. Se utilizan en flujos de datos UTF-16 y UTF-32 para indicar el orden de bytes utilizado, y en UTF-8 como firma Unicode. BOM_UTF16 es BOM_UTF16_BE o BOM_UTF16_LE dependiendo del orden de bytes nativo de la plataforma, BOM es un alias para BOM_UTF16, BOM_LE para BOM_UTF16_LE y BOM_BE para BOM_UTF16_BE. Los otros representan la lista de materiales en las codificaciones UTF-8 y UTF-32.

Clases Base de Códec

El módulo codecs define un conjunto de clases base que definen las interfaces para trabajar con objetos de códec, y también puede usarse como base para implementaciones de códec personalizadas.

Cada códec tiene que definir cuatro interfaces para que pueda usarse como códec en Python: codificador sin estado, decodificador sin estado, lector de flujo y escritor de flujo. El lector de flujo y los escritores suelen reutilizar el codificador/decodificador sin estado para implementar los protocolos de archivo. Los autores de códecs también necesitan definir cómo manejará los errores de codificación y decodificación.

Manejadores de errores

To simplify and standardize error handling, codecs may implement different error handling schemes by accepting the errors string argument:

>>> 'German ß, ♬'.encode(encoding='ascii', errors='backslashreplace')
b'German \\xdf, \\u266c'
>>> 'German ß, ♬'.encode(encoding='ascii', errors='xmlcharrefreplace')
b'German &#223;, &#9836;'

The following error handlers can be used with all Python Codificaciones estándar codecs:

Valor

Significado

'strict'

Raise UnicodeError (or a subclass), this is the default. Implemented in strict_errors().

'ignore'

Ignore los datos mal formados y continúe sin previo aviso. Implementado en ignore_errors().

'replace'

Replace with a replacement marker. On encoding, use ? (ASCII character). On decoding, use � (U+FFFD, the official REPLACEMENT CHARACTER). Implemented in replace_errors().

'backslashreplace'

Replace with backslashed escape sequences. On encoding, use hexadecimal form of Unicode code point with formats \xhh \uxxxx \Uxxxxxxxx. On decoding, use hexadecimal form of byte value with format \xhh. Implemented in backslashreplace_errors().

'surrogateescape'

En la decodificación, reemplace el byte con código sustituto individual que va desde U+DC80 a U+DCFF. Este código se volverá a convertir en el mismo byte cuando se use el controlador de errores 'sustituto de paisaje' al codificar los datos. (Ver PEP 383 [https://www.python.org/dev/peps/pep-0383] para más información).

The following error handlers are only applicable to encoding (within text encodings):

Valor

Significado

'xmlcharrefreplace'

Replace with XML/HTML numeric character reference, which is a decimal form of Unicode code point with format &#num; Implemented in xmlcharrefreplace_errors().

'namereplace'

Replace with \N{...} escape sequences, what appears in the braces is the Name property from Unicode Character Database. Implemented in namereplace_errors().

Además, el siguiente controlador de errores es específico de los códecs dados:

Valor

Códecs

Significado

'surrogatepass'

utf-8, utf-16, utf-32, utf-16-be, utf-16-le, utf-32-be, utf-32-le

Allow encoding and decoding surrogate code point (U+D800 - U+DFFF) as normal code point. Otherwise these codecs treat the presence of surrogate code point in str as an error.

Nuevo en la versión 3.1: Los manejadores de errores 'surrogateescape' y 'surrogatepass'.

Distinto en la versión 3.4: The 'surrogatepass' error handler now works with utf-16* and utf-32* codecs.

Nuevo en la versión 3.5: El controlador de errores 'namereplace'.

Distinto en la versión 3.5: The 'backslashreplace' error handler now works with decoding and translating.

El conjunto de valores permitidos puede ampliarse registrando un nuevo controlador de errores con nombre:

codecs.register_error(name, error_handler)

Registre la función de manejo de errores error_handler bajo el nombre name. Se invocará el argumento error_handler durante la codificación y decodificación en caso de error, cuando name se especifica como el parámetro de errores.

Para la codificación, se llamará a error_handler con una instancia UnicodeEncodeError, que contiene información sobre la ubicación del error. El controlador de errores debe generar esta o una excepción diferente, o retornar una tupla con un reemplazo para la parte no codificable de la entrada y una posición donde la codificación debe continuar. El reemplazo puede ser str o bytes. Si el reemplazo son bytes, el codificador simplemente los copiará en el búfer de salida. Si el reemplazo es una cadena de caracteres, el codificador codificará el reemplazo. La codificación continúa en la entrada original en la posición especificada. Los valores de posición negativos se tratarán como relativos al final de la cadena de entrada. Si la posición resultante está fuera del límite, se generará IndexError.

La decodificación y traducción funcionan de manera similar, excepto que UnicodeDecodeError o UnicodeTranslateError se pasarán al controlador y el reemplazo del controlador de errores se colocará directamente en la salida.

Los controladores de errores registrados previamente (incluidos los controladores de errores estándar) se pueden buscar por nombre:

codecs.lookup_error(name)

Retorna el controlador de errores previamente registrado con el nombre name.

Lanza un LookupError en caso de que no se pueda encontrar el controlador.

Los siguientes controladores de errores estándar también están disponibles como funciones de nivel de módulo:

codecs.strict_errors(exception)

Implements the 'strict' error handling.

Each encoding or decoding error raises a UnicodeError.

codecs.ignore_errors(exception)

Implements the 'ignore' error handling.

Malformed data is ignored; encoding or decoding is continued without further notice.

codecs.replace_errors(exception)

Implements the 'replace' error handling.

Substitutes ? (ASCII character) for encoding errors or � (U+FFFD, the official REPLACEMENT CHARACTER) for decoding errors.

codecs.backslashreplace_errors(exception)

Implements the 'backslashreplace' error handling.

Malformed data is replaced by a backslashed escape sequence. On encoding, use the hexadecimal form of Unicode code point with formats \xhh \uxxxx \Uxxxxxxxx. On decoding, use the hexadecimal form of byte value with format \xhh.

Distinto en la versión 3.5: Works with decoding and translating.

codecs.xmlcharrefreplace_errors(exception)

Implements the 'xmlcharrefreplace' error handling (for encoding within text encoding only).

The unencodable character is replaced by an appropriate XML/HTML numeric character reference, which is a decimal form of Unicode code point with format &#num; .

codecs.namereplace_errors(exception)

Implements the 'namereplace' error handling (for encoding within text encoding only).

The unencodable character is replaced by a \N{...} escape sequence. The set of characters that appear in the braces is the Name property from Unicode Character Database. For example, the German lowercase letter 'ß' will be converted to byte sequence \N{LATIN SMALL LETTER SHARP S} .

Nuevo en la versión 3.5.

Codificación y decodificación sin estado

La clase base Codec define estos métodos que también definen las interfaces de función del codificador y decodificador sin estado:

Codec.encode(input, errors='strict')

Codifica el objeto input y retorna una tupla (objeto de salida, longitud consumida). Por ejemplo text encoding convierte un objeto de cadena de caracteres en un objeto de bytes utilizando una codificación de juego de caracteres particular (por ejemplo,``cp1252`` o iso-8859-1).

El argumento errors define el manejo de errores a aplicar. El valor predeterminado es el manejo estricto.

Es posible que el método no almacene estado en la instancia Codec. Use StreamWriter para códecs que deben mantener el estado para que la codificación sea eficiente.

El codificador debe poder manejar la entrada de longitud cero y retornar un objeto vacío del tipo de objeto de salida en esta situación.

Codec.decode(input, errors='strict')

Decodifica el objeto input y retorna una tupla (objeto de salida, longitud consumida). Por ejemplo, para un codificación de texto, la decodificación convierte un objeto de bytes codificado usando una codificación de juego de caracteres particular en un objeto de cadena de caracteres.

Para codificaciones de texto y códecs de bytes a bytes, input debe ser un objeto de bytes o uno que proporcione la interfaz de búfer de solo lectura, por ejemplo, objetos de búfer y archivos mapeados en memoria.

El argumento errors define el manejo de errores a aplicar. El valor predeterminado es el manejo estricto.

Es posible que el método no almacene estado en la instancia de Codec. Use StreamReader para códecs que deben mantener el estado para que la decodificación sea eficiente.

El decodificador debe poder manejar la entrada de longitud cero y retornar un objeto vacío del tipo de objeto de salida en esta situación.

Codificación y decodificación incrementales

Las clases IncrementalEncoder y IncrementalDecoder proporcionan la interfaz básica para la codificación y decodificación incrementales. La codificación/decodificación de la entrada no se realiza con una llamada a la función de codificador/decodificador sin estado, sino con varias llamadas al método encode()/decode() del codificador incremental /decodificador. El codificador/decodificador incremental realiza un seguimiento del proceso de codificación/decodificación durante las llamadas a métodos.

La salida combinada de las llamadas al método encode()/decode() es el mismo que si todas las entradas individuales se unieran en una, y esta entrada se codificara/decodificara con codificador/decodificador sin estado.

Objetos IncrementalEncoder

La clase IncrementalEncoder se usa para codificar una entrada en varios pasos. Define los siguientes métodos que cada codificador incremental debe definir para ser compatible con el registro de códec Python.

class codecs.IncrementalEncoder(errors='strict')

Constructor para una clase instancia de IncrementalEncoder.

Todos los codificadores incrementales deben proporcionar esta interfaz de constructor. Son libres de agregar argumentos de palabras clave adicionales, pero el registro de códecs de Python solo utiliza los definidos aquí.

La clase IncrementalEncoder puede implementar diferentes esquemas de manejo de errores al proporcionar el argumento de palabra clave errors. Ver Manejadores de errores para posibles valores.

El argumento errors se asignará a un atributo del mismo nombre. La asignación a este atributo hace posible cambiar entre diferentes estrategias de manejo de errores durante la vida útil del objeto IncrementalEncoder.

encode(object, final=False)

Codifica object (teniendo en cuenta el estado actual del codificador) y retorna el objeto codificado resultante. Si esta es la última llamada a encode() final debe ser verdadero (el valor predeterminado es falso).

reset()

Restablece el codificador al estado inicial. La salida se descarta: llama a .encode(object, final=True), pasando un byte vacío o una cadena de texto si es necesario, para restablecer el codificador y obtener la salida.

getstate()

Retorna el estado actual del codificador que debe ser un número entero. La implementación debe asegurarse de que 0 sea el estado más común. (Los estados que son más complicados que los enteros se pueden convertir en un entero al empaquetar/serializar el estado y codificar los bytes de la cadena resultante en un entero).

setstate(state)

Establece el estado del codificador en state. state debe ser un estado de codificador retornado por getstate().

Objetos IncrementalDecoder

La clase IncrementalDecoder se usa para decodificar una entrada en varios pasos. Define los siguientes métodos que cada decodificador incremental debe definir para ser compatible con el registro de códec Python.

class codecs.IncrementalDecoder(errors='strict')

Constructor para una instancia de IncrementalDecoder.

Todos los decodificadores incrementales deben proporcionar esta interfaz de constructor. Son libres de agregar argumentos de palabras clave adicionales, pero el registro de códecs de Python solo utiliza los definidos aquí.

La clase IncrementalDecoder puede implementar diferentes esquemas de manejo de errores al proporcionar el argumento de palabra clave errors. Ver Manejadores de errores para posibles valores.

El argumento errors se asignará a un atributo del mismo nombre. La asignación a este atributo hace posible cambiar entre diferentes estrategias de manejo de errores durante la vida útil del objeto IncrementalDecoder.

decode(object, final=False)

Decodifica object (teniendo en cuenta el estado actual del decodificador) y retorna el objeto decodificado resultante. Si esta es la última llamada a decode() final debe ser verdadero (el valor predeterminado es falso). Si final es verdadero, el decodificador debe decodificar la entrada por completo y debe vaciar todos los búferes. Si esto no es posible (por ejemplo, debido a secuencias de bytes incompletas al final de la entrada), debe iniciar el manejo de errores al igual que en el caso sin estado (lo que podría generar una excepción).

reset()

Restablece el decodificador al estado inicial.

getstate()

Retorna el estado actual del decodificador. Debe ser una tupla con dos elementos, el primero debe ser el búfer que contiene la entrada aún sin codificar. El segundo debe ser un número entero y puede ser información de estado adicional. (La implementación debe asegurarse de que 0 sea la información de estado adicional más común). Si esta información de estado adicional es 0, debe ser posible establecer el decodificador en el estado que no tiene entrada almacenada y 0 como información de estado adicional, de modo que alimentar la entrada previamente almacenada en el búfer al decodificador la retorna al estado anterior sin producir ninguna salida. (La información de estado adicional que es más complicada que los enteros se puede convertir en un entero al empaquetar/serializar la información y codificar los bytes de la cadena resultante en un entero).

setstate(state)

Establezca el estado del decodificador en state. state debe ser un estado de decodificador retornado por getstate().

Codificación y decodificación de flujos

Las clases StreamWriter y StreamReader proporcionan interfaces de trabajo genéricas que se pueden usar para implementar nuevos submódulos de codificación muy fácilmente. Ir a encodings.utf_8 para ver un ejemplo de cómo se hace esto.

Objetos StreamWriter

La clase StreamWriter es una subclase de Codec y define los siguientes métodos que cada escritor del flujo debe definir para ser compatible con el registro de códecs Python.

class codecs.StreamWriter(stream, errors='strict')

Constructor para una instancia de StreamWriter.

Todos los escritores de flujos deben proporcionar esta interfaz de constructor. Son libres de agregar argumentos de palabras clave adicionales, pero el registro de códecs de Python solo utiliza los definidos aquí.

El argumento stream debe ser un objeto tipo archivo abierto para escribir texto o datos binarios, según corresponda para el códec específico.

La clase StreamWriter puede implementar diferentes esquemas de manejo de errores al proporcionar el argumento de palabra clave errors. Consulte Manejadores de errores para ver los controladores de error estándar que puede admitir el códec de flujo subyacente.

El argumento errors se asignará a un atributo del mismo nombre. La asignación a este atributo hace posible cambiar entre diferentes estrategias de manejo de errores durante la vida útil del objeto StreamWriter.

write(object)

Escribe el contenido del objeto codificado en el flujo.

writelines(list)

Writes the concatenated iterable of strings to the stream (possibly by reusing the write() method). Infinite or very large iterables are not supported. The standard bytes-to-bytes codecs do not support this method.

reset()

Restablece los búfers de códec utilizados para mantener el estado interno.

Llamar a este método debería garantizar que los datos en la salida se pongan en un estado limpio que permita agregar datos nuevos sin tener que volver a escanear todo el flujo para recuperar el estado.

Además de los métodos anteriores, la clase StreamWriter también debe heredar todos los demás métodos y atributos del flujo subyacente.

Objetos StreamReader

La clase StreamReader es una subclase de Codec y define los siguientes métodos que cada lector de flujo debe definir para ser compatible con el registro de códecs de Python.

class codecs.StreamReader(stream, errors='strict')

Constructor para una instancia de StreamReader.

Todos los lectores de flujo deben proporcionar esta interfaz de constructor. Son libres de agregar argumentos de palabras clave adicionales, pero el registro de códecs de Python solo utiliza los definidos aquí.

El argumento stream debe ser un objeto tipo archivo abierto para leer texto o datos binarios, según corresponda para el códec específico.

La clase StreamReader puede implementar diferentes esquemas de manejo de errores al proporcionar el argumento de palabra clave errors. Consulte Manejadores de errores para ver los controladores de error estándar que puede admitir el códec de flujo subyacente.

El argumento errors se asignará a un atributo del mismo nombre. La asignación a este atributo hace posible cambiar entre diferentes estrategias de manejo de errores durante la vida útil del objeto StreamReader.

El conjunto de valores permitidos para el argumento errors se puede ampliar con register_error().

read(size=-1, chars=-1, firstline=False)

Decodifica datos del flujo y retorna el objeto resultante.

El argumento chars indica el número de puntos de código decodificados o bytes a retornar. El método read() nunca retornará más datos de los solicitados, pero podría retornar menos, si no hay suficientes disponibles.

El argumento size indica el número máximo aproximado de bytes codificados o puntos de código para leer para la decodificación. El decodificador puede modificar esta configuración según corresponda. El valor predeterminado -1 indica leer y decodificar tanto como sea posible. Este parámetro está diseñado para evitar tener que decodificar archivos grandes en un solo paso.

La bandera firstline indica que sería suficiente retornar solo la primera línea, si hay errores de decodificación en las líneas posteriores.

El método debe usar una estrategia de lectura codiciosa, lo que significa que debe leer la mayor cantidad de datos permitidos dentro de la definición de la codificación y el tamaño dado, por ejemplo si las terminaciones de codificación opcionales o los marcadores de estado están disponibles en la transmisión, también deben leerse.

readline(size=None, keepends=True)

Lee una línea del flujo de entrada y retorna los datos decodificados.

size, si se da, se pasa como argumento de tamaño al método read() del stream.

Si keepends es falso, las terminaciones de línea se eliminarán de las líneas retornadas.

readlines(sizehint=None, keepends=True)

Lee todas las líneas disponibles en el flujo de entrada y las retorna como una lista de líneas.

Los finales de línea se implementan utilizando el método decode() del códec y se incluyen en las entradas de la lista si keepends es verdadero.

sizehint, si se proporciona, se pasa como argumento size al método read() del stream.

reset()

Restablece los búfers de códec utilizados para mantener el estado interno.

Tenga en cuenta que ningún reposicionamiento de flujo debe suceder. Este método está destinado principalmente a poder recuperarse de errores de decodificación.

Además de los métodos anteriores, la clase StreamReader también debe heredar todos los demás métodos y atributos del flujo subyacente.

Objetos StreamReaderWriter

La clase StreamReaderWriter es una clase de conveniencia que permite envolver flujos que funcionan tanto en modo de lectura como de escritura.

El diseño es tal que uno puede usar las funciones de fábrica retornadas por la función lookup() para construir la instancia.

class codecs.StreamReaderWriter(stream, Reader, Writer, errors='strict')

Crea una instancia de StreamReaderWriter. stream debe ser un objeto similar a un archivo. Reader y Writer deben ser funciones o clases de fábrica que proporcionen la interfaz StreamReader y StreamWriter respectivamente. El manejo de errores se realiza de la misma manera que se define para los lectores y escritores de flujos.

Las instancias StreamReaderWriter definen las interfaces combinadas de StreamReader y clases StreamWriter. Heredan todos los demás métodos y atributos del flujo subyacente.

Objetos StreamRecoder

La clase StreamRecoder traduce datos de una codificación a otra, lo que a veces es útil cuando se trata de diferentes entornos de codificación.

El diseño es tal que uno puede usar las funciones de fábrica retornadas por la función lookup() para construir la instancia.

class codecs.StreamRecoder(stream, encode, decode, Reader, Writer, errors='strict')

Crea una instancia de StreamRecoder que implementa una conversión bidireccional: encode y decode funcionan en el frontend: los datos visibles para la llamada de código read() y write(), mientras que Reader y Writer funcionan en el backend — los datos en stream.

Puede usar estos objetos para realizar transcodificaciones transparentes, por ejemplo, de Latin-1 a UTF-8 y viceversa.

El argumento stream debe ser un objeto similar a un archivo.

Los argumentos encode y decode deben cumplir con la interfaz de Codec. Reader y Writer deben ser funciones o clases de fábrica que proporcionen objetos de la interfaz StreamReader y StreamWriter respectivamente.

El manejo de errores se realiza de la misma manera que se define para los lectores y escritores de flujos.

las instancias StreamRecoder definen las interfaces combinadas de las clases StreamReader y StreamWriter. Heredan todos los demás métodos y atributos del flujo subyacente.

Codificaciones y Unicode

Strings are stored internally as sequences of code points in range U+0000–U+10FFFF. (See PEP 393 [https://www.python.org/dev/peps/pep-0393] for more details about the implementation.) Once a string object is used outside of CPU and memory, endianness and how these arrays are stored as bytes become an issue. As with other codecs, serialising a string into a sequence of bytes is known as encoding, and recreating the string from the sequence of bytes is known as decoding. There are a variety of different text serialisation codecs, which are collectivity referred to as text encodings.

La codificación de texto más simple (llamada 'latin-1' o 'iso-8859-1') asigna los puntos de código 0–255 a los bytes 0x0 – 0xff, lo que significa que un objeto de cadena de caracteres que contiene puntos de código encima de U+00FF no se puede codificar con este códec. Al hacerlo, lanzará un UnicodeEncodeError que se parece a lo siguiente (aunque los detalles del mensaje de error pueden diferir): UnicodeEncodeError: 'latin-1' codec can't encode character '\u1234' 'in position 3: ordinal not in range(256).

Hay otro grupo de codificaciones (las llamadas codificaciones de mapa de caracteres) que eligen un subconjunto diferente de todos los puntos de código Unicode y cómo estos puntos de código se asignan a los bytes 0x0 – 0xff. Para ver cómo se hace esto, simplemente abra, por ejemplo encodings/cp1252.py (que es una codificación que se usa principalmente en Windows). Hay una cadena constante con 256 caracteres que le muestra qué carácter está asignado a qué valor de byte.

All of these encodings can only encode 256 of the 1114112 code points defined in Unicode. A simple and straightforward way that can store each Unicode code point, is to store each code point as four consecutive bytes. There are two possibilities: store the bytes in big endian or in little endian order. These two encodings are called UTF-32-BE and UTF-32-LE respectively. Their disadvantage is that if e.g. you use UTF-32-BE on a little endian machine you will always have to swap bytes on encoding and decoding. UTF-32 avoids this problem: bytes will always be in natural endianness. When these bytes are read by a CPU with a different endianness, then bytes have to be swapped though. To be able to detect the endianness of a UTF-16 or UTF-32 byte sequence, there’s the so called BOM («Byte Order Mark»). This is the Unicode character U+FEFF. This character can be prepended to every UTF-16 or UTF-32 byte sequence. The byte swapped version of this character (0xFFFE) is an illegal character that may not appear in a Unicode text. So when the first character in a UTF-16 or UTF-32 byte sequence appears to be a U+FFFE the bytes have to be swapped on decoding. Unfortunately the character U+FEFF had a second purpose as a ZERO WIDTH NO-BREAK SPACE: a character that has no width and doesn’t allow a word to be split. It can e.g. be used to give hints to a ligature algorithm. With Unicode 4.0 using U+FEFF as a ZERO WIDTH NO-BREAK SPACE has been deprecated (with U+2060 (WORD JOINER) assuming this role). Nevertheless Unicode software still must be able to handle U+FEFF in both roles: as a BOM it’s a device to determine the storage layout of the encoded bytes, and vanishes once the byte sequence has been decoded into a string; as a ZERO WIDTH NO-BREAK SPACE it’s a normal character that will be decoded like any other.

There’s another encoding that is able to encode the full range of Unicode characters: UTF-8. UTF-8 is an 8-bit encoding, which means there are no issues with byte order in UTF-8. Each byte in a UTF-8 byte sequence consists of two parts: marker bits (the most significant bits) and payload bits. The marker bits are a sequence of zero to four 1 bits followed by a 0 bit. Unicode characters are encoded like this (with x being payload bits, which when concatenated give the Unicode character):

Rango

Codificación

U-00000000 … U-0000007F

0xxxxxxx

U-00000080 … U-000007FF

110xxxxx 10xxxxxx

U-00000800 … U-0000FFFF

1110xxxx 10xxxxxx 10xxxxxx

U-00010000 … U-0010FFFF

11110xxx 10xxxxxx 10xxxxxx 10xxxxxx

El bit menos significativo del carácter Unicode es el bit x más a la derecha.

Como UTF-8 es una codificación de 8 bits, no se requiere una lista de materiales y cualquier carácter U+FEFF en la cadena decodificada (incluso si es el primer carácter) se trata como un ESPACIO SIN QUIEBRE DE ANCHO CERO` (``ZERO WIDTH NO-BREAK SPACE``).

Without external information it’s impossible to reliably determine which encoding was used for encoding a string. Each charmap encoding can decode any random byte sequence. However that’s not possible with UTF-8, as UTF-8 byte sequences have a structure that doesn’t allow arbitrary byte sequences. To increase the reliability with which a UTF-8 encoding can be detected, Microsoft invented a variant of UTF-8 (that Python calls "utf-8-sig") for its Notepad program: Before any of the Unicode characters is written to the file, a UTF-8 encoded BOM (which looks like this as a byte sequence: 0xef, 0xbb, 0xbf) is written. As it’s rather improbable that any charmap encoded file starts with these byte values (which would e.g. map to

LETRA LATINA PEQUEÑA I CON DIAERESIS

SEÑALADO A LA DERECHA DE DOBLE ÁNGULO MARCA DE CITA

SIGNO DE PREGUNTA INVERTIDO

en iso-8859-1), esto aumenta la probabilidad de que una codificación utf-8-sig pueda adivinarse correctamente a partir de la secuencia de bytes. Por lo tanto, aquí la lista de materiales no se utiliza para poder determinar el orden de bytes utilizado para generar la secuencia de bytes, sino como una firma que ayuda a adivinar la codificación. Al codificar, el códec utf-8-sig escribirá 0xef, 0xbb, 0xbf como los primeros tres bytes del archivo. Al decodificar, utf-8-sig omitirá esos tres bytes si aparecen como los primeros tres bytes en el archivo. En UTF-8, se desaconseja el uso de la lista de materiales y, en general, debe evitarse.

Codificaciones estándar

Python viene con una serie de códecs integrados, ya sea implementados como funciones C o con diccionarios como tablas de mapeo. La siguiente tabla enumera los códecs por nombre, junto con algunos alias comunes y los idiomas para los que probablemente se usa la codificación. Ni la lista de alias ni la lista de idiomas deben ser exhaustivas. Tenga en cuenta que las alternativas de ortografía que solo difieren en el caso o usan un guión en lugar de un guión bajo también son alias válidos; por lo tanto, por ejemplo 'utf-8' es un alias válido para el códec 'utf_8'.

CPython implementation detail: Algunas codificaciones comunes pueden omitir la maquinaria de búsqueda de códecs para mejorar el rendimiento. CPython solo reconoce estas oportunidades de optimización para un conjunto limitado de alias (sin distinción entre mayúsculas y minúsculas): utf-8, utf8, latin-1, latin1, iso-8859-1, iso8859-1, mbcs (solo Windows), ascii, us-ascii, utf-16, utf16, utf-32, utf32, y lo mismo usando guiones bajos en lugar de guiones. El uso de alias alternativos para estas codificaciones puede resultar en una ejecución más lenta.

Distinto en la versión 3.6: Oportunidad de optimización reconocida para us-ascii.

Muchos de los juegos de caracteres admiten los mismos idiomas. Varían en caracteres individuales (por ejemplo, si el SIGNO EURO es compatible o no), y en la asignación de caracteres para codificar posiciones. Para los idiomas europeos en particular, generalmente existen las siguientes variantes:

un conjunto de códigos ISO 8859

una página de códigos de Microsoft Windows, que generalmente se deriva de un conjunto de códigos 8859, pero reemplaza los caracteres de control con caracteres gráficos adicionales

una página de códigos EBCDIC de IBM

una página de códigos de IBM PC, que es compatible con ASCII

Códec

Aliases

Lenguajes

ascii

646, us-ascii

Inglés

big5

big5-tw, csbig5

Chino Tradicional

big5hkscs

big5-hkscs, hkscs

Chino Tradicional

cp037

IBM037, IBM039

Inglés

cp273

273, IBM273, csIBM273

Alemán

Nuevo en la versión 3.4.

cp424

EBCDIC-CP-HE, IBM424

Hebreo

cp437

437, IBM437

Inglés

cp500

EBCDIC-CP-BE, EBCDIC-CP-CH, IBM500

Europa Occidental

cp720

Árabe

cp737

Griego

cp775

IBM775

Lenguajes bálticos

cp850

850, IBM850

Europa Occidental

cp852

852, IBM852

Europa central y del este

cp855

855, IBM855

Búlgaro, Bielorruso, Macedonio, Ruso, Serbio

cp856

Hebreo

cp857

857, IBM857

Turco

cp858

858, IBM858

Europa Occidental

cp860

860, IBM860

Portugués

cp861

861, CP-IS, IBM861

Islandés

cp862

862, IBM862

Hebreo

cp863

863, IBM863

Canadiense

cp864

IBM864

Árabe

cp865

865, IBM865

Danés, Noruego

cp866

866, IBM866

Ruso

cp869

869, CP-GR, IBM869

Griego

cp874

Tailandés

cp875

Griego

cp932

932, ms932, mskanji, ms-kanji

Japonés

cp949

949, ms949, uhc

Coreano

cp950

950, ms950

Chino Tradicional

cp1006

Urdu

cp1026

ibm1026

Turco

cp1125

1125, ibm1125, cp866u, ruscii

Ucraniano

Nuevo en la versión 3.4.

cp1140

ibm1140

Europa Occidental

cp1250

windows-1250

Europa central y del este

cp1251

windows-1251

Búlgaro, Bielorruso, Macedonio, Ruso, Serbio

cp1252

windows-1252

Europa Occidental

cp1253

windows-1253

Griego

cp1254

windows-1254

Turco

cp1255

windows-1255

Hebreo

cp1256

windows-1256

Árabe

cp1257

windows-1257

Lenguajes bálticos

cp1258

windows-1258

Vietnamita

euc_jp

eucjp, ujis, u-jis

Japonés

euc_jis_2004

jisx0213, eucjis2004

Japonés

euc_jisx0213

eucjisx0213

Japonés

euc_kr

euckr, korean, ksc5601, ks_c-5601, ks_c-5601-1987, ksx1001, ks_x-1001

Coreano

gb2312

chinese, csiso58gb231280, euc-cn, euccn, eucgb2312-cn, gb2312-1980, gb2312-80, iso-ir-58

Chino simplificado

gbk

936, cp936, ms936

Chino Unificado

gb18030

gb18030-2000

Chino Unificado

hz

hzgb, hz-gb, hz-gb-2312

Chino simplificado

iso2022_jp

csiso2022jp, iso2022jp, iso-2022-jp

Japonés

iso2022_jp_1

iso2022jp-1, iso-2022-jp-1

Japonés

iso2022_jp_2

iso2022jp-2, iso-2022-jp-2

Japonés, Coreano, Chino simplificado, Europa occidental, Griego

iso2022_jp_2004

iso2022jp-2004, iso-2022-jp-2004

Japonés

iso2022_jp_3

iso2022jp-3, iso-2022-jp-3

Japonés

iso2022_jp_ext

iso2022jp-ext, iso-2022-jp-ext

Japonés

iso2022_kr

csiso2022kr, iso2022kr, iso-2022-kr

Coreano

latin_1

iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1

Europa Occidental

iso8859_2

iso-8859-2, latin2, L2

Europa central y del este

iso8859_3

iso-8859-3, latin3, L3

Esperanto, Maltés

iso8859_4

iso-8859-4, latin4, L4

Lenguajes bálticos

iso8859_5

iso-8859-5, cyrillic

Búlgaro, Bielorruso, Macedonio, Ruso, Serbio

iso8859_6

iso-8859-6, arabic

Árabe

iso8859_7

iso-8859-7, greek, greek8

Griego

iso8859_8

iso-8859-8, hebrew

Hebreo

iso8859_9

iso-8859-9, latin5, L5

Turco

iso8859_10

iso-8859-10, latin6, L6

Lenguajes nórdicos

iso8859_11

iso-8859-11, thai

Lenguajes tailandeses

iso8859_13

iso-8859-13, latin7, L7

Lenguajes bálticos

iso8859_14

iso-8859-14, latin8, L8

Lenguajes Celtas

iso8859_15

iso-8859-15, latin9, L9

Europa Occidental

iso8859_16

iso-8859-16, latin10, L10

Europa sudoriental

johab

cp1361, ms1361

Coreano

koi8_r

Ruso

koi8_t

Tayiko

Nuevo en la versión 3.5.

koi8_u

Ucraniano

kz1048

kz_1048, strk1048_2002, rk1048

Kazajo

Nuevo en la versión 3.5.

mac_cyrillic

maccyrillic

Búlgaro, Bielorruso, Macedonio, Ruso, Serbio

mac_greek

macgreek

Griego

mac_iceland

maciceland

Islandés

mac_latin2

maclatin2, maccentraleurope, mac_centeuro

Europa central y del este

mac_roman

macroman, macintosh

Europa Occidental

mac_turkish

macturkish

Turco

ptcp154

csptcp154, pt154, cp154, cyrillic-asian

Kazajo

shift_jis

csshiftjis, shiftjis, sjis, s_jis

Japonés

shift_jis_2004

shiftjis2004, sjis_2004, sjis2004

Japonés

shift_jisx0213

shiftjisx0213, sjisx0213, s_jisx0213

Japonés

utf_32

U32, utf32

todos los lenguajes

utf_32_be

UTF-32BE

todos los lenguajes

utf_32_le

UTF-32LE

todos los lenguajes

utf_16

U16, utf16

todos los lenguajes

utf_16_be

UTF-16BE

todos los lenguajes

utf_16_le

UTF-16LE

todos los lenguajes

utf_7

U7, unicode-1-1-utf-7

todos los lenguajes

utf_8

U8, UTF, utf8, cp65001

todos los lenguajes

utf_8_sig

todos los lenguajes

Distinto en la versión 3.4: Los codificadores utf-16* y utf-32* ya no permiten codificar puntos de código sustitutos (U+D800 – U+DFFF). Los decodificadores utf-32* ya no decodifican secuencias de bytes que corresponden a puntos de código sustituto.

Distinto en la versión 3.8: cp65001 ahora es un alias de utf_8.

Codificaciones específicas de Python

Varios códecs predefinidos son específicos de Python, por lo que sus nombres de códec no tienen significado fuera de Python. Estos se enumeran en las tablas a continuación según los tipos de entrada y salida esperados (tenga en cuenta que si bien las codificaciones de texto son el caso de uso más común para los códecs, la infraestructura de códecs subyacente admite transformaciones de datos arbitrarias en lugar de solo codificaciones de texto). Para los códecs asimétricos, el significado indicado describe la dirección de codificación.

Codificaciones de texto

Los siguientes códecs proporcionan codificación de str a bytes y decodificación de bytes-like object a str, similar a las codificaciones de texto Unicode.

Códec

Aliases

Significado

idna

Implementar RFC 3490 [https://tools.ietf.org/html/rfc3490.html], ver también encodings.idna. Solo se admite errors='strict'.

mbcs

ansi, dbcs

Solo Windows: codifique el operando de acuerdo con la página de códigos ANSI (CP_ACP).

oem

Solo Windows: codifique el operando de acuerdo con la página de códigos OEM (CP_OEMCP).

Nuevo en la versión 3.6.

palmos

Codificación de PalmOS 3.5.

punycode

Implementar RFC 3492 [https://tools.ietf.org/html/rfc3492.html]. Los códecs con estado no son compatibles.

raw_unicode_escape

Codificación Latin-1 con \uXXXX y \UXXXXXXXX para otros puntos de código. Las barras invertidas existentes no se escapan de ninguna manera. Se usa en el protocolo Python pickle.

indefinido

Lanza una excepción para todas las conversiones, incluso cadenas vacías. El controlador de errores se ignora.

unicode_escape

Codificación adecuada como contenido de un literal Unicode en código fuente Python codificado en ASCII, excepto que no se escapan las comillas. Decodificar desde el código fuente Latin-1. Tenga en cuenta que el código fuente de Python realmente usa UTF-8 por defecto.

Distinto en la versión 3.8: Se elimina el códec «unicode_internal».

Transformaciones Binarias

Los siguientes códecs proporcionan transformaciones binarias: mapeos de bytes-like object a bytes. No son compatibles con bytes.decode() (que solo produce str de salida).

Códec

Aliases

Significado

Codificador / decodificador

base64_codec 1

base64, base_64

Convierta el operando a MIME base64 multilínea (el resultado siempre incluye un '\n' final).

Distinto en la versión 3.4: acepta cualquier bytes-like object como entrada para codificar y decodificar

base64.encodebytes() / base64.decodebytes()

bz2_codec

bz2

Comprime el operando usando bz2.

bz2.compress() / bz2.decompress()

hex_codec

hex

Convierte el operando en representación hexadecimal, con dos dígitos por byte.

binascii.b2a_hex() / binascii.a2b_hex()

quopri_codec

quopri, quotedprintable, quoted_printable

Convierte el operando a MIME citado imprimible.

quopri.encode() con quotetabs=True / quopri.decode()

uu_codec

uu

Convierte el operando usando uuencode.

uu.encode() / uu.decode()

zlib_codec

zip, zlib

Comprime el operando usando gzip.

zlib.compress() / zlib.decompress()

1

Además de objetos similares a bytes, 'base64_codec' también acepta instancias solo ASCII de str para decodificación

Nuevo en la versión 3.2: Restauración de las transformaciones binarias.

Distinto en la versión 3.4: Restauración de los alias para las transformaciones binarias.

Transformaciones de texto

El siguiente códec proporciona una transformación de texto: un mapeo de str a str. No es compatible con str.encode() (que solo produce bytes de salida).

Códec

Aliases

Significado

rot_13

rot13

Retorna el cifrado César (Caesar-cypher) del operando.

Nuevo en la versión 3.2: Restauración de la transformación de texto rot_13.

Distinto en la versión 3.4: Restauración del alias rot13.

encodings.idna — Nombres de dominio internacionalizados en aplicaciones

Este módulo implementa RFC 3490 [https://tools.ietf.org/html/rfc3490.html] (nombres de dominio internacionalizados en aplicaciones) y RFC 3492 [https://tools.ietf.org/html/rfc3492.html] (Nameprep: un perfil de Stringprep para nombres de dominio internacionalizados (IDN)). Se basa en la codificación punycode y stringprep.

If you need the IDNA 2008 standard from RFC 5891 [https://tools.ietf.org/html/rfc5891.html] and RFC 5895 [https://tools.ietf.org/html/rfc5895.html], use the third-party idna module [https://pypi.org/project/idna/].

Estas RFC juntas definen un protocolo para admitir caracteres no ASCII en los nombres de dominio. Un nombre de dominio que contiene caracteres no ASCII (como www.Alliancefrançaise.nu) se convierte en una codificación compatible con ASCII (ACE, como www.xn--alliancefranaise-npb.nu). La forma ACE del nombre de dominio se utiliza en todos los lugares donde el protocolo no permite caracteres arbitrarios, como consultas DNS, campos HTTP Host, etc. Esta conversión se lleva a cabo en la aplicación; si es posible invisible para el usuario: la aplicación debe convertir de forma transparente las etiquetas de dominio Unicode a IDNA en el cable, y volver a convertir las etiquetas ACE a Unicode antes de presentarlas al usuario.

Python admite esta conversión de varias maneras: el códec idna realiza la conversión entre Unicode y ACE, separando una cadena de entrada en etiquetas basadas en los caracteres separadores definidos en la sección 3.1 de RFC 3490 RFC 3490#section-3.1 [https://tools.ietf.org/html/rfc3490.html#section-3.1] y convertir cada etiqueta a ACE según sea necesario, y por el contrario, separar una cadena de bytes de entrada en etiquetas basadas en el separador . y convertir cualquier etiqueta ACE encontrada en unicode. Además, el módulo socket convierte de forma transparente los nombres de host Unicode a ACE, por lo que las aplicaciones no necesitan preocuparse por convertir los nombres de host ellos mismos cuando los pasan al módulo de socket. Además de eso, los módulos que tienen nombres de host como parámetros de función, como http.client y ftplib, aceptan nombres de host Unicode (http.client y luego también envían un mensaje transparente IDNA hostname en el campo Host si envía ese campo).

Al recibir nombres de host desde el cable (como en la búsqueda inversa de nombres), no se realiza una conversión automática a Unicode: las aplicaciones que deseen presentar dichos nombres de host al usuario deben decodificarlos en Unicode.

El módulo encodings.idna también implementa el procedimiento nameprep, que realiza ciertas normalizaciones en los nombres de host, para lograr la insensibilidad a mayúsculas y minúsculas de los nombres de dominio internacionales y unificar caracteres similares. Las funciones nameprep se pueden usar directamente si lo desea.

encodings.idna.nameprep(label)

Retorna la versión pasada por nameprep (o versión nameprepped) de label. La implementación actualmente asume cadenas de caracteres de consulta, por lo que AllowUnassigned es verdadero.

encodings.idna.ToASCII(label)

Convierte una etiqueta a ASCII, como se especifica en RFC 3490 [https://tools.ietf.org/html/rfc3490.html]. Se supone que UseSTD3ASCIIRules es falso.

encodings.idna.ToUnicode(label)

Convierte una etiqueta a Unicode, como se especifica en RFC 3490 [https://tools.ietf.org/html/rfc3490.html].

encodings.mbcs — Página de códigos ANSI de Windows

Este módulo implementa la página de códigos ANSI (CP_ACP).

Availability: solo Windows.

Distinto en la versión 3.3: Admite cualquier controlador de errores.

Distinto en la versión 3.2: Antes de 3.2, se ignoraba el argumento errors; 'replace' siempre se usó para codificar e 'ignore' para decodificar.

encodings.utf_8_sig — Códec UTF-8 con firma BOM

Este módulo implementa una variante del códec UTF-8. Al codificar, una lista de materiales codificada en UTF-8 se antepondrá a los bytes codificados en UTF-8. Para el codificador con estado esto solo se hace una vez (en la primera escritura en el flujo de bytes). En la decodificación, se omitirá una lista de materiales opcional codificada en UTF-8 al comienzo de los datos.

Tipos de datos

Los módulos descritos en este capítulo proporcionan una variedad de tipos de datos especializados, como fechas y horas, matrices de tipo fijo (fixed-type arrays), colas de montículos (heap queues), colas de doble extremo (double-ended queues) y enumeraciones.

Python también proporciona algunos tipos de datos integrados, concretamente dict, list, set y frozenset, y tuple. La clase str se utiliza para contener cadenas de caracteres Unicode, y las clases bytes y bytearray se utilizan para contener datos binarios.

En este capítulo se documentan los siguientes módulos:

datetime — Tipos básicos de fecha y hora

Objetos conscientes (aware) y naífs (naive)

Constantes

Tipos disponibles

Propiedades comunes

Determinando si un objeto es Consciente (Aware) o Naíf (Naive)

Objetos timedelta

Ejemplos de uso: timedelta

Objeto date

Ejemplos de uso: date

Objetos datetime

Ejemplos de uso: datetime

Objetos time

Ejemplos de uso: time

Objetos tzinfo

Objetos timezone

Comportamiento strftime() y strptime()

Códigos de formato strftime() y strptime()

Detalle técnico

zoneinfo — Soporte de zona horaria IANA

Usando ZoneInfo

Fuentes de datos

Configurando los orígenes de datos

Configuración en tiempo de compilación

Configuración del entorno

Configuración de tiempo de ejecución

La clase ZoneInfo

Representaciones de cadenas

Serialización de Pickle

Funciones

Globales

Excepciones y advertencias

calendar — Funciones generales relacionadas con el calendario

collections — Tipos de datos contenedor

Objetos ChainMap

Ejemplos y recetas ChainMap

Objetos Counter

Objetos deque

Recetas deque

Objetos defaultdict

Ejemplos defaultdict

namedtuple() Funciones Factory para Tuplas y Campos con Nombres

Objetos OrderedDict

Ejemplos y Recetas OrderedDict

Objetos UserDict

Objetos UserList

Objetos UserString

collections.abc — Clases Base Abstractas para Contenedores

Colecciones Clases Base Abstractas

heapq — Algoritmo de colas montículos (heap)

Ejemplos Básicos

Notas de Aplicación de la Cola de Prioridades

Teoría

bisect — Algoritmo de bisección de arreglos

Búsqueda en listas ordenadas

Otros ejemplos

array — Arreglos eficientes de valores numéricos

weakref — Referencias débiles

Objetos de Referencias Débiles

Ejemplo

Objetos Finalizadores

Comparando finalizadores con los métodos __del__()

types — Creación de tipos dinámicos y nombres para tipos integrados

Creación dinámica de tipos

Tipos de Intérpretes Estándar

Clases y funciones de utilidad adicionales

Funciones de utilidad de corutina

copy — Operaciones de copia superficial y profunda

pprint — Impresión bonita de datos

Objetos PrettyPrinter

Ejemplo

reprlib — Implementación repr() alternativa

Objetos Repr

Subclasificando Objetos Repr

enum — Soporte para enumeraciones

Contenido del Módulo

Creando un Enum

Acceso programático a los miembros de la enumeración y sus atributos

Duplicando miembros y valores enum

Garantizando valores de enumeración únicos

Usando valores automáticos

Iteración

Comparaciones

Miembros permitidos y atributos de enumeraciones

Subclases restringidas de Enum

Serialización

API Funcional

Enumeraciones derivadas

IntEnum

IntFlag

Bandera

Otros

Cuándo usar __new__() contra __init__()

Ejemplos interesantes

Omitir valores

Usando auto

Usando object

Usando una cadena descriptiva

Usando __new__() personalizados

OrderedEnum

DuplicateFreeEnum

Planeta

Periodo de tiempo

¿Cómo son diferentes las Enums?

Clases Enum

Miembros de Enum (también conocidos como instancias)

Puntos más finos

Nombres soportados __dunder__

Nombres _sunder_ compatibles

_Private__names

Tipo de miembro Enum

Valor booleano de las clases y miembros Enum

Enum clases con métodos

Combinando miembros de``Flag``

graphlib — Functionality to operate with graph-like structures

Exceptions

datetime — Tipos básicos de fecha y hora

Código fuente: Lib/datetime.py [https://github.com/python/cpython/tree/3.9/Lib/datetime.py]

El módulo datetime proporciona clases para manipular fechas y horas.

Si bien la implementación permite operaciones aritméticas con fechas y horas, su principal objetivo es poder extraer campos de forma eficiente para su posterior manipulación o formateo.

Ver también

Módulo calendar

Funciones generales relacionadas a calendar.

Módulo time

Acceso a tiempo y conversiones.

Module zoneinfo

Concrete time zones representing the IANA time zone database.

Paquete dateutil [https://dateutil.readthedocs.io/en/stable/]

Biblioteca de terceros con zona horaria ampliada y soporte de análisis.

Objetos conscientes (aware) y naífs (naive)

Los objetos de fecha y hora pueden clasificarse como conscientes (aware) o naífs (naive) dependiendo de si incluyen o no información de zona horaria.

Con suficiente conocimiento de los ajustes de tiempo políticos y algorítmicos aplicables, como la zona horaria y la información del horario de verano, un objeto consciente puede ubicarse en relación con otros objetos conscientes. Un objeto consciente representa un momento específico en el tiempo que no está abierto a interpretación. 1

Un objeto ingenuo no contiene suficiente información para ubicarse sin ambigüedades en relación con otros objetos de fecha/hora. Si un objeto ingenuo representa la hora universal coordinada (UTC), la hora local o la hora en alguna otra zona horaria depende exclusivamente del programa, al igual que depende del programa si un número en particular representa metros, millas o masa. Los objetos ingenuos son fáciles de entender y trabajar con ellos, a costa de ignorar algunos aspectos de la realidad.

Para las aplicaciones que requieren objetos conscientes, los objetos datetime y time tienen un atributo de información de zona horaria opcional, tzinfo, que se puede establecer en una instancia de una subclase de la clase abstracta tzinfo. Estos objetos tzinfo capturan información sobre el desplazamiento de la hora UTC, el nombre de la zona horaria y si el horario de verano está en vigor.

El módulo datetime solo proporciona una clase concreta tzinfo, la clase timezone. La clase timezone puede representar zonas horarias simples con desplazamientos fijos desde UTC, como UTC o las zonas horarias EST y EDT de América del Norte. La compatibilidad de zonas horarias con niveles de detalle más profundos depende de la aplicación. Las reglas para el ajuste del tiempo en todo el mundo son mas políticas que racionales, cambian con frecuencia y no existe un estándar adecuado para cada aplicación, aparte de UTC.

Constantes

El módulo datetime exporta las siguientes constantes:

datetime.MINYEAR

El número de año más pequeño permitido en un objeto date o datetime. MINYEAR es` 1`.

datetime.MAXYEAR

El número de año más grande permitido en un objeto date o en datetimeMAXYEAR es` 9999`.

Tipos disponibles

class datetime.date

Una fecha naíf (naive) idealizada, suponiendo que el calendario gregoriano actual siempre estuvo, y siempre estará, vigente. Atributos: year, month, y day.

class datetime.time

Un tiempo idealizado, independiente de cualquier día en particular, suponiendo que cada día tenga exactamente 24* 60* 60 segundos. (Aquí no hay noción de «segundos intercalares».) Atributos: hour, minute, second, microsecond, y tzinfo.

class datetime.datetime

Una combinación de una fecha y una hora. Atributos: year, month, day, hour, minute, second, microsecond , y tzinfo.

class datetime.timedelta

Una duración que expresa la diferencia entre dos instancias date, time o datetime a una resolución de microsegundos.

class datetime.tzinfo

Una clase base abstracta para objetos de información de zona horaria. Estos son utilizados por las clases datetime y time para proporcionar una noción personalizable de ajuste de hora (por ejemplo, para tener en cuenta la zona horaria y / o el horario de verano).

class datetime.timezone

Una clase que implementa la clase de base abstracta tzinfo como un desplazamiento fijo desde el UTC.

Nuevo en la versión 3.2.

Los objetos de este tipo son inmutables.

Relaciones de subclase:

object
    timedelta
    tzinfo
        timezone
    time
    date
        datetime

Propiedades comunes

Las clases date, datetime, time, y timezone comparten estas características comunes:

Los objetos de este tipo son inmutables.

Los objetos de este tipo son hashable, lo que significa que pueden usarse como claves de diccionario.

Los objetos de este tipo admiten el pickling eficiente a través del módulo pickle.

Determinando si un objeto es Consciente (Aware) o Naíf (Naive)

Los objetos del tipo date son siempre naíf (naive).

Un objeto de tipo time o datetime puede ser consciente (aware) o naíf (naive).

Un objeto datetime d es consciente si se cumplen los dos siguientes:

d.tzinfo no es None

d.tzinfo.utcoffset(d) no retorna None

De lo contrario, d es naíf (naive).

A time object t es consciente si ambos de los siguientes se mantienen:

t.tzinfo no es None

t.tzinfo.utcoffset(None) no retorna None.

De lo contrario, t es naíf (naive).

La distinción entre los objetos consciente (aware) y naíf (naive) no se aplica a timedelta.

Objetos timedelta

El objeto timedelta representa una duración, la diferencia entre dos fechas u horas.

class datetime.timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0)

Todos los argumentos son opcionales y predeterminados a 0. Los argumentos pueden ser enteros o flotantes, y pueden ser positivos o negativos.

Solo days, seconds y microseconds se almacenan internamente. Los argumentos se convierten a esas unidades:

Un milisegundo se convierte a 1000 microsegundos.

Un minuto se convierte a 60 segundos.

Una hora se convierte a 3600 segundos.

Una semana se convierte a 7 días.

y los días, segundos y microsegundos se normalizan para que la representación sea única, con

0 <= microsegundos < 1000000

0 <= segundos< 3600*24 (el número de segundos en un día)

-999999999 <= days <= 999999999

El siguiente ejemplo ilustra cómo cualquier argumento además de days, seconds y microseconds se «fusionan» y normalizan en esos tres atributos resultantes:

>>> from datetime import timedelta
>>> delta = timedelta(
...     days=50,
...     seconds=27,
...     microseconds=10,
...     milliseconds=29000,
...     minutes=5,
...     hours=8,
...     weeks=2
... )
>>> # Only days, seconds, and microseconds remain
>>> delta
datetime.timedelta(days=64, seconds=29156, microseconds=10)

Si algún argumento es flotante y hay microsegundos fraccionarios, los microsegundos fraccionarios que quedan de todos los argumentos se combinan y su suma se redondea al microsegundo más cercano utilizando el desempate de medio redondeo a par. Si ningún argumento es flotante, los procesos de conversión y normalización son exactos (no se pierde información).

Si el valor normalizado de los días se encuentra fuera del rango indicado, se lanza OverflowError.

Tenga en cuenta que la normalización de los valores negativos puede ser sorprendente al principio. Por ejemplo:

>>> from datetime import timedelta
>>> d = timedelta(microseconds=-1)
>>> (d.days, d.seconds, d.microseconds)
(-1, 86399, 999999)

Atributos de clase:

timedelta.min

El objeto más negativo en timedelta, timedelta(-999999999).

timedelta.max

El objeto más positivo de la timedelta, timedelta(days=999999999, hours=23, minutes=59, seconds=59, microseconds=999999).

timedelta.resolution

La diferencia más pequeña posible entre los objetos no iguales timedelta timedelta(microseconds=1).

Tenga en cuenta que, debido a la normalización, timedelta.max> -timedelta.min. -timedelta.max no es representable como un objeto timedelta.

Atributos de instancia (solo lectura):

Atributo

Valor

days

Entre -999999999 y 999999999 inclusive

seconds

Entre 0 y 86399 inclusive

microseconds

Entre 0 y 999999 inclusive

Operaciones soportadas:

Operación

Resultado

t1 = t2 + t3

Suma de t2 y t3. Después t1-t2 == t3 y t1-t3 == t2 son verdaderos. (1)

t1 = t2 - t3

La suma de t2 y t3. Después t1 == t2 - t3 y t2 == t1 + t3 son verdaderos. (1)(6)

t1 = t2 * i o t1 = i * t2

Delta multiplicado por un entero. Después t1 // i == t2 es verdadero, siempre que i != 0.

En general, t1 * i == t1 * (i-1) + t1 es verdadero. (1)

t1 = t2 * f o t1 = f * t2

Delta multiplicado por un número decimal. El resultado se redondea al múltiplo mas cercano de timedelta.resolution usando redondeo de medio a par.

f = t2 / t3

División (3) de la duración total t2 por unidad de intervalo t3. Retorna un objeto float.

t1 = t2 / f o t1 = t2 / i

Delta dividido por un número decimal o un entero. El resultado se redondea al múltiplo más cercano de timedelta.resolution usando redondeo de medio a par.

t1 = t2 // i o t1 = t2 // t3

El piso (floor) se calcula y el resto (si lo hay) se descarta. En el segundo caso, se retorna un entero. (3)

t1 = t2 % t3

El resto se calcula como un objeto timedelta. (3)

q, r = divmod(t1, t2)

Calcula el cociente y el resto: q = t1 // t2 (3) y r = t1% t2. q es un entero y r es un objeto timedelta.

+t1

Retorna un objeto timedelta con el mismo valor. (2)

-t1

equivalente a timedelta(-t1.days, -t1.seconds, -t1.microseconds), y a t1* -1. (1)(4)

abs(t)

equivalente a +t cuando t.days>= 0, y a -*t* cuando t.days < 0. (2)

str(t)

Retorna una cadena de caracteres en la forma [D day[s], ][H]H:MM:SS[.UUUUUU], donde D es negativo para negativo t. (5)

repr(t)

Retorna una representación de cadena del objeto timedelta como una llamada de constructor con valores de atributos canónicos.

Notas:

Esto es exacto pero puede desbordarse.

Esto es exacto pero no puede desbordarse.

División por 0 genera ZeroDivisionError.

-timedelta.max no es representable como un objeto timedelta.

Las representaciones de cadena de caracteres de los objetos timedelta se normalizan de manera similar a su representación interna. Esto conduce a resultados algo inusuales para timedeltas negativos. Por ejemplo:

>>> timedelta(hours=-5)
datetime.timedelta(days=-1, seconds=68400)
>>> print(_)
-1 day, 19:00:00

La expresión t2 - t3 siempre será igual a la expresión t2 + (-t3) excepto cuando t3 es igual a timedelta.max; en ese caso, el primero producirá un resultado mientras que el segundo se desbordará.

Además de las operaciones enumeradas anteriormente, los objetos timedelta admiten ciertas sumas y restas con objetos date y datetime (ver más abajo).

Distinto en la versión 3.2: La división de piso y la división verdadera de un objeto timedelta por otro timedelta ahora son compatibles, al igual que las operaciones restantes y la función divmod(). La división verdadera y multiplicación de un objeto timedelta por un objeto flotante ahora son compatibles.

Comparaciones de los objetos timedelta son compatibles, con algunas limitaciones.

Las comparaciones == o != Siempre retornan bool, sin importar el tipo de objeto comparado:

>>> from datetime import timedelta
>>> delta1 = timedelta(seconds=57)
>>> delta2 = timedelta(hours=25, seconds=2)
>>> delta2 != delta1
True
>>> delta2 == 5
False

Para todas las demás comparaciones (como < y >), cuando un objeto timedelta se compara con un objeto de un tipo diferente, se genera TypeError:

>>> delta2 > delta1
True
>>> delta2 > 5
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: '>' not supported between instances of 'datetime.timedelta' and 'int'

En contextos booleanos, un objeto timedelta se considera verdadero si y solo si no es igual a timedelta (0).

Métodos de instancia:

timedelta.total_seconds()

Retorna el número total de segundos contenidos en la duración. Equivalente a td / timedelta(segundos=1). Para unidades de intervalo que no sean segundos, use la forma de división directamente (por ejemplo, td / timedelta(microseconds=1)).

Tenga en cuenta que para intervalos de tiempo muy largos (más de 270 años en la mayoría de las plataformas) este método perderá precisión de microsegundos.

Nuevo en la versión 3.2.

Ejemplos de uso: timedelta

Ejemplos adicionales de normalización:

>>> # Components of another_year add up to exactly 365 days
>>> from datetime import timedelta
>>> year = timedelta(days=365)
>>> another_year = timedelta(weeks=40, days=84, hours=23,
...                          minutes=50, seconds=600)
>>> year == another_year
True
>>> year.total_seconds()
31536000.0

Ejemplos de timedelta aritmética:

>>> from datetime import timedelta
>>> year = timedelta(days=365)
>>> ten_years = 10 * year
>>> ten_years
datetime.timedelta(days=3650)
>>> ten_years.days // 365
10
>>> nine_years = ten_years - year
>>> nine_years
datetime.timedelta(days=3285)
>>> three_years = nine_years // 3
>>> three_years, three_years.days // 365
(datetime.timedelta(days=1095), 3)

Objeto date

El objeto date representa una fecha (año, mes y día) en un calendario idealizado, el calendario gregoriano actual se extiende indefinidamente en ambas direcciones.

El 1 de enero del año 1 se llama día número 1, el 2 de enero del año 1 se llama día número 2, y así sucesivamente. 2

class datetime.date(year, month, day)

Todos los argumentos son obligatorios. Los argumentos deben ser enteros, en los siguientes rangos:

MINYEAR <= year <= MAXYEAR

1 <= month <= 12

1 <= day <= number of days in the given month and year

Si se proporciona un argumento fuera de esos rangos, ValueError se genera.

Otros constructores, todos los métodos de clase:

classmethod date.today()

Retorna la fecha local actual.

Esto es equivalente a date.fromtimestamp(time.time()).

classmethod date.fromtimestamp(timestamp)

Retorna la fecha local correspondiente a la marca de tiempo POSIX, tal como la retorna time.time().

Esto puede generar OverflowError, si la marca de tiempo está fuera del rango de valores admitidos por la plataforma C localtime(), y OSError en localtime() falla . Es común que esto se restrinja a años desde 1970 hasta 2038. Tenga en cuenta que en los sistemas que no son POSIX que incluyen segundos bisiestos en su noción de marca de tiempo, los segundos bisiestos son ignorados por fromtimestamp().

Distinto en la versión 3.3: Se genera OverflowError en lugar de ValueError si la marca de tiempo está fuera del rango de valores admitidos por la plataforma C localtime(). Se genera OSError en lugar de ValueError cuando localtime(), falla.

classmethod date.fromordinal(ordinal)

Retorna la fecha correspondiente al ordinal gregoriano proléptico, donde el 1 de enero del año 1 tiene el ordinal 1.

ValueError se genera a menos que 1 <= ordinal <= date.max.toordinal(). ()``. Para cualquier fecha d, date.fromordinal(d.toordinal()) == d.

classmethod date.fromisoformat(date_string)

Retorna date correspondiente a una date_string dada en el formato YYYY-MM-DD:

>>> from datetime import date
>>> date.fromisoformat('2019-12-04')
datetime.date(2019, 12, 4)

Este es el inverso de date.isoformat(). Solo admite el formato AAAA-MM-DD.

Nuevo en la versión 3.7.

classmethod date.fromisocalendar(year, week, day)

Retorna date correspondiente a la fecha del calendario ISO especificada por año, semana y día. Esta es la inversa de la función date.isocalendar().

Nuevo en la versión 3.8.

Atributos de clase:

date.min

La fecha representable más antigua, date(MINYEAR, 1, 1).

date.max

La última fecha representable, date(MAXYEAR, 12, 31).

date.resolution

La menor diferencia entre objetos de fecha no iguales, timedelta(days=1).

Atributos de instancia (solo lectura):

date.year

Entre MINYEAR y MAXYEAR inclusive.

date.month

Entre 1 y 12 inclusive.

date.day

Entre 1 y el número de días en el mes dado del año dado.

Operaciones soportadas:

Operación

Resultado

date2 = date1 + timedelta

date2 es timedelta.days días eliminados de date1. (1)

date2 = date1 - timedelta

Calcula date2 tal que date2 + timedelta == date1. (2)

timedelta = date1 - date2

(3)

date1 < date2

date1 se considera menor que date2 cuando date1 precede a date2 en el tiempo. (4)

Notas:

date2 se mueve hacia adelante en el tiempo si timedelta.days > 0, o hacia atrás si timedelta.days < 0. Después date2 - date1 == timedelta. days. timedelta.seconds y timedelta.microseconds se ignoran. OverflowError se lanza si date2.year sería menor que MINYEAR o mayor que MAXYEAR.

timedelta.seconds y timedelta.microseconds son ignorados.

Esto es exacto y no puede desbordarse. timedelta.seconds y timedelta.microseconds son 0, y date2 + timedelta == date1.

En otras palabras, date1 < date2 si y solo si date1.toordinal()) < date2.toordinal(). La comparación de fechas plantea TypeError si el otro elemento comparado no es también un objeto date. Sin embargo, se retorna NotImplemented si el otro elemento comparado tiene un atributo timetuple(). Este enlace ofrece a otros tipos de objetos de fecha la posibilidad de implementar una comparación de tipos mixtos. Si no, cuando un objeto date se compara con un objeto de un tipo diferente, TypeError se genera a menos que la comparación sea == or !=. Los últimos casos retorna False o True, respectivamente.

En contextos booleanos, todos los objetos date se consideran verdaderos.

Métodos de instancia:

date.replace(year=self.year, month=self.month, day=self.day)

Retorna una fecha con el mismo valor, a excepción de aquellos parámetros dados nuevos valores por cualquier argumento de palabra clave especificado.

Ejemplo:

>>> from datetime import date
>>> d = date(2002, 12, 31)
>>> d.replace(day=26)
datetime.date(2002, 12, 26)

date.timetuple()

Retorna una time.struct_time como la que retorna time.localtime().

Las horas, minutos y segundos son 0, y el indicador DST es -1.

d.timetuple() es equivalente a:

time.struct_time((d.year, d.month, d.day, 0, 0, 0, d.weekday(), yday, -1))

donde yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1 es el número de día dentro del año actual que comienza con 1 para el 1 de enero.

date.toordinal()

Retorna el ordinal gregoriano proléptico de la fecha, donde el 1 de enero del año 1 tiene el ordinal 1. Para cualquiera date object d, date.fromordinal(d.toordinal()) == d.

date.weekday()

Retorna el día de la semana como un número entero, donde el lunes es 0 y el domingo es 6. Por ejemplo, date(2002, 12, 4).weekday() == 2, un miércoles. Ver también isoweekday().

date.isoweekday()

Retorna el día de la semana como un número entero, donde el lunes es 1 y el domingo es 7. Por ejemplo, date(2002, 12, 4).isoweekday() == 3, un miércoles. Ver también weekday(), isocalendar().

date.isocalendar()

Retorna un objeto named tuple con tres componentes: year, week y weekday.

El calendario ISO es una variante amplia utilizada del calendario gregoriano. 3

El año ISO consta de 52 o 53 semanas completas, y donde una semana comienza un lunes y termina un domingo. La primera semana de un año ISO es la primera semana calendario (gregoriana) de un año que contiene un jueves. Esto se llama semana número 1, y el año ISO de ese jueves es el mismo que el año gregoriano.

Por ejemplo, 2004 comienza en jueves, por lo que la primera semana del año ISO 2004 comienza el lunes 29 de diciembre de 2003 y termina el domingo 4 de enero de 2004

>>> from datetime import date
>>> date(2003, 12, 29).isocalendar()
datetime.IsoCalendarDate(year=2004, week=1, weekday=1)
>>> date(2004, 1, 4).isocalendar()
datetime.IsoCalendarDate(year=2004, week=1, weekday=7)

Distinto en la versión 3.9: El resultado cambió de una tupla a un named tuple.

date.isoformat()

Retorna una cadena de caracteres que representa la fecha en formato ISO 8601, AAAA-MM-DD:

>>> from datetime import date
>>> date(2002, 12, 4).isoformat()
'2002-12-04'

Este es el inverso de date.fromisoformat().

date.__str__()

Para una fecha d, str(d) es equivalente a d.isoformat().

date.ctime()

Retorna una cadena de caracteres que representa la fecha:

>>> from datetime import date
>>> date(2002, 12, 4).ctime()
'Wed Dec  4 00:00:00 2002'

d.ctime() es equivalente a:

time.ctime(time.mktime(d.timetuple()))

en plataformas donde la función nativa C ctime() (donde time.ctime() llama, pero que date.ctime() no se llama) se ajusta al estándar C.

date.strftime(format)

Retorna una cadena de caracteres que representa la fecha, controlada por una cadena de formato explícito. Los códigos de formato que se refieren a horas, minutos o segundos verán valores 0. Para obtener una lista completa de las directivas de formato, consulte Comportamiento strftime() y strptime().

date.__format__(format)

Igual que date.strftime(). Esto hace posible especificar una cadena de formato para un objeto date en literales de cadena con formato y cuando se usa str.format(). Para obtener una lista completa de las directivas de formato, consulte Comportamiento strftime() y strptime().

Ejemplos de uso: date

Ejemplo de contar días para un evento:

>>> import time
>>> from datetime import date
>>> today = date.today()
>>> today
datetime.date(2007, 12, 5)
>>> today == date.fromtimestamp(time.time())
True
>>> my_birthday = date(today.year, 6, 24)
>>> if my_birthday < today:
...     my_birthday = my_birthday.replace(year=today.year + 1)
>>> my_birthday
datetime.date(2008, 6, 24)
>>> time_to_birthday = abs(my_birthday - today)
>>> time_to_birthday.days
202

Más ejemplos de trabajo con date:

>>> from datetime import date
>>> d = date.fromordinal(730920) # 730920th day after 1. 1. 0001
>>> d
datetime.date(2002, 3, 11)

>>> # Methods related to formatting string output
>>> d.isoformat()
'2002-03-11'
>>> d.strftime("%d/%m/%y")
'11/03/02'
>>> d.strftime("%A %d. %B %Y")
'Monday 11. March 2002'
>>> d.ctime()
'Mon Mar 11 00:00:00 2002'
>>> 'The {1} is {0:%d}, the {2} is {0:%B}.'.format(d, "day", "month")
'The day is 11, the month is March.'

>>> # Methods for to extracting 'components' under different calendars
>>> t = d.timetuple()
>>> for i in t:
...     print(i)
2002                # year
3                   # month
11                  # day
0
0
0
0                   # weekday (0 = Monday)
70                  # 70th day in the year
-1
>>> ic = d.isocalendar()
>>> for i in ic:
...     print(i)
2002                # ISO year
11                  # ISO week number
1                   # ISO day number ( 1 = Monday )

>>> # A date object is immutable; all operations produce a new object
>>> d.replace(year=2005)
datetime.date(2005, 3, 11)

Objetos datetime

El objeto datetime es un único objeto que contiene toda la información de un objeto date y un objeto time.

Como un objeto date, datetime asume el calendario gregoriano actual extendido en ambas direcciones; como un objeto time, datetime supone que hay exactamente 3600*24 segundos en cada día.

Constructor:

class datetime.datetime(year, month, day, hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)

Se requieren los argumentos year, month y day. tzinfo puede ser None, o una instancia de una subclase tzinfo. Los argumentos restantes deben ser enteros en los siguientes rangos:

MINYEAR <= year <= MAXYEAR,

1 <= month <= 12,

1 <= day <= number of days in the given month and year,

0 <= hour < 24,

0 <= minute < 60,

0 <= second < 60,

0 <= microsecond < 1000000,

fold in [0, 1].

Si se proporciona un argumento fuera de esos rangos, ValueError se genera.

Nuevo en la versión 3.6: Se agregó el argumento fold.

Otros constructores, todos los métodos de clase:

classmethod datetime.today()

Retorna la fecha y hora local actual, con tzinfo None.

Equivalente a:

datetime.fromtimestamp(time.time())

Ver también now(), fromtimestamp().

Este método es funciona como now(), pero sin un parámetro tz.

classmethod datetime.now(tz=None)

Retorna la fecha y hora local actual.

Si el argumento opcional tz es None o no se especifica, es como today(), pero, si es posible, proporciona más precisión de la que se puede obtener al pasar por time.time() marca de tiempo (por ejemplo, esto puede ser posible en plataformas que suministran la función C gettimeofday()).

Si tz no es None, debe ser una instancia de una subclase tzinfo, y la fecha y hora actuales se convierten en la zona horaria de tz.

Esta función es preferible a today() y utcnow().

classmethod datetime.utcnow()

Retorna la fecha y hora UTC actual, con tzinfo None.

Esto es como now(), pero retorna la fecha y hora UTC actual, como un objeto naíf (naive): datetime. Se puede obtener una fecha y hora UTC actual consciente (aware) llamando a datetime.now (timezone.utc). Ver también now().

Advertencia

Debido a que los objetos naífs (naive) de datetime son tratados por muchos métodos de datetime como horas locales, se prefiere usar fechas y horas conscientes(aware) para representar las horas en UTC. Como tal, la forma recomendada de crear un objeto que represente la hora actual en UTC es llamando a datetime.now(timezone.utc).

classmethod datetime.fromtimestamp(timestamp, tz=None)

Retorna la fecha y hora local correspondiente a la marca de tiempo POSIX, tal como la retorna time.time(). Si el argumento opcional tz es None o no se especifica, la marca de tiempo se convierte a la fecha y hora local de la plataforma, y ​​el objeto retornado datetime es naíf (naive).

Si tz no es None, debe ser una instancia de una subclase tzinfo, y la fecha y hora actuales se convierten en la zona horaria de tz.

fromtimestamp() puede aumentar OverflowError, si la marca de tiempo está fuera del rango de valores admitidos por la plataforma C localtime() o gmtime(), y OSError en localtime() o gmtime() falla. Es común que esto se restrinja a los años 1970 a 2038. Tenga en cuenta que en los sistemas que no son POSIX que incluyen segundos bisiestos en su noción de marca de tiempo, los segundos bisiestos son ignorados por fromtimestamp(), y luego es posible tener dos marcas de tiempo que difieren en un segundo que producen objetos idénticos datetime. Se prefiere este método sobre utcfromtimestamp().

Distinto en la versión 3.3: Se genera OverflowError en lugar de ValueError si la marca de tiempo está fuera del rango de valores admitidos por la plataforma C localtime() o gmtime(). genera OSError en lugar de la función ValueError en localtime() o error gmtime().

Distinto en la versión 3.6: fromtimestamp() puede retornar instancias con fold establecido en 1.

classmethod datetime.utcfromtimestamp(timestamp)

Retorna el UTC datetime correspondiente a la marca de tiempo POSIX, con tzinfo None. (El objeto resultante es naíf (naive).)

Esto puede generar OverflowError, si la marca de tiempo está fuera del rango de valores admitidos por la plataforma C gmtime(), y error en OSError en gmtime(). Es común que esto se restrinja a los años entre1970 a 2038.

Para conocer un objeto datetime, llama a fromtimestamp():

datetime.fromtimestamp(timestamp, timezone.utc)

En las plataformas compatibles con POSIX, es equivalente a la siguiente expresión:

datetime(1970, 1, 1, tzinfo=timezone.utc) + timedelta(seconds=timestamp)

excepto que la última fórmula siempre admite el rango de años completo: entre MINYEAR y MAXYEAR inclusive.

Advertencia

Debido a que los objetos naíf (naive) de datetime son tratados por muchos métodos de datetime como horas locales, se prefiere usar fechas y horas conscientes para representar las horas en UTC. Como tal, la forma recomendada de crear un objeto que represente una marca de tiempo específica en UTC es llamando a datetime.fromtimestamp(timestamp, tz=timezone.utc).

Distinto en la versión 3.3: Se genera OverflowError en lugar de ValueError si la marca de tiempo está fuera del rango de valores admitidos por la plataforma C gmtime(). genera OSError en lugar de ValueError en el error de gmtime().

classmethod datetime.fromordinal(ordinal)

Se genera datetime correspondiente al ordinal del proléptico gregoriano, donde el 1 de enero del año 1 tiene ordinal 1. ValueError se genera a menos que 1 <= ordinal <= datetime.max.toordinal(). La hora, minuto, segundo y microsegundo del resultado son todos 0, y tzinfo es` None`.

classmethod datetime.combine(date, time, tzinfo=self.tzinfo)

Se genera un nuevo objeto datetime cuyos componentes de fecha son iguales a los dados en el objeto date, y cuyos componentes de tiempo son iguales a los dados en el objeto time. Si se proporciona el argumento tzinfo, su valor se usa para establecer el atributo tzinfo del resultado; de lo contrario, se usa el atributo tzinfo del argumento time.

Para cualquier objeto de datetime d, d == datetime.combine(d.date(), d.time(), d.tzinfo). Si la fecha es un objeto de datetime, se ignoran sus componentes de tiempo y tzinfo.

Distinto en la versión 3.6: Se agregó el argumento tzinfo.

classmethod datetime.fromisoformat(date_string)

Retorna datetime correspondiente a date_string en uno de los formatos emitidos por date.isoformat() y datetime.isoformat().

Específicamente, esta función admite cadenas de caracteres en el formato:

YYYY-MM-DD[*HH[:MM[:SS[.fff[fff]]]][+HH:MM[:SS[.ffffff]]]]

donde * puede coincidir con cualquier carácter individual.

Prudencia

Esto no admite el parsing de cadenas de caracteres arbitrarias ISO 8601; solo está pensado cómo la operación inversa de datetime.isoformat(). Un parseador ISO 8601 mas completo, dateutil.parser.isoparse está disponible en el paquete de terceros dateutil [https://dateutil.readthedocs.io/en/stable/parser.html#dateutil.parser.isoparse].

Ejemplos:

>>> from datetime import datetime
>>> datetime.fromisoformat('2011-11-04')
datetime.datetime(2011, 11, 4, 0, 0)
>>> datetime.fromisoformat('2011-11-04T00:05:23')
datetime.datetime(2011, 11, 4, 0, 5, 23)
>>> datetime.fromisoformat('2011-11-04 00:05:23.283')
datetime.datetime(2011, 11, 4, 0, 5, 23, 283000)
>>> datetime.fromisoformat('2011-11-04 00:05:23.283+00:00')
datetime.datetime(2011, 11, 4, 0, 5, 23, 283000, tzinfo=datetime.timezone.utc)
>>> datetime.fromisoformat('2011-11-04T00:05:23+04:00')
datetime.datetime(2011, 11, 4, 0, 5, 23,
    tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))

Nuevo en la versión 3.7.

classmethod datetime.fromisocalendar(year, week, day)

Retorna datetime correspondiente a la fecha del calendario ISO especificada por año, semana y día. Los componentes que no son de fecha de fecha y hora se rellenan con sus valores predeterminados normales. Esta es la inversa de la función datetime.isocalendar().

Nuevo en la versión 3.8.

classmethod datetime.strptime(date_string, format)

Retorna datetime correspondiente a date_string, analizado según format.

Esto es equivalente a:

datetime(*(time.strptime(date_string, format)[0:6]))

Se genera ValueError se genera si date_string y el formato no pueden ser analizados por time.strptime() o si retorna un valor que no es una tupla de tiempo. Para obtener una lista completa de las directivas de formato, consulte Comportamiento strftime() y strptime().

Atributos de clase:

datetime.min

La primera fecha representable datetime, datetime(MINYEAR, 1, 1, tzinfo=None).

datetime.max

La última fecha representable datetime, datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999, tzinfo=None).

datetime.resolution

La diferencia más pequeña posible entre objetos no iguales datetime, timedelta(microseconds=1).

Atributos de instancia (solo lectura):

datetime.year

Entre MINYEAR y MAXYEAR inclusive.

datetime.month

Entre 1 y 12 inclusive.

datetime.day

Entre 1 y el número de días en el mes dado del año dado.

datetime.hour

En range(24).

datetime.minute

En range(60).

datetime.second

En range(60).

datetime.microsecond

En range(1000000).

datetime.tzinfo

El objeto pasó como argumento tzinfo al constructor datetime, o None si no se pasó ninguno.

datetime.fold

En [0, 1]. Se usa para desambiguar los tiempos de pared durante un intervalo repetido. (Se produce un intervalo repetido cuando los relojes se retrotraen al final del horario de verano o cuando el desplazamiento UTC para la zona actual se reduce por razones políticas). El valor 0 (1) representa el anterior (posterior) de los dos momentos con la misma representación de tiempo real transcurrido (wall time).

Nuevo en la versión 3.6.

Operaciones soportadas:

Operación

Resultado

datetime2 = datetime1 + timedelta

(1)

datetime2 = datetime1 - timedelta

(2)

timedelta = datetime1 - datetime2

(3)

datetime1 < datetime2

Compara datetime to datetime. (4)

datetime2 es una duración de timedelta eliminada de datetime1, avanzando en el tiempo si timedelta.days> 0, o hacia atrás si timedelta.days < 0. El resultado tiene el mismo tzinfo como el atributo datetime y datetime2 - datetime1 == timedelta . OverflowError se genera si datetime2.year sería menor que MINYEAR o mayor que MAXYEAR. Tenga en cuenta que no se realizan ajustes de zona horaria, incluso si la entrada es un objeto consciente.

Calcula el datetime tal que datetime2 + timedelta == datetime1. En cuanto a la adición, el resultado tiene el mismo atributo tzinfo que la fecha y hora de entrada, y no se realizan ajustes de zona horaria, incluso si la entrada es consciente.

La resta de datetime de la datetime se define solo si ambos operandos son naíf(naive), o si ambos son conscientes(aware). Si uno es consciente y el otro es naíf, TypeError aparece.

Si ambos son naíf (naive), o ambos son conscientes (aware) y tienen el mismo atributo tzinfo, los atributos tzinfo se ignoran y el resultado es un objeto de timedelta ` *t* tal que ``datetime2 + t == datetime1`. No se realizan ajustes de zona horaria en este caso.

Si ambos son conscientes (aware) y tienen atributos diferentes tzinfo,` a-b` actúa como si primero a y b se convirtieran primero en fechas naíf (naive) UTC. El resultado es (a.replace(tzinfo = None) - a.utcoffset()) - (b.replace (tzinfo = None) - b.utcoffset()) excepto que la implementación nunca se desborda.

datetime1 se considera menor que datetime2 cuando datetime1 precede datetime2 en el tiempo.

Si un de los elementos comparados es naíf (naive) y el otro lo sabe, se genera un TypeError si se intenta una comparación de órdenes. Para las comparaciones de igualdad, las instancias naíf nunca son iguales a las instancias conscientes (aware).

Si ambos comparados son conscientes (aware) y tienen el mismo atributo tzinfo, el atributo común tzinfo se ignora y se comparan las fechas base. Si ambos elementos comparados son conscientes y tienen atributos diferentes tzinfo, los elementos comparados se ajustan primero restando sus compensaciones UTC (obtenidas de self.utcoffset()).

Distinto en la versión 3.3: Las comparaciones de igualdad entre las instancias conscientes (aware) y naíf (naive) datetime no generan TypeError.

Nota

Para evitar que la comparación vuelva al esquema predeterminado de comparación de direcciones de objetos, la comparación de fecha y hora normalmente genera TypeError si el otro elemento comparado no es también un objeto datetime. Sin embargo, NotImplemented se retorna si el otro elemento comparado tiene un atributo timetuple() . Este enlace ofrece a otros tipos de objetos de fecha la posibilidad de implementar una comparación de tipos mixtos. Si no, cuándo un objeto datetime se compara con un objeto de un tipo diferente, se genera TypeError a menos que la comparación sea == o !=. Los últimos casos retornan False o True, respectivamente.

Métodos de instancia:

datetime.date()

Retorna el objeto date con el mismo año, mes y día.

datetime.time()

Retorna el objeto time con la misma hora, minuto, segundo, microsegundo y doblado(fold). tzinfo es None. Ver también método timetz().

Distinto en la versión 3.6: El valor de plegado (fold value) se copia en el objeto time retornado.

datetime.timetz()

Retorna el objeto time con los mismos atributos de hora, minuto, segundo, microsegundo, pliegue y tzinfo. Ver también método time().

Distinto en la versión 3.6: El valor de plegado (fold value) se copia en el objeto time retornado.

datetime.replace(year=self.year, month=self.month, day=self.day, hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=0)

Retorna una fecha y hora con los mismos atributos, a excepción de aquellos atributos a los que se les asignan nuevos valores según los argumentos de palabras clave especificados. Tenga en cuenta que tzinfo = None se puede especificar para crear una fecha y hora naíf (naive) a partir de una fecha y hora consciente(aware) sin conversión de datos de fecha y hora.

Nuevo en la versión 3.6: Se agregó el argumento fold.

datetime.astimezone(tz=None)

Retorna un objeto datetime con el atributo nuevo tzinfo tz, ajustando los datos de fecha y hora para que el resultado sea la misma hora UTC que self, pero en hora local tz.

Si se proporciona, tz debe ser una instancia de una subclase tzinfo, y sus métodos utcoffset() y dst`no deben retornar ``None`().Si self es naíf, se supone que representa la hora en la zona horaria del sistema.

Si se llama sin argumentos (o con tz=None), se asume la zona horaria local del sistema para la zona horaria objetivo. El atributo .tzinfo de la instancia de fecha y hora convertida se establecerá en una instancia de timezone con el nombre de zona y el desplazamiento obtenido del sistema operativo.

Si self.tzinfo es tz, self.astimezone (tz) es igual a self: no se realiza ningún ajuste de datos de fecha u hora. De lo contrario, el resultado es la hora local en la zona horaria tz, que representa la misma hora UTC que self: después de astz = dt.astimezone (tz), astz - astz.utcoffset() tendrá los mismos datos de fecha y hora que dt - dt.utcoffset().

Si simplemente desea adjuntar un objeto de zona horaria tz a una fecha y hora dt sin ajustar los datos de fecha y hora, use dt.replace (tzinfo = tz). Si simplemente desea eliminar el objeto de zona horaria de una fecha y hora dt sin conversión de datos de fecha y hora, use dt.replace (tzinfo = None).

Tenga en cuenta que el método predeterminado tzinfo.fromutc() se puede reemplazar en una subclase tzinfo para afectar el resultado retornado por astimezone(). astimezone() ignora los casos de error, actúa como:

def astimezone(self, tz):
    if self.tzinfo is tz:
        return self
    # Convert self to UTC, and attach the new time zone object.
    utc = (self - self.utcoffset()).replace(tzinfo=tz)
    # Convert from UTC to tz's local time.
    return tz.fromutc(utc)

Distinto en la versión 3.3: tz ahora puede ser omitido.

Distinto en la versión 3.6: El método astimezone() ahora se puede invocar en instancias naíf (naive) que se supone representan la hora local del sistema.

datetime.utcoffset()

Si tzinfo es None, retorna None, de lo contrario retorna self.tzinfo.utcoffset (self)` `, y genera una excepción si este último no retorna ``None o un objeto timedelta con magnitud inferior a un día.

Distinto en la versión 3.7: El desfase UTC no está restringido a un número entero de minutos.

datetime.dst()

Si tzinfo es None, retorna None, de lo contrario retorna self.tzinfo.utcoffset (self), y genera una excepción si este último no retorna None o un objeto timedelta con magnitud inferior a un día.

Distinto en la versión 3.7: El desfase DST no está restringido a un número entero de minutos.

datetime.tzname()

Si tzinfo es None, retorna None, de lo contrario retorna self.tzinfo.tzname(self), genera una excepción si este último no retorna None o un objeto de cadena de caracteres,

datetime.timetuple()

Retorna una time.struct_time como la que retorna time.localtime().

d.timetuple() es equivalente a:

time.struct_time((d.year, d.month, d.day,
                  d.hour, d.minute, d.second,
                  d.weekday(), yday, dst))

donde yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1 es el número de día dentro del año actual que comienza con 1 para el 1 de enero. El indicador tm_isdst del resultado se establece de acuerdo con el método dst(): tzinfo es None o dst() retorna None, tm_isdst se establece en -1; si no dst() retorna un valor distinto de cero, tm_isdst se establece en 1; de lo contrario tm_isdst se establece en 0.

datetime.utctimetuple()

Si datetime instancia d es naíf (naive), esto es lo mismo que d.timetuple() excepto que tm_isdst se fuerza a 0 independientemente de lo que retorna d.dst( ). El horario de verano nunca está en vigencia durante un horario UTC.

Si d es consciente (aware), d se normaliza a la hora UTC, restando d.utcoffset(), y se retorna time.struct_time para la hora normalizada. tm_isdst se fuerza a 0. Tenga en cuenta que un OverflowError puede aparecer si d*.year fue MINYEAR o MAXYEAR y el ajuste UTC se derrama durante el límite de un año.

Advertencia

Debido a que los objetos naíf (naive) de datetime son tratados por muchos métodos de datetime como horas locales, se prefiere usar fechas y horas conscientes (aware) para representar las horas en UTC; como resultado, el uso de utcfromtimetuple puede dar resultados engañosos. Si tiene una datetime naíf que representa UTC, use datetime.replace(tzinfo=timezone.utc) para que sea consciente, en cuyo punto se puede usar datetime.timetuple().

datetime.toordinal()

Retorna el ordinal gregoriano proléptico de la fecha. Lo mismo que self.date().toordinal().

datetime.timestamp()

Retorna la marca de tiempo (timestamp) POSIX correspondiente a la instancia datetime. El valor de retorno es float similar al retornado por time.time().

Se supone que las instancias Naíf datetime representan la hora local y este método se basa en la función de plataforma C mktime() para realizar la conversión. Dado que datetime admite un rango de valores más amplio que mktime() en muchas plataformas, este método puede lanzar OverflowError para tiempos lejanos en el pasado o en el futuro.

Para las instancias de datetime, el valor de retorno se calcula como:

(dt - datetime(1970, 1, 1, tzinfo=timezone.utc)).total_seconds()

Nuevo en la versión 3.3.

Distinto en la versión 3.6: El método timestamp() utiliza el atributo fold para desambiguar los tiempos durante un intervalo repetido.

Nota

No hay ningún método para obtener la marca de tiempo (timestamp) POSIX directamente de una instancia naíf datetime que representa la hora UTC. Si su aplicación utiliza esta convención y la zona horaria de su sistema no está configurada en UTC, puede obtener la marca de tiempo POSIX al proporcionar tzinfo = timezone.utc:

timestamp = dt.replace(tzinfo=timezone.utc).timestamp()

o calculando la marca de tiempo (timestamp) directamente:

timestamp = (dt - datetime(1970, 1, 1)) / timedelta(seconds=1)

datetime.weekday()

Retorna el día de la semana como un entero, donde el lunes es 0 y el domingo es 6. Lo mismo que self.date().weekday(). Ver también isoweekday().

datetime.isoweekday()

Retorna el día de la semana como un número entero, donde el lunes es 1 y el domingo es 7. Lo mismo que self.date().isoweekday(). Ver también weekday(), isocalendar().

datetime.isocalendar()

Retorna una named tuple con tres componentes: year, week, y weekday. Lo mismo que self.date().isocalendar().

datetime.isoformat(sep='T', timespec='auto')

Retorna una cadena de caracteres representando la fecha y la hora en formato ISO 8601:

YYYY-MM-DDTHH:MM:SS.ffffff, si microsecond no es 0

YYYY-MM-DDTHH:MM:SS, si microsecond es 0

Si utcoffset() no retorna None, se agrega una cadena de caracteres dando el desplazamiento UTC:

YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]], si microsecond no es 0

YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]], si microsecond es 0

Ejemplos:

>>> from datetime import datetime, timezone
>>> datetime(2019, 5, 18, 15, 17, 8, 132263).isoformat()
'2019-05-18T15:17:08.132263'
>>> datetime(2019, 5, 18, 15, 17, tzinfo=timezone.utc).isoformat()
'2019-05-18T15:17:00+00:00'

El argumento opcional sep (default ’T’) es un separador de un carácter, ubicado entre las porciones de fecha y hora del resultado. Por ejemplo:

>>> from datetime import tzinfo, timedelta, datetime
>>> class TZ(tzinfo):
...     """A time zone with an arbitrary, constant -06:39 offset."""
...     def utcoffset(self, dt):
...         return timedelta(hours=-6, minutes=-39)
...
>>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
'2002-12-25 00:00:00-06:39'
>>> datetime(2009, 11, 27, microsecond=100, tzinfo=TZ()).isoformat()
'2009-11-27T00:00:00.000100-06:39'

El argumento opcional timespec especifica el número de componentes adicionales del tiempo a incluir (el valor predeterminado es ‘auto’). Puede ser uno de los siguientes:

’auto’: Igual que ’seconds’ si microsecond es 0, igual que ’microseconds’ de lo contrario.

’hours’: incluye el hour en el formato de dos dígitos HH.

’minutes’: Incluye hour y minute en formato``HH:MM``.

’seconds’: Incluye hour, minute, y second en formato HH:MM:SS.

’milliseconds’: Incluye tiempo completo, pero trunca la segunda parte fraccionaria a milisegundos. Formato HH:MM:SS.sss.

’microseconds’: Incluye tiempo completo en formato``HH:MM:SS.ffffff``.

Nota

Los componentes de tiempo excluidos están truncados, no redondeados.

ValueError generará un argumento inválido timespec:

>>> from datetime import datetime
>>> datetime.now().isoformat(timespec='minutes')
'2002-12-25T00:00'
>>> dt = datetime(2015, 1, 1, 12, 30, 59, 0)
>>> dt.isoformat(timespec='microseconds')
'2015-01-01T12:30:59.000000'

Nuevo en la versión 3.6: Se agregó el argumento timespec.

datetime.__str__()

Para una instancia de la datetime d, str(d) es equivalente a d.isoformat(' ').

datetime.ctime()

Retorna una cadena de caracteres que representa la fecha y la hora:

>>> from datetime import datetime
>>> datetime(2002, 12, 4, 20, 30, 40).ctime()
'Wed Dec  4 20:30:40 2002'

La cadena de salida no incluirá información de zona horaria, independientemente de si la entrada es consciente (aware) o naíf (naive).

d.ctime() es equivalente a:

time.ctime(time.mktime(d.timetuple()))

en plataformas donde la función nativa C ctime() (que time.ctime() invoca, pero que datetime.ctime() no invoca) se ajusta al estándar C.

datetime.strftime(format)

Retorna una cadena de caracteres que representa la fecha y la hora, controlada por una cadena de formato explícito. Para obtener una lista completa de las directivas de formato, consulte Comportamiento strftime() y strptime().

datetime.__format__(format)

Igual que date.strftime(). Esto hace posible especificar una cadena de formato para un objeto date en literales de cadena con formato y cuando se usa str.format(). Para obtener una lista completa de las directivas de formato, consulte Comportamiento strftime() y strptime().

Ejemplos de uso: datetime

Ejemplos de trabajo con objetos datetime:

>>> from datetime import datetime, date, time, timezone

>>> # Using datetime.combine()
>>> d = date(2005, 7, 14)
>>> t = time(12, 30)
>>> datetime.combine(d, t)
datetime.datetime(2005, 7, 14, 12, 30)

>>> # Using datetime.now()
>>> datetime.now()
datetime.datetime(2007, 12, 6, 16, 29, 43, 79043)   # GMT +1
>>> datetime.now(timezone.utc)
datetime.datetime(2007, 12, 6, 15, 29, 43, 79060, tzinfo=datetime.timezone.utc)

>>> # Using datetime.strptime()
>>> dt = datetime.strptime("21/11/06 16:30", "%d/%m/%y %H:%M")
>>> dt
datetime.datetime(2006, 11, 21, 16, 30)

>>> # Using datetime.timetuple() to get tuple of all attributes
>>> tt = dt.timetuple()
>>> for it in tt:
...     print(it)
...
2006    # year
11      # month
21      # day
16      # hour
30      # minute
0       # second
1       # weekday (0 = Monday)
325     # number of days since 1st January
-1      # dst - method tzinfo.dst() returned None

>>> # Date in ISO format
>>> ic = dt.isocalendar()
>>> for it in ic:
...     print(it)
...
2006    # ISO year
47      # ISO week
2       # ISO weekday

>>> # Formatting a datetime
>>> dt.strftime("%A, %d. %B %Y %I:%M%p")
'Tuesday, 21. November 2006 04:30PM'
>>> 'The {1} is {0:%d}, the {2} is {0:%B}, the {3} is {0:%I:%M%p}.'.format(dt, "day", "month", "time")
'The day is 21, the month is November, the time is 04:30PM.'

El siguiente ejemplo define una subclase tzinfo que captura la información de zona horaria de Kabul, Afganistán, que utilizó +4 UTC hasta 1945 y +4:30 UTC a partir de entonces:

from datetime import timedelta, datetime, tzinfo, timezone

class KabulTz(tzinfo):
    # Kabul used +4 until 1945, when they moved to +4:30
    UTC_MOVE_DATE = datetime(1944, 12, 31, 20, tzinfo=timezone.utc)

    def utcoffset(self, dt):
        if dt.year < 1945:
            return timedelta(hours=4)
        elif (1945, 1, 1, 0, 0) <= dt.timetuple()[:5] < (1945, 1, 1, 0, 30):
            # An ambiguous ("imaginary") half-hour range representing
            # a 'fold' in time due to the shift from +4 to +4:30.
            # If dt falls in the imaginary range, use fold to decide how
            # to resolve. See PEP495.
            return timedelta(hours=4, minutes=(30 if dt.fold else 0))
        else:
            return timedelta(hours=4, minutes=30)

    def fromutc(self, dt):
        # Follow same validations as in datetime.tzinfo
        if not isinstance(dt, datetime):
            raise TypeError("fromutc() requires a datetime argument")
        if dt.tzinfo is not self:
            raise ValueError("dt.tzinfo is not self")

        # A custom implementation is required for fromutc as
        # the input to this function is a datetime with utc values
        # but with a tzinfo set to self.
        # See datetime.astimezone or fromtimestamp.
        if dt.replace(tzinfo=timezone.utc) >= self.UTC_MOVE_DATE:
            return dt + timedelta(hours=4, minutes=30)
        else:
            return dt + timedelta(hours=4)

    def dst(self, dt):
        # Kabul does not observe daylight saving time.
        return timedelta(0)

    def tzname(self, dt):
        if dt >= self.UTC_MOVE_DATE:
            return "+04:30"
        return "+04"

Uso de KabulTz desde arriba

>>> tz1 = KabulTz()

>>> # Datetime before the change
>>> dt1 = datetime(1900, 11, 21, 16, 30, tzinfo=tz1)
>>> print(dt1.utcoffset())
4:00:00

>>> # Datetime after the change
>>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=tz1)
>>> print(dt2.utcoffset())
4:30:00

>>> # Convert datetime to another time zone
>>> dt3 = dt2.astimezone(timezone.utc)
>>> dt3
datetime.datetime(2006, 6, 14, 8, 30, tzinfo=datetime.timezone.utc)
>>> dt2
datetime.datetime(2006, 6, 14, 13, 0, tzinfo=KabulTz())
>>> dt2 == dt3
True

Objetos time

Un objeto time representa a una hora del día (local), independiente de cualquier día en particular, y está sujeto a ajustes a través de un objeto tzinfo.

class datetime.time(hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)

Todos los argumentos son opcionales. tzinfo puede ser None, o una instancia de una subclase tzinfo. Los argumentos restantes deben ser enteros en los siguientes rangos:

0 <= hour < 24,

0 <= minute < 60,

0 <= second < 60,

0 <= microsecond < 1000000,

fold in [0, 1].

Si se proporciona un argumento fuera de esos rangos, se genera ValueError. Todo predeterminado a 0 excepto tzinfo, que por defecto es None.

Atributos de clase:

time.min

El primero representable time,``time (0, 0, 0, 0)``.

time.max

El último representable time, time(23, 59, 59, 999999).

time.resolution

La diferencia más pequeña posible entre los objetos no iguales time, timedelta(microseconds=1), aunque tenga en cuenta que la aritmética en objetos time no es compatible.

Atributos de instancia (solo lectura):

time.hour

En range(24).

time.minute

En range(60).

time.second

En range(60).

time.microsecond

En range(1000000).

time.tzinfo

El objeto pasado como argumento tzinfo al constructor de la clase time , o None si no se pasó ninguno.

time.fold

En [0, 1]. Se usa para desambiguar los tiempos de pared durante un intervalo repetido. (Se produce un intervalo repetido cuando los relojes se retrotraen al final del horario de verano o cuando el desplazamiento UTC para la zona actual se reduce por razones políticas). El valor 0 (1) representa el anterior (posterior) de los dos momentos con la misma representación de tiempo real transcurrido (wall time).

Nuevo en la versión 3.6.

Los objetos time admiten la comparación de time con time, donde a se considera menor que b cuando a precede a b en el tiempo. Si un elemento comparado es naíf (naive) y el otro lo sabe se genera TypeError si se intenta una comparación de orden. Para las comparaciones de igualdad, las instancias naíf nunca son iguales a las instancias conscientes (aware).

Si ambos elementos comparados son conscientes (aware) y tienen el mismo atributo tzinfo, el atributo común tzinfo se ignora y se comparan los tiempos base. Si ambos elementos comparados son conscientes y tienen atributos diferentes tzinfo, los elementos comparados se ajustan primero restando sus compensaciones UTC (obtenidas de self.utcoffset()). Para evitar que las comparaciones de tipos mixtos vuelvan a la comparación predeterminada por dirección de objeto, cuando un objeto time se compara con un objeto de un tipo diferente, se genera TypeError a menos que la comparación es == o !=. Los últimos casos retornan False o True, respectivamente.

Distinto en la versión 3.3: Las comparaciones de igualdad entre las instancias conscientes (aware) y naífs (naive) time no generan TypeError.

En contextos booleanos, un objeto time siempre se considera verdadero.

Distinto en la versión 3.5: Antes de Python 3.5, un objeto time se consideraba falso si representaba la medianoche en UTC. Este comportamiento se consideró oscuro y propenso a errores y se ha eliminado en Python 3.5. Ver bpo-13936 [https://bugs.python.org/issue?@action=redirect&bpo=13936] para más detalles.

Otro constructor:

classmethod time.fromisoformat(time_string)

Retorna una time correspondiente a time_string en uno de los formatos emitidos por time.isoformat(). Específicamente, esta función admite cadenas de caracteres en el formato:

HH[:MM[:SS[.fff[fff]]]][+HH:MM[:SS[.ffffff]]]

Prudencia

Esto no admite el parsing de cadenas arbitrarias ISO 8601. Solo pretende ser la operación inversa de time.isoformat().

Ejemplos:

>>> from datetime import time
>>> time.fromisoformat('04:23:01')
datetime.time(4, 23, 1)
>>> time.fromisoformat('04:23:01.000384')
datetime.time(4, 23, 1, 384)
>>> time.fromisoformat('04:23:01+04:00')
datetime.time(4, 23, 1, tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))

Nuevo en la versión 3.7.

Métodos de instancia:

time.replace(hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=0)

Retorna una time con el mismo valor, excepto para aquellos atributos a los que se les otorgan nuevos valores según los argumentos de palabras clave especificados. Tenga en cuenta que tzinfo = None se puede especificar para crear una time naíf (naive) desde un consciente (aware) time, sin conversión de los datos de tiempo.

Nuevo en la versión 3.6: Se agregó el argumento fold.

time.isoformat(timespec='auto')

Retorna una cadena que representa la hora en formato ISO 8601, una de:

HH:MM:SS.ffffff, si microsecond no es 0

HH:MM:SS, si microsecond es 0

HH:MM:SS.ffffff+HH:MM[:SS[.ffffff]], si utcoffset() no retorna None

HH:MM:SS+HH:MM[:SS[.ffffff]], si microsecond es 0 y utcoffset() no retorna None

El argumento opcional timespec especifica el número de componentes adicionales del tiempo a incluir (el valor predeterminado es ‘auto’). Puede ser uno de los siguientes:

’auto’: Igual que ’seconds’ si microsecond es 0, igual que ’microseconds’ de lo contrario.

’hours’: incluye el hour en el formato de dos dígitos HH.

’minutes’: Incluye hour y minute en formato``HH:MM``.

’seconds’: Incluye hour, minute, y second en formato HH:MM:SS.

’milliseconds’: Incluye tiempo completo, pero trunca la segunda parte fraccionaria a milisegundos. Formato HH:MM:SS.sss.

’microseconds’: Incluye tiempo completo en formato``HH:MM:SS.ffffff``.

Nota

Los componentes de tiempo excluidos están truncados, no redondeados.

ValueError generará un argumento inválido timespec.

Ejemplo:

>>> from datetime import time
>>> time(hour=12, minute=34, second=56, microsecond=123456).isoformat(timespec='minutes')
'12:34'
>>> dt = time(hour=12, minute=34, second=56, microsecond=0)
>>> dt.isoformat(timespec='microseconds')
'12:34:56.000000'
>>> dt.isoformat(timespec='auto')
'12:34:56'

Nuevo en la versión 3.6: Se agregó el argumento timespec.

time.__str__()

Durante un tiempo t, str(t) es equivalente a t.isoformat().

time.strftime(format)

Retorna una cadena que representa la hora, controlada por una cadena de formato explícito. Para obtener una lista completa de las directivas de formato, consulte Comportamiento strftime() y strptime().

time.__format__(format)

Igual que time.strftime(). Esto permite especificar una cadena de formato para un objeto time en cadenas de caracteres literales con formato y cuando se usa str.format(). Para obtener una lista completa de las directivas de formato, consulte Comportamiento strftime() y strptime().

time.utcoffset()

Si tzinfo es None, retorna None, sino retorna self.tzinfo.utcoffset(None), y genera una excepción si este último no retorna None o un objeto de timedelta con magnitud inferior a un día.

Distinto en la versión 3.7: El desfase UTC no está restringido a un número entero de minutos.

time.dst()

Si tzinfo es None, retorna None, sino retorna self.tzinfo.utcoffset(None), y genera una excepción si este último no retorna None, o un objeto de timedelta con magnitud inferior a un día.

Distinto en la versión 3.7: El desfase DST no está restringido a un número entero de minutos.

time.tzname()

Si tzinfo es None, retorna None, sino retorna self.tzinfo.tzname(None), o genera una excepción si este último no retorna None o un objeto de cadena.

Ejemplos de uso: time

Ejemplos de trabajo con el objeto time:

>>> from datetime import time, tzinfo, timedelta
>>> class TZ1(tzinfo):
...     def utcoffset(self, dt):
...         return timedelta(hours=1)
...     def dst(self, dt):
...         return timedelta(0)
...     def tzname(self,dt):
...         return "+01:00"
...     def  __repr__(self):
...         return f"{self.__class__.__name__}()"
...
>>> t = time(12, 10, 30, tzinfo=TZ1())
>>> t
datetime.time(12, 10, 30, tzinfo=TZ1())
>>> t.isoformat()
'12:10:30+01:00'
>>> t.dst()
datetime.timedelta(0)
>>> t.tzname()
'+01:00'
>>> t.strftime("%H:%M:%S %Z")
'12:10:30 +01:00'
>>> 'The {} is {:%H:%M}.'.format("time", t)
'The time is 12:10.'

Objetos tzinfo

class datetime.tzinfo

Esta es una clase base abstracta, lo que significa que esta clase no debe ser instanciada directamente. Defina una subclase de tzinfo para capturar información sobre una zona horaria particular.

Una instancia (de una subclase concreta) tzinfo se puede pasar a los constructores para objetos de datetime y time. Los últimos objetos ven sus atributos como en la hora local, y el objeto tzinfo admite métodos que revelan el desplazamiento de la hora local desde UTC, el nombre de la zona horaria y el desplazamiento DST, todo en relación con un objeto de fecha u hora pasó a ellos.

Debe derivar una subclase concreta y (al menos) proporcionar implementaciones de los métodos estándar tzinfo que necesitan los métodos datetime que utiliza. El módulo datetime proporciona timezone, una subclase concreta simple de tzinfo que puede representar zonas horarias con desplazamiento fijo desde UTC como UTC o Norte América EST y EDT.

Requisito especial para el pickling: La subclase tzinfo debe tener un método __init__() que se pueda invocar sin argumentos; de lo contrario, se puede hacer pickling pero posiblemente no se vuelva a despegar. Este es un requisito técnico que puede ser relajado en el futuro.

Una subclase concreta de tzinfo puede necesitar implementar los siguientes métodos. Exactamente qué métodos son necesarios depende de los usos de los objetos conscientes(aware) datetime. En caso de duda, simplemente implemente todos ellos.

tzinfo.utcoffset(dt)

Retorna el desplazamiento de la hora local desde UTC, como un objeto timedelta que es positivo al este de UTC. Si la hora local es al oeste de UTC, esto debería ser negativo.

Esto representa el desplazamiento total de UTC; por ejemplo, si un objeto tzinfo representa ajustes de zona horaria y DST, utcoffset() debería retornar su suma. Si no se conoce el desplazamiento UTC, retorna None . De lo contrario, el valor detonado debe ser un objeto de timedelta estrictamente entre -timedelta(hours = 24) y timedelta (hours = 24) (la magnitud del desplazamiento debe ser inferior a un día) La mayoría de las implementaciones de utcoffset() probablemente se parecerán a una de estas dos:

return CONSTANT                 # fixed-offset class
return CONSTANT + self.dst(dt)  # daylight-aware class

Si utcoffset() no retorna None, dst() no debería retornar None tampoco.

La implementación por defecto de utcoffset() genera NotImplementedError.

Distinto en la versión 3.7: El desfase UTC no está restringido a un número entero de minutos.

tzinfo.dst(dt)

Retorna el ajuste del horario de verano (DST), como un objeto de timedelta o None si no se conoce la información de DST.

Retorna timedelta(0) si el horario de verano no está en vigor. Si DST está en vigor, retorna el desplazamiento como un objeto timedelta (consulte utcoffset() para más detalles). Tenga en cuenta que el desplazamiento DST, si corresponde, ya se ha agregado al desplazamiento UTC retornado por utcoffset(), por lo que no es necesario consultar dst() a menos que esté interesado en obtener información DST por separado. Por ejemplo, datetime.timetuple() llama a su tzinfo del atributo dst() para determinar cómo se debe establecer el indicador tm_isdst, y tzinfo.fromutc() llama dst() para tener en cuenta los cambios de horario de verano al cruzar zonas horarias.

Una instancia tz de una subclase tzinfo que modela los horarios estándar y diurnos debe ser coherente en este sentido:

tz.utcoffset(dt) - tz.dst(dt)

debe retornar el mismo resultado para cada datetime dt con dt.tzinfo == tz Para las subclases sanas tzinfo, esta expresión produce el «desplazamiento estándar» de la zona horaria, que no debe depender de la fecha o la hora, sino solo de la ubicación geográfica. La implementación de datetime.astimezone() se basa en esto, pero no puede detectar violaciones; es responsabilidad del programador asegurarlo. Si una subclase tzinfo no puede garantizar esto, puede anular la implementación predeterminada de tzinfo.fromutc() para que funcione correctamente con astimezone() independientemente.

La mayoría de las implementaciones de dst() probablemente se parecerán a una de estas dos:

def dst(self, dt):
    # a fixed-offset class:  doesn't account for DST
    return timedelta(0)

o:

def dst(self, dt):
    # Code to set dston and dstoff to the time zone's DST
    # transition times based on the input dt.year, and expressed
    # in standard local time.

    if dston <= dt.replace(tzinfo=None) < dstoff:
        return timedelta(hours=1)
    else:
        return timedelta(0)

La implementación predeterminada de dst() genera NotImplementedError.

Distinto en la versión 3.7: El desfase DST no está restringido a un número entero de minutos.

tzinfo.tzname(dt)

Retorna el nombre de zona horaria correspondiente al objeto datetime dt, como una cadena de caracteres. El módulo datetime no define nada sobre los nombres de cadena, y no hay ningún requisito de que signifique algo en particular. Por ejemplo,*»GMT», «UTC», «-500», «-5:00», «EDT», «US/Eastern», *»America/New York» son todas respuestas válidas. Retorna None si no se conoce un nombre de cadena. Tenga en cuenta que este es un método en lugar de una cadena fija principalmente porque algunas subclases tzinfo desearán retornar diferentes nombres dependiendo del valor específico de dt pasado, especialmente si la clase tzinfo es contable para el horario de verano.

La implementación predeterminada de tzname() genera NotImplementedError.

Estos métodos son llamados por un objeto datetime o time, en respuesta a sus métodos con los mismos nombres. El objeto de datetime se pasa a sí mismo como argumento, y un objeto time pasa a None como argumento. Los métodos de la subclase tzinfo deben, por lo tanto, estar preparados para aceptar un argumento dt de None, o de clase datetime.

Cuando se pasa None, corresponde al diseñador de la clase decidir la mejor respuesta. Por ejemplo, retornar None es apropiado si la clase desea decir que los objetos de tiempo no participan en los protocolos tzinfo. Puede ser más útil que utcoffset(None) retorne el desplazamiento UTC estándar, ya que no existe otra convención para descubrir el desplazamiento estándar.

Cuando se pasa un objeto datetime en respuesta a un método datetime, dt.tzinfo es el mismo objeto que self. tzinfo los métodos pueden confiar en esto, a menos que el código del usuario llame tzinfo métodos directamente. La intención es que los métodos tzinfo interpreten dt como si estuvieran en la hora local, y no necesiten preocuparse por los objetos en otras zonas horarias.

Hay un método más tzinfo que una subclase puede desear anular:

tzinfo.fromutc(dt)

Esto se llama desde la implementación predeterminada datetime.astimezone(). Cuando se llama desde eso, dt.tzinfo es self , y los datos de fecha y hora de dt deben considerarse como una hora UTC. El propósito de fromutc() es ajustar los datos de fecha y hora, retornando una fecha y hora equivalente en la hora local de self.

La mayoría de las subclases tzinfo deberían poder heredar la implementación predeterminada fromutc() sin problemas. Es lo suficientemente fuerte como para manejar zonas horarias de desplazamiento fijo y zonas horarias que representan tanto el horario estándar como el horario de verano, y esto último incluso si los tiempos de transición DST difieren en años diferentes. Un ejemplo de una zona horaria predeterminada fromutc(), la implementación puede que no se maneje correctamente en todos los casos es aquella en la que el desplazamiento estándar (desde UTC) depende de la fecha y hora específicas que pasan, lo que puede suceder por razones políticas. Las implementaciones predeterminadas de astimezone() y fromutc() pueden no producir el resultado que desea si el resultado es una de las horas a horcajadas en el momento en que cambia el desplazamiento estándar.

Código de omisión para casos de error, el valor predeterminado fromutc() la implementación actúa como

def fromutc(self, dt):
    # raise ValueError error if dt.tzinfo is not self
    dtoff = dt.utcoffset()
    dtdst = dt.dst()
    # raise ValueError if dtoff is None or dtdst is None
    delta = dtoff - dtdst  # this is self's standard offset
    if delta:
        dt += delta   # convert to standard local time
        dtdst = dt.dst()
        # raise ValueError if dtdst is None
    if dtdst:
        return dt + dtdst
    else:
        return dt

En el siguiente archivo tzinfo_examples.py hay algunos ejemplos de clases tzinfo:

from datetime import tzinfo, timedelta, datetime

ZERO = timedelta(0)
HOUR = timedelta(hours=1)
SECOND = timedelta(seconds=1)

# A class capturing the platform's idea of local time.
# (May result in wrong values on historical times in
#  timezones where UTC offset and/or the DST rules had
#  changed in the past.)
import time as _time

STDOFFSET = timedelta(seconds = -_time.timezone)
if _time.daylight:
    DSTOFFSET = timedelta(seconds = -_time.altzone)
else:
    DSTOFFSET = STDOFFSET

DSTDIFF = DSTOFFSET - STDOFFSET

class LocalTimezone(tzinfo):

    def fromutc(self, dt):
        assert dt.tzinfo is self
        stamp = (dt - datetime(1970, 1, 1, tzinfo=self)) // SECOND
        args = _time.localtime(stamp)[:6]
        dst_diff = DSTDIFF // SECOND
        # Detect fold
        fold = (args == _time.localtime(stamp - dst_diff))
        return datetime(*args, microsecond=dt.microsecond,
                        tzinfo=self, fold=fold)

    def utcoffset(self, dt):
        if self._isdst(dt):
            return DSTOFFSET
        else:
            return STDOFFSET

    def dst(self, dt):
        if self._isdst(dt):
            return DSTDIFF
        else:
            return ZERO

    def tzname(self, dt):
        return _time.tzname[self._isdst(dt)]

    def _isdst(self, dt):
        tt = (dt.year, dt.month, dt.day,
              dt.hour, dt.minute, dt.second,
              dt.weekday(), 0, 0)
        stamp = _time.mktime(tt)
        tt = _time.localtime(stamp)
        return tt.tm_isdst > 0

Local = LocalTimezone()

# A complete implementation of current DST rules for major US time zones.

def first_sunday_on_or_after(dt):
    days_to_go = 6 - dt.weekday()
    if days_to_go:
        dt += timedelta(days_to_go)
    return dt

# US DST Rules
#
# This is a simplified (i.e., wrong for a few cases) set of rules for US
# DST start and end times. For a complete and up-to-date set of DST rules
# and timezone definitions, visit the Olson Database (or try pytz):
# http://www.twinsun.com/tz/tz-link.htm
# http://sourceforge.net/projects/pytz/ (might not be up-to-date)
#
# In the US, since 2007, DST starts at 2am (standard time) on the second
# Sunday in March, which is the first Sunday on or after Mar 8.
DSTSTART_2007 = datetime(1, 3, 8, 2)
# and ends at 2am (DST time) on the first Sunday of Nov.
DSTEND_2007 = datetime(1, 11, 1, 2)
# From 1987 to 2006, DST used to start at 2am (standard time) on the first
# Sunday in April and to end at 2am (DST time) on the last
# Sunday of October, which is the first Sunday on or after Oct 25.
DSTSTART_1987_2006 = datetime(1, 4, 1, 2)
DSTEND_1987_2006 = datetime(1, 10, 25, 2)
# From 1967 to 1986, DST used to start at 2am (standard time) on the last
# Sunday in April (the one on or after April 24) and to end at 2am (DST time)
# on the last Sunday of October, which is the first Sunday
# on or after Oct 25.
DSTSTART_1967_1986 = datetime(1, 4, 24, 2)
DSTEND_1967_1986 = DSTEND_1987_2006

def us_dst_range(year):
    # Find start and end times for US DST. For years before 1967, return
    # start = end for no DST.
    if 2006 < year:
        dststart, dstend = DSTSTART_2007, DSTEND_2007
    elif 1986 < year < 2007:
        dststart, dstend = DSTSTART_1987_2006, DSTEND_1987_2006
    elif 1966 < year < 1987:
        dststart, dstend = DSTSTART_1967_1986, DSTEND_1967_1986
    else:
        return (datetime(year, 1, 1), ) * 2

    start = first_sunday_on_or_after(dststart.replace(year=year))
    end = first_sunday_on_or_after(dstend.replace(year=year))
    return start, end

class USTimeZone(tzinfo):

    def __init__(self, hours, reprname, stdname, dstname):
        self.stdoffset = timedelta(hours=hours)
        self.reprname = reprname
        self.stdname = stdname
        self.dstname = dstname

    def __repr__(self):
        return self.reprname

    def tzname(self, dt):
        if self.dst(dt):
            return self.dstname
        else:
            return self.stdname

    def utcoffset(self, dt):
        return self.stdoffset + self.dst(dt)

    def dst(self, dt):
        if dt is None or dt.tzinfo is None:
            # An exception may be sensible here, in one or both cases.
            # It depends on how you want to treat them.  The default
            # fromutc() implementation (called by the default astimezone()
            # implementation) passes a datetime with dt.tzinfo is self.
            return ZERO
        assert dt.tzinfo is self
        start, end = us_dst_range(dt.year)
        # Can't compare naive to aware objects, so strip the timezone from
        # dt first.
        dt = dt.replace(tzinfo=None)
        if start + HOUR <= dt < end - HOUR:
            # DST is in effect.
            return HOUR
        if end - HOUR <= dt < end:
            # Fold (an ambiguous hour): use dt.fold to disambiguate.
            return ZERO if dt.fold else HOUR
        if start <= dt < start + HOUR:
            # Gap (a non-existent hour): reverse the fold rule.
            return HOUR if dt.fold else ZERO
        # DST is off.
        return ZERO

    def fromutc(self, dt):
        assert dt.tzinfo is self
        start, end = us_dst_range(dt.year)
        start = start.replace(tzinfo=self)
        end = end.replace(tzinfo=self)
        std_time = dt + self.stdoffset
        dst_time = std_time + HOUR
        if end <= dst_time < end + HOUR:
            # Repeated hour
            return std_time.replace(fold=1)
        if std_time < start or dst_time >= end:
            # Standard time
            return std_time
        if start <= std_time < end - HOUR:
            # Daylight saving time
            return dst_time

Eastern  = USTimeZone(-5, "Eastern",  "EST", "EDT")
Central  = USTimeZone(-6, "Central",  "CST", "CDT")
Mountain = USTimeZone(-7, "Mountain", "MST", "MDT")
Pacific  = USTimeZone(-8, "Pacific",  "PST", "PDT")

Tenga en cuenta que hay sutilezas inevitables dos veces al año en una subclase tzinfo que representa tanto el horario estándar como el horario de verano, en los puntos de transición DST. Para mayor concreción, considere US Eastern (UTC -0500), donde EDT comienza el minuto después de 1:59 (EST) el segundo domingo de marzo y termina el minuto después de 1:59 (EDT) el primer domingo de noviembre

  UTC   3:MM  4:MM  5:MM  6:MM  7:MM  8:MM
  EST  22:MM 23:MM  0:MM  1:MM  2:MM  3:MM
  EDT  23:MM  0:MM  1:MM  2:MM  3:MM  4:MM

start  22:MM 23:MM  0:MM  1:MM  3:MM  4:MM

  end  23:MM  0:MM  1:MM  1:MM  2:MM  3:MM

Cuando comienza el horario de verano (la línea de «inicio»),tiempo real transcurrido (wall time) salta de 1:59 a 3:00. Un tiempo de pared de la forma 2: MM realmente no tiene sentido ese día, por lo que astimezone (Eastern) no entregará un resultado con hour == 2 el día en que comienza el horario de verano. Por ejemplo, en la transición de primavera de 2016, obtenemos

>>> from datetime import datetime, timezone
>>> from tzinfo_examples import HOUR, Eastern
>>> u0 = datetime(2016, 3, 13, 5, tzinfo=timezone.utc)
>>> for i in range(4):
...     u = u0 + i*HOUR
...     t = u.astimezone(Eastern)
...     print(u.time(), 'UTC =', t.time(), t.tzname())
...
05:00:00 UTC = 00:00:00 EST
06:00:00 UTC = 01:00:00 EST
07:00:00 UTC = 03:00:00 EDT
08:00:00 UTC = 04:00:00 EDT

Cuando finaliza el horario de verano (la línea «final»), hay un problema potencialmente peor: hay una hora que no se puede deletrear sin ambigüedades en el tiempo de la pared local: la última hora del día. En el Este, esos son los tiempos de la forma 5:MM UTC en el día en que termina el horario de verano. El reloj de pared local salta de 1:59 (hora del día) a la 1:00 (hora estándar) nuevamente. Horas locales de la forma 1:MM son ambiguas. astimezone() imita el comportamiento del reloj local al mapear dos horas UTC adyacentes en la misma hora local. En el ejemplo oriental, los tiempos UTC de la forma 5: MM y 6: MM se correlacionan con 1:MM cuando se convierten en oriental, pero los tiempos anteriores tienen el atributo fold establecido en 0 y los tiempos posteriores configúrelo en 1. Por ejemplo, en la transición alternativa de 2016, obtenemos:

>>> u0 = datetime(2016, 11, 6, 4, tzinfo=timezone.utc)
>>> for i in range(4):
...     u = u0 + i*HOUR
...     t = u.astimezone(Eastern)
...     print(u.time(), 'UTC =', t.time(), t.tzname(), t.fold)
...
04:00:00 UTC = 00:00:00 EDT 0
05:00:00 UTC = 01:00:00 EDT 0
06:00:00 UTC = 01:00:00 EST 1
07:00:00 UTC = 02:00:00 EST 0

Tenga en cuenta que las instancias datetime que difieren solo por el valor del atributo fold se consideran iguales en las comparaciones.

Las aplicaciones que no pueden soportar ambigüedades de tiempo real (wall time) deben verificar explícitamente el valor del atributo fold o evitar el uso de las subclases híbridas tzinfo; no existen ambigüedades cuando se utiliza timezone, o cualquier otra subclase de clase offset tzinfo (como una clase que representa solo EST (desplazamiento fijo -5 horas), o solo EDT (desplazamiento fijo -4 horas)).

Ver también

zoneinfo

El módulo datetime tiene una clase básica timezone (para manejar compensaciones fijas arbitrarias desde UTC) y su atributo timezone.utc (una instancia de zona horaria UTC).

zoneinfo brings the IANA timezone database (also known as the Olson database) to Python, and its usage is recommended.

IANA timezone database [https://www.iana.org/time-zones]

La base de datos de zonas horarias (a menudo llamada tz, tzdata o zoneinfo) contiene código y datos que representan el historial de la hora local de muchos lugares representativos de todo el mundo. Se actualiza periódicamente para reflejar los cambios realizados por los cuerpos políticos en los límites de la zona horaria, las compensaciones UTC y las reglas de horario de verano.

Objetos timezone

La clase timezone es una subclase de tzinfo, cada una de las cuales representa una zona horaria definida por un desplazamiento fijo desde UTC.

Los objetos de esta clase no se pueden usar para representar la información de zona horaria en los lugares donde se usan diferentes desplazamientos en diferentes días del año o donde se han realizado cambios históricos en la hora civil.

class datetime.timezone(offset, name=None)

El argumento offset debe especificarse como un objeto de timedelta que representa la diferencia entre la hora local y UTC. Debe estar estrictamente entre -timedelta(horas = 24) y timedelta(horas = 24), de lo contrario ValueError se genera.

El argumento name es opcional. Si se especifica, debe ser una cadena de caracteres que se utilizará como el valor retornado por el método datetime.tzname().

Nuevo en la versión 3.2.

Distinto en la versión 3.7: El desfase UTC no está restringido a un número entero de minutos.

timezone.utcoffset(dt)

Retorna el valor fijo especificado cuando se construye la instancia timezone.

El argumento dt se ignora. El valor de retorno es una instancia de timedelta igual a la diferencia entre la hora local y UTC.

Distinto en la versión 3.7: El desfase UTC no está restringido a un número entero de minutos.

timezone.tzname(dt)

Retorna el valor fijo especificado cuando se construye la instancia timezone.

Si no se proporciona name en el constructor, el nombre retornado por tzname(dt) se genera a partir del valor del offset de la siguiente manera. Si offset es timedelta (0), el nombre es «UTC», de lo contrario es una cadena en el formato UTC ±, donde ± es el signo de offset, HH y MM son dos dígitos de offset.hours y offset.minutes respectivamente.

Distinto en la versión 3.6: El nombre generado a partir de offset = timedelta (0) ahora es simple `` UTC``, no ‘UTC+00:00’.

timezone.dst(dt)

Siempre retorna None.

timezone.fromutc(dt)

Retorna dt + offset. El argumento dt debe ser una instancia consciente (aware) datetime, con` tzinfo` establecido en``self``.

Atributos de clase:

timezone.utc

La zona horaria UTC, timezone(timedelta(0)).

Comportamiento strftime() y strptime()

date, datetime, y time los objetos admiten un método strftime(format), para crear una cadena que represente el tiempo bajo el control de una cadena de caracteres de formato explícito.

Por el contrario, el método de clase datetime.strptime() crea un objeto datetime a partir de una cadena que representa una fecha y hora y una cadena de formato correspondiente.

La siguiente tabla proporciona una comparación de alto nivel de strftime() versus strptime():

strftime

strptime

Uso

Convierte objetos en una cadena de caracteres de acuerdo con un formato dado

parsear una cadena en un objeto datetime con el formato correspondiente

Tipo de método

Método de instancia

Método de clase

Método de

date; datetime; time

datetime

Firma

strftime(format)

strptime(date_string, format)

Códigos de formato strftime() y strptime()

La siguiente es una lista de todos los códigos de formato que requiere el estándar 1989 C, y estos funcionan en todas las plataformas con una implementación estándar C.

Directiva

Significado

Ejemplo

Notas

%a

Día de la semana como nombre abreviado según la configuración regional.

Sun, Mon, …, Sat (en_US);

So, Mo, …, Sa (de_DE)

(1)

%A

Día de la semana como nombre completo de la localidad.

Sunday, Monday, …, Saturday (en_US);

Sonntag, Montag, …, Samstag (de_DE)

(1)

%w

Día de la semana como un número decimal, donde 0 es domingo y 6 es sábado.

0, 1, …, 6

%d

Día del mes como un número decimal rellenado con ceros.

01, 02, …, 31

(9)

%b

Mes como nombre abreviado según la configuración regional.

Jan, Feb, …, Dec (en_US);

Jan, Feb, …, Dez (de_DE)

(1)

%B

Mes como nombre completo según la configuración regional.

January, February, …, December (en_US);

Januar, Februar, …, Dezember (de_DE)

(1)

%m

Mes como un número decimal rellenado con ceros.

01, 02, …, 12

(9)

%y

Año sin siglo como un número decimal rellenado con ceros.

00, 01, …, 99

(9)

%Y

Año con siglo como número decimal.

0001, 0002, …, 2013, 2014, …, 9998, 9999

(2)

%H

Hora (reloj de 24 horas) como un número decimal rellenado con ceros.

00, 01, …, 23

(9)

%I

Hora (reloj de 12 horas) como un número decimal rellenado con ceros.

01, 02, …, 12

(9)

%p

El equivalente de la configuración regional de AM o PM.

AM, PM (en_US);

am, pm (de_DE)

(1), (3)

%M

Minuto como un número decimal rellenado con ceros.

00, 01, …, 59

(9)

%S

Segundo como un número decimal rellenado con ceros.

00, 01, …, 59

(4), (9)

%f

Microsecond as a decimal number, zero-padded to 6 digits.

000000, 000001, …, 999999

(5)

%z

Desplazamiento (offset) UTC en la forma ±HHMM[SS[.ffffff]] (cadena de caracteres vacía si el objeto es naíf (naive)).

(vacío), +0000, -0400, +1030, +063415, -030712.345216

(6)

%Z

Nombre de zona horaria (cadena de caracteres vacía si el objeto es naíf (naive)).

(vacío), UTC, GMT

(6)

%j

Día del año como un número decimal rellenado con ceros.

001, 002, …, 366

(9)

%U

Week number of the year (Sunday as the first day of the week) as a zero-padded decimal number. All days in a new year preceding the first Sunday are considered to be in week 0.

00, 01, …, 53

(7), (9)

%W

Week number of the year (Monday as the first day of the week) as a zero-padded decimal number. All days in a new year preceding the first Monday are considered to be in week 0.

00, 01, …, 53

(7), (9)

%c

Representación apropiada de fecha y hora de la configuración regional.

Tue Aug 16 21:30:00 1988 (en_US);

Di 16 Aug 21:30:00 1988 (de_DE)

(1)

%x

Representación de fecha apropiada de la configuración regional.

08/16/88 (None);

08/16/1988 (en_US);

16.08.1988 (de_DE)

(1)

%X

Representación de la hora apropiada de la configuración regional.

21:30:00 (en_US);

21:30:00 (de_DE)

(1)

%%

Un carácter literal ’%’.

%

Se incluyen varias directivas adicionales no requeridas por el estándar C89 por conveniencia. Todos estos parámetros corresponden a valores de fecha ISO 8601.

Directiva

Significado

Ejemplo

Notas

%G

ISO 8601 año con siglo que representa el año que contiene la mayor parte de la semana ISO (%V).

0001, 0002, …, 2013, 2014, …, 9998, 9999

(8)

%u

ISO 8601 día de la semana como un número decimal donde 1 es lunes.

1, 2, …, 7

%V

ISO 8601 semana como un número decimal con lunes como primer día de la semana. La semana 01 es la semana que contiene el 4 de enero.

01, 02, …, 53

(8), (9)

Es posible que no estén disponibles en todas las plataformas cuando se usan con el método strftime(). Las directivas ISO 8601 año e ISO 8601 semana no son intercambiables con las directivas de número de año y semana anteriores. Llamar a strptime() con directivas ISO 8601 incompletas o ambiguas generará un ValueError.

The full set of format codes supported varies across platforms, because Python calls the platform C library’s strftime() function, and platform variations are common. To see the full set of format codes supported on your platform, consult the strftime(3) documentation. There are also differences between platforms in handling of unsupported format specifiers.

Nuevo en la versión 3.6: %G, %u y %V fueron añadidos.

Detalle técnico

En términos generales, d.strftime (fmt) actúa como el módulo time time.strftime(fmt, d.timetuple()) aunque no todos los objetos admiten el método timetuple().

Para el método de clase datetime.strptime(), el valor predeterminado es 1900-01-01T00:00:00.000: cualquier componente no especificado en la cadena de formato se extraerá del valor predeterminado. 4

Usar datetime.strptime(date_string, format) es equivalente a:

datetime(*(time.strptime(date_string, format)[0:6]))

excepto cuando el formato incluye componentes de sub-segundos o información de compensación de zona horaria, que son compatibles con datetime.strptime pero son descartados por time.strptime.

Para objetos de time, los códigos de formato para año, mes y día no deben usarse, ya que los objetos de time no tienen tales valores. Si se usan de todos modos, 1900 se sustituye por el año y 1 por el mes y el día.

Para los objetos date, los códigos de formato para horas, minutos, segundos y microsegundos no deben usarse, ya que los objetos date no tienen tales valores. Si se usan de todos modos, 0 se sustituye por ellos.

Por la misma razón, el manejo de cadenas de formato que contienen puntos de código Unicode que no se pueden representar en el conjunto de caracteres del entorno local actual también depende de la plataforma. En algunas plataformas, estos puntos de código se conservan intactos en la salida, mientras que en otros strftime puede generar UnicodeError o retornar una cadena vacía.

Notas:

Debido a que el formato depende de la configuración regional actual, se debe tener cuidado al hacer suposiciones sobre el valor de salida. Los ordenamientos de campo variarán (por ejemplo, «mes/día/año» versus «día/mes/año»), y la salida puede contener caracteres Unicode codificados utilizando la codificación predeterminada de la configuración regional (por ejemplo, si la configuración regional actual es ja_JP, la codificación predeterminada podría ser cualquiera de eucJP, `` SJIS`` o utf-8; use locale.getlocale() para determinar la codificación de la configuración regional actual).

El método strptime() puede analizar años en el rango completo [1, 9999], pero los años < 1000 deben llenarse desde cero hasta un ancho de 4 dígitos.

Distinto en la versión 3.2: En versiones anteriores, el método strftime() estaba restringido a años >= 1900.

Distinto en la versión 3.3: En la versión 3.2, el método strftime() estaba restringido a años >= 1000.

Cuando se usa con el método strptime(), la directiva %p solo afecta el campo de hora de salida si se usa la directiva %I para analizar la hora.

A diferencia del módulo time, el módulo datetime no admite segundos intercalares.

Cuando se usa con el método strptime(), la %f` directiva acepta de uno a seis dígitos y cero pads a la derecha. %f es una extensión del conjunto de caracteres de formato en el estándar C (pero implementado por separado en objetos de fecha y hora y, por lo tanto, siempre disponible).

Para un objeto naíf (naive), los códigos de formato %z y %Z se reemplazan por cadenas vacías.

Para un objeto consciente (aware)

%z

utcoffset() se transforma en una cadena de la forma ±HHMM[SS[.ffffff]], donde``HH`` es una cadena de 2 dígitos que da el número de horas de desplazamiento UTC,``MM`` es una cadena de 2 dígitos que da el número de minutos de desplazamiento UTC,``SS`` es una cadena de 2 dígitos que da el número de segundos de desplazamiento UTC y ffffff es una cadena de 6 dígitos que da el número de microsegundos de desplazamiento UTC. La parte ffffff se omite cuando el desplazamiento es un número entero de segundos y tanto la parte ffffff como la parte SS se omiten cuando el desplazamiento es un número entero de minutos. Por ejemplo, si utcoffset() retorna timedelta(hours=-3, minutes=-30), %z se reemplaza con la cadena '-0330'.

Distinto en la versión 3.7: El desfase UTC no está restringido a un número entero de minutos.

Distinto en la versión 3.7: Cuando la directiva %z se proporciona al método strptime(), las compensaciones UTC pueden tener dos puntos como separador entre horas, minutos y segundos. Por ejemplo, ’+01:00:00’ se analizará como una compensación de una hora. Además, proporcionar 'Z' es idéntico a ’+00:00’.

%Z

En strftime(), %Z se reemplaza por una cadena de caracteres vacía si tzname() retorna None; de lo contrario, %Z se reemplaza por el valor retornado, que debe ser una cadena de caracteres.

strptime() solo acepta ciertos valores para %Z:

cualquier valor en time.tzname para la configuración regional de su máquina

los valores codificados de forma rígida UTC y GMT

Entonces, alguien que viva en Japón puede tener JST, UTC y GMT como valores válidos, pero probablemente no EST. Lanzará ValueError para valores no válidos.

Distinto en la versión 3.2: Cuando la directiva %z se proporciona al método strptime(), se generará un objeto consciente datetime. El tzinfo del resultado se establecerá en una instancia timezone.

Cuando se usa con el método strptime(), %U y %W solo se usan en los cálculos cuando se especifican el día de la semana y el año calendario (%Y) .

Similar a %U y %W, %V solo se usa en cálculos cuando el día de la semana y el año ISO (%G) se especifican en strptime() cadena de formato. También tenga en cuenta que %G y %Y no son intercambiables.

Cuando se usa con el método strptime(), el cero inicial es opcional para los formatos %d, %m, %H, %I, %M, %S, %J, %U, %W y %V. El formato %y requiere un cero a la izquierda.

Pie de notas

1

Es decir, si ignoramos los efectos de la relatividad

2

Esto coincide con la definición del calendario «proléptico gregoriano» en el libro de Dershowitz y Reingold Cálculos calendáricos, donde es el calendario base para todos los cálculos. Consulte el libro sobre algoritmos para convertir entre ordinales gregorianos prolépticos y muchos otros sistemas de calendario.

3

Consulte la guía de R. H. van Gent’s guide to the mathematics of the ISO 8601 calendar [https://www.staff.science.uu.nl/~gent0113/calendar/isocalendar.htm] para una buena explicación.

4

Si se pasa datetime.strptime (’29 de febrero’, ‘%b %d’) fallará ya que 1900 no es un año bisiesto.

zoneinfo — Soporte de zona horaria IANA

Nuevo en la versión 3.9.

El módulo zoneinfo proporciona una implementación concreta de zonas horarias para soportar la base de datos de zonas horarias de IANA tal y como se especificó originalmente en PEP 615 [https://www.python.org/dev/peps/pep-0615]. Por defecto, zoneinfo utiliza los datos de zona horaria del sistema si están disponibles; si no hay datos de zona horaria del sistema, la biblioteca volverá a utilizar el paquete de primera parte tzdata [https://pypi.org/project/tzdata/] disponible en PyPI.

Ver también

Modulo: datetime

Proporciona los tipos time y datetime con los que está diseñada la clase ZoneInfo.

Paquete tzdata [https://pypi.org/project/tzdata/]

Paquete de origen mantenido por los desarrolladores del núcleo de CPython para suministrar datos de zonas horarias a través de PyPI.

Usando ZoneInfo

ZoneInfo es una implementación concreta de la clase base abstracta datetime.tzinfo, y está pensada para ser adjuntada a tzinfo, bien a través del constructor, del método datetime.replace o de datetime.astimezone:

>>> from zoneinfo import ZoneInfo
>>> from datetime import datetime, timedelta

>>> dt = datetime(2020, 10, 31, 12, tzinfo=ZoneInfo("America/Los_Angeles"))
>>> print(dt)
2020-10-31 12:00:00-07:00

>>> dt.tzname()
'PDT'

Las fechas construidas de esta manera son compatibles con la aritmética de fechas y manejan las transiciones del horario de verano sin ninguna otra intervención:

>>> dt_add = dt + timedelta(days=1)

>>> print(dt_add)
2020-11-01 12:00:00-08:00

>>> dt_add.tzname()
'PST'

Estas zonas horarias también soportan el atributo fold introducido en PEP 495 [https://www.python.org/dev/peps/pep-0495]. Durante las transiciones de desfase que inducen tiempos ambiguos (como una transición de horario de verano a horario estándar), se utiliza el desfase de antes de la transición cuando fold=0, y el desfase después de la transición cuando fold=1, por ejemplo:

>>> dt = datetime(2020, 11, 1, 1, tzinfo=ZoneInfo("America/Los_Angeles"))
>>> print(dt)
2020-11-01 01:00:00-07:00

>>> print(dt.replace(fold=1))
2020-11-01 01:00:00-08:00

Al convertir desde otra zona horaria, el pliegue se ajustará al valor correcto:

>>> from datetime import timezone
>>> LOS_ANGELES = ZoneInfo("America/Los_Angeles")
>>> dt_utc = datetime(2020, 11, 1, 8, tzinfo=timezone.utc)

>>> # Before the PDT -> PST transition
>>> print(dt_utc.astimezone(LOS_ANGELES))
2020-11-01 01:00:00-07:00

>>> # After the PDT -> PST transition
>>> print((dt_utc + timedelta(hours=1)).astimezone(LOS_ANGELES))
2020-11-01 01:00:00-08:00

Fuentes de datos

El módulo zoneinfo no proporciona directamente los datos de la zona horaria, y en su lugar extrae la información de la zona horaria de la base de datos de la zona horaria del sistema o del paquete de PyPI tzdata [https://pypi.org/project/tzdata/], si está disponible. Algunos sistemas, incluyendo notablemente los sistemas Windows, no tienen una base de datos IANA disponible, por lo que para los proyectos que tienen como objetivo la compatibilidad entre plataformas que requieren datos de zona horaria, se recomienda declarar una dependencia de tzdata. Si no están disponibles ni los datos del sistema ni los de tzdata, todas las llamadas a ZoneInfo lanzarán un ZoneInfoNotFoundError.

Configurando los orígenes de datos

Cuando se llama a ZoneInfo(key), el constructor busca primero en los directorios especificados en TZPATH un archivo que coincida con key, y en caso de fallo busca una coincidencia en el paquete tzdata. Este comportamiento puede configurarse de tres maneras:

El TZPATH por defecto cuando no se especifica otra cosa puede configurarse en tiempo de compilación.

TZPATH puede configurarse utilizando una variable de entorno.

En runtime, la ruta de búsqueda puede ser manipulada usando la función reset_tzpath().

Configuración en tiempo de compilación

La ruta por defecto TZPATH incluye varias ubicaciones comunes de despliegue para la base de datos de zonas horarias (excepto en Windows, donde no hay ubicaciones «conocidas» para los datos de zonas horarias). En los sistemas POSIX, los distribuidores posteriores y aquellos que construyen Python desde el código fuente que saben dónde se despliegan los datos de zona horaria de su sistema pueden cambiar la ruta de zona horaria por defecto especificando la opción de compilación TZPATH (o, más probablemente, la bandera configure --with-tzpath), que debe ser una cadena delimitada por os.pathsep.

En todas las plataformas, el valor configurado está disponible como la clave TZPATH en sysconfig.get_config_var().

Configuración del entorno

Cuando se inicializa TZPATH (ya sea en el momento de la importación o cuando se llama a reset_tzpath() sin argumentos), el módulo zoneinfo utilizará la variable de entorno PYTHONTZPATH, si existe, para establecer la ruta de búsqueda.

PYTHONTZPATH

Se trata de una cadena separada por os.pathsep que contiene la ruta de búsqueda de la zona horaria a utilizar. Debe consistir sólo en rutas absolutas y no relativas. Los componentes relativos especificados en PYTHONTZPATH no se utilizarán, pero por lo demás el comportamiento cuando se especifica una ruta relativa es definido por la implementación; CPython lanzará InvalidTZPathWarning, pero otras implementaciones son libres de ignorar silenciosamente el componente erróneo o lanzar una excepción.

Para que el sistema ignore los datos del sistema y utilice el paquete tzdata en su lugar, establezca PYTHONTZPATH="".

Configuración de tiempo de ejecución

La ruta de búsqueda de TZ también puede configurarse en tiempo de ejecución mediante la función reset_tzpath(). Por lo general, esta operación no es aconsejable, aunque es razonable utilizarla en funciones de prueba que requieran el uso de una ruta de zona horaria específica (o que requieran deshabilitar el acceso a las zonas horarias del sistema).

La clase ZoneInfo

class zoneinfo.ZoneInfo(key)

Una subclase concreta de datetime.tzinfo que representa una zona horaria IANA especificada por la cadena key. Las llamadas al constructor primario siempre devolverán objetos que se comparan de forma idéntica; dicho de otro modo, salvo la invalidación de la caché mediante ZoneInfo.clear_cache(), para todos los valores de key, la siguiente afirmación siempre será verdadera:

a = ZoneInfo(key)
b = ZoneInfo(key)
assert a is b

La key debe tener la forma de una ruta POSIX relativa y normalizada, sin referencias de nivel superior. El constructor lanzará ValueError si se pasa una clave no conforme.

Si no se encuentra ningún archivo que coincida con la clave, el constructor lanzará ZoneInfoNotFoundError.

La clase ZoneInfo tiene dos constructores alternativos:

classmethod ZoneInfo.from_file(fobj, /, key=None)

Construye un objeto ZoneInfo a partir de un objeto tipo archivo que retorna bytes (por ejemplo, un archivo abierto en modo binario o un objeto io.BytesIO). A diferencia del constructor primario, éste siempre construye un nuevo objeto.

El parámetro key establece el nombre de la zona a efectos de __str__() y __repr__().

Los objetos creados a través de este constructor no pueden ser serializados (ver pickling).

classmethod ZoneInfo.no_cache(key)

Un constructor alternativo que omite la caché del constructor. Es idéntico al constructor principal, pero retorna un nuevo objeto en cada llamada. Es muy probable que esto sea útil para propósitos de prueba o demostración, pero también se puede utilizar para crear un sistema con una estrategia de invalidación de caché diferente.

Los objetos creados a través de este constructor también pasarán por encima de la caché de un proceso de deserialización cuando sean deserializados.

Prudencia

El uso de este constructor puede cambiar la semántica de tus datetimes de manera sorprendente, sólo úsalo si sabes que lo necesitas.

También están disponibles los siguientes métodos de clase:

classmethod ZoneInfo.clear_cache(*, only_keys=None)

Un método para invalidar la caché de la clase ZoneInfo. Si no se pasan argumentos, se invalidan todas las cachés y la siguiente llamada al constructor primario de cada clave devolverá una nueva instancia.

Si se pasa un iterable de nombres de claves al parámetro only_keys, sólo se eliminarán de la caché las claves especificadas. Las claves pasadas a only_keys pero que no se encuentran en la caché se ignoran.

Advertencia

La invocación de esta función puede cambiar la semántica de las fechas utilizando ZoneInfo de forma sorprendente; esto modifica el estado global del proceso y por lo tanto puede tener efectos de gran alcance. Utilícela sólo si sabe que lo necesita.

La clase tiene un atributo:

ZoneInfo.key

Se trata de un attribute de sólo lectura que retorna el valor de key pasado al constructor, que debe ser una clave de búsqueda en la base de datos de zonas horarias de la IANA (por ejemplo, America/New_York, Europe/Paris o Asia/Tokyo.

Para las zonas construidas a partir de un archivo sin especificar un parámetro key, se establecerá como None.

Nota

Aunque es una práctica algo común exponerlos a los usuarios finales, estos valores están diseñados para ser claves primarias para representar las zonas relevantes y no necesariamente elementos orientados al usuario. Se pueden utilizar proyectos como CLDR (Unicode Common Locale Data Repository) para obtener cadenas más fáciles de usar a partir de estas claves.

Representaciones de cadenas

La representación de cadena que se retorna al llamar a str sobre un objeto ZoneInfo utiliza por defecto el atributo ZoneInfo.key (ver la nota de uso en la documentación del atributo):

>>> zone = ZoneInfo("Pacific/Kwajalein")
>>> str(zone)
'Pacific/Kwajalein'

>>> dt = datetime(2020, 4, 1, 3, 15, tzinfo=zone)
>>> f"{dt.isoformat()} [{dt.tzinfo}]"
'2020-04-01T03:15:00+12:00 [Pacific/Kwajalein]'

Para los objetos construidos a partir de un fichero sin especificar un parámetro key, str vuelve a llamar a repr`(). El parámetro repr de ZoneInfo está definido por la implementación y no es necesariamente estable entre versiones, pero se garantiza que no es una clave válida de ZoneInfo.Pickled.

Serialización de Pickle

En lugar de serializar todos los datos de transición, los objetos ZoneInfo se serializan por clave, y los objetos ZoneInfo construidos a partir de archivos (incluso los que tienen un valor por key especifico) no pueden ser serializados.

El comportamiento de un archivo ZoneInfo depende de cómo se haya construido:

ZoneInfo(key): Cuando se construye con el constructor primario, un objeto ZoneInfo se serializa por la clave, y cuando se deserializa, el proceso de deserialización utiliza el primario y por lo tanto se espera que estos sean el mismo objeto que otras referencias a la misma zona horaria. Por ejemplo, si europe_berlin_pkl es una cadena que contiene un pickle construido a partir de ZoneInfo("Europe/Berlin"), se esperaría el siguiente comportamiento:

>>> a = ZoneInfo("Europe/Berlin")
>>> b = pickle.loads(europe_berlin_pkl)
>>> a is b
True

ZoneInfo.no_cache(key): Cuando se construye a partir del constructor que evita la caché, el objeto ZoneInfo también se serializa por clave, pero cuando se deserializa, el proceso de deserialización utiliza el constructor que evita la caché. Si europe_berlin_pkl_nc es una cadena que contiene un pickle construido a partir de ZoneInfo.no_cache("Europe/Berlin"), cabría esperar el siguiente comportamiento:

>>> a = ZoneInfo("Europe/Berlin")
>>> b = pickle.loads(europe_berlin_pkl_nc)
>>> a is b
False

ZoneInfo.from_file(fobj, /, key=None): Cuando se construye a partir de un fichero, el objeto ZoneInfo lanza una excepción al ser recogido. Si un usuario final quiere recoger un ZoneInfo construido a partir de un archivo, se recomienda que utilice un tipo de envoltura o una función de serialización personalizada: ya sea serializando por clave o almacenando el contenido del objeto archivo y serializándolo.

Este método de serialización requiere que los datos de la zona horaria para la clave requerida estén disponibles tanto en el lado de serialización como en el de deserialización, de forma similar a como se espera que las referencias a las clases y funciones existan tanto en el entorno de serialización como en el de deserialización. También significa que no se garantiza la consistencia de los resultados cuando se retira un ZoneInfo recogido en un entorno con una versión diferente de los datos de la zona horaria.

Funciones

zoneinfo.available_timezones()

Obtiene un conjunto que contiene todas las claves válidas para las zonas horarias de la IANA disponibles en cualquier lugar de la ruta de zonas horarias. Se recalcula en cada llamada a la función.

Esta función sólo incluye los nombres de zona canónicos y no incluye las zonas «especiales» como las que se encuentran bajo los directorios posix/ y right/, o la zona posixrules.

Prudencia

Esta función puede abrir un gran número de archivos, ya que la mejor manera de determinar si un archivo en la ruta de la zona horaria es una zona horaria válida es leer la «magic string» (cadena mágica) al principio.

Nota

Estos valores no están diseñados para ser expuestos a los usuarios finales; para los elementos de cara al usuario, las aplicaciones deberían utilizar algo como CLDR (el Unicode Common Locale Data Repository) para obtener cadenas más fáciles de usar. Véase también la nota de advertencia sobre ZoneInfo.key.

zoneinfo.reset_tzpath(to=None)

Establece o restablece la ruta de búsqueda de la zona horaria (TZPATH) para el módulo. Cuando se llama sin argumentos, TZPATH se establece en el valor por defecto.

La llamada a reset_tzpath no invalidará la caché de ZoneInfo, por lo que las llamadas al constructor primario de ZoneInfo sólo utilizarán el nuevo TZPATH en caso de que se pierda la caché.

El parámetro to debe ser un sequence de cadenas o os.PathLike y no una cadena, todos los cuales deben ser rutas absolutas. ValueError se lanzará si se pasa algo que no sea una ruta absoluta.

Globales

zoneinfo.TZPATH

Una secuencia de sólo lectura que representa la ruta de búsqueda de zonas horarias – cuando se construye un ZoneInfo a partir de una clave, la clave se une a cada entrada del TZPATH, y se utiliza el primer archivo encontrado.

TZPATH sólo puede contener rutas absolutas, nunca relativas, independientemente de cómo esté configurado.

El objeto al que apunta zoneinfo.TZPATH puede cambiar en respuesta a una llamada a reset_tzpath(), por lo que se recomienda utilizar zoneinfo.TZPATH en lugar de importar TZPATH desde zoneinfo o asignar una variable de larga duración a zoneinfo.TZPATH.

Para más información sobre la configuración de la ruta de búsqueda de zonas horarias, consulte Configurando los orígenes de datos.

Excepciones y advertencias

exception zoneinfo.ZoneInfoNotFoundError

Se lanza cuando la construcción de un objeto ZoneInfo falla porque la clave especificada no puede encontrarse en el sistema. Es una subclase de KeyError.

exception zoneinfo.InvalidTZPathWarning

Se lanza cuando PYTHONTZPATH contiene un componente no válido que será filtrado, como una ruta relativa.

calendar — Funciones generales relacionadas con el calendario

Código fuente: Lib/calendar.py [https://github.com/python/cpython/tree/3.9/Lib/calendar.py]

Este módulo te permite generar calendarios como el programa Unix cal, y proporciona funciones útiles adicionales relacionadas con el calendario. Por defecto, estos calendarios tienen el lunes como el primer día de la semana, y el domingo como el último (la convención europea). Use setfirstweekday() para establecer el primer día de la semana en domingo (6) o en cualquier otro día de la semana. Los parámetros que especifican fechas se indican como enteros. Para la funcionalidad relacionada, consulta también los módulos datetime y time.

Las funciones y clases definidas en este módulo utilizan un calendario idealizado, el calendario gregoriano actual extendido indefinidamente en ambas direcciones. Esto coincide con la definición del calendario «Gregoriano proléptico» en el libro «Calendrical Calculations» de Dershowitz y Reingold, donde es el calendario base para todos los cálculos. Los años cero y negativos se interpretan según lo prescrito por la norma ISO 8601. El año 0 es 1 A. C., el año -1 es 2 a. C., y así sucesivamente.

class calendar.Calendar(firstweekday=0)

Crea un objeto Calendar. firstweekday es un entero que especifica el primer día de la semana. 0 es lunes (por defecto), 6 es domingo.

Un objeto Calendar proporciona varios métodos que se pueden utilizar para preparar los datos del calendario para dar formato. Esta clase no hace ningún formato en sí. Este es el trabajo de las subclases.

Las instancias de Calendar tienen los siguientes métodos:

iterweekdays()

Retorna un iterador para los números del día de la semana que se usará durante una semana. El primer valor del iterador será el mismo que el valor de la propiedad firstweekday.

itermonthdates(year, month)

Retorna un iterador para el mes month (1–12) en el año year. Este iterador retornará todos los días (como objetos datetime.date) para el mes y todos los días antes del inicio del mes o después del final del mes que se requieren para obtener una semana completa.

itermonthdays(year, month)

Retorna un iterador para el mes month en el año year similar a itermonthdates(), pero no restringido por el intervalo datetime.date. Los días retornados serán simplemente el día de los números del mes. Para los días fuera del mes especificado, el número de día es 0.

itermonthdays2(year, month)

Retorna un iterador para el mes month del año year similar a itermonthdates(), pero no restringido por el rango datetime.date. Los días retornados serán tuplas que consisten en un número de día del mes y un número de día de la semana.

itermonthdays3(year, month)

Retorna un iterador para el mes month del año year similar a itermonthdates(), pero no restringido por el rango datetime.date. Los días retornados serán tuplas que consisten en un año, un mes y un día del mes.

Nuevo en la versión 3.7.

itermonthdays4(year, month)

Retorna un iterador para el mes month del año year similar a itermonthdates(), pero no restringido por el rango datetime.date. Los días retornados serán tuplas que consisten en un año, un mes, un día del mes y un día de la semana.

Nuevo en la versión 3.7.

monthdatescalendar(year, month)

Retorna una lista de las semanas del mes month del año year como semanas completas. Las semanas son listas de siete objetos datetime.date.

monthdays2calendar(year, month)

Retorna una lista de las semanas del mes month del año year como semanas completas. Las semanas son listas de siete tuplas de números de días y números de días de la semana.

monthdayscalendar(year, month)

Retorna una lista de las semanas del mes month del año year como semanas completas. Las semanas son listas de números de siete días.

yeardatescalendar(year, width=3)

Retorna los datos del año especificado listos para ser formateados. El valor de retorno es una lista de filas de mes. Cada fila de mes contiene hasta width meses (por defecto hasta 3). Cada mes contiene entre 4 y 6 semanas y cada semana contiene 1–7 días. Los días son objetos datetime.date.

yeardays2calendar(year, width=3)

Retorna los datos del año especificado listos para ser formateados (similar a yeardatescalendar()). Las entradas en las listas de la semana son tuplas de números de días y números de días de la semana. Los números de los días fuera de este mes son cero.

yeardayscalendar(year, width=3)

Retorna los datos del año especificado listos para ser formateados (similar a yeardatescalendar()). Las entradas en las listas de la semana son números de día. Los números de día fuera de este mes son cero.

class calendar.TextCalendar(firstweekday=0)

Esta clase puede ser usada para generar calendarios de texto simple.

Las instancias de TextCalendar tienen los siguientes métodos:

formatmonth(theyear, themonth, w=0, l=0)

Retorna el calendario de un mes en una cadena de varias líneas. Si se proporciona w, especifica el ancho de las columnas de fecha, que están centradas. Si se proporciona l, especifica el número de líneas que se utilizarán cada semana. Depende del primer día de la semana como se especifica en el constructor o se establece por el método setfirstweekday().

prmonth(theyear, themonth, w=0, l=0)

Imprime el calendario de un mes como lo retorna formatmonth().

formatyear(theyear, w=2, l=1, c=6, m=3)

Retorna un calendario de m columnas para todo un año como una cadena de varias líneas. Los parámetros opcionales w, l y c son para el ancho de la columna de la fecha, las líneas por semana y el número de espacios entre las columnas del mes, respectivamente. Depende del primer día de la semana como se especifica en el constructor o se establece por el método setfirstweekday(). El primer año para el que se puede generar un calendario depende de la plataforma.

pryear(theyear, w=2, l=1, c=6, m=3)

Imprime el calendario de un año entero como lo retorna formatyear().

class calendar.HTMLCalendar(firstweekday=0)

Esta clase puede utilizarse para generar calendarios HTML.

Las instancias de HTMLCalendar tienen los siguientes métodos:

formatmonth(theyear, themonth, withyear=True)

Retorna el calendario de un mes como una tabla HTML. Si withyear es verdadero, el año será incluido en el encabezado, de lo contrario sólo se usará el nombre del mes.

formatyear(theyear, width=3)

Retorna el calendario de un año como una tabla HTML. width (por defecto a 3) especifica el número de meses por fila.

formatyearpage(theyear, width=3, css='calendar.css', encoding=None)

Retorna el calendario de un año como una página HTML completa. width (por defecto a 3) especifica el número de meses por fila. css es el nombre de la hoja de estilo en cascada que se debe usar. None puede ser pasada si no se debe usar una hoja de estilo. encoding especifica la codificación a ser usada para la salida (por defecto a la codificación por defecto del sistema).

HTMLCalendar tiene los siguientes atributos que puedes sobrescribir para personalizar las clases CSS utilizadas por el calendario:

cssclasses

Una lista de clases CSS utilizadas para cada día de la semana. La lista de clases predeterminada es:

cssclasses = ["mon", "tue", "wed", "thu", "fri", "sat", "sun"]

se pueden añadir más estilos para cada día:

cssclasses = ["mon text-bold", "tue", "wed", "thu", "fri", "sat", "sun red"]

Ten en cuenta que la longitud de esta lista debe ser de siete elementos.

cssclass_noday

La clase CSS para un día de la semana que ocurre en el mes anterior o siguiente.

Nuevo en la versión 3.7.

cssclasses_weekday_head

Una lista de clases CSS utilizadas para los nombres de los días de la semana en la fila del encabezado. El valor por defecto es el mismo que cssclasses.

Nuevo en la versión 3.7.

cssclass_month_head

La clase de CSS del mes (usada por formatmonthname()). El valor por defecto es "month".

Nuevo en la versión 3.7.

cssclass_month

La clase de CSS para la tabla de todo el mes (usada por formatmonth()). El valor por defecto es "month".

Nuevo en la versión 3.7.

cssclass_year

La clase de CSS para la tabla de tablas de todo el año (usada por formatyear()). El valor por defecto es "year".

Nuevo en la versión 3.7.

cssclass_year_head

La clase de CSS para el encabezado de la tabla para todo el año (usado por formatyear()). El valor por defecto es "year".

Nuevo en la versión 3.7.

Nótese que aunque la denominación de los atributos de clase descritos anteriormente es singular (por ejemplo, cssclass_month cssclass_noday), uno puede reemplazar la clase CSS única con una lista de clases CSS separadas por espacios, por ejemplo:

"text-bold text-red"

Aquí hay un ejemplo de cómo HTMLCalendar puede ser personalizado:

class CustomHTMLCal(calendar.HTMLCalendar):
    cssclasses = [style + " text-nowrap" for style in
                  calendar.HTMLCalendar.cssclasses]
    cssclass_month_head = "text-center month-head"
    cssclass_month = "text-center month"
    cssclass_year = "text-italic lead"

class calendar.LocaleTextCalendar(firstweekday=0, locale=None)

Esta subclase de TextCalendar se le puede pasar un nombre de configuración regional en el constructor y retornará los nombres de los meses y días de la semana en la configuración regional especificada. Si esta configuración regional incluye una codificación, todas las cadenas que contengan los nombres de los meses y días de la semana serán retornadas como Unicode.

class calendar.LocaleHTMLCalendar(firstweekday=0, locale=None)

Esta subclase de TextCalendar se le puede pasar un nombre de configuración regional en el constructor y retornará los nombres de los meses y días de la semana en la configuración regional especificada. Si esta configuración regional incluye una codificación, todas las cadenas que contengan los nombres de los meses y días de la semana serán retornadas como Unicode.

Nota

Los métodos formatweekday() y formatmonthname() de estas dos clases cambian temporalmente la configuración regional actual al locale dado. Debido a que la configuración regional actual es un ajuste de todo el proceso, no son seguros para los hilos.

Para los calendarios de texto simples este módulo proporciona las siguientes funciones.

calendar.setfirstweekday(weekday)

Establece el día de la semana (el 0 es el lunes, el 6 es el domingo) para empezar cada semana. Los valores MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, y SUNDAY se proporcionan por conveniencia. Por ejemplo, para fijar el primer día de la semana en domingo:

import calendar
calendar.setfirstweekday(calendar.SUNDAY)

calendar.firstweekday()

Retorna la configuración actual para el día de la semana para empezar cada semana.

calendar.isleap(year)

Retorna True si year es un año bisiesto, si no False.

calendar.leapdays(y1, y2)

Retorna el número de años bisiestos en el rango de y1 a y2 (exclusivo), donde y1 y y2 son años.

Esta función opera para rangos que abarcan un cambio de siglo.

calendar.weekday(year, month, day)

Retorna el día de la semana (0 es lunes) para year (1970`--...), *month* (``1–12), day (1–31).

calendar.weekheader(n)

Retorna un encabezado con nombres abreviados de los días de la semana. n especifica el ancho en caracteres de un día de la semana.

calendar.monthrange(year, month)

Retorna el día de la semana del primer día del mes y el número de días del mes, para el year y month especificados.

calendar.monthcalendar(year, month)

Retorna una matriz que representa el calendario de un mes. Cada fila representa una semana; los días fuera del mes se representan con ceros. Cada semana comienza con el lunes a menos que lo establezca setfirstweekday().

calendar.prmonth(theyear, themonth, w=0, l=0)

Imprime el calendario de un mes según lo retorna month().

calendar.month(theyear, themonth, w=0, l=0)

Retorna el calendario de un mes en una cadena de varias líneas usando el formatmonth() de la clase TextCalendar.

calendar.prcal(year, w=0, l=0, c=6, m=3)

Imprime el calendario de todo un año como lo retorna calendar().

calendar.calendar(year, w=2, l=1, c=6, m=3)

Retorna un calendario de 3 columnas para un año entero como una cadena de varias líneas usando el formatyear() de la clase TextCalendar.

calendar.timegm(tuple)

Una función no relacionada pero útil que toma una tupla de tiempo como la retornada por la función gmtime() en el módulo time, y retorna el valor correspondiente a la marca de tiempo (timestamp) Unix, asumiendo una época de 1970, y la codificación POSIX. De hecho, time.gmtime() y timegm() son el inverso de cada uno de ellos.

El módulo calendar exporta los siguientes atributos de datos:

calendar.day_name

Un arreglo que representa los días de la semana en la configuración regional actual.

calendar.day_abbr

Un vector que representa los días abreviados de la semana en la configuración regional actual.

calendar.month_name

Un vector que representa los meses del año en la configuración regional actual. Esto sigue la convención normal de que enero es el mes número 1, por lo que tiene una longitud de 13 y month_name[0] es la cadena vacía.

calendar.month_abbr

Una matriz que representa los meses abreviados del año en la configuración regional actual. Esto sigue la convención normal de que enero es el mes número 1, por lo que tiene una longitud de 13 y month_abbr[0] es la cadena vacía.

Ver también

Módulo datetime

Interfaz orientada a objetos para fechas y horas con una funcionalidad similar a la del módulo time.

Módulo time

Funciones de bajo nivel relacionadas con el tiempo.

collections — Tipos de datos contenedor

Source code: Lib/collections/__init__.py [https://github.com/python/cpython/tree/3.9/Lib/collections/__init__.py]

Este módulo implementa tipos de datos de contenedores especializados que proporcionan alternativas a los contenedores integrados de uso general de Python, dict, list, set, and tuple.

namedtuple()

función factory para crear subclases de tuplas con campos con nombre

deque

contenedor similar a una lista con appends y pops rápidos en ambos extremos

ChainMap

clase similar a dict para crear una vista única de múltiples mapeados

Counter

subclase de dict para contar objetos hashables

OrderedDict

subclase de dict que recuerda las entradas de la orden que se agregaron

defaultdict

subclase de dict que llama a una función de factory para suministrar valores faltantes

UserDict

envoltura alrededor de los objetos de diccionario para facilitar subclasificaciones dict

UserList

envoltura alrededor de los objetos de lista para facilitar la subclasificación de un list

UserString

envoltura alrededor de objetos de cadena para facilitar la subclasificación de string

Deprecated since version 3.3, will be removed in version 3.10: Trasladado Colecciones Clases Base Abstractas al modulo collections.abc. Para compatibilidad hacia atrás, continúan siendo visibles en este módulo a través de Python 3.9.

Objetos ChainMap

Nuevo en la versión 3.3.

Una clase ChainMap se proporciona para vincular rápidamente una serie de mappings de modo que puedan tratarse como una sola unidad. Suele ser mucho más rápido que crear un diccionario nuevo y ejecutar varias llamadas a update().

La clase se puede utilizar para simular ámbitos anidados y es útil para crear plantillas.

class collections.ChainMap(*maps)

Un ChainMap agrupa varios diccionarios u otros mappings para crear una vista única y actualizable. Si no se especifican maps, se proporciona un solo diccionario vacío para que una nueva cadena siempre tenga al menos un mapeo.

Las asignaciones subyacentes se almacenan en una lista. Esa lista es pública y se puede acceder a ella o actualizarla usando el atributo maps. No hay otro estado.

Las búsquedas buscan los mapeos subyacentes sucesivamente hasta que se encuentra una clave. Por el contrario, las escrituras, actualizaciones y eliminaciones solo operan en el primer mapeo.

Un ChainMap incorpora los mapeos subyacentes por referencia. Entonces, si una de los mapeos subyacentes se actualiza, esos cambios se reflejarán en ChainMap.

Se admiten todos los métodos habituales de un diccionario. Además, hay un atributo maps, un método para crear nuevos sub contextos y una propiedad para acceder a todos menos al primer mapeo:

maps

Una lista de mapeos actualizable por el usuario. La lista está ordenada desde la primera búsqueda hasta la última búsqueda. Es el único estado almacenado y se puede modificar para cambiar los mapeos que se buscan. La lista siempre debe contener al menos un mapeo.

new_child(m=None)

Retorna un nuevo ChainMap conteniendo un nuevo mapa seguido de todos los mapas de la instancia actual. Si se especifica m, se convierte en el nuevo mapa al principio de la lista de asignaciones; si no se especifica, se usa un dict vacío, de modo que una llamada a d.new_child() es equivalente a: ChainMap({}, *d.maps). Este método se utiliza para crear sub contextos que se pueden actualizar sin alterar los valores en ninguna de los mapeos padre.

Distinto en la versión 3.4: Se agregó el parámetro opcional m .

parents

Propiedad que retorna un nuevo ChainMap conteniendo todos los mapas de la instancia actual excepto el primero. Esto es útil para omitir el primer mapa en la búsqueda. Los casos de uso son similares a los de nonlocal la palabra clave usada en alcances anidados. Los casos de uso también son paralelos a los de la función incorporada super(). Una referencia a d.parents es equivalente a: ChainMap(*d.maps[1:]).

Tenga en cuenta que el orden de iteración de a ChainMap() se determina escaneando los mapeos del último al primero:

>>> baseline = {'music': 'bach', 'art': 'rembrandt'}
>>> adjustments = {'art': 'van gogh', 'opera': 'carmen'}
>>> list(ChainMap(adjustments, baseline))
['music', 'art', 'opera']

Esto da el mismo orden que una serie de llamadas a dict.update() comenzando con el último mapeo:

>>> combined = baseline.copy()
>>> combined.update(adjustments)
>>> list(combined)
['music', 'art', 'opera']

Distinto en la versión 3.9: Se agregó soporte para los operadores | y |=, especificados en PEP 584 [https://www.python.org/dev/peps/pep-0584].

Ver también

La clase MultiContext [https://github.com/enthought/codetools/blob/4.0.0/codetools/contexts/multi_context.py] en el paquete de Enthought llamado CodeTools [https://github.com/enthought/codetools] tiene opciones para admitir la escritura en cualquier mapeo de la cadena.

La clase de Django Context [https://github.com/django/django/blob/master/django/template/context.py] para crear plantillas es una cadena de mapeo de solo lectura. También presenta características de pushing y popping de contextos similar al método new_child() y a la propiedad parents .

La receta de Contextos Anidados [https://code.activestate.com/recipes/577434/] tiene opciones para controlar si las escrituras y otras mutaciones se aplican solo al primer mapeo o a cualquier mapeo en la cadena.

Una versión de solo lectura muy simplificada de Chainmap [https://code.activestate.com/recipes/305268/].

Ejemplos y recetas ChainMap

Esta sección muestra varios enfoques para trabajar con mapas encadenados.

Ejemplo de simulación de la cadena de búsqueda interna de Python:

import builtins
pylookup = ChainMap(locals(), globals(), vars(builtins))

Ejemplo de dejar que los argumentos de la línea de comandos especificados por el usuario tengan prioridad sobre las variables de entorno que, a su vez, tienen prioridad sobre los valores predeterminados:

import os, argparse

defaults = {'color': 'red', 'user': 'guest'}

parser = argparse.ArgumentParser()
parser.add_argument('-u', '--user')
parser.add_argument('-c', '--color')
namespace = parser.parse_args()
command_line_args = {k: v for k, v in vars(namespace).items() if v is not None}

combined = ChainMap(command_line_args, os.environ, defaults)
print(combined['color'])
print(combined['user'])

Patrones de ejemplo para usar la clase ChainMap para simular contextos anidados:

c = ChainMap()        # Create root context
d = c.new_child()     # Create nested child context
e = c.new_child()     # Child of c, independent from d
e.maps[0]             # Current context dictionary -- like Python's locals()
e.maps[-1]            # Root context -- like Python's globals()
e.parents             # Enclosing context chain -- like Python's nonlocals

d['x'] = 1            # Set value in current context
d['x']                # Get first key in the chain of contexts
del d['x']            # Delete from current context
list(d)               # All nested values
k in d                # Check all nested values
len(d)                # Number of nested values
d.items()             # All nested items
dict(d)               # Flatten into a regular dictionary

La clase ChainMap solo realiza actualizaciones (escrituras y eliminaciones) en el primer mapeo de la cadena, mientras que las búsquedas buscarán en la cadena completa. Sin embargo, si se desean escrituras y eliminaciones profundas, es fácil crear una subclase que actualice las llaves que se encuentran más profundas en la cadena:

class DeepChainMap(ChainMap):
    'Variant of ChainMap that allows direct updates to inner scopes'

    def __setitem__(self, key, value):
        for mapping in self.maps:
            if key in mapping:
                mapping[key] = value
                return
        self.maps[0][key] = value

    def __delitem__(self, key):
        for mapping in self.maps:
            if key in mapping:
                del mapping[key]
                return
        raise KeyError(key)

>>> d = DeepChainMap({'zebra': 'black'}, {'elephant': 'blue'}, {'lion': 'yellow'})
>>> d['lion'] = 'orange'         # update an existing key two levels down
>>> d['snake'] = 'red'           # new keys get added to the topmost dict
>>> del d['elephant']            # remove an existing key one level down
>>> d                            # display result
DeepChainMap({'zebra': 'black', 'snake': 'red'}, {}, {'lion': 'orange'})

Objetos Counter

Se proporciona una herramienta de contador para respaldar recuentos rápidos y convenientes. Por ejemplo:

>>> # Tally occurrences of words in a list
>>> cnt = Counter()
>>> for word in ['red', 'blue', 'red', 'green', 'blue', 'blue']:
...     cnt[word] += 1
>>> cnt
Counter({'blue': 3, 'red': 2, 'green': 1})

>>> # Find the ten most common words in Hamlet
>>> import re
>>> words = re.findall(r'\w+', open('hamlet.txt').read().lower())
>>> Counter(words).most_common(10)
[('the', 1143), ('and', 966), ('to', 762), ('of', 669), ('i', 631),
 ('you', 554),  ('a', 546), ('my', 514), ('hamlet', 471), ('in', 451)]

class collections.Counter([iterable-or-mapping])

Una clase Counter es una subclase dict para contar objetos hashables. Es una colección donde los elementos se almacenan como llaves de diccionario y sus conteos se almacenan como valores de diccionario. Se permite que los conteos sean cualquier valor entero, incluidos los conteos de cero o negativos. La clase Counter es similar a los bags o multiconjuntos en otros idiomas.

Los elementos se cuentan desde un iterable o se inicializan desde otro mapeo (o contador):

>>> c = Counter()                           # a new, empty counter
>>> c = Counter('gallahad')                 # a new counter from an iterable
>>> c = Counter({'red': 4, 'blue': 2})      # a new counter from a mapping
>>> c = Counter(cats=4, dogs=8)             # a new counter from keyword args

Los objetos Counter tienen una interfaz de diccionario, excepto que retornan un conteo de cero para los elementos faltantes en lugar de levantar una KeyError:

>>> c = Counter(['eggs', 'ham'])
>>> c['bacon']                              # count of a missing element is zero
0

Establecer un conteo en cero no elimina un elemento de un contador. Utilice del para eliminarlo por completo:

>>> c['sausage'] = 0                        # counter entry with a zero count
>>> del c['sausage']                        # del actually removes the entry

Nuevo en la versión 3.1.

Distinto en la versión 3.7: Como subclase de dict , Counter heredó la capacidad de recordar el orden de inserción. Las operaciones matemáticas en objetos Counter también preserva el orden. Los resultados se ordenan cuando se encuentra un elemento por primera vez en el operando izquierdo y luego según el orden encontrado en el operando derecho.

Counter objects support additional methods beyond those available for all dictionaries:

elements()

Retorna un iterador sobre los elementos que se repiten tantas veces como su conteo. Los elementos se retornan en el orden en que se encontraron por primera vez. Si el conteo de un elemento es menor que uno, elements() lo ignorará.

>>> c = Counter(a=4, b=2, c=0, d=-2)
>>> sorted(c.elements())
['a', 'a', 'a', 'a', 'b', 'b']

most_common([n])

Retorna una lista de los n elementos mas comunes y sus conteos, del mas común al menos común. Si se omite n o None, most_common() retorna todos los elementos del contador. Los elementos con conteos iguales se ordenan en el orden en que se encontraron por primera vez:

>>> Counter('abracadabra').most_common(3)
[('a', 5), ('b', 2), ('r', 2)]

subtract([iterable-or-mapping])

Los elementos se restan de un iterable o de otro mapeo (o contador). Como dict.update() pero resta los conteos en lugar de reemplazarlos. Tanto las entradas como las salidas pueden ser cero o negativas.

>>> c = Counter(a=4, b=2, c=0, d=-2)
>>> d = Counter(a=1, b=2, c=3, d=4)
>>> c.subtract(d)
>>> c
Counter({'a': 3, 'b': 0, 'c': -3, 'd': -6})

Nuevo en la versión 3.2.

Los métodos de diccionario habituales están disponibles para objetos Counter excepto dos que funcionan de manera diferente para los contadores.

fromkeys(iterable)

Este método de clase no está implementado para objetos Counter .

update([iterable-or-mapping])

Los elementos se cuentan desde un iterable o agregados desde otro mapeo (o contador). Como dict.update() pero agrega conteos en lugar de reemplazarlos. Además, se espera que el iterable sea una secuencia de elementos, no una secuencia de parejas (llave, valor) .

Patrones comunes para trabajar con objetos Counter:

sum(c.values())                 # total of all counts
c.clear()                       # reset all counts
list(c)                         # list unique elements
set(c)                          # convert to a set
dict(c)                         # convert to a regular dictionary
c.items()                       # convert to a list of (elem, cnt) pairs
Counter(dict(list_of_pairs))    # convert from a list of (elem, cnt) pairs
c.most_common()[:-n-1:-1]       # n least common elements
+c                              # remove zero and negative counts

Se proporcionan varias operaciones matemáticas para combinar objetos Counter para producir multiconjuntos (contadores que tienen conteos mayores que cero). La suma y la resta combinan contadores sumando o restando los conteos de los elementos correspondientes. La Intersección y unión retornan el mínimo y el máximo de conteos correspondientes. Cada operación puede aceptar entradas con conteos con signo, pero la salida excluirá los resultados con conteos de cero o menos.

>>> c = Counter(a=3, b=1)
>>> d = Counter(a=1, b=2)
>>> c + d                       # add two counters together:  c[x] + d[x]
Counter({'a': 4, 'b': 3})
>>> c - d                       # subtract (keeping only positive counts)
Counter({'a': 2})
>>> c & d                       # intersection:  min(c[x], d[x])
Counter({'a': 1, 'b': 1})
>>> c | d                       # union:  max(c[x], d[x])
Counter({'a': 3, 'b': 2})

La suma y resta unaria son atajos para agregar un contador vacío o restar de un contador vacío.

>>> c = Counter(a=2, b=-4)
>>> +c
Counter({'a': 2})
>>> -c
Counter({'b': 4})

Nuevo en la versión 3.3: Se agregó soporte para operaciones unarias de adición, resta y multiconjunto en su lugar (in-place).

Nota

Los Counters se diseñaron principalmente para trabajar con números enteros positivos para representar conteos continuos; sin embargo, se tuvo cuidado de no excluir innecesariamente los casos de uso que necesitan otros tipos o valores negativos. Para ayudar con esos casos de uso, esta sección documenta el rango mínimo y las restricciones de tipo.

La clase Counter en sí misma es una subclase de diccionario sin restricciones en sus llaves y valores. Los valores están pensados para ser números que representan conteos, pero podría almacenar cualquier cosa en el campo de valor.

El método most_common() solo requiere que los valores se puedan ordenar.

Para operaciones en su lugar (in-place) como c[key] += 1, el tipo de valor solo necesita admitir la suma y la resta. Por lo tanto, las fracciones, flotantes y decimales funcionarían y se admiten valores negativos. Lo mismo ocurre con update() y subtract() que permiten valores negativos y cero para las entradas y salidas.

Los métodos de multiconjuntos están diseñados solo para casos de uso con valores positivos. Las entradas pueden ser negativas o cero, pero solo se crean salidas con valores positivos. No hay restricciones de tipo, pero el tipo de valor debe admitir la suma, la resta y la comparación.

El método elements() requiere conteos enteros. Ignora los conteos de cero y negativos.

Ver también

Clase Bag [https://www.gnu.org/software/smalltalk/manual-base/html_node/Bag.html] en Smalltalk.

Entrada de Wikipedia para Multiconjuntos [https://es.wikipedia.org/wiki/Multiconjunto].

Tutorial de multiconjuntos de C++ [http://www.java2s.com/Tutorial/Cpp/0380__set-multiset/Catalog0380__set-multiset.htm] con ejemplos.

Para operaciones matemáticas en multiconjuntos y sus casos de uso, consulte Knuth, Donald. The Art of Computer Programming Volume II, Sección 4.6.3, Ejercicio 19.

Para enumerar todos los distintos multiconjuntos de un tamaño dado sobre un conjunto dado de elementos, consulte itertools.combinations_with_replacement():

map(Counter, combinations_with_replacement('ABC', 2)) # --> AA AB AC BB BC CC

Objetos deque

class collections.deque([iterable[, maxlen]])

Retorna un nuevo objeto deque inicializado de izquierda a derecha (usando append()) con datos de iterable. Si no se especifica iterable, el nuevo deque estará vacío.

Los deques son una generalización de pilas y colas (el nombre se pronuncia “baraja”, deck en inglés, y es la abreviatura de “cola de dos extremos”, double-ended queue en inglés). Los Deques admiten hilos seguros, appends y pops eficientes en memoria desde cualquier lado del deque con aproximadamente el mismo rendimiento O(1) en cualquier dirección.

Aunque los objetos list admiten operaciones similares, están optimizados para operaciones rápidas de longitud fija e incurren en costos de movimiento de memoria O(n) para operaciones pop(0) y insert(0, v) que cambian tanto el tamaño como la posición de la representación de datos subyacente.

Si no se especifica maxlen o es None, los deques pueden crecer hasta una longitud arbitraria. De lo contrario, el deque está limitado a la longitud máxima especificada. Una vez que un deque de longitud limitada esta lleno, cuando se agregan nuevos elementos, se descarta el número correspondiente de elementos del extremo opuesto. Los deques de longitud limitada proporcionan una funcionalidad similar al filtro tail en Unix. También son útiles para rastrear transacciones y otros grupos de datos donde solo la actividad más reciente es de interés.

Los objetos deque admiten los siguientes métodos:

append(x)

Agregue x al lado derecho del deque.

appendleft(x)

Agregue x al lado izquierdo del deque.

clear()

Retire todos los elementos del deque dejándolo con longitud 0.

copy()

Crea una copia superficial del deque.

Nuevo en la versión 3.5.

count(x)

Cuente el número de elementos deque igual a x.

Nuevo en la versión 3.2.

extend(iterable)

Extienda el lado derecho del deque agregando elementos del argumento iterable.

extendleft(iterable)

Extienda el lado izquierdo del deque agregando elementos de iterable. Tenga en cuenta que la serie de appends a la izquierda da como resultado la inversión del orden de los elementos en el argumento iterable.

index(x[, start[, stop]])

Retorna la posición de x en el deque (en o después del índice start y antes del índice stop). Retorna la primera coincidencia o lanza ValueError si no se encuentra.

Nuevo en la versión 3.5.

insert(i, x)

Ingrese x en el dique en la posición i.

Si la inserción causara que un deque limitado crezca más allá de maxlen, se lanza un IndexError.

Nuevo en la versión 3.5.

pop()

Elimina y retorna un elemento del lado derecho del deque. Si no hay elementos presentes, lanza un IndexError.

popleft()

Elimina y retorna un elemento del lado izquierdo del deque. Si no hay elementos presentes, lanza un IndexError.

remove(value)

Elimina la primera aparición de value. Si no se encuentra, lanza un ValueError.

reverse()

Invierte los elementos del deque en su lugar (in-place) y luego retorna None.

Nuevo en la versión 3.2.

rotate(n=1)

Gira el deque n pasos a la derecha. Si n es negativo, lo gira hacia la izquierda.

Cuando el deque no está vacío, girar un paso hacia la derecha equivale a d.appendleft(d.pop()), y girar un paso hacia la izquierda equivale a d.append(d.popleft()).

Los objetos deque también proporcionan un atributo de solo lectura:

maxlen

Tamaño máximo de un deque o None si no está limitado.

Nuevo en la versión 3.1.

Además de lo anterior, los deques admiten iteración, pickling, len(d), reversed(d), copy.copy(d), copy.deepcopy(d), prueba de pertenencia con el operador in , y referencias de subíndices como d[0] para acceder al primer elemento. El acceso indexado es O(1) en ambos extremos, pero se ralentiza hasta O(n) en el medio. Para un acceso aleatorio rápido, use listas en su lugar.

A partir de la versión 3.5, los deques admiten __add__(), __mul__(), y __imul__().

Ejemplo:

>>> from collections import deque
>>> d = deque('ghi')                 # make a new deque with three items
>>> for elem in d:                   # iterate over the deque's elements
...     print(elem.upper())
G
H
I

>>> d.append('j')                    # add a new entry to the right side
>>> d.appendleft('f')                # add a new entry to the left side
>>> d                                # show the representation of the deque
deque(['f', 'g', 'h', 'i', 'j'])

>>> d.pop()                          # return and remove the rightmost item
'j'
>>> d.popleft()                      # return and remove the leftmost item
'f'
>>> list(d)                          # list the contents of the deque
['g', 'h', 'i']
>>> d[0]                             # peek at leftmost item
'g'
>>> d[-1]                            # peek at rightmost item
'i'

>>> list(reversed(d))                # list the contents of a deque in reverse
['i', 'h', 'g']
>>> 'h' in d                         # search the deque
True
>>> d.extend('jkl')                  # add multiple elements at once
>>> d
deque(['g', 'h', 'i', 'j', 'k', 'l'])
>>> d.rotate(1)                      # right rotation
>>> d
deque(['l', 'g', 'h', 'i', 'j', 'k'])
>>> d.rotate(-1)                     # left rotation
>>> d
deque(['g', 'h', 'i', 'j', 'k', 'l'])

>>> deque(reversed(d))               # make a new deque in reverse order
deque(['l', 'k', 'j', 'i', 'h', 'g'])
>>> d.clear()                        # empty the deque
>>> d.pop()                          # cannot pop from an empty deque
Traceback (most recent call last):
    File "<pyshell#6>", line 1, in -toplevel-
        d.pop()
IndexError: pop from an empty deque

>>> d.extendleft('abc')              # extendleft() reverses the input order
>>> d
deque(['c', 'b', 'a'])

Recetas deque

Esta sección muestra varios enfoques para trabajar con deques.

Los deques de longitud limitada proporcionan una funcionalidad similar al filtro tail en Unix:

def tail(filename, n=10):
    'Return the last n lines of a file'
    with open(filename) as f:
        return deque(f, n)

Otro enfoque para usar deques es mantener una secuencia de elementos agregados recientemente haciendo appending a la derecha y popping a la izquierda:

def moving_average(iterable, n=3):
    # moving_average([40, 30, 50, 46, 39, 44]) --> 40.0 42.0 45.0 43.0
    # http://en.wikipedia.org/wiki/Moving_average
    it = iter(iterable)
    d = deque(itertools.islice(it, n-1))
    d.appendleft(0)
    s = sum(d)
    for elem in it:
        s += elem - d.popleft()
        d.append(elem)
        yield s / n

Un scheduler round-robin [https://en.wikipedia.org/wiki/Round-robin_scheduling] se puede implementar con iteradores de entrada almacenados en deque. Los valores son producidos del iterador activo en la posición cero. Si ese iterador está agotado, se puede eliminar con popleft(); de lo contrario, se puede volver en ciclos al final con el método rotate()

def roundrobin(*iterables):
    "roundrobin('ABC', 'D', 'EF') --> A D E B F C"
    iterators = deque(map(iter, iterables))
    while iterators:
        try:
            while True:
                yield next(iterators[0])
                iterators.rotate(-1)
        except StopIteration:
            # Remove an exhausted iterator.
            iterators.popleft()

El método rotate() proporciona una forma de implementar eliminación y rebanado de deque. Por ejemplo, una implementación pura de Python de del d[n] se basa en el método rotate() para colocar los elementos que se van a extraer:

def delete_nth(d, n):
    d.rotate(-n)
    d.popleft()
    d.rotate(n)

Para implementar el rebanado de un deque, use un enfoque similar aplicando rotate() para traer un elemento objetivo al lado izquierdo del deque. Elimine las entradas antiguas con popleft(), agregue nuevas entradas con extend(), y luego invierta la rotación. Con variaciones menores en ese enfoque, es fácil implementar manipulaciones de pila de estilo hacia adelante como dup, drop, swap, over, pick, rot, y roll.

Objetos defaultdict

class collections.defaultdict(default_factory=None, /[, ...])

Return a new dictionary-like object. defaultdict is a subclass of the built-in dict class. It overrides one method and adds one writable instance variable. The remaining functionality is the same as for the dict class and is not documented here.

El primer argumento proporciona el valor inicial para el atributo default_factory; por defecto es None. Todos los argumentos restantes se tratan de la misma forma que si se pasaran al constructor dict, incluidos los argumentos de palabras clave.

Los objetos defaultdict admiten el siguiente método además de las operaciones estándar de dict:

__missing__(key)

Si el atributo default_factory es None, lanza una excepción KeyError con la llave como argumento.

Si default_factory no es None, se llama sin argumentos para proporcionar un valor predeterminado para la llave dada, este valor se inserta en el diccionario para la llave y se retorna.

Si llamar a default_factory lanza una excepción, esta excepción se propaga sin cambios.

Este método es llamado por el método __getitem__() de la clase dict cuando no se encuentra la llave solicitada; todo lo que retorna o lanza es retornado o lanzado por __getitem__().

Tenga en cuenta que __missing__() no se llama para ninguna operación aparte de __getitem__(). Esto significa que get(), como los diccionarios normales, retornará None por defecto en lugar de usar default_factory.

los objetos defaultdict admiten la siguiente variable de instancia:

default_factory

Este atributo es utilizado por el método __missing__() ; se inicializa desde el primer argumento al constructor, si está presente, o en None, si está ausente.

Distinto en la versión 3.9: Se agregaron los operadores unir (|) y actualizar (|=), especificados en PEP 584 [https://www.python.org/dev/peps/pep-0584].

Ejemplos defaultdict

Usando list como default_factory, es fácil agrupar una secuencia de pares llave-valor en un diccionario de listas:

>>> s = [('yellow', 1), ('blue', 2), ('yellow', 3), ('blue', 4), ('red', 1)]
>>> d = defaultdict(list)
>>> for k, v in s:
...     d[k].append(v)
...
>>> sorted(d.items())
[('blue', [2, 4]), ('red', [1]), ('yellow', [1, 3])]

Cuando se encuentra cada llave por primera vez, no está ya en el mapping; por lo que una entrada se crea automáticamente usando la función default_factory que retorna una list vacía. La operación list.append() luego adjunta el valor a la nueva lista. Cuando se vuelven a encontrar llaves, la búsqueda procede normalmente (retornando la lista para esa llave) y la operación list.append() agrega otro valor a la lista. Esta técnica es más simple y rápida que una técnica equivalente usando dict.setdefault():

>>> d = {}
>>> for k, v in s:
...     d.setdefault(k, []).append(v)
...
>>> sorted(d.items())
[('blue', [2, 4]), ('red', [1]), ('yellow', [1, 3])]

Establecer default_factory en int hace que defaultdict sea útil para contar (como un bag o multiconjunto en otros idiomas):

>>> s = 'mississippi'
>>> d = defaultdict(int)
>>> for k in s:
...     d[k] += 1
...
>>> sorted(d.items())
[('i', 4), ('m', 1), ('p', 2), ('s', 4)]

Cuando se encuentra una letra por primera vez, falta en el mapping, por lo que la función default_factory llama a int() para proporcionar una cuenta predeterminada de cero. La operación de incremento luego acumula el conteo de cada letra.

La función int() que siempre retorna cero es solo un caso especial de funciones constantes. Una forma más rápida y flexible de crear funciones constantes es utilizar una función lambda que pueda proporcionar cualquier valor constante (no solo cero):

>>> def constant_factory(value):
...     return lambda: value
>>> d = defaultdict(constant_factory('<missing>'))
>>> d.update(name='John', action='ran')
>>> '%(name)s %(action)s to %(object)s' % d
'John ran to <missing>'

Establecer default_factory en set hace que defaultdict sea útil para construir un diccionario de conjuntos:

>>> s = [('red', 1), ('blue', 2), ('red', 3), ('blue', 4), ('red', 1), ('blue', 4)]
>>> d = defaultdict(set)
>>> for k, v in s:
...     d[k].add(v)
...
>>> sorted(d.items())
[('blue', {2, 4}), ('red', {1, 3})]

namedtuple() Funciones Factory para Tuplas y Campos con Nombres

Las tuplas con nombre asignan significado a cada posición en una tupla y permiten un código más legible y autodocumentado. Se pueden usar donde se usen tuplas regulares y agregan la capacidad de acceder a los campos por nombre en lugar del índice de posición.

collections.namedtuple(typename, field_names, *, rename=False, defaults=None, module=None)

Retorna una nueva subclase de tupla llamada typename. La nueva subclase se utiliza para crear objetos tipo tupla que tienen campos accesibles mediante búsqueda de atributos, además de ser indexables e iterables. Las instancias de la subclase también tienen un docstring útil (con typename y field_names) y un método útil __repr__() que lista el contenido de la tupla en un formato de nombre=valor.

Los nombres de campo son una secuencia de cadenas como [‘x’, ‘y’]. Alternativamente, nombres de campo puede ser una sola cadena con cada nombre de campo separado por espacios en blanco y/o comas, por ejemplo ’x y’ or ’x, y’.

Se puede usar cualquier identificador de Python válido para un fieldname, excepto para los nombres que comienzan con un guión bajo. Los identificadores válidos constan de letras, dígitos y guiones bajos, pero no comienzan con un dígito o guion bajo y no pueden ser keyword como class, for, return, global, pass, o raise.

Si rename es verdadero, los nombres de campo no válidos se reemplazan automáticamente con nombres posicionales. Por ejemplo, [‘abc’, ‘def’, ‘ghi’, ‘abc’] se convierte en [‘abc’, ‘_1’, ‘ghi’, ‘_3’], eliminando la palabra clave def y el nombre de campo duplicado abc.

defaults pueden ser None o un iterable de los valores predeterminados. Dado que los campos con un valor predeterminado deben venir después de cualquier campo sin un valor predeterminado, los defaults se aplican a los parámetros situados más a la derecha. Por ejemplo, si los nombres de campo son [‘x’, ‘y’, ‘z’]``y los valores predeterminados son ``(1, 2), entonces x será un argumento obligatorio, y tendrá el valor predeterminado de 1, y z el valor predeterminado de 2.

Si se define module, el atributo __module__ de la tupla nombrada se establece en ese valor.

Las instancias de tuplas con nombre no tienen diccionarios por instancia, por lo que son livianas y no requieren más memoria que las tuplas normales.

Para admitir el serializado (pickling), la clase tupla con nombre debe asignarse a una variable que coincida con typename.

Distinto en la versión 3.1: Se agregó soporte para rename.

Distinto en la versión 3.6: Los parámetros verbose y rename se convirtieron en argumentos de solo palabra clave.

Distinto en la versión 3.6: Se agregó el parámetro module.

Distinto en la versión 3.7: Se eliminaron el parámetro verbose y el atributo _source.

Distinto en la versión 3.7: Se agregaron el parámetro defaults y él atributo _field_defaults.

>>> # Basic example
>>> Point = namedtuple('Point', ['x', 'y'])
>>> p = Point(11, y=22)     # instantiate with positional or keyword arguments
>>> p[0] + p[1]             # indexable like the plain tuple (11, 22)
33
>>> x, y = p                # unpack like a regular tuple
>>> x, y
(11, 22)
>>> p.x + p.y               # fields also accessible by name
33
>>> p                       # readable __repr__ with a name=value style
Point(x=11, y=22)

Las tuplas con nombre son especialmente útiles para asignar nombres de campo a las tuplas de resultado retornadas por los módulos csv o sqlite3:

EmployeeRecord = namedtuple('EmployeeRecord', 'name, age, title, department, paygrade')

import csv
for emp in map(EmployeeRecord._make, csv.reader(open("employees.csv", "rb"))):
    print(emp.name, emp.title)

import sqlite3
conn = sqlite3.connect('/companydata')
cursor = conn.cursor()
cursor.execute('SELECT name, age, title, department, paygrade FROM employees')
for emp in map(EmployeeRecord._make, cursor.fetchall()):
    print(emp.name, emp.title)

Además de los métodos heredados de las tuplas, las tuplas con nombre admiten tres métodos adicionales y dos atributos. Para evitar conflictos con los nombres de campo, los nombres de método y atributo comienzan con un guión bajo.

classmethod somenamedtuple._make(iterable)

Método de clase que crea una nueva instancia a partir de una secuencia existente o iterable.

>>> t = [11, 22]
>>> Point._make(t)
Point(x=11, y=22)

somenamedtuple._asdict()

Retorna un nuevo dict que asigna los nombres de los campos a sus valores correspondientes:

>>> p = Point(x=11, y=22)
>>> p._asdict()
{'x': 11, 'y': 22}

Distinto en la versión 3.1: Retorna un OrderedDict en lugar de un dict regular.

Distinto en la versión 3.8: Retorna un dict normal en lugar de un OrderedDict. A partir de Python 3.7, se garantiza el orden de los diccionarios normales. Si se requieren las características adicionales de OrderedDict , la corrección sugerida es emitir el resultado al tipo deseado: OrderedDict(nt._asdict()).

somenamedtuple._replace(**kwargs)

Retorna una nueva instancia de la tupla nombrada reemplazando los campos especificados con nuevos valores:

>>> p = Point(x=11, y=22)
>>> p._replace(x=33)
Point(x=33, y=22)

>>> for partnum, record in inventory.items():
...     inventory[partnum] = record._replace(price=newprices[partnum], timestamp=time.now())

somenamedtuple._fields

Tupla de cadenas que lista los nombres de los campos. Útil para la introspección y para crear nuevos tipos de tuplas con nombre a partir de tuplas con nombre existentes.

>>> p._fields            # view the field names
('x', 'y')

>>> Color = namedtuple('Color', 'red green blue')
>>> Pixel = namedtuple('Pixel', Point._fields + Color._fields)
>>> Pixel(11, 22, 128, 255, 0)
Pixel(x=11, y=22, red=128, green=255, blue=0)

somenamedtuple._field_defaults

Diccionario de nombres de campos mapeados a valores predeterminados.

>>> Account = namedtuple('Account', ['type', 'balance'], defaults=[0])
>>> Account._field_defaults
{'balance': 0}
>>> Account('premium')
Account(type='premium', balance=0)

Para recuperar un campo cuyo nombre está almacenado en una cadena, use la función getattr():

>>> getattr(p, 'x')
11

Para convertir un diccionario en una tupla con nombre, use el operador de doble estrella (como se describe en Desempaquetando una lista de argumentos):

>>> d = {'x': 11, 'y': 22}
>>> Point(**d)
Point(x=11, y=22)

Dado que una tupla con nombre es una clase Python normal, es fácil agregar o cambiar la funcionalidad con una subclase. A continuación, se explica cómo agregar un campo calculado y un formato de impresión de ancho fijo:

>>> class Point(namedtuple('Point', ['x', 'y'])):
...     __slots__ = ()
...     @property
...     def hypot(self):
...         return (self.x ** 2 + self.y ** 2) ** 0.5
...     def __str__(self):
...         return 'Point: x=%6.3f  y=%6.3f  hypot=%6.3f' % (self.x, self.y, self.hypot)

>>> for p in Point(3, 4), Point(14, 5/7):
...     print(p)
Point: x= 3.000  y= 4.000  hypot= 5.000
Point: x=14.000  y= 0.714  hypot=14.018

La subclase que se muestra arriba establece __slots__ a una tupla vacía. Esto ayuda a mantener bajos los requisitos de memoria al evitar la creación de diccionarios de instancia.

La subclasificación no es útil para agregar campos nuevos almacenados. En su lugar, simplemente cree un nuevo tipo de tupla con nombre a partir del atributo _fields:

>>> Point3D = namedtuple('Point3D', Point._fields + ('z',))

Los docstrings se pueden personalizar realizando asignaciones directas a los campos __doc__ :

>>> Book = namedtuple('Book', ['id', 'title', 'authors'])
>>> Book.__doc__ += ': Hardcover book in active collection'
>>> Book.id.__doc__ = '13-digit ISBN'
>>> Book.title.__doc__ = 'Title of first printing'
>>> Book.authors.__doc__ = 'List of authors sorted by last name'

Distinto en la versión 3.5: Los docstrings de propiedad se pueden escribir.

Ver también

Consulte typing.NamedTuple para ver una forma de agregar sugerencias de tipo para tuplas con nombre. También proporciona una notación elegante usando la palabra clave class:

class Component(NamedTuple):
    part_number: int
    weight: float
    description: Optional[str] = None

Vea types.SimpleNamespace() para un espacio de nombres mutable basado en un diccionario subyacente en lugar de una tupla.

El módulo dataclasses proporciona un decorador y funciones para agregar automáticamente métodos especiales generados a clases definidas por el usuario.

Objetos OrderedDict

Los diccionarios ordenados son como los diccionarios normales, pero tienen algunas capacidades adicionales relacionadas con las operaciones de ordenado. Se han vuelto menos importantes ahora que la clase incorporada dict ganó la capacidad de recordar el orden de inserción (este nuevo comportamiento quedó garantizado en Python 3.7).

Aún quedan algunas diferencias con dict :

El dict normal fue diseñado para ser muy bueno en operaciones de mapeo. El seguimiento del pedido de inserción era secundario.

La OrderedDict fue diseñada para ser buena para reordenar operaciones. La eficiencia del espacio, la velocidad de iteración y el rendimiento de las operaciones de actualización fueron secundarios.

Algorítmicamente, OrderedDict puede manejar operaciones frecuentes de reordenamiento mejor que dict. Esto lo hace adecuado para rastrear accesos recientes (por ejemplo, en un cache LRU [https://medium.com/@krishankantsinghal/my-first-blog-on-medium-583159139237]).

La operación de igualdad para OrderedDict comprueba el orden coincidente.

El método popitem() de OrderedDict tiene una firma diferente. Acepta un argumento opcional para especificar qué elemento es popped.

OrderedDict tiene un método move_to_end() para reposiciones eficientemente un elemento a un punto final.

Hasta Python 3.8, dict carecía de un método __reversed__().

class collections.OrderedDict([items])

Retorna una instancia de una subclase dict que tiene métodos especializados para reorganizar el orden del diccionario.

Nuevo en la versión 3.1.

popitem(last=True)

El método popitem() para diccionarios ordenados retorna y elimina un par (llave, valor). Los pares se retornan en orden LIFO si el último es verdadero o en orden FIFO si es falso.

move_to_end(key, last=True)

Mueva una llave existente a cualquier extremo de un diccionario ordenado. El elemento se mueve al final de la derecha si el último es verdadero (el valor predeterminado) o al principio si el último es falso. Lanza KeyError si la llave no existe:

>>> d = OrderedDict.fromkeys('abcde')
>>> d.move_to_end('b')
>>> ''.join(d.keys())
'acdeb'
>>> d.move_to_end('b', last=False)
>>> ''.join(d.keys())
'bacde'

Nuevo en la versión 3.2.

Además de los métodos de mapeo habituales, los diccionarios ordenados también admiten la iteración inversa usando reversed().

Las pruebas de igualdad entre los objetos OrderedDict son sensibles al orden y se implementan como list(od1.items())==list(od2.items()). Las pruebas de igualdad entre los objetos OrderedDict y otros objetos Mapping son insensibles al orden como los diccionarios normales. Esto permite que los objetos OrderedDict sean sustituidos en cualquier lugar donde se utilice un diccionario normal.

Distinto en la versión 3.5: Los elementos, llaves y valores vistas de OrderedDict ahora admiten la iteración inversa usando reversed().

Distinto en la versión 3.6: Con la aceptación de PEP 468 [https://www.python.org/dev/peps/pep-0468], el orden se mantiene para los argumentos de palabras clave pasados al constructor OrderedDict y su método update().

Distinto en la versión 3.9: Se agregaron los operadores unir (|) y actualizar (|=), especificados en PEP 584 [https://www.python.org/dev/peps/pep-0584].

Ejemplos y Recetas OrderedDict

Es sencillo crear una variante de diccionario ordenado que recuerde el orden en que las llaves se insertaron por última vez. Si una nueva entrada sobrescribe una entrada existente, la posición de inserción original se cambia y se mueve al final:

class LastUpdatedOrderedDict(OrderedDict):
    'Store items in the order the keys were last added'

    def __setitem__(self, key, value):
        super().__setitem__(key, value)
        self.move_to_end(key)

An OrderedDict would also be useful for implementing variants of functools.lru_cache():

class LRU:

    def __init__(self, func, maxsize=128):
        self.func = func
        self.maxsize = maxsize
        self.cache = OrderedDict()

    def __call__(self, *args):
        if args in self.cache:
            value = self.cache[args]
            self.cache.move_to_end(args)
            return value
        value = self.func(*args)
        if len(self.cache) >= self.maxsize:
            self.cache.popitem(False)
        self.cache[args] = value
        return value

Objetos UserDict

La clase, UserDict actúa como un contenedor alrededor de los objetos del diccionario. La necesidad de esta clase ha sido parcialmente suplantada por la capacidad de crear subclases directamente desde dict; sin embargo, es más fácil trabajar con esta clase porque se puede acceder al diccionario subyacente como un atributo.

class collections.UserDict([initialdata])

Class that simulates a dictionary. The instance’s contents are kept in a regular dictionary, which is accessible via the data attribute of UserDict instances. If initialdata is provided, data is initialized with its contents; note that a reference to initialdata will not be kept, allowing it to be used for other purposes.

Además de admitir los métodos y operaciones de los mappings, las instancias UserDict proporcionan el siguiente atributo:

data

Un diccionario real utilizado para almacenar el contenido de la clase UserDict .

Objetos UserList

Esta clase actúa como un contenedor alrededor de los objetos de lista. Es una clase base útil para tus propias clases tipo lista que pueden heredar de ellas y anular métodos existentes o agregar nuevos. De esta forma, se pueden agregar nuevos comportamientos a las listas.

La necesidad de esta clase ha sido parcialmente suplantada por la capacidad de crear subclases directamente desde list; sin embargo, es más fácil trabajar con esta clase porque se puede acceder a la lista subyacente como atributo.

class collections.UserList([list])

Clase que simula una lista. El contenido de la instancia se mantiene en una lista normal, a la que se puede acceder mediante el atributo data de las instancias UserList. El contenido de la instancia se establece inicialmente en una copia de list, por defecto a la lista vacía []. list puede ser cualquier iterable, por ejemplo, una lista de Python real o un objeto UserList.

Además de admitir los métodos y operaciones de secuencias mutables, las instancias UserList proporcionan el siguiente atributo:

data

Un objeto real list usado para almacenar el contenido de la clase UserList .

Requisitos de subclases: Se espera que las subclases de UserList ofrezcan un constructor al que se pueda llamar sin argumentos o con un solo argumento. Las operaciones de lista que retornan una nueva secuencia intentan crear una instancia de la clase de implementación real. Para hacerlo, asume que se puede llamar al constructor con un solo parámetro, que es un objeto de secuencia utilizado como fuente de datos.

Si una clase derivada no desea cumplir con este requisito, todos los métodos especiales admitidos por esta clase deberán de anularse; consulte las fuentes para obtener información sobre los métodos que deben proporcionarse en ese caso.

Objetos UserString

La clase, UserString actúa como un envoltorio alrededor de los objetos de cadena. La necesidad de esta clase ha sido parcialmente suplantada por la capacidad de crear subclases directamente de str; sin embargo, es más fácil trabajar con esta clase porque se puede acceder a la cadena subyacente como atributo.

class collections.UserString(seq)

Clase que simula un objeto de cadena. El contenido de la instancia se mantiene en un objeto de cadena normal, al que se puede acceder a través del atributo data de las instancias UserString. El contenido de la instancia se establece inicialmente en una copia de seq. El argumento seq puede ser cualquier objeto que se pueda convertir en una cadena usando la función incorporada str().

Además de admitir los métodos y operaciones de cadenas, las instancias UserString proporcionan el siguiente atributo:

data

Un objeto real str usado para almacenar el contenido de la clase UserString.

Distinto en la versión 3.5: Nuevos métodos __getnewargs__, __rmod__, casefold, format_map, isprintable, y maketrans.

collections.abc — Clases Base Abstractas para Contenedores

Nuevo en la versión 3.3: Anteriormente, este módulo formaba parte del módulo collections.

Código fuente: Lib/_collections_abc.py [https://github.com/python/cpython/tree/3.9/Lib/_collections_abc.py]

Este módulo proporciona clases base abstractas que pueden usarse para probar si una clase proporciona una interfaz específica; por ejemplo, si es hashable o si es un mapeo.

Nuevo en la versión 3.9: These abstract classes now support []. See Tipo Alias Genérico and PEP 585 [https://www.python.org/dev/peps/pep-0585].

Colecciones Clases Base Abstractas

El módulo de colecciones ofrece lo siguiente ABCs:

ABC

Hereda de

Métodos Abstractos

Métodos Mixin

Container

__contains__

Hashable

__hash__

Iterable

__iter__

Iterator

Iterable

__next__

__iter__

Reversible

Iterable

__reversed__

Generator

Iterator

send, throw

close, __iter__, __next__

Sized

__len__

Callable

__call__

Collection

Sized, Iterable, Container

__contains__, __iter__, __len__

Sequence

Reversible, Collection

__getitem__, __len__

__contains__, __iter__, __reversed__, index, and count

MutableSequence

Sequence

__getitem__, __setitem__, __delitem__, __len__, insert

Métodos heredados Sequence y append, reverse, extend, pop, remove, and __iadd__

ByteString

Sequence

__getitem__, __len__

Métodos heredados Sequence

Set

Collection

__contains__, __iter__, __len__

__le__, __lt__, __eq__, __ne__, __gt__, __ge__, __and__, __or__, __sub__, __xor__, and isdisjoint

MutableSet

Set

__contains__, __iter__, __len__, add, discard

Métodos heredados Set y clear, pop, remove, __ior__, __iand__, __ixor__, and __isub__

Mapping

Collection

__getitem__, __iter__, __len__

__contains__, keys, items, values, get, __eq__, and __ne__

MutableMapping

Mapping

__getitem__, __setitem__, __delitem__, __iter__, __len__

Métodos heredados Mapping y pop, popitem, clear, update, and setdefault

MappingView

Sized

__len__

ItemsView

MappingView, Set

__contains__, __iter__

KeysView

MappingView, Set

__contains__, __iter__

ValuesView

MappingView, Collection

__contains__, __iter__

Awaitable

__await__

Coroutine

Awaitable

send, throw

close

AsyncIterable

__aiter__

AsyncIterator

AsyncIterable

__anext__

__aiter__

AsyncGenerator

AsyncIterator

asend, athrow

aclose, __aiter__, __anext__

class collections.abc.Container

ABC para clases que proporcionan el método __contains__().

class collections.abc.Hashable

ABC para clases que proporcionan el método __hash__().

class collections.abc.Sized

ABC para clases que proporcionan el método __len__().

class collections.abc.Callable

ABC para clases que proporcionan el método __call__().

class collections.abc.Iterable

ABC para clases que proporcionan el método __iter__().

Al marcar isinstance(obj, Iterable) se detectan las clases que están registradas como Iterable o que tienen un método __iter__(), pero no detecta clases que iteran con el método __getitem__(). La única forma confiable de determinar si un objeto es iterable es llamar a iter(obj).

class collections.abc.Collection

ABC para clases de contenedor iterables de tamaño.

Nuevo en la versión 3.6.

class collections.abc.Iterator

ABC para clases que proporcionan el método __iter__() y __next__(). Ver también la definición de iterator.

class collections.abc.Reversible

ABC para clases iterables que también proporcionan __reversed__() method.

Nuevo en la versión 3.6.

class collections.abc.Generator

ABC para clases generadoras que implementan el protocolo definido en PEP 342 [https://www.python.org/dev/peps/pep-0342] que extiende los iteradores con los métodos send(), throw() and close(). Ver también la definición de generator.

Nuevo en la versión 3.5.

class collections.abc.Sequence

class collections.abc.MutableSequence

class collections.abc.ByteString

ABC para solo lectura y mutable secuencias.

Nota de implementación: algunos de los métodos mixin, tales como __iter__(), __reversed__() and index(), hacen llamadas repetidas al subyacente __getitem__() method. En consecuencia, si __getitem__() se implementa con velocidad de acceso constante, los métodos mixin tendrán un rendimiento lineal; sin embargo, si el método subyacente es lineal (como lo sería con una lista vinculada), los mixins tendrán un rendimiento cuadrático y probablemente deberán ser anulados.

Distinto en la versión 3.5: El método index() agregó soporte para los argumentos stop y start.

class collections.abc.Set

class collections.abc.MutableSet

ABC para conjuntos de solo lectura y mutables.

class collections.abc.Mapping

class collections.abc.MutableMapping

ABC para solo lectura y mutable mapeos.

class collections.abc.MappingView

class collections.abc.ItemsView

class collections.abc.KeysView

class collections.abc.ValuesView

ABC para mapeo, elementos, claves y valores vistas.

class collections.abc.Awaitable

ABC para objetos awaitable, que pueden ser usados en expresiones await. Las implementaciones personalizadas deben proporcionar el método __await__().

Coroutine objetos e instancias de la clase Coroutine ABC son todas las instancias de este ABC.

Nota

En CPython, las corrutinas basadas en generador (generadores decorados con types.coroutine() o asyncio.coroutine()) son awaitables, a pesar de que no tienen un método __await__(). El uso de isinstance(gencoro, Awaitable) para ellos retornará False. Use inspect.isawaitable() para detectarlos.

Nuevo en la versión 3.5.

class collections.abc.Coroutine

ABC para clases corrutinas compatibles. Estos implementan los siguientes métodos, definidos en Objetos de Corrutina: send(), throw(), and close(). Las implementaciones personalizadas también deben implementar __await__(). Todas las instancias de Coroutine también son instancias de Awaitable. Ver también la definición de coroutine.

Nota

En CPython, las corrutinas basadas en generador (generadores decorados con types.coroutine() o asyncio.coroutine()) son awaitables, a pesar de que no tienen un método __await__(). El uso de isinstance(gencoro, Coroutine) para ellos retornará False. Use inspect.isawaitable() para detectarlos.

Nuevo en la versión 3.5.

class collections.abc.AsyncIterable

ABC para las clases que proporcionan el método __aiter__. Ver también la definición de asynchronous iterable.

Nuevo en la versión 3.5.

class collections.abc.AsyncIterator

ABC para clases que proveen métodos __aiter__ and __anext__. Ver también la definición de asynchronous iterator.

Nuevo en la versión 3.5.

class collections.abc.AsyncGenerator

ABC para clases generadoras asincrónicas que implementan el protocolo definido en PEP 525 [https://www.python.org/dev/peps/pep-0525] y PEP 492 [https://www.python.org/dev/peps/pep-0492].

Nuevo en la versión 3.6.

Estos ABC nos permiten preguntar a clases o instancias si proporcionan una funcionalidad particular, por ejemplo:

size = None
if isinstance(myvar, collections.abc.Sized):
    size = len(myvar)

Varios ABCs también son útiles como mixins que facilitan el desarrollo de clases que admiten APIs de contenedor. Por ejemplo, para escribir una clase que admita toda la API Set, solo es necesario proporcionar los tres métodos abstractos subyacentes: __contains__(), __iter__(), y __len__(). El ABC proporciona los métodos restantes, como __and__() y isdisjoint():

class ListBasedSet(collections.abc.Set):
    ''' Alternate set implementation favoring space over speed
        and not requiring the set elements to be hashable. '''
    def __init__(self, iterable):
        self.elements = lst = []
        for value in iterable:
            if value not in lst:
                lst.append(value)

    def __iter__(self):
        return iter(self.elements)

    def __contains__(self, value):
        return value in self.elements

    def __len__(self):
        return len(self.elements)

s1 = ListBasedSet('abcdef')
s2 = ListBasedSet('defghi')
overlap = s1 & s2            # The __and__() method is supported automatically

Notas sobre el uso de Set y MutableSet como un mixin:

Dado que algunas operaciones de conjuntos crean nuevos conjuntos, los métodos mixin predeterminados necesitan una forma de crear nuevas instancias a partir de un iterable. Se supone que el constructor de la clase tiene una firma con el formato ClassName(iterable). Esa suposición se factoriza en un método de clase interno llamado _from_iterable() que llama a cls(iterable) para producir un nuevo conjunto. Si el mixin Set se está usando en una clase con una firma de constructor diferente, necesitarás anular _from_iterable() con un método de clase o método regular que pueda construir nuevas instancias a partir de un argumento iterable.

Para reemplazar las comparaciones (presumiblemente para la velocidad, ya que las semánticas son fijas), redefinir __le__() y __ge__(), luego las otras operaciones seguirán automáticamente su ejemplo.

El mixin Set proporciona un método _hash() para calcular un valor hash para el conjunto; sin embargo, __hash__() no está definido porque no todos los conjuntos son encadenados o inmutables. Para agregar capacidad de encadenamiento en conjuntos que usan mixin, herede de ambos Set() y Hashable(), luego defina __hash__ = Set._hash.

Ver también

OrderedSet receta [https://code.activestate.com/recipes/576694/] para un ejemplo basado en MutableSet.

Para obtener más información sobre ABCs, ver el módulo abc y PEP 3119 [https://www.python.org/dev/peps/pep-3119].

heapq — Algoritmo de colas montículos (heap)

Código fuente: Lib/heapq.py [https://github.com/python/cpython/tree/3.9/Lib/heapq.py]

Este módulo proporciona una implementación del algoritmo de montículos, también conocido como algoritmo de cola con prioridad.

Los montículos son árboles binarios para los cuales cada nodo padre tiene un valor menor o igual que cualquiera de sus hijos. Esta implementación utiliza matrices para las cuales heap[k] <= heap[2*k+1] y heap[k] <= heap[2*k+2] para todo k, contando los elementos desde cero. Para poder comparar, los elementos inexistentes se consideran infinitos. La propiedad interesante de un montículo es que su elemento más pequeño es siempre la raíz, heap[0].

El API que se presenta a continuación difiere de los algoritmos de los libros de texto en dos aspectos: (a) Utilizamos la indexación basada en cero. Esto hace que la relación entre el índice de un nodo y los índices de sus hijos sea un poco menos evidente, pero es más adecuado ya que Python utiliza la indexación basada en cero. (b) Nuestro método «pop» retorna el elemento más pequeño, no el más grande (llamado «min heap» o montículo por mínimo en los libros de texto; un «max heap» o montículo por máximos es más común en los textos debido a su idoneidad para la clasificación in situ).

Estos dos permiten ver el montículo como una lista Python normal sin sorpresas: heap[0] es el ítem más pequeño, y heap.sort() mantiene el montículo invariable!

Para crear un montículo, usa una lista inicializada como [], o puedes transformar una lista poblada en un montículo a través de la función heapify().

Las siguientes funciones están provistas:

heapq.heappush(heap, item)

Empujar el valor item en el heap, manteniendo el montículo invariable.

heapq.heappop(heap)

Desapila o pop y retorna el elemento más pequeño del heap, manteniendo el montículo invariable. Si el montículo está vacío, IndexError se lanza. Para acceder al elemento más pequeño sin necesidad de desapilar, usa``heap[0]``.

heapq.heappushpop(heap, item)

Apila el elemento o iem en el montículo, y luego desapila y retorna el elemento más pequeño del montículo. La acción combinada se ejecuta más eficientemente que heappush() seguido de una llamada separada a heappop().

heapq.heapify(x)

Transformar la lista x en un montículo, en el lugar, en tiempo lineal.

heapq.heapreplace(heap, item)

Desapila y retorna el elemento más pequeño del heap, y también apile el nuevo item. El tamaño del montículo no cambia. Si el montículo está vacío, IndexError se eleva.

Esta operación de un solo paso es más eficiente que un heappop() seguido por heappush() y puede ser más apropiada cuando se utiliza un montículo de tamaño fijo. La combinación pop/push siempre retorna un elemento del montículo y lo reemplaza con item.

El valor retornado puede ser mayor que el item añadido. Si no se desea eso, considere usar heappushpop() en su lugar. Su combinación push/pop retorna el menor de los dos valores, dejando el mayor valor en el montículo.

El módulo también ofrece tres funciones de propósito general basadas en los montículos.

heapq.merge(*iterables, key=None, reverse=False)

Fusionar varias entradas ordenadas en una sola salida ordenada (por ejemplo, fusionar entradas con marca de tiempo de varios archivos de registro). Retorna un iterator sobre los valores ordenados.

Similar a sorted(itertools.chain(*iterables)) pero retorna un iterable, no hala los datos a la memoria de una sola vez, y asume que cada uno de los flujos de entrada ya están ordenado (de menor a mayor).

Tiene dos argumentos opcionales que deben ser especificados como argumentos de palabras clave.

key especifica una key function de un argumento que se utiliza para extraer una clave de comparación de cada elemento de entrada. El valor por defecto es None (compara los elementos directamente).

reverse es un valor booleano. Si se establece en True, entonces los elementos de entrada se fusionan como si cada comparación se invirtiera. Para lograr un comportamiento similar a sorted(itertools.chain(*iterables), reverse=True), todos los iterables deben ser ordenados de mayor a menor.

Distinto en la versión 3.5: Añadió los parámetros opcionales de key y reverse.

heapq.nlargest(n, iterable, key=None)

Retorna una lista con los n elementos más grandes del conjunto de datos definidos por iterable. key, si se proporciona, especifica una función de un argumento que se utiliza para extraer una clave de comparación de cada elemento en iterable (por ejemplo, key=str.lower). Equivalente a: sorted(iterable, key=clave, reverse=True)[:n].

heapq.nsmallest(n, iterable, key=None)

Retorna una lista con los n elementos más pequeños del conjunto de datos definidos por iterable. key, si se proporciona, especifica una función de un argumento que se utiliza para extraer una clave de comparación de cada elemento en iterable (por ejemplo, key=str.lower). Equivalente a: sorted(iterable, key=clave)[:n].

Las dos últimas funciones funcionan mejor para valores más pequeños de n. Para valores más grandes, es más eficiente usar la función sorted(). Además, cuando n==1, es más eficiente usar las funciones incorporadas min() y max`(). Si se requiere el uso repetido de estas funciones, considere convertir lo iterable en un verdadero montículo.

Ejemplos Básicos

Un heapsort» [https://en.wikipedia.org/wiki/Heapsort] puede ser implementado empujando todos los valores en un montículo y luego desapilando los valores más pequeños uno a la vez:

>>> def heapsort(iterable):
...     h = []
...     for value in iterable:
...         heappush(h, value)
...     return [heappop(h) for i in range(len(h))]
...
>>> heapsort([1, 3, 5, 7, 9, 2, 4, 6, 8, 0])
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

Esto es similar a sorted(iterable), pero a diferencia de sorted(), esta implementación no es estable.

Los elementos del montículo pueden ser tuplas. Esto es útil para asignar valores de comparación (como las prioridades de las tareas) junto con el registro principal que se está rastreando:

>>> h = []
>>> heappush(h, (5, 'write code'))
>>> heappush(h, (7, 'release product'))
>>> heappush(h, (1, 'write spec'))
>>> heappush(h, (3, 'create tests'))
>>> heappop(h)
(1, 'write spec')

Notas de Aplicación de la Cola de Prioridades

Una cola de prioridad [https://en.wikipedia.org/wiki/Priority_queue] es de uso común para un montículo, y presenta varios desafíos de implementación:

Estabilidad de la clasificación: ¿cómo se consigue que dos tareas con iguales prioridades sean retornadas en el orden en que fueron añadidas originalmente?

Interrupciones de comparación en tupla para pares (prioridad, tarea) si las prioridades son iguales y las tareas no tienen un orden de comparación por defecto.

¿Si la prioridad de una tarea cambia, cómo la mueves a una nueva posición en el montículo?

¿O si una tarea pendiente necesita ser borrada, cómo la encuentras y la eliminas de la cola?

Una solución a los dos primeros desafíos es almacenar las entradas como una lista de 3 elementos que incluya la prioridad, un recuento de entradas y la tarea. El recuento de entradas sirve como un desempate para que dos tareas con la misma prioridad sean retornadas en el orden en que fueron añadidas. Y como no hay dos recuentos de entradas iguales, la comparación tupla nunca intentará comparar directamente dos tareas.

Otra solución al problema de las tareas no comparables es crear una clase envolvente que ignore el elemento de la tarea y sólo compare el campo de prioridad:

from dataclasses import dataclass, field
from typing import Any

@dataclass(order=True)
class PrioritizedItem:
    priority: int
    item: Any=field(compare=False)

Los desafíos restantes giran en torno a encontrar una tarea pendiente y hacer cambios en su prioridad o eliminarla por completo. Encontrar una tarea se puede hacer con un diccionario que apunta a una entrada en la cola.

Eliminar la entrada o cambiar su prioridad es más difícil porque rompería las invariantes de la estructura del montículo. Por lo tanto, una posible solución es marcar la entrada como eliminada y añadir una nueva entrada con la prioridad revisada:

pq = []                         # list of entries arranged in a heap
entry_finder = {}               # mapping of tasks to entries
REMOVED = '<removed-task>'      # placeholder for a removed task
counter = itertools.count()     # unique sequence count

def add_task(task, priority=0):
    'Add a new task or update the priority of an existing task'
    if task in entry_finder:
        remove_task(task)
    count = next(counter)
    entry = [priority, count, task]
    entry_finder[task] = entry
    heappush(pq, entry)

def remove_task(task):
    'Mark an existing task as REMOVED.  Raise KeyError if not found.'
    entry = entry_finder.pop(task)
    entry[-1] = REMOVED

def pop_task():
    'Remove and return the lowest priority task. Raise KeyError if empty.'
    while pq:
        priority, count, task = heappop(pq)
        if task is not REMOVED:
            del entry_finder[task]
            return task
    raise KeyError('pop from an empty priority queue')

Teoría

Los montículos son conjuntos para los cuales``a[k] <= a[2*k+1]`` y «a[k] <= a[2*k+2]`` para todos los k, contando los elementos desde 0. Para comparar, los elementos no existentes se consideran infinitos. La interesante propiedad de un montículo es que a[0] es siempre su elemento más pequeño.

La extraña invariante de arriba intenta ser una representación eficiente de la memoria para un torneo. Los números de abajo son k, no``a[k]``:

                               0

              1                                 2

      3               4                5               6

  7       8       9       10      11      12      13      14

15 16   17 18   19 20   21 22   23 24   25 26   27 28   29 30

En el árbol de arriba, cada celda k está coronada por 2*k+1 y 2*k+2. En un torneo binario habitual que vemos en los deportes, cada celda es el ganador sobre las dos celdas que supera, y podemos rastrear al ganador hasta el árbol para ver todos los oponentes que tuvo. Sin embargo, en muchas aplicaciones informáticas de tales torneos, no necesitamos rastrear la historia de un ganador. Para ser más eficientes en la memoria, cuando un ganador es ascendido, tratamos de reemplazarlo por algo más en un nivel inferior, y la regla se convierte en que una celda y las dos celdas que supera contienen tres elementos diferentes, pero la celda superior «gana» sobre las dos celdas superiores.

Si esta invariante del montículo está protegida en todo momento, el índice 0 es claramente el ganador general. La forma algorítmica más simple de eliminarlo y encontrar el «próximo» ganador es mover algún perdedor (digamos la celda 30 en el diagrama de arriba) a la posición 0, y luego filtrar este nuevo 0 por el árbol, intercambiando valores, hasta que la invariante se reestablezca. Esto es claramente logarítmico en el número total de elementos del árbol. Al iterar sobre todos los elementos, se obtiene una clasificación O(n log n).

Una buena característica de este tipo es que puedes insertar nuevos elementos de manera eficiente mientras se realiza la clasificación, siempre y cuando los elementos insertados no sean «mejores» que el último 0’th elemento que has extraído. Esto es especialmente útil en contextos de simulación, donde el árbol contiene todos los eventos entrantes, y la condición de «ganar» significa el menor tiempo programado. Cuando un evento programa otros eventos para su ejecución, se programan en el futuro, para que puedan ir fácilmente al montículo. Por lo tanto, un montículo es una buena estructura para implementar planificadores o schedulers (esto es lo que usé para mi secuenciador MIDI :-).

Se han estudiado extensamente varias estructuras para implementar los planificadores, y los montículos son buenos para ello, ya que son razonablemente rápidos, la velocidad es casi constante, y el peor de los casos no es muy diferente del caso promedio. Sin embargo, hay otras representaciones que son más eficientes en general, aunque los peores casos podrían ser terribles.

Los montículos también son muy útiles en las grandes ordenaciones de elementos en discos de memoria. Lo más probable es que todos sepan que un tipo grande implica la producción de «ejecuciones» (que son secuencias preclasificadas, cuyo tamaño suele estar relacionado con la cantidad de memoria de la CPU), seguidas de una fusión de pases para estas ejecuciones, cuya fusión suele estar muy inteligentemente organizada 1. Es muy importante que la clasificación inicial produzca las ejecuciones posibles más largas. Los torneos son una buena manera de lograrlo. Si, utilizando toda la memoria disponible para celebrar un torneo, sustituyes y filtras los elementos que encajan en la carrera actual, producirás carreras que tienen el doble del tamaño de la memoria para la entrada aleatoria, y mucho mejor para la entrada ordenada de forma difusa.

Además, si se da salida al 0’th item en el disco y se obtiene una entrada que no puede caber en el torneo actual (porque el valor «gana» sobre el último valor de salida), no puede caber en el montículo, por lo que el tamaño del montículo disminuye. La memoria liberada podría ser ingeniosamente reutilizada inmediatamente para construir progresivamente un segundo montículo, que crece exactamente al mismo ritmo que el primer montículo se está fundiendo. Cuando el primer montículo se desvanece completamente, se cambia de montículo y se inicia una nueva carrera. ¡Ingenioso y muy efectivo!

En una palabra, los montículos son estructuras de memoria útiles a conocer. Las uso en algunas aplicaciones, y creo que es bueno tener un módulo “heap” alrededor. :-)

Notas al pie de página

1

Los algoritmos de balanceo de discos que están vigentes hoy en día, son más molestos que inteligentes, y esto es una consecuencia de las capacidades de búsqueda de los discos. En los dispositivos que no pueden buscar, como las grandes unidades de cinta, la historia era muy diferente, y había que ser muy inteligente para asegurarse (con mucha antelación) de que cada movimiento de la cinta fuera el más efectivo (es decir, que participara mejor en el «progreso» de la fusión). Algunas cintas eran incluso capaces de leer al revés, y esto también se utilizó para evitar el tiempo rebobinado. Créanme, ¡la ordenación de elementos en cinta realmente buenos fueron espectaculares de ver! ¡Desde todos los tiempos, la ordenación de elementos siempre ha sido un Gran Arte! :-)

bisect — Algoritmo de bisección de arreglos

Código fuente: Lib/bisect.py [https://github.com/python/cpython/tree/3.9/Lib/bisect.py]

Este módulo brinda soporte para mantener una lista ordenada sin tener que reordenar la lista tras cada nueva inserción. Para listas largas de elementos que tienen operaciones de comparación costosas, será una mejora respecto a la estrategia más habitual. El módulo se llama bisect porque usa un algoritmo de bisección básico para lograr su objetivo. El código fuente puede ser útil como ejemplo del algoritmo en funcionamiento (¡las precondiciones ya están bien de antemano!).

Las siguientes funciones están disponibles:

bisect.bisect_left(a, x, lo=0, hi=len(a))

Ubicar el punto de inserción para x en a para mantener el ordenamiento. Los parámetros lo (inferior) y hi (superior) pueden utilizarse para especificar un subconjunto (subset) de la lista que debería considerarse. Por defecto, se utiliza la lista completa. Si x ya está presente en a, el punto de inserción será antes (a la izquierda de) cualquier elemento existente. El valor de retorno es adecuado para que se utilice como primer parámetro para list.insert(), suponiendo que a ya está ordenada.

El punto de inserción retornado i particiona al arreglo a en dos mitades, tal que all(val < x for val in a[lo:i]) para el lado izquierdo y all(val >= x for val in a[i:hi]) para el derecho.

bisect.bisect_right(a, x, lo=0, hi=len(a))

bisect.bisect(a, x, lo=0, hi=len(a))

Similar a bisect_left(), pero retorna un punto de inserción que viene después (a la derecha de) cualquier entrada de x en a.

El punto de inserción retornado i particiona al arreglo a en dos mitades, tal que all(val <= x for val in a[lo:i]) para el lado izquierdo y all(val > x for val in a[i:hi]) para el derecho.

bisect.insort_left(a, x, lo=0, hi=len(a))

Inserta x en a de forma ordenada. Esto equivale a a.insert(bisect.bisect_left(a, x, lo, hi), x), suponiendo que a ya está ordenada. Tenga presente que la búsqueda O(log n) está dominada por el paso de inserción O(n) lento.

bisect.insort_right(a, x, lo=0, hi=len(a))

bisect.insort(a, x, lo=0, hi=len(a))

Similar a insort_left(), pero inserta x en a después de cualquier entrada x existente.

Ver también

Receta SortedCollection [https://code.activestate.com/recipes/577197-sortedcollection/] que usa bisección para construir una «clase-colección» con todas las funcionalidades, con métodos de búsqueda directos y con soporte para una función-clave (key-function). Las claves son procesadas de antemano, para ahorrar llamadas innecesarias a la función clave durante las búsquedas.

Búsqueda en listas ordenadas

Las funciones anteriores bisect() son útiles para encontrar puntos de inserción, pero pueden resultar difíciles o engorrosas para tareas de búsqueda habituales. Las cinco funciones que siguen muestran cómo convertirlas en búsquedas estándar para listas ordenadas:

def index(a, x):
    'Locate the leftmost value exactly equal to x'
    i = bisect_left(a, x)
    if i != len(a) and a[i] == x:
        return i
    raise ValueError

def find_lt(a, x):
    'Find rightmost value less than x'
    i = bisect_left(a, x)
    if i:
        return a[i-1]
    raise ValueError

def find_le(a, x):
    'Find rightmost value less than or equal to x'
    i = bisect_right(a, x)
    if i:
        return a[i-1]
    raise ValueError

def find_gt(a, x):
    'Find leftmost value greater than x'
    i = bisect_right(a, x)
    if i != len(a):
        return a[i]
    raise ValueError

def find_ge(a, x):
    'Find leftmost item greater than or equal to x'
    i = bisect_left(a, x)
    if i != len(a):
        return a[i]
    raise ValueError

Otros ejemplos

La función bisect() puede ser útil para búsquedas en tablas numéricas. Este ejemplo utiliza bisect() para buscar una calificación de un examen dada por una letra, basada en un conjunto de marcas numéricas ordenadas: 90 o más es una “A”, de 80 a 89 es una “B”, y así sucesivamente:

>>> def grade(score, breakpoints=[60, 70, 80, 90], grades='FDCBA'):
...     i = bisect(breakpoints, score)
...     return grades[i]
...
>>> [grade(score) for score in [33, 99, 77, 70, 89, 90, 100]]
['F', 'A', 'C', 'C', 'B', 'A', 'A']

A diferencia de la función sorted(), no tiene sentido para las funciones bisect() tener los argumentos key o reversed, porque conduciría a un diseño ineficiente (llamadas sucesivas a funciones de bisección no «recordarían» todas las búsquedas previas con clave).

En su lugar, es mejor buscar en una lista de claves procesadas de antemano para encontrar el índice del registro en cuestión:

>>> data = [('red', 5), ('blue', 1), ('yellow', 8), ('black', 0)]
>>> data.sort(key=lambda r: r[1])
>>> keys = [r[1] for r in data]         # precomputed list of keys
>>> data[bisect_left(keys, 0)]
('black', 0)
>>> data[bisect_left(keys, 1)]
('blue', 1)
>>> data[bisect_left(keys, 5)]
('red', 5)
>>> data[bisect_left(keys, 8)]
('yellow', 8)

array — Arreglos eficientes de valores numéricos

Este modulo define un tipo de objeto que representa un arreglo de valores básicos: caracteres, números enteros y de punto flotante. Los arreglos son tipos de secuencias que se comportan de forma similar a las listas, a excepción que el tipo de objeto guardado es definido. El tipo es especificado al momento de crear el objeto mediante type code, que es un carácter simple. Se definen los siguientes tipos:

Código de tipo

Tipo C

Tipo Python

Tamaño mínimo en bytes

Notas

'b'

signed char

int

1

'B'

unsigned char

int

1

'u'

wchar_t

Carácter Unicode

2

(1)

'h'

signed short

int

2

'H'

unsigned short

int

2

'i'

signed int

int

2

'I'

unsigned int

int

2

'l'

signed long

int

4

'L'

unsigned long

int

4

'q'

signed long long

int

8

'Q'

unsigned long long

int

8

'f'

float

float

4

'd'

double

float

8

Notas:

Puede ser de 16 bits o 32 bits según la plataforma.

Distinto en la versión 3.9: array('u') ahora usa wchar_t como tipo C en lugar de Py_UNICODE obsoleto. Este cambio no afecta su comportamiento porque Py_UNICODE es el alias de wchar_t desde Python 3.3.

Deprecated since version 3.3, will be removed in version 4.0.

La representación real de los valores viene determinada por la arquitectura de la maquina (estrictamente hablando, por la implementación de C). El tamaño actual se puede obtener mediante el atributo itemsize.

El módulo define los siguientes tipos:

class array.array(typecode[, initializer])

Un nuevo arreglo cuyos elementos son restringidos por typecode, e inicializados con el valor opcional initializer, el cual debe ser una lista, un bytes-like object, o un iterable sobre los elementos del tipo apropiado.

Si dada una lista o un string, el inicializador es pasado a los nuevos métodos fromlist(), frombytes(), fromunicode() del arreglo (ver abajo) para añadir nuevos elementos al arreglo. De forma contraria, el iterable inicializador se pasa al método extend().

Lanza un evento de auditoría array.__new__ con argumentos typecode, initializer.

array.typecodes

Una cadena de caracteres con todos los códigos de tipos disponible.

Los objetos tipo arreglo soportan operaciones de secuencia ordinarias de indexación, segmentación, concatenación y multiplicación . Cuando se utiliza segmentación, el valor asignado debe ser un arreglo con el mismo código de tipo, en todos los otros casos se lanza TypeError. Los arreglos también implementan una interfaz de buffer, y puede ser utilizada en cualquier momento cuando los objetos bytes-like objects son soportados.

Los siguientes tipos de datos y métodos también son soportados:

array.typecode

El carácter typecode utilizado para crear el arreglo.

array.itemsize

La longitud en bytes de un elemento del arreglo en su representación interna.

array.append(x)

Añade un nuevo elemento con valor x al final del arreglo.

array.buffer_info()

Retorna una tupla (address, length) con la dirección de memoria actual y la longitud de los elementos en el buffer utilizado para almacenar temporalmente los elementos del arreglo. El tamaño del buffer de memoria es calculado como array.buffer_info()[1] * array.itemsize. Ocasionalmente es practico cuando trabajamos en interfaces E/S de bajo nivel (de manera inherentemente insegura) que requieren direcciones de memoria, por ejemplo ciertas operaciones ioctl(). Los números retornados son válidos mientras el arreglo exista y no se cambie la longitud del mismo.

Nota

Cuando utilizamos objetos tipo arreglo escritos en C o C++ (la única manera de utilizar esta información de forma más efectiva), tiene más sentido utilizar interfaces buffer que soporten objetos del tipo arreglo. Este método es mantenido con retro compatibilidad y tiene que ser evitado en el nuevo código. Las interfaces de buffer son documentadas en Protocolo Búfer.

array.byteswap()

«Byteswap» todos los elementos del arreglo. Solo es soportado para valores de tamaño 1,2,3,4 o 8 bytes; para otros valores se lanza RuntimeError. Es útil cuando leemos información de un fichero en una máquina con diferente orden de bytes.

array.count(x)

Retorna el número de ocurrencias de x en el arreglo.

array.extend(iterable)

Añade los elementos del iterable al final del arreglo. Si el iterable es de otro arreglo, este debe ser exactamente del mismo tipo; si no, se lanza TypeError. Si el iterable no es un arreglo, este debe de ser un iterable y sus elementos deben ser del tipo correcto para ser añadidos al arreglo.

array.frombytes(s)

Añade los elementos de la cadena de texto, interpretando la cadena de texto como un arreglo de valores máquina (como si se leyera de un fichero utilizando el método fromfile()).

Nuevo en la versión 3.2: fromstring() se renombra como frombytes() por claridad.

array.fromfile(f, n)

Read n items (as machine values) from the file object f and append them to the end of the array. If less than n items are available, EOFError is raised, but the items that were available are still inserted into the array.

array.fromlist(list)

Añade los elementos de la lista. Es equivalente a for x in list: a.append(x) excepto que si hay un error de tipo, el arreglo no se modifica.

array.fromunicode(s)

Extiende este arreglo con datos de la cadena de texto unicode. El arreglo debe ser un arreglo tipo 'u'; de forma contraria se lanza ValueError. Utiliza array.frombytes(unicodestring.encode(enc)) para añadir datos Unicode a un arreglo de algún otro tipo.

array.index(x)

Retorna la i más pequeña de modo que i es el índice de la primera ocurrencia de x en el arreglo.

array.insert(i, x)

Inserta un nuevo elemento con valor x en el arreglo antes de la posición i. Si hay valores negativos son tratados como relativos a la posición final del arreglo.

array.pop([i])

Elimina el elemento con índice i del arreglo y lo retorna. El argumento opcional por defecto es -1, en caso de utilizar el argumento por defecto el ultimo elemento es eliminado y retornado.

array.remove(x)

Elimina la primera ocurrencia de x del arreglo.

array.reverse()

Invierte el orden de los elementos en el arreglo.

array.tobytes()

Convierte el arreglo en un arreglo de valores máquina y retorna una representación en formato de bytes (la misma secuencia de bytes que se deben escribir en un fichero por el método tofile().)

Nuevo en la versión 3.2: tostring() se renombra como tobytes() para claridad.

array.tofile(f)

Escribe todos los elementos (incluido elementos máquina) a el file object f.

array.tolist()

Convierte el arreglo a una lista ordinaria con los mismos elementos.

array.tounicode()

Convierte el arreglo a una cadena de texto unicode. El arreglo debe ser un arreglo tipo 'u' ; en caso contrario se lanza ValueError. Utiliza array.tobytes().decode(enc) para obtener una cadena de texto unicode de un arreglo de algún otro tipo.

Cuando un objeto se imprime o se convierte a una cadena de texto, este se representa como array(typecode, initializer). El initializer se omite cuando el arreglo está vacío, de forma contraria es una cadena de caracteres si su typecode es 'u', de lo contrario es una lista de números. La cadena de caracteres garantiza que es capaz de ser convertida de nuevo a un arreglo con el mismo tipo y valor utilizando eval(), hasta que la clase array ha sido importada utilizando from array import array. Ejemplos:

array('l')
array('u', 'hello \u2641')
array('l', [1, 2, 3, 4, 5])
array('d', [1.0, 2.0, 3.14])

Ver también

Módulo struct

Empaquetado y desempaquetado de datos binarios heterogéneos.

Módulo xdrlib

Empaquetado y desempaquetado de datos de Representación de datos externos (XDR) como los utilizados en algunos sistemas de llamadas de procedimientos remotos.

NumPy [https://numpy.org/]

The NumPy package defines another array type.

weakref — Referencias débiles

Código Fuente: Lib/weakref.py [https://github.com/python/cpython/tree/3.9/Lib/weakref.py]

El módulo weakref le permite al programador de Python crear referencias débiles<weak references> a objetos.

A continuación, el término referente alude al objeto que es referenciado por una referencia débil.

Una referencia débil a un objeto no es suficiente para mantener al objeto con vida: cuando las únicas referencias que le queden a un referente son referencias débiles, la (recolección de basura) es libre de destruir al referente y reusar su memoria para algo más. Sin embargo, hasta que el objeto no sea realmente destruido, la referencia débil puede retornar el objeto incluso si no tiene referencias fuertes.

Un uso principal para las referencias débiles es para implementar caches o mapeados que mantienen objetos grandes, cuando no se desea que un objeto grande no sea mantenido con vida sólo porque aparece en un cache o mapeado.

Por ejemplo, si tienes un número de grandes objetos de imágenes binarias, puedes desear asociar un nombre con cada uno. Si usaras un diccionario de Python para mapear los nombres a imágenes, o imágenes a nombres, los objetos imagen quedarían con vida sólo porque aparecen como valores o llaves en los diccionarios. Las clases WeakKeyDictionary y WeakValueDictionary que se proporcionan por el módulo weakref son una alternativa, usando referencias débiles para construir mapeados que no mantengan con vida el objeto sólo porque aparecen en el mapeado de objetos. Si, por ejemplo, un objeto imagen es un valor en un WeakValueDictionary, entonces cuando las últimas referencias que queden de ese objeto imagen sean las referencias débiles guardadas por mapeados débiles, la recolección de basura puede reclamar el objeto, y sus entradas correspondientes en mapeados débiles son simplemente eliminadas.

WeakKeyDictionary y WeakValueDictionary usan referencias débiles en sus implementaciones, estableciendo retrollamadas (callback) en las referencias débiles que notifiquen a los diccionarios débiles cuando una llave o valor ha sido reclamado por la recolección de basura. WeakSet implementa la interfaz set, pero mantiene referencias débiles de sus elementos, justo como lo hace WeakKeyDictionary.

finalize provee una forma directa de registrar una función de limpieza que se llame cuando un objeto es recogido por la recolección de basura. Esto es más simple que configurar una retrollamada en una referencia débil pura, ya que el módulo automáticamente se asegura que el finalizador se mantenga con vida hasta que el objeto sea recolectado.

La mayoría de programas deben descubrir que usar uno de estos tipos de contenedores débiles o la clase finalize es todo lo que necesitan – usualmente no es necesario crear tus propias referencias débiles directamente. La maquinaria de bajo nivel está expuesta por el módulo weakref para el beneficio de usuarios avanzados.

No todos los objetos pueden ser débilmente referenciados; esos objetos que pueden incluir instancias de clases, funciones escritas en Python (pero no en C), métodos de instancia, conjuntos, frozensets, algunos objetos de archivo, generadores, objetos de tipos, sockets, arreglos, deques, objetos de patrones de expresiones regulares, y objetos código.

Distinto en la versión 3.2: Se añadió el soporte para thread.lock, threading.Lock, y objetos código.

Varios tipos incorporados como list y dict no soportan directamente referencias débiles pero pueden añadir soporte al crear una subclase:

class Dict(dict):
    pass

obj = Dict(red=1, green=2, blue=3)   # this object is weak referenceable

CPython implementation detail: Otros tipos incorporados como tuple y int no soportan referencias débiles incluso cuando son usadas como clase base.

Los tipos de extensiones se pueden hacer para soportar referencias débiles; véase Soporte de referencia débil.

When __slots__ are defined for a given type, weak reference support is disabled unless a '__weakref__' string is also present in the sequence of strings in the __slots__ declaration. See __slots__ documentation for details.

class weakref.ref(object[, callback])

Retorna una referencia débil de object. El objeto original puede ser recuperado al llamar la referencia del objeto si el referente sigue con vida; si el referente ya no está con vida, llamar a la referencia del objeto causará que se retorne un None. Si se proporciona callback y no None, y el objeto weakref retornado aún sigue con vida, la retrollamada (callback) será llamado cuando el objeto esté a punto de ser finalizado; el objeto de la referencia débil será pasado como el único parámetro a la retrollamada, el referente ya no estará disponible.

Se permite que muchas referencias débiles sean construidas por el mismo objeto. Las retrollamadas registradas por cada referencia débil serán llamados desde la retrollamada registrada más recientemente hasta la retrollamada registrada más antigua.

Las excepciones lanzadas por la retrollamada serán anotadas en la salida de error estándar, pero no pueden ser propagadas; son manejadas igual que las excepciones lanzadas por el método __del__() de un objeto.

Las referencias débiles son hashable si el object es mapeable. Ellos mantendrán su valor del hash incluso cuando el objet haya sido eliminado. Si hash() es llamado por primera vez sólo después de que object sea eliminado, la llamada lanzará un TypeError.

Las referencias débiles soportan pruebas para igualdad, pero no para ordenación. Si los referentes están todavía con vida, dos referencias tiene la misma relación de igualdad como sus referentes (sin importar el callback). Si un referente ha sido eliminado, las referencias son iguales sólo si el objetos de referencia son el mismo objeto.

Es un tipo del que se puede crear una subclase en vez de una función de fábrica.

__callback__

Este atributo de sólo lectura retorna la llamada que está asociada actualmente con el weakref. Si no hay retrollamadas o si el referente del weakref no está con vida entonces este atributo tendrá de valor None.

Distinto en la versión 3.4: Se añadió el atributo __callback__.

weakref.proxy(object[, callback])

Retorna un proxy a object que usa una referencia débil. Esto soporta el uso del proxy en la mayoría de los contextos en vez de requerir la dereferencia explícita usada con los objetos de referencia débil. El objeto retornado tendrá un tipo ProxyType o CallableProxyType, dependiendo si object es invocable. Objetos Proxy no son hashable independiente de la referencia; esto evita un número de problemas relacionados a su naturaleza mutable fundamental, y previene su uso como claves de diccionario. callback es el mismo como el parámetro del mismo nombre de la función ref().

Distinto en la versión 3.8: Se extendió el soporto de operadores en objetos proxy para incluir los operadores de multiplicación de matrices @ and @=.

weakref.getweakrefcount(object)

Retorna el número de referencias débiles y proxies que refieren a object.

weakref.getweakrefs(object)

Retorna una lista de todas las referencias débiles y objetos proxy que refieren a object.

class weakref.WeakKeyDictionary([dict])

Clase de mapeado que referencia llaves débilmente. Las entradas en el diccionario serán descartadas cuando no haya una referencia fuerte a la llave. Esto puede ser usado para asociar datos con un objeto apropiado por otras partes de una aplicación sin añadir atributos a esos objetos. Esto puede ser especialmente útil con objetos que sobre escriben atributos de acceso.

Distinto en la versión 3.9: Se agregó soporte para los operadores | y |=, especificados en PEP 584 [https://www.python.org/dev/peps/pep-0584].

Los objetos WeakKeyDictionary tiene un método adicional que expone las referencias internas directamente. Las referencias no tienen garantía de estar con «vida» en el momento en que son usadas, por lo que el resultado de llamar las referencias necesita ser revisado antes de ser usado. Esto puede ser usado para evitar crear referencias que causen que recolector de basura mantenga las llaves en existencia más tiempo del que necesitan.

WeakKeyDictionary.keyrefs()

Retorna un iterable de las referencias débiles a las llaves.

class weakref.WeakValueDictionary([dict])

Clase de mapeado que referencia valores débilmente. Las entradas en el diccionario serán descartadas cuando ya no existan las referencias fuertes a los valores.

Distinto en la versión 3.9: Se agregó soporte para los operadores | y |=, como se especifica en PEP 584 [https://www.python.org/dev/peps/pep-0584].

Los objetos WeakValueDictionary tienen un método adicional que tiene los mismos problemas que el método keyrefs() de los objetos WeakyKeyDictionary.

WeakValueDictionary.valuerefs()

Retorna un iterable de las referencias débiles a los valores.

class weakref.WeakSet([elements])

Clase Conjunto que mantiene referencias débiles a sus elementos. Un elemento será descartado cuando ya no existan referencias fuertes.

class weakref.WeakMethod(method)

Una subclase ref personalizada que simula una referencia débil a un método vinculado (i.e., un método definido en una clase y visto en una instancia). Ya que un método atado es efímero, una referencia débil estándar no puede mantenerlo. El WeakMethod tiene un código especial para recrear el método atado hasta que o el objeto o la función original muera:

>>> class C:
...     def method(self):
...         print("method called!")
...
>>> c = C()
>>> r = weakref.ref(c.method)
>>> r()
>>> r = weakref.WeakMethod(c.method)
>>> r()
<bound method C.method of <__main__.C object at 0x7fc859830220>>
>>> r()()
method called!
>>> del c
>>> gc.collect()
0
>>> r()
>>>

Nuevo en la versión 3.4.

class weakref.finalize(obj, func, /, *args, **kwargs)

Retorna un objeto finalizador invocable que será llamado cuando obj sea recolectado por el recolector de basura. A diferencia de referencias débiles ordinarias, un finalizador siempre sobrevivirá hasta que el objeto de referencia sea recolectado, simplificando enormemente la gestión del ciclo de vida.

Se considera a un finalizador como vivo hasta que sea llamado (o explícitamente o en la recolección de basura), y después que esté muerto. Llamar a un finalizador vivo retorna el resultado de evaluar func(*arg, **kwargs), mientras que llamar a un finalizador muerto retorna None.

Las excepciones lanzadas por retrollamadas de finalizadores durante la recolección de basura serán mostradas en la salida de error estándar, pero no pueden ser propagadas. Son gestionados de la misma forma que las excepciones lanzadas del método __del__() de un objeto o la retrollamada de una referencia débil.

Cuando el programa sale, cada finalizador vivo que quede es llamado a menos que su atributo atexit sea falso. Son llamados en el orden reverso de creación.

Un finalizador nunca invocará su retrollamada durante la última parte del interpreter shutdown cuando los módulos globales están sujetos a ser reemplazados por None.

__call__()

Si self está vivo entonces lo marca como muerto y retorna el resultado de llamar a func(*args, **kwargs). Si self está muerto entonces retorna None.

detach()

Si self está vivo entonces lo marca como muerto y retorna la tupla (obj, func, args, kwargs). Si self está muerto entonces retorna None.

peek()

Si self está vivo entonces retorna la tupla (obj, func, args, kwargs). Si self está muerto entonces retorna None.

alive

Propiedad que es verdadera si el finalizador está vivo, caso contrario, falso.

atexit

Una propiedad booleana con permisos de escritura que por defecto es verdadero. Cuando el programa sale, llama a todos los finalizadores vivos que queden para los cuales atexit es verdadero. Ellos son llamados en el orden reverso de creación.

Nota

Es importante asegurar que func, args y kwargs no sean dueños de ninguna referencia a obj, o directamente o indirectamente, ya que de otra manera obj nunca será recolectado por el recolector de basura. En particular, func no debe ser un método vinculado de obj.

Nuevo en la versión 3.4.

weakref.ReferenceType

El objeto de tipo para objetos de referencias débiles.

weakref.ProxyType

El objeto de tipo para proxies de objetos que no son invocables.

weakref.CallableProxyType

El objeto de tipo para proxies de objetos invocables.

weakref.ProxyTypes

Una secuencia que contiene todos los objetos de tipo para los proxies. Esto puede hacerlo más simple para pruebas si un objeto es un proxy sin ser dependiente en nombrar a ambos tipos proxy.

Ver también

PEP 205 [https://www.python.org/dev/peps/pep-0205] - Referencias Débiles

La propuesta y lógica de esta característica, incluyendo los enlaces a implementaciones tempranas e información acerca de características similares en otros lenguajes.

Objetos de Referencias Débiles

Los objetos de referencias débiles no tiene métodos y atributos aparte de ref.__calback__. Un objeto de referencia débil permite que el referente sea obtenido, si todavía existe, al llamarlo:

>>> import weakref
>>> class Object:
...     pass
...
>>> o = Object()
>>> r = weakref.ref(o)
>>> o2 = r()
>>> o is o2
True

Si el referente no existe, llamar al objeto de referencia retorna None:

>>> del o, o2
>>> print(r())
None

Probar que un objeto de referencia débil está todavía con vida debe ser hecho usando la expresión ref() is not None. Normalmente, el código de aplicación que necesite usar un objeto de referencia debe seguir este patrón:

# r is a weak reference object
o = r()
if o is None:
    # referent has been garbage collected
    print("Object has been deallocated; can't frobnicate.")
else:
    print("Object is still live!")
    o.do_something_useful()

Usar una prueba separada para «vivacidad» crea una condición de carrera en aplicaciones con hilos; otro hilo puede hacer que una referencia débil sea invalidada antes de que la referencia débil sea llamada; El modismo mostrado arriba es seguro en aplicaciones con hilos también como aplicaciones de un sólo hilo.

Versiones especializadas de objetos ref pueden ser creadas a través de creación por subclase. Esto es usado en la implementación de WeakValueDictionary para reducir la memoria elevada por cada entrada en el mapeado. Esto puede ser lo más útil para asociar información adicional con un referencia, pero también puede ser usado para insertar procesamiento adicional en llamadas para recuperar el referente.

Este ejemplo muestra como una subclase de ref puede ser usado para guardar información adicional sobre un objeto y afectar el valor que se retorna cuando el referente es accedido:

import weakref

class ExtendedRef(weakref.ref):
    def __init__(self, ob, callback=None, /, **annotations):
        super().__init__(ob, callback)
        self.__counter = 0
        for k, v in annotations.items():
            setattr(self, k, v)

    def __call__(self):
        """Return a pair containing the referent and the number of
        times the reference has been called.
        """
        ob = super().__call__()
        if ob is not None:
            self.__counter += 1
            ob = (ob, self.__counter)
        return ob

Ejemplo

Este simple ejemplo muestra como una aplicación puede usar objetos ID para recuperar objetos que han sido visto antes. Los ID de los objetos pueden ser usados en otras estructuras de datos sin forzar que los objetos permanezcan con vida, pero los objetos pueden aún pueden ser recuperados por el ID si lo hacen.

import weakref

_id2obj_dict = weakref.WeakValueDictionary()

def remember(obj):
    oid = id(obj)
    _id2obj_dict[oid] = obj
    return oid

def id2obj(oid):
    return _id2obj_dict[oid]

Objetos Finalizadores

El principal beneficio de usar finalize es que hace simple registrar una retrollamada sin necesitar preservar el objeto finalizador retornado. Por ejemplo

>>> import weakref
>>> class Object:
...     pass
...
>>> kenny = Object()
>>> weakref.finalize(kenny, print, "You killed Kenny!")
<finalize object at ...; for 'Object' at ...>
>>> del kenny
You killed Kenny!

El finalizador puede ser llamado directamente también. Sin embargo, el finalizador invocará la retrollamada como máximo una vez.

>>> def callback(x, y, z):
...     print("CALLBACK")
...     return x + y + z
...
>>> obj = Object()
>>> f = weakref.finalize(obj, callback, 1, 2, z=3)
>>> assert f.alive
>>> assert f() == 6
CALLBACK
>>> assert not f.alive
>>> f()                     # callback not called because finalizer dead
>>> del obj                 # callback not called because finalizer dead

Puedes de-registrar un finalizador usando su método detach(). Esto mata el finalizador y retorna los argumentos pasados al constructor cuando fue creado.

>>> obj = Object()
>>> f = weakref.finalize(obj, callback, 1, 2, z=3)
>>> f.detach()
(<...Object object ...>, <function callback ...>, (1, 2), {'z': 3})
>>> newobj, func, args, kwargs = _
>>> assert not f.alive
>>> assert newobj is obj
>>> assert func(*args, **kwargs) == 6
CALLBACK

A menos que pongas el atributo atexit a False, un finalizador será llamado cuando el programa salga si todavía está con vida. Por ejemplo

>>> obj = Object()
>>> weakref.finalize(obj, print, "obj dead or exiting")
<finalize object at ...; for 'Object' at ...>
>>> exit()
obj dead or exiting

Comparando finalizadores con los métodos __del__()

Suponga que queremos crear una clase cuyas instancias representan directorios temporales. Los directorios deben ser eliminados con sus contenidos cuando el primero de los siguiente eventos ocurre:

el objeto es recolectado por el recolector de basura,

el método remove() del objeto es llamado, o

el programa sale.

Nosotros podemos intentar implementar la clase usando el método __del__() como sigue:

class TempDir:
    def __init__(self):
        self.name = tempfile.mkdtemp()

    def remove(self):
        if self.name is not None:
            shutil.rmtree(self.name)
            self.name = None

    @property
    def removed(self):
        return self.name is None

    def __del__(self):
        self.remove()

Empezando con Python 3.4, Los métodos __del__() ya no previenen ciclos de referencia de ser recolectado como basura, y los módulos globales ya no fuerzan None durante interpreter shutdown. Por lo que este código debe trabajar sin ningún problema en CPython.

Sin embargo, la gestión de métodos __del__() es notoriamente específico por la implementación, ya que depende de detalles internos de la implementación del recolector de basura del intérprete.

Una alternativa más robusta puede ser para definir un finalizador que sólo hace referencia a funciones específicas y objetos que necesite, en vez de tener acceso al estado completo del objeto:

class TempDir:
    def __init__(self):
        self.name = tempfile.mkdtemp()
        self._finalizer = weakref.finalize(self, shutil.rmtree, self.name)

    def remove(self):
        self._finalizer()

    @property
    def removed(self):
        return not self._finalizer.alive

Definido así, nuestro finalizador sólo recibe una referencia a los detalles que necesita limpiar los directorios apropiadamente. Si el objeto nueva llega a ser recolectado como basura el finalizador aún será llamado al salir.

La otra ventaja de weakref basados en finalizadores es que ellos pueden ser usados para registrar finalizadores para clases donde la definición es controlado por terceros, como un código que corre cuando un módulo es descargado:

import weakref, sys
def unloading_module():
    # implicit reference to the module globals from the function body
weakref.finalize(sys.modules[__name__], unloading_module)

Nota

Si creas un objeto finalizador en un hilo daemon sólo como el programa sale entonces hay la posibilidad de que el finalizador no llegue a ser llamado. Sin embargo, en un hilo daemonic atexit.register(), try: ... finally: ... y with: ... no garantizan que la limpieza ocurra tampoco.

types — Creación de tipos dinámicos y nombres para tipos integrados

Código fuente: Lib/types.py [https://github.com/python/cpython/tree/3.9/Lib/types.py]

Este módulo define funciones de utilidad para ayudar en la creación dinámica de tipos nuevos.

Este también define nombres para algunos tipos de objetos que son utilizados por el intérprete estándar de Python, pero no expuestos como integrados como lo son int o str.

Por último, este proporciona algunas clases de utilidad y funciones adicionales relacionadas con tipos que no son lo suficientemente fundamentales como para ser integradas.

Creación dinámica de tipos

types.new_class(name, bases=(), kwds=None, exec_body=None)

Crea un objeto de clase dinámicamente utilizando la metaclase adecuada.

Los tres primeros argumentos son los componentes que componen un encabezado de definición de clase: el nombre de la clase, las clases base (en orden), los argumentos por palabra clave (tal como metaclass).

The exec_body argument is a callback that is used to populate the freshly created class namespace. It should accept the class namespace as its sole argument and update the namespace directly with the class contents. If no callback is provided, it has the same effect as passing in lambda ns: None.

Nuevo en la versión 3.3.

types.prepare_class(name, bases=(), kwds=None)

Calcula la metaclase adecuada y crea el espacio de nombre de clase.

Los argumentos son los componentes que constituyen un encabezado de definición de clase: el nombre de la clase, las clases base (en orden) y los argumentos de palabra clave (como metaclass).

El valor retornado es una tupla de 3: metaclass, namespace, kwds

metaclass es la metaclase adecuada, namespace es el espacio de nombre de clase preparado y kwds es una copia actualizada del pasado en el argumento kwds con cualquier entrada 'metaclass' eliminada. Si no se pasa ningún argumento kwds, será un diccionario vacío.

Nuevo en la versión 3.3.

Distinto en la versión 3.6: El valor predeterminado para el elemento namespace de la tupla retornada ha cambiado. Ahora una asignación de inserción-orden-conservación es utilizada cuando la metaclase no tiene un método __prepare__.

Ver también

Metaclases

Detalles completos del proceso de creación de clases soportado por estas funciones

PEP 3115 [https://www.python.org/dev/peps/pep-3115] - Metaclases en Python 3000

Se presenta el hook de espacio de nombres __prepare__

types.resolve_bases(bases)

Resuelve las entradas MRO dinámicamente según lo especificado por PEP 560 [https://www.python.org/dev/peps/pep-0560].

Esta función busca elementos en bases que no son instancias de type y retorna una tupla donde cada uno de estos objetos que tiene un método __mro_entries__ se reemplaza con un resultado desempaquetado de llamar a este método. Si un elemento bases es una instancia de type o no tiene un método __mro_entries__, se incluye en el retorno la tupla sin cambios.

Nuevo en la versión 3.7.

Ver también

PEP 560 [https://www.python.org/dev/peps/pep-0560] - Soporte principal para módulos de tipo y tipos genéricos

Tipos de Intérpretes Estándar

Este módulo proporciona nombres para muchos de los tipos necesarios para implementar un intérprete de Python. Esto evita deliberadamente incluir algunos de los tipos que surgen sólo accidentalmente durante el procesamiento, tal como el tipo listiterator.

El uso típico de estos nombres es para verificar isinstance() o issubclass().

Si se crea una instancia de cualquiera de estos tipos, tenga en cuenta que las firmas pueden variar entre las versiones de Python.

Los nombres estándar son definidos para los siguientes tipos:

types.FunctionType

types.LambdaType

El tipo de funciones definidas por el usuario y funciones creadas por expresiones lambda.

Lanza un auditing event function.__new__ con el argumento code.

El evento auditor solo ocurre para la instanciación directa de objetos de código y no se genera para la compilación normal.

types.GeneratorType

El tipo de iterador generator de objetos, creados por funciones generadoras.

types.CoroutineType

El tipo de objetos coroutine, creados por funciones async def.

Nuevo en la versión 3.5.

types.AsyncGeneratorType

El tipo de iterador asynchronous generator de objetos, creados por funciones generadoras asíncronas.

Nuevo en la versión 3.6.

class types.CodeType(**kwargs)

El tipo de objetos de código cómo los retornados por compile().

Lanza un evento auditor code.__new__ con los argumentos code, filename, name, argcount, posonlyargcount, kwonlyargcount, nlocals, stacksize, flags.

Tenga en cuenta que los argumentos auditados pueden no coincidir con los nombres o posiciones requeridos por el inicializador. El evento auditor solo ocurre para la instanciación directa de objetos de código y no se genera para la compilación normal.

replace(**kwargs)

Retorna una copia del objeto de código con nuevos valores para los campos especificados.

Nuevo en la versión 3.8.

types.CellType

El tipo de objetos de celda: estos objetos se utilizan como contenedores para las variables libres de una función.

Nuevo en la versión 3.8.

types.MethodType

El tipo de métodos de instancias de clase definidas por el usuario.

types.BuiltinFunctionType

types.BuiltinMethodType

El tipo de funciones integradas como len() o sys.exit() y métodos de clases integradas. (Aquí, el término «incorporado» significa «escrito en C».)

types.WrapperDescriptorType

El tipo de métodos de algunos tipos de datos integrados y clases base como object.__init__() o object.__lt__().

Nuevo en la versión 3.7.

types.MethodWrapperType

El tipo de métodos bound de algunos tipos de datos integrados y clases base. Por ejemplo, es el tipo de object().__str__.

Nuevo en la versión 3.7.

types.MethodDescriptorType

El tipo de métodos de algunos tipos de datos integrados como str.join().

Nuevo en la versión 3.7.

types.ClassMethodDescriptorType

El tipo de métodos de clase unbound de algunos tipos de datos integrados como dict.__dict__['fromkeys'].

Nuevo en la versión 3.7.

class types.ModuleType(name, doc=None)

The type of modules. The constructor takes the name of the module to be created and optionally its docstring.

Nota

Utilice importlib.util.module_from_spec() para crear un nuevo módulo si desea establecer los diversos atributos controlados por importación.

__doc__

El docstring del módulo. El valor predeterminado es None.

__loader__

El loader que cargó el módulo. El valor predeterminado es None.

This attribute is to match importlib.machinery.ModuleSpec.loader as stored in the attr:__spec__ object.

Nota

A future version of Python may stop setting this attribute by default. To guard against this potential change, preferably read from the __spec__ attribute instead or use getattr(module, "__loader__", None) if you explicitly need to use this attribute.

Distinto en la versión 3.4: El valor predeterminado es None. Anteriormente el atributo era opcional.

__name__

The name of the module. Expected to match importlib.machinery.ModuleSpec.name.

__package__

A cuál package pertenece un módulo. Si el módulo es de nivel superior (es decir, no una parte de algún paquete específico), el atributo debe establecerse en '', de lo contrario debe establecerse en el nombre del paquete (el cual puede ser __name__ si el módulo es un paquete). El valor predeterminado es None.

This attribute is to match importlib.machinery.ModuleSpec.parent as stored in the attr:__spec__ object.

Nota

A future version of Python may stop setting this attribute by default. To guard against this potential change, preferably read from the __spec__ attribute instead or use getattr(module, "__package__", None) if you explicitly need to use this attribute.

Distinto en la versión 3.4: El valor predeterminado es None. Anteriormente el atributo era opcional.

__spec__

A record of the module’s import-system-related state. Expected to be an instance of importlib.machinery.ModuleSpec.

Nuevo en la versión 3.4.

class types.GenericAlias(t_origin, t_args)

El tipo de parameterized generics como list[int].

t_origin debería ser una clase genérica no parametrizada, como list, tuple o dict. t_args debe ser una tuple (posiblemente de longitud 1) de tipos que parametriza t_origin:

>>> from types import GenericAlias

>>> list[int] == GenericAlias(list, (int,))
True
>>> dict[str, int] == GenericAlias(dict, (str, int))
True

Nuevo en la versión 3.9.

Distinto en la versión 3.9.2: Este tipo ahora puede tener subclases

class types.TracebackType(tb_next, tb_frame, tb_lasti, tb_lineno)

El tipo de objetos traceback tal como los encontrados en sys.exc_info()[2].

Consulte la referencia de lenguaje para obtener detalles de los atributos y operaciones disponibles, y orientación sobre cómo crear tracebacks dinámicamente.

types.FrameType

El tipo de objetos de marco como se encuentra en tb.tb_frame si tb es un objeto traceback.

Consulte la referencia de lenguaje para obtener más información sobre los atributos y operaciones disponibles.

types.GetSetDescriptorType

El tipo de objetos definidos en módulos de extensión con PyGetSetDef, como FrameType.f_locals o array.array.typecode. Este tipo se utiliza como descriptor para los atributos de objeto; tiene el mismo propósito que el tipo property, pero para las clases definidas en los módulos de extensión.

types.MemberDescriptorType

El tipo de objetos definidos en módulos de extensión con PyMemberDef, como datetime.timedelta.days. Este tipo se utiliza como descriptor para miembros de datos C simples que utilizan funciones de conversión estándar; tiene el mismo propósito que el tipo property, pero para las clases definidas en los módulos de extensión.

CPython implementation detail: En otras implementaciones de Python, este tipo puede ser idéntico a GetSetDescriptorType.

class types.MappingProxyType(mapping)

Proxy de solo lectura de un mapeo. Proporciona una vista dinámica en las entradas de la asignación, lo que significa que cuando cambia la asignación, la vista refleja estos cambios.

Nuevo en la versión 3.3.

Distinto en la versión 3.9: Actualizado para soportar el nuevo operador de unión (|) de PEP 584 [https://www.python.org/dev/peps/pep-0584], que simplemente delega al mapeo subyacente.

key in proxy

Retorna True si la asignación subyacente tiene una clave key, de lo contrario False.

proxy[key]

Retorna el elemento de la asignación subyacente con la clave key. Lanza un KeyError si key no está en la asignación subyacente.

iter(proxy)

Retorna un iterador sobre las claves de la asignación subyacente. Este es un método abreviado para iter(proxy.keys()).

len(proxy)

Retorna el número de elementos de la asignación subyacente.

copy()

Retorna una copia superficial de la asignación subyacente.

get(key[, default])

Retorna el valor de key si key está en la asignación subyacente, de lo contrario default. Si no se proporciona default, el valor predeterminado es None, por lo que este método nunca lanza un KeyError.

items()

Retorna una nueva vista de los elementos de la asignación subyacente (en pares (key, value)).

keys()

Retorna una nueva vista de las claves de la asignación subyacente.

values()

Retorna una nueva vista de los valores de la asignación subyacente.

reversed(proxy)

Retorna un iterador inverso sobre las claves de la asignación subyacente.

Nuevo en la versión 3.9.

Clases y funciones de utilidad adicionales

class types.SimpleNamespace

Una subclase simple object que proporciona acceso de atributo a su espacio de nombre, así como una representación significativa.

A diferencia de object, con SimpleNamespace puede agregar y eliminar atributos. Si un objeto SimpleNamespace se inicializa con argumentos de palabra clave, estos se agregan directamente al espacio de nombres subyacente.

El tipo es aproximadamente equivalente al código siguiente:

class SimpleNamespace:
    def __init__(self, /, **kwargs):
        self.__dict__.update(kwargs)

    def __repr__(self):
        items = (f"{k}={v!r}" for k, v in self.__dict__.items())
        return "{}({})".format(type(self).__name__, ", ".join(items))

    def __eq__(self, other):
        if isinstance(self, SimpleNamespace) and isinstance(other, SimpleNamespace):
           return self.__dict__ == other.__dict__
        return NotImplemented

SimpleNamespace puede ser útil como reemplazo para class NS: pass. Sin embargo, para un tipo de registro estructurado, utilice namedtuple() en su lugar.

Nuevo en la versión 3.3.

Distinto en la versión 3.9: El orden de los atributos en el repr cambió de alfabético a orden de inserción (como dict).

types.DynamicClassAttribute(fget=None, fset=None, fdel=None, doc=None)

Acceso de atributo de ruta en una clase para __getattr__.

Se trata de un descriptor, que se utiliza para definir atributos que actúan de forma diferente cuando se accede a través de una instancia y a través de una clase. El acceso a la instancia sigue siendo normal, pero el acceso a un atributo a través de una clase se enrutará al método __getattr__ de la clase; esto se hace lanzando AttributeError.

Esto permite tener propiedades activas en una instancia y tener atributos virtuales en la clase con el mismo nombre (véase enum.Enum para obtener un ejemplo).

Nuevo en la versión 3.4.

Funciones de utilidad de corutina

types.coroutine(gen_func)

Esta función transforma una función generador en una función coroutine que retorna una corrutina basada en un generador. La corrutina basada en un generador sigue siendo un generator iterator, pero también se considera un objeto coroutine y es awaitable. Sin embargo, no puede necesariamente implementar el método __await__().

Si gen_func es una función generadora, se modificará en el lugar.

Si gen_func no es una función generadora, se envolverá. Si retorna una instancia de collections.abc.Generator, la instancia se ajustará en un objeto proxy awaitable. Todos los demás tipos de objetos se retornarán tal cual.

Nuevo en la versión 3.5.

copy — Operaciones de copia superficial y profunda

Source code: Lib/copy.py [https://github.com/python/cpython/tree/3.9/Lib/copy.py]

Las declaraciones de asignación en Python no copian objetos, crean enlaces entre un objetivo y un objeto. Para colecciones que son mutables o que contienen elementos mutables, a veces se necesita una copia para que uno pueda cambiar una copia sin cambiar la otra. Este módulo proporciona operaciones genéricas de copia superficial y profunda (explicadas a continuación).

Resumen de la interfaz:

copy.copy(x)

Retorna una copia superficial de x.

copy.deepcopy(x[, memo])

Retorna una copia profunda de x.

exception copy.Error

Levantado para errores específicos del módulo.

La diferencia entre copia superficial y profunda solo es relevante para objetos compuestos (objetos que contienen otros objetos, como listas o instancias de clase):

Una copia superficial (shallow copy) construye un nuevo objeto compuesto y luego (en la medida de lo posible) inserta references en él a los objetos encontrados en el original.

Una copia profunda (deep copy) construye un nuevo objeto compuesto y luego, recursivamente, inserta copias en él de los objetos encontrados en el original.

A menudo existen dos problemas con las operaciones de copia profunda que no existen con las operaciones de copia superficial:

Los objetos recursivos (objetos compuestos que, directa o indirectamente, contienen una referencia a sí mismos) pueden causar un bucle recursivo.

Debido a que la copia profunda copia todo, puede copiar demasiado, como los datos que deben compartirse entre copias.

La función deepcopy() evita estos problemas al:

mantener un diccionario memo de objetos ya copiados durante la pasada de copia actual; y

dejando que las clases definidas por el usuario anulen la operación de copia o el conjunto de componentes copiados.

This module does not copy types like module, method, stack trace, stack frame, file, socket, window, or any similar types. It does «copy» functions and classes (shallow and deeply), by returning the original object unchanged; this is compatible with the way these are treated by the pickle module.

Se pueden hacer copias superficiales de los diccionarios usando dict.copy(), y de las listas mediante la asignación de una porción de la lista completa, por ejemplo, copied_list = original_list[:].

Las clases pueden usar las mismas interfaces para controlar la copia que usan para controlar el pickling. Consulte la descripción del módulo pickle para obtener información sobre estos métodos. De hecho, el módulo copy utiliza las funciones de pickle registradas del módulo copyreg.

Para que una clase defina su propia implementación de copia, puede definir métodos especiales __copy__() y __deepcopy__(). El primero se llama para implementar la operación de copia superficial; no se pasan argumentos adicionales. Este último está llamado a implementar la operación de copia profunda; se pasa un argumento, el diccionario memo. Si la implementación __deepcopy__() necesita hacer una copia profunda de un componente, debe llamar a la función deepcopy() con el componente como primer argumento y el diccionario memo como segundo argumento.

Ver también

Módulo pickle

Discusión de los métodos especiales utilizados para apoyar la recuperación y restauración del estado del objeto.

pprint — Impresión bonita de datos

Código fuente: Lib/pprint.py [https://github.com/python/cpython/tree/3.9/Lib/pprint.py]

El módulo pprint proporciona la capacidad de «imprimir de forma bonita» estructuras de datos arbitrarias de Python de manera que se puede utilizar como entrada para el intérprete. Si las estructuras formateadas incluyen objetos que no son tipos fundamentales de Python, es posible que la representación no sea válida como tal para el intérprete. Esto puede darse si se incluyen objetos como archivos, sockets o clases, así como muchos otros objetos que no se pueden representar como literales de Python.

La representación formateada mantiene los objetos en una sola línea siempre que sea posible y los divide en varias líneas si no encajan dentro del ancho permitido. Se deben crear objetos PrettyPrinter de forma explícita si se necesita ajustar la restricción de ancho.

Los diccionarios se ordenan por clave antes de que se calcule la representación en pantalla.

Distinto en la versión 3.9: Added support for pretty-printing types.SimpleNamespace.

El módulo pprint define una sola clase:

class pprint.PrettyPrinter(indent=1, width=80, depth=None, stream=None, *, compact=False, sort_dicts=True)

Construye una instancia de PrettyPrinter. Este constructor acepta varios argumento por palabra clave. Se puede establecer un flujo de salida usando la palabra clave stream; el único método utilizado en el objeto stream es el método write() del protocolo de archivo. Si no se especifica, PrettyPrinter adopta sys.stdout por defecto. La cantidad de sangría agregada para cada nivel recursivo se especifica mediante indent; por defecto es uno. Otros valores pueden hacer que la salida se vea un poco extraña, pero pueden hacer más fácil la visualización de los anidamientos. El número de niveles que se pueden mostrar se controla mediante depth; si la estructura de datos que se muestra es demasiado profunda, el siguiente nivel contenido se reemplaza por .... De forma predeterminada, no hay restricciones en la profundidad de los objetos que se formatean. El ancho de salida deseado se restringe mediante el parámetro width; el valor predeterminado es 80 caracteres. Si no se puede formatear una estructura dentro del límite de ancho establecido, se ajustará lo mejor posible. Si compact es False (el valor por defecto), cada elemento de una secuencia larga se formateará en una línea separada. Si compact es True, en cada linea de salida se formatearán todos los elementos que quepan dentro del ancho definido. Si sort_dicts es True (el valor por defecto), los diccionarios se formatearán con sus claves ordenadas; de lo contrario, se mostrarán según orden de inserción.

Distinto en la versión 3.4: Añadido el argumento compact.

Distinto en la versión 3.8: Añadido el argumento sort_dicts.

>>> import pprint
>>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
>>> stuff.insert(0, stuff[:])
>>> pp = pprint.PrettyPrinter(indent=4)
>>> pp.pprint(stuff)
[   ['spam', 'eggs', 'lumberjack', 'knights', 'ni'],
    'spam',
    'eggs',
    'lumberjack',
    'knights',
    'ni']
>>> pp = pprint.PrettyPrinter(width=41, compact=True)
>>> pp.pprint(stuff)
[['spam', 'eggs', 'lumberjack',
  'knights', 'ni'],
 'spam', 'eggs', 'lumberjack', 'knights',
 'ni']
>>> tup = ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead',
... ('parrot', ('fresh fruit',))))))))
>>> pp = pprint.PrettyPrinter(depth=6)
>>> pp.pprint(tup)
('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead', (...)))))))

El módulo pprint también proporciona varias funciones de atajo:

pprint.pformat(object, indent=1, width=80, depth=None, *, compact=False, sort_dicts=True)

Retorna la representación formateada de object como una cadena de caracteres. indent, width, depth, compact y sort_dicts se pasarán al constructor de PrettyPrinter como parámetros de formato.

Distinto en la versión 3.4: Añadido el argumento compact.

Distinto en la versión 3.8: Añadido el argumento sort_dicts.

pprint.pp(object, *args, sort_dicts=False, **kwargs)

Imprime la representación formateada de object seguida de una nueva línea. Si sort_dicts es False (el valor por defecto), los diccionarios se mostrarán con sus claves según orden de inserción, de lo contrario, las claves del diccionario serán ordenadas. args y kwargs se pasarán a pprint() como parámetros de formato.

Nuevo en la versión 3.8.

pprint.pprint(object, stream=None, indent=1, width=80, depth=None, *, compact=False, sort_dicts=True)

Imprime la representación formateada de object en stream, seguida de una nueva línea. Si stream es None, se usa sys.stdout. Esta función se puede usar en el intérprete interactivo en lugar de la función print() para inspeccionar valores (incluso puedes reasignar print = pprint.pprint para su uso dentro del ámbito). indent, width, depth, compact y sort_dicts se pasarán al constructor de PrettyPrinter como parámetros de formato.

Distinto en la versión 3.4: Añadido el argumento compact.

Distinto en la versión 3.8: Añadido el argumento sort_dicts.

>>> import pprint
>>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
>>> stuff.insert(0, stuff)
>>> pprint.pprint(stuff)
[<Recursion on list with id=...>,
 'spam',
 'eggs',
 'lumberjack',
 'knights',
 'ni']

pprint.isreadable(object)

Determina si la representación formateada de object es «legible» o si puede usarse para reconstruir el objeto usando eval(). Siempre retorna False para objetos recursivos.

>>> pprint.isreadable(stuff)
False

pprint.isrecursive(object)

Determina si object requiere una representación recursiva.

Una función extra de soporte es también definida:

pprint.saferepr(object)

Retorna una representación en forma de cadena de caracteres de object, que está protegida contra estructuras de datos recursivas. Si la representación de object presenta una entrada recursiva, dicha referencia recursiva se representará como <Recursion on typename with id=number>. Además, la representación no tendrá otro formato.

>>> pprint.saferepr(stuff)
"[<Recursion on list with id=...>, 'spam', 'eggs', 'lumberjack', 'knights', 'ni']"

Objetos PrettyPrinter

Las instancias de PrettyPrinter tienen los siguientes métodos:

PrettyPrinter.pformat(object)

Retorna la representación formateada de object. Tiene en cuenta las opciones pasadas al constructor de la clase PrettyPrinter.

PrettyPrinter.pprint(object)

Imprime la representación formateada de object en la secuencia configurada, seguida de una nueva línea.

Los siguientes métodos proporcionan las implementaciones para las funciones correspondientes con los mismos nombres. Usar estos métodos en una instancia es algo más eficiente, ya que no es necesario crear nuevos objetos PrettyPrinter.

PrettyPrinter.isreadable(object)

Determina si la representación formateada de object es «legible» o si se puede usar para reconstruir su valor usando eval(). Se debe tener en cuenta que se retorna False para objetos recursivos. Si el parámetro depth de PrettyPrinter es proporcionado y el objeto es más profundo de lo permitido, también se retorna False.

PrettyPrinter.isrecursive(object)

Determina si object requiere una representación recursiva.

Este método se proporciona como un punto de entrada o método de enlace automático (hook en inglés) para permitir que las subclases modifiquen la forma en que los objetos se convierten en cadenas de caracteres. La implementación por defecto utiliza la implementación interna de saferepr().

PrettyPrinter.format(object, context, maxlevels, level)

Retorna tres valores: la versión formateada de object como una cadena de caracteres, una bandera que indica si el resultado es legible y una bandera que indica si se detectó recursividad. El primer argumento es el objeto a representar. El segundo es un diccionario que contiene la id() de los objetos que son parte del contexto de representación actual (contenedores directos e indirectos para object que están afectando a la representación), como las claves; si es necesario representar un objeto que ya está representado en context, el tercer valor de retorno será True. Las llamadas recursivas al método format() deben agregar entradas adicionales a los contenedores de este diccionario. El tercer argumento, maxlevels, proporciona el límite máximo de recursividad; su valor por defecto es 0. Este argumento debe pasarse sin modificaciones a las llamadas recursivas. El cuarto argumento, level, da el nivel actual; las llamadas recursivas sucesivas deben pasar un valor menor que el de la llamada actual.

Ejemplo

Para demostrar varios usos de la función pprint() y sus parámetros, busquemos información sobre un proyecto en PyPI [https://pypi.org]:

>>> import json
>>> import pprint
>>> from urllib.request import urlopen
>>> with urlopen('https://pypi.org/pypi/sampleproject/json') as resp:
...     project_info = json.load(resp)['info']

En su forma básica, la función pprint() muestra el objeto completo:

>>> pprint.pprint(project_info)
{'author': 'The Python Packaging Authority',
 'author_email': 'pypa-dev@googlegroups.com',
 'bugtrack_url': None,
 'classifiers': ['Development Status :: 3 - Alpha',
                 'Intended Audience :: Developers',
                 'License :: OSI Approved :: MIT License',
                 'Programming Language :: Python :: 2',
                 'Programming Language :: Python :: 2.6',
                 'Programming Language :: Python :: 2.7',
                 'Programming Language :: Python :: 3',
                 'Programming Language :: Python :: 3.2',
                 'Programming Language :: Python :: 3.3',
                 'Programming Language :: Python :: 3.4',
                 'Topic :: Software Development :: Build Tools'],
 'description': 'A sample Python project\n'
                '=======================\n'
                '\n'
                'This is the description file for the project.\n'
                '\n'
                'The file should use UTF-8 encoding and be written using '
                'ReStructured Text. It\n'
                'will be used to generate the project webpage on PyPI, and '
                'should be written for\n'
                'that purpose.\n'
                '\n'
                'Typical contents for this file would include an overview of '
                'the project, basic\n'
                'usage examples, etc. Generally, including the project '
                'changelog in here is not\n'
                'a good idea, although a simple "What\'s New" section for the '
                'most recent version\n'
                'may be appropriate.',
 'description_content_type': None,
 'docs_url': None,
 'download_url': 'UNKNOWN',
 'downloads': {'last_day': -1, 'last_month': -1, 'last_week': -1},
 'home_page': 'https://github.com/pypa/sampleproject',
 'keywords': 'sample setuptools development',
 'license': 'MIT',
 'maintainer': None,
 'maintainer_email': None,
 'name': 'sampleproject',
 'package_url': 'https://pypi.org/project/sampleproject/',
 'platform': 'UNKNOWN',
 'project_url': 'https://pypi.org/project/sampleproject/',
 'project_urls': {'Download': 'UNKNOWN',
                  'Homepage': 'https://github.com/pypa/sampleproject'},
 'release_url': 'https://pypi.org/project/sampleproject/1.2.0/',
 'requires_dist': None,
 'requires_python': None,
 'summary': 'A sample Python project',
 'version': '1.2.0'}

El resultado puede limitarse a una cierta profundidad asignando un valor al argumento depth (... se utiliza para contenidos más «profundos»):

>>> pprint.pprint(project_info, depth=1)
{'author': 'The Python Packaging Authority',
 'author_email': 'pypa-dev@googlegroups.com',
 'bugtrack_url': None,
 'classifiers': [...],
 'description': 'A sample Python project\n'
                '=======================\n'
                '\n'
                'This is the description file for the project.\n'
                '\n'
                'The file should use UTF-8 encoding and be written using '
                'ReStructured Text. It\n'
                'will be used to generate the project webpage on PyPI, and '
                'should be written for\n'
                'that purpose.\n'
                '\n'
                'Typical contents for this file would include an overview of '
                'the project, basic\n'
                'usage examples, etc. Generally, including the project '
                'changelog in here is not\n'
                'a good idea, although a simple "What\'s New" section for the '
                'most recent version\n'
                'may be appropriate.',
 'description_content_type': None,
 'docs_url': None,
 'download_url': 'UNKNOWN',
 'downloads': {...},
 'home_page': 'https://github.com/pypa/sampleproject',
 'keywords': 'sample setuptools development',
 'license': 'MIT',
 'maintainer': None,
 'maintainer_email': None,
 'name': 'sampleproject',
 'package_url': 'https://pypi.org/project/sampleproject/',
 'platform': 'UNKNOWN',
 'project_url': 'https://pypi.org/project/sampleproject/',
 'project_urls': {...},
 'release_url': 'https://pypi.org/project/sampleproject/1.2.0/',
 'requires_dist': None,
 'requires_python': None,
 'summary': 'A sample Python project',
 'version': '1.2.0'}

Además, se puede establecer un valor máximo de caracteres por línea asignando un valor al parámetro width. Si un objeto largo no se puede dividir, el valor dado al ancho se anulará y será excedido:

>>> pprint.pprint(project_info, depth=1, width=60)
{'author': 'The Python Packaging Authority',
 'author_email': 'pypa-dev@googlegroups.com',
 'bugtrack_url': None,
 'classifiers': [...],
 'description': 'A sample Python project\n'
                '=======================\n'
                '\n'
                'This is the description file for the '
                'project.\n'
                '\n'
                'The file should use UTF-8 encoding and be '
                'written using ReStructured Text. It\n'
                'will be used to generate the project '
                'webpage on PyPI, and should be written '
                'for\n'
                'that purpose.\n'
                '\n'
                'Typical contents for this file would '
                'include an overview of the project, '
                'basic\n'
                'usage examples, etc. Generally, including '
                'the project changelog in here is not\n'
                'a good idea, although a simple "What\'s '
                'New" section for the most recent version\n'
                'may be appropriate.',
 'description_content_type': None,
 'docs_url': None,
 'download_url': 'UNKNOWN',
 'downloads': {...},
 'home_page': 'https://github.com/pypa/sampleproject',
 'keywords': 'sample setuptools development',
 'license': 'MIT',
 'maintainer': None,
 'maintainer_email': None,
 'name': 'sampleproject',
 'package_url': 'https://pypi.org/project/sampleproject/',
 'platform': 'UNKNOWN',
 'project_url': 'https://pypi.org/project/sampleproject/',
 'project_urls': {...},
 'release_url': 'https://pypi.org/project/sampleproject/1.2.0/',
 'requires_dist': None,
 'requires_python': None,
 'summary': 'A sample Python project',
 'version': '1.2.0'}

reprlib — Implementación repr() alternativa

Código fuente: Lib/reprlib.py [https://github.com/python/cpython/tree/3.9/Lib/reprlib.py]

El módulo reprlib provee de los medios necesarios para producir representaciones de objetos con límites en el tamaño de las cadenas resultantes. Es usado en el depurador de Python y puede ser útil también en otros contextos.

Este módulo provee una clase, una instancia y una función:

class reprlib.Repr

Clase que provee de servicios de formateo útiles en la implementación de funciones similar a la integrada repr(); los límites de tamaño para diferentes tipos de objetos son añadidos para evitar la generación de representaciones que son excesivamente largas.

reprlib.aRepr

Esta es una instancia de Repr que es usada para proveer la función repr() descrita debajo. Cambiar los atributos de este objeto afectará los límites de tamaño usados por repr() y el depurador de Python.

reprlib.repr(obj)

Este es el método repr() de aRepr. Retorna una cadena similar a la retornada por la función integrada del mismo nombre, pero con límites en la mayoría de tamaños.

Además de las herramientas de limitación de tamaño, el módulo también provee un decorador para detectar invocaciones recursivas a __repr__() y sustituyendo por un marcador de posición de cadena en su lugar.

@reprlib.recursive_repr(fillvalue="...")

Decorador para métodos __repr__() que detecta invocaciones recursivas dentro del mismo hilo. Si se produce una invocación recursiva, el fillvalue es retornado, si no, se produce la invocación __repr__() habitual. Por ejemplo:

>>> from reprlib import recursive_repr
>>> class MyList(list):
...     @recursive_repr()
...     def __repr__(self):
...         return '<' + '|'.join(map(repr, self)) + '>'
...
>>> m = MyList('abc')
>>> m.append(m)
>>> m.append('x')
>>> print(m)
<'a'|'b'|'c'|...|'x'>

Nuevo en la versión 3.2.

Objetos Repr

Las instancias Repr proveen varios atributos que pueden ser usados para proporcionar límites de tamaño para las representaciones de diferentes tipos de objetos, y métodos que formatean tipos de objetos específicos.

Repr.maxlevel

Límite de profundidad en la creación de representaciones recursivas. El valor por defecto es 6.

Repr.maxdict

Repr.maxlist

Repr.maxtuple

Repr.maxset

Repr.maxfrozenset

Repr.maxdeque

Repr.maxarray

Límites en el número de entradas representadas por el tipo de objeto nombrado. El valor por defecto es 4 para maxdict, 5 para maxarray, y 6 para los otros.

Repr.maxlong

Máximo número de caracteres en la representación para un entero. Los dígitos son eliminados desde el medio. El valor por defecto es 40.

Repr.maxstring

Límite en el número de caracteres en la representación de la cadena. Fíjese que la representación «normal» de la cadena es la usada como la fuente de caracteres: si se necesitan secuencias de escape en la representación, estas pueden ser desordenadas cuando la representación se ha acortado. El valor por defecto es 30.

Repr.maxother

Este límite es usado para controlar el tamaño de los tipos de objetos para los cuales no hay ningún método de formateo específico en el objeto Repr. Se aplica de una manera similar a maxstring. El valor por defecto es 20.

Repr.repr(obj)

El equivalente a la función integrada repr() que usa el formateo impuesto por la instancia.

Repr.repr1(obj, level)

Implementación recursiva usada por repr(). Este usa el tipo de obj para determinar qué método invocar, pasándole obj y level. Los métodos de tipo específico deben invocar repr1() para realizar formateo recursivo, con level - 1 para el valor de level en la invocación recursiva.

Repr.repr_TYPE(obj, level)

Métodos de formateo para tipos específicos son implementados como métodos con un nombre basado en el nombre del tipo. En el nombre del método, TYPE es reemplazado por '_'.join(type(obj).__name__.split()). El envío a estos métodos es gestionado por repr1(). Los métodos de tipo específico que necesitan formatear recursivamente un valor deben invocar self.repr1(subobj, level - 1).

Subclasificando Objetos Repr

El uso de envíos dinámicos por Repr.repr1() permite a las subclases de Repr añadir soporte para tipos adicionales de objetos integrados o modificar el manejo de tipos ya soportados. Este ejemplo muestra como el soporte especial para objetos de tipo archivo puede ser añadido.

import reprlib
import sys

class MyRepr(reprlib.Repr):

    def repr_TextIOWrapper(self, obj, level):
        if obj.name in {'<stdin>', '<stdout>', '<stderr>'}:
            return obj.name
        return repr(obj)

aRepr = MyRepr()
print(aRepr.repr(sys.stdin))         # prints '<stdin>'

enum — Soporte para enumeraciones

Nuevo en la versión 3.4.

Código fuente: Lib/enum.py [https://github.com/python/cpython/tree/3.9/Lib/enum.py]

Una enumeración es un conjunto de nombres simbólicos (miembros) vinculados a valores únicos y constantes. Dentro de una enumeración, los miembros se pueden comparar por identidad, y la enumeración en sí se puede iterar.

Nota

Caso de miembros de Enum

Debido a que las enumeraciones se usan para representar constantes, recomendamos usar nombres UPPER_CASE para los miembros de enumeración, y usaremos ese estilo en nuestros ejemplos.

Contenido del Módulo

Este módulo define cuatro clases de enumeración que se pueden usar para definir conjuntos únicos de nombres y valores: Enum, IntEnum, Flag, and IntFlag. También define un decorador, unique(), y un ayudante, auto.

class enum.Enum

Clase base para crear constantes enumeradas. Consulte la sección API Funcional para obtener una sintaxis de construcción alternativa.

class enum.IntEnum

Clase base para crear constantes enumeradas que también son sub clases de int.

class enum.IntFlag

Clase base para crear constantes enumeradas que se pueden combinar usando los operadores bitwise sin perder su membresía IntFlag. Los miembros de IntFlag también son subclases de int.

class enum.Flag

Clase base para crear constantes enumeradas que se pueden combinar utilizando las operaciones bitwise sin perder su membresía Flag.

enum.unique()

El decorador de clase Enum que garantiza que solo un nombre esté vinculado a cualquier valor.

class enum.auto

Las instancias se reemplazan con un valor apropiado para los miembros de Enum. El valor inicial comienza en 1.

Nuevo en la versión 3.6: Flag, IntFlag, auto

Creando un Enum

Las enumeraciones son creadas usando la sintaxis class, lo que las hace de fácil lectura y escritura. Un método de creación alternativo se describe en API Funcional. Para definir una enumeración, hacer una subclase Enum de la siguiente manera:

>>> from enum import Enum
>>> class Color(Enum):
...     RED = 1
...     GREEN = 2
...     BLUE = 3
...

Nota

Valores de miembros de Enum

Los valores de los miembros pueden ser cualquier cosa: int, str, etc.. Si el valor exacto no es importante, puede usar instancias auto y se elegirá un valor apropiado para usted. Se debe tener cuidado si se mezcla auto con otros valores.

Nota

Nomenclatura

La clase Color es una enumeración (o enum)

Los atributos Color.RED, Color.GREEN, etc., son miembros de enumeración (o miembros de enum) y son funcionalmente constantes.

Los miembros de la enumeración tienen nombres y valores (el nombre de Color.RED es ROJO, el valor de Color.BLUE es 3, etc. )

Nota

Aunque usamos la sintaxis class para crear Enums, los Enums no son clases normales de Python. Consulte ¿En qué se diferencian las enumeraciones? para obtener más detalles.

Los miembros de la enumeración tienen representaciones de cadenas legibles para humanos

>>> print(Color.RED)
Color.RED

…mientras que su repr tiene más información

>>> print(repr(Color.RED))
<Color.RED: 1>

El tipo de un miembro de enumeración es la enumeración a la que pertenece:

>>> type(Color.RED)
<enum 'Color'>
>>> isinstance(Color.GREEN, Color)
True
>>>

Los miembros de Enum también tienen una propiedad que contiene solo su nombre del elemento

>>> print(Color.RED.name)
RED

Las enumeraciones soportan iteración, en orden de definición:

>>> class Shake(Enum):
...     VANILLA = 7
...     CHOCOLATE = 4
...     COOKIES = 9
...     MINT = 3
...
>>> for shake in Shake:
...     print(shake)
...
Shake.VANILLA
Shake.CHOCOLATE
Shake.COOKIES
Shake.MINT

Los miembros de la enumeración son hasheables, por lo que pueden usarse en diccionarios y conjuntos:

>>> apples = {}
>>> apples[Color.RED] = 'red delicious'
>>> apples[Color.GREEN] = 'granny smith'
>>> apples == {Color.RED: 'red delicious', Color.GREEN: 'granny smith'}
True

Acceso programático a los miembros de la enumeración y sus atributos

A veces es útil acceder a los miembros en enumeraciones mediante programación (es decir, situaciones en las que Color.RED no funcionará porque no se conoce el color exacto al momento de escribir el programa). Enum permite dicho acceso:

>>> Color(1)
<Color.RED: 1>
>>> Color(3)
<Color.BLUE: 3>

Si desea acceder a los miembros de enumeración por nombre, use el acceso a elementos:

>>> Color['RED']
<Color.RED: 1>
>>> Color['GREEN']
<Color.GREEN: 2>

Si tiene un miembro enum y necesita su name o value:

>>> member = Color.RED
>>> member.name
'RED'
>>> member.value
1

Duplicando miembros y valores enum

Tener dos miembros enum con el mismo nombre no es válido:

>>> class Shape(Enum):
...     SQUARE = 2
...     SQUARE = 3
...
Traceback (most recent call last):
...
TypeError: Attempted to reuse key: 'SQUARE'

Sin embargo, se permite que dos miembros enum tengan el mismo valor. Dado que dos miembros A y B tienen el mismo valor (y A se definió primero), B es un alias de A. La búsqueda por valor del valor de A y B retornará A. La búsqueda por nombre de B también retornará A:

>>> class Shape(Enum):
...     SQUARE = 2
...     DIAMOND = 1
...     CIRCLE = 3
...     ALIAS_FOR_SQUARE = 2
...
>>> Shape.SQUARE
<Shape.SQUARE: 2>
>>> Shape.ALIAS_FOR_SQUARE
<Shape.SQUARE: 2>
>>> Shape(2)
<Shape.SQUARE: 2>

Nota

Intentar crear un miembro con el mismo nombre que un atributo ya definido (otro miembro, un método, etc.) o intentar crear un atributo con el mismo nombre que un miembro no está permitido.

Garantizando valores de enumeración únicos

Por defecto, las enumeraciones permiten múltiples nombres como alias para el mismo valor. Cuando no se desea este comportamiento, se puede usar el siguiente decorador para garantizar que cada valor se use solo una vez en la enumeración:

@enum.unique

Un decorador de class específicamente para enumeraciones. Busca una enumeración __members__ reuniendo cualquier alias que encuentre; si no se encuentra alguno se genera un ValueError con los detalles:

>>> from enum import Enum, unique
>>> @unique
... class Mistake(Enum):
...     ONE = 1
...     TWO = 2
...     THREE = 3
...     FOUR = 3
...
Traceback (most recent call last):
...
ValueError: duplicate values found in <enum 'Mistake'>: FOUR -> THREE

Usando valores automáticos

Si el valor exacto no es importante, puede usar auto:

>>> from enum import Enum, auto
>>> class Color(Enum):
...     RED = auto()
...     BLUE = auto()
...     GREEN = auto()
...
>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Los valores se eligen por _generate_next_value_(), que se puede invalidar:

>>> class AutoName(Enum):
...     def _generate_next_value_(name, start, count, last_values):
...         return name
...
>>> class Ordinal(AutoName):
...     NORTH = auto()
...     SOUTH = auto()
...     EAST = auto()
...     WEST = auto()
...
>>> list(Ordinal)
[<Ordinal.NORTH: 'NORTH'>, <Ordinal.SOUTH: 'SOUTH'>, <Ordinal.EAST: 'EAST'>, <Ordinal.WEST: 'WEST'>]

Nota

El objetivo del método predeterminado _generate_next_value_() es proporcionar el siguiente int en secuencia con el último int proporcionado, pero la forma en que lo hace es un detalle de implementación y puede cambiar.

Nota

El método _generate_next_value_() debe definirse antes que cualquier miembro.

Iteración

Iterar sobre los miembros de una enumeración no proporciona los alias:

>>> list(Shape)
[<Shape.SQUARE: 2>, <Shape.DIAMOND: 1>, <Shape.CIRCLE: 3>]

El atributo especial __members__ es una asignación ordenada de solo lectura de nombres a miembros. Incluye todos los nombres definidos en la enumeración, incluidos los alias:

>>> for name, member in Shape.__members__.items():
...     name, member
...
('SQUARE', <Shape.SQUARE: 2>)
('DIAMOND', <Shape.DIAMOND: 1>)
('CIRCLE', <Shape.CIRCLE: 3>)
('ALIAS_FOR_SQUARE', <Shape.SQUARE: 2>)

El atributo __members__ se puede usar para el acceso programático detallado a los miembros de la enumeración. Por ejemplo, encontrar todos los alias:

>>> [name for name, member in Shape.__members__.items() if member.name != name]
['ALIAS_FOR_SQUARE']

Comparaciones

Los miembros de la enumeración se comparan por identidad:

>>> Color.RED is Color.RED
True
>>> Color.RED is Color.BLUE
False
>>> Color.RED is not Color.BLUE
True

Las comparaciones ordenadas entre valores de enumeración no son soportadas. Los miembros de Enum no son enteros (pero vea IntEnum a continuación):

>>> Color.RED < Color.BLUE
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: '<' not supported between instances of 'Color' and 'Color'

Aunque, las comparaciones de igualdad se definen:

>>> Color.BLUE == Color.RED
False
>>> Color.BLUE != Color.RED
True
>>> Color.BLUE == Color.BLUE
True

Las comparaciones con valores de no enumeración siempre se compararán no iguales (de nuevo, IntEnum fue diseñado explícitamente para comportarse de manera diferente, ver más abajo):

>>> Color.BLUE == 2
False

Miembros permitidos y atributos de enumeraciones

Los ejemplos anteriores usan números enteros para los valores de enumeración. El uso de enteros es breve y útil (y lo proporciona de forma predeterminada la API Funcional), pero no se aplica estrictamente. En la gran mayoría de los casos de uso, a uno no le importa cuál es el valor real de una enumeración. Pero si el valor es importante, las enumeraciones pueden tener valores arbitrarios.

Las enumeraciones son clases de Python y pueden tener métodos y métodos especiales como de costumbre. Si tenemos esta enumeración

>>> class Mood(Enum):
...     FUNKY = 1
...     HAPPY = 3
...
...     def describe(self):
...         # self is the member here
...         return self.name, self.value
...
...     def __str__(self):
...         return 'my custom str! {0}'.format(self.value)
...
...     @classmethod
...     def favorite_mood(cls):
...         # cls here is the enumeration
...         return cls.HAPPY
...

Después:

>>> Mood.favorite_mood()
<Mood.HAPPY: 3>
>>> Mood.HAPPY.describe()
('HAPPY', 3)
>>> str(Mood.FUNKY)
'my custom str! 1'

Las reglas para lo que está permitido son las siguientes: los nombres que comienzan y terminan con un solo guión bajo están reservados por enum y no se pueden usar; todos los demás atributos definidos dentro de una enumeración se convertirán en miembros de esta enumeración, con la excepción de métodos especiales (__str__(), __add__(), etc.), descriptores (los métodos también son descriptores) y nombres de variables listado en _ignore_.

Nota: si tu enumeración define __new__() o __init__(), los valores que se hayan dado al miembro enum se pasarán a esos métodos. Ver Planet para un ejemplo.

Subclases restringidas de Enum

Una nueva clase Enum debe tener una clase base Enum, hasta un tipo de datos concreto, y tantas clases mixin basadas en object como sean necesarias. El orden de estas clases base es:

class EnumName([mix-in, ...,] [data-type,] base-enum):
    pass

Además, la subclasificación de una enumeración solo está permitida si la enumeración no define ningún miembro. Entonces esto está prohibido:

>>> class MoreColor(Color):
...     PINK = 17
...
Traceback (most recent call last):
...
TypeError: Cannot extend enumerations

Pero esto es permitido:

>>> class Foo(Enum):
...     def some_behavior(self):
...         pass
...
>>> class Bar(Foo):
...     HAPPY = 1
...     SAD = 2
...

Permitir la subclasificación de enumeraciones que definen miembros conduciría a una violación de algunos invariantes importantes de tipos e instancias. Por otro lado, tiene sentido permitir compartir un comportamiento común entre un grupo de enumeraciones. (Ver OrderedEnum para un ejemplo.)

Serialización

Las enumeraciones se pueden serializar y desempaquetar:

>>> from test.test_enum import Fruit
>>> from pickle import dumps, loads
>>> Fruit.TOMATO is loads(dumps(Fruit.TOMATO))
True

Se aplican las restricciones habituales para la serialización (pickling): las enum seleccionables se deben definir en el nivel superior de un módulo, ya que el desempaquetado requiere que sean importables desde ese módulo.

Nota

Con la versión 4 del protocolo de serialización (pickle), es posible seleccionar fácilmente las enumeraciones anidadas en otras clases.

Es posible modificar la forma en que los miembros de Enum se serializan/desempaquetan definiendo __reduce_ex__() en la clase de enumeración.

API Funcional

La clase Enum es invocable, proporcionando la siguiente API funcional:

>>> Animal = Enum('Animal', 'ANT BEE CAT DOG')
>>> Animal
<enum 'Animal'>
>>> Animal.ANT
<Animal.ANT: 1>
>>> Animal.ANT.value
1
>>> list(Animal)
[<Animal.ANT: 1>, <Animal.BEE: 2>, <Animal.CAT: 3>, <Animal.DOG: 4>]

La semántica de esta API se parece a namedtuple. El primer argumento de la llamada a Enum es el nombre de la enumeración.

El segundo argumento es la fuente de los nombres de los miembros de la enumeración. Puede se una cadena de nombres separados por espacios en blanco, una secuencia de 2 tuplas con pares de clave/valor, o un mapeo de nombres y valores (ej. diccionario). Las últimas dos opciones permiten asignar valores arbitrarios a las enumeraciones; los otros asignan automáticamente enteros crecientes comenzando con 1 (use el parámetros start para especificar un valor de inicio diferente). Se regresa una nueva clase derivada de Enum. En otras palabras, la asignación de arriba Animal es equivalente a:

>>> class Animal(Enum):
...     ANT = 1
...     BEE = 2
...     CAT = 3
...     DOG = 4
...

La razón por la que el valor predeterminado es 1 como numero inicial y no 0 es que 0 es False en sentido booleano, pero todos los miembros enum evalúan como True.

Las enumeraciones serializadas creadas con la API funcional pueden ser complicadas ya que los detalles de implementación de la pila se usan para tratar de averiguar en qué módulo se está creando la enumeración (ej. fallará si usa una función de utilidad en un módulo separado, y también puede no funcionar en IronPython o Jython). La solución es especificar el nombre del módulo explícitamente de la siguiente manera:

>>> Animal = Enum('Animal', 'ANT BEE CAT DOG', module=__name__)

Advertencia

Si no se suministra un module, y Enum no puede determinar que es, los miembros del nuevo Enum no se podrán desempaquetar; para mantener los errores más cerca de la fuente, la serialización se deshabilitará.

El nuevo protocolo 4 de serialización también, en ciertas circunstancias, se basa en __qualname__ se establece en la ubicación donde la serialización podrá encontrar la clase. Por ejemplo, si la clase se hizo disponible en la clase SomeData en el campo global:

>>> Animal = Enum('Animal', 'ANT BEE CAT DOG', qualname='SomeData.Animal')

La firma completa es:

Enum(value='NewEnumName', names=<...>, *, module='...', qualname='...', type=<mixed-in class>, start=1)

valor

Lo que la nueva clase Enum registrará como su nombre.

nombres

Los miembros de Enum. Esto puede ser un espacio en blanco o una cadena separada por comas (los valores empezarán en 1 a menos que se especifique lo contrario):

'RED GREEN BLUE' | 'RED,GREEN,BLUE' | 'RED, GREEN, BLUE'

o un iterador de nombres:

['RED', 'GREEN', 'BLUE']

o un iterador de pares(nombre,valor):

[('CYAN', 4), ('MAGENTA', 5), ('YELLOW', 6)]

o un mapeo:

{'CHARTREUSE': 7, 'SEA_GREEN': 11, 'ROSEMARY': 42}

módulo

nombre del módulo donde se puede encontrar la nueva clase Enum.

qualname

donde en el módulo se puede encontrar la nueva clase Enum.

tipo

escriba para mezclar en la nueva clase Enum.

inicio

número para comenzar a contar sí solo se pasan nombres.

Distinto en la versión 3.5: Se agregó el parámetro start.

Enumeraciones derivadas

IntEnum

La primera variación de Enum que se proporciona también es una subclase de int. Los miembros de IntEnum se pueden comparar con enteros; por extensión, las enumeraciones enteras de diferentes tipos también se pueden comparar entre sí:

>>> from enum import IntEnum
>>> class Shape(IntEnum):
...     CIRCLE = 1
...     SQUARE = 2
...
>>> class Request(IntEnum):
...     POST = 1
...     GET = 2
...
>>> Shape == 1
False
>>> Shape.CIRCLE == 1
True
>>> Shape.CIRCLE == Request.POST
True

Sin embargo, todavía no se pueden comparar con las enumeraciones estándar Enum:

>>> class Shape(IntEnum):
...     CIRCLE = 1
...     SQUARE = 2
...
>>> class Color(Enum):
...     RED = 1
...     GREEN = 2
...
>>> Shape.CIRCLE == Color.RED
False

los valores IntEnum se comportan como enteros en otras maneras que esperarías:

>>> int(Shape.CIRCLE)
1
>>> ['a', 'b', 'c'][Shape.CIRCLE]
'b'
>>> [i for i in range(Shape.SQUARE)]
[0, 1]

IntFlag

La siguiente variación de Enum proporcionada, IntFlag, también se basa en int. La diferencia es que los miembros IntFlag se pueden combinar usando los operadores (&, |, ^, ~) y el resultado es un miembro IntFlag. Sin embargo, como su nombre lo indica, los miembros de IntFlag también son subclase int y pueden usarse siempre que int se use. Cualquier operación en un miembro IntFlag además de las operaciones de bit perderán la membresía IntFlag.

Nuevo en la versión 3.6.

Clase muestra IntFlag:

>>> from enum import IntFlag
>>> class Perm(IntFlag):
...     R = 4
...     W = 2
...     X = 1
...
>>> Perm.R | Perm.W
<Perm.R|W: 6>
>>> Perm.R + Perm.W
6
>>> RW = Perm.R | Perm.W
>>> Perm.R in RW
True

También es posible nombrar las combinaciones:

>>> class Perm(IntFlag):
...     R = 4
...     W = 2
...     X = 1
...     RWX = 7
>>> Perm.RWX
<Perm.RWX: 7>
>>> ~Perm.RWX
<Perm.-8: -8>

Otra diferencia importante entre IntFlag y Enum es que si no hay banderas establecidas (el valor es 0), su evaluación booleana es False:

>>> Perm.R & Perm.X
<Perm.0: 0>
>>> bool(Perm.R & Perm.X)
False

Porque los miembros IntFlag también son subclases de int se pueden combinar con ellos:

>>> Perm.X | 8
<Perm.8|X: 9>

Bandera

La última variación es Flag. Al igual que IntFlag, Flag los miembros se pueden combinar usando los operadores (&, |, ^, ~). A diferencia de IntFlag, no pueden combinar ni comparar con ninguna otra enumeración Flag, ni con int. Es posible especificar los valores directamente, se recomienda usar auto como el valor y dejar que Flag seleccione el valor apropiado.

Nuevo en la versión 3.6.

Al igual que IntFlag, si una combinación de miembros Flag resultan en que no se establezcan banderas, la evaluación booleana es False:

>>> from enum import Flag, auto
>>> class Color(Flag):
...     RED = auto()
...     BLUE = auto()
...     GREEN = auto()
...
>>> Color.RED & Color.GREEN
<Color.0: 0>
>>> bool(Color.RED & Color.GREEN)
False

Las banderas individuales deben tener valores que sean potencias de dos (1, 2, 4, 8, …), mientras que las combinaciones de banderas no:

>>> class Color(Flag):
...     RED = auto()
...     BLUE = auto()
...     GREEN = auto()
...     WHITE = RED | BLUE | GREEN
...
>>> Color.WHITE
<Color.WHITE: 7>

Dar un nombre a la condición «sin banderas establecidas» no cambia su valor booleano:

>>> class Color(Flag):
...     BLACK = 0
...     RED = auto()
...     BLUE = auto()
...     GREEN = auto()
...
>>> Color.BLACK
<Color.BLACK: 0>
>>> bool(Color.BLACK)
False

Nota

Para la mayoría del código nuevo, Enum y Flag son muy recomendables, ya que IntEnum y IntFlag rompen algunas promesas semánticas de una enumeración (al ser comparables con enteros, y por transitividad a otras enumeraciones no relacionadas). IntEnum y IntFlag deben usarse solo en casos donde Enum y Flag no son suficientes: por ejemplo, cuando las constantes enteras se reemplazan por enumeraciones, o por interoperabilidad con otros sistemas.

Otros

Mientras que IntEnum es parte del módulo enum, sería muy simple de implementar de forma independiente:

class IntEnum(int, Enum):
    pass

Esto demuestra que similares pueden ser las enumeraciones derivadas; por ejemplo una StrEnum que se mezcla en str en lugar de int.

Algunas reglas:

Al subclasificar Enum, los tipos mixtos deben aparecer antes Enum en la secuencia de bases, como en el ejemplo anterior IntEnum.

Mientras que Enum puede tener miembros de cualquier tipo, una vez que se mezcle tipos adicionales, todos los miembros deben de tener los valores de ese tipo, por ejemplo, int de arriba. Esta restricción no se aplica a las mezclas que solo agregan métodos y no especifican otro tipo.

Cuando se mezcla otro tipo de datos, el atributo value no es el mismo que el mismo miembro enum, aunque es equivalente y se comparará igual.

Formato %-style: %s y %r llaman, respectivamente, a __str__() y __repr__() de la clase Enum; otros códigos (como &i o %h para IntEnum) tratan al miembro enum como su tipo mixto.

Cadenas de caracteres literales formateadas, str.format(), y format() usará el tipo mixto __format__() a menos que __str__() o __format__() se sobreescriba en la subclase, en cuyo caso se utilizarán los métodos anulados o Enum. Use los códigos de formato !s y !r para forzar el uso de los métodos Enum de las clases __str__() y __repr__().

Cuándo usar __new__() contra __init__()

__new__() debe usarse siempre que desee personalizar el valor del miembro real Emum. Cualquier otra modificación puede ir en __new__() o __init__(), prefiriendo siempre __init__().

Por ejemplo, si desea pasar varios elementos al constructor, pero solo desea que uno de ellos sea el valor:

>>> class Coordinate(bytes, Enum):
...     """
...     Coordinate with binary codes that can be indexed by the int code.
...     """
...     def __new__(cls, value, label, unit):
...         obj = bytes.__new__(cls, [value])
...         obj._value_ = value
...         obj.label = label
...         obj.unit = unit
...         return obj
...     PX = (0, 'P.X', 'km')
...     PY = (1, 'P.Y', 'km')
...     VX = (2, 'V.X', 'km/s')
...     VY = (3, 'V.Y', 'km/s')
...

>>> print(Coordinate['PY'])
Coordinate.PY

>>> print(Coordinate(3))
Coordinate.VY

Ejemplos interesantes

Si bien se espera que Enum, IntEnum, IntFlag, y Flag cubran la mayoría de los casos de uso, no pueden cubrirlos a todos. Aquí hay recetas para algunos tipos diferentes de enumeraciones que puede usarse directamente, o como ejemplos para crear los propios.

Omitir valores

En muchos casos de uso, a uno no le importa cuál es el valor real de una enumeración. Hay varias formas de definir este tipo de enumeración simple:

use instancias de auto para el valor

use instancias de object como el valor

use a descriptive string as the value

use una tupla como valor y un __new__() personalizado para reemplazar la tupla con un valor int

El uso de cualquiera de estos métodos significa para el usuario que estos valores no son importantes y también permite agregar, eliminar o reordenar miembros sin tener que volver a numerar los miembros restantes.

Cualquiera que sea el método que elijas, debe proporcionar un repr() que también oculte el valor (sin importancia):

>>> class NoValue(Enum):
...     def __repr__(self):
...         return '<%s.%s>' % (self.__class__.__name__, self.name)
...

Usando auto

Usando auto se vería como:

>>> class Color(NoValue):
...     RED = auto()
...     BLUE = auto()
...     GREEN = auto()
...
>>> Color.GREEN
<Color.GREEN>

Usando object

Usando object se vería como:

>>> class Color(NoValue):
...     RED = object()
...     GREEN = object()
...     BLUE = object()
...
>>> Color.GREEN
<Color.GREEN>

Usando una cadena descriptiva

Usar una cadena como valor se vería así:

>>> class Color(NoValue):
...     RED = 'stop'
...     GREEN = 'go'
...     BLUE = 'too fast!'
...
>>> Color.GREEN
<Color.GREEN>
>>> Color.GREEN.value
'go'

Usando __new__() personalizados

Usando una numeración automática __new__() se vería como:

>>> class AutoNumber(NoValue):
...     def __new__(cls):
...         value = len(cls.__members__) + 1
...         obj = object.__new__(cls)
...         obj._value_ = value
...         return obj
...
>>> class Color(AutoNumber):
...     RED = ()
...     GREEN = ()
...     BLUE = ()
...
>>> Color.GREEN
<Color.GREEN>
>>> Color.GREEN.value
2

Para hacer un AutoNumber de propósito más general, agregue *args a la firma:

>>> class AutoNumber(NoValue):
...     def __new__(cls, *args):      # this is the only change from above
...         value = len(cls.__members__) + 1
...         obj = object.__new__(cls)
...         obj._value_ = value
...         return obj
...

Luego, cuando hereda de AutoNumber, puede escribir su propio __init__ para manejar cualquier argumento adicional:

>>> class Swatch(AutoNumber):
...     def __init__(self, pantone='unknown'):
...         self.pantone = pantone
...     AUBURN = '3497'
...     SEA_GREEN = '1246'
...     BLEACHED_CORAL = () # New color, no Pantone code yet!
...
>>> Swatch.SEA_GREEN
<Swatch.SEA_GREEN: 2>
>>> Swatch.SEA_GREEN.pantone
'1246'
>>> Swatch.BLEACHED_CORAL.pantone
'unknown'

Nota

El método __new__(), está definido, se usa durante la creación de los miembros Enum; se remplaza entonces por el Enum __new__() que se utiliza después de la creación de la clase para buscar miembros existentes.

OrderedEnum

Una enumeración ordenada que no se basa en IntEnum y, por lo tanto mantiene los invariantes normales de Enum (como no ser comparables con otras enumeraciones):

>>> class OrderedEnum(Enum):
...     def __ge__(self, other):
...         if self.__class__ is other.__class__:
...             return self.value >= other.value
...         return NotImplemented
...     def __gt__(self, other):
...         if self.__class__ is other.__class__:
...             return self.value > other.value
...         return NotImplemented
...     def __le__(self, other):
...         if self.__class__ is other.__class__:
...             return self.value <= other.value
...         return NotImplemented
...     def __lt__(self, other):
...         if self.__class__ is other.__class__:
...             return self.value < other.value
...         return NotImplemented
...
>>> class Grade(OrderedEnum):
...     A = 5
...     B = 4
...     C = 3
...     D = 2
...     F = 1
...
>>> Grade.C < Grade.A
True

DuplicateFreeEnum

Levanta un error si se encuentra un nombre de miembro duplicado en lugar de crear un alias:

>>> class DuplicateFreeEnum(Enum):
...     def __init__(self, *args):
...         cls = self.__class__
...         if any(self.value == e.value for e in cls):
...             a = self.name
...             e = cls(self.value).name
...             raise ValueError(
...                 "aliases not allowed in DuplicateFreeEnum:  %r --> %r"
...                 % (a, e))
...
>>> class Color(DuplicateFreeEnum):
...     RED = 1
...     GREEN = 2
...     BLUE = 3
...     GRENE = 2
...
Traceback (most recent call last):
...
ValueError: aliases not allowed in DuplicateFreeEnum:  'GRENE' --> 'GREEN'

Nota

Este es un ejemplo útil para subclasificar Enum para agregar o cambiar otros comportamientos, así como no permitir alias. Si el único cambio deseado es no permitir alias, el decorador unique() puede usarse en su lugar.

Planeta

Si __new__() o __init__() se definen el valor del miembro enum se pasará a estos métodos:

>>> class Planet(Enum):
...     MERCURY = (3.303e+23, 2.4397e6)
...     VENUS   = (4.869e+24, 6.0518e6)
...     EARTH   = (5.976e+24, 6.37814e6)
...     MARS    = (6.421e+23, 3.3972e6)
...     JUPITER = (1.9e+27,   7.1492e7)
...     SATURN  = (5.688e+26, 6.0268e7)
...     URANUS  = (8.686e+25, 2.5559e7)
...     NEPTUNE = (1.024e+26, 2.4746e7)
...     def __init__(self, mass, radius):
...         self.mass = mass       # in kilograms
...         self.radius = radius   # in meters
...     @property
...     def surface_gravity(self):
...         # universal gravitational constant  (m3 kg-1 s-2)
...         G = 6.67300E-11
...         return G * self.mass / (self.radius * self.radius)
...
>>> Planet.EARTH.value
(5.976e+24, 6378140.0)
>>> Planet.EARTH.surface_gravity
9.802652743337129

Periodo de tiempo

Un ejemplo para mostrar el atributo ignore en uso:

>>> from datetime import timedelta
>>> class Period(timedelta, Enum):
...     "different lengths of time"
...     _ignore_ = 'Period i'
...     Period = vars()
...     for i in range(367):
...         Period['day_%d' % i] = i
...
>>> list(Period)[:2]
[<Period.day_0: datetime.timedelta(0)>, <Period.day_1: datetime.timedelta(days=1)>]
>>> list(Period)[-2:]
[<Period.day_365: datetime.timedelta(days=365)>, <Period.day_366: datetime.timedelta(days=366)>]

¿Cómo son diferentes las Enums?

Los Enums tienen una metaclase personalizada que afecta muchos aspectos, tanto de las clases derivadas Enum como de sus instancias (miembros).

Clases Enum

La meta clase EnumMeta es responsable de proveer los métodos __contains__(), __dir__(), __iter__() y cualquier otro que permita hacer cosas con una clase Enum que falla en una clase típica, como list(Color) o some_enum_var in Color. EnumMeta es responsable de asegurar que los otro varios métodos en la clase final Enum sean correctos (como __new__(), __getnewargs__(), __str__() y __repr__()).

Miembros de Enum (también conocidos como instancias)

Lo más interesante de los miembros de Enum es que son únicos. Enum los crea todos mientras está creando la clase Enum misma, y después un __new__() personalizado para garantizar que nunca se creen instancias nuevas retornando solo las instancias de miembros existentes.

Puntos más finos

Nombres soportados __dunder__

__members__ es una asignación ordenada de solo lectura de artículos member_name:member. Solo está disponible en la clase.

__new__(), si se especifica, debe crear y retornar los miembros de enumeración; también es una muy buena idea establecer el _value_ del miembro apropiadamente. Una vez que se crean todos los miembros, ya no se usa.

Nombres _sunder_ compatibles

_name_— nombre del miembro

_value_ — valor del miembro; se puede definir / modificar en __new__

_missing_ — una función de búsqueda utilizada cuando no se encuentra un valor; puede ser anulado

_ignore_ – una lista de nombres, ya sea como una list() o una str() que no será transformada en miembros, y que se eliminará de la clase final

_order_ — usado en código Python 2/3 para asegurar que el orden de los miembros sea consistente (atributo de clase, eliminado durante la creación de la clase)

_generate_next_value_ — usado por la Funcional API y por auto para obtener un valor apropiado para un miembro enum; puede ser anulado

Nuevo en la versión 3.6: _missing_, _order_, _generate_next_value_

Nuevo en la versión 3.7: _ignore_

Para ayudar a mantener sincronizado el código Python 2 / Python 3 se puede proporcionar un atributo _order_. Se verificará con el orden real de la enumeración y generará un error si los dos no coinciden:

>>> class Color(Enum):
...     _order_ = 'RED GREEN BLUE'
...     RED = 1
...     BLUE = 3
...     GREEN = 2
...
Traceback (most recent call last):
...
TypeError: member order does not match _order_

Nota

En código Python 2 el atributo _order_ es necesario ya que el orden de definición se pierde antes de que se pueda registrar.

_Private__names

Private names will be normal attributes in Python 3.11 instead of either an error or a member (depending on if the name ends with an underscore). Using these names in 3.9 and 3.10 will issue a DeprecationWarning.

Tipo de miembro Enum

Los miembros Enum son instancias de su clase Enum, y normalmente se accede a ellos como EnumClass.member. Bajo ciertas circunstancias también se puede acceder como EnumClass.member.member, pero nunca se debe hacer esto ya que esa búsqueda puede fallar, o peor aún, retornar algo además del miembro Enum que está buscando (esta es otra buena razón para usar solo mayúsculas en los nombres para los miembros):

>>> class FieldTypes(Enum):
...     name = 0
...     value = 1
...     size = 2
...
>>> FieldTypes.value.size
<FieldTypes.size: 2>
>>> FieldTypes.size.value
2

Nota

This behavior is deprecated and will be removed in 3.11.

Distinto en la versión 3.5.

Valor booleano de las clases y miembros Enum

Lo miembros Enum que están mezclados con tipos sin-Enum (como int, str, etc.) se evalúan de acuerdo con las reglas de tipo mixto; de lo contrario, todos los miembros evalúan como True. Para hacer que tu propia evaluación booleana de Enum dependa del valor del miembro, agregue lo siguiente a su clase:

def __bool__(self):
    return bool(self.value)

las clases Enum siempre evalúan como True.

Enum clases con métodos

Si le da a su subclase Enum métodos adicionales, como la clase Planet anterior, esos métodos aparecerán en una dir() del miembro, pero no de la clase

>>> dir(Planet)
['EARTH', 'JUPITER', 'MARS', 'MERCURY', 'NEPTUNE', 'SATURN', 'URANUS', 'VENUS', '__class__', '__doc__', '__members__', '__module__']
>>> dir(Planet.EARTH)
['__class__', '__doc__', '__module__', 'name', 'surface_gravity', 'value']

Combinando miembros de``Flag``

Si no se nombra una combinación de miembros de Flag, el repr() incluirá todos los flags con nombre y todas las combinaciones de flags con nombre que estén en el valor

>>> class Color(Flag):
...     RED = auto()
...     GREEN = auto()
...     BLUE = auto()
...     MAGENTA = RED | BLUE
...     YELLOW = RED | GREEN
...     CYAN = GREEN | BLUE
...
>>> Color(3)  # named combination
<Color.YELLOW: 3>
>>> Color(7)      # not named combination
<Color.CYAN|MAGENTA|BLUE|YELLOW|GREEN|RED: 7>

Nota

In 3.11 unnamed combinations of flags will only produce the canonical flag members (aka single-value flags). So Color(7) would produce something like <Color.BLUE|GREEN|RED: 7>.

graphlib — Functionality to operate with graph-like structures

Source code: Lib/graphlib.py [https://github.com/python/cpython/tree/3.9/Lib/graphlib.py]

class graphlib.TopologicalSorter(graph=None)

Provides functionality to topologically sort a graph of hashable nodes.

A topological order is a linear ordering of the vertices in a graph such that for every directed edge u -> v from vertex u to vertex v, vertex u comes before vertex v in the ordering. For instance, the vertices of the graph may represent tasks to be performed, and the edges may represent constraints that one task must be performed before another; in this example, a topological ordering is just a valid sequence for the tasks. A complete topological ordering is possible if and only if the graph has no directed cycles, that is, if it is a directed acyclic graph.

If the optional graph argument is provided it must be a dictionary representing a directed acyclic graph where the keys are nodes and the values are iterables of all predecessors of that node in the graph (the nodes that have edges that point to the value in the key). Additional nodes can be added to the graph using the add() method.

In the general case, the steps required to perform the sorting of a given graph are as follows:

Create an instance of the TopologicalSorter with an optional initial graph.

Add additional nodes to the graph.

Call prepare() on the graph.

While is_active() is True, iterate over the nodes returned by get_ready() and process them. Call done() on each node as it finishes processing.

In case just an immediate sorting of the nodes in the graph is required and no parallelism is involved, the convenience method TopologicalSorter.static_order() can be used directly:

>>> graph = {"D": {"B", "C"}, "C": {"A"}, "B": {"A"}}
>>> ts = TopologicalSorter(graph)
>>> tuple(ts.static_order())
('A', 'C', 'B', 'D')

The class is designed to easily support parallel processing of the nodes as they become ready. For instance:

topological_sorter = TopologicalSorter()

# Add nodes to 'topological_sorter'...

topological_sorter.prepare()
while topological_sorter.is_active():
    for node in topological_sorter.get_ready():
        # Worker threads or processes take nodes to work on off the
        # 'task_queue' queue.
        task_queue.put(node)

    # When the work for a node is done, workers put the node in
    # 'finalized_tasks_queue' so we can get more nodes to work on.
    # The definition of 'is_active()' guarantees that, at this point, at
    # least one node has been placed on 'task_queue' that hasn't yet
    # been passed to 'done()', so this blocking 'get()' must (eventually)
    # succeed.  After calling 'done()', we loop back to call 'get_ready()'
    # again, so put newly freed nodes on 'task_queue' as soon as
    # logically possible.
    node = finalized_tasks_queue.get()
    topological_sorter.done(node)

add(node, *predecessors)

Add a new node and its predecessors to the graph. Both the node and all elements in predecessors must be hashable.

If called multiple times with the same node argument, the set of dependencies will be the union of all dependencies passed in.

It is possible to add a node with no dependencies (predecessors is not provided) or to provide a dependency twice. If a node that has not been provided before is included among predecessors it will be automatically added to the graph with no predecessors of its own.

Raises ValueError if called after prepare().

prepare()

Mark the graph as finished and check for cycles in the graph. If any cycle is detected, CycleError will be raised, but get_ready() can still be used to obtain as many nodes as possible until cycles block more progress. After a call to this function, the graph cannot be modified, and therefore no more nodes can be added using add().

is_active()

Returns True if more progress can be made and False otherwise. Progress can be made if cycles do not block the resolution and either there are still nodes ready that haven’t yet been returned by TopologicalSorter.get_ready() or the number of nodes marked TopologicalSorter.done() is less than the number that have been returned by TopologicalSorter.get_ready().

The __bool__() method of this class defers to this function, so instead of:

if ts.is_active():
    ...

it is possible to simply do:

if ts:
    ...

Raises ValueError if called without calling prepare() previously.

done(*nodes)

Marks a set of nodes returned by TopologicalSorter.get_ready() as processed, unblocking any successor of each node in nodes for being returned in the future by a call to TopologicalSorter.get_ready().

Raises ValueError if any node in nodes has already been marked as processed by a previous call to this method or if a node was not added to the graph by using TopologicalSorter.add(), if called without calling prepare() or if node has not yet been returned by get_ready().

get_ready()

Returns a tuple with all the nodes that are ready. Initially it returns all nodes with no predecessors, and once those are marked as processed by calling TopologicalSorter.done(), further calls will return all new nodes that have all their predecessors already processed. Once no more progress can be made, empty tuples are returned.

Raises ValueError if called without calling prepare() previously.

static_order()

Returns an iterator object which will iterate over nodes in a topological order. When using this method, prepare() and done() should not be called. This method is equivalent to:

def static_order(self):
    self.prepare()
    while self.is_active():
        node_group = self.get_ready()
        yield from node_group
        self.done(*node_group)

The particular order that is returned may depend on the specific order in which the items were inserted in the graph. For example:

>>> ts = TopologicalSorter()
>>> ts.add(3, 2, 1)
>>> ts.add(1, 0)
>>> print([*ts.static_order()])
[2, 0, 1, 3]

>>> ts2 = TopologicalSorter()
>>> ts2.add(1, 0)
>>> ts2.add(3, 2, 1)
>>> print([*ts2.static_order()])
[0, 2, 1, 3]

This is due to the fact that «0» and «2» are in the same level in the graph (they would have been returned in the same call to get_ready()) and the order between them is determined by the order of insertion.

If any cycle is detected, CycleError will be raised.

Nuevo en la versión 3.9.

Exceptions

The graphlib module defines the following exception classes:

exception graphlib.CycleError

Subclass of ValueError raised by TopologicalSorter.prepare() if cycles exist in the working graph. If multiple cycles exist, only one undefined choice among them will be reported and included in the exception.

The detected cycle can be accessed via the second element in the args attribute of the exception instance and consists in a list of nodes, such that each node is, in the graph, an immediate predecessor of the next node in the list. In the reported list, the first and the last node will be the same, to make it clear that it is cyclic.

Módulos numéricos y matemáticos

Los módulos descritos en este capítulo proporcionan funciones y tipos de datos numéricos y relacionados con las matemáticas. El módulo numbers define una jerarquía abstracta de tipos numéricos. Los módulos math y cmath contienen varias funciones matemáticas para números complejos y de punto flotante. El módulo decimal admite representaciones exactas de números decimales, utilizando aritmética de precisión arbitraria.

En este capítulo se documentan los siguientes módulos:

numbers — Clase base abstracta numérica

La torre numérica

Notas para implementadores de tipos

Agregar más ABCs numéricos

Implementar operaciones aritméticas

math — Funciones matemáticas

Teoría de números y funciones de representación

Funciones logarítmicas y exponenciales

Funciones trigonométricas

Conversión angular

Funciones hiperbólicas

Funciones especiales

Constantes

cmath – Función matemática para números complejos

Conversión a y desde coordenadas polares

Funciones logarítmicas y de potencias

Funciones trigonométricas

Funciones hiperbólicas

Funciones de clasificación

Constantes

decimal — Aritmética decimal de coma fija y coma flotante

Tutorial de inicio rápido

Objetos Decimal

Operandos lógicos

Objetos Context

Constantes

Modos de redondeo

Señales

Notas sobre la representación en coma flotante

Mitigación del error de redondeo usando mayor precisión

Valores especiales

Trabajando con hilos

Casos prácticos

Preguntas frecuentes sobre Decimal

fractions — Números racionales

random —Generar números pseudoaleatorios

Funciones de contabilidad

Funciones para los bytes

Funciones para enteros

Funciones para secuencias

Distribuciones para los nombres reales

Generador alternativo

Notas sobre la Reproducibilidad

Ejemplos

Recetas

statistics — Funciones de estadística matemática

Promedios y medidas de tendencia central

Medidas de dispersión

Detalles de las funciones

Excepciones

Objetos NormalDist

Ejemplos de uso de NormalDist

numbers — Clase base abstracta numérica

Código fuente: Lib/numbers.py [https://github.com/python/cpython/tree/3.9/Lib/numbers.py]

The numbers module (PEP 3141 [https://www.python.org/dev/peps/pep-3141]) defines a hierarchy of numeric abstract base classes which progressively define more operations. None of the types defined in this module are intended to be instantiated.

class numbers.Number

La raíz de la jerarquía numérica. Si desea validar si un argumento x es un número, sin importar su tipo, use isinstance(x, Number).

La torre numérica

class numbers.Complex

Subclasses of this type describe complex numbers and include the operations that work on the built-in complex type. These are: conversions to complex and bool, real, imag, +, -, *, /, **, abs(), conjugate(), ==, and !=. All except - and != are abstract.

real

Abstracto. Recupera el componente real de este número.

imag

Abstracto. Recupera el componente imaginario de este número.

abstractmethod conjugate()

Abstracto. Retorna el complejo conjugado. Por ejemplo, (1+3j).conjugate() == (1-3j).

class numbers.Real

Para Complex, Real agrega las operaciones que trabajan con números reales.

En resumen, estos son: conversiones a float, math.trunc(), round(), math.floor(), math.ceil(), divmod(), //, %, <, <=, >, y >=.

Real también proporciona valores predeterminados para complex(), real, imag, y conjugate().

class numbers.Rational

Subtipos Real y agrega numerator y denominator propiedades, que deben estar en los términos más bajos. Con estos, proporciona un valor predeterminado para float().

numerator

Abstracto.

denominator

Abstracto.

class numbers.Integral

Subtypes Rational and adds a conversion to int. Provides defaults for float(), numerator, and denominator. Adds abstract methods for pow() with modulus and bit-string operations: <<, >>, &, ^, |, ~.

Notas para implementadores de tipos

Los implementadores deben tener cuidado de igualar números iguales y aplicar un hash a los mismos valores. Esto puede ser sutil si hay dos extensiones diferentes de los números reales. Por ejemplo, fractions.Fraction implementa hash() de la siguiente manera:

def __hash__(self):
    if self.denominator == 1:
        # Get integers right.
        return hash(self.numerator)
    # Expensive check, but definitely correct.
    if self == float(self):
        return hash(float(self))
    else:
        # Use tuple's hash to avoid a high collision rate on
        # simple fractions.
        return hash((self.numerator, self.denominator))

Agregar más ABCs numéricos

Por supuesto, hay más ABCs posibles para los números, y esto sería una jerarquía deficiente si se excluye la posibilidad de añadirlos. Puede usar MyFoo entre Complex y Real así:

class MyFoo(Complex): ...
MyFoo.register(Real)

Implementar operaciones aritméticas

Queremos implementar las operaciones aritméticas tal que las operaciones de modo mixto llamen a una implementación cuyo autor conocía los tipos de ambos argumentos, o convertir ambos argumentos al tipo incorporado más cercano antes de hacer la operación. Para subtipos de Integral, esto significa que __add__() y __radd__() tienen que ser definidos como:

class MyIntegral(Integral):

    def __add__(self, other):
        if isinstance(other, MyIntegral):
            return do_my_adding_stuff(self, other)
        elif isinstance(other, OtherTypeIKnowAbout):
            return do_my_other_adding_stuff(self, other)
        else:
            return NotImplemented

    def __radd__(self, other):
        if isinstance(other, MyIntegral):
            return do_my_adding_stuff(other, self)
        elif isinstance(other, OtherTypeIKnowAbout):
            return do_my_other_adding_stuff(other, self)
        elif isinstance(other, Integral):
            return int(other) + int(self)
        elif isinstance(other, Real):
            return float(other) + float(self)
        elif isinstance(other, Complex):
            return complex(other) + complex(self)
        else:
            return NotImplemented

Hay 5 casos diferentes para una operación de tipo mixto en subclases de Complex. Se explicará todo el código anterior que no se refiere a MyIntegral y OtherTypeIKnowAbout` como "repetitivo". ``a será una instancia de A, que es un subtipo de Complex (a: A <: Complex`), y ``b : B <: Complex. Consideraré a + b:

Si A define un __add__() que acepta b, todo está bien.

Si A recurre al código repetitivo y retorna un valor de __add__(), perderíamos la posibilidad de que B defina un __radd __() más inteligente, por lo que el código repetitivo debería retornar NotImplemented de __add__(). (O A no puede implementar __add__() en absoluto.)

Entonces B’s __radd__() tiene una oportunidad. Si acepta a, todo esta bien.

Si se vuelve a caer en el código repetitivo, no hay más posibles métodos para probar, por lo que acá debería vivir la implementación predeterminada.

Si B <: A, Python probara B.__radd__ antes que A.__add__. Esto está bien, porque se implementó con conocimiento de A, por lo que puede manejar instancias antes de delegar un Complex.

Si A <: Complex y B <: Real sin compartir ningún otro conocimiento,la operación compartida apropiada es la que involucra la clase complex incorporada, y ambos __radd__() desencadenan allí, entonces a+b == b+a.

Dado que la mayoría de las operaciones en un tipo determinado serán muy similares, puede ser útil definir una función auxiliar que genere las instancias forward y reverse de cualquier operador dado. Por ejemplo, fractions.Fraction así:

def _operator_fallbacks(monomorphic_operator, fallback_operator):
    def forward(a, b):
        if isinstance(b, (int, Fraction)):
            return monomorphic_operator(a, b)
        elif isinstance(b, float):
            return fallback_operator(float(a), b)
        elif isinstance(b, complex):
            return fallback_operator(complex(a), b)
        else:
            return NotImplemented
    forward.__name__ = '__' + fallback_operator.__name__ + '__'
    forward.__doc__ = monomorphic_operator.__doc__

    def reverse(b, a):
        if isinstance(a, Rational):
            # Includes ints.
            return monomorphic_operator(a, b)
        elif isinstance(a, numbers.Real):
            return fallback_operator(float(a), float(b))
        elif isinstance(a, numbers.Complex):
            return fallback_operator(complex(a), complex(b))
        else:
            return NotImplemented
    reverse.__name__ = '__r' + fallback_operator.__name__ + '__'
    reverse.__doc__ = monomorphic_operator.__doc__

    return forward, reverse

def _add(a, b):
    """a + b"""
    return Fraction(a.numerator * b.denominator +
                    b.numerator * a.denominator,
                    a.denominator * b.denominator)

__add__, __radd__ = _operator_fallbacks(_add, operator.add)

# ...

math — Funciones matemáticas

Este módulo proporciona acceso a las funciones matemáticas definidas en el estándar de C.

Estas funciones no pueden ser usadas con números complejos; usa las funciones con el mismo nombre del módulo cmath si requieres soporte para números complejos. La distinción entre las funciones que admiten números complejos y las que no se hace debido a que la mayoría de los usuarios no quieren aprender tantas matemáticas como se requiere para comprender los números complejos. Recibir una excepción en lugar de un resultado complejo permite la detección temprana del número complejo inesperado utilizado como parámetro, de modo que el programador pueda determinar cómo y porqué se generó en primer lugar.

Este módulo proporciona las funciones descritas a continuación. Excepto cuando se indique lo contrario explícitamente, todos los valores retornados son flotantes.

Teoría de números y funciones de representación

math.ceil(x)

Return the ceiling of x, the smallest integer greater than or equal to x. If x is not a float, delegates to x.__ceil__, which should return an Integral value.

math.comb(n, k)

Retorna el número de formas posibles de elegir k elementos de n, de forma ordenada y sin repetición.

Se evalúa como n! / (k! * (n - k)!) cuando k <= n y como cero cuando k > n.

También se llama coeficiente binomial porque es equivalente al coeficiente del k-ésimo término en el desarrollo polinomial de la expresión (1 + x) ** n.

Lanza una excepción TypeError si alguno de los argumentos no es un entero. Lanza una excepción ValueError si alguno de los argumentos es negativo.

Nuevo en la versión 3.8.

math.copysign(x, y)

Retorna un flotante con la magnitud (valor absoluto) de x pero el signo de y. En plataformas que admiten ceros con signo, copysign(1.0, -0.0) retorna -1.0.

math.fabs(x)

Retorna el valor absoluto de x.

math.factorial(x)

Retorna el factorial de x como un número entero. Lanza una excepción ValueError si x no es un entero o es negativo.

Obsoleto desde la versión 3.9: Aceptar flotantes con valores integrales (como 5.0) está obsoleto.

math.floor(x)

Return the floor of x, the largest integer less than or equal to x. If x is not a float, delegates to x.__floor__, which should return an Integral value.

math.fmod(x, y)

Retorna fmod(x, y), tal como se define en la biblioteca de C de la plataforma. Ten en cuenta que la expresión x % y de Python puede no retornar el mismo resultado. La intención del estándar de C es que fmod(x, y) sea exactamente (matemáticamente; con precisión infinita) igual a x - n*y para algún número entero n tal que el resultado tenga el mismo signo que x y magnitud menor que abs(y). La expresión x % y de Python retorna un resultado con el signo de y en su lugar, y es posible que no pueda calcularse con exactitud para argumentos flotantes. Por ejemplo, fmod(-1e-100, 1e100) es -1e-100, pero el resultado de -1e-100 % 1e100 en Python es 1e100-1e-100, que no se puede representar exactamente como un flotante, y se redondea sorprendentemente a 1e100. Por esta razón, generalmente se prefiere la función fmod() cuando se trabaja con flotantes, mientras que se prefiere el uso de x % y de Python cuando se trabaja con enteros.

math.frexp(x)

Retorna la mantisa y el exponente de x como el par (m, e). m es un flotante y e es un número entero tal que x == m * 2**e exactamente. Si x es cero, retorna (0.0, 0), y retorna 0.5 <= abs(m) < 1 en caso contrario. Se utiliza como una forma portable de «extraer» la representación interna de un flotante.

math.fsum(iterable)

Retorna una suma precisa en coma flotante de los valores de un iterable. Evita la pérdida de precisión mediante el seguimiento de múltiples sumas parciales intermedias:

>>> sum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1])
0.9999999999999999
>>> fsum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1])
1.0

La precisión del algoritmo depende de las garantías aritméticas de IEEE-754 y del caso típico en el que se usa el «medio redondo a par» (half-even) como método de redondeo. En algunas compilaciones que no son de Windows, la biblioteca de C subyacente utiliza la adición de precisión extendida y, ocasionalmente, puede realizar un doble redondeo en una suma intermedia, haciendo que el bit menos significativo tome el valor incorrecto.

Para una discusión más amplia y dos enfoques alternativos, consultar ASPN cookbook recipes for accurate floating point summation [https://code.activestate.com/recipes/393090/].

math.gcd(*integers)

Retorna el máximo común divisor de los argumentos enteros. Si cualquiera de los argumentos no es cero, entonces el valor retornado es el entero positivo más grande que divide a todos los argumentos. Si todos los argumentos son cero, entonces el valor retornado es 0. gcd() sin argumentos retorna 0.

Nuevo en la versión 3.5.

Distinto en la versión 3.9: Agregado soporte para un número arbitrario de argumentos. Anteriormente sólo se soportaba dos argumentos.

math.isclose(a, b, *, rel_tol=1e-09, abs_tol=0.0)

Retorna True si los valores a y b están cerca el uno del otro y False en caso contrario.

Que dos valores se consideren cercanos o no, se determina de acuerdo con las tolerancias absolutas y relativas dadas.

rel_tol es la tolerancia relativa: esta es la diferencia máxima permitida entre a y b, en relación con el valor absoluto mayor de a o b. Por ejemplo, para establecer una tolerancia del 5%, pasa rel_tol=0.05. La tolerancia predeterminada es 1e-09, lo que garantiza que los dos valores sean iguales considerando 9 dígitos decimales aproximadamente. rel_tol debe ser mayor que cero.

abs_tol es la tolerancia absoluta mínima, útil para las comparaciones cercanas a cero. abs_tol debe valer al menos cero.

Si no se encuentran errores, el resultado será: abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol).

Los valores especiales de IEEE 754 NaN, inf e -inf se manejarán de acuerdo con las reglas del IEEE. Concretamente, NaN no se considera cercano a ningún otro valor, incluido NaN. Por su parte, inf e -inf solo se consideran cercanos a sí mismos.

Nuevo en la versión 3.5.

Ver también

PEP 485 [https://www.python.org/dev/peps/pep-0485] – Una función para comprobar la igualdad aproximada

math.isfinite(x)

Retorna True si x no es infinito ni NaN, o False en caso contrario. (Ten en cuenta que 0.0 es considerado finito.)

Nuevo en la versión 3.2.

math.isinf(x)

Retorna True si x es infinito positivo o negativo, o False en caso contrario.

math.isnan(x)

Retorna True si x es NaN (not a number, en español: no es un número), o False en caso contrario.

math.isqrt(n)

Retorna la raíz cuadrada del número entero no negativo n. Es el resultado de aplicar la función suelo al valor exacto de la raíz cuadrada de n, o de forma equivalente, el mayor entero a tal que a² ≤ n.

Para algunas aplicaciones, puede ser más conveniente tener el menor número entero a tal que n ≤ a², en otras palabras, el resultado de aplicar la función techo a la raíz cuadrada exacta de n. Para n positivo, esto se puede calcular usando a = 1 + isqrt(n - 1).

Nuevo en la versión 3.8.

math.lcm(*integers)

Retorna el mínimo común múltiplo de los argumentos enteros. Si todos los argumentos no son cero, entonces el valor retornado es el entero positivo más pequeño que es un múltiplo de todos los argumentos. Si cualquiera de los argumentos es cero, entonces el valor retornado es 0. lcm() sin argumentos retorna 1.

Nuevo en la versión 3.9.

math.ldexp(x, i)

Retorna x * (2**i). Esta es esencialmente la función inversa de frexp().

math.modf(x)

Retorna la parte fraccionaria y entera de x. Ambos resultados son flotantes y tienen el mismo signo que x .

math.nextafter(x, y)

Retorna el siguiente valor flotante después de x en la dirección de y.

Si x es igual a y, retorna y.

Ejemplos:

math.nextafter(x, math.inf) va hacia el infinito positivo.

math.nextafter(x, -math.inf) va hacia el infinito negativo.

math.nextafter(x, 0.0) va hacia cero.

math.nextafter(x, math.copysign(math.inf, x)) se aleja de cero.

Ver también math.ulp().

Nuevo en la versión 3.9.

math.perm(n, k=None)

Retorna el número de formas posibles de elegir k elementos de n elementos, sin repetición y en orden.

Se evalúa como n! / (n - k)! cuando k <= n y como cero cuando k > n.

Si k no se especifica o es None, k será igual a n por defecto y la función retornará n!.

Lanza una excepción TypeError si alguno de los argumentos no es un entero. Lanza una excepción ValueError si alguno de los argumentos es negativo.

Nuevo en la versión 3.8.

math.prod(iterable, *, start=1)

Calcula el producto de todos los elementos en la entrada iterable. El valor start predeterminado para el producto es 1.

Cuando el iterable está vacío, retorna el valor inicial. Esta función está diseñada específicamente para su uso con valores numéricos y puede rechazar tipos no numéricos.

Nuevo en la versión 3.8.

math.remainder(x, y)

Retorna el resto o residuo según la norma IEEE 754 de x con respecto a y. Para un valor x finito y un valor y finito distinto de cero, es la diferencia x - n * y, donde n es el número entero más cercano al valor exacto del cociente x / y. Si x / y está exactamente en mitad de dos enteros consecutivos, el entero par más cercano se utiliza para n. Por lo tanto, el residuo r = remainder(x, y) siempre satisface abs(r) <= 0.5 * abs(y).

Los casos especiales siguen el estándar IEEE 754: en particular, remainder(x, math.inf) es x para todo x finito, y remainder(x, 0) junto a remainder(math.inf, x) lanzan una excepción ValueError para todo x que no sea NaN. Si el resultado de la operación residuo es cero, este cero tendrá el mismo signo que x.

En plataformas que utilizan la norma IEEE 754 para números en coma flotante binarios, el resultado de esta operación siempre es exactamente representable: no se introduce ningún error de redondeo.

Nuevo en la versión 3.7.

math.trunc(x)

Return x with the fractional part removed, leaving the integer part. This rounds toward 0: trunc() is equivalent to floor() for positive x, and equivalent to ceil() for negative x. If x is not a float, delegates to x.__trunc__, which should return an Integral value.

math.ulp(x)

Retorna el valor del bit menos significativo del flotante x:

Si x es un NaN (not a number), retorna x.

Si x es negativo, retorna ulp(-x).

Si x es un infinito positivo, retorna x.

Si x es igual a cero, retorna el flotante representable desnormalizado positivo más pequeño (menor que el flotante normalizado positivo mínimo, sys.float_info.min).

Si x es igual al flotante representable positivo más pequeño, retorna el bit menos significativo de x, de tal manera que el primer flotante menor que x es x - ulp(x).

De lo contrario (x es un número finito positivo), retorna el valor del bit menos significativo de x , de tal forma que el primer flotante mayor a x es x + ulp(x).

ULP significa Unit in the Last Place (unidad en el último lugar).

Ver también math.nextafter() y sys.float_info.epsilon.

Nuevo en la versión 3.9.

Ten en cuenta que frexp() y modf() tienen un patrón de llamada/retorno diferente al de sus equivalentes en C: toman un solo argumento y retornan un par de valores, en lugar de retornar su segundo valor de retorno a través de un parámetro de salida (no existe tal cosa en Python).

Para las funciones ceil(), floor() y modf(), ten en cuenta que todos los números de coma flotante de magnitud suficientemente grande son enteros exactos. Los flotantes de Python normalmente no tienen más de 53 bits de precisión (lo mismo que el tipo double de C en la plataforma), en cuyo caso cualquier flotante x con abs(x) >= 2**52 no necesariamente tiene bits fraccionarios.

Funciones logarítmicas y exponenciales

math.exp(x)

Retorna e elevado a la x potencia, dónde e = 2.718281… es la base de los logaritmos naturales. Esto generalmente es más preciso que math.e ** x o pow(math.e, x).

math.expm1(x)

Retorna e elevado a la x potencia, menos 1. Aquí e es la base de los logaritmos naturales. Para flotantes x pequeños, la resta en exp(x) - 1 puede resultar en una pérdida significativa de precisión [https://en.wikipedia.org/wiki/Loss_of_significance]; la función expm1() proporciona una forma de calcular este valor con una precisión total:

>>> from math import exp, expm1
>>> exp(1e-5) - 1  # gives result accurate to 11 places
1.0000050000069649e-05
>>> expm1(1e-5)    # result accurate to full precision
1.0000050000166668e-05

Nuevo en la versión 3.2.

math.log(x[, base])

Con un argumento, retorna el logaritmo natural de x (en base e).

Con dos argumentos, retorna el logaritmo de x en la base dada, calculado como log(x)/log(base).

math.log1p(x)

Retorna el logaritmo natural de 1+x (base e). El resultado se calcula de forma precisa para x cercano a cero.

math.log2(x)

Retorna el logaritmo en base 2 de x. Esto suele ser más preciso que log(x, 2).

Nuevo en la versión 3.3.

Ver también

int.bit_length() retorna el número de bits necesarios para representar un entero en binario, excluyendo el signo y los ceros iniciales.

math.log10(x)

Retorna el logaritmo en base 10 de x. Esto suele ser más preciso que log(x, 10).

math.pow(x, y)

Retorna x elevado a la potencia y. Los casos excepcionales siguen el Anexo “F” del estándar C99 en la medida de lo posible. En particular, pow(1.0, x) y pow(x, 0.0) siempre retornan 1.0, incluso cuando x es cero o NaN. Si tanto x como y son finitos, x es negativo e y no es un número entero, entonces pow(x, y) no está definido y se lanza una excepción ValueError.

A diferencia del operador incorporado **, math.pow() convierte ambos argumentos al tipo float. Utiliza ** o la función incorporada pow() para calcular potencias enteras exactas.

math.sqrt(x)

Retorna la raíz cuadrada de x.

Funciones trigonométricas

math.acos(x)

Retorna el arcocoseno de x, en radianes. El resultado está entre 0 y pi.

math.asin(x)

Retorna el arcoseno de x, en radianes. El resultado está entre -pi/2 y pi/2.

math.atan(x)

Retorna la arcotangente de x, en radianes. El resultado está entre -pi/2 y pi/2.

math.atan2(y, x)

Retorna atan(y / x), en radianes. El resultado está entre -pi y pi. El vector del plano que va del origen al punto (x, y), forma este ángulo con el eje X positivo. La ventaja de atan2() es que el signo de ambas entradas es conocido, por lo que se puede calcular el cuadrante correcto para el ángulo. Por ejemplo, atan(1) y atan2(1, 1) son ambas pi/4, pero atan2(-1, -1) es -3*pi/4.

math.cos(x)

Retorna el coseno de x radianes.

math.dist(p, q)

Retorna la distancia euclidiana entre dos puntos p y q, cada uno de ellos dado como una secuencia (o iterable) de coordenadas. Los dos puntos deben tener la misma dimensión.

Aproximadamente equivalente a:

sqrt(sum((px - qx) ** 2.0 for px, qx in zip(p, q)))

Nuevo en la versión 3.8.

math.hypot(*coordinates)

Retorna la norma euclidiana, sqrt(sum(x**2 for x in coordinates)). Esta es la longitud del vector que va desde el origen hasta el punto dado por las coordenadas.

Para un punto bidimensional (x, y), esto equivale a calcular la hipotenusa de un triángulo rectángulo usando el teorema de Pitágoras, sqrt(x*x + y*y).

Distinto en la versión 3.8: Agregado soporte para puntos n-dimensionales. Anteriormente, solo se admitía el caso bidimensional.

math.sin(x)

Retorna el seno de x radianes.

math.tan(x)

Retorna la tangente de x radianes.

Conversión angular

math.degrees(x)

Convierte el ángulo x de radianes a grados.

math.radians(x)

Convierte el ángulo x de grados a radianes.

Funciones hiperbólicas

Las funciones hiperbólicas [https://es.wikipedia.org/wiki/Funci%C3%B3n_hiperb%C3%B3lica] son análogas a las funciones trigonométricas pero basadas en hipérbolas en lugar de en círculos.

math.acosh(x)

Retorna el coseno hiperbólico inverso de x.

math.asinh(x)

Retorna el seno hiperbólico inverso de x.

math.atanh(x)

Retorna la tangente hiperbólica inversa de x.

math.cosh(x)

Retorna el coseno hiperbólico de x.

math.sinh(x)

Retorna el seno hiperbólico de x.

math.tanh(x)

Retorna la tangente hiperbólica de x.

Funciones especiales

math.erf(x)

Retorna la función error [https://es.wikipedia.org/wiki/Funci%C3%B3n_error] en x.

La función erf() se puede utilizar para calcular funciones estadísticas tradicionales como la distribución normal estándar acumulativa [https://en.wikipedia.org/wiki/Normal_distribution#Cumulative_distribution_function]:

def phi(x):
    'Cumulative distribution function for the standard normal distribution'
    return (1.0 + erf(x / sqrt(2.0))) / 2.0

Nuevo en la versión 3.2.

math.erfc(x)

Retorna la función error complementaria en x. La función error complementaria [https://es.wikipedia.org/wiki/Funci%C3%B3n_error] se define como 1.0 - erf(x). Se usa para valores grandes de x donde una resta de 1 causaría una pérdida de presición [https://en.wikipedia.org/wiki/Loss_of_significance].

Nuevo en la versión 3.2.

math.gamma(x)

Retorna la función gamma [https://es.wikipedia.org/wiki/Funci%C3%B3n_gamma] en x.

Nuevo en la versión 3.2.

math.lgamma(x)

Retorna el logaritmo natural del valor absoluto de la función gamma en x.

Nuevo en la versión 3.2.

Constantes

math.pi

La constante matemática π = 3.141592…, hasta la precisión disponible.

math.e

La constante matemática e = 2.718281…, hasta la precisión disponible.

math.tau

La constante matemática τ = 6.283185…, hasta la precisión disponible. Tau es una constante del círculo igual a 2π, la razón entre la circunferencia de un círculo y su radio. Para obtener más información sobre Tau, consulta el video de Vi Hart, Pi is (still) Wrong [https://www.youtube.com/watch?v=jG7vhMMXagQ], y comienza a celebrar el el día de Tau [https://tauday.com/] ¡comiendo el doble de tarta!

Nuevo en la versión 3.6.

math.inf

Un valor infinito positivo en punto flotante. (Para un valor infinito negativo, usa -math.inf.) Equivalente a la salida de float('inf').

Nuevo en la versión 3.5.

math.nan

A floating-point «not a number» (NaN) value. Equivalent to the output of float('nan'). Due to the requirements of the IEEE-754 standard [https://en.wikipedia.org/wiki/IEEE_754], math.nan and float('nan') are not considered to equal to any other numeric value, including themselves. To check whether a number is a NaN, use the isnan() function to test for NaNs instead of is or ==. Example:

>>> import math
>>> math.nan == math.nan
False
>>> float('nan') == float('nan')
False
>>> math.isnan(math.nan)
True
>>> math.isnan(float('nan'))
True

Nuevo en la versión 3.5.

CPython implementation detail: El módulo math consiste principalmente en delgados envoltorios alrededor de las funciones matemáticas de la biblioteca de C de la plataforma. El comportamiento en casos excepcionales sigue el Anexo F del estándar C99 cuando corresponda. La implementación actual lanzará un ValueError para operaciones no válidas como sqrt(-1.0) o log(0.0) (donde el estándar C99 recomienda señalar que la operación no es válida o que hay división entre cero), y un OverflowError para aquellos resultados de desbordamiento (por ejemplo, exp(1000.0)). No se retornará NaN para ninguna de las funciones anteriores, a no ser que al menos uno de los argumentos de la función sea NaN. En este caso, la mayoría de las funciones retornan NaN, pero de nuevo (de acuerdo con el apéndice F del estándar C99) hay algunas excepciones a esta regla, por ejemplo pow(float('nan'), 0.0) o hypot(float('nan'), float('inf')).

Ten en cuenta que Python no hace ningún esfuerzo por distinguir los NaN de señalización de los NaN silenciosos, y el comportamiento de señalización de los NaN permanece sin especificar. El comportamiento estándar es tratar a todos los NaN como silenciosos.

Ver también

Módulo cmath

Versiones de muchas de estas funciones para números complejos.

cmath – Función matemática para números complejos

Este modulo proporciona acceso a funciones matemáticas para números complejos. Las funciones de este módulo aceptan números enteros, números de coma flotante o números complejos como argumentos. Aceptarán además cualquier objeto de Python que tenga tanto un método __complex__() o un método __float__() : estos métodos son usados para convertir el objeto a un número complejo o de coma flotante, respectivamente, y la función es entonces aplicada al resultado de la conversión.

Nota

En sistemas con hardware y soporte del sistema para ceros con signo, las funciones que involucran tramos son continuas en ambos lados del tramo: el signo de cero distingue un lado del tramo del otro. En plataformas que no soportan el cero con signo la continuidad es especificada abajo.

Conversión a y desde coordenadas polares

Un numero complejo de Python z se almacena internamente usando coordenadas rectangulares o cartesianas. Esta determinado completamente por su parte real z.real``y su *parte imaginaria*``z.imag. Dicho de otra forma:

z == z.real + z.imag*1j

Las coordenadas polares dan una alternativa a la representación de números complejos. En las coordenadas polares, un número complejo z se define por los módulos r y el ángulo de fase phi. El módulo r es la distancia desde z hasta el origen, mientras que la fase phi es el ángulo que va en contra de las agujas del reloj, medido en radianes, desde el eje positivo de las X hasta el segmento de linea que une el origen con z.

Las siguientes funciones pueden ser usadas para convertir desde coordenadas rectangulares nativas hasta coordenadas polares y viceversa.

cmath.phase(x)

Retorna la fase de x (también conocido como el argumento de x), como un número de coma flotante. phase(x) es equivalente a math.atan2(x.imag, x.real). El resultado se encuentra en el rango [-π, π], y el tramo para esta operación se sostiene a lo largo del eje de abscisas negativo, continuo desde abajo. En sistemas con soporte para el número 0 con signo (que son las mayoría de ellos en uso vigente), esto significa que el signo del resultado es el mismo como el signo de x.imag, incluso donde x.imag es cero:

>>> phase(complex(-1.0, 0.0))
3.141592653589793
>>> phase(complex(-1.0, -0.0))
-3.141592653589793

Nota

El módulo (valor absoluto) de un número complejo x puede ser calculado usado la función predeterminada abs(). No existe otra función aparte del módulo cmath para esta operación.

cmath.polar(x)

Retorna la representación de x en coordenadas polares. Retorna un par (r, phi) donde r es el módulo de x y phi es la fase de x. polar(x) ``es equivalente a ``(abs(x), phase(x)).

cmath.rect(r, phi)

Retorna el número complejo x con coordenadas polares r y phi. Esto es equivalente a r*(math.cos(phi) + math.sin(phi)*1j).

Funciones logarítmicas y de potencias

cmath.exp(x)

Retorna e elevado a la potencia de x, donde e es la base de los logaritmos naturales.

cmath.log(x[, base])

Retorna el logaritmo de x dada una base. Si la base no se especifica, retorna el logaritmo natural de x .No hay tramo, desde 0 en el eje negativo real hasta -∞, continuo desde arriba.

cmath.log10(x)

Retorna el logaritmo en base de 10 de x. Tiene el mismo tramo que log().

cmath.sqrt(x)

Retorna la raíz cuadrada de x. Tiene el mismo tramo que log().

Funciones trigonométricas

cmath.acos(x)

Retorna el arcocoseno de x. Existen dos tramos: Uno que se extiende desde 1 sobre todo el eje de abscisas hasta ∞, continuo desde abajo. El otro se extiende desde -1 a lo largo del eje de abscisas hasta -∞, continuo por arriba.

cmath.asin(x)

Retorna el arcoseno de x. Este tiene los mismos tramos que acos().

cmath.atan(x)

Retorna el arcotangente de x. Tiene dos tramos. Uno se extiende desde 1j a lo largo de el eje de abscisas imaginario ∞j, continuo desde la derecha. El otro extiende desde -1j` a lo largo de el eje de abscisas hasta -∞j , continuo desde la izquierda.

cmath.cos(x)

Retorna el coseno de x.

cmath.sin(x)

Retorna el seno de x.

cmath.tan(x)

Retorna la tangente de x.

Funciones hiperbólicas

cmath.acosh(x)

Retorna el inverso del coseno hiperbólico de x. Tiene un tramo, que se extiende desde la izquierda desde 1 a lo largo del eje de abscisas hasta -∞, continuo desde abajo.

cmath.asinh(x)

Retorna el inverso del seno hiperbólico de x. Tiene dos tramos. Uno se extiende desde 1j a lo largo de el eje de abscisas imaginario ∞j, continuo desde la derecha. El otro se extiende desde -1j a lo largo de el eje de abscisas hasta -∞j, continuo desde la izquierda.

cmath.atanh(x)

Retorna el inverso de la tangente hiperbólica de x. Tiene dos tramos: Uno se extiende desde 1 a lo largo de las abscisas reales hasta ∞, continuo desde abajo. El otro se extiende desde -1``a lo largo de las abscisas reales hasta `-∞``, continuo desde arriba.

cmath.cosh(x)

Retorna el coseno hiperbólico de x.

cmath.sinh(x)

Retorna el seno hiperbólico de x.

cmath.tanh(x)

Retorna la tangente hiperbólica de x.

Funciones de clasificación

cmath.isfinite(x)

Retorna True si tanto la parte imaginaria como real de x son finitas, y False en cualquier otro caso.

Nuevo en la versión 3.2.

cmath.isinf(x)

Retorna True si la parte real o la imaginaria de x es un infinito, y False en el caso contrario.

cmath.isnan(x)

Retorna True tanto si la parte real o imaginaria de x es NaN, y Falso en cualquier otro caso.

cmath.isclose(a, b, *, rel_tol=1e-09, abs_tol=0.0)

Retorna True si los valores a y b son cercanos el uno al otro y Falso de otro modo.

Que dos valores sean o no considerados como cercanos es determinado de acuerdo al valor absoluto y las tolerancias relativas.

rel_tol es la tolerancia relativa – es el máximo valor permitido de la resta entre a y b, relativo al valor absoluto más grande de a o b. Por ejemplo, para fijar una tolerancia del 5%, usar rel_tol=0.05. El valor de tolerancia por defecto es 1e-09, lo que asegura que los dos valores son los mismos en aproximadamente 9 dígitos decimales. rel_tol debe ser mayor que cero.

abs_tol es la tolerancia mínima absoluta – útil a la hora de hacer comparaciones cercanas al cero. abs_tol debe ser al menos cero.

Si no ocurren errores, el resultado será: abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol).

Los valores especiales IEEE 754 de NaN, inf y``-inf`` serán manejados de acuerdo al estándar de IEEE. Especialmente, NaN no se considera cercano a ningún otro valor, incluido NaN. inf y -inf solo son considerados cercanos a sí mismos.

Nuevo en la versión 3.5.

Ver también

PEP 485 [https://www.python.org/dev/peps/pep-0485] – Una función para probar igualdad aproximada.

Constantes

cmath.pi

La constante matemática π, como número de coma flotante.

cmath.e

La constante matemática e, como número de coma flotante.

cmath.tau

La constante matemática τ, como número de coma flotante.

Nuevo en la versión 3.6.

cmath.inf

Números de coma flotante de +infinito. Equivalente a float('inf').

Nuevo en la versión 3.6.

cmath.infj

Números complejos con la parte real cero y números positivos infinitos como la parte imaginaria. Equivalente a complex(0.0, float('inf')).

Nuevo en la versión 3.6.

cmath.nan

El valor del número de coma flotante «not a number» (NaN) . Equivalente a float('nan').

Nuevo en la versión 3.6.

cmath.nanj

Números complejos con parte real cero y como parte imaginaria NaN. Equivalente a complex(0.0, float('nan')).

Nuevo en la versión 3.6.

Nótese que la selección de funciones es similar, pero no idéntica, a la del módulo math. El motivo de tener dos módulos se halla en que algunos usuarios no se encuentran interesados en números complejos, y quizás ni siquiera sepan que son. Preferirían que math.sqrt(-1) lance una excepción a que retorne un número complejo. Además fíjese que las funciones definidas en cmath siempre retornan un número complejo, incluso si la respuesta puede ser expresada como un número real (en cuyo caso el número complejo tiene una parte imaginaria de cero).

Un apunte en los tramos: Se tratan de curvas en las cuales las funciones fallan a ser continua. Son un complemento necesario de muchas funciones complejas. Se asume que si se necesitan cálculos con funciones complejas, usted entenderá sobre tramos. Consulte casi cualquier(no muy elemental) libro sobre variables complejas para saber más. Para más información en la correcta elección de los tramos para propósitos numéricos, se recomienda la siguiente bibliografía:

Ver también

Kahan, W: Branch cuts for complex elementary functions; o, Much ado about nothing’s sign bit. En Iserles, A., and Powell, M. (eds.), The state of the art in numerical analysis. Clarendon Press (1987) pp165–211.

decimal — Aritmética decimal de coma fija y coma flotante

Código fuente: Lib/decimal.py [https://github.com/python/cpython/tree/3.9/Lib/decimal.py]

El módulo decimal proporciona soporte para aritmética decimal de coma flotante rápida y con redondeo matemáticamente correcto. Ofrece varias ventajas en comparación con el tipo de dato float:

Decimal «se basa en un modelo de coma flotante que se diseñó pensando en las personas, y necesariamente tiene un principio rector supremo: las computadoras deben proporcionar una aritmética que funcione de la misma manera que la aritmética que las personas aprenden en la escuela.» – extracto (traducido) de la especificación de la aritmética decimal.

Los números decimales se pueden representar de forma exacta en coma flotante decimal. En cambio, números como 1.1 y 2.2 no tienen representaciones exactas en coma flotante binaria. Los usuarios finales normalmente no esperaran que 1.1 + 2.2 se muestre como 3.3000000000000003, como ocurre al usar la representación binaria en coma flotante.

La exactitud se traslada a la aritmética. En coma flotante decimal, 0.1 + 0.1 + 0.1 - 0.3 es exactamente igual a cero. En coma flotante binaria, el resultado es 5.5511151231257827e-017. Aunque cercanas a cero, las diferencias impiden pruebas de igualdad confiables y las diferencias pueden acumularse. Por estas razones, se recomienda el uso de decimal en aplicaciones de contabilidad con estrictas restricciones de confiabilidad.

El módulo decimal incorpora una noción de dígitos significativos, de modo que 1.30 + 1.20 es 2.50. El cero final se mantiene para indicar el número de dígitos significativos. Esta es la representación habitual en aplicaciones monetarias. Para la multiplicación, el método de «libro escolar» utilizado usa todas las cifras de los multiplicandos. Por ejemplo, 1.3 * 1.2 es igual a 1.56, mientras que 1.30 * 1.20 es igual a 1.5600.

A diferencia del punto flotante binario basado en hardware, el módulo decimal tiene una precisión modificable por el usuario (por defecto es de 28 dígitos decimales) que puede ser tan grande como sea necesario para un problema dado:

>>> from decimal import *
>>> getcontext().prec = 6
>>> Decimal(1) / Decimal(7)
Decimal('0.142857')
>>> getcontext().prec = 28
>>> Decimal(1) / Decimal(7)
Decimal('0.1428571428571428571428571429')

Tanto la representación en coma flotante binaria como la decimal se implementan de acuerdo a estándares publicados. Mientras que el tipo float expone solo una pequeña parte de sus capacidades, el módulo decimal expone todos los componentes requeridos del estándar. Cuando es necesario, el desarrollador tiene control total sobre el redondeo y la gestión de las señales. Esto incluye la capacidad de forzar la aritmética exacta, utilizando excepciones para bloquear cualquier operación inexacta.

El módulo decimal fue diseñado para admitir «indiscriminadamente, tanto aritmética decimal exacta sin redondeo (a veces llamada aritmética de coma fija) como la aritmética de coma flotante con redondeo.» – extracto (traducido) de la especificación de la aritmética decimal.

El módulo está diseñado en torno a tres conceptos: el número decimal, el contexto aritmético y las señales.

Un número decimal es inmutable. Tiene un signo, un coeficiente y un exponente. Para conservar el número de dígitos significativos, los ceros iniciales no se truncan. Los números decimales también incluyen valores especiales como Infinity, -Infinity y NaN. El estándar también marca la diferencia entre -0 y +0.

El contexto aritmético es un entorno que permite especificar una precisión, reglas de redondeo, límites en los exponentes, flags que indican el resultado de las operaciones y habilitadores de trampas que especifican si las señales (reportadas durante operaciones ilegales) son tratadas o no como excepciones de Python. Las opciones de redondeo incluyen ROUND_CEILING, ROUND_DOWN, ROUND_FLOOR, ROUND_HALF_DOWN, ROUND_HALF_EVEN, ROUND_HALF_UP, ROUND_UP y ROUND_05UP.

Las señales son grupos de condiciones excepcionales que ocurren durante el cálculo. Dependiendo de las necesidades de la aplicación, las señales pueden ignorarse, tratarse como información o tratarse como excepciones. Las señales existentes en el módulo decimal son Clamped, InvalidOperation, DivisionByZero, Inexact, Rounded, Subnormal, Overflow, Underflow y FloatOperation.

Por cada señal hay un flag y un habilitador de trampa. Cuando ocurre una operación ilegal, su flag se establece en uno, luego, si su habilitador de trampa está establecido en uno, se lanza una excepción. La configuración de los flags es persistente, por lo que el usuario debe restablecerlos antes de comenzar un cálculo que desee monitorear.

Ver también

Especificación general de la aritmética decimal de IBM, The General Decimal Arithmetic Specification [http://speleotrove.com/decimal/decarith.html].

Tutorial de inicio rápido

El punto de partida habitual para usar decimales es importar el módulo, ver el contexto actual con getcontext() y, si es necesario, establecer nuevos valores para la precisión, el redondeo o trampas de señales habilitadas:

>>> from decimal import *
>>> getcontext()
Context(prec=28, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,
        capitals=1, clamp=0, flags=[], traps=[Overflow, DivisionByZero,
        InvalidOperation])

>>> getcontext().prec = 7       # Set a new precision

Las instancias de la clase Decimal se pueden construir a partir de números enteros, cadenas de caracteres, flotantes o tuplas. La construcción a partir de un número entero o flotante realiza una conversión exacta del valor de ese número. Los números decimales incluyen valores especiales como NaN, que significa «No es un número», Infinity positivo y negativo o -0:

>>> getcontext().prec = 28
>>> Decimal(10)
Decimal('10')
>>> Decimal('3.14')
Decimal('3.14')
>>> Decimal(3.14)
Decimal('3.140000000000000124344978758017532527446746826171875')
>>> Decimal((0, (3, 1, 4), -2))
Decimal('3.14')
>>> Decimal(str(2.0 ** 0.5))
Decimal('1.4142135623730951')
>>> Decimal(2) ** Decimal('0.5')
Decimal('1.414213562373095048801688724')
>>> Decimal('NaN')
Decimal('NaN')
>>> Decimal('-Infinity')
Decimal('-Infinity')

Si la señal FloatOperation es atrapada, la mezcla accidental de decimales y flotantes en constructores o comparaciones de orden lanzará una excepción:

>>> c = getcontext()
>>> c.traps[FloatOperation] = True
>>> Decimal(3.14)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
decimal.FloatOperation: [<class 'decimal.FloatOperation'>]
>>> Decimal('3.5') < 3.7
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
decimal.FloatOperation: [<class 'decimal.FloatOperation'>]
>>> Decimal('3.5') == 3.5
True

Nuevo en la versión 3.3.

La significación de un nuevo objeto Decimal es determinada únicamente por el número de dígitos ingresados. La precisión y el redondeo establecidos en el contexto solo entran en juego durante las operaciones aritméticas.

>>> getcontext().prec = 6
>>> Decimal('3.0')
Decimal('3.0')
>>> Decimal('3.1415926535')
Decimal('3.1415926535')
>>> Decimal('3.1415926535') + Decimal('2.7182818285')
Decimal('5.85987')
>>> getcontext().rounding = ROUND_UP
>>> Decimal('3.1415926535') + Decimal('2.7182818285')
Decimal('5.85988')

Se lanza una excepción InvalidOperation si durante la construcción de un objeto Decimal se exceden los límites internos de la versión de C:

>>> Decimal("1e9999999999999999999")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
decimal.InvalidOperation: [<class 'decimal.InvalidOperation'>]

Distinto en la versión 3.3.

Los objetos Decimal interactúan bien con gran parte del resto de Python. Aquí hay un pequeño circo volador de punto flotante decimal:

>>> data = list(map(Decimal, '1.34 1.87 3.45 2.35 1.00 0.03 9.25'.split()))
>>> max(data)
Decimal('9.25')
>>> min(data)
Decimal('0.03')
>>> sorted(data)
[Decimal('0.03'), Decimal('1.00'), Decimal('1.34'), Decimal('1.87'),
 Decimal('2.35'), Decimal('3.45'), Decimal('9.25')]
>>> sum(data)
Decimal('19.29')
>>> a,b,c = data[:3]
>>> str(a)
'1.34'
>>> float(a)
1.34
>>> round(a, 1)
Decimal('1.3')
>>> int(a)
1
>>> a * 5
Decimal('6.70')
>>> a * b
Decimal('2.5058')
>>> c % a
Decimal('0.77')

Y algunas funciones matemáticas también están disponibles para Decimal:

>>> getcontext().prec = 28
>>> Decimal(2).sqrt()
Decimal('1.414213562373095048801688724')
>>> Decimal(1).exp()
Decimal('2.718281828459045235360287471')
>>> Decimal('10').ln()
Decimal('2.302585092994045684017991455')
>>> Decimal('10').log10()
Decimal('1')

El método quantize() redondea un número a un exponente fijo. Este método es útil para aplicaciones monetarias, que a menudo redondean los resultados a un número fijo de dígitos significativos:

>>> Decimal('7.325').quantize(Decimal('.01'), rounding=ROUND_DOWN)
Decimal('7.32')
>>> Decimal('7.325').quantize(Decimal('1.'), rounding=ROUND_UP)
Decimal('8')

Como se muestra arriba, la función getcontext() accede al contexto actual y permite cambiar la configuración. Este enfoque satisface las necesidades de la mayoría de las aplicaciones.

Para trabajos más avanzados, puede resultar útil crear contextos alternativos utilizando el constructor Context(). Para activar un contexto alternativo, usa la función setcontext().

De acuerdo con el estándar, el módulo decimal proporciona dos contextos estándar listos para usar, BasicContext y ExtendedContext. El primero es particularmente útil para la depuración, ya que muchas de las trampas de señales están habilitadas por defecto:

>>> myothercontext = Context(prec=60, rounding=ROUND_HALF_DOWN)
>>> setcontext(myothercontext)
>>> Decimal(1) / Decimal(7)
Decimal('0.142857142857142857142857142857142857142857142857142857142857')

>>> ExtendedContext
Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,
        capitals=1, clamp=0, flags=[], traps=[])
>>> setcontext(ExtendedContext)
>>> Decimal(1) / Decimal(7)
Decimal('0.142857143')
>>> Decimal(42) / Decimal(0)
Decimal('Infinity')

>>> setcontext(BasicContext)
>>> Decimal(42) / Decimal(0)
Traceback (most recent call last):
  File "<pyshell#143>", line 1, in -toplevel-
    Decimal(42) / Decimal(0)
DivisionByZero: x / 0

Los objetos Context también tienen flags de señalización para detectar condiciones excepcionales detectadas durante los cálculos. Estos flags permanecen habilitados hasta que se restablecen explícitamente. Por esta razón, suele ser buena idea restablecerlos mediante el método clear_flags() antes de proceder con cada conjunto de cálculos monitorizados.

>>> setcontext(ExtendedContext)
>>> getcontext().clear_flags()
>>> Decimal(355) / Decimal(113)
Decimal('3.14159292')
>>> getcontext()
Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,
        capitals=1, clamp=0, flags=[Inexact, Rounded], traps=[])

La entrada flags muestra que la aproximación racional de Pi fue redondeada (los dígitos más allá de la precisión especificada por el contexto se descartaron) y que el resultado es inexacto (algunos de los dígitos descartados no eran cero).

Las trampas de señales se habilitan a través del diccionario expuesto por el atributo traps del objeto Context:

>>> setcontext(ExtendedContext)
>>> Decimal(1) / Decimal(0)
Decimal('Infinity')
>>> getcontext().traps[DivisionByZero] = 1
>>> Decimal(1) / Decimal(0)
Traceback (most recent call last):
  File "<pyshell#112>", line 1, in -toplevel-
    Decimal(1) / Decimal(0)
DivisionByZero: x / 0

La mayoría de los programas ajustan el contexto actual una sola vez, al comienzo del programa. Y, en muchas aplicaciones, los datos se convierten a Decimal mediante una única conversión dentro de un bucle. Con el contexto establecido y los decimales creados, la mayor parte del programa manipula los datos de la misma forma que con otros tipos numéricos de Python.

Objetos Decimal

class decimal.Decimal(value="0", context=None)

Construye un nuevo objeto Decimal basado en value.

value puede ser un entero, una cadena de caracteres, una tupla, un float u otro objeto Decimal. Si no se proporciona value, retorna Decimal('0'). Si value es una cadena, debe ajustarse a la sintaxis de cadena numérica decimal después de que los espacios en blanco iniciales y finales, así como los guiones bajos, sean eliminados:

sign           ::=  '+' | '-'
digit          ::=  '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'
indicator      ::=  'e' | 'E'
digits         ::=  digit [digit]...
decimal-part   ::=  digits '.' [digits] | ['.'] digits
exponent-part  ::=  indicator [sign] digits
infinity       ::=  'Infinity' | 'Inf'
nan            ::=  'NaN' [digits] | 'sNaN' [digits]
numeric-value  ::=  decimal-part [exponent-part] | infinity
numeric-string ::=  [sign] numeric-value | [sign] nan

También se permiten otros dígitos decimales Unicode en aquellos lugares en los que arriba aparece digit. Estos incluyen dígitos decimales de otros alfabetos (por ejemplo, dígitos del alfabeto árabe-índico y devanāgarī) junto con los dígitos de ancho completo desde '\uff10' a '\uff19'.

Si value es un objeto tuple, debe tener tres componentes, un signo (0 para positivo o 1 para negativo), un objeto tuple con los dígitos y un exponente entero. Por ejemplo, Decimal((0, (1, 4, 1, 4), -3)) retorna Decimal('1.414').

Si value es un float, el valor binario de coma flotante se convierte sin pérdidas a su equivalente decimal exacto. Esta conversión a menudo puede requerir 53 o más dígitos de precisión. Por ejemplo, Decimal(float('1.1')) se convierte en Decimal('1.100000000000000088817841970012523233890533447265625').

La precisión de context no afecta a la cantidad de dígitos almacenados. Eso está determinado exclusivamente por el número de dígitos en value. Por ejemplo, Decimal('3.00000') registra los cinco ceros incluso si la precisión del contexto es solo tres.

El propósito del argumento context es determinar qué hacer si value es una cadena de caracteres mal formada. Si el contexto atrapa la señal InvalidOperation, se genera una excepción; de lo contrario, el constructor retorna un nuevo decimal con el valor NaN.

Una vez construidos, los objetos Decimal son inmutables.

Distinto en la versión 3.2: Ahora se permite que el argumento del constructor sea una instancia float.

Distinto en la versión 3.3: Los argumentos float ahora generan una excepción si se establece la trampa FloatOperation. Por defecto, la trampa está desactivada.

Distinto en la versión 3.6: Se permiten guiones bajos para la agrupación, como ocurre en el código con los literales enteros y de punto flotante.

Los objetos de coma flotante decimal comparten muchas propiedades con los otros tipos numéricos integrados, como float e int. Se aplican todas las operaciones matemáticas habituales y los métodos especiales. Asimismo, los objetos decimales se pueden copiar, serializar con pickle, imprimir, usar como claves de un diccionario o como elementos de un conjunto, comparar, ordenar y convertir a otros tipos (como float o int).

Hay algunas pequeñas diferencias entre la aritmética en objetos decimales y la aritmética en enteros y flotantes. Cuando el operador de resto % se aplica a objetos Decimal, el signo del resultado es el signo del dividendo en lugar del signo del divisor:

>>> (-7) % 4
1
>>> Decimal(-7) % Decimal(4)
Decimal('-3')

El operador de división entera // se comporta de manera análoga, retornando la parte entera del cociente verdadero (truncando hacia cero) en lugar del resultado de aplicarle la función suelo. Esto se hace con la finalidad de preservar la identidad habitual x == (x // y) * y + x % y:

>>> -7 // 4
-2
>>> Decimal(-7) // Decimal(4)
Decimal('-1')

Los operadores % y // implementan las operaciones remainder y divide-integer (respectivamente) como se describe en la especificación.

Los objetos de la clase Decimal generalmente no se pueden combinar con flotantes o instancias de fractions.Fraction en operaciones aritméticas: un intento de agregar un objeto Decimal a un float, por ejemplo, lanzará una excepción TypeError. Sin embargo, es posible usar los operadores de comparación de Python para comparar una instancia de Decimal x con otro número y. Esto evita resultados confusos al hacer comparaciones de igualdad entre números de diferentes tipos.

Distinto en la versión 3.2: Las comparaciones de tipo mixto entre instancias de Decimal y otros tipos numéricos ahora son totalmente compatibles.

Además de las propiedades numéricas estándar, los objetos de coma flotante decimal también tienen varios métodos especializados:

adjusted()

Retorna el exponente ajustado después de desplazar los dígitos del extremo derecho del coeficiente hasta que solo quede el dígito principal: Decimal('321e+5').adjusted() retorna siete. Se utiliza para determinar la posición del dígito más significativo con respecto al punto decimal.

as_integer_ratio()

Retorna un par de enteros (n, d) que representan la instancia de Decimal proporcionada como una fracción irreducible y con un denominador positivo:

>>> Decimal('-3.14').as_integer_ratio()
(-157, 50)

La conversión es exacta. Lanza una excepción OverflowError si se proporcionan valores infinitos y ValueError con valores NaN.

Nuevo en la versión 3.6.

as_tuple()

Retorna una representación en forma de named tuple del número: DecimalTuple(sign, digits, exponent).

canonical()

Retorna la codificación canónica del argumento. Actualmente, la codificación de una instancia de Decimal es siempre canónica, por lo que esta operación retorna su argumento sin cambios.

compare(other, context=None)

Compara los valores de dos instancias de Decimal. El método compare() retorna una instancia de Decimal, y si alguno de los operandos es un NaN, el resultado es un NaN:

a or b is a NaN  ==> Decimal('NaN')
a < b            ==> Decimal('-1')
a == b           ==> Decimal('0')
a > b            ==> Decimal('1')

compare_signal(other, context=None)

Esta operación es idéntica al método compare(), excepto que todos los valores NaN generan una señal. Es decir, si ninguno de los operandos es un NaN señalizador, cualquier operando de NaN silencioso se trata como si fuera un NaN señalizador.

compare_total(other, context=None)

Compara dos operandos utilizando su representación abstracta en lugar de su valor numérico. Similar al método compare(), pero el resultado proporciona un ordenamiento total en las instancias de Decimal. Dos instancias de Decimal con el mismo valor numérico, pero diferentes representaciones, se comparan como desiguales usando este orden:

>>> Decimal('12.0').compare_total(Decimal('12'))
Decimal('-1')

Los NaN silenciosos y señalizadores también se incluyen en el ordenamiento total. El resultado de esta función es Decimal('0') si ambos operandos tienen la misma representación, Decimal('-1') si el primer operando es menor en el orden total que el segundo y Decimal('1') si el primer operando es mayor en el orden total que el segundo operando. Consulta las especificaciones para obtener detalles sobre el ordenamiento total.

Esta operación no se ve afectada por el contexto y es silenciosa: no se cambian los flags y no se realiza ningún redondeo. Como excepción, la versión de C puede lanzar InvalidOperation si el segundo operando no se puede convertir exactamente.

compare_total_mag(other, context=None)

Compara dos operandos usando su representación abstracta en lugar de su valor, como en compare_total(), pero ignorando el signo de cada operando. x.compare_total_mag(y) es equivalente a x.copy_abs().compare_total(y.copy_abs()).

Esta operación no se ve afectada por el contexto y es silenciosa: no se cambian los flags y no se realiza ningún redondeo. Como excepción, la versión de C puede lanzar InvalidOperation si el segundo operando no se puede convertir exactamente.

conjugate()

Simplemente retorna self (el propio objeto al que pertenece el método invocado). Este método existe solo para cumplir con la Especificación decimal.

copy_abs()

Retorna el valor absoluto del argumento. Esta operación no se ve afectada por el contexto y es silenciosa: no se modifican los flags y no se realiza ningún redondeo.

copy_negate()

Retorna la negación del argumento. Esta operación no se ve afectada por el contexto y es silenciosa: no se cambian los flags y no se realiza ningún redondeo.

copy_sign(other, context=None)

Retorna una copia del primer operando pero con el signo establecido para que sea el mismo que el del segundo operando. Por ejemplo:

>>> Decimal('2.3').copy_sign(Decimal('-1.5'))
Decimal('-2.3')

Esta operación no se ve afectada por el contexto y es silenciosa: no se cambian los flags y no se realiza ningún redondeo. Como excepción, la versión de C puede lanzar InvalidOperation si el segundo operando no se puede convertir exactamente.

exp(context=None)

Retorna el valor de la función exponencial (natural) e**x en el número dado. El resultado es correctamente redondeado utilizando el modo de redondeo ROUND_HALF_EVEN.

>>> Decimal(1).exp()
Decimal('2.718281828459045235360287471')
>>> Decimal(321).exp()
Decimal('2.561702493119680037517373933E+139')

from_float(f)

Método de clase que convierte un flotante en un número decimal, de forma exacta.

Nota que Decimal.from_float (0.1) no es lo mismo que Decimal(“0.1”). Dado que 0.1 no es exactamente representable en coma flotante binaria, el valor se almacena como el valor representable más cercano, que es 0x1.999999999999ap-4. Ese valor equivalente en decimal es 0.1000000000000000055511151231257827021181583404541015625.

Nota

Desde Python 3.2 en adelante, una instancia de Decimal también se puede construir directamente desde una instancia de float.

>>> Decimal.from_float(0.1)
Decimal('0.1000000000000000055511151231257827021181583404541015625')
>>> Decimal.from_float(float('nan'))
Decimal('NaN')
>>> Decimal.from_float(float('inf'))
Decimal('Infinity')
>>> Decimal.from_float(float('-inf'))
Decimal('-Infinity')

Nuevo en la versión 3.1.

fma(other, third, context=None)

Fusión de la multiplicación y la suma. Retorna self*other+third sin redondeo del producto intermedio self*other.

>>> Decimal(2).fma(3, 5)
Decimal('11')

is_canonical()

Retorna True si el argumento es canónico y False en caso contrario. Actualmente, una instancia de Decimal es siempre canónica, por lo que esta operación siempre retorna True.

is_finite()

Retorna True si el argumento es un número finito y False si el argumento es un valor infinito o un NaN.

is_infinite()

Retorna True si el argumento es un valor infinito positivo o negativo y False en caso contrario.

is_nan()

Retorna True si el argumento es un NaN (silencioso o señalizador) y False en caso contrario.

is_normal(context=None)

Retorna True si el argumento es un número finito normal. Retorna False si el argumento es cero, subnormal, infinito o un NaN.

is_qnan()

Retorna True si el argumento es un NaN silencioso y False en caso contrario.

is_signed()

Retorna True si el argumento tiene signo negativo y False en caso contrario. Ten en cuenta que tanto los ceros como los NaN pueden tener signo.

is_snan()

Retorna True si el argumento es un NaN señalizador y False en caso contrario.

is_subnormal(context=None)

Retorna True si el argumento es subnormal y False en caso contrario.

is_zero()

Retorna True si el argumento es un cero (positivo o negativo) y False en caso contrario.

ln(context=None)

Retorna el logaritmo natural (base e) del operando. El resultado es correctamente redondeado utilizando el modo de redondeo ROUND_HALF_EVEN.

log10(context=None)

Retorna el logaritmo en base diez del operando. El resultado es correctamente redondeado utilizando el modo de redondeo ROUND_HALF_EVEN.

logb(context=None)

Para un número distinto de cero, retorna el exponente ajustado de su operando como una instancia de Decimal. Si el operando es cero, se retorna Decimal('-Infinity') y se activa el flag DivisionByZero. Si el operando es infinito, se retorna Decimal('Infinity').

logical_and(other, context=None)

logic_and() es una operación lógica que toma dos operandos lógicos (consultar Operandos lógicos). El resultado es el and dígito por dígito de los dos operandos.

logical_invert(context=None)

logic_invert() es una operación lógica. El resultado es la inversión dígito a dígito del operando.

logical_or(other, context=None)

logical_or() es una operación lógica que toma dos operandos lógicos (consultar Operandos lógicos). El resultado es un or dígito a dígito de los dos operandos.

logical_xor(other, context=None)

logic_xor() es una operación lógica que toma dos operandos lógicos (consultar Operandos lógicos). El resultado es la disyunción exclusiva («exclusive or») dígito a dígito de ambos operandos.

max(other, context=None)

Como max(self, other), excepto que la regla de redondeo del contexto se aplica antes de retornar y que los valores NaN generan una señal o son ignorados (dependiendo del contexto y de si son señalizadores o silenciosos).

max_mag(other, context=None)

Similar al método max(), pero la comparación se realiza utilizando los valores absolutos de los operandos.

min(other, context=None)

Como min(self, other), excepto que la regla de redondeo del contexto se aplica antes de retornar y que los valores NaN generan una señal o se ignoran (según el contexto y si son señalizadores o no).

min_mag(other, context=None)

Similar al método min(), pero la comparación se realiza utilizando los valores absolutos de los operandos.

next_minus(context=None)

Retorna el número más grande representable en el contexto proporcionado (o en el contexto del hilo actual si no se proporciona un contexto) que sea más pequeño que el operando proporcionado.

next_plus(context=None)

Retorna el número más pequeño representable en el contexto proporcionado (o en el contexto del hilo actual si no se proporciona ningún contexto) que sea más grande que el operando proporcionado.

next_toward(other, context=None)

Si los dos operandos no son iguales, retorna el número más cercano al primer operando en la dirección del segundo operando. Si ambos operandos son numéricamente iguales, retorna una copia del primer operando con el signo establecido para que sea el mismo que el signo del segundo operando.

normalize(context=None)

Normaliza el número, eliminando los ceros finales situados más a la derecha y convirtiendo cualquier resultado igual a Decimal('0') en Decimal('0e0'). Se utiliza para producir valores canónicos para atributos de una clase de equivalencia. Por ejemplo, Decimal('32 .100') y Decimal('0.321000e+2') se normalizan ambos al valor equivalente Decimal('32 .1').

number_class(context=None)

Retorna una cadena de caracteres que describe la class del operando. El valor retornado es una de las siguientes diez cadenas de caracteres.

"-Infinity", que indica que el operando es un infinito negativo.

"-Normal", que indica que el operando es un número normal negativo.

"-Subnormal", que indica que el operando es negativo y subnormal.

"-Zero", que indica que el operando es un cero negativo.

"+Zero", que indica que el operando es un cero positivo.

"+Subnormal",que indica que el operando es positivo y subnormal.

"+Normal", que indica que el operando es un número normal positivo.

"+Infinity", que indica que el operando es un infinito positivo.

"NaN", que indica que el operando es un NaN (no es un número) silencioso.

"sNaN", que indica que el operando es un NaN (no es un número) señalizador.

quantize(exp, rounding=None, context=None)

Retorna un valor igual al primer operando después de ser redondeado y de asignarle el exponente del segundo operando.

>>> Decimal('1.41421356').quantize(Decimal('1.000'))
Decimal('1.414')

A diferencia de otras operaciones, se genera una señal InvalidOperation si la longitud del coeficiente después de la operación quantize es mayor que la precisión. Esto garantiza que, a menos que exista una condición de error, el exponente cuantificado sea siempre igual al del operando de la derecha.

Además, a diferencia de otras operaciones, quantize nunca genera una señal Underflow, incluso si el resultado es subnormal e inexacto.

Si el exponente del segundo operando es mayor que el del primero, puede ser necesario redondear. En este caso, el modo de redondeo está determinado por el argumento rounding, si se proporciona, o por el argumento context en caso contrario. Si no se proporciona ninguno de estos dos argumentos, se utiliza el modo de redondeo establecido en el contexto del hilo actual.

Se retorna un error siempre que el exponente resultante sea mayor que Emax o menor que Etiny.

radix()

Retorna Decimal(10), que es la raíz (base) en la que la clase Decimal hace toda su aritmética. Este método está incluido solo por compatibilidad con la especificación.

remainder_near(other, context=None)

Retorna el resto de dividir self entre other. Esto difiere de la operación self%other, en la que el signo del resto se elige para minimizar su valor absoluto. Más precisamente, el valor de retorno es self - n * other, donde n es el número entero más cercano al valor exacto de self / other. Si dos enteros están igualmente cerca, entonces el valor par es el elegido.

Si el resultado es cero, entonces su signo será el signo de self.

>>> Decimal(18).remainder_near(Decimal(10))
Decimal('-2')
>>> Decimal(25).remainder_near(Decimal(10))
Decimal('5')
>>> Decimal(35).remainder_near(Decimal(10))
Decimal('-5')

rotate(other, context=None)

Retorna el resultado de rotar los dígitos del primer operando en una cantidad especificada por el segundo operando. El segundo operando debe ser un número entero en el rango comprendido desde -precisión hasta precisión. El valor absoluto del segundo operando da el número de lugares a rotar. Si el segundo operando es positivo, la rotación es hacia la izquierda; de lo contrario, la rotación es hacia la derecha. El coeficiente del primer operando se rellena con ceros a la izquierda para satisfacer la precisión de longitud si es necesario. El signo y el exponente del primer operando no se modifican.

same_quantum(other, context=None)

Comprueba si self y other tienen el mismo exponente o si ambos son NaN.

Esta operación no se ve afectada por el contexto y es silenciosa: no se cambian los flags y no se realiza ningún redondeo. Como excepción, la versión de C puede lanzar InvalidOperation si el segundo operando no se puede convertir exactamente.

scaleb(other, context=None)

Retorna el primer operando con su exponente ajustado por el segundo. De manera equivalente, retorna el primer operando multiplicado por 10**other. El segundo operando debe ser un número entero.

shift(other, context=None)

Retorna el resultado de cambiar los dígitos del primer operando en una cantidad especificada por el segundo operando. El segundo operando debe ser un número entero en el rango comprendido desde -precisión hasta precisión. El valor absoluto del segundo operando da el número de lugares a desplazar. Si el segundo operando es positivo, el desplazamiento es hacia la izquierda; de lo contrario, el desplazamiento es hacia la derecha. Los dígitos desplazados en el coeficiente son ceros. El signo y el exponente del primer operando no se modifican.

sqrt(context=None)

Retorna la raíz cuadrada del argumento con precisión total.

to_eng_string(context=None)

Convierte a una cadena de caracteres, usando notación de ingeniería si se necesita un exponente.

La notación de ingeniería tiene como exponente un múltiplo de 3. Esto puede dejar hasta 3 dígitos a la izquierda del punto decimal y puede requerir la adición de uno o dos ceros finales.

Por ejemplo, este método convierte Decimal('123E+1') en Decimal('1.23E+3').

to_integral(rounding=None, context=None)

Idéntico al método to_integral_value(). El nombre to_integral se ha mantenido por compatibilidad con versiones anteriores.

to_integral_exact(rounding=None, context=None)

Redondea al entero más cercano, generando la señal Inexact o Rounded, según corresponda, si se produce un redondeo. El modo de redondeo está determinado por el parámetro rounding si es proporcionado, o por el establecido en el context proporcionado en caso contrario. Si no se proporciona ninguno de estos dos parámetros, se utiliza el modo de redondeo establecido en el contexto actual.

to_integral_value(rounding=None, context=None)

Redondea al entero más cercano sin generar la señal Inexact o Rounded. Si se proporciona, se aplica el método de redondeo especificado por rounding; en caso contrario, se utiliza el método de redondeo del context proporcionado o el del contexto actual.

Operandos lógicos

Los métodos logical_and(), logical_invert(), logical_or() y logical_xor() esperan que sus argumentos sean operandos lógicos. Un operando lógico es una instancia de Decimal cuyo exponente y signo son ambos cero, y cuyos dígitos son todos 0 o 1.

Objetos Context

Los contextos son entornos para operaciones aritméticas. Gobiernan la precisión, establecen reglas para el redondeo, determinan qué señales se tratan como excepciones y limitan el rango para los exponentes.

Cada hilo tiene su propio contexto actual, al que se accede o se reemplaza usando las funciones getcontext() y setcontext() respectivamente:

decimal.getcontext()

Retorna el contexto actual del hilo activo.

decimal.setcontext(c)

Establece c como contexto actual para el hilo activo.

También puedes usar la declaración with y la función localcontext() para cambiar temporalmente el contexto activo.

decimal.localcontext(ctx=None)

Retorna un gestor de contexto que establecerá el contexto actual para el hilo activo en una copia de ctx al ingresar en la declaración with y restaurará el contexto anterior al salir de la misma. Si no se especifica ningún contexto, se utiliza una copia del contexto actual.

Por ejemplo, el siguiente código establece la precisión decimal actual en 42 lugares, realiza un cálculo y luego restaura automáticamente el contexto anterior:

from decimal import localcontext

with localcontext() as ctx:
    ctx.prec = 42   # Perform a high precision calculation
    s = calculate_something()
s = +s  # Round the final result back to the default precision

También se pueden crear nuevos contextos utilizando el constructor de la clase Context que se describe a continuación. Además, el módulo proporciona tres contextos prediseñados:

class decimal.BasicContext

Este es un contexto estándar definido por la Especificación general de la aritmética decimal. La precisión se establece en nueve. El redondeo se establece en ROUND_HALF_UP. Se restablecen todos los flags. Todas las trampas están habilitadas (las señales son tratadas como excepciones) excepto Inexact, Rounded y Subnormal.

Debido a que la mayoría de las trampas están habilitadas, este contexto es especialmente útil para la depuración.

class decimal.ExtendedContext

Este es un contexto estándar definido por la Especificación general de la aritmética decimal. La precisión se establece en nueve. El redondeo se establece en ROUND_HALF_EVEN. Se restablecen todos los flags. No se habilitan trampas (para que no se generen excepciones durante los cálculos).

Debido a que las trampas están deshabilitadas, este contexto es útil para aplicaciones que prefieren tener un valor NaN o Infinity como resultado en lugar de lanzar excepciones. Esto permite que una aplicación complete una ejecución en presencia de condiciones que, de otra manera, detendrían el programa.

class decimal.DefaultContext

Este contexto es utilizado por el constructor de la clase Context como un prototipo para nuevos contextos. Cambiar un campo (como la precisión) tiene el efecto de cambiar el valor predeterminado para los nuevos contextos creados por el constructor de Context.

Este contexto es más útil en entornos con múltiples hilos. Cambiar uno de los campos antes de que se inicien los hilos tiene el efecto de establecer valores predeterminados en todo el sistema. No se recomienda cambiar los campos después de que se hayan iniciado los hilos, ya que requeriría el uso de mecanismos de sincronización para evitar condiciones de carrera entre los hilos.

En entornos de un solo hilo, es preferible no utilizar este contexto en absoluto. En su lugar, simplemente crea contextos explícitamente como se describe a continuación.

Los valores predeterminados son prec=28, rounding=ROUND_HALF_EVEN y trampas habilitadas para Overflow, InvalidOperation y DivisionByZero.

Además de los tres contextos proporcionados, se pueden crear nuevos contextos mediante el constructor de la clase Context.

class decimal.Context(prec=None, rounding=None, Emin=None, Emax=None, capitals=None, clamp=None, flags=None, traps=None)

Crea un nuevo contexto. Si no se especifica un campo, o es None, los valores predeterminados se copian de DefaultContext. Si el campo flags no está especificado, o es None, se restablecen todas los flags.

prec es un número entero en el rango [1, MAX_PREC] que establece la precisión para las operaciones aritméticas en el contexto.

La opción rounding es una de las constantes enumeradas en la sección Rounding Modes.

Los campos traps y flags enumeran las señales que se deben establecer. Generalmente, los nuevos contextos solo deben establecer trampas y dejar los flags sin establecer.

Los campos Emin y Emax son números enteros que especifican los límites externos permitidos para los exponentes. Emin debe estar en el rango [MIN_EMIN, 0] y Emax en el rango [0, MAX_EMAX].

El campo capitals es 0 o 1 (por defecto). Si se establece en 1, los exponentes se imprimen usando una E mayúscula; de lo contrario, se usa una e minúscula: Decimal('6.02e+23').

El campo clamp es 0 (por defecto) o 1. Si se establece en 1, el exponente e representable en este contexto de una instancia de Decimal está estrictamente limitado al rango Emin - prec + 1 <= e <= Emax - prec + 1. Si clamp es 0, entonces se cumple una condición más laxa: el exponente ajustado de la instancia de Decimal es como máximo Emax. Cuando clamp es 1, cuando sea posible, se reducirá el exponente de un número normal grande y se agregarán el número correspondiente de ceros a su coeficiente, a fin de que se ajuste a las restricciones del exponente; esto conserva el valor del número pero conlleva una pérdida de información causada por los ceros finales significativos. Por ejemplo:

>>> Context(prec=6, Emax=999, clamp=1).create_decimal('1.23e999')
Decimal('1.23000E+999')

Un valor clamp de 1 permite la compatibilidad con los formatos de intercambio decimal de ancho fijo especificados en IEEE 754.

La clase Context define varios métodos de propósito general, así como una gran cantidad de métodos para hacer aritmética directamente en un contexto dado. Además, para cada uno de los métodos de la clase Decimal descritos anteriormente (con la excepción de los métodos adjusted() y as_tuple()) hay un método correspondiente en la clase Context. Por ejemplo, para una instancia de Context C y una instancia de Decimal x, C.exp(x) es equivalente a x.exp(context=C). Cada método Context acepta también un entero de Python (una instancia de int) en cualquier lugar donde se acepte una instancia de Decimal.

clear_flags()

Restablece todos los flags a 0.

clear_traps()

Restablece todas las trampas a 0.

Nuevo en la versión 3.3.

copy()

Retorna un duplicado del contexto.

copy_decimal(num)

Retorna una copia de la instancia de Decimal num.

create_decimal(num)

Crea una nueva instancia de Decimal a partir de num pero usando self como contexto. A diferencia del constructor de Decimal, la precisión del contexto, el método de redondeo, los flags y las trampas se aplican a la conversión.

Esto es útil porque las constantes a menudo se proporcionan con una precisión mayor que la que necesita la aplicación. Otro beneficio es que el redondeo elimina inmediatamente los efectos no deseados de los dígitos más allá de la precisión actual. En el siguiente ejemplo, usar entradas no redondeadas significa que agregar cero a una suma puede cambiar el resultado:

>>> getcontext().prec = 3
>>> Decimal('3.4445') + Decimal('1.0023')
Decimal('4.45')
>>> Decimal('3.4445') + Decimal(0) + Decimal('1.0023')
Decimal('4.44')

Este método implementa la operación to-number de la especificación de IBM. Si el argumento es una cadena de caracteres, no se permiten espacios en blanco ni guiones bajos, ni al principio ni al final.

create_decimal_from_float(f)

Crea una nueva instancia de Decimal a partir de un flotante f, pero redondeando usando self como contexto. A diferencia del método de clase Decimal.from_float(), la precisión del contexto, el método de redondeo, los flags y las trampas se aplican a la conversión.

>>> context = Context(prec=5, rounding=ROUND_DOWN)
>>> context.create_decimal_from_float(math.pi)
Decimal('3.1415')
>>> context = Context(prec=5, traps=[Inexact])
>>> context.create_decimal_from_float(math.pi)
Traceback (most recent call last):
    ...
decimal.Inexact: None

Nuevo en la versión 3.1.

Etiny()

Retorna un valor igual a Emin - prec + 1 que es el valor mínimo del exponente para resultados subnormales. Cuando ocurre un desbordamiento numérico negativo («underflow»), el exponente se establece en Etiny.

Etop()

Retorna un valor igual a Emax - prec + 1.

El enfoque habitual para trabajar con decimales es crear instancias de la clase Decimal y luego aplicar operaciones aritméticas que tienen lugar dentro del contexto actual para el hilo activo. Un enfoque alternativo es utilizar métodos de contexto para calcular dentro de un contexto específico. Los métodos son similares a los de la clase Decimal y aquí solo se relatan brevemente.

abs(x)

Retorna el valor absoluto de x.

add(x, y)

Retorna la suma de x e y.

canonical(x)

Retorna el mismo objeto Decimal x.

compare(x, y)

Compara x e y numéricamente.

compare_signal(x, y)

Compara los valores de los dos operandos numéricamente.

compare_total(x, y)

Compara los dos operandos utilizando su representación abstracta.

compare_total_mag(x, y)

Compara los dos operandos utilizando su representación abstracta, ignorando el signo.

copy_abs(x)

Retorna una copia de x con el signo establecido en 0.

copy_negate(x)

Retorna una copia de x con el signo invertido.

copy_sign(x, y)

Copia el signo de y en x.

divide(x, y)

Retorna x dividido entre y.

divide_int(x, y)

Retorna x dividido entre y, truncando el resultado a un número entero.

divmod(x, y)

Divide dos números y retorna la parte entera del resultado.

exp(x)

Retorna e ** x.

fma(x, y, z)

Retorna x multiplicado por y, más z.

is_canonical(x)

Retorna True si x está en forma canónica, en caso contrario retorna False.

is_finite(x)

Retorna True si x es un valor finito, en caso contrario retorna False.

is_infinite(x)

Retorna True si x es un valor infinito, en caso contrario retorna False.

is_nan(x)

Retorna True si x es un valor qNaN o sNaN , en caso contrario retorna False.

is_normal(x)

Retorna True si x es un número normal, en caso contrario retorna False.

is_qnan(x)

Retorna True si x es un NaN silencioso, en caso contrario retorna False.

is_signed(x)

Retorna True si x es un valor negativo, en caso contrario retorna False.

is_snan(x)

Retorna True si x es un NaN señalizador, en caso contrario retorna False.

is_subnormal(x)

Retorna True si x es un número subnormal, en caso contrario retorna False.

is_zero(x)

Retorna True si x es un cero, en caso contrario retorna False.

ln(x)

Retorna el logaritmo natural (base e) de x.

log10(x)

Retorna el logaritmo en base 10 de x.

logb(x)

Retorna el exponente de la magnitud del MSD («dígito más significativo») del operando.

logical_and(x, y)

Aplica la operación lógica and entre los dígitos de cada operando.

logical_invert(x)

Invierte todos los dígitos en x.

logical_or(x, y)

Aplica la operación lógica or entre los dígitos de cada operando.

logical_xor(x, y)

Aplica la operación lógica xor entre los dígitos de cada operando.

max(x, y)

Compara dos valores numéricamente y retorna el mayor de ellos.

max_mag(x, y)

Compara los valores numéricamente ignorando sus signos.

min(x, y)

Compara dos valores numéricamente y retorna el menor de ellos.

min_mag(x, y)

Compara los valores numéricamente ignorando sus signos.

minus(x)

Se corresponde con el operador unario de resta (prefijo) de Python.

multiply(x, y)

Retorna el producto de x por y.

next_minus(x)

Retorna el número más grande representable menor que x.

next_plus(x)

Retorna el número más pequeño representable mayor que x.

next_toward(x, y)

Retorna el número más cercano a x, en la dirección de y.

normalize(x)

Reduce x a su forma más simple.

number_class(x)

Retorna una cadena de caracteres indicando la clase de x.

plus(x)

Se corresponde con el operador unario de suma (prefijo) de Python. Esta operación aplica la precisión y el redondeo establecidos en el contexto, por lo que no es una operación de identidad.

power(x, y, modulo=None)

Retorna x elevado a la potencia y, reconduciendo al módulo modulo si se proporciona.

Con dos argumentos, calcula x**y. Si x es negativo, entonces y debe ser un entero. El resultado será inexacto, a menos que y sea un entero y el resultado sea finito y pueda expresarse exactamente con los dígitos de la “precisión” establecida. Se utiliza el modo de redondeo establecido en el contexto. Los resultados siempre se redondean correctamente en la versión de Python.

Decimal(0) ** Decimal(0) results in InvalidOperation, and if InvalidOperation is not trapped, then results in Decimal('NaN').

Distinto en la versión 3.3: El módulo C calcula power() en términos de las funciones exp() y ln() redondeadas correctamente. El resultado está bien definido pero sólo «casi siempre correctamente redondeado».

Con tres argumentos, calcula (x**y) % modulo. Para la forma de tres argumentos, se mantienen las siguientes restricciones sobre los argumentos:

los tres argumentos deben ser enteros

y debe ser un valor no negativo

al menos uno, x o y , no debe ser cero

modulo no debe ser cero y tener como mínimo los dígitos de la “precisión”

El valor resultante de Context.power(x, y, modulo) es igual al valor que se obtendría calculando (x**y) % modulo con precisión ilimitada, la diferencia es que se calcula de manera más eficiente . El exponente del resultado es cero, independientemente de los exponentes de x, y y modulo. El resultado siempre es exacto.

quantize(x, y)

Retorna un valor igual a x (redondeado), pero que tiene el exponente de y.

radix()

Simplemente retorna 10, ya que es Decimal, :)

remainder(x, y)

Retorna el resto de la división entera.

El signo del resultado, si no es cero, es el mismo que el del dividendo original.

remainder_near(x, y)

Retorna x - y * n, donde n es el número entero más cercano al valor exacto de x / y (si el resultado es 0, entonces su signo será el signo de x).

rotate(x, y)

Retorna una copia de x rotada y veces.

same_quantum(x, y)

Retorna True si los dos operandos tienen el mismo exponente.

scaleb(x, y)

Retorna el primer operando después de agregar el segundo valor a su exponente.

shift(x, y)

Retorna una copia de x desplazada y veces.

sqrt(x)

Retorna la raíz cuadrada de un número no negativo para la precisión del contexto.

subtract(x, y)

Retorna la diferencia entre x e y.

to_eng_string(x)

Convierte a una cadena de caracteres, usando notación de ingeniería si se necesita un exponente.

La notación de ingeniería tiene como exponente un múltiplo de 3. Esto puede dejar hasta 3 dígitos a la izquierda del punto decimal y puede requerir la adición de uno o dos ceros finales.

to_integral_exact(x)

Redondea a un entero.

to_sci_string(x)

Convierte un número en una cadena de caracteres usando notación científica.

Constantes

Las constantes detalladas en esta sección solo son relevantes para el módulo de C. Se incluyen también en la versión pura de Python por compatibilidad.

32-bit

64-bit

decimal.MAX_PREC

425000000

999999999999999999

decimal.MAX_EMAX

425000000

999999999999999999

decimal.MIN_EMIN

-425000000

-999999999999999999

decimal.MIN_ETINY

-849999999

-1999999999999999997

decimal.HAVE_THREADS

El valor es True. Está obsoleta, debido ha que Python ahora siempre tiene soporte para hilos.

Obsoleto desde la versión 3.9.

decimal.HAVE_CONTEXTVAR

El valor predeterminado es True. Si Python se compila con la opción --without-decimal-contextvar, la versión de C usa un contexto de hilos locales en lugar de un contexto de corrutinas locales y el valor de la constante es False. Esto es algo más rápido en algunos escenarios de contexto anidado.

Nuevo en la versión 3.9: backported to 3.7 and 3.8.

Modos de redondeo

decimal.ROUND_CEILING

Redondear hacia Infinity.

decimal.ROUND_DOWN

Redondear hacia cero.

decimal.ROUND_FLOOR

Redondear hacia -Infinity.

decimal.ROUND_HALF_DOWN

Redondear al valor contiguo más cercano, con empates hacia cero.

decimal.ROUND_HALF_EVEN

Redondear al valor contiguo más cercano, con empates al entero par contiguo.

decimal.ROUND_HALF_UP

Redondear al valor contiguo más cercano, con empates alejándose de cero.

decimal.ROUND_UP

Redondear alejándose de cero.

decimal.ROUND_05UP

Si el último dígito después de redondear hacia cero es 0 ó 5, redondear alejándose de cero, en caso contrario, redondear hacia cero.

Señales

Las señales representan condiciones que surgen durante el cálculo. Cada una se corresponde con un solo flag de contexto y un habilitador de trampas de contexto.

El flag de contexto se establece siempre que se encuentra la condición. Después del cálculo, los flags pueden comprobarse con fines informativos (por ejemplo, para determinar si un cálculo fue exacto). Después de verificar los flags, asegúrate de borrarlos antes de comenzar con el siguiente cálculo.

Si el habilitador de trampas del contexto está configurado para la señal, entonces la condición hace que se lance una excepción de Python. Por ejemplo, si se establece la trampa DivisionByZero, se genera una excepción DivisionByZero al encontrar la condición.

class decimal.Clamped

Cambia un exponente para ajustar las restricciones de representación.

Normalmente, la restricción ocurre cuando un exponente cae fuera de los límites Emin y Emax del contexto. Si es posible, el exponente se reduce para ajustar agregando ceros al coeficiente.

class decimal.DecimalException

Clase base para otras señales. Es una subclase de ArithmeticError.

class decimal.DivisionByZero

Señala la división de un número no infinito entre cero.

Puede ocurrir en la división, en la división modular o al elevar un número a una potencia negativa. Si esta señal no es atrapada, se retorna Infinity o -Infinity, con el signo determinado por las entradas del cálculo.

class decimal.Inexact

Indica que se produjo un redondeo y el resultado no es exacto.

Señala que se descartaron dígitos distintos de cero durante el redondeo. Se retorna el resultado redondeado. El flag o la trampa de señal se utiliza para detectar cuando los resultados son inexactos.

class decimal.InvalidOperation

Señala que se realizó una operación no válida.

Indica que se solicitó una operación que no tiene lógica. Si esta señal no está atrapada, se retorna NaN. Las posibles causas incluyen:

Infinity - Infinity
0 * Infinity
Infinity / Infinity
x % 0
Infinity % x
sqrt(-x) and x > 0
0 ** 0
x ** (non-integer)
x ** Infinity

class decimal.Overflow

Desbordamiento numérico.

Indica que el exponente es mayor que max después de que se haya producido el redondeo. Si no está atrapada, el resultado depende del modo de redondeo, ya sea tirando hacia adentro hasta el mayor número finito representable o redondeando hacia afuera a Infinity. En cualquier caso, también se activan las señales Inexact y Rounded.

class decimal.Rounded

Se produjo un redondeo, aunque posiblemente no hubo pérdida de información.

Señal lanzada cada vez que el redondeo descarta dígitos; incluso si esos dígitos son cero (como al redondear 5.00 a 5.0). Si no está atrapada, se retorna el resultado sin cambios. Esta señal se utiliza para detectar la pérdida de dígitos significativos.

class decimal.Subnormal

El exponente antes del redondeo era menor que Emin.

Ocurre cuando el resultado de una operación es subnormal (el exponente es demasiado pequeño). Si no está atrapada, se retorna el resultado sin cambios.

class decimal.Underflow

Desbordamiento numérico negativo con resultado redondeado a cero.

Ocurre cuando un resultado subnormal se lleva a cero mediante redondeo. Inexact y Subnormal también se señalan.

class decimal.FloatOperation

Habilita una semántica más estricta para mezclar flotantes y objetos Decimal.

Si la señal no está atrapada (predeterminado), se permite mezclar flotantes y objetos Decimal en el constructor de Decimal, en el método create_decimal() y en todos los operadores de comparación. Tanto la conversión como las comparaciones son exactas. Cualquier ocurrencia de una operación mixta se registra silenciosamente estableciendo FloatOperation a los flags del contexto. Las conversiones explícitas usando from_float() o create_decimal_from_float() no establecen el flag.

En caso contrario (la señal está atrapada), solo las comparaciones de igualdad y las conversiones explícitas permanecen silenciadas. Todas las demás operaciones mixtas lanzan una excepción FloatOperation.

La siguiente tabla resume la jerarquía de señales:

exceptions.ArithmeticError(exceptions.Exception)
    DecimalException
        Clamped
        DivisionByZero(DecimalException, exceptions.ZeroDivisionError)
        Inexact
            Overflow(Inexact, Rounded)
            Underflow(Inexact, Rounded, Subnormal)
        InvalidOperation
        Rounded
        Subnormal
        FloatOperation(DecimalException, exceptions.TypeError)

Notas sobre la representación en coma flotante

Mitigación del error de redondeo usando mayor precisión

El uso de la coma flotante decimal elimina el error de representación decimal (haciendo posible representar 0.1 de forma exacta). Sin embargo, algunas operaciones aún pueden incurrir en errores de redondeo cuando los dígitos distintos de cero exceden la precisión fija.

Los efectos del error de redondeo pueden amplificarse mediante la suma o resta de cantidades casi compensadas, lo que da como resultado una pérdida de significación. Knuth proporciona dos ejemplos instructivos en los que la aritmética de coma flotante redondeada con precisión insuficiente provoca la ruptura de las propiedades asociativas y distributivas de la suma:

# Examples from Seminumerical Algorithms, Section 4.2.2.
>>> from decimal import Decimal, getcontext
>>> getcontext().prec = 8

>>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
>>> (u + v) + w
Decimal('9.5111111')
>>> u + (v + w)
Decimal('10')

>>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')
>>> (u*v) + (u*w)
Decimal('0.01')
>>> u * (v+w)
Decimal('0.0060000')

El módulo decimal permite restaurar las identidades ampliando la precisión lo suficiente para evitar la pérdida de significación:

>>> getcontext().prec = 20
>>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
>>> (u + v) + w
Decimal('9.51111111')
>>> u + (v + w)
Decimal('9.51111111')
>>>
>>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')
>>> (u*v) + (u*w)
Decimal('0.0060000')
>>> u * (v+w)
Decimal('0.0060000')

Valores especiales

El sistema numérico para el módulo decimal proporciona valores especiales que incluyen: NaN, sNaN, -Infinity, Infinity, y dos ceros, +0 y -0.

Los infinitos se pueden construir directamente con Decimal('Infinity'). Además, pueden surgir al dividir entre cero cuando la señal DivisionByZero no es interceptada. Asimismo, cuando la señal Overflow no es interceptada, un infinito puede resultar del redondeo más allá de los límites del mayor número representable.

Los infinitos tienen signo (afín) y se pueden usar en operaciones aritméticas donde se tratan como números muy grandes e indeterminados. Por ejemplo, adicionar una constante a infinito resulta en otro infinito.

Algunas operaciones son indeterminadas y retornan NaN, o lanzan una excepción si la señal InvalidOperation es atrapada. Por ejemplo, 0/0 retorna NaN que significa «no es un número». Esta variedad de NaN es silenciosa y, una vez creada, fluirá a través de otros cálculos dando siempre como resultado otro NaN. Este comportamiento puede ser útil para una serie de cálculos a los que ocasionalmente les faltan entradas, permitiendo que el cálculo continúe mientras se marcan resultados específicos como no válidos.

Una variante es sNaN, que emite una señal en lugar de permanecer en silencio después de cada operación. Este es un valor de retorno útil cuando un resultado no válido requiere interrumpir un cálculo para un manejo especial.

El comportamiento de los operadores de comparación de Python puede ser un poco sorprendente cuando está involucrado un valor NaN. Una prueba de igualdad donde uno de los operandos es un NaN silencioso o señalizador siempre retorna False (incluso cuando se hace Decimal('NaN')==Decimal('NaN')), mientras que una prueba de desigualdad siempre retorna True. Un intento de comparar dos objetos Decimal usando cualquiera de los operadores <, <=, > o >= lanzará la señal InvalidOperation si alguno de los operandos es NaN, y retornará False si esta señal no es capturada. Ten en cuenta que la Especificación general de la aritmética decimal no especifica el comportamiento de las comparaciones directas. Estas reglas para las comparaciones que involucran a NaN se tomaron del estándar IEEE 854 (consulta la Tabla 3 en la sección 5.7). Utiliza en su lugar los métodos compare() y compare-signal() para garantizar el cumplimiento estricto de los estándares.

Los ceros con signo pueden resultar de cálculos que desbordan la precisión establecida. Mantienen el signo que habría resultado si el cálculo se hubiera realizado con mayor precisión. Dado que su magnitud es cero, los ceros positivos y negativos se tratan como iguales y su signo es solo informativo.

Además de los dos ceros con signo, que son distintos pero iguales, hay varias representaciones del cero con diferente precisión pero equivalentes en valor. Esto requiere de algo de tiempo para acostumbrarse. Para un ojo habituado a las representaciones normalizadas de coma flotante, no es inmediatamente obvio que el siguiente cálculo retorne un valor igual a cero:

>>> 1 / Decimal('Infinity')
Decimal('0E-1000026')

Trabajando con hilos

La función getcontext() accede a un objeto Context diferente para cada hilo. Tener contextos de hilo separados significa que los hilos pueden realizar cambios (como getcontext().prec=10) sin interferir con otros hilos.

Asimismo, la función setcontext() asigna automáticamente su objetivo al hilo actual.

Si setcontext() no ha sido invocada antes de getcontext(), entonces getcontext() creará automáticamente un nuevo contexto para usar en el hilo actual.

El nuevo contexto es copiado a partir de un contexto prototipo llamado DefaultContext. Modifica directamente el objeto DefaultContext para controlar los valores predeterminados, de modo que cada hilo utilice los mismos valores en toda la aplicación. Esto debe hacerse antes de que se inicien los hilos, para evitar que tenga lugar una condición de carrera entre los mismos al invocar a getcontext(). Por ejemplo:

# Set applicationwide defaults for all threads about to be launched
DefaultContext.prec = 12
DefaultContext.rounding = ROUND_DOWN
DefaultContext.traps = ExtendedContext.traps.copy()
DefaultContext.traps[InvalidOperation] = 1
setcontext(DefaultContext)

# Afterwards, the threads can be started
t1.start()
t2.start()
t3.start()
 . . .

Casos prácticos

A continuación hay algunos casos prácticos que sirven como funciones de utilidad y que muestran formas de trabajar con la clase Decimal:

def moneyfmt(value, places=2, curr='', sep=',', dp='.',
             pos='', neg='-', trailneg=''):
    """Convert Decimal to a money formatted string.

    places:  required number of places after the decimal point
    curr:    optional currency symbol before the sign (may be blank)
    sep:     optional grouping separator (comma, period, space, or blank)
    dp:      decimal point indicator (comma or period)
             only specify as blank when places is zero
    pos:     optional sign for positive numbers: '+', space or blank
    neg:     optional sign for negative numbers: '-', '(', space or blank
    trailneg:optional trailing minus indicator:  '-', ')', space or blank

    >>> d = Decimal('-1234567.8901')
    >>> moneyfmt(d, curr='$')
    '-$1,234,567.89'
    >>> moneyfmt(d, places=0, sep='.', dp='', neg='', trailneg='-')
    '1.234.568-'
    >>> moneyfmt(d, curr='$', neg='(', trailneg=')')
    '($1,234,567.89)'
    >>> moneyfmt(Decimal(123456789), sep=' ')
    '123 456 789.00'
    >>> moneyfmt(Decimal('-0.02'), neg='<', trailneg='>')
    '<0.02>'

    """
    q = Decimal(10) ** -places      # 2 places --> '0.01'
    sign, digits, exp = value.quantize(q).as_tuple()
    result = []
    digits = list(map(str, digits))
    build, next = result.append, digits.pop
    if sign:
        build(trailneg)
    for i in range(places):
        build(next() if digits else '0')
    if places:
        build(dp)
    if not digits:
        build('0')
    i = 0
    while digits:
        build(next())
        i += 1
        if i == 3 and digits:
            i = 0
            build(sep)
    build(curr)
    build(neg if sign else pos)
    return ''.join(reversed(result))

def pi():
    """Compute Pi to the current precision.

    >>> print(pi())
    3.141592653589793238462643383

    """
    getcontext().prec += 2  # extra digits for intermediate steps
    three = Decimal(3)      # substitute "three=3.0" for regular floats
    lasts, t, s, n, na, d, da = 0, three, 3, 1, 0, 0, 24
    while s != lasts:
        lasts = s
        n, na = n+na, na+8
        d, da = d+da, da+32
        t = (t * n) / d
        s += t
    getcontext().prec -= 2
    return +s               # unary plus applies the new precision

def exp(x):
    """Return e raised to the power of x.  Result type matches input type.

    >>> print(exp(Decimal(1)))
    2.718281828459045235360287471
    >>> print(exp(Decimal(2)))
    7.389056098930650227230427461
    >>> print(exp(2.0))
    7.38905609893
    >>> print(exp(2+0j))
    (7.38905609893+0j)

    """
    getcontext().prec += 2
    i, lasts, s, fact, num = 0, 0, 1, 1, 1
    while s != lasts:
        lasts = s
        i += 1
        fact *= i
        num *= x
        s += num / fact
    getcontext().prec -= 2
    return +s

def cos(x):
    """Return the cosine of x as measured in radians.

    The Taylor series approximation works best for a small value of x.
    For larger values, first compute x = x % (2 * pi).

    >>> print(cos(Decimal('0.5')))
    0.8775825618903727161162815826
    >>> print(cos(0.5))
    0.87758256189
    >>> print(cos(0.5+0j))
    (0.87758256189+0j)

    """
    getcontext().prec += 2
    i, lasts, s, fact, num, sign = 0, 0, 1, 1, 1, 1
    while s != lasts:
        lasts = s
        i += 2
        fact *= i * (i-1)
        num *= x * x
        sign *= -1
        s += num / fact * sign
    getcontext().prec -= 2
    return +s

def sin(x):
    """Return the sine of x as measured in radians.

    The Taylor series approximation works best for a small value of x.
    For larger values, first compute x = x % (2 * pi).

    >>> print(sin(Decimal('0.5')))
    0.4794255386042030002732879352
    >>> print(sin(0.5))
    0.479425538604
    >>> print(sin(0.5+0j))
    (0.479425538604+0j)

    """
    getcontext().prec += 2
    i, lasts, s, fact, num, sign = 1, 0, x, 1, x, 1
    while s != lasts:
        lasts = s
        i += 2
        fact *= i * (i-1)
        num *= x * x
        sign *= -1
        s += num / fact * sign
    getcontext().prec -= 2
    return +s

Preguntas frecuentes sobre Decimal

P. Es engorroso escribir decimal.Decimal('1234.5'). ¿Hay alguna forma de minimizar la escritura cuando se usa el intérprete interactivo?

R. Algunos usuarios abrevian el constructor a una sola letra:

>>> D = decimal.Decimal
>>> D('1.23') + D('3.45')
Decimal('4.68')

P. En una aplicación de coma fija con dos decimales, algunas entradas tienen muchos dígitos decimales y deben redondearse. En cambio, otras no tienen dígitos en exceso y deben ser validadas. ¿Qué métodos deben utilizarse?

R. El método quantize() redondea a un número fijo de decimales. Si se establece la trampa Inexact, también es útil para la validación:

>>> TWOPLACES = Decimal(10) ** -2       # same as Decimal('0.01')

>>> # Round to two places
>>> Decimal('3.214').quantize(TWOPLACES)
Decimal('3.21')

>>> # Validate that a number does not exceed two places
>>> Decimal('3.21').quantize(TWOPLACES, context=Context(traps=[Inexact]))
Decimal('3.21')

>>> Decimal('3.214').quantize(TWOPLACES, context=Context(traps=[Inexact]))
Traceback (most recent call last):
   ...
Inexact: None

P. Si tengo entradas validadas con dos dígitos decimales, ¿cómo mantengo eso invariante en una aplicación?

R. Algunas operaciones como la suma, la resta y la multiplicación por un número entero conservarán automáticamente el punto fijo. Otras operaciones, como la división y la multiplicación de números no enteros, cambiarán el número de lugares decimales y deberá aplicarse quantize() después de ellas:

>>> a = Decimal('102.72')           # Initial fixed-point values
>>> b = Decimal('3.17')
>>> a + b                           # Addition preserves fixed-point
Decimal('105.89')
>>> a - b
Decimal('99.55')
>>> a * 42                          # So does integer multiplication
Decimal('4314.24')
>>> (a * b).quantize(TWOPLACES)     # Must quantize non-integer multiplication
Decimal('325.62')
>>> (b / a).quantize(TWOPLACES)     # And quantize division
Decimal('0.03')

Al desarrollar aplicaciones de coma fija, es conveniente definir funciones para gestionar el paso quantize():

>>> def mul(x, y, fp=TWOPLACES):
...     return (x * y).quantize(fp)
>>> def div(x, y, fp=TWOPLACES):
...     return (x / y).quantize(fp)

>>> mul(a, b)                       # Automatically preserve fixed-point
Decimal('325.62')
>>> div(b, a)
Decimal('0.03')

P. Hay muchas formas de expresar un mismo valor. Los números 200, 200.000, 2E2 y 02E+4 tienen todos el mismo valor pero con varias precisiones. ¿Hay alguna manera de transformarlos en un único valor canónico reconocible?

R. El método normalize() mapea todos los valores equivalentes a un solo representante:

>>> values = map(Decimal, '200 200.000 2E2 .02E+4'.split())
>>> [v.normalize() for v in values]
[Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2')]

P. Algunos valores decimales siempre se imprimen usando notación exponencial. ¿Hay alguna forma de obtener una representación no exponencial?

R. Para algunos valores, la notación exponencial es la única forma de expresar el número de lugares significativos que tiene el coeficiente. Por ejemplo, expresar 5.0E+3 como 5000 mantiene el valor constante, pero no puede mostrar la significación de dos lugares que tiene el original.

Si una aplicación no necesita preocuparse por el seguimiento de significación, es fácil eliminar el exponente y los ceros finales, perdiendo significación, pero manteniendo el valor sin cambios:

>>> def remove_exponent(d):
...     return d.quantize(Decimal(1)) if d == d.to_integral() else d.normalize()

>>> remove_exponent(Decimal('5E+3'))
Decimal('5000')

P. ¿Hay alguna forma de convertir un flotante regular en un Decimal?

R. Sí, cualquier número de coma flotante binario se puede expresar exactamente mediante un Decimal, aunque una conversión exacta puede requerir más precisión de la que sugiere la intuición:

>>> Decimal(math.pi)
Decimal('3.141592653589793115997963468544185161590576171875')

P. Dentro de un cálculo complejo, cómo puedo asegurarme de que no he obtenido un resultado adulterado debido a una precisión insuficiente o anomalías de redondeo.

R. El módulo decimal facilita la comprobación de resultados. Una buena práctica es volver a ejecutar los cálculos con mayor precisión y con varios modos de redondeo. La obtención de resultados muy dispares indica una precisión insuficiente, problemas relacionados con el modo de redondeo, entradas mal acondicionadas o un algoritmo numéricamente inestable.

P. Noté que la precisión del contexto se aplica a los resultados de las operaciones pero no a las entradas. ¿Hay algo a tener en cuenta al mezclar valores con distintas precisiones?

R. Sí. El principio es que todos los valores se consideran exactos y también lo es la aritmética de esos valores. Solo se redondean los resultados. La ventaja para las entradas es que «lo que escribes es lo que obtienes». Una desventaja es que los resultados pueden parecer extraños si olvidas que las entradas no se han redondeado:

>>> getcontext().prec = 3
>>> Decimal('3.104') + Decimal('2.104')
Decimal('5.21')
>>> Decimal('3.104') + Decimal('0.000') + Decimal('2.104')
Decimal('5.20')

La solución es aumentar la precisión o forzar el redondeo de las entradas utilizando la operación unaria más:

>>> getcontext().prec = 3
>>> +Decimal('1.23456789')      # unary plus triggers rounding
Decimal('1.23')

Alternativamente, las entradas se pueden redondear en el momento que se crean usando el método Context.create_decimal():

>>> Context(prec=5, rounding=ROUND_DOWN).create_decimal('1.2345678')
Decimal('1.2345')

P. ¿La implementación de CPython es rápida para números grandes?

R. Sí. En las implementaciones de CPython y PyPy3, las versiones C/CFFI del módulo decimal integran la biblioteca de alta velocidad libmpdec [https://www.bytereef.org/mpdecimal/doc/libmpdec/index.html] para aritmética de precisión arbitraria de coma flotante decimal correctamente redondeada 1. libmpdec usa la multiplicación de Karatsuba [https://es.wikipedia.org/wiki/Algoritmo_de_Karatsuba] para números de tamaño mediano y la transformada teórico-numérica (Number Theoretic Transform [https://en.wikipedia.org/wiki/Discrete_Fourier_transform_(general)#Number-theoretic_transform]) para números muy grandes.

El contexto debe adaptarse para una aritmética de precisión arbitraria exacta. Emin y Emax siempre deben establecerse en sus valores máximos, clamp siempre debe ser 0 (el valor predeterminado). Establecer prec requiere cierto cuidado.

El enfoque más fácil para probar la aritmética bignum es usar también el valor máximo para prec 2:

>>> setcontext(Context(prec=MAX_PREC, Emax=MAX_EMAX, Emin=MIN_EMIN))
>>> x = Decimal(2) ** 256
>>> x / 128
Decimal('904625697166532776746648320380374280103671755200316906558262375061821325312')

Para resultados inexactos, MAX_PREC es demasiado grande en plataformas de 64 bits y la memoria disponible será insuficiente:

>>> Decimal(1) / 3
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
MemoryError

En sistemas con sobreasignación (por ejemplo, Linux), un enfoque más sofisticado es establecer prec a la cantidad de RAM disponible. Supongamos que tenemos 8GB de RAM y esperamos 10 operandos simultáneos usando un máximo de 500 MB cada uno:

>>> import sys
>>>
>>> # Maximum number of digits for a single operand using 500MB in 8-byte words
>>> # with 19 digits per word (4-byte and 9 digits for the 32-bit build):
>>> maxdigits = 19 * ((500 * 1024**2) // 8)
>>>
>>> # Check that this works:
>>> c = Context(prec=maxdigits, Emax=MAX_EMAX, Emin=MIN_EMIN)
>>> c.traps[Inexact] = True
>>> setcontext(c)
>>>
>>> # Fill the available precision with nines:
>>> x = Decimal(0).logical_invert() * 9
>>> sys.getsizeof(x)
524288112
>>> x + 2
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  decimal.Inexact: [<class 'decimal.Inexact'>]

En general (y especialmente en sistemas sin sobreasignación), se recomienda estimar límites aún más estrictos y establecer la trampa Inexact si se espera que todos los cálculos sean exactos.

1

Nuevo en la versión 3.3.

2

Distinto en la versión 3.9: Este enfoque ahora funciona para todos los resultados exactos excepto para las potencias no enteras. También retro-portado a 3.7 y 3.8.

fractions — Números racionales

Source code: Lib/fractions.py [https://github.com/python/cpython/tree/3.9/Lib/fractions.py]

El módulo fractions provee soporte para aritmética de números racionales.

Una instancia de Fraction puede construirse desde dos enteros, desde otro número racional, o desde una cadena de caracteres.

class fractions.Fraction(numerator=0, denominator=1)

class fractions.Fraction(other_fraction)

class fractions.Fraction(float)

class fractions.Fraction(decimal)

class fractions.Fraction(string)

La primera versión necesita que numerator y denominator sean instancias de numbers.Rational y retorna una nueva instancia de Fraction con valor numerator/denominator. Si denominator es 0, esto arrojará un error ZeroDivisionError. La segunda versión necesita que other_fraction sea una instancia de numbers.Rational y retorna una instancia Fraction con el mismo valor. Las restantes dos versiones aceptan igualmente instancias float o decimal.Decimal y retornan una instancia Fraction con exactamente el mismo valor. Nota que debido a los problemas usuales con la representación binaria en punto flotante (ver Aritmética de Punto Flotante: Problemas y Limitaciones), el argumento de Fraction(1.1) no es exactamente igual a 11/10, por lo que Fraction(1.1) no retorna Fraction(11, 10) como uno esperaría. (Mira la documentación para el método limit_denominator() abajo.) La última versión del constructor espera una cadena de caracteres o una instancia Unicode. La forma usual para esta instancia es:

[sign] numerator ['/' denominator]

donde el sign opcional puede ser “+” o “-” y numerator y denominator (si están presentes) son cadenas de caracteres de dígitos decimales. Además, cualquier cadena de caracteres que represente un valor finito y sea aceptado por el constructor de float también es aceptado por el constructor de Fraction. En cualquier caso, la cadena de caracteres de entrada también puede tener espacios en blanco iniciales y / o finales. Aquí hay unos ejemplos:

>>> from fractions import Fraction
>>> Fraction(16, -10)
Fraction(-8, 5)
>>> Fraction(123)
Fraction(123, 1)
>>> Fraction()
Fraction(0, 1)
>>> Fraction('3/7')
Fraction(3, 7)
>>> Fraction(' -3/7 ')
Fraction(-3, 7)
>>> Fraction('1.414213 \t\n')
Fraction(1414213, 1000000)
>>> Fraction('-.125')
Fraction(-1, 8)
>>> Fraction('7e-6')
Fraction(7, 1000000)
>>> Fraction(2.25)
Fraction(9, 4)
>>> Fraction(1.1)
Fraction(2476979795053773, 2251799813685248)
>>> from decimal import Decimal
>>> Fraction(Decimal('1.1'))
Fraction(11, 10)

La clase Fraction hereda de la clase base abstracta numbers.Rational, e implementa todos los métodos y operaciones de esa clase. Las instancias Fraction son hashable, y deben ser tratadas como inmutables. Adicionalmente Fraction tiene los siguientes métodos y propiedades:

Distinto en la versión 3.2: El constructor de Fraction ahora acepta instancias de float y decimal.

Distinto en la versión 3.9: La función math.gcd() ahora se usa para normalizar el numerator y denominator. math.gcd() siempre retorna un tipo int. Anteriormente, el tipo de GCD dependía de numerator y denominator.

numerator

Numerador de la fracción irreducible.

denominator

Denominador de la fracción irreducible.

as_integer_ratio()

Retorna una tupla de dos enteros, cuyo ratio es igual a la fracción y con un denominador positivo.

Nuevo en la versión 3.8.

from_float(flt)

Este método de clase construye una instancia de Fraction representando el valor exacto de flt que debe ser un float. Ten cuidado, observa que Fraction.from_float(0.3) no es el mismo valor que Fraction(3, 10).

Nota

Desde Python 3.2 en adelante, puedes construir una instancia Fraction directamente desde float.

from_decimal(dec)

Este método de clase construye una instancia de Fraction representando el valor exacto de dec, que debe ser una instancia de decimal.Decimal.

Nota

Desde Python 3.2 en adelante, puedes construir una instancia Fraction directamente desde una instancia decimal.Decimal.

limit_denominator(max_denominator=1000000)

Busca y retorna la instancia de Fraction mas cercana a self que tenga como denominador max_denominator. Este método es útil para encontrar aproximaciones racionales a un número en punto flotante determinado:

>>> from fractions import Fraction
>>> Fraction('3.1415926535897932').limit_denominator(1000)
Fraction(355, 113)

o para recuperar un numero racional que esta representado como flotante:

>>> from math import pi, cos
>>> Fraction(cos(pi/3))
Fraction(4503599627370497, 9007199254740992)
>>> Fraction(cos(pi/3)).limit_denominator()
Fraction(1, 2)
>>> Fraction(1.1).limit_denominator()
Fraction(11, 10)

__floor__()

Retorna el máximo int <= self. Este método puede accederse también a través de la función math.floor():

>>> from math import floor
>>> floor(Fraction(355, 113))
3

__ceil__()

Retorna el mínimo int >= self. Este método puede accederse también a través de la función math.ceil().

__round__()

__round__(ndigits)

La primera versión retorna el valor int mas cercano a self redondeando mitades al valor par. La segunda versión redondea self al múltiplo mas cercano de Fraction(1, 10**ndigits) (lógicamente, si ndigits es negativo), nuevamente redondeando mitades al valor par. Este método también puede accederse a través de la función round().

Ver también

Módulo numbers

Las clases base abstractas que representan la jerarquía de números.

random —Generar números pseudoaleatorios

Código fuente: Lib/random.py [https://github.com/python/cpython/tree/3.9/Lib/random.py]

Este módulo implementa generadores de números pseudoaleatorios para varias distribuciones.

Para los enteros, existe una selección uniforme dentro de un rango. Para las secuencias, existe una selección uniforme de un elemento aleatorio, una función para generar una permutación aleatoria de una lista in-situ y una función para el muestreo aleatorio sin reemplazo.

Para números reales, existen funciones para calcular distribuciones uniformes, normales (Gaussianas), log-normales, exponenciales negativas, gamma y beta. Para generar distribuciones angulares está disponible la distribución de von Mises.

Casi todas las funciones del módulo dependen de la función básica random(), la cuál genera uniformemente un número flotante aleatorio en el rango semiabierto [0.0, 1.0). Python utiliza Mersenne Twister como generador principal. Éste produce números de coma flotante de 53 bits de precisión y tiene un periodo de 2**19937-1. La implementación subyacente en C es rápida y segura para subprocesos. Mersenne Twister es uno de los generadores de números aleatorios más testados que existen. Sin embargo, al ser completamente determinístico, no es adecuado para todos los propósitos y es completamente inadecuado para fines criptográficos.

Las funciones proporcionadas por este módulo en realidad son métodos enlazados a instancias ocultas a la clase random.Random. Puedes instanciar tus propias instancias de Random para obtener generadores que no compartan estado.

La clase Random puede ser también subclaseada si quieres usar un generador básico diferente para tu propio diseño: en este caso, invalida los métodos random(), seed(), getstate() y setstate(). Opcionalmente, se puede substituir un método getrandbits() por un nuevo generador — esto permite a randrange() producir selecciones sobre un rango arbitrariamente amplio.

El módulo random también proporciona la clase SystemRandom, la cuál usa la función del sistema os.urandom() para generar números aleatorios a partir de fuentes proporcionadas por el sistema operativo.

Advertencia

Los generadores pseudoaleatorios de este módulo no deben ser utilizados con fines de seguridad. Para usos de seguridad o criptográficos, consulta el módulo secrets.

Ver también

M. Matsumoto and T. Nishimura, «Mersenne Twister: A 623-dimensionally equidistributed uniform pseudorandom number generator», ACM Transactions on Modeling and Computer Simulation Vol. 8, No. 1, January pp.3–30 1998.

Complementary-Multiply-with-Carry recipe [https://code.activestate.com/recipes/576707/] for a compatible alternative random number generator with a long period and comparatively simple update operations.

Funciones de contabilidad

random.seed(a=None, version=2)

Inicializa el generador de números aleatorios.

Si a es omitida o None, se utilizará la hora actual del sistema. Si las fuentes de aleatoriedad vienen del sistema operativo, éstas se usarán en vez de la hora del sistema (ver la función os.urandom() para detalles sobre su disponibilidad).

Si a es un entero, se usará directamente.

Con la versión 2 (la versión por defecto), un objeto str, bytes, o bytearray se convierte en int y se usarán todos sus bits.

Con la versión 1 (proporcionada para reproducir secuencias aleatorias desde versiones anteriores de Python), el algoritmo para str y bytes genera un rango de semillas más estrecho.

Distinto en la versión 3.2: El esquema que usa todos los bits en una semilla de tipo cadena, se ha movido a la versión 2.

Obsoleto desde la versión 3.9: En el futuro, la semilla debe ser de uno de los siguientes tipos: NoneType, int, float, str, bytes, o bytearray.

random.getstate()

Retorna un objeto capturando el estado interno del generador. Este objeto puede pasarse a setstate() para restaurar su estado.

random.setstate(state)

El state debería haberse obtenido de una llamada previa a getstate(), y setstate() reestablece el estado interno del generador al que tenia cuando se llamó a la función getstate().

Funciones para los bytes

random.randbytes(n)

Genera n bytes aleatorios.

Este método no debe utilizarse para generar tokens de seguridad. Utilice secrets.token_bytes() en su lugar.

Nuevo en la versión 3.9.

Funciones para enteros

random.randrange(stop)

random.randrange(start, stop[, step])

Retorna un elemento de range(start, stop, step) seleccionado aleatoriamente. Esto es equivalente a choice(range(start, stop, step)), pero en realidad no crea un objeto rango.

El patrón de argumento posicional coincide con el de range(). Los argumentos no deben usarse porque la función puede usarlos de forma inesperada.

Distinto en la versión 3.2: randrange() es más sofisticado produciendo valores igualmente distribuidos. Anteriormente utilizaba un estilo como int(random()*n) el cual puede producir distribuciones ligeramente desiguales.

random.randint(a, b)

Retorna un entero aleatorio N tal que a <= N <= b. Alias de randrange(a, b+1).

random.getrandbits(k)

Retorna un entero de Python no negativo con k bits aleatorios. Este método se provee con el generador MersenneTwister y algunos otros generadores pueden también proveerlo como una parte opcional de la API. Cuando está disponible, getrandbits() permite a randrange() manejar rangos arbitrariamente grandes.

Distinto en la versión 3.9: Este método ahora acepta cero para k.

Funciones para secuencias

random.choice(seq)

Retorna un elemento aleatorio de una secuencia seq no vacía. Si seq está vacía, lanza IndexError.

random.choices(population, weights=None, *, cum_weights=None, k=1)

Retorna una lista de elementos de tamaño k elegidos de la population con reemplazo. Si la population está vacía, lanza IndexError.

Si se especifica una secuencia weights, las selecciones se realizan de acuerdo con las ponderaciones relativas. Alternativamente, si se da una secuencia cum_weights, las selecciones se harán según los pesos cumulativos (posiblemente se calculen usando itertools.accumulate()). Por ejemplo, los pesos relativos [10, 5, 30, 5] son equivalentes a los pesos cumulativos [10, 15, 45, 50]. Internamente, los pesos relativos se convierten en pesos cumulativos antes de hacer selecciones, por lo cual suplir los pesos cumulativos ahorra trabajo.

Si ni weights ni cum_weights están especificadas, las selecciones se realizan con la misma probabilidad. Si se proporciona una secuencia de ponderaciones, debe tener la misma longitud que la secuencia population. Es un TypeError especificar ambas weights y cum_weights.

Los weights o los cum_weights pueden utilizar cualquier tipo numérico que interactúe con los valores float retornados por random() (que incluye enteros, flotantes y fracciones pero excluye decimales). El comportamiento es indefinido si algún peso es negativo. Se produce un ValueError si todos los pesos son cero.

Dada una semilla, la función choices() normalmente produce una secuencia diferente a las llamadas repetidas a choice() con la misma ponderación. El algoritmo usado por choices() emplea aritmética de coma flotante para la consistencia interna y velocidad. El algoritmo usado por choice() emplea por defecto aritmética de enteros con selecciones repetidas para evitar pequeños sesgos de errores de redondeo.

Nuevo en la versión 3.6.

Distinto en la versión 3.9: Genera un ValueError si todos los pesos son cero.

random.shuffle(x[, random])

Mezcla la secuencia x in-situ.

El argumento opcional random es una función de 0 argumentos que retorna un flotante random en [0.0, 1.0); por defecto esta es la función random().

Para mezclar una secuencia inmutable y retornar una nueva lista mezclada, utilice muestra(x, k=len(x)) en su lugar.

Tenga en cuenta que incluso para pequeños len(x), el número total de permutaciones de x puede crecer rápidamente más que el periodo de muchos generadores de números aleatorios. Esto implica que la mayoría de las permutaciones de una secuencia larga nunca se pueden generar. Por ejemplo, una secuencia de longitud 2080 es la más grande que cabe dentro del período del generador de números aleatorios de Mersenne Twister.

Deprecated since version 3.9, will be removed in version 3.11: El parámetro opcional random.

random.sample(population, k, *, counts=None)

Retorna una lista de longitud k de elementos únicos elegidos de la secuencia de población o conjunto. Se utiliza para el muestreo aleatorio sin reemplazo.

Retorna una nueva lista que contiene elementos de la población sin modificar la población original. La lista resultante está en orden de selección de forma que todos los subsectores también son muestras aleatorias válidas. Esto permite que los ganadores de la rifa (la muestra) se dividan en primer premio y ganadores del segundo lugar (los subsectores).

Los miembros de la población no tienen porqué ser hashable o únicos. Si la población incluye repeticiones, entonces cada ocurrencia es una posible selección en la muestra.

Los elementos repetidos pueden especificarse de uno en uno o con el parámetro opcional counts, que es una palabra clave. Por ejemplo, sample(['red', 'blue'], counts=[4, 2], k=5) es equivalente a sample(['red', 'red', 'red', 'red', 'blue', 'blue'], k=5).

Para escoger una muestra de un rango de enteros, use un objeto range() como argumento. Esto es especialmente rápido y eficiente en espacio para el muestreo de poblaciones grandes: sample(range(10000000), k=60).

Si el tamaño de la muestra es mayor que el tamaño de la población, se lanzará un ValueError.

Distinto en la versión 3.9: Se añadió el parámetro counts.

Obsoleto desde la versión 3.9: En el futuro, la población debe ser una secuencia. Las instancias de set ya no se admiten. El conjunto debe convertirse primero en una list o tuple, preferiblemente en un orden determinista para que la muestra sea reproducible.

Distribuciones para los nombres reales

Las siguientes funciones generan distribuciones específicas para números reales. Los parámetros de la función reciben el nombre de las variables correspondientes en la ecuación de distribución, tal y como se utilizan en la práctica matemática común.; la mayoría de estas ecuaciones se pueden encontrar en cualquier texto estadístico.

random.random()

Retorna el siguiente número en coma flotante aleatorio dentro del rango [0.0, 1.0).

random.uniform(a, b)

Retorna un número en coma flotante aleatorio N tal que a <= N <= b para a <= b y b <= N <= a para b < a.

El valor final b puede o no estar incluido en el rango, dependiendo del redondeo de coma flotante en la ecuación a + (b-a) * random().

random.triangular(low, high, mode)

Retorna un número de coma flotante N tal que low <= N <= high y con el mode especificado entre esos límites. Los límites low (inferior) y high (superior) son por defecto cero y uno. El argumento mode tiene como valor por defecto el punto medio entre los límites, dando lugar a una distribución simétrica.

random.betavariate(alpha, beta)

Distribución beta. Las condiciones de los parámetros son alpha > 0 y beta > 0. Retorna valores dentro del rango entre 0 y 1.

random.expovariate(lambd)

Distribución exponencial. lambd es 1.0 dividido entre la media deseada. Debe ser distinto a cero (El parámetro debería llamarse lambda pero esa es una palabra reservada en Python). Retorna valores dentro del rango de 0 a infinito positivo si lambd es positivo, y de infinito negativo a 0 si lambd es negativo.

random.gammavariate(alpha, beta)

Distribución gamma. (¡No la función gamma!) Las condiciones en los parámetros son alpha > 0 y beta > 0.

La función de distribución de la probabilidad es:

          x ** (alpha - 1) * math.exp(-x / beta)
pdf(x) =  --------------------------------------
            math.gamma(alpha) * beta ** alpha

random.gauss(mu, sigma)

Distribución gaussiana. mu es la media y sigma es la desviación estándar. Es un poco más rápida que la función normalvariate() definida debajo.

Nota sobre el multithreading: Cuando dos hilos llaman a esta función simultáneamente, es posible que reciban el mismo valor de retorno. Esto se puede evitar de tres maneras. 1) Hacer que cada hilo utilice una instancia diferente del generador de números aleatorios. 2) Poner bloqueos alrededor de todas las llamadas. 3) Utilizar la función normalvariate(), más lenta pero segura para los hilos, en su lugar.

random.lognormvariate(mu, sigma)

Logaritmo de la distribución normal. Si se usa un logaritmo natural de esta distribución, se obtendrá una distribución normal con media mu y desviación estándar sigma. mu puede tener cualquier valor, y sigma debe ser mayor que cero.

random.normalvariate(mu, sigma)

Distribución normal. mu es la media y sigma es la desviación estándar.

random.vonmisesvariate(mu, kappa)

mu es el ángulo medio, expresado en radiantes entre 0 y 2*pi, y kappa es el parámetro de concentración, que debe ser mayor o igual a cero. Si kappa es igual a cero, esta distribución se reduce a un ángulo aleatorio uniforme sobre el rango de 0 a 2*pi.

random.paretovariate(alpha)

Distribución de Pareto. alpha es el parámetro de forma.

random.weibullvariate(alpha, beta)

Distribución de Weibull. alpha es el parámetro de escala y beta es el parámetro de forma.

Generador alternativo

class random.Random([seed])

Esta clase implementa el generador de números pseudoaleatorios predeterminado que usa el módulo random .

Obsoleto desde la versión 3.9: En el futuro, la semilla debe ser de uno de los siguientes tipos: NoneType, int, float, str, bytes, o bytearray.

class random.SystemRandom([seed])

Clase que utiliza la función os.urandom() para generar números aleatorios a partir de fuentes proporcionadas por el sistema operativo. No está disponible en todos los sistemas. No se basa en el estado del software y las secuencias no son reproducibles. En consecuencia, el método seed() no tiene efecto y es ignorado. Los métodos getstate() y setstate() lanzan NotImplementedError si se les llama.

Notas sobre la Reproducibilidad

A veces es útil poder reproducir las secuencias dadas por un generador de números pseudoaleatorios. Al reutilizar un valor de semilla, la misma secuencia debería ser reproducible de una ejecución a otra siempre que no se estén ejecutando múltiples hilos.

Muchos de los algoritmos y de las funciones de generación de semillas del módulo aleatorio pueden cambiar entre versiones de Python, pero se garantiza que dos aspectos no cambien:

Si se añade un nuevo método de generación de semilla, se ofrecerá un generador de semilla retrocompatible.

El método generador random() continuará produciendo la misma secuencia cuando se le da la misma semilla al generador de semilla compatible.

Ejemplos

Ejemplos básicos:

>>> random()                             # Random float:  0.0 <= x < 1.0
0.37444887175646646

>>> uniform(2.5, 10.0)                   # Random float:  2.5 <= x <= 10.0
3.1800146073117523

>>> expovariate(1 / 5)                   # Interval between arrivals averaging 5 seconds
5.148957571865031

>>> randrange(10)                        # Integer from 0 to 9 inclusive
7

>>> randrange(0, 101, 2)                 # Even integer from 0 to 100 inclusive
26

>>> choice(['win', 'lose', 'draw'])      # Single random element from a sequence
'draw'

>>> deck = 'ace two three four'.split()
>>> shuffle(deck)                        # Shuffle a list
>>> deck
['four', 'two', 'ace', 'three']

>>> sample([10, 20, 30, 40, 50], k=4)    # Four samples without replacement
[40, 10, 50, 30]

Simulaciones:

>>> # Six roulette wheel spins (weighted sampling with replacement)
>>> choices(['red', 'black', 'green'], [18, 18, 2], k=6)
['red', 'green', 'black', 'black', 'red', 'black']

>>> # Deal 20 cards without replacement from a deck
>>> # of 52 playing cards, and determine the proportion of cards
>>> # with a ten-value:  ten, jack, queen, or king.
>>> dealt = sample(['tens', 'low cards'], counts=[16, 36], k=20)
>>> dealt.count('tens') / 20
0.15

>>> # Estimate the probability of getting 5 or more heads from 7 spins
>>> # of a biased coin that settles on heads 60% of the time.
>>> def trial():
...     return choices('HT', cum_weights=(0.60, 1.00), k=7).count('H') >= 5
...
>>> sum(trial() for i in range(10_000)) / 10_000
0.4169

>>> # Probability of the median of 5 samples being in middle two quartiles
>>> def trial():
...     return 2_500 <= sorted(choices(range(10_000), k=5))[2] < 7_500
...
>>> sum(trial() for i in range(10_000)) / 10_000
0.7958

Ejemplo de statistical bootstrapping [https://en.wikipedia.org/wiki/Bootstrapping_(statistics)] utilizando el remuestreo con reemplazo para estimar un intervalo de confianza para la media de una muestra:

# http://statistics.about.com/od/Applications/a/Example-Of-Bootstrapping.htm
from statistics import fmean as mean
from random import choices

data = [41, 50, 29, 37, 81, 30, 73, 63, 20, 35, 68, 22, 60, 31, 95]
means = sorted(mean(choices(data, k=len(data))) for i in range(100))
print(f'The sample mean of {mean(data):.1f} has a 90% confidence '
      f'interval from {means[5]:.1f} to {means[94]:.1f}')

Ejemplo de un test de permutación en remuestreo (en) [https://en.wikipedia.org/wiki/Resampling_(statistics)#Permutation_tests] para determinar la significación estadística o p-valor [https://es.wikipedia.org/wiki/Valor_p] de una diferencia observada entre los efectos de un fármaco y un placebo:

# Example from "Statistics is Easy" by Dennis Shasha and Manda Wilson
from statistics import fmean as mean
from random import shuffle

drug = [54, 73, 53, 70, 73, 68, 52, 65, 65]
placebo = [54, 51, 58, 44, 55, 52, 42, 47, 58, 46]
observed_diff = mean(drug) - mean(placebo)

n = 10_000
count = 0
combined = drug + placebo
for i in range(n):
    shuffle(combined)
    new_diff = mean(combined[:len(drug)]) - mean(combined[len(drug):])
    count += (new_diff >= observed_diff)

print(f'{n} label reshufflings produced only {count} instances with a difference')
print(f'at least as extreme as the observed difference of {observed_diff:.1f}.')
print(f'The one-sided p-value of {count / n:.4f} leads us to reject the null')
print(f'hypothesis that there is no difference between the drug and the placebo.')

Simulación de tiempos de llegada y entrega de servicios para una cola de múltiples servidores:

from heapq import heapify, heapreplace
from random import expovariate, gauss
from statistics import mean, median, stdev

average_arrival_interval = 5.6
average_service_time = 15.0
stdev_service_time = 3.5
num_servers = 3

waits = []
arrival_time = 0.0
servers = [0.0] * num_servers  # time when each server becomes available
heapify(servers)
for i in range(1_000_000):
    arrival_time += expovariate(1.0 / average_arrival_interval)
    next_server_available = servers[0]
    wait = max(0.0, next_server_available - arrival_time)
    waits.append(wait)
    service_duration = max(0.0, gauss(average_service_time, stdev_service_time))
    service_completed = arrival_time + wait + service_duration
    heapreplace(servers, service_completed)

print(f'Mean wait: {mean(waits):.1f}.  Stdev wait: {stdev(waits):.1f}.')
print(f'Median wait: {median(waits):.1f}.  Max wait: {max(waits):.1f}.')

Ver también

*Statistics for Hackers* [https://www.youtube.com/watch?v=Iq9DzN6mvYA] un video tutorial de Jake Vanderplas [https://us.pycon.org/2016/speaker/profile/295/] sobre análisis estadístico usando sólo algunos conceptos fundamentales incluyendo simulación, muestreo, baraja y validación cruzada.

*Economics Simulation* <http://nbviewer.jupyter.org/url/norvig.com/ipython/Economics.ipynb>`_una simulación de un mercado por `Peter Norvig [http://norvig.com/bio.html] que muestra un uso efectivo de las herramientas y distribuciones proporcionadas por este modulo (gauss, uniform, sample, betavariate, choice, triangular, y randrange).

*A Concrete Introduction to Probability (using Python)* <http://nbviewer.jupyter.org/url/norvig.com/ipython/Probability.ipynb>`_un tutorial de `Peter Norvig [http://norvig.com/bio.html] cubriendo teoría básica de probabilidad, cómo escribir simulaciones y cómo realizar un análisis de datos usando Python.

Recetas

La función random() por defecto devuelve múltiplos de 2⁻⁵³ en el rango 0.0 ≤ x < 1.0. Todos estos números están espaciados uniformemente y son representables exactamente como flotantes de Python. Sin embargo, muchos otros flotadores representables en ese intervalo no son selecciones posibles. Por ejemplo, 0.05954861408025609 no es un múltiplo entero de 2⁻⁵³.

La siguiente receta adopta un enfoque diferente. Todos los flotantes en el intervalo son selecciones posibles. La mantisa proviene de una distribución uniforme de enteros en el rango 2⁵² ≤ mantisa < 2⁵³. El exponente proviene de una distribución geométrica en la que los exponentes menores de -53 ocurren con la mitad de frecuencia que el siguiente exponente mayor.

from random import Random
from math import ldexp

class FullRandom(Random):

    def random(self):
        mantissa = 0x10_0000_0000_0000 | self.getrandbits(52)
        exponent = -53
        x = 0
        while not x:
            x = self.getrandbits(32)
            exponent += x.bit_length() - 32
        return ldexp(mantissa, exponent)

Todas las distribuciones de valor real de la clase utilizarán el nuevo método:

>>> fr = FullRandom()
>>> fr.random()
0.05954861408025609
>>> fr.expovariate(0.25)
8.87925541791544

La receta es conceptualmente equivalente a un algoritmo que elige entre todos los múltiplos de 2⁻¹⁰⁷⁴ en el rango 0,0 ≤ x < 1,0. Todos esos números son uniformes, pero la mayoría tienen que ser redondeados al flotante de Python representable más cercano. (El valor 2⁻¹⁰⁷⁴ es el menor flotante positivo no normalizado y es igual a math.ulp(0.0).)

Ver también

Generating Pseudo-random Floating-Point Values [https://allendowney.com/research/rand/downey07randfloat.pdf] un artículo de Allen B. Downey en el que se describen formas de generar flotantes más refinados que los generados normalmente por random().

statistics — Funciones de estadística matemática

Nuevo en la versión 3.4.

Código fuente: Lib/statistics.py [https://github.com/python/cpython/tree/3.9/Lib/statistics.py]

Este módulo proporciona funciones para calcular estadísticas matemáticas de datos numéricos (de tipo Real).

Este módulo no pretende ser competidor o sustituto de bibliotecas de terceros como NumPy [https://numpy.org] o SciPy [https://www.scipy.org/], ni de paquetes completos de software propietario para profesionales como Minitab, SAS o Matlab. Este módulo se ubica a nivel de calculadoras científicas gráficas.

A menos que se indique explícitamente lo contrario, las funciones de este módulo manejan objetos int, float, Decimal y Fraction. No se garantiza un correcto funcionamiento con otros tipos (numéricos o no). El comportamiento de estas funciones con colecciones mixtas que contengan objetos de diferente tipo no está definido y depende de la implementación. Si tus datos de entrada consisten en una mezcla de varios tipos, puedes usar map() para asegurarte de que el resultado sea consistente, por ejemplo: map(float, input_data).

Promedios y medidas de tendencia central

Estas funciones calculan el promedio o el valor típico de una población o muestra.

mean()

Media aritmética («promedio») de los datos.

fmean()

Media aritmética usando coma flotante, más rápida.

geometric_mean()

Media geométrica de los datos.

harmonic_mean()

Media armónica de los datos.

median()

Mediana (valor central) de los datos.

median_low()

Mediana baja de los datos.

median_high()

Mediana alta de los datos.

median_grouped()

Mediana, o percentil 50, de los datos agrupados.

mode()

Moda única (valor más común) de datos discretos o nominales.

multimode()

Lista de modas (valores más comunes) de datos discretos o nominales.

quantiles()

Divide los datos en intervalos equiprobables.

Medidas de dispersión

Estas funciones calculan una medida de cuánto tiende a desviarse la población o muestra de los valores típicos o promedios.

pstdev()

Desviación típica poblacional de los datos.

pvariance()

Varianza poblacional de los datos.

stdev()

Desviación típica muestral de los datos.

variance()

Varianza muestral de los datos.

Detalles de las funciones

Nota: Las funciones no requieren que se ordenen los datos que se les proporcionan. Sin embargo, para facilitar la lectura, la mayoría de los ejemplos muestran secuencias ordenadas.

statistics.mean(data)

Retorna la media aritmética muestral de data, que puede ser una secuencia o un iterable.

La media aritmética es la suma de los valores dividida entre el número de observaciones. Es comúnmente denominada «promedio», aunque hay muchas formas de definir el promedio matemáticamente. Es una medida de tendencia central de los datos.

Se lanza una excepción StatisticsError si data está vacío.

Algunos ejemplos de uso:

>>> mean([1, 2, 3, 4, 4])
2.8
>>> mean([-1.0, 2.5, 3.25, 5.75])
2.625

>>> from fractions import Fraction as F
>>> mean([F(3, 7), F(1, 21), F(5, 3), F(1, 3)])
Fraction(13, 21)

>>> from decimal import Decimal as D
>>> mean([D("0.5"), D("0.75"), D("0.625"), D("0.375")])
Decimal('0.5625')

Nota

The mean is strongly affected by outliers [https://en.wikipedia.org/wiki/Outlier] and is not necessarily a typical example of the data points. For a more robust, although less efficient, measure of central tendency [https://en.wikipedia.org/wiki/Central_tendency], see median().

La media muestral proporciona una estimación no sesgada de la media real de la población. Por lo tanto, al calcular el promedio de todas las muestras posibles, mean(sample) converge con el promedio real de toda la población. Si data representa a una población completa, en lugar de a una muestra, entonces mean(data) equivale a calcular la media poblacional verdadera μ.

statistics.fmean(data)

Convierte los valores de data a flotantes y calcula la media aritmética.

Esta función se ejecuta más rápido que mean() y siempre retorna un float. data puede ser una secuencia o un iterable. Si el conjunto de datos de entrada está vacío, se lanza una excepción StatisticsError.

>>> fmean([3.5, 4.0, 5.25])
4.25

Nuevo en la versión 3.8.

statistics.geometric_mean(data)

Convierte los valores de data a flotantes y calcula la media geométrica.

La media geométrica indica la tendencia central o valor típico de data utilizando el producto de los valores (en oposición a la media aritmética, que utiliza su suma).

Lanza una excepción StatisticsError si el conjunto de datos de entrada está vacío, o si contiene un cero o un valor negativo. data puede ser una secuencia o un iterable.

No se toman medidas especiales para garantizar que el resultado sea completamente preciso. (Sin embargo, esto puede cambiar en una versión futura.)

>>> round(geometric_mean([54, 24, 36]), 1)
36.0

Nuevo en la versión 3.8.

statistics.harmonic_mean(data)

Retorna la media armónica de data, que debe ser una secuencia o un iterable de números que pertenezcan al conjunto de los números reales.

La media armónica es el inverso o recíproco de la media aritmética (mean()) de los inversos multiplicativos de los datos. Por ejemplo, la media armónica de tres valores a, b y c es 3/(1/a + 1/b + 1/c). El resultado es cero si uno de los valores es cero.

La media armónica es un tipo de promedio, una medida de la tendencia central de los datos. Generalmente es adecuada para calcular promedios de tasas o fracciones, por ejemplo, velocidades.

Supongamos que un automóvil viaja 10 km a 40 km/h, luego otros 10 km a 60 km/h. ¿Cuál es su velocidad media?

>>> harmonic_mean([40, 60])
48.0

Supongamos que un inversor compra la misma cantidad de acciones de tres empresas diferentes, con unos PER (ratio precio-beneficio) de 2.5, 3 y 10. ¿Cuál es el PER promedio para la cartera del inversor?

>>> harmonic_mean([2.5, 3, 10])  # For an equal investment portfolio.
3.6

Una excepción StatisticsError es lanzada si data está vacío o algún elemento es menor que cero.

El algoritmo actual tiene una salida anticipada cuando encuentra un cero en la entrada. Esto significa que no se comprueba la validez de las entradas posteriores al cero. (Este comportamiento puede cambiar en el futuro.)

Nuevo en la versión 3.6.

statistics.median(data)

Retorna la mediana (valor central) de los datos numéricos, utilizando el método clásico de «media de los dos del medio». Si data está vacío, se lanza una excepción StatisticsError. data puede ser una secuencia o un iterable.

La mediana es una medida de tendencia central robusta y es menos sensible a la presencia de valores atípicos que la media. Cuando el número de casos es impar, se retorna el valor central:

>>> median([1, 3, 5])
3

Cuando el número de observaciones es par, la mediana se interpola calculando el promedio de los dos valores centrales:

>>> median([1, 3, 5, 7])
4.0

Este enfoque es adecuado para datos discretos, siempre que se acepte que la mediana no es necesariamente parte de las observaciones.

Si los datos son ordinales (se pueden ordenar) pero no numéricos (no se pueden sumar), considera usar median_low() o median_high() en su lugar.

statistics.median_low(data)

Retorna la mediana baja de los datos numéricos. Se lanza una excepción StatisticsError si data está vacío. data puede ser una secuencia o un iterable.

La mediana baja es siempre un valor presente en el conjunto de datos. Cuando el número de casos es impar, se retorna el valor central. Cuando el número de casos es par, se retorna el menor de los dos valores centrales.

>>> median_low([1, 3, 5])
3
>>> median_low([1, 3, 5, 7])
3

Utiliza la mediana baja cuando tus datos sean discretos y prefieras que la mediana sea un valor representado en tus observaciones, en lugar de ser el resultado de una interpolación.

statistics.median_high(data)

Retorna la mediana alta de los datos. Lanza una excepción StatisticsError si data está vacío. data puede ser una secuencia o un iterable.

La mediana alta es siempre un valor presente en el conjunto de datos. Cuando el número de casos es impar, se retorna el valor central. Cuando el número de casos es par, se retorna el mayor de los dos valores centrales.

>>> median_high([1, 3, 5])
3
>>> median_high([1, 3, 5, 7])
5

Utiliza la mediana alta cuando tus datos sean discretos y prefieras que la mediana sea un valor representado en tus observaciones, en lugar de ser el resultado de una interpolación.

statistics.median_grouped(data, interval=1)

Retorna la mediana de los datos continuos agrupados, calculada como el percentil 50, usando interpolación. Se lanza una excepción StatisticsError si data está vacío. data puede ser una secuencia o un iterable.

>>> median_grouped([52, 52, 53, 54])
52.5

En el siguiente ejemplo, los valores se redondean para que cada valor represente la mitad de un grupo. Por ejemplo, 1 es la mitad del grupo 0.5–1.5, 2 es la mitad del grupo 1.5–2.5, 3 es la mitad de 2.5–3.5, etc. En los datos proporcionados a continuación, el valor medio está en algún lugar del grupo que va de 3,5 a 4,5 y se estima mediante interpolación:

>>> median_grouped([1, 2, 2, 3, 4, 4, 4, 4, 4, 5])
3.7

El argumento opcional interval representa el intervalo de clase y el valor predeterminado es 1. Cambiar el intervalo de clase cambiará la interpolación, como es natural:

>>> median_grouped([1, 3, 3, 5, 7], interval=1)
3.25
>>> median_grouped([1, 3, 3, 5, 7], interval=2)
3.5

Esta función no comprueba si los valores están separados por al menos un interval.

CPython implementation detail: Bajo algunas circunstancias, median_grouped() puede convertir algunos de los valores proporcionados en flotantes. Es probable que este comportamiento cambie en el futuro.

Ver también

«Statistics for the Behavioral Sciences», Frederick J Gravetter y Larry B Wallnau (8ª edición).

La función SSMEDIAN [https://help.gnome.org/users/gnumeric/stable/gnumeric.html#gnumeric-function-SSMEDIAN] del programa de hojas de cálculo Gnumeric de Gnome, incluyendo esta discusión [https://mail.gnome.org/archives/gnumeric-list/2011-April/msg00018.html].

statistics.mode(data)

Retorna el valor más común del conjunto de datos discretos o nominales data.La moda (cuando existe) es el valor más representativo y sirve como medida de tendencia central.

Si hay varias modas con la misma frecuencia, retorna la primera encontrada en data. Si deseas la menor o la mayor de ellas, usa min(multimode(data)) o max(multimode(data)). Se lanza una excepción StatisticsError si la entrada data está vacía.

mode asume que los datos de entrada son discretos y retorna un solo valor. Esta es la definición habitual de la moda que se enseña en las escuelas:

>>> mode([1, 1, 2, 3, 3, 3, 3, 4])
3

La moda tiene la particularidad de ser la única estadística de este módulo que se puede calcular sobre datos nominales (no numéricos):

>>> mode(["red", "blue", "blue", "red", "green", "red", "red"])
'red'

Distinto en la versión 3.8: Ahora maneja conjuntos de datos multimodales, retornando la primera moda encontrada. Anteriormente, se lanzaba una excepción StatisticsError cuando se daba esta situación.

statistics.multimode(data)

Retorna una lista de los valores más frecuentes en el orden en que aparecen en data. Retornará varios resultados en el caso de que existan varias modas, o una lista vacía si data está vacío:

>>> multimode('aabbbbccddddeeffffgg')
['b', 'd', 'f']
>>> multimode('')
[]

Nuevo en la versión 3.8.

statistics.pstdev(data, mu=None)

Retorna la desviación típica poblacional (la raíz cuadrada de la varianza poblacional). Consultar pvariance() para los argumentos y otros detalles.

>>> pstdev([1.5, 2.5, 2.5, 2.75, 3.25, 4.75])
0.986893273527251

statistics.pvariance(data, mu=None)

Retorna la varianza poblacional de data, que debe ser una secuencia no vacía o un iterable de números reales. La varianza, o momento de segundo orden respecto a la media, es una medida de la variabilidad (o dispersión) de los datos. Una alta varianza indica una amplia dispersión de valores; una varianza baja indica que los valores están agrupados alrededor de la media.

El segundo argumento opcional mu, que normalmente será la media de data, también se puede utilizar para calcular el momento de segundo orden alrededor de un punto que no es la media. Si no se proporciona o es None (el valor predeterminado), la media aritmética se calcula automáticamente.

Utiliza esta función para calcular la varianza de toda la población. Para estimar la varianza de una muestra, la función variance() suele ser una opción mejor.

Lanza una excepción StatisticsError si data está vacío.

Ejemplos:

>>> data = [0.0, 0.25, 0.25, 1.25, 1.5, 1.75, 2.75, 3.25]
>>> pvariance(data)
1.25

Si ya has calculado la media de tus datos, puedes pasarla como segundo argumento opcional mu para evitar que se tenga que volver a calcular:

>>> mu = mean(data)
>>> pvariance(data, mu)
1.25

Se admiten decimales (Decimal) y fracciones (Fraction):

>>> from decimal import Decimal as D
>>> pvariance([D("27.5"), D("30.25"), D("30.25"), D("34.5"), D("41.75")])
Decimal('24.815')

>>> from fractions import Fraction as F
>>> pvariance([F(1, 4), F(5, 4), F(1, 2)])
Fraction(13, 72)

Nota

Esta función retorna la varianza poblacional σ² cuando se aplica a toda la población. Si se aplica solo a una muestra, el resultado es la varianza muestral s², conocida también como varianza con N grados de libertad.

Si se conoce de antemano la verdadera media poblacional μ, se puede usar esta función para calcular la varianza muestral, pasando la media poblacional conocida como segundo argumento. Suponiendo que las observaciones provienen de una selección aleatoria uniforme de la población, el resultado será una estimación no sesgada de la varianza poblacional.

statistics.stdev(data, xbar=None)

Retorna la desviación típica muestral (la raíz cuadrada de la varianza muestral). Consultar variance() para los argumentos y otros detalles.

>>> stdev([1.5, 2.5, 2.5, 2.75, 3.25, 4.75])
1.0810874155219827

statistics.variance(data, xbar=None)

Retorna la varianza muestral de data, que debe ser un iterable de al menos dos números reales. La varianza, o momento de segundo orden respecto a la media, es una medida de la variabilidad (difusión o dispersión) de los datos. Una alta varianza indica que los datos están dispersos; una baja varianza indica que los datos están agrupados estrechamente alrededor de la media.

Si se proporciona el segundo argumento opcional xbar, este debe ser la media aritmética de data. Si no se proporciona o es None (el valor predeterminado), la media aritmética se calcula automáticamente.

Utiliza esta función cuando tus datos sean una muestra de una población. Para calcular la varianza de toda la población, consulta pvariance().

Lanza una excepción StatisticsError si data tiene menos de dos valores.

Ejemplos:

>>> data = [2.75, 1.75, 1.25, 0.25, 0.5, 1.25, 3.5]
>>> variance(data)
1.3720238095238095

Si previamente se ha calculado la media de los datos, puede pasarse como segundo argumento opcional xbar para evitar que se tenga que volver a calcular:

>>> m = mean(data)
>>> variance(data, m)
1.3720238095238095

Esta función no comprueba si el valor pasado al argumento xbar corresponde al promedio. El uso de valores arbitrarios para xbar produce resultados imposibles o incorrectos.

La función maneja decimales (Decimal) y fracciones (Fraction):

>>> from decimal import Decimal as D
>>> variance([D("27.5"), D("30.25"), D("30.25"), D("34.5"), D("41.75")])
Decimal('31.01875')

>>> from fractions import Fraction as F
>>> variance([F(1, 6), F(1, 2), F(5, 3)])
Fraction(67, 108)

Nota

Esta es la varianza muestral s² con la corrección de Bessel, también conocida como varianza con N-1 grados de libertad. Suponiendo que las observaciones son representativas de la población (es decir, independientes y distribuidas de forma idéntica), el resultado es una estimación no sesgada de la varianza.

Si conoces de antemano la verdadera media poblacional μ, debes pasarla a pvariance() mediante el parámetro mu para obtener la varianza muestral.

statistics.quantiles(data, *, n=4, method='exclusive')

Divide data en n intervalos continuos equiprobables. Retorna una lista de n - 1 límites que delimitan los intervalos (cuantiles).

Establece n en 4 para obtener los cuartiles (el valor predeterminado), en 10 para obtener los deciles y en 100 para obtener los percentiles (lo que produce 99 valores que separan data en 100 grupos del mismo tamaño). Si n es menor que 1, se lanza una excepción StatisticsError.

data puede ser cualquier iterable que contenga los valores de la muestra. Para que los resultados sean significativos, el número de observaciones en la muestra data debe ser mayor que n. Si no hay al menos dos observaciones se lanza una excepción StatisticsError.

Los límites de los intervalos se interpolan linealmente a partir de los dos valores más cercanos de la muestra. Por ejemplo, si un límite es un tercio de la distancia entre los valores 100 y 112 de la muestra, el límite será 104.

El argumento method indica el método que se utilizará para calcular los cuantiles y se puede modificar para especificar si se deben incluir o excluir valores de data extremos, altos y bajos, de la población.

El valor predeterminado para method es «exclusive» y es aplicable a los datos muestreados de una población que puede tener valores más extremos que los encontrados en las muestras. La proporción de la población que se encuentra por debajo del i-ésimo valor de m valores ordenados se calcula mediante la fórmula i / (m + 1). Por ejemplo, asumiendo que hay 9 valores en la muestra, este método los ordena y los asocia con los siguientes percentiles: 10%, 20%, 30%, 40%, 50%, 60%, 70%, 80%, 90%.

Si se usa «inclusive» como valor para el parámetro method, se asume que los datos corresponden a una población completa o que los valores extremos de la población están representados en la muestra. El valor mínimo de data se considera entonces como percentil 0 y el máximo como percentil 100. La proporción de la población que se encuentra por debajo del i-ésimo valor de m valores ordenados se calcula mediante la fórmula (i - 1) / (m - 1). Suponiendo que tenemos 11 valores en la muestra, este método los ordena y los asocia con los siguientes percentiles: 0%, 10%, 20%, 30%, 40%, 50%, 60%, 70%, 80 %, 90%, 100%.

# Decile cut points for empirically sampled data
>>> data = [105, 129, 87, 86, 111, 111, 89, 81, 108, 92, 110,
...         100, 75, 105, 103, 109, 76, 119, 99, 91, 103, 129,
...         106, 101, 84, 111, 74, 87, 86, 103, 103, 106, 86,
...         111, 75, 87, 102, 121, 111, 88, 89, 101, 106, 95,
...         103, 107, 101, 81, 109, 104]
>>> [round(q, 1) for q in quantiles(data, n=10)]
[81.0, 86.2, 89.0, 99.4, 102.5, 103.6, 106.0, 109.8, 111.0]

Nuevo en la versión 3.8.

Excepciones

Se define una sola excepción:

exception statistics.StatisticsError

Subclase de ValueError para excepciones relacionadas con la estadística.

Objetos NormalDist

NormalDist es una herramienta para crear y manipular distribuciones normales de una variable aleatoria [http://www.stat.yale.edu/Courses/1997-98/101/ranvar.htm]. Esta clase gestiona la desviación típica y la media de un conjunto de observaciones como una sola entidad.

Las distribuciones normales surgen del Teorema del límite central [https://es.wikipedia.org/wiki/Teorema_del_l%C3%ADmite_central] y tienen una amplia gama de aplicaciones en estadística.

class statistics.NormalDist(mu=0.0, sigma=1.0)

Retorna un nuevo objeto NormalDist donde mu representa la media aritmética [https://es.wikipedia.org/wiki/Media_aritm%C3%A9tica] y sigma representa la desviación típica [https://es.wikipedia.org/wiki/Desviaci%C3%B3n_t%C3%ADpica].

Se lanza una excepción StatisticsError si sigma es negativo.

mean

Una propiedad de solo lectura para la media aritmética [https://es.wikipedia.org/wiki/Media_aritm%C3%A9tica] de una distribución normal.

median

Una propiedad de solo lectura para la mediana [https://es.wikipedia.org/wiki/Mediana_(estad%C3%ADstica)] de una distribución normal.

mode

Una propiedad de solo lectura para la moda [https://es.wikipedia.org/wiki/Moda_(estad%C3%ADstica)] de una distribución normal.

stdev

Una propiedad de solo lectura para la desviación típica [https://es.wikipedia.org/wiki/Desviaci%C3%B3n_t%C3%ADpica] de una distribución normal.

variance

Una propiedad de solo lectura para la varianza [https://es.wikipedia.org/wiki/Varianza] de una distribución normal. Es igual al cuadrado de la desviación típica.

classmethod from_samples(data)

Crea una instancia de distribución normal con los parámetros mu y sigma estimados a partir de data usando fmean() y stdev().

data puede ser cualquier iterable de valores que se puedan convertir al tipo float. Se lanza una excepción StatisticsError si data no contiene al menos dos elementos, esto se debe a que se necesita al menos un punto para estimar un valor central y al menos dos puntos para estimar la dispersión.

samples(n, *, seed=None)

Genera n muestras aleatorias para una media y una desviación típica proporcionadas. Retorna un objeto list de valores float.

Si se proporciona seed, su valor se usa para inicializar una nueva instancia del generador de números aleatorios subyacente. Esto permite producir resultados reproducibles incluso en un contexto de paralelismo con múltiples hilos.

pdf(x)

Haciendo uso de una función de densidad de probabilidad (FPD o PDF en inglés) [https://es.wikipedia.org/wiki/Funci%C3%B3n_de_densidad_de_probabilidad], calcula la verosimilitud relativa de que una variable aleatoria X caiga en una región cercana al valor x proporcionado. Matemáticamente, esto corresponde al límite de la razón P(x <= X < x+dx) / dx cuando dx tiende a cero.

La verosimilitud relativa se calcula como la probabilidad de que una observación pertenezca a un intervalo estrecho dividida entre el ancho del intervalo (de ahí el término «densidad»). Como la verosimilitud es relativa a los otros puntos, su valor puede ser mayor que 1.0.

cdf(x)

Usando una función de distribución acumulada (FDA, CDF en inglés) [https://es.wikipedia.org/wiki/Funci%C3%B3n_de_distribuci%C3%B3n], calcula la probabilidad de que una variable aleatoria X sea menor o igual que x. Matemáticamente, se escribe P(X <= x).

inv_cdf(p)

Calcula la función de distribución acumulada inversa, también conocida como función cuantil [https://es.wikipedia.org/wiki/Funci%C3%B3n_cuantil] o función punto porcentual [https://www.statisticshowto.datasciencecentral.com/inverse-distribution-function/]. Matemáticamente, se escribe x : P(X <= x) = p.

Calcula el valor x de la variable aleatoria X tal que la probabilidad de que la variable sea menor o igual a este valor es igual a la probabilidad p dada.

overlap(other)

Mide la concordancia entre dos distribuciones de probabilidad normales. Retorna un valor entre 0.0 y 1.0 que indica el área de superposición de dos funciones de densidad de probabilidad [https://www.rasch.org/rmt/rmt101r.htm].

quantiles(n=4)

Divide la distribución normal en n intervalos continuos equiprobables. Retorna una lista de (n - 1) cuantiles que separan los intervalos.

Establece n en 4 para obtener los cuartiles (el valor predeterminado), en 10 para obtener los deciles y en 100 para obtener los percentiles (lo que produce 99 límites que separan los datos en 100 grupos del mismo tamaño).

zscore(x)

Compute the Standard Score [https://www.statisticshowto.com/probability-and-statistics/z-score/] describing x in terms of the number of standard deviations above or below the mean of the normal distribution: (x - mean) / stdev.

Nuevo en la versión 3.9.

Las instancias de la clase NormalDist soportan la suma, resta, multiplicación y división por una constante. Estas operaciones se pueden utilizar para traducir o escalar, por ejemplo:

>>> temperature_february = NormalDist(5, 2.5)             # Celsius
>>> temperature_february * (9/5) + 32                     # Fahrenheit
NormalDist(mu=41.0, sigma=4.5)

No se admite la división de una constante entre una instancia de NormalDist debido a que el resultado no sería una distribución normal.

Dado que las distribuciones normales se derivan de las propiedades aditivas de variables independientes, es posible sumar o restar dos variables independientes con distribución normal [https://en.wikipedia.org/wiki/Sum_of_normally_distributed_random_variables] representadas por instancias de NormalDist. Por ejemplo :

>>> birth_weights = NormalDist.from_samples([2.5, 3.1, 2.1, 2.4, 2.7, 3.5])
>>> drug_effects = NormalDist(0.4, 0.15)
>>> combined = birth_weights + drug_effects
>>> round(combined.mean, 1)
3.1
>>> round(combined.stdev, 1)
0.5

Nuevo en la versión 3.8.

Ejemplos de uso de NormalDist

NormalDist permite resolver fácilmente problemas probabilísticos clásicos.

Por ejemplo, sabiendo que los datos históricos de los exámenes SAT [https://nces.ed.gov/programs/digest/d17/tables/dt17_226.40.asp] siguen una distribución normal con una media de 1060 y una desviación típica de 195, determinar el porcentaje de estudiantes con puntuaciones entre 1100 y 1200, redondeado al número entero más cercano:

>>> sat = NormalDist(1060, 195)
>>> fraction = sat.cdf(1200 + 0.5) - sat.cdf(1100 - 0.5)
>>> round(fraction * 100.0, 1)
18.4

Determinar los cuartiles [https://es.wikipedia.org/wiki/Cuartil] y deciles [https://es.wikipedia.org/wiki/Decil_(estad%C3%ADstica)] de las puntuaciones del SAT:

>>> list(map(round, sat.quantiles()))
[928, 1060, 1192]
>>> list(map(round, sat.quantiles(n=10)))
[810, 896, 958, 1011, 1060, 1109, 1162, 1224, 1310]

Con la finalidad de estimar la distribución de un modelo que es difícil de resolver analíticamente, NormalDist puede generar muestras de entrada para una simulación utilizando el método Montecarlo [https://es.wikipedia.org/wiki/M%C3%A9todo_de_Montecarlo]:

>>> def model(x, y, z):
...     return (3*x + 7*x*y - 5*y) / (11 * z)
...
>>> n = 100_000
>>> X = NormalDist(10, 2.5).samples(n, seed=3652260728)
>>> Y = NormalDist(15, 1.75).samples(n, seed=4582495471)
>>> Z = NormalDist(50, 1.25).samples(n, seed=6582483453)
>>> quantiles(map(model, X, Y, Z))
[1.4591308524824727, 1.8035946855390597, 2.175091447274739]

Las distribuciones normales se pueden utilizar para aproximar distribuciones binomiales [http://mathworld.wolfram.com/BinomialDistribution.html] cuando el tamaño de la muestra es grande y la probabilidad de un ensayo exitoso es cercana al 50%.

Por ejemplo, 750 personas asisten a una conferencia sobre código abierto y se dispone de dos salas con capacidad para 500 personas cada una. En la primera sala hay una charla sobre Python, en la otra una sobre Ruby. En conferencias pasadas, el 65% de las personas prefirieron escuchar las charlas sobre Python. Suponiendo que las preferencias de la población no hayan cambiado, ¿cuál es la probabilidad de que la sala de Python permanezca por debajo de su capacidad máxima?

>>> n = 750             # Sample size
>>> p = 0.65            # Preference for Python
>>> q = 1.0 - p         # Preference for Ruby
>>> k = 500             # Room capacity

>>> # Approximation using the cumulative normal distribution
>>> from math import sqrt
>>> round(NormalDist(mu=n*p, sigma=sqrt(n*p*q)).cdf(k + 0.5), 4)
0.8402

>>> # Solution using the cumulative binomial distribution
>>> from math import comb, fsum
>>> round(fsum(comb(n, r) * p**r * q**(n-r) for r in range(k+1)), 4)
0.8402

>>> # Approximation using a simulation
>>> from random import seed, choices
>>> seed(8675309)
>>> def trial():
...     return choices(('Python', 'Ruby'), (p, q), k=n).count('Python')
>>> mean(trial() <= k for i in range(10_000))
0.8398

Las distribuciones normales a menudo están involucradas en el aprendizaje automático.

Wikipedia detalla un buen ejemplo de un clasificador bayesiano ingenuo [https://es.wikipedia.org/wiki/Clasificador_bayesiano_ingenuo]. El objetivo es predecir el género de una persona a partir de características físicas que siguen una distribución normal, como la altura, el peso y el tamaño del pie.

Disponemos de un conjunto de datos de entrenamiento que contiene las medidas de ocho personas. Se supone que estas medidas siguen una distribución normal, por lo que podemos sintetizar los datos usando NormalDist:

>>> height_male = NormalDist.from_samples([6, 5.92, 5.58, 5.92])
>>> height_female = NormalDist.from_samples([5, 5.5, 5.42, 5.75])
>>> weight_male = NormalDist.from_samples([180, 190, 170, 165])
>>> weight_female = NormalDist.from_samples([100, 150, 130, 150])
>>> foot_size_male = NormalDist.from_samples([12, 11, 12, 10])
>>> foot_size_female = NormalDist.from_samples([6, 8, 7, 9])

A continuación, nos encontramos con un nuevo individuo del que conocemos las medidas de sus características pero no su género:

>>> ht = 6.0        # height
>>> wt = 130        # weight
>>> fs = 8          # foot size

Partiendo de una probabilidad a priori [https://es.wikipedia.org/wiki/Probabilidad_a_priori] del 50% de ser hombre o mujer, calculamos la probabilidad a posteriori como el producto de la probabilidad a priori y la verosimilitud de las diferentes medidas dado el género:

>>> prior_male = 0.5
>>> prior_female = 0.5
>>> posterior_male = (prior_male * height_male.pdf(ht) *
...                   weight_male.pdf(wt) * foot_size_male.pdf(fs))

>>> posterior_female = (prior_female * height_female.pdf(ht) *
...                     weight_female.pdf(wt) * foot_size_female.pdf(fs))

La predicción final es la que tiene mayor probabilidad a posteriori. Este enfoque se denomina máximo a posteriori [https://en.wikipedia.org/wiki/Maximum_a_posteriori_estimation] o MAP:

>>> 'male' if posterior_male > posterior_female else 'female'
'female'

Módulos de programación funcional

Los módulos descritos en este capítulo proporcionan funciones y clases que admiten un estilo de programación funcional y operaciones generales invocables (callables).

En este capítulo se documentan los siguientes módulos:

itertools — Funciones que crean iteradores para bucles eficientes

Funciones de itertools

Fórmulas con itertools

functools — Funciones de orden superior y operaciones sobre objetos invocables

partial Objetos

operator — Operadores estándar como funciones

Asignación de operadores a funciones

Operadores In-place

itertools — Funciones que crean iteradores para bucles eficientes

Este módulo implementa un número de piezas básicas iterator inspiradas en constructs de APL, Haskell y SML. Cada pieza ha sido reconvertida a una forma apropiada para Python.

El módulo estandariza un conjunto base de herramientas rápidas y eficientes en memoria, útiles por sí mismas o en combinación con otras. Juntas, forman un «álgebra de iteradores», haciendo posible la construcción de herramientas especializadas, sucintas y eficientes, en Python puro.

Por ejemplo, SML provee una herramienta de tabulación tabulate(f), que produce una secuencia f(0), f(1), .... En Python, se puede lograr el mismo efecto al combinar map() y count() para formar map(f, count()).

Estas herramientas y sus contrapartes incorporadas también funcionan bien con funciones de alta velocidad del módulo operator. Por ejemplo, el operador de multiplicación se puede mapear a lo largo de dos vectores para formar un eficiente producto escalar: sum(map(operator.mul, vector1, vector2)).

Iteradores infinitos:

Iterador

Argumentos

Resultados

Ejemplo

count()

start, [step]

start, start+step, start+2*step, …

count(10) --> 10 11 12 13 14 ...

cycle()

p

p0, p1, … plast, p0, p1, …

cycle('ABCD') --> A B C D A B C D ...

repeat()

elem [,n]

elem, elem, elem, … indefinidamente o hasta n veces

repeat(10, 3) --> 10 10 10

Iteradores que terminan en la secuencia de entrada más corta:

Iterador

Argumentos

Resultados

Ejemplo

accumulate()

p [,func]

p0, p0+p1, p0+p1+p2, …

accumulate([1,2,3,4,5]) --> 1 3 6 10 15

chain()

p, q, …

p0, p1, … plast, q0, q1, …

chain('ABC', 'DEF') --> A B C D E F

chain.from_iterable()

iterable

p0, p1, … plast, q0, q1, …

chain.from_iterable(['ABC', 'DEF']) --> A B C D E F

compress()

data, selectors

(d[0] if s[0]), (d[1] if s[1]), …

compress('ABCDEF', [1,0,1,0,1,1]) --> A C E F

dropwhile()

pred, seq

seq[n], seq[n+1], comenzando cuando pred falla

dropwhile(lambda x: x<5, [1,4,6,4,1]) --> 6 4 1

filterfalse()

pred, seq

elementos de seq donde pred(elem) es falso

filterfalse(lambda x: x%2, range(10)) --> 0 2 4 6 8

groupby()

iterable[, key]

sub-iteradores agrupados según el valor de key(v)

islice()

seq, [start,] stop [, step]

elementos de seq[start:stop:step]

islice('ABCDEFG', 2, None) --> C D E F G

starmap()

func, seq

func(*seq[0]), func(*seq[1]), …

starmap(pow, [(2,5), (3,2), (10,3)]) --> 32 9 1000

takewhile()

pred, seq

seq[0], seq[1], hasta que pred falle

takewhile(lambda x: x<5, [1,4,6,4,1]) --> 1 4

tee()

it, n

it1, it2, … itn divide un iterador en n

zip_longest()

p, q, …

(p[0], q[0]), (p[1], q[1]), …

zip_longest('ABCD', 'xy', fillvalue='-') --> Ax By C- D-

Iteradores combinatorios:

Iterador

Argumentos

Resultados

product()

p, q, … [repeat=1]

producto cartesiano, equivalente a un bucle for anidado

permutations()

p[, r]

tuplas de longitud r, en todas los órdenes posibles, sin elementos repetidos

combinations()

p, r

tuplas de longitud r, ordenadas, sin elementos repetidos

combinations_with_replacement()

p, r

tuplas de longitud r, ordenadas, con elementos repetidos

Ejemplos

Resultados

product('ABCD', repeat=2)

AA AB AC AD BA BB BC BD CA CB CC CD DA DB DC DD

permutations('ABCD', 2)

AB AC AD BA BC BD CA CB CD DA DB DC

combinations('ABCD', 2)

AB AC AD BC BD CD

combinations_with_replacement('ABCD', 2)

AA AB AC AD BB BC BD CC CD DD

Funciones de itertools

Todas las funciones del siguiente módulo construyen y retornan iteradores. Algunas proveen flujos infinitos, por lo que deberían ser sólo manipuladas por funciones o bucles que cortan el flujo.

itertools.accumulate(iterable[, func, *, initial=None])

Crea un iterador que retorna sumas acumuladas o resultados acumulados de otra función binaria (especificada a través del argumento opcional func).

Si func es definido, debería ser una función de 2 argumentos. Los elementos de entrada de iterable pueden ser de cualquier tipo que puedan ser aceptados como argumentos de func. (Por ejemplo, con la operación por defecto –adición, los elementos pueden ser cualquier tipo que sea sumable, incluyendo Decimal o Fraction.)

Usualmente el número de elementos de salida corresponde con el número de elementos del iterador de entrada. Sin embargo, si el argumento clave initial es suministrado, la acumulación empieza con initial como valor inicial y el resultado contiene un elemento más que el iterador de entrada.

Aproximadamente equivalente a:

def accumulate(iterable, func=operator.add, *, initial=None):
    'Return running totals'
    # accumulate([1,2,3,4,5]) --> 1 3 6 10 15
    # accumulate([1,2,3,4,5], initial=100) --> 100 101 103 106 110 115
    # accumulate([1,2,3,4,5], operator.mul) --> 1 2 6 24 120
    it = iter(iterable)
    total = initial
    if initial is None:
        try:
            total = next(it)
        except StopIteration:
            return
    yield total
    for element in it:
        total = func(total, element)
        yield total

Hay un número de usos para el argumento func. Se le puede asignar min() para calcular un mínimo acumulado, max() para un máximo acumulado, o operator.mul() para un producto acumulado. Se pueden crear tablas de amortización al acumular intereses y aplicando pagos. Relaciones de recurrencias [https://es.wikipedia.org/wiki/Relación_de_recurrencia] de primer orden se puede modelar al proveer el valor inicial en el iterable y utilizando sólo el total acumulado en el argumento func:

>>> data = [3, 4, 6, 2, 1, 9, 0, 7, 5, 8]
>>> list(accumulate(data, operator.mul))     # running product
[3, 12, 72, 144, 144, 1296, 0, 0, 0, 0]
>>> list(accumulate(data, max))              # running maximum
[3, 4, 6, 6, 6, 9, 9, 9, 9, 9]

# Amortize a 5% loan of 1000 with 4 annual payments of 90
>>> cashflows = [1000, -90, -90, -90, -90]
>>> list(accumulate(cashflows, lambda bal, pmt: bal*1.05 + pmt))
[1000, 960.0, 918.0, 873.9000000000001, 827.5950000000001]

# Chaotic recurrence relation https://en.wikipedia.org/wiki/Logistic_map
>>> logistic_map = lambda x, _:  r * x * (1 - x)
>>> r = 3.8
>>> x0 = 0.4
>>> inputs = repeat(x0, 36)     # only the initial value is used
>>> [format(x, '.2f') for x in accumulate(inputs, logistic_map)]
['0.40', '0.91', '0.30', '0.81', '0.60', '0.92', '0.29', '0.79', '0.63',
 '0.88', '0.39', '0.90', '0.33', '0.84', '0.52', '0.95', '0.18', '0.57',
 '0.93', '0.25', '0.71', '0.79', '0.63', '0.88', '0.39', '0.91', '0.32',
 '0.83', '0.54', '0.95', '0.20', '0.60', '0.91', '0.30', '0.80', '0.60']

Para una función similar que retorne únicamente el valor final acumulado, revisa functools.reduce().

Nuevo en la versión 3.2.

Distinto en la versión 3.3: Adicionó el argumento opcional func.

Distinto en la versión 3.8: Adicionó el argumento opcional initial.

itertools.chain(*iterables)

Crea un iterador que retorna elementos del primer iterable hasta que es consumido, para luego proceder con el siguiente iterable, hasta que todos los iterables son consumidos. Se utiliza para tratar secuencias consecutivas como unas sola secuencia. Aproximadamente equivalente a:

def chain(*iterables):
    # chain('ABC', 'DEF') --> A B C D E F
    for it in iterables:
        for element in it:
            yield element

classmethod chain.from_iterable(iterable)

Constructor alternativo para chain(). Obtiene entradas enlazadas de un mismo argumento que se evalúa perezosamente. Aproximadamente equivalente a:

def from_iterable(iterables):
    # chain.from_iterable(['ABC', 'DEF']) --> A B C D E F
    for it in iterables:
        for element in it:
            yield element

itertools.combinations(iterable, r)

Retorna subsecuencias de longitud r con elementos del iterable de entrada.

Las tuplas de combinación se emiten en orden lexicográfico según el orden de la entrada iterable. Entonces, si la entrada iterable está ordenada, las tuplas de combinación se producirán en una secuencia ordenada.

Los elementos son tratados como únicos basados en su posición, no en su valor. De esta manera, si los elementos de entrada son únicos, no habrá valores repetidos en cada combinación.

Aproximadamente equivalente a:

def combinations(iterable, r):
    # combinations('ABCD', 2) --> AB AC AD BC BD CD
    # combinations(range(4), 3) --> 012 013 023 123
    pool = tuple(iterable)
    n = len(pool)
    if r > n:
        return
    indices = list(range(r))
    yield tuple(pool[i] for i in indices)
    while True:
        for i in reversed(range(r)):
            if indices[i] != i + n - r:
                break
        else:
            return
        indices[i] += 1
        for j in range(i+1, r):
            indices[j] = indices[j-1] + 1
        yield tuple(pool[i] for i in indices)

El código para combinations() se puede expresar también como una subsecuencia de permutations(), luego de filtrar entradas donde los elementos no están ordenados (de acuerdo a su posición en el conjunto de entrada):

def combinations(iterable, r):
    pool = tuple(iterable)
    n = len(pool)
    for indices in permutations(range(n), r):
        if sorted(indices) == list(indices):
            yield tuple(pool[i] for i in indices)

El número de elementos retornados es n! / r! / (n-r)! cuando 0 <= r <= n o cero cuando r > n.

itertools.combinations_with_replacement(iterable, r)

Retorna subsecuencias, de longitud r, con elementos del iterable de entrada, permitiendo que haya elementos individuales repetidos más de una vez.

Las tuplas de combinación se emiten en orden lexicográfico según el orden de la entrada iterable. Entonces, si la entrada iterable está ordenada, las tuplas de combinación se producirán en una secuencia ordenada.

Los elementos son tratados como únicos basados en su posición, no en su valor. De esta manera, si los elementos de entrada son únicos, las combinaciones generadas también serán únicas.

Aproximadamente equivalente a:

def combinations_with_replacement(iterable, r):
    # combinations_with_replacement('ABC', 2) --> AA AB AC BB BC CC
    pool = tuple(iterable)
    n = len(pool)
    if not n and r:
        return
    indices = [0] * r
    yield tuple(pool[i] for i in indices)
    while True:
        for i in reversed(range(r)):
            if indices[i] != n - 1:
                break
        else:
            return
        indices[i:] = [indices[i] + 1] * (r - i)
        yield tuple(pool[i] for i in indices)

El código para combinations_with_replacement() se puede expresar también como una subsecuencia de product(), luego de filtrar entradas donde los elementos no están ordenados (de acuerdo a su posición en el conjunto de entrada):

def combinations_with_replacement(iterable, r):
    pool = tuple(iterable)
    n = len(pool)
    for indices in product(range(n), repeat=r):
        if sorted(indices) == list(indices):
            yield tuple(pool[i] for i in indices)

El número de elementos retornados es (n+r-1)! / r! / (n-1)! cuando n > 0.

Nuevo en la versión 3.1.

itertools.compress(data, selectors)

Crea un iterador que filtra elementos de data, retornando sólo aquellos que tienen un elemento correspondiente en selectors que evalúa a True. El iterador se detiene cuando alguno de los iterables (data o selectors) ha sido consumido. Aproximadamente equivalente a:

def compress(data, selectors):
    # compress('ABCDEF', [1,0,1,0,1,1]) --> A C E F
    return (d for d, s in zip(data, selectors) if s)

Nuevo en la versión 3.1.

itertools.count(start=0, step=1)

Crea un iterador que retorna valores espaciados uniformemente, comenzando con el número start. Usualmente se utiliza como argumento en map() para generar puntos de datos consecutivos. También se utiliza en zip() para agregar secuencias de números. Aproximadamente equivalente a:

def count(start=0, step=1):
    # count(10) --> 10 11 12 13 14 ...
    # count(2.5, 0.5) -> 2.5 3.0 3.5 ...
    n = start
    while True:
        yield n
        n += step

Cuando se hace conteo con números de punto flotante, se puede lograr una mejor precisión al sustituir código multiplicativo como: (start + step * i for i in count()).

Distinto en la versión 3.1: Se adicionó el argumento step y se permitieron argumentos diferentes a enteros.

itertools.cycle(iterable)

Crea un iterador que retorna elementos del iterable y hace una copia de cada uno. Cuando el iterable es consumido, retornar los elementos de la copia almacenada. Se repite indefinidamente. Aproximadamente equivalente a:

def cycle(iterable):
    # cycle('ABCD') --> A B C D A B C D A B C D ...
    saved = []
    for element in iterable:
        yield element
        saved.append(element)
    while saved:
        for element in saved:
              yield element

Ten en cuenta, este miembro del conjunto de herramientas puede requerir almacenamiento auxiliar importante (dependiendo de la longitud del iterable).

itertools.dropwhile(predicate, iterable)

Crea un iterador que descarta elementos del iterable, siempre y cuando el predicado sea verdadero; después, retorna cada elemento. Ten en cuenta, el iterador no produce ningún resultado hasta que el predicado se hace falso, pudiendo incurrir en un tiempo de arranque extenso. Aproximadamente equivalente a:

def dropwhile(predicate, iterable):
    # dropwhile(lambda x: x<5, [1,4,6,4,1]) --> 6 4 1
    iterable = iter(iterable)
    for x in iterable:
        if not predicate(x):
            yield x
            break
    for x in iterable:
        yield x

itertools.filterfalse(predicate, iterable)

Crea un iterador que filtra elementos de un iterable, retornando sólo aquellos para los cuales el predicado es False. Si predicate es None, retorna los elementos que son falsos. Aproximadamente equivalente a:

def filterfalse(predicate, iterable):
    # filterfalse(lambda x: x%2, range(10)) --> 0 2 4 6 8
    if predicate is None:
        predicate = bool
    for x in iterable:
        if not predicate(x):
            yield x

itertools.groupby(iterable, key=None)

Crea un iterador que retorna claves consecutivas y grupos del iterable. key es una función que calcula un valor clave para cada elemento. Si no se especifica o es None, key es una función de identidad por defecto y retorna el elemento sin cambios. Generalmente, el iterable necesita estar ordenado con la misma función key.

El funcionamiento de groupby() es similar al del filtro uniq en Unix. Genera un salto o un nuevo grupo cada vez que el valor de la función clave cambia (por lo que usualmente es necesario ordenar los datos usando la misma función clave). Ese comportamiento difiere del de GROUP BY de SQL, el cual agrega elementos comunes sin importar el orden de entrada.

El grupo retornado es un iterador mismo que comparte el iterable subyacente con groupby(). Al compartir la fuente, cuando el objeto groupby() se avanza, el grupo previo deja de ser visible. En ese caso, si los datos se necesitan posteriormente, se deberían almacenar como lista:

groups = []
uniquekeys = []
data = sorted(data, key=keyfunc)
for k, g in groupby(data, keyfunc):
    groups.append(list(g))      # Store group iterator as a list
    uniquekeys.append(k)

groupby() es aproximadamente equivalente a:

class groupby:
    # [k for k, g in groupby('AAAABBBCCDAABBB')] --> A B C D A B
    # [list(g) for k, g in groupby('AAAABBBCCD')] --> AAAA BBB CC D
    def __init__(self, iterable, key=None):
        if key is None:
            key = lambda x: x
        self.keyfunc = key
        self.it = iter(iterable)
        self.tgtkey = self.currkey = self.currvalue = object()
    def __iter__(self):
        return self
    def __next__(self):
        self.id = object()
        while self.currkey == self.tgtkey:
            self.currvalue = next(self.it)    # Exit on StopIteration
            self.currkey = self.keyfunc(self.currvalue)
        self.tgtkey = self.currkey
        return (self.currkey, self._grouper(self.tgtkey, self.id))
    def _grouper(self, tgtkey, id):
        while self.id is id and self.currkey == tgtkey:
            yield self.currvalue
            try:
                self.currvalue = next(self.it)
            except StopIteration:
                return
            self.currkey = self.keyfunc(self.currvalue)

itertools.islice(iterable, stop)

itertools.islice(iterable, start, stop[, step])

Crea un iterador que retorna los elementos seleccionados del iterable. Si start es diferente a cero, los elementos del iterable son ignorados hasta que se llegue a start. Después de eso, los elementos son retornados consecutivamente a menos que step posea un valor tan alto que permita que algunos elementos sean ignorados. Si stop es None, la iteración continúa hasta que el iterador sea consumido (si es que llega a ocurrir); de lo contrario, se detiene en la posición especificada. A diferencia de la segmentación normal, islice() no soporta valores negativos para start, stop, o step. Puede usarse para extraer campos relacionados de estructuras de datos que internamente has sido simplificadas (por ejemplo, un reporte multilínea puede contener un nombre de campo cada tres líneas). Aproximadamente equivalente a:

def islice(iterable, *args):
    # islice('ABCDEFG', 2) --> A B
    # islice('ABCDEFG', 2, 4) --> C D
    # islice('ABCDEFG', 2, None) --> C D E F G
    # islice('ABCDEFG', 0, None, 2) --> A C E G
    s = slice(*args)
    start, stop, step = s.start or 0, s.stop or sys.maxsize, s.step or 1
    it = iter(range(start, stop, step))
    try:
        nexti = next(it)
    except StopIteration:
        # Consume *iterable* up to the *start* position.
        for i, element in zip(range(start), iterable):
            pass
        return
    try:
        for i, element in enumerate(iterable):
            if i == nexti:
                yield element
                nexti = next(it)
    except StopIteration:
        # Consume to *stop*.
        for i, element in zip(range(i + 1, stop), iterable):
            pass

Si start es None, la iteración empieza en cero. Si step es None, step se establece en uno por defecto.

itertools.permutations(iterable, r=None)

Retorna permutaciones de elementos sucesivas de longitud r en el iterable.

Si r no es especificado o si es None, entonces por defecto r será igual a la longitud de iterable y todas las permutaciones de máxima longitud serán generadas.

Las tuplas de permutación se emiten en orden lexicográfico según el orden de la entrada iterable. Entonces, si la entrada iterable está ordenada, las tuplas de combinación se producirán en una secuencia ordenada.

Los elementos son tratados como únicos según su posición, y no su valor. Por ende, no habrá elementos repetidos en cada permutación si los elementos de entrada son únicos.

Aproximadamente equivalente a:

def permutations(iterable, r=None):
    # permutations('ABCD', 2) --> AB AC AD BA BC BD CA CB CD DA DB DC
    # permutations(range(3)) --> 012 021 102 120 201 210
    pool = tuple(iterable)
    n = len(pool)
    r = n if r is None else r
    if r > n:
        return
    indices = list(range(n))
    cycles = list(range(n, n-r, -1))
    yield tuple(pool[i] for i in indices[:r])
    while n:
        for i in reversed(range(r)):
            cycles[i] -= 1
            if cycles[i] == 0:
                indices[i:] = indices[i+1:] + indices[i:i+1]
                cycles[i] = n - i
            else:
                j = cycles[i]
                indices[i], indices[-j] = indices[-j], indices[i]
                yield tuple(pool[i] for i in indices[:r])
                break
        else:
            return

El código para permutations() también se puede expresar como una subsecuencia de product(), filtrado para excluir registros con elementos repetidos (aquellos en la misma posición que en el conjunto de entrada):

def permutations(iterable, r=None):
    pool = tuple(iterable)
    n = len(pool)
    r = n if r is None else r
    for indices in product(range(n), repeat=r):
        if len(set(indices)) == r:
            yield tuple(pool[i] for i in indices)

El número de elementos retornados es n! / (n-r)! cuando 0 <= r <= n o cero cuando r > n.

itertools.product(*iterables, repeat=1)

Producto cartesiano de los iterables de entrada.

Aproximadamente equivalente a tener bucles for anidados en un generador. Por ejemplo, product(A, B) es equivalente a ((x,y) for x in A for y in B).

Los bucles anidados hacen ciclos como un cuentapasos o taxímetro, con el elemento más hacia la derecha avanzando en cada iteración. Este patrón crea un orden lexicográfico en el que, si los iterables de entrada están ordenados, las tuplas producidas son emitidas de manera ordenada.

Para calcular el producto de un iterable consigo mismo, especifica el número de repeticiones con el argumento opcional repeat. Por ejemplo, product(A, repeat=4) es equivalente a product(A, A, A, A).

Esta función es aproximadamente equivalente al código siguiente, exceptuando que la implementación real no acumula resultados intermedios en memoria:

def product(*args, repeat=1):
    # product('ABCD', 'xy') --> Ax Ay Bx By Cx Cy Dx Dy
    # product(range(2), repeat=3) --> 000 001 010 011 100 101 110 111
    pools = [tuple(pool) for pool in args] * repeat
    result = [[]]
    for pool in pools:
        result = [x+[y] for x in result for y in pool]
    for prod in result:
        yield tuple(prod)

Antes de que product() se ejecute, consume completamente los iterables de entrada, manteniendo grupos de valores en la memoria para generar los productos. En consecuencia, solo es útil con entradas finitas.

itertools.repeat(object[, times])

Crea un iterador que retorna object una y otra vez. Se ejecuta indefinidamente a menos que se especifique el argumento times. Se utiliza como argumento de map() para argumentos invariantes de la función invocada. También se usa con zip() para crear una parte invariante de una tupla.

Aproximadamente equivalente a:

def repeat(object, times=None):
    # repeat(10, 3) --> 10 10 10
    if times is None:
        while True:
            yield object
    else:
        for i in range(times):
            yield object

Un uso común de repeat es el de proporcionar un flujo de valores constantes a map o zip:

>>> list(map(pow, range(10), repeat(2)))
[0, 1, 4, 9, 16, 25, 36, 49, 64, 81]

itertools.starmap(function, iterable)

Crea un iterador que calcula la función utilizando argumentos obtenidos del iterable. Se usa en lugar de map() cuando los argumentos ya están agrupados en tuplas de un mismo iterable (los datos ya han sido «pre-comprimidos”). La diferencia entre map() y starmap() es similar a la distinción entre function(a,b) y function(*c). Aproximadamente equivalente a:

def starmap(function, iterable):
    # starmap(pow, [(2,5), (3,2), (10,3)]) --> 32 9 1000
    for args in iterable:
        yield function(*args)

itertools.takewhile(predicate, iterable)

Crea un iterador que retorna elementos del iterador siempre y cuando el predicado sea cierto. Aproximadamente equivalente a:

def takewhile(predicate, iterable):
    # takewhile(lambda x: x<5, [1,4,6,4,1]) --> 1 4
    for x in iterable:
        if predicate(x):
            yield x
        else:
            break

itertools.tee(iterable, n=2)

Retorna n iteradores independientes de un mismo iterador.

El código Python a continuación ayuda a explicar el funcionamiento de tee (aunque la implementación real es mucho más compleja y usa sólo una cola FIFO subyacente).

Aproximadamente equivalente a:

def tee(iterable, n=2):
    it = iter(iterable)
    deques = [collections.deque() for i in range(n)]
    def gen(mydeque):
        while True:
            if not mydeque:             # when the local deque is empty
                try:
                    newval = next(it)   # fetch a new value and
                except StopIteration:
                    return
                for d in deques:        # load it to all the deques
                    d.append(newval)
            yield mydeque.popleft()
    return tuple(gen(d) for d in deques)

Una vez que tee() ha hecho un corte, el iterable original no se debería usar en otro lugar. De lo contrario, el iterable podría avanzarse sin informar a los objetos tee.

Los iteradores tee no son threadsafe. RuntimeError puede ocurrir si se usan simultáneamente iteradores retornados por la misma llamada a tee() call, aún cuando el iterable original sea threadsafe.

Esta herramienta de iteración puede requerir almacenamiento auxiliar significativo (dependiendo de qué tantos datos necesitan ser almacenados). En general, si un iterador utiliza todos o la mayoría de los datos antes que otro iterador comience, es más rápido utilizar list() en vez de tee().

itertools.zip_longest(*iterables, fillvalue=None)

Crea un iterador que agrega elementos de cada uno de los iterables. Si los iterables tiene longitud impar, los valores sin encontrar serán iguales a fillvalue. La iteración continúa hasta que el iterable más largo sea consumido. Aproximadamente equivalente a:

def zip_longest(*args, fillvalue=None):
    # zip_longest('ABCD', 'xy', fillvalue='-') --> Ax By C- D-
    iterators = [iter(it) for it in args]
    num_active = len(iterators)
    if not num_active:
        return
    while True:
        values = []
        for i, it in enumerate(iterators):
            try:
                value = next(it)
            except StopIteration:
                num_active -= 1
                if not num_active:
                    return
                iterators[i] = repeat(fillvalue)
                value = fillvalue
            values.append(value)
        yield tuple(values)

Si alguno de los iterables es potencialmente infinito, la función zip_longest() debería ser recubierta por otra que limite el número de llamadas (por ejemplo, islice() o takewhile()). Si no se especifica, fillvalue es None por defecto.

Fórmulas con itertools

Esta sección muestra fórmulas para crear un conjunto de herramientas extendido usando las herramientas de itertools como piezas básicas.

De manera considerable, todas estas fórmulas y muchos otras se pueden instalar desde el proyecto more-itertools [https://pypi.org/project/more-itertools/], ubicado en el Python Package Index:

pip install more-itertools

Las herramientas adicionales ofrecen el mismo alto rendimiento que las herramientas subyacentes. El rendimiento de memoria superior se mantiene al procesar los elementos uno a uno, y no cargando el iterable entero en memoria. El volumen de código se mantiene bajo al enlazar las herramientas en estilo funcional, eliminando variables temporales. La alta velocidad se retiene al preferir piezas «vectorizadas» sobre el uso de bucles for y generators que puedan incurrir en costos extra.

def take(n, iterable):
    "Return first n items of the iterable as a list"
    return list(islice(iterable, n))

def prepend(value, iterator):
    "Prepend a single value in front of an iterator"
    # prepend(1, [2, 3, 4]) -> 1 2 3 4
    return chain([value], iterator)

def tabulate(function, start=0):
    "Return function(0), function(1), ..."
    return map(function, count(start))

def tail(n, iterable):
    "Return an iterator over the last n items"
    # tail(3, 'ABCDEFG') --> E F G
    return iter(collections.deque(iterable, maxlen=n))

def consume(iterator, n=None):
    "Advance the iterator n-steps ahead. If n is None, consume entirely."
    # Use functions that consume iterators at C speed.
    if n is None:
        # feed the entire iterator into a zero-length deque
        collections.deque(iterator, maxlen=0)
    else:
        # advance to the empty slice starting at position n
        next(islice(iterator, n, n), None)

def nth(iterable, n, default=None):
    "Returns the nth item or a default value"
    return next(islice(iterable, n, None), default)

def all_equal(iterable):
    "Returns True if all the elements are equal to each other"
    g = groupby(iterable)
    return next(g, True) and not next(g, False)

def quantify(iterable, pred=bool):
    "Count how many times the predicate is true"
    return sum(map(pred, iterable))

def pad_none(iterable):
    """Returns the sequence elements and then returns None indefinitely.

    Useful for emulating the behavior of the built-in map() function.
    """
    return chain(iterable, repeat(None))

def ncycles(iterable, n):
    "Returns the sequence elements n times"
    return chain.from_iterable(repeat(tuple(iterable), n))

def dotproduct(vec1, vec2):
    return sum(map(operator.mul, vec1, vec2))

def convolve(signal, kernel):
    # See:  https://betterexplained.com/articles/intuitive-convolution/
    # convolve(data, [0.25, 0.25, 0.25, 0.25]) --> Moving average (blur)
    # convolve(data, [1, -1]) --> 1st finite difference (1st derivative)
    # convolve(data, [1, -2, 1]) --> 2nd finite difference (2nd derivative)
    kernel = tuple(kernel)[::-1]
    n = len(kernel)
    window = collections.deque([0], maxlen=n) * n
    for x in chain(signal, repeat(0, n-1)):
        window.append(x)
        yield sum(map(operator.mul, kernel, window))

def flatten(list_of_lists):
    "Flatten one level of nesting"
    return chain.from_iterable(list_of_lists)

def repeatfunc(func, times=None, *args):
    """Repeat calls to func with specified arguments.

    Example:  repeatfunc(random.random)
    """
    if times is None:
        return starmap(func, repeat(args))
    return starmap(func, repeat(args, times))

def pairwise(iterable):
    "s -> (s0,s1), (s1,s2), (s2, s3), ..."
    a, b = tee(iterable)
    next(b, None)
    return zip(a, b)

def grouper(iterable, n, fillvalue=None):
    "Collect data into fixed-length chunks or blocks"
    # grouper('ABCDEFG', 3, 'x') --> ABC DEF Gxx"
    args = [iter(iterable)] * n
    return zip_longest(*args, fillvalue=fillvalue)

def roundrobin(*iterables):
    "roundrobin('ABC', 'D', 'EF') --> A D E B F C"
    # Recipe credited to George Sakkis
    num_active = len(iterables)
    nexts = cycle(iter(it).__next__ for it in iterables)
    while num_active:
        try:
            for next in nexts:
                yield next()
        except StopIteration:
            # Remove the iterator we just exhausted from the cycle.
            num_active -= 1
            nexts = cycle(islice(nexts, num_active))

def partition(pred, iterable):
    "Use a predicate to partition entries into false entries and true entries"
    # partition(is_odd, range(10)) --> 0 2 4 6 8   and  1 3 5 7 9
    t1, t2 = tee(iterable)
    return filterfalse(pred, t1), filter(pred, t2)

def powerset(iterable):
    "powerset([1,2,3]) --> () (1,) (2,) (3,) (1,2) (1,3) (2,3) (1,2,3)"
    s = list(iterable)
    return chain.from_iterable(combinations(s, r) for r in range(len(s)+1))

def unique_everseen(iterable, key=None):
    "List unique elements, preserving order. Remember all elements ever seen."
    # unique_everseen('AAAABBBCCDAABBB') --> A B C D
    # unique_everseen('ABBCcAD', str.lower) --> A B C D
    seen = set()
    seen_add = seen.add
    if key is None:
        for element in filterfalse(seen.__contains__, iterable):
            seen_add(element)
            yield element
    else:
        for element in iterable:
            k = key(element)
            if k not in seen:
                seen_add(k)
                yield element

def unique_justseen(iterable, key=None):
    "List unique elements, preserving order. Remember only the element just seen."
    # unique_justseen('AAAABBBCCDAABBB') --> A B C D A B
    # unique_justseen('ABBCcAD', str.lower) --> A B C A D
    return map(next, map(operator.itemgetter(1), groupby(iterable, key)))

def iter_except(func, exception, first=None):
    """ Call a function repeatedly until an exception is raised.

    Converts a call-until-exception interface to an iterator interface.
    Like builtins.iter(func, sentinel) but uses an exception instead
    of a sentinel to end the loop.

    Examples:
        iter_except(functools.partial(heappop, h), IndexError)   # priority queue iterator
        iter_except(d.popitem, KeyError)                         # non-blocking dict iterator
        iter_except(d.popleft, IndexError)                       # non-blocking deque iterator
        iter_except(q.get_nowait, Queue.Empty)                   # loop over a producer Queue
        iter_except(s.pop, KeyError)                             # non-blocking set iterator

    """
    try:
        if first is not None:
            yield first()            # For database APIs needing an initial cast to db.first()
        while True:
            yield func()
    except exception:
        pass

def first_true(iterable, default=False, pred=None):
    """Returns the first true value in the iterable.

    If no true value is found, returns *default*

    If *pred* is not None, returns the first item
    for which pred(item) is true.

    """
    # first_true([a,b,c], x) --> a or b or c or x
    # first_true([a,b], x, f) --> a if f(a) else b if f(b) else x
    return next(filter(pred, iterable), default)

def random_product(*args, repeat=1):
    "Random selection from itertools.product(*args, **kwds)"
    pools = [tuple(pool) for pool in args] * repeat
    return tuple(map(random.choice, pools))

def random_permutation(iterable, r=None):
    "Random selection from itertools.permutations(iterable, r)"
    pool = tuple(iterable)
    r = len(pool) if r is None else r
    return tuple(random.sample(pool, r))

def random_combination(iterable, r):
    "Random selection from itertools.combinations(iterable, r)"
    pool = tuple(iterable)
    n = len(pool)
    indices = sorted(random.sample(range(n), r))
    return tuple(pool[i] for i in indices)

def random_combination_with_replacement(iterable, r):
    "Random selection from itertools.combinations_with_replacement(iterable, r)"
    pool = tuple(iterable)
    n = len(pool)
    indices = sorted(random.choices(range(n), k=r))
    return tuple(pool[i] for i in indices)

def nth_combination(iterable, r, index):
    "Equivalent to list(combinations(iterable, r))[index]"
    pool = tuple(iterable)
    n = len(pool)
    if r < 0 or r > n:
        raise ValueError
    c = 1
    k = min(r, n-r)
    for i in range(1, k+1):
        c = c * (n - k + i) // i
    if index < 0:
        index += c
    if index < 0 or index >= c:
        raise IndexError
    result = []
    while r:
        c, n, r = c*r//n, n-1, r-1
        while index >= c:
            index -= c
            c, n = c*(n-r)//n, n-1
        result.append(pool[-1-n])
    return tuple(result)

functools — Funciones de orden superior y operaciones sobre objetos invocables

Código fuente: Lib/functools.py [https://github.com/python/cpython/tree/3.9/Lib/functools.py]

El módulo functools es para funciones de orden superior: funciones que actúan o retornan otras funciones. En general, cualquier objeto invocable puede ser tratado como una función para los propósitos de este módulo.

El módulo functools define las siguientes funciones:

@functools.cache(user_function)

Caché de funciones ilimitado, ligero y simple. Aveces llamado «memoización» [https://es.wikipedia.org/wiki/Memoizaci%C3%B3n].

Retorna lo mismo que lru_cache(maxsize=None), creando una envoltura delgada alrededor de una búsqueda de diccionario para los argumentos de la función. Debido a que nunca necesita desalojar los valores antiguos, esto es más pequeño y más rápido que lru_cache() con un límite de tamaño.

Por ejemplo:

@cache
def factorial(n):
    return n * factorial(n-1) if n else 1

>>> factorial(10)      # no previously cached result, makes 11 recursive calls
3628800
>>> factorial(5)       # just looks up cached value result
120
>>> factorial(12)      # makes two new recursive calls, the other 10 are cached
479001600

Nuevo en la versión 3.9.

@functools.cached_property(func)

Transforma un método de una clase en una propiedad cuyo valor se computa una vez y luego se almacena como un atributo normal durante la vida de la instancia. Similar a property(), con la adición de caching. Útil para propiedades calculadas costosas de instancias que de otra manera son efectivamente inmutables.

Ejemplo:

class DataSet:

    def __init__(self, sequence_of_numbers):
        self._data = tuple(sequence_of_numbers)

    @cached_property
    def stdev(self):
        return statistics.stdev(self._data)

La mecánica de cached_property() es algo diferente de property(). Un atributo de bloques de propiedad normal escribe a menos que se defina un establecedor. Por el contrario, cached_property permite escrituras.

El decorador cached_property solo se ejecuta en búsquedas y solo cuando no existe un atributo con el mismo nombre. Cuando se ejecuta, cached_property escribe en el atributo con el mismo nombre. Las lecturas y escrituras de atributos posteriores tienen prioridad sobre el método cached_property y funciona como un atributo normal.

El valor en caché se puede borrar eliminando el atributo. Esto permite que el método cached_property se ejecute nuevamente.

Tenga en cuenta que este decorador interfiere con el funcionamiento de diccionarios de intercambio de claves PEP 412 [https://www.python.org/dev/peps/pep-0412]. Esto significa que los diccionarios de instancias pueden ocupar más espacio de lo habitual.

Además, este decorador requiere que el atributo __dict__ en cada instancia sea un mapeo mutable. Esto significa que no funcionará con algunos tipos, como las metaclases (ya que los atributos __dict__ en las instancias de tipos son proxies de solo lectura para el espacio de nombres de la clase) y aquellos que especifican __slots__ sin incluir __dict__ como una de las ranuras definidas (ya que tales clases no proporcionan un atributo __dict__ en absoluto).

Si un mapeo mutable no está disponible o si se desea compartir claves con espacio eficiente, se puede lograr un efecto similar a cached_property() apilando property() encima de cache():

class DataSet:
    def __init__(self, sequence_of_numbers):
        self._data = sequence_of_numbers

    @property
    @cache
    def stdev(self):
        return statistics.stdev(self._data)

Nuevo en la versión 3.8.

functools.cmp_to_key(func)

Transformar una función de comparación de estilo antiguo en una key function. Se utiliza con herramientas que aceptan funciones clave (como sorted(), min(), max(), heapq.nlargest(), heapq.nsmallest(), itertools.groupby()). Esta función se utiliza principalmente como una herramienta de transición para los programas que se están convirtiendo a partir de Python 2, que soportaba el uso de funciones de comparación.

Una función de comparación es cualquier invocable que acepta dos argumentos, los compara y retorna un número negativo para diferencia, cero para igualdad o un número positivo para más. Una función clave es un invocable que acepta un argumento y retorna otro valor para ser usado como clave de ordenación.

Ejemplo:

sorted(iterable, key=cmp_to_key(locale.strcoll))  # locale-aware sort order

Para ejemplos de clasificación y un breve tutorial de clasificación, ver HOW TO - Ordenar.

Nuevo en la versión 3.2.

@functools.lru_cache(user_function)

@functools.lru_cache(maxsize=128, typed=False)

Decorador para envolver una función con un memorizador invocable que guarda hasta el maxsize de las llamadas más recientes. Puede salvar el tiempo cuando una función costosa o de E/S es llamada periódicamente con los mismos argumentos.

Dado que se utiliza un diccionario para guardar los resultados, los argumentos posicionales y de las palabras clave de la función deben ser hashable.

Los patrones de argumento distintos pueden considerarse como llamadas distintas con entradas de caché separadas. Por ejemplo, f(a=1, b=2) y f(b=2, a=1) difieren en el orden de los argumentos de las palabras clave y pueden tener dos entradas de caché separadas.

Si se especifica user_function, debe ser una llamada. Esto permite que el decorador lru_cache se aplique directamente a una función de usuario, dejando el maxsize en su valor por defecto de 128:

@lru_cache
def count_vowels(sentence):
    sentence = sentence.casefold()
    return sum(sentence.count(vowel) for vowel in 'aeiou')

Si maxsize está configurado como None, la función LRU está desactivada y la caché puede crecer sin límites.

Si typed se establece como verdadero, los argumentos de las funciones de diferentes tipos se almacenarán en la memoria caché por separado. Por ejemplo, f(3) y f(3.0) se tratarán como llamadas distintas con resultados distintos.

La función envuelta está instrumentada con una función cache_parameters() que retorna un nuevo dict que muestra los valores para maxsize y typed. Esto es solo para fines informativos. La mutación de los valores no tiene ningún efecto.

Para ayudar a medir la efectividad del cache y afinar el parámetro maxsize, la función envolvente está instrumentada con una función cache_info() que retorna un named tuple mostrando hits, misses, maxsize y currsize. En un entorno multi-hilo, los aciertos y los fallos son aproximados.

El decorador también proporciona una función cache_clear() para limpiar o invalidar el caché.

La función subyacente original es accesible a través del atributo __wrapped__. Esto es útil para la introspección, para evitar el caché, o para volver a envolver la función con un caché diferente.

Un caché LRU (menos usado recientemente) [https://es.wikipedia.org/wiki/Algoritmo_de_cach%C3%A9#Menos_usado_recientemente_(LRU)] funciona mejor cuando las llamadas más recientes son los mejores predictores de las próximas llamadas (por ejemplo, el los artículos más populares en un servidor de noticias tienden a cambiar cada día). El límite de tamaño de la caché asegura que la caché no crezca sin límites en procesos de larga ejecución como servidores web.

En general, la caché de la LRU sólo debe utilizarse cuando se desea reutilizar valores previamente calculados. Por consiguiente, no tiene sentido almacenar en la caché funciones con efectos secundarios, funciones que necesitan crear distintos objetos mutables en cada llamada, o funciones impuras como time() o random().

Ejemplo de un caché de la LRU para contenido web estático:

@lru_cache(maxsize=32)
def get_pep(num):
    'Retrieve text of a Python Enhancement Proposal'
    resource = 'https://www.python.org/dev/peps/pep-%04d/' % num
    try:
        with urllib.request.urlopen(resource) as s:
            return s.read()
    except urllib.error.HTTPError:
        return 'Not Found'

>>> for n in 8, 290, 308, 320, 8, 218, 320, 279, 289, 320, 9991:
...     pep = get_pep(n)
...     print(n, len(pep))

>>> get_pep.cache_info()
CacheInfo(hits=3, misses=8, maxsize=32, currsize=8)

Ejemplo de computar eficientemente los «números de Fibonacci» <https://en.wikipedia.org/wiki/Fibonacci_number>`_ usando un cache para implementar una «programación dinámica» <https://en.wikipedia.org/wiki/Dynamic_programming>`_ técnica:

@lru_cache(maxsize=None)
def fib(n):
    if n < 2:
        return n
    return fib(n-1) + fib(n-2)

>>> [fib(n) for n in range(16)]
[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610]

>>> fib.cache_info()
CacheInfo(hits=28, misses=16, maxsize=None, currsize=16)

Nuevo en la versión 3.2.

Distinto en la versión 3.3: Añadida la opción typed option.

Distinto en la versión 3.8: Añadida la opción user_function.

Nuevo en la versión 3.9: Añadida la función cache_parameters()

@functools.total_ordering

Dada una clase que define uno o más métodos de ordenamiento de comparación ricos, este decorador de clase suministra el resto. Esto simplifica el esfuerzo de especificar todas las posibles operaciones de comparación rica:

La clase debe definir uno de __lt__(), __le__(), __gt__(), o __ge__(). Además, la clase debe suministrar un método __eq__(). Dada una clase que define uno o más métodos de ordenamiento de comparación ricos, este decorador de clase suministra el resto. Esto simplifica el esfuerzo de especificar todas las posibles operaciones de comparación rica.

Por ejemplo:

@total_ordering
class Student:
    def _is_valid_operand(self, other):
        return (hasattr(other, "lastname") and
                hasattr(other, "firstname"))
    def __eq__(self, other):
        if not self._is_valid_operand(other):
            return NotImplemented
        return ((self.lastname.lower(), self.firstname.lower()) ==
                (other.lastname.lower(), other.firstname.lower()))
    def __lt__(self, other):
        if not self._is_valid_operand(other):
            return NotImplemented
        return ((self.lastname.lower(), self.firstname.lower()) <
                (other.lastname.lower(), other.firstname.lower()))

Nota

Mientras que este decorador facilita la creación de tipos bien comportados y totalmente ordenados, does a costa de una ejecución más lenta y de trazos de pila (stack traces) más complejos para los métodos de comparación derivados. Si la evaluación comparativa del rendimiento indica que se trata de un cuello de botella para una aplicación determinada, la aplicación de los seis métodos de comparación ricos en su lugar es probable que proporcione un fácil aumento de la velocidad.

Nuevo en la versión 3.2.

Distinto en la versión 3.4: Retornando NotImplemented de la función de comparación subyacente para los tipos no reconocidos está ahora soportado.

functools.partial(func, /, *args, **keywords)

Retorna un nuevo partial object que cuando sea llamado se comportará como func llamado con los argumentos posicionales args y los argumentos de palabras clave keywords. Si se suministran más argumentos a la llamada, se añaden a args. Si se suministran más argumentos de palabras clave, se extienden y anulan las keywords. Aproximadamente equivalente a:

def partial(func, /, *args, **keywords):
    def newfunc(*fargs, **fkeywords):
        newkeywords = {**keywords, **fkeywords}
        return func(*args, *fargs, **newkeywords)
    newfunc.func = func
    newfunc.args = args
    newfunc.keywords = keywords
    return newfunc

El partial() se utiliza para la aplicación de funciones parciales que «congela» (freezes) alguna porción de los argumentos y/o palabras clave de una función dando como resultado un nuevo objeto con una firma simplificada. Por ejemplo, partial() puede usarse para crear una llamada que se comporte como la función int() donde el argumento base tiene un valor por defecto de dos:

>>> from functools import partial
>>> basetwo = partial(int, base=2)
>>> basetwo.__doc__ = 'Convert base 2 string to an int.'
>>> basetwo('10010')
18

class functools.partialmethod(func, /, *args, **keywords)

Retorna un nuevo descriptor partialmethod que se comporta como partial excepto que está diseñado para ser usado como una definición de método en lugar de ser directamente invocable.

func debe ser un descriptor o un invocable (los objetos que son ambos, como las funciones normales, se manejan como descriptores).

Cuando func es un descriptor (como una función Python normal, classmethod(), staticmethod(), abstractmethod() u otra instancia de partialmethod), las llamadas a __get__ se delegan al descriptor subyacente, y se retorna un partial object apropiado como resultado.

Cuando func es una llamada no descriptiva, se crea dinámicamente un método de unión apropiado. Esto se comporta como una función Python normal cuando se usa como método: el argumento self se insertará como el primer argumento posicional, incluso antes de las args y keywords suministradas al constructor partialmethod.

Ejemplo:

>>> class Cell:
...     def __init__(self):
...         self._alive = False
...     @property
...     def alive(self):
...         return self._alive
...     def set_state(self, state):
...         self._alive = bool(state)
...     set_alive = partialmethod(set_state, True)
...     set_dead = partialmethod(set_state, False)
...
>>> c = Cell()
>>> c.alive
False
>>> c.set_alive()
>>> c.alive
True

Nuevo en la versión 3.4.

functools.reduce(function, iterable[, initializer])

Aplicar una función de dos argumentos acumulativos a los elementos de iterable, de izquierda a derecha, para reducir los itables a un solo valor. Por ejemplo, reduce(lambda x, y: x+y, [1, 2, 3, 4, 5]) calcula ((((1+2)+3)+4)+5). El argumento de la izquierda, x, es el valor acumulado y el de la derecha, y, es el valor de actualización del iterable. Si el initializer opcional está presente, se coloca antes de los ítems de la iterable en el cálculo, y sirve como predeterminado cuando la iterable está vacía. Si no se da el initializer y el iterable contiene sólo un elemento, se retorna el primer elemento.

Aproximadamente equivalente a:

def reduce(function, iterable, initializer=None):
    it = iter(iterable)
    if initializer is None:
        value = next(it)
    else:
        value = initializer
    for element in it:
        value = function(value, element)
    return value

Ver itertools.accumulate() para un iterador que produce todos los valores intermedios.

@functools.singledispatch

Transformar una función en una single-dispatch generic function.

To define a generic function, decorate it with the @singledispatch decorator. When defining a function using @singledispatch, note that the dispatch happens on the type of the first argument:

>>> from functools import singledispatch
>>> @singledispatch
... def fun(arg, verbose=False):
...     if verbose:
...         print("Let me just say,", end=" ")
...     print(arg)

To add overloaded implementations to the function, use the register() attribute of the generic function, which can be used as a decorator. For functions annotated with types, the decorator will infer the type of the first argument automatically:

>>> @fun.register
... def _(arg: int, verbose=False):
...     if verbose:
...         print("Strength in numbers, eh?", end=" ")
...     print(arg)
...
>>> @fun.register
... def _(arg: list, verbose=False):
...     if verbose:
...         print("Enumerate this:")
...     for i, elem in enumerate(arg):
...         print(i, elem)

Para el código que no utiliza anotaciones de tipo, el argumento de tipo apropiado puede ser pasado explícitamente al propio decorador:

>>> @fun.register(complex)
... def _(arg, verbose=False):
...     if verbose:
...         print("Better than complicated.", end=" ")
...     print(arg.real, arg.imag)
...

To enable registering lambdas and pre-existing functions, the register() attribute can also be used in a functional form:

>>> def nothing(arg, verbose=False):
...     print("Nothing.")
...
>>> fun.register(type(None), nothing)

The register() attribute returns the undecorated function. This enables decorator stacking, pickling, and the creation of unit tests for each variant independently:

>>> @fun.register(float)
... @fun.register(Decimal)
... def fun_num(arg, verbose=False):
...     if verbose:
...         print("Half of your number:", end=" ")
...     print(arg / 2)
...
>>> fun_num is fun
False

Cuando se llama, la función genérica despacha sobre el tipo del primer argumento:

>>> fun("Hello, world.")
Hello, world.
>>> fun("test.", verbose=True)
Let me just say, test.
>>> fun(42, verbose=True)
Strength in numbers, eh? 42
>>> fun(['spam', 'spam', 'eggs', 'spam'], verbose=True)
Enumerate this:
0 spam
1 spam
2 eggs
3 spam
>>> fun(None)
Nothing.
>>> fun(1.23)
0.615

Where there is no registered implementation for a specific type, its method resolution order is used to find a more generic implementation. The original function decorated with @singledispatch is registered for the base object type, which means it is used if no better implementation is found.

If an implementation is registered to an abstract base class, virtual subclasses of the base class will be dispatched to that implementation:

>>> from collections.abc import Mapping
>>> @fun.register
... def _(arg: Mapping, verbose=False):
...     if verbose:
...         print("Keys & Values")
...     for key, value in arg.items():
...         print(key, "=>", value)
...
>>> fun({"a": "b"})
a => b

To check which implementation the generic function will choose for a given type, use the dispatch() attribute:

>>> fun.dispatch(float)
<function fun_num at 0x1035a2840>
>>> fun.dispatch(dict)    # note: default implementation
<function fun at 0x103fe0000>

Para acceder a todas las implementaciones registradas, utilice el atributo registry de sólo lectura:

>>> fun.registry.keys()
dict_keys([<class 'NoneType'>, <class 'int'>, <class 'object'>,
          <class 'decimal.Decimal'>, <class 'list'>,
          <class 'float'>])
>>> fun.registry[float]
<function fun_num at 0x1035a2840>
>>> fun.registry[object]
<function fun at 0x103fe0000>

Nuevo en la versión 3.4.

Distinto en la versión 3.7: The register() attribute now supports using type annotations.

class functools.singledispatchmethod(func)

Transformar un método en un single-dispatch generic function.

To define a generic method, decorate it with the @singledispatchmethod decorator. When defining a function using @singledispatchmethod, note that the dispatch happens on the type of the first non-self or non-cls argument:

class Negator:
    @singledispatchmethod
    def neg(self, arg):
        raise NotImplementedError("Cannot negate a")

    @neg.register
    def _(self, arg: int):
        return -arg

    @neg.register
    def _(self, arg: bool):
        return not arg

@singledispatchmethod supports nesting with other decorators such as @classmethod. Note that to allow for dispatcher.register, singledispatchmethod must be the outer most decorator. Here is the Negator class with the neg methods bound to the class, rather than an instance of the class:

class Negator:
    @singledispatchmethod
    @classmethod
    def neg(cls, arg):
        raise NotImplementedError("Cannot negate a")

    @neg.register
    @classmethod
    def _(cls, arg: int):
        return -arg

    @neg.register
    @classmethod
    def _(cls, arg: bool):
        return not arg

The same pattern can be used for other similar decorators: @staticmethod, @abstractmethod, and others.

Nuevo en la versión 3.8.

functools.update_wrapper(wrapper, wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)

Actualiza una función wrapper para que se parezca a la función wrapped. Los argumentos opcionales son tuplas para especificar qué atributos de la función original se asignan directamente a los atributos coincidentes en la función contenedora y qué atributos de la función contenedora se actualizan con los atributos correspondientes de la función original. Los valores predeterminados para estos argumentos son las constantes de nivel de módulo WRAPPER_ASSIGNMENTS (que se asigna a la función contenedora __module__, __name__, __qualname__, __annotations__ y __doc__, la cadena de caracteres de documentación) y WRAPPER_UPDATES (que actualiza el __dict__ de la función contenedora, es decir, el diccionario de instancia).

Para permitir el acceso a la función original para la introspección y otros propósitos (por ejemplo, evitando un decorador de caché como lru_cache()), esta función añade automáticamente un atributo __wrapped__ al envoltorio que se refiere a la función que se está envolviendo.

El principal uso previsto para esta función es en decorator functions que envuelven la función decorada y retornan el envoltorio. Si la función de envoltura no se actualiza, los metadatos de la función retornada reflejarán la definición de la envoltura en lugar de la definición de la función original, lo que normalmente no es de gran ayuda.

update_wrapper() puede ser usado con otros invocables que no sean funciones. Cualquier atributo nombrado en assigned o updated que falte en el objeto que se está invoca se ignora (es decir, esta función no intentará establecerlos en la función de envoltura (wrapper)). AttributeError sigue apareciendo si la propia función de envoltura no tiene ningún atributo nombrado en updated.

Nuevo en la versión 3.2: Adición automática de __wrapped__ attribute.

Nuevo en la versión 3.2: Copia del atributo __annotations__ por defecto.

Distinto en la versión 3.2: Los atributos faltantes ya no desencadenan un AtributoError.

Distinto en la versión 3.4: El atributo __wrapped__ ahora siempre se refiere a la función envuelta, incluso si esa función definió un atributo __wrapped__. (see :issue:17482)

@functools.wraps(wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)

Esta es una función conveniente para invocar update_wrapper() como decorador de la función cuando se define una función de envoltura (wrapper). Es equivalente a partial(update_wrapper, wrapped=wrapped, assigned=assigned, updated=updated). Por ejemplo:

>>> from functools import wraps
>>> def my_decorator(f):
...     @wraps(f)
...     def wrapper(*args, **kwds):
...         print('Calling decorated function')
...         return f(*args, **kwds)
...     return wrapper
...
>>> @my_decorator
... def example():
...     """Docstring"""
...     print('Called example function')
...
>>> example()
Calling decorated function
Called example function
>>> example.__name__
'example'
>>> example.__doc__
'Docstring'

Sin el uso de esta fábrica de decoradores, el nombre de la función de ejemplo habría sido 'wrapper', y el docstring de la example() se habría perdido.

partial Objetos

Los objetos partial son objetos invocables creados por partial(). Tienen tres atributos de sólo lectura:

partial.func

Un objeto o función invocable. Las llamadas al objeto partial serán reenviadas a func con nuevos argumentos y palabras clave.

partial.args

Los argumentos posicionales de la izquierda que se prepararán para los argumentos posicionales proporcionados un llamado al objeto partial.

partial.keywords

Los argumentos de la palabra clave que se suministrarán cuando se llame al objeto partial.

Los objetos partial son como los objetos function que son invocables, de referencia débil y pueden tener atributos. Hay algunas diferencias importantes. Por ejemplo, los atributos __name__ y __doc__ no se crean automáticamente. Además, los objetos partial definidos en las clases se comportan como métodos estáticos y no se transforman en métodos vinculados durante la búsqueda de atributos de la instancia.

operator — Operadores estándar como funciones

Código fuente: Lib/operator.py [https://github.com/python/cpython/tree/3.9/Lib/operator.py]

El módulo operator exporta un conjunto de funciones eficientes correspondientes a los operadores intrínsecos de Python. Por ejemplo, operator.add(x, y) es equivalente a la expresión x+y. Muchos nombres de función son los utilizados para métodos especiales, sin los dobles guiones bajos. Por compatibilidad con versiones anteriores, muchos de estos tienen una variante que conserva los dobles guiones bajos . Se prefieren las variantes sin los dobles guiones bajos para mayor claridad.

Las funciones se dividen en categorías que realizan comparaciones de objetos, operaciones lógicas, operaciones matemáticas y operaciones sobre secuencias.

Las funciones de comparación de objetos son útiles para todos los objetos, y llevan el nombre de los operadores de comparación enriquecida que soportan:

operator.lt(a, b)

operator.le(a, b)

operator.eq(a, b)

operator.ne(a, b)

operator.ge(a, b)

operator.gt(a, b)

operator.__lt__(a, b)

operator.__le__(a, b)

operator.__eq__(a, b)

operator.__ne__(a, b)

operator.__ge__(a, b)

operator.__gt__(a, b)

Realiza «comparaciones enriquecidas» entre a y b. Específicamente, lt(a, b) es equivalente a a < b, le(a, b) es equivalente a a <= b, eq(a, b) es equivalente a a == b, ne(a, b) es equivalente a a != b, gt(a, b) es equivalente a a > b y ge(a, b) es equivalente a a >= b. Tenga en cuenta que estas funciones pueden retornar cualquier valor, que puede o no ser interpretable como un valor booleano. Consulte Comparaciones para obtener más información sobre las comparaciones enriquecidas.

Las operaciones lógicas también son aplicables a todos los objetos, y admiten pruebas de verdad, pruebas de identidad y operaciones booleanas:

operator.not_(obj)

operator.__not__(obj)

Retorna el resultado de not obj. (Tenga en cuenta que no hay ningún método __not__() para las instancias de objeto; solo el núcleo del intérprete define esta operación. El resultado se ve afectado por los métodos __bool__() y __len__().)

operator.truth(obj)

Retorna True si obj es verdadero, y False de lo contrario. Esto equivale a usar el constructor bool.

operator.is_(a, b)

Retorna a is b. Chequea la identidad del objeto.

operator.is_not(a, b)

Retorna a is not b. Chequea la identidad del objeto.

Las operaciones matemáticas y a nivel de bits son las más numerosas:

operator.abs(obj)

operator.__abs__(obj)

Retorna el valor absoluto de obj.

operator.add(a, b)

operator.__add__(a, b)

Retorna a + b, para los números a y b.

operator.and_(a, b)

operator.__and__(a, b)

Retorna la «conjunción bit a bit» (bitwise and) de a y b.

operator.floordiv(a, b)

operator.__floordiv__(a, b)

Retorna a // b.

operator.index(a)

operator.__index__(a)

Retorna a convertido a un número entero. Equivalente a a.__index__().

operator.inv(obj)

operator.invert(obj)

operator.__inv__(obj)

operator.__invert__(obj)

Retorna el «inverso bit a bit» (bitwise inverse) del número obj. Esto es equivalente a ~obj.

operator.lshift(a, b)

operator.__lshift__(a, b)

Retorna a desplazado a izquierda (shift left) b bits.

operator.mod(a, b)

operator.__mod__(a, b)

Retorna a % b.

operator.mul(a, b)

operator.__mul__(a, b)

Retorna a * b, para los números a y b.

operator.matmul(a, b)

operator.__matmul__(a, b)

Retorna a @ b.

Nuevo en la versión 3.5.

operator.neg(obj)

operator.__neg__(obj)

Retorna obj negado (-obj).

operator.or_(a, b)

operator.__or__(a, b)

Retorna la «disyunción bit a bit» (bitwise or) de a y b.

operator.pos(obj)

operator.__pos__(obj)

Retorna obj positivo (+obj).

operator.pow(a, b)

operator.__pow__(a, b)

Retorna a ** b, para los números a y b.

operator.rshift(a, b)

operator.__rshift__(a, b)

Retorna a desplazado a derecha (shift right) b bits.

operator.sub(a, b)

operator.__sub__(a, b)

Retorna a - b.

operator.truediv(a, b)

operator.__truediv__(a, b)

Retorna a / b donde 2/3 es .66 en lugar de 0. Esto también se conoce como división «real» (true division).

operator.xor(a, b)

operator.__xor__(a, b)

Retorna la disyunción exclusiva bit a bit (bitwise exclusive or) de a y b.

Las operaciones que funcionan con secuencias (y algunas de ellas también con mapeos) incluyen:

operator.concat(a, b)

operator.__concat__(a, b)

Retorna a + b para las secuencias a y b.

operator.contains(a, b)

operator.__contains__(a, b)

Retorna el resultado del chequeo b in a. Notar que los operandos se invirtieron.

operator.countOf(a, b)

Retorna el número de ocurrencias de b en a.

operator.delitem(a, b)

operator.__delitem__(a, b)

Remueve el valor de a en el índice b.

operator.getitem(a, b)

operator.__getitem__(a, b)

Retorna el valor de a en el índice b.

operator.indexOf(a, b)

Retorna el índice de la primera ocurrencia de b en a.

operator.setitem(a, b, c)

operator.__setitem__(a, b, c)

Establece el valor de a en el índice b a c.

operator.length_hint(obj, default=0)

Retorna un largo estimativo del objeto o. Primero intenta retornar su largo real, luego un estimativo usando object.__length_hint__(), y finalmente retorna un valor predeterminado.

Nuevo en la versión 3.4.

El módulo operator también define herramientas para la obtención generalizada de atributos e ítems. Estas herramientas son útiles para utilizar rápidamente extractores de campos como argumentos de map(), sorted(), itertools.groupby(), u otras funciones que esperan una función como argumento.

operator.attrgetter(attr)

operator.attrgetter(*attrs)

Retorna un objeto invocable que obtiene attr de su operando. Si se solicita más de un atributo, retorna una tupla de los atributos. Los nombres de los atributos también pueden contener puntos. Por ejemplo:

Después de f = attrgetter('name'), la llamada f(b) retorna b.name.

Después de f = attrgetter('name', 'date'), la llamada f(b)` retorna ``(b.name, b.date).

Después de f = attrgetter('name.first', 'name.last'), la llamada f(b) retorna (b.name.first, b.name.last).

Equivalente a:

def attrgetter(*items):
    if any(not isinstance(item, str) for item in items):
        raise TypeError('attribute name must be a string')
    if len(items) == 1:
        attr = items[0]
        def g(obj):
            return resolve_attr(obj, attr)
    else:
        def g(obj):
            return tuple(resolve_attr(obj, attr) for attr in items)
    return g

def resolve_attr(obj, attr):
    for name in attr.split("."):
        obj = getattr(obj, name)
    return obj

operator.itemgetter(item)

operator.itemgetter(*items)

Retorna un objeto invocable que obtiene item de su operando utilizando sobre el mismo el método __getitem__(). Si se especifican múltiples ítems, retorna una tupla con los valores obtenidos. Por ejemplo:

Después de f = itemgetter(2), la llamada f(r) retorna r[2].

Después de g = itemgetter(2, 5, 3), la llamada g(r) retorna (r[2], r[5], r[3]).

Equivalente a:

def itemgetter(*items):
    if len(items) == 1:
        item = items[0]
        def g(obj):
            return obj[item]
    else:
        def g(obj):
            return tuple(obj[item] for item in items)
    return g

Los ítems pueden ser de cualquier tipo aceptado por el método __getitem__() del operando. Los diccionarios aceptan cualquier valor hasheable. Las listas, las tuplas y las cadenas de caracteres aceptan un índice o un segmento:

>>> itemgetter(1)('ABCDEFG')
'B'
>>> itemgetter(1, 3, 5)('ABCDEFG')
('B', 'D', 'F')
>>> itemgetter(slice(2, None))('ABCDEFG')
'CDEFG'
>>> soldier = dict(rank='captain', name='dotterbart')
>>> itemgetter('rank')(soldier)
'captain'

Ejemplos que utilizan itemgetter() para obtener campos específicos de un registro tupla:

>>> inventory = [('apple', 3), ('banana', 2), ('pear', 5), ('orange', 1)]
>>> getcount = itemgetter(1)
>>> list(map(getcount, inventory))
[3, 2, 5, 1]
>>> sorted(inventory, key=getcount)
[('orange', 1), ('banana', 2), ('apple', 3), ('pear', 5)]

operator.methodcaller(name, /, *args, **kwargs)

Retorna un objeto invocable que a su vez invoca al método name sobre su operando. Si se pasan argumentos adicionales y/o argumentos por palabra clave, estos serán a su vez pasados al método. Por ejemplo:

Después de f = methodcaller('name'), la llamada f(b) retorna b.name().

Después de f = methodcaller('name', 'foo', bar=1), la llamada f(b) retorna b.name('foo', bar=1).

Equivalente a:

def methodcaller(name, /, *args, **kwargs):
    def caller(obj):
        return getattr(obj, name)(*args, **kwargs)
    return caller

Asignación de operadores a funciones

Esta tabla muestra cómo operaciones abstractas se corresponden con operadores simbólicos en la sintaxis de Python y las funciones en el módulo operator.

Operación

Sintaxis

Función

Adición

a + b

add(a, b)

Concatenación

seq1 + seq2

concat(seq1, seq2)

Chequeo de pertenencia

obj in seq

contains(seq, obj)

División

a / b

truediv(a, b)

División

a // b

floordiv(a, b)

Conjunción lógica bit a bit (bitwise and)

a & b

and_(a, b)

Disyunción lógica bit a bit (bitwise exclusive or)

a ^ b

xor(a, b)

Inversión bit a bit (bitwise inversion)

~ a

invert(a)

Disyunción lógica bit a bit (bitwise or)

a | b

or_(a, b)

Exponenciación

a ** b

pow(a, b)

Identidad

a is b

is_(a, b)

Identidad

a is not b

is_not(a, b)

Asignación indexada

obj[k] = v

setitem(obj, k, v)

Eliminación indexada

del obj[k]

delitem(obj, k)

Indexado

obj[k]

getitem(obj, k)

Desplazamiento a izquierda (left shift)

a << b

lshift(a, b)

Módulo

a % b

mod(a, b)

Multiplicación

a * b

mul(a, b)

Multiplicación de matrices

a @ b

matmul(a, b)

Negación (aritmética)

- a

neg(a)

Negación (lógica)

not a

not_(a)

Positivo

+ a

pos(a)

Desplazamiento a derecha (right shift)

a >> b

rshift(a, b)

Asignación por segmento

seq[i:j] = values

setitem(seq, slice(i, j), values)

Eliminación por segmento

del seq[i:j]

delitem(seq, slice(i, j))

Segmentación

seq[i:j]

getitem(seq, slice(i, j))

Formateo de cadenas

s % obj

mod(s, obj)

Sustracción

a - b

sub(a, b)

Chequeo de verdad

obj

truth(obj)

Ordenado

a < b

lt(a, b)

Ordenado

a <= b

le(a, b)

Igualdad

a == b

eq(a, b)

Diferencia

a != b

ne(a, b)

Ordenado

a >= b

ge(a, b)

Ordenado

a > b

gt(a, b)

Operadores In-place

Muchas operaciones tienen una versión «in-place». Abajo se listan las funciones que proveen un acceso más primitivo a operadores in-place que la sintaxis usual; por ejemplo, el statement x += y es equivalente a x = operator.iadd(x, y). Otra forma de decirlo es que z = operator.iadd(x, y) es equivalente a la sentencia (statement) compuesta z = x; z += y.

En esos ejemplo, notar que cuando se invoca un método in-place, el cómputo y la asignación se realizan en dos pasos separados. Las funciones in-place que se listan aquí debajo solo hacen el primer paso, llamar al método in-place. El segundo paso, la asignación, no se gestiona.

Para objetivos inmutables como cadenas de caracteres, números, y tuplas, el valor actualizado es computado, pero no es asignado de nuevo a la variable de entrada:

>>> a = 'hello'
>>> iadd(a, ' world')
'hello world'
>>> a
'hello'

Para objetivos mutables como listas y diccionarios, el método in-place realiza la actualización, así que no es necesaria una asignación subsiguiente:

>>> s = ['h', 'e', 'l', 'l', 'o']
>>> iadd(s, [' ', 'w', 'o', 'r', 'l', 'd'])
['h', 'e', 'l', 'l', 'o', ' ', 'w', 'o', 'r', 'l', 'd']
>>> s
['h', 'e', 'l', 'l', 'o', ' ', 'w', 'o', 'r', 'l', 'd']

operator.iadd(a, b)

operator.__iadd__(a, b)

a = iadd(a, b) es equivalente a a += b.

operator.iand(a, b)

operator.__iand__(a, b)

a = iand(a, b) es equivalente a a &= b.

operator.iconcat(a, b)

operator.__iconcat__(a, b)

a = iconcat(a, b) es equivalente a a += b para dos a y b secuencias.

operator.ifloordiv(a, b)

operator.__ifloordiv__(a, b)

a = ifloordiv(a, b) es equivalente a a //= b.

operator.ilshift(a, b)

operator.__ilshift__(a, b)

a = ilshift(a, b) es equivalente a a <<= b.

operator.imod(a, b)

operator.__imod__(a, b)

a = imod(a, b) es equivalente a a %= b.

operator.imul(a, b)

operator.__imul__(a, b)

a = imul(a, b) es equivalente a a *= b.

operator.imatmul(a, b)

operator.__imatmul__(a, b)

a = imul(a, b) es equivalente a a *= b.

Nuevo en la versión 3.5.

operator.ior(a, b)

operator.__ior__(a, b)

a = ior(a, b) es equivalente a a |= b.

operator.ipow(a, b)

operator.__ipow__(a, b)

a = ipow(a, b) es equivalente a a **= b.

operator.irshift(a, b)

operator.__irshift__(a, b)

a = irshift(a, b) es equivalente a a >>= b.

operator.isub(a, b)

operator.__isub__(a, b)

a = isub(a, b) es equivalente a a -= b.

operator.itruediv(a, b)

operator.__itruediv__(a, b)

a = itruediv(a, b) es equivalente a a /= b.

operator.ixor(a, b)

operator.__ixor__(a, b)

a = ixor(a, b) es equivalente a a ^= b.

Acceso a archivos y directorios

Los módulos descritos en este capítulo tratan de archivos de disco y directorios. Por ejemplo, hay módulos para leer las propiedades de los archivos, manipular rutas de acceso de forma portátil y crear archivos temporales. La lista completa de módulos en este capítulo es:

pathlib — Object-oriented filesystem paths

Uso básico

Rutas puras

Propiedades generales

Operadores

Acceso a partes individuales

Métodos y propiedades

Rutas concretas

Métodos

Correspondencia a herramientas en el módulo os

os.path — Manipulaciones comunes de nombre de ruta

fileinput — Iterar sobre líneas de múltiples flujos de entrada

stat — Interpretación de los resultados de stat()

filecmp— Comparaciones de Archivo y Directorio

La clase dircmp

tempfile — Generar archivos y directorios temporales

Ejemplos

Funciones y variables deprecadas

glob — Expansión del patrón de nombres de ruta de estilo Unix

fnmatch — Coincidencia de patrones de nombre de archivos Unix

linecache — Acceso aleatorio a líneas de texto

shutil — Operaciones de archivos de alto nivel

Operaciones de directorios y archivos

Operaciones de copia eficientes dependientes de la plataforma

ejemplo de copytree

ejemplo de rmtree

Operaciones de archivado

Ejemplo de archivado

Ejemplo de archivado con base_dir

Consulta el tamaño de la terminal de salida

Ver también

Módulo os

Interfaces del sistema operativo, incluidas las funciones para trabajar con archivos en un nivel inferior al de Python file objects.

Módulo io

La biblioteca de I/O integrada de Python, incluidas las clases abstractas y algunas clases concretas, como la I/O de archivos.

Función incorporada open()

La forma estándar de abrir archivos para leer y escribir con Python.

pathlib — Object-oriented filesystem paths

Nuevo en la versión 3.4.

Código fuente: Lib/pathlib.py [https://github.com/python/cpython/tree/3.9/Lib/pathlib.py]

Este módulo ofrece clases que representan rutas del sistema de archivos con semántica apropiada para diferentes sistemas operativos. Las clases ruta se dividen entre rutas puras, que proporcionan operaciones puramente computacionales sin E/S; y rutas concretas, que heredan de rutas puras pero también proporcionan operaciones de E/S.

Si nunca has usado este módulo o simplemente no estás seguro de qué clase es la adecuada para tu tarea, Path es probablemente lo que necesitas. Crea una instancia ruta concreta para la plataforma en la que se ejecuta el código.

Las rutas puras son útiles en algunos casos especiales, por ejemplo:

Si deseas manipular las rutas de Windows en una máquina Unix (o viceversa). No puedes crear una instancia de WindowsPath cuando se ejecuta en Unix, pero puedes crear una instancia de PureWindowsPath.

Desea asegurar que su código solo manipule rutas sin acceder realmente al sistema operativo. En este caso, crear instancias de una de las clases puras puede ser útil, ya que simplemente no tienen ninguna operación de acceso al sistema operativo.

Ver también

PEP 428 [https://www.python.org/dev/peps/pep-0428]: El módulo pathlib – rutas de sistema orientadas a objetos.

Ver también

Para la manipulación de rutas de bajo nivel en cadenas, también puede usar el módulo os.path.

Uso básico

Importar la clase principal:

>>> from pathlib import Path

Listado de subdirectorios:

>>> p = Path('.')
>>> [x for x in p.iterdir() if x.is_dir()]
[PosixPath('.hg'), PosixPath('docs'), PosixPath('dist'),
 PosixPath('__pycache__'), PosixPath('build')]

Listing Python source files in this directory tree:

>>> list(p.glob('**/*.py'))
[PosixPath('test_pathlib.py'), PosixPath('setup.py'),
 PosixPath('pathlib.py'), PosixPath('docs/conf.py'),
 PosixPath('build/lib/pathlib.py')]

Navegar dentro de un árbol de directorios:

>>> p = Path('/etc')
>>> q = p / 'init.d' / 'reboot'
>>> q
PosixPath('/etc/init.d/reboot')
>>> q.resolve()
PosixPath('/etc/rc.d/init.d/halt')

Consultar propiedades de ruta:

>>> q.exists()
True
>>> q.is_dir()
False

Abrir un archivo:

>>> with q.open() as f: f.readline()
...
'#!/bin/bash\n'

Rutas puras

Los objetos ruta pura proporcionan operaciones de manejo de rutas que en realidad no acceden al sistema de archivos. Hay tres formas de acceder a estas clases, que llamaremos familias:

class pathlib.PurePath(*pathsegments)

Una clase genérica que representa la familia de rutas del sistema (al crear una instancia se crea PurePosixPath o PureWindowsPath):

>>> PurePath('setup.py')      # Running on a Unix machine
PurePosixPath('setup.py')

Each element of pathsegments can be either a string representing a path segment, an object implementing the os.PathLike interface which returns a string, or another path object:

>>> PurePath('foo', 'some/path', 'bar')
PurePosixPath('foo/some/path/bar')
>>> PurePath(Path('foo'), Path('bar'))
PurePosixPath('foo/bar')

Cuando pathsegments está vacío, se asume el directorio actual:

>>> PurePath()
PurePosixPath('.')

Cuando se proporcionan varias rutas absolutas, la última se toma como un ancla (copiando el comportamiento de os.path.join()):

>>> PurePath('/etc', '/usr', 'lib64')
PurePosixPath('/usr/lib64')
>>> PureWindowsPath('c:/Windows', 'd:bar')
PureWindowsPath('d:bar')

Sin embargo, en una ruta de Windows, cambiar la raíz local no elimina la configuración de la unidad anterior:

>>> PureWindowsPath('c:/Windows', '/Program Files')
PureWindowsPath('c:/Program Files')

Spurious slashes and single dots are collapsed, but double dots ('..') are not, since this would change the meaning of a path in the face of symbolic links:

>>> PurePath('foo//bar')
PurePosixPath('foo/bar')
>>> PurePath('foo/./bar')
PurePosixPath('foo/bar')
>>> PurePath('foo/../bar')
PurePosixPath('foo/../bar')

(un enfoque naif haría pensar que PurePosixPath('foo/../bar') es equivalente a PurePosixPath('bar'), lo cual es incorrecto si foo es un enlace simbólico a otro directorio)

Los objetos ruta pura implementan la interfaz os.PathLike, lo que permite su uso en cualquier lugar donde se acepte la interfaz.

Distinto en la versión 3.6: Se agregó soporte para la interfaz os.PathLike.

class pathlib.PurePosixPath(*pathsegments)

Una subclase de PurePath, esta familia representa rutas que no son del sistema de archivos de Windows:

>>> PurePosixPath('/etc')
PurePosixPath('/etc')

pathsegments se especifica de manera similar a PurePath.

class pathlib.PureWindowsPath(*pathsegments)

A subclass of PurePath, this path flavour represents Windows filesystem paths:

>>> PureWindowsPath('c:/Program Files/')
PureWindowsPath('c:/Program Files')

pathsegments se especifica de manera similar a PurePath.

Independientemente del sistema en el que se encuentre, puede crear instancias de todas estas clases, ya que no proporcionan ninguna operación que llame al sistema operativo.

Propiedades generales

Paths are immutable and hashable. Paths of a same flavour are comparable and orderable. These properties respect the flavour’s case-folding semantics:

>>> PurePosixPath('foo') == PurePosixPath('FOO')
False
>>> PureWindowsPath('foo') == PureWindowsPath('FOO')
True
>>> PureWindowsPath('FOO') in { PureWindowsPath('foo') }
True
>>> PureWindowsPath('C:') < PureWindowsPath('d:')
True

Rutas de diferentes familias no son iguales y no se pueden ordenar:

>>> PureWindowsPath('foo') == PurePosixPath('foo')
False
>>> PureWindowsPath('foo') < PurePosixPath('foo')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: '<' not supported between instances of 'PureWindowsPath' and 'PurePosixPath'

Operadores

El operador barra ayuda a crear rutas secundarias, similar a os.path.join():

>>> p = PurePath('/etc')
>>> p
PurePosixPath('/etc')
>>> p / 'init.d' / 'apache2'
PurePosixPath('/etc/init.d/apache2')
>>> q = PurePath('bin')
>>> '/usr' / q
PurePosixPath('/usr/bin')

Se puede usar un objeto ruta en cualquier lugar donde se acepte un objeto que implemente os.PathLike:

>>> import os
>>> p = PurePath('/etc')
>>> os.fspath(p)
'/etc'

The string representation of a path is the raw filesystem path itself (in native form, e.g. with backslashes under Windows), which you can pass to any function taking a file path as a string:

>>> p = PurePath('/etc')
>>> str(p)
'/etc'
>>> p = PureWindowsPath('c:/Program Files')
>>> str(p)
'c:\\Program Files'

Del mismo modo, llamar a bytes en una ruta proporciona la ruta cruda del sistema de archivos como un objeto bytes, codificado por os.fsencode():

>>> bytes(p)
b'/etc'

Nota

Llamar a bytes solo se recomienda en Unix. En Windows, la forma unicode es la representación canónica de las rutas del sistema de archivos.

Acceso a partes individuales

Para acceder a las «partes» (componentes) individuales de una ruta, use la siguiente propiedad:

PurePath.parts

Una tupla que da acceso a los diversos componentes de la ruta:

>>> p = PurePath('/usr/bin/python3')
>>> p.parts
('/', 'usr', 'bin', 'python3')

>>> p = PureWindowsPath('c:/Program Files/PSF')
>>> p.parts
('c:\\', 'Program Files', 'PSF')

(obsérvese cómo la unidad y la raíz local se reagrupan en una sola parte)

Métodos y propiedades

Las rutas puras proporcionan los siguientes métodos y propiedades:

PurePath.drive

Una cadena que representa la letra o el nombre de la unidad, si corresponde:

>>> PureWindowsPath('c:/Program Files/').drive
'c:'
>>> PureWindowsPath('/Program Files/').drive
''
>>> PurePosixPath('/etc').drive
''

UNC shares are also considered drives:

>>> PureWindowsPath('//host/share/foo.txt').drive
'\\\\host\\share'

PurePath.root

Una cadena que representa la raíz (local o global), si la hay:

>>> PureWindowsPath('c:/Program Files/').root
'\\'
>>> PureWindowsPath('c:Program Files/').root
''
>>> PurePosixPath('/etc').root
'/'

Las localizaciones UNC siempre tienen una raíz:

>>> PureWindowsPath('//host/share').root
'\\'

PurePath.anchor

La concatenación de la unidad y la raíz:

>>> PureWindowsPath('c:/Program Files/').anchor
'c:\\'
>>> PureWindowsPath('c:Program Files/').anchor
'c:'
>>> PurePosixPath('/etc').anchor
'/'
>>> PureWindowsPath('//host/share').anchor
'\\\\host\\share\\'

PurePath.parents

Una secuencia inmutable que proporciona acceso a los ancestros lógicos de la ruta:

>>> p = PureWindowsPath('c:/foo/bar/setup.py')
>>> p.parents[0]
PureWindowsPath('c:/foo/bar')
>>> p.parents[1]
PureWindowsPath('c:/foo')
>>> p.parents[2]
PureWindowsPath('c:/')

PurePath.parent

El padre lógico de la ruta

>>> p = PurePosixPath('/a/b/c/d')
>>> p.parent
PurePosixPath('/a/b/c')

No puede ir más allá de un ancla o una ruta vacía:

>>> p = PurePosixPath('/')
>>> p.parent
PurePosixPath('/')
>>> p = PurePosixPath('.')
>>> p.parent
PurePosixPath('.')

Nota

Esta es una operación puramente léxica, de ahí el siguiente comportamiento:

>>> p = PurePosixPath('foo/..')
>>> p.parent
PurePosixPath('foo')

Si desea explorar una ruta arbitraria del sistema de archivos, se recomienda llamar primero a Path.resolve() para resolver los enlaces simbólicos y eliminar los componentes «..».

PurePath.name

Una cadena que representa el componente final de la ruta, excluyendo la unidad y la raíz, si hay alguna:

>>> PurePosixPath('my/library/setup.py').name
'setup.py'

Los nombres de unidad UNC no se consideran:

>>> PureWindowsPath('//some/share/setup.py').name
'setup.py'
>>> PureWindowsPath('//some/share').name
''

PurePath.suffix

La extensión del archivo del componente final, si lo hay:

>>> PurePosixPath('my/library/setup.py').suffix
'.py'
>>> PurePosixPath('my/library.tar.gz').suffix
'.gz'
>>> PurePosixPath('my/library').suffix
''

PurePath.suffixes

Una lista de las extensiones de archivo de la ruta:

>>> PurePosixPath('my/library.tar.gar').suffixes
['.tar', '.gar']
>>> PurePosixPath('my/library.tar.gz').suffixes
['.tar', '.gz']
>>> PurePosixPath('my/library').suffixes
[]

PurePath.stem

El componente final de la ruta, sin su sufijo:

>>> PurePosixPath('my/library.tar.gz').stem
'library.tar'
>>> PurePosixPath('my/library.tar').stem
'library'
>>> PurePosixPath('my/library').stem
'library'

PurePath.as_posix()

Retorna una cadena que representa la ruta con barras invertidas (/):

>>> p = PureWindowsPath('c:\\windows')
>>> str(p)
'c:\\windows'
>>> p.as_posix()
'c:/windows'

PurePath.as_uri()

Representa la ruta como un file URI. ValueError se genera si la ruta no es absoluta.

>>> p = PurePosixPath('/etc/passwd')
>>> p.as_uri()
'file:///etc/passwd'
>>> p = PureWindowsPath('c:/Windows')
>>> p.as_uri()
'file:///c:/Windows'

PurePath.is_absolute()

Retorna si la ruta es absoluta o no. Una ruta se considera absoluta si tiene una raíz y (si la familia lo permite) una unidad:

>>> PurePosixPath('/a/b').is_absolute()
True
>>> PurePosixPath('a/b').is_absolute()
False

>>> PureWindowsPath('c:/a/b').is_absolute()
True
>>> PureWindowsPath('/a/b').is_absolute()
False
>>> PureWindowsPath('c:').is_absolute()
False
>>> PureWindowsPath('//some/share').is_absolute()
True

PurePath.is_relative_to(*other)

Return whether or not this path is relative to the other path.

>>> p = PurePath('/etc/passwd')
>>> p.is_relative_to('/etc')
True
>>> p.is_relative_to('/usr')
False

Nuevo en la versión 3.9.

PurePath.is_reserved()

Con PureWindowsPath, retorna True si la ruta se considera reservada en Windows, False en caso contrario. Con PurePosixPath, siempre retorna False.

>>> PureWindowsPath('nul').is_reserved()
True
>>> PurePosixPath('nul').is_reserved()
False

Las llamadas al sistema de archivos en rutas reservadas pueden fallar inesperadamente o tener efectos no deseados.

PurePath.joinpath(*other)

Llamar a este método es equivalente a combinar la ruta con cada uno de los other argumentos:

>>> PurePosixPath('/etc').joinpath('passwd')
PurePosixPath('/etc/passwd')
>>> PurePosixPath('/etc').joinpath(PurePosixPath('passwd'))
PurePosixPath('/etc/passwd')
>>> PurePosixPath('/etc').joinpath('init.d', 'apache2')
PurePosixPath('/etc/init.d/apache2')
>>> PureWindowsPath('c:').joinpath('/Program Files')
PureWindowsPath('c:/Program Files')

PurePath.match(pattern)

Match this path against the provided glob-style pattern. Return True if matching is successful, False otherwise.

Si pattern es relativo, la ruta puede ser relativa o absoluta, y la coincidencia se realiza desde la derecha:

>>> PurePath('a/b.py').match('*.py')
True
>>> PurePath('/a/b/c.py').match('b/*.py')
True
>>> PurePath('/a/b/c.py').match('a/*.py')
False

Si pattern es absoluto, la ruta debe ser absoluta y toda la ruta debe coincidir:

>>> PurePath('/a.py').match('/*.py')
True
>>> PurePath('a/b.py').match('/*.py')
False

Al igual que con otros métodos, la distinción entre mayúsculas y minúsculas sigue los valores predeterminados de la plataforma:

>>> PurePosixPath('b.py').match('*.PY')
False
>>> PureWindowsPath('b.py').match('*.PY')
True

PurePath.relative_to(*other)

Compute a version of this path relative to the path represented by other. If it’s impossible, ValueError is raised:

>>> p = PurePosixPath('/etc/passwd')
>>> p.relative_to('/')
PurePosixPath('etc/passwd')
>>> p.relative_to('/etc')
PurePosixPath('passwd')
>>> p.relative_to('/usr')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "pathlib.py", line 694, in relative_to
    .format(str(self), str(formatted)))
ValueError: '/etc/passwd' is not in the subpath of '/usr' OR one path is relative and the other absolute.

NOTE: This function is part of PurePath and works with strings. It does not check or access the underlying file structure.

PurePath.with_name(name)

Retorna una nueva ruta con name cambiado. Si la ruta original no tiene nombre, se genera ValueError:

>>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz')
>>> p.with_name('setup.py')
PureWindowsPath('c:/Downloads/setup.py')
>>> p = PureWindowsPath('c:/')
>>> p.with_name('setup.py')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/antoine/cpython/default/Lib/pathlib.py", line 751, in with_name
    raise ValueError("%r has an empty name" % (self,))
ValueError: PureWindowsPath('c:/') has an empty name

PurePath.with_stem(stem)

Return a new path with the stem changed. If the original path doesn’t have a name, ValueError is raised:

>>> p = PureWindowsPath('c:/Downloads/draft.txt')
>>> p.with_stem('final')
PureWindowsPath('c:/Downloads/final.txt')
>>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz')
>>> p.with_stem('lib')
PureWindowsPath('c:/Downloads/lib.gz')
>>> p = PureWindowsPath('c:/')
>>> p.with_stem('')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/antoine/cpython/default/Lib/pathlib.py", line 861, in with_stem
    return self.with_name(stem + self.suffix)
  File "/home/antoine/cpython/default/Lib/pathlib.py", line 851, in with_name
    raise ValueError("%r has an empty name" % (self,))
ValueError: PureWindowsPath('c:/') has an empty name

Nuevo en la versión 3.9.

PurePath.with_suffix(suffix)

Retorna una nueva ruta con suffix cambiado. Si la ruta original no tiene un sufijo, se agrega el nuevo suffix. Si suffix es una cadena vacía, el sufijo original se elimina:

>>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz')
>>> p.with_suffix('.bz2')
PureWindowsPath('c:/Downloads/pathlib.tar.bz2')
>>> p = PureWindowsPath('README')
>>> p.with_suffix('.txt')
PureWindowsPath('README.txt')
>>> p = PureWindowsPath('README.txt')
>>> p.with_suffix('')
PureWindowsPath('README')

Rutas concretas

Las rutas concretas son subclases de las rutas puras. Además de las operaciones proporcionadas por estas últimas, también proporcionan métodos realizar llamadas del sistema a objetos ruta. Hay tres formas de crear instancias de rutas concretas:

class pathlib.Path(*pathsegments)

Una subclase de PurePath, esta clase representa rutas concretas de la familia ruta del sistema (al crear una instancia crea ya sea PosixPath o WindowsPath):

>>> Path('setup.py')
PosixPath('setup.py')

pathsegments se especifica de manera similar a PurePath.

class pathlib.PosixPath(*pathsegments)

Una subclase de Path y PurePosixPath, esta clase representa rutas concretas de sistemas de archivos que no son de Windows:

>>> PosixPath('/etc')
PosixPath('/etc')

pathsegments se especifica de manera similar a PurePath.

class pathlib.WindowsPath(*pathsegments)

Una subclase de Path y PureWindowsPath, esta clase representa rutas concretas del sistema de archivos de Windows:

>>> WindowsPath('c:/Program Files/')
WindowsPath('c:/Program Files')

pathsegments se especifica de manera similar a PurePath.

Solo puedes crear instancias de la familia de clase que corresponde a su sistema operativo (permitir llamadas del sistema no compatibles podría provocar errores o fallas en su aplicación):

>>> import os
>>> os.name
'posix'
>>> Path('setup.py')
PosixPath('setup.py')
>>> PosixPath('setup.py')
PosixPath('setup.py')
>>> WindowsPath('setup.py')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "pathlib.py", line 798, in __new__
    % (cls.__name__,))
NotImplementedError: cannot instantiate 'WindowsPath' on your system

Métodos

Las rutas concretas proporcionan los siguientes métodos -además de los métodos de ruta puros-. Muchos de estos métodos pueden generar un OSError si falla una llamada al sistema (por ejemplo, porque la ruta no existe).

Distinto en la versión 3.8: exists(), is_dir(), is_file(), is_mount(), is_symlink(), is_block_device(), is_char_device(), is_fifo(), is_socket() ahora retorna `` False`` en lugar de generar una excepción para las rutas que contienen caracteres que no se pueden representar a nivel del sistema operativo.

classmethod Path.cwd()

Retorna un nuevo objeto ruta que representa el directorio actual (como lo retorna os.getcwd()):

>>> Path.cwd()
PosixPath('/home/antoine/pathlib')

classmethod Path.home()

Retorna un nuevo objeto ruta que representa el directorio de inicio del usuario (como lo retorna os.path.expanduser() con el agregado ~):

>>> Path.home()
PosixPath('/home/antoine')

Note that unlike os.path.expanduser(), on POSIX systems a KeyError or RuntimeError will be raised, and on Windows systems a RuntimeError will be raised if home directory can’t be resolved.

Nuevo en la versión 3.5.

Path.stat()

Retorna un objeto os.stat_result que contiene información sobre esta ruta, del mismo modo que os.stat(). El resultado se consulta en cada llamada a este método.

>>> p = Path('setup.py')
>>> p.stat().st_size
956
>>> p.stat().st_mtime
1327883547.852554

Path.chmod(mode)

Cambia el modo y los permisos de archivo, como os.chmod():

>>> p = Path('setup.py')
>>> p.stat().st_mode
33277
>>> p.chmod(0o444)
>>> p.stat().st_mode
33060

Path.exists()

Si la ruta apunta a un archivo o directorio existente:

>>> Path('.').exists()
True
>>> Path('setup.py').exists()
True
>>> Path('/etc').exists()
True
>>> Path('nonexistentfile').exists()
False

Nota

Si la ruta apunta a un enlace simbólico, exist() retorna si el enlace simbólico apunta a un archivo o directorio existente.

Path.expanduser()

Retorna una nueva ruta con las construcciones ~ y ~user expandidas, como lo retorna os.path.expanduser():

>>> p = PosixPath('~/films/Monty Python')
>>> p.expanduser()
PosixPath('/home/eric/films/Monty Python')

Note that unlike os.path.expanduser(), on POSIX systems a KeyError or RuntimeError will be raised, and on Windows systems a RuntimeError will be raised if home directory can’t be resolved.

Nuevo en la versión 3.5.

Path.glob(pattern)

Glob the given relative pattern in the directory represented by this path, yielding all matching files (of any kind):

>>> sorted(Path('.').glob('*.py'))
[PosixPath('pathlib.py'), PosixPath('setup.py'), PosixPath('test_pathlib.py')]
>>> sorted(Path('.').glob('*/*.py'))
[PosixPath('docs/conf.py')]

El patrón «**» significa «este directorio y todos los subdirectorios de forma recursiva». En otras palabras, habilita el comodín recursivo:

>>> sorted(Path('.').glob('**/*.py'))
[PosixPath('build/lib/pathlib.py'),
 PosixPath('docs/conf.py'),
 PosixPath('pathlib.py'),
 PosixPath('setup.py'),
 PosixPath('test_pathlib.py')]

Nota

El uso del patrón «**» en grandes árboles de directorios puede consumir una cantidad excesiva de tiempo.

Raises an auditing event pathlib.Path.glob with arguments self, pattern.

Path.group()

Retorna el nombre del grupo propietario del archivo. KeyError se genera si el gid del archivo no se encuentra en la base de datos del sistema.

Path.is_dir()

Retorna True si la ruta apunta a un directorio (o un enlace simbólico que apunta a un directorio), False si apunta a otro tipo de archivo.

False is also returned if the path doesn’t exist or is a broken symlink; other errors (such as permission errors) are propagated.

Path.is_file()

Retorna True si la ruta apunta a un archivo normal (o un enlace simbólico que apunta a un archivo normal), Falso si apunta a otro tipo de archivo.

False is also returned if the path doesn’t exist or is a broken symlink; other errors (such as permission errors) are propagated.

Path.is_mount()

Return True if the path is a mount point: a point in a file system where a different file system has been mounted. On POSIX, the function checks whether path’s parent, path/.., is on a different device than path, or whether path/.. and path point to the same i-node on the same device — this should detect mount points for all Unix and POSIX variants. Not implemented on Windows.

Nuevo en la versión 3.7.

Path.is_symlink()

Retorna True si la ruta apunta a un enlace simbólico, False de lo contrario.

`` False`` también se retorna si la ruta no existe; se extiende a otros errores (como errores de permiso).

Path.is_socket()

Retorna True si la ruta apunta a un socket Unix (o un enlace simbólico que apunta a uno), False si apunta a otro tipo de archivo.

False is also returned if the path doesn’t exist or is a broken symlink; other errors (such as permission errors) are propagated.

Path.is_fifo()

Retorna True si la ruta apunta a un FIFO (o un enlace simbólico que apunta a un FIFO), False si apunta a otro tipo de archivo.

False is also returned if the path doesn’t exist or is a broken symlink; other errors (such as permission errors) are propagated.

Path.is_block_device()

Retorna True si la ruta apunta a un dispositivo de bloques (o un enlace simbólico que apunta a uno), False si apunta a otro tipo de archivo.

False is also returned if the path doesn’t exist or is a broken symlink; other errors (such as permission errors) are propagated.

Path.is_char_device()

Retorna True si la ruta apunta a un dispositivo de caracteres (o un enlace simbólico que apunta a uno), False si apunta a otro tipo de archivo.

False is also returned if the path doesn’t exist or is a broken symlink; other errors (such as permission errors) are propagated.

Path.iterdir()

Cuando la ruta apunta a un directorio, produce objetos de ruta del contenido del directorio:

>>> p = Path('docs')
>>> for child in p.iterdir(): child
...
PosixPath('docs/conf.py')
PosixPath('docs/_templates')
PosixPath('docs/make.bat')
PosixPath('docs/index.rst')
PosixPath('docs/_build')
PosixPath('docs/_static')
PosixPath('docs/Makefile')

The children are yielded in arbitrary order, and the special entries '.' and '..' are not included. If a file is removed from or added to the directory after creating the iterator, whether a path object for that file be included is unspecified.

Path.lchmod(mode)

Del mismo modo que Path.chmod() pero si la ruta apunta a un enlace simbólico, el modo del enlace simbólico cambia en lugar del de su objetivo.

Path.lstat()

Del mismo modo que Path.stat() pero si la ruta apunta a un enlace simbólico, retorna la información del enlace simbólico en lugar de la de su objetivo.

Path.mkdir(mode=0o777, parents=False, exist_ok=False)

Crea un nuevo directorio en la ruta dada. Si se proporciona mode, se combina con el valor del proceso umask para determinar el modo de archivo y los derechos de acceso. Si la ruta ya existe, se genera FileExistsError.

Si parents es verdadero, los padres que faltan de esta ruta se crean según sea necesario; se crean con los permisos predeterminados sin tener en cuenta mode (imitando el comando POSIX mkdir -p).

Si parents es falso (el valor predeterminado), se genera un padre que falta FileNotFoundError.

Si exist_ok es falso (el valor predeterminado), se genera FileExistsError si el directorio de destino ya existe.

Si exist_ok es verdadero, se ignorarán las excepciones FileExistsError (el mismo comportamiento que el comando POSIX mkdir -p), pero solo si el último componente de ruta no es un archivo existente que no sea de directorio.

Distinto en la versión 3.5: Se agregó el parámetro exist_ok.

Path.open(mode='r', buffering=-1, encoding=None, errors=None, newline=None)

Abre el archivo señalado por la ruta, como lo hace la función incorporada open():

>>> p = Path('setup.py')
>>> with p.open() as f:
...     f.readline()
...
'#!/usr/bin/env python3\n'

Path.owner()

Retorna el nombre del usuario propietario del archivo. KeyError se genera si el uid del archivo no se encuentra en la base de datos del sistema.

Path.read_bytes()

Retorna el contenido binario del archivo apuntado como un objeto bytes:

>>> p = Path('my_binary_file')
>>> p.write_bytes(b'Binary file contents')
20
>>> p.read_bytes()
b'Binary file contents'

Nuevo en la versión 3.5.

Path.read_text(encoding=None, errors=None)

Retorna el contenido decodificado del archivo apuntado como una cadena:

>>> p = Path('my_text_file')
>>> p.write_text('Text file contents')
18
>>> p.read_text()
'Text file contents'

El archivo se abre y luego se cierra. Los parámetros opcionales funcionan de la misma manera que en open().

Nuevo en la versión 3.5.

Path.readlink()

Return the path to which the symbolic link points (as returned by os.readlink()):

>>> p = Path('mylink')
>>> p.symlink_to('setup.py')
>>> p.readlink()
PosixPath('setup.py')

Nuevo en la versión 3.9.

Path.rename(target)

Cambia el nombre del archivo o directorio apuntado al de target y retorna una nueva instancia de Path que apunte a target. En Unix, si target existe, es un archivo y el usuario tiene permisos, será reemplazado sin notificar. target puede ser una cadena u otro objeto ruta:

>>> p = Path('foo')
>>> p.open('w').write('some text')
9
>>> target = Path('bar')
>>> p.rename(target)
PosixPath('bar')
>>> target.open().read()
'some text'

The target path may be absolute or relative. Relative paths are interpreted relative to the current working directory, not the directory of the Path object.

Distinto en la versión 3.8: Valor de retorno agregado, retorna la nueva instancia de Path.

Path.replace(target)

Rename this file or directory to the given target, and return a new Path instance pointing to target. If target points to an existing file or empty directory, it will be unconditionally replaced.

The target path may be absolute or relative. Relative paths are interpreted relative to the current working directory, not the directory of the Path object.

Distinto en la versión 3.8: Valor de retorno agregado, retorna la nueva instancia de Path.

Path.resolve(strict=False)

Hace que la ruta sea absoluta, resolviendo los enlaces simbólicos. Se retorna un nuevo objeto ruta:

>>> p = Path()
>>> p
PosixPath('.')
>>> p.resolve()
PosixPath('/home/antoine/pathlib')

Los componentes «..» también se eliminan (este es el único método para hacerlo):

>>> p = Path('docs/../setup.py')
>>> p.resolve()
PosixPath('/home/antoine/pathlib/setup.py')

Si la ruta no existe y strict es True, se genera FileNotFoundError. Si strict es False, la ruta se resuelve en la medida de lo posible y se agrega el resto sin verificar si existe. Si se encuentra un bucle infinito en la resolución de la ruta se genera RuntimeError.

Nuevo en la versión 3.6: The strict argument (pre-3.6 behavior is strict).

Path.rglob(pattern)

Idéntico a llamar a Path.glob() con «**/» agregado delante del pattern relativo:

>>> sorted(Path().rglob("*.py"))
[PosixPath('build/lib/pathlib.py'),
 PosixPath('docs/conf.py'),
 PosixPath('pathlib.py'),
 PosixPath('setup.py'),
 PosixPath('test_pathlib.py')]

Raises an auditing event pathlib.Path.rglob with arguments self, pattern.

Path.rmdir()

Elimina el directorio. El directorio debe estar vacío.

Path.samefile(other_path)

Retorna si la ruta apunta al mismo archivo que other_path, que puede ser un objeto Path o una cadena. La semántica es similar a os.path.samefile() y os.path.samestat().

Se puede generar OSError si no se accede a alguno de los archivos por algún motivo.

>>> p = Path('spam')
>>> q = Path('eggs')
>>> p.samefile(q)
False
>>> p.samefile('spam')
True

Nuevo en la versión 3.5.

Path.symlink_to(target, target_is_directory=False)

Hace de la ruta un enlace simbólico a target. En Windows, target_is_directory debe ser verdadero si el destino del enlace es un directorio (False es predeterminado). En POSIX, el valor de target_is_directory se ignora.

>>> p = Path('mylink')
>>> p.symlink_to('setup.py')
>>> p.resolve()
PosixPath('/home/antoine/pathlib/setup.py')
>>> p.stat().st_size
956
>>> p.lstat().st_size
8

Nota

El orden de los argumentos (link, target) es el reverso de os.symlink()”s.

Path.link_to(target)

Make target a hard link to this path.

Advertencia

This function does not make this path a hard link to target, despite the implication of the function and argument names. The argument order (target, link) is the reverse of Path.symlink_to(), but matches that of os.link().

Nuevo en la versión 3.8.

Path.touch(mode=0o666, exist_ok=True)

Crea un archivo en la ruta dada. Si se proporciona mode, se combina con el valor del proceso umask para determinar el modo de archivo y los indicadores de acceso. Si el archivo ya existe, la función tiene éxito si exist_ok es verdadero (y su hora de modificación se actualiza a la hora actual), de lo contrario se genera FileExistsError.

Path.unlink(missing_ok=False)

Elimine el archivo o enlace simbólico. Si la ruta apunta a un directorio, use Path.rmdir() en su lugar.

Si missing_ok es falso (el valor predeterminado), se genera FileNotFoundError si la ruta no existe.

Si missing_ok es verdadero, las excepciones FileNotFoundError serán ignoradas (el mismo comportamiento que el comando POSIX rm -f).

Distinto en la versión 3.8: Se agregó el parámetro missing_ok.

Path.write_bytes(data)

Abre el archivo apuntado en modo bytes, escribe data y cierra el archivo:

>>> p = Path('my_binary_file')
>>> p.write_bytes(b'Binary file contents')
20
>>> p.read_bytes()
b'Binary file contents'

Se sobrescribe un archivo existente con el mismo nombre.

Nuevo en la versión 3.5.

Path.write_text(data, encoding=None, errors=None)

Abre el archivo apuntado en modo texto, escribe data y cierra el archivo:

>>> p = Path('my_text_file')
>>> p.write_text('Text file contents')
18
>>> p.read_text()
'Text file contents'

Se sobrescribe un archivo existente con el mismo nombre. Los parámetros opcionales tienen el mismo significado que en open().

Nuevo en la versión 3.5.

Correspondencia a herramientas en el módulo os

A continuación se muestra una tabla que asigna varias funciones os a sus equivalentes en PurePath/Path.

Nota

Aunque os.path.relpath() y PurePath.relative_to() tienen algunos casos de uso superpuestos, su semántica difiere lo suficiente como para justificar no considerarlos equivalentes.

os y os.path

pathlib

os.path.abspath()

Path.resolve()

os.chmod()

Path.chmod()

os.mkdir()

Path.mkdir()

os.makedirs()

Path.mkdir()

os.rename()

Path.rename()

os.replace()

Path.replace()

os.rmdir()

Path.rmdir()

os.remove(), os.unlink()

Path.unlink()

os.getcwd()

Path.cwd()

os.path.exists()

Path.exists()

os.path.expanduser()

Path.expanduser() y Path.home()

os.listdir()

Path.iterdir()

os.path.isdir()

Path.is_dir()

os.path.isfile()

Path.is_file()

os.path.islink()

Path.is_symlink()

os.link()

Path.link_to()

os.symlink()

Path.symlink_to()

os.readlink()

Path.readlink()

os.stat()

Path.stat(), Path.owner(), Path.group()

os.path.isabs()

PurePath.is_absolute()

os.path.join()

PurePath.joinpath()

os.path.basename()

PurePath.name

os.path.dirname()

PurePath.parent

os.path.samefile()

Path.samefile()

os.path.splitext()

PurePath.suffix

os.path — Manipulaciones comunes de nombre de ruta

Source code: Lib/posixpath.py [https://github.com/python/cpython/tree/3.9/Lib/posixpath.py] (for POSIX) and Lib/ntpath.py [https://github.com/python/cpython/tree/3.9/Lib/ntpath.py] (for Windows).

This module implements some useful functions on pathnames. To read or write files see open(), and for accessing the filesystem see the os module. The path parameters can be passed as strings, or bytes, or any object implementing the os.PathLike protocol.

A diferencia de un shell Unix, Python no realiza ninguna expansión de ruta automática. Las funciones como expanduser() y expandvars() puede ser invocadas de manera explicita cuando una aplicación desea realizar una expansión de ruta shell-like. (Consulta el módulo glob)

Ver también

El módulo pathlib ofrece objetos de ruta de alto nivel.

Nota

Todas estas funciones aceptan solo bytes o solo objetos de cadena como sus parámetros. El resultado es un objeto del mismo tipo, si se retorna una ruta o un nombre de archivo.

Nota

Dado que los diferentes sistemas operativos tienen diferentes convenciones de nombres de ruta, existen varias versiones de este módulo en la librería estándar. El módulo os.path siempre es el módulo adecuado para el sistema operativo en el cual Python está operando, y por lo tanto es utilizable para rutas locales. Sin embargo, también puedes importar y utilizar los módulos individuales si deseas manipular una ruta que siempre está en uno de los diferentes formatos. Todos tienen la misma interfaz:

posixpath para rutas con estilo UNIX

ntpath para rutas Windows

Distinto en la versión 3.8: exists(), lexists(), isdir(), isfile(), islink(), y ismount() ahora retornan False en lugar de lanzar una excepción para rutas que contienen caracteres o bytes que no se puedan representar a nivel de sistema operativo.

os.path.abspath(path)

Retorna una versión normalizada y absoluta del nombre de ruta path. En la mayoría de las plataformas esto es el equivalente a invocar la función normpath`de la siguiente manera: ``normpath(join(os.getcwd(), path))`().

Distinto en la versión 3.6: Acepta un path-like object.

os.path.basename(path)

Retorna un nombre base de nombre de ruta path. Este es el segundo elemento del par retornado al pasar path a la función split(). Toma en cuenta que el resultado de esta función es diferente a la del programa de Unix basename; donde basename para '/foo/bar/' retorna 'bar', la función basename() retorna una cadena vacía ('').

Distinto en la versión 3.6: Acepta un path-like object.

os.path.commonpath(paths)

Retorna la sub-ruta común más larga de cada nombre de ruta en la secuencia paths. Lanza una excepción ValueError si paths contiene nombres de ruta absolutos y relativos, o los paths están en discos diferentes o si paths está vacío. A diferencia de commonprefix(), retorna una ruta valida.

Availability: Unix, Windows.

Nuevo en la versión 3.5.

Distinto en la versión 3.6: Acepta una secuencia de path-like objects.

os.path.commonprefix(list)

Retorna el prefijo de ruta más largo (tomado carácter por carácter) que es un prefijo de todas las rutas en list. Si list está vacía, retorna la cadena vacía ('').

Nota

Esta función puede que retorne rutas invalidas porque trabaja un carácter a la vez. Para obtener una ruta valida, consulta commonpath().

>>> os.path.commonprefix(['/usr/lib', '/usr/local/lib'])
'/usr/l'

>>> os.path.commonpath(['/usr/lib', '/usr/local/lib'])
'/usr'

Distinto en la versión 3.6: Acepta un path-like object.

os.path.dirname(path)

Retorna el nombre del directorio de la ruta path. Es el primer elemento del par retornado al pasar path a la función split().

Distinto en la versión 3.6: Acepta un path-like object.

os.path.exists(path)

Retorna True si path se refiere a una ruta existente o un descriptor de archivo abierto. Retorna False para enlaces simbólicos rotos. En algunas plataformas, esta función puede retornar False si no se concede permiso para ejecutar os.stat() en el archivo solicitado, incluso la ruta path existe físicamente.

Distinto en la versión 3.3: path ahora puede ser un valor entero: retorna True si es un descriptor de archivo abierto, de otro modo retorna False.

Distinto en la versión 3.6: Acepta un path-like object.

os.path.lexists(path)

Retorna True si path se refiere a un camino existente. Retorna True para los enlaces simbólicos rotos. Equivalente a exists() en plataformas que carecen de os.lstat().

Distinto en la versión 3.6: Acepta un path-like object.

os.path.expanduser(path)

En Unix y Windows, retorna el argumento con un componente inicial de ~ o ~user reemplazado por el directorio home de user.

En Unix, el ~ inicial es reemplazado por la variable de entorno HOME si está activada; si no, el directorio principal del usuario actual se busca en el directorio de contraseñas a través del módulo incorporado pwd. Un ~user inicial es buscado directamente en el directorio de contraseñas.

En Windows, se usará USERPROFILE si está configurado, si no, se usará una combinación de HOMEPATH y HOMEDRIVE . Un ~user` inicial se maneja quitando el último componente del directorio de la ruta de usuario creada derivada arriba.

Si la expansión falla o si la ruta no comienza con una tilde, la ruta se retorna sin cambios.

Distinto en la versión 3.6: Acepta un path-like object.

Distinto en la versión 3.8: Ya no utiliza HOME en Windows.

os.path.expandvars(path)

Retorna el argumento con variables de entorno expandidas. Las sub-cadenas de la forma $name or ${name} se reemplazan por el valor de la variable de entorno name. Los nombres de variables mal formadas y las referencias a variables no existentes se dejan sin cambios.

En Windows, las expansiones %name% están soportadas además de $name y ${name}.

Distinto en la versión 3.6: Acepta un path-like object.

os.path.getatime(path)

Retorna la hora del último acceso de path. El valor de retorno es un número de punto flotante que da el número de segundos desde la época (Consulta el módulo time). Lanza una excepción OSError si el archivo no existe o es inaccesible.

os.path.getmtime(path)

Retorna el tiempo de la última modificación de path. El valor de retorno es un número de punto flotante que da el número de segundos desde la época (consulta el módulo time). lanza una excepción OSError si el archivo no existe o es inaccesible.

Distinto en la versión 3.6: Acepta un path-like object.

os.path.getctime(path)

Retorna el ctime del sistema que, en algunos sistemas (como Unix) es la hora del último cambio de metadatos y, en otros (como Windows), es el tiempo de creación de path. El valor retornado es un número que da el número de segundos desde la época (consulta el módulo time). Lanza una excepción OSError si el archivo no existe o es inaccesible.

Distinto en la versión 3.6: Acepta un path-like object.

os.path.getsize(path)

Retorna el tamaño en bytes de path, Lanza una excepción OSError si el archivo no existe o es inaccesible.

Distinto en la versión 3.6: Acepta un path-like object.

os.path.isabs(path)

Retorna True si path es un nombre de ruta de acceso absoluto. En Unix, eso significa que comienza con una barra diagonal, en Windows que comienza con una barra diagonal (invertida) después de cortar una letra de unidad potencial.

Distinto en la versión 3.6: Acepta un path-like object.

os.path.isfile(path)

Retorna True si path es un archivo existing. Esto sigue los enlaces simbólicos, por lo que tanto islink() como isfile() pueden ser verdaderos para la misma ruta.

Distinto en la versión 3.6: Acepta un path-like object.

os.path.isdir(path)

Retorna True si path es un directorio existing. Esto sigue los enlaces simbólicos, por lo que tanto islink() como isdir() pueden ser verdaderos para la misma ruta.

Distinto en la versión 3.6: Acepta un path-like object.

os.path.islink(path)

Retorna True si path hace referencia a una entrada de directorio existing que es un enlace simbólico. Siempre False si el entorno de ejecución de Python no admite vínculos simbólicos..

Distinto en la versión 3.6: Acepta un path-like object.

os.path.ismount(path)

Retorna True si el nombre de ruta path es un mount point: un punto en un sistema de archivos donde se ha montado un sistema de archivos diferente. En POSIX, la función comprueba si el elemento primario de path, path/.., se encuentra en un dispositivo diferente de path, o si path/.. y path apuntan al mismo i-node en el mismo dispositivo — esto debería detectar puntos de montaje para todas las variantes Unix y POSIX. No es capaz de detectar de forma fiable los montajes de enlace en el mismo sistema de archivos. En Windows, una raíz de letra de unidad y un recurso compartido UNC siempre son puntos de montaje, y para cualquier otra ruta de acceso GetVolumePathName se llama para ver si es diferente de la ruta de acceso de entrada.

Nuevo en la versión 3.4: Soporte para detectar puntos de montaje non-root en Windows.

Distinto en la versión 3.6: Acepta un path-like object.

os.path.join(path, *paths)

Join one or more path components intelligently. The return value is the concatenation of path and any members of *paths with exactly one directory separator following each non-empty part except the last, meaning that the result will only end in a separator if the last part is empty. If a component is an absolute path, all previous components are thrown away and joining continues from the absolute path component.

En Windows, la letra de la unidad no se restablece cuando se encuentra un componente de ruta absoluta (por ejemplo, r'\foo'). Si un componente contiene una letra de unidad, todos los componentes anteriores se desechan y la letra de unidad se restablece. Ten en cuenta que, dado que hay un directorio actual para cada unidad, `` os.path.join («c:», «foo») `` representa una ruta relativa al directorio actual en la unidad C: (c:foo),, no c:\foo.

Distinto en la versión 3.6: Acepta un objeto path-like object para path y paths.

os.path.normcase(path)

Normaliza las mayúsculas y minúsculas de un nombre de ruta. En Windows convierte todos los caracteres en el nombre de ruta a minúsculas y también convierte las barras inclinadas hacia atrás en barras inclinadas hacia atrás. En otros sistemas operativos, retorna la ruta sin cambios.

Distinto en la versión 3.6: Acepta un path-like object.

os.path.normpath(path)

Normaliza un nombre de ruta colapsando separadores redundantes y referencias de nivel superior para que A//B, A/B/, A/./B y A/foo/../B se transformen en``A/B``. Esta modificación de cadena puede que modifique el significado de la ruta que contenga enlaces simbólicos. En Windows, convierte las barras inclinadas hacia adelante en barras hacia atrás. Para normalizar mayúsculas y minúsculas, utiliza normcase().

Nota

On POSIX systems, in accordance with IEEE Std 1003.1 2013 Edition; 4.13 Pathname Resolution [http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_13], if a pathname begins with exactly two slashes, the first component following the leading characters may be interpreted in an implementation-defined manner, although more than two leading characters shall be treated as a single character.

Distinto en la versión 3.6: Acepta un path-like object.

os.path.realpath(path)

Retorna la ruta canónica del nombre de archivo especificado, eliminando cualquier enlace simbólico encontrado en la ruta (si es que tienen soporte por el sistema operativo).

Nota

Cuando ocurren ciclos de enlaces simbólicos, la ruta retornada será un miembro del ciclo, pero no se garantiza cuál miembro será.

Distinto en la versión 3.6: Acepta un path-like object.

Distinto en la versión 3.8: Los enlaces y uniones simbólicos ahora se resuelven en Windows.

os.path.relpath(path, start=os.curdir)

Return a relative filepath to path either from the current directory or from an optional start directory. This is a path computation: the filesystem is not accessed to confirm the existence or nature of path or start. On Windows, ValueError is raised when path and start are on different drives.

start toma de forma predeterminada el valor de os.curdir.

Availability: Unix, Windows.

Distinto en la versión 3.6: Acepta un path-like object.

os.path.samefile(path1, path2)

Retorna True si ambos argumentos de nombre de ruta refieren al mismo archivo o directorio. Esto se determina por el número de dispositivo y el número de i-node y lanza una excepción si una llamada de os.stat() en alguno de los nombres de ruta falla.

Availability: Unix, Windows.

Distinto en la versión 3.2: Añadido soporte para Windows.

Distinto en la versión 3.4: Windows ahora utiliza la misma implementación que en el resto de las plataformas.

Distinto en la versión 3.6: Acepta un path-like object.

os.path.sameopenfile(fp1, fp2)

Retorna True si los descriptores de archivo fp1 y fp2 se refieren al mismo archivo.

Availability: Unix, Windows.

Distinto en la versión 3.2: Añadido soporte para Windows.

Distinto en la versión 3.6: Acepta un path-like object.

os.path.samestat(stat1, stat2)

Retorna True si las tuplas de stat (stat1 y stat2) refieren al mismo archivo. Estas estructuras pueden haber sido retornadas por os.fstat(), os.lstat(), o os.stat(). Esta función implementa la comparación subyacente utilizada por: samefile() y sameopenfile().

Availability: Unix, Windows.

Distinto en la versión 3.4: Añadido soporte para Windows.

Distinto en la versión 3.6: Acepta un path-like object.

os.path.split(path)

Divide el nombre de la ruta path * en un par, `` (head, tail) `` donde *tail es el último componente del nombre de la ruta y head es todo lo que conduce a eso. La parte head nunca contendrá una barra; si head termina en una barra, tail estará vacía. Si no hay barra inclinada en path, head estará vacío. Si path está vacía, tanto head como tail estarán vacíos. Las barras diagonales finales se eliminan de head a menos que sea la raíz (solo una o más barras). En todos los casos, join(head, tail) retorna una ruta a la misma ubicación que path (pero las cadenas pueden diferir). Consulta las funciones dirname() y basename().

Distinto en la versión 3.6: Acepta un path-like object.

os.path.splitdrive(path)

Divide el nombre de ruta path en un par (drive, tail) donde drive es un punto de montaje o una cadena vacía. En sistemas que no utilizan especificaciones de unidad, drive siempre será una cadena vacía. En todos los casos, drive + tail será lo mismo que path.

En Windows, divide un nombre de ruta en unidad / punto compartido UNC y ruta relativa.

If the path contains a drive letter, drive will contain everything up to and including the colon:

>>> splitdrive("c:/dir")
("c:", "/dir")

If the path contains a UNC path, drive will contain the host name and share, up to but not including the fourth separator:

>>> splitdrive("//host/computer/dir")
("//host/computer", "/dir")

Distinto en la versión 3.6: Acepta un path-like object.

os.path.splitext(path)

Split the pathname path into a pair (root, ext) such that root + ext == path, and the extension, ext, is empty or begins with a period and contains at most one period.

If the path contains no extension, ext will be '':

>>> splitext('bar')
('bar', '')

If the path contains an extension, then ext will be set to this extension, including the leading period. Note that previous periods will be ignored:

>>> splitext('foo.bar.exe')
('foo.bar', '.exe')
>>> splitext('/foo/bar.exe')
('/foo/bar', '.exe')

Leading periods of the last component of the path are considered to be part of the root:

>>> splitext('.cshrc')
('.cshrc', '')
>>> splitext('/foo/....jpg')
('/foo/....jpg', '')

Distinto en la versión 3.6: Acepta un path-like object.

os.path.supports_unicode_filenames

True si se pueden utilizar cadenas Unicode arbitrarias como nombres de archivo (dentro de las limitaciones impuestas por el sistema de archivos).

fileinput — Iterar sobre líneas de múltiples flujos de entrada

Código fuente: Lib/fileinput.py [https://github.com/python/cpython/tree/3.9/Lib/fileinput.py]

Este módulo implementa una clase auxiliar y funciones para escribir rápidamente un bucle sobre una entrada estándar o una lista de archivos. Si solo quiere leer o escribir un archivo, vea open().

El uso común es:

import fileinput
for line in fileinput.input():
    process(line)

Esto itera sobre las líneas de todos los archivos enumerados en sys.argv[1:], por defecto a sys.stdin``si la lista está vacía. Si un nombre de archivo es ``'-', también se reemplaza por sys.stdin y los argumentos opcionales mode y openhook se ignoran. Para especificar una lista alternativa de nombres de archivo, se pasa como primer argumento a input(). También se permite un único nombre de archivo.

Todos los archivos se abren en modo texto de manera predeterminada, pero puede anular esto especificando el parámetro mode en la llamada a input() o FileInput. Si se produce un error de E/S durante la apertura o lectura de un archivo, se lanza OSError.

Distinto en la versión 3.3: IOError solía ser lanzado; ahora es un alias de OSError.

Si sys.stdin se usa más de una vez, el segundo y siguientes usos no retornarán líneas, excepto tal vez para uso interactivo, o si se ha reiniciado explícitamente (por ejemplo, usando sys.stdin.seek(0)).

Los archivos vacíos se abren e inmediatamente se cierran; la única vez que su presencia en la lista de nombres de archivo es notable es cuando el último archivo abierto está vacío.

Las líneas se retornan con cualquier nueva línea intacta, lo que significa que la última línea en un archivo puede no tener una.

Puede controlar cómo se abren los archivos proporcionando un enlace de apertura a través del parámetro openhook a fileinput.input() o FileInput(). El enlace debe ser una función que tome dos argumentos, filename y mode, y retorna un objeto similar a un archivo abierto. Este módulo ya proporciona dos enlaces útiles.

La siguiente función es la interfaz principal de este módulo:

fileinput.input(files=None, inplace=False, backup='', *, mode='r', openhook=None)

Crea una instancia de la clase FileInput. La instancia se usará como estado global para las funciones de este módulo y también se volverá a usar durante la iteración. Los parámetros de esta función se pasarán al constructor de la clase FileInput.

La instancia FileInput se puede usar como gestor de contexto en la declaración with. En este ejemplo, input se cierra después de salir de la instrucción with, incluso si se produce una excepción:

with fileinput.input(files=('spam.txt', 'eggs.txt')) as f:
    for line in f:
        process(line)

Distinto en la versión 3.2: Se puede usar como gestor de contexto.

Distinto en la versión 3.8: Los parámetros de palabras clave mode y openhook ahora son solo palabras clave.

Las siguientes funciones utilizan el estado global creado por fileinput.input(); si no hay estado activo, es lanzado RuntimeError.

fileinput.filename()

Retorna el nombre del archivo que se está leyendo actualmente. Antes de leer la primera línea, retorna None.

fileinput.fileno()

Retorna el entero «file descriptor» para el archivo actual. Cuando no se abre ningún archivo (antes de la primera línea y entre archivos), retorna -1.

fileinput.lineno()

Retorna el número de línea acumulativa de la línea que se acaba de leer. Antes de que se haya leído la primera línea, retorna 0. Después de leer la última línea del último archivo, retorna el número de línea de esa línea.

fileinput.filelineno()

Retorna el número de línea en el archivo actual. Antes de que se haya leído la primera línea, retorna 0. Después de leer la última línea del último archivo, retorna el número de línea de esa línea dentro del archivo.

fileinput.isfirstline()

Retorna True si la línea que acaba de leer es la primera línea de su archivo; de lo contrario, retorna False.

fileinput.isstdin()

Retorna True si la última línea se leyó de sys.stdin, de lo contrario, retorna False.

fileinput.nextfile()

Cierra el archivo actual para que la próxima iteración lea la primera línea del siguiente archivo (si corresponde); las líneas no leídas del archivo no contarán para el recuento de líneas acumuladas. El nombre del archivo no se cambia hasta que se haya leído la primera línea del siguiente archivo. Antes de que se haya leído la primera línea, esta función no tiene efecto; no se puede usar para omitir el primer archivo. Después de leer la última línea del último archivo, esta función no tiene efecto.

fileinput.close()

Cierra la secuencia.

La clase que implementa el comportamiento de secuencia proporcionado por el módulo también está disponible para la subclasificación:

class fileinput.FileInput(files=None, inplace=False, backup='', *, mode='r', openhook=None)

La Clase FileInput es la implementación; sus métodos filename(), fileno(), lineno(), filelineno(), isfirstline(), isstdin(), nextfile() and close() corresponden a las funciones del mismo nombre en el módulo. Además tiene un método readline() que retorna la siguiente línea de entrada, y un método __getitem__() que implementa el comportamiento de secuencia. Se debe acceder a la secuencia en orden estrictamente secuencial; acceso aleatorio y readline() no se pueden mezclar.

Con mode puede especificar a qué modo de archivo se pasará open(). Debe ser uno de 'r', 'rU', 'U' and 'rb'.

El openhook, cuando se proporciona, debe ser una función que tome dos argumentos, filename y mode, y retorne un objeto similar a un archivo abierto en consecuencia. No puede usar inplace y openhook juntos.

Una instancia FileInput se puede usar como gestor de contexto en la instrucción with. En este ejemplo, input se cierra después de salir de la palabra clave:!with, incluso si se produce una excepción:

with FileInput(files=('spam.txt', 'eggs.txt')) as input:
    process(input)

Distinto en la versión 3.2: Se puede usar como gestor de contexto.

Obsoleto desde la versión 3.4: Los modos 'rU' and 'U'.

Obsoleto desde la versión 3.8: Soporte para el método __getitem__() está discontinuado.

Distinto en la versión 3.8: El parámetro de palabra clave mode y openhook ahora son solo palabras clave.

Filtrado al instante opcional: si el argumento de la palabra clave inplace=True se pasa a fileinput.input() o al constructor FileInput, el archivo se mueve a una copia de seguridad y la salida estándar es dirigida al archivo de entrada (si ya existe un archivo con el mismo nombre que el archivo de copia de seguridad, se reemplazará en silencio). Esto hace posible escribir un filtro que reescribe su archivo de entrada en su lugar. Si se proporciona el parámetro backup (generalmente como backup='.<some extension>'), este especifica la extensión para el archivo de respaldo y el archivo de respaldo permanece; de forma predeterminada, la extensión es '.bak' y se elimina cuando se cierra el archivo de salida. El filtrado en el lugar se desactiva cuando se lee la entrada estándar.

Este módulo proporciona los dos enlaces de apertura siguientes:

fileinput.hook_compressed(filename, mode)

Abre de forma transparente archivos comprimidos con gzip y bzip2 (reconocidos por las extensiones '.gz' and '.bz2') utilizando los módulos gzip y bz2. Si la extensión del nombre de archivo no es '.gz' or '.bz2', el archivo se abre normalmente (es decir, usando open() sin descompresión).

Ejemplo de uso: fi = fileinput.FileInput(openhook=fileinput.hook_compressed)

fileinput.hook_encoded(encoding, errors=None)

Retorna un enlace que abre cada archivo con open(), usando el encoding y errors dados para leer el archivo.

Ejemplo de uso: fi = fileinput.FileInput(openhook=fileinput.hook_encoded("utf-8", "surrogateescape"))

Distinto en la versión 3.6: Se agregó el parámetro opcional errors.

stat — Interpretación de los resultados de stat()

Código fuente: Lib/stat.py [https://github.com/python/cpython/tree/3.9/Lib/stat.py]

El módulo stat define constantes y funciones para interpretar los resultados de os.stat(), os.fstat() y os.lstat() (si existen). Para obtener los detalles completos sobre las llamadas a stat(), fstat() y lstat(), consulta la documentación de tu sistema.

Distinto en la versión 3.4: El módulo stat se apoya en una implementación en C.

El módulo stat define las siguientes funciones para comprobar tipos de archivo específicos:

stat.S_ISDIR(mode)

Retorna un valor no nulo si el modo es de un directorio.

stat.S_ISCHR(mode)

Retorna un valor no nulo si el modo es de un archivo de un dispositivo especial de caracteres.

stat.S_ISBLK(mode)

Retorna un valor no nulo si el modo es de un archivo de un dispositivo especial de bloques.

stat.S_ISREG(mode)

Retorna un valor no nulo si el modo es de un archivo normal.

stat.S_ISFIFO(mode)

Retorna un valor no nulo si el modo es de un FIFO (tubería con nombre).

stat.S_ISLNK(mode)

Retorna un valor no nulo si el modo es de un enlace simbólico.

stat.S_ISSOCK(mode)

Retorna un valor no nulo si el modo es de un socket.

stat.S_ISDOOR(mode)

Retorna un valor no nulo si el modo es de un door.

Nuevo en la versión 3.4.

stat.S_ISPORT(mode)

Retorna un valor no nulo si el modo es de un event port.

Nuevo en la versión 3.4.

stat.S_ISWHT(mode)

Retorna un valor no nulo si el modo es de un whiteout.

Nuevo en la versión 3.4.

Se definen dos funciones adicionales para una manipulación más general del modo del archivo:

stat.S_IMODE(mode)

Retorna la porción del modo del archivo que puede ser establecida por os.chmod()— esto es, los bits de los permisos del archivo más los bits sticky bit, set-group-id y set-user-id (en los sistemas que lo soporten).

stat.S_IFMT(mode)

Retorna la porción del modo del archivo que describe el tipo de archivo (usado por las funciones S_IS*() de más arriba).

Normalmente se usarían las funciones os.path.is*() para comprobar el tipo de un archivo; estas funciones de aquí son útiles cuando se hacen múltiples comprobaciones sobre el mismo archivo y se desea evitar la sobrecarga causada por la llamada al sistema stat() en cada comprobación. También son útiles cuando se comprueba información de un archivo que no es gestionada por os.path, como buscar dispositivos de bloques o caracteres.

Ejemplo:

import os, sys
from stat import *

def walktree(top, callback):
    '''recursively descend the directory tree rooted at top,
       calling the callback function for each regular file'''

    for f in os.listdir(top):
        pathname = os.path.join(top, f)
        mode = os.lstat(pathname).st_mode
        if S_ISDIR(mode):
            # It's a directory, recurse into it
            walktree(pathname, callback)
        elif S_ISREG(mode):
            # It's a file, call the callback function
            callback(pathname)
        else:
            # Unknown file type, print a message
            print('Skipping %s' % pathname)

def visitfile(file):
    print('visiting', file)

if __name__ == '__main__':
    walktree(sys.argv[1], visitfile)

Se proporciona una función de utilidad adicional para convertir el modo del archivo en una cadena de caracteres legible por humanos:

stat.filemode(mode)

Convierte el modo del archivo a una cadena de caracteres de la forma “-rwxrwxrwx”.

Nuevo en la versión 3.3.

Distinto en la versión 3.4: La función soporta S_IFDOOR, S_IFPORT y S_IFWHT.

Todas las variables de debajo son simplemente índices simbólicos sobre la tupla de 10 elementos retornada por os.stat(), os.fstat() o os.lstat().

stat.ST_MODE

Modo de protección del inode.

stat.ST_INO

Número del inode.

stat.ST_DEV

Dispositivo en el que reside el inode.

stat.ST_NLINK

Número de enlaces al inode.

stat.ST_UID

Id de usuario del propietario.

stat.ST_GID

Id del grupo del propietario.

stat.ST_SIZE

Tamaño en bytes de un archivo normal; cantidad de datos esperando en algunos archivos especiales.

stat.ST_ATIME

Momento del último acceso.

stat.ST_MTIME

Momento de la última modificación.

stat.ST_CTIME

El «ctime» reportado por el sistema operativo. En algunos sistemas (como Unix) es el momento del último cambio en los metadatos, y en otros (como Windows), es el momento de creación (véase la documentación de la plataforma para más detalles).

La interpretación de «tamaño de archivo» cambia dependiendo del tipo de archivo. Para archivos normales es el tamaño del archivo en bytes. En la mayoría de sistemas Unix (incluyendo Linux en particular), para FIFOs y sockets es el número de bytes que esperan ser leídos en el momento de la llamada a os.stat(), os.fstat(), o os.lstat(); en ocasiones, esto puede ser útil, especialmente para sondear uno de estos archivos especiales después de una apertura no bloqueante. Para otros dispositivos de caracteres y bloques el significado del campo size es más variado, dependiendo de la implementación de la llamada al sistema subyacente.

Las variables de debajo definen los flags usados en el campo ST_MODE.

El uso de las funciones de arriba es más portable que el uso del primer juego de flags:

stat.S_IFSOCK

Socket.

stat.S_IFLNK

Enlace simbólico.

stat.S_IFREG

Archivo normal.

stat.S_IFBLK

Dispositivo de bloques.

stat.S_IFDIR

Directorio.

stat.S_IFCHR

Dispositivo de caracteres.

stat.S_IFIFO

FIFO.

stat.S_IFDOOR

Door.

Nuevo en la versión 3.4.

stat.S_IFPORT

Event port.

Nuevo en la versión 3.4.

stat.S_IFWHT

Whiteout.

Nuevo en la versión 3.4.

Nota

S_IFDOOR, S_IFPORT o S_IFWHT se definen como 0 cuando la plataforma no soporta los tipos de archivo.

Los siguientes flags también pueden usarse en el argumento mode de os.chmod():

stat.S_ISUID

Establecer el bit UID.

stat.S_ISGID

Bit Set-group-ID. Este bit tiene varios usos especiales. Para un directorio indica que la semántica BSD debe usarse para ese directorio: los archivos creados ahí heredan el ID de grupo del directorio, no del ID de grupo efectivo del proceso que los crea, y los directorios creados ahí también tendrán activado el bit S_ISGID. Para un archivo que no tiene activado el bit de ejecución de grupo (S_IXGRP), el bit Set-group-ID indica el bloqueo obligatorio del archivo/registro (véase también S_ENFMT).

stat.S_ISVTX

Sticky bit. Cuando este bit está activado en un directorio, significa que un archivo dentro de ese directorio puede ser renombrado o borrado sólo por el propietario del archivo, por el propietario del directorio, o por un proceso con privilegios.

stat.S_IRWXU

Máscara para los permisos del propietario del archivo.

stat.S_IRUSR

El propietario tiene permiso de lectura.

stat.S_IWUSR

El propietario tiene permiso de escritura.

stat.S_IXUSR

El propietario tiene permiso de ejecución.

stat.S_IRWXG

Máscara para los permisos del grupo.

stat.S_IRGRP

El grupo tiene permiso de lectura.

stat.S_IWGRP

El grupo tiene permiso de escritura.

stat.S_IXGRP

El grupo tiene permiso de ejecución.

stat.S_IRWXO

Máscara para permisos de los otros (no en el grupo).

stat.S_IROTH

Los otros tienen permiso de lectura.

stat.S_IWOTH

Los otros tienen permiso de escritura.

stat.S_IXOTH

Los otros tienen permiso de ejecución.

stat.S_ENFMT

Imposición del bloqueo de archivos de System V. Este flag se comparte con S_ISGID: se impone el bloqueo de archivos/registros en archivos que no tengan activado el bit de ejecución por el grupo (S_IXGRP).

stat.S_IREAD

Sinónimo de S_IRUSR en Unix V7.

stat.S_IWRITE

Sinónimo de S_IWUSR en Unix V7.

stat.S_IEXEC

Sinónimo de S_IXUSR en Unix V7.

Los siguientes flags pueden usarse como argumento flags de os.chflags():

stat.UF_NODUMP

No volcar el archivo.

stat.UF_IMMUTABLE

El archivo no puede ser modificado.

stat.UF_APPEND

Sólo se puede añadir al archivo.

stat.UF_OPAQUE

El directorio es opaco cuando se mira a través de un union stack.

stat.UF_NOUNLINK

El archivo no puede ser renombrado o borrado.

stat.UF_COMPRESSED

The file is stored compressed (macOS 10.6+).

stat.UF_HIDDEN

The file should not be displayed in a GUI (macOS 10.5+).

stat.SF_ARCHIVED

El archivo puede ser archivado.

stat.SF_IMMUTABLE

El archivo no puede ser modificado.

stat.SF_APPEND

Sólo se puede añadir al archivo.

stat.SF_NOUNLINK

El archivo no puede ser renombrado o borrado.

stat.SF_SNAPSHOT

El archivo es una instantánea.

See the *BSD or macOS systems man page chflags(2) for more information.

En Windows, las siguientes constantes de atributos de fichero están disponibles para ser usadas al comprobar los bits del miembro st_file_attributes retornado por os.stat(). Véase Windows API documentation [https://msdn.microsoft.com/en-us/library/windows/desktop/gg258117.aspx] para más detalles sobre el significado de estas constantes.

stat.FILE_ATTRIBUTE_ARCHIVE

stat.FILE_ATTRIBUTE_COMPRESSED

stat.FILE_ATTRIBUTE_DEVICE

stat.FILE_ATTRIBUTE_DIRECTORY

stat.FILE_ATTRIBUTE_ENCRYPTED

stat.FILE_ATTRIBUTE_HIDDEN

stat.FILE_ATTRIBUTE_INTEGRITY_STREAM

stat.FILE_ATTRIBUTE_NORMAL

stat.FILE_ATTRIBUTE_NOT_CONTENT_INDEXED

stat.FILE_ATTRIBUTE_NO_SCRUB_DATA

stat.FILE_ATTRIBUTE_OFFLINE

stat.FILE_ATTRIBUTE_READONLY

stat.FILE_ATTRIBUTE_REPARSE_POINT

stat.FILE_ATTRIBUTE_SPARSE_FILE

stat.FILE_ATTRIBUTE_SYSTEM

stat.FILE_ATTRIBUTE_TEMPORARY

stat.FILE_ATTRIBUTE_VIRTUAL

Nuevo en la versión 3.5.

En Windows, las siguientes constantes están disponibles para la comparación con el miembro st_reparse_tag retornado por os.lstat(). Estas constantes son muy conocidas, pero no se trata de una lista exhaustiva.

stat.IO_REPARSE_TAG_SYMLINK

stat.IO_REPARSE_TAG_MOUNT_POINT

stat.IO_REPARSE_TAG_APPEXECLINK

Nuevo en la versión 3.8.

filecmp— Comparaciones de Archivo y Directorio

Código fuente:Lib/filecmp.py [https://github.com/python/cpython/tree/3.9/Lib/filecmp.py]

El módulo filecmp define funciones para comparar ficheros y directorios, con varias compensaciones de tiempo/corrección. Para comparar ficheros, vea también el módulo difflib.

El módulo filecmp define las siguientes funciones:

filecmp.cmp(f1, f2, shallow=True)

Compara los ficheros llamados f1 y f2, retornando True si son iguales, False en caso contrario.

If shallow is true and the os.stat() signatures (file type, size, and modification time) of both files are identical, the files are taken to be equal.

Otherwise, the files are treated as different if their sizes or contents differ.

Note que ningún programa externo es llamado desde esta función, dándole portabilidad y eficiencia.

La función utiliza un caché para comparaciones pasadas y los resultados, con entradas de caché invalidadas si la información de os.stat() para el fichero cambia. El caché entero puede ser limpiado utilizando clear_cache().

filecmp.cmpfiles(dir1, dir2, common, shallow=True)

Compara los ficheros en los dos directorios dir1 y dir2 cuyos nombres son dados por common.

Retorna tres listas de nombres de fichero: match, mismatch, errors. match contiene la lista de ficheros que coinciden, mismatch contiene los nombres de aquellos que no, y errors lista los nombres de los ficheros que no deberían ser comparados. Los ficheros son listados en errors si no existen en uno de los directorios, el usuario carece de permisos para leerlos o si la comparación no puede hacerse por alguna razón.

El parámetro shallow tiene el mismo significado y valor por defecto en cuanto a filecmp.cmp().

Por ejemplo, cmpfiles('a', 'b', ['c', 'd/e']) comparará a/c con b/c y a/d/e con b/d/e. 'c' y 'd/e' estará cada uno en una de las tres listas retornadas.

filecmp.clear_cache()

Limpia el caché de filecmp. Esto podría ser útil si un fichero es comparado muy rápido después de que es modificado que está dentro de la resolución mtime del sistema de archivos subyacente.

Nuevo en la versión 3.4.

La clase dircmp

class filecmp.dircmp(a, b, ignore=None, hide=None)

Construye un nuevo objeto de comparación de directorio, para comparar los directorios a y b. ignore es una lista de nombres a ignorar, y predetermina a filecmp.DEFAULT_IGNORES. hide es una lista de nombres a ocultar, y predetermina a [os.curdir, os.pardir].

La clase dircmp compara ficheros haciendo comparaciones shallow como está descrito en filecmp.cmp().

La clase dircmp provee los siguientes métodos:

report()

Imprime (a sys.stdout) una comparación entre a y b.

report_partial_closure()

Imprime una comparación entre a y b y subdirectorios inmediatos comunes.

report_full_closure()

Imprime una comparación entre a y b y subdirectorios comunes (recursivamente).

La clase dircmp ofrece un número de atributos interesantes que pueden ser utilizados para obtener varios bits de información sobre los árboles de directorio que están siendo comparados.

Note que vía los hooks __getattr__(), todos los atributos son perezosamente computados, así que no hay penalización de velocidad si sólo esos atributos que son ligeros de computar son utilizados.

left

El directorio a.

right

El directorio b.

left_list

Ficheros y subdirectorios en a, filtrados por hide e ignore.

right_list

Ficheros y subdirectorios en b, filtrados por hide e ignore.

common

Ficheros y subdirectorios en a y b.

left_only

Ficheros y subdirectorios sólo en a.

right_only

Ficheros y subdirectorios sólo en b.

common_dirs

Subdirectorios en a y b.

common_files

Ficheros en a y b.

common_funny

Nombres en a y b, de forma que el tipo difiera entre los directorios, o los nombres por los que os.stat() reporta un error.

same_files

Ficheros que son idénticos en a y b, utilizando el operador de comparación de fichero de la clase.

diff_files

Ficheros que están en a y b, cuyos contenidos difieren acorde al operador de comparación del fichero de clase.

funny_files

Ficheros que están en a y b, pero no deberían ser comparados.

subdirs

Un diccionario mapeando nombres en objetos de common_dirs a dircmp.

filecmp.DEFAULT_IGNORES

Nuevo en la versión 3.4.

Lista de directorios ignorados por dircmp por defecto.

Aquí hay un ejemplo simplificado de uso del atributo subdirs para buscar recursivamente a través de dos directorios para mostrar diferentes ficheros comunes:

>>> from filecmp import dircmp
>>> def print_diff_files(dcmp):
...     for name in dcmp.diff_files:
...         print("diff_file %s found in %s and %s" % (name, dcmp.left,
...               dcmp.right))
...     for sub_dcmp in dcmp.subdirs.values():
...         print_diff_files(sub_dcmp)
...
>>> dcmp = dircmp('dir1', 'dir2')
>>> print_diff_files(dcmp)

tempfile — Generar archivos y directorios temporales

Código fuente: Lib/tempfile.py [https://github.com/python/cpython/tree/3.9/Lib/tempfile.py]

Este módulo crea archivos y directorios temporales. Funciona en todas las plataformas soportadas. TemporaryFile, NamedTemporaryFile, TemporaryDirectory, y SpooledTemporaryFile son interfaces de alto nivel que proporcionan limpieza automática y se pueden utilizar como administradores de contexto. mkstemp() y mkdtemp() son funciones de nivel inferior que requieren limpieza manual.

Todas las funciones y constructores invocables por el usuario toman argumentos adicionales que permiten el control directo sobre la ubicación y el nombre de los archivos y directorios temporales. Los nombres de archivos utilizados por este módulo incluyen una cadena de caracteres aleatorios que permite que esos archivos se creen de forma segura en directorios temporales compartidos. Para mantener la compatibilidad con versiones anteriores, el orden de argumentos es algo extraño; se recomienda utilizar argumentos nombrados para mayor claridad.

El módulo define los siguientes elementos invocables por el usuario:

tempfile.TemporaryFile(mode='w+b', buffering=-1, encoding=None, newline=None, suffix=None, prefix=None, dir=None, *, errors=None)

Retorna un file-like object que se puede usar como área de almacenamiento temporal. El archivo se crea de forma segura, usando las mismas reglas que mkstemp(). Este se destruirá tan pronto como se cierre (incluido un cierre implícito cuando el objeto es recolectado como basura). Bajo Unix, la entrada de directorio para el archivo no se crea en lo absoluto o se elimina inmediatamente después de crear el archivo. Otras plataformas no soportan esto; tu código no debería depender en un archivo temporal creado con esta función teniendo o no un nombre visible en el sistema de archivos.

El objeto resultante puede usarse como un administrador de contexto (ver Ejemplos). Al completar el contexto o la destrucción del objeto de archivo, el archivo temporal se eliminará del sistema de archivos.

El parámetro mode por defecto es 'w+b' para que el archivo creado pueda leerse y escribirse sin cerrarse. El modo binario se utiliza para que se comporte consistentemente en todas las plataformas sin tener en cuenta los datos que se almacenan. buffering, encoding, errors y newline se interpretan como en open().

Los parámetros dir, prefix y suffix tienen el mismo significado y valores predeterminados de mkstemp().

El objeto retornado es un objeto de archivo verdadero en las plataformas POSIX. En otras plataformas, es un objeto similar a un archivo cuyo atributo file es el objeto de archivo verdadero subyacente.

El indicador os.O_TMPFILE se usa si está disponible (específico de Linux, requiere el kernel de Linux 3.11 o posterior).

On platforms that are neither Posix nor Cygwin, TemporaryFile is an alias for NamedTemporaryFile.

Lanza un evento de auditoria tempfile.mkstemp con argumento fullpath.

Distinto en la versión 3.5: El indicador os.O_TMPFILE ahora se usa si está disponible.

Distinto en la versión 3.8: Se agregó el parámetro errors.

tempfile.NamedTemporaryFile(mode='w+b', buffering=-1, encoding=None, newline=None, suffix=None, prefix=None, dir=None, delete=True, *, errors=None)

This function operates exactly as TemporaryFile() does, except that the file is guaranteed to have a visible name in the file system (on Unix, the directory entry is not unlinked). That name can be retrieved from the name attribute of the returned file-like object. Whether the name can be used to open the file a second time, while the named temporary file is still open, varies across platforms (it can be so used on Unix; it cannot on Windows). If delete is true (the default), the file is deleted as soon as it is closed. The returned object is always a file-like object whose file attribute is the underlying true file object. This file-like object can be used in a with statement, just like a normal file.

Lanza un evento de auditoria tempfile.mkstemp con argumento fullpath.

Distinto en la versión 3.8: Se agregó el parámetro errors.

tempfile.SpooledTemporaryFile(max_size=0, mode='w+b', buffering=-1, encoding=None, newline=None, suffix=None, prefix=None, dir=None, *, errors=None)

Esta función opera exactamente como lo hace TemporaryFile(), excepto que los datos se almacenan en la memoria hasta que el tamaño del archivo excede max_size, o hasta que el método del archivo fileno() se llama, en ese momento los contenidos se escriben en el disco y la operación continúa como con TemporaryFile().

El archivo resultante tiene un método adicional, rollover(), que hace que el archivo se transfiera a un archivo en el disco, independientemente de su tamaño.

El objeto retornado es un objeto tipo archivo cuyo atributo _file es un objeto io.BytesIO o io.TextIOWrapper (dependiendo de si se especificó binario o texto mode) o un objeto de archivo verdadero, dependiendo de si: se ha llamado a rollover(). Este objeto similar a un archivo se puede usar en una sentencia with, al igual que un archivo normal.

Distinto en la versión 3.3: el método truncate ahora acepta un argumento size.

Distinto en la versión 3.8: Se agregó el parámetro errors.

tempfile.TemporaryDirectory(suffix=None, prefix=None, dir=None)

Esta función crea de forma segura un directorio temporal utilizando las mismas reglas que mkdtemp(). El objeto resultante puede usarse como administrador de contexto (ver Ejemplos). Al finalizar el contexto o la destrucción del objeto de directorio temporal, el directorio temporal recién creado y todo su contenido se eliminan del sistema de archivos.

El nombre del directorio se puede obtener del atributo name del objeto retornado. Cuando el objeto retornado se usa como administrador de contexto, el name se asignará al objetivo de la cláusula as en la sentencia with, si hay una.

El directorio se puede limpiar explícitamente llamando al método cleanup().

Lanza un evento de auditoria tempfile.mkdtemp con argumento fullpath.

Nuevo en la versión 3.2.

tempfile.mkstemp(suffix=None, prefix=None, dir=None, text=False)

Crea un archivo temporal de la manera más segura posible. No hay condiciones de carrera en la creación del archivo, suponiendo que la plataforma implemente correctamente el indicador os.O_EXCL para os.open(). El archivo se puede leer y escribir solo mediante el ID del usuario que lo crea. Aunque la plataforma utilice bits de permiso para indicar si un archivo es ejecutable, nadie puede ejecutar el archivo. El descriptor de archivo no es heredado por los procesos hijos.

A diferencia de TemporaryFile(), el usuario de mkstemp() es responsable de eliminar el archivo temporal cuando haya terminado con él.

Si suffix no es None, el nombre del archivo terminará con ese sufijo, de lo contrario no habrá sufijo. mkstemp() no pone un punto entre el nombre del archivo y el sufijo; si necesita uno, póngalo al comienzo del suffix.

Si prefix no es None, el nombre del archivo comenzará con ese prefijo; de lo contrario, se usa un prefijo predeterminado. El valor predeterminado es el valor de retorno de gettempprefix() o gettempprefixb(), según corresponda.

Si dir no es None, el archivo se creará en ese directorio; de lo contrario, se usa un directorio predeterminado. El directorio predeterminado se elige de una lista dependiente de la plataforma, pero el usuario de la aplicación puede controlar la ubicación del directorio configurando las variables de entorno TMPDIR, TEMP o TMP . Por lo tanto, no hay garantía de que el nombre de archivo generado tenga buenas propiedades, como no requerir comillas cuando se pasa a comandos externos a través de os.popen().

Si alguno de los argumentos suffix, prefix, y dir no son None, estos deben ser del mismo tipo. Si son bytes, el nombre retornado será bytes en lugar de str. Si desea forzar un valor de retorno de bytes con un comportamiento predeterminado, pase suffix=b’’.

Si se especifica text y es verdadero, el archivo se abre en modo texto. De lo contrario, (por defecto) el archivo se abre en modo binario.

mkstemp() retorna una tupla que contiene un controlador de nivel de sistema operativo a un archivo abierto (como sería retornado por os.open()) y la ruta absoluta de ese archivo, en ese orden.

Lanza un evento de auditoria tempfile.mkstemp con argumento fullpath.

Distinto en la versión 3.5: suffix, prefix, y dir ahora se pueden suministrar en bytes para obtener el valor de retorno en bytes. Antes de esto, solo str se permitía. suffix y prefix ahora aceptan y por defecto None para hacer que se use un valor predeterminado apropiado.

Distinto en la versión 3.6: El parámetro dir ahora acepta un path-like object.

tempfile.mkdtemp(suffix=None, prefix=None, dir=None)

Crea un directorio temporal de la manera más segura posible. No hay condiciones de carrera en la creación del directorio. El directorio se puede leer, escribir y buscar solo por el ID del usuario creador.

El usuario de mkdtemp() es responsable de eliminar el directorio temporal y su contenido cuando haya terminado con él.

Los argumentos prefix, suffix, y dir son los mismos que para mkstemp().

mkdtemp() retorna la ruta absoluta del nuevo directorio.

Lanza un evento de auditoria tempfile.mkdtemp con argumento fullpath.

Distinto en la versión 3.5: suffix, prefix, y dir ahora se pueden suministrar en bytes para obtener el valor de retorno en bytes. Antes de esto, solo str se permitía. suffix y prefix ahora aceptan y por defecto None para hacer que se use un valor predeterminado apropiado.

Distinto en la versión 3.6: El parámetro dir ahora acepta un path-like object.

tempfile.gettempdir()

Retorna el nombre del directorio utilizado para archivos temporales. Esto define el valor predeterminado para el argumento dir para todas las funciones en este módulo.

Python busca en una lista estándar de directorios para encontrar uno dentro del cual el usuario pueda crear archivos. La lista es:

El directorio nombrado por la variable de entorno TMPDIR.

El directorio nombrado por la variable de entorno TEMP.

El directorio nombrado por la variable de entorno TMP.

Una ubicación especifica de la plataforma:

En Windows, los directorios C:\TEMP, C:\TMP, \TEMP, y \TMP, en ese orden.

En todas las otras plataformas, los directorios /tmp, /var/tmp, y /usr/tmp, en ese orden.

Y como última alternativa, el directorio de trabajo actual.

El resultado de la búsqueda es cacheada, vea la descripción de tempdir abajo.

tempfile.gettempdirb()

Igual a gettempdir() pero el valor retornado es en bytes.

Nuevo en la versión 3.5.

tempfile.gettempprefix()

Retorna el prefijo del nombre de archivo utilizado para crear archivos temporales. Este no contiene el componente de directorio.

tempfile.gettempprefixb()

Igual que gettempprefix() pero el valor retornado es en bytes.

Nuevo en la versión 3.5.

El módulo utiliza una variable global para almacenar el nombre del directorio utilizado para los archivos temporales retornados por gettempdir(). Se puede configurar directamente para anular el proceso de selección, pero esto no se recomienda. Todas las funciones en este módulo toman un argumento dir que puede usarse para especificar el directorio y este es el enfoque recomendado.

tempfile.tempdir

Cuando se establece en un valor distinto de None, esta variable define el valor predeterminado para el argumento dir para las funciones definidas en este módulo.

Si tempdir es None (por defecto) en cualquier llamada a cualquiera de las funciones anteriores excepto gettempprefix() se inicializa siguiendo el algoritmo descrito en gettempdir().

Ejemplos

Estos son algunos ejemplos del uso típico del módulo tempfile:

>>> import tempfile

# create a temporary file and write some data to it
>>> fp = tempfile.TemporaryFile()
>>> fp.write(b'Hello world!')
# read data from file
>>> fp.seek(0)
>>> fp.read()
b'Hello world!'
# close the file, it will be removed
>>> fp.close()

# create a temporary file using a context manager
>>> with tempfile.TemporaryFile() as fp:
...     fp.write(b'Hello world!')
...     fp.seek(0)
...     fp.read()
b'Hello world!'
>>>
# file is now closed and removed

# create a temporary directory using the context manager
>>> with tempfile.TemporaryDirectory() as tmpdirname:
...     print('created temporary directory', tmpdirname)
>>>
# directory and contents have been removed

Funciones y variables deprecadas

Una forma histórica de crear archivos temporales era generar primero un nombre de archivo con la función mktemp() y luego crear un archivo con este nombre. Desafortunadamente, esto no es seguro, porque un proceso diferente puede crear un archivo con este nombre en el tiempo entre la llamada a mktemp() y el intento posterior de crear el archivo mediante el primer proceso. La solución es combinar los dos pasos y crear el archivo de inmediato. Este enfoque es utilizado por mkstemp() y las otras funciones descritas anteriormente.

tempfile.mktemp(suffix='', prefix='tmp', dir=None)

Obsoleto desde la versión 2.3: Utilice mkstemp() en su lugar.

Retorna el nombre de la ruta absoluta de un archivo que no existía en el momento en que se realiza la llamada. Los argumentos prefix, suffix y dir son similares a los de mkstemp(), excepto los nombres de archivo de bytes, suffix=None y prefix=None no son soportados.

Advertencia

El uso de esta función puede introducir un agujero de seguridad en su programa. Para cuando llegues a hacer algo con el nombre de archivo que retorna, alguien más pudo haberse adelantado. El uso de mktemp() se puede reemplazar fácilmente con NamedTemporaryFile(), pasándole el parámetro delete=False:

>>> f = NamedTemporaryFile(delete=False)
>>> f.name
'/tmp/tmptjujjt'
>>> f.write(b"Hello World!\n")
13
>>> f.close()
>>> os.unlink(f.name)
>>> os.path.exists(f.name)
False

glob — Expansión del patrón de nombres de ruta de estilo Unix

Código fuente: Lib/glob.py [https://github.com/python/cpython/tree/3.9/Lib/glob.py]

The glob module finds all the pathnames matching a specified pattern according to the rules used by the Unix shell, although results are returned in arbitrary order. No tilde expansion is done, but *, ?, and character ranges expressed with [] will be correctly matched. This is done by using the os.scandir() and fnmatch.fnmatch() functions in concert, and not by actually invoking a subshell.

Note that files beginning with a dot (.) can only be matched by patterns that also start with a dot, unlike fnmatch.fnmatch() or pathlib.Path.glob(). (For tilde and shell variable expansion, use os.path.expanduser() and os.path.expandvars().)

Para una coincidencia literal, envuelve los meta-caracteres en corchetes. Por ejemplo, '[?]' empareja el caracter '?'.

Ver también

El módulo pathlib ofrece objetos ruta de alto nivel.

glob.glob(pathname, *, recursive=False)

Retorna una lista posiblemente vacía de nombres de ruta que coincidan con pathname, que debe ser una cadena de caracteres que contenga una especificación de ruta. pathname puede ser absoluto (como /usr/src/Python-1.5/Makefile) o relativo (como ../../Tools/*/*.gif) y puede contener wildcards de estilo shell. Los enlaces simbólicos rotos se incluyen en los resultados (como en el shell). La clasificación de los resultados depende del sistema de archivos. Si un archivo que cumple las condiciones se elimina o se agrega durante la llamada de esta función, no se especifica si se incluirá un nombre de ruta para ese archivo.

Si recursive es verdadero, el patrón «**» coincidirá con cualquier fichero y cero o más directorios, subdirectorios y enlaces simbólicos a directorios. Si el patrón va seguido de un os.sep o os.altsep los ficheros no coincidirán.

Lanza un evento de auditoría glob.glob con los argumentos pathname, recursive.

Nota

El uso del patrón «**» en árboles de directorios grandes podría consumir una cantidad de tiempo excesiva.

Distinto en la versión 3.5: Soporte para globs recursivos usando «**».

glob.iglob(pathname, *, recursive=False)

Retorna un iterador el cual produce los mismos valores que glob() sin necesidad de almacenarlos todos de forma simultánea.

Lanza un evento de auditoría glob.glob con los argumentos pathname, recursive.

glob.escape(pathname)

Escapa todos los caracteres especiales ('?', '*' y '['). Esto es útil si deseas coincidir una cadena de caracteres literal arbitraria que podría contener caracteres especiales. Los caracteres especiales en unidades compartidas/UNC no se eluden, e.g. en Windows escape('//?/c:/Quo vadis?.txt') retorna '//?/c:/Quo vadis[?].txt'.

Nuevo en la versión 3.4.

Por ejemplo, considera un directorio que contenga los siguientes ficheros: 1.gif, 2.txt, card.gif y un subdirectorio sub el cual contenga solo el fichero 3.txt. glob() producirá los siguientes resultados. Nótese como se preservará cualquier componente inicial de la ruta.

>>> import glob
>>> glob.glob('./[0-9].*')
['./1.gif', './2.txt']
>>> glob.glob('*.gif')
['1.gif', 'card.gif']
>>> glob.glob('?.gif')
['1.gif']
>>> glob.glob('**/*.txt', recursive=True)
['2.txt', 'sub/3.txt']
>>> glob.glob('./**/', recursive=True)
['./', './sub/']

Si un directorio contiene ficheros que comienzan con . no coincidirá por defecto. Por ejemplo, considera un directorio que contiene card.gif y .card.gif:

>>> import glob
>>> glob.glob('*.gif')
['card.gif']
>>> glob.glob('.c*')
['.card.gif']

Ver también

Módulo fnmatch

Expansión de nombre de fichero (no de ruta) al estilo de la terminal

fnmatch — Coincidencia de patrones de nombre de archivos Unix

Código fuente: Lib/fnmatch.py [https://github.com/python/cpython/tree/3.9/Lib/fnmatch.py]

Este módulo proporciona soporte para comodines de estilo shell de Unix, que no son lo mismo que las expresiones regulares (que se documentan en el módulo re). Los caracteres especiales utilizados en los comodines de estilo shell son:

Patrón

Significado

*

coincide con todo

?

coincide con un solo carácter

[seq]

coincide con cualquier carácter presente en seq

[!seq]

coincide con cualquier carácter ausente en seq

Para una coincidencia literal, envuelva los meta-caracteres entre paréntesis. Por ejemplo, '[?]' coincide con el carácter '?'.

Ten en cuenta que el separador de nombre de archivo ('/' en Unix) no es tratado de forma especial en este módulo. Consulta el módulo glob para realizar expansiones de nombre de ruta (glob usa filter() para hacer coincidir con los componentes del nombre de ruta). Del mismo modo, los nombres de archivo que comienzan con un punto tampoco son tratados de forma especial por este módulo y se corresponden con los patrones * y ?.

fnmatch.fnmatch(filename, pattern)

Prueba si la cadena de caracteres filename coincide con la cadena pattern, retornando True o False. Ambos parámetros se normalizan entre mayúsculas y minúsculas usando os.path.normcase(). fnmatchcase() se puede utilizar para realizar una comparación que distingue entre mayúsculas y minúsculas, independientemente de si es estándar para el sistema operativo.

Este ejemplo imprimirá todos los nombres de archivo en el directorio actual con la extensión .txt:

import fnmatch
import os

for file in os.listdir('.'):
    if fnmatch.fnmatch(file, '*.txt'):
        print(file)

fnmatch.fnmatchcase(filename, pattern)

Prueba si filename coincide con pattern, retornando True o False; la comparación distingue entre mayúsculas y minúsculas y no aplica os.path.normcase().

fnmatch.filter(names, pattern)

Construye una lista a partir de los elementos de los names iterables que coinciden con el pattern. Es lo mismo que [n for n in names if fnmatch(n, pattern)], pero implementado de manera más eficiente.

fnmatch.translate(pattern)

Retorna el pattern estilo shell convertido a una expresión regular para usar con re.match().

Ejemplo:

>>> import fnmatch, re
>>>
>>> regex = fnmatch.translate('*.txt')
>>> regex
'(?s:.*\\.txt)\\Z'
>>> reobj = re.compile(regex)
>>> reobj.match('foobar.txt')
<re.Match object; span=(0, 10), match='foobar.txt'>

Ver también

Módulo glob

Expansión de ruta estilo shell en Unix.

linecache — Acceso aleatorio a líneas de texto

Código fuente: Lib/linecache.py [https://github.com/python/cpython/tree/3.9/Lib/linecache.py]

El módulo linecache permite obtener cualquier línea de un archivo fuente Python, mientras se intenta optimizar internamente, usando una caché, el caso común en el que se leen muchas líneas de un solo archivo. Esto es utilizado por el módulo traceback para recuperar líneas de código fuente para incluirlas en el seguimiento de pila formateado.

La función tokenize.open() se utiliza para abrir archivos. Esta función usa tokenize.detect_encoding() para obtener la codificación del archivo; en la ausencia de un token de codificación, la codificación del archivo es por defecto UTF-8.

El módulo linecache define las siguientes funciones:

linecache.getline(filename, lineno, module_globals=None)

Obtiene la línea lineno del archivo llamado filename. Esta función nunca lanzará una excepción — retornará '' en los errores (el carácter de la nueva línea de terminación se incluirá para las líneas que se encuentren).

Si un archivo llamado filename no se encuentra, la función primero verifica un __loader__ en module_globals PEP 302 [https://www.python.org/dev/peps/pep-0302]. Si existe tal cargador y define un método get_source, entonces eso determina las líneas de origen (si get_source() retorna None, entonces se retorna ''). Finalmente, si filename es un nombre de fichero relativo, se busca en relación a las entradas en la ruta de búsqueda del módulo, sys.path.

linecache.clearcache()

Borra el caché. Use esta función si ya no necesita las líneas de archivos leídos previamente usando getline().

linecache.checkcache(filename=None)

Comprueba la validez de la caché. Use esta función si los archivos de la caché pueden haber cambiado en disco y necesita la versión actualizada. Si se omite filename, comprobará todas las entradas en la caché.

linecache.lazycache(filename, module_globals)

Captura suficientes detalles sobre un módulo no basado en archivos para permitir obtener sus líneas más tarde a través de getline() incluso si module_globals es None en la llamada posterior. Esto evita hacer E/S hasta que una línea es realmente necesaria, sin tener que llevar los módulo globales indefinidamente.

Nuevo en la versión 3.5.

Ejemplo:

>>> import linecache
>>> linecache.getline(linecache.__file__, 8)
'import sys\n'

shutil — Operaciones de archivos de alto nivel

Código fuente: Lib/shutil.py [https://github.com/python/cpython/tree/3.9/Lib/shutil.py]

El módulo shutil ofrece varias operaciones de alto nivel en archivos y colecciones de archivos. En particular, provee funciones que dan soporte a la copia y remoción de archivos. Para operaciones en archivos individuales, véase también el módulo os.

Advertencia

Incluso las funciones de copia de archivos de nivel superior (shutil.copy(), shutil.copy2()) no pueden copiar todos los metadatos del archivo.

En las plataformas POSIX, esto significa que tanto el propietario como el grupo del archivo se pierden, al igual que las ACLs (access control lists o lista de control de acceso). En Mac OS, la bifurcación (fork) de recursos y de otros metadatos no se utilizan. Esto quiere decir que los recursos se perderán y que el tipo de archivo y los códigos de creador no serán correctos. En Windows, los propietarios de archivos, las ACLs y secuencias de datos alternativas no se copian.

Operaciones de directorios y archivos

shutil.copyfileobj(fsrc, fdst[, length])

Copia los contenidos del objeto de tipo archivo fsrc en el objeto fdst. El valor entero length, si está indicado, es el tamaño del búfer. En particular, un valor length negativo significa copiar los datos sin recorrer los datos de origen en fragmentos; los datos se leen en fragmentos en forma predeterminada para evitar el consumo de memoria incontrolado. Nótese que si la posición actual del archivo del objeto fsrc es distinto de cero, solo se copiarán el contenido desde la posición actual del archivo hasta el final.

shutil.copyfile(src, dst, *, follow_symlinks=True)

Copia los contenidos (sin metadatos) del archivo src en un archivo denominado dst y retorna dst de la manera más eficaz posible. src y dst son objetos de tipo ruta o nombres de ruta dados como cadenas de caracteres.

dst debe ser el nombre completo del archivo destino; véase shutil.copy() para una copia que acepta una ruta de directorio destino. Si src y dst refieren al mismo archivo, se lanza SameFileError.

El local de destino debe tener permisos de escritura; de lo contrario, se genera una excepción OSError. Si dst ya existe, se reemplazará. Los archivos especiales, como los dispositivos de caracteres o de bloques y pipes, no se pueden copiar con esta función.

Si follow_symlinks es falso y src es un enlace simbólico, un enlace simbólico nuevo se creará en lugar de copiar el archivo al que src apunta.

Se genera un evento de auditoría shutil.copyfile con argumentos src, dst.

Distinto en la versión 3.3: Solía generarse IOError en lugar de OSError. Se añadió el argumento follow_symlinks. Ahora retorna dst.

Distinto en la versión 3.4: Genera SameFileError en lugar de Error. Dado que la primera es una subclase de la segunda, el cambio es compatible con versiones anteriores.

Distinto en la versión 3.8: Las llamadas a sistema de copia rápida específicas de la plataforma se pueden usar internamente para copiar el archivo de manera más eficiente. Véase la sección Operaciones de copia eficientes dependientes de la plataforma.

exception shutil.SameFileError

Esta excepción se genera si el origen y destino en copyfile() son el mismo archivo.

Nuevo en la versión 3.4.

shutil.copymode(src, dst, *, follow_symlinks=True)

Copia los bits de permiso de src a dst. Los contenidos, el propietario y el grupo no se ven afectados. src y dst son objetos tipo ruta o nombres de ruta dados como cadenas de caracteres. Si follow_symlinks es falso, y tanto src como dst son enlaces simbólicos, copymode() intentará modificar el modo de dst (y no el archivo al que apunta). Esta funcionalidad no está disponible en todas las plataformas; véase copystat() para mayor información. Si copymode() no puede modificar los enlaces simbólicos de la plataforma local y se le solicita hacerlo, no hará nada y retornará.

Genera un evento de auditoría shutil.copymode con argumentos src, dst.

Distinto en la versión 3.3: Se añadió el argumento follow_symlinks.

shutil.copystat(src, dst, *, follow_symlinks=True)

Copia los bits de permiso, la última hora de acceso, la última hora de modificación y las flags desde src a dst. En Linux, copystat() también copia los «atributos extendidos» siempre que sea posible. Los contenidos, el propietario y el grupo del archivo no se ven afectados. src y dst son objetos de tipo a ruta o nombres de ruta dados como cadenas de caracteres.

Si follow_symlinks es falso, y src y dst hacen referencia los enlaces simbólicos, copystat() funcionará con los enlaces simbólicos en lugar de en los archivos a los que estos se refieren: leer la información del enlace simbólico src y escribirla en el enlace simbólico dst.

Nota

No todas las plataformas proporcionan la capacidad de examinar y modificar enlaces simbólicos. Python puede indicarte qué funcionalidad está disponible localmente.

Si os.chmod in os.supports_follow_symlinks es True, copystat() puede modificar los bits de permiso de un enlace simbólico.

Si os.utime in os.supports_follow_symlinks es True, copystat() puede modificar el último acceso y las veces que un enlace simbólico fue modificado.

Si os.chflags in os.supports_follow_symlinks es True, copystat() puede modificar las flags de un enlace simbólico. (os.chflags no está disponible en todas las plataformas.)

En plataformas donde parte o toda esta funcionalidad no está disponible, cuando se le pida modificar un enlace simbólico, copystat() copiará todo lo que pueda. copystat() nunca retorna un error.

Véase os.supports_follow_symlinks para más información.

Genera un evento de auditoría shutil.copystat con argumentos src, dst.

Distinto en la versión 3.3: Se ha añadido el argumento follow_symlinks y el soporte para atributos extendidos de Linux.

shutil.copy(src, dst, *, follow_symlinks=True)

Copies the file src to the file or directory dst. src and dst should be path-like objects or strings. If dst specifies a directory, the file will be copied into dst using the base filename from src. If dst specifies a file that already exists, it will be replaced. Returns the path to the newly created file.

Si follow_symlinks es falso, y src es un enlace simbólico, dst se creará como enlace simbólico. Si follow_symlinks es verdadero y src es un enlace simbólico, dst será una copia del archivo al que src hace referencia.

copy() copia los datos del archivo y el modo de permiso del archivo (véase os.chmod()). Otros metadatos, como los tiempos de creación y modificación de archivos, no se preservan. Para preservar todos los metadatos del archivo, usa copy2() en su lugar.

Se genera un evento de auditoría shutil.copyfile con argumentos src, dst.

Genera un evento de auditoría shutil.copymode con argumentos src, dst.

Distinto en la versión 3.3: Se ha añadido el argumento follow_symlinks. Ahora retorna la ruta de acceso al archivo recién creado.

Distinto en la versión 3.8: Las llamadas a sistema de copia rápida específicas de la plataforma se pueden usar internamente para copiar el archivo de manera más eficiente. Véase la sección Operaciones de copia eficientes dependientes de la plataforma.

shutil.copy2(src, dst, *, follow_symlinks=True)

Idéntico a copy() , excepto que copy2() también intenta conservar los metadatos del archivo.

Cuando follow_symlinks es falso, y src es un enlace simbólico, copy2() intenta copiar todos los metadatos del enlace simbólico src en el enlace simbólico dst recién creado. Sin embargo, esta funcionalidad no está disponible en todas las plataformas. En las plataformas donde parte o toda esta funcionalidad no está disponible, copy2() conservará todos los metadatos que pueda; copy2() nunca genera una excepción porque no puede conservar los metadatos del archivo.

copy2() usa copystat() para copiar todos los metadatos del archivo. Véase copystat() para más información sobre la compatibilidad con la plataforma para modificar los metadatos del enlace simbólico.

Se genera un evento de auditoría shutil.copyfile con argumentos src, dst.

Genera un evento de auditoría shutil.copystat con argumentos src, dst.

Distinto en la versión 3.3: Añadido el argumento follow_symlinks, intenta copiar también los atributos del sistema de archivos extendidos (actualmente solo en Linux). Ahora retorna la ruta de acceso al archivo recién creado.

Distinto en la versión 3.8: Las llamadas a sistema de copia rápida específicas de la plataforma se pueden usar internamente para copiar el archivo de manera más eficiente. Véase la sección Operaciones de copia eficientes dependientes de la plataforma.

shutil.ignore_patterns(*patterns)

Esta función de fábrica crea una función que puede ser usada como un invocable para el argumento ignore de copytree(), ignorando los archivos y directorios que coinciden con uno de los patrones patterns de estilo glob provistos. Véase el ejemplo siguiente.

shutil.copytree(src, dst, symlinks=False, ignore=None, copy_function=copy2, ignore_dangling_symlinks=False, dirs_exist_ok=False)

Recursively copy an entire directory tree rooted at src to a directory named dst and return the destination directory. All intermediate directories needed to contain dst will also be created by default.

Los permisos y los tiempos de directorios son copiados con copystat(); los archivos individuales son copiados usando copy2().

Si symlinks es verdadero, los enlaces simbólicos en el árbol de origen son representados como enlaces simbólicos en el árbol nuevo y los metadatos de los enlaces originales serán copiados mientras la plataforma lo permita; si es falso o se omite, los contenidos y los metadatos de los archivos vinculados se copiarán en el árbol nuevo.

Cuando symlinks es falso y el archivo al que apunta no exista, se agrega una excepción a la lista de errores generados en una excepción Error al final del proceso de copia. Puedes establecer la marca opcional ignore_dangling_symlinks en verdadero si deseas silenciar esa excepción. Ten en cuenta que esta opción no tiene efecto en plataformas que no admiten os.symlink().

Si se proporciona ignore, debe ser un invocable que recibirá como argumentos el directorio visitado por copytree() y una lista de sus contenidos, tal como los retorna os.listdir(). Ya que copytree() se invoca recursivamente, el invocable ignore se llamará una vez por cada directorio que se copia. El invocable debe retornar una secuencia de directorio y de nombres de archivo en relación con el directorio actual (es decir, un subconjunto de los elementos en su segundo argumento); estos nombres serán ignorados en el proceso de copia. ignore_patterns() se pueden usar para crear un invocable que ignora los nombres basados en patrones de estilo gob.

Si ocurren excepciones, se genera, un Error con una lista de razones.

Si copy_function está dado, debe ser un invocable que se usará para copiar cada archivo. Se le invocará con la ruta de origen y la ruta de destino como argumentos. Por defecto, se usa copy2(), pero se puede usar cualquier función que admita la misma (como copy()).

If dirs_exist_ok is false (the default) and dst already exists, a FileExistsError is raised. If dirs_exist_ok is true, the copying operation will continue if it encounters existing directories, and files within the dst tree will be overwritten by corresponding files from the src tree.

Se genera un evento de auditoría shutil.copytree con argumentos src, dst.

Distinto en la versión 3.3: Copia los metadatos cuando symlinks es falso. Ahora retorna dst.

Distinto en la versión 3.2: Added the copy_function argument to be able to provide a custom copy function. Added the ignore_dangling_symlinks argument to silence dangling symlinks errors when symlinks is false.

Distinto en la versión 3.8: Las llamadas a sistema de copia rápida específicas de la plataforma se pueden usar internamente para copiar el archivo de manera más eficiente. Véase la sección Operaciones de copia eficientes dependientes de la plataforma.

Nuevo en la versión 3.8: El parámetro dirs_exist_ok.

shutil.rmtree(path, ignore_errors=False, onerror=None)

Elimina un árbol de directorios entero; path debe apuntar a un directorio (pero no a un enlace simbólico a un directorio). Si ignore_errors es verdadero, se eliminarán los errores que resulten de eliminaciones fallidas; si es falso u omitido, estos errores se controlan invocando un controlador especificado por onerror o, si este es omitido, se genera una excepción.

Nota

En plataformas que admiten las funciones basadas en descriptores de archivo necesarias, una versión resistente de rmtree() al ataque de enlace simbólico se usa por defecto. En otras plataformas, la implementación rmtree() es susceptible a un ataque de enlace simbólico; dados el tiempo y las circunstancias adecuados, los atacantes pueden manipular los enlaces simbólicos en el sistema de archivos para eliminar archivos a los que no podrían acceder de otra manera. Las aplicaciones pueden usar el atributo de función rmtree.avoids_symlink_attacks para determinar qué caso aplica.

Si se onerror está dado, debe ser un invocable que acepte tres parámetros: function, path, y excinfo.

El primer parámetro, function, es la función que generó la excepción; depende de la plataforma y de la implementación. El segundo parámetro, path, será el nombre de ruta pasado a function. El tercer parámetro, excinfo, será la información de la excepción retornada por sys.exc_info(). Las excepciones generadas por onerror no serán tomadas.

Genera un evento de auditoría shutil.rmtree con argumento path.

Distinto en la versión 3.3: Se añadió una versión resistente a los ataques de enlaces simbólicos que se usan automáticamente si la plataforma admite funciones pasadas en descriptores de archivo.

Distinto en la versión 3.8: En Windows, ya no eliminará los contenidos de un cruce de directorios antes de quitar el cruce.

rmtree.avoids_symlink_attacks

Indica si la plataforma actual y la implementación proporciona una versión de rmtree() resistente al ataque de enlace simbólico. Actualmente, esto solo sucede para plataformas que admitan funciones de acceso a directorios basadas en descriptores de archivo.

Nuevo en la versión 3.3.

shutil.move(src, dst, copy_function=copy2)

Mueve de forma recursiva un archivo o directorio (src) a otra ubicación (dst) y retorna el destino.

Si el destino es un directorio existente, entonces src se mueve dentro de ese directorio. Si el destino existe pero no es un directorio, puede sobrescribirse dependiendo de la semántica os.rename().

Si el destino está en el sistema de archivos actual, entonces se usa os.rename(). De lo contrario, src se copia en dst usando copy_function y luego se elimina. En el caso de los enlaces simbólicos, se creará un enlace simbólico nuevo que apunta al destino de *src en o como dst y será eliminado.

Si copy_function se proporciona, debe ser un invocable que toma dos argumentos src y dst, y se usará para copiar src a dest si no se puede usar os.rename(). Si el origen es un directorio, se invoca copytree() y se le pasa copy_function(). El copy_function por defecto es copy2(). El uso de copy() como copy_function permite que el movimiento se realice correctamente cuando no es posible copiar los metadatos también, a expensas de no copiar ninguno de los metadatos.

Genera un evento de auditoría shutil.move con argumentos src, dst.

Distinto en la versión 3.3: Se añadió el manejo explícito de enlaces simbólicos para sistemas de archivos extranjeros, de manera que se adapta al comportamiento del mv del GNU. Ahora retorna dst.

Distinto en la versión 3.5: Se agregó el argumento de keyword copy_function.

Distinto en la versión 3.8: Las llamadas a sistema de copia rápida específicas de la plataforma se pueden usar internamente para copiar el archivo de manera más eficiente. Véase la sección Operaciones de copia eficientes dependientes de la plataforma.

Distinto en la versión 3.9: Acepta un objeto tipo ruta como src y dst.

shutil.disk_usage(path)

Retorna las estadísticas de uso de disco sobre la ruta de acceso dada como un named tuple con los atributos total, used y free, que son las cantidades del espacio total, el usado y el libre, en bytes. path puede ser un archivo o un directorio.

Nuevo en la versión 3.3.

Distinto en la versión 3.8: En Windows, path ahora puede ser un archivo o un directorio.

Disponibilidad: Unix, Windows.

shutil.chown(path, user=None, group=None)

Cambia el propietario user y/o group de la ruta dada.

user puede ser un nombre usuario de sistema o un UID (identificador de usuario); lo mismo aplica a group. Se requiere al menos un argumento.

Véase también os.chown(), la función subyacente.

Genera un evento de auditoría shutil.chown con argumentos path, user, group.

Disponibilidad: Unix.

Nuevo en la versión 3.3.

shutil.which(cmd, mode=os.F_OK | os.X_OK, path=None)

Retorna la ruta de acceso a un ejecutable que se ejecutaría si el cmd dado se invoca. Si no se invoca a cmd, retorna None.

mode es una máscara de permiso que se pasa a os.access(), que determinar por defecto si el archivo existe y es ejecutable.

Cuando no se especifica path, se usan los resultados de os.environ() y se retorna el valor de «PATH» o una reserva de os.defpath.

En Windows, el directorio actual siempre se antepone a path, independientemente de si usa el valor predeterminado o si tú provees el tuyo propio, que es el comportamiento que el comando shell usa cuando encuentra ejecutables. Además, al encontrar el cmd en el path, se comprueba la variable de entorno PATHEXT. Por ejemplo, si invocas shutil.which("python"), which() buscará PATHEXT para saber si debe buscar python.exe dentro de los directorios path. Por ejemplo, en Windows:

>>> shutil.which("python")
'C:\\Python33\\python.EXE'

Nuevo en la versión 3.3.

Distinto en la versión 3.8: Ahora se acepta el tipo bytes. Si el tipo cmd es bytes, el tipo resultante también es bytes.

exception shutil.Error

Esta excepción recopila las excepciones que se generan durante una operación de varios archivos. Para copytree(), el argumento de excepción es una lista de 3 tuplas (scrname, dstname, exception).

Operaciones de copia eficientes dependientes de la plataforma

A partir de Python 3.8, todas las funciones que incluyen una copia de archivo (copyfile(), copy(), copy2(), copytree(), y move()) puede usar llamadas a sistema de «copia rápida» específicas a cada plataforma para poder copiar el archivo de forma más eficiente (véase bpo-33671 [https://bugs.python.org/issue?@action=redirect&bpo=33671]). «copia rápida» significa que la operación de copia ocurre dentro del núcleo, evitando el uso de búferes en espacio de usuario en Python como en «outfd.write(infd.read())».

En macOS, se usa fcopyfile [http://www.manpagez.com/man/3/copyfile/] para copiar el contenido del archivo (pero no los metadatos).

En Linux, se usa os.sendfile().

En Windows, shutil.copyfile() usa un tamaño de búfer predeterminado más grande (1 MiB en lugar de 64 KiB) y se usa una variante de shutil.copyfileobj() basada en memoryview().

Si ocurre un error en la operación de copia rápida y no se ha escrito ningún dato en el archivo de destino, entonces shutil recurrirá silenciosamente a usar la función copyfileobj() menos eficiente internamente.

Distinto en la versión 3.8.

ejemplo de copytree

An example that uses the ignore_patterns() helper:

from shutil import copytree, ignore_patterns

copytree(source, destination, ignore=ignore_patterns('*.pyc', 'tmp*'))

Esto copiará todo excepto archivos .pyc y archivos o directorios cuyo nombre comience con tmp.

Otro ejemplo que usa el argumento ignore para agregar una llamada a iniciar sesión:

from shutil import copytree
import logging

def _logpath(path, names):
    logging.info('Working in %s', path)
    return []   # nothing will be ignored

copytree(source, destination, ignore=_logpath)

ejemplo de rmtree

Este ejemplo muestra como eliminar un árbol de directorio en Windows donde algunos de los archivos tienen configurado su bit de sólo lectura. Usa la onerror callback para limpiar el bit de sólo lectura y reintentar eliminarlo. Cualquier fallo que le siga, se propagará.

import os, stat
import shutil

def remove_readonly(func, path, _):
    "Clear the readonly bit and reattempt the removal"
    os.chmod(path, stat.S_IWRITE)
    func(path)

shutil.rmtree(directory, onerror=remove_readonly)

Operaciones de archivado

Nuevo en la versión 3.2.

Distinto en la versión 3.5: Se agregó soporte para el formato xztar.

Se proveen también las utilidades de alto nivel para crear y leer archivos comprimidos y archivados. Utilizan para esto los módulos zipfile y tarfile.

shutil.make_archive(base_name, format[, root_dir[, base_dir[, verbose[, dry_run[, owner[, group[, logger]]]]]]])

Crea un documento de archivado (como zip o tar) y retorna su nombre.

base_name es el nombre del archivo a crear, incluyendo la ruta, menos cualquier extensión que sea específica de formato. format es el formato de archivo: uno de zip (si el módulo zlib está disponible), «tar», «gztar» (si el módulo zlib está disponible), «bztar» (si el módulo bz2 está disponible), o «xztar» (si el módulo lzma).

root_dir es un directorio que será el directorio raíz del archivo, todas las rutas en el archivo serán relativas a él; por ejemplo, típicamente nos cambiaremos de directorio (chdir) a root_dir antes de crear el archivo.

base_dir es el directorio desde donde iniciamos el archivado; i.e, base_dir será el prefijo común para todos los archivos y directorios en el archivo. base_dir debe ser dado de forma relativa a root_dir. En Ejemplo de archivado con base_dir se ve un ejemplo de cómo usar base_dir y root_dir juntos.

root_dir y base_dir irán por defecto al directorio actual.

If dry_run es verdadero, no se crea un archivo, pero las operaciones que se ejecutarán están registradas en logger.

owner y group se usan al crear un archivador tar. Por defecto, usa el propietario y el grupo actual.

logger debe ser un objeto compatible con PEP 282 [https://www.python.org/dev/peps/pep-0282], usualmente una instancia de logging.Logger.

El argumento verbose está fuera de uso y es obsoleto.

Genera un evento de auditoría shutil.make_archive con argumentos base_name, format, root_dir, base_dir.

Nota

This function is not thread-safe.

Distinto en la versión 3.8: El formato de pax moderno (POSIX.1-2001) se usa ahora en lugar del formato de legado GNU para archivadores creados con format="tar".

shutil.get_archive_formats()

Retorna una lista de formatos admitidos para archivado. Cada elemento de una secuencia retornada es una tupla (name, description).

Por defecto, shutil provee los siguientes formatos:

zip: archivo ZIP (si el módulo zlib está disponible).

tar: archivo tar sin comprimir. Utiliza el formato pax POSIX.1-2001 para archivos nuevos.

gztar: archivo tar comprimido con gzip (si el módulo zlib está disponible).

bztar: archivo tar comprimido con bzip2 (si el módulo bz2 está disponible).

xztar: archivo tar comprimido con xz (si el módulo lzma está disponible).

Puedes registrar formatos nuevos o proporcionar tu propio archivador para cualquier formato existente, usando register_archive_format().

shutil.register_archive_format(name, function[, extra_args[, description]])

Registra un archivador para el formato name.

function es el invocable que se usará para desempacar archivos. El invocable recibirá el base_name del archivo para crearlo, seguido por base_dir (que cae por defecto en os.curdir) para comenzar a archivar desde allí. Otros argumentos se pasan como argumentos de palabras clave: owner, group, dry_run y logger (como se pasa en make_archive()).

Si está dado, extra_args es una secuencia de pares (name, value) que se usarán como argumentos de palabras clave extra cuando se usa el archivador invocable.

description se usa por get_archive_formats() que retorna la lista de archivadores. Cae por defecto en una cadena de caracteres vacía.

shutil.unregister_archive_format(name)

Elimina el formato de archivo name de la lista de formatos admitidos.

shutil.unpack_archive(filename[, extract_dir[, format[, filter]]])

Desempaqueta un archivo. filename es la ruta completa del archivo.

extract_dir es el nombre del directorio donde se desempaca el archivo. Si no está provisto, se usa el nombre del directorio actual.

format es el formato de archivo: uno de «zip», «tar», «gztar», «bztar», or «xztar». O cualquier otra formato registrado con register_unpack_format(). Si no está provisto, unpack_archive() usará la extensión de archivo del archivador y verá si se registró un desempacador para esa extensión. En caso de que no se encuentre ninguno, se genera un ValueError.

The keyword-only filter argument, which was added in Python 3.9.17, is passed to the underlying unpacking function. For zip files, filter is not accepted. For tar files, it is recommended to set it to 'data', unless using features specific to tar and UNIX-like filesystems. (See Extraction filters for details.) The 'data' filter will become the default for tar files in Python 3.14.

Se genera un evento de auditoría shutil.unpack_archive con argumentos filename, extract_dir, format.

Advertencia

Never extract archives from untrusted sources without prior inspection. It is possible that files are created outside of the path specified in the extract_dir argument, e.g. members that have absolute filenames starting with «/» or filenames with two dots «..».

Distinto en la versión 3.7: Acepta un path-like object como filename y extract_dir.

Distinto en la versión 3.9.17: Added the filter argument.

shutil.register_unpack_format(name, extensions, function[, extra_args[, description]])

Registra un formato de desempaque. name es el nombre del formato y extensions es una lista de extensiones que corresponden al formato, como .zip para archivos zip.

function is the callable that will be used to unpack archives. The callable will receive:

the path of the archive, as a positional argument;

the directory the archive must be extracted to, as a positional argument;

possibly a filter keyword argument, if it was given to unpack_archive();

additional keyword arguments, specified by extra_args as a sequence of (name, value) tuples.

description se puede proporcionar para describir el formato y será retornado por la función get_unpack_formats().

shutil.unregister_unpack_format(name)

Anula el registro del formato de desempaque. name es el nombre del formato.

shutil.get_unpack_formats()

Retorna una lista de todos los formatos registrados para desempaquetar. Cada elemento de la secuencia es una tupla (name, extensions, description).

Por defecto, shutil provee los siguientes formatos:

zip: archivo zip (desempaquetar archivos comprimidos funciona solo si el módulo correspondiente está disponible).

tar: archivo tar sin comprimir.

gztar: archivo tar comprimido con gzip (si el módulo zlib está disponible).

bztar: archivo tar comprimido con bzip2 (si el módulo bz2 está disponible).

xztar: archivo tar comprimido con xz (si el módulo lzma está disponible).

Puedes registrar formatos nuevos o proporcionar tu propio desempaquetado para cualquier formato existente, usando register_unpack_format().

Ejemplo de archivado

En este ejemplo, creamos un archivo tar de tipo gzip que contiene todos los archivos que se encuentran en el directorio .ssh del usuario:

>>> from shutil import make_archive
>>> import os
>>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive'))
>>> root_dir = os.path.expanduser(os.path.join('~', '.ssh'))
>>> make_archive(archive_name, 'gztar', root_dir)
'/Users/tarek/myarchive.tar.gz'

El archivo resultante contiene:

$ tar -tzvf /Users/tarek/myarchive.tar.gz
drwx------ tarek/staff       0 2010-02-01 16:23:40 ./
-rw-r--r-- tarek/staff     609 2008-06-09 13:26:54 ./authorized_keys
-rwxr-xr-x tarek/staff      65 2008-06-09 13:26:54 ./config
-rwx------ tarek/staff     668 2008-06-09 13:26:54 ./id_dsa
-rwxr-xr-x tarek/staff     609 2008-06-09 13:26:54 ./id_dsa.pub
-rw------- tarek/staff    1675 2008-06-09 13:26:54 ./id_rsa
-rw-r--r-- tarek/staff     397 2008-06-09 13:26:54 ./id_rsa.pub
-rw-r--r-- tarek/staff   37192 2010-02-06 18:23:10 ./known_hosts

Ejemplo de archivado con base_dir

En este ejemplo, similar al de arriba, mostramos cómo usar make_archive(), pero esta vez utilizando base_dir. Ahora tenemos la siguiente estructura de directorios:

$ tree tmp
tmp
└── root
    └── structure
        ├── content
            └── please_add.txt
        └── do_not_add.txt

En el archivo final, please_add.txt debería estar incluido, pero do_not_add.txt no. Por lo tanto usamos lo siguiente:

>>> from shutil import make_archive
>>> import os
>>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive'))
>>> make_archive(
...     archive_name,
...     'tar',
...     root_dir='tmp/root',
...     base_dir='structure/content',
... )
'/Users/tarek/my_archive.tar'

Listando los archivos en el archivo resultante nos da:

$ python -m tarfile -l /Users/tarek/myarchive.tar
structure/content/
structure/content/please_add.txt

Consulta el tamaño de la terminal de salida

shutil.get_terminal_size(fallback=(columns, lines))

Obtén el tamaño de la ventana de la terminal.

Para cada una de las dos dimensiones, se comprueba la variable de entorno COLUMNS y LINES respectivamente. Si la variable está definida y el valor es un entero positivo, se utiliza.

Cuando COLUMNS o LINES no está definido, como suele ocurrir, la terminal conectada a sys.__stdout__ se consulta invocando os.get_terminal_size().

Si el tamaño de la terminal no se puede consultar correctamente, ya sea porque el sistema no admite consultas o porque no estamos conectados a una terminal, se usa el valor dado en el parámetro fallback. fallback tiene por defecto (80, 24), que es el tamaño por defecto que se usa en muchos emuladores de terminal.

El valor retornado es una tupla con su respectivo nombre, de tipo os.terminal_size.

Ver también: The Single UNIX Specification, Versión 2, Other Environment Variables [http://pubs.opengroup.org/onlinepubs/7908799/xbd/envvar.html#tag_002_003].

Nuevo en la versión 3.3.

Persistencia de datos

Los módulos descritos en este capítulo soportan el almacenamiento de datos de Python de forma persistente en el disco. Los módulos pickle y marshal pueden convertir muchos tipos de datos de Python en un flujo de bytes y luego recrear los objetos a partir de los bytes. Los diversos módulos relacionados con DBM admiten una familia de formatos de archivo basados en hash que almacenan un mapeo de cadenas a otras cadenas.

La lista de módulos descritos en este capítulo es:

pickle — Serialización de objetos Python

Relación con otros módulos de Python

Comparación con marshal

Comparación con json

Formato de flujo de datos

Interfaz del módulo

¿Qué se puede serializar (pickled) y deserializar (unpickled) con pickle?

Pickling de Instancias de clases

Persistencia de objetos externos

Tablas de despacho

Manejo de objetos con estado

Reducción personalizada para tipos, funciones y otros objetos

Búferes fuera de banda

API de proveedor

API de consumidor

Ejemplo

Restricción de Globals

Performance

Ejemplos

copyreg — Registrar funciones de soporte de pickle

Ejemplo

shelve — Persistencia de objetos de Python

Restricciones

Ejemplo

marshal — Serialización interna de objetos Python

dbm — Interfaces para «bases de datos» de Unix

dbm.gnu — La reinterpretación de GNU de dbm

dbm.ndbm — Interfaz basada en ndbm

dbm.dumb — Implementación de DBM portátil

sqlite3 — DB-API 2.0 interfaz para bases de datos SQLite

Funciones y constantes del módulo

Objetos de conexión

Objetos Cursor

Objetos Fila (Row)

Excepciones

SQLite y tipos de Python

Introducción

Usando adaptadores para almacenar tipos adicionales de Python en bases de datos SQLite

Permitiéndole al objeto auto adaptarse

Registrando un adaptador invocable

Convertir valores SQLite a tipos de Python personalizados

Adaptadores y convertidores por defecto

Controlando Transacciones

Usando sqlite3 eficientemente

Usando métodos atajo

Accediendo a las columnas por el nombre en lugar del índice

Usando la conexión como un administrador de contexto

pickle — Serialización de objetos Python

Código fuente: Lib/pickle.py [https://github.com/python/cpython/tree/3.9/Lib/pickle.py]

El modulo pickle implementa protocolos binarios para serializar y deserializar una estructura de objetos Python. «Pickling» es el proceso mediante el cual una jerarquía de objetos de Python se convierte en una secuencia de bytes, y el «unpickling» es la operación inversa, mediante la cual una secuencia de bytes de un archivo binario (binary file) ó un objeto tipo binario (bytes-like object) es convertido nuevamente en una jerarquía de objetos. Pickling (y unpickling) son alternativamente conocidos como «serialización», «ensamblaje,» 1 o «aplanamiento»; sin embargo, para evitar confusiones, los términos utilizados aquí son «pickling» y «unpickling».

Advertencia

El modulo pickle no es seguro. Solo deserialize con pickle los datos en los que confía.

Es posible construir datos maliciosos con pickle que ejecuten código arbitrario durante el proceso de `unpickling`. Nunca deserialize datos con pickle que podrían haber venido de una fuente no confiable, o que podrían haber sido manipulados.

Considere firmar los datos con hmac si necesita asegurarse de que no hayan sido alterados.

Los formatos de serialización más seguros como json pueden ser más apropiados si está procesando datos no confiables. Ver Comparación con json.

Relación con otros módulos de Python

Comparación con marshal

Python tiene un módulo de serialización más primitivo llamado marshal, pero en general pickle debería ser siempre la forma preferida de serializar objetos de Python. marshal existe principalmente para soportar archivos Python .pyc.

El modulo pickle difiere de marshal en varias formas significativas:

El modulo pickle realiza un seguimiento de los objetos que ya ha serializado, para que las referencias posteriores al mismo objeto no se serializen nuevamente. marshal no hace esto.

Esto tiene implicaciones tanto para los objetos recursivos como para compartir objetos. Los objetos recursivos son objetos que contienen referencias a sí mismos. Marshal no los maneja y, de hecho, intentar agrupar objetos recursivos bloqueará su intérprete de Python. El intercambio de objetos ocurre cuando hay múltiples referencias al mismo objeto en diferentes lugares de la jerarquía de objetos que se serializan. pickle almacena dichos objetos solo una vez y garantiza que todas las demás referencias apunten a la copia maestra. Los objetos compartidos permanecen compartidos, lo cual puede ser muy importante para los objetos mutables.

marshal no se puede usar para serializar clases definidas por el usuario y sus instancias. pickle puede guardar y restaurar instancias de clase de forma transparente, sin embargo, la definición de clase debe ser importable y vivir en el mismo módulo que cuando se almacenó el objeto.

No se garantiza que el formato de serialización marshal sea portable a través de todas las versiones de Python. Debido a que su trabajo principal es dar soporte a archivos .pyc, los implementadores de Python se reservan el derecho de cambiar el formato de serialización de formas no compatibles con versiones anteriores si surge la necesidad. El formato de serialización pickle está garantizado para ser compatible con versiones anteriores de Python siempre que se elija un protocolo de pickle compatible y el serializado y deserializado de código con pickle se encargue de lidiar con las diferencias de tipos entre Python 2 y Python 3 si sus datos están cruzando ese limite único entre las versiones del lenguaje.

Comparación con json

Existen diferencias fundamentales entre los protocolos de pickle y JSON (acrónimo de JavaScript Object Notation, «notación de objeto de JavaScript») [http://json.org]:

JSON es un formato de serialización de texto (genera texto unicode, aunque la mayoría de las veces se codifica a utf-8), mientras que pickle es un formato de serialización binario;

JSON es legible por humanos, mientras que pickle no lo es;

JSON es interoperable y ampliamente utilizado fuera del ecosistema de Python, mientras que pickle es específico de Python;

JSON, por defecto, solo puede representar un subconjunto de los tipos integrados de Python, y no clases personalizadas; pickle puede representar un número extremadamente grande de tipos de Python (muchos de ellos automáticamente, mediante el uso inteligente de la introspección de objetos en Python; los casos complejos se pueden abordar implementando API de objetos específicos, specific object APIs);

A diferencia de pickle, deserializar JSON no confiable no crea en sí mismo una vulnerabilidad de ejecución de código arbitraria.

Ver también

El modulo json: un módulo de la biblioteca estándar que permite la serialización y deserialización de JSON.

Formato de flujo de datos

El formato de datos utilizado por pickle es específico de Python. Esto tiene la ventaja de que no hay restricciones impuestas por estándares externos como JSON o XDR (que no pueden representar el uso compartido de punteros); sin embargo, significa que los programas que no son de Python pueden no ser capaces de reconstruir objetos Python serialzados con pickle.

Por defecto, el formato de datos pickle utiliza una representación binaria relativamente compacta. Si necesita características de tamaño óptimas, puede eficientemente comprimir datos serializados con pickle.

El modulo pickletools contiene herramientas para analizar flujos de datos generados por pickle. El código fuente de pickletools tiene comentarios extensos sobre los códigos de operación utilizados por los protocolos de pickle.

Actualmente hay 6 protocolos diferentes que se pueden utilizar para serializar con pickle. Cuanto mayor sea el protocolo utilizado, más reciente será la versión de Python necesaria para leer el pickle producido.

La versión 0 del protocolo es el protocolo original «legible para humanos» y es compatible con versiones anteriores de Python.

La versión 1 del protocolo es un formato binario antiguo que también es compatible con versiones anteriores de Python.

Protocol version 2 was introduced in Python 2.3. It provides much more efficient pickling of new-style classes. Refer to PEP 307 [https://www.python.org/dev/peps/pep-0307] for information about improvements brought by protocol 2.

Se agregó la versión 3 del protocolo en Python 3.0. Tiene soporte explícito para objetos bytes y no puede ser deserializado con pickle por Python 2.x. Este era el protocolo predeterminado en Python 3.0–3.7.

Se agregó la versión 4 del protocolo en Python 3.4. Agrega soporte para objetos muy grandes, pickling de mas tipos de objetos y algunas optimizaciones de formato de datos. Es el protocolo predeterminado que comienza con Python 3.8. Consulte PEP 3154 [https://www.python.org/dev/peps/pep-3154] para obtener información sobre las mejoras aportadas por el protocolo 4.

Se agregó la versión 5 del protocolo en Python 3.8. Agrega soporte para datos fuera de banda y aceleración para datos dentro de banda. Consulte PEP 574 [https://www.python.org/dev/peps/pep-0574] para obtener información sobre las mejoras aportadas por el protocolo 5.

Nota

La serialización es una noción más primitiva que la persistencia; aunque pickle lee y escribe objetos de archivo, no maneja el problema de nombrar objetos persistentes, ni el problema (aún más complicado) de acceso concurrente a objetos persistentes. El módulo pickle puede transformar un objeto complejo en una secuencia de bytes y puede transformar la secuencia de bytes en un objeto con la misma estructura interna. Quizás lo más obvio que hacer con estos flujos de bytes es escribirlos en un archivo, pero también es concebible enviarlos a través de una red o almacenarlos en una base de datos. El módulo shelve proporciona una interfaz simple para serializar y deserializar objetos con pickle en archivos de bases de datos de estilo DBM.

Interfaz del módulo

Para serializar una jerarquía de objetos, simplemente llame a la función dumps(). De manera similar, para deserializar un flujo de datos, llama a la función loads(). Sin embargo, si desea tener más control sobre la serialización y la deserialización, puede crear un objeto Pickler o Unpickler, respectivamente.

El módulo pickle proporciona las siguientes constantes:

pickle.HIGHEST_PROTOCOL

Un entero, la versión de protocolo (protocol version) más alta disponible. Este valor se puede pasar como un valor de protocolo a las funciones dump() y dumps() así como al constructor Pickler.

pickle.DEFAULT_PROTOCOL

Un entero, la versión de protocolo (protocol version) predeterminada utilizada para el serializado con pickle. Puede ser menor que HIGHEST_PROTOCOL. Actualmente, el protocolo predeterminado es 4, introducido por primera vez en Python 3.4 e incompatible con versiones anteriores.

Distinto en la versión 3.0: El protocolo predeterminado es 3.

Distinto en la versión 3.8: El protocolo predeterminado es 4.

El módulo pickle proporciona las siguientes funciones para que el proceso de pickling sea más conveniente:

pickle.dump(obj, file, protocol=None, *, fix_imports=True, buffer_callback=None)

Escribe la representación pickle del objeto obj en el archivo abierto file object. Esto es equivalente a Pickler(file, protocol).dump(obj).

Los argumentos file, protocol, fix_imports y buffer_callback tienen el mismo significado que en el constructor Pickler.

Distinto en la versión 3.8: Se agregó el argumento buffer_callback.

pickle.dumps(obj, protocol=None, *, fix_imports=True, buffer_callback=None)

Retorna la representación pickle del objeto obj como un objeto bytes, en lugar de escribirlo en un archivo.

Los argumentos protocol, fix_imports y buffer_callback tienen el mismo significado que en el constructor Pickler.

Distinto en la versión 3.8: Se agregó el argumento buffer_callback.

pickle.load(file, *, fix_imports=True, encoding="ASCII", errors="strict", buffers=None)

Lee la representación pickle de un objeto desde un archivo abierto file object y retorna la jerarquía de objetos reconstituidos especificada en el mismo. Esto es equivalente a Unpickler(file).load().

La versión de protocolo del pickle se detecta automáticamente, por lo que no se necesita ningún argumento de protocolo. Los bytes más allá de la representación empaquetada son ignorados.

Los argumentos file, fix_imports, encoding, errors, strict y buffers tienen el mismo significado que en el constructor Unpickler.

Distinto en la versión 3.8: Se agregó el argumento buffers.

pickle.loads(data, /, *, fix_imports=True, encoding="ASCII", errors="strict", buffers=None)

Retorna la jerarquía de objetos reconstruida de la representación pickle data de un objeto. data debe ser un objeto tipo binario (bytes-like object).

La versión de protocolo del pickle se detecta automáticamente, por lo que no se necesita ningún argumento de protocolo. Los bytes más allá de la representación empaquetada son ignorados.

Arguments fix_imports, encoding, errors, strict and buffers have the same meaning as in the Unpickler constructor.

Distinto en la versión 3.8: Se agregó el argumento buffers.

El módulo pickle define tres excepciones:

exception pickle.PickleError

Clase base común para las otras excepciones de pickling. Hereda de Exception.

exception pickle.PicklingError

Error generado cuando Pickler encuentra un objeto que no se puede serializar con pickle . Hereda de PickleError.

Consulte ¿Qué se puede serializar (pickled) y deserializar (unpickled) con pickle? para aprender qué tipos de objetos se pueden serializar con pickle.

exception pickle.UnpicklingError

Se produce un error cuando hay un problema al deserializar un objeto con pickle, por ejemplo como una corrupción de datos o una violación de seguridad. Hereda de PickleError.

Tenga en cuenta que también se pueden generar otras excepciones durante la deserializacion con pickle, incluyendo (pero no necesariamente limitado a) AttributeError, EOFError, ImportError, e IndexError.

El módulo pickle exporta tres clases, Pickler, Unpickler y PickleBuffer:

class pickle.Pickler(file, protocol=None, *, fix_imports=True, buffer_callback=None)

Esto toma un archivo binario para escribir un flujo de datos de pickle.

El argumento opcional protocol , un entero, le dice al pickler que use el protocolo dado; los protocolos admitidos son 0 para HIGHEST_PROTOCOL. Si no se especifica, el valor predeterminado es DEFAULT_PROTOCOL. Si se especifica un número negativo, HIGHEST_PROTOCOL es seleccionado.

El argumento file debe tener un método write() que acepte un argumento de bytes individuales. Por lo tanto, puede ser un archivo en disco abierto para escritura binaria, una instancia io.BytesIO , o cualquier otro objeto personalizado que cumpla con esta interfaz.

Si fix_imports es verdadero y protocol es menor que 3, pickle intentará asignar los nuevos nombres de Python 3 a los nombres de módulos antiguos utilizados en Python 2, de modo que la secuencia de datos de pickle sea legible con Python 2.

Si buffer_callback es None (el valor predeterminado), las vistas de búfer se serializan en file como parte de la secuencia de pickle.

Si buffer_callback no es None, entonces se puede llamar cualquier número de veces con una vista de búfer. Si la callback retorna un valor falso (como None), el búfer dado está fuera de banda (out-of-band); de lo contrario, el búfer se serializa en banda, es decir, dentro del flujo de pickle.

Es un error si buffer_callback no es None y protocol es None o menor que 5.

Distinto en la versión 3.8: Se agregó el argumento buffer_callback.

dump(obj)

Escribe la representación serializada con pickle del objeto obj en el objeto archivo abierto dado en el constructor.

persistent_id(obj)

No hacer nada por defecto. Esto existe para que una subclase pueda sobreescribirlo.

Si persistent_id() retorna None, obj es serializado con pickle como siempre. Cualquier otro valor hace que Pickler emita el valor retornado como un ID persistente para obj. El significado de este ID persistente debe definirse por Unpickler.persistent_load(). Tenga en cuenta que el valor retornado por persistent_id() no puede tener una ID persistente.

Ver Persistencia de objetos externos para detalles y ejemplos de uso.

dispatch_table

La tabla de envío de un objeto Pickler es un registro de funciones de reducción del tipo que se puede declarar usando copyreg.pickle(). Es un mapeo cuyas claves son clases y cuyos valores son funciones de reducción. Una función de reducción toma un solo argumento de la clase asociada y debe ajustarse a la misma interfaz que un método __reduce__().

Por defecto, un objeto de pickle no tendrá un atributo dispatch_table, y en su lugar utilizará la tabla de despacho global administrada por el módulo copyreg. Sin embargo, para personalizar el pickling para un objeto de pickle específico, se puede establecer el atributo dispatch_table en un objeto tipo dict. Alternativamente, si una subclase de Pickler tiene un atributo dispatch_table esto se usará como la tabla de despacho predeterminada para instancias de esa clase.

Ver Tablas de despacho para ejemplos de uso.

Nuevo en la versión 3.3.

reducer_override(obj)

Reductor especial que se puede definir en subclases de Pickler. Este método tiene prioridad sobre cualquier reductor en dispatch_table. Debe cumplir con la misma interfaz que un método __reduce__(), y opcionalmente puede retornar NotImplemented para recurrir a reductores registrados en dispatch_table el objeto pickle obj.

Para un ejemplo detallado, ver Reducción personalizada para tipos, funciones y otros objetos.

Nuevo en la versión 3.8.

fast

Obsoleto. Habilite el modo rápido si se establece en un valor verdadero. El modo rápido deshabilita el uso de memo, por lo tanto, acelera el proceso de pickling al no generar códigos de operación PUT superfluos. No debe usarse con objetos autorreferenciales; de lo contrario, la clase Pickler se repetirá infinitamente.

Use pickletools.optimize() si necesita pickles más compactos.

class pickle.Unpickler(file, *, fix_imports=True, encoding="ASCII", errors="strict", buffers=None)

Esto toma un archivo binario para leer un flujo de datos de pickle.

La versión de protocolo de pickle se detecta automáticamente, por lo que no se necesita ningún argumento de protocolo.

El argumento file debe tener tres métodos, un método read() que toma un argumento entero, un método readinto() que toma un argumento búfer y un método readline() que no requiere argumentos, como en la interfaz io.BufferedIOBase. Por lo tanto file puede ser un archivo en disco abierto para lectura binaria, un objeto io.BytesIO, o cualquier otro objeto personalizado que cumpla con esta interfaz.

Los argumentos opcionales fix_imports, encoding and errors se utilizan para controlar el soporte de compatibilidad para el flujo de pickle generado por Python 2. Si fix_imports es verdadero, pickle intentará asignar los nombres antiguos de Python 2 a los nuevos nombres utilizados en Python 3. Tanto encoding como errors le indican a pickle cómo decodificar instancias de cadenas de 8 bits seleccionadas por Python 2; estos son predeterminados a “ASCII” y “strict”, respectivamente. encoding puede ser “bytes” para leer estas instancias de cadena de 8 bits como objetos de bytes. Se requiere el uso de encoding='latin1' para realizar el unpickling de arreglos de NumPy e instancias de datetime, date y time serializados con pickle por Python 2.

Si buffers es None (el valor predeterminado), todos los datos necesarios para la deserialización deben estar contenidos en el flujo de pickle. Esto significa que el argumento buffer_callback era None cuando se instanciaba una clase Pickler (o cuando se llamaba a dump() o dumps()).

Si buffers no es None, debería ser un iterable de objetos habilitados para almacenamiento intermedio que se consumen cada vez que el flujo de pickle hace referencia a una vista de buffer fuera de banda (out-of-band). Tales buffers se han dado para el buffer_callback de un objeto Pickler.

Distinto en la versión 3.8: Se agregó el argumento buffers.

load()

Lee la representación serializada con pickle de un objeto desde el objeto de archivo abierto dado en el constructor, y retorne la jerarquía de objetos reconstituidos especificada allí. Los Bytes más allá de la representación serializada con pickle del objeto se ignoran.

persistent_load(pid)

Lanza un UnpicklingError de forma predeterminada.

Si se define, persistent_load() debería retornar el objeto especificado por el ID persistente pid. Si se encuentra un ID persistente no válido, se debe lanzar un UnpicklingError.

Ver Persistencia de objetos externos para detalles y ejemplos de uso.

find_class(module, name)

Importa module si es necesario y retorna el objeto llamado name desde el, donde los argumentos module y name son objetos de str. Tenga en cuenta que, a diferencia de lo que sugiere su nombre, find_class() también se usa para buscar funciones.

Las subclases pueden sobreescribir esto para obtener control sobre qué tipo de objetos y cómo se pueden cargar, reduciendo potencialmente los riesgos de seguridad. Consulte Restricción de Globals para obtener más detalles.

Lanza un auditing event pickle.find_class con argumentos module, name.

class pickle.PickleBuffer(buffer)

Un envoltorio (wrapper) para un búfer que representa datos serializables con pickle (picklable data). buffer debe ser un objeto que proporciona un búfer (buffer-providing), como objeto tipo binario (bytes-like object) o un arreglo N-dimensional.

PickleBuffer es en sí mismo un proveedor de búfer, por lo que es posible pasarlo a otras API que esperan un objeto que provea un búfer, como memoryview.

Los objetos PickleBuffer solo se pueden serializar usando el protocolo pickle 5 o superior. Son elegibles para serialización fuera de banda (out-of-band serialization).

Nuevo en la versión 3.8.

raw()

Retorna un memoryview del área de memoria subyacente a este búfer. El objeto retornado es una vista de memoria unidimensional, C-contigua con formato B (bytes sin firmar). BufferError es lanzado si el búfer no es contiguo a C ni a Fortran.

release()

Libera el búfer subyacente expuesto por el objeto PickleBuffer.

¿Qué se puede serializar (pickled) y deserializar (unpickled) con pickle?

Los siguientes tipos se pueden serializar con pickle (pickled):

None, True, and False;

integers, floating-point numbers, complex numbers;

strings, bytes, bytearrays;

tuples, lists, sets, and dictionaries containing only picklable objects;

functions (built-in and user-defined) defined at the top level of a module (using def, not lambda);

classes defined at the top level of a module;

instancias de tales clases cuyo __dict__ o el resultado de llamar a __getstate__() es serializable con pickle (picklable) (consulte la sección Pickling de Instancias de clases para obtener más detalles).

Los intentos de serializar objetos no serializables con pickle lanzaran la excepción PicklingError; cuando esto sucede, es posible que ya se haya escrito una cantidad no especificada de bytes en el archivo subyacente. Intentar serializar con pickle una estructura de datos altamente recursiva puede exceder la profundidad máxima de recursividad, en este caso se lanzará un RecursionError. Puede aumentar cuidadosamente este límite con sys.setrecursionlimit().

Note that functions (built-in and user-defined) are pickled by fully qualified name, not by value. 2 This means that only the function name is pickled, along with the name of the module the function is defined in. Neither the function’s code, nor any of its function attributes are pickled. Thus the defining module must be importable in the unpickling environment, and the module must contain the named object, otherwise an exception will be raised. 3

Similarly, classes are pickled by fully qualified name, so the same restrictions in the unpickling environment apply. Note that none of the class’s code or data is pickled, so in the following example the class attribute attr is not restored in the unpickling environment:

class Foo:
    attr = 'A class attribute'

picklestring = pickle.dumps(Foo)

These restrictions are why picklable functions and classes must be defined at the top level of a module.

De manera similar, cuando las instancias de clases son serializadas con pickle, el código y los datos de la clase no son serializadas junto con ella. Solo los datos de la instancia son serializados con pickle (pickled). Esto se hace a propósito, por lo que puede corregir errores en una clase o agregar métodos a la clase y aún cargar objetos que fueron creados con una versión anterior de la clase. Si planea tener objetos de larga duración que verán muchas versiones de una clase, puede valer la pena poner un número de versión en los objetos para que las conversiones adecuadas se puedan realizar mediante el método __setstate__().

Pickling de Instancias de clases

En esta sección, describimos los mecanismos generales disponibles para que usted defina, personalice y controle cómo se serializan y deserializan con Pickle las instancias de clase.

En la mayoría de los casos, no se necesita código adicional para hacer que las instancias sean picklable (serializables con pickle). Por defecto, pickle recuperará la clase y los atributos de una instancia a través de la introspección. Cuando una instancia de clase es deserializada con pickle (unpickled), su método __init__() generalmente no se invoca. El comportamiento predeterminado es que primero crea una instancia no inicializada y luego restaura los atributos guardados. El siguiente código muestra una implementación de este comportamiento:

def save(obj):
    return (obj.__class__, obj.__dict__)

def restore(cls, attributes):
    obj = cls.__new__(cls)
    obj.__dict__.update(attributes)
    return obj

Las clases pueden alterar el comportamiento predeterminado proporcionando uno o varios métodos especiales:

object.__getnewargs_ex__()

En los protocolos 2 y más recientes, las clases que implementan el método __getnewargs_ex__() pueden dictar los valores pasados al método __new__() al hacer`unpickling`. El método debe retornar un par (args, kwargs) donde args es una tupla de argumentos posicionales y kwargs un diccionario de argumentos con nombre para construir el objeto. Estos se pasarán al método __new__() al hacer unpickling.

Debes implementar este método si el método __new__() de tu clase requiere argumentos de solo palabras clave. De lo contrario, se recomienda para la compatibilidad implementar __getnewargs__().

Distinto en la versión 3.6: __getnewargs_ex__() ahora se usa en los protocolos 2 y 3.

object.__getnewargs__()

Este método tiene un propósito similar a __getnewargs_ex__(), pero solo admite argumentos posicionales. Debe retornar una tupla de argumentos args que se pasarán al método __new__() al hacer unpickling.

__getnewargs__() no se llamará si __getnewargs_ex__() está definido.

Distinto en la versión 3.6: Antes de Python 3.6, se llamaba a, __getnewargs__() en lugar de __getnewargs_ex__() en los protocolos 2 y 3.

object.__getstate__()

Las clases pueden influir aún más en cómo sus instancias se serializan con pickle; si la clase define el método __getstate__(), este es llamado y el objeto retornado se selecciona como contenido de la instancia, en lugar del contenido del diccionario de la instancia. Si el método __getstate__() está ausente, el __dict__ de la instancia se conserva como de costumbre.

object.__setstate__(state)

Al hacer unpickling, si la clase define __setstate__(), este es llamado con el estado unpickled (no serializado con pickle). En ese caso, no es necesario que el objeto de estado sea un diccionario. De lo contrario, el estado pickled (pickled state) debe ser un diccionario y sus elementos se asignan al diccionario de la nueva instancia.

Nota

Si __getstate__() retorna un valor falso, el método __setstate__() no se llamará al hacer unpickling.

Consulte la sección Manejo de objetos con estado para obtener más información sobre cómo utilizar los métodos __getstate__() y __setstate__().

Nota

Al momento de hacer unpickling, algunos métodos como __getattr__(), __getattribute__(), o __setattr__() pueden invocarse sobre la instancia. En caso de que esos métodos dependan de que algún invariante interno sea verdadero, el tipo debería implementar __new__() para establecer tal invariante, ya que __init__() no se llama cuando se hace unpickling de una instancia.

Como veremos, pickle no utiliza directamente los métodos descritos anteriormente. De hecho, estos métodos son parte del protocolo de copia que implementa el método especial __reduce__(). El protocolo de copia proporciona una interfaz unificada para recuperar los datos necesarios para hacer el pickling y la copia de objetos. 4

Aunque es poderoso, implementar __reduce__() directamente en sus clases es propenso a errores. Por esta razón, los diseñadores de clases deben usar la interfaz de alto nivel (es decir, __getnewargs_ex__(), __getstate__() y __setstate__()) siempre que sea posible. Sin embargo, mostraremos casos en los que usar __reduce__() es la única opción o conduce a un pickling más eficiente o ambos.

object.__reduce__()

La interfaz se define actualmente de la siguiente manera. El método __reduce__() no toma ningún argumento y retornará una cadena o preferiblemente una tupla (el objeto retornado a menudo se denomina «valor reducido»).

Si se retorna una cadena, la cadena debe interpretarse como el nombre de una variable global. Debe ser el nombre local del objeto relativo a su módulo; el módulo pickle busca en el espacio de nombres del módulo para determinar el módulo del objeto. Este comportamiento suele ser útil para singletons.

Cuando se retorna una tupla, debe tener entre dos y seis elementos. Los elementos opcionales se pueden omitir o se puede proporcionar None como su valor. La semántica de cada elemento está en orden:

Un objeto invocable que se llamará para crear la versión inicial del objeto.

Una tupla de argumentos para el objeto invocable. Se debe proporcionar una tupla vacía si el invocable no acepta ningún argumento.

Opcionalmente, el estado del objeto, que se pasará al método __setstate__() del objeto como se describió anteriormente. Si el objeto no tiene dicho método, el valor debe ser un diccionario y se agregará al atributo __dict__ del objeto.

Opcionalmente, un iterador (y no una secuencia) produce elementos sucesivos. Estos elementos se agregarán al objeto usando obj.append(item) o, por lotes, usando obj.extend(list_of_items). Esto se usa principalmente para subclases de lista, pero puede ser usado por otras clases siempre que tengan los métodos append() y extend() con la firma apropiada. (El uso de append() o extend() depende de la versión del protocolo pickle que se use, así como de la cantidad de elementos que se agregarán, por lo que ambos deben ser soportados.)

Opcionalmente, un iterador (no una secuencia) que produce pares clave-valor sucesivos. Estos elementos se almacenarán en el objeto usando obj[key] = value. Esto se usa principalmente para subclases de diccionario, pero otras clases pueden usarlo siempre que implementen __setitem__().

Opcionalmente, un invocable con una firma (obj, state). Este invocable permite al usuario controlar programáticamente el comportamiento de actualización de estado de un objeto específico, en lugar de usar el método estático de obj __setstate__(). Si no es None, este invocable tendrá prioridad sobre obj’s __setstate__().

Nuevo en la versión 3.8: Se agregó el sexto elemento opcional de tupla (obj, state).

object.__reduce_ex__(protocol)

Alternativamente, se puede definir un método __reduce_ex__(). La única diferencia es que este método debe tomar un único argumento entero, la versión del protocolo. Cuando esté definido, pickle lo preferirá en lugar del método __reduce__(). Además, __reduce__() se convierte automáticamente en sinónimo de la versión extendida. El uso principal de este método es proporcionar valores reducidos compatibles con versiones anteriores para versiones anteriores de Python.

Persistencia de objetos externos

Para el beneficio de la persistencia del objeto, el módulo pickle admite la noción de una referencia a un objeto fuera del flujo de datos serializados con pickle. Dichos objetos son referenciados por un ID persistente, que debe ser una cadena de caracteres alfanuméricos (para el protocolo 0) 5 o simplemente un objeto arbitrario (para cualquier protocolo más nuevo).

La resolución de tales ID persistentes no está definida por el módulo pickle; delegará esta resolución a los métodos definidos por el usuario en el pickler y el unpickler, persistent_id() y persistent_load() respectivamente.

Para seleccionar objetos que tienen una ID persistente externo, el pickler debe tener un método personalizado persistent_id() que toma un objeto como argumento y retorna None o el ID persistente para ese objeto. Cuando se retorna None, el pickler simplemente serializará el objeto de forma normal. Cuando se retorna una cadena de identificación persistente, el pickler serializará ese objeto, junto con un marcador para que el unpickler lo reconozca como una identificación persistente.

Para hacer el unpickling objetos externos, el unpickler debe tener un método personalizado persistent_load() que toma un objeto de identificación persistente y retorna el objeto referenciado.

Aquí hay un ejemplo completo que presenta cómo se puede usar la identificación persistente para hacer el pickling objetos externos por referencia.

# Simple example presenting how persistent ID can be used to pickle
# external objects by reference.

import pickle
import sqlite3
from collections import namedtuple

# Simple class representing a record in our database.
MemoRecord = namedtuple("MemoRecord", "key, task")

class DBPickler(pickle.Pickler):

    def persistent_id(self, obj):
        # Instead of pickling MemoRecord as a regular class instance, we emit a
        # persistent ID.
        if isinstance(obj, MemoRecord):
            # Here, our persistent ID is simply a tuple, containing a tag and a
            # key, which refers to a specific record in the database.
            return ("MemoRecord", obj.key)
        else:
            # If obj does not have a persistent ID, return None. This means obj
            # needs to be pickled as usual.
            return None

class DBUnpickler(pickle.Unpickler):

    def __init__(self, file, connection):
        super().__init__(file)
        self.connection = connection

    def persistent_load(self, pid):
        # This method is invoked whenever a persistent ID is encountered.
        # Here, pid is the tuple returned by DBPickler.
        cursor = self.connection.cursor()
        type_tag, key_id = pid
        if type_tag == "MemoRecord":
            # Fetch the referenced record from the database and return it.
            cursor.execute("SELECT * FROM memos WHERE key=?", (str(key_id),))
            key, task = cursor.fetchone()
            return MemoRecord(key, task)
        else:
            # Always raises an error if you cannot return the correct object.
            # Otherwise, the unpickler will think None is the object referenced
            # by the persistent ID.
            raise pickle.UnpicklingError("unsupported persistent object")

def main():
    import io
    import pprint

    # Initialize and populate our database.
    conn = sqlite3.connect(":memory:")
    cursor = conn.cursor()
    cursor.execute("CREATE TABLE memos(key INTEGER PRIMARY KEY, task TEXT)")
    tasks = (
        'give food to fish',
        'prepare group meeting',
        'fight with a zebra',
        )
    for task in tasks:
        cursor.execute("INSERT INTO memos VALUES(NULL, ?)", (task,))

    # Fetch the records to be pickled.
    cursor.execute("SELECT * FROM memos")
    memos = [MemoRecord(key, task) for key, task in cursor]
    # Save the records using our custom DBPickler.
    file = io.BytesIO()
    DBPickler(file).dump(memos)

    print("Pickled records:")
    pprint.pprint(memos)

    # Update a record, just for good measure.
    cursor.execute("UPDATE memos SET task='learn italian' WHERE key=1")

    # Load the records from the pickle data stream.
    file.seek(0)
    memos = DBUnpickler(file, conn).load()

    print("Unpickled records:")
    pprint.pprint(memos)

if __name__ == '__main__':
    main()

Tablas de despacho

Si se desea personalizar el pickling de algunas clases sin alterar ningún otro código que dependa del pickling, se puede crear un pickler con una tabla de despacho privada.

La tabla de despacho global administrada por el módulo copyreg está disponible como copyreg.dispatch_table. Por lo tanto, se puede optar por utilizar una copia modificada de copyreg.dispatch_table como tabla de envío privada.

Por ejemplo

f = io.BytesIO()
p = pickle.Pickler(f)
p.dispatch_table = copyreg.dispatch_table.copy()
p.dispatch_table[SomeClass] = reduce_SomeClass

crea una instancia de pickle.Pickler con una tabla de despacho privada que maneja la clase AlgunaClase especialmente. Alternativamente, el código

class MyPickler(pickle.Pickler):
    dispatch_table = copyreg.dispatch_table.copy()
    dispatch_table[SomeClass] = reduce_SomeClass
f = io.BytesIO()
p = MyPickler(f)

does the same but all instances of MyPickler will by default share the private dispatch table. On the other hand, the code

copyreg.pickle(SomeClass, reduce_SomeClass)
f = io.BytesIO()
p = pickle.Pickler(f)

modifies the global dispatch table shared by all users of the copyreg module.

Manejo de objetos con estado

Aquí hay un ejemplo que muestra cómo modificar el comportamiento del pickling de una clase. La clase TextReader abre un archivo de texto y retorna el número de línea y el contenido de la línea cada vez que se llama a su método readline() . Si se selecciona una instancia de TextReader se guardan todos los atributos excepto el miembro del objeto de archivo. Cuando se hace el unpickling de la instancia, el archivo se vuelve a abrir y la lectura se reanuda desde la última ubicación. Los métodos __setstate__() y __getstate__() se utilizan para implementar este comportamiento.

class TextReader:
    """Print and number lines in a text file."""

    def __init__(self, filename):
        self.filename = filename
        self.file = open(filename)
        self.lineno = 0

    def readline(self):
        self.lineno += 1
        line = self.file.readline()
        if not line:
            return None
        if line.endswith('\n'):
            line = line[:-1]
        return "%i: %s" % (self.lineno, line)

    def __getstate__(self):
        # Copy the object's state from self.__dict__ which contains
        # all our instance attributes. Always use the dict.copy()
        # method to avoid modifying the original state.
        state = self.__dict__.copy()
        # Remove the unpicklable entries.
        del state['file']
        return state

    def __setstate__(self, state):
        # Restore instance attributes (i.e., filename and lineno).
        self.__dict__.update(state)
        # Restore the previously opened file's state. To do so, we need to
        # reopen it and read from it until the line count is restored.
        file = open(self.filename)
        for _ in range(self.lineno):
            file.readline()
        # Finally, save the file.
        self.file = file

Un ejemplo de uso podría ser algo como esto:

>>> reader = TextReader("hello.txt")
>>> reader.readline()
'1: Hello world!'
>>> reader.readline()
'2: I am line number two.'
>>> new_reader = pickle.loads(pickle.dumps(reader))
>>> new_reader.readline()
'3: Goodbye!'

Reducción personalizada para tipos, funciones y otros objetos

Nuevo en la versión 3.8.

A veces, dispatch_table puede no ser lo suficientemente flexible. En particular, es posible que deseemos personalizar el pickling en función de otro criterio que no sea el tipo de objeto, o es posible que deseemos personalizar el pickling de funciones y clases.

Para esos casos, es posible crear una subclase de la clase Pickler e implementar el método reducer_override(). Este método puede retornar una tupla de reducción arbitraria (ver __reduce__()). Alternativamente, puede retornar NotImplemented para volver al comportamiento tradicional.

Si se definen tanto dispatch_table como reducer_override(), entonces reducer_override() tiene prioridad.

Nota

Por motivos de rendimiento, no se puede llamar a reducer_override() para los siguientes objetos: None, True, False, e instancias exactas de int, float, bytes, str, dict, set, frozenset, list y tuple.

Aquí hay un ejemplo simple donde permitimos el pickling y reconstruir una clase dada class:

import io
import pickle

class MyClass:
    my_attribute = 1

class MyPickler(pickle.Pickler):
    def reducer_override(self, obj):
        """Custom reducer for MyClass."""
        if getattr(obj, "__name__", None) == "MyClass":
            return type, (obj.__name__, obj.__bases__,
                          {'my_attribute': obj.my_attribute})
        else:
            # For any other object, fallback to usual reduction
            return NotImplemented

f = io.BytesIO()
p = MyPickler(f)
p.dump(MyClass)

del MyClass

unpickled_class = pickle.loads(f.getvalue())

assert isinstance(unpickled_class, type)
assert unpickled_class.__name__ == "MyClass"
assert unpickled_class.my_attribute == 1

Búferes fuera de banda

Nuevo en la versión 3.8.

En algunos contextos, el módulo pickle se usa para transferir cantidades masivas de datos. Por lo tanto, puede ser importante minimizar el número de copias de memoria para preservar el rendimiento y el consumo de recursos. Sin embargo, el funcionamiento normal del módulo pickle, ya que transforma una estructura gráfica de objetos en un flujo secuencial de bytes, implica intrínsecamente copiar datos hacia y desde el flujo pickle.

Esta restricción puede evitarse si tanto el proveedor (la implementación de los tipos de objeto a transferir) como el consumidor (a implementación del sistema de comunicaciones) admiten las facilidades de transferencia fuera de banda proporcionadas por el protocolo pickle 5 y mayor.

API de proveedor

Los objetos de datos grandes que se van a serializar con pickle deben implementar un método __reduce_ex__() especializado para el protocolo 5 y superior, que retorna una instancia de PickleBuffer (en lugar de, por ejemplo, un objeto bytes object) para cualquier datos.

Un objeto PickleBuffer indica que el búfer subyacente es elegible para la transferencia de datos fuera de banda. Estos objetos siguen siendo compatibles con el uso normal del módulo pickle . Sin embargo, los consumidores también pueden optar por decirle a pickle que manejarán esos búferes por sí mismos.

API de consumidor

Un sistema de comunicaciones puede permitir el manejo personalizado de los objetos PickleBuffer generados al serializar un gráfico de objetos.

En el lado del envío, necesita pasar un argumento buffer_callback a Pickler (o a las funciones dump() o dumps()), que se llamará con cada PickleBuffer generado al hacer pickling del gráfico del objeto. Los búferes acumulados por buffer_callback no verán sus datos copiados en el flujo de pickle, solo se insertará un marcador barato.

En el lado receptor, necesita pasar un argumento buffers a Unpickler (o a las funciones load() o loads()), que es un iterable de los búferes que fueron pasado a buffer_callback. Ese iterable debería producir búferes en el mismo orden en que se pasaron a buffer_callback. Esos búferes proporcionarán los datos esperados por los reconstructores de los objetos cuyo pickling produjo los objetos originales PickleBuffer.

Entre el lado de envío y el lado de recepción, el sistema de comunicaciones es libre de implementar su propio mecanismo de transferencia para memorias intermedias fuera de banda. Las posibles optimizaciones incluyen el uso de memoria compartida o compresión dependiente del tipo de datos.

Ejemplo

Aquí hay un ejemplo trivial donde implementamos una subclase bytearray capaz de participar en el pickling de un búfer fuera de banda:

class ZeroCopyByteArray(bytearray):

    def __reduce_ex__(self, protocol):
        if protocol >= 5:
            return type(self)._reconstruct, (PickleBuffer(self),), None
        else:
            # PickleBuffer is forbidden with pickle protocols <= 4.
            return type(self)._reconstruct, (bytearray(self),)

    @classmethod
    def _reconstruct(cls, obj):
        with memoryview(obj) as m:
            # Get a handle over the original buffer object
            obj = m.obj
            if type(obj) is cls:
                # Original buffer object is a ZeroCopyByteArray, return it
                # as-is.
                return obj
            else:
                return cls(obj)

El reconstructor (el método de clase _reconstruct) retorna el objeto que proporciona el búfer si tiene el tipo correcto. Esta es una manera fácil de simular el comportamiento de copia cero en este ejemplo de juguete.

En el lado del consumidor, podemos serializar con pickle esos objetos de la forma habitual, que cuando no se serializan nos dará una copia del objeto original:

b = ZeroCopyByteArray(b"abc")
data = pickle.dumps(b, protocol=5)
new_b = pickle.loads(data)
print(b == new_b)  # True
print(b is new_b)  # False: a copy was made

Pero si pasamos un buffer_callback y luego retornamos los búferes acumulados al anular la serialización, podemos recuperar el objeto original:

b = ZeroCopyByteArray(b"abc")
buffers = []
data = pickle.dumps(b, protocol=5, buffer_callback=buffers.append)
new_b = pickle.loads(data, buffers=buffers)
print(b == new_b)  # True
print(b is new_b)  # True: no copy was made

Este ejemplo está limitado por el hecho de que bytearray asigna su propia memoria: no puedes crear una instancia de bytearray que esté respaldada por la memoria de otro objeto. Sin embargo, los tipos de datos de terceros, como las matrices NumPy no tienen esta limitación y permiten el uso de pickling de copia cero (o realizar la menor cantidad de copias posible) cuando se transfieren entre procesos o sistemas distintos.

Ver también

PEP 574 [https://www.python.org/dev/peps/pep-0574] – Protocolo Pickle 5 con datos fuera de banda

Restricción de Globals

De forma predeterminada, el unpickling importará cualquier clase o función que encuentre en los datos de pickle. Para muchas aplicaciones, este comportamiento es inaceptable, ya que permite al unpickler importar e invocar código arbitrario. Solo considere lo que hace este flujo de datos de pickle hechos a mano cuando se carga:

>>> import pickle
>>> pickle.loads(b"cos\nsystem\n(S'echo hello world'\ntR.")
hello world
0

En este ejemplo, el unpickler importa la función os.system() y luego aplica el argumento de cadena «echo hello world». Aunque este ejemplo es inofensivo, no es difícil imaginar uno que pueda dañar su sistema.

Por esta razón, es posible que desee controlar lo que se deserializa con pickle personalizando Unpickler.find_class(). A diferencia de lo que sugiere su nombre, Unpickler.find_class() se llama siempre que se solicita un global (es decir, una clase o una función). Por lo tanto, es posible prohibir completamente los globales o restringirlos a un subconjunto seguro.

Aquí hay un ejemplo de un unpickler que permite cargar solo unas pocas clases seguras del módulo builtins:

import builtins
import io
import pickle

safe_builtins = {
    'range',
    'complex',
    'set',
    'frozenset',
    'slice',
}

class RestrictedUnpickler(pickle.Unpickler):

    def find_class(self, module, name):
        # Only allow safe classes from builtins.
        if module == "builtins" and name in safe_builtins:
            return getattr(builtins, name)
        # Forbid everything else.
        raise pickle.UnpicklingError("global '%s.%s' is forbidden" %
                                     (module, name))

def restricted_loads(s):
    """Helper function analogous to pickle.loads()."""
    return RestrictedUnpickler(io.BytesIO(s)).load()

A sample usage of our unpickler working as intended:

>>> restricted_loads(pickle.dumps([1, 2, range(15)]))
[1, 2, range(0, 15)]
>>> restricted_loads(b"cos\nsystem\n(S'echo hello world'\ntR.")
Traceback (most recent call last):
  ...
pickle.UnpicklingError: global 'os.system' is forbidden
>>> restricted_loads(b'cbuiltins\neval\n'
...                  b'(S\'getattr(__import__("os"), "system")'
...                  b'("echo hello world")\'\ntR.')
Traceback (most recent call last):
  ...
pickle.UnpicklingError: global 'builtins.eval' is forbidden

Como muestran nuestros ejemplos, debes tener cuidado con lo que permites que se deserialize con pickle. Por lo tanto, si la seguridad es un problema, puede considerar alternativas como la API de marshalling en xmlrpc.client o soluciones de terceros.

Performance

Las versiones recientes del protocolo pickle (desde el protocolo 2 en adelante) cuentan con codificaciones binarias eficientes para varias características comunes y tipos integrados. Además, el módulo pickle tiene un optimizador transparente escrito en C.

Ejemplos

Para obtener el código más simple, use las funciones dump() y load().

import pickle

# An arbitrary collection of objects supported by pickle.
data = {
    'a': [1, 2.0, 3+4j],
    'b': ("character string", b"byte string"),
    'c': {None, True, False}
}

with open('data.pickle', 'wb') as f:
    # Pickle the 'data' dictionary using the highest protocol available.
    pickle.dump(data, f, pickle.HIGHEST_PROTOCOL)

El siguiente ejemplo lee los datos serializados con pickle resultantes.

import pickle

with open('data.pickle', 'rb') as f:
    # The protocol version used is detected automatically, so we do not
    # have to specify it.
    data = pickle.load(f)

Ver también

Módulo copyreg

Registro de constructor de interfaz Pickle para tipos de extensión.

Módulo pickletools

Herramientas para trabajar y analizar datos serializados con pickle.

Módulo shelve

Bases de datos indexadas de objetos; usa pickle.

Module copy

Copia de objetos superficial y profunda.

Módulo marshal

Serialización de alto rendimiento de tipos integrados.

Notas al pie

1

No confunda esto con el módulo marshal

2

Esta es la razón por la que las funciones lambda no se pueden serializar con pickle: todas las funciones lambda comparten el mismo nombre: <lambda>.

3

La excepción generada probablemente será un ImportError o un AttributeError pero podría ser otra cosa.

4

El módulo copy utiliza este protocolo para operaciones de copia superficial y profunda.

5

The limitation on alphanumeric characters is due to the fact that persistent IDs in protocol 0 are delimited by the newline character. Therefore if any kind of newline characters occurs in persistent IDs, the resulting pickled data will become unreadable.

copyreg — Registrar funciones de soporte de pickle

Código fuente: Lib/copyreg.py [https://github.com/python/cpython/tree/3.9/Lib/copyreg.py]

El módulo copyreg ofrece una manera de definir funciones usada cuando se serializan (pickling) objectos específicos.Los módulos pickle y copy utilizan estas funciones cuando se realizan acciones de serializado/copiado en esos objetos. El módulo provee información de configuración acerca de los objetos constructores, los cuales no son clases. Estos objetos constructores pueden ser funciones de fábrica o instancias de clase.

copyreg.constructor(object)

Declara que el object debe ser un constructor válido. Si el object no es invocable (y por lo tanto, no es válido como constructor), lanza una excepción TypeError.

copyreg.pickle(type, function, constructor=None)

Declara que la function deber ser usada como una función de «reducción» para objetos de tipo type. La function debe retornar ya sea una cadena de caracteres o una tupla que contenga dos o tres elementos.

The optional constructor parameter, if provided, is a callable object which can be used to reconstruct the object when called with the tuple of arguments returned by function at pickling time. A TypeError is raised if the constructor is not callable.

Consulte el módulo pickle para más detalles sobre la interfaz esperada de function y constructor. Note que el atributo dispatch_table de un objeto pickler o subclase de pickle.Pickler puede también ser utilizado para declarar funciones de reducción.

Ejemplo

El siguiente ejemplo pretende mostrar cómo registrar una función pickle y cómo se utilizará:

>>> import copyreg, copy, pickle
>>> class C:
...     def __init__(self, a):
...         self.a = a
...
>>> def pickle_c(c):
...     print("pickling a C instance...")
...     return C, (c.a,)
...
>>> copyreg.pickle(C, pickle_c)
>>> c = C(1)
>>> d = copy.copy(c)
pickling a C instance...
>>> p = pickle.dumps(c)
pickling a C instance...

shelve — Persistencia de objetos de Python

Source code: Lib/shelve.py [https://github.com/python/cpython/tree/3.9/Lib/shelve.py]

Un «estante» o shelve, es un objeto persistente similar a un diccionario. La diferencia con las bases de datos «dbm» es que los valores (¡no las claves!) en un estante pueden ser esencialmente objetos Python arbitrarios — cualquier cosa que el módulo pickle pueda manejar. Esto incluye la mayoría de las instancias de clase, tipos de datos recursivos y objetos que contienen muchos subobjetos compartidos. Las claves son cadenas ordinarias.

shelve.open(filename, flag='c', protocol=None, writeback=False)

Abre un diccionario persistente. El nombre de archivo especificado es el nombre de archivo base para la base de datos subyacente. Como efecto secundario, se puede agregar una extensión al nombre de archivo y se puede crear más de un archivo. De forma predeterminada, el archivo de base de datos subyacente se abre para leer y escribir. El parámetro opcional flag tiene la misma interpretación que el parámetro flag de dbm.open().

De forma predeterminada, los pickles de la versión 3 se utilizan para serializar valores. La versión del protocolo pickle se puede especificar con el parámetro protocol.

Debido a la semántica de Python, un estante no puede saber cuándo se modifica una entrada de diccionario persistente mutable. De forma predeterminada, los objetos modificados se escriben sólo cuando se asignan al estante (consulte Ejemplo). Si el parámetro opcional writeback se establece en True, todas las entradas a las que se accede también se almacenan en caché en la memoria y se vuelven a escribir en sync() y close(); esto puede hacer que sea más práctico mutar entradas mutables en el diccionario persistente, pero, si se accede a muchas entradas, puede consumir grandes cantidades de memoria para la memoria caché, y puede hacer que la operación de cierre sea muy lenta ya que todas las entradas a las que se accede se vuelven a escribir (no hay manera de determinar qué entradas a las que se accede son mutables, ni cuáles se mutaron realmente).

Nota

No confíe en que el estante se cerrará automáticamente; siempre llame a close() explícitamente cuando ya no lo necesite, o use shelve.open() como administrador de contexto:

with shelve.open('spam') as db:
    db['eggs'] = 'eggs'

Advertencia

Debido a que el módulo shelve está respaldado por pickle, es inseguro cargar un estante desde una fuente que no es de confianza. Al igual que con el pickle, cargar un estante puede ejecutar código arbitrario.

Shelf objects support most of methods and operations supported by dictionaries (except copying, constructors and operators | and |=). This eases the transition from dictionary based scripts to those requiring persistent storage.

Se admiten dos métodos adicionales:

Shelf.sync()

Escriba todas las entradas en la caché si el estante se abrió con writeback establecido en True. También vacíe la caché y sincronice el diccionario persistente en el disco, si es posible. Esto se llama automáticamente cuando el estante se cierra con close().

Shelf.close()

Sincronice y cierre el objeto persistente dict. Las operaciones en un estante cerrado fallarán con un ValueError.

Ver también

Receta de diccionario persistente <https://code.activestate.com/recipes/576642/> _ con formatos de almacenamiento ampliamente compatibles y con la velocidad de los diccionarios nativos.

Restricciones

La elección de qué paquete de base de datos se utilizará (como dbm.ndbm o dbm.gnu) depende de la interfaz disponible. Por lo tanto, no es seguro abrir la base de datos directamente usando dbm. La base de datos también está (desafortunadamente) sujeta a las limitaciones de dbm, si se usa — esto significa que (la representación pickle de) los objetos almacenados en la base de datos debe ser bastante pequeña, y en casos raros las colisiones de claves pueden hacer que la base de datos rechace las actualizaciones.

El módulo shelve no admite el acceso concurrent de lectura/escritura a los objetos almacenados. (Los accesos de lectura múltiples simultáneos son seguros). Cuando un programa tiene un estante abierto para escritura, ningún otro programa debe tenerlo abierto para lectura o escritura. El bloqueo de archivos Unix se puede usar para resolver esto, pero esto difiere entre las versiones de Unix y requiere conocimiento sobre la implementación de la base de datos utilizada.

class shelve.Shelf(dict, protocol=None, writeback=False, keyencoding='utf-8')

Una subclase de collections.abc.MutableMapping que almacena valores pickle en el objeto dict.

De forma predeterminada, los pickles de la versión 3 se utilizan para serializar valores. La versión del protocolo pickle se puede especificar con el parámetro protocol. Vea la documentación de pickle para una discusión de los protocolos de pickle.

Si el parámetro writeback es True, el objeto mantendrá un caché de todas las entradas a las que se accedió y las volverá a escribir en el dict en las horas de sincronización y cierre. Esto permite operaciones naturales en entradas mutables, pero puede consumir mucha más memoria y hacer que la sincronización y el cierre tomen mucho tiempo.

El parámetro keyencoding es la codificación utilizada para codificar las claves antes de que se utilicen con el dict subyacente.

El objeto Shelf también se puede utilizar como administrador de contexto, en cuyo caso se cerrará automáticamente cuando finalice el bloque with.

Distinto en la versión 3.2: Se agregó el parámetro keyencoding; anteriormente, las claves siempre estaban codificadas en UTF-8.

Distinto en la versión 3.4: Agregado soporte para administrador de contexto.

class shelve.BsdDbShelf(dict, protocol=None, writeback=False, keyencoding='utf-8')

Una subclase de Shelf que expone first(), next(), previous(), last() y set_location() que están disponibles en el módulo de terceros bsddb de pybsddb [https://www.jcea.es/programacion/pybsddb.htm] pero no en otros módulos de base de datos. El objeto dict que se pasa al constructor debe admitir esos métodos. Esto se logra generalmente llamando a uno de los siguientes bsddb.hashopen(), bsddb.btopen() o bsddb.rnopen(). Los parámetros opcionales protocol, writeback y keyencoding tienen la misma interpretación que para la clase Shelf.

class shelve.DbfilenameShelf(filename, flag='c', protocol=None, writeback=False)

Una subclase de Shelf que acepta un filename en lugar de un objeto tipo diccionario (dict). El archivo subyacente se abrirá usando dbm.open(). De forma predeterminada, el archivo se creará y se abrirá tanto para lectura como para escritura. El parámetro opcional flag tiene la misma interpretación que para la función open(). Los parámetros opcionales protocol y writeback tienen la misma interpretación que para la clase Shelf.

Ejemplo

Para resumir la interfaz (key es una cadena de caracteres, data es un objeto arbitrario):

import shelve

d = shelve.open(filename)  # open -- file may get suffix added by low-level
                           # library

d[key] = data              # store data at key (overwrites old data if
                           # using an existing key)
data = d[key]              # retrieve a COPY of data at key (raise KeyError
                           # if no such key)
del d[key]                 # delete data stored at key (raises KeyError
                           # if no such key)

flag = key in d            # true if the key exists
klist = list(d.keys())     # a list of all existing keys (slow!)

# as d was opened WITHOUT writeback=True, beware:
d['xx'] = [0, 1, 2]        # this works as expected, but...
d['xx'].append(3)          # *this doesn't!* -- d['xx'] is STILL [0, 1, 2]!

# having opened d without writeback=True, you need to code carefully:
temp = d['xx']             # extracts the copy
temp.append(5)             # mutates the copy
d['xx'] = temp             # stores the copy right back, to persist it

# or, d=shelve.open(filename,writeback=True) would let you just code
# d['xx'].append(5) and have it work as expected, BUT it would also
# consume more memory and make the d.close() operation slower.

d.close()                  # close it

Ver también

Módulo dbm

Interfaz genérica para bases de datos estilo dbm.

Módulo pickle

Serialización de objetos utilizada por shelve.

marshal — Serialización interna de objetos Python

Este módulo contiene funciones que pueden leer y escribir valores de Python en un formato binario. El formato es específico de Python, pero independiente de los problemas de arquitectura de la máquina (por ejemplo, puede escribir un valor de Python en un archivo en un PC, transportar el archivo a un Sun y leerlo allí). Los detalles del formato están indocumentados a propósito; pueden cambiar entre las versiones de Python (aunque rara vez lo hacen). 1

Este no es un módulo general de «persistencia». Para la persistencia general y la transferencia de objetos Python a través de llamadas RPC, consulte los módulos pickle y shelve. El módulo marshal existe principalmente para admitir la lectura y escritura del código «pseudocompilado» para los módulos Python de archivos .pyc. Por lo tanto, los mantenedores de Python se reservan el derecho de modificar el formato de cálculo de referencias de manera incompatible hacia atrás en caso de necesidad. Si va a serializar y deserializar objetos Python, utilice el módulo pickle en su lugar: el rendimiento es comparable, la independencia de la versión está garantizada y pickle admite una gama sustancialmente más amplia de objetos que marshal.

Advertencia

El módulo marshal no está destinado a ser seguro contra datos erróneos o construidos maliciosamente. Nunca deserializar con marshal los datos recibidos de una fuente no confiable o no autenticada.

No se admiten todos los tipos de objetos de Python; en general, este módulo solo puede escribir y leer objetos cuyo valor es independiente de una invocación concreta de Python. Se admiten los siguientes tipos: booleanos, enteros, números de punto flotante, números complejos, cadenas de caracteres, bytes, arrays de bytes (bytearray), tuplas, listas, conjuntos (set y frozenset), diccionarios y objetos de código, donde se debe entender que las tuplas, listas, conjuntos y diccionarios solo se admiten siempre que se admitan los valores contenidos en ellos mismos. Los singletons None, Ellipsis y StopIteration también pueden ser marshalled y unmarshalled. Para el formato versión inferior a 3, no se pueden escribir listas, conjuntos ni diccionarios recursivos (véase más adelante).

Hay funciones que leen/escriben archivos, así como funciones que operan en objetos similares a bytes.

El módulo define estas funciones:

marshal.dump(value, file[, version])

Escribe el valor en el archivo abierto. El valor debe ser un tipo admitido. El archivo debe ser un archivo binary file en el que se pueda escribir.

Si el valor tiene (o contiene un objeto que tiene) un tipo no admitido, se produce una excepción ValueError — pero los datos no utilizados también se escribirán en el archivo. El objeto no será leído correctamente por load().

El argumento version indica el formato de datos que dump debe usar (véase más adelante).

Raises an auditing event marshal.dumps with arguments value, version.

marshal.load(file)

Lee un valor del archivo abierto y lo retorna. Si no se lee ningún valor válido (por ejemplo, porque los datos tienen un formato de cálculo de referencias incompatible de una versión de Python diferente), lanza una excepción EOFError, ValueError o TypeError. El archivo debe ser un binary file habilitado para lectura.

Raises an auditing event marshal.load with no arguments.

Nota

Si un objeto que contiene un tipo no admitido se calcula con dump(), load() sustituirá None por el tipo «unmarshallable».

Distinto en la versión 3.9.7: This call used to raise a code.__new__ audit event for each code object. Now it raises a single marshal.load event for the entire load operation.

marshal.dumps(value[, version])

Retorna el objeto bytes que se escribiría en un archivo mediante dump(value, file). El valor debe ser un tipo admitido. Lanza una excepción ValueError si value tiene (o contiene un objeto que tiene) un tipo no admitido.

El argumento version indica el formato de datos que dumps debe usar (véase más adelante).

Raises an auditing event marshal.dumps with arguments value, version.

marshal.loads(bytes)

Convierte el objeto bytes-like object en un valor. Si no se encuentra ningún valor válido, lanza una excepción EOFError, ValueError o TypeError. Se omiten los bytes adicionales de la entrada.

Raises an auditing event marshal.loads with argument bytes.

Distinto en la versión 3.9.7: This call used to raise a code.__new__ audit event for each code object. Now it raises a single marshal.loads event for the entire load operation.

Además, se definen las siguientes constantes:

marshal.version

Indica el formato que utiliza el módulo. La versión 0 es el formato histórico, la versión 1 comparte cadenas internadas y la versión 2 utiliza un formato binario para los números de punto flotante. La versión 3 agrega compatibilidad con la creación de instancias de objetos y la recursividad. La versión actual es 4.

Notas al pie

1

El nombre de este módulo proviene de algunos términos utilizados por los diseñadores de Modula-3 (entre otros), que utilizan el término «marshalling» para el envío de datos de forma auto-contenida. Estrictamente hablando «marshalling», significa convertir algunos datos internos en un formato externo (por ejemplo, en un búfer RPC) y «unmarshalling» es el proceso inverso.

dbm — Interfaces para «bases de datos» de Unix

Código fuente: Lib/dbm/__init__.py [https://github.com/python/cpython/tree/3.9/Lib/dbm/__init__.py]

dbm es una interfaz genérica para variantes de la base de datos DBM — dbm.gnu o dbm.ndbm. Si ninguno de estos módulos son instalados, se utilizará la implementación lenta pero sencilla en el módulo dbm.dumb. Existe una interfaz de terceros [https://www.jcea.es/programacion/pybsddb.htm] para la Oracle Berkeley DB.

exception dbm.error

Una tupla que contiene las excepciones que pueden ser lanzadas por cada uno de los módulos soportados, con una excepción única también denominada dbm.error como el primer elemento — el último se usa cuando se genera dbm.error.

dbm.whichdb(filename)

Esta función intenta adivinar cuál de los varios módulos de base de datos simples disponibles — dbm.gnu, dbm.ndbm o dbm.dumb — deberán usarse para abrir un archivo.

Retorna uno de los siguientes valores: None si el archivo no se puede abrir porque no se puede leer o no existe; la cadena de caracteres vacía ('') si no se puede adivinar el formato del archivo; o una cadena de caracteres que contenga el nombre del módulo requerido, como 'dbm.ndbm' o 'dbm.gnu'.

dbm.open(file, flag='r', mode=0o666)

Abre el archivo file de la base de datos y retorna un objeto correspondiente.

Si el archivo de la base de datos existe, la función whichdb() es usada para determinar su tipo y el módulo apropiado se utiliza; sino existe, se utiliza el primer módulo listado anteriormente que se puede importar.

El argumento opcional flag puede ser:

Valor

Significado

'r'

Abre la base de datos existente solo para lectura (predeterminado)

'w'

Abre la base de datos existente para leer y escribir

'c'

Abre la base de datos para lectura y escritura, creándola si no existe

'n'

Siempre cree una base de datos nueva, vacía, abierta para lectura y escritura

El argumento opcional mode es el modo Unix del archivo, usado solamente cuando la base de datos tiene que ser creada. Su valor predeterminado es octal 0o666 (y será modificado por el umask vigente).

El objeto retornado por open() admite la misma funcionalidad básica que los diccionarios; las claves y sus valores correspondientes se pueden almacenar, recuperar y eliminar, y el operador in y el método keys() están disponibles, así como get() y setdefault().

Distinto en la versión 3.2: get() y setdefault() ya están disponibles en todos los módulos de base de datos.

Distinto en la versión 3.8: Al eliminar una clave de una base de datos de solo lectura lanza un error específico del módulo de la base de datos en lugar de KeyError.

La clave y los valores siempre se almacenan como bytes. Esto significa que cuando se utilizan cadenas de caracteres, se convierten implícitamente a la codificación predeterminada antes de almacenarse.

Estos objetos también admiten el uso en una instrucción with, que los cerrará automáticamente cuando termine.

Distinto en la versión 3.4: Se agregó soporte nativo para el protocolo de administración de contexto a los objetos retornados por open().

El siguiente ejemplo registra algunos nombres de host y un título correspondiente, y luego imprime el contenido de la base de datos:

import dbm

# Open database, creating it if necessary.
with dbm.open('cache', 'c') as db:

    # Record some values
    db[b'hello'] = b'there'
    db['www.python.org'] = 'Python Website'
    db['www.cnn.com'] = 'Cable News Network'

    # Note that the keys are considered bytes now.
    assert db[b'www.python.org'] == b'Python Website'
    # Notice how the value is now in bytes.
    assert db['www.cnn.com'] == b'Cable News Network'

    # Often-used methods of the dict interface work too.
    print(db.get('python.org', b'not present'))

    # Storing a non-string key or value will raise an exception (most
    # likely a TypeError).
    db['www.yahoo.com'] = 4

# db is automatically closed when leaving the with statement.

Ver también

Módulo shelve

Módulo de persistencia que almacena datos que no son cadenas de caracteres.

Los submódulos individuales se describen en las siguientes secciones.

dbm.gnu — La reinterpretación de GNU de dbm

Código fuente: Lib/dbm/gnu.py [https://github.com/python/cpython/tree/3.9/Lib/dbm/gnu.py]

Este módulo es bastante similar al módulo dbm, pero usa la biblioteca GNU gdbm en su lugar para proporcionar alguna funcionalidad adicional. Tenga en cuenta que los formatos de archivo creados por dbm.gnu y dbm.ndbm son incompatibles.

El módulo dbm.gnu proporciona una interfaz a la biblioteca GNU DBM. Los objetos dbm.gnu.gdbm se comportan como asignaciones (diccionarios), excepto que las claves y los valores siempre se convierten a bytes antes de almacenarlos. La impresión de un objeto gdbm no imprime las llaves y los valores, y los métodos items() y values() no son compatibles.

exception dbm.gnu.error

Se lanza en errores específicos dbm.gnu, como errores de E/S. KeyError se genera para errores generales de asignación, como especificar una clave incorrecta.

dbm.gnu.open(filename[, flag[, mode]])

Abre una base de datos gdbm y retorna un objeto gdbm. El argumento filename es el nombre del archivo de la base de datos.

El argumento opcional flag puede ser:

Valor

Significado

'r'

Abre la base de datos existente solo para lectura (predeterminado)

'w'

Abre la base de datos existente para leer y escribir

'c'

Abre la base de datos para lectura y escritura, creándola si no existe

'n'

Siempre cree una base de datos nueva, vacía, abierta para lectura y escritura

Los siguientes caracteres adicionales se pueden agregar al flag para controlar cómo se abre la base de datos:

Valor

Significado

'f'

Abre la base de datos en modo rápido. Las escrituras en la base de datos no se sincronizarán.

's'

Modo sincronizado. Esto hará que los cambios en la base de datos se escriban inmediatamente en el archivo.

'u'

No bloquea la base de datos.

No todos los flags son válidas para todas las versiones de gdbm. La constante del módulo open_flags es una cadena de caracteres de flags soportadas. La excepción error se lanza si se especifica un flag no válido.

El argumento opcional mode es el modo Unix del archivo, usado solo cuando la base de datos tiene que ser creada. Su valor predeterminado es octal 0o666.

Además de los métodos similares a los diccionarios, los objetos gdbm tienen los siguientes métodos:

gdbm.firstkey()

Es posible recorrer cada clave en la base de datos usando este método y el método nextkey(). El recorrido está ordenado por los valores hash internos de gdbm y no se ordenará por los valores clave. Este método retorna la clave de inicio.

gdbm.nextkey(key)

Retorna la clave que sigue a key en el recorrido. El siguiente código imprime todas las claves en la base de datos db, sin tener que crear una lista en la memoria que las contenga todas:

k = db.firstkey()
while k is not None:
    print(k)
    k = db.nextkey(k)

gdbm.reorganize()

Si ha realizado muchas eliminaciones y desea reducir el espacio utilizado por el archivo gdbm, esta rutina reorganizará la base de datos. Los objetos gdbm no acortarán la longitud de un archivo de base de datos excepto al usar esta reorganización; de lo contrario, el espacio de archivo eliminado se conservará y reutilizará cuando se agreguen nuevos pares (clave, valor).

gdbm.sync()

Cuando la base de datos se ha abierto en modo rápido, este método obliga a que los datos no escritos se escriban en el disco.

gdbm.close()

Cierra la base de datos gdbm.

dbm.ndbm — Interfaz basada en ndbm

Código fuente: Lib/dbm/ndbm.py [https://github.com/python/cpython/tree/3.9/Lib/dbm/ndbm.py]

El módulo dbm.ndbm proporciona una interfaz a la biblioteca «(n)dbm» de Unix. Los objetos DBM se comportan como asignaciones (diccionarios), excepto que las claves y los valores siempre se almacenan como bytes. La impresión de un objeto dbm no imprime las claves y los valores, y los métodos items() y values() no son compatibles.

Este módulo se puede utilizar con la interfaz ndbm «clásica» o la interfaz de compatibilidad GNU GDBM. En Unix, el código configure intentará localizar el archivo de encabezado apropiado para simplificar la construcción de este módulo.

exception dbm.ndbm.error

Se lanza en errores específicos bm.ndbm, como errores de E/S. KeyError lanza para errores generales de asignación, como especificar una clave incorrecta.

dbm.ndbm.library

Nombre de la biblioteca de implementación ndbm utilizada.

dbm.ndbm.open(filename[, flag[, mode]])

Abre una base de datos dbm y retorna un objeto ndbm. El argumento filename es el nombre de la base de datos (sin las extensiones .dir y .pag).

El argumento flag opcional debe ser uno de estos valores:

Valor

Significado

'r'

Abre la base de datos existente solo para lectura (predeterminado)

'w'

Abre la base de datos existente para leer y escribir

'c'

Abre la base de datos para lectura y escritura, creándola si no existe

'n'

Siempre cree una base de datos nueva, vacía, abierta para lectura y escritura

El argumento opcional mode es el modo Unix del archivo, usado solamente cuando la base de datos tiene que ser creada. Su valor predeterminado es octal 0o666 (y será modificado por el umask vigente).

Además de los métodos similares a los de un diccionario, los objetos ndbm proporcionan el siguiente método:

ndbm.close()

Cierra la base de datos ndbm.

dbm.dumb — Implementación de DBM portátil

Código fuente: Lib/dbm/dumb.py [https://github.com/python/cpython/tree/3.9/Lib/dbm/dumb.py]

Nota

El módulo dbm.dumb está pensado como último recurso para el módulo dbm cuando no hay disponible un módulo más robusto. El módulo dbm.dymb no está escrito para velocidad y no se usa tanto como los otros módulos de base de datos.

El módulo dbm.dumb proporciona una interfaz persistente similar a un diccionario que está escrita completamente en Python. A diferencia de otros módulos como dbm.gnu, no se requiere una biblioteca externa. Al igual que con otras asignaciones persistentes, las claves y los valores siempre se almacenan como bytes.

El módulo define lo siguiente:

exception dbm.dumb.error

Se lanza en errores específicos dbm.dumb, como errores de E/S. KeyError se lanza para errores de mapeo generales como especificar una clave incorrecta.

dbm.dumb.open(filename[, flag[, mode]])

Abre una base de datos dumbdbm y retorna un objeto dumbdbm. El argumento del filename es el nombre base del archivo de la base de datos (sin extensiones específicas). Cuando una base de datos dumbdbm se crea, archivos con la extensión .dat y .dir se crean.

El argumento opcional flag puede ser:

Valor

Significado

'r'

Abre la base de datos existente solo para lectura (predeterminado)

'w'

Abre la base de datos existente para leer y escribir

'c'

Abre la base de datos para lectura y escritura, creándola si no existe

'n'

Siempre cree una base de datos nueva, vacía, abierta para lectura y escritura

El argumento opcional mode es el modo Unix del archivo, usado solamente cuando la base de datos tiene que ser creada. Su valor predeterminado es octal 0o666 (y será modificado por el umask vigente).

Advertencia

Es posible bloquear el intérprete de Python cuando se carga una base de datos con una entrada suficientemente grande/compleja debido a las limitaciones de profundidad de la pila en el compilador AST de Python.

Distinto en la versión 3.5: open() siempre crea una nueva base de datos cuando el flag tiene valor de 'n'.

Distinto en la versión 3.8: Una base de datos abierta con flags 'r' ahora es de solo lectura. Abrir con los flags 'r' y 'w' ya no crea una base de datos si no existe.

Además de los métodos proporcionados por la clase collections.abc.MutableMapping, los objetos dumbdbm proporcionan los siguientes métodos:

dumbdbm.sync()

Sincroniza el directorio en disco y los archivos de datos. Este método es llamado por el método Shelve.sync().

dumbdbm.close()

Cierra la base de datos dumbdbm.

sqlite3 — DB-API 2.0 interfaz para bases de datos SQLite

Código fuente: Lib/sqlite3/ [https://github.com/python/cpython/tree/3.9/Lib/sqlite3/]

SQLite es una biblioteca de C que provee una base de datos ligera basada en disco que no requiere un proceso de servidor separado y permite acceder a la base de datos usando una variación no estándar del lenguaje de consulta SQL. Algunas aplicaciones pueden usar SQLite para almacenamiento interno. También es posible prototipar una aplicación usando SQLite y luego transferir el código a una base de datos más grande como PostgreSQL u Oracle.

The sqlite3 module was written by Gerhard Häring. It provides an SQL interface compliant with the DB-API 2.0 specification described by PEP 249 [https://www.python.org/dev/peps/pep-0249].

To use the module, start by creating a Connection object that represents the database. Here the data will be stored in the example.db file:

import sqlite3
con = sqlite3.connect('example.db')

The special path name :memory: can be provided to create a temporary database in RAM.

Once a Connection has been established, create a Cursor object and call its execute() method to perform SQL commands:

cur = con.cursor()

# Create table
cur.execute('''CREATE TABLE stocks
               (date text, trans text, symbol text, qty real, price real)''')

# Insert a row of data
cur.execute("INSERT INTO stocks VALUES ('2006-01-05','BUY','RHAT',100,35.14)")

# Save (commit) the changes
con.commit()

# We can also close the connection if we are done with it.
# Just be sure any changes have been committed or they will be lost.
con.close()

The saved data is persistent: it can be reloaded in a subsequent session even after restarting the Python interpreter:

import sqlite3
con = sqlite3.connect('example.db')
cur = con.cursor()

To retrieve data after executing a SELECT statement, either treat the cursor as an iterator, call the cursor’s fetchone() method to retrieve a single matching row, or call fetchall() to get a list of the matching rows.

Este ejemplo usa la forma con el iterador:

>>> for row in cur.execute('SELECT * FROM stocks ORDER BY price'):
        print(row)

('2006-01-05', 'BUY', 'RHAT', 100, 35.14)
('2006-03-28', 'BUY', 'IBM', 1000, 45.0)
('2006-04-06', 'SELL', 'IBM', 500, 53.0)
('2006-04-05', 'BUY', 'MSFT', 1000, 72.0)

SQL operations usually need to use values from Python variables. However, beware of using Python’s string operations to assemble queries, as they are vulnerable to SQL injection attacks (see the xkcd webcomic [https://xkcd.com/327/] for a humorous example of what can go wrong):

# Never do this -- insecure!
symbol = 'RHAT'
cur.execute("SELECT * FROM stocks WHERE symbol = '%s'" % symbol)

Instead, use the DB-API’s parameter substitution. To insert a variable into a query string, use a placeholder in the string, and substitute the actual values into the query by providing them as a tuple of values to the second argument of the cursor’s execute() method. An SQL statement may use one of two kinds of placeholders: question marks (qmark style) or named placeholders (named style). For the qmark style, parameters must be a sequence. For the named style, it can be either a sequence or dict instance. The length of the sequence must match the number of placeholders, or a ProgrammingError is raised. If a dict is given, it must contain keys for all named parameters. Any extra items are ignored. Here’s an example of both styles:

import sqlite3

con = sqlite3.connect(":memory:")
cur = con.cursor()
cur.execute("create table lang (name, first_appeared)")

# This is the qmark style:
cur.execute("insert into lang values (?, ?)", ("C", 1972))

# The qmark style used with executemany():
lang_list = [
    ("Fortran", 1957),
    ("Python", 1991),
    ("Go", 2009),
]
cur.executemany("insert into lang values (?, ?)", lang_list)

# And this is the named style:
cur.execute("select * from lang where first_appeared=:year", {"year": 1972})
print(cur.fetchall())

con.close()

Ver también

https://www.sqlite.org

La página web SQLite; la documentación describe la sintaxis y los tipos de datos disponibles para el lenguaje SQL soportado.

https://www.w3schools.com/sql/

Tutorial, referencia y ejemplos para aprender sintaxis SQL.

PEP 249 [https://www.python.org/dev/peps/pep-0249] - Especificación de la API 2.0 de base de datos

PEP escrito por Marc-André Lemburg.

Funciones y constantes del módulo

sqlite3.apilevel

String constant stating the supported DB-API level. Required by the DB-API. Hard-coded to "2.0".

sqlite3.paramstyle

String constant stating the type of parameter marker formatting expected by the sqlite3 module. Required by the DB-API. Hard-coded to "qmark".

Nota

The sqlite3 module supports both qmark and numeric DB-API parameter styles, because that is what the underlying SQLite library supports. However, the DB-API does not allow multiple values for the paramstyle attribute.

sqlite3.version

El número de versión de este módulo, como una cadena de caracteres. Este no es la versión de la librería SQLite.

sqlite3.version_info

El número de versión de este módulo, como una tupla de enteros. Este no es la versión de la librería SQLite.

sqlite3.sqlite_version

El número de versión de la librería SQLite en tiempo de ejecución, como una cadena de caracteres.

sqlite3.sqlite_version_info

El número de versión de la librería SQLite en tiempo de ejecución, como una tupla de enteros.

sqlite3.threadsafety

Integer constant required by the DB-API, stating the level of thread safety the sqlite3 module supports. Currently hard-coded to 1, meaning «Threads may share the module, but not connections.» However, this may not always be true. You can check the underlying SQLite library’s compile-time threaded mode using the following query:

import sqlite3
con = sqlite3.connect(":memory:")
con.execute("""
    select * from pragma_compile_options
    where compile_options like 'THREADSAFE=%'
""").fetchall()

Note that the SQLITE_THREADSAFE levels [https://sqlite.org/compile.html#threadsafe] do not match the DB-API 2.0 threadsafety levels.

sqlite3.PARSE_DECLTYPES

Esta constante se usa con el parámetro detect_types de la función connect().

Configurarla hace que el módulo sqlite3 analice el tipo declarado para cada columna que retorna. Este convertirá la primera palabra del tipo declarado, i. e. para «integer primary key», será convertido a «integer», o para «number(10)» será convertido a «number». Entonces para esa columna, revisará el diccionario de conversiones y usará la función de conversión registrada para ese tipo.

sqlite3.PARSE_COLNAMES

Esta constante se usa con el parámetro detect_types de la función connect().

Setting this makes the SQLite interface parse the column name for each column it returns. It will look for a string formed [mytype] in there, and then decide that “mytype” is the type of the column. It will try to find an entry of “mytype” in the converters dictionary and then use the converter function found there to return the value. The column name found in Cursor.description does not include the type, i. e. if you use something like 'as "Expiration date [datetime]"' in your SQL, then we will parse out everything until the first '[' for the column name and strip the preceding space: the column name would simply be «Expiration date».

sqlite3.connect(database[, timeout, detect_types, isolation_level, check_same_thread, factory, cached_statements, uri])

Abre una conexión al archivo de base de datos SQLite database. Por defecto retorna un objeto Connection, a menos que se indique un factory personalizado.

database es un path-like object indicando el nombre de ruta (absoluta o relativa al directorio de trabajo actual) del archivo de base de datos abierto. Se puede usar ":memory:" para abrir una conexión de base de datos a una base de datos que reside en memoria RAM en lugar que disco.

Cuando una base de datos es accedida por múltiples conexiones, y uno de los procesos modifica la base de datos, la base de datos SQLite se bloquea hasta que la transacción se confirme. El parámetro timeout especifica que tanto debe esperar la conexión para que el bloqueo desaparezca antes de lanzar una excepción. Por defecto el parámetro timeout es de 5.0 (cinco segundos).

Para el parámetro isolation_level, por favor ver la propiedad isolation_level del objeto Connection.

De forma nativa SQLite soporta solo los tipos TEXT, INTEGER,*REAL*,*BLOB* y NULL. Si se quiere usar otros tipos, debe soportarlos usted mismo. El parámetro detect_types y el uso de converters personalizados registrados con la función a nivel del módulo register_converter() permite hacerlo fácilmente.

detect_types por defecto es 0 (es decir, desactivado, sin detección de tipo), puede configurarlo en cualquier combinación de PARSE_DECLTYPES y PARSE_COLNAMES para activar la detección de tipo. Debido al comportamiento de SQLite, los tipos no se pueden detectar para los campos generados (por ejemplo, max(data)), incluso cuando se establece el parámetro detect_types. En tal caso, el tipo devuelto es str.

Por defecto, check_same_thread es True y únicamente el hilo creado puede utilizar la conexión. Si se configura False, la conexión retornada podrá ser compartida con múltiples hilos. Cuando se utilizan múltiples hilos con la misma conexión, las operaciones de escritura deberán ser serializadas por el usuario para evitar corrupción de datos.

Por defecto el módulo sqlite3 utiliza su propia clase Connection para la llamada de conexión. Sin embargo se puede crear una subclase de Connection y hacer que connect() use su clase en lugar de proveer la suya en el parámetro factory.

Consulte la sección SQLite y tipos de Python de este manual para más detalles.

El módulo sqlite3 internamente usa cache de declaraciones para evitar un análisis SQL costoso. Si se desea especificar el número de sentencias que estarán en memoria caché para la conexión, se puede configurar el parámetro cached_statements. Por defecto están configurado para 100 sentencias en memoria caché.

If uri is True, database is interpreted as a URI with a file path and an optional query string. The scheme part must be "file:". The path can be a relative or absolute file path. The query string allows us to pass parameters to SQLite. Some useful URI tricks include:

# Open a database in read-only mode.
con = sqlite3.connect("file:template.db?mode=ro", uri=True)

# Don't implicitly create a new database file if it does not already exist.
# Will raise sqlite3.OperationalError if unable to open a database file.
con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True)

# Create a shared named in-memory database.
con1 = sqlite3.connect("file:mem1?mode=memory&cache=shared", uri=True)
con2 = sqlite3.connect("file:mem1?mode=memory&cache=shared", uri=True)
con1.executescript("create table t(t); insert into t values(28);")
rows = con2.execute("select * from t").fetchall()

More information about this feature, including a list of recognized parameters, can be found in the SQLite URI documentation [https://www.sqlite.org/uri.html].

Lanza un evento de auditoría sqlite3.connect con argumento database.

Distinto en la versión 3.4: Agregado el parámetro uri.

Distinto en la versión 3.7: database ahora también puede ser un path-like object, no solo una cadena de caracteres.

sqlite3.register_converter(typename, callable)

Registra un invocable para convertir un bytestring de la base de datos en un tipo Python personalizado. El invocable será invocado por todos los valores de la base de datos que son del tipo typename. Conceder el parámetro detect_types de la función connect() para el funcionamiento de la detección de tipo. Se debe notar que typename y el nombre del tipo en la consulta son comparados insensiblemente a mayúsculas y minúsculas.

sqlite3.register_adapter(type, callable)

Registra un invocable para convertir el tipo Python personalizado type a uno de los tipos soportados por SQLite’s. El invocable callable acepta un único parámetro de valor Python, y debe retornar un valor de los siguientes tipos: int, float, str or bytes.

sqlite3.complete_statement(sql)

Retorna True si la cadena sql contiene una o más sentencias SQL completas terminadas con punto y coma. No se verifica que la sentencia SQL sea sintácticamente correcta, solo que no existan literales de cadenas no cerradas y que la sentencia termine por un punto y coma.

Esto puede ser usado para construir un shell para SQLite, como en el siguiente ejemplo:

# A minimal SQLite shell for experiments

import sqlite3

con = sqlite3.connect(":memory:")
con.isolation_level = None
cur = con.cursor()

buffer = ""

print("Enter your SQL commands to execute in sqlite3.")
print("Enter a blank line to exit.")

while True:
    line = input()
    if line == "":
        break
    buffer += line
    if sqlite3.complete_statement(buffer):
        try:
            buffer = buffer.strip()
            cur.execute(buffer)

            if buffer.lstrip().upper().startswith("SELECT"):
                print(cur.fetchall())
        except sqlite3.Error as e:
            print("An error occurred:", e.args[0])
        buffer = ""

con.close()

sqlite3.enable_callback_tracebacks(flag)

Por defecto no se obtendrá ningún tracebacks en funciones definidas por el usuario, agregaciones, converters, autorizador de callbacks etc. si se quiere depurarlas, se puede llamar esta función con flag configurado a True. Después se obtendrán tracebacks de los callbacks en sys.stderr. Usar False para deshabilitar la característica de nuevo.

Objetos de conexión

class sqlite3.Connection

An SQLite database connection has the following attributes and methods:

isolation_level

Obtener o configurar el actual nivel de insolación. None para modo autocommit o uno de «DEFERRED», «IMMEDIATE» o «EXCLUSIVO». Ver sección Controlando Transacciones para una explicación detallada.

in_transaction

True si una transacción está activa (existen cambios uncommitted), False en sentido contrario. Atributo de solo lectura.

Nuevo en la versión 3.2.

cursor(factory=Cursor)

El método cursor acepta un único parámetro opcional factory. Si es agregado, éste debe ser un invocable que retorna una instancia de Cursor o sus subclases.

commit()

Este método asigna la transacción actual. Si no se llama este método, cualquier cosa hecha desde la última llamada de commit() no es visible para otras conexiones de bases de datos. Si se pregunta el porqué no se ven los datos que escribiste, por favor verifica que no olvidaste llamar este método.

rollback()

Este método retrocede cualquier cambio en la base de datos desde la llamada del último commit().

close()

Este método cierra la conexión a la base de datos. Nótese que éste no llama automáticamente commit(). Si se cierra la conexión a la base de datos sin llamar primero commit(), los cambios se perderán!

execute(sql[, parameters])

Create a new Cursor object and call execute() on it with the given sql and parameters. Return the new cursor object.

executemany(sql[, parameters])

Create a new Cursor object and call executemany() on it with the given sql and parameters. Return the new cursor object.

executescript(sql_script)

Create a new Cursor object and call executescript() on it with the given sql_script. Return the new cursor object.

create_function(name, num_params, func, *, deterministic=False)

Crea un función definida de usuario que se puede usar después desde declaraciones SQL con el nombre de función name. num_params es el número de parámetros que la función acepta (si num_params is -1, la función puede tomar cualquier número de argumentos), y func es un invocable de Python que es llamado como la función SQL. Si deterministic es verdadero, la función creada es marcada como deterministic [https://sqlite.org/deterministic.html], lo cual permite a SQLite hacer optimizaciones adicionales. Esta marca es soportada por SQLite 3.8.3 o superior, será lanzado NotSupportedError si se usa con versiones antiguas.

La función puede retornar cualquier tipo soportado por SQLite: bytes, str, int, float y None.

Distinto en la versión 3.8: El parámetro deterministic fue agregado.

Ejemplo:

import sqlite3
import hashlib

def md5sum(t):
    return hashlib.md5(t).hexdigest()

con = sqlite3.connect(":memory:")
con.create_function("md5", 1, md5sum)
cur = con.cursor()
cur.execute("select md5(?)", (b"foo",))
print(cur.fetchone()[0])

con.close()

create_aggregate(name, num_params, aggregate_class)

Crea una función agregada definida por el usuario.

La clase agregada debe implementar un método step, el cual acepta el número de parámetros num_params (si num_params es -1, la función puede tomar cualquier número de argumentos), y un método finalize el cual retornará el resultado final del agregado.

El método finalize puede retornar cualquiera de los tipos soportados por SQLite: bytes, str, int, float and None.

Ejemplo:

import sqlite3

class MySum:
    def __init__(self):
        self.count = 0

    def step(self, value):
        self.count += value

    def finalize(self):
        return self.count

con = sqlite3.connect(":memory:")
con.create_aggregate("mysum", 1, MySum)
cur = con.cursor()
cur.execute("create table test(i)")
cur.execute("insert into test(i) values (1)")
cur.execute("insert into test(i) values (2)")
cur.execute("select mysum(i) from test")
print(cur.fetchone()[0])

con.close()

create_collation(name, callable)

Crea una collation con el name y callable especificado. El invocable será pasado con dos cadenas de texto como argumentos. Se retornará -1 si el primero esta ordenado menor que el segundo, 0 si están ordenados igual y 1 si el primero está ordenado mayor que el segundo. Nótese que esto controla la ordenación (ORDER BY en SQL) por lo tanto sus comparaciones no afectan otras comparaciones SQL.

Note que el invocable obtiene sus parámetros como Python bytestrings, lo cual normalmente será codificado en UTF-8.

El siguiente ejemplo muestra una collation personalizada que ordena «La forma incorrecta»:

import sqlite3

def collate_reverse(string1, string2):
    if string1 == string2:
        return 0
    elif string1 < string2:
        return 1
    else:
        return -1

con = sqlite3.connect(":memory:")
con.create_collation("reverse", collate_reverse)

cur = con.cursor()
cur.execute("create table test(x)")
cur.executemany("insert into test(x) values (?)", [("a",), ("b",)])
cur.execute("select x from test order by x collate reverse")
for row in cur:
    print(row)
con.close()

Para remover una collation, llama create_collation con None como invocable:

con.create_collation("reverse", None)

interrupt()

Se puede llamar este método desde un hilo diferente para abortar cualquier consulta que pueda estar ejecutándose en la conexión. La consulta será abortada y quien realiza la llamada obtendrá una excepción.

set_authorizer(authorizer_callback)

Esta rutina registra un callback. El callback es invocado para cada intento de acceso a un columna de una tabla en la base de datos. El callback deberá retornar SQLITE_OK si el acceso esta permitido, SQLITE_DENY si la completa declaración SQL deberá ser abortada con un error y SQLITE_IGNORE si la columna deberá ser tratada como un valor NULL. Estas constantes están disponibles en el módulo sqlite3.

El primer argumento del callback significa que tipo de operación será autorizada. El segundo y tercer argumento serán argumentos o None dependiendo del primer argumento. El cuarto argumento es el nombre de la base de datos («main», «temp», etc.) si aplica. El quinto argumento es el nombre del disparador más interno o vista que es responsable por los intentos de acceso o None si este intento de acceso es directo desde el código SQL de entrada.

Por favor consulte la documentación de SQLite sobre los posibles valores para el primer argumento y el significado del segundo y tercer argumento dependiendo del primero. Todas las constantes necesarias están disponibles en el módulo sqlite3.

set_progress_handler(handler, n)

Esta rutina registra un callback. El callback es invocado para cada n instrucciones de la máquina virtual SQLite. Esto es útil si se quiere tener llamado a SQLite durante operaciones de larga duración, por ejemplo para actualizar una GUI.

Si se desea limpiar cualquier progress handler instalado previamente, llame el método con None para handler.

Retornando un valor diferente a 0 de la función gestora terminará la actual consulta en ejecución y causará lanzar una excepción OperationalError.

set_trace_callback(trace_callback)

Registra trace_callback para ser llamado por cada sentencia SQL que realmente se ejecute por el backend de SQLite.

The only argument passed to the callback is the statement (as str) that is being executed. The return value of the callback is ignored. Note that the backend does not only run statements passed to the Cursor.execute() methods. Other sources include the transaction management of the sqlite3 module and the execution of triggers defined in the current database.

Pasando None como trace_callback deshabilitara el trace callback.

Nota

Exceptions raised in the trace callback are not propagated. As a development and debugging aid, use enable_callback_tracebacks() to enable printing tracebacks from exceptions raised in the trace callback.

Nuevo en la versión 3.3.

enable_load_extension(enabled)

Esta rutina habilita/deshabilita el motor de SQLite para cargar extensiones SQLite desde bibliotecas compartidas. Las extensiones SQLite pueden definir nuevas funciones, agregaciones o una completa nueva implementación de tablas virtuales. Una bien conocida extensión es fulltext-search distribuida con SQLite.

Las extensiones cargables están deshabilitadas por defecto. Ver 1.

Nuevo en la versión 3.2.

import sqlite3

con = sqlite3.connect(":memory:")

# enable extension loading
con.enable_load_extension(True)

# Load the fulltext search extension
con.execute("select load_extension('./fts3.so')")

# alternatively you can load the extension using an API call:
# con.load_extension("./fts3.so")

# disable extension loading again
con.enable_load_extension(False)

# example from SQLite wiki
con.execute("create virtual table recipe using fts3(name, ingredients)")
con.executescript("""
    insert into recipe (name, ingredients) values ('broccoli stew', 'broccoli peppers cheese tomatoes');
    insert into recipe (name, ingredients) values ('pumpkin stew', 'pumpkin onions garlic celery');
    insert into recipe (name, ingredients) values ('broccoli pie', 'broccoli cheese onions flour');
    insert into recipe (name, ingredients) values ('pumpkin pie', 'pumpkin sugar flour butter');
    """)
for row in con.execute("select rowid, name, ingredients from recipe where name match 'pie'"):
    print(row)

con.close()

load_extension(path)

This routine loads an SQLite extension from a shared library. You have to enable extension loading with enable_load_extension() before you can use this routine.

Las extensiones cargables están deshabilitadas por defecto. Ver 1.

Nuevo en la versión 3.2.

row_factory

Se puede cambiar este atributo a un invocable que acepta el cursor y la fila original como una tupla y retornará la fila con el resultado real. De esta forma, se puede implementar más avanzadas formas de retornar resultados, tales como retornar un objeto que puede también acceder a las columnas por su nombre.

Ejemplo:

import sqlite3

def dict_factory(cursor, row):
    d = {}
    for idx, col in enumerate(cursor.description):
        d[col[0]] = row[idx]
    return d

con = sqlite3.connect(":memory:")
con.row_factory = dict_factory
cur = con.cursor()
cur.execute("select 1 as a")
print(cur.fetchone()["a"])

con.close()

Si retornado una tupla no es suficiente y se quiere acceder a las columnas basadas en nombre, se debe considerar configurar row_factory a la altamente optimizada tipo sqlite3.Row. Row provee ambos accesos a columnas basada en índice y tipado insensible con casi nada de sobrecoste de memoria. Será probablemente mejor que tú propio enfoque de basado en diccionario personalizado o incluso mejor que una solución basada en db_row.

text_factory

Using this attribute you can control what objects are returned for the TEXT data type. By default, this attribute is set to str and the sqlite3 module will return str objects for TEXT. If you want to return bytes instead, you can set it to bytes.

También se puede configurar a cualquier otro callable que acepte un único parámetro bytestring y retorne el objeto resultante.

Ver el siguiente ejemplo de código para ilustración:

import sqlite3

con = sqlite3.connect(":memory:")
cur = con.cursor()

AUSTRIA = "Österreich"

# by default, rows are returned as str
cur.execute("select ?", (AUSTRIA,))
row = cur.fetchone()
assert row[0] == AUSTRIA

# but we can make sqlite3 always return bytestrings ...
con.text_factory = bytes
cur.execute("select ?", (AUSTRIA,))
row = cur.fetchone()
assert type(row[0]) is bytes
# the bytestrings will be encoded in UTF-8, unless you stored garbage in the
# database ...
assert row[0] == AUSTRIA.encode("utf-8")

# we can also implement a custom text_factory ...
# here we implement one that appends "foo" to all strings
con.text_factory = lambda x: x.decode("utf-8") + "foo"
cur.execute("select ?", ("bar",))
row = cur.fetchone()
assert row[0] == "barfoo"

con.close()

total_changes

Regresa el número total de filas de la base de datos que han sido modificadas, insertadas o borradas desde que la conexión a la base de datos fue abierta.

iterdump()

Regresa un iterador para volcar la base de datos en un texto de formato SQL. Es útil cuando guardamos una base de datos en memoria para posterior restauración. Esta función provee las mismas capacidades que el comando dump en el shell sqlite3.

Ejemplo:

# Convert file existing_db.db to SQL dump file dump.sql
import sqlite3

con = sqlite3.connect('existing_db.db')
with open('dump.sql', 'w') as f:
    for line in con.iterdump():
        f.write('%s\n' % line)
con.close()

backup(target, *, pages=-1, progress=None, name="main", sleep=0.250)

This method makes a backup of an SQLite database even while it’s being accessed by other clients, or concurrently by the same connection. The copy will be written into the mandatory argument target, that must be another Connection instance.

Por defecto, o cuando pages es 0 o un entero negativo, la base de datos completa es copiada en un solo paso; de otra forma el método realiza un bucle copiando hasta el número de pages a la vez.

Si progress es especificado, deberá ser None o un objeto callable que será ejecutado en cada iteración con los tres argumentos enteros, respectivamente el estado status de la última iteración, el restante remaining numero de páginas presentes para ser copiadas y el número total total de páginas.

El argumento name especifica el nombre de la base de datos que será copiada: deberá ser una cadena de texto que contenga el por defecto "main", que indica la base de datos principal, "temp" que indica la base de datos temporal o el nombre especificado después de la palabra clave AS en una sentencia ATTACH DATABASE para una base de datos adjunta.

El argumento sleep especifica el número de segundos a dormir entre sucesivos intentos de respaldar páginas restantes, puede ser especificado como un entero o un valor de punto flotante.

Ejemplo 1, copiar una base de datos existente en otra:

import sqlite3

def progress(status, remaining, total):
    print(f'Copied {total-remaining} of {total} pages...')

con = sqlite3.connect('existing_db.db')
bck = sqlite3.connect('backup.db')
with bck:
    con.backup(bck, pages=1, progress=progress)
bck.close()
con.close()

Ejemplo 2: copiar una base de datos existente en una copia transitoria:

import sqlite3

source = sqlite3.connect('existing_db.db')
dest = sqlite3.connect(':memory:')
source.backup(dest)

Disponibilidad: SQLite 3.6.11 o superior

Nuevo en la versión 3.7.

Objetos Cursor

class sqlite3.Cursor

Una instancia de Cursor tiene los siguientes atributos y métodos.

execute(sql[, parameters])

Executes an SQL statement. Values may be bound to the statement using placeholders.

execute() solo ejecutará una única sentencia SQL. Si se trata de ejecutar más de una sentencia con el, lanzará un Warning. Usar executescript() si se quiere ejecutar múltiples sentencias SQL con una llamada.

executemany(sql, seq_of_parameters)

Executes a parameterized SQL command against all parameter sequences or mappings found in the sequence seq_of_parameters. The sqlite3 module also allows using an iterator yielding parameters instead of a sequence.

import sqlite3

class IterChars:
    def __init__(self):
        self.count = ord('a')

    def __iter__(self):
        return self

    def __next__(self):
        if self.count > ord('z'):
            raise StopIteration
        self.count += 1
        return (chr(self.count - 1),) # this is a 1-tuple

con = sqlite3.connect(":memory:")
cur = con.cursor()
cur.execute("create table characters(c)")

theIter = IterChars()
cur.executemany("insert into characters(c) values (?)", theIter)

cur.execute("select c from characters")
print(cur.fetchall())

con.close()

Acá un corto ejemplo usando un generator:

import sqlite3
import string

def char_generator():
    for c in string.ascii_lowercase:
        yield (c,)

con = sqlite3.connect(":memory:")
cur = con.cursor()
cur.execute("create table characters(c)")

cur.executemany("insert into characters(c) values (?)", char_generator())

cur.execute("select c from characters")
print(cur.fetchall())

con.close()

executescript(sql_script)

This is a nonstandard convenience method for executing multiple SQL statements at once. It issues a COMMIT statement first, then executes the SQL script it gets as a parameter. This method disregards isolation_level; any transaction control must be added to sql_script.

sql_script puede ser una instancia de str.

Ejemplo:

import sqlite3

con = sqlite3.connect(":memory:")
cur = con.cursor()
cur.executescript("""
    create table person(
        firstname,
        lastname,
        age
    );

    create table book(
        title,
        author,
        published
    );

    insert into book(title, author, published)
    values (
        'Dirk Gently''s Holistic Detective Agency',
        'Douglas Adams',
        1987
    );
    """)
con.close()

fetchone()

Obtiene la siguiente fila de un conjunto resultado, retorna una única secuencia, o None cuando no hay más datos disponibles.

fetchmany(size=cursor.arraysize)

Obtiene el siguiente conjunto de filas del resultado de una consulta, retornando una lista. Una lista vacía es retornada cuando no hay más filas disponibles.

El número de filas a obtener por llamado es especificado por el parámetro size. Si no es suministrado, el arraysize del cursor determina el número de filas a obtener. El método debería intentar obtener tantas filas como las indicadas por el parámetro size. Si esto no es posible debido a que el número especificado de filas no está disponible, entonces menos filas deberán ser retornadas.

Nótese que hay consideraciones de desempeño involucradas con el parámetro size. Para un optimo desempeño, es usualmente mejor usar el atributo arraysize. Si el parámetro size es usado, entonces es mejor retener el mismo valor de una llamada fetchmany() a la siguiente.

fetchall()

Obtiene todas las filas (restantes) del resultado de una consulta. Nótese que el atributo arraysize del cursor puede afectar el desempeño de esta operación. Una lista vacía será retornada cuando no hay filas disponibles.

close()

Cierra el cursor ahora (en lugar que cuando __del__ es llamado)

El cursor no será usable de este punto en adelante; una excepción ProgrammingError será lanzada si se intenta cualquier operación con el cursor.

setinputsizes(sizes)

Required by the DB-API. Does nothing in sqlite3.

setoutputsize(size[, column])

Required by the DB-API. Does nothing in sqlite3.

rowcount

A pesar de que la clase Cursor del módulo sqlite3 implementa este atributo, el propio soporte del motor de base de datos para la determinación de «filas afectadas»/»filas seleccionadas» es raro.

Para sentencias executemany(), el número de modificaciones se resumen en rowcount.

Cómo lo requiere la especificación Python DB API, el atributo rowcount «es -1 en caso de que executeXX() no haya sido ejecutada en el cursor o en el rowcount de la última operación no haya sido determinada por la interface». Esto incluye sentencias SELECT porque no podemos determinar el número de filas que una consulta produce hasta que todas las filas sean obtenidas.

Con versiones de SQLite anteriores a 3.6.5, rowcount es configurado a 0 si se hace un DELETE FROM table sin ninguna condición.

lastrowid

This read-only attribute provides the row id of the last inserted row. It is only updated after successful INSERT or REPLACE statements using the execute() method. For other statements, after executemany() or executescript(), or if the insertion failed, the value of lastrowid is left unchanged. The initial value of lastrowid is None.

Nota

Inserts into WITHOUT ROWID tables are not recorded.

Distinto en la versión 3.6: Se agregó soporte para sentencias REPLACE.

arraysize

Atributo de lectura/escritura que controla el número de filas retornadas por fetchmany(). El valor por defecto es 1, lo cual significa que una única fila será obtenida por llamada.

description

Este atributo de solo lectura provee el nombre de las columnas de la última consulta. Para ser compatible con Python DB API, retorna una 7-tupla para cada columna en donde los últimos seis ítems de cada tupla son None.

También es configurado para sentencias SELECT sin ninguna fila coincidente.

connection

Este atributo de solo lectura provee la Connection de la base de datos SQLite usada por el objeto Cursor. Un objeto Cursor creado por la llamada de con.cursor() tendrá un atributo connection que se refiere a con:

>>> con = sqlite3.connect(":memory:")
>>> cur = con.cursor()
>>> cur.connection == con
True

Objetos Fila (Row)

class sqlite3.Row

Una instancia Row sirve como una altamente optimizada row_factory para objetos Connection. Esta trata de imitar una tupla en su mayoría de características.

Soporta acceso mapeado por nombre de columna e índice, iteración, representación, pruebas de igualdad y len().

Si dos objetos Row tienen exactamente las mismas columnas y sus miembros son iguales, entonces se comparan a igual.

keys()

Este método retorna una lista con los nombre de columnas. Inmediatamente después de una consulta, es el primer miembro de cada tupla en Cursor.description.

Distinto en la versión 3.5: Agrega soporte de segmentación.

Vamos a asumir que se inicializa una tabla como en el ejemplo dado:

con = sqlite3.connect(":memory:")
cur = con.cursor()
cur.execute('''create table stocks
(date text, trans text, symbol text,
 qty real, price real)''')
cur.execute("""insert into stocks
            values ('2006-01-05','BUY','RHAT',100,35.14)""")
con.commit()
cur.close()

Ahora conectamos Row en:

>>> con.row_factory = sqlite3.Row
>>> cur = con.cursor()
>>> cur.execute('select * from stocks')
<sqlite3.Cursor object at 0x7f4e7dd8fa80>
>>> r = cur.fetchone()
>>> type(r)
<class 'sqlite3.Row'>
>>> tuple(r)
('2006-01-05', 'BUY', 'RHAT', 100.0, 35.14)
>>> len(r)
5
>>> r[2]
'RHAT'
>>> r.keys()
['date', 'trans', 'symbol', 'qty', 'price']
>>> r['qty']
100.0
>>> for member in r:
...     print(member)
...
2006-01-05
BUY
RHAT
100.0
35.14

Excepciones

exception sqlite3.Warning

Una subclase de Exception.

exception sqlite3.Error

La clase base de otras excepciones en este módulo. Es una subclase de Exception.

exception sqlite3.DatabaseError

Excepción lanzada para errores que están relacionados con la base de datos.

exception sqlite3.IntegrityError

Excepción lanzada cuando la integridad de la base de datos es afectada, por ejemplo la comprobación de una llave foránea falla. Es una subclase de DatabaseError.

exception sqlite3.ProgrammingError

Excepción lanzada por errores de programación, e.g. tabla no encontrada o ya existente, error de sintaxis en la sentencia SQL, número equivocado de parámetros especificados, etc. Es una subclase de DatabaseError.

exception sqlite3.OperationalError

Excepción lanzada por errores relacionados por la operación de la base de datos y no necesariamente bajo el control del programador, por ejemplo ocurre una desconexión inesperada, el nombre de la fuente de datos no es encontrado, una transacción no pudo ser procesada, etc. Es una subclase de DatabaseError.

exception sqlite3.NotSupportedError

Excepción lanzada en caso de que un método o API de base de datos fuera usada en una base de datos que no la soporta, e.g. llamando el método rollback() en una conexión que no soporta la transacción o tiene deshabilitada las transacciones. Es una subclase de DatabaseError.

SQLite y tipos de Python

Introducción

SQLite soporta de forma nativa los siguientes tipos: NULL, INTEGER, REAL, TEXT, BLOB.

Los siguientes tipos de Python se pueden enviar a SQLite sin problema alguno:

Tipo de Python

Tipo de SQLite

None

NULL

int

INTEGER

float

REAL

str

TEXT

bytes

BLOB

De esta forma es como los tipos de SQLite son convertidos a tipos de Python por defecto:

Tipo de SQLite

Tipo de Python

NULL

None

INTEGER

int

REAL

float

TEXT

depende de text_factory, str por defecto

BLOB

bytes

The type system of the sqlite3 module is extensible in two ways: you can store additional Python types in an SQLite database via object adaptation, and you can let the sqlite3 module convert SQLite types to different Python types via converters.

Usando adaptadores para almacenar tipos adicionales de Python en bases de datos SQLite

Como se describió anteriormente, SQLite soporta solamente un conjunto limitado de tipos de forma nativa. Para usar otros tipos de Python con SQLite, se deben adaptar a uno de los tipos de datos soportados por el módulo sqlite3 para SQLite: uno de NoneType, int, float, str, bytes.

Hay dos formas de habilitar el módulo sqlite3 para adaptar un tipo personalizado de Python a alguno de los admitidos.

Permitiéndole al objeto auto adaptarse

Este es un buen enfoque si uno mismo escribe la clase. Vamos a suponer que se tiene una clase como esta:

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

Ahora desea almacenar el punto en una sola columna de SQLite. Primero tendrá que elegir uno de los tipos admitidos que se utilizará para representar el punto. Usemos str y separemos las coordenadas usando un punto y coma. Luego, debe darle a su clase un método __conform __(self, protocol) que debe retornar el valor convertido. El parámetro protocol será PrepareProtocol.

import sqlite3

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

    def __conform__(self, protocol):
        if protocol is sqlite3.PrepareProtocol:
            return "%f;%f" % (self.x, self.y)

con = sqlite3.connect(":memory:")
cur = con.cursor()

p = Point(4.0, -3.2)
cur.execute("select ?", (p,))
print(cur.fetchone()[0])

con.close()

Registrando un adaptador invocable

La otra posibilidad es crear una función que convierta el escrito a representación de cadena de texto y registrar la función con register_adapter().

import sqlite3

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

def adapt_point(point):
    return "%f;%f" % (point.x, point.y)

sqlite3.register_adapter(Point, adapt_point)

con = sqlite3.connect(":memory:")
cur = con.cursor()

p = Point(4.0, -3.2)
cur.execute("select ?", (p,))
print(cur.fetchone()[0])

con.close()

El módulo sqlite3 tiene dos adaptadores por defecto para las funciones integradas de Python datetime.date y tipos datetime.datetime. Ahora vamos a suponer que queremos almacenar objetos datetime.datetime no en representación ISO, sino como una marca de tiempo Unix.

import sqlite3
import datetime
import time

def adapt_datetime(ts):
    return time.mktime(ts.timetuple())

sqlite3.register_adapter(datetime.datetime, adapt_datetime)

con = sqlite3.connect(":memory:")
cur = con.cursor()

now = datetime.datetime.now()
cur.execute("select ?", (now,))
print(cur.fetchone()[0])

con.close()

Convertir valores SQLite a tipos de Python personalizados

Escribir un adaptador permite enviar escritos personalizados de Python a SQLite. Pero para hacer esto realmente útil, tenemos que hace el flujo Python a SQLite a Python.

Ingresar convertidores.

Regresemos a la clase Point. Se almacena las coordenadas x e y de forma separada por punto y coma como una cadena de texto en SQLite.

Primero, se define una función de conversión que acepta la cadena de texto como un parámetro y construye un objeto Point de ahí.

Nota

Las funciones de conversión siempre son llamadas con un objeto bytes, no importa bajo qué tipo de dato se envió el valor a SQLite.

def convert_point(s):
    x, y = map(float, s.split(b";"))
    return Point(x, y)

Ahora se necesita hacer que el módulo sqlite3 conozca que lo que tu seleccionaste de la base de datos es de hecho un punto. Hay dos formas de hacer esto:

Implícitamente vía el tipo declarado

Explícitamente vía el nombre de la columna

Ambas formas están descritas en la sección Funciones y constantes del módulo, en las entradas para las constantes PARSE_DECLTYPES y PARSE_COLNAMES.

El siguiente ejemplo ilustra ambos enfoques.

import sqlite3

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

    def __repr__(self):
        return "(%f;%f)" % (self.x, self.y)

def adapt_point(point):
    return ("%f;%f" % (point.x, point.y)).encode('ascii')

def convert_point(s):
    x, y = list(map(float, s.split(b";")))
    return Point(x, y)

# Register the adapter
sqlite3.register_adapter(Point, adapt_point)

# Register the converter
sqlite3.register_converter("point", convert_point)

p = Point(4.0, -3.2)

#########################
# 1) Using declared types
con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES)
cur = con.cursor()
cur.execute("create table test(p point)")

cur.execute("insert into test(p) values (?)", (p,))
cur.execute("select p from test")
print("with declared types:", cur.fetchone()[0])
cur.close()
con.close()

#######################
# 1) Using column names
con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_COLNAMES)
cur = con.cursor()
cur.execute("create table test(p)")

cur.execute("insert into test(p) values (?)", (p,))
cur.execute('select p as "p [point]" from test')
print("with column names:", cur.fetchone()[0])
cur.close()
con.close()

Adaptadores y convertidores por defecto

Hay adaptadores por defecto para los tipos date y datetime en el módulo datetime. Éstos serán enviados como fechas/marcas de tiempo ISO a SQLite.

Los convertidores por defecto están registrados bajo el nombre «date» para datetime.date y bajo el mismo nombre para «timestamp» para datetime.datetime.

De esta forma, se puede usar date/timestamps para Python sin ajuste adicional en la mayoría de los casos. El formato de los adaptadores también es compatible con las funciones experimentales de SQLite date/time.

El siguiente ejemplo demuestra esto.

import sqlite3
import datetime

con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES|sqlite3.PARSE_COLNAMES)
cur = con.cursor()
cur.execute("create table test(d date, ts timestamp)")

today = datetime.date.today()
now = datetime.datetime.now()

cur.execute("insert into test(d, ts) values (?, ?)", (today, now))
cur.execute("select d, ts from test")
row = cur.fetchone()
print(today, "=>", row[0], type(row[0]))
print(now, "=>", row[1], type(row[1]))

cur.execute('select current_date as "d [date]", current_timestamp as "ts [timestamp]"')
row = cur.fetchone()
print("current_date", row[0], type(row[0]))
print("current_timestamp", row[1], type(row[1]))

con.close()

Si un timestamp almacenado en SQLite tiene una parte fraccional mayor a 6 números, este valor será truncado a precisión de microsegundos por el convertidor de timestamp.

Nota

The default «timestamp» converter ignores UTC offsets in the database and always returns a naive datetime.datetime object. To preserve UTC offsets in timestamps, either leave converters disabled, or register an offset-aware converter with register_converter().

Controlando Transacciones

La librería subyacente sqlite3 opera en modo autocommit por defecto, pero el módulo de Python sqlite3 no.

El modo autocommit significa que la sentencias que modifican la base de datos toman efecto de forma inmediata. Una sentencia BEGIN o SAVEPOINT deshabilitan el modo autocommit, y un COMMIT, un ROLLBACK, o un RELEASE que terminan la transacción más externa, habilitan de nuevo el modo autocommit.

El módulo de Python sqlite3 emite por defecto una sentencia BEGIN implícita antes de una sentencia tipo Lenguaje Manipulación de Datos (DML) (es decir INSERT/UPDATE/DELETE/REPLACE).

Se puede controlar en qué tipo de sentencias BEGIN sqlite3 implícitamente ejecuta vía el parámetro insolation_level a la función de llamada connect(), o vía las propiedades de conexión isolation_level. Si no se especifica isolation_level, se usa un plano BEGIN, el cuál es equivalente a especificar DEFERRED. Otros posibles valores son IMMEDIATE and EXCLUSIVE.

Se puede deshabilitar la gestión implícita de transacciones del módulo sqlite3 con la configuración isolation_level a None. Esto dejará la subyacente biblioteca operando en modo autocommit. Se puede controlar completamente el estado de la transacción emitiendo explícitamente sentencias BEGIN, ROLLBACK, SAVEPOINT, y RELEASE en el código.

Note that executescript() disregards isolation_level; any transaction control must be added explicitly.

Distinto en la versión 3.6: sqlite3 solía realizar commit en transacciones implícitamente antes de sentencias DDL. Este ya no es el caso.

Usando sqlite3 eficientemente

Usando métodos atajo

Usando los métodos no estándar execute(), executemany() y executescript() del objeto Connection, el código puede ser escrito más consistentemente porque no se tienen que crear explícitamente los (a menudo superfluos) objetos Cursor. En cambio, los objetos de Cursor son creados implícitamente y estos métodos atajo retornan los objetos cursor. De esta forma, se puede ejecutar una sentencia SELECT e iterar directamente sobre él, solamente usando una única llamada al objeto Connection.

import sqlite3

langs = [
    ("C++", 1985),
    ("Objective-C", 1984),
]

con = sqlite3.connect(":memory:")

# Create the table
con.execute("create table lang(name, first_appeared)")

# Fill the table
con.executemany("insert into lang(name, first_appeared) values (?, ?)", langs)

# Print the table contents
for row in con.execute("select name, first_appeared from lang"):
    print(row)

print("I just deleted", con.execute("delete from lang").rowcount, "rows")

# close is not a shortcut method and it's not called automatically,
# so the connection object should be closed manually
con.close()

Accediendo a las columnas por el nombre en lugar del índice

Una característica útil del módulo sqlite3 es la clase incluida sqlite3.Row diseñada para ser usada como una fábrica de filas.

Filas envueltas con esta clase pueden ser accedidas tanto por índice (al igual que tuplas) como por nombre insensible a mayúsculas o minúsculas:

import sqlite3

con = sqlite3.connect(":memory:")
con.row_factory = sqlite3.Row

cur = con.cursor()
cur.execute("select 'John' as name, 42 as age")
for row in cur:
    assert row[0] == row["name"]
    assert row["name"] == row["nAmE"]
    assert row[1] == row["age"]
    assert row[1] == row["AgE"]

con.close()

Usando la conexión como un administrador de contexto

Los objetos de conexión pueden ser usados como administradores de contexto que automáticamente transacciones commit o rollback. En el evento de una excepción, la transacción es retrocedida; de otra forma, la transacción es confirmada:

import sqlite3

con = sqlite3.connect(":memory:")
con.execute("create table lang (id integer primary key, name varchar unique)")

# Successful, con.commit() is called automatically afterwards
with con:
    con.execute("insert into lang(name) values (?)", ("Python",))

# con.rollback() is called after the with block finishes with an exception, the
# exception is still raised and must be caught
try:
    with con:
        con.execute("insert into lang(name) values (?)", ("Python",))
except sqlite3.IntegrityError:
    print("couldn't add Python twice")

# Connection object used as context manager only commits or rollbacks transactions,
# so the connection object should be closed manually
con.close()

Notas al pie

1(1,2)

The sqlite3 module is not built with loadable extension support by default, because some platforms (notably macOS) have SQLite libraries which are compiled without this feature. To get loadable extension support, you must pass --enable-loadable-sqlite-extensions to configure.

Compresión de datos y archivado

Los módulos descritos en este capítulo soportan compresión de datos con los algoritmos zlib, gzip, bzip2 e lzma, y la creación de archivos con formato ZIP y tar. Véase también Operaciones de archivado provistos por el módulo shutil.

zlib — Compresión compatible con gzip

gzip — Soporte para archivos gzip

Ejemplos de uso

Interfaz de Línea de Comandos

Opciones de línea de comandos

bz2 — Soporte para compresión bzip2

(De)compresión de archivos

(De)compresión incremental

(Des)comprimir en un solo paso

Ejemplos de uso

lzma — Compresión utilizando el algoritmo LZMA

Leyendo y escribiendo ficheros comprimidos

Comprimiendo y descomprimiendo datos en memoria

Misceláneas

Especificando cadenas de filtro personalizadas

Ejemplos

zipfile — Trabajar con archivos ZIP

Objetos ZipFile

Objetos de ruta

Objetos PyZipFile

Objetos ZipInfo

Interfaz de línea de comandos

Opciones de línea de comando

Problemas de descompresión

Del archivo mismo

Limitaciones del sistema de archivos

Limitaciones de recursos

Interrupción

Comportamientos predeterminados de extracción

tarfile — Leer y escribir archivos tar

Objetos TarFile

Objetos TarInfo

Extraction filters

Default named filters

Filter errors

Hints for further verification

Supporting older Python versions

Stateful extraction filter example

Interfaz de línea de comandos

Opciones de línea de comandos

Ejemplos

Formatos tar con soporte

Problemas Unicode

zlib — Compresión compatible con gzip

Para aplicaciones que requieren compresión de datos, las funciones en este módulo permiten la compresión y descompresión mediante la biblioteca zlib. La biblioteca zlib tiene su propia página de inicio en https://www.zlib.net. Existen incompatibilidades conocidas entre el módulo de Python y las versiones de la biblioteca zlib anteriores a la 1.1.3; 1.1.3 tiene una vulnerabilidad de seguridad [https://zlib.net/zlib_faq.html#faq33], por lo que recomendamos usar 1.1.4 o posterior.

Las funciones de zlib tienen muchas opciones y, a menudo, deben usarse en un orden particular. Esta documentación no intenta cubrir todas las permutaciones; consulte el manual de zlib en http://www.zlib.net/manual.html para obtener información autorizada.

Para leer y escribir archivos .gz consultar el módulo gzip.

La excepción y las funciones disponibles en este módulo son:

exception zlib.error

Excepción provocada en errores de compresión y descompresión.

zlib.adler32(data[, value])

Calcula una suma de comprobación Adler-32 de data. (Una suma de comprobación Adler-32 es casi tan confiable como un CRC32, pero se puede calcular mucho más rápidamente). El resultado es un entero de 32 bits sin signo. Si value está presente, se utiliza como el valor inicial de la suma de comprobación; de lo contrario, se utiliza un valor predeterminado de 1. Pasar value permite calcular una suma de comprobación en ejecución durante la concatenación de varias entradas. El algoritmo no es criptográficamente fuerte y no se debe utilizar para la autenticación o las firmas digitales. Puesto que está diseñado como un algoritmo de suma de comprobación, no es adecuado su uso como un algoritmo hash general.

Distinto en la versión 3.0: The result is always unsigned. To generate the same numeric value when using Python 2 or earlier, use adler32(data) & 0xffffffff.

zlib.compress(data, /, level=-1)

Comprime los bytes de data, retornando un objeto bytes que contiene datos comprimidos. level es un entero de 0 a 9 o -1 que controla el nivel de compresión; 1 (Z_BEST_SPEED) es más rápido y produce la menor compresión, 9 (Z_BEST_COMPRESSION) es más lento y produce mayor compresión. 0 (Z_NO_COMPRESSION) no es compresión. El valor predeterminado es -1 (Z_DEFAULT_COMPRESSION). Z_DEFAULT_COMPRESSION representa un compromiso predeterminado entre velocidad y compresión (actualmente equivalente al nivel 6). Genera la excepción error si se produce algún error.

Distinto en la versión 3.6: level ahora se puede utilizar como parámetro de palabra clave.

zlib.compressobj(level=-1, method=DEFLATED, wbits=MAX_WBITS, memLevel=DEF_MEM_LEVEL, strategy=Z_DEFAULT_STRATEGY[, zdict])

Retorna un objeto de compresión, para ser usado para comprimir flujos de datos que no caben en la memoria de una vez.

level es el nivel de compresión – es un entero de `` 0`` a `` 9`` o `` -1``. Un valor de `` 1`` (Z_BEST_SPEED) es el más rápido y produce la menor compresión, mientras que un valor de `` 9`` (Z_BEST_COMPRESSION) es el más lento y produce la mayor cantidad. 0 (Z_NO_COMPRESSION) no es compresión. El valor predeterminado es -1 (Z_DEFAULT_COMPRESSION). Z_DEFAULT_COMPRESSION representa un compromiso predeterminado entre velocidad y compresión (actualmente equivalente al nivel 6).

method es el algoritmo de compresión. Actualmente, el único valor admitido es DEFLATED.

El argumento wbits controla el tamaño del búfer histórico (o el «tamaño de ventana») utilizado al comprimir datos, y si se incluye un encabezado y un avance en la salida. Puede tomar varios rangos de valores, por defecto es 15 (MAX_WBITS):

+9 a +15: el logaritmo en base dos del tamaño de la ventana, que por lo tanto oscila entre 512 y 32768. Los valores más grandes producen una mejor compresión a expensas de un mayor uso de memoria. Como resultado se incluirá un encabezado y un avance específicos de zlib.

−9 a −15: utiliza el valor absoluto de wbits como el logaritmo del tamaño de la ventana, al tiempo que produce una secuencia de salida sin encabezado ni suma de verificación.

+25 a +31 = 16 + (9 a 15): utiliza los 4 bits bajos del valor como el logaritmo del tamaño de la ventana, mientras que incluye un encabezado básico gzip y suma de verificación en la salida.

El argumento memLevel controla la cantidad de memoria utilizada para el estado de compresión interna. Los valores posibles varían de 1 a 9. Los valores más altos usan más memoria, pero son más rápidos y producen una salida más pequeña.

strategy se usa para ajustar el algoritmo de compresión. Los valores posibles son Z_DEFAULT_STRATEGY, Z_FILtered, Z_HUFFMAN_ONLY, Z_RLE (zlib 1.2.0.1) y Z_FIXED (zlib 1.2.2.2).

zdict es un diccionario de compresión predefinido. Este es una secuencia de bytes (como un objeto bytes) que contiene subsecuencias que se espera que ocurran con frecuencia en los datos que se van a comprimir. Las subsecuencias que se espera que sean más comunes deben aparecer al final del diccionario.

Distinto en la versión 3.3: Se agregó el parámetro zdict y el soporte de argumentos de palabras clave.

zlib.crc32(data[, value])

Calcula un suma de comprobación CRC (comprobación de redundancia cíclica, por sus siglas en inglés Cyclic Redundancy Check) de datos. El resultado es un entero de 32 bits sin signo. Si value está presente, se usa como el valor inicial de la suma de verificación; de lo contrario, se usa el valor predeterminado 0. Pasar value permite calcular una suma de verificación en ejecución sobre la concatenación de varias entradas. El algoritmo no es criptográficamente fuerte y no debe usarse para autenticación o firmas digitales. Dado que está diseñado para usarse como un algoritmo de suma de verificación, no es adecuado su uso como algoritmo hash general.

Distinto en la versión 3.0: The result is always unsigned. To generate the same numeric value when using Python 2 or earlier, use crc32(data) & 0xffffffff.

zlib.decompress(data, /, wbits=MAX_WBITS, bufsize=DEF_BUF_SIZE)

Descomprime los bytes en data, retornando un objeto de bytes que contiene los datos sin comprimir. El parámetro wbits depende del formato de data, y se trata más adelante. Si se da bufsize, se usa como el tamaño inicial del búfer de salida. Provoca la excepción error si se produce algún error.

El parámetro wbits controla el tamaño del búfer histórico (o el «tamaño de ventana») y qué formato de encabezado y cola se espera. Es similar al parámetro para compressobj(), pero acepta más rangos de valores:

+8 a +15: el logaritmo en base dos del tamaño del búfer. La entrada debe incluir encabezado y cola zlib.

0: determina automáticamente el tamaño del búfer desde el encabezado zlib. Solo se admite desde zlib 1.2.3.5.

-8 to -15: utiliza el valor absoluto de wbits como el logaritmo del tamaño del búfer. La entrada debe ser una transmisión sin formato, sin encabezado ni cola.

+24 a +31 = 16 + (8 a 15): utiliza los 4 bits de bajo orden del valor como el logaritmo del tamaño del búfer. La entrada debe incluir encabezado y cola gzip.

+40 a +47 = 32 + (8 a 15): utiliza los 4 bits de bajo orden del valor como el logaritmo del tamaño del búfer y acepta automáticamente el formato zlib o gzip.

Al descomprimir una secuencia, el tamaño del búfer no debe ser menor al tamaño utilizado originalmente para comprimir la secuencia; el uso de un valor demasiado pequeño puede generar una excepción error. El valor predeterminado wbits corresponde al tamaño más grande de búfer y requiere que se incluya encabezado y cola zlib.

bufsize es el tamaño inicial del búfer utilizado para contener datos descomprimidos. Si se requiere más espacio, el tamaño del búfer aumentará según sea necesario, por lo que no hay que tomar este valor como exactamente correcto; al ajustarlo solo se guardarán algunas llamadas en malloc().

Distinto en la versión 3.6: wbits y bufsize se pueden usar como argumentos de palabra clave.

zlib.decompressobj(wbits=MAX_WBITS[, zdict])

Retorna un objeto de descompresión, que se utilizará para descomprimir flujos de datos que no caben en la memoria de una vez.

El parámetro wbits controla el tamaño del búfer histórico (o el «tamaño de ventana») y qué formato de encabezado y cola se espera. Tiene el mismo significado que described for decompress().

El parámetro zdict especifica un diccionario de compresión predefinido. Si se proporciona, este debe ser el mismo diccionario utilizado por el compresor que produjo los datos que se van a descomprimir.

Nota

Si zdict es un objeto mutable (como bytearray), no se debe modificar su contenido entre la llamada decompressobj() y la primera llamada al método descompresor decompress().

Distinto en la versión 3.3: Se agregó el parámetro zdict.

Los objetos de compresión admiten los siguientes métodos:

Compress.compress(data)

Comprime data, y retorna al menos algunos de los datos comprimidos como un objeto de bytes. Estos datos deben concatenarse a la salida producida por cualquier llamada anterior al método compress(). Algunas entradas pueden mantenerse en un búfer interno para su posterior procesamiento.

Compress.flush([mode])

Se procesan todas las entradas pendientes y se retorna un objeto de bytes que contiene la salida comprimida restante. El argumento mode acepta una de las siguientes constantes Z_NO_FLUSH, Z_PARTIAL_FLUSH, Z_SYNC_FLUSH, Z_FULL_FLUSH, Z_BLOCK (zlib 1.2.3.4), o Z_FINISH, por defecto Z_FINISH. Excepto Z_FINISH, todas las constantes permiten comprimir más cadenas de bytes, mientras que Z_FINISH finaliza el flujo comprimido y evita la compresión de más datos. Después de llamar a flush() con mode establecido en Z_FINISH, el método compress() no se puede volver a llamar. La única acción posible es eliminar el objeto.

Compress.copy()

Retorna una copia del objeto compresor. Esto se puede utilizar para comprimir eficientemente un conjunto de datos que comparten un prefijo inicial común.

Distinto en la versión 3.8: Añadido copy.copy() y copy.deepcopy() para el soporte de objetos de compresión.

Los objetos de descompresión admiten los siguientes métodos y atributos:

Decompress.unused_data

Un objeto de bytes que contiene todos los bytes restantes después de los datos comprimidos. Es decir, esto permanece b "" hasta que esté disponible el último byte que contiene datos de compresión. Si la cadena de bytes completa resultó contener datos comprimidos, es b"", un objeto de bytes vacío.

Decompress.unconsumed_tail

Un objeto de bytes que contiene datos no procesados por la última llamada al método descompress() , debido a un desbordamiento del límite del búfer de datos descomprimidos. Estos datos aún no han sido procesados por la biblioteca zlib, por lo que debe enviarlos (potencialmente concatenando los datos nuevamente) mediante una llamada al método descompress() para obtener la salida correcta.

Decompress.eof

Un valor booleano que indica si se ha alcanzado el final del flujo de datos comprimido.

Esto hace posible distinguir entre un flujo comprimido correctamente y un flujo incompleto.

Nuevo en la versión 3.3.

Decompress.decompress(data, max_length=0)

Descomprime data, retornando un objeto de bytes que contiene al menos parte de los datos descomprimidos en string. Estos datos deben concatenarse con la salida producida por cualquier llamada anterior al método decompress(). Algunos de los datos de entrada pueden conservarse en búfer internos para su posterior procesamiento.

Si el parámetro opcional max_length no es cero, el valor de retorno no será más largo que max_length. Esto puede significar que no toda la entrada comprimida puede procesarse; y los datos no consumidos se almacenarán en el atributo unconsumed_tail. Esta cadena de bytes debe pasarse a una llamada posterior a decompress() si la descompresión ha de continuar. Si max_length es cero, toda la entrada se descomprime y unconsumed_tail queda vacío.

Distinto en la versión 3.6: max_length puede ser utilizado como argumento de palabras clave.

Decompress.flush([length])

Se procesan todas las entradas pendientes y se retorna un objeto de bytes que contiene el resto de los datos que se descomprimirán. Después de llamar a flush(), no se puede volver a llamar al método decompress(). La única acción posible es eliminar el objeto.

El parámetro opcional length establece el tamaño inicial del búfer de salida.

Decompress.copy()

Retorna una copia del objeto de descompresión. Puede usarlo para guardar el estado de la descompresión actual, de modo que pueda regresar rápidamente a esta ubicación más tarde.

Distinto en la versión 3.8: Añadido copy.copy() y copy.deepcopy() para el soporte de objetos de compresión.

La información sobre la versión de la biblioteca zlib en uso está disponible a través de las siguientes constantes:

zlib.ZLIB_VERSION

Versión de la biblioteca zlib utilizada al compilar el módulo. Puede ser diferente de la biblioteca zlib utilizada actualmente por el sistema, que puede ver en ZLIB_RUNTIME_VERSION.

zlib.ZLIB_RUNTIME_VERSION

Cadena que contiene la versión de la biblioteca zlib utilizada actualmente por el intérprete.

Nuevo en la versión 3.3.

Ver también

Módulo gzip

Lectura y escritura de los archivos en formato gzip.

http://www.zlib.net

Página oficial de la biblioteca zlib.

http://www.zlib.net/manual.html

El manual de zlib explica la semántica y el uso de las numerosas funciones de la biblioteca.

gzip — Soporte para archivos gzip

Código fuente: Lib/gzip.py [https://github.com/python/cpython/tree/3.9/Lib/gzip.py]

Este módulo proporciona una interfaz simple para comprimir y descomprimir archivos como lo harían los programas GNU gzip y gunzip.

La compresión de datos la proporciona el módulo zlib.

El módulo gzip proporciona la clase GzipFile, así como las funciones de conveniencia open(), compress() y decompress(). La clase GzipFile lee y escribe archivos de formato gzip, comprimiendo o descomprimiendo automáticamente los datos para que parezcan un file object ordinario.

Tenga en cuenta que los formatos de archivo adicionales que pueden ser descomprimidos por los programas gzip y gunzip, como los producidos por compress y pack, no son compatibles con este módulo.

El módulo define los siguientes elementos:

gzip.open(filename, mode='rb', compresslevel=9, encoding=None, errors=None, newline=None)

Abre un archivo comprimido gzip en modo binario o de texto, devolviendo un file object.

El argumento filename puede ser un nombre de archivo real (un objeto str o bytes), o un objeto archivo existente para leer o escribir.

El argumento mode puede ser cualquiera de 'r', 'rb', 'a', 'ab', 'w', 'wb', 'x' or 'xb' para el modo binario, o 'rt', 'at', 'wt', or 'xt' para el modo texto. El valor predeterminado es 'rb'.

El argumento compresslevel es un número entero de 0 a 9, como para el constructor GzipFile.

Para el modo binario, esta función es equivalente al constructor GzipFile: GzipFile (filename, mode, compresslevel). En este caso, no se deben proporcionar los argumentos encoding, errors y newline.

Para el modo texto, se crea un objeto GzipFile y se envuelve en una instancia io.TextIOWrapper con la codificación especificada, comportamiento de manejo de errores y terminación(es) de línea.

Distinto en la versión 3.3: Se agregó soporte para que filename sea un objeto de archivo, soporte para el modo de texto y los argumentos encoding, errors y newline.

Distinto en la versión 3.4: Se agregó soporte para los modos 'x', 'xb' y 'xt'.

Distinto en la versión 3.6: Acepta un path-like object.

exception gzip.BadGzipFile

Se lanzó una excepción para archivos gzip no válidos. Hereda OSError. OFError y zlib.error también se pueden lanzar para archivos gzip no válidos.

Nuevo en la versión 3.8.

class gzip.GzipFile(filename=None, mode=None, compresslevel=9, fileobj=None, mtime=None)

Constructor para la clase GzipFile, que simula la mayoría de los métodos de file object, con la excepción del método truncate(). Al menos uno de fileobj y filename debe recibir un valor no trivial.

La nueva instancia de clase se basa en fileobj, que puede ser un archivo normal, un objeto io.BytesIO, o cualquier otro objeto que simule un archivo. El valor predeterminado es None, en cuyo caso se abre filename para proporcionar un objeto de archivo.

Cuando fileobj no es None, el argumento filename solo se usa para ser incluido en el encabezado del archivo gzip, que puede incluir el nombre de archivo original del archivo sin comprimir. De forma predeterminada, el nombre de archivo es de fileobj, si es discernible; de lo contrario, el valor predeterminado es la cadena vacía, y en este caso el nombre del archivo original no se incluye en el encabezado.

El argumento mode puede ser cualquiera de 'r', 'rb', 'a', 'ab', 'w', 'wb', 'x', or 'xb', dependiendo de si el archivo se leerá o escribirá. El valor predeterminado es el modo de fileobj si es discernible; de lo contrario, el valor predeterminado es 'rb'. En futuras versiones de Python, no se utilizará el modo fileobj. Es mejor especificar siempre mode para escribir.

Tenga en cuenta que el archivo siempre se abre en modo binario. Para abrir un archivo comprimido en modo de texto, utilice open() (o ajuste su GzipFile con un io.TextIOWrapper).

El argumento compresslevel es un entero de 0 a 9 que controla el nivel de compresión; 1 es más rápido y produce la menor compresión, y 9 es más lento y produce la mayor compresión. 0 no es una compresión. El valor predeterminado es 9.

El argumento mtime es una marca de tiempo numérica opcional que se escribirá en el campo de tiempo de última modificación de la secuencia al comprimir. Sólo debe proporcionarse en modo de compresión. Si se omite o None, se utiliza la hora actual. Consulte el atributo mtime para obtener más detalles.

Al llamar en un objeto GzipFile el método close() no cierra fileobj, ya que es posible que desee anexar más material después de los datos comprimidos. Esto también le permite pasar un objeto io.BytesIO que se abrió para escribir como fileobj, y recupera el búfer de memoria resultante usando el io.BytesIO método del objeto getvalue().

GzipFile admite la interfaz io.BufferedIOBase, incluida la iteración y la declaración with. Solo el método truncate() no está implementado.

GzipFile también proporciona el siguiente método y atributo:

peek(n)

Lee n bytes no comprimidos sin avanzar en la posición del archivo. A lo sumo se realiza una sola lectura en la secuencia comprimida para satisfacer la llamada. El número de bytes retornados puede ser mayor o menor de lo solicitado.

Nota

Al llamar a peek() no cambia la posición del archivo GzipFile, puede cambiar la posición del objeto de archivo subyacente (por ejemplo, si el GzipFile se construyó con el parámetro fileobj).

Nuevo en la versión 3.2.

mtime

Al descomprimir, el valor de la última modificación del campo de tiempo en el encabezado de lectura más reciente se puede leer de este atributo, como un entero. El valor inicial antes de leer cualquier encabezado es None.

Todas las secuencias comprimidas gzip deben contener este campo de marca de tiempo. Algunos programas, como gunzip, hacen uso de la marca de tiempo. El formato es el mismo que el valor retornado de time.time() y el atributo st_mtime del objeto retornado por os.stat().

Distinto en la versión 3.1: Se ha agregado soporte para la declaración with, junto con el argumento del constructor mtime y el atributo mtime.

Distinto en la versión 3.2: Se agregó soporte para archivos con relleno de ceros y que no se pueden buscar.

Distinto en la versión 3.3: El método io.BufferedIOBase.read1() ahora está implementado.

Distinto en la versión 3.4: Se agregó soporte para los modos 'x' y 'xb'.

Distinto en la versión 3.5: Se ha añadido soporte para escribir objetos arbitrarios bytes-like objects. El método read() ahora acepta un argumento de None.

Distinto en la versión 3.6: Acepta un path-like object.

Obsoleto desde la versión 3.9: Abriendo GzipFile para escribir sin especificar el argumento mode está obsoleto.

gzip.compress(data, compresslevel=9, *, mtime=None)

Comprima los data, devolviendo un objeto bytes que contiene los datos comprimidos. compresslevel y mtime tienen el mismo significado que en el constructor GzipFile anterior.

Nuevo en la versión 3.2.

Distinto en la versión 3.8: Se agregó el parámetro mtime para una salida reproducible.

gzip.decompress(data)

Descomprime los data, devolviendo un objeto bytes que contiene los datos sin comprimir.

Nuevo en la versión 3.2.

Ejemplos de uso

Ejemplos de como leer un archivo comprimido:

import gzip
with gzip.open('/home/joe/file.txt.gz', 'rb') as f:
    file_content = f.read()

Ejemplos de como crear un archivo comprimido GZIP:

import gzip
content = b"Lots of content here"
with gzip.open('/home/joe/file.txt.gz', 'wb') as f:
    f.write(content)

Ejemplos de como GZIP comprime un archivo existente:

import gzip
import shutil
with open('/home/joe/file.txt', 'rb') as f_in:
    with gzip.open('/home/joe/file.txt.gz', 'wb') as f_out:
        shutil.copyfileobj(f_in, f_out)

Ejemplo de como GZIP comprime una cadena binaria:

import gzip
s_in = b"Lots of content here"
s_out = gzip.compress(s_in)

Ver también

Módulo zlib

El módulo básico de compresión de datos necesario para admitir el formato de archivo gzip.

Interfaz de Línea de Comandos

El módulo gzip proporciona una interfaz de línea de comandos simple para comprimir o descomprimir archivos.

Una vez ejecutado el módulo gzip conserva los archivos de entrada.

Distinto en la versión 3.8: Agrega una nueva interfaz de línea de comandos con un uso. De forma predeterminada, cuando ejecutará la CLI, el nivel de compresión predeterminado es 6.

Opciones de línea de comandos

file

Si no se especifica file, lee de sys.stdin.

--fast

Indica el método de compresión más rápido (menos compresión).

--best

Indica el método de compresión más lento (mejor compresión).

-d, --decompress

Descomprime el archivo dado.

-h, --help

Muestra el mensaje de ayuda.

bz2 — Soporte para compresión bzip2

Código fuente: Lib/bz2.py [https://github.com/python/cpython/tree/3.9/Lib/bz2.py]

Este módulo proporciona una interfaz completa para comprimir y descomprimir datos utilizando el algoritmo de compresión bzip2.

El módulo bz2 contiene:

La función open() y la clase BZ2File para leer y escribir archivos comprimidos.

Las clases BZ2Compressor y BZ2Decompressor para la (de)compresión incremental.

Las funciones compress() y decompress() para una (de)compresión en un solo paso.

Se puede acceder de forma segura a todas las clases de este módulo desde varios hilos.

(De)compresión de archivos

bz2.open(filename, mode='rb', compresslevel=9, encoding=None, errors=None, newline=None)

Abre un archivo comprimido con bzip2 en modo binario o texto, retorna un objeto archivo.

Al igual que con el constructor para BZ2File, el argumento filename puede ser un nombre de archivo real (un objeto str o bytes), o un objeto de archivo existente para leer o escribirle.

El argumento mode puede ser cualquiera de 'r', 'rb', 'w', 'wb', 'x', 'xb', 'a' o 'ab' para modo binario, o 'rt', 'wt', 'xt' , o 'a' para el modo de texto. El valor predeterminado es 'rb'.

El argumento compresslevel es un entero del 1 al 9, como para el constructor de BZ2File.

Para el modo binario, esta función es equivalente a BZ2File constructor: BZ2File(filename, mode, compresslevel=compresslevel). En este caso, no se deben proporcionar los argumentos encoding, errors y newline (nueva linea).

Para el modo de texto, se crea un objeto BZ2File, y se envuelve en una instancia io.TextIOWrapper con la codificación especificada, el comportamiento de manejo de errores y los final(es) de línea.

Nuevo en la versión 3.3.

Distinto en la versión 3.4: El modo 'x' (creación exclusiva) ha sido agregado.

Distinto en la versión 3.6: Acepta un objeto similar a una ruta (path-like object).

class bz2.BZ2File(filename, mode='r', *, compresslevel=9)

Abre un archivo comprimido con bzip2 en modo binario.

Si filename es un objeto tipo str o bytes, abre el archivo nombrado directamente. De lo contrario, filename debería ser un file object, que se utilizará para leer o escribir los datos comprimidos.

El argumento mode puede ser 'r' para lectura (predeterminado), 'w' para sobrescribir, 'x' para creación exclusiva o 'a' para anexar. Estos se pueden dar de manera equivalente como 'rb', 'wb', 'xb' y 'ab' respectivamente.

Si filename es un objeto de archivo (en lugar de un nombre de archivo real), el modo 'w' no trunca el archivo, y es equivalente a 'a'.

Si mode es 'w' o 'a', compresslevel puede ser un número entero entre 1 y 9 especificando el nivel de compresión: 1 produce la menor compresión y 9 (predeterminado) produce la mayor compresión.

Si mode es 'r', el archivo de entrada puede ser la concatenación de múltiples flujos (streams) comprimidos.

BZ2File proporciona todos los miembros especificados por io.BufferedIOBase, excepto detach() y truncate(). Se admite la iteración y la palabra clave with.

BZ2File también proporciona el siguiente método:

peek([n])

Retorna datos almacenados en el búfer sin avanzar la posición del archivo. Se retornará al menos un byte de datos (a menos que sea EOF). El número exacto de bytes retornados no está especificado.

Nota

Al invocar peek() no cambia la posición del archivo de BZ2File, puede cambiar la posición del objeto de archivo subyacente (por ejemplo, si BZ2File se construyó pasando un objeto de archivo a filename).

Nuevo en la versión 3.3.

Distinto en la versión 3.1: Se agregó soporte para la declaración with.

Distinto en la versión 3.3: Se agregaron los métodos fileno(), legible(), seekable(), writable(), read1() y readinto().

Distinto en la versión 3.3: Se agregó soporte para filename siendo un objeto de archivo (file object) en lugar de un nombre de archivo real.

Distinto en la versión 3.3: Se agregó el modo 'a' (agregar), junto con el soporte para leer archivos de flujo múltiple (multi-stream).

Distinto en la versión 3.4: El modo 'x' (creación exclusiva) ha sido agregado.

Distinto en la versión 3.5: El método read() ahora acepta el argumento None.

Distinto en la versión 3.6: Acepta un objeto similar a una ruta (path-like object).

Distinto en la versión 3.9: El parámetro buffering ha sido retirado. Desde Python 3.0 era ignorado y estaba obsoleto. Pasa un objeto archivo abierto para controlar cómo el archivo es abierto.

El parámetro compresslevel se convirtió en un argumento sólo por palabra clave.

(De)compresión incremental

class bz2.BZ2Compressor(compresslevel=9)

Crea un nuevo objeto compresor. Este objeto puede usarse para comprimir datos de forma incremental. Para comprimir en un solo paso, use la función compress() en su lugar.

compresslevel, si se proporciona, debe ser un número entero entre 1 y 9. El valor predeterminado es 9.

compress(data)

Provee datos al objeto del compresor. Retorna un fragmento de datos comprimidos si es posible, o una cadena de bytes vacía de lo contrario.

Cuando haya terminado de proporcionar datos al compresor, llame al método flush() para finalizar el proceso de compresión.

flush()

Termina el proceso de compresión. Retorna los datos comprimidos que quedan en los búferes internos.

El objeto compresor no puede usarse después de que se haya llamado a este método.

class bz2.BZ2Decompressor

Crea un nuevo objeto descompresor. Este objeto puede usarse para descomprimir datos de forma incremental. Para descomprimir en un solo paso, use la función decompress() en su lugar.

Nota

Esta clase no maneja de forma transparente las entradas que contienen múltiples flujos comprimidos, a diferencia de decompress() y BZ2File. Si necesitas descomprimir una entrada de flujo múltiple con BZ2Decompressor, debe usar un nuevo descompresor para cada flujo (stream).

decompress(data, max_length=-1)

Descomprime datos (un bytes-like object), retornando datos sin comprimir como bytes. Algunos de los datos pueden almacenarse internamente para su uso en llamadas posteriores a decompress(). Los datos retornados deben concatenarse con la salida de cualquier llamada anterior a decompress().

Si max_length no es negativo, retorna como máximo max_length bytes de datos descomprimidos. Si se alcanza este límite y se pueden producir más resultados, el atributo needs_input se establecerá en False. En este caso, la siguiente llamada a decompress() puede proporcionar datos como``b””`` para obtener más de la salida.

Si todos los datos de entrada se descomprimieron y retornaron (ya sea porque esto era menor que max_length bytes, o porque max_length era negativo), el atributo needs_input se establecerá en True.

Intentar descomprimir datos una vez que se alcanza el final de la transmisión genera un EOFError. Cualquier dato encontrado después del final del flujo se ignora y se guarda en el atributo unused_data.

Distinto en la versión 3.5: Añadido el parámetro max_length.

eof

True si se ha alcanzado el marcador de fin de flujo.

Nuevo en la versión 3.3.

unused_data

Datos encontrados después del final del flujo comprimido.

Si se accede a este atributo antes de que se haya alcanzado el final del flujo, su valor será b''.

needs_input

False si el método decompress() puede proporcionar más datos descomprimidos antes de requerir una nueva entrada sin comprimir.

Nuevo en la versión 3.5.

(Des)comprimir en un solo paso

bz2.compress(data, compresslevel=9)

Comprime datos, un objetos tipo binarios.

compresslevel, si se proporciona, debe ser un número entero entre 1 y 9. El valor predeterminado es 9.

Para compresión incremental, use BZ2Compressor en su lugar.

bz2.decompress(data)

Descomprime datos, un objetos tipo binarios.

Si data es la concatenación de múltiples flujos comprimidos, descomprime todos los flujos.

Para la descompresión incremental, use BZ2Decompressor en su lugar.

Distinto en la versión 3.3: Se agregó soporte para entradas de flujo múltiple.

Ejemplos de uso

Aquí hay algunos ejemplos del uso típico del modulo bz2.

Usando compress() y decompress() para demostrar una compresión de ida y vuelta (round-trip):

>>> import bz2
>>> data = b"""\
... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
... sit amet cursus ante. In interdum laoreet mi, sit amet ultrices purus
... pulvinar a. Nam gravida euismod magna, non varius justo tincidunt feugiat.
... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
>>> c = bz2.compress(data)
>>> len(data) / len(c)  # Data compression ratio
1.513595166163142
>>> d = bz2.decompress(c)
>>> data == d  # Check equality to original object after round-trip
True

Usando BZ2Compressor para compresión incremental:

>>> import bz2
>>> def gen_data(chunks=10, chunksize=1000):
...     """Yield incremental blocks of chunksize bytes."""
...     for _ in range(chunks):
...         yield b"z" * chunksize
...
>>> comp = bz2.BZ2Compressor()
>>> out = b""
>>> for chunk in gen_data():
...     # Provide data to the compressor object
...     out = out + comp.compress(chunk)
...
>>> # Finish the compression process.  Call this once you have
>>> # finished providing data to the compressor.
>>> out = out + comp.flush()

El ejemplo anterior utiliza un flujo de datos bastante «no aleatoria»(un flujo de fragmentos b»z»). Los datos aleatorios tienden a comprimirse mal, mientras que los datos ordenados y repetitivos generalmente producen una alta relación de compresión.

Escribiendo y leyendo un archivo comprimido con bzip2 en modo binario:

>>> import bz2
>>> data = b"""\
... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
... sit amet cursus ante. In interdum laoreet mi, sit amet ultrices purus
... pulvinar a. Nam gravida euismod magna, non varius justo tincidunt feugiat.
... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
>>> with bz2.open("myfile.bz2", "wb") as f:
...     # Write compressed data to file
...     unused = f.write(data)
>>> with bz2.open("myfile.bz2", "rb") as f:
...     # Decompress data from file
...     content = f.read()
>>> content == data  # Check equality to original object after round-trip
True

lzma — Compresión utilizando el algoritmo LZMA

Nuevo en la versión 3.3.

Código fuente:Lib/lzma.py [https://github.com/python/cpython/tree/3.9/Lib/lzma.py]

Este módulo provee clases y funciones de conveniencia para comprimir y descomprimir datos utilizando el algoritmo de compresión LZMA. También se incluye una interfaz de fichero soportando el .xz y formatos de fichero .lzma heredados utilizados por la utilidad xz, así como flujos comprimidos sin procesar.

La interfaz que provee este módulo es muy similar al del módulo bz2. Sin embargo, note que LZMAFile no es seguro en hilos, a diferencia de bz2.BZ2File, así que si necesita utilizar una única instancia LZMAFile desde múltiples hilos, es necesario protegerse con un bloqueo (lock).

exception lzma.LZMAError

Esta excepción es generada cuando un error ocurre durante la compresión o descompresión, o mientras se inicializa el estado de compresor/descompresor.

Leyendo y escribiendo ficheros comprimidos

lzma.open(filename, mode="rb", *, format=None, check=-1, preset=None, filters=None, encoding=None, errors=None, newline=None)

Abre un fichero comprimido LZMA in binario o modo texto, retornando un file object.

El argumento filename puede ser un nombre de fichero real (dado como un objeto str, bytes o path-like), en cuyo caso el fichero nombrado es abierto, o puede ser un objeto de fichero existente para leer o escribir.

El argumento mode puede ser cualquiera de "r", "rb", "w", "wb", "x", "xb", "a" o "a" para modo binario, o "rt", "wt", "xt", o "at" para modo texto. Por defecto es "rb".

Al abrir un fichero para lectura, los argumentos format y filters tienen el mismo significado que para LZMADecompressor. En este caso, los argumentos check y preset no deberían ser utilizados.

Al abrir un fichero para lectura, los argumentos format, check, preset y filters tienen el mismo significado que para LZMACompressor.

Para modo binario, esta función es equivalente al constructor LZMAFile: LZMAFile(filename, mode, ...). En este caso, los argumentos encoding, errors y newline no deben ser proveídos.

Para modo texto, un objeto LZMAFile es creado, y envuelto en una instancia io.TextIOWrapper con codificación específica, comportamiento de manejo de errores, y codificación(es) de línea.

Distinto en la versión 3.4: Agregado soporte para los modos "x", "xb" y "xt".

Distinto en la versión 3.6: Acepta un path-like object.

class lzma.LZMAFile(filename=None, mode="r", *, format=None, check=-1, preset=None, filters=None)

Abre un fichero comprimido LZMA en modo binario.

Un LZMAFIle puede envolver un ya abierto file object, u operar directamente en un fichero nombrado. El argumento filename especifica el objeto de fichero a envolver, o el nombre del fichero para abrir (como un str, bytes o un objeto path-like). Al envolver un objeto de fichero existente, el fichero envuelto no será cerrado cuando el LZMAFile es cerrado.

El argumento mode puede ser "r" para lectura (por defecto), "w" para sobreescritura, "x" para creación exclusiva, o "a" para agregado, Estos pueden ser equivalentemente dados como "rb", "wb", "xb" y "ab" respectivamente.

Si filename es un objeto de fichero (en lugar de un nombre de fichero actual), un modo de "w" no trunca el fichero, y en cambio es equivalente a "a".

Al abrir un fichero para escritura, el fichero de entrada puede ser la concatenación para múltiples flujos comprimidos separados. Estos son transparentemente decodificados como un único flujo lógico.

Al abrir un fichero para lectura, los argumentos format y filters tienen el mismo significado que para LZMADecompressor. En este caso, los argumentos check y preset no deberían ser utilizados.

Al abrir un fichero para lectura, los argumentos format, check, preset y filters tienen el mismo significado que para LZMACompressor.

LZMAFile soporta todos los miembros especificados por io.BufferedIOBase, excepto por detach() y truncate(). La declaración de iteración y with son soportados.

El siguiente método también es proveído:

peek(size=-1)

Retorna datos almacenados en búfer sin avanzar la posición del fichero. Al menos un byte de datos será retornado, a menos que EOF es alcanzado. El número exacto de bytes retornado no está especificado (el argumento size es ignorado).

Nota

Mientras que llamar peek() no cambia la posición de fichero del LZMAFile, puede cambiar la posición del objeto de fichero subyacente (por ejemplo si el LZMAFile fue construido pasando un objeto de fichero por filename).

Distinto en la versión 3.4: Agregado soporte para los modos "x" y "xb".

Distinto en la versión 3.5: El método read() acepta ahora un argumento de None.

Distinto en la versión 3.6: Acepta un path-like object.

Comprimiendo y descomprimiendo datos en memoria

class lzma.LZMACompressor(format=FORMAT_XZ, check=-1, preset=None, filters=None)

Crea un objeto compresor, el cual puede ser utilizado para comprimir datos incrementalmente.

Para una forma más conveniente de comprimir un único fragmento de datos, vea compress().

El argumento format especifica qué formato de contenedor debería ser utilizado. Posibles valores son:

FORMAT_XZ: El formato de contenedor .xz.

Este es el formato por defecto.

FORMAT_ALONE: El formato de contenedor .lzma heredado.

Este formato es más limitado que .xz – no soporta chequeos de integridad o múltiples filtros.

FORMAT_RAW: Un flujo de datos sin procesar, sin utilizar ningún formato de contenedor.

Este especificador de formato no soporta chequeos de integridad, y requiere que siempre especifiques una cadena de filtro personalizada (para compresión y descompresión). Adicionalmente, los datos comprimidos de esta manera no pueden ser descomprimidos utilizando FORMAT_AUTO (vea LZMADecompressor).

El argumento check especifica el tipo de chequeo de integridad a incluir en los datos descomprimidos. Este chequeo es utilizado al descomprimir, para asegurarse que los datos no han sido corrompidos. Los posibles valores son:

CHECK_NONE: Sin verificación de integridad. Este es el valor por defecto (y el único valor aceptable) para FORMAT_ALONE y FORMAT_RAW.

CHECK_CRC32: Chequeo de Redundancia Cíclica de 32 bits.

CHECK_CRC64: Chequeo de Redundancia Cíclica de 64 bits. Este es el valor por defecto para FORMAT_XZ.

CHECK_SHA256: Algoritmo Hash Seguro de 256 bits.

Si el chequeo especificado no es soportado, un LZMAError es generado.

Las configuraciones de compresión pueden ser especificadas como un nivel de compresión predefinido (con el argumento preset), o en detalle como una cadena de filtro personalizada (con el argumento filters).

El argumento preset (si es proveído) debería ser un entero entre 0```y ``9 (inclusive), opcionalmente OR con la constante PRESET_EXTREME. Si no se proporciona preset ni filters, el comportamiento por defecto es utilizar PRESET_DEFAULT (nivel preestablecido 6). Altos preestablecidos producen salidas más pequeñas, pero vuelve el proceso de compresión más lento.

Nota

En adición a ser más CPU-intensivo, la compresión con preestablecidos más altos también requiere mucha más memoria (y produce salida que necesita más memoria a descomprimir). Con un preestablecido de 9 por ejemplo, la sobrecarga para un objeto LZMACompressor puede ser tan alto como 800MiB. Por esta razón, es generalmente mejor quedarse con el preestablecido por defecto.

El argumento filters (si es proveído) debería ser un especificador de cadena de filtro. Vea Especificando cadenas de filtro personalizadas para detalles.

compress(data)

Comprime data (un objeto bytes), retornando un objeto bytes conteniendo información comprimida por al menos parte de la entrada. Algo de data puede ser almacenado internamente, para uso en llamadas posteriores a compress() y flush(). La información retornada debería ser concatenada con la salida en cualquier llamada previa a compress().

flush()

Finiquita el proceso de compresión, retornando un objeto bytes conteniendo cualquier información almacenada en los búferes internos del compresor.

El compresor no puede ser utilizado después de que este método es llamado.

class lzma.LZMADecompressor(format=FORMAT_AUTO, memlimit=None, filters=None)

Crea un objeto descompresor, el cual puede ser utilizado para descomprimir datos incrementalmente.

Para una forma más conveniente de descomprimir un flujo completo de compresión a la vez, vea decompress().

El argumento format especifica el formato de contenedor que debería ser utilizado. El valor por defecto es FORMAT_AUTO, el cual puede descomprimir los ficheros .xz y .lzma. Otros posibles valores son FORMAT_XZ, FORMAT_ALONE, y FORMAT_RAW.

El argumento memlimit especifica un límite (en bytes) en la cantidad de memoria que el descompresor puede utilizar. Cuando este argumento es utilizado, la descompresión fallará con un LZMAError si no es posible descomprimir la entrada dentro del límite de memoria dado.

El argumento filters especifica la cadena de filtro que fue utilizado para crear el flujo que se descomprime. El argumento es requerido si format es FORMAT_RAW, pero no debería ser utilizado para otros formatos. Vea Especificando cadenas de filtro personalizadas para más información sobre cadenas de filtro.

Nota

Esta clase no maneja transparentemente entradas que contienen múltiples flujos comprimidos, a diferencia de decompress() y LZMAFile. Para descomprimir una entrada multi-flujo con LZMADecompressor, debería crear un nuevo descompresor para cada flujo.

decompress(data, max_length=-1)

Descomprime data (un bytes-like object), retornando información sin comprimir como bytes. Alguna data puede ser almacenada internamente, para uso en llamadas posteriores a decompress(). La información retornada debería ser concatenada con la salida de cualquier llamada anterior a decompress().

Si max_length no es negativo, retorna al menos max_length bytes para descomprimir información, Si este límite es alcanzado y salidas adicionales pueden ser producidas, el atributo needs_input será establecido a False. En este caso, la siguiente llamada a decompress() podría proveer data como "b'' para obtener más de la salida.

Si toda la información ingresada fue descomprimida y retornada (ya sea porque esto fue menos que max_length bytes, o porque max_length fue negativo), el atributo needs_input será establecido a True.

Intentar descomprimir la información descomprimida después de que el fin del flujo es alcanzado genera un EOFError. Cualquier información encontrada después de que el fin del flujo es ignorada y guardada en el atributo unused_data.

Distinto en la versión 3.5: Agregado el parámetro max_length.

check

El ID del chequeo de integridad utilizado por el flujo de entrada. Esto puede ser CHECK_UNKNOWN hasta que suficiente de la entrada ha sido decodificada para determinar qué chequeo de integridad utiliza.

eof

True si el marcador de fin-de-flujo ha sido alcanzado.

unused_data

Información encontrada después del fin del flujo comprimido.

Antes de que el fin del flujo es alcanzado, este será "b".

needs_input

False si el método decompress() puede proveer más información descomprimida antes de requerir nueva entrada descomprimida.

Nuevo en la versión 3.5.

lzma.compress(data, format=FORMAT_XZ, check=-1, preset=None, filters=None)

Comprime data (un objeto bytes), retornando la información comprimida como un objeto bytes.

Vea LZMACompressor arriba para una descripción de los argumentos format, check, preset y filters.

lzma.decompress(data, format=FORMAT_AUTO, memlimit=None, filters=None)

Descomprime data (un objeto bytes), retornando la información descomprimida como un objeto bytes.

Si data es la concatenación de múltiples flujos comprimidos distintos, descomprime todos esos flujos, y retorna la concatenación de los resultados.

Vea LZMADecompressor arriba para una descripción de los argumentos format, memlimit y filters.

Misceláneas

lzma.is_check_supported(check)

Retorna True si el chequeo de integridad dado es soportado en este sistema.

CHECK_NONE y CHECK_CRC32 son soportados siempre. CHECK_CRC64 y CHECK_SHA256 pueden no estar disponibles si está utilizando una versión de liblzma que fue compilada con un conjunto de funciones limitado.

Especificando cadenas de filtro personalizadas

Un especificador de cadena de filtro es una secuencia de diccionarios, donde cada diccionario contiene el ID y opciones para un único filtro. Cada diccionario debe contener la llave "id", y puede contener llaves adicionales para especificar opciones filtro-dependientes. Los ID de filtro válidos son como sigue:

Filtro de compresión:

FILTER_LZMA1 (para uso con FORMAT_ALONE)

FILTER_LZMA2 (para uso con FORMAT_XZ y bytesFORMAT_RAW)

Filtro delta:

FILTER_DELTA

Filtros Branch-Call-Jump (BCJ):

FILTER_X86

FILTER_IA64

FILTER_ARM

FILTER_ARMTHUMB

FILTER_POWERPC

FILTER_SPARC

Una cadena de filtro puede consistir de hasta 4 filtros, y no puede estar vacía. El último filtro en la cadena debe ser un filtro de compresión, y cualquier otro filtro debe ser un filtro delta o BCJ.

Los filtros de compresión soportan las siguientes opciones (especificadas como entradas adicionales:

preset: Un ajuste de compresión a utilizar como una fuente de valores por defecto para opciones que no están especificadas explícitamente.

dict_size: Tamaño del diccionario en bytes. Esto debería estar entre 4 kiB y 1.5 GiB (inclusive).

lc Número de bits de contexto literal.

lp: Número de bits de posición literal. La suma lc + lp debe ser al menos 4.

pb: Número de bits de posición; debe ser al menos 4.

mode: MODE_FAST o MODE_NORMAL.

nice_len: Lo que debería ser considerado una «buena longitud» para una coincidencia. Esto debería ser 273 o menos.

mf: Qué buscador de coincidencias utilizar – MF_HC3, MF_HC4. MF_BT2, MF_BT3, o MF_BT4.

depth: Profundidad de búsqueda máxima utilizada por el buscador de coincidencias. 0 (por defecto) significa seleccionar automáticamente basado en otras opciones de filtro.

El filtro delta almacena las diferencias entre bytes, produciendo más entrada repetitiva para el compresor en ciertas circunstancias. Soporta una opción, dist. Esto indica la distancia entre bytes a ser sustraída. Por defecto es 1, por ejemplo toma las diferencias entre bytes adyacentes.

Los filtros BCJ están destinados a ser aplicados a código máquina. Convierten ramas, llamadas y saltos relativos en el código para utilizar el direccionamiento absoluto, con el objetivo de incrementar la redundancia que puede ser explotada por el compresor. Estos filtros soportan una opción, start_offset. Esto especifica la dirección que debería ser mapeada al comienzo de la entrada de información. Por defecto es 0.

Ejemplos

Leyendo un fichero comprimido:

import lzma
with lzma.open("file.xz") as f:
    file_content = f.read()

Creando un fichero comprimido:

import lzma
data = b"Insert Data Here"
with lzma.open("file.xz", "w") as f:
    f.write(data)

Comprimiendo información en memoria:

import lzma
data_in = b"Insert Data Here"
data_out = lzma.compress(data_in)

Compresión incremental:

import lzma
lzc = lzma.LZMACompressor()
out1 = lzc.compress(b"Some data\n")
out2 = lzc.compress(b"Another piece of data\n")
out3 = lzc.compress(b"Even more data\n")
out4 = lzc.flush()
# Concatenate all the partial results:
result = b"".join([out1, out2, out3, out4])

Escribiendo información comprimida en fichero ya abierto:

import lzma
with open("file.xz", "wb") as f:
    f.write(b"This data will not be compressed\n")
    with lzma.open(f, "w") as lzf:
        lzf.write(b"This *will* be compressed\n")
    f.write(b"Not compressed\n")

Creando un fichero comprimido utilizando una cadena de filtro personalizada:

import lzma
my_filters = [
    {"id": lzma.FILTER_DELTA, "dist": 5},
    {"id": lzma.FILTER_LZMA2, "preset": 7 | lzma.PRESET_EXTREME},
]
with lzma.open("file.xz", "w", filters=my_filters) as f:
    f.write(b"blah blah blah")

zipfile — Trabajar con archivos ZIP

Source code: Lib/zipfile.py [https://github.com/python/cpython/tree/3.9/Lib/zipfile.py]

El formato de archivo ZIP es un estándar común de archivo y compresión. Este módulo proporciona herramientas para crear, leer, escribir, agregar y listar un archivo ZIP. Cualquier uso avanzado de este módulo requerirá una comprensión del formato, tal como se define en la PKZIP Application Note [https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT].

Actualmente, este módulo no maneja archivos ZIP multi-disco. Puede manejar archivos ZIP que usan las extensiones ZIP64 (es decir, archivos ZIP que tienen más de 4 GB de tamaño). Admite el descifrado de archivos cifrados en archivos ZIP, pero actualmente no puede crear un archivo cifrado. El descifrado es extremadamente lento ya que se implementa en Python nativo en lugar de C.

El módulo define los siguientes elementos:

exception zipfile.BadZipFile

El error lanzado para archivos ZIP incorrectos.

Nuevo en la versión 3.2.

exception zipfile.BadZipfile

Alias de BadZipFile, para compatibilidad con versiones anteriores de Python.

Obsoleto desde la versión 3.2.

exception zipfile.LargeZipFile

El error lanzado cuando un archivo ZIP requiera la funcionalidad ZIP64 pero no ha sido habilitado.

class zipfile.ZipFile

La clase para leer y escribir archivos ZIP. Vea la sección Objetos ZipFile para detalles del constructor.

class zipfile.Path

Un contenedor compatible con pathlib para archivos zip. Vea la sección Objetos de ruta para más detalles.

Nuevo en la versión 3.8.

class zipfile.PyZipFile

Clase para crear archivos ZIP que contienen bibliotecas de Python.

class zipfile.ZipInfo(filename='NoName', date_time=(1980, 1, 1, 0, 0, 0))

Clase utilizada para representar información sobre un miembro de un archivo. Las instancias de esta clase son retornadas por los métodos getinfo() y infolist() de objetos ZipFile. La mayoría de los usuarios del módulo zipfile no necesitarán crearlos, sino que solo usarán aquellos creados por este módulo. filename debe ser el nombre completo del miembro del archivo, y date_time debe ser una tupla que contenga seis campos que describan la hora de la última modificación del archivo; los campos se describen en la sección Objetos ZipInfo.

zipfile.is_zipfile(filename)

Retorna True si filename es un archivo ZIP válido basado en su número mágico; de lo contrario, retorna False. filename también puede ser un archivo o un objeto similar a un archivo.

Distinto en la versión 3.1: Soporte para archivos y objetos similares a archivos.

zipfile.ZIP_STORED

La constante numérica para un miembro de archivo sin comprimir.

zipfile.ZIP_DEFLATED

La constante numérica para el método de compresión ZIP habitual. Esto requiere el módulo zlib.

zipfile.ZIP_BZIP2

La constante numérica para el método de compresión BZIP2. Esto requiere el módulo bz2.

Nuevo en la versión 3.3.

zipfile.ZIP_LZMA

La constante numérica para el método de compresión LZMA. Esto requiere el módulo lzma.

Nuevo en la versión 3.3.

Nota

La especificación del formato del archivo ZIP ha incluido soporte para la compresión bzip2 desde 2001 y para la compresión LZMA desde 2006. Sin embargo, algunas herramientas (incluidas las versiones anteriores de Python) no admiten estos métodos de compresión y pueden negarse a procesar el archivo ZIP por completo o no puede extraer archivos individuales.

Ver también

PKZIP Application Note [https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT]

Documentación sobre el formato de archivo ZIP por Phil Katz, el creador del formato y los algoritmos utilizados.

Info-ZIP Home Page [http://www.info-zip.org/]

Información sobre los programas de archivo ZIP del proyecto Info-ZIP y las bibliotecas de desarrollo.

Objetos ZipFile

class zipfile.ZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, compresslevel=None, *, strict_timestamps=True)

Abra un archivo ZIP, donde file puede ser una ruta a un archivo (una cadena), un objeto similar a un archivo o un path-like object.

El parámetro mode debe ser 'r' para leer un archivo existente, 'w' para truncar y escribir un nuevo archivo, 'a' para agregarlo a un archivo existente, o 'x' para crear y escribir exclusivamente un nuevo archivo. Si mode es 'x' y file se refiere a un archivo existente, se generará a FileExistsError. Si mode es 'a' y file se refiere a un archivo ZIP existente, entonces se le agregan archivos adicionales. Si file no se refiere a un archivo ZIP, se agrega un nuevo archivo ZIP al archivo. Esto está destinado a agregar un archivo ZIP a otro archivo (como: archivo:python.exe). Si mode es 'a' y el archivo no existe en absoluto, se crea. Si mode es 'r' o 'a', el archivo debe poder buscarse.

compression es el método de compresión ZIP que se utiliza al escribir el archivo, y debe ser ZIP_STORED, ZIP_DEFLATED, ZIP_BZIP2 o ZIP_LZMA; los valores no reconocidos harán que se lance NotImplementedError. Si ZIP_DEFLATED, ZIP_BZIP2 o ZIP_LZMA se especifica pero el módulo correspondiente (zlib, bz2 o lzma) no está disponible, RuntimeError es lanzado. El valor predeterminado es ZIP_STORED.

Si allowZip64 es True (el valor predeterminado) zipfile creará archivos ZIP que usan las extensiones ZIP64 cuando el archivo zip es mayor que 4 GB. Si es False zipfile generará una excepción cuando el archivo ZIP requiera extensiones ZIP64.

El parámetro compresslevel controla el nivel de compresión que se utilizará al escribir archivos en el archivo. Cuando se utiliza ZIP_STORED o ZIP_LZMA no tiene ningún efecto. Cuando se usa ZIP_DEFLATED se aceptan los enteros 0 a 9 (ver zlib para más información). Cuando se utiliza ZIP_BZIP2 se aceptan enteros 1 a 9 (consulte bz2 para obtener más información).

El argumento strictly_timestamps, cuando se establece en False, permite comprimir archivos anteriores a 1980-01-01 a costa de establecer la marca de tiempo en 1980-01-01. Un comportamiento similar ocurre con archivos más nuevos que 2107-12-31, la marca de tiempo también se establece en el límite.

Si el archivo se crea con el modo 'w', 'x' o 'a' y luego closed sin agregar ningún archivo al archivo, Las estructuras ZIP apropiadas para un archivo vacío se escribirán en el archivo.

ZipFile también es un manejador de contexto y por lo tanto, admite la declaración with. En el ejemplo, myzip se cierra después que el conjunto de instrucciones with se termine—incluso si se produce una excepción:

with ZipFile('spam.zip', 'w') as myzip:
    myzip.write('eggs.txt')

Nuevo en la versión 3.2: Se agregó la capacidad de usar ZipFile como administrador de contexto.

Distinto en la versión 3.3: Soporte agregado para bzip2 y compresión lzma.

Distinto en la versión 3.4: Las extensiones ZIP64 están habilitadas por defecto.

Distinto en la versión 3.5: Se agregó soporte para escribir en secuencias que no se pueden buscar. Se agregó soporte para el modo 'x'.

Distinto en la versión 3.6: Anteriormente, se generó un simple RuntimeError para valores de compresión no reconocidos.

Distinto en la versión 3.6.2: El parámetro file acepta un path-like object.

Distinto en la versión 3.7: Agregue el parámetro compresslevel.

Nuevo en la versión 3.8: El Argumento strict_timestamps solo palabra clave

ZipFile.close()

Cierra el archivo. Debe llamar a close() antes de salir de su programa o no se escribirán registros esenciales.

ZipFile.getinfo(name)

Retorna un objeto ZipInfo con información sobre el miembro del archivo name. Llamando a getinfo() para obtener un nombre que no figura actualmente en el archivo generará un KeyError.

ZipFile.infolist()

Retorna una lista que contiene un objeto ZipInfo para cada miembro del archivo. Los objetos están en el mismo orden que sus entradas en el archivo ZIP real en el disco si se abrió un archivo existente.

ZipFile.namelist()

Retorna una lista de miembros del archivo por nombre.

ZipFile.open(name, mode='r', pwd=None, *, force_zip64=False)

Acceda a un miembro del archivo como un objeto binario similar a un archivo. name puede ser el nombre de un archivo dentro del archivo o un objeto ZipInfo. El parámetro mode, si está incluido, debe ser 'r' (el valor predeterminado) o 'w'. pwd es la contraseña utilizada para descifrar archivos ZIP cifrados.

open() también es un administrador de contexto y por lo tanto, soporta with statement:

with ZipFile('spam.zip') as myzip:
    with myzip.open('eggs.txt') as myfile:
        print(myfile.read())

Con mode 'r', el objeto tipo archivo (ZipExtFile) es de solo lectura y proporciona los siguientes métodos: read(), readline(), readlines(), seek(), tell(), __iter__(), __ next__(). Estos objetos pueden funcionar independientemente del archivo Zip.

Con mode = 'w', se retorna un controlador de archivo escribible, que admite el método write(). Mientras está abierto un identificador de archivo escribible, intentar leer o escribir otros archivos en el archivo ZIP generará un ValueError.

Al escribir un archivo, si el tamaño del archivo no se conoce de antemano pero puede exceder los 2 GB, pase force_zip64 = True para asegurarse de que el formato del encabezado sea capaz de admitir archivos grandes. Si el tamaño del archivo se conoce de antemano, construya un objeto ZipInfo con file_size establecido, y úselo como parámetro name.

Nota

Los métodos open(), read() y extract() pueden tomar un nombre de archivo o un objeto ZipInfo. Apreciará esto cuando intente leer un archivo ZIP que contiene miembros con nombres duplicados.

Distinto en la versión 3.6: Se eliminó el soporte de mode='U'. Use io.TextIOWrapper para leer archivos de texto comprimido en modo universal newlines.

Distinto en la versión 3.6: ZipFile.open() can now be used to write files into the archive with the mode='w' option.

Distinto en la versión 3.6: Llamar a open() en un ZipFile cerrado generará un ValueError. Anteriormente, se planteó a RuntimeError.

ZipFile.extract(member, path=None, pwd=None)

Extraer un miembro del archivo al directorio de trabajo actual; member debe ser su nombre completo o un objeto ZipInfo. La información de su archivo se extrae con la mayor precisión posible. path especifica un directorio diferente para extraer. member puede ser un nombre de archivo o un objeto ZipInfo. pwd es la contraseña utilizada para archivos cifrados.

Retorna la ruta normalizada creada (un directorio o archivo nuevo).

Nota

Si el nombre de archivo de un miembro es una ruta absoluta, se eliminarán un punto compartido de drive/UNC y las barras diagonales (hacia atrás), ej: ///foo/bar se convierte en foo/bar en Unix y C:\foo\bar se convierte en foo\bar en Windows. Y todos los componentes `` «..» `` en un nombre de archivo miembro se eliminarán, ej: ../../foo../../ba..r se convierte en foo../ba..r. En Windows, los caracteres ilegales (: ``, `` <, > ``, `` | ``, `` "` `,?`` Y *) se reemplazan por guion bajo (_).

Distinto en la versión 3.6: Llamando extract() en un ZipFile cerrado generará un ValueError. Anteriormente, se planteó a RuntimeError.

Distinto en la versión 3.6.2: El parámetro path acepta un path-like object.

ZipFile.extractall(path=None, members=None, pwd=None)

Extrae todos los miembros del archivo al directorio de trabajo actual. path especifica un directorio diferente para extraer. members es opcional y debe ser un subconjunto de la lista retornada por namelist(). pwd es la contraseña utilizada para archivos cifrados.

Advertencia

Nunca extraiga archivos de fuentes no confiables sin inspección previa. Es posible que los archivos se creen fuera de path, ej. miembros que tienen nombres de archivo absolutos que comienzan con "/" o nombres de archivo con dos puntos "..". Este módulo intenta evitar eso. Ver extract() nota.

Distinto en la versión 3.6: Llamar a extractall() en un ZipFile cerrado generará un ValueError. Anteriormente, se planteó a RuntimeError.

Distinto en la versión 3.6.2: El parámetro path acepta un path-like object.

ZipFile.printdir()

Imprime una tabla de contenido para el archivo en sys.stdout.

ZipFile.setpassword(pwd)

Establece pwd como contraseña predeterminada para extraer archivos cifrados.

ZipFile.read(name, pwd=None)

Retorna los bytes del archivo name en el archivo. name es el nombre del archivo en el archivo, o un objeto ZipInfo. El archivo debe estar abierto para leer o agregar. pwd es la contraseña utilizada para los archivos cifrados y, si se especifica, anulará la contraseña predeterminada establecida con setpassword(). Llamar a read() en un archivo Zip que utiliza un método de compresión que no sea ZIP_STORED, ZIP_DEFLATED, ZIP_BZIP2 o ZIP_LZMA generará un NotImplementedError. También se generará un error si el módulo de compresión correspondiente no está disponible.

Distinto en la versión 3.6: Llamando read() en un ZipFile cerrado generará un ValueError. Anteriormente, se planteó a RuntimeError.

ZipFile.testzip()

Lee todos los archivos en el archivo y verifica sus CRC y encabezados de archivo. Retorna el nombre del primer archivo incorrecto o retorna None.

Distinto en la versión 3.6: Llamar a testzip() en un ZipFile cerrado generará un ValueError. Anteriormente, se planteó a RuntimeError.

ZipFile.write(filename, arcname=None, compress_type=None, compresslevel=None)

Escribe el archivo llamado filename en el archivo, dándole el nombre de archivo arcname (por defecto, será el mismo que filename, pero sin una letra de unidad y con los separadores de ruta principales eliminados). Si se proporciona, compress_type anula el valor dado para el parámetro compression al constructor para la nueva entrada. Del mismo modo, compresslevel anulará el constructor si se proporciona. El archivo debe estar abierto con el modo 'w', 'x' o 'a'.

Nota

Los nombres de archivo deben ser relativos a la raíz del archivo, es decir, no deben comenzar con un separador de ruta.

Nota

Si arcname (o filename, si arcname no se proporciona) contiene un byte nulo, el nombre del archivo en el archivo se truncará en el byte nulo.

Nota

A leading slash in the filename may lead to the archive being impossible to open in some zip programs on Windows systems.

Distinto en la versión 3.6: Llamando write() en un ZipFile creado con el modo 'r' o un ZipFile cerrado generará un ValueError. Anteriormente, se planteó a RuntimeError.

ZipFile.writestr(zinfo_or_arcname, data, compress_type=None, compresslevel=None)

Escribe un registro en el archivo. El contenido es data, que puede ser una instancia de str o a bytes; si es una str, primero se codifica como UTF-8. zinfo_or_arcname es el nombre del archivo que se le dará en el archivo o una instancia de ZipInfo. Si se trata de una instancia, se debe proporcionar al menos el nombre de archivo, la fecha y la hora. Si es un nombre, la fecha y la hora se configuran en la fecha y hora actuales. El archivo debe abrirse con el modo 'w', 'x' o 'a'.

Si se proporciona, compress_type anula el valor dado para el parámetro compression al constructor para la nueva entrada, o en zinfo_or_arcname (si es una instancia de ZipInfo). Del mismo modo, compresslevel anulará el constructor si se proporciona.

Nota

Al pasar una instancia de ZipInfo como el parámetro zinfo_or_arcname, el método de compresión utilizado será el especificado en el miembro compress_type de la instancia dada ZipInfo. Por defecto, el constructor ZipInfo establece este miembro en ZIP_STORED.

Distinto en la versión 3.2: El argumento compress_type.

Distinto en la versión 3.6: Llamando writestr() en un ZipFile creado con el modo 'r' o un ZipFile cerrado generará un ValueError. Anteriormente, se planteó a RuntimeError.

Los siguientes atributos de datos también están disponibles:

ZipFile.filename

Nombre del archivo ZIP.

ZipFile.debug

El nivel de salida de depuración a usar. Esto se puede configurar de 0 (el valor predeterminado, sin salida) a 3 (la mayor cantidad de salida). La información de depuración se escribe en sys.stdout.

ZipFile.comment

El comentario asociado con el archivo ZIP como un objeto bytes. Si se asigna un comentario a una instancia de ZipFile creada con el modo 'w', 'x' o 'a', no debe tener más de 65535 bytes. Los comentarios más largos que esto se truncarán.

Objetos de ruta

class zipfile.Path(root, at='')

Construye un objeto Path a partir de un archivo zip root (que puede ser una instancia ZipFile o file adecuado para pasar al constructor ZipFile).

at especifica la ubicación de esta ruta dentro del archivo zip, ej. “dir/file.txt”, “dir/” o “”.El valor predeterminado es la cadena vacía, que indica la raíz.

Los objetos de ruta exponen las siguientes características de objetos pathlib.Path:

Los objetos de ruta se pueden atravesar utilizando el operador /.

Path.name

El componente final de la ruta.

Path.open(mode='r', *, pwd, **)

Invoca ZipFile.open() en la ruta actual. Permite la apertura para lectura o escritura, texto o binario a través de los modos admitidos: “r”, “w”, “rb”, “wb”. Los argumentos posicionales y de palabras clave se pasan a través de io.TextIOWrapper cuando se abren como texto y se ignoran en caso contrario. pwd es el parámetro pwd para ZipFile.open().

Distinto en la versión 3.9: Se agregó soporte para modos de texto y binarios para abrir. El modo predeterminado ahora es texto.

Path.iterdir()

Enumera los hijos del directorio actual.

Path.is_dir()

Retorna True si el contexto actual hace referencia a un directorio.

Path.is_file()

Retorna True si el contexto actual hace referencia a un archivo.

Path.exists()

Retorna True si el contexto actual hace referencia a un archivo o directorio en el archivo zip.

Path.read_text(*, **)

Lee el archivo actual como texto unicode. Los argumentos posicionales y de palabras clave se pasan a io.TextIOWrapper (excepto buffer, que está implícito en el contexto).

Path.read_bytes()

Lee el archivo actual como bytes.

Objetos PyZipFile

El constructor PyZipFile toma los mismos parámetros que el constructor ZipFile, y un parámetro adicional, optimize.

class zipfile.PyZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, optimize=-1)

Nuevo en la versión 3.2: El parámetro optimize.

Distinto en la versión 3.4: Las extensiones ZIP64 están habilitadas por defecto.

Las instancias tienen un método ademas de los objetos ZipFile:

writepy(pathname, basename='', filterfunc=None)

Busca archivos *.py y agrega el archivo correspondiente al archivo.

Si no se proporcionó el parámetro optimize a PyZipFile o -1, el archivo correspondiente es un archivo *.pyc, compilando si es necesario.

Si el parámetro optimize a PyZipFile era 0, 1 or 2, solo se agregarán a ese archivo los archivos con ese nivel de optimización (ver compile()) el archivo, compilando si es necesario.

Si pathname es un archivo, el nombre del archivo debe terminar con .py, y solo el archivo (correspondiente *.pyc) se agrega en el nivel superior (sin información de ruta). Si pathname es un archivo que no termina con .py, se generará RuntimeError. Si es un directorio, y el directorio no es un directorio de paquetes, entonces todos los archivos *.pyc se agregan en el nivel superior. Si el directorio es un directorio de paquetes, todos *.pyc se agregan bajo el nombre del paquete como una ruta de archivo, y si alguno de los subdirectorios son directorios de paquetes, todos estos se agregan recursivamente en orden ordenado.

basename está destinado solo para uso interno.

filterfunc, si se proporciona, debe ser una función que tome un único argumento de cadena. Se le pasará cada ruta (incluida cada ruta de archivo completa individual) antes de que se agregue al archivo. Si filterfunc retorna un valor falso, la ruta no se agregará y si se trata de un directorio se ignorará su contenido. Por ejemplo, si nuestros archivos de prueba están todos en directorios de test o comienzan con la cadena test_, podemos usar un filterfunc para excluirlos

>>> zf = PyZipFile('myprog.zip')
>>> def notests(s):
...     fn = os.path.basename(s)
...     return (not (fn == 'test' or fn.startswith('test_')))
>>> zf.writepy('myprog', filterfunc=notests)

El método writepy() crea archivos con nombres de archivo como este

string.pyc                   # Top level name
test/__init__.pyc            # Package directory
test/testall.pyc             # Module test.testall
test/bogus/__init__.pyc      # Subpackage directory
test/bogus/myfile.pyc        # Submodule test.bogus.myfile

Nuevo en la versión 3.4: El parámetro filterfunc.

Distinto en la versión 3.6.2: El parámetro pathname acepta un path-like object.

Distinto en la versión 3.7: La recursividad ordena las entradas del directorio.

Objetos ZipInfo

Las instancias de la clase ZipInfo son retornadas por los métodos getinfo() y infolist() de ZipFile. Cada objeto almacena información sobre un solo miembro del archivo ZIP.

Hay un método de clase para hacer una instancia de ZipInfo para un archivo de sistema de archivos:

classmethod ZipInfo.from_file(filename, arcname=None, *, strict_timestamps=True)

Construye una instancia de ZipInfo para un archivo en el sistema de archivos, en preparación para agregarlo a un archivo zip.

filename debe ser la ruta a un archivo o directorio en el sistema de archivos.

Si se especifica arcname, este es usado como el nombre dentro del archivo. Si no se especifica arcname, el nombre será el mismo que filename, pero con cualquier letra de unidad y separadores de ruta principales eliminados.

El argumento strictly_timestamps, cuando se establece en False, permite comprimir archivos anteriores a 1980-01-01 a costa de establecer la marca de tiempo en 1980-01-01. Un comportamiento similar ocurre con archivos más nuevos que 2107-12-31, la marca de tiempo también se establece en el límite.

Nuevo en la versión 3.6.

Distinto en la versión 3.6.2: El parámetro filename acepta un path-like object.

Nuevo en la versión 3.8: El Argumento strict_timestamps solo palabra clave

Las instancias tienen los siguientes métodos y atributos:

ZipInfo.is_dir()

Retorna True si este miembro del archivo es un directorio.

Utiliza el nombre de la entrada: los directorios siempre deben terminar con /.

Nuevo en la versión 3.6.

ZipInfo.filename

Nombre del archivo en el archivo.

ZipInfo.date_time

La hora y fecha de la última modificación al miembro del archivo. Esta es una tupla de seis valores:

Índice

Valor

0

Año (>= 1980)

1

Mes (basado en uno)

2

Día del mes (basado en uno)

3

Horas (basados en cero)

4

Minutos (basados en cero)

5

Segundos (basado en cero)

Nota

El formato de archivo ZIP no admite marcas de tiempo anteriores a 1980.

ZipInfo.compress_type

Tipo de compresión para la miembro del archivo.

ZipInfo.comment

Comenta para el miembro de archivo individual como un objeto bytes.

ZipInfo.extra

Datos de campo de expansión. La PKZIP Application Note [https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT] contiene algunos comentarios sobre la estructura interna de los datos contenidos en este objeto bytes.

ZipInfo.create_system

Sistema que creó el archivo ZIP.

ZipInfo.create_version

Versión PKZIP que creó el archivo ZIP.

ZipInfo.extract_version

Se necesita la versión PKZIP para extraer el archivo.

ZipInfo.reserved

Debe ser cero.

ZipInfo.flag_bits

Bits de bandera ZIP.

ZipInfo.volume

Número de volumen del encabezado del archivo.

ZipInfo.internal_attr

Atributos internos.

ZipInfo.external_attr

Atributos de archivo externo.

ZipInfo.header_offset

Byte desplazado al encabezado del archivo.

ZipInfo.CRC

CRC-32 del archivo sin comprimir.

ZipInfo.compress_size

Tamaño de los datos comprimidos.

ZipInfo.file_size

Tamaño del archivo sin comprimir.

Interfaz de línea de comandos

El módulo zipfile proporciona una interfaz de línea de comandos simple para interactuar con archivos ZIP.

Si desea crear un nuevo archivo ZIP, especifique su nombre después de la opción -c y luego enumere los nombres de archivo que deben incluirse:

$ python -m zipfile -c monty.zip spam.txt eggs.txt

Pasar un directorio también es aceptable:

$ python -m zipfile -c monty.zip life-of-brian_1979/

Si desea extraer un archivo ZIP en el directorio especificado, use la opción -e:

$ python -m zipfile -e monty.zip target-dir/

Para obtener una lista de los archivos en un archivo ZIP, use la opción -l:

$ python -m zipfile -l monty.zip

Opciones de línea de comando

-l <zipfile>

--list <zipfile>

Lista de archivos en un archivo zip.

-c <zipfile> <source1> ... <sourceN>

--create <zipfile> <source1> ... <sourceN>

Crea el archivo zip a partir de archivos fuente.

-e <zipfile> <output_dir>

--extract <zipfile> <output_dir>

Extrae el archivo zip en el directorio de destino.

-t <zipfile>

--test <zipfile>

Prueba si el archivo zip es válido o no.

Problemas de descompresión

La extracción en el módulo zipfile puede fallar debido a algunos problemas que se enumeran a continuación.

Del archivo mismo

La descompresión puede fallar debido a una contraseña incorrecta / suma de verificación CRC / formato ZIP o método / descifrado de compresión no compatible.

Limitaciones del sistema de archivos

Exceder las limitaciones en diferentes sistemas de archivos puede causar que la descompresión falle. Como los caracteres permitidos en las entradas del directorio, la longitud del nombre del archivo, la longitud de la ruta, el tamaño de un solo archivo y la cantidad de archivos, etc.

Limitaciones de recursos

La falta de memoria o volumen de disco conduciría a la descompresión fallida. Por ejemplo, las bombas de descompresión (también conocido como ZIP bomb [https://en.wikipedia.org/wiki/Zip_bomb]) se aplican a la biblioteca de archivos zip que pueden causar el agotamiento del volumen del disco.

Interrupción

La interrupción durante la descompresión, como presionar control-C o matar el proceso de descompresión, puede dar como resultado una descompresión incompleta del archivo.

Comportamientos predeterminados de extracción

No conocer los comportamientos de extracción predeterminados puede causar resultados de descompresión inesperados. Por ejemplo, al extraer el mismo archivo dos veces, sobrescribe los archivos sin preguntar.

tarfile — Leer y escribir archivos tar

Código fuente: Lib/tarfile.py [https://github.com/python/cpython/tree/3.9/Lib/tarfile.py]

El módulo tarfile hace posible escribir y leer archivos tar, incluyendo aquellos que hacen uso de compresión gzip, bz2 y lzma. Utiliza el módulo zipfile para leer o escribir archivos .zip, o las funciones de nivel superior en shutil.

Algunos hechos y cifras:

lee y escribe archivos comprimidos gzip, bz2 y lzma si los respectivos módulos están disponibles.

soporte de lectura/escritura para el formato POSIX.1-1988 (ustar).

soporte de lectura/escritura para el formato GNU tar incluyendo extensiones longname y longlink, soporte de solo escritura para todas las variantes de extensiones de sparse (archivo disperso) incluyendo restablecimiento de archivos dispersos.

soporte de lectura/escritura para el formato POSIX.1-2001 (pax).

gestiona directorios, archivos regulares, enlaces duros, enlaces simbólicos, fifos, dispositivos de carácter, dispositivos de bloque y puede adquirir y restaurar información de archivo como marca de tiempo, permisos de acceso y dueño.

Distinto en la versión 3.3: Añadido soporte para compresión lzma.

tarfile.open(name=None, mode='r', fileobj=None, bufsize=10240, **kwargs)

Retorna un objeto TarFile para el nombre de ruta name. Para información detallada en los objetos de la clase TarFile y los argumentos por palabra clave que están permitidos, dirígete a Objetos TarFile.

mode tiene que ser una cadena de texto en el formato 'filemode[:compression]', adquiere el valor de 'r' de forma predeterminada. Aquí hay una lista completa de combinaciones de modo:

modo

acción

'r' o 'r:*'

Abrir para leer con compresión transparente (recomendado).

'r:'

Abrir para leer exclusivamente sin compresión.

'r:gz'

Abrir para leer con compresión gzip.

'r:bz2'

Abrir para leer con compresión bzip2.

'r:xz'

Abrir para leer con compresión lzma.

'x' o 'x:'

Crear un archivo tarfile exclusivamente sin compresión. Lanza una excepción FileExistsError si el archivo ya existe.

'x:gz'

Crear un archivo tar con compresión gzip. Lanza una excepción FileExistsError si ya existe.

'x:bz2'

Crear un archivo tar con compresión bzip2. Lanza una excepción FileExistsError si ya existe.

'x:xz'

Crear un archivo tar con compresión lzma. Lanza una excepción FileExistsError si ya existe.

'a' or 'a:'

Abrir para anexar sin compresión. El archivo se crea si no existe.

'w' o 'w:'

Abrir para escritura con compresión lzma.

'w:gz'

Abrir para escritura con compresión gzip.

'w:bz2'

Abrir para escritura con compresión bzip2.

'w:xz'

Abrir para escritura con compresión lzma.

Ten en cuenta que 'a:gz', 'a:bz2' or 'a:xz' no son posibles. Si mode no es apropiado para abrir ciertos archivos (comprimidos) para lectura, se lanza una excepción de tipo ReadError. Usa el modo 'r' para evitar esto. Si el método de compresión no es admitido, se lanza una excepción CompressionError.

Si fileobj es especificado, se utiliza como alternativa a file object abierto en modo binario para name. Debe estar en la posición 0.

Para los modos 'w:gz', 'r:gz', 'w:bz2', 'r:bz2', 'x:gz', 'x:bz2', tarfile.open() acepta el argumento por palabra clave compresslevel (por defecto 9) para especificar el nivel de compresión del archivo.

For modes 'w:xz' and 'x:xz', tarfile.open() accepts the keyword argument preset to specify the compression level of the file.

Para propósitos especiales, hay un segundo formato para modo: 'filemode|[compression]'. tarfile.open() retornará un objeto TarFile que procesa sus datos como un stream de bloques. No se realizará una búsqueda aleatoria en el archivo. Si se proporciona, fileobj puede ser un objeto con los métodos read() o write() (dependiendo del modo). bufsize especifica el blocksize y por default tiene un valor de 20 * 512 bytes. Utiliza esta variante en combinación con por ejemplo sys.stdin, un socket file object o un tape device. Sin embargo, dicho objeto TarFile está limitado en el aspecto de que no permite acceso aleatorio. Consulta Ejemplos. Los modos posibles:

Modo

Acción

'r|*'

Abre un stream de bloques tar para leer con compresión transparente.

'r|'

Abre un stream de bloques tar sin comprimir para lectura.

'r|gz'

Abre un stream comprimido con gzip para lectura.

'r|bz2'

Abre un stream bzip2 comprimido para lectura.

'r|xz'

Abre un stream lzma comprimido para lectura.

'w|'

Abre un stream sin comprimir para escritura.

'w|gz'

Abre un stream gzip comprimido para escritura.

'w|bz2'

Abre un stream bzip2 comprimido para escritura.

'w|xz'

Abre un stream lzma comprimido para escritura.

Distinto en la versión 3.5: El modo 'x' (creación exclusiva) fue añadido.

Distinto en la versión 3.6: El parámetro name acepta un objeto path-like object.

class tarfile.TarFile

Clase para leer y escribir archivos tar. No utilices esta clase directamente; usa tarfile.open() en su lugar. Consulta Objetos TarFile.

tarfile.is_tarfile(name)

Retorna True si name es un archivo tar, que el módulo tarfile puede leer. name puede ser un str, archivo o un objeto similar a un archivo.

Distinto en la versión 3.9: Soporte para archivos y objetos similares a archivos.

El módulo tarfile define las siguientes excepciones:

exception tarfile.TarError

Clase base para todas las excepciones del módulo tarfile.

exception tarfile.ReadError

Se lanza cuando un archivo tar se abre, que no puede ser manejado por el módulo tarfile o de alguna manera no es válido.

exception tarfile.CompressionError

Se lanza cuando un método de compresión no tiene soporte o cuando la información no puede ser decodificada de manera apropiada.

exception tarfile.StreamError

Se lanza para limitaciones que son comunes para objetos stream-like TarFile.

exception tarfile.ExtractError

Se lanza para errores no fatales cuando se utiliza TarFile.extract(), pero solo si TarFile.errorlevel== 2.

exception tarfile.HeaderError

Se lanza por TarInfo.frombuf() si el buffer que obtiene es invalido.

exception tarfile.FilterError

Base class for members refused by filters.

tarinfo

Information about the member that the filter refused to extract, as TarInfo.

exception tarfile.AbsolutePathError

Raised to refuse extracting a member with an absolute path.

exception tarfile.OutsideDestinationError

Raised to refuse extracting a member outside the destination directory.

exception tarfile.SpecialFileError

Raised to refuse extracting a special file (e.g. a device or pipe).

exception tarfile.AbsoluteLinkError

Raised to refuse extracting a symbolic link with an absolute path.

exception tarfile.LinkOutsideDestinationError

Raised to refuse extracting a symbolic link pointing outside the destination directory.

Las siguientes constantes están disponibles a nivel de módulo:

tarfile.ENCODING

La codificación para caracteres predeterminada: 'utf-8' en Windows, de otra manera, el valor retornado por sys.getfilesystemencoding().

Cada una de las siguientes constantes define un formato de archivo tar que el módulo tarfile puede crear. Ve la sección: Formatos tar con soporte para más detalles.

tarfile.USTAR_FORMAT

Formato POSIX.1-1988 (ustar).

tarfile.GNU_FORMAT

Formato GNU tar.

tarfile.PAX_FORMAT

Formato POSIX.1-2001 (pax).

tarfile.DEFAULT_FORMAT

El formato predeterminado para crear archivos. Es actualmente PAX_FORMAT.

Distinto en la versión 3.8: El formato predeterminado para nuevos archivos fue cambiado de GNU_FORMAT a PAX_FORMAT.

Ver también

Módulo zipfile

Documentación del módulo estándar zipfile.

Operaciones de archivado

Documentación para las facilidades de archivos de más alto nivel proporcionadas por el módulo estándar shutil.

Manual GNU tar, formato básico tar [https://www.gnu.org/software/tar/manual/html_node/Standard.html]

Documentación para archivos de tipo tar, incluyendo extensiones GNU tar.

Objetos TarFile

El objeto TarFile provee una interfaz a un archivo tar. Un archivo tar es una secuencia de bloques. Un miembro de archivos (un archivo almacenado) está hecho de un bloque de encabezado seguido de bloques de datos. Es posible almacenar un archivo dentro de un tar múltiples veces. Cada archivo miembro está representado por un objeto TarInfo, consulta Objetos TarInfo para más detalles.

Un objeto TarFile puede ser usado como un administrador de contexto en una declaración with. Será automáticamente cerrado cuando el bloque sea completado. Ten en cuenta que en el evento de una excepción un archivo abierto para escritura no será terminado; solo el objeto de archivo interno será cerrado. Consulta la sección Ejemplos para un caso de uso.

Nuevo en la versión 3.2: Añadido soporte para el protocolo de administración de contexto.

class tarfile.TarFile(name=None, mode='r', fileobj=None, format=DEFAULT_FORMAT, tarinfo=TarInfo, dereference=False, ignore_zeros=False, encoding=ENCODING, errors='surrogateescape', pax_headers=None, debug=0, errorlevel=1)

Los siguientes argumentos son opcionales y también se pueden acceder como atributos de instancia.

name es el nombre de ruta del archivo. name puede ser un objeto path-like object. Puede ser omitido si fileobj se proporciona. En este caso, el atributo name del objeto de archivo se usa si existe.

mode puede ser 'r' para leer desde un archivo existente, 'a' para adjuntar datos a un archivo existente,``”w”`` para crear un nuevo archivo sobrescribiendo uno existente, o 'x' para crear un nuevo archivo únicamente si este no existe.

Si fileobj es proporcionado, se utiliza para escritura o lectura de datos. Si puede ser determinado, mode puede ser anulado por el modo de fileobj. fileobj será usado desde la posición 0.

Nota

fileobj no se cierra cuando TarFile se cierra.

format controla el formato de archivo para la escritura. Debe ser una de las constantes USTAR_FORMAT, GNU_FORMAT o PAX_FORMAT que se definen a nivel de módulo. Al leer, el formato se detectará automáticamente, incluso si hay diferentes formatos en un solo archivo.

El argumento tarinfo puede ser utilizado para reemplazar la clase predeterminada TarInfo con una diferente.

Si dereference tiene el valor de False, añade enlaces simbólicos y duros al archivo. Si tiene el valor de True, añade el contenido de archivos objetivo al archivo. Esto no tiene ningún efecto en los sistemas que no admiten enlaces simbólicos.

Si ignore_zeros tiene el valor de False, trata un bloque vacío como el final del archivo. Si es True, omite los bloques vacíos (y no válidos) e intenta obtener tantos miembros como sea posible. Esto solo es útil para leer archivos concatenados o dañados.

debug puede ser establecido con valores desde 0 (sin mensajes de depuración) hasta 3 (todos los mensajes de depuración). Los mensajes son escritos en sys.stderr.

errorlevel controls how extraction errors are handled, see the corresponding attribute.

Los argumentos encoding y errors definen la codificación de caracteres que se utilizará para lectura o escritura del archivo y como los errores de conversión van a ser manejados. La configuración predeterminada funcionará para la mayoría de los usuarios. Mira la sección Problemas Unicode para más información a detalle.

El argumento pax_headers es un diccionario opcional de cadenas las cuales serán añadidas como un encabezado pax global si el valor de format es PAX_FORMAT.

Distinto en la versión 3.2: Utiliza 'surrogateescape' como valor predeterminado del argumento errors.

Distinto en la versión 3.5: El modo 'x' (creación exclusiva) fue añadido.

Distinto en la versión 3.6: El parámetro name acepta un objeto path-like object.

classmethod TarFile.open(...)

Constructor alternativo. La función tarfile.open() es un acceso directo a este método de la clase.

TarFile.getmember(name)

Retorna un objeto TarInfo para el miembro name. Si name no puede ser encontrado, entonces una excepción de tipo KeyError será lanzada.

Nota

Si un miembro aparece más de una vez en el archivo, se asume que su última aparición es la versión más actualizada.

TarFile.getmembers()

Retorna los miembros del archivo como una lista de objetos TarInfo. La lista tiene el mismo orden que los miembros del archivo.

TarFile.getnames()

Retorna los miembros como una lista de sus nombres. Tiene el mismo orden que la lista retornada por getmembers().

TarFile.list(verbose=True, *, members=None)

Imprime en sys.stdout una tabla de contenidos. Si verbose es False, solo los nombres de los miembros son impresos. si es True, se produce una salida de impresión similar a la de ls -l. Si el parámetro members es proporcionado, debe ser un subconjunto de la lista retornada por getmembers().

Distinto en la versión 3.5: Se agregó el parámetro members.

TarFile.next()

Retorna el siguiente miembro del archivo como un objeto TarInfo cuando TarFile se abre para lectura. Retorna None si no hay más miembros disponibles.

TarFile.extractall(path=".", members=None, *, numeric_owner=False, filter=None)

Extrae todos los miembros de un archivo al directorio de trabajo actual o al directorio de path. Si se proporciona el parámetro opcional members, debe ser un subconjunto de la lista retornada por el método getmembers(). Información de directorio como dueño, fecha de modificación y permisos son establecidos una vez que todos los miembros han sido extraídos. Esto se realiza para trabajar con dos problemáticas: La fecha de modificación de un directorio es modificada cada vez que un archivo es creado en el. Y si los permisos de un directorio no permiten escritura, extraer archivos en el no será posible.

Si numeric_owner tiene el valor de True, los números uid y gid del archivo tar se utilizan para establecer el dueño/grupo de los archivos extraídos. De lo contrario, se utilizan los valores nombrados del archivo tar.

The filter argument, which was added in Python 3.9.17, specifies how members are modified or rejected before extraction. See Extraction filters for details. It is recommended to set this explicitly depending on which tar features you need to support.

Advertencia

Nunca extraigas archivos de fuentes no confiables sin una inspección previa. Es posible que los archivos se creen fuera de path, Ej. miembros que tienen nombres de archivo absolutos que comienzan con "/" o nombres de archivo con dos puntos "..".

Set filter='data' to prevent the most dangerous security issues, and read the Extraction filters section for details.

Distinto en la versión 3.5: Se agregó el parámetro numeric_owner.

Distinto en la versión 3.6: El parámetro path acepta a path-like object.

Distinto en la versión 3.9.17: Se agregó el parámetro filter.

TarFile.extract(member, path="", set_attrs=True, *, numeric_owner=False, filter=None)

Extrae un miembro del archivo al directorio de trabajo actual utilizando su nombre completo. La información de su archivo se extrae con la mayor precisión posible. member puede ser un nombre de archivo o un objeto TarInfo. Puedes especificar un directorio diferente utilizando path. path puede ser un path-like object. Los atributos de archivo (dueño, fecha de modificación, modo) son establecidos a no ser que set_attrs sea falso.

The numeric_owner and filter arguments are the same as for extractall().

Nota

El método extract() no cuida de varios problemas de extracción. En la mayoría de los casos deberías considerar utilizar el método extractall().

Advertencia

Consulta la advertencia para extractall().

Set filter='data' to prevent the most dangerous security issues, and read the Extraction filters section for details.

Distinto en la versión 3.2: Se agregó el parámetro set_attrs.

Distinto en la versión 3.5: Se agregó el parámetro numeric_owner.

Distinto en la versión 3.6: El parámetro path acepta a path-like object.

Distinto en la versión 3.9.17: Se agregó el parámetro filter.

TarFile.extractfile(member)

Extrae un miembro del archivo como un objeto de archivo. member puede ser un nombre de archivo o un objeto TarInfo. Si member es un archivo normal o un enlace, se retorna un objeto io.BufferedReader. Para todos los demás miembros existentes, se retorna None. Si member no aparece en el archivo, se lanza KeyError.

Distinto en la versión 3.3: Retorna un objeto io.BufferedReader.

TarFile.errorlevel: int

If errorlevel is 0, errors are ignored when using TarFile.extract() and TarFile.extractall(). Nevertheless, they appear as error messages in the debug output when debug is greater than 0. If 1 (the default), all fatal errors are raised as OSError or FilterError exceptions. If 2, all non-fatal errors are raised as TarError exceptions as well.

Some exceptions, e.g. ones caused by wrong argument types or data corruption, are always raised.

Custom extraction filters should raise FilterError for fatal errors and ExtractError for non-fatal ones.

Note that when an exception is raised, the archive may be partially extracted. It is the user’s responsibility to clean up.

TarFile.extraction_filter

Nuevo en la versión 3.9.17.

The extraction filter used as a default for the filter argument of extract() and extractall().

The attribute may be None or a callable. String names are not allowed for this attribute, unlike the filter argument to extract().

If extraction_filter is None (the default), calling an extraction method without a filter argument will use the fully_trusted filter for compatibility with previous Python versions.

In Python 3.12+, leaving extraction_filter=None will emit a DeprecationWarning.

In Python 3.14+, leaving extraction_filter=None will cause extraction methods to use the data filter by default.

The attribute may be set on instances or overridden in subclasses. It also is possible to set it on the TarFile class itself to set a global default, although, since it affects all uses of tarfile, it is best practice to only do so in top-level applications or site configuration. To set a global default this way, a filter function needs to be wrapped in staticmethod() to prevent injection of a self argument.

TarFile.add(name, arcname=None, recursive=True, *, filter=None)

Añade el archivo name al archivo. name puede ser cualquier tipo de archivo (directorio, fifo, enlace simbólico, etc.). Si se proporciona, arcname especifica un nombre alternativo para el archivo en el archivo. Los directorios se agregan de forma recursiva de forma predeterminada. Esto se puede evitar estableciendo recursive con el valor de False. La recursividad agrega entradas en orden ordenado. Si se proporciona filter, debería ser una función que tome un argumento de objeto TarInfo y retorna el objeto TarInfo modificado. Si en cambio retorna None, el objeto TarInfo será excluido del archivo. Consulta Ejemplos para ver un ejemplo.

Distinto en la versión 3.2: Se agregó el parámetro filter.

Distinto en la versión 3.7: La recursividad agrega entradas en orden ordenado.

TarFile.addfile(tarinfo, fileobj=None)

Añade el objeto TarInfo tarinfo al archivo. Si se proporciona fileobj, debería ser un binary file, y los bytes de tarinfo.size se leen y se agregan al archivo. Puedes crear objetos TarInfo directamente o usando gettarinfo().

TarFile.gettarinfo(name=None, arcname=None, fileobj=None)

Crea un objeto TarInfo a partir del resultado de os.stat() o equivalente en un archivo existente. El archivo es nombrado por name o especificado como un objeto file object fileobj con un descriptor de archivo. name puede ser un objeto path-like object. Si es proporcionado, arcname especifica un nombre alternativo para el archivo en el archivo, de otra forma, el nombre es tomado del atributo fileobj’s name, o el argumento name. El nombre puede ser una cadena de texto.

Puedes modificar algunos de los atributos de la clase TarInfo’ antes de que lo añadas utilizado el método addfile(). Si el archivo objeto no es un archivo objeto ordinario posicionado al principio del archivo, atributos como size puede que necesiten modificaciones. Este es el caso para objetos como GzipFile. El atributo name también puede ser modificado, en cuyo caso arcname podría ser una cadena ficticia.

Distinto en la versión 3.6: El parámetro name acepta un objeto path-like object.

TarFile.close()

Cierra TarFile. En el modo de escritura, se añaden dos bloques de cero de finalización al archivo.

TarFile.pax_headers

Un diccionario que contiene pares claves-valor de los encabezados globales pax.

Objetos TarInfo

Un objeto TarInfo representa un miembro en TarFile. Además de almacenar todos los atributos requeridos de un archivo (como tipo de archivo, tamaño, fecha, permisos, dueño, etc.), provee de algunos métodos útiles para determinar su tipo. No contiene los datos del archivo por si mismo.

TarInfo objects are returned by TarFile’s methods getmember(), getmembers() and gettarinfo().

Modifying the objects returned by getmember() or getmembers() will affect all subsequent operations on the archive. For cases where this is unwanted, you can use copy.copy() or call the replace() method to create a modified copy in one step.

Several attributes can be set to None to indicate that a piece of metadata is unused or unknown. Different TarInfo methods handle None differently:

The extract() or extractall() methods will ignore the corresponding metadata, leaving it set to a default.

addfile() will fail.

list() will print a placeholder string.

Distinto en la versión 3.9.17: Added replace() and handling of None.

class tarfile.TarInfo(name="")

Crea un objeto TarInfo.

classmethod TarInfo.frombuf(buf, encoding, errors)

Crea y retorna un objeto TarInfo.

Lanza una excepción HeaderError si el buffer es invalido.

classmethod TarInfo.fromtarfile(tarfile)

Lee el siguiente miembro del objeto de la clase TarFile tarfile y lo retorna como un objeto TarInfo.

TarInfo.tobuf(format=DEFAULT_FORMAT, encoding=ENCODING, errors='surrogateescape')

Crear un buffer de cadena a partir de un objeto TarInfo. Para información sobre los argumentos consulta el constructor de la clase TarFile.

Distinto en la versión 3.2: Utiliza 'surrogateescape' como valor predeterminado del argumento errors.

Un objeto TarInfo tiene los siguientes atributos de dato públicos:

TarInfo.name: str

Nombre del archivo miembro.

TarInfo.size: int

Tamaño en bytes.

TarInfo.mtime: int | float

Time of last modification in seconds since the epoch, as in os.stat_result.st_mtime.

Distinto en la versión 3.9.17: Can be set to None for extract() and extractall(), causing extraction to skip applying this attribute.

TarInfo.mode: int

Permission bits, as for os.chmod().

Distinto en la versión 3.9.17: Can be set to None for extract() and extractall(), causing extraction to skip applying this attribute.

TarInfo.type

Tipo de archivo. type es por lo general una de las siguientes constantes: REGTYPE, AREGTYPE, LNKTYPE, SYMTYPE, DIRTYPE, FIFOTYPE, CONTTYPE, CHRTYPE, BLKTYPE, GNUTYPE_SPARSE. Para determinar el tipo de un objeto TarInfo de forma más conveniente, utiliza los métodos is*() de abajo.

TarInfo.linkname: str

Nombre del archivo objetivo, el cual solo está presente en los objetos TarInfo de tipo LNKTYPE y del tipo SYMTYPE.

For symbolic links (SYMTYPE), the linkname is relative to the directory that contains the link. For hard links (LNKTYPE), the linkname is relative to the root of the archive.

TarInfo.uid: int

ID de usuario que originalmente almacenó este miembro.

Distinto en la versión 3.9.17: Can be set to None for extract() and extractall(), causing extraction to skip applying this attribute.

TarInfo.gid: int

ID de grupo del usuario que originalmente almacenó este miembro.

Distinto en la versión 3.9.17: Can be set to None for extract() and extractall(), causing extraction to skip applying this attribute.

TarInfo.uname: str

Nombre de usuario.

Distinto en la versión 3.9.17: Can be set to None for extract() and extractall(), causing extraction to skip applying this attribute.

TarInfo.gname: str

Nombre del grupo.

Distinto en la versión 3.9.17: Can be set to None for extract() and extractall(), causing extraction to skip applying this attribute.

TarInfo.pax_headers: dict

Un diccionario que contiene pares key-value de un encabezado pax extended.

TarInfo.replace(name=..., mtime=..., mode=..., linkname=...,

uid=..., gid=..., uname=..., gname=...,

deep=True)

Nuevo en la versión 3.9.17.

Return a new copy of the TarInfo object with the given attributes changed. For example, to return a TarInfo with the group name set to 'staff', use:

new_tarinfo = old_tarinfo.replace(gname='staff')

By default, a deep copy is made. If deep is false, the copy is shallow, i.e. pax_headers and any custom attributes are shared with the original TarInfo object.

Un objeto TarInfo también provee de algunos métodos de consulta convenientes:

TarInfo.isfile()

Retorna True si el objeto Tarinfo es un archivo regular.

TarInfo.isreg()

Igual que isfile().

TarInfo.isdir()

Retorna True si es un directorio.

TarInfo.issym()

Retorna True si es un enlace simbólico.

TarInfo.islnk()

Retorna True si es un enlace duro.

TarInfo.ischr()

Retorna True si es un dispositivo de caracter.

TarInfo.isblk()

Retorna True si es un dispositivo de bloque.

TarInfo.isfifo()

Retorna True si es un FIFO.

TarInfo.isdev()

Retorna True si es uno de los caracteres de dispositivo, dispositivo de bloque o FIFO.

Extraction filters

Nuevo en la versión 3.9.17.

The tar format is designed to capture all details of a UNIX-like filesystem, which makes it very powerful. Unfortunately, the features make it easy to create tar files that have unintended – and possibly malicious – effects when extracted. For example, extracting a tar file can overwrite arbitrary files in various ways (e.g. by using absolute paths, .. path components, or symlinks that affect later members).

In most cases, the full functionality is not needed. Therefore, tarfile supports extraction filters: a mechanism to limit functionality, and thus mitigate some of the security issues.

Ver también

PEP 706 [https://www.python.org/dev/peps/pep-0706]

Contains further motivation and rationale behind the design.

The filter argument to TarFile.extract() or extractall() can be:

the string 'fully_trusted': Honor all metadata as specified in the archive. Should be used if the user trusts the archive completely, or implements their own complex verification.

the string 'tar': Honor most tar-specific features (i.e. features of UNIX-like filesystems), but block features that are very likely to be surprising or malicious. See tar_filter() for details.

the string 'data': Ignore or block most features specific to UNIX-like filesystems. Intended for extracting cross-platform data archives. See data_filter() for details.

None (default): Use TarFile.extraction_filter.

If that is also None (the default), the 'fully_trusted' filter will be used (for compatibility with earlier versions of Python).

In Python 3.12, the default will emit a DeprecationWarning.

In Python 3.14, the 'data' filter will become the default instead. It’s possible to switch earlier; see TarFile.extraction_filter.

A callable which will be called for each extracted member with a TarInfo describing the member and the destination path to where the archive is extracted (i.e. the same path is used for all members):

filter(/, member: TarInfo, path: str) -> TarInfo | None

The callable is called just before each member is extracted, so it can take the current state of the disk into account. It can:

return a TarInfo object which will be used instead of the metadata in the archive, or

return None, in which case the member will be skipped, or

raise an exception to abort the operation or skip the member, depending on errorlevel. Note that when extraction is aborted, extractall() may leave the archive partially extracted. It does not attempt to clean up.

Default named filters

The pre-defined, named filters are available as functions, so they can be reused in custom filters:

tarfile.fully_trusted_filter(/, member, path)

Return member unchanged.

This implements the 'fully_trusted' filter.

tarfile.tar_filter(/, member, path)

Implements the 'tar' filter.

Strip leading slashes (/ and os.sep) from filenames.

Refuse to extract files with absolute paths (in case the name is absolute even after stripping slashes, e.g. C:/foo on Windows). This raises AbsolutePathError.

Refuse to extract files whose absolute path (after following symlinks) would end up outside the destination. This raises OutsideDestinationError.

Clear high mode bits (setuid, setgid, sticky) and group/other write bits (S_IWOTH).

Return the modified TarInfo member.

tarfile.data_filter(/, member, path)

Implements the 'data' filter. In addition to what tar_filter does:

Refuse to extract links (hard or soft) that link to absolute paths, or ones that link outside the destination.

This raises AbsoluteLinkError or LinkOutsideDestinationError.

Note that such files are refused even on platforms that do not support symbolic links.

Refuse to extract device files (including pipes). This raises SpecialFileError.

For regular files, including hard links:

Set the owner read and write permissions (S_IWUSR).

Remove the group & other executable permission (S_IXOTH) if the owner doesn’t have it (S_IXUSR).

For other files (directories), set mode to None, so that extraction methods skip applying permission bits.

Set user and group info (uid, gid, uname, gname) to None, so that extraction methods skip setting it.

Return the modified TarInfo member.

Filter errors

When a filter refuses to extract a file, it will raise an appropriate exception, a subclass of FilterError. This will abort the extraction if TarFile.errorlevel is 1 or more. With errorlevel=0 the error will be logged and the member will be skipped, but extraction will continue.

Hints for further verification

Even with filter='data', tarfile is not suited for extracting untrusted files without prior inspection. Among other issues, the pre-defined filters do not prevent denial-of-service attacks. Users should do additional checks.

Here is an incomplete list of things to consider:

Extract to a new temporary directory to prevent e.g. exploiting pre-existing links, and to make it easier to clean up after a failed extraction.

When working with untrusted data, use external (e.g. OS-level) limits on disk, memory and CPU usage.

Check filenames against an allow-list of characters (to filter out control characters, confusables, foreign path separators, etc.).

Check that filenames have expected extensions (discouraging files that execute when you “click on them”, or extension-less files like Windows special device names).

Limit the number of extracted files, total size of extracted data, filename length (including symlink length), and size of individual files.

Check for files that would be shadowed on case-insensitive filesystems.

Also note that:

Tar files may contain multiple versions of the same file. Later ones are expected to overwrite any earlier ones. This feature is crucial to allow updating tape archives, but can be abused maliciously.

tarfile does not protect against issues with “live” data, e.g. an attacker tinkering with the destination (or source) directory while extraction (or archiving) is in progress.

Supporting older Python versions

Extraction filters were added to Python 3.12, and are backported to older versions as security updates. To check whether the feature is available, use e.g. hasattr(tarfile, 'data_filter') rather than checking the Python version.

The following examples show how to support Python versions with and without the feature. Note that setting extraction_filter will affect any subsequent operations.

Fully trusted archive:

my_tarfile.extraction_filter = (lambda member, path: member)
my_tarfile.extractall()

Use the 'data' filter if available, but revert to Python 3.11 behavior ('fully_trusted') if this feature is not available:

my_tarfile.extraction_filter = getattr(tarfile, 'data_filter',
                                       (lambda member, path: member))
my_tarfile.extractall()

Use the 'data' filter; fail if it is not available:

my_tarfile.extractall(filter=tarfile.data_filter)

or:

my_tarfile.extraction_filter = tarfile.data_filter
my_tarfile.extractall()

Use the 'data' filter; warn if it is not available:

if hasattr(tarfile, 'data_filter'):
    my_tarfile.extractall(filter='data')
else:
    # remove this when no longer needed
    warn_the_user('Extracting may be unsafe; consider updating Python')
    my_tarfile.extractall()

Stateful extraction filter example

While tarfile’s extraction methods take a simple filter callable, custom filters may be more complex objects with an internal state. It may be useful to write these as context managers, to be used like this:

with StatefulFilter() as filter_func:
    tar.extractall(path, filter=filter_func)

Such a filter can be written as, for example:

class StatefulFilter:
    def __init__(self):
        self.file_count = 0

    def __enter__(self):
        return self

    def __call__(self, member, path):
        self.file_count += 1
        return member

    def __exit__(self, *exc_info):
        print(f'{self.file_count} files extracted')

Interfaz de línea de comandos

Nuevo en la versión 3.4.

El módulo tarfile provee una interfaz de línea de comandos sencilla para interactuar con archivos tar.

Si quieres crear un nuevo archivo tar, especifica su nombre después de la opción -c y después lista el nombre de archivo(s) que deberían ser incluidos:

$ python -m tarfile -c monty.tar  spam.txt eggs.txt

Proporcionar un directorio también es aceptable:

$ python -m tarfile -c monty.tar life-of-brian_1979/

Si deseas extraer un archivo tar en el directorio actual, utiliza la opción -e:

$ python -m tarfile -e monty.tar

También puedes extraer un archivo tar en un directorio diferente pasando el nombre del directorio como parámetro:

$ python -m tarfile -e monty.tar  other-dir/

Para obtener una lista de archivos dentro de un archivo tar, utiliza la opción -l:

$ python -m tarfile -l monty.tar

Opciones de línea de comandos

-l <tarfile>

--list <tarfile>

Listar archivos en un tar.

-c <tarfile> <source1> ... <sourceN>

--create <tarfile> <source1> ... <sourceN>

Crear archivo tar desde archivos fuente.

-e <tarfile> [<output_dir>]

--extract <tarfile> [<output_dir>]

Extrae el archivo tar en el directorio actual si output_dir no es especificado.

-t <tarfile>

--test <tarfile>

Probar si el archivo tar es valido o no.

-v, --verbose

Output verbose.

--filter <filtername>

Specifies the filter for --extract. See Extraction filters for details. Only string names are accepted (that is, fully_trusted, tar, and data).

Nuevo en la versión 3.9.17.

Ejemplos

Cómo extraer un archivo tar entero al directorio de trabajo actual:

import tarfile
tar = tarfile.open("sample.tar.gz")
tar.extractall()
tar.close()

Cómo extraer un subconjunto de un archivo tar con TarFile.extractall() utilizando una función generadora en lugar de una lista:

import os
import tarfile

def py_files(members):
    for tarinfo in members:
        if os.path.splitext(tarinfo.name)[1] == ".py":
            yield tarinfo

tar = tarfile.open("sample.tar.gz")
tar.extractall(members=py_files(tar))
tar.close()

Cómo crear un archivo tar sin comprimir desde una lista de nombres de archivo:

import tarfile
tar = tarfile.open("sample.tar", "w")
for name in ["foo", "bar", "quux"]:
    tar.add(name)
tar.close()

El mismo ejemplo utilizando la declaración with:

import tarfile
with tarfile.open("sample.tar", "w") as tar:
    for name in ["foo", "bar", "quux"]:
        tar.add(name)

Cómo leer un archivo tar comprimido con gzip y desplegar un poco de información del miembro:

import tarfile
tar = tarfile.open("sample.tar.gz", "r:gz")
for tarinfo in tar:
    print(tarinfo.name, "is", tarinfo.size, "bytes in size and is ", end="")
    if tarinfo.isreg():
        print("a regular file.")
    elif tarinfo.isdir():
        print("a directory.")
    else:
        print("something else.")
tar.close()

Cómo crear un archivo y reiniciar la información del usuario usando el parámetro filter en TarFile.add():

import tarfile
def reset(tarinfo):
    tarinfo.uid = tarinfo.gid = 0
    tarinfo.uname = tarinfo.gname = "root"
    return tarinfo
tar = tarfile.open("sample.tar.gz", "w:gz")
tar.add("foo", filter=reset)
tar.close()

Formatos tar con soporte

Hay tres formatos tar que puede ser creados con el módulo tarfile:

El formato (USTAR_FORMAT) POSIX.1-1988 ustar. Admite nombres de archivos de hasta una longitud de 256 caracteres y nombres de enlace de hasta 100 caracteres. El tamaño máximo de archivo es de 8 GiB. Este es un formato viejo y limitado pero con amplio soporte.

El formato GNU tar (GNU_FORMAT). Admite nombres de archivo largos y nombres de enlace, archivos más grandes que 8 GiB de tamaño y archivos dispersos. Es el estándar de facto en sistemas GNU/Linux. tarfile admite de forma completa las extensiones de GNU tar para nombres largos, el soporte para archivos dispersos es de solo lectura.

El formato pax POSIX.1-2001 (PAX_FORMAT). Es el formato más flexible prácticamente sin límites. Admite nombres de archivo largos y nombres de enlaces, archivos grandes y almacena nombres de ruta de forma portátil. Las implementaciones modernas de tar, incluyendo GNU tar, bsdtar/libarchive y star, son totalmente compatibles con las características extendidas pax; Es posible que algunas bibliotecas antiguas o no mantenidas no lo hagan, pero deberían tratar los archivos pax como si estuvieran en el formato ustar compatible universalmente. Es el formato predeterminado actual para archivos nuevos.

Extiende el formato existente ustar con cabeceras adicionales para información que no puede ser almacenada de otra manera. Hay dos variaciones de encabezados pax: Los encabezados extendidos solo afectan al encabezado del archivo posterior, las encabezados globales son validos para el archivo entero y afectan todos los siguientes archivos. Todos los datos en un encabezado pax son codificados en UTF-8 por razones de portabilidad.

Existen más variantes del formato tar que puede ser leídas, pero no creadas:

El antiguo formato V7. Este es el primer formato tar de Unix Seventh Edition, almacena solo archivos y directorios normales. Los nombres no deben tener más de 100 caracteres, no hay información de nombre de usuario/grupo disponible. Algunos archivos tienen sumas de comprobación de encabezado mal calculadas en el caso de campos con caracteres que no son ASCII.

El formato extendido tar de SunOS. Este formato es una variante del formato POSIX.1-2001 pax, pero no es compatible.

Problemas Unicode

El formato tar fue originalmente concebido para realizar respaldos en unidades de cinta con el objetivo principal de preservar la información del sistema de archivos. Hoy en día los archivos tar son comúnmente utilizados para distribución de archivos e intercambio de archivos sobre redes. Un problema del formato original (el cual es la base de todos los demás formatos) es que no hay concepto de soporte para diferentes codificaciones de caracteres. Por ejemplo, un archivo tar ordinario creado en un sistema UTF-8 no puede ser leído correctamente en un sistema Latin-1 si este contiene caracteres de tipo no ASCII. Los meta-datos textuales (como nombres de archivos, nombres de enlace, nombres de usuario/grupo) aparecerán dañados. Desafortunadamente, no hay manera de detectar de forma automática la codificación de un archivo. El formato pax fue diseñado para resolver este problema. Almacena los metadatos no ASCII usando una codificación de caracteres universal UTF-8.

Los detalles de la conversión de caracteres en el módulo tarfile son controlados por los argumentos de palabra clave encoding y errors de la clase TarFile.

encoding define la codificación de caracteres a utilizar para los metadatos del archivo. El valor predeterminado es sys.getfilesystemencoding() o 'ascii' como una alternativa. Dependiendo de si el archivo se lee o escribe, los metadatos deben decodificarse o codificarse. Si el encoding no se configura correctamente, esta conversión puede fallar.

El argumento errors define como van a ser tratados los caracteres que no pueden ser transformados. Los valores admitidos están listados en la sección Manejadores de errores. El esquema predeterminado es 'surrogateescape' el cual Python también utiliza para sus llamadas al sistema de archivos. Consulta Nombres de archivos, argumentos de la línea de comandos y variables de entorno.

Para archivos PAX_FORMAT (el formato default), el encoding generalmente no es necesario porque todos los meta-datos son almacenados utilizando UTF-8, el encoding solo es utilizado en aquellos casos cuando las cabeceras binarias PAX son decodificadas o cuando se almacenan cadenas de texto con caracteres sustitutos.

Formatos de archivo

Los módulos descritos en este capítulo analizan varios formatos de archivo que no son lenguajes de marcado y no están relacionados con el correo electrónico.

csv — Lectura y escritura de archivos CSV

Contenidos del módulo

Dialectos y parámetros de formato

Objetos Reader

Objetos Writer

Ejemplos

configparser — Parser para archivos de configuración

Inicio Rápido

Tipos de Datos Soportados

Valores de contingencia

Estructura Soportada para el Archivo INI

Interpolación de valores

Acceso por Protocolo de Mapeo

Personalizando el Comportamiento del Parser

Ejemplos de la API heredada

Objetos ConfigParser

Objetos RawConfigParser

Excepciones

netrc — procesado del fichero netrc

Objetos netrc

plistlib — Genera y analiza archivos .plist de Apple

Ejemplos

csv — Lectura y escritura de archivos CSV

Código fuente: Lib/csv.py [https://github.com/python/cpython/tree/3.9/Lib/csv.py]

El tan llamado CSV (Valores Separados por Comas) es el formato más común de importación y exportación de hojas de cálculo y bases de datos. El formato CSV se utilizó durante muchos años antes de intentar describir el formato de manera estandarizada en RFC 4180 [https://tools.ietf.org/html/rfc4180.html]. La falta de un estándar bien definido significa que a veces existen pequeñas diferencias en la información producida y consumida por diferentes aplicaciones. Estas diferencias pueden ser molestas al momento de procesar archivos CSV desde múltiples fuentes. Aún así, aunque los delimitadores y separadores varíen, el formato general es lo suficientemente similar como para que sea posible un sólo módulo que puede manipular tal información eficientemente, escondiendo los detalles de lectura y escritura de datos del programador.

El módulo csv implementa clases para leer y escribir datos tabulares en formato CSV. Permite a los programadores decir, «escribe estos datos en el formato preferido por Excel», o «lee datos de este archivo que fue generado por Excel», sin conocer los detalles precisos del formato CSV usado por Excel. Los programadores también pueden describir los formatos CSV entendidos por otras aplicaciones o definir sus propios formatos CSV para fines particulares.

Los objetos reader y writer del módulo csv leen y escriben secuencias. Los programadores también pueden leer y escribir datos en forma de diccionario usando las clases DictReader y DictWriter.

Ver también

PEP 305 [https://www.python.org/dev/peps/pep-0305] - API de archivo CSV

La Propuesta de Mejora de Python (PEP, por sus siglas en inglés) que propone esta adición a Python.

Contenidos del módulo

El módulo csv define las siguientes funciones:

csv.reader(csvfile, dialect='excel', **fmtparams)

Retorna un objeto reader que iterará sobre las líneas del csvfile proporcionado. csvfile puede ser cualquier objeto que soporte el protocolo iterator y retorna una cadena de caracteres siempre que su método __next__() sea llamado — tanto objetos de archivo como objetos de lista son adecuados. Si csvfile es un objeto de archivo, debería ser abierto con newline=''. 1 Se puede proporcionar un parámetro opcional dialect, el cual se utiliza para definir un conjunto de parámetros específicos para un dialecto de CSV particular. Puede ser una instancia de una subclase de la clase Dialect o una de las cadenas retornadas por la función list_dialects(). Los otros argumentos nombrados opcionales fmtparams pueden ser dados para sustituir parámetros de formato individuales del dialecto actual. Para detalles completos sobre el dialecto y los parámetros de formato, vea la sección Dialectos y parámetros de formato.

Cada fila leída del archivo csv es retornada como una lista de cadenas. No se realiza conversión automática de tipo de datos a menos que la opción de formato QUOTE_NONNUMERIC esté especificada (en ese caso los campos no citados son transformados en flotantes).

Un pequeño ejemplo de uso:

>>> import csv
>>> with open('eggs.csv', newline='') as csvfile:
...     spamreader = csv.reader(csvfile, delimiter=' ', quotechar='|')
...     for row in spamreader:
...         print(', '.join(row))
Spam, Spam, Spam, Spam, Spam, Baked Beans
Spam, Lovely Spam, Wonderful Spam

csv.writer(csvfile, dialect='excel', **fmtparams)

Return a writer object responsible for converting the user’s data into delimited strings on the given file-like object. csvfile can be any object with a write() method. If csvfile is a file object, it should be opened with newline='' 1. An optional dialect parameter can be given which is used to define a set of parameters specific to a particular CSV dialect. It may be an instance of a subclass of the Dialect class or one of the strings returned by the list_dialects() function. The other optional fmtparams keyword arguments can be given to override individual formatting parameters in the current dialect. For full details about dialects and formatting parameters, see the Dialectos y parámetros de formato section. To make it as easy as possible to interface with modules which implement the DB API, the value None is written as the empty string. While this isn’t a reversible transformation, it makes it easier to dump SQL NULL data values to CSV files without preprocessing the data returned from a cursor.fetch* call. All other non-string data are stringified with str() before being written.

Un pequeño ejemplo de uso:

import csv
with open('eggs.csv', 'w', newline='') as csvfile:
    spamwriter = csv.writer(csvfile, delimiter=' ',
                            quotechar='|', quoting=csv.QUOTE_MINIMAL)
    spamwriter.writerow(['Spam'] * 5 + ['Baked Beans'])
    spamwriter.writerow(['Spam', 'Lovely Spam', 'Wonderful Spam'])

csv.register_dialect(name[, dialect[, **fmtparams]])

Associate dialect with name. name must be a string. The dialect can be specified either by passing a sub-class of Dialect, or by fmtparams keyword arguments, or both, with keyword arguments overriding parameters of the dialect. For full details about dialects and formatting parameters, see section Dialectos y parámetros de formato.

csv.unregister_dialect(name)

Borra el dialecto asociado a name del registro de dialectos. Un Error es lanzado si name no está registrado como el nombre de un dialecto.

csv.get_dialect(name)

Retorna el dialecto asociado a name. Un Error es lanzado si name no está registrado como el nombre de un dialecto. Esta función retorna un objeto Dialect inmutable.

csv.list_dialects()

Retorna los nombres de todos los dialectos registrados.

csv.field_size_limit([new_limit])

Retorna el tamaño máximo de campo permitido actualmente por el intérprete. Si new_limit es dado, este se convierte en el nuevo límite.

El módulo csv define las siguientes clases:

class csv.DictReader(f, fieldnames=None, restkey=None, restval=None, dialect='excel', *args, **kwds)

Crea un objeto que opera como un reader común, pero mapea la información en cada fila a un dict cuyas claves son provistas en el parámetro opcional fieldnames.

El parámetro fieldnames es una sequence. Si se omite fieldnames, los valores en la primera fila del archivo f serán usados como nombres de campo. Independientemente de como se determinen los nombres de campo, el diccionario preserva su orden original.

Si una fila tiene más campos que nombres de campo, los datos restantes son colocados en una lista y guardados con el nombre de campo especificado por restkey (que por defecto es None). Si una fila que no esta en blanco tiene menos campos que nombres de campo, los valores faltantes son rellenados con el valor de restval (que por defecto es None).

Todos los demás argumentos de palabra clave u opcionales son pasados a la instancia subyacente de reader.

Distinto en la versión 3.6: Las filas retornadas son ahora de tipo OrderedDict.

Distinto en la versión 3.8: Las filas retornadas son ahora de tipo dict.

Un pequeño ejemplo de uso:

>>> import csv
>>> with open('names.csv', newline='') as csvfile:
...     reader = csv.DictReader(csvfile)
...     for row in reader:
...         print(row['first_name'], row['last_name'])
...
Eric Idle
John Cleese

>>> print(row)
{'first_name': 'John', 'last_name': 'Cleese'}

class csv.DictWriter(f, fieldnames, restval='', extrasaction='raise', dialect='excel', *args, **kwds)

Crea un objeto que opera como un writer común, pero mapea diccionarios a filas de salida. El parámetro fieldnames es una secuencia de claves que identifican el orden en el cual los valores en el diccionario pasados al método writerow() son escritos en el archivo f. El parámetro opcional restval especifica el valor a ser escrito si al diccionario le falta una clave en fieldnames. Si el diccionario pasado al método writerow() contiene una clave no encontrada en fieldnames, el parámetro opcional extrasaction indica que acción ejecutar. Si esta configurado en 'raise', el valor por defecto, es lanzado un ValueError. Si esta configurado con 'ignore', los valores extra en el diccionario son ignorados. Cualquier otro argumento de palabra clave u opcional es pasado a la instancia subyacente de reader.

Nótese que a diferencia de la clase DictReader, el parámetro fieldnames de la clase DictWriter no es opcional.

Un pequeño ejemplo de uso:

import csv

with open('names.csv', 'w', newline='') as csvfile:
    fieldnames = ['first_name', 'last_name']
    writer = csv.DictWriter(csvfile, fieldnames=fieldnames)

    writer.writeheader()
    writer.writerow({'first_name': 'Baked', 'last_name': 'Beans'})
    writer.writerow({'first_name': 'Lovely', 'last_name': 'Spam'})
    writer.writerow({'first_name': 'Wonderful', 'last_name': 'Spam'})

class csv.Dialect

The Dialect class is a container class whose attributes contain information for how to handle doublequotes, whitespace, delimiters, etc. Due to the lack of a strict CSV specification, different applications produce subtly different CSV data. Dialect instances define how reader and writer instances behave.

All available Dialect names are returned by list_dialects(), and they can be registered with specific reader and writer classes through their initializer (__init__) functions like this:

import csv

with open('students.csv', 'w', newline='') as csvfile:
    writer = csv.writer(csvfile, dialect='unix')
                                 ^^^^^^^^^^^^^^

class csv.excel

La clase excel define las propiedades usuales de un archivo CSV generado por Excel. Esta registrada con el nombre de dialecto 'excel'.

class csv.excel_tab

La clase excel_tab define las propiedades usuales de un archivo delimitado por tabulaciones generado por Excel. Esta registrada con el nombre de dialecto 'excel-tab'.

class csv.unix_dialect

La clase unix_dialect define las propiedades usuales de un archivo CSV generado en sistemas UNIX, es decir, usando '\n' como terminador de línea y citando todos los campos. Esta registrada con el nombre de dialecto 'unix'.

Nuevo en la versión 3.2.

class csv.Sniffer

La clase Sniffer es usada para deducir el formato de un archivo CSV.

La clase Sniffer provee 2 métodos:

sniff(sample, delimiters=None)

Analiza la muestra dada y retorna una subclase Dialect reflejando los parámetros encontrados. Si el parámetro opcional delimiters es dado, este será interpretado como una cadena que contiene posibles caracteres delimitadores válidos.

has_header(sample)

Analiza el texto de muestra (presumiblemente en formato CSV) y retorna True si la primera fila parece ser una serie de encabezados de columna.

Un ejemplo para el uso de Sniffer:

with open('example.csv', newline='') as csvfile:
    dialect = csv.Sniffer().sniff(csvfile.read(1024))
    csvfile.seek(0)
    reader = csv.reader(csvfile, dialect)
    # ... process CSV file contents here ...

El módulo csv define las siguientes constantes:

csv.QUOTE_ALL

Ordena a los objetos writer citar todos los campos.

csv.QUOTE_MINIMAL

Ordena a los objetos writer citar solo aquellos campos que contengan caracteres especiales como por ejemplo delimiter, *quotechar o cualquiera de los caracteres en lineterminator.

csv.QUOTE_NONNUMERIC

Ordena a los objetos writer citar todos los campos no numéricos.

Ordena al reader a convertir todos los campos no citados al tipo float.

csv.QUOTE_NONE

Ordena a los objetos writer nunca citar campos. Cuando el delimiter actual aparece en los datos de salida es precedido por el carácter escapechar actual. Si escapechar no esta definido, el writer lanzará Error si cualquier carácter que requiere escaparse es encontrado.

Ordena a reader no ejecutar un procesamiento especial de caracteres citados.

El módulo csv define la siguiente excepción:

exception csv.Error

Lanzada por cualquiera de las funciones cuando se detecta un error.

Dialectos y parámetros de formato

Para facilitar la especificación del formato de registros de entrada y salida, los parámetros específicos de formateo son agrupados en dialectos. Un dialecto es una subclase de la clase Dialect con un conjunto de métodos específicos y un solo método validate(). Cuando se crean objetos reader o writer, el programador puede especificar una cadena de caracteres o una subclase de la clase Dialect como el parámetro de dialecto. Además de, o en vez de, el parámetro dialect, el programador también puede especificar parámetros de formateo individuales, con los mismos nombres que los atributos definidos debajo para la clase Dialect.

Los dialectos soportan los siguientes atributos:

Dialect.delimiter

Una cadena de un solo carácter usada para separar campos. Por defecto es ','.

Dialect.doublequote

Controla como las instancias de quotechar que aparecen dentro de un campo deben estar citadas. Cuando es True, el carácter es duplicado. Cuando es False, el escapechar es usado como un prefijo el quotechar. Por defecto es True.

En la salida, si el doublequote es False y el escapechar no está configurado, un Error es lanzado si se encuentra un quotechar en algún campo.

Dialect.escapechar

Una cadena de un solo carácter usada por el writer para escapar al delimiter si quoting está configurado como QUOTE_NONE y al quotechar si doublequote es False. En la lectura, el escapechar elimina cualquier significado especial del siguiente carácter. Por defecto es None, lo que deshabilita el escape.

Dialect.lineterminator

La cadena de caracteres usada para terminar las líneas producidas por writer. Por defecto es '\r\n'.

Nota

El reader esta codificado para reconocer tanto '\r' o '\n' como final de línea, e ignora lineterminator. Este comportamiento puede cambiar en el futuro.

Dialect.quotechar

Una cadena de un solo carácter usada para citar campos que contienen caracteres especiales, como lo son delimiter o quotechar, o que contienen caracteres de nueva línea. Por defecto es '"'.

Dialect.quoting

Controla cuando las comillas deberían ser generadas por el writer y ser reconocidas por el reader. Puede tomar cualquiera de las constantes QUOTE_* (ver sección Contenidos del módulo) y por defecto es QUOTE_MINIMAL.

Dialect.skipinitialspace

Cuando es True, el espacio en blanco que sigue después del delimiter es ignorado. Por defecto es False.

Dialect.strict

Cuando es True, lanza una excepción Error sobre una mala entrada CSV. Por defecto es False.

Objetos Reader

Los objetos reader (instancias de DictReader y objetos retornados por la función reader()) contienen los siguientes métodos públicos:

csvreader.__next__()

Return the next row of the reader’s iterable object as a list (if the object was returned from reader()) or a dict (if it is a DictReader instance), parsed according to the current Dialect. Usually you should call this as next(reader).

Los objetos reader contienen los siguientes atributos públicos:

csvreader.dialect

Una descripción de sólo lectura del dialecto en uso por el intérprete.

csvreader.line_num

El número de líneas leídas del iterador fuente. Esto no es lo mismo que el número de registros retornado, ya que los registros pueden abarcar múltiples líneas.

Los objetos DictReader tienen los siguientes atributos públicos:

csvreader.fieldnames

Si no son pasados como parámetros cuando se crea el objeto, este atributo es inicializado en el primer acceso o cuando es leído el primer registro del archivo.

Objetos Writer

Los objetos Writer (instancias de DictWriter y objetos retornados por la función writer()) contienen los siguientes métodos públicos. Una row debe ser un iterable de cadenas de caracteres o números para objetos Writer y un diccionario que mapea nombres de campo a cadenas de caracteres o números (pasándolos primero a través de str()) para objetos DictWriter. Note que los números complejos se escriben rodeados de paréntesis. Esto puede causar algunos problemas para otros programas que leen archivos CSV (asumiendo que soportan números complejos).

csvwriter.writerow(row)

Write the row parameter to the writer’s file object, formatted according to the current Dialect. Return the return value of the call to the write method of the underlying file object.

Distinto en la versión 3.5: Agregado soporte para iterables.

csvwriter.writerows(rows)

Escribe todos los elementos en rows (un iterable de objetos row como se describe anteriormente) al objeto de archivo del writer, formateados según el dialecto actual.

Los objetos writer contienen los siguientes atributos públicos:

csvwriter.dialect

Una descripción de solo lectura del dialecto en uso por el writer.

Los objetos DictWriter contienen los siguientes métodos públicos:

DictWriter.writeheader()

Escribe una fila con los nombres de los campos (como se especifica en el constructor) al objeto de archivo del writer, formateada según el dialecto actual. Retorna el valor de retorno de la llamada a csvwriter.writerow() usada internamente.

Nuevo en la versión 3.2.

Distinto en la versión 3.8: writeheader() ahora también retorna el valor retornado por el método csvwriter.writerow() que usa internamente.

Ejemplos

El ejemplo más simple de lectura de un archivo CSV:

import csv
with open('some.csv', newline='') as f:
    reader = csv.reader(f)
    for row in reader:
        print(row)

Lectura de un archivo con un formato alternativo:

import csv
with open('passwd', newline='') as f:
    reader = csv.reader(f, delimiter=':', quoting=csv.QUOTE_NONE)
    for row in reader:
        print(row)

El correspondiente ejemplo de escritura más simple es:

import csv
with open('some.csv', 'w', newline='') as f:
    writer = csv.writer(f)
    writer.writerows(someiterable)

Ya que open() es usado para abrir un archivo CSV para lectura, el archivo será decodificado por defecto en unicode usando la codificación por defecto del sistema (ver locale.getpreferredencoding()). Para decodificar un archivo usando una codificación diferente, usa el argumento encoding de open:

import csv
with open('some.csv', newline='', encoding='utf-8') as f:
    reader = csv.reader(f)
    for row in reader:
        print(row)

Lo mismo aplica a escribir en algo diferente a la codificación por defecto del sistema: especifique el argumento de codificación cuando abra el archivo de salida.

Registrando un nuevo dialecto:

import csv
csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE)
with open('passwd', newline='') as f:
    reader = csv.reader(f, 'unixpwd')

Un uso ligeramente más avanzado del reader — captura y reporte de errores:

import csv, sys
filename = 'some.csv'
with open(filename, newline='') as f:
    reader = csv.reader(f)
    try:
        for row in reader:
            print(row)
    except csv.Error as e:
        sys.exit('file {}, line {}: {}'.format(filename, reader.line_num, e))

Y a pesar de que el módulo no soporta el análisis de cadenas de caracteres directamente, puede ser realizado fácilmente:

import csv
for row in csv.reader(['one,two,three']):
    print(row)

Notas al pie

1(1,2)

Si newline='' no es especificado, las nuevas líneas dentro de los campos citados no serán interpretadas correctamente y, en plataformas que utilicen finales de línea \r\n en la escritura, se añadirá un \r extra. Siempre debería ser seguro especificar newline='', ya que el módulo csv realiza su propio manejo de nuevas líneas (universal).

configparser — Parser para archivos de configuración

Código fuente: Lib/configparser.py [https://github.com/python/cpython/tree/3.9/Lib/configparser.py]

Este módulo provee la clase ConfigParser, la cual implementa un lenguaje básico de configuración que proporciona una estructura similar a la encontrada en los archivos INI de Microsoft Windows. Puedes utilizarla para escribir programas Python que los usuarios finales puedan personalizar con facilidad.

Nota

Esta biblioteca no interpreta o escribe los prefijos valor-tipo usados en la versión extendida de la sintaxis INI, utilizada en el registro de Windows.

Ver también

Módulo shlex

Soporta la creación de un mini-lenguaje parecido a shell de Unix, que puede utilizarse como formato alternativo para archivos de configuración de aplicaciones.

Módulo json

El módulo json implementa un subconjunto de la sintaxis de JavaScript, que también puede utilizarse para este propósito.

Inicio Rápido

Tomemos un archivo de configuración muy básico, el cual luce así:

[DEFAULT]
ServerAliveInterval = 45
Compression = yes
CompressionLevel = 9
ForwardX11 = yes

[bitbucket.org]
User = hg

[topsecret.server.com]
Port = 50022
ForwardX11 = no

La estructura de los archivos INI es descrita en la siguiente sección. En esencia, el archivo consiste de secciones, cada una de las cuales contiene claves con valores. Las clases configparser pueden leer y escribir dichos archivos. Comencemos creando el anterior archivo de configuración de forma programática.

>>> import configparser
>>> config = configparser.ConfigParser()
>>> config['DEFAULT'] = {'ServerAliveInterval': '45',
...                      'Compression': 'yes',
...                      'CompressionLevel': '9'}
>>> config['bitbucket.org'] = {}
>>> config['bitbucket.org']['User'] = 'hg'
>>> config['topsecret.server.com'] = {}
>>> topsecret = config['topsecret.server.com']
>>> topsecret['Port'] = '50022'     # mutates the parser
>>> topsecret['ForwardX11'] = 'no'  # same here
>>> config['DEFAULT']['ForwardX11'] = 'yes'
>>> with open('example.ini', 'w') as configfile:
...   config.write(configfile)
...

Como puedes ver, podemos tratar al config parser como a un diccionario. Existen diferencias, descritas posteriormente, pero su comportamiento es muy parecido al que esperarías de un diccionario.

Ahora que hemos creado y guardado el archivo de configuración, vamos a releerlo y analizar los datos que contiene.

>>> config = configparser.ConfigParser()
>>> config.sections()
[]
>>> config.read('example.ini')
['example.ini']
>>> config.sections()
['bitbucket.org', 'topsecret.server.com']
>>> 'bitbucket.org' in config
True
>>> 'bytebong.com' in config
False
>>> config['bitbucket.org']['User']
'hg'
>>> config['DEFAULT']['Compression']
'yes'
>>> topsecret = config['topsecret.server.com']
>>> topsecret['ForwardX11']
'no'
>>> topsecret['Port']
'50022'
>>> for key in config['bitbucket.org']:
...     print(key)
user
compressionlevel
serveraliveinterval
compression
forwardx11
>>> config['bitbucket.org']['ForwardX11']
'yes'

Como podemos apreciar, la API es muy clara. La única “porción de magia” está en la sección DEFAULT, la cual proporciona los valores por defecto para todas las demás secciones 1. Observe también que las claves de las secciones son insensibles a mayúsculas y minúsculas, pero se almacenan en minúscula 1.

Tipos de Datos Soportados

Los config parsers no especulan respecto a los tipos de datos de los valores en los archivos de configuración, siempre los almacenan internamente como cadenas de caracteres. Esto significa que si necesitas otros tipos de datos, deberás hacer la conversión por ti mismo:

>>> int(topsecret['Port'])
50022
>>> float(topsecret['CompressionLevel'])
9.0

Dado que esta tarea es muy común, los config parsers proporcionan una amplia variedad de útiles métodos de lectura (getter) que manejan enteros, números de punto flotante y booleanos. Este último es el más interesante, porque puede no ser correcto pasar simplemente el valor a bool(), ya que bool('False') resultará en True. Por esta razón los config parsers proporcionan también el método getboolean(). Este método es insensible a mayúsculas y minúsculas, y reconoce como valores booleanos a los valores 'yes'/'no', 'on'/'off', 'true'/'false' and '1'/'0' 1. Por ejemplo:

>>> topsecret.getboolean('ForwardX11')
False
>>> config['bitbucket.org'].getboolean('ForwardX11')
True
>>> config.getboolean('bitbucket.org', 'Compression')
True

Además de getboolean(), los config parsers también proporcionan los métodos equivalentes getint() y getfloat(). Puedes registrar tus propios conversores, y personalizar los que se proporcionan. 1

Valores de contingencia

Similar a un diccionario, puedes utilizar el método get() de una sección para especificar valores de contingencia (fallback values):

>>> topsecret.get('Port')
'50022'
>>> topsecret.get('CompressionLevel')
'9'
>>> topsecret.get('Cipher')
>>> topsecret.get('Cipher', '3des-cbc')
'3des-cbc'

Por favor, fíjate que los valores por defecto tienen prioridad sobre los valores de contingencia (fallback). Así, en nuestro ejemplo, la clave 'CompressionLevel' sólo fue especificada en la sección 'DEFAULT'. Si tratamos de obtener su valor de la sección 'topsecret.server.com', obtendremos siempre el valor por defecto, incluso si especificamos un valor de contingencia:

>>> topsecret.get('CompressionLevel', '3')
'9'

Otra cuestión que hay que tener en cuenta, es que el método a nivel analizador (parser) get() proporciona una interfaz personalizada, más compleja, que se mantiene por compatibilidad con versiones anteriores. Cuando se utiliza este método, se puede proporcionar un valor de contingencia mediante el argumento de sólo-palabra clave (keyword-only) fallback:

>>> config.get('bitbucket.org', 'monster',
...            fallback='No such things as monsters')
'No such things as monsters'

El mismo argumento fallback puede utilizarse con los métodos getint(), getfloat() y getboolean(), por ejemplo:

>>> 'BatchMode' in topsecret
False
>>> topsecret.getboolean('BatchMode', fallback=True)
True
>>> config['DEFAULT']['BatchMode'] = 'no'
>>> topsecret.getboolean('BatchMode', fallback=True)
False

Estructura Soportada para el Archivo INI

A configuration file consists of sections, each led by a [section] header, followed by key/value entries separated by a specific string (= or : by default 1). By default, section names are case sensitive but keys are not 1. Leading and trailing whitespace is removed from keys and values. Values can be omitted if the parser is configured to allow it 1, in which case the key/value delimiter may also be left out. Values can also span multiple lines, as long as they are indented deeper than the first line of the value. Depending on the parser’s mode, blank lines may be treated as parts of multiline values or ignored.

By default, a valid section name can be any string that does not contain “\n” or “]”. To change this, see ConfigParser.SECTCRE.

Los archivos de configuración pueden incluir comentarios, con caracteres específicos como prefijos (# y ; por defecto 1). Los comentarios pueden ocupar su propia línea, posiblemente indentada. 1

Por ejemplo:

[Simple Values]
key=value
spaces in keys=allowed
spaces in values=allowed as well
spaces around the delimiter = obviously
you can also use : to delimit keys from values

[All Values Are Strings]
values like this: 1000000
or this: 3.14159265359
are they treated as numbers? : no
integers, floats and booleans are held as: strings
can use the API to get converted values directly: true

[Multiline Values]
chorus: I'm a lumberjack, and I'm okay
    I sleep all night and I work all day

[No Values]
key_without_value
empty string value here =

[You can use comments]
# like this
; or this

# By default only in an empty line.
# Inline comments can be harmful because they prevent users
# from using the delimiting characters as parts of values.
# That being said, this can be customized.

    [Sections Can Be Indented]
        can_values_be_as_well = True
        does_that_mean_anything_special = False
        purpose = formatting for readability
        multiline_values = are
            handled just fine as
            long as they are indented
            deeper than the first line
            of a value
        # Did I mention we can indent comments, too?

Interpolación de valores

En el nivel superior de su funcionalidad central, ConfigParser soporta la interpolación. Esto significa que los valores pueden ser preprocesados, antes de ser retornados por los llamados a get().

class configparser.BasicInterpolation

Es la implementación por defecto que utiliza ConfigParser. Permite valores que contengan cadenas de formato, que hacen referencia a otros valores en la misma sección o a valores presentes en la sección especial default 1. Valores por defecto adicionales pueden ser proporcionados en la inicialización.

Por ejemplo:

[Paths]
home_dir: /Users
my_dir: %(home_dir)s/lumberjack
my_pictures: %(my_dir)s/Pictures

[Escape]
# use a %% to escape the % sign (% is the only character that needs to be escaped):
gain: 80%%

En el ejemplo anterior, ConfigParser con la interpolación establecida a BasicInterpolation() puede resolver %(home_dir)s al valor home_dir (/Users en este caso). En efecto, %(my_dir)s podría resolverse como /Users/lumberjack. Todas las interpolaciones son realizadas bajo demanda, de modo que las claves utilizadas en la cadena de referencias no requieren un orden específico en el archivo de configuración.

Con interpolation establecida al valor None, el parser retornará simplemente %(my_dir)s/Pictures como el valor de my_pictures y %(home_dir)s/lumberjack como el valor de my_dir.

class configparser.ExtendedInterpolation

Es un gestor alternativo para la interpolación, que implementa una sintaxis más avanzada; es utilizado, por ejemplo, en zc.buildout. La interpolación es extendida al utilizar ${section:option}, a fin de especificar un valor que proviene de una sección externa. La interpolación puede cubrir múltiples niveles. Por conveniencia, si la parte section: es omitida, la interpolación utilizará la sección actual (y posiblemente los valores por defecto establecidos en la sección especial).

Por ejemplo, la configuración indicada anteriormente, con interpolación básica, luciría de la siguiente manera utilizando interpolación extendida:

[Paths]
home_dir: /Users
my_dir: ${home_dir}/lumberjack
my_pictures: ${my_dir}/Pictures

[Escape]
# use a $$ to escape the $ sign ($ is the only character that needs to be escaped):
cost: $$80

También pueden buscarse valores en otras secciones:

[Common]
home_dir: /Users
library_dir: /Library
system_dir: /System
macports_dir: /opt/local

[Frameworks]
Python: 3.2
path: ${Common:system_dir}/Library/Frameworks/

[Arthur]
nickname: Two Sheds
last_name: Jackson
my_dir: ${Common:home_dir}/twosheds
my_pictures: ${my_dir}/Pictures
python_dir: ${Frameworks:path}/Python/Versions/${Frameworks:Python}

Acceso por Protocolo de Mapeo

Nuevo en la versión 3.2.

El acceso por protocolo de mapeo es un nombre genérico asignado a la funcionalidad que permite el uso de objetos personalizados como si fuesen diccionarios. En el caso de configparser, la implementación de la interfaz de mapeo utiliza la notación parser['section']['option'].

En particular, parser['section'] retorna un proxy para los datos de la sección en el parser. Esto significa que los valores no son copiados, sino que son tomados del parser original sobre la marcha.

Los objetos de configparser se comportan de forma tan similar a un diccionario como se puede. La interfaz de mapeo es completa y se ciñe a la MutableMapping ABC. Sin embargo, existen unas pequeñas diferencias que deben tomarse en cuenta:

Por defecto, todas las claves de las secciones se pueden acceder de una forma insensible a mayúsculas y minúsculas 1. Ej. for option in parser["section"] entrega solamente nombres de claves de opción que han pasado por optionxform. Esto significa, claves en minúscula por defecto. A la vez, para una sección que contiene la clave 'a', ambas expresiones retornan True:

"a" in parser["section"]
"A" in parser["section"]

Todas las secciones también incluyen valores DEFAULTSECT, lo que significa que .clear() en una sección puede no significar que esta quede vacía de forma visible. Ello debido a que los valores por defecto no pueden ser borrados de la sección (ya que técnicamente no están allí). Si fueron redefinidas en la sección, su borrado ocasiona que los valores por defecto sean visibles de nuevo. Cualquier intento de borrar un valor por defecto ocasiona una excepción KeyError.

DEFAULTSECT no puede ser eliminado del parser:

el intento de borrarlo lanza una excepción ValueError,

parser.clear() lo deja intacto,

parser.popitem() nunca lo retorna.

parser.get(section, option, **kwargs) - el segundo argumento no es un valor de contingencia. Observe, sin embargo, que los métodos get() a nivel de sección son compatibles tanto con el protocolo de mapeo como con la API clásica de configparser.

parser.items() es compatible con el protocolo de mapeo (retorna una lista de pares section_name, section_proxy que estén incluidos en DEFAULTSECT). Sin embargo, este método también puede ser invocado con los argumentos: parser.items(section, raw, vars). Esta última llamada retorna una lista de pares option, value para una section específica, con todas las interpolaciones expandidas (a menos que se especifique raw=True).

El protocolo de mapeo se implementa en el nivel superior de la actual API heredada, de modo que esas subclases que sobre-escriben la interfaz original aún deberían hacer funcionar el mapeo como se esperaría.

Personalizando el Comportamiento del Parser

Existen casi tantas variantes del formato INI como aplicaciones que lo usen. configparser llega muy lejos al proporcionar soporte al mayor conjunto sensible de estilos de INI disponibles. La funcionalidad predeterminada es impuesta principalmente por antecedentes históricos y es muy probable que quieras personalizar algunas de las funcionalidades.

La forma más común para modificar cómo funciona un config parser específico consiste en el uso de las opciones de __init__():

defaults, valor por defecto: None

Esta opción acepta un diccionario de pares clave-valor, que debe ser colocado inicialmente en la sección DEFAULT. De este modo se obtiene una manera elegante de apoyar los archivos de configuración concisos, que no especifican valores que sean los mismos documentados por defecto.

Consejo: si quieres especificar valores por defecto para una sección específica, usa read_dict() antes de leer el archivo real.

dict_type, valor por defecto: dict

Esta opción tiene un gran impacto en cómo funcionará el protocolo de mapeo, y cómo lucirán los archivos de configuración a escribir. Con el diccionario estándar, cada sección se almacena en el orden en que se añadieron al parser. Lo mismo ocurre con las opciones dentro de las secciones.

Un tipo alternativo de diccionario puede ser utilizado, por ejemplo, para ordenar las secciones y opciones en un modo a posteriori (write-back).

Por favor, tome en cuenta que: existen formas de agregar un par clave-valor en una sola operación. Cuando se utiliza un diccionario común en tales operaciones, el orden de las claves será el empleado en la creación. Por ejemplo:

>>> parser = configparser.ConfigParser()
>>> parser.read_dict({'section1': {'key1': 'value1',
...                                'key2': 'value2',
...                                'key3': 'value3'},
...                   'section2': {'keyA': 'valueA',
...                                'keyB': 'valueB',
...                                'keyC': 'valueC'},
...                   'section3': {'foo': 'x',
...                                'bar': 'y',
...                                'baz': 'z'}
... })
>>> parser.sections()
['section1', 'section2', 'section3']
>>> [option for option in parser['section3']]
['foo', 'bar', 'baz']

allow_no_value, valor por defecto: False

Se sabe que algunos archivos de configuración incluyen elementos sin indicar un valor, aunque cumplan con la sintaxis soportada por configparser en todo lo demás. El parámetro allow_no_value le indica al constructor que tales valores deben ser aceptados:

>>> import configparser

>>> sample_config = """
... [mysqld]
...   user = mysql
...   pid-file = /var/run/mysqld/mysqld.pid
...   skip-external-locking
...   old_passwords = 1
...   skip-bdb
...   # we don't need ACID today
...   skip-innodb
... """
>>> config = configparser.ConfigParser(allow_no_value=True)
>>> config.read_string(sample_config)

>>> # Settings with values are treated as before:
>>> config["mysqld"]["user"]
'mysql'

>>> # Settings without values provide None:
>>> config["mysqld"]["skip-bdb"]

>>> # Settings which aren't specified still raise an error:
>>> config["mysqld"]["does-not-exist"]
Traceback (most recent call last):
  ...
KeyError: 'does-not-exist'

delimiters, valor por defecto: ('=', ':')

Los delimiters son cadenas de caracteres que separan las claves de los valores dentro de una sección. La primera ocurrencia de una cadena de separación en una línea se considera como un separador. Esto significa que los valores pueden contener separadores, no así las claves.

Vea también el argumento space_around_delimiters de ConfigParser.write().

comment_prefixes, valor por defecto: ('#', ';')

inline_comment_prefixes, valor por defecto: None

Los prefijos de comentario son cadenas de caracteres que indican el inicio de un comentario válido dentro de un archivo de configuración. Los comment_prefixes son utilizados solamente en lo que serían líneas en blanco (opcionalmente indentadas), mientras que inline_comment_prefixes pueden ser utilizados después de cada valor válido (ej. nombres de sección, opciones y también líneas en blanco). De forma predeterminada, los comentarios en la misma línea están deshabilitados, y tanto '#' como ';' se utilizan como prefijos para comentarios que ocupan toda la línea.

Distinto en la versión 3.2: En versiones previas de configparser el comportamiento correspondía a comment_prefixes=('#',';') e inline_comment_prefixes=(';',).

Por favor, observe que los config parsers no soportan el escapado de los prefijos de comentarios, de modo que la utilización de los inline_comment_prefixes puede impedir que los usuarios especifiquen valores de opciones que incluyan caracteres empleados como prefijos de comentarios. Ante la duda, evite especificar los inline_comment_prefixes. En cualquier circunstancia, la única forma de almacenar caracteres prefijos de comentario al inicio de una línea, en valores multilínea, es mediante la interpolación del prefijo, por ejemplo:

>>> from configparser import ConfigParser, ExtendedInterpolation
>>> parser = ConfigParser(interpolation=ExtendedInterpolation())
>>> # the default BasicInterpolation could be used as well
>>> parser.read_string("""
... [DEFAULT]
... hash = #
...
... [hashes]
... shebang =
...   ${hash}!/usr/bin/env python
...   ${hash} -*- coding: utf-8 -*-
...
... extensions =
...   enabled_extension
...   another_extension
...   #disabled_by_comment
...   yet_another_extension
...
... interpolation not necessary = if # is not at line start
... even in multiline values = line #1
...   line #2
...   line #3
... """)
>>> print(parser['hashes']['shebang'])

#!/usr/bin/env python
# -*- coding: utf-8 -*-
>>> print(parser['hashes']['extensions'])

enabled_extension
another_extension
yet_another_extension
>>> print(parser['hashes']['interpolation not necessary'])
if # is not at line start
>>> print(parser['hashes']['even in multiline values'])
line #1
line #2
line #3

strict, valor por defecto: True

Cuando tiene el valor True, el parser no permitirá duplicados en ninguna sección u opción, al efectuar la lectura desde una sola fuente (utilizando read_file(), read_string() ó read_dict()). Se recomienda el uso de strict parsers en las aplicaciones nuevas.

Distinto en la versión 3.2: En versiones previas de configparser el comportamiento correspondía a strict=False.

empty_lines_in_values, valor por defecto: True

En los config parsers, los valores pueden abarcar varias líneas, siempre y cuando estén indentadas a un nivel superior al de la clave que las contiene. De forma predeterminada, los parsers permiten que las líneas en blanco formen parte de los valores. Igualmente, las claves pueden estar indentadas a sí mismas de forma arbitraria, a fin de mejorar la legibilidad. Por lo tanto, cuando los archivos de configuración se vuelven grandes y complejos, es fácil para el usuario el perder la pista de la estructura del archivo. Tomemos como ejemplo:

[Section]
key = multiline
  value with a gotcha

 this = is still a part of the multiline value of 'key'

Esto puede ser especialmente problemático de observar por parte del usuario, en caso que se esté utilizando un tipo de fuente proporcional para editar el archivo. Y es por ello que, cuando tu aplicación no necesite valores con líneas en blanco, debes considerar invalidarlas. Esto ocasionaría que las líneas en blanco sirvan para dividir a las claves, siempre. En el ejemplo anterior, produciría dos claves: key y this.

default_section, valor por defecto: configparser.DEFAULTSECT (es decir: "DEFAULT")

El convenio de permitir una sección especial con valores por defecto para otras secciones, o con propósito de interpolación, es un concepto poderoso de esta librería, el cual permite a los usuarios crear configuraciones declarativas complejas. Esta sección se suele denominar "DEFAULT", pero puede personalizarse para corresponder a cualquier otro nombre de sección. Algunas valores comunes son: "general" ó "common". El nombre proporcionado es utilizado para reconocer las secciones por defecto al momento de realizar la lectura desde cualquier fuente, y es utilizado ante cualquier escritura al archivo de configuración. Su valor actual puede obtenerse utilizando el atributo parser_instance.default_section y puede ser modificado en tiempo de ejecución (es decir, para convertir archivos de un formato a otro).

interpolation, valor por defecto: configparser.BasicInterpolation

El comportamiento de la interpolación puede ser personalizado al proporcionar un gestor personalizado mediante el argumento interpolation. El valor None se utiliza para desactivar la interpolación por completo, mientras que ExtendedInterpolation() proporciona una variante más avanzada, inspirada por zc.buildout. Más información al respecto en la sección dedicada de la documentación. El RawConfigParser tiene un valor por defecto de None.

converters, valor por defecto: no definido

Los config parsers proporcionan métodos para lectura (getters) de valores de opciones, que llevan a cabo la conversión de tipo. Están implementados los métodos getint(), getfloat(), y getboolean(), de forma predeterminada. Si se desean otros métodos de lectura (getters), los usuarios pueden definirlos en una subclase o pasar un diccionario donde cada clave sea el nombre del conversor y cada valor es un invocable (callable) que implemente la conversión requerida. Por ejemplo, al pasar {'decimal': decimal.Decimal} se agregaría getdecimal() tanto en el objeto parser como en todas las secciones proxies. En otras palabras, sería posible escribir tanto parser_instance.getdecimal('section', 'key', fallback=0) como parser_instance['section'].getdecimal('key', 0).

Si el conversor necesita acceder al estado del parser, este puede ser implementado como un método en una subclase del config parser. Si el nombre de este método comienza con get, estará disponible en todas las secciones proxy, en su forma compatible con diccionarios (vea el ejemplo anterior de getdecimal()).

Una personalización más avanzada puede conseguirse al sustituir los valores por defecto de estos atributos del parser. Los valores por defecto son definidos en las clases, de modo que pueden ser sustituidos por las subclases o mediante la asignación de atributos.

ConfigParser.BOOLEAN_STATES

Por defecto, al utilizar el método getboolean(), los config parsers consideran a los siguientes valores como True: '1', 'yes', 'true', 'on' y a los siguientes valores como False: '0', 'no', 'false', 'off'. Puedes cambiar ello proporcionando un diccionario personalizado de cadenas de caracteres, con sus correspondientes valores booleanos. Por ejemplo:

>>> custom = configparser.ConfigParser()
>>> custom['section1'] = {'funky': 'nope'}
>>> custom['section1'].getboolean('funky')
Traceback (most recent call last):
...
ValueError: Not a boolean: nope
>>> custom.BOOLEAN_STATES = {'sure': True, 'nope': False}
>>> custom['section1'].getboolean('funky')
False

Otros pares booleanos comunes incluyen accept/reject ó enabled/disabled.

ConfigParser.optionxform(option)

Este método realiza la transformación de los nombres de opciones para cada operación de lectura, obtención o asignación. Por defecto convierte los nombres a minúsculas. Esto significa que, cuando un archivo de configuración es escrito, todas las claves son convertidas a minúsculas. Sobre-escribe este método si tal comportamiento no es adecuado. Por ejemplo:

>>> config = """
... [Section1]
... Key = Value
...
... [Section2]
... AnotherKey = Value
... """
>>> typical = configparser.ConfigParser()
>>> typical.read_string(config)
>>> list(typical['Section1'].keys())
['key']
>>> list(typical['Section2'].keys())
['anotherkey']
>>> custom = configparser.RawConfigParser()
>>> custom.optionxform = lambda option: option
>>> custom.read_string(config)
>>> list(custom['Section1'].keys())
['Key']
>>> list(custom['Section2'].keys())
['AnotherKey']

Nota

La función optionxform transforma los nombres de opción a una forma canónica. Esta debería ser una función idempotente: si el nombre ya está en su forma canónica, debería retornarse sin cambios.

ConfigParser.SECTCRE

Es una expresión regular compilada que se utiliza para parsear cabeceras de sección. Por defecto hace corresponder [section] con el nombre "section". Los espacios en blanco son considerados parte del nombre de sección, por lo que [  larch  ] será leído como la sección de nombre "  larch  ". Sobre-escribe este atributo si tal comportamiento no es adecuado. Por ejemplo:

>>> import re
>>> config = """
... [Section 1]
... option = value
...
... [  Section 2  ]
... another = val
... """
>>> typical = configparser.ConfigParser()
>>> typical.read_string(config)
>>> typical.sections()
['Section 1', '  Section 2  ']
>>> custom = configparser.ConfigParser()
>>> custom.SECTCRE = re.compile(r"\[ *(?P<header>[^]]+?) *\]")
>>> custom.read_string(config)
>>> custom.sections()
['Section 1', 'Section 2']

Nota

Mientras que los objectos ConfigParser también utilizan un atributo OPTCRE para reconocer las líneas de opciones, no se recomienda su sobre-escritura porque puede interferir con las opciones allow_no_value y delimiters del constructor.

Ejemplos de la API heredada

configparser proporciona también una API heredada con métodos get/set explícitos; ello, principalmente debido a asuntos de compatibilidad con versiones anteriores. Aunque existen casos de uso válidos para los métodos descritos a continuación, se prefiere el acceso por protocolo de mapeo para los proyectos nuevos. La API heredada es al mismo tiempo más avanzada, de bajo nivel y sumamente contradictoria.

Un ejemplo de escritura a un archivo de configuración:

import configparser

config = configparser.RawConfigParser()

# Please note that using RawConfigParser's set functions, you can assign
# non-string values to keys internally, but will receive an error when
# attempting to write to a file or when you get it in non-raw mode. Setting
# values using the mapping protocol or ConfigParser's set() does not allow
# such assignments to take place.
config.add_section('Section1')
config.set('Section1', 'an_int', '15')
config.set('Section1', 'a_bool', 'true')
config.set('Section1', 'a_float', '3.1415')
config.set('Section1', 'baz', 'fun')
config.set('Section1', 'bar', 'Python')
config.set('Section1', 'foo', '%(bar)s is %(baz)s!')

# Writing our configuration file to 'example.cfg'
with open('example.cfg', 'w') as configfile:
    config.write(configfile)

Un ejemplo de lectura de un archivo de configuración, nuevamente:

import configparser

config = configparser.RawConfigParser()
config.read('example.cfg')

# getfloat() raises an exception if the value is not a float
# getint() and getboolean() also do this for their respective types
a_float = config.getfloat('Section1', 'a_float')
an_int = config.getint('Section1', 'an_int')
print(a_float + an_int)

# Notice that the next output does not interpolate '%(bar)s' or '%(baz)s'.
# This is because we are using a RawConfigParser().
if config.getboolean('Section1', 'a_bool'):
    print(config.get('Section1', 'foo'))

Para obtener la interpolación, utilice ConfigParser:

import configparser

cfg = configparser.ConfigParser()
cfg.read('example.cfg')

# Set the optional *raw* argument of get() to True if you wish to disable
# interpolation in a single get operation.
print(cfg.get('Section1', 'foo', raw=False))  # -> "Python is fun!"
print(cfg.get('Section1', 'foo', raw=True))   # -> "%(bar)s is %(baz)s!"

# The optional *vars* argument is a dict with members that will take
# precedence in interpolation.
print(cfg.get('Section1', 'foo', vars={'bar': 'Documentation',
                                       'baz': 'evil'}))

# The optional *fallback* argument can be used to provide a fallback value
print(cfg.get('Section1', 'foo'))
      # -> "Python is fun!"

print(cfg.get('Section1', 'foo', fallback='Monty is not.'))
      # -> "Python is fun!"

print(cfg.get('Section1', 'monster', fallback='No such things as monsters.'))
      # -> "No such things as monsters."

# A bare print(cfg.get('Section1', 'monster')) would raise NoOptionError
# but we can also use:

print(cfg.get('Section1', 'monster', fallback=None))
      # -> None

Los valores por defecto están disponibles en ambos tipos de ConfigParsers. Ellos son utilizados en la interpolación cuando una opción utilizada no está definida en otro lugar.

import configparser

# New instance with 'bar' and 'baz' defaulting to 'Life' and 'hard' each
config = configparser.ConfigParser({'bar': 'Life', 'baz': 'hard'})
config.read('example.cfg')

print(config.get('Section1', 'foo'))     # -> "Python is fun!"
config.remove_option('Section1', 'bar')
config.remove_option('Section1', 'baz')
print(config.get('Section1', 'foo'))     # -> "Life is hard!"

Objetos ConfigParser

class configparser.ConfigParser(defaults=None, dict_type=dict, allow_no_value=False, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section=configparser.DEFAULTSECT, interpolation=BasicInterpolation(), converters={})

La config parser principal. Si se proporciona defaults, su valor es inicializado en el diccionario de valores por defecto intrínsecos. Si se proporciona dict_type, se utiliza para crear el diccionario de objetos para la lista de secciones, las opciones dentro de una sección, y los valores por defecto.

Si se proporciona delimiters, se utiliza como un conjunto de cadenas de caracteres que dividen las claves de los valores. Si se proporciona comment_prefixes, se utiliza como un conjunto de cadenas de caracteres que preceden a los comentarios, en líneas que estarían, de otro modo, vacías. Los comentarios pueden estar indentados. Si se proporciona inline_comment_prefixes, se utiliza como un conjunto de cadenas de caracteres que preceden a los comentarios en líneas que no están vacías.

Cuando strict es True (por defecto), el parser no permitirá duplicados en ninguna sección u opción, al realizar la lectura de una sola fuente (archivo, cadena de caracteres o diccionario), generando una excepción DuplicateSectionError ó DuplicateOptionError. Cuando empty_lines_in_values es False (valor por defecto: True), cada línea en blanco indica el fin de una opción. De otro modo, las líneas en blanco de una opción multilínea son tratadas como parte del valor de esta. Cuando allow_no_value es True (valor por defecto: False), se aceptan opciones sin valores; el valor que toman esas opciones es None y serán serializadas sin el delimitador final.

Cuando se proporciona default_section, se define el nombre de la sección especial que contiene valores por defecto para otras secciones y con propósito de interpolación (habitualmente denominada "DEFAULT"). Este valor puede obtenerse y modificarse en tiempo de ejecución utilizando el atributo de instancia default_section.

La interpolación puede personalizarse al proporcionar un gestor personalizado, mediante el argumento interpolation. El valor None se utiliza para desactivar la interpolación completamente, ExtendedInterpolation() proporciona una variante avanzada, inspirada en zc.buildout. Más al respecto puede encontrarse en la correspondiente sección de la documentación.

Todos los nombres de opción que se utilizan en la interpolación pasarán por el método optionxform(), igual que cualquier otra referencia a un nombre de opción. Por lo tanto, si se utiliza la implementación por defecto de optionxform() (la cual convierte los nombres de opción a minúsculas), los valores foo %(bar)s y foo %(BAR)s son equivalentes.

Cuando se proporciona converters, este debe ser un diccionario, donde cada clave representa el nombre de un conversor, y cada valor un invocable que implementa la conversión de la cadena de caracteres al tipo de datos deseado. Cada conversor recibe su método get*() correspondiente en el objeto parser y los proxies de sección.

Distinto en la versión 3.1: El valor por defecto de dict_type es collections.OrderedDict.

Distinto en la versión 3.2: se agregaron los argumentos allow_no_value, delimiters, comment_prefixes, strict, empty_lines_in_values, default_section y interpolation.

Distinto en la versión 3.5: Se agregó el argumento converters.

Distinto en la versión 3.7: El argumento defaults es leído con read_dict(), proporcionando un comportamiento consistente en el parser: las claves y valores que no sean cadenas de caracteres son convertidas a tales.

Distinto en la versión 3.8: El valor por defecto para dict_type es dict, dado que este ahora preserva el orden de inserción.

defaults()

Retorna un diccionario que contiene los valores por defecto para toda la instancia.

sections()

Retorna una lista de las secciones disponibles; default section no se incluye en la lista.

add_section(section)

Agrega una sección llamada section a la instancia. Si ya existe una sección con el nombre proporcionado, se genera la excepción DuplicateSectionError. Si se suministra el nombre default section, se genera la excepción ValueError. El nombre de la sección debe ser una cadena de caracteres, de lo contrario, se genera la excepción TypeError.

Distinto en la versión 3.2: Nombres de sección que no sean del tipo cadena de caracteres generan la excepción TypeError.

has_section(section)

Indica si la sección de nombre section existe en la configuración. No se permite default section.

options(section)

Retorna una lista de opciones disponibles en la sección especificada.

has_option(section, option)

Si la sección indicada existe, y esta contiene las opción proporcionada, retorna True; de lo contrario, retorna False. Si la sección especificada es None o una cadena de caracteres vacía, se asume DEFAULT.

read(filenames, encoding=None)

Intenta leer y analizar sintácticamente (parse) un iterable de nombres de archivos, retornando una lista de nombres de archivos que han sido analizados (parsed) con éxito.

Si filenames es una cadena de caracteres, un objeto bytes o un path-like object, es tratado como un simple nombre de archivo. Si un archivo mencionado en filenames no puede ser abierto, será ignorado. Está diseñado de forma que puedas especificar un iterable de potenciales ubicaciones para archivos de configuración (por ejemplo, el directorio actual, el directorio home del usuario, o algún directorio del sistema), y todos los archivos de configuración existentes serán leídos.

Si no existe ninguno de los archivos mencionados, la instancia de ConfigParser contendrá un conjunto de datos vacío. Una aplicación que requiera valores iniciales, que sean cargados desde un archivo, deberá cargar el(los) archivo(s) requerido(s) utilizando read_file() antes de llamar a read() para cualquier otro archivo opcional:

import configparser, os

config = configparser.ConfigParser()
config.read_file(open('defaults.cfg'))
config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')],
            encoding='cp1250')

Nuevo en la versión 3.2: El parámetro encoding. Anteriormente, todos los archivos eran leídos utilizando la codificación por defecto de la la función open().

Nuevo en la versión 3.6.1: El parámetro filenames acepta un path-like object.

Nuevo en la versión 3.7: El parámetro filenames acepta un objeto bytes.

read_file(f, source=None)

Leer y analizar (parse) los datos de configuración de f, el cual debe ser un iterable que retorne cadenas de caracteres Unicode (por ejemplo, archivos abiertos en modo texto).

El argumento opcional source especifica el nombre del archivo que se está leyendo. Si no se proporciona y f tiene un atributo name, este es utilizado como source; el valor por defecto es '<???>'.

Nuevo en la versión 3.2: Reemplaza a readfp().

read_string(string, source='<string>')

Analiza (parse) los datos de configuración desde una cadena de caracteres.

El argumento opcional source especifica un nombre para la cadena de caracteres proporcionada, relativo al contexto. Si no se proporciona, se utiliza '<string>'. Esto, por lo general, debería ser una ruta de archivo o una URL.

Nuevo en la versión 3.2.

read_dict(dictionary, source='<dict>')

Carga la configuración a partir de cualquier objeto que proporcione un método items(), similar a un diccionario. Las claves son nombres de secciones, los valores son diccionarios con claves y valores que deben estar presentes en la sección. Si el tipo de diccionario utilizado preserva el orden, las secciones y sus claves serán agregados en orden. Los valores son convertidos a cadenas de caracteres de forma automática.

El argumento opcional source especifica un nombre para el diccionario proporcionado, relativo al contexto. Si no se proporciona, se utiliza <dict>.

Este método puede utilizarse para copiar el estado entre parsers.

Nuevo en la versión 3.2.

get(section, option, *, raw=False, vars=None[, fallback])

Obtiene el valor de una option para la sección indicada. Si se proporciona vars, tiene que ser un diccionario. El valor de option será buscado en vars (si se proporciona), en section y en DEFAULTSECT, en ese orden. Si la clave no se encuentra, y se ha proporcionado fallback, este es utilizado como un valor de contingencia. Se puede utilizar None como valor de contingencia (fallback).

Todas las interpolaciones '%' son expandidas en el valor retornado, a menos que el argumento raw sea true. Los valores para la interpolación de las claves son buscados de la misma forma que para la opción.

Distinto en la versión 3.2: Los argumentos raw, vars y fallback son argumentos nombrados solamente, a fin de proteger a los usuarios de los intentos de emplear el tercer argumento como el valor de contingencia de fallback (especialmente cuando se utiliza el protocolo de mapeo).

getint(section, option, *, raw=False, vars=None[, fallback])

Un cómodo método para forzar a entero el valor de la opción de la sección indicada. Revise get() para una explicación acerca de raw, vars y fallback.

getfloat(section, option, *, raw=False, vars=None[, fallback])

Un cómodo método para forzar a número de punto flotante el valor de la opción de la sección indicada. Revise get() para una explicación acerca de raw, vars y fallback.

getboolean(section, option, *, raw=False, vars=None[, fallback])

Un cómodo método para forzar a booleano el valor de la opción de la sección indicada. Tome nota que los valores aceptados para la opción son '1', 'yes', 'true', and 'on', para que el método retorne True, y '0', 'no', 'false', y 'off' para que el método retorne False. Esos valores de cadenas de caracteres son revisados sin diferenciar mayúsculas de minúsculas. Cualquier otro valor ocasionará que se genere la excepción ValueError. Revise get() para una explicación acerca de raw, vars y fallback.

items(raw=False, vars=None)

items(section, raw=False, vars=None)

Cuando no se proporciona el argumento section, retorna una lista de pares section_name, section_proxy, incluyendo DEFAULTSECT.

De lo contrario, retorna una lista de pares name, value para las opciones de la sección especificada. Los argumentos opcionales tienen el mismo significado que en el método get().

Distinto en la versión 3.8: Los elementos que estén en vars no aparecen en el resultado. El comportamiento previo mezcla las opciones actuales del parser con las variables proporcionadas para la interpolación.

set(section, option, value)

Si la sección indicada existe, asigna el valor especificado a la opción indicada; en caso contrario, genera la excepción NoSectionError. option y value deben ser cadenas de caracteres; de lo contrario, se genera la excepción TypeError.

write(fileobject, space_around_delimiters=True)

Escribe una representación de la configuración al file object especificado, el cual debe ser abierto en modo texto (aceptando cadenas de caracteres). Esta representación puede ser analizada (parsed) por una posterior llamada a read(). Si space_around_delimiters es true, los delimitadores entre claves y valores son rodeados por espacios.

Nota

Comments in the original configuration file are not preserved when writing the configuration back. What is considered a comment, depends on the given values for comment_prefix and inline_comment_prefix.

remove_option(section, option)

Elimina la opción especificada de la sección indicada. Si la sección no existe, se genera una excepción NoSectionError. Si la opción existía antes de la eliminación, retorna True; de lo contrario retorna False.

remove_section(section)

Elimina la sección especificada de la configuración. Si la sección existía, retorna True. De lo contrario, retorna False.

optionxform(option)

Transforma el nombre de opción option de la forma en que se encontraba en el archivo de entrada o como fue pasada por el código del cliente, a la forma en que debe ser utilizada en las estructuras internas. La implementación por defecto retorna una versión en minúsculas de option; las subclases pueden sobre-escribirla o el código del cliente puede asignar un atributo de su nombre en las instancias, para afectar su comportamiento.

No necesitas crear una subclase del parser para utilizar este método, ya que también puedes asignarlo en una instancia a una función, la cual reciba una cadena de caracteres como argumento y retorne otra. Por ejemplo, estableciéndola a str, se hará que los nombres de opciones sean sensibles a mayúsculas y minúsculas:

cfgparser = ConfigParser()
cfgparser.optionxform = str

Tome en cuenta que cuando se leen archivos de configuración, los espacios en blanco alrededor de los nombres de opción son eliminados antes de llamar a optionxform().

readfp(fp, filename=None)

Obsoleto desde la versión 3.2: Utilice read_file() en su lugar.

Distinto en la versión 3.2: Ahora, readfp() itera sobre fp, en lugar de llamar a fp.readline().

Para el código existente, que llama a readfp() sin argumentos que soporten la iteración, el siguiente generador puede utilizarse como un envoltorio (wrapper) para el objeto semejante a archivo:

def readline_generator(fp):
    line = fp.readline()
    while line:
        yield line
        line = fp.readline()

Utilice parser.read_file(readline_generator(fp)) en lugar de parser.readfp(fp).

configparser.MAX_INTERPOLATION_DEPTH

La profundidad máxima de interpolación para get() cuando el parámetro raw es false. Esto es de importancia solamente cuando la interpolación por defecto es empleada.

Objetos RawConfigParser

class configparser.RawConfigParser(defaults=None, dict_type=dict, allow_no_value=False, *, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section=configparser.DEFAULTSECT[, interpolation])

Variante heredada de ConfigParser. Tiene la interpolación deshabilitada por defecto y permite nombres de sección que no sean cadenas de caracteres, nombres de opciones, y valores a través de sus métodos inseguros add_section y set, así como el manejo heredado del argumento nombrado defaults=.

Distinto en la versión 3.8: El valor por defecto para dict_type es dict, dado que este ahora preserva el orden de inserción.

Nota

Considere el uso de ConfigParser en su lugar, el cual verifica los tipos de datos de los valores que se almacenarán internamente. Si no quieres la interpolación, puedes utilizar ConfigParser(interpolation=None).

add_section(section)

Agrega a la instancia una sección de nombre section. Si ya existe una sección con el nombre proporcionado, se genera la excepción DuplicateSectionError. Si se suministra el nombre default section, se genera la excepción ValueError.

No se comprueba el tipo de datos de section, con lo cual se permite que los usuarios creen secciones con nombres que no sean cadenas de caracteres. Este comportamiento no está soportado y puede ocasionar errores internos.

set(section, option, value)

Si existe la sección indicada, asigna el valor especificado a la sección indicada; de lo contrario, genera la excepción NoSectionError. Aunque es posible utilizar RawConfigParser (ó ConfigParser con parámetros raw con valor true) como almacenamiento interno para valores que no sean cadenas de caracteres, el funcionamiento completo (incluyendo la interpolación y escritura en archivos) sólo puede lograrse utilizando valores del tipo cadena de caracteres.

Este método permite que los usuarios asignen valores que no sean cadenas de caracteres a las claves, internamente. Este comportamiento no está soportado y causará errores cuando se intente escribir en un archivo o cuando se intente obtenerlo en un modo no raw. Utilice la API del protocolo de mapeo, la cual no permite ese tipo de asignaciones.

Excepciones

exception configparser.Error

Clase base para todas las otras excepciones configparser.

exception configparser.NoSectionError

Excepción generada cuando no se encuentra una sección especificada.

exception configparser.DuplicateSectionError

Excepción generada si el método add_section() es llamado proporcionando el nombre de una sección que ya existe, o, en caso de parsers estrictos, si una sección se encuentra más de una vez en un solo archivo de entrada, cadena de caracteres o diccionario.

Nuevo en la versión 3.2: Al método __init__() se agregaron los atributos y argumentos opcionales source y lineno.

exception configparser.DuplicateOptionError

Excepción generada por parsers estrictos si una sola opción aparece dos veces durante la lectura de un solo archivo, cadena de caracteres o diccionario. Captura errores de escritura o relacionados con el uso de mayúsculas y minúsculas, ej. un diccionario podría tener dos claves que representan la misma clave de configuración bajo un esquema insensible a mayúsculas y minúsculas.

exception configparser.NoOptionError

Excepción generada cuando una opción especificada no se encuentra en una sección indicada.

exception configparser.InterpolationError

Clase base para excepciones generadas por problemas que ocurren al realizar la interpolación de cadenas de caracteres.

exception configparser.InterpolationDepthError

Excepción generada cuando la interpolación de cadenas de caracteres no puede completarse, debido a que el número de iteraciones excede a MAX_INTERPOLATION_DEPTH. Subclase de InterpolationError.

exception configparser.InterpolationMissingOptionError

Excepción generada cuando no existe una opción referida por un valor. Subclase de InterpolationError.

exception configparser.InterpolationSyntaxError

Excepción generada cuando el texto fuente, donde se realizan las sustituciones, no se ajusta a la sintaxis requerida. Subclase de InterpolationError.

exception configparser.MissingSectionHeaderError

Excepción generada cuando se intenta analizar (parse) un archivo que no tiene encabezados de sección.

exception configparser.ParsingError

Excepción generada cuando ocurren errores intentando analizar (parse) un archivo.

Distinto en la versión 3.2: El atributo filename y el argumento __init__() fueron renombrados a source por consistencia.

Notas al pie

1(1,2,3,4,5,6,7,8,9,10,11)

Los config parsers permiten una gran personalización. Si estás interesado en modificar el comportamiento descrito por la referencia de la nota al pie, consulta la sección Customizing Parser Behaviour.

netrc — procesado del fichero netrc

Código fuente: Lib/netrc.py [https://github.com/python/cpython/tree/3.9/Lib/netrc.py]

La clase netrc analiza y encapsula el formato del fichero netrc, usado por el programa Unix ftp y otros clientes FTP.

class netrc.netrc([file])

Una instancia de netrc o una instancia de una subclase encapsula la información del fichero netrc. El argumento de inicialización, si está presente, especifica el fichero a analizar. Si no se pasan argumentos, se leerá el fichero .netrc del directorio home del usuario – determinado por os.path.expanduser(). De lo contrario, se lanzará una excepción FileNotFoundError. Los errores de análisis lanzarán una excepción NetrcParseError con información de diagnóstico que incluye nombre del fichero, número de línea y token de finalización. Si no se especifica ningún argumento en un sistema POSIX, la presencia de contraseñas en el fichero .netrc lanzará una excepción NetrcParseError si la propiedad del fichero o los permisos son inseguros (el propietario del fichero es distinto del usuario que ejecuta el proceso, o puede ser leído o escrito por cualquier otro usuario). Esto implementa un nivel de seguridad equivalente al de ftp y otros programas que usan .netrc.

Distinto en la versión 3.4: Añadida la comprobación de permisos POSIX.

Distinto en la versión 3.7: os.path.expanduser() se usa para encontrar la localización del fichero .netrc cuando file no se pasa como argumento.

exception netrc.NetrcParseError

Excepción lanzada por la clase netrc cuando se encuentran errores sintácticos en el texto origen. Las instancias de esta excepción ofrecen tres atributos interesantes: msg es una explicación textual del error, filename es el nombre del fichero origen, y lineno indica el número de línea en el que se encontró el error.

Objetos netrc

Una instancia netrc tiene los siguientes métodos:

netrc.authenticators(host)

Retorna una 3-tupla (login, account, password) para autenticarse contra host. Si el fichero netrc no contiene una entrada para el host dado, retorna una tupla asociada con la entrada por defecto. Si no están disponibles ni el host correspondiente ni la entrada por defecto, retorna None.

netrc.__repr__()

Vuelca los datos de la clase como una cadena de caracteres en el formato de un fichero netrc. (Esto descarta comentarios y puede reordenar las entradas.)

Las instancias de netrc tienen variables de instancia públicas:

netrc.hosts

Diccionario que asocia nombres de hosts a tuplas (login, account, password). La entrada por defecto, si existe, está representada como un pseudo-host por ese nombre.

netrc.macros

Diccionario que asocia nombres de macros a listas de cadenas de caracteres.

Nota

Las contraseñas están limitadas a un subconjunto del conjunto de caracteres ASCII. En las contraseñas se permiten todos los símbolos de puntuación ASCII. Sin embargo, no se permiten espacios en blanco ni caracteres no imprimibles. Esto es una limitación de la manera en que se analiza el fichero .netrc y puede que se elimine en el futuro.

plistlib — Genera y analiza archivos .plist de Apple

Código fuente: Lib/plistlib.py [https://github.com/python/cpython/tree/3.9/Lib/plistlib.py]

Este módulo proporciona una interfaz para leer y escribir los archivos de «lista de propiedades» utilizados por Apple, principalmente en macOS e iOS. Este módulo admite archivos plist binarios y XML.

El formato de lista de propiedades (.plist) es una serialización simple que soporta tipos de objetos básicos, como diccionarios, listas, números y cadenas. Generalmente el objeto de nivel superior es un diccionario.

Para escribir y analizar un archivo plist usa las funciones dump() y load().

Para trabajar con datos plist en objetos de bytes usa dumps() y loads().

Los valores pueden ser cadenas, enteros, flotantes, booleanos, tuplas, listas, diccionarios (pero solo con claves de cadena), bytes, bytearray u objetos datetime.datetime.

Distinto en la versión 3.4: Nueva API, API antigua obsoleta. Añadido soporte para plists en formato binario.

Distinto en la versión 3.8: Añadido soporte para lectura y escritura de tokens UID en plists binarios como lo usan NSKeyedArchiver y NSKeyedUnarchiver.

Distinto en la versión 3.9: API antigua eliminada.

Ver también

Página del manual PList [https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/PropertyLists/]

Documentación de Apple del formato de archivo.

Este módulo define las siguientes funciones:

plistlib.load(fp, *, fmt=None, dict_type=dict)

Lee un archivo plist. fp debe ser un objeto de archivo binario y legible. Retorna el objeto raíz desempaquetado (el cual generalmente es un diccionario).

El fmt es el formato del archivo y los siguientes valores son válidos:

None: Autodetecta el formato de archivo

FMT_XML: Formato de archivo XML

FMT_BINARY: Formato binario plist

EL dict_type es el tipo usado por los diccionarios que son leídos del archivo plist.

Los datos XML para el formato FMT_XML son analizados usando el analizador Expat desde xml.parsers.expat – consulte su documentación para conocer las posibles excepciones en XML mal formado. Elementos desconocidos serán simplemente ignorados por el analizador plist.

El analizar para el formato binario lanza InvalidFileException cuando el archivo no puede ser analizado.

Nuevo en la versión 3.4.

plistlib.loads(data, *, fmt=None, dict_type=dict)

Carga un plist desde un objeto de bytes. Consulte load() para una explicación de los argumentos de palabra clave.

Nuevo en la versión 3.4.

plistlib.dump(value, fp, *, fmt=FMT_XML, sort_keys=True, skipkeys=False)

Escribe value a un archivo plist. Fp debe ser un objeto de archivo binario escribible.

El argumento fmt especifica el formato del archivo plist y puede ser uno de los siguientes valores:

FMT_XML: Archivo plist con formato XML

FMT_BINARY: Archivo plist con formato binario

Cuando sort_keys es verdadero (el valor por defecto) las claves para los diccionarios serán escritas al plist ordenadamente, si no serán escritas en el orden de iteración del diccionario.

Cuando skipkeys es falso (el valor por defecto) la función levanta TypeError cuando una clave del diccionario no es una cadena de caracteres, si no tales claves serán omitidas.

Una excepción TypeError será levantada si el objeto es un tipo no admitido o el contenedor que contiene tipos no admitidos.

Una excepción OverflowError será levantada para valores enteros que no pueden ser representados en archivos plist (binarios).

Nuevo en la versión 3.4.

plistlib.dumps(value, *, fmt=FMT_XML, sort_keys=True, skipkeys=False)

Retorna value como un objeto de bytes con formato plist. Consulte la documentación de dump() para una explicación de los argumentos de palabra clave de esta función.

Nuevo en la versión 3.4.

Las siguientes clases están disponibles:

class plistlib.UID(data)

Envuelve un int. Este es usado leyendo o escribiendo datos codificados NSKeyedArchiver, los cuales contienen UID (ver manual PList).

It has one attribute, data, which can be used to retrieve the int value of the UID. data must be in the range 0 <= data < 2**64.

Nuevo en la versión 3.8.

Las siguientes constantes están disponibles:

plistlib.FMT_XML

El formato XML para archivos plist.

Nuevo en la versión 3.4.

plistlib.FMT_BINARY

El formato binario para archivos plist

Nuevo en la versión 3.4.

Ejemplos

Generar un plist:

pl = dict(
    aString = "Doodah",
    aList = ["A", "B", 12, 32.1, [1, 2, 3]],
    aFloat = 0.1,
    anInt = 728,
    aDict = dict(
        anotherString = "<hello & hi there!>",
        aThirdString = "M\xe4ssig, Ma\xdf",
        aTrueValue = True,
        aFalseValue = False,
    ),
    someData = b"<binary gunk>",
    someMoreData = b"<lots of binary gunk>" * 10,
    aDate = datetime.datetime.fromtimestamp(time.mktime(time.gmtime())),
)
with open(fileName, 'wb') as fp:
    dump(pl, fp)

Analizar un plist:

with open(fileName, 'rb') as fp:
    pl = load(fp)
print(pl["aKey"])

Servicios Criptográficos

Los módulos descritos en este capítulo implementan varios algoritmos de naturaleza criptográfica. Están disponibles a discreción de la instalación. En sistema Unix, el módulo crypt también puede estar disponible. Aquí una descripción:

hashlib — Hashes seguros y resúmenes de mensajes

Algoritmos de hash

Resúmenes SHAKE de largo variable

Derivación de clave

BLAKE2

Creando objetos hash

Constantes

Ejemplos

Cifrado simple

Usar diferentes tamaños de resumen

Cifrado de clave

Cifrado aleatorio

Personalización

Modo de árbol

Créditos

hmac — Hash con clave para autenticación de mensajes

secrets — Genera números aleatorios seguros para trabajar con secretos criptográficos

Números aleatorios

Generando tokens

¿Cuántos bytes deben tener los tokens?

Otras funciones

Recetas y mejores prácticas

hashlib — Hashes seguros y resúmenes de mensajes

Código fuente: Lib/hashlib.py [https://github.com/python/cpython/tree/3.9/Lib/hashlib.py]

Este módulo implementa una interfaz común a diferentes algoritmos de hash y resúmenes de mensajes seguros. Están incluidos los algoritmos de hash FIPS seguros SHA1, SHA224, SHA226, SHA384 y SHA512 (definidos en FIPS 180-2) además del algoritmo MD5 de RSA (definido en Internet RFC 1321 [https://tools.ietf.org/html/rfc1321.html]). Los términos «hash seguro» y «resumen de mensaje» son intercambiables. Los algoritmos más antiguos fueron denominados resúmenes de mensajes. El término moderno es hash seguro.

Nota

Si quieres las funciones de hash adler32 o crc32, están disponibles en el módulo zlib.

Advertencia

Algunos algoritmos tienen conocidas debilidades de colisión de hash, consulte la sección «Ver también» al final.

Algoritmos de hash

Hay un método constructor nombrado para cada tipo de hash. Todos retornan un objeto de hash con la misma interfaz simple. Por ejemplo, usa sha256() para crear un objeto de hash SHA-256. Ahora puedes alimentar este objeto con objetos como bytes (normalmente bytes) usando el método update(). En cualquier punto puedes pedir el resumen (digest) de la concatenación de los datos alimentados al mismo usando los métodos digest() o hexdigest().

Nota

Para un rendimiento multihilo mejor, el GIL de Python es liberado para datos superiores a 2047 bytes en la creación o actualización de objetos.

Nota

La alimentación de objetos de cadenas en update() no está soportada, ya que los hashes funcionan en bytes, no en caracteres.

Los constructores para algoritmos hash que siempre están presentes en este módulo son sha1(), sha224(), sha256(), sha384(), sha512(), blake2b() y blake2s(). md5() normalmente también está disponible, aunque puede faltar o estar bloqueado si está utilizando una rara compilación de Python «compatible con FIPS «. También pueden estar disponibles algoritmos adicionales dependiendo de la biblioteca OpenSSL que Python use en su plataforma. En la mayoría de las plataformas también están disponibles sha3_224(), sha3_256(), sha3_384(), sha3_512(), shake_128(), shake_256().

Nuevo en la versión 3.6: Constructores SHA3 (Keccak) y SHAKE sha3_224(), sha3_256(), sha3_384(), sha3_512(), shake_128(), shake_256().

Nuevo en la versión 3.6: Fueron añadidas blake2b() y blake2s().

Distinto en la versión 3.9: Todos los constructores hashlib toman un argumento de solo palabra clave usedforsecurity con el valor predeterminado True. Un valor falso permite el uso de algoritmos hash inseguros y bloqueados en entornos restringidos. False indica que el algoritmo hash no se utiliza en un contexto de seguridad, por ejemplo, como una función de compresión unidireccional no criptográfica.

Hashlib ahora usa SHA3 y SHAKE de OpenSSL 1.1.1 y posteriores.

Por ejemplo, para obtener el resumen de la cadena de bytes b'Nobody inspects the spammish repetition':

>>> import hashlib
>>> m = hashlib.sha256()
>>> m.update(b"Nobody inspects")
>>> m.update(b" the spammish repetition")
>>> m.digest()
b'\x03\x1e\xdd}Ae\x15\x93\xc5\xfe\\\x00o\xa5u+7\xfd\xdf\xf7\xbcN\x84:\xa6\xaf\x0c\x95\x0fK\x94\x06'
>>> m.digest_size
32
>>> m.block_size
64

Más resumido:

>>> hashlib.sha224(b"Nobody inspects the spammish repetition").hexdigest()
'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'

hashlib.new(name, [data, ]*, usedforsecurity=True)

Es un constructor genérico que toma la cadena name del algoritmo deseado como su primer parámetro. También existe para permitir acceso a los hashes arriba listados así como cualquiera de los otros algoritmos que tu biblioteca OpenSSL puede ofrecer. Los constructores nombrados son mucho más rápidos que new() y deberían preferirse.

Usando new() con un algoritmo provisto por OpenSSL:

>>> h = hashlib.new('sha256')
>>> h.update(b"Nobody inspects the spammish repetition")
>>> h.hexdigest()
'031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'

Hashlib provee los siguientes atributos constantes:

hashlib.algorithms_guaranteed

Un conjunto que contiene los nombres de los algoritmos garantizados a ser soportados por este módulo en todas las plataformas. Ten en cuenta que “md5” se encuentra en esta lista a pesar de que algunos proveedores ofrecen una extraña construcción Python «compatible con FIPS» que la excluye.

Nuevo en la versión 3.2.

hashlib.algorithms_available

Un conjunto que contiene los nombres de los algoritmos de hash que están disponibles en el intérprete de Python en ejecución. Estos nombres serán reconocidos cuando sean pasados a new(). algorithms_guaranteed siempre será un subconjunto. El mismo algoritmo puede aparecer múltiples veces en este conjunto bajo diferentes nombres (gracias a OpenSSL).

Nuevo en la versión 3.2.

Los siguientes valores son provistos como atributos constantes de los objetos hash retornados por los constructores:

hash.digest_size

El tamaño del hash resultante en bytes.

hash.block_size

El tamaño del bloque interno del algoritmo de hash en bytes.

Un objeto hash tiene los siguientes atributos:

hash.name

El nombre canónico de este hash, siempre en minúsculas y siempre adecuado como un parámetro a new() para crear otro hash de este tipo.

Distinto en la versión 3.4: El atributo name ha estado presente en CPython desde su inicio, pero desde Python 3.4 no fue especificado formalmente, por lo que puede no existir en algunas plataformas.

Un objeto hash tiene los siguientes métodos:

hash.update(data)

Actualiza el objeto de hash con el bytes-like object. Invocaciones repetidas son equivalentes a una única invocación con la concatenación de todos los argumentos: m.update(a); m.update(b) es equivalente a m.update(a+b).

Distinto en la versión 3.1: El GIL de Python es liberado para permitir a otros hilos ejecutarse mientras ocurren actualizaciones de hash en datos con tamaños superiores a 2047 bytes cuando se usan algoritmos de hash suministrados por OpenSSL.

hash.digest()

Retorna el resumen de los datos pasados al método update() hasta el momento. Este es un objeto de bytes de tamaño digest_size el cual puede contener bytes en el rango completo desde 0 a 255.

hash.hexdigest()

Como digest() excepto que el resumen es retornado como un objeto de cadena del doble de largo, conteniendo sólo dígitos hexadecimales. Este puede ser usado para intercambiar el valor de forma segura en correos electrónicos u otros entornos no binarios.

hash.copy()

Retorna una copia («clon») del objeto hash. Este puede ser usado para calcular eficientemente los resúmenes de datos compartiendo una subcadena inicial común.

Resúmenes SHAKE de largo variable

Los algoritmos shake_128() y shake_256() proveen resúmenes de largo variable con largo_en_bits//2 hasta 128 ó 256 bits de seguridad. Como tales, sus métodos de resumen requieren un largo. El largo máximo no está limitado por el algoritmo SHAKE.

shake.digest(length)

Retorna el resumen de los datos pasados al método update() hasta el momento. Este es un objeto de bytes de tamaño length el cual puede contener bytes en el rango completo desde 0 a 255.

shake.hexdigest(length)

Como digest() excepto que el resumen es retornado como un objeto de cadena del doble de largo, conteniendo sólo dígitos hexadecimales. Este puede ser usado para intercambiar el valor de forma segura en correos electrónicos u otros entornos no binarios.

Derivación de clave

Los algoritmos de derivación de clave y estiramiento de clave están diseñados para el cifrado seguro de contraseña. Algoritmos ingenuos como sha1(password) no son resistentes contra ataques de fuerza bruta. Una buena función hash de contraseña debe ser afinable, lenta e incluir una sal [https://es.wikipedia.org/wiki/Sal_(criptograf%C3%ADa)].

hashlib.pbkdf2_hmac(hash_name, password, salt, iterations, dklen=None)

La función provee contraseñas PKCS#5 basadas en función de derivación de clave 2. Usa HMAC como función de pseudoaleatoriedad.

La cadena hash_name es el nombre deseado del algoritmo de resumen de hash para HMAC, ej. “sha1” o “sha256”. password y salt son interpretados como búferes de bytes. Aplicaciones y bibliotecas deberían limitar password a un largo razonable (ej. 1024). salt debería ser sobre 16 o más bytes desde una fuente adecuada, ej. os.urandom().

El número de iterations debería ser elegido basado en el algoritmo de hash y el poder de cómputo. A partir del 2013, se sugiere al menos 100,000 iteraciones de SHA-256.

dklen es el largo de la clave derivada. Si dklen es None entonces el tamaño de resumen del algoritmo de hash hash_name es usado, ej. 64 para SHA-512.

>>> import hashlib
>>> dk = hashlib.pbkdf2_hmac('sha256', b'password', b'salt', 100000)
>>> dk.hex()
'0394a2ede332c9a13eb82e9b24631604c31df978b4e2f0fbd2c549944f9d79a5'

Nuevo en la versión 3.4.

Nota

Una implementación rápida de pbkdf2_hmac está disponible con OpenSSL. La implementación Python usa una versión en línea de hmac. Es aproximadamente tres veces más lenta y no libera el GIL.

hashlib.scrypt(password, *, salt, n, r, p, maxmem=0, dklen=64)

La función provee una contraseña scrypt basada en una función derivación de clave como es definida en RFC 7914 [https://tools.ietf.org/html/rfc7914.html].

password y salt deben ser objetos de bytes. Aplicaciones y bibliotecas deberían limitar password a un largo razonable (ej. 1024). salt debería ser aproximadamente 16 o más bytes de una fuente adecuada, ej. os.unrandom().

n es el factor de coste de CPU/Memoria, r el tamaño de bloque, p el factor de paralelización y maxmem limita la memoria (OpenSSL 1.1.0 por defecto a 32 MiB). dklen es el largo de la clave derivada.

Disponibilidad: OpenSSL 1.1+.

Nuevo en la versión 3.6.

BLAKE2

BLAKE2 [https://blake2.net] es una función de hash criptográfico definida en RFC 7693 [https://tools.ietf.org/html/rfc7693.html] que viene en dos sabores:

BLAKE2b, optimizada para plataformas de 64 bits y produce resúmenes de cualquier tamaño entre 1 y 64 bytes,

BLAKE2s, optimizada para plataformas de 8 a 32 bits y produce resúmenes de cualquier tamaño entre 1 y 32 bytes.

BLAKE2 proporciona el modo keyed (un remplazamiento más simple rápido para HMAC [https://en.wikipedia.org/wiki/Hash-based_message_authentication_code]), cifrado salado (salted hashing), personalización y cifrado de árbol.

Los objetos hash de este módulo siguen los estándares de los objetos de la biblioteca hashlib.

Creando objetos hash

Se crean nuevos objetos hash invocando a las funciones de constructor:

hashlib.blake2b(data=b'', *, digest_size=64, key=b'', salt=b'', person=b'', fanout=1, depth=1, leaf_size=0, node_offset=0, node_depth=0, inner_size=0, last_node=False, usedforsecurity=True)

hashlib.blake2s(data=b'', *, digest_size=32, key=b'', salt=b'', person=b'', fanout=1, depth=1, leaf_size=0, node_offset=0, node_depth=0, inner_size=0, last_node=False, usedforsecurity=True)

Estas funciones retornan los objetos hash correspondientes para calcular BLAKE2b o BLAKE2s. Ellas toman opcionalmente estos parámetros generales:

data: trozo inicial de datos a cifrar, el cual debe ser un bytes-like object. Puede ser pasado sólo como argumento posicional.

digest_size: tamaño del resumen de salida en bytes.

key: clave para el cifrado de clave (keyed hashing) (hasta 64 bytes para BLAKE2b, hasta 32 bytes para BLAKE2s).

salt: sal para el cifrado aleatorio (hasta 16 bytes para BLAKE2b, hasta 8 bytes para BLAKE2s).

person: cadena de personalización (hasta 16 bytes para BLAKE2b, hasta 8 bytes para BLAKE2s).

La siguiente tabla muestra los límites para parámetros generales (en bytes):

Cifrado

digest_size

len(key)

len(salt)

len(person)

BLAKE2b

64

64

16

16

BLAKE2s

32

32

8

8

Nota

La especificación BLAKE2 define largos constantes para los parámetros de sal y personalización, sin embargo, por conveniencia, esta implementación acepta cadenas de bytes de cualquier tamaño hasta el largo especificado. Si el largo del parámetro es menor que el especificado, es acolchado con ceros, por lo tanto, por ejemplo, b'salt' y b'salt\x00' es el mismo valor. (Este no es el caso para key.)

Estos tamaños están disponibles como constantes del módulo descritas abajo.

Las funciones constructoras también aceptan los siguientes parámetros de cifrado de árbol:

fanout: despliegue en abanico (0 a 255, 0 si ilimitado, 1 en modo secuencial).

depth: profundidad máxima del árbol (1 a 255, 255 si ilimitado, 1 en modo secuencial).

leaf_size: maximal byte length of leaf (0 to 2**32-1, 0 if unlimited or in sequential mode).

node_offset: node offset (0 to 2**64-1 for BLAKE2b, 0 to 2**48-1 for BLAKE2s, 0 for the first, leftmost, leaf, or in sequential mode).

node_depth: profundidad de nodo (0 a 255, 0 para hojas o en modo secuencial).

inner_size: tamaño interno del resumen (0 a 64 para BLAKE2b, 0 a 32 para BLAKE2s, 0 en modo secuencial).

last_node: booleano indicando si el nodo procesado es el último (False para modo secuencial).

Consulta la sección 2.10 en la especificación BLAKE2 <https://blake2.net/blake2_20130129.pdf> para una revisión integral del cifrado en árbol.

Constantes

blake2b.SALT_SIZE

blake2s.SALT_SIZE

Largo de sal (largo máximo aceptado por los constructores).

blake2b.PERSON_SIZE

blake2s.PERSON_SIZE

Largo de cadena de personalización (largo máximo aceptado por los constructores).

blake2b.MAX_KEY_SIZE

blake2s.MAX_KEY_SIZE

Tamaño máximo de clave.

blake2b.MAX_DIGEST_SIZE

blake2s.MAX_DIGEST_SIZE

Tamaño máximo de resumen que puede producir la función hash.

Ejemplos

Cifrado simple

Para calcular el hash de algunos datos, primero debes construir un objeto hash invocando a la función del constructor apropiada (blake2b() o blake2s()), entonces actualizarlo con los datos invocando update() en el objeto y, finalmente, obtener el resumen del objeto invocando digest() (o hexdigest() para una cadena codificada en hexadecimal).

>>> from hashlib import blake2b
>>> h = blake2b()
>>> h.update(b'Hello world')
>>> h.hexdigest()
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'

Como atajo, puedes pasar el primer trozo de datos para actualizar directamente el constructor como el argumento posicional:

>>> from hashlib import blake2b
>>> blake2b(b'Hello world').hexdigest()
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'

Puedes invocar hash.update() tantas veces como necesites para actualizar el hash iterativamente:

>>> from hashlib import blake2b
>>> items = [b'Hello', b' ', b'world']
>>> h = blake2b()
>>> for item in items:
...     h.update(item)
>>> h.hexdigest()
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'

Usar diferentes tamaños de resumen

BLAKE2 tiene tamaño de resúmenes configurables de hasta 64 bytes para BLAKE2b y 32 bytes para BLAKE2s. Por ejemplo, para remplazar SHA-1 con BLAKE2b sin cambiar el tamaño de la salida, puedes decirle a BLAKE2b que produzca resúmenes de 20 bytes:

>>> from hashlib import blake2b
>>> h = blake2b(digest_size=20)
>>> h.update(b'Replacing SHA1 with the more secure function')
>>> h.hexdigest()
'd24f26cf8de66472d58d4e1b1774b4c9158b1f4c'
>>> h.digest_size
20
>>> len(h.digest())
20

Objetos hash con diferentes tamaños de resumen tienen salidas completamente diferentes (hashes más cortos no son prefijos de hashes más largos); BLAKE2b y BLAKE2s producen salidas diferentes incluso si el largo de salida es el mismo:

>>> from hashlib import blake2b, blake2s
>>> blake2b(digest_size=10).hexdigest()
'6fa1d8fcfd719046d762'
>>> blake2b(digest_size=11).hexdigest()
'eb6ec15daf9546254f0809'
>>> blake2s(digest_size=10).hexdigest()
'1bf21a98c78a1c376ae9'
>>> blake2s(digest_size=11).hexdigest()
'567004bf96e4a25773ebf4'

Cifrado de clave

Keyed hashing can be used for authentication as a faster and simpler replacement for Hash-based message authentication code [https://en.wikipedia.org/wiki/HMAC] (HMAC). BLAKE2 can be securely used in prefix-MAC mode thanks to the indifferentiability property inherited from BLAKE.

Este ejemplo muestra como obtener un código de autentificación (codificado como hexadecimal) de 128 bits para el mensaje b'message data' con la clave b'pseudorandom key':

>>> from hashlib import blake2b
>>> h = blake2b(key=b'pseudorandom key', digest_size=16)
>>> h.update(b'message data')
>>> h.hexdigest()
'3d363ff7401e02026f4a4687d4863ced'

Como ejemplo práctico, una aplicación web puede firmar simétricamente cookies enviadas a los usuarios y verificarlas más tarde para asegurar que no fueron manipuladas con:

>>> from hashlib import blake2b
>>> from hmac import compare_digest
>>>
>>> SECRET_KEY = b'pseudorandomly generated server secret key'
>>> AUTH_SIZE = 16
>>>
>>> def sign(cookie):
...     h = blake2b(digest_size=AUTH_SIZE, key=SECRET_KEY)
...     h.update(cookie)
...     return h.hexdigest().encode('utf-8')
>>>
>>> def verify(cookie, sig):
...     good_sig = sign(cookie)
...     return compare_digest(good_sig, sig)
>>>
>>> cookie = b'user-alice'
>>> sig = sign(cookie)
>>> print("{0},{1}".format(cookie.decode('utf-8'), sig))
user-alice,b'43b3c982cf697e0c5ab22172d1ca7421'
>>> verify(cookie, sig)
True
>>> verify(b'user-bob', sig)
False
>>> verify(cookie, b'0102030405060708090a0b0c0d0e0f00')
False

Incluso aunque hay un modo de cifrado de claves nativo, BLAKE2 puede, por supuesto, ser usado en construcción de HMAC con el módulo hmac:

>>> import hmac, hashlib
>>> m = hmac.new(b'secret key', digestmod=hashlib.blake2s)
>>> m.update(b'message')
>>> m.hexdigest()
'e3c8102868d28b5ff85fc35dda07329970d1a01e273c37481326fe0c861c8142'

Cifrado aleatorio

Definiendo el parámetro salt los usuarios pueden introducir aleatoriedad a la función hash. El cifrado aleatorio es útil para proteger contra ataques de colisión en la función hash usada en firmas digitales.

El cifrado aleatorio está diseñado para situaciones en las que una parte, el preparador del mensaje, genera todo o parte de un mensaje para ser firmado por una segunda parte, el firmante del mensaje. Si el preparador del mensaje es capaz de encontrar colisiones de funciones hash criptográficas (ej., dos mensajes produciendo el mismo valor de hash), entonces ellos pueden preparar versiones significativas del mensaje que producirían el mismo valor de hash y firma digital, pero con diferentes resultados (ej., transfiriendo 1,000,000 $ a una cuenta, en lugar de 10 $), Las funciones de hash criptográfico han sido diseñadas con resistencia de colisión como objetivo principal, pero la concentración actual en el ataque a las funciones hash criptográficas puede resultar en una función hash criptográfica dada que provea menor resistencia de colisión de la esperada. El cifrado aleatorio ofrece al firmante protección adicional reduciendo la probabilidad de que un preparador puede generar dos o más mensajes que en última instancia producen el mismo valor hash durante el proceso de generación de la firma digital, — incluso si es práctico encontrar colisiones para la función hash. Sin embargo, el uso de cifrado aleatorio puede reducir la cantidad de seguridad provista por una firma digital cuando todas las porciones del mensaje son preparadas por el firmante.

(NIST SP-800-106 «Randomized Hashing for Digital Signatures» [https://csrc.nist.gov/publications/detail/sp/800-106/final])

En BLAKE2 la sal es procesada como una entrada de una vez a la función hash durante la inicialización, en lugar de como una entrada para cada función de compresión.

Advertencia

El cifrado salado (o sólo cifrado) con BLAKE2 o cualquier otra función de hash criptográfico de propósito general, como SHA-256, no son aptas para cifrar contraseñas. Ver BLAKE2 FAQ [https://blake2.net/#qa] para más información.

>>> import os
>>> from hashlib import blake2b
>>> msg = b'some message'
>>> # Calculate the first hash with a random salt.
>>> salt1 = os.urandom(blake2b.SALT_SIZE)
>>> h1 = blake2b(salt=salt1)
>>> h1.update(msg)
>>> # Calculate the second hash with a different random salt.
>>> salt2 = os.urandom(blake2b.SALT_SIZE)
>>> h2 = blake2b(salt=salt2)
>>> h2.update(msg)
>>> # The digests are different.
>>> h1.digest() != h2.digest()
True

Personalización

A veces es útil forzar a la función hash para producir diferentes resúmenes para la misma entrada para diferentes propósitos. Citando a los autores de la función hash Skein:

Recomendamos que todos los diseñadores de aplicaciones consideren seriamente hacer esto; hemos visto muchos protocolos donde un hash que es calculado en una parte del protocolo puede ser usado en una parte completamente diferente porque dos cálculos hash fueron realizados en datos similares o relacionados, y el atacante puede forzar a la aplicación a hacer las entradas hash iguales. Personalizar cada función hash usada en el protocolo resumidamente detiene este tipo de ataque.

(The Skein Hash Function Family [http://www.skein-hash.info/sites/default/files/skein1.3.pdf], p. 21)

BLAKE2 puede ser personalizado pasando bytes al argumento person:

>>> from hashlib import blake2b
>>> FILES_HASH_PERSON = b'MyApp Files Hash'
>>> BLOCK_HASH_PERSON = b'MyApp Block Hash'
>>> h = blake2b(digest_size=32, person=FILES_HASH_PERSON)
>>> h.update(b'the same content')
>>> h.hexdigest()
'20d9cd024d4fb086aae819a1432dd2466de12947831b75c5a30cf2676095d3b4'
>>> h = blake2b(digest_size=32, person=BLOCK_HASH_PERSON)
>>> h.update(b'the same content')
>>> h.hexdigest()
'cf68fb5761b9c44e7878bfb2c4c9aea52264a80b75005e65619778de59f383a3'

Se puede usar también personalización en conjunto con el modo de clave para derivar diferentes claves desde una sola.

>>> from hashlib import blake2s
>>> from base64 import b64decode, b64encode
>>> orig_key = b64decode(b'Rm5EPJai72qcK3RGBpW3vPNfZy5OZothY+kHY6h21KM=')
>>> enc_key = blake2s(key=orig_key, person=b'kEncrypt').digest()
>>> mac_key = blake2s(key=orig_key, person=b'kMAC').digest()
>>> print(b64encode(enc_key).decode('utf-8'))
rbPb15S/Z9t+agffno5wuhB77VbRi6F9Iv2qIxU7WHw=
>>> print(b64encode(mac_key).decode('utf-8'))
G9GtHFE1YluXY1zWPlYk1e/nWfu0WSEb0KRcjhDeP/o=

Modo de árbol

Aquí hay un ejemplo de cifrar un árbol mínimo con dos nodos de hoja:

  10
 /  \
00  01

Este ejemplo usa resúmenes internos de 64 bytes, y retorna el resumen final de 32 bytes:

>>> from hashlib import blake2b
>>>
>>> FANOUT = 2
>>> DEPTH = 2
>>> LEAF_SIZE = 4096
>>> INNER_SIZE = 64
>>>
>>> buf = bytearray(6000)
>>>
>>> # Left leaf
... h00 = blake2b(buf[0:LEAF_SIZE], fanout=FANOUT, depth=DEPTH,
...               leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,
...               node_offset=0, node_depth=0, last_node=False)
>>> # Right leaf
... h01 = blake2b(buf[LEAF_SIZE:], fanout=FANOUT, depth=DEPTH,
...               leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,
...               node_offset=1, node_depth=0, last_node=True)
>>> # Root node
... h10 = blake2b(digest_size=32, fanout=FANOUT, depth=DEPTH,
...               leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,
...               node_offset=0, node_depth=1, last_node=True)
>>> h10.update(h00.digest())
>>> h10.update(h01.digest())
>>> h10.hexdigest()
'3ad2a9b37c6070e374c7a8c508fe20ca86b6ed54e286e93a0318e95e881db5aa'

Créditos

BLAKE2 [https://blake2.net] fue diseñado por Jean-Philippe Aumasson, Samuel Neves, Zooko Wilcox-O’Hearn y Christian Winnerlein basado en el SHA-3 [https://en.wikipedia.org/wiki/NIST_hash_function_competition] finalista BLAKE [https://131002.net/blake/] creado por Jean-Philippe Aumasson, Luca Henzen, Willi Meier y Raphael C.-W. Phan.

Usa el algoritmo núcleo del cifrado ChaCha [https://cr.yp.to/chacha.html] diseñado por Daniel J. Bernstein.

La implementación stdlib está basada en el módulo pyblake2 [https://pythonhosted.org/pyblake2/]. Fue escrita por Dmitry Chestnykh basada en la implementación C escrita por Samuel Neves. La documentación fue copiada desde pyblake2 [https://pythonhosted.org/pyblake2/] y escrita por Dmitry Chestnykh.

El código C fue parcialmente reescrito para Python por Christian Heimes.

La siguiente dedicación de dominio público aplica tanto para la implementación de la función hash C, el código de extensión y su documentación:

En la medida en que la ley lo permite, el/los autor/es han dedicado todos los derechos de autor y los derechos relacionados y vecinos de este software al dominio público mundial. Este software se distribuye sin ninguna garantía.

Deberías haber recibido una copia de la Dedicación CC0 de Dominio Público junto a este software. Si no, consulta https://creativecommons.org/publicdomain/zero/1.0/.

Las siguientes personas han ayudado con el desarrollo o contribuyeron con sus cambios al proyecto y el dominio público de acuerdo a Creative Commons Public Domain Dedication 1.0 Universal:

Alexandr Sokolovskiy

Ver también

Módulo hmac

Un módulo para generar mensajes de códigos de autentificación usando hashes.

Módulo base64

Otra forma de codificar hashes binarios para entornos no binarios.

https://blake2.net

Sitio web oficial de BLAKE2.

https://csrc.nist.gov/csrc/media/publications/fips/180/2/archive/2002-08-01/documents/fips180-2.pdf

La publicación FIPS 180-2 sobre Algoritmos de Cifrado Seguros.

https://en.wikipedia.org/wiki/Cryptographic_hash_function#Cryptographic_hash_algorithms

Artículo de Wikipedia con información sobre cuáles algoritmos tienen errores conocidos y lo que eso significa con respecto a su uso.

https://www.ietf.org/rfc/rfc2898.txt

PKCS #5: Password-Based Cryptography Specification Version 2.0

hmac — Hash con clave para autenticación de mensajes

Código fuente: Lib/hmac.py [https://github.com/python/cpython/tree/3.9/Lib/hmac.py]

Este módulo implementa el algoritmo HMAC como se describe en la RFC 2104 [https://tools.ietf.org/html/rfc2104.html].

hmac.new(key, msg=None, digestmod='')

Retorna un nuevo objeto hmac. key es un objeto bytes o bytearray que proporciona la clave secreta. Si msg está presente, se realiza la llamada al método update(msg). digestmod es el nombre del resumen, constructor o módulo del resumen para el objeto HMAC que se va a usar. Puede ser cualquier nombre adecuado para hashlib.new(). Se requiere este argumento a pesar de su posición.

Distinto en la versión 3.4: El parámetro key puede ser un objeto bytes o bytearray. El parámetro msg puede ser de cualquier tipo soportado por hashlib. El parámetro digestmod puede ser el nombre del algoritmo de hash.

Deprecated since version 3.4, removed in version 3.8: MD5 como resumen por defecto implícito para digestmod está obsoleto. Ahora se requiere el parámetro digestmod. Páselo como un argumento de palabra clave para evitar dificultades cuando no tiene un msg inicial.

hmac.digest(key, msg, digest)

Retorna el resumen de msg para una clave key secreta y un resumen digest dados. La función es equivalente a HMAC(key, msg, digest).digest(), pero utiliza una implementación optimizada en C o inline, que es más rápida para mensajes que caben en memoria. Los parámetros key, msg y digest tienen el mismo significado que en new().

Un detalle de la implementación de CPython: la implementación optimizada en C solo se usa cuando digest es una cadena de caracteres y el nombre de un algoritmo de resumen, que está soportado por OpenSSL.

Nuevo en la versión 3.7.

Un objeto HMAC tiene los siguientes métodos:

HMAC.update(msg)

Actualiza el objeto hmac con msg. Las llamadas repetidas equivalen a una sola llamada con la concatenación de todos los argumentos: m.update(a); m.update(b) es equivalente a m.update(a + b).

Distinto en la versión 3.4: El parámetro msg puede ser de cualquier tipo soportado por hashlib.

HMAC.digest()

Retorna el resumen de los bytes que se pasaron al método update() hasta el momento. Este objeto bytes será de la misma longitud que el digest_size del resumen que se pasa al constructor. Puede contener bytes no ASCII, incluyendo bytes NUL.

Advertencia

Cuando se compara la salida de digest() a un resumen provisto externamente durante una rutina de verificación, se recomienda utilizar la función compare_digest() en lugar del operador == para reducir la vulnerabilidad a ataques de temporización.

HMAC.hexdigest()

Como digest() excepto que el resumen se retorna como una cadena de caracteres de dos veces la longitud conteniendo solo dígitos hexadecimales. Esto se puede utilizar para intercambiar el valor de forma segura en email u otros entornos no binarios.

Advertencia

Cuando se compara la salida de hexdigest() a un resumen provisto externamente durante una rutina de verificación, se recomienda utilizar la función compare_digest() en lugar del operador == para reducir la vulnerabilidad a ataques de temporización.

HMAC.copy()

Retorna una copia («clon») del objeto hmac. Esto se puede utilizar para calcular de forma eficiente los resúmenes de las cadenas de caracteres que comparten una subcadena de caracteres inicial común.

Un objeto hash tiene los siguientes atributos:

HMAC.digest_size

El tamaño del resumen HMAC resultante en bytes.

HMAC.block_size

El tamaño de bloque interno del algoritmo de hash en bytes.

Nuevo en la versión 3.4.

HMAC.name

El nombre canónico de este HMAC, siempre en minúsculas, por ejemplo hmac-md5.

Nuevo en la versión 3.4.

Obsoleto desde la versión 3.9: Los atributos no documentados HMAC.digest_cons, HMAC.inner y HMAC.outer son detalles de implementación interna y se eliminarán en Python 3.10.

Este módulo también provee las siguiente funciones auxiliares:

hmac.compare_digest(a, b)

Retorna a == b. Esta función utiliza un enfoque diseñado para prevenir el análisis de temporización evitando el comportamiento de cortocircuito basado en contenido, haciéndolo adecuado para criptografía. a y b deben ser del mismo tipo: ya sea str (solo ASCII, como por ejemplo retornado por HMAC.hexdigest()), o un objeto tipo binario.

Nota

Si a y b son de diferente longitud, o si ocurre un error, un ataque de temporización teóricamente podría revelar información sobre los tipos y longitudes de a y b—pero no sus valores.

Nuevo en la versión 3.3.

Distinto en la versión 3.9: La función utiliza CRYPTO_memcmp() de OpenSSL internamente cuando está disponible.

Ver también

Módulo hashlib

El módulo de Python que provee funciones de hash seguras.

secrets — Genera números aleatorios seguros para trabajar con secretos criptográficos

Nuevo en la versión 3.6.

Código fuente: Lib/secrets.py [https://github.com/python/cpython/tree/3.9/Lib/secrets.py]

El módulo secrets se usa para generar números aleatorios criptográficamente fuertes, apropiados para trabajar con datos como contraseñas, autenticación de cuentas, tokens de seguridad y secretos relacionados.

En particular, secrets se debe usar en lugar del generador de números pseudoaleatorios del módulo random, que está diseñado para el modelado y la simulación, no para la seguridad o la criptografía.

Ver también

PEP 506 [https://www.python.org/dev/peps/pep-0506]

Números aleatorios

El módulo secrets provee acceso a la fuente más segura de aleatoriedad que proporciona su sistema operativo.

class secrets.SystemRandom

Una clase para generar números aleatorios utilizando las fuentes de mayor calidad que proporciona el sistema operativo. Ver random.SystemRandom para más detalles.

secrets.choice(sequence)

Retorna un elemento aleatorio de una secuencia no vacía.

secrets.randbelow(n)

Retorna un entero aleatorio en el rango [0, n).

secrets.randbits(k)

Retorna un entero con k bits aleatorios.

Generando tokens

El módulo secrets provee funciones para generar tokens seguros, adecuados para aplicaciones como el restablecimiento de contraseñas, URLs difíciles de adivinar, y similares.

secrets.token_bytes([nbytes=None])

Retorna una cadena de bytes aleatorios que contiene nbytes número de bytes. Si nbytes es None o no se suministra, se utiliza un valor por defecto razonable.

>>> token_bytes(16)
b'\xebr\x17D*t\xae\xd4\xe3S\xb6\xe2\xebP1\x8b'

secrets.token_hex([nbytes=None])

Retorna una cadena de caracteres aleatoria, en hexadecimal. La cadena de caracteres tiene nbytes bytes aleatorios, cada byte convertido a dos dígitos hexadecimales. Si nbytes es None o no se suministra, se utiliza un valor por defecto razonable.

>>> token_hex(16)
'f9bf78b9a18ce6d46a0cd2b0b86df9da'

secrets.token_urlsafe([nbytes=None])

Retorna una cadena de caracteres aleatoria para usarse en URLs, que contiene nbytes bytes aleatorios. El texto está codificado en Base64, por lo que en promedio cada byte resulta en aproximadamente 1,3 caracteres. Si nbytes es None o no se suministra, se utiliza un valor por defecto razonable.

>>> token_urlsafe(16)
'Drmhze6EPcv0fN_81Bj-nA'

¿Cuántos bytes deben tener los tokens?

Para estar seguros contra los ataques de fuerza bruta [https://es.wikipedia.org/wiki/Ataque_de_fuerza_bruta], los tokens deben tener suficiente aleatoriedad. Desafortunadamente, lo que es considerado suficiente necesariamente aumentará a medida que las computadoras se vuelvan más potentes y capaces de hacer más pruebas en un período más corto. Desde 2015 se cree que 32 bytes (256 bits) de aleatoriedad son considerados suficientes para el típico caso de uso del módulo secrets.

Para quienes quieran gestionar la longitud de sus propios tokens, pueden especificar explícitamente cuánta aleatoriedad se utiliza para los tokens dando un argumento int a las funciones token_*. Ese argumento se toma como el número de bytes de aleatoriedad a utilizar.

En caso contrario, si no se proporciona ningún argumento, o si el argumento es None, las funciones token_* utilizarán en su lugar un valor por defecto razonable.

Nota

El valor por defecto está sujeto a cambios en cualquier momento, incluso en los lanzamientos de mantenimiento.

Otras funciones

secrets.compare_digest(a, b)

Retorna True si las cadenas de caracteres a y b son iguales, de lo contrario, False, de forma tal que se reduzca el riesgo de ataques de análisis temporal [https://codahale.com/a-lesson-in-timing-attacks/]. Ver hmac.compare_digest`() para detalles adicionales.

Recetas y mejores prácticas

Esta sección muestra las recetas y las mejores prácticas para usar secrets para conseguir un nivel mínimo de seguridad.

Generar una contraseña alfanumérica de ocho caracteres:

import string
import secrets
alphabet = string.ascii_letters + string.digits
password = ''.join(secrets.choice(alphabet) for i in range(8))

Nota

Las aplicaciones no deben almacenar contraseñas en un formato recuperable [http://cwe.mitre.org/data/definitions/257.html], ya sea en texto plano o encriptado. Deberían ser saladas y hasheadas usando una función hash unidireccional (irreversible) y criptográficamente fuerte.

Generar una contraseña alfanumérica de diez caracteres con al menos un carácter en minúscula, al menos un carácter en mayúscula y al menos tres dígitos:

import string
import secrets
alphabet = string.ascii_letters + string.digits
while True:
    password = ''.join(secrets.choice(alphabet) for i in range(10))
    if (any(c.islower() for c in password)
            and any(c.isupper() for c in password)
            and sum(c.isdigit() for c in password) >= 3):
        break

Generar una contraseña al estilo XKCD [https://xkcd.com/936/]:

import secrets
# On standard Linux systems, use a convenient dictionary file.
# Other platforms may need to provide their own word-list.
with open('/usr/share/dict/words') as f:
    words = [word.strip() for word in f]
    password = ' '.join(secrets.choice(words) for i in range(4))

Generar una URL temporal difícil de adivinar que contenga un token de seguridad adecuado para la recuperación de contraseñas:

import secrets
url = 'https://example.com/reset=' + secrets.token_urlsafe()

Servicios genéricos del sistema operativo

Los módulos descritos en este capítulo proporcionan interfaces a las características del sistema operativo que están disponibles en (casi) todos los sistemas operativos, como archivos y un reloj. Las interfaces se modelan, por norma general, según las interfaces Unix o C, pero también están disponibles en la mayoría de los otros sistemas. Esta es una visión general:

os — Interfaces misceláneas del sistema operativo

Nombres de archivos, argumentos de la línea de comandos y variables de entorno

Parámetros de proceso

Creación de objetos de tipo archivo

Operaciones de descriptores de archivos

Consultando las dimensiones de una terminal

Herencia de los descriptores de archivos

Archivos y directorios

Atributos extendidos de Linux

Gestión de proceso

Interfaz al planificador

Información miscelánea del sistema

Números al azar

io — Herramientas principales para trabajar con streams

Resumen

E/S Texto

E/S Binaria

E/S sin formato

Interfaz de módulo de alto nivel

Jerarquía de clases

Clases base E/S

Archivo sin formato E/S

Streams almacenados (búfer)

E/S Texto

Rendimiento

E/S Binaria

E/S Texto

Multihilo

Reentrada

time — Tiempo de acceso y conversiones

Las Funciones

Constantes de ID de reloj

Constantes de zona horaria

argparse — Analizador sintáctico (Parser) para las opciones, argumentos y sub-comandos de la línea de comandos

Ejemplo

Creando un analizador sintáctico (parser)

Añadiendo argumentos

Analizando argumentos

Objetos ArgumentParser

prog

uso

description

epilog

parents

formatter_class

prefix_chars

fromfile_prefix_chars

argument_default

allow_abbrev

conflict_handler

add_help

exit_on_error

El método add_argument()

name or flags

action

nargs

const

default

type

choices

required

help

metavar

dest

Las clases Action

El método parse_args()

Sintaxis del valor de la opción

Argumentos no válidos

Argumentos conteniendo -

Abreviaturas de los argumentos (coincidencia de prefijos)

Más allá de sys.argv

El objeto Namespace

Otras utilidades

Sub-comandos

Objetos FileType

Grupos de argumentos

Exclusión mutua

Valores por defecto del analizador

Mostrando la ayuda

Análisis parcial

Personalizando el análisis de archivos

Métodos de salida

Análisis entremezclado

Actualizar el código de optparse

getopt — Analizador de estilo C para opciones de línea de comando

logging — Instalación de logging para Python

Objetos Logger

Niveles de logging

Gestor de objetos

Objetos formateadores

Filtro de Objetos

Objetos LogRecord

Atributos LogRecord

Objetos LoggerAdapter

Seguridad del hilo

Funciones a nivel de módulo

Atributos a nivel de módulo

Integración con el módulo de advertencias

logging.config — Configuración de registro

Funciones de configuración

Security considerations

Esquema del diccionario de configuración

Detalles del esquema del diccionario

Configuración incremental

Conexiones de objeto

Objetos definidos por el usuario

Acceso a objetos externos

Acceso a objetos internos

Resolución de importación e importadores personalizados

Formato de archivo de configuración

logging.handlers — Gestores de logging

StreamHandler

FileHandler

NullHandler

WatchedFileHandler

BaseRotatingHandler

RotatingFileHandler

TimedRotatingFileHandler

SocketHandler

DatagramHandler

Gestor SysLog (SysLogHandler)

Gestor de eventos NTELog (NTEventLogHandler)

SMTPHandler

MemoryHandler

HTTPHandler

QueueHandler

QueueListener

getpass — Entrada de contraseña portátil

curses — Manejo de terminales para pantallas de celdas de caracteres

Funciones

Objetos de ventana

Constantes

curses.textpad— Widget de entrada de texto para programas de curses

Objeto de caja de texto

curses.ascii — Utilidades para los caracteres ASCII

curses.panel — Una extensión de pila de panel para curses

Funciones

Objetos de Panel

platform — Acceso a los datos identificativos de la plataforma subyacente

Plataforma cruzada

Plataforma Java

Plataforma windows

macOS Platform

Plataformas Unix

errno — Símbolos estándar del sistema errno

ctypes — Una biblioteca de funciones foráneas para Python

tutorial de ctypes

Carga de bibliotecas de enlaces dinámicos

Acceder a las funciones de los dll cargados

Funciones de llamada

Tipos de datos fundamentales

Funciones de llamada, continuación

Funciones de llamada con sus propios tipos de datos personalizados

Especificar los tipos de argumentos requeridos (prototipos de funciones)

Tipos de retorno

Pasar los punteros (o: pasar los parámetros por referencia)

Estructuras y uniones

Alineación de estructura/unión y orden de bytes

Campos de bits en estructuras y uniones

Arreglos

Punteros

Conversiones de tipos

Tipos incompletos

Funciones de retrollamadas (callback)

Acceder a los valores exportados de los dlls

Sorpresas

Tipos de datos de tamaño variable

referencia ctypes

Encontrar bibliotecas compartidas

Cargando bibliotecas compartidas

Funciones foráneas

Prototipos de funciones

Funciones de utilidad

Tipos de datos

Tipos de datos fundamentales

Tipos de datos estructurados

Arreglos y punteros

os — Interfaces misceláneas del sistema operativo

Código fuente: Lib/os.py [https://github.com/python/cpython/tree/3.9/Lib/os.py]

Este módulo provee una manera versátil de usar funcionalidades dependientes del sistema operativo. Si quieres leer o escribir un archivo mira open(), si quieres manipular rutas, mira el módulo os.path, y si quieres leer todas las líneas en todos los archivos en la línea de comandos mira el módulo fileinput. Para crear archivos temporales y directorios mira el módulo tempfile, y para el manejo de alto nivel de archivos y directorios puedes ver el módulo shutil.

Notas sobre la disponibilidad de estas funciones:

El diseño de todos los módulos incorporados de Python dependientes del sistema operativo es tal que, mientras funcionalidad esté disponible, usará la misma interfaz; por ejemplo, la función os.stat(path) retorna estadísticas sobre la ruta (path) en el mismo formato (lo que sucede originalmente con la interfaz POSIX).

Las extensiones propias de un sistema operativo en particular también están disponibles a través del módulo os, pero usarlas, por supuesto, es un riesgo a la portabilidad.

Todas las funciones que aceptan rutas o nombres de archivos aceptan bytes o cadenas de texto, y el resultado es un objeto del mismo tipo, siempre que se retorna una ruta o un archivo.

En VxWorks, no están soportados os.fork, os.execv y os.spawn*p*.

Nota

Todas las funciones en este módulo lanzan OSError (o subclases), en el caso de archivos o rutas inaccesibles o inválidas, u otros argumentos que tienen el tipo correcto, pero que no son aceptados por el sistema operativo.

exception os.error

Un alias de la excepción incorporada OSError.

os.name

El nombre del módulo dependiente del sistema operativo importado. Los siguientes nombres están registrados: 'posix', 'nt', 'java'.

Ver también

sys.platform tiene un mayor nivel de detalle. os.uname() proporciona información de la versión dependiendo del sistema operativo.

El módulo platform proporciona verificaciones detalladas de la identidad del sistema.

Nombres de archivos, argumentos de la línea de comandos y variables de entorno

En Python, los nombres de archivo, los argumentos de la línea de comandos y las variables de entorno están representados usando cadena de caracteres. En algunos sistemas, decodificar esas cadenas desde y hacia bytes es necesario para pasárselos al sistema operativo. Python usa la codificación del sistema operativo para realizar esta conversión (ver sys.getfilesystemencoding()).

Distinto en la versión 3.1: En algunos sistemas, la conversión usando la codificación del sistema de archivos puede fallar. En este caso, Python usa el controlador de error de codificación de *subrogateescape*, lo que significa que los bytes no codificables se reemplazan por un carácter Unicode U + DCxx en la decodificación, y estos se traducen nuevamente al byte original en la codificación.

La codificación del sistema de archivos debe garantizar la decodificación exitosa de todos los bytes por debajo de 128. Si la codificación del sistema de archivos no proporciona esta garantía, las funciones de la API pueden generar errores Unicode.

Parámetros de proceso

Estas funciones y elementos de datos proporcionan información y operan en el proceso y con el usuario actuales.

os.ctermid()

Retorna el nombre del archivo correspondiente al terminal que controla el proceso.

Disponibilidad: Unix.

os.environ

A mapping object where keys and values are strings that represent the process environment. For example, environ['HOME'] is the pathname of your home directory (on some platforms), and is equivalent to getenv("HOME") in C.

This mapping is captured the first time the os module is imported, typically during Python startup as part of processing site.py. Changes to the environment made after this time are not reflected in os.environ, except for changes made by modifying os.environ directly.

Este mapeo puede ser usado para modificar el entorno y también para consultarlo. putenv() será llamado automáticamente cuando el mapeo sea modificado.

En Unix, claves y valores usan la función sys.getfilesystemencoding() y el controlador de errores 'surrogateescape'. Hay que utilizar environb si se quiere usar una codificación diferente.

Nota

Calling putenv() directly does not change os.environ, so it’s better to modify os.environ.

Nota

On some platforms, including FreeBSD and macOS, setting environ may cause memory leaks. Refer to the system documentation for putenv().

You can delete items in this mapping to unset environment variables. unsetenv() will be called automatically when an item is deleted from os.environ, and when one of the pop() or clear() methods is called.

Distinto en la versión 3.9: Actualizado para soportar los operadores merge (|) y update (|=) de PEP 584 [https://www.python.org/dev/peps/pep-0584]’s.

os.environb

Bytes version of environ: a mapping object where both keys and values are bytes objects representing the process environment. environ and environb are synchronized (modifying environb updates environ, and vice versa).

environb está disponible sólo si supports_bytes_environ está establecido en True.

Nuevo en la versión 3.2.

Distinto en la versión 3.9: Actualizado para soportar los operadores merge (|) y update (|=) de PEP 584 [https://www.python.org/dev/peps/pep-0584]’s.

os.chdir(path)

os.fchdir(fd)

os.getcwd()

Estas funciones están detalladas en Archivos y directorios.

os.fsencode(filename)

Codifica un nombre de archivo tipo ruta con la codificación del sistema de archivos usando el controlador de errores 'surrogateescape', o 'strict' en Windows; retorna bytes sin alterar.

fsdecode() es la función inversa.

Nuevo en la versión 3.2.

Distinto en la versión 3.6: Soporte agregado para aceptar objetos que implementan una interfaz os.PathLike.

os.fsdecode(filename)

Decodifica un nombre de archivo tipo ruta desde la codificación del sistema de archivos usando el controlador de errores 'surrogateescape', o 'strict' en Windows; retorna str sin alterar.

fsencode() es la función inversa.

Nuevo en la versión 3.2.

Distinto en la versión 3.6: Soporte agregado para aceptar objetos que implementan una interfaz os.PathLike.

os.fspath(path)

Retorna la representación en el sistema de archivos de la ruta.

Si se le pasa str o bytes, retorna sin alterar. De lo contrario se llama a __fspath__() y se retorna su valor siempre que sea un objeto str o bytes. En los demás casos se lanza una excepción del tipo TypeError.

Nuevo en la versión 3.6.

class os.PathLike

Una clase base abstracta para objetos que representan una ruta del sistema de archivos, i.e. pathlib.PurePath.

Nuevo en la versión 3.6.

abstractmethod __fspath__()

Retorna la representación de la ruta del sistema de archivos del objeto.

Este método sólo retornará objetos str or bytes, preferentemente str.

os.getenv(key, default=None)

Return the value of the environment variable key if it exists, or default if it doesn’t. key, default and the result are str. Note that since getenv() uses os.environ, the mapping of getenv() is similarly also captured on import, and the function may not reflect future environment changes.

En Unix, claves y valores se decodifican con la función sys.getfilesystemencoding() y con el controlador de errores 'surrogateescape'. Usar os.getenvb() si se quiere usar una codificación diferente.

Disponibilidad: sistemas tipo Unix, Windows.

os.getenvb(key, default=None)

Return the value of the environment variable key if it exists, or default if it doesn’t. key, default and the result are bytes. Note that since getenvb() uses os.environb, the mapping of getenvb() is similarly also captured on import, and the function may not reflect future environment changes.

getenvb() está disponible sólo si supports_bytes_environ está establecido en True.

Disponibilidad: sistemas tipo Unix.

Nuevo en la versión 3.2.

os.get_exec_path(env=None)

Retorna una lista de directorios en la que se buscará un ejecutable, similar a una shell, cuando se ejecuta un proceso. env, cuando se especifica, tienen que ser un diccionario de variables de entorno donde buscar el PATH. Por defecto cuando env es None, se usa environ.

Nuevo en la versión 3.2.

os.getegid()

Retorna el id del grupo (gid) efectivo correspondiente al proceso que se está ejecutando. Esto corresponde al bit de «set id» en el archivo que se está ejecutando en el proceso actual.

Disponibilidad: Unix.

os.geteuid()

Retorna el id el usuario correspondiente al proceso que se está ejecutando actualmente.

Disponibilidad: Unix.

os.getgid()

Retorna el id del grupo real correspondiente al proceso que se está ejecutando actualmente.

Disponibilidad: Unix.

os.getgrouplist(user, group)

Return list of group ids that user belongs to. If group is not in the list, it is included; typically, group is specified as the group ID field from the password record for user, because that group ID will otherwise be potentially omitted.

Disponibilidad: Unix.

Nuevo en la versión 3.3.

os.getgroups()

Retorna la lista de ids de grupos secundarios asociados con el proceso actual.

Disponibilidad: Unix.

Nota

On macOS, getgroups() behavior differs somewhat from other Unix platforms. If the Python interpreter was built with a deployment target of 10.5 or earlier, getgroups() returns the list of effective group ids associated with the current user process; this list is limited to a system-defined number of entries, typically 16, and may be modified by calls to setgroups() if suitably privileged. If built with a deployment target greater than 10.5, getgroups() returns the current group access list for the user associated with the effective user id of the process; the group access list may change over the lifetime of the process, it is not affected by calls to setgroups(), and its length is not limited to 16. The deployment target value, MACOSX_DEPLOYMENT_TARGET, can be obtained with sysconfig.get_config_var().

os.getlogin()

Retorna el nombre del usuario que inició sesión en el terminal que controla el proceso. Para la mayoría de los casos, es más útil usar getpass.getuser() ya que este último verifica las variables de entorno LOGNAME o USERNAME para averiguar quién es el usuario y recurre a pwd.getpwuid(os.getuid())[0] para obtener el nombre de inicio de sesión del ID de usuario real actual.

Disponibilidad: Unix, Windows.

os.getpgid(pid)

Retorna el id del grupo de procesos del proceso con la identificación del proceso pid. Si pid es 0, se retorna la identificación del grupo de proceso del proceso actual.

Disponibilidad: Unix.

os.getpgrp()

Retorna el id del grupo de proceso actual.

Disponibilidad: Unix.

os.getpid()

Retorna el id del proceso actual.

os.getppid()

Retorna el id del proceso del padre. Cuando el proceso padre ha terminado, en Unix la identificación que retorna es la del proceso init (1), en Windows sigue siendo la misma identificación, que ya puede ser reutilizada por otro proceso.

Disponibilidad: Unix, Windows.

Distinto en la versión 3.2: Se agregó soporte para Windows.

os.getpriority(which, who)

Obtenga la prioridad del programa. El valor which es uno de PRIO_PROCESS, PRIO_PGRP, o PRIO_USER, y who se interpreta en relación a which (un identificador de proceso para PRIO_PROCESS, un identificador de grupo de proceso para PRIO_PGRP, y un ID de usuario para PRIO_USER). Un valor cero para who denota (respectivamente) el proceso llamado, el grupo de proceso del proceso llamado o el ID de usuario real del proceso llamado.

Disponibilidad: Unix.

Nuevo en la versión 3.3.

os.PRIO_PROCESS

os.PRIO_PGRP

os.PRIO_USER

Parámetros para las funciones getpriority() y setpriority().

Disponibilidad: Unix.

Nuevo en la versión 3.3.

os.getresuid()

Retorna una tupla (ruid, euid, suid) que denota los ID de usuario reales, efectivos y guardados del proceso actual.

Disponibilidad: Unix.

Nuevo en la versión 3.2.

os.getresgid()

Retorna una tupla (rgid, egid, sgid) que denota los ID de grupo reales, efectivos y guardados del proceso actual.

Disponibilidad: Unix.

Nuevo en la versión 3.2.

os.getuid()

Retorna el id del usuario real del proceso actual.

Disponibilidad: Unix.

os.initgroups(username, gid)

Llamada al sistema initgroups() para inicializar la lista de acceso de grupo con todos los grupos de los que es miembro el nombre de usuario especificado, más el ID del grupo especificado.

Disponibilidad: Unix.

Nuevo en la versión 3.2.

os.putenv(key, value)

Establece la variable de entorno llamada key con el valor de la cadena value. Dichos cambios en el entorno impactan a los subprocesos iniciados con os.system(), popen() o fork() y execv().

Assignments to items in os.environ are automatically translated into corresponding calls to putenv(); however, calls to putenv() don’t update os.environ, so it is actually preferable to assign to items of os.environ. This also applies to getenv() and getenvb(), which respectively use os.environ and os.environb in their implementations.

Nota

On some platforms, including FreeBSD and macOS, setting environ may cause memory leaks. Refer to the system documentation for putenv().

Lanza un evento de auditoría os.putenv con argumentos key, value.

Distinto en la versión 3.9: Esta función actualmente siempre esta disponible.

os.setegid(egid)

Establece el id de grupo efectivo del proceso actual.

Disponibilidad: Unix.

os.seteuid(euid)

Establece el id de usuario efectivo del proceso actual.

Disponibilidad: Unix.

os.setgid(gid)

Establece el id de grupo del proceso actual.

Disponibilidad: Unix.

os.setgroups(groups)

Establece la lista de ids de grupos secundarios asociados con el proceso actual en groups. groups debe ser una secuencia y cada elemento debe ser un número entero que identifique un grupo. Esta operación generalmente está disponible sólo para el superusuario.

Disponibilidad: Unix.

Nota

On macOS, the length of groups may not exceed the system-defined maximum number of effective group ids, typically 16. See the documentation for getgroups() for cases where it may not return the same group list set by calling setgroups().

os.setpgrp()

Invoca a la llamada de sistema setpgrp() o setpgrp(0, 0) dependiendo de la versión que se implemente (si la hay). Vea el manual de Unix para la semántica.

Disponibilidad: Unix.

os.setpgid(pid, pgrp)

Invoca a la llamada de sistema setpgid() para establecer la identificación del grupo de procesos del id del proceso como pid al grupo de procesos con id pgrp. Vea el manual de Unix para la semántica.

Disponibilidad: Unix.

os.setpriority(which, who, priority)

Establecer la prioridad del programa. El valor which es uno de PRIO_PROCESS, PRIO_PGRP, o PRIO_USER, y who se interpreta en relación con which (un identificador de proceso para PRIO_PROCESS, un identificador de grupo de proceso para PRIO_PGRP, y un ID de usuario para PRIO_USER). Un valor cero para who denota (respectivamente) el proceso llamado, el grupo de procesos del proceso llamado o el ID del usuario real del proceso llamado. priority es un valor en el rango de -20 a 19. La prioridad predeterminada es 0; las prioridades más bajas causan una programación más favorable.

Disponibilidad: Unix.

Nuevo en la versión 3.3.

os.setregid(rgid, egid)

Establece los ids de grupos reales y efectivos del proceso actual.

Disponibilidad: Unix.

os.setresgid(rgid, egid, sgid)

Establece los ids de grupo reales, efectivos y guardados del proceso actual.

Disponibilidad: Unix.

Nuevo en la versión 3.2.

os.setresuid(ruid, euid, suid)

Establece los ids de usuario reales, efectivos y guardados del proceso actual.

Disponibilidad: Unix.

Nuevo en la versión 3.2.

os.setreuid(ruid, euid)

Establece los ids de usuario reales y efectivos del proceso actual.

Disponibilidad: Unix.

os.getsid(pid)

Invoca a la llamada de sistema getsid(). Vea el manual de Unix para la semántica.

Disponibilidad: Unix.

os.setsid()

Invoca a la llamada de sistema setsid(). Vea el manual de Unix para la semántica.

Disponibilidad: Unix.

os.setuid(uid)

Establece id del usuario del proceso actual.

Disponibilidad: Unix.

os.strerror(code)

Retorna el mensaje de error correspondiente al código de error en code. En plataformas donde strerror() retorna NULL cuando se le da un número de error desconocido lanza un ValueError.

os.supports_bytes_environ

True si el tipo de entorno nativo del sistema operativo es bytes (por ejemplo, False en Windows).

Nuevo en la versión 3.2.

os.umask(mask)

Establece la umask numérica actual y retorna la umask anterior.

os.uname()

Retorna información que identifica el sistema operativo actual. El valor retornado es un objeto con cinco atributos:

sysname - nombre del sistema operativo

nodename - nombre de la máquina en la red (definida por la implementación)

release - release del sistema operativo

version - versión del sistema operativo

machine - identificador de hardware

Por compatibilidad con versiones anteriores, este objeto también es iterable, se comporta como una tupla que contiene sysname, nodename, release, version, y machine en ese orden.

Algunos sistemas se truncan nodename a 8 caracteres o al componente principal; una mejor manera de obtener el nombre de host es usar socket.gethostname() o incluso socket.gethostbyaddr(socket.gethostname()).

Disponibilidad: sistemas tipo Unix más nuevos.

Distinto en la versión 3.3: El tipo de objeto retornado cambió de una tupla a un objeto tipo tupla con atributos con nombre.

os.unsetenv(key)

Desestablece (elimine) la variable de entorno llamada key. Dichos cambios en el entorno afectan a los subprocesos iniciados con os.system(), popen() o fork() y execv().

Deletion of items in os.environ is automatically translated into a corresponding call to unsetenv(); however, calls to unsetenv() don’t update os.environ, so it is actually preferable to delete items of os.environ.

Lanza un evento de auditoría os.unsetenv con argumento key.

Distinto en la versión 3.9: Estas funciones se encuentra ahora siempre disponible y también esta disponible en Windows

Creación de objetos de tipo archivo

Estas funciones crean nuevos objetos de archivo. (Consulte también open() para abrir los descriptores de archivos).

os.fdopen(fd, *args, **kwargs)

Retorna un objeto de archivo abierto conectado al descriptor de archivo fd. Este es un alias de la función incorporada open() y acepta los mismos argumentos. La única diferencia es que el primer argumento de fdopen() siempre debe ser un número entero.

Operaciones de descriptores de archivos

Estas funciones operan en flujos de E/S a los que se hace referencia mediante descriptores de archivo.

Los descriptores de archivo son enteros pequeños que corresponden a un archivo que ha sido abierto por el proceso actual. Por ejemplo, la entrada estándar suele ser el descriptor de archivo 0, la salida estándar es el 1 y el error estándar es el 2. A los archivos abiertos por un proceso se les asignará 3, 4, 5, y así sucesivamente. El nombre «descriptor de archivo» es ligeramente engañoso; en las plataformas Unix, los descriptores de archivo también hacen referencia a sockets y tuberías.

El método fileno() se puede utilizar para obtener el descriptor de archivo asociado con un file object cuando sea necesario. Tenga en cuenta que el uso del descriptor de archivo directamente omitirá los métodos de objeto de archivo, ignorando aspectos como el almacenamiento interno interno de datos.

os.close(fd)

Cierra el descriptor de archivo fd.

Nota

Esta función está diseñada para E/S de bajo nivel y debe aplicarse a un descriptor de archivo tal como lo retorna os.open() o pipe(). Para cerrar un «objeto de archivo» retornado por la función incorporada open() o por popen() o fdopen(), use el método close().

os.closerange(fd_low, fd_high)

Cierra todos los descriptores de archivo desde fd_low (inclusive) hasta fd_high (exclusivo), ignorando los errores. Equivalente a (pero mucho más rápido que):

for fd in range(fd_low, fd_high):
    try:
        os.close(fd)
    except OSError:
        pass

os.copy_file_range(src, dst, count, offset_src=None, offset_dst=None)

Copia count bytes del descriptor de archivo src, comenzando desde offset offset_src, al descriptor de archivo dst, comenzando desde offset offset_dst. Si offset_src es None, entonces src se lee desde la posición actual; respectivamente para offset_dst. Los archivos señalados por src y dst deben estar en el mismo sistema de archivos; de lo contrario, se genera una OSError con errno establecido en errno.EXDEV.

Esta copia se realiza sin el costo adicional de transferir datos desde el kernel al espacio del usuario y luego nuevamente al kernel. También, algunos sistemas de archivos podrían implementar optimizaciones adicionales. La copia se realiza como si ambos archivos se abrieran como binarios.

El valor de retorno es la cantidad de bytes copiados. Esto podría ser menor que la cantidad solicitada.

Disponibilidad: Kernel de Linux >= 4.5 o glibc >= 2.27.

Nuevo en la versión 3.8.

os.device_encoding(fd)

Retorna una cadena que describe la codificación del dispositivo asociado con fd si está conectado a una terminal; sino retorna None.

os.dup(fd)

Retorna un duplicado del descriptor de archivo fd. El nuevo descriptor de archivo es no heredable.

En Windows, al duplicar un flujo estándar (0: stdin, 1: stdout, 2: stderr), el nuevo descriptor de archivo es heredable.

Distinto en la versión 3.4: El nuevo descriptor de archivo ahora es no heredable.

os.dup2(fd, fd2, inheritable=True)

Duplicar el descriptor de archivo fd a fd2, cerrando el anterior si es necesario. Retorna fd2. El nuevo descriptor de archivo es heredable por defecto o no heredable si inheritable es False.

Distinto en la versión 3.4: Agrega el parámetro opcional inheritable.

Distinto en la versión 3.7: Retorna fd2 en caso de éxito. Anteriormente se retornaba siempre None.

os.fchmod(fd, mode)

Cambia el modo del archivo dado por fd al modo numérico mode. Consulte los documentos para chmod() para conocer los posibles valores de mode. A partir de Python 3.3, esto es equivalente a os.chmod(fd, mode).

Lanza un evento de auditoría os.chmod con argumentos path, mode, dir_fd.

Disponibilidad: Unix.

os.fchown(fd, uid, gid)

Cambia el propietario y el id del grupo del archivo proporcionado por fd a los numéricos dados por uid y gid. Para dejar uno de los identificadores sin cambios, configúrelo en -1. Ver chown(). A partir de Python 3.3, esto es equivalente a os.chown(fd, uid, gid).

Lanza un evento de auditoría os.chown con argumentos path, uid, gid, dir_fd.

Disponibilidad: Unix.

os.fdatasync(fd)

Fuerza la escritura del archivo con el descriptor de archivo fd en el disco. No fuerza la actualización de metadatos.

Disponibilidad: Unix.

Nota

Esta función no está disponible en MacOS.

os.fpathconf(fd, name)

Retorna la información de configuración del sistema relevante para un archivo abierto. name especifica el valor de configuración para recuperar; puede ser una cadena que es el nombre de un valor de sistema definido; estos nombres se especifican en varios estándares (POSIX.1, Unix 95, Unix 98 y otros). Algunas plataformas también definen nombres adicionales. Los nombres conocidos por el sistema operativo anfitrión se dan en el diccionario pathconf_names. Para las variables de configuración no incluidas en esa asignación, también se acepta pasar un número entero para name.

Si name es una cadena y no se conoce, se lanza un ValueError. Si el sistema anfitrión no admite un valor específico para name, incluso si está incluido en pathconf_names, se genera un OSError con errno.EINVAL para el número de error.

A partir de Python 3.3, esto es equivalente a os.pathconf(fd, name).

Disponibilidad: Unix.

os.fstat(fd)

Obtiene el estado del descriptor de archivo fd. Retorna un objeto stat_result.

A partir de Python 3.3, esto es equivalente a os.stat(fd).

Ver también

La función stat().

os.fstatvfs(fd)

Retorna información sobre el sistema de archivos que contiene el archivo asociado con el descriptor de archivo fd, como statvfs(). A partir de Python 3.3, esto es equivalente a os.statvfs(fd).

Disponibilidad: Unix.

os.fsync(fd)

Fuerza la escritura del archivo con el descriptor de archivo fd en el disco. En Unix, esto llama a la función nativa fsync(); en Windows, la función MS _commit().

Si está comenzando con un Python almacenado en búfer file object f, primero haga f.flush(), y luego haga os.fsync(f.fileno()), para garantizar que todas las memorias intermedias internas asociadas con f se escriban en disco.

Disponibilidad: Unix, Windows.

os.ftruncate(fd, length)

Trunca el archivo correspondiente al descriptor de archivo fd, para que tenga como máximo length bytes de tamaño. A partir de Python 3.3, esto es equivalente a os.truncate(fd, length).

Lanza un evento de auditoría os.truncate con argumentos fd, length.

Disponibilidad: Unix, Windows.

Distinto en la versión 3.5: Se agregó soporte para Windows

os.get_blocking(fd)

Obtiene el modo de bloqueo del descriptor de archivo: False si se establece el indicador O_NONBLOCK, True si el indicador se borra.

Consulte también set_blocking() y socket.socket.setblocking().

Disponibilidad: Unix.

Nuevo en la versión 3.5.

os.isatty(fd)

Retorna True si el descriptor de archivo fd está abierto y conectado a un dispositivo tipo tty, de lo contrario, False.

os.lockf(fd, cmd, len)

Aplique, pruebe o elimine un bloqueo POSIX en un descriptor de archivo abierto. fd es un descriptor de archivo abierto. cmd especifica el comando a usar - uno de F_LOCK, F_TLOCK, F_ULOCK o F_TEST. len especifica la sección del archivo a bloquear.

Lanza un evento de auditoría os.lockf con argumentos fd, cmd, len.

Disponibilidad: Unix.

Nuevo en la versión 3.3.

os.F_LOCK

os.F_TLOCK

os.F_ULOCK

os.F_TEST

Indicadores que especifican qué acción tomará lockf().

Disponibilidad: Unix.

Nuevo en la versión 3.3.

os.lseek(fd, pos, how)

Establece la posición actual del descriptor de archivo fd en la posición pos, modificada por how: SEEK_SET o 0 para establecer la posición relativa al comienzo del archivo; SEEK_CUR o 1 para establecerlo en relación con la posición actual; SEEK_END o 2 para establecerlo en relación con el final del archivo. Retorna la nueva posición del cursor en bytes, comenzando desde el principio.

os.SEEK_SET

os.SEEK_CUR

os.SEEK_END

Parámetros para la función lseek(). Sus valores son 0, 1 y 2, respectivamente.

Nuevo en la versión 3.3: Algunos sistemas operativos pueden admitir valores adicionales, como os.SEEK_HOLE o os.SEEK_DATA.

os.open(path, flags, mode=0o777, *, dir_fd=None)

Abre el archivo path y configura varios indicadores según flags y su modo según mode. Al calcular el modo el valor actual de umask se enmascara primero. Retorna el descriptor de archivo para el archivo recién abierto. El nuevo descriptor de archivo es no heredable.

Para una descripción de los valores de indicadores (flags) y modo (mode), consulte la documentación de tiempo de ejecución de C; los indicadores constantes de flag (como O_RDONLY y O_WRONLY) se definen en el módulo os. En particular, en Windows agregar O_BINARY es necesario para abrir archivos en modo binario.

Esta función puede admitir rutas relativas a descriptores de directorio con el parámetro dir_fd.

Lanza un evento de auditoría open con argumentos path, mode, flags.

Distinto en la versión 3.4: El nuevo descriptor de archivo ahora es no heredable.

Nota

Esta función está diseñada para E/S de bajo nivel. Para un uso normal, use la función integrada open(), que retorna un file object con métodos read() y write() (y mucho mas). Para envolver un descriptor de archivo en un objeto de archivo, use fdopen().

Nuevo en la versión 3.3: El argumento dir_fd.

Distinto en la versión 3.5: Si la llamada al sistema se interrumpe y el controlador de señal no genera una excepción, la función vuelve a intentar la llamada del sistema en lugar de generar una excepción InterruptedError (ver PEP 475 [https://www.python.org/dev/peps/pep-0475] para la justificación).

Distinto en la versión 3.6: Acepta un objeto tipo ruta.

Las siguientes constantes son opciones para el parámetro flags de la función open(). Se pueden combinar con el operador OR a nivel de bit |. Algunos de ellas no están disponibles en todas las plataformas. Para obtener descripciones de su disponibilidad y uso, consulte la página de manual open(2) en Unix o la MSDN [https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx] en Windows.

os.O_RDONLY

os.O_WRONLY

os.O_RDWR

os.O_APPEND

os.O_CREAT

os.O_EXCL

os.O_TRUNC

Las constantes anteriores están disponibles en Unix y Windows.

os.O_DSYNC

os.O_RSYNC

os.O_SYNC

os.O_NDELAY

os.O_NONBLOCK

os.O_NOCTTY

os.O_CLOEXEC

Las constantes anteriores sólo están disponibles en Unix.

Distinto en la versión 3.3: Se agregó la constante O_CLOEXEC.

os.O_BINARY

os.O_NOINHERIT

os.O_SHORT_LIVED

os.O_TEMPORARY

os.O_RANDOM

os.O_SEQUENTIAL

os.O_TEXT

Las constantes anteriores sólo están disponibles en Windows.

os.O_ASYNC

os.O_DIRECT

os.O_DIRECTORY

os.O_NOFOLLOW

os.O_NOATIME

os.O_PATH

os.O_TMPFILE

os.O_SHLOCK

os.O_EXLOCK

Las constantes anteriores son extensiones y no están presentes si no están definidas por la biblioteca de C.

Distinto en la versión 3.4: Se agrega la constante O_PATH en los sistemas que lo admiten. Se agrega O_TMPFILE, sólo disponible en Linux para el Kernel 3.11 o posterior.

os.openpty()

Abre un nuevo par de pseudo-terminal. Retorna un par de descriptores de archivo (master, slave); para pty y tty, respectivamente. Los nuevos descriptores de archivo son no heredable. Para un enfoque (ligeramente) más portátil, use el módulo pty.

Disponibilidad: algunos sistemas tipo Unix.

Distinto en la versión 3.4: Los nuevos descriptores de archivo ahora son no heredables.

os.pipe()

Crea una tubería. Retorna un par de descriptores de archivo (r, w) que se pueden usar para leer y escribir, respectivamente. El nuevo descriptor de archivo es no heredable.

Disponibilidad: Unix, Windows.

Distinto en la versión 3.4: Los nuevos descriptores de archivo ahora son no heredables.

os.pipe2(flags)

Crea una tubería con flags establecidas atómicamente. flags pueden construirse juntando uno o más de estos valores: O_NONBLOCK, O_CLOEXEC con el operador OR. Retorna un par de descriptores de archivo (r, w) que se pueden usar para leer y escribir, respectivamente.

Disponibilidad: algunos sistemas tipo Unix.

Nuevo en la versión 3.3.

os.posix_fallocate(fd, offset, len)

Asegura que se asigne suficiente espacio en disco para el archivo especificado por fd a partir de offset y se extiende por len bytes.

Disponibilidad: Unix.

Nuevo en la versión 3.3.

os.posix_fadvise(fd, offset, len, advice)

Avisa una intención de acceder a los datos en un patrón específico, permitiendo así que el núcleo haga optimizaciones. El consejo se aplica a la región del archivo especificada por fd que comienza en offset y se extiende para len bytes. advice es uno de POSIX_FADV_NORMAL, POSIX_FADV_SEQUENTIAL, POSIX_FADV_RANDOM, POSIX_FADV_NOREUSE, POSIX_FADV_WILLNEED o POSIX_FADV_DONTNEED.

Disponibilidad: Unix.

Nuevo en la versión 3.3.

os.POSIX_FADV_NORMAL

os.POSIX_FADV_SEQUENTIAL

os.POSIX_FADV_RANDOM

os.POSIX_FADV_NOREUSE

os.POSIX_FADV_WILLNEED

os.POSIX_FADV_DONTNEED

Indicadores que se pueden usar en advice en posix_fadvise() que especifican el patrón de acceso que es probable que se use.

Disponibilidad: Unix.

Nuevo en la versión 3.3.

os.pread(fd, n, offset)

Lee como máximo n bytes del descriptor de archivo fd en una posición de offset, sin modificar el desplazamiento (offset) del archivo.

Retorna una cadena de bytes que contiene los bytes leídos. Si se alcanza el final del archivo al que hace referencia fd, se retorna un objeto de bytes vacío.

Disponibilidad: Unix.

Nuevo en la versión 3.3.

os.preadv(fd, buffers, offset, flags=0)

Lee de un descriptor de archivo fd en una posición de offset en mutable objetos de tipo bytes buffers, dejando el desplazamiento del archivo sin cambios. Transfiere datos a cada búfer hasta que esté lleno y luego pase al siguiente búfer en la secuencia para contener el resto de los datos.

El argumento flags contiene un operador de bit a bit OR de cero o más de las siguientes flags:

RWF_HIPRI

RWF_NOWAIT

Retorna el número total de bytes realmente leídos que puede ser menor que la capacidad total de todos los objetos.

El sistema operativo puede establecer un límite (sysconf() valor 'SC_IOV_MAX') en el número de búferes que se pueden usar.

Combina la funcionalidad de os.readv() y os.pread().

Disponibilidad: Linux 2.6.30 y posterior, FreeBSD 6.0 y posterior, OpenBSD 2.7 y posterior, AIX 7.1 y posterior. El uso de flags requiere Linux 4.6 o posterior.

Nuevo en la versión 3.7.

os.RWF_NOWAIT

No espere datos que no estén disponibles de inmediato. Si se especifica este indicador, la llamada al sistema regresará instantáneamente si tuviera que leer datos del almacenamiento de respaldo o esperar por un bloqueo.

Si algunos datos se leyeron con éxito, retornará el número de bytes leídos. Si no se leyeron bytes, retornará -1 y establecerá errno en errno.EAGAIN.

Disponibilidad: Linux 4.14 y más nuevos.

Nuevo en la versión 3.7.

os.RWF_HIPRI

Alta prioridad de lectura/escritura. Permite que los sistemas de archivos basados en bloques utilicen el sondeo del dispositivo, lo que proporciona una latencia más baja, pero puede usar recursos adicionales.

Actualmente, en Linux, esta función sólo se puede usar en un descriptor de archivo abierto con el indicador O_DIRECT.

Disponibilidad: Linux 4.6 y más nuevos.

Nuevo en la versión 3.7.

os.pwrite(fd, str, offset)

Escribe la cadena de bytes en str en el descriptor de archivo fd en la posición offset, sin modificar el desplazamiento del archivo.

Retorna el número de bytes realmente escritos.

Disponibilidad: Unix.

Nuevo en la versión 3.3.

os.pwritev(fd, buffers, offset, flags=0)

Escribe los contenidos de los buffers en el descriptor de archivo fd en un desplazamiento offset, dejando el desplazamiento del archivo sin cambios. buffers deben ser una secuencia de objetos tipo bytes. Los búferes se procesan en orden secuencial. Se escribe todo el contenido del primer búfer antes de pasar al segundo, y así sucesivamente.

El argumento flags contiene un operador de bit a bit OR de cero o más de las siguientes flags:

RWF_DSYNC

RWF_SYNC

Retorna el número total de bytes realmente escritos.

El sistema operativo puede establecer un límite (sysconf() valor 'SC_IOV_MAX') en el número de búferes que se pueden usar.

Combina la funcionalidad de os.writev() y os.pwrite().

Disponibilidad: Linux 2.6.30 y posterior, FreeBSD 6.0 y posterior, OpenBSD 2.7 y posterior, AIX 7.1 y posterior. El uso de flags requiere Linux 4.7 o posterior.

Nuevo en la versión 3.7.

os.RWF_DSYNC

Proporciona un equivalente por escritura de la flag O_DSYNC` open(2)`. Esta flag sólo se aplica al rango de datos escrito por la llamada al sistema.

Disponibilidad: Linux 4.7 y más nuevos.

Nuevo en la versión 3.7.

os.RWF_SYNC

Proporciona un equivalente por escritura de la flag O_SYNC` open(2)`. Esta flag sólo se aplica al rango de datos escrito por la llamada al sistema.

Disponibilidad: Linux 4.7 y más nuevos.

Nuevo en la versión 3.7.

os.read(fd, n)

Lee como máximo n bytes del descriptor de archivo fd.

Retorna una cadena de bytes que contiene los bytes leídos. Si se alcanza el final del archivo al que hace referencia fd, se retorna un objeto de bytes vacío.

Nota

Esta función está diseñada para E/S de bajo nivel y debe aplicarse a un descriptor de archivo tal como lo retorna os.open() o pipe(). Para leer un «objeto archivo» retornado por la función incorporada open() o por popen() o fdopen(), o sys.stdin, use los métodos read() o readline().

Distinto en la versión 3.5: Si la llamada al sistema se interrumpe y el controlador de señal no genera una excepción, la función vuelve a intentar la llamada del sistema en lugar de generar una excepción InterruptedError (ver PEP 475 [https://www.python.org/dev/peps/pep-0475] para la justificación).

os.sendfile(out_fd, in_fd, offset, count)

os.sendfile(out_fd, in_fd, offset, count, headers=(), trailers=(), flags=0)

Copia count bytes del descriptor de archivo in_fd al descriptor de archivo out_fd comenzando en offset. Retorna el número de bytes enviados. Cuando se alcanza EOF, retorna 0.

La primera notación de la función es compatible con todas las plataformas que definen sendfile().

En Linux, si offset se entrega como None, los bytes se leen desde la posición actual de in_fd y la posición de in_fd se actualiza.

The second case may be used on macOS and FreeBSD where headers and trailers are arbitrary sequences of buffers that are written before and after the data from in_fd is written. It returns the same as the first case.

On macOS and FreeBSD, a value of 0 for count specifies to send until the end of in_fd is reached.

Todas las plataformas admiten sockets como descriptor de archivo out_fd, y algunas plataformas también permiten otros tipos (por ejemplo, archivo regular, tuberías).

Las aplicaciones multiplataforma no deben usar los argumentos headers, trailers y flags.

Disponibilidad: Unix.

Nota

Para un contenedor de alto nivel de sendfile(), vea socket.socket.sendfile().

Nuevo en la versión 3.3.

Distinto en la versión 3.9: Parámetros out e in han sido renombrados a out_fd e in_fd.

os.set_blocking(fd, blocking)

Establece el modo de bloqueo del descriptor de archivo especificado. Establece la flag O_NONBLOCK si se quiere que el bloqueo sea False, borre la flag de lo contrario.

Consulte también get_blocking() y socket.socket.setblocking().

Disponibilidad: Unix.

Nuevo en la versión 3.5.

os.SF_NODISKIO

os.SF_MNOWAIT

os.SF_SYNC

Parámetros para la función sendfile(), si la implementación los admite.

Disponibilidad: Unix.

Nuevo en la versión 3.3.

os.readv(fd, buffers)

Leer desde un descriptor de archivo fd en una cantidad de mutable objetos tipo bytes buffers. Transfiere datos a cada búfer hasta que esté lleno y luego pase al siguiente búfer en la secuencia para contener el resto de los datos.

Retorna el número total de bytes realmente leídos que puede ser menor que la capacidad total de todos los objetos.

El sistema operativo puede establecer un límite (sysconf() valor 'SC_IOV_MAX') en el número de búferes que se pueden usar.

Disponibilidad: Unix.

Nuevo en la versión 3.3.

os.tcgetpgrp(fd)

Retorna el grupo del proceso asociado con la terminal proporcionada por fd (un descriptor de archivo abierto como lo retorna os.open()).

Disponibilidad: Unix.

os.tcsetpgrp(fd, pg)

Establece el grupo del proceso asociado con la terminal dada por fd (un descriptor de archivo abierto como lo retorna os.open()) a pg.

Disponibilidad: Unix.

os.ttyname(fd)

Retorna una cadena que especifica el dispositivo de terminal asociado con el descriptor de archivo fd. Si fd no está asociado con un dispositivo de terminal, se genera una excepción.

Disponibilidad: Unix.

os.write(fd, str)

Escribe la cadena de bytes en str en el descriptor de archivo fd.

Retorna el número de bytes realmente escritos.

Nota

Esta función está diseñada para E/S de bajo nivel y debe aplicarse a un descriptor de archivo tal como lo retorna os.open() o pipe(). Para escribir un «objeto archivo» retornado por la función incorporada open() o por popen() o fdopen(), o sys.stdout o sys.stderr, use el método write().

Distinto en la versión 3.5: Si la llamada al sistema se interrumpe y el controlador de señal no genera una excepción, la función vuelve a intentar la llamada del sistema en lugar de generar una excepción InterruptedError (ver PEP 475 [https://www.python.org/dev/peps/pep-0475] para la justificación).

os.writev(fd, buffers)

Escribe el contenido de buffers en el descriptor de archivo fd. buffers debe ser una secuencia de objetos tipo bytes. Los búferes se procesan en orden secuencial. Se escribe todo el contenido del primer búfer antes de pasar al segundo, y así sucesivamente.

Retorna el número total de bytes realmente escritos.

El sistema operativo puede establecer un límite (sysconf() valor 'SC_IOV_MAX') en el número de búferes que se pueden usar.

Disponibilidad: Unix.

Nuevo en la versión 3.3.

Consultando las dimensiones de una terminal

Nuevo en la versión 3.3.

os.get_terminal_size(fd=STDOUT_FILENO)

Retorna el tamaño de la ventana de la terminal como (columns, lines), una tupla del tipo terminal_size.

El argumento opcional fd (por defecto es STDOUT_FILENO, o la salida estándar) especifica qué descriptor de archivo debe consultarse.

Si el descriptor de archivo no está conectado a una terminal, se genera un OSError.

shutil.get_terminal_size() es la función de alto nivel que normalmente debería usarse, os.get_terminal_size es la implementación de bajo nivel.

Disponibilidad: Unix, Windows.

class os.terminal_size

Una subclase de tupla, que contiene (columns, lines) representando el tamaño de la ventana de la terminal.

columns

Ancho de la ventana de la terminal en caracteres.

lines

Alto de la ventana de la terminal en caracteres.

Herencia de los descriptores de archivos

Nuevo en la versión 3.4.

Un descriptor de archivo tiene un indicador heredable (inheritable) que indica si el descriptor de archivo puede ser heredado por procesos secundarios. Desde Python 3.4, los descriptores de archivo creados por Python son no heredables por defecto.

En UNIX, los descriptores de archivo no heredables se cierran en procesos hijos en la ejecución de un nuevo programa, otros descriptores de archivos sí se heredan.

En Windows, los descriptores de archivo y los identificadores no heredables se cierran en los procesos hijos, a excepción de los flujos estándar (descriptores de archivo 0, 1 y 2: stdin, stdout y stderr), que siempre se heredan. Usando las funciones spawn*, todos los identificadores heredables y todos los descriptores de archivos heredables se heredan. Usando el módulo subprocess, todos los descriptores de archivo, excepto los flujos estándar, están cerrados, y los identificadores heredables sólo se heredan si el parámetro close_fds es False.

os.get_inheritable(fd)

Obtiene el indicador heredable (inheritable) del descriptor de archivo especificado (un valor booleano).

os.set_inheritable(fd, inheritable)

Establece el indicador heredable (inheritable) del descriptor de archivo especificado.

os.get_handle_inheritable(handle)

Obtiene el indicador heredable (inheritable) del identificador especificado (un valor booleano).

Disponibilidad: Windows.

os.set_handle_inheritable(handle, inheritable)

Establece el indicador heredable (inheritable) del identificador especificado.

Disponibilidad: Windows.

Archivos y directorios

En algunas plataformas Unix, muchas de estas funciones admiten una o más de estas características:

especificando un descriptor de archivo: Normalmente el argumento path proporcionado a las funciones en el módulo os debe ser una cadena que especifique una ruta de archivo. Sin embargo, algunas funciones ahora aceptan alternativamente un descriptor de archivo abierto para su argumento path. La función actuará en el archivo al que hace referencia el descriptor. (Para los sistemas POSIX, Python llamará a la variante de la función con el prefijo f (por ejemplo, llamará a fchdir en lugar de chdir)).

Puede verificar si path se puede especificar o no como un descriptor de archivo para una función particular en su plataforma usando os.supports_fd. Si esta funcionalidad no está disponible, su uso generará un NotImplementedError.

Si la función también admite argumentos dir_fd o follow_symlinks, es un error especificar uno de esos al suministrar path como descriptor de archivo.

rutas relativas a los descriptores de directorio: Si dir_fd no es None, debería ser un descriptor de archivo que se refiera a un directorio, y la ruta a operar debería ser relativa; entonces la ruta será relativa a ese directorio. Si la ruta es absoluta, dir_fd se ignora. (Para los sistemas POSIX, Python llamará a la variante de la función con un sufijo at y posiblemente con el prefijo f (por ejemplo, llamará a faccessat en lugar de access).

Puede verificar si dir_fd es compatible o no para una función particular en su plataforma usando os.supports_dir_fd. Si no está disponible, usarlo generará un NotImplementedError.

no seguir los enlaces simbólicos: Si follow_symlinks es False, y el último elemento de la ruta para operar es un enlace simbólico, la función operará en el enlace simbólico en lugar del archivo señalado por el enlace. (Para los sistemas POSIX, Python llamará a la variante l... de la función).

Puede verificar si follow_symlinks es compatible o no para una función particular en su plataforma usando os.supports_follow_symlinks. Si no está disponible, usarlo generará un NotImplementedError.

os.access(path, mode, *, dir_fd=None, effective_ids=False, follow_symlinks=True)

Use el uid/gid real para probar el acceso a path. Tenga en cuenta que la mayoría de las operaciones utilizarán el uid/gid efectivo, por lo tanto, esta rutina se puede usar en un entorno suid/sgid para probar si el usuario que invoca tiene el acceso especificado a path. mode debería ser F_OK para probar la existencia de path, o puede ser el OR inclusivo de uno o más de R_OK, W_OK, y X_OK para probar los permisos. Retorna True si el acceso está permitido, False si no. Consulte la página de manual de Unix access (2) para obtener más información.

Esta función puede admitir la especificación rutas relativas a descriptores de directorio y no seguir los enlaces simbólicos.

Si effective_ids es True, access() realizará sus comprobaciones de acceso utilizando el uid/gid efectivo en lugar del uid/gid real. effective_ids puede no ser compatible con su plataforma; puede verificar si está disponible o no usando os.supports_effective_ids. Si no está disponible, usarlo generará un NotImplementedError.

Nota

Usando access() para verificar si un usuario está autorizado para, por ejemplo, abrir un archivo antes de hacerlo usando open() crea un agujero de seguridad, porque el usuario podría explotar el breve intervalo de tiempo entre verificar y abrir el archivo para manipularlo es preferible utilizar técnicas EAFP. Por ejemplo:

if os.access("myfile", os.R_OK):
    with open("myfile") as fp:
        return fp.read()
return "some default data"

está mejor escrito como:

try:
    fp = open("myfile")
except PermissionError:
    return "some default data"
else:
    with fp:
        return fp.read()

Nota

Las operaciones de E/S pueden fallar incluso cuando access() indica que tendrán éxito, particularmente para operaciones en sistemas de archivos de red que pueden tener una semántica de permisos más allá del modelo habitual de bits de permiso POSIX.

Distinto en la versión 3.3: Se agregaron los parámetros dir_fd, effective_ids y follow_symlinks.

Distinto en la versión 3.6: Acepta un objeto tipo ruta.

os.F_OK

os.R_OK

os.W_OK

os.X_OK

Valores para pasar como parámetro mode de access() para probar la existencia, legibilidad, escritura y ejecutabilidad de path, respectivamente.

os.chdir(path)

Cambia el directorio de trabajo actual a path.

Esta función puede soportar especificando un descriptor de archivo. El descriptor debe hacer referencia a un directorio abierto, no a un archivo abierto.

Esta función puede generar OSError y subclases como FileNotFoundError, PermissionError, y NotADirectoryError.

Lanza un evento de auditoría os.chdir con argumento path.

Nuevo en la versión 3.3: Se agregó soporte para especificar path como descriptor de archivo en algunas plataformas.

Distinto en la versión 3.6: Acepta un objeto tipo ruta.

os.chflags(path, flags, *, follow_symlinks=True)

Establece las flags del path a las flags numéricas. flags puede tomar una combinación (OR bit a bit) de los siguientes valores (como se define en el módulo stat):

stat.UF_NODUMP

stat.UF_IMMUTABLE

stat.UF_APPEND

stat.UF_OPAQUE

stat.UF_NOUNLINK

stat.UF_COMPRESSED

stat.UF_HIDDEN

stat.SF_ARCHIVED

stat.SF_IMMUTABLE

stat.SF_APPEND

stat.SF_NOUNLINK

stat.SF_SNAPSHOT

Esta función puede soportar no seguir enlaces simbólicos.

Lanza un evento de auditoría os.chflags con argumentos path, flags.

Disponibilidad: Unix.

Nuevo en la versión 3.3: El argumento follow_symlinks.

Distinto en la versión 3.6: Acepta un objeto tipo ruta.

os.chmod(path, mode, *, dir_fd=None, follow_symlinks=True)

Cambia el modo de path al modo numérico mode. mode puede tomar uno de los siguientes valores (como se define en el módulo stat) o combinaciones OR de bit a bit de ellos:

stat.S_ISUID

stat.S_ISGID

stat.S_ENFMT

stat.S_ISVTX

stat.S_IREAD

stat.S_IWRITE

stat.S_IEXEC

stat.S_IRWXU

stat.S_IRUSR

stat.S_IWUSR

stat.S_IXUSR

stat.S_IRWXG

stat.S_IRGRP

stat.S_IWGRP

stat.S_IXGRP

stat.S_IRWXO

stat.S_IROTH

stat.S_IWOTH

stat.S_IXOTH

Esta función puede soportar especificando un descriptor de archivo, rutas relativas a los descriptores de directorio y no seguir enlaces simbólicos.

Nota

Aunque Windows admite chmod(), sólo puede establecer el indicador de sólo lectura del archivo (a través de las constantes``stat.S_IWRITE`` y stat.S_IREAD o un valor entero correspondiente). Todos los demás bits son ignorados.

Lanza un evento de auditoría os.chmod con argumentos path, mode, dir_fd.

Nuevo en la versión 3.3: Se agregó soporte para especificar path como un descriptor de archivo abierto, y los argumentos dir_fd y follow_symlinks.

Distinto en la versión 3.6: Acepta un objeto tipo ruta.

os.chown(path, uid, gid, *, dir_fd=None, follow_symlinks=True)

Cambia el propietario y el id del grupo de path a los numéricos uid y gid. Para dejar uno de los identificadores sin cambios, configúrelo en -1.

Esta función puede soportar especificando un descriptor de archivo, rutas relativas a los descriptores de directorio y no seguir enlaces simbólicos.

Ver shutil.chown() para una función de nivel superior que acepta nombres además de identificadores numéricos.

Lanza un evento de auditoría os.chown con argumentos path, uid, gid, dir_fd.

Disponibilidad: Unix.

Nuevo en la versión 3.3: Se agregó soporte para especificar path como un descriptor de archivo abierto, y los argumentos dir_fd y follow_symlinks.

Distinto en la versión 3.6: Admite un objeto tipo ruta.

os.chroot(path)

Cambia el directorio raíz del proceso actual a path.

Disponibilidad: Unix.

Distinto en la versión 3.6: Acepta un objeto tipo ruta.

os.fchdir(fd)

Cambia el directorio de trabajo actual al directorio representado por el descriptor de archivo fd. El descriptor debe hacer referencia a un directorio abierto, no a un archivo abierto. A partir de Python 3.3, esto es equivalente a os.chdir(fd).

Lanza un evento de auditoría os.chdir con argumento path.

Disponibilidad: Unix.

os.getcwd()

Retorna una cadena que representa el directorio de trabajo actual.

os.getcwdb()

Retorna una cadena de bytes que representa el directorio de trabajo actual.

Distinto en la versión 3.8: La función ahora usa la codificación UTF-8 en Windows, en lugar de los códigos ANSI: consulte PEP 529 [https://www.python.org/dev/peps/pep-0529] para ver la justificación. La función ya no está en desuso en Windows.

os.lchflags(path, flags)

Establece las flags de path a las flags numéricas, como chflags(), pero no siga los enlaces simbólicos. A partir de Python 3.3, esto es equivalente a os.chflags(path, flags, follow_symlinks=False).

Lanza un evento de auditoría os.chflags con argumentos path, flags.

Disponibilidad: Unix.

Distinto en la versión 3.6: Acepta un objeto tipo ruta.

os.lchmod(path, mode)

Cambia el modo de path al mode numérico. Si la ruta es un enlace simbólico, esto afecta al enlace simbólico en lugar del objetivo. Consulte los documentos para chmod() para conocer los posibles valores de mode. A partir de Python 3.3, esto es equivalente a os.chmod(path, mode, follow_symlinks=False).

Lanza un evento de auditoría os.chmod con argumentos path, mode, dir_fd.

Disponibilidad: Unix.

Distinto en la versión 3.6: Acepta un objeto tipo ruta.

os.lchown(path, uid, gid)

Cambia el propietario y la identificación del grupo de path a los numéricos uid y gid. Esta función no seguirá enlaces simbólicos. A partir de Python 3.3, esto es equivalente a os.chown(path, uid, gid, follow_symlinks=False).

Lanza un evento de auditoría os.chown con argumentos path, uid, gid, dir_fd.

Disponibilidad: Unix.

Distinto en la versión 3.6: Acepta un objeto tipo ruta.

os.link(src, dst, *, src_dir_fd=None, dst_dir_fd=None, follow_symlinks=True)

Cree un enlace rígido que apunte a src llamado dst.

Esta función puede admitir la especificación de src_dir_fd o dst_dir_fd para proporcionar rutas relativas a los descriptores de directorio, y no sigue enlaces simbólicos.

Lanza un evento de auditoría os.link con argumentos src, dst, src_dir_fd, dst_dir_fd.

Disponibilidad: Unix, Windows.

Distinto en la versión 3.2: Se agregó soporte para Windows.

Nuevo en la versión 3.3: Se agregaron los argumentos src_dir_fd, dst_dir_fd y follow_symlinks.

Distinto en la versión 3.6: Acepta un path-like object para src y dst.

os.listdir(path='.')

Retorna una lista que contiene los nombres de las entradas en el directorio dado por path. La lista está en un orden arbitrario y no incluye las entradas especiales '.' Y '..' incluso si están presentes en el directorio. Si un archivo es removido de o añadido al directorio mientras se llama a esta función, no se especifica si el nombre para el archivo será incluido.

path puede ser un path-like object. Si path es de tipo bytes (directa o indirectamente a través de la interfaz PathLike), los nombres de archivo retornados también serán de tipo bytes; en todas las demás circunstancias, serán del tipo str.

Esta función también puede admitir especificando un descriptor de archivo; el descriptor de archivo debe hacer referencia a un directorio.

Lanza un evento de auditoría os.listdir con el argumento ruta.

Nota

Para codificar los nombres de archivo str en bytes, use fsencode().

Ver también

La función scandir() retorna entradas de directorio junto con información de atributos de archivo, lo que proporciona un mejor rendimiento para muchos casos de uso comunes.

Distinto en la versión 3.2: El parámetro path se convirtió en opcional.

Nuevo en la versión 3.3: Se agregó soporte para especificar path como un descriptor de archivo abierto.

Distinto en la versión 3.6: Acepta un objeto tipo ruta.

os.lstat(path, *, dir_fd=None)

Realice el equivalente de una llamada al sistema lstat() en la ruta dada. Similar a stat(), pero no sigue enlaces simbólicos. Retorna un objeto stat_result.

En plataformas que no admiten enlaces simbólicos, este es un alias para stat().

A partir de Python 3.3, esto es equivalente a os.stat(path, dir_fd=dir_fd, follow_symlinks=False).

Esta función también puede admitir rutas relativas a descriptores de directorio.

Ver también

La función stat().

Distinto en la versión 3.2: Se agregó soporte para enlaces simbólicos de Windows 6.0 (Vista).

Distinto en la versión 3.3: Se agregó el parámetro dir_fd.

Distinto en la versión 3.6: Acepta un objeto tipo ruta.

Distinto en la versión 3.8: En Windows, ahora abre puntos de análisis que representan otra ruta (nombres sustitutos), incluidos enlaces simbólicos y uniones de directorio. El sistema operativo resuelve otros tipos de puntos de análisis como stat().

os.mkdir(path, mode=0o777, *, dir_fd=None)

Cree un directorio llamado path con modo numérico mode.

If the directory already exists, FileExistsError is raised. If a parent directory in the path does not exist, FileNotFoundError is raised.

En algunos sistemas, mode se ignora. Donde se usa, el valor actual de umask se enmascara primero. Si se establecen bits distintos de los últimos 9 (es decir, los últimos 3 dígitos de la representación octal del mode), su significado depende de la plataforma. En algunas plataformas, se ignoran y debe llamar a chmod() explícitamente para configurarlos.

Esta función también puede admitir rutas relativas a descriptores de directorio.

También es posible crear directorios temporales; vea la función tempfile del módulo tempfile.mkdtemp().

Lanza un evento de auditoría os.mkdir con argumentos ruta, modo, dir_fd.

Nuevo en la versión 3.3: El argumento dir_fd.

Distinto en la versión 3.6: Acepta un objeto tipo ruta.

os.makedirs(name, mode=0o777, exist_ok=False)

Función de creación de directorio recursiva. Como mkdir(), pero hace que todos los directorios de nivel intermedio sean necesarios para contener el directorio hoja.

El parámetro mode se pasa a mkdir() para crear el directorio hoja; ver la descripción de mkdir() por cómo se interpreta. Para configurar los bits de permiso de archivo de cualquier directorio padre recién creado, puede configurar la umask antes de invocar makedirs(). Los bits de permiso de archivo de los directorios principales existentes no se modifican.

Si exist_ok es False (el valor predeterminado), se genera un FileExistsError si el directorio de destino ya existe.

Nota

makedirs() se confundirá si los elementos de ruta a crear incluyen pardir (por ejemplo, «..» en sistemas UNIX).

Esta función maneja las rutas UNC correctamente.

Lanza un evento de auditoría os.mkdir con argumentos ruta, modo, dir_fd.

Nuevo en la versión 3.2: El parámetro exist_ok.

Distinto en la versión 3.4.1: Antes de Python 3.4.1, si exist_ok era True y el directorio existía, makedirs() aún generaría un error si mode no coincidía con el modo del directorio existente. Como este comportamiento era imposible de implementar de forma segura, se eliminó en Python 3.4.1. Ver bpo-21082 [https://bugs.python.org/issue?@action=redirect&bpo=21082].

Distinto en la versión 3.6: Acepta un objeto tipo ruta.

Distinto en la versión 3.7: El argumento mode ya no afecta los bits de permiso de archivo de los directorios de nivel intermedio recién creados.

os.mkfifo(path, mode=0o666, *, dir_fd=None)

Cree una FIFO (una tubería con nombre) llamada path con modo numérico modo. El valor actual de umask se enmascara primero del modo.

Esta función también puede admitir rutas relativas a descriptores de directorio.

Los FIFO son tuberías a las que se puede acceder como archivos normales. Los FIFO existen hasta que se eliminan (por ejemplo con os.unlink()). En general, los FIFO se utilizan como punto de encuentro entre los procesos de tipo «cliente» y «servidor»: el servidor abre el FIFO para leer y el cliente lo abre para escribir. Tenga en cuenta que mkfifo() no abre el FIFO — solo crea el punto de encuentro.

Disponibilidad: Unix.

Nuevo en la versión 3.3: El argumento dir_fd.

Distinto en la versión 3.6: Acepta un objeto tipo ruta.

os.mknod(path, mode=0o600, device=0, *, dir_fd=None)

Cree un nodo del sistema de archivos (archivo, archivo especial del dispositivo o canalización con nombre) llamado path. mode especifica tanto los permisos para usar como el tipo de nodo que se creará, combinándose (OR bit a bit) con uno de stat.S_IFREG, stat.S_IFCHR, stat.S_IFBLK , y stat.S_IFIFO (esas constantes están disponibles en stat). Para stat.S_IFCHR y stat.S_IFBLK, device define el archivo especial del dispositivo recién creado (probablemente usando os.makedev()), de lo contrario se ignora.

Esta función también puede admitir rutas relativas a descriptores de directorio.

Disponibilidad: Unix.

Nuevo en la versión 3.3: El argumento dir_fd.

Distinto en la versión 3.6: Acepta un objeto tipo ruta.

os.major(device)

Extrae el número principal del dispositivo de un número de dispositivo sin formato (generalmente el campo st_dev o st_rdev de stat).

os.minor(device)

Extrae el número menor del dispositivo de un número de dispositivo sin formato (generalmente el campo st_dev o st_rdev de stat).

os.makedev(major, minor)

Compone un número de dispositivo sin procesar a partir de los números de dispositivo mayor y menor.

os.pathconf(path, name)

Retorna información de configuración del sistema relevante para un archivo con nombre. name especifica el valor de configuración para recuperar; puede ser una cadena que es el nombre de un valor de sistema definido; Estos nombres se especifican en varios estándares (POSIX.1, Unix 95, Unix 98 y otros). Algunas plataformas también definen nombres adicionales. Los nombres conocidos por el sistema operativo host se dan en el diccionario pathconf_names. Para las variables de configuración no incluidas en esa asignación, también se acepta pasar un número entero para name.

Si name es una cadena y no se conoce, se lanza un ValueError. Si el sistema anfitrión no admite un valor específico para name, incluso si está incluido en pathconf_names, se genera un OSError con errno.EINVAL para el número de error.

Esta función puede soportar especificando un descriptor de archivo.

Disponibilidad: Unix.

Distinto en la versión 3.6: Acepta un objeto tipo ruta.

os.pathconf_names

Nombres de mapeo de diccionario aceptados por pathconf() y fpathconf() a los valores enteros definidos para esos nombres por el sistema operativo host. Esto se puede usar para determinar el conjunto de nombres conocidos por el sistema.

Disponibilidad: Unix.

os.readlink(path, *, dir_fd=None)

Retorna una cadena que representa la ruta a la que apunta el enlace simbólico. El resultado puede ser un nombre de ruta absoluto o relativo; si es relativo, se puede convertir a un nombre de ruta absoluto usando os.path.join(os.path.dirname(path), result).

Si la path es un objeto de cadena (directa o indirectamente a través de una interfaz PathLike), el resultado también será un objeto de cadena y la llamada puede generar un UnicodeDecodeError. Si la path es un objeto de bytes (directa o indirectamente), el resultado será un objeto de bytes.

Esta función también puede admitir rutas relativas a descriptores de directorio.

Cuando intente resolver una ruta que puede contener enlaces, use realpath() para manejar adecuadamente la recurrencia y las diferencias de plataforma.

Disponibilidad: Unix, Windows.

Distinto en la versión 3.2: Se agregó soporte para enlaces simbólicos de Windows 6.0 (Vista).

Nuevo en la versión 3.3: El argumento dir_fd.

Distinto en la versión 3.6: Acepta un path-like object en Unix.

Distinto en la versión 3.8: Acepta un path-like object y un objeto de bytes en Windows.

Distinto en la versión 3.8: Se agregó soporte para uniones de directorio y se modificó para retornar la ruta de sustitución (que generalmente incluye el prefijo \\?\) En lugar del campo opcional «nombre de impresión» que se retornó anteriormente.

os.remove(path, *, dir_fd=None)

Remove (delete) the file path. If path is a directory, an IsADirectoryError is raised. Use rmdir() to remove directories. If the file does not exist, a FileNotFoundError is raised.

Esta función puede admitir rutas relativas a descriptores de directorio.

En Windows, intentar eliminar un archivo que está en uso provoca una excepción; en Unix, la entrada del directorio se elimina pero el almacenamiento asignado al archivo no está disponible hasta que el archivo original ya no esté en uso.

Esta función es semánticamente idéntica a unlink().

Lanza un evento de auditoría os.remove con argumentos ruta, dir_fd.

Nuevo en la versión 3.3: El argumento dir_fd.

Distinto en la versión 3.6: Acepta un objeto tipo ruta.

os.removedirs(name)

Eliminar directorios de forma recursiva. Funciona como rmdir() excepto que, si el directorio hoja se elimina con éxito, removeirs() intenta eliminar sucesivamente cada directorio principal mencionado en path hasta que se genere un error (que se ignora, porque generalmente significa que un directorio padre no está vacío). Por ejemplo, os.removedirs('foo/bar/baz') primero eliminará el directorio 'foo/bar/baz', y luego eliminará 'foo/bar' y 'foo' si están vacíos. Genera OSError si el directorio hoja no se pudo eliminar con éxito.

Lanza un evento de auditoría os.remove con argumentos ruta, dir_fd.

Distinto en la versión 3.6: Acepta un objeto tipo ruta.

os.rename(src, dst, *, src_dir_fd=None, dst_dir_fd=None)

Cambia el nombre del archivo o directorio src a dst. Si dst existe, la operación fallará con una subclase OSError en varios casos:

En Windows, si dst existe a FileExistsError siempre se genera.

En Unix, si src es un archivo y dst es un directorio o viceversa, se generará un IsADirectoryError o un NotADirectoryError respectivamente. Si ambos son directorios y dst está vacío, dst será reemplazado silenciosamente. Si dst es un directorio no vacío, se genera un OSError. Si ambos son archivos, dst se reemplazará en silencio si el usuario tiene permiso. La operación puede fallar en algunos sabores de Unix si src y dst están en diferentes sistemas de archivos. Si tiene éxito, el cambio de nombre será una operación atómica (este es un requisito POSIX).

Esta función puede admitir la especificación de src_dir_fd o dst_dir_fd para proporcionar rutas relativas a los descriptores de directorio.

Si desea sobrescribir multiplataforma del destino, use replace().

Lanza un evento de auditoría os.rename con argumentos src, dst, src_dir_fd, dst_dir_fd.

Nuevo en la versión 3.3: Los argumentos src_dir_fd y dst_dir_fd.

Distinto en la versión 3.6: Acepta un path-like object para src y dst.

os.renames(old, new)

Directorio recursivo o función de cambio de nombre de archivo. Funciona como rename(), excepto que primero se intenta crear cualquier directorio intermedio necesario para que el nuevo nombre de ruta sea bueno. Después del cambio de nombre, los directorios correspondientes a los segmentos de ruta más a la derecha del nombre anterior se eliminarán usando removeirs().

Nota

Esta función puede fallar con la nueva estructura de directorios realizada si carece de los permisos necesarios para eliminar el directorio o archivo hoja.

Lanza un evento de auditoría os.rename con argumentos src, dst, src_dir_fd, dst_dir_fd.

Distinto en la versión 3.6: Acepta un path-like object para old y new.

os.replace(src, dst, *, src_dir_fd=None, dst_dir_fd=None)

Rename the file or directory src to dst. If dst is a non-empty directory, OSError will be raised. If dst exists and is a file, it will be replaced silently if the user has permission. The operation may fail if src and dst are on different filesystems. If successful, the renaming will be an atomic operation (this is a POSIX requirement).

Esta función puede admitir la especificación de src_dir_fd o dst_dir_fd para proporcionar rutas relativas a los descriptores de directorio.

Lanza un evento de auditoría os.rename con argumentos src, dst, src_dir_fd, dst_dir_fd.

Nuevo en la versión 3.3.

Distinto en la versión 3.6: Acepta un path-like object para src y dst.

os.rmdir(path, *, dir_fd=None)

Elimina (delete) el directorio path. Si el directorio no existe o no está vacío, se genera un FileNotFoundError o un OSError respectivamente. Para eliminar árboles de directorios completos, se puede usar shutil.rmtree().

Esta función puede admitir rutas relativas a descriptores de directorio.

Lanza un evento de auditoría os.rmdir con argumentos ruta, dir_fd.

Nuevo en la versión 3.3: El parámetro dir_fd.

Distinto en la versión 3.6: Acepta un objeto tipo ruta.

os.scandir(path='.')

Retorna un iterador de objetos os.DirEntry correspondientes a las entradas en el directorio dado por path. Las entradas se entregan en orden arbitrario, y las entradas especiales '.' Y '..' no están incluidas. Si un archivo es removido de o añadido al directorio después de crear el iterador, no se especifica si una entrada para el archivo será incluido.

El uso de scandir() en lugar de listdir() puede aumentar significativamente el rendimiento del código que también necesita información de tipo de archivo o atributo de archivo, porque: los objetos os.DirEntry exponen esta información si el sistema operativo proporciona cuando escanea un directorio. Todos los métodos os.DirEntry pueden realizar una llamada al sistema, pero is_dir() y is_file() generalmente solo requieren una llamada al sistema para enlaces simbólicos; os.DirEntry.stat() siempre requiere una llamada al sistema en Unix, pero solo requiere una para enlaces simbólicos en Windows.

path puede ser un path-like object. Si path es de tipo bytes (directa o indirectamente a través de la interfaz PathLike), el tipo de name y los atributos path de cada os.DirEntry serán bytes; en todas las demás circunstancias, serán del tipo str.

Esta función también puede admitir especificando un descriptor de archivo; el descriptor de archivo debe hacer referencia a un directorio.

Lanza un evento de auditoría os.scandir con argumento ruta.

El iterador scandir() admite el protocolo context manager y tiene el siguiente método:

scandir.close()

Cierre el iterador y libere los recursos adquiridos.

Esto se llama automáticamente cuando el iterador se agota o se recolecta basura, o cuando ocurre un error durante la iteración. Sin embargo, es aconsejable llamarlo explícitamente o utilizar la palabra clave with.

Nuevo en la versión 3.6.

El siguiente ejemplo muestra un uso simple de scandir() para mostrar todos los archivos (excepto los directorios) en la path dada que no comienzan con '.'. La llamada entry.is_file() generalmente no realizará una llamada adicional al sistema:

with os.scandir(path) as it:
    for entry in it:
        if not entry.name.startswith('.') and entry.is_file():
            print(entry.name)

Nota

En sistemas basados en Unix, scandir() usa el opendir() del sistema [http://pubs.opengroup.org/onlinepubs/009695399/functions/opendir.html] y readdir() [http://pubs.opengroup.org/onlinepubs/009695399/functions/readdir_r.html] funciones. En Windows, utiliza el Win32 FindFirstFileW [https://msdn.microsoft.com/en-us/library/windows/desktop/aa364418(v=vs.85).aspx] y FindNextFileW [https://msdn.microsoft.com/en-us/library/windows/desktop/aa364428(v=vs.85).aspx] funciones.

Nuevo en la versión 3.5.

Nuevo en la versión 3.6: Se agregó soporte para el protocolo context manager y el método close(). Si un iterador scandir() no está agotado ni cerrado explícitamente, se emitirá a ResourceWarning en su destructor.

La función acepta un path-like object.

Distinto en la versión 3.7: Soporte agregado para descriptores de archivo en Unix.

class os.DirEntry

Objeto generado por scandir() para exponer la ruta del archivo y otros atributos de archivo de una entrada de directorio.

scandir() proporcionará tanta información como sea posible sin hacer llamadas adicionales al sistema. Cuando se realiza una llamada al sistema stat() o lstat(), el objeto os.DirEntry almacenará en caché el resultado.

Las instancias os.DirEntry no están destinadas a ser almacenadas en estructuras de datos de larga duración; si sabe que los metadatos del archivo han cambiado o si ha transcurrido mucho tiempo desde la llamada scandir(), llame a os.stat(entry.path) para obtener información actualizada.

Debido a que los métodos os.DirEntry pueden hacer llamadas al sistema operativo, también pueden generar OSError. Si necesita un control muy preciso sobre los errores, puede detectar OSError cuando llame a uno de los métodos os.DirEntry y maneje según corresponda.

Para ser directamente utilizable como path-like object, os.DirEntry implementa la interfaz PathLike.

Los atributos y métodos en una instancia de os.DirEntry son los siguientes:

name

El nombre de archivo base de la entrada, relativo al argumento scandir() path.

El atributo name será bytes si el argumento scandir() path es de tipo bytes y str de lo contrario. Utilice fsdecode() para decodificar los nombres de archivo de bytes.

path

El nombre completo de la ruta de entrada: equivalente a os.path.join(scandir_path, entry.name) donde scandir_path es el argumento scandir() path. La ruta solo es absoluta si el argumento scandir() path fue absoluto. Si el argumento scandir() path era un descriptor de archivo, el atributo path es el mismo que el atributo name.

El atributo path será bytes si el argumento scandir() path es de tipo bytes y str de lo contrario. Utilice fsdecode() para decodificar los nombres de archivo de bytes.

inode()

Retorna el número de inodo de la entrada.

El resultado se almacena en caché en el objeto os.DirEntry. Use os.stat(entry.path, follow_symlinks=False).st_ino para obtener información actualizada.

En la primera llamada no almacenada en caché, se requiere una llamada del sistema en Windows pero no en Unix.

is_dir(*, follow_symlinks=True)

Retorna True si esta entrada es un directorio o un enlace simbólico que apunta a un directorio; retorna False si la entrada es o apunta a cualquier otro tipo de archivo, o si ya no existe.

Si follow_symlinks es False, retorna True solo si esta entrada es un directorio (sin seguir los enlaces simbólicos); retorna False si la entrada es cualquier otro tipo de archivo o si ya no existe.

El resultado se almacena en caché en el objeto os.DirEntry, con un caché separado para follow_symlinks True y False. Llame a os.stat() junto con stat.S_ISDIR() para obtener información actualizada.

En la primera llamada no almacenada en caché, no se requiere ninguna llamada al sistema en la mayoría de los casos. Específicamente, para los enlaces no simbólicos, ni Windows ni Unix requieren una llamada al sistema, excepto en ciertos sistemas de archivos Unix, como los sistemas de archivos de red, que retornan dirent.d_type == DT_UNKNOWN. Si la entrada es un enlace simbólico, se requerirá una llamada al sistema para seguir el enlace simbólico a menos que follow_symlinks sea False.

Este método puede generar OSError, como PermissionError, pero FileNotFoundError se captura y no se genera.

is_file(*, follow_symlinks=True)

Retorna True si esta entrada es un archivo o un enlace simbólico que apunta a un archivo; retorna False si la entrada es o apunta a un directorio u otra entrada que no sea de archivo, o si ya no existe.

Si follow_symlinks es False, retorna True solo si esta entrada es un archivo (sin los siguientes enlaces simbólicos); retorna False si la entrada es un directorio u otra entrada que no sea de archivo, o si ya no existe.

El resultado se almacena en caché en el objeto os.DirEntry. El almacenamiento en caché, las llamadas realizadas al sistema y las excepciones generadas son las siguientes is_dir().

is_symlink()

Retorna True si esta entrada es un enlace simbólico (incluso si está roto); retorna False si la entrada apunta a un directorio o cualquier tipo de archivo, o si ya no existe.

El resultado se almacena en caché en el objeto os.DirEntry. Llame a os.path.islink() para obtener información actualizada.

En la primera llamada no almacenada en caché, no se requiere ninguna llamada al sistema en la mayoría de los casos. Específicamente, ni Windows ni Unix requieren una llamada al sistema, excepto en ciertos sistemas de archivos Unix, como los sistemas de archivos de red, que retornan dirent.d_type == DT_UNKNOWN.

Este método puede generar OSError, como PermissionError, pero FileNotFoundError se captura y no se genera.

stat(*, follow_symlinks=True)

Retorna un objeto a stat_result para esta entrada. Este método sigue enlaces simbólicos por defecto; para crear un enlace simbólico agregue el argumento follow_symlinks=False.

En Unix, este método siempre requiere una llamada al sistema. En Windows, solo requiere una llamada al sistema si follow_symlinks es True y la entrada es un punto de análisis (por ejemplo, un enlace simbólico o una unión de directorio).

En Windows, los atributos st_ino, st_dev y st_nlink de stat_result siempre se establecen en cero. Llame a os.stat() para obtener estos atributos.

El resultado se almacena en caché en el objeto os.DirEntry, con un caché separado para follow_symlinks True y False. Llame a os.stat() para obtener información actualizada.

Tenga en cuenta que existe una buena correspondencia entre varios atributos y métodos de os.DirEntry y de pathlib.Path. En particular, el atributo name tiene el mismo significado, al igual que los métodos is_dir(), is_file(), is_symlink() y stat().

Nuevo en la versión 3.5.

Distinto en la versión 3.6: Se agregó soporte para la interfaz PathLike. Se agregó soporte para rutas de bytes en Windows.

os.stat(path, *, dir_fd=None, follow_symlinks=True)

Obtener el estado de un archivo o un descriptor de archivo. Realice el equivalente de a llamada del sistema stat() en la ruta dada. path puede especificarse como una cadena o bytes, directa o indirectamente a través de la interfaz PathLike, o como un descriptor de archivo abierto. Retorna un objeto stat_result.

Esta función normalmente sigue enlaces simbólicos; para crear un enlace simbólico agregue el argumento follow_symlinks=False, o use lstat().

Esta función puede soportar especificando un descriptor de archivo y no siguen enlaces simbólicos.

En Windows, pasar follow_symlinks=False deshabilitará el seguimiento de todos los puntos de análisis sustitutos de nombre, que incluyen enlaces simbólicos y uniones de directorio. Se abrirán directamente otros tipos de puntos de análisis que no se parecen a los enlaces o que el sistema operativo no puede seguir. Al seguir una cadena de enlaces múltiples, esto puede dar como resultado que se retorna el enlace original en lugar del no enlace que impidió el recorrido completo. Para obtener resultados estadísticos para la ruta final en este caso, use la función os.path.realpath() para resolver el nombre de la ruta lo más posible y llame a lstat() en el resultado. Esto no se aplica a enlaces simbólicos o puntos de unión colgantes, lo que generará las excepciones habituales.

El diseño de todos los módulos incorporados de Python dependientes del sistema operativo es tal que, mientras funcionalidad esté disponible, usará la misma interfaz; por ejemplo, la función os.stat(path) retorna estadísticas sobre la ruta (path) en el mismo formato (lo que sucede originalmente con la interfaz POSIX).

>>> import os
>>> statinfo = os.stat('somefile.txt')
>>> statinfo
os.stat_result(st_mode=33188, st_ino=7876932, st_dev=234881026,
st_nlink=1, st_uid=501, st_gid=501, st_size=264, st_atime=1297230295,
st_mtime=1297230027, st_ctime=1297230027)
>>> statinfo.st_size
264

Ver también

fstat() y funciones lstat().

Nuevo en la versión 3.3: Se agregaron los argumentos dir_fd y follow_symlinks, especificando un descriptor de archivo en lugar de una ruta.

Distinto en la versión 3.6: Acepta un objeto tipo ruta.

Distinto en la versión 3.8: En Windows, ahora se siguen todos los puntos de análisis que el sistema operativo puede resolver, y pasar follow_symlinks=False desactiva los siguientes puntos de análisis sustitutos de nombre. Si el sistema operativo alcanza un punto de análisis que no puede seguir, stat ahora retorna la información de la ruta original como si se hubiera especificado follow_symlinks=False en lugar de generar un error.

class os.stat_result

Objeto cuyos atributos corresponden aproximadamente a los miembros de la estructura stat. Se utiliza para el resultado de os.stat(), os.fstat() y os.lstat().

Atributos:

st_mode

Modo de archivo: tipo de archivo y bits de modo de archivo (permisos).

st_ino

Dependiendo de la plataforma, pero si no es cero, identifica de forma exclusiva el archivo para un valor dado de st_dev. Típicamente:

el número de inodo en Unix,

el índice del archivo <https://msdn.microsoft.com/en-us/library/aa363788>`_ en Windows

st_dev

Identificador del dispositivo en el que reside este archivo.

st_nlink

Número de enlaces duros.

st_uid

Identificador de usuario del propietario del archivo.

st_gid

Identificador de grupo del propietario del archivo.

st_size

Tamaño del archivo en bytes, si es un archivo normal o un enlace simbólico. El tamaño de un enlace simbólico es la longitud del nombre de ruta que contiene, sin un byte nulo de terminación.

Marcas de tiempo:

st_atime

Tiempo de acceso más reciente expresado en segundos.

st_mtime

Tiempo de modificación de contenido más reciente expresado en segundos.

st_ctime

Depende de la plataforma:

el momento del cambio de metadatos más reciente en Unix,

el tiempo de creación en Windows, expresado en segundos.

st_atime_ns

Tiempo de acceso más reciente expresado en nanosegundos como un entero.

st_mtime_ns

Hora de la modificación de contenido más reciente expresada en nanosegundos como un entero.

st_ctime_ns

Depende de la plataforma:

el momento del cambio de metadatos más reciente en Unix,

el tiempo de creación en Windows, expresado en nanosegundos como un entero.

Nota

El significado exacto y la resolución de los atributos st_atime, st_mtime y st_ctime dependen del sistema operativo y del sistema de archivos. Por ejemplo, en sistemas Windows que utilizan los sistemas de archivos FAT o FAT32, st_mtime tiene una resolución de 2 segundos y st_atime tiene una resolución de solo 1 día. Consulte la documentación de su sistema operativo para más detalles.

De manera similar, aunque st_atime_ns, st_mtime_ns y st_ctime_ns siempre se expresan en nanosegundos, muchos sistemas no proporcionan precisión en nanosegundos. En los sistemas que proporcionan precisión en nanosegundos, el objeto de punto flotante utilizado para almacenar st_atime, st_mtime, y st_ctime no puede preservarlo todo, y como tal será ligeramente inexacto . Si necesita las marcas de tiempo exactas, siempre debe usar st_atime_ns, st_mtime_ns y st_ctime_ns.

En algunos sistemas Unix (como Linux), los siguientes atributos también pueden estar disponibles:

st_blocks

Número de bloques de 512 bytes asignados para el archivo. Esto puede ser más pequeño que st_size / 512 cuando el archivo tiene agujeros.

st_blksize

Tamaño de bloque «preferido» para una eficiente E / S del sistema de archivos. Escribir en un archivo en fragmentos más pequeños puede causar una lectura-modificación-reescritura ineficiente.

st_rdev

Tipo de dispositivo si es un dispositivo inodo.

st_flags

Indicadores definidos por el usuario para el archivo.

En otros sistemas Unix (como FreeBSD), los siguientes atributos pueden estar disponibles (pero solo se pueden completar si la raíz intenta usarlos):

st_gen

Número de generación de archivos.

st_birthtime

Hora de creación del archivo.

En Solaris y derivados, los siguientes atributos también pueden estar disponibles:

st_fstype

Cadena que identifica de forma exclusiva el tipo de sistema de archivos que contiene el archivo.

On macOS systems, the following attributes may also be available:

st_rsize

Tamaño real del archivo.

st_creator

Creador del archivo.

st_type

Tipo de archivo.

En los sistemas Windows, los siguientes atributos también están disponibles:

st_file_attributes

Atributos del archivo de Windows: miembro dwFileAttributes de la estructura BY_HANDLE_FILE_INFORMATION retornado por GetFileInformationByHandle(). Vea las constantes FILE_ATTRIBUTE_* en el módulo stat.

st_reparse_tag

Cuando st_file_attributes tiene el conjunto` FILE_ATTRIBUTE_REPARSE_POINT`, este campo contiene la etiqueta que identifica el tipo de punto de análisis. Vea las constantes IO_REPARSE_TAG_* en el módulo stat.

El módulo estándar stat define funciones y constantes que son útiles para extraer información de la estructura a stat. (En Windows, algunos elementos están llenos de valores ficticios).

Para compatibilidad con versiones anteriores, una instancia de stat_result también es accesible como una tupla de al menos 10 enteros que dan los miembros más importantes (y portátiles) de la estructura stat, en el orden st_mode, st_ino, st_dev, st_nlink, st_uid, st_gid, st_size, st_atime, st_mtime, st_ctime. Algunas implementaciones pueden agregar más elementos al final. Para compatibilidad con versiones anteriores de Python, acceder a stat_result como una tupla siempre retorna enteros.

Nuevo en la versión 3.3: Se agregaron los miembros st_atime_ns, st_mtime_ns y st_ctime_ns.

Nuevo en la versión 3.5: Se agregó el miembro st_file_attributes en Windows.

Distinto en la versión 3.5: Windows ahora retorna el índice del archivo como st_ino cuando está disponible.

Nuevo en la versión 3.7: Se agregó el miembro st_fstype a Solaris/derivados.

Nuevo en la versión 3.8: Se agregó el miembro st_reparse_tag en Windows.

Distinto en la versión 3.8: En Windows, el miembro st_mode ahora identifica archivos especiales como S_IFCHR, S_IFIFO o S_IFBLK según corresponda.

os.statvfs(path)

Realice una llamada al sistema a statvfs() en la ruta dada. El valor de retorno es un objeto cuyos atributos describen el sistema de archivos en la ruta dada y corresponden a los miembros de la estructura statvfs, a saber: f_bsize, f_frsize, f_blocks, f_bfree, f_bavail, f_files, f_ffree, f_favail, f_flag, f_namemax, f_fsid.

Se definen dos constantes de nivel de módulo para: indicadores de bit del atributo f_flag: si ST_RDONLY está configurado, el sistema de archivos está montado de solo lectura, y si ST_NOSUID está configurado, el la semántica de los bits setuid/setgid está deshabilitada o no es compatible.

Se definen constantes de nivel de módulo adicionales para sistemas basados en GNU / glibc. Estos son ST_NODEV (no permitir el acceso a archivos especiales del dispositivo), ST_NOEXEC (no permitir la ejecución del programa), ST_SYNCHRONOUS (las escrituras se sincronizan a la vez), ST_MANDLOCK ( permitir bloqueos obligatorios en un FS), ST_WRITE (escribir en el archivo/directorio/enlace simbólico), ST_APPEND (archivo de solo agregado), ST_IMMUTABLE (archivo inmutable), ST_NOATIME (no actualiza los tiempos de acceso), ST_NODIRATIME (no actualiza los tiempos de acceso al directorio), ST_RELATIME (tiempo de actualización relativo a mtime/ctime).

Esta función puede soportar especificando un descriptor de archivo.

Disponibilidad: Unix.

Distinto en la versión 3.2: Se agregaron las constantes ST_RDONLY y ST_NOSUID.

Nuevo en la versión 3.3: Se agregó soporte para especificar path como un descriptor de archivo abierto.

Distinto en la versión 3.4: El ST_NODEV, ST_NOEXEC, ST_SYNCHRONOUS, ST_MANDLOCK, ST_WRITE, ST_APPEND, ST_IMMUTABLE, ST_NOATIME, ST_NODIRATIME, y ST_RELATIME se agregaron constantes.

Distinto en la versión 3.6: Acepta un objeto tipo ruta.

Nuevo en la versión 3.7: Agregado f_fsid.

os.supports_dir_fd

A objeto set que indica qué funciones en el módulo os aceptan un descriptor de archivo abierto para su parámetro dir_fd. Las diferentes plataformas proporcionan características diferentes, y la funcionalidad subyacente que Python usa para implementar el parámetro dir_fd no está disponible en todas las plataformas que admite Python. En aras de la coherencia, las funciones que pueden admitir dir_fd siempre permiten especificar el parámetro, pero generarán una excepción si la funcionalidad se utiliza cuando no está disponible localmente. (Especificar None para dir_fd siempre es compatible con todas las plataformas).

Para verificar si una función particular acepta un descriptor de archivo abierto para su parámetro dir_fd, use el operador in en supports_dir_fd. Como ejemplo, esta expresión se evalúa como True si os.stat() acepta descriptores de archivos abiertos para dir_fd en la plataforma local:

os.stat in os.supports_dir_fd

Actualmente, los parámetros dir_fd solo funcionan en plataformas Unix; ninguno de ellos funciona en Windows.

Nuevo en la versión 3.3.

os.supports_effective_ids

Un objeto set que indica si os.access() permite especificar True para su parámetro fective_ids en la plataforma local. (Especificar False para effective_id siempre es compatible con todas las plataformas). Si la plataforma local lo admite, la colección contendrá os.access(); de lo contrario estará vacío.

Esta expresión se evalúa como True si os.access() admite effective_id=True en la plataforma local:

os.access in os.supports_effective_ids

Actualmente, effective_ids solo es compatible con plataformas Unix; No funciona en Windows.

Nuevo en la versión 3.3.

os.supports_fd

A objeto set que indica qué funciones en el módulo os permiten especificar su parámetro path como un descriptor de archivo abierto en la plataforma local. Las diferentes plataformas proporcionan características diferentes, y la funcionalidad subyacente que Python utiliza para aceptar descriptores de archivos abiertos como argumentos path no está disponible en todas las plataformas que admite Python.

Para determinar si una función en particular permite especificar un descriptor de archivo abierto para su parámetro path, use el operador in en supports_fd. Como ejemplo, esta expresión se evalúa como True si os.chdir() acepta descriptores de archivo abiertos para path en su plataforma local:

os.chdir in os.supports_fd

Nuevo en la versión 3.3.

os.supports_follow_symlinks

Un objeto set que indica qué funciones en el módulo os aceptan False para su parámetro follow_symlinks en la plataforma local. Las diferentes plataformas proporcionan características diferentes, y la funcionalidad subyacente que Python usa para implementar follow_symlinks no está disponible en todas las plataformas que admite Python. En aras de la coherencia, las funciones que pueden admitir follow_symlinks siempre permiten especificar el parámetro, pero arrojarán una excepción si la funcionalidad se utiliza cuando no está disponible localmente. (Especificar True para follow_symlinks siempre se admite en todas las plataformas).

Para verificar si una función particular acepta False para su parámetro follow_symlinks, use el operador in en supports_follow_symlinks. Como ejemplo, esta expresión se evalúa como True si puede especificar follow_symlinks=False al llamar a os.stat() en la plataforma local:

os.stat in os.supports_follow_symlinks

Nuevo en la versión 3.3.

os.symlink(src, dst, target_is_directory=False, *, dir_fd=None)

Cree un enlace simbólico que apunte a src llamado dst.

En Windows, un enlace simbólico representa un archivo o un directorio, y no se transforma dinámicamente en el destino. Si el objetivo está presente, el tipo de enlace simbólico se creará para que coincida. De lo contrario, el enlace simbólico se creará como un directorio si target_is_directory es True o un enlace simbólico de archivo (el valor predeterminado) de lo contrario. En plataformas que no son de Windows, target_is_directory se ignora.

Esta función puede admitir rutas relativas a descriptores de directorio.

Nota

En las versiones más recientes de Windows 10, las cuentas sin privilegios pueden crear enlaces simbólicos si el Modo desarrollador está habilitado. Cuando el Modo desarrollador no está disponible / habilitado, se requiere el privilegio SeCreateSymbolicLinkPrivilege, o el proceso debe ejecutarse como administrador.

OSError se lanza cuando un usuario sin privilegios llama a la función.

Lanza un evento de auditoría os.symlink con argumentos src, dst, dir_fd.

Disponibilidad: Unix, Windows.

Distinto en la versión 3.2: Se agregó soporte para enlaces simbólicos de Windows 6.0 (Vista).

Nuevo en la versión 3.3: Se agregó el argumento dir_fd y ahora permite target_is_directory en plataformas que no son de Windows.

Distinto en la versión 3.6: Acepta un path-like object para src y dst.

Distinto en la versión 3.8: Se agregó soporte para enlaces simbólicos sin elevar en Windows con el modo de desarrollador.

os.sync()

Forzar la escritura de todo en el disco.

Disponibilidad: Unix.

Nuevo en la versión 3.3.

os.truncate(path, length)

Trunca el archivo correspondiente a path, para que tenga como máximo length bytes de tamaño.

Esta función puede soportar especificando un descriptor de archivo.

Lanza un evento de auditoría os.truncate con argumentos path, length.

Disponibilidad: Unix, Windows.

Nuevo en la versión 3.3.

Distinto en la versión 3.5: Se agregó soporte para Windows

Distinto en la versión 3.6: Acepta un objeto tipo ruta.

os.unlink(path, *, dir_fd=None)

Elimina (elimine) el archivo path. Esta función es semánticamente idéntica a remove(); El nombre unlink es su nombre tradicional de Unix. Consulte la documentación de remove() para obtener más información.

Lanza un evento de auditoría os.remove con argumentos ruta, dir_fd.

Nuevo en la versión 3.3: El parámetro dir_fd.

Distinto en la versión 3.6: Acepta un objeto tipo ruta.

os.utime(path, times=None, *, [ns, ]dir_fd=None, follow_symlinks=True)

Establece el acceso y los tiempos modificados del archivo especificado por path.

utime() toma dos parámetros opcionales, times y ns. Estos especifican los tiempos establecidos en path y se utilizan de la siguiente manera:

Si se especifica ns, debe ser una tupla de 2 de la forma (atime_ns, mtime_ns) donde cada miembro es un int que expresa nanosegundos.

Si times no es None, debe ser una 2-tupla de la forma (atime, mtime) donde cada miembro es un int o flotante que expresa segundos.

Si times es None y ns no está especificado, esto es equivalente a especificar ns=(atime_ns, mtime_ns) donde ambas horas son la hora actual.

Es un error especificar tuplas para times y ns.

Tenga en cuenta que las horas exactas que establezca aquí pueden no ser retornadas por una llamada posterior stat(), dependiendo de la resolución con la que su sistema operativo registre los tiempos de acceso y modificación; ver stat(). La mejor manera de preservar los tiempos exactos es usar los campos st_atime_ns y st_mtime_ns del objeto de resultado os.stat() con el parámetro ns para utime.

Esta función puede soportar especificando un descriptor de archivo, rutas relativas a los descriptores de directorio y no seguir enlaces simbólicos.

Lanza un evento de auditoría os.utime con argumentos path, times, ns, dir_fd.

Nuevo en la versión 3.3: Se agregó soporte para especificar path como un descriptor de archivo abierto, y los parámetros dir_fd, follow_symlinks y ns.

Distinto en la versión 3.6: Acepta un objeto tipo ruta.

os.walk(top, topdown=True, onerror=None, followlinks=False)

Genere los nombres de archivo en un árbol de directorios recorriendo el árbol de arriba hacia abajo o de abajo hacia arriba. Para cada directorio en el árbol enraizado en el directorio top (incluido top), produce una tupla de 3 tuplas (dirpath, dirnames, filenames).

dirpath es una cadena, la ruta al directorio. dirnames es una lista de los nombres de los subdirectorios en dirpath (excluyendo '.' y '..'). filenames es una lista de los nombres de los archivos que no son un directorio en dirpath. Tenga en cuenta que los nombres en las listas no contienen componentes de ruta. Para obtener una ruta completa (que comienza con top) a un archivo o directorio en dirpath, haga os.path.join(dirpath, name). El hecho de que las lista esta ordenada o no depende del sistema de archivos. Si un archivo es removido de o agregado al directorio dirpath mientras se generan las listas, no se especifica si el nombre para el archivo será incluido.

Si el argumento opcional topdown es True o no se especifica, el triple para un directorio se genera antes de triplicarse para cualquiera de sus subdirectorios (los directorios se generan de arriba hacia abajo). Si topdown es False, el triple para un directorio se genera después de los triples para todos sus subdirectorios (los directorios se generan de abajo hacia arriba). No importa el valor de topdown, la lista de subdirectorios se recupera antes de que se generen las tuplas para el directorio y sus subdirectorios.

Cuando topdown es True, la persona que llama puede modificar la lista dirnames en su lugar (quizás usando del o asignación de corte) y walk() solo se repetirá en los subdirectorios cuyos nombres permanecen en dirnames; Esto se puede utilizar para podar la búsqueda, imponer un orden específico de visitas o incluso para informar walk() sobre los directorios que la persona que llama crea o renombra antes de que se reanude walk() nuevamente. La modificación de dirnames cuando topdown es False no tiene ningún efecto en el comportamiento de la caminata, porque en el modo ascendente los directorios en dirnames se generan antes de que se genere dirpath.

Por defecto, los errores de la llamada scandir() se ignoran. Si se especifica el argumento opcional onerror, debería ser una función; se llamará con un argumento, una instancia OSError. Puede informar el error para continuar con la caminata, o generar la excepción para abortar la caminata. Tenga en cuenta que el nombre de archivo está disponible como el atributo filename del objeto de excepción.

Por defecto, walk() no entrará en enlaces simbólicos que se resuelven en directorios. Establece followlinks en True para visitar los directorios señalados por los enlaces simbólicos, en los sistemas que los admiten.

Nota

Tenga en cuenta que establecer followlinks en True puede conducir a una recursión infinita si un enlace apunta a un directorio padre de sí mismo. walk() no realiza un seguimiento de los directorios que ya visitó.

Nota

Si pasa un nombre de ruta relativo, no cambie el directorio de trabajo actual entre las reanudaciones de walk(). walk() nunca cambia el directorio actual, y supone que la persona que llama tampoco.

Este ejemplo muestra el número de bytes que toman los archivos que no son de directorio en cada directorio bajo el directorio inicial, excepto que no se ve en ningún subdirectorio CVS:

import os
from os.path import join, getsize
for root, dirs, files in os.walk('python/Lib/email'):
    print(root, "consumes", end=" ")
    print(sum(getsize(join(root, name)) for name in files), end=" ")
    print("bytes in", len(files), "non-directory files")
    if 'CVS' in dirs:
        dirs.remove('CVS')  # don't visit CVS directories

En el siguiente ejemplo (implementación simple de shutil.rmtree()), recorrer el árbol de abajo hacia arriba es esencial, rmdir() no permite eliminar un directorio antes de que el directorio esté vacío:

# Delete everything reachable from the directory named in "top",
# assuming there are no symbolic links.
# CAUTION:  This is dangerous!  For example, if top == '/', it
# could delete all your disk files.
import os
for root, dirs, files in os.walk(top, topdown=False):
    for name in files:
        os.remove(os.path.join(root, name))
    for name in dirs:
        os.rmdir(os.path.join(root, name))

Lanza un evento de auditoría os.spawn con argumentos top, topdown, onerror, followlinks.

Distinto en la versión 3.5: Esta función ahora llama os.scandir() en lugar de os.listdir(), lo que lo hace más rápido al reducir el número de llamadas a os.stat().

Distinto en la versión 3.6: Acepta un objeto tipo ruta.

os.fwalk(top='.', topdown=True, onerror=None, *, follow_symlinks=False, dir_fd=None)

Esto se comporta exactamente como walk(), excepto que produce 4 tuplas (dirpath, dirnames, filenames, dirfd), y admite dir_fd.

dirpath, dirnames y filenames son idénticos a walk() output, y dirfd es un descriptor de archivo que se refiere al directorio dirpath.

Esta función siempre admite rutas relativas a descriptores de directorio y no siguen enlaces simbólicos. Sin embargo, tenga en cuenta que, a diferencia de otras funciones, el valor predeterminado fwalk() para follow_symlinks es False.

Nota

Dado que fwalk() produce descriptores de archivo, estos solo son válidos hasta el siguiente paso de iteración, por lo que debe duplicarlos (por ejemplo, con dup()) si desea mantenerlos más tiempo.

Este ejemplo muestra el número de bytes que toman los archivos que no son de directorio en cada directorio bajo el directorio inicial, excepto que no se ve en ningún subdirectorio CVS:

import os
for root, dirs, files, rootfd in os.fwalk('python/Lib/email'):
    print(root, "consumes", end="")
    print(sum([os.stat(name, dir_fd=rootfd).st_size for name in files]),
          end="")
    print("bytes in", len(files), "non-directory files")
    if 'CVS' in dirs:
        dirs.remove('CVS')  # don't visit CVS directories

En el siguiente ejemplo, recorrer el árbol de abajo hacia arriba es esencial: rmdir() no permite eliminar un directorio antes de que el directorio esté vacío:

# Delete everything reachable from the directory named in "top",
# assuming there are no symbolic links.
# CAUTION:  This is dangerous!  For example, if top == '/', it
# could delete all your disk files.
import os
for root, dirs, files, rootfd in os.fwalk(top, topdown=False):
    for name in files:
        os.unlink(name, dir_fd=rootfd)
    for name in dirs:
        os.rmdir(name, dir_fd=rootfd)

Lanza un evento de auditoría os.chown con argumentos top, topdown, onerror, follow_symlinks, dir_fd.

Disponibilidad: Unix.

Nuevo en la versión 3.3.

Distinto en la versión 3.6: Acepta un objeto tipo ruta.

Distinto en la versión 3.7: Se agregó soporte para rutas de acceso bytes.

os.memfd_create(name[, flags=os.MFD_CLOEXEC])

Cree un archivo anónimo y retorna un descriptor de archivo que se refiera a él. flags debe ser una de las constantes os.MFD_* disponibles en el sistema (o una combinación ORed bit a bit de ellas). Por defecto, el nuevo descriptor de archivo es no heredable.

El nombre proporcionado en name se utiliza como nombre de archivo y se mostrará como el destino del enlace simbólico correspondiente en el directorio /proc/self/fd/. El nombre que se muestra siempre tiene el prefijo memfd: y solo sirve para fines de depuración. Los nombres no afectan el comportamiento del descriptor de archivo y, como tal, varios archivos pueden tener el mismo nombre sin efectos secundarios.

Disponibilidad: Linux 3.17 o posterior con glibc 2.27 o posterior.

Nuevo en la versión 3.8.

os.MFD_CLOEXEC

os.MFD_ALLOW_SEALING

os.MFD_HUGETLB

os.MFD_HUGE_SHIFT

os.MFD_HUGE_MASK

os.MFD_HUGE_64KB

os.MFD_HUGE_512KB

os.MFD_HUGE_1MB

os.MFD_HUGE_2MB

os.MFD_HUGE_8MB

os.MFD_HUGE_16MB

os.MFD_HUGE_32MB

os.MFD_HUGE_256MB

os.MFD_HUGE_512MB

os.MFD_HUGE_1GB

os.MFD_HUGE_2GB

os.MFD_HUGE_16GB

Estas flags se pueden pasar a memfd_create().

Disponibilidad: Linux 3.17 o posterior con glibc 2.27 o posterior. Los indicadores MFD_HUGE* solo están disponibles desde Linux 4.14.

Nuevo en la versión 3.8.

Atributos extendidos de Linux

Nuevo en la versión 3.3.

Estas funciones están disponibles solo en Linux.

os.getxattr(path, attribute, *, follow_symlinks=True)

Retorna el valor del atributo del sistema de archivos extendido atrribute para path. attribute puede ser bytes o str (directa o indirectamente a través de la interfaz PathLike). Si es str, se codifica con la codificación del sistema de archivos.

Esta función puede soportar especificando un descriptor de archivo y no siguen enlaces simbólicos.

Lanza un evento de auditoría os.getxattr con argumentos path, atributo.

Distinto en la versión 3.6: Acepta un path-like object para path*y *attribute.

os.listxattr(path=None, *, follow_symlinks=True)

Retorna una lista de los atributos del sistema de archivos extendido en path. Los atributos en la lista se representan como cadenas decodificadas con la codificación del sistema de archivos. Si path es None, listxattr() examinará el directorio actual.

Esta función puede soportar especificando un descriptor de archivo y no siguen enlaces simbólicos.

Lanza un evento de auditoría os.listxattr con el argumento path.

Distinto en la versión 3.6: Acepta un objeto tipo ruta.

os.removexattr(path, attribute, *, follow_symlinks=True)

Elimina el atributo del sistema de archivos extendido attribute de path. attribute debe ser bytes o str (directa o indirectamente a través de la interfaz PathLike). Si es una cadena, se codifica con la codificación del sistema de archivos.

Esta función puede soportar especificando un descriptor de archivo y no siguen enlaces simbólicos.

Lanza un evento de auditoría os.removexattr con argumentos path, attribute.

Distinto en la versión 3.6: Acepta un path-like object para path*y *attribute.

os.setxattr(path, attribute, value, flags=0, *, follow_symlinks=True)

Set the extended filesystem attribute attribute on path to value. attribute must be a bytes or str with no embedded NULs (directly or indirectly through the PathLike interface). If it is a str, it is encoded with the filesystem encoding. flags may be XATTR_REPLACE or XATTR_CREATE. If XATTR_REPLACE is given and the attribute does not exist, ENODATA will be raised. If XATTR_CREATE is given and the attribute already exists, the attribute will not be created and EEXISTS will be raised.

Esta función puede soportar especificando un descriptor de archivo y no siguen enlaces simbólicos.

Nota

Un error en las versiones de kernel de Linux anteriores a 2.6.39 hizo que el argumento de las flags se ignorara en algunos sistemas de archivos.

Lanza un evento de auditoría os.setxattr con argumentos path, attribute, value, flags.

Distinto en la versión 3.6: Acepta un path-like object para path*y *attribute.

os.XATTR_SIZE_MAX

El tamaño máximo que puede tener el valor de un atributo extendido. Actualmente, esto es 64 KiB en Linux.

os.XATTR_CREATE

Este es un valor posible para el argumento flags en setxattr(). Indica que la operación debe crear un atributo.

os.XATTR_REPLACE

Este es un valor posible para el argumento flags en setxattr(). Indica que la operación debe reemplazar un atributo existente.

Gestión de proceso

Estas funciones pueden usarse para crear y administrar procesos.

Las varias funciones exec * toman una lista de argumentos para el nuevo programa cargado en el proceso. En cada caso, el primero de estos argumentos se pasa al nuevo programa como su propio nombre en lugar de como un argumento que un usuario puede haber escrito en una línea de comando. Para el programador C, este es el argv[0] pasado a un programa main(). Por ejemplo, os.execv('/bin/echo', ['foo', 'bar']) solo imprimirá bar en la salida estándar; foo parecerá ignorado.

os.abort()

Genere una señal SIGABRT para el proceso actual. En Unix, el comportamiento predeterminado es producir un volcado de núcleo; en Windows, el proceso retorna inmediatamente un código de salida de 3. Tenga en cuenta que llamar a esta función no llamará al controlador de señal Python registrado para SIGABRT con signal.signal().

os.add_dll_directory(path)

Agregue una ruta a la ruta de búsqueda de DLL.

This search path is used when resolving dependencies for imported extension modules (the module itself is resolved through sys.path), and also by ctypes.

Elimina el directorio llamando a close() en el objeto retornado o utilizándolo en una with instrucción.

Consulte la documentación de Microsoft [https://msdn.microsoft.com/44228cf2-6306-466c-8f16-f513cd3ba8b5] para obtener más información sobre cómo se cargan las DLL.

Lanza un evento de auditoría os.add_dll_directory con el argumento path.

Disponibilidad: Windows.

Nuevo en la versión 3.8: Las versiones anteriores de CPython resolverían las DLL utilizando el comportamiento predeterminado para el proceso actual. Esto condujo a inconsistencias, como solo a veces buscar PATH o el directorio de trabajo actual, y las funciones del sistema operativo como AddDllDirectory no tienen ningún efecto.

En 3.8, las dos formas principales en que se cargan las DLL ahora anulan explícitamente el comportamiento de todo el proceso para garantizar la coherencia. Ver el notas de portabilidad para obtener información sobre la actualización de bibliotecas.

os.execl(path, arg0, arg1, ...)

os.execle(path, arg0, arg1, ..., env)

os.execlp(file, arg0, arg1, ...)

os.execlpe(file, arg0, arg1, ..., env)

os.execv(path, args)

os.execve(path, args, env)

os.execvp(file, args)

os.execvpe(file, args, env)

Todas estas funciones ejecutan un nuevo programa, reemplazando el proceso actual; No vuelven. En Unix, el nuevo ejecutable se carga en el proceso actual y tendrá la misma identificación de proceso que la persona que llama. Los errores se informarán como excepciones OSError.

El proceso actual se reemplaza inmediatamente. Los objetos de archivo abierto y los descriptores no se vacían, por lo que si puede haber datos almacenados en estos archivos abiertos, debe limpiarlos usando sys.stdout.flush() o os.fsync() antes de llamar a exec* función.

Las variantes «l» y «v» de las funciones exec* difieren en cómo se pasan los argumentos de la línea de comandos. Las variantes «l» son quizás las más fáciles de trabajar si el número de parámetros se fija cuando se escribe el código; los parámetros individuales simplemente se convierten en parámetros adicionales a las funciones execl*(). Las variantes «v» son buenas cuando el número de parámetros es variable, y los argumentos se pasan en una lista o tupla como parámetro args. En cualquier caso, los argumentos del proceso secundario deben comenzar con el nombre del comando que se ejecuta, pero esto no se aplica.

Las variantes que incluyen una «p» cerca del final (execlp(), execlpe(), execvp(), y execvpe()) usarán PATH variable de entorno para ubicar el programa file. Cuando se reemplaza el entorno (utilizando uno de los siguientes variantes exec*e variantes, discutidas en el siguiente párrafo), el nuevo entorno se utiliza como fuente de la variable PATH. Las otras variantes, execl(), execle(), execv(), y execve(), no utilizarán la variable PATH para localizar el ejecutable; path debe contener una ruta absoluta o relativa apropiada.

Para execle(), execlpe(), execve() y execvpe() (tenga en cuenta que todo esto termina en «e»), el parámetro env debe ser un mapeo que se utiliza para definir las variables de entorno para el nuevo proceso (se utilizan en lugar del entorno del proceso actual); las funciones execl(), execlp(), execv() y execvp() hacen que el nuevo proceso herede el entorno del proceso actual.

Para execve() en algunas plataformas, path también puede especificarse como un descriptor de archivo abierto. Es posible que esta funcionalidad no sea compatible con su plataforma; puede verificar si está disponible o no usando os.supports_fd. Si no está disponible, su uso generará un NotImplementedError.

Lanza un evento de auditoría os.exec con argumentos ruta, args, env.

Disponibilidad: Unix, Windows.

Nuevo en la versión 3.3: Se agregó soporte para especificar path como un descriptor de archivo abierto para execve().

Distinto en la versión 3.6: Acepta un objeto tipo ruta.

os._exit(n)

Salga del proceso con el estado n, sin llamar a los controladores de limpieza, vaciar los buffers stdio, etc.

Nota

La forma estándar de salir es sys.exit(n). _exit() normalmente solo debe usarse en el proceso secundario después de fork().

Los siguientes códigos de salida están definidos y se pueden usar con _exit(), aunque no son obligatorios. Por lo general, se usan para programas del sistema escritos en Python, como el programa de entrega de comandos externos de un servidor de correo.

Nota

Es posible que algunos de estos no estén disponibles en todas las plataformas Unix, ya que hay alguna variación. Estas constantes se definen donde están definidas por la plataforma subyacente.

os.EX_OK

Código de salida que significa que no se produjo ningún error.

Disponibilidad: Unix.

os.EX_USAGE

Código de salida que significa que el comando se usó incorrectamente, como cuando se da un número incorrecto de argumentos.

Disponibilidad: Unix.

os.EX_DATAERR

Código de salida que significa que los datos de entrada eran incorrectos.

Disponibilidad: Unix.

os.EX_NOINPUT

Código de salida que significa que no existía un archivo de entrada o que no era legible.

Disponibilidad: Unix.

os.EX_NOUSER

Código de salida que significa que un usuario especificado no existía.

Disponibilidad: Unix.

os.EX_NOHOST

Código de salida que significa que no existía un host especificado.

Disponibilidad: Unix.

os.EX_UNAVAILABLE

Código de salida que significa que un servicio requerido no está disponible.

Disponibilidad: Unix.

os.EX_SOFTWARE

Código de salida que significa que se detectó un error interno de software.

Disponibilidad: Unix.

os.EX_OSERR

Código de salida que significa que se detectó un error del sistema operativo, como la imposibilidad de bifurcar o crear una tubería.

Disponibilidad: Unix.

os.EX_OSFILE

Código de salida que significa que algunos archivos del sistema no existían, no podían abrirse o tenían algún otro tipo de error.

Disponibilidad: Unix.

os.EX_CANTCREAT

Código de salida que significa que no se pudo crear un archivo de salida especificado por el usuario.

Disponibilidad: Unix.

os.EX_IOERR

Código de salida que significa que se produjo un error al realizar E / S en algún archivo.

Disponibilidad: Unix.

os.EX_TEMPFAIL

Código de salida que significa que ocurrió una falla temporal. Esto indica algo que puede no ser realmente un error, como una conexión de red que no se pudo realizar durante una operación recuperable.

Disponibilidad: Unix.

os.EX_PROTOCOL

Código de salida que significa que un intercambio de protocolo fue ilegal, inválido o no se entendió.

Disponibilidad: Unix.

os.EX_NOPERM

Código de salida que significa que no había permisos suficientes para realizar la operación (pero no para problemas del sistema de archivos).

Disponibilidad: Unix.

os.EX_CONFIG

Código de salida que significa que se produjo algún tipo de error de configuración.

Disponibilidad: Unix.

os.EX_NOTFOUND

Código de salida que significa algo así como «no se encontró una entrada».

Disponibilidad: Unix.

os.fork()

Bifurcar un proceso hijo. Retorna 0 en el niño y la identificación del proceso del niño en el padre. Si se produce un error se genera OSError.

Tenga en cuenta que algunas plataformas que incluyen FreeBSD &lt;= 6.3 y Cygwin tienen problemas conocidos al usar fork() desde un hilo.

Lanza un evento de auditoría os.fork sin argumentos.

Distinto en la versión 3.8: Llamar a fork() en un subinterpretador ya no es compatible (RuntimeError está activado).

Advertencia

Ver ssl para aplicaciones que usan el módulo SSL con fork().

Disponibilidad: Unix.

os.forkpty()

Bifurca un proceso hijo, usando un nuevo pseudo-terminal como terminal de control del niño. Retorna un par de (pid, fd), donde pid es 0 en el elemento secundario, la identificación del proceso del elemento secundario nuevo en el elemento primario y fd es el descriptor de archivo del final maestro de El pseudo-terminal. Para un enfoque más portátil, use el módulo pty. Si se produce un error se genera OSError.

Lanza un evento de auditoría os.forkpty sin argumentos.

Distinto en la versión 3.8: Llamar a forkpty() en un subinterpretador ya no es compatible (RuntimeError está activado).

Disponibilidad: algunos sistemas tipo Unix.

os.kill(pid, sig)

Enviar señal sig al proceso pid. Las constantes para las señales específicas disponibles en la plataforma host se definen en el módulo signal.

Windows: Las señales signal.CTRL_C_EVENT y signal.CTRL_BREAK_EVENT son señales especiales que solo pueden enviarse a procesos de consola que comparten una ventana de consola común, por ejemplo, algunos subprocesos. Cualquier otro valor para sig hará que la API TerminateProcess elimine el proceso incondicionalmente, y el código de salida se establecerá en sig. La versión de Windows de kill() también requiere que los identificadores de proceso sean eliminados.

Ver también signal.pthread_kill().

Lanza un evento de auditoría os.kill con argumentos pid, sig.

Nuevo en la versión 3.2: Soporte de Windows.

os.killpg(pgid, sig)

Envíe la señal sig al grupo de procesos pgid.

Lanza un evento de auditoría os.killpg con argumentos pgid, sig.

Disponibilidad: Unix.

os.nice(increment)

Agregue increment a la «simpatía» del proceso. Retorna la nueva amabilidad.

Disponibilidad: Unix.

os.pidfd_open(pid, flags=0)

Retorna un descriptor de archivo referente al pid del proceso. Este descriptor puede ser usado para realizar gestión de procesos sin necesidad de señales y carreras. El argumento flags es proporcionado para extensiones futuras; ningún valor se encuentra definido en las banderas actualmente.

Ver la página manual de pidfd_open(2) para mas detalles.

Disponibilidad: Linux 5.3+

Nuevo en la versión 3.9.

os.plock(op)

Bloquee segmentos del programa en la memoria. El valor de op (definido en <sys/lock.h>) determina qué segmentos están bloqueados.

Disponibilidad: Unix.

os.popen(cmd, mode='r', buffering=-1)

Abra una tubería hacia o desde el comando cmd. El valor de retorno es un objeto de archivo abierto conectado a la tubería, que puede leerse o escribirse dependiendo de si mode es 'r' (predeterminado) o 'w'. El argumento buffering tiene el mismo significado que el argumento correspondiente a la función incorporada open(). El objeto de archivo retornado lee o escribe cadenas de texto en lugar de bytes.

El método close retorna None si el subproceso salió correctamente, o el código de retorno del subproceso si hubo un error. En los sistemas POSIX, si el código de retorno es positivo, representa el valor de retorno del proceso desplazado a la izquierda en un byte. Si el código de retorno es negativo, el proceso fue terminado por la señal dada por el valor negado del código de retorno. (Por ejemplo, el valor de retorno podría ser - signal.SIGKILL si se eliminó el subproceso). En los sistemas Windows, el valor de retorno contiene el código de retorno entero firmado del proceso secundario.

En Unix, waitstatus_to_exitcode() puede ser usado para convertir el resultado del método close (estado de salida) en un código de salida si es que no es None. En Windows, el resultado del método close es directamente el código de salida (o None).

Esto se implementa usando subprocess.Popen; consulte la documentación de esa clase para obtener formas más potentes de administrar y comunicarse con subprocesos.

os.posix_spawn(path, argv, env, *, file_actions=None, setpgroup=None, resetids=False, setsid=False, setsigmask=(), setsigdef=(), scheduler=None)

Envuelve la API de la biblioteca C posix_spawn() para usar desde Python.

La mayoría de los usuarios deberían usar subprocess.run() en lugar de posix_spawn().

Los argumentos de solo posición path, args y env son similares a execve().

El parámetro path es la ruta al archivo ejecutable. La path debe contener un directorio. Utilice posix_spawnp() para pasar un archivo ejecutable sin directorio.

El argumento file_actions puede ser una secuencia de tuplas que describen acciones para tomar descriptores de archivo específicos en el proceso secundario entre los pasos de implementación de la biblioteca C fork() y exec(). El primer elemento de cada tupla debe ser uno de los tres indicadores de tipo que se enumeran a continuación y que describen los elementos de tupla restantes:

os.POSIX_SPAWN_OPEN

(os.POSIX_SPAWN_OPEN, fd, path, flags, mode)

Realiza os.dup2(os.open(path, flags, mode), fd).

os.POSIX_SPAWN_CLOSE

(os.POSIX_SPAWN_CLOSE, fd)

Realiza os.close(fd).

os.POSIX_SPAWN_DUP2

(os.POSIX_SPAWN_DUP2, fd, new_fd)

Realiza os.dup2(fd, new_fd).

Estas tuplas corresponden a la biblioteca C posix_spawn_file_actions_addopen(), posix_spawn_file_actions_addclose(), y posix_spawn_file_actions_adddup2() Llamadas API utilizadas para prepararse para posix_spawn() se llame a sí mismo.

El argumento setpgroup establecerá el grupo de proceso del elemento secundario en el valor especificado. Si el valor especificado es 0, la ID del grupo de procesos del niño se hará igual que su ID de proceso. Si el valor de setpgroup no está establecido, el elemento secundario heredará la ID del grupo de proceso del elemento primario. Este argumento corresponde al flag POSIX_SPAWN_SETPGROUP de la biblioteca de C.

Si el argumento resetids es True, restablecerá el UID y el GID efectivos del niño al UID y GID reales del proceso padre. Si el argumento es False, el niño conserva el UID y el GID efectivos del padre. En cualquier caso, si los bits de permiso set-user-ID y set-group-ID están habilitados en el archivo ejecutable, su efecto anulará la configuración del UID y GID efectivos. Este argumento corresponde a la flag de la biblioteca C POSIX_SPAWN_RESETIDS.

Si el argumento setsid es True, creará una nueva ID de sesión para posix_spawn. setsid requiere POSIX_SPAWN_SETSID o flag POSIX_SPAWN_SETSID_NP. De lo contrario, se excita NotImplementedError.

El argumento setsigmask establecerá la máscara de señal en el conjunto de señal especificado. Si no se usa el parámetro, el niño hereda la máscara de señal del padre. Este argumento corresponde al flag POSIX_SPAWN_SETSIGMASK de la biblioteca en C.

El argumento sigdef restablecerá la disposición de todas las señales en el conjunto especificado. Este argumento corresponde al flag POSIX_SPAWN_SETSIGDEF de la biblioteca de C.

El argumento scheduler debe ser una tupla que contenga la política del planificador (opcional) y una instancia de sched_param con los parámetros del planificador. Un valor de None en el lugar de la política del planificador indica que no se proporciona. Este argumento es una combinación de la biblioteca C POSIX_SPAWN_SETSCHEDPARAM y flags POSIX_SPAWN_SETSCHEDULER.

Lanza un evento de auditoría os.posix_spawn con argumentos ruta, argv, env.

Nuevo en la versión 3.8.

Disponibilidad: Unix.

os.posix_spawnp(path, argv, env, *, file_actions=None, setpgroup=None, resetids=False, setsid=False, setsigmask=(), setsigdef=(), scheduler=None)

Envuelve la API de la biblioteca posix_spawnp() C para usar desde Python.

Similar a posix_spawn() excepto que el sistema busca el archivo executable en la lista de directorios especificada por la variable de entorno PATH (de la misma manera que para execvp(3) )

Lanza un evento de auditoría os.posix_spawn con argumentos ruta, argv, env.

Nuevo en la versión 3.8.

Disponibilidad: Ver documentación posix_spawn().

os.register_at_fork(*, before=None, after_in_parent=None, after_in_child=None)

Registra los invocables que se ejecutarán cuando se bifurca un nuevo proceso secundario utilizando os.fork() o API de clonación de procesos similares. Los parámetros son opcionales y solo de palabras clave. Cada uno especifica un punto de llamada diferente.

before es una función llamada antes de bifurcar un proceso hijo.

after_in_parent es una función llamada desde el proceso padre después de bifurcar un proceso hijo.

after_in_child es una función llamada desde el proceso hijo.

Estas llamadas solo se realizan si se espera que el control regrese al intérprete de Python. Un lanzamiento típico subprocess no los activará ya que el niño no va a volver a ingresar al intérprete.

Las funciones registradas para su ejecución antes de la bifurcación se invocan en orden de registro inverso. Las funciones registradas para la ejecución después de la bifurcación (ya sea en el padre o en el hijo) se invocan en orden de registro.

Tenga en cuenta que las llamadas fork() realizadas por código C de terceros no pueden llamar a esas funciones, a menos que explícitamente llame a PyOS_BeforeFork(), PyOS_AfterFork_Parent() y PyOS_AfterFork_Child().

No hay forma de cancelar el registro de una función.

Disponibilidad: Unix.

Nuevo en la versión 3.7.

os.spawnl(mode, path, ...)

os.spawnle(mode, path, ..., env)

os.spawnlp(mode, file, ...)

os.spawnlpe(mode, file, ..., env)

os.spawnv(mode, path, args)

os.spawnve(mode, path, args, env)

os.spawnvp(mode, file, args)

os.spawnvpe(mode, file, args, env)

Ejecute el programa path en un nuevo proceso.

(Tenga en cuenta que el módulo subprocess proporciona funciones más potentes para generar nuevos procesos y recuperar sus resultados; es preferible usar ese módulo que usar estas funciones. Compruebe especialmente la sección Cómo reemplazar anteriores funciones con el módulo subprocess.)

Si mode es P_NOWAIT, esta función retorna la identificación del proceso del nuevo proceso; if mode is P_WAIT, retorna el código de salida del proceso si sale normalmente, o -signal, donde signal es la señal que mató el proceso. En Windows, la identificación del proceso en realidad será el identificador del proceso, por lo que se puede usar con la función waitpid().

Nota sobre VxWorks, esta función no retorna -signal cuando se cierra el nuevo proceso. En su lugar, genera una excepción OSError.

Las variantes «l» y «v» de las funciones spawn* difieren en cómo se pasan los argumentos de la línea de comandos. Las variantes «l» son quizás las más fáciles de trabajar si el número de parámetros se fija cuando se escribe el código; los parámetros individuales simplemente se convierten en parámetros adicionales a las funciones spawnl*(). Las variantes «v» son buenas cuando el número de parámetros es variable, y los argumentos se pasan en una lista o tupla como parámetro args. En cualquier caso, los argumentos del proceso secundario deben comenzar con el nombre del comando que se está ejecutando.

Las variantes que incluyen una segunda «p» cerca del final (spawnlp(), spawnlpe(), spawnvp(), y spawnvpe()) usarán PATH variable de entorno para ubicar el programa file. Cuando se reemplaza el entorno (usando uno de los siguientes spawn*e variantes, discutidas en el siguiente párrafo), el nuevo entorno se utiliza como fuente de la variable PATH. Las otras variantes, spawnl(), spawnle(), spawnv(), y spawnve(), no utilizarán la variable PATH para localizar el ejecutable; path debe contener una ruta absoluta o relativa apropiada.

Para spawnle(), spawnlpe(), spawnve(), y spawnvpe() (tenga en cuenta que todo esto termina en «e»), el parámetro env debe ser un mapeo que se utiliza para definir las variables de entorno para el nuevo proceso (se utilizan en lugar del entorno del proceso actual); las funciones spawnl(), spawnlp(), spawnv() y spawnvp() hacen que el nuevo proceso herede el entorno del proceso actual. Tenga en cuenta que las claves y los valores en el diccionario env deben ser cadenas; Las teclas o valores no válidos harán que la función falle, con un valor de retorno de 127.

Como ejemplo, las siguientes llamadas a spawnlp() y spawnvpe() son equivalentes:

import os
os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null')

L = ['cp', 'index.html', '/dev/null']
os.spawnvpe(os.P_WAIT, 'cp', L, os.environ)

Lanza un evento de auditoría os.spawn con argumentos mode, path, args, env.

Disponibilidad: Unix, Windows. spawnlp(), spawnlpe(), spawnvp() y spawnvpe() no están disponibles en Windows. spawnle() y spawnve() no son seguros para subprocesos en Windows; le recomendamos que utilice el módulo subprocess en su lugar.

Distinto en la versión 3.6: Acepta un objeto tipo ruta.

os.P_NOWAIT

os.P_NOWAITO

Valores posibles para el parámetro mode para spawn* familia de funciones. Si se da alguno de estos valores, las funciones spawn*() volverán tan pronto como se haya creado el nuevo proceso, con la identificación del proceso como valor de retorno.

Disponibilidad: Unix, Windows.

os.P_WAIT

Posible valor para el parámetro mode para spawn* familia de funciones. Si esto se da como mode, las funciones spawn*() no volverán hasta que el nuevo proceso se haya completado y retornará el código de salida del proceso, la ejecución es exitosa, o -signal si una señal mata el proceso.

Disponibilidad: Unix, Windows.

os.P_DETACH

os.P_OVERLAY

Valores posibles para el parámetro mode para spawn* familia de funciones. Estos son menos portátiles que los enumerados anteriormente. P_DETACH es similar a P_NOWAIT, pero el nuevo proceso se desconecta de la consola del proceso de llamada. Si se usa P_OVERLAY, el proceso actual será reemplazado; la función spawn* no volverá.

Disponibilidad: Windows.

os.startfile(path[, operation])

Inicie un archivo con su aplicación asociada.

Cuando operation no se especifica o 'abre', esto actúa como hacer doble clic en el archivo en el Explorador de Windows, o dar el nombre del archivo como argumento para el comando start desde el shell de comandos interactivo: el archivo se abre con cualquier aplicación (si la hay) a la que está asociada su extensión.

Cuando se da otra operation, debe ser un «verbo de comando» que especifica qué se debe hacer con el archivo. Los verbos comunes documentados por Microsoft son 'print' y 'edit' (para usar en archivos), así como 'explore' y 'find' (para usar en directorios).

startfile() vuelve tan pronto como se inicia la aplicación asociada. No hay opción de esperar a que la aplicación se cierre y no hay forma de recuperar el estado de salida de la aplicación. El parámetro path es relativo al directorio actual. Si desea utilizar una ruta absoluta, asegúrese de que el primer carácter no sea una barra inclinada ('/'); la función subyacente Win32 ShellExecute() no funciona si lo es. Use la función os.path.normpath() para asegurarse de que la ruta esté codificada correctamente para Win32.

Para reducir la sobrecarga de inicio del intérprete, la función Win32 ShellExecute() no se resuelve hasta que esta función se llama por primera vez. Si la función no se puede resolver, se generará NotImplementedError.

Lanza un evento de auditoría os.startfile con argumentos path, operation.

Disponibilidad: Windows.

os.system(command)

Execute the command (a string) in a subshell. This is implemented by calling the Standard C function system(), and has the same limitations. Changes to sys.stdin, etc. are not reflected in the environment of the executed command. If command generates any output, it will be sent to the interpreter standard output stream. The C standard does not specify the meaning of the return value of the C function, so the return value of the Python function is system-dependent.

On Unix, the return value is the exit status of the process encoded in the format specified for wait().

En Windows, el valor de retorno es el que retorna el shell del sistema después de ejecutar command. El shell viene dado por la variable de entorno de Windows COMSPEC: generalmente es cmd.exe, que retorna el estado de salida de la ejecución del comando; En sistemas que utilizan un shell no nativo, consulte la documentación del shell.

El módulo subprocess proporciona instalaciones más potentes para generar nuevos procesos y recuperar sus resultados; usar ese módulo es preferible a usar esta función. Consulte la sección Cómo reemplazar anteriores funciones con el módulo subprocess en la documentación de subprocess para obtener algunas recetas útiles.

En Unix, waitstatus_to_exitcode() puede ser usado para convertir el resultado (estado de salida) en un código de salida. En Windows, el resultado es directamente el código de salida.

Lanza un evento de auditoría os.system con argumento command.

Disponibilidad: Unix, Windows.

os.times()

Retorna los tiempos de proceso globales actuales. El valor de retorno es un objeto con cinco atributos:

user - user time

system - system time

children_user - user time of all child processes

children_system - system time of all child processes

elapsed - elapsed real time since a fixed point in the past

For backwards compatibility, this object also behaves like a five-tuple containing user, system, children_user, children_system, and elapsed in that order.

See the Unix manual page times(2) and times(3) manual page on Unix or the GetProcessTimes MSDN [https://docs.microsoft.com/windows/win32/api/processthreadsapi/nf-processthreadsapi-getprocesstimes] on Windows. On Windows, only user and system are known; the other attributes are zero.

Disponibilidad: Unix, Windows.

Distinto en la versión 3.3: El tipo de objeto retornado cambió de una tupla a un objeto tipo tupla con atributos con nombre.

os.wait()

Espere a que se complete un proceso secundario y retorna una tupla que contenga su indicación de estado pid y de salida: un número de 16 bits, cuyo byte bajo es el número de señal que mató el proceso y cuyo byte alto es el estado de salida (si la señal el número es cero); el bit alto del byte bajo se establece si se produjo un archivo central.

waitstatus_to_exitcode() puede ser usado para convertir el estado de salida en el código de salida.

Disponibilidad: Unix.

Ver también

waitpid() puede ser usado para esperar a la terminación de algún proceso hijo en específico y tiene más opciones.

os.waitid(idtype, id, options)

Espere la finalización de uno o más procesos secundarios. idtype puede ser P_PID, P_PGID, P_ALL o P_PIDFD en Linux. id especifica el pid para esperar. options se construye a partir de ORing de uno o más de WEXITED, WSTOPPED o WCONTINUED y adicionalmente se puede ORed con WNOHANG o WNOWAIT. El valor de retorno es un objeto que representa los datos contenidos en la estructura siginfo_t, a saber: si_pid, si_uid, si_signo, si_status, si_code o None si WNOHANG está especificado y no hay hijos en un estado de espera.

Disponibilidad: Unix.

Nuevo en la versión 3.3.

os.P_PID

os.P_PGID

os.P_ALL

Estos son los valores posibles para idtype en waitid(). Afectan cómo se interpreta id.

Disponibilidad: Unix.

Nuevo en la versión 3.3.

os.P_PIDFD

Esto es un idtype especifico de Linux que indica que ese id es un descriptor de archivo que hace referencia a un proceso.

Disponibilidad: Linux 5.4+

Nuevo en la versión 3.9.

os.WEXITED

os.WSTOPPED

os.WNOWAIT

Indicadores que se pueden usar en options en waitid() que especifican qué señal secundaria esperar.

Disponibilidad: Unix.

Nuevo en la versión 3.3.

os.CLD_EXITED

os.CLD_KILLED

os.CLD_DUMPED

os.CLD_TRAPPED

os.CLD_STOPPED

os.CLD_CONTINUED

Estos son los valores posibles para si_code en el resultado retornado por waitid().

Disponibilidad: Unix.

Nuevo en la versión 3.3.

Distinto en la versión 3.9: Agregado los valores CLD_KILLED y CLD_STOPPED.

os.waitpid(pid, options)

Los detalles de esta función difieren en Unix y Windows.

En Unix: espere a que se complete un proceso secundario dado por la identificación del proceso pid, y retorna una tupla que contenga su identificación del proceso y la indicación del estado de salida (codificado como para wait()). La semántica de la llamada se ve afectada por el valor del número entero options, que debe ser 0 para el funcionamiento normal.

Si pid es mayor que 0, waitpid() solicita información de estado para ese proceso específico. Si pid es 0, la solicitud es para el estado de cualquier hijo en el grupo de procesos del proceso actual. Si pid es -1, la solicitud corresponde a cualquier elemento secundario del proceso actual. Si pid es menor que -1, se solicita el estado de cualquier proceso en el grupo de procesos -pid (el valor absoluto de pid).

Un OSError se lanza con el valor de errno cuando syscall retorna -1.

En Windows: espere a que se complete un proceso dado por el identificador de proceso pid, y retorna una tupla que contiene pid, y su estado de salida se desplazó a la izquierda en 8 bits (el desplazamiento facilita el uso de la función en la plataforma). A pid menor o igual que 0 no tiene un significado especial en Windows y genera una excepción. El valor de entero options no tiene ningún efecto. pid puede referirse a cualquier proceso cuya identificación sea conocida, no necesariamente un proceso hijo. Las funciones spawn* llamadas con P_NOWAIT retornan manejadores de proceso adecuados.

waitstatus_to_exitcode() puede ser usado para convertir el estado de salida en el código de salida.

Distinto en la versión 3.5: Si la llamada al sistema se interrumpe y el controlador de señal no genera una excepción, la función vuelve a intentar la llamada del sistema en lugar de generar una excepción InterruptedError (ver PEP 475 [https://www.python.org/dev/peps/pep-0475] para la justificación).

os.wait3(options)

Similar a waitpid(), excepto que no se proporciona ningún argumento de identificación de proceso y se retorna una tupla de 3 elementos que contiene la identificación de proceso del niño, la indicación del estado de salida y la información de uso de recursos. Consulte resource. getrusage() para obtener detalles sobre la información de uso de recursos. El argumento de la opción es el mismo que se proporciona a waitpid() y wait4().

waitstatus_to_exitcode() puede ser usado para convertir el estado de salida al código de salida.

Disponibilidad: Unix.

os.wait4(pid, options)

Similar a waitpid(), excepto una tupla de 3 elementos, que contiene la identificación del proceso del niño, la indicación del estado de salida y la información de uso de recursos. Consulte resource.getrusage() para obtener detalles sobre la información de uso de recursos. Los argumentos para wait4() son los mismos que los proporcionados para waitpid().

waitstatus_to_exitcode() puede ser usado para convertir el estado de salida al código de salida.

Disponibilidad: Unix.

os.waitstatus_to_exitcode(status)

Convertir un estado de espera a un código de salida.

En Unix:

Si el proceso termino con normalidad (if WIFEXITED(status) is true, se retornan el estado de salida del proceso (return WEXITSTATUS(status)): resultado mayor o igual a 0.

Si el proceso fue terminado por una señal (if WIFSIGNALED(status) is true), retorna -signum donde signum es el numero de la señal que cause que el proceso termine (return -WTERMSIG(status)): resultado menor que 0.

En el caso contrario, se lanza un ValueError.

En Windows, retorna status desplazado a la derecha en 8 bits.

En Unix, si el proceso esta siendo rastreado o si waitpid() fue llamado con la opción WUNTRACED, el que llama debe revisar primero si WIFSTOPPED(status) es verdadero. La función no debe de ser llamada si WIFSTOPPED(status) es verdadero.

Ver también

Funciones WIFEXITED(), WEXITSTATUS(), WIFSIGNALED(), WTERMSIG(), WIFSTOPPED(), WSTOPSIG().

Nuevo en la versión 3.9.

os.WNOHANG

La opción para waitpid() para regresar inmediatamente si no hay un estado de proceso secundario disponible de inmediato. La función retorna (0, 0) en este caso.

Disponibilidad: Unix.

os.WCONTINUED

Esta opción hace que se informen los procesos secundarios si se han continuado desde una parada de control de trabajo desde la última vez que se informó su estado.

Disponibilidad: algunos sistemas Unix.

os.WUNTRACED

Esta opción hace que se informen los procesos secundarios si se han detenido pero su estado actual no se ha informado desde que se detuvieron.

Disponibilidad: Unix.

Las siguientes funciones toman un código de estado del proceso retornado por system(), wait(), o waitpid() como parámetro. Pueden usarse para determinar la disposición de un proceso.

os.WCOREDUMP(status)

Retorna True si se generó un volcado de núcleo para el proceso; de lo contrario, retorna False.

Esta función debe emplearse solo si WIFSIGNALED() es verdadero.

Disponibilidad: Unix.

os.WIFCONTINUED(status)

Retorna True si un niño detenido se ha reanudado mediante la entrega de SIGCONT (si el proceso se ha continuado desde una parada de control de trabajo), de lo contrario, retorna False.

Ver opción WCONTINUED.

Disponibilidad: Unix.

os.WIFSTOPPED(status)

Retorna True si el proceso se detuvo mediante la entrega de una señal; de lo contrario, retorna False.

WIFSTOPPED() solo retorna True si la llamada waitpid() se realizó utilizando la opción WUNTRACED o cuando se rastrea el proceso (consulte ptrace(2))

Disponibilidad: Unix.

os.WIFSIGNALED(status)

Retorna True si el proceso finalizó con una señal; de lo contrario, retorna False.

Disponibilidad: Unix.

os.WIFEXITED(status)

Retorna True si el proceso finalizó normalmente, es decir, llamando a exit() o _exit(), o volviendo de main(); de lo contrario, retorna False.

Disponibilidad: Unix.

os.WEXITSTATUS(status)

Retorna el estado de salida del proceso.

Esta función debe emplearse solo si WIFEXITED() es verdadero.

Disponibilidad: Unix.

os.WSTOPSIG(status)

Retorna la señal que hizo que el proceso se detuviera.

Esta función debe emplearse solo si WIFSTOPPED() es verdadero.

Disponibilidad: Unix.

os.WTERMSIG(status)

Retorna el número de la señal que provocó la finalización del proceso.

Esta función debe emplearse solo si WIFSIGNALED() es verdadero.

Disponibilidad: Unix.

Interfaz al planificador

Estas funciones controlan cómo el sistema operativo asigna el tiempo de CPU a un proceso. Solo están disponibles en algunas plataformas Unix. Para obtener información más detallada, consulte las páginas de manual de Unix.

Nuevo en la versión 3.3.

Las siguientes políticas de programación están expuestas si son compatibles con el sistema operativo.

os.SCHED_OTHER

La política de programación predeterminada.

os.SCHED_BATCH

Política de programación para procesos intensivos en CPU que intenta preservar la interactividad en el resto de la computadora.

os.SCHED_IDLE

Política de programación para tareas en segundo plano de prioridad extremadamente baja.

os.SCHED_SPORADIC

Política de programación para programas de servidor esporádicos.

os.SCHED_FIFO

Una política de programación First In First Out.

os.SCHED_RR

Una política de programación round-robin.

os.SCHED_RESET_ON_FORK

Esta flag se puede OR con cualquier otra política de programación. Cuando un proceso con este indicador establece bifurcaciones, la política de programación y la prioridad de su hijo se restablecen a los valores predeterminados.

class os.sched_param(sched_priority)

Esta clase representa los parámetros de programación ajustables utilizados en sched_setparam(), sched_setscheduler() y sched_getparam(). Es inmutable.

Por el momento, solo hay un parámetro posible:

sched_priority

La prioridad de programación para una política de programación.

os.sched_get_priority_min(policy)

Obtiene el valor de prioridad mínimo para policy. policy es una de las constantes de política de programación anteriores.

os.sched_get_priority_max(policy)

Obtiene el valor de prioridad máxima para policy. policy es una de las constantes de política de programación anteriores.

os.sched_setscheduler(pid, policy, param)

Establece la política de programación para el proceso con PID pid. Un pid de 0 significa el proceso de llamada. policy es una de las constantes de política de programación anteriores. param es una instancia de sched_param.

os.sched_getscheduler(pid)

Retorna la política de programación para el proceso con PID pid. Un pid de 0 significa el proceso de llamada. El resultado es una de las constantes de política de programación anteriores.

os.sched_setparam(pid, param)

Set the scheduling parameters for the process with PID pid. A pid of 0 means the calling process. param is a sched_param instance.

os.sched_getparam(pid)

Retorna los parámetros de programación como una instancia de sched_param para el proceso con PID pid. Un pid de 0 significa el proceso de llamada.

os.sched_rr_get_interval(pid)

Retorna el round-robin quantum en segundos para el proceso con PID pid. Un pid de 0 significa el proceso de llamada.

os.sched_yield()

Renunciar voluntariamente a la CPU.

os.sched_setaffinity(pid, mask)

Restringe el proceso con PID pid (o el proceso actual si es cero) a un conjunto de CPU. mask es un entero iterable que representa el conjunto de CPU a las que se debe restringir el proceso.

os.sched_getaffinity(pid)

Retorna el conjunto de CPU al proceso con PID pid (o el proceso actual si es cero) está restringido.

Información miscelánea del sistema

os.confstr(name)

Retorna valores de configuración del sistema con valores de cadena. name especifica el valor de configuración para recuperar; puede ser una cadena que es el nombre de un valor de sistema definido; estos nombres se especifican en varios estándares (POSIX, Unix 95, Unix 98 y otros). Algunas plataformas también definen nombres adicionales. Los nombres conocidos por el sistema operativo host se dan como las claves del diccionario confstr_names. Para las variables de configuración no incluidas en esa asignación, también se acepta pasar un número entero para name.

Si el valor de configuración especificado por name no está definido, se retorna None.

Si name es una cadena y no se conoce, se excita ValueError. Si el sistema host no admite un valor específico para name, incluso si está incluido en confstr_names, se lanza un OSError con errno.EINVAL para el número de error .

Disponibilidad: Unix.

os.confstr_names

Nombres de mapeo de diccionario aceptados por confstr() a los valores enteros definidos para esos nombres por el sistema operativo host. Esto se puede usar para determinar el conjunto de nombres conocidos por el sistema.

Disponibilidad: Unix.

os.cpu_count()

Retorna el número de CPU en el sistema. Retorna None si no está determinado.

Este número no es equivalente al número de CPU que puede utilizar el proceso actual. El número de CPU utilizables se puede obtener con len(os.sched_getaffinity(0))

Nuevo en la versión 3.4.

os.getloadavg()

Retorna el número de procesos en la cola de ejecución del sistema promediada durante los últimos 1, 5 y 15 minutos o aumentos OSError si el promedio de carga no se pudo obtener.

Disponibilidad: Unix.

os.sysconf(name)

Retorna valores de configuración del sistema con valores enteros. Si el valor de configuración especificado por name no está definido, se retorna -1. Los comentarios sobre el parámetro name para confstr() se aplican aquí también; El diccionario que proporciona información sobre los nombres conocidos viene dado por sysconf_names.

Disponibilidad: Unix.

os.sysconf_names

Nombres de asignación de diccionario aceptados por sysconf() a los valores enteros definidos para esos nombres por el sistema operativo host. Esto se puede usar para determinar el conjunto de nombres conocidos por el sistema.

Disponibilidad: Unix.

Los siguientes valores de datos se utilizan para admitir operaciones de manipulación de rutas. Estos están definidos para todas las plataformas.

Las operaciones de nivel superior en los nombres de ruta se definen en el módulo os.path.

os.curdir

La cadena constante utilizada por el sistema operativo para referirse al directorio actual. Esto es '.' Para Windows y POSIX. También disponible a través de os.path.

os.pardir

La cadena constante utilizada por el sistema operativo para hacer referencia al directorio principal. Esto es '...' para Windows y POSIX. También disponible a través de os.path.

os.sep

El carácter utilizado por el sistema operativo para separar los componentes del nombre de ruta. Esto es '/' para POSIX y '\\' para Windows. Tenga en cuenta que saber esto no es suficiente para poder analizar o concatenar nombres de ruta — use os.path.split() y os.path.join() — pero en ocasiones es útil. También disponible a través de os.path.

os.altsep

Un carácter alternativo utilizado por el sistema operativo para separar los componentes del nombre de ruta, o None si solo existe un carácter separador. Esto se establece en '/' en los sistemas Windows donde sep es una barra invertida. También disponible a través de os.path.

os.extsep

El carácter que separa el nombre de archivo base de la extensión; por ejemplo, el '.' en os.py. También disponible a través de os.path.

os.pathsep

El carácter utilizado convencionalmente por el sistema operativo para separar los componentes de la ruta de búsqueda (como en PATH), como ':' para POSIX o ';' para Windows. También disponible a través de os.path.

os.defpath

La ruta de búsqueda predeterminada utilizada por exec*p* y spawn*p* si el entorno no tiene una tecla 'RUTA'. También disponible a través de os.path.

os.linesep

La cadena utilizada para separar (o, más bien, terminar) líneas en la plataforma actual. Este puede ser un solo carácter, como '\n' para POSIX, o varios caracteres, por ejemplo, '\r\n' para Windows. No utilice os.linesep como terminador de línea cuando escriba archivos abiertos en modo texto (el valor predeterminado); use un solo '\n' en su lugar, en todas las plataformas.

os.devnull

La ruta del archivo del dispositivo nulo. Por ejemplo: '/dev/null' para POSIX, 'nul' para Windows. También disponible a través de os.path.

os.RTLD_LAZY

os.RTLD_NOW

os.RTLD_GLOBAL

os.RTLD_LOCAL

os.RTLD_NODELETE

os.RTLD_NOLOAD

os.RTLD_DEEPBIND

Flags para usar con las funciones setdlopenflags() y getdlopenflags(). Consulte la página del manual de Unix dlopen(3) para saber qué significan las diferentes flags.

Nuevo en la versión 3.3.

Números al azar

os.getrandom(size, flags=0)

Obtiene hasta size bytes aleatorios. La función puede retornar menos bytes que los solicitados.

Estos bytes se pueden usar para generar generadores de números aleatorios en el espacio del usuario o para fines criptográficos.

getrandom() se basa en la entropía obtenida de los controladores de dispositivos y otras fuentes de ruido ambiental. La lectura innecesaria de grandes cantidades de datos tendrá un impacto negativo en otros usuarios de los dispositivos /dev/random y /dev/urandom.

El argumento de las flags es una máscara de bits que puede contener cero o más de los siguientes valores OR juntos:: py os.GRND_RANDOM y GRND_NONBLOCK.

Consulte también la página del manual Linux getrandom() [http://man7.org/linux/man-pages/man2/getrandom.2.html].

Disponibilidad: Linux 3.17 y más reciente.

Nuevo en la versión 3.6.

os.urandom(size)

Return a bytestring of size random bytes suitable for cryptographic use.

Esta función retorna bytes aleatorios de una fuente de aleatoriedad específica del sistema operativo. Los datos retornados deben ser lo suficientemente impredecibles para las aplicaciones criptográficas, aunque su calidad exacta depende de la implementación del sistema operativo.

En Linux, si la llamada al sistema getrandom() está disponible, se usa en modo de bloqueo: bloquee hasta que el grupo de entropía urandom del sistema se inicialice (el núcleo recopila 128 bits de entropía). Ver el PEP 524 [https://www.python.org/dev/peps/pep-0524] para la justificación. En Linux, la función getrandom() puede usarse para obtener bytes aleatorios en modo sin bloqueo (usando el indicador GRND_NONBLOCK) o para sondear hasta que el grupo de entropía urandom del sistema se inicialice.

En un sistema tipo Unix, los bytes aleatorios se leen desde el dispositivo /dev/urandom. Si el dispositivo /dev/urandom no está disponible o no es legible, se genera la excepción NotImplementedError.

En Windows, usará CryptGenRandom().

Ver también

El módulo secrets proporciona funciones de nivel superior. Para obtener una interfaz fácil de usar con el generador de números aleatorios proporcionado por su plataforma, consulte random.SystemRandom.

Distinto en la versión 3.6.0: En Linux, getrandom() ahora se usa en modo de bloqueo para aumentar la seguridad.

Distinto en la versión 3.5.2: En Linux, si el syscall getrandom() bloquea (el grupo de entropía urandom aún no está inicializado), recurra a la lectura /dev/urandom.

Distinto en la versión 3.5: En Linux 3.17 y versiones posteriores, la llamada al sistema getrandom() ahora se usa cuando está disponible. En OpenBSD 5.6 y posterior, ahora se usa la función C getentropy(). Estas funciones evitan el uso de un descriptor de archivo interno.

os.GRND_NONBLOCK

Por defecto, cuando lee desde /dev/random, getrandom() bloquea si no hay bytes aleatorios disponibles, y cuando lee desde /dev/urandom, bloquea si el grupo de entropía no tiene, sin embargo, se ha inicializado.

Si se establece el indicador GRND_NONBLOCK, entonces getrandom() no se bloquea en estos casos, sino que inmediatamente genera BlockingIOError.

Nuevo en la versión 3.6.

os.GRND_RANDOM

Si se establece este bit, los bytes aleatorios se extraen del grupo /dev/random en lugar del grupo /dev/urandom.

Nuevo en la versión 3.6.

io — Herramientas principales para trabajar con streams

Código fuente: Lib/io.py [https://github.com/python/cpython/tree/3.9/Lib/io.py]

Resumen

El módulo io provee las facilidades principales de Python para manejar diferentes tipos de E/S. Hay tres diferentes tipos de E/S: texto E/S, binario E/S e E/S sin formato. Estas son categorías generales y varios respaldos de almacenamiento se pueden usar para cada una de ellas. Un objeto concreto perteneciendo a cualquiera de estas categorías se llama un file object. Otros términos comunes son stream y file-like object.

Independiente de su categoría, cada objeto stream también tendrá varias capacidades: puede ser solamente para lectura, solo escritura, or lectura y escritura. También permite arbitrariamente acceso aleatorio (buscando adelante o hacia atrás en cualquier lugar) o solamente acceso secuencial (por ejemplo en el caso de un socket o pipe).

Todas los streams son cuidadosas del tipo de datos que se les provee. Por ejemplo dando un objeto de clase str al método write() de un stream binaria lanzará un TypeError. También dándole un objeto de tipo bytes al método write() de un stream de tipo texto.

Distinto en la versión 3.3: Operaciones que lanzarán un IOError ahora lanzan OSError, ya que IOError es un alias de OSError.

E/S Texto

E/S de tipo texto espera y produce objetos de clase str. Esto significa que cuando el respaldo de almacenamiento está compuesto de forma nativa de bytes (como en el caso de un archivo), la codificación y descodificación de datos está hecho de forma transparente tanto como traducción opcional de caracteres de nueva línea específicos de la plataforma.

La manera más fácil de crear un stream de tipo texto es con el método open(), con la opción de especificar una codificación:

f = open("myfile.txt", "r", encoding="utf-8")

Streams de texto en memoria también están disponibles como objetos de tipo StringIO:

f = io.StringIO("some initial text data")

El API (interfaz de programación de aplicaciones) de streams tipo texto está descrito con detalle en la documentación de TextIOBase.

E/S Binaria

E/S binaria (también conocido como buffered E/S) espera objetos tipo bytes y produce objetos tipo bytes. No se hace codificación, descodificación, o traducciones de nueva línea. Esta categoría de streams puede ser usada para todos tipos de datos sin texto, y también cuando se desea control manual sobre el manejo de dato textual.

La manera más fácil para crear un stream binario es con el método open() con 'b' en el modo de la cadena de caracteres:

f = open("myfile.jpg", "rb")

Los streams binarios en memoria también están disponibles como objetos tipo BytesIO:

f = io.BytesIO(b"some initial binary data: \x00\x01")

El API de stream binario está descrito con detalle en la documentación de BufferedIOBase.

Otros módulos bibliotecarios pueden proveer maneras alternativas para crear streams de tipo texto o binario. Ver socket.socket.makefile() como ejemplo.

E/S sin formato

E/S sin formato (también conocido como unbuffered E/S) es generalmente usado como un fundamento de nivel bajo para streams binario y tipo texto; es raramente útil para manipular directamente streams sin formatos del código de usuario. Sin embargo puedes crear un stream sin formato abriendo un archivo en modo binario con el búfer apagado:

f = open("myfile.jpg", "rb", buffering=0)

El API de streams sin formato está descrito con detalle en la documentación de RawIOBase.

Interfaz de módulo de alto nivel

io.DEFAULT_BUFFER_SIZE

Un int que contiene el búfer de tamaño predeterminado usado por las clases de tipo E/S. open() utiliza el blksize del archivo (obtenido por os.stat()) si es posible.

io.open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)

Esto es un alias para la función incorporada open().

Lanza un auditing event open con los argumentos``path``, mode, flags.

io.open_code(path)

Abre el archivo dado con el modo 'rb'. Esta función debe ser usado cuando la intención es tratar el contenido como código ejecutable.

path debe ser un str y una ruta absoluta.

Se puede anular el comportamiento de esta función haciendo un pedido anterior a PyFile_SetOpenCodeHook(). Sin embargo, asumiendo que path es un str y una ruta absoluta, open_code(path) debería manejarse al igual que open(path, ‘rb'). El propósito de anular el comportamiento existe para validación adicional o para el preprocesamiento del archivo.

Nuevo en la versión 3.8.

exception io.BlockingIOError

Esto es un alias de compatibilidad para la incorporada excepción BlockingIOError.

exception io.UnsupportedOperation

Una excepción heredando OSError y ValueError que es generado cuando se llama a una operación no admitida en un stream.

Ver también

sys

contiene los streams estándar de IO sys.stdin, sys.stdout, y sys.stderr.

Jerarquía de clases

La implementación de streams E/S está organizada como una jerarquía de clases. Primero abstract base classes (ABC), que son usados para especificar las varias categorías de streams, luego las clases concretas proveen un stream estándar de implementaciones.

Nota

Las clases abstractas base también proveen implementaciones predeterminadas de algunos métodos para ayudar implementar clases de streams concretos. Por ejemplo, BufferedIOBase proporciona implementaciones no optimizadas de readinto() y readline().

En la parte superior de la jerarquía E/S está la clase abstracta base IOBase. Define la interfaz básica del stream. Tenga en cuenta que no hay separación entre streams de lectura y escritura; implementaciones están permitidos lanzar UnsupportedOperation si no apoyan la operación.

La clase RawIOBase extiende IOBase. Maneja la lectura y escritura de bytes a un stream. FileIO subclasifica RawIOBase para proveer una interfaz a los archivos en el sistema de archivos de la máquina.

The BufferedIOBase ABC extends IOBase. It deals with buffering on a raw binary stream (RawIOBase). Its subclasses, BufferedWriter, BufferedReader, and BufferedRWPair buffer raw binary streams that are readable, writable, and both readable and writable, respectively. BufferedRandom provides a buffered interface to seekable streams. Another BufferedIOBase subclass, BytesIO, is a stream of in-memory bytes.

The TextIOBase ABC extends IOBase. It deals with streams whose bytes represent text, and handles encoding and decoding to and from strings. TextIOWrapper, which extends TextIOBase, is a buffered text interface to a buffered raw stream (BufferedIOBase). Finally, StringIO is an in-memory stream for text.

Los nombres de los argumentos no son parte de la especificación, y solo los argumentos de open() están destinados a ser utilizados como argumentos de palabras clave.

La siguiente tabla resume los ABC proporcionado por el módulo io module:

ABC

Hereda

Métodos de trozos (Stub)

Métodos Mixin y propiedades

IOBase

fileno, seek, and truncate

close, closed, __enter__, __exit__, flush, isatty, __iter__, __next__, readable, readline, readlines, seekable, tell, writable, and writelines

RawIOBase

IOBase

readinto and write

Métodos IOBase heredados, read, and readall

BufferedIOBase

IOBase

detach, read, read1, and write

Métodos IOBase heredados, readinto, and readinto1

TextIOBase

IOBase

detach, read, readline, and write

Métodos IOBase heredados, encoding, errors, and newlines

Clases base E/S

class io.IOBase

The abstract base class for all I/O classes.

Esta clase provee implementaciones abstractas vacías para muchos métodos que clases que derivadas pueden anular selectivamente; la implementación predeterminada representa un archivo que no se puede leer, grabar o ser buscado.

Aunque IOBase no declara el método read() o write() porque sus firmas varían, implementaciones y clientes deberían considerar usar métodos como parte de la interfaz. Las implementaciones también podrían lanzar un ValueError (o UnsupportedOperation) cuando operaciones que estos no apoyan son usados.

El tipo básico usado para leer datos binarios o grabar un archivo es bytes. Otros bytes-like objects son aceptados como argumentos para métodos también. Clases de tipo E/S funcionan usando datos de tipo str.

Tenga en cuenta que llamando cualquier método (incluso indagaciones) en un stream cerrada es indefinido. En este caso implementaciones podrían lanzar un error ValueError.

IOBase (y sus subclasificaciones) apoyan el protocolo iterador, significando que un objeto de clase IOBase puede ser iterado sobre el rendimiento de las líneas en un stream de datos. Líneas son definidas un poco diferente dependiendo si el stream es de tipo binario (produciendo bytes), o un stream de texto (produciendo cadenas de caracteres). Ver readline() abajo.

IOBase es también un gestor de contexto y por ende apoya la declaración with. En este ejemplo, file es cerrado después de que la declaración with termina–incluso si alguna excepción ocurre:

with open('spam.txt', 'w') as file:
    file.write('Spam and eggs!')

IOBase provee los siguientes atributos y métodos:

close()

Cierra el stream. Este método no tiene efecto si el archivo ya está cerrado. Cuándo está cerrado, cualquier operación que se le haga al archivo (ej. leer or grabar) lanzará el error ValueError.

Como conveniencia, se permite llamar este método más que una vez. Sin embargo, solamente el primer llamado tenderá efecto.

closed

True si está cerrada el stream.

fileno()

Retorna el descriptor de archivo subyacente (un número de tipo entero) de el stream si existe. Un OSError se lanza si el objeto IO no tiene un archivo descriptor.

flush()

Vacía los buffers de grabación del stream si corresponde. Esto no hace nada para streams que son solamente de lectura o streams sin bloqueo.

isatty()

Retorna True si el stream es interactiva (ej., si está conectado a un terminal o dispositivo tty).

readable()

Retorna True si el stream puede ser leída. Si es False, el método read() lanzará un OSError.

readline(size=-1, /)

Lee y retorna una línea del stream. Si size (tamaño) es especificado, se capturará un máximo de ése mismo tamaño especificado en bytes.

El terminador de la línea siempre es b'\n' para archivos de tipo binario; para archivos de tipo texto el argumento newline para la función open() pueden ser usados para seleccionar las líneas terminadoras reconocidas.

readlines(hint=-1, /)

Lee y retorna una lista de líneas del stream. hint puede ser especificado para controlar el número de líneas que se lee: no se leerán más líneas si el tamaño total (en bytes / caracteres) de todas las líneas excede hint.

hint values of 0 or less, as well as None, are treated as no hint.

Tenga en cuenta que ya es posible iterar sobre objetos de archivo usando for line in file: … sin llamar file.readlines().

seek(offset, whence=SEEK_SET, /)

Cambiar la posición del stream al dado byte offset. offset se interpreta en relación con la posición indicada por whence. El valor dado para whence es SEEK_SET. Valores para whence son:

SEEK_SET o 0 – inicio del stream (el dado); offset debería ser cero o positivo

SEEK_CUR o 1 – posición actual del stream; offset puede ser negativo

SEEK_END o 2 – fin del stream; offset is usualmente negativo

Retorna la nueva posición absoluta.

Nuevo en la versión 3.1: Los constantes``SEEK_*``.

Nuevo en la versión 3.3: Algunos sistemas operativos pueden apoyar valores adicionales, como os.SEEK_HOLE o os.SEEK_DATA. Los valores válidos para un archivo podrían depender de que esté abierto en modo texto o binario.

seekable()

Retorna True si el stream apoya acceso aleatorio. Si retorna False, seek(), tell() y truncate() lanzarán OSError.

tell()

Retorna la posición actual del stream.

truncate(size=None, /)

Cambia el tamaño del stream al size dado en bytes (o la posición actual si no se especifica size). La posición actual del stream no se cambia. Este cambio de tamaño puede incrementar o reducir el tamaño actual del archivo. En caso de extensión, los contenidos del área del nuevo archivo depende de la plataforma (en la mayoría de los sistemas bytes adicionales son llenos de cero). Se retorna el nuevo tamaño del archivo.

Distinto en la versión 3.5: Windows llenará los archivos con cero cuando extienda.

writable()

Retorna True si el stream apoya grabación. Si retorna False, write() y truncate() lanzarán OSError.

writelines(lines, /)

Escribir una lista de líneas al stream. No se agrega separadores de líneas, así que es usual que las líneas tengan separador al final.

__del__()

Prepara para la destrucción de un objeto. IOBase proporciona una implementación dada de este método que ejecuta las instancias del método close().

class io.RawIOBase

Base class for raw binary streams. It inherits IOBase.

Raw binary streams typically provide low-level access to an underlying OS device or API, and do not try to encapsulate it in high-level primitives (this functionality is done at a higher-level in buffered binary streams and text streams, described later in this page).

RawIOBase provides these methods in addition to those from IOBase:

read(size=-1, /)

Lee hasta el size de los bytes del objeto y los retorna. Como conveniencia si no se especifica size o es -1, se retornan todos los bytes hasta que se retorne el fin del archivo. Sino, se hace solo un llamado al sistema. Se pueden retornar menos de size bytes si la llamada del sistema operativo retorna menos de size bytes.

Si se retorna 0 bytes y el size no era 0, esto indica que es el fin del archivo. Si el objeto está en modo sin bloqueo y no hay bytes disponibles, se retorna None.

La implementación dada difiera al método readall() y readinto().

readall()

Lee y retorna todos los bytes del stream hasta llegar al fin del archivo, usando, si es necesario, varias llamadas al stream.

readinto(b, /)

Lee bytes en objeto pre-asignado y grabable bytes-like object b, y retorna el número de bytes leído. Por ejemplo, b puede ser una clase de tipo bytearray. Si el objeto está en modo sin bloquear y no hay bytes disponibles, se retorna None.

write(b, /)

Escribe bytes-like object dado, b, al stream subyacente y retorna la cantidad de bytes grabadas. Esto puede ser menos que la longitud de b en bytes, dependiendo de la especificaciones del stream subyacente, especialmente si no está en modo no-bloqueo. None se retorna si el stream sin formato está configurado para no bloquear y ningún byte puede ser rápidamente grabada. El llamador puede deshacer o mutar b después que retorne este método, así que la implementación solo debería acceder b durante la ejecución al método.

class io.BufferedIOBase

Base class for binary streams that support some kind of buffering. It inherits IOBase.

La diferencia principal de RawIOBase es que los métodos read(), readinto() y write() intentarán (respectivamente) leer la cantidad de información solicitada o consumir toda la salida dada, a expensas de hacer más de una llamada al sistema.

Adicionalmente, esos métodos pueden lanzar un BlockingIOError si el stream sin formato subyacente está en modo no bloqueo y no puede obtener or dar más datos; a diferencia de sus contrapartes RawIOBase, estos nunca retornarán None.

Además, el método read() no tiene una implementación dada que difiere al método readinto().

Una implementación típica de BufferedIOBase no debería heredar una implementación de RawIOBase, es más, debería envolver como uno, así como hacen las clases BufferedWriter y BufferedReader.

BufferedIOBase provides or overrides these data attributes and methods in addition to those from IOBase:

raw

El stream sin formato subyacente ( una instancia RawIOBase) que BufferedIOBase maneja. Esto no es parte de la API BufferedIOBase y posiblemente no exista en algunas implementaciones.

detach()

Separa el stream subyacente del búfer y lo retorna.

Luego que el stream sin formato ha sido separado, el búfer está en un estado inutilizable.

Algunos búfer, como BytesIO, no tienen el concepto de un stream sin formato singular para retornar de este método. Lanza un UnsupportedOperation.

Nuevo en la versión 3.1.

read(size=-1, /)

Lee y retorna hasta size en bytes. Si el argumento está omitido, None, o es negativo, los datos son leídos y retornados hasta que se alcance el fin del archivo. Un objeto bytes vacío se retorna si el stream está al final del archivo.

Si el argumento es positivo, y el stream subyacente no es interactiva, varias lecturas sin formato pueden ser otorgadas para satisfacer la cantidad de byte (al menos que primero se llegue al fin del archivo). Pero para los streams sin formato interactivas, a lo sumo una lectura sin formato será emitida y un resultado corto no implica que se haya llegado al fin del archivo.

Un BlockingIOError se lanza si el stream subyacente está en modo no bloqueo y no tiene datos al momento.

read1(size=-1, /)

Lee y retorna hasta size en bytes con al menos una llamada al método read() (o readinto()) del stream subyacente. Esto puede ser útil si estás implementando tu propio búfer por encima de un objeto BufferedIOBase.

Si size es -1 (el valor dado) se retorna un monto arbitrario de bytes (más que cero al menos que se haya llegado al fin del archivo).

readinto(b, /)

Lee bytes a un objeto predeterminado y grabable bytes-like object b y retorna el número de bytes leídos. Por ejemplo, b puede ser un bytearray.

Como read(), varias lecturas pueden ser otorgadas al stream sin formato subyacente al menos que esto último sea interactivo.

Un BlockingIOError se lanza si el stream subyacente está en modo no bloqueo y no tiene datos al momento.

readinto1(b, /)

Leer bytes a un objeto predeterminado y grabable bytes-like object b usando por lo menos una llamada al método read() (o readinto()) del stream subyacente. Retorna la cantidad de bytes leídas.

Un BlockingIOError se lanza si el stream subyacente está en modo no bloqueo y no tiene datos al momento.

Nuevo en la versión 3.5.

write(b, /)

Escribe el bytes-like object dado, b, y retorna el número de bytes grabados (siempre el equivalente en longitud de b en bytes, ya que si falla la grabación se lanza un OSError). Dependiendo en la implementación actual estos bytes pueden ser grabados rápidamente al stream subyacente o mantenido en un búfer por razones de rendimiento y latencia.

Cuando estás en modo no bloqueo, se lanza un BlockingIOError si los datos tenían que ser grabadas al stream sin formato pero no pudo aceptar todos los datos sin bloquear.

El llamador puede otorgar o mutar b después que este método retorne algo, entonces la implementación debería acceder solamente a b durante la llamada al método.

Archivo sin formato E/S

class io.FileIO(name, mode='r', closefd=True, opener=None)

A raw binary stream representing an OS-level file containing bytes data. It inherits RawIOBase.

El name puede ser una de dos cosas:

una cadena de caracteres u objeto de tipo bytes representando la ruta del archivo en la que fue abierto. En este caso closefd es True (el valor dado) de otra manera un error será dada.

un integer representando el número de descriptores de archivos de nivel OS que resultan dando acceso a través del objeto FileIO. Cuando el objeto FileIO está cerrado este fd cerrará también a no ser que closefd esté configurado a False.

El mode puede ser 'r', 'w', 'x' o``”a”`` para lectura (el valor dado), grabación, creación exclusiva o anexando. Si no existe el archivo se creará cuando se abra para grabar o anexar; se truncará cuando se abra para grabar. Se lanzará un error FileExistsError si ya existe cuando se abra para crear. Abriendo un archivo para crear implica grabar entonces este modo se comporta similarmente a 'w'. Agrega un '+' al modo para permitir lectura y grabación simultáneas.

Los métodos read() (cuando se llama con un argumento positivo), readinto() y write() en esta clase harán solo una llamada al sistema.

Un abridor personalizado puede ser usado pasando un llamador como opener. El descriptor de archivo subyacente es obtenido llamando opener con (name, flags). opener debe retornar un descriptor de archivo abierto (pasando os.open como opener resulta con funcionamiento similar a pasando None).

El archivo recién creado es non-inheritable.

Ver la función incorporada open() para ejemplos usando el parámetro opener.

Distinto en la versión 3.3: El parámetro opener fue agregado. El modo 'x' fue agregado.

Distinto en la versión 3.4: El archivo ahora no es heredable.

FileIO provides these data attributes in addition to those from RawIOBase and IOBase:

mode

El modo dado en el constructor.

name

El nombre del archivo. Este es el descriptor del archivo cuando no se proporciona ningún nombre en el constructor.

Streams almacenados (búfer)

Streams E/S almacenadas (búfer) proveen una interfaz de más alto nivel a un dispositivo E/S que a un E/S sin formato.

class io.BytesIO(initial_bytes=b'')

A binary stream using an in-memory bytes buffer. It inherits BufferedIOBase. The buffer is discarded when the close() method is called.

El argumento opcional initial_bytes es un bytes-like object que contiene datos iniciales.

BytesIO provee o anula estos métodos además de los de BufferedIOBase y IOBase:

getbuffer()

Retorna una vista legible y grabable acerca de los contenidos del búfer sin copiarlos. Además mutando la vista actualizará de forma transparente los contenidos del búfer:

>>> b = io.BytesIO(b"abcdef")
>>> view = b.getbuffer()
>>> view[2:4] = b"56"
>>> b.getvalue()
b'ab56ef'

Nota

Mientras exista la vista el objeto BytesIO no se le puede cambiar el tamaño o cerrado.

Nuevo en la versión 3.2.

getvalue()

Retorna bytes que contiene los contenidos enteros del búfer.

read1(size=-1, /)

En la clase BytesIO esto es lo mismo que read().

Distinto en la versión 3.7: Ahora es opcional el argumento size.

readinto1(b, /)

En la clase BytesIO esto es lo mismo que readinto().

Nuevo en la versión 3.5.

class io.BufferedReader(raw, buffer_size=DEFAULT_BUFFER_SIZE)

A buffered binary stream providing higher-level access to a readable, non seekable RawIOBase raw binary stream. It inherits BufferedIOBase.

When reading data from this object, a larger amount of data may be requested from the underlying raw stream, and kept in an internal buffer. The buffered data can then be returned directly on subsequent reads.

El constructor crea un BufferedReader para el stream legible sin formato raw y buffer_size. Si se omite buffer_size se usa DEFAULT_BUFFER_SIZE.

BufferedReader provee o anula los métodos en adición a los de BufferedIOBase y IOBase:

peek(size=0, /)

Retorna bytes del stream sin avanzar la posición. Al menos una lectura se hace al stream sin formato para satisfacer el llamado. El número de bytes retornados puede ser menor o mayor al solicitado.

read(size=-1, /)

Lee y retorna size bytes o si no se da size, o es negativo, hasta el fin del archivo o si la llamada leída podría bloquear in modo no bloquear.

read1(size=-1, /)

Lee y retorna hasta el tamaño size en bytes con solo un llamado al stream. Si al menos un byte pasa por el proceso de búfer, solo se retornan buffered bytes. De lo contrario se realiza un llamado de lectura de un stream sin formato.

Distinto en la versión 3.7: Ahora es opcional el argumento size.

class io.BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)

A buffered binary stream providing higher-level access to a writeable, non seekable RawIOBase raw binary stream. It inherits BufferedIOBase.

When writing to this object, data is normally placed into an internal buffer. The buffer will be written out to the underlying RawIOBase object under various conditions, including:

cuando el búfer se vuelve demasiado pequeño para todos los datos pendientes;

cuando se llama flush();

cuando se pide un método seek() (para objetos BufferedRandom);

cuando el objeto BufferedWriter is cerrado o anulado.

El constructor crea un BufferedWriter para el stream grabable raw. Si no es dado el buffer_size, recurre el valor DEFAULT_BUFFER_SIZE.

BufferedWriter provee o anula estos métodos además de los de BufferedIOBase y IOBase:

flush()

Forzar bytes retenidos en el búfer al stream sin formato. Un BlockingIOError debería ser lanzado si el stream sin formato bloquea.

write(b, /)

Escribe el bytes-like object, b, y retorna el número de bytes grabados. Cuando estás en modo no-bloqueo, se lanza un BlockingIOError si el búfer tiene que ser escrito pero el stream sin formato bloquea.

class io.BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)

A buffered binary stream providing higher-level access to a seekable RawIOBase raw binary stream. It inherits BufferedReader and BufferedWriter.

El constructor crea un lector y una grabación para un stream sin formato buscable, dado en el primer argumento. Si se omite el buffer_size este recae sobre el valor predeterminado DEFAULT_BUFFER_SIZE.

BufferedRandom es capaz de todo lo que puede hacer BufferedReader o BufferedWriter. Adicionalmente, se garantiza implementar seek() y tell().

class io.BufferedRWPair(reader, writer, buffer_size=DEFAULT_BUFFER_SIZE, /)

A buffered binary stream providing higher-level access to two non seekable RawIOBase raw binary streams—one readable, the other writeable. It inherits BufferedIOBase.

reader y writer son objetos RawIOBase que son respectivamente legibles y escribibles. Si se omite buffer_size este se recae sobre el valor predeterminado DEFAULT_BUFFER_SIZE.

BufferedRWPair implementa todos los métodos de BufferedIOBase excepto por detach(), que lanza un UnsupportedOperation.

Advertencia

BufferedRWPair no intenta sincronizar accesos al stream sin formato subyacente. No debes pasar el mismo objeto como legible y escribible; usa BufferedRandom en su lugar.

E/S Texto

class io.TextIOBase

Base class for text streams. This class provides a character and line based interface to stream I/O. It inherits IOBase.

TextIOBase provee o anula estos atributos y métodos de datos además de los de IOBase:

encoding

El nombre de la codificación utilizada para decodificar los bytes del stream a cadenas de caracteres y para codificar cadenas de caracteres en bytes.

errors

La configuración de error del decodificador o codificador.

newlines

Una cadena de caracteres, una tupla de cadena de caracteres, o None, indicando las nuevas líneas traducidas hasta ese momento. Dependiendo de la implementación y los indicadores iniciales del constructor, esto puede no estar disponible.

buffer

El búfer binario subyacente (una instancia BufferedIOBase) que maneja TextIOBase. Esto no es parte del API de TextIOBase y puede no existir en algunas implementaciones.

detach()

Separa el búfer binario subyacente de TextIOBase y lo retorna.

Una vez que se ha separado el búfer subyacente, la TextIOBase está en un estado inutilizable.

Algunas implementaciones de TextIOBase, como StringIO, puede no tener el concepto de un búfer subyacente y llamar a este método se lanzará UnsupportedOperation.

Nuevo en la versión 3.1.

read(size=-1, /)

Lee y retorna como máximo size caracteres del stream como un str singular. Si size es negativo o None, lee hasta llegar al fin del archivo.

readline(size=-1, /)

Leer hasta la nueva línea o fin del archivo y retorna un str singular. Si el stream está al fin del archivo una cadena de caracteres se retorna.

Si se especifica size como máximo size de caracteres será leído.

seek(offset, whence=SEEK_SET, /)

Cambia la posición del stream dada offset. El comportamiento depende del parámetro whence. El valor dado de whence es SEEK_SET.

SEEK_SET o 0: buscar el inicio del stream (el dado); offset debería ser un número dado por TextIOBase.tell(), o cero. Cualquier otro valor offset produce comportamiento indefinido.

SEEK_CUR o 1: buscar la posición actual; offset debería ser cero, que es una operación no (no se apoya ningún otro valor).

SEEK_END o 2: buscar el fin del stream; offset debería ser cero (cualquier otro valor no es apoyado).

Retorna la nueva posición absoluta como un número opaco.

Nuevo en la versión 3.1: Los constantes``SEEK_*``.

tell()

Retorna la posición actual de la secuencia como un número opaco. El número no suele representar una cantidad de bytes en el almacenamiento binario subyacente.

write(s, /)

Escribe la cadena de caracteres s al stream y retorna el número de caracteres grabadas.

class io.TextIOWrapper(buffer, encoding=None, errors=None, newline=None, line_buffering=False, write_through=False)

A buffered text stream providing higher-level access to a BufferedIOBase buffered binary stream. It inherits TextIOBase.

encoding da el nombre de la codificación con que el stream será codificada o descodificado. Se da al valor predeterminado locale.getpreferredencoding(False).

errors es una cadena de caracteres opcional que especifica cómo se manejan los errores codificados y descodificados. Pasa 'strict' para lanzar una excepción ValueError si hay un error codificado (el valor predeterminado None tiene el mismo efecto), o pasa 'ignore' para ignorar errores. (Tenga en cuenta que ignorar errores puede llevar a perder datos). 'replace' causa un marcador de reemplazo (como '?') para ser insertado donde haya datos mal formados. 'backslashreplace' reemplaza datos mal formados con una secuencia de escape de tipo barra invertida. Cuando se escribe, 'xmlcharrefreplace' (reemplazar con la referencia apropiada de XML) o 'namereplace' (reemplazar con secuencias de caracteres \N{…}) pueden ser usadas. Cualquier otro nombre de manejador de errores que hayan sido registrados con codecs.register_error() también son validas.

newline controla cómo finalizar las terminaciones de líneas. Pueden ser None, '', '\n', '\r', and '\r\n'. Funciona de la siguiente manera:

When reading input from the stream, if newline is None, universal newlines mode is enabled. Lines in the input can end in '\n', '\r', or '\r\n', and these are translated into '\n' before being returned to the caller. If newline is '', universal newlines mode is enabled, but line endings are returned to the caller untranslated. If newline has any of the other legal values, input lines are only terminated by the given string, and the line ending is returned to the caller untranslated.

Al escribir la salida al stream, si newline es None, cualquier carácter '\n' escrito son traducidos a la línea separador default del sistema, os.linesep. Si newline es '' o '\n', la traducción no ocurre. Si newline es de cualquier de los otros valores legales, cualquier carácter '\n' escrito es traducido a la cadena de caracteres dada.

Si line_buffering es True, se implica flush() cuando una llamada a grabar contiene un carácter de nueva línea o un retorno.

Si write_through es True, llamadas a write() no garantizan ser pasados por el proceso de búfer: cualquier dato grabado en el objeto TextIOWrapper es inmediatamente manejado por el buffer binario subyacente.

Distinto en la versión 3.3: Se ha agregado el argumento write_through.

Distinto en la versión 3.3: La codificación (encoding) por defecto es ahora locale.getpreferredencoding(False) en vez de locale.getpreferredencoding(). No cambie temporalmente la codificación local usando locale.setlocale(), use la codificación local actual en vez del preferido del usuario.

TextIOWrapper provides these data attributes and methods in addition to those from TextIOBase and IOBase:

line_buffering

Si el almacenamiento en línea está habilitado.

write_through

Si grabaciones son pasadas inmediatamente al búfer binario subyacente.

Nuevo en la versión 3.7.

reconfigure(*[, encoding][, errors][, newline][, line_buffering][, write_through])

Reconfigura este stream textual usando las nuevas configuraciones de encoding, errors, newline, line_buffering y write_through.

Los parámetros que no son especificados mantienen las configuraciones actuales, excepto por errors='strict' cuando encoding se especifica pero errors no está especificado.

No es posible cambiar la codificación o nueva línea si algunos datos han sido captados por el stream. Sin embargo, cambiando la codificación después de grabar es posible.

Este método hace una nivelación implícita del stream antes de configurar los nuevos parámetros.

Nuevo en la versión 3.7.

class io.StringIO(initial_value='', newline='\n')

A text stream using an in-memory text buffer. It inherits TextIOBase.

The text buffer is discarded when the close() method is called.

El valor inicial del búfer puede ser configurado dando initial_value. Si la traducción de la nueva línea es habilitado, nuevas líneas serán codificado como si fuera por write(). El stream está posicionado al inicio del búfer.

The newline argument works like that of TextIOWrapper, except that when writing output to the stream, if newline is None, newlines are written as \n on all platforms.

StringIO provides this method in addition to those from TextIOBase and IOBase:

getvalue()

Retorna un str que contiene el contenido entero de los búfer. Nuevas lineas son descodificados como si fuera read(), aunque la posición de la transmisión no haya cambiado.

Ejemplos de uso:

import io

output = io.StringIO()
output.write('First line.\n')
print('Second line.', file=output)

# Retrieve file contents -- this will be
# 'First line.\nSecond line.\n'
contents = output.getvalue()

# Close object and discard memory buffer --
# .getvalue() will now raise an exception.
output.close()

class io.IncrementalNewlineDecoder

Un códec auxiliar que descodifica nuevas líneas para el modo universal newlines. Hereda codecs.IncrementalDecoder.

Rendimiento

Esta sección discute el rendimiento de las implementaciones concretas de E/S proporcionadas.

E/S Binaria

Leyendo y grabando solamente grandes porciones de datos incluso cuando el usuario pide para solo un byte, E/S de tipo búfer esconde toda ineficiencia llamando y ejecutando las rutinas E/S del sistema operativo que no ha pasado por el proceso de búfer. La ganancia depende en el OS y el tipo de E/S que se ejecuta. Por ejemplo, en algunos sistemas operativos modernos como Linux, un disco E/S sin búfer puede ser rápido como un E/S búfer. Al final, sin embargo, es que el E/S búfer ofrece rendimiento predecible independientemente de la plataforma y el dispositivo de respaldo. Entonces es siempre preferible user E/S búfer que E/S sin búfer para datos binarios.

E/S Texto

E/S de tipo texto por sobre un almacenamiento binario (como un archivo) es más lento que un E/S binario sobre el mismo almacenamiento porque requiere conversiones entre unicode y datos binarios usando un códec de caracteres. Esto puede ser notable al manejar datos enormes de texto como archivos de registro. También TextIOWrapper.tell() y TextIOWrapper.seek() son bastante lentos debido al uso del algoritmo de reconstrucción.

StringIO, sin embargo, es un contenedor unicode nativo en memoria y exhibirá una velocidad similar a BytesIO.

Multihilo

objetos FileIO son seguros para subprocesos en la medida en que las llamadas al sistema operativo(como read(2) en Unix) que envuelven también son seguros para subprocesos.

Objetos binarios búfer (instancias de BufferedReader, BufferedWriter, BufferedRandom y BufferedRWPair) protegen sus estructuras internas usando un bloqueo; es seguro, entonces, llamarlos de varios hilos a la vez.

objetos TextIOWrapper no son seguros para subprocesos.

Reentrada

Objetos binarios búfer (instancias de BufferedReader, BufferedWriter, BufferedRandom y BufferedRWPair) no son reentrante. Mientras llamadas reentrantes no ocurren en situaciones normales pueden surgir haciendo E/S en un manejador signal. Si un hilo trata de entrar de nuevo a un objeto búfer que se está accediendo actualmente, se lanza un RuntimeError. Tenga en cuenta que esto no prohíbe un hilo diferente entrando un objeto búfer.

The above implicitly extends to text files, since the open() function will wrap a buffered object inside a TextIOWrapper. This includes standard streams and therefore affects the built-in print() function as well.

time — Tiempo de acceso y conversiones

Este módulo proporciona varias funciones relacionadas con el tiempo. Para la funcionalidad relacionada, consulte también los módulos datetime y calendar.

Aunque este módulo siempre está disponible, no todas las funciones están disponibles en todas las plataformas. La mayoría de las funciones definidas en este módulo llaman a la plataforma de biblioteca C funciones con el mismo nombre. A veces puede ser útil consultar la documentación de la plataforma, ya que la semántica de estas funciones varía entre plataformas.

Una explicación de algunas terminologías y convenciones está en orden.

El epoch es el punto donde comienza el tiempo, y depende de la plataforma. Para Unix, la época es el 1 de enero de 1970, 00:00:00 (UTC). Para averiguar cuál es la época en una plataforma determinada, mire time.gmtime(0).

El término seconds since the epoch se refiere al número total de segundos transcurridos desde la época, excluyendo típicamente leap seconds [https://en.wikipedia.org/wiki/Leap_second] . Los segundos bisiestos se excluyen de este total en todas las plataformas compatibles con POSIX.

Es posible que las funciones de este módulo no manejen fechas y horas antes de la época o mucho en el futuro. El punto de corte en el futuro está determinado por la biblioteca C; para sistemas de 32 bits, normalmente es en 2038.

Función strptime() puede analizar años de 2 dígitos cuando se le da el código de formato %y. Cuando se analizan los años de 2 dígitos, se convierten de acuerdo con los estándares POSIX e ISO C: los valores 69–99 se asignan a 1969–1999, y los valores 0–68 se asignan a 2000–2068.

UTC es la hora universal coordinada (anteriormente conocida como hora media de Greenwich, o GMT). El acrónimo UTC no es un error, sino un compromiso entre inglés y francés.

El horario de verano es el horario de verano, un ajuste de la zona horaria por (generalmente) una hora durante parte del año. Las reglas DST son mágicas (determinadas por la ley local) y pueden cambiar de un año a otro. La biblioteca C tiene una tabla que contiene las reglas locales (a menudo se lee desde un archivo del sistema para la flexibilidad) y es la única fuente de verdadera sabiduría en este sentido.

La precisión de las diversas funciones en tiempo real puede ser inferior a la sugerida por las unidades en las que se expresa su valor o argumento. P.ej. En la mayoría de los sistemas Unix, el reloj «funciona» solo 50 o 100 veces por segundo.

Por otro lado, la precisión de time() y sleep() es mejor que sus equivalentes Unix: los tiempos se expresan como números de coma flotante, time() retorna el tiempo más preciso disponible (usando Unix gettimeofday() donde esté disponible) y sleep() aceptará un tiempo con una fracción distinta de cero (Unix select() se usa para implementar esto, donde esté disponible).

El valor de tiempo retornado por gmtime(), localtime(), y strptime(), y aceptado por asctime(), mktime() y strftime(), es una secuencia de 9 enteros. Los valores de retorno de gmtime(), localtime(), y strptime() también ofrecen nombres de atributos para campos individuales.

Ver struct_time para una descripción de estos objetos.

Distinto en la versión 3.3: El tipo struct_time se extendió para proporcionar los atributos tm_gmtoff y tm_zone cuando la plataforma admite los miembros correspondientes de struct tm.

Distinto en la versión 3.6: Los atributos struct_time tm_gmtoff y tm_zone ahora están disponibles en todas las plataformas.

Use las siguientes funciones para convertir entre representaciones de tiempo:

Desde

A

Usar

segundos desde la época

struct_time en UTC

gmtime()

segundos desde la época

struct_time en hora local

localtime()

struct_time en UTC

segundos desde la época

calendar.timegm()

struct_time en hora local

segundos desde la época

mktime()

Las Funciones

time.asctime([t])

Convierta una tupla o struct_time que represente una hora retornada por gmtime() o localtime() en una cadena de la siguiente forma: 'Dom 20 de junio 23:21:05 1993'. El campo del día tiene dos caracteres de largo y se rellena con espacio si el día es un solo dígito, por ejemplo: 'Miercoles  9 de Julio 04:26:40 1993'.

Si no se proporciona t, se utiliza la hora actual retornada por localtime(). La información regional no es utilizada por asctime().

Nota

A diferencia de la función C del mismo nombre, asctime() no agrega una nueva línea final.

time.pthread_getcpuclockid(thread_id)

Retorna el clk_id del reloj de tiempo de CPU específico del subproceso para el thread_id especificado.

Utilice threading.get_ident() o el atributo ident de objetos threading.Thread para obtener un valor adecuado para * thread_id*.

Advertencia

Pasar un * thread_id * no válido o caducado puede provocar un comportamiento indefinido, como un error de segmentación.

Disponibilidad: Unix (consulte la página de manual para pthread_getcpuclockid(3) para más información).

Nuevo en la versión 3.7.

time.clock_getres(clk_id)

Retorna la resolución (precisión) del reloj especificado clk_id. Consulte Constantes de ID de reloj para obtener una lista de los valores aceptados para clk_id.

Disponibilidad: Unix.

Nuevo en la versión 3.3.

time.clock_gettime(clk_id) → float

Retorna la hora del reloj especificado clk_id. Consulte Constantes de ID de reloj para obtener una lista de los valores aceptados para clk_id.

Disponibilidad: Unix.

Nuevo en la versión 3.3.

time.clock_gettime_ns(clk_id) → int

Similar a clock_gettime() pero retorna el tiempo en nanosegundos.

Disponibilidad: Unix.

Nuevo en la versión 3.7.

time.clock_settime(clk_id, time: float)

Establece la hora del reloj especificado clk_id. Actualmente, CLOCK_REALTIME es el único valor aceptado para clk_id.

Disponibilidad: Unix.

Nuevo en la versión 3.3.

time.clock_settime_ns(clk_id, time: int)

Similar a clock_settime() pero establece el tiempo con nanosegundos.

Disponibilidad: Unix.

Nuevo en la versión 3.7.

time.ctime([secs])

Convierta un tiempo expresado en segundos desde la época en una cadena de una forma: 'Dom 20 de junio 23:21:05 1993' que representa la hora local. El campo del día tiene dos caracteres de largo y se rellena con espacio si el día es de un solo dígito, por ejemplo: 'Miercoles Junio 9 04:26:40 1993'.

Si no se proporciona secs o None, se utiliza la hora actual retornada por time(). ctime(secs) es equivalente a asctime(localtime(secs)). La información de configuración regional no la utiliza ctime().

time.get_clock_info(name)

Obtenga información sobre el reloj especificado como un objeto de espacio de nombres. Los nombres de reloj admitidos y las funciones correspondientes para leer su valor son:

'monotonic': time.monotonic()

'perf_counter': time.perf_counter()

'process_time': time.process_time()

'thread_time': time.thread_time()

'time': time.time()

The result has the following attributes:

afjustable: True si el reloj se puede cambiar automáticamente (por ejemplo, por un demonio NTP) o manualmente por el administrador del sistema, False de lo contrario

implementation: el nombre de la función C subyacente utilizada para obtener el valor del reloj. Consulte Constantes de ID de reloj para conocer los posibles valores.

monotonic: `` Verdadero`` si el reloj no puede retroceder, False de lo contrario

resolution: la resolución del reloj en segundos (float)

Nuevo en la versión 3.3.

time.gmtime([secs])

Convierta un tiempo expresado en segundos desde la época en a struct_time en UTC en el que el indicador dst siempre es cero. Si no se proporciona secs o None, se utiliza la hora actual retornada por time(). Se ignoran fracciones de segundo. Consulte más arriba para obtener una descripción del objeto struct_time. Ver calendar.timegm() para el inverso de esta función.

time.localtime([secs])

Como gmtime() pero se convierte a la hora local. Si no se proporciona secs o None, se utiliza la hora actual retornada por time(). El indicador dst se establece en 1 cuando DST se aplica al tiempo dado.

localtime() may raise OverflowError, if the timestamp is outside the range of values supported by the platform C localtime() or gmtime() functions, and OSError on localtime() or gmtime() failure. It’s common for this to be restricted to years between 1970 and 2038.

time.mktime(t)

Esta es la función inversa de localtime(). Su argumento es struct_time o una 9-tupla completa (ya que se necesita la bandera dst; use -1 como la bandera dst si es desconocida) que expresa la hora en hora local, no UTC. Retorna un número de coma flotante, por compatibilidad con time(). Si el valor de entrada no se puede representar como un tiempo válido, se generará OverflowError o ValueError (que depende de si Python o las bibliotecas C subyacentes capturan el valor no válido). La fecha más temprana para la que puede generar una hora depende de la plataforma.

time.monotonic() → float

Retorna el valor (en segundos fraccionarios) de un reloj monotónico, es decir, un reloj que no puede retroceder. El reloj no se ve afectado por las actualizaciones del reloj del sistema. El punto de referencia del valor retornado no está definido, de modo que sólo la diferencia entre los resultados de dos llamadas es válida.

Nuevo en la versión 3.3.

Distinto en la versión 3.5: La función ahora está siempre disponible y siempre en todo el sistema.

time.monotonic_ns() → int

Similar a monotonic(), pero el tiempo de retorno es en nanosegundos.

Nuevo en la versión 3.7.

time.perf_counter() → float

Retorna el valor (en fracciones de segundo) de un contador de rendimiento, es decir, un reloj con la resolución más alta disponible para medir una corta duración. Incluye el tiempo transcurrido durante el sueño y abarca todo el sistema. El punto de referencia del valor retornado no está definido, de modo que sólo la diferencia entre los resultados de dos llamadas es válida.

Nuevo en la versión 3.3.

time.perf_counter_ns() → int

Similar a perf_counter(), pero el tiempo de retorno es en nanosegundos.

Nuevo en la versión 3.7.

time.process_time() → float

Retorna el valor (en fracciones de segundo) de la suma del sistema y el tiempo de CPU del usuario del proceso actual. No incluye el tiempo transcurrido durante el sueño. Es todo el proceso por definición. El punto de referencia del valor retornado no está definido, de modo que sólo la diferencia entre los resultados de dos llamadas es válida.

Nuevo en la versión 3.3.

time.process_time_ns() → int

Similar a process_time() pero retorna el tiempo en nanosegundos.

Nuevo en la versión 3.7.

time.sleep(secs)

Suspende la ejecución del hilo que lo invoca por el número de segundos dado. El argumento puede ser un número de punto flotante para indicar un tiempo de suspensión más preciso. El tiempo de suspensión real puede ser menor que el solicitado porque cualquier señal detectada terminará la función sleep() siguiendo la rutina de captura de la señal. El tiempo de suspensión también puede ser más largo que el solicitado por una cantidad arbitraria debido a la programación de otra actividad en el sistema.

Distinto en la versión 3.5: La función ahora duerme al menos * segundos * incluso si el sueño es interrumpido por una señal, excepto si el manejador de la señal genera una excepción (ver PEP 475 [https://www.python.org/dev/peps/pep-0475] para la justificación).

time.strftime(format[, t])

Convierta una tupla o struct_time que represente un tiempo retornado por gmtime() o localtime() en una cadena como se especifica mediante el argumento format. Si no se proporciona t, se utiliza la hora actual retornada por localtime(). format debe ser una cadena. ValueError se genera si algún campo en t está fuera del rango permitido.

0 es un argumento legal para cualquier posición en la tupla de tiempo; si normalmente es ilegal, el valor se fuerza a uno correcto.

Las siguientes directivas se pueden incrustar en la cadena format. Se muestran sin el ancho de campo opcional y la especificación de precisión, y se reemplazan por los caracteres indicados en el resultado strftime():

Directiva

Sentido

Notas

%a

Nombre abreviado del día local de la localidad.

%A

Nombre completo del día laborable de Localidad.

%b

Nombre abreviado del mes de la localidad.

%B

Nombre completo del mes de la localidad.

%c

Representación apropiada de fecha y hora de la localidad.

%d

Día del mes como número decimal [01,31].

%H

Hora (reloj de 24 horas) como un número decimal [00,23].

%I

Hora (reloj de 12 horas) como un número decimal [01,12].

%j

Día del año como número decimal [001,366].

%m

Mes como un número decimal [01,12].

%M

Minuto como un número decimal [00,59].

%p

El equivalente de la configuración regional de AM o PM.

(1)

%S

Segunda como un número decimal [00,61].

(2)

%U

Número de semana del año (domingo como primer día de la semana) como número decimal [00,53]. Todos los días en un nuevo año anterior al primer domingo se consideran en la semana 0.

(3)

%w

Día de la semana como un número decimal [0 (domingo), 6].

%W

Número de semana del año (lunes como primer día de la semana) como número decimal [00,53]. Todos los días en un nuevo año anterior al primer lunes se consideran en la semana 0.

(3)

%x

Representación de fecha apropiada de la localidad.

%X

Representación del tiempo apropiado de la localidad.

%y

Año sin siglo como número decimal [00,99].

%Y

Año con siglo como número decimal.

%z

Time zone offset indicating a positive or negative time difference from UTC/GMT of the form +HHMM or -HHMM, where H represents decimal hour digits and M represents decimal minute digits [-23:59, +23:59]. 1

%Z

Time zone name (no characters if no time zone exists). Deprecated. 1

%%

Un carácter literal '%'.

Notas:

Cuando se usa con la función strptime(), la directiva %p solo afecta el campo de hora de salida si se usa la directiva %I para analizar la hora.

El rango realmente es `` 0`` a `` 61``; el valor `` 60`` es válido en las marcas de tiempo que representan segundos intercalares [https://en.wikipedia.org/wiki/Leap_second] y el valor 61 es compatible por razones históricas.

Cuando se usa con la función strptime(), %U y %W solo se usan en los cálculos cuando se especifica el día de la semana y el año.

Here is an example, a format for dates compatible with that specified in the RFC 2822 [https://tools.ietf.org/html/rfc2822.html] Internet email standard. 1

>>> from time import gmtime, strftime
>>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime())
'Thu, 28 Jun 2001 14:17:15 +0000'

Es posible que se admitan directivas adicionales en ciertas plataformas, pero solo las que se enumeran aquí tienen un significado estandarizado por ANSI C. Para ver el conjunto completo de códigos de formato admitidos en su plataforma, consulte la documentación de strftime(3).

En algunas plataformas, una especificación de precisión y ancho de campo opcional puede seguir inmediatamente el '%' inicial de una directiva en el siguiente orden; Esto tampoco es portátil. El ancho del campo es normalmente 2 excepto %j donde es 3.

time.strptime(string[, format])

Analiza una cadena que representa un tiempo de acuerdo con un formato. El valor de retorno es a struct_time como lo retorna gmtime() o localtime().

El parámetro format utiliza las mismas directivas que las utilizadas por strftime(); el valor predeterminado es "%a %b %d %H:%M:%S %Y" que coincide con el formato retornado por ctime(). Si string no se puede analizar de acuerdo con format, o si tiene un exceso de datos después del análisis, se excita ValueError. Los valores predeterminados utilizados para completar los datos faltantes cuando no se pueden inferir valores más precisos son (1900, 1, 1, 0, 0, 0, 0, 1, -1). Tanto string como format deben ser strings.

Por ejemplo:

>>> import time
>>> time.strptime("30 Nov 00", "%d %b %y")
time.struct_time(tm_year=2000, tm_mon=11, tm_mday=30, tm_hour=0, tm_min=0,
                 tm_sec=0, tm_wday=3, tm_yday=335, tm_isdst=-1)

La compatibilidad con la directiva %Z se basa en los valores contenidos en `` tzname`` y en si daylight es verdadero. Debido a esto, es específico de la plataforma, excepto para reconocer UTC y GMT que siempre se conocen (y se consideran zonas horarias que no son de horario de verano).

Solo se admiten las directivas especificadas en la documentación. Debido a que strftime() se implementa por plataforma, a veces puede ofrecer más directivas que las enumeradas. Pero strptime() es independiente de cualquier plataforma y, por lo tanto, no necesariamente admite todas las directivas disponibles que no están documentadas como compatibles.

class time.struct_time

El tipo de secuencia de valores de tiempo retornado por gmtime(), localtime(), y strptime(). Es un objeto con una interfaz named tuple: se puede acceder a los valores por índice y por nombre de atributo. Los siguientes valores están presentes:

Índice

Atributo

Valores

0

tm_year

(por ejemplo, 1993)

1

tm_mon

rango [1, 12]

2

tm_mday

rango [1, 31]

3

tm_hour

rango [0, 23]

4

tm_min

rango [0, 59]

5

tm_sec

rango [0, 61]; ver (2) in strftime() descripción

6

tm_wday

rango [0, 6], Lunes es 0

7

tm_yday

rango [1, 366]

8

tm_isdst

0, 1 ó -1; ver abajo

N/A

tm_zone

abreviatura del nombre de la zona horaria

N/A

tm_gmtoff

desplazamiento al este de UTC en segundos

Tenga en cuenta que, a diferencia de la estructura C, el valor del mes es un rango de [1, 12], no [0, 11].

En llamadas a mktime(), tm_isdst puede establecerse en 1 cuando el horario de verano está vigente y 0 cuando no lo está. Un valor de -1 indica que esto no se conoce y, por lo general, se completará el estado correcto.

Cuando una tupla con una longitud incorrecta se pasa a una función que espera a struct_time, o que tiene elementos del tipo incorrecto, se genera a TypeError.

time.time() → float

Retorna el tiempo en segundos desde epoch como un número de coma flotante. La fecha específica de la época y el manejo de los leap seconds [https://en.wikipedia.org/wiki/Leap_second] depende de la plataforma. En Windows y la mayoría de los sistemas Unix, la época es el 1 de enero de 1970, 00:00:00 (UTC) y los segundos bisiestos no se cuentan para el tiempo en segundos desde la época. Esto se conoce comúnmente como Tiempo Unix [https://en.wikipedia.org/wiki/Unix_time]. Para saber cuál es la época en una plataforma determinada, mire gmtime(0).

Tenga en cuenta que aunque el tiempo siempre se retorna como un número de coma flotante, no todos los sistemas proporcionan tiempo con una precisión superior a 1 segundo. Si bien esta función normalmente retorna valores no decrecientes, puede retornar un valor más bajo que una llamada anterior si el reloj del sistema se ha retrasado entre las dos llamadas.

El número retornado por time() se puede convertir a un formato de hora más común (es decir, año, mes, día, hora, etc.) en UTC pasándolo a función gmtime() o en hora local pasándola a la función localtime(). En ambos casos se retorna un objeto struct_time, desde el cual se puede acceder a los componentes de la fecha del calendario como atributos.

time.thread_time() → float

Retorna el valor (en fracciones de segundo) de la suma del sistema y el tiempo de CPU del usuario del subproceso actual. No incluye el tiempo transcurrido durante el sueño. Es específico del hilo por definición. El punto de referencia del valor retornado no está definido, de modo que sólo la diferencia entre los resultados de dos llamadas en el mismo hilo es válida.

Disponibilidad: Windows, Linux, sistemas Unix que admiten `` CLOCK_THREAD_CPUTIME_ID``.

Nuevo en la versión 3.7.

time.thread_time_ns() → int

Similar a thread_time() pero retorna el tiempo en nanosegundos.

Nuevo en la versión 3.7.

time.time_ns() → int

Similar a time() pero retorna el tiempo como un número entero de nanosegundos desde la época.

Nuevo en la versión 3.7.

time.tzset()

Restablezca las reglas de conversión de tiempo utilizadas por las rutinas de la biblioteca. La variable de entorno TZ especifica cómo se hace esto. También establecerá las variables tzname (de variable de entorno TZ), timezone (segundos que no son DST al oeste de UTC), altzone (segundos DST al oeste de UTC ) y daylight (a 0 si esta zona horaria no tiene ninguna regla de horario de verano, o a cero si hay un horario pasado, presente o futuro cuando se aplica el horario de verano).

Disponibilidad: Unix.

Nota

Aunque en muchos casos, cambiar la variable de entorno TZ puede afectar la salida de funciones como localtime() sin llamar a tzset(), no se debe confiar en este comportamiento.

La variable de entorno TZ no debe contener espacios en blanco.

El formato estándar de la variable de entorno TZ es (espacio en blanco agregado para mayor claridad):

std offset [dst [offset [,start[/time], end[/time]]]]

Donde están los componentes:

std y dst

Tres o más caracteres alfanuméricos que dan las abreviaturas de zona horaria. Estos se propagarán en time.tzname

offset

El desplazamiento tiene la forma: ± hh[:mm[:ss]]. Esto indica el valor agregado de la hora local para llegar a UTC. Si está precedido por un “-”, la zona horaria está al este del primer meridiano; de lo contrario, es oeste. Si no hay desplazamiento después de dst, se supone que el horario de verano es una hora antes del horario estándar.

start[/time], end[/time]

Indica cuándo cambiar hacia y desde DST. El formato de las fechas de inicio y finalización es uno de los siguientes:

Jn

El día de Julio * n * (1 <= * n * <= 365). Los días bisiestos no se cuentan, por lo que en todos los años el 28 de febrero es el día 59 y el 1 de marzo es el día 60.

n

El día julio basado en cero (0 <= * n * <= 365). Los días bisiestos se cuentan y es posible referirse al 29 de febrero.

Mm.n.d

El día d (0 <= d <= 6) de la semana n del mes m del año (1 <= n <= 5, 1 <= m <= 12, donde la semana 5 significa «el último d día del mes m», que puede ocurrir en la cuarta o quinta semana). La semana 1 es la primera semana en la que ocurre el día d. El día cero es un domingo.

time tiene el mismo formato que offset, excepto que no se permite ningún signo inicial (“-” o “+”). El valor predeterminado, si no se da el tiempo, es 02:00:00.

>>> os.environ['TZ'] = 'EST+05EDT,M4.1.0,M10.5.0'
>>> time.tzset()
>>> time.strftime('%X %x %Z')
'02:07:36 05/08/03 EDT'
>>> os.environ['TZ'] = 'AEST-10AEDT-11,M10.5.0,M3.5.0'
>>> time.tzset()
>>> time.strftime('%X %x %Z')
'16:08:12 05/08/03 AEST'

En muchos sistemas Unix (incluidos *BSD, Linux, Solaris y Darwin), es más conveniente utilizar la base de datos zoneinfo (tzfile(5)) del sistema para especificar las reglas de zona horaria. Para hacer esto, configure la variable de entorno TZ en la ruta del archivo de datos de zona horaria requerida, en relación con la raíz de la base de datos de zona horaria “zoneinfo” de los sistemas, generalmente ubicada en /usr/share/zoneinfo . Por ejemplo, 'US/Eastern', 'Australia/Melbourne', 'Egypt' o 'Europe/Amsterdam'.

>>> os.environ['TZ'] = 'US/Eastern'
>>> time.tzset()
>>> time.tzname
('EST', 'EDT')
>>> os.environ['TZ'] = 'Egypt'
>>> time.tzset()
>>> time.tzname
('EET', 'EEST')

Constantes de ID de reloj

Estas constantes se utilizan como parámetros para clock_getres() y clock_gettime().

time.CLOCK_BOOTTIME

Idéntico a CLOCK_MONOTONIC, excepto que también incluye cualquier momento en que el sistema esté suspendido.

Esto permite que las aplicaciones obtengan un reloj monotónico con suspensión sin tener que lidiar con las complicaciones de CLOCK_REALTIME, que puede tener discontinuidades si se cambia la hora usando settimeofday() o similar.

Disponibilidad: Linux 2.6.39 o posterior.

Nuevo en la versión 3.7.

time.CLOCK_HIGHRES

El sistema operativo Solaris tiene un temporizador `` CLOCK_HIGHRES`` que intenta utilizar una fuente de hardware óptima y puede brindar una resolución cercana a los nanosegundos. `` CLOCK_HIGHRES`` es el reloj de alta resolución no ajustable.

Disponibilidad: Solaris.

Nuevo en la versión 3.3.

time.CLOCK_MONOTONIC

Reloj que no se puede configurar y representa el tiempo monótono desde algún punto de partida no especificado.

Disponibilidad: Unix.

Nuevo en la versión 3.3.

time.CLOCK_MONOTONIC_RAW

Similar a CLOCK_MONOTONIC, pero proporciona acceso a un tiempo sin procesar basado en hardware que no está sujeto a ajustes NTP.

Disponibilidad: Linux 2.6.28 y posterior, macOS 10.12 y posterior.

Nuevo en la versión 3.3.

time.CLOCK_PROCESS_CPUTIME_ID

Temporizador por proceso de alta resolución desde la CPU.

Disponibilidad: Unix.

Nuevo en la versión 3.3.

time.CLOCK_PROF

Temporizador por proceso de alta resolución desde la CPU.

Disponibilidad: FreeBSD, NetBSD 7 o posterior, OpenBSD.

Nuevo en la versión 3.7.

time.CLOCK_TAI

Tiempo Atómico Internacional [https://www.nist.gov/pml/time-and-frequency-division/nist-time-frequently-asked-questions-faq#tai]

El sistema debe contar con una tabla de segundos intercalares para que éste dé la respuesta correcta. Software PTP o NTP puede mantener una tabla de segundos intercalares.

Disponibilidad: Linux.

Nuevo en la versión 3.9.

time.CLOCK_THREAD_CPUTIME_ID

Reloj de tiempo de CPU específico de subproceso.

Disponibilidad: Unix.

Nuevo en la versión 3.3.

time.CLOCK_UPTIME

Tiempo cuyo valor absoluto es el tiempo que el sistema ha estado funcionando y no suspendido, proporcionando una medición precisa del tiempo de actividad, tanto absoluta como de intervalo.

Disponibilidad: FreeBSD, OpenBSD 5.5 o posterior.

Nuevo en la versión 3.7.

time.CLOCK_UPTIME_RAW

Reloj que se incrementa monotónicamente, rastreando el tiempo desde un punto arbitrario, no afectado por los ajustes de frecuencia o tiempo y no incrementado mientras el sistema está dormido.

Disponibilidad: macOS 10.12 y posterior.

Nuevo en la versión 3.8.

La siguiente constante es el único parámetro que se puede enviar a clock_settime().

time.CLOCK_REALTIME

Reloj en tiempo real de todo el sistema. Configurar este reloj requiere los privilegios apropiados.

Disponibilidad: Unix.

Nuevo en la versión 3.3.

Constantes de zona horaria

time.altzone

El desplazamiento de la zona horaria de horario de verano local, en segundos al oeste de UTC, si se define uno. Esto es negativo si la zona horaria local del horario de verano está al este de UTC (como en Europa occidental, incluido el Reino Unido). Solo use esto si la daylight no es cero. Vea la nota abajo.

time.daylight

No es cero si se define una zona horaria DST. Vea la nota abajo.

time.timezone

El desplazamiento de la zona horaria local (no DST), en segundos al oeste de UTC (negativo en la mayoría de Europa occidental, positivo en los EE. UU., Cero en el Reino Unido). Vea la nota abajo.

time.tzname

Una tupla de dos cadenas: la primera es el nombre de la zona horaria local no DST, la segunda es el nombre de la zona horaria local DST. Si no se define la zona horaria DST, la segunda cadena no debe usarse. Vea la nota abajo.

Nota

Para las constantes de zona horaria anteriores (altzone, daylight, timezone, y tzname), el valor está determinado por las reglas de zona horaria vigentes en el momento de carga del módulo o la última vez se llama a tzset() y puede ser incorrecto en el pasado. Se recomienda utilizar tm_gmtoff y tm_zone resulta de localtime() para obtener información sobre la zona horaria.

Ver también

Modulo datetime

Más interfaz orientada a objetos para fechas y horas.

Modulo locale

Servicios de internacionalización. La configuración regional afecta la interpretación de muchos especificadores de formato en strftime() y strptime().

Modulo calendar

Funciones generales relacionadas con el calendario. timegm() es el inverso de gmtime() de este módulo.

Notas al pie

1(1,2,3)

The use of %Z is now deprecated, but the %z escape that expands to the preferred hour/minute offset is not supported by all ANSI C libraries. Also, a strict reading of the original 1982 RFC 822 [https://tools.ietf.org/html/rfc822.html] standard calls for a two-digit year (%y rather than %Y), but practice moved to 4-digit years long before the year 2000. After that, RFC 822 [https://tools.ietf.org/html/rfc822.html] became obsolete and the 4-digit year has been first recommended by RFC 1123 [https://tools.ietf.org/html/rfc1123.html] and then mandated by RFC 2822 [https://tools.ietf.org/html/rfc2822.html].

argparse — Analizador sintáctico (Parser) para las opciones, argumentos y sub-comandos de la línea de comandos

Nuevo en la versión 3.2.

Código fuente: Lib/argparse.py [https://github.com/python/cpython/tree/3.9/Lib/argparse.py]

Tutorial

Esta página contiene la información de referencia de la API. Para una introducción más amigable al análisis de la línea de comandos de Python, echa un vistazo al argparse tutorial.

El módulo argparse facilita la escritura de interfaces de línea de comandos amigables. El programa define qué argumentos requiere, y argparse averiguará cómo analizar los de sys.argv. El módulo argparse también genera automáticamente mensajes de ayuda y de uso y muestra errores cuando los usuarios dan parámetros incorrectos al programa.

Ejemplo

El siguiente código es un programa Python que toma una lista de números enteros y obtiene la suma o el máximo:

import argparse

parser = argparse.ArgumentParser(description='Process some integers.')
parser.add_argument('integers', metavar='N', type=int, nargs='+',
                    help='an integer for the accumulator')
parser.add_argument('--sum', dest='accumulate', action='store_const',
                    const=sum, default=max,
                    help='sum the integers (default: find the max)')

args = parser.parse_args()
print(args.accumulate(args.integers))

Asumiendo que el código Python anterior se guarda en un archivo llamado prog.py, se puede ejecutar en la línea de comandos y proporciona mensajes de ayuda útiles:

$ python prog.py -h
usage: prog.py [-h] [--sum] N [N ...]

Process some integers.

positional arguments:
 N           an integer for the accumulator

optional arguments:
 -h, --help  show this help message and exit
 --sum       sum the integers (default: find the max)

Cuando se ejecuta con los parámetros apropiados, muestra la suma o el máximo de los números enteros de la línea de comandos:

$ python prog.py 1 2 3 4
4

$ python prog.py 1 2 3 4 --sum
10

Si se pasan argumentos incorrectos, se mostrará un error:

$ python prog.py a b c
usage: prog.py [-h] [--sum] N [N ...]
prog.py: error: argument N: invalid int value: 'a'

Las siguientes secciones te guiarán a través de este ejemplo.

Creando un analizador sintáctico (parser)

El primer paso para usar argparse es crear un objeto ArgumentParser

>>> parser = argparse.ArgumentParser(description='Process some integers.')

El objeto ArgumentParser contendrá toda la información necesaria para analizar la línea de comandos con los tipos de datos de Python.

Añadiendo argumentos

Completar un ArgumentParser con información sobre los argumentos del programa se hace realizando llamadas al método add_argument(). Generalmente, estas llamadas le dicen a ArgumentParser cómo capturar las cadenas de caracteres de la línea de comandos y convertirlas en objetos. Esta información se almacena y se usa cuando se llama a parse_args(). Por ejemplo:

>>> parser.add_argument('integers', metavar='N', type=int, nargs='+',
...                     help='an integer for the accumulator')
>>> parser.add_argument('--sum', dest='accumulate', action='store_const',
...                     const=sum, default=max,
...                     help='sum the integers (default: find the max)')

Más tarde, llamando a parse_args() retornará un objeto con dos atributos, integers y accumulate. El atributo integers será una lista de uno o más enteros, y el atributo accumulate será la función sum(), si se especificó --sum en la línea de comandos, o la función max() si no.

Analizando argumentos

ArgumentParser analiza los argumentos mediante el método parse_args(). Éste inspeccionará la línea de comandos, convertirá cada argumento al tipo apropiado y luego invocará la acción correspondiente. En la mayoría de los casos, esto significa que un simple objeto Namespace se construirá a partir de los atributos analizados en la línea de comandos:

>>> parser.parse_args(['--sum', '7', '-1', '42'])
Namespace(accumulate=<built-in function sum>, integers=[7, -1, 42])

En un script, parse_args() será llamado típicamente sin argumentos, y la ArgumentParser determinará automáticamente los argumentos de la línea de comandos de sys.argv.

Objetos ArgumentParser

class argparse.ArgumentParser(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=argparse.HelpFormatter, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True, exit_on_error=True)

Crea un nuevo objeto ArgumentParser. Todos los parámetros deben pasarse como argumentos de palabra clave. Cada parámetro tiene su propia descripción más detallada a continuación, pero en resumen son:

prog - El nombre del programa (default: sys.argv[0])

usage - La cadena de caracteres que describe el uso del programa (por defecto: generado a partir de los argumentos añadidos al analizador)

description - Texto a mostrar antes del argumento ayuda (por defecto: ninguno)

epilog - Texto a mostrar después del argumento ayuda (por defecto: ninguno)

parents - Una lista de objetos ArgumentParser cuyos argumentos también deberían ser incluidos

formatter_class - Una clase para personalizar la salida de la ayuda

prefix_chars - El conjunto de caracteres que preceden a los argumentos opcionales (por defecto: ‘-‘)

fromfile_prefix_chars - El conjunto de caracteres que preceden a los archivos de los cuales se deberían leer los argumentos adicionales (por defecto: None)

argument_default - El valor global por defecto de los argumentos (por defecto: None)

conflict_handler - La estrategia para resolver los opcionales conflictivos (normalmente es innecesaria)

add_help - Añade una opción -h/--help al analizador (por defecto: True)

allow_abbrev - Permite abreviar las opciones largas si la abreviatura es inequívoca. (por defecto: True)

exit_on_error - Determina si ArgumentParser sale o no con información de error cuando se produce un error. (predeterminado: True)

Distinto en la versión 3.5: se añadió el parámetro allow_abbrev.

Distinto en la versión 3.8: En versiones anteriores, allow_abbrev también deshabilitaba la agrupación de banderas (flags) cortas como -vv para que sea -v -v.

Distinto en la versión 3.9: Se agregó el parámetro exit_on_error.

En las siguientes secciones se describe cómo se utiliza cada una de ellas.

prog

Por defecto, los objetos ArgumentParser utilizan sys.argv[0] para determinar cómo mostrar el nombre del programa en los mensajes de ayuda. Este valor por defecto es casi siempre deseable porque hará que los mensajes de ayuda coincidan con la forma en que el programa fue invocado en la línea de comandos. Por ejemplo, considera un archivo llamado myprogram.py con el siguiente código:

import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--foo', help='foo help')
args = parser.parse_args()

La ayuda para este programa mostrará myprogram.py como el nombre del programa (sin importar desde dónde se haya invocado el programa):

$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]

optional arguments:
 -h, --help  show this help message and exit
 --foo FOO   foo help
$ cd ..
$ python subdir/myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]

optional arguments:
 -h, --help  show this help message and exit
 --foo FOO   foo help

Para cambiar este comportamiento por defecto, se puede proporcionar otro valor usando el argumento``prog=`` para ArgumentParser:

>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.print_help()
usage: myprogram [-h]

optional arguments:
 -h, --help  show this help message and exit

Ten en cuenta que el nombre del programa, ya sea determinado a partir de sys.argv[0] o del argumento prog= , está disponible para los mensajes de ayuda usando el especificador de formato %(prog)s.

>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.add_argument('--foo', help='foo of the %(prog)s program')
>>> parser.print_help()
usage: myprogram [-h] [--foo FOO]

optional arguments:
 -h, --help  show this help message and exit
 --foo FOO   foo of the myprogram program

uso

Por defecto, ArgumentParser determina el mensaje de uso a partir de los argumentos que contiene:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', nargs='?', help='foo help')
>>> parser.add_argument('bar', nargs='+', help='bar help')
>>> parser.print_help()
usage: PROG [-h] [--foo [FOO]] bar [bar ...]

positional arguments:
 bar          bar help

optional arguments:
 -h, --help   show this help message and exit
 --foo [FOO]  foo help

El mensaje por defecto puede ser sustituido con el argumento de palabra clave usage=:

>>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')
>>> parser.add_argument('--foo', nargs='?', help='foo help')
>>> parser.add_argument('bar', nargs='+', help='bar help')
>>> parser.print_help()
usage: PROG [options]

positional arguments:
 bar          bar help

optional arguments:
 -h, --help   show this help message and exit
 --foo [FOO]  foo help

El especificador de formato %(prog)s está preparado para introducir el nombre del programa en los mensajes de ayuda.

description

La mayoría de las llamadas al constructor ArgumentParser usarán el argumento de palabra clave description=. Este argumento da una breve descripción de lo que hace el programa y cómo funciona. En los mensajes de ayuda, la descripción se muestra entre la cadena de caracteres de uso (usage) de la línea de comandos y los mensajes de ayuda para los distintos argumentos:

>>> parser = argparse.ArgumentParser(description='A foo that bars')
>>> parser.print_help()
usage: argparse.py [-h]

A foo that bars

optional arguments:
 -h, --help  show this help message and exit

Por defecto, la descripción será ajustada a una línea para que encaje en el espacio dado. Para cambiar este comportamiento, revisa el argumento formatter_class.

epilog

A algunos programas les gusta mostrar una descripción adicional del programa después de la descripción de los argumentos. Dicho texto puede ser especificado usando el argumento epilog= para ArgumentParser:

>>> parser = argparse.ArgumentParser(
...     description='A foo that bars',
...     epilog="And that's how you'd foo a bar")
>>> parser.print_help()
usage: argparse.py [-h]

A foo that bars

optional arguments:
 -h, --help  show this help message and exit

And that's how you'd foo a bar

Al igual que con el argumento description, el texto epilog= está por defecto ajustado a una línea, pero este comportamiento puede ser modificado con el argumento formatter_class para ArgumentParser.

parents

A veces, varios analizadores comparten un conjunto de argumentos comunes. En lugar de repetir las definiciones de estos argumentos, se puede usar un único analizador con todos los argumentos compartidos y pasarlo en el argumento parents= a ArgumentParser. El argumento parents= toma una lista de objetos ArgumentParser, recoge todas las acciones de posición y de opción de éstos, y añade estas acciones al objeto ArgumentParser que se está construyendo:

>>> parent_parser = argparse.ArgumentParser(add_help=False)
>>> parent_parser.add_argument('--parent', type=int)

>>> foo_parser = argparse.ArgumentParser(parents=[parent_parser])
>>> foo_parser.add_argument('foo')
>>> foo_parser.parse_args(['--parent', '2', 'XXX'])
Namespace(foo='XXX', parent=2)

>>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])
>>> bar_parser.add_argument('--bar')
>>> bar_parser.parse_args(['--bar', 'YYY'])
Namespace(bar='YYY', parent=None)

Ten en cuenta que la mayoría de los analizadores padre especificarán add_help=False. De lo contrario, el ArgumentParser verá dos opciones -h/—help (una para el padre y otra para el hijo) y generará un error.

Nota

Debes inicializar completamente los analizadores antes de pasarlos a través de parents=. Si cambias los analizadores padre después del analizador hijo, esos cambios no se reflejarán en el hijo.

formatter_class

los objetos ArgumentParser permiten personalizar el formato de la ayuda especificando una clase de formato alternativa. Actualmente, hay cuatro clases de este tipo:

class argparse.RawDescriptionHelpFormatter

class argparse.RawTextHelpFormatter

class argparse.ArgumentDefaultsHelpFormatter

class argparse.MetavarTypeHelpFormatter

RawDescriptionHelpFormatter y RawTextHelpFormatter dan más control sobre cómo se muestran las descripciones de texto. Por defecto, los objetos ArgumentParser ajustan a la línea los textos de description y epilog en los mensajes de ayuda de la línea de comandos:

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     description='''this description
...         was indented weird
...             but that is okay''',
...     epilog='''
...             likewise for this epilog whose whitespace will
...         be cleaned up and whose words will be wrapped
...         across a couple lines''')
>>> parser.print_help()
usage: PROG [-h]

this description was indented weird but that is okay

optional arguments:
 -h, --help  show this help message and exit

likewise for this epilog whose whitespace will be cleaned up and whose words
will be wrapped across a couple lines

Pasar RawDescriptionHelpFormatter como formatter_class= indica que description y epilog ya tienen el formato correcto y no deben ser ajustados a la línea:

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     formatter_class=argparse.RawDescriptionHelpFormatter,
...     description=textwrap.dedent('''\
...         Please do not mess up this text!
...         --------------------------------
...             I have indented it
...             exactly the way
...             I want it
...         '''))
>>> parser.print_help()
usage: PROG [-h]

Please do not mess up this text!
--------------------------------
   I have indented it
   exactly the way
   I want it

optional arguments:
 -h, --help  show this help message and exit

RawTextHelpFormatter mantiene espacios en blanco para todo tipo de texto de ayuda, incluyendo descripciones de argumentos. Sin embargo, varias líneas nuevas son reemplazadas por una sola. Si deseas conservar varias líneas en blanco, añade espacios entre las nuevas líneas.

ArgumentDefaultsHelpFormatter añade automáticamente información sobre los valores por defecto a cada uno de los mensajes de ayuda de los argumentos:

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     formatter_class=argparse.ArgumentDefaultsHelpFormatter)
>>> parser.add_argument('--foo', type=int, default=42, help='FOO!')
>>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')
>>> parser.print_help()
usage: PROG [-h] [--foo FOO] [bar ...]

positional arguments:
 bar         BAR! (default: [1, 2, 3])

optional arguments:
 -h, --help  show this help message and exit
 --foo FOO   FOO! (default: 42)

MetavarTypeHelpFormatter utiliza el nombre del parámetro type para cada argumento como el nombre a mostrar para sus valores (en lugar de utilizar dest como lo hace el formato habitual):

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     formatter_class=argparse.MetavarTypeHelpFormatter)
>>> parser.add_argument('--foo', type=int)
>>> parser.add_argument('bar', type=float)
>>> parser.print_help()
usage: PROG [-h] [--foo int] float

positional arguments:
  float

optional arguments:
  -h, --help  show this help message and exit
  --foo int

prefix_chars

La mayoría de las opciones de la línea de comandos usarán - como prefijo, por ejemplo -f/--foo. Los analizadores que necesiten soportar caracteres prefijo diferentes o adicionales, por ejemplo, para opciones como +f o /foo, pueden especificarlos usando el argumento prefix_chars= para el constructor ArgumentParser:

>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')
>>> parser.add_argument('+f')
>>> parser.add_argument('++bar')
>>> parser.parse_args('+f X ++bar Y'.split())
Namespace(bar='Y', f='X')

El argumento prefix_chars= tiene un valor por defecto de '-'. Proporcionar un conjunto de caracteres que no incluya - causará que las opciones -f/--foo no sean inhabilitadas.

fromfile_prefix_chars

Sometimes, for example when dealing with a particularly long argument list, it may make sense to keep the list of arguments in a file rather than typing it out at the command line. If the fromfile_prefix_chars= argument is given to the ArgumentParser constructor, then arguments that start with any of the specified characters will be treated as files, and will be replaced by the arguments they contain. For example:

>>> with open('args.txt', 'w') as fp:
...     fp.write('-f\nbar')
>>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
>>> parser.add_argument('-f')
>>> parser.parse_args(['-f', 'foo', '@args.txt'])
Namespace(f='bar')

Los argumentos leídos de un archivo deben ser por defecto uno por línea (pero vea también convert_arg_line_to_args()) y se tratan como si estuvieran en el mismo lugar que el argumento de referencia del archivo original en la línea de comandos. Así, en el ejemplo anterior, la expresión [‘-f’, ‘foo’, ‘@args.txt’] se considera equivalente a la expresión [‘-f’, ‘foo’, ‘-f’, ‘bar’].

El argumento fromfile_prefix_chars= por defecto es None, lo que significa que los argumentos nunca serán tratados como referencias de archivos.

argument_default

Generalmente, los valores por defecto de los argumentos se especifican ya sea pasando un valor por defecto a add_argument() o llamando a los métodos set_defaults() con un conjunto específico de pares nombre-valor. A veces, sin embargo, puede ser útil especificar un único valor por defecto para todos los argumentos del analizador. Esto se puede lograr pasando el argumento de palabra clave argument_default= a ArgumentParser. Por ejemplo, para suprimir globalmente la creación de atributos en las llamadas a parse_args() , proporcionamos el argumento argument_default=SUPPRESS:

>>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
>>> parser.add_argument('--foo')
>>> parser.add_argument('bar', nargs='?')
>>> parser.parse_args(['--foo', '1', 'BAR'])
Namespace(bar='BAR', foo='1')
>>> parser.parse_args([])
Namespace()

allow_abbrev

Normalmente, cuando pasas una lista de argumentos al método parse_args() de un ArgumentParser, reconoce las abreviaturas de las opciones largas.

Esta característica puede ser desactivada poniendo allow_abbrev a False:

>>> parser = argparse.ArgumentParser(prog='PROG', allow_abbrev=False)
>>> parser.add_argument('--foobar', action='store_true')
>>> parser.add_argument('--foonley', action='store_false')
>>> parser.parse_args(['--foon'])
usage: PROG [-h] [--foobar] [--foonley]
PROG: error: unrecognized arguments: --foon

Nuevo en la versión 3.5.

conflict_handler

Los objetos ArgumentParser no permiten dos acciones con la misma cadena de caracteres de opción. Por defecto, los objetos ArgumentParser lanzan una excepción si se intenta crear un argumento con una cadena de caracteres de opción que ya está en uso:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-f', '--foo', help='old foo help')
>>> parser.add_argument('--foo', help='new foo help')
Traceback (most recent call last):
 ..
ArgumentError: argument --foo: conflicting option string(s): --foo

A veces (por ejemplo, cuando se utiliza parents) puede ser útil anular simplemente cualquier argumento antiguo con la misma cadena de caracteres de opción. Para lograr este comportamiento, se puede suministrar el valor 'resolve' al argumento conflict_handler= de ArgumentParser:

>>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve')
>>> parser.add_argument('-f', '--foo', help='old foo help')
>>> parser.add_argument('--foo', help='new foo help')
>>> parser.print_help()
usage: PROG [-h] [-f FOO] [--foo FOO]

optional arguments:
 -h, --help  show this help message and exit
 -f FOO      old foo help
 --foo FOO   new foo help

Ten en cuenta que los objetos ArgumentParser sólo eliminan una acción si todas sus cadenas de caracteres de opción están anuladas. Así, en el ejemplo anterior, la antigua acción -f/--foo se mantiene como la acción``-f``, porque sólo la cadena de caracteres de opción --foo fue anulada.

add_help

Por defecto, los objetos ArgumentParser añaden una opción que simplemente muestra el mensaje de ayuda del analizador. Por ejemplo, considera un archivo llamado myprogram.py que contiene el siguiente código:

import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--foo', help='foo help')
args = parser.parse_args()

Si -h o --help se indica en la línea de comandos, se imprimirá la ayuda de ArgumentParser:

$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]

optional arguments:
 -h, --help  show this help message and exit
 --foo FOO   foo help

Ocasionalmente, puede ser útil desactivar la inclusión de esta opción de ayuda. Esto se puede lograr pasando False como argumento de add_help= a ArgumentParser:

>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> parser.add_argument('--foo', help='foo help')
>>> parser.print_help()
usage: PROG [--foo FOO]

optional arguments:
 --foo FOO  foo help

La opción de ayuda es típicamente -h/--help. La excepción a esto es si prefix_chars= se especifica y no incluye -, en cuyo caso -h y --help no son opciones válidas. En este caso, el primer carácter en prefix_chars se utiliza para preceder a las opciones de ayuda:

>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')
>>> parser.print_help()
usage: PROG [+h]

optional arguments:
  +h, ++help  show this help message and exit

exit_on_error

Normalmente, cuando pasa una lista de argumentos no válidos al método parse_args() de un ArgumentParser, saldrá con información de error.

If the user would like to catch errors manually, the feature can be enabled by setting exit_on_error to False:

>>> parser = argparse.ArgumentParser(exit_on_error=False)
>>> parser.add_argument('--integers', type=int)
_StoreAction(option_strings=['--integers'], dest='integers', nargs=None, const=None, default=None, type=<class 'int'>, choices=None, help=None, metavar=None)
>>> try:
...     parser.parse_args('--integers a'.split())
... except argparse.ArgumentError:
...     print('Catching an argumentError')
...
Catching an argumentError

Nuevo en la versión 3.9.

El método add_argument()

ArgumentParser.add_argument(name or flags...[, action][, nargs][, const][, default][, type][, choices][, required][, help][, metavar][, dest])

Define cómo se debe interpretar un determinado argumento de línea de comandos. Cada parámetro tiene su propia descripción más detallada a continuación, pero en resumen son:

name or flags - Ya sea un nombre o una lista de cadena de caracteres de opción, e.g. foo o -f, --foo.

action - El tipo básico de acción a tomar cuando este argumento se encuentra en la línea de comandos.

nargs - El número de argumentos de la línea de comandos que deben ser consumidos.

const - Un valor fijo requerido por algunas selecciones de action y nargs.

default - El valor producido si el argumento está ausente en la línea de comando y si está ausente en el objeto de espacio de nombres.

type - El tipo al que debe convertirse el argumento de la línea de comandos.

choices - Un contenedor con los valores permitidos para el argumento.

required - Si se puede omitir o no la opción de la línea de comandos (sólo opcionales).

help - Una breve descripción de lo que hace el argumento.

metavar - Un nombre para el argumento en los mensajes de uso.

dest - El nombre del atributo que será añadido al objeto retornado por parse_args().

En las siguientes secciones se describe cómo se utiliza cada una de ellas.

name or flags

El método add_argument() debe saber si se espera un argumento opcional, como -f o --foo, o un argumento posicional, como una lista de nombres de archivos. Por lo tanto, los primeros argumentos que se pasan a add_argument() deben ser una serie de indicadores (flags), o un simple nombre de argumento (name). Por ejemplo, se puede crear un argumento opcional como:

>>> parser.add_argument('-f', '--foo')

mientras que un argumento posicional podría ser creado como:

>>> parser.add_argument('bar')

Cuando se llama a parse_args() , los argumentos opcionales serán identificados por el prefijo -, y el resto de los argumentos serán asumidos como posicionales:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-f', '--foo')
>>> parser.add_argument('bar')
>>> parser.parse_args(['BAR'])
Namespace(bar='BAR', foo=None)
>>> parser.parse_args(['BAR', '--foo', 'FOO'])
Namespace(bar='BAR', foo='FOO')
>>> parser.parse_args(['--foo', 'FOO'])
usage: PROG [-h] [-f FOO] bar
PROG: error: the following arguments are required: bar

action

Los objetos ArgumentParser asocian los argumentos de la línea de comandos con las acciones. Esta acciones pueden hacer casi cualquier cosa con los argumentos de línea de comandos asociados a ellas, aunque la mayoría de las acciones simplemente añaden un atributo al objeto retornado por parse_args(). El argumento de palabra clave action especifica cómo deben ser manejados los argumentos de la línea de comandos. Las acciones proporcionadas son:

'store' - Esta sólo almacena el valor del argumento. Esta es la acción por defecto. Por ejemplo:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.parse_args('--foo 1'.split())
Namespace(foo='1')

'store_const' - Esta almacena el valor especificado por el argumento de palabra clave const . La acción 'store_const' se usa más comúnmente con argumentos opcionales que especifican algún tipo de indicador (flag). Por ejemplo:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_const', const=42)
>>> parser.parse_args(['--foo'])
Namespace(foo=42)

'store_true' y 'store_false' - Son casos especiales de 'store_const' usados para almacenar los valores True y False respectivamente. Además, crean valores por defecto de False y True respectivamente. Por ejemplo:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_true')
>>> parser.add_argument('--bar', action='store_false')
>>> parser.add_argument('--baz', action='store_false')
>>> parser.parse_args('--foo --bar'.split())
Namespace(foo=True, bar=False, baz=True)

'append' - Esta almacena una lista, y añade cada valor del argumento a la lista. Esto es útil para permitir que una opción sea especificada varias veces. Ejemplo de uso:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='append')
>>> parser.parse_args('--foo 1 --foo 2'.split())
Namespace(foo=['1', '2'])

'append_const' - Esta almacena una lista, y añade el valor especificado por el argumento de palabra clave const a la lista. (Nótese que el argumento de palabra clave const por defecto es None.) La acción 'append_const' es útil típicamente cuando múltiples argumentos necesitan almacenar constantes a la misma lista. Por ejemplo:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--str', dest='types', action='append_const', const=str)
>>> parser.add_argument('--int', dest='types', action='append_const', const=int)
>>> parser.parse_args('--str --int'.split())
Namespace(types=[<class 'str'>, <class 'int'>])

'count' - Esta cuenta el número de veces que un argumento de palabra clave aparece. Por ejemplo, esto es útil para incrementar los niveles de detalle:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--verbose', '-v', action='count', default=0)
>>> parser.parse_args(['-vvv'])
Namespace(verbose=3)

Observa, default (el valor por defecto) será None a menos que explícitamente se establezca como 0.

'help' - Esta imprime un mensaje de ayuda completo para todas las opciones del analizador actual y luego termina. Por defecto, se añade una acción de ayuda automáticamente al analizador. Ver ArgumentParser para detalles de cómo se genera la salida.

’version’ - Esta espera un argumento de palabra clave version= en la llamada add_argument(), e imprime la información de la versión y finaliza cuando es invocada:

>>> import argparse
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--version', action='version', version='%(prog)s 2.0')
>>> parser.parse_args(['--version'])
PROG 2.0

’extend’ - Esta almacena una lista, y extiende cada valor del argumento a la lista. Ejemplo de uso:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument("--foo", action="extend", nargs="+", type=str)
>>> parser.parse_args(["--foo", "f1", "--foo", "f2", "f3", "f4"])
Namespace(foo=['f1', 'f2', 'f3', 'f4'])

Nuevo en la versión 3.8.

También puede especificar una acción arbitraria pasando una subclase de Acción u otro objeto que implemente la misma interfaz. BooleanOptionalAction está disponible en argparse y agrega soporte para acciones booleanas como --foo y --no-foo:

>>> import argparse
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action=argparse.BooleanOptionalAction)
>>> parser.parse_args(['--no-foo'])
Namespace(foo=False)

Nuevo en la versión 3.9.

La forma recomendada de crear una acción personalizada es extender Action, anulando el método __call__ y, opcionalmente, los métodos __init__ y format_usage.

Un ejemplo de una acción personalizada:

>>> class FooAction(argparse.Action):
...     def __init__(self, option_strings, dest, nargs=None, **kwargs):
...         if nargs is not None:
...             raise ValueError("nargs not allowed")
...         super().__init__(option_strings, dest, **kwargs)
...     def __call__(self, parser, namespace, values, option_string=None):
...         print('%r %r %r' % (namespace, values, option_string))
...         setattr(namespace, self.dest, values)
...
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action=FooAction)
>>> parser.add_argument('bar', action=FooAction)
>>> args = parser.parse_args('1 --foo 2'.split())
Namespace(bar=None, foo=None) '1' None
Namespace(bar='1', foo=None) '2' '--foo'
>>> args
Namespace(bar='1', foo='2')

Para más detalles, ver Action.

nargs

Los objetos ArgumentParser suelen asociar un único argumento de línea de comandos con una única acción a realizar. El argumento de palabra clave nargs asocia un número diferente de argumentos de línea de comandos con una sola acción. Los valores admitidos son:

N (un entero). N argumentos de la línea de comandos se agruparán en una lista. Por ejemplo:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs=2)
>>> parser.add_argument('bar', nargs=1)
>>> parser.parse_args('c --foo a b'.split())
Namespace(bar=['c'], foo=['a', 'b'])

Ten en cuenta que nargs=1 produce una lista de un elemento. Esto es diferente del valor por defecto, en el que el elemento se produce por sí mismo.

’?’. Un argumento se consumirá desde la línea de comandos si es posible, y se generará como un sólo elemento. Si no hay ningún argumento de línea de comandos, se obtendrá el valor de default. Ten en cuenta que para los argumentos opcionales, hay un caso adicional - la cadena de caracteres de opción está presente pero no va seguida de un argumento de línea de comandos. En este caso se obtendrá el valor de const. Algunos ejemplos para ilustrar esto:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs='?', const='c', default='d')
>>> parser.add_argument('bar', nargs='?', default='d')
>>> parser.parse_args(['XX', '--foo', 'YY'])
Namespace(bar='XX', foo='YY')
>>> parser.parse_args(['XX', '--foo'])
Namespace(bar='XX', foo='c')
>>> parser.parse_args([])
Namespace(bar='d', foo='d')

Uno de los usos más comunes de nargs='?' es permitir archivos de entrada y salida opcionales:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'),
...                     default=sys.stdin)
>>> parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'),
...                     default=sys.stdout)
>>> parser.parse_args(['input.txt', 'output.txt'])
Namespace(infile=<_io.TextIOWrapper name='input.txt' encoding='UTF-8'>,
          outfile=<_io.TextIOWrapper name='output.txt' encoding='UTF-8'>)
>>> parser.parse_args([])
Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>,
          outfile=<_io.TextIOWrapper name='<stdout>' encoding='UTF-8'>)

’*’. Todos los argumentos presentes en la línea de comandos se recogen en una lista. Ten en cuenta que generalmente no tiene mucho sentido tener más de un argumento posicional con nargs=‘*’, pero es posible tener múltiples argumentos opcionales con nargs=‘*’. Por ejemplo:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs='*')
>>> parser.add_argument('--bar', nargs='*')
>>> parser.add_argument('baz', nargs='*')
>>> parser.parse_args('a b --foo x y --bar 1 2'.split())
Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])

'+'. Al igual que '*', todos los argumentos de la línea de comandos se recogen en una lista. Además, se generará un mensaje de error si no había al menos un argumento presente en la línea de comandos. Por ejemplo:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', nargs='+')
>>> parser.parse_args(['a', 'b'])
Namespace(foo=['a', 'b'])
>>> parser.parse_args([])
usage: PROG [-h] foo [foo ...]
PROG: error: the following arguments are required: foo

Si no se proporciona el argumento de palabra clave nargs, el número de argumentos consumidos se determina por action. Generalmente esto significa que se consumirá un único argumento de línea de comandos y se obtendrá un único elemento (no una lista).

const

El argumento const de add_argument() se usa para mantener valores constantes que no se leen desde la línea de comandos pero que son necesarios para las diversas acciones de ArgumentParser. Los dos usos más comunes son:

Cuando add_argument() se llama con action='store_const' o action='append_const'. Estas acciones añaden el valor const a uno de los atributos del objeto retornado por parse_args(). Mira la descripción action para ver ejemplos.

Cuando add_argument() se llama con cadenas de caracteres de opción (como -f o —foo) y nargs=‘?’. Esto crea un argumento opcional que puede ir seguido de cero o un argumento de línea de comandos. Al analizar la línea de comandos, si la cadena de opciones se encuentra sin ningún argumento de línea de comandos que la siga, asumirá en su lugar el valor de const. Mira la descripción nargs para ejemplos.

Con las acciones 'store_const' y 'append_const', se debe asignar el argumento palabra clave const. Para otras acciones, por defecto es None.

default

Todos los argumentos opcionales y algunos argumentos posicionales pueden ser omitidos en la línea de comandos. El argumento de palabra clave default de add_argument(), cuyo valor por defecto es None, especifica qué valor debe usarse si el argumento de línea de comandos no está presente. Para los argumentos opcionales, se usa el valor default cuando la cadena de caracteres de opción no está presente en la línea de comandos:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=42)
>>> parser.parse_args(['--foo', '2'])
Namespace(foo='2')
>>> parser.parse_args([])
Namespace(foo=42)

Si el espacio de nombres de destino ya tiene un atributo establecido, la acción default no lo sobrescribirá:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=42)
>>> parser.parse_args([], namespace=argparse.Namespace(foo=101))
Namespace(foo=101)

Si el valor default es una cadena de caracteres, el analizador procesa el valor como si fuera un argumento de la línea de comandos. En particular, el analizador aplica cualquier argumento de conversión type , si se proporciona, antes de establecer el atributo en el valor de retorno Namespace. En caso contrario, el analizador utiliza el valor tal y como es:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--length', default='10', type=int)
>>> parser.add_argument('--width', default=10.5, type=int)
>>> parser.parse_args()
Namespace(length=10, width=10.5)

Para argumentos posiciones con nargs igual a ? o *, el valor default se utiliza cuando no hay ningún argumento de línea de comandos presente:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', nargs='?', default=42)
>>> parser.parse_args(['a'])
Namespace(foo='a')
>>> parser.parse_args([])
Namespace(foo=42)

Proporcionar default=argparse.SUPPRESS causa que no se agregue ningún atributo si el argumento de la línea de comandos no está presente:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=argparse.SUPPRESS)
>>> parser.parse_args([])
Namespace()
>>> parser.parse_args(['--foo', '1'])
Namespace(foo='1')

type

De forma predeterminada, el analizador lee los argumentos de la línea de comandos como cadenas simples. Sin embargo, a menudo, la cadena de la línea de comandos debe interpretarse como otro tipo, como float o int. La palabra clave type para add_argument() permite realizar cualquier verificación de tipo y conversión de tipo necesaria.

Si la palabra clave type se usa con la palabra clave default, el convertidor de tipos solo se aplica si el valor predeterminado es una cadena de caracteres.

El argumento para type puede ser cualquier invocable que acepte una sola cadena de caracteres. Si la función lanza ArgumentTypeError, TypeError, o ValueError, se detecta la excepción y se muestra un mensaje de error con un formato agradable. No se manejan otros tipos de excepciones.

Los tipos y funciones incorporados comunes se pueden utilizar como convertidores de tipos:

import argparse
import pathlib

parser = argparse.ArgumentParser()
parser.add_argument('count', type=int)
parser.add_argument('distance', type=float)
parser.add_argument('street', type=ascii)
parser.add_argument('code_point', type=ord)
parser.add_argument('source_file', type=open)
parser.add_argument('dest_file', type=argparse.FileType('w', encoding='latin-1'))
parser.add_argument('datapath', type=pathlib.Path)

Las funciones definidas por el usuario también se pueden utilizar:

>>> def hyphenated(string):
...     return '-'.join([word[:4] for word in string.casefold().split()])
...
>>> parser = argparse.ArgumentParser()
>>> _ = parser.add_argument('short_title', type=hyphenated)
>>> parser.parse_args(['"The Tale of Two Cities"'])
Namespace(short_title='"the-tale-of-two-citi')

La función bool() no se recomienda como convertidor de tipos. Todo lo que hace es convertir cadenas de caracteres vacías en False y cadenas de caracteres no vacías en True. Por lo general, esto no es lo que se desea.

En general, la palabra clave type es una conveniencia que solo debe usarse para conversiones simples que solo pueden generar una de las tres excepciones admitidas. Cualquier cosa con un manejo de errores o de recursos más interesante debe hacerse en sentido descendente después de analizar los argumentos.

For example, JSON or YAML conversions have complex error cases that require better reporting than can be given by the type keyword. A JSONDecodeError would not be well formatted and a FileNotFound exception would not be handled at all.

Even FileType tiene sus limitaciones para su uso con la palabra clave type. Si un argumento usa FileType y luego falla un argumento posterior, se informa un error pero el archivo no se cierra automáticamente. En este caso, sería mejor esperar hasta que se haya ejecutado el analizador y luego usar la declaración with para administrar los archivos.

Para los verificadores de tipo que simplemente verifican un conjunto fijo de valores, considere usar la palabra clave choice en su lugar.

choices

Algunos argumentos de la línea de comandos deberían seleccionarse de un conjunto restringido de valores. Estos pueden ser manejados pasando un objeto contenedor como el argumento de palabra clave choices a add_argument(). Cuando se analiza la línea de comandos, se comprueban los valores de los argumentos y se muestra un mensaje de error si el argumento no era uno de los valores aceptables:

>>> parser = argparse.ArgumentParser(prog='game.py')
>>> parser.add_argument('move', choices=['rock', 'paper', 'scissors'])
>>> parser.parse_args(['rock'])
Namespace(move='rock')
>>> parser.parse_args(['fire'])
usage: game.py [-h] {rock,paper,scissors}
game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',
'paper', 'scissors')

Ten en cuenta que la inclusión en el contenedor choices se comprueba después de que se haya realizado cualquier conversión de type, por lo que el tipo de los objetos del contenedor choices debe coincidir con el type especificado:

>>> parser = argparse.ArgumentParser(prog='doors.py')
>>> parser.add_argument('door', type=int, choices=range(1, 4))
>>> print(parser.parse_args(['3']))
Namespace(door=3)
>>> parser.parse_args(['4'])
usage: doors.py [-h] {1,2,3}
doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3)

Se puede pasar cualquier contenedor como el valor para choices, así que los objetos list, set , y los contenedores personalizados están todos soportados.

No se recomienda el uso de enum.Enum porque es difícil controlar su apariencia en el uso, la ayuda y los mensajes de error.

Las opciones formateadas anulan el metavar predeterminado que normalmente se deriva de dest. Esto suele ser lo que desea porque el usuario nunca ve el parámetro dest. Si esta visualización no es deseable (quizás porque hay muchas opciones), simplemente especifique un metavar explícito.

required

En general, el módulo argparse asume que los indicadores (flags) como -f y --bar señalan argumentos opcionales, que siempre pueden ser omitidos en la línea de comandos. Para hacer una opción requerida, se puede especificar``True`` para el argumento de palabra clave``required=`` en add_argument():

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', required=True)
>>> parser.parse_args(['--foo', 'BAR'])
Namespace(foo='BAR')
>>> parser.parse_args([])
usage: [-h] --foo FOO
: error: the following arguments are required: --foo

Como muestra el ejemplo, si una opción está marcada como required, parse_args() informará de un error si esa opción no está presente en la línea de comandos.

Nota

Las opciones requeridas están consideradas generalmente mala práctica porque los usuarios esperan que las opciones sean opcionales, y por lo tanto deberían ser evitadas cuando sea posible.

help

El valor help es una cadena de caracteres que contiene una breve descripción del argumento. Cuando un usuario solicita ayuda (normalmente usando -h o --help en la línea de comandos), estas descripciones help se mostrarán con cada argumento:

>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('--foo', action='store_true',
...                     help='foo the bars before frobbling')
>>> parser.add_argument('bar', nargs='+',
...                     help='one of the bars to be frobbled')
>>> parser.parse_args(['-h'])
usage: frobble [-h] [--foo] bar [bar ...]

positional arguments:
 bar     one of the bars to be frobbled

optional arguments:
 -h, --help  show this help message and exit
 --foo   foo the bars before frobbling

Las cadenas de texto help pueden incluir varios descriptores de formato para evitar la repetición de cosas como el nombre del programa o el argumento default. Los descriptores disponibles incluyen el nombre del programa, %(prog)s y la mayoría de los argumentos de palabra clave de add_argument(), por ejemplo %(default)s, %(type)s, etc.:

>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('bar', nargs='?', type=int, default=42,
...                     help='the bar to %(prog)s (default: %(default)s)')
>>> parser.print_help()
usage: frobble [-h] [bar]

positional arguments:
 bar     the bar to frobble (default: 42)

optional arguments:
 -h, --help  show this help message and exit

Como la cadena de caracteres de ayuda soporta el formato-%, si quieres que aparezca un % literal en la ayuda, debes escribirlo como %%.

argparse soporta el silenciar la ayuda para ciertas opciones, ajustando el valor help a argparse.SUPPRESS:

>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('--foo', help=argparse.SUPPRESS)
>>> parser.print_help()
usage: frobble [-h]

optional arguments:
  -h, --help  show this help message and exit

metavar

Cuando ArgumentParser genera mensajes de ayuda, necesita alguna forma de referirse a cada argumento esperado. Por defecto, los objetos ArgumentParser utilizan el valor dest como «nombre» de cada objeto. Por defecto, para las acciones de argumento posicional, el valor dest se utiliza directamente, y para las acciones de argumento opcional, el valor dest está en mayúsculas. Así, un único argumento posicional con dest='bar' se denominará bar. Un único argumento opcional --foo que debería seguirse por un único argumento de línea de comandos se denominará FOO. Un ejemplo:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.add_argument('bar')
>>> parser.parse_args('X --foo Y'.split())
Namespace(bar='X', foo='Y')
>>> parser.print_help()
usage:  [-h] [--foo FOO] bar

positional arguments:
 bar

optional arguments:
 -h, --help  show this help message and exit
 --foo FOO

Un nombre alternativo se puede especificar con metavar:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', metavar='YYY')
>>> parser.add_argument('bar', metavar='XXX')
>>> parser.parse_args('X --foo Y'.split())
Namespace(bar='X', foo='Y')
>>> parser.print_help()
usage:  [-h] [--foo YYY] XXX

positional arguments:
 XXX

optional arguments:
 -h, --help  show this help message and exit
 --foo YYY

Ten en cuenta que metavar sólo cambia el nombre mostrado - el nombre del atributo en el objeto parse_args() sigue estando determinado por el valor dest.

Diferentes valores de nargs pueden causar que metavar sea usado múltiples veces. Proporcionar una tupla a metavar especifica una visualización diferente para cada uno de los argumentos:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x', nargs=2)
>>> parser.add_argument('--foo', nargs=2, metavar=('bar', 'baz'))
>>> parser.print_help()
usage: PROG [-h] [-x X X] [--foo bar baz]

optional arguments:
 -h, --help     show this help message and exit
 -x X X
 --foo bar baz

dest

La mayoría de las acciones ArgumentParser añaden algún valor como atributo del objeto retornado por parse_args(). El nombre de este atributo está determinado por el argumento de palabra clave dest de add_argument(). Para acciones de argumento posicional, se proporciona dest normalmente como primer argumento de add_argument():

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bar')
>>> parser.parse_args(['XXX'])
Namespace(bar='XXX')

Para las acciones de argumentos opcionales, el valor de dest se infiere normalmente de las cadenas de caracteres de opción. ArgumentParser genera el valor de dest tomando la primera cadena de caracteres de opción larga y quitando la cadena inicial --. Si no se proporcionaron cadenas de caracteres de opción largas, dest se derivará de la primera cadena de caracteres de opción corta quitando el carácter -. Cualquier carácter - interno se convertirá a caracteres _ para asegurarse de que la cadena de caracteres es un nombre de atributo válido. Los ejemplos siguientes ilustran este comportamiento:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('-f', '--foo-bar', '--foo')
>>> parser.add_argument('-x', '-y')
>>> parser.parse_args('-f 1 -x 2'.split())
Namespace(foo_bar='1', x='2')
>>> parser.parse_args('--foo 1 -y 2'.split())
Namespace(foo_bar='1', x='2')

dest permite que se proporcione un nombre de atributo personalizado:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', dest='bar')
>>> parser.parse_args('--foo XXX'.split())
Namespace(bar='XXX')

Las clases Action

Las clases Action implementan la API de Action, un invocable que retorna un invocable que procesa los argumentos de la línea de comandos. Cualquier objeto que siga esta API puede ser pasado como el parámetro action a add_argument().

class argparse.Action(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

Los objetos Action son utilizados por un ArgumentParser para representar la información necesaria para analizar un sólo argumento de una o más cadenas de caracteres de la línea de comandos. La clase Action debe aceptar los dos argumentos de posición más cualquier argumento de palabra clave pasado a ArgumentParser.add_argument() excepto para la propia action.

Las instancias de Action (o el valor de retorno de cualquier invocable al parámetro action ) deben tener definidos los atributos ”dest”, ”option_strings”, ”default”, ”type”, ”required”, ”help”, etc. La forma más fácil de asegurar que estos atributos estén definidos es llamar a Action.__init__.

Las instancias de Action deben ser invocables, por lo que las subclases deben anular el método __call__, que debería aceptar cuatro parámetros:

parser - El objeto ArgumentParser que contiene esta acción.

namespace - El objeto Namespace que será retornado por parse_args(). La mayoría de las acciones añaden un atributo a este objeto usando setattr().

values - Los argumentos de la línea de comandos asociados, con cualquier tipo de conversión aplicada. Las conversiones de tipos se especifican con el argumento de palabra clave type a add_argument().

option_string - La cadena de caracteres de opción que se usó para invocar esta acción. El argumento option_string es opcional, y estará ausente si la acción está asociada a un argumento de posición.

El método __call__ puede realizar acciones arbitrarias, pero típicamente estable atributos en namespace basados en dest y values.

Las subclases de acción pueden definir un método format_usage que no toma ningún argumento y devuelve una cadena que se utilizará al imprimir el uso del programa. Si no se proporciona dicho método, se utilizará un valor predeterminado razonable.

El método parse_args()

ArgumentParser.parse_args(args=None, namespace=None)

Convierte las cadenas de caracteres de argumentos en objetos y los asigna como atributos del espacio de nombres (namespace). Retorna el espacio de nombres (namespace) ocupado.

Las llamadas previas a add_argument() determinan exactamente qué objetos se crean y cómo se asignan. Mira la documentación de add_argument() para más detalles.

args - Lista de cadenas de caracteres para analizar. El valor por defecto se toma de sys.argv.

namespace - Un objeto para obtener los atributos. Por defecto es un nuevo objeto vacío Namespace.

Sintaxis del valor de la opción

El método parse_args() soporta diversas formas de especificar el valor de una opción (si requiere uno). En el caso más simple, la opción y su valor se pasan como dos argumentos separados:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x')
>>> parser.add_argument('--foo')
>>> parser.parse_args(['-x', 'X'])
Namespace(foo=None, x='X')
>>> parser.parse_args(['--foo', 'FOO'])
Namespace(foo='FOO', x=None)

En el caso de opciones largas (opciones con nombres más largos que un sólo carácter), la opción y el valor también se pueden pasar como un sólo argumento de línea de comandos, utilizando = para separarlos:

>>> parser.parse_args(['--foo=FOO'])
Namespace(foo='FOO', x=None)

Para las opciones cortas (opciones de un sólo carácter de largo), la opción y su valor pueden ser concatenados:

>>> parser.parse_args(['-xX'])
Namespace(foo=None, x='X')

Se pueden unir varias opciones cortas, usando un sólo prefijo -, siempre y cuando sólo la última opción (o ninguna de ellas) requiera un valor:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x', action='store_true')
>>> parser.add_argument('-y', action='store_true')
>>> parser.add_argument('-z')
>>> parser.parse_args(['-xyzZ'])
Namespace(x=True, y=True, z='Z')

Argumentos no válidos

Mientras analiza la línea de comandos, parse_args() comprueba una variedad de errores, incluyendo opciones ambiguas, tipos no válidos, opciones no válidas, número incorrecto de argumentos de posición, etc. Cuando encuentra un error de este tipo, termina y muestra el error junto con un mensaje de uso:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', type=int)
>>> parser.add_argument('bar', nargs='?')

>>> # invalid type
>>> parser.parse_args(['--foo', 'spam'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: argument --foo: invalid int value: 'spam'

>>> # invalid option
>>> parser.parse_args(['--bar'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: no such option: --bar

>>> # wrong number of arguments
>>> parser.parse_args(['spam', 'badger'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: extra arguments found: badger

Argumentos conteniendo -

El método parse_args() busca generar errores cuando el usuario ha cometido claramente una equivocación, pero algunas situaciones son inherentemente ambiguas. Por ejemplo, el argumento de línea de comandos -1 podría ser un intento de especificar una opción o un intento de proporcionar un argumento de posición. El método parse_args() es cauteloso aquí: los argumentos de posición sólo pueden comenzar con - si se ven como números negativos y no hay opciones en el analizador que se puedan ver como números negativos

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x')
>>> parser.add_argument('foo', nargs='?')

>>> # no negative number options, so -1 is a positional argument
>>> parser.parse_args(['-x', '-1'])
Namespace(foo=None, x='-1')

>>> # no negative number options, so -1 and -5 are positional arguments
>>> parser.parse_args(['-x', '-1', '-5'])
Namespace(foo='-5', x='-1')

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-1', dest='one')
>>> parser.add_argument('foo', nargs='?')

>>> # negative number options present, so -1 is an option
>>> parser.parse_args(['-1', 'X'])
Namespace(foo=None, one='X')

>>> # negative number options present, so -2 is an option
>>> parser.parse_args(['-2'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: no such option: -2

>>> # negative number options present, so both -1s are options
>>> parser.parse_args(['-1', '-1'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: argument -1: expected one argument

Si tienes argumentos de posición que deben comenzar con - y no parecen números negativos, puedes insertar el pseudo-argumento '--' que indica a parse_args() que todo lo que sigue es un argumento de posición:

>>> parser.parse_args(['--', '-f'])
Namespace(foo='-f', one=None)

Abreviaturas de los argumentos (coincidencia de prefijos)

El método parse_args() por defecto permite abreviar las opciones largas a un prefijo, si la abreviatura es inequívoca (el prefijo coincide con una opción única):

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-bacon')
>>> parser.add_argument('-badger')
>>> parser.parse_args('-bac MMM'.split())
Namespace(bacon='MMM', badger=None)
>>> parser.parse_args('-bad WOOD'.split())
Namespace(bacon=None, badger='WOOD')
>>> parser.parse_args('-ba BA'.split())
usage: PROG [-h] [-bacon BACON] [-badger BADGER]
PROG: error: ambiguous option: -ba could match -badger, -bacon

Se incurre en un error por argumentos que podrían derivar en más de una opción. Esta característica puede ser desactivada poniendo allow_abbrev a False.

Más allá de sys.argv

A veces puede ser útil tener un ArgumentParser analizando argumentos que no sean los de sys.argv. Esto se puede lograr pasando una lista de cadenas de caracteres a parse_args(). Esto es útil para probar en el prompt interactivo:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument(
...     'integers', metavar='int', type=int, choices=range(10),
...     nargs='+', help='an integer in the range 0..9')
>>> parser.add_argument(
...     '--sum', dest='accumulate', action='store_const', const=sum,
...     default=max, help='sum the integers (default: find the max)')
>>> parser.parse_args(['1', '2', '3', '4'])
Namespace(accumulate=<built-in function max>, integers=[1, 2, 3, 4])
>>> parser.parse_args(['1', '2', '3', '4', '--sum'])
Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])

El objeto Namespace

class argparse.Namespace

Clase simple utilizada por defecto por parse_args() para crear un objeto que contenga atributos y retornarlo.

Esta clase es deliberadamente simple, sólo una subclase object con una representación de cadena de texto legible. Si prefieres tener una vista en forma de diccionario de los atributos, puedes usar el lenguaje estándar de Python, vars():

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> args = parser.parse_args(['--foo', 'BAR'])
>>> vars(args)
{'foo': 'BAR'}

También puede ser útil tener un ArgumentParser que asigne atributos a un objeto ya existente, en lugar de un nuevo objeto Namespace. Esto se puede lograr especificando el argumento de palabra clave namespace=:

>>> class C:
...     pass
...
>>> c = C()
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)
>>> c.foo
'BAR'

Otras utilidades

Sub-comandos

ArgumentParser.add_subparsers([title][, description][, prog][, parser_class][, action][, option_string][, dest][, required][, help][, metavar])

Muchos programas dividen su funcionalidad en varios sub-comandos, por ejemplo, el programa svn puede llamar sub-comandos como svn checkout, svn update, y svn commit. Dividir la funcionalidad de esta forma puede ser una idea particularmente buena cuando un programa realiza varias funciones diferentes que requieren diferentes tipos de argumentos en la línea de comandos. ArgumentParser soporta la creación de tales sub-comandos con el método add_subparsers(). El método add_subparsers() se llama normalmente sin argumentos y retorna un objeto de acción especial. Este objeto tiene un único método, add_parser(), que toma un nombre de comando y cualquier argumento de construcción ArgumentParser, y retorna un objeto ArgumentParser que puede ser modificado de la forma habitual.

Descripción de los parámetros:

title - título para el grupo del analizador secundario en la salida de la ayuda; por defecto «subcommands» si se proporciona la descripción, de lo contrario utiliza el título para los argumentos de posición

description - descripción para el grupo del analizador secundario en la salida de la ayuda, por defecto None

prog - información de uso que se mostrará con la ayuda de los sub-comandos, por defecto el nombre del programa y cualquier argumento de posición antes del argumento del analizador secundario

parser_class - clase que se usará para crear instancias de análisis secundario, por defecto la clase del analizador actual (por ejemplo, ArgumentParser)

action - el tipo básico de acción a tomar cuando este argumento se encuentre en la línea de comandos

dest - nombre del atributo en el que se almacenará el nombre del sub-comando; por defecto None y no se almacena ningún valor

required - Si se debe proporcionar o no un sub-comando, por defecto False (añadido en 3.7)

help - ayuda para el grupo de análisis secundario en la salida de la ayuda, por defecto None

metavar - cadena de caracteres que presenta los sub-comandos disponibles en la ayuda; por defecto es None y presenta los sub-comandos de la forma {cmd1, cmd2, ..}

Algún ejemplo de uso:

>>> # create the top-level parser
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', action='store_true', help='foo help')
>>> subparsers = parser.add_subparsers(help='sub-command help')
>>>
>>> # create the parser for the "a" command
>>> parser_a = subparsers.add_parser('a', help='a help')
>>> parser_a.add_argument('bar', type=int, help='bar help')
>>>
>>> # create the parser for the "b" command
>>> parser_b = subparsers.add_parser('b', help='b help')
>>> parser_b.add_argument('--baz', choices='XYZ', help='baz help')
>>>
>>> # parse some argument lists
>>> parser.parse_args(['a', '12'])
Namespace(bar=12, foo=False)
>>> parser.parse_args(['--foo', 'b', '--baz', 'Z'])
Namespace(baz='Z', foo=True)

Ten en cuenta que el objeto retornado por parse_args() sólo contendrá atributos para el analizador principal y el analizador secundario que fue seleccionado por la línea de comandos (y no cualquier otro analizador secundario). Así que en el ejemplo anterior, cuando se especifica el comando a, sólo están presentes los atributos foo y bar, y cuando se especifica el comando``b``, sólo están presentes los atributos foo y baz.

Del mismo modo, cuando se solicita un mensaje de ayuda de un analizador secundario, sólo se imprimirá la ayuda para ese analizador en particular. El mensaje de ayuda no incluirá mensajes del analizador principal o de analizadores relacionados. (Sin embargo, se puede dar un mensaje de ayuda para cada comando del analizador secundario suministrando el argumento help= a add_parser() como se ha indicado anteriormente).

>>> parser.parse_args(['--help'])
usage: PROG [-h] [--foo] {a,b} ...

positional arguments:
  {a,b}   sub-command help
    a     a help
    b     b help

optional arguments:
  -h, --help  show this help message and exit
  --foo   foo help

>>> parser.parse_args(['a', '--help'])
usage: PROG a [-h] bar

positional arguments:
  bar     bar help

optional arguments:
  -h, --help  show this help message and exit

>>> parser.parse_args(['b', '--help'])
usage: PROG b [-h] [--baz {X,Y,Z}]

optional arguments:
  -h, --help     show this help message and exit
  --baz {X,Y,Z}  baz help

El método add_subparsers() también soporta los argumentos de palabra clave``title`` y description. Cuando cualquiera de los dos esté presente, los comandos del analizador secundario aparecerán en su propio grupo en la salida de la ayuda. Por ejemplo:

>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(title='subcommands',
...                                    description='valid subcommands',
...                                    help='additional help')
>>> subparsers.add_parser('foo')
>>> subparsers.add_parser('bar')
>>> parser.parse_args(['-h'])
usage:  [-h] {foo,bar} ...

optional arguments:
  -h, --help  show this help message and exit

subcommands:
  valid subcommands

  {foo,bar}   additional help

Además, add_parser soporta un argumento adicional aliases, que permite que múltiples cadenas se refieran al mismo analizador secundario. Este ejemplo, algo del estilo svn, alias co como abreviatura para checkout:

>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers()
>>> checkout = subparsers.add_parser('checkout', aliases=['co'])
>>> checkout.add_argument('foo')
>>> parser.parse_args(['co', 'bar'])
Namespace(foo='bar')

Una forma particularmente efectiva de manejar los sub-comandos es combinar el uso del método add_subparsers() con llamadas a set_defaults() para que cada analizador secundario sepa qué función de Python debe ejecutar. Por ejemplo:

>>> # sub-command functions
>>> def foo(args):
...     print(args.x * args.y)
...
>>> def bar(args):
...     print('((%s))' % args.z)
...
>>> # create the top-level parser
>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers()
>>>
>>> # create the parser for the "foo" command
>>> parser_foo = subparsers.add_parser('foo')
>>> parser_foo.add_argument('-x', type=int, default=1)
>>> parser_foo.add_argument('y', type=float)
>>> parser_foo.set_defaults(func=foo)
>>>
>>> # create the parser for the "bar" command
>>> parser_bar = subparsers.add_parser('bar')
>>> parser_bar.add_argument('z')
>>> parser_bar.set_defaults(func=bar)
>>>
>>> # parse the args and call whatever function was selected
>>> args = parser.parse_args('foo 1 -x 2'.split())
>>> args.func(args)
2.0
>>>
>>> # parse the args and call whatever function was selected
>>> args = parser.parse_args('bar XYZYX'.split())
>>> args.func(args)
((XYZYX))

De esta manera, puedes dejar que parse_args() haga el trabajo de llamar a la función apropiada después de que el análisis de los argumentos se haya completado. Asociar funciones con acciones como esta es típicamente la forma más fácil de manejar las diferentes acciones para cada uno de tus analizadores secundarios. Sin embargo, si es necesario comprobar el nombre del analizador secundario que se ha invocado, el argumento de palabra clave dest a la llamada add_subparsers() hará el trabajo:

>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(dest='subparser_name')
>>> subparser1 = subparsers.add_parser('1')
>>> subparser1.add_argument('-x')
>>> subparser2 = subparsers.add_parser('2')
>>> subparser2.add_argument('y')
>>> parser.parse_args(['2', 'frobble'])
Namespace(subparser_name='2', y='frobble')

Distinto en la versión 3.7: Nuevo argumento de palabra clave required.

Objetos FileType

class argparse.FileType(mode='r', bufsize=-1, encoding=None, errors=None)

El generador FileType crea objetos que pueden ser transferidos al argumento tipo de ArgumentParser.add_argument(). Los argumentos que tienen objetos FileType como su tipo abrirán los argumentos de líneas de comandos como archivos con los modos, tamaños de búfer, codificaciones y manejo de errores solicitados (véase la función open() para más detalles):

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--raw', type=argparse.FileType('wb', 0))
>>> parser.add_argument('out', type=argparse.FileType('w', encoding='UTF-8'))
>>> parser.parse_args(['--raw', 'raw.dat', 'file.txt'])
Namespace(out=<_io.TextIOWrapper name='file.txt' mode='w' encoding='UTF-8'>, raw=<_io.FileIO name='raw.dat' mode='wb'>)

Los objetos FileType entienden el pseudo-argumento '-' y lo convierten automáticamente en sys.stdin para objetos de lectura FileType y sys.stdout para objetos de escritura FileType:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('infile', type=argparse.FileType('r'))
>>> parser.parse_args(['-'])
Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>)

Nuevo en la versión 3.4: Los argumentos de palabra clave encodings y errors.

Grupos de argumentos

ArgumentParser.add_argument_group(title=None, description=None)

Por defecto, ArgumentParser agrupa los argumentos de la línea de comandos en «argumentos de posición» y «argumentos opcionales» al mostrar los mensajes de ayuda. Cuando hay una mejor agrupación conceptual de argumentos que esta predeterminada, se pueden crear grupos apropiados usando el método add_argument_group():

>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> group = parser.add_argument_group('group')
>>> group.add_argument('--foo', help='foo help')
>>> group.add_argument('bar', help='bar help')
>>> parser.print_help()
usage: PROG [--foo FOO] bar

group:
  bar    bar help
  --foo FOO  foo help

El método add_argument_group() retorna un objeto de grupo de argumentos que tiene un método add_argument() igual que un ArgumentParser convencional. Cuando se añade un argumento al grupo, el analizador lo trata como un argumento cualquiera, pero presenta el argumento en un grupo aparte para los mensajes de ayuda. El método add_argument_group() acepta los argumentos title y description que pueden ser usados para personalizar esta presentación:

>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> group1 = parser.add_argument_group('group1', 'group1 description')
>>> group1.add_argument('foo', help='foo help')
>>> group2 = parser.add_argument_group('group2', 'group2 description')
>>> group2.add_argument('--bar', help='bar help')
>>> parser.print_help()
usage: PROG [--bar BAR] foo

group1:
  group1 description

  foo    foo help

group2:
  group2 description

  --bar BAR  bar help

Ten en cuenta que cualquier argumento que no esté en los grupos definidos por el usuario terminará en las secciones habituales de «argumentos de posición» y «argumentos opcionales».

Exclusión mutua

ArgumentParser.add_mutually_exclusive_group(required=False)

Crear un grupo de exclusividad mutua. argparse se asegurará de que sólo uno de los argumentos del grupo de exclusividad mutua esté presente en la línea de comandos:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> group = parser.add_mutually_exclusive_group()
>>> group.add_argument('--foo', action='store_true')
>>> group.add_argument('--bar', action='store_false')
>>> parser.parse_args(['--foo'])
Namespace(bar=True, foo=True)
>>> parser.parse_args(['--bar'])
Namespace(bar=False, foo=False)
>>> parser.parse_args(['--foo', '--bar'])
usage: PROG [-h] [--foo | --bar]
PROG: error: argument --bar: not allowed with argument --foo

El método add_mutually_exclusive_group() también acepta un argumento required, para indicar que se requiere al menos uno de los argumentos mutuamente exclusivos:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> group = parser.add_mutually_exclusive_group(required=True)
>>> group.add_argument('--foo', action='store_true')
>>> group.add_argument('--bar', action='store_false')
>>> parser.parse_args([])
usage: PROG [-h] (--foo | --bar)
PROG: error: one of the arguments --foo --bar is required

Ten en cuenta que actualmente los grupos de argumentos mutuamente exclusivos no admiten los argumentos title y description de add_argument_group().

Valores por defecto del analizador

ArgumentParser.set_defaults(**kwargs)

La mayoría de las veces, los atributos del objeto retornado por parse_args() se determinarán completamente inspeccionando los argumentos de la línea de comandos y las acciones de los argumentos. set_defaults() permite que se añadan algunos atributos adicionales que se determinan sin ninguna inspección de la línea de comandos:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', type=int)
>>> parser.set_defaults(bar=42, baz='badger')
>>> parser.parse_args(['736'])
Namespace(bar=42, baz='badger', foo=736)

Ten en cuenta que los valores por defecto a nivel analizador siempre prevalecen sobre los valores por defecto a nivel argumento:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default='bar')
>>> parser.set_defaults(foo='spam')
>>> parser.parse_args([])
Namespace(foo='spam')

Los valores por defecto a nivel analizador pueden ser muy útiles cuando se trabaja con varios analizadores. Consulta el método add_subparsers() para ver un ejemplo de este tipo.

ArgumentParser.get_default(dest)

Obtiene el valor por defecto para un atributo del espacio de nombres (namespace), establecido ya sea por add_argument() o por set_defaults():

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default='badger')
>>> parser.get_default('foo')
'badger'

Mostrando la ayuda

En la mayoría de las aplicaciones típicas, parse_args() se encargará de dar formato y mostrar cualquier mensaje de uso o de error. Sin embargo, hay varios métodos para dar formato disponibles:

ArgumentParser.print_usage(file=None)

Muestra una breve descripción de cómo se debe invocar el ArgumentParser en la línea de comandos. Si file es None, se asume sys.stdout.

ArgumentParser.print_help(file=None)

Muestra un mensaje de ayuda, incluyendo el uso del programa e información sobre los argumentos registrados en el ArgumentParser. Si file es None, se asume sys.stdout.

También hay variantes de estos métodos que simplemente retornan una cadena de caracteres en lugar de mostrarla:

ArgumentParser.format_usage()

Retorna una cadena de caracteres que contiene una breve descripción de cómo se debe invocar el ArgumentParser en la línea de comandos.

ArgumentParser.format_help()

Retorna una cadena de caracteres que contiene un mensaje de ayuda, incluyendo el uso del programa e información sobre los argumentos registrados en el ArgumentParser.

Análisis parcial

ArgumentParser.parse_known_args(args=None, namespace=None)

A veces una secuencia de comandos (script) sólo puede analizar algunos de los argumentos de la línea de comandos, pasando el resto de los argumentos a otra secuencia o programa. En estos casos, el método parse_known_args() puede ser útil. Funciona de forma muy parecida a parse_args() excepto que no produce un error cuando hay argumentos extra presentes. En lugar de ello, retorna una tupla de dos elementos que contiene el espacio de nombres ocupado y la lista de argumentos de cadena de caracteres restantes.

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_true')
>>> parser.add_argument('bar')
>>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])
(Namespace(bar='BAR', foo=True), ['--badger', 'spam'])

Advertencia

Coincidencia de prefijos las reglas se aplican a parse_known_args(). El analizador puede consumir una opción aunque sea sólo un prefijo de una de sus opciones conocidas, en lugar de dejarla en la lista de argumentos restantes.

Personalizando el análisis de archivos

ArgumentParser.convert_arg_line_to_args(arg_line)

Los argumentos que se leen de un archivo (mira el argumento de palabra clave fromfile_prefix_chars para el constructor ArgumentParser) se leen uno por línea. convert_arg_line_to_args() puede ser invalidado para una lectura más elegante.

Este método utiliza un sólo argumento arg_line que es una cadena de caracteres leída desde el archivo de argumentos. Retorna una lista de argumentos analizados a partir de esta cadena de caracteres. El método se llama una vez por línea leída del fichero de argumentos, en orden.

Una alternativa útil de este método es la que trata cada palabra separada por un espacio como un argumento. El siguiente ejemplo demuestra cómo hacerlo:

class MyArgumentParser(argparse.ArgumentParser):
    def convert_arg_line_to_args(self, arg_line):
        return arg_line.split()

Métodos de salida

ArgumentParser.exit(status=0, message=None)

Este método finaliza el programa, saliendo con el status especificado y, si corresponde, muestra un message antes de eso. El usuario puede anular este método para manejar estos pasos de manera diferente:

class ErrorCatchingArgumentParser(argparse.ArgumentParser):
    def exit(self, status=0, message=None):
        if status:
            raise Exception(f'Exiting because of an error: {message}')
        exit(status)

ArgumentParser.error(message)

Este método imprime un mensaje de uso incluyendo el message para error estándar y finaliza el programa con código de estado 2.

Análisis entremezclado

ArgumentParser.parse_intermixed_args(args=None, namespace=None)

ArgumentParser.parse_known_intermixed_args(args=None, namespace=None)

Una serie de comandos Unix permiten al usuario mezclar argumentos opcionales con argumentos de posición. Los métodos parse_intermixed_args() y parse_known_intermixed_args() soportan este modo de análisis.

Estos analizadores no soportan todas las capacidades de argparse, y generarán excepciones si se utilizan capacidades no soportadas. En particular, los analizadores secundarios, argparse.REMAINDER, y los grupos mutuamente exclusivos que incluyen tanto opcionales como de posición no están soportados.

El siguiente ejemplo muestra la diferencia entre parse_known_args() y parse_intermixed_args(): el primero retorna ['2', '3'] como argumentos sin procesar, mientras que el segundo recoge todos los de posición en rest.

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.add_argument('cmd')
>>> parser.add_argument('rest', nargs='*', type=int)
>>> parser.parse_known_args('doit 1 --foo bar 2 3'.split())
(Namespace(cmd='doit', foo='bar', rest=[1]), ['2', '3'])
>>> parser.parse_intermixed_args('doit 1 --foo bar 2 3'.split())
Namespace(cmd='doit', foo='bar', rest=[1, 2, 3])

parse_known_intermixed_args() retorna una tupla de dos elementos que contiene el espacio de nombres poblado y la lista de los restantes argumentos de cadenas de caracteres. parse_intermixed_args() arroja un error si quedan argumentos de cadenas de caracteres sin procesar.

Nuevo en la versión 3.7.

Actualizar el código de optparse

Originalmente, el módulo argparse había intentado mantener la compatibilidad con optparse. Sin embargo, optparse era difícil de extender de forma transparente, particularmente con los cambios necesarios para soportar los nuevos especificadores nargs= y los mensajes de uso mejorados. Cuando casi todo en optparse había sido copiado y pegado o monkey-patched, ya no parecía práctico tratar de mantener la retro-compatibilidad.

El módulo argparse mejora la biblioteca estándar del módulo optparse de varias maneras, incluyendo:

Manejando argumentos de posición.

Soportando sub-comandos.

Permitiendo prefijos de opción alternativos como + y /.

Manejando argumentos de estilo cero o más y uno o más.

Generando mensajes de uso más informativos.

Proporcionando una interfaz mucho más simple para type y action personalizadas.

Una manera de actualizar parcialmente de optparse a argparse:

Reemplaza todas las llamadas optparse.OptionParser.add_option() con llamadas ArgumentParser.add_argument().

Reemplaza (options, args) = parser.parse_args() con args = parser.parse_args() y agrega las llamadas adicionales ArgumentParser.add_argument() para los argumentos de posición. Ten en cuenta que lo que antes se llamaba options, ahora en el contexto argparse se llama args.

Reemplaza optparse.OptionParser.disable_interspersed_args() por parse_intermixed_args() en lugar de parse_args().

Reemplaza las acciones de respuesta y los argumentos de palabra clave callback_* con argumentos de type o action.

Reemplaza los nombres de cadena de caracteres por argumentos de palabra clave type con los correspondientes objetos tipo (por ejemplo, int, float, complex, etc).

Reemplaza optparse.Values por Namespace y optparse.OptionError y optparse.OptionValueError por ArgumentError.

Reemplaza las cadenas de caracteres con argumentos implícitos como %default o %prog por la sintaxis estándar de Python y usa diccionarios para dar formato a cadenas de caracteres, es decir, %(default)s y %(prog)s.

Reemplaza el argumento version del constructor OptionParser por una llamada a parser.add_argument('--version', action='version', version='<the version>').

getopt — Analizador de estilo C para opciones de línea de comando

Código fuente: Lib/getopt.py [https://github.com/python/cpython/tree/3.9/Lib/getopt.py]

Nota

El módulo getopt es un analizador de opciones de línea de comando cuya API está diseñada para que los usuarios de la función C getopt() estén familiarizados. Los usuarios que no estén familiarizados con la función C getopt() o que deseen escribir menos código y obtener mejor ayuda y mensajes de error deberían considerar el uso del módulo argparse.

Este módulo ayuda a los scripts a analizar los argumentos de la línea de comandos en sys.argv. Admite las mismas convenciones que la función Unix getopt() (incluidos los significados especiales de los argumentos de la forma “-” y “--“). También se pueden usar opciones largas similares a las admitidas por el software GNU a través de un tercer argumento opcional.

Este módulo proporciona dos funciones y una excepción:

getopt.getopt(args, shortopts, longopts=[])

Analiza las opciones de la línea de comandos y la lista de parámetros. args es la lista de argumentos a analizar, sin la referencia principal al programa en ejecución. Por lo general, esto significa sys.argv[:]. shortopts es la cadena de letras de opciones que el script quiere reconocer, con opciones que requieren un argumento seguido de dos puntos (':'; es decir, el mismo formato que Unix getopt() usa).

Nota

A diferencia de GNU getopt(), después de un argumento no-opcional, todos los argumentos adicionales se consideran también no-opcionales. Esto es similar a la forma en que funcionan los sistemas Unix que no son GNU.

longopts, si se especifica, debe ser una lista de cadenas con los nombres de las opciones largas que deben admitirse. Los caracteres principales '-' no deben incluirse en el nombre de la opción. Las opciones largas que requieren un argumento deben ir seguidas de un signo igual ('='). Los argumentos opcionales no son compatibles. Para aceptar solo opciones largas, shortopts debe ser una cadena vacía. Las opciones largas en la línea de comando pueden reconocerse siempre que proporcionen un prefijo del nombre de la opción que coincida exactamente con una de las opciones aceptadas. Por ejemplo, si longopts es ['foo', 'frob'], la opción --fo coincidirá como --foo, pero --f no coincidirá de forma exclusiva, por lo que se lanzará GetoptError.

El valor de retorno consta de dos elementos: el primero es una lista de pares (option, value); el segundo es la lista de argumentos del programa que quedan después de que se eliminó la lista de opciones (esta es una porción final de args). Cada par de opción y valor retornado tiene la opción como su primer elemento, con un guión para las opciones cortas (por ejemplo, '-x') o dos guiones para las opciones largas (por ejemplo, '--long-option'), y el argumento de la opción como su segundo elemento, o una cadena vacía si la opción no tiene argumento. Las opciones aparecen en la lista en el mismo orden en que se encontraron, lo que permite múltiples ocurrencias. Las opciones largas y cortas pueden ser mixtas.

getopt.gnu_getopt(args, shortopts, longopts=[])

Esta función funciona como getopt(), excepto que el modo de escaneo estilo GNU se usa por defecto. Esto significa que los argumentos opcionales y no opcionales pueden estar mezclados. La función getopt() detiene el procesamiento de opciones tan pronto como se encuentra un argumento no-opcionales.

Si el primer carácter de la cadena de opciones es '+', o si la variable de entorno POSIXLY_CORRECT está configurada, el procesamiento de opciones se detiene tan pronto como se encuentre un argumento que no sea de opción.

exception getopt.GetoptError

Esto se lanza cuando se encuentra una opción no reconocida en la lista de argumentos o cuando una opción que requiere un argumento no recibe ninguna. El argumento de la excepción es una cadena que indica la causa del error. Para opciones largas, un argumento dado a una opción que no requiere una también provocará que se lance esta excepción. Los atributos msg y opt dan el mensaje de error y la opción relacionada; si no hay una opción específica con la cual se relaciona la excepción, opt es una cadena vacía.

exception getopt.error

Alias para GetoptError; para compatibilidad con versiones anteriores.

Un ejemplo que usa solo opciones de estilo Unix:

>>> import getopt
>>> args = '-a -b -cfoo -d bar a1 a2'.split()
>>> args
['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'abc:d:')
>>> optlist
[('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]
>>> args
['a1', 'a2']

Usar nombres largos de opciones es igualmente fácil:

>>> s = '--condition=foo --testing --output-file abc.def -x a1 a2'
>>> args = s.split()
>>> args
['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'x', [
...     'condition=', 'output-file=', 'testing'])
>>> optlist
[('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-x', '')]
>>> args
['a1', 'a2']

En un script, el uso típico es algo como esto:

import getopt, sys

def main():
    try:
        opts, args = getopt.getopt(sys.argv[1:], "ho:v", ["help", "output="])
    except getopt.GetoptError as err:
        # print help information and exit:
        print(err)  # will print something like "option -a not recognized"
        usage()
        sys.exit(2)
    output = None
    verbose = False
    for o, a in opts:
        if o == "-v":
            verbose = True
        elif o in ("-h", "--help"):
            usage()
            sys.exit()
        elif o in ("-o", "--output"):
            output = a
        else:
            assert False, "unhandled option"
    # ...

if __name__ == "__main__":
    main()

Tenga en cuenta que se podría generar una interfaz de línea de comando equivalente con menos código y más ayuda informativa y mensajes de error utilizando el módulo argparse:

import argparse

if __name__ == '__main__':
    parser = argparse.ArgumentParser()
    parser.add_argument('-o', '--output')
    parser.add_argument('-v', dest='verbose', action='store_true')
    args = parser.parse_args()
    # ... do something with args.output ...
    # ... do something with args.verbose ..

Ver también

Módulo argparse

Opción de línea de comando alternativa y biblioteca de análisis de argumentos.

logging — Instalación de logging para Python

Source code: Lib/logging/__init__.py [https://github.com/python/cpython/tree/3.9/Lib/logging/__init__.py]

Important

Esta página contiene la información de referencia de la API. Para información sobre tutorial y discusión de temas más avanzados, ver

Tutorial básico

Tutorial avanzado

Libro de recetas de Logging

Este módulo define funciones y clases que implementan un sistema flexible de logging de eventos para aplicaciones y bibliotecas.

El beneficio clave de tener la API de logging proporcionada por un módulo de la biblioteca estándar es que todos los módulos de Python pueden participar en el logging, por lo que el registro de su aplicación puede incluir sus propios mensajes integrados con mensajes de módulos de terceros.

El módulo proporciona mucha funcionalidad y flexibilidad. Si no está familiarizado con logging, la mejor manera de familiarizarse con él es ver los tutoriales (ver los enlaces a la derecha).

Las clases básicas definidas por el módulo, junto con sus funciones, se enumeran a continuación.

Los loggers exponen la interfaz que el código de la aplicación usa directamente.

Los gestores envían los registros (creados por los loggers) al destino apropiado.

Los filtros proporcionan una facilidad de ajuste preciso para determinar que registros generar.

Los formateadores especifican el diseño de los registros en el resultado final.

Objetos Logger

Los loggers tienen los siguientes atributos y métodos. Tenga en cuenta que los loggers NUNCA deben ser instanciados directamente, siempre a través de la función de nivel de módulo logging.getLogger(name). Múltiples llamadas a getLogger() con el mismo nombre siempre retornarán una referencia al mismo objeto Logger.

El name es potencialmente un valor jerárquico separado por puntos, como foo.bar.baz (aunque también podría ser simplemente `foo, por ejemplo). Los loggers que están más abajo en la lista jerárquica son hijos de los loggers que están más arriba en la lista. Por ejemplo, dado un logger con el nombre de foo, los logger con los nombres de foo.bar, foo.bar.baz y foo.bam son descendientes de foo. La jerarquía del nombre del logger es análoga a la jerarquía del paquete Python e idéntica si organiza los logger por módulo utilizando la construcción recomendada logging.getLogger(__name__). Debido que en un módulo, __name__ es el nombre del módulo en el espacio de nombres del paquete Python.

class logging.Logger

propagate

Si este atributo se evalúa como verdadero, los eventos registrados en este logger se pasarán a los gestores de los loggers de nivel superior (ancestro), además de los gestores asociados a este logger. Los mensajes se pasan directamente a los gestores de los loggers ancestrales; no se consideran ni el nivel ni los filtros de los loggers ancestrales en cuestión.

Si esto se evalúa como falso, los mensajes de registro no se pasan a los gestores de los logger ancestrales.

Spelling it out with an example: If the propagate attribute of the logger named A.B.C evaluates to true, any event logged to A.B.C via a method call such as logging.getLogger('A.B.C').error(...) will [subject to passing that logger’s level and filter settings] be passed in turn to any handlers attached to loggers named A.B, A and the root logger, after first being passed to any handlers attached to A.B.C. If any logger in the chain A.B.C, A.B, A has its propagate attribute set to false, then that is the last logger whose handlers are offered the event to handle, and propagation stops at that point.

El constructor establece este atributo en True.

Nota

Si adjunta un controlador a un logger y uno o más de sus ancestros, puede emitir el mismo registro varias veces. En general, no debería necesitar adjuntar un gestor a más de un logger; si solo lo adjunta al logger apropiado que está más arriba en la jerarquía del logger, verá todos los eventos registrados por todos los logger descendientes, siempre que la configuración de propagación sea True. Un escenario común es adjuntar gestores solo al logger raíz y dejar que la propagación se encargue del resto.

setLevel(level)

Establece el umbral para este logger en level. Los mensajes de logging que son menos severos que level serán ignorados; los mensajes de logging que tengan un nivel de severidad level o superior serán emitidos por cualquier gestor o gestores que atiendan este logger, a menos que el nivel de un gestor haya sido configurado en un nivel de severidad más alto que level.

Cuando se crea un logger, el nivel se establece en NOTSET (que hace que todos los mensajes se procesen cuando el logger es el logger raíz, o la delegación al padre cuando el logger no es un logger raíz). Tenga en cuenta que el logger raíz se crea con el nivel WARNING.

El término “delegación al padre” significa que si un logger tiene un nivel de NOTSET, su cadena de logger ancestrales se atraviesa hasta que se encuentra un ancestro con un nivel diferente a NOTSET o se alcanza la raíz.

Si se encuentra un antepasado con un nivel distinto de NOTSET, entonces el nivel de ese antepasado se trata como el nivel efectivo del logger donde comenzó la búsqueda de antepasados, y se utiliza para determinar cómo se maneja un evento de registro.

Si se alcanza la raíz y tiene un nivel de NOTSET, se procesarán todos los mensajes. De lo contrario, el nivel de la raíz se utilizará como el nivel efectivo.

Ver Niveles de logging para obtener una lista de niveles.

Distinto en la versión 3.2: El parámetro level ahora acepta una representación de cadena del nivel como “INFO” como alternativa a las constantes de enteros como INFO. Sin embargo, tenga en cuenta que los niveles se almacenan internamente como e.j. getEffectiveLevel() y isEnabledFor() retornará/esperará que se pasen enteros.

isEnabledFor(level)

Indica si este logger procesará un mensaje de gravedad level. Este método verifica primero el nivel de nivel de módulo establecido por logging.disable(level) y luego el nivel efectivo del logger según lo determinado por getEffectiveLevel().

getEffectiveLevel()

Indica el nivel efectivo para este logger. Si se ha establecido un valor distinto de NOTSET utilizando setLevel(), se retorna. De lo contrario, la jerarquía se atraviesa hacia la raíz hasta que se encuentre un valor que no sea NOTSET y se retorna ese valor. El valor retornado es un entero, típicamente uno de logging.DEBUG, logging.INFO etc.

getChild(suffix)

Retorna un logger que es descendiente de este logger, según lo determinado por el sufijo. Por lo tanto, logging.getLogger('abc').getChild('def.ghi') retornaría el mismo logger que retornaría logging.getLogger('abc.def.ghi'). Este es un método convenientemente útil cuando el logger principal se nombra usando e.j. __name__ en lugar de una cadena literal.

Nuevo en la versión 3.2.

debug(msg, *args, **kwargs)

Registra un mensaje con el nivel DEBUG en este logger. El msg es la cadena de formato del mensaje, y los args son los argumentos que se fusionan en msg utilizando el operador de formato de cadena. (Tenga en cuenta que esto significa que puede usar palabras clave en la cadena de formato, junto con un solo argumento de diccionario). No se realiza ninguna operación de formateo % en msg cuando no se suministran args.

Hay cuatro argumentos de palabras clave kwargs que se inspeccionan: exc_info, stack_info, stacklevel y extra.

Si exc_info no se evalúa como falso, hace que se agregue información de excepción al mensaje de registro. Si se proporciona una tupla de excepción (en el formato retornado por sys.exc_info()) o se proporciona una instancia de excepción, se utiliza; de lo contrario, se llama a sys.exc_info() para obtener la información de excepción.

El segundo argumento opcional con la palabra clave stack_info, que por defecto es False. Si es verdadero, la información de la pila agregara el mensaje de registro, incluida la actual llamada del registro. Tenga en cuenta que esta no es la misma información de la pila que se muestra al especificar exc_info: la primera son los cuadros de la pila desde la parte inferior de la pila hasta la llamada de registro en el hilo actual, mientras que la segunda es la información sobre los cuadros de la pila que se han desenrollado, siguiendo una excepción, mientras busca gestores de excepción.

Puede especificar stack_info independientemente de exc_info, por ejemplo solo para mostrar cómo llegaste a cierto punto en tu código, incluso cuando no se lanzaron excepciones. Los marcos de la pila se imprimen siguiendo una línea de encabezado que dice:

Stack (most recent call last):

Esto imita el Traceback (most recent call last): que se usa cuando se muestran marcos de excepción.

El tercer argumento opcional con la palabra clave stacklevel, que por defecto es 1. Si es mayor que 1, se omite el número correspondiente de cuadros de pila al calcular el número de línea y el nombre de la función establecidos en LogRecord creado para el evento de registro. Esto se puede utilizar en el registro de ayudantes para que el nombre de la función, el nombre de archivo y el número de línea registrados no sean la información para la función/método auxiliar, sino más bien su llamador. El nombre de este parámetro refleja el equivalente en el modulo warnings.

El cuarto argumento de palabra clave es extra, que se puede usar para pasar un diccionario que se usa para completar el __dict__ de LogRecord creado para el evento de registro con atributos definidos por el usuario. Estos atributos personalizados se pueden usar a su gusto. Podrían incorporarse en mensajes registrados. Por ejemplo:

FORMAT = '%(asctime)s %(clientip)-15s %(user)-8s %(message)s'
logging.basicConfig(format=FORMAT)
d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}
logger = logging.getLogger('tcpserver')
logger.warning('Protocol problem: %s', 'connection reset', extra=d)

imprimiría algo como

2006-02-08 22:20:02,165 192.168.0.1 fbloggs  Protocol problem: connection reset

Las claves en el diccionario pasado extra no deben entrar en conflicto con las claves utilizadas por el sistema de registro. (Ver la documentación de Formatter para obtener más información sobre qué claves utiliza el sistema de registro).

Si elige usar estos atributos en los mensajes registrados, debe tener cuidado. En el ejemplo anterior, se ha configurado Formatter con una cadena de formato que espera clientip y “usuario” en el diccionario de atributos de LogRecord. Si faltan, el mensaje no se registrará porque se producirá una excepción de formato de cadena. En este caso, siempre debe pasar el diccionario extra con estas teclas.

Si bien esto puede ser molesto, esta función está diseñada para su uso en circunstancias especializadas, como servidores de subprocesos múltiples donde el mismo código se ejecuta en muchos contextos, y las condiciones interesantes que surgen dependen de este contexto (como la dirección IP del cliente remoto y autenticado nombre de usuario, en el ejemplo anterior). En tales circunstancias, es probable que se especialice Formatters con particular Handlers.

Distinto en la versión 3.2: Se agregó el parámetro stack_info.

Distinto en la versión 3.5: El parámetro exc_info ahora puede aceptar instancias de excepción.

Distinto en la versión 3.8: Se agregó el parámetro stacklevel.

info(msg, *args, **kwargs)

Registra un mensaje con el nivel INFO en este logger. Los argumentos se interpretan como debug().

warning(msg, *args, **kwargs)

Registra un mensaje con el nivel WARNING en este logger. Los argumentos se interpretan como debug().

Nota

Hay un método obsoleto warn que es funcionalmente idéntico a warning. Como warn está en desuso, no lo use, use warning en su lugar.

error(msg, *args, **kwargs)

Registra un mensaje con nivel ERROR en este logger. Los argumentos se interpretan como debug().

critical(msg, *args, **kwargs)

Registra un mensaje con el nivel CRITICAL en este logger. Los argumentos se interpretan como debug().

log(level, msg, *args, **kwargs)

Registra un mensaje con nivel entero level en este logger. Los otros argumentos se interpretan como debug().

exception(msg, *args, **kwargs)

Registra un mensaje con nivel ERROR en este logger. Los argumentos se interpretan como debug(). La información de excepción se agrega al mensaje de registro. Este método solo debe llamarse desde un gestor de excepciones.

addFilter(filter)

Agrega el filtro filter especificado a este logger.

removeFilter(filter)

Elimina el filtro filter especificado de este logger.

filter(record)

Aplique los filtros de este logger al registro y retorna True si se va a procesar el registro. Los filtros se consultan a su vez, hasta que uno de ellos retorna un valor falso. Si ninguno de ellos retorna un valor falso, el registro será procesado (pasado a los gestores). Si se retorna un valor falso, no se produce más procesamiento del registro.

addHandler(hdlr)

Agrega el gestor especificado hdlr a este logger.

removeHandler(hdlr)

Elimina el gestor especificado hdlr de este logger.

findCaller(stack_info=False, stacklevel=1)

Encuentra el nombre de archivo de origen de la invoca y el número de línea. Retorna el nombre del archivo, el número de línea, el nombre de la función y la información de la pila como una tupla de 4 elementos. La información de la pila se retorna como None a menos que stack_info sea True.

El parámetro stacklevel se pasa del código que llama a debug() y otras API. Si es mayor que 1, el exceso se utiliza para omitir los cuadros de la pila antes de determinar los valores que se retornarán. Esto generalmente será útil al llamar a las API de registro desde un helper/wrapper, de modo que la información en el registro de eventos no se refiera al helper/wrapper, sino al código que lo llama.

handle(record)

Gestiona un registro pasándolo a todos los gestores asociados con este logger y sus antepasados (hasta que se encuentre un valor falso de propagar). Este método se utiliza para registros no empaquetados recibidos de un socket, así como para aquellos creados localmente. El filtrado a nivel de logger se aplica usando filter().

makeRecord(name, level, fn, lno, msg, args, exc_info, func=None, extra=None, sinfo=None)

Este es un método factory que se puede sobreescribir en subclases para crear instancias especializadas LogRecord.

hasHandlers()

Comprueba si este logger tiene algún controlador configurado. Esto se hace buscando gestores en este logger y sus padres en la jerarquía del logger. Retorna True si se encontró un gestor, de lo contrario, False . El método deja de buscar en la jerarquía cada vez que se encuentra un logger con el atributo propagate establecido en falso: ese será el último logger que verificará la existencia de gestores.

Nuevo en la versión 3.2.

Distinto en la versión 3.7: Los logger ahora se pueden serializar y deserializar (pickled and unpickled).

Niveles de logging

Los valores numéricos de los niveles de logging se dan en la siguiente tabla. Estos son principalmente de interés si desea definir sus propios niveles y necesita que tengan valores específicos en relación con los niveles predefinidos. Si define un nivel con el mismo valor numérico, sobrescribe el valor predefinido; se pierde el nombre predefinido.

Nivel

Valor numérico

CRITICAL

50

ERROR

40

WARNING

30

INFO

20

DEBUG

10

NOTSET

0

Gestor de objetos

Los gestores tienen los siguientes atributos y métodos. Tenga en cuenta que Handler nunca se instancia directamente; Esta clase actúa como base para subclases más útiles. Sin embargo, el método __init__() en las subclases debe llamar a Handler.__init__().

class logging.Handler

__init__(level=NOTSET)

Inicializa la instancia Handler estableciendo su nivel, configurando la lista de filtros en la lista vacía y creando un bloqueo (usando createLock()) para serializar el acceso a un mecanismo de E/S.

createLock()

Inicializa un bloqueo de subprocesos que se puede utilizar para serializar el acceso a la funcionalidad de E/S subyacente que puede no ser segura para subprocesos.

acquire()

Adquiere el bloqueo de hilo creado con createLock().

release()

Libera el bloqueo de hilo adquirido con acquire().

setLevel(level)

Establece el umbral para este gestor en level. Los mensajes de registro que son menos severos que level serán ignorados. Cuando se crea un controlador, el nivel se establece en NOTSET (lo que hace que se procesen todos los mensajes).

Ver Niveles de logging para obtener una lista de niveles.

Distinto en la versión 3.2: El parámetro level ahora acepta una representación de cadena del nivel como “INFO” como alternativa a las constantes de enteros como INFO.

setFormatter(fmt)

Establece Formatter para este controlador en fmt.

addFilter(filter)

Agrega el filtro filter especificado a este gestor.

removeFilter(filter)

Elimina el filtro especificado filter de este gestor.

filter(record)

Aplique los filtros de este gestor al registro y retorna True si se va a procesar el registro. Los filtros se consultan a su vez, hasta que uno de ellos retorna un valor falso. Si ninguno de ellos retorna un valor falso, se emitirá el registro. Si uno retorna un valor falso, el controlador no emitirá el registro.

flush()

Asegúrese de que toda la salida de logging se haya vaciado. Esta versión no hace nada y está destinada a ser implementada por subclases.

close()

Poner en orden los recursos utilizados por el gestor. Esta versión no genera salida, pero elimina el controlador de una lista interna de gestores que se cierra cuando se llama a shutdown(). Las subclases deben garantizar que esto se llame desde métodos close() sobreescritos.

handle(record)

Emite condicionalmente el registro especifico, según los filtros que se hayan agregado al controlador. Envuelve la actual emisión del registro con acquisition/release del hilo de bloqueo E/S.

handleError(record)

Este método debe llamarse desde los gestores cuando se encuentra una excepción durante una llamada a emit(). Si el atributo de nivel de módulo raiseExceptions es `` False``, las excepciones se ignoran silenciosamente. Esto es lo que más se necesita para un sistema de registro: a la mayoría de los usuarios no les importan los errores en el sistema de registro, están más interesados en los errores de la aplicación. Sin embargo, puede reemplazar esto con un gestor personalizado si lo desea. El registro especificado es el que se estaba procesando cuando se produjo la excepción. (El valor predeterminado de raiseExceptions es `` True``, ya que es más útil durante el desarrollo).

format(record)

Formato para un registro - si se configura un formateador, úselo. De lo contrario, use el formateador predeterminado para el módulo.

emit(record)

Haga lo que sea necesario para registrar de forma especifica el registro. Esta versión está destinada a ser implementada por subclases y, por lo tanto, lanza un NotImplementedError.

Para obtener una lista de gestores incluidos como estándar, consulte logging.handlers.

Objetos formateadores

Formatter tiene los siguientes atributos y métodos. Son responsables de convertir una LogRecord a (generalmente) una cadena que puede ser interpretada por un sistema humano o externo. La base Formatter permite especificar una cadena de formato. Si no se proporciona ninguno, se utiliza el valor predeterminado de '%(message)s', que solo incluye el mensaje en la llamada de registro. Para tener elementos de información adicionales en la salida formateada (como una marca de tiempo), siga leyendo.

Un formateador se puede inicializar con una cadena de formato que utiliza el conocimiento de los atributos LogRecord, como el valor predeterminado mencionado anteriormente, haciendo uso del hecho de que el mensaje y los argumentos del usuario están formateados previamente en LogRecord’s con message como atributo. Esta cadena de formato contiene claves de mapeo de Python %-style estándar. Ver la sección Formateo de cadenas al estilo *printf* para obtener más información sobre el formato de cadenas.

Las claves de mapeo útiles en a LogRecord se dan en la sección sobre Atributos LogRecord.

class logging.Formatter(fmt=None, datefmt=None, style='%', validate=True)

Retorna una nueva instancia de Formatter. La instancia se inicializa con una cadena de formato para el mensaje en su conjunto, así como una cadena de formato para la porción fecha/hora de un mensaje. Si no se especifica fmt, se utiliza '%(message)s'. Si no se especifica datefmt, se utiliza un formato que se describe en la documentación formatTime().

El parámetro style puede ser uno de “%”, “{”” o “$” y determina cómo se fusionará la cadena de formato con sus datos: usando uno de %-formatting, str.format() o string.Template. Esto solo aplica al formato de cadenas de caracteres fmt (e.j. '%(message)s' o {message}), no al mensaje pasado actualmente al Logger.debug etc; ver Usar estilos de formato particulares en toda su aplicación para más información sobre usar {- y formateado-$ para mensajes de log.

Distinto en la versión 3.2: Se agregó el parámetro style.

Distinto en la versión 3.8: Se agregó el parámetro validate. Si el estilo es incorrecto o no coincidente, fmt lanzará un ValueError. Por ejemplo: logging.Formatter('%(asctime)s - %(message)s', style='{').

format(record)

El diccionario de atributos del registro se usa como el operando de una operación para formateo de cadenas. Retorna la cadena resultante. Antes de formatear el diccionario, se llevan a cabo un par de pasos preparatorios. El atributo message del registro se calcula usando msg % args. Si el formato de la cadena contiene '(asctime)', formatTime() es llamado para dar formato al evento. Si hay información sobre la excepción, se formatea usando formatException() y se adjunta al mensaje. Tenga en cuenta que la información de excepción formateada se almacena en caché en el atributo exc_text. Esto es útil porque la información de excepción se puede pickled y propagarse en el cable, pero debe tener cuidado si tiene más de una subclase Formatter que personaliza el formato de la información de la excepción. En este caso, tendrá que borrar el valor almacenado en caché después de que un formateador haya terminado su formateo, para que el siguiente formateador que maneje el evento no use el valor almacenado en caché sino que lo recalcule.

Si la información de la pila está disponible, se agrega después de la información de la excepción, usando formatStack() para transformarla si es necesario.

formatTime(record, datefmt=None)

Este método debe ser llamado desde format() por un formateador que espera un tiempo formateado . Este método se puede reemplazar en formateadores para proporcionar cualquier requisito específico, pero el comportamiento básico es el siguiente: if datefmt (una cadena), se usa con time.strftime() para formatear el tiempo de creación del registro De lo contrario, se utiliza el formato “%Y-%m-%d %H:%M:%S,uuu”, donde la parte uuu es un valor de milisegundos y las otras letras son time.strftime() . Un ejemplo de tiempo en este formato es 2003-01-23 00:29:50,411. Se retorna la cadena resultante.

Esta función utiliza una función configurable por el usuario para convertir el tiempo de creación en una tupla. Por defecto, se utiliza time.localtime(); Para cambiar esto para una instancia de formateador particular, se agrega el atributo converter en una función con igual firma como time.localtime() o time.gmtime(). Para cambiarlo en todos los formateadores, por ejemplo, si desea que todos los tiempos de registro se muestren en GMT, agregue el atributo converter en la clase Formatter.

Distinto en la versión 3.3: Anteriormente, el formato predeterminado estaba codificado como en este ejemplo: 2010-09-06 22:38:15,292 donde la parte anterior a la coma es manejada por una cadena de formato strptime ('%Y-%m-%d %H:%M:%S'), y la parte después de la coma es un valor de milisegundos. Debido a que strptime no tiene una posición de formato para milisegundos, el valor de milisegundos se agrega usando otra cadena de formato, '%s,%03d'— ambas cadenas de formato se han codificado en este método. Con el cambio, estas cadenas se definen como atributos de nivel de clase que pueden overridden a nivel de instancia cuando se desee. Los nombres de los atributos son default_time_format (para una cadena de formato strptime) y default_msec_format (para agregar el valor de milisegundos).

Distinto en la versión 3.9: The default_msec_format can be None.

formatException(exc_info)

Formatea la información de una excepción especificada (una excepción como una tupla estándar es retornada por sys.exc_info()) como una cadena. Esta implementación predeterminada solo usa traceback.print_exception(). La cadena resultantes retornada.

formatStack(stack_info)

Formatea la información de una pila especificada (una cadena es retornada por traceback.print_stack(), pero con la ultima línea removida) como una cadena. Esta implementación predeterminada solo retorna el valor de entrada.

Filtro de Objetos

Los Manejadores y los Registradores pueden usar los Filtros para un filtrado más sofisticado que el proporcionado por los niveles. La clase de filtro base solo permite eventos que están por debajo de cierto punto en la jerarquía del logger. Por ejemplo, un filtro inicializado con “A.B” permitirá los eventos registrados por los logger “A.B”, “A.B.C”, “A.B.C.D”, “A.B.D” etc., pero no “A.BB”, “B.A.B”, etc. Si se inicializa con una cadena vacía, se pasan todos los eventos.

class logging.Filter(name='')

Retorna una instancia de la clase Filter. Si se especifica name, nombra un logger que, junto con sus hijos, tendrá sus eventos permitidos a través del filtro. Si name es una cadena vacía, permite todos los eventos.

filter(record)

¿Se apuntará el registro especificado? Retorna cero para no, distinto de cero para sí. Si se considera apropiado, el registro puede modificarse in situ mediante este método.

Tenga en cuenta que los filtros adjuntos a los gestores se consultan antes de que el gestor emita un evento, mientras que los filtros adjuntos a los loggers se consultan cada vez que se registra un evento (usando debug(), info(), etc.), antes de enviar un evento a los gestores. Esto significa que los eventos que han sido generados por loggers descendientes no serán filtrados por la configuración del filtro del logger, a menos que el filtro también se haya aplicado a esos loggers descendientes.

En realidad, no se necesita la subclase Filtro: se puede pasar cualquier instancia que tenga un método de filter con la misma semántica.

Distinto en la versión 3.2: No es necesario crear clases especializadas de Filter ni usar otras clases con un método filter: puede usar una función (u otra invocable) como filtro. La lógica de filtrado verificará si el objeto de filtro tiene un atributo filter: si lo tiene, se asume que es un Filter y se llama a su método filter(). De lo contrario, se supone que es invocable y se llama con el registro como único parámetro. El valor retornado debe ajustarse al retornado por filter().

Aunque los filtros se utilizan principalmente para filtrar registros basados ​​en criterios más sofisticados que los niveles, son capaces de ver cada registro que es procesado por el gestor o logger al que están adjuntos: esto puede ser útil si desea hacer cosas como contar cuántos registros fueron procesados por un logger o gestor en particular, o agregando, cambiando o quitando atributos en LogRecord que se está procesando. Obviamente, el cambio de LogRecord debe hacerse con cierto cuidado, pero permite la inyección de información contextual en los registros (ver Usar filtros para impartir información contextual).

Objetos LogRecord

Las instancias LogRecord son creadas automáticamente por Logger cada vez que se registra algo, y se pueden crear manualmente a través de makeLogRecord() (por ejemplo, a partir de un evento serializado (pickled) recibido en la transmisión).

class logging.LogRecord(name, level, pathname, lineno, msg, args, exc_info, func=None, sinfo=None)

Contiene toda la información pertinente al evento que se registra.

La información principal se pasa en msg y args, que se combinan usando msg % args para crear el campo message del registro.

Parámetros

name – El nombre del logger utilizado para registrar el evento representado por este LogRecord. Tenga en cuenta que este nombre siempre tendrá este valor, aunque puede ser emitido por un gestor adjunto a un logger diferente (ancestro).

level – El nivel numérico del evento logging (uno de DEBUG, INFO, etc.) Tenga en cuenta que esto se convierte en dos atributos de LogRecord:levelno para el valor numérico y levelname para el nombre del nivel correspondiente .

pathname – El nombre de ruta completo del archivo de origen donde se realizó la llamada logging.

lineno – El número de línea en el archivo de origen donde se realizó la llamada logging.

msg – El mensaje de descripción del evento, posiblemente una cadena de formato con marcadores de posición para datos variables.

args – Datos variables para fusionar en el argumento msg para obtener la descripción del evento.

exc_info – Una tupla de excepción con la información de excepción actual, o None si no hay información de excepción disponible.

func – El nombre de la función o método desde el que se invocó la llamada de logging.

sinfo – Una cadena de texto que representa la información de la pila desde la base de la pila en el hilo actual, hasta la llamada de logging.

getMessage()

Retorna el mensaje para la instancia LogRecord después de fusionar cualquier argumento proporcionado por el usuario con el mensaje. Si el argumento del mensaje proporcionado por el usuario para la llamada de logging no es una cadena de caracteres, se invoca str() para convertirlo en una cadena. Esto permite el uso de clases definidas por el usuario como mensajes, cuyo método __str__ puede retornar la cadena de formato real que se utilizará.

Distinto en la versión 3.2: La creación de LogRecord se ha hecho más configurable al proporcionar una fábrica que se utiliza para crear el registro. La fábrica se puede configurar usando getLogRecordFactory() y setLogRecordFactory() (ver esto para la firma de la fábrica).

Esta funcionalidad se puede utilizar para inyectar sus propios valores en LogRecord en el momento de la creación. Puede utilizar el siguiente patrón:

old_factory = logging.getLogRecordFactory()

def record_factory(*args, **kwargs):
    record = old_factory(*args, **kwargs)
    record.custom_attribute = 0xdecafbad
    return record

logging.setLogRecordFactory(record_factory)

Con este patrón, se podrían encadenar varias fábricas y, siempre que no sobrescriban los atributos de las demás o se sobrescriban involuntariamente los atributos estándar enumerados anteriormente, no debería haber sorpresas.

Atributos LogRecord

LogRecord tiene varios atributos, la mayoría de los cuales se derivan de los parámetros del constructor. (Tenga en cuenta que los nombres no siempre se corresponden exactamente entre los parámetros del constructor de LogRecord y los atributos de LogRecord). Estos atributos se pueden usar para combinar datos del registro en la cadena de formato. La siguiente tabla enumera (en orden alfabético) los nombres de los atributos, sus significados y el marcador de posición correspondiente en una cadena de formato %.

Si utilizas formato-{} (str.format()), puedes usar {attrname} como marcador de posición en la cadena de caracteres de formato. Si está utilizando formato-$ (string.Template), use la forma ${attrname}. En ambos casos, por supuesto, reemplace` attrname` con el nombre de atributo real que desea utilizar.

En el caso del formato-{}, puede especificar flags de formato colocándolos después del nombre del atributo, separados con dos puntos. Por ejemplo: un marcador de posición de {msecs:03d} formateará un valor de milisegundos de 4 como 004. Consulte la documentación str.format() para obtener detalles completos sobre las opciones disponibles.

Nombre del atributo

Formato

Descripción

args

No debería necesitar formatear esto usted mismo.

La tupla de argumentos se fusionó en msg para producir un messsage, o un dict cuyos valores se utilizan para la fusión (cuando solo hay un argumento y es un diccionario).

asctime

%(asctime)s

Fecha y Hora en formato legible por humanos cuando se creó LogRecord. De forma predeterminada, tiene el formato “2003-07-08 16: 49: 45,896” (los números después de la coma son milisegundos).

created

%(created)f

Tiempo en que se creó LogRecord (según lo retornado por time.time()).

exc_info

No debería necesitar formatear esto usted mismo.

Tupla de excepción (al modo sys.exc_info) o, si no se ha producido ninguna excepción, None.

filename

%(filename)s

Parte del nombre de archivo de pathname.

funcName

%(funcName)s

Nombre de la función que contiene la llamada de logging.

levelname

%(levelname)s

Texto de nivel de logging para el mensaje ('DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL').

levelno

%(levelno)s

Número de nivel de logging para el mensaje (DEBUG, INFO, WARNING, ERROR, CRITICAL).

lineno

%(lineno)d

Número de línea original donde se emitió la llamada de logging (si está disponible).

message

%(message)s

El mensaje registrado, computado como msg % args. Esto se establece cuando se invoca Formatter.format().

module

%(module)s

Módulo (parte del nombre de filename).

msecs

%(msecs)d

Porción de milisegundos del tiempo en que se creó LogRecord.

msg

No debería necesitar formatear esto usted mismo.

La cadena de caracteres de formato pasada en la llamada logging original. Se fusionó con args para producir un message, o un objeto arbitrario (ver Usando objetos arbitrarios como mensajes).

name

%(name)s

Nombre del logger usado para registrar la llamada.

pathname

%(pathname)s

Nombre de ruta completo del archivo de origen donde se emitió la llamada de logging (si está disponible).

process

%(process)d

ID de proceso (si está disponible).

processName

%(processName)s

Nombre del proceso (si está disponible).

relativeCreated

%(relativeCreated)d

Tiempo en milisegundos cuando se creó el LogRecord, en relación con el tiempo en que se cargó el módulo logging.

stack_info

No debería necesitar formatear esto usted mismo.

Apila la información del marco (si está disponible) desde la parte inferior de la pila en el hilo actual hasta la llamada de registro que dio como resultado la generación de este registro.

thread

%(thread)d

ID de hilo (si está disponible).

threadName

%(threadName)s

Nombre del hilo (si está disponible).

Distinto en la versión 3.1: processName fue agregado.

Objetos LoggerAdapter

Las instancias LoggerAdapter se utilizan para pasar convenientemente información contextual en las llamadas de logging. Para ver un ejemplo de uso, consulte la sección sobre agregar información contextual a su salida de logging.

class logging.LoggerAdapter(logger, extra)

Retorna una instancia de LoggerAdapter inicializada con una instancia subyacente Logger y un objeto del tipo dict.

process(msg, kwargs)

Modifica el mensaje y/o los argumentos de palabra clave pasados a una llamada de logging para insertar información contextual. Esta implementación toma el objeto pasado como extra al constructor y lo agrega a kwargs usando la clave “extra”. El valor de retorno es una tupla (msg, kwargs) que tiene las versiones (posiblemente modificadas) de los argumentos pasados.

Además de lo anterior, LoggerAdapter admite los siguientes métodos de Logger: debug(), info(), warning(), error(), exception(), critical(), log(), isEnabledFor(), getEffectiveLevel(), setLevel() y hasHandlers(). Estos métodos tienen las mismas firmas que sus contrapartes en Logger, por lo que puede usar los dos tipos de instancias indistintamente.

Distinto en la versión 3.2: Los métodos isEnabledFor(), getEffectiveLevel(), setLevel() y hasHandlers() se agregaron a LoggerAdapter . Estos métodos se delegan al logger subyacente.

Distinto en la versión 3.6: Attribute manager and method _log() were added, which delegate to the underlying logger and allow adapters to be nested.

Seguridad del hilo

El módulo logging está diseñado para ser seguro para subprocesos sin que sus clientes tengan que realizar ningún trabajo especial. Lo logra mediante el uso de bloqueos de hilos; hay un bloqueo para serializar el acceso a los datos compartidos del módulo, y cada gestor también crea un bloqueo para serializar el acceso a su E/S subyacente.

Si está implementando gestores de señales asíncronos usando el módulo signal, es posible que no pueda usar logging desde dichos gestores. Esto se debe a que las implementaciones de bloqueo en el módulo threading no siempre son reentrantes y, por lo tanto, no se pueden invocar desde dichos gestores de señales.

Funciones a nivel de módulo

Además de las clases descritas anteriormente, hay una serie de funciones a nivel de módulo.

logging.getLogger(name=None)

Retorna un logger con el nombre especificado o, si el nombre es None, retorna un logger que es el logger principal de la jerarquía. Si se especifica, el nombre suele ser un nombre jerárquico separado por puntos como “a”, “a.b” or “a.b.c.d”. La elección de estos nombres depende totalmente del desarrollador que utiliza logging.

Todas las llamadas a esta función con un nombre dado retornan la misma instancia de logger. Esto significa que las instancias del logger nunca necesitan pasar entre diferentes partes de una aplicación.

logging.getLoggerClass()

Retorna ya sea la clase estándar Logger, o la última clase pasada a setLoggerClass(). Esta función se puede llamar desde una nueva definición de clase, para garantizar que la instalación de una clase personalizada Logger no deshaga las customizaciones ya aplicadas por otro código. Por ejemplo:

class MyLogger(logging.getLoggerClass()):
    # ... override behaviour here

logging.getLogRecordFactory()

Retorna un invocable que se usa para crear una LogRecord.

Nuevo en la versión 3.2: Esta función se ha proporcionado, junto con setLogRecordFactory(), para permitir a los desarrolladores un mayor control sobre cómo LogRecord representa un evento logging construido.

Consulte setLogRecordFactory() para obtener más información sobre cómo se llama a la fábrica.

logging.debug(msg, *args, **kwargs)

Registra un mensaje con el nivel DEBUG en el logger raíz. msg * es la cadena de carácteres de formato del mensaje y *args son los argumentos que se fusionan en msg usando el operador de formato de cadena. (Tenga en cuenta que esto significa que puede utilizar palabras clave en la cadena de formato, junto con un único argumento de diccionario).

Hay tres argumentos de palabras clave en kwargs que se inspeccionan: exc_info que, si no se evalúa como falso, hace que se agregue información de excepción al mensaje de registro. Si se proporciona una tupla de excepción (en el formato retornado por sys.exc_info()) o una instancia de excepción, se utiliza; de lo contrario, se llama a sys.exc_info() para obtener la información de la excepción.

El segundo argumento opcional con la palabra clave stack_info, que por defecto es False. Si es verdadero, la información de la pila agregara el mensaje de registro, incluida la actual llamada del registro. Tenga en cuenta que esta no es la misma información de la pila que se muestra al especificar exc_info: la primera son los cuadros de la pila desde la parte inferior de la pila hasta la llamada de registro en el hilo actual, mientras que la segunda es la información sobre los cuadros de la pila que se han desenrollado, siguiendo una excepción, mientras busca gestores de excepción.

Puede especificar stack_info independientemente de exc_info, por ejemplo solo para mostrar cómo llegaste a cierto punto en tu código, incluso cuando no se lanzaron excepciones. Los marcos de la pila se imprimen siguiendo una línea de encabezado que dice:

Stack (most recent call last):

Esto imita el Traceback (most recent call last): que se usa cuando se muestran marcos de excepción.

El tercer argumento de palabra clave opcional es extra que se puede usar para pasar un diccionario que se usa para completar el __dict__ de LogRecord creado para el evento de registro con atributos definidos por el usuario. Estos atributos personalizados se pueden utilizar como desee. Por ejemplo, podrían incorporarse a mensajes registrados. Por ejemplo:

FORMAT = '%(asctime)s %(clientip)-15s %(user)-8s %(message)s'
logging.basicConfig(format=FORMAT)
d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}
logging.warning('Protocol problem: %s', 'connection reset', extra=d)

imprimiría algo como:

2006-02-08 22:20:02,165 192.168.0.1 fbloggs  Protocol problem: connection reset

Las claves en el diccionario pasado extra no deben entrar en conflicto con las claves utilizadas por el sistema de registro. (Ver la documentación de Formatter para obtener más información sobre qué claves utiliza el sistema de registro).

Si opta por utilizar estos atributos en los mensajes registrados, debemos tener cuidado. En el caso anterior, por ejemplo, Formatter se ha configurado con una cadena de caracteres de formato que espera “clientip” y “user” en el diccionario de atributos de LogRecord. Si faltan, el mensaje no se registrará porque se producirá una excepción de formato de cadena. Entonces, en este caso, siempre debe pasar el diccionario extra con estas claves.

Si bien esto puede ser molesto, esta función está diseñada para su uso en circunstancias especializadas, como servidores de subprocesos múltiples donde el mismo código se ejecuta en muchos contextos, y las condiciones interesantes que surgen dependen de este contexto (como la dirección IP del cliente remoto y autenticado nombre de usuario, en el ejemplo anterior). En tales circunstancias, es probable que se especialice Formatters con particular Handlers.

Distinto en la versión 3.2: Se agregó el parámetro stack_info.

logging.info(msg, *args, **kwargs)

Registra un mensaje con nivel INFO en el logger raíz. Los argumentos se interpretan como debug().

logging.warning(msg, *args, **kwargs)

Registra un mensaje con nivel WARNING en el logger raíz. Los argumentos se interpretan como debug().

Nota

Hay una función obsoleta warn` que es funcionalmente idéntica a warning. Como warn está deprecado, por favor no lo use, use warning en su lugar.

logging.error(msg, *args, **kwargs)

Registra un mensaje con nivel ERROR en el logger raíz. Los argumentos se interpretan como debug().

logging.critical(msg, *args, **kwargs)

Registra un mensaje con nivel CRITICAL en el logger raíz. Los argumentos se interpretan como debug().

logging.exception(msg, *args, **kwargs)

Registra un mensaje con nivel ERROR en el logger raíz. Los argumentos se interpretan como debug(). Se agrega información de excepción al mensaje de logging. Esta función solo se debe llamar desde un gestor de excepciones.

logging.log(level, msg, *args, **kwargs)

Registra un mensaje con nivel level en el logger raíz. Los argumentos restantes se interpretan como debug().

logging.disable(level=CRITICAL)

Proporciona un nivel superior de level para todos los loggers que tienen prioridad sobre el propio nivel del logger. Cuando surge la necesidad de reducir temporalmente la salida de logging en toda la aplicación, esta función puede resultar útil. Su efecto es deshabilitar todas las llamadas de gravedad level e inferior, de modo que si lo llaman con un valor de INFO, todos los eventos INFO y DEBUG se descartarán, mientras que los de gravedad WARNING y superiores se procesarán de acuerdo con el nivel efectivo del logger. Si se llama a logging.disable(logging.NOTSET) , elimina efectivamente este nivel primordial, de modo que la salida del registro depende nuevamente de los niveles efectivos de los loggers individuales.

Tenga en cuenta que si ha definido un nivel de logging personalizado superior a CRITICAL (esto no es recomendado), no podrá confiar en el valor predeterminado para el parámetro level, pero tendrá que proporcionar explícitamente un valor adecuado.

Distinto en la versión 3.7: El parámetro level se estableció por defecto en el nivel CRITICAL. Consulte el Issue #28524 para obtener más información sobre este cambio.

logging.addLevelName(level, levelName)

Asocia nivel level con el texto levelName en un diccionario interno, que se utiliza para asignar niveles numéricos a una representación textual, por ejemplo, cuando Formatter formatea un mensaje. Esta función también se puede utilizar para definir sus propios niveles. Las únicas restricciones son que todos los niveles utilizados deben registrarse utilizando esta función, los niveles deben ser números enteros positivos y deben aumentar en orden creciente de severidad.

Nota

Si está pensando en definir sus propios niveles, consulte la sección sobre Niveles personalizados.

logging.getLevelName(level)

Returns the textual or numeric representation of logging level level.

If level is one of the predefined levels CRITICAL, ERROR, WARNING, INFO or DEBUG then you get the corresponding string. If you have associated levels with names using addLevelName() then the name you have associated with level is returned. If a numeric value corresponding to one of the defined levels is passed in, the corresponding string representation is returned.

The level parameter also accepts a string representation of the level such as “INFO”. In such cases, this functions returns the corresponding numeric value of the level.

If no matching numeric or string value is passed in, the string “Level %s” % level is returned.

Nota

Los niveles internamente son números enteros (ya que deben compararse en la lógica de logging). Esta función se utiliza para convertir entre un nivel entero y el nombre del nivel que se muestra en la salida de logging formateado mediante el especificador de formato %(levelname)s (ver Atributos LogRecord).

Distinto en la versión 3.4: En las versiones de Python anteriores a la 3.4, esta función también podría pasar un nivel de texto y retornaría el valor numérico correspondiente del nivel. Este comportamiento indocumentado se consideró un error y se eliminó en Python 3.4, pero se restableció en 3.4.2 debido a que conserva la compatibilidad con versiones anteriores.

logging.makeLogRecord(attrdict)

Crea y retorna una nueva instancia LogRecord cuyos atributos están definidos por attrdict. Esta función es útil para tomar un diccionario de atributos serializado (pickled) LogRecord, enviado a través de un socket, y reconstituido como una instancia LogRecord en el extremo receptor.

logging.basicConfig(**kwargs)

Realiza una configuración básica para el sistema de logging creando una StreamHandler con un Formatter predeterminado y agregándolo al logger raíz. Las funciones debug(), info(), warning(), error() y critical() llamarán basicConfig() automáticamente si no se definen gestores para el logger raíz.

Esta función no hace nada si el logger raíz ya tiene gestores configurados, a menos que el argumento de palabra clave force esté establecido como True.

Nota

Esta función debe llamarse desde el hilo principal antes de que se inicien otros hilos. En las versiones de Python anteriores a 2.7.1 y 3.2, si se llama a esta función desde varios subprocesos, es posible (en raras circunstancias) que se agregue un gestor al logger raíz más de una vez, lo que genera resultados inesperados como mensajes duplicados en el registro.

Se admiten los siguientes argumentos de palabras clave.

Formato

Descripción

filename

Especifica que se cree un FileHandler, utilizando el nombre de archivo especificado, en lugar de StreamHandler.

filemode

Si se especifica filename, abre el archivo en mode. Por defecto es 'a'.

format

Utiliza la cadena de caracteres de formato especificada para el gestor.Los atributos por defecto son levelname, name y message separado por dos puntos.

datefmt

Utiliza el formato de fecha/hora especificado, aceptado por time.strftime().

style

Si format es especificado, utilice este estilo para la cadena de caracteres de formato. Uno de '%', '{' o '$' para printf-style, str.format() o string.Template respectivamente. El valor predeterminado es '%'.

level

Establece el nivel del logger raíz en el level especificado.

stream

Utiliza la secuencia especificada para inicializar StreamHandler. Tenga en cuenta que este argumento es incompatible con filename; si ambos están presentes, se lanza un ValueError.

handlers

Si se especifica, debe ser una iteración de los gestores ya creados para agregar al logger raíz. A cualquier gestor que aún no tenga un formateador configurado se le asignará el formateador predeterminado creado en esta función. Tenga en cuenta que este argumento es incompatible con filename o stream; si ambos están presentes, se lanza un ValueError.

force

Si este argumento de palabra clave se especifica como verdadero, los gestores existentes adjuntos al logger raíz se eliminan y cierran antes de llevar a cabo la configuración tal como se especifica en los otros argumentos.

encoding

If this keyword argument is specified along with filename, its value is used when the FileHandler is created, and thus used when opening the output file.

errors

If this keyword argument is specified along with filename, its value is used when the FileHandler is created, and thus used when opening the output file. If not specified, the value “backslashreplace” is used. Note that if None is specified, it will be passed as such to func:open, which means that it will be treated the same as passing “errors”.

Distinto en la versión 3.2: Se agregó el argumento style.

Distinto en la versión 3.3: Se agregó el argumento handlers. Se agregaron verificaciones adicionales para detectar situaciones en las que se especifican argumentos incompatibles (por ejemplo, handlers junto con stream o filename, o stream junto con filename).

Distinto en la versión 3.8: Se agregó el argumento force.

Distinto en la versión 3.9: The encoding and errors arguments were added.

logging.shutdown()

Informa al sistema de logging para realizar un apagado ordenado descargando y cerrando todos los gestores. Esto se debe llamar al salir de la aplicación y no se debe hacer ningún uso posterior del sistema de logging después de esta llamada.

Cuando se importa el módulo de logging, registra esta función como un gestor de salida (ver atexit), por lo que normalmente no es necesario hacerlo manualmente.

logging.setLoggerClass(klass)

Le dice al sistema de logging que use la clase klass al crear una instancia de un logger. La clase debe definir __init__() tal que solo se requiera un argumento de nombre, y __init__() debe llamar Logger.__init__(). Por lo general, esta función se llama antes de cualquier loggers sea instanciado por las aplicaciones que necesitan utilizar un comportamiento de logger personalizado. Después de esta llamada, como en cualquier otro momento, no cree instancias de loggers directamente usando la subclase: continúe usando la API logging.getLogger() para obtener sus loggers.

logging.setLogRecordFactory(factory)

Establece un invocable que se utiliza para crear LogRecord.

Parámetros

factory – La fábrica invocable que se utilizará para crear una instancia de un registro.

Nuevo en la versión 3.2: Esta función se ha proporcionado, junto con getLogRecordFactory(), para permitir a los desarrolladores un mayor control sobre cómo se construye LogRecord que representa un evento de logging.

La fábrica tiene la siguiente firma:

factory(name, level, fn, lno, msg, args, exc_info, func=None, sinfo=None, **kwargs)

name

El nombre del logger.

level

El nivel de logging (numérico).

fn

El nombre de ruta completo del archivo donde se realizó la llamada de logging.

lno

El número de línea en el archivo donde se realizó la llamada de logging.

msg

El mensaje de logging.

args

Los argumentos para el mensaje de logging.

exc_info

Una tupla de excepción o None.

func

El nombre de la función o método que invocó la llamada de logging.

sinfo

Un seguimiento de pila como el que proporciona traceback.print_stack(), que muestra la jerarquía de llamadas.

kwargs

Argumentos de palabras clave adicionales.

Atributos a nivel de módulo

logging.lastResort

Un «gestor de último recurso» está disponible a través de este atributo. Esta es una StreamHandler que escribe en``sys.stderr`` con un nivel WARNING, y se usa para gestionar eventos de logging en ausencia de cualquier configuración de logging. El resultado final es simplemente imprimir el mensaje en sys.stderr. Esto reemplaza el mensaje de error anterior que decía que «no se pudieron encontrar gestores para el logger XYZ». Si necesita el comportamiento anterior por alguna razón, lastResort se puede configurar en None.

Nuevo en la versión 3.2.

Integración con el módulo de advertencias

La función captureWarnings() se puede utilizar para integrar logging con el módulo warnings.

logging.captureWarnings(capture)

Esta función se utiliza para activar y desactivar la captura de advertencias (warnings).

Si capture es True, las advertencias emitidas por el módulo warnings serán redirigidas al sistema de logging. Específicamente, una advertencia se formateará usando warnings.formatwarning() y la cadena de caracteres resultante se registrará en un logger llamado 'py.warnings' con severidad WARNING.

Si capture es False, la redirección de advertencias al sistema de logging se detendrá y las advertencias serán redirigidas a sus destinos originales (es decir, aquellos en vigor antes de que se llamara a captureWarnings(True)).

Ver también

Módulo logging.config

API de configuración para el módulo logging.

Módulo logging.handlers

Gestores útiles incluidos con el módulo logging.

PEP 282 [https://www.python.org/dev/peps/pep-0282] - A Logging System

La propuesta que describió esta característica para su inclusión en la biblioteca estándar de Python.

Original Python logging package [https://old.red-dove.com/python_logging.html]

Esta es la fuente original del paquete logging. La versión del paquete disponible en este sitio es adecuada para usar con Python 1.5.2, 2.1.xy 2.2.x, que no incluyen el paquete logging en la biblioteca estándar.

logging.config — Configuración de registro

Código fuente: Lib/logging/config.py [https://github.com/python/cpython/tree/3.9/Lib/logging/config.py]

Important

Esta página solo contiene información de referencia. Para tutoriales, por favor consulte

Tutorial Básico

Tutorial Avanzado

Guía de registro *Logging*

Esta sección describe la API para configurar el módulo de registro.

Funciones de configuración

Las siguientes funciones configuran el módulo de registro. Se encuentran en el módulo logging.config. Su uso es opcional: puede configurar el módulo de registro utilizando estas funciones o realizando llamadas a la API principal (definida en logging) y definiendo los manejadores que se declaran en logging o logging.handlers.

logging.config.dictConfig(config)

Toma la configuración de registro de un diccionario. El contenido de este diccionario se describe en Esquema del diccionario de configuración a continuación.

Si se encuentra un error durante la configuración, esta función lanzará un ValueError, TypeError, AttributeError o ImportError con un mensaje descriptivo adecuado. La siguiente es una lista (posiblemente incompleta) de condiciones que lanzará un error:

Un nivel que no es una cadena o que es una cadena que no corresponde a un nivel de registro real.

Un valor de propagación que no es booleano.

Una identificación que no tiene un destino correspondiente.

Una identificación de manejador inexistente encontrada durante una llamada incremental.

Un nombre de registrador no válido.

Incapacidad para resolver un objeto interno o externo.

El análisis se realiza mediante la clase DictConfigurator, a cuyo constructor se le pasa el diccionario utilizado para la configuración, y tiene un método configure(). El módulo logging.config tiene un atributo invocable dictConfigClass que se establece inicialmente en DictConfigurator. Puede reemplazar el valor de dictConfigClass con una implementación adecuada propia.

dictConfig() llama dictConfigClass pasando el diccionario especificado, y luego llama al método configure() en el objeto retornado para que la configuración surta efecto:

def dictConfig(config):
    dictConfigClass(config).configure()

Por ejemplo, una subclase de DictConfigurator podría llamar a DictConfigurator.__ init__() en su mismo __init__(), luego configurar prefijos personalizados que serían utilizables en la siguiente llamada configure(). dictConfigClass estaría vinculado a esta nueva subclase, y luego dictConfig() podría llamarse exactamente como en el estado predeterminado, no personalizado.

Nuevo en la versión 3.2.

logging.config.fileConfig(fname, defaults=None, disable_existing_loggers=True)

Lee la configuración de registro desde un archivo de formato de configparser. El formato del archivo debe ser como se describe en Formato de archivo de configuración. Esta función se puede invocar varias veces desde una aplicación, lo que permite al usuario final seleccionar entre varias configuraciones predeterminadas (si el desarrollador proporciona un mecanismo para presentar las opciones y cargar la configuración elegida).

Parámetros

fname – Un nombre de archivo, o un objeto similar a un archivo, o una instancia derivada de RawConfigParser. Si se pasa una instancia derivada de RawConfigParser, se usa tal cual. De lo contrario, se instancia Configparser, y la configuración leída desde el objeto pasado en fname. Si eso tiene un método readline(), se supone que es un objeto similar a un archivo y se lee usando read_file(); de lo contrario, se supone que es un nombre de archivo y se pasa a read().

defaults – Los valores predeterminados para pasar al ConfigParser se pueden especificar en este argumento.

disable_existing_loggers – Si se especifica como False, los registradores que existen cuando se realiza esta llamada se dejan habilitados. El valor predeterminado es True porque esto permite un comportamiento antiguo de una manera compatible con versiones anteriores. Este comportamiento consiste en deshabilitar cualquier registrador no root existente a menos que ellos o sus antepasados se mencionen explícitamente en la configuración de registro.

Distinto en la versión 3.4: Una instancia de una subclase de RawConfigParser ahora se acepta como un valor para fname. Esto facilita:

Uso de un archivo de configuración donde la configuración de registro es solo parte de la configuración general de la aplicación.

Uso de una configuración leída de un archivo, y luego modificada por la aplicación que lo usa (por ejemplo, basada en parámetros de línea de comandos u otros aspectos del entorno de ejecución) antes de pasar a fileConfig.

logging.config.listen(port=DEFAULT_LOGGING_CONFIG_PORT, verify=None)

Inicia un servidor de socket en el puerto especificado y escucha nuevas configuraciones. Si no se especifica ningún puerto, se usa el valor predeterminado del módulo DEFAULT_LOGGING_CONFIG_PORT. Las configuraciones de registro se enviarán como un archivo adecuado para su procesamiento por dictConfig() o fileConfig(). Retorna una instancia de Thread en la que puede llamar start() para iniciar el servidor, y que puede join() cuando corresponda . Para detener el servidor, llame a stopListening().

El argumento verificar, si se especifica, debe ser invocable, lo que debería verificar si los bytes recibidos en el socket son válidos y deben procesarse. Esto podría hacerse encriptando y / o firmando lo que se envía a través del socket, de modo que el verificar invocable pueda realizar la verificación o descifrado de la firma. El llamado invocable verificar se llama con un solo argumento (los bytes recibidos a través del socket) y debe retornar los bytes a procesar, o None para indicar que los bytes deben descartarse. Los bytes retornados podrían ser los mismos que los pasados en bytes (por ejemplo, cuando solo se realiza la verificación), o podrían ser completamente diferentes (tal vez si se realizó el descifrado).

Para enviar una configuración al socket, lea el archivo de configuración y envíelo al socket como una secuencia de bytes precedida por una cadena de longitud de cuatro bytes empaquetada en binario usando struct.pack('>L', n).

Nota

Because portions of the configuration are passed through eval(), use of this function may open its users to a security risk. While the function only binds to a socket on localhost, and so does not accept connections from remote machines, there are scenarios where untrusted code could be run under the account of the process which calls listen(). Specifically, if the process calling listen() runs on a multi-user machine where users cannot trust each other, then a malicious user could arrange to run essentially arbitrary code in a victim user’s process, simply by connecting to the victim’s listen() socket and sending a configuration which runs whatever code the attacker wants to have executed in the victim’s process. This is especially easy to do if the default port is used, but not hard even if a different port is used. To avoid the risk of this happening, use the verify argument to listen() to prevent unrecognised configurations from being applied.

Distinto en la versión 3.4: Se agregó el argumento verificar.

Nota

Si desea enviar configuraciones al oyente que no deshabiliten los registradores existentes, deberá usar un formato JSON para la configuración, que utilizará dictConfig() para la configuración. Este método le permite especificar disable_existing_loggers como False en la configuración que envía.

logging.config.stopListening()

Detiene el servidor de escucha que se creó con una llamada a listen(). Esto normalmente se llama antes de llamar join() en el valor de retorno de listen().

Security considerations

The logging configuration functionality tries to offer convenience, and in part this is done by offering the ability to convert text in configuration files into Python objects used in logging configuration - for example, as described in Objetos definidos por el usuario. However, these same mechanisms (importing callables from user-defined modules and calling them with parameters from the configuration) could be used to invoke any code you like, and for this reason you should treat configuration files from untrusted sources with extreme caution and satisfy yourself that nothing bad can happen if you load them, before actually loading them.

Esquema del diccionario de configuración

La descripción de una configuración de registro requiere una lista de los diversos objetos para crear y las conexiones entre ellos; por ejemplo, puede crear un manejador llamado “consola” y luego decir que el registrador llamado “inicio” enviará sus mensajes al manejador “consola”. Estos objetos no se limitan a los proporcionados por el módulo logging porque podría escribir su propia clase de formateador o manejador. Los parámetros de estas clases también pueden necesitar incluir objetos externos como sys.stderr. La sintaxis para describir estos objetos y conexiones se define en Conexiones de objeto a continuación.

Detalles del esquema del diccionario

El diccionario pasado a dictConfig() debe contener las siguientes claves:

version - se establece en un valor entero que representa la versión del esquema. El único valor válido en este momento es 1, pero tener esta clave permite que el esquema evolucione sin perder la compatibilidad con versiones anteriores.

Todas las demás claves son opcionales, pero si están presentes se interpretarán como se describe a continuación. En todos los casos a continuación, donde se menciona un “dict de configuración”, se verificará la clave especial '()' para ver si se requiere una instanciación personalizada. Si es así, el mecanismo descrito en Objetos definidos por el usuario a continuación se usa para crear una instancia; de lo contrario, el contexto se usa para determinar qué instanciar.

formatters: el valor correspondiente será un diccionario en el que cada clave es una identificación de formateador y cada valor es un diccionario que describe cómo configurar la instancia correspondiente Formatter.

La configuración diccionario se busca para las claves format y datefmt (con los valores predeterminados de None) y se utilizan para construir una instancia de Formatter.

Distinto en la versión 3.8: se puede agregar una tecla validar (con el valor predeterminado True) en la sección formatters de la configuración diccionario, esto es para validar el formato.

filters: el valor correspondiente será un diccionario en el que cada clave es una identificación de filtro y cada valor es un diccionario que describe cómo configurar la instancia de filtro correspondiente.

El diccionario de configuración busca la clave nombre (por defecto en la cadena vacía) y esto se utiliza para construir una instancia de logging.Filter.

handlers: el valor correspondiente será un diccionario en el que cada clave es una identificación de manejador y cada valor es un diccionario que describe cómo configurar la instancia del manejador correspondiente.

El diccionario de configuración busca las siguientes claves:

clase (obligatorio). Este es el nombre completo de la clase de manejador.

nivel (opcional). El nivel del manejador.

formateador (opcional). La identificación del formateador para este manejador.

filtros (opcional). Una lista de identificadores de los filtros para este manejador.

Todas las claves other se pasan como argumentos de palabras clave al constructor del manejador. Por ejemplo, dado el fragmento:

handlers:
  console:
    class : logging.StreamHandler
    formatter: brief
    level   : INFO
    filters: [allow_foo]
    stream  : ext://sys.stdout
  file:
    class : logging.handlers.RotatingFileHandler
    formatter: precise
    filename: logconfig.log
    maxBytes: 1024
    backupCount: 3

el manejador con id consola se instancia como logging.StreamHandler, usando sys.stdout como la secuencia subyacente. El manejador con la identificación archivo se instancia como logging.handlers.RotatingFileHandler con los argumentos de la palabra clave filename='logconfig.log', maxBytes=1024, backupCount=3.

loggers: el valor correspondiente será un diccionario en el que cada clave es un nombre de logger y cada valor es un diccionario que describe cómo configurar la instancia de Logger correspondiente.

El diccionario de configuración busca las siguientes claves:

nivel (opcional). El nivel del registrador.

propagar (opcional). La configuración de propagación del registrador.

filtros (opcional). Una lista de identificadores de los filtros para este registrador.

manipuladores (opcional). Una lista de identificadores de los manejadores para este registrador.

Los registradores especificados se configurarán de acuerdo con el nivel, la propagación, los filtros y los manejadores especificados.

root - Esta será la configuración para el registrador root. El procesamiento de la configuración será como para cualquier registrador, excepto que la configuración de propagar no será aplicable.

incremental - si la configuración debe interpretarse como incremental a la configuración existente. Este valor predeterminado es False, lo que significa que la configuración especificada reemplaza la configuración existente con la misma semántica que la utilizada por la API existente fileConfig().

Si el valor especificado es True, la configuración se procesa como se describe en la sección sobre Configuración incremental.

disable_existing_loggers - si se debe deshabilitar cualquier registrador no root existente. Esta configuración refleja el parámetro del mismo nombre en fileConfig(). Si está ausente, este parámetro tiene el valor predeterminado True. Este valor se ignora si incremental es True.

Configuración incremental

Es difícil proporcionar flexibilidad completa para la configuración incremental. Por ejemplo, debido a que los objetos como los filtros y formateadores son anónimos, una vez que se configura una configuración, no es posible hacer referencia a dichos objetos anónimos al aumentar una configuración.

Además, no hay un caso convincente para alterar arbitrariamente el gráfico de objetos de registradores, manejadores, filtros, formateadores en tiempo de ejecución, una vez que se configura una configuración; la verbosidad de los registradores y manejadores se puede controlar simplemente estableciendo niveles (y, en el caso de los registradores, flags de propagación). Cambiar el gráfico de objetos de manera arbitraria y segura es problemático en un entorno de subprocesos múltiples; Si bien no es imposible, los beneficios no valen la complejidad que agrega a la implementación.

Por lo tanto, cuando la tecla incremental de un diccionario de configuración está presente y es True, el sistema ignorará por completo cualquier entrada de formateadores y filtros, y procesará solo el nivel configuraciones en las entradas de manejadores, y las configuraciones de nivel y propagar en las entradas de registradores y raíz.

El uso de un valor en la configuración diccionario permite que las configuraciones se envíen a través del cable como dictados en vinagre a un escucha de socket. Por lo tanto, la verbosidad de registro de una aplicación de larga ejecución puede modificarse con el tiempo sin necesidad de detener y reiniciar la aplicación.

Conexiones de objeto

El esquema describe un conjunto de objetos de registro (registradores, manejadores, formateadores, filtros) que están conectados entre sí en un gráfico de objetos. Por lo tanto, el esquema necesita representar conexiones entre los objetos. Por ejemplo, supongamos que, una vez configurado, un registrador particular le ha adjuntado un manejador particular. A los fines de esta discusión, podemos decir que el registrador representa la fuente y el manejador el destino de una conexión entre los dos. Por supuesto, en los objetos configurados esto está representado por el registrador que tiene una referencia al manejador. En la configuración dict, esto se hace dando a cada objeto de destino una identificación que lo identifica inequívocamente, y luego utilizando la identificación en la configuración del objeto de origen para indicar que existe una conexión entre el origen y el objeto de destino con esa identificación.

Entonces, por ejemplo, considere el siguiente fragmento de YAML:

formatters:
  brief:
    # configuration for formatter with id 'brief' goes here
  precise:
    # configuration for formatter with id 'precise' goes here
handlers:
  h1: #This is an id
   # configuration of handler with id 'h1' goes here
   formatter: brief
  h2: #This is another id
   # configuration of handler with id 'h2' goes here
   formatter: precise
loggers:
  foo.bar.baz:
    # other configuration for logger 'foo.bar.baz'
    handlers: [h1, h2]

(Nota: YAML se usa aquí porque es un poco más legible que el formulario fuente Python equivalente para el diccionario.)

Los identificadores para los registradores son los nombres de los registradores que se utilizarían mediante programación para obtener una referencia a esos registradores, por ejemplo foo.bar.baz. Los identificadores para Formateadores y Filtros pueden ser cualquier valor de cadena (como breve, preciso arriba) y son transitorios, ya que solo son significativos para procesar el diccionario de configuración y se utilizan para determinar conexiones entre objetos , y no persisten en ninguna parte cuando se completa la llamada de configuración.

El fragmento anterior indica que el registrador llamado foo.bar.baz debe tener dos manejadores adjuntos, que se describen mediante los identificadores de manejador h1 y h2. El formateador para h1 es el descrito por identificador brief, y el formateador para h2 es el descrito por identificador precise.

Objetos definidos por el usuario

El esquema admite objetos definidos por el usuario para manejadores, filtros y formateadores. (Los registradores no necesitan tener diferentes tipos para diferentes instancias, por lo que no hay soporte en este esquema de configuración para las clases de registrador definidas por el usuario).

Los objetos a configurar son descritos por diccionarios que detallan su configuración. En algunos lugares, el sistema de registro podrá inferir del contexto cómo se va a instanciar un objeto, pero cuando se va a instanciar un objeto definido por el usuario, el sistema no sabrá cómo hacerlo. Con el fin de proporcionar una flexibilidad completa para la creación de instancias de objetos definidos por el usuario, el usuario debe proporcionar una “fábrica”, una llamada que se llama con un diccionario de configuración y que retorna el objeto instanciado. Esto se indica mediante una ruta de importación absoluta a la fábrica disponible bajo la tecla especial '()'. Aquí hay un ejemplo concreto:

formatters:
  brief:
    format: '%(message)s'
  default:
    format: '%(asctime)s %(levelname)-8s %(name)-15s %(message)s'
    datefmt: '%Y-%m-%d %H:%M:%S'
  custom:
      (): my.package.customFormatterFactory
      bar: baz
      spam: 99.9
      answer: 42

El fragmento de YAML anterior define tres formateadores. El primero, con identificador``breve``, es una instancia estándar logging.Formatter con la cadena de formato especificada. El segundo, con identificador predeterminado, tiene un formato más largo y también define el formato de hora explícitamente, y dará como resultado logging.Formatter inicializado con esas dos cadenas de formato. En forma de fuente Python, los formateadores breve y predeterminado tienen sub-diccionarios de configuración:

{
  'format' : '%(message)s'
}

y:

{
  'format' : '%(asctime)s %(levelname)-8s %(name)-15s %(message)s',
  'datefmt' : '%Y-%m-%d %H:%M:%S'
}

respectivamente, y como estos diccionarios no contienen la clave especial '()', la instanciación se infiere del contexto: como resultado, se crean las instancias estándar logging.Formatter. El sub-diccionario de configuración para el tercer formateador, con identificador personalizado, es:

{
  '()' : 'my.package.customFormatterFactory',
  'bar' : 'baz',
  'spam' : 99.9,
  'answer' : 42
}

y esto contiene la clave especial '()', lo que significa que se desea la creación de instancias definida por el usuario. En este caso, se utilizará la llamada especificada de fábrica especificada. Si es una llamada real, se usará directamente; de lo contrario, si especifica una cadena (como en el ejemplo), la llamada real se ubicará utilizando mecanismos de importación normales. Se llamará al invocable con los elementos restantes en el sub-diccionario de configuración como argumentos de palabras clave. En el ejemplo anterior, se supondrá que el formateador con identificador personalizado será retornado por la llamada:

my.package.customFormatterFactory(bar='baz', spam=99.9, answer=42)

La clave '()' se ha utilizado como clave especial porque no es un nombre de parámetro de palabra clave válido, por lo que no entrará en conflicto con los nombres de los argumentos de palabras clave utilizados en la llamada. El '()' también sirve como mnemónico de que el valor correspondiente es invocable.

Acceso a objetos externos

Hay momentos en que una configuración debe referirse a objetos externos a la configuración, por ejemplo, sys.stderr. Si el diccionario de configuración se construye utilizando el código Python, esto es sencillo, pero surge un problema cuando la configuración se proporciona a través de un archivo de texto (por ejemplo, JSON, YAML). En un archivo de texto, no hay una forma estándar de distinguir sys.stderr de la cadena literal 'sys.stderr'. Para facilitar esta distinción, el sistema de configuración busca ciertos prefijos especiales en valores de cadena y los trata especialmente. Por ejemplo, si la cadena literal 'ext://sys.stderr' se proporciona como un valor en la configuración, entonces la ext:// se eliminará y se procesará el resto del valor utilizando mecanismos normales de importación.

El manejo de dichos prefijos se realiza de manera análoga al manejo del protocolo: existe un mecanismo genérico para buscar prefijos que coincidan con la expresión regular ^(?P<prefix>[a-z]+)://(?P<suffix>.*)$ por el cual, si se reconoce el prefix, el suffix se procesa de manera dependiente del prefijo y el resultado del procesamiento reemplaza el valor de la cadena. Si no se reconoce el prefijo, el valor de la cadena se dejará tal cual.

Acceso a objetos internos

Además de los objetos externos, a veces también es necesario hacer referencia a los objetos en la configuración. El sistema de configuración hará esto implícitamente para las cosas que conoce. Por ejemplo, el valor de cadena 'DEBUG' para un nivel en un registrador o manejador se convertirá automáticamente al valor logging.DEBUG, y los manejadores, Las entradas de filtros y formateador tomarán una identificación de objeto y se resolverán en el objeto de destino apropiado.

Sin embargo, se necesita un mecanismo más genérico para los objetos definidos por el usuario que no conoce el módulo logging. Por ejemplo, considere logging.handlers.MemoryHandler, que toma un argumento target que es otro manejador para delegar. Dado que el sistema ya conoce esta clase, entonces en la configuración, el objetivo dado solo necesita ser la identificación del objeto del manejador de destino relevante, y el sistema resolverá el manejador desde la identificación. Sin embargo, si un usuario define un my.package.MyHandler que tiene un manejador alternativo, el sistema de configuración no sabría que el alternativo se refería a un manejador. Para atender esto, un sistema de resolución genérico permite al usuario especificar:

handlers:
  file:
    # configuration of file handler goes here

  custom:
    (): my.package.MyHandler
    alternate: cfg://handlers.file

La cadena literal 'cfg://handlers.file' se resolverá de manera análoga a las cadenas con el prefijo ext://, pero buscando en la configuración misma en lugar del espacio de nombres de importación. El mecanismo permite el acceso por punto o por índice, de manera similar a la proporcionada por str.format. Por lo tanto, dado el siguiente fragmento:

handlers:
  email:
    class: logging.handlers.SMTPHandler
    mailhost: localhost
    fromaddr: my_app@domain.tld
    toaddrs:
      - support_team@domain.tld
      - dev_team@domain.tld
    subject: Houston, we have a problem.

en la configuración, la cadena 'cfg://handlers' se resolvería al diccionario con la clave handlers, la cadena de caracteres 'cfg://handlers.email se resolvería al diccionario con clave correo electrónico en el diccionario manejadores, y así sucesivamente. La cadena de caracteres 'cfg: //handlers.email.toaddrs [1] se resolvería en 'dev_team.domain.tld' y la cadena de caracteres 'cfg://handlers.email.toaddrs[0] resolvería el valor 'support_team@domain.tld'. Se puede acceder al valor de asunto usando 'cfg://handlers.email.subject' o, de manera equivalente, 'cfg://handlers.email[subject]'. La última forma solo debe usarse si la clave contiene espacios o caracteres no alfanuméricos. Si un valor de índice consta solo de dígitos decimales, se intentará acceder utilizando el valor entero correspondiente, volviendo al valor de cadena si es necesario.

Dada una cadena cfg://handlers.myhandler.mykey.123, esto se resolverá en config_dict['handlers']['myhandler']['mykey']['123']. Si la cadena se especifica como cfg: //handlers.myhandler.mykey[123], el sistema intentará recuperar el valor de config_dict['handlers']['myhandler']['mykey'][123], y vuelva a config_dict['handlers']['myhandler']['mykey']['123'] si eso falla.

Resolución de importación e importadores personalizados

La resolución de importación, por defecto, utiliza la función incorporada __import__() para importar. Es posible que desee reemplazar esto con su propio mecanismo de importación: si es así, puede reemplazar el atributo importer de DictConfigurator o su superclase, la clase BaseConfigurator. Sin embargo, debe tener cuidado debido a la forma en que se accede a las funciones desde las clases a través de descriptores. Si está utilizando un Python invocable para realizar sus importaciones, y lo desea definir a nivel de clase en lugar de a nivel de instancia, debe envolverlo con staticmethod(). Por ejemplo:

from importlib import import_module
from logging.config import BaseConfigurator

BaseConfigurator.importer = staticmethod(import_module)

No necesita envolver con staticmethod() si está configurando la importación invocable en un configurador instance.

Formato de archivo de configuración

El formato del archivo de configuración que entiende fileConfig() se basa en la funcionalidad configparser. El archivo debe contener secciones llamadas [loggers], [handlers] y [formateadores] que identifican por nombre las entidades de cada tipo que se definen en el archivo. Para cada una de esas entidades, hay una sección separada que identifica cómo se configura esa entidad. Por lo tanto, para un registrador llamado log01 en la sección [loggers], los detalles de configuración relevantes se encuentran en una sección [logger_log01]. Del mismo modo, un manejador llamado hand01 en la sección [handlers] tendrá su configuración en una sección llamada [handler_hand01], mientras que un formateador llamado form01 en el [formateadores] sección tendrá su configuración especificada en una sección llamada [formatter_form01]. La configuración del registrador raíz debe especificarse en una sección llamada [logger_root].

Nota

La API fileConfig() es más antigua que la API dictConfig() y no proporciona funcionalidad para cubrir ciertos aspectos del registro. Por ejemplo, no puede configurar objetos Filter, que permiten el filtrado de mensajes más allá de niveles enteros simples, usando fileConfig(). Si necesita tener instancias de Filter en su configuración de registro, deberá usar dictConfig(). Tenga en cuenta que las mejoras futuras a la funcionalidad de configuración se agregarán a dictConfig(), por lo que vale la pena considerar la transición a esta API más nueva cuando sea conveniente hacerlo.

A continuación se dan ejemplos de estas secciones en el archivo.

[loggers]
keys=root,log02,log03,log04,log05,log06,log07

[handlers]
keys=hand01,hand02,hand03,hand04,hand05,hand06,hand07,hand08,hand09

[formatters]
keys=form01,form02,form03,form04,form05,form06,form07,form08,form09

El registrador raíz debe especificar un nivel y una lista de manejadores. A continuación se muestra un ejemplo de una sección de registrador raíz.

[logger_root]
level=NOTSET
handlers=hand01

La entrada de nivel puede ser una de DEBUG, INFO, WARNING, ERROR, CRITICAL o NOTSET. Solo para el registrador raíz, NOTSET significa que todos los mensajes se registrarán. Los valores de nivel son eval()uados en el contexto del espacio de nombres del paquete logging.

La entrada manejadores es una lista separada por comas de nombres de manejadores, que debe aparecer en la sección [manejadores]. Estos nombres deben aparecer en la sección [manejadores] y tener las secciones correspondientes en el archivo de configuración.

Para los registradores que no sean el registrador raíz, se requiere información adicional. Esto se ilustra en el siguiente ejemplo.

[logger_parser]
level=DEBUG
handlers=hand01
propagate=1
qualname=compiler.parser

Las entradas de nivel y manejadores se interpretan como para el registrador raíz, excepto que si el nivel de un registrador no raíz se especifica como NOTSET, el sistema consulta a los registradores más arriba en la jerarquía para determinar el nivel efectivo del registrador. La entrada propagar se establece en 1 para indicar que los mensajes deben propagarse a los manejadores que están más arriba en la jerarquía del registrador, o 0 para indicar que los mensajes no se propagan a los manejadores en la jerarquía superior. La entrada qualname es el nombre jerárquico del canal del registrador, es decir, el nombre utilizado por la aplicación para obtener el registrador.

Las secciones que especifican la configuración del manejador se ejemplifican a continuación.

[handler_hand01]
class=StreamHandler
level=NOTSET
formatter=form01
args=(sys.stdout,)

La entrada class indica la clase del manejador (según lo determinado por eval() en el espacio de nombres del paquete logging). El `` nivel “” se interpreta como para los registradores, y NOTSET se entiende como “registrar todo”.

La entrada formateador indica el nombre clave del formateador para este manejador. Si está en blanco, se utiliza un formateador predeterminado (logging._defaultFormatter). Si se especifica un nombre, debe aparecer en la sección [formateadores] y tener una sección correspondiente en el archivo de configuración.

La entrada args, cuando eval() ua en el contexto del espacio de nombres del paquete logging, es la lista de argumentos para el constructor de la clase de manejador. Consulte los constructores de los manejadores relevantes, o los ejemplos a continuación, para ver cómo se construyen las entradas típicas. Si no se proporciona, el valor predeterminado es ().

La entrada opcional kwargs, cuando eval()úa en el contexto del espacio de nombres del paquete logging, es el argumento de palabra clave diccionario al constructor para la clase de manejador. Si no se proporciona, el valor predeterminado es {}.

[handler_hand02]
class=FileHandler
level=DEBUG
formatter=form02
args=('python.log', 'w')

[handler_hand03]
class=handlers.SocketHandler
level=INFO
formatter=form03
args=('localhost', handlers.DEFAULT_TCP_LOGGING_PORT)

[handler_hand04]
class=handlers.DatagramHandler
level=WARN
formatter=form04
args=('localhost', handlers.DEFAULT_UDP_LOGGING_PORT)

[handler_hand05]
class=handlers.SysLogHandler
level=ERROR
formatter=form05
args=(('localhost', handlers.SYSLOG_UDP_PORT), handlers.SysLogHandler.LOG_USER)

[handler_hand06]
class=handlers.NTEventLogHandler
level=CRITICAL
formatter=form06
args=('Python Application', '', 'Application')

[handler_hand07]
class=handlers.SMTPHandler
level=WARN
formatter=form07
args=('localhost', 'from@abc', ['user1@abc', 'user2@xyz'], 'Logger Subject')
kwargs={'timeout': 10.0}

[handler_hand08]
class=handlers.MemoryHandler
level=NOTSET
formatter=form08
target=
args=(10, ERROR)

[handler_hand09]
class=handlers.HTTPHandler
level=NOTSET
formatter=form09
args=('localhost:9022', '/log', 'GET')
kwargs={'secure': True}

Las secciones que especifican la configuración del formateador se caracterizan por lo siguiente.

[formatter_form01]
format=F1 %(asctime)s %(levelname)s %(message)s
datefmt=
class=logging.Formatter

La entrada format es la cadena de formato general, y la entrada datefmt es una cadena de formato fecha/hora strftime() compatible. Si está vacío, el paquete sustituye algo que es casi equivalente a especificar la cadena de formato de fecha '%Y-%m-%d %H:%M:%S'. Este formato también especifica milisegundos, que se agregan al resultado del uso de la cadena de formato anterior, con un separador de coma. Un ejemplo de tiempo en este formato es 2003-01-23 00:29:50,411.

La entrada clase es opcional. Indica el nombre de la clase del formateador (como módulo de puntos y nombre de clase). Esta opción es útil para crear instancias de una subclase Formatter. Las subclases de Formatter pueden presentar trazas de excepción en un formato expandido o condensado.

Nota

Debido al uso de eval() como se describió anteriormente, existen riesgos potenciales de seguridad que resultan del uso de listen() para enviar y recibir configuraciones a través de sockets. Los riesgos se limitan a donde múltiples usuarios sin confianza mutua ejecutan código en la misma máquina; consulte la documentación de listen() para obtener más información.

Ver también

Módulo logging

Referencia de API para el módulo de registro.

Módulo logging.handlers

Manejadores útiles incluidos con el módulo de registro.

logging.handlers — Gestores de logging

Código fuente Lib/logging/handlers.py [https://github.com/python/cpython/tree/3.9/Lib/logging/handlers.py]

Important

Esta página contiene solo información de referencia. Para tutoriales por favor véase

Tutorial Básico

Tutorial avanzado

Libro de cocina de *Logging*

Estos gestores son muy útiles y están provistos en este paquete. Nota que tres de los gestores de las clases (StreamHandler, FileHandler and NullHandler) están definidos en propio módulo logging pero fueron documentados aquí junto con los otros gestores.

StreamHandler

La clase StreamHandler ubicada en el paquete núcleo logging envía la salida del logging a un stream como sys.stdout, sys.stderr o cualquier objeto tipo archivo (o mas precisamente cualquier objeto que soporte los métodos write() y flush()).

class logging.StreamHandler(stream=None)

Retorna una nueva instancia de la clase StreamHandler. Si stream esta especificado, la instancia lo usará para la salida del registro, sino se usará sys.stderr.

emit(record)

If a formatter is specified, it is used to format the record. The record is then written to the stream followed by terminator. If exception information is present, it is formatted using traceback.print_exception() and appended to the stream.

flush()

Descarga el stream llamando a su método flush(). Nota que el método close() es heredado de la clase Handler y por lo tanto no produce ninguna salida. Por eso muchas veces será necesario invocar al método explícito flush().

setStream(stream)

Establece el stream de la instancia a un valor especifico, si este es diferente. El anterior stream es vaciado antes de que el nuevo stream sea establecido.

Parámetros

stream – El stream que el gestor debe usar.

Devuelve

el anterior stream. si el stream cambió o None si no cambió.

Nuevo en la versión 3.7.

terminator

Cadena utilizada como terminador al escribir un registro formateado en un flujo. El valor por defecto es '\n'.

Si no quieres una terminación de nueva línea, puedes establecer el atributo terminator de la instancia del manejador a la cadena vacía.

En versiones anteriores, el terminador estaba codificado como '\n'.

Nuevo en la versión 3.2.

FileHandler

La clase FileHandler está localizada en el paquete núcleo logging, envía la salida del logging a un archivo de disco. Hereda la funcionalidad de salida de la clase StreamHandler.

class logging.FileHandler(filename, mode='a', encoding=None, delay=False, errors=None)

Returns a new instance of the FileHandler class. The specified file is opened and used as the stream for logging. If mode is not specified, 'a' is used. If encoding is not None, it is used to open the file with that encoding. If delay is true, then file opening is deferred until the first call to emit(). By default, the file grows indefinitely. If errors is specified, it’s used to determine how encoding errors are handled.

Distinto en la versión 3.6: Así como valores de cadena de caracteres, también se aceptan objetos de la clase Path para el argumento «filename».

Distinto en la versión 3.9: The errors parameter was added.

close()

Cierra el archivo.

emit(record)

Da la salida del registro al archivo.

NullHandler

Nuevo en la versión 3.1.

La clase NullHandler está ubicada en el núcleo biblioteca logging . No realiza ningún formateo o salida. Es en esencia un gestor “no-op” para uso de desarrolladores de bibliotecas.

class logging.NullHandler

Retorna una nueva instancia de la clase NullHandler.

emit(record)

Este método no realiza ninguna acción.

handle(record)

Este método no realiza ninguna acción.

createLock()

Este método retorna None para el bloqueo , dado que no hay una E/S subyacente cuyo acceso se necesite serializar.

Véase Configurando Logging para una biblioteca para mas información en como usar la clase NullHandler.

WatchedFileHandler

La clase WatchedFileHandler está ubicada en el módulo logging.handlers, es una clase FileHandler que vigila a que archivo se está enviando el logging. Si el archivo cambia , este se cerrará y se volverá a abrir usando el nombre de archivo.

Puede suceder que haya un cambio de archivo por uso de programas como newsyslog y logrotate que realizan una rotación del archivo log. Este gestor destinado para uso bajo Unix/Linux controla el archivo para ver si hubo cambios desde la última emisión. (Un archivo se considera que cambió si su dispositivo o nodo índice cambió). Si el archivo cambió entonces el anterior stream de archivo se cerrará, y se abrirá el nuevo para obtener un nuevo stream.

Este gestor no es apropiado para uso bajo Windows porque bajo Windows los archivos log abiertos no se pueden mover o renombrar. Logging abre los archivos con bloqueos exclusivos y entonces no hay necesidad de usar el gestor. Por otra parte ST_INO no es soportado bajo Windows. La función stat() siempre retorna cero para este valor.

class logging.handlers.WatchedFileHandler(filename, mode='a', encoding=None, delay=False, errors=None)

Returns a new instance of the WatchedFileHandler class. The specified file is opened and used as the stream for logging. If mode is not specified, 'a' is used. If encoding is not None, it is used to open the file with that encoding. If delay is true, then file opening is deferred until the first call to emit(). By default, the file grows indefinitely. If errors is provided, it determines how encoding errors are handled.

Distinto en la versión 3.6: Así como valores de cadena de caracteres, también se aceptan objetos de la clase Path para el argumento «filename».

Distinto en la versión 3.9: The errors parameter was added.

reopenIfNeeded()

Revisa si el archivo cambió. Si hubo cambio, el stream existente se vacía y cierra y el archivo se abre nuevamente. Típicamente es un precursor para dar salida del registro a un archivo.

Nuevo en la versión 3.6.

emit(record)

Da salida al registro a un archivo, pero primero invoca al método reopenIfNeeded() para reabrir el archivo si es que cambió.

BaseRotatingHandler

La clase BaseRotatingHandler ubicada en el módulo logging.handlers es la clase base para rotar los gestores de archivos de clases RotatingFileHandler y TimedRotatingFileHandler. No debería ser necesario instanciar esta clase, pero tiene métodos y atributos que quizá se necesiten sobrescribir (override).

class logging.handlers.BaseRotatingHandler(filename, mode, encoding=None, delay=False, errors=None)

Los parámetros son como los de la clase FileHandler. Los atributos son:

namer

Si este atributo se establece como invocable, el método rotation_filename() delega a este invocable. Los parámetros pasados al invocable son aquellos pasados al método rotation_filename().

Nota

La función de nombrado es invocada unas cuantas veces durante el volcado (rollover) , entonces debe ser tan simple y rápida como sea posible. Debe también retornar siempre la misma salida para una misma entrada, de otra manera el volcado puede no funcionar como se espera.

It’s also worth noting that care should be taken when using a namer to preserve certain attributes in the filename which are used during rotation. For example, RotatingFileHandler expects to have a set of log files whose names contain successive integers, so that rotation works as expected, and TimedRotatingFileHandler deletes old log files (based on the backupCount parameter passed to the handler’s initializer) by determining the oldest files to delete. For this to happen, the filenames should be sortable using the date/time portion of the filename, and a namer needs to respect this. (If a namer is wanted that doesn’t respect this scheme, it will need to be used in a subclass of TimedRotatingFileHandler which overrides the getFilesToDelete() method to fit in with the custom naming scheme.)

Nuevo en la versión 3.3.

rotator

Si este atributo se estableció como invocable, el método rotate() delega a este invocable. Los parámetros pasados al invocable son aquellos pasados al método rotate().

Nuevo en la versión 3.3.

rotation_filename(default_name)

Modifica el nombre de un archivo log cuando esta rotando.

Esto esta previsto para que pueda usarse un nombre de archivo personalizado.

La implementación por defecto llama al atributo “namer” del gestor, si este es invocable, pasando el nombre por defecto a él. Si el atributo no es invocable (por defecto es None) el nombre se retorna sin cambios.

Parámetros

default_name – El nombre por defecto para el archivo de log.

Nuevo en la versión 3.3.

rotate(source, dest)

Cuando está rotando, rotar el actual log.

La implementación por defecto llama al atributo “rotator” del gestor, si es invocable, pasando los argumentos de origen y destino a él. Si no se puede invocar (porque el atributo por defecto es “None”) el origen es simplemente renombrado al destino.

Parámetros

source – El nombre de archivo origen . Normalmente el nombre de archivo base, por ejemplo “test.log”.

dest – El nombre de archivo de destino. Normalmente es el nombre al que se rota el archivo origen por ejemplo “test.log.1”.

Nuevo en la versión 3.3.

La razón de que existen los atributos es para evitar tener que usar una subclase - puedes usar los mismos invocadores para instancias de clase RotatingFileHandler y TimedRotatingFileHandler. Si el rotador invocable o la función de nombrado plantean una excepción esta se manejará de la misma manera que cualquier otra excepción durante una llamada al método emit() por ejemplo a través del método handleError() del gestor.

Si necesitas hacer cambios mas significativos al proceso de rotación puedes obviar los métodos.

Para un ejemplo véase Usar un rotador y un nombre para personalizar el procesamiento de rotación de log.

RotatingFileHandler

La clase RotatingFileHandler, localizada en el módulo logging.handlers soporta la rotación de archivos log de disco.

class logging.handlers.RotatingFileHandler(filename, mode='a', maxBytes=0, backupCount=0, encoding=None, delay=False, errors=None)

Returns a new instance of the RotatingFileHandler class. The specified file is opened and used as the stream for logging. If mode is not specified, 'a' is used. If encoding is not None, it is used to open the file with that encoding. If delay is true, then file opening is deferred until the first call to emit(). By default, the file grows indefinitely. If errors is provided, it determines how encoding errors are handled.

Se pueden usar los valores maxBytes y backupCount para permitir que el archivo rollover tenga un tamaño predeterminado. Cuando el tamaño del archivo está a punto de excederse, se cerrará y un nuevo archivo se abrirá silenciosamente para salida. El volcado (rollover) ocurre cada vez que el actual archivo log esta cerca de maxBytes en tamaño , pero si cualquiera maxBytes o backupCount es cero, el volcado (rollover) no ocurre. Por eso generalmente necesitas establecer backupCount por lo menos en 1 y no tener cero en maxBytes. Cuando backupCount no es cero, el sistema guardará los anteriores archivos log agregando las extensiones “.1”, “.2” etc. al nombre del archivo. Por ejemplo con un backupCount de 5 y un nombre de archivo base de app.log, tendrás como nombre de archivo t app.log, app.log.1, app.log.2, hasta app.log.5. El archivo que esta siendo escrito es siempre app.log. Cuando este se completa , se cierra y se renombra a app.log.1 y si ya existen app.log.1, app.log.2, etc. Entonces se renombrará como app.log.2, app.log.3 etc. respectivamente.

Distinto en la versión 3.6: Así como valores de cadena de caracteres, también se aceptan objetos de la clase Path para el argumento «filename».

Distinto en la versión 3.9: The errors parameter was added.

doRollover()

Realiza un volcado (rollover) como se describe arriba.

emit(record)

Da la salida del registro al archivo , dando suministro para el volcado (rollover) como está descripto anteriormente.

TimedRotatingFileHandler

La clase TimedRotatingFileHandler está ubicada en el módulo logging.handlers. Soporta la rotación de archivos de log a ciertos intervalos de tiempo.

class logging.handlers.TimedRotatingFileHandler(filename, when='h', interval=1, backupCount=0, encoding=None, delay=False, utc=False, atTime=None, errors=None)

Retorna una nueva instancia de la clase TimedRotatingFileHandler . El archivo especificado es abierto y usado como stream para el historial de log. En la rotación también establece el sufijo del nombre de archivo. La rotación ocurre basada en el producto de when y interval.

Puedes usar el when para especificar el tipo de intervalo interval. La lista de posibles valores esta debajo. Nota que no distingue mayúsculas y minúsculas.

Valor

Tipo de intervalo

Si/como atTime es usado

'S'

Segundos

Ignorado

'M'

Minutos

Ignorado

'H'

Horas

Ignorado

'D'

Días

Ignorado

'W0'-'W6'

Día de la semana (0=Lunes)

Usado para calcular la hora inicial del volcado rollover

'midnight'

Volcado (rollover) a medianoche , si atTime no está especificado, sino el volcado se hará atTime

Usado para calcular la hora inicial del volcado rollover

Cuando se usa rotación basada en día de la semana, especifica “W0” para Lunes, “W1” para Martes y así, hasta “W6” para Domingo. en este caso el valor pasado para Interval no se usa.

El sistema guardará los archivos de log anteriores agregándoles extensiones al nombre de archivo. Las extensiones están basadas en día-hora usando el formato %Y-%m-%d_%H-%M-%S o un prefijo respecto el intervalo del volcado (rollover).

Cuando se calcula la hora del siguiente volcado (rollover) por primera vez (cuando el gestor es creado), la última hora de modificación de un archivo log existente o sino la hora actual, se usa para calcular cuando será la próxima rotación.

Si el argumento utc es true se usará la hora en UTC, sino se usará la hora local.

Si backupCount no es cero, se conservará como máximo una cantidad de archivos especificada en backupCount,y si son creados más, cuando ocurre el volcado (rollover) se borrará el último. La lógica de borrado usa el intervalo para determinar que archivos borrar, pues entonces cambiando el intervalo puede dejar viejos archivos abandonados.

Si delay es true entonces la apertura del archivo se demorará hasta la primer llamada a emit().

Si atTime no es «None», debe haber una instancia datetime.time que especifica la hora que ocurre el volcado (rollover) , para los casos en que el volcado esta establecido para ocurrir «a medianoche» o «un día en particular». Nótese que en estos casos el valor atTime se usa para calcular el valor initial del volcado (rollover) y los subsecuentes volcados serán calculados a través del calculo normal de intervalos.

Si se especifica errors, se utiliza para determinar cómo se manejan los errores de codificación.

Nota

El cálculo de la hora en que se realizara el volcado (rollover) inicial cuando se inicializa el gestor. El cálculo de la hora de los siguientes volcados (rollovers) se realiza solo cuando este ocurre, y el volcado ocurre solo cuando se emite una salida. Si esto no se tiene en cuenta puede generar cierta confusión. Por ejemplo si se establece un intervalo de «cada minuto» eso no significa que siempre se verán archivos log con hora (en el nombre del archivo) separados por un minuto. Si durante la ejecución de la aplicación el logging se genera con mayor frecuencia que un minuto entonces se pueden esperar archivos log separados por un minuto. Si por otro lado los mensajes logging son establecidos cada digamos cinco minutos, entonces habrá brechas de tiempo en los archivos correspondientes a los minutos que no hubo salida (y no ocurrió por tanto volcado alguno).

Distinto en la versión 3.4: Se agregó el parámetro atTime.

Distinto en la versión 3.6: Así como valores de cadena de caracteres, también se aceptan objetos de la clase Path para el argumento «filename».

Distinto en la versión 3.9: The errors parameter was added.

doRollover()

Realiza un volcado (rollover) como se describe arriba.

emit(record)

Da la salida del registro a un archivo , proveyendo la información para el volcado (rollover) como esta descripto anteriormente.

getFilesToDelete()

Returns a list of filenames which should be deleted as part of rollover. These are the absolute paths of the oldest backup log files written by the handler.

SocketHandler

La clase SocketHandler esta localizada en el módulo logging.handlers, envía el logging a un socket de la red. La clase base usa sockets TCP.

class logging.handlers.SocketHandler(host, port)

Retorna una nueva instancia de la clase SocketHandler destinada para comunicarse con una terminal remota cuya dirección esta dada por host y port.

Distinto en la versión 3.4: Si «port» se especifica como``None`` se crea un socket de dominio Unix, usando el valor en``host`` - de otra manera se creará un socket TCP.

close()

Cierra el socket.

emit()

Serializa (Pickles) el registro del diccionario de atributos y lo escribe en el socket en formato binario. Si hay un error con el socket, silenciosamente descarta el paquete. Si la conexión se perdió previamente, la restablece. Para deserializar (unpickle) un registro en el extremo receptor a una clase LogRecord, usa la función makeLogRecord().

handleError()

Maneja un error que ocurrió durante el método emit(). La causa mas común es una perdida de conexión. Cierra el socket para que podamos reintentar en el próximo evento.

makeSocket()

Este es un método patrón que permite subclases para definir el tipo preciso de socket que se necesita. La implementación por defecto crea un socket TCP(socket.SOCK_STREAM).

makePickle(record)

Serializa (pickles) el registro del diccionario de atributos en formato binario con un prefijo de tamaño, y lo retorna listo para transmitir a través del socket. Los detalles de esta operación son equivalentes a:

data = pickle.dumps(record_attr_dict, 1)
datalen = struct.pack('>L', len(data))
return datalen + data

Nota que los serializados (pickles) no son totalmente seguros. Si te preocupa la seguridad desearás evitar este método para implementar un mecanismo mas seguro. Por ejemplo puedes firmar pickles usando HMAC y verificarlos después en el extremo receptor. O alternativamente puedes deshabilitar la deserialización (unpickling) de objetos globales en el extremo receptor.

send(packet)

Envía un paquete serializado (pickled) de cadena de caracteres al socket. El formato de la cadena de bytes enviada es tal como se describe en la documentación de makePickle().

Esta función permite envíos parciales, que pueden ocurrir cuando la red esta ocupada.

createSocket()

Intenta crear un socket, si hay una falla usa un algoritmo de marcha atrás exponencial. En el fallo inicial el gestor desechará el mensaje que intentaba enviar. Cuando los siguientes mensajes sean gestionados por la misma instancia no intentará conectarse hasta que haya transcurrido cierto tiempo. Los parámetros por defecto son tales que el retardo inicial es un segundo y si después del retardo la conexión todavía no se puede realizar, el gestor doblará el retardo cada vez hasta un máximo de 30 segundos.

Este comportamiento es controlado por los siguientes atributos del gestor:

retryStart (retardo inicial por defecto 1.0 segundos)

retryFactor (multiplicador por defecto 2.0)

retryMax (máximo retardo por defecto 30.0 segundos)

Esto significa que si el oyente remoto (listener) comienza después de que se usó el gestor , pueden perderse mensajes (dado que el gestor no puede siquiera intentar una conexión hasta que se haya cumplido el retardo, y silenciosamente desechará los mensajes mientras se cumpla el retardo).

DatagramHandler

La clase DatagramHandler está ubicada en el módulo logging.handlers, hereda de la clase SocketHandler para realizar el soporte de mensajes logging por los sockets UDP.

class logging.handlers.DatagramHandler(host, port)

Retorna una nueva instancia de la clase DatagramHandler destinada para comunicarse con la terminal remota cuya dirección es dada por host y port.

Distinto en la versión 3.4: Si “port” se especifica como «None», se crea un socket de dominio Unix, usando el valor en «host» - de otra manera se crea un socket UDP.

emit()

Serializa (pickles) el registro del diccionario de atributos y lo escribe en el socket en formato binario. Si hay un error con el socket, silenciosamente desecha el paquete. Para deserializar (unpickle) el registro en el extremo de recepción a una clase LogRecord, usa la función makeLogRecord().

makeSocket()

El método original de la clase SocketHandler se omite para crear un socket UDP (socket.SOCK_DGRAM).

send(s)

Enviar una cadena de caracteres serializada (pickled) a un socket de red. El formato de la cadena de bytes enviado es tal como se describe en la documentación para SocketHandler.makePickle().

Gestor SysLog (SysLogHandler)

La clase SysLogHandler está ubicada en el módulo logging.handlers. Realiza el soporte de los mensajes de logging a un syslog Unix local o remoto.

class logging.handlers.SysLogHandler(address=('localhost', SYSLOG_UDP_PORT), facility=LOG_USER, socktype=socket.SOCK_DGRAM)

Retorna una nueva instancia de la clase SysLogHandler concebida para comunicarse con una terminal remota Unix cuya dirección esta dada por address en la forma de una tupla (host, port) . Si address no se especifica se usará ('localhost', 514). La dirección se usa para abrir el socket. Una alternativa a consignar una tupla (host, port) es proveer una dirección como cadena de caracteres, por ejemplo “/dev/log”. En este caso se usa un socket de dominio Unix para enviar el mensaje al syslog. Si facility no se especifica se usara LOG_USER . El tipo de socket abierto usado depende del argumento socktype , que por defecto es socket.SOCK_DGRAM y por lo tanto abre un socket UDP . Para abrir un socket TCP (para usar con los nuevos daemons syslog como rsyslog) se debe especificar un valor de socket.SOCK_STREAM.

Nótese que si el servidor no esta escuchando el puerto UDP 514, la clase SysLogHandler puede parecer no funcionar. En ese caso chequea que dirección deberías usar para un socket de dominio . Es sistema-dependiente. Por ejemplo en Linux generalmente es “/dev/log” pero en OS/X es “/var/run/syslog”. Será necesario chequear tu plataforma y usar la dirección adecuada (quizá sea necesario realizar este chequeo mientras corre la aplicación si necesita correr en diferentes plataformas). En Windows seguramente tengas que usar la opción UDP.

Distinto en la versión 3.2: Se agregó socktype.

close()

Cierra el socket del host remoto.

emit(record)

El registro es formateado, y luego enviado al servidor syslog. Si hay información de excepción presente entonces no se enviará al servidor.

Distinto en la versión 3.2.1: (Véase el bpo-12168 [https://bugs.python.org/issue?@action=redirect&bpo=12168].) En versiones anteriores , los mensajes enviados a los daemons syslog siempre terminaban con un byte NUL ya que versiones anteriores de estos daemons esperaban un mensaje NUL de terminación. Incluso a pesar que no es relevante la especificación (RFC 5424 [https://tools.ietf.org/html/rfc5424.html]). Versiones mas recientes de estos daemons no esperan el byte NUL pero lo quitan si esta ahí. Versiones aún mas recientes que están mas cercanas a la especificación RFC 5424 pasan el byte NUL como parte del mensaje.

Para habilitar una gestión mas sencilla de los mensajes syslog respecto de todos esos daemons de diferentes comportamientos el agregado del byte NUL es configurable a través del uso del atributo de nivel de clase append_nul. Este es por defecto “True (preservando el comportamiento ya existente) pero se puede establecer a “False” en una instancia SysLogHandler como para que esa instancia no añada el terminador NUL.

Distinto en la versión 3.3: (Véase: issue “12419”) en versiones anteriores, no había posibilidades para un prefijo “ident” o “tag” para identificar el origen del mensaje. Esto ahora se puede especificar usando un atributo de nivel de clase, que por defecto será «””» para preservar el comportamiento existente , pero puede ser sorteado en una instancia SysLogHandler para que esta instancia anteponga el ident a todos los mensajes gestionados. Nótese que el ident provisto debe ser texto, no bytes y se antepone al mensaje tal como es.

encodePriority(facility, priority)

Codifica la funcionalidad y prioridad en un entero. Puedes pasar cadenas de caracteres o enteros, si pasas cadenas de caracteres se usarán los diccionarios de mapeo interno para convertirlos en enteros.

Los valores simbólicos LOG_ están definidos en SysLogHandler e invierten los valores definidos en el archivo de encabezado sys/syslog.h`.

Prioridades

Nombre (cadena de caracteres)

Valor simbólico

alert

LOG_ALERT

crit or critical

LOG_CRIT

debug

LOG_DEBUG

emerg or panic

LOG_EMERG

err or error

LOG_ERR

info

LOG_INFO

notice

LOG_NOTICE

warn o warning

LOG_WARNING

Facilities

Nombre (cadena de caracteres)

Valor simbólico

auth

LOG_AUTH

authpriv

LOG_AUTHPRIV

cron

LOG_CRON

daemon

LOG_DAEMON

ftp

LOG_FTP

kern

LOG_KERN

lpr

LOG_LPR

mail

LOG_MAIL

news

LOG_NEWS

syslog

LOG_SYSLOG

user

LOG_USER

uucp

LOG_UUCP

local0

LOG_LOCAL0

local1

LOG_LOCAL1

local2

LOG_LOCAL2

local3

LOG_LOCAL3

local4

LOG_LOCAL4

local5

LOG_LOCAL5

local6

LOG_LOCAL6

local7

LOG_LOCAL7

mapPriority(levelname)

Mapea un nombre de nivel logging a un nombre de prioridad syslog. Puedes necesitar omitir esto si estas usando niveles personalizados, o si el algoritmo por defecto no es aplicable a tus necesidades. El algoritmo por defecto mapea DEBUG, INFO, WARNING, ERROR y CRITICAL a sus nombres equivalentes syslog, y todos los demás nombres de nivel a “warning”.

Gestor de eventos NTELog (NTEventLogHandler)

La clase NTEventLogHandler esta localizada en el módulo logging.handlers, soporta el envío de mensajes de logging a un log de eventos local Windows NT, Windows 2000 o Windows XP. Antes de que puedas usarlo, necesitarás tener instaladas las extensiones de Win32 de Mark Hammond para Python.

class logging.handlers.NTEventLogHandler(appname, dllname=None, logtype='Application')

Retorna una nueva instancia de la clase NTEventLogHandler la appname se usa para definir el nombre de la aplicación tal como aparece en el log de eventos. Se crea una entrada de registro apropiada usando este nombre. El dllname debe dar la ruta completa calificada de un .dll o .exe que contiene definiciones de mensaje para conservar en el log. (si no esta especificada, se usara 'win32service.pyd' esto es instalado con las extensiones de Win32 y contiene algunas definiciones básicas de mensajes de conservación de lugar. Nótese que el uso de estos conservadores de lugar harán tu log de eventos extenso, dado que el origen completo del mensaje es guardado en el log. Si quieres logs menos extensos deberás pasar el nombre de tu propio .dll o .exe que contiene la definición de mensajes que quieres usar en el log. El logtype puede ser de 'Application', 'System' or 'Security' y sino por defecto será de 'Application'.

close()

Llegado a este punto puedes remover el nombre de aplicación del registro como origen de entrada de log de eventos. Sin embargo si haces esto no te será posible ver los eventos tal como has propuesto en el visor del log de eventos - necesita ser capaz de acceder al registro para tomar el nombre .dll. Esto no lo hace la versión actual.

emit(record)

Determina el ID del mensaje, categoría y tipo de evento y luego registra el mensaje en el log de eventos NT.

getEventCategory(record)

Retorna la categoría de evento del registro. Evita esto si quieres especificar tus propias categorías. Esta versión retorna 0.

getEventType(record)

Retorna el tipo de evento del registro. Haz caso omiso de esto si quieres especificar tus propios tipos. Esta versión realiza un mapeo usando el atributo typemap del gestor, que se establece en __init__() a un diccionario que contiene mapeo para DEBUG, INFO, WARNING, ERROR y CRITICAL. Si estas usando tus propios niveles, necesitarás omitir este método o colocar un diccionario a medida en el atributo typemap del gestor.

getMessageID(record)

Retorna el ID de mensaje para el registro. Si estas usando tus propios mensajes, podrás hacerlo pasando el msg al logger siendo un ID mas que un formato de cadena de caracteres. Luego aquí puedes usar una búsqueda de diccionario para obtener el ID de mensaje. Esta versión retorna 1, que es el ID de mensaje base en win32service.pyd.

SMTPHandler

La clase SMTPHandler esta ubicada en el módulo logging.handlers y soporta el envío de mensajes de logging a un a dirección de correo electrónico a través de SMTP.

class logging.handlers.SMTPHandler(mailhost, fromaddr, toaddrs, subject, credentials=None, secure=None, timeout=1.0)

Retorna una nueva instancia de la clase SMTPHandler . Esta instancia se inicializa con la dirección de: y para: y asunto: del correo electrónico. El toaddrs debe ser una lista de cadena de caracteres. Para especificar un puerto SMTP no estandarizado usa el formato de tupla (host, puerto) para el argumento mailhost. Si usas una cadena de caracteres, se utiliza el puerto estándar SMTP. Si tu servidor SMTP necesita autenticación, puedes especificar una tupla (usuario, contraseña) para el argumento de credentials.

Para especificar el uso de un protocolo de seguridad (TLS), pasa una tupla al argumento secure. Esto solo se utilizará cuando sean provistas las credenciales de autenticación. La tupla deberá ser una tupla vacía o una tupla con único valor con el nombre de un archivo-clave keyfile, o una tupla de 2 valores con el nombre del archivo-clave keyfile y archivo certificado. (Esta tupla se pasa al método smtplib.SMTP.starttls() method.).

Se puede especificar un tiempo de espera para comunicación con el servidor SMTP usando el argumento timeout.

Nuevo en la versión 3.3: Se agregó el argumento timeout.

emit(record)

Formatea el registro y lo envía a las direcciones especificadas.

getSubject(record)

Si quieres especificar una línea de argumento que es registro-dependiente, sobrescribe (override) este método.

MemoryHandler

La clase MemoryHandler esta ubicada en el módulo logging.handlers .Soporta el almacenamiento temporal de registros logging en memoria. Periódicamente los descarga al gestor target. Esto ocurre cuando el búfer está lleno o cuando ocurre un evento de cierta importancia.

MemoryHandler es una subclase de la clase mas general BufferingHandler, que es una clase abstracta. Este almacena temporalmente registros logging en la memoria. Cada vez que un registro es agregado al búfer, se realiza una comprobación llamando al método shouldFlush() para ver si dicho búfer debe ser descargado. Si debiera, entonces el método flush() se espera que realice la descarga.

class logging.handlers.BufferingHandler(capacity)

Inicializa el gestor con un búfer de una capacidad especifica. Aquí capacidad significa el número de registros logging en el almacenamiento temporal.

emit(record)

Añade un registro al búfer. Si el método shouldFlush() retorna true , entonces llama al método flush() para procesar el búfer.

flush()

Puedes sobrescribir (override) esto para implementar un comportamiento “a medida” de la descarga. Esta versión solo vacía el búfer.

shouldFlush(record)

Retorna True si el búfer tiene aún capacidad. Este método puede ser omitido para implementar estrategias a medida de vaciado.

class logging.handlers.MemoryHandler(capacity, flushLevel=ERROR, target=None, flushOnClose=True)

Retorna una nueva instancia de la clase MemoryHandler . La instancia se inicializa con un búfer del tamaño capacity. Si el flushLevel no se especifica, se usará ERROR . Si no se especifica target el objetivo deberá especificarse usando el método setTarget() -Antes de esto el gestor no realizará nada útil. Si se especifica flushOnClose como False, entonces el búfer no se vaciará cuando el gestor se cierra. Si no se especifica o se especifica como True, el comportamiento previo de vaciado del búfer sucederá cuando se cierre el gestor.

Distinto en la versión 3.6: Se añadió el parámetro flushOnClose.

close()

Invoca al método flush() y establece el objetivo a “None” y vacía el búfer.

flush()

Para la clase MemoryHandler el vaciado significa simplemente enviar los registros del búfer al objetivo, si es que hay uno. El búfer además se vacía cuando esto ocurre. Sobrescribe (override) si deseas un comportamiento diferente.

setTarget(target)

Establece el gestor de objetivo para este gestor.

shouldFlush(record)

Comprueba si el búfer esta lleno o un registro igual o mas alto que flushLevel.

HTTPHandler

La clase HTTPHandler está ubicada en el módulo logging.handlers.Soporta el envío de mensajes logging a un servidor Web, usando la semántica GET o POST`.

class logging.handlers.HTTPHandler(host, url, method='GET', secure=False, credentials=None, context=None)

Retorna una nueva instancia de la clase HTTPHandler. el host puede ser de la forma «host:puerto», y necesitarás usar un numero de puerto especifico. Si no se especifica method se usará GET . Si secure es true se usará una conexión HTTPS. El parámetro context puede establecerse a una instancia ssl.SSLContext para establecer la configuración de SSL usado en la conexión HTTPS. Si se especifica credentials debe ser una tupla doble, consistente en usuario y contraseña, que se colocará en un encabezado de autorización HTTP usando autenticación básica. Si especificas credenciales también deberás especificar secure=True así tu usuario y contraseña no son pasados como texto en blanco por la conexión.

Distinto en la versión 3.5: Se agregó el parámetro context.

mapLogRecord(record)

Provee un diccionario, basado en record para ser codificado en forma URL y enviado al servidor web. La implementación por defecto retorna record.__dict__. Este método puede omitirse si por ejemplo solo se enviará al servidor web un subconjunto de la clase LogRecord o si se requiere enviar al servidor algo mas específico.

emit(record)

Envía el registro al servidor Web como un diccionario con codificación URL. Se usa el método mapLogRecord() para convertir el registro al diccionario que debe ser enviado.

Nota

Dado que preparar un registro para enviar a un servidor Web no es lo mismo que una operación genérica de formato, usando el método setFormatter() para especificar una clase Formatter por una clase HTTPHandler no tiene efecto. En vez de llamar al método format() este gestor llama al método mapLogRecord() y después a la función urllib.parse.urlencode() para codificar el diccionario en una forma que sea adecuada para enviar a un servidor Web.

QueueHandler

Nuevo en la versión 3.2.

La clase QueueHandler localizada en el módulo logging.handlers soporta el envío de mensajes de logging a una cola, tal como los implementados en los módulos queue o multiprocessing .

Junto con la clase QueueListener la clase QueueHandler puede usarse para permitir a los gestores realizar su tarea en un hilo separado del que realiza el logging. Esto es importante en aplicaciones Web y también otras aplicaciones donde los clientes servidos por los hilos necesitan responder tan rápido como sea posible, mientras que cualquier operación potencialmente lenta (tal como enviar un correo electrónico a través la clase SMTPHandler) se realizan por un hilo diferente.

class logging.handlers.QueueHandler(queue)

Retorna una nueva instancia de la clase QueueHandler. La instancia se inicializa con la cola a la que se enviarán los mensajes. La cola puede ser cualquier objeto tipo-cola; es usado tal como por el método enqueue() que necesita saber como enviar los mensajes a ella. La cola no es requerida para tener una API de rastreo de tareas, lo que significa que puedes usar instancias de SimpleQueue como queue.

emit(record)

Pone en la cola el resultado de preparar el registro historial de log. Si ocurre una excepción (por ejemplo por que una cola de destino se llenó) entonces se llama al método handleError(). Esto puede resultar en que el registro se descarte (si logging.raiseExceptions es False) o que se imprima un mensaje a sys.stderr (si logging.raiseExceptions es True).

prepare(record)

Prepara un registro para poner en la cola. El objeto que retorna este método se colocará en cola.

La implementación base da formato al registro para unir la información de los mensajes, argumentos y excepciones, si están presentes. También remueve los elementos que no se pueden serializar (unpickleables) de los registros in-situ.

Puedes querer hacer caso omiso de este método si quieres convertir el registro en un diccionario o cadena de caracteres JSON, o enviar una copia modificada del registro mientras dejas el original intacto.

enqueue(record)

Coloca en la cola al registro usando put_nowait(); puede que quieras sobrescribe (override) esto si quieres usar una acción de bloqueo, o un tiempo de espera, o una implementación de cola a medida.

QueueListener

Nuevo en la versión 3.2.

La clase QueueListener esta localizada en el módulo logging.handlers. Soporta la recepción de mensajes logging de una cola, tal como los implementados en los módulos queue or multiprocessing . Los mensajes son recibidos de una cola en un hilo interno y se pasan en el mismo hilo, a uno o mas gestores para procesarlos. Mientras la clase QueueListener no es en si misma un gestor, esta documentada aquí porque trabaja mano a mano con la clase QueueHandler.

Junto con la clase QueueHandler , la clase QueueListener puede usarse para permitir a los gestores hacer su labor en un hilo separado del que hace el logging. Esto es importante en aplicaciones Web y también otras aplicaciones de servicio donde los clientes servidos por los hilos necesitan una respuesta tan rápida como sea posible, mientras cualquier operación potencialmente lenta (tal como enviar un correo electrónico a través de la clase SMTPHandler) son atendidas por un hilo diferente.

class logging.handlers.QueueListener(queue, *handlers, respect_handler_level=False)

Retorna una nueva instancia de la clase QueueListener. La instancia se inicializa con la cola para enviar mensajes a una lista de gestores que manejarán entradas colocadas en la cola. La cola puede ser cualquier objeto de tipo-cola, es usado tal como está por el método dequeue() que necesita saber como tomar los mensajes de esta. La cola no es obligatoria para tener la API de seguimiento de tareas (aunque se usa si está disponible), lo que significa que puede usar instancias SimpleQueue para queue.

Si respect_handler_level es True, se respeta un nivel de gestor (comparado con el nivel del mensaje) cuando decide si pasar el mensajes al gestor; de otra manera, el comportamiento es como en versiones anteriores de Python - de pasar cada mensaje a cada gestor.

Distinto en la versión 3.5: Se agregó el argumento respect_handler_levels.

dequeue(block)

Extrae de la cola un registro y lo retorna, con opción a bloquearlo.

La implementación base usa get(). Puedes sobrescribir (override) este método si quieres usar tiempos de espera o trabajar con colas implementadas a medida.

prepare(record)

Prepara un registro para ser gestionado.

Esta implementación solo retorna el registro que fue pasado. Puedes sobrescribir (override) este método para hacer una serialización a medida o una manipulación del registro antes de pasarlo a los gestores.

handle(record)

Manejar un registro.

Esto solo realiza un bucle a través de los gestores ofreciéndoles el registro para ser gestionado. El objeto actual pasado a los gestores es aquel que es retornado por el método prepare().

start()

Da comienzo al oyente (listener).

Esto da comienzo a un hilo en segundo plano para supervisar la cola de registros log a procesar.

stop()

Detiene el oyente (listener).

Esto solicita terminar al hilo, y luego espera hasta que termine. Nota que si no llamas a esto antes de que tu aplicación salga, puede haber algunos registros que aun están en la cola, que no serán procesados.

enqueue_sentinel()

Escribe un centinela (sentinel) en la cola para decir al oyente (listener) de salir. Esta implementación usa put_nowait(). Puedes sobrescribir (override) este método si quieres usar tiempos de espera o trabajar con implementaciones de cola a tu medida.

Nuevo en la versión 3.3.

Ver también

Módulo logging

Referencia API para el módulo de logging.

Módulo logging.config

Configuración API para el módulo de logging.

getpass — Entrada de contraseña portátil

Código fuente: Lib/getpass.py [https://github.com/python/cpython/tree/3.9/Lib/getpass.py]

El módulo getpass proporciona dos funciones:

getpass.getpass(prompt='Password: ', stream=None)

Solicita al usuario una contraseña sin hacer eco. Se solicita al usuario mediante la cadena prompt, que por defecto es 'Password: '. En Unix, el indicador se escribe en el objeto similar a un archivo stream usando el controlador de errores de reemplazo si es necesario. stream toma por defecto el terminal de control (/dev/tty) o si no está disponible para sys.stderr (este argumento se ignora en Windows).

Si la entrada sin echo no está disponible, getpass() recurre a imprimir un mensaje de advertencia en stream y leer de sys.stdin y lanza un GetPassWarning.

Nota

Si llama a getpass desde IDLE, la entrada puede realizarse en la terminal desde la que inició IDLE en lugar de en la ventana inactiva en sí.

exception getpass.GetPassWarning

Una subclase UserWarning lanzada cuando la entrada de la contraseña puede repetirse.

getpass.getuser()

Retorna el «nombre de inicio de sesión» del usuario.

Esta función verifica las variables de entorno LOGNAME, USER, LNAME and USERNAME, en orden, y retorna el valor del primero que se establece en un cadena no vacía. Si no se establece ninguno, el nombre de inicio de sesión de la base de datos de contraseñas se retorna en los sistemas que admiten el módulo pwd; de lo contrario, se lanza una excepción.

En general, esta función debería preferirse respecto a os.getlogin().

curses — Manejo de terminales para pantallas de celdas de caracteres

El módulo curses provee una interfaz para la librería curses, el estándar para el manejo avanzado de terminales portátiles.

Mientras que curses es más ampliamente usado en los ambientes Unix, las versiones están disponibles para Windows, DOS, y posiblemente para otros sistemas también. Esta extensión del módulo es diseñada para coincidir con el API de ncurses, una librería de código abierto almacenada en Linux y las variantes BSD de Unix.

Nota

Cuando la documentación menciona un carácter, esto puede ser especificado como un entero, una cadena Unicode de un carácter o una cadena de bytes de un byte.

Cuando la documentación menciona una cadena de caracteres, esto puede ser especificado como una cadena Unicode o una cadena de bytes.

Nota

Desde la versión 5.4, la librería ncurses decide cómo interpretar los datos no ASCII usando la función nl_langinfo. Eso significa que tú tienes que llamar a locate.setlocate() en la aplicación y codificar las cadenas Unicode usando una de las codificaciones disponibles del sistema. Este ejemplo usa la codificación del sistema por defecto:

import locale
locale.setlocale(locale.LC_ALL, '')
code = locale.getpreferredencoding()

Entonces usa code como la codificación para las llamadas str.encode().

Ver también

Módulo curses.ascii

Utilidades para trabajar con caracteres ASCII, independientemente de tu configuración local.

Módulo curses.panel

Una extensión de la pila de paneles que añade profundidad a las ventanas de curses.

Módulo curses.textpad

Widget de texto editable para apoyar curses Emacs- como enlaces.

Programación de Curses con Python

Material del tutorial usando curses con Python, por Andrew Kuchling y Eric Raymond.

El directorio Tools/demo/ [https://github.com/python/cpython/tree/3.9/Tools/demo/] en el recurso de distribución de Python contiene algunos programas de ejemplo usando los enlaces de curses previstos en este módulo.

Funciones

El módulo curses define la siguiente excepción:

exception curses.error

Una excepción se lanza cuando una función de la librería curses retorna un error.

Nota

Cuando los argumentos x o y para una función o un método son opcionales, se predetermina la ubicación actual del cursor. Cuando attr es opcional, por defecto es A_NORMAL.

El módulo curses define las siguientes funciones:

curses.baudrate()

Retorna la velocidad de salida de la terminal en bits por segundo. En emuladores de terminal de software esto tendrá un alto valor fijado. Incluido por razones históricas; en tiempos pasados, esto fue usado para escribir los ciclos de salida por retrasos de tiempo y ocasionalmente para cambiar interfaces dependiendo de la velocidad en la línea.

curses.beep()

Emite un corto sonido de atención.

curses.can_change_color()

Retorna True o False, dependiendo ya sea que el programador puede cambiar los colores presentados por la terminal.

curses.cbreak()

Entra al modo cbreak. En el modo cbreak (a veces llamado modo «raro») del buffer de línea tty normal es apagado y los caracteres están disponibles para ser leídos uno por uno. Sin embargo, a diferencia del modo raw, los caracteres especiales (interrumpir, salir, suspender y control de flujo) retiene sus efectos en el manejador tty y el programa de llamada. Llamando primero raw() luego cbreak() dejando la terminal en modo cbreak.

curses.color_content(color_number)

Retorna la intensidad de los componentes rojo, verde y azul (RGB) en el color color_number, que debe estar entre 0 y COLORS-1. Retorna una tupla de 3, que contiene los valores R,G,B para el color dado, que estará entre 0 (sin componente) y 1000 (cantidad máxima de componente).

curses.color_pair(pair_number)

Retorna el valor del atributo para mostrar texto en el par de colores especificado. Solo se admiten los primeros 256 pares de colores. Este valor de atributo se puede combinar con A_STANDOUT, A_REVERSE, y los otros atributos A_*. pair_number() es la contraparte de esta función.

curses.curs_set(visibility)

Configura el estado del cursor. visibilidad puede estar configurado para «0», «1» o «2», para invisible, normal o muy visible. Si la terminal soporta la visibilidad requerida, retorna el estado del cursor previo; de otra manera ejecuta una excepción. En muchos terminales, el modo «visible» es un cursor subrayado y el modo «muy visible» es un cursor de bloque.

curses.def_prog_mode()

Guardar el modo del terminal actual como el modo «program», el modo cuando el programa corriendo está usando curses. (Su contraparte es el modo «shell», para cuando el programa no está en curses.) Seguido de la llamada a reset_prog_mode() restaurará este modo.

curses.def_shell_mode()

Guarde el modo de terminal actual como el modo «shell», el modo en el que el programa en ejecución no utiliza curses. (Su contraparte es el modo «program», cuando el programa está usando las capacidades de curses.) Las llamadas subsecuentes a reset_shell_mode() restaurarán este modo.

curses.delay_output(ms)

Inserte una pausa en milisegundo ms en la salida.

curses.doupdate()

Actualiza la pantalla física. La librería curses mantiene dos estructuras de datos, uno representa el contenido de la pantalla física actual y una pantalla virtual representa el próximo estado deseado. La base doupdate() actualiza la pantalla física para comparar la pantalla virtual.

La pantalla virtual puede ser actualizada por una llamada noutrefresh() después de escribir las operaciones tales como addstr() ha sido ejecutada en una ventana. La llamada normal refresh() es simplemente noutrefresh() seguido por doupdate(); si tienes para actualizar múltiples ventanas, puedes aumentar el rendimiento y quizás reducir los parpadeos de la pantalla usando la llamada noutrefresh() en todas las ventanas, seguido por un simple doupdate().

curses.echo()

Entrar en modo echo. En modo echo, cada caracter de entrada es repercutido a la pantalla como este es introducido.

curses.endwin()

Desinicializa la librería y retorne el terminal al estado normal.

curses.erasechar()

Retorne el carácter borrado del usuario actual como un objeto de bytes de un byte. Bajo el sistema de operaciones Unix esta es una propiedad de el controlador tty de el programa curses, y no es configurado por la librería curses en sí misma.

curses.filter()

La rutina filter(), si es usada, debe ser llamada antes que initscr() sea llamada. El efecto es que durante estas llamadas, LINES es configurada para 1; las capacidades clear, cup, cud, cud1, cuu1, cuu, vpa son desactivadas; y la cadena home es configurada para el valor de cr. El efecto es que el cursor es confinado para la línea actual, y también las pantallas son actualizadas. Este puede ser usado para habilitar la línea editando el carácter en un tiempo sin tocar el resto de las pantallas.

curses.flash()

La pantalla Flash. Eso es, cambiar lo a video inverso y luego cambie lo de nuevo en un corto intervalo. Algunas personas prefieren como “campana visible” para la señal de atención audible producida por beep().

curses.flushinp()

Vacíe todos los búferes de entrada. Esto desecha cualquier mecanografiado que ha sido escrito por el usuario y no ha sido aún procesado por el programa.

curses.getmouse()

Después de getch() retorna KEY_MOUSE para señalar un evento de mouse, se debe llamar a este método para recuperar el evento de mouse en cola, representado como una tupla de 5 (id, x, y, z, bstate). id es un valor de ID que se utiliza para distinguir varios dispositivos, y x, y, z son las coordenadas del evento. (z no se usa actualmente.) bstate es un valor entero cuyos bits se establecerán para indicar el tipo de evento, y será el OR bit a bit de una o más de las siguientes constantes, donde n es el botón número de 1 a 4: BUTTONn_PRESSED, BUTTONn_RELEASED, BUTTONn_CLICKED, BUTTONn_DOUBLE_CLICKED, BUTTONn_TRIPLE_CLICKED, BUTTON_SHIFT, BUTTON_CTRL, BUTTON_ALT.

curses.getsyx()

Retorna las coordenadas actuales del cursor en la pantalla virtual como una tupla (y, x). Si leaveok es actualmente True entonces retorna (-1,-1).

curses.getwin(file)

Lee la ventana relacionada con los datos almacenados en el archivo por una llamada temprana a putwin(). La rutina entonces crea e inicializa una nueva ventana usando esos datos, retornando el nuevo objeto de ventana.

curses.has_colors()

Retorna True si el terminal puede desplegar colores, en caso contrario, retorna False.

curses.has_ic()

Retorna True si el terminal tiene la capacidad de insertar y eliminar caracteres. Esta función es incluida por razones históricas solamente, ya que todos los emuladores de la terminal de software modernos tienen tales capacidades.

curses.has_il()

Retorna True si la terminal tiene la capacidad de insertar y eliminar caracteres o pueden simularlos usando las regiones de desplazamiento. Esta función es incluida por razones históricas solamente, como todos los emuladores de terminales de software modernos tienen tales capacidades.

curses.has_key(ch)

Toma una clave valor ch, y retorna True si el tipo de terminal actual reconoce una clave con ese valor.

curses.halfdelay(tenths)

Usado por el modo de medio retardo, el cual es similar al modo cbreak en que los caracteres escritos por el usuario están disponibles inmediatamente para el programa. Sin embargo, después de bloquearlos por tenths décimas de segundos, se levanta una excepción si nada ha sido escrito. El valor de tenths debe ser un número entre 1 y 255. Use nocbreak() para salir del modo de medio retardo.

curses.init_color(color_number, r, g, b)

Cambia la definición de un color, tomando el número del color a cambiar seguido de tres valores RGB (para las cantidades de componentes rojo, verde y azul). El valor de color_number debe estar entre 0 y COLORS - 1. Cada uno de r, g, b, debe tener un valor entre 0 y 1000. Cuando se usa init_color(), todas las apariciones de ese color en la pantalla cambian inmediatamente a la nueva definición. Esta función no es operativa en la mayoría de terminales; solo está activo si can_change_color() retorna True.

curses.init_pair(pair_number, fg, bg)

Cambia la definición de un par de colores. Se necesitan tres argumentos: el número del par de colores que se va a cambiar, el número de color de primer plano y el número de color de fondo. El valor de par_number debe estar entre 1 y COLOR_PAIRS-1 (el par de colores 0 está conectado a blanco sobre negro y no se puede cambiar). El valor de los argumentos fg y bg debe estar entre 0'' y ``COLORS-1 o, después de llamar a use_default_colors(), -1. Si el par de colores se inicializó previamente, la pantalla se actualiza y todas las apariciones de ese par de colores se cambian a la nueva definición.

curses.initscr()

Inicializa la librería. Retorna un objeto window el cual representa a toda la pantalla.

Nota

Si hay un error al abrir el terminal, la librería curses subyacente puede causar que el interprete salga.

curses.is_term_resized(nlines, ncols)

Retorna True si resize_term() modificaría la estructura de la ventana, False en caso contrario.

curses.isendwin()

Retorna True si endwin() ha sido llamado (eso es que la librería curses ha sido desinicializada).

curses.keyname(k)

Retorna el nombre de la tecla enumerada k como un objeto de bytes. El nombre de una tecla que genera un carácter ASCII imprimible es el carácter de la tecla. El nombre de una combinación de teclas de control es un consistente objeto de bytes de dos bytes de un signo de intercalación (b'^') seguido por el correspondiente carácter ASCII imprimible. El nombre de una combinación de tecla alt (128-255) es un objeto de bytes consistente del prefijo b'M-' seguido por el nombre del correspondiente carácter ASCII.

curses.killchar()

Retorna el carácter de eliminación de la línea actual del usuario como un objeto de bytes de un byte. Bajo el sistema operativo Unix esta es una propiedad del controlador tty del programa curses, y no está configurado por la librería curses por sí mismo.

curses.longname()

Retorna un objeto de bytes que contiene el campo de nombre largo terminfo que describe el terminal actual. La longitud máxima de una descripción verbosa es 128 caracteres. Esto es definido solamente después de la llamada a initscr().

curses.meta(flag)

Si flag es True, permite caracteres de 8 bits para ser introducidos. Si flag es False, permite solamente caracteres de 7 bits.

curses.mouseinterval(interval)

Configura el tiempo máximo en milisegundos que pueden transcurrir entre los eventos de presionar y soltar para que se reconozcan como un click, y retornen el valor del intervalo anterior. El valor por defecto es 200 msec, o una quinta parte de un segundo.

curses.mousemask(mousemask)

Configure los eventos del mouse para ser reportados, y retorna una tupla (availmask, oldmask). availmask indica cual de los eventos del ratón especificados pueden ser reportados; en caso de falla completa retorna 0. oldmask es el valor previo de la máscara de evento del mouse de la ventana dada. Si esta función nunca es llamada, los eventos del mouse nunca son reportados.

curses.napms(ms)

Duerme durante ms milisegundos.

curses.newpad(nlines, ncols)

Crea y retorna un apuntador para una nueva estructura de datos de pad con el número dado de líneas y columnas. Retorna un pad como un objeto de ventana.

Una almohadilla es como una ventana, excepto que no es restringida por el tamaño de la pantalla, y no está necesariamente asociada con una parte particular de la pantalla. Las almohadillas pueden ser usadas cuando un ventana grande es necesitada, y solamente una parte de la ventana estará en la pantalla de una sola vez. Actualizaciones automáticas de almohadillas (tales desde el desplazamiento o haciendo eco de la entrada) no ocurre. Los métodos refresh() y noutrefresh() de una almohadilla requiere 6 argumentos para especificar la parte de la almohadilla a ser mostrada y la locación en la ventana que se utilizará para la visualización. Los argumentos son pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol; el argumento p se refiere a la esquina superior izquierda de la región de la almohadilla a ser mostrada y el argumento s define una caja de recorte en la pantalla con la cual la región de la almohadilla será mostrada.

curses.newwin(nlines, ncols)

curses.newwin(nlines, ncols, begin_y, begin_x)

Retorna una nueva window, cuya esquina superior izquierda esta en (begin_y, begin_x), y cuyo alto/ancho es nlines/ncols.

Por defecto, la ventana extenderá desde la posición especificada para la esquina inferior derecha de la pantalla.

curses.nl()

Ingrese al modo de línea nueva. Este modo pone la tecla de retorno en una nueva línea en la entrada, y traduce la nueva línea en retorno y avance de línea en la salida. El modo de nueva línea está inicialmente encendida.

curses.nocbreak()

Salir del modo cbreak. Retorne al modo normal «cooked» con la línea del búfer.

curses.noecho()

Salir del modo echo. El eco de los caracteres de entrada está desactivado.

curses.nonl()

Dejar el modo de nueva línea. Desactiva la traducción de retorno en una nueva línea en la entrada, y desactiva la traducción a bajo nivel de una nueva línea en nueva línea/retorno en la salida (pero esto no cambia el comportamiento de addch('\n'), el cual siempre es el equivalente de retornar y avanzar la línea en la pantalla virtual). Con las traducciones apagadas, curses puede aumentar algunas veces la velocidad del movimiento vertical un poco; también, estará disponible para detectar la tecla de retorno en la entrada.

curses.noqiflush()

Cuando la rutina noqiflush() es usada, descarga normal de colas de entrada y salida asociadas con el INTR, los caracteres QUIT and SUSP no serán hechos. Puedes querer llamar noqiflush() en un manejador de señales si quieres que la salida continúe como si la interrupción no hubiera ocurrido después de que el manejador exista.

curses.noraw()

Salir del modo raw. Retorna al modo normal «cooked» con la línea del búfer.

curses.pair_content(pair_number)

Retorna una tupla (fg, bg) conteniendo los colores del par de color solicitado. El valor de pair_number debe ser entre 0 y COLOR_PAIRS-1.

curses.pair_number(attr)

Retorna el numero del conjunto de pares de colores para el valor del atributo attr. color_pair() es la contraparte de esta función.

curses.putp(str)

Equivalente a tputs(str, 1, putchar); emite el valor de una capacidad especificada terminfo para el terminal actual. Nota que la salida de putp() siempre va a la salida estándar.

curses.qiflush([flag])

Si flag es False, el efecto es el mismo como llamar noqiflush(). Si flag es True, o el argumento no es proveído, la cola será nivelada cuando estos caracteres de control son leídos.

curses.raw()

Entrar al modo crudo. En el modo crudo, el almacenamiento en búfer de la línea normal y procesamiento de las teclas de interrupción, salida, suspensión y control de flujo son apagadas; los caracteres son presentados a la función de entrada de curses una por una.

curses.reset_prog_mode()

Restaura la terminal para el modo «program», anteriormente guardado por def_prog_mode().

curses.reset_shell_mode()

Restablece el terminal al modo «shell» como lo guardó previamente def_shell_mode().

curses.resetty()

Restablece el estado del modo del terminal para lo que esto fue en el último llamado a savetty().

curses.resize_term(nlines, ncols)

La función backend usada por resizeterm(), caracteriza más de el trabajo; cuando se redimensiona la ventana, resize_term() los rellenos blancos de las áreas que son extendidas. La aplicación de llamada llenaría en estas áreas con datos apropiados. La función resize_term() intenta redimensionar todas las ventanas. Sin embargo, debido a la convención de llamadas del las almohadillas, esto no es posible para redimensionar estos sin interacciones adicionales con la aplicación.

curses.resizeterm(nlines, ncols)

Ajusta el tamaño al estándar y la ventana actual para las dimensiones especificadas, y ajusta otros datos contables usados por la librería curses que registra las dimensiones de la ventana (en particular el manejador SIGWINCH ).

curses.savetty()

Guarda el estado actual del modo del terminal en un búfer, usable por resetty().

curses.get_escdelay()

Recupera el valor establecido por set_escdelay().

Nuevo en la versión 3.9.

curses.set_escdelay(ms)

Establece el número de milisegundos de espera después de leer un carácter de escape, para distinguir entre un carácter de escape individual ingresado en el teclado de las secuencias de escape enviadas por el cursor y las teclas de función.

Nuevo en la versión 3.9.

curses.get_tabsize()

Recupera el valor establecido por set_tabsize().

Nuevo en la versión 3.9.

curses.set_tabsize(size)

Establece el número de columnas utilizadas por la biblioteca de curses al convertir un carácter de tabulación en espacios, ya que agrega la tabulación a una ventana.

Nuevo en la versión 3.9.

curses.setsyx(y, x)

Fija el cursor de la pantalla virtual para y, x. Si y y x son ambos «-1», entonces leaveok es configurado True.

curses.setupterm(term=None, fd=-1)

Inicializa la terminal. term es una cadena de caracteres dando el nombre de la terminal, o None; si es omitido o None, el valor de la variable de entorno TERM será usada. fd es el archivo descriptor al cual alguna secuencia de inicialización será enviada; si no es suministrada o -1, el archivo descriptor para sys.stdout será usado.

curses.start_color()

Debe ser llamado si el programador quiere usar colores, y antes de que cualquier otra rutina de manipulación de colores sea llamada. Esta es una buena práctica para llamar esta rutina inmediatamente después de initscr().

start_color() inicializa ocho colores básicos (negro, rojo, verde, amarillo, azul, magenta, cian, y blanco), y dos variables globales en el módulo curses, COLORS y COLOR_PAIRS, contiene el número máximo de colores y los pares de colores que la terminal puede soportar. Esto también restaura los colores en la terminal para los valores que ellos tienen cuando la terminal fue solo activada.

curses.termattrs()

Retorna un OR lógico de todos los atributos del video soportados por el terminal. Esta información es útil cuando un programa curses necesita completar el control sobre la apariencia de la pantalla.

curses.termname()

Retorna el valor de la variable de entorno TERM, como un objeto de bytes, trucado para 14 caracteres.

curses.tigetflag(capname)

Retorna el valor de la capacidad booleana correspondiente al nombre de la capacidad terminfo capname como un número entero. Retorna el valor -1 si capname no es una capacidad booleana, o 0 si es cancelada o ausente desde la descripción de la terminal.

curses.tigetnum(capname)

Retorna el valor de la capacidad numérica correspondiente al nombre de la capacidad terminfo capname como un entero. Regresa el valor -2 si capname no es una capacidad numérica, o -1 si esta es cancelada o ausente desde la descripción del terminal.

curses.tigetstr(capname)

Retorna el valor de la capacidad de la cadena de caracteres correspondiente al nombre de la capacidad terminfo capname como un objeto de bytes. Retorna None si capname no es una «capacidad de cadena de caracteres» de terminfo, o es cancelada o ausente desde la descripción de la terminal.

curses.tparm(str[, ...])

Instancia del objeto de bytes str con los parámetros suministrados, dónde str sería un cadena de caracteres parametrizada obtenida desde la base de datos de terminfo. E.g. tparm(tigetstr("cup"), 5, 3) podría resultar en b'\033[6;4H', el resultado exacto depende del tipo de terminal.

curses.typeahead(fd)

Especifica que el descriptor de archivo fd es usado para la verificación anticipada. Si fd es «-1», entonces no se realiza ninguna verificación anticipada.

La librería curses hace «la optimización del rompimiento de línea» por la búsqueda para mecanografiar periódicamente mientras se actualiza la pantalla. Si la entrada es encontrada, y viene desde un tty, la actualización actual es pospuesta hasta que se vuelva a llamar la actualización, permitiendo la respuesta más rápida para comandos escritos en avance. Esta función permite especificar un archivo diferente al descriptor para la verificación anticipada.

curses.unctrl(ch)

Regresa un objeto de bytes el cual es una representación imprimible del carácter ch. Los caracteres de control son representados como un símbolo de intercalación seguido del carácter, por ejemplo como b'^C'. La impresión de caracteres son dejados como están.

curses.ungetch(ch)

Presiona ch para que el siguiente getch() lo retorne.

Nota

Solamente un ch puede ser colocado antes getch() es llamada.

curses.update_lines_cols()

Actualiza LINES y COLS. Útil para detectar el cambio manual del tamaño de pantalla.

Nuevo en la versión 3.5.

curses.unget_wch(ch)

Presiona ch para que el siguiente get_wch() lo retorne.

Nota

Solamente un ch puede ser presionado antes get_wch() es llamada.

Nuevo en la versión 3.3.

curses.ungetmouse(id, x, y, z, bstate)

Coloca un evento KEY_MOUSE en la cola de entrada, asociando el estado de los datos dados con esto.

curses.use_env(flag)

Si es usado, esta función sería llamada antes de initscr() o newterm son llamados. Cuando flag es False, los valores de líneas y columnas especificadas en la base de datos terminfo será usado, incluso si las variables de entorno LINES y COLUMNS (usadas por defecto) son configuradas, o si curses está corriendo en una ventana (en cuyo caso el comportamiento por defecto sería usar el tamaño de ventana si LINES y COLUMNS no están configuradas).

curses.use_default_colors()

Permite usar valores por defecto para los colores en terminales apoyando esta característica. Use esto para apoyar la transparencia en tu aplicación. El color por defecto es asignada para el número de color -1. Después de llamar esta función, inicializa init_pair(x, curses.COLOR_RED, -1), por ejemplo, los pares de color x a un primer plano de color rojo en el fondo por defecto.

curses.wrapper(func, /, *args, **kwargs)

Inicializa curses y llama a otro objeto invocable, func, el cual debería ser el resto de tu aplicación que usa curses. Si la aplicación lanza una excepción, esta función restaurará la terminal para un estado sano antes de re-lanzar la excepción y generar un una pista. El objeto invocable func es entonces pasado a la ventana principal “stdscr” como su primer argumento, seguido por algún otro argumento pasado a wrapper(). Antes de llamar a func, wrapper() habilita el modo cbreak, desactiva echo, permite el teclado del terminal, e inicializa los colores si la terminal tiene soporte de color. En salida (ya sea normal o por excepción) esto restaura el modo cooked, habilita el echo, y desactiva el teclado del terminal.

Objetos de ventana

Los objetos ventana, retornados por initscr() y newwin() anteriores, tienen los siguientes métodos y atributos:

window.addch(ch[, attr])

window.addch(y, x, ch[, attr])

Pinta el carácter ch en (y, x) con atributos attr, sobrescribiendo cualquier carácter pintado previamente en esa ubicación. De forma predeterminada, la posición y los atributos del carácter son la configuración actual del objeto ventana.

Nota

Escribiendo afuera de la ventana, sub-ventana, o pad genera un curses.error. Intentando escribir en la esquina inferior derecha de una ventana, sub-ventana, o pad causará una excepción a ser generada después de que el carácter es pintado.

window.addnstr(str, n[, attr])

window.addnstr(y, x, str, n[, attr])

Pintar como máximo n caracteres de la cadena de texto str en «(y,x)» con atributos attr, sobrescribiendo algo previamente en la pantalla.

window.addstr(str[, attr])

window.addstr(y, x, str[, attr])

Dibuja la cadena de caracteres str en «(y,x)» con atributos attr, sobrescribiendo cualquier cosa previamente en la pantalla.

Nota

Escribiendo afuera de la ventana, sub-ventana, o pad genera un curses.error. Intentando escribir en la esquina inferior derecha de una ventana, sub-ventana, o pad causará una excepción a ser generada después de que la cadena de caracteres es pintada.

Un bug en *ncurses* [https://bugs.python.org/issue35924], el backend para este módulo de Python, puede causar SegFaults cuando re-dimensionan las ventanas. Esto es reparado en ncurses-6.1-20190511. Si tu estás atascado con un ncurses anterior, puedes evitar desencadenar este si no llamas addstr() con un str que tiene embebido nuevas líneas. En su lugar, llama addstr() separadamente por cada línea.

window.attroff(attr)

Remueve el atributo attr desde el conjunto «background» aplicado a todos los escritos para la ventana actual.

window.attron(attr)

Añade el atributo attr del conjunto del «background» aplicado para todas las escrituras de la ventana actual.

window.attrset(attr)

Establezca el conjunto de atributos «background para attr. Este conjunto es inicialmente «0» (sin atributos).

window.bkgd(ch[, attr])

Configura la propiedad de fondo de la ventana para el carácter ch, con atributos atte. El cambio es entonces aplicado para la posición de cada carácter en esa ventana:

El atributo de cada carácter en la ventana es cambiado por el nuevo atributo de fondo.

Dónde quiera que el carácter del fondo anterior aparezca, es cambiado al nuevo carácter de fondo.

window.bkgdset(ch[, attr])

Configura el fondo de la ventana. Un fondo de ventana consiste de un carácter y cualquier combinación de atributos. La parte del atributo del fondo es combinado (OR” ed) con todos los caracteres que no son blancos escritos en la ventana. Tanto las partes del carácter y del atributo del fondo son combinados con los caracteres en blanco. El fondo se convierte en una propiedad del carácter y se mueve con el carácter a través de cualquier operación de desplazamiento e inserción/eliminación de línea/carácter.

window.border([ls[, rs[, ts[, bs[, tl[, tr[, bl[, br]]]]]]]])

Dibuja un borde alrededor de las orillas de la ventana. Cada parámetro especifica el carácter a usar para una parte específica del borde; ve la tabla abajo para más detalles.

Nota

Un valor 0 para cualquier parámetro causará el carácter por defecto a ser usado para ese parámetro. parámetros de palabras clave pueden no ser usados. Los valores predeterminados son listados en esta tabla:

Parámetro

Descripción

Valor por defecto

ls

Lado izquierdo

ACS_VLINE

rs

Lado derecho

ACS_VLINE

ts

Arriba

ACS_HLINE

bs

Abajo

ACS_HLINE

tl

Esquina superior izquierda

ACS_ULCORNER

tr

Esquina superior derecha

ACS_URCORNER

bl

Esquina inferior izquierda

ACS_LLCORNER

br

Esquina inferior derecha

ACS_LRCORNER

window.box([vertch, horch])

Similar a border(), pero ambos ls y *rs son vertch y ambos ts y bs son horch. Los caracteres de esquina predeterminados son siempre usados por esta función.

window.chgat(attr)

window.chgat(num, attr)

window.chgat(y, x, attr)

window.chgat(y, x, num, attr)

Configura los atributos de num de caracteres en la posición del cursor, o una posición (y, x) si es suministrado. Si num no es dado o es -1, el atributo será configurado en todos los caracteres para el final de la línea. Esta función mueve el cursor a la posición (y, x) si es suministrado. La línea cambiada será tocada usando el método touchline() tal que el contenido será vuelto a mostrar por la actualización de la siguiente ventana.

window.clear()

Semejante a erase(), pero también causa que toda la ventana sea repintada sobre la siguiente llamada para refresh().

window.clearok(flag)

Si flag es True, la siguiente llamada para refresh() limpiará la ventana completamente.

window.clrtobot()

Borrar desde el cursor hasta el final de la ventana: todas las líneas bajo el cursor son eliminadas, y entonces el equivalente de clrtoeol() es realizado.

window.clrtoeol()

Borrar desde el cursor hasta el final de la línea.

window.cursyncup()

Actualice la posición actual del cursor de todos los ancestros de la ventana para reflejar la posición actual del cursor de la ventana.

window.delch([y, x])

Borrar cualquier carácter en «(y,x)».

window.deleteln()

Borra la línea bajo el cursor. Todas las líneas siguientes son movidas una línea hacía arriba.

window.derwin(begin_y, begin_x)

window.derwin(nlines, ncols, begin_y, begin_x)

Una abreviación para «ventana derivada», derwin() es el mismo cómo llamar subwin(), excepto que begin_y y begin_x son relativos al origen de la ventana, más bien relativo a la pantalla completa. Retorna un objeto ventana para la ventana derivada.

window.echochar(ch[, attr])

Añada el carácter ch con atributo attr, e inmediatamente llame a refresh() en la ventana.

window.enclose(y, x)

Pruebe si el par dado de las coordenadas de celda del carácter relativas de la ventana son encerrados por la ventana dada, retornando True o False. Esto es útil para determinar que subconjunto de las ventanas de pantalla encierran la locación de un evento del mouse.

window.encoding

La codificación utilizada para codificar argumentos de método (Unicode de caracteres y cadena de caracteres). El atributo codificado es heredado desde la ventana padre cuando una sub-ventana es creada, por ejemplo con window.subwin(). Por defecto, la codificación local es usada (ver locale.getpreferredencoding()).

Nuevo en la versión 3.3.

window.erase()

Limpiar la ventana.

window.getbegyx()

Retorna una tupla «(y,x)» de coordenadas de la esquina superior izquierda.

window.getbkgd()

Retorna el par carácter/atributo dada la ventana actual.

window.getch([y, x])

Obtener un carácter. Nota que el entero retornado no tiene que estar en el rango ASCII: teclas de función, claves de teclado y los demás son representados por números mayores que 255. En el modo sin demora, retorna -1 si no hay entrada, en caso contrario espere hasta que una tecla es presionada.

window.get_wch([y, x])

Obtener un carácter amplio. Retorna un carácter para la mayoría de las teclas, o un entero para las teclas de función, teclas del teclado, y otras teclas especiales. En modo de no retorna, genera una excepción si no hay entrada.

Nuevo en la versión 3.3.

window.getkey([y, x])

Obtener un carácter, retornando una cadena de caracteres en lugar de un entero, como getch() lo hace. Las teclas de función, teclas del teclado y otras teclas especiales retornan una cadena multibyte conteniendo el nombre de la tecla. En modo de no retardo, genera una excepción si no hay entrada.

window.getmaxyx()

Retorna una tupla «(y,x)» de el alto y ancho de la ventana.

window.getparyx()

Retorne las coordenadas iniciales de esta ventana relativa para su ventana padre como una tupla (y, x). Retorna (-1, -1) si esta ventana no tiene padre.

window.getstr()

window.getstr(n)

window.getstr(y, x)

window.getstr(y, x, n)

Lee un objeto de bytes desde el usuario, con capacidad de edición de línea primitiva.

window.getyx()

Retorna una tupla (y, x) de la posición actual del cursor relativa para la esquina superior izquierda de la ventana.

window.hline(ch, n)

window.hline(y, x, ch, n)

Muestra una línea horizontal iniciando en (y, x) con longitud n consistente de el carácter ch.

window.idcok(flag)

Si flag es False, curses ya no considera el uso de la función de insertar/eliminar caracteres de hardware del terminal; si flag True, el uso de inserción y borrado de caracteres está habilitado. Cuando curses es inicializado primero, el uso de caracteres de inserción / borrado está habilitado por defecto.

window.idlok(flag)

Si flag es True, curses tratará y usará las funciones de la línea de edición de hardware. En caso contrario, la línea inserción/borrado están deshabilitadas.

window.immedok(flag)

Si flag es True, cualquier cambio en la imagen de la ventana automáticamente causará que la ventana sea refrescada; ya no tienes que llamar a refresh() por ti mismo. Sin embargo, esto puede degradar el rendimiento considerablemente, debido a las repeticiones de llamada a wrefresh. Esta opción está deshabilitada por defecto.

window.inch([y, x])

Retorna el carácter en la posición dada en la ventana. Los 8bits inferiores son los caracteres propiamente dichos, y los bits superiores son los atributos.

window.insch(ch[, attr])

window.insch(y, x, ch[, attr])

Pinta el carácter ch en (y, x) con atributos attr, moviendo la línea desde la posición x a la derecha un carácter.

window.insdelln(nlines)

Inserta nlines líneas en la ventana especificada arriba de la línea actual. Las nlines líneas de fondo se pierden. Para nlines negativos, elimine nlines líneas comenzando con la que está debajo del cursor, y mueve las restantes hacia arriba. Se borran las nlines líneas inferiores. La posición del cursor actual se mantiene igual.

window.insertln()

Inserte una línea en blanco bajo el cursos. Las líneas siguientes se moverán una línea hacía abajo.

window.insnstr(str, n[, attr])

window.insnstr(y, x, str, n[, attr])

Inserte una cadena de caracteres (tantos caracteres quepan en la línea) antes los caracteres bajo el cursor, sobre los n caracteres. Si n es cero o negativo, la cadena entera es insertada. Todos los caracteres a la derecha de el cursor son desplazados a la derecha, perdiéndose los caracteres de la derecha en la línea. La posición del cursor no cambia (después de mover a y, x, si es especificado).

window.insstr(str[, attr])

window.insstr(y, x, str[, attr])

Inserte una cadena de caracteres ( tantos caracteres encajen en la línea) antes los caracteres bajo el cursor. Todos los caracteres a la derecha de el cursor son desplazados a la derecha, perdiéndose los caracteres de la derecha en línea.

window.instr([n])

window.instr(y, x[, n])

Regresa un objeto de bytes de caracteres, extraídos desde la ventana comenzando en la posición actual del cursor, o en y, x si es especificado. Los atributos son despojados desde los caracteres. Si n es especificado, instr() retorna una cadena de caracteres como máximo de n caracteres (exclusivo de la NULL final).

window.is_linetouched(line)

Retorna True si la línea especificada fue modificada desde la última llamada a refresh(); de otra manera retorna False. Genera una excepción curses.error si line no es válida para la ventana dada.

window.is_wintouched()

Retorna True si la ventana especificada fue modificada desde la última llamada para refresh(); en caso contrario, retorna False.

window.keypad(flag)

Si flag es True, evita las secuencias generadas por algunas teclas (teclado, teclas de función) será interpretadas por curses. Si flag es False, evita las secuencias que serán dejadas como está en la corriente de entrada.

window.leaveok(flag)

Si flag es True, el cursor es dejado donde está en la actualización, por ejemplo estando en «cursor position.» Esto reduce el movimiento del cursor siempre que sea posible. Si es posible, el cursor se hará invisible.

Si flag es False, el cursor siempre estará en «cursor position» después de una actualización.

window.move(new_y, new_x)

Mueve el cursor a (new_y, new_x).

window.mvderwin(y, x)

Mueve la ventana adentro de su ventana padre. Los parámetros relativos a la pantalla de la ventana no son cambiados. Esta rutina es usada para mostrar diferentes partes de la ventana padre en la misma posición física en la pantalla.

window.mvwin(new_y, new_x)

Mueve la ventana a su esquina superior izquierda que está en (new_y,new_x).

window.nodelay(flag)

Si flag es True, getch() no será bloqueada.

window.notimeout(flag)

Si flag es True, las secuencias de escape no serán agotadas.

Si flag es False, después de pocos milisegundos, una secuencia de escape no será interpretada, y será dejada en el flujo de entrada como está.

window.noutrefresh()

Marque para actualizar pero espere. Esta función actualiza la estructura de datos representando el estado deseado de la ventana, pero no fuerza una actualización en la pantalla física. Para realizar eso, llame doupdate().

window.overlay(destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol])

Cubre la ventana en la parte superior de destwin. La ventana no necesita ser del mismo tamaño, solamente se solapa la región copiada. Esta copia no es destructiva, lo que significa que el carácter de fondo actual no sobre-escribe el contenido viejo de destwin.

Para obtener el control de grano fino sobre la región copiada, la segunda forma de overlay() puede ser usada. sminrow y smincol son las coordenadas superior izquierda de la ventana de origen, y las otras variables marcan un rectángulo en la ventana destino.

window.overwrite(destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol])

Sobre-escribe la ventana en la parte superior de destwin. La ventana no necesita ser del mismo tamaño, en cuyo caso solamente se sobrepone la región que es copiada. Esta copia es destructiva, lo cual significa que el carácter de fondo actual sobre-escribe el contenido viejo de destwin.

Para obtener el control de grano fino sobre la región copiada, la segunda forma de overwrite() puede ser usada. sminrow y smincol son las coordenadas superior izquierda de la ventana origen, las otras variables marcan un rectángulo en la ventana de destino.

window.putwin(file)

Escribe todos los datos asociados con la ventana en el objeto de archivo proveído. Esta información puede estar después recuperada usando la función getwin().

window.redrawln(beg, num)

Indica que el num de líneas de la pantalla, empiezan en la línea beg, son corruptos y deberían ser completamente redibujado en la siguiente llamada refresh().

window.redrawwin()

Toca la ventana completa, causando que se vuelva a dibujar completamente en la siguiente llamada refresh() .

window.refresh([pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol])

Actualiza la pantalla inmediatamente (sincronice la pantalla actual con los métodos previos de dibujar/borrar).

Los 6 argumentos opcionales pueden ser solamente especificados cuando la ventana es una almohadilla creada con newpad(). Los parámetros adicionales son necesarios para indicar que parte de la almohadilla y pantalla son envueltos. pminrow y pmincol especifica la esquina superior de la mano izquierda del rectángulo a ser mostrado en el pad. sminrow, smincol, smaxrow, y smaxcol especifica los bordes del rectángulo a ser mostrados en la pantalla. La esquina inferior de la mano derecha del rectángulo a ser mostrado en el pad es calculado desde las coordenadas de la pantalla, desde que el rectángulo debe ser del mismo tamaño. Ambos rectángulos deben ser completamente contenidos con su estructura respectiva. Valores negativos de pminrow, pmincol, sminrow, o smincol son tratados como si fueran cero.

window.resize(nlines, ncols)

Redistribuir el almacenamiento para una ventana curses para ajustar su dimensión para los valores especificados. Si la dimensión también es mayor que los valores actuales, los datos de la ventana serán llenados con espacios en blanco que tiene la ejecución del fondo actual (como ajustado por bkgdset()) uniéndolos.

window.scroll([lines=1])

Desplace la pantalla o la región de desplazamiento hacia arriba por lines líneas.

window.scrollok(flag)

Control que sucede cuando el cursor de una ventana es movida fuera del borde de la ventana o región de desplazamiento, también como un resultado de una acción de nueva línea en la línea inferior, o escribiendo el último carácter de la última línea. Si flag es False, el cursor está a la izquierda sobre la línea inferior. Si flag es True, la ventana será desplazada hacía arriba por una línea. Note que en orden para obtener el efecto del desplazamiento físico en el terminal, también será necesario llamar idlok().

window.setscrreg(top, bottom)

Configura la región de desplazamiento desde la línea top hasta la línea bottom. Todas las acciones de desplazamiento tomarán lugar en esta región.

window.standend()

Desactive el atributo destacado. En algunos terminales esto tiene el efecto secundario de desactivar todos los atributos.

window.standout()

Active el atributo A_STANDOUT.

window.subpad(begin_y, begin_x)

window.subpad(nlines, ncols, begin_y, begin_x)

Retorna la sub-ventana, cuya esquina superior izquierda esta en (begin_y, begin_x), y cuyo ancho/alto es ncols/nlines.

window.subwin(begin_y, begin_x)

window.subwin(nlines, ncols, begin_y, begin_x)

Retorna la sub-ventana, cuya esquina superior izquierda esta en (begin_y, begin_x), y cuyo ancho/alto es ncols/nlines.

Por defecto, la sub-ventana extenderá desde la posición especificada para la esquina inferior derecha de la ventana.

window.syncdown()

Toca cada ubicación en la ventana que ha sido tocado por alguna de sus ventanas padres. Esta rutina es llamada por refresh(), esto casi nunca debería ser necesario para llamarlo manualmente.

window.syncok(flag)

Si flag es True, entonces syncup() es llamada automáticamente cuando hay un cambio en la ventana.

window.syncup()

Toque todas las locaciones de los ancestros de la ventana que han sido cambiados en la ventana.

window.timeout(delay)

Configura el bloqueo o no bloqueo del comportamiento para la ventana. Si el delay es negativo, bloqueando la lectura usada (el cual esperará indefinidamente para la entrada). Si delay es cero, entonces no se bloqueará la lectura usada, y getch() retornará -1 si la entrada no está esperando. Si delay es positivo, entonces getch() se bloqueará por delay milisegundos, y retorna -1 si aún no entra en el final de ese tiempo.

window.touchline(start, count[, changed])

Supone count líneas han sido cambiadas, iniciando con la línea start. Si changed es suministrado, específica que las líneas afectadas son marcadas como hayan sido cambiadas (changed=True) o no cambiadas (changed=False).

window.touchwin()

Suponga que toda la ventana ha sido cambiada, con el fin de optimizar el dibujo.

window.untouchwin()

Marque todas las líneas en la ventana como no cambiadas desde la última llamada para refresh().

window.vline(ch, n)

window.vline(y, x, ch, n)

Muestre una línea vertical iniciando en (y, x) con longitud n consistente de el carácter ch.

Constantes

El módulo curses define los siguientes miembros de datos:

curses.ERR

Algunas rutinas de curses que retornan un entero, tales como getch(), retorna ERR sobre el fallo.

curses.OK

Algunas rutinas de curses que retornan un entero, tales como napms(), retorna OK tras el éxito.

curses.version

Un objeto de bytes representando la versión actual de el módulo. También disponible como __version__.

curses.ncurses_version

Una tupla nombrada contiene los 3 componentes de la versión de la librería ncurses major, minor, y patch. Todos los valores son enteros. Los componentes pueden también ser accedidos por nombre, así curses.ncurses_version[0] es equivalente a curses.ncurses_version.major y así.

Disponibilidad: si la librería ncurses es usada.

Nuevo en la versión 3.8.

Algunas constantes están disponibles para especificar los atributos del celdas de caracteres. Las constantes exactas disponible dependen del sistema.

Atributo

Significado

A_ALTCHARSET

Modo de conjunto de caracteres alternativo

A_BLINK

Modo parpadeo

A_BOLD

Modo negrita

A_DIM

Modo tenue

A_INVIS

Modo invisible o en blanco

A_ITALIC

Modo cursiva

A_NORMAL

Atributo normal

A_PROTECT

Modo protegido

A_REVERSE

Fondo inverso y colores de primer plano

A_STANDOUT

Modo destacado

A_UNDERLINE

Modo subrayado

A_HORIZONTAL

Resaltado horizontal

A_LEFT

Resaltado a la izquierda

A_LOW

Resaltado bajo

A_RIGHT

Resaltado a la derecha

A_TOP

Resaltado arriba

A_VERTICAL

Resaltado vertical

A_CHARTEXT

Mascara de bits para extraer un caracter

Nuevo en la versión 3.7: A_ITALIC fue añadido.

Varias constantes están disponibles para extraer los atributos correspondientes retornados por algunos métodos.

Mascara de bits

Significado

A_ATTRIBUTES

Mascara de bits para extraer atributos

A_CHARTEXT

Mascara de bits para extraer un caracter

A_COLOR

Mascara de bits para extraer información de campo de pares de colores

Las teclas se denominan constantes enteras con nombres que comienzan con KEY_. Las teclas exactas disponibles son dependientes del sistema.

Clave constante

Clave

KEY_MIN

Valor mínimo de la clave

KEY_BREAK

Clave rota (no confiable)

KEY_DOWN

Flecha hacia abajo

KEY_UP

Flecha hacia arriba

KEY_LEFT

Flecha hacia la izquierda

KEY_RIGHT

Flecha hacia la derecha

KEY_HOME

Tecla de inicio (flecha hacia arriba + flecha hacia la izquierda)

KEY_BACKSPACE

Retroceso (no confiable)

KEY_F0

Teclas de función. Más de 64 teclas de función son soportadas.

KEY_Fn

Valor de tecla de función n

KEY_DL

Borrar línea

KEY_IL

Inserte línea

KEY_DC

Borrar caracter

KEY_IC

Insertar carácter o ingresara al modo de inserción

KEY_EIC

Salir del modo de inserción de caracteres

KEY_CLEAR

Limpiar pantalla

KEY_EOS

Limpiar al final de pantalla

KEY_EOL

Limpiar al final de la línea

KEY_SF

Desplazar una línea hacia adelante

KEY_SR

Desplazar una línea hacia atrás (reversa)

KEY_NPAGE

Página siguiente

KEY_PPAGE

Página anterior

KEY_STAB

Establecer pestaña

KEY_CTAB

Limpiar pestaña

KEY_CATAB

Limpiar todas las pestañas

KEY_ENTER

Ingresar o enviar (no confiable)

KEY_SRESET

Reinicio suave (parcial) (no confiable)

KEY_RESET

Reinicio o reinicio fuerte (no confiable)

KEY_PRINT

Imprimir

KEY_LL

Inicio abajo o abajo (abajo a la izquierda)

KEY_A1

Superior izquierda del teclado

KEY_A3

Superior derecha de el teclado

KEY_B2

Centro del teclado

KEY_C1

Inferior izquierdo del teclado

KEY_C3

Inferior derecho del teclado

KEY_BTAB

Pestaña trasera

KEY_BEG

Mendigar (Comienzo)

KEY_CANCEL

Cancelar

KEY_CLOSE

Cerrar

KEY_COMMAND

Cmd (Comando)

KEY_COPY

Copiar

KEY_CREATE

Crear

KEY_END

Final

KEY_EXIT

Salir

KEY_FIND

Encontrar

KEY_HELP

Ayudar

KEY_MARK

Marca

KEY_MESSAGE

Mensaje

KEY_MOVE

Mover

KEY_NEXT

Siguiente

KEY_OPEN

Abrir

KEY_OPTIONS

Opciones

KEY_PREVIOUS

Anterior

KEY_REDO

Rehacer

KEY_REFERENCE

Referencia

KEY_REFRESH

Refrescar

KEY_REPLACE

Re-emplazar

KEY_RESTART

Re-iniciar

KEY_RESUME

Resumir

KEY_SAVE

Guardar

KEY_SBEG

Mendicidad desplazada (comienzo)

KEY_SCANCEL

Cancelar cambiado

KEY_SCOMMAND

Comando cambiado

KEY_SCOPY

Copiado cambiado

KEY_SCREATE

Crear con desplazamiento

KEY_SDC

Borrar carácter desplazado

KEY_SDL

Borrar línea desplazada

KEY_SELECT

Seleccionar

KEY_SEND

Final desplazado

KEY_SEOL

Limpiar línea desplazada

KEY_SEXIT

Salida desplazada

KEY_SFIND

Búsqueda desplazada

KEY_SHELP

Ayuda desplazada

KEY_SHOME

Inicio cambiado

KEY_SIC

Entrada cambiada

KEY_SLEFT

Flecha hacia la izquierda desplazada

KEY_SMESSAGE

Mensaje cambiado

KEY_SMOVE

Movimiento desplazado

KEY_SNEXT

Siguiente desplazado

KEY_SOPTIONS

Opciones cambiadas

KEY_SPREVIOUS

Anterior cambiado

KEY_SPRINT

Imprimir desplazado

KEY_SREDO

Rehacer cambiado

KEY_SREPLACE

Re-emplazo cambiado

KEY_SRIGHT

Flecha hacia la derecha cambiada

KEY_SRSUME

Resumen cambiado

KEY_SSAVE

Guardar desplazado

KEY_SSUSPEND

Suspender cambiado

KEY_SUNDO

Deshacer desplazado

KEY_SUSPEND

Suspender

KEY_UNDO

Deshacer

KEY_MOUSE

Evento del ratón ha ocurrido

KEY_RESIZE

Evento de cambio de tamaño del terminal

KEY_MAX

Valor máximo de clave

En VT100s y su emulador de software, tal como X emulador de terminal, normalmente hay al menos cuatro funciones de tecla (KEY_F1, KEY_F2, KEY_F3, KEY_F4) disponibles, y la tecla flecha mapeada para KEY_UP, KEY_DOWN, KEY_LEFT y KEY_RIGHT en la manera obvia. Si tu máquina tiene un teclado de PC, esto asegura la expectativa de las teclas flecha y doce teclas de función (el más viejo de los teclados de PC pueden tener solamente diez teclas de función); también, la siguientes funciones de teclado son estándar:

Tecla

Constante

Insert

KEY_IC

Delete

KEY_DC

Home

KEY_HOME

End

KEY_END

Page Up

KEY_PPAGE

Page Down

KEY_NPAGE

La siguiente tabla lista los caracteres desde el conjunto alterno de caracteres. Estos son heredados desde el terminal VT100, y generalmente estará disponible en emuladores de software tales como terminales X. Cuando no hay gráficos disponibles, curses cae en una aproximación cruda de ASCII imprimibles.

Nota

Estos están disponibles solamente después de que initscr() ha sido llamada.

Código ACS

Significado

ACS_BBSS

nombre alternativo para la esquina superior derecha

ACS_BLOCK

bloque cuadrado sólido

ACS_BOARD

tablero de cuadrados

ACS_BSBS

nombre alternativo para línea horizontal

ACS_BSSB

nombre alternativo para esquina superior izquierda

ACS_BSSS

nombre alternativo para el soporte superior

ACS_BTEE

soporte inferior

ACS_BULLET

bala

ACS_CKBOARD

tablero inspector (punteado)

ACS_DARROW

flecha punteada hacia abajo

ACS_DEGREE

símbolo de grado

ACS_DIAMOND

diamante

ACS_GEQUAL

mayor que o igual a

ACS_HLINE

línea horizontal

ACS_LANTERN

símbolo de la linterna

ACS_LARROW

flecha izquierda

ACS_LEQUAL

menor que o igual a

ACS_LLCORNER

esquina inferior izquierda

ACS_LRCORNER

esquina inferior derecha

ACS_LTEE

soporte izquierdo

ACS_NEQUAL

signo no igual

ACS_PI

letra pi

ACS_PLMINUS

signo más o menos

ACS_PLUS

gran signo más

ACS_RARROW

flecha hacia la derecha

ACS_RTEE

soporte derecho

ACS_S1

escanear línea 1

ACS_S3

escanear línea 3

ACS_S7

escanear línea 7

ACS_S9

escanear línea 9

ACS_SBBS

nombre alterno para la esquina inferior derecha

ACS_SBSB

nombre alterno para la línea vertical

ACS_SBSS

nombre alterno para el soporte derecho

ACS_SSBB

nombre alterno para la esquina inferior izquierda

ACS_SSBS

nombre alterno para el soporte inferior

ACS_SSSB

nombre alterno para el soporte izquierdo

ACS_SSSS

nombre alterno para crossover o un gran más

ACS_STERLING

libra esterlina

ACS_TTEE

soporte superior

ACS_UARROW

flecha hacia arriba

ACS_ULCORNER

esquina superior izquierda

ACS_URCORNER

esquina superior derecha

ACS_VLINE

línea vertical

La siguiente tabla lista los colores pre-definidos:

Constante

Color

COLOR_BLACK

Negro

COLOR_BLUE

Azul

COLOR_CYAN

Cian (azul verdoso claro)

COLOR_GREEN

Verde

COLOR_MAGENTA

Magenta (rojo violáceo)

COLOR_RED

Rojo

COLOR_WHITE

Blanco

COLOR_YELLOW

Amarillo

curses.textpad— Widget de entrada de texto para programas de curses

El módulo curses.textpad provee una clase Textbox que maneja edición de texto primario en una ventana curses, apoyando un conjunto de atajos de teclado re-ensamblando estos de Emacs (esto, también de Netscape Navigator, BBedit 6.x, FrameMaker, y muchos otros programas). Los módulos también proveen una función de dibujo de rectángulo útil para enmarcar las cajas de texto o para otros propósitos.

El módulo curses.textpad define la siguiente función:

curses.textpad.rectangle(win, uly, ulx, lry, lrx)

Dibuja un rectángulo. El primer argumento debe ser un objeto de ventana, los argumentos restantes son coordenadas relativas para esa ventana. El segundo y tercer argumento son las coordenadas “x” y “y” de la esquina superior de la mano izquierda del rectángulo a ser dibujado, el cuarto y quinto argumento son las coordenadas “x” y “y” de la esquina inferior de la mano derecha. El rectángulo será dibujado usando formularios de caracteres VT100/IBM PC en terminales que hace esto posible (incluyendo xterm y mas otro emulador de terminal de software). Por otra parte será dibujado con guiones, barras verticales, y signos de más de ASCII.

Objeto de caja de texto

Tú puedes instanciar un objeto Textbox como sigue:

class curses.textpad.Textbox(win)

Retorna un objeto widget de caja de texto. El argumento win debería ser un objeto curses window en el cual la caja de texto es para ser contenido. El cursor de la caja de texto está inicialmente localizado en la esquina superior de la mano izquierda de la ventana que lo contiene, con coordenadas (0, 0). La bandera instanciada stripspaces está inicialmente encendida.

Objeto Textbox tiene los siguientes métodos:

edit([validator])

Este es el punto de entrada que normalmente usarás. Esto acepta la edición de las pulsaciones de tecla hasta que uno de las pulsaciones de finalización es introducida. Si validator es suministrado, esto debe ser una función. Será llamado para cada pulsación de tecla introducida con la pulsación de tecla como un parámetro; el comando ejecutado está hecho en el resultado. Este método retorna el contenido de la ventana como una cadena de caracteres; si se incluyen espacios en blanco en la ventana se ve afectado por el atributo stripspaces.

do_command(ch)

Procesa un simple comando al pulsar una tecla. Aquí está las funciones de tecla especiales admitidas:

Pulsación de tecla

Acción

Control-A

Ve al borde izquierdo de la ventana.

Control-B

Cursor hacia la izquierda, pasando a la línea anterior si corresponde.

Control-D

Borra el carácter bajo el cursor.

Control-E

Ve al borde derecho (quita los espacios) o al final de línea (eliminar los espacios).

Control-F

Cursor hacia la derecha, pasando a la línea siguiente cuando corresponda.

Control-G

Terminar, retornando el contenido de la ventana.

Control-H

Eliminar carácter al revés.

Control-J

Terminar si la ventana es de 1 línea, en caso contrario, inserte una nueva línea.

Control-K

Si la línea es blanca bórrela, en caso contrario, limpie hasta el final de línea.

Control-L

Refrescar la pantalla.

Control-N

Cursor hacia abajo; mueve hacia abajo una línea.

Control-O

Inserte una línea en blanco en la posición del cursor.

Control-P

Cursor hacia arriba; mueve hacia arriba una línea.

Las operaciones de movimiento no hacen nada si el cursor está en un borde donde el movimiento no es posible. Los siguientes sinónimos están apoyados siempre que sea posible:

Constante

Pulsación de tecla

KEY_LEFT

Control-B

KEY_RIGHT

Control-F

KEY_UP

Control-P

KEY_DOWN

Control-N

KEY_BACKSPACE

Control-h

Todas las otras pulsaciones de teclas están tratadas como un comando para insertar el carácter dado y muévase a la derecha (con ajuste en la línea).

gather()

Retorne el contenido de la ventana como una cadena de texto; si se incluyen espacios en blanco en la ventana se ve afectado por el miembro stripspaces.

stripspaces

Este atributo es una bandera que controla la interpretación de los espacios en blanco en la ventana. Cuando está encendido, los espacios en blanco al final en cada línea son ignorados; cualquier movimiento del cursor que lo coloque en un espacio en blanco final va hasta el final de esa línea, y los espacios en blanco finales son despejados cuando se recopila el contenido de la ventana.

curses.ascii — Utilidades para los caracteres ASCII

El módulo curses.ascii proporciona constantes de nombre para caracteres ASCII y funciones para probar la pertenencia a varias clases de los caracteres ASCII. Las constantes proporcionadas son nombres para caracteres de control de la siguiente manera:

Nombre

Significado

NUL

SOH

Inicio del encabezado, interrupción de la consola

STX

Inicio del texto

ETX

Final del texto

EOT

Fin de la transmisión

ENQ

Consulta, va con el control de flujo ACK

ACK

Reconocimiento

BEL

Campana

BS

Retroceso

TAB

Tabulación

HT

Alias para TAB: «Tabulación horizontal»

LF

Línea de alimentación

NL

Alias para LF: «Nueva línea»

VT

Tabulación vertical

FF

Alimentación de formulario

CR

Retorno de carro (Carriage return en inglés)

SO

Shift-out, comenzar un conjunto de caracteres alternativo

SI

Shift-in, reanudar el conjunto de caracteres predeterminado

DLE

Escape de enlace de datos

DC1

XON, para control de flujo

DC2

Control de dispositivo 2, control de flujo en modo bloque

DC3

XOFF, para control de flujo

DC4

Control de dispositivo 4

NAK

Reconocimiento negativo

SYN

Inactivo sincrónico

ETB

Bloque de transmisión final

CAN

Cancelar

EM

Fin del medio

SUB

Sustituir

ESC

Escapar

FS

Separador de archivos

GS

Separador de grupos

RS

Separador de registros, finalizador en modo bloque

US

Separador de unidades

SP

Espacio

DEL

Eliminar

Tenga en cuenta que muchos de estos tienen poca importancia práctica en el uso moderno. Los mnemónicos se derivan de las convenciones de la teleimpresora que son anteriores a las computadoras digitales.

El módulo proporciona las siguientes funciones, siguiendo el patrón de las de la biblioteca C estándar:

curses.ascii.isalnum(c)

Comprueba un carácter alfanumérico ASCII; esto es equivalente a isalpha(c) or isdigit(c).

curses.ascii.isalpha(c)

Comprueba si hay un carácter alfabético ASCII; es equivalente a isupper(c) or islower(c).

curses.ascii.isascii(c)

Comprueba un valor de carácter que se ajuste al conjunto ASCII de 7 bits.

curses.ascii.isblank(c)

Comprueba si hay un carácter de espacio en blanco ASCII; espacio o tabulación horizontal.

curses.ascii.iscntrl(c)

Comprueba un carácter de control ASCII (en el rango de 0x00 a 0x1f o 0x7f).

curses.ascii.isdigit(c)

Comprueba si hay un dígito decimal ASCII, desde '0' hasta '9'. Esto es equivalente a c in string.digits.

curses.ascii.isgraph(c)

Comprueba en ASCII cualquier carácter imprimible excepto el espacio.

curses.ascii.islower(c)

Comprueba un carácter ASCII en minúscula.

curses.ascii.isprint(c)

Comprueba cualquier carácter imprimible ASCII, incluido el espacio.

curses.ascii.ispunct(c)

Comprueba si hay algún carácter ASCII imprimible que no sea un espacio o un carácter alfanumérico.

curses.ascii.isspace(c)

Comprueba los caracteres de espacio en blanco ASCII; espacio, línea de alimentación, retorno de carro, formulario de alimentación, tabulación horizontal, tabulación vertical.

curses.ascii.isupper(c)

Comprueba una letra mayúscula ASCII.

curses.ascii.isxdigit(c)

Comprueba si hay un dígito hexadecimal ASCII. Esto es equivalente a c in string.hexdigits.

curses.ascii.isctrl(c)

Comprueba un carácter de control ASCII (valores ordinales de 0 a 31)

curses.ascii.ismeta(c)

Comprueba si hay un carácter no ASCII (valores ordinales 0x80 y superiores).

Estas funciones aceptan enteros o cadenas de un solo carácter; cuando el argumento es una cadena de caracteres, primero se convierte utilizando la función built-in ord().

Tenga en cuenta que todas estas funciones verifican los valores de bits ordinales derivados del carácter de la cadena que ingresa; en realidad, no saben nada sobre la codificación de caracteres de la máquina host.

Las siguientes dos funciones toman una cadena de un solo carácter o un valor de byte entero; devuelven un valor del mismo tipo.

curses.ascii.ascii(c)

Retorna el valor ASCII correspondiente a los 7 bits bajos de c.

curses.ascii.ctrl(c)

Retorna el carácter de control correspondiente al carácter dado (el valor del bit del carácter es bit a bit (bitwise-anded) con 0x1f).

curses.ascii.alt(c)

Retorna el carácter de 8 bits correspondiente al carácter ASCII dado (el valor del bit de carácter se escribe bit a bit (bitwise-ored) con 0x80).

La siguiente función toma una cadena de un solo carácter o un valor entero; devuelve una cadena.

curses.ascii.unctrl(c)

Retorna una representación de cadena del carácter ASCII c. Si c es imprimible, esta cadena es el propio carácter. Si el carácter es un carácter de control (0x00–0x1f) la cadena consta de un signo de intercalación ('^') seguido de la letra mayúscula correspondiente. Si el carácter es una eliminación ASCII (0x7f), la cadena es '^?'. Si el carácter tiene su meta bit establecido (0x80), el meta bit se elimina, se aplican las reglas anteriores y se antepone '!' al resultado.

curses.ascii.controlnames

Una matriz de cadena de caracteres de 33 elementos que contiene los mnemónicos ASCII para los treinta y dos caracteres de control ASCII desde 0 (NUL) a 0x1f (US), en orden, más el mnemónico``SP`` para el carácter de espacio.

curses.panel — Una extensión de pila de panel para curses

Los paneles son ventanas con la característica de profundidad añadida, por lo que se pueden apilar una encima de la otra, y solo se mostrarán las partes visibles de cada ventana. Los paneles se pueden agregar, mover hacia arriba o hacia abajo en la pila y eliminarse.

Funciones

El módulo curses.panel define las siguientes funciones:

curses.panel.bottom_panel()

Retorna el panel inferior en la pila del panel.

curses.panel.new_panel(win)

Retorna un objeto de panel, asociándolo con la ventana dada win. Tenga en cuenta que debe mantener explícitamente el objeto de panel retornado al que se hace referencia. Si no lo hace, el objeto de panel se recoge como basura y elimina de la pila del panel.

curses.panel.top_panel()

Retorna el panel superior de la pila de paneles.

curses.panel.update_panels()

Actualiza la pantalla virtual después de los cambios en la pila del panel. Esto no llama a curses.doupdate(), por lo que tendrás que hacerlo tú mismo.

Objetos de Panel

Los objetos panel, retornados por new_panel() arriba, son ventanas con un orden de apilamiento. Siempre hay una ventana asociada a un panel que determina el contenido, mientras que los métodos del panel son responsables de la profundidad de la ventana en la pila del panel.

Los objetos de panel tienen los siguientes métodos:

Panel.above()

Retorna el panel situado encima del panel actual.

Panel.below()

Retorna el panel debajo del panel actual.

Panel.bottom()

Empuja el panel hasta la parte inferior de la pila.

Panel.hidden()

Retorna True si el panel está oculto (no visible), False en caso contrario.

Panel.hide()

Ocultar el panel. Esto no elimina el objeto, solo hace que la ventana en la pantalla sea invisible.

Panel.move(y, x)

Mueve el panel a las coordenadas de pantalla``(y, x)``.

Panel.replace(win)

Cambia la ventana asociada con el panel a la ventana win.

Panel.set_userptr(obj)

Establece el puntero de usuario del panel en obj. Esto se usa para asociar un dato arbitrario con el panel y puede ser cualquier objeto de Python.

Panel.show()

Muestra el panel (que podría haber estado oculto).

Panel.top()

Empuja el panel hacia la parte superior de la pila.

Panel.userptr()

Retorna el puntero del usuario para el panel. Puede ser cualquier objeto de Python.

Panel.window()

Retorna el objeto de ventana asociado con el panel.

platform — Acceso a los datos identificativos de la plataforma subyacente

código fuente: Lib/platform.py [https://github.com/python/cpython/tree/3.9/Lib/platform.py]

Nota

Plataformas específicas listadas alfabéticamente, con Linux incluido en la sección de Unix.

Plataforma cruzada

platform.architecture(executable=sys.executable, bits='', linkage='')

Consulta el ejecutable provisto (por defecto el archivo binario del intérprete de Python) para obtener información de diversas arquitecturas.

Retorna una tupla (bits, linkage), siendo bits la información sobre la arquitectura del procesador y linkage el formato de conexión usado por el ejecutable. Ambos valores se retornan como cadenas.

Los valores que no se pueden determinar se retornan según lo indicado por los ajustes por defecto de los parámetros. Si bits se da como '', el sizeof(pointer) (o sizeof(long) en la versión de Python < 1.5.2) se utiliza como indicador para el tamaño del puntero admitido.

La función se basa en el comando file del sistema para realizar la tarea. Está disponible en la mayoría de las plataformas Unix, si no en todas, y en algunas plataformas que no son de Unix y solo si el ejecutable apunta al intérprete de Python. Unos valores por defecto se utilizan cuando no se satisfacen las necesidades anteriores.

Nota

On macOS (and perhaps other platforms), executable files may be universal files containing multiple architectures.

Para llegar a los «64-bits» del intérprete actual, es más seguro consultar el atributo sys.maxsize:

is_64bits = sys.maxsize > 2**32

platform.machine()

Retorna el tipo de máquina, por ejemplo 'i386'. Si no se puede determinar el valor, se retorna una cadena vacía.

platform.node()

Retorna el nombre de la red del ordenador (¡tal vez no sea el nombre completo!). Si no se puede determinar el valor, se retorna una cadena vacía.

platform.platform(aliased=0, terse=0)

Retorna una sola cadena identificando la plataforma subyacente con la mayor información útil posible.

La salida se intenta que sea humanamente legible más que tratable por una máquina. Tal vez la salida sea diferente en diversas plataformas y eso mismo es lo que se pretende.

Si aliased es verdadero, la función usará aliases para varias plataformas que informen de nombres de sistema que sean diferentes a sus nombres comunes. Por ejemplo, SunOS se reportará como Solaris. La función system_alias() ha sido usada para implementar esto.

Estableciendo terse a verdadero provoca que la función retorne el mínimo de información necesaria para identificar la plataforma.

Distinto en la versión 3.8: En macOS, la función ahora usa mac_ver(), si retorna una cadena no vacía para obtener la versión de macOS más que la versión de darwin.

platform.processor()

Retorna el nombre (real) del procesador. E.j. 'amdk6'.

Una cadena vacía se retorna si el valor no se puede determinar. Destacar que muchas plataformas no proveen esta información o simplemente retorna los mismos valores que para machine(), como hace NetBSD.

platform.python_build()

Retorna una tupla (buildno, builddate) con buildno indicando el número de la build de Python y builddate su fecha de publicación como cadenas.

platform.python_compiler()

Retorna la string con la identificación del compilador usado para compilar Python.

platform.python_branch()

Retorna la string identificando la implementación de la rama SCM de Python.

platform.python_implementation()

Retorna la string identificando la implementación de Python. Algunos valores posibles son: “CPython”, “IronPython”, “Jython”, “PyPy”.

platform.python_revision()

Retorna la string identificando la implementación de la revisión SCM de Python.

platform.python_version()

Retorna la versión de Python en formato de cadena de caracteres con la forma 'major.minor.patchlevel' siendo major la versión principal, minor la versión menor y patchlevel el último parche aplicado.

Destacar que a diferencia del sys.version de Python, el valor retornado siempre incluirá el último parche aplicado (siendo 0 por defecto).

platform.python_version_tuple()

Retorna la versión de Python como una tupla (major, minor, patchlevel) de cadena, siendo major la versión principal, minor la versión menor y patchlevel último parche aplicado.

Destacar que a diferencia del sys.version de Python, el valor retornado siempre incluirá el último parche aplicado (siendo '0' por defecto).

platform.release()

Returns the system’s release, e.g. '2.2.0' or 'NT'. An empty string is returned if the value cannot be determined.

platform.system()

Retorna el nombre del sistema/SO, como 'Linux', 'Darwin', 'Java', 'Windows'. Si no se puede determinar el valor, se retorna una cadena vacía.

platform.system_alias(system, release, version)

Retorna la tupla (system, release, version) con los aliases de los nombres comerciales usados por algunos sistemas siendo system el nombre comercial del sistema, release como la versión principal de publicación y version como el número de la versión del sistema. También hace cierta reordenación de la información en algunos casos donde se produjera algún tipo de confusión.

platform.version()

Retorna la versión de la publicación del sistema. Por ejemplo: '#3 n degas'. Una cadena vacía se retorna en el caso de que el valor no pueda ser determinado.

platform.uname()

Interfaz uname relativamente portable. Retorna una namedtuple() con seis atributos: system, node, release, version, machine, and processor.

Destacar que añade un sexto atributo (processor) que no está presente en el resultado de la función os.uname(). Los dos primeros atributos tienen nombres diferentes a los que tiene os.uname(), que los llama sysname y nodename.

Cualquier entrada que no pueda ser determinada se establece como ''.

Distinto en la versión 3.3: Result changed from a tuple to a namedtuple().

Plataforma Java

platform.java_ver(release='', vendor='', vminfo=('', '', ''), osinfo=('', '', ''))

Versión de la interfaz de Jython.

Retorna una tupla (release, vendor, vminfo, osinfo) con vminfo siendo una tupla (vm_name, vm_release, vm_vendor) y osinfo siendo una tupla (os_name, os_version, os_arch). Los valores que no se pueden determinar se establecen por defecto de los parámetros (que todos los valores predeterminados son '').

Plataforma windows

platform.win32_ver(release='', version='', csd='', ptype='')

Get additional version information from the Windows Registry and return a tuple (release, version, csd, ptype) referring to OS release, version number, CSD level (service pack) and OS type (multi/single processor). Values which cannot be determined are set to the defaults given as parameters (which all default to an empty string).

Como sugerencia: ptype es 'Uniprocessor Free' en máquinas NT de procesador único y 'Multiprocessor Free' en máquinas multiprocesador. El “Free” se refiere a que la versión del sistema operativo está libre de código de depuración. También podría indicar “Checked” lo que significa que la versión del sistema operativo utiliza código de depuración, es decir, código que comprueba argumentos, rangos, etc.

platform.win32_edition()

Returns a string representing the current Windows edition, or None if the value cannot be determined. Possible values include but are not limited to 'Enterprise', 'IoTUAP', 'ServerStandard', and 'nanoserver'.

Nuevo en la versión 3.8.

platform.win32_is_iot()

Retorna True si la edición de Windows retornada por win32_edition() se reconoce como una edición IoT.

Nuevo en la versión 3.8.

macOS Platform

platform.mac_ver(release='', versioninfo=('', '', ''), machine='')

Get macOS version information and return it as tuple (release, versioninfo, machine) with versioninfo being a tuple (version, dev_stage, non_release_version).

Cualquier registro que no puede ser determinado se establece como ''. Todas los registros de la tupla son cadenas.

Plataformas Unix

platform.libc_ver(executable=sys.executable, lib='', version='', chunksize=16384)

Intenta determinar la versión libc al que está enlazado el fichero ejecutable (por defecto el intérprete de Python). Retorna una tupla de cadenas (lib, version) que tiene por defecto los parámetros que han sido introducidos en caso de que la búsqueda fallase.

Destacar que esta función tiene un conocimiento íntimo de cómo las diferentes versiones de libc agregan símbolos al ejecutable. Probablemente sólo se puede utilizar para los ejecutables compilados mediante gcc.

El archivo se lee y se analiza en fragmentos de bytes chunksize.

errno — Símbolos estándar del sistema errno

This module makes available standard errno system symbols. The value of each symbol is the corresponding integer value. The names and descriptions are borrowed from linux/include/errno.h, which should be all-inclusive.

errno.errorcode

Diccionario que proporciona un mapeo del valor de errno al nombre de la cadena en el sistema subyacente. Por ejemplo, errno.errorcode[errno.EPERM] se asigna a 'EPERM'.

Para traducir un código de error numérico en un mensaje de error, use os.strerror().

De la siguiente lista, los símbolos que no se utilizan en la plataforma actual no están definidos por el módulo. La lista específica de símbolos definidos está disponible como errno.errorcode.keys(). Los símbolos disponibles pueden incluir:

errno.EPERM

Operation not permitted. This error is mapped to the exception PermissionError.

errno.ENOENT

No such file or directory. This error is mapped to the exception FileNotFoundError.

errno.ESRCH

No such process. This error is mapped to the exception ProcessLookupError.

errno.EINTR

Interrupted system call. This error is mapped to the exception InterruptedError.

errno.EIO

Error de E/S

errno.ENXIO

No existe tal dispositivo o dirección

errno.E2BIG

Lista de argumentos demasiado larga

errno.ENOEXEC

Error de formato de ejecución

errno.EBADF

Número de archivo incorrecto

errno.ECHILD

No child processes. This error is mapped to the exception ChildProcessError.

errno.EAGAIN

Try again. This error is mapped to the exception BlockingIOError.

errno.ENOMEM

Sin memoria

errno.EACCES

Permission denied. This error is mapped to the exception PermissionError.

errno.EFAULT

Dirección incorrecta

errno.ENOTBLK

Bloquear dispositivo requerido

errno.EBUSY

Dispositivo o recurso ocupado

errno.EEXIST

File exists. This error is mapped to the exception FileExistsError.

errno.EXDEV

Enlace entre dispositivos

errno.ENODEV

Hay tal dispositivo

errno.ENOTDIR

Not a directory. This error is mapped to the exception NotADirectoryError.

errno.EISDIR

Is a directory. This error is mapped to the exception IsADirectoryError.

errno.EINVAL

Argumento inválido

errno.ENFILE

Desbordamiento de la tabla de archivos

errno.EMFILE

Demasiados archivos abiertos

errno.ENOTTY

No es un typewriter

errno.ETXTBSY

Archivo de texto ocupado

errno.EFBIG

Archivo demasiado grande

errno.ENOSPC

No queda espacio en el dispositivo

errno.ESPIPE

Búsqueda ilegal

errno.EROFS

Sistema de archivos de sólo lectura

errno.EMLINK

Demasiados enlaces

errno.EPIPE

Broken pipe. This error is mapped to the exception BrokenPipeError.

errno.EDOM

Argumento matemático fuera del dominio de función

errno.ERANGE

Resultado matemático no representable

errno.EDEADLK

Podría ocurrir un bloqueo de recursos

errno.ENAMETOOLONG

Nombre de archivo demasiado largo

errno.ENOLCK

No hay bloqueos de registro disponibles

errno.ENOSYS

Función no implementada

errno.ENOTEMPTY

Directorio no vacío

errno.ELOOP

Se han encontrado demasiados enlaces simbólicos

errno.EWOULDBLOCK

Operation would block. This error is mapped to the exception BlockingIOError.

errno.ENOMSG

Ningún mensaje del tipo deseado

errno.EIDRM

Identificador eliminado

errno.ECHRNG

Número de canal fuera de rango

errno.EL2NSYNC

Nivel 2 no sincronizado

errno.EL3HLT

Nivel 3 detenido

errno.EL3RST

Nivel 3 restablecido

errno.ELNRNG

Número de enlace fuera de rango

errno.EUNATCH

Controlador de protocolo no adjunto

errno.ENOCSI

No hay estructura CSI disponible

errno.EL2HLT

Nivel 2 detenido

errno.EBADE

Intercambio inválido

errno.EBADR

Descriptor de solicitud inválido

errno.EXFULL

Intercambio completo

errno.ENOANO

Sin ánodo

errno.EBADRQC

Código de solicitud inválido

errno.EBADSLT

Ranura inválida

errno.EDEADLOCK

Error de interbloqueo de bloqueo de archivos

errno.EBFONT

Formato de archivo de fuente incorrecto

errno.ENOSTR

El dispositivo no es una secuencia

errno.ENODATA

Datos no disponibles

errno.ETIME

Temporizador expirado

errno.ENOSR

Recursos fuera de flujos

errno.ENONET

La computadora no está en la red

errno.ENOPKG

Paquete no instalado

errno.EREMOTE

El objeto es remoto

errno.ENOLINK

El enlace ha sido cortado

errno.EADV

Error de publicidad

errno.ESRMNT

Error de Srmount

errno.ECOMM

Error de comunicación al enviar

errno.EPROTO

Error de protocolo

errno.EMULTIHOP

Intento de salto múltiple

errno.EDOTDOT

Error específico de RFS (por su significado en inglés Remote File System)

errno.EBADMSG

No es un mensaje de datos

errno.EOVERFLOW

Valor demasiado grande para el tipo de datos definido

errno.ENOTUNIQ

Nombre no único en la red

errno.EBADFD

Descriptor de archivo en mal estado

errno.EREMCHG

La dirección remota cambió

errno.ELIBACC

No se puede acceder a una biblioteca compartida necesaria

errno.ELIBBAD

Accediendo a una biblioteca compartida dañada

errno.ELIBSCN

Sección .lib en a.out corrupta

errno.ELIBMAX

Intentando vincular demasiadas bibliotecas compartidas

errno.ELIBEXEC

No se puede ejecutar una biblioteca compartida directamente

errno.EILSEQ

Secuencia de byte ilegal

errno.ERESTART

Llamada al sistema interrumpida debe reiniciarse

errno.ESTRPIPE

Error de tubería de flujos

errno.EUSERS

Demasiados usuarios

errno.ENOTSOCK

Operación de socket en no-socket

errno.EDESTADDRREQ

Dirección de destino requerida

errno.EMSGSIZE

Mensaje demasiado largo

errno.EPROTOTYPE

Protocolo de tipo incorrecto para socket

errno.ENOPROTOOPT

Protocolo no disponible

errno.EPROTONOSUPPORT

Protocolo no soportado

errno.ESOCKTNOSUPPORT

Tipo de socket no soportado

errno.EOPNOTSUPP

Operación no soportada en el punto final de transporte

errno.EPFNOSUPPORT

Familia de protocolo no soportada

errno.EAFNOSUPPORT

Familia de direcciones no soportada por protocolo

errno.EADDRINUSE

Dirección ya en uso

errno.EADDRNOTAVAIL

No se puede asignar la dirección solicitada

errno.ENETDOWN

Red caída

errno.ENETUNREACH

Red es inalcanzable

errno.ENETRESET

Conexión de red interrumpida debido al reinicio

errno.ECONNABORTED

Software caused connection abort. This error is mapped to the exception ConnectionAbortedError.

errno.ECONNRESET

Connection reset by peer. This error is mapped to the exception ConnectionResetError.

errno.ENOBUFS

No hay espacio de búfer disponible

errno.EISCONN

El punto final de transporte ya está conectado

errno.ENOTCONN

El punto final de transporte no está conectado

errno.ESHUTDOWN

Cannot send after transport endpoint shutdown. This error is mapped to the exception BrokenPipeError.

errno.ETOOMANYREFS

Demasiadas referencias: no se puede empalmar

errno.ETIMEDOUT

Connection timed out. This error is mapped to the exception TimeoutError.

errno.ECONNREFUSED

Connection refused. This error is mapped to the exception ConnectionRefusedError.

errno.EHOSTDOWN

Anfitrión caído

errno.EHOSTUNREACH

Sin ruta al anfitrión

errno.EALREADY

Operation already in progress. This error is mapped to the exception BlockingIOError.

errno.EINPROGRESS

Operation now in progress. This error is mapped to the exception BlockingIOError.

errno.ESTALE

Manejador de archivos NFS (por su significado en inglés Network File System) obsoleto

errno.EUCLEAN

La estructura necesita limpieza

errno.ENOTNAM

No es un archivo de tipo con nombre XENIX

errno.ENAVAIL

No hay semáforos XENIX disponibles

errno.EISNAM

Es un archivo de tipo con nombre

errno.EREMOTEIO

Error de E/S remota

errno.EDQUOT

Cuota excedida

ctypes — Una biblioteca de funciones foráneas para Python

ctypes es una biblioteca de funciones foráneas para Python. Proporciona tipos de datos compatibles con C y permite llamar a funciones en archivos DLL o bibliotecas compartidas. Se puede utilizar para envolver estas bibliotecas en Python puro.

tutorial de ctypes

Note: The code samples in this tutorial use doctest to make sure that they actually work. Since some code samples behave differently under Linux, Windows, or macOS, they contain doctest directives in comments.

Nota: Algunos ejemplos de código hacen referencia al tipo ctypes c_int. En las plataformas donde sizeof(long) == sizeof(int) es un alias de c_long. Por lo tanto, no debe confundirse si c_long se imprime si espera c_int — son en realidad del mismo tipo.

Carga de bibliotecas de enlaces dinámicos

ctypes exporta los objetos cdll y en Windows windll y oledll, para cargar bibliotecas de enlaces dinámicos.

Las bibliotecas se cargan accediendo a ellas como atributos de estos objetos. cdll carga bibliotecas que exportan funciones utilizando la convención de llamada estándar cdecl, mientras que las bibliotecas windll llaman a funciones mediante la convención de llamada stdcall. oledll también utiliza la convención de llamada stdcall y asume que las funciones retornan un código de error Windows HRESULT. El código de error se utiliza para generar automáticamente una excepción OSError cuando se produce un error en la llamada a la función.

Distinto en la versión 3.3: Los errores de Windows solían generar WindowsError, que ahora es un alias de OSError.

Estos son algunos ejemplos para Windows. Tener en cuenta que “”msvcrt”” es la biblioteca estándar de MS C que contiene la mayoría de las funciones C estándar y utiliza la convención de llamada cdecl:

>>> from ctypes import *
>>> print(windll.kernel32)
<WinDLL 'kernel32', handle ... at ...>
>>> print(cdll.msvcrt)
<CDLL 'msvcrt', handle ... at ...>
>>> libc = cdll.msvcrt
>>>

Windows agrega automáticamente la extensión común .dll.

Nota

Acceder a la biblioteca estándar de C a través de cdll.msvcrt utilizará una versión obsoleta de la biblioteca que puede ser incompatible con la utilizada por Python. Cuando sea posible, use la funcionalidad nativa de Python, o bien importe y use el módulo msvcrt.

En Linux, se requiere especificar el nombre de archivo incluyendo la extensión para cargar una biblioteca, por lo que no se puede utilizar el acceso por atributos para cargar las bibliotecas. Se debe usar el método LoadLibrary() de los cargadores de dll, o se debe cargar la biblioteca creando una instancia de CDLL llamando al constructor:

>>> cdll.LoadLibrary("libc.so.6")
<CDLL 'libc.so.6', handle ... at ...>
>>> libc = CDLL("libc.so.6")
>>> libc
<CDLL 'libc.so.6', handle ... at ...>
>>>

Acceder a las funciones de los dll cargados

Las funciones se acceden como atributos de los objetos dll:

>>> from ctypes import *
>>> libc.printf
<_FuncPtr object at 0x...>
>>> print(windll.kernel32.GetModuleHandleA)
<_FuncPtr object at 0x...>
>>> print(windll.kernel32.MyOwnFunction)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "ctypes.py", line 239, in __getattr__
    func = _StdcallFuncPtr(name, self)
AttributeError: function 'MyOwnFunction' not found
>>>

Nótese que las dlls del sistema win32 como kernel32 y user32 a menudo exportan versiones ANSI y UNICODE de una función. La versión UNICODE se exporta con una W añadida al nombre, mientras que la versión ANSI se exporta con una A añadida al nombre. La función GetModuleHandle de win32, que retorna un manejador de módulo para un nombre de módulo dado, tiene el siguiente prototipo de C, y se usa una macro para exponer uno de ellos como GetModuleHandle dependiendo de si UNICODE está definido o no:

/* ANSI version */
HMODULE GetModuleHandleA(LPCSTR lpModuleName);
/* UNICODE version */
HMODULE GetModuleHandleW(LPCWSTR lpModuleName);

windll no intenta seleccionar una de ellas por arte de magia, se debe acceder a la versión que se necesita especificando GetModuleHandleA o GetModuleHandleW explícitamente, y luego llamarlo con bytes u objetos de cadena respectivamente.

A veces, las dlls exportan funciones con nombres que no son identificadores válidos de Python, como "??2@YAPAXI@Z". En este caso tienes que usar getattr() para recuperar la función:

>>> getattr(cdll.msvcrt, "??2@YAPAXI@Z")
<_FuncPtr object at 0x...>
>>>

En Windows, algunas dlls exportan funciones no por nombre sino por ordinal. Se pueden acceder a estas funciones indexando el objeto dll con el número ordinal:

>>> cdll.kernel32[1]
<_FuncPtr object at 0x...>
>>> cdll.kernel32[0]
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "ctypes.py", line 310, in __getitem__
    func = _StdcallFuncPtr(name, self)
AttributeError: function ordinal 0 not found
>>>

Funciones de llamada

Puedes llamar a estas funciones como cualquier otra función en Python. Este ejemplo utiliza la función time(), que retorna el tiempo del sistema en segundos desde la época de Unix, y la función GetModuleHandleA(), que retorna un manejador de módulo de win32.

Este ejemplo llama a ambas funciones con un puntero NULL (None debe ser usado como el puntero NULL):

>>> print(libc.time(None))
1150640792
>>> print(hex(windll.kernel32.GetModuleHandleA(None)))
0x1d000000
>>>

ValueError es lanzado cuando se llama a una función stdcall con la convención de llamada cdecl, o viceversa:

>>> cdll.kernel32.GetModuleHandleA(None)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: Procedure probably called with not enough arguments (4 bytes missing)
>>>

>>> windll.msvcrt.printf(b"spam")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: Procedure probably called with too many arguments (4 bytes in excess)
>>>

Para saber la convención de llamada correcta, hay que mirar en el archivo de encabezado C o en la documentación de la función que se quiere llamar.

En Windows, ctypes utiliza la gestión de excepciones estructurada de win32 para evitar que se produzcan fallos de protección general cuando se llaman funciones con valores de argumento inválidos:

>>> windll.kernel32.GetModuleHandleA(32)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
OSError: exception: access violation reading 0x00000020
>>>

Sin embargo, hay suficientes maneras de bloquear Python con ctypes, así que debes tener cuidado de todos modos. El módulo faulthandler puede ser útil para depurar bloqueos (por ejemplo, provenientes de fallos de segmentación producidos por llamadas erróneas a la biblioteca C).

Los objetos None, enteros, bytes y cadenas (unicode) son los únicos objetos nativos de Python que pueden ser usados directamente como parámetros en estas llamadas a funciones. None se pasa como puntero de C NULL, los objetos bytes y las cadenas se pasan como puntero al bloque de memoria que contiene sus datos (char * o wchar_t *). Los enteros de Python se pasan como por defecto en la plataforma como tipo int de C, su valor se enmascara para que encuadre en el tipo C.

Antes de pasar a llamar funciones con otros tipos de parámetros, tenemos que aprender más sobre los tipos de datos ctypes.

Tipos de datos fundamentales

ctypes define un número de tipos de datos primitivos compatibles con C:

tipo ctypes

Tipo C

Tipo Python

c_bool

_Bool

bool (1)

c_char

char

Un objeto bytes de 1-caracter

c_wchar

wchar_t

Una cadena de 1-caracter

c_byte

char

entero

c_ubyte

unsigned char

entero

c_short

short

entero

c_ushort

unsigned short

entero

c_int

int

entero

c_uint

unsigned int

entero

c_long

long

entero

c_ulong

unsigned long

entero

c_longlong

__int64 o long long

entero

c_ulonglong

unsigned __int64 o unsigned long long

entero

c_size_t

size_t

entero

c_ssize_t

ssize_t o Py_ssize_t

entero

c_float

float

flotante

c_double

double

flotante

c_longdouble

long double

flotante

c_char_p

char * (NUL terminated)

objecto de bytes o None

c_wchar_p

wchar_t * (NUL terminated)

cadena o None

c_void_p

void *

entero o None

El constructor acepta cualquier objeto con valor verdadero.

Todos estos tipos pueden ser creados llamándolos con un inicializador opcional del tipo y valor correctos:

>>> c_int()
c_long(0)
>>> c_wchar_p("Hello, World")
c_wchar_p(140018365411392)
>>> c_ushort(-3)
c_ushort(65533)
>>>

Dado que estos tipos son mutables, su valor también puede ser cambiado después:

>>> i = c_int(42)
>>> print(i)
c_long(42)
>>> print(i.value)
42
>>> i.value = -99
>>> print(i.value)
-99
>>>

Asignando un nuevo valor a las instancias de los tipos de punteros c_char_p, c_wchar_p, y c_void_p cambia el lugar de memoria al que apuntan, no el contenido del bloque de memoria (por supuesto que no, porque los objetos de bytes de Python son inmutables):

>>> s = "Hello, World"
>>> c_s = c_wchar_p(s)
>>> print(c_s)
c_wchar_p(139966785747344)
>>> print(c_s.value)
Hello World
>>> c_s.value = "Hi, there"
>>> print(c_s)              # the memory location has changed
c_wchar_p(139966783348904)
>>> print(c_s.value)
Hi, there
>>> print(s)                # first object is unchanged
Hello, World
>>>

Sin embargo, debe tener cuidado de no pasarlos a funciones que esperan punteros a la memoria mutable. Si necesitas bloques de memoria mutables, ctypes tiene una función create_string_buffer() que los crea de varias maneras. El contenido actual del bloque de memoria puede ser accedido (o cambiado) con la propiedad raw; si quieres acceder a él como cadena terminada NUL, usa la propiedad value:

>>> from ctypes import *
>>> p = create_string_buffer(3)            # create a 3 byte buffer, initialized to NUL bytes
>>> print(sizeof(p), repr(p.raw))
3 b'\x00\x00\x00'
>>> p = create_string_buffer(b"Hello")     # create a buffer containing a NUL terminated string
>>> print(sizeof(p), repr(p.raw))
6 b'Hello\x00'
>>> print(repr(p.value))
b'Hello'
>>> p = create_string_buffer(b"Hello", 10) # create a 10 byte buffer
>>> print(sizeof(p), repr(p.raw))
10 b'Hello\x00\x00\x00\x00\x00'
>>> p.value = b"Hi"
>>> print(sizeof(p), repr(p.raw))
10 b'Hi\x00lo\x00\x00\x00\x00\x00'
>>>

La función create_string_buffer() reemplaza a la función c_buffer() (que todavía está disponible como un alias), así como a la función c_string() de versiones anteriores de ctypes. Para crear un bloque de memoria mutable que contenga caracteres unicode del tipo C wchar_t utilice la función create_unicode_buffer().

Funciones de llamada, continuación

Note que printf imprime al canal de salida estándar real, no a sys.stdout, por lo que estos ejemplos sólo funcionarán en el prompt de la consola, no desde dentro de IDLE o PythonWin:

>>> printf = libc.printf
>>> printf(b"Hello, %s\n", b"World!")
Hello, World!
14
>>> printf(b"Hello, %S\n", "World!")
Hello, World!
14
>>> printf(b"%d bottles of beer\n", 42)
42 bottles of beer
19
>>> printf(b"%f bottles of beer\n", 42.5)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ArgumentError: argument 2: exceptions.TypeError: Don't know how to convert parameter 2
>>>

Como se ha mencionado antes, todos los tipos de Python, excepto los enteros, cadenas y objetos bytes, tienen que ser envueltos en su correspondiente tipo ctypes, para que puedan ser convertidos al tipo de datos C requerido:

>>> printf(b"An int %d, a double %f\n", 1234, c_double(3.14))
An int 1234, a double 3.140000
31
>>>

Funciones de llamada con sus propios tipos de datos personalizados

También puedes personalizar la conversión de argumentos de ctypes para permitir que las instancias de tus propias clases se usen como argumentos de función. ctypes busca un atributo _as_parameter_ y lo usa como argumento de función. Por supuesto, debe ser uno de entero, cadena o bytes:

>>> class Bottles:
...     def __init__(self, number):
...         self._as_parameter_ = number
...
>>> bottles = Bottles(42)
>>> printf(b"%d bottles of beer\n", bottles)
42 bottles of beer
19
>>>

Si no quieres almacenar los datos de la instancia en la variable de instancia _as_parameter_, puedes definir una property que haga que el atributo esté disponible a petición.

Especificar los tipos de argumentos requeridos (prototipos de funciones)

Es posible especificar los tipos de argumentos necesarios de las funciones exportadas desde las DLL estableciendo el atributo argtypes.

argtypes debe ser una secuencia de tipos de datos de C (la función printf probablemente no es un buen ejemplo aquí, porque toma un número variable y diferentes tipos de parámetros dependiendo del formato de la cadena, por otro lado esto es bastante útil para experimentar con esta característica):

>>> printf.argtypes = [c_char_p, c_char_p, c_int, c_double]
>>> printf(b"String '%s', Int %d, Double %f\n", b"Hi", 10, 2.2)
String 'Hi', Int 10, Double 2.200000
37
>>>

La especificación de un formato protege contra los tipos de argumentos incompatibles (al igual que un prototipo para una función C), e intenta convertir los argumentos en tipos válidos:

>>> printf(b"%d %d %d", 1, 2, 3)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ArgumentError: argument 2: exceptions.TypeError: wrong type
>>> printf(b"%s %d %f\n", b"X", 2, 3)
X 2 3.000000
13
>>>

Si has definido tus propias clases las cuales pasas a las llamadas a funciones, tienes que implementar un método de clase from_param() para que puedan ser usadas en la secuencia argtypes. El método de clase from_param() recibe el objeto Python que se le pasa a la llamada a función, debería hacer una comprobación de tipo o lo que sea necesario para asegurarse de que este objeto es aceptable, y luego retornar el objeto en sí, su atributo _as_parameter_, o lo que se quiera pasar como argumento de la función C en este caso. De nuevo, el resultado debe ser un entero, una cadena, unos bytes, una instancia ctypes, o un objeto con el atributo _as_parameter_.

Tipos de retorno

Por defecto, se supone que las funciones retornan el tipo C int. Se pueden especificar otros tipos de retorno estableciendo el atributo restype del objeto de la función.

Aquí hay un ejemplo más avanzado, utiliza la función strchr, que espera un puntero de cadena y un carácter, y retorna un puntero a una cadena:

>>> strchr = libc.strchr
>>> strchr(b"abcdef", ord("d"))
8059983
>>> strchr.restype = c_char_p    # c_char_p is a pointer to a string
>>> strchr(b"abcdef", ord("d"))
b'def'
>>> print(strchr(b"abcdef", ord("x")))
None
>>>

Si quieres evitar las llamadas ord("x") de arriba, puedes establecer el atributo argtypes, y el segundo argumento se convertirá de un objeto de un solo carácter de bytes de Python a un char:

>>> strchr.restype = c_char_p
>>> strchr.argtypes = [c_char_p, c_char]
>>> strchr(b"abcdef", b"d")
'def'
>>> strchr(b"abcdef", b"def")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ArgumentError: argument 2: exceptions.TypeError: one character string expected
>>> print(strchr(b"abcdef", b"x"))
None
>>> strchr(b"abcdef", b"d")
'def'
>>>

También puedes usar un objeto Python invocable (una función o una clase, por ejemplo) como el atributo restype, si la función foránea retorna un número entero. El objeto invocable será llamado con el entero que la función C retorna, y el resultado de esta llamada será utilizado como resultado de la llamada a la función. Esto es útil para comprobar si hay valores de retorno de error y plantear automáticamente una excepción:

>>> GetModuleHandle = windll.kernel32.GetModuleHandleA
>>> def ValidHandle(value):
...     if value == 0:
...         raise WinError()
...     return value
...
>>>
>>> GetModuleHandle.restype = ValidHandle
>>> GetModuleHandle(None)
486539264
>>> GetModuleHandle("something silly")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 3, in ValidHandle
OSError: [Errno 126] The specified module could not be found.
>>>

WinError es una función que llamará a la api Windows FormatMessage para obtener la representación de la cadena de un código de error, y retornará una excepción. WinError toma un parámetro de código de error opcional, si no se usa ninguno, llama a GetLastError`() para recuperarlo.

Tenga en cuenta que un mecanismo de comprobación de errores mucho más potente está disponible a través del atributo errcheck; consulte el manual de referencia para obtener más detalles.

Pasar los punteros (o: pasar los parámetros por referencia)

A veces una función api C espera un puntero a un tipo de datos como parámetro, probablemente para escribir en el lugar correspondiente, o si los datos son demasiado grandes para ser pasados por valor. Esto también se conoce cómo pasar parámetros por referencia.

ctypes exporta la función byref() que se utiliza para pasar parámetros por referencia. El mismo efecto se puede conseguir con la función pointer(), aunque pointer() hace mucho más trabajo ya que construye un objeto puntero real, por lo que es más rápido usar byref() si no se necesita el objeto puntero en el propio Python:

>>> i = c_int()
>>> f = c_float()
>>> s = create_string_buffer(b'\000' * 32)
>>> print(i.value, f.value, repr(s.value))
0 0.0 b''
>>> libc.sscanf(b"1 3.14 Hello", b"%d %f %s",
...             byref(i), byref(f), s)
3
>>> print(i.value, f.value, repr(s.value))
1 3.1400001049 b'Hello'
>>>

Estructuras y uniones

Las estructuras y uniones deben derivar de las clases base Structure y Union que se definen en el módulo ctypes. Cada subclase debe definir un atributo _fields_. _fields_ debe ser una lista de 2-tuplas, que contenga un nombre de campo y un tipo de campo.

El tipo de campo debe ser un tipo ctypes como c_int, o cualquier otro tipo ctypes derivado: estructura, unión, matriz, puntero.

Aquí hay un ejemplo simple de una estructura POINT, que contiene dos enteros llamados x y y, y también muestra cómo inicializar una estructura en el constructor:

>>> from ctypes import *
>>> class POINT(Structure):
...     _fields_ = [("x", c_int),
...                 ("y", c_int)]
...
>>> point = POINT(10, 20)
>>> print(point.x, point.y)
10 20
>>> point = POINT(y=5)
>>> print(point.x, point.y)
0 5
>>> POINT(1, 2, 3)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: too many initializers
>>>

Sin embargo, se pueden construir estructuras mucho más complicadas. Una estructura puede contener por sí misma otras estructuras usando una estructura como tipo de campo.

Aquí hay una estructura RECT que contiene dos POINTs llamados upperleft (superior izquierda)y lowerright (abajo a la derecha):

>>> class RECT(Structure):
...     _fields_ = [("upperleft", POINT),
...                 ("lowerright", POINT)]
...
>>> rc = RECT(point)
>>> print(rc.upperleft.x, rc.upperleft.y)
0 5
>>> print(rc.lowerright.x, rc.lowerright.y)
0 0
>>>

Las estructuras anidadas también pueden ser inicializadas en el constructor de varias maneras:

>>> r = RECT(POINT(1, 2), POINT(3, 4))
>>> r = RECT((1, 2), (3, 4))

El campo descriptor puede ser recuperado de la class, son útiles para la depuración porque pueden proporcionar información útil:

>>> print(POINT.x)
<Field type=c_long, ofs=0, size=4>
>>> print(POINT.y)
<Field type=c_long, ofs=4, size=4>
>>>

Advertencia

ctypes no soporta el paso de uniones o estructuras con campos de bits a funciones por valor. Aunque esto puede funcionar en 32-bit x86, la biblioteca no garantiza que funcione en el caso general. Las uniones y estructuras con campos de bits siempre deben pasarse a las funciones por puntero.

Alineación de estructura/unión y orden de bytes

Por defecto, los campos de Estructura y Unión están alineados de la misma manera que lo hace el compilador C. Es posible anular este comportamiento especificando un atributo de clase _pack_ en la definición de la subclase. Este debe ser establecido como un entero positivo y especifica la alineación máxima de los campos. Esto es lo que #pragma pack(n) también hace en MSVC.

ctypes utiliza el orden de bytes nativos para las Estructuras y Uniones. Para construir estructuras con un orden de bytes no nativo, puedes usar una de las clases base BigEndianStructure, LittleEndianStructure, BigEndianUnion, y LittleEndianUnion. Estas clases no pueden contener campos puntero.

Campos de bits en estructuras y uniones

Es posible crear estructuras y uniones que contengan campos de bits. Los campos de bits sólo son posibles para campos enteros, el ancho de bit se especifica como el tercer ítem en las tuplas _fields_:

>>> class Int(Structure):
...     _fields_ = [("first_16", c_int, 16),
...                 ("second_16", c_int, 16)]
...
>>> print(Int.first_16)
<Field type=c_long, ofs=0:0, bits=16>
>>> print(Int.second_16)
<Field type=c_long, ofs=0:16, bits=16>
>>>

Arreglos

Los arreglos son secuencias, que contienen un número fijo de instancias del mismo tipo.

La forma recomendada de crear tipos de arreglos es multiplicando un tipo de dato por un entero positivo:

TenPointsArrayType = POINT * 10

Aquí hay un ejemplo de un tipo de datos algo artificial, una estructura que contiene 4 POINTs entre otras cosas:

>>> from ctypes import *
>>> class POINT(Structure):
...     _fields_ = ("x", c_int), ("y", c_int)
...
>>> class MyStruct(Structure):
...     _fields_ = [("a", c_int),
...                 ("b", c_float),
...                 ("point_array", POINT * 4)]
>>>
>>> print(len(MyStruct().point_array))
4
>>>

Las instancias se crean de la manera habitual, llamando a la clase:

arr = TenPointsArrayType()
for pt in arr:
    print(pt.x, pt.y)

El código anterior imprime una serie de líneas 0 0, porque el contenido del arreglos se inicializa con ceros.

También se pueden especificar inicializadores del tipo correcto:

>>> from ctypes import *
>>> TenIntegers = c_int * 10
>>> ii = TenIntegers(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
>>> print(ii)
<c_long_Array_10 object at 0x...>
>>> for i in ii: print(i, end=" ")
...
1 2 3 4 5 6 7 8 9 10
>>>

Punteros

Las instancias de puntero se crean llamando a la función pointer() en un tipo ctypes:

>>> from ctypes import *
>>> i = c_int(42)
>>> pi = pointer(i)
>>>

Las instancias del puntero tienen un atributo contents que retorna el objeto al que apunta el puntero, el objeto i arriba:

>>> pi.contents
c_long(42)
>>>

Ten en cuenta que ctypes no tiene OOR (original object return), construye un nuevo objeto equivalente cada vez que recuperas un atributo:

>>> pi.contents is i
False
>>> pi.contents is pi.contents
False
>>>

Asignar otra instancia c_int al atributo de contenido del puntero causaría que el puntero apunte al lugar de memoria donde se almacena:

>>> i = c_int(99)
>>> pi.contents = i
>>> pi.contents
c_long(99)
>>>

Las instancias de puntero también pueden ser indexadas con números enteros:

>>> pi[0]
99
>>>

Asignando a un índice entero cambia el valor señalado:

>>> print(i)
c_long(99)
>>> pi[0] = 22
>>> print(i)
c_long(22)
>>>

También es posible usar índices diferentes de 0, pero debes saber lo que estás haciendo, al igual que en C: Puedes acceder o cambiar arbitrariamente las ubicaciones de memoria. Generalmente sólo usas esta característica si recibes un puntero de una función C, y sabes que el puntero en realidad apunta a un arreglo en lugar de a un solo elemento.

Entre bastidores, la función pointer() hace más que simplemente crear instancias de puntero, tiene que crear primero punteros tipos. Esto se hace con la función POINTER(), que acepta cualquier tipo de ctypes, y retorna un nuevo tipo:

>>> PI = POINTER(c_int)
>>> PI
<class 'ctypes.LP_c_long'>
>>> PI(42)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: expected c_long instead of int
>>> PI(c_int(42))
<ctypes.LP_c_long object at 0x...>
>>>

Llamar al tipo de puntero sin un argumento crea un puntero NULL. Los punteros NULL tienen un valor booleano falso..:

>>> null_ptr = POINTER(c_int)()
>>> print(bool(null_ptr))
False
>>>

ctypes comprueba si hay NULL cuando los punteros de referencia (pero los punteros no válidos de referencia no-NULL se romperán en Python):

>>> null_ptr[0]
Traceback (most recent call last):
    ....
ValueError: NULL pointer access
>>>

>>> null_ptr[0] = 1234
Traceback (most recent call last):
    ....
ValueError: NULL pointer access
>>>

Conversiones de tipos

Por lo general, los ctypes hacen un control estricto de los tipos. Esto significa que si tienes POINTER(c_int) en la lista argtypes de una función o como el tipo de un campo miembro en una definición de estructura, sólo se aceptan instancias exactamente del mismo tipo. Hay algunas excepciones a esta regla, en las que ctypes acepta otros objetos. Por ejemplo, se pueden pasar instancias de arreglo compatibles en lugar de tipos de puntero. Así, para POINTER(c_int), ctypes acepta un arreglo de c_int:

>>> class Bar(Structure):
...     _fields_ = [("count", c_int), ("values", POINTER(c_int))]
...
>>> bar = Bar()
>>> bar.values = (c_int * 3)(1, 2, 3)
>>> bar.count = 3
>>> for i in range(bar.count):
...     print(bar.values[i])
...
1
2
3
>>>

Además, si se declara explícitamente que un argumento de función es de tipo puntero (como POINTER(c_int)) en argtypes, se puede pasar un objeto de tipo puntero (c_int en este caso) a la función. ctypes aplicará la conversión byref() requerida en este caso automáticamente.

Para poner un campo de tipo POINTER a NULL, puedes asignar None:

>>> bar.values = None
>>>

A veces se tienen instancias de tipos incompatibles. En C, puedes cambiar un tipo por otro tipo. ctypes proporciona una función cast() qué puede ser usada de la misma manera. La estructura Bar definida arriba acepta punteros POINTER(c_int) o arreglos c_int` para su campo values, pero no instancias de otros tipos:

>>> bar.values = (c_byte * 4)()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: incompatible types, c_byte_Array_4 instance instead of LP_c_long instance
>>>

Para estos casos, la función cast() es muy útil.

La función cast() puede ser usada para lanzar una instancia ctypes en un puntero a un tipo de datos ctypes diferente. cast() toma dos parámetros, un objeto ctypes que es o puede ser convertido en un puntero de algún tipo, y un tipo de puntero ctypes. retorna una instancia del segundo argumento, que hace referencia al mismo bloque de memoria que el primer argumento:

>>> a = (c_byte * 4)()
>>> cast(a, POINTER(c_int))
<ctypes.LP_c_long object at ...>
>>>

Así, cast() puede ser usado para asignar al campo values de Bar la estructura:

>>> bar = Bar()
>>> bar.values = cast((c_byte * 4)(), POINTER(c_int))
>>> print(bar.values[0])
0
>>>

Tipos incompletos

Los Tipos Incompletos son estructuras, uniones o matrices cuyos miembros aún no están especificados. En C, se especifican mediante declaraciones a futuro, que se definen más adelante:

struct cell; /* forward declaration */

struct cell {
    char *name;
    struct cell *next;
};

La traducción directa al código de ctypes sería esta, pero no funciona:

>>> class cell(Structure):
...     _fields_ = [("name", c_char_p),
...                 ("next", POINTER(cell))]
...
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 2, in cell
NameError: name 'cell' is not defined
>>>

porque la nueva class cell no está disponible en la propia declaración de clase. En ctypes, podemos definir la clase cell y establecer el atributo _fields_ más tarde, después de la declaración de clase:

>>> from ctypes import *
>>> class cell(Structure):
...     pass
...
>>> cell._fields_ = [("name", c_char_p),
...                  ("next", POINTER(cell))]
>>>

Vamos a intentarlo. Creamos dos instancias de cell, y dejamos que se apunten una a la otra, y finalmente seguimos la cadena de punteros unas cuantas veces:

>>> c1 = cell()
>>> c1.name = b"foo"
>>> c2 = cell()
>>> c2.name = b"bar"
>>> c1.next = pointer(c2)
>>> c2.next = pointer(c1)
>>> p = c1
>>> for i in range(8):
...     print(p.name, end=" ")
...     p = p.next[0]
...
foo bar foo bar foo bar foo bar
>>>

Funciones de retrollamadas (callback)

ctypes permite crear punteros de función invocables C a partir de los invocables de Python. A veces se llaman funciones de retrollamada.

Primero, debes crear una clase para la función de retrollamada. La clase conoce la convención de llamada, el tipo de retorno, y el número y tipos de argumentos que esta función recibirá.

La función de fábrica CFUNCTYPE`() crea tipos para las funciones de retrollamada usando la convención de llamada cdecl. En Windows, la función de fábrica WINFUNCTYPE() crea tipos para funciones de retrollamadas usando la convención de llamadas stdcall.

Ambas funciones de fábrica se llaman con el tipo de resultado como primer argumento, y las funciones de llamada de retorno con los tipos de argumentos esperados como los argumentos restantes.

Presentaré un ejemplo aquí que utiliza la función qsort() de la biblioteca estándar de C, que se utiliza para ordenar los elementos con la ayuda de una función de retrollamada. qsort() se utilizará para ordenar un conjunto de números enteros:

>>> IntArray5 = c_int * 5
>>> ia = IntArray5(5, 1, 7, 33, 99)
>>> qsort = libc.qsort
>>> qsort.restype = None
>>>

qsort() debe ser llamada con un puntero a los datos a ordenar, el número de elementos en el array de datos, el tamaño de un elemento, y un puntero a la función de comparación, la llamada de retorno. La llamada de retorno se llamará entonces con dos punteros a los ítems, y debe retornar un entero negativo si el primer ítem es más pequeño que el segundo, un cero si son iguales, y un entero positivo en caso contrario.

Así que nuestra función de retrollamada recibe punteros a números enteros, y debe retornar un número entero. Primero creamos el tipo para la función de retrollamada:

>>> CMPFUNC = CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))
>>>

Para empezar, aquí hay una simple llamada que muestra los valores que se pasan:

>>> def py_cmp_func(a, b):
...     print("py_cmp_func", a[0], b[0])
...     return 0
...
>>> cmp_func = CMPFUNC(py_cmp_func)
>>>

El resultado:

>>> qsort(ia, len(ia), sizeof(c_int), cmp_func)
py_cmp_func 5 1
py_cmp_func 33 99
py_cmp_func 7 33
py_cmp_func 5 7
py_cmp_func 1 7
>>>

Ahora podemos comparar los dos artículos y obtener un resultado útil:

>>> def py_cmp_func(a, b):
...     print("py_cmp_func", a[0], b[0])
...     return a[0] - b[0]
...
>>>
>>> qsort(ia, len(ia), sizeof(c_int), CMPFUNC(py_cmp_func))
py_cmp_func 5 1
py_cmp_func 33 99
py_cmp_func 7 33
py_cmp_func 1 7
py_cmp_func 5 7
>>>

Como podemos comprobar fácilmente, nuestro arreglo está ordenado ahora:

>>> for i in ia: print(i, end=" ")
...
1 5 7 33 99
>>>

Las funciones de fabrica pueden ser usadas como decoradores de fabrica, así que podemos escribir:

>>> @CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))
... def py_cmp_func(a, b):
...     print("py_cmp_func", a[0], b[0])
...     return a[0] - b[0]
...
>>> qsort(ia, len(ia), sizeof(c_int), py_cmp_func)
py_cmp_func 5 1
py_cmp_func 33 99
py_cmp_func 7 33
py_cmp_func 1 7
py_cmp_func 5 7
>>>

Nota

Asegúrate de mantener las referencias a los objetos CFUNCTYPE() mientras se usen desde el código C. ctypes no lo hace, y si no lo haces, pueden ser basura recolectada, colapsando tu programa cuando se hace una llamada.

Además, nótese que sí se llama a la función de retrollamada en un hilo creado fuera del control de Python (por ejemplo, por el código foráneo que llama a la retrollamada), ctypes crea un nuevo hilo Python tonto en cada invocación. Este comportamiento es correcto para la mayoría de los propósitos, pero significa que los valores almacenados con threading.local no sobreviven a través de diferentes llamadas de retorno, incluso cuando esas llamadas se hacen desde el mismo hilo C.

Acceder a los valores exportados de los dlls

Algunas bibliotecas compartidas no sólo exportan funciones, sino también variables. Un ejemplo en la propia biblioteca de Python es el Py_OptimizeFlag, un entero establecido en 0, 1, o 2, dependiendo del flag -O o -OO dado en el inicio.

ctypes puede acceder a valores como este con los métodos de la clase in_dll() del tipo. pythonapi es un símbolo predefinido que da acceso a la API de Python C:

>>> opt_flag = c_int.in_dll(pythonapi, "Py_OptimizeFlag")
>>> print(opt_flag)
c_long(0)
>>>

Si el intérprete se hubiera iniciado con -O, el ejemplo habría impreso c_long(1), o c_long(2) si -OO se hubiera especificado.

Un ejemplo extendido que también demuestra el uso de punteros accediendo al puntero PyImport_FrozenModules exportado por Python.

Citando los documentos para ese valor:

Este puntero está inicializado para apuntar a un arreglo de registros struct _frozen`, terminada por uno cuyos miembros son todos NULL o cero. Cuando se importa un módulo congelado, se busca en esta tabla. El código de terceros podría jugar con esto para proporcionar una colección creada dinámicamente de módulos congelados.

Así que manipular este puntero podría incluso resultar útil. Para restringir el tamaño del ejemplo, sólo mostramos cómo esta tabla puede ser leída con ctypes:

>>> from ctypes import *
>>>
>>> class struct_frozen(Structure):
...     _fields_ = [("name", c_char_p),
...                 ("code", POINTER(c_ubyte)),
...                 ("size", c_int)]
...
>>>

Hemos definido el tipo de datos struct _frozen, para que podamos obtener el puntero de la tabla:

>>> FrozenTable = POINTER(struct_frozen)
>>> table = FrozenTable.in_dll(pythonapi, "PyImport_FrozenModules")
>>>

Como tabla` es un puntero al arreglo de registros struct_frozen, podemos iterar sobre ella, pero sólo tenemos que asegurarnos de que nuestro bucle termine, porque los punteros no tienen tamaño. Tarde o temprano, probablemente se caerá con una violación de acceso o lo que sea, así que es mejor salir del bucle cuando le demos a la entrada NULL:

>>> for item in table:
...     if item.name is None:
...         break
...     print(item.name.decode("ascii"), item.size)
...
_frozen_importlib 31764
_frozen_importlib_external 41499
__hello__ 161
__phello__ -161
__phello__.spam 161
>>>

El hecho de que la Python estándar tenga un módulo congelado y un paquete congelado (indicado por el miembro tamaño negativo) no se conoce bien, sólo se usa para hacer pruebas. Pruébalo con import __hello__ por ejemplo.

Sorpresas

Hay algunas aristas en ctypes en las que podrías esperar algo distinto de lo que realmente sucede.

Considere el siguiente ejemplo:

>>> from ctypes import *
>>> class POINT(Structure):
...     _fields_ = ("x", c_int), ("y", c_int)
...
>>> class RECT(Structure):
...     _fields_ = ("a", POINT), ("b", POINT)
...
>>> p1 = POINT(1, 2)
>>> p2 = POINT(3, 4)
>>> rc = RECT(p1, p2)
>>> print(rc.a.x, rc.a.y, rc.b.x, rc.b.y)
1 2 3 4
>>> # now swap the two points
>>> rc.a, rc.b = rc.b, rc.a
>>> print(rc.a.x, rc.a.y, rc.b.x, rc.b.y)
3 4 3 4
>>>

Hm. Ciertamente esperábamos que la última declaración imprimiera 3 4 1 2. ¿Qué ha pasado? Aquí están los pasos de la línea rc.a, rc.b = rc.b, rc.a arriba:

>>> temp0, temp1 = rc.b, rc.a
>>> rc.a = temp0
>>> rc.b = temp1
>>>

Note que temp0 y temp1 son objetos que todavía usan el buffer interno del objeto rc de arriba. Así que ejecutando rc.a = temp0 copia el contenido del buffer de temp0 en el buffer de rc. Esto, a su vez, cambia el contenido de temp1. Por lo tanto, la última asignación rc.b = temp1, no tiene el efecto esperado.

Tengan en cuenta que la recuperación de subobjetos de Estructuras, Uniones y Arreglos no copia el subobjeto, sino que recupera un objeto contenido que accede al búfer subyacente del objeto raíz.

Otro ejemplo que puede comportarse de manera diferente a lo que uno esperaría es este:

>>> s = c_char_p()
>>> s.value = b"abc def ghi"
>>> s.value
b'abc def ghi'
>>> s.value is s.value
False
>>>

Nota

Los objetos instanciados desde c_char_p sólo pueden tener su valor fijado en bytes o enteros.

¿Por qué está imprimiendo False? Las instancias ctypes son objetos que contienen un bloque de memoria más algunos descriptors que acceden al contenido de la memoria. Almacenar un objeto Python en el bloque de memoria no almacena el objeto en sí mismo, en su lugar se almacenan los contenidos del objeto. ¡Acceder a los contenidos de nuevo construye un nuevo objeto Python cada vez!

Tipos de datos de tamaño variable

ctypes proporciona algo de soporte para matrices y estructuras de tamaño variable.

La función resize() puede ser usada para redimensionar el buffer de memoria de un objeto ctypes existente. La función toma el objeto como primer argumento, y el tamaño solicitado en bytes como segundo argumento. El bloque de memoria no puede hacerse más pequeño que el bloque de memoria natural especificado por el tipo de objeto, se lanza un ValueError si se intenta:

>>> short_array = (c_short * 4)()
>>> print(sizeof(short_array))
8
>>> resize(short_array, 4)
Traceback (most recent call last):
    ...
ValueError: minimum size is 8
>>> resize(short_array, 32)
>>> sizeof(short_array)
32
>>> sizeof(type(short_array))
8
>>>

Esto está bien, pero ¿cómo se puede acceder a los elementos adicionales contenidos en este arreglo? Dado que el tipo todavía sabe sólo 4 elementos, obtenemos errores al acceder a otros elementos:

>>> short_array[:]
[0, 0, 0, 0]
>>> short_array[7]
Traceback (most recent call last):
    ...
IndexError: invalid index
>>>

Otra forma de utilizar tipos de datos de tamaño variable con ctypes es utilizar la naturaleza dinámica de Python, y (re)definir el tipo de datos después de que se conozca el tamaño requerido, caso por caso.

referencia ctypes

Encontrar bibliotecas compartidas

Cuando se programa en un lenguaje compilado, se accede a las bibliotecas compartidas cuando se compila/enlaza un programa, y cuándo se ejecuta el programa.

El propósito de la función find_library() es localizar una biblioteca de forma similar a lo que hace el compilador o el cargador en tiempo de ejecución (en plataformas con varias versiones de una biblioteca compartida se debería cargar la más reciente), mientras que los cargadores de bibliotecas ctypes actúan como cuando se ejecuta un programa, y llaman directamente al cargador en tiempo de ejecución.

El módulo ctypes.util proporciona una función que puede ayudar a determinar la biblioteca a cargar.

ctypes.util.find_library(name)

Intenta encontrar una biblioteca y retornar un nombre. name es el nombre de la biblioteca sin ningún prefijo como lib, sufijo como .so, .dylib o número de versión (esta es la forma usada para la opción del enlazador posix -l). Si no se puede encontrar ninguna biblioteca, retorna None.

La funcionalidad exacta depende del sistema.

En Linux, find_library() intenta ejecutar programas externos (/sbin/ldconfig, gcc, objdump y ld) para encontrar el archivo de la biblioteca. retorna el nombre del archivo de la biblioteca.

Distinto en la versión 3.6: En Linux, el valor de la variable de entorno LD_LIBRARY_PATH se utiliza cuando se buscan bibliotecas, si una biblioteca no puede ser encontrada por ningún otro medio.

Aquí hay algunos ejemplos:

>>> from ctypes.util import find_library
>>> find_library("m")
'libm.so.6'
>>> find_library("c")
'libc.so.6'
>>> find_library("bz2")
'libbz2.so.1.0'
>>>

On macOS, find_library() tries several predefined naming schemes and paths to locate the library, and returns a full pathname if successful:

>>> from ctypes.util import find_library
>>> find_library("c")
'/usr/lib/libc.dylib'
>>> find_library("m")
'/usr/lib/libm.dylib'
>>> find_library("bz2")
'/usr/lib/libbz2.dylib'
>>> find_library("AGL")
'/System/Library/Frameworks/AGL.framework/AGL'
>>>

En Windows, find_library`() busca a lo largo de la ruta de búsqueda del sistema, y retorna la ruta completa, pero como no hay un esquema de nombres predefinido, una llamada como find_library("c") fallará y retornará None.

Si envolvemos una biblioteca compartida con ctypes, puede ser mejor determinar el nombre de la biblioteca compartida en tiempo de desarrollo, y codificarlo en el módulo de envoltura en lugar de usar find_library() para localizar la biblioteca en tiempo de ejecución.

Cargando bibliotecas compartidas

Hay varias maneras de cargar las bibliotecas compartidas en el proceso Python. Una forma es instanciar una de las siguientes clases:

class ctypes.CDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=None)

Las instancias de esta clase representan bibliotecas compartidas cargadas. Las funciones de estas bibliotecas usan la convención estándar de llamada C, y se asume que retornan int.

En Windows, la creación de una instancia CDLL puede fallar incluso si existe el nombre de la DLL. Cuando no se encuentra una DLL dependiente de la DLL cargada, se lanza un error OSError con el mensaje «[WinError 126] No se pudo encontrar el módulo especificado». Este mensaje de error no contiene el nombre de DLL que falta porque la API de Windows no devuelve esta información, lo que dificulta el diagnóstico de este error. Para resolver este error y determinar qué DLL no se encuentra, debe buscar la lista de DLL dependientes y determinar cuál no se encuentra utilizando las herramientas de depuración y seguimiento de Windows.

Ver también

Herramienta Microsoft DUMPBIN [https://docs.microsoft.com/cpp/build/reference/dependents] – Una herramienta para encontrar dependientes de DLL.

class ctypes.OleDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=None)

Sólo Windows: Las instancias de esta clase representan bibliotecas compartidas cargadas, las funciones en estas bibliotecas usan la convención de llamada stdcall, y se asume que retornan el código específico de windows HRESULT`. Los valores HRESULT` contienen información que especifica si la llamada a la función falló o tuvo éxito, junto con un código de error adicional. Si el valor de retorno señala un fracaso, se eleva automáticamente un OSError`.

Distinto en la versión 3.3: WindowsError solía ser lanzado.

class ctypes.WinDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=None)

Sólo Windows: Las instancias de esta clase representan bibliotecas compartidas cargadas, las funciones de estas bibliotecas usan la convención de llamada stdcall, y se supone que retornan int por defecto.

El termino Python global interpreter lock es lanzado antes de llamar a cualquier función exportada por estas librerías, y se requiere después.

class ctypes.PyDLL(name, mode=DEFAULT_MODE, handle=None)

Las instancias de esta clase se comportan como instancias CDLL , excepto que el GIL de Python es no liberado durante la llamada a la función, y después de la ejecución de la función se comprueba si esta activo el flag de error de Python. Si el flag de error esta activado, se lanza una excepción Python.

Por lo tanto, esto sólo es útil para llamar directamente a las funciones api C de Python.

Todas estas clases pueden ser instanciadas llamándolas con al menos un argumento, la ruta de la biblioteca compartida. Si tienes un manejador existente de una biblioteca compartida ya cargada, se puede pasar como el parámetro llamado handle, de lo contrario la función dlopen o LoadLibrary de la plataforma subyacente es utilizada para cargar la biblioteca en el proceso, y obtener un manejador de la misma.

El parámetro mode puede utilizarse para especificar cómo se carga la biblioteca. Para más detalles, consulte la página dlopen(3) del manual. En Windows, mode es ignorado. En los sistemas posix, RTLD_NOW siempre se agrega, y no es configurable.

El parámetro use_errno, cuando se establece en true, habilita un mecanismo ctypes que permite acceder al número de error del sistema errno de forma segura. ctypes mantiene una copia local del hilo de la variable del sistema errno; si llamas a funciones extranjeras creadas con use_errno=True entonces el valor errno antes de la llamada a la función se intercambia con la copia privada de ctypes, lo mismo ocurre inmediatamente después de la llamada a la función.

La función ctypes.get_errno() retorna el valor de la copia privada de ctypes, y la función ctypes.set_errno() cambia la copia privada de ctypes a un nuevo valor y retorna el valor anterior.

El parámetro use_last_error, cuando se establece en true, habilita el mismo mecanismo para el código de error de Windows que es administrado por las funciones de la API de Windows GetLastError() y SetLastError(); ctypes.get_last_error() y ctypes.set_last_error() se utilizan para solicitar y cambiar la copia privada ctypes del código de error de Windows.

El parámetro winmode se utiliza en Windows para especificar cómo se carga la biblioteca (ya que mode se ignora). Toma cualquier valor que sea válido para el parámetro flags de la API de Win32 LoadLibraryEx. Cuando se omite, el valor por defecto es usar los flags que resultan en la carga de DLL más segura para evitar problemas como el secuestro de DLL. Pasar la ruta completa a la DLL es la forma más segura de asegurar que se cargan la biblioteca y las dependencias correctas.

Distinto en la versión 3.8: Añadido el parámetro winmode.

ctypes.RTLD_GLOBAL

Flag para usar como parámetro modo. En las plataformas en las que esta bandera no está disponible, se define como el cero entero.

ctypes.RTLD_LOCAL

Flag para usar como parámetro modo. En las plataformas en las que esto no está disponible, es lo mismo que RTLD_GLOBAL.

ctypes.DEFAULT_MODE

El modo por defecto que se utiliza para cargar las bibliotecas compartidas. En OSX 10.3, esto es RTLD_GLOBAL, de lo contrario es lo mismo que RTLD_LOCAL.

Las instancias de estas clases no tienen métodos públicos. Se puede acceder a las funciones exportadas por la biblioteca compartida como atributos o por índice. Tenga en cuenta que al acceder a la función a través de un atributo se almacena en caché el resultado y, por lo tanto, al acceder a él repetidamente se retorna el mismo objeto cada vez. Por otro lado, acceder a ella a través de un índice retorna un nuevo objeto cada vez:

>>> from ctypes import CDLL
>>> libc = CDLL("libc.so.6")  # On Linux
>>> libc.time == libc.time
True
>>> libc['time'] == libc['time']
False

Los siguientes atributos públicos están disponibles, su nombre comienza con un guión bajo para no chocar con los nombres de las funciones exportadas:

PyDLL._handle

El manejador del sistema usado para acceder a la biblioteca.

PyDLL._name

El nombre de la biblioteca pasado en el constructor.

Las bibliotecas compartidas también pueden ser cargadas usando uno de los objetos prefabricados, que son instancias de la clase LibraryLoader, ya sea llamando al método LoadLibrary(), o recuperando la biblioteca como atributo de la instancia de carga.

class ctypes.LibraryLoader(dlltype)

Clase que carga bibliotecas compartidas. dlltype debe ser uno de los tipos CDLL, PyDLL, WinDLL, o OleDLL.

__getattr__() tiene un comportamiento especial: Permite cargar una biblioteca compartida accediendo a ella como atributo de una instancia de carga de biblioteca. El resultado se almacena en caché, de modo que los accesos repetidos a los atributos retornan la misma biblioteca cada vez.

LoadLibrary(name)

Carga una biblioteca compartida en el proceso y la retorna. Este método siempre retorna una nueva instancia de la biblioteca.

Estos cargadores prefabricados de bibliotecas están disponibles:

ctypes.cdll

Crea instancias de CDLL.

ctypes.windll

Sólo Windows: Crea instancias de WinDLL.

ctypes.oledll

Sólo Windows: Crea instancias de OleDLL.

ctypes.pydll

Crea instancias de PyDLL.

Para acceder directamente a la API C de Python, se dispone de un objeto de biblioteca compartida de Python listo-para-usar:

ctypes.pythonapi

Una instancia de PyDLL que expone las funciones de la API C de Python como atributos. Ten en cuenta que se supone que todas estas funciones retornan C int, lo que por supuesto no siempre es cierto, así que tienes que asignar el atributo correcto restype para usar estas funciones.

Lanza un auditing event ctypes.dlopen con argumento name.

Al acceder a una función en una biblioteca cargada se lanza un evento de auditoría ctypes.dlsym con argumentos library (el objeto de la biblioteca) y name (el nombre del símbolo como cadena o entero).

En los casos en los que sólo está disponible el manejador de la biblioteca en lugar del objeto, al acceder a una función se produce un evento de auditoría ctypes.dlsym/handle con los argumentos handle (el manejador de la biblioteca en bruto) y name.

Funciones foráneas

Como se explicó en la sección anterior, se puede acceder a las funciones foráneas como atributos de las bibliotecas compartidas cargadas. Los objetos de función creados de esta forma aceptan por defecto cualquier número de argumentos, aceptan cualquier instancia de datos ctypes como argumentos y retornan el tipo de resultado por defecto especificado por el cargador de la biblioteca. Son instancias de una clase privada:

class ctypes._FuncPtr

Clase base para funciones foráneas C invocables.

Las instancias de funciones foráneas también son tipos de datos compatibles con C; representan punteros de funciones C.

Este comportamiento puede personalizarse asignando a los atributos especiales del objeto de la función foránea.

restype

Asigne un tipo de ctypes para especificar el tipo de resultado de la función externa. Usa None para void, una función que no retorna nada.

Es posible asignar un objeto Python invocable que no sea de tipo ctypes, en este caso se supone que la función retorna un C int, y el invocable se llamará con este entero, lo que permite un posterior procesamiento o comprobación de errores. El uso de esto está obsoleto, para un postprocesamiento más flexible o para la comprobación de errores utilice un tipo de datos ctypes como restype y asigne un invocable al atributo errcheck.

argtypes

Asigne una tupla de tipos ctypes para especificar los tipos de argumentos que acepta la función. Las funciones que utilizan la convención de llamada stdcall sólo pueden ser llamadas con el mismo número de argumentos que la longitud de esta tupla; las funciones que utilizan la convención de llamada C aceptan también argumentos adicionales no especificados.

Cuando se llama a una función foránea, cada argumento real se pasa al método de la clase from_param() de los elementos de la tupla argtypes, este método permite adaptar el argumento real a un objeto que la función externa acepta. Por ejemplo, un elemento c_char_p de la tupla argtypes convertirá una cadena pasada como argumento en un objeto de bytes utilizando reglas de conversión ctypes.

Nuevo: Ahora es posible poner en argtypes elementos que no son de tipo ctypes, pero cada elemento debe tener un método from_param() que retorne un valor utilizable como argumento (entero, cadena, instancia ctypes). Esto permite definir adaptadores que pueden adaptar objetos personalizados como parámetros de la función.

errcheck

Asigne una función Python u otra llamada a este atributo. El invocable será llamado con tres o más argumentos:

callable(result, func, arguments)

result es lo que retorna la función externa, como se especifica en el atributo restype.

func es el propio objeto de la función foránea, lo que permite reutilizar el mismo objeto invocable para comprobar o postprocesar los resultados de varias funciones.

arguments es una tupla que contiene los parámetros originalmente pasados a la llamada de la función, esto permite especializar el comportamiento en los argumentos utilizados.

El objeto que retorna esta función será retornado por la llamada de la función foránea, pero también puede comprobar el valor del resultado y hacer una excepción si la llamada de la función foránea ha fallado.

exception ctypes.ArgumentError

Esta excepción se lanza cuando una llamada a una función foránea no puede convertir uno de los argumentos pasados.

En Windows, cuando una llamada a una función foránea plantea una excepción de sistema (por ejemplo, debido a una violación de acceso), será capturada y sustituida por una excepción Python adecuada. Además, un evento de auditoría ctypes.seh_exception con el argumento code será levantado, permitiendo que un gancho de auditoría reemplace la excepción con la suya propia.

Algunas formas de invocar llamadas a funciones foráneas pueden lanzar un evento de auditoría ctypes.call_function con los argumentos function pointer y arguments.

Prototipos de funciones

Las funciones foráneas también pueden crearse mediante la instanciación de prototipos de funciones. Los prototipos de funciones son similares a los prototipos de funciones en C; describen una función (tipo de retorno, tipos de argumentos, convención de llamada) sin definir una implementación. Las funciones de fábrica deben ser llamadas con el tipo de resultado deseado y los tipos de argumento de la función, y pueden ser usadas como fábricas de decoradores, y como tales, ser aplicadas a las funciones a través de la sintaxis @wrapper. Ver Funciones de retrollamadas (callback) para ejemplos.

ctypes.CFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False)

El prototipo de función retornado crea funciones que usan la convención de llamada C estándar. La función liberará el GIL durante la llamada. Si use_errno se configura a true, la copia privada de ctypes de la variable del sistema errno se intercambia con el valor real errno antes y después de la llamada; use_last_error hace lo mismo con el código de error de Windows.

ctypes.WINFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False)

Windows only: The returned function prototype creates functions that use the stdcall calling convention. The function will release the GIL during the call. use_errno and use_last_error have the same meaning as above.

ctypes.PYFUNCTYPE(restype, *argtypes)

El prototipo de función retornado crea funciones que usan la convención de llamadas de Python. La función no liberará el GIL durante la llamada.

Los prototipos de funciones creados por estas funciones de fábrica pueden ser instanciados de diferentes maneras, dependiendo del tipo y el número de los parámetros en la llamada:

prototype(address)

Retorna una función foránea en la dirección especificada que debe ser un número entero.

prototype(callable)

Crear una función de llamada C (una función de retrollamada) a partir de un callable Python.

prototype(func_spec[, paramflags])

Retorna una función foránea exportada por una biblioteca compartida. func_spec debe ser un 2-tupla (name_or_ordinal, library). El primer elemento es el nombre de la función exportada como cadena, o el ordinal de la función exportada como entero pequeño. El segundo elemento es la instancia de la biblioteca compartida.

prototype(vtbl_index, name[, paramflags[, iid]])

Retorna una función foránea que llamará a un método COM. vtbl_index es el índice de la tabla de funciones virtuales, un pequeño entero no negativo. name es el nombre del método COM. iid es un puntero opcional para el identificador de la interfaz que se utiliza en el informe de errores extendido.

Los métodos COM usan una convención especial de llamadas: Requieren un puntero a la interfaz COM como primer argumento, además de los parámetros que se especifican en la tupla argtypes.

El parámetro opcional paramflags crea envoltorios de funciones foráneas con mucha más funcionalidad que las características descritas anteriormente.

paramflags deben ser una tupla de la misma longitud que argtypes.

Cada elemento de esta tupla contiene más información sobre un parámetro, debe ser una tupla que contenga uno, dos o tres elementos.

El primer elemento es un entero que contiene una combinación de flags de dirección para el parámetro:

1

Especifica un parámetro de entrada a la función.

2

Parámetro de salida. La función foránea rellena un valor.

4

Parámetro de entrada que por defecto es el cero entero.

El segundo elemento opcional es el nombre del parámetro como cadena. Si se especifica esto, se puede llamar a la función foránea con parámetros con nombre.

El tercer elemento opcional es el valor por defecto de este parámetro.

Este ejemplo demuestra cómo envolver la función MessageBoxW de Windows para que soporte los parámetros por defecto y los argumentos con nombre. La declaración C del archivo de cabecera de Windows es esta:

WINUSERAPI int WINAPI
MessageBoxW(
    HWND hWnd,
    LPCWSTR lpText,
    LPCWSTR lpCaption,
    UINT uType);

Aquí está el envoltorio con ctypes:

>>> from ctypes import c_int, WINFUNCTYPE, windll
>>> from ctypes.wintypes import HWND, LPCWSTR, UINT
>>> prototype = WINFUNCTYPE(c_int, HWND, LPCWSTR, LPCWSTR, UINT)
>>> paramflags = (1, "hwnd", 0), (1, "text", "Hi"), (1, "caption", "Hello from ctypes"), (1, "flags", 0)
>>> MessageBox = prototype(("MessageBoxW", windll.user32), paramflags)

La función foránea de MessageBox puede ser llamada de esta manera:

>>> MessageBox()
>>> MessageBox(text="Spam, spam, spam")
>>> MessageBox(flags=2, text="foo bar")

Un segundo ejemplo demuestra los parámetros de salida. La función GetWindowRect de win32 retorna las dimensiones de una ventana especificada copiándolas en la estructura RECT que la persona que llama tiene que suministrar. Aquí está la declaración C:

WINUSERAPI BOOL WINAPI
GetWindowRect(
     HWND hWnd,
     LPRECT lpRect);

Aquí está el envoltorio con ctypes:

>>> from ctypes import POINTER, WINFUNCTYPE, windll, WinError
>>> from ctypes.wintypes import BOOL, HWND, RECT
>>> prototype = WINFUNCTYPE(BOOL, HWND, POINTER(RECT))
>>> paramflags = (1, "hwnd"), (2, "lprect")
>>> GetWindowRect = prototype(("GetWindowRect", windll.user32), paramflags)
>>>

Las funciones con parámetros de salida retornarán automáticamente el valor del parámetro de salida si hay uno solo, o una tupla que contiene los valores del parámetro de salida cuando hay más de uno, por lo que la función GetWindowRect retorna ahora una instancia RECT, cuando se llama.

Los parámetros de salida pueden combinarse con el protocolo errcheck para hacer un mayor procesamiento de la salida y la comprobación de errores. La función api de win32 GetWindowRect retorna un BOOL para señalar el éxito o el fracaso, por lo que esta función podría hacer la comprobación de errores, y plantea una excepción cuando la llamada api ha fallado:

>>> def errcheck(result, func, args):
...     if not result:
...         raise WinError()
...     return args
...
>>> GetWindowRect.errcheck = errcheck
>>>

Si la función errcheck retorna la tupla de argumentos que recibe sin cambios, ctypes continúa el procesamiento normal que hace en los parámetros de salida. Si quieres retornar una tupla de coordenadas de ventana en lugar de una instancia RECT, puedes recuperar los campos de la función y retornarlos en su lugar, el procesamiento normal ya no tendrá lugar:

>>> def errcheck(result, func, args):
...     if not result:
...         raise WinError()
...     rc = args[1]
...     return rc.left, rc.top, rc.bottom, rc.right
...
>>> GetWindowRect.errcheck = errcheck
>>>

Funciones de utilidad

ctypes.addressof(obj)

Retorna la dirección del buffer de memoria como un entero. obj debe ser una instancia de tipo ctypes.

Lanza un auditing event ctypes.addressof con el argumento obj.

ctypes.alignment(obj_or_type)

Retorna los requerimientos de alineación de un tipo de ctypes. obj_or_type debe ser un tipo o instancia ctypes.

ctypes.byref(obj[, offset])

Retorna un puntero ligero a obj, que debe ser un ejemplo de un tipo de ctypes. offset es por defecto cero, y debe ser un entero que se añadirá al valor del puntero interno.

byref(obj, offset) corresponde a este código C:

(((char *)&obj) + offset)

El objeto retornado sólo puede ser utilizado como un parámetro de llamada de función foránea. Se comporta de manera similar a pointer(obj), pero la construcción es mucho más rápida.

ctypes.cast(obj, type)

Esta función es similar a la del operador de reparto en C. retorna una nueva instancia de type que apunta al mismo bloque de memoria que obj. type debe ser un tipo de puntero, y obj debe ser un objeto que pueda ser interpretado como un puntero.

ctypes.create_string_buffer(init_or_size, size=None)

Esta función crea un búfer de caracteres mutables. El objeto retornado es un arreglo de ctypes de c_char.

init_or_size debe ser un número entero que especifique el tamaño del arreglo, o un objeto de bytes que se utilizará para inicializar los elementos del arreglo.

Si se especifica un objeto bytes como primer argumento, el buffer se hace un elemento más grande que su longitud, de modo que el último elemento del arreglo es un carácter de terminación NUL. Se puede pasar un entero como segundo argumento que permite especificar el tamaño del arreglo si no se debe utilizar la longitud de los bytes.

Lanza un auditing event ctypes.create_string_buffer con argumentos init, size.

ctypes.create_unicode_buffer(init_or_size, size=None)

Esta función crea un búfer de caracteres unicode mutable. El objeto retornado es un arreglo de ctypes de c_wchar.

init_or_size debe ser un entero que especifique el tamaño del arreglo, o una cadena que se utilizará para inicializar los elementos del arreglo.

Si se especifica una cadena como primer argumento, el búfer se hace un elemento más grande que la longitud de la cadena, de modo que el último elemento del arreglo es un carácter de terminación NUL. Se puede pasar un entero como segundo argumento que permite especificar el tamaño del arreglo si no se debe utilizar la longitud de la cadena.

Lanza un auditing event ctypes.create_unicode_buffer con argumentos init, size.

ctypes.DllCanUnloadNow()

Sólo Windows: Esta función es un gancho que permite implementar servidores COM en proceso con ctypes. Se llama desde la función DllCanUnloadNow que la extensión _ctypes dll exporta.

ctypes.DllGetClassObject()

Sólo Windows: Esta función es un gancho que permite implementar servidores COM en proceso con ctypes. Se llama desde la función DllGetClassObject que la extensión _ctypes exporta.

ctypes.util.find_library(name)

Intenta encontrar una biblioteca y retornar un nombre de ruta. name es el nombre de la biblioteca sin ningún prefijo como lib, sufijo como .so, .dylib o número de versión (esta es la forma usada para la opción del enlazador posix -l). Si no se puede encontrar ninguna biblioteca, retorna None.

La funcionalidad exacta depende del sistema.

ctypes.util.find_msvcrt()

Sólo Windows: retorna el nombre de archivo de la biblioteca de tiempo de ejecución de VC usada por Python, y por los módulos de extensión. Si no se puede determinar el nombre de la biblioteca, se retorna None.

Si necesita liberar memoria, por ejemplo, asignada por un módulo de extensión con una llamada al free(void *), es importante que utilice la función en la misma biblioteca que asignó la memoria.

ctypes.FormatError([code])

Sólo Windows: retorna una descripción textual del código de error code. Si no se especifica ningún código de error, se utiliza el último código de error llamando a la función de api de Windows GetLastError.

ctypes.GetLastError()

Sólo Windows: retorna el último código de error establecido por Windows en el hilo de llamada. Esta función llama directamente a la función GetLastError() de Windows, no retorna la copia ctypes-private del código de error.

ctypes.get_errno()

Retorna el valor actual de la copia ctypes-private de la variable de sistema errno en el hilo de llamada.

Lanza un auditing event ctypes.get_errno sin argumentos.

ctypes.get_last_error()

Sólo Windows: retorna el valor actual de la copia ctypes-private de la variable de sistema LastError en el hilo de llamada.

Lanza un auditing event ctypes.get_last_error sin argumentos.

ctypes.memmove(dst, src, count)

Igual que la función de la biblioteca estándar de C memmove: copia count bytes de src a dst. dst y src deben ser enteros o instancias ctypes que pueden ser convertidos en punteros.

ctypes.memset(dst, c, count)

Igual que la función de la biblioteca estándar de C memset C: llena el bloque de memoria en la dirección dst con count bytes de valor c. dst debe ser un número entero que especifique una dirección, o una instancia ctypes.

ctypes.POINTER(type)

Esta función de fábrica crea y retorna un nuevo tipo de puntero ctypes. Los tipos de puntero se almacenan en caché y se reutilizan internamente, por lo que llamar a esta función repetidamente es barato. type debe ser un tipo ctypes.

ctypes.pointer(obj)

Esta función crea una nueva instancia de puntero, apuntando a obj. El objeto retornado es del tipo POINTER(tipo(obj)).

Nota: Si sólo quieres pasar un puntero a un objeto a una llamada de función foránea, deberías usar byref(obj) que es mucho más rápido.

ctypes.resize(obj, size)

Esta función redimensiona el búfer de memoria interna de obj, que debe ser una instancia de tipo ctypes. No es posible hacer el buffer más pequeño que el tamaño nativo del tipo de objetos, como lo indica size of (type(obj)), pero es posible agrandar el buffer.

ctypes.set_errno(value)

Poner el valor actual de la copia ctypes-private de la variable del sistema errno en el hilo de llamada a valor y retornar el valor anterior.

Lanza un auditing event ctypes.set_errno con argumento errno.

ctypes.set_last_error(value)

Sólo para Windows: pone el valor actual de la copia ctypes-private de la variable del sistema LastError en el hilo de llamada a valor y retorna el valor anterior.

Lanza un auditing event ctypes.set_last_error con argumento error.

ctypes.sizeof(obj_or_type)

Retorna el tamaño en bytes de un buffer de memoria tipo ctypes o instancia. Hace lo mismo que el operador C sizeof.

ctypes.string_at(address, size=-1)

Esta función retorna la cadena C que comienza en la dirección de memoria address como un objeto de bytes. Si se especifica el tamaño, se utiliza como tamaño, de lo contrario se asume que la cadena tiene un final cero.

Lanza un auditing event ctypes.string_at con argumentos address, size.

ctypes.WinError(code=None, descr=None)

Sólo para Windows: esta función es probablemente la cosa peor nombrada de los ctypes. Crea una instancia de OSError. Si no se especifica el code, se llama a GetLastError para determinar el código de error. Si no se especifica descr, se llama a FormatError`() para obtener una descripción textual del error.

Distinto en la versión 3.3: Una instancia de WindowsError solía ser creada.

ctypes.wstring_at(address, size=-1)

Esta función retorna la cadena de caracteres anchos que comienza en la dirección de memoria address como una cadena. Si se especifica size, se utiliza como el número de caracteres de la cadena, de lo contrario se asume que la cadena tiene un final cero.

Lanza un auditing event ctypes.wstring_at con argumentos address, size.

Tipos de datos

class ctypes._CData

Esta clase no pública es la clase de base común de todos los tipos de datos de los ctypes. Entre otras cosas, todas las instancias de tipo ctypes contienen un bloque de memoria que contiene datos compatibles con C; la dirección del bloque de memoria es retornada por la función de ayuda addressof(). Otra variable de instancia se expone como _objetos; ésta contiene otros objetos de Python que deben mantenerse vivos en caso de que el bloque de memoria contenga punteros.

Métodos comunes de tipos de datos ctypes, estos son todos métodos de clase (para ser exactos, son métodos del metaclass):

from_buffer(source[, offset])

Este método retorna una instancia ctypes que comparte el buffer del objeto source. El objeto source debe soportar la interfaz del buffer de escritura. El parámetro opcional offset especifica un offset en el buffer de la fuente en bytes; el valor por defecto es cero. Si el buffer de la fuente no es lo suficientemente grande se lanza un ValueError.

Lanza un auditing event ctypes.cdata/buffer con argumentos pointer, size, offset.

from_buffer_copy(source[, offset])

Este método crea una instancia ctypes, copiando el buffer del buffer de objetos source que debe ser legible. El parámetro opcional offset especifica un offset en el buffer de origen en bytes; el valor por defecto es cero. Si el buffer de fuente no es lo suficientemente grande se lanza un ValueError.

Lanza un auditing event ctypes.cdata/buffer con argumentos pointer, size, offset.

from_address(address)

Este método retorna una instancia de tipo ctypes utilizando la memoria especificada por address que debe ser un entero.

Lanza un auditing event ctypes.cdata con argumento address.

from_param(obj)

Este método adapta el obj a un tipo de ctypes. Se llama con el objeto real usado en una llamada a una función externa cuando el tipo está presente en la tupla argtypes de la función foránea; debe retornar un objeto que pueda ser usado como parámetro de llamada a la función.

Todos los tipos de datos ctypes tienen una implementación por defecto de este método de clase que normalmente retorna obj si es una instancia del tipo. Algunos tipos aceptan también otros objetos.

in_dll(library, name)

Este método retorna una instancia de tipo ctypes exportada por una biblioteca compartida. name es el nombre del símbolo que exporta los datos, library es la biblioteca compartida cargada.

Variables de instancia común de los tipos de datos de ctypes:

_b_base_

A veces, las instancias de datos ctypes no poseen el bloque de memoria que contienen, sino que comparten parte del bloque de memoria de un objeto base. El miembro de sólo lectura _b_base_ es el objeto raíz ctypes que posee el bloque de memoria.

_b_needsfree_

Esta variable de sólo lectura es verdadera cuando la instancia de datos ctypes ha sido asignada a el propio bloque de memoria, falsa en caso contrario.

_objects

Este miembro es None o un diccionario que contiene objetos de Python que deben mantenerse vivos para que el contenido del bloque de memoria sea válido. Este objeto sólo se expone para su depuración; nunca modifique el contenido de este diccionario.

Tipos de datos fundamentales

class ctypes._SimpleCData

Esta clase no pública es la clase base de todos los tipos de datos de ctypes fundamentales. Se menciona aquí porque contiene los atributos comunes de los tipos de datos de ctypes fundamentales. _SimpleCData es una subclase de _CData, por lo que hereda sus métodos y atributos. Los tipos de datos ctypes que no son y no contienen punteros ahora pueden ser archivados.

Los instancias tienen un solo atributo:

value

Este atributo contiene el valor real de la instancia. Para los tipos enteros y punteros, es un entero, para los tipos de caracteres, es un objeto o cadena de bytes de un solo carácter, para los tipos de punteros de caracteres es un objeto o cadena de bytes de Python.

Cuando el atributo value se recupera de una instancia ctypes, normalmente se retorna un nuevo objeto cada vez. ctypes no implementa el retorno del objeto original, siempre se construye un nuevo objeto. Lo mismo ocurre con todas las demás instancias de objetos ctypes.

Los tipos de datos fundamentales, cuando se retornan como resultados de llamadas de funciones foráneas, o, por ejemplo, al recuperar miembros de campo de estructura o elementos de arreglos, se convierten de forma transparente a tipos nativos de Python. En otras palabras, si una función externa tiene un restype de c_char_p, siempre recibirá un objeto de bytes Python, no una instancia de c_char_p.

Las subclases de los tipos de datos fundamentales no heredan este comportamiento. Así, si una función externa restype es una subclase de c_void_p, recibirás una instancia de esta subclase desde la llamada a la función. Por supuesto, puedes obtener el valor del puntero accediendo al atributo value.

Estos son los tipos de datos fundamentales de ctypes:

class ctypes.c_byte

Representa el tipo de datos C signed char, e interpreta el valor como un entero pequeño. El constructor acepta un inicializador de entero opcional; no se hace ninguna comprobación de desbordamiento.

class ctypes.c_char

Representa el tipo de datos C char, e interpreta el valor como un solo carácter. El constructor acepta un inicializador de cadena opcional, la longitud de la cadena debe ser exactamente un carácter.

class ctypes.c_char_p

Representa el tipo de datos C char * cuando apunta a una cadena terminada en cero. Para un puntero de carácter general que también puede apuntar a datos binarios, se debe usar POINTER(c_char). El constructor acepta una dirección entera, o un objeto de bytes.

class ctypes.c_double

Representa el tipo de datos C double. El constructor acepta un inicializador flotante opcional.

class ctypes.c_longdouble

Representa el tipo de datos C long double. El constructor acepta un inicializador flotante opcional. En las plataformas donde sizeof(long double) == sizeof(double) es un alias de c_double.

class ctypes.c_float

Representa el tipo de datos C float. El constructor acepta un inicializador flotante opcional.

class ctypes.c_int

Representa el tipo de datos C signed int. El constructor acepta un inicializador entero opcional; no se hace ninguna comprobación de desbordamiento. En plataformas donde sizeof(int) == sizeof(long) es un alias de c_long.

class ctypes.c_int8

Representa el tipo de datos C 8-bit signed int. Normalmente un alias para c_byte.

class ctypes.c_int16

Representa el tipo de datos C 16-bit signed int. Normalmente un alias para c_short.

class ctypes.c_int32

Representa el tipo de datos C 32-bit signed int. Normalmente un alias para c_int.

class ctypes.c_int64

Representa el tipo de datos C 64-bit signed int. Normalmente un alias para c_longlong.

class ctypes.c_long

Representa el tipo de datos C signed long. El constructor acepta un inicializador entero opcional; no se hace ninguna comprobación de desbordamiento.

class ctypes.c_longlong

Representa el tipo de datos C significado long long. El constructor acepta un inicializador entero opcional; no se hace ninguna comprobación de desbordamiento.

class ctypes.c_short

Representa el tipo de datos C signed short. El constructor acepta un inicializador entero opcional; no se hace ninguna comprobación de desbordamiento.

class ctypes.c_size_t

Representa el tipo de datos C size_t.

class ctypes.c_ssize_t

Representa el tipo de datos C ssize_t.

Nuevo en la versión 3.2.

class ctypes.c_ubyte

Representa el tipo de datos C unsigned char, interpreta el valor como un entero pequeño. El constructor acepta un inicializador entero opcional; no se hace ninguna comprobación de desbordamiento.

class ctypes.c_uint

Representa el tipo de datos C unsigned int. El constructor acepta un inicializador entero opcional; no se hace ninguna comprobación de desbordamiento. En plataformas donde sizeof(int) == sizeof(long) es un alias para c_ulong.

class ctypes.c_uint8

Representa el tipo de datos C 8-bit unsigned int. Normalmente un alias para c_ubyte.

class ctypes.c_uint16

Representa el tipo de datos C 16-bit unsigned int. Normalmente un alias para c_ushort.

class ctypes.c_uint32

Representa el tipo de datos C 32-bit unsigned int. Normalmente un alias para c_uint.

class ctypes.c_uint64

Representa el tipo de datos C 64-bit unsigned int. Normalmente un alias para c_ulonglong.

class ctypes.c_ulong

Representa el tipo de datos C unsigned long. El constructor acepta un inicializador entero opcional; no se hace ninguna comprobación de desbordamiento.

class ctypes.c_ulonglong

Representa el tipo de datos C unsigned long long. El constructor acepta un inicializador entero opcional; no se hace ninguna comprobación de desbordamiento.

class ctypes.c_ushort

Representa el tipo de datos C unsigned short. El constructor acepta un inicializador entero opcional; no se hace ninguna comprobación de desbordamiento.

class ctypes.c_void_p

Representa el tipo C void *. El valor se representa como un entero. El constructor acepta un inicializador entero opcional.

class ctypes.c_wchar

Representa el tipo de datos C wchar_t, e interpreta el valor como una cadena unicode de un solo carácter. El constructor acepta un inicializador de cadena opcional, la longitud de la cadena debe ser exactamente de un carácter.

class ctypes.c_wchar_p

Representa el tipo de datos C wchar_t *, que debe ser un puntero a una cadena de caracteres anchos con terminación cero. El constructor acepta una dirección entera, o una cadena.

class ctypes.c_bool

Representa el tipo de datos C bool (más exactamente, _Bool de C99). Su valor puede ser True o False, y el constructor acepta cualquier objeto que tenga un valor verdadero.

class ctypes.HRESULT

Sólo Windows: Representa un valor HRESULT , que contiene información de éxito o error para una llamada de función o método.

class ctypes.py_object

Representa el tipo de datos C PyObject *. Llamar esto sin un argumento crea un puntero NULL PyObject *.

El módulo ctypes.wintypes proporciona otros tipos de datos específicos de Windows, por ejemplo HWND, WPARAM, o DWORD. Algunas estructuras útiles como MSG o RECT también están definidas.

Tipos de datos estructurados

class ctypes.Union(*args, **kw)

Clase base abstracta para uniones en orden de bytes nativos.

class ctypes.BigEndianStructure(*args, **kw)

Clase base abstracta para estructuras en orden de bytes big endian.

class ctypes.LittleEndianStructure(*args, **kw)

Clase base abstracta para estructuras en orden de bytes little endian.

Las estructuras con un orden de bytes no nativo no pueden contener campos de tipo puntero, o cualquier otro tipo de datos que contenga campos de tipo puntero.

class ctypes.Structure(*args, **kw)

Clase base abstracta para estructuras en orden de bytes native.

La estructura concreta y los tipos de unión deben crearse subclasificando uno de estos tipos, y al menos definir una variable de clase _fields_. ctypes creará descriptors que permitan leer y escribir los campos por accesos directos de atributos. Estos son los

_fields_

Una secuencia que define los campos de estructura. Los elementos deben ser de 2 o 3 tuplas. El primer ítem es el nombre del campo, el segundo ítem especifica el tipo de campo; puede ser cualquier tipo de datos ctypes.

Para los campos de tipo entero como c_int, se puede dar un tercer elemento opcional. Debe ser un pequeño entero positivo que defina el ancho de bit del campo.

Los nombres de los campos deben ser únicos dentro de una estructura o unión. Esto no se comprueba, sólo se puede acceder a un campo cuando los nombres se repiten.

Es posible definir la variable de clase _fields_ después de la sentencia de clase que define la subclase Estructura, esto permite crear tipos de datos que se refieren directa o indirectamente a sí mismos:

class List(Structure):
    pass
List._fields_ = [("pnext", POINTER(List)),
                 ...
                ]

Sin embargo, la variable de clase _fields_ debe ser definida antes de que el tipo sea usado por primera vez (se crea una instancia, se llama a sizeof(), y así sucesivamente). Las asignaciones posteriores a la variable de clase _fields_ lanzarán un AttributeError.

Es posible definir subclases de tipos de estructura, que heredan los campos de la clase base más el _fields_ definido en la subclase, si existe.

_pack_

Un pequeño entero opcional que permite anular la alineación de los campos de estructura en la instancia. _pack_ ya debe estar definido cuando se asigna _fields_, de lo contrario no tendrá ningún efecto.

_anonymous_

Una secuencia opcional que enumera los nombres de los campos sin nombre (anónimos). _anonymous_ debe estar ya definida cuando se asigna _fields_, de lo contrario no tendrá ningún efecto.

Los campos listados en esta variable deben ser campos de tipo estructura o unión. ctypes creará descriptores en el tipo de estructura que permitan acceder a los campos anidados directamente, sin necesidad de crear el campo de estructura o unión.

Aquí hay un tipo de ejemplo (Windows):

class _U(Union):
    _fields_ = [("lptdesc", POINTER(TYPEDESC)),
                ("lpadesc", POINTER(ARRAYDESC)),
                ("hreftype", HREFTYPE)]

class TYPEDESC(Structure):
    _anonymous_ = ("u",)
    _fields_ = [("u", _U),
                ("vt", VARTYPE)]

La estructura TYPEDESC describe un tipo de datos COM, el campo vt especifica cuál de los campos de unión es válido. Como el campo u está definido como campo anónimo, ahora es posible acceder a los miembros directamente desde la instancia TYPEDESC. td.lptdesc y td.u.lptdesc son equivalentes, pero el primero es más rápido ya que no necesita crear una instancia de unión temporal:

td = TYPEDESC()
td.vt = VT_PTR
td.lptdesc = POINTER(some_type)
td.u.lptdesc = POINTER(some_type)

Es posible definir subclases de estructuras, que heredan los campos de la clase base. Si la definición de la subclase tiene una variable _fields_ separada, los campos especificados en ella se añaden a los campos de la clase base.

Los constructores de estructuras y uniones aceptan tanto argumentos posicionales como de palabras clave. Los argumentos posicionales se usan para inicializar los campos de los miembros en el mismo orden en que aparecen en _fields_. Los argumentos de palabras clave en el constructor se interpretan como asignaciones de atributos, por lo que inicializarán _fields_ con el mismo nombre, o crearán nuevos atributos para nombres no presentes en _fields_.

Arreglos y punteros

class ctypes.Array(*args)

Clase base abstracta para arreglos.

The recommended way to create concrete array types is by multiplying any ctypes data type with a non-negative integer. Alternatively, you can subclass this type and define _length_ and _type_ class variables. Array elements can be read and written using standard subscript and slice accesses; for slice reads, the resulting object is not itself an Array.

_length_

Un número entero positivo que especifica el número de elementos del conjunto. Los subíndices fuera de rango dan como resultado un IndexError. Será retornado por len().

_type_

Especifica el tipo de cada elemento del arreglo.

Los constructores de subclases de arreglos aceptan argumentos posicionales, usados para inicializar los elementos en orden.

class ctypes._Pointer

Clase base, privada y abstracta para punteros.

Los tipos de punteros concretos se crean llamando a POINTER() con el tipo que será apuntado; esto se hace automáticamente por pointer().

Si un puntero apunta a un arreglo, sus elementos pueden ser leídos y escritos usando accesos de subíndices y cortes estándar. Los objetos punteros no tienen tamaño, así que len() lanzará un TypeError. Los subíndices negativos se leerán de la memoria antes que el puntero (como en C), y los subíndices fuera de rango probablemente se bloqueen con una violación de acceso (si tienes suerte).

_type_

Especifica el tipo apuntado.

contents

Retorna el objeto al que el puntero apunta. Asignando a este atributo cambia el puntero para que apunte al objeto asignado.

Ejecución concurrente

Los módulos descritos en este capítulo proveen soporte para la ejecución concurrente de código. La elección de qué herramienta utilizar depende de la tarea a ejecutar (vinculada a CPU o vinculada a E/S) y del estilo preferido de desarrollo (multi-tarea cooperativa o multi-tarea apropiativa). A continuación se muestra un resumen:

threading — Paralelismo basado en hilos

Datos locales del hilo

Objetos tipo hilo

Objetos tipo lock

Objetos Rlock

Objetos condicionales

Objetos semáforo

Ejemplo de Semaphore

Objetos de eventos

Objetos temporizadores

Objetos de barrera

Uso de locks, condiciones y semáforos en la declaración with

multiprocessing — Paralelismo basado en procesos

Introducción

La clase Process

Contextos y métodos de inicio

Intercambiando objetos entre procesos

Sincronización entre procesos

Compartiendo estado entre procesos

Usando una piscina de trabajadores (pool of workers)

Referencia

Process y excepciones

Tuberías (Pipes) y Colas (Queues)

Miscelánea

Objetos de conexión Connection Objects

Primitivas de sincronización (Synchronization primitives)

Objetos compartidos ctypes

El módulo multiprocessing.sharedctypes

Administradores (Managers)

Administradores customizables (Customized managers)

Utilizando un administrador remoto

Objetos Proxy (Proxy Objects)

Limpieza (Cleanup)

Piscinas de procesos (Process Pools)

Oyentes y Clientes (Listeners and Clients)

Formatos de dirección (Address formats)

Llaves de autentificación

Logging

El módulo multiprocessing.dummy

Pautas de programación

Todos los métodos de inicio

Los métodos de inicio spawn y forkserver

Ejemplos

multiprocessing.shared_memory — Proporciona memoria compartida para acceso directo a través de procesos

El paquete concurrent

concurrent.futures — Lanzamiento de tareas paralelas

Objetos Ejecutores

ThreadPoolExecutor

Ejemplo de ThreadPoolExecutor

ProcessPoolExecutor

Ejemplo de ProcessPoolExecutor

Objetos Futuro

Funciones del Módulo

Clases de Excepciones

subprocess — Gestión de subprocesos

Uso del módulo subprocess

Argumentos frecuentemente empleados

El constructor de Popen

Excepciones

Consideraciones sobre seguridad

Objetos Popen

Elementos auxiliares de Popen en Windows

Constantes de Windows

Antigua API de alto nivel

Cómo reemplazar anteriores funciones con el módulo subprocess

Cómo reemplazar la sustitución de órdenes de /bin/sh

Cómo remplazar los flujos de la shell

Cómo reemplazar os.system()

Cómo reemplazar la familia os.spawn

Cómo reemplazar os.popen(), os.popen2(), os.popen3()

Cómo reemplazar las funciones del módulo popen2

Funciones de llamada a la shell de retrocompatibilidad

Notas

Cómo convertir una secuencia de argumentos a una cadena en Windows

sched — Eventos del planificador

Objetos de Scheduler

queue — clase de cola sincronizada

Objetos de la cola

Objetos de cola simple

contextvars — Variables de Contexto

Variables de Contexto

Gestión de Contexto Manual

Soporte asyncio

He aquí módulos de apoyo para algunos de los servicios mencionados:

_thread — API de bajo nivel para manejo de hilos

threading — Paralelismo basado en hilos

Código fuente: Lib/threading.py [https://github.com/python/cpython/tree/3.9/Lib/threading.py]

Este módulo construye interfaces de hilado de alto nivel sobre el módulo de más bajo nivel _thread. Ver también el módulo queue.

Distinto en la versión 3.7: Este módulo solía ser opcional, ahora está siempre disponible.

Nota

Aunque no están listados en lo que sigue, los nombres en camelCase usados para algunos de los métodos y funciones de la versión Python 2.x todavía son soportados por este módulo.

CPython implementation detail: In CPython, due to the Global Interpreter Lock, only one thread can execute Python code at once (even though certain performance-oriented libraries might overcome this limitation). If you want your application to make better use of the computational resources of multi-core machines, you are advised to use multiprocessing or concurrent.futures.ProcessPoolExecutor. However, threading is still an appropriate model if you want to run multiple I/O-bound tasks simultaneously.

Este módulo define las siguientes funciones:

threading.active_count()

Retorna el número de objetos Thread actualmente con vida. La cuenta retornada es igual al largo de la lista retornada por enumerate().

threading.current_thread()

Retorna el objeto Thread actual, correspondiente al hilo de control del invocador. Si el hilo de control del invocador no fue creado a través del módulo threading, se retorna un objeto hilo dummy con funcionalidad limitada.

threading.excepthook(args, /)

Gestiona una excepción lanzada por Thread.run().

El argumento args posee los siguientes atributos:

exc_type: Tipo de la excepción.

exc_value: Valor de la excepción, puede ser None.

exc_traceback: Rastreo de la excepción, puede ser None.

thread: El hilo que ha lanzado la excepción, puede ser None.

Si exc_type es SystemExit, la excepción es silenciosamente ignorada. De otro modo, la excepción se imprime en sys.stderr.

Si esta función lanza una excepción, se llama a sys.excepthook() para manejarla.

threading.excepthook() se puede sobrescribir para controlar cómo se gestionan las excepciones levantadas por Thread.run().

Guarda exc_value usando un hook personalizado puede crear un ciclo de referencias. Debe ser aclarado explícitamente que se rompa el ciclo de referencias cuando la excepción ya no se necesite.

Guarda thread usando un hook personalizado puede resucitarlo si se asigna a un objeto que esté siendo finalizado. Evítese que thread sea almacenado después de que el hook personalizado se complete para evitar resucitar objetos.

Ver también

sys.excepthook() gestiona excepciones no capturadas.

Nuevo en la versión 3.8.

threading.get_ident()

Retorna el “identificador de hilo” del hilo actual. Éste es un entero distinto de cero. Su valor no tiene un significado directo; ha sido pensado como una cookie mágica para usarse, por ejemplo, en indexar un diccionario con datos específicos del hilo. Los identificadores de hilo pueden ser reciclados cuando se abandona un hilo y se crea otro hilo.

Nuevo en la versión 3.3.

threading.get_native_id()

Retorna la ID de Hilo (Thread ID) nativo integral del hilo actual asignado por el kernel. Ella es un entero distinto de cero. Su valor puede utilizarse para identificar de forma única a este hilo en particular a través de todo el sistema (hasta que el hilo termine, luego de lo cual el valor puede ser reciclado por el SO).

Disponibilidad: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX.

Nuevo en la versión 3.8.

threading.enumerate()

Return a list of all Thread objects currently active. The list includes daemonic threads and dummy thread objects created by current_thread(). It excludes terminated threads and threads that have not yet been started. However, the main thread is always part of the result, even when terminated.

threading.main_thread()

Retorna el objeto Thread principal. En condiciones normales, el hilo principal es el hilo desde el que fue inicializado el intérprete de Python.

Nuevo en la versión 3.4.

threading.settrace(func)

Establece una función de traza para todos los hilos iniciados desde el módulo threading . La func se pasará a sys.settrace() por cada hilo, antes de que su método run() sea llamado.

threading.setprofile(func)

Establece una función de perfil para todos los hilos iniciados desde el módulo threading. La func se pasará a sys.setprofile() por cada hilo, antes de que se llame a su método run().

threading.stack_size([size])

Retorna el tamaño de pila usado para crear nuevos hilos. El argumento opcional size (tamaño) especifica el tamaño de pila a ser utilizado para hilos creados posteriormente, y debe ser 0 (usar el valor por defecto de la plataforma o el configurado) o un valor entero positivo de al menos 32.768 (32KiB). Si no se especifica size, se usará 0. Si no existe soporte para cambiar el tamaño de pila, se lanzará un RuntimeError. Si el tamaño de pila especificado es inválido, se lanzará un ValueError y el tamaño de pila no será modificado. El tamaño mínimo de pila actualmente soportado es de 32KiB para garantizar suficiente espacio de pila para el intérprete mismo. Nótese que algunas plataformas pueden tener restricciones particulares de valores para tamaños de pila, como requerir un tamaño de pila > 32KiB, o requerir una asignación en múltiplos del tamaño de página de la memoria del sistema. Debe consultarse la documentación de cada plataforma para mayor información (páginas de 4KiB son comunes; se recomienda el uso de múltiplos de 4096 para el tamaño de pila en ausencia de información más específica)

Disponibilidad: Windows, sistemas con hilos POSIX.

Este módulo también define la siguiente constante:

threading.TIMEOUT_MAX

El máximo valor permitido para el parámetro timeout de las funciones bloqueantes (Lock.acquire(), RLock.acquire(), Condition.wait(), etc.). La especificación de un tiempo de espera mayor a este valor lanzará un OverflowError.

Nuevo en la versión 3.2.

Este módulo define un número de clases, las cuales son detalladas en las siguientes secciones.

El diseño de este módulo está libremente basado en el modelo de threading de Java. Sin embargo, donde Java hace de locks y variables condicionales el comportamiento básico de cada objeto, éstos son objetos separados en Python. La clase de Python Thread soporta un subdominio del comportamiento de la clase Thread de Java; actualmente, no hay prioridades, ni grupos de hilos, y los hilos no pueden ser destruidos, detenidos, suspendidos, retomados o interrumpidos. Los métodos estáticos de la clase Thread de Java, cuando son implementados, son mapeados a funciones a nivel de módulo.

Todos los métodos descritos abajo son ejecutados de manera atómica.

Datos locales del hilo

Los datos locales de hilo son datos cuyos valores son específicos a cada hilo. Para manejar los datos locales de hilos, simplemente crear una instancia de local (o una subclase) y almacenar los atributos en ella:

mydata = threading.local()
mydata.x = 1

Los valores de instancia serán diferentes para hilos distintos.

class threading.local

Una clase que representa datos locales de hilo.

Para más detalles y ejemplos extensivos, véase la documentación del módulo _threading_local.

Objetos tipo hilo

La clase Thread representa una actividad que corre en un hilo de control separado. Hay dos manera de especificar la actividad: pasando un objeto invocable al constructor, o sobrescribiendo el método run() en una subclase. Ningún otro método (a excepción del constructor) deberá ser sobrescrito en una subclase. En otras palabras, solo sobrescribir los métodos __init__() y run() de esta clase.

Una vez que un objeto thread es creado, su actividad debe ser iniciada llamando al método start() del hilo. Ésto invoca el método run() en un hilo de control separado.

Una vez que la actividad del hilo ha sido iniciada, el hilo se considerará “vivo”. Deja de estar vivo cuando su método run() termina – ya sea normalmente, o por lanzar una excepción no manejada. El método is_alive() verifica si acaso el hilo está vivo.

Otros hilos pueden llamar al método join() de un hilo. Esto bloquea el hilo llamador hasta que el hilo cuyo método join() ha sido llamado termine.

Un hilo tiene un nombre. El nombre puede ser pasado al constructor y leído o cambiado a través del atributo name.

Si el método run() lanza una excepción, se llama a threading.excepthook() para gestionarla. Por defecto, threading.excepthook() ignora silenciosamente a SystemExit.

Un hilo puede ser marcado como un «hilo demonio». El significado de esta marca es que la totalidad del programa de Python finalizará cuando solo queden hilos demonio. El valor inicial es heredado del hilo creador. La marca puede ser establecida a través de la propiedad daemon o del argumento daemon en el constructor.

Nota

Los hilos demonio son detenidos abruptamente al momento del cierre. Sus recursos (tales como archivos abiertos, transacciones con bases de datos, etc.) pueden no ser liberados adecuadamente. Si se requiere que los hilos se detengan con gracia, háganse no-demoníacos y úsese un mecanismo de señalización adecuado tal como un Event.

Existe un objeto «hilo principal»; éste corresponde al hilo de control inicial del programa de Python. No es un hilo demonio.

Existe la posibilidad de crear «objetos de hilos dummy». Estos son objetos hilo correspondientes a «hilos extranjeros», que son hilos de control iniciados afuera del modulo threading, por ejemplo directamente de código en C. Los objetos de hilos dummy tienen funcionalidad limitada; siempre se consideran vivos y demoníacos, y no pueden se les puede aplicar el método join(). Nunca son eliminados, ya que es imposible detectar la terminación de hilos extranjeros.

class threading.Thread(group=None, target=None, name=None, args=(), kwargs={}, *, daemon=None)

Este constructor siempre debe ser llamado con argumentos de palabra clave. Los argumentos son:

group debe ser None; reservado para una futura extensión cuando se implemente una clase ThreadGroup.

target es el objeto invocable a ser invocado por el método run(). Por defecto es None, lo que significa que nada es llamado.

name es el nombre del hilo. Por defecto, se construye un nombre único con la forma «Thread-N» donde N es un número decimal pequeño.

args es la tupla de argumento para la invocación objetivo. Por defecto es ().

kwargs es un diccionario de argumentos de palabra clave para la invocación objetivo. Por defecto es {}.

Si no es None, daemon establece explícitamente si el hilo es demoníaco. Si es None (el valor por defecto), la propiedad demoníaca es heredada del hilo actual.

Si la subclase sobrescribe el constructor, debe asegurarse de invocar al constructor de la clase base (Thread.__init__()) antes de hacer cualquier otra cosa al hilo.

Distinto en la versión 3.3: Se agregó el argumento daemon.

start()

Inicia la actividad del hilo.

Debe ser llamada máximo una vez por objeto hilo. Se encarga de que el método run() del objeto sea invocado en un hilo de control separado.

Este método lanzará un RuntimeError si se llama más de una vez en el mismo objeto hilo.

run()

Método que representa la actividad del hilo.

Se puede sobrescribir este método en una subclase. El método estándar run() invoca el objeto invocable pasado al constructor del objeto como argumento target, si lo hay, con argumentos posicionales y de palabra clave tomados de los argumentos args y kwargs, respectivamente.

join(timeout=None)

Espera a que el hilo termine. Esto bloquea el hilo llamador hasta que el hilo cuyo método join() es llamado finalice – ya sea normalmente o a través de una excepción no gestionada – o hasta que el tiempo de espera opcional caduque.

Cuando se presenta un argumento timeout y no es None, debe ser un número de punto flotante que especifique un tiempo de espera en segundos (o en fracciones de segundo) para la operación . Ya que join() siempre retorna None, se debe llamar a is_alive() después de join() para decidir si acaso caducó el tiempo de espera – si el hilo todavía está vivo, la llamada a join() caducó.

Cuando el argumento timeout no se presenta o es None, la operación bloqueará hasta que el hilo termine.

A un hilo se le puede aplicar join() muchas veces.

join() lanza un RuntimeError si se intenta unir el hilo actual ya que ello generaría un punto muerto. También es un error aplicar join() a un hilo antes de que haya sido iniciado y los intentos de hacerlo lanzaran la misma excepción.

name

Un string utilizado con propósitos de identificación. No posee semántica. Se puede dar el mismo nombre a múltiples hilos. El nombre inicial es establecido por el constructor.

getName()

setName()

Antigua API getter/setter para name; úsese en cambio directamente como una propiedad.

ident

El “identificador de hilo” de este hilo o None si el hilo no ha sido iniciado. Es un entero distinto de cero. Ver la función get_ident(). Los identificadores de hilos pueden ser reciclados cuando un hilo finaliza y otro hilo es creado. El identificador está disponible incuso después de que el hilo ha abandonado.

native_id

La ID integral nativa de este hilo. Es un entero no negativo, o None si el hilo no ha sido iniciado. Ver la función get_native_id(). Ésta representa la Thread ID (TID) tal como haya sido asignada al hilo por el SO (kernel). Su valor puede puede ser utilizado para identificar específicamente a este hilo en particular a través de todo el sistema (hasta que el hilo termina, luego de lo cual el valor puede ser reciclado por el SO).

Nota

Similar a las Process IDs, las Thread IDs sólo son válidas (garantizadas como únicas a través de todo el sistema) desde el momento en que se crea el hilo hasta que el hilo es finalizado.

Disponibilidad: Requiere la función get_native_id().

Nuevo en la versión 3.8.

is_alive()

Retornar si acaso el hilo está vivo.

Este método retorna True desde justo antes de que el método run() inicie hasta junto antes de que el método run() termine. La función enumerate() del módulo retorna una lista de todos los hilos vivos.

daemon

Un valor booleano que indica si este hilo es un hilo demonio (True) o no (False). Debe ser establecido antes de que se llame a start(), de lo contrario se lanzará un RuntimeError. Su valor inicial se hereda del hilo creador; el hilo principal no es un hilo demonio y por lo tanto todos los hilos creados en el hilo principal tienen por defecto un valor daemon = False.

El programa de Python en su totalidad finaliza cuando no queda ningún hilo no-demonio vivo.

isDaemon()

setDaemon()

Antigua API getter/setter para daemon; úsese en cambio directamente como una propiedad.

Objetos tipo lock

Una primitiva lock, es una primitiva de sincronización que no pertenece a ningún hilo en particular cuando está cerrado. En Python, es la primitiva de sincronización de más bajo nivel actualmente disponible, implementado directamente por el módulo de extensión _thread.

Una primitiva lock está en uno de dos estados, «cerrado» o «abierto» (locked/unlocked). Se crea en estado abierto. Tiene dos métodos básicos, acquire() (adquirir) y release() (liberar). Cuando el estado es abierto, acquire() cambia el estado a cerrado y retorna inmediatamente. Cuando el estado es cerrado, acquire() bloquea hasta que una llamada a release() en otro hilo lo cambie a abierto, luego la llamada a acquire() lo restablece a cerrado y retorna. El método release() sólo debe ser llamado en el estado cerrado; cambia el estado a abierto y retorna inmediatamente. Si se realiza un intento de liberar un lock abierto, se lanzará un RuntimeError.

Los locks también soportan el protocolo de gestión de contexto.

Cuando más de un hilo está bloqueado en acquire() esperando que el estado sea abierto, sólo un hilo procederá cuando una llamada a release() restablezca el estado a abierto; cuál de los hilos en espera procederá no está definido, y puede variar a través de las implementaciones.

Todos los métodos se ejecutan de manera atómica.

class threading.Lock

La clase que implemente los objetos de la primitiva lock. Una vez que un hilo ha adquirido un lock, intentos subsecuentes por adquirirlo bloquearán, hasta que sea liberado; cualquier hilo puede liberarlo.

Nótese que Lock es una función de fábrica que retorna una instancia de la versión más eficiente de la clase Lock concreta soportada por la plataforma.

acquire(blocking=True, timeout=-1)

Adquirir un lock, bloqueante o no bloqueante.

Cuando se invoca con el argumento blocking establecido como True (el valor por defecto), bloquea hasta que el lock se abra, luego lo establece como cerrado y retorna True.

Cuando es invocado con el argumento blocking como False, no bloquea. Si una llamada con blocking establecido como True bloqueara, retorna Falso inmediatamente; de otro modo, cierra el lock y retorna True.

Cuando se invoca con el argumento de punto flotante timeout fijado a un valor positivo, bloquea por a lo más el número de segundos especificado en timeout y mientras el lock no pueda ser adquirido. Un argumento timeout de «-1» especifica una espera ilimitada. No está admitido especificar un timeout cuando blocking es falso.

El valor de retorno es True si el lock es adquirido con éxito, Falso si no (por ejemplo si timeout expiró).

Distinto en la versión 3.2: El parámetro timeout es nuevo.

Distinto en la versión 3.2: La adquisición de un lock ahora puede ser interrumpida por señales en POSIX si la implementación de hilado subyacente lo soporta.

release()

Libera un lock. Puede ser llamado desde cualquier hilo, no solo el hilo que ha adquirido el lock.

Cuando el lock está cerrado, lo restablece a abierto, y retorna. Si cualquier otro hilo está bloqueado esperando que el lock se abra, permite que exactamente uno de ellos proceda.

Cuando se invoca en un lock abierto, se lanza un RuntimeError.

No hay valor de retorno.

locked()

Retorna true si el lock ha sido adquirido.

Objetos Rlock

Un lock reentrante es una primitiva de sincronización que puede ser adquirido múltiples veces por el mismo hilo. Internamente, utiliza el concepto de «hilo dueño» y «nivel de recursividad» además del estado abierto/cerrado utilizado por las primitivas locks. Si está en estado cerrado, algún hilo es dueño del lock; si está en estado abierto, ningún hilo es dueño.

Para cerrar el lock, un hilo llama a su método acquire(); esto retorna una vez que el hilo se ha adueñado del lock. Para abrir el lock, un hilo llama a su método release(). Pares de llamadas acquire()/release() pueden anidarse; sólo el release() final (el release() del par más externo) restablece el lock a abierto y permite que otro hilo bloqueado en acquire() proceda.

Los locks reentrantes también soportan el protocolo de manejo de contextos.

class threading.RLock

Esta clase implementa objetos tipo lock reentrantes. Un lock reentrante debe ser liberado por el hilo que lo adquirió. Una vez que un hilo ha adquirido un lock reentrante, el mismo hilo puede adquirirlo otra vez sin bloquearse; el hilo debe liberarlo una vez por vez que lo adquiere.

Nótese que RLock en realidad es una función fábrica que retorna una instancia de la versión más eficiente de la clase RLock concreta que sea soportada por la plataforma.

acquire(blocking=True, timeout=-1)

Adquirir un lock, bloqueante o no bloqueante.

Cuando se invoca sin argumentos: si este hilo ya es dueño del lock, incrementa el nivel de recursividad en uno, y retorna inmediatamente. De otro modo, si otro hilo es dueño del lock, bloquea hasta que se abra el lock. Una vez que el lock se abra (ningún hilo sea su dueño), se adueña, establece el nivel de recursividad en uno, y retorna. Si más de un hilo está bloqueado esperando que sea abra el lock, solo uno a la vez podrá apoderarse del lock. No hay valor de retorno en este caso.

Cuando se invoca con el argumento blocking fijado en true, hace lo mismo que cuando se llama sin argumentos y retorna True.

Cuando se invoca con el argumento blocking fijado a falso, no bloquea. Si una llamada sin argumento bloquease, retorna False inmediatamente; de otro modo, hace lo mismo que al llamarse sin argumentos, y retorna True.

Cuando se invoca con el argumento de coma flotante timeout fijado a un valor positivo, bloquea por máximo el número de segundos especificado por timeout y mientras el lock no pueda ser adquirido. Retorna True si el lock ha sido adquirido, falso si el tiempo de espera timeout ha caducado.

Distinto en la versión 3.2: El parámetro timeout es nuevo.

release()

Libera un lock, disminuyendo el nivel de recursividad. Si después de la disminución es cero, restablece el lock a abierto (no perteneciente a ningún hilo), y si cualquier otro hilo está bloqueado esperando que se abra el lock, permite que exactamente uno de ellos proceda. Si luego de la disminución el nivel de recursividad todavía no es cero, el lock permanece cerrado y perteneciente al hilo llamador.

Solo llámese este método cuando el hilo llamador sea dueño del lock. Se lanza un RuntimeError si se llama este método cuando el lock esta abierto.

No hay valor de retorno.

Objetos condicionales

Una condición variable siempre va asociada a algún tipo de lock. éste puede ser provisto o se creará uno por defecto. Proveer uno es útil cuando varias variables de condición deben compartir el mismo lock. El lock es parte del objeto condicional: no es necesario rastrearlo por separado.

Una condición variable obedece el protocolo de gestión de contexto: al usar la declaración with se adquiere el lock asociado por la duración del bloque contenido. Los métodos acquire() y release() también llaman los métodos correspondientes del lock asociado.

Otros métodos deben llamarse con el lock asociado conservado. El método wait() libera el lock, y luego bloquea hasta que otro hilo lo despierte llamando notify() o notify_all(). Una vez que ha sido despertado, wait() re-adquiere el lock y retorna. También es posible especificar un tiempo de espera.

El método notify() despierta a uno de los hilos que esperan a la condición variable, si es que alguno espera. El método notify_all() despierta a todos los hilos que estén esperando a la condición variable.

Nota: Los métodos notify() y notify_all() no liberan el lock; esto significa que el hilo o los hilos que han sido despertados no retornaran de su llamada de wait() inmediatamente, sino solo una vez que el hilo que haya llamado a notify() o notify_all() renuncie finalmente a la propiedad del lock.

El estilo típico de programación con variables condicionales utiliza el lock para sincronizar el acceso a algún estado compartido; hilos que estén interesados en un cambio de estado en particular llamarán a wait() reiteradamente hasta que vean el estado deseado, mientras que los hilos que modifiquen el estado llamarán a notify() o a notify_all() cuando cambien el estado de modo que pudiera ser que el el estado sea el deseado por alguno de los hilos en espera. Por ejemplo, el siguiente código es una situación genérica de productor-consumidor con capacidad de búfer ilimitada:

# Consume one item
with cv:
    while not an_item_is_available():
        cv.wait()
    get_an_available_item()

# Produce one item
with cv:
    make_an_item_available()
    cv.notify()

El bucle while que verifica la condición de la aplicación es necesario porque wait() puede retornar después de una cantidad arbitraria de tiempo, y la condición que dio pie a la llamada de notify() puede ya no ser verdadera. Esto es inherente a la programación multi-hilo. El método wait_for() puede usarse para automatizar la revisión de condiciones, y facilita la computación de tiempos de espera:

# Consume an item
with cv:
    cv.wait_for(an_item_is_available)
    get_an_available_item()

Para elegir entre notify() y notify_all(), considérese si un cambio de estado puede ser interesante para uno o varios hilos en espera. Por ejemplo en una típica situación productor-consumidor, agregar un elemento al búfer sólo necesita despertar un hilo consumidor.

class threading.Condition(lock=None)

Esta clase implementa objetos de condición variable. Una condición variable permite que uno o más hilos esperen hasta que sean notificados por otro hilo.

Si se provee un argumento lock distinto de None, debe ser un objeto Lock o RLock, y se utiliza como el lock subyacente. De otro modo, se crea un nuevo objeto RLock y se utiliza como el lock subyacente.

Distinto en la versión 3.3: cambiado de función de fábrica a una clase.

acquire(*args)

Adquiere el lock subyacente. Este método llama al método correspondiente sobre el lock subyacente; el valor de retorno es lo que retorne aquel método.

release()

Libera el lock subyacente. Este método llama al método correspondiente en el lock subyacente; no tiene valor de retorno.

wait(timeout=None)

Espera hasta ser notificado o hasta que el tiempo de espera caduque. Si el hilo invocador no ha adquirido el lock cuando este método es llamado, se lanza un RuntimeError.

Este método libera el lock subyacente, y luego bloquea hasta ser despertado por una llamada a notify() o notify_all() para la misma condición variable en otro hilo, o hasta que el tiempo de espera opcional se cumpla. Una vez que ha sido despertado o el tiempo de espera ha pasado, re-adquiere el lock y retorna.

Cuando haya un argumento timeout presente y no sea None, debe ser un número de punto flotante que especifique un tiempo de espera para la operación en segundos (o fracciones de segundo).

Cuando el lock subyacente es un RLock, no se libera utilizando su método release(), ya que esto podría no abrir realmente el lock cuando haya sido adquirido múltiples veces recursivamente. En cambio, se usa una interfaz interna de la clase RLock, que lo abre realmente incluso cuando haya sido adquirido múltiples veces recursivamente. Otra interfaz interna se usa luego para restablecer el nivel de recursividad cuando el lock es readquirido.

El valor de retorno es True a menos que un timeout dado haya expirado, en cuyo caso será False.

Distinto en la versión 3.2: Previamente, el método siempre retornaba None.

wait_for(predicate, timeout=None)

Espera a que una condición se evalúe como verdadera. predicate debe ser un invocable cuyo resultado se interpretará como un valor booleano. Se puede proveer un timeout que especifique el máximo tiempo de espera.

Este método utilitario puede llamar a wait() reiteradas veces hasta que se satisfaga el predicado, o hasta que la espera caduque. El valor de retorno es el último valor de retorno del predicado y se evaluará a False si el método ha caducado.

Al ignorar la propiedad feature, llamar a este método equivale vagamente a escribir:

while not predicate():
    cv.wait()

Por ende, aplican las mismas reglas que con wait(): El lock debe ser conservado cuando se llame y es re-adquirido al momento del retorno. El predicado se evalúa con el lock conservado.

Nuevo en la versión 3.2.

notify(n=1)

Por defecto, despierta a un hilo que esté esperando por esta condición, si lo existe. Si el hilo llamador no ha adquirido el lock cuando se llama este método, se lanza un RuntimeError.

Este método despierta como máximo n de los hilos que estén esperando por la condición variable; no es una opción si no hay hilos esperando.

La implementación actual despierta exactamente n hilos, si hay por lo menos n hilos esperando. Sin embargo, no es seguro apoyarse en este comportamiento. A futuro, una implementación optimizada podría ocasionalmente despertar a más de n hilos.

Nota: un hilo que ha sido despertado no retorna realmente de su llamada a wait() hasta que pueda readquirir el lock. Ya que notify() no libera el lock, su llamador debiera hacerlo.

notify_all()

Despierta a todos los hilos que esperen por esta condición. Este método actúa como notify(), pero despierta a todos los hilos en espera en vez de a uno. Si el hilo llamador no ha adquirido el lock cuando se llama a este método, se lanza un RuntimeError.

Objetos semáforo

Éste es uno de las primitivas de sincronización más antiguos en la historia de las ciencias de la computación, inventado por el pionero en ciencias de la computación holandés Edsger W. Dijkstra (él utilizó los nombres P() y V() en lugar de acquire() y release())

Un semáforo administra un contador interno que se disminuye por cada llamada a acquire() y se incrementa por cada llamada a release(). El contador no puede bajar de cero; cuando acquire() lo encuentra en cero, bloquea, esperando hasta que otro hilo llame release().

Los semáforos también tienen soporte para el protocolo de gestión de contexto.

class threading.Semaphore(value=1)

Esta clase implementa los objetos semáforo. Un semáforo gestiona un contador atómico que representa el número de llamadas a release() menos el número de llamadas a acquire(), más un valor inicial. El método acquire() bloquea si es necesario, hasta que pueda retornar sin volver el contador negativo. Si no es provisto, el valor por defecto de value será 1.

El argumento opcional da el value inicial al contador interno; por defecto es 1. Si el value provisto es menor a 0; se lanza un ValueError.

Distinto en la versión 3.3: cambiado de función de fábrica a una clase.

acquire(blocking=True, timeout=None)

Adquirir un semáforo.

Cuando se invoca sin argumentos:

Si el contador interno es mayor a cero de entrada, lo disminuye en uno y retorna True inmediatamente.

Si el contador interno es cero de entrada, bloquea hasta ser despertado por una llamada a release(). Una vez despierto (y el contador sea mayor a 0), disminuye el contador en 1 y retorna True. Se despertará exactamente un hilo por cada llamada a release(). No debiese confiarse en el orden en que los hilos sean despertados.

Cuando se invoca con blocking fijado en falso, no bloquea. Si una llamada sin un argumento bloquease, retorna Falso inmediatamente; de otro modo, hace lo mismo que cuando se llama sin argumentos, y retorna True.

Cuando se invoca con timeout distinto de None, bloqueará por un tiempo máximo en segundos fijados en timeout. Si acquire no se completa exitosamente en ese intervalo, retorna False. De otro modo retorna True.

Distinto en la versión 3.2: El parámetro timeout es nuevo.

release(n=1)

Release a semaphore, incrementing the internal counter by n. When it was zero on entry and other threads are waiting for it to become larger than zero again, wake up n of those threads.

Distinto en la versión 3.9: Added the n parameter to release multiple waiting threads at once.

class threading.BoundedSemaphore(value=1)

Clase que implementa objetos de semáforo delimitados. Un semáforo delimitado verifica que su valor actual no exceda su valor inicial. Si lo hace, se lanza un ValueError. En la mayoría de las situaciones se utilizan los semáforos para cuidar recursos con capacidad limitada. Si se libera el semáforo demasiadas veces es signo de un bug. Si no se provee, el valor por defecto de value será 1.

Distinto en la versión 3.3: cambiado de función de fábrica a una clase.

Ejemplo de Semaphore

Los semáforos suelen utilizarse para cuidar recursos con capacidad limitada, por ejemplo, un servidor de base de datos. En cualquier situación en que el tamaño de los recursos sea fijo, se debe usar un semáforo delimitado. Antes de generar cualquier hilo de trabajo, tu hilo principal debe inicializar el semáforo:

maxconnections = 5
# ...
pool_sema = BoundedSemaphore(value=maxconnections)

Una vez que han sido generados, los hilos de trabajo llaman a los métodos acquire y release cuando necesitan conectarse al servidor:

with pool_sema:
    conn = connectdb()
    try:
        # ... use connection ...
    finally:
        conn.close()

El uso de semáforos delimitados reduce la posibilidad de que pase inadvertido un error de programación que cause que el semáforo sea liberado más veces de las que sea adquirido.

Objetos de eventos

Éste es uno de los mecanismos más simples de comunicación entre hilos: un hilo señala un evento y otro hilo lo espera.

Un objeto de evento maneja una marca interna que puede ser establecida como verdadera mediante el método set() y restablecida a falsa mediante el método clear(). El método wait() bloquea hasta que la marca sea true.

class threading.Event

Clase que implementa los objetos de evento. Un evento gestiona un indicador que puede ser establecido a verdadero mediante el método set() y restablecido a falso con el método clear(). El método wait() bloquea hasta que el indicador sea verdadero. El indicador es inicialmente falso.

Distinto en la versión 3.3: cambiado de función de fábrica a una clase.

is_set()

Retorna True exclusivamente si el indicador interno es verdadero.

set()

Establece el indicador interno a verdadero. Todos los hilos que estén esperando que se vuelva verdadero serán despertados. Los hilos que llaman a wait() una vez que el indicador marca verdadero no bloquearán.

clear()

Restablece el indicador a falso. Posteriormente, los hilos que llamen a wait() bloquearán hasta que se llame a set() para establecer el indicador interno a verdadero nuevamente.

wait(timeout=None)

Bloquea hasta que el indicador interno sea verdadero. Si el indicador interno es verdadero de entrada, retorna inmediatamente. De otro modo, bloquea hasta que otro hilo llame a set() para establecer el indicador a verdadero, o hasta que el tiempo de espera opcional caduque.

Cuando se presenta un argumento para el tiempo de espera timeout distinto de None, debe ser un número de punto flotante que especifique un tiempo de espera para la operación en segundos (o fracciones en su defecto).

Este método retorna True exclusivamente si el indicador interno ha sido establecido a verdadero, ya sea antes de la llamada a la espera o después de que la espera inicie, por lo que siempre retorna True excepto si se provee un tiempo de espera máximo y la operación caduca.

Distinto en la versión 3.1: Previamente, el método siempre retornaba None.

Objetos temporizadores

Esta clase representa una acción que sólo debe ejecutarse luego de que una cierta cantidad de tiempo transcurra — un temporizador. Timer es una subclase de Thread y en tanto tal también funciona como un ejemplo de creación de hilos personalizados.

Los temporizadores son iniciados, tal como los hilos, al llamarse su método start(). El temporizador puede ser detenido (antes de que su acción haya comenzado) al llamar al método cancel(). El intervalo que el temporizador esperará antes de ejecutar su acción puede no ser exactamente el mismo que el intervalo especificado por el usuario.

Por ejemplo:

def hello():
    print("hello, world")

t = Timer(30.0, hello)
t.start()  # after 30 seconds, "hello, world" will be printed

class threading.Timer(interval, function, args=None, kwargs=None)

Crear un temporizador que ejecutará function con los argumentos args y los argumentos de palabra clave kwargs, luego de que una cantidad interval de segundos hayan transcurrido. Si args es None (por defecto) se utilizará una lista vacía. Si kwargs es None (por defecto) se utilizará un dict vacío.

Distinto en la versión 3.3: cambiado de función de fábrica a una clase.

cancel()

Detiene el temporizador, y cancela la ejecución de la acción del temporizador. Esto sólo funcionará si el temporizador está en etapa de espera.

Objetos de barrera

Nuevo en la versión 3.2.

Esta clase provee una primitiva de sincronización simple para ser usado por un número fijo de hilos que necesitan esperarse entre ellos. Cada uno de los hilos intenta pasar la barrera llamando al método wait() y bloqueará hasta que todos los hilos hayan hecho sus respectivas llamadas a wait(). En este punto, los hilos son liberados simultáneamente.

La barrera puede ser reutilizada cualquier número de veces para el mismo número de hilos.

Como ejemplo, aquí hay una manera simple de sincronizar un hilo cliente con uno servidor:

b = Barrier(2, timeout=5)

def server():
    start_server()
    b.wait()
    while True:
        connection = accept_connection()
        process_server_connection(connection)

def client():
    b.wait()
    while True:
        connection = make_connection()
        process_client_connection(connection)

class threading.Barrier(parties, action=None, timeout=None)

Crear un objeto de barrera para un número parties de hilos. Una action, si es provista, es un invocable a ser llamado por uno de los hilos cuando sean liberados. timeout es el valor de tiempo de espera máximo por defecto si no se especifica uno en el método wait().

wait(timeout=None)

Pasa la barrera. Cuando todos los hilos involucrados en el objeto barrera han llamado esta función, se liberan todos simultáneamente. Si se provee un valor timeout, se utilizará con preferencia sobre cualquiera que haya sido suministrado al constructor de la clase.

El valor de retorno es un entero en el rango desde 0 hasta parties – 1, diferente para cada hilo. Puede ser utilizado para seleccionar a un hilo para que haga alguna limpieza especial, por ejemplo:

i = barrier.wait()
if i == 0:
    # Only one thread needs to print this
    print("passed the barrier")

Se se provee una action al constructor, uno de los hilos la habrá llamado antes de ser liberado. Si acaso esta llamada lanzara un error, la barrera entra en estado broken (roto).

Si la llamada caduca, la barrera entra en estado broken.

Este método podría lanzar una excepción BrokenBarrierError si la barrera está rota o si se reinicia mientras el hilo está esperando.

reset()

Retorna la barrera al estado por defecto, vacío. Cualquier hilo que esté a su espera recibirá la excepción BrokenBarrierError.

Nótese que utilizar esta función podría requerir alguna sincronización externa si existen otros hilos cuyos estados sean desconocidos. Si una barrera se rompe puede ser mejor abandonarla y crear una nueva.

abort()

Coloca la barrera en estado roto. Esto causa que cualquier llamada activa o futura a wait() falle con el error BrokenBarrierError. Úsese por ejemplo si uno de los hilos necesita abortar, para evitar que la aplicación quede en punto muerto.

Puede ser preferible simplemente crear la barrera con un valor timeout sensato para cuidarse automáticamente de que uno de los hilos falle.

parties

El número de hilos requeridos para pasar la barrera.

n_waiting

El número de hilos actualmente esperando en la barrera.

broken

Un valor booleano que será True si la barrera está en el estado roto.

exception threading.BrokenBarrierError

Esta excepción, una subclase de RuntimeError, se lanza cuando el objeto Barrier se restablece o se rompe.

Uso de locks, condiciones y semáforos en la declaración with

Todos los objetos provistos por este módulo que tienen métodos acquire() y release() pueden ser utilizados como administradores de contexto para una declaración with. El método acquire() será llamado cuando se ingresa al bloque y el método release() será llamado cuando se abandona el bloque. De ahí que, el siguiente fragmento:

with some_lock:
    # do something...

sea equivalente a:

some_lock.acquire()
try:
    # do something...
finally:
    some_lock.release()

Actualmente, los objetos Lock, RLock, Condition, Semaphore, y BoundedSemaphore pueden ser utilizados como gestores de contexto con declaraciones with.

multiprocessing — Paralelismo basado en procesos

Código fuente: Lib/multiprocessing/ [https://github.com/python/cpython/tree/3.9/Lib/multiprocessing/]

Introducción

multiprocessing es un paquete que permite crear procesos (spawning) utilizando una API similar al módulo threading. El paquete multiprocessing ofrece concurrencia tanto local como remota, esquivando el Global Interpreter Lock mediante el uso de subprocesos en lugar de hilos (threads). Debido a esto, el módulo multiprocessing le permite al programador aprovechar al máximo múltiples procesadores en una máquina determinada. Se ejecuta tanto en Unix como en Windows.

El módulo multiprocessing también introduce API que no tienen análogos en el módulo threading. Un buen ejemplo de esto es el objeto Pool que ofrece un medio conveniente de paralelizar la ejecución de una función a través de múltiples valores de entrada, distribuyendo los datos de entrada a través de procesos (paralelismo de datos). El siguiente ejemplo demuestra la práctica común de definir tales funciones en un módulo para que los procesos secundarios puedan importar con éxito ese módulo. Este ejemplo básico de paralelismo de datos usando Pool,

from multiprocessing import Pool

def f(x):
    return x*x

if __name__ == '__main__':
    with Pool(5) as p:
        print(p.map(f, [1, 2, 3]))

imprimirá la salida estándar

[1, 4, 9]

La clase Process

En multiprocessing, los procesos se generan creando un objeto Process y luego llamando a su método start() . Process sigue la API de threading.Thread. Un ejemplo trivial de un programa multiproceso es

from multiprocessing import Process

def f(name):
    print('hello', name)

if __name__ == '__main__':
    p = Process(target=f, args=('bob',))
    p.start()
    p.join()

Para mostrar las IDs individuales involucradas en el proceso, aquí hay un ejemplo ampliado:

from multiprocessing import Process
import os

def info(title):
    print(title)
    print('module name:', __name__)
    print('parent process:', os.getppid())
    print('process id:', os.getpid())

def f(name):
    info('function f')
    print('hello', name)

if __name__ == '__main__':
    info('main line')
    p = Process(target=f, args=('bob',))
    p.start()
    p.join()

Para obtener una explicación de por qué es necesaria la parte if __name__ == '__main__' , consulte Pautas de programación.

Contextos y métodos de inicio

Dependiendo de la plataforma, multiprocessing admite tres formas de iniciar un proceso. Estos métodos de inicio start methods son

Generación (spawn)

El proceso parental inicia un nuevo proceso de intérprete de Python. El proceso hijo solo heredará los recursos necesarios para ejecutar los objetos del método run(). En particular, no se heredarán los descriptores de archivo innecesarios ni identificadores del proceso principal. Iniciar un proceso usando este método es bastante lento en comparación con el uso de fork o forkserver.

Disponible en Unix y Windows. Por defecto en Windows y macOS.

fork

El proceso parental usa os.fork() para bifurcar el intérprete de Python. El proceso hijo, cuando comienza, es efectivamente idéntico al proceso parental. Todos los recursos del proceso parental son heredados por el proceso hijo. Tenga en cuenta que bifurcar (forking) de forma segura un proceso multihilo es problemático.

Disponible solo en Unix. Por defecto en Unix.

forkserver

Cuando el programa se inicia y selecciona el método de inicio forkserver, se inicia un proceso de servidor. A partir de ese momento, cada vez que se necesite un nuevo proceso, el proceso parental se conecta al servidor y solicita que bifurque un nuevo proceso. El proceso del servidor fork es de un solo hilo, por lo que es seguro usarlo os.fork(). No se heredan recursos innecesarios.

Disponible en plataformas Unix que admiten pasar descriptores de archivo a través de tuberías (pipes) Unix.

Distinto en la versión 3.8: En macOS, el método de inicio spawn ahora es el predeterminado. El método de inicio fork debe considerarse inseguro ya que puede provocar bloqueos del subproceso. Consulte bpo-33725 [https://bugs.python.org/issue?@action=redirect&bpo=33725].

Distinto en la versión 3.4: spawn fue añadido en todas las plataformas Unix, y forkserver fue agregado para algunas plataformas Unix. Los procesos hijos (child processes) ya no heredan todos los identificadores heredables de los procesos parentales en Windows.

En Unix, los métodos de inicio spawn o forkserver también iniciarán un proceso resource tracker que rastrea los recursos del sistema con nombre no vinculados (como los nombrados semáforos o objetos SharedMemory) creado por procesos del programa. Cuando todos los procesos han salido, el rastreador de recursos desvincula cualquier objeto rastreado restante. Por lo general, no debería haber ninguno, pero si un proceso fue eliminado por una señal, puede haber algunos recursos «filtrados». (Ni los semáforos filtrados ni los segmentos de memoria compartida se desvincularán automáticamente hasta el próximo reinicio. Esto es problemático para ambos objetos porque el sistema solo permite un número limitado de semáforos con nombre, y los segmentos de memoria compartida ocupan algo de espacio en la memoria principal).

Para seleccionar un método de inicio, utilice la función set_start_method() en la cláusula if __name__ == '__main__' del módulo principal. Por ejemplo:

import multiprocessing as mp

def foo(q):
    q.put('hello')

if __name__ == '__main__':
    mp.set_start_method('spawn')
    q = mp.Queue()
    p = mp.Process(target=foo, args=(q,))
    p.start()
    print(q.get())
    p.join()

set_start_method() no debería ser usada más de una vez en el programa.

Alternativamente, se puede usar get_context() para obtener un objeto de contexto. Los objetos de contexto tienen la misma API que el módulo de multiprocesamiento, y permiten utilizar múltiples métodos de inicio en el mismo programa.

import multiprocessing as mp

def foo(q):
    q.put('hello')

if __name__ == '__main__':
    ctx = mp.get_context('spawn')
    q = ctx.Queue()
    p = ctx.Process(target=foo, args=(q,))
    p.start()
    print(q.get())
    p.join()

Tenga en cuenta que los objetos relacionados con un contexto pueden no ser compatibles con procesos para un contexto diferente. En particular, los locks creados con el contexto fork no se pueden pasar a los procesos iniciados con los métodos de inicio spawn o forkserver .

Una biblioteca que quiera usar un método de inicio particular probablemente debería usar get_context() para evitar interferir con la elección del usuario de la biblioteca.

Advertencia

Los métodos de inicio 'spawn' y 'forkserver' actualmente no pueden ser usados con ejecutables «congelados» (frozen)(es decir, binarios producidos por paquetes como PyInstaller y cx_Freeze) en Unix. El método de inicio 'fork' funciona.

Intercambiando objetos entre procesos

multiprocessing admite dos tipos de canales de comunicación entre procesos:

Colas (*queues*)

La clase Queue es prácticamente un clon de queue.Queue. Por ejemplo:

from multiprocessing import Process, Queue

def f(q):
    q.put([42, None, 'hello'])

if __name__ == '__main__':
    q = Queue()
    p = Process(target=f, args=(q,))
    p.start()
    print(q.get())    # prints "[42, None, 'hello']"
    p.join()

Las colas (queues) son hilos y procesos seguro.

Tuberías (*Pipes*)

La función Pipe() retorna un par de objetos de conexión conectados por una tubería (pipe) que, por defecto, es un dúplex (bidireccional). Por ejemplo:

from multiprocessing import Process, Pipe

def f(conn):
    conn.send([42, None, 'hello'])
    conn.close()

if __name__ == '__main__':
    parent_conn, child_conn = Pipe()
    p = Process(target=f, args=(child_conn,))
    p.start()
    print(parent_conn.recv())   # prints "[42, None, 'hello']"
    p.join()

Los dos objetos de conexión retornados por Pipe() representan los dos extremos de la tubería (pipe). Cada objeto de conexión tiene los métodos send() y recv() (entre otros). Tenga en cuenta que los datos en una tubería pueden corromperse si dos procesos (o hilos) intentan leer o escribir en el mismo (same) extremo de la tubería al mismo tiempo. Por supuesto, no hay riesgo de corrupción por procesos que utilizan diferentes extremos de la tubería (pipe) al mismo tiempo.

Sincronización entre procesos

multiprocessing contiene equivalentes de todas las sincronizaciones primitivas de threading. Por ejemplo, se puede usar un candado (lock) para garantizar que solo un proceso se imprima a la salida estándar a la vez:

from multiprocessing import Process, Lock

def f(l, i):
    l.acquire()
    try:
        print('hello world', i)
    finally:
        l.release()

if __name__ == '__main__':
    lock = Lock()

    for num in range(10):
        Process(target=f, args=(lock, num)).start()

Sin usar el candado (lock) de salida de los diferentes procesos, es probable que todo se mezcle.

Compartiendo estado entre procesos

Como se mencionó anteriormente, cuando se realiza una programación concurrente, generalmente es mejor evitar el uso del estado compartido en la medida de lo posible. Esto es particularmente cierto cuando se utilizan múltiples procesos.

Sin embargo, si usted realmente necesita usar algunos datos compartidos el multiprocessing proporciona un par de maneras de hacerlo.

Memoria compartida

Los datos se pueden almacenar en un mapa de memoria compartida usando Value o Array. Por ejemplo, el siguiente código

from multiprocessing import Process, Value, Array

def f(n, a):
    n.value = 3.1415927
    for i in range(len(a)):
        a[i] = -a[i]

if __name__ == '__main__':
    num = Value('d', 0.0)
    arr = Array('i', range(10))

    p = Process(target=f, args=(num, arr))
    p.start()
    p.join()

    print(num.value)
    print(arr[:])

imprimirá

3.1415927
[0, -1, -2, -3, -4, -5, -6, -7, -8, -9]

Los argumentos 'd' y 'i'``utilizados al crear ``num y arr son códigos de tipo del tipo utilizado por array module: 'd' indica un flotador de doble precisión y 'i' indica un entero con signo. Estos objetos compartidos serán seguros para procesos y subprocesos.

Para una mayor flexibilidad en el uso de la memoria compartida, se puede usar el módulo multiprocessing.sharedctypes que admite la creación arbitraria de objetos ctypes asignados desde la memoria compartida.

Proceso servidor (*Server process*)

Un objeto de administrador retornado por Manager() controla un proceso de servidor que contiene objetos de Python y permite que otros procesos los manipulen usando proxies.

Un administrador retornado por Manager() soportará tipos de clases como list, dict, Namespace, Lock, RLock, Semaphore, BoundedSemaphore, Condition, Event, Barrier, Queue, Value y Array. Por ejemplo,

from multiprocessing import Process, Manager

def f(d, l):
    d[1] = '1'
    d['2'] = 2
    d[0.25] = None
    l.reverse()

if __name__ == '__main__':
    with Manager() as manager:
        d = manager.dict()
        l = manager.list(range(10))

        p = Process(target=f, args=(d, l))
        p.start()
        p.join()

        print(d)
        print(l)

imprimirá

{0.25: None, 1: '1', '2': 2}
[9, 8, 7, 6, 5, 4, 3, 2, 1, 0]

Los administradores de procesos del servidor son más flexibles que el uso de objetos de memoria compartida porque pueden hacerse para admitir tipos de objetos arbitrarios. Por lo tanto, un solo administrador puede ser compartido por procesos en diferentes ordenadores a través de una red. Sin embargo, son más lentos que usar memoria compartida.

Usando una piscina de trabajadores (pool of workers)

La clase Pool representa procesos de piscina de trabajadores (pool of workers). Tiene métodos que permiten que las tareas se descarguen a los procesos de trabajo de diferentes maneras.

Por ejemplo:

from multiprocessing import Pool, TimeoutError
import time
import os

def f(x):
    return x*x

if __name__ == '__main__':
    # start 4 worker processes
    with Pool(processes=4) as pool:

        # print "[0, 1, 4,..., 81]"
        print(pool.map(f, range(10)))

        # print same numbers in arbitrary order
        for i in pool.imap_unordered(f, range(10)):
            print(i)

        # evaluate "f(20)" asynchronously
        res = pool.apply_async(f, (20,))      # runs in *only* one process
        print(res.get(timeout=1))             # prints "400"

        # evaluate "os.getpid()" asynchronously
        res = pool.apply_async(os.getpid, ()) # runs in *only* one process
        print(res.get(timeout=1))             # prints the PID of that process

        # launching multiple evaluations asynchronously *may* use more processes
        multiple_results = [pool.apply_async(os.getpid, ()) for i in range(4)]
        print([res.get(timeout=1) for res in multiple_results])

        # make a single worker sleep for 10 secs
        res = pool.apply_async(time.sleep, (10,))
        try:
            print(res.get(timeout=1))
        except TimeoutError:
            print("We lacked patience and got a multiprocessing.TimeoutError")

        print("For the moment, the pool remains available for more work")

    # exiting the 'with'-block has stopped the pool
    print("Now the pool is closed and no longer available")

Tenga en cuenta que los métodos de una piscina (pool) solo deben ser utilizados por el proceso que lo creó.

Nota

La funcionalidad en este paquete requiere que los procesos hijos (children) puedan importar el módulo __main__. Esto está cubierto en Pautas de programación sin embargo, vale la pena señalarlo aquí. Esto significa que algunos ejemplos, como multiprocessing.pool.Pool no funcionarán en el intérprete interactivo. Por ejemplo:

>>> from multiprocessing import Pool
>>> p = Pool(5)
>>> def f(x):
...     return x*x
...
>>> with p:
...   p.map(f, [1,2,3])
Process PoolWorker-1:
Process PoolWorker-2:
Process PoolWorker-3:
Traceback (most recent call last):
Traceback (most recent call last):
Traceback (most recent call last):
AttributeError: 'module' object has no attribute 'f'
AttributeError: 'module' object has no attribute 'f'
AttributeError: 'module' object has no attribute 'f'

(Si intenta esto, en realidad generará tres trazas completas intercaladas de forma semialeatoria, y luego tendrá que detener el proceso principal de alguna manera)

Referencia

El paquete multiprocessing mayoritariamente replica la API del módulo threading.

Process y excepciones

class multiprocessing.Process(group=None, target=None, name=None, args=(), kwargs={}, *, daemon=None)

Los objetos de proceso representan la actividad que se ejecuta en un proceso separado. La clase Process tiene equivalentes para todos los métodos threading.Thread.

El constructor siempre debe llamarse con argumentos de palabras clave. group siempre debe ser None; existe únicamente por compatibilidad con threading.Thread. target es el objeto invocable a ser llamado por el método run() . El valor predeterminado es None, lo que significa que nada es llamado. name es el nombre del proceso (consulte name para más detalles). args es la tupla de argumento para la invocación de destino. kwargs es un diccionario de argumentos de palabras clave para la invocación de destino. Si se proporciona, el argumento daemon solo de palabra clave establece el proceso daemon en True o False. Si None (el valor predeterminado), este indicador se heredará del proceso de creación.

Por defecto, ningún argumento es pasado a target.

Si una subclase anula al constructor, debe asegurarse de que invoca al constructor de la clase base (Process.__init__()) antes de hacer cualquier otra cosa al proceso.

Distinto en la versión 3.3: Añadido el argumento daemon.

run()

Método que representa la actividad del proceso.

Puede anular este método en una subclase. El método estándar run() invoca el objeto invocable pasado al constructor del objeto como argumento objetivo, si lo hay, con argumentos posicionares y de palabras clave tomados de los argumentos args y kwargs, respectivamente.

start()

Comienza la actividad del proceso.

Esto debe llamarse como máximo una vez por objeto de proceso. Organiza la invocación del método run() del objeto en un proceso separado.

join([timeout])

Si el argumento opcional timeout es None (el valor predeterminado), el método se bloquea hasta que el proceso cuyo método join() se llama termina. Si timeout es un número positivo, bloquea como máximo timeout segundos. Tenga en cuenta que el método retorna None si su proceso finaliza o si el método agota el tiempo de espera. Verifique el proceso exitcode para determinar si terminó.

Un proceso puede unirse muchas veces.

Un proceso no puede unirse a sí mismo porque esto provocaría un punto muerto. Es un error intentar unirse a un proceso antes de que se haya iniciado.

name

El nombre del proceso. El nombre es una cadena utilizada solo con fines de identificación. No tiene semántica. Múltiples procesos pueden tener el mismo nombre.

El nombre inicial es establecido por el constructor. Si no se proporciona un nombre explícito al constructor, se forma un nombre usando “Process-N:sub:`1`:N:sub:`2`:…:N:sub:`k`” se construye, donde cada N:sub:`k` es el N-enésimo hijo del parental.

is_alive()

Retorna si el proceso está vivo.

Aproximadamente, un objeto de proceso está vivo desde el momento en que el método start() retorna hasta que finaliza el proceso hijo.

daemon

La bandera del proceso daemon , es un valor booleano. Esto debe establecerse antes de que start() sea llamado.

El valor inicial se hereda del proceso de creación.

Cuando un proceso sale, intenta terminar todos sus procesos demoníacos (daemonic) hijos.

Tenga en cuenta que un proceso demoníaco (daemonic) no puede crear procesos hijos. De lo contrario, un proceso demoníaco (daemonic) dejaría a sus hijos huérfanos si se termina cuando finaliza su proceso parental. Además, estos no son daemons o servicios de Unix, son procesos normales qué finalizarán (y no se unirán) si los procesos no demoníacos han salido.

Además de API threading.Thread, los objetos Process también admiten los siguientes atributos y métodos:

pid

Retorna el ID del proceso. Antes de que se genere el proceso, esto será None.

exitcode

The child’s exit code. This will be None if the process has not yet terminated.

If the child’s run() method returned normally, the exit code will be 0. If it terminated via sys.exit() with an integer argument N, the exit code will be N.

If the child terminated due to an exception not caught within run(), the exit code will be 1. If it was terminated by signal N, the exit code will be the negative value -N.

authkey

La clave de autenticación del proceso (una cadena de bytes).

Cuando el multiprocessing se inicializa el proceso principal se le asigna una cadena aleatoria usando os.urandom().

Cuando se crea un objeto Process, este heredará la clave de autenticación de su proceso parental, aunque esto puede cambiarse configurando authkey a otra cadena de bytes.

Consulte Llaves de autentificación.

sentinel

Un identificador numérico de un objeto del sistema que estará «listo» cuando finalice el proceso.

Se puede usar este valor si desea esperar varios eventos a la vez usando multiprocessing.connection.wait(). De lo contrario, llamar a join() es más simple.

En Windows, este es un sistema operativo manejable con la familia de llamadas API WaitForSingleObject y WaitForMultipleObjects. En Unix, este es un descriptor de archivo utilizable con primitivas del módulo select.

Nuevo en la versión 3.3.

terminate()

Terminar el proceso. En Unix, esto se hace usando la señal SIGTERM; en Windows se utiliza TerminateProcess() . Tenga en cuenta que los manejadores de salida y finalmente las cláusulas, etc., no se ejecutarán.

Tenga en cuenta que los procesos descendientes del proceso no finalizarán – simplemente quedarán huérfanos.

Advertencia

Si este método se usa cuando el proceso asociado está usando una tubería (pipe) o una cola(queue), entonces la tubería o la cola pueden corromperse y pueden quedar inutilizables por otro proceso. Del mismo modo, si el proceso ha adquirido un lock o un semáforo, etc., su finalización puede provocar el bloqueo de otros procesos.

kill()

Siempre como terminate() pero utilizando la señal SIGKILL en Unix.

Nuevo en la versión 3.7.

close()

El cierre del objeto Process, libera todos los recursos asociados a él. ValueError se lanza si el proceso subyacente aún se está ejecutando. Una vez close() se retorna con éxito, la mayoría de los otros métodos y atributos del objeto Process lanzará ValueError.

Nuevo en la versión 3.7.

Tenga en cuenta que los métodos start(), join(), is_alive(), terminate() y exitcode deberían solo ser llamados por el proceso que creó el objeto del proceso.

Ejemplo de uso de algunos métodos de la Process:

 >>> import multiprocessing, time, signal
 >>> p = multiprocessing.Process(target=time.sleep, args=(1000,))
 >>> print(p, p.is_alive())
 <Process ... initial> False
 >>> p.start()
 >>> print(p, p.is_alive())
 <Process ... started> True
 >>> p.terminate()
 >>> time.sleep(0.1)
 >>> print(p, p.is_alive())
 <Process ... stopped exitcode=-SIGTERM> False
 >>> p.exitcode == -signal.SIGTERM
 True

exception multiprocessing.ProcessError

La clase base de todas las excepciones multiprocessing.

exception multiprocessing.BufferTooShort

La excepción Connection.recv_bytes_into() es lanzada cuando el objeto de búfer suministrado es demasiado pequeño para el mensaje leído.

Si e es una instancia de BufferTooShort entonces e.args[0] dará el mensaje como una cadena de bytes.

exception multiprocessing.AuthenticationError

Lanzada cuando hay un error de autenticación.

exception multiprocessing.TimeoutError

Lanzada por métodos con un tiempo de espera (timeout) cuando este expira.

Tuberías (Pipes) y Colas (Queues)

Cuando se usan múltiples procesos, uno generalmente usa el paso de mensajes para la comunicación entre procesos y evita tener que usar primitivas de sincronización como locks.

Para pasar mensajes se puede usar Pipe() (para una conexión entre dos procesos) o una cola (queue)(que permite múltiples productores y consumidores).

Los tipos Queue, SimpleQueue y JoinableQueue son colas multi-productor, multi-consumidor FIFO (primero en entrar, primero en salir) modeladas en queue.Queue en la biblioteca estándar. Se diferencian en que Queue carece de task_done() y join() métodos introducidos en Python 2.5 queue.Queue class.

Si usa JoinableQueue, entonces debe llamar a JoinableQueue.task_done() para cada tarea eliminada de la cola (queue) o de lo contrario el semáforo utilizado para contar el número de tareas sin terminar puede eventualmente desbordarse, lanzando un excepción.

Tenga en cuenta que también se puede crear una cola compartida mediante el uso de un objeto de administrador – consulte Administradores (Managers).

Nota

multiprocessing utiliza las excepciones habituales queue.Empty y queue.Full para indicar un tiempo de espera. No están disponibles en el espacio de nombres multiprocessing, por lo que debe importarlos desde queue.

Nota

Cuando un objeto se coloca en una cola (queue), el objeto se serializa (pickled) y luego un subproceso de fondo vacía los datos serializados a una tubería (pipe) subyacente. Esto tiene algunas consecuencias que son un poco sorprendentes, pero no deberían causar dificultades prácticas: si realmente causan molestias, se puede usar una cola creada con un manager.

Después de poner un objeto en una cola vacía, puede haber un retraso infinitesimal antes de que el método de la cola empty() retorne False y get_nowait() puede retornar sin lanzar queue.Empty.

Si varios procesos están poniendo en cola objetos, es posible que los objetos se reciban en el otro extremo fuera de orden. Sin embargo, los objetos en cola por el mismo proceso siempre estarán en el orden esperado entre sí.

Advertencia

Si se termina un proceso usando Process.terminate() o os.kill() mientras intenta usar una clase Queue, es probable que los datos de la cola(queue) se corrompan. Esto puede hacer que cualquier otro proceso obtenga una excepción cuando intente usar la cola más adelante.

Advertencia

Como se mencionó anteriormente, si un proceso hijo ha puesto elementos en una cola (queue) (y no ha utilizado JoinableQueue.cancel_join_thread), entonces ese proceso no terminará hasta que todos los elementos almacenados en búfer hayan sido vaciados a la tubería (pipe).

Esto significa que si intenta unirse a ese proceso, puede obtener un punto muerto a menos que esté seguro de que todos los elementos que se han puesto en la cola (queue) se han consumido. Del mismo modo, si el proceso hijo no es daemonic, el proceso parental puede bloquearse en la salida cuando intenta unir todos sus elementos hijos no daemonic.

Tenga en cuenta que una cola (queue) creada con un administrador no tiene este problema. Consulte Pautas de programación.

Para ver un ejemplo del uso de colas para la comunicación entre procesos, consulte Ejemplos.

multiprocessing.Pipe([duplex])

Retorna un par de objetos ``(conn1, conn2)`` de la Connection que representan los extremos de una tubería (pipe).

Si duplex es True (el valor predeterminado), entonces la tubería (pipe) es bidireccional. Si duplex es False, entonces la tubería es unidireccional: conn1 solo se puede usar para recibir mensajes y conn2 solo se puede usar para enviar mensajes.

class multiprocessing.Queue([maxsize])

Retorna un proceso de cola (queue) compartida implementado utilizando una tubería (pipe) y algunos candados/semáforos (locks/semaphores). Cuando un proceso pone por primera vez un elemento en la cola, se inicia un hilo alimentador que transfiere objetos desde un búfer a la tubería.

Las excepciones habituales queue.Empty y queue.Full del módulo de la biblioteca estándar queue se generan para indicar tiempos de espera.

La Queue implementa todos los métodos de la queue.Queue excepto por task_done() y join().

qsize()

Retorna el tamaño aproximado de la cola (queue). Debido a la semántica multiproceso/multiprocesamiento, este número no es confiable.

Note that this may raise NotImplementedError on Unix platforms like macOS where sem_getvalue() is not implemented.

empty()

Retorna True si la cola (queue) está vacía, de lo contrario retorna False . Debido a la semántica multiproceso/multiprocesamiento, esto no es confiable.

full()

Retorna True si la cola (queue) está llena, de lo contrario retorna False . Debido a la semántica multiproceso/multiprocesamiento, esto no es confiable.

put(obj[, block[, timeout]])

Pone obj en la cola. Si el argumento opcional block es True (el valor predeterminado) y timeout es None (el valor predeterminado), se bloquea si es necesario hasta que haya un espacio disponible. Si timeout es un número positivo, bloquea a lo sumo timeout segundos y genera la excepción queue.Full si no hay espacio libre disponible en ese tiempo. De lo contrario (block es False), y coloca un elemento en la cola si hay un espacio libre disponible de inmediato, de lo contrario, genera la excepción queue.Full (timeout se ignora en ese caso).

Distinto en la versión 3.8: Si la cola (queue) está cerrada, ValueError se lanza en lugar de AssertionError.

put_nowait(obj)

Equivalente a put(obj, False).

get([block[, timeout]])

Elimina y retorna un artículo de la cola (queue). Si un argumento opcional block es True (el valor predeterminado) y el timeout es None (el valor predeterminado), es bloqueado si es necesario hasta que un elemento esté disponible. Si el timeout es un número positivo, bloquea a lo sumo segundos y genera la excepción queue.Empty si no había ningún elemento disponible dentro de ese tiempo. De lo contrario (el bloque es False), retorna un elemento si hay uno disponible de inmediato, de lo contrario, levante la excepción queue.Empty (timeout se ignora en ese caso).

Distinto en la versión 3.8: Si la cola está cerrada, se lanza ValueError en lugar de OSError.

get_nowait()

Equivalente a get(False).

La multiprocessing.Queue tiene algunos métodos adicionales que no se encuentran en queue.Queue. Estos métodos suelen ser innecesarios para la mayoría de los códigos:

close()

Indica que el proceso actual no colocará más datos en esta cola (queue). El subproceso en segundo plano se cerrará una vez que haya vaciado todos los datos almacenados en la tubería (pipe). Esto se llama automáticamente cuando la cola es recolectada por el recolector de basura.

join_thread()

Unifica al hilo de fondo. Esto solo se puede usar después de que se ha llamado a close(). Esto se bloquea hasta que salga el hilo de fondo, asegurando que todos los datos en el búfer se hayan vaciado a la tubería (pipe).

Por defecto, si un proceso no es el creador de la cola (queue), al salir intentará unirse al hilo de fondo de la cola. El proceso puede llamar a cancel_join_thread() para hacer que el join_thread() no haga nada.

cancel_join_thread()

Evita que join_thread() bloquee. En particular, esto evita que el subproceso en segundo plano se una automáticamente cuando finaliza el proceso; consulte join_thread().

Un mejor nombre para este método podría ser allow_exit_without_flush(). Es probable que provoque la pérdida de datos en cola (queue), y es casi seguro que no necesitará usarlos. Realmente solo está allí si necesita que el proceso actual salga inmediatamente sin esperar a vaciar los datos en cola en la tubería (pipe) subyacente, y no le importan los datos perdidos.

Nota

La funcionalidad de esta clase requiere una implementación de semáforo compartido en funcionamiento en el sistema operativo que es huésped (host). Sin uno, la funcionalidad en esta clase se deshabilitará, y los intentos de instanciar a Queue resultarán en ImportError. Consulte bpo-3770 [https://bugs.python.org/issue?@action=redirect&bpo=3770] para información adicional. Lo mismo es válido para cualquiera de los tipos de cola especializados que se enumeran a continuación.

class multiprocessing.SimpleQueue

Es un tipo simplificado Queue, muy similar a un lock de Pipe.

close()

Cierra la cola: libera recursos internos.

Una cola no se debe usar más después de ser cerrada. Por ejemplo los métodos get(), put() y empty() no deben ser llamados.

Nuevo en la versión 3.9.

empty()

Retorna True si la cola (queue) está vacía, de otra manera retorna False.

get()

Eliminar y retornar un artículo de la cola (queue).

put(item)

Pone item en la cola.

class multiprocessing.JoinableQueue([maxsize])

JoinableQueue, una subclase Queue , es una cola (queue) que además tiene los métodos task_done() y join().

task_done()

Indica que una tarea anteriormente en cola (queue) está completa. Usado por los consumidores de la cola. Por cada get() utilizado para recuperar una tarea, una llamada posterior a task_done() le dice a la cola que el procesamiento de la tarea se ha completado.

Si un join() se está bloqueando actualmente, se reanudará cuando se hayan procesado todos los elementos (lo que significa que task_done() es llamado para cada elemento que había sido puesto en cola (queue) por put()).

Lanza un ValueError si es llamado más veces que elementos hay en una cola.

join()

Se bloquea hasta que todos los elementos en una cola han sido recibidos y procesados.

El recuento de tareas no finalizadas aumenta cada vez que se agrega un elemento a la cola. El recuento disminuye cada vez que un consumidor llama a task_done() para indicar que el artículo se recuperó y todo el trabajo en él está completo. Cuando el recuento de tareas inacabadas cae a cero, join() se desbloquea.

Miscelánea

multiprocessing.active_children()

Retorna una lista con todos los hijos del proceso actual.

Llamar a esto tiene el efecto secundario de «unir» (joining) cualquier proceso que ya haya finalizado.

multiprocessing.cpu_count()

Retorna el número de CPU en el sistema.

Este número no es equivalente al número de CPU que puede utilizar el proceso actual. El número de CPU utilizables se puede obtener con len(os.sched_getaffinity(0))

When the number of CPUs cannot be determined a NotImplementedError is raised.

Ver también

os.cpu_count()

multiprocessing.current_process()

Retorna el objeto de la Process correspondiente al proceso actual.

Un análogo de la threading.current_thread().

multiprocessing.parent_process()

Retorna el objeto de la Process correspondiente al proceso parental de current_process(). Para el proceso principal, parent_process` será ``None.

Nuevo en la versión 3.8.

multiprocessing.freeze_support()

Agrega soporte para cuando un programa que utiliza multiprocessing se haya congelado para producir un ejecutable de Windows. (Ha sido probado con py2exe, PyInstaller y cx_Freeze.)

Es necesario llamar a esta función inmediatamente después de la línea principal del módulo if __name__ == “__main__”` . Por ejemplo:

from multiprocessing import Process, freeze_support

def f():
    print('hello world!')

if __name__ == '__main__':
    freeze_support()
    Process(target=f).start()

Si se omite la línea freeze_support() entonces se intenta comenzar el ejecutable congelado que lanzará RuntimeError.

La llamada de freeze_support() no tiene efecto cuando es invocada por cualquier sistema operativo que no sea Windows. Además, si el módulo ha sido ejecutado en un intérprete de Python en Windows (y el programa no se ha congelado) entonces freeze_support() no tiene efecto.

multiprocessing.get_all_start_methods()

Retorna una lista de los métodos de inicio admitidos, el primero de los cuales es el predeterminado. Los posibles métodos de inicio son 'fork', 'spawn' y 'forkserver'. En Windows solo está disponible 'spawn'. En Unix, 'fork' y 'spawn' siempre son compatibles, siendo 'fork' el valor predeterminado.

Nuevo en la versión 3.4.

multiprocessing.get_context(method=None)

Retorna un objeto de contexto que tiene los mismos atributos que el módulo multiprocessing.

Si el método method es None entonces el contexto predeterminado es retornado. Por lo contrario, method debería ser 'fork', 'spawn', 'forkserver'. Se lanza ValueError if el método de inicio no esta disponible.

Nuevo en la versión 3.4.

multiprocessing.get_start_method(allow_none=False)

Retorna el nombre del método de inicio que es utilizado para iniciar procesos.

Si el método de inicio no se ha solucionado y allow_none es falso, entonces el método de inicio se fija al predeterminado y se retorna el nombre. Si el método de inicio no se ha solucionado y allow_none es verdadero, se retorna None.

The return value can be 'fork', 'spawn', 'forkserver' or None. 'fork' is the default on Unix, while 'spawn' is the default on Windows and macOS.

Distinto en la versión 3.8: En macOS, el método de inicio spawn ahora es el predeterminado. El método de inicio fork debe considerarse inseguro ya que puede provocar bloqueos del subproceso. Consulte bpo-33725 [https://bugs.python.org/issue?@action=redirect&bpo=33725].

Nuevo en la versión 3.4.

multiprocessing.set_executable(executable)

Set the path of the Python interpreter to use when starting a child process. (By default sys.executable is used). Embedders will probably need to do some thing like

set_executable(os.path.join(sys.exec_prefix, 'pythonw.exe'))

antes ellos pueden crear procesos hijos.

Distinto en la versión 3.4: Ahora es compatible con Unix cuando se usa el método de inicio 'spawn'.

multiprocessing.set_start_method(method)

Se establece el método que se debe usar para iniciar procesos secundarios. method puede ser 'fork', 'spawn' o 'forkserver'.

Tenga en cuenta que esto debería llamarse como máximo una vez, y debería protegerse dentro de la cláusula if __name__ == '__main__' del módulo principal.

Nuevo en la versión 3.4.

Nota

multiprocessing no contiene análogos de threading.active_count(), threading.enumerate(), threading.settrace(), threading.setprofile(), threading.Timer, o threading.local.

Objetos de conexión Connection Objects

Los objetos de conexión permiten el envío y la recepción de objetos serializables (pickable) o cadenas de caracteres seleccionables. Pueden considerarse como sockets conectados orientados a mensajes.

Los objetos de conexión usualmente son creados usando Pipe – ver también Oyentes y Clientes (Listeners and Clients).

class multiprocessing.connection.Connection

send(obj)

Envía un objeto al otro extremo de la conexión que debe leerse usando recv().

El objeto debe ser serializable (pickable). Los serializados (pickable) muy grandes (aproximadamente 32 MiB+ , aunque depende del sistema operativo) pueden generar una excepción ValueError.

recv()

Retorna un objeto enviado desde el otro extremo de la conexión usando send(). Se bloquea hasta que haya algo para recibir. Se lanza EOFError si no queda nada por recibir y el otro extremo está cerrado.

fileno()

Retorna el descriptor de archivo o identificador utilizado por la conexión.

close()

Cierra la conexión.

Esto se llama automáticamente cuando la conexión es basura recolectada.

poll([timeout])

Retorna si hay datos disponibles para leer.

Si no se especifica timeout, se retornará de inmediato. Si timeout es un número, esto especifica el tiempo máximo en segundos para bloquear. Si timeout es None, se usa un tiempo de espera infinito.

Tenga en cuenta que se pueden sondear varios objetos de conexión a la vez utilizando multiprocessing.connection.wait().

send_bytes(buffer[, offset[, size]])

Envía datos de bytes desde a bytes-like object como un mensaje completo.

Si se da offset, los datos se leen desde esa posición en buffer. Si se da size entonces se leerán muchos bytes del búfer. Los buffers muy grandes (aproximadamente 32 MiB+, aunque depende del sistema operativo) pueden generar una excepción ValueError

recv_bytes([maxlength])

Retorna un mensaje completo de datos de bytes enviados desde el otro extremo de la conexión como una cadena de caracteres. Se bloquea hasta que haya algo para recibir. Aumenta EOFError si no queda nada por recibir y el otro extremo se ha cerrado.

Si se especifica maxlength y el mensaje es más largo que maxlength, entonces se lanza un OSError y la conexión ya no será legible.

Distinto en la versión 3.3: Esta función solía lanzar un IOError, que ahora es un alias de OSError.

recv_bytes_into(buffer[, offset])

Lee en buffer un mensaje completo de datos de bytes enviados desde el otro extremo de la conexión y retorne el número de bytes en el mensaje. Se bloquea hasta que haya algo para recibir. Si no queda nada por recibir y el otro extremo está cerrándose se lanza EOFError.

buffer debe ser un escribible bytes-like object. Si se proporciona offset el mensaje se escribirá en el búfer desde esa posición. La compensación debe ser un número entero no negativo menor que la longitud de buffer (en bytes).

Si el búfer es demasiado corto, se genera una excepción BufferTooShort y el mensaje completo está disponible como e.args[0] donde e es la instancia de excepción.

Distinto en la versión 3.3: Los objetos de conexión ahora pueden transferirse entre procesos usando Connection.send() y Connection.recv().

Nuevo en la versión 3.3: Los objetos de conexión ahora admiten el protocolo de administración de contexto – consulte Tipos Gestores de Contexto. __enter__() retorna el objeto de conexión, y __exit__() llama a close().

Por ejemplo:

>>> from multiprocessing import Pipe
>>> a, b = Pipe()
>>> a.send([1, 'hello', None])
>>> b.recv()
[1, 'hello', None]
>>> b.send_bytes(b'thank you')
>>> a.recv_bytes()
b'thank you'
>>> import array
>>> arr1 = array.array('i', range(5))
>>> arr2 = array.array('i', [0] * 10)
>>> a.send_bytes(arr1)
>>> count = b.recv_bytes_into(arr2)
>>> assert count == len(arr1) * arr1.itemsize
>>> arr2
array('i', [0, 1, 2, 3, 4, 0, 0, 0, 0, 0])

Advertencia

El método Connection.recv() desempaqueta automáticamente los datos que recibe, lo que puede ser un riesgo de seguridad a menos que pueda confiar en el proceso que envió el mensaje.

Por lo tanto, a menos que el objeto de conexión se haya producido usando Pipe() solo debe usar los métodos recv() y send() después de realizar algún tipo de autenticación. Consulte Llaves de autentificación.

Advertencia

Si se mata un proceso mientras intenta leer o escribir en una tubería (pipe), entonces es probable que los datos en la tubería se corrompan, porque puede ser imposible estar seguro de dónde se encuentran los límites del mensaje.

Primitivas de sincronización (Synchronization primitives)

En general, las primitivas de sincronización no son tan necesarias en un programa multiproceso como en un programa multihilos (multithreaded). Consulte la documentación para threading .

Tenga en cuenta que también se pueden crear primitivas de sincronización utilizando un objeto administrador – consulte Administradores (Managers).

class multiprocessing.Barrier(parties[, action[, timeout]])

Un objeto de barrera: un clon de threading.Barrier.

Nuevo en la versión 3.3.

class multiprocessing.BoundedSemaphore([value])

Un objeto semáforo (semaphore object) acotado: un análogo cercano de la threading.BoundedSemaphore.

Existe una diferencia solitaria de su análogo cercano: el primer argumento de su método acquire es nombrado block, es consistente con Lock.acquire().

Nota

On macOS, this is indistinguishable from Semaphore because sem_getvalue() is not implemented on that platform.

class multiprocessing.Condition([lock])

Una variable de condición: un alias para la threading.Condition.

Si se especifica lock, entonces debería ser una Lock o RLock objeto de multiprocessing.

Distinto en la versión 3.3: El método wait_for() fue a añadido.

class multiprocessing.Event

Un clon de threading.Event.

class multiprocessing.Lock

Un objeto candado no recursivo: un análogo cercano de threading.Lock . Una vez que un proceso o subproceso ha adquirido un bloqueo, los intentos posteriores de adquirirlo de cualquier proceso o subproceso se bloquearán hasta que se libere; cualquier proceso o hilo puede liberarlo. Los conceptos y comportamientos de threading.Lock como se aplica a los subprocesos se replican aquí en multiprocessing.Lock como se aplica a los procesos o subprocesos, excepto como se indica.

Tenga en cuenta que Lock es en realidad una función de fábrica que retorna una instancia de multiprocessing.synchronize.Lock inicializada con un contexto predeterminado.

La Lock soporta el protocolo context manager y, por lo tanto, se puede usar en la declaración with.

acquire(block=True, timeout=None)

Adquiriendo un candado (lock), bloqueante o no bloqueante.

Con el argumento block establecido en True (el valor predeterminado), la llamada al método se bloqueará hasta que el bloqueo esté en un estado desbloqueado, luego configúrelo como bloqueado y retorne True. Tenga en cuenta que el nombre de este primer argumento difiere del que aparece en threading.Lock.acquire().

Con el argumento block establecido en False, la llamada al método no se bloquea. Si el bloqueo está actualmente en un estado bloqueado, retorna False; de lo contrario, configure el bloqueo en un estado bloqueado y retorne True.

Cuando se invoca con un valor positivo de punto flotante para timeout, bloquea como máximo el número de segundos especificado por timeout siempre que no se pueda obtener el bloqueo. Las invocaciones con un valor negativo para timeout de cero. Las invocaciones con un valor timeout de None (el valor predeterminado) establecen el período de tiempo de espera en infinito. Tenga en cuenta que el tratamiento de valores negativos o None para timeout difiere del comportamiento implementado en threading.Lock.acquire(). El argumento timeout no tiene implicaciones prácticas si el argumento block se establece en False y, por lo tanto, se ignora. Retorna True si se ha adquirido el candado o False si ha transcurrido el tiempo de espera.

release()

Suelta un candado. Esto se puede llamar desde cualquier proceso o subproceso, no solo desde el proceso o subproceso que originalmente adquirió el candado.

El comportamiento es el mismo que en threading.Lock.release() excepto que cuando se invoca en un bloqueo desbloqueado, se genera a ValueError.

class multiprocessing.RLock

Un objeto de candado recursivo: un análogo cercano a threading.RLock. El proceso o el hilo que lo adquirió debe liberar un candado recursivo. Una vez que un proceso o subproceso ha adquirido un candado recursivo, el mismo proceso o subproceso puede volver a adquirirlo sin bloquearlo; ese proceso o hilo debe liberarlo una vez por cada vez que se haya adquirido.

Tenga en cuenta que RLock es en realidad una función de fábrica que retorna una instancia de multiprocessing.synchronize.RLock inicializada con un contexto predeterminado.

La RLock admite el protocolo context manager y, por lo tanto, puede usarse en with.

acquire(block=True, timeout=None)

Adquiriendo un candado (lock), bloqueante o no bloqueante.

Cuando se invoca con el argumento block establecido en True , bloquea hasta que el candado esté en un estado desbloqueado (que no sea propiedad de ningún proceso o subproceso) a menos que el candado o el subproceso actual ya sea de su propiedad. El proceso o subproceso actual se apropia del candado (si aún no lo tiene) y el nivel de recursión dentro de este aumenta en uno, lo que da como resultado un valor de retorno de True. Tenga en cuenta que hay varias diferencias en el comportamiento de este primer argumento en comparación con la implementación de threading.RLock.acquire(), comenzando con el nombre del argumento en sí.

Cuando se invoca con el argumento block establecido en False, no bloquea. Si el candado ya ha sido adquirido (y por lo tanto es propiedad) de otro proceso o subproceso, el proceso o subproceso actual no se apropia y el nivel de recursión dentro del candado no cambia, lo que resulta en un valor de retorno de False. Si el candado está en un estado desbloqueado, el proceso o subproceso actual toma posesión y el nivel de recurrencia se incrementa, lo que resulta en un valor de retorno de True.

El uso y los comportamientos del argumento timeout son los mismos que en Lock.acquire(). Tenga en cuenta que algunos de estos comportamientos de timeout difieren de los comportamientos implementados en threading.RLock.acquire().

release()

Libera un candado, disminuyendo el nivel de recursión. Si después del decremento el nivel de recursión es cero, restablece el candado a desbloqueado (que no sea propiedad de ningún proceso o subproceso) y si se bloquean otros procesos o subprocesos esperando que el candado se desbloquee, permite que continúe exactamente uno de ellos. Si después del decremento el nivel de recursión sigue siendo distinto de cero, el candado permanece bloqueado y pertenece al proceso de llamada o subproceso.

Solo llame a este método cuando el proceso o subproceso de llamada sea el propietario del candado. Se lanza un AssertionError si se llama a este método mediante un proceso o subproceso que no sea el propietario o si el candado está en un estado desbloqueado (sin propietario). Tenga en cuenta que el tipo de excepción planteada en esta situación difiere del comportamiento implementado en threading.RLock.release().

class multiprocessing.Semaphore([value])

Un objeto semáforo: un análogo cercano de threading.Semaphore.

Existe una diferencia solitaria de su análogo cercano: el primer argumento de su método acquire es nombrado block, es consistente con Lock.acquire().

Nota

On macOS, sem_timedwait is unsupported, so calling acquire() with a timeout will emulate that function’s behavior using a sleeping loop.

Nota

Si la señal SIGINT generada por Ctrl-C llega mientras el hilo principal está bloqueado por una llamada a BoundedSemaphore.acquire(), Lock.acquire(), RLock.acquire(), Semaphore.acquire(), Condition.acquire() o Condition.wait(), la llamada se interrumpirá inmediatamente y KeyboardInterrupt se lanzará.

Esto difiere del comportamiento de threading donde SIGINT será ignorado mientras las llamadas de candado equivalentes están en progreso.

Nota

Parte de la funcionalidad de este paquete requiere una implementación de semáforo compartido que funcione en el sistema operativo. Sin uno, el módulo multiprocessing.synchronize se desactivará, y los intentos de importarlo darán como resultado ImportError. Consulte bpo-3770 [https://bugs.python.org/issue?@action=redirect&bpo=3770] para información adicional.

Objetos compartidos ctypes

Es posible crear objetos compartidos utilizando memoria compartida que puede ser heredada por procesos secundarios.

multiprocessing.Value(typecode_or_type, *args, lock=True)

Retorna un objeto ctypes asignado desde la memoria compartida. Por defecto, el valor de retorno es en realidad un contenedor sincronizado para el objeto. Se puede acceder al objeto en sí a través del atributo value de la Value.

typecode_or_type determina el tipo del objeto retornado: es un tipo ctypes o un código de tipo de un carácter del tipo utilizado por el módulo array. *args se pasa al constructor para el tipo.

Si lock es True (el valor predeterminado), se crea un nuevo objeto de candado recursivo para sincronizar el acceso al valor. Si lock es un objeto Lock o RLock, se usará para sincronizar el acceso al valor. Si lock es False, entonces el acceso al objeto retornado no estará protegido automáticamente por un candado, por lo que no será necesariamente «proceso-seguro».

Operaciones como += que implican una lectura y escritura no son atómicas. Entonces, si, por ejemplo, desea incrementar atómicamente un valor compartido, es insuficiente simplemente hacer:

counter.value += 1

Suponiendo que el candado asociado es recursivo (que es por defecto), puede hacer

with counter.get_lock():
    counter.value += 1

Véase que lock es un argumento de solo una palabra clave.

multiprocessing.Array(typecode_or_type, size_or_initializer, *, lock=True)

Retorna una matriz ctypes asignada desde la memoria compartida. Por defecto, el valor de retorno es en realidad un contenedor sincronizado para el arreglo.

typecode_or_type determina el tipo de los elementos de la matriz retornada: es un tipo de tipo ctypes o un código de tipo de un carácter del tipo utilizado por el módulo array. Si size_or_initializer es un número entero, entonces determina la longitud de la matriz, y la matriz se pondrá a cero inicialmente. De lo contrario, size_or_initializer es una secuencia que se utiliza para inicializar la matriz y cuya longitud determina la longitud de la matriz.

Si lock es True (el valor predeterminado), se crea un nuevo objeto de bloqueo para sincronizar el acceso al valor. Si lock es un objeto Lock o RLock, se usará para sincronizar el acceso al valor. Si lock es False, entonces el acceso al objeto retornado no estará protegido automáticamente por un candado, por lo que no será necesariamente «proceso seguro».

Véase que lock es un argumento de solo una palabra clave.

Tenga en cuenta que una matriz de ctypes.c_char tiene atributos value y raw que le permiten a uno usarlo para almacenar y recuperar cadenas de caracteres.

El módulo multiprocessing.sharedctypes

El módulo multiprocessing.sharedctypes proporciona funciones para asignar objetos ctypes de la memoria compartida que pueden ser heredados por procesos secundarios.

Nota

Aunque es posible almacenar un puntero en la memoria compartida, recuerde que esto se referirá a una ubicación en el espacio de direcciones de un proceso específico. Sin embargo, es muy probable que el puntero sea inválido en el contexto de un segundo proceso y tratar de desreferenciar el puntero del segundo proceso puede causar un bloqueo.

multiprocessing.sharedctypes.RawArray(typecode_or_type, size_or_initializer)

Retorna una matriz ctypes asignada desde la memoria compartida.

typecode_or_type determina el tipo de los elementos de la matriz retornada: es un tipo de tipo ctypes o un código de tipo de un carácter del tipo utilizado por el módulo array. Si size_or_initializer es un entero, entonces determina la longitud de la matriz, y la matriz se pondrá a cero inicialmente. De lo contrario, size_or_initializer es una secuencia que se usa para inicializar la matriz y cuya longitud determina la longitud del arreglo.

Tenga en cuenta que configurar y obtener un elemento es potencialmente no atómico – utiliza Array() en su lugar para asegurarse de que el acceso se sincronice automáticamente mediante un candado.

multiprocessing.sharedctypes.RawValue(typecode_or_type, *args)

Retorna un objeto ctypes asignado desde la memoria compartida.

typecode_or_type determina el tipo del objeto retornado: es un tipo ctypes o un código de tipo de un carácter del tipo utilizado por el módulo array. *args se pasa al constructor para el tipo.

Tenga en cuenta que configurar y obtener el valor es potencialmente no atómico – use Value() en su lugar para asegurarse de que el acceso se sincronice automáticamente mediante un candado.

Tenga en cuenta que una matriz de ctypes.c_char tiene atributos value y` raw` que le permiten a uno usarlo para almacenar y recuperar cadenas de caracteres – consulte la documentación para ctypes.

multiprocessing.sharedctypes.Array(typecode_or_type, size_or_initializer, *, lock=True)

Lo mismo que RawArray(), excepto que, dependiendo del valor de lock, se puede retornar un contenedor de sincronización seguro para el proceso en lugar de un arreglo de tipos crudos.

Si lock es True (el valor predeterminado), se crea un nuevo objeto candado para sincronizar el acceso al valor. Si lock es un objeto Lock o RLock, se utilizará para sincronizar el acceso al valor. Si lock es `` False``, entonces el acceso al objeto retornado no estará protegido automáticamente por un candado, por lo que no será necesariamente «seguro para el proceso».

Véase que lock es un argumento de solo una palabra clave.

multiprocessing.sharedctypes.Value(typecode_or_type, *args, lock=True)

Lo mismo que RawValue() excepto que, dependiendo del valor de lock, se puede retornar una envoltura de sincronización segura para el proceso en lugar de un objeto ctypes sin procesar.

Si lock es True (el valor predeterminado), se crea un nuevo objeto candado para sincronizar el acceso al valor. Si lock es un objeto Lock o RLock, se utilizará para sincronizar el acceso al valor. Si lock es `` False``, entonces el acceso al objeto retornado no estará protegido automáticamente por un candado, por lo que no será necesariamente «seguro para el proceso».

Véase que lock es un argumento de solo una palabra clave.

multiprocessing.sharedctypes.copy(obj)

Retorna un objeto ctypes asignado de la memoria compartida, que es una copia del objeto ctypes obj.

multiprocessing.sharedctypes.synchronized(obj[, lock])

Retorna un objeto contenedor seguro para un objeto ctypes que usa lock para sincronizar el acceso. Si lock es None (el valor predeterminado), se crea automáticamente un objeto multiprocessing.RLock.

Un contenedor sincronizado tendrá dos métodos además de los del objeto que envuelve: get_obj() retorna el objeto envuelto y get_lock() retorna el objeto de bloqueo utilizado para la sincronización.

Tenga en cuenta que acceder al objeto ctypes a través del contenedor puede ser mucho más lento que acceder al objeto ctypes sin formato.

Distinto en la versión 3.5: Los objetos sincronizados admiten el protocolo: context manager.

La siguiente tabla compara la sintaxis para crear objetos ctypes compartidos desde la memoria compartida con la sintaxis ctypes normal. (En la tabla MyStruct hay alguna subclase de ctypes.Structure.)

ctypes

sharedctypes usando type

sharedctypes usando typecode

c_double(2.4)

RawValue(c_double, 2.4)

RawValue(“d”, 2.4)

MyStruct(4, 6)

RawValue(MyStruct, 4, 6)

(c_short * 7)()

RawArray(c_short, 7)

RawArray(‘h’, 7)

(c_int * 3)(9, 2, 8)

RawArray(c_int, (9, 2, 8))

RawArray(“i”, (9, 2, 8))

A continuación se muestra un ejemplo donde un número de objetos ctypes son modificados por un proceso hijo:

from multiprocessing import Process, Lock
from multiprocessing.sharedctypes import Value, Array
from ctypes import Structure, c_double

class Point(Structure):
    _fields_ = [('x', c_double), ('y', c_double)]

def modify(n, x, s, A):
    n.value **= 2
    x.value **= 2
    s.value = s.value.upper()
    for a in A:
        a.x **= 2
        a.y **= 2

if __name__ == '__main__':
    lock = Lock()

    n = Value('i', 7)
    x = Value(c_double, 1.0/3.0, lock=False)
    s = Array('c', b'hello world', lock=lock)
    A = Array(Point, [(1.875,-6.25), (-5.75,2.0), (2.375,9.5)], lock=lock)

    p = Process(target=modify, args=(n, x, s, A))
    p.start()
    p.join()

    print(n.value)
    print(x.value)
    print(s.value)
    print([(a.x, a.y) for a in A])

Los resultados impresos son

49
0.1111111111111111
HELLO WORLD
[(3.515625, 39.0625), (33.0625, 4.0), (5.640625, 90.25)]

Administradores (Managers)

Los administradores (managers) proporcionan una forma de crear datos que se pueden compartir entre diferentes procesos, incluido el intercambio en una red entre procesos que se ejecutan en diferentes máquinas. Un objeto administrador controla un proceso de servidor que gestiona shared objects (objetos compartidos). Otros procesos pueden acceder a los objetos compartidos mediante el uso de servidores proxy.

multiprocessing.Manager()

Retorna un objeto iniciado SyncManager que se puede usar para compartir objetos entre procesos. El objeto administrador retornado corresponde a un proceso hijo generado y tiene métodos que crearán objetos compartidos y retornarán los proxies correspondientes.

Los procesos del administrador se cerrarán tan pronto como se recolecte la basura o salga su proceso padre. Las clases de administrador se definen en el módulo multiprocessing.managers:

class multiprocessing.managers.BaseManager([address[, authkey]])

Crear un objeto BaseManager.

Una vez creado, debe llamar a start() o get_server().serve_forever() para asegurarse de que el objeto de administrador se refiera a un proceso de administrador iniciado.

address es la dirección en la que el proceso del administrador escucha las nuevas conexiones. Si address es None, se elige una arbitrariamente.

authkey es la clave de autenticación que se utilizará para verificar la validez de las conexiones entrantes al proceso del servidor. Si authkey es None, entonces se usa current_process().authkey. De lo contrario, se usa authkey y debe ser una cadena de bytes.

start([initializer[, initargs]])

Se inicia un subproceso para iniciar el administrador. Si initializer no es None, entonces el subproceso llamará initializer(*initargs) cuando se inicie.

get_server()

Retorna un objeto Server que representa el servidor real bajo el control del Administrador. El objeto Server admite el método serve_forever():

>>> from multiprocessing.managers import BaseManager
>>> manager = BaseManager(address=('', 50000), authkey=b'abc')
>>> server = manager.get_server()
>>> server.serve_forever()

Server tiene un atributo adicional address.

connect()

Conecta un objeto de administrador (manager) local a un proceso de administrador remoto:

>>> from multiprocessing.managers import BaseManager
>>> m = BaseManager(address=('127.0.0.1', 50000), authkey=b'abc')
>>> m.connect()

shutdown()

Detiene el proceso utilizado por el gerente (manager). Esto solo está disponible si start() se ha utilizado para iniciar el proceso del servidor.

Esto se puede llamar múltiples veces.

register(typeid[, callable[, proxytype[, exposed[, method_to_typeid[, create_method]]]]])

Un método de clase que puede usarse para registrar un tipo o invocarse con la clase de administrador (manager).

typeid es un «identificador de tipo» que se utiliza para identificar un tipo particular de objeto compartido. Esto debe ser una cadena de caracteres.

callable es un invocable utilizado para crear objetos para este identificador de tipo. Si una instancia de administrador se conectará al servidor utilizando el método connect(), o si el argumento create_method es False, esto se puede dejar como None.

proxytype es una subclase de BaseProxy que se usa para crear proxies para objetos compartidos con este typeid. Si None, se crea automáticamente una clase proxy.

Se utiliza exposed para especificar una secuencia de nombres de métodos a los que se debe permitir el acceso de los servidores proxy para este tipo de identificación utilizando BaseProxy._callmethod(). (Si exposed es None, entonces proxytype._exposed_ se usa en su lugar si existe). En el caso de que no se especifique una lista expuesta, todos los «métodos públicos» del objeto compartido serán accesibles . (Aquí un «método público» significa cualquier atributo que tenga un método __call__() y cuyo nombre no comience con '_'.)

El method_to_typeid es una asignación utilizada para especificar el tipo de retorno de los métodos expuestos que deberían retornar un proxy. Asigna nombres de métodos a cadenas typeid. (Si method_to_typeid es None entonces proxytype._method_to_typeid se usa en su lugar si existe). Si el nombre de un método no es una clave de esta asignación o si la asignación es None entonces el objeto retornado por el método se copiará por valor.

create_method determina si un método debe crearse con el nombre typeid que se puede usar para indicarle al proceso del servidor que cree un nuevo objeto compartido y retornando un proxy para él. Por defecto es True.

BaseManager las instancias también tienen una propiedad de solo lectura:

address

La dirección utilizada por el administrador.

Distinto en la versión 3.3: Los objetos de administrador admiten el protocolo de gestión de contexto; consulte Tipos Gestores de Contexto. __enter__() inicia el proceso del servidor (si aún no se ha iniciado) y luego retorna el objeto de administrador. __exit__() llama shutdown().

En versiones anteriores __enter__() no iniciaba el proceso del servidor del administrador si aún no se había iniciado.

class multiprocessing.managers.SyncManager

Una subclase de BaseManager que se puede utilizar para la sincronización de procesos. Los objetos de este tipo son retornados por multiprocessing.Manager().

Sus métodos crean y retornan Objetos Proxy (Proxy Objects) para varios tipos de datos de uso común que se sincronizarán entre procesos. Esto incluye notablemente listas compartidas y diccionarios.

Barrier(parties[, action[, timeout]])

threading.Barrier crea un objeto compartido y retorna un proxy para él.

Nuevo en la versión 3.3.

BoundedSemaphore([value])

Crea un objeto compartido threading.BoundedSemaphore y retorna un proxy para él.

Condition([lock])

Crea un objeto compartido threading.Condition y retorna un proxy para él.

Si se proporciona lock, debería ser un proxy para un objeto threading.Lock o threading.RLock.

Distinto en la versión 3.3: El método wait_for() fue a añadido.

Event()

Crea un objeto compartido threading.Event y retorna un proxy para él.

Lock()

Crea un objeto compartido threading.Lock y retorna un proxy para él.

Namespace()

Crea un objeto compartido Namespace y retorna un proxy para él.

Queue([maxsize])

Crea un objeto compartido queue.Queue y retorna un proxy para él.

RLock()

Crea un objeto compartido threading.RLock y retorna un proxy para él.

Semaphore([value])

Crea un objeto compartido threading.Semaphore y retorna un proxy para él.

Array(typecode, sequence)

Crea un arreglo y retorna un proxy para ello.

Value(typecode, value)

Crea un objeto con un atributo de escritura value y retorna un proxy para él.

dict()

dict(mapping)

dict(sequence)

Crea un objeto compartido dict y retorna un proxy para él.

list()

list(sequence)

Crea un objeto compartido list y retorna un proxy para él.

Distinto en la versión 3.6: Los objetos compartidos pueden anidarse. Por ejemplo, un objeto contenedor compartido, como una lista compartida, puede contener otros objetos compartidos que serán administrados y sincronizados por SyncManager.

class multiprocessing.managers.Namespace

Un tipo que puede registrarse con SyncManager.

Un objeto de espacio de nombres no tiene métodos públicos, pero tiene atributos de escritura. Su representación muestra los valores de sus atributos.

Sin embargo, cuando se usa un proxy para un objeto de espacio de nombres, un atributo que comience con '_' será un atributo del proxy y no un atributo del referente:

>>> manager = multiprocessing.Manager()
>>> Global = manager.Namespace()
>>> Global.x = 10
>>> Global.y = 'hello'
>>> Global._z = 12.3    # this is an attribute of the proxy
>>> print(Global)
Namespace(x=10, y='hello')

Administradores customizables (Customized managers)

Para crear su propio administrador, uno crea una subclase de BaseManager y utiliza el método de clase register() para registrar nuevos tipos o llamadas con la clase de administrador. Por ejemplo:

from multiprocessing.managers import BaseManager

class MathsClass:
    def add(self, x, y):
        return x + y
    def mul(self, x, y):
        return x * y

class MyManager(BaseManager):
    pass

MyManager.register('Maths', MathsClass)

if __name__ == '__main__':
    with MyManager() as manager:
        maths = manager.Maths()
        print(maths.add(4, 3))         # prints 7
        print(maths.mul(7, 8))         # prints 56

Utilizando un administrador remoto

Es posible ejecutar un servidor administrador en una máquina y hacer que los clientes lo usen desde otras máquinas (suponiendo que los cortafuegos involucrados lo permitan).

La ejecución de los siguientes comandos crea un servidor para una única cola compartida a la que los clientes remotos pueden acceder:

>>> from multiprocessing.managers import BaseManager
>>> from queue import Queue
>>> queue = Queue()
>>> class QueueManager(BaseManager): pass
>>> QueueManager.register('get_queue', callable=lambda:queue)
>>> m = QueueManager(address=('', 50000), authkey=b'abracadabra')
>>> s = m.get_server()
>>> s.serve_forever()

Un cliente puede tener accesos al servidor de la siguiente manera:

>>> from multiprocessing.managers import BaseManager
>>> class QueueManager(BaseManager): pass
>>> QueueManager.register('get_queue')
>>> m = QueueManager(address=('foo.bar.org', 50000), authkey=b'abracadabra')
>>> m.connect()
>>> queue = m.get_queue()
>>> queue.put('hello')

Otro cliente puede también usarlo:

>>> from multiprocessing.managers import BaseManager
>>> class QueueManager(BaseManager): pass
>>> QueueManager.register('get_queue')
>>> m = QueueManager(address=('foo.bar.org', 50000), authkey=b'abracadabra')
>>> m.connect()
>>> queue = m.get_queue()
>>> queue.get()
'hello'

Los procesos locales también pueden acceder a esa cola (queue), utilizando el código de arriba en el cliente para acceder de forma remota:

>>> from multiprocessing import Process, Queue
>>> from multiprocessing.managers import BaseManager
>>> class Worker(Process):
...     def __init__(self, q):
...         self.q = q
...         super().__init__()
...     def run(self):
...         self.q.put('local hello')
...
>>> queue = Queue()
>>> w = Worker(queue)
>>> w.start()
>>> class QueueManager(BaseManager): pass
...
>>> QueueManager.register('get_queue', callable=lambda: queue)
>>> m = QueueManager(address=('', 50000), authkey=b'abracadabra')
>>> s = m.get_server()
>>> s.serve_forever()

Objetos Proxy (Proxy Objects)

Un proxy es un objeto que se refiere a un objeto compartido que vive (presumiblemente) en un proceso diferente. Se dice que el objeto compartido es el referente del proxy. Varios objetos proxy pueden tener el mismo referente.

Un objeto proxy tiene métodos que invocan los métodos correspondientes de su referente (aunque no todos los métodos del referente estarán necesariamente disponibles a través del proxy). De esta manera, un proxy se puede usar al igual que su referente:

>>> from multiprocessing import Manager
>>> manager = Manager()
>>> l = manager.list([i*i for i in range(10)])
>>> print(l)
[0, 1, 4, 9, 16, 25, 36, 49, 64, 81]
>>> print(repr(l))
<ListProxy object, typeid 'list' at 0x...>
>>> l[4]
16
>>> l[2:5]
[4, 9, 16]

Tenga en cuenta que la aplicación str() a un proxy retornará la representación del referente, mientras que la aplicación repr() retornará la representación del proxy.

Una característica importante de los objetos proxy es que son seleccionables para que puedan pasarse entre procesos. Como tal, un referente puede contener Objetos Proxy (Proxy Objects). Esto permite anidar estas listas administradas, dictados y otros Objetos Proxy (Proxy Objects):

>>> a = manager.list()
>>> b = manager.list()
>>> a.append(b)         # referent of a now contains referent of b
>>> print(a, b)
[<ListProxy object, typeid 'list' at ...>] []
>>> b.append('hello')
>>> print(a[0], b)
['hello'] ['hello']

Del mismo modo, los proxies dict y list pueden estar anidados uno dentro del otro:

>>> l_outer = manager.list([ manager.dict() for i in range(2) ])
>>> d_first_inner = l_outer[0]
>>> d_first_inner['a'] = 1
>>> d_first_inner['b'] = 2
>>> l_outer[1]['c'] = 3
>>> l_outer[1]['z'] = 26
>>> print(l_outer[0])
{'a': 1, 'b': 2}
>>> print(l_outer[1])
{'c': 3, 'z': 26}

Si los objetos estándar (no proxy) list or dict están contenidos en un referente, las modificaciones a esos valores mutables no se propagarán a través del administrador porque el proxy no tiene forma de saber cuándo los valores contenidos dentro son modificados. Sin embargo, almacenar un valor en un proxy de contenedor (que desencadena un __setitem__ en el objeto proxy) se propaga a través del administrador y, por lo tanto, para modificar efectivamente dicho elemento, uno podría reasignar el valor modificado al proxy de contenedor:

# create a list proxy and append a mutable object (a dictionary)
lproxy = manager.list()
lproxy.append({})
# now mutate the dictionary
d = lproxy[0]
d['a'] = 1
d['b'] = 2
# at this point, the changes to d are not yet synced, but by
# updating the dictionary, the proxy is notified of the change
lproxy[0] = d

Este enfoque es quizás menos conveniente que emplear anidado Objetos Proxy (Proxy Objects) para la mayoría de los casos de uso, pero también demuestra un nivel de control sobre la sincronización.

Nota

Los tipos de proxy en multiprocessing no hacen nada para admitir comparaciones por valor. Entonces, por ejemplo, tenemos:

>>> manager.list([1,2,3]) == [1,2,3]
False

En su lugar, se debe usar una copia del referente al hacer comparaciones.

class multiprocessing.managers.BaseProxy

Los objetos proxy son instancias de subclases de BaseProxy.

_callmethod(methodname[, args[, kwds]])

Llama y retorna el resultado de un método del referente del proxy.

Si proxy es un proxy cuyo referente es obj entonces la expresión

proxy._callmethod(methodname, args, kwds)

evaluará la expresión

getattr(obj, methodname)(*args, **kwds)

en el proceso del administrador.

El valor retornado será una copia del resultado de la llamada o un proxy a un nuevo objeto compartido; consulte la documentación del argumento method_to_typeid de BaseManager.register().

Si la llamada genera una excepción, entonces se vuelve a generar _callmethod(). Si se genera alguna otra excepción en el proceso del administrador, esto se convierte en una excepción RemoteError y se genera mediante _callmethod().

Tenga en cuenta en particular que se generará una excepción si methodname no ha sido exposed.

Un ejemplo de uso de _callmethod():

>>> l = manager.list(range(10))
>>> l._callmethod('__len__')
10
>>> l._callmethod('__getitem__', (slice(2, 7),)) # equivalent to l[2:7]
[2, 3, 4, 5, 6]
>>> l._callmethod('__getitem__', (20,))          # equivalent to l[20]
Traceback (most recent call last):
...
IndexError: list index out of range

_getvalue()

Retorna una copia del referente.

Si el referente no se puede deserializar (unpicklable), esto generará una excepción.

__repr__()

Retorna una representación de un objeto proxy.

__str__()

Retorna una representación del referente.

Limpieza (Cleanup)

Un objeto proxy utiliza una devolución de llamada (callback) de referencia débil (weakref) para que cuando sea recolectado por el recolector de basura se da de baja del administrador que posee su referente.

Un objeto compartido se elimina del proceso del administrador cuando ya no hay ningún proxy que se refiera a él.

Piscinas de procesos (Process Pools)

Se puede crear un grupo de procesos que llevarán a cabo las tareas que se le presenten con la Pool class.

class multiprocessing.pool.Pool([processes[, initializer[, initargs[, maxtasksperchild[, context]]]]])

Un objeto de grupo de procesos que controla un grupo de procesos de trabajo a los que se pueden enviar trabajos. Admite resultados asincrónicos con tiempos de espera y devoluciones de llamada y tiene una implementación de mapa paralelo.

processes es el número de procesos de trabajo a utilizar. Si processes es None , se utiliza el número retornado por os.cpu_count().

Si initializer no es None, cada proceso de trabajo llamará initializer(*initargs) cuando se inicie.

maxtasksperchild es el número de tareas que un proceso de trabajo puede completar antes de salir y ser reemplazado por un proceso de trabajo nuevo, para permitir que se liberen los recursos no utilizados. El valor predeterminado maxtasksperchild es None, lo que significa que los procesos de trabajo vivirán tanto tiempo como el grupo.

context se puede utilizar para especificar el contexto utilizado para iniciar los procesos de trabajo. Por lo general, un grupo se crea utilizando la función multiprocessing.Pool() o el método de un objeto de contexto Pool(). En ambos casos, context se establece de manera adecuada.

Tenga en cuenta que los métodos del objeto de grupo solo deben ser invocados por el proceso que creó el grupo.

Advertencia

Los objetos multiprocessing.pool tienen recursos internos que necesitan ser administrados adecuadamente (como cualquier otro recurso) utilizando el grupo como administrador de contexto o llamando a close() y terminate() manualmente. De lo contrario, el proceso puede demorarse en la finalización.

Tenga en cuenta que no es correcto confiar en el recolector de basura para destruir el grupo ya que CPython no asegura que se llamará al finalizador del grupo (consulte object.__del__() para obtener más información).

Nuevo en la versión 3.2: maxtasksperchild

Nuevo en la versión 3.4: context

Nota

Los procesos de los trabajadores dentro de una Pool normalmente viven durante la duración completa de la cola de trabajo de la piscina. Un patrón frecuente que se encuentra en otros sistemas (como Apache, mod_wsgi, etc.) para liberar recursos en poder de los trabajadores es permitir que un trabajador dentro de un grupo complete solo una cantidad determinada de trabajo antes de salir, limpiarse y generar un nuevo proceso para reemplazar el viejo. El argumento maxtasksperchild para Pool expone esta capacidad al usuario final.

apply(func[, args[, kwds]])

Llama a func con argumentos args y argumentos de palabras clave kwds. Se bloquea hasta que el resultado esté listo. Dados estos bloques, apply_async() es más adecuado para realizar trabajos en paralelo. Además, func solo se ejecuta en uno de los trabajadores de piscina.

apply_async(func[, args[, kwds[, callback[, error_callback]]]])

Una variante del método apply() que retorna un objeto AsyncResult.

Si se especifica callback, debería ser un invocable que acepte un único argumento. Cuando el resultado está listo, se le aplica callback, a menos que la llamada falle, en cuyo caso se aplica error_callback.

Si se especifica error_callback, debería ser un invocable que acepte un único argumento. Si la función de destino falla, se llama a error_callback con la instancia de excepción.

Las devoluciones de llamada deben completarse inmediatamente ya que de lo contrario el hilo que maneja los resultados se bloqueará.

map(func, iterable[, chunksize])

Un equivalente paralelo de la función incorporada map() (aunque solo admite un argumento iterable, para varios iterables consulte starmap()). Bloquea hasta que el resultado esté listo.

Este método corta el iterable en varios trozos que envía al grupo de procesos como tareas separadas. El tamaño (aproximado) de estos fragmentos se puede especificar estableciendo chunksize en un entero positivo.

Tenga en cuenta que puede causar un alto uso de memoria para iterables muy largos. Considere usar imap() o imap_unordered() con la opción explícita chunksize para una mejor eficiencia.

map_async(func, iterable[, chunksize[, callback[, error_callback]]])

Una variante del método map() que retorna un objeto AsyncResult.

Si se especifica callback, debería ser un invocable que acepte un único argumento. Cuando el resultado está listo, se le aplica callback, a menos que la llamada falle, en cuyo caso se aplica error_callback.

Si se especifica error_callback, debería ser un invocable que acepte un único argumento. Si la función de destino falla, se llama a error_callback con la instancia de excepción.

Las devoluciones de llamada deben completarse inmediatamente ya que de lo contrario el hilo que maneja los resultados se bloqueará.

imap(func, iterable[, chunksize])

Una versión más perezosa (lazier) de map().

El argumento chunksize es el mismo que el utilizado por el método map(). Para iterables muy largos, usar un valor grande para chunksize puede hacer que el trabajo se complete much (mucho) más rápido que usar el valor predeterminado de 1.

Además, si chunksize es 1, el método next() del iterador retornado por el método imap() tiene un parámetro opcional timeout :next (timeout) lanzará multiprocessing.TimeoutError si el resultado no puede retornarse dentro de timeout segundos.

imap_unordered(func, iterable[, chunksize])

Lo mismo que imap(), excepto que el orden de los resultados del iterador retornado debe considerarse arbitrario. (Solo cuando hay un solo proceso de trabajo se garantiza que el orden sea «correcto»).

starmap(func, iterable[, chunksize])

Like map() except that the elements of the iterable are expected to be iterables that are unpacked as arguments.

Por lo tanto, un iterable de [(1,2), (3, 4)] da como resultado [func(1,2), func(3,4)].

Nuevo en la versión 3.3.

starmap_async(func, iterable[, chunksize[, callback[, error_callback]]])

Una combinación de starmap() y map_async() que itera sobre iterable de iterables y llama a func con los iterables desempaquetados. Como resultado se retorna un objeto.

Nuevo en la versión 3.3.

close()

Impide que se envíen más tareas a la piscina (pool). Una vez que se hayan completado todas las tareas, se cerrarán los procesos de trabajo.

terminate()

Detiene los procesos de trabajo inmediatamente sin completar el trabajo pendiente. Cuando el objeto del grupo es basura recolectada terminate() se llamará inmediatamente.

join()

Espera a que salgan los procesos de trabajo. Se debe llamar close() o terminate() antes de usar join().

Nuevo en la versión 3.3: Los objetos de piscina (pool) ahora admiten el protocolo de administración de contexto; consulte Tipos Gestores de Contexto. __ enter__() retorna el objeto de grupo, y __ exit__() llama terminate().

class multiprocessing.pool.AsyncResult

La clase del resultado retornado por Pool.apply_async() y Pool.map_async().

get([timeout])

Retorna el resultado cuando llegue. Si timeout no es None y el resultado no llega dentro de timeout segundos, entonces se lanza multiprocessing.TimeoutError. Si la llamada remota generó una excepción, esa excepción se volverá a plantear mediante get().

wait([timeout])

Espera hasta que el resultado esté disponible o hasta que pase timeout segundos.

ready()

Retorna si la llamada se ha completado.

successful()

Retorna si la llamada se completó sin generar una excepción. Lanzará ValueError si el resultado no está listo.

Distinto en la versión 3.7: Si el resultado no está listo ValueError aparece en lugar de AssertionError.

El siguiente ejemplo demuestra el uso de una piscina(pool):

from multiprocessing import Pool
import time

def f(x):
    return x*x

if __name__ == '__main__':
    with Pool(processes=4) as pool:         # start 4 worker processes
        result = pool.apply_async(f, (10,)) # evaluate "f(10)" asynchronously in a single process
        print(result.get(timeout=1))        # prints "100" unless your computer is *very* slow

        print(pool.map(f, range(10)))       # prints "[0, 1, 4,..., 81]"

        it = pool.imap(f, range(10))
        print(next(it))                     # prints "0"
        print(next(it))                     # prints "1"
        print(it.next(timeout=1))           # prints "4" unless your computer is *very* slow

        result = pool.apply_async(time.sleep, (10,))
        print(result.get(timeout=1))        # raises multiprocessing.TimeoutError

Oyentes y Clientes (Listeners and Clients)

Por lo general, el paso de mensajes entre procesos se realiza mediante colas o mediante objetos Connection retornados por Pipe().

Sin embargo, el módulo multiprocessing.connection permite cierta flexibilidad adicional. Básicamente proporciona una API orientada a mensajes de alto nivel para tratar con sockets o canalizaciones con nombre de Windows. También tiene soporte para digest authentication usando el módulo hmac, y para sondear múltiples conexiones al mismo tiempo.

multiprocessing.connection.deliver_challenge(connection, authkey)

Envía un mensaje generado aleatoriamente al otro extremo de la conexión y espera una respuesta.

Si la respuesta coincide con el resumen del mensaje utilizando authkey como clave, se envía un mensaje de bienvenida al otro extremo de la conexión. De lo contrario se lanza AuthenticationError.

multiprocessing.connection.answer_challenge(connection, authkey)

Recibe un mensaje, calcula el resumen del mensaje usando authkey como la clave y luego envía el resumen de vuelta.

Si no se recibe un mensaje de bienvenida, se lanza AuthenticationError.

multiprocessing.connection.Client(address[, family[, authkey]])

Se intenta configurar una conexión con el oyente que utiliza la dirección address, retornando Connection.

El tipo de conexión está determinado por el argumento family, pero esto generalmente se puede omitir ya que generalmente se puede inferir del formato de address. (Consulte Formatos de dirección (Address formats))

Si se proporciona authkey y no None, debe ser una cadena de bytes y se utilizará como clave secreta para un desafío de autenticación basado en HMAC. No se realiza la autenticación si authkey es None. Si falla la autenticación se lanza AuthenticationError. Consulte Llaves de autentificación.

class multiprocessing.connection.Listener([address[, family[, backlog[, authkey]]]])

Un contenedor para un socket vinculado o una tubería (pipe) con nombre de Windows que está “escuchando” las conexiones.

address es la dirección que utilizará el socket vinculado o la conocida tubería (pipe) con nombre del objeto de escucha.

Nota

Si se usa una dirección de “0.0.0.0” , la dirección no será un punto final conectable en Windows. Si necesita un punto final conectable, debe usar “127.0.0.1”.

family es el tipo de socket (o tubería con nombre) a utilizar. Esta puede ser una de las cadenas de caracteres 'AF_INET' (para un socket TCP), ' AF_UNIX' (para un socket de dominio Unix) o 'AF_PIPE' (para una tubería con nombre de Windows) . De estos, solo el primero está garantizado para estar disponible. Si family es None , family se deduce del formato de address. Si address también es None , se elige un valor predeterminado. Este valor predeterminado es family con la opción más rápida disponible. Consulte Formatos de dirección (Address formats). Tenga en cuenta que si family es 'AF_UNIX' y la dirección es None, el socket se creará en un directorio temporal privado usando tempfile.mkstemp().

Si el objeto de escucha utiliza un socket, entonces backlog (1 por defecto) se pasa al método listen() del socket una vez que se ha vinculado.

Si se proporciona authkey y no None, debe ser una cadena de bytes y se utilizará como clave secreta para un desafío de autenticación basado en HMAC. No se realiza la autenticación si authkey es None. Si falla la autenticación se lanza AuthenticationError. Consulte Llaves de autentificación.

accept()

Acepta una conexión en el socket vinculado o canalización con nombre del objeto de escucha y retorne un objeto Connection. Si se intenta la autenticación y falla, entonces se lanza una AuthenticationError.

close()

Cierra el socket vinculado o la tubería con nombre del objeto de escucha. Esto se llama automáticamente cuando el oyente es recolectado por el recolector de basura. Sin embargo, es aconsejable llamarlo explícitamente.

Los objetos de escucha tienen las siguientes propiedades de solo lectura:

address

La dirección que está utilizando el objeto Listener.

last_accepted

La dirección de donde vino la última conexión aceptada. Si esto no está disponible, entonces es None.

Nuevo en la versión 3.3: Los objetos de escucha ahora admiten el protocolo de gestión de contexto – consulte Tipos Gestores de Contexto. El objeto lISTENER retorna __enter__(), y __exit__() llama a close().

multiprocessing.connection.wait(object_list, timeout=None)

Espera hasta que un objeto en object_list esté listo. Retorna la lista de esos objetos en object_list que están listos. Si timeout es flotante, la llamada se bloquea durante como máximo tantos segundos. Si timeout es `None, se bloqueará por un período ilimitado. Un tiempo de espera negativo es equivalente a un tiempo de espera cero.

Tanto para Unix como para Windows, un objeto puede aparecer en object_list si este es

un objeto legible de Connection;

un objeto conectado y legible de socket.socket; o

el atributo sentinel de un objeto Process.

Un objeto de conexión o socket está listo cuando hay datos disponibles para leer, o el otro extremo se ha cerrado.

Unix: wait(object_list, timeout) es casi equivalente a select.select(object_list, [], [], timeout). La diferencia es que si se interrumpe select.select() por una señal, este lanza OSError con un número de error EINTR, a diferencia de wait().

Windows: Un elemento en object_list debe ser un identificador de número entero que se pueda esperar (de acuerdo con la definición utilizada por la documentación de la función Win32 WaitForMultipleObjects()) o puede ser un objeto con un fileno() Método que retorna un manejador de tubo o manejador de tubería. (Tenga en cuenta que las manijas de las tuberías y las manijas de los zócalos son no manijas aptas)

Nuevo en la versión 3.3.

Ejemplos

El siguiente código de servidor crea un escucha que utiliza 'secret password' como clave de autenticación. Luego espera una conexión y envía algunos datos al cliente:

from multiprocessing.connection import Listener
from array import array

address = ('localhost', 6000)     # family is deduced to be 'AF_INET'

with Listener(address, authkey=b'secret password') as listener:
    with listener.accept() as conn:
        print('connection accepted from', listener.last_accepted)

        conn.send([2.25, None, 'junk', float])

        conn.send_bytes(b'hello')

        conn.send_bytes(array('i', [42, 1729]))

El siguiente código se conecta al servidor y recibe algunos datos del servidor:

from multiprocessing.connection import Client
from array import array

address = ('localhost', 6000)

with Client(address, authkey=b'secret password') as conn:
    print(conn.recv())                  # => [2.25, None, 'junk', float]

    print(conn.recv_bytes())            # => 'hello'

    arr = array('i', [0, 0, 0, 0, 0])
    print(conn.recv_bytes_into(arr))    # => 8
    print(arr)                          # => array('i', [42, 1729, 0, 0, 0])

El siguiente código utiliza wait() para esperar mensajes de múltiples procesos a la vez:

import time, random
from multiprocessing import Process, Pipe, current_process
from multiprocessing.connection import wait

def foo(w):
    for i in range(10):
        w.send((i, current_process().name))
    w.close()

if __name__ == '__main__':
    readers = []

    for i in range(4):
        r, w = Pipe(duplex=False)
        readers.append(r)
        p = Process(target=foo, args=(w,))
        p.start()
        # We close the writable end of the pipe now to be sure that
        # p is the only process which owns a handle for it.  This
        # ensures that when p closes its handle for the writable end,
        # wait() will promptly report the readable end as being ready.
        w.close()

    while readers:
        for r in wait(readers):
            try:
                msg = r.recv()
            except EOFError:
                readers.remove(r)
            else:
                print(msg)

Formatos de dirección (Address formats)

Una dirección 'AF_INET' es una tupla de la forma (hostname, port) donde hostname es una cadena de caracteres y port es un número entero.

Una dirección 'AF_UNIX' es una cadena que representa un nombre de archivo en el sistema de archivos.

Una dirección 'AF_PIPE' es una cadena de la forma r'\.\pipe{PipeName}'. Para usar Client() para conectarse a una tubería (pipe) con nombre en un ordenador remoto llamada ServerName uno debe usar una dirección del formulario r'\ServerName\pipe{PipeName}'.

Tenga en cuenta que cualquier cadena que comience con dos barras inclinadas invertidas se asume por defecto como una dirección 'AF_PIPE' en lugar de una dirección 'AF_UNIX'.

Llaves de autentificación

Cuando uno usa Connection.recv, los datos recibidos se desbloquean automáticamente. Desafortunadamente, la eliminación de datos de una fuente no confiable es un riesgo de seguridad. Por lo tanto Listener y Client() usan el módulo hmac para proporcionar autenticación de resumen.

Una clave de autenticación es una cadena de bytes que se puede considerar como una contraseña: una vez que se establece una conexión, ambos extremos exigirán pruebas de que el otro conoce la clave de autenticación. (Demostrar que ambos extremos están usando la misma clave no implica enviar la clave a través de la conexión).

Si se solicita la autenticación pero no se especifica una clave de autenticación, se utiliza el valor de retorno de current_process().authkey (consulte Process ). Este valor será heredado automáticamente por cualquier objeto Process que crea el proceso actual. Esto significa que (por defecto) todos los procesos de un programa multiproceso compartirán una única clave de autenticación que se puede usar al configurar conexiones entre ellos.

Las claves de autenticación adecuadas también se pueden generar utilizando os.urandom().

Logging

Existe cierto soporte para el registro. Sin embargo, tenga en cuenta que el paquete logging no utiliza candados compartidos de proceso, por lo que es posible (dependiendo del tipo de controlador) que los mensajes de diferentes procesos se mezclen.

multiprocessing.get_logger()

Retorna el registrador utilizado por multiprocessing. Si es necesario, se creará uno nuevo.

Cuando se creó por primera vez, el registrador tiene nivel logging.NOTSET y no tiene un controlador predeterminado. Los mensajes enviados a este registrador no se propagarán por defecto al registrador raíz.

Tenga en cuenta que en Windows los procesos hijos solo heredarán el nivel del registrador del proceso parental – no se heredará ninguna otra personalización del registrador.

multiprocessing.log_to_stderr(level=None)

This function performs a call to get_logger() but in addition to returning the logger created by get_logger, it adds a handler which sends output to sys.stderr using format '[%(levelname)s/%(processName)s] %(message)s'. You can modify levelname of the logger by passing a level argument.

A continuación se muestra una sesión de ejemplo con el registro activado:

>>> import multiprocessing, logging
>>> logger = multiprocessing.log_to_stderr()
>>> logger.setLevel(logging.INFO)
>>> logger.warning('doomed')
[WARNING/MainProcess] doomed
>>> m = multiprocessing.Manager()
[INFO/SyncManager-...] child process calling self.run()
[INFO/SyncManager-...] created temp directory /.../pymp-...
[INFO/SyncManager-...] manager serving at '/.../listener-...'
>>> del m
[INFO/MainProcess] sending shutdown message to manager
[INFO/SyncManager-...] manager exiting with exitcode 0

Para obtener una tabla completa de niveles de registro, consulte el módulo logging.

El módulo multiprocessing.dummy

El multiprocessing.dummy replica la API de multiprocessing pero no es más que un contenedor alrededor del módulo threading.

En particular, la función Pool ofrecida por multiprocessing.dummy retorna un instancia de ThreadPool, la cual es un subclase de Pool que soporta todas las mismas llamadas, pero usa un pool de hebras trabajadoras en vez de procesos trabajadores.

class multiprocessing.pool.ThreadPool([processes[, initializer[, initargs]]])

Un objeto de pool de hebras que controla un pool de hebras trabajadoras a las cuales se pueden enviar trabajos. La interfaz de las instancias de ThreadPool son totalmente compatibles con las instancias de Pool, y sus recursos también deben ser debidamente administrador, ya sea usando el pool como un gestor de contexto, o llamando a close() y terminate() manualmente.

processes es el número de hebras de trabajo a utilizar. Si processes es None , se utiliza el número retornado por os.cpu_count().

Si initializer no es None, cada proceso de trabajo llamará initializer(*initargs) cuando se inicie.

A diferencia de Pool, maxtasksperchild and context no se pueden entregar.

Nota

Un ThreadPool comparte la misma interfaz que Pool, la cual está diseñada alrededor de un pool de procesos, y precede la introducción del módulo concurrent.futures. Como tal, hereda algunas operaciones que no tienen sentido para un pool basado en hebras, y tiene su propio tipo para representar el estado de trabajos asíncronos, AsyncResult, el cual no es entendido por otras librerías.

Los usuarios deberían por lo general preferir usar concurrent.futures.ThreadPoolExecutor, el cual tiene una interfaz más simple que fue diseñada alrededor de hebras desde un principio, y que retorna instancias de concurrent.futures.Future, las que son compatibles con muchas más librerías, incluyendo asyncio.

Pautas de programación

Hay ciertas pautas y expresiones idiomáticas que deben tenerse en cuenta al usar multiprocessing .

Todos los métodos de inicio

Lo siguiente se aplica a todos los métodos de inicio.

Evita estado compartido

En la medida de lo posible, se debe tratar de evitar el desplazamiento de grandes cantidades de datos entre procesos.

Probablemente sea mejor seguir usando colas (queues) o tuberías (pipes) para la comunicación entre procesos en lugar de usar las primitivas de sincronización de nivel inferior.

Serialización (picklability)

Asegúrese que todos los argumentos de los métodos de proxies son serializables (pickable)

Seguridad de hilos de proxies

No usa un objeto proxy de más de un hilo a menos que lo proteja con un candado (lock).

(Nunca hay un problema con diferentes procesos que usan el mismo proxy.)

Uniéndose a procesos zombies

En Unix, cuando un proceso finaliza pero no se ha unido, se convierte en un zombie. Nunca debería haber muchos porque cada vez que se inicia un nuevo proceso (o se llama active_children()) se unirán todos los procesos completados que aún no se hayan unido. También llamando a un proceso terminado Process.is_alive se unirá al proceso. Aun así, probablemente sea una buena práctica unir explícitamente todos los procesos que comience.

Mejor heredar que serializar/deserializar (pickle/unpickle)

Cuando se usan los métodos de inicio spawn o forkserver, muchos tipos de multiprocesamiento deben ser seleccionables para que los procesos secundarios puedan usarlos. Sin embargo, generalmente se debe evitar enviar objetos compartidos a otros procesos mediante tuberías o colas. En su lugar, debe organizar el programa para que un proceso que necesita acceso a un recurso compartido creado en otro lugar pueda heredarlo de un proceso ancestro.

Evita procesos de finalización

El uso del método Process.terminate para detener un proceso puede causar que los recursos compartidos (como candados, semáforos, tuberías y colas) que el proceso utiliza actualmente se rompan o no disponible para otros procesos.

Por lo tanto, probablemente sea mejor considerar usar Process.terminate en procesos que nunca usan recursos compartidos.

Unirse a procesos que usan colas

Tenga en cuenta que un proceso que ha puesto elementos en una cola esperará antes de finalizar hasta que todos los elementos almacenados en búfer sean alimentados por el hilo «alimentador» a la tubería subyacente. (El proceso secundario puede llamar al método Queue.cancel_join_thread de la cola para evitar este comportamiento).

Esto significa que siempre que use una cola debe asegurarse de que todos los elementos que se hayan puesto en la cola se eliminarán antes de unirse al proceso. De lo contrario, no puede estar seguro de que los procesos que han puesto elementos en la cola finalizarán. Recuerde también que los procesos no demoníacos se unirán automáticamente.

Un ejemplo que de bloqueo mutuo (deadlock) es el siguiente

from multiprocessing import Process, Queue

def f(q):
    q.put('X' * 1000000)

if __name__ == '__main__':
    queue = Queue()
    p = Process(target=f, args=(queue,))
    p.start()
    p.join()                    # this deadlocks
    obj = queue.get()

Una solución aquí sería intercambiar las dos últimas líneas (o simplemente eliminar la línea p.join()).

Se pasan recursos explícitamente a procesos hijos

En Unix que utiliza el método de inicio fork, un proceso secundario puede hacer uso de un recurso compartido creado en un proceso primario utilizando un recurso global. Sin embargo, es mejor pasar el objeto como argumento al constructor para el proceso secundario.

Además de hacer que el código (potencialmente) sea compatible con Windows y los otros métodos de inicio, esto también garantiza que mientras el proceso secundario siga vivo, el objeto no se recolectará en el proceso primario. Esto podría ser importante si se libera algún recurso cuando el objeto es basura recolectada en el proceso padre.

Entonces por ejemplo

from multiprocessing import Process, Lock

def f():
    ... do something using "lock" ...

if __name__ == '__main__':
    lock = Lock()
    for i in range(10):
        Process(target=f).start()

debería ser reescrito como

from multiprocessing import Process, Lock

def f(l):
    ... do something using "l" ...

if __name__ == '__main__':
    lock = Lock()
    for i in range(10):
        Process(target=f, args=(lock,)).start()

Tenga cuidado de reemplazar sys.stdin con un «file like object»

multiprocessing original e incondicionalmente llamado:

os.close(sys.stdin.fileno())

en el método multiprocessing.Process._bootstrap() — Esto dio lugar a problemas con los procesos en proceso. Esto ha sido cambiado a:

sys.stdin.close()
sys.stdin = open(os.open(os.devnull, os.O_RDONLY), closefd=False)

Lo que resuelve el problema fundamental de los procesos que chocan entre sí dando como resultado un error de descriptor de archivo incorrecto, pero presenta un peligro potencial para las aplicaciones que reemplazan sys.stdin() con un «objeto similar a un archivo» con almacenamiento en búfer de salida. Este peligro es que si varios procesos invocan close() en este objeto similar a un archivo, podría ocasionar que los mismos datos se vacíen al objeto varias veces, lo que provocaría corrupción.

Si escribe un objeto similar a un archivo e implementa su propio almacenamiento en caché, puede hacer que sea seguro para la bifurcación (fork-safe) almacenando el pid cada vez que se agrega al caché y descartando el caché cuando cambia el pid. Por ejemplo:

@property
def cache(self):
    pid = os.getpid()
    if pid != self._pid:
        self._pid = pid
        self._cache = []
    return self._cache

Para más información, consulte bpo-5155 [https://bugs.python.org/issue?@action=redirect&bpo=5155], bpo-5313 [https://bugs.python.org/issue?@action=redirect&bpo=5313] y bpo-5331 [https://bugs.python.org/issue?@action=redirect&bpo=5331]

Los métodos de inicio spawn y forkserver

Hay algunas restricciones adicionales que no se aplican al método de inicio fork.

Más serialización (pickability)

Asegúrese de que todos los argumentos para Process.__init__() sean serializables (picklable). Además, si la subclase es Process asegúrese de que las instancias serán serializables cuando se llame al método Process.start.

Variables globales

Tenga en cuenta que si el código que se ejecuta en un proceso secundario intenta acceder a una variable global, entonces el valor que ve (si lo hay) puede no ser el mismo que el valor en el proceso primario en el momento en que fue llamado Process.start.

Sin embargo, las variables globales que son solo constantes de nivel de módulo no causan problemas.

Importando de manera segura el módulo principal

Asegúrese de que un nuevo intérprete de Python pueda importar de forma segura el módulo principal sin causar efectos secundarios no deseados (como comenzar un nuevo proceso).

Por ejemplo, usando el método de inicio spawn o forkserver ejecutando este módulo fallaría produciendo RuntimeError:

from multiprocessing import Process

def foo():
    print('hello')

p = Process(target=foo)
p.start()

En su lugar, se debe proteger el «punto de entrada» («entry point») del programa utilizando como sigue if __name__ == '__main__':

from multiprocessing import Process, freeze_support, set_start_method

def foo():
    print('hello')

if __name__ == '__main__':
    freeze_support()
    set_start_method('spawn')
    p = Process(target=foo)
    p.start()

(La línea freeze_support() puede omitirse si el programa se ejecuta normalmente en lugar de congelarse).

Esto permite que el intérprete de Python recién generado importe de forma segura el módulo y luego ejecute la función del módulo foo().

Se aplican restricciones similares si se crea un grupo o administrador en el módulo principal.

Ejemplos

Demostración de cómo crear y usar gerentes y proxies personalizados:

from multiprocessing import freeze_support
from multiprocessing.managers import BaseManager, BaseProxy
import operator

##

class Foo:
    def f(self):
        print('you called Foo.f()')
    def g(self):
        print('you called Foo.g()')
    def _h(self):
        print('you called Foo._h()')

# A simple generator function
def baz():
    for i in range(10):
        yield i*i

# Proxy type for generator objects
class GeneratorProxy(BaseProxy):
    _exposed_ = ['__next__']
    def __iter__(self):
        return self
    def __next__(self):
        return self._callmethod('__next__')

# Function to return the operator module
def get_operator_module():
    return operator

##

class MyManager(BaseManager):
    pass

# register the Foo class; make `f()` and `g()` accessible via proxy
MyManager.register('Foo1', Foo)

# register the Foo class; make `g()` and `_h()` accessible via proxy
MyManager.register('Foo2', Foo, exposed=('g', '_h'))

# register the generator function baz; use `GeneratorProxy` to make proxies
MyManager.register('baz', baz, proxytype=GeneratorProxy)

# register get_operator_module(); make public functions accessible via proxy
MyManager.register('operator', get_operator_module)

##

def test():
    manager = MyManager()
    manager.start()

    print('-' * 20)

    f1 = manager.Foo1()
    f1.f()
    f1.g()
    assert not hasattr(f1, '_h')
    assert sorted(f1._exposed_) == sorted(['f', 'g'])

    print('-' * 20)

    f2 = manager.Foo2()
    f2.g()
    f2._h()
    assert not hasattr(f2, 'f')
    assert sorted(f2._exposed_) == sorted(['g', '_h'])

    print('-' * 20)

    it = manager.baz()
    for i in it:
        print('<%d>' % i, end=' ')
    print()

    print('-' * 20)

    op = manager.operator()
    print('op.add(23, 45) =', op.add(23, 45))
    print('op.pow(2, 94) =', op.pow(2, 94))
    print('op._exposed_ =', op._exposed_)

##

if __name__ == '__main__':
    freeze_support()
    test()

Usando Pool:

import multiprocessing
import time
import random
import sys

#
# Functions used by test code
#

def calculate(func, args):
    result = func(*args)
    return '%s says that %s%s = %s' % (
        multiprocessing.current_process().name,
        func.__name__, args, result
        )

def calculatestar(args):
    return calculate(*args)

def mul(a, b):
    time.sleep(0.5 * random.random())
    return a * b

def plus(a, b):
    time.sleep(0.5 * random.random())
    return a + b

def f(x):
    return 1.0 / (x - 5.0)

def pow3(x):
    return x ** 3

def noop(x):
    pass

#
# Test code
#

def test():
    PROCESSES = 4
    print('Creating pool with %d processes\n' % PROCESSES)

    with multiprocessing.Pool(PROCESSES) as pool:
        #
        # Tests
        #

        TASKS = [(mul, (i, 7)) for i in range(10)] + \
                [(plus, (i, 8)) for i in range(10)]

        results = [pool.apply_async(calculate, t) for t in TASKS]
        imap_it = pool.imap(calculatestar, TASKS)
        imap_unordered_it = pool.imap_unordered(calculatestar, TASKS)

        print('Ordered results using pool.apply_async():')
        for r in results:
            print('\t', r.get())
        print()

        print('Ordered results using pool.imap():')
        for x in imap_it:
            print('\t', x)
        print()

        print('Unordered results using pool.imap_unordered():')
        for x in imap_unordered_it:
            print('\t', x)
        print()

        print('Ordered results using pool.map() --- will block till complete:')
        for x in pool.map(calculatestar, TASKS):
            print('\t', x)
        print()

        #
        # Test error handling
        #

        print('Testing error handling:')

        try:
            print(pool.apply(f, (5,)))
        except ZeroDivisionError:
            print('\tGot ZeroDivisionError as expected from pool.apply()')
        else:
            raise AssertionError('expected ZeroDivisionError')

        try:
            print(pool.map(f, list(range(10))))
        except ZeroDivisionError:
            print('\tGot ZeroDivisionError as expected from pool.map()')
        else:
            raise AssertionError('expected ZeroDivisionError')

        try:
            print(list(pool.imap(f, list(range(10)))))
        except ZeroDivisionError:
            print('\tGot ZeroDivisionError as expected from list(pool.imap())')
        else:
            raise AssertionError('expected ZeroDivisionError')

        it = pool.imap(f, list(range(10)))
        for i in range(10):
            try:
                x = next(it)
            except ZeroDivisionError:
                if i == 5:
                    pass
            except StopIteration:
                break
            else:
                if i == 5:
                    raise AssertionError('expected ZeroDivisionError')

        assert i == 9
        print('\tGot ZeroDivisionError as expected from IMapIterator.next()')
        print()

        #
        # Testing timeouts
        #

        print('Testing ApplyResult.get() with timeout:', end=' ')
        res = pool.apply_async(calculate, TASKS[0])
        while 1:
            sys.stdout.flush()
            try:
                sys.stdout.write('\n\t%s' % res.get(0.02))
                break
            except multiprocessing.TimeoutError:
                sys.stdout.write('.')
        print()
        print()

        print('Testing IMapIterator.next() with timeout:', end=' ')
        it = pool.imap(calculatestar, TASKS)
        while 1:
            sys.stdout.flush()
            try:
                sys.stdout.write('\n\t%s' % it.next(0.02))
            except StopIteration:
                break
            except multiprocessing.TimeoutError:
                sys.stdout.write('.')
        print()
        print()

if __name__ == '__main__':
    multiprocessing.freeze_support()
    test()

Un ejemplo que muestra cómo usar las colas para alimentar tareas a una colección de procesos de trabajo y recopilar los resultados:

import time
import random

from multiprocessing import Process, Queue, current_process, freeze_support

#
# Function run by worker processes
#

def worker(input, output):
    for func, args in iter(input.get, 'STOP'):
        result = calculate(func, args)
        output.put(result)

#
# Function used to calculate result
#

def calculate(func, args):
    result = func(*args)
    return '%s says that %s%s = %s' % \
        (current_process().name, func.__name__, args, result)

#
# Functions referenced by tasks
#

def mul(a, b):
    time.sleep(0.5*random.random())
    return a * b

def plus(a, b):
    time.sleep(0.5*random.random())
    return a + b

#
#
#

def test():
    NUMBER_OF_PROCESSES = 4
    TASKS1 = [(mul, (i, 7)) for i in range(20)]
    TASKS2 = [(plus, (i, 8)) for i in range(10)]

    # Create queues
    task_queue = Queue()
    done_queue = Queue()

    # Submit tasks
    for task in TASKS1:
        task_queue.put(task)

    # Start worker processes
    for i in range(NUMBER_OF_PROCESSES):
        Process(target=worker, args=(task_queue, done_queue)).start()

    # Get and print results
    print('Unordered results:')
    for i in range(len(TASKS1)):
        print('\t', done_queue.get())

    # Add more tasks using `put()`
    for task in TASKS2:
        task_queue.put(task)

    # Get and print some more results
    for i in range(len(TASKS2)):
        print('\t', done_queue.get())

    # Tell child processes to stop
    for i in range(NUMBER_OF_PROCESSES):
        task_queue.put('STOP')

if __name__ == '__main__':
    freeze_support()
    test()

multiprocessing.shared_memory — Proporciona memoria compartida para acceso directo a través de procesos

Código fuente: Lib/multiprocessing/shared_memory.py [https://github.com/python/cpython/tree/3.9/Lib/multiprocessing/shared_memory.py]

Nuevo en la versión 3.8.

Este módulo proporciona una clase, SharedMemory, para la asignación y administración de memoria compartida entre uno o más procesos en una máquina con varios núcleos o varios procesadores simétrico (SMP). Para facilitar la gestión del ciclo de vida de la memoria compartida, especialmente entre múltiples procesos, el módulo multiprocessing.managers también proporciona la clase SharedMemoryManager, una subclase de BaseManager.

En este módulo, la memoria compartida se refiere a bloques de memoria compartida de «Sistema estilo V» (aunque no necesariamente se implementa explícitamente como tal) y no se refiere a «memoria compartida distribuida». Este tipo de memoria compartida permite que múltiples procesos lean y escriban en un área común (o compartida) de memoria volátil. Normalmente, los procesos solo tienen acceso a su propio espacio de memoria; la memoria compartida permite compartir datos entre procesos, lo que evita que tengan que enviar estos datos por mensaje. Compartir datos directamente a través de la memoria puede proporcionar importantes beneficios de rendimiento en comparación con compartir datos a través de un disco o socket u otras comunicaciones que requieren la serialización/deserialización y copia de datos.

class multiprocessing.shared_memory.SharedMemory(name=None, create=False, size=0)

Crea un nuevo bloque de memoria compartida o guarda un bloque ya existente. Se debe dar un nombre único a cada bloque de memoria compartida; por lo tanto, un proceso puede crear un nuevo bloque de memoria compartida con un nombre particular y un proceso diferente se puede conectar a ese mismo bloque de memoria compartida usando ese mismo nombre.

Como un recurso para compartir datos entre procesos, los bloques de memoria compartida pueden sobrevivir al proceso original que los creó. Cuando un proceso ya no necesita acceso a un bloque de memoria compartida que otros procesos aún podrían necesitar, se debe llamar al método close(). Cuando un proceso ya no necesita un bloque de memoria compartida, se debe llamar al método unlink() para garantizar una limpieza adecuada.

name es el nombre único para la memoria compartida solicitada, especificada como una cadena de caracteres. Al crear un nuevo bloque de memoria compartida, si se proporciona None (valor por defecto) para el nombre, se generará un nombre nuevo.

create controla si se crea un nuevo bloque de memoria compartida (True) o si se adjunta un bloque de memoria compartida existente (False).

size especifica el número solicitado de bytes al crear un nuevo bloque de memoria compartida. Debido a que algunas plataformas eligen asignar fragmentos de memoria en función del tamaño de página de memoria de esa plataforma, el tamaño exacto del bloque de memoria compartida puede ser mayor o igual al tamaño solicitado. Cuando se conecta a un bloque de memoria compartida existente, se ignora el parámetro size.

close()

Cierra el acceso a la memoria compartida desde esta instancia. Para garantizar la limpieza adecuada de los recursos, todas las instancias deben llamar a close() una vez que la instancia ya no sea necesaria. Tenga en cuenta que llamar a close() no causa que el bloque de memoria compartida se destruya.

unlink()

Solicita que se destruya el bloque de memoria compartida subyacente. Para garantizar la limpieza adecuada de los recursos, se debe llamar a unlink() una vez (y solo una vez) en todos los procesos que necesitan el bloque de memoria compartida. Después de solicitar su destrucción, un bloque de memoria compartida puede o no destruirse de inmediato y este comportamiento puede diferir entre plataformas. Los intentos de acceder a los datos dentro del bloque de memoria compartida después de que se haya llamado a unlink() pueden provocar errores de acceso a la memoria. Nota: el último proceso para liberar el bloque de memoria compartida puede llamar a unlink() y close() en cualquier orden.

buf

Un memoryview del contenido del bloque de memoria compartida.

name

Acceso de solo lectura al nombre único del bloque de memoria compartida.

size

Acceso de solo lectura al tamaño en bytes del bloque de memoria compartida.

El siguiente ejemplo muestra el uso de bajo nivel de instancias de SharedMemory:

>>> from multiprocessing import shared_memory
>>> shm_a = shared_memory.SharedMemory(create=True, size=10)
>>> type(shm_a.buf)
<class 'memoryview'>
>>> buffer = shm_a.buf
>>> len(buffer)
10
>>> buffer[:4] = bytearray([22, 33, 44, 55])  # Modify multiple at once
>>> buffer[4] = 100                           # Modify single byte at a time
>>> # Attach to an existing shared memory block
>>> shm_b = shared_memory.SharedMemory(shm_a.name)
>>> import array
>>> array.array('b', shm_b.buf[:5])  # Copy the data into a new array.array
array('b', [22, 33, 44, 55, 100])
>>> shm_b.buf[:5] = b'howdy'  # Modify via shm_b using bytes
>>> bytes(shm_a.buf[:5])      # Access via shm_a
b'howdy'
>>> shm_b.close()   # Close each SharedMemory instance
>>> shm_a.close()
>>> shm_a.unlink()  # Call unlink only once to release the shared memory

El siguiente ejemplo muestra un uso práctico de la clase SharedMemory con NumPy arrays [https://www.numpy.org/], accediendo al mismo numpy.ndarray desde dos shells de Python distintos:

>>> # In the first Python interactive shell
>>> import numpy as np
>>> a = np.array([1, 1, 2, 3, 5, 8])  # Start with an existing NumPy array
>>> from multiprocessing import shared_memory
>>> shm = shared_memory.SharedMemory(create=True, size=a.nbytes)
>>> # Now create a NumPy array backed by shared memory
>>> b = np.ndarray(a.shape, dtype=a.dtype, buffer=shm.buf)
>>> b[:] = a[:]  # Copy the original data into shared memory
>>> b
array([1, 1, 2, 3, 5, 8])
>>> type(b)
<class 'numpy.ndarray'>
>>> type(a)
<class 'numpy.ndarray'>
>>> shm.name  # We did not specify a name so one was chosen for us
'psm_21467_46075'

>>> # In either the same shell or a new Python shell on the same machine
>>> import numpy as np
>>> from multiprocessing import shared_memory
>>> # Attach to the existing shared memory block
>>> existing_shm = shared_memory.SharedMemory(name='psm_21467_46075')
>>> # Note that a.shape is (6,) and a.dtype is np.int64 in this example
>>> c = np.ndarray((6,), dtype=np.int64, buffer=existing_shm.buf)
>>> c
array([1, 1, 2, 3, 5, 8])
>>> c[-1] = 888
>>> c
array([  1,   1,   2,   3,   5, 888])

>>> # Back in the first Python interactive shell, b reflects this change
>>> b
array([  1,   1,   2,   3,   5, 888])

>>> # Clean up from within the second Python shell
>>> del c  # Unnecessary; merely emphasizing the array is no longer used
>>> existing_shm.close()

>>> # Clean up from within the first Python shell
>>> del b  # Unnecessary; merely emphasizing the array is no longer used
>>> shm.close()
>>> shm.unlink()  # Free and release the shared memory block at the very end

class multiprocessing.managers.SharedMemoryManager([address[, authkey]])

Una subclase de BaseManager que se puede utilizar para la gestión de bloques de memoria compartida en todos los procesos.

Una llamada al método start() en una instancia de SharedMemoryManager hace que se inicie un nuevo proceso. El único propósito de este nuevo proceso es administrar el ciclo de vida de todos los bloques de memoria compartida creados a través de él. Para activar la liberación de todos los bloques de memoria compartida administrados por ese proceso, llama al método shutdown() en la instancia. Esto desencadena una llamada al método SharedMemory.unlink() en todos los objetos de la clase SharedMemory administrados por ese proceso y luego detiene el proceso en sí. Al crear instancias de SharedMemory a través de un SharedMemoryManager, evitamos la necesidad de rastrear manualmente y activar la liberación de recursos de memoria compartida.

Esta clase proporciona métodos para crear y retornar instancias SharedMemory y para crear un objeto de tipo lista (ShareableList) basados en memoria compartida.

Consulte multiprocessing.managers.BaseManager para obtener una descripción de los argumentos heredados opcionales address y authkey y cómo se deben usar para registrar un servicio SharedMemoryManager desde otro proceso.

SharedMemory(size)

Crea y retorna un nuevo objeto SharedMemory con el tamaño size especificado en bytes.

ShareableList(sequence)

Crea y retorna un nuevo objeto ShareableList, inicializado por los valores de la entrada sequence.

El siguiente ejemplo muestra los mecanismos básicos de SharedMemoryManager:

>>> from multiprocessing.managers import SharedMemoryManager
>>> smm = SharedMemoryManager()
>>> smm.start()  # Start the process that manages the shared memory blocks
>>> sl = smm.ShareableList(range(4))
>>> sl
ShareableList([0, 1, 2, 3], name='psm_6572_7512')
>>> raw_shm = smm.SharedMemory(size=128)
>>> another_sl = smm.ShareableList('alpha')
>>> another_sl
ShareableList(['a', 'l', 'p', 'h', 'a'], name='psm_6572_12221')
>>> smm.shutdown()  # Calls unlink() on sl, raw_shm, and another_sl

El siguiente ejemplo muestra un patrón más conveniente para usar un objeto SharedMemoryManager con la sentencia with para asegurarse de que todos los bloques de memoria se liberen cuando ya no son necesarios. Esto suele ser más práctico que el ejemplo anterior:

>>> with SharedMemoryManager() as smm:
...     sl = smm.ShareableList(range(2000))
...     # Divide the work among two processes, storing partial results in sl
...     p1 = Process(target=do_work, args=(sl, 0, 1000))
...     p2 = Process(target=do_work, args=(sl, 1000, 2000))
...     p1.start()
...     p2.start()  # A multiprocessing.Pool might be more efficient
...     p1.join()
...     p2.join()   # Wait for all work to complete in both processes
...     total_result = sum(sl)  # Consolidate the partial results now in sl

Cuando se utiliza un SharedMemoryManager en una sentencia with, los bloques de memoria compartida creados por ese administrador se liberan cuando la sentencias dentro del bloque de código with finaliza la ejecución.

class multiprocessing.shared_memory.ShareableList(sequence=None, *, name=None)

Construye un objeto mutable compatible con el tipo de lista cuyos valores se almacenan en un bloque de memoria compartida. Esto reduce los valores de tipo que se pueden almacenar solo a tipos de datos nativos int, float, bool, str (menos de 10 MB cada uno), bytes (menos de 10 MB cada uno) y None. Otra diferencia importante con una lista nativa es que es imposible cambiar el tamaño (es decir, sin adición al final de la lista, sin inserción, etc.) y que no es posible crear nuevas instancias de ShareableList mediante la división.

sequence se utiliza para completar una nueva ShareableList con valores. Establezca en None para registrar en su lugar una ShareableList ya existente por su nombre único de memoria compartida.

name es el nombre único para la memoria compartida solicitada, como se describe en la definición de SharedMemory. Al adjuntar a una ShareableList existente, especifique el nombre único de su bloque de memoria compartida mientras deja sequence establecida en None.

count(value)

Retorna el número de ocurrencias de value.

index(value)

Retorna la primera posición del índice de value. Lanza ValueError si value no está presente.

format

Atributo de solo lectura que contiene el formato de empaquetado struct utilizado por todos los valores almacenados actualmente.

shm

La instancia de SharedMemory donde se almacenan los valores.

El siguiente ejemplo muestra el uso básico de una instancia ShareableList:

>>> from multiprocessing import shared_memory
>>> a = shared_memory.ShareableList(['howdy', b'HoWdY', -273.154, 100, None, True, 42])
>>> [ type(entry) for entry in a ]
[<class 'str'>, <class 'bytes'>, <class 'float'>, <class 'int'>, <class 'NoneType'>, <class 'bool'>, <class 'int'>]
>>> a[2]
-273.154
>>> a[2] = -78.5
>>> a[2]
-78.5
>>> a[2] = 'dry ice'  # Changing data types is supported as well
>>> a[2]
'dry ice'
>>> a[2] = 'larger than previously allocated storage space'
Traceback (most recent call last):
  ...
ValueError: exceeds available storage for existing str
>>> a[2]
'dry ice'
>>> len(a)
7
>>> a.index(42)
6
>>> a.count(b'howdy')
0
>>> a.count(b'HoWdY')
1
>>> a.shm.close()
>>> a.shm.unlink()
>>> del a  # Use of a ShareableList after call to unlink() is unsupported

El siguiente ejemplo muestra cómo uno, dos o muchos procesos pueden acceder al mismo ShareableList al proporcionar el nombre del bloque de memoria compartida detrás de él:

>>> b = shared_memory.ShareableList(range(5))         # In a first process
>>> c = shared_memory.ShareableList(name=b.shm.name)  # In a second process
>>> c
ShareableList([0, 1, 2, 3, 4], name='...')
>>> c[-1] = -999
>>> b[-1]
-999
>>> b.shm.close()
>>> c.shm.close()
>>> c.shm.unlink()

El paquete concurrent

Actualmente solo existe un módulo en este paquete:

concurrent.futures – Lanzamiento de tareas paralelas

concurrent.futures — Lanzamiento de tareas paralelas

Nuevo en la versión 3.2.

Código fuente: Lib/concurrent/futures/thread.py [https://github.com/python/cpython/tree/3.9/Lib/concurrent/futures/thread.py] y Lib/concurrent/futures/process.py [https://github.com/python/cpython/tree/3.9/Lib/concurrent/futures/process.py]

El módulo concurrent.futures provee una interfaz de alto nivel para ejecutar invocables de forma asincrónica.

La ejecución asincrónica se puede realizar mediante hilos, usando ThreadPoolExecutor, o procesos independientes, mediante ProcessPoolExecutor. Ambos implementan la misma interfaz, que se encuentra definida por la clase abstracta Executor.

Objetos Ejecutores

class concurrent.futures.Executor

Una clase abstracta que proporciona métodos para ejecutar llamadas de forma asincrónica. No debe ser utilizada directamente, sino a través de sus subclases.

submit(fn, /, *args, **kwargs)

Schedules the callable, fn, to be executed as fn(*args, **kwargs) and returns a Future object representing the execution of the callable.

with ThreadPoolExecutor(max_workers=1) as executor:
    future = executor.submit(pow, 323, 1235)
    print(future.result())

map(func, *iterables, timeout=None, chunksize=1)

Similar a map(func, *iterables) excepto que:

los iterables son recolectados inmediatamente, en lugar de perezosamente;

func se ejecuta de forma asincrónica y se pueden realizar varias llamadas a func simultáneamente.

El iterador retornado lanza concurrent.futures.TimeoutError si __next__() es llamado y el resultado no está disponible luego de timeout segundos luego de la llamada original a Executor.map(). timeout puede ser un int o un float. Si no se provee un timeout o es None, no hay limite de espera.

Si una llamada a func lanza una excepción, dicha excepción va a ser lanzada cuando su valor sea retornado por el iterador.

Al usar ProcessPoolExecutor, este método divide los iterables en varios fragmentos que luego envía al grupo como tareas separadas. El tamaño (aproximado) de estos fragmentos puede especificarse estableciendo chunksize a un entero positivo. El uso de un valor grande para chunksize puede mejorar significativamente el rendimiento en comparación con el tamaño predeterminado de 1. Con ThreadPoolExecutor, el chunksize no tiene ningún efecto.

Distinto en la versión 3.5: Se agregó el argumento chunksize.

shutdown(wait=True, *, cancel_futures=False)

Indica al ejecutor que debe liberar todos los recursos que está utilizando cuando los futuros actualmente pendientes de ejecución finalicen. Las llamadas a Executor.submit() y Executor.map() realizadas después del apagado lanzarán RuntimeError.

Si wait es True este método no retornará hasta que todos los futuros pendientes hayan terminado su ejecución y los recursos asociados al ejecutor hayan sido liberados. Si wait es False, este método retornará de inmediato y los recursos asociados al ejecutor se liberarán cuando todos los futuros asociados hayan finalizado su ejecución. Independientemente del valor de wait, el programa Python entero no finalizará hasta que todos los futuros pendientes hayan finalizado su ejecución.

Si cancel_futures es True, este método cancelará todos los futuros pendientes que el ejecutor no ha comenzado a ejecutar. Los futuros que se completen o estén en ejecución no se cancelarán, independientemente del valor de cancel_futures.

Si tanto cancel_futures como wait son True, todos los futuros que el ejecutor ha comenzado a ejecutar se completarán antes de que regrese este método. Los futuros restantes se cancelan.

Se puede evitar tener que llamar este método explícitamente si se usa la sentencia with, la cual apagará el Executor (esperando como si Executor.shutdown() hubiera sido llamado con wait en True):

import shutil
with ThreadPoolExecutor(max_workers=4) as e:
    e.submit(shutil.copy, 'src1.txt', 'dest1.txt')
    e.submit(shutil.copy, 'src2.txt', 'dest2.txt')
    e.submit(shutil.copy, 'src3.txt', 'dest3.txt')
    e.submit(shutil.copy, 'src4.txt', 'dest4.txt')

Distinto en la versión 3.9: Agregado cancel_futures.

ThreadPoolExecutor

ThreadPoolExecutor es una subclase de Executor que usa un grupo de hilos para ejecutar llamadas de forma asincrónica.

Pueden ocurrir bloqueos mutuos cuando la llamada asociada a un Future espera el resultado de otro Future. Por ejemplo:

import time
def wait_on_b():
    time.sleep(5)
    print(b.result())  # b will never complete because it is waiting on a.
    return 5

def wait_on_a():
    time.sleep(5)
    print(a.result())  # a will never complete because it is waiting on b.
    return 6

executor = ThreadPoolExecutor(max_workers=2)
a = executor.submit(wait_on_b)
b = executor.submit(wait_on_a)

Y:

def wait_on_future():
    f = executor.submit(pow, 5, 2)
    # This will never complete because there is only one worker thread and
    # it is executing this function.
    print(f.result())

executor = ThreadPoolExecutor(max_workers=1)
executor.submit(wait_on_future)

class concurrent.futures.ThreadPoolExecutor(max_workers=None, thread_name_prefix='', initializer=None, initargs=())

Subclase de Executor que utiliza un grupo de hilos de max_workers como máximo para ejecutar llamadas de forma asincrónica.

initializer es un invocable opcional que es llamado al comienzo de cada hilo de trabajo; initargs es una tupla de argumentos pasados al inicializador. Si el initializer lanza una excepción, todos los trabajos actualmente pendientes lanzarán BrokenThreadPool, así como cualquier intento de enviar más trabajos al grupo.

Distinto en la versión 3.5: Si max_workers es None o no es especificado, se tomará por defecto el número de procesadores de la máquina, multiplicado por 5, asumiendo que ThreadPoolExecutor a menudo se utiliza para paralelizar E/S en lugar de trabajo de CPU y que el numero de trabajadores debe ser mayor que el número de trabajadores para ProcessPoolExecutor.

Nuevo en la versión 3.6: El argumento thread_name_prefix fue añadido para permitir al usuario controlar los nombres asignados a los threading.Thread creados por el grupo para facilitar la depuración del programa.

Distinto en la versión 3.7: Se agregaron los argumentos initializer y initargs.

Distinto en la versión 3.8: El valor predeterminado de max_workers fue reemplazado por min(32, os.cpu_count() + 4). Este valor predeterminado conserva al menos 5 trabajadores para las tareas vinculadas de E/S. Utiliza como máximo 32 núcleos de CPU para tareas vinculadas a la CPU que liberan el GIL. Y evita utilizar recursos muy grandes implícitamente en máquinas de muchos núcleos.

ThreadPoolExecutor ahora también reutiliza hilos inactivos antes de crear max_workers hilos de trabajo.

Ejemplo de ThreadPoolExecutor

import concurrent.futures
import urllib.request

URLS = ['http://www.foxnews.com/',
        'http://www.cnn.com/',
        'http://europe.wsj.com/',
        'http://www.bbc.co.uk/',
        'http://nonexistant-subdomain.python.org/']

# Retrieve a single page and report the URL and contents
def load_url(url, timeout):
    with urllib.request.urlopen(url, timeout=timeout) as conn:
        return conn.read()

# We can use a with statement to ensure threads are cleaned up promptly
with concurrent.futures.ThreadPoolExecutor(max_workers=5) as executor:
    # Start the load operations and mark each future with its URL
    future_to_url = {executor.submit(load_url, url, 60): url for url in URLS}
    for future in concurrent.futures.as_completed(future_to_url):
        url = future_to_url[future]
        try:
            data = future.result()
        except Exception as exc:
            print('%r generated an exception: %s' % (url, exc))
        else:
            print('%r page is %d bytes' % (url, len(data)))

ProcessPoolExecutor

La clase ProcessPoolExecutor es una subclase Executor que usa un grupo de procesos para ejecutar llamadas de forma asíncrona. ProcessPoolExecutor usa el módulo multiprocessing, que le permite eludir el Global Interpreter Lock pero también significa que solo los objetos seleccionables pueden ser ejecutados y retornados.

El módulo __main__ debe ser importable por los subprocesos trabajadores. Esto significa que ProcessPoolExecutor no funcionará en el intérprete interactivo.

Llamar a métodos de Executor o Future desde el invocable enviado a ProcessPoolExecutor resultará en bloqueos mutuos.

class concurrent.futures.ProcessPoolExecutor(max_workers=None, mp_context=None, initializer=None, initargs=())

Subclase de Executor que ejecuta llamadas asincrónicas mediante un grupo de, como máximo, max_workers procesos. Si max_workers es None o no fue especificado, el número predeterminado será la cantidad de procesadores de la máquina, Si max_workers es menor o igual a 0, la excepción ValueError será lanzada. En Windows, max_workers debe ser menor o igual a 61. Si no es así, la excepción ValueError será lanzada. Si max_workers es None, el número predeterminado será 61 como máximo, aún si existen más procesadores disponibles. mp_context puede ser un contexto de multiprocesamiento o None y será utilizado para iniciar los trabajadores. Si mp_context es None o no es especificado, se utilizará el contexto predeterminado de multiprocesamiento.

initializer es un invocable opcional que es llamado al comienzo de cada proceso trabajador; initargs es una tupla de argumentos pasados al inicializador. Si el initializer lanza una excepción, todos los trabajos actualmente pendientes lanzarán BrokenProcessPool, así como cualquier intento de enviar más trabajos al grupo.

Distinto en la versión 3.3: Cuando uno de los procesos finaliza abruptamente, se lanzará BrokenProcessPool. Anteriormente, el comportamiento no estaba definido, pero las operaciones en el ejecutor o sus futuros a menudo se detenían o bloqueaban mutuamente.

Distinto en la versión 3.7: El argumento mp_context se agregó para permitir a los usuarios controlar el método de iniciación para procesos de trabajo creados en el grupo.

Se agregaron los argumentos initializer y initargs.

Ejemplo de ProcessPoolExecutor

import concurrent.futures
import math

PRIMES = [
    112272535095293,
    112582705942171,
    112272535095293,
    115280095190773,
    115797848077099,
    1099726899285419]

def is_prime(n):
    if n < 2:
        return False
    if n == 2:
        return True
    if n % 2 == 0:
        return False

    sqrt_n = int(math.floor(math.sqrt(n)))
    for i in range(3, sqrt_n + 1, 2):
        if n % i == 0:
            return False
    return True

def main():
    with concurrent.futures.ProcessPoolExecutor() as executor:
        for number, prime in zip(PRIMES, executor.map(is_prime, PRIMES)):
            print('%d is prime: %s' % (number, prime))

if __name__ == '__main__':
    main()

Objetos Futuro

La clase Future encapsula la ejecución asincrónica del invocable. Las instancias de Future son creadas por Executor.submit().

class concurrent.futures.Future

Encapsula la ejecución asincrónica del invocable. Las instancias de Future son creadas por Executor.submit() y no deberían ser creadas directamente, excepto para pruebas.

cancel()

Intenta cancelar la llamada. Si el invocable está siendo ejecutado o ha finalizado su ejecución y no puede ser cancelado el método retornará False, de lo contrario la llamada será cancelada y el método retornará True.

cancelled()

Retorna True si la llamada fue cancelada exitosamente.

running()

Retorna True si la llamada está siendo ejecutada y no puede ser cancelada.

done()

Retorna True si la llamada fue cancelada exitosamente o terminó su ejecución.

result(timeout=None)

Retorna el valor retornado por la llamada. Si la llamada aún no ha finalizado, el método esperará un total de timeout segundos. Si la llamada no ha finalizado luego de timeout segundos, concurrent.futures.TimeoutError será lanzada. timeout puede ser un int o un float. Si timeout es None o no fue especificado, no hay limite de espera.

Si el futuro es cancelado antes de finalizar su ejecución, CancelledError será lanzada.

If the call raised an exception, this method will raise the same exception.

exception(timeout=None)

Retorna la excepción lanzada por la llamada. Si la llamada aún no ha finalizado, el método esperará un máximo de timeout segundos. Si la llamada aún no ha finalizado luego de timeout segundos, entonces concurrent.futures.TimeoutError será lanzada. timeout puede ser un int o un float. Si timeout es None o no es especificado, no hay limite en el tiempo de espera.

Si el futuro es cancelado antes de finalizar su ejecución, CancelledError será lanzada.

Si la llamada es completada sin excepciones, se retornará `None.

add_done_callback(fn)

Asocia el invocable fn al futuro. fn va a ser llamada, con el futuro como su único argumento, cuando el futuro sea cancelado o finalice su ejecución.

Los invocables agregados se llaman en el orden en que se agregaron y siempre se llaman en un hilo que pertenece al proceso que los agregó. Si el invocable genera una subclase Exception, se registrará y se ignorará. Si el invocable genera una subclase BaseException, el comportamiento no está definido.

Si el futuro ya ha finalizado su ejecución o fue cancelado, fn retornará inmediatamente.

Los siguientes métodos de Future están pensados para ser usados en pruebas unitarias e implementaciones de Executor.

set_running_or_notify_cancel()

Este método sólo debe ser llamado en implementaciones de Executor antes de ejecutar el trabajo asociado al Future y por las pruebas unitarias.

Si el método retorna False entonces Future fue cancelado. i.e. Future.cancel() fue llamado y retornó True. Todos los hilos esperando la finalización del Future (i.e. a través de as_completed() o wait()) serán despertados.

Si el método retorna True, entonces el Future no fue cancelado y ha sido colocado en estado de ejecución, i.e. las llamadas a Future.running() retornarán True.

Este método solo puede ser llamado una sola vez y no puede ser llamado luego de haber llamado a Future.set_result() o a Future.set_exception().

set_result(result)

Establece result como el resultado del trabajo asociado al Future.

Este método solo debe ser usado por implementaciones de Executor y pruebas unitarias.

Distinto en la versión 3.8: Este método lanza concurrent.futures.InvalidStateError si Future ya ha finalizado su ejecución.

set_exception(exception)

Establece exception, subclase de Exception, como el resultado del trabajo asociado al Future.

Este método solo debe ser usado por implementaciones de Executor y pruebas unitarias.

Distinto en la versión 3.8: Este método lanza concurrent.futures.InvalidStateError si Future ya ha finalizado su ejecución.

Funciones del Módulo

concurrent.futures.wait(fs, timeout=None, return_when=ALL_COMPLETED)

Wait for the Future instances (possibly created by different Executor instances) given by fs to complete. Duplicate futures given to fs are removed and will be returned only once. Returns a named 2-tuple of sets. The first set, named done, contains the futures that completed (finished or cancelled futures) before the wait completed. The second set, named not_done, contains the futures that did not complete (pending or running futures).

El argumento timeout puede ser usado para controlar la espera máxima en segundos antes de retornar. timeout puede ser un int o un float. Si timeout no es especificado o es None, no hay limite en el tiempo de espera.

return_when indica cuando debe retornar esta función. Debe ser alguna de las siguientes constantes:

Constante

Descripción

FIRST_COMPLETED

La función retornará cuando cualquier futuro finalice o sea cancelado.

FIRST_EXCEPTION

La función retornará cuando cualquier futuro finalice lanzando una excepción. Si ningún futuro lanza una excepción, esta opción es equivalente a ALL_COMPLETED.

ALL_COMPLETED

La función retornará cuando todos los futuros finalicen o sean cancelados.

concurrent.futures.as_completed(fs, timeout=None)

Retorna un iterador sobre las instancias de Future (posiblemente creadas por distintas instancias de Executor) dadas por fs que produce futuros a medida que van finalizando (normalmente o cancelados). Cualquier futuro dado por fs que esté duplicado será retornado una sola vez. Los futuros que hayan finalizado antes de la llamada a as_completed() serán entregados primero. El iterador retornado lanzará concurrent.futures.TimeoutError si __next__() es llamado y el resultado no está disponible luego de timeout segundos a partir de la llamada original a as_completed(). timeout puede ser un int o un float. Si timeout no es especificado o es None, no hay limite en el tiempo de espera.

Ver también

PEP 3148 [https://www.python.org/dev/peps/pep-3148] – futuros - ejecutar cómputos asincrónicamente

La propuesta que describe esta propuesta de inclusión en la biblioteca estándar de Python.

Clases de Excepciones

exception concurrent.futures.CancelledError

Lanzada cuando un futuro es cancelado.

exception concurrent.futures.TimeoutError

Lanzada cuando un futuro excede el tiempo de espera máximo.

exception concurrent.futures.BrokenExecutor

Derivada de RuntimeError, esta excepción es lanzada cuando un ejecutor se encuentra corrupto por algún motivo y no puede ser utilizado para enviar o ejecutar nuevas tareas.

Nuevo en la versión 3.7.

exception concurrent.futures.InvalidStateError

Lanzada cuando una operación es realizada sobre un futuro que no permite dicha operación en el estado actual.

Nuevo en la versión 3.8.

exception concurrent.futures.thread.BrokenThreadPool

Derivada de BrokenExecutor, esta excepción es lanzada cuando uno de los trabajadores de ThreadPoolExecutor ha fallado en su inicialización.

Nuevo en la versión 3.7.

exception concurrent.futures.process.BrokenProcessPool

Derivada de BrokenExecutor (previamente RuntimeError), esta excepción es lanzada cuando uno de los trabajadores de ProcessPoolExecutor ha finalizado de forma abrupta (por ejemplo, al ser terminado desde afuera del proceso).

Nuevo en la versión 3.3.

subprocess — Gestión de subprocesos

Código fuente: Lib/subprocess.py [https://github.com/python/cpython/tree/3.9/Lib/subprocess.py]

El módulo subprocess permite lanzar nuevos procesos, conectarse a sus pipes de entrada/salida/error y obtener sus códigos de resultado. Este módulo está destinado a reemplazar múltiples módulos y funciones previamente existentes:

os.system
os.spawn*

Se puede obtener información sobre cómo utilizar el módulo subprocess para reemplazar estos módulos y funciones en las siguientes secciones.

Ver también

PEP 324 [https://www.python.org/dev/peps/pep-0324] – PEP de proposición del módulo subprocess

Uso del módulo subprocess

La opción recomendada para invocar subprocesos es utilizar la función run() para todos los casos al alcance de ésta. Para usos más avanzados, se puede utilizar la interfaz de más bajo nivel Popen.

La función run() se añadió en Python 3.5; si necesita mantener la compatibilidad con versiones anteriores, consulte la sección Antigua API de alto nivel.

subprocess.run(args, *, stdin=None, input=None, stdout=None, stderr=None, capture_output=False, shell=False, cwd=None, timeout=None, check=False, encoding=None, errors=None, text=None, env=None, universal_newlines=None, **other_popen_kwargs)

Ejecuta la orden descrita por args. Espera a que termine y retorna una instancia de CompletedProcess.

Los argumentos mostrados en la definición superior son sólo los más comunes; que se describen posteriormente en Argumentos frecuentemente empleados (de ahí el uso de la notación por clave en la signatura abreviada). La signatura completa de la función es a grandes rasgos la misma que la del constructor de Popen; la mayoría de los argumentos de esta función se pasan a esa interfaz (no es el caso de timeout, input, check ni capture_output).

Si capture_output es verdadero, se capturarán stdout y stderr. En tal caso, el objeto Popen interno se crea automáticamente con stdout=PIPE y stderr=PIPE. No se pueden proporcionar los argumentos stdout y stderr a la vez que capture_output. Si se desea capturar y combinar los dos flujos, se ha de usar stdout=PIPE y stderr=STDOUT en lugar de capture_output.

El argumento timeout se pasa a Popen.communicate(). Si vence el plazo de ejecución, se matará el proceso hijo y se le esperará. Se relanzará la excepción TimeoutExpired cuando finalice el proceso hijo.

Se pasará el argumento input a Popen.communicate() y de ahí, a la entrada estándar del subproceso. Si se usa, debe ser una secuencia de bytes o una cadena de texto si se especifican encoding o errors o text en verdadero. Cuando se usa, el objeto Popen interno se crea automáticamente con stdin=PIPE y no se puede usar el argumento stdin a la vez.

Si check es verdadero y el proceso retorna un resultado distinto de cero, se lanzará una excepción CalledProcessError. Los atributos de dicha excepción contendrán los argumentos, el código retornado y tanto stdout como stderr si se capturaron.

Si se especifican encoding o errors o text es verdadero, se abrirán los objetos fichero para stdin, stdout y stderr en modo texto, con los encoding y errors especificados o los valores predeterminados de io.TextIOWrapper. El argumento universal_newlines equivale a text y se admite por compatibilidad hacia atrás. Los objetos fichero se abren en modo binario por defecto.

Si env no es None, debe ser un mapeo que defina las variables de entorno para el nuevo proceso; se utilizarán éstas en lugar del comportamiento predeterminado de heredar el entorno del proceso actual. Se le pasa directamente a Popen.

Ejemplos:

>>> subprocess.run(["ls", "-l"])  # doesn't capture output
CompletedProcess(args=['ls', '-l'], returncode=0)

>>> subprocess.run("exit 1", shell=True, check=True)
Traceback (most recent call last):
  ...
subprocess.CalledProcessError: Command 'exit 1' returned non-zero exit status 1

>>> subprocess.run(["ls", "-l", "/dev/null"], capture_output=True)
CompletedProcess(args=['ls', '-l', '/dev/null'], returncode=0,
stdout=b'crw-rw-rw- 1 root root 1, 3 Jan 23 16:23 /dev/null\n', stderr=b'')

Nuevo en la versión 3.5.

Distinto en la versión 3.6: Se añadieron los parámetros encoding y errors

Distinto en la versión 3.7: Se añadió el parámetro text como alias más comprensible de universal_newlines. Se añadió el parámetro capture_output.

Distinto en la versión 3.9.17: Changed Windows shell search order for shell=True. The current directory and %PATH% are replaced with %COMSPEC% and %SystemRoot%\System32\cmd.exe. As a result, dropping a malicious program named cmd.exe into a current directory no longer works.

class subprocess.CompletedProcess

El valor retornado por run(), que representa un proceso ya terminado.

args

Los argumentos utilizados para lanzar el proceso. Pueden ser una lista o una cadena.

returncode

Estado de salida del proceso hijo. Típicamente, un estado de salida 0 indica que la ejecución tuvo éxito.

Un valor negativo -N indica que el hijo fue forzado a terminar con la señal N (solamente POSIX).

stdout

La salida estándar capturada del proceso hijo. Una secuencia de bytes, o una cadena si se llamó a run() con encoding, errors, o text establecidos a True. None si no se capturó el error estándar.

Si se ejecutó el proceso con stderr=subprocess.STDOUT, stdout y stderr se combinarán en este atributo, y stderr será None.

stderr

El error estándar capturado del proceso hijo. Una secuencia de bytes, o una cadena si se llamó a run() con encoding, errors, o text establecidos a True. None si no se capturó el error estándar.

check_returncode()

Si returncode no es cero, lanza un CalledProcessError.

Nuevo en la versión 3.5.

subprocess.DEVNULL

Valor especial que se puede usar como argumento stdin, stdout o stderr de Popen y que indica que se usará el fichero especial os.devnull.

Nuevo en la versión 3.3.

subprocess.PIPE

Valor especial que se puede usar como argumento stdin, stdout o stderr de Popen y que indica que se abrirá un pipe al flujo indicado. Es útil para usarlo con Popen.communicate().

subprocess.STDOUT

Valor especial que se puede usar de argumento stderr a Popen y que indica que el error estándar debería ir al mismo gestor que la salida estándar.

exception subprocess.SubprocessError

Clase base para el resto de excepciones de este módulo.

Nuevo en la versión 3.3.

exception subprocess.TimeoutExpired

Subclase de SubprocessError, se lanza cuando expira un plazo de ejecución esperando a un proceso hijo.

cmd

Orden que se utilizó para lanzar el proceso hijo.

timeout

Plazo de ejecución en segundos.

output

Output of the child process if it was captured by run() or check_output(). Otherwise, None. This is always bytes when any output was captured regardless of the text=True setting. It may remain None instead of b'' when no output was observed.

stdout

Alias de output, por simetría con stderr.

stderr

Stderr output of the child process if it was captured by run(). Otherwise, None. This is always bytes when stderr output was captured regardless of the text=True setting. It may remain None instead of b'' when no stderr output was observed.

Nuevo en la versión 3.3.

Distinto en la versión 3.5: Se añadieron los atributos stdout y stderr

exception subprocess.CalledProcessError

Subclass of SubprocessError, raised when a process run by check_call(), check_output(), or run() (with check=True) returns a non-zero exit status.

returncode

Estado de salida del proceso hijo. Si el proceso terminó por causa de una señal, el estado será el número de la señal en negativo.

cmd

Orden que se utilizó para lanzar el proceso hijo.

output

Salida del proceso hijo si fue capturada por run() o check_output(). De otro modo, None.

stdout

Alias de output, por simetría con stderr.

stderr

Salida de stderr del proceso hijo si fue capturada por run(). De otro modo, None.

Distinto en la versión 3.5: Se añadieron los atributos stdout y stderr

Argumentos frecuentemente empleados

Para permitir una gran variedad de usos, el constructor de Popen (y las funciones asociadas) aceptan un gran número de argumentos opcionales. Para los usos más habituales, se pueden dejar de forma segura los valores por defecto. Los argumentos más frecuentemente necesarios son:

args se requiere en todas las llamadas; debe ser una cadena o una secuencia de argumentos al programa. En general, es mejor proporcionar una secuencia de argumentos porque permite que el módulo se ocupe de las secuencias de escape y los entrecomillados de los argumentos (por ejemplo, para permitir espacios en los nombres de fichero). Si se pasa una cadena simple, se ha de especificar shell como True (ver más adelante) o la cadena debe ser el nombre del programa a ejecutar sin especificar ningún argumento.

stdin, stdout and stderr specify the executed program’s standard input, standard output and standard error file handles, respectively. Valid values are PIPE, DEVNULL, an existing file descriptor (a positive integer), an existing file object with a valid file descriptor, and None. PIPE indicates that a new pipe to the child should be created. DEVNULL indicates that the special file os.devnull will be used. With the default settings of None, no redirection will occur; the child’s file handles will be inherited from the parent. Additionally, stderr can be STDOUT, which indicates that the stderr data from the child process should be captured into the same file handle as for stdout.

Si se especifican encoding o errors, o text (o su alias universal_newlines) es verdadero, se abrirán en modo texto los objetos fichero stdin, stdout y stderr usando los encoding y errors especificados en la llamada o los valores predeterminados de io.TextIOWrapper.

Para stdin, los saltos del línea '\n' de la entrada serán convertidos al separador de línea predeterminado os.linesep. Para stdout y stderr, todos los saltos de línea de la salida serán convertidos a '\n'. Hay más información en la documentación de la clase io.TextIOWrapper para el caso en que el argumento newline de su constructor es None.

Si no se usa el modo texto, stdin, stdout y stderr se abrirán como flujos binarios. No se realizará ninguna codificación ni conversión de salto de línea.

Nuevo en la versión 3.6: Se añadieron los parámetros encoding y errors.

Nuevo en la versión 3.7: Se añadió el parámetro text como alias de universal_newlines.

Nota

El atributo newlines de los objetos fichero Popen.stdin, Popen.stdout y Popen.stderr no es actualizado por el método Popen.communicate().

Si shell es True, la orden especificada se ejecutará pasando por la shell. Esto tiene utilidad si se usa Python principalmente por el flujo de control mejorado sobre la mayoría de las shell de sistema, pero se desea también un acceso práctico a otras características de la shell, como pipes, nombres de fichero con comodines, expansión de variables de entorno o expansión de ~ al directorio home del usuario. Sin embargo, no se debe olvidar que el propio Python tiene implementaciones de muchas características tipo shell (en particular, glob, fnmatch, os.walk(), os.path.expandvars(), os.path.expanduser(), y shutil).

Distinto en la versión 3.3: Cuando universal_newlines es True, la clase usa la codificación locale.getpreferredencoding(False) en lugar de locale.getpreferredencoding(). Ver la clase io.TextIOWrapper para obtener más información sobre este cambio.

Nota

Leer la sección Consideraciones sobre la seguridad antes de usar shell=True.

Estas opciones y el resto se describen con más detalle en la documentación del constructor de Popen.

El constructor de Popen

El proceso interno de creación y gestión de este módulo lo gestiona la clase Popen. Proporciona una gran flexibilidad para que los desarrolladores sean capaces de gestionar los casos menos comunes que quedan sin cubrir por las funciones auxiliares.

class subprocess.Popen(args, bufsize=-1, executable=None, stdin=None, stdout=None, stderr=None, preexec_fn=None, close_fds=True, shell=False, cwd=None, env=None, universal_newlines=None, startupinfo=None, creationflags=0, restore_signals=True, start_new_session=False, pass_fds=(), *, group=None, extra_groups=None, user=None, umask=-1, encoding=None, errors=None, text=None)

Ejecuta un programa hijo en un proceso nuevo. En POSIX, la clase se comporta como os.execvp() para lanzar el proceso hijo. En Windows, la clase usa la función CreateProcess() de Windows. Los argumentos de Popen son los siguientes.

args debe ser o una secuencia de argumentos de programa o una cadena simple o un objeto tipo ruta. Por omisión, el programa a ejecutar es el primer elemento de args si args es una secuencia. Si args es una cadena, la interpretación es dependiente de la plataforma, según se describe más abajo. Véase los argumentos shell y executable para más información sobre el comportamiento por defecto. Salvo que se indique, se recomienda pasar los args como una secuencia.

Un ejemplo del paso de argumentos a un programa externo mediante una secuencia:

Popen(["/usr/bin/git", "commit", "-m", "Fixes a bug."])

En POSIX, si args es una cadena se interpreta como el nombre o la ruta del programa que ejecutar. Sin embargo, esto solamente funciona si no hay que pasar argumentos al programa.

Nota

Puede que no resulte evidente cómo descomponer una orden de la shell en una secuencia de argumentos, especialmente en casos complejos. shlex.split() puede aclarar cómo determinar la descomposición en tokens de args:

>>> import shlex, subprocess
>>> command_line = input()
/bin/vikings -input eggs.txt -output "spam spam.txt" -cmd "echo '$MONEY'"
>>> args = shlex.split(command_line)
>>> print(args)
['/bin/vikings', '-input', 'eggs.txt', '-output', 'spam spam.txt', '-cmd', "echo '$MONEY'"]
>>> p = subprocess.Popen(args) # Success!

Hay que destacar en particular que las opciones (como -input) y los argumentos (como eggs.txt) que van separados por espacio en blanco en la shell van en elementos de lista separados, mientras los argumentos que necesitan entrecomillado o escapado de espacios cuando se usan en la shell (como los nombres de ficheros con espacios o la orden echo anteriormente mostrada) son elementos simples de la lista.

En Windows, si args es una secuencia, se convertirá a cadena del modo descrito en Cómo convertir una secuencia de argumentos a una cadena en Windows. Esto es así porque la función de bajo nivel CreateProcess() funciona sobre cadenas.

Distinto en la versión 3.6: El parámetro args toma un objeto tipo ruta si shell es False y una secuencia de objetos tipo fichero en POSIX.

Distinto en la versión 3.8: El parámetro args toma un objeto tipo ruta si shell es False y una secuencia de bytes y objetos tipo fichero en Windows.

El argumento shell (False``por defecto) especifica si usar la shell como programa a ejecutar. Si *shell* es ``True, se recomienda pasar args como cadena mejor que como secuencia.

En POSIX con shell=True, la shell predeterminada es /bin/sh. Si args es una cadena, ésta especifica la orden a ejecutar por la shell. Esto significa que la cadena tiene que tener el formato que tendría si se tecleara en la línea de órdenes. Esto incluye, por ejemplo, el entrecomillado y las secuencias de escape necesarias para los nombres de fichero que contengan espacios. Si args es una secuencia, el primer elemento especifica la cadena de la orden y cualquier otro elemento será tratado como argumentos adicionales a la propia shell. De este modo, Popen hace el equivalente de:

Popen(['/bin/sh', '-c', args[0], args[1], ...])

En Windows con shell=True, la variable de entorno COMSPEC especifica la shell predeterminada. Solamente hace falta especificar shell=True en Windows cuando la orden que se desea ejecutar es interna a la shell (como. dir o copy). No hace falta especificar shell=True para ejecutar un fichero por lotes o un ejecutable de consola.

Nota

Leer la sección Consideraciones sobre la seguridad antes de usar shell=True.

Se proporcionará bufsize como el argumento correspondiente a la función open() cuando se creen los objetos fichero de los flujos stdin/stdout/stderr:

0 significa sin búfer (read y write son una llamada al sistema y pueden retornar datos parciales)

1 significa usar búfer de líneas (solamente se puede usar si universal_newlines=True, es decir, en modo texto)

cualquier otro valor positivo indica que hay que usar un búfer de aproximadamente dicho tamaño

bufsize negativo (el valor por defecto) indica que se use el valor predeterminado del sistema, io.DEFAULT_BUFFER_SIZE.

Distinto en la versión 3.3.1: bufsize es ahora -1 por defecto para permitir que el buffering por defecto se comporte como o que la mayoría del código espera. En versiones anteriores a Python 3.2.4 o 3.3.1 tomaba un valor por defecto de 0, sin búfer, lo que permitía lecturas demasiado cortas. Esto no era intencionado y no se correspondía con el comportamiento de Python 2 como la mayoría de códigos esperan.

El argumento executable especifica un programa de reemplazo que ejecutar. Esto es muy poco frecuente. Cuando shell=False, executable reemplaza al programa especificado por args. Sin embargo, se pasan los args originales al programa. La mayoría de los programas tratan el programa especificado en los args como el nombre del programa, que puede ser diferente del programa realmente ejecutado. En POSIX, el nombre en args funciona como nombre visible en utilidades como ps. Si shell=True, en POSIX el argumento executable especifica una shell de reemplazo de la predeterminada /bin/sh.

Distinto en la versión 3.6: El parámetro executable acepta un objeto tipo ruta en POSIX.

Distinto en la versión 3.8: El parámetro executable acepta bytes y un objeto tipo ruta en POSIX.

Distinto en la versión 3.9.17: Changed Windows shell search order for shell=True. The current directory and %PATH% are replaced with %COMSPEC% and %SystemRoot%\System32\cmd.exe. As a result, dropping a malicious program named cmd.exe into a current directory no longer works.

stdin, stdout and stderr specify the executed program’s standard input, standard output and standard error file handles, respectively. Valid values are PIPE, DEVNULL, an existing file descriptor (a positive integer), an existing file object with a valid file descriptor, and None. PIPE indicates that a new pipe to the child should be created. DEVNULL indicates that the special file os.devnull will be used. With the default settings of None, no redirection will occur; the child’s file handles will be inherited from the parent. Additionally, stderr can be STDOUT, which indicates that the stderr data from the applications should be captured into the same file handle as for stdout.

Si se establece preexec_fn a un objeto invocable, se llamará a dicho objeto en el proceso hijo justo antes de que se ejecute el hijo. (solamente POSIX)

Advertencia

No es seguro utilizar el parámetro preexec_fn en presencia de hilos de ejecución en la aplicación. El proceso hijo podría bloquearse antes de llamar a exec. ¡Si es imprescindible, que sea tan simple como sea posible! Se ha de minimizar el número de librerías a las que se llama.

Nota

Si es necesario modificar el entorno para el proceso hijo, se debe utilizar el parámetro env en lugar de hacerlo en una preexec_fn. El parámetro start_new_session puede tomar el lugar de un uso anteriormente común de preexec_fn para llamar a os.setsid en el proceso hijo.

Distinto en la versión 3.8: Se ha abandonado el soporte de preexec_fn en subintérpretes. El uso de dicho parámetro en un subintérprete lanza RuntimeError. La nueva restricción puede afectar a aplicaciones desplegadas en mod_wsgi, uWSGI y otros entornos incrustados.

Si close_fds es verdadero, todos los descriptores de fichero salvo 0, 1 y 2 serán cerrados antes de ejecutar el proceso hijo. Por el contrario, cuando close_fds es falso, los descriptores de fichero obedecen su indicador de heredable según Herencia de los descriptores de archivos.

En Windows, si close_fds es verdadero el proceso hijo no heredará ningún gestor de fichero salvo que se le pasen explícitamente en el elemento handle_list de STARTUPINFO.lpAttributeList, o mediante redirección estándar.

Distinto en la versión 3.2: El valor predeterminado de close_fds se cambió de False a lo antes descrito.

Distinto en la versión 3.7: En Windows, el valor predeterminado de close_fds se cambió de False a True al redirigir los gestores estándar. Ahora es posible establecer close_fds a True cuando se redirigen los gestores estándar.

pass_fds es una secuencia de descriptor de ficheros opcional que han de mantenerse abiertos entre el proceso padre e hijo. Si se proporciona un valor a pass_fds se fuerza close_fds a True. (solamente POSIX)

Distinto en la versión 3.2: Se añadió el parámetro pass_fds.

Si cwd no es None, la función cambia el directorio de trabajo a cwd antes de ejecutar el proceso hijo. cwd puede ser una cadena, o un objeto bytes o tipo ruta. En particular, la función busca executable (o el primer elemento de args) relativo a cwd si la ruta del ejecutable es relativa.

Distinto en la versión 3.6: El parámetro cwd acepta un objeto tipo ruta en POSIX.

Distinto en la versión 3.7: El parámetro cwd acepta un objeto tipo ruta en Windows.

Distinto en la versión 3.8: El parámetro cwd acepta un objeto bytes en Windows.

Si restore_signals es verdadero (el valor por defecto) todas las señales que Python ha establecido a SIG_IGN se restauran a SIG_DFL en el proceso hijo antes del exec. En la actualidad, esto incluye las señales SIGPIPE, SIGXFZ y SIGXFSZ (solamente POSIX).

Distinto en la versión 3.2: Se añadió restore_signals.

Si start_new_session es verdadero la llamada al sistema setsid se hará en el proceso hijo antes de la ejecución del subproceso (solamente POSIX).

Distinto en la versión 3.2: Se añadió start_new_session.

Si group no es None, la llamada a sistema setregid() se hará en el proceso hijo antes de la ejecución del subproceso. Si el valor proveído es una cadena de caracteres, será buscado usando grp.getgrnam() y el valor en gr_gid será usado. Si el valor es un entero, será pasado literalmente. (solamente POSIX)

Disponibilidad: POSIX

Nuevo en la versión 3.9.

Si extra_groups no es None, la llamada a sistema setgroups() se hará en el proceso hijo antes de la ejecución del subproceso. Cadenas de caracteres proveídas en extra_groups serán buscadas usando grp.getgrnam() y los valores en gr_gid serán usados. Valor enteros serán pasados literalmente. (solamente POSIX)

Disponibilidad: POSIX

Nuevo en la versión 3.9.

Si user no es None, la llamada a sistema setreuid() se hará en el proceso hijo antes de la ejecución del subproceso. Si el valor proveído es una cadena de caracteres, será buscado usando pwd.getpwnam() y el valor en pw_uid será usado. Si el valor es un entero, será pasado literalmente. (solamente POSIX)

Disponibilidad: POSIX

Nuevo en la versión 3.9.

Si umask no es negativo, la llamada a sistema umask() se hará en el proceso hijo antes de la ejecución del subproceso.

Disponibilidad: POSIX

Nuevo en la versión 3.9.

Si env no es None, debe ser un mapeo que defina las variables de entorno del nuevo proceso; se utilizarán éstas en lugar del comportamiento por defecto de heredar el entorno del proceso en curso.

Nota

Si se especifica, env debe proporcionar las variables necesarias para que el programa se ejecute. En Windows, para ejecutar una side-by-side assembly [https://en.wikipedia.org/wiki/Side-by-Side_Assembly] el env especificado debe incluir un SystemRoot válido.

Si se especifica encoding o errors, o text verdadero, los objetos fichero stdin, stdout y stderr se abren en modo texto con la codificación y errors especificados, según se describió en Argumentos frecuentemente empleados. El argumento universal_newlines es equivalente a text y se admite por compatibilidad hacia atrás. Por omisión, los ficheros se abren en modo binario.

Nuevo en la versión 3.6: Se añadieron encoding y errors.

Nuevo en la versión 3.7: Se añadió text como alias más legible de universal_newlines.

Si se proporciona, startupinfo será un objeto STARTUPINFO, que se pasa a la función de más bajo nivel CreateProcess. creationflags, si está presente, puede ser uno o más de los siguientes indicadores:

CREATE_NEW_CONSOLE

CREATE_NEW_PROCESS_GROUP

ABOVE_NORMAL_PRIORITY_CLASS

BELOW_NORMAL_PRIORITY_CLASS

HIGH_PRIORITY_CLASS

IDLE_PRIORITY_CLASS

NORMAL_PRIORITY_CLASS

REALTIME_PRIORITY_CLASS

CREATE_NO_WINDOW

DETACHED_PROCESS

CREATE_DEFAULT_ERROR_MODE

CREATE_BREAKAWAY_FROM_JOB

Se puede usar los objetos Popen como gestores de contexto mediante sentencia with: a la salida, los descriptores de flujo se cierran y se espera a que acabe el proceso.

with Popen(["ifconfig"], stdout=PIPE) as proc:
    log.write(proc.stdout.read())

Lanza un evento de auditoría subprocess.Popen con argumentos executable, args, cwd, env.

Distinto en la versión 3.2: Se añadió la funcionalidad de gestor de contexto.

Distinto en la versión 3.6: El destructor de Popen ahora emite una advertencia ResourceWarning si el proceso hijo todavía se está ejecutando.

Distinto en la versión 3.8: Popen puede usar os.posix_spawn() en algunos casos para obtener mejor rendimiento. En el Subsistema de Windows para Linux (WSL) y en la emulación del modo usuario de QEMU, el constructor de Popen que use os.posix_spawn() ya no lanzará una excepción cuando se den errores tales como que un programa no esté, sino que el proceso hijo fracasará con un returncode distinto de cero.

Excepciones

Las excepciones lanzadas en el proceso hijo, antes de que el nuevo programa haya empezado a ejecutarse, se relanzarán en el padre.

The most common exception raised is OSError. This occurs, for example, when trying to execute a non-existent file. Applications should prepare for OSError exceptions. Note that, when shell=True, OSError will be raised by the child only if the selected shell itself was not found. To determine if the shell failed to find the requested application, it is necessary to check the return code or output from the subprocess.

Se lanzará un ValueError si se llama a Popen con argumentos no válidos.

check_call() y check_output() lanzarán un CalledProcessError si el proceso invocado retorna un código de retorno distinto de cero.

Todas las funciones y métodos que admiten un parámetro timeout, tales como call() y Popen.communicate() lanzarán TimeoutExpired si se vence el plazo de ejecución antes de que finalice el proceso hijo.

Todas las excepciones definidas en este módulo heredan de SubprocessError.

Nuevo en la versión 3.3: Se añadió la clase base SubprocessError.

Consideraciones sobre seguridad

Al contrario que otras funciones popen, esta implementación nunca llamará implícitamente a la shell del sistema. Esto significa que todos los caracteres, incluidos los metacaracteres de la shell, se pueden pasar de manera segura a los procesos hijos. Si se invoca la shell explícitamente, mediante shell=True, es responsabilidad de la aplicación asegurar que todo el espaciado y metacaracteres se entrecomillan adecuadamente para evitar vulnerabilidades de inyección de código [https://es.wikipedia.org/wiki/Inyecci%C3%B3n_de_c%C3%B3digo].

Cuando se usa shell=True, se puede usar la función shlex.quote() para escapar correctamente el espaciado y los metacaracteres de la shell en las cadenas que se vayan a utilizar para construir órdenes de la shell.

Objetos Popen

Las instancias de la clase Popen cuentan con los siguientes métodos:

Popen.poll()

Comprueba si el proceso hijo ha finalizado. Establece y retorna el atributo returncode. De lo contrario, retorna None.

Popen.wait(timeout=None)

Espera a que termine el proceso hijo. Establece y retorna el atributo returncode.

Si el proceso no finaliza tras timeout segundos, lanza una excepción TimeoutExpired. Se puede capturar esta excepción para reintentar la espera.

Nota

Esto causará un bloqueo cuando se use stdout=PIPE o stderr=PIPE y el proceso hijo genere suficiente salida hacia un pipe como para bloquear esperando que el búfer del pipe del SO acepte más datos. Se debe usar Popen.communicate() cuando se usen pipes para evitar esto.

Nota

Esta función se implementa mediante una espera activa (llamada no bloqueante y breves llamadas a sleep). Se debe usar el módulo asyncio para hacer una espera asíncrona: ver asyncio.create_subprocess_exec.

Distinto en la versión 3.3: Se añadió timeout.

Popen.communicate(input=None, timeout=None)

Interactúa con el proceso: Envía datos a stdin. Lee datos de stdout y stderr hasta encontrar un fin-de-fichero. Espera a que termine el proceso y escribe el atributo returncode. El argumento opcional input debe contener los datos que hay que enviar al proceso hijo o None si no hay que enviar datos al proceso hijo. Si se abrieron los flujos en modo texto, input ha de ser una cadena de caracteres. En caso contrario, debe contener bytes.

communicate() retorna una tupla (stdout_data, stderr_data). Los datos serán cadenas si se abrieron los flujos en modo texto, en caso contrario serán bytes.

Adviértase que si se desea enviar datos al stdin del proceso, se ha de crear el objeto Popen con stdin=PIPE. Análogamente, para obtener algo diferente de None en la tupla del resultado, hay que suministrar stdout=PIPE o stderr=PIPE también.

Si el proceso no termina tras timeout segundos, se lanza una excepción TimeoutExpired. Si se captura dicha excepción y se reintenta la comunicación, no se perderán datos de salida.

No se matará el proceso si vence el plazo de ejecución, así que para hacer limpieza, una aplicación correcta debería matar el proceso y terminar la comunicación:

proc = subprocess.Popen(...)
try:
    outs, errs = proc.communicate(timeout=15)
except TimeoutExpired:
    proc.kill()
    outs, errs = proc.communicate()

Nota

Los datos leídos pasan por un búfer en memoria, así que no se ha de usar este método para un tamaño de datos grande o ilimitado.

Distinto en la versión 3.3: Se añadió timeout.

Popen.send_signal(signal)

Envía la señal signal al proceso hijo.

No hace nada si el proceso ya ha terminado.

Nota

En Windows, SIGTERM es un alias de terminate(). Se puede enviar CTRL_C_EVENT y CTRL_BREAK_EVENT a los procesos creados con un parámetro creationflags que incluya CREATE_NEW_PROCESS_GROUP.

Popen.terminate()

Detiene el proceso hijo. En sistemas operativos POSIX este método envía SIGTERM al proceso hijo. En Windows se llama a la función TerminateProcess() de la API de Win32 para detener el proceso hijo.

Popen.kill()

Mata el proceso hijo. En sistemas operativos POSIX la función envía SIGKILL al proceso hijo. En Windows kill() es un alias de terminate().

También están disponibles los siguientes atributos:

Popen.args

El argumento args según se pasó a Popen: o una secuencia de argumentos del programa o una cadena sencilla.

Nuevo en la versión 3.3.

Popen.stdin

Si el argumento stdin fue PIPE, este atributo es un objeto flujo escribible según lo retorna open(). Si se especificaron argumentos encoding o errors o el argumento universal_newlines fue True, el flujo es de texto, de lo contrario, es de bytes. Si el argumento stdin no fue PIPE, este atributo es None.

Popen.stdout

Si el argumento stdout fue PIPE, este atributo el un objeto de flujo legible según lo retorna open(). Leer del flujo proporciona salida del proceso hijo. Si se especificaron argumentos encoding o errors o el argumento universal_newlines fue True, el flujo es de texto, de lo contrario, es de bytes. Si el argumento stdout no fue PIPE, este atributo es None.

Popen.stderr

Si el argumento stderr fue PIPE, este atributo el un objeto de flujo legible según lo retorna open(). Leer del flujo proporciona salida del proceso hijo. Si se especificaron argumentos encoding o errors o el argumento universal_newlines fue True, el flujo es de texto, de lo contrario, es de bytes. Si el argumento stderr no fue PIPE, este atributo es None.

Advertencia

Se ha de usar communicate() en lugar de .stdin.write, .stdout.read o .stderr.read para evitar bloqueos por búfer de pipes del SO llenos que puedan bloquear el proceso hijo.

Popen.pid

El ID de proceso del hijo.

Adviértase que si se establece el argumento shell a True, éste es el ID de proceso del la shell generada.

Popen.returncode

El código de retorno del hijo, establecido por poll() y wait() (e indirectamente por communicate()). Un valor None indica que el proceso no ha terminado aún.

Un valor negativo -N indica que el hijo fue forzado a terminar con la señal N (solamente POSIX).

Elementos auxiliares de Popen en Windows

La clase STARTUPINFO y las siguientes constantes sólo están disponibles en Windows.

class subprocess.STARTUPINFO(*, dwFlags=0, hStdInput=None, hStdOutput=None, hStdError=None, wShowWindow=0, lpAttributeList=None)

Se utiliza un soporte parcial de la estructura STARTUPINFO [https://msdn.microsoft.com/en-us/library/ms686331(v=vs.85).aspx] de Windows para la creación de Popen. Se pueden establecer los siguientes atributos pasándolos como argumentos sólo por clave.

Distinto en la versión 3.7: Se añadió el soporte de argumentos sólo por clave.

dwFlags

Un campo bit que determina si se usan ciertos atributos de STARTUPINFO cuando el proceso crea una ventana.

si = subprocess.STARTUPINFO()
si.dwFlags = subprocess.STARTF_USESTDHANDLES | subprocess.STARTF_USESHOWWINDOW

hStdInput

Si dwFlags especifica STARTF_USESTDHANDLES, este atributo es el gestor de entrada estándar del proceso. Si no se especifica STARTF_USESTDHANDLES, el valor predeterminado de entrada estándar es el búfer de teclado.

hStdOutput

Si dwFlags especifica STARTF_USESTDHANDLES, este atributo es el gestor de salida estándar del proceso. En caso contrario, se hace caso omiso del atributo y el valor predeterminado de salida estándar es el búfer de ventana.

hStdError

Si dwFlags especifica STARTF_USESTDHANDLES, este atributo es el gestor de error estándar del proceso. En caso contrario, se hace caso omiso del atributo y el valor predeterminado de error estándar es el búfer de ventana.

wShowWindow

Si dwFlags especifica STARTF_USESHOWWINDOW, este atributo puede ser cualquiera de los valores que pueden especificarse en el parámetro nCmdShow para la función ShowWindow [https://msdn.microsoft.com/en-us/library/ms633548(v=vs.85).aspx], salvo SW_SHOWDEFAULT. De otro modo, se hace caso omiso del atributo.

Se proporciona SW_HIDE para este atributo. Se usa cuando se llama a Popen con shell=True.

lpAttributeList

Un diccionario de atributos adicionales para la creación del proceso, según STARTUPINFOEX, véase UpdateProcThreadAttribute [https://msdn.microsoft.com/en-us/library/windows/desktop/ms686880(v=vs.85).aspx].

Atributos admitidos:

handle_list

Una secuencia de gestores que se heredará. close_fds debe ser verdadero si no viene vacío.

Los gestores deben hacerse temporalmente heredables por os.set_handle_inheritable() cuando se pasan al constructor de Popen o de lo contrario, se lanzará OSError con el error de Windows ERROR_INVALID_PARAMETER (87).

Advertencia

En un proceso multihilo, hay que evitar filtrar gestores no heredables cuando se combina esta característica con llamadas concurrentes a otras funciones de creación de procesos que heredan todos los gestores, como os.system(). Esto también rige para la redirección de gestores estándar, que crea temporalmente gestores heredables.

Nuevo en la versión 3.7.

Constantes de Windows

El módulo subprocess expone las siguientes constantes.

subprocess.STD_INPUT_HANDLE

El dispositivo de entrada estándar. Inicialmente, es el búfer de entrada de la consola, CONIN$.

subprocess.STD_OUTPUT_HANDLE

El dispositivo de salida estándar. Inicialmente, es el búfer de pantalla de la consola activa, CONOUT$.

subprocess.STD_ERROR_HANDLE

El dispositivo de error estándar. Inicialmente, es el búfer de pantalla de la consola activa, CONOUT$.

subprocess.SW_HIDE

Oculta la ventana. Se activará otra ventana.

subprocess.STARTF_USESTDHANDLES

Especifica que los atributos STARTUPINFO.hStdInput, STARTUPINFO.hStdOutput, y STARTUPINFO.hStdError contienen información adicional.

subprocess.STARTF_USESHOWWINDOW

Especifica que el atributo STARTUPINFO.wShowWindow contiene información adicional.

subprocess.CREATE_NEW_CONSOLE

El nuevo proceso obtiene una nueva consola, en lugar de heredar la consola del padre (que es el comportamiento predeterminado).

subprocess.CREATE_NEW_PROCESS_GROUP

Un parámetro Popen creationflags para especificar que se cree un nuevo grupo de procesos. Este indicador es necesario para usar os.kill() sobre el subproceso.

Este indicador no se tiene en cuenta si se especifica CREATE_NEW_CONSOLE.

subprocess.ABOVE_NORMAL_PRIORITY_CLASS

Parámetro Popen creationflags para especificar que el nuevo proceso tendrá una prioridad superior a la media.

Nuevo en la versión 3.7.

subprocess.BELOW_NORMAL_PRIORITY_CLASS

Parámetro Popen creationflags para especificar que el nuevo proceso tendrá una prioridad inferior a la media.

Nuevo en la versión 3.7.

subprocess.HIGH_PRIORITY_CLASS

Parámetro Popen creationflags para especificar que el nuevo proceso tendrá una prioridad elevada.

Nuevo en la versión 3.7.

subprocess.IDLE_PRIORITY_CLASS

Parámetro Popen creationflags para especificar que el nuevo proceso tendrá una la mínima prioridad.

Nuevo en la versión 3.7.

subprocess.NORMAL_PRIORITY_CLASS

Parámetro Popen creationflags para especificar que el nuevo proceso tendrá una prioridad normal (éste es el valor predeterminado).

Nuevo en la versión 3.7.

subprocess.REALTIME_PRIORITY_CLASS

Parámetro Popen creationflags para especificar que el nuevo proceso tendrá una prioridad de tiempo real. Raramente se debería usar REALTIME_PRIORITY_CLASS, porque esto interrumpe los hilos que gestionan la entrada del ratón y del teclado, así como la gestión del volcado de búfer del disco. Esta clase es apropiada para aplicaciones que se comunican directamente con el hardware o que llevan a cabo tareas breves que no admitan interrupciones.

Nuevo en la versión 3.7.

subprocess.CREATE_NO_WINDOW

Parámetro Popen creationflags para especificar que el nuevo proceso no creará una ventana.

Nuevo en la versión 3.7.

subprocess.DETACHED_PROCESS

Parámetro Popen creationflags para especificar que el nuevo proceso no heredará la consola del padre. Este valor es incompatible con CREATE_NEW_CONSOLE.

Nuevo en la versión 3.7.

subprocess.CREATE_DEFAULT_ERROR_MODE

Parámetro Popen creationflags para especificar que el nuevo proceso no hereda el modo de error del proceso padre. En su lugar, el proceso parte del modo de error predeterminado. Esta característica es particularmente útil para aplicaciones de shell multihilo que se ejecutan con los errores “duros” desactivados.

Nuevo en la versión 3.7.

subprocess.CREATE_BREAKAWAY_FROM_JOB

Parámetro Popen creationflags para especificar que el nuevo proceso no está asociado a la tarea.

Nuevo en la versión 3.7.

Antigua API de alto nivel

Antes de Python 3.5, estas tres funciones conformaban la API de alto nivel para subprocesos. Ahora se puede usar run() en muchos casos, pero hay mucho código escrito con estas funciones.

subprocess.call(args, *, stdin=None, stdout=None, stderr=None, shell=False, cwd=None, timeout=None, **other_popen_kwargs)

Ejecutar la orden descrita por args. Esperar que la orden se complete y retornar al atributo returncode.

El código que requiera capturar stdout o stderr debería usar run() en su lugar:

run(...).returncode

Para suprimir stdout o stderr se ha de proporcionar un valor de DEVNULL.

Se muestran algunos argumentos comunes. La signatura completa de la función es la misma que la del constructor de Popen; esta función pasa todos los argumentos proporcionados (salvo timeout) directamente a esa interfaz.

Nota

No usar stdout=PIPE ni stderr=PIPE con esta función. El proceso hijo se bloqueará si genera suficiente salida a un pipe como para saturar el búfer del pipe del sistema operativo mientras no se lee de los pipes.

Distinto en la versión 3.3: Se añadió timeout.

Distinto en la versión 3.9.17: Changed Windows shell search order for shell=True. The current directory and %PATH% are replaced with %COMSPEC% and %SystemRoot%\System32\cmd.exe. As a result, dropping a malicious program named cmd.exe into a current directory no longer works.

subprocess.check_call(args, *, stdin=None, stdout=None, stderr=None, shell=False, cwd=None, timeout=None, **other_popen_kwargs)

Run command with arguments. Wait for command to complete. If the return code was zero then return, otherwise raise CalledProcessError. The CalledProcessError object will have the return code in the returncode attribute. If check_call() was unable to start the process it will propagate the exception that was raised.

El código que requiera capturar stdout o stderr debería usar run() en su lugar:

run(..., check=True)

Para suprimir stdout o stderr se ha de proporcionar un valor de DEVNULL.

Se muestran algunos argumentos comunes. La signatura completa de la función es la misma que la del constructor de Popen; esta función pasa todos los argumentos proporcionados (salvo timeout) directamente a esa interfaz.

Nota

No usar stdout=PIPE ni stderr=PIPE con esta función. El proceso hijo se bloqueará si genera suficiente salida a un pipe como para saturar el búfer del pipe del sistema operativo mientras no se lee de los pipes.

Distinto en la versión 3.3: Se añadió timeout.

Distinto en la versión 3.9.17: Changed Windows shell search order for shell=True. The current directory and %PATH% are replaced with %COMSPEC% and %SystemRoot%\System32\cmd.exe. As a result, dropping a malicious program named cmd.exe into a current directory no longer works.

subprocess.check_output(args, *, stdin=None, stderr=None, shell=False, cwd=None, encoding=None, errors=None, universal_newlines=None, timeout=None, text=None, **other_popen_kwargs)

Ejecuta orden con argumentos y retorna su salida.

Si el código de retorno fue diferente de cero lanza un CalledProcessError. El objeto CalledProcessError tendrá el código de retorno en el atributo returncode y los datos de salida en el atributo output.

Esto equivale a:

run(..., check=True, stdout=PIPE).stdout

Los argumentos mostrados arriba son meramente algunos de los comunes. La signatura completa de la función es casi la misma que la de run() - la mayoría de los argumentos se pasa directamente a esa interfaz. Existe una diferencia con la interfaz de run() respecto al comportamiento: pasar input=None genera el mismo comportamiento que input=b'' (o input='', dependiendo de otros argumentos) en vez de usar el flujo entrada estándar del padre.

Por omisión, esta función retornará los datos como bytes codificados. La codificación real de los datos podría depender de la orden invocada, por lo que la decodificación a texto se deberá hacer al nivel de la aplicación.

Este comportamiento se puede modificar estableciendo text, encoding, errors, o universal_newlines a True, como se describe en Argumentos frecuentemente empleados y run().

Para capturar también el error estándar del resultado se debe usar stderr=subprocess.STDOUT:

>>> subprocess.check_output(
...     "ls non_existent_file; exit 0",
...     stderr=subprocess.STDOUT,
...     shell=True)
'ls: non_existent_file: No such file or directory\n'

Nuevo en la versión 3.1.

Distinto en la versión 3.3: Se añadió timeout.

Distinto en la versión 3.4: Se añadió soporte para el argumento por clave input.

Distinto en la versión 3.6: Se añadieron encoding y errors. Ver run() para más detalles.

Nuevo en la versión 3.7: Se añadió text como alias más legible de universal_newlines.

Distinto en la versión 3.9.17: Changed Windows shell search order for shell=True. The current directory and %PATH% are replaced with %COMSPEC% and %SystemRoot%\System32\cmd.exe. As a result, dropping a malicious program named cmd.exe into a current directory no longer works.

Cómo reemplazar anteriores funciones con el módulo subprocess

En esta sección, «a se convierte en b» significa que b se puede usar en lugar de.

Nota

Todas las funciones «a» de esta sección fracasan silenciosamente (o casi) si no se halla el programa ejecutado; las funciones de reemplazo «b» lanzan OSError en lugar de esto.

Además, las funciones de reemplazo que usan check_output() fracasarán con un error CalledProcessError si la operación solicitada produce un código de retorno diferente de cero. La salida queda disponible en el atributo output de la excepción lanzada.

En los siguientes ejemplos, se asume que las funciones relevantes ya han sido importadas del módulo subprocess.

Cómo reemplazar la sustitución de órdenes de /bin/sh

output=$(mycmd myarg)

se convierte en:

output = check_output(["mycmd", "myarg"])

Cómo remplazar los flujos de la shell

output=$(dmesg | grep hda)

se convierte en:

p1 = Popen(["dmesg"], stdout=PIPE)
p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
p1.stdout.close()  # Allow p1 to receive a SIGPIPE if p2 exits.
output = p2.communicate()[0]

La llamada a p1.stdout.close() tras lanzar p2 es importante para que p1 reciba un SIGPIPE si p2 retorna antes que p1.

Alternativamente, para entrada de confianza, se puede usar el propio soporte de pipeline de la shell directamente:

output=$(dmesg | grep hda)

se convierte en:

output=check_output("dmesg | grep hda", shell=True)

Cómo reemplazar os.system()

sts = os.system("mycmd" + " myarg")
# becomes
retcode = call("mycmd" + " myarg", shell=True)

Notas:

No suele hacer falta llamar al programa a través de la shell.

The call() return value is encoded differently to that of os.system().

The os.system() function ignores SIGINT and SIGQUIT signals while the command is running, but the caller must do this separately when using the subprocess module.

Un ejemplo más creíble:

try:
    retcode = call("mycmd" + " myarg", shell=True)
    if retcode < 0:
        print("Child was terminated by signal", -retcode, file=sys.stderr)
    else:
        print("Child returned", retcode, file=sys.stderr)
except OSError as e:
    print("Execution failed:", e, file=sys.stderr)

Cómo reemplazar la familia os.spawn

Ejemplo de P_NOWAIT:

pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
==>
pid = Popen(["/bin/mycmd", "myarg"]).pid

Ejemplo de P_WAIT:

retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
==>
retcode = call(["/bin/mycmd", "myarg"])

Ejemplo de vector:

os.spawnvp(os.P_NOWAIT, path, args)
==>
Popen([path] + args[1:])

Ejemplo de entorno:

os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)
==>
Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})

Cómo reemplazar os.popen(), os.popen2(), os.popen3()

(child_stdin, child_stdout) = os.popen2(cmd, mode, bufsize)
==>
p = Popen(cmd, shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdin, child_stdout) = (p.stdin, p.stdout)

(child_stdin,
 child_stdout,
 child_stderr) = os.popen3(cmd, mode, bufsize)
==>
p = Popen(cmd, shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=True)
(child_stdin,
 child_stdout,
 child_stderr) = (p.stdin, p.stdout, p.stderr)

(child_stdin, child_stdout_and_stderr) = os.popen4(cmd, mode, bufsize)
==>
p = Popen(cmd, shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, stderr=STDOUT, close_fds=True)
(child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout)

La gestión del código de retorno se traduce así:

pipe = os.popen(cmd, 'w')
...
rc = pipe.close()
if rc is not None and rc >> 8:
    print("There were some errors")
==>
process = Popen(cmd, stdin=PIPE)
...
process.stdin.close()
if process.wait() != 0:
    print("There were some errors")

Cómo reemplazar las funciones del módulo popen2

Nota

Si el argumento cmd de las funciones popen2 es una cadena, la orden se ejecuta a través de /bin/sh. Si es una lista, la orden se ejecuta directamente.

(child_stdout, child_stdin) = popen2.popen2("somestring", bufsize, mode)
==>
p = Popen("somestring", shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdout, child_stdin) = (p.stdout, p.stdin)

(child_stdout, child_stdin) = popen2.popen2(["mycmd", "myarg"], bufsize, mode)
==>
p = Popen(["mycmd", "myarg"], bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdout, child_stdin) = (p.stdout, p.stdin)

popen2.Popen3 y popen2.Popen4 funcionan a grandes rasgos como subprocess.Popen, salvo:

Popen lanza una excepción si falla la ejecución.

El argumento capturestderr se sustituye por el argumento stderr.

Se ha de especificar stdin=PIPE y stdout=PIPE.

popen2 cierra todos los descriptores de fichero por omisión, pero se ha de especificar close_fds=True con Popen para garantizar este comportamiento en todas las plataformas o en versiones anteriores de Python.

Funciones de llamada a la shell de retrocompatibilidad

Este módulo también proporciona las siguientes funciones de compatibilidad del módulo commands de las versiones 2.X. Estas operaciones invocan implícitamente a la shell del sistema y no se les aplican ninguna de las garantías descritas anteriormente respecto a seguridad o consistencia en la gestión de excepciones.

subprocess.getstatusoutput(cmd)

Retorna (exitcode, output) de ejecutar cmd en una shell.

Ejecuta la cadena cmd en una shell con Popen.check_output() y retorna una tupla (exitcode, output). Se utiliza la codificación de localización activa; consultar las notas sobre Argumentos frecuentemente empleados para más información.

Se elimina un salto de línea final de la salida. El código de salida de la orden se puede interpretar como el código de retorno del subproceso. Por ejemplo:

>>> subprocess.getstatusoutput('ls /bin/ls')
(0, '/bin/ls')
>>> subprocess.getstatusoutput('cat /bin/junk')
(1, 'cat: /bin/junk: No such file or directory')
>>> subprocess.getstatusoutput('/bin/junk')
(127, 'sh: /bin/junk: not found')
>>> subprocess.getstatusoutput('/bin/kill $$')
(-15, '')

Disponibilidad: POSIX y Windows.

Distinto en la versión 3.3.4: Se añadió soporte de Windows.

La función ahora retorna (exitcode, output) en lugar de (status, output) como en Python 3.3.3 y anteriores. exitcode tiene el mismo valor que returncode.

subprocess.getoutput(cmd)

Retorna la salida (stdout y stderr) de ejecutar cmd en una shell.

Como getstatusoutput(), salvo que se ignora el código de salida y el valor retornado es una cadena que contiene la salida del comando. Por ejemplo:

>>> subprocess.getoutput('ls /bin/ls')
'/bin/ls'

Disponibilidad: POSIX y Windows.

Distinto en la versión 3.3.4: Se añadió soporte de Windows

Notas

Cómo convertir una secuencia de argumentos a una cadena en Windows

En Windows, para convertir una secuencia args en una cadena que puede ser analizada con las siguientes reglas (correspondientes a las reglas que usa la biblioteca de ejecución de MS C):

Los argumentos se separan por espacio en blanco, que debe ser un espacio o un tabulador.

Una cadena entre comillas dobles se interpreta como un argumento simple, sin importar los espacios en blanco que contenga. Se puede incrustar una cadena entre comillas en un argumento.

Una comilla doble precedida de una barra invertida se interpreta literalmente como una comilla doble.

Las barras invertidas se interpretan literalmente, salvo que precedan a una comilla doble.

Si las barras invertidas preceden inmediatamente a una doble comilla, cada par de barras invertidas se interpreta como una barra invertida literal. Si el número de barras invertidas es impar, la última barra invertida escapa la siguiente comilla doble según se describe en la regla 3.

Ver también

shlex

Módulo que proporciona una función para analizar y escapar líneas de órdenes.

sched — Eventos del planificador

Código fuente: Lib/sched.py [https://github.com/python/cpython/tree/3.9/Lib/sched.py]

El módulo sched define una clase que implementa un planificador de eventos de propósito general:

class sched.scheduler(timefunc=time.monotonic, delayfunc=time.sleep)

La clase scheduler define una interfaz genérica para planificar eventos. Necesita dos funciones para tratar con el «mundo exterior» — timefunc debe poder llamarse sin argumentos y retornar un número (el «time», en cualquier unidad). La función delayfunc debería ser invocable con un argumento, compatible con la salida de timefunc, y debería retrasar tantas unidades de tiempo. delayfunc también se llamará con el argumento 0 después de que se ejecute cada evento para permitir que otros hilos tengan la oportunidad de ejecutarse en aplicaciones multihilo.

Distinto en la versión 3.3: Los argumentos timefunc and delayfunc son opcionales.

Distinto en la versión 3.3: scheduler La clase se puede usar de forma segura en entornos multihilo.

Ejemplo:

>>> import sched, time
>>> s = sched.scheduler(time.time, time.sleep)
>>> def print_time(a='default'):
...     print("From print_time", time.time(), a)
...
>>> def print_some_times():
...     print(time.time())
...     s.enter(10, 1, print_time)
...     s.enter(5, 2, print_time, argument=('positional',))
...     s.enter(5, 1, print_time, kwargs={'a': 'keyword'})
...     s.run()
...     print(time.time())
...
>>> print_some_times()
930343690.257
From print_time 930343695.274 positional
From print_time 930343695.275 keyword
From print_time 930343700.273 default
930343700.276

Objetos de Scheduler

scheduler Las sentencias tienen los siguientes métodos y atributos:

scheduler.enterabs(time, priority, action, argument=(), kwargs={})

Planifica un nuevo evento. El argumento time debe ser un tipo numérico compatible con el valor de retorno de la función timefunc que se pasa al constructor. Los eventos planificados para la misma time se ejecutarán en el orden de su priority. Un número más bajo representa una prioridad más alta.

Ejecutar el evento significa ejecutar action(*argument, **kwargs). argument es una secuencia que contiene los argumentos posicionales para action. kwargs es un diccionario que contiene los argumentos de palabras clave para action.

El valor de retorno es un evento que puede usarse para una cancelación posterior del evento (ver cancel()).

Distinto en la versión 3.3: El argumento argument es opcional.

Distinto en la versión 3.3: Se agregó el argumento kwargs.

scheduler.enter(delay, priority, action, argument=(), kwargs={})

Planifica un evento delay para más unidades de tiempo. Aparte del tiempo relativo, los otros argumentos, el efecto y el valor de retorno son los mismos que para enterabs().

Distinto en la versión 3.3: El argumento argument es opcional.

Distinto en la versión 3.3: Se agregó el argumento kwargs.

scheduler.cancel(event)

Elimina el evento de la cola. Si event no es un evento actualmente en la cola, este método generará un ValueError.

scheduler.empty()

Retorna True si la cola de eventos está vacía.

scheduler.run(blocking=True)

Ejecuta todos los eventos programados. Este método esperará (usando la función delayfunc() enviada al constructor) el próximo evento, luego lo ejecutará y así sucesivamente hasta que no haya más eventos programados.

Si blocking es falso, se ejecutan los eventos planificados que expiran mas pronto (si corresponde) y luego retorna la fecha límite de la próxima llamada programada en el planificador (si corresponde).

action o delayfunc pueden generar una excepción. En cualquier caso, el planificador mantendrá un estado consistente y propagará la excepción. Si action genera una excepción, el evento no se intentará en futuras llamadas a run().

Si una secuencia de eventos tarda más en ejecutarse que el tiempo disponible antes del próximo evento, el planificador simplemente se retrasará. No se descartarán eventos; el código de llamada es responsable de cancelar eventos que ya no son oportunos.

Distinto en la versión 3.3: Se agregó el argumento blocking.

scheduler.queue

Atributo de solo lectura que retorna una lista de los próximos eventos en el orden en que se ejecutarán. Cada evento se muestra como un named tuple con los siguientes campos : time, priority, action, argument, kwargs.

queue — clase de cola sincronizada

Código fuente: Lib/queue.py [https://github.com/python/cpython/tree/3.9/Lib/queue.py]

El módulo queue implementa colas multi-productor y multi-consumidor. Es especialmente útil en la programación en hilo cuando la información debe intercambiarse de forma segura entre varios subprocesos. La clase Queue de este módulo implementa toda la semántica de bloqueo necesaria.

El módulo implementa tres tipos de cola, que difieren sólo en el orden en que se recuperan las entradas. En una cola FIFO, las primeras tareas añadidas son las primeras recuperadas. En una cola LIFO, la última entrada añadida es la primera recuperada (operando como una pila). En una cola de prioridad, las entradas se mantienen ordenadas (usando el módulo heapq) y la entrada de menor valor se recupera primero.

Internamente, estos tres tipos de colas utilizan bloqueos para bloquear temporalmente los hilos que compiten entre sí; sin embargo, no están diseñadas para manejar la reposición dentro de un hilo.

Además, el módulo implementa un tipo de cola «simple» FIFO, SimpleQueue, cuya implementación específica proporciona garantías adicionales a cambio de una funcionalidad menor.

El módulo queue define las siguientes clases y excepciones:

class queue.Queue(maxsize=0)

Constructor para una cola FIFO. maxsize es un número entero que establece el límite superior del número de elementos que pueden ser colocados en la cola. La inserción se bloqueará una vez que se haya alcanzado este tamaño, hasta que se consuman los elementos de la cola. Si maxsize es menor o igual a cero, el tamaño de la cola es infinito.

class queue.LifoQueue(maxsize=0)

Constructor para una cola LIFO. maxsize es un número entero que establece el límite superior del número de elementos que pueden ser colocados en la cola. La inserción se bloqueará una vez que se haya alcanzado este tamaño, hasta que se consuman los elementos de la cola. Si maxsize es menor o igual a cero, el tamaño de la cola es infinito.

class queue.PriorityQueue(maxsize=0)

Constructor para una cola de prioridad. maxsize es un número entero que establece el límite superior del número de elementos que pueden ser colocados en la cola. La inserción se bloqueará una vez que se haya alcanzado este tamaño, hasta que se consuman los elementos de la cola. Si maxsize es menor o igual a cero, el tamaño de la cola es infinito.

Las entradas de menor valor se recuperan primero (la entrada de menor valor es la retornada por sorted(list(entries))[0]). Un patrón típico para las entradas es una tupla en la forma: (número_de_prioridad, datos).

Si los elementos de datos no son comparables, los datos pueden envolverse en una clase que ignore el elemento de datos y sólo compare el número de prioridad:

from dataclasses import dataclass, field
from typing import Any

@dataclass(order=True)
class PrioritizedItem:
    priority: int
    item: Any=field(compare=False)

class queue.SimpleQueue

Constructor de una cola sin límites FIFO. Las colas simples carecen de funcionalidad avanzada como el seguimiento de tareas.

Nuevo en la versión 3.7.

exception queue.Empty

Excepción lanzada cuando el objeto get() (o get_nowait()) que no se bloquea es llamado en un objeto Queue que está vacío.

exception queue.Full

Excepción lanzada cuando el objeto put() (o put_nowait()) que no se bloquea es llamado en un objeto Queue que está lleno.

Objetos de la cola

Los objetos de la cola (Queue, LifoQueue, o PriorityQueue) proporcionan los métodos públicos descritos a continuación.

Queue.qsize()

Retorna el tamaño aproximado de la cola. Nota, qsize() > 0 no garantiza que un get() posterior no se bloquee, ni qsize() < maxsize garantiza que put() no se bloquee.

Queue.empty()

Retorna True si la cola está vacía, False si no. Si empty() retorna True no garantiza que una llamada posterior a put() no se bloquee. Del mismo modo, si empty() retorna False no garantiza que una llamada posterior a get() no se bloquee.

Queue.full()

Retorna True si la cola está llena, False si no. Si full() retorna True no garantiza que una llamada posterior a get() no se bloquee. Del mismo modo, si full() retorna False no garantiza que una llamada posterior a put() no se bloquee.

Queue.put(item, block=True, timeout=None)

Pone el item en la cola. Si el argumento opcional block es verdadero y timeout es None (el predeterminado), bloquea si es necesario hasta que un espacio libre esté disponible. Si timeout es un número positivo, bloquea como máximo timeout segundos y aumenta la excepción Full si no había ningún espacio libre disponible en ese tiempo. De lo contrario (block es falso), pone un elemento en la cola si un espacio libre está disponible inmediatamente, o bien levanta la excepción Full (timeout es ignorado en ese caso).

Queue.put_nowait(item)

Equivalent to put(item, block=False).

Queue.get(block=True, timeout=None)

Retira y retorna un elemento de la cola. Si el argumento opcional block es verdadero y timeout es None (el predeterminado), bloquea si es necesario hasta que un elemento esté disponible. Si timeout es un número positivo, bloquea como máximo timeout segundos y aumenta la excepción Empty si no había ningún elemento disponible en ese tiempo. De lo contrario (block es falso), retorna un elemento si uno está disponible inmediatamente, o bien lanza la excepción Empty (timeout es ignorado en ese caso).

Antes de la 3.0 en los sistemas POSIX, y para todas las versiones en Windows, si block es verdadero y timeout es None, esta operación entra en una espera ininterrumpida en una cerradura subyacente. Esto significa que no puede haber excepciones, y en particular una SIGINT no disparará una KeyboardInterrupt.

Queue.get_nowait()

Equivalente a get(False).

Se ofrecen dos métodos para apoyar el seguimiento si las tareas en cola han sido completamente procesadas por hilos daemon de consumo.

Queue.task_done()

Indica que una tarea anteriormente en cola está completa. Utilizado por los hilos de la cola de consumo. Por cada get() usado para recuperar una tarea, una llamada posterior a task_done() le dice a la cola que el procesamiento de la tarea está completo.

Si un join() se está bloqueando actualmente, se reanudará cuando todos los ítems hayan sido procesados (lo que significa que se recibió una llamada task_done() por cada ítem que había sido put() en la cola).

Lanza un ValueError si se llama más veces de las que hay elementos colocados en la cola.

Queue.join()

Bloquea hasta que todos los artículos de la cola se hayan obtenido y procesado.

El conteo de tareas sin terminar sube cada vez que se añade un elemento a la cola. El conteo baja cuando un hilo de consumidor llama task_done() para indicar que el elemento fue recuperado y todo el trabajo en él está completo. Cuando el conteo de tareas sin terminar cae a cero, join() se desbloquea.

Ejemplo de cómo esperar a que se completen las tareas en cola:

import threading, queue

q = queue.Queue()

def worker():
    while True:
        item = q.get()
        print(f'Working on {item}')
        print(f'Finished {item}')
        q.task_done()

# turn-on the worker thread
threading.Thread(target=worker, daemon=True).start()

# send thirty task requests to the worker
for item in range(30):
    q.put(item)
print('All task requests sent\n', end='')

# block until all tasks are done
q.join()
print('All work completed')

Objetos de cola simple

Los objetos SimpleQueue proporcionan los métodos públicos descritos a continuación.

SimpleQueue.qsize()

Retorna el tamaño aproximado de la cola. Nota, qsize() > 0 no garantiza que un get() posterior no se bloquee.

SimpleQueue.empty()

Retorna True si la cola está vacía, False si no. Si empty() retorna False no garantiza que una llamada posterior a get() no se bloquee.

SimpleQueue.put(item, block=True, timeout=None)

Pone el elemento en la cola. El método nunca se bloquea y siempre tiene éxito (excepto por posibles errores de bajo nivel como la falta de asignación de memoria). Los argumentos opcionales block y timeout son ignorados y sólo se proporcionan por compatibilidad con Queue.put().

CPython implementation detail: This method has a C implementation which is reentrant. That is, a put() or get() call can be interrupted by another put() call in the same thread without deadlocking or corrupting internal state inside the queue. This makes it appropriate for use in destructors such as __del__ methods or weakref callbacks.

SimpleQueue.put_nowait(item)

Equivalent to put(item, block=False), provided for compatibility with Queue.put_nowait().

SimpleQueue.get(block=True, timeout=None)

Retira y retorna un elemento de la cola. Si los argumentos opcionales block son true y timeout es None (el predeterminado), bloquea si es necesario hasta que un elemento esté disponible. Si timeout es un número positivo, bloquea como máximo timeout segundos y lanza la excepción Empty si no había ningún elemento disponible en ese tiempo. De lo contrario (block es falso), retorna un elemento si uno está disponible inmediatamente, o bien lanza la excepción Empty (timeout es ignorado en ese caso).

SimpleQueue.get_nowait()

Equivalente a get(False).

Ver también

Clase multiprocessing.Queue

Una clase de cola para su uso en un contexto de multiprocesamiento (en lugar de multihilo).

collections.deque es una implementación alternativa de colas sin límites con operaciones atómicas rápidas append() y popleft() que no requieren bloqueo y también soportan indexación.

contextvars — Variables de Contexto

Este módulo proporciona APIs para gestionar, almacenar y acceder a estados en el contexto local. La clase ContextVar se utiliza para declarar y trabajar con Variables de Contexto (Context Variables). La función copy_context() y la clase Context deberían ser utilizadas para gestionar el contexto actual en frameworks asíncronos.

Los gestores de contexto que tienen un estado establecido deberían utilizar Variables de Contexto en lugar de threading.local(), para así evitar que este estado se inyecte inesperadamente a otro código, cuando se utilice en código concurrente.

Ver PEP 567 [https://www.python.org/dev/peps/pep-0567] para más detalles.

Nuevo en la versión 3.7.

Variables de Contexto

class contextvars.ContextVar(name[, *, default])

Esta clase se utiliza para declarar una nueva Variable de Contexto, por ejemplo:

var: ContextVar[int] = ContextVar('var', default=42)

El parámetro obligatorio name se utiliza para introspección y depuración.

El parámetro opcional de sólo palabra clave default es utilizado por ContextVar.get(), cuando en el contexto actual no se encuentra ningún valor para la variable.

Importante: las Variables de Contexto deberían ser creadas en lo más alto a nivel de módulo y nunca en clausura. Los objetos Context mantienen referencias a variables de contexto, lo cual no permitiría que estas variables de contexto sean limpiadas por el recolector de basura.

name

El nombre de la variable. Propiedad de sólo lectura.

Nuevo en la versión 3.7.1.

get([default])

Retorna un valor para la variable de contexto en el contexto actual.

Si la variable no tiene ningún valor en el contexto actual, el método:

retornará el valor del argumento default del método, si alguno fue dado; o

retornará el valor por defecto de la variable de contexto, si ésta fue creada con alguno; o

lanzará LookupError.

set(value)

Establece un nuevo valor para la variable de contexto en el contexto actual.

El argumento obligatorio value es el nuevo valor de la variable de contexto.

Retorna un objeto Token que puede utilizarse para restaurar la variable a su valor anterior, utilizando el método ContextVar.reset().

reset(token)

Restablece la variable de contexto al valor que tenía antes de llamar al método ContextVar.set(), que creó el token utilizado.

Por ejemplo:

var = ContextVar('var')

token = var.set('new value')
# code that uses 'var'; var.get() returns 'new value'.
var.reset(token)

# After the reset call the var has no value again, so
# var.get() would raise a LookupError.

class contextvars.Token

Los objetos token son retornados por el método ContextVar.set(). Se le pueden dar al método ContextVar.reset() para restablecer el valor de la variable al que estuviese dado antes del set correspondiente.

var

Propiedad de sólo lectura. Apunta al objeto ContextVar que creó el token.

old_value

Propiedad de sólo lectura. Es el valor que la variable tenía antes de llamar al método ContextVar.set() que creó el token. Apunta a Token.MISSING si la variable no estaba establecida antes de la llamada.

MISSING

Marcador utilizado por Token.old_value.

Gestión de Contexto Manual

contextvars.copy_context()

Retorna una copia del objeto Context actual.

El siguiente código obtiene una copia del contexto actual e imprime todas las variables y sus valores establecidos en el contexto:

ctx: Context = copy_context()
print(list(ctx.items()))

La función tiene una complejidad de O(1); es decir, trabaja a la misma velocidad en contextos con pocas o con muchas variables de contexto.

class contextvars.Context

Mapeo de ContextVars con sus valores.

Context() crea un contexto vacío sin valores. Para obtener una copia del contexto actual, se puede utilizar la función copy_context().

Every thread will have a different top-level Context object. This means that a ContextVar object behaves in a similar fashion to threading.local() when values are assigned in different threads.

Context implementa la interfaz collections.abc.Mapping.

run(callable, *args, **kwargs)

Ejecuta el código de callable(*args, **kwargs) en el objeto de contexto del cual se llama al método run. Retorna el resultado de la ejecución, o propaga una excepción si alguna ocurre.

Cualquier cambio realizado por callable sobre cualquier variable de contexto será contenido en el objeto de contexto:

var = ContextVar('var')
var.set('spam')

def main():
    # 'var' was set to 'spam' before
    # calling 'copy_context()' and 'ctx.run(main)', so:
    # var.get() == ctx[var] == 'spam'

    var.set('ham')

    # Now, after setting 'var' to 'ham':
    # var.get() == ctx[var] == 'ham'

ctx = copy_context()

# Any changes that the 'main' function makes to 'var'
# will be contained in 'ctx'.
ctx.run(main)

# The 'main()' function was run in the 'ctx' context,
# so changes to 'var' are contained in it:
# ctx[var] == 'ham'

# However, outside of 'ctx', 'var' is still set to 'spam':
# var.get() == 'spam'

El método lanzará RuntimeError cuando es llamado desde el mismo objeto de contexto desde más de un hilo del sistema operativo, o si se llama recursivamente.

copy()

Retorna una copia superficial (shallow copy) del objeto de contexto.

var in context

Retorna True si context tiene un valor establecido para var; de lo contrario, retorna False.

context[var]

Retorna el valor de la variable ContextVar var. Si la variable no está establecida en el contexto actual, se lanzará KeyError.

get(var[, default])

Retorna el valor de var, si var tiene el valor en el objeto de contexto; de lo contrario, retorna default. Si default no es dado, retorna None.

iter(context)

Retorna un iterador de las variables almacenadas en el objeto de contexto.

len(proxy)

Retorna el número de variables establecidas en el objeto de contexto.

keys()

Retorna un listado de todas las variables en el objeto de contexto.

values()

Retorna un listado de los valores de todas las variables en el objeto de contexto.

items()

Retorna un listado de dos tuplas que contienen todas las variables y sus variables en el contexto actual.

Soporte asyncio

Las variables de contexto están soportadas de forma nativa en asyncio y se pueden utilizar sin ninguna configuración adicional. Por ejemplo, el siguiente código crea un servidor simple de respuesta, que utiliza una variable de contexto que hace que la dirección del cliente remoto esté disponible en la Task que gestiona al cliente:

import asyncio
import contextvars

client_addr_var = contextvars.ContextVar('client_addr')

def render_goodbye():
    # The address of the currently handled client can be accessed
    # without passing it explicitly to this function.

    client_addr = client_addr_var.get()
    return f'Good bye, client @ {client_addr}\n'.encode()

async def handle_request(reader, writer):
    addr = writer.transport.get_extra_info('socket').getpeername()
    client_addr_var.set(addr)

    # In any code that we call is now possible to get
    # client's address by calling 'client_addr_var.get()'.

    while True:
        line = await reader.readline()
        print(line)
        if not line.strip():
            break
        writer.write(line)

    writer.write(render_goodbye())
    writer.close()

async def main():
    srv = await asyncio.start_server(
        handle_request, '127.0.0.1', 8081)

    async with srv:
        await srv.serve_forever()

asyncio.run(main())

# To test it you can use telnet:
#     telnet 127.0.0.1 8081

_thread — API de bajo nivel para manejo de hilos

Este módulo ofrece primitivas de bajo nivel para trabajar con múltiples threads o hilos (también llamados light-weight processes o tasks) – múltiples hilos de control compartiendo su espacio de datos global. Para sincronizar, provee «candados» simples (también llamados mutexes o binary semaphores). El módulo threading provee una API de manejo de hilos más fácil de usar y de más alto nivel, construida sobre este módulo.

Distinto en la versión 3.7: Este módulo solía ser opcional, pero ahora está siempre disponible.

Este módulo define las siguientes constantes y funciones:

exception _thread.error

Lanzado ante errores específicos de un hilo.

Distinto en la versión 3.3: Ahora es un sinónimo de la excepción incorporada RuntimeError.

_thread.LockType

Este es el tipo de los objetos candado (lock objects).

_thread.start_new_thread(function, args[, kwargs])

Inicia un nuevo hilo y retorna su identificador. El hilo ejecuta la función function con la lista de argumentos args (que debe ser una tupla). El argumento opcional kwargs especifica un diccionario de argumentos por palabras clave.

Cuando la función retorna, el hilo finaliza silenciosamente.

Cuando la función termina con una excepción no gestionada, se invoca a sys.unraisablehook() para que gestione la excepción. El atributo object del argumento gancho (hook), es function. Por defecto, se muestra un seguimiento de pila y luego el hilo sale (pero los otros hilos continúan funcionando).

Cuando la función lanza una excepción SystemExit, se ignora silenciosamente.

Distinto en la versión 3.8: Ahora se utiliza sys.unraisablehook() para gestionar las excepciones no gestionadas.

_thread.interrupt_main()

Simular el efecto de una señal signal.SIGINT que llega al hilo principal. Un hilo puede usar esta función para interrumpir el hilo principal.

Si signal.SIGINT no está gestionada por Python (se definió signal.SIG_DFL o signal.SIG_IGN), esta función no hace nada.

_thread.exit()

Lanza la excepción SystemExit. Cuando no es gestionada, causa que el hilo salga silenciosamente.

_thread.allocate_lock()

Retorna un nuevo objeto candado (lock object). Los métodos de los candados se describen más abajo. El candado está abierto al inicio.

_thread.get_ident()

Retorna el “identificador de hilo” (thread identifier) del hilo actual. Es un entero distinto de cero. Su valor no tiene un significado directo, tiene la intención de ser utilizada como una cookie mágica para, por ejemplo, indexar un diccionario con datos específicos del hilo. Los identificadores de hilo pueden reciclarse cuando un hilo sale y otro se crea.

_thread.get_native_id()

Retorna el ID de hilo nativo integral del hilo asignado por el kernel. Es un entero no-negativo. Su valor puede utilizarse para identificar inequívocamente este hilo en particular en todo el sistema (hasta que el hilo termine, luego de lo cual el valor puede ser reciclado por el Sistema Operativo).

Disponibilidad: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX.

Nuevo en la versión 3.8.

_thread.stack_size([size])

Retorna el tamaño de la pila del hilo (thread stack) utilizada al crear nuevos hilos. El argumento opcional size especifica el tamaño de la pila a utilizar en los hilos que se creen a continuación, y debe ser 0 (utiliza el valor por defecto de la plataforma o el configurado) o un entero positivo de al menos 32768 (32KiB). Si size no se especifica, se utiliza 0. Si no está soportado el cambio del tamaño de pila del hilo, se lanza una excepción RuntimeError. Si la pila especificada es inválida se lanza un ValueError y el tamaño de la pila no se modifica. 32KiB es actualmente el menor valor soportado para el tamaño de la pila, para garantizar suficiente espacio en la misma para que quepa el propio intérprete. Tenga en cuenta que alguna plataformas pueden tener restricciones particulares en los valores para el tamaño de la pila, como requerir un mínimo que supere los 32KiB, o requerir una asignación en múltiplos del tamaño de página de memoria del sistema. Es necesario consultar la documentación de la plataforma para mayor información (son habituales las páginas de 4KiB; usar múltiplos de 4096 para el tamaño de pila es la estrategia sugerida si no se cuenta con información más específica).

Disponibilidad: Sistemas Windows, con hilos POSIX.

_thread.TIMEOUT_MAX

El máximo valor permitido para el parámetro timeout de Lock.acquire(). Especificar un tiempo de espera (timeout) mayor que este valor lanzará una excepción OverflowError.

Nuevo en la versión 3.2.

Los objetos candado (lock objects) tienen los siguientes métodos:

lock.acquire(waitflag=1, timeout=-1)

Sin ningún argumento opcional, este método adquiere el candado incondicionalmente, si es necesario esperando que éste sea liberado por otro hilo (solamente un hilo por vez puede adquirir un candado; para eso existen).

Si el argumento entero waitflag está presente, la acción depende de su valor: si es cero, el candado solamente es adquirido si está disponible de forma inmediata, sin esperas. Mientras que si es distinto de cero, el candado es adquirido sin condiciones, como en el caso anterior.

Si el argumento de punto flotante timeout está presente y es positivo, especifica el tiempo máximo de espera en segundos antes de retornar. Un argumento timeout negativo, especifica una espera ilimitada. No se puede especificar un timeout si waitflag es cero.

El valor de retorno es True si el candado (lock) se adquirió exitosamente, False de lo contrario.

Distinto en la versión 3.2: El parámetro timeout es nuevo.

Distinto en la versión 3.2: La adquisición de candados ahora puede ser interrumpida por señales en POSIX.

lock.release()

Libera el candado. El candado debe haber sido adquirido previamente, pero no necesariamente por el mismo hilo.

lock.locked()

Retorna el estado del candado: True si ha sido adquirido por algún hilo, False de lo contrario.

Además de estos métodos, los objetos candado pueden ser utilizados mediante la declaración with, por ejemplo:

import _thread

a_lock = _thread.allocate_lock()

with a_lock:
    print("a_lock is locked while this executes")

Salvedades:

Los hilos interactúan de manera extraña con interrupciones: la excepción KeyboardInterrupt va a ser recibida por un hilo cualquiera. (Cuando el módulo signal está disponible, la interrupción siempre se dirige al hilo principal.

Invocar a sys.exit() o lanzar la excepción SystemExit equivale a invocar _thread.exit().

No es posible interrumpir el método acquire() en un candado. La excepción KeyboardInterrupt tendrá lugar después de que el candado haya sido adquirido.

Cuando el hilo principal sale, ¿sobreviven los otros hilos? Depende de cómo esté definido por el sistema. En la mayoría de los sistemas, los hilos se cierran inmediatamente (killed), sin ejecutar las cláusulas try … finally o los destructores del objeto.

Cuando el hilo principal sale, no hace ninguna de las tareas de limpieza habituales (excepto que se haga honor a las cláusulas try … finally), y los archivos de E/S estándar no son liberados.

Comunicación en redes y entre procesos

Los módulos descritos en este capítulo proveen los mecanismos para la comunicación en red y entre procesos.

Algunos módulos solo funcionan para dos procesos que están en una misma máquina, e.g. signal y mmap. Otros módulos soportan protocolos de red que dos o mas procesos pueden utilizar para comunicarse entre máquinas.

La lista de módulos descritos en este capítulo es:

asyncio — E/S Asíncrona

socket — interfaz de red de bajo nivel

ssl —Empaquetador o wrapper TLS/SSL para objetos de tipo socket

select — Esperando la finalización de E/S

selectors — Multiplexación de E/S de alto nivel

signal — Establece gestores para eventos asíncronos

mmap — Soporte de archivos mapeados en memoria

asyncio — E/S Asíncrona

¡Hola Mundo!

import asyncio

async def main():
    print('Hello ...')
    await asyncio.sleep(1)
    print('... World!')

asyncio.run(main())

asyncio es una biblioteca para escribir código concurrente utilizando la sintaxis async/await.

asyncio es utilizado como base en múltiples frameworks asíncronos de Python y provee un alto rendimiento en redes y servidores web, bibliotecas de conexión de base de datos, colas de tareas distribuidas, etc.

asyncio suele encajar perfectamente para operaciones con límite de E/S y código de red estructurado de alto nivel.

asyncio provee un conjunto de APIs de alto nivel para:

ejecutar corutinas de Python de manera concurrente y tener control total sobre su ejecución;

realizar redes E/S y comunicación entre procesos(IPC);

controlar subprocesos;

distribuir tareas a través de colas;

sincronizar código concurrente;

Adicionalmente, existen APIs de bajo nivel para desarrolladores de bibliotecas y frameworks para:

crear y administrar bucles de eventos, los cuales proveen APIs asíncronas para redes, ejecutando subprocesos, gestionando señales del sistema operativo, etc;

implementar protocolos eficientes utilizando transportes;

Bibliotecas puente basadas en retrollamadas y código con sintaxis async/wait.

Referencias

*APIs* de alto nivel

Corrutinas y Tareas

Streams

Primitivas de sincronización

Sub-procesos

Colas

Excepciones

*APIs* de bajo nivel

Bucle de eventos

Futures

Transportes y protocolos

Políticas

Soporte de plataforma

Guías y tutoriales

Índice de API de alto nivel

Índice de API de bajo nivel

Desarrollando con asyncio

Nota

El código fuente para asyncio puede encontrarse en Lib/asyncio/ [https://github.com/python/cpython/tree/3.9/Lib/asyncio/].

Corrutinas y Tareas

Esta sección describe las API de asyncio de alto nivel para trabajar con corrutinas y tareas.

Corrutinas

Esperables

Ejecutando un programa asyncio

Creando Tareas

Durmiendo

Ejecutando Tareas Concurrentemente

Protección contra Cancelación

Tiempo agotado

Esperando Primitivas

Ejecutando en Hilos

Planificación Desde Otros Hilos

Introspección

Objeto Task

Corrutinas basadas en generadores

Corrutinas

Coroutines declared with the async/await syntax is the preferred way of writing asyncio applications. For example, the following snippet of code prints «hello», waits 1 second, and then prints «world»:

>>> import asyncio

>>> async def main():
...     print('hello')
...     await asyncio.sleep(1)
...     print('world')

>>> asyncio.run(main())
hello
world

Tenga en cuenta que simplemente llamando a una corrutina no programará para que se ejecute:

>>> main()
<coroutine object main at 0x1053bb7c8>

Para ejecutar realmente una corrutina, asyncio proporciona tres mecanismos principales:

La función asyncio.run() para ejecutar la función de punto de entrada de nivel superior «main()» (consulte el ejemplo anterior.)

Esperando en una corrutina. El siguiente fragmento de código imprimirá «hola» después de esperar 1 segundo y luego imprimirá «mundo» después de esperar otros 2 segundos:

import asyncio
import time

async def say_after(delay, what):
    await asyncio.sleep(delay)
    print(what)

async def main():
    print(f"started at {time.strftime('%X')}")

    await say_after(1, 'hello')
    await say_after(2, 'world')

    print(f"finished at {time.strftime('%X')}")

asyncio.run(main())

Salida esperada:

started at 17:13:52
hello
world
finished at 17:13:55

La función asyncio.create_task() para ejecutar corrutinas concurrentemente como asyncio Tasks.

Modifiquemos el ejemplo anterior y ejecutemos dos corrutinas say_after concurrentemente:

async def main():
    task1 = asyncio.create_task(
        say_after(1, 'hello'))

    task2 = asyncio.create_task(
        say_after(2, 'world'))

    print(f"started at {time.strftime('%X')}")

    # Wait until both tasks are completed (should take
    # around 2 seconds.)
    await task1
    await task2

    print(f"finished at {time.strftime('%X')}")

Tenga en cuenta que la salida esperada ahora muestra que el fragmento de código se ejecuta 1 segundo más rápido que antes:

started at 17:14:32
hello
world
finished at 17:14:34

Esperables

Decimos que un objeto es un objeto esperable si se puede utilizar en una expresión await. Muchas API de asyncio están diseñadas para aceptar los valores esperables.

Hay tres tipos principales de objetos esperables: corrutinas, Tareas y Futuros.

Corrutinas

Las corrutinas de Python son esperables y por lo tanto se pueden esperar de otras corrutinas:

import asyncio

async def nested():
    return 42

async def main():
    # Nothing happens if we just call "nested()".
    # A coroutine object is created but not awaited,
    # so it *won't run at all*.
    nested()

    # Let's do it differently now and await it:
    print(await nested())  # will print "42".

asyncio.run(main())

Importante

En esta documentación se puede utilizar el término «corrutina» para dos conceptos estrechamente relacionados:

una función corrutina: una función async def;

un objeto corrutina: un objeto retornado llamando a una función corrutina.

asyncio también es compatible con corrutinas heredadas generator-based.

Tareas

Las tareas se utilizan para programar corrutinas concurrentemente.

Cuando una corrutina se envuelve en una Tarea con funciones como asyncio.create_task() la corrutina se programa automáticamente para ejecutarse pronto:

import asyncio

async def nested():
    return 42

async def main():
    # Schedule nested() to run soon concurrently
    # with "main()".
    task = asyncio.create_task(nested())

    # "task" can now be used to cancel "nested()", or
    # can simply be awaited to wait until it is complete:
    await task

asyncio.run(main())

Futuros

Un Future es un objeto esperable especial de bajo-nivel que representa un resultado eventual de una operación asíncrona.

Cuando un objeto Future es esperado significa que la corrutina esperará hasta que el Future se resuelva en algún otro lugar.

Los objetos Future de asyncio son necesarios para permitir que el código basado en retro llamada se use con async/await.

Normalmente , no es necesario crear objetos Future en el código de nivel de aplicación.

Los objetos Future, a veces expuestos por bibliotecas y algunas API de asyncio, pueden ser esperados:

async def main():
    await function_that_returns_a_future_object()

    # this is also valid:
    await asyncio.gather(
        function_that_returns_a_future_object(),
        some_python_coroutine()
    )

Un buen ejemplo de una función de bajo nivel que retorna un objeto Future es loop.run_in_executor().

Ejecutando un programa asyncio

asyncio.run(coro, *, debug=False)

Ejecuta la coroutine coro y retornando el resultado.

Esta función ejecuta la corrutina pasada, encargándose de administrar el bucle de eventos asyncio, finalizing asynchronous generators y cerrando el threadpool.

Esta función no se puede llamar cuando otro bucle de eventos asyncio se está ejecutando en el mismo hilo.

Si debug es True, el bucle de eventos se ejecutará en modo debug.

Esta función siempre crea un nuevo ciclo de eventos y lo cierra al final. Debe usarse como un punto de entrada principal para los programas asyncio, e idealmente solo debe llamarse una vez.

Ejemplo:

async def main():
    await asyncio.sleep(1)
    print('hello')

asyncio.run(main())

Nuevo en la versión 3.7.

Distinto en la versión 3.9: Actualizado para usar loop.shutdown_default_executor().

Nota

El código fuente para asyncio.run() se puede encontrar en Lib/asyncio/runners.py [https://github.com/python/cpython/tree/3.9/Lib/asyncio/runners.py].

Creando Tareas

asyncio.create_task(coro, *, name=None)

Envuelve una coroutine coro en una Task y programa su ejecución. Retorna el objeto Tarea.

Si name no es None, se establece como el nombre de la tarea mediante Task.set_name().

La tarea se ejecuta en el bucle retornado por get_running_loop(), RuntimeError se genera si no hay ningún bucle en ejecución en el subproceso actual.

Importante

Save a reference to the result of this function, to avoid a task disappearing mid execution.

Nuevo en la versión 3.7.

Distinto en la versión 3.8: Se ha añadido el parámetro name.

Durmiendo

coroutine asyncio.sleep(delay, result=None, *, loop=None)

Bloquea por delay segundos.

Si se proporciona result, se retorna al autor de la llamada cuando se completa la corrutina.

sleep() siempre suspende la tarea actual, permitiendo que se ejecuten otras tareas.

Setting the delay to 0 provides an optimized path to allow other tasks to run. This can be used by long-running functions to avoid blocking the event loop for the full duration of the function call.

Deprecated since version 3.8, will be removed in version 3.10: El parámetro loop.

Ejemplo de una rutina que muestra la fecha actual cada segundo durante 5 segundos:

import asyncio
import datetime

async def display_date():
    loop = asyncio.get_running_loop()
    end_time = loop.time() + 5.0
    while True:
        print(datetime.datetime.now())
        if (loop.time() + 1.0) >= end_time:
            break
        await asyncio.sleep(1)

asyncio.run(display_date())

Ejecutando Tareas Concurrentemente

awaitable asyncio.gather(*aws, loop=None, return_exceptions=False)

Ejecute objetos esperables en la secuencia aws de forma concurrently.

Si cualquier esperable en aws es una corrutina, se programa automáticamente como una Tarea.

Si todos los esperables se completan correctamente, el resultado es una lista agregada de valores retornados. El orden de los valores de resultado corresponde al orden de esperables en aws.

Si return_exceptions es False (valor predeterminado), la primera excepción provocada se propaga inmediatamente a la tarea que espera en gather(). Otros esperables en la secuencia aws no se cancelarán y continuarán ejecutándose.

Si return_exceptions es True, las excepciones se tratan igual que los resultados correctos y se agregan en la lista de resultados.

Si gather() es cancelado, todos los esperables enviados (que aún no se han completado) también se cancelan.

Si alguna Tarea o Futuro de la secuencia aws se cancela, se trata como si se lanzara CancelledError – la llamada gather() no se cancela en este caso. Esto es para evitar la cancelación de una Tarea/Futuro enviada para hacer que otras Tareas/Futuros sean canceladas.

Deprecated since version 3.8, will be removed in version 3.10: El parámetro loop.

Ejemplo:

import asyncio

async def factorial(name, number):
    f = 1
    for i in range(2, number + 1):
        print(f"Task {name}: Compute factorial({number}), currently i={i}...")
        await asyncio.sleep(1)
        f *= i
    print(f"Task {name}: factorial({number}) = {f}")
    return f

async def main():
    # Schedule three calls *concurrently*:
    L = await asyncio.gather(
        factorial("A", 2),
        factorial("B", 3),
        factorial("C", 4),
    )
    print(L)

asyncio.run(main())

# Expected output:
#
#     Task A: Compute factorial(2), currently i=2...
#     Task B: Compute factorial(3), currently i=2...
#     Task C: Compute factorial(4), currently i=2...
#     Task A: factorial(2) = 2
#     Task B: Compute factorial(3), currently i=3...
#     Task C: Compute factorial(4), currently i=3...
#     Task B: factorial(3) = 6
#     Task C: Compute factorial(4), currently i=4...
#     Task C: factorial(4) = 24
#     [2, 6, 24]

Nota

Si return_exceptions es False, cancelar gather() después de que se haya marcado como hecho no cancelará ninguna espera enviada. Por ejemplo, la recopilación se puede marcar como hecha después de propagar una excepción a la persona que llama, por lo tanto, llamar a gather.cancel() después de detectar una excepción (generada por uno de los elementos pendientes) de recopilación no cancelará ningún otro elemento pendiente.

Distinto en la versión 3.7: Si se cancela el propio gather, la cancelación se propaga independientemente de return_exceptions.

Protección contra Cancelación

awaitable asyncio.shield(aw, *, loop=None)

Protege un objeto esperable de ser cancelado.

Si aw es una corrutina, se programa automáticamente como una Tarea.

La declaración:

res = await shield(something())

es equivalente a:

res = await something()

excepto que si la corrutina que lo contiene se cancela, la tarea que se ejecuta en something() no se cancela. Desde el punto de vista de something(), la cancelación no ocurrió. Aunque su invocador siga cancelado, por lo que la expresión «await» sigue generando un CancelledError.

Si something() se cancela por otros medios (es decir, desde dentro de sí mismo) eso también cancelaría shield().

Si se desea ignorar por completo la cancelación (no se recomienda) la función shield() debe combinarse con una cláusula try/except, como se indica a continuación:

try:
    res = await shield(something())
except CancelledError:
    res = None

Deprecated since version 3.8, will be removed in version 3.10: El parámetro loop.

Tiempo agotado

coroutine asyncio.wait_for(aw, timeout, *, loop=None)

Espere a que el aw esperable se complete con un tiempo agotado.

Si aw es una corrutina, se programa automáticamente como una Tarea.

timeout puede ser None o punto flotante o un número entero de segundos a esperar. Si timeout es None, se bloquea hasta que futuro se complete.

Si se produce un agotamiento de tiempo, cancela la tarea y genera asyncio.TimeoutError.

Para evitar la cancelación de la tarea , envuélvala en shield().

La función esperará hasta que se cancele el futuro, por lo que el tiempo de espera total puede exceder el timeout. Si ocurre una excepción durante la cancelación, se propaga.

Si se cancela la espera, el futuro aw también se cancela.

Deprecated since version 3.8, will be removed in version 3.10: El parámetro loop.

Ejemplo:

async def eternity():
    # Sleep for one hour
    await asyncio.sleep(3600)
    print('yay!')

async def main():
    # Wait for at most 1 second
    try:
        await asyncio.wait_for(eternity(), timeout=1.0)
    except asyncio.TimeoutError:
        print('timeout!')

asyncio.run(main())

# Expected output:
#
#     timeout!

Distinto en la versión 3.7: Cuando aw se cancela debido a un agotamiento de tiempo, wait_for espera a que se cancele aw. Anteriormente, se lanzó inmediatamente asyncio.TimeoutError.

Esperando Primitivas

coroutine asyncio.wait(aws, *, loop=None, timeout=None, return_when=ALL_COMPLETED)

Ejecuta objetos en espera en el aws iterable simultáneamente y bloquee hasta la condición especificada por return_when.

El iterable aws no debe estar vacío.

Retorna dos conjuntos de Tareas/Futuros: (done, pending).

Uso:

done, pending = await asyncio.wait(aws)

timeout (un punto flotante o int), si se especifica, se puede utilizar para controlar el número máximo de segundos que hay que esperar antes de retornar.

Tenga en cuenta que esta función no lanza asyncio.TimeoutError. Los Futuros o Tareas que no terminan cuando se agota el tiempo simplemente se retornan en el segundo conjunto.

return_when indica cuándo debe retornar esta función. Debe ser una de las siguientes constantes:

Constante

Descripción

FIRST_COMPLETED

La función retornará cuando cualquier Futuro termine o se cancele.

FIRST_EXCEPTION

La función retornará cuando cualquier Futuro finalice lanzando una excepción. Si ningún Futuro lanza una excepción, entonces es equivalente a ALL_COMPLETED.

ALL_COMPLETED

La función retornará cuando todos los Futuros terminen o se cancelen.

A diferencia de wait_for(), wait() no cancela los Futuros cuando se produce un agotamiento de tiempo.

Obsoleto desde la versión 3.8: Si cualquier aguardable en aws es una corrutina, se programa automáticamente como una Tarea. El paso de objetos corrutinas a wait() directamente está en desuso, ya que conduce a comportamiento confuso.

Deprecated since version 3.8, will be removed in version 3.10: El parámetro loop.

Nota

wait() programa las corrutinas como Tareas automáticamente y posteriormente retorna los objetos Tarea creados implícitamente en conjuntos (done, pending). Por lo tanto, el código siguiente no funcionará como se esperaba:

async def foo():
    return 42

coro = foo()
done, pending = await asyncio.wait({coro})

if coro in done:
    # This branch will never be run!

Aquí es cómo se puede arreglar el fragmento de código anterior:

async def foo():
    return 42

task = asyncio.create_task(foo())
done, pending = await asyncio.wait({task})

if task in done:
    # Everything will work as expected now.

Deprecated since version 3.8, will be removed in version 3.11: El paso de objetos corrutina a wait() directamente está en desuso.

asyncio.as_completed(aws, *, loop=None, timeout=None)

Ejecuta objetos en espera en el aws iterable al mismo tiempo. Devuelve un iterador de corrutinas. Se puede esperar a cada corrutina devuelta para obtener el siguiente resultado más temprano del iterable de los esperables restantes.

Lanza asyncio.TimeoutError si el agotamiento de tiempo ocurre antes que todos los Futuros terminen.

Deprecated since version 3.8, will be removed in version 3.10: El parámetro loop.

Ejemplo:

for coro in as_completed(aws):
    earliest_result = await coro
    # ...

Ejecutando en Hilos

coroutine asyncio.to_thread(func, /, *args, **kwargs)

Ejecutar asincrónicamente la función func en un hilo separado.

Cualquier *args y **kwargs suministrados para esta función se pasan directamente a func. Además, el current contextvars.Context se propaga, lo que permite acceder a las variables de contexto del subproceso del bucle de eventos en el subproceso separado.

Retorna una corrutina que se puede esperar para obtener el resultado final de func.

Esta función de corrutina está destinada principalmente a ser utilizada para ejecutar funciones/métodos vinculados a IO que de otro modo bloquearían el bucle de eventos si se ejecutaran en el hilo principal. Por ejemplo:

def blocking_io():
    print(f"start blocking_io at {time.strftime('%X')}")
    # Note that time.sleep() can be replaced with any blocking
    # IO-bound operation, such as file operations.
    time.sleep(1)
    print(f"blocking_io complete at {time.strftime('%X')}")

async def main():
    print(f"started main at {time.strftime('%X')}")

    await asyncio.gather(
        asyncio.to_thread(blocking_io),
        asyncio.sleep(1))

    print(f"finished main at {time.strftime('%X')}")

asyncio.run(main())

# Expected output:
#
# started main at 19:50:53
# start blocking_io at 19:50:53
# blocking_io complete at 19:50:54
# finished main at 19:50:54

Llamando directamente a blocking_io() en cualquier corrutina bloquearía el bucle de eventos por su duración, lo que daría como resultado 1 segundo adicional de tiempo de ejecución. En cambio, usando asyncio.to_thread(), podemos ejecutarlo en un hilo separado sin bloquear el bucle de eventos.

Nota

Debido al GIL, asyncio.to_thread() normalmente solo se puede usar para hacer que las funciones vinculadas a IO no bloqueen. Sin embargo, para los módulos de extensión que lanzan GIL o implementaciones alternativas de Python que no tienen una, asyncio.to_thread() también se puede usar para funciones vinculadas a la CPU.

Nuevo en la versión 3.9.

Planificación Desde Otros Hilos

asyncio.run_coroutine_threadsafe(coro, loop)

Envía una corrutina al bucle de eventos especificado. Seguro para Hilos.

Retorna concurrent.futures.Future para esperar el resultado de otro hilo del SO (Sistema Operativo).

Esta función está pensada para llamarse desde un hilo del SO diferente al que se ejecuta el bucle de eventos. Ejemplo:

# Create a coroutine
coro = asyncio.sleep(1, result=3)

# Submit the coroutine to a given loop
future = asyncio.run_coroutine_threadsafe(coro, loop)

# Wait for the result with an optional timeout argument
assert future.result(timeout) == 3

Si se lanza una excepción en la corrutina, el Futuro retornado será notificado. También se puede utilizar para cancelar la tarea en el bucle de eventos:

try:
    result = future.result(timeout)
except asyncio.TimeoutError:
    print('The coroutine took too long, cancelling the task...')
    future.cancel()
except Exception as exc:
    print(f'The coroutine raised an exception: {exc!r}')
else:
    print(f'The coroutine returned: {result!r}')

Consulte la sección de la documentación Concurrencia y multi hilos.

A diferencia de otras funciones asyncio, esta función requiere que el argumento loop se pase explícitamente.

Nuevo en la versión 3.5.1.

Introspección

asyncio.current_task(loop=None)

Retorna la instancia Task actualmente en ejecución o None si no se está ejecutando ninguna tarea.

Si loop es None get_running_loop() se utiliza para obtener el bucle actual.

Nuevo en la versión 3.7.

asyncio.all_tasks(loop=None)

Retorna un conjunto de objetos Task que se ejecutan por el bucle.

Si loop es None, get_running_loop() se utiliza para obtener el bucle actual.

Nuevo en la versión 3.7.

Objeto Task

class asyncio.Task(coro, *, loop=None, name=None)

Un objeto similar a Futuro que ejecuta Python coroutine. No es seguro hilos.

Las tareas se utilizan para ejecutar corrutinas en bucles de eventos. Si una corrutina aguarda en un Futuro, la Tarea suspende la ejecución de la corrutina y espera la finalización del Futuro. Cuando el Futuro termina, se reanuda la ejecución de la corrutina envuelta.

Los bucles de eventos usan la programación cooperativa: un bucle de eventos ejecuta una tarea a la vez. Mientras una Tarea espera para la finalización de un Futuro, el bucle de eventos ejecuta otras tareas, retorno de llamada o realiza operaciones de E/S.

Utilice la función de alto nivel asyncio.create_task() para crear Tareas, o las funciones de bajo nivel loop.create_task() o ensure_future(). Se desaconseja la creación de instancias manuales de Tareas.

Para cancelar una Tarea en ejecución, utilice el método cancel(). Llamarlo hará que la tarea lance una excepción CancelledError en la corrutina contenida. Si una corrutina está esperando en un objeto Futuro durante la cancelación, se cancelará el objeto Futuro.

cancelled() se puede utilizar para comprobar si la Tarea fue cancelada. El método devuelve True si la corrutina contenida no suprimió la excepción CancelledError y se canceló realmente.

asyncio.Task hereda de Future todas sus API excepto Future.set_result() y Future.set_exception().

Las tareas admiten el módulo contextvars. Cuando se crea una Tarea, copia el contexto actual y, posteriormente, ejecuta su corrutina en el contexto copiado.

Distinto en la versión 3.7: Agregado soporte para el módulo contextvars.

Distinto en la versión 3.8: Se ha añadido el parámetro name.

Deprecated since version 3.8, will be removed in version 3.10: El parámetro loop.

cancel(msg=None)

Solicita que se cancele la Tarea.

Esto hace que una excepción CancelledError sea lanzada a la corrutina contenida en el próximo ciclo del bucle de eventos.

La corrutina entonces tiene la oportunidad de limpiar o incluso denegar la solicitud suprimiendo la excepción con un bloque try … …``except CancelledError`` … finally. Por lo tanto, a diferencia de Future.cancel(), Task.cancel() no garantiza que la tarea será cancelada, aunque suprimir la cancelación por completo no es común y se desalienta activamente.

Distinto en la versión 3.9: Se agregó el parámetro msg.

En el ejemplo siguiente se muestra cómo las corrutinas pueden interceptar la solicitud de cancelación:

async def cancel_me():
    print('cancel_me(): before sleep')

    try:
        # Wait for 1 hour
        await asyncio.sleep(3600)
    except asyncio.CancelledError:
        print('cancel_me(): cancel sleep')
        raise
    finally:
        print('cancel_me(): after sleep')

async def main():
    # Create a "cancel_me" Task
    task = asyncio.create_task(cancel_me())

    # Wait for 1 second
    await asyncio.sleep(1)

    task.cancel()
    try:
        await task
    except asyncio.CancelledError:
        print("main(): cancel_me is cancelled now")

asyncio.run(main())

# Expected output:
#
#     cancel_me(): before sleep
#     cancel_me(): cancel sleep
#     cancel_me(): after sleep
#     main(): cancel_me is cancelled now

cancelled()

Retorna True si la Tarea se cancela.

La tarea se cancela cuando se solicitó la cancelación con cancel() y la corrutina contenida propagó la excepción CancelledError que se le ha lanzado.

done()

Retorna True si la Tarea está finalizada.

Una tarea está finalizada cuando la corrutina contenida retornó un valor, lanzó una excepción, o se canceló la Tarea.

result()

Retorna el resultado de la Tarea.

Si la tarea está terminada, se devuelve el resultado de la corrutina contenida (o si la corrutina lanzó una excepción, esa excepción se vuelve a relanzar.)

Si la Tarea ha sido cancelada, este método lanza una excepción CancelledError.

Si el resultado de la Tarea aún no está disponible, este método lanza una excepción InvalidStateError.

exception()

Retorna la excepción de la Tarea.

Si la corrutina contenida lanzó una excepción, esa excepción es retornada. Si la corrutina contenida retorna normalmente, este método retorna None.

Si la Tarea ha sido cancelada, este método lanza una excepción CancelledError.

Si la Tarea aún no está terminada, este método lanza una excepción InvalidStateError.

add_done_callback(callback, *, context=None)

Agrega una retro llamada que se ejecutará cuando la Tarea esté terminada.

Este método solo se debe usar en código basado en retrollamada de bajo nivel.

Consulte la documentación de Future.add_done_callback() para obtener más detalles.

remove_done_callback(callback)

Remueve la retrollamada de la lista de retrollamadas.

Este método solo se debe usar en código basado en retrollamada de bajo nivel.

Consulte la documentación de Future.remove_done_callback() para obtener más detalles.

get_stack(*, limit=None)

Retorna la lista de marcos de pila para esta tarea.

Si la corrutina contenida no se termina, esto retorna la pila donde se suspende. Si la corrutina se ha completado correctamente o se ha cancelado, retorna una lista vacía. Si la corrutina terminó por una excepción, esto retorna la lista de marcos de seguimiento.

Los marcos siempre se ordenan de más antiguo a más nuevo.

Solo se retorna un marco de pila para una corrutina suspendida.

El argumento opcional limit establece el número máximo de marcos que se retornarán; de forma predeterminada se retornan todos los marcos disponibles. El orden de la lista devuelta varía en función de si se retorna una pila o un traceback: se devuelven los marcos más recientes de una pila, pero se devuelven los marcos más antiguos de un traceback. (Esto coincide con el comportamiento del módulo traceback.)ss

print_stack(*, limit=None, file=None)

Imprime la pila o el seguimiento de esta tarea.

Esto produce una salida similar a la del módulo traceback para los marcos recuperados por get_stack().

El argumento limit se pasa directamente a get_stack().

El argumento file es un flujo de E/S en el que se escribe la salida; por defecto, la salida se escribe en sys.stderr.

get_coro()

Retorna el objeto corrutina contenido por Task.

Nuevo en la versión 3.8.

get_name()

Retorna el nombre de la Tarea.

Si no se ha asignado explícitamente ningún nombre a la Tarea, la implementación de Tarea asyncio predeterminada genera un nombre predeterminado durante la creación de instancias.

Nuevo en la versión 3.8.

set_name(value)

Establece el nombre de la Tarea.

El argumento value puede ser cualquier objeto, que luego se convierte en una cadena.

En la implementación de Task predeterminada, el nombre será visible en la salida repr() de un objeto de tarea.

Nuevo en la versión 3.8.

Corrutinas basadas en generadores

Nota

Support for generator-based coroutines is deprecated and is removed in Python 3.11.

Las corrutinas basadas en generadores son anteriores a la sintaxis async/await. Son generadores de Python que utilizan expresiones yield from para esperar en Futuros y otras corrutinas.

Las corrutinas basadas en generadores deben estar decoradas con @asyncio.coroutine, aunque esto no se aplica.

@asyncio.coroutine

Decorador para marcar corrutinas basadas en generadores.

Este decorador permite que las corrutinas basadas en generadores de versiones anteriores (legacy) sean compatibles con el código async/await:

@asyncio.coroutine
def old_style_coroutine():
    yield from asyncio.sleep(1)

async def main():
    await old_style_coroutine()

Este decorador no debe utilizarse para corrutinas async def.

Deprecated since version 3.8, will be removed in version 3.11: Usar async def en su lugar.

asyncio.iscoroutine(obj)

Retorna True si obj es un coroutine object.

Este método es diferente de inspect.iscoroutine() porque retorna True para corrutinas basadas en generadores.

asyncio.iscoroutinefunction(func)

Retorna True si func es una coroutine function.

Este método es diferente de inspect.iscoroutinefunction() porque retorna True para funciones de corrutinas basadas en generadores decoradas con @coroutine.

Streams

Código fuente: Lib/asyncio/streams.py [https://github.com/python/cpython/tree/3.9/Lib/asyncio/streams.py]

Los streams son async/await primitivos de alto nivel para trabajar con conexiones de red. Los streams permiten enviar y recibir datos sin utilizar callbacks o protocolos y transportes de bajo nivel.

Aquí hay un ejemplo de un cliente eco TCP escrito utilizando streams asyncio:

import asyncio

async def tcp_echo_client(message):
    reader, writer = await asyncio.open_connection(
        '127.0.0.1', 8888)

    print(f'Send: {message!r}')
    writer.write(message.encode())
    await writer.drain()

    data = await reader.read(100)
    print(f'Received: {data.decode()!r}')

    print('Close the connection')
    writer.close()
    await writer.wait_closed()

asyncio.run(tcp_echo_client('Hello World!'))

Consulte también la sección de Examples a continuación.

Funciones stream

Las siguientes funciones asyncio de nivel superior se pueden utilizar para crear y trabajar con streams:

coroutine asyncio.open_connection(host=None, port=None, *, loop=None, limit=None, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None, ssl_handshake_timeout=None, happy_eyeballs_delay=None, interleave=None)

Establece una conexión de red y retorna un par de objetos (reader, writer).

Los objetos retornados reader y writer son instancias de las clases StreamReader y StreamWriter.

El argumento loop es opcional y siempre se puede determinar automáticamente cuando se espera esta función de una corrutina.

limit determina el límite de tamaño del búfer utilizado por la instancia de StreamReader retornada. De forma predeterminada, limit está establecido en 64 KiB.

El resto de los argumentos se pasan directamente a loop.create_connection().

Nuevo en la versión 3.7: El parámetro ssl_handshake_timeout.

Nuevo en la versión 3.8: Added happy_eyeballs_delay and interleave parameters.

coroutine asyncio.start_server(client_connected_cb, host=None, port=None, *, loop=None, limit=None, family=socket.AF_UNSPEC, flags=socket.AI_PASSIVE, sock=None, backlog=100, ssl=None, reuse_address=None, reuse_port=None, ssl_handshake_timeout=None, start_serving=True)

Inicia un servidor socket.

La retrollamada client_connected_cb se llama siempre que se establece una nueva conexión de cliente. Recibe un par (reader, writer) como dos argumentos, instancias de las clases StreamReader y StreamWriter.

client_connected_cb puede ser una función simple invocable o de corrutina; si es una función de corrutina, se programará automáticamente como un Task.

El argumento loop es opcional y siempre se puede determinar automáticamente cuando se espera este método de una corrutina.

limit determina el límite de tamaño del búfer utilizado por la instancia de StreamReader retornada. De forma predeterminada, limit está establecido en 64 KiB.

El resto de los argumentos se pasan directamente a loop.create_server().

Nuevo en la versión 3.7: Los parámetros ssl_handshake_timeout y start_serving.

Sockets Unix

coroutine asyncio.open_unix_connection(path=None, *, loop=None, limit=None, ssl=None, sock=None, server_hostname=None, ssl_handshake_timeout=None)

Establece una conexión de socket Unix y retorna un par de (reader, writer).

Similar a open_connection() pero opera en sockets Unix.

Consulte también la documentación de loop.create_unix_connection().

Disponibilidad: Unix.

Nuevo en la versión 3.7: El parámetro ssl_handshake_timeout.

Distinto en la versión 3.7: El parámetro path ahora puede ser un objeto similar a una ruta (path-like object)

coroutine asyncio.start_unix_server(client_connected_cb, path=None, *, loop=None, limit=None, sock=None, backlog=100, ssl=None, ssl_handshake_timeout=None, start_serving=True)

Inicia un servidor socket Unix.

Similar a start_server() pero funciona con sockets Unix.

Consulte también la documentación de loop.create_unix_server().

Disponibilidad: Unix.

Nuevo en la versión 3.7: Los parámetros ssl_handshake_timeout y start_serving.

Distinto en la versión 3.7: El parámetro path ahora puede ser un objeto similar a una ruta (path-like object).

StreamReader

class asyncio.StreamReader

Representa un objeto lector que proporciona APIs para leer datos del flujo de E/S.

No se recomienda crear instancias de objetos StreamReader directamente; utilice open_connection() y start_server() en su lugar.

coroutine read(n=-1)

Lee hasta n bytes. Si no se proporciona n, o se establece en -1, lee hasta EOF (final del archivo) y retorna todos los bytes leídos.

Si se recibió EOF (final del archivo) y el búfer interno está vacío, retorna un objeto de bytes vacío.

coroutine readline()

Lea una línea, donde «línea» es una secuencia de bytes que termina en \n.

Si se recibe EOF (final del archivo) y no se encontró \n, el método retorna datos leídos parcialmente.

Si se recibe EOF (final de archivo) y el búfer interno está vacío, retorna un objeto de bytes vacío.

coroutine readexactly(n)

Lee exactamente n bytes.

Genera un IncompleteReadError si se alcanza EOF (final del archivo) antes de que se pueda leer n. Utilice el atributo IncompleteReadError.partial para obtener los datos leídos parcialmente.

coroutine readuntil(separator=b'\n')

Lee datos de la secuencia hasta que se encuentre el separador (separator).

En caso de éxito, los datos y el separador se eliminarán del búfer interno (consumido). Los datos retornados incluirán el separador al final.

Si la cantidad de datos leídos excede el límite de flujo configurado, se genera una excepción LimitOverrunError y los datos se dejan en el búfer interno y se pueden leer nuevamente.

Si se alcanza EOF (final del archivo) antes de que se encuentre el separador completo, se genera una excepción IncompleteReadError y se restablece el búfer interno. El atributo IncompleteReadError.partial puede contener una parte del separador.

Nuevo en la versión 3.5.2.

at_eof()

Retorna True si el buffer está vacío y feed_eof() fue llamado.

StreamWriter

class asyncio.StreamWriter

Representa un objeto de escritura que proporciona APIs para escribir datos en el flujo de E/S.

No se recomienda crear instancias de objetos StreamWriter directamente; use open_connection() y start_server() en su lugar.

write(data)

El método intenta escribir los datos (data) en el socket subyacente inmediatamente. Si eso falla, los datos se ponen en cola en un búfer de escritura interno hasta que se puedan enviar.

El método debe usarse junto con el método drain():

stream.write(data)
await stream.drain()

writelines(data)

El método escribe una lista (o cualquier iterable) de bytes en el socket subyacente inmediatamente. Si eso falla, los datos se ponen en cola en un búfer de escritura interno hasta que se puedan enviar.

El método debe usarse junto con el método drain():

stream.writelines(lines)
await stream.drain()

close()

El método cierra la secuencia y el socket subyacente.

El método debe usarse junto con el método wait_closed():

stream.close()
await stream.wait_closed()

can_write_eof()

Retorna True si el transporte subyacente admite el método write_eof(), False en caso contrario.

write_eof()

Cierra la escritura de la secuencia después de que se vacíen los datos de escritura almacenados en búfer.

transport

Retorna el transporte asyncio subyacente.

get_extra_info(name, default=None)

Accede a información de transporte opcional; consulte BaseTransport.get_extra_info() para obtener más detalles.

coroutine drain()

Espera hasta que sea apropiado reanudar la escritura en la transmisión. Ejemplo:

writer.write(data)
await writer.drain()

Este es un método de control de flujo que interactúa con el búfer de escritura de E/S subyacente. Cuando el tamaño del búfer alcanza la marca de agua alta, drain() bloquea hasta que el tamaño del búfer se agota hasta la marca de agua baja y se pueda reanudar la escritura. Cuando no hay nada que esperar, drain() regresa inmediatamente.

is_closing()

Retorna True si la secuencia está cerrada o en proceso de cerrarse.

Nuevo en la versión 3.7.

coroutine wait_closed()

Espera hasta que se cierre la secuencia.

Debería llamarse después de close() para esperar hasta que se cierre la conexión subyacente.

Nuevo en la versión 3.7.

Ejemplos

Cliente eco TCP usando streams

Cliente eco TCP usando la función asyncio.open_connection():

import asyncio

async def tcp_echo_client(message):
    reader, writer = await asyncio.open_connection(
        '127.0.0.1', 8888)

    print(f'Send: {message!r}')
    writer.write(message.encode())

    data = await reader.read(100)
    print(f'Received: {data.decode()!r}')

    print('Close the connection')
    writer.close()

asyncio.run(tcp_echo_client('Hello World!'))

Ver también

El ejemplo del protocolo de cliente eco TCP utiliza el método loop.create_connection() de bajo nivel.

Servidor eco TCP usando streams

Servidor eco TCP usando la función asyncio.start_server():

import asyncio

async def handle_echo(reader, writer):
    data = await reader.read(100)
    message = data.decode()
    addr = writer.get_extra_info('peername')

    print(f"Received {message!r} from {addr!r}")

    print(f"Send: {message!r}")
    writer.write(data)
    await writer.drain()

    print("Close the connection")
    writer.close()

async def main():
    server = await asyncio.start_server(
        handle_echo, '127.0.0.1', 8888)

    addrs = ', '.join(str(sock.getsockname()) for sock in server.sockets)
    print(f'Serving on {addrs}')

    async with server:
        await server.serve_forever()

asyncio.run(main())

Ver también

El ejemplo del protocolo de servidor eco TCP utiliza el método loop.create_server().

Obtener encabezados HTTP

Ejemplo simple de consulta de encabezados HTTP de la URL pasada en la línea de comando:

import asyncio
import urllib.parse
import sys

async def print_http_headers(url):
    url = urllib.parse.urlsplit(url)
    if url.scheme == 'https':
        reader, writer = await asyncio.open_connection(
            url.hostname, 443, ssl=True)
    else:
        reader, writer = await asyncio.open_connection(
            url.hostname, 80)

    query = (
        f"HEAD {url.path or '/'} HTTP/1.0\r\n"
        f"Host: {url.hostname}\r\n"
        f"\r\n"
    )

    writer.write(query.encode('latin-1'))
    while True:
        line = await reader.readline()
        if not line:
            break

        line = line.decode('latin1').rstrip()
        if line:
            print(f'HTTP header> {line}')

    # Ignore the body, close the socket
    writer.close()

url = sys.argv[1]
asyncio.run(print_http_headers(url))

Uso:

python example.py http://example.com/path/page.html

o con HTTPS:

python example.py https://example.com/path/page.html

Registrar un socket abierto para esperar datos usando streams

Corutina esperando hasta que un socket reciba datos usando la función open_connection() function:

import asyncio
import socket

async def wait_for_data():
    # Get a reference to the current event loop because
    # we want to access low-level APIs.
    loop = asyncio.get_running_loop()

    # Create a pair of connected sockets.
    rsock, wsock = socket.socketpair()

    # Register the open socket to wait for data.
    reader, writer = await asyncio.open_connection(sock=rsock)

    # Simulate the reception of data from the network
    loop.call_soon(wsock.send, 'abc'.encode())

    # Wait for data
    data = await reader.read(100)

    # Got data, we are done: close the socket
    print("Received:", data.decode())
    writer.close()

    # Close the second socket
    wsock.close()

asyncio.run(wait_for_data())

Ver también

El ejemplo de registro de un socket abierto para esperar datos usando un protocolo utiliza un protocolo de bajo nivel y el método loop.create_connection().

El ejemplo de observar un descriptor de archivo para leer eventos utiliza el método loop.add_reader() de bajo nivel para ver un descriptor de archivo.

Primitivas de sincronización

Código fuente: Lib/asyncio/locks.py [https://github.com/python/cpython/tree/3.9/Lib/asyncio/locks.py]

Las primitivas de sincronización de asyncio están diseñadas para ser similares a las del módulo threading, con dos importantes advertencias:

las primitivas de asyncio no son seguras en hilos, por lo tanto, no deben ser usadas para la sincronización de hilos del sistema operativo (usa threading para esto);

los métodos de estas primitivas de sincronización no aceptan el argumento timeout. Usa la función asyncio.wait_for() para realizar operaciones que involucren tiempos de espera.

asyncio tiene las siguientes primitivas de sincronización básicas:

Lock

Event

Condition

Semaphore

BoundedSemaphore

Lock

class asyncio.Lock(*, loop=None)

Implementa un cierre de exclusión mutua para tareas asyncio. No es seguro en hilos.

Un cierre asyncio puede usarse para garantizar el acceso en exclusiva a un recurso compartido.

La forma preferida de usar un Lock es mediante una declaración async with:

lock = asyncio.Lock()

# ... later
async with lock:
    # access shared state

lo que es equivalente a:

lock = asyncio.Lock()

# ... later
await lock.acquire()
try:
    # access shared state
finally:
    lock.release()

Deprecated since version 3.8, will be removed in version 3.10: El parámetro loop.

coroutine acquire()

Adquiere el cierre.

Este método espera hasta que el cierre está abierto, lo establece como cerrado y retorna True.

Cuando más de una corrutina está bloqueada en acquire(), esperando a que el cierre se abra, solo una de las corrutinas proseguirá finalmente.

Adquirir un cierre es justo: la corrutina que prosigue será la primera corrutina que comenzó a esperarlo.

release()

Libera el cierre.

Cuando el cierre está cerrado, lo restablece al estado abierto y retorna.

Si el cierre está abierto, se lanza una excepción RuntimeError.

locked()

Retorna True si el cierre está cerrado.

Event

class asyncio.Event(*, loop=None)

Un objeto de eventos. No es seguro en hilos.

Un evento asyncio puede usarse para notificar a múltiples tareas asyncio que ha ocurrido algún evento.

Un objeto Event administra una bandera interna que se puede establecer en true con el método set() y se restablece en false con el método clear(). El método wait() se bloquea hasta que la bandera se establece en true. El flag se establece en false inicialmente.

Deprecated since version 3.8, will be removed in version 3.10: El parámetro loop.

Ejemplo:

async def waiter(event):
    print('waiting for it ...')
    await event.wait()
    print('... got it!')

async def main():
    # Create an Event object.
    event = asyncio.Event()

    # Spawn a Task to wait until 'event' is set.
    waiter_task = asyncio.create_task(waiter(event))

    # Sleep for 1 second and set the event.
    await asyncio.sleep(1)
    event.set()

    # Wait until the waiter task is finished.
    await waiter_task

asyncio.run(main())

coroutine wait()

Espera hasta que se establezca el evento.

Si el evento está configurado, retorna True inmediatamente. De lo contrario, bloquea hasta que otra tarea llame a set().

set()

Establece el evento.

Todas las tareas esperando a que el evento se establezca serán activadas inmediatamente.

clear()

Borra (restablece) el evento.

Las tareas que esperan en wait() ahora se bloquearán hasta que se vuelva a llamar al método set().

is_set()

Retorna True si el evento está establecido.

Condition

class asyncio.Condition(lock=None, *, loop=None)

Un objeto Condition. No seguro en hilos.

Una tarea puede usar una condición primitiva de asyncio para esperar a que suceda algún evento y luego obtener acceso exclusivo a un recurso compartido.

En esencia, un objeto Condition combina la funcionalidad de un objeto Event y un objeto Lock. Es posible tener múltiples objetos Condition que compartan un mismo Lock, lo que permite coordinar el acceso exclusivo a un recurso compartido entre diferentes tareas interesadas en estados particulares de ese recurso compartido.

El argumento opcional lock debe ser un objeto Lock o None. En este último caso, se crea automáticamente un nuevo objeto Lock.

Deprecated since version 3.8, will be removed in version 3.10: El parámetro loop.

La forma preferida de usar una condición es mediante una declaración async with:

cond = asyncio.Condition()

# ... later
async with cond:
    await cond.wait()

lo que es equivalente a:

cond = asyncio.Condition()

# ... later
await cond.acquire()
try:
    await cond.wait()
finally:
    cond.release()

coroutine acquire()

Adquiere el cierre (lock) subyacente.

Este método espera hasta que el cierre subyacente esté abierto, lo establece en cerrado y retorna True.

notify(n=1)

Despierta como máximo n tareas (1 por defecto) que estén esperando a esta condición. El método no es operativo si no hay tareas esperando.

El cierre debe adquirirse antes de llamar a este método y liberarse poco después. Si se llama con un cierre abierto, se lanza una excepción RuntimeError.

locked()

Retorna True si el cierre subyacente está adquirido.

notify_all()

Despierta todas las tareas que esperan a esta condición.

Este método actúa como notify(), pero despierta todas las tareas en espera.

El cierre debe adquirirse antes de llamar a este método y liberarse poco después. Si se llama con un cierre abierto, se lanza una excepción RuntimeError.

release()

Libera el cierre subyacente.

Cuando se invoca en un cierre abierto, se lanza una excepción RuntimeError.

coroutine wait()

Espera hasta que se le notifique.

Si la tarea que llama no ha adquirido el cierre cuando se llama a este método, se lanza una excepción RuntimeError.

Este método libera el cierre subyacente y luego se bloquea hasta que lo despierte una llamada notify() o notify_all(). Una vez despertado, la condición vuelve a adquirir su cierre y este método retorna``True``.

coroutine wait_for(predicate)

Espera hasta que un predicado se vuelva verdadero.

El predicado debe ser un objeto invocable cuyo resultado se interpretará como un valor booleano. El valor final es el valor de retorno.

Semaphore

class asyncio.Semaphore(value=1, *, loop=None)

Un objeto Semaphore. No es seguro en hilos.

Un semáforo gestiona un contador interno que se reduce en cada llamada al método acquire() y se incrementa en cada llamada al método release(). El contador nunca puede bajar de cero, cuando acquire() encuentra que es cero, se bloquea, esperando hasta que alguna tarea llame a release().

El argumento opcional value proporciona el valor inicial para el contador interno (1 por defecto). Si el valor dado es menor que 0 se lanza una excepción ValueError.

Deprecated since version 3.8, will be removed in version 3.10: El parámetro loop.

La forma preferida de utilizar un semáforo es mediante una declaración async with:

sem = asyncio.Semaphore(10)

# ... later
async with sem:
    # work with shared resource

lo que es equivalente a:

sem = asyncio.Semaphore(10)

# ... later
await sem.acquire()
try:
    # work with shared resource
finally:
    sem.release()

coroutine acquire()

Adquiere un semáforo.

Si el contador interno es mayor que cero, lo reduce en uno y retorna True inmediatamente. Si es cero, espera hasta que se llame al método release() y retorna True.

locked()

Retorna True si el semáforo no se puede adquirir de inmediato.

release()

Libera un semáforo, incrementando el contador interno en uno. Puede despertar una tarea que esté a la espera para adquirir el semáforo.

A diferencia de BoundedSemaphore, Semaphore permite hacer más llamadas release() que llamadas acquire().

BoundedSemaphore

class asyncio.BoundedSemaphore(value=1, *, loop=None)

Un objeto semáforo delimitado. No es seguro en hilos.

BoundedSemaphore es una versión de la clase Semaphore que lanza una excepción ValueError en release() si aumenta el contador interno por encima del valor inicial.

Deprecated since version 3.8, will be removed in version 3.10: El parámetro loop.

Distinto en la versión 3.9: Adquirir un bloqueo usando await lock o yield from lock o una declaración with (with await lock, with (yield from lock)) se eliminó . En su lugar, use async with lock.

Sub-procesos

Código fuente: Lib/asyncio/subprocess.py [https://github.com/python/cpython/tree/3.9/Lib/asyncio/subprocess.py], Lib/asyncio/base_subprocess.py [https://github.com/python/cpython/tree/3.9/Lib/asyncio/base_subprocess.py]

Esta sección describe APIs de alto nivel de async/await de asyncio para crear y gestionar sub-procesos.

Aquí podemos encontrar un ejemplo de cómo asyncio puede ejecutar un comando de shell y obtener su resultado:

import asyncio

async def run(cmd):
    proc = await asyncio.create_subprocess_shell(
        cmd,
        stdout=asyncio.subprocess.PIPE,
        stderr=asyncio.subprocess.PIPE)

    stdout, stderr = await proc.communicate()

    print(f'[{cmd!r} exited with {proc.returncode}]')
    if stdout:
        print(f'[stdout]\n{stdout.decode()}')
    if stderr:
        print(f'[stderr]\n{stderr.decode()}')

asyncio.run(run('ls /zzz'))

mostrará en pantalla:

['ls /zzz' exited with 1]
[stderr]
ls: /zzz: No such file or directory

Ya que todos las funciones de sub-procesos de asyncio son asíncronas y asyncio proporciona herramientas para trabajar con tales funciones, es fácil ejecutar y monitorear múltiples subprocesos en paralelo. De hecho es trivial modificar los ejemplos de arriba para ejecutar varios comandos simultáneamente:

async def main():
    await asyncio.gather(
        run('ls /zzz'),
        run('sleep 1; echo "hello"'))

asyncio.run(main())

Véase también la subsección Examples.

Creando sub-procesos

coroutine asyncio.create_subprocess_exec(program, *args, stdin=None, stdout=None, stderr=None, loop=None, limit=None, **kwds)

Crea un sub-proceso.

El argumento limit establece el límite del buffer para los envoltorios StreamReader para Process.stdout y Process.stderr (si se pasa subprocess.PIPE a los argumentos stdout y stderr).

Retorna una instancia de Process.

Véase la documentación de loop.subprocess_exec() para los otros parámetros.

Deprecated since version 3.8, will be removed in version 3.10: El parámetro loop.

coroutine asyncio.create_subprocess_shell(cmd, stdin=None, stdout=None, stderr=None, loop=None, limit=None, **kwds)

Ejecuta el comando de shell cmd.

El argumento limit establece el límite del buffer para los envoltorios StreamReader para Process.stdout y Process.stderr (si se pasa subprocess.PIPE a los argumentos stdout y stderr).

Retorna una instancia de Process.

Véase la documentación de loop.subprocess_shell() para los otros parámetros.

Importante

Es la responsabilidad de la aplicación asegurarse que todos los espacios en blanco y caracteres especiales estén citados apropiadamente para evitar vulnerabilidades de inyección de instrucciones [https://es.wikipedia.org/wiki/Inyecci%C3%B3n_de_c%C3%B3digo#Inyecci%C3%B3n_de_instrucciones]. La función shlex.quote() puede ser usada para escapar caracteres en blanco y caracteres especiales de shell en cadenas de caracteres a ser usadas para construir comandos de shell.

Deprecated since version 3.8, will be removed in version 3.10: El parámetro loop.

Nota

Los subprocesos están disponibles para Windows si se utiliza un ProactorEventLoop. Consulte Soporte de subprocesos en Windows para obtener más detalles.

Ver también

asyncio también tiene las siguientes APIs de bajo nivel para trabajar con sub-procesos: loop.subprocess_exec(), loop.subprocess_shell(), loop.connect_read_pipe(), loop.connect_write_pipe(), así como también los Sub-procesos de Transportes y los Sub-procesos de Protocolos.

Constantes

asyncio.subprocess.PIPE

Se le puede pasar a los parámetros stding, stdout o stderr.

Si se le pasa PIPE al argumento stdin, el atributo Process.stdin apuntará a la instancia StreamWriter.

Si se pasa PIPE a los argumentos stdout o stderr, los atributos Process.stdout y Process.stderr apuntarán a las instancias StreamReader.

asyncio.subprocess.STDOUT

Un valor especial que puede ser usado como el argumento de stderr e indica que los errores estándar deben ser redireccionados en la salida estándar.

asyncio.subprocess.DEVNULL

Un valor especial que puede ser usado como el argumento de stdin, stdout, stderr para procesar funciones de creación. Indica que el archivo especial os.devnull será usado para la correspondiente transmisión del sub-proceso.

Interactuando con Subprocesos

Las dos funciones create_subprocess_exec() y create_subprocess_shell() retornan instancias de la clase Process. Process es un envoltorio de alto nivel que permite comunicarse con los subprocesos y estar atento a sus términos.

class asyncio.subprocess.Process

Un objeto que envuelve procesos del SO creados por las funciones create_subprocess_exec() y create_subprocess_shell().

Esta clase está diseñada para tener un API similar a la clase subprocess.Popen, pero hay algunas diferencias notables:

a diferencia de Popen, las instancias de Process no tiene un equivalente del método poll();

los métodos communicate() y wait() no tienen un parámetro timeout: use la función wait_for();

el método Process.wait() es asíncrono, mientras que el método subprocess.Popen.wait() es implementado como un bucle de espera activa;

el parámetro universal_newlines no es compatible.

Esta clase no es segura para subprocesos (not thread safe).

Véase también la sección Subprocesos e Hilos.

coroutine wait()

Espera a que el proceso hijo termine.

Define y retorna el atributo returncode.

Nota

Este método puede bloquearse cuando usa stdout=PIPE o stderr=PIPE y el proceso hijo genera tanta salida que se bloquea esperando a que la tubería de búfer del SO acepte más datos. Use el método communicate() cuando use tuberías para evitar esta condición.

coroutine communicate(input=None)

Interactuar con el proceso:

envía datos a stdin (si input no es None);

lee datos desde stdout y stderr, hasta que el llegue al EOF;

espera a que el proceso termine.

El argumento opcional input son los datos (objetos bytes) que serán enviados a los procesos hijos.

Retorna una tupla (stdout_data, stderr_data).

Si se levanta la excepción BrokenPipeError o ConnectionResetError cuando se escribe input en stdin, la excepción es ignorada. Esta condición ocurre cuando el proceso finaliza antes de que todos los datos sean escritos en stdin.

Si se desea enviar datos al stdin del proceso, el proceso necesita ser creado con stdin=PIPE. De manera similar, para obtener cualquier cosa excepto None en la tupla del resultado, el proceso tiene que ser creado con los argumentos stdout=PIPE y/o stderr=PIPE.

Tenga en cuenta que los datos leídos son almacenados en memoria, por lo que no utilice este método si el tamaño de los datos es más grande o ilimitado.

send_signal(signal)

Envíe la señal signal al proceso hijo.

Nota

En Windows, SIGTERM es un alias para terminate(). Se puede enviar CTRL_C_EVENT y CTRL_BREAK_EVENT a procesos iniciados con un parámetro creationflags que incluye CREATE_NEW_PROCESS_GROUP.

terminate()

Para al proceso hijo.

En sistemas POSIX este método envía signal.SIGNTERM al proceso hijo.

En Windows, la función de la API de Win32 TerminateProcess() es llamado para parar a los procesos hijos.

kill()

Kill the child process.

En sistemas POSIX, este método envía SIGKILL al proceso hijo.

En Windows este método es un alias para terminate().

stdin

Flujo de entrada estándar (StreamWriter) o None si el proceso fue creado con stdin=None.

stdout

Flujo de salida estándar (SreamReader) o None si el proceso fue creado con stdout=None.

stderr

Flujo de salida estándar (StreamReader) o None si el proceso fue creado con stderr=None.

Advertencia

Use the communicate() method rather than process.stdin.write(), await process.stdout.read() or await process.stderr.read(). This avoids deadlocks due to streams pausing reading or writing and blocking the child process.

pid

Número de identificación del Proceso (PID por sus siglas en inglés).

Tenga en cuenta que para procesos creados por la función create_subprocess_shell(), este atributo es el PID del shell generado.

returncode

Código de retorno del proceso cuando finaliza.

Un valor None indica que el proceso todavía no ha finalizado.

Un valor negativo -N indica que el hijo ha finalizado por la señal N (sólo para POSIX).

Subprocesos y Hilos

Por defecto el bucle de eventos de asyncio estándar permite correr subprocesos desde hilos diferentes.

En Windows, sólo ProactorEventLoop proporciona subprocesos (por defecto), SelectorEventLoop no es compatible con subprocesos.

En UNIX, los observadores de hijos son usados para la espera de finalización de subprocesos, véase Observadores de procesos para más información.

Distinto en la versión 3.8: UNIX cambió para usar ThreadedChildWatcher para generar subprocesos de hilos diferentes sin ninguna limitación.

Crear un subproceso con el observador del hijo inactivo lanza un RuntimeError.

Tenga en cuenta que implementaciones alternativas del bucle de eventos pueden tener limitaciones propias; por favor consulte su documentación.

Ver también

La sección Concurrencia y multihilos en asyncio.

Ejemplos

Un ejemplo usando la clase Process para controlar un subproceso y la clase StreamReader para leer de su salida estándar.

El subproceso es creado por la función create_subprocess_exec():

import asyncio
import sys

async def get_date():
    code = 'import datetime; print(datetime.datetime.now())'

    # Create the subprocess; redirect the standard output
    # into a pipe.
    proc = await asyncio.create_subprocess_exec(
        sys.executable, '-c', code,
        stdout=asyncio.subprocess.PIPE)

    # Read one line of output.
    data = await proc.stdout.readline()
    line = data.decode('ascii').rstrip()

    # Wait for the subprocess exit.
    await proc.wait()
    return line

date = asyncio.run(get_date())
print(f"Current date: {date}")

Véase también los ejemplos de prueba escritos usando APIs de bajo nivel.

Colas

Código fuente: Lib/asyncio/queue.py [https://github.com/python/cpython/tree/3.9/Lib/asyncio/queue.py]

Las colas asyncio son diseñadas para ser similares a clases del módulo queue. Sin embargo las colas asyncio no son seguras para hilos, son diseñadas para usar específicamente en código async/await.

Nota que los métodos de colas de asyncio no tienen un parámetro timeout; usa la función asyncio.wait_for() para hacer operaciones de cola con un tiempo de espera.

Ver también la sección Examples a continuación.

Cola

class asyncio.Queue(maxsize=0, *, loop=None)

Una cola primero en entrar, primero en salir (PEPS, o FIFO en inglés).

Si maxsize es menor que o igual a cero, el tamaño de la cola es infinito. Si es un entero mayor a 0, entonces await put() se bloquea cuando una cola alcanza su maxsize hasta que un elemento es removido por get().

Diferente de los subprocesos de la biblioteca estándar queue, el tamaño de la cola siempre es conocido y puede ser retornado llamando el método qsize().

Deprecated since version 3.8, will be removed in version 3.10: El parámetro loop.

Esta clase es no segura para hilos.

maxsize

Número de ítems permitidos en la cola.

empty()

Retorna True si la cola es vacía, o False en caso contrario.

full()

Retorna True si hay maxsize ítems en la cola.

Si la cola fue inicializada con maxsize=0 (el predeterminado), entonces fill() nunca retorna True.

coroutine get()

Remueve y retorna un ítem de la cola. Si la cola es vacía, espera hasta que un ítem esté disponible.

get_nowait()

Retorna un ítem si uno está inmediatamente disponible, de otra manera levanta QueueEmpty.

coroutine join()

Se bloquea hasta que todos los ítems en la cola han sido recibidos y procesados.

El conteo de tareas no terminadas sube siempre que un ítem es agregado a la cola. El conteo baja siempre que la ejecución de una corrutina task_done() para indicar que el ítem fue recuperado y todo el trabajo en él está completo. Cuando el conteo de tareas inacabadas llega a cero, join() se desbloquea.

coroutine put(item)

Pone un ítem en la cola. Si la cola está completa, espera hasta que una entrada vacía esté disponible antes de agregar el ítem.

put_nowait(item)

Pone un ítem en la cola sin bloquearse.

Si no hay inmediatamente disponibles entradas vacías, lanza QueueFull.

qsize()

Retorna el número de ítems en la cola.

task_done()

Indica que una tarea formalmente en cola está completa.

Usada por consumidores de la cola. Para cada get() usado para buscar una tarea, una ejecución subsecuente a task_done() dice a la cola que el procesamiento de la tarea está completo.

Si un join() está actualmente bloqueando, éste se resumirá cuando todos los ítems han sido procesados (implicado que un método task_done() fue recibido por cada ítem que ha sido put() en la cola.

Lanza ValueError si fue llamado más veces que los ítems en la cola.

Cola de prioridad

class asyncio.PriorityQueue

Una variante de Queue; recupera entradas en su orden de prioridad (el más bajo primero).

Las entradas son típicamente tuplas de la forma (priority_number, data).

Cola UEPA (o LIFO en inglés)

class asyncio.LifoQueue

Una variante de una Queue que recupera primero el elemento agregado más reciente (último en entrar, primero en salir).

Excepciones

exception asyncio.QueueEmpty

Esta excepción es lanzada cuando el método get_nowait() es ejecutado en una cola vacía.

exception asyncio.QueueFull

Las excepciones son lanzadas cuando el método put_nowait() es lanzado en una cola que ha alcanzado su maxsize.

Ejemplos

Las colas pueden ser usadas para distribuir cargas de trabajo entre múltiples tareas concurrentes:

import asyncio
import random
import time

async def worker(name, queue):
    while True:
        # Get a "work item" out of the queue.
        sleep_for = await queue.get()

        # Sleep for the "sleep_for" seconds.
        await asyncio.sleep(sleep_for)

        # Notify the queue that the "work item" has been processed.
        queue.task_done()

        print(f'{name} has slept for {sleep_for:.2f} seconds')

async def main():
    # Create a queue that we will use to store our "workload".
    queue = asyncio.Queue()

    # Generate random timings and put them into the queue.
    total_sleep_time = 0
    for _ in range(20):
        sleep_for = random.uniform(0.05, 1.0)
        total_sleep_time += sleep_for
        queue.put_nowait(sleep_for)

    # Create three worker tasks to process the queue concurrently.
    tasks = []
    for i in range(3):
        task = asyncio.create_task(worker(f'worker-{i}', queue))
        tasks.append(task)

    # Wait until the queue is fully processed.
    started_at = time.monotonic()
    await queue.join()
    total_slept_for = time.monotonic() - started_at

    # Cancel our worker tasks.
    for task in tasks:
        task.cancel()
    # Wait until all worker tasks are cancelled.
    await asyncio.gather(*tasks, return_exceptions=True)

    print('====')
    print(f'3 workers slept in parallel for {total_slept_for:.2f} seconds')
    print(f'total expected sleep time: {total_sleep_time:.2f} seconds')

asyncio.run(main())

Excepciones

Código Fuente Lib/asyncio/exceptions.py [https://github.com/python/cpython/tree/3.9/Lib/asyncio/exceptions.py]

exception asyncio.TimeoutError

La operación ha excedido el tiempo límite.

Importante

Esta excepción es diferente a la excepción incorporada TimeoutError.

exception asyncio.CancelledError

La operación ha sido cancelada.

Esta excepción se puede capturar para realizar operaciones personalizadas cuando se cancelan las tareas de asyncio. En casi todas las situaciones, la excepción debe volver a lanzarse.

Distinto en la versión 3.8: CancelledError es ahora una subclase de BaseException.

exception asyncio.InvalidStateError

Estado Interno no válido de Task o Future.

Se puede lanzar en situaciones como establecer un valor de resultado para un objeto Future que ya tiene un valor de resultado establecido.

exception asyncio.SendfileNotAvailableError

La llamada al sistema «sendfile» no esta disponible desde el socket o tipo de archivo dado.

Una subclase de RuntimeError.

exception asyncio.IncompleteReadError

La operación de lectura solicitada no se completó completamente.

Lanzado por la asyncio stream APIs.

La excepción es una subclase de EOFError.

expected

El número total (int) de bytes esperados.

partial

Un cadena de bytes leída antes de que alcance al final del flujo.

exception asyncio.LimitOverrunError

Alcanzó el límite de tamaño del búfer mientras buscaba un separador.

Lanzado por asyncio stream APIs.

consumed

El número total de bytes que se consumirán.

Bucle de eventos

Código fuente: Lib/asyncio/events.py [https://github.com/python/cpython/tree/3.9/Lib/asyncio/events.py], Lib/asyncio/base_events.py [https://github.com/python/cpython/tree/3.9/Lib/asyncio/base_events.py]

Prólogo

El bucle de eventos es el núcleo de cada aplicación asyncio. Los bucles de eventos ejecutan tareas asíncronas y llamadas de retorno, realizan operaciones de E/S de red y ejecutan subprocesos.

Los desarrolladores de aplicaciones normalmente deberían usar las funciones asyncio de alto nivel, como: asyncio.run(), y rara vez deberían necesitar hacer referencia al objeto de bucle o llamar a sus métodos. Esta sección esta dirigida principalmente a autores de código de nivel inferior, bibliotecas y frameworks, quienes necesitan un control mas preciso sobre el comportamiento del bucle de eventos.

Obtención del bucle de eventos

Las siguientes funciones de bajo nivel se pueden utilizar para obtener, establecer o crear un bucle de eventos:

asyncio.get_running_loop()

Retorna el bucle de eventos en ejecución en el hilo del sistema operativo actual.

Si no hay un bucle de eventos en ejecución, se levanta un RuntimeError. Esta función únicamente puede ser llamada desde una corrutina o una llamada de retorno.

Nuevo en la versión 3.7.

asyncio.get_event_loop()

Obtiene bucle de eventos actual.

Si no hay un bucle de eventos actual establecido en el hilo actual del sistema operativo, el hilo del sistema operativo es el principal, y set_event_loop() aún no ha sido llamado, asyncio creará un nuevo bucle de eventos y lo establecerá como el actual.

Dado que esta función tiene un comportamiento bastante complejo (especialmente cuando están en uso las políticas de bucle de eventos personalizadas), usar la función get_running_loop() es preferible antes que get_event_loop() en corrutinas y llamadas de retorno.

Considere también usar la función asyncio.run() en lugar de usar funciones de bajo nivel para crear y cerrar manualmente un bucle de eventos.

asyncio.set_event_loop(loop)

Establece loop como el bucle de eventos actual para el hilo actual del sistema operativo.

asyncio.new_event_loop()

Create and return a new event loop object.

Tenga en cuenta que el comportamiento de las funciones get_event_loop(), set_event_loop(), y new_event_loop() puede ser modificado mediante estableciendo una política de bucle de eventos personalizada.

Contenidos

Esta página de documentación contiene las siguientes secciones:

La sección Métodos del bucle de eventos es la documentación de referencia de las APIs del bucle de eventos;

La sección Callback Handles documenta las instancias Handle y TimerHandle las cuales son retornadas por métodos planificados como loop.call_soon() y loop.call_later();

La sección Objetos del servidor documenta tipos retornados por los métodos del bucle de eventos como loop.create_server();

La sección Implementaciones de bucle de eventos documenta las clases SelectorEventLoop y ProactorEventLoop;

La sección Ejemplos muestra como trabajar con algunas APIs de bucle de eventos.

Métodos del bucle de eventos

Los bucles de eventos tienen APIs de bajo nivel para lo siguiente:

Iniciar y para el bucle

Programación de llamadas de retorno

Planificando llamadas retardadas

Creando Futuros y Tareas

Abriendo conexiones de red

Creando servidores de red

Transfiriendo archivos

Actualización de TLS

Viendo descriptores de archivos

Trabajar con objetos sockets directamente

DNS

Trabajando con tuberías

Señales Unix

Ejecutando código en un hilos o grupos de procesos

API para manejo de errores

Habilitando el modo depuración

Ejecutando Subprocesos

Iniciar y para el bucle

loop.run_until_complete(future)

Se ejecuta hasta que future (una instancia de Future) se haya completado.

Si el argumento es un objeto corrutina está implícitamente planificado para ejecutarse como una asyncio.Task.

Retorna el resultado del Futuro o genera una excepción.

loop.run_forever()

Ejecuta el bucle de eventos hasta que stop() es llamado.

Si stop() es llamado antes que run_forever(), el bucle va a sondear el selector de E/S una sola vez con un plazo de ejecución de cero, ejecuta todas las llamadas planificadas como respuesta a eventos E/S (y aquellas que ya hayan sido planificados), y entonces termina.

Si stop() es llamado mientras run_forever() se está ejecutando, el loop ejecutará el lote actual de llamadas y después finalizará. Tenga en cuenta que llamadas planificadas por otras llamadas no se ejecutarán en este caso; en su lugar, ellas correrán la próxima vez que run_forever() o run_until_complete() sean llamados.

loop.stop()

Detener el bucle de eventos.

loop.is_running()

Retorna True si el bucle de eventos esta en ejecución actualmente.

loop.is_closed()

Retorna True si el bucle de eventos se cerró.

loop.close()

Cierra el bucle de eventos.

El bucle no debe estar en ejecución cuando se llama a esta función. Cualquier llamada de retorno pendiente será descartada.

Este método limpia todas las colas y apaga el ejecutor, pero no espera a que el ejecutor termine.

Este método es idempotente e irreversible. No se debe llamar ningún otro método después que el bucle de eventos es cerrado.

coroutine loop.shutdown_asyncgens()

Programa todos los objetos asynchronous generator abiertos actualmente para cerrarlos con una llamada aclose(). Después de llamar este método, el bucle de eventos emitirá una advertencia si un nuevo generador asíncrono es iterado. Esto debe ser usado para finalizar de manera confiable todos los generadores asíncronos planificados.

Tenga en cuenta que no hay necesidad de llamar esta función cuando asyncio.run() es utilizado.

Ejemplo:

try:
    loop.run_forever()
finally:
    loop.run_until_complete(loop.shutdown_asyncgens())
    loop.close()

Nuevo en la versión 3.6.

coroutine loop.shutdown_default_executor()

Programa el cierre del ejecutor predeterminado y espere a que se una a todos los hilos de la clase ThreadPoolExecutor. Después de llamar a este método, se generará un RuntimeError si se llama a loop.run_in_executor() mientras se usa el ejecutor predeterminado.

Tenga en cuenta que no hay necesidad de llamar esta función cuando asyncio.run() es utilizado.

Nuevo en la versión 3.9.

Programación de llamadas de retorno

loop.call_soon(callback, *args, context=None)

Programa el callback (retrollamada) callback para que se llame con argumentos args en la próxima iteración del ciclo de eventos.

Llamadas que son ejecutadas en el orden en el que fueron registradas. Cada llamada será ejecutada exactamente una sola vez.

Un argumento context opcional y solo de palabra clave que permite especificar una clase contextvars.Context personalizada en la cual callback será ejecutada. Cuando no se provee context el contexto actual es utilizado.

Una instancia de asyncio.Handle es retornada, que puede ser utilizada después para cancelar la llamada.

Este método no es seguro para subprocesos.

loop.call_soon_threadsafe(callback, *args, context=None)

Una variante de call_soon() que es segura para subprocesos. Debe ser usada en llamadas planificadas desde otro hilo.

Raises RuntimeError if called on a loop that’s been closed. This can happen on a secondary thread when the main application is shutting down.

Vea sección concurrencia y multiproceso de la documentación.

Distinto en la versión 3.7: Fue agregado el parámetro solo de palabra clave context. Vea PEP 567 [https://www.python.org/dev/peps/pep-0567] para mas detalles.

Nota

La mayoría de las funciones planificadas de asyncio no permiten pasar argumentos de palabra clave. Para hacer eso utilice functools.partial():

# will schedule "print("Hello", flush=True)"
loop.call_soon(
    functools.partial(print, "Hello", flush=True))

El uso de objetos parciales es usualmente mas conveniente que utilizar lambdas, ya que asyncio puede renderizar mejor objetos parciales en mensajes de depuración y error.

Planificando llamadas retardadas

El bucle de eventos provee mecanismos para planificar funciones de llamadas que serán ejecutadas en algún punto en el futuro. El bucle de eventos usa relojes monotónicos para seguir el tiempo.

loop.call_later(delay, callback, *args, context=None)

Planifica callback para ser ejecutada luego de delay número de segundos (puede ser tanto un entero como un flotante).

Una instancia de asyncio.TimerHandle es retornada, la que puede ser utilizada para cancelar la ejecución.

callback será ejecutada exactamente una sola vez. Si dos llamadas son planificadas para el mismo momento exacto, el orden en el que son ejecutadas es indefinido.

El argumento posicional opcional args será pasado a la llamada cuando esta sea ejecutada. Si quieres que la llamada sea ejecutada con argumentos de palabra clave usa functools.partial().

Un argumento context opcional y solo de palabra clave que permite especificar una clase contextvars.Context personalizada en la cual callback será ejecutada. Cuando no se provee context el contexto actual es utilizado.

Distinto en la versión 3.7: Fue agregado el parámetro solo de palabra clave context. Vea PEP 567 [https://www.python.org/dev/peps/pep-0567] para mas detalles.

Distinto en la versión 3.8: En Python 3.7 y versiones anteriores con la implementación del bucle de eventos predeterminada, el delay no puede exceder un día. Esto fue arreglado en Python 3.8.

loop.call_at(when, callback, *args, context=None)

Planifica callback para ser ejecutada en una marca de tiempo absoluta when (un entero o un flotante), usando la misma referencia de tiempo que loop.time().

El comportamiento de este método es el mismo que call_later().

Una instancia de asyncio.TimerHandle es retornada, la que puede ser utilizada para cancelar la ejecución.

Distinto en la versión 3.7: Fue agregado el parámetro solo de palabra clave context. Vea PEP 567 [https://www.python.org/dev/peps/pep-0567] para mas detalles.

Distinto en la versión 3.8: En Python 3.7 y versiones anteriores con la implementación del bucle de eventos predeterminada, la diferencia entre when y el tiempo actual no puede exceder un día. Esto fue arreglado en Python 3.8.

loop.time()

Retorna el tiempo actual, como un float, de acuerdo al reloj monotónico interno del bucle de evento.

Nota

Distinto en la versión 3.8: En Python 3.7 y versiones anteriores los tiempos de espera (delay relativo o when absoluto) no deben exceder un día. Esto fue arreglado en Python 3.8.

Ver también

La función asyncio.sleep().

Creando Futuros y Tareas

loop.create_future()

Crea un objeto asyncio.Future adjunto al bucle de eventos.

Esta es la manera preferida de crear Futures en asyncio. Esto permite que bucles de eventos de terceros provean implementaciones alternativas del objeto Future (con mejor rendimiento o instrumentación).

Nuevo en la versión 3.5.2.

loop.create_task(coro, *, name=None)

Planifica la ejecución de una Corrutinas. Retorna un objeto Task.

Bucles de eventos de terceros pueden usar sus propias subclases de Task por interoperabilidad. En este caso, el tipo de resultado es una subclase de Task.

Si el argumento name es provisto y no None, se establece como el nombre de la tarea usando Task.set_name().

Distinto en la versión 3.8: Agregado el parámetro name.

loop.set_task_factory(factory)

Establece una fábrica de tareas que será utilizada por loop.create_task().

Si factory es None se establecerá la fábrica de tareas por defecto. En cualquier otro caso, factory debe ser un callable con la misma firma (loop, coro), donde loop es una referencia al bucle de eventos activo y coro es un objeto de corrutina. El ejecutable debe retornar una objeto asyncio.Future compatible.

loop.get_task_factory()

Retorna una fábrica de tareas o None si la predefinida está en uso.

Abriendo conexiones de red

coroutine loop.create_connection(protocol_factory, host=None, port=None, *, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None, ssl_handshake_timeout=None, happy_eyeballs_delay=None, interleave=None)

Abre una conexión de transmisión de transporte a una dirección especificada por host y port.

La familia de sockets puede ser tanto AF_INET como AF_INET6 dependiendo de host (o del argumento family si es que fue provisto).

El tipo de socket será SOCK_STREAM.

protocol_factory debe ser un ejecutable que retorna una implementación del asyncio protocol.

Este método tratará de establecer la conexión en un segundo plano. Cuando es exitosa, retorna un par (transport, protocol).

La sinopsis cronológica de las operaciones subyacentes es como sigue:

La conexión es establecida y un transporte es creado para ello.

protocol_factory es llamado sin argumentos y se espera que retorne una instancia de protocol.

La instancia del protocolo se acopla con el transporte mediante el llamado de su método connection_made().

Una tupla (transport, protocol) es retornada cuando se tiene éxito.

El transporte creado es una transmisión (stream) bidireccional que depende de la implementación.

Otros argumentos:

ssl: si se provee y no es falso, un transporte SSL/TLS es creado (de manera predeterminada se crea un transporte TCP plano). Si ssl es un objeto ssl.SSLContext, este contexto es utilizado para crear el transporte; si ssl es True, se utiliza un contexto predeterminado retornado por ssl.create_default_context().

Ver también

Consideraciones de seguridad SSL/TLS

server_hostname establece o reemplaza el nombre de servidor (hostname) contra el cual el certificado del servidor de destino será comparado. Sólo debería ser pasado si ssl no es None. De manera predeterminada es usado el valor del argumento host. Si host está vacío, no hay valor predeterminado y debes pasar un valor para server_hostname. Si server_hostname es una cadena vacía, la comparación de nombres de servidores es deshabilitada (lo que es un riesgo de seguridad serio, permitiendo potenciales ataques de hombre-en-el-medio, man-in-the-middle attacks).

family, proto, flags son dirección de familia, protocolo y banderas opcionales que serán pasadas a través de getaddrinfo() para la resolución de host. Si están dados, todos ellos deberían ser enteros de las constantes del módulo socket correspondiente.

happy_eyeballs_delay, si se proporciona, habilita Happy Eyeballs para esta conexión. Debe ser un número de punto flotante que represente la cantidad de tiempo en segundos para esperar a que se complete un intento de conexión, antes de comenzar el siguiente intento en paralelo. Este es el «Retraso de intento de conexión» como se define en RFC 8305 [https://tools.ietf.org/html/rfc8305.html]. Un valor predeterminado sensato recomendado por el RFC es 0.25 (250 milisegundos).

interleave controla reordenamientos de dirección cuando un nombre de servidor resuelve a múltiples direcciones IP. Si es 0 o no es especificado, no se hace ningún reordenamiento, y las direcciones son intentadas en el orden retornado por getaddrinfo(). Si un entero positivo es especificado, las direcciones son intercaladas por dirección de familia, y el entero dado es interpretado como «Número de familias de la primera dirección» (First Address Family Count) como es definida en RFC 8305 [https://tools.ietf.org/html/rfc8305.html]. El valor predefinido es 0 si happy_eyeballs_delay no es especificado, y 1 si lo es.

sock, si está dado, debe ser un objeto socket.socket existente y ya conectado, que será utilizado por el transporte. Si sock es dado, ningún host, port, family, proto, flags, happy_eyeballs_delay, interleave o local_addr deben ser especificados.

local_addr, if given, is a (local_host, local_port) tuple used to bind the socket locally. The local_host and local_port are looked up using getaddrinfo(), similarly to host and port.

ssl_handshake_timeout es (para una conexión TLS) el tiempo en segundos a esperar que se complete el apretón de manos (handshake) TLS antes de abortar la conexión. 60.0 segundos si es None (predefinido).

Nuevo en la versión 3.8: Agregados los parámetros happy_eyeballs_delay y interleave.

Algoritmo de Globos Oculares Felices (Happy Eyeballs): Éxito con Servidores de Doble-Pila (Dual-Stack Hosts). Cuando la ruta IPv4 y el protocolo de un servidor están funcionando, pero la ruta IPv6 y el protocolo no están funcionando, una aplicación del cliente de doble-pila experimenta una demora de conexión significante en comparación con un cliente sólo de IPv4. Esto no es deseable porque causa que el cliente de doble-pila tenga la peor experiencia de usuario. Este documento especifica requerimientos para algoritmos que reducen esta demora visible por el usuario, y provee un algoritmo.

Para mas información: https://tools.ietf.org/html/rfc6555

Nuevo en la versión 3.7: El parámetro ssl_handshake_timeout.

Distinto en la versión 3.6: La opción del socket TCP_NODELAY es establecida de manera predeterminada para todas las conexiones TCP.

Distinto en la versión 3.5: Agregado el soporte para SSL/TLS en ProactorEventLoop.

Ver también

La función open_connection() es una API alternativa de alto nivel. Retorna un par de (StreamReader, StreamWriter) que puede ser usado directamente en código async/await.

coroutine loop.create_datagram_endpoint(protocol_factory, local_addr=None, remote_addr=None, *, family=0, proto=0, flags=0, reuse_address=None, reuse_port=None, allow_broadcast=None, sock=None)

Nota

El parámetro reuse_address ya no es soportado, como utiliza SO_REUSEADDR plantea un problema de seguridad importante para UDP. Pasando explícitamente reuse_address=True lanzará una excepción.

Cuando múltiples procesos con UIDs diferentes asignan sockets a una misma dirección socket UDP con SO_REUSEADDR, los paquetes entrantes pueden distribuirse aleatoriamente entre los sockets.

Para plataformas soportadas, reuse_port puede ser utilizado como un reemplazo para funcionalidades similares. Con reuse_port, SO_REUSEPORT es usado en su lugar, que específicamente previene que procesos con distintos UIDs asignen sockets a la misma dirección de socket.

Crea un datagrama de conexión.

La familia de socket puede ser tanto AF_INET, AF_INET6, como AF_UNIX, dependiendo de host (o del argumento family, si fue provisto).

El tipo de socket será SOCK_DGRAM.

protocol_factory debe ser un ejecutable que retorne una implementación de protocol.

Una tupla de (transport, protocol) es retornada cuando se tiene éxito.

Otros argumentos:

local_addr, if given, is a (local_host, local_port) tuple used to bind the socket locally. The local_host and local_port are looked up using getaddrinfo().

remote_addr, si está dado, es una tupla (remote_host, remote_port) utilizada para conectar el socket a una dirección remota. Los remote_host y remote_port son buscados utilizando getaddrinfo().

family, proto, flags son direcciones de familia, protocolo y banderas opcionales que serán pasadas a través de getaddrinfo() para la resolución de host. Si está dado, estos deben ser todos enteros de las constantes del módulo socket correspondiente.

reuse_port dice al kernel que habilite este punto de conexión para ser unido al mismo puerto de la misma forma que otros puntos de conexión existentes también están unidos, siempre y cuando todos ellos establezcan esta bandera al ser creados. Esta opción no es soportada en Windows y algunos sistemas Unix. Si la constante SO_REUSEPORT no está definida entonces esta funcionalidad no es soportada.

allow_broadcast dice al kernel que habilite este punto de conexión para enviar mensajes a la dirección de transmisión (broadcast).

sock puede opcionalmente ser especificado para usar un objeto socket.socket preexistente y ya conectado que será utilizado por el transporte. Si están especificados, local_addr y remote_addr deben ser omitidos (tienen que ser None).

Refiérase a los ejemplos UDP echo client protocol y UDP echo server protocol.

Distinto en la versión 3.4.4: Los parámetros family, proto, flags, reuse_address, reuse_port, allow_broadcast y sock fueron agregados.

Distinto en la versión 3.8.1: El parámetro reuse_address ya no es soportado debido a problemas de seguridad.

Distinto en la versión 3.8: Se agregó soporte para Windows.

coroutine loop.create_unix_connection(protocol_factory, path=None, *, ssl=None, sock=None, server_hostname=None, ssl_handshake_timeout=None)

Crear una conexión Unix.

La familia de sockets será AF_UNIX; el tipo de socket será SOCK_STREAM.

Una tupla de (transport, protocol) es retornada cuando se tiene éxito.

path es el nombre de un dominio de un socket Unix y es requerido, a menos que un parámetro sock sea especificado. Los socket Unix abstractos, str, bytes, y Path son soportados.

Vea la documentación del método loop.create_connection() para información acerca de los argumentos de este método.

Availability: Unix.

Nuevo en la versión 3.7: El parámetro ssl_handshake_timeout.

Distinto en la versión 3.7: El parámetro path ahora puede ser un path-like object.

Creando servidores de red

coroutine loop.create_server(protocol_factory, host=None, port=None, *, family=socket.AF_UNSPEC, flags=socket.AI_PASSIVE, sock=None, backlog=100, ssl=None, reuse_address=None, reuse_port=None, ssl_handshake_timeout=None, start_serving=True)

Crea un servidor TCP (tipo de socket SOCK_STREAM) escuchando en port de la dirección host.

Retorna un objeto Server.

Argumentos:

protocol_factory debe ser un ejecutable que retorne una implementación de protocol.

El parámetro host puede ser establecido a distintos tipos que determinan donde el servidor estaría escuchando:

Si host es una cadena, el servidor TCP está enlazado a una sola interfaz de red especificada por host.

Si host es una secuencia de cadenas, el servidor TCP está enlazado a todas las interfaces de red especificadas por la secuencia.

Si host es una cadena vacía o None, se asumen todas las interfaces y una lista con múltiples sockets será retornada (mas probablemente uno para IPv4 y otro para IPv6).

The port parameter can be set to specify which port the server should listen on. If 0 or None (the default), a random unused port will be selected (note that if host resolves to multiple network interfaces, a different random port will be selected for each interface).

family puede ser establecido como socket.AF_INET o AF_INET6 para forzar al socket a usar IPv4 o IPv6. Si no es establecido, la family será determinada por medio del nombre del host (por defecto será AF_UNSPEC).

flags es una máscara de bits para getaddrinfo().

sock puede ser especificado opcionalmente para usar objetos socket preexistentes. Si se utiliza, entonces host y port no deben ser especificados.

backlog es el número máximo de conexiones encoladas pasadas a listen() (el valor predeterminado es 100).

ssl puede ser establecido como una instancia de SSLContext para habilitar TLS sobre las conexiones aceptadas.

reuse_address indica al kernel que reutilice un socket local en estado TIME_WAIT, sin esperar que su plazo de ejecución expire. Si no es especificado será establecido automáticamente como True en Unix.

reuse_port dice al kernel que habilite este punto de conexión para ser unido al mismo puerto de la misma forma que otros puntos de conexión existentes también están unidos, siempre y cuando todos ellos establezcan esta bandera al ser creados.

ssl_handshake_timeout es (para un servidor TLS) el tiempo en segundos a esperar por el apretón de manos (handshake) TLS a ser completado antes de abortar la conexión. 60.0 si es None (su valor predeterminado).

start_serving establecido como True (de manera predeterminada) produce que los servidores creados comiencen a aceptar conexiones inmediatamente. Si es establecido como False, el usuario debe esperar por Server.start_serving() o Server.serve_forever() para que el servidor comience a aceptar conexiones.

Nuevo en la versión 3.7: Agregados los parámetros ssl_handshake_timeout y start_serving.

Distinto en la versión 3.6: La opción del socket TCP_NODELAY es establecida de manera predeterminada para todas las conexiones TCP.

Distinto en la versión 3.5: Agregado el soporte para SSL/TLS en ProactorEventLoop.

Distinto en la versión 3.5.1: El parámetro host puede ser una secuencia de cadenas.

Ver también

La función start_server() es una API alternativa de alto nivel que retorna un par de StreamReader y StreamWriter que pueden ser usados en código async/await.

coroutine loop.create_unix_server(protocol_factory, path=None, *, sock=None, backlog=100, ssl=None, ssl_handshake_timeout=None, start_serving=True)

Similar a loop.create_server() pero funciona con la familia de sockets AF_UNIX.

path es el nombre de un dominio de socket Unix, y es requerido a menos que el argumento sock sea provisto. Son soportados sockets unix abstractos, str, bytes, y rutas Path.

Vea la documentación de el método loop.create_server() para mas información acerca de los argumentos de este método.

Availability: Unix.

Nuevo en la versión 3.7: Los parámetros ssl_handshake_timeout*y *start_serving.

Distinto en la versión 3.7: El parámetro path ahora puede ser un objeto Path.

coroutine loop.connect_accepted_socket(protocol_factory, sock, *, ssl=None, ssl_handshake_timeout=None)

Envuelve una conexión ya aceptada en un par de transporte/protocolo.

Este método puede ser usado por servidores que acepten conexiones por fuera de asyncio, pero que usen asyncio para manejarlas.

Parámetros:

protocol_factory debe ser un ejecutable que retorne una implementación de protocol.

sock es un objeto socket preexistente retornado por socket.accept.

ssl puede ser establecido como un SSLContext para habilitar SSL sobre las conexiones aceptadas.

ssl_handshake_timeout es (para una conexión SSL) el tiempo en segundos que se esperará para que se complete el apretón de manos (handshake) SSL antes de abortar la conexión. 60.0 si es None (su valor predeterminado).

Retorna un par (transport, protocol).

Nuevo en la versión 3.7: El parámetro ssl_handshake_timeout.

Nuevo en la versión 3.5.3.

Transfiriendo archivos

coroutine loop.sendfile(transport, file, offset=0, count=None, *, fallback=True)

Envía un file a través de un transport. Retorna el numero total de bytes enviados.

El método usa os.sendfile() de alto rendimiento si está disponible.

file debe ser un objeto de archivo regular abierto en modo binario.

offset indica desde donde se empezará a leer el archivo. Si es especificado, count es el número total de bytes a transmitir en contraposición con enviar el archivo hasta que se alcance EOF. La posición del archivo es actualizada siempre, incluso cuando este método genere un error, y file.tell() puede ser usado para obtener el número de bytes enviados hasta el momento.

fallback establecido como True hace que asyncio lea y envíe el archivo manualmente cuando la plataforma no soporta la llamada de envío de archivos del sistema (por ejemplo, Windows o sockets SSL en Unix).

Lanza SendfileNotAvailableError si el sistema no soporta la llamada de envío de archivos del sistema y fallback es True.

Nuevo en la versión 3.7.

Actualización de TLS

coroutine loop.start_tls(transport, protocol, sslcontext, *, server_side=False, server_hostname=None, ssl_handshake_timeout=None)

Actualiza una conexión basada en transporte ya existente a TLS.

Retorna una nueva instancia de transporte, que el protocol debe empezar a usar inmediatamente después del await. La instancia transport pasada al método start_tls nunca debe ser usada de nuevo.

Parámetros:

Las instancias transport y protocol que retornan los métodos como create_server() y create_connection().

sslcontext: una instancia configurada de SSLContext.

server_side pasa True cuando se actualiza una conexión del lado del servidor (como en el caso de una creada por create_server()).

server_hostname: establece o reemplaza el nombre del host contra el cual se compara el certificado del servidor de destino.

ssl_handshake_timeout es (para una conexión TLS) el tiempo en segundos a esperar que se complete el apretón de manos (handshake) TLS antes de abortar la conexión. 60.0 segundos si es None (predefinido).

Nuevo en la versión 3.7.

Viendo descriptores de archivos

loop.add_reader(fd, callback, *args)

Empieza a monitorear el descriptor de archivos fd para disponibilidad de lectura e invoca callback con los argumentos especificados una vez que fd está habilitado para ser leído.

loop.remove_reader(fd)

Deja de monitorear el descriptor de archivos fd para disponibilidad de lectura.

loop.add_writer(fd, callback, *args)

Empieza a monitorear el descriptor de archivos fd para disponibilidad de escritura e invoca callback con los argumentos especificados una vez que fd está habilitado para ser escrito.

Use functools.partial() para pasar argumentos de palabra clave a callback.

loop.remove_writer(fd)

Deja de monitorear el descriptor de archivos fd para disponibilidad de escritura.

Vea también la sección Soporte de plataforma para algunas limitaciones de estos métodos.

Trabajar con objetos sockets directamente

En general, implementaciones de protocolo que usen APIs basadas en transporte como loop.create_connection() y loop.create_server() son mas rápidas que aquellas implementaciones que trabajan con directamente con sockets. De cualquier forma, hay algunos casos de uso en los cuales el rendimiento no es crítico, y trabajar directamente con objetos socket es mas conveniente.

coroutine loop.sock_recv(sock, nbytes)

Recibe hasta nbytes de sock. Versión asíncrona de socket.recv().

Retorna los datos recibidos como un objeto bytes.

sock debe ser un socket no bloqueante.

Distinto en la versión 3.7: A pesar de que este método siempre fue documentado como un método de corrutina, los lanzamientos previos a Python 3.7 retornaban un Future. Desde Python 3.7 este es un método async def.

coroutine loop.sock_recv_into(sock, buf)

Recibe datos desde sock en el búfer buf. Modelado después del método bloqueante socket.recv_into().

Retorna el número de bytes escritos en el búfer.

sock debe ser un socket no bloqueante.

Nuevo en la versión 3.7.

coroutine loop.sock_sendall(sock, data)

Envía data al socket sock. Versión asíncrona de socket.sendall().

Este método continua enviando al socket hasta que se hayan enviado todos los datos en data u ocurra un error. None es retornado cuando se tiene éxito. Cuando ocurre un error, se lanza una excepción. Adicionalmente, no hay manera de determinar cuantos datos, si es que se hubo alguno, se procesaron correctamente por el extremo receptor de la conexión.

sock debe ser un socket no bloqueante.

Distinto en la versión 3.7: A pesar de que este método siempre fue documentado como un método de corrutina, antes de Python 3.7 retorna un Future. Desde Python 3.7, este es un método async def.

coroutine loop.sock_connect(sock, address)

Conecta sock a un socket remoto en address.

Versión asíncrona de socket.connect().

sock debe ser un socket no bloqueante.

Distinto en la versión 3.5.2: address ya no necesita ser resuelto. sock_connect va a intentar verificar si address ya fue resuelto a partir del llamado de socket.inet_pton(). Si no lo fue, se utilizará loop.getaddrinfo() ara resolver address.

Ver también

loop.create_connection() y asyncio.open_connection().

coroutine loop.sock_accept(sock)

Acepta una conexión. Modelado después del método bloqueante socket.accept().

The socket must be bound to an address and listening for connections. The return value is a pair (conn, address) where conn is a new socket object usable to send and receive data on the connection, and address is the address bound to the socket on the other end of the connection.

sock debe ser un socket no bloqueante.

Distinto en la versión 3.7: A pesar de que este método siempre fue documentado como un método de corrutina, antes de Python 3.7 retorna un Future. Desde Python 3.7, este es un método async def.

Ver también

loop.create_server() y start_server().

coroutine loop.sock_sendfile(sock, file, offset=0, count=None, *, fallback=True)

Envía un archivo usando os.sendfile de alto rendimiento si es posible. Retorna el número total de bytes enviados.

Versión asíncrona de socket.sendfile().

sock debe ser un socket.SOCK_STREAM socket no bloqueante.

file debe ser un objeto de archivo regular abierto en modo binario.

offset indica desde donde se empezará a leer el archivo. Si es especificado, count es el número total de bytes a transmitir en contraposición con enviar el archivo hasta que se alcance EOF. La posición del archivo es actualizada siempre, incluso cuando este método genere un error, y file.tell() puede ser usado para obtener el número de bytes enviados hasta el momento.

fallback, cuando es establecida como True, hace que asyncio lea y escriba el archivo manualmente cuando el sistema no soporta la llamada de envío de archivos del sistema (por ejemplo, Windows o sockets SSL en Unix).

Lanza SendfileNotAvailableError si el sistema no soporta la llamada de envío de archivos del sistema sendfile y fallback es False.

sock debe ser un socket no bloqueante.

Nuevo en la versión 3.7.

DNS

coroutine loop.getaddrinfo(host, port, *, family=0, type=0, proto=0, flags=0)

Versión asíncrona de socket.getaddrinfo().

coroutine loop.getnameinfo(sockaddr, flags=0)

Asynchronous version of socket.getnameinfo().

Distinto en la versión 3.7: Ambos métodos getaddrinfo y getnameinfo siempre fueron documentados para retornar una corrutina, pero antes de Python 3.7 retornaban, de hecho, objetos Future. A partir de Python 3.7, ambos métodos son corrutinas.

Trabajando con tuberías

coroutine loop.connect_read_pipe(protocol_factory, pipe)

Registra el fin de lectura de pipe en el bucle de eventos.

protocol_factory debe ser un ejecutable que retorna una implementación del asyncio protocol.

pipe es un objeto de tipo archivo.

Retorna un par (transport, protocol), donde transport soporta la interface ReadTransport y protocol es un objeto instanciado por protocol_factory.

Con el bucle de eventos SelectorEventLoop, el pipe es establecido en modo no bloqueante.

coroutine loop.connect_write_pipe(protocol_factory, pipe)

Registra el fin de escritura de pipe en el bucle de eventos.

protocol_factory debe ser un ejecutable que retorna una implementación del asyncio protocol.

pipe es un objeto de tipo archivo.

Retorna un par (transport, protocol), donde transport soporta la interface WriteTransport y protocol es un objeto inicializado por protocol_factory.

Con el bucle de eventos SelectorEventLoop, el pipe es establecido en modo no bloqueante.

Nota

SelectorEventLoop no soporta los métodos anteriores en windows. En su lugar, use ProactorEventLoop para Windows.

Ver también

Los métodos loop.subprocess_exec() y loop.subprocess_shell().

Señales Unix

loop.add_signal_handler(signum, callback, *args)

Establece callback como el gestor para la señal signum.

La llamada será invocada por loop, junto con otras llamadas encoladas y corrutinas ejecutables de ese bucle de eventos. A menos que los gestores de señal la registren usando signal.signal(), una llamada registrada con esta función tiene permitido interactuar con el bucle de eventos.

Lanza ValueError si el número de señal es invalido o inalcanzable. Lanza RuntimeError si hay algún problema preparando el gestor.

Use functools.partial() para pasar argumentos de palabra clave a callback.

Como signal.signal(), esta función debe ser invocada en el hilo principal.

loop.remove_signal_handler(sig)

Elimina el gestor para la señal sig.

Retorna True si el gestor de señal fue eliminado, o False si no se estableció gestor para la señal dada.

Availability: Unix.

Ver también

El módulo signal.

Ejecutando código en un hilos o grupos de procesos

awaitable loop.run_in_executor(executor, func, *args)

Hace arreglos para que func sea llamado en el ejecutor especificado.

El argumento executor debe ser una instancia de concurrent.futures.Executor. El ejecutor predeterminado es usado si executor es None.

Ejemplo:

import asyncio
import concurrent.futures

def blocking_io():
    # File operations (such as logging) can block the
    # event loop: run them in a thread pool.
    with open('/dev/urandom', 'rb') as f:
        return f.read(100)

def cpu_bound():
    # CPU-bound operations will block the event loop:
    # in general it is preferable to run them in a
    # process pool.
    return sum(i * i for i in range(10 ** 7))

async def main():
    loop = asyncio.get_running_loop()

    ## Options:

    # 1. Run in the default loop's executor:
    result = await loop.run_in_executor(
        None, blocking_io)
    print('default thread pool', result)

    # 2. Run in a custom thread pool:
    with concurrent.futures.ThreadPoolExecutor() as pool:
        result = await loop.run_in_executor(
            pool, blocking_io)
        print('custom thread pool', result)

    # 3. Run in a custom process pool:
    with concurrent.futures.ProcessPoolExecutor() as pool:
        result = await loop.run_in_executor(
            pool, cpu_bound)
        print('custom process pool', result)

asyncio.run(main())

Este método retorna un objeto asyncio.Future.

Use functools.partial() para pasar argumentos de palabra clave a func.

Distinto en la versión 3.5.3: loop.run_in_executor() ya no configura el max_workers del ejecutor del grupo de subprocesos que crea, sino que lo deja en manos del ejecutor del grupo de subprocesos (ThreadPoolExecutor) para establecer el valor por defecto.

loop.set_default_executor(executor)

Establece executor como el ejecutor predeterminado utilizado por run_in_executor(). executor debe ser una instancia de ThreadPoolExecutor.

Obsoleto desde la versión 3.8: Usar un ejecutor que no es una instancia de ThreadPoolExecutor es obsoleto y disparará un error en Python 3.9.

executor debe ser una instancia de concurrent.futures.ThreadPoolExecutor.

API para manejo de errores

Permite personalizar como son manejadas las excepciones en el bucle de eventos.

loop.set_exception_handler(handler)

Establece handler como el nuevo gestor de excepciones del bucle de eventos.

Si handler es None, se establecerá el gestor de excepciones predeterminado. De otro modo, handler debe ser un invocable con la misma firma (loop, context), donde loop es una referencia al bucle de eventos activo, y context es un objeto dict que contiene los detalles de la excepción (vea la documentación de call_exception_handler() para detalles acerca del contexto).

loop.get_exception_handler()

Retorna el gesto de excepciones actual, o None si no fue establecido ningún gestor de excepciones personalizado.

Nuevo en la versión 3.5.2.

loop.default_exception_handler(context)

Gestor de excepciones por defecto.

Esto es llamado cuando ocurre una excepción y no se estableció ningún gestor de excepciones. Esto puede ser llamado por un gestor de excepciones personalizado que quiera cambiar el comportamiento del gestor predeterminado.

El parámetro context tiene el mismo significado que en call_exception_handler().

loop.call_exception_handler(context)

Llama al gestor de excepciones del bucle de eventos actual.

context es un objeto dict conteniendo las siguientes claves (en futuras versiones de Python podrían introducirse nuevas claves):

“message”: Mensaje de error;

“exception” (opcional): Objeto de excepción;

“future” (opcional): instancia de asyncio.Future;

“task” (optional): asyncio.Task instance;

“handle” (opcional): instancia de asyncio.Handle;

“protocol” (opcional): instancia de Protocol;

“transport” (opcional): instancia de Transport;

“socket” (optional): socket.socket instance;

“asyncgen” (optional): Asynchronous generator that caused

the exception.

Nota

Este método no debe ser sobrecargado en bucles de eventos en subclase. Para gestión de excepciones personalizadas, use el método set_exception_handler().

Habilitando el modo depuración

loop.get_debug()

Obtiene el modo depuración (bool) del bucle de eventos.

El valor predeterminado es True si la variable de entorno PYTHONASYNCIODEBUG es establecida a una cadena no vacía, de otro modo será False.

loop.set_debug(enabled: bool)

Establece el modo de depuración del bucle de eventos.

Distinto en la versión 3.7: El nuevo Python Modo de Desarrollo ahora también se puede usar para habilitar el modo de depuración.

Ver también

El modo depuración de asyncio.

Ejecutando Subprocesos

Los métodos descritos en esta subsección son de bajo nivel. En código async/await regular considere usar las convenientes funciones de alto nivel asyncio.create_subprocess_shell() y asyncio.create_subprocess_exec().

Nota

On Windows, the default event loop ProactorEventLoop supports subprocesses, whereas SelectorEventLoop does not. See Subprocess Support on Windows for details.

coroutine loop.subprocess_exec(protocol_factory, *args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, **kwargs)

Crea un subproceso de uno o mas argumentos de cadena especificados por args.

args debe ser una lista de cadenas representadas por:

str;

o bytes, codificados a la codificación del sistema de archivos.

La primer cadena especifica el programa ejecutable, y las cadenas restantes especifican los argumentos. En conjunto, los argumentos de cadena forman el argv del programa.

Esto es similar a la clase de la librería estándar subprocess.Popen llamada con shell=False y la lista de cadenas pasadas como el primer argumento; de cualquier forma, cuando Popen toma un sólo argumento que es una lista de cadenas, subprocess_exec toma múltiples cadenas como argumentos.

El protocol_factory debe ser un ejecutable que retorne una subclase de la clase asyncio.SubprocessProtocol.

Otros parámetros:

stdin puede ser cualquier de estos:

un objeto de tipo archivo representando una tubería que será conectada al flujo de entrada estándar del subproceso utilizando connect_write_pipe()

la constante subprocess.PIPE (predeterminado) que creará una tubería nueva y la conectará,

el valor None que hará que el subproceso herede el descriptor de archivo de este proceso

la constante subprocess.DEVNULL que indica que el archivo especial os.devnull será utilizado

stdout puede ser cualquier de estos:

un objeto de tipo archivo representando una tubería que será conectada al flujo de salida estándar del subproceso utilizando connect_write_pipe()

la constante subprocess.PIPE (predeterminado) que creará una tubería nueva y la conectará,

el valor None que hará que el subproceso herede el descriptor de archivo de este proceso

la constante subprocess.DEVNULL que indica que el archivo especial os.devnull será utilizado

stderr puede ser cualquier de estos:

un objeto de tipo archivo representando una tubería que será conectada al flujo de error estándar del subproceso utilizando connect_write_pipe()

la constante subprocess.PIPE (predeterminado) que creará una tubería nueva y la conectará,

el valor None que hará que el subproceso herede el descriptor de archivo de este proceso

la constante subprocess.DEVNULL que indica que el archivo especial os.devnull será utilizado

la constante subprocess.STDOUT que conectará el flujo de errores predeterminado al flujo de salida predeterminado del proceso

El resto de argumentos de palabra clave son pasados a subprocess.Popen sin interpretación, excepto por bufsize, universal_newlines, shell, text, encoding y errors, que no deben ser especificados en lo absoluto.

La API subproceso asyncio no soporta decodificar los flujos como texto. bytes.decode() puede ser usado para convertir a texto los bytes retornados por el flujo.

Vea el constructor de la clase subprocess.Popen para documentación acerca de otros argumentos.

Retorna un par de (transport, protocol), donde transport se ajusta a la clase base asyncio.SubprocessTransport y protocol es un objeto instanciado por protocol_factory.

coroutine loop.subprocess_shell(protocol_factory, cmd, *, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, **kwargs)

Crea un subproceso desde cmd, que puede ser una cadena str o bytes codificado a la codificación del sistema de archivos, usando la sintaxis «shell» de la plataforma.

Esto es similar a la clase de la librería estándar subprocess.Popen llamada con shell=True.

El protocol_factory debe ser un ejecutable que retorne una subclase de la clase asyncio.SubprocessProtocol.

Vea subprocess_exec() para mas detalles acerca de los argumentos restantes.

Retorna un par de (transport, protocol), donde transport se ajusta a la clase base SubprocessTransport y protocol es un objeto instanciado por protocol_factory.

Nota

Es responsabilidad de la aplicación asegurar que todos los espacios en blanco y caracteres especiales estén escapados correctamente para evitar vulnerabilidades de inyección de código [https://en.wikipedia.org/wiki/Shell_injection#Shell_injection]. La función shlex.quote() puede ser usada para escapar apropiadamente espacios en blanco y caracteres especiales en cadenas que van a ser usadas para construir comandos de consola.

Gestores de llamadas

class asyncio.Handle

Un objeto de contenedor de llamada retornado por loop.call_soon(), loop.call_soon_threadsafe().

cancel()

Cancela la llamada. Si la llamada ya fue cancelada o ejecutada, este método no tiene efecto.

cancelled()

Retorna True si la llamada fue cancelada.

Nuevo en la versión 3.7.

class asyncio.TimerHandle

Un objeto de contenedor de llamada retornado por loop.call_later(), and loop.call_at().

Esta clase es una subclase de Handle.

when()

Retorna el tiempo de una llamada planificada como float segundos.

El tiempo es una marca de tiempo absoluta, usando la misma referencia de tiempo que loop.time().

Nuevo en la versión 3.7.

Objetos Servidor

Los objetos de servidor son creados por las funciones loop.create_server(), loop.create_unix_server(), start_server(), y start_unix_server().

No instanciar la clase directamente.

class asyncio.Server

Los objetos Server son gestores de asíncronos de contexto. Cuando son usados en una declaración async with, está garantizado que el objeto Servidor está cerrado y no está aceptando nuevas conexiones cuando la declaración async with es completada:

srv = await loop.create_server(...)

async with srv:
    # some code

# At this point, srv is closed and no longer accepts new connections.

Distinto en la versión 3.7: El objeto Servidor es un gestor asíncrono de contexto desde Python 3.7.

close()

Deja de servir: deja de escuchar sockets y establece el atributo sockets a None.

Los sockets que representan conexiones entrantes existentes de clientes se dejan abiertas.

El servidor es cerrado de manera asíncrona, usa la corrutina wait_closed() para esperar hasta que el servidor esté cerrado.

get_loop()

Retorna el bucle de eventos asociado con el objeto Servidor.

Nuevo en la versión 3.7.

coroutine start_serving()

Comienza a aceptar conexiones.

Este método es idempotente, así que puede ser llamado cuando el servidor ya está sirviendo.

El parámetro sólo de palabra clave start_serving de loop.create_server() y asyncio.start_server() permite crear un objeto Servidor que no está aceptando conexiones inicialmente. En este caso Server.start_serving(), o Server.serve_forever() pueden ser usados para hacer que el servidor empiece a aceptar conexiones.

Nuevo en la versión 3.7.

coroutine serve_forever()

Comienza a aceptar conexiones hasta que la corrutina sea cancelada. La cancelación de la tarea serve_forever hace que el servidor sea cerrado.

Este método puede ser llamado si el servidor ya está aceptando conexiones. Solamente una tarea serve_forever puede existir para un objeto Server.

Ejemplo:

async def client_connected(reader, writer):
    # Communicate with the client with
    # reader/writer streams.  For example:
    await reader.readline()

async def main(host, port):
    srv = await asyncio.start_server(
        client_connected, host, port)
    await srv.serve_forever()

asyncio.run(main('127.0.0.1', 0))

Nuevo en la versión 3.7.

is_serving()

Retorna True si el servidor está aceptando nuevas conexiones.

Nuevo en la versión 3.7.

coroutine wait_closed()

Espera hasta que el método close() se complete.

sockets

Lista todos los objetos socket.socket en los que el servidor está escuchando.

Distinto en la versión 3.7: Antes de Python 3.7 Server.sockets solía retornar directamente una lista interna de servidores socket. En 3.7 se retorna una copia de esa lista.

Implementaciones del bucle de eventos

asyncio viene con dos implementaciones diferentes del bucle de eventos: SelectorEventLoop y ProactorEventLoop.

De manera predefinida asyncio está configurado para usar SelectorEventLoop en Unix y ProactorEventLoop en Windows.

class asyncio.SelectorEventLoop

Un bucle de eventos basado en el módulo selectors.

Usa el selector disponible mas eficiente para la plataforma dada. También es posible configurar manualmente la implementación exacta del selector a utilizar:

import asyncio
import selectors

selector = selectors.SelectSelector()
loop = asyncio.SelectorEventLoop(selector)
asyncio.set_event_loop(loop)

Disponibilidad: Unix, Windows.

class asyncio.ProactorEventLoop

Un bucle de eventos para Windows que usa «E/S Puertos de Finalización» (IOCP).

Disponibilidad: Windows.

Ver también

Documentaci´on de MSDN sobre E/S Puertos de Finalización [https://docs.microsoft.com/en-ca/windows/desktop/FileIO/i-o-completion-ports].

class asyncio.AbstractEventLoop

Clase base abstracta para bucles de evento compatibles con asyncio.

La sección Métodos del bucle de eventos lista todos los métodos que como implementación alternativa de AbstractEventLoop debería haber estado definido.

Examples

Nótese que todos los ejemplos en esta sección muestran a propósito como usar las APIs de bucle de eventos de bajo nivel, como ser loop.run_forever() y loop.call_soon(). Aplicaciones asyncio modernas raramente necesitan ser escritas de esta manera; considere utilizar funciones de alto nivel como asyncio.run().

Hola Mundo con call_soon()

Un ejemplo usando el método loop.call_soon() para planificar una llamada. La llamada muestra "Hello World" y luego para el bucle de eventos:

import asyncio

def hello_world(loop):
    """A callback to print 'Hello World' and stop the event loop"""
    print('Hello World')
    loop.stop()

loop = asyncio.get_event_loop()

# Schedule a call to hello_world()
loop.call_soon(hello_world, loop)

# Blocking call interrupted by loop.stop()
try:
    loop.run_forever()
finally:
    loop.close()

Ver también

Un ejemplo similar de Hola Mundo creado con una corrutina y la función run().

Muestra la fecha actual con call_later()

Un ejemplo de llamada mostrando la fecha actual cada un segundo. La llamada usa el método loop.call_later() para volver a planificarse después de 5 segundos, y después para el bucle de eventos:

import asyncio
import datetime

def display_date(end_time, loop):
    print(datetime.datetime.now())
    if (loop.time() + 1.0) < end_time:
        loop.call_later(1, display_date, end_time, loop)
    else:
        loop.stop()

loop = asyncio.get_event_loop()

# Schedule the first call to display_date()
end_time = loop.time() + 5.0
loop.call_soon(display_date, end_time, loop)

# Blocking call interrupted by loop.stop()
try:
    loop.run_forever()
finally:
    loop.close()

Ver también

Un ejemplo similar a fecha actual creado con una corrutina y la función run().

Mirar un descriptor de archivo para leer eventos

Espera hasta que el descriptor de archivo reciba algún dato usando el método loop.add_reader() y entonces cierra el bucle de eventos:

import asyncio
from socket import socketpair

# Create a pair of connected file descriptors
rsock, wsock = socketpair()

loop = asyncio.get_event_loop()

def reader():
    data = rsock.recv(100)
    print("Received:", data.decode())

    # We are done: unregister the file descriptor
    loop.remove_reader(rsock)

    # Stop the event loop
    loop.stop()

# Register the file descriptor for read event
loop.add_reader(rsock, reader)

# Simulate the reception of data from the network
loop.call_soon(wsock.send, 'abc'.encode())

try:
    # Run the event loop
    loop.run_forever()
finally:
    # We are done. Close sockets and the event loop.
    rsock.close()
    wsock.close()
    loop.close()

Ver también

Un ejemplo similar usando transportes, protocolos y el método loop.create_connection().

Otro ejemplo similar usando la función de alto nivel asyncio.open_connection() y transmisiones.

Establece los gestores de señal para SIGINT y SIGTERM

(Este ejemplo de signals solamente funcionan en Unix.)

Registra gestores para las señales SIGINT y SIGTERM usando el método loop.add_signal_handler():

import asyncio
import functools
import os
import signal

def ask_exit(signame, loop):
    print("got signal %s: exit" % signame)
    loop.stop()

async def main():
    loop = asyncio.get_running_loop()

    for signame in {'SIGINT', 'SIGTERM'}:
        loop.add_signal_handler(
            getattr(signal, signame),
            functools.partial(ask_exit, signame, loop))

    await asyncio.sleep(3600)

print("Event loop running for 1 hour, press Ctrl+C to interrupt.")
print(f"pid {os.getpid()}: send SIGINT or SIGTERM to exit.")

asyncio.run(main())

Futures

Código fuente: Lib/asyncio/futures.py [https://github.com/python/cpython/tree/3.9/Lib/asyncio/futures.py], Lib/asyncio/base_futures.py [https://github.com/python/cpython/tree/3.9/Lib/asyncio/base_futures.py]

Los objetos Future se utilizan para conectar código basado en retrollamadas de bajo nivel (low-level callback-based code) con código async/await de alto nivel.

Funciones Future

asyncio.isfuture(obj)

Retorna True si obj es uno de los siguientes:

una instancia de asyncio.Future,

una instancia de asyncio.Task,

un objeto tipo Future con un atributo _asyncio_future_blocking.

Nuevo en la versión 3.5.

asyncio.ensure_future(obj, *, loop=None)

Retorna:

el argumento obj inalterado, si obj es una Future, Task, o un objeto tipo Future (esto se puede verificar con isfuture().)

un objeto Task envolviendo obj, si obj es una corrutina (esto se puede verificar con iscoroutine()); en este caso, la corrutina será programada por ensure_future().

un objeto Task que aguardará a obj, si obj es aguardable (esto se puede verificar con inspect.isawaitable().)

Si obj no es ninguno de los superiores, se lanzará TypeError.

Importante

Ver también la función create_task(), que es la forma preferida de crear nuevas Tasks.

Save a reference to the result of this function, to avoid a task disappearing mid execution.

Distinto en la versión 3.5.1: La función acepta cualquier objeto awaitable.

asyncio.wrap_future(future, *, loop=None)

Envuelve un objeto concurrent.futures.Future en un objeto asyncio.Future.

Objeto Future

class asyncio.Future(*, loop=None)

Un Future representa un resultado eventual de una operación asíncrona. No es seguro en hilos (thread-safe).

Future es un objeto awaitable. Las corrutinas pueden esperar (await) a objetos Future hasta que obtengan un resultado o excepción, o hasta que se cancelen.

Normalmente, los Futures se utilizan para permitir que código basado en retrollamadas de bajo nivel (low-level callback-based code) (por ejemplo, en protocolos implementados utilizando asyncio transports) interactúe con código async/await de alto nivel.

Es recomendable no exponer nunca objetos Future en APIs expuestas al usuario, y la forma recomendada de crear un objeto Future es llamando a loop.create_future(). De esta forma, implementaciones alternativas de bucles de eventos (event loop) pueden inyectar sus propias implementaciones optimizadas de un objeto Future.

Distinto en la versión 3.7: Añadido soporte para el módulo contextvars.

result()

Retorna el resultado del Future.

Si el Future es done y tiene un resultado establecido por el método set_result(), el valor resultante es retornado.

Si el Future es done y tiene una excepción establecida por el método set_exception(), este método lanzará esta excepción.

Si un evento es cancelled, este método lanzará una excepción CancelledError.

Si el resultado del Future todavía no está disponible, este método lanzará una excepción InvalidStateError.

set_result(result)

Marca el Future como done y establece su resultado.

Lanza un error InvalidStateError si el Future ya está done.

set_exception(exception)

Marca el Future como done y establece una excepción.

Lanza un error InvalidStateError si el Future ya está done.

done()

Retorna True si el Future está done.

Un Future está done si estaba cancelled o si tiene un resultado o excepción establecidos mediante llamadas a set_result() o set_exception().

cancelled()

Retorna True si el Future fue cancelled.

El método suele utilizarse para comprobar que un Future no es cancelled antes de establecer un resultado o excepción al mismo:

if not fut.cancelled():
    fut.set_result(42)

add_done_callback(callback, *, context=None)

Añade una retrollamada (callback) a ser ejecutada cuando el Future es done.

La retrollamada (callback) es llamada con el objeto Future como su único argumento.

Si el Future ya es done cuando se llama a este método, la retrollamada (callback) es programada con loop.call_soon().

Un argumento opcional de contexto, por palabra clave, permite especificar un contextvars.Context personalizado para ser ejecutado en la retrollamada (callback). El contexto actual se utiliza cuando no se provee un contexto (context).

functools.partial() se puede utilizar para dar parámetros a la retrollamada (callback), por ejemplo:

# Call 'print("Future:", fut)' when "fut" is done.
fut.add_done_callback(
    functools.partial(print, "Future:"))

Distinto en la versión 3.7: El parámetro de contexto (context) por palabra clave fue añadido. Ver PEP 567 [https://www.python.org/dev/peps/pep-0567] para más detalles.

remove_done_callback(callback)

Elimina la retrollamada (callback) de la lista de retrollamadas.

Retorna el número de retrollamadas (callbacks) eliminadas, que normalmente es 1, excepto si una retrollamada fue añadida más de una vez.

cancel(msg=None)

Cancela el Future y programa retrollamadas (callbacks).

Si el Future ya está done o cancelled, retorna False. De lo contrario, cambia el estado del Future a cancelled, programa las retrollamadas, y retorna True.

Distinto en la versión 3.9: Se agregó el parámetro msg.

exception()

Retorna la excepción definida en este Future.

La excepción (o None si no se había establecido ninguna excepción) es retornada sólo si Future es done.

Si un evento es cancelled, este método lanzará una excepción CancelledError.

Si el Future todavía no es done, este método lanza una excepción InvalidStateError.

get_loop()

Retorna el bucle de eventos (event loop) al cual el objeto Future está asociado.

Nuevo en la versión 3.7.

Este ejemplo crea un objeto Future, crea y programa una Task asíncrona para establecer el resultado para el Future, y espera hasta que el Future tenga un resultado:

async def set_after(fut, delay, value):
    # Sleep for *delay* seconds.
    await asyncio.sleep(delay)

    # Set *value* as a result of *fut* Future.
    fut.set_result(value)

async def main():
    # Get the current event loop.
    loop = asyncio.get_running_loop()

    # Create a new Future object.
    fut = loop.create_future()

    # Run "set_after()" coroutine in a parallel Task.
    # We are using the low-level "loop.create_task()" API here because
    # we already have a reference to the event loop at hand.
    # Otherwise we could have just used "asyncio.create_task()".
    loop.create_task(
        set_after(fut, 1, '... world'))

    print('hello ...')

    # Wait until *fut* has a result (1 second) and print it.
    print(await fut)

asyncio.run(main())

Importante

El objeto Future fue diseñado para imitar a concurrent.futures.Future. Entre las principales diferencias están:

al contrario que Futures de asyncio, las instancias de concurrent.futures.Future no son aguardables (await).

asyncio.Future.result() y asyncio.Future.exception() no aceptan el argumento timeout.

asyncio.Future.result() y asyncio.Future.exception() lanzan una excepción InvalidStateError cuando el Future no es done.

Las retrollamadas (callbacks) registradas con asyncio.Future.add_done_callback() no son llamadas inmediatamente, sino que son programadas con loop.call_soon().

asyncio Future no es compatible con las funciones concurrent.futures.wait() ni concurrent.futures.as_completed().

asyncio.Future.cancel() acepta un argumento opcional msg, pero concurrent.futures.cancel() no.

Transportes y protocolos

Prefacio

Los transportes y protocolos son utilizados por las APIs de bajo nivel de los bucles de eventos, como loop.create_connection(). Utilizan un estilo de programación basado en retrollamadas y permiten implementaciones de alto rendimiento de protocolos de red o IPC (p. ej. HTTP).

Esencialmente, los transportes y protocolos solo deben usarse en bibliotecas y frameworks, nunca en aplicaciones asyncio de alto nivel.

Esta página de la documentación cubre tanto Transports como Protocols.

Introducción

En el nivel más alto, el transporte se ocupa de cómo se transmiten los bytes, mientras que el protocolo determina qué bytes transmitir (y hasta cierto punto cuándo).

Una forma diferente de decir lo mismo: Un transporte es una abstracción para un socket (o un punto final de E/S similar) mientras que un protocolo es una abstracción para una aplicación, desde el punto de vista del transporte.

Otro punto de vista más es que las interfaces de transporte y protocolo definen juntas una interfaz abstracta para usar E/S de red y E/S entre procesos.

Siempre existe una relación 1:1 entre el transporte y los objetos protocolo: el protocolo llama a los métodos del transporte para enviar datos, mientras que el transporte llama a los métodos del protocolo para enviarle los datos que se han recibido.

La mayoría de los métodos del bucle de eventos orientados a la conexión (como loop.create_connection()) aceptan generalmente un argumento protocol_factory que es usado para crear un objeto Protocol para una conexión aceptada, representada por un objeto Transport. Estos métodos suelen retornar una tupla de la forma (transporte, protocolo).

Contenidos

Esta página de la documentación contiene las siguientes secciones:

La sección Transports documenta las clases asyncio BaseTransport, ReadTransport, WriteTransport, Transport, DatagramTransport y SubprocessTransport.

La sección Protocols documenta las clases asyncio BaseProtocol, Protocol, BufferedProtocol, DatagramProtocol y SubprocessProtocol.

La sección Examples muestra cómo trabajar con transportes, protocolos y las APIs de bajo nivel del bucle de eventos.

Transportes

Código fuente: Lib/asyncio/transports.py [https://github.com/python/cpython/tree/3.9/Lib/asyncio/transports.py]

Los transportes son clases proporcionadas por asyncio para abstraer varios tipos de canales de comunicación.

Los objetos transporte siempre son instanciados por un bucle de eventos asyncio.

asyncio implementa transportes para TCP, UDP, SSL y pipes de subprocesos. Los métodos disponibles en un transporte dependen del tipo de transporte.

Las clases transporte no son seguras en hilos.

Jerarquía de transportes

class asyncio.BaseTransport

Clase base para todos los transportes. Contiene métodos que todos los transportes asyncio comparten.

class asyncio.WriteTransport(BaseTransport)

Un transporte base para conexiones de solo escritura.

Las instancias de la clase WriteTransport se retornan desde el método del bucle de eventos loop.connect_write_pipe() y también se utilizan en métodos relacionados con subprocesos como loop.subprocess_exec().

class asyncio.ReadTransport(BaseTransport)

Un transporte base para conexiones de solo lectura.

Las instancias de la clase ReadTransport se retornan desde el método del bucle de eventos loop.connect_read_pipe() y también se utilizan en métodos relacionados con subprocesos como loop.subprocess_exec().

class asyncio.Transport(WriteTransport, ReadTransport)

Interfaz que representa un transporte bidireccional, como una conexión TCP.

El usuario no crea una instancia de transporte directamente; en su lugar se llama a una función de utilidad, pasándole una fábrica de protocolos junto a otra información necesaria para crear el transporte y el protocolo.

Las instancias de la clase Transport son retornadas o utilizadas por métodos del bucle de eventos como loop.create_connection(), loop.create_unix_connection(), loop.create_server(), loop.sendfile(), etc.

class asyncio.DatagramTransport(BaseTransport)

Un transporte para conexiones de datagramas (UDP).

Las instancias de la clase DatagramTransport se retornan desde el método loop.create_datagram_endpoint() del bucle de eventos.

class asyncio.SubprocessTransport(BaseTransport)

Una abstracción para representar una conexión entre un proceso padre y su proceso OS hijo.

Las instancias de la clase SubprocessTransport se retornan desde los métodos del bucle de eventos loop.subprocess_shell() y loop.subprocess_exec().

Transporte base

BaseTransport.close()

Cierra el transporte.

Si el transporte tiene un búfer para datos de salida, los datos almacenados en el búfer se eliminarán de forma asincrónica. No se recibirán más datos. Después de que se vacíen todos los datos almacenados en el búfer, el método protocol.connection_lost() del protocolo se llamará con None como argumento.

BaseTransport.is_closing()

Retorna True si el transporte se está cerrando o está ya cerrado.

BaseTransport.get_extra_info(name, default=None)

Retorna información sobre el transporte o los recursos subyacentes que utiliza.

name es una cadena de caracteres que representa la información específica del transporte que se va a obtener.

default es el valor que se retornará si la información no está disponible o si el transporte no admite la consulta con la implementación del bucle de eventos de terceros dada o en la plataforma actual.

Por ejemplo, el siguiente código intenta obtener el objeto socket subyacente del transporte:

sock = transport.get_extra_info('socket')
if sock is not None:
    print(sock.getsockopt(...))

Categorías de información que se pueden consultar sobre algunos transportes:

socket:

'peername': la dirección remota a la que está conectado el socket, resultado de socket.socket.getpeername() (None en caso de error)

'socket': instancia de socket.socket

'sockname': la dirección propia del socket, resultado de socket.socket.getsockname()

socket SSL:

'compression': el algoritmo de compresión que se está usando como una cadena de caracteres o None si la conexión no está comprimida; resultado de ssl.SSLSocket.compression()

'cipher': una tupla de tres valores que contiene el nombre del cifrado que se está utilizando, la versión del protocolo SSL que define su uso y la cantidad de bits de la clave secreta que se utilizan; resultado de ssl.SSLSocket.cipher()

'peercert': certificado de pares; resultado de ssl.SSLSocket.getpeercert()

'sslcontext': instancia de ssl.SSLContext

'ssl_object': instancia de ssl.SSLObject o ssl.SSLSocket

pipe:

'pipe': objeto pipe

subproceso:

'subprocess': instancia de subprocess.Popen

BaseTransport.set_protocol(protocol)

Establece un nuevo protocolo.

El cambio de protocolo solo debe realizarse cuando esté documentado que ambos protocolos admiten el cambio.

BaseTransport.get_protocol()

Retorna el protocolo actual.

Transportes de solo lectura

ReadTransport.is_reading()

Retorna True si el transporte está recibiendo nuevos datos.

Nuevo en la versión 3.7.

ReadTransport.pause_reading()

Pausa el extremo receptor del transporte. No se pasarán datos al método protocol.data_received() del protocolo hasta que se llame a resume_reading().

Distinto en la versión 3.7: El método es idempotente, es decir, se puede llamar cuando el transporte ya está en pausa o cerrado.

ReadTransport.resume_reading()

Reanuda el extremo receptor. El método protocol.data_received() del protocolo se llamará una vez más si hay algunos datos disponibles para su lectura.

Distinto en la versión 3.7: El método es idempotente, es decir, se puede llamar cuando el transporte está leyendo.

Transportes de solo escritura

WriteTransport.abort()

Cierra el transporte inmediatamente, sin esperar a que finalicen las operaciones pendientes. Se perderán los datos almacenados en el búfer. No se recibirán más datos. El método protocol.connection_lost() del protocolo será llamado eventualmente con None como argumento.

WriteTransport.can_write_eof()

Retorna True si el transporte admite write_eof(), en caso contrario False.

WriteTransport.get_write_buffer_size()

Retorna el tamaño actual del búfer de salida utilizado por el transporte.

WriteTransport.get_write_buffer_limits()

Obtiene los límites superior e inferior para el control del flujo de escritura. Retorna una tupla (low, high) donde low (“inferior”) y high (“superior”) son un número de bytes positivo.

Usa set_write_buffer_limits() para establecer los límites.

Nuevo en la versión 3.4.2.

WriteTransport.set_write_buffer_limits(high=None, low=None)

Establece los límites high (“superior”) y low (“inferior”) para el control del flujo de escritura.

Estos dos valores (medidos en número de bytes) controlan cuándo se llaman los métodos protocol.pause_writing() y protocol.resume_writing() del protocolo . Si se especifica, el límite inferior debe ser menor o igual que el límite superior. Ni high ni low pueden ser negativos.

pause_writing() se llama cuando el tamaño del búfer es mayor o igual que el valor high (“superior”). Si se ha pausado la escritura, se llama a resume_writing() cuando el tamaño del búfer es menor o igual que el valor low (“inferior”).

Los valores por defecto son específicos de la implementación. Si solo se proporciona el límite superior, el inferior toma de forma predeterminada un valor específico, dependiente de la implementación, menor o igual que el límite superior. Establecer high (“superior”) en cero fuerza low (“inferior”) a cero también y hace que pause_writing() sea llamado siempre que el búfer no esté vacío. Establecer low (“inferior”) en cero hace que resume_writing() sea llamado únicamente cuando el búfer esté vacío. El uso de cero para cualquiera de los límites es generalmente subóptimo, ya que reduce las oportunidades para realizar E/S y cálculos simultáneamente.

Usa get_write_buffer_limits() para obtener los límites.

WriteTransport.write(data)

Escribe los bytes de data en el transporte.

Este método no bloquea; almacena los datos en el búfer y organiza que se envíen de forma asincrónica.

WriteTransport.writelines(list_of_data)

Escribe una lista (o cualquier iterable) de bytes de datos en el transporte. Esto es funcionalmente equivalente a llamar a write() en cada elemento generado por el iterable, pero puede ser implementado de manera más eficiente.

WriteTransport.write_eof()

Cierra el extremo de escritura del transporte después de vaciar todos los datos almacenados en el búfer. Aún es posible recibir datos.

Este método puede lanzar una excepción NotImplementedError si el transporte (p. ej. SSL) no soporta conexiones semicerradas (half-closed).

Transportes de datagramas

DatagramTransport.sendto(data, addr=None)

Envía los bytes data al par remoto proporcionado por addr (una dirección de destino dependiente del transporte). Si addr es None, los datos se envían a la dirección de destino proporcionada en la creación del transporte.

Este método no bloquea; almacena los datos en el búfer y organiza que se envíen de forma asincrónica.

DatagramTransport.abort()

Cierra el transporte inmediatamente, sin esperar a que finalicen las operaciones pendientes. Se perderán los datos almacenados en el búfer. No se recibirán más datos. El método protocol.connection_lost() del protocolo será llamado eventualmente con None como argumento.

Transportes de subprocesos

SubprocessTransport.get_pid()

Retorna la id del subproceso como un número entero.

SubprocessTransport.get_pipe_transport(fd)

Retorna el transporte para la pipe de comunicación correspondiente al descriptor de archivo entero fd:

0: transporte de streaming para lectura de la entrada estándar (stdin) o None si el subproceso no se creó con stdin = PIPE

1: transporte de streaming para escritura de la salida estándar (stdout) o None si el subproceso no se creó con stdout = PIPE

2`: transporte de streaming para escritura del error estándar (stderr) o None si el subproceso no se creó con stderr = PIPE

otro fd: None

SubprocessTransport.get_returncode()

Retorna el código de retorno del subproceso como un entero o None si no ha retornado aún, lo que es similar al atributo subprocess.Popen.returncode.

SubprocessTransport.kill()

Mata al subproceso.

En los sistemas POSIX, la función envía SIGKILL al subproceso. En Windows, este método es un alias para terminate().

Ver también subprocess.Popen.kill().

SubprocessTransport.send_signal(signal)

Envía el número de señal al subproceso, como en subprocess.Popen.send_signal().

SubprocessTransport.terminate()

Detiene el subproceso.

En los sistemas POSIX, este método envía SIGTERM al subproceso. En Windows, se llama a la función de la API de Windows TerminateProcess() para detener el subproceso.

Ver también subprocess.Popen.terminate().

SubprocessTransport.close()

Mata al subproceso llamando al método kill().

Si el subproceso aún no ha retornado, cierra los transportes de las pipes stdin, stdout y stderr.

Protocolos

Código fuente: Lib/asyncio/protocols.py [https://github.com/python/cpython/tree/3.9/Lib/asyncio/protocols.py]

asyncio proporciona un conjunto de clases base abstractas que pueden usarse para implementar protocolos de red. Estas clases están destinadas a ser utilizadas junto con los transportes.

Las subclases de las clases abstractas de protocolos base pueden implementar algunos o todos los métodos. Todos estos métodos son retrollamadas: son llamados por los transportes en ciertos eventos, por ejemplo, cuando se reciben algunos datos. Un método del protocolo base debe ser llamado por el transporte correspondiente.

Protocolos base

class asyncio.BaseProtocol

Protocolo base con métodos que comparten todos los demás protocolos.

class asyncio.Protocol(BaseProtocol)

La clase base para implementar protocolos de streaming (TCP, sockets Unix, etc).

class asyncio.BufferedProtocol(BaseProtocol)

Una clase base para implementar protocolos de streaming con control manual del búfer de recepción.

class asyncio.DatagramProtocol(BaseProtocol)

La clase base para implementar protocolos de datagramas (UDP).

class asyncio.SubprocessProtocol(BaseProtocol)

La clase base para implementar protocolos que se comunican con procesos secundarios (pipes unidireccionales).

Protocolo base

Todos los protocolos asyncio pueden implementar las retrollamadas del protocolo base.

Retrollamadas de conexión

Las retrollamadas de conexión son llamadas exactamente una vez por conexión establecida en todos los protocolos. Todas las demás retrollamadas del protocolo solo pueden ser llamadas entre estos dos métodos.

BaseProtocol.connection_made(transport)

Se llama cuando se establece una conexión.

El argumento transport es el transporte que representa la conexión. El protocolo se encarga de almacenar la referencia a su propio transporte.

BaseProtocol.connection_lost(exc)

Se llama cuando la conexión se pierde o se cierra.

El argumento es un objeto excepción o None. Esto último significa que se recibió un EOF regular o que la conexión fue cancelada o cerrada por este lado de la conexión.

Retrollamadas de control de flujo

Los transportes pueden llamar a las retrollamadas de control de flujo para pausar o reanudar la escritura llevada a cabo por el protocolo.

Consulta la documentación del método set_write_buffer_limits() para obtener más detalles.

BaseProtocol.pause_writing()

Se llama cuando el búfer del transporte supera el límite superior.

BaseProtocol.resume_writing()

Se llama cuando el búfer del transporte se vacía por debajo del límite inferior.

Si el tamaño del búfer es igual al límite superior, pause_writing() no será llamado: el tamaño del búfer debe superarse estrictamente.

Por el contrario, se llama a resume_writing() cuando el tamaño del búfer es igual o menor que el límite inferior. Estas condiciones finales son importantes para garantizar que todo salga como se espera cuando cualquiera de los dos límites sea cero.

Protocolos de streaming

Los métodos de eventos, como loop.create_server(), loop.create_unix_server(), loop.create_connection(), loop.create_unix_connection(), loop.connect_accepted_socket(), loop.connect_read_pipe(), y loop.connect_write_pipe() aceptan fábricas que retornan protocolos de streaming.

Protocol.data_received(data)

Se llama cuando se reciben algunos datos. data es un objeto bytes no vacío que contiene los datos entrantes.

Que los datos se almacenen en un búfer, que se fragmenten o se vuelvan a ensamblar depende del transporte. En general, no debe confiar en semánticas específicas y, en cambio, hacer que su análisis sea genérico y flexible. Sin embargo, los datos siempre se reciben en el orden correcto.

El método se puede llamar un número arbitrario de veces mientras una conexión esté abierta.

Sin embargo, protocol.eof_received() se llama como máximo una vez. En el momento que se llama a eof_received(), ya no se llama a data_received().

Protocol.eof_received()

Se llama cuando el otro extremo indica que no enviará más datos (por ejemplo, llamando a transport.write_eof() si el otro extremo también usa asyncio).

Este método puede retornar un valor falso (incluido None), en cuyo caso el transporte se cerrará solo. Por el contrario, si este método retorna un valor verdadero, el protocolo utilizado determina si se debe cerrar el transporte. Dado que la implementación por defecto retorna None, en éste caso, se cierra implícitamente la conexión.

Algunos transportes, incluido SSL, no admiten conexiones semicerradas (half-closed), en cuyo caso retornar verdadero desde este método resultará en el cierre de la conexión.

Máquina de estado:

start -> connection_made
    [-> data_received]*
    [-> eof_received]?
-> connection_lost -> end

Protocolos de streaming mediante búfer

Nuevo en la versión 3.7.

Los protocolos que hacen uso de un búfer se pueden utilizar con cualquier método del bucle de eventos que admita Streaming Protocols.

Las implementaciones de BufferedProtocol permiten la asignación manual explícita y el control del búfer de recepción. Los bucles de eventos pueden utilizar el búfer proporcionado por el protocolo para evitar copias de datos innecesarias. Esto puede resultar en una mejora notable del rendimiento de los protocolos que reciben grandes cantidades de datos. Las implementaciones de protocolos sofisticados pueden reducir significativamente la cantidad de asignaciones de búfer.

Las siguientes retrollamadas son llamadas en instancias BufferedProtocol:

BufferedProtocol.get_buffer(sizehint)

Se llama para asignar un nuevo búfer de recepción.

sizehint es el tamaño mínimo recomendado para el búfer retornado. Es aceptable retornar búferes más pequeños o más grandes de lo que sugiere sizehint. Cuando se establece en -1, el tamaño del búfer puede ser arbitrario. Es un error retornar un búfer con tamaño cero.

get_buffer() debe retornar un objeto que implemente el protocolo de búfer.

BufferedProtocol.buffer_updated(nbytes)

Se llama cuando el búfer se ha actualizado con los datos recibidos.

nbytes es el número total de bytes que se escribieron en el búfer.

BufferedProtocol.eof_received()

Consulte la documentación del método protocol.eof_received().

get_buffer() se puede llamar un número arbitrario de veces durante una conexión. Sin embargo, protocol.eof_received () se llama como máximo una vez y, si se llama, get_buffer() y buffer_updated() no serán llamados después de eso.

Máquina de estado:

start -> connection_made
    [-> get_buffer
        [-> buffer_updated]?
    ]*
    [-> eof_received]?
-> connection_lost -> end

Protocolos de datagramas

Las instancias del protocolo de datagramas deben ser construidas por fábricas de protocolos pasadas al método loop.create_datagram_endpoint().

DatagramProtocol.datagram_received(data, addr)

Se llama cuando se recibe un datagrama. data es un objeto bytes que contiene los datos entrantes. addr es la dirección del par que envía los datos; el formato exacto depende del transporte.

DatagramProtocol.error_received(exc)

Se llama cuando una operación de envío o recepción anterior genera una OSError. exc es la instancia OSError.

Este método se llama en condiciones excepcionales, cuando el transporte (por ejemplo, UDP) detecta que un datagrama no se pudo entregar a su destinatario. Sin embargo, en la mayoría de casos, los datagramas que no se puedan entregar se eliminarán silenciosamente.

Nota

En los sistemas BSD (macOS, FreeBSD, etc.) el control de flujo no es compatible con los protocolos de datagramas, esto se debe a que no hay una forma confiable de detectar fallos de envío causados por escribir demasiados paquetes.

El socket siempre aparece como disponible (“ready”) y se eliminan los paquetes sobrantes. Un error OSError con errno establecido en errno.ENOBUFS puede o no ser generado; si se genera, se informará a DatagramProtocol.error_received() pero en caso contrario se ignorará.

Protocolos de subprocesos

Subprocess Protocol instances should be constructed by protocol factories passed to the loop.subprocess_exec() and loop.subprocess_shell() methods.

SubprocessProtocol.pipe_data_received(fd, data)

Se llama cuando el proceso hijo escribe datos en su pipe stdout o stderr.

fd es el descriptor de archivo entero de la pipe.

data es un objeto bytes no vacío que contiene los datos recibidos.

SubprocessProtocol.pipe_connection_lost(fd, exc)

Se llama cuando se cierra una de las pipes que se comunican con el proceso hijo.

fd es el descriptor de archivo entero que se cerró.

SubprocessProtocol.process_exited()

Se llama cuando el proceso hijo ha finalizado.

Ejemplos

Servidor de eco TCP

Crear un servidor de eco TCP usando el método loop.create_server(), enviar de vuelta los datos recibidos y cerrar la conexión:

import asyncio

class EchoServerProtocol(asyncio.Protocol):
    def connection_made(self, transport):
        peername = transport.get_extra_info('peername')
        print('Connection from {}'.format(peername))
        self.transport = transport

    def data_received(self, data):
        message = data.decode()
        print('Data received: {!r}'.format(message))

        print('Send: {!r}'.format(message))
        self.transport.write(data)

        print('Close the client socket')
        self.transport.close()

async def main():
    # Get a reference to the event loop as we plan to use
    # low-level APIs.
    loop = asyncio.get_running_loop()

    server = await loop.create_server(
        lambda: EchoServerProtocol(),
        '127.0.0.1', 8888)

    async with server:
        await server.serve_forever()

asyncio.run(main())

Ver también

El ejemplo Servidor de eco TCP usando streams usa la función de alto nivel asyncio.start_server().

Cliente de eco TCP

Un cliente de eco TCP usando el método loop.create_connection(), envía datos y espera hasta que la conexión se cierre:

import asyncio

class EchoClientProtocol(asyncio.Protocol):
    def __init__(self, message, on_con_lost):
        self.message = message
        self.on_con_lost = on_con_lost

    def connection_made(self, transport):
        transport.write(self.message.encode())
        print('Data sent: {!r}'.format(self.message))

    def data_received(self, data):
        print('Data received: {!r}'.format(data.decode()))

    def connection_lost(self, exc):
        print('The server closed the connection')
        self.on_con_lost.set_result(True)

async def main():
    # Get a reference to the event loop as we plan to use
    # low-level APIs.
    loop = asyncio.get_running_loop()

    on_con_lost = loop.create_future()
    message = 'Hello World!'

    transport, protocol = await loop.create_connection(
        lambda: EchoClientProtocol(message, on_con_lost),
        '127.0.0.1', 8888)

    # Wait until the protocol signals that the connection
    # is lost and close the transport.
    try:
        await on_con_lost
    finally:
        transport.close()

asyncio.run(main())

Ver también

El ejemplo Cliente de eco TCP usando streams usa la función de alto nivel asyncio.open_connection().

Servidor de eco UDP

Un servidor de eco UDP, usando el método loop.create_datagram_endpoint(), envía de vuelta los datos recibidos:

import asyncio

class EchoServerProtocol:
    def connection_made(self, transport):
        self.transport = transport

    def datagram_received(self, data, addr):
        message = data.decode()
        print('Received %r from %s' % (message, addr))
        print('Send %r to %s' % (message, addr))
        self.transport.sendto(data, addr)

async def main():
    print("Starting UDP server")

    # Get a reference to the event loop as we plan to use
    # low-level APIs.
    loop = asyncio.get_running_loop()

    # One protocol instance will be created to serve all
    # client requests.
    transport, protocol = await loop.create_datagram_endpoint(
        lambda: EchoServerProtocol(),
        local_addr=('127.0.0.1', 9999))

    try:
        await asyncio.sleep(3600)  # Serve for 1 hour.
    finally:
        transport.close()

asyncio.run(main())

Cliente de eco UDP

Un cliente de eco UDP, usando el método loop.create_datagram_endpoint(), envía datos y cierra el transporte cuando recibe la respuesta:

import asyncio

class EchoClientProtocol:
    def __init__(self, message, on_con_lost):
        self.message = message
        self.on_con_lost = on_con_lost
        self.transport = None

    def connection_made(self, transport):
        self.transport = transport
        print('Send:', self.message)
        self.transport.sendto(self.message.encode())

    def datagram_received(self, data, addr):
        print("Received:", data.decode())

        print("Close the socket")
        self.transport.close()

    def error_received(self, exc):
        print('Error received:', exc)

    def connection_lost(self, exc):
        print("Connection closed")
        self.on_con_lost.set_result(True)

async def main():
    # Get a reference to the event loop as we plan to use
    # low-level APIs.
    loop = asyncio.get_running_loop()

    on_con_lost = loop.create_future()
    message = "Hello World!"

    transport, protocol = await loop.create_datagram_endpoint(
        lambda: EchoClientProtocol(message, on_con_lost),
        remote_addr=('127.0.0.1', 9999))

    try:
        await on_con_lost
    finally:
        transport.close()

asyncio.run(main())

Conectando sockets existentes

Espera hasta que un socket reciba datos usando el método loop.create_connection() mediante un protocolo:

import asyncio
import socket

class MyProtocol(asyncio.Protocol):

    def __init__(self, on_con_lost):
        self.transport = None
        self.on_con_lost = on_con_lost

    def connection_made(self, transport):
        self.transport = transport

    def data_received(self, data):
        print("Received:", data.decode())

        # We are done: close the transport;
        # connection_lost() will be called automatically.
        self.transport.close()

    def connection_lost(self, exc):
        # The socket has been closed
        self.on_con_lost.set_result(True)

async def main():
    # Get a reference to the event loop as we plan to use
    # low-level APIs.
    loop = asyncio.get_running_loop()
    on_con_lost = loop.create_future()

    # Create a pair of connected sockets
    rsock, wsock = socket.socketpair()

    # Register the socket to wait for data.
    transport, protocol = await loop.create_connection(
        lambda: MyProtocol(on_con_lost), sock=rsock)

    # Simulate the reception of data from the network.
    loop.call_soon(wsock.send, 'abc'.encode())

    try:
        await protocol.on_con_lost
    finally:
        transport.close()
        wsock.close()

asyncio.run(main())

Ver también

El ejemplo monitorizar eventos de lectura en un descriptor de archivo utiliza el método de bajo nivel loop.add_reader() para registrar un descriptor de archivo.

El ejemplo registrar un socket abierto a la espera de datos usando streams usa streams de alto nivel creados por la función open_connection() en una corrutina.

loop.subprocess_exec() y SubprocessProtocol

Un ejemplo de un protocolo de subproceso que se utiliza para obtener la salida de un subproceso y esperar su terminación.

El subproceso es creado por el método loop.subprocess_exec()

import asyncio
import sys

class DateProtocol(asyncio.SubprocessProtocol):
    def __init__(self, exit_future):
        self.exit_future = exit_future
        self.output = bytearray()

    def pipe_data_received(self, fd, data):
        self.output.extend(data)

    def process_exited(self):
        self.exit_future.set_result(True)

async def get_date():
    # Get a reference to the event loop as we plan to use
    # low-level APIs.
    loop = asyncio.get_running_loop()

    code = 'import datetime; print(datetime.datetime.now())'
    exit_future = asyncio.Future(loop=loop)

    # Create the subprocess controlled by DateProtocol;
    # redirect the standard output into a pipe.
    transport, protocol = await loop.subprocess_exec(
        lambda: DateProtocol(exit_future),
        sys.executable, '-c', code,
        stdin=None, stderr=None)

    # Wait for the subprocess exit using the process_exited()
    # method of the protocol.
    await exit_future

    # Close the stdout pipe.
    transport.close()

    # Read the output which was collected by the
    # pipe_data_received() method of the protocol.
    data = bytes(protocol.output)
    return data.decode('ascii').rstrip()

date = asyncio.run(get_date())
print(f"Current date: {date}")

Consulte también el mismo ejemplo escrito utilizando la API de alto nivel.

Políticas

Una política del bucle de eventos es un objeto por proceso que controla la administración del bucle de eventos. Cada bucle de eventos tiene una política por defecto, que puede ser cambiada y editada usando la política de API.

Una política define la noción de contexto y administra un bucle de eventos separado por contexto. La política por defecto define un contexto como el estado actual.

Usando una política de bucle de eventos personalizada, la conducta de las funciones get_event_loop(), set_event_loop(), y new_event_loop() puede ser personalizada.

Los objetos de política deberían implementar las APIs definidas en la clase abstracta base AbstractEventLoopPolicy.

Obteniendo y Configurando la Política

Las siguientes funciones pueden ser usadas para obtener y configurar la política de los procesos actuales:

asyncio.get_event_loop_policy()

Retorna la política actual en todo el proceso.

asyncio.set_event_loop_policy(policy)

Establece la política actual en todo el proceso a policy.

Si policy está configurado a None, la política por defecto se reestablece.

Objetos de Política

La clase base de política de bucle de eventos abstractos se define de la siguiente manera:

class asyncio.AbstractEventLoopPolicy

Una clase base abstracta para políticas asyncio.

get_event_loop()

Retorna el bucle de eventos para el contexto actual.

Retorna un objeto bucle de eventos implementando la interfaz AbstractEventLoop.

Este método nunca debería retornar None.

Distinto en la versión 3.6.

set_event_loop(loop)

Establece el bucle de eventos para el contexto a loop.

new_event_loop()

Crea y retorna un nuevo objeto de bucle de eventos.

Este método nunca debería retornar None.

get_child_watcher()

Retorna un objeto observador de procesos secundarios.

Retorna un objeto observador implementando la interfaz AbstractChildWatcher.

Esta función es específica de Unix.

set_child_watcher(watcher)

Establece el observador de procesos secundarios actuales a watcher.

Esta función es específica de Unix.

asyncio se envía con las siguientes políticas integradas:

class asyncio.DefaultEventLoopPolicy

La política por defecto asyncio. Usa SelectorEventLoop en Unix y ProactorEventLoop en Windows.

No hay necesidad de instalar la política por defecto manualmente. asyncio está configurado para usar la política por defecto automáticamente.

Distinto en la versión 3.8: En Windows, ProactorEventLoop ahora se usa por defecto.

class asyncio.WindowsSelectorEventLoopPolicy

Una política de bucle de eventos alternativa que usa la implementación de bucle de eventos SelectorEventLoop.

Disponibilidad: Windows.

class asyncio.WindowsProactorEventLoopPolicy

Una política de bucle de eventos alternativa que usa la implementación de bucle de eventos ProactorEventLoop.

Disponibilidad: Windows.

Observadores de procesos

Un observador de procesos permite personalizar cómo un bucle de eventos monitorea procesos secundarios en Unix. Específicamente, un bucle de eventos necesita saber cuándo un proceso secundario ha terminado.

En asyncio, los procesos secundarios son creados con las funciones créate_subprocess_exec() y loop.subprocess_exec().

asyncio define la clase base abstracta AbstractChildWatcher, qué observadores de subprocesos deberían implementarse, y tiene cuatro implementaciones diferentes: ThreadedChildWatcher (configurado para ser usado por defecto), MultiLoopChildWatcher, SaferChildWatcher, y FastChildWatcher.

Mirar también la sección Subprocesos e hilos.

Las siguientes dos funciones pueden ser usadas para personalizar la implementación de observadores de procesos secundarios usados por el bucle de eventos de asyncio:

asyncio.get_child_watcher()

Retorna el observador de procesos secundarios para la política actual.

asyncio.set_child_watcher(watcher)

Establece el observador de procesos secundarios actuales a watcher para la política actual. watcher debe implementar métodos definidos en la clase base AbstractChildWatcher.

Nota

Implementaciones de bucles de eventos de terceras partes no deben dar soporte a observadores de procesos secundarios personalizados. Para dichos bucles de eventos, usando set_child_watcher() podría estar prohibido o no tener efecto.

class asyncio.AbstractChildWatcher

add_child_handler(pid, callback, *args)

Registra un nuevo gestor de proceso secundario.

Arreglo para callback(pid, returncode, *args) a ser invocado cuando un proceso con PID igual a pid termina. Especificando otro retrollamada para el mismo proceso reemplaza el gestor previo.

El callback invocable debe ser seguro para hilos.

remove_child_handler(pid)

Remueve el gestor para el proceso con PID igual a pid.

La función retorna True si el gestor fue removido de forma exitosa, False si no hubo nada que remover.

attach_loop(loop)

Adjunta el observador a un bucle de eventos.

Si el observador estaba previamente adjuntado a un bucle de eventos, entonces primero es separado antes de adjuntar el nuevo bucle.

Nota: el bucle puede ser None.

is_active()

Retorna True si el observador está listo para usarse.

Generar un nuevo subproceso con observador de procesos secundarios actual inactive lanza RuntimeError.

Nuevo en la versión 3.8.

close()

Cierra el observador.

Este método tiene que ser invocado para asegurar que los objetos subyacentes están limpiados.

class asyncio.ThreadedChildWatcher

Esta implementación inicia un nuevo hilo esperando para cada subproceso generado.

Trabaja de manera confiable incluso cuando el bucle de eventos asyncio se ejecuta en un hilo de SO no principal.

No hay sobrecarga notable cuando se gestiona un número grande de procesos secundarios (O(1) cada vez que un proceso secundario termina), pero iniciar un hilo por proceso requiere memoria extra.

Este observador es usado por defecto.

Nuevo en la versión 3.8.

class asyncio.MultiLoopChildWatcher

Esta implementación registra un gestor de señal en instanciación SIGCHLD. Eso puede romper código de terceras partes que instalen un gestor personalizado para la señal SIGCHLD.

El observador evita interrumpir otro código generando procesos sondeando cada proceso explícitamente en una señal SIGCHLD.

No hay limitación para ejecutar subprocesos de diferentes hilos una vez el observador es instalado.

La solución es segura pero tiene una sobrecarga significativa cuando se gestiona un número grande de procesos (O(n) cada vez que un SIGCHLD es recibido).

Nuevo en la versión 3.8.

class asyncio.SafeChildWatcher

Esta implementación usa bucles de eventos activos del hilo principal para gestionar la señal SIGCHLD. Si el hilo principal no tiene bucles de eventos en ejecución otro hilo no puede generar un subproceso (RuntimeError es disparada).

El observador evita interrumpir otro código generando procesos sondeando cada proceso explícitamente en una señal SIGCHLD.

Esta solución es tan segura como MultiLoopChildWatcher y tiene la misma complejidad O(n) pero requiere de un bucle de eventos ejecutándose en el hilo principal para trabajar.

class asyncio.FastChildWatcher

Esta implementación cosecha cada proceso terminado llamando os.waitpad(-1) directamente, posiblemente rompiendo otro código generando procesos y esperando por su terminación.

No hay sobrecarga notable cuando se gestiona un número grande de procesos secundarios (O(1) cada vez que un proceso secundario termina).

Esta solución requiere un bucle de eventos ejecutándose en el hilo principal para trabajar, como SafeChildWatcher.

class asyncio.PidfdChildWatcher

Esta implementación sondea los descriptores de archivos de proceso (pidfds) para esperar la terminación del proceso hijo. En ciertos sentidos PidfdChildWatcher es una implementación de niño vigilante «Ricitos de oro». No requiere señales o hilos, no interfiere con ningún proceso lanzado fuera del bucle de eventos y escala linealmente con el número de subprocesos lanzados por el bucle de eventos. La principal desventaja es que los pidfds son específicos de Linux y solo funcionan en kernels recientes (5.3+).

Nuevo en la versión 3.9.

Personalizar Políticas

Para implementar una nueva política de bucle de eventos, se recomienda heredar DefaultEventLoopPolicy y sobreescribir los métodos para los cuales se desea una conducta personalizada, por ejemplo:

class MyEventLoopPolicy(asyncio.DefaultEventLoopPolicy):

    def get_event_loop(self):
        """Get the event loop.

        This may be None or an instance of EventLoop.
        """
        loop = super().get_event_loop()
        # Do something with loop ...
        return loop

asyncio.set_event_loop_policy(MyEventLoopPolicy())

Soporte de plataforma

El módulo asyncio está diseñado para ser portátil, pero algunas plataformas tienen diferencias y limitaciones sutiles debido a la arquitectura y las capacidades subyacentes de las plataformas.

Todas las Plataformas

loop.add_reader() y loop.add_writer() no se pueden utilizar para supervisar la E/S del archivo.

Windows

Código fuente: Lib/asyncio/proactor_events.py [https://github.com/python/cpython/tree/3.9/Lib/asyncio/proactor_events.py], Lib/asyncio/windows_events.py [https://github.com/python/cpython/tree/3.9/Lib/asyncio/windows_events.py], Lib/asyncio/windows_utils.py [https://github.com/python/cpython/tree/3.9/Lib/asyncio/windows_utils.py]

Distinto en la versión 3.8: En Windows, ProactorEventLoop es ahora el bucle de eventos predeterminado.

Todos los bucles de eventos en Windows no admiten los métodos siguientes:

loop.create_unix_connection() y loop.create_unix_server() no son compatibles. La familia de sockets socket.AF_UNIX es específica de Unix.

loop.add_signal_handler() y loop.remove_signal_handler() no son compatibles.

SelectorEventLoop tiene las siguientes limitaciones:

SelectSelector se utiliza para esperar los eventos de los sockets: soporta los sockets y está limitado a 512 sockets.

loop.add_reader() y loop.add_writer() sólo aceptan manejadores de sockets (por ejemplo, los descriptores de archivos de tuberías no están soportados).

Las tuberías no están soportadas, por lo que los métodos loop.connect_read_pipe() y loop.connect_write_pipe() no están implementados.

Subprocesos no están soportados, es decir, los métodos loop.subprocess_exec() y loop.subprocess_shell() no están implementados.

ProactorEventLoop tiene las siguientes limitaciones:

Los métodos loop.add_reader() y loop.add_writer() no están soportados.

La resolución del reloj monótono de Windows suele ser de unos 15,6 mseg. La mejor resolución es de 0,5 mseg. La resolución depende del hardware (disponibilidad de HPET [https://es.wikipedia.org/wiki/High_Precision_Event_Timer]) y de la configuración de Windows.

Soporte de sub-procesos en Windows

En Windows, el bucle de eventos por defecto ProactorEventLoop soporta subprocesos, mientras que SelectorEventLoop no lo hace.

La función policy.set_child_watcher() tampoco está soportada, ya que ProactorEventLoop tiene un mecanismo diferente para vigilar los procesos hijos.

macOS

Las versiones modernas de MacOS son totalmente compatibles.

macOS <= 10.8

En macOS 10.6, 10.7 y 10.8, el bucle de eventos por defecto utiliza selectors.KqueueSelector, que no soporta dispositivos de caracteres en estas versiones. El SelectorEventLoop puede ser configurado manualmente para usar SelectSelector o PollSelector para soportar dispositivos de caracteres en estas versiones antiguas de macOS. Ejemplo:

import asyncio
import selectors

selector = selectors.SelectSelector()
loop = asyncio.SelectorEventLoop(selector)
asyncio.set_event_loop(loop)

Índice de API de alto nivel

Esta página lista todas las APIs async/await habilitadas de alto nivel.

Tareas

Utilidades para ejecutar programas asyncio, crear Tareas, y esperar en múltiples cosas con tiempos de espera.

run()

Crea un loop de eventos, ejecuta una corrutina, cierra el loop.

create_task()

Lanza una Tarea asyncio.

await sleep()

Duerme por un número de segundos.

await gather()

Programa y espera por cosas concurrentemente.

await wait_for()

Ejecuta con un tiempo de expiración.

await shield()

Protege de la cancelación.

await wait()

Monitorea la completitud.

current_task()

Retorna la Tarea actual.

all_tasks()

Retorna todas las tareas para un loop de eventos.

Task

Objeto Tarea.

to_thread()

Ejecute de forma asincrónica una función en un subproceso del sistema operativo independiente.

run_coroutine_threadsafe()

Programa una corrutina de desde otro hilo del sistema operativo.

for in as_completed()

Monitorea por completitud con un loop for.

Ejemplos

Usando asyncio.gather() para ejecutar cosas en paralelo.

Usando asyncio.wait_for() para forzar un tiempo de expiración.

Cancelación.

Usando asyncio.sleep().

Ver también la página principal de documentación de Tareas.

Colas

Las colas deberían ser usadas para distribuir trabajo entre múltiples Tareas asyncio, implementar pools de conexiones y patrones pub/sub.

Queue

Una cola FIFO.

PriorityQueue

Una cola de prioridad.

LifoQueue

Una cola LIFO.

Ejemplos

Usando asyncio.Queue para distribuir carga de trabajo entre varias Tareas.

Ver también la página de documentación de Colas.

Subprocesos

Utilidades para generar subprocesos y ejecutar comandos de consola.

await create_subprocess_exec()

Crea un subproceso.

await create_subprocess_shell()

Ejecuta un comando de consola.

Ejemplos

Ejecutando un comando de consola.

Ver también la documentación de las APIs de subprocesos.

Flujos

APIs de alto nivel para trabajar con IO de red.

await open_connection()

Establece una conexión TCP.

await open_unix_connection()

Establece una conexión de un socket Unix.

await start_server()

Lanza un servidor TCP.

await start_unix_server()

Lanza un servidor de sockets Unix.

StreamReader

Objeto de alto nivel async/await para recibir datos de red.

StreamWriter

Objeto de alto nivel async/await para enviar datos de red.

Ejemplos

Cliente TCP de ejemplo.

Ver también la documentación de APIs de flujos.

Sincronización

Primitivas de sincronización al estilo hilos que pueden ser usadas en Tareas.

Lock

Un bloqueo mutex.

Event

Un objeto de evento.

Condition

Un objeto de condición.

Semaphore

Un semáforo.

BoundedSemaphore

Un semáforo acotado.

Ejemplos

Usando asyncio.Event.

Ver también la documentación de las primitivas de sincronización de asyncio.

Excepciones

asyncio.TimeoutError

Lanzado en tiempos de expiración por funciones como wait_for(). Ten en mente que asyncio.TimeoutError` no está relacionada con la excepción predefinida TimeoutError.

asyncio.CancelledError

Lanzada cuando una Tarea es cancelada. Ver también Task.cancel().

Ejemplos

Gestionando CancelledError para ejecutar código en petición de cancelación.

Ver también la lista completa de excepciones específicas de asyncio.

Índice de API de bajo nivel

Esta página enumera todas las APIs de asyncio de bajo nivel.

Obtención del bucle de eventos

asyncio.get_running_loop()

La función preferida para obtener el bucle de eventos en ejecución.

asyncio.get_event_loop()

Obtiene una instancia del bucle de eventos (actual o mediante la política del bucle).

asyncio.set_event_loop()

Establece el bucle de eventos como actual a través de la política del bucle.

asyncio.new_event_loop()

Crea un nuevo bucle de eventos.

Ejemplos

Usando asyncio.get_running_loop().

Métodos del bucle de eventos

Consulte también la sección de la documentación principal sobre los métodos del bucle de eventos.

Ciclo de vida

loop.run_until_complete()

Ejecuta un Future/Tarea/aguardable (awaitable) hasta que se complete.

loop.run_forever()

Ejecuta el bucle de eventos para siempre.

loop.stop()

Detiene el bucle de eventos.

loop.close()

Cierra el bucle de eventos.

loop.is_running()

Retorna True si el bucle de eventos se está ejecutando.

loop.is_closed()

Retorna True si el bucle de eventos está cerrado.

await loop.shutdown_asyncgens()

Cierra generadores asincrónicos.

Depuración

loop.set_debug()

Habilita o deshabilita el modo de depuración.

loop.get_debug()

Obtiene el modo de depuración actual.

Programación de devoluciones de llamada

loop.call_soon()

Invoca una devolución de llamada soon.

loop.call_soon_threadsafe()

Una variante segura para subprocesos de loop.call_soon().

loop.call_later()

Invoca una devolución de llamada después del tiempo especificado.

loop.call_at()

Invoca una devolución de llamada en el tiempo especificado.

Hilo/Grupo de procesos

await loop.run_in_executor()

Ejecuta una función de bloqueo vinculada a la CPU o de otro tipo en un ejecutor concurrent.futures.

loop.set_default_executor()

Establece el ejecutor predeterminado para loop.run_in_executor().

Tareas y Futures

loop.create_future()

Crea un objeto Future.

loop.create_task()

Programa una corrutina como Task.

loop.set_task_factory()

Establece una fábrica utilizada por loop.create_task() para crear Tareas.

loop.get_task_factory()

Obtiene la fábrica loop.create_task() que se usa para crear Tareas.

DNS

await loop.getaddrinfo()

Versión asincrónica de socket.getaddrinfo().

await loop.getnameinfo()

Versión asincrónica de socket.getnameinfo().

Redes e IPC

await loop.create_connection()

Abre una conexión TCP.

await loop.create_server()

Crea un servidor TCP.

await loop.create_unix_connection()

Abre una conexión de socket Unix.

await loop.create_unix_server()

Crea un servidor socket de Unix.

await loop.connect_accepted_socket()

Envuelve un socket en un par (transport, protocol).

await loop.create_datagram_endpoint()

Abre una conexión de datagramas (UDP).

await loop.sendfile()

Envía un archivo a través del transporte.

await loop.start_tls()

Actualiza una conexión existente a TLS.

await loop.connect_read_pipe()

Envuelve el fin de lectura de pipe en un par (transport, protocol).

await loop.connect_write_pipe()

Envuelve el fin de escritura de pipe en un par (transport, protocol).

Sockets

await loop.sock_recv()

Recibe datos de socket.

await loop.sock_recv_into()

Recibe datos de socket en un buffer.

await loop.sock_sendall()

Envía datos a socket.

await loop.sock_connect()

Conecta con socket.

await loop.sock_accept()

Acepta una conexión socket.

await loop.sock_sendfile()

Envía un archivo a través de socket.

loop.add_reader()

Comienza a monitorear un descriptor de archivo para ver la disponibilidad de lectura.

loop.remove_reader()

Detiene el monitoreo del descriptor de archivo para ver la disponibilidad de lectura.

loop.add_writer()

Comienza a monitorear un descriptor de archivo para ver la disponibilidad de escritura.

loop.remove_writer()

Detiene el monitoreo del descriptor de archivo para ver la disponibilidad de escritura.

Señales Unix

loop.add_signal_handler()

Añade un gestor para signal.

loop.remove_signal_handler()

Elimina un gestor para signal.

Subprocesos

loop.subprocess_exec()

Genera un subproceso.

loop.subprocess_shell()

Genera un subproceso desde un comando de shell.

Gestor de errores

loop.call_exception_handler()

Invoca al gestor de excepciones.

loop.set_exception_handler()

Establece un nuevo gestor de excepciones.

loop.get_exception_handler()

Obtiene el gestor de excepciones actual.

loop.default_exception_handler()

La implementación predetermina del gestor de excepciones.

Ejemplos

Usando asyncio.get_event_loop() y loop.run_forever().

Usando loop.call_later().

Usando loop.create_connection() para implementar un cliente de eco.

Usando loop.create_connection() para conectar a un socket.

Usando add_reader() para mirar un FD y leer eventos.

Usando loop.add_signal_handler().

Usando loop.subprocess_exec().

Transportes

Todos los transportes implementan los siguientes métodos:

transport.close()

Cierra el transporte.

transport.is_closing()

Retorna True si el transporte está cerrado o se está cerrando.

transport.get_extra_info()

Solicita información sobre el transporte.

transport.set_protocol()

Establece un nuevo protocolo.

transport.get_protocol()

Retorna el protocolo actual.

Transportes que pueden recibir datos (conexiones TCP y Unix, pipes, etc). Retornan de métodos como loop.create_connection(), loop.create_unix_connection(), loop.connect_read(), etc:

Leer transportes

transport.is_reading()

Retorna True si el transporte está recibiendo.

transport.pause_reading()

Pausa la recepción.

transport.resume_reading()

Reanuda la recepción.

Transportes que pueden enviar datos (conexiones TCP y Unix, pipes, etc). Retornan de métodos como loop.create_connection(), loop.create_unix_connection(), loop.connect_write_pipe(), etc:

Escribir transportes

transport.write()

Escribe datos en el transporte.

transport.writelines()

Escribe búferes en el transporte.

transport.can_write_eof()

Retorna True si el transporte admite el envío de EOF.

transport.write_eof()

Cierra y envía EOF después de vaciar los datos almacenados en búfer.

transport.abort()

Cierra el transporte inmediatamente.

transport.get_write_buffer_size()

Retorna los límites superior e inferior para controlar el flujo de escritura.

transport.set_write_buffer_limits()

Establece nuevos límites superior e inferior para el control del flujo de escritura.

Transportes retornados por loop.create_datagram_endpoint():

Transportes de datagramas

transport.sendto()

Envía datos al par remoto.

transport.abort()

Cierra el transporte inmediatamente.

Abstracción de transporte de bajo nivel sobre subprocesos. Retornado por loop.subprocess_exec() y loop.subprocess_shell():

Transportes de subprocesos

transport.get_pid()

Retorna el id de proceso del subproceso.

transport.get_pipe_transport()

Retorna el transporte para la pipe de comunicación solicitada (stdin, stdout o stderr).

transport.get_returncode()

Retorna el código de retorno del subproceso.

transport.kill()

Mata el subproceso.

transport.send_signal()

Envía una señal al subproceso.

transport.terminate()

Detiene el subproceso.

transport.close()

Mata el subproceso y cierra todas las pipes.

Protocolos

Las clases de protocolo pueden implementar los siguientes métodos de devolución de llamada:

callback connection_made()

Se llama cuando se establece una conexión.

callback connection_lost()

Se llama cuando la conexión se pierde o cierra.

callback pause_writing()

Se llama cuando el búfer del transporte excede el límite superior.

callback resume_writing()

Se llama cuando el búfer del transporte se vacía por debajo del límite inferior.

Protocolos de streaming (TCP, Unix Sockets, Pipes)

callback data_received()

Se llama cuando se reciben algunos datos.

callback eof_received()

Se llama cuando se recibe un EOF.

Protocolos de streaming en búfer

callback get_buffer()

Se llama para asignar un nuevo búfer de recepción.

callback buffer_updated()

Se llama cuando el búfer se actualizó con los datos recibidos.

callback eof_received()

Se llama cuando se recibe un EOF.

Protocolos de datagramas

callback datagram_received()

Se llama cuando se recibe un datagrama.

callback error_received()

Se llama cuando una operación de envío o recepción anterior genera un OSError.

Protocolos de subprocesos

callback pipe_data_received()

Se llama cuando el proceso hijo escribe datos en su pipe stdout o stderr.

callback pipe_connection_lost()

Se llama cuando se cierra un pipe que se comunica con el proceso hijo.

callback process_exited()

Se llama cuando el proceso hijo ha finalizado.

Políticas de bucle de eventos

Las políticas son un mecanismo de bajo nivel para alterar el comportamiento de funciones como asyncio.get_event_loop(). Vea también la sección principal políticas para más detalles.

Acceso a políticas

asyncio.get_event_loop_policy()

Retorna la política actual en todo el proceso.

asyncio.set_event_loop_policy()

Establece una nueva política para todo el proceso.

AbstractEventLoopPolicy

Clase base para objetos de política.

Desarrollando con asyncio

La programación asincrónica es diferente a la programación «secuencial» clásica.

Esta página enumera errores y trampas comunes y explica cómo evitarlos.

Modo Depuración

Por defecto asyncio se ejecuta en modo producción. Para facilitar el desarrollo asyncio tiene un modo depuración.

Hay varias maneras de habilitar el modo depuración de asyncio:

Definiendo la variable de entorno PYTHONASYNCIODEBUG a 1.

Usando Modo de Desarrollo de Python.

Pasando debug=True a asyncio.run().

Invocando loop.set_debug().

Además de habilitar el modo depuración, considere también:

definir el nivel de log del asyncio logger a logging.DEBUG, por ejemplo el siguiente fragmento de código puede ser ejecutado al inicio de la aplicación:

logging.basicConfig(level=logging.DEBUG)

configurando el módulo warnings para mostrar advertencias ResourceWarning. Una forma de hacerlo es usando la opción -W default de la línea de comandos.

Cuando el modo depuración está habilitado:

asyncio comprueba las corrutinas que no son esperadas y las registra; esto mitiga la dificultad de las «esperas olvidadas».

Muchas APIs asyncio que no son seguras para hilos (como los métodos loop.call_soon() y loop.call_at()) generan una excepción si son llamados desde un hilo equivocado.

El tiempo de ejecución del selector E/S es registrado si tarda demasiado tiempo en realizar una operación E/S.

Los callbacks que tardan más de 100ms son registrados. El atributo loop.slow_callback_duration puede ser usado para definir la duración mínima de ejecución en segundos considerada como «lenta».

Concurrencia y Multihilo

Un bucle de eventos se ejecuta en un hilo (generalmente el hilo principal) y ejecuta todos los callbacks y las Tareas en su hilo. Mientras una Tarea está ejecutándose en el bucle de eventos, ninguna otra Tarea puede ejecutarse en el mismo hilo. Cuando una Tarea ejecuta una expresión await, la Tarea en ejecución se suspende y el bucle de eventos ejecuta la siguiente Tarea.

Para programar un callback desde otro hilo del SO, se debe usar el método loop.call_soon_threadsafe(). Ejemplo:

loop.call_soon_threadsafe(callback, *args)

Casi ningún objeto asyncio es seguro entre hilos (thread safe), lo cual generalmente no es un problema a no ser que haya código que trabaje con ellos desde fuera de una Tarea o un callback. Si tal código necesita llamar a la API de asyncio de bajo nivel, se debe usar el método loop.call_soon_threadsafe(), por ejemplo:

loop.call_soon_threadsafe(fut.cancel)

Para programar un objeto de corrutina desde una hilo diferente del sistema operativo se debe usar la función run_coroutine_threadsafe(). Esta retorna un concurrent.futures.Future para acceder al resultado:

async def coro_func():
     return await asyncio.sleep(1, 42)

# Later in another OS thread:

future = asyncio.run_coroutine_threadsafe(coro_func(), loop)
# Wait for the result:
result = future.result()

Para manejar señales y ejecutar subprocesos, el bucle de eventos debe ser ejecutado en el hilo principal.

El método loop.run_in_executor() puede ser usado con un concurrent.futures.ThreadPoolExecutor para ejecutar código bloqueante en un hilo diferente del sistema operativo sin bloquear el hilo del sistema operativo en el que el bucle de eventos está siendo ejecutado.

Actualmente no hay forma de programar corrutinas o devoluciones de llamada directamente desde un proceso diferente (como uno que comenzó con multiprocessing). La sección Event Loop Methods enumera las APIs que pueden leer desde las tuberías y ver descriptores de archivos sin bloquear el bucle de eventos. Además, las APIs de asyncio Subprocess proporcionan una forma de iniciar un proceso y comunicarse con él desde el bucle de eventos. Por último, el método loop.run_in_executor() mencionado anteriormente también se puede usar con un concurrent.futures.ProcessPoolExecutor para ejecutar código en un proceso diferente.

Ejecutando Código Bloqueante

Código bloqueante (dependiente de la CPU) no debe ser ejecutado directamente. Por ejemplo, si una función realiza un cálculo intensivo de CPU durante 1 segundo, todas las Tareas y operaciones de Entrada/Salida (IO) concurrentes se retrasarían 1 segundo.

Un ejecutor puede ser usado para ejecutar una tarea en un hilo diferente o incluso en un proceso diferente para evitar bloquear el hilo del sistema operativo con el bucle de eventos. Consulte el método loop.run_in_executor() para más detalles.

Logueando

asyncio usa el módulo logging y todo el logueo es realizado mediante el logger "asyncio".

El nivel de log por defecto es logging.INFO, el cual puede ser fácilmente ajustado:

logging.getLogger("asyncio").setLevel(logging.WARNING)

Detectar corrutinas no esperadas

Cuando una función de corrutina es invocada, pero no esperada (por ejemplo coro() en lugar de await coro()) o la corrutina no es programada con asyncio.create_task(), asyncio emitirá una RuntimeWarning:

import asyncio

async def test():
    print("never scheduled")

async def main():
    test()

asyncio.run(main())

Salida:

test.py:7: RuntimeWarning: coroutine 'test' was never awaited
  test()

Salida en modo depuración:

test.py:7: RuntimeWarning: coroutine 'test' was never awaited
Coroutine created at (most recent call last)
  File "../t.py", line 9, in <module>
    asyncio.run(main(), debug=True)

  < .. >

  File "../t.py", line 7, in main
    test()
  test()

La solución habitual es esperar la corrutina o llamar a la función asyncio.create_task():

async def main():
    await test()

Detectar excepciones nunca recuperadas

Si un Future.set_exception() es invocado pero el objeto Futuro nunca es esperado, la excepción nunca será propagada al código del usuario. En este caso, asyncio emitiría un mensaje de registro cuando el objeto Futuro fuera recolectado como basura.

Ejemplo de una excepción no manejada:

import asyncio

async def bug():
    raise Exception("not consumed")

async def main():
    asyncio.create_task(bug())

asyncio.run(main())

Salida:

Task exception was never retrieved
future: <Task finished coro=<bug() done, defined at test.py:3>
  exception=Exception('not consumed')>

Traceback (most recent call last):
  File "test.py", line 4, in bug
    raise Exception("not consumed")
Exception: not consumed

Habilita el modo depuración para obtener el seguimiento de pila (traceback) donde la tarea fue creada:

asyncio.run(main(), debug=True)

Salida en modo depuración:

Task exception was never retrieved
future: <Task finished coro=<bug() done, defined at test.py:3>
    exception=Exception('not consumed') created at asyncio/tasks.py:321>

source_traceback: Object created at (most recent call last):
  File "../t.py", line 9, in <module>
    asyncio.run(main(), debug=True)

< .. >

Traceback (most recent call last):
  File "../t.py", line 4, in bug
    raise Exception("not consumed")
Exception: not consumed

socket — interfaz de red de bajo nivel

Código fuente: Lib/socket.py [https://github.com/python/cpython/tree/3.9/Lib/socket.py]

Este módulo proporciona acceso a la interfaz BSD socket. Está disponible en todos los sistemas Unix modernos, Windows, MacOS y probablemente plataformas adicionales.

Nota

Algunos comportamientos pueden depender de la plataforma, ya que las llamadas se realizan a las API de socket del sistema operativo.

La interfaz de Python es una transcripción sencilla de la llamada al sistema Unix y la interfaz de la biblioteca para sockets al estilo orientado a objetos de Python: la función socket() devuelve a socket object cuyos métodos implementan las diversas llamadas al sistema de socket. Los tipos de parámetros tienen un nivel algo más alto que en la interfaz C: como con read() y write() en las operaciones en los archivos Python, la asignación del buffer en las operaciones de recepción es automática y la longitud del buffer está implícita en las operaciones de envío.

Ver también

Módulo socketserver

Clases que simplifican la escritura de servidores de red.

Módulo ssl

Un contenedor TLS/SSL para objetos de socket.

Familias Socket

Dependiendo del sistema y de las opciones de compilación, este módulo admite varias familias de sockets.

El formato de dirección requerido por un objeto de socket determinado se selecciona automáticamente en función de la familia de direcciones especificada cuando se creó el objeto de socket. Las direcciones de socket se representan de la siguiente manera:

La dirección de un socket AF_UNIX enlazado a un nodo del sistema de archivos es representado como una cadena de caracteres, utilizando la codificación del sistema de archivos y el controlador de errores 'surrogateescape' (Observar PEP 383 [https://www.python.org/dev/peps/pep-0383]). Una dirección en el espacio de nombre abstracto de Linux es devuelvo como un bytes-like object con un byte inicial nulo; tenga en cuenta que los sockets en este nombre de espacio puede comunicarse con sockets normales del sistema de archivos, así que los programas destinados a correr en Linux podrían necesitar tratar con ambos tipos de direcciones. Se puede pasar un objeto similar a una cadena de caracteres o bytes para cualquier tipo de dirección al pasarlo como argumento.

Distinto en la versión 3.3: Anteriormente, se suponía que las rutas de socket AF_UNIX utilizaban codificación UTF-8.

Distinto en la versión 3.5: Ahora se acepta la grabación bytes-like object.

Un par (host, puerto) se utiliza para la familia de direcciones AF_INET, donde host es una cadena que representa un nombre de host en notación de dominio de Internet como 'daring.cwi.nl' o una dirección IPv4 como '100.50.200.5' y puerto es un entero.

Para direcciones IPv4, se aceptan dos formas especiales en lugar de una dirección de host: ’’ representa INADDR_ANY, que se utiliza para enlazar a todas las interfaces, y la cadena de caracteres '<broadcast>' representa INADDR_BROADCAST. Este comportamiento no es compatible con IPv6, por lo tanto, es posible que desee evitarlos sí tiene la intención de admitir IPv6 con sus programas Python.

Para la familia de direcciones AF_INET6, se utiliza una (host, port, flowinfo, scope_id) de cuatro tuplas, donde flowinfo y scope_id representan los miembros sin6_flowinfo y sin6_scope_id en struct sockaddr_in6 en C. Para los métodos de los módulos socket, flowinfo y scope_id pueden ser omitidos solo por compatibilidad con versiones anteriores. Sin embargo la omisión de scope_id puede causar problemas en la manipulación de direcciones IPv6 con ámbito.

Distinto en la versión 3.7: Para direcciones de multidifusión (con scopeid significativo) address puede no contener la parte %scope (o zone id). Esta información es superflua y puede omitirse de forma segura (recomendado).

AF_NETLINK sockets se representan como pares (pid, groups).

La compatibilidad con LINUX solo para TIPC está disponible mediante la familia de direcciones AF_TIPC. TIPC es un protocolo en red abierto y no basado en IP diseñado para su uso en entornos informáticos agrupados. Las direcciones se representan mediante una tupla y los campos dependen del tipo de dirección. El formulario de tupla general es (addr_type, v1, v2, v3 [, scope]), donde:

addr_type es uno de TIPC_ADDR_NAMESEQ, TIPC_ADDR_NAME, o TIPC_ADDR_ID.

scope es una de TIPC_ZONE_SCOPE, TIPC_CLUSTER_SCOPE, y TIPC_NODE_SCOPE.

Si addr_type es TIPC_ADDR_NAME, entonces v1 es el tipo de servidor, v2 es el identificador de puerto, y v3 debe ser 0.

Si addr_type es TIPC_ADDR_NAMESEQ, entonces v1 es el tipo de servidor, v2 es el numero de puerto inferior, y v3 es el numero de puerto superior.

Si addr_type es TIPC_ADDR_ID, v1 es el nodo, v2 es la referencia y v3 debe establecerse en 0.

Una tupla (interface, ) es usada para la dirección de familia AF_CAN, donde interface es una cadena de caracteres representando a un nombre de interfaz de red como ’can0’. La interfaz de red llamada '' puede ser usada para recibir paquetes de todas las interfaces de red de esta familia.

Protocolo CAN_ISOTP requiere una tupla (interface, rx_addr, tx_addr) donde ambos tiene parámetros adicionales son enteres largos sin símbolos que representan una identificador CAN (estándar o extendido).

Protocolo CAN_J1939 requiere una tupla (interface, name, pgn, addr) donde los parámetros adicionales son números enteros sin signo de 64 bits representando el nombre ECU, los enteros sin signo de 32-bits representan el numero de grupo de parámetros(PGN), y los enteros de 8-bit representan la dirección.

Se utiliza una cadena o una tupla (id, unit) para el protocolo SYSPROTO_CONTROL de la familia PF_SYSTEM. La cadena es el nombre de un control de kernel mediante un IDENTIFICADOR asignado dinámicamente. La tupla se puede utilizar si se conoce el ID y el número de unidad del control del kernel o si se utiliza un ID registrado.

Nuevo en la versión 3.3.

AF_BLUETOOTH admite los siguientes protocolos y formatos de dirección:

BTPROTO_L2CAP acepta (bdaddr, psm) donde bdaddr es la dirección Bluetooth como una cadena de caracteres y psm es un entero.

BTPROTO_RFCOMM acepta (bdaddr, channel) donde bdaddr es la dirección Bluetooth como una cadena de caracteres y channel es un entero.

BTPROTO_HCI acepta (device_id,) donde device_id es un numero entero o una cadena de caracteres con la dirección Bluetooth de la interfaz. (Esto depende de tu OS; NetBSD y DragonFlyBSD supone una dirección Bluetooth mientras todo lo demás espera un entero.)

Distinto en la versión 3.2: Se ha añadido compatibilidad con NetBSD y DragonFlyBSD.

BTPROTO_SCO acepta bdaddr donde bdaddr es un objeto bytes que contiene la dirección Bluetooth en un formato cadena. (ex. b’12:23:34:45:56:67’) este protocolo no es admitido bajo FreeBSD.

AF_ALG es una interfaz basada en socket sólo Linux para la criptografía del núcleo. Un socket de algoritmo se configura con una tupla de dos a cuatro elementos (type, name [, feat [, mask]]), donde:

type es el tipo de algoritmos como cadenas de caracteres, e.g. aead, hash, skcipher o rng.

name es el nombre del algoritmo y el modo de operación como cadena de caracteres, e.g. sha256, hmac(sha256), cbc(aes) o drbg_nopr_ctr_aes256.

feat y mask son enteros de 32 bits sin signo.

Availability: Linux 2.6.38, some algorithm types require more recent Kernels.

Nuevo en la versión 3.6.

AF_VSOCK permite comunicación entre maquinas virtuales y sus hosts. Los sockets están representando como una tupla (CID, port) donde el contexto del ID o CID y el puerto son enteros.

Availability: Linux >= 4.8 QEMU >= 2.8 ESX >= 4.0 ESX Workstation >= 6.5.

Nuevo en la versión 3.7.

AF_PACKET es una interfaz de bajo nivel directa con los dispositivos de red. Los paquetes están representados por la tupla (ifname, proto[, pkttype[, hatype[, addr]]]) donde:

ifname - Cadena que especifica el nombre del dispositivo.

proto - Un entero en orden de byte de red que especifica el número de protocolo Ethernet.

pkttype - Entero opcional especificando el tipo de paquete:

PACKET_HOST (por defecto) - Paquetes diseccionado al local host.

PACKET_BROADCAST - Paquete de transmisión de la capa física.

PACKET_MULTIHOST - Paquete enviado a una dirección de multidifusión de capa física.

PACKET_OTHERHOST - Paquete a otro host que haya sido capturado por un controlador de dispositivo en modo promiscuo.

PACKET_OUTGOING - Paquete originalmente desde el local host que se enlaza de nuevo a un conector de paquetes.

hatype - Entero opcional que especifica el tipo de dirección de hardware ARP.

addr - Objeto opcional en forma de bytes que especifica la dirección física del hardware, cuya interpretación depende del dispositivo.

Availability: Linux >= 2.2.

AF_QIPCRTR es una interfaz basada en sockets solo para Linux para comunicarse con servicios que se ejecutan en co-procesadores en plataformas Qualcomm. La familia de direcciones se representa como una tupla (node, port) donde el node y port son enteros no negativos.

Availability: Linux >= 4.7.

Nuevo en la versión 3.8.

IPPROTO_UDPLITE es una variante de UDO que te permite especificar que porción del paquete es cubierta con la suma de comprobación. Esto agrega dos opciones al socket que pueden cambiar. self.setsockopt(IPPROTO_UDPLITE, UDPLITE_SEND_CSCOV, length) cambiara que parte de los paquetes salientes están cubierta por la suma de comprobación y self.setsockopt(IPPROTO_UDPLITE, UDPLITE_RECV_CSCOV, length) filtrara los paquetes que permitirá cubrir una pequeña parte de tu datos. En ambos casos length deben estar en range(8, 2**16, 8).

Tal socket debe construirse como socket(AF_INET, SOCK_DGRAM, IPPROTO_UDPLITE) para IPV4 o socket(AF_INET6, SOCK_DGRAM, IPPROTO_UDPLITE)` para IPV6.

Availability: Linux >= 2.6.20, FreeBSD >= 10.1-RELEASE

Nuevo en la versión 3.9.

Si utiliza un nombre de host en la parte host de la dirección de socket IPv4/v6, el programa puede mostrar un comportamiento no determinista, ya que Python utiliza la primera dirección devuelta por la resolución DNS. La dirección del socket se resolverá de manera diferente en una dirección IPv4/v6 real, dependiendo de los resultados de la resolución DNS y/o la configuración del host. Para un comportamiento determinista, utilice una dirección numérica en la parte host.

Todos los errores generan excepciones. Se pueden generar las excepciones normales para los tipos de argumento no válidos y las condiciones de memoria insuficiente; a partir de Python 3.3, los errores relacionados con la semántica de socket o direcciones generan OSError o una de sus subclases (solían generar socket.error).

El modo de no bloqueo es compatible a través de setblocking(). Se admite una generalización de esto basada en los tiempos de espera a través de settimeout().

Contenido del módulo

El módulo socket exporta los siguientes elementos.

Excepciones

exception socket.error

Un alias en desuso de OSError.

Distinto en la versión 3.3: Siguiendo PEP 3151 [https://www.python.org/dev/peps/pep-3151], es clase fue creada como un alias de OSError.

exception socket.herror

Una subclase de OSError, esta excepción se produce para los errores relacionados con la dirección, es decir, para las funciones que utilizan h_errno en la API de POSIX C, incluidas gethostbyname_ex() y gethostbyaddr(). El valor adjunto es un par (h_errno, string) que representa un error devuelto por una llamada a la biblioteca. h_errno es un valor numérico, mientras que string representa la descripción de h_errno, devuelta por la función hstrerror() C.

Distinto en la versión 3.3: Esta clase fue creada como una subclase de OSError.

exception socket.gaierror

Una subclase de OSError, esta excepción se genera por errores relacionados a la dirección por getaddrinfo() y getnameinfo(). El valor de acompañamiento es un par (error, string) representado un error retornado por una llamada de librería. string representa la descripción del error, tal como es retornado por la función C gai_strerror(). El valor numérico error coincide con una de las constantes EAI_* definidas en este modulo.

Distinto en la versión 3.3: Esta clase fue creada como una subclase de OSError.

exception socket.timeout

Una subclase de OSError, esta excepción se genera cuando ocurre un timeout en un socket que ha tenido tiempos de espera habilitados a través de una llamada previa a settimeout() ( o implícitamente mediante setdefaulttimeout()). El valor del acompañamiento es una cadena de caracteres cuyo valor es actualmente siempre “tiempo de espera”.

Distinto en la versión 3.3: Esta clase fue creada como una subclase de OSError.

Constantes

Las constantes AF_* y SOCK_* ahora son colecciones: AddressFamily y SocketKind IntEnum.

Nuevo en la versión 3.4.

socket.AF_UNIX

socket.AF_INET

socket.AF_INET6

Estas constantes representan la familias de direcciones (y protocolos), usados para el primer argumento para socket(). Si la constante AF_UNIX no esta definida entonces este protocolo no es compatible. Mas constantes podrían estar disponibles dependiendo del sistema.

socket.SOCK_STREAM

socket.SOCK_DGRAM

socket.SOCK_RAW

socket.SOCK_RDM

socket.SOCK_SEQPACKET

Estas constantes representan los tipos de socket, usadas por el segundo argumento para socket(). Mas constante podrían estar disponibles dependiendo del sistema. ( Solamente SOCK_STREAM y SOCK_DGRAM parecen ser útiles en general.)

socket.SOCK_CLOEXEC

socket.SOCK_NONBLOCK

Estas dos constantes, si se definen, se pueden combinar con los tipos de socket y le permiten establecer algunas banderas atómicamente (evitando así posibles condiciones de carrera y la necesidad de llamadas separadas).

Ver también

Secure File Descriptor Handling [http://udrepper.livejournal.com/20407.html] para una explicación más completa.

Availability: Linux >= 2.6.27.

Nuevo en la versión 3.2.

SO_*

socket.SOMAXCONN

MSG_*

SOL_*

SCM_*

IPPROTO_*

IPPORT_*

INADDR_*

IP_*

IPV6_*

EAI_*

AI_*

NI_*

TCP_*

Muchas constantes de estos formularios, documentadas en la documentación de Unix en sockets y/o el protocolo IP, también se definen en el módulo de socket. Generalmente se utilizan en argumentos de los métodos setsockopt() y getsockopt() de objetos socket. En la mayoría de los casos, solo se definen los símbolos definidos en los archivos de encabezado Unix; para algunos símbolos, se proporcionan valores predeterminados.

Distinto en la versión 3.6: SO_DOMAIN, SO_PROTOCOL, SO_PEERSEC, SO_PASSSEC, TCP_USER_TIMEOUT, TCP_CONGESTION han sido agregados.

Distinto en la versión 3.6.5: En Windows, TCP_FASTOPEN, TCP_KEEPCNT aparecen si el tiempo de ejecución de Windows lo admite.

Distinto en la versión 3.7: TCP_NOTSENT_LOWAT ha sido agregada.

En Windows, TCP_KEEPIDLE, TCP_KEEPINTVL aparecen si el tiempo de ejecución de Windows lo admite.

socket.AF_CAN

socket.PF_CAN

SOL_CAN_*

CAN_*

Muchas constantes de estos formularios, documentadas en la documentación de Linux, también se definen en el módulo de socket.

Availability: Linux >= 2.6.25.

Nuevo en la versión 3.3.

socket.CAN_BCM

CAN_BCM_*

CAN_BCM, en la familia de protocolo CAN, es el protocolo del administrador de difusión (BCM. Las constantes del administrador de difusión, documentada en la documentación de Linux, también esta definidos en el modulo socket.

Availability: Linux >= 2.6.25.

Nota

El indicador CAN_BCM_CAN_FD_FRAME esta solamente disponible en Linux >= 4.8.

Nuevo en la versión 3.4.

socket.CAN_RAW_FD_FRAMES

Habilita la compatibilidad con CAN FD en un socket CAN_RAW. Esta opción está deshabilitada de forma predeterminada. Esto permite que la aplicación envíe tramas CAN y CAN FD; sin embargo, debe aceptar las tramas CAN y CAN FD al leer desde el socket.

Esta constante se documenta en la documentación de Linux.

Availability: Linux >= 3.6.

Nuevo en la versión 3.5.

socket.CAN_RAW_JOIN_FILTERS

Se une a los filtros CAN aplicados de modo que solo las tramas CAN que coinciden con todos los filtros CAN dados se pasan al espacio del usuario.

Esta constante se documenta en la documentación de Linux.

Availability: Linux >= 4.1.

Nuevo en la versión 3.9.

socket.CAN_ISOTP

CAN_ISOTP, en el protocolo de familia CAN, es el protocolo ISO-TP (ISO 15765-2). Constantes ISO-TP, documentadas en la documentación Linux.

Availability: Linux >= 2.6.25.

Nuevo en la versión 3.7.

socket.CAN_J1939

CAN_J1939, en el protocolo de familias CAN, es el protocolo SAE J1939. Constantes J1939, documentadas en el documentación Linux.

Availability: Linux >= 5.4.

Nuevo en la versión 3.9.

socket.AF_PACKET

socket.PF_PACKET

PACKET_*

Muchas constantes de estos formularios, documentadas en la documentación de Linux, también se definen en el módulo de socket.

Availability: Linux >= 2.2.

socket.AF_RDS

socket.PF_RDS

socket.SOL_RDS

RDS_*

Muchas constantes de estos formularios, documentadas en la documentación de Linux, también se definen en el módulo de socket.

Availability: Linux >= 2.6.30.

Nuevo en la versión 3.3.

socket.SIO_RCVALL

socket.SIO_KEEPALIVE_VALS

socket.SIO_LOOPBACK_FAST_PATH

RCVALL_*

Constantes para Windows’ WSAIoctl(). Las constantes se utiliza como argumentos al método ioctl() de objetos de sockets.

Distinto en la versión 3.6: SIO_LOOPBACK_FAST_PATH ha sido agregado.

TIPC_*

LAS constantes relacionadas con TIPC, que coinciden con las exportadas por la API de socket de C. Consulte la documentación de TIPC para obtener más información.

socket.AF_ALG

socket.SOL_ALG

ALG_*

Constantes para la criptográfica del Kernel de Linux.

Availability: Linux >= 2.6.38.

Nuevo en la versión 3.6.

socket.AF_VSOCK

socket.IOCTL_VM_SOCKETS_GET_LOCAL_CID

VMADDR*

SO_VM*

Constantes para la comunicación host/invitado de Linux.

Availability: Linux >= 4.8.

Nuevo en la versión 3.7.

socket.AF_LINK

Availability: BSD, macOS.

Nuevo en la versión 3.4.

socket.has_ipv6

Esta constante contiene un valor booleano que indica si IPv6 se admite en esta plataforma.

socket.BDADDR_ANY

socket.BDADDR_LOCAL

Estas son constantes de cadenas que contienen direcciones Bluetooth con significados especiales. Por ejemplo BDADDR_ANY son usados para indicar cualquier dirección al especificar el socket vinculante con BTPROTO_RFCOMM.

socket.HCI_FILTER

socket.HCI_TIME_STAMP

socket.HCI_DATA_DIR

Para usar con BTPROTO_HCI. HCI_FILTER no esta disponible para NetBSD o DragonFlyBSD. HCI_TIME_STAMP y HCI_DATA_DIR no esta disponible para FreeBSD, NetBSD, o DragonFlyBSD.

socket.AF_QIPCRTR

Constante para el protocolo de router IPC de Qualcomm, que se utiliza para comunicarse con procesadores remotos que brindan servicios.

Availability: Linux >= 4.7.

Funciones

Creación de sockets

Todas las siguientes funciones crean socket objects.

class socket.socket(family=AF_INET, type=SOCK_STREAM, proto=0, fileno=None)

Crear un nuevo socket usando la dirección de familia dada, tipo de socket y el numero de protocolo. La dirección de familia debería ser AF_INET (por defecto), AF_INET6, AF_UNIX, AF_CAN, AF_PACKET, o AF_RDS. El tipo de socket debería ser SOCK_STREAM (por defecto), SOCK_DGRAM, SOCK_RAW o quizás una de las otras constantes SOCK_. El numero de protocolo es usualmente cero u omitirse o en el caso donde la familia de dirección es AF_CAN el protocolo debería ser uno de CAN_RAW, CAN_BCM, CAN_ISOTP o CAN_J1939.

Si fileno esta especificado, el valor de family, type, y proto son detectados automáticamente por el descriptor especificado de archivo. La detección automática se puede anular llamado la función con los argumentos explícitos family, type, o proto. Esto solamente afecta como Python representa e.g. el valor de retorno de socket.getpeername() pero no del recurso actual del OS. Diferente a socket.fromfd(), fileno retornara el mismo socket y no un duplicado. Esto puede ayudar a cerrar un socket desconectado usando socket.close().

El socket recién creado es non-inheritable.

Genera un auditing event socket.__new__ con los argumentos self, family, type, protocol.

Distinto en la versión 3.3: Se añadió la familia AF_CAN. Se añadió la familia AF_RDS.

Distinto en la versión 3.4: El protocolo CAN_BCM ha sido agregado.

Distinto en la versión 3.4: Los sockets devueltos ahora no son heredables.

Distinto en la versión 3.7: El protocolo CAN_ISOTP ha sido agregado.

Distinto en la versión 3.7: Cuando las banderas bit SOCK_NONBLOCK or SOCK_CLOEXEC esta aplicados a type se borran, y socket.type no reflejan eso. Todavía se pasan a la llamada socket () del sistema subyacente. Por lo tanto,

sock = socket.socket(
    socket.AF_INET,
    socket.SOCK_STREAM | socket.SOCK_NONBLOCK)

seguirá creando un socket sin bloqueo en los sistemas operativos que admiten SOCK_NONBLOCK, pero sock.type se establecerá en socket.SOCK_STREAM.

Distinto en la versión 3.9: El protocolo CAN_J1939 ha sido agregado.

socket.socketpair([family[, type[, proto]]])

Cree un par de objetos de socket conectados utilizando la familia de direcciones, el tipo de socket y el número de protocolo especificados. La familia de direcciones, el tipo de socket y el número de protocolo son los siguientes para la función socket() anterior. La familia predeterminada es AF_UNIX si se define en la plataforma; de lo contrario, el valor predeterminado es AF_INET.

Los sockets creados recientemente son non-inheritable.

Distinto en la versión 3.2: Los objetos de socket devueltos ahora admiten toda la API de socket, en lugar de un subconjunto.

Distinto en la versión 3.4: Los sockets devueltos ahora no son heredables.

Distinto en la versión 3.5: Se ha agregado compatibilidad con Windows.

socket.create_connection(address[, timeout[, source_address]])

Conecta con un servicio TCP escuchando una address Internet (una tupla de 2 (host, port)), y retorna el objeto socket. Este es una función de nivel superior que socket.connect(): si host es un nombre de host no numérico, intentara resolverlo para ambos AF_INET y AF_INET6, y luego intenta conectarte a todas las direcciones posibles a la vez para lograr una conexión exitosa. Esto facilita la escritura de clientes que sean compatibles con IPv4 e IPv6.

Pasando el parámetro opcional timeout establece el tiempo de espera dentro de la instancia del socket. Si no es proporcionado timeout, la configuración global de tiempo de espera predeterminada retornada por getdefaulttimeout() es usada.

Si se suministra, source_address debe ser una “”(host, puerto)”” de 2 tuplas para que el socket se enlace como su dirección de origen antes de conectarse. Si el host o el puerto son “” o 0 respectivamente, se utilizará el comportamiento predeterminado del sistema operativo.

Distinto en la versión 3.2: source_address ha sido agregado.

socket.create_server(address, *, family=AF_INET, backlog=None, reuse_port=False, dualstack_ipv6=False)

Función de conveniencia que crea un socket TCP enlazado a address (una tupla de 2 (host, puerto)) y devuelve el objeto de socket.

family debe ser AF_INET o AF_INET6. backlog es el tamaño de la cola pasado a socket.listen(); cuando 0 se elige un valor predeterminado razonable. reuse_port dicta si se debe establecer la opción de socket SO_REUSEPORT.

Si dualstack_ipv6 es true y la plataforma lo admite el socket podrá aceptar conexiones IPv4 e IPv6, de lo contrario generará ValueError. Se supone que la mayoría de las plataformas POSIX y Windows admiten esta funcionalidad. Cuando esta funcionalidad está habilitada, la dirección devuelta por socket.getpeername() cuando se produce una conexión IPv4 será una dirección IPv6 representada como una dirección IPv4 asignada6. Si dualstack_ipv6 es false, deshabilitará explícitamente esta funcionalidad en las plataformas que la habilitan de forma predeterminada (por ejemplo, Linux). Este parámetro se puede utilizar junto con has_dualstack_ipv6():

import socket

addr = ("", 8080)  # all interfaces, port 8080
if socket.has_dualstack_ipv6():
    s = socket.create_server(addr, family=socket.AF_INET6, dualstack_ipv6=True)
else:
    s = socket.create_server(addr)

Nota

En plataformas POSIX la opción del socket SO_REUSEADDR está configurado para inmediatamente rehusar los sockets previos que estaban vinculados la misma address y permanecer en estado TIME_WAIT.

Nuevo en la versión 3.8.

socket.has_dualstack_ipv6()

Devuelve True si la plataforma admite la creación de un socket TCP que pueda manejar conexiones IPv4 e IPv6.

Nuevo en la versión 3.8.

socket.fromfd(fd, family, type, proto=0)

Duplica el descriptor de archivo fd (un entero retornado por el método fileno() de un objeto archivo) y crea un objeto socket a partir del resultado. La familia de direcciones, el tipo de socket y el número de protocolo son como para la función socket() anterior. El descriptor de archivo debe hacer referencia a un socket, pero esto no se comprueba — las operaciones posteriores en el objeto pueden fallar si el descriptor de archivo no es válido. Esta función rara vez se necesita, pero se puede usar para obtener o establecer opciones de socket en un socket pasado a un programa como entrada o salida estándar (como un servidor iniciado por el demonio inet de Unix). Se supone que el socket está en modo de bloqueo.

El socket recién creado es non-inheritable.

Distinto en la versión 3.4: Los sockets devueltos ahora no son heredables.

socket.fromshare(data)

Cree una instancia de un socket a partir de los datos obtenidos del método socket.share(). Se supone que el socket está en modo de bloqueo.

Availability: Windows.

Nuevo en la versión 3.3.

socket.SocketType

Este es un tipo de objeto Python que representa el tipo de objeto del socket. Es lo mismo que decir type(socket(…)).

Otras funciones

El modulo socket también ofrece varios servicios de red relacionados:

socket.close(fd)

Cierre un descriptor de archivo de socket. Esto es como os.close(), pero para sockets. En algunas plataformas (la mayoría notable de Windows) os.close() no funciona para descriptores de archivos de socket.

Nuevo en la versión 3.7.

socket.getaddrinfo(host, port, family=0, type=0, proto=0, flags=0)

Traduce el argumento host/port dentro de una secuencia de 5 tuplas que contiene todo los argumentos necesarios para crear un socket conectado a ese servicio. host es un nombre de dominio, una cadena en representación de una dirección IPV4/IPV6 o None. port es una nombre de una cadena de servicio como 'http', un numero de puerto numérico o None. Pasando None como el valor del host y port, pasando NULL a la API C subyacente.

Los argumentos family, type y proto se puede especificar opcionalmente para reducir la lista de direcciones retornadas. Pasando cero como un valor para cada uno de estos argumentos se selecciona la gama completa de resultados. El argumento flags puede ser uno o varios de los argumentos AI_*, y pueden influenciar como los resultados son computados y devueltos. Por ejemplo, AI_NUMERICHOST desactivará la resolución de nombres de dominio y generará un error sí * host * es un nombre de dominio.

La función devuelve una lista de 5 tuplas con la siguiente estructura:

(family, type, proto, canonname, sockaddr)

En estas tuplas, family, type, proto son todos enteros y están destinados a ser pasados por la función socket(). canonname debe ser una cadena que representa el nombre canónico del host si AI_CANONNAME es parte de el argumento flags; de lo contrario canonname estará vacía. sockaddr es un tupla describiendo una dirección de socket, cuyo formato depende del devuelto family (una (address, port) tupla de 2 para AF_INET, una (address, port, flowinfo, scope_id) una tupla de 4 para una AF_INET6), y está destinado a ser pasado a el método socket.connect().

Genera un auditing event socket.getaddrinfo con los argumentos host, port, family, type, protocol.

En el ejemplo siguiente se obtiene información de dirección para una conexión TCP hipotética a example.org en el puerto 80 (los resultados pueden diferir en el sistema si IPv6 no está habilitado):

>>> socket.getaddrinfo("example.org", 80, proto=socket.IPPROTO_TCP)
[(<AddressFamily.AF_INET6: 10>, <SocketType.SOCK_STREAM: 1>,
 6, '', ('2606:2800:220:1:248:1893:25c8:1946', 80, 0, 0)),
 (<AddressFamily.AF_INET: 2>, <SocketType.SOCK_STREAM: 1>,
 6, '', ('93.184.216.34', 80))]

Distinto en la versión 3.2: los parámetros ahora se pueden pasar mediante argumentos de palabra clave.

Distinto en la versión 3.7: para direcciones de multidifusión IPv6, la cadena que representa una dirección no contendrá partes %scope_id.

socket.getfqdn([name])

Return a fully qualified domain name for name. If name is omitted or empty, it is interpreted as the local host. To find the fully qualified name, the hostname returned by gethostbyaddr() is checked, followed by aliases for the host, if available. The first name which includes a period is selected. In case no fully qualified domain name is available and name was provided, it is returned unchanged. If name was empty or equal to '0.0.0.0', the hostname from gethostname() is returned.

socket.gethostbyname(hostname)

Traduce un nombre de host a un formato de dirección IPV4. La dirección IPV4 es retornada como una cadena, como ’100.50.200.5’. Si el nombre de host es una dirección IPV4 en sí, se devuelve sin cambios. Observa gethostbyname_ex() para una interfaz mas completa. gethostbyname() no soporta la resolución de nombres IPV6, y getaddrinfo() debe utilizarse en su lugar para compatibilidad con doble pila IPv4/v6.

Genera un evento auditing socket.gethostbyname con el argumento hostname.

socket.gethostbyname_ex(hostname)

Translate a host name to IPv4 address format, extended interface. Return a triple (hostname, aliaslist, ipaddrlist) where hostname is the host’s primary host name, aliaslist is a (possibly empty) list of alternative host names for the same address, and ipaddrlist is a list of IPv4 addresses for the same interface on the same host (often but not always a single address). gethostbyname_ex() does not support IPv6 name resolution, and getaddrinfo() should be used instead for IPv4/v6 dual stack support.

Genera un evento auditing socket.gethostbyname con el argumento hostname.

socket.gethostname()

Devuelve una cadena que contenga el nombre de host de la máquina donde se está ejecutando actualmente el intérprete de Python.

Genera un auditing event socket.gethostname sin argumentos.

Nota: gethostname() no siempre retorna el nombre de dominio completo, usa getfqdn() para eso.

socket.gethostbyaddr(ip_address)

Retorna un triple (hostname, aliaslist, ipaddrlist) donde hostname es el nombre del host primario respondiendo de la misma ip_address, aliaslist es una (posiblemente vacía) lista de nombres de hosts alternativa, y ipaddrlist es una lista de direcciones IPV4/IPV6 para la misma interfaz y en el mismo host ( lo más probable es que contenga solo una dirección ). Para encontrar el nombre de dominio completo, use la función getfqdn(). gethostbyaddr() admite tanto IPv4 como IPv6.

Generar un auditing event socket.gethostbyaddr con los argumentos ip_address.

socket.getnameinfo(sockaddr, flags)

Traduce una dirección de socket sockaddr dentro de una tupla de 2 (host, port). Dependiendo de la configuraciones de flags, el resultado puede contener un nombre de dominio completo o una representación numérica de la dirección en host. Similar, port puede contener un nombre de puerto de cadena o un numero de puerto numérico.

Para las direcciones IPv6, %scope se anexa a la parte del host si sockaddr contiene scopeid significativo. Generalmente esto sucede para las direcciones de multidifusión.

Para mas información sobre flags pueden consultar getnameinfo(3).

Plantea un auditing event socket.getnameinfo con el argumento sockaddr.

socket.getprotobyname(protocolname)

Traduzca un nombre de protocolo de Internet (por ejemplo, 'icmp') a una constante adecuada para pasar como el tercer argumento (opcional) a la función socket(). Por lo general, esto sólo es necesario para los sockets abiertos en modo «crudo» (SOCK_RAW); para los modos de socket normales, el protocolo correcto se elige automáticamente si se omite el protocolo o cero.

socket.getservbyname(servicename[, protocolname])

Traduce un nombre de servicio de Internet y el nombre del protocolo para un numero de puerto para ese servicio. El nombre del protocolo opcional, si se da, podría ser ’tcp’` o ’udp’, de lo contrario, cualquier protocolo coincidirá.

Genera un auditing event socket.getservbyname con los argumentos servicename, protocolname.

socket.getservbyport(port[, protocolname])

Traduzca un número de puerto de Internet y un nombre de protocolo a un nombre de servicio para ese servicio. El nombre del protocolo opcional, si se da, debe ser 'tcp' o 'udp', de lo contrario cualquier protocolo coincidirá.

Genera un auditing event socket.getservbyport con los argumentos port, protocolname.

socket.ntohl(x)

Convierta enteros positivos de 32 bits de red a orden de bytes de host. En equipos donde el orden de bytes de host es el mismo que el orden de bytes de red, se trata de un no-op; de lo contrario, realiza una operación de intercambio de 4 bytes.

socket.ntohs(x)

Convierta enteros positivos de 16 bits de red a orden de bytes de host. En equipos donde el orden de bytes de host es el mismo que el orden de bytes de red, se trata de un no-op; de lo contrario, realiza una operación de intercambio de 2 bytes.

Obsoleto desde la versión 3.7: En el caso que x no encaje en un entero sin signo de 16 bits, pero encaja en un entero positivo C, esto es silenciosamente truncado en un entero sin signo de 16 bits. Esta característica de truncamiento silenciosa esta obsoleta, y generará una excepción en versiones futuras de Python.

socket.htonl(x)

Convierta enteros positivos de 32 bits del host al orden de bytes de red. En equipos donde el orden de bytes de host es el mismo que el orden de bytes de red, se trata de un no-op; de lo contrario, realiza una operación de intercambio de 4 bytes.

socket.htons(x)

Convierta enteros positivos de 16 bits del host al orden de bytes de red. En equipos donde el orden de bytes de host es el mismo que el orden de bytes de red, se trata de un no-op; de lo contrario, realiza una operación de intercambio de 2 bytes.

Obsoleto desde la versión 3.7: En el caso que x no encaje en un entero sin signo de 16 bits, pero encaja en un entero positivo C, esto es silenciosamente truncado en un entero sin signo de 16 bits. Esta característica de truncamiento silenciosa esta obsoleta, y generará una excepción en versiones futuras de Python.

socket.inet_aton(ip_string)

Convierte una dirección IPV4 desde el formato de cadena de cuatro puntos (por ejemplo, ‘123.45.67.89’) a formato binario empaquetado de 32 bits, como un objeto de bytes de cuatro caracteres de longitud. Esto es usado cuando al convertir un programa que usa la librería estándar C y necesita objetos de tipo struct in_addr, que es el tipo C para el binario empaquetado de 32 bits que devuelve esta función.

Ademas inet_aton`acepta cadena de caracteres con menos de tres puntos, observar la pagina del manual Unix :manpage:`inet(3)() para mas detalles.

Si la cadena de dirección IPv4 es pasada a esta función es invalido, OSError se generará. Tenga en cuenta que exactamente lo que es valido depende de la implementación C de inet_aton().

inet_aton() no admite IPV6, y inet_pton() deberían utilizarse en su lugar para compatibilidad con doble pilas IPV4/v6.

socket.inet_ntoa(packed_ip)

Convierte una dirección IPV4 empaquetada de 32 bits (un bytes-like object cuatro bytes de longitud) a su representación estándar de cadena de cuatro puntos ( por ejemplo ‘123.45.67.89’). Esto es útil cuando convertimos con un programa que usa la librería estándar C y necesita objetos de tipo struct in_addr, que es el tipo C para los datos binarios empaquetados de 32 bits que esta función toma como argumento.

Si la secuencia de byte pasada a esta función no es exactamente 4 bytes de longitud OSError podría generarse inet_ntoa() no soporta IPV6, y inet_ntop() debe utilizarse en su lugar para compatibilidad con doble pila IPv4 / v6.

Distinto en la versión 3.5: Ahora se acepta la grabación bytes-like object.

socket.inet_pton(address_family, ip_string)

Convierte una dirección IP desde su formato de cadena especifico de la familia a un empaquetado, formato binario inet_pton() es útil cuando una librería o protocolo de red llama desde un objeto de tipo struct in_addr (similar a inet_aton()) o struct in6_addr.

Los Valores soportados para address_family son actualmente AF_INET y AF_INET6. Si la cadena de dirección IP ip_string no es válida, OSError se genera. Tenga en cuenta que exactamente lo que es válido depende tanto del valor de address_family como de la implementación subyacente de inet_pton().

Disponibilidad: Unix(Tal vez no todas las plataformas), Windows.

Distinto en la versión 3.4: Se ha añadido compatibilidad con Windows

socket.inet_ntop(address_family, packed_ip)

Convierte una dirección IP empaquetada ( un bytes-like object de algún numero de bytes) a su representación de cadena estándar, específica de la familia (por ejemplo ’7.10.0.5’ o ’5aef:2b::8’). inet_ntop() es usado cuando una librería o protocolo de red retorna un objeto de tipo struct in_addr (similar para inet_ntoa()) o struct in6_addr.

Los valores soportados para address_family actualmente son AF_INET y AF_INET6. Si los objetos de bytes packed_ip no tienen la longitud correcta para la familia de direcciones especificas, ValueError podría generarse. OSError se genera para errores desde la llamada a inet_ntop().

Disponibilidad: Unix(Tal vez no todas las plataformas), Windows.

Distinto en la versión 3.4: Se ha añadido compatibilidad con Windows

Distinto en la versión 3.5: Ahora se acepta la grabación bytes-like object.

socket.CMSG_LEN(length)

Retorna la longitud total, sin relleno de arrastre, de un elemento de datos auxiliares con datos asociados del length. Este valor se puede utilizar a menudo como tamaño de búfer para recvmsg() para recibir un solo valor de datos auxiliares, pero RFC 3542 [https://tools.ietf.org/html/rfc3542.html] requiere aplicaciones portables para usar CMSG_SPACE() y así incluir espacio para el relleno, incluso cuando el elemento será el último en el búfer. Genera OverflowError si length está fuera del rango de valores permitido.

Availability: la mayoría de plataformas Unix, posiblemente otras.

Nuevo en la versión 3.3.

socket.CMSG_SPACE(length)

Retorna el tamaño del buffer necesario por recvmsg() para recibir un elemento de datos auxiliares con datos asociados del length dado, junto con cualquier relleno final. El espacio de buffer necesario para recibir múltiples elementos es la suma de los valores de CMSG_SPACE() para los datos asociados con la longitudes. Genera OverflowError si length está fuera del rango de valores permitido.

Tenga en cuenta que algunos sistemas pueden admitir datos auxiliares sin proporcionar esta función. Tenga en cuenta también que establecer el tamaño del búfer utilizando los resultados de esta función puede no limitar con precisión la cantidad de datos auxiliares que se pueden recibir, ya que los datos adicionales pueden caber en el área de relleno.

Availability: la mayoría de plataformas Unix, posiblemente otras.

Nuevo en la versión 3.3.

socket.getdefaulttimeout()

Retorna el tiempo de espera por defecto en segundos (flotante) para los objetos de un nuevo socket. Un valor de None indicada que los objetos del nuevo socket no tiene un tiempo de espera. Cuando el modulo socket es importado primero, por defecto es None.

socket.setdefaulttimeout(timeout)

Selecciona el tiempo de espera por defecto en segundos (flotante ) para los objetos nuevos del socket. Cuando el modulo socket es importado primero, el valor por defecto es None. Observar settimeout() para posible valores y sus respectivos significados.

socket.sethostname(name)

Establece el nombre de host de la maquina en name. Esto genera un OSError si no tiene suficientes derechos.

Plantea un auditing event socket.sethostname con el argumento name.

Availability: Unix.

Nuevo en la versión 3.3.

socket.if_nameindex()

Devuelve una lista de tuplas de información de interfaz de red (índice int, cadena de nombre). OSError si se produce un error en la llamada del sistema.

Availability: Unix, Windows.

Nuevo en la versión 3.3.

Distinto en la versión 3.8: Se ha agregado compatibilidad con Windows.

Nota

En Windows las interfaces de redes tienen diferentes nombres en diferentes contextos (todos los nombres son ejemplos):

UUID: {FB605B73-AAC2-49A6-9A2F-25416AEA0573}

nombre: ethernet_32770

nombre amigable: vEthernet (nat)

descripción: Hyper-V Virtual Ethernet Adapter

Esta función retorna los nombres del segundo formulario de la lista, en este caso de ejemplo ethernet_32770.

socket.if_nametoindex(if_name)

Devuelve un número de índice de interfaz de red correspondiente a un nombre de interfaz. OSError si no existe ninguna interfaz con el nombre especificado.

Availability: Unix, Windows.

Nuevo en la versión 3.3.

Distinto en la versión 3.8: Se ha agregado compatibilidad con Windows.

Ver también

“”Interface name” es un nombre como se documenta en if_nameindex().

socket.if_indextoname(if_index)

Devuelve un nombre de interfaz de red correspondiente a un número de índice de interfaz. OSError si no existe ninguna interfaz con el índice dado.

Availability: Unix, Windows.

Nuevo en la versión 3.3.

Distinto en la versión 3.8: Se ha agregado compatibilidad con Windows.

Ver también

“”Interface name” es un nombre como se documenta en if_nameindex().

socket.send_fds(sock, buffers, fds[, flags[, address]])

Send the list of file descriptors fds over an AF_UNIX socket sock. The fds parameter is a sequence of file descriptors. Consult sendmsg() for the documentation of these parameters.

Availability: Soporte para Unix sendmsg() con el mecanismo SCM_RIGHTS.

Nuevo en la versión 3.9.

socket.recv_fds(sock, bufsize, maxfds[, flags])

Receive up to maxfds file descriptors from an AF_UNIX socket sock. Return (msg, list(fds), flags, addr). Consult recvmsg() for the documentation of these parameters.

Availability: Soporte para Unix recvmsg() y el mecanismo SCM_RIGHTS.

Nuevo en la versión 3.9.

Nota

Cualquier número entero truncado al final de la lista de descriptores de archivo.

Objetos Socket

Los objetos socket tienen los siguientes métodos. Excepto para makefile(), esto corresponde al sistema de llamadas Unix para sockets.

Distinto en la versión 3.2: El soporte para el protocolo context manager ha sido agregado. Salir del gestor de contexto es equivalente para el llamado close().

socket.accept()

Acepta una conexión. El socket debe estar vinculado a una dirección y estar escuchando las conexiones. El valor de retorno es el par (conn, address) cuando conn es un new objeto socket usado para enviar y recibir información en la conexión, y address es la dirección vinculada al socket en el extremo de la conexión.

El socket recién creado es non-inheritable.

Distinto en la versión 3.4: El socket ahora no es heredable.

Distinto en la versión 3.5: Si se interrumpe la llamada del sistema y el controlador de señal no genera una excepción, el método ahora vuelve a intentar la llamada del sistema en lugar de generar una excepción InterruptedError (consulte PEP 475 [https://www.python.org/dev/peps/pep-0475] para la lógica).

socket.bind(address)

Enlaza el socket a address. El socket no debe estar ya unido. (El formato de address depende de la familia de direcciones, consulte más arriba).

Genera un auditing event socket.getaddrinfo con los argumentos host, port, family, type, protocol.

socket.close()

Marca el socket cerrado. El recurso del sistema subyacente (ej. un descriptor de archivo) también se cierra cuando todos los objetos de archivo de makefile() están cerrados. Una vez que eso suceda, todas las operaciones futuras en el objeto socket fallarán. El extremo remoto no recibirá más datos (después de que se vacíen los datos en cola).

Los sockets se cierran automáticamente cuando se recogen basura, pero se recomienda cerrarlos() explícitamente, o usar una instrucción with alrededor de ellos.

Distinto en la versión 3.6: OSError is now raised if an error occurs when the underlying close() call is made.

Nota

close() libera el recurso asociado a una conexión, pero no necesariamente cierra la conexión inmediatamente. Si desea cerrar la conexión a tiempo, llame a shutdown() antes de close().

socket.connect(address)

Conectar a un socket remoto en address. (El formato de address depende de la familia de direcciones — ver arriba.)

Si una señal interrumpe la conexión, el método espera hasta que se complete la conexión o genere un socket.timeout en el tiempo de espera, si el controlador de señal no genera una excepción y el socket está bloqueando o tiene un tiempo de espera. Para los sockets sin bloqueo, el método genera una excepción InterruptedError si la conexión se interrumpe por una señal (o la excepción provocada por el controlador de señal).

Genera un auditing event socket.connect con los argumentos self, address.

Distinto en la versión 3.5: El método ahora espera hasta que se completa la conexión en lugar de generar una excepción InterruptedError si la conexión se interrumpe por una señal, el controlador de señal no genera una excepción y el socket está bloqueando o tiene un tiempo de espera (consulte el PEP 475 [https://www.python.org/dev/peps/pep-0475] para la razón de ser).

socket.connect_ex(address)

Similar a connect(address)`, pero retorna un indicador de error en lugar de generar una excepción para los errores retornados por la llamada de nivel C connect() (otros problemas, como “host no encontrado”, aún pueden generar excepciones). El indicador de error es 0 si la operación tuvo éxito, caso contrario es el valor de la variable errno. Esto es útil para admitir, por ejemplo, conexiones asincrónicas.

Genera un auditing event socket.connect con los argumentos self, address.

socket.detach()

Coloque el objeto de socket en estado cerrado sin cerrar realmente el descriptor de archivo subyacente. Se devuelve el descriptor de archivo y se puede reutilizar para otros fines.

Nuevo en la versión 3.2.

socket.dup()

Duplica el socket.

El socket recién creado es non-inheritable.

Distinto en la versión 3.4: El socket ahora no es heredable.

socket.fileno()

Retorna un archivo descriptor del socket (un entero pequeño), o -1 si falla. Esto es útil con select.select().

En Windows el pequeño entero retornado por este método no puede ser usado donde un descriptor de un archivo pueda ser usado (como una os.fdopen()). Unix no tiene esta limitación.

socket.get_inheritable()

Obtiene el inheritable flag del descriptor del archivo del socket o el controlador del socket: True si el socket puede ser heredada en procesos secundarios, False si falla.

Nuevo en la versión 3.4.

socket.getpeername()

Retorna la dirección remota a la que esta conectado el socket. Esto es útil para averiguar el número de puerto de un socket IPv4/v6 remoto, por ejemplo. (El formato de la dirección devuelta depende de la familia de direcciones, consulte más arriba). En algunos sistemas, esta función no es compatible.

socket.getsockname()

Retorna la dirección del propio socket. Esto es útil para descubrir el numero de puerto de un socket IPv4/IPv6, por ejemplo. (El formato de la dirección devuelta depende de la familia de direcciones, consulte más arriba).

socket.getsockopt(level, optname[, buflen])

Devuelve el valor de la opción de socket dada (consulte la página de comando man de Unix getsockopt(2)). Las constantes simbólicas necesarias (SO_* etc.) se definen en este módulo. Si buflen está ausente, se asume una opción de entero y la función devuelve su valor entero. Si buflen está presente, especifica la longitud máxima del búfer utilizado para recibir la opción y este búfer se devuelve como un objeto bytes. Depende del autor de la llamada descodificar el contenido del búfer (consulte el módulo integrado opcional struct para obtener una manera de decodificar las estructuras C codificadas como cadenas de bytes).

socket.getblocking()

Devuelve True si el socket está en modo de bloqueo, False si está en sin bloqueo.

Esto es equivalente a comprobar socket.gettimeout() == 0.

Nuevo en la versión 3.7.

socket.gettimeout()

Retorna el tiempo de espera en segundos (flotante) asociado con las operaciones del socket, o None si el tiempo de espera no es seleccionado. Esto refleja la ultima llamada al setblocking() o settimeout().

socket.ioctl(control, option)

plataforma

Windows

El método ioctl() es una interfaz limitada para el sistema de interfaces WSAIoctl. Por favor refiérase a Win32 documentation [https://msdn.microsoft.com/en-us/library/ms741621%28VS.85%29.aspx] para mas información.

En otras plataformas, las funciones genéricas fcntl.fcntl() y fcntl.ioctl() podrían ser usadas; ellas aceptan un objeto socket como su primer argumento.

Actualmente solo el siguiente control de códigos está soportados: SIO_RCVALL, SIO_KEEPALIVE_VALS, y SIO_LOOPBACK_FAST_PATH.

Distinto en la versión 3.6: SIO_LOOPBACK_FAST_PATH ha sido agregado.

socket.listen([backlog])

Habilita un servidor para aceptar conexiones. Si backlog es especifico, debe ser al menos 0 (si es menor, se establece en 0); especifica el número de conexiones no aceptadas que permitirá el sistema antes de rechazar nuevas conexiones. Si no se especifica, se elige un valor razonable predeterminado.

Distinto en la versión 3.5: El parámetro backlog ahora es opcional.

socket.makefile(mode='r', buffering=None, *, encoding=None, errors=None, newline=None)

Retorna un file object asociado con el socket. El tipo exacto retornado depende de los argumentos dados a makefile(). Estos argumentos se interpretan de la misma forma que la función open(), excepto que los únicos valores de mode admitidos son ’r’ (default), ’w’ and ’b’.

El socket debe estar en modo de bloqueo; puede tener un tiempo de espera, pero el búfer interno del objeto de archivo puede terminar en un estado incoherente si se produce un tiempo de espera.

Cerrar el objeto de archivo devuelto por makefile() no cerrará el socket original a menos que se hayan cerrado todos los demás objetos de archivo y socket.close() se haya llamado al objeto socket.

Nota

En Windows, el objeto similar a un archivo creado por makefile() no se puede utilizar cuando se espera un objeto de archivo con un descriptor de archivo, como los argumentos de secuencia de subprocess.Popen().

socket.recv(bufsize[, flags])

Recibir datos del socket. El valor devuelto es un objeto bytes que representa los datos recibidos. bufsize especifica la cantidad máxima de datos que se recibirán a la vez. Consulte la página del manual de Unix recv(2) para conocer el significado del argumento opcional flags; por defecto es cero.

Nota

Para una mejor coincidencia con las realidades de hardware y red, el valor de bufsize debe ser una potencia relativamente pequeña de 2, por ejemplo, 4096.

Distinto en la versión 3.5: Si se interrumpe la llamada del sistema y el controlador de señal no genera una excepción, el método ahora vuelve a intentar la llamada del sistema en lugar de generar una excepción InterruptedError (consulte PEP 475 [https://www.python.org/dev/peps/pep-0475] para la lógica).

socket.recvfrom(bufsize[, flags])

Recibe datos desde el socket. El valor de retorno es un par (bytes, address) donde bytes es un objeto de bytes que representa los datos recibidos y address es la dirección de el socket enviando los datos. Observar la pagina del manual Unix recv(2) para el significado del argumento opcional flags; por defecto es cero. (El formato de address depende de la familia de direcciones, consulte más arriba).

Distinto en la versión 3.5: Si se interrumpe la llamada del sistema y el controlador de señal no genera una excepción, el método ahora vuelve a intentar la llamada del sistema en lugar de generar una excepción InterruptedError (consulte PEP 475 [https://www.python.org/dev/peps/pep-0475] para la lógica).

Distinto en la versión 3.7: Para direcciones IPv6 de multidifusión, el primer elemento de address ya no contiene la parte %scope_id. Para obtener la dirección IPV6 completa, use getnameinfo().

socket.recvmsg(bufsize[, ancbufsize[, flags]])

Reciba datos normales (hasta bufsize bytes) y datos auxiliares del socket. El argumento ancbufsize establece el tamaño en bytes del búfer interno utilizado para recibir los datos auxiliares; el valor predeterminado es 0, lo que significa que no se recibirán datos auxiliares. Los tamaños de búfer adecuados para los datos auxiliares se pueden calcular mediante CMSG_SPACE() o CMSG_LEN(), y los elementos que no caben en el búfer pueden truncarse o descartarse. El valor predeterminado del argumento flags es 0 y tiene el mismo significado que para recv().

El valor de retorno es una tupla de 4: (data, ancdata, msg_flags, address). El valor data es un objeto bytes que contiene los datos no auxiliares recibidos. El valor ancdata es una lista de cero o mas tuplas (cmsg_level, cmsg_type, cmsg_data) representado los datos auxiliares (control de mensajes) recibidos: cmsg_level y cmsg_type son enteros especificando el nivel de protocolo y tipo específico de protocolo respectivamente, y cmsg_data es un objeto bytes sosteniendo los datos asociados. El valor msg_flags es el OR bit a bit de varios indicadores que indican condiciones en el mensaje recibido; consulte la documentación de su sistema para obtener más detalles. Si la toma de recepción no está conectada, address es la dirección de el socket enviado, si está disponible; de lo contrario, su valor no se especifica.

En algunos sistemas, sendmsg() y recvmsg() se puede utilizar para pasar descriptores de archivos entre procesos a través de un socket AF_UNIX Cuando se utiliza esta función (a menudo se limita a sockets SOCK_STREAM), recvmsg`devolverá, en sus datos auxiliares, elementos del formulario ``(socket.SOL_SOCKET, socket.SCM_RIGHTS, fds)`(), donde fds es un objeto bytes representado el nuevo descriptor de archivos como una matriz binaria del tipo C nativa :int. Si recvmsg() genera un excepción después del retorno de la llamada del sistema, primero intentará cerrar cualquier descriptor de archivo recibido a través de este mecanismo.

Algunos sistemas no indican la longitud truncada de los elementos de datos auxiliares que solo se han recibido parcialmente. Si un elemento parece extenderse más allá del final del búfer, recvmsg() emitirá un RuntimeWarning, y devolverá la parte de él que está dentro del búfer siempre que no se haya truncado antes del inicio de sus datos asociados.

En sistemas donde soporta el mecanismo SCM_RIGHTS, la siguiente función recibirá un descriptor de archivos maxfds, devolviendo el mensaje de datos y un lista que contiene los descriptores (mientras se ignoran las condiciones inesperadas, como la recepción de mensajes de control no relacionados). Ver también sendmsg().

import socket, array

def recv_fds(sock, msglen, maxfds):
    fds = array.array("i")   # Array of ints
    msg, ancdata, flags, addr = sock.recvmsg(msglen, socket.CMSG_LEN(maxfds * fds.itemsize))
    for cmsg_level, cmsg_type, cmsg_data in ancdata:
        if cmsg_level == socket.SOL_SOCKET and cmsg_type == socket.SCM_RIGHTS:
            # Append data, ignoring any truncated integers at the end.
            fds.frombytes(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)])
    return msg, list(fds)

Availability: la mayoría de plataformas Unix, posiblemente otras.

Nuevo en la versión 3.3.

Distinto en la versión 3.5: Si se interrumpe la llamada del sistema y el controlador de señal no genera una excepción, el método ahora vuelve a intentar la llamada del sistema en lugar de generar una excepción InterruptedError (consulte PEP 475 [https://www.python.org/dev/peps/pep-0475] para la lógica).

socket.recvmsg_into(buffers[, ancbufsize[, flags]])

Recibir datos normales y datos auxiliares desde el socket, comportándose como recvmsg() lo haría, pero dispersar los datos no auxiliares en una serie de buffers en lugar de devolver un nuevo objeto bytes. El argumento buffers debe ser un iterable de objetos que exportan buffers de escritura (por ejemplo, objetos bytearray); estos se llenarán con fragmentos sucesivos de los datos no auxiliares hasta que se hayan escrito todos o no haya más buffers. El sistema operativo puede establecer un límite (sysconf() valor SC_IOV_MAX) en el número de buffers que se pueden utilizar. Los argumentos ancbufsize y flags tienen el mismo significado que para recvmsg().

El valor de retorno es tupla de 4: (nbytes, ancdata, msg_flags, address), donde nbytes es el numero total de bytes de datos no auxiliares escrito dentro de los bufetes, y ancdata, msg_flags y address son lo mismo que para recvmsg().

Ejemplo:

>>> import socket
>>> s1, s2 = socket.socketpair()
>>> b1 = bytearray(b'----')
>>> b2 = bytearray(b'0123456789')
>>> b3 = bytearray(b'--------------')
>>> s1.send(b'Mary had a little lamb')
22
>>> s2.recvmsg_into([b1, memoryview(b2)[2:9], b3])
(22, [], 0, None)
>>> [b1, b2, b3]
[bytearray(b'Mary'), bytearray(b'01 had a 9'), bytearray(b'little lamb---')]

Availability: la mayoría de plataformas Unix, posiblemente otras.

Nuevo en la versión 3.3.

socket.recvfrom_into(buffer[, nbytes[, flags]])

Reciba datos del socket, escribiéndolo en buffer en lugar de crear una nueva cadena de bytes. El valor devuelto es un par (nbytes, address) donde nbytes es el número de bytes recibidos y address es la dirección del socket que envía los datos. Consulte la página del manual de Unix recv(2) para conocer el significado del argumento opcional flags; por defecto es cero. (El formato de address depende de la familia de direcciones — ver arriba.)

socket.recv_into(buffer[, nbytes[, flags]])

Recibe hasta nbytes bytes desde el socket, almacenado los datos en un búfer en lugar de crear una nueva cadena de bytes. Si nbytes no esta especificado (o 0), recibir hasta el tamaño disponible en el búfer dado. Devuelve el número de bytes recibidos. Ver la página del manual de Unix recv(2) para el significado del argumento opcional flags; por defecto es cero.

socket.send(bytes[, flags])

Enviar datos al socket. El socket debe estar conectado a un socket remoto. El argumento opcional flags tiene el mismo significado que para recv() arriba. Devuelve el número de bytes enviados. Las aplicaciones son responsables de comprobar que se han enviado todos los datos; si sólo se transmitieron algunos de los datos, la aplicación debe intentar la entrega de los datos restantes. Para obtener más información sobre este tema, consulte HOW TO - Programación con sockets.

Distinto en la versión 3.5: Si se interrumpe la llamada del sistema y el controlador de señal no genera una excepción, el método ahora vuelve a intentar la llamada del sistema en lugar de generar una excepción InterruptedError (consulte PEP 475 [https://www.python.org/dev/peps/pep-0475] para la lógica).

socket.sendall(bytes[, flags])

Enviar datos al socket. El socket debe estar conectado a un socket remoto. El argumento opcional flags tiene el mismo significado que para recv() arriba. A diferencia de send(), este método continúa enviando datos desde bytes hasta que se han enviado todos los datos o se produce un error. Ninguno se devuelve en caso de éxito. Por error, se genera una excepción y no hay forma de determinar cuántos datos, si los hay, se enviaron correctamente.

Distinto en la versión 3.5: El tiempo de espera del socket no se restablece más cada vez que los datos se envían correctamente. El tiempo de espera del socket es ahora la duración total máxima para enviar todos los datos.

Distinto en la versión 3.5: Si se interrumpe la llamada del sistema y el controlador de señal no genera una excepción, el método ahora vuelve a intentar la llamada del sistema en lugar de generar una excepción InterruptedError (consulte PEP 475 [https://www.python.org/dev/peps/pep-0475] para la lógica).

socket.sendto(bytes, address)

socket.sendto(bytes, flags, address)

Enviar datos al socket. El socket no debe estar conectado a un socket remoto, ya que el socket de destino se especifica mediante address. El argumento opcional flags tiene el mismo significado que para recv() arriba. Devolver el número de bytes enviados. (El formato de address depende de la familia de direcciones — ver arriba.)

Genera un auditing event socket.sendto con los argumentos self, address.

Distinto en la versión 3.5: Si se interrumpe la llamada del sistema y el controlador de señal no genera una excepción, el método ahora vuelve a intentar la llamada del sistema en lugar de generar una excepción InterruptedError (consulte PEP 475 [https://www.python.org/dev/peps/pep-0475] para la lógica).

socket.sendmsg(buffers[, ancdata[, flags[, address]]])

Enviar datos normales y auxiliares al socket, recopilar los datos no auxiliares de una serie de buffers y concatenando en un único mensaje. El argumento buffers especifica los datos no auxiliares como un iterable de bytes-como objetos (por ejemplo: objetos bytes); el sistema operativo puede establecer un límite (os.sysconf() valor SC_IOV_MAX) en el número de buffers que se pueden utilizar. El argumento ancdata especifica los datos auxiliares (mensajes de control) como un iterable de cero o más tuplas (cmsg_level, cmsg_type, cmsg_data), donde cmsg_level y cmsg_type son enteros que especifican el nivel de protocolo y el tipo específico del protocolo respectivamente, y cmsg_data es un objeto similar a bytes que contiene los datos asociados. Tenga en cuenta que algunos sistemas (en particular, sistemas sin CMSG_SPACE()) pueden admitir el envío de solo un mensaje de control por llamada. El valor predeterminado del argumento flags es 0 y tiene el mismo significado que para send(). Si se proporciona address y no None, establece una dirección de destino para el mensaje. El valor devuelto es el número de bytes de datos no auxiliares enviados.

La siguiente función envía la lista de descriptores de archivos fds sobre un socket AF_UNIX, estos sistemas pueden soportar la mecánica SCM_RIGHTS. Observar también recvmsg().

import socket, array

def send_fds(sock, msg, fds):
    return sock.sendmsg([msg], [(socket.SOL_SOCKET, socket.SCM_RIGHTS, array.array("i", fds))])

Availability: la mayoría de plataformas Unix, posiblemente otras.

Genera un auditing event socket.sendmsg con los argumentos self, address.

Nuevo en la versión 3.3.

Distinto en la versión 3.5: Si se interrumpe la llamada del sistema y el controlador de señal no genera una excepción, el método ahora vuelve a intentar la llamada del sistema en lugar de generar una excepción InterruptedError (consulte PEP 475 [https://www.python.org/dev/peps/pep-0475] para la lógica).

socket.sendmsg_afalg([msg, ]*, op[, iv[, assoclen[, flags]]])

Versión especializada de sendmsg() para el socket AF_ALG. Modo de ajuste, IV, longitud de datos asociados a AEAD y banderas para el socket AF_ALG.

Availability: Linux >= 2.6.38.

Nuevo en la versión 3.6.

socket.sendfile(file, offset=0, count=None)

Enviar un archivo hasta que se alcance EOF mediante el uso de alto rendimiento os.sendfile y devolver el número total de bytes que se enviaron. file debe ser un objeto de archivo normal abierto en modo binario. Si os.sendfile no está disponible (por ejemplo, Windows) o file no es un archivo normal send() se utilizará en su lugar. offset indica desde dónde empezar a leer el archivo. Si se especifica, count es el número total de bytes para transmitir en lugar de enviar el archivo hasta que se alcance EOF. La posición del archivo se actualiza a la vuelta o también en caso de error en cuyo caso file.tell() se puede utilizar para averiguar el número de bytes que se enviaron. El socket debe ser de tipo SOCK_STREAM No se admiten sockets sin bloqueo.

Nuevo en la versión 3.5.

socket.set_inheritable(inheritable)

Selecciona el inheritable flag descriptor del archivo del socket o el controlador del socket.

Nuevo en la versión 3.4.

socket.setblocking(flag)

Establecer el modo de bloqueo o no bloqueo del socket: si flag es false, el socket se establece en modo sin bloqueo, de lo contrario en modo de bloqueo.

El método es una abreviatura para ciertas llamadas settimeout():

sock.setblocking(True) es equivalente a sock.settimeout(None)

sock.setblocking(False) es equivalente a sock.settimeout(0.0)

Distinto en la versión 3.7: El método ya no aplica la bandera SOCK_NONBLOCK en socket.type.

socket.settimeout(value)

Establece un tiempo de espera para bloquear las operaciones de socket. El argumento value puede ser un número de punto flotante no negativo que exprese segundos, o None. Si se da un valor distinto de cero, las operaciones subsiguientes de socket generarán una excepción timeout si el período de tiempo de espera value ha transcurrido antes de que se complete la operación. Si se da cero, el socket se pone en modo sin bloqueo. Si se da None, el enchufe se pone en modo de bloqueo.

Para obtener más información, consulte las notas notas sobre los tiempos de espera del socket.

Distinto en la versión 3.7: El método ya no cambia la bandera SOCK_NONBLOCK en socket.type.

socket.setsockopt(level, optname, value: int)

socket.setsockopt(level, optname, value: buffer)

socket.setsockopt(level, optname, None, optlen: int)

Establece el valor de la opción de socket dada (consulte la página de manual de Unix setsockopt(2)). Las constantes simbólicas necesarias se definen en el modulo socket (SO_* etc.). El valor puede ser un entero, None o un bytes-like object representan un buffer. En el último caso, depende de la persona que llama asegurarse de que la cadena de bytes contenga los bits adecuados (consulte el módulo integrado opcional struct para una forma de codificar estructuras C como cadenas de bytes). Cuando value se establece en None, el argumento optlen es requerido. Esto es equivalente a llamar a una función C setsockopt() con optval=NULL y optlen=optlen.

Distinto en la versión 3.5: Ahora se acepta la grabación bytes-like object.

Distinto en la versión 3.6: setsockopt(level, optname, None, optlen: int) form added.

socket.shutdown(how)

Apague una o ambas mitades de la conexión. Si how es SHUT_RD, más recibe no se permiten. Si how es SHUT_WR, mas recibe no se permiten. Si how es SHUT_RDWR, más recibe no se permiten.

socket.share(process_id)

Duplica un socket y lo prepara para compartirlo con el proceso de destino. El proceso de destino debe estar provisto de process_id. el objeto de bytes resultante luego se puede pasar al proceso de destino usando alguna forma de comunicación entre procesos y el socket se puede recrear allí usando fromshare(). Una vez que se ha llamado a este método, es seguro cerrar el socket ya que el sistema operativo ya lo ha duplicado para el proceso de destino.

Availability: Windows.

Nuevo en la versión 3.3.

Tenga en cuenta que no hay métodos read() o write(); use recv() y send() sin el argumento flags en su lugar.

Los objetos de socket también tienen estos atributos (de solo lectura) que corresponden a los valores dados al constructor socket.

socket.family

La familia Socket.

socket.type

El tipo de socket.

socket.proto

The socket protocol.

Notas sobre los tiempos de espera del socket

Un objeto de socket puede estar en uno de los tres modos: bloqueo, no bloqueo o tiempo de espera. Los sockets se crean de forma predeterminada siempre en modo de bloqueo, pero esto se puede cambiar llamando a setdefaulttimeout().

En el modo bloqueo, las operaciones se bloquean hasta que se completan o el sistema devuelve un error (como tiempo de espera de conexión agotado).

En el modo sin bloqueo, las operaciones fallan (con un error que, por desgracia, depende del sistema) si no se pueden completar inmediatamente: las funciones de select se pueden utilizar para saber cuándo y si un socket está disponible para leer o escribir.

En timeout mode, las operaciones fallan si no se puede completan el tiempo de espera especifico para el socket ( ellos levanta una excepción timeout) o si el sistema devuelve un error.

Nota

En el nivel del sistema operativo, los sockets en el timeout mode se establecen internamente en modo sin bloqueo. Además, los modos de bloqueo y tiempo de espera se comparten entre descriptores de archivo y objetos de socket que hacen referencia al mismo punto de conexión de red. Este detalle de implementación puede tener consecuencias visibles si, por ejemplo, decide utilizar el fileno() de un socket.

Tiempos de espera y el método connect

La operación connect() también está sujeta a la configuración de tiempo de espera, y en general se recomienda llamar a settimeout() antes de llamar a connect() o pasar un parámetro de tiempo de espera a create_connection(). Sin embargo, la pila de red del sistema también puede devolver un error de tiempo de espera de conexión propio independientemente de cualquier configuración de tiempo de espera del socket de Python.

Tiempos de espera y el método accept

Si getdefaulttimeout() no es una None, los sockets devuelto por el método accept() heredan ese tiempo de espera. De lo contrario, el comportamiento depende de la configuración de la toma de escucha:

si los sockets están escuchando en blocking mode o en el timeout mode, el socket devuelve el accept() en un blocking mode;

si los sockets están escuchando en non-blocking mode, ya sea el socket devuelto por accept() es un modo de bloqueo o no bloque depende del sistema operativo. Si desea garantizar un comportamiento multiplataforma, se recomienda que se anule manualmente esta configuración.

Ejemplo

Aquí están cuatro programas mínimos usando el protocolo TCP/IP: un servidor que hace eco de todos los datos que reciban de vuelta ( Servicio a un solo cliente), y un cliente usando esto. Recuerde que un servidor debe llevar a cabo la secuencia socket(), bind(), listen(), accept() (posiblemente repitiendo la accept() para un servicio mas que un cliente), mientras un cliente solamente necesita la secuencia socket(), connect(). También recuerde que el servidor no sendall()/recv() en el socket esta escuchando pero en el nuevo socket devuelto por accept().

Los dos primeros ejemplos solo admiten IPv4.

# Echo server program
import socket

HOST = ''                 # Symbolic name meaning all available interfaces
PORT = 50007              # Arbitrary non-privileged port
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
    s.bind((HOST, PORT))
    s.listen(1)
    conn, addr = s.accept()
    with conn:
        print('Connected by', addr)
        while True:
            data = conn.recv(1024)
            if not data: break
            conn.sendall(data)

# Echo client program
import socket

HOST = 'daring.cwi.nl'    # The remote host
PORT = 50007              # The same port as used by the server
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
    s.connect((HOST, PORT))
    s.sendall(b'Hello, world')
    data = s.recv(1024)
print('Received', repr(data))

Los dos ejemplos siguientes son idénticos a los dos anteriores, pero admiten IPv4 e IPv6. El lado del servidor escuchará la primera familia de direcciones disponible (debe escuchar ambas en su lugar). En la mayoría de los sistemas listos para IPv6, IPv6 tendrá prioridad y es posible que el servidor no acepte tráfico IPv4. El lado del cliente intentará conectarse a todas las direcciones devueltas como resultado de la resolución de nombres y enviará el tráfico al primero conectado correctamente.

# Echo server program
import socket
import sys

HOST = None               # Symbolic name meaning all available interfaces
PORT = 50007              # Arbitrary non-privileged port
s = None
for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC,
                              socket.SOCK_STREAM, 0, socket.AI_PASSIVE):
    af, socktype, proto, canonname, sa = res
    try:
        s = socket.socket(af, socktype, proto)
    except OSError as msg:
        s = None
        continue
    try:
        s.bind(sa)
        s.listen(1)
    except OSError as msg:
        s.close()
        s = None
        continue
    break
if s is None:
    print('could not open socket')
    sys.exit(1)
conn, addr = s.accept()
with conn:
    print('Connected by', addr)
    while True:
        data = conn.recv(1024)
        if not data: break
        conn.send(data)

# Echo client program
import socket
import sys

HOST = 'daring.cwi.nl'    # The remote host
PORT = 50007              # The same port as used by the server
s = None
for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM):
    af, socktype, proto, canonname, sa = res
    try:
        s = socket.socket(af, socktype, proto)
    except OSError as msg:
        s = None
        continue
    try:
        s.connect(sa)
    except OSError as msg:
        s.close()
        s = None
        continue
    break
if s is None:
    print('could not open socket')
    sys.exit(1)
with s:
    s.sendall(b'Hello, world')
    data = s.recv(1024)
print('Received', repr(data))

El siguiente ejemplo muestra cómo escribir un rastreador de red muy simple con sockets sin procesar en Windows. El ejemplo requiere privilegios de administrador para modificar la interfaz:

import socket

# the public network interface
HOST = socket.gethostbyname(socket.gethostname())

# create a raw socket and bind it to the public interface
s = socket.socket(socket.AF_INET, socket.SOCK_RAW, socket.IPPROTO_IP)
s.bind((HOST, 0))

# Include IP headers
s.setsockopt(socket.IPPROTO_IP, socket.IP_HDRINCL, 1)

# receive all packages
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON)

# receive a package
print(s.recvfrom(65565))

# disabled promiscuous mode
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF)

En el ejemplo siguiente se muestra cómo utilizar la interfaz de socket para comunicarse con una red CAN mediante el protocolo de socket sin procesar. Para utilizar CAN con el protocolo de gestor de difusión en su lugar, abra un socket con:

socket.socket(socket.AF_CAN, socket.SOCK_DGRAM, socket.CAN_BCM)

Después de enlazar (CAN_RAW) o conectar (CAN_BCM) el socket, puede usar las operaciones socket.send() y socket.recv() (y sus contrapartes) en el objeto de socket como de costumbre.

Este último ejemplo puede requerir privilegios especiales:

import socket
import struct

# CAN frame packing/unpacking (see 'struct can_frame' in <linux/can.h>)

can_frame_fmt = "=IB3x8s"
can_frame_size = struct.calcsize(can_frame_fmt)

def build_can_frame(can_id, data):
    can_dlc = len(data)
    data = data.ljust(8, b'\x00')
    return struct.pack(can_frame_fmt, can_id, can_dlc, data)

def dissect_can_frame(frame):
    can_id, can_dlc, data = struct.unpack(can_frame_fmt, frame)
    return (can_id, can_dlc, data[:can_dlc])

# create a raw socket and bind it to the 'vcan0' interface
s = socket.socket(socket.AF_CAN, socket.SOCK_RAW, socket.CAN_RAW)
s.bind(('vcan0',))

while True:
    cf, addr = s.recvfrom(can_frame_size)

    print('Received: can_id=%x, can_dlc=%x, data=%s' % dissect_can_frame(cf))

    try:
        s.send(cf)
    except OSError:
        print('Error sending CAN frame')

    try:
        s.send(build_can_frame(0x01, b'\x01\x02\x03'))
    except OSError:
        print('Error sending CAN frame')

Ejecutar un ejemplo varias veces con un retraso demasiado pequeño entre ejecuciones, podría dar lugar a este error:

OSError: [Errno 98] Address already in use

Esto se debe a que la ejecución anterior ha dejado el socket en un estado TIME_WAIT y no se puede reutilizar inmediatamente.

Este es una bandera socket para establecer, en orden para prevenir esto, socket.SO_REUSEADDR:

s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
s.bind((HOST, PORT))

el indicador SO_REUSEADDR indica al kernel que reutilice un socket local en estado TIME_WAIT, sin esperar a que expire su tiempo de espera natural.

Ver también

Para obtener una introducción a la programación de sockets (en C), consulte los siguientes documentos:

An Introductory 4.3BSD Interprocess Communication Tutorial, por Stuart Sechrest

An Advanced 4.3BSD Interprocess Communication Tutorial, por Samuel J. Leffler et al,

ambos en el manual del programador de Unix, documentos suplementarios 1 ( secciones PS1:7 y PS1:8). La plataforma especifica material de referencia para las diversas llamadas al sistema también son una valiosa fuente de información en los detalles de la semántica del socket. Para Unix, referencia a las paginas del manual, para Windows, observa la especificación WinSock (o WinSock 2). Para APIS listas IPV6, los lectores pueden querer referirse al titulado Extensiones básicas de interfaz de socket para IPv6 RFC 3493 [https://tools.ietf.org/html/rfc3493.html] .

ssl —Empaquetador o wrapper TLS/SSL para objetos de tipo socket

Código fuente:Lib/ssl.py [https://github.com/python/cpython/tree/3.9/Lib/ssl.py]

This module provides access to Transport Layer Security (often known as «Secure Sockets Layer») encryption and peer authentication facilities for network sockets, both client-side and server-side. This module uses the OpenSSL library. It is available on all modern Unix systems, Windows, macOS, and probably additional platforms, as long as OpenSSL is installed on that platform.

Nota

Some behavior may be platform dependent, since calls are made to the operating system socket APIs. The installed version of OpenSSL may also cause variations in behavior. For example, TLSv1.1 and TLSv1.2 come with openssl version 1.0.1.

Advertencia

No use este módulo sin leer Consideraciones de seguridad. Hacerlo puede generar una falsa sensación de seguridad, ya que la configuración predeterminada del módulo ssl no es necesariamente la adecuada para su aplicación.

Esta sección documenta los objetos y funciones en el módulo ssl; para más información general sobre TLS,SSL, y certificados, se recomienda que el lector acuda a la sección «Ver también» al final de la página.

Este módulo proporciona una clase, ssl.SSLSocket, que se deriva del tipo socket.socket, y proporciona una envoltura similar a un socket que también encripta y desencripta los datos que pasan por el socket con SSL . Admite métodos adicionales como getpeercert(), que recupera el certificado del otro lado de la conexión, y cipher(), que recupera el cifrado que se utiliza para la conexión segura.

Para aplicaciones más sofisticadas, la clase ssl.SSLContext ayuda a administrar la configuración y los certificados, que luego pueden ser heredados por sockets SSL creados a través del método SSLContext.wrap_socket().

Distinto en la versión 3.5.3: Actualizado para admitir la vinculación con OpenSSL 1.1.0

Distinto en la versión 3.6: OpenSSL 0.9.8, 1.0.0 y 1.0.1 son obsoletos y no son compatibles. En el futuro, el módulo ssl requerirá al menos OpenSSL 1.0.2 o 1.1.0.

Funciones, constantes y excepciones

Creación de sockets

Desde Python 3.2 y 2.7.9, se recomienda utilizar SSLContext.wrap_socket() de una instancia de SSLContext para envolver sockets como objetos SSLSocket. La función utilitaria create_default_context() retorna un nuevo contexto con ajustes por defecto seguros. La vieja función wrap_socket() es obsoleta debido a que es ineficiente y que no tiene soporte para la indicación de nombre de servidor (SNI) ni hostname matching.

Ejemplo de socket cliente con contexto por defecto y doble pila IPv4/IPv6:

import socket
import ssl

hostname = 'www.python.org'
context = ssl.create_default_context()

with socket.create_connection((hostname, 443)) as sock:
    with context.wrap_socket(sock, server_hostname=hostname) as ssock:
        print(ssock.version())

Ejemplo de socket cliente con contexto personalizado y IPv4:

hostname = 'www.python.org'
# PROTOCOL_TLS_CLIENT requires valid cert chain and hostname
context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
context.load_verify_locations('path/to/cabundle.pem')

with socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0) as sock:
    with context.wrap_socket(sock, server_hostname=hostname) as ssock:
        print(ssock.version())

Ejemplo de socket servidor escuchando en localhost IPv4:

context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
context.load_cert_chain('/path/to/certchain.pem', '/path/to/private.key')

with socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0) as sock:
    sock.bind(('127.0.0.1', 8443))
    sock.listen(5)
    with context.wrap_socket(sock, server_side=True) as ssock:
        conn, addr = ssock.accept()
        ...

Creación de contexto

Una función conveniente ayuda a crear objetos SSLContext para propósitos comunes.

ssl.create_default_context(purpose=Purpose.SERVER_AUTH, cafile=None, capath=None, cadata=None)

Retorna un nuevo objeto SSLContext con ajustes por defecto para el purpose dado. Los ajustes son elegidos por el módulo ssl y generalmente representan un nivel de seguridad mas alto que invocando directamente el constructor de SSLContext.

cafile, capath, cadata representan certificados CA opcionales para confiar en la verificación de certificados, como en SSLContext.load_verify_locations(). Si los tres son None al mismo tiempo, esta función puede optar por confiar en su lugar en los certificados CA por defecto del sistema.

Los ajustes son: PROTOCOL_TLS, OP_NO_SSLv2 y OP_NO_SSLv3 con suites de cifrado de alto nivel sin RC4 y sin suites de cifrado sin autentificar. Pasar SERVER_AUTH como purpose establece verify_mode a CERT_REQUIRED y carga los certificados CA (si al menos uno de cafile, capath o cadata es dado) o usa SSLContext.load_default_certs() para cargar los certificados CA por defecto.

Cuando keylog_filename es soportado y la variable de entorno SSLKEYLOGFILE está establecida, create_default_context() activa el registro de claves.

Nota

El protocolo, las opciones, el cifrado y otros ajustes pueden cambiar a valores mas restrictivos en cualquier momento sin previa obsolescencia. Los valores representan un equilibrio justo entre compatibilidad y seguridad.

Si su aplicación necesita ajustes específicos, debe crear un SSLContext y aplicar los ajustes usted mismo.

Nota

Si encuentra que cuando ciertos clientes o servidores antiguos intentan conectarse con un SSLContext creado con esta función obtienen un error indicando Protocol or cipher suite mismatch, puede ser que estos sólo soportan SSL3.0 el cual esta función excluye utilizando OP_NO_SSLv3. SSL3.0 está ampliamente considerado como completamente roto [https://en.wikipedia.org/wiki/POODLE]. Si todavía desea seguir utilizando esta función pero permitir conexiones SSL 3.0, puede volver a activarlas mediante:

ctx = ssl.create_default_context(Purpose.CLIENT_AUTH)
ctx.options &= ~ssl.OP_NO_SSLv3

Nuevo en la versión 3.4.

Distinto en la versión 3.4.4: RC4 ha sido abandonado de la cadena de cifrado por defecto.

Distinto en la versión 3.6: ChaCha20/Poly1305 ha sido agregado a la cadena de caracteres de cifrado por defecto.

3DES ha sido abandonado de la cadena de caracteres de cifrado por defecto.

Distinto en la versión 3.8: Soporte del registro de claves en SSLKEYLOGFILE ha sido agregado.

Excepciones

exception ssl.SSLError

Se lanza para señalar un error de la implementación de SSL subyacente (actualmente proporcionada por la biblioteca OpenSSL). Esto indica algún problema en la capa de cifrado y autenticación de alto nivel que se superpone a la conexión de red subyacente. Este error es un subtipo de OSError. El código de error y el mensaje de las instancias de SSLError son proporcionados por la biblioteca OpenSSL.

Distinto en la versión 3.3: SSLError era un subtipo de socket.error.

library

Una cadena de caracteres mnemotécnica que designa el submódulo de OpenSSL en el que se ha producido el error, como SSL, PEM o X509. El rango de valores posibles depende de la versión de OpenSSL.

Nuevo en la versión 3.3.

reason

Una cadena de caracteres mnemotécnica que designa la razón por la que se produjo el error, por ejemplo CERTIFICATE_VERIFY_FAILED. El rango de valores posibles depende de la versión de OpenSSL.

Nuevo en la versión 3.3.

exception ssl.SSLZeroReturnError

Una subclase de SSLError lanzada cuando se intenta leer o escribir y la conexión SSL ha sido cerrada limpiamente. Tenga en cuenta que esto no significa que el transporte subyacente (lectura TCP) haya sido cerrado.

Nuevo en la versión 3.3.

exception ssl.SSLWantReadError

Una subclase de SSLError lanzada por un socket SSL no bloqueante cuando se intenta leer o escribir datos, pero mas datos necesitan ser recibidos en el transporte TCP subyacente antes de que la solicitud pueda ser completada.

Nuevo en la versión 3.3.

exception ssl.SSLWantWriteError

Una subclase de SSLError lanzada por un socket SSL no bloqueante cuando se intenta leer o escribir datos, pero mas datos necesitan ser enviados en el transporte TCP subyacente antes de que la solicitud pueda ser completada.

Nuevo en la versión 3.3.

exception ssl.SSLSyscallError

Una subclase de SSLError lanzada cuando se encuentra un error del sistema mientras se intenta completar una operación en un socket SSL. Por desgracia, no hay una manera fácil de inspeccionar el número errno original.

Nuevo en la versión 3.3.

exception ssl.SSLEOFError

Una subclase de SSLError lanzada cuando la conexión SSL ha sido cancelada abruptamente. Generalmente, no debería intentar reutilizar el transporte subyacente cuando este error se produce.

Nuevo en la versión 3.3.

exception ssl.SSLCertVerificationError

Una subclase de SSLError lanzada cuando la validación del certificado ha fallado.

Nuevo en la versión 3.7.

verify_code

Un número de error numérico que indica el error de verificación.

verify_message

Una cadena de caracteres legible del error de verificación.

exception ssl.CertificateError

Un alias para SSLCertVerificationError.

Distinto en la versión 3.7: La excepción es ahora un alias para SSLCertVerificationError.

Generación aleatoria

ssl.RAND_bytes(num)

Retorna num bytes pseudoaleatorios criptográficamente fuertes. Lanza un SSLError si el PRNG no a sido sembrado con suficiente datos o si la operación no es soportada por el método RAND actual. RAND_status() puede ser usada para verificar el estado de PRNG y RAND_add() puede ser usada para sembrar el PRNG.

Para casi todas las aplicaciones os.urandom() es preferible.

Léase el artículo Wikipedia, Generador de números pseudoaleatorios criptográficamente seguro (CSPRNG) [https://es.wikipedia.org/wiki/Generador_de_n%C3%BAmeros_pseudoaleatorios_criptogr%C3%A1ficamente_seguro], para obtener los requisitos para un generador criptográficamente seguro.

Nuevo en la versión 3.3.

ssl.RAND_pseudo_bytes(num)

Retorna (bytes, is_cryptographic): bytes es num bytes pseudoaleatorios, is_cryptographic es True si los bytes generados son criptográficamente fuertes. Lanza un SSLError si la operación no es soportada por el método RAND actual.

Las secuencias de bytes pseudoaleatorios generadas serán únicas si tienen una longitud suficiente, pero no son necesariamente impredecibles. Pueden utilizarse para fines no criptográficos y para ciertos fines en protocolos criptográficos, pero normalmente no para la generación de claves, etc.

Para casi todas las aplicaciones os.urandom() es preferible.

Nuevo en la versión 3.3.

Obsoleto desde la versión 3.6: OpenSSL a dejado obsoleta ssl.RAND_pseudo_bytes(), utilice ssl.RAND_bytes() en su lugar.

ssl.RAND_status()

Retorna True si el generador de números pseudoaleatorios SSL a sido sembrado con “suficiente” aleatoriedad, y False de lo contrario. Puede utilizarse ssl.RAND_egd() y ssl.RAND_add() para aumentar la aleatoriedad del generador de números pseudoaleatorios.

ssl.RAND_egd(path)

Si está ejecutando un daemon de recolección de entropía (EGD) en algún lugar, y path es la ruta de una conexión de socket abierta a él, esto leerá 256 bytes de aleatoriedad del socket, y lo añadirá al generador de números pseudoaleatorios de SSL para aumentar la seguridad de las claves secretas generadas. Esto suele ser necesario sólo en sistemas sin mejores fuentes de aleatoriedad.

Véase http://egd.sourceforge.net/ o http://prngd.sourceforge.net/ para fuentes de daemons de recolección de entropía (EGD).

Disponibilidad: no disponible con LibreSSL y OpenSSL > 1.1.0.

ssl.RAND_add(bytes, entropy)

Mezcla los bytes dados en el generador de números pseudoaleatorios de SSL. El parámetro entropy (un flotante) es un límite inferior de la entropía contenida en la cadena de caracteres (por lo que siempre se puede utilizar 0.0). Véase RFC 1750 [https://tools.ietf.org/html/rfc1750.html] para mas información sobre las fuentes de entropía.

Distinto en la versión 3.5: Ahora se acepta bytes-like object modificable.

Gestión de certificados

ssl.match_hostname(cert, hostname)

Verifica que cert (en formato decodificado tal y como es retornado por SSLSocket.getpeercert()) coincide con el hostname dado. Las reglas aplicadas son las de comprobación de la identidad de los servidores HTTPS, como se indica en RFC 2818 [https://tools.ietf.org/html/rfc2818.html], RFC 5280 [https://tools.ietf.org/html/rfc5280.html] y RFC 6125 [https://tools.ietf.org/html/rfc6125.html]. Además de HTTPS, esta función debería ser adecuada para comprobar la identidad de servidores en varios protocolos basados en SSL como FTPS, IMAPS, POPS y otros.

CertificateError es lanzado en caso de error. En caso de éxito, la función no retorna nada:

>>> cert = {'subject': ((('commonName', 'example.com'),),)}
>>> ssl.match_hostname(cert, "example.com")
>>> ssl.match_hostname(cert, "example.org")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/py3k/Lib/ssl.py", line 130, in match_hostname
ssl.CertificateError: hostname 'example.org' doesn't match 'example.com'

Nuevo en la versión 3.2.

Distinto en la versión 3.3.3: La función ahora sigue RFC 6125 [https://tools.ietf.org/html/rfc6125.html] sección 6.4.3 y no soporta múltiples caracteres comodín (por ejemplo *.*.com o *a*.example.org) ni tampoco un carácter comodín dentro de un fragmento de un nombre de dominio internacionalizado (IDN). Etiquetas A de IDN tales como www*.xn--pthon-kva.org son todavía soportadas, pero x*.python.org ya no corresponde con xn--tda.python.org.

Distinto en la versión 3.5: Ahora se admite la coincidencia de direcciones IP cuando están presentes en el campo subjectAltName del certificado.

Distinto en la versión 3.7: La función ya no se utiliza para las conexiones TLS. La coincidencia de hostname es ahora realizada por OpenSSL.

Se permite el carácter comodín cuando es el carácter más a la izquierda y el único en ese segmento. Ya no se admiten comodines parciales como www*.example.com .

Obsoleto desde la versión 3.7.

ssl.cert_time_to_seconds(cert_time)

Retorna el tiempo en segundos desde la Época, dada la cadena de caracteres cert_time que representa la fecha notBefore o notAfter de un certificado en formato strptime "%b %d %H:%M:%S %Y %Z" (C locale).

He aquí un ejemplo:

>>> import ssl
>>> timestamp = ssl.cert_time_to_seconds("Jan  5 09:34:43 2018 GMT")
>>> timestamp
1515144883
>>> from datetime import datetime
>>> print(datetime.utcfromtimestamp(timestamp))
2018-01-05 09:34:43

Las fechas notBefore o notAfter deben utilizar GMT (RFC 5280 [https://tools.ietf.org/html/rfc5280.html]).

Distinto en la versión 3.5: Interpreta la hora de entrada como una hora en UTC según lo especificado por la zona horaria “GMT” en la cadena de caracteres de entrada. Anteriormente se utilizaba la zona horaria local. Devuelve un número entero (sin fracciones de segundo en el formato de entrada)

ssl.get_server_certificate(addr, ssl_version=PROTOCOL_TLS, ca_certs=None)

Dada la dirección addr de un servidor protegido con SSL, como un par (hostname, port-number), obtiene el certificado del servidor, y lo retorna como una cadena de caracteres codificada en PEM. Si se especifica ssl_version, utiliza esta versión del protocolo SSL para intentar conectarse al servidor. Si se especifica ca_certs, debe ser un archivo que contenga una lista de certificados raíz, con el mismo formato que se utiliza para el mismo parámetro en SSLContext.wrap_socket(). La llamada intentará validar el certificado del servidor contra ese conjunto de certificados raíz, y fallará si el intento de validación falla.

Distinto en la versión 3.3: Esta función es ahora compatible IPv6.

Distinto en la versión 3.5: La ssl_version por defecto se cambia de PROTOCOL_SSLv3 a PROTOCOL_TLS para una máxima compatibilidad con los servidores modernos.

ssl.DER_cert_to_PEM_cert(DER_cert_bytes)

Dado un certificado como blob de bytes codificado en DER, devuelve una versión de cadena de caracteres codificada en PEM del mismo certificado.

ssl.PEM_cert_to_DER_cert(PEM_cert_string)

Dado un certificado como cadena de caracteres ASCII PEM, devuelve una secuencia de bytes codificada con DER para ese mismo certificado.

ssl.get_default_verify_paths()

Retorna una tupla con nombre con las rutas por defecto de cafile y capath de OpenSSL. Las rutas son las mismas que las usadas por SSLContext.set_default_verify_paths(). El valor de retorno es una named tuple DefaultVerifyPaths:

cafile - ruta resuelta a cafile o None si el archivo no existe,

capath - ruta resuelta a capath o None si el directorio no existe,

openssl_cafile_env - clave de entorno de OpenSSL que apunta a un cafile,

openssl_cafile - camino codificado de forma rígida a un cafile,

openssl_capath_env - clave de entorno de OpenSSL que apunta a un capath,

openssl_capath - camino codificado de forma rígida a un directorio capath

Disponibilidad: LibreSSL ignora las variables de entorno openssl_cafile_env y openssl_capath_env.

Nuevo en la versión 3.4.

ssl.enum_certificates(store_name)

Recupera los certificados del almacén de certificados del sistema de Windows. store_name puede ser uno de los siguientes: CA, ROOT o MY. Windows también puede proporcionar almacenes de certificados adicionales.

La función devuelve una lista de tuplas (cert_bytes, encoding_type, trust). El encoding_type especifica la codificación de cert_bytes. Es x509_asn para datos X.509 ASN.1 o pkcs_7_asn para datos PKCS#7 ASN.1. Trust especifica el propósito del certificado como un conjunto de OIDS o exactamente True si el certificado es de confianza para todos los propósitos.

Ejemplo:

>>> ssl.enum_certificates("CA")
[(b'data...', 'x509_asn', {'1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2'}),
 (b'data...', 'x509_asn', True)]

Disponibilidad: Windows.

Nuevo en la versión 3.4.

ssl.enum_crls(store_name)

Obtiene CRLs del almacén de certificados del sistema de Windows. store_name puede ser uno de los siguientes: CA, ROOT o MY. Windows también puede proporcionar almacenes de certificados adicionales.

La función devuelve una lista de tuplas (cert_bytes, encoding_type, trust). El encoding_type especifica la codificación de cert_bytes. Es x509_asn para datos X.509 ASN.1 o pkcs_7_asn para datos PKCS#7 ASN.1.

Disponibilidad: Windows.

Nuevo en la versión 3.4.

ssl.wrap_socket(sock, keyfile=None, certfile=None, server_side=False, cert_reqs=CERT_NONE, ssl_version=PROTOCOL_TLS, ca_certs=None, do_handshake_on_connect=True, suppress_ragged_eofs=True, ciphers=None)

Toma una instancia sock de socket.socket, y devuelve una instancia de ssl.SSLSocket, un subtipo de socket.socket, que envuelve el socket de base en un contexto SSL. sock debe ser un socket SOCK_STREAM; otros tipos de socket no son compatibles.

Internamente, la función crea un SSLContext con un protocolo ssl_version y SSLContext.options establecido a cert_reqs. Si los parámetros keyfile, certfile, ca_certs o ciphers son establecidos, entonces los valores son pasados a SSLContext.load_cert_chain(), SSLContext.load_verify_locations(), y SSLContext.set_ciphers().

Los argumentos server_side, do_handshake_on_connect, y supress_ragged_eofs tienen el mismo significado que SSLContext.wrap_socket().

Obsoleto desde la versión 3.7: Desde Python 3.2 y 2.7.9, se recomienda usar SSLContext.wrap_socket() en lugar de wrap_socket(). La función de alto nivel tiene limitaciones y crea un socket cliente no seguro sin indicación de nombre de servidor ni hostname matching.

Constantes

Todas las constantes son ahora colecciones enum.IntEnum o enum.IntFlag.

Nuevo en la versión 3.6.

ssl.CERT_NONE

Valor posible para SSLContext.verify_mode, o el parámetro cert_reqs de wrap_socket(). A excepción de PROTOCOL_TLS_CLIENT, es el modo por defecto. Con sockets del lado del cliente, se acepta casi cualquier certificado. Errores de validación, como certificado no confiable o caducado, son ignorados y no abortan el handshake TLS/SSL.

En modo servidor, no se solicita ningún certificado al cliente, por lo que el cliente no envía ninguno para la autenticación del certificado del cliente.

Vea la discusión sobre Consideraciones de seguridad más abajo.

ssl.CERT_OPTIONAL

Valor posible para SSLContext.verify_mode, o el parámetro cert_reqs de wrap_socket(). En modo cliente, CERT_OPTIONAL tiene el mismo significado que CERT_REQUIRED. Se recomienda usar en su lugar CERT_REQUIRED para sockets del lado del cliente.

En el modo servidor, se envía una solicitud de certificado de cliente al cliente. El cliente puede ignorar la solicitud o enviar un certificado para realizar la autenticación de certificado de cliente TLS. Si el cliente opta por enviar un certificado, éste se verifica. Cualquier error de verificación aborta inmediatamente el handshake TLS.

El uso de esta configuración requiere que se pase un conjunto válido de certificados de CA, ya sea a SSLContext.load_verify_locations() o como valor del parámetro ca_certs de wrap_socket().

ssl.CERT_REQUIRED

Valor posible para SSLContext.verify_mode, o el parámetro cert_reqs de wrap_socket(). En este modo, se requieren certificados del otro lado de la conexión del socket; se lanzará un SSLError si no se proporciona ningún certificado, o si su validación falla. Este modo no es suficiente para verificar un certificado en modo cliente, ya que no coincide con los hostnames. check_hostname debe estar activado también para verificar la autenticidad de un certificado. PROTOCOL_TLS_CLIENT utiliza CERT_REQUIRED y activa check_hostname por defecto.

Con socket servidor, este modo proporciona una autenticación obligatoria de certificado de cliente TLS. Se envía una solicitud de certificado de cliente al cliente y el cliente debe proporcionar un certificado válido y de confianza.

El uso de esta configuración requiere que se pase un conjunto válido de certificados de CA, ya sea a SSLContext.load_verify_locations() o como valor del parámetro ca_certs de wrap_socket().

class ssl.VerifyMode

Colección enum.IntEnum de constantes CERT_*.

Nuevo en la versión 3.6.

ssl.VERIFY_DEFAULT

Valor posible para SSLContext.verify_flags. En este modo, las listas de revocación de certificado (CRLs) no son verificadas. Por defecto OpenSSL no requiere ni verifica CRLs.

Nuevo en la versión 3.4.

ssl.VERIFY_CRL_CHECK_LEAF

Valor posible para SSLContext.verify_flags. En este modo, sólo el certificado de pares es verificado pero ninguno de los certificados CA intermedios. El modo requiere una CRL válida que esté firmada por el emisor del certificado de pares (su CA antecesora directa). Si no se ha cargado una CRL adecuada con SSLContext.load_verify_locations, la validación fallará.

Nuevo en la versión 3.4.

ssl.VERIFY_CRL_CHECK_CHAIN

Valor posible para SSLContext.verify_flags. En este modo, las CRLs de todos los certificados en la cadena de certificado de pares son verificadas.

Nuevo en la versión 3.4.

ssl.VERIFY_X509_STRICT

Valor posible para SSLContext.verify_flags para desactivar soluciones alternativas para certificados X.509 rotos.

Nuevo en la versión 3.4.

ssl.VERIFY_X509_TRUSTED_FIRST

Valor posible para SSLContext.verify_flags. Indica a OpenSSL de preferir certificados de confianza al construir la cadena de confianza para validar un certificado. Esta opción está activada por defecto.

Nuevo en la versión 3.4.4.

class ssl.VerifyFlags

Colección enum.IntFlag de constantes VERIFY_*.

Nuevo en la versión 3.6.

ssl.PROTOCOL_TLS

Selecciona la versión mas alta del protocolo soportada tanto por el cliente como por el servidor. A pesar de su nombre, esta opción puede seleccionar ambos protocolos «SSL» y «TLS».

Nuevo en la versión 3.6.

ssl.PROTOCOL_TLS_CLIENT

Negocia automáticamente la versión más alta del protocolo como PROTOCOL_TLS, pero sólo soporta conexiones SSLSocket del lado del cliente. El protocolo activa CERT_REQUIRED y check_hostname por defecto.

Nuevo en la versión 3.6.

ssl.PROTOCOL_TLS_SERVER

Negocia automáticamente la versión más alta del protocolo como PROTOCOL_TLS, pero sólo soporta conexiones SSLSocket del lado del servidor.

Nuevo en la versión 3.6.

ssl.PROTOCOL_SSLv23

Alias para PROTOCOL_TLS.

Obsoleto desde la versión 3.6: Utilice en su lugar PROTOCOL_TLS.

ssl.PROTOCOL_SSLv2

Selecciona la versión 2 de SSL como protocolo de cifrado del canal.

Este protocolo no está disponible si OpenSSL fue compilada con la opción OPENSSL_NO_SSL2.

Advertencia

La versión 2 de SSL es insegura. Su uso es muy desaconsejado.

Obsoleto desde la versión 3.6: OpenSSL a eliminado el soporte para SSLv2.

ssl.PROTOCOL_SSLv3

Selecciona la versión 3 de SSL como protocolo de cifrado del canal.

Este protocolo no está disponible si OpenSSL fue compilada con la opción OPENSSL_NO_SSLv3.

Advertencia

La versión 3 de SSL es insegura. Su uso es muy desaconsejado.

Obsoleto desde la versión 3.6: OpenSSL a dejado obsoletas todos los protocolos de versiones específicas. Utilice en su lugar el protocolo por defecto PROTOCOL_TLS con opciones como OP_NO_SSLv3.

ssl.PROTOCOL_TLSv1

Selecciona la versión 1.0 de TLS como protocolo de cifrado del canal.

Obsoleto desde la versión 3.6: OpenSSL a dejado obsoletas todos los protocolos de versiones específicas. Utilice en su lugar el protocolo por defecto PROTOCOL_TLS con opciones como OP_NO_SSLv3.

ssl.PROTOCOL_TLSv1_1

Selecciona la versión 1.1 de TLS como protocolo de cifrado del canal. Disponible sólo con openssl en versión 1.0.1+.

Nuevo en la versión 3.4.

Obsoleto desde la versión 3.6: OpenSSL a dejado obsoletas todos los protocolos de versiones específicas. Utilice en su lugar el protocolo por defecto PROTOCOL_TLS con opciones como OP_NO_SSLv3.

ssl.PROTOCOL_TLSv1_2

Selecciona la versión 1.2 de TLS como protocolo de cifrado del canal. Esta es la versión mas moderna, y probablemente la mejor alternativa para máxima protección, si ambos lados pueden utilizarla. Disponible sólo con openssl en versión 1.0.1+.

Nuevo en la versión 3.4.

Obsoleto desde la versión 3.6: OpenSSL a dejado obsoletas todos los protocolos de versiones específicas. Utilice en su lugar el protocolo por defecto PROTOCOL_TLS con opciones como OP_NO_SSLv3.

ssl.OP_ALL

Activa soluciones alternativas para varios errores presentes en otras implementaciones SSL. Esta opción esta activada por defecto. No necesariamente activa las mismas opciones como la constante SSL_OP_ALL de OpenSSL.

Nuevo en la versión 3.2.

ssl.OP_NO_SSLv2

Evita una conexión SSLv2. Esta opción sólo es aplicable junto con PROTOCOL_TLS. Evita que los pares elijan SSLv2 como versión del protocolo.

Nuevo en la versión 3.2.

Obsoleto desde la versión 3.6: SSLv2 es obsoleto

ssl.OP_NO_SSLv3

Evita una conexión SSLv3. Esta opción sólo es aplicable junto con PROTOCOL_TLS. Evita que los pares elijan SSLv3 como versión del protocolo.

Nuevo en la versión 3.2.

Obsoleto desde la versión 3.6: SSLv3 es obsoleto

ssl.OP_NO_TLSv1

Evita una conexión TLSv1. Esta opción sólo es aplicable junto con PROTOCOL_TLS. Evita que los pares elijan TLSv1 como versión del protocolo.

Nuevo en la versión 3.2.

Obsoleto desde la versión 3.7: Esta opción es obsoleta desde OpenSSL 1.1.0, utilice en su lugar los nuevos SSLContext.minimum_version y SSLContext.maximum_version.

ssl.OP_NO_TLSv1_1

Evita una conexión TLSv1.1. Esta opción sólo es aplicable junto con PROTOCOL_TLS. Evita que los pares elijan TLSv1.1 como versión del protocolo. Disponible sólo con openssl en versión 1.0.1+.

Nuevo en la versión 3.4.

Obsoleto desde la versión 3.7: Esta opción es obsoleta desde OpenSSL 1.1.0.

ssl.OP_NO_TLSv1_2

Evita una conexión TLSv1.2. Esta opción sólo es aplicable junto con PROTOCOL_TLS. Evita que los pares elijan TLSv1.2 como versión del protocolo. Disponible sólo con openssl en versión 1.0.1+.

Nuevo en la versión 3.4.

Obsoleto desde la versión 3.7: Esta opción es obsoleta desde OpenSSL 1.1.0.

ssl.OP_NO_TLSv1_3

Evita una conexión TLSv1.3. Esta opción sólo es aplicable junto con PROTOCOL_TLS. Evita que los pares elijan TLSv1.3 como versión del protocolo. TLS 1.3 está disponible con OpenSSL 1.1.1 o superior. Cuando Python es compilado contra una versión mas antigua de OpenSSL, la opción vale 0 por defecto.

Nuevo en la versión 3.7.

Obsoleto desde la versión 3.7: Esta opción es obsoleta desde OpenSSL 1.1.0. Ha sido agregada a 2.7.15, 3.6.3 y 3.7.0 por retro-compatibilidad con OpenSSL 1.0.2.

ssl.OP_NO_RENEGOTIATION

Desactiva toda re-negociación en TLSv1.2 y anteriores. No envía mensajes HelloRequest e ignora solicitudes de re-negociación vía ClientHello.

Esta opción sólo está disponible con OpenSSL 1.1.0h y posteriores.

Nuevo en la versión 3.7.

ssl.OP_CIPHER_SERVER_PREFERENCE

Utiliza la preferencia de ordenación de cifrado del servidor, en lugar de la del cliente. Esta opción no tiene efecto en los sockets del cliente ni en los sockets del servidor SSLv2.

Nuevo en la versión 3.3.

ssl.OP_SINGLE_DH_USE

Evita la reutilización de la misma clave DH para distintas sesiones SSL. Esto mejora el secreto hacia adelante pero requiere más recursos computacionales. Esta opción sólo se aplica a los sockets del servidor.

Nuevo en la versión 3.3.

ssl.OP_SINGLE_ECDH_USE

Evita la reutilización de la misma clave ECDH para distintas sesiones SSL. Esto mejora el secreto hacia adelante pero requiere más recursos computacionales. Esta opción sólo se aplica a los sockets del servidor.

Nuevo en la versión 3.3.

ssl.OP_ENABLE_MIDDLEBOX_COMPAT

Enviar mensajes Change Cipher Spec (CCS) ficticios en el handshake de TLS 1.3 para que una conexión TLS 1.3 se parezca más a una conexión TLS 1.2.

Esta opción sólo está disponible con OpenSSL 1.1.1 y posteriores.

Nuevo en la versión 3.8.

ssl.OP_NO_COMPRESSION

Desactivar la compresión en el canal SSL. Esto es útil si el protocolo de la aplicación soporta su propio esquema de compresión.

Esta opción sólo está disponible con OpenSSL 1.0.0 y posteriores.

Nuevo en la versión 3.3.

class ssl.Options

Colección enum.IntFlag de constantes OP_*.

ssl.OP_NO_TICKET

Evita que el lado del cliente solicite un ticket de sesión.

Nuevo en la versión 3.6.

ssl.OP_IGNORE_UNEXPECTED_EOF

Ignore unexpected shutdown of TLS connections.

This option is only available with OpenSSL 3.0.0 and later.

Nuevo en la versión 3.10.

ssl.HAS_ALPN

Si la biblioteca OpenSSL tiene soporte incorporado para la extensión TLS Application-Layer Protocol Negotiation como se describe en RFC 7301 [https://tools.ietf.org/html/rfc7301.html].

Nuevo en la versión 3.5.

ssl.HAS_NEVER_CHECK_COMMON_NAME

Si la biblioteca OpenSSL tiene soporte incorporado para no comprobar el nombre común del sujeto y SSLContext.hostname_checks_common_name es modificable.

Nuevo en la versión 3.7.

ssl.HAS_ECDH

Si la biblioteca OpenSSL tiene soporte incorporado para el intercambio de claves Diffie-Hellman basado en Elliptic Curve. Esto debería ser cierto a menos que la función haya sido desactivada explícitamente por el distribuidor.

Nuevo en la versión 3.3.

ssl.HAS_SNI

Si la biblioteca OpenSSL tiene soporte incorporado para la extensión Server Name Indication (como se define en RFC 6066 [https://tools.ietf.org/html/rfc6066.html]).

Nuevo en la versión 3.2.

ssl.HAS_NPN

Si la biblioteca OpenSSL tiene soporte incorporado para Next Protocol Negotiation como se describe en Application Layer Protocol Negotiation [https://en.wikipedia.org/wiki/Application-Layer_Protocol_Negotiation]. Cuando es verdadero, puede utilizar el método SSLContext.set_npn_protocols() para anunciar los protocolos que desea soportar.

Nuevo en la versión 3.3.

ssl.HAS_SSLv2

Si la biblioteca OpenSSL tiene soporte incorporado para el protocolo SSL 2.0.

Nuevo en la versión 3.7.

ssl.HAS_SSLv3

Si la biblioteca OpenSSL tiene soporte incorporado para el protocolo SSL 3.0.

Nuevo en la versión 3.7.

ssl.HAS_TLSv1

Si la biblioteca OpenSSL tiene soporte incorporado para el protocolo TLS 1.0.

Nuevo en la versión 3.7.

ssl.HAS_TLSv1_1

Si la biblioteca OpenSSL tiene soporte incorporado para el protocolo TLS 1.1.

Nuevo en la versión 3.7.

ssl.HAS_TLSv1_2

Si la biblioteca OpenSSL tiene soporte incorporado para el protocolo TLS 1.2.

Nuevo en la versión 3.7.

ssl.HAS_TLSv1_3

Si la biblioteca OpenSSL tiene soporte incorporado para el protocolo TLS 1.3.

Nuevo en la versión 3.7.

ssl.CHANNEL_BINDING_TYPES

Lista de tipos de enlace de canales TLS admitidos. Las cadenas de caracteres en esta lista pueden ser usadas como argumentos para SSLSocket.get_channel_binding().

Nuevo en la versión 3.3.

ssl.OPENSSL_VERSION

La cadena de versión de la biblioteca OpenSSL cargada por el intérprete:

>>> ssl.OPENSSL_VERSION
'OpenSSL 1.0.2k  26 Jan 2017'

Nuevo en la versión 3.2.

ssl.OPENSSL_VERSION_INFO

Una tupla de cinco números enteros representando la información de versión de la biblioteca OpenSSL:

>>> ssl.OPENSSL_VERSION_INFO
(1, 0, 2, 11, 15)

Nuevo en la versión 3.2.

ssl.OPENSSL_VERSION_NUMBER

El número de versión en bruto de la biblioteca OpenSSL, como un único número entero:

>>> ssl.OPENSSL_VERSION_NUMBER
268443839
>>> hex(ssl.OPENSSL_VERSION_NUMBER)
'0x100020bf'

Nuevo en la versión 3.2.

ssl.ALERT_DESCRIPTION_HANDSHAKE_FAILURE

ssl.ALERT_DESCRIPTION_INTERNAL_ERROR

ALERT_DESCRIPTION_*

Descripciones de alertas de RFC 5246 [https://tools.ietf.org/html/rfc5246.html] y otras. El IANA TLS Alert Registry [https://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-6] contiene esta lista y las referencias a las RFC donde se define su significado.

Se utiliza como valor de retorno de la función callback en SSLContext.set_servername_callback().

Nuevo en la versión 3.4.

class ssl.AlertDescription

Colección enum.IntEnum de constantes ALERT_DESCRIPTION_*.

Nuevo en la versión 3.6.

Purpose.SERVER_AUTH

Opción para create_default_context() y SSLContext.load_default_certs(). Este valor indica que el contexto puede utilizarse para autenticar servidores web (por lo tanto, se utilizará para crear sockets del lado del cliente).

Nuevo en la versión 3.4.

Purpose.CLIENT_AUTH

Opción para create_default_context() y SSLContext.load_default_certs(). Este valor indica que el contexto puede utilizarse para autenticar clientes web (por lo tanto, se utilizará para crear sockets del lado del servidor).

Nuevo en la versión 3.4.

class ssl.SSLErrorNumber

Colección enum.IntEnum de constantes SSL_ERROR_*.

Nuevo en la versión 3.6.

class ssl.TLSVersion

Colección enum.IntEnum de versiones SSL y TLS para SSLContext.maximum_version y SSLContext.minimum_version.

Nuevo en la versión 3.7.

TLSVersion.MINIMUM_SUPPORTED

TLSVersion.MAXIMUM_SUPPORTED

La mínima o máxima versión soportada de SSL o TLS. Estas son constantes mágicas. Sus valores no reflejan la mas baja o mas alta versión TLS/SSL disponible.

TLSVersion.SSLv3

TLSVersion.TLSv1

TLSVersion.TLSv1_1

TLSVersion.TLSv1_2

TLSVersion.TLSv1_3

SSL 3.0 a TLS 1.3.

Sockets SSL

class ssl.SSLSocket(socket.socket)

Los sockets SSL proporcionan los siguientes métodos de Objetos Socket:

accept()

bind()

close()

connect()

detach()

fileno()

getpeername(), getsockname()

getsockopt(), setsockopt()

gettimeout(), settimeout(), setblocking()

listen()

makefile()

recv(), recv_into() (pero no se admite pasar un argumento flags diferente de cero)

send(), sendall() (con la misma limitación)

sendfile() (pero os.sendfile sera utilizado sólo para sockets de texto simple, sino send() sera utilizado)

shutdown()

Sin embargo, dado que el protocolo SSL (y TLS) tiene su propia estructura encima de TCP, la abstracción de los sockets SSL puede, en ciertos aspectos, divergir de la especificación de los sockets normales a nivel de SO. Ver especialmente las notas sobre sockets no bloqueantes.

Instancias de SSLSocket deben ser creadas usando el método SSLContext.wrap_socket().

Distinto en la versión 3.5: El método sendfile() ha sido agregado.

Distinto en la versión 3.5: El método shutdown() no reinicia el tiempo de espera del socket cada vez que se reciben o envían bytes. El tiempo de espera del socket es ahora la máxima duración del cierre.

Obsoleto desde la versión 3.6: Crear una instancia de SSLSocket directamente es obsoleto, utilice SSLContext.wrap_socket() para envolver un socket.

Distinto en la versión 3.7: Las instancias de SSLSocket deben crearse con wrap_socket(). En versiones anteriores, era posible crear instancias directamente. Esto nunca fue documentado ni soportado oficialmente.

Los sockets SSL tienen también los siguientes métodos y atributos adicionales:

SSLSocket.read(len=1024, buffer=None)

Lee hasta len bytes de datos del socket SSL y retorna el resultado como una instancia bytes. Si buffer es especificado, entonces se lee hacia el búfer en su lugar, y retorna el número de bytes leídos.

Lanza SSLWantReadError o SSLWantWriteError si el socket es no-bloqueante y la lectura se bloquearía.

Como en cualquier momento es posible una re-negociación, una llamada a read() también puede provocar operaciones de escritura.

Distinto en la versión 3.5: El tiempo de espera del socket ya no se reinicia cada vez que se reciben o envían bytes. El tiempo de espera del socket es ahora la duración total máxima para leer hasta len bytes.

Obsoleto desde la versión 3.6: Utilice recv() en lugar de read().

SSLSocket.write(buf)

Escribe buf en el socket SSL y retorna el número de bytes escritos. El argumento buf debe ser un objeto que soporte la interfaz búfer.

Lanza SSLWantReadError o SSLWantWriteError si el socket es no-bloqueante y la escritura se bloquearía.

Como en cualquier momento es posible una re-negociación, una llamada a write() también puede provocar operaciones de lectura.

Distinto en la versión 3.5: El tiempo de espera del socket ya no se reinicia cada vez que se reciben o envían bytes. El tiempo de espera del socket es ahora la duración total máxima para escribir buf.

Obsoleto desde la versión 3.6: Utilice send() en lugar de write().

Nota

Los métodos read() y write() son los métodos de bajo nivel que leen y escriben datos no cifrados a nivel de aplicación y los descifran/cifran a datos cifrados a nivel de cable. Estos métodos requieren una conexión SSL activa, es decir, que se haya completado el handshake y no se haya llamado a SSLSocket.unwrap().

Normalmente se deberían utilizar los métodos de la API de sockets como recv() y send() en lugar de estos métodos.

SSLSocket.do_handshake()

Realiza el handshake de configuración SSL.

Distinto en la versión 3.4: El método handshake también realiza match_hostname() cuando el atributo check_hostname del context del socket es verdadero.

Distinto en la versión 3.5: El tiempo de espera del socket ya no se reinicia cada vez que se reciben o envían bytes. El tiempo de espera del socket es ahora la duración total máxima del handshake.

Distinto en la versión 3.7: El hostname o la dirección IP son comparados por OpenSSL durante el handshake. La función match_hostname() ya no se utiliza. En caso de que OpenSSL rechace un hostname o dirección IP, el handshake se aborta antes de tiempo y se envía un mensaje de alerta TLS al peer.

SSLSocket.getpeercert(binary_form=False)

Si no hay un certificado para el peer en el otro extremo de la conexión, devuelve None. Si el handshake SSL no se ha realizado todavía, lanza ValueError.

Si el parámetro binary_form es False, y se ha recibido un certificado del peer, este método devuelve una instancia dict. Si el certificado no fue validado, el dict está vacío. Si el certificado fue validado, devuelve un dict con varias claves, entre ellas subject (la entidad para la que se emitió el certificado) y issuer (la entidad que emite el certificado). Si un certificado contiene una instancia de la extensión Subject Alternative Name (véase RFC 3280 [https://tools.ietf.org/html/rfc3280.html]), también habrá una clave subjectAltName en el diccionario.

Los campos subject y issuer son tuplas que contienen la secuencia de nombres distinguidos relativos (RDNs) indicados en la estructura de datos del certificado para los campos respectivos, y cada RDN es una secuencia de pares nombre-valor. Este es un ejemplo del mundo real:

{'issuer': ((('countryName', 'IL'),),
            (('organizationName', 'StartCom Ltd.'),),
            (('organizationalUnitName',
              'Secure Digital Certificate Signing'),),
            (('commonName',
              'StartCom Class 2 Primary Intermediate Server CA'),)),
 'notAfter': 'Nov 22 08:15:19 2013 GMT',
 'notBefore': 'Nov 21 03:09:52 2011 GMT',
 'serialNumber': '95F0',
 'subject': ((('description', '571208-SLe257oHY9fVQ07Z'),),
             (('countryName', 'US'),),
             (('stateOrProvinceName', 'California'),),
             (('localityName', 'San Francisco'),),
             (('organizationName', 'Electronic Frontier Foundation, Inc.'),),
             (('commonName', '*.eff.org'),),
             (('emailAddress', 'hostmaster@eff.org'),)),
 'subjectAltName': (('DNS', '*.eff.org'), ('DNS', 'eff.org')),
 'version': 3}

Nota

Para validar un certificado para un servicio concreto, puede utilizar la función match_hostname().

Si el parámetro binary_form es True, y se proporcionó un certificado, este método devuelve la forma codificada en DER del certificado completo como una secuencia de bytes, o None si el par no proporcionó un certificado. El hecho de que el par proporcione un certificado depende del rol del socket SSL:

para un socket SSL cliente, el servidor siempre proporcionará un certificado, independientemente de si se requirió la validación;

para un socket SSL servidor, el cliente sólo proporcionará un certificado cuando lo solicite el servidor; por lo tanto getpeercert() devolverá None si ha utilizado CERT_NONE (en lugar de CERT_OPTIONAL o CERT REQUIRED).

Distinto en la versión 3.2: El diccionario devuelto incluye elementos adicionales tales como issuer y notBefore.

Distinto en la versión 3.4: ValueError se lanza cuando no se realiza el handshake. El diccionario retornado incluye elementos de extensión X509v3 adicionales como crlDistributionPoints, caIssuers y OCSP URIs.

Distinto en la versión 3.9: Las cadenas de direcciones IPv6 ya no tienen una nueva línea al final.

SSLSocket.cipher()

Retorna una tupla de tres valores que contiene el nombre del cifrado que se está utilizando, la versión del protocolo SSL que define su uso y el número de bits secretos que se están utilizando. Si no se ha establecido ninguna conexión, retorna None.

SSLSocket.shared_ciphers()

Retorna la lista de cifrados compartidos por el cliente durante el handshake. Cada entrada de la lista devuelta es una tupla de tres valores que contiene el nombre del cifrado, la versión del protocolo SSL que define su uso y el número de bits secretos que utiliza el cifrado. shared_ciphers`() retorna None si no se ha establecido ninguna conexión o el socket es un socket cliente.

Nuevo en la versión 3.5.

SSLSocket.compression()

Retorna el algoritmo de compresión utilizado como una cadena de caracteres, o None si la conexión no está comprimida.

Si el protocolo de nivel superior soporta su propio mecanismo de compresión, puede utilizar OP_NO_COMPRESSION para desactivar la compresión a nivel de SSL.

Nuevo en la versión 3.3.

SSLSocket.get_channel_binding(cb_type="tls-unique")

Obtiene los datos de enlace del canal para la conexión actual, como un objeto bytes. Retorna None si no está conectado o no se ha completado el handshake.

El parámetro cb_type permite seleccionar el tipo de enlace de canal deseado. Los tipos de enlace de canal válidos se enumeran en la lista CHANNEL_BINDING_TYPES. Actualmente, sólo se admite la vinculación de canal “tls-unique”, definida por RFC 5929 [https://tools.ietf.org/html/rfc5929.html]. ValueError se lanzará si se solicita un tipo de vinculación de canal no admitido.

Nuevo en la versión 3.3.

SSLSocket.selected_alpn_protocol()

Retorna el protocolo que fue seleccionado durante el handshake TLS. Si no se ha llamado a SSLContext.set_alpn_protocols(), si la otra parte no soporta ALPN, si este socket no soporta ninguno de los protocolos propuestos por el cliente, o si el handshake no ha ocurrido todavía, se devuelve None.

Nuevo en la versión 3.5.

SSLSocket.selected_npn_protocol()

Devuelve el protocolo de nivel superior que se seleccionó durante el handshake TLS/SSL. Si no se llamó a SSLContext.set_npn_protocols(), o si la otra parte no soporta NPN, o si el handshake aún no ha ocurrido, esto devolverá None.

Nuevo en la versión 3.3.

SSLSocket.unwrap()

Realiza el handshake de cierre de SSL, que elimina la capa TLS del socket subyacente, y devuelve el objeto socket subyacente. Esto puede utilizarse para pasar de una operación encriptada sobre una conexión a una sin encriptar. El socket devuelto debe utilizarse siempre para la comunicación posterior con el otro lado de la conexión, en lugar del socket original.

SSLSocket.verify_client_post_handshake()

Solicita la autenticación post-handshake (PHA) de un cliente TLS 1.3. PHA sólo puede iniciarse para una conexión TLS 1.3 desde un socket del lado del servidor, después del handshake TLS inicial y con PHA habilitado en ambos lados, ver SSLContext.post_handshake_auth.

El método no realiza un intercambio de certificados inmediatamente. El lado del servidor envía una CertificateRequest durante el siguiente evento de escritura y espera que el cliente responda con un certificado en el siguiente evento de lectura.

Si alguna precondición no se cumple (por ejemplo, no es TLS 1.3, PHA no está habilitado), se genera un SSLError.

Nota

Sólo está disponible con OpenSSL 1.1.1 y TLS 1.3 habilitados. Sin el soporte de TLS 1.3, el método lanza NotImplementedError.

Nuevo en la versión 3.8.

SSLSocket.version()

Return the actual SSL protocol version negotiated by the connection as a string, or None if no secure connection is established. As of this writing, possible return values include "SSLv2", "SSLv3", "TLSv1", "TLSv1.1" and "TLSv1.2". Recent OpenSSL versions may define more return values.

Nuevo en la versión 3.5.

SSLSocket.pending()

Retorna el número de bytes ya descifrados disponibles para leer, pendientes de la conexión.

SSLSocket.context

El objeto SSLContext al que está vinculado este socket SSL. Si el socket SSL fue creado usando la función obsoleta wrap_socket() (en lugar de SSLContext.wrap_socket()), este es un objeto de contexto personalizado creado para este socket SSL.

Nuevo en la versión 3.2.

SSLSocket.server_side

Un booleano que es True para los sockets del lado del servidor y False para los sockets del lado del cliente.

Nuevo en la versión 3.2.

SSLSocket.server_hostname

Hostname del servidor: tipo str, o None para el socket del lado del servidor o si el hostname no fue especificado en el constructor.

Nuevo en la versión 3.2.

Distinto en la versión 3.7: El atributo es ahora siempre texto ASCII. Cuando server_hostname es un nombre de dominio internacionalizado (IDN), este atributo almacena ahora la forma de etiqueta A ("xn--pythn-mua.org"), en lugar de la forma de etiqueta U ("pythön.org").

SSLSocket.session

La SSLSession para esta conexión SSL. La sesión está disponible para los sockets del lado del cliente y del servidor después de que se haya realizado el handshake TLS. Para los sockets del cliente la sesión puede ser establecida antes de que do_handshake() haya sido llamado para reutilizar una sesión.

Nuevo en la versión 3.6.

SSLSocket.session_reused

Nuevo en la versión 3.6.

Contextos SSL

Nuevo en la versión 3.2.

Un contexto SSL contiene varios datos más duraderos que las conexiones SSL individuales, como opciones de configuración SSL, certificado(s) y clave(s) privada(s). También gestiona un cache de sesiones SSL para sockets del lado del servidor, para acelerar conexiones repetidas de los mismos clientes.

class ssl.SSLContext(protocol=PROTOCOL_TLS)

Crea un nuevo contexto SSL. Puede pasar protocolo que debe ser una de las constantes PROTOCOL_* definidas en este módulo. El parámetro especifica la versión del protocolo SSL a utilizar. Típicamente, el servidor elige una versión particular del protocolo, y el cliente debe adaptarse a la elección del servidor. La mayoría de las versiones no son interoperables con las demás. Si no se especifica, el valor por defecto es PROTOCOL_TLS; proporciona la mayor compatibilidad con otras versiones.

Esta es una tabla que muestra qué versiones de un cliente (en la parte inferior) pueden conectarse a qué versiones de un servidor (en la parte superior):

cliente / servidor

SSLv2

SSLv3

TLS 3

TLSv1

TLSv1.1

TLSv1.2

SSLv2

si

no

no 1

no

no

no

SSLv3

no

si

no 2

no

no

no

TLS (SSLv23) 3

no 1

no 2

si

si

si

si

TLSv1

no

no

si

si

no

no

TLSv1.1

no

no

si

no

si

no

TLSv1.2

no

no

si

no

no

si

Notas a pie de página

1(1,2)

SSLContext desactiva SSLv2 con OP_NO_SSLv2 por defecto.

2(1,2)

SSLContext desactiva SSLv3 con OP_NO_SSLv3 por defecto.

3(1,2)

El protocolo TLS 1.3 estará disponible con PROTOCOL_TLS en OpenSSL >= 1.1.1. No existe una constante PROTOCOL dedicada sólo a TLS 1.3.

Ver también

create_default_context() permite al módulo ssl elegir la configuración de seguridad para un propósito determinado.

Distinto en la versión 3.6: El contexto se crea con valores seguros por defecto. Las opciones OP_NO_COMPRESSION, OP_CIPHER_SERVER_PREFERENCE, OP_SINGLE_DH_USE, OP_SINGLE_ECDH_USE, OP_NO_SSLv2 (excepto para PROTOCOL_SSLv2), y OP_NO_SSLv3 (excepto para PROTOCOL_SSLv3) están establecidas por defecto. La lista inicial de conjuntos de cifrado sólo contiene cifrados HIGH, ningún cifrado NULL y ningún cifrado MD5 (excepto para PROTOCOL_SSLv2).

Los objetos SSLContext tienen los siguientes métodos y atributos:

SSLContext.cert_store_stats()

Obtiene estadísticas sobre las cantidades de certificados X.509 cargados, la cantidad de certificados X.509 marcados como certificados CA y las listas de revocación de certificados como diccionario.

Ejemplo para un contexto con un certificado CA y otro certificado:

>>> context.cert_store_stats()
{'crl': 0, 'x509_ca': 1, 'x509': 2}

Nuevo en la versión 3.4.

SSLContext.load_cert_chain(certfile, keyfile=None, password=None)

Load a private key and the corresponding certificate. The certfile string must be the path to a single file in PEM format containing the certificate as well as any number of CA certificates needed to establish the certificate’s authenticity. The keyfile string, if present, must point to a file containing the private key. Otherwise the private key will be taken from certfile as well. See the discussion of Certificados for more information on how the certificate is stored in the certfile.

El argumento password puede ser una función a la que llamar para obtener la contraseña para descifrar la clave privada. Sólo se llamará si la clave privada está encriptada y se necesita una contraseña. Se llamará sin argumentos, y deberá devolver una cadena de caracteres, bytes o bytearray. Si el valor devuelto es una cadena de caracteres, se codificará como UTF-8 antes de utilizarlo para descifrar la clave. Alternativamente, se puede suministrar un valor de cadena de caracteres, bytes o bytearray directamente como argumento password. Se ignorará si la clave privada no está cifrada y no se necesita una contraseña.

Si el argumento password no es especificado y una contraseña es requerida, el mecanismo de solicitud de contraseña incorporado de OpenSSL se usará para solicitarle una contraseña al usuario de forma interactiva.

Un SSLError es lanzado si la clave privada no coincide con el certificado.

Distinto en la versión 3.3: Nuevo argumento opcional password.

SSLContext.load_default_certs(purpose=Purpose.SERVER_AUTH)

Load a set of default «certification authority» (CA) certificates from default locations. On Windows it loads CA certs from the CA and ROOT system stores. On all systems it calls SSLContext.set_default_verify_paths(). In the future the method may load CA certificates from other locations, too.

La opción purpose especifica qué tipo de certificados CA se cargan. La configuración por defecto Purpose.SERVER_AUTH carga certificados, que están marcados y son de confianza para la autenticación del servidor web TLS (sockets del lado del cliente). Purpose.CLIENT_AUTH carga certificados CA para la verificación de certificados de cliente en el lado del servidor.

Nuevo en la versión 3.4.

SSLContext.load_verify_locations(cafile=None, capath=None, cadata=None)

Carga un conjunto de certificados de «autoridad de certificación» (CA) usados para validar certificados de otros pares cuando verify_mode es distinto de CERT_NONE. Debe especificarse al menos uno de cafile o capath.

Este método puede cargar también listas de revocación de certificados (CRLs) en formato PEM o DER. Para poder usar CRLs, SSLContext.verify_flags debe ser configurado correctamente.

La cadena de caracteres cafile, si está presente, es la ruta a un archivo de certificados CA concatenados en formato PEM. Vea la discusión de Certificados para más información acerca de como organizar los certificados en este archivo.

La cadena de caracteres capath, si está presente, es la ruta a un directorio que contiene varios certificados CA en formato PEM, siguiendo la disposición específica de OpenSSL [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_load_verify_locations.html].

El objeto cadata, si está presente, es una cadena de caracteres ASCII de uno o más certificados codificados en PEM o un bytes-like object de certificados codificados en DER. Al igual que con capath, las líneas adicionales alrededor de los certificados codificados en PEM se ignoran, pero debe haber al menos un certificado.

Distinto en la versión 3.4: Nuevo argumento opcional cadata

SSLContext.get_ca_certs(binary_form=False)

Obtiene una lista de certificados de «autoridad de certificación» (CA) cargados. Si el parámetro binary_form es False cada entrada de la lista es un diccionario como la salida de SSLSocket.getpeercert(). En caso contrario, el método devuelve una lista de certificados codificados con DER. La lista devuelta no contiene certificados de capath a menos que un certificado haya sido solicitado y cargado por una conexión SSL.

Nota

Los certificados de un directorio capath no se cargan a menos que se hayan utilizado al menos una vez.

Nuevo en la versión 3.4.

SSLContext.get_ciphers()

Obtiene una lista de cifrados habilitados. La lista está en orden de prioridad de cifrado. Véase SSLContext.set_ciphers().

Ejemplo:

>>> ctx = ssl.SSLContext(ssl.PROTOCOL_SSLv23)
>>> ctx.set_ciphers('ECDHE+AESGCM:!ECDSA')
>>> ctx.get_ciphers()  # OpenSSL 1.0.x
[{'alg_bits': 256,
  'description': 'ECDHE-RSA-AES256-GCM-SHA384 TLSv1.2 Kx=ECDH     Au=RSA  '
                 'Enc=AESGCM(256) Mac=AEAD',
  'id': 50380848,
  'name': 'ECDHE-RSA-AES256-GCM-SHA384',
  'protocol': 'TLSv1/SSLv3',
  'strength_bits': 256},
 {'alg_bits': 128,
  'description': 'ECDHE-RSA-AES128-GCM-SHA256 TLSv1.2 Kx=ECDH     Au=RSA  '
                 'Enc=AESGCM(128) Mac=AEAD',
  'id': 50380847,
  'name': 'ECDHE-RSA-AES128-GCM-SHA256',
  'protocol': 'TLSv1/SSLv3',
  'strength_bits': 128}]

En OpenSSL 1.1 y posterior el diccionario de cifrado contiene campos adicionales:

>>> ctx.get_ciphers()  # OpenSSL 1.1+
[{'aead': True,
  'alg_bits': 256,
  'auth': 'auth-rsa',
  'description': 'ECDHE-RSA-AES256-GCM-SHA384 TLSv1.2 Kx=ECDH     Au=RSA  '
                 'Enc=AESGCM(256) Mac=AEAD',
  'digest': None,
  'id': 50380848,
  'kea': 'kx-ecdhe',
  'name': 'ECDHE-RSA-AES256-GCM-SHA384',
  'protocol': 'TLSv1.2',
  'strength_bits': 256,
  'symmetric': 'aes-256-gcm'},
 {'aead': True,
  'alg_bits': 128,
  'auth': 'auth-rsa',
  'description': 'ECDHE-RSA-AES128-GCM-SHA256 TLSv1.2 Kx=ECDH     Au=RSA  '
                 'Enc=AESGCM(128) Mac=AEAD',
  'digest': None,
  'id': 50380847,
  'kea': 'kx-ecdhe',
  'name': 'ECDHE-RSA-AES128-GCM-SHA256',
  'protocol': 'TLSv1.2',
  'strength_bits': 128,
  'symmetric': 'aes-128-gcm'}]

Availability: OpenSSL 1.0.2+.

Nuevo en la versión 3.6.

SSLContext.set_default_verify_paths()

Carga un conjunto de certificados de «autoridad de certificación» (CA) por defecto desde una ruta del sistema de archivos definida al construir la biblioteca OpenSSL. Desafortunadamente, no hay una manera fácil de saber si este método tiene éxito: no se devuelve ningún error si no se encuentran certificados. Sin embargo, cuando la biblioteca OpenSSL se proporciona como parte del sistema operativo, es probable que esté configurada correctamente.

SSLContext.set_ciphers(ciphers)

Establece los cifrados disponibles para los sockets creados con este contexto. Debe ser una cadena de caracteres con el formato de la lista de cifrado de OpenSSL [https://www.openssl.org/docs/manmaster/man1/ciphers.html]. Si no se puede seleccionar ningún cifrado (porque las opciones en tiempo de compilación u otra configuración prohíben el uso de todos los cifrados especificados), se lanzará un SSLError.

Nota

cuando se conecta, el método SSLSocket.cipher() de los sockets SSL dará el cifrado actualmente seleccionado.

OpenSSL 1.1.1 tiene suites de cifrado TLS 1.3 habilitadas por defecto. Las suites no se pueden desactivar con set_ciphers().

SSLContext.set_alpn_protocols(protocols)

Especifica qué protocolos debe anunciar el socket durante el handshake SSL/TLS. Debe ser una lista de cadenas de caracteres ASCII, como ['http/1.1', 'spdy/2'], ordenadas por preferencia. La selección de un protocolo ocurrirá durante el handshake, y se desarrollará de acuerdo con RFC 7301 [https://tools.ietf.org/html/rfc7301.html]. Después de un handshake exitoso, el método SSLSocket.selected_alpn_protocol() devolverá el protocolo acordado.

Este método lanzará NotImplementedError si HAS_ALPN es False.

OpenSSL 1.1.0 a 1.1.0e abortará el handshake y lanzará SSLError cuando ambos lados soporten ALPN pero no puedan acordar un protocolo. 1.1.0f+ se comporta como 1.0.2, SSLSocket.selected_alpn_protocol() devuelve None.

Nuevo en la versión 3.5.

SSLContext.set_npn_protocols(protocols)

Especifica qué protocolos debe anunciar el socket durante el handshake SSL/TLS. Debe ser una lista de cadenas, como ['http/1.1', 'spdy/2'], ordenadas por preferencia. La selección de un protocolo ocurrirá durante el handshake, y se desarrollará de acuerdo a la Negociación del Protocolo de la Capa de Aplicación [https://en.wikipedia.org/wiki/Application-Layer_Protocol_Negotiation]. Después de un handshake exitoso, el método SSLSocket.selected_npn_protocol() devolverá el protocolo acordado.

Este método lanzará NotImplementedError si HAS_NPN es False.

Nuevo en la versión 3.3.

SSLContext.sni_callback

Registra una función callback que se llamará después de que el servidor SSL/TLS haya recibido el mensaje de diálogo TLS Client Hello cuando el cliente TLS especifique una indicación de nombre de servidor. El mecanismo de indicación de nombre de servidor se especifica en RFC 6066 [https://tools.ietf.org/html/rfc6066.html] sección 3 - Server Name Indication.

Sólo se puede establecer una función callback por SSLContext. Si sni_callback se establece como None, la función callback se desactiva. Si se llama a esta función una vez más, se desactivará la función callback registrada anteriormente.

La función callback será llamada con tres argumentos; el primero es el ssl.SSLSocket, el segundo es una cadena que representa el nombre del servidor con el que el cliente pretende comunicarse (o None si el TLS Client Hello no contiene un nombre de servidor) y el tercer argumento es el SSLContext original. El argumento del nombre del servidor es un texto. En el caso de los nombres de dominio internacionalizados, el nombre del servidor es un IDN etiqueta A ("xn--pythn-mua.org").

Un uso típico de esta función callback es cambiar el atributo SSLSocket.context de ssl.SSLSocket por un nuevo objeto de tipo SSLContext que representa una cadena de certificados que coincide con el nombre del servidor.

Due to the early negotiation phase of the TLS connection, only limited methods and attributes are usable like SSLSocket.selected_alpn_protocol() and SSLSocket.context. The SSLSocket.getpeercert(), SSLSocket.cipher() and SSLSocket.compression() methods require that the TLS connection has progressed beyond the TLS Client Hello and therefore will not return meaningful values nor can they be called safely.

La función sni_callback debe devolver None para permitir que la negociación TLS continúe. Si se requiere un fallo TLS, se puede devolver una constante ALERT_DESCRIPTION_*. Otros valores de retorno resultarán en un error fatal TLS con ALERT_DESCRIPTION_INTERNAL_ERROR.

Si se lanza una excepción desde la función sni_callback la conexión TLS terminará con un mensaje de alerta TLS fatal ALERT_DESCRIPTION_HANDSHAKE_FAILURE.

Este método lanzará NotImplementedError si la biblioteca OpenSSL tenía definido OPENSSL_NO_TLSEXT cuando se construyó.

Nuevo en la versión 3.7.

SSLContext.set_servername_callback(server_name_callback)

Se trata de una API heredada que se mantiene por compatibilidad con versiones anteriores. Cuando sea posible, debería utilizar sni_callback en su lugar. El server_name_callback dado es similar a sni_callback, excepto que cuando el nombre del servidor es un nombre de dominio internacionalizado codificado con IDN, el server_name_callback recibe una etiqueta U decodificada ("pythön.org").

Si hay un error de decodificación en el nombre del servidor, la conexión TLS terminará con un mensaje fatal de alerta TLS ALERT_DESCRIPTION_INTERNAL_ERROR al cliente.

Nuevo en la versión 3.4.

SSLContext.load_dh_params(dhfile)

Carga los parámetros de generación de claves para el intercambio de claves Diffie-Hellman (DH). El uso del intercambio de claves DH mejora el secreto hacia adelante a expensas de recursos computacionales (tanto en el servidor como en el cliente). El parámetro dhfile debe ser la ruta de un archivo que contenga los parámetros DH en formato PEM.

Esta configuración no se aplica a los sockets de los clientes. También puede utilizar la opción OP_SINGLE_DH_USE para mejorar aún más la seguridad.

Nuevo en la versión 3.3.

SSLContext.set_ecdh_curve(curve_name)

Establece el nombre de la curva para el intercambio de claves Diffie-Hellman basado en la curva elíptica (ECDH). ECDH es significativamente más rápido que el DH normal, aunque podría decirse que es igual de seguro. El parámetro curve_name debe ser una cadena que describa una curva elíptica conocida, por ejemplo prime256v1 para una curva ampliamente soportada.

Esta configuración no se aplica a los sockets de los clientes. También puede utilizar la opción OP_SINGLE_ECDH_USE para mejorar aún más la seguridad.

Este método no está disponible si HAS_ECDH es False.

Nuevo en la versión 3.3.

Ver también

SSL/TLS & Perfect Forward Secrecy [https://vincent.bernat.im/en/blog/2011-ssl-perfect-forward-secrecy]

Vincent Bernat.

SSLContext.wrap_socket(sock, server_side=False, do_handshake_on_connect=True, suppress_ragged_eofs=True, server_hostname=None, session=None)

Envuelve un socket Python existente sock y devuelve una instancia de SSLContext.sslsocket_class (por defecto SSLSocket). El socket SSL devuelto está ligado al contexto, su configuración y certificados. sock debe ser un socket SOCK_STREAM; otros tipos de socket no son soportados.

El parámetro server_side es un booleano que identifica si se desea un comportamiento del lado del servidor o del lado del cliente en este socket.

Para los sockets del lado del cliente, la construcción del contexto es perezosa; si el socket subyacente no está conectado todavía, la construcción del contexto se realizará después de llamar a connect() en el socket. Para los sockets del lado del servidor, si el socket no tiene un par remoto, se asume que es un socket a la escucha, y la envoltura SSL del lado del servidor se realiza automáticamente en las conexiones del cliente aceptadas a través del método accept(). El método puede lanzar SSLError.

En las conexiones de cliente, el parámetro opcional server_hostname especifica el nombre del servicio al que nos estamos conectando. Esto permite que un único servidor aloje varios servicios basados en SSL con certificados distintos, de forma similar a los hosts virtuales HTTP. Al especificar server_hostname se producirá un ValueError si server_side es verdadero.

El parámetro do_handshake_on_connect especifica si se hace el handshake SSL automáticamente después de hacer un socket.connect(), o si el programa de aplicación lo llamará explícitamente, invocando el método SSLSocket.do_handshake(). Llamar explícitamente a SSLSocket.do_handshake() da al programa el control sobre el comportamiento de bloqueo de la E/S del socket involucrada en el handshake.

El parámetro suppress_ragged_eofs especifica cómo el método SSLSocket.recv() debe señalar los EOF inesperados desde el otro extremo de la conexión. Si se especifica como True (el valor por defecto), devuelve un EOF normal (un objeto bytes vacío) en respuesta a los errores EOF inesperados que se produzcan desde el socket subyacente; si False, lanzará las excepciones al llamador.

session, véase session.

Distinto en la versión 3.5: Siempre permite pasar un server_hostname, incluso si OpenSSL no tiene SNI.

Distinto en la versión 3.6: Se agregó el argumento session.

Distinto en la versión 3.7: El método retorna una instancia de SSLContext.sslsocket_class en lugar de un SSLSocket rígidamente programado.

SSLContext.sslsocket_class

El tipo de retorno de SSLContext.wrap_socket(), por defecto es SSLSocket. El atributo puede anularse en la instancia de la clase para devolver una subclase personalizada de SSLSocket.

Nuevo en la versión 3.7.

SSLContext.wrap_bio(incoming, outgoing, server_side=False, server_hostname=None, session=None)

Envuelve los objetos BIO incoming y outgoing y devuelve una instancia de SSLContext.sslobject_class (por defecto SSLObject). Las rutinas SSL leerán los datos de entrada de la BIO entrante y escribirán los datos en la BIO saliente.

Los parámetros server_side, server_hostname y session tienen el mismo significado que en SSLContext.wrap_socket().

Distinto en la versión 3.6: Se agregó el argumento session.

Distinto en la versión 3.7: El método retorna una instancia de SSLContext.sslobject_class en lugar de un SSLObject rígidamente programado.

SSLContext.sslobject_class

El tipo de retorno de SSLContext.wrap_bio(), por defecto es SSLObject. El atributo puede anularse en la instancia de la clase para devolver una subclase personalizada de SSLObject.

Nuevo en la versión 3.7.

SSLContext.session_stats()

Obtiene estadísticas sobre las sesiones SSL creadas o gestionadas por este contexto. Se devuelve un diccionario que asigna los nombres de cada pieza de información [https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_sess_number.html] a sus valores numéricos. Por ejemplo, aquí está el número total de aciertos y errores en la caché de sesión desde que se creó el contexto:

>>> stats = context.session_stats()
>>> stats['hits'], stats['misses']
(0, 0)

SSLContext.check_hostname

Whether to match the peer cert’s hostname in SSLSocket.do_handshake(). The context’s verify_mode must be set to CERT_OPTIONAL or CERT_REQUIRED, and you must pass server_hostname to wrap_socket() in order to match the hostname. Enabling hostname checking automatically sets verify_mode from CERT_NONE to CERT_REQUIRED. It cannot be set back to CERT_NONE as long as hostname checking is enabled. The PROTOCOL_TLS_CLIENT protocol enables hostname checking by default. With other protocols, hostname checking must be enabled explicitly.

Ejemplo:

import socket, ssl

context = ssl.SSLContext(ssl.PROTOCOL_TLSv1_2)
context.verify_mode = ssl.CERT_REQUIRED
context.check_hostname = True
context.load_default_certs()

s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
ssl_sock = context.wrap_socket(s, server_hostname='www.verisign.com')
ssl_sock.connect(('www.verisign.com', 443))

Nuevo en la versión 3.4.

Distinto en la versión 3.7: verify_mode ahora se cambia automáticamente a CERT_REQUIRED cuando la comprobación del hostname está activada y verify_mode es CERT_NONE. Anteriormente la misma operación habría fallado con un ValueError.

Nota

Esta funcionalidad requiere OpenSSL 0.9.8f o posterior.

SSLContext.keylog_filename

Escribe las claves TLS en un archivo keylog, siempre que se genere o reciba material de claves. El archivo keylog está diseñado únicamente para fines de depuración. El formato del archivo está especificado por NSS y es utilizado por muchos analizadores de tráfico como Wireshark. El archivo de registro se abre en modo sólo añadir. Las escrituras se sincronizan entre hilos, pero no entre procesos.

Nuevo en la versión 3.8.

Nota

Esta funcionalidad requiere OpenSSL 1.1.1 o posterior.

SSLContext.maximum_version

Un miembro enumeración de TLSVersion que representa la versión más alta de TLS soportada. El valor por defecto es TLSVersion.MAXIMUM_SUPPORTED. El atributo es de sólo lectura para protocolos distintos de PROTOCOL_TLS, PROTOCOL_TLS_CLIENT y PROTOCOL_TLS_SERVER.

Los atributos maximum_version, minimum_version y SSLContext.options afectan a las versiones SSL y TLS soportadas del contexto. La implementación no evita la combinación inválida. Por ejemplo, un contexto con OP_NO_TLSv1_2 en options y maximum_version establecido en TLSVersion.TLSv1_2 no podrá establecer una conexión TLS 1.2.

Nota

Este atributo no está disponible a menos que el módulo ssl haya sido compilado con OpenSSL 1.1.0g o posterior.

Nuevo en la versión 3.7.

SSLContext.minimum_version

Igual que SSLContext.maximum_version excepto que es la versión más baja soportada o TLSVersion.MINIMUM_SUPPORTED.

Nota

Este atributo no está disponible a menos que el módulo ssl haya sido compilado con OpenSSL 1.1.0g o posterior.

Nuevo en la versión 3.7.

SSLContext.num_tickets

Controla el número de tickets de sesión TLS 1.3 de un contexto TLS_PROTOCOL_SERVER. El ajuste no tiene impacto en las conexiones TLS 1.0 a 1.2.

Nota

Este atributo no está disponible a menos que el módulo ssl haya sido compilado con OpenSSL 1.1.1 o posterior.

Nuevo en la versión 3.8.

SSLContext.options

Un número entero que representa el conjunto de opciones SSL habilitadas en este contexto. El valor por defecto es OP_ALL, pero se pueden especificar otras opciones como OP_NO_SSLv2 mediante la combinación OR.

Nota

Con versiones de OpenSSL anteriores a la 0.9.8m, sólo es posible establecer opciones, no borrarlas. Si se intenta borrar una opción (restableciendo los bits correspondientes) se producirá un ValueError.

Distinto en la versión 3.6: SSLContext.options retorna opciones Options:

>>> ssl.create_default_context().options
<Options.OP_ALL|OP_NO_SSLv3|OP_NO_SSLv2|OP_NO_COMPRESSION: 2197947391>

SSLContext.post_handshake_auth

Habilita la autenticación del cliente TLS 1.3 post-handshake. La autenticación post-handshake está deshabilitada por defecto y un servidor sólo puede solicitar un certificado de cliente TLS durante el handshake inicial. Cuando se habilita, un servidor puede solicitar un certificado de cliente TLS en cualquier momento después del handshake.

Cuando se activa en los sockets del lado del cliente, el cliente indica al servidor que soporta la autenticación post-handshake.

Cuando se activa en los sockets del lado del servidor, SSLContext.verify_mode debe establecerse también como CERT_OPTIONAL o CERT_REQUIRED. El intercambio real de certificados del cliente se retrasa hasta que se llama a SSLSocket.verify_client_post_handshake() y se realiza alguna E/S.

Nota

Sólo está disponible con OpenSSL 1.1.1 y TLS 1.3 habilitados. Sin soporte de TLS 1.3, el valor de la propiedad es None y no puede ser modificado

Nuevo en la versión 3.8.

SSLContext.protocol

La versión del protocolo elegida cuando se construyó el contexto. Este atributo es de sólo lectura.

SSLContext.hostname_checks_common_name

Si check_hostname vuelve a verificar el nombre común del sujeto del certificado en ausencia de una extensión de nombre alternativo del sujeto (por defecto: true).

Nota

Solo modificable con OpenSSL 1.1.0 o posterior.

Nuevo en la versión 3.7.

Distinto en la versión 3.9.3: The flag had no effect with OpenSSL before version 1.1.1k. Python 3.8.9, 3.9.3, and 3.10 include workarounds for previous versions.

SSLContext.verify_flags

Los indicadores para las operaciones de verificación de certificados. Se pueden establecer indicadores como VERIFY_CRL_CHECK_LEAF mediante la combinación OR. Por defecto, OpenSSL no requiere ni verifica las listas de revocación de certificados (CRL). Disponible sólo con la versión 0.9.8+ de openssl.

Nuevo en la versión 3.4.

Distinto en la versión 3.6: SSLContext.verify_flags retorna opciones VerifyFlags:

>>> ssl.create_default_context().verify_flags
<VerifyFlags.VERIFY_X509_TRUSTED_FIRST: 32768>

SSLContext.verify_mode

Si se intenta verificar los certificados de otros pares y cómo comportarse si la verificación falla. Este atributo debe ser uno de los siguientes: CERT_NONE, CERT_OPTIONAL o CERT_REQUIRED.

Distinto en la versión 3.6: SSLContext.verify_mode retorna VerifyMode enum:

>>> ssl.create_default_context().verify_mode
<VerifyMode.CERT_REQUIRED: 2>

Certificados

En general, los certificados forman parte de un sistema de clave pública/clave privada. En este sistema, a cada principal (que puede ser una máquina, una persona o una organización) se le asigna una clave de cifrado única de dos partes. Una parte de la clave es pública y se llama clave pública; la otra parte se mantiene en secreto y se llama clave privada. Las dos partes están relacionadas, en el sentido de que si se cifra un mensaje con una de las partes, se puede descifrar con la otra parte, y sólo con la otra parte.

Un certificado contiene información sobre dos sujetos. Contiene el nombre de un sujeto, y la clave pública del sujeto. También contiene una declaración de un segundo titular, el emisor, de que el sujeto es quien dice ser, y de que ésta es efectivamente la clave pública del sujeto. La declaración del emisor está firmada con su clave privada, que sólo el emisor conoce. Sin embargo, cualquiera puede verificar la declaración del emisor encontrando la clave pública del emisor, descifrando la declaración con ella y comparándola con el resto de la información del certificado. El certificado también contiene información sobre el periodo de tiempo en el que es válido. Esto se expresa en dos campos, llamados notBefore y notAfter.

En el uso de certificados en Python, un cliente o servidor puede utilizar un certificado para demostrar quién es. El otro lado de una conexión de red también puede ser requerido para producir un certificado, y ese certificado puede ser validado a la satisfacción del cliente o servidor que requiere dicha validación. El intento de conexión puede configurarse para que lance una excepción si la validación falla. La validación se realiza automáticamente, por el subyacente framework OpenSSL; la aplicación no necesita preocuparse de su mecánica. Sin embargo, la aplicación normalmente necesita proporcionar conjuntos de certificados para permitir que este proceso tenga lugar.

Python utiliza archivos para contener certificados. Deben ser formateados como «PEM» (ver RFC 1422 [https://tools.ietf.org/html/rfc1422.html]), que es una forma codificada en base-64 envuelta con una línea de cabecera y una línea de pie de página:

-----BEGIN CERTIFICATE-----
... (certificate in base64 PEM encoding) ...
-----END CERTIFICATE-----

Cadenas de certificados

Los archivos de Python que contienen certificados pueden contener una secuencia de certificados, a veces llamada cadena de certificados. Esta cadena debería empezar con el certificado específico para el principal que «es» el cliente o servidor, y luego el certificado para el emisor de ese certificado, y luego el certificado para el emisor de ese certificado, y así sucesivamente hasta llegar a un certificado que es auto-firmado, es decir, un certificado que tiene el mismo sujeto y emisor, a veces llamado certificado raíz. Los certificados sólo deben concatenarse en el archivo de certificados. Por ejemplo, supongamos que tenemos una cadena de tres certificados, desde el certificado de nuestro servidor al certificado de la autoridad de certificación que firmó nuestro certificado del servidor, hasta el certificado raíz de la agencia que emitió el certificado de la autoridad de certificación:

-----BEGIN CERTIFICATE-----
... (certificate for your server)...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... (the certificate for the CA)...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... (the root certificate for the CA's issuer)...
-----END CERTIFICATE-----

Certificados CA

Si se requiere la validación del certificado del otro lado de la conexión, se necesita proporcionar un archivo «CA certs», con las cadenas de certificados para cada emisor en el que se está dispuesto a confiar. De nuevo, este archivo sólo contiene estas cadenas concatenadas. Para la validación, Python utilizará la primera cadena que encuentre en el archivo que coincida. El archivo de certificados de la plataforma se puede utilizar llamando a SSLContext.load_default_certs(), esto se hace automáticamente con create_default_context().

Clave y certificado combinados

A menudo la clave privada se almacena en el mismo archivo que el certificado; en este caso, sólo es necesario pasar el parámetro certfile a SSLContext.load_cert_chain() y wrap_socket(). Si la clave privada se almacena con el certificado, debe ir antes del primer certificado de la cadena de certificados:

-----BEGIN RSA PRIVATE KEY-----
... (private key in base64 encoding) ...
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
... (certificate in base64 PEM encoding) ...
-----END CERTIFICATE-----

Certificados auto-firmados

Si va a crear un servidor que proporcione servicios de conexión encriptada SSL, necesitará adquirir un certificado para ese servicio. Hay muchas formas de adquirir los certificados adecuados, como comprar uno a una autoridad de certificación. Otra práctica común es generar un certificado auto-firmado. La forma más sencilla de hacerlo es con el paquete OpenSSL, utilizando algo como lo siguiente:

% openssl req -new -x509 -days 365 -nodes -out cert.pem -keyout cert.pem
Generating a 1024 bit RSA private key
.......++++++
.............................++++++
writing new private key to 'cert.pem'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:MyState
Locality Name (eg, city) []:Some City
Organization Name (eg, company) [Internet Widgits Pty Ltd]:My Organization, Inc.
Organizational Unit Name (eg, section) []:My Group
Common Name (eg, YOUR name) []:myserver.mygroup.myorganization.com
Email Address []:ops@myserver.mygroup.myorganization.com
%

La desventaja de un certificado auto-firmado es que es su propio certificado raíz, y nadie más lo tendrá en su caché de certificados raíz conocidos (y de confianza).

Ejemplos

Pruebas de compatibilidad con SSL

Para comprobar la presencia de soporte SSL en una instalación de Python, el código del usuario debe utilizar el siguiente modismo:

try:
    import ssl
except ImportError:
    pass
else:
    ...  # do something that requires SSL support

Operación del lado del cliente

Este ejemplo crea un contexto SSL con la configuración de seguridad recomendada para los sockets del cliente, incluyendo la verificación automática de certificados:

>>> context = ssl.create_default_context()

Si prefieres ajustar la configuración de seguridad tú mismo, puedes crear un contexto desde cero (pero ten en cuenta que podrías no acertar con la configuración):

>>> context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
>>> context.load_verify_locations("/etc/ssl/certs/ca-bundle.crt")

(este fragmento asume que tu sistema operativo coloca un paquete de todos los certificados CA en /etc/ssl/certs/ca-bundle.crt; si no es así, obtendrá un error y tendrá que ajustar la ubicación)

El protocolo PROTOCOL_TLS_CLIENT configura el contexto para la validación de certificados y la verificación del hostname. verify_mode se establece en CERT_REQUIRED y check_hostname se establece en True. Todos los demás protocolos crean contextos SSL con valores predeterminados inseguros.

Cuando se utiliza el contexto para conectarse a un servidor, CERT_REQUIRED y check_hostname validan el certificado del servidor: se asegura de que el certificado del servidor se ha firmado con uno de los certificados de la CA, se comprueba que la firma es correcta y se verifican otras propiedades como la validez y la identidad del hostname:

>>> conn = context.wrap_socket(socket.socket(socket.AF_INET),
...                            server_hostname="www.python.org")
>>> conn.connect(("www.python.org", 443))

A continuación, puede obtener el certificado:

>>> cert = conn.getpeercert()

La inspección visual muestra que el certificado sí identifica el servicio deseado (es decir, el host HTTPS www.python.org):

>>> pprint.pprint(cert)
{'OCSP': ('http://ocsp.digicert.com',),
 'caIssuers': ('http://cacerts.digicert.com/DigiCertSHA2ExtendedValidationServerCA.crt',),
 'crlDistributionPoints': ('http://crl3.digicert.com/sha2-ev-server-g1.crl',
                           'http://crl4.digicert.com/sha2-ev-server-g1.crl'),
 'issuer': ((('countryName', 'US'),),
            (('organizationName', 'DigiCert Inc'),),
            (('organizationalUnitName', 'www.digicert.com'),),
            (('commonName', 'DigiCert SHA2 Extended Validation Server CA'),)),
 'notAfter': 'Sep  9 12:00:00 2016 GMT',
 'notBefore': 'Sep  5 00:00:00 2014 GMT',
 'serialNumber': '01BB6F00122B177F36CAB49CEA8B6B26',
 'subject': ((('businessCategory', 'Private Organization'),),
             (('1.3.6.1.4.1.311.60.2.1.3', 'US'),),
             (('1.3.6.1.4.1.311.60.2.1.2', 'Delaware'),),
             (('serialNumber', '3359300'),),
             (('streetAddress', '16 Allen Rd'),),
             (('postalCode', '03894-4801'),),
             (('countryName', 'US'),),
             (('stateOrProvinceName', 'NH'),),
             (('localityName', 'Wolfeboro'),),
             (('organizationName', 'Python Software Foundation'),),
             (('commonName', 'www.python.org'),)),
 'subjectAltName': (('DNS', 'www.python.org'),
                    ('DNS', 'python.org'),
                    ('DNS', 'pypi.org'),
                    ('DNS', 'docs.python.org'),
                    ('DNS', 'testpypi.org'),
                    ('DNS', 'bugs.python.org'),
                    ('DNS', 'wiki.python.org'),
                    ('DNS', 'hg.python.org'),
                    ('DNS', 'mail.python.org'),
                    ('DNS', 'packaging.python.org'),
                    ('DNS', 'pythonhosted.org'),
                    ('DNS', 'www.pythonhosted.org'),
                    ('DNS', 'test.pythonhosted.org'),
                    ('DNS', 'us.pycon.org'),
                    ('DNS', 'id.python.org')),
 'version': 3}

Ahora que se ha establecido el canal SSL y se ha verificado el certificado, se puede proceder a hablar con el servidor:

>>> conn.sendall(b"HEAD / HTTP/1.0\r\nHost: linuxfr.org\r\n\r\n")
>>> pprint.pprint(conn.recv(1024).split(b"\r\n"))
[b'HTTP/1.1 200 OK',
 b'Date: Sat, 18 Oct 2014 18:27:20 GMT',
 b'Server: nginx',
 b'Content-Type: text/html; charset=utf-8',
 b'X-Frame-Options: SAMEORIGIN',
 b'Content-Length: 45679',
 b'Accept-Ranges: bytes',
 b'Via: 1.1 varnish',
 b'Age: 2188',
 b'X-Served-By: cache-lcy1134-LCY',
 b'X-Cache: HIT',
 b'X-Cache-Hits: 11',
 b'Vary: Cookie',
 b'Strict-Transport-Security: max-age=63072000; includeSubDomains',
 b'Connection: close',
 b'',
 b'']

Vea la discusión sobre Consideraciones de seguridad más abajo.

Operación del lado del servidor

Para el funcionamiento del servidor, normalmente necesitarás tener un certificado de servidor y una clave privada, cada uno en un archivo. Primero crearás un contexto que contenga la clave y el certificado, para que los clientes puedan comprobar tu autenticidad. Entonces abrirás un socket, lo enlazarás a un puerto, llamarás a listen() en él, y empezarás a esperar a que los clientes se conecten:

import socket, ssl

context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)
context.load_cert_chain(certfile="mycertfile", keyfile="mykeyfile")

bindsocket = socket.socket()
bindsocket.bind(('myaddr.example.com', 10023))
bindsocket.listen(5)

Cuando un cliente se conecta, llamarás a accept() en el socket para obtener el nuevo socket del otro extremo, y utilizarás el método SSLContext.wrap_socket() del contexto para crear un socket SSL del lado del servidor para la conexión:

while True:
    newsocket, fromaddr = bindsocket.accept()
    connstream = context.wrap_socket(newsocket, server_side=True)
    try:
        deal_with_client(connstream)
    finally:
        connstream.shutdown(socket.SHUT_RDWR)
        connstream.close()

Entonces leerás los datos del connstream y harás algo con ellos hasta que hayas terminado con el cliente (o el cliente haya terminado contigo):

def deal_with_client(connstream):
    data = connstream.recv(1024)
    # empty data means the client is finished with us
    while data:
        if not do_something(connstream, data):
            # we'll assume do_something returns False
            # when we're finished with client
            break
        data = connstream.recv(1024)
    # finished with client

Y volver a escuchar nuevas conexiones de clientes (por supuesto, un servidor real probablemente manejaría cada conexión de cliente en un hilo separado, o pondría los sockets en modo no-bloqueo y usaría un bucle de eventos).

Notas sobre los sockets no bloqueantes

Los sockets SSL se comportan de forma ligeramente diferente a los sockets normales en modo no bloqueante. Cuando se trabaja con sockets no bloqueantes, hay varias cosas que hay que tener en cuenta:

La mayoría de los métodos de SSLSocket lanzarán SSLWantWriteError o SSLWantReadError en lugar de BlockingIOError si una operación de E/S se bloquea. SSLWantReadError se lanzará si es necesaria una operación de lectura en el socket subyacente, y SSLWantWriteError para una operación de escritura en el socket subyacente. Tenga en cuenta que los intentos de escribir en un socket SSL pueden requerir leer del socket subyacente primero, y los intentos de leer del socket SSL pueden requerir una escritura previa en el socket subyacente.

Distinto en la versión 3.5: En versiones anteriores de Python, el método SSLSocket.send() devolvía cero en lugar de lanzar SSLWantWriteError o SSLWantReadError.

Llamar a select() le indica que se puede leer (o escribir) en el socket a nivel del SO, pero no implica que haya suficientes datos en la capa superior SSL. Por ejemplo, puede que sólo haya llegado una parte de una trama SSL. Por lo tanto, debe estar preparado para manejar los fallos de SSLSocket.recv() y SSLSocket.send(), y re-intentar después de otra llamada a select().

Por el contrario, dado que la capa SSL tiene su propia estructura, un socket SSL puede tener datos disponibles para leer sin que select() lo sepa. Por lo tanto, debería llamar primero a SSLSocket.recv() para drenar cualquier dato potencialmente disponible, y luego sólo bloquear en una llamada a select() si todavía es necesario.

(por supuesto, se aplican disposiciones similares cuando se utilizan otras primitivas como poll(), o las del módulo selectors)

El handshake SSL en sí mismo será no bloqueante: el método SSLSocket.do_handshake() tiene que ser re-intentado hasta que regrese con éxito. Aquí hay una sinopsis usando select() para esperar la disponibilidad del socket:

while True:
    try:
        sock.do_handshake()
        break
    except ssl.SSLWantReadError:
        select.select([sock], [], [])
    except ssl.SSLWantWriteError:
        select.select([], [sock], [])

Ver también

El módulo asyncio soporta sockets SSL no bloqueantes y proporciona una API de alto nivel. Busca eventos usando el módulo selectors y maneja las excepciones SSLWantWriteError, SSLWantReadError y BlockingIOError. También ejecuta el handshake SSL de forma asíncrona.

Soporte de memoria BIO

Nuevo en la versión 3.5.

Desde que se introdujo el módulo SSL en Python 2.6, la clase SSLSocket ha proporcionado dos áreas de funcionalidad relacionadas pero distintas:

Manejo del protocolo SSL

E/S de red

La API de E/S de red es idéntica a la proporcionada por socket.socket, de la que también hereda SSLSocket. Esto permite que un socket SSL sea utilizado como un reemplazo de un socket normal, haciendo que sea muy fácil añadir soporte SSL a una aplicación existente.

La combinación del manejo del protocolo SSL y la E/S de red suele funcionar bien, pero hay algunos casos en los que no es así. Un ejemplo son los frameworks de E/S asíncronos que quieren utilizar un modelo de multiplexación de E/S diferente al modelo «selección/consulta de un descriptor de archivo» (basado en la preparación) que es asumido por socket.socket y por las rutinas internas de E/S de socket de OpenSSL. Esto es principalmente relevante para plataformas como Windows donde este modelo no es eficiente. Para este propósito, se proporciona una variante de ámbito reducido de SSLSocket llamada SSLObject.

class ssl.SSLObject

Una variante de alcance reducido de SSLSocket que representa una instancia del protocolo SSL que no contiene ningún método de E/S de red. Esta clase suele ser utilizada por los autores de frameworks que quieren implementar E/S asíncrona para SSL a través de búfers de memoria.

Esta clase implementa una interfaz sobre un objeto SSL de bajo nivel como el implementado por OpenSSL. Este objeto captura el estado de una conexión SSL pero no proporciona ninguna E/S de red en sí misma. La E/S debe realizarse a través de objetos «BIO» separados que son la capa de abstracción de E/S de OpenSSL.

Esta clase no tiene un constructor público. Se debe crear una instancia SSLObject utilizando el método wrap_bio(). Este método creará la instancia SSLObject y la vinculará a un par de BIOs. El BIO de entrada se utiliza para pasar los datos de Python a la instancia del protocolo SSL, mientras que el BIO de salida se utiliza para pasar los datos a la inversa.

Los siguientes métodos son disponibles:

context

server_side

server_hostname

session

session_reused

read()

write()

getpeercert()

selected_alpn_protocol()

selected_npn_protocol()

cipher()

shared_ciphers()

compression()

pending()

do_handshake()

verify_client_post_handshake()

unwrap()

get_channel_binding()

version()

En comparación con SSLSocket, este objeto carece de las siguientes características:

Cualquier forma de E/S de red; recv() y send() leen y escriben sólo en los búfers subyacentes de MemoryBIO.

No existe la maquinaria do_handshake_on_connect. Siempre hay que llamar manualmente a do_handshake() para iniciar el handshake.

No hay manejo de suppress_ragged_eofs. Todas las condiciones de fin de archivo que violan el protocolo se reportan a través de la excepción SSLEOFError.

La llamada al método unwrap() no devuelve nada, a diferencia de lo que ocurre con un socket SSL, que devuelve el socket subyacente.

La función callback server_name_callback pasada a SSLContext.set_servername_callback() obtendrá una instancia de SSLObject en lugar de una instancia de SSLSocket como primer parámetro.

Algunas notas relacionadas con el uso de SSLObject:

Toda la E/S en un SSLObject es non-blocking. Esto significa que, por ejemplo, read() lanzará un SSLWantReadError si necesita más datos de los que la BIO entrante tiene disponibles.

No hay una llamada a nivel de módulo wrap_bio() como la que hay para wrap_socket(). Un SSLObject siempre se crea a través de un SSLContext.

Distinto en la versión 3.7: Las instancias SSLObject deben crearse con wrap_bio(). En versiones anteriores, era posible crear instancias directamente. Esto nunca fue documentado ni soportado oficialmente.

Un SSLObject se comunica con el mundo exterior utilizando búfers de memoria. La clase MemoryBIO proporciona un búfer de memoria que puede ser utilizado para este propósito. Envuelve un objeto BIO (Basic IO) de memoria de OpenSSL:

class ssl.MemoryBIO

Un búfer de memoria que se puede utilizar para pasar datos entre Python y una instancia del protocolo SSL.

pending

Retorna el número de bytes que se encuentran actualmente en la memoria búfer.

eof

Un booleano que indica si la memoria BIO es actual en la posición de fin de archivo.

read(n=-1)

Lee hasta n bytes del búfer de memoria. Si n no se especifica o es negativo, se devuelven todos los bytes.

write(buf)

Escribe los bytes de buf en la memoria BIO. El argumento buf debe ser un objeto que soporte el protocolo de búfer.

El valor de retorno es el número de bytes escritos, que siempre es igual a la longitud de buf.

write_eof()

Escribe un marcador EOF en la memoria BIO. Después de llamar a este método, es ilegal llamar a write(). El atributo eof se convertirá en verdadero después de que se hayan leído todos los datos que hay actualmente en el búfer.

Sesión SSL

Nuevo en la versión 3.6.

class ssl.SSLSession

Objeto sesión usado por session.

id

time

timeout

ticket_lifetime_hint

has_ticket

Consideraciones de seguridad

Los mejores valores por defecto

Para el uso en el cliente, si no tiene ningún requisito especial para su política de seguridad, es muy recomendable que utilice la función create_default_context() para crear su contexto SSL. Cargará los certificados CA de confianza del sistema, habilitará la validación de certificados y la comprobación del hostname, e intentará elegir una configuración de protocolo y cifrado razonablemente segura.

Por ejemplo, así es como se utiliza la clase smtplib.SMTP para crear una conexión segura y de confianza con un servidor SMTP:

>>> import ssl, smtplib
>>> smtp = smtplib.SMTP("mail.python.org", port=587)
>>> context = ssl.create_default_context()
>>> smtp.starttls(context=context)
(220, b'2.0.0 Ready to start TLS')

Si se necesita un certificado de cliente para la conexión, se puede añadir con SSLContext.load_cert_chain().

Por el contrario, si crea el contexto SSL llamando usted mismo al constructor SSLContext, no tendrá activada por defecto la validación de certificados ni la comprobación de hostname. Si lo hace, lea los párrafos siguientes para conseguir un buen nivel de seguridad.

Ajustes manuales

Verificación de certificados

Cuando se llama al constructor de SSLContext directamente, CERT_NONE es el valor por defecto. Dado que no autentifica al otro peer, puede ser inseguro, especialmente en modo cliente, donde la mayoría de las veces se quiere asegurar la autenticidad del servidor con el que se está hablando. Por lo tanto, cuando se está en modo cliente, es muy recomendable utilizar CERT_REQUIRED. Sin embargo, no es suficiente por sí mismo; también hay que comprobar que el certificado del servidor, que se puede obtener llamando a SSLSocket.getpeercert(), coincide con el servicio deseado. Para muchos protocolos y aplicaciones, el servicio puede ser identificado por el hostname; en este caso, se puede utilizar la función match_hostname(). Esta comprobación común se realiza automáticamente cuando SSLContext.check_hostname está activado.

Distinto en la versión 3.7: Las hostname matchings son ahora realizadas por OpenSSL. Python ya no utiliza match_hostname().

En el modo servidor, si quiere autenticar a sus clientes utilizando la capa SSL (en lugar de utilizar un mecanismo de autenticación de nivel superior), también tendrá que especificar CERT_REQUIRED y comprobar de forma similar el certificado del cliente.

Versiones del protocolo

Las versiones 2 y 3 de SSL se consideran inseguras y, por lo tanto, su uso es peligroso. Si desea la máxima compatibilidad entre clientes y servidores, se recomienda utilizar PROTOCOL_TLS_CLIENT o PROTOCOL_TLS_SERVER como versión del protocolo. SSLv2 y SSLv3 están desactivados por defecto.

>>> client_context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
>>> client_context.options |= ssl.OP_NO_TLSv1
>>> client_context.options |= ssl.OP_NO_TLSv1_1

El contexto SSL creado anteriormente sólo permitirá conexiones TLSv1.2 y posteriores (si su sistema lo soporta) a un servidor. PROTOCOL_TLS_CLIENT implica la validación del certificado y la comprobación del nombre de host por defecto. Tiene que cargar los certificados en el contexto.

Selección de cifrado

Si tienes requisitos de seguridad avanzados, es posible ajustar los cifrados habilitados al negociar una sesión SSL mediante el método SSLContext.set_ciphers(). A partir de Python 3.2.3, el módulo ssl deshabilita ciertos cifrados débiles por defecto, pero es posible que quieras restringir más la elección del cifrado. Asegúrese de leer la documentación de OpenSSL sobre el formato de la lista de cifrado [https://www.openssl.org/docs/manmaster/man1/ciphers.html#CIPHER-LIST-FORMAT]. Si quiere comprobar qué cifrados están habilitados por una determinada lista de cifrado, utilice SSLContext.get_ciphers() o el comando openssl ciphers en su sistema.

Multiprocesamiento

Si utiliza este módulo como parte de una aplicación multiproceso (utilizando, por ejemplo, los módulos multiprocessing o concurrent.futures), tenga en cuenta que el generador de números aleatorios interno de OpenSSL no maneja adecuadamente los procesos bifurcados. Las aplicaciones deben cambiar el estado del PRNG del proceso padre si utilizan cualquier función de SSL con os.fork(). Cualquier llamada exitosa de RAND_add(), RAND_bytes() o RAND_pseudo_bytes() es suficiente.

TLS 1.3

Nuevo en la versión 3.7.

Python tiene soporte provisional y experimental para TLS 1.3 con OpenSSL 1.1.1. El nuevo protocolo se comporta de forma ligeramente diferente a la versión anterior de TLS/SSL. Algunas de las nuevas características de TLS 1.3 aún no están disponibles.

TLS 1.3 utiliza un conjunto disjunto de suites de cifrado. Todas las suites de cifrado AES-GCM y ChaCha20 están habilitadas por defecto. El método SSLContext.set_ciphers() aún no puede habilitar o deshabilitar ningún cifrado de TLS 1.3, pero SSLContext.get_ciphers() los devuelve.

Los tickets de sesión ya no se envían como parte del handshake inicial y se manejan de forma diferente. SSLSocket.session y SSLSession no son compatibles con TLS 1.3.

Los certificados del lado del cliente ya no se verifican durante el handshake inicial. Un servidor puede solicitar un certificado en cualquier momento. Los clientes procesan las solicitudes de certificados mientras envían o reciben datos de la aplicación desde el servidor.

Las funciones de TLS 1.3, como los datos anticipados, la solicitud de certificado de cliente TLS diferida, la configuración del algoritmo de firma y la repetición de claves, aún no son compatibles.

Soporte LibreSSL

LibreSSL es un fork de OpenSSL 1.0.1. El módulo ssl tiene un soporte limitado para LibreSSL. Algunas características no están disponibles cuando el módulo ssl se compila con LibreSSL.

LibreSSL >= 2.6.1 ya no soporta NPN. Los métodos SSLContext.set_npn_protocols() y SSLSocket.selected_npn_protocol() no están disponibles.

SSLContext.set_default_verify_paths() ignora las variables de entorno SSL_CERT_FILE y SSL_CERT_PATH aunque get_default_verify_paths() aún los reporta.

Ver también

Clase socket.socket

Documentación de la clase socket subyacente

SSL/TLS Strong Encryption: An Introduction [https://httpd.apache.org/docs/trunk/en/ssl/ssl_intro.html]

Introducción de la documentación del servidor HTTP Apache

RFC 1422: Privacy Enhancement for Internet Electronic Mail: Part II: Certificate-Based Key Management [https://tools.ietf.org/html/rfc1422.html]

Steve Kent

RFC 4086: Randomness Requirements for Security [https://tools.ietf.org/html/rfc4086.html]

Donald E., Jeffrey I. Schiller

RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile [https://tools.ietf.org/html/rfc5280.html]

D. Cooper

RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2 [https://tools.ietf.org/html/rfc5246.html]

T. Dierks et. al.

RFC 6066: Transport Layer Security (TLS) Extensions [https://tools.ietf.org/html/rfc6066.html]

D. Eastlake

IANA TLS: Transport Layer Security (TLS) Parameters [https://www.iana.org/assignments/tls-parameters/tls-parameters.xml]

IANA

RFC 7525: Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) [https://tools.ietf.org/html/rfc7525.html]

IETF

Mozilla’s Server Side TLS recommendations [https://wiki.mozilla.org/Security/Server_Side_TLS]

Mozilla

select — Esperando la finalización de E/S

Este módulo proporciona acceso a las funciones select() y poll() disponibles en la mayoría de los sistemas operativos, devpoll() disponible en Solaris y derivados, epoll() disponible en Linux 2.5+ y kqueue() disponible en la mayoría de BSD. Tenga en cuenta que en Windows, solo funciona para sockets; en otros sistemas operativos, también funciona para otros tipos de archivos (en particular, en Unix, funciona en tuberías). No se puede usar en archivos normales para determinar si un archivo ha crecido desde la última lectura.

Nota

El módulo selectors permite la multiplexación de E/S de alto nivel y eficiente, construida sobre las primitivas del módulo select. Se alienta a los usuarios a utilizar el módulo selectors en su lugar, a menos que quieran un control preciso sobre las primitivas utilizadas de nivel OS.

El módulo define lo siguiente:

exception select.error

Un alias en desuso de OSError.

Distinto en la versión 3.3: Siguiente PEP 3151 [https://www.python.org/dev/peps/pep-3151], esta clase se convirtió en un alias de OSError.

select.devpoll()

(Solo se admite en Solaris y derivados). Retorna un objeto de sondeo /dev/poll; vea la sección Objetos de sondeo /dev/poll a continuación para conocer los métodos admitidos por los objetos devpoll.

Los objetos devpoll() están vinculados a la cantidad de descriptores de archivo permitidos en el momento de la creación de instancias. Si su programa reduce este valor, devpoll() fallará. Si su programa aumenta este valor, devpoll() puede retornar una lista incompleta de descriptores de archivos activos.

El nuevo descriptor del archivo es non-inheritable.

Nuevo en la versión 3.3.

Distinto en la versión 3.4: El nuevo descriptor de archivo ahora no es heredable.

select.epoll(sizehint=-1, flags=0)

(Solo se admite en Linux 2.5.44 y versiones posteriores). Retorna un objeto de sondeo de borde, que se puede usar como interfaz de disparo de nivel o de borde para eventos de E/S.

sizehint informa a epoll sobre el número esperado de eventos a ser registrados. Debe ser positivo o -1 para usar el valor predeterminado. Solo se usa en sistemas más antiguos donde epoll_create1() no está disponible; de lo contrario no tiene ningún efecto (aunque su valor aún está marcado).

flags está en desuso y se ignora por completo. Sin embargo, cuando se proporciona, su valor debe ser 0 o select.EPOLL_CLOEXEC, de lo contrario, se generará OSError.

Consulte la sección Objetos de sondeo de Edge y Level Trigger (epoll) a continuación para conocer los métodos admitidos por los objetos epolling.

Los objetos epoll admiten el protocolo context management: cuando se usa en una declaración with, el nuevo descriptor de archivo se cierra automáticamente al final del bloque.

El nuevo descriptor del archivo es non-inheritable.

Distinto en la versión 3.3: Se agregó el parámetro flags.

Distinto en la versión 3.4: Se agregó soporte para la declaración with. El nuevo descriptor de archivo ahora no es heredable.

Obsoleto desde la versión 3.4: El parámetro flags. select.EPOLL_CLOEXEC se usa por defecto ahora. Use os.set_inheritable() para hacer que el descriptor de archivo sea heredable.

select.poll()

(No es compatible con todos los sistemas operativos). Retorna un objeto de sondeo, que admite registrar y anular el registro de descriptores de archivo, y luego sondearlos para eventos de I/O; vea la sección Sondeo de objetos a continuación para conocer los métodos admitidos por los objetos de sondeo.

select.kqueue()

(Solo se admite en BSD). Retorna un objeto de cola del kernel; vea la sección Objetos Kqueue a continuación para conocer los métodos admitidos por los objetos kqueue.

El nuevo descriptor del archivo es non-inheritable.

Distinto en la versión 3.4: El nuevo descriptor de archivo ahora no es heredable.

select.kevent(ident, filter=KQ_FILTER_READ, flags=KQ_EV_ADD, fflags=0, data=0, udata=0)

(Solo se admite en BSD). Retorna un objeto de evento del kernel; vea la sección Objetos Kevent a continuación para conocer los métodos admitidos por los objetos kevent.

select.select(rlist, wlist, xlist[, timeout])

Esta es una interfaz sencilla para la llamada al sistema Unix select(). Los primeros tres argumentos son iterables de “objetos en espera”: enteros que representan descriptores de archivos u objetos con un método sin parámetros llamado fileno() que retorna un entero de este tipo:

rlist: espera hasta que esté listo para leer

wlist: espera hasta que esté listo para escribir

xlist: espera una «condición excepcional» (consulte la página del manual para ver lo que su sistema considera tal condición)

Se permiten iterables vacíos, pero la aceptación de tres iterables vacíos depende de la plataforma. (Se sabe que funciona en Unix pero no en Windows). El argumento opcional timeout especifica un tiempo de espera como un número de punto flotante en segundos. Cuando se omite el argumento timeout, la función se bloquea hasta que al menos un descriptor de archivo esté listo. Un valor de tiempo de espera de cero especifica un sondeo y nunca se bloquea.

El valor de retorno es un triple de listas de objetos que están listos: subconjuntos de los primeros tres argumentos. Cuando se alcanza el tiempo de espera sin que esté listo un descriptor de archivo, se retornan tres listas vacías.

Entre los tipos de objetos aceptables en los iterables se encuentran Python objetos de archivo (por ejemplo, sys.stdin, u objetos retornados por open() o os.popen() ), objetos de socket retornados por socket.socket(). También puede definir una clase wrapper usted mismo, siempre que tenga un método fileno() apropiado (que realmente retorne un descriptor de archivo, no solo un entero aleatorio).

Nota

Los objetos de archivo en Windows no son admisibles, pero los sockets sí. En Windows, la función subyacente select() es proporcionada por la biblioteca WinSock, y no maneja los descriptores de archivo que no se originan en WinSock.

Distinto en la versión 3.5: La función ahora se vuelve a intentar con un tiempo de espera (timeout) recalculado cuando se interrumpe por una señal, excepto si el controlador de señal genera una excepción (ver PEP 475 [https://www.python.org/dev/peps/pep-0475] para la justificación), en lugar de generar InterruptedError.

select.PIPE_BUF

El número mínimo de bytes que se pueden escribir sin bloquear en una tubería cuando la tubería ha sido reportada como lista para escribir por select(), poll() u otra interfaz en este módulo. Esto no se aplica a otro tipo de objetos similares a archivos, como los sockets.

Este valor es garantizado por POSIX para ser menor a 512.

Availability: Unix

Nuevo en la versión 3.2.

Objetos de sondeo /dev/poll

Solaris y derivados tienen /dev/poll. Mientras que select() es O(descriptor de archivo más alto) y poll() es O (número de descriptores de archivo), /dev/poll es O(descriptores de archivo activos).

El comportamiento /dev/poll está muy cerca del estándar objeto poll().

devpoll.close()

Cierra el descriptor de archivo del objeto de sondeo.

Nuevo en la versión 3.4.

devpoll.closed

True si el objeto de sondeo está cerrado.

Nuevo en la versión 3.4.

devpoll.fileno()

Retorna el número de descriptor de archivo del objeto de sondeo.

Nuevo en la versión 3.4.

devpoll.register(fd[, eventmask])

Registra un descriptor de archivo con el objeto de sondeo. Las futuras llamadas al método poll() comprobarán si el descriptor del archivo tiene algún evento I/O pendiente. fd puede ser un entero o un objeto con un método fileno() que retorna un entero. Los objetos de archivo implementan Fileno(), por lo que también pueden usarse como argumento.

eventmask es una máscara de bits opcional que describe el tipo de eventos que desea verificar. Las constantes son las mismas que con el objeto poll(). El valor predeterminado es una combinación de las constantes POLLIN, POLLPRI y POLLOUT.

Advertencia

Registra un descriptor de archivo que ya está registrado no es un error, pero el resultado no está definido. La acción apropiada es anular el registro o modificarlo primero. Esta es una diferencia importante en comparación con poll().

devpoll.modify(fd[, eventmask])

Este método hace un unregister() seguido de a register(). Es (un poco) más eficiente que hacer lo mismo explícitamente.

devpoll.unregister(fd)

Elimina un descriptor de archivo que está siendo rastreado por un objeto de sondeo. Al igual que el método register(), fd puede ser un entero o un objeto con un método fileno() que retorna un entero.

Al intentar eliminar un descriptor de archivo que nunca se registró se ignora de forma segura.

devpoll.poll([timeout])

Sondea el conjunto de descriptores de archivos registrados y retorna una lista posiblemente vacía que contiene (fd, event) 2 tuplas para los descriptores que tienen eventos o errores que informar. fd es el descriptor de archivo, y event es una máscara de bits con bits establecidos para los eventos informados para ese descriptor — POLLIN para la entrada en espera, POLLOUT para indicar que el descriptor puede ser escrito, y así sucesivamente. Una lista vacía indica que se agotó el tiempo de espera de la llamada y que ningún descriptor de archivos tuvo ningún evento que informar. Si se da timeout, especifica el período de tiempo en milisegundos que el sistema esperará por los eventos antes de regresar. Si se omite timeout, es -1 o es None, la llamada se bloqueará hasta que haya un evento para este objeto de encuesta.

Distinto en la versión 3.5: La función ahora se vuelve a intentar con un tiempo de espera (timeout) recalculado cuando se interrumpe por una señal, excepto si el controlador de señal genera una excepción (ver PEP 475 [https://www.python.org/dev/peps/pep-0475] para la justificación), en lugar de generar InterruptedError.

Objetos de sondeo de Edge y Level Trigger (epoll)

https://linux.die.net/man/4/epoll

eventmask

Constante

Significado

EPOLLIN

Disponible para lectura

EPOLLOUT

Disponible para escritura

EPOLLPRI

Urgente para lectura

EPOLLERR

La condición de error ocurrió en la asociación. fd

EPOLLHUP

Se colgó en la asociación. fd

EPOLLET

Establece el comportamiento en Edge Trigger, el valor predeterminado es Level Trigger

EPOLLONESHOT

Establece el comportamiento en one-shot. Después de que se retira un evento, el fd se deshabilita internamente

EPOLLEXCLUSIVE

Despierta solo un objeto epoll cuando el fd asociado tiene un evento. El valor predeterminado (si este flag no está configurado) es activar todos los objetos epoll que sondean en un fd.

EPOLLRDHUP

Socket de flujo de conexión cerrada por pares o apagado escribiendo la mitad de la conexión.

EPOLLRDNORM

Equivalente a EPOLLIN

EPOLLRDBAND

La banda de datos de prioridad se puede leer.

EPOLLWRNORM

Equivalente a EPOLLOUT

EPOLLWRBAND

Se pueden escribir datos de prioridad.

EPOLLMSG

Ignorado.

Nuevo en la versión 3.6: EPOLLEXCLUSIVE fue agregado. Solo es compatible con Linux Kernel 4.5 o posterior.

epoll.close()

Cierra el descriptor del archivo de control del objeto epoll.

epoll.closed

True si el objeto epoll está cerrado.

epoll.fileno()

Retorna el número de descriptor de archivo del control fd.

epoll.fromfd(fd)

Crea un objeto epoll a partir de un descriptor de archivo dado.

epoll.register(fd[, eventmask])

Registra un descriptor fd con el objeto epoll.

epoll.modify(fd, eventmask)

Modifica un descriptor de archivo registrado.

epoll.unregister(fd)

Elimina un descriptor de archivo registrado del objeto epoll.

Distinto en la versión 3.9: El método ya no ignora el error EBADF.

epoll.poll(timeout=None, maxevents=-1)

Espera los eventos. tiempo de espera (timeout) en segundos (float)

Distinto en la versión 3.5: La función ahora se vuelve a intentar con un tiempo de espera (timeout) recalculado cuando se interrumpe por una señal, excepto si el controlador de señal genera una excepción (ver PEP 475 [https://www.python.org/dev/peps/pep-0475] para la justificación), en lugar de generar InterruptedError.

Sondeo de objetos

La llamada al sistema: poll(), compatible con la mayoría de los sistemas Unix, proporciona una mejor escalabilidad para los servidores de red que dan servicio a muchos, muchos clientes al mismo tiempo. poll() escala mejor porque la llamada al sistema solo requiere enumerar los descriptores de archivo de interés, mientras que select() construye un mapa de bits, activa bits para los fds de interés, y luego todo el mapa de bits debe escanearse linealmente nuevamente. select() es O (descriptor de archivo más alto), mientras que poll() es O(número de descriptores de archivo).

poll.register(fd[, eventmask])

Registra un descriptor de archivo con el objeto de sondeo. Las futuras llamadas al método poll() comprobarán si el descriptor del archivo tiene algún evento I/O pendiente. fd puede ser un entero o un objeto con un método fileno() que retorna un entero. Los objetos de archivo implementan Fileno(), por lo que también pueden usarse como argumento.

eventmask es una máscara de bits opcional que describe el tipo de eventos que se desea verificar y puede ser una combinación de las constantes POLLIN, POLLPRI, y POLLOUT, descrito en la mesa de abajo. Si no se especifica, el valor predeterminado utilizado verificará los 3 tipos de eventos.

Constante

Significado

POLLIN

Hay datos para leer

POLLPRI

Hay datos urgentes para leer

POLLOUT

Lista para la salida: la escritura no bloqueará

POLLERR

Condición de error de algún tipo

POLLHUP

Colgado

POLLRDHUP

Socket de flujo de conexión cerrada por pares, o apagado escribiendo la mitad de la conexión

POLLNVAL

Solicitud no válida: descriptor no abierto

Al registrar un descriptor de archivo que ya está registrado no es un error y tiene el mismo efecto que registrar el descriptor exactamente una vez.

poll.modify(fd, eventmask)

Modifica un fd ya registrado. Esto tiene el mismo efecto que register(fd, eventmask). Si se intenta modificar un descriptor de archivo que nunca se registró, se genera una excepción OSError con errno ENOENT.

poll.unregister(fd)

Elimina un descriptor de archivo que está siendo rastreado por un objeto de sondeo. Al igual que el método register(), fd puede ser un entero o un objeto con un método fileno() que retorna un entero.

Intenta eliminar un descriptor de archivo que nunca se registró provoca una excepción KeyError.

poll.poll([timeout])

Sondea el conjunto de descriptores de archivos registrados y retorna una lista posiblemente vacía que contiene (fd, event) y 2 tuplas para los descriptores que tienen eventos o errores que informar. fd es el descriptor de archivo, y event es una máscara de bits con bits establecidos para los eventos informados para ese descriptor — POLLIN para la entrada en espera, POLLOUT para indicar que el descriptor puede ser escrito, y así sucesivamente. Una lista vacía indica que se agotó el tiempo de espera de la llamada y que ningún descriptor de archivos tuvo ningún evento que informar. Si se da timeout , especifica el período de tiempo en milisegundos que el sistema esperará por los eventos antes de regresar. Si se omite timeout, es negativo, o None, la llamada se bloqueará hasta que haya un evento para este objeto de encuesta.

Distinto en la versión 3.5: La función ahora se vuelve a intentar con un tiempo de espera (timeout) recalculado cuando se interrumpe por una señal, excepto si el controlador de señal genera una excepción (ver PEP 475 [https://www.python.org/dev/peps/pep-0475] para la justificación), en lugar de generar InterruptedError.

Objetos Kqueue

kqueue.close()

Cierra el descriptor del archivo de control del objeto kqueue.

kqueue.closed

True si el objeto kqueue está cerrado.

kqueue.fileno()

Retorna el número de descriptor de archivo del control fd.

kqueue.fromfd(fd)

Crea un objeto kqueue a partir de un descriptor de archivo dado.

kqueue.control(changelist, max_events[, timeout]) → eventlist

Interfaz de bajo nivel para kevent

la lista de cambios (changelist) debe ser iterable de objetos kevent o None

max_events debe ser 0 o un entero positivo

tiempo de espera (timeout) en segundos (posible con floats); el valor predeterminado es None, para esperar para siempre

Distinto en la versión 3.5: La función ahora se vuelve a intentar con un tiempo de espera (timeout) recalculado cuando se interrumpe por una señal, excepto si el controlador de señal genera una excepción (ver PEP 475 [https://www.python.org/dev/peps/pep-0475] para la justificación), en lugar de generar InterruptedError.

Objetos Kevent

https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2

kevent.ident

Valor utilizado para identificar el evento. La interpretación depende del filtro, pero generalmente es el descriptor de archivo. En el constructor, ident puede ser un int o un objeto con un método fileno(). kevent almacena el entero internamente.

kevent.filter

Nombre del filtro del kernel.

Constante

Significado

KQ_FILTER_READ

Toma un descriptor y retorna cada vez que hay datos disponibles para leer

KQ_FILTER_WRITE

Toma un descriptor y retorna cada vez que hay datos disponibles para escribir

KQ_FILTER_AIO

Solicitudes de AIO

KQ_FILTER_VNODE

Retorna cuando ocurre uno o más de los eventos solicitados observados en fflag

KQ_FILTER_PROC

Vigila los eventos en un id de proceso

KQ_FILTER_NETDEV

Watch for events on a network device [not available on macOS]

KQ_FILTER_SIGNAL

Retorna cada vez que la señal observada se entrega al proceso

KQ_FILTER_TIMER

Establece un temporizador arbitrario

kevent.flags

Acción de filtro.

Constante

Significado

KQ_EV_ADD

Agrega o modifica un evento

KQ_EV_DELETE

Elimina un evento de la cola

KQ_EV_ENABLE

Permitscontrol() para retornar el evento

KQ_EV_DISABLE

Disablesevent

KQ_EV_ONESHOT

Elimina evento después de la primera aparición

KQ_EV_CLEAR

Restablece el estado después de recuperar un evento

KQ_EV_SYSFLAGS

evento interno

KQ_EV_FLAG1

evento interno

KQ_EV_EOF

Filtrar la condición específica de EOF

KQ_EV_ERROR

Ver valores de retorno

kevent.fflags

Filtrar flags específicas.

KQ_FILTER_READ y KQ_FILTER_WRITE bandera de filtro:

Constante

Significado

KQ_NOTE_LOWAT

marca de agua baja de un socket buffer

KQ_FILTER_VNODE bandera de filtro:

Constante

Significado

KQ_NOTE_DELETE

unlink() fue llamado

KQ_NOTE_WRITE

una escritura ha ocurrido

KQ_NOTE_EXTEND

el archivo fue extendido

KQ_NOTE_ATTRIB

un atributo fue cambiado

KQ_NOTE_LINK

el recuento de enlaces ha cambiado

KQ_NOTE_RENAME

el archivo fue renombrado

KQ_NOTE_REVOKE

se revocó el acceso al archivo

KQ_FILTER_PROC bandera de filtro:

Constante

Significado

KQ_NOTE_EXIT

el proceso ha terminado (exited)

KQ_NOTE_FORK

el proceso ha llamado a fork()

KQ_NOTE_EXEC

el proceso ha ejecutado un nuevo proceso

KQ_NOTE_PCTRLMASK

flag de filtro interno

KQ_NOTE_PDATAMASK

flag de filtro interno

KQ_NOTE_TRACK

sigue un proceso a través de fork()

KQ_NOTE_CHILD

retornado en el proceso hijo para NOTE_TRACK

KQ_NOTE_TRACKERR

incapaz de adjuntar a un proceso hijo

KQ_FILTER_NETDEV filter flags (not available on macOS):

Constante

Significado

KQ_NOTE_LINKUP

el enlace está funcionando

KQ_NOTE_LINKDOWN

el enlace está caído

KQ_NOTE_LINKINV

el estado del enlace es invalido

kevent.data

Filtrar datos específicos.

kevent.udata

Valor definido por el usuario.

selectors — Multiplexación de E/S de alto nivel

Nuevo en la versión 3.4.

Código fuente: Lib/selectors.py [https://github.com/python/cpython/tree/3.9/Lib/selectors.py]

Introducción

Este módulo permite multiplexación de E/S eficiente y de alto nivel, basada en los primitivos del módulo select. Se recomienda a los usuarios utilizar este módulo en su lugar, a menos que deseen un control preciso sobre los primitivos a nivel de sistema operativo utilizados.

Define una clase base abstracta BaseSelector, junto con varias implementaciones concretas (KqueueSelector, EpollSelector…), que se pueden utilizar para esperar la notificación de disponibilidad para E/S en varios objetos de archivo. De aquí en adelante, «objeto de archivo» hace referencia a cualquier objeto con un método fileno() o un descriptor de archivo sin procesar. Véase file object.

DefaultSelector es un alias de la implementación más eficiente disponible en la plataforma actual: esta debería ser la opción predeterminada para la mayoría de los usuarios.

Nota

El tipo de objetos de archivo admitidos depende de la plataforma: en Windows, se admiten sockets, pero no pipes, mientras que en Unix, ambos son compatibles (también se pueden admitir algunos otros tipos, como FIFOs o dispositivos de archivo especiales).

Ver también

select

Módulo de multiplexación de E/S de bajo nivel.

Clases

Jerarquía de clases:

BaseSelector
+-- SelectSelector
+-- PollSelector
+-- EpollSelector
+-- DevpollSelector
+-- KqueueSelector

De aquí en adelante, events es una máscara bit a bit que indica qué eventos de E/S se deben esperar en un objeto de archivo determinado. Puede ser cualquier combinación de las siguientes constantes de módulo:

Constante

Significado

EVENT_READ

Disponible para lectura

EVENT_WRITE

Disponible para escritura

class selectors.SelectorKey

La clase SelectorKey es una namedtuple que se utiliza para asociar un objeto de archivo a su descriptor de archivo subyacente, máscara de evento seleccionada y datos adjuntos. Es retornada por varios métodos BaseSelector.

fileobj

Objeto de archivo registrado.

fd

Descriptor de archivo subyacente.

events

Eventos que se deben esperar en este objeto de archivo.

data

Datos opacos opcionales asociados a este objeto de archivo: por ejemplo, podría usarse para almacenar un ID de sesión por cliente.

class selectors.BaseSelector

Un BaseSelector se usa para esperar a que el evento de E/S esté listo en varios objetos de archivo. Admite el registro y la cancelación del registro de secuencias de archivos y un método para esperar eventos de E/S en esas secuencias, con un tiempo de espera opcional. Es una clase base abstracta, por lo que no se puede crear una instancia. Use DefaultSelector en su lugar, o un SelectSelector, KqueueSelector, etc. si deseas usar específicamente una implementación y su plataforma la admite. BaseSelector y sus implementaciones concretas soportan el protocolo context manager.

abstractmethod register(fileobj, events, data=None)

Registra un objeto de archivo para su selección y lo monitoriza en busca de eventos de E/S.

fileobj es el objeto de archivo a monitorear. Puede ser un descriptor de archivo de tipo entero o un objeto con un método fileno(). events es una máscara bit a bit de eventos para monitorear. data es un objeto opaco.

Esto retorna una nueva instancia SelectorKey, o lanza un ValueError en caso de una máscara de evento o un descriptor de archivo no válidos, o KeyError si el objeto de archivo ya está registrado.

abstractmethod unregister(fileobj)

Anula el registro de un objeto de archivo de la selección y lo elimina del monitoreo. Se anulará el registro de un objeto de archivo antes de cerrarlo.

fileobj debe ser un objeto de archivo previamente registrado.

Esto retorna la instancia SelectorKey asociada, o lanza un KeyError si fileobj no está registrado. Se lanzará un ValueError si fileobj no es válido (por ejemplo, no tiene el método fileno () o su método fileno () tiene un valor de retorno no válido).

modify(fileobj, events, data=None)

Cambia los eventos monitorizados de un objeto de archivo registrado o los datos adjuntos.

Esto es equivalente a BaseSelector.unregister(fileobj)() seguido de BaseSelector.register(fileobj, events, data)(), excepto que se puede implementar de manera más eficiente.

Esto retorna una nueva instancia de SelectorKey, o lanza un ValueError en caso de una máscara de evento o un descriptor de archivo no válidos, o KeyError si el objeto de archivo no está registrado.

abstractmethod select(timeout=None)

Espera hasta que algunos objetos de archivo registrados estén listos o el tiempo de espera expire.

Si timeout > 0, esto especifica el tiempo máximo de espera, en segundos. Si timeout <= 0, la llamada no se bloqueará y reportará los objetos de archivo actualmente listos. Si timeout es None, la llamada se bloqueará hasta que un objeto de archivo monitorizado esté listo.

Retorna una lista de tuplas (key, events), una por cada objeto de archivo listo.

key es la instancia SelectorKey correspondiente a un objeto de archivo listo. events es una máscara de bits de eventos listos en este objeto de archivo.

Nota

Este método puede regresar antes de que cualquier objeto de archivo esté listo o haya transcurrido el tiempo de espera si el proceso actual recibe una señal: en este caso, se retornará una lista vacía.

Distinto en la versión 3.5: El selector ahora se reintenta con un tiempo de espera recalculado cuando es interrumpido por una señal si el gestor de señales no lanzó una excepción (ver PEP 475 [https://www.python.org/dev/peps/pep-0475] para la justificación), en lugar de retornar una lista vacía de eventos antes del tiempo de espera.

close()

Cierra el selector.

Se debe llamar para asegurarse de que se libera cualquier recurso subyacente. El selector no se utilizará una vez cerrado.

get_key(fileobj)

Retorna la clave asociada con un objeto de archivo registrado.

Esto retorna la instancia SelectorKey asociada a este objeto de archivo, o lanza un KeyError si el objeto de archivo no está registrado.

abstractmethod get_map()

Retorna un mapeo asociando objetos de archivo a las llaves del selector.

Retorna una instancia de Mapping mapeando objetos de archivo registrados a su instancia SelectorKey asociada

class selectors.DefaultSelector

La clase de selector predeterminada, utiliza la implementación más eficiente disponible en la plataforma actual. Esta debería ser la opción predeterminada para la mayoría de los usuarios.

class selectors.SelectSelector

Selector basado en select.select().

class selectors.PollSelector

Selector basado en select.poll().

class selectors.EpollSelector

Selector basado en select.epoll().

fileno()

Esto retorna el descriptor de archivo utilizado por el objeto select.epoll() subyacente.

class selectors.DevpollSelector

Selector basado en select.devpoll().

fileno()

Esto retorna el descriptor de archivo utilizado por el objeto select.devpoll() subyacente.

Nuevo en la versión 3.5.

class selectors.KqueueSelector

Selector basado en select.kqueue().

fileno()

Esto retorna el descriptor de archivo utilizado por el objeto select.kqueue() subyacente.

Ejemplos

Aquí hay una implementación simple de un servidor de eco:

import selectors
import socket

sel = selectors.DefaultSelector()

def accept(sock, mask):
    conn, addr = sock.accept()  # Should be ready
    print('accepted', conn, 'from', addr)
    conn.setblocking(False)
    sel.register(conn, selectors.EVENT_READ, read)

def read(conn, mask):
    data = conn.recv(1000)  # Should be ready
    if data:
        print('echoing', repr(data), 'to', conn)
        conn.send(data)  # Hope it won't block
    else:
        print('closing', conn)
        sel.unregister(conn)
        conn.close()

sock = socket.socket()
sock.bind(('localhost', 1234))
sock.listen(100)
sock.setblocking(False)
sel.register(sock, selectors.EVENT_READ, accept)

while True:
    events = sel.select()
    for key, mask in events:
        callback = key.data
        callback(key.fileobj, mask)

signal — Establece gestores para eventos asíncronos

Este módulo proporciona mecanismos para usar gestores de señales en Python.

Reglas generales

La función signal.signal() permite definir gestores personalizados que serán ejecutados cuando una señal es recibida. Un pequeño número de gestores por defecto son instalados: SIGPIPE es ignorada (por lo que los errores de escritura en tuberías y sockets se pueden informar como excepciones ordinarias de Python) y SIGINT es trasladada en una excepción KeyboardInterrupt si el proceso padre no lo ha cambiado.

El gestor para una señal en particular, una vez establecido, continua instalado hasta que se resetea explícitamente (Python emula el estilo de interfaz BSD independientemente de la implementación subyacente), con la excepción del gestor para SIGCHLD, que sigue la implementación subyacente.

Ejecución de los gestores de señales de Python

Un gestor de señales de Python no se ejecuta dentro del gestor de señales de bajo nivel (C). En vez de eso, el gestor de señales de bajo nivel establece una señal que le dice al virtual machine que ejecute la correspondiente señal del gestor de Python en una posición posterior (por ejemplo en la próxima instrucción bytecode). Esto tiene consecuencias:

Tiene poco sentido detectar errores sincrónicos como SIGFPE o SIGSEGV que son causados por una operación no válida en código C. Python retornará desde el gestor de señales a código C, que es probable que extienda la misma señal otra vez, ocasionando que Python se cuelgue aparentemente. Desde Python 3.3 en adelante, puedes usar el módulo faulthandler para reportar errores síncronos.

Un cálculo de larga duración implementado exclusivamente en C (como una coincidencia de expresiones regulares en un gran cuerpo de texto) puede funcionar interrumpidamente durante una cantidad arbitraria de tiempo, independientemente de las señales recibidas. Los gestores de señales de Python serán llamados cuando el cálculo finalice.

If the handler raises an exception, it will be raised «out of thin air» in the main thread. See the note below for a discussion.

Señales e hilos

Los gestores de señales de Python se ejecutan siempre en el hilo principal de Python, incluso si la señal fue recibida desde otro hilo. Esto significa que las señales no pueden ser usadas como un medio de comunicación entre hilos. Puedes usar las primitivas de sincronización desde el módulo threading en su lugar.

Además, solo el hilo principal puede configurar un nuevo gestor de señal.

Contenidos del módulo

Distinto en la versión 3.5: señal (SIG*), gestor (SIG_DFL, SIG_IGN) y “sigmask” (SIG_BLOCK, SIG_UNBLOCK, SIG_SETMASK) las clases relacionadas abajo se cambian en las funciones enums. getsignal(), pthread_sigmask(), sigpending() y sigwait() que retornan enums que pueden ser leídas por humanos.

Las variables definidas en el módulo signal son:

signal.SIG_DFL

Ésta es una de las dos opciones estándar de manejo de señales; simplemente realizará la función predeterminada para la señal. Por ejemplo, en la mayoría de los sistemas, la acción predeterminada para SIGQUIT es volcar el núcleo y salir, mientras que la acción predeterminada para SIGCHLD es simplemente ignorarlo.

signal.SIG_IGN

Este es otro manejador de señales estándar, que simplemente ignorará la señal dada.

signal.SIGABRT

Abortar señal de abort(3).

signal.SIGALRM

Señal de temporizador de alarm(2).

Disponibilidad: Unix.

signal.SIGBREAK

Interrumpir desde el teclado (CTRL + BREAK).

Disponibilidad: Windows.

signal.SIGBUS

Error de bus (mal acceso a la memoria).

Disponibilidad: Unix.

signal.SIGCHLD

El proceso hijo se detuvo o terminó.

Disponibilidad: Unix.

signal.SIGCLD

Alias para SIGCHLD.

signal.SIGCONT

Continuar el proceso si está detenido actualmente

Disponibilidad: Unix.

signal.SIGFPE

Excepción de coma flotante. Por ejemplo, división por cero.

Ver también

ZeroDivisionError se genera cuando el segundo argumento de una operación de división o módulo es cero.

signal.SIGHUP

Se detectó un bloqueo en el terminal de control o muerte del proceso de control.

Disponibilidad: Unix.

signal.SIGILL

Instrucción ilegal.

signal.SIGINT

Interrumpir desde el teclado (CTRL + C).

La acción predeterminada es generar KeyboardInterrupt.

signal.SIGKILL

Señal de muerte.

No se puede detectar, bloquear ni ignorar.

Disponibilidad: Unix.

signal.SIGPIPE

Tubería rota: escriba en la tubería sin lectores.

La acción predeterminada es ignorar la señal.

Disponibilidad: Unix.

signal.SIGSEGV

Fallo de segmentación: referencia de memoria no válida.

signal.SIGTERM

Señal de terminación.

signal.SIGUSR1

Señal definida por el usuario 1.

Disponibilidad: Unix.

signal.SIGUSR2

Señal definida por el usuario 2.

Disponibilidad: Unix.

signal.SIGWINCH

Señal de cambio de tamaño de ventana.

Disponibilidad: Unix.

SIG*

Todos los números de señal se definen simbólicamente. Por ejemplo, la señal de colgar se define como signal.SIGHUP; los nombres de las variables son idénticos a los nombres utilizados en los programas C, como se encuentran en <signal.h>. La página de manual de Unix para “signal()” enumera las señales existentes (en algunos sistemas esto es signal(2) `, en otros la lista está en :manpage:`signal(7) ). Tenga en cuenta que no todos los sistemas definen el mismo conjunto de nombres de señales; Este módulo solo define los nombres definidos por el sistema.

signal.CTRL_C_EVENT

La señal correspondiente al evento de pulsación de tecla Ctrl + C. Esta señal solo se puede utilizar con os.kill().

Disponibilidad: Windows.

Nuevo en la versión 3.2.

signal.CTRL_BREAK_EVENT

La señal correspondiente al evento de pulsación de tecla Ctrl + Break. Esta señal solo se puede utilizar con os.kill().

Disponibilidad: Windows.

Nuevo en la versión 3.2.

signal.NSIG

Uno más que el número de señal más alto.

signal.ITIMER_REAL

Reduce el temporizador de intervalo en tiempo real y entrega SIGALRM al vencimiento.

signal.ITIMER_VIRTUAL

Disminuye el temporizador de intervalo solo cuando el proceso se está ejecutando y entrega SIGVTALRM al vencimiento.

signal.ITIMER_PROF

Disminuye el temporizador de intervalo tanto cuando se ejecuta el proceso como cuando el sistema se está ejecutando en nombre del proceso. Junto con ITIMER_VIRTUAL, este temporizador generalmente se usa para perfilar el tiempo que pasa la aplicación en el espacio del usuario y del kernel. SIGPROF se entrega al vencimiento.

signal.SIG_BLOCK

Un valor posible para el parámetro how para pthread_sigmask() que indica que las señales deben bloquearse.

Nuevo en la versión 3.3.

signal.SIG_UNBLOCK

Un valor posible para el parámetro how para pthread_sigmask() que indica que las señales deben desbloquearse.

Nuevo en la versión 3.3.

signal.SIG_SETMASK

Un valor posible para el parámetro how para pthread_sigmask() que indica que la máscara de señal debe ser reemplazada.

Nuevo en la versión 3.3.

El módulo signal define una excepción:

exception signal.ItimerError

Se genera para señalar un error de la implementación subyacente setitimer() o getitimer(). Espere este error si se pasa un temporizador de intervalo no válido o un tiempo negativo a setitimer(). Este error es un subtipo de OSError.

Nuevo en la versión 3.3: Este error solía ser un subtipo de IOError, que ahora es un alias de OSError.

El módulo signal define las siguientes funciones:

signal.alarm(time)

Si time es distinto de cero, esta función solicita que se envíe una señal SIGALRM al proceso en time segundos. Se cancela cualquier alarma programada previamente (solo se puede programar una alarma en cualquier momento). El valor retornado es entonces el número de segundos antes de que se entregara cualquier alarma previamente configurada. Si time es cero, no se programa ninguna alarma y se cancela cualquier alarma programada. Si el valor de retorno es cero, no hay ninguna alarma programada actualmente.

Disponibilidad: Unix. Consulte la página de manual alarm(2) para obtener más información.

signal.getsignal(signalnum)

Retorna el manejador de señales actual para la señal signalnum. El valor retornado puede ser un objeto de Python invocable o uno de los valores especiales signal.SIG_IGN, signal.SIG_DFL o None. Aquí, signal.SIG_IGN significa que la señal fue previamente ignorada, signal.SIG_DFL significa que la forma predeterminada de manejar la señal estaba en uso anteriormente, y el gestor de señales no se instaló desde Python.

signal.strsignal(signalnum)

Retorna la descripción del sistema de la señal signalnum, como «Interrupción», «Fallo de segmentación», etc. Retorna None si no se reconoce la señal.

Nuevo en la versión 3.8.

signal.valid_signals()

Retorna el conjunto de números de señal válidos en esta plataforma. Esto puede ser menor que rango(1, NSIG) si el sistema reserva algunas señales para uso interno.

Nuevo en la versión 3.8.

signal.pause()

Hacer que el proceso duerma hasta que se reciba una señal; entonces se llamará al manejador apropiado. No retorna nada.

Disponibilidad: Unix. Consulte la página man signal(2) para obtener más información.

Vea también sigwait(), sigwaitinfo(), sigtimedwait() y sigpending().

signal.raise_signal(signum)

Envía una señal al proceso de llamada. No retorna nada.

Nuevo en la versión 3.8.

signal.pidfd_send_signal(pidfd, sig, siginfo=None, flags=0)

Envía la señal sig al proceso referido por el descriptor de archivo pidfd. Python actualmente no soporta el parámetro siginfo; éste debe ser None. El argumento flags está proveído para extensiones futuras; no hay valores actualmente definidos para flags.

Para más información vea la página de manual pidfd_send_signal(2).

Disponibilidad: Linux 5.1+

Nuevo en la versión 3.9.

signal.pthread_kill(thread_id, signalnum)

Envíe la señal signalnum al hilo thread_id, otro hilo en el mismo proceso que el llamador. El hilo de destino puede ejecutar cualquier código (Python o no). Sin embargo, si el hilo de destino está ejecutando el intérprete de Python, los manejadores de señales de Python serán ejecutados por el hilo principal. Por lo tanto, el único punto de enviar una señal a un hilo de Python en particular sería forzar que una llamada al sistema en ejecución falle con InterruptedError.

Utilice threading.get_ident() o el atributo ident de los objetos threading.Thread para obtener un valor adecuado para thread_id.

Si signalnum es 0, no se envía ninguna señal, pero se sigue realizando la comprobación de errores; esto se puede usar para verificar si el hilo de destino aún se está ejecutando.

Genera un evento de auditoría signal.pthread_kill con argumentos thread_id, signalnum.

Disponibilidad: Unix. Consulte la página del manual pthread_kill(3) para obtener más información.

Vea también os.kill().

Nuevo en la versión 3.3.

signal.pthread_sigmask(how, mask)

Busca o cambia la máscara de señal del hilo de llamada. La máscara de señal es el conjunto de señales cuya entrega está actualmente bloqueada para la persona que llama. Retorna la máscara de señal anterior como un conjunto de señales.

El comportamiento de la llamada depende del valor de how, como sigue.

SIG_BLOCK: El conjunto de señales bloqueadas es la unión del conjunto actual y el argumento mask.

SIG_UNBLOCK: Las señales en mask se eliminan del conjunto actual de señales bloqueadas. Está permitido intentar desbloquear una señal que no esté bloqueada.

SIG_SETMASK: El conjunto de señales bloqueadas se establece en el argumento mask.

mask es un conjunto de números de señales (por ejemplo, {signal.SIGINT, signal.SIGTERM}). Utilice valid_signals() para una máscara completa que incluya todas las señales.

Por ejemplo, signal.pthread_sigmask(signal.SIG_BLOCK, []) lee la máscara de señal del hilo de llamada.

SIGKILL y SIGSTOP no se pueden bloquear.

Disponibilidad: Unix. Consulte la página de manual sigprocmask(3) y pthread_sigmask(3) para obtener más información.

Vea también pause(), sigpending() y sigwait().

Nuevo en la versión 3.3.

signal.setitimer(which, seconds, interval=0.0)

Establece el temporizador de intervalo dado (uno de signal.ITIMER_REAL, signal.ITIMER_VIRTUAL o signal.ITIMER_PROF) especificado por which disparar después de seconds (se acepta el números de punto flotante, diferente de alarm()) y luego cada interval segundos (si interval es distinto de cero). El temporizador de intervalo especificado por which se puede borrar estableciendo seconds en cero.

Cuando se dispara un temporizador de intervalos, se envía una señal al proceso. La señal enviada depende del temporizador que se utilice; signal.ITIMER_REAL entregará SIGALRM, signal.ITIMER_VIRTUAL envía SIGVTALRM, y signal.ITIMER_PROF entregará SIGPROF.

Los valores antiguos se retornan como una tupla: (retraso, intervalo).

Si intenta pasar un temporizador de intervalo no válido, se producirá un ItimerError.

Disponibilidad: Unix.

signal.getitimer(which)

Retorna el valor actual de un temporizador de intervalo dado especificado por which.

Disponibilidad: Unix.

signal.set_wakeup_fd(fd, *, warn_on_full_buffer=True)

Establezca el descriptor del archivo de activación en fd. Cuando se recibe una señal, el número de la señal se escribe como un solo byte en el fd. Esto puede ser utilizado por una biblioteca para despertar una encuesta o seleccionar una llamada, permitiendo que la señal se procese por completo.

Se retorna el antiguo fd de activación (o -1 si la activación del descriptor de archivo no estaba habilitada). Si fd es -1, la activación del descriptor de archivo está deshabilitada. Si no es -1, fd debe ser sin bloqueo. Depende de la biblioteca eliminar los bytes de fd antes de llamar a poll o seleccionar nuevamente.

Cuando los hilos están habilitados, esta función solo se puede llamar desde el subproceso principal del intérprete principal; intentar llamarlo desde otros hilos hará que se lance una excepción ValueError.

Hay dos formas habituales de utilizar esta función. En ambos enfoques, usa el fd para despertarse cuando llega una señal, pero luego difieren en cómo determinan which señal o señales han llegado.

En el primer enfoque, leemos los datos del búfer de fd, y los valores de bytes le dan los números de señal. Esto es simple, pero en casos raros puede surgir un problema: generalmente el fd tendrá una cantidad limitada de espacio en el búfer, y si llegan demasiadas señales demasiado rápido, entonces el búfer puede llenarse y algunas señales pueden perderse. Si usa este enfoque, entonces debe configurar warn_on_full_buffer = True, que al menos causará que se imprima una advertencia en stderr cuando se pierdan las señales.

En el segundo enfoque, usamos el wakeup fd solo para wakeups e ignoramos los valores de bytes reales. En este caso, lo único que nos importa es si el búfer de fd está vacío o no; un búfer lleno no indica ningún problema. Si utiliza este enfoque, debe configurar warn_on_full_buffer = False, para que sus usuarios no se confundan con mensajes de advertencia falsos.

Distinto en la versión 3.5: En Windows, la función ahora también admite identificadores de socket.

Distinto en la versión 3.7: Se agregó el parámetro warn_on_full_buffer.

signal.siginterrupt(signalnum, flag)

Cambiar el comportamiento de reinicio de la llamada al sistema: si flag es False, las llamadas al sistema se reiniciarán cuando las interrumpa la señal signalnum, de lo contrario, las llamadas al sistema se interrumpirán. No retorna nada.

Disponibilidad: Unix. Consulte la página man siginterrupt(3) para obtener más información.

Tenga en cuenta que la instalación de un gestor de señales con signal() restablecerá el comportamiento de reinicio a interrumpible llamando implícitamente a siginterrupt() con un valor de flag verdadero para la señal dada.

signal.signal(signalnum, handler)

Establece el gestor de la señal signalnum en la función handler (manejador). handler puede ser un objeto de Python invocable que toma dos argumentos (ver más abajo), o uno de los valores especiales signal.SIG_IGN o signal.SIG_DFL. Se retornará el manejador de señales anterior (vea la descripción de getsignal() arriba). (Consulte la página del manual de Unix signal(2) para obtener más información).

Cuando los hilos están habilitados, esta función solo se puede llamar desde el subproceso principal del intérprete principal; intentar llamarlo desde otros hilos hará que se lance una excepción ValueError.

El handler se llama con dos argumentos: el número de señal y el marco de pila actual (None o un objeto marco; para obtener una descripción de los objetos marco, consulte la descripción en la jerarquía de tipos o vea las descripciones de los atributos en el módulo inspect).

En Windows, signal() solo se puede llamar con SIGABRT, SIGFPE, SIGILL, SIGINT, SIGSEGV, SIGTERM, o SIGBREAK. A ValueError se generará en cualquier otro caso. Tenga en cuenta que no todos los sistemas definen el mismo conjunto de nombres de señales; un AttributeError se lanzará si un nombre de señal no está definido como constante de nivel de módulo SIG*.

signal.sigpending()

Examine el conjunto de señales que están pendientes de entrega al hilo de llamada (es decir, las señales que se han generado mientras estaban bloqueadas). Retorna el conjunto de señales pendientes.

Disponibilidad: Unix. Consulte la página de manual sigpending(2) para obtener más información.

Vea también pause(), pthread_sigmask() y sigwait().

Nuevo en la versión 3.3.

signal.sigwait(sigset)

Suspende la ejecución del hilo de llamada hasta la entrega de una de las señales especificadas en el conjunto de señales sigset. La función acepta la señal (la elimina de la lista pendiente de señales) y retorna el número de señal.

Disponibilidad: Unix. Consulte la página man sigwait(3) para obtener más información.

Vea también pause(), pthread_sigmask(), sigpending(), sigwaitinfo() y sigtimedwait().

Nuevo en la versión 3.3.

signal.sigwaitinfo(sigset)

Suspende la ejecución del hilo de llamada hasta la entrega de una de las señales especificadas en el conjunto de señales sigset. La función acepta la señal y la elimina de la lista de señales pendientes. Si una de las señales en sigset ya está pendiente para el hilo de llamada, la función regresará inmediatamente con información sobre esa señal. No se llama al gestor de señales para la señal enviada. La función genera un InterruptedError si es interrumpida por una señal que no está en sigset.

El valor de retorno es un objeto que representa los datos contenidos en la estructura siginfo_t, a saber: si_signo, si_code, si_errno, si_pid, si_uid, si_status, si_band.

Disponibilidad: Unix. Consulte la página man sigwaitinfo(2) para obtener más información.

Vea también pause(), sigwait() y sigtimedwait().

Nuevo en la versión 3.3.

Distinto en la versión 3.5: La función ahora se vuelve a intentar si es interrumpida por una señal que no está en sigset y el manejador de señales no genera una excepción (ver PEP 475 [https://www.python.org/dev/peps/pep-0475] para la justificación).

signal.sigtimedwait(sigset, timeout)

Como sigwaitinfo(), pero toma un argumento timeout adicional que especifica un tiempo de espera. Si timeout se especifica como 0, se realiza una encuesta. Retorna None si se agota el tiempo de espera.

Disponibilidad: Unix. Consulte la página de manual sigtimedwait(2) para obtener más información.

Vea también pause(), sigwait() y sigwaitinfo().

Nuevo en la versión 3.3.

Distinto en la versión 3.5: La función ahora se reintenta con el timeout recalculado si se interrumpe por una señal que no está en sigset y el manejador de señales no genera una excepción (ver PEP 475 [https://www.python.org/dev/peps/pep-0475] para la justificación).

Ejemplo

Aquí hay un programa de ejemplo mínimo. Utiliza la función alarm() para limitar el tiempo de espera para abrir un archivo; esto es útil si el archivo es para un dispositivo serial que puede no estar encendido, lo que normalmente haría que os.open() se cuelgue indefinidamente. La solución es configurar una alarma de 5 segundos antes de abrir el archivo; si la operación lleva demasiado tiempo, se enviará la señal de alarma y el gestor genera una excepción.

import signal, os

def handler(signum, frame):
    print('Signal handler called with signal', signum)
    raise OSError("Couldn't open device!")

# Set the signal handler and a 5-second alarm
signal.signal(signal.SIGALRM, handler)
signal.alarm(5)

# This open() may hang indefinitely
fd = os.open('/dev/ttyS0', os.O_RDWR)

signal.alarm(0)          # Disable the alarm

Nota sobre SIGPIPE

Canalizar la salida de su programa a herramientas como head(1) hará que se envíe una señal SIGPIPE a su proceso cuando el receptor de su salida estándar se cierre antes. Esto da como resultado una excepción como BrokenPipeError: [Errno 32] Broken pipe. Para manejar este caso, envuelva su punto de entrada para detectar esta excepción de la siguiente manera:

import os
import sys

def main():
    try:
        # simulate large output (your code replaces this loop)
        for x in range(10000):
            print("y")
        # flush output here to force SIGPIPE to be triggered
        # while inside this try block.
        sys.stdout.flush()
    except BrokenPipeError:
        # Python flushes standard streams on exit; redirect remaining output
        # to devnull to avoid another BrokenPipeError at shutdown
        devnull = os.open(os.devnull, os.O_WRONLY)
        os.dup2(devnull, sys.stdout.fileno())
        sys.exit(1)  # Python exits with error code 1 on EPIPE

if __name__ == '__main__':
    main()

Do not set SIGPIPE’s disposition to SIG_DFL in order to avoid BrokenPipeError. Doing that would cause your program to exit unexpectedly whenever any socket connection is interrupted while your program is still writing to it.

Note on Signal Handlers and Exceptions

If a signal handler raises an exception, the exception will be propagated to the main thread and may be raised after any bytecode instruction. Most notably, a KeyboardInterrupt may appear at any point during execution. Most Python code, including the standard library, cannot be made robust against this, and so a KeyboardInterrupt (or any other exception resulting from a signal handler) may on rare occasions put the program in an unexpected state.

To illustrate this issue, consider the following code:

class SpamContext:
    def __init__(self):
        self.lock = threading.Lock()

    def __enter__(self):
        # If KeyboardInterrupt occurs here, everything is fine
        self.lock.acquire()
        # If KeyboardInterrupt occcurs here, __exit__ will not be called
        ...
        # KeyboardInterrupt could occur just before the function returns

    def __exit__(self, exc_type, exc_val, exc_tb):
        ...
        self.lock.release()

For many programs, especially those that merely want to exit on KeyboardInterrupt, this is not a problem, but applications that are complex or require high reliability should avoid raising exceptions from signal handlers. They should also avoid catching KeyboardInterrupt as a means of gracefully shutting down. Instead, they should install their own SIGINT handler. Below is an example of an HTTP server that avoids KeyboardInterrupt:

import signal
import socket
from selectors import DefaultSelector, EVENT_READ
from http.server import HTTPServer, SimpleHTTPRequestHandler

interrupt_read, interrupt_write = socket.socketpair()

def handler(signum, frame):
    print('Signal handler called with signal', signum)
    interrupt_write.send(b'\0')
signal.signal(signal.SIGINT, handler)

def serve_forever(httpd):
    sel = DefaultSelector()
    sel.register(interrupt_read, EVENT_READ)
    sel.register(httpd, EVENT_READ)

    while True:
        for key, _ in sel.select():
            if key.fileobj == interrupt_read:
                interrupt_read.recv(1)
                return
            if key.fileobj == httpd:
                httpd.handle_request()

print("Serving on port 8000")
httpd = HTTPServer(('', 8000), SimpleHTTPRequestHandler)
serve_forever(httpd)
print("Shutdown...")

mmap — Soporte de archivos mapeados en memoria

Los objetos de archivo mapeados en memoria se comportan como bytearray y como objetos de archivo. Puede usar objetos mmap en la mayoría de los lugares donde se espera bytearray; por ejemplo, puede usar el módulo re para buscar en un archivo mapeado en memoria. También puede cambiar un solo byte haciendo obj[índice] = 97, o cambiar una subsecuencia asignando a un segmento: obj[i1: i2] = b'...'. También puede leer y escribir datos comenzando en la posición actual del archivo, y seek() a través del archivo a diferentes posiciones.

Un archivo mapeado en memoria se crea con el constructor mmap, que es diferente en Unix y en Windows. En cualquier caso, debes proporcionar un descriptor de archivo para un archivo abierto para la actualización. Si deseas mapear un objeto archivo de Python existente, use su método fileno() para obtener el valor correcto para el parámetro fileno. De otra manera, puedes abrir el archivo usando la función os.open(), que retorna un descriptor de archivo directamente (el archivo aún necesita ser cerrado cuando hayas terminado).

Nota

Si quieres crear un mapeado en memoria para un archivo con permisos de escritura y en el búfer, debes ejecutar la función flush(). Es necesario para asegurar que las modificaciones locales a los búfer estén realmente disponible para el mapeado.

Para las versiones del constructor de tanto Unix como de Windows, access puede ser especificado como un parámetro nombrado opcional. access acepta uno de cuatro valores: ACCESS_READ, ACCESS_WRITE, o ACCESS_DEFAULT para especificar una memoria de sólo lectura, write-through, o copy-on-write respectivamente, o ACCES_DEFAULT para deferir a prot. El parámetro access se puede usar tanto en Unix como en Windows. Si access no es especificado, el mmap de Windows retorna un mapeado write-through. Los valores de la memoria inicial para los tres tipos de acceso son tomados del archivo especificado. La asignación a una mapa de memoria ACCESS_READ lanza una excepción TypeError. La asignación a un mapa de memoria ACCESS_WRITE afecta tanto a la memoria como al archivo subyacente. La asignación a un mapa de memoria ACCES_COPY afecta a la memoria pero no actualiza el archivo subyacente.

Distinto en la versión 3.7: Se añadió la constante ACCESS_DEFAULT.

Para mapear memoria anónima, se debe pasar -1 como el fileno junto con la longitud.

class mmap.mmap(fileno, length, tagname=None, access=ACCESS_DEFAULT[, offset])

(En la versión de Windows) Mapea length bytes desde el archivo especificado por el gestor de archivo fileno, y crea un objeto mmap. Si length es más largo que el tamaño actual del archivo, el archivo es extendido para contener length bytes. Si length es 0, la longitud máxima del map es la tamaño actual del archivo, salvo que si el archivo está vacío Windows lanza una excepción (no puedes crear un mapeado vacío en Windows)

tagname, si está especifico y no es None, es una cadena que proporciona el nombre de la etiqueta para el mapeado. Windows te permite tener varios mapeados diferentes del mismo archivo. Si especificas el nombre de una etiqueta existente, la etiqueta se abre, de otro modo una crea una nueva etiqueta. Si este parámetro se omite o es None, el mapeado es creado sin un nombre. Evitar el uso del parámetro etiqueta te ayudará a mantener tu código portable entre Unix y Windows.

offset puede ser especificado como un offset entero no negativo. las referencias de mmap serán relativas al offset desde el comienzo del archivo. offset es por defecto 0. offset debe ser un múltiplo de ALLOCATIONGRANULARITY.

Lanza un evento de inspección mmap.__new__ con los argumentos fileno, length, access, offset.

class mmap.mmap(fileno, length, flags=MAP_SHARED, prot=PROT_WRITE|PROT_READ, access=ACCESS_DEFAULT[, offset])

(En la versión de Unix) Mapea length bytes desde el archivo especificado por el descriptor de archivo fileno, y retorna un objeto mmap. Si length es 0, la longitud máxima del map será el tamaño actual del archivo cuando mmap sea llamado.

flags especifica la naturaleza del mapeado. MAP_PRIVATE crea un mapeado copy-on-write privado, por lo que los cambios al contenido del objeto mmap serán privados para este proceso, y MAP_SHARED crea un mapeado que es compartido con todos los demás procesos que mapean las mismas áreas del archivo. El valor por defecto es MAP_SHARED.

prot, si se especifica, proporciona la protección de memoria deseado; los dos valores más útiles son PROT_READ y PROT_WRITE, para especificar que las páginas puedan ser escritas o leídas. prot es por defecto PROT_READ|PROT_WRITE.

access puede ser especificado en lugar de flags y prot como un parámetro nombrado opcional. Es un error especificar tanto flags, prot como access. Véase la descripción de access arriba por información de cómo usar este parámetro.

offset puede ser especificado como un offset entero no negativo. Las referencias serán relativas al offset desde el comienzo del archivo. offset por defecto es 0. offset debe ser un múltiplo de ALLOCATIONGRANULARITY que es igual a PAGESIZE en los sistemas Unix.

To ensure validity of the created memory mapping the file specified by the descriptor fileno is internally automatically synchronized with physical backing store on macOS and OpenVMS.

Este ejemplo muestra un forma simple de usar mmap:

import mmap

# write a simple example file
with open("hello.txt", "wb") as f:
    f.write(b"Hello Python!\n")

with open("hello.txt", "r+b") as f:
    # memory-map the file, size 0 means whole file
    mm = mmap.mmap(f.fileno(), 0)
    # read content via standard file methods
    print(mm.readline())  # prints b"Hello Python!\n"
    # read content via slice notation
    print(mm[:5])  # prints b"Hello"
    # update content using slice notation;
    # note that new content must have same size
    mm[6:] = b" world!\n"
    # ... and read again using standard file methods
    mm.seek(0)
    print(mm.readline())  # prints b"Hello  world!\n"
    # close the map
    mm.close()

mmap también puede ser usado como un gestor de contexto en una sentencia with

import mmap

with mmap.mmap(-1, 13) as mm:
    mm.write(b"Hello world!")

Nuevo en la versión 3.2: Soporte del Gestor de Contexto.

El siguiente ejemplo demuestra como crear un mapa anónimo y cambiar los datos entre los procesos padre e hijo:

import mmap
import os

mm = mmap.mmap(-1, 13)
mm.write(b"Hello world!")

pid = os.fork()

if pid == 0:  # In a child process
    mm.seek(0)
    print(mm.readline())

    mm.close()

Lanza un evento de inspección mmap.__new__ con los argumentos fileno, length, access, offset.

Los objetos de archivos mapeados en memoria soportan los siguiente métodos:

close()

Cierra el mmap. Las llamadas posteriores a otros métodos del objeto resultarán en que se lance una excepción ValueError. Esto no cerrará el archivo abierto.

closed

True si el archivo está cerrado.

Nuevo en la versión 3.2.

find(sub[, start[, end]])

Retorna el índice mínimo en el objeto donde la subsecuencia sub es hallada, tal que sub este contenido en el rango [start, end]. Los argumentos opcionales start y end son interpretados como en una notación de rebanada. Retorna -1 si falla.

Distinto en la versión 3.5: Ahora el objeto bytes-like object con permisos de escritura se acepta.

flush([offset[, size]])

Transmite los cambios hechos a la copia en memoria de una archivo de vuelta al archivo. Sin el uso de esta llamada no hay garantía que los cambios sean escritos de vuelta antes de que los objetos sean destruidos. Si offset y size son especificados, sólo los cambios al rango de bytes dado serán transmitidos al disco; de otra forma, la extensión completa al mapeado se transmite. offset debe ser un múltiplo de la constante PAGESIZE o ALLOCATIONGRANULARITY.

Se retorna None para indicar éxito. Una excepción es lanzada cuando la llamada falla.

Distinto en la versión 3.8: Anteriormente, se retornaba un valor diferente de cero cuando era exitoso; se retornaba cero cuando pasaba un error en Windows. Se retornaba un valor de cero cuando era exitoso; se lanzaba una excepción cuando pasaba un error en Unix.

madvise(option[, start[, length]])

Envía un aviso option al kernel sobre la región de la memoria que comienza con start y se extiende length bytes. option debe ser una de las constantes MADV_* disponibles en el sistema. Si start y end se omiten, se abarca al mapeo entero. En algunos sistemas (incluyendo Linux), start debe ser un múltiplo de PAGESIZE.

Disponibilidad: Sistemas con la llamada al sistema madvise().

Nuevo en la versión 3.8.

move(dest, src, count)

Copia los count bytes empezando en el offset src al índice de destino dest. Si el mmap fue creado con ACCESS_READ, entonces las llamadas lanzaran una excepción TypeError.

read([n])

Retorna una clase bytes que contiene hasta n bytes empezando desde la posición del archivo actual. Si se omite el argumento, es None o negativo, retorna todos los bytes desde la posición actual del archivo hasta el final del mapeado. Se actualiza la posición del archivo para apuntar después de los bytes que se retornaron.

Distinto en la versión 3.3: El argumento puede ser omitido o ser None.

read_byte()

Retorna un byte en la posición actual del archivo como un entero, y avanza la posición del archivo por 1.

readline()

Retorna una sola línea, comenzando en la posición actual del archivo y hasta la siguiente nueva línea. La posición del archivo se actualiza para apuntar después de los bytes que se retornaron.

resize(newsize)

Redimensiona el mapa y el archivo subyacente, si lo hubiera. Si el mmap fue creado con ACCESS_READ o ACCESS_COPY, redimensionar el mapa lanzará una excepción TypeError.

rfind(sub[, start[, end]])

Retorna el índice más alto en el objeto donde la subsecuencia sub se encuentre, tal que sub sea contenido en el rango [start, end]. Los argumentos opcionales start y end son interpretados como un notación de rebanada. Retorna -1 si falla.

Distinto en la versión 3.5: Ahora el objeto bytes-like object con permisos de escritura se acepta.

seek(pos[, whence])

Establece la posición actual del archivo. El argumento whence es opcional y es por defecto os.SEEK_SET o 0 (posicionamiento del archivo absoluto); otros valores son os.SEEK_CUR o 1 (búsqueda relativa a la posición actual) y os.SEEK_END o 2 (búsqueda relativa al final del archivo).

size()

Retorna el tamaño del archivo, que puede ser más grande que el tamaño del área mapeado en memoria.

tell()

Retorna la posición actual del puntero del archivo.

write(bytes)

Escribe los bytes en bytes en memoria en la posición actual del puntero del archivo y retorna el números de bytes escritos (nunca menos que len(bytes), ya que si la escritura falla, una excepción ValueError será lanzada). La posición del archivo es actualizada para apuntar después de los bytes escritos. Si el mmap fue creado con ACCESS_READ, entonces escribirlo lanzará una excepción TypeError.

Distinto en la versión 3.5: Ahora el objeto bytes-like object con permisos de escritura se acepta.

Distinto en la versión 3.6: Ahora se retorna el número de bytes escritos.

write_byte(byte)

Escribe el entero byte en la memoria en la posición actual del puntero del archivo; se avanza la posición del archivo por 1. Si el mmap es creado con ACCES_READ, entonces escribirlo hará que se lance la excepción TypeError.

Constantes MADV_*

mmap.MADV_NORMAL

mmap.MADV_RANDOM

mmap.MADV_SEQUENTIAL

mmap.MADV_WILLNEED

mmap.MADV_DONTNEED

mmap.MADV_REMOVE

mmap.MADV_DONTFORK

mmap.MADV_DOFORK

mmap.MADV_HWPOISON

mmap.MADV_MERGEABLE

mmap.MADV_UNMERGEABLE

mmap.MADV_SOFT_OFFLINE

mmap.MADV_HUGEPAGE

mmap.MADV_NOHUGEPAGE

mmap.MADV_DONTDUMP

mmap.MADV_DODUMP

mmap.MADV_FREE

mmap.MADV_NOSYNC

mmap.MADV_AUTOSYNC

mmap.MADV_NOCORE

mmap.MADV_CORE

mmap.MADV_PROTECT

Se pueden pasar estas opciones al método mmap.madvise(). No todas las opciones estarán presentes en todos los sistemas.

Disponibilidad: Sistemas con la llamada al sistema madvise().

Nuevo en la versión 3.8.

Manejo de Datos de Internet

Este capítulo describe los módulos que admiten el manejo de formatos de datos que se usan comúnmente en Internet.

email — Un paquete de manejo de correo electrónico y MIME

email.message: Representando un mensaje de correo electrónico

email.parser: Analizar mensajes de correo electrónico

API FeedParser

API Parser

Notas adicionales

email.generator: Generando documentos MIME

email.policy: Objetos Policy

email.errors: Clases de excepción y defecto

email.headerregistry: Objetos de encabezado personalizados

email.contentmanager: Gestión de contenido MIME

Instancias gestoras de contenido

email: Ejemplos

email.message.Message: Representar un mensaje de correo electrónico usando la API compat32

email.mime: Creación de correo electrónico y objetos MIME desde cero

email.header: Cabeceras internacionalizadas

email.charset: Representa conjunto de caracteres

email.encoders: Codificadores

email.utils: Utilidades misceláneas

email.iterators: Iteradores

json — Codificador y decodificador JSON

Uso básico

Codificadores y Decodificadores

Excepciones

Cumplimiento e interoperabilidad estándar

Codificaciones de caracteres

Valores de número infinito y NaN

Nombres repetidos dentro de un objeto

Valores de nivel superior No-Objeto , No-Arreglo

Limitaciones de la implementación

Interfaz de línea de comandos

Opciones de línea de comandos

mailbox — Manipular buzones de correo en varios formatos

Objetos :class:”Mailbox”

Maildir

mbox

MH

Babyl

MMDF

Objetos Message

MaildirMessage

mboxMessage

MHMessage

BabylMessage

MMDFMessage

Excepciones

Ejemplos

mimetypes — Mapea nombres de archivo a tipos MIME

Objetos MimeTypes

base64 — Codificaciones de datos Base16, Base32, Base64, y Base85

binhex — Codificar y decodificar archivos binhex4

Notas

binascii — Convertir entre binario y ASCII

quopri — Codificar y decodificar datos MIME imprimibles entre comillas

email — Un paquete de manejo de correo electrónico y MIME

Código fuente Lib/email/__init__.py [https://github.com/python/cpython/tree/3.9/Lib/email/__init__.py]

The email package is a library for managing email messages. It is specifically not designed to do any sending of email messages to SMTP (RFC 2821 [https://tools.ietf.org/html/rfc2821.html]), NNTP, or other servers; those are functions of modules such as smtplib and nntplib. The email package attempts to be as RFC-compliant as possible, supporting RFC 5322 [https://tools.ietf.org/html/rfc5322.html] and RFC 6532 [https://tools.ietf.org/html/rfc6532.html], as well as such MIME-related RFCs as RFC 2045 [https://tools.ietf.org/html/rfc2045.html], RFC 2046 [https://tools.ietf.org/html/rfc2046.html], RFC 2047 [https://tools.ietf.org/html/rfc2047.html], RFC 2183 [https://tools.ietf.org/html/rfc2183.html], and RFC 2231 [https://tools.ietf.org/html/rfc2231.html].

La estructura general del paquete de correo electrónico se puede dividir en tres componentes principales, más un cuarto componente que controla el comportamiento de los otros componentes.

El componente central del paquete es un «modelo de objetos» que representa los mensajes de correo electrónico. Una aplicación interactúa con el paquete principalmente a través de la interfaz del modelo de objetos definida en el submódulo message. La aplicación puede usar esta API para hacer preguntas sobre un correo electrónico existente, para construir un nuevo correo electrónico o para agregar o eliminar subcomponentes de correo electrónico que utilizan la misma interfaz de modelo de objetos. Es decir, siguiendo la naturaleza de los mensajes de correo electrónico y sus subcomponentes MIME, el modelo de objetos de correo electrónico es una estructura de árbol de objetos que proporcionan la API EmailMessage.

Los otros dos componentes principales del paquete son parser y generator. El parser toma la versión serializada de un mensaje de correo electrónico (una secuencia de bytes) Y la convierte en un árbol de objetos EmailMessage. El generador toma un EmailMessage y lo convierte de nuevo en un flujo de bytes serializado. (El analizador y el generador también manejan flujos de caracteres de texto, pero se desaconseja este uso ya que es demasiado fácil terminar con mensajes que no son válidos de una forma u otra).

El componente de control es el módulo de policy. Cada EmailMessage cada generator, y cada parser tiene un objeto de policy asociado que controla su comportamiento. Por lo general, una aplicación solo necesita especificar la política cuando se crea un EmailMessage , ya sea instanciando directamente un EmailMessage para crear un nuevo correo electrónico o analizando un flujo de entrada con un parser. Pero la política se puede cambiar cuando el mensaje se serializa mediante un generator. Esto permite, por ejemplo, analizar un mensaje de correo electrónico genérico desde el disco, pero serializarlo utilizando la configuración estándar de SMTP al enviarlo a un servidor de correo electrónico.

El paquete de correo electrónico hace todo lo posible para ocultar los detalles de las diversas RFC que rigen de la aplicación. Conceptualmente, la aplicación debería poder tratar el mensaje de correo electrónico como un árbol estructurado de texto Unicode y archivos adjuntos binarios, sin tener que preocuparse por cómo se representan estos cuando se serializan. En la práctica, sin embargo, a menudo es necesario conocer al menos algunas de las reglas que rigen los mensajes MIME y su estructura, específicamente los nombres y la naturaleza de los «tipos de contenido» MIME y cómo identifican los documentos de varias partes. En su mayor parte, este conocimiento solo debería ser necesario para aplicaciones más complejas, e incluso entonces debería ser solo la estructura de alto nivel en cuestión, y no los detalles de cómo se representan esas estructuras. Dado que los tipos de contenido MIME se utilizan ampliamente en el software moderno de Internet (no solo en el correo electrónico), este será un concepto familiar para muchos programadores.

Las siguientes secciones describen la funcionalidad del paquete email. Comenzamos con el modelo de objetos message, que es la interfaz principal que usará una aplicación, y lo seguimos con los componentes del parser y generator . Luego cubrimos los controles de la policy, lo que completa el tratamiento de los principales componentes de la biblioteca.

Las siguientes tres secciones cubren las excepciones que puede generar el paquete y los defectos (incumplimiento de las RFC) que el parser puede detectar. Luego cubrimos los subcomponentes headerregistry y contentmanager, que proporcionan herramientas para realizar una manipulación más detallada de los encabezados y cargas útiles, respectivamente. Ambos componentes contienen características relevantes para consumir y producir mensajes no triviales, pero también documentan sus API de extensibilidad, que serán de interés para aplicaciones avanzadas.

A continuación, se muestra un conjunto de ejemplos del uso de las partes fundamentales de las API cubiertas en las secciones anteriores.

Lo anterior representa la API moderna (compatible con Unicode) del paquete de correo electrónico. Las secciones restantes, comenzando con la clase Message, cubren la API compat32 heredada que trata mucho más directamente con los detalles de cómo se representan los mensajes de correo electrónico. La API compat32 no oculta los detalles de las RFC de la aplicación, pero para las aplicaciones que necesitan operar a ese nivel, pueden ser herramientas útiles. Esta documentación también es relevante para las aplicaciones que todavía usan la API compat32 por razones de compatibilidad con versiones anteriores.

Distinto en la versión 3.6: Documentos reorganizados y reescritos para promover la nueva API EmailMessage/EmailPolicy.

Contenido de la documentación del paquete email:

email.message: Representando un mensaje de correo electrónico

email.parser: Analizar mensajes de correo electrónico

API FeedParser

API Parser

Notas adicionales

email.generator: Generando documentos MIME

email.policy: Objetos Policy

email.errors: Clases de excepción y defecto

email.headerregistry: Objetos de encabezado personalizados

email.contentmanager: Gestión de contenido MIME

Instancias gestoras de contenido

email: Ejemplos

API heredada:

email.message.Message: Representar un mensaje de correo electrónico usando la API compat32

email.mime: Creación de correo electrónico y objetos MIME desde cero

email.header: Cabeceras internacionalizadas

email.charset: Representa conjunto de caracteres

email.encoders: Codificadores

email.utils: Utilidades misceláneas

email.iterators: Iteradores

Ver también

Módulo smtplib

Cliente SMTP (Protocolo simple de transporte de correo)

Módulo poplib

Cliente POP (Protocolo de oficina postal)

Módulo imaplib

Cliente IMAP (Protocolo de acceso a mensajes de Internet)

Módulo nntplib

Cliente NNTP (Protocolo de transporte de noticias de red)

Módulo mailbox

Herramientas para crear, leer y administrar colecciones de mensajes en disco utilizando una variedad de formatos estándar.

Módulo smtpd

Marco del servidor SMTP (principalmente útil para pruebas)

email.message: Representando un mensaje de correo electrónico

Código fuente: Lib/email/message.py [https://github.com/python/cpython/tree/3.9/Lib/email/message.py]

Nuevo en la versión 3.6: 1

La clase central en el paquete de email es la clase EmailMessage, importada desde el módulo email.message. Esta es la clase base para el modelo de objeto email. EmailMessage provee la funcionalidad clave para configurar y consultar las cabeceras, para acceder al cuerpo del mensaje, y para crear o modificar la estructura del mensaje.

Un mensaje de correo electrónico consiste en headers y un payload (al que también nos referimos como content). Headers como RFC 5322 [https://tools.ietf.org/html/rfc5322.html] o RFC 6532 [https://tools.ietf.org/html/rfc6532.html] son nombres de campos de estilo y valores, donde el nombre y valor están separados por un “:”. Los dos puntos no son parte ni del nombre ni del valor. El payload puede ser un simple mensaje, un objeto binario, o una secuencia estructurada de sub-mensajes, cada uno con su propio conjunto de headers y su propio payload. El último tipo de payload es indicado por el mensaje con un MIME como multipart/* o message/rfc822 .

El modelo conceptual provisto por un objeto EmailMessage es el de un diccionario ordenado de cabeceras emparejadas con una carga útil que representa al cuerpo del mensaje RFC 5322 [https://tools.ietf.org/html/rfc5322.html], que podría ser una lista de objetos sub-EmailMessage. Además de los métodos normales de diccionario para acceder a las cabeceras y valores, tiene métodos para acceder a información especializada desde las cabeceras (por ejemplo, el tipo de contenido MIME), para operar en la carga útil, generar una versión serializada del mensaje, y recorrer recursivamente el árbol de objetos.

La interfaz tipo diccionario de EmailMessage está indexada por los nombres de las cabeceras, que deberán ser valores ASCII. Los valores del diccionario son cadenas con algunos métodos adicionales. Las cabeceras son almacenadas y retornadas de forma sensible a mayúsculas, pero los nombres de los campos son comparados sin discriminar entre mayúsculas. A diferencia de un dict real, las llaves están ordenadas y pueden estar duplicadas. Se proveen métodos adicionales para trabajar con cabeceras que tienen llaves duplicadas.

La carga útil es un objeto de cadena de caracteres o bytes, en el caso de objetos de mensaje simples, o una lista de objetos EmailMessage, para documentos de contenedor MIME como multipart/* y objetos de mensaje message/rfc822.

class email.message.EmailMessage(policy=default)

Si se especifica policy, use las reglas especificadas para actualizar y serializar la representación del mensaje. Si la política no es establecida, use default, que sigue las reglas RFC de email excepto para el fin de línea(en lugar del RFC \r\n, usa los finales estándar de Python \n como final de línea). Para más información ve a la documentación del policy.

as_string(unixfrom=False, maxheaderlen=None, policy=None)

Retorna el mensaje entero como cadena de caracteres. Cuando la opción unixform es verdadera, la cabecera está incluida en la cadena de caracteres retornada. unixform está predeterminado con valor False. Por compatibilidad con versiones anteriores, la base Message, la case maxheaderlen es aceptada pero con valor None como predeterminado, por lo que la longitud de línea se controla mediante max_line_length. El argumento policy puede ser usado para anular el valor predeterminado obtenido de la instancia del mensaje. Esto puede ser usado para controlar parte del formato producido por el método, ya que la política especificada pasará a Generator.

Aplanar el mensaje puede acarrear cambios en EmailMessage si es necesario rellenar los valores predeterminados para completar la transformación a una cadena de caracteres (por ejemplo, se pueden generar o modificar límites MIME).

Tenga en cuenta que este método se proporciona como una comodidad y quizás no sea la forma más eficiente de serializar mensajes en su aplicación, especialmente si estás tratando con múltiples mensajes. Consulte Generator por una API más flexible para serializar mensajes. No olvide también que este método está restringido a producir mensajes serializados como «7 bit clean» cuando utf8 es False, que es el valor predeterminado.

Distinto en la versión 3.6: el comportamiento predeterminado cuando maxheaderlen no está especificado cambió de 0 al valor de max_line_length de la política .

__str__()

Equivalente a as_string(policy=self.policy.clone(utf8=True)). Permite str(msg) para producir una cadena que contenga un mensaje serializado en un formato legible.

Distinto en la versión 3.4: el método se cambió para usar utf8=True, produciendo así un RFC 6531 [https://tools.ietf.org/html/rfc6531.html] como representación del mensaje, en vez de ser un alias de as_string().

as_bytes(unixfrom=False, policy=None)

Retorna el mensaje plano como un objeto de bytes. Cuando unixform es verdadero, la cabecera es incluida en la cadena de caracteres retornada. El valor predeterminado de unixform es False. El argumento policy puede ser usado para sobreescribir el valor predeterminado obtenido de la instancia del mensaje. Esto puede ser usado para controlar parte del formato producido por el método, ya que la política especificada pasará a Generator.

Aplanar el mensaje puede acarrear cambios en EmailMessage si es necesario rellenar los valores predeterminados para completar la transformación a una cadena de caracteres (por ejemplo, se pueden generar o modificar límites MIME).

Tenga en cuenta que este método se proporciona como una comodidad y quizás no sea la forma más eficiente de serializar mensajes en su aplicación, especialmente si estas tratando con múltiples mensajes. Consulte Generator por una API más flexible para serializar mensajes.

__bytes__()

Equivalente a as_bytes(). Permite bytes(msg) para producir un objeto byte que contenga el mensaje serializado.

is_multipart()

Retorna True si la carga útil del mensaje es una lista de objetos de sub-EmailMessage, de otra manera retorna False. Cuando is_multipart() retorna False, la carga útil deberá ser un objeto cadena de caracteres (que podría ser una carga útil binaria codificada con CTE). Note que si is_multipart() retorna True no necesariamente significa que «msg.get_content_maintype() == “multipart”» retornará True. Por ejemplo, is_multipart retornará True cuando la EmailMessage sea del tipo message/rfc822.

set_unixfrom(unixfrom)

Configura la cabecera del mensaje a unixform, que debería ser una cadena de caracteres. (Consulte mboxMessage para una descripción de esta cabecera)

get_unixfrom()

Retorna la cabecera del mensaje. Predeterminado None si la cabecera no ha sido configurada.

Los siguientes métodos implementan el mapeo como una interfaz para acceder a la cabecera del mensaje. Tenga en cuenta que hay algunas diferencias semánticas entre esos métodos y una interfaz de mapeo normal(es decir, diccionario). Por ejemplo, en un diccionario no hay claves duplicadas, pero pueden haber cabeceras duplicadas. Además, en los diccionarios no hay un orden garantizado para las claves retornadas por keys(), pero en un objeto EmailMessage, las cabeceras siempre regresan en orden de aparición en el mensaje original, o en el que fueron agregadas luego. Cualquier cabecera borrada y vuelta a añadir siempre se agrega al final de la lista.

Estas diferencias semánticas son intencionales y están sesgadas hacia la conveniencia en los casos de uso más comunes.

Note que en todos los casos, cualquier cabecera presente en el mensaje no se incluye en la interfaz de mapeo.

__len__()

Retorna el número total de cabeceras, incluidas las duplicadas.

__contains__(name)

Retorna True si el objeto del mensaje tiene un campo llamado “nombre”. La comparación se realiza sin tener en cuenta mayúsculas o minúsculas y “nombre” no incluye “:”. Se utiliza para el operador in Por ejemplo:

if 'message-id' in myMessage:
   print('Message-ID:', myMessage['message-id'])

__getitem__(name)

Retorna el valor de la cabecera nombrada. name no incluye el separador de dos puntos, “:”. Si la cabecera se pierde, regresa None, un KeyError no se genera nunca.

Tenga en cuenta que si el campo nombrado aparece más de una vez en la cabecera del mensaje, esa cantidad de veces el valor regresado será indefinido. Use el método get_all() para obtener los valores de todas las cabeceras existentes llamadas name.

Usando el standard non-“compat32”, el valor regresado es una instancia de una subclase de email.headerregistry.BaseHeader.

__setitem__(name, val)

Agrega una cabecera al mensaje con un campo “nombre” y un valor “val”. El campo se agrega al final de las cabeceras existentes en el mensaje.

Tenga en cuenta que esto no sobrescribe ni borra ninguna cabecera con el mismo nombre. Si quiere asegurarse de que la nueva cabecera es la única en el mensaje con el campo “nombre”, borre el campo primero, por ejemplo:

del msg['subject']
msg['subject'] = 'Python roolz!'

Si el policy define ciertas cabeceras para ser únicos(como lo hace el standard), este método puede generar un ValueError cuando se intenta asignar un valor a una cabecera preexistente. Este comportamiento es intencional por consistencia, pero no dependa de ello, ya que podemos optar por hacer que tales asignaciones eliminen la cabecera en el futuro.

__delitem__(name)

Elimine todas las apariciones del campo “nombre” de las cabeceras del mensaje. No se genera ninguna excepción si el campo nombrado no está presente en las cabeceras.

keys()

Retorna una lista de los nombres de todos los campos de la cabecera del mensaje.

values()

Retorna una lista de todos los valores de los campos del mensaje.

items()

Retorna una lista de tuplas de dos elementos que contienen todos los campos cabeceras y valores del mensaje.

get(name, failobj=None)

Retorna el valor de la cabecera nombrada. Esto es idéntico a __getitem__() excepto que el opcional failobj es retornado si no se encuentra la cabecera nombrada (failobj es por defecto None).

Aquí hay algunos métodos adicionales útiles relacionados con la cabecera:

get_all(name, failobj=None)

Retorna una lista de todos los valores para el campo nombre. Si no se nombran tales cabeceras en el mensaje, regresa failobj (por defecto None)

add_header(_name, _value, **_params)

Configuración extendida de cabeceras. Este método es similar a __setitem__(), excepto que se pueden proporcionar parámetros de cabecera adicionales como argumentos de palabras clave.

Por cada ítem en los parámetros del diccionario _params, la clave se toma como el nombre del parámetro, con barra baja (“_”) convertidos a guiones (“-”) (ya que en Python no se permiten “-” como identificadores). Normalmente, el parámetro debe ser añadido como key='value' a menos que el valor sea None, en ese caso solo la clave debe ser añadida.

Si el valor contiene caracteres no-ASCII, el charset y el lenguaje deben ser controlados especificando el valor como una triple tupla en formato (CHARSET, LANGUAJE, VALUE), donde CHARSET es una string llamando al charset usado para codificar el valor, LANGUAJE generalmente se establece en None o en una cadena de caracteres vacía (consulte RFC 2231 [https://tools.ietf.org/html/rfc2231.html] para más opciones), y VALUE es el valor de la cadena de caracteres que contiene puntos de código no-ASCII. Si la triple tupla no pasa y el valor contiene caracteres no-ASCII, es automáticamente codificada en formato RFC 2231 [https://tools.ietf.org/html/rfc2231.html], usando CHARSET de utf-8 y LANGUAJE None.

Aquí hay un ejemplo:

msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')

Esto agregará una cabecera que se ve como:

Content-Disposition: attachment; filename="bud.gif"

Un ejemplo de la interfaz extendida con caracteres no-ASCII:

msg.add_header('Content-Disposition', 'attachment',
               filename=('iso-8859-1', '', 'Fußballer.ppt'))

replace_header(_name, _value)

Reemplaza una cabecera. Reemplaza la primer cabecera encontrada en el mensaje que coincida con _name, conservando el orden de cabeceras y uso de minúsculas (y mayúsculas) del nombre de campo de la cabecera original. Si no hay coincidencia, se lanzará un KeyError.

get_content_type()

Retorna el tipo de contenido del mensaje, pasado a minúsculas de la forma maintype/subtype. Si no hay cabecera llamada Content-Type en el mensaje, regresa el valor de get_default_type(). Si Content-Type no es válido, retorna text/plain.

(De acuerdo con RFC 2045 [https://tools.ietf.org/html/rfc2045.html], los mensajes siempre tienen un tipo predeterminado, get_content_type`siempre retornará un valor. :rfc:`2045`define el tipo predeterminado de un mensaje como :mimetype:`text/plain() a menos que aparezca dentro de un contenedor multipart/digest, en cuyo caso sería message/rfc822. Si la cabecera Content-Type tiene una especificación de tipo que sea inválida, RFC 2045 [https://tools.ietf.org/html/rfc2045.html] exige que el tipo predeterminado sea text/plain.)

get_content_maintype()

Retorna el tipo de contenido principal del mensaje. Esta es la parte maintype de la cadena retornada por get_content_type().

get_content_subtype()

Retorna el tipo del sub-contenido del mensaje. Esta es la parte subtype de la cadena retornada por get_content_type().

get_default_type()

Retorna el tipo de contenido predeterminado. La mayoría de los mensajes tienen como tipo de contenido predeterminado a text/plain, a excepción de los mensajes que son sub-partes de contenedores multipart/digest. Estas sub-partes tienen como tipo de contenido predeterminado a message/rfc822.

set_default_type(ctype)

Establece el tipo de contenido predeterminado. ctype debería ser text/plain o message/rfc822, aunque esto no está impuesto. El tipo de contenido predeterminado no se almacena en la cabecera Content-Type, así que sólo afecta al valor de retorno de los métodos get_content_type cuando ninguna cabecera Content-Type está presente en el mensaje.

set_param(param, value, header='Content-Type', requote=True, charset=None, language='', replace=False)

Establece un parámetro en el encabezado Content-Type. Si el parámetro ya existe en el encabezado, reemplace su valor con value. Cuando header es Content-Type (el predeterminado) y el encabezado aún no existe en el mensaje, agréguelo, establece su valor en text/plain y agregue el nuevo valor del parámetro. header opcional especifica un encabezado alternativo a Content-Type.

Si el valor contiene caracteres non-ASCII, el charset y el lenguaje pueden ser especificados explícitamente con los parámetros charset y language. Opcionalmente language especifica el lenguaje RFC 2231 [https://tools.ietf.org/html/rfc2231.html], por defecto una cadena vacía. Ambos charset y language deberán ser cadenas. los valores predeterminados son utf8 para charset y None para language.

Si replace es False (predeterminado) la cabecera se mueve al final de la lista de cabeceras. Si replace es True, la cabecera se actualizará en su lugar.

El uso del parámetro requote con objetos EmailMessage está obsoleto.

Tenga en cuenta que se puede acceder a los parámetros existentes de las cabeceras a través del atributo params de la cabecera (por ejemplo, msg['Content-Type'].params['charset']).

Distinto en la versión 3.4: Se agregó la palabra clave replace.

del_param(param, header='content-type', requote=True)

Elimina completamente el parámetro dado de la cabecera Content-Type. La cabecera será reescrita en su lugar, sin el parámetro o su valor. Opcionalmente header especifica una alternativa a Content-Type.

El uso del parámetro requote con objetos EmailMessage está obsoleto.

get_filename(failobj=None)

Retorna el valor del parámetro filename de la cabecera Content-Disposition del mensaje. Si la cabecera no tiene un parámetro filename, este método recae a buscar el parámetro name en la cabecera Content-Type. Si ninguno se encuentra o falta la cabecera, se retorna failobj. La cadena retornada siempre estará sin comillas según email.utils.unquote().

get_boundary(failobj=None)

Retorna el parámetro boundary de la cabecera Content-Type del mensaje, o failobj si la cabecera no se encuentra o si no tiene un parámetro boundary. La cadena retornada siempre estará sin comillas según email.utils.unquote().

set_boundary(boundary)

Establece el parámetro boundary de la cabecera Content-Type como boundary. set_boundary() siempre que sea necesario pondrá comillas a boundary. Si el objeto mensaje no tiene cabecera Content-Type se lanza HeaderParseError.

Note que usar este método es sutilmente diferente a borrar la cabecera Content-Type antigua y agregar una nueva con el nuevo límite utilizando add_header(), porque set_boundary() preserva el orden de la cabecera Content-Type en la lista de cabeceras.

get_content_charset(failobj=None)

Retorna el parámetro charset de la cabecera Content-Type`forzado a minúsculas. Si no hay una cabecera :mailheader:`Content-Type, o si esa cabecera no tiene el parámetro charset, se retorna failobj.

get_charsets(failobj=None)

Retorna una lista que contiene los nombres de los charset en el mensaje. Si el mensaje es multipart, la lista contendrá un elemento por cada subparte en la carga útil, de lo contrario será una lista de longitud 1.

Cada elemento de la lista será una cadena que tendrá el valor del parámetro charset en la cabecera Content-Type para la subparte representada. Si la subparte no tiene cabecera Content-Type, no tiene parámetro charset, o no es del tipo MIME principal text, entonces ese elemento en la lista retornada será failobj.

is_attachment()

Retorna True si hay una cabecera Content-Disposition y su valor (sensible a mayúsculas) es attachment, de lo contrario retorna False.

Distinto en la versión 3.4.2: is_attachment ahora es un método en lugar de una propiedad, por consistencia con is_multipart().

get_content_disposition()

Retorna el valor en minúsculas (sin parámetros) de la cabecera Content-Disposition si el mensaje la tiene, de lo contrario retorna None. Los valores posibles para este método son inline, attachment o None si el mensaje sigue RFC 2183 [https://tools.ietf.org/html/rfc2183.html].

Nuevo en la versión 3.5.

Los siguientes métodos se refieren a interrogar y manipular el contenido (payload) del mensaje.

walk()

El método walk() es un generador multipropósito que puede usarse para iterar sobre todas las partes y subpartes del árbol de un objeto mensaje, ordenando el recorrido en profundidad primero. Típicamente se usaría walk() como el iterador en un ciclo for; cada iteración retornará la siguiente subparte.

Aquí hay un ejemplo que imprime el tipo MIME de cada parte de una estructura de mensaje de varias partes:

>>> for part in msg.walk():
...     print(part.get_content_type())
multipart/report
text/plain
message/delivery-status
text/plain
text/plain
message/rfc822
text/plain

walk itera sobre las subpartes de cualquier parte donde is_multipart() retorna True, aun si msg.get_content_maintype() == 'multipart' pueda retornar False. Podemos ver esto en nuestro ejemplo al hacer uso de la función auxiliar de depuración _structure:

>>> from email.iterators import _structure
>>> for part in msg.walk():
...     print(part.get_content_maintype() == 'multipart',
...           part.is_multipart())
True True
False False
False True
False False
False False
False True
False False
>>> _structure(msg)
multipart/report
    text/plain
    message/delivery-status
        text/plain
        text/plain
    message/rfc822
        text/plain

Aquí las partes message no son multiparts, pero sí contienen subpartes. is_multipart()``retorna ``True y walk desciende a las subpartes.

get_body(preferencelist=('related', 'html', 'plain'))

Retorna la parte MIME que es la mejor candidata para ser el «cuerpo» del mensaje.

preferencelist debe ser una secuencia de cadenas del conjunto related, html, y plain, e Indica el orden de preferencia para el tipo de contenido de la parte retornada.

Empieza a buscar coincidencias candidatas con el objeto en el que se llama al método get_body”.

Si related no está incluido en la preferencelist, considere la parte raíz (o subparte de la parte raíz) de cualquier relacionado encontrado como candidato si la (sub-)parte coincide con una preferencia.

Cuando se encuentra una multipart/related, verifica el parámetro start y si se encuentra una parte con un Content-ID que coincida, considera solamente a ésta cuando se busca coincidencias candidatas. De otra forma considera sólo la primera parte (predeterminado root) de la multipart/related.

Si una parte tiene una cabecera Content-Disposition , sólo se considera a ésta parte como coincidencia candidata si el valor de la cabecera es inline.

Si ninguno de los candidatos coincide con ninguna de las preferencias en preferencelist, retorna None.

Notas: (1) Para la mayoría de las aplicaciones las únicas combinaciones de preferencelist que realmente tienen sentido son ('plain',), ('html', 'plain'), y la predeterminada ('related', 'html', 'plain'). (2) Debido a que la coincidencia comienza con el objeto en el que se llama a get_body, llamar a get_body en un multipart/related devolverá el objeto en sí a menos que la preferencelist tenga un valor no predeterminado. (3) Los mensajes (o partes de mensajes) que no especifican un Content-Type o cuya cabecera Content-Type sea inválida se tratarán como si fueran del tipo text/plain, que ocasionalmente puede ocasionar que get_body retorne resultados inesperados.

iter_attachments()

Devuelve un iterador sobre todas las subpartes inmediatas del mensaje que no son partes candidatas del «body». Es decir, omitir la primer ocurrencia de cada text/plain, text/html, multipart/related, o multipart/alternative``(a menos que estén marcados explícitamente como adjuntos a través de :mailheader:`Content-Disposition: attachment`) y retornar todas las partes restantes. Cuando se aplica directamente a un ``multipart/related, retorna un iterador sobre todas las partes relacionadas excepto la parte raíz (es decir, la parte apuntada por el parámetro start , o la primera parte si no hay un parámetro start o el parámetro start no coincide con el Content-ID de ninguna de las partes). Cuando se aplica directamente a un multipart/alternative o a un no-multipart, retorna un iterador vacío.

iter_parts()

Retorna un iterador sobre todas las partes inmediatas del mensaje, que estará vacío para una no-multipart. (vea también walk().)

get_content(*args, content_manager=None, **kw)

Llama al método get_content() del content_manager, pasando self como el objeto del mensaje y pasando cualquier otro argumento o palabra clave como argumentos adicionales. Si no se especifica content_manager se usa el content_manager especificado por la policy actual.

set_content(*args, content_manager=None, **kw)

Llama al método set_content() del content_manager, pasando self como el objeto message y pasando cualquier otro argumento o palabra clave como argumentos adicionales. Si no se especifica content_manager se usa el content_manager especificado por la policy actual.

make_related(boundary=None)

Convierte un mensaje no-multipart a un mensaje multipart/related, moviendo cualquier cabecera Content- y la carga útil a una (nueva) primera parte del multipart. Si boundary se especifica, se utiliza como la cadena límite en el multipart, de otra forma deja que el límite se cree automáticamente cuando se necesite (por ejemplo, cuando se serializa el mensaje).

make_alternative(boundary=None)

Convierte un mensaje no-multipart o un mensaje multipart/related a uno multipart/alternative``moviendo cualquier cabecera :mailheader:`Content-` y la carga útil existentes a una (nueva) primera parte del ``multipart. Si boundary se especifica, se utiliza como la cadena límite en el multipart, de otra forma deja que el límite se cree automáticamente cuando se necesite (por ejemplo, cuando se serializa el mensaje).

make_mixed(boundary=None)

Convierte un mensaje no-multipart, multipart/related o multipart-alternative a uno multipart/mixed moviendo cualquier cabecera Content- y la carga útil existentes a una (nueva) primera parte del multipart. Si boundary se especifica, se utiliza como la cadena límite en el multipart, de otra forma deja que el límite se cree automáticamente cuando se necesite (por ejemplo, cuando se serializa el mensaje).

add_related(*args, content_manager=None, **kw)

Si el mensaje es un multipart/related, crea un nuevo objeto mensaje, pasa todos los argumentos a su método set_content() y lo une al multipart con attach(). Si el mensaje es un no-multipart, llama a make_related() y procede como arriba. Si el mensaje es cualquier otro tipo de multipart, lanza TypeError. Si content_manager no es especificado, usa el content_manager especificado por la policy actual. Si la parte agregada no tiene un encabezado Content-Disposition, se agrega uno con el valor inline.

add_alternative(*args, content_manager=None, **kw)

Si el mensaje es un multipart/alternative, crea un nuevo objeto mensaje, pasa todos los argumentos a su método set_content() y lo une al multipart con attach(). Si el mensaje es un no-multipart o multipart/related, llama a make_alternative() y procede como arriba. Si el mensaje es cualquier otro tipo de multipart, lanza TypeError. Si content_manager no es especificado, usa el content_manager especificado por la policy actual.

add_attachment(*args, content_manager=None, **kw)

Si el mensaje es un multipart/mixed, cree un nuevo objeto de mensaje, pase todos los argumentos a su método set_content() y attach() al multipart. Si el mensaje no es multipart, multipart/related o multipart/alternative, llame make_mixed() y luego proceda como se indicó anteriormente. Si no se especifica content_manager, use el content_manager especificado por el actual policy. Si la parte agregada no tiene encabezado Content-Disposition, agregue uno con el valor attachment. Este método se puede utilizar tanto para adjuntos explícitos (Content-Disposition: attachment) como para adjuntos inline (Content-Disposition: inline), pasando las opciones apropiadas al content_manager.

clear()

Elimina la carga útil y todas las cabeceras.

clear_content()

Elimina la carga útil y todos los Content- headers, dejando a las demás cabeceras intactas y en su orden original.

Los objetos EmailMessage tienen los siguientes atributos de instancia:

preamble

El formato de un documento MIME permite algo de texto entre la linea en blanco después de las cabeceras y la primera cadena límite de multiparte. Normalmente, este texto nunca es visible en un lector de correo compatible con MIME porque queda fuera de la armadura MIME estándar. Sin embargo, al ver el texto sin formato del mensaje, o al ver el mensaje en un lector no compatible con MIME, este texto puede volverse visible.

El atributo preamble contiene este texto extra para documentos MIME. Cuando el Parser descubre texto después de las cabeceras pero antes de la primer cadena límite, asigna este texto al atributo preamble del mensaje. Cuando el Generator escribe la representación de texto sin formato de un mensaje MIME y encuentra que el mensaje tiene un atributo preamble escribirá este texto en el área entre las cabeceras y el primer límite. Véase email.parser y email.generator para conocer detalles.

Cabe señalar que si el objeto message no tiene preámbulo, el atributo preamble será igual a None.

epilogue

El atributo epilogue actúa de igual forma al atributo preamble con la excepción de que contiene texto que aparece entre el último límite y el fin del mensaje. Como con el preamble, si no hay texto de epílogo este atributo será None.

defects

El atributo defects contiene una lista de todos los errores encontrados al hacer el análisis sintáctico del mensaje. Vea email.errors para una descripción detallada de los posibles efectos del análisis sintáctico.

class email.message.MIMEPart(policy=default)

Esta clase representa una subparte de un mensaje MIME. Es idéntica a EmailMessage, excepto que las cabeceras MIME-Version son añadidas cuando se llama a set_content(), ya que las subpartes no necesitan su propia cabecera MIME-Version.

Notas al pie

1

Añadido originalmente en la versión 3.4 como un módulo provisional. La documentación para la clase heredada message se movió a email.message.Message: Representar un mensaje de correo electrónico usando la API compat32.

email.parser: Analizar mensajes de correo electrónico

Código fuente: Lib/email/parser.py [https://github.com/python/cpython/tree/3.9/Lib/email/parser.py]

Se pueden construir estructuras de objetos de mensaje de dos formas: pueden ser creados de puro invento al crear un objeto EmailMessage, añadir encabezados usando la interfaz de diccionario, y añadir carga(s) usando el método set_content() y otros relacionados, o pueden ser creados al analizar una representación serializada de un mensaje de correo electrónico.

El paquete email proporciona un analizador estándar que entiende la mayoría de estructuras de documentos de correo electrónico, incluyendo documentos MIME. Le puedes pasar al analizador bytes, una cadena de caracteres o una archivo de objeto, y el analizador te retornará la instancia EmailMessage raíz de la estructura del objeto. Para mensajes simples que no sean MIME, la carga de su objeto raíz probablemente será una cadena de caracteres conteniendo el texto o el mensaje. Para mensajes MIME, el objeto raíz retornará True de su método is_multipart(), y las subpartes pueden ser accedidas a través de los métodos de manipulación de carga, tales como get_body(), iter_parts(), y walk().

De hecho hay dos interfaces de analizadores disponibles para usar, la API Parser y la API progresiva FeedParser. La API Parser es más útil si tú tienes el texto del mensaje entero en memoria, o si el mensaje entero reside en un archivo en el sistema. FeedParser es más apropiado cuando estás leyendo el mensaje de un stream que puede ser bloqueado esperando más entrada (tal como leer un mensaje de correo electrónico de un socket). El FeedParser puede consumir y analizar el mensaje de forma progresiva, y sólo retorna el objeto raíz cuando cierras el analizador.

Tenga en cuenta que el analizador puede ser extendido en formas limitadas, y por supuesto puedes implementar tu propio analizador completamente desde cero. Toda la lógica que conecta el analizador empaquetado del paquete email y la clase EmailMessage está encarnada en la clase policy, por lo que un analizador personalizado puede crear árboles de objetos mensaje en cualquier forma que encuentre necesario al implementar versiones personalizadas de los métodos apropiados de policy.

API FeedParser

La clase BytesFeedParser, importado del módulo email.feedparser, proporciona una API que es propicia para el análisis progresivo de mensajes de correo electrónico, tal como sería necesario cuando se esté leyendo el texto de un mensaje de correo electrónico de una fuente que puede bloquear (tal como un socket). Desde luego se puede usar la clase BytesFeedParser para analizar un mensaje de correo electrónico completamente contenido en un bytes-like object, cadena de caracteres, o archivo, pero la API BytesParser puede ser más conveniente para tales casos de uso. Las semánticas y resultados de las dos API de los analizadores son idénticas.

La API de BytesFeedParser es simple; puedes crear una instancia, le proporcionas un montón de bytes hasta que no haya más necesidad de hacerlo, entonces cierras el analizador para recuperar el objeto del mensaje raíz. El BytesFeedParser es extremadamente preciso cuando está analizando mensajes conformes al estándar, y hace un buen trabajo al analizar mensajes no conformes, proporcionando información acerca de cómo un mensaje fue considerado inservible. Ingresará una lista de cualquier problema que encontró en el atributo defects del objeto mensaje. Véase el módulo email.errors para la lista de defectos que puede encontrar.

Aquí está el API para BytesFeedParser:

class email.parser.BytesFeedParser(_factory=None, *, policy=policy.compat32)

Crea una instancia de BytesFeedParser. El argumento opcional _factory es un invocable sin argumentos; si no se especifica, usa el message_factory de policy. Llama a _factory cuando sea necesario un nuevo objeto mensaje.

Si se especifica policy, usa las reglas que especifica para actualizar la representación del mensaje. Si policy no está puesta, usa la política (policy) compat32, que mantiene compatibilidad con la versión 3.2 de Python del paquete de correo electrónico y proporciona a Message como la fábrica por defecto. Todas las otras políticas proveen a EmailMessage como el _factory por defecto. Para más información en lo demás que policy controla, véase la documentación policy.

Nota: La palabra clave *policy* siempre debe estar especificada; El valor por defecto cambiará a email.policy.default en una versión futura de Python.

Nuevo en la versión 3.2.

Distinto en la versión 3.3: Se añadió la palabra clave policy.

Distinto en la versión 3.6: _factory es por defecto la policy message_factory.

feed(data)

Le proporciona al analizador algunos datos más. data debe ser un bytes-like object conteniendo una o más líneas. Las líneas pueden ser parciales y el analizador va a juntar tales líneas parciales apropiadamente. las líneas pueden tener cualquiera de las tres terminaciones de línea comunes: retorno de cargo (retorno de cargo), nueva línea (newline), o retorno de cargo y nueva línea (pueden ser mezclados).

close()

Completa el análisis de todos los datos previamente proporcionados y retorna la raíz del objeto mensaje. No está definido lo que pasa si se llama a feed() después de que este método haya sido llamado.

class email.parser.FeedParser(_factory=None, *, policy=policy.compat32)

Funciona como BytesFeedParser excepto que la entrada al método feed() no debe ser una cadena de caracteres. Esto es utilidad limitada, ya que la única manera de que tal mensaje sea válido es que sólo contenga texto ASCII o, si utf8 es True, sin binarios adjuntos.

Distinto en la versión 3.3: Se añadió la palabra clave policy.

API Parser

La clase BytesParser, importado del módulo email.parser, proporciona una API que puede ser usada para analizar un mensaje cuando el contenido completo del mensaje esté disponible en un bytes-like object o archivo. El módulo email.parser también proporciona a Parser para analizar cadenas de caracteres, y analizadores de sólo cabeceras, BytesHeaderParser y HeaderParser que pueden ser usados si sólo estás interesado en las cabeceras del mensaje. BytesHeaderParser y HeaderParser puede ser más rápidos en estas situaciones, ya que no intentan analizar el cuerpo del mensaje, en vez de eso configuran la carga al cuerpo puro.

class email.parser.BytesParser(_class=None, *, policy=policy.compat32)

Crea una instancia de BytesParser. Los argumentos _class y policy tiene el mismo significado y semántica que los argumentos _factory y policy de BytesFeedParser.

Nota: La palabra clave *policy* siempre debe estar especificada; El valor por defecto cambiará a email.policy.default en una versión futura de Python.

Distinto en la versión 3.3: Se eliminó el argumento strict que fue deprecado en 2.4. Se añadió la palabra clave policy.

Distinto en la versión 3.6: _class es por defecto la política message_factory.

parse(fp, headersonly=False)

Lee todos los datos del objeto binario parecido a archivo fp, analiza los bytes resultantes, y retorna el objeto mensaje. fp debe soportar tanto el método readline() como el método read().

Los bytes contenidos en fp deben ser formateados como un bloque de cabeceras de estilo y líneas de continuación de cabecera de RFC 5322 [https://tools.ietf.org/html/rfc5322.html] (o, si utf8 es True, RFC 6532 [https://tools.ietf.org/html/rfc6532.html]). El bloque cabecera se termina o al final de los datos o por una línea blanca. Después del bloque de cabecera esta él cuerpo del mensaje (que puede contener subpartes codificadas como MIME, incluyendo subpartes con un Content-Transfer-Encoding de 8bit).

El argumento opcional headersonly es un flag que especifica si se debe analizar después de leer las cabeceras o no. El valor por defecto es False, significando que analiza el contenido entero del archivo.

parsebytes(bytes, headersonly=False)

Similar al método parse(), excepto que toma un bytes-like object en vez de un objeto similar a un archivo. Llamar a este método en un bytes-like object es equivalente a envolver a bytes en una instancia de BytesIO primero y llamar a parse().

El argumento opcional headersonly es como el método parse().

Nuevo en la versión 3.2.

class email.parser.BytesHeaderParser(_class=None, *, policy=policy.compat32)

Exactamente como BytesParser, excepto que headersonly es por defecto True.

Nuevo en la versión 3.3.

class email.parser.Parser(_class=None, *, policy=policy.compat32)

Esta clase es paralela a BytesParser, pero trata entradas de cadenas de caracteres.

Distinto en la versión 3.3: Se eliminó el argumento strict. Se añadió la palabra clave policy.

Distinto en la versión 3.6: _class es por defecto la política message_factory.

parse(fp, headersonly=False)

Lee todos los datos del modo texto del objeto parecido a archivo fp, analiza el texto resultante, y retorna el objeto mensaje raíz. fp debe soportar tanto el método readline() y el método read() en objetos parecidos a archivos.

Además de el requisito del modo texto, este método opera como BytesParser.parse().

parsestr(text, headersonly=False)

Similar al método parse(), excepto que toma un objeto de cadena de caracteres de un objeto similar a un archivo. Llamar a este método en una cadena de caracteres es equivalente a envolver a text en una instancia de StringIO primero y llamar a parse().

El argumento opcional headersonly es como el método parse().

class email.parser.HeaderParser(_class=None, *, policy=policy.compat32)

Exactamente como Parser, excepto que headersonly es por defecto True.

Ya que crear una estructura de un objeto mensaje de una cadena de caracteres o un objeto archivo es una tarea tan común, Se proporcionaron 4 funciones como una conveniencia. Están disponibles en paquete de espacio de nombres de alto nivel email.

email.message_from_bytes(s, _class=None, *, policy=policy.compat32)

Retorna una estructura del objeto mensaje de un bytes-like object. Esto es equivalente a BytesParser().parsebytes(s). El argumento opcional _class y policy son interpretados como sucede con el constructor de clase BytesParser.

Nuevo en la versión 3.2.

Distinto en la versión 3.3: Se eliminó el argumento strict. Se añadió la palabra clave policy.

email.message_from_binary_file(fp, _class=None, *, policy=policy.compat32)

Retorna una estructura árbol del objeto mensaje de un file object binario abierto. Esto es equivalente a BytesParser().parse(fp). _class y policy son interpretados como sucede con el constructor de clase BytesParser.

Nuevo en la versión 3.2.

Distinto en la versión 3.3: Se eliminó el argumento strict. Se añadió la palabra clave policy.

email.message_from_string(s, _class=None, *, policy=policy.compat32)

Retorna una estructura del objeto mensaje de una cadena de caracteres. Esto es equivalente a Parser().parsestr(s). _class y policy son interpretados como sucede con el constructor de clase Parser.

Distinto en la versión 3.3: Se eliminó el argumento strict. Se añadió la palabra clave policy.

email.message_from_file(fp, _class=None, *, policy=policy.compat32)

Retorna una estructura árbol del objeto mensaje de un file object abierto. Esto es equivalente a Parser().parse(fp). _class y policy son interpretados como sucede con el constructor de clase Parser.

Distinto en la versión 3.3: Se eliminó el argumento strict. Se añadió la palabra clave policy.

Distinto en la versión 3.6: _class es por defecto la política message_factory.

Aquí está un ejemplo de cómo puedes usar message_from_bytes() en una entrada interactiva de Python:

>>> import email
>>> msg = email.message_from_bytes(myBytes)

Notas adicionales

Aquí están algunas notas sobre la semántica del análisis:

La mayoría de los mensajes de tipo que no son multipart son actualizados como un solo objeto mensaje con una carga de cadena de caracteres. Estos objetos retornarán False para is_multipart(), y iter_parts() cederá (yield) una lista vacía.

Todos los mensajes de tipo multipart serán analizados como un objeto mensaje contenedor con una lista de objetos sub-mensajes para sus cargas. El mensaje del contenedor externo retornará True para is_multipart(), y iter_parts() cederá (yield) una lista de subpartes.

La mayoría de mensajes con una tipo de contenido de message/* (tal como message/delivery-status y message/rfc822) también serán analizados como objetos contenedores que contienen una lista de cargas de longitud 1. Su método is_multipart() retornará True. El único elemento cedido (yielded) por iter_parts() será un objeto sub-mensaje.

Algunos mensajes de conformidad no estándar pueden no ser internamente consistentes acerca de su multipart-idad. Tales mensajes pueden tener una cabecera Content-Type de tipo multipart, pero su método is_multipart() puede retornar False. Si tales mensajes son analizados con FeedParser, tendrán una instancia de la clase MultipartInvariantViolationDefect en su lista de atributos defects. Véase email.errors para más detalles.

email.generator: Generando documentos MIME

Código fuente: Lib/email/generator.py [https://github.com/python/cpython/tree/3.9/Lib/email/generator.py]

Una de las tareas más comunes es generar la versión plana (serializada) del mensaje de correo electrónico representado por una estructura de objeto de mensaje. Se tendrá que hacer esto si se desea enviar un mensaje a través de smtplib.SMTP.sendmail(), o el módulo nntplib, o imprimir el mensaje en la consola. Tomar una estructura de objeto de mensaje y producir una representación serializada es el trabajo de las clases generadoras.

Al igual que con el módulo email.parser, no se limita a la funcionalidad del generador incluido; se podría escribir uno desde cero. Sin embargo, el generador incluido sabe cómo generar la mayoría del correo electrónico de una manera compatible con los estándares, debería controlar los mensajes de correo electrónico MIME y no MIME bien. Está diseñado para que las operaciones de análisis y generación orientadas a bytes sean inversas, asumiendo que se utilice la misma policy de no transformación para ambos. Es decir, analizar la secuencia de bytes serializada a través de la clase BytesParser y, a continuación, regenerar la secuencia de bytes serializada mediante BytesGenerator debe producir una salida idéntica a la entrada 1. (Por otro lado, el uso del generador en un EmailMessage construido por el programa puede dar lugar a cambios en el objeto EmailMessage a medida que se rellenan los valores predeterminados.)

La clase Generator se puede utilizar para acoplar un mensaje en una representación serializada de texto (a diferencia de la binaria). Sin embargo, como Unicode no puede representar datos binarios directamente, el mensaje es necesariamente transformado en algo que contiene sólo caracteres ASCII. Se utiliza las técnicas de codificación de transferencia de contenido RFC de correo electrónico estándar para codificar mensajes de correo electrónico para el transporte a través de canales que no son «8 bits limpios».

Para adaptar procesamiento reproducible de mensajes firmados por SMIME, Generator deshabilita el encabezamiento para las partes del mensaje de tipo multipart/signed y todas sus subpartes.

class email.generator.BytesGenerator(outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)

Retorna un objeto BytesGenerator que escribirá cualquier mensaje provisto por el método flatten(), o cualquier texto de escape sustituto cifrado con el método write(), al file-like object outfp. outfp debe soportar un método``write`` que acepte datos binarios.

Si mangle_from_ opcional es True, se coloca un carácter “”>”” delante de cualquier línea del cuerpo que comience con la cadena exacta ““«From «””, es decir, “”From”” seguido de un espacio al principio de una línea. mangle_from_ vuelve de forma predeterminada al valor de la configuración mangle_from_ de la norma (que es “”True”” para la norma compat32 y “”False”” para todas las demás). mangle_from_ está diseñado para su uso cuando los mensajes se almacenan en formato unix mbox (consulte mailbox y WHY THE CONTENT-LENGTH FORMAT IS BAD [https://www.jwz.org/doc/content-length.html]).

Si maxheaderlen no es None, se repliega las líneas de encabezado que son mayores que maxheaderlen, o si es 0, no se reenvuelve ningún encabezado. Si manheaderlen es None (predeterminado), se envuelven los encabezados y otras líneas de mensajes de acuerdo a los ajustes de policy.

Si la norma es especificada, se usa esa norma para controlar la generación de mensajes. Si la norma es None (predeterminado), se usa la norma asociada con el Message o el objeto EmailMessage pasado para flatten para controlar la generación del mensaje. Se puede ver email.policy para detalles de que controla la norma.

Nuevo en la versión 3.2.

Distinto en la versión 3.3: Agregada la palabra clave norma.

Distinto en la versión 3.6: El comportamiento predeterminado de los parámetros mangle_from_ y maxheaderlen es para seguir la norma.

flatten(msg, unixfrom=False, linesep=None)

Imprime la representación textual de la estructura del objeto de mensaje originada en msg al archivo de salida especificado cuando se creó la instancia BytesGenerator.

Si el tipo cte_type de la opción policy :attr:””email.policy.Policy.cte_type” es “”8bit”” (valor predeterminado), se copia los encabezados en el mensaje analizado original que no se hayan modificado con ningún bytes a la salida con el conjunto de bits altos, reproducido como en el original, y se conserva el Content-Transfer-Encoding no ASCII de cualquier parte del cuerpo que los tenga. Si cte_type es 7bit, se convierte los bytes con el conjunto de bits altos según sea necesario utilizando un Content-Transfer-Encoding compatible con ASCII . Es decir, se transforma partes con Content-Transfer-Encoding no ASCII (Content-Transfer-Encoding: 8bit) en un conjunto de caracteres compatible con ASCII Content-Transfer-Encoding, y se codifica bytes inválidos RFC no ASCII en encabezados mediante el conjunto de caracteres MIME unknown-8bit, lo que los convierte en compatibles con RFC.

Si unixfrom es True, se imprime el delimitador de encabezado de sobre utilizado por el formato de buzón de correo Unix (consulta mailbox) antes del primero de los encabezados RFC 5322 [https://tools.ietf.org/html/rfc5322.html] del objeto de mensaje raíz. Si el objeto raíz no tiene encabezado de sobre, se crea uno estándar. El valor predeterminado es False. Tener en cuenta que para las subpartes, nunca se imprime ningún encabezado de sobre.

Si linesep no es None, se usa como caracter separador entre todas las líneas del mensaje acoplado. Si linesep es None (predeterminado), se usa el valor especificado en la norma.

clone(fp)

Retorna un clon independiente de esta instancia de BytesGenerator con las mismas configuraciones exactas, y fp como el nuevo outfp.

write(s)

Codifica s usando el códec ASCII u el manipulador de error escape sustituto, y lo pasa al método write del outfp pasado al constructor de la clase BytesGenerator.

Como conveniencia, EmailMessage provee los métodos as_bytes() y bytes(aMessage) (también conocido como __bytes__()) que simplifican la generación de la representación serializada binaria de un objeto mensaje. Para más detalle, ver email.message.

Dado que las cadenas de caracteres no pueden representar datos binarios, la clase Generator debe convertir los datos binarios en cualquier mensaje que aplane a un formato compatible con ASCII, convirtiéndolos en un Content-Transfer_Encoding compatible con ASCII. Usando la terminología de RFC de correo electrónico, se puede pensar en esto como Generator serializando a una secuencia de E/S que no es «8 bit clean». En otras palabras, la mayoría de las aplicaciones querrán usar BytesGenerator, y no Generator.

class email.generator.Generator(outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)

Retorna un objeto Generator que escribirá cualquier mensaje provisto al método flatten(), o cualquier texto provisto al método write(), al file-like object outfp. outfp debe soportar un método write que acepte datos de cadena de caracteres.

Si mangle_from_ opcional es True, se coloca un carácter “”>”” delante de cualquier línea del cuerpo que comience con la cadena exacta ““«From «””, es decir, “”From”” seguido de un espacio al principio de una línea. mangle_from_ vuelve de forma predeterminada al valor de la configuración mangle_from_ de la norma (que es “”True”” para la norma compat32 y “”False”” para todas las demás). mangle_from_ está diseñado para su uso cuando los mensajes se almacenan en formato unix mbox (consulte mailbox y WHY THE CONTENT-LENGTH FORMAT IS BAD [https://www.jwz.org/doc/content-length.html]).

Si maxheaderlen no es None, se repliega las líneas de encabezado que son mayores que maxheaderlen, o si es 0, no se reenvuelve ningún encabezado. Si manheaderlen es None (predeterminado), se envuelven los encabezados y otras líneas de mensajes de acuerdo a los ajustes de policy.

Si la norma es especificada, se usa esa norma para controlar la generación de mensajes. Si la norma es None (predeterminado), se usa la norma asociada con el Message o el objeto EmailMessage pasado para flatten para controlar la generación del mensaje. Se puede ver email.policy para detalles de que controla la norma.

Distinto en la versión 3.3: Agregada la palabra clave norma.

Distinto en la versión 3.6: El comportamiento predeterminado de los parámetros mangle_from_ y maxheaderlen es para seguir la norma.

flatten(msg, unixfrom=False, linesep=None)

Imprime la representación textual de la estructura del objeto de mensaje originado en el msg al archivo especificado de salida cuando la instancia de Generator fue creada.

Si la opción policy cte_type es 8bit, se genera el mensaje como si la opción estuviera establecida en 7bit. (Esto es necesario porque las cadenas de caracteres no pueden representar bytes que no sean ASCII). Convierte cualesquiera bytes con el conjunto de bits alto según sea necesario utilizando un Content-Transfer-Encoding compatible con ASCII. Es decir, transforma partes con Content-Transfer-Encoding (Content-Transfer-Encoding: 8bit) no ASCII en un conjunto de caracteres Content-Transfer-Encoding compatible con ASCII. Y codifica bytes no ASCII RFC inválidos ASCII en encabezados mediante el conjunto de caracteres MIME unknown-8bit, lo que los convierte en compatibles con RFC.

Si unixfrom es True, se imprime el delimitador de encabezado de sobre utilizado por el formato de buzón de correo Unix (consulta mailbox) antes del primero de los encabezados RFC 5322 [https://tools.ietf.org/html/rfc5322.html] del objeto de mensaje raíz. Si el objeto raíz no tiene encabezado de sobre, se crea uno estándar. El valor predeterminado es False. Tener en cuenta que para las subpartes, nunca se imprime ningún encabezado de sobre.

Si linesep no es None, se usa como caracter separador entre todas las líneas del mensaje acoplado. Si linesep es None (predeterminado), se usa el valor especificado en la norma.

Distinto en la versión 3.2: Agrega soporte para el recodificado de cuerpos de mensajes 8bit, y el argumento linesep.

clone(fp)

Retorna un clon independiente de esta instancia de Generator con las mismas opciones exactas y fp como la nueva outfp.

write(s)

Escribe s al método write del outfp pasado al constructor de la Generator. Esto provee justo la suficiente API de tipo archivo para instancias de Generator para ser usadas en la función print().

Para conveniencia, EmailMessage provee los métodos as_string() y str(aMessage) (también conocido como __str__()), que simplifican la generación de una representación de una cadena de caracteres formateada de un objeto mensaje. Para más detalles, ver email.message.

El módulo email.generator también provee una clase derivada, DecodedGenerator, la cual es como la clase base Generator, excepto que las partes no text no están serializadas, sino que en su lugar, están representadas en el flujo de salida por una cadena de caracteres derivada de una plantilla llenada con información sobre la parte.

class email.generator.DecodedGenerator(outfp, mangle_from_=None, maxheaderlen=None, fmt=None, *, policy=None)

Se actúa como Generator, excepto para cualquier subparte del mensaje pasado a Generator.flatten(), si la subparte es de tipo principal text, se imprime la carga útil decodificada de la subparte, y si el tipo principal no es text, en lugar de imprimirlo se rellena la cadena de caracteres fmt utilizando la información de la parte y se imprime la cadena de caracteres rellenada resultante.

Para llenar fmt, se ejecuta fmt % part_info, donde part_info es un diccionario compuesto por las siguientes claves y valores:

type – Todo el tipo MIME de la parte notext

maintype – Principal tipo MIME de la parte notext

subtype – Tipo sub-MIME de la parte no-text

filename – Nombre de archivo de la parte notext

description – Descripción asociada con la parte notext

encoding – Codificado de la transferencia del contenido de la parte no-text

Si fmt es None, se usa el siguiente fmt predeterminado:

«[Non-text (%(type)s) part of message omitted, filename %(filename)s]»

Los opcionales _mangle_from_ y maxheaderlen son como en la clase base Generator.

Notas al pie

1

Esta instrucción supone que se utiliza la configuración adecuada para unixfrom, y que no hay ninguna configuración policy que llame a ajustes automáticos (por ejemplo, refold_source debe ser none, que es no es el valor predeterminado). Esto tampoco es 100% verdadero, ya que si el mensaje no se ajusta a los estándares RFC ocasionalmente la información sobre el texto original exacto se pierde durante la el análisis de recuperación de errores. Es un objetivo fijar estos últimos casos extremos cuando sea posible.

email.policy: Objetos Policy

Nuevo en la versión 3.3.

Código fuente: Lib/email/policy.py [https://github.com/python/cpython/tree/3.9/Lib/email/policy.py]

El enfoque principal del paquete email es la gestión de mensajes de correo electrónico como se describe por los varios RFC de correos electrónicos y MIME. Sin embargo, el formato general de los mensajes de correo electrónico (un bloque de campos de cabecera cada uno consistiendo en un nombre seguido de dos puntos seguido de un valor, el bloque entero seguido por una línea blanca y un “cuerpo” arbitrario), es un formato que ha encontrado utilidad fuera del campo de correos electrónicos. Algunos de estos usos cumplen bastante cerca los RFC de correos electrónicos principales, alguno no. Incluso cuando se trabajo con correos electrónicos, hay veces cuando es deseable romper la estricta conformidad con los RFC, tal como generar correos electrónicos que se integran con servidores de correos electrónicos que no siguen los estándares, o que implementan extensiones que quieres usar en formas que violan los estándares.

Los objetos policy dan al paquete de correos electrónicos la flexibilidad de manejar todos estos casos de uso diversos.

Un objeto Policy encapsula un conjunto de atributos y métodos que controlan el comportamiento de varios componentes del paquete de correos electrónicos durante el uso. Las instancias Policy pueden ser pasadas a varias clases y métodos en el paquete de correos electrónicos para alterar el comportamiento por defecto. Los valores que se pueden configurar y sus valores por defecto se describen abajo.

Hay una policy por defecto usada por todas las clases en el paquete de correos electrónicos. Para todos las clases Parser y las funciones de conveniencia relacionadas, y para la clase Message, esta es una policy Compat32, a través de sus correspondientes instancias compat32 pre-definidas. Esta política mantiene una compatibilidad (en algunos casos, compatibilidad con los bugs) con el paquete de correos electrónicos de las versiones anteriores de Python3.3.

El valor por defecto para la palabra clave policy de EmailMessage es la policy EmailPolicy, a través de su instancia pre-definida default.

Cuando un objeto Message o EmailMessage es creado, adquiere un policy. Si el mensaje es creado por un parser, un policy pasado al analizador será el policy usado por el mensaje que cree. Si el mensaje es creado por el programa, entonces el policy puede ser especificado cuando sea creado. Cuando un mensaje es pasado a un generator, el generador usa el policy del mensaje por defecto, pero también puedes pasar un policy específico al generador que anulará el que está guardado en el objeto mensaje.

El valor por defecto del argumento por palabra clave policy para las clases email.parser y las funciones de conveniencia del analizador se cambiarán en una futura versión de Python. Por consiguiente, siempre debes especificar explícitamente qué policy quieres usar cuando se llama a cualquiera de las clases y funciones descritas en el módulo parser.

La primera parte de esta documentación cubre las características de Policy, un abstract base class que define las características que son comunes a todos los objetos policy, incluyendo compat32. Esto incluye ciertos métodos gancho (hook) que son llamados internamente por el paquete de correos electrónicos, que un policy personalizado puede invalidar para obtener un comportamiento diferente. La segunda parte describe las clases concretas EmailPolicy y Compat32, que implementan los ganchos (hooks) que proporcionan el comportamiento estándar y el comportamiento y características compatibles hacia atrás, respectivamente.

Las instancias Policy son inmutables, pero pueden ser clonadas, aceptando los mismos argumentos de palabra clave que el constructor de clase y retorna una nueva instancia Policy que es una copia del original pero con los valores de atributos específicos cambiados.

Como un ejemplo, el siguiente código puede ser usado para leer un mensaje de correo electrónico de un archivo en disco y pasarlo al programa de sistema sendmail en un sistema Unix:

>>> from email import message_from_binary_file
>>> from email.generator import BytesGenerator
>>> from email import policy
>>> from subprocess import Popen, PIPE
>>> with open('mymsg.txt', 'rb') as f:
...     msg = message_from_binary_file(f, policy=policy.default)
>>> p = Popen(['sendmail', msg['To'].addresses[0]], stdin=PIPE)
>>> g = BytesGenerator(p.stdin, policy=msg.policy.clone(linesep='\r\n'))
>>> g.flatten(msg)
>>> p.stdin.close()
>>> rc = p.wait()

Aquí le estamos diciendo a BytesGenerator que use los caracteres de separación de línea correctos de RFC cuando crea la cadena binaria para alimentar a stding de sendmail (sendmails's stdin), donde el policy por defecto usaría separadores de línea \n.

Algunos métodos del paquete de correos electrónicos aceptan un argumento de palabra clave policy, permitiendo que el policy pueda ser anulado para ese método. Por ejemplo, el siguiente código usa el método as_bytes() del objeto msg del ejemplo anterior y escribe el mensaje en un archivo usando los separadores de línea nativos para la plataforma en el que esté corriendo:

>>> import os
>>> with open('converted.txt', 'wb') as f:
...     f.write(msg.as_bytes(policy=msg.policy.clone(linesep=os.linesep)))
17

Los objetos policy puede ser combinados usando el operador de adición, produciendo un objeto policy cuya configuración es una combinación de los valores que de los objetos sumados:

>>> compat_SMTP = policy.compat32.clone(linesep='\r\n')
>>> compat_strict = policy.compat32.clone(raise_on_defect=True)
>>> compat_strict_SMTP = compat_SMTP + compat_strict

Esta operación no es conmutativa; es decir, el orden en el que los objetos son añadidos importa. Para ilustrar:

>>> policy100 = policy.compat32.clone(max_line_length=100)
>>> policy80 = policy.compat32.clone(max_line_length=80)
>>> apolicy = policy100 + policy80
>>> apolicy.max_line_length
80
>>> apolicy = policy80 + policy100
>>> apolicy.max_line_length
100

class email.policy.Policy(**kw)

Este es el abstract base class para todas las clases policy. Proporciona las implementaciones por defecto para un par de métodos triviales, también como la implementación de las propiedades de inmutabilidad, el método clone(), y las semánticas del constructor.

Se pueden pasar varios argumentos de palabra clave al constructor de una clase policy. Los argumentos que pueden ser especificados son cualquier propiedad que no sea método en esta clase, además de cualquier otra propiedad adicional que no sea método en la clase concreta. Un valor especificado en el constructor anulará el valor por defecto para los atributos correspondientes.

Esta clase define las siguientes propiedades, y por consiguiente los valores a continuación pueden ser pasados al constructor de cualquier clase policy:

max_line_length

El tamaño máximo de cualquier línea en la salida serializada, sin contar el fin de la línea de carácter(res). Por defecto es 78, por el RFC 5322 [https://tools.ietf.org/html/rfc5322.html]. Un valor de 0 o None indica que ningún envolvimiento de líneas puede ser hecha en lo más mínimo.

linesep

La cadena de caracteres a ser usada para terminar las líneas en una salida serializada. El valor por defecto es \n porque esa es la disciplina del fin de línea interna usada por Python, aunque \r\n es requerida por los RFCs.

cte_type

Controla el tipo de Codificaciones de Transferencia de Contenido que pueden ser o son necesarios para ser usados. Los valores posibles son:

7bit

todos los datos deben ser «compatibles con 7 bit (7 bit clean)» (ASCII-only). Esto significa que donde sea necesario, los datos serán codificados usando o codificación imprimible entre comillas o base64.

8bit

los datos no son limitados a ser compatibles con 7 bits (7 bit clean). Se requiere que los datos en las cabeceras todavía sean sólo ASCII y por lo tanto estarán codificadas (véase fold_binary() y utf8 abajo por las excepciones), pero las partes del cuerpo pueden usar 8bit CTE.

Un valor cte_type de `8bit sólo trabaja con BytesGenerator, no Generator, porque las cadenas no pueden contener datos binarios. Si un Generator está operando bajo un policy que especifica cte_type=8bit, actuará como si cte_type fuese 7bit.

raise_on_defect

Si es True, cualquier defecto encontrado será lanzado como error. Si es False (el valor por defecto), los defectos serán pasados al método register_defect().

mangle_from_

Si es True, las líneas empezando con «From « en el cuerpo son saltados al poner un > en frente de ellos. Este parámetro es usado cuando el mensaje está siendo serializado por un generador. El valor por defecto es: False.

Nuevo en la versión 3.5: El parámetro mangle_from_.

message_factory

Una función de fábrica para construir un nuevo objeto mensaje vacío. Usado por el analizador cuando construye mensajes. Por defecto es None, en cuyo caso Message es usado.

Nuevo en la versión 3.6.

El siguiente método de Policy está destinado a ser llamado por código usando la librería de correos electrónicos para crear instancias de policy con configuraciones personalizadas:

clone(**kw)

Retorna una nueva instancia de Policy cuyos atributos tienen los mismos valores que la instancia actual, excepto donde se le dan, a esos atributos, nuevos valores por los argumentos de palabra clave.

Los métodos de Policy restantes son llamados por el código de paquete de correos electrónicos, y no están destinados a ser llamados por una aplicación usando el paquete de correos electrónicos. Un policy personalizado debe implementar todos estos métodos.

handle_defect(obj, defect)

Trata un defect encontrado en obj. Cuando el paquete de correos electrónicos llama a este método, defect siempre será una subclase de Defect.

La implementación por defecto verifica la bandera raise_on_defect. Si es True, defect es lanzado como una excepción. Si es False (el valor por defecto), obj y defect son pasados a register_defect().

register_defect(obj, defect)

Registra un defect en obj. En el paquete de correos electrónicos, defect será siempre una subclase de Defect.

La implementación por defecto llama al método append del atributo defects de obj. Cuando un paquete de correos electrónicos llama a handle_defect, obj normalmente tendrá un atributo defects que tiene un método append. Los tipos de objetos personalizados usados con el paquete de correos electrónicos (por ejemplo, objetos Message personalizados) también deben proporcionar tal atributo, de otro modo, los defectos en los mensajes analizados levantarán errores no esperados.

header_max_count(name)

Retorna el máximo número permitido de cabeceras llamadas name.

Llamado cuando una cabecera es añadida a un objeto EmailMessage o Message. Si el valor retornado no es 0 o None, y ya hay un número de cabeceras con el nombre name mayor o igual que el valor retornado, un ValueError es lanzado.

Porque el comportamiento por defecto de Message.__setitem__ es agregar el valor a la lista de cabeceras, es fácil crear cabeceras duplicadas sin darse cuenta. Este método permite que ciertas cabeceras sean limitadas en el número de instancias de esa cabecera que puede ser agregada a Message programáticamente. (El límite no es observado por el analizador, que fielmente producirá tantas cabeceras como existen en el mensaje siendo analizado.)

La implementación por defecto retorna None para todos los nombres de cabeceras.

header_source_parse(sourcelines)

El paquete de correos electrónicos llama a este método con una lista de cadenas de caracteres, cada terminación de cadena con los caracteres de separación de línea encontrada en la fuente siendo analizada. La primera línea incluye el campo del nombre de cabecera y el separador. Todos los espacios en blanco en la fuente son preservados. El método debe retornar la tupla (name,value) que va a ser guardada en el Message para representar la cabecera analizada.

Si una implementación desea mantener compatibilidad con los policy del paquete de correos electrónicos existentes, name debe ser el nombre con las letras preservadas (todos los caracteres hasta el separador “:”), mientras que value debe ser el valor desdoblado (todos los caracteres de separación de líneas eliminados, pero los espacios en blanco intactos), privado de espacios en blanco al comienzo.

sourcelines puede contener datos binarios surrogateescaped.

No hay implementación por defecto

header_store_parse(name, value)

El paquete de correos electrónicos llama a este método con el nombre y valor proporcionados por el programa de aplicación cuando la aplicación está modificando un Message programáticamente (en lugar de un Message creado por un analizador). El método debe retornar la tupla (name,value) que va a ser almacenada en el Message para representar la cabecera.

Si una implementación desea retener compatibilidad con los policy del paquete de correos electrónicos existentes, el name y value deben ser cadenas de caracteres o subclases de cadenas que no cambien el contenido de los pasados en los argumentos.

No hay implementación por defecto

header_fetch_parse(name, value)

El paquete de correos electrónicos llama a este método con el name y valor actualmente guardados en Message (el mensaje) cuando la cabecera es solicitada por el programa de aplicación, y lo que sea que el método retorne es lo que es pasado de vuelta a la aplicación como el valor de la cabecera siendo recuperado. Note que puede haber más de una cabecera con el mismo nombre guardado en Message; el método es pasado al nombre específico y valor de la cabecera destinado a ser retornado a la aplicación.

value puede contener datos binarios surrogateescaped. No debe haber datos binarios surrogateescaped en el valor retornado por el método.

No hay implementación por defecto

fold(name, value)

El paquete de correos electrónicos llama a este método con los name y value actualmente guardados en Message para una cabecera dada. El método debe retornar una cadena de caracteres que represente esa cabecera «doblada» correctamente (de acuerdo a los ajustes del policy) al componer name con value e insertar caracteres linesep en los lugares apropiados. Véase RFC 5322 [https://tools.ietf.org/html/rfc5322.html] para una discusión de las reglas para doblar cabeceras de correos electrónicos.

value puede contener datos binarios surrogateescaped. No debe haber datos binarios surrogateescaped en la cadena de caracteres retornada por el método.

fold_binary(name, value)

Igual que fold(), excepto que el valor retornado debe ser un objeto bytes en vez de una cadena de caracteres.

value puede contener datos binarios surrogateescaped. Estos pueden ser convertidos de vuelta a datos binarios en el objeto de bytes retornado.

class email.policy.EmailPolicy(**kw)

Este Policy concreto proporciona el comportamiento que sirve para cumplir con los RFCs actuales para correos electrónicos. Estos incluyen (pero no están limitados a) RFC 5322 [https://tools.ietf.org/html/rfc5322.html], RFC 2047 [https://tools.ietf.org/html/rfc2047.html], y los actuales RFCs MIME.

Esta policy incorpora nuevos analizadores de cabeceras y algoritmos de doblado. En vez de cadenas de caracteres simples, las cabeceras son subclases de str con atributos que dependen del tipo del campo. El analizado y algoritmo de doblado implementan los RFC 2047 [https://tools.ietf.org/html/rfc2047.html] y RFC 5322 [https://tools.ietf.org/html/rfc5322.html] por completo.

El valor por defecto para el atributo message_factory es EmailMessage.

Además de los atributos que se pueden configurar listados arriba que aplican a todas los policies, este policy añade los siguientes atributos adicionales:

Nuevo en la versión 3.6: 1

utf8

Si es False, se sigue el RFC 5322 [https://tools.ietf.org/html/rfc5322.html], siendo compatible con caracteres non-ASCII en las cabeceras al codificarlas como «palabras codificadas». Si es True, sigue el RFC 6532 [https://tools.ietf.org/html/rfc6532.html] y usa el formato de codificación utf-8 para las cabeceras. Los mensajes formateados de esta manera puede ser pasados a servidores SMTP que admitan la extensión SMTPUTF8 (RFC 6531 [https://tools.ietf.org/html/rfc6531.html]).

refold_source

Si el valor para una cabecera en el objeto Message se originó de un parser (en lugar de ser establecido por el programa), este atributo indica tanto si un generador debe redoblar ese valor cuando se transforma al mensaje de vuelta a la forma serializada o no. Los valores posibles son:

none

todos los valores de la fuente usan el doblamiento original

long

los valores de la fuente que tengan una línea que sea más grande que max_line_length serán redoblados

all

todos los valores son redoblados.

El valor por defecto es long.

header_factory

Un invocable que toma dos argumentos, name y value, donde name es un nombre de campo de cabecera y value es un valor del campo de la cabecera no doblado, y retorna una subclase de cadenas de caracteres que representan la cabecera. Un valor por defecto header_factory (véase headerregistry) es proporcionado que admite el análisis personalizado para los varios tipos de cabecera RFC 5322 [https://tools.ietf.org/html/rfc5322.html] de direcciones y fechas, y los tipos del cabeceras MIME principales. La compatibilidad de analizadores personalizados adicionales será agregada en el futuro.

content_manager

Un objeto con al menos dos métodos: get_content and set_content. Cuando los métodos get_content() o set_content() del objeto messageEmailMessage son llamados, llama al método correspondiente de este objeto, pasándole el mensaje objeto como su primer argumento, y cualquier argumento o palabra clave que fuese pasado como un argumento adicional. Por defecto content_manager se pone a raw_data_manager.

Nuevo en la versión 3.4.

La clase proporciona las siguientes implementaciones concretas de los métodos abstractos de Policy:

header_max_count(name)

Retorna el valor del atributo max_count de la clase especializada usada para representar la cabecera con el nombre dado.

header_source_parse(sourcelines)

El nombre es analizado como todo hasta el “:” y retornado inalterado. El valor es determinado al remover los espacios en blanco al principio del resto de la primera línea, juntando todas las subsecuentes líneas, y removiendo cualquier carácter CR o LF.

header_store_parse(name, value)

El nombre es retornado inalterado. Si el valor de la entrada tiene un atributo name y coincide con name ignorando mayúsculas y minúsculas, el valor es retornado inalterado. Si no, el name y value son pasados a header_factory , y el objeto cabecera resultante es retornado como el valor. En este caso un ValueError es lanzado si el valor de la entrada contiene caracteres CR o LF.

header_fetch_parse(name, value)

Si el valor tiene un atributo name, es retornado inalterado. De otra manera el name, y el value con cualquier carácter CR o LF eliminado, son pasados a la header_factory, y el objeto cabecera resultante es retornado. Cualquier byte surrogateescaped es convertido al glifo de carácter desconocido de unicode.

fold(name, value)

El doblamiento de la cabecera es controlado por la configuración de policy refold_source. Se considera que un valor es source value (valor fuente) si y sólo si no tiene un atributo name```(tener un atributo ``name significa que es un objeto cabecera de algún tipo). Si un valor fuente necesita ser redoblado de acuerdo a la política, es convertido en un objeto cabecera al pasarle el name y value con cualquier carácter CR y LF eliminado al header_factory. El doblamiento de un objeto cabecera es hecho al llamar a su método fold con el policy actual.

Los valores fuente son separadas en líneas usando el método splitlines(). Si el valor no va a ser redoblado, las líneas son unidas de nuevo usando el linesep del policy y retornadas. La excepción son las líneas que contienen datos binarios non-ascii. En ese caso el valor es redoblado a pesar de la configuración de refold_source, que causa que los datos binarios sean codificados CTE usando el juego de caracteres (charset) unknown-8bit.

fold_binary(name, value)

Igual que fold() si cte_type fuese 7bit, excepto que el valor retornado son bytes.

Si cte_type es 8bit, los datos binarios non-ASCII son convertidos de vuelta a bytes. Las cabeceras con datos binarios son redoblados, sin considerar la configuración de refold_header, ya que no hay forma de saber si los datos binarios consisten en caracteres de un sólo byte o caracteres con múltiples bytes.

Las siguientes instancias de EmailPolicy proporcionan valores por defecto apropiados para dominios de aplicaciones específicas. Note que en el futuro el comportamiento de estas instancias (en particular la instancia HTTP) puede ser ajustado para cumplir incluso más de cerca a los RFC relevantes a sus dominios.

email.policy.default

Una instancia de EmailPolicy con todos los valores por defecto sin cambiar. Este policy usa la terminación de línea \n estándar de Python en vez de correcto por el RFC \r\n.

email.policy.SMTP

Apropiado para la serialización de mensajes en cumplimiento con los RFC de correos electrónicos. Como default, pero con linesep puesto en \r\n, que es conforme con el RFC.

email.policy.SMTPUTF8

Igual que SMTP excepto que utf8 es True. Útil para serializar mensajes a un almacén de mensajes sin usar palabras codificadas en las cabeceras. Sólo debe ser utilizada para transmisiones por SMTP si las direcciones del remitente o recipiente tienen caracteres non-ASCII (el método smtplib.SMTP.send_message() gestiona esto automáticamente).

email.policy.HTTP

Apropiado para serializar cabeceras con uso en tráfico de HTTP. Como SMTP excepto que max_line_length es puesto en None (ilimitado).

email.policy.strict

Instancias de conveniencia. Igual que default excepto que raise_of_defect es puesto en True. Esto permite que cualquier policy sea hecho estricto al escribir:

somepolicy + policy.strict

Con todos estos EmailPolicies, el API efectivo del paquete de correos electrónicos es cambiado del API de Python 3.2 en las siguientes maneras:

Estableciendo una cabecera en una Message resulta en que la cabecera sea analizada y un objeto cabecera sea creado.

Buscar una valor de cabecera de un Message resulta en que la cabecera sea analizada y un objeto cabecera sea creado y retornado.

Cualquier objeto cabecera, o cualquier cabecera que sea redoblada debido a las configuraciones del policy, es doblado usando un algoritmo que implementa el algoritmo de doblado del RFC por completo, incluyendo saber dónde las palabras codificadas son requeridas y permitidas.

Desde la vista de la aplicación, significa que cualquier cabecera obtenida a través de EmailMessage es un objeto cabecera con atributos extra, cuyo valor de cadena es el valor Unicode de la cabecera completamente decodificada. Asimismo, se le puede asignar un nuevo valor a una cabecera, o a una nueva cabecera creada, usando una cadena de caracteres Unicode, y el policy se ocupará de convertir la cadena Unicode en la forma decodificada correcta según el RFC.

Los objetos cabecera y sus atributos son descritos en headerrregistry.

class email.policy.Compat32(**kw)

Este Policy concreto es el policy compatible hacia atrás. Replica el comportamiento del paquete de correos electrónicos en Python 3.2. El módulo policy también define una instancia de esta clase, compat32, que es usado como el policy por defecto. Por consiguiente, el comportamiento por defecto del paquete de correos electrónicos es mantener compatibilidad con Python 3.2.

Los siguientes atributos tienen valores que son diferentes del Policy por defecto:

mangle_from_

El valor por defecto es True.

La clase proporciona las siguientes implementaciones concretas de los métodos abstractos de Policy:

header_source_parse(sourcelines)

El nombre es analizado como todo hasta el “:” y retornado inalterado. El valor es determinado al remover los espacios en blanco al principio del resto de la primera línea, juntando todas las subsecuentes líneas, y removiendo cualquier carácter CR o LF.

header_store_parse(name, value)

El nombre y valor son retornados inalterados.

header_fetch_parse(name, value)

Si el valor contiene datos binarios, es convertido a un objeto Header usando el juego de caracteres (charset) unknown-8bit. De otro modo, es retornado sin modificar.

fold(name, value)

Las cabeceras son dobladas usando el algoritmo de doblado de Header, lo que preserva los saltos de líneas existentes en el valor, y envuelve cada línea resultante hasta el max_line_length. Los datos binarios Non-ASCII son codificados por CTE usando el juego de caracteres (charset) unknown-8bit.

fold_binary(name, value)

Las cabeceras son dobladas usando el algoritmo de doblado Header, lo que preserva los saltos de línea existentes en el valor, y envuelve cada línea resultante hasta max_line_length. Si cte_type es 7bit, los datos binarios non-ascii son codificados por CTE usando el juego de caracteres unknown-8bit. De otro modo, la cabecera fuente original es usada, con sus saltos de línea existentes y cualquier (inválido según el RFC) dato binario que puede contener.

email.policy.compat32

Una instancia de Compat32, proporcionando compatibilidad hacia atrás con el comportamiento del paquete de correos electrónicos en Python 3.2.

Notas al pie de página

1

Se añadió originalmente en 3.3 como un característica provisional.

email.errors: Clases de excepción y defecto

Código fuente: Lib/email/errors.py [https://github.com/python/cpython/tree/3.9/Lib/email/errors.py]

Las siguientes clases de excepción se definen en el módulo email.errors:

exception email.errors.MessageError

Esta es la clase base para todas las excepciones que el paquete email puede lanzar. Se deriva de la clase estándar Exception y no define métodos adicionales.

exception email.errors.MessageParseError

Esta es la clase base para las excepciones generadas por la clase Parser. Se deriva de MessageError. Esta clase también es utilizada internamente por el analizador sintáctico utilizado por headerregistry.

exception email.errors.HeaderParseError

Lanzada en algunas condiciones de error al analizar los encabezados RFC 5322 [https://tools.ietf.org/html/rfc5322.html] de un mensaje, esta clase se deriva de MessageParseError. El método set_boundary() lanzará este error si el tipo de contenido es desconocido cuando se llama al método. Header puede lanzar este error para ciertos errores de decodificación de base64, y cuando se intenta crear un encabezado que parece contener un encabezado incrustado (es decir, hay lo que se supone que es un línea de continuación que no tiene espacios en blanco iniciales y parece un encabezado).

exception email.errors.BoundaryError

Deprecada y no utilizada actualmente.

exception email.errors.MultipartConversionError

Se lanza cuando se agrega una carga útil (payload) a un objeto Message usando add_payload(), pero la carga útil ya es un número escalar y el tipo principal del mensaje Content-Type no es multipart ni perdido (missing). MultipartConversionError hereda al mismo tiempo de MessageError y el incorporado TypeError.

Dado que Message.add_payload() está en desuso, esta excepción rara vez se presenta en la práctica. Sin embargo, la excepción también se puede lanzar si se llama al método attach() en una instancia de una clase derivada de MIMENonMultipart (por ejemplo MIMEImage).

Aquí está la lista de defectos que FeedParser puede encontrar mientras analiza mensajes. Tenga en cuenta que los defectos se agregan al mensaje donde se encontró el problema, por ejemplo, si un mensaje anidado dentro de un multipart/alternative tenía un encabezado mal formado, ese objeto de mensaje anidado tendría un defecto, pero el contenido los mensajes no lo harían.

Todas las clases de defectos se derivan de email.errors.MessageDefect.

NoBoundaryInMultipartDefect – Un mensaje que se dice que es multiparte, pero que no tiene el parámetro boundary.

StartBoundaryNotFoundDefect – El límite de inicio reclamado en el encabezado Content-Type nunca se encontró.

CloseBoundaryNotFoundDefect – Se encontró un límite de inicio, pero nunca se encontró un límite cercano correspondiente.

Nuevo en la versión 3.3.

FirstHeaderLineIsContinuationDefect – El mensaje tenía una línea de continuación como primera línea de encabezado.

MisplacedEnvelopeHeaderDefect – Se encontró un encabezado «Unix From» en medio de un bloque de encabezado.

MissingHeaderBodySeparatorDefect - Se encontró una línea al analizar sintácticamente los encabezados que no tenían espacios en blanco iniciales pero que no contenían “:”. El análisis continúa asumiendo que la línea representa la primera línea del cuerpo.

Nuevo en la versión 3.3.

MalformedHeaderDefect – Se encontró un encabezado al que le faltaban dos puntos o tenía un formato incorrecto.

Obsoleto desde la versión 3.3: Este defecto no se ha utilizado por varias versiones de Python.

MultipartInvariantViolationDefect– Un mensaje que se afirma ser multipart, pero no se encontraron subpartes. Tenga en cuenta que cuando un mensaje tiene este defecto, su método is_multipart() puede retornar False aunque su tipo de contenido afirma ser multipart.

InvalidBase64PaddingDefect – Al decodificar un bloque de bytes codificados en base64, el relleno no era correcto. Se agrega suficiente relleno (padding) para realizar la decodificación, pero los bytes decodificados resultantes pueden no ser válidos.

InvalidBase64CharactersDefect – Al decodificar un bloque de bytes codificados en base64, se encontraron caracteres fuera del alfabeto base64. Los caracteres se ignoran, pero los bytes decodificados resultantes pueden no ser válidos.

InvalidBase64LengthDefect – Al decodificar un bloque de bytes codificados en base64, el número de caracteres base64 sin relleno no era válido (1 más que un múltiplo de 4). El bloque codificado se mantuvo tal cual.

email.headerregistry: Objetos de encabezado personalizados

Código fuente: Lib/email/headerregistry.py [https://github.com/python/cpython/tree/3.9/Lib/email/headerregistry.py]

Nuevo en la versión 3.6: 1

Los encabezados están representados por subclases personalizadas de str. La clase particular utilizada para representar un encabezado dado está determinada por header_factory del policy vigente cuando se crean los encabezados. Esta sección documenta el header_factory particular implementado por el paquete de correo electrónico para el manejo mensajes de correo electrónico compatibles con RFC 5322 [https://tools.ietf.org/html/rfc5322.html], que no solo proporciona objetos de encabezado personalizados para varios tipos de encabezados, sino que también proporciona un mecanismo de extensión para que las aplicaciones agreguen sus propios tipos de encabezados personalizados.

Cuando se utiliza cualquiera de los objetos de política derivados de EmailPolicy, todos los encabezados son producidos por HeaderRegistry y tienen BaseHeader como su última clase base. Cada clase de encabezado tiene una clase base adicional que está determinada por el tipo de encabezado. Por ejemplo, muchos encabezados tienen la clase UnstructuredHeader como su otra clase base. La segunda clase especializada para un encabezado está determinada por el nombre del encabezado, utilizando una tabla de búsqueda almacenada en HeaderRegistry. Todo esto se gestiona de forma transparente para el programa de aplicación típico, pero se proporcionan interfaces para modificar el comportamiento predeterminado para su uso por aplicaciones más complejas.

Las secciones a continuación primero documentan las clases base de encabezados y sus atributos, seguidas por la API para modificar el comportamiento de HeaderRegistry, y finalmente las clases de soporte utilizadas para representar los datos analizados a partir de encabezados estructurados.

class email.headerregistry.BaseHeader(name, value)

name y value se pasan a BaseHeader desde la llamada header_factory. El valor de cadena de caracteres de cualquier objeto de encabezado es el value completamente descodificado en unicode.

Esta clase base define las siguientes propiedades de solo lectura:

name

El nombre del encabezado (la parte del campo antes del “:”). Este es exactamente el valor pasado en header_factory llamada para name; es decir, se conserva el caso.

defects

Una tupla de instancias HeaderDefect que informan sobre cualquier problema de cumplimiento de RFC que se encuentre durante el análisis. El paquete de correo electrónico intenta estar completo para detectar problemas de cumplimiento. Vea el módulo errors para una discusión de los tipos de defectos que pueden ser reportados.

max_count

El número máximo de encabezados de este tipo que pueden tener el mismo name. Un valor de None significa ilimitado. El valor de BaseHeader para este atributo es None; se espera que las clases de encabezado especializadas anulen este valor según sea necesario.

BaseHeader también proporciona el siguiente método, que es llamado por el código de la biblioteca de correo electrónico y, en general, no debe ser llamado por programas de aplicación:

fold(*, policy)

Retorna una cadena que contenga linesep caracteres según sea necesario para doblar correctamente el encabezado de acuerdo con policy. Un atributo cte_type de` 8bit` se tratará como si fuera``7bit``, ya que los encabezados no pueden contener datos binarios arbitrarios. Si utf8 es False, los datos no ASCII estarán codificados RFC 2047 [https://tools.ietf.org/html/rfc2047.html].

BaseHeader por sí solo no se puede utilizar para crear un objeto de encabezado. Define un protocolo con el que coopera cada encabezado especializado para producir el objeto de encabezado. Específicamente, BaseHeader requiere que la clase especializada proporcione un classmethod() llamado parse. Este método se llama de la siguiente manera:

parse(string, kwds)

kwds es un diccionario que contiene una clave preinicializada, defects. defects es una lista vacía. El método de análisis debe agregar cualquier defecto detectado a esta lista. A la devolución, el diccionario kwds debe (must) contener valores para al menos las claves decoded` y ``defects. decoded debe ser el valor de cadena para el encabezado (es decir, el valor del encabezado completamente decodificado a Unicode). El método de análisis debe asumir que string puede contener partes codificadas por transferencia de contenido, pero también debe manejar correctamente todos los caracteres Unicode válidos para que pueda analizar valores de encabezado no codificados.

Entonces, el __new__ de BaseHeader crea la instancia del encabezado y llama a su método init. La clase especializada solo necesita proporcionar un método init si desea establecer atributos adicionales más allá de los proporcionados por BaseHeader. Tal método init debería verse así:

def init(self, /, *args, **kw):
    self._myattr = kw.pop('myattr')
    super().init(*args, **kw)

Es decir, cualquier cosa adicional que la clase especializada ponga en el diccionario kwds debe eliminarse y manejarse, y el contenido restante de kw (y args) debe pasar BaseHeader al método init.

class email.headerregistry.UnstructuredHeader

Un encabezado «sin estructura» es el tipo predeterminado de encabezado en RFC 5322 [https://tools.ietf.org/html/rfc5322.html]. Cualquier encabezado que no tenga una sintaxis especificada se trata como no estructurado. El ejemplo clásico de un encabezado no estructurado es el encabezado Subject.

En RFC 5322 [https://tools.ietf.org/html/rfc5322.html], un encabezado no estructurado es una ejecución de texto arbitrario en el conjunto de caracteres ASCII. RFC 2047 [https://tools.ietf.org/html/rfc2047.html], sin embargo, tiene un mecanismo compatible RFC 5322 [https://tools.ietf.org/html/rfc5322.html] para codificar texto no ASCII como caracteres ASCII dentro de un valor de encabezado. Cuando un value que contiene palabras codificadas se pasa al constructor, el analizador UnstructuredHeader convierte dichas palabras codificadas en unicode, siguiendo las reglas RFC 2047 [https://tools.ietf.org/html/rfc2047.html] para texto no estructurado. El analizador utiliza heurística para intentar decodificar ciertas palabras codificadas no compatibles. Los defectos se registran en tales casos, así como defectos por problemas como caracteres no válidos dentro de las palabras codificadas o el texto no codificado.

Este tipo de encabezado no proporciona atributos adicionales.

class email.headerregistry.DateHeader

RFC 5322 [https://tools.ietf.org/html/rfc5322.html] especifica un formato muy específico para las fechas dentro de los encabezados de correo electrónico. El analizador DateHeader reconoce ese formato de fecha, además de reconocer una serie de formas variantes que a veces se encuentran «en la naturaleza» («in the wild»).

Este tipo de encabezado proporciona los siguientes atributos adicionales:

datetime

Si el valor del encabezado puede reconocerse como una fecha válida de una forma u otra, este atributo contendrá una instancia datetime que representa esa fecha. Si la zona horaria de la fecha de entrada se especifica como -0000 (lo que indica que está en UTC pero no contiene información sobre la zona horaria de origen), entonces datetime será un ingenuo datetime. Si se encuentra un desplazamiento de zona horaria específico (incluido +0000), entonces datetime contendrá un datetime consciente que usa datetime.timezone para registrar el desplazamiento de la zona horaria.

El valor decoded del encabezado se determina formateando la datetime de acuerdo con las reglas RFC 5322 [https://tools.ietf.org/html/rfc5322.html]; es decir, esto se establece en:

email.utils.format_datetime(self.datetime)

Al crear un DateHeader, value puede ser datetime instancia. Esto significa, por ejemplo, que el siguiente código es válido y hace lo que cabría esperar:

msg['Date'] = datetime(2011, 7, 15, 21)

Debido a que se trata de una datetime naif, se interpretará como una marca de tiempo UTC, y el valor resultante tendrá una zona horaria de -0000. Mucho más útil es usar la función localtime() del módulo utils:

msg['Date'] = utils.localtime()

Este ejemplo establece el encabezado de la fecha en la hora y fecha actuales utilizando el desplazamiento de zona horaria actual.

class email.headerregistry.AddressHeader

Los encabezados de dirección son uno de los tipos de encabezados estructurados más complejos. La clase AddressHeader proporciona una interfaz genérica para cualquier encabezado de dirección.

Este tipo de encabezado proporciona los siguientes atributos adicionales:

groups

Una tupla de objetos Group que codifican las direcciones y los grupos que se encuentran en el valor del encabezado. Las direcciones que no forman parte de un grupo se representan en esta lista como Groups de una sola dirección cuyo display_name es None.

addresses

Una tupla de objetos Address que codifican todas las direcciones individuales del valor del encabezado. Si el valor del encabezado contiene algún grupo, las direcciones individuales del grupo se incluyen en la lista en el punto donde el grupo aparece en el valor (es decir, la lista de direcciones se «aplana» («flattened») en una lista unidimensional).

El valor decoded del encabezado tendrá todas las palabras codificadas decodificadas a Unicode. Los nombres de dominio codificados idna también se decodifican en Unicode. El valor decoded se establece mediante join del valor str de los elementos del atributo groups con ', '.

Se puede utilizar una lista de objetos Address y Group en cualquier combinación para establecer el valor de un encabezado de dirección. Los objetos Group cuyo display_name sea None se interpretarán como direcciones únicas, lo que permite copiar una lista de direcciones con los grupos intactos utilizando la lista obtenida del atributo groups de el encabezado de origen.

class email.headerregistry.SingleAddressHeader

Una subclase de AddressHeader que agrega un atributo adicional:

address

La única dirección codificada por el valor del encabezado. Si el valor del encabezado en realidad contiene más de una dirección (lo que sería una violación del RFC bajo el valor predeterminado policy), acceder a este atributo resultará en un ValueError.

Muchas de las clases anteriores también tienen una variante Unique (por ejemplo,``UniqueUnstructuredHeader``). La única diferencia es que en la variante Unique, max_count se establece en 1.

class email.headerregistry.MIMEVersionHeader

En realidad, solo hay un valor válido para el encabezado MIME-Version, y ese es 1.0. Para pruebas futuras, esta clase de encabezado admite otros números de versión válidos. Si un número de versión tiene un valor válido por RFC 2045 [https://tools.ietf.org/html/rfc2045.html], entonces el objeto de encabezado tendrá valores distintos de None para los siguientes atributos:

version

El número de versión como una cadena de caracteres, con cualquier espacio en blanco y/o comentarios eliminados.

major

El número de versión mayor como un entero

minor

El número de versión menor como un entero

class email.headerregistry.ParameterizedMIMEHeader

Todos los encabezados MIME comienzan con el prefijo “Content-”. Cada encabezado específico tiene un valor determinado, que se describe en la clase de ese encabezado. Algunos también pueden tomar una lista de parámetros complementarios, que tienen un formato común. Esta clase sirve como base para todos los encabezados MIME que toman parámetros.

params

Un diccionario que asigna nombres de parámetros a valores de parámetros.

class email.headerregistry.ContentTypeHeader

Una clase ParameterizedMIMEHeader que maneja el encabezado Content-Type.

content_type

La cadena de caracteres de tipo de contenido, en la forma maintype/subtype.

maintype

subtype

class email.headerregistry.ContentDispositionHeader

Una clase ParameterizedMIMEHeader que maneja el encabezado Content-Disposition.

content_disposition

inline y attachment son los únicos valores válidos de uso común.

class email.headerregistry.ContentTransferEncoding

Maneja el encabezado de Content-Transfer-Encoding.

cte

Los valores válidos son 7bit, 8bit, base64, y quoted-printable. Consulte RFC 2045 [https://tools.ietf.org/html/rfc2045.html] para obtener más información.

class email.headerregistry.HeaderRegistry(base_class=BaseHeader, default_class=UnstructuredHeader, use_default_map=True)

Esta es la mecánica utilizada por EmailPolicy por defecto. HeaderRegistry construye la clase utilizada para crear una instancia de encabezado dinámicamente, usando base_class y una clase especializada recuperada de un registro que contiene. Cuando un nombre de encabezado determinado no aparece en el registro, la clase especificada por default_class se utiliza como clase especializada. Cuando use_default_map es True (el valor predeterminado), la asignación estándar de nombres de encabezado a clases se copia en el registro durante la inicialización. base_class es siempre la última clase en la lista __bases__ de la clase generada.

Las asignaciones predeterminadas son:

subject

UniqueUnstructuredHeader

date

UniqueDateHeader

resent-date

DateHeader

orig-date

UniqueDateHeader

sender

UniqueSingleAddressHeader

resent-sender

SingleAddressHeader

to

UniqueAddressHeader

resent-to

AddressHeader

cc

UniqueAddressHeader

resent-cc

AddressHeader

bcc

UniqueAddressHeader

resent-bcc

AddressHeader

from

UniqueAddressHeader

resent-from

AddressHeader

reply-to

UniqueAddressHeader

mime-version

MIMEVersionHeader

content-type

ContentTypeHeader

content-disposition

ContentDispositionHeader

content-transfer-encoding

ContentTransferEncodingHeader

message-id

MessageIDHeader

HeaderRegistry tiene los siguientes métodos:

map_to_type(self, name, cls)

name es el nombre del encabezado que se asignará. Se convertirá a minúsculas en el registro. cls es la clase especializada que se utilizará, junto con base_class, para crear la clase utilizada para instanciar encabezados que coincidan con name.

__getitem__(name)

Construye y retorna una clase para manejar la creación de un encabezado nombre.

__call__(name, value)

Recupera el encabezado especializado asociado con name del registro (usando default_class si name no aparece en el registro) y lo compone con base_class para producir una clase, llama al constructor de la clase construida, pasándole el mismo lista de argumentos y, finalmente, retorna la instancia de clase creada de ese modo.

Las siguientes clases son las clases que se utilizan para representar datos analizados a partir de encabezados estructurados y, en general, pueden ser utilizadas por un programa de aplicación para construir valores estructurados para asignar a encabezados específicos.

class email.headerregistry.Address(display_name='', username='', domain='', addr_spec=None)

La clase utilizada para representar una dirección de correo electrónico. La forma general de una dirección es:

[display_name] <username@domain>

or:

username@domain

donde cada parte debe ajustarse a reglas de sintaxis específicas explicadas en RFC 5322 [https://tools.ietf.org/html/rfc5322.html].

Para su comodidad, se puede especificar addr_spec en lugar de username y domain, en cuyo caso username y domain se analizarán a partir de addr_spec. Un addr_spec debe ser una cadena de caracteres entre comillas RFC adecuada; si no es Address, se generará un error. Se permiten caracteres Unicode y se codificarán como propiedad cuando se serialicen. Sin embargo, según las RFC, no se permite unicode en la parte del nombre de usuario de la dirección.

display_name

La parte del nombre para mostrar de la dirección, si la hubiera, con todas las citas eliminadas. Si la dirección no tiene un nombre para mostrar, este atributo será una cadena vacía.

username

La parte del username de la dirección, con todas las citas eliminadas.

domain

La parte de domain de la dirección.

addr_spec

La parte de la dirección username@domain, citada correctamente para usarla como dirección simple (el segundo formulario que se muestra arriba). Este atributo no es mutable.

__str__()

El valor str del objeto es la dirección citada de acuerdo con las reglas RFC 5322 [https://tools.ietf.org/html/rfc5322.html], pero sin codificación de transferencia de contenido de ningún carácter que no sea ASCII.

Para admitir SMTP (RFC 5321 [https://tools.ietf.org/html/rfc5321.html]), Address maneja un caso especial: si username y domain son ambos la cadena de caracteres vacía (o None), entonces el valor de cadena de caracteres Address es <>.

class email.headerregistry.Group(display_name=None, addresses=None)

La clase utilizada para representar un grupo de direcciones. La forma general de un grupo de direcciones es:

display_name: [address-list];

Para facilitar el procesamiento de listas de direcciones que constan de una mezcla de grupos y direcciones únicas, también se puede utilizar un Group para representar direcciones únicas que no forman parte de un grupo al establecer display_name en None y proporcionando una lista de direcciones únicas como addresses.

display_name

El display_name del grupo. Si es None y hay exactamente una Address en addresses, entonces el Group representa una única dirección que no está en un grupo.

addresses

Posiblemente una tupla vacía de Address que representan las direcciones en el grupo.

__str__()

El valor str de un Group se formatea de acuerdo con RFC 5322 [https://tools.ietf.org/html/rfc5322.html], pero sin codificación de transferencia de contenido de ningún carácter que no sea ASCII. Si display_name no es ninguno y hay una sola Address en la lista de addresses, el valor de str será el mismo que el str de ese single Address.

Pie de notas

1

Originalmente añadido en 3.3 como módulo provisional provisional module

email.contentmanager: Gestión de contenido MIME

Código fuente: Lib/email/contentmanager.py [https://github.com/python/cpython/tree/3.9/Lib/email/contentmanager.py]

Nuevo en la versión 3.6: 1

class email.contentmanager.ContentManager

Clase base para gestores de contenido. Proporciona los mecanismos de registro estándar para registrar convertidores entre contenido MIME y otras representaciones, así como los métodos de envío get_content y set_content.

get_content(msg, *args, **kw)

Busca una función de controlador basada en el mimetype de msg (ver el siguiente párrafo), la llama, le pasa todos los argumentos y retorna el resultado de la llamada. La expectativa es que el controlador extraiga la carga útil de msg y retorne un objeto que codifica información sobre los datos extraídos.

Para encontrar el controlador, busca las siguientes llaves en el registro, deteniéndose con la primera que encuentre:

la cadena que representa el tipo MIME completo (maintype/subtype)

la cadena de caracteres que representa el maintype

la cadena de caracteres vacía

Si ninguna de estas llaves produce un controlador, se lanza una excepción KeyError para el tipo MIME completo.

set_content(msg, obj, *args, **kw)

Si el maintype es multipart, se lanza un TypeError; de lo contrario, busca una función de controlador basada en el tipo de obj (ver el siguiente párrafo), llama a clear_content() en el msg y llama a la función de controlador, pasando todos los argumentos. La expectativa es que el controlador transforme y almacene obj en msg, posiblemente realizando otros cambios a msg también, como agregar varios encabezados MIME para codificar la información necesaria para interpretar los datos almacenados.

Para encontrar el controlador, obtiene el tipo de obj (typ = type(obj)), y busca las siguientes llaves en el registro, deteniéndose con la primera encontrada:

el tipo en sí (typ)

el nombre completo de calificación del tipo (typ.__module__ + '.' + typ.__qualname__).

el nombre de calificación del tipo (typ.__qualname__)

el nombre del tipo (typ.__name__).

Si ninguno de los anteriores coincide, repite todas las comprobaciones anteriores para cada uno de los tipos en el MRO (typ.__mro__). Finalmente, si ninguna otra llave produce un controlador, busca un controlador para la llave None. Si no hay un controlador para None, lanza un KeyError para el nombre completo de calificación del tipo.

También agrega un encabezado MIME-Version si no hay uno presente (vea también MIMEPart).

add_get_handler(key, handler)

Registra el handler de funciones como el manejador de key. Para los posibles valores de key, consulte get_content().

add_set_handler(typekey, handler)

Registra el handler como la función a llamar cuando un objeto de un tipo coincidente typekey se pasa a set_content(). Para los posibles valores de typekey, consulte set_content().

Instancias gestoras de contenido

Actualmente, el paquete de correo electrónico solo proporciona un administrador de contenido concreto, raw_data_manager, aunque en el futuro se pueden agregar más. raw_data_manager es el content_manager proporcionado por EmailPolicy y sus derivados.

email.contentmanager.raw_data_manager

Este administrador de contenido proporciona sólo una interfaz mínima más allá de la proporcionada por Message en sí: trata solo con texto, cadenas de bytes sin procesar, y objetos Message. Sin embargo, proporciona ventajas significativas en comparación con la API base: get_content en una parte de texto retornará una cadena de caracteres unicode sin que la aplicación tenga que decodificarla manualmente, set_content proporciona un amplio conjunto de opciones para controlar los encabezados añadidos a una parte y controlar la codificación de transferencia de contenido, y permite el uso de los diversos métodos add_, simplificando así la creación de mensajes multiparte.

email.contentmanager.get_content(msg, errors='replace')

Retorna la carga útil de la parte como una cadena de caracteres (para partes de text), un objeto EmailMessage (para partes de message/rfc822), o un objeto de bytes (para todos los demás tipos que no son multiparte). Lanza un KeyError si se llama en un multipart. Si la parte es una parte de text y se especifica errors, se usa como el controlador de errores al decodificar la carga útil a unicode. El controlador de errores predeterminado es replace.

email.contentmanager.set_content(msg, <'str'>, subtype="plain", charset='utf-8', cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)

email.contentmanager.set_content(msg, <'bytes'>, maintype, subtype, cte="base64", disposition=None, filename=None, cid=None, params=None, headers=None)

email.contentmanager.set_content(msg, <'EmailMessage'>, cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)

Añade cabeceras y carga útil al msg:

Añade un encabezado Content-Type con un valor maintype/subtype.

Para str, establece el maintype de MIME en text, y establece el subtipo en subtype si se especifica, o plain si no está presente.

Para bytes, usa el maintype y subtype especificados, o lanza un TypeError si no se especifican.

Para objetos EmailMessage, establece el maintype en message, y establece el subtype en subtype si se especifica o rfc822 si no se especifica. Si subtype es partial, se lanza un error (los objetos de bytes deben usarse para construir partes message/partial).

Si se proporciona charset (lo cual solo es válido para str), codifica la cadena de caracteres en bytes utilizando el conjunto de caracteres especificado. El valor por defecto es utf-8. Si el charset especificado es un alias conocido del nombre de un conjunto de caracteres del estándar MIME, utiliza el conjunto de caracteres estándar en su lugar.

Si se establece cte, codifica la carga útil mediante la codificación de transferencia de contenido especificada y establece el encabezado Content-Transfer-Encoding en ese valor. Los valores posibles para cte son quoted-printable, base64, 7bit, 8bit, y binary. Si la entrada no se puede codificar en la codificación especificada (por ejemplo, especificando un cte de 7bit para una entrada que contiene valores no ASCII), se lanza un ValueError.

Para objetos str, si cte no está configurado, se usa la heurística para determinar la codificación más compacta.

Para EmailMessage, según RFC 2046 [https://tools.ietf.org/html/rfc2046.html], se lanza un error si se solicita un cte de quoted-printable o base64 para el subtype rfc822, y para cualquier cte que no sea 7bit para el subtype external-body. Para message/rfc822, se usa 8bit si no se especifica cte. Para todos los demás valores de subtype, se usa 7bit.

Nota

Un cte de binary todavía no funciona correctamente. El objeto EmailMessage modificado por set_content es correcto, pero BytesGenerator no lo serializa correctamente.

Si se establece disposición, se usa como valor del encabezado Content-Disposition. Si no se especifica y se especifica filename, agrega el encabezado con el valor attachment. Si no se especifica disposition y tampoco se especifica filename, no agrega el encabezado. Los únicos valores válidos para disposition son attachment e inline.

Si se especifica el filename, se usa como el valor del parámetro filename del encabezado Content-Disposition.

Si se especifica cid, agrega un encabezado Content-ID con valor cid.

Si se especifica params, itera su método items y use los pares resultantes (key, value) para establecer parámetros adicionales en el encabezado Content-Type.

Si se especifica headers y es una lista de cadenas de caracteres de la forma headername: headervalue o una lista de objetos header (que se distinguen de las cadenas de caracteres por tener un atributo name), agrega los encabezados a msg.

Notas al pie de página

1

Originalmente añadido en la versión 3.4 como un módulo provisional

email: Ejemplos

Aquí hay algunos ejemplos de cómo usar el paquete email para leer, escribir y enviar mensajes de correo electrónico simples, así como mensajes MIME más complejos.

Primero, veamos cómo crear y enviar un mensaje de texto simple (tanto el contenido de texto como las direcciones pueden contener caracteres unicode):

# Import smtplib for the actual sending function
import smtplib

# Import the email modules we'll need
from email.message import EmailMessage

# Open the plain text file whose name is in textfile for reading.
with open(textfile) as fp:
    # Create a text/plain message
    msg = EmailMessage()
    msg.set_content(fp.read())

# me == the sender's email address
# you == the recipient's email address
msg['Subject'] = f'The contents of {textfile}'
msg['From'] = me
msg['To'] = you

# Send the message via our own SMTP server.
s = smtplib.SMTP('localhost')
s.send_message(msg)
s.quit()

El análisis de los encabezados RFC 822 [https://tools.ietf.org/html/rfc822.html] se pueden hacer fácilmente usando las clases del módulo parser:

# Import the email modules we'll need
from email.parser import BytesParser, Parser
from email.policy import default

# If the e-mail headers are in a file, uncomment these two lines:
# with open(messagefile, 'rb') as fp:
#     headers = BytesParser(policy=default).parse(fp)

#  Or for parsing headers in a string (this is an uncommon operation), use:
headers = Parser(policy=default).parsestr(
        'From: Foo Bar <user@example.com>\n'
        'To: <someone_else@example.com>\n'
        'Subject: Test message\n'
        '\n'
        'Body would go here\n')

#  Now the header items can be accessed as a dictionary:
print('To: {}'.format(headers['to']))
print('From: {}'.format(headers['from']))
print('Subject: {}'.format(headers['subject']))

# You can also access the parts of the addresses:
print('Recipient username: {}'.format(headers['to'].addresses[0].username))
print('Sender name: {}'.format(headers['from'].addresses[0].display_name))

Aquí hay un ejemplo de cómo enviar un mensaje MIME que contiene un grupo de fotos familiares que pueden residir en un directorio:

# Import smtplib for the actual sending function
import smtplib

# And imghdr to find the types of our images
import imghdr

# Here are the email package modules we'll need
from email.message import EmailMessage

# Create the container email message.
msg = EmailMessage()
msg['Subject'] = 'Our family reunion'
# me == the sender's email address
# family = the list of all recipients' email addresses
msg['From'] = me
msg['To'] = ', '.join(family)
msg.preamble = 'You will not see this in a MIME-aware mail reader.\n'

# Open the files in binary mode.  Use imghdr to figure out the
# MIME subtype for each specific image.
for file in pngfiles:
    with open(file, 'rb') as fp:
        img_data = fp.read()
    msg.add_attachment(img_data, maintype='image',
                                 subtype=imghdr.what(None, img_data))

# Send the email via our own SMTP server.
with smtplib.SMTP('localhost') as s:
    s.send_message(msg)

Aquí hay un ejemplo de cómo enviar todo el contenido de un directorio como un mensaje de correo electrónico: 1

#!/usr/bin/env python3

"""Send the contents of a directory as a MIME message."""

import os
import smtplib
# For guessing MIME type based on file name extension
import mimetypes

from argparse import ArgumentParser

from email.message import EmailMessage
from email.policy import SMTP

def main():
    parser = ArgumentParser(description="""\
Send the contents of a directory as a MIME message.
Unless the -o option is given, the email is sent by forwarding to your local
SMTP server, which then does the normal delivery process.  Your local machine
must be running an SMTP server.
""")
    parser.add_argument('-d', '--directory',
                        help="""Mail the contents of the specified directory,
                        otherwise use the current directory.  Only the regular
                        files in the directory are sent, and we don't recurse to
                        subdirectories.""")
    parser.add_argument('-o', '--output',
                        metavar='FILE',
                        help="""Print the composed message to FILE instead of
                        sending the message to the SMTP server.""")
    parser.add_argument('-s', '--sender', required=True,
                        help='The value of the From: header (required)')
    parser.add_argument('-r', '--recipient', required=True,
                        action='append', metavar='RECIPIENT',
                        default=[], dest='recipients',
                        help='A To: header value (at least one required)')
    args = parser.parse_args()
    directory = args.directory
    if not directory:
        directory = '.'
    # Create the message
    msg = EmailMessage()
    msg['Subject'] = f'Contents of directory {os.path.abspath(directory)}'
    msg['To'] = ', '.join(args.recipients)
    msg['From'] = args.sender
    msg.preamble = 'You will not see this in a MIME-aware mail reader.\n'

    for filename in os.listdir(directory):
        path = os.path.join(directory, filename)
        if not os.path.isfile(path):
            continue
        # Guess the content type based on the file's extension.  Encoding
        # will be ignored, although we should check for simple things like
        # gzip'd or compressed files.
        ctype, encoding = mimetypes.guess_type(path)
        if ctype is None or encoding is not None:
            # No guess could be made, or the file is encoded (compressed), so
            # use a generic bag-of-bits type.
            ctype = 'application/octet-stream'
        maintype, subtype = ctype.split('/', 1)
        with open(path, 'rb') as fp:
            msg.add_attachment(fp.read(),
                               maintype=maintype,
                               subtype=subtype,
                               filename=filename)
    # Now send or store the message
    if args.output:
        with open(args.output, 'wb') as fp:
            fp.write(msg.as_bytes(policy=SMTP))
    else:
        with smtplib.SMTP('localhost') as s:
            s.send_message(msg)

if __name__ == '__main__':
    main()

Aquí hay un ejemplo de cómo descomprimir un mensaje MIME como el anterior, en un directorio de archivos:

#!/usr/bin/env python3

"""Unpack a MIME message into a directory of files."""

import os
import email
import mimetypes

from email.policy import default

from argparse import ArgumentParser

def main():
    parser = ArgumentParser(description="""\
Unpack a MIME message into a directory of files.
""")
    parser.add_argument('-d', '--directory', required=True,
                        help="""Unpack the MIME message into the named
                        directory, which will be created if it doesn't already
                        exist.""")
    parser.add_argument('msgfile')
    args = parser.parse_args()

    with open(args.msgfile, 'rb') as fp:
        msg = email.message_from_binary_file(fp, policy=default)

    try:
        os.mkdir(args.directory)
    except FileExistsError:
        pass

    counter = 1
    for part in msg.walk():
        # multipart/* are just containers
        if part.get_content_maintype() == 'multipart':
            continue
        # Applications should really sanitize the given filename so that an
        # email message can't be used to overwrite important files
        filename = part.get_filename()
        if not filename:
            ext = mimetypes.guess_extension(part.get_content_type())
            if not ext:
                # Use a generic bag-of-bits extension
                ext = '.bin'
            filename = f'part-{counter:03d}{ext}'
        counter += 1
        with open(os.path.join(args.directory, filename), 'wb') as fp:
            fp.write(part.get_payload(decode=True))

if __name__ == '__main__':
    main()

Aquí hay un ejemplo de cómo crear un mensaje HTML con una versión alternativa de texto sin formato. Para hacer las cosas un poco más interesantes, incluimos una imagen relacionada en la parte html, y guardamos una copia de lo que vamos a enviar en el disco, además de enviarlo.

#!/usr/bin/env python3

import smtplib

from email.message import EmailMessage
from email.headerregistry import Address
from email.utils import make_msgid

# Create the base text message.
msg = EmailMessage()
msg['Subject'] = "Ayons asperges pour le déjeuner"
msg['From'] = Address("Pepé Le Pew", "pepe", "example.com")
msg['To'] = (Address("Penelope Pussycat", "penelope", "example.com"),
             Address("Fabrette Pussycat", "fabrette", "example.com"))
msg.set_content("""\
Salut!

Cela ressemble à un excellent recipie[1] déjeuner.

[1] http://www.yummly.com/recipe/Roasted-Asparagus-Epicurious-203718

--Pepé
""")

# Add the html version.  This converts the message into a multipart/alternative
# container, with the original text message as the first part and the new html
# message as the second part.
asparagus_cid = make_msgid()
msg.add_alternative("""\
<html>
  <head></head>
  <body>
    <p>Salut!</p>
    <p>Cela ressemble à un excellent
        <a href="http://www.yummly.com/recipe/Roasted-Asparagus-Epicurious-203718">
            recipie
        </a> déjeuner.
    </p>
    <img src="cid:{asparagus_cid}" />
  </body>
</html>
""".format(asparagus_cid=asparagus_cid[1:-1]), subtype='html')
# note that we needed to peel the <> off the msgid for use in the html.

# Now add the related image to the html part.
with open("roasted-asparagus.jpg", 'rb') as img:
    msg.get_payload()[1].add_related(img.read(), 'image', 'jpeg',
                                     cid=asparagus_cid)

# Make a local copy of what we are going to send.
with open('outgoing.msg', 'wb') as f:
    f.write(bytes(msg))

# Send the message via local SMTP server.
with smtplib.SMTP('localhost') as s:
    s.send_message(msg)

Si nos enviaron el mensaje del último ejemplo, aquí hay una forma en que podríamos procesarlo:

import os
import sys
import tempfile
import mimetypes
import webbrowser

# Import the email modules we'll need
from email import policy
from email.parser import BytesParser

# An imaginary module that would make this work and be safe.
from imaginary import magic_html_parser

# In a real program you'd get the filename from the arguments.
with open('outgoing.msg', 'rb') as fp:
    msg = BytesParser(policy=policy.default).parse(fp)

# Now the header items can be accessed as a dictionary, and any non-ASCII will
# be converted to unicode:
print('To:', msg['to'])
print('From:', msg['from'])
print('Subject:', msg['subject'])

# If we want to print a preview of the message content, we can extract whatever
# the least formatted payload is and print the first three lines.  Of course,
# if the message has no plain text part printing the first three lines of html
# is probably useless, but this is just a conceptual example.
simplest = msg.get_body(preferencelist=('plain', 'html'))
print()
print(''.join(simplest.get_content().splitlines(keepends=True)[:3]))

ans = input("View full message?")
if ans.lower()[0] == 'n':
    sys.exit()

# We can extract the richest alternative in order to display it:
richest = msg.get_body()
partfiles = {}
if richest['content-type'].maintype == 'text':
    if richest['content-type'].subtype == 'plain':
        for line in richest.get_content().splitlines():
            print(line)
        sys.exit()
    elif richest['content-type'].subtype == 'html':
        body = richest
    else:
        print("Don't know how to display {}".format(richest.get_content_type()))
        sys.exit()
elif richest['content-type'].content_type == 'multipart/related':
    body = richest.get_body(preferencelist=('html'))
    for part in richest.iter_attachments():
        fn = part.get_filename()
        if fn:
            extension = os.path.splitext(part.get_filename())[1]
        else:
            extension = mimetypes.guess_extension(part.get_content_type())
        with tempfile.NamedTemporaryFile(suffix=extension, delete=False) as f:
            f.write(part.get_content())
            # again strip the <> to go from email form of cid to html form.
            partfiles[part['content-id'][1:-1]] = f.name
else:
    print("Don't know how to display {}".format(richest.get_content_type()))
    sys.exit()
with tempfile.NamedTemporaryFile(mode='w', delete=False) as f:
    # The magic_html_parser has to rewrite the href="cid:...." attributes to
    # point to the filenames in partfiles.  It also has to do a safety-sanitize
    # of the html.  It could be written using html.parser.
    f.write(magic_html_parser(body.get_content(), partfiles))
webbrowser.open(f.name)
os.remove(f.name)
for fn in partfiles.values():
    os.remove(fn)

# Of course, there are lots of email messages that could break this simple
# minded program, but it will handle the most common ones.

Hasta el aviso, el resultado de lo anterior es:

To: Penelope Pussycat <penelope@example.com>, Fabrette Pussycat <fabrette@example.com>
From: Pepé Le Pew <pepe@example.com>
Subject: Ayons asperges pour le déjeuner

Salut!

Cela ressemble à un excellent recipie[1] déjeuner.

Notas al pie

1

Gracias a Matthew Dixon Cowles por la inspiración y ejemplos originales.

email.message.Message: Representar un mensaje de correo electrónico usando la API compat32

La clase Message es muy similar a la clase EmailMessage, sin los métodos añadidos por esa clase y con el comportamiento predeterminado de algunos otros métodos siendo ligeramente diferente. También documentamos aquí algunos métodos que, aun siendo soportados por EmailMessage, no están recomendados a no ser que estés lidiando con código heredado.

Por lo demás, la filosofía y estructura de las dos clases es la misma.

Este documento describe el comportamiento bajo la política por defecto (para Message) Compat32. Si vas a usar otra política, deberías estar usando la clase EmailMessage en su lugar.

An email message consists of headers and a payload. Headers must be RFC 5322 [https://tools.ietf.org/html/rfc5322.html] style names and values, where the field name and value are separated by a colon. The colon is not part of either the field name or the field value. The payload may be a simple text message, or a binary object, or a structured sequence of sub-messages each with their own set of headers and their own payload. The latter type of payload is indicated by the message having a MIME type such as multipart/* or message/rfc822.

El modelo conceptual proporcionado por un objeto Message es el de un diccionario ordenado de encabezados con métodos adicionales para acceder a información especializada de los encabezados, para acceder a la carga, para generar una versión serializada del mensaje y para recorrer recursivamente el árbol del objeto. Ten en cuenta que son soportados encabezados duplicados pero deben ser usados métodos especiales para acceder a ellos.

El pseudodiccionario Message es indexado por los nombres de encabezados, los cuales deben ser valores ASCII. Los valores del diccionario son cadenas que se supone que contienen sólo caracteres ASCII; hay algún manejo especial para la entrada no ASCII, pero esta no siempre produce los resultados correctos. Los encabezados son almacenados y retornados preservando mayúsculas y minúsculas, pero los nombres de campos son emparejados sin distinción entre mayúsculas y minúsculas. También puede haber sólo un encabezado de envoltura, también conocido como el encabezado Unix-From o el encabezado From_. La carga (payload) es una cadena o bytes, en el caso de objetos de mensajes simples, o una lista de objetos Message, para contenedores de documentos MIME (ej. multipart/* y message/rfc822).

Aquí están los métodos de la clase Message:

class email.message.Message(policy=compat32)

Si se especifica policy (debe ser una instancia de una clase policy) utiliza las reglas que especifica para actualizar y serializar la representación del mensaje. Si no se define policy, utiliza la política compat32, la cual mantiene compatibilidad con la versión de Python 3.2 del paquete email. Para más información consulta la documentación de policy.

Distinto en la versión 3.3: El argumento de palabra clave policy fue añadido.

as_string(unixfrom=False, maxheaderlen=0, policy=None)

Retorna el mensaje completo aplanado como una cadena. Cuando el parámetro opcional unixfrom es verdadero, el encabezado de envoltura se incluye en la cadena retornada. unixfrom es por defecto False. Por razones de compatibilidad con versiones anteriores, maxheaderlen es 0 por defecto, por lo que si quieres un valor diferente debes debes sobreescribirlo explícitamente (el valor especificado por max_line_length en la política será ignorado por este método). El argumento policy puede ser usado para sobrescribir la política por defecto obtenida de la instancia del mensaje. Esto puede ser usado para controlar algo del formato producido por el método, ya que la policy especificada puede ser pasada al Generator.

Aplanar el mensaje puede desencadenar cambios en Message si por defecto necesita ser rellenado para completar la transformación a una cadena (por ejemplo, límites MIME pueden ser generados o modificados).

Ten en cuenta que este método es proporcionado como conveniencia y puede no siempre formatear el mensaje de la forma que quieres. Por ejemplo, de forma predeterminada no realiza la mutilación de líneas que comienzan con From que es requerida por el formato unix mbox. Para mayor flexibilidad, instancia un Generator y utiliza su método flatten() directamente. Por ejemplo:

from io import StringIO
from email.generator import Generator
fp = StringIO()
g = Generator(fp, mangle_from_=True, maxheaderlen=60)
g.flatten(msg)
text = fp.getvalue()

Si el objeto de mensaje contiene datos binarios que no están codificados de acuerdo a los estándares RFC, los datos no compatibles serán reemplazados por puntos de código Unicode de «carácter desconocido». (Consulta también as_bytes() y BytesGenerator.)

Distinto en la versión 3.4: el argumento de palabra clave policy fue añadido.

__str__()

Equivalente a as_string(). Permite a str(msg) producir una cadena conteniendo el mensaje formateado.

as_bytes(unixfrom=False, policy=None)

Retorna el mensaje completo aplanado como un objeto de bytes. Cuando el argumento opcional unixfrom es verdadero, el encabezado de envoltura se incluye en la cadena retornada. unixfrom es por defecto False. El argumento policy puede ser usado para sobrescribir la política por defecto obtenida desde la instancia del mensaje. Esto puede ser usado para controlar algo del formato producido por el método, ya que el policy especificado será pasado al BytesGenerator.

Aplanar el mensaje puede desencadenar cambios en Message si por defecto necesita ser rellenado para completar la transformación a una cadena (por ejemplo, límites MIME pueden ser generados o modificados).

Nota que este método es proporcionado como conveniencia y puede no siempre formatear el mensaje de la forma que quieres. Por ejemplo, por defecto no realiza la mutilación de línea que comienzan con From que es requerida por el formato unix mbox. Para mayor flexibilidad, instancia un BytesGenerator y utiliza su método flatten() directamente. Por ejemplo:

from io import BytesIO
from email.generator import BytesGenerator
fp = BytesIO()
g = BytesGenerator(fp, mangle_from_=True, maxheaderlen=60)
g.flatten(msg)
text = fp.getvalue()

Nuevo en la versión 3.4.

__bytes__()

Equivalente a as_bytes(). Permite a bytes(msg) producir un objeto de bytes conteniendo el mensaje formateado.

Nuevo en la versión 3.4.

is_multipart()

Retorna True si la carga del mensaje es una lista de objetos heredados de Message, si no retorna False. Cuando is_multipart() retorna False, la carga debe ser un objeto de cadena (el cual puede ser una carga CTE codificada en binario). (Ten en cuenta que is_multipart() retornando True no significa necesariamente que «msg.get_content_maintype() == “multipart”» retornará True. Por ejemplo, is_multipart retornará True cuando el Message es de tipo message/rfc822.)

set_unixfrom(unixfrom)

Establece el mensaje del encabezado de envoltura a unixfrom, el cual debe ser una cadena.

get_unixfrom()

Retorna el mensaje del encabezado de envoltura. Por defecto a None si el encabezado de envoltura nunca fue definido.

attach(payload)

Añade el payload dado a la carga actual, la cual debe ser None o una lista de objetos Message antes de la invocación. Después de la invocación, la carga siempre será una lista de objetos Message. Si quieres definir la carga a un objeto escalar (ej. una cadena), usa set_payload() en su lugar.

Este es un método heredado. En la clase EmailMessage su funcionalidad es remplazada por set_content() y los métodos relacionados make y add.

get_payload(i=None, decode=False)

Retorna la carga (payload) actual, la cual será una lista de objetos Message cuando is_multipart() es True, o una cadena cuando is_multipart() es False. Si la carga es una lista y mutas el objeto de lista, modificarás la carga del mensaje.

Con el argumento opcional i, get_payload() retornará el elemento número i de la carga (payload), contando desde cero, si is_multipart() es True. Un IndexError será generado si i es menor que 0 ó mayor o igual que el número de elementos en la carga. Si la carga es una cadena (ej. is_multipart() es False) y se define i, se genera un TypeError.

El argumento opcional decode es un indicador que determina si una carga debería ser decodificada o no, de acuerdo al encabezado Content-Transfer-Encoding. Cuando es True y el mensaje no es multiparte, la carga será decodificada si el valor de su encabezado es quoted-printable o base64. Si se usa alguna otra codificación o falta el encabezado Content-Transfer-Encoding, la carga es retornada tal cual (sin decodificar). En todos los casos el valor retornado son datos binarios. Si el mensaje es multiparte y el indicador decode es True, entonces se retorna None. Si la carga es base64 y no fue perfectamente formada (falta relleno, tiene caracteres fuera del alfabeto base64), entonces un defecto apropiado será añadido a la propiedad defect del mensaje (InvalidBase64PaddingDefect o InvalidBase64CharactersDefect, respectivamente).

Cuando decode es False (por defecto) el cuerpo es retornado como una cadena sin decodificar el Content-Transfer-Encoding. Sin embargo, para un Content-Transfer-Encoding de 8bit, se realiza un intento para decodificar los bytes originales usando el charset especificado por el encabezado Content-Type, usando el manejador de error replace. Si ningún charset es especificado o si el charset dado no es reconocido por el paquete email, el cuerpo es decodificado usando el conjunto de caracteres ASCII por defecto.

Este es un método heredado. En la clase EmailMessage su funcionalidad es remplazada por get_content() y iter_parts().

set_payload(payload, charset=None)

Define la carga completa del objeto mensaje a payload. Es responsabilidad del cliente asegurar invariantes de carga. El argumento opcional charset define el conjunto de caracteres por defecto del mensaje; consulta set_charset() para más detalles.

Este es un método heredado. En la clase EmailMessage su funcionalidad es remplazada por set_content().

set_charset(charset)

Define el junto de caracteres de la carga a charset, el cual puede ser tanto una instancia Charset (ver email.charset), una cadena denominando un conjunto de caracteres, o None. Si es una cadena, será convertida a una instancia Charset. Si charset es None, el parámetro charset será eliminado del encabezado Content-Type (el mensaje no será modificado de otra manera). Cualquier otro valor generará un TypeError.

Si no hay un encabezado existente MIME-Version, será añadido uno. Si no hay un encabezado existente Content-Type, será añadido uno con valor text/plain. Tanto como si el encabezado Content-Type existe actualmente como si no, su parámetro charset será establecido a charset.output_charset. Si charset.input_charset y charset.output_charset difieren, la carga será recodificada al output_charset. Si no hay un encabezado existente Content-Transfer-Encoding, entonces la carga será codificada por transferencia, si es necesario, usando el Charset especificado y un encabezado con el valor apropiado será añadido. Si ya existe un encabezado Content-Transfer-Encoding, la carga se asume que ya está correctamente codificada usando ese Content-Transfer-Encoding y no es modificada.

Este es un método heredado. En la clase EmailMessage su funcionalidad es remplazada por el parámetro charset del método email.emailmessage.EmailMessage.set_content().

get_charset()

Retorna la instancia Charset asociada con la carga del mensaje.

Este es un método heredado. En la clase EmailMessage siempre retorna None.

Los siguientes métodos implementan una interfaz parecida a un mapeo para acceder a los encabezados RFC 2822 [https://tools.ietf.org/html/rfc2822.html] del mensaje. Ten en cuenta que hay algunas diferencias semánticas entre esos métodos y una interfaz de mapeo normal (ej. diccionario). Por ejemplo, en un diccionario no hay claves duplicadas, pero aquí pueden haber encabezados de mensaje duplicados. También, en diccionarios no hay un orden garantizado de las claves retornadas por keys(), pero en un objeto Message, los encabezados siempre son retornados en el orden que aparecieron en el mensaje original, o en el que fueron añadidos al mensaje más tarde. Cualquier encabezado eliminado y vuelto a adicionar siempre es añadido al final de la lista de encabezados.

Esas diferencias semánticas son intencionales y están sesgadas hacia la máxima comodidad.

Ten en cuenta que en todos los casos, cualquier encabezado de envoltura presente en el mensaje no está incluido en la interfaz de mapeo.

En un modelo generado desde bytes, cualesquiera valores de encabezado que (en contravención de los RFCs) contienen bytes ASCII serán representados, cuando sean obtenidos mediante esta interfaz, como objetos Header con un conjunto de caracteres unknown-8bit.

__len__()

Retorna el número total de encabezados, incluyendo duplicados.

__contains__(name)

Retorna True si el objeto mensaje tiene un campo llamado name. La concordancia se realiza sin distinguir mayúsculas de minúsculas y name no debería incluir el caracter de doble punto final. Usado para el operador in, ej:

if 'message-id' in myMessage:
   print('Message-ID:', myMessage['message-id'])

__getitem__(name)

Retorna el valor del campo del encabezado nombrado. name no debe incluir el separador de campo de doble punto. Si falta un encabezado, se retorna None; nunca se genera un error KeyError.

Ten en cuenta que si el campo nombrado aparece más de una vez en los encabezados del mensaje, no se define cuales serán exactamente aquellos valores de campos retornados. Usa el método get_all() para obtener los valores de todos los encabezados nombrados existentes.

__setitem__(name, val)

Añade un encabezado al mensaje con el nombre de campo name y el valor val. El campo es añadido al final de los campos existentes del mensaje.

Ten en cuenta que esto no sobreescribe ni elimina ningún encabezado existente con el mismo nombre. Si quieres asegurar que el nuevo encabezado es el único presente en el mensaje con el nombre de campo name, elimina el campo primero, ej:

del msg['subject']
msg['subject'] = 'Python roolz!'

__delitem__(name)

Elimina todas las ocurrencias de un campo con el nombre name de los encabezados del mensaje. No se genera ninguna excepción si el encabezado nombrado no está presente en los encabezados.

keys()

Retorna una lista de todos los nombres de campos de encabezados del mensaje.

values()

Retorna una lista de todos los valores de campos del mensaje.

items()

Retorna una lista de tuplas de dos elementos conteniendo todos los campos y valores de encabezados del mensaje.

get(name, failobj=None)

Retorna el valor del campo de encabezado nombrado. Esto es idéntico a __getitem__() excepto que el argumento failobj es retornado si falta el encabezado nombrado (por defecto a None).

Aquí hay algunos métodos útiles adicionales:

get_all(name, failobj=None)

Retorna una lista de todos los valores para el campo denominado name. Si no hay tales encabezados nombrados en el mensaje, retorna failobj (por defecto None).

add_header(_name, _value, **_params)

Configuración de encabezado extendida. Este método es similar a __setitem__() excepto que pueden ser provistos parámetros adicionales de encabezado como argumentos de palabra clave. _name es el campo de encabezado a añadir y _value es el valor primario para el encabezado.

Para cada elemento en el diccionario de argumentos de palabra clave _params, la clave se toma como el nombre del parámetro con guiones bajos convertidos a guiones medios (ya que los guiones medios son ilegales como identificadores en Python). Normalmente, el parámetro será añadido como key="value" a no ser que el valor sea None, en cuyo caso sólo la clave será añadida. Si el valor contiene caracteres no ASCII, puede ser especificado como una tupla de tres elementos en el formato (CHARSET, LANGUAGE, VALUE), donde CHARSET es una cadena que nombra el conjunto de caracteres a ser usado al codificar el valor, LANGUAGE puede normalmente ser definido a None o una cadena vacía (ver RFC 2231 [https://tools.ietf.org/html/rfc2231.html] para otras posibilidades) y VALUE es la cadena del valor conteniendo puntos de caracteres no ASCII. Si no se pasa una tupla de tres elementos y el valor contiene caracteres no ASCII, se codifica automáticamente en formato RFC 2231 [https://tools.ietf.org/html/rfc2231.html] usando CHARSET como utf-8 y LANGUAGE como None.

Aquí hay un ejemplo:

msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')

Esto añadirá un encabezado que se verá como

Content-Disposition: attachment; filename="bud.gif"

Un ejemplo con caracteres no ASCII:

msg.add_header('Content-Disposition', 'attachment',
               filename=('iso-8859-1', '', 'Fußballer.ppt'))

Lo que produce

Content-Disposition: attachment; filename*="iso-8859-1''Fu%DFballer.ppt"

replace_header(_name, _value)

Reemplaza un encabezado. Reemplaza el primer encabezado encontrado en el mensaje que concuerda con _name, conservando el orden del encabezado y el nombre del campo. Si no se encuentra ningún encabezado que concuerde, se genera un error KeyError.

get_content_type()

Retorna el tipo de contenido del mensaje. La cadena retornada se fuerza a letras minúsculas de la forma maintype/subtype. Si no hay ningún encabezado Content-Type en el mensaje será retornado el tipo por defecto como es dado por get_default_type(). Dado que según RFC 2045 [https://tools.ietf.org/html/rfc2045.html], los mensajes tienen siempre un tipo predeterminado, get_content_type() siempre retornará un valor.

RFC 2045 [https://tools.ietf.org/html/rfc2045.html] define el tipo predeterminado del mensaje a text/plain a no ser que aparezca dentro de un contenedor multipart/digest, en cuyo caso sería message/rfc822. Si el encabezado Content-Type tiene una especificación de tipo inválido, RFC 2045 [https://tools.ietf.org/html/rfc2045.html] ordena que el tipo por defecto sea text/plain.

get_content_maintype()

Retorna el tipo de contenido principal del mensaje. Esta es la parte maintype de la cadena retornada por get_content_type().

get_content_subtype()

Retorna el tipo del subcontenido del mensaje. Esta es la parte subtype de la cadena retornada por get_content_type().

get_default_type()

Retorna el tipo del contenido por defecto. La mayoría de mensajes tienen un tipo de contenido por defecto de text/plain, excepto para mensajes que son subpartes de contenedores multipart/digest. Tales subpartes tienen como tipo de contenido predeterminado message/rfc822.

set_default_type(ctype)

Establece el tipo de contenido por defecto. ctype debería ser text/plain o message/rfc822, aunque esto no es obligatorio. El tipo de contenido predeterminado no se almacena en el encabezado Content-Type.

get_params(failobj=None, header='content-type', unquote=True)

Retorna los parámetros del Content-Type del mensaje como una lista. Los elementos de la lista retornada son tuplas de dos elementos de pares clave/valor, tal y como son partidas por el signo '='. El lado izquierdo del '=' es la clave, mientras el lado derecho es el valor. Si no hay signo '=' en el parámetro, el valor es la cadena vacía, en caso contrario el valor es como se describe en get_param() y no está citado si el parámetro opcional unquote es True (por defecto).

El parámetro opcional failobj es el objeto a retornar si no hay encabezado Content-Type. El parámetro opcional header es el encabezado a buscar en lugar de Content-Type.

Este es un método heredado. En la clase EmailMessage su funcionalidad es remplazada por la propiedad params de los objetos individuales de encabezado retornados por los métodos de acceso del encabezado.

get_param(param, failobj=None, header='content-type', unquote=True)

Retorna el valor del parámetro param del encabezado Content-Type como una cadena. Si el mensaje no tiene encabezado Content-Type o si no existe tal parámetro, entonces se retorna failobj (por defecto es None).

El parámetro opcional header, si es definido, especifica el encabezado del mensaje a usar en lugar de Content-Type.

Las claves de parámetros siempre son comparadas distinguiendo entre mayúsculas y minúsculas. El valor de retorno puede ser una cadena, una tupla de 3 elementos si el parámetro fue codificado según RFC 2231 [https://tools.ietf.org/html/rfc2231.html]. Cuando es una tupla de 3 elementos, los elementos del valor tienen la forma (CHARSET, LANGUAGE, VALUE). Ten en cuenta que CHARSET y LANGUAGE pueden ser None, en cuyo caso debes considerar VALUE como codificado en el conjunto de caracteres us-ascii. Generalmente puedes ignorar LANGUAGE.

Si a tu aplicación no le importa si el parámetro fue codificado según RFC 2231 [https://tools.ietf.org/html/rfc2231.html], puedes contraer el valor del parámetro invocando email.utils.collapse_rfc2231_value(), pasando el valor de retorno desde get_param(). Esto retornará una cadena Unicode convenientemente decodificada cuando el valor es una tupla o la cadena original sin entrecomillar si no lo es. Por ejemplo:

rawparam = msg.get_param('foo')
param = email.utils.collapse_rfc2231_value(rawparam)

En cualquier caso, el valor del parámetro (tanto la cadena retornada o el elemento VALUE en la tupla de 3 elementos) siempre está sin entrecomillar, a no ser que unquote está establecido a False.

Este es un método heredado. En la clase EmailMessage su funcionalidad es remplazada por la propiedad params de los objetos individuales de encabezado retornados por los métodos de acceso del encabezado.

set_param(param, value, header='Content-Type', requote=True, charset=None, language='', replace=False)

Establece un parámetro en el encabezado Content-Type. Si el parámetro ya existe en el encabezado, su valor será remplazado con value. Si el encabezado Content-Type no ha sido definido todavía para este mensaje, será establecido a text/plain y el nuevo valor del parámetro será añadido según RFC 2045 [https://tools.ietf.org/html/rfc2045.html].

El parámetro opcional header especifica una alternativa a Content-Type y todos los parámetros serán entrecomillados si es necesario a no ser que el parámetro opcional requote sea False (por defecto es True).

Si se especifica el parámetro opcional charset, el parámetro será codificado de acuerdo a RFC 2231 [https://tools.ietf.org/html/rfc2231.html]. El parámetro opcional language especifica el lenguaje RFC 2231, por defecto una cadena vacía. Tanto charset como language deberían ser cadenas.

Si replace es False (por defecto) el encabezado será movido al final de la lista de encabezados. Si replace es True, el encabezado será actualizado.

Distinto en la versión 3.4: el parámetro de palabra clave replace fue añadido.

del_param(param, header='content-type', requote=True)

Elimina el parámetro dado completamente del encabezado Content-Type. El encabezado será reescrito en sí mismo sin el parámetro o su valor. Todos los valores serán entrecomillados si es necesario a no ser que requote sea False (por defecto es True). El parámetro opcional header especifica una alternativa a Content-Type.

set_type(type, header='Content-Type', requote=True)

Establece el tipo y subtipo principal para el encabezado Content-Type. type debe ser una cadena de la forma maintype/subtype, si no será generado un ValueError.

Este método remplaza el encabezado Content-Type, manteniendo todos los parámetros en su lugar. Si requote es False, este dejará el encabezado existente tal como está, en caso contrario los parámetros serán entrecomillados (por defecto).

Un encabezado alternativo puede ser especificado en el argumento header. Cuando el encabezado Content-Type es definido, un encabezado MIME-Version también es añadido.

Este es un método heredado. En la clase EmailMessage su funcionalidad es remplazada por los métodos make_ y add_.

get_filename(failobj=None)

Retorna el valor del parámetro filename del encabezado Content-Disposition del mensaje. Si el encabezado no tiene un parámetro filename, este método recurre a buscar el parámetro name en el encabezado Content-Type. Si tampoco se encuentra o falta el encabezado, entonces retorna failobj. La cadena retornada siempre será sin entrecomillar según email.utils.unquote().

get_boundary(failobj=None)

Retorna el valor del parámetro boundary del encabezado Content-Type del mensaje o failobj tanto si falta el encabezado como si no tiene parámetro boundary. La cadena retornada siempre será sin entrecomillar según email.utils.unquote().

set_boundary(boundary)

Establece el parámetro boundary del encabezado Content-Type a boundary. set_boundary() siempre entrecomillará boundary si es necesario. Se genera HeaderParseError si el objeto de mensaje no tiene encabezado Content-Type.

Ten en cuenta que usar este método es sutilmente diferente a borrar el antiguo encabezado Content-Type y añadir uno nuevo con el nuevo límite mediante add_header() porque set_boundary() preserva el orden del encabezado Content-Type en la lista de encabezados. Sin embargo, no conserva ninguna línea de continuación que pueden haber estado presentes en el encabezado original Content-Type.

get_content_charset(failobj=None)

Retorna el parámetro charset del encabezado Content-Type, forzado a letras minúsculas. Si no hay un encabezado Content-Type o si ese encabezado no tiene parámetro charset, se retorna failobj.

Ten en cuenta que este método difiere de get_charset(), el cual retorna la instancia Charset para la codificación por defecto del cuerpo del mensaje.

get_charsets(failobj=None)

Retorna una lista conteniendo los nombres de los conjuntos de caracteres en el mensaje. Si el mensaje es multipart, entonces la lista contendrá un elemento para cada subparte en la carga (payload), en caso contrario será una lista de un elemento.

Cada elemento en la lista será una cadena la cual es el valor del parámetro charset en el encabezado Content-Type para la subparte representada. Sin embargo, si la subparte no tiene encabezado Content-Type, no tiene parámetro charset o no es del tipo MIME text principal, entonces ese elemento en la lista retornada será failobj.

get_content_disposition()

Retorna el valor en minúsculas (sin parámetros) del encabezado del mensaje Content-Disposition si tiene uno o None. Los valores posibles para este método son inline, attachment o None si el mensaje sigue el RFC 2183 [https://tools.ietf.org/html/rfc2183.html].

Nuevo en la versión 3.5.

walk()

El método walk() es un generador de todo propósito el cual puede ser usado para iterar sobre todas las partes y subpartes de árbol de objeto de mensaje, en orden de recorrido de profundidad primero. Siempre usarás típicamente walk() como iterador en un bucle for; cada iteración retorna la siguiente subparte.

Aquí hay un ejemplo que imprime el tipo MIME de cada parte de una estructura de mensaje multiparte:

>>> for part in msg.walk():
...     print(part.get_content_type())
multipart/report
text/plain
message/delivery-status
text/plain
text/plain
message/rfc822
text/plain

walk itera sobre las subpartes de cualquier parte donde is_multipart() retorna True, aunque msg.get_content_maintype() == 'multipart' puede retornar False. Vemos esto en nuestro ejemplo haciendo uso de la función de ayuda de depuración _structure:

>>> for part in msg.walk():
...     print(part.get_content_maintype() == 'multipart',
...           part.is_multipart())
True True
False False
False True
False False
False False
False True
False False
>>> _structure(msg)
multipart/report
    text/plain
    message/delivery-status
        text/plain
        text/plain
    message/rfc822
        text/plain

Aquí las partes de message``no son ``multiparts, pero contienen subpartes. is_multipart() retorna True y walk desciende a las subpartes.

Los objetos Message pueden contener opcionalmente dos atributos de instancia, los cuales pueden ser usados al generar el texto plano de un mensaje MIME.

preamble

El formato de un documento MIME permite algo de texto entre la línea en blanco que sigue a los encabezados y la primera cadena límite multiparte. Normalmente, este texto nunca es visible en un lector de correo compatible con MIME porque queda fuera de la armadura MIME estándar. Sin embargo, viendo el texto del mensaje en crudo o viendo el mensaje en un lector no compatible con MIME, este texto puede volverse visible.

El atributo preamble contiene este texto de refuerzo adicional para documentos MIME. Cuando el Parser descubre algo de texto después de los encabezados pero antes de la primera cadena límite, asigna este texto al atributo preamble del mensaje. Cuando el Generator está escribiendo la representación de texto sin formato de un mensaje MIME y puede encontrar el mensaje como un atributo preamble, escribirá este texto en el área entre los encabezados y el primer límite. Consulta email.parser y email.generator para más detalles.

Ten en cuenta que si el objeto de mensaje no tiene preámbulo, el atributo preamble será None.

epilogue

El atributo epilogue actúa de la misma manera que el atributo preamble, excepto que contiene texto que aparece entre el último límite y el fin del mensaje.

No necesitas establecer el epílogo de la cadena vacía en orden para el Generator para imprimir una nueva línea al final del archivo.

defects

El atributo defects contiene una lista de todos los problemas encontrados al analizar este mensaje. Consulta email.errors para una descripción detallada de los posibles defectos de análisis.

email.mime: Creación de correo electrónico y objetos MIME desde cero

Código fuente: Lib/email/mime/ [https://github.com/python/cpython/tree/3.9/Lib/email/mime/]

Este módulo forma parte de la API heredada de correo electrónico (Compat32). Su funcionalidad se sustituye parcialmente por el contentmanager en la nueva API, pero en ciertas aplicaciones estas clases pueden seguir siendo útiles, incluso en código no heredado.

Normalmente, se obtiene una estructura de objeto de mensaje pasando un archivo o algún texto a un analizador, que analiza el texto y retorna el objeto de mensaje principal. Sin embargo, también puede crear una estructura de mensajes completa desde cero, o incluso objetos individuales Message a mano. De hecho, también puede tomar una estructura existente y agregar nuevos objetos Message, moverlos, etc. Esto compone una interfaz muy conveniente para cortar y gestionar mensajes MIME.

Puede crear una nueva estructura de objeto mediante la creación de una instancia de Message, añadiendo accesorios y todos los encabezados necesarios manualmente. Para mensajes MIME sin embargo, el paquete email proporciona subclases convenientes para facilitar las cosas.

Descripción de las clases:

class email.mime.base.MIMEBase(_maintype, _subtype, *, policy=compat32, **_params)

Módulo: email.mime.base

Esta es la clase básica para todas las subclases específicas Message para MIME. Normalmente no creará instancias específicas de la MIMEBase, aunque es posible. La MIMEBase se proporciona principalmente como una clase básica conveniente para subclases más específicas, apropiadas para MIME.

_maintype es el tipo principal Content-Type (por ejemplo text o image), y _subtype es el tipo menor Content-Type (por ejemplo plain o gif). _params es un diccionario de parámetro clave/valor y se pasa directamente a Message.add_header.

Si se especifica policy, (por defecto, la directiva compat32) se pasará a Message.

La clase MIMEBase siempre agrega un encabezado Content-Type (basado en _maintype, _subtype y _params), y un encabezado MIME-Versión (siempre establecido en 1.0).

Distinto en la versión 3.6: Se ha añadido el parámetro policy de solo palabra clave.

class email.mime.nonmultipart.MIMENonMultipart

Módulo: email.mime.nonmultipart

Una subclase de MIMEBase, es una clase base intermedia para los mensajes MIME que no son multipart. El propósito principal de esta clase es evitar el uso del método attach(), que solo tiene sentido para los mensajes multipart. Si se llama a attach(), se lanza una excepción MultipartConversionError.

class email.mime.multipart.MIMEMultipart(_subtype='mixed', boundary=None, _subparts=None, *, policy=compat32, **_params)

Módulo: email.mime.multipart

Una subclase de MIMEBase, se trata de una clase base intermedia para los mensajes MIME que son multipart. El valor predeterminado opcional de _subtype es mixed, pero se puede utilizar para especificar el subtipo del mensaje. Se agregará un encabezado Content-Type de multipart/_subtype al objeto del mensaje. También se agregará un encabezado MIME-Version.

El boundary opcional es la cadena de límite multiparte. Cuando None (valor predeterminado), el límite se calcula cuando es necesario (por ejemplo, cuando se serializa el mensaje).

_subparts es una secuencia de subpartes iniciales para la carga útil. Debe ser posible convertir esta secuencia en una lista. Siempre puede adjuntar nuevas subpartes al mensaje mediante el método Message.attach.

El valor predeterminado del argumento policy opcional es compat32.

Los parámetros adicionales para el encabezado Content-Type se toman de los argumentos de palabra clave, o se pasan al argumento _params, que es un diccionario de palabras clave.

Distinto en la versión 3.6: Se ha añadido el parámetro policy de solo palabra clave.

class email.mime.application.MIMEApplication(_data, _subtype='octet-stream', _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

Módulo: email.mime.application

Una subclase de MIMENonMultipart, la clase MIMEApplication se utiliza para representar objetos de mensaje MIME de tipo principal application. _data es una cadena de caracteres que contiene los datos de bytes sin procesar. _subtype opcional especifica el subtipo MIME y el valor predeterminado es octet-stream.

_encoder opcional es una recurso invocable (es decir, una función) que realizará la codificación real de los datos para el transporte. Este invocable toma un argumento, que es la instancia MIMEApplication. Debe utilizar get_payload() y set_payload() para cambiar la carga útil a la forma codificada. También debe agregar cualquier Content-Transfer-Encoding u otros encabezados al objeto del mensaje según sea necesario. La codificación predeterminada es base64. Consulte el módulo email.encoders para obtener una lista de los codificadores integrados.

El valor predeterminado del argumento policy opcional es compat32.

_params se pasan directamente al constructor de la clase base.

Distinto en la versión 3.6: Se ha añadido el parámetro policy de solo palabra clave.

class email.mime.audio.MIMEAudio(_audiodata, _subtype=None, _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

Módulo: email.mime.audio

Una subclase de MIMENonMultipart, la clase MIMEAudio se utiliza para crear objetos de mensaje MIME de tipo principal audio. _audiodata es una cadena de caracteres que contiene los datos de audio sin procesar. Si estos datos pueden ser decodificados por el módulo estándar de Python sndhdr, entonces el subtipo se incluirá automáticamente en el encabezado Content-Type. De lo contrario, puede especificar explícitamente el subtipo de audio mediante el argumento _subtype. Si no se pudo adivinar el tipo secundario y no se ha proporcionado _subtype, se lanza TypeError.

_encoder opcional es un recurso invocable (es decir, una función) que realizará la codificación real de los datos de audio para el transporte. Este invocable toma un argumento, que es la instancia MIMEAudio. Debe utilizar get_payload() y set_payload() para cambiar la carga útil a la forma codificada. También debe agregar cualquier Content-Transfer-Encoding u otros encabezados al objeto del mensaje según sea necesario. La codificación predeterminada es base64. Consulte el módulo email.encoders para obtener una lista de los codificadores integrados.

El valor predeterminado del argumento policy opcional es compat32.

_params se pasan directamente al constructor de la clase base.

Distinto en la versión 3.6: Se ha añadido el parámetro policy de solo palabra clave.

class email.mime.image.MIMEImage(_imagedata, _subtype=None, _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

Módulo: email.mime.image

Una subclase de MIMENonMultipart, la clase MIMEImage se utiliza para crear objetos de mensaje MIME de tipo principal image. _imagedata es una cadena de caracteres que contiene los datos de imagen sin procesar. Si estos datos pueden ser decodificados por el módulo estándar de Python imghdr, entonces el subtipo se incluirá automáticamente en el encabezado Content-Type. De lo contrario, puede especificar explícitamente el subtipo de imagen mediante el argumento _subtype. Si no se pudo adivinar el tipo secundario y no se ha proporcionado _subtype, se lanza TypeError.

_encoder opcional es un recurso invocable (es decir, una función) que realizará la codificación real de los datos de imagen para el transporte. Este invocable toma un argumento, que es la instancia MIMEImage. Debe utilizar get_payload() y set_payload() para cambiar la carga útil a la forma codificada. También debe agregar cualquier Content-Transfer-Encoding u otros encabezados al objeto del mensaje según sea necesario. La codificación predeterminada es base64. Consulte el módulo email.encoders para obtener una lista de los codificadores integrados.

El valor predeterminado del argumento policy opcional es compat32.

_params se pasan directamente al constructor MIMEBase.

Distinto en la versión 3.6: Se ha añadido el parámetro policy de solo palabra clave.

class email.mime.message.MIMEMessage(_msg, _subtype='rfc822', *, policy=compat32)

Módulo: email.mime.message

Una subclase de MIMENonMultipart, la clase MIMEMessage se utiliza para crear objetos MIME de tipo principal message. _msg se utiliza como la carga y debe ser una instancia de la clase Message (o una subclase de la misma), de lo contrario se lanza un TypeError.

_subtype opcional establece el subtipo del mensaje; por defecto es rfc822.

El valor predeterminado del argumento policy opcional es compat32.

Distinto en la versión 3.6: Se ha añadido el parámetro policy de solo palabra clave.

class email.mime.text.MIMEText(_text, _subtype='plain', _charset=None, *, policy=compat32)

Módulo: email.mime.text

Una subclase de MIMENonMultipart, la clase MIMEText se utiliza para crear objetos MIME de tipo principal text. _text es la cadena de caracteres de la carga útil. _subtype es el tipo menor y el valor predeterminado es plain. _charset es el paquete de caracteres del texto y se pasa como argumento al constructor MIMENonMultipart; el valor predeterminado es us-ascii si la cadena contiene sólo puntos de código ascii, y utf-8 en caso contrario. El parámetro _charset acepta una cadena o una instancia Charset.

A menos que el argumento _charset se establezca explícitamente como None, el objeto MIMEText creado tendrá a la vez un encabezado Content-Type con un parámetro charset, y un encabezado Content-Transfer-Encoding. Esto significa que una llamada posterior a set_payload no dará lugar a una carga codificada, incluso si se pasa un conjunto de caracteres en el comando set_payload. Puede «restablecer» este comportamiento eliminando el encabezado Content-Transfer-Encoding, después de lo cual una llamada a set_payload codificará automáticamente la nueva carga útil (y agregará un nuevo encabezado Content-Transfer-Encoding).

El valor predeterminado del argumento policy opcional es compat32.

Distinto en la versión 3.5: _charset también acepta instancias Charset.

Distinto en la versión 3.6: Se ha añadido el parámetro policy de solo palabra clave.

email.header: Cabeceras internacionalizadas

Código fuente: Lib/email/header.py [https://github.com/python/cpython/tree/3.9/Lib/email/header.py]

Este módulo es parte de la API de email heredada (Compat32). En la API actual, la codificación y decodificación de las cabeceras se gestiona de forma transparente por la API de tipo diccionario de la clase EmailMessage. Además de los usos del código heredado, este módulo puede ser útil en aplicaciones que necesiten controlar completamente el conjunto de caracteres usado cuando se codifican las cabeceras.

El resto del texto de esta sección es la documentación original del módulo.

RFC 2822 [https://tools.ietf.org/html/rfc2822.html] es el estándar base que describe el formato de los mensajes de correo electrónico. Deriva del estándar anterior RFC 822 [https://tools.ietf.org/html/rfc822.html], cuyo uso se generalizó durante una época en la que la mayoría del correo electrónico se componía únicamente de caracteres ASCII. RFC 2822 [https://tools.ietf.org/html/rfc2822.html] es una especificación que se escribió asumiendo que el correo electrónico contiene solo caracteres ASCII 7-bit.

Por supuesto, al haberse extendido el correo electrónico por todo el mundo, se ha internacionalizado, de forma que ahora pueden usarse los conjuntos de caracteres específicos de un idioma en los mensajes de correo electrónico. El estándar base todavía requiere que los mensajes de correo electrónico sean transferidos usando solo caracteres ASCII 7-bit, así que se han escrito multitud de RFCs describiendo cómo codificar correos electrónicos que contengan caracteres no ASCII en formatos conforme a la RFC 2822 [https://tools.ietf.org/html/rfc2822.html]. Entre estas RFCs se incluyen RFC 2045 [https://tools.ietf.org/html/rfc2045.html], RFC 2046 [https://tools.ietf.org/html/rfc2046.html], RFC 2047 [https://tools.ietf.org/html/rfc2047.html] y RFC 2231 [https://tools.ietf.org/html/rfc2231.html]. El paquete email soporta estos estándares en sus módulos email.header y email.charset.

Si quieres incluir caracteres no ASCII en tus cabeceras de correo electrónico, por ejemplo en los campos Subject o To, deberías usar la clase Header y asignar el campo del objeto Message a una instancia de Header en vez de usar una cadena de caracteres para el valor de la cabecera. Importa la clase Header del módulo email.header. Por ejemplo:

>>> from email.message import Message
>>> from email.header import Header
>>> msg = Message()
>>> h = Header('p\xf6stal', 'iso-8859-1')
>>> msg['Subject'] = h
>>> msg.as_string()
'Subject: =?iso-8859-1?q?p=F6stal?=\n\n'

¿Has visto cómo hemos hecho que el campo Subject contuviera un caracter no ASCII? Lo hemos hecho creando una instancia de Header y pasándole el conjunto de caracteres en los que estaba codificado la cadena de bytes. Cuando la instancia de Message subsecuente se ha aplanado, el campo Subject se ha codificado en RFC 2047 [https://tools.ietf.org/html/rfc2047.html] adecuadamente. Los lectores de correo que soportan MIME deberían mostrar esta cabecera usando el caracter ISO-8859-1 incrustado.

Aquí está la descripción de la clase Header:

class email.header.Header(s=None, charset=None, maxlinelen=None, header_name=None, continuation_ws=' ', errors='strict')

Crea una cabecera conforme a las especificaciones MIME que contiene cadenas de caracteres en diferentes conjuntos de caracteres.

El argumento opcional s es el valor inicial de la cabecera. Si es None (el valor por defecto), el valor inicial de la cabecera quedará sin asignar. Puedes añadirlo luego a la cabecera con llamadas al método append(). s debe ser una instancia de bytes o str, pero lee la documentación de append() para conocer los detalles semánticos.

El argumento opcional charset sirve para dos propósitos: tiene el mismo significado que el argumento charset en el método append(). También asigna el conjunto de caracteres por defecto para todas las llamadas subsecuentes a append() que omitan el argumento charset. Si no se proporciona charset en el constructor (por defecto), el conjunto de caracteres us-ascii se usa tanto para el conjunto de caracteres inicial de s como por defecto para las llamadas subsecuentes a append().

La longitud de línea máxima puede especificarse explícitamente con maxlinelen. Para dividir la primera línea en un valor más corto (teniendo en cuenta los campos de la cabecera que no están incluidos en s, por ejemplo Subject), pasar el nombre del campo en header_name. El valor por defecto de maxlinelen es 76, y el valor por defecto de header_name es None, lo que quiere decir que no se tiene en cuenta para una cabecera larga dividida.

El argumento opcional continuation_ws debe ser conforme a las normas de espacios en blanco plegables de la RFC 2822 [https://tools.ietf.org/html/rfc2822.html], y normalmente es o un espacio o un caracter tabulador. Este caracter se antepondrá delante de las líneas continuadas. El valor por defecto de continuation_ws es un solo espacio.

El argumento opcional errors se pasa directamente a través del método append().

append(s, charset=None, errors='strict')

Añade la cadena de caracteres s a la cabecera MIME.

El argumento opcional charset, si se proporciona, debe ser una instancia de Charset (ver email.charset) o el nombre de un conjunto de datos, que deberá ser convertido a una instancia de Charset. Un valor de None (el valor por defecto) significa que se usará el charset dado en el constructor.

s puede ser una instancia de bytes o de str. Si es una instancia de bytes, entonces charset es la codificación de esa cadena de bytes, y se lanzará un UnicodeError si la cadena de caracteres no puede decodificarse con ese conjunto de caracteres.

Si s es una instancia de str, entonces charset es una sugerencia que especifica el conjunto de caracteres usando en la cadena de caracteres.

En cualquier caso, cuando se produce una cabecera conforme a la RFC 2822 [https://tools.ietf.org/html/rfc2822.html] usando las reglas de la RFC 2047 [https://tools.ietf.org/html/rfc2047.html], la cadena de caracteres se codificará usando el códec de salida del conjunto de caracteres. Si la cadena de caracteres no puede codificarse usando el códec de salida, se lanzará un UnicodeError.

El argumento opcional errors se pasa como el argumento de errores para la llamada de decodificación si s es una cadena de bits.

encode(splitchars=';, \t', maxlinelen=None, linesep='\n')

Codifica un mensaje de la cabecera en un formato conforme a RFC, posiblemente envolviendo las líneas largas y encapsulando las partes no ASCII en base64 o en codificaciones imprimibles entrecomilladas.

El argumento opcional splitchars es una cadena de caracteres que contiene caracteres a los que el algoritmo de separación debería asignar espacio extra durante la encapsulación de la cabecera normal. Esto da un basto soporte a los saltos sintácticos de alto nivel de la RFC 2822 [https://tools.ietf.org/html/rfc2822.html]: los puntos de separación precedidos por un caracter separador tienen preferencia durante la separación de la línea, con preferencia de caracteres en el orden en el que aparecen en la cadena de caracteres. El espacio y el tabulador pueden incluirse en la cadena de caracteres para indicar si se debería dar preferencia a uno sobre el otro como punto de separación cuando no aparezcan otros caracteres separadores en la línea que se está dividiendo. Los caracteres separadores no afectan a las líneas codificadas de la RFC 2047 [https://tools.ietf.org/html/rfc2047.html].

maxlinelen, si se proporciona, sobrescribe el valor de longitud de línea máxima para la instancia.

linesep especifica los caracteres usados para separar las líneas de la cabecera plegada. Su valor por defecto es el valor más útil para el código de una aplicación Python (\n), pero se puede especificar \r\n para producir cabeceras con separadores de línea conforme a RFCs.

Distinto en la versión 3.2: Argumento linesep añadido.

La clase Header también proporciona una serie de métodos para soportar operaciones estándar y funciones incorporadas.

__str__()

Retorna una aproximación de Header como una cadena de caracteres, usando una longitud de línea ilimitada. Todas las piezas se convierten a unicode utilizando la codificación especificada y unidas adecuadamente. Todas las piezas con un conjunto de caracteres 'unknown-8bit' se decodifican como ASCII usando el gestor de errores de 'replace'.

Distinto en la versión 3.2: Añadida gestión del conjunto de caracteres 'unknown-8bit'.

__eq__(other)

Este método permite comparar si dos instancias de Header son iguales.

__ne__(other)

Este método permite comparar si dos instancias de Header no son iguales.

El módulo email.header También proporciona las prácticas funciones que se indican a continuación.

email.header.decode_header(header)

Decodifica el valor de un mensaje de la cabecera sin convertir el conjunto de caracteres. El valor de la cabecera está en header.

Esta función retorna una lista de duplas (decoded_string, charset) que contiene cada una de las partes decodificadas de la cabecera. charset será None para las partes no codificadas de la cabecera, de lo contrario será una cadena de caracteres en minúscula con el nombre del conjunto de caracteres especificado en la cadena de caracteres codificada.

Aquí va un ejemplo:

>>> from email.header import decode_header
>>> decode_header('=?iso-8859-1?q?p=F6stal?=')
[(b'p\xf6stal', 'iso-8859-1')]

email.header.make_header(decoded_seq, maxlinelen=None, header_name=None, continuation_ws=' ')

Crea una instancia de Header a partir de una secuencia de duplas como las retornadas por decode_header().

decode_header() toma el valor de una cadena de caracteres de la cabecera y retorna una secuencia de duplas con el formato (decoded_string, charset), donde charset es el nombre del conjunto de caracteres.

Esta función toma una de esas secuencias de duplas y retorna una instancia de Header. Los argumentos opcionales maxlinelen, header_name y continuation_ws son como los del constructor Header.

email.charset: Representa conjunto de caracteres

Código fuente: Lib/email/charset.py [https://github.com/python/cpython/tree/3.9/Lib/email/charset.py]

Este módulo es parte de la API de email heredada (Compat32). En la nueva API solo se usa la tabla de alias.

El texto restante de esta sección corresponde a la documentación original del módulo.

Este módulo proporciona una clase Charset para representar conjuntos de caracteres y conversiones de conjuntos de caracteres en mensajes de correo electrónico, así como un registro de conjuntos de caracteres y varios métodos de conveniencia para manipular este registro. Las instancias de Charset se utilizan en varios otros módulos dentro del paquete email.

Importe esta clase desde el módulo email.charset.

class email.charset.Charset(input_charset=DEFAULT_CHARSET)

Asigna conjuntos de caracteres a sus propiedades de correo electrónico.

Esta clase proporciona información sobre los requisitos impuestos al correo electrónico para un conjunto de caracteres específico. También proporciona rutinas de conveniencia para convertir entre juegos de caracteres, dada la disponibilidad de los códecs aplicables. Dado un conjunto de caracteres, hará todo lo posible para proporcionar información sobre cómo utilizar ese conjunto de caracteres en un mensaje de correo electrónico de forma compatible con RFC.

Ciertos conjuntos de caracteres deben codificarse con quoted-printable o base64 cuando se usan en encabezados o cuerpos de correo electrónico. Ciertos conjuntos de caracteres deben convertirse directamente y no están permitidos en el correo electrónico.

Opcional input_charset es como se describe a continuación; siempre se convierte a minúsculas. Después de que el alias sea normalizado también se utiliza como una búsqueda en el registro de conjuntos de caracteres para averiguar la codificación del encabezado, codificación de cuerpo, y códec de conversión de salida que se usarán para el conjunto de caracteres. Por ejemplo, si input_charset es iso-8859-1, los encabezados y cuerpos se codificarán mediante quoted-printable y no es necesario ningún códec de conversión de salida. Si input_charset es euc-jp, los encabezados se codificarán con base64, los cuerpos no se codificarán, pero el texto de salida se convertirá del conjunto de caracteres euc-jp al conjunto de caracteres iso-2022-jp.

Las instancias Charset tienen los siguientes atributos de datos:

input_charset

El conjunto de caracteres inicial especificado. Los alias comunes se convierten a sus nombres de correo electrónico Official (por ejemplo, latin_1 se convierte a `` iso-8859-1``). El valor predeterminado es `` us-ascii “” de 7 bits.

header_encoding

If the character set must be encoded before it can be used in an email header, this attribute will be set to charset.QP (for quoted-printable), charset.BASE64 (for base64 encoding), or charset.SHORTEST for the shortest of QP or BASE64 encoding. Otherwise, it will be None.

body_encoding

Same as header_encoding, but describes the encoding for the mail message’s body, which indeed may be different than the header encoding. charset.SHORTEST is not allowed for body_encoding.

output_charset

Algunos conjuntos de caracteres deben ser convertidos antes de poder ser usados en cabeceras o cuerpos de correos. Si el input_charset es uno de ellos, este atributo contendrá el nombre del conjunto de caracteres al que será convertido. De lo contrario, será None.

input_codec

El nombre del códec de Python usado para convertir el input_charset a Unicode. Si no es necesario un códec de conversión, este atributo será None.

output_codec

El nombre del códec de Python usado para convertir Unicode a output_charset. Si no es necesario un códec de conversión, este atributo tendrá el mismo valor que input_codec.

Las instancias Charset además tienen los siguientes métodos:

get_body_encoding()

Retorna la codificación de transferencia de contenido usada para la codificación del cuerpo.

Esta es la cadena de caracteres quoted-printable o base64 dependiendo de la codificación usada, o es una función, en cuyo caso se deberá llamar a la función con un solo argumento, el objeto Mensaje a ser codificado. La función deberá luego establecer el encabezado Content-Transfer-Encoding en lo que sea apropiado.

Retorna la cadena quoted-printable si body_encoding es QP, retorna la cadena base64 si body_encoding es BASE64, y retorna la cadena 7bit en caso contrario.

get_output_charset()

Return the output character set.

Este es el atributo output_charset si no es None, en caso contrario es input_charset.

header_encode(string)

Codifica como encabezado la cadena de caracteres string.

El tipo de codificación (base64 o quoted-printable) se basará en el atributo header_encoding.

header_encode_lines(string, maxlengths)

Codifica como encabezado string convirtiéndolo primero a bytes.

Es similar a header_encode() excepto que la cadena se ajusta a las longitudes máximas indicadas en el argumento maxlengths, el cual debe ser un iterador: cada elemento retornado por este iterador proporcionará la siguiente longitud máxima de línea.

body_encode(string)

Codifica como Cuerpo la cadena string.

El tipo de codificación (base64 o quoted-printable) se basará en el atributo body_encoding.

La clase Charset también proporciona una serie de métodos para soportar operaciones estándar y funciones integradas.

__str__()

Retorna input_charset como una cadena de caracteres convertida a minúsculas. __repr__() es un alias para __str__().

__eq__(other)

Este método le permite comparar dos instancias Charset por igualdad.

__ne__(other)

Este método le permite comparar dos instancias Charset por desigualdad.

El módulo email.charset provee además las siguientes funciones para agregar nuevas entradas al conjunto global de caracteres, alias y registros de códecs:

email.charset.add_charset(charset, header_enc=None, body_enc=None, output_charset=None)

Añade propiedades de carácter al registro global.

charset es el conjunto de caracteres de entrada, y debe ser el nombre canónico del conjunto de caracteres.

Optional header_enc and body_enc is either charset.QP for quoted-printable, charset.BASE64 for base64 encoding, charset.SHORTEST for the shortest of quoted-printable or base64 encoding, or None for no encoding. SHORTEST is only valid for header_enc. The default is None for no encoding.

Opcional output_charset es es el conjunto de caracteres en el que debe estar la salida. Las conversiones proceden del conjunto de caracteres de entrada, a Unicode, al conjunto de caracteres de salida cuando se llama al método Charset.convert(). El valor predeterminado es la salida en el mismo conjunto de caracteres que la entrada.

Tanto input_charset y output_charset deben tener entradas de códec Unicode en el conjunto de caracteres del módulo para la asignación del códec; use add_codec() para agregar códecs que el módulo no conozca. Consulte la documentación del módulo codecs para más información.

El registro global de conjuntos de caracteres se mantiene en el módulo global diccionario CHARSETS.

email.charset.add_alias(alias, canonical)

Añade un alias al conjunto de caracteres. alias es el nombre del alias, p. ej. latin-1`. canonical es el nombre canónico del conjunto de caracteres, p. ej. iso-8859-1.

El registro de alias global de conjuntos de caracteres se mantiene en el módulo global diccionario ALIASES.

email.charset.add_codec(charset, codecname)

Añade un códec que asigna caracteres en el conjunto de caracteres dado hacia y desde Unicode.

charset es el nombre canónico de un conjunto de caracteres. codename es el nombre de un códec de Python, según corresponda para el segundo argumento del método str de encode().

email.encoders: Codificadores

Código fuente: Lib/email/encoders.py [https://github.com/python/cpython/tree/3.9/Lib/email/encoders.py]

Este módulo forma parte de la anterior API de correo electrónico (Compat32). En la nueva API, la funcionalidad la proporciona el parámetro cte del método set_content().

Este módulo está obsoleto en Python 3. Las funciones que aparecen aquí no deberían ser llamadas explícitamente ya que la clase MIMEText establece el tipo de contenido y el encabezado CTE utilizando los valores del _subtype y del _charset que se pasan cuando se instancia esa clase.

El texto que viene a continuación corresponde a la documentación original del módulo.

Cuando se crean objetos Message desde 0, a menudo se necesita codificar el contenido del mensaje para transportarlo a través de servidores de correo electrónico adecuados. Esto es así especialmente para el tipo de mensajes image/* y text/* que contienen datos binarios.

El paquete email proporciona algunos codificadores adecuados en su módulo encoders. Estos codificadores son en realidad utilizados por los constructores de las clases MIMEAudio y MIMEImage para proporcionar codificadores por defecto. Todas las funciones de codificación tienen exactamente un argumento, el mensaje a codificar Normalmente extraen el contenido, lo codifican y borran el contenido para introducir el nuevo contenido codificado. También deberían marcar el encabezado Content-Transfer-Encoding como apropiado.

Ten en cuenta que estas funciones no sirven para un mensaje con múltiples partes. En lugar de aplicarlo al mensaje completo, las funciones deben aplicarse a cada subparte individual. Si se pasa un mensaje de múltiples partes como argumento se activara un mensaje de error TypeError.

A continuación, una lista de las funciones de codificación facilitadas:

email.encoders.encode_quopri(msg)

Codifica el contenido en formularios entrecomillados e imprimibles y marca el encabezado Content-Transfer-Encoding como quoted-printable 1. Es un buen codificador para usar cuando la mayoría del contenido son datos imprimibles normales pero hay algún dato que no es imprimible.

email.encoders.encode_base64(msg)

Codifica el contenido en un formulario base64 y marca el encabezado Content-Transfer-Encoding como base64. Esta codificación es buena cuando la mayoría del contenido son datos no imprimibles ya que es un formulario más compacto que formularios entrecomillados e imprimibles. La desventaja es que incluye el texto que no es leíble por los humanos.

email.encoders.encode_7or8bit(msg)

Esto, en realidad, no modifica el contenido del mensaje, pero fija el encabezado Content-Transfer-Encoding a 7bit u 8bit, lo que considere más adecuado en función del contenido del mensaje.

email.encoders.encode_noop(msg)

Esto no hace nada; ni siquiera fija el encabezado Content-Transfer-Encoding.

Notas

1

El codificado con encode_quopri() también codifica todas las tabulaciones y caracteres de espacios en los datos.

email.utils: Utilidades misceláneas

Código fuente: Lib/email/utils.py [https://github.com/python/cpython/tree/3.9/Lib/email/utils.py]

Existen varias funciones útiles proporcionadas en el módulo email.utils:

email.utils.localtime(dt=None)

Retorna el tiempo local como un objecto datetime consciente. Si se llama sin argumentos, retorna el tiempo actual. De lo contrario, el argumento dt debe ser una instancia datetime, y es convertida a la zona horaria local de acuerdo a la base de datos de zonas horarias del sistema. Si dt es naíf (naif, es decir, dt.tzinfo es None), se asume que está en tiempo local. En este caso, un valor positivo o cero para isdst hace que localtime asuma inicialmente que el horario de verano está o no (respectivamente) en efecto para el tiempo especificado. Un valor negativo para isdst hace que el localtime intente determinar si el horario de verano está en efecto para el tiempo especificado.

Nuevo en la versión 3.3.

email.utils.make_msgid(idstring=None, domain=None)

Retorna una cadena de caracteres apropiada para una cabecera Message-ID que cumpla con RFC 2822 [https://tools.ietf.org/html/rfc2822.html]. Si se especifica un idstring opcional, es una cadena de caracteres utilizada para reforzar la unicidad del identificador del mensaje. Si se especifica un domain opcional provee la porción del msgid después de “@”. El predeterminado es el hostname local. Normalmente no es necesario especificar este valor, pero puede ser útil en algunos casos, como cuando se está construyendo un sistema distribuido que utiliza un nombre de dominio consistente a lo largo de varios ordenadores.

Distinto en la versión 3.2: Se añadió la palabra clave domain.

Las funciones que quedan son parte de la API de correo electrónico heredada (Compat32) . No hay necesidad de utilizarlas directamente con el nuevo API, dado que el análisis sintáctico y formateo que proporcionan es realizado automáticamente por el mecanismo de análisis sintáctico de la nueva API.

email.utils.quote(str)

Retorna una nueva cadena de caracteres con barras invertidas (\) en str reemplazado por dos barras invertidas, y comillas dobles reemplazadas por barra invertida seguido de comillas dobles.

email.utils.unquote(str)

Retorna una nueva cadena de caracteres que es una versión unquoted de str. Si str comienza y termina con comillas dobles, éstas son eliminadas. De igual manera si str empieza y termina con comillas angulares (< y >), éstas son eliminadas.

email.utils.parseaddr(address)

Interpreta address – la cual debe ser el valor de un campo que contenga un campo tal como To o Cc – para separarlo en sus componentes realname y email address. Retorna una tupla de información, a menos que la interpretación falle, en cuyo caso una 2-tupla de ('','') es retornada.

email.utils.formataddr(pair, charset='utf-8')

El inverso de parseaddr(), este toma una 2-tupla de la forma (realname,real, email_address) y retorna una cadena de caracteres válido para una cabecera To o Cc. Si el primer elemento de pair es falso, entonces el segundo elemento es retornado sin modificación.

El charset opcional es el conjunto de caracteres que será usado en la codificación RFC 2047 [https://tools.ietf.org/html/rfc2047.html] del real_name si el real_name contiene caracteres que no sean ASCII. Puede ser una instancia de str o Charset. El valor predeterminado es utf-8.

Distinto en la versión 3.3: Se añadió la opción charset.

email.utils.getaddresses(fieldvalues)

Este método retorna una lista de 2-tuplas de la forma retornada por parseaddr(). fieldvalues es una secuencia de valores de campos de cabecera como la que puede ser retornado por Message.get_all. Aquí hay un ejemplo sencillo que obtiene todos los destinatarios de un mensaje:

from email.utils import getaddresses

tos = msg.get_all('to', [])
ccs = msg.get_all('cc', [])
resent_tos = msg.get_all('resent-to', [])
resent_ccs = msg.get_all('resent-cc', [])
all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)

email.utils.parsedate(date)

Intenta interpretar una fecha de acuerdo a las reglas en RFC 2822 [https://tools.ietf.org/html/rfc2822.html]. Sin embargo, algunos clientes de correo no siguen ese formato como está especificado, por lo cual parsedate() intenta adivinar correctamente en esos casos. date es una secuencia de caracteres que contiene una fecha RFC 2822 [https://tools.ietf.org/html/rfc2822.html] como "Mon, 20 Nov 1995 19:12:08 -0500". Si tiene éxito en interpretar la fecha, parsedate() retorna una 9-tupla que puede ser pasada directamente a time.mktime(); de lo contrario None es retornado. Observar que los índices 6,7 y 8 de la tupla resultante no son utilizables.

email.utils.parsedate_tz(date)

Realiza la misma función que parsedate(), pero retorna None o una 10-tupla; los primeros 9 elementos forman una tupla que puede ser pasada directamente a time.mktime(), y el décimo es el desfase de la zona horaria de la fecha con respecto a UTC (que es el término oficial para Greenwich Mean Time) 1. Si la cadena de caracteres de entrada no tiene zona horaria, el último elemento de la tupla retornada es 0, el cual representa UTC. Nótese que los índices 6, 7 y 8 de la tupla resultante no son utilizables.

email.utils.parsedate_to_datetime(date)

El inverso de format_datetime(). Realiza la misma función que parsedate(), pero al tener éxito retorna un datetime. Si la fecha de entrada tiene una zona horaria de -0000, el datetime será un datetime naíf, y si la fecha cumple con los RFCs representará un tiempo en UTC pero sin indicación de la zona horaria originaria actual del mensaje de donde proviene la fecha. Si la fecha de entrada tiene cualquier otro desfase de zona horaria válida, el datetime será un datetime consiente con el correspondiente timezone tzinfo.

Nuevo en la versión 3.3.

email.utils.mktime_tz(tuple)

Cambia una 10-tupla, como la retornada por parsedate_tz() a una marca de tiempo UTC (segundos desde la Época). Si la zona horaria en la tupla es None, asume el tiempo local.

email.utils.formatdate(timeval=None, localtime=False, usegmt=False)

Retorna una fecha como una cadena de caracteres de acuerdo a RFC 2822 [https://tools.ietf.org/html/rfc2822.html], por ejemplo:

Fri, 09 Nov 2001 01:08:47 -0000

timeval opcional, es un valor de tiempo de punto flotante como el aceptado por time.gmtime() y time.localtime(). Si no es dado, el tiempo actual es usado.

localtime opcional, es una bandera que cuando es True, interpreta timeval y retorna una fecha relativa a la zona horaria local en lugar de UTC, tomando apropiadamente en cuenta el horario de verano. El valor predeterminado es False con lo cual UTC es utilizado.

usegmt opcional, es una bandera que cuando es True retorna una fecha como cadena de caracteres con la zona horaria como una cadena de caracteres ascii GMT, en lugar de un numérico -0000. Esto es necesario para algunos protocolos (como HTTP). Sólo aplica cuando localtime es False. El valor predeterminado es False.

email.utils.format_datetime(dt, usegmt=False)

Similar a formatdate, pero la entrada es una instancia datetime. Si es un datetime naíf, se asume ser «UTC sin información sobre la zona horaria de origen», y el -0000 convencional es usado para la zona horaria. Si es un datetime consciente entonces el desfase numérico de la zona horaria es utilizado. Si es una zona horaria consciente con un desfase cero, entonces usegmt puede ser True, en cuyo caso la cadena de caracteres GMT es utilizada en lugar del desfase numérico de zona horaria. Esto provee una manera de generar cabeceras de fecha HTTP conforme estándares.

Nuevo en la versión 3.3.

email.utils.decode_rfc2231(s)

Decodifica la cadena de caracteres s de acuerdo a RFC 2231 [https://tools.ietf.org/html/rfc2231.html].

email.utils.encode_rfc2231(s, charset=None, language=None)

Codifica la cadena de caracteres s de acuerdo a RFC 2231 [https://tools.ietf.org/html/rfc2231.html]. charset y language opcionales, si son dados es el conjunto de caracteres y nombre del lenguaje a utilizar. Si ninguno es dado, s es retornado sin modificar. Si charset es dado pero language no, la cadena de caracteres es codificada usando la cadena de caracteres vacía para language.

email.utils.collapse_rfc2231_value(value, errors='replace', fallback_charset='us-ascii')

Cuando un parámetro de cabecera está codificado en formato RFC 2231 [https://tools.ietf.org/html/rfc2231.html], Message.get_param puede retornar una 3-tupla conteniendo el conjunto de caracteres, lenguaje y valor. collapse_rfc2231_value() convierte esto en una cadena de caracteres unicode. El parámetro opcional errors es pasado al argumento errors del método encode() de str; de manera predeterminada recae en 'replace'. fallback_charset opcional, especifica el conjunto de caracteres a utilizar si el especificado en la cabecera RFC 2231 [https://tools.ietf.org/html/rfc2231.html] no es conocido por Python; su valor predeterminado es 'us-ascii'.

Por conveniencia, si el value pasado a collapse_rfc2231_value() no es una tupla, debería ser una cadena de caracteres y se retorna sin citar.

email.utils.decode_params(params)

Decodifica la lista de parámetros de acuerdo a RFC 2231 [https://tools.ietf.org/html/rfc2231.html]. params es una secuencia de 2-tuplas conteniendo elementos de la forma (content-type, string-value).

Notas a pie de página

1

Nótese que el signo del desfase de la zona horaria es opuesto al signo de la variable time.timezone para la misma zona horaria; este último sigue el estándar POSIX mientras que este módulo sigue RFC 2822 [https://tools.ietf.org/html/rfc2822.html].

email.iterators: Iteradores

Código fuente: Lib/email/iterators.py [https://github.com/python/cpython/tree/3.9/Lib/email/iterators.py]

Iterar sobre un árbol de objetos mensaje es bastante fácil con el método Message.walk. El módulo email.iterators proporciona algunos iteradores útiles de más alto nivel sobre árboles de objetos mensaje.

email.iterators.body_line_iterator(msg, decode=False)

Itera sobre todas las cargas útiles de todas las subpartes de msg, retornando las cargas útiles en cadenas de caracteres línea por línea. Descarta todas las cabeceras de las subpartes, y descarta cualquier subparte con una carga útil que no sea una cadena de caracteres de Python. Esto de alguna forma es equivalente a leer la representación en texto plano del mensaje desde un fichero usando readline(), descartando todas las cabeceras intermedias.

El argumento opcional decode se pasa a través de Message.get_payload.

email.iterators.typed_subpart_iterator(msg, maintype='text', subtype=None)

Itera sobre todas las subpartes de msg, retornando solo las subpartes que coincidan el tipo MIME especificado por maintype y subtype.

Note que subtype es opcional; si se omite, entonces se comprobará si el tipo MIME de las subpartes coincide con el tipo principal solamente. maintype es opcional también; su valor por defecto es text.

Por tanto, por defecto typed_subpart_iterator() retorna cada parte que tenga un tipo MIME text/*.

La siguiente función se ha añadido como una útil herramienta de depuración. No debe ser considerada parte de la interfaz pública soportada para este paquete.

email.iterators._structure(msg, fp=None, level=0, include_default=False)

Imprime una representación con sangrías de los tipos del contenido de la estructura de objetos mensaje. Por ejemplo:

>>> msg = email.message_from_file(somefile)
>>> _structure(msg)
multipart/mixed
    text/plain
    text/plain
    multipart/digest
        message/rfc822
            text/plain
        message/rfc822
            text/plain
        message/rfc822
            text/plain
        message/rfc822
            text/plain
        message/rfc822
            text/plain
    text/plain

El argumento opcional fp es un objeto similar a un fichero en el que imprimir la salida. Debe ser adecuado para la función de Python print(). Se usa level internamente. include_default, si tiene su valor a verdadero, imprime el tipo por defecto también.

json — Codificador y decodificador JSON

Código fuente: Lib/json/__init__.py [https://github.com/python/cpython/tree/3.9/Lib/json/__init__.py]

JSON (JavaScript Object Notation) [https://json.org], specified by RFC 7159 [https://tools.ietf.org/html/rfc7159.html] (which obsoletes RFC 4627 [https://tools.ietf.org/html/rfc4627.html]) and by ECMA-404 [https://www.ecma-international.org/publications-and-standards/standards/ecma-404/], is a lightweight data interchange format inspired by JavaScript [https://en.wikipedia.org/wiki/JavaScript] object literal syntax (although it is not a strict subset of JavaScript 1 ).

Advertencia

Be cautious when parsing JSON data from untrusted sources. A malicious JSON string may cause the decoder to consume considerable CPU and memory resources. Limiting the size of data to be parsed is recommended.

json expone una API familiar a los usuarios de los módulos de la biblioteca estándar marshal y pickle.

Codificación de jerarquías básicas de objetos de Python:

>>> import json
>>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}])
'["foo", {"bar": ["baz", null, 1.0, 2]}]'
>>> print(json.dumps("\"foo\bar"))
"\"foo\bar"
>>> print(json.dumps('\u1234'))
"\u1234"
>>> print(json.dumps('\\'))
"\\"
>>> print(json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True))
{"a": 0, "b": 0, "c": 0}
>>> from io import StringIO
>>> io = StringIO()
>>> json.dump(['streaming API'], io)
>>> io.getvalue()
'["streaming API"]'

Codificación compacta:

>>> import json
>>> json.dumps([1, 2, 3, {'4': 5, '6': 7}], separators=(',', ':'))
'[1,2,3,{"4":5,"6":7}]'

Impresión linda:

>>> import json
>>> print(json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4))
{
    "4": 5,
    "6": 7
}

Decodificación JSON:

>>> import json
>>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]')
['foo', {'bar': ['baz', None, 1.0, 2]}]
>>> json.loads('"\\"foo\\bar"')
'"foo\x08ar'
>>> from io import StringIO
>>> io = StringIO('["streaming API"]')
>>> json.load(io)
['streaming API']

Decodificación personalizada de objetos JSON:

>>> import json
>>> def as_complex(dct):
...     if '__complex__' in dct:
...         return complex(dct['real'], dct['imag'])
...     return dct
...
>>> json.loads('{"__complex__": true, "real": 1, "imag": 2}',
...     object_hook=as_complex)
(1+2j)
>>> import decimal
>>> json.loads('1.1', parse_float=decimal.Decimal)
Decimal('1.1')

Extendiendo JSONEncoder:

>>> import json
>>> class ComplexEncoder(json.JSONEncoder):
...     def default(self, obj):
...         if isinstance(obj, complex):
...             return [obj.real, obj.imag]
...         # Let the base class default method raise the TypeError
...         return json.JSONEncoder.default(self, obj)
...
>>> json.dumps(2 + 1j, cls=ComplexEncoder)
'[2.0, 1.0]'
>>> ComplexEncoder().encode(2 + 1j)
'[2.0, 1.0]'
>>> list(ComplexEncoder().iterencode(2 + 1j))
['[2.0', ', 1.0', ']']

Usando json.tool desde el shell para validación e impresión con sangría:

$ echo '{"json":"obj"}' | python -m json.tool
{
    "json": "obj"
}
$ echo '{1.2:3.4}' | python -m json.tool
Expecting property name enclosed in double quotes: line 1 column 2 (char 1)

Consulte Interfaz de línea de comandos para obtener documentación detallada.

Nota

JSON es un subconjunto de YAML [http://yaml.org/] 1.2. El JSON producido por la configuración predeterminada de este módulo (en particular, el valor predeterminado separators) también es un subconjunto de YAML 1.0 y 1.1. Por lo tanto, este módulo también se puede utilizar como un serializador YAML.

Nota

Los codificadores y decodificadores de este módulo conservan el orden de entrada y salida de forma predeterminada. El orden solo se pierde si los contenedores subyacentes no están ordenados.

Uso básico

json.dump(obj, fp, *, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, default=None, sort_keys=False, **kw)

Serializa obj como una secuencia con formato JSON a fp (una invocación .write()- que soporta file-like object) usando esto conversion table.

Si skipkeys es verdadero (predeterminado: False), entonces las llaves del dict que no son de un tipo básico (str, int, float, bool, None) se omitirán en lugar de generar un TypeError.

El módulo json siempre produce objetos str, no objetos bytes. Por lo tanto, fp.write() debe admitir str como entrada.

Si ensure_ascii es verdadero (el valor predeterminado), se garantiza que la salida tendrá todos los caracteres entrantes no ASCII escapados. Si ensure_ascii es falso, estos caracteres se mostrarán tal cual.

If check_circular is false (default: True), then the circular reference check for container types will be skipped and a circular reference will result in an RecursionError (or worse).

Si allow_nan es falso (predeterminado: True), entonces serializar los valores fuera de rango float (nan, inf` `, ``-inf) provocará un ValueError en estricto cumplimiento de la especificación JSON. Si allow_nan es verdadero, se utilizarán sus equivalentes de JavaScript (NaN, Infinity, -Infinity).

Si indent es un entero no negativo o una cadena, los elementos del arreglo JSON y los miembros del objeto se imprimirán con ese nivel de sangría. Un nivel de sangría de 0, negativo o "" solo insertará nuevas líneas. None (el valor predeterminado) selecciona la representación más compacta. El uso de una sangría de entero positivo agrega sangrías de muchos espacios por nivel. Si indent es una cadena (como "\t"), esa cadena se usa para agregarle sangría a cada nivel.

Distinto en la versión 3.2: Permite cadenas de caracteres para indent además de enteros.

Si se especifica, separators debe ser una tupla (separador_elemento, separador_llave). El valor predeterminado es (', ', ': ') si indent es None y (', ', ': ') de lo contrario. Para obtener la representación JSON más compacta, debe especificar (', ', ': ') para eliminar espacios en blanco.

Distinto en la versión 3.4: Usa (',', ': ') como predeterminado si indent no es None.

Si se especifica, default debería ser una función que se llama para objetos que de otro modo no se pueden serializar. Debería retornar una versión codificable JSON del objeto o generar un TypeError. Si no se especifica, produce TypeError.

Si sort_keys es verdadero (predeterminado: False), la salida de los diccionarios se ordenará por llave.

Para usar una subclase personalizada de JSONEncoder (por ejemplo, una que sobre escriba el método default() para serializar tipos adicionales), se especifica mediante el argumento por palabra clave cls; de lo contrario se usa JSONEncoder.

Distinto en la versión 3.6: Todos los parámetros opcionales son ahora palabra-clave-solamente.

Nota

A diferencia de pickle y marshal, JSON no es un protocolo enmarcado, por lo que intentar serializar varios objetos con llamadas repetidas a dump() utilizando el mismo fp dará como resultado un archivo JSON no válido.

json.dumps(obj, *, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, default=None, sort_keys=False, **kw)

Serializa obj en un str con formato JSON usando esta conversion table. Los argumentos tienen el mismo significado que en dump().

Nota

Las llaves de los pares llave/valor de JSON siempre son del tipo str. Cuando un diccionario se convierte en JSON, todas las llaves del diccionario se convierten en cadenas. Como resultado de esto, si un diccionario se convierte en JSON y, a continuación, se convierte nuevamente en un diccionario, el diccionario puede que no sea igual al original. Es decir, loads(dumps(x)) != x si x tiene llaves que no son de tipo cadena de caracteres.

json.load(fp, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)

Deserializa fp (un text file o binary file que soporte .read() y que contiene un documento JSON) a un objeto Python usando esta conversion table.

object_hook es una función opcional a la que se llamará con el resultado de cualquier literal de objeto decodificado (un dict). El valor de retorno de object_hook se utilizará en lugar de dict. Esta característica se puede utilizar para implementar decodificadores personalizados (por ejemplo, la sugerencia de clase JSON-RPC [http://www.jsonrpc.org]).

object_pairs_hook es una función opcional a la que se llamará con el resultado de cualquier literal de objeto decodificado con una lista ordenada de pares. El valor de retorno de object_pairs_hook se utilizará en lugar de dict. Esta característica se puede utilizar para implementar decodificadores personalizados. Si también se define object_hook, el object_pairs_hook tiene prioridad.

Distinto en la versión 3.1: Soporte agregado para object_pairs_hook.

parse_float, si se especifica, se llamará con la cadena de cada flotante JSON que se va a decodificar. De forma predeterminada, esto es equivalente a float(num_str). Esto se puede utilizar para hacer uso de otro tipo de datos o analizador para flotantes JSON (por ejemplo decimal. Decimal).

parse_int, si se especifica, se llamará con la cadena de cada entero JSON que se va a decodificar. De forma predeterminada, esto es equivalente a int(num_str). Esto se puede utilizar para hace uso de otro tipo de datos o analizador para enteros JSON (por ejemplo float).

Distinto en la versión 3.9.14: The default parse_int of int() now limits the maximum length of the integer string via the interpreter’s integer string conversion length limitation to help avoid denial of service attacks.

parse_constant, si se especifica, se llamará con una de las siguientes cadenas: '-Infinity', 'Infinity', 'NaN'. Esto se puede utilizar para generar una excepción si se encuentran números JSON inválidos.

Distinto en la versión 3.1: parse_constant ya no es llamado en “null”, “true”, “false”.

Para utilizar una subclase personalizada de JSONDecoder, especificarlo con el argumento por llave cls; de lo contrario, se utilizará JSONDecoder. Se pasarán argumentos adicionales de palabra llave al constructor de la clase.

Si los datos que se deserializan no constituyen un documento JSON válido, se generará un JSONDecodeError.

Distinto en la versión 3.6: Todos los parámetros opcionales son ahora palabra-clave-solamente.

Distinto en la versión 3.6: fp ahora puede ser un binary file. La codificación de entrada debe ser UTF-8, UTF-16 o UTF-32.

json.loads(s, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)

Deserializa s (una instancia str, bytes o bytearray que contiene un documento JSON) en un objeto Python mediante esta conversion table.

Los otros argumentos tienen el mismo significado que en load().

Si los datos que se deserializan no constituyen un documento JSON válido, se generará un JSONDecodeError.

Distinto en la versión 3.6: s ahora puede ser de tipo bytes o bytearray. La codificación de entrada debe ser UTF-8, UTF-16 o UTF-32.

Distinto en la versión 3.9: El argumento de palabra llave encoding ha sido removido.

Codificadores y Decodificadores

class json.JSONDecoder(*, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, strict=True, object_pairs_hook=None)

Decodificador JSON simple.

Realiza las siguientes traducciones en la decodificación de forma predeterminada:

JSON

Python

object

dict

array

list

string

str

número (int)

int

número (real)

float

true

True

false

False

null

None

También entiende NaN, Infinity y -Infinity como sus correspondientes valores float, que está fuera de la especificación JSON.

object_hook, si se especifica, se llamará con el resultado de cada objeto JSON decodificado y su valor de retorno se utilizará en lugar de la dict dada. Esto se puede usar para proporcionar deserializaciones personalizadas (por ejemplo, para admitir sugerencias de clases JSON-RPC [http://www.jsonrpc.org]).

object_pairs_hook, si se especifica se llamará con el resultado de cada objeto JSON decodificado con una lista ordenada de pares. El valor de retorno de object_pairs_hook se utilizará en lugar de dict. Esta característica se puede utilizar para implementar decodificadores personalizados. Si también se define object_hook, el object_pairs_hook tiene prioridad.

Distinto en la versión 3.1: Soporte agregado para object_pairs_hook.

parse_float, si se especifica, se llamará con la cadena de cada flotante JSON que se va a decodificar. De forma predeterminada, esto es equivalente a float(num_str). Esto se puede utilizar para hacer uso de otro tipo de datos o analizador para flotantes JSON (por ejemplo decimal. Decimal).

parse_int, si se especifica, se llamará con la cadena de cada entero JSON que se va a decodificar. De forma predeterminada, esto es equivalente a int(num_str). Esto se puede utilizar para hace uso de otro tipo de datos o analizador para enteros JSON (por ejemplo float).

parse_constant, si se especifica, se llamará con una de las siguientes cadenas: '-Infinity', 'Infinity', 'NaN'. Esto se puede utilizar para generar una excepción si se encuentran números JSON inválidos.

Si strict es falso (“”True”” es el valor predeterminado), se permitirán caracteres de control dentro de cadenas. Los caracteres de control en este contexto son aquellos con códigos de caracteres en el rango 0–31, incluyendo '\t' (tab), '\n', '\r' and '\0'.

Si los datos que se deserializan no constituyen un documento JSON válido, se generará un JSONDecodeError.

Distinto en la versión 3.6: Todos los parámetros son ahora palabra-clave-solamente.

decode(s)

Retorna la representación Python de s (una instancia str que contiene un documento JSON).

JSONDecodeError se producirá si el documento JSON entregado es invalido.

raw_decode(s)

Decodifica un documento JSON de s (un str comenzando con un documento JSON) y retorna una tupla de 2 de la representación Python y el índice en s donde terminó el documento.

Esto se puede usar para decodificar un documento JSON de una cadena de caracteres que puede tener datos extraños al final.

class json.JSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Codificador JSON extensible para estructuras de datos de Python.

Admite los siguientes objetos y tipos de forma predeterminada:

Python

JSON

dict

object

list, tuple

array

str

string

int, float, Enums derivadas de int o float

number

True

true

False

false

None

null

Distinto en la versión 3.4: Compatibilidad añadida con las clases Enum derivadas de int y float.

A fin de extender esto para reconocer otros objetos, implementar una subclase con un método default() con otro método que retorna un objeto serializable para “”o”” si es posible, de lo contrario debe llamar a la implementación de superclase (para elevar TypeError).

Si skipkeys es falso (lo es por defecto), un TypeError será lanzado cuando se trate de codificar llaves que no sean str, int, float o None. Si skipkeys es verdadero, tales elementos son simplemente pasados por alto.

Si ensure_ascii es verdadero (el valor predeterminado), se garantiza que la salida tendrá todos los caracteres entrantes no ASCII escapados. Si ensure_ascii es falso, estos caracteres se mostrarán tal cual.

If check_circular is true (the default), then lists, dicts, and custom encoded objects will be checked for circular references during encoding to prevent an infinite recursion (which would cause an RecursionError). Otherwise, no such check takes place.

Si allow_nan es cierto (valor predeterminado), NaN, Infinity y -Infinity se codificarán como tales. Este comportamiento no es compatible con las especificaciones JSON, pero es coherente con la mayoría de los codificadores y decodificadores basados en JavaScript. De lo contrario, codificar dichos puntos flotantes provocará un ValueError.

Si sort_keys es cierto (predeterminado: False), la salida de los diccionarios se ordenará por clave; esto es útil para las pruebas de regresión para garantizar que las serializaciones JSON se pueden comparar en el día a día.

Si indent es un entero no negativo o una cadena, los elementos del arreglo JSON y los miembros del objeto se imprimirán con ese nivel de sangría. Un nivel de sangría de 0, negativo o "" solo insertará nuevas líneas. None (el valor predeterminado) selecciona la representación más compacta. El uso de una sangría de entero positivo agrega sangrías de muchos espacios por nivel. Si indent es una cadena (como "\t"), esa cadena se usa para agregarle sangría a cada nivel.

Distinto en la versión 3.2: Permite cadenas de caracteres para indent además de enteros.

Si se especifica, separators debe ser una tupla (separador_elemento, separador_llave). El valor predeterminado es (', ', ': ') si indent es None y (', ', ': ') de lo contrario. Para obtener la representación JSON más compacta, debe especificar (', ', ': ') para eliminar espacios en blanco.

Distinto en la versión 3.4: Usa (',', ': ') como predeterminado si indent no es None.

Si se especifica, default debería ser una función que se llama para objetos que de otro modo no se pueden serializar. Debería retornar una versión codificable JSON del objeto o generar un TypeError. Si no se especifica, produce TypeError.

Distinto en la versión 3.6: Todos los parámetros son ahora palabra-clave-solamente.

default(o)

Implemente este método en una subclase de modo que retorne un objeto serializable para o, o llame a la implementación base (para generar un TypeError).

Por ejemplo, para admitir iteradores arbitrarios, podría implementar default() de esta manera:

def default(self, o):
   try:
       iterable = iter(o)
   except TypeError:
       pass
   else:
       return list(iterable)
   # Let the base class default method raise the TypeError
   return json.JSONEncoder.default(self, o)

encode(o)

Retorna una representación de cadena de caracteres JSON de una estructura de datos de Python, o. Por ejemplo:

>>> json.JSONEncoder().encode({"foo": ["bar", "baz"]})
'{"foo": ["bar", "baz"]}'

iterencode(o)

Codifica el objeto dado, o, y produce cada representación de cadena como disponible. Por ejemplo:

for chunk in json.JSONEncoder().iterencode(bigobject):
    mysocket.write(chunk)

Excepciones

exception json.JSONDecodeError(msg, doc, pos)

Subclase de ValueError con los siguientes atributos adicionales:

msg

El mensaje de error sin formato.

doc

El documento JSON que se está analizando.

pos

El índice de inicio de doc donde se produjo un error en el análisis.

lineno

La línea correspondiente a pos.

colno

La columna correspondiente a pos.

Nuevo en la versión 3.5.

Cumplimiento e interoperabilidad estándar

The JSON format is specified by RFC 7159 [https://tools.ietf.org/html/rfc7159.html] and by ECMA-404 [https://www.ecma-international.org/publications-and-standards/standards/ecma-404/]. This section details this module’s level of compliance with the RFC. For simplicity, JSONEncoder and JSONDecoder subclasses, and parameters other than those explicitly mentioned, are not considered.

Este módulo no cumple con la RFC de forma estricta, implementando algunas extensiones que son válidas en JavaScript pero no son válidas en JSON. En particular:

Se aceptan y se envían valores de números Infinitos y NaN;

Se aceptan nombres repetidos dentro de un objeto y solo se utiliza el valor del último par nombre-valor.

Puesto que el RFC permite a los analizadores compatibles con RFC aceptar textos de entrada que no son compatibles con RFC, el deserializador de este módulo es técnicamente compatible con RFC bajo la configuración predeterminada.

Codificaciones de caracteres

La RFC requiere que JSON se represente mediante UTF-8, UTF-16 o UTF-32, siendo UTF-8 el valor predeterminado recomendado para la máxima interoperabilidad.

Según lo permitido, aunque no es necesario, por la RFC, el serializador de este módulo establece ensure_ascii=True de forma predeterminada, escapando así el dato de salida para que las cadenas resultantes solo contengan caracteres ASCII.

Aparte del parámetro ensure_ascii, este módulo se define estrictamente en términos de conversión entre objetos Python y Unicode strings, y por lo tanto no aborda directamente el problema de las codificaciones de caracteres.

La RFC prohíbe agregar una marca de orden byte (BOM, por sus siglas en inglés) al inicio de un texto JSON y el serializador de este módulo no agrega una BOM a su salida. La RFC permite, pero no requiere, deserializadores JSON para omitir una BOM inicial en su entrada. El deserializador de este módulo genera un ValueError cuando hay una lista de materiales inicial.

La RFC no prohíbe explícitamente las cadenas JSON que contienen secuencias de bytes que no corresponden a caracteres Unicode válidos (por ejemplo, sustitutos UTF-16 no espaciados), pero sí tiene en cuenta que pueden causar problemas de interoperabilidad. De forma predeterminada, este módulo acepta y genera puntos de código (cuando está presente en el original str) para dichas secuencias.

Valores de número infinito y NaN

El RFC no permite la representación de los valores de número infinito o NaN. A pesar de eso, de forma predeterminada, este módulo acepta y genera Infinity, -Infinity y NaN como si fueran valores literales de número JSON válidos:

>>> # Neither of these calls raises an exception, but the results are not valid JSON
>>> json.dumps(float('-inf'))
'-Infinity'
>>> json.dumps(float('nan'))
'NaN'
>>> # Same when deserializing
>>> json.loads('-Infinity')
-inf
>>> json.loads('NaN')
nan

En el serializador, el parámetro allow_nan se puede utilizar para modificar este comportamiento. En el deserializador, se puede utilizar el parámetro parse_constant para modificar este comportamiento.

Nombres repetidos dentro de un objeto

La RFC especifica que los nombres dentro de un objeto JSON deben ser únicos, pero no exige cómo se deben controlar los nombres repetidos en los objetos JSON. De forma predeterminada, este módulo no genera una excepción; en su lugar, ignora todo excepto el último par nombre-valor para un nombre dado:

>>> weird_json = '{"x": 1, "x": 2, "x": 3}'
>>> json.loads(weird_json)
{'x': 3}

El parámetro object_pairs_hook se puede utilizar para alterar este comportamiento.

Valores de nivel superior No-Objeto , No-Arreglo

La versión anterior de JSON especificada por el obsoleto RFC 4627 [https://tools.ietf.org/html/rfc4627.html] requería que el valor de nivel superior de un texto JSON fuera un objeto JSON o un arreglo (Python dict o list), y no podía ser un valor JSON nulo, booleano, numérico o de cadena. RFC 7159 [https://tools.ietf.org/html/rfc7159.html] eliminó esa restricción, y este módulo no ha implementado ni ha implementado nunca esa restricción en su serializador o en su deserializador.

Independientemente, para lograr la máxima interoperabilidad, es posible que usted desee adherirse voluntariamente a la restricción.

Limitaciones de la implementación

Algunas implementaciones del deserializador JSON pueden establecer límites en:

el tamaño de los textos JSON aceptados

el nivel máximo de anidamiento de objetos y arreglos JSON

el rango y precisión de los números JSON

el contenido y la longitud máxima de las cadenas de caracteres JSON

Este módulo no impone tales límites más allá de los propios tipos de datos de Python relevantes o del propio intérprete de Python.

Al serializar en JSON, tenga en cuenta las limitaciones en las aplicaciones que pueden consumir su JSON. En particular, es común que los números JSON se deserialicen en números de doble precisión IEEE 754 y, por lo tanto, estén sujetos al rango y las limitaciones de precisión de esa representación. Esto es especialmente relevante cuando se serializan valores de Python int de magnitud extremadamente grande, o cuando se serializan instancias de tipos numéricos «exóticos» como decimal. Decimal.

Interfaz de línea de comandos

Código fuente: Lib/json/tool.py [https://github.com/python/cpython/tree/3.9/Lib/json/tool.py]

El módulo json.tool proporciona una interfaz de línea de comandos simple para validar e imprimir objetos JSON.

Si no se especifican los argumentos opcionales infile y outfile, se utilizarán sys.stdin y sys.stdout respectivamente:

$ echo '{"json": "obj"}' | python -m json.tool
{
    "json": "obj"
}
$ echo '{1.2:3.4}' | python -m json.tool
Expecting property name enclosed in double quotes: line 1 column 2 (char 1)

Distinto en la versión 3.5: La salida está ahora en el mismo orden que la entrada. Utilice la opción --sort-keys para ordenar la salida de los diccionarios alfabéticamente por llave.

Opciones de línea de comandos

infile

El archivo JSON que se va a validar o imprimir con impresión linda:

$ python -m json.tool mp_films.json
[
    {
        "title": "And Now for Something Completely Different",
        "year": 1971
    },
    {
        "title": "Monty Python and the Holy Grail",
        "year": 1975
    }
]

Si no se especifica infile, lee sys.stdin.

outfile

Escribe la salida de infile en el outfile dado. De lo contrario, lo escribe en sys.stdout.

--sort-keys

Ordena la salida de los diccionarios alfabéticamente por llave.

Nuevo en la versión 3.5.

--no-ensure-ascii

Deshabilita el escape de caracteres que no sean ascii, véase json.dumps() para más información.

Nuevo en la versión 3.9.

--json-lines

Analiza cada línea de entrada como objeto JSON independiente.

Nuevo en la versión 3.8.

--indent, --tab, --no-indent, --compact

Opciones mutuamente exclusivas para control de espacios en blanco.

Nuevo en la versión 3.9.

-h, --help

Muestra el mensaje de ayuda.

Notas de pie de página

1

Como se indica en la errata para RFC 7159 [https://www.rfc-editor.org/errata_search.php?rfc-7159], JSON permite caracteres literales U+2028 (SEPARADOR DE LINEA) y U+2029 (SEPARADOR DE PÁRRAFO) en cadenas, mientras que JavaScript (a partir de ECMAScript Edición 5.1) no lo hace.

mailbox — Manipular buzones de correo en varios formatos

Código fuente: Lib/mailbox.py [https://github.com/python/cpython/tree/3.9/Lib/mailbox.py]

Este módulo define dos clases, Mailbox y Message, para acceder y manipular en disco los buzones de correo y los mensajes que contienen. Mailbox ofrece una asignación similar a un diccionario de claves a mensajes. Message extiende la clase email.message del módulo Message con el estado y el comportamiento específicos del formato. Los formatos de buzón de correo compatibles son Maildir, mbox, MH, Babyl y MMDF.

Ver también

Módulo email

Representar y manipular mensajes.

Objetos :class:”Mailbox”

class mailbox.Mailbox

Un buzón de correo, que se puede inspeccionar y modificar.

La clase Mailbox define una interfaz y no está diseñada para crear instancias. En su lugar, las subclases específicas del formato deben heredar de Mailbox y el código debe crear una instancia de una subclase determinada.

La interfaz Mailbox es similar a un diccionario, con pequeñas claves correspondientes a los mensajes. Las claves son emitidas por la instancia Mailbox con la que se utilizarán y solo son significativas para esa instancia Mailbox. Una clave continúa identificando un mensaje incluso si se modifica el mensaje correspondiente, por ejemplo, sustituyéndolo por otro mensaje.

Los mensajes se pueden agregar a una instancia Mailbox utilizando el método como add() y quitarse mediante una instrucción del o los métodos como remove() y discard().

La semántica de la interfaz Mailbox difiere de la semántica del diccionario en algunos aspectos notables. Cada vez que se solicita un mensaje, se genera una nueva representación (típicamente una instancia Message) basada en el estado actual del buzón de correo. De forma similar, cuando se añade un mensaje a una instancia Mailbox, se copia el contenido de la representación del mensaje proporcionado. En ninguno de los dos casos se mantiene una referencia a la representación del mensaje por parte de la instancia Mailbox.

El iterador por defecto de Mailbox itera sobre las representaciones de los mensajes, no sobre las claves como lo hace el iterador del diccionario por defecto. Además, la modificación de un buzón de correo durante la iteración es segura y bien definida. Los mensajes añadidos al buzón de correo después de que se cree un iterador no serán vistos por el iterador. Los mensajes eliminados del buzón de correo antes de que el iterador los ceda serán omitidos silenciosamente, aunque el uso de una clave de un iterador puede dar lugar a una excepción KeyError si el mensaje correspondiente es eliminado posteriormente.

Advertencia

Sea muy cauteloso al modificar los buzones de correo que pueden ser cambiados simultáneamente por algún otro proceso. El formato más seguro de buzón de correo que se puede utilizar para esas tareas es Maildir; trate de evitar el uso de formatos de un solo archivo, como mbox, para la escritura simultánea. Si estás modificando un buzón de correo, debes bloquearlo llamando a los métodos lock() y unlock() antes de leer cualquier mensaje en el fichero o hacer cualquier cambio añadiendo o borrando un mensaje. Si no se bloquea el buzón se corre el riesgo de perder mensajes o de corromper todo el buzón.

Las instancias de Mailbox tienen los siguientes métodos:

add(message)

Añade message al buzón de correo y retorna la clave que se le ha asignado.

El parámetro message puede ser una instancia Message, una instancia email.message.Message, una cadena, una cadena de bytes o un objeto tipo archivo (que debe estar abierto en modo binario). Si message es una instancia de la subclase Message con el formato apropiado (por ejemplo, si es una instancia mboxMessage y ésta es una instancia mbox), se utiliza su información de formato específico. En caso contrario, se utilizan valores por defecto razonables para la información específica del formato.

Distinto en la versión 3.2: Se añadió el soporte para la entrada binaria.

remove(key)

__delitem__(key)

discard(key)

Borre el mensaje correspondiente a la key del buzón de correo.

Si no existe tal mensaje, se levanta una excepción KeyError si el método se llamó remove() o __delitem__() pero no se levanta una excepción si el método se llamó discard(). El comportamiento de discard() puede ser preferido si el formato de buzón subyacente soporta la modificación concurrente por otros procesos.

__setitem__(key, message)

Reemplaza el mensaje correspondiente a key por message. Levante una excepción KeyError si ningún mensaje ya corresponde a key.

Al igual que add(), el parámetro message puede ser una instancia Message, una instancia email.message.Message, una cadena, una cadena de bytes, o un objeto tipo archivo (que debe estar abierto en modo binario). Si message es una instancia de la subclase Message con el formato apropiado (por ejemplo, si es una instancia mboxMessage y ésta es una instancia mbox), se utiliza su información de formato específico. En caso contrario, la información específica del formato del mensaje que actualmente corresponde a key se deja sin cambios.

iterkeys()

keys()

Retorna un iterador sobre todas las claves si se llama iterkeys() o retorna una lista de claves si se llama keys().

itervalues()

__iter__()

values()

Retorna un iterador sobre las representaciones de todos los mensajes si se llama itervalores() o __iter__() o retorna una lista de tales representaciones si se llama values(). Los mensajes se representan como instancias de la subclase Message específica del formato, a menos que se haya especificado una fábrica de mensajes personalizados cuando se haya inicializado la instancia Mailbox.

Nota

El comportamiento de __iter__() es diferente al de los diccionarios, que iteran sobre las claves.

iteritems()

items()

Retorna un iterador sobre los pares (key, message), donde key es una clave y message es una representación de un mensaje, si se llama como iteritems() o retorna una lista de tales pares si se llama como items(). Los mensajes se representan como instancias de la subclase Message específica del formato, a menos que se haya especificado una fábrica de mensajes personalizados cuando se haya inicializado la instancia Maiblox.

get(key, default=None)

__getitem__(key)

Retorna una representación del mensaje correspondiente a key. Si no existe tal mensaje, se retorna default si el método fue llamado como get() y se produce una excepción KeyError si el método fue llamado como __getitem__(). El mensaje se representa como una instancia de la subclase Message específica del formato, a menos que se especificara una fábrica de mensajes personalizados cuando se inicializa la instancia Mailbox.

get_message(key)

Retorna una representación del mensaje correspondiente a key como una instancia de la subclase Message específica del formato, o lanza una excepción KeyError si no existe tal mensaje.

get_bytes(key)

Retorna una representación en bytes del mensaje correspondiente a key, o levanta una excepción KeyError si no existe tal mensaje.

Nuevo en la versión 3.2.

get_string(key)

Retorna una representación en cadena del mensaje correspondiente a key, o lanza una excepción KeyError si no existe tal mensaje. El mensaje se procesa a través de email.message.Message para convertirlo en una representación limpia de 7 bits.

get_file(key)

Retorna una representación en forma de archivo del mensaje correspondiente a key, o lanza una excepción KeyError si no existe tal mensaje. El objeto tipo archivo se comporta como si estuviera abierto en modo binario. Este archivo debería cerrarse una vez que ya no se necesite.

Distinto en la versión 3.2: El objeto del archivo es realmente un archivo binario; anteriormente fue retornado incorrectamente en modo de texto. Además, el objeto tipo archivo ahora soporta el protocolo de gestión de contexto: puedes usar una sentencia with para cerrarlo automáticamente.

Nota

A diferencia de otras representaciones de mensajes, las representaciones en forma de archivo no son necesariamente independientes de la instancia Mailbox que las creó o del buzón de correo subyacente. Cada subclase proporciona una documentación más específica.

__contains__(key)

Retorna True si «key» corresponde a un mensaje, si no False.

__len__()

Retorna un recuento de los mensajes en el buzón de correo.

clear()

Borrar todos los mensajes del buzón.

pop(key, default=None)

Retorna una representación del mensaje correspondiente a key y borra el mensaje. Si no existe tal mensaje, retorna default. El mensaje se representa como una instancia de la subclase Message con el formato apropiado, a menos que se haya especificado una fábrica de mensajes personalizados al inicializar la instancia Mailbox.

popitem()

Retorna un par arbitrario (key, message), donde key es una clave y message es una representación de un mensaje, y borra el mensaje correspondiente. Si el buzón de correo está vacío, lanza una excepción KeyError. El mensaje se representa como una instancia de la subclase Message específica del formato, a menos que se haya especificado una fábrica de mensajes personalizados al inicializar la instancia Mailbox.

update(arg)

El parámetro arg debe ser un mapa de key a message o un iterable de pares (key, message). Actualiza el buzón de correo para que, por cada key y message dados, el mensaje correspondiente a key será establecido a*message* como si se usara __setitem__(). Como con __setitem__(), cada key debe corresponder ya a un mensaje en el buzón de correo o de lo contrario se lanzará una excepción KeyError, por lo que en general es incorrecto que arg sea una instancia de Mailbox.

Nota

A diferencia de los diccionarios, los argumentos de las palabras clave no están soportados.

flush()

Escribe cualquier cambio pendiente en el sistema de archivos. Para algunas subclases de Mailbox, los cambios siempre se escriben inmediatamente y flush() no hace nada, pero aún así deberías tener el hábito de llamar a este método.

lock()

Adquiera un aviso exclusivo de bloqueo en el buzón de correo para que otros procesos sepan que no deben modificarlo. Un ExternalClashError se lanza si el bloqueo no está disponible. Los mecanismos de bloqueo particulares utilizados dependen del formato del buzón de correo. Deberías siempre bloquear el buzón antes de hacer cualquier modificación a su contenido.

unlock()

Libera el bloqueo del buzón de correo, si lo hay.

close()

Limpia el buzón de correo, y lo desbloquea si es necesario, y cierra cualquier archivo abierto. Para algunas subclases de Mailbox, este método no hace nada.

Maildir

class mailbox.Maildir(dirname, factory=None, create=True)

Una subclase de Mailbox para los buzones de correo en formato Maildir. El parámetro factory es un objeto invocable que acepta una representación de mensaje tipo archivo (que se comporta como si se abriera en modo binario) y retorna una representación personalizada. Si factory es None, MaildirMessage se utiliza como representación de mensaje por defecto. Si create es True, el buzón se crea si no existe.

Si create es True y la ruta de dirname existe, será tratado como un maildir existente sin intentar verificar su diseño de directorio.

Es por razones históricas que dirname es nombrado como tal en lugar de path.

Maildir es un formato de buzón de correo basado en un directorio inventado para el agente de transferencia de correo qmail y ahora ampliamente soportado por otros programas. Los mensajes en un buzón de correo de Maildir se almacenan en archivos separados dentro de una estructura de directorio común. Este diseño permite que los buzones de Maildir sean accedidos y modificados por múltiples programas no relacionados sin corrupción de datos, por lo que el bloqueo de archivos es innecesario.

Los buzones de correo de Maildir contienen tres subdirectorios, a saber: tmp, new, y cur. Los mensajes se crean momentáneamente en el subdirectorio tmp y luego se mueven al subdirectorio new para finalizar la entrega. Un agente de usuario de correo puede posteriormente mover el mensaje al subdirectorio cur y almacenar la información sobre el estado del mensaje en una sección especial «info» adjunta a su nombre de archivo.

Se admiten también carpetas del estilo introducido por el agente de transferencia de correo Courier. Cualquier subdirectorio del buzón de correo principal se considera una carpeta si '.' es el primer carácter de su nombre. Los nombres de las carpetas están representados por Maildir sin la palabra '.'. Cada carpeta es en sí misma un buzón de correo de Maildir pero no debe contener otras carpetas. En su lugar, se indica un anidamiento lógico usando '.' para delimitar los niveles, por ejemplo, «Archived.2005.07».

Nota

La especificación Maildir requiere el uso de dos puntos (':') en ciertos nombres de archivos de mensajes. Sin embargo, algunos sistemas operativos no permiten este carácter en los nombres de archivo, si desea utilizar un formato similar a Maildir en dicho sistema operativo, debe especificar otro carácter para utilizarlo en su lugar. El signo de exclamación ('!') es una elección popular. Por ejemplo:

import mailbox
mailbox.Maildir.colon = '!'

El atributo colon también puede ser establecido para cada instancia.

Las instancias de Maildir tienen todos los métodos de Mailbox además de los siguientes:

list_folders()

Retorna una lista con los nombres de todas las carpetas.

get_folder(folder)

Retorna una instancia Maildir que representa la carpeta cuyo nombre es folder. Una excepción NoSuchMailboxError se lanza si la carpeta no existe.

add_folder(folder)

Crea una carpeta cuyo nombre sea folder y retorna una instancia Maildir que la represente.

remove_folder(folder)

Elimina la carpeta cuyo nombre es folder. Si la carpeta contiene algún mensaje, se lanzará una excepción NotEmptyError y la carpeta no se borrará.

clean()

Borra los archivos temporales del buzón de correo que no han sido accedidos en las últimas 36 horas. La especificación Maildir dice que los programas de lectura de correo deben hacer esto ocasionalmente.

Algunos métodos de Mailbox implementados por Maildir merecen comentarios especiales:

add(message)

__setitem__(key, message)

update(arg)

Advertencia

Estos métodos generan nombres de archivo únicos basados en el ID del proceso actual. Cuando se utilizan varios hilos, pueden producirse conflictos de nombres no detectados y causar la corrupción del buzón de correo a menos que se coordinen los hilos para evitar que se utilicen estos métodos para manipular el mismo buzón de correo simultáneamente.

flush()

Todos los cambios en los buzones de Maildir se aplican inmediatamente, así que este método no hace nada.

lock()

unlock()

Los buzones de Maildir no admiten (o requieren) bloqueo, por lo que estos métodos no hacen nada.

close()

Las instancias de Maildir no mantienen ningún archivo abierto y los buzones subyacentes no soportan el bloqueo, por lo que este método no hace nada.

get_file(key)

Dependiendo de la plataforma del host, puede que no sea posible modificar o eliminar el mensaje subyacente mientras el archivo retornado permanezca abierto.

Ver también

pagina web maildir de Courier [http://www.courier-mta.org/maildir.html]

Una especificación del formato. Describe una extensión común para admitir carpetas.

Utilizando el formato maildir [https://cr.yp.to/proto/maildir.html]

Notas sobre Maildir por su inventor. Incluye un esquema actualizado de creación de nombres y detalles sobre la «info» de la semántica».

mbox

class mailbox.mbox(path, factory=None, create=True)

Una subclase de Mailbox para los buzones de correo en formato mbox. El parámetro factory es un objeto invocable que acepta una representación de mensaje tipo archivo (que se comporta como si se abriera en modo binario) y retorna una representación personalizada. Si factory es None, mboxMessage se utiliza como representación de mensaje por defecto. Si create es True, el buzón de correo se crea si no existe.

El formato mbox es el formato clásico para almacenar correo en sistemas Unix. Todos los mensajes de un buzón de correo mbox se almacenan en un único archivo con el comienzo de cada mensaje indicado por una línea cuyos cinco primeros caracteres son «From».

Existen varias variaciones del formato mbox para abordar las deficiencias percibidas en el original. En aras de la compatibilidad, mbox implementa el formato original, que a veces se denomina mboxo. Esto significa que el encabezado Content-Length, si está presente, se ignora y que cualquier ocurrencia de «From » al principio de una línea en el cuerpo de un mensaje se transforma en «>From » al almacenar el mensaje, aunque las ocurrencias de «>From » no se transforman en «From » al leer el mensaje.

Algunos métodos de Mailbox implementados por Maildir merecen comentarios especiales:

get_file(key)

Usar el archivo después de llamar a flush() o close() en la instancia mbox puede producir resultados impredecibles o lanzar una excepción.

lock()

unlock()

Se utilizan tres mecanismos de bloqueo… el bloqueo por puntos y, si está disponible, las llamadas del sistema flock() y lockf().

Ver también

pagina web mbox de tin [http://www.tin.org/bin/man.cgi?section=5&topic=mbox]

Una especificación del formato, con detalles sobre el bloqueo.

Configurando el correo de Netscape en Unix: Por qué el formato de longitud de contenido es malo [https://www.jwz.org/doc/content-length.html]

Un argumento para usar el formato original mbox en lugar de una variación.

«mbox» es una familia de varios formatos de buzón de correo mutuamente incompatibles <https://www.loc.gov/preservation/digital/formats/fdd/fdd000383.shtml>`__

Una historia de variaciones de mbox.

MH

class mailbox.MH(path, factory=None, create=True)

Una subclase de Mailbox para los buzones de correo en formato MH. El parámetro factory es un objeto invocable que acepta una representación de mensaje tipo archivo (que se comporta como si se abriera en modo binario) y retorna una representación personalizada. Si factory es None, MHMessage se utiliza como representación de mensaje por defecto. Si create es True, el buzón de correo se crea si no existe.

MH es un formato de buzón de correo basado en un directorio inventado para el Sistema de Manejo de Mensajes MH, un agente de usuario de correo. Cada mensaje de un buzón de correo MH reside en su propio archivo. Un buzón de correo MH puede contener otros buzones de correos MH (llamados folders) además de los mensajes. Las carpetas pueden anidarse indefinidamente. Los buzones de correo MH también soportan sequences, que son listas con nombre usadas para agrupar lógicamente los mensajes sin moverlos a subcarpetas. Las secuencias se definen en un archivo llamado .mh_sequences en cada carpeta.

La clase MH manipula los buzones de correos de MH, pero no intenta emular todos los comportamientos de mh. En particular, no modifica ni se ve afectado por los archivos de context o .mh_profile que utiliza mh para almacenar su estado y configuración.

Las instancias de Maildir tienen todos los métodos de Mailbox además de los siguientes:

list_folders()

Retorna una lista con los nombres de todas las carpetas.

get_folder(folder)

Retorna una instancia Maildir que representa la carpeta cuyo nombre es folder. Una excepción NoSuchMailboxError se lanza si la carpeta no existe.

add_folder(folder)

Crea una carpeta cuyo nombre sea folder y retorna una instancia MH que la represente.

remove_folder(folder)

Elimina la carpeta cuyo nombre es folder. Si la carpeta contiene algún mensaje, se lanzará una excepción NotEmptyError y la carpeta no se borrará.

get_sequences()

Retorna un diccionario de nombres de secuencias mapeadas a listas clave. Si no hay secuencias, se retorna el diccionario vacío.

set_sequences(sequences)

Re-define las secuencias que existen en el buzón de correo basado en sequences, un diccionario de nombres mapeados a listas de claves, como las retornadas por get_sequences().

pack()

Renombra los mensajes en el buzón de correo según sea necesario para eliminar los huecos en la numeración. Las entradas en la lista de secuencias se actualizan correspondientemente.

Nota

Las llaves ya emitidas quedan invalidadas por esta operación y no deben utilizarse posteriormente.

Algunos métodos de Mailbox implementados por Maildir merecen comentarios especiales:

remove(key)

__delitem__(key)

discard(key)

Estos métodos borran inmediatamente el mensaje. No se utiliza la convención del MH de marcar un mensaje para borrarlo poniendo una coma en su nombre.

lock()

unlock()

Se utilizan tres mecanismos de bloqueo… el bloqueo por puntos y, si está disponible, las llamadas del sistema flock() y lockf(). Para los buzones de correos MH, bloquear el buzón de correo significa bloquear el archivo .mh_sequences y, sólo durante la duración de cualquier operación que les afecte, bloquear los archivos de mensajes individuales.

get_file(key)

Dependiendo de la plataforma anfitriona, puede que no sea posible eliminar el mensaje subyacente mientras el archivo retornado permanezca abierto.

flush()

Todos los cambios en los buzones de correos de Maildir se aplican inmediatamente, así que este método no hace nada.

close()

Las instancias de MH no mantienen ningún archivo abierto, así que este método es equivalente a unlock().

Ver también

nmh - Sistema de Manejo de Mensajes [http://www.nongnu.org/nmh/]

Página principal de nmh, una versión actualizada del original mh.

MH & nmh: Correo electrónico para usuarios y programadores [https://rand-mh.sourceforge.io/book/]

Un libro con licencia GPL sobre mh y nmh, con alguna información sobre el formato del buzón.

Babyl

class mailbox.Babyl(path, factory=None, create=True)

Una subclase de Mailbox para los buzones en formato Babyl. El parámetro factory es un objeto invocable que acepta una representación de mensaje tipo archivo (que se comporta como si se abriera en modo binario) y retorna una representación personalizada. Si factory es None, BabylMessage se utiliza como representación de mensaje por defecto. Si create es True, el buzón se crea si no existe.

Babyl es un formato de buzón de un solo archivo usado por el agente de usuario de correo de Rmail incluido en Emacs. El comienzo de un mensaje se indica con una línea que contiene los dos caracteres Control-Underscore ('\037') y Control-L ('\014'). El final de un mensaje se indica con el comienzo del siguiente mensaje o, en el caso del último mensaje, una línea que contiene un carácter Control-Underscore ('\037').

Los mensajes en un buzón de correo de Babyl tienen dos juegos de encabezados, los encabezados originales y los llamados encabezados visibles. Los encabezados visibles son típicamente un subconjunto de los encabezados originales que han sido reformateados o abreviados para ser más atractivos. Cada mensaje de un buzón de correo de Babyl también tiene una lista de labels, o cadenas cortas que registran información adicional sobre el mensaje, y una lista de todas las etiquetas definidas por el usuario que se encuentran en el buzón de correo se mantiene en la sección de opciones de Babyl.

Las instancias de Maildir tienen todos los métodos de Mailbox además de los siguientes:

get_labels()

Retorna una lista de los nombres de todas las etiquetas definidas por el usuario utilizadas en el buzón de correo.

Nota

Los mensajes actuales se inspeccionan para determinar qué etiquetas existen en el buzón de correo en lugar de consultar la lista de etiquetas en la sección de opciones de Babyl, pero la sección de Babyl se actualiza cada vez que se modifica el buzón de correo.

Algunos métodos de Mailbox implementados por Maildir merecen comentarios especiales:

get_file(key)

En los buzones de correos de Babyl, los encabezados de un mensaje no se almacenan contiguamente al cuerpo del mensaje. Para generar una representación tipo archivo, las cabeceras y el cuerpo se copian juntos en una instancia io.BytesIO, que tiene una API idéntica a la de un archivo. Como resultado, el objeto similar a un archivo es verdaderamente independiente del buzón de correo subyacente, pero no ahorra memoria en comparación con una representación en cadena.

lock()

unlock()

Se utilizan tres mecanismos de bloqueo… el bloqueo por puntos y, si está disponible, las llamadas del sistema flock() y lockf().

Ver también

«Formato de la versión 5 de los archivos de Babyl» <https://quimby.gnus.org/notes/BABYL>`_

Una especificación del formato Babyl.

Leyendo el correo con Rmail [https://www.gnu.org/software/emacs/manual/html_node/emacs/Rmail.html]

El manual de Rmail, con cierta información sobre la semántica Babyl.

MMDF

class mailbox.MMDF(path, factory=None, create=True)

Una subclase de Mailbox para buzones de correos en formato MMDF. El parámetro factory es un objeto al que se puede llamar que acepta una representación de mensaje similar a un archivo (que se comporta como si se abriera en modo binario) y retorna una representación personalizada. Si factory es None, MMDFMessage se utiliza como representación de mensaje predeterminada. Si create es True, el buzón de correo se crea si no existe.

MMDF es un formato de buzón de correo de un solo archivo inventado para el centro de distribución de memorandos multicanal, un agente de transferencia de correo. Cada mensaje está en la misma forma que un mensaje de mbox, pero está entre corchetes antes y después por líneas que contienen cuatro caracteres Control-A ('\001'). Al igual que con el formato mbox, el principio de cada mensaje se indica mediante una línea cuyos primeros cinco caracteres son «From «, pero las apariciones adicionales de «From» no se transforman en «>From» al almacenar mensajes porque las líneas de separador de mensajes adicionales impiden confundir tales ocurrencias para los inicios de los mensajes posteriores.

Algunos métodos Mailbox implementados por MMDF merecen comentarios especiales:

get_file(key)

Usar el archivo después de llamar a flush() o close() en la instancia MMDF puede producir resultados impredecibles o generar una excepción.

lock()

unlock()

Se utilizan tres mecanismos de bloqueo… el bloqueo por puntos y, si está disponible, las llamadas del sistema flock() y lockf().

Ver también

Página web de mmdf de tin [http://www.tin.org/bin/man.cgi?section-5&topic-mmdf]

Una especificación del formato MMDF de la documentación de tin, un lector de noticias.

MMDF [https://en.wikipedia.org/wiki/MMDF]

Un artículo de Wikipedia que describe el Centro de Distribución de Memorandos Multicanal.

Objetos Message

class mailbox.Message(message=None)

Una subclase del módulo email.message de Message. Las subclases de mailbox.Message añaden el estado y el comportamiento específicos del formato del buzón de correo.

Si se omite message, la nueva instancia se crea en un estado predeterminado, vacío. Si message es una instancia email.message.Message, se copian sus contenidos; además, cualquier información específica del formato se convierte en la medida de lo posible si message es una instancia Message. Si message es una cadena, una cadena de bytes, o un archivo, debe contener un mensaje conforme RFC 2822 [https://tools.ietf.org/html/rfc2822.html], que se lee y analiza. Los archivos deben estar abiertos en modo binario, pero los archivos en modo texto son aceptados para compatibilidad con versiones anteriores.

El estado y los comportamientos específicos del formato que ofrecen las subclases varían, pero en general sólo se admiten las propiedades que no son específicas de un buzón de correo concreto (aunque presumiblemente las propiedades son específicas de un formato de buzón de correo concreto). Por ejemplo, no se conservan las compensaciones de archivos para los formatos de buzón de correo de un solo archivo ni los nombres de archivo para los formatos de buzón de correo basados en directorios, porque sólo son aplicables al buzón de correo original. Pero sí se conservan las declaraciones tales como si un mensaje ha sido leído por el usuario o marcado como importante, porque se aplican al propio mensaje.

No hay ningún requisito de que las instancias de Message se usen para representar los mensajes recuperados usando las instancias de Mailbox. En algunas situaciones, el tiempo y la memoria necesarios para generar representaciones de Message podrían no ser aceptables. Para estas situaciones, las instancias de Mailbox también ofrecen representaciones en forma de cadenas y archivos, y se puede especificar una fábrica de mensajes personalizados cuando se inicializa una instancia de Mailbox.

MaildirMessage

class mailbox.MaildirMessage(message=None)

Un mensaje con comportamientos específicos de Maildir. El parámetro message tiene el mismo significado que con el constructor Message.

Típicamente, una aplicación de agente de usuario de correo mueve todos los mensajes del subdirectorio new al subdirectorio cur después de la primera vez que el usuario abre y cierra el buzón de coreo, registrando que los mensajes son antiguos, tanto si han sido leídos como si no. Cada mensaje en cur tiene una sección «info» añadida a su nombre de archivo para almacenar información sobre su estado. (Algunos lectores de correo también pueden añadir una sección «info» a los mensajes en new.) La sección «info» puede tomar una de dos formas: puede contener «2», seguido de una lista de flags estandarizados (por ejemplo, «2,FR») o puede contener «1», seguido de la llamada información experimental. Los flags normalizados para los mensajes de Maildir son los siguientes:

Flag

Significado

Explicación

D

Borrador

Bajo composición

F

Marcada

Marcado como importante

P

Aprobado

Enviado, reenviado o rebotado

R

Contestado

Contestado a

S

Visto

Leído

T

Destruido

Marcado para su posterior eliminación

Instancias de MaildirMessage ofrecen los siguientes métodos:

get_subdir()

Retorna «new» (si el mensaje debe ser almacenado en el subdirectorio new) o «cur» (si el mensaje debe ser almacenado en el subdirectorio cur).

Nota

Un mensaje es típicamente movido de nuevo a cur después de que su buzón de correo ha sido accedido, ya sea que el mensaje haya sido leído o no. Un mensaje msg ha sido leído si "S" in msg.get_flags() es True.

set_subdir(subdir)

Establece el subdirectorio en el que debe almacenarse el mensaje. El parámetro subdir debe ser «new» o «cur».

get_flags()

Retorna una cadena que especifica los flags que están actualmente establecidos. Si el mensaje cumple con el formato estándar de Maildir, el resultado es la concatenación en orden alfabético de cero o una ocurrencia de cada una de los flags 'D', 'F', 'P', 'R', 'S', y 'T'. La cadena vacía se retorna si no hay flags o si «info» contiene semántica experimental.

set_flags(flags)

Establece los flags especificados por flags y desactiva todas las demás.

add_flag(flag)

Establece lo(s) flag(s) especificado(s) por flags sin cambiar otros flags. Para añadir más de un indicador a la vez, flag puede ser una cadena de más de un carácter. La «info» actual se sobrescribe si contiene o no información experimental en lugar de flags.

remove_flag(flag)

Deshabilita lo(s) flag(s) especificado(s) por flag sin cambiar otros flags. Para quitar más de un indicador a la vez, flag puede ser una cadena de más de un carácter. Si «info» contiene información experimental en lugar de flags, la «info» actual no se modifica.

get_date()

Retorna la fecha de entrega del mensaje como un número de punto flotante que representa los segundos desde la época.

set_date(date)

Establece la fecha de entrega del mensaje en date, un número de punto flotante que representa los segundos desde la época.

get_info()

Retorna una cadena que contiene la «info» de un mensaje. Esto es útil para acceder y modificar la «info» que es experimental (es decir, no una lista de flags).

set_info(info)

Establece «info» en info, que debería ser una cadena.

Cuando se crea una instancia MaildirMessage basada en una instancia mboxMessage o MMDFMessage, se omiten las cabeceras Status y X-Status y se producen las siguientes conversiones:

Estado resultante

Estado mboxMessage o MMDFMessage

subdirectorio «cur»

flag O

flag F

flag F

flag R

flag A

flag S

flag R

flag T

flag D

Cuando se crea una instancia MaildirMessage basada en una instancia MHMessage, se producen las siguientes conversiones:

Estado resultante

Estado MHMessage

subdirectorio «cur»

Secuencia «unseen» (no vista)

subdirectorio «cur» e indicador S

no hay una secuencia «unseen» (invisible)

flag F

secuencia «flagged» (marcada)

flag R

Secuencia «replied» (respondida)

Cuando se crea una instancia MaildirMessage basada en una instancia BabylMessage, se producen las siguientes conversiones:

Estado resultante

Estado BabylMessage

subdirectorio «cur»

etiqueta «unseen» (invisible)

subdirectorio «cur» e indicador S

no hay una etiqueta «unseen» (invisible)

flag P

etiqueta «forwarded» o «resent» (reenviado)

flag R

etiqueta de «answered» (contestado)

flag T

etiqueta «deleted» (borrado)

mboxMessage

class mailbox.mboxMessage(message=None)

Un mensaje con comportamientos específicos de mbox. El parámetro message tiene el mismo significado que con el constructor Message.

Los mensajes en un buzón de correo de mbox se almacenan juntos en un solo archivo. La dirección del sobre del remitente y la hora de entrega se almacenan normalmente en una línea que comienza con «From» que se utiliza para indicar el comienzo de un mensaje, aunque hay una variación considerable en el formato exacto de estos datos entre las implementaciones de mbox. Los flags del estado del mensaje, como por ejemplo si ha sido leído o marcado como importante, se almacenan típicamente en las cabeceras Status y X-Status.

Los flags convencionales para los mensajes de mbox son los siguientes:

Flag

Significado

Explicación

R

Leído

Leído

O

Antiguo

Anteriormente detectado por MUA

D

Borrado

Marcado para su posterior eliminación

F

Marcada

Marcado como importante

A

Respondido

Contestado a

Los flags «R» y «O» se almacenan en el encabezado Status y los flags «D», «F» y «A» se almacenan en el encabezado X-Status. Los flags y los encabezados aparecen típicamente en el orden mencionado.

Instancias de mboxMessage ofrecen los siguientes métodos:

get_from()

Retorna una cadena que representa la línea «From» que marca el inicio del mensaje en un buzón de correo de mbox. El «From» inicial y la nueva línea final están excluidas.

set_from(from_, time_=None)

Ponga la línea «From» en from_, que debe ser especificada sin una línea «From» o una nueva línea posterior. Para mayor comodidad, se puede especificar time_, que se formateará adecuadamente y se añadirá a from_. Si se especifica time_, debe ser una instancia time.struct_time, una tupla adecuada para pasar a time.strftime(), o True (para usar time.gmtime()).

get_flags()

Retorna una cadena que especifica los flags que están actualmente establecidos. Si el mensaje cumple con el formato convencional, el resultado es la concatenación en el siguiente orden de cero o una ocurrencia de cada uno de los flags “R”`, 'O', 'D', 'F', and 'A'.

set_flags(flags)

Establece los flags especificadas por flags y desactiva todos las demás. El parámetro flags debe ser la concatenación en cualquier orden de cero o más ocurrencias de cada uno de los flags 'R', 'O', 'D', 'F', and 'A'.

add_flag(flag)

Establece lo(s) flag(s) especificado(s) por flag sin cambiar otros flags. Para añadir más de un indicador a la vez, flag puede ser una cadena de más de un carácter.

remove_flag(flag)

Deshabilita lo(s) flag(s) especificado(s) por flag sin cambiar otros flags. Para quitar más de un indicador a la vez, flag puede ser una cadena de más de un carácter.

Cuando se crea una instancia mboxMessage basada en una instancia MaildirMessage, se genera una línea «From » basada en la fecha de entrega de la instancia MaildirMessage, y se realizan las siguientes conversiones:

Estado resultante

Estado de MaildirMessage

flag R

flag S

flag O

subdirectorio «cur»

flag D

flag T

flag F

flag F

flag A

flag R

Cuando se crea una instancia mboxMessage basada en una instancia MHMessage, se producen las siguientes conversiones:

Estado resultante

Estado MHMessage

flag R y flag O

no hay una secuencia «unseen» (invisible)

flag O

Secuencia «unseen» (no vista)

flag F

secuencia «flagged» (marcada)

flag A

Secuencia «replied» (respondida)

Cuando se crea una instancia mboxMessage basada en una instancia BabylMessage, se producen las siguientes conversiones:

Estado resultante

Estado BabylMessage

flag R y flag O

no hay una etiqueta «unseen» (invisible)

flag O

etiqueta «unseen» (invisible)

flag D

etiqueta «deleted» (borrado)

flag A

etiqueta de «answered» (contestado)

Cuando se crea una instancia Message basada en una instancia MMDFMessage, la línea «From» se copia y todas los flags se corresponden directamente:

Estado resultante

Estado de MMDFMessage

flag R

flag R

flag O

flag O

flag D

flag D

flag F

flag F

flag A

flag A

MHMessage

class mailbox.MHMessage(message=None)

Un mensaje con comportamientos específicos de la HM. El parámetro message tiene el mismo significado que con el constructor Message.

Los mensajes de MH no soportan marcas o flags en el sentido tradicional, pero sí secuencias, que son agrupaciones lógicas de mensajes arbitrarios. Algunos programas de lectura de correo (aunque no los estándares mh y nmh) usan secuencias de manera muy similar a los flags que se usan con otros formatos, como sigue:

Secuencia

Explicación

unseen (no visto)

No leído, pero previamente detectado por la MUA

replied (contestado)

Contestado a

flagged (marcado)

Marcado como importante

Instancias de MHMessage ofrecen los siguientes métodos:

get_sequences()

Retorna una lista de los nombres de las secuencias que incluyen este mensaje.

set_sequences(sequences)

Establece la lista de secuencias que incluyen este mensaje.

add_sequence(sequence)

Añade sequence a la lista de secuencias que incluyen este mensaje.

remove_sequence(sequence)

Elimina sequence de la lista de secuencias que incluyen este mensaje.

Cuando se crea una instancia MHMessage basada en una instancia MaildirMessage, se producen las siguientes conversiones:

Estado resultante

Estado de MaildirMessage

Secuencia «unseen» (no vista)

no hay indicador S

Secuencia «replied» (respondida)

flag R

secuencia «flagged» (marcada)

flag F

Cuando se crea una instancia MHMessage basada en una instancia mboxMessage o MMDFMessage, se omiten las cabeceras Status y X-Status y se producen las siguientes conversiones:

Estado resultante

Estado mboxMessage o MMDFMessage

Secuencia «unseen» (no vista)

sin indicador R

Secuencia «replied» (respondida)

flag A

secuencia «flagged» (marcada)

flag F

Cuando se crea una instancia MHMessage basada en una instancia BabylMessage, se producen las siguientes conversiones:

Estado resultante

Estado BabylMessage

Secuencia «unseen» (no vista)

etiqueta «unseen» (invisible)

Secuencia «replied» (respondida)

etiqueta de «answered» (contestado)

BabylMessage

class mailbox.BabylMessage(message=None)

Un mensaje con comportamientos específicos de Babyl. El parámetro message tiene el mismo significado que con el constructor Message.

Ciertas etiquetas de mensajes, llamadas attributes, están definidas por convención para tener significados especiales. Los atributos son los siguientes:

Etiqueta

Explicación

unseen (no visto)

No leído, pero previamente detectado por la MUA

deleted (borrado)

Marcado para su posterior eliminación

filed (archivado)

Copiado a otro archivo o buzón de correo

answered (contestado)

Contestado a

forwarded (reenviado)

Reenviado

edited (editado)

Modificado por el usuario

resent (reenviado)

Reenviado

De forma predeterminada, Rmail sólo muestra las cabeceras visibles. La clase BabylMessage, sin embargo, usa los encabezados originales porque son más completos. Se puede acceder a las cabeceras visibles explícitamente si se desea.

Instancias de BabylMessage ofrecen los siguientes métodos:

get_labels()

Retorna una lista de etiquetas en el mensaje.

set_labels(labels)

Establece la lista de etiquetas del mensaje en labels.

add_label(label)

Añade label a la lista de etiquetas del mensaje.

remove_label(label)

Eliminar label de la lista de etiquetas del mensaje.

get_visible()

Retorna una instancia de Message cuyos encabezados son los encabezados visibles del mensaje y cuyo cuerpo está vacío.

set_visible(visible)

Establece los encabezados visibles del mensaje para que sean los mismos que los del message. El parámetro visible debe ser una instancia Message, una instancia email.message.Message, una cadena, o un objeto tipo archivo (que debe estar abierto en modo texto).

update_visible()

Cuando se modifican los encabezados originales de una instancia BabylMessage, los encabezados visibles no se modifican automáticamente para que se correspondan. Este método actualiza los encabezados visibles de la siguiente manera: cada encabezado visible con un encabezado original correspondiente se establece como el valor del encabezado original, cada encabezado visible sin un encabezado original correspondiente se elimina, y cualquiera de Date, From, Reply-To, To, CC, y Subject que están presentes en las cabeceras originales pero no las cabeceras visibles se añaden a las cabeceras visibles.

Cuando se crea una instancia BabylMessage basada en una instancia MaildirMessage, se producen las siguientes conversiones:

Estado resultante

Estado de MaildirMessage

etiqueta «unseen» (invisible)

no hay indicador S

etiqueta «deleted» (borrado)

flag T

etiqueta de «answered» (contestado)

flag R

etiqueta «forwarded» (reenviado)

flag P

Cuando se crea una instancia BabylMessage basada en una instancia mboxMessage o MMDFMessage, se omiten los encabezados Status y X-Status y se producen las siguientes conversiones:

Estado resultante

Estado mboxMessage o MMDFMessage

etiqueta «unseen» (invisible)

sin indicador R

etiqueta «deleted» (borrado)

flag D

etiqueta de «answered» (contestado)

flag A

Cuando se crea una instancia BabylMessage basada en una instancia MHMessage, se producen las siguientes conversiones:

Estado resultante

Estado MHMessage

etiqueta «unseen» (invisible)

Secuencia «unseen» (no vista)

etiqueta de «answered» (contestado)

Secuencia «replied» (respondida)

MMDFMessage

class mailbox.MMDFMessage(message=None)

Un mensaje con comportamientos específicos de MMDF. El parámetro message tiene el mismo significado que con el constructor Message.

Al igual que los mensajes en un buzón de correo de mbox, los mensajes MMDF se almacenan con la dirección del remitente y la fecha de entrega en una línea inicial que comienza con «From». De la misma manera, los flags que indican el estado del mensaje se almacenan típicamente en las cabeceras Status y X-Status.

Los flags convencionales para los mensajes MMDF son idénticos a las de los mensajes de mbox y son los siguientes:

Flag

Significado

Explicación

R

Leído

Leído

O

Antiguo

Anteriormente detectado por MUA

D

Borrado

Marcado para su posterior eliminación

F

Marcada

Marcado como importante

A

Respondido

Contestado a

Los flags «R» y «O» se almacenan en el encabezado Status y los flags «D», «F» y «A» se almacenan en el encabezado X-Status. Los flags y los encabezados aparecen típicamente en el orden mencionado.

Las instancias de MMDFMessage ofrecen los siguientes métodos, que son idénticos a los ofrecidos por mboxMessage:

get_from()

Retorna una cadena que representa la línea «From» que marca el inicio del mensaje en un buzón de correo de mbox. El «From» inicial y la nueva línea final están excluidas.

set_from(from_, time_=None)

Ponga la línea «From» en from_, que debe ser especificada sin una línea «From» o una nueva línea posterior. Para mayor comodidad, se puede especificar time_, que se formateará adecuadamente y se añadirá a from_. Si se especifica time_, debe ser una instancia time.struct_time, una tupla adecuada para pasar a time.strftime(), o True (para usar time.gmtime()).

get_flags()

Retorna una cadena que especifica los flags que están actualmente establecidos. Si el mensaje cumple con el formato convencional, el resultado es la concatenación en el siguiente orden de cero o una ocurrencia de cada uno de los flags “R”`, 'O', 'D', 'F', and 'A'.

set_flags(flags)

Establece los flags especificadas por flags y desactiva todos las demás. El parámetro flags debe ser la concatenación en cualquier orden de cero o más ocurrencias de cada uno de los flags 'R', 'O', 'D', 'F', and 'A'.

add_flag(flag)

Establece lo(s) flag(s) especificado(s) por flag sin cambiar otros flags. Para añadir más de un indicador a la vez, flag puede ser una cadena de más de un carácter.

remove_flag(flag)

Deshabilita lo(s) flag(s) especificado(s) por flag sin cambiar otros flags. Para quitar más de un indicador a la vez, flag puede ser una cadena de más de un carácter.

Cuando se crea una instancia MMDFMessage basada en una instancia MaildirMessage, se genera una línea «From » basada en la fecha de entrega de la instancia MaildirMessage, y se realizan las siguientes conversiones:

Estado resultante

Estado de MaildirMessage

flag R

flag S

flag O

subdirectorio «cur»

flag D

flag T

flag F

flag F

flag A

flag R

Cuando se crea una instancia MMDFMessage basada en una instancia MHMessage, se producen las siguientes conversiones:

Estado resultante

Estado MHMessage

flag R y flag O

no hay una secuencia «unseen» (invisible)

flag O

Secuencia «unseen» (no vista)

flag F

secuencia «flagged» (marcada)

flag A

Secuencia «replied» (respondida)

Cuando se crea una instancia MMDFMessage basada en una instancia BabylMessage, se producen las siguientes conversiones:

Estado resultante

Estado BabylMessage

flag R y flag O

no hay una etiqueta «unseen» (invisible)

flag O

etiqueta «unseen» (invisible)

flag D

etiqueta «deleted» (borrado)

flag A

etiqueta de «answered» (contestado)

Cuando se crea una instancia MMDFMessage basada en una instancia mboxMessage, la línea «From » se copia y todos los flags se corresponden directamente:

Estado resultante

Estado de mboxMessage

flag R

flag R

flag O

flag O

flag D

flag D

flag F

flag F

flag A

flag A

Excepciones

Las siguientes clases de excepción están definidas en el módulo mailbox:

exception mailbox.Error

La clase base para todas las demás excepciones específicas del módulo.

exception mailbox.NoSuchMailboxError

Se lanza cuando se espera un buzón de correo pero no se encuentra, como cuando se instancia una subclase Mailbox con una ruta que no existe (y con el parámetro create establecido en False), o cuando se abre una carpeta que no existe.

exception mailbox.NotEmptyError

Se lanza cuando un buzón de correo no está vacío, pero se espera que lo esté, como cuando se elimina una carpeta que contiene mensajes.

exception mailbox.ExternalClashError

Se lanza cuando alguna condición relacionada con el buzón de correo, fuera del control del programa, hace que éste no pueda proceder, como por ejemplo cuando se falla en la adquisición de un bloqueo que es mantenido por otro programa, o cuando ya existe un nombre de archivo generado de forma única.

exception mailbox.FormatError

Se lanza cuando los datos de un archivo no pueden ser analizados, como cuando una instancia MH intenta leer un archivo .mh_sequences corrupto.

Ejemplos

Un simple ejemplo de impresión de los temas de todos los mensajes en un buzón de correo que parecen interesantes:

import mailbox
for message in mailbox.mbox('~/mbox'):
    subject = message['subject']       # Could possibly be None.
    if subject and 'python' in subject.lower():
        print(subject)

Para copiar todo el correo de un buzón de Babyl a un buzón de MH, convirtiendo toda la información de formato específico que puede ser convertida:

import mailbox
destination = mailbox.MH('~/Mail')
destination.lock()
for message in mailbox.Babyl('~/RMAIL'):
    destination.add(mailbox.MHMessage(message))
destination.flush()
destination.unlock()

Este ejemplo clasifica el correo de varias listas de correo en diferentes buzones, teniendo cuidado de evitar la corrupción del correo debido a la modificación simultánea por otros programas, la pérdida de correo debido a la interrupción del programa, o la terminación prematura debido a mensajes malformados en el buzón:

import mailbox
import email.errors

list_names = ('python-list', 'python-dev', 'python-bugs')

boxes = {name: mailbox.mbox('~/email/%s' % name) for name in list_names}
inbox = mailbox.Maildir('~/Maildir', factory=None)

for key in inbox.iterkeys():
    try:
        message = inbox[key]
    except email.errors.MessageParseError:
        continue                # The message is malformed. Just leave it.

    for name in list_names:
        list_id = message['list-id']
        if list_id and name in list_id:
            # Get mailbox to use
            box = boxes[name]

            # Write copy to disk before removing original.
            # If there's a crash, you might duplicate a message, but
            # that's better than losing a message completely.
            box.lock()
            box.add(message)
            box.flush()
            box.unlock()

            # Remove original message
            inbox.lock()
            inbox.discard(key)
            inbox.flush()
            inbox.unlock()
            break               # Found destination, so stop looking.

for box in boxes.itervalues():
    box.close()

mimetypes — Mapea nombres de archivo a tipos MIME

Código fuente: Lib/mimetypes.py [https://github.com/python/cpython/tree/3.9/Lib/mimetypes.py]

El módulo mimetypes convierte entre un nombre de archivo o URL y el tipo MIME asociado a la extensión del nombre de archivo. Se proporcionan conversiones de nombre de archivo a tipo MIME y de tipo MIME a extensión de nombre de archivo; no se admiten codificaciones para esta última conversión.

El módulo proporciona una clase y varias funciones de conveniencia. Las funciones son la interfaz normal de este módulo, pero algunas aplicaciones pueden estar interesadas en la clase también.

Las funciones que se describen a continuación constituyen la interfaz principal de este módulo. Si el módulo no ha sido inicializado, llamarán init() si se basan en la información que init() establece.

mimetypes.guess_type(url, strict=True)

Adivina el tipo de un archivo basado en su nombre de archivo, ruta o URL, dado por url. La URL puede ser una cadena o un objeto path-like object.

El valor de retorno es una tupla (type, encoding) donde type es None si el tipo no puede ser adivinado (por sufijo ausente o desconocido) o una cadena de la forma type/subtype', utilizable para un encabezado MIME content-type.

encoding es None para no codificar o el nombre del programa usado para codificar (por ejemplo compress o gzip). La codificación es adecuada para ser usada como una cabecera de Content-Encoding, no como una cabecera de Content-Transfer-Encoding. Los mapeos son conducidos por tablas. Los sufijos de codificación son sensibles a las mayúsculas y minúsculas; los sufijos de tipo se prueban primero distinguiendo entre mayúsculas y minúsculas, y luego sin dicha distinción.

El argumento opcional strict es una flag que especifica si la lista de tipos MIME conocidos se limita sólo a los tipos oficiales registrados en IANA [https://www.iana.org/assignments/media-types/media-types.xhtml]. Cuando strict es True (el valor por defecto), sólo se soportan los tipos de IANA; cuando strict es False, también se reconocen algunos tipos MIME adicionales no estándar pero de uso común.

Distinto en la versión 3.8: Añadido soporte para que la URL sea un objeto path-like object.

mimetypes.guess_all_extensions(type, strict=True)

Adivina las extensiones de un archivo basadas en su tipo MIME, dadas por type. El valor de retorno es una lista de cadenas que dan todas las extensiones posibles del nombre del archivo, incluyendo el punto inicial ('.'). No se garantiza que las extensiones hayan sido asociadas con ningún flujo de datos en particular, pero serían mapeadas al tipo MIME type por guess_type().

El argumento opcional strict tiene el mismo significado que con la función guess_type().

mimetypes.guess_extension(type, strict=True)

Adivina la extensión de un archivo basada en su tipo MIME, dada por type. El valor de retorno es una cadena que da una extensión de nombre de archivo, incluyendo el punto inicial ('.'). No se garantiza que la extensión haya sido asociada con ningún flujo de datos en particular, pero sería mapeada al tipo MIME type por guess_type(). Si no se puede adivinar ninguna extensión para type, se retorna None.

El argumento opcional strict tiene el mismo significado que con la función guess_type().

Algunas funciones adicionales y elementos de datos están disponibles para controlar el comportamiento del módulo.

mimetypes.init(files=None)

Inicializa las estructuras de datos internos. Si se proporciona files debe ser una secuencia de nombres de archivos que deben utilizarse para aumentar el mapa de tipo por defecto. Si se omite, los nombres de archivo a utilizar se toman de knownfiles; en Windows, se cargan las configuraciones actuales del registro. Cada archivo nombrado en files o knownfiles tiene prioridad sobre los nombrados antes de él. Se permite llamar repetidamente a init().

Si se especifica una lista vacía para files se evitará que se apliquen los valores predeterminados del sistema: sólo estarán presentes los valores conocidos de una lista incorporada.

Si files es None la estructura interna de datos se reconstruye completamente a su valor inicial por defecto. Esta es una operación estable y producirá los mismos resultados cuando se llame varias veces.

Distinto en la versión 3.2: Anteriormente, la configuración del registro de Windows se ignoraba.

mimetypes.read_mime_types(filename)

Carga el mapa de tipo dado en el archivo filename, si existe. El mapa de tipos es retornado como un diccionario que mapea las extensiones de los nombres de archivo, incluyendo el punto inicial ('.'), a las cadenas de la forma 'type/subtype'. Si el archivo filename no existe o no puede ser leído, se retorna None.

mimetypes.add_type(type, ext, strict=True)

Añade un mapeo del tipo MIME type a la extensión ext. Cuando la extensión ya se conoce, el nuevo tipo reemplazará al antiguo. Cuando el tipo ya se conoce la extensión se añadirá a la lista de extensiones conocidas.

Cuando strict es True (el valor por defecto), el mapeo se añadirá a los tipos MIME oficiales, de lo contrario a los no estándar.

mimetypes.inited

Flag que indica si se han inicializado o no las estructuras de datos globales. Esto se establece como «True» por init().

mimetypes.knownfiles

Lista de los nombres de los archivos de mapas de tipo comúnmente instalados. Estos archivos se llaman típicamente mime.types y se instalan en diferentes lugares por diferentes paquetes.

mimetypes.suffix_map

Diccionario que mapea sufijos a sufijos. Se utiliza para permitir el reconocimiento de archivos codificados cuya codificación y tipo se indican con la misma extensión. Por ejemplo, la extensión .tgz se mapea a .tar.gz para permitir que la codificación y el tipo se reconozcan por separado.

mimetypes.encodings_map

El diccionario mapea las extensiones de los nombres de archivo a los tipos de codificación.

mimetypes.types_map

Diccionario que mapea extensiones de los nombres de archivo a tipos MIME.

mimetypes.common_types

Diccionario que mapea extensiones de los nombres de archivo a tipos MIME no estándar, pero comúnmente encontrados.

Un ejemplo de utilización del módulo:

>>> import mimetypes
>>> mimetypes.init()
>>> mimetypes.knownfiles
['/etc/mime.types', '/etc/httpd/mime.types', ... ]
>>> mimetypes.suffix_map['.tgz']
'.tar.gz'
>>> mimetypes.encodings_map['.gz']
'gzip'
>>> mimetypes.types_map['.tgz']
'application/x-tar-gz'

Objetos MimeTypes

La clase MimeTypes puede ser útil para aplicaciones que quieran más de una base de datos de tipo MIME; proporciona una interfaz similar a la del módulo mimetypes.

class mimetypes.MimeTypes(filenames=(), strict=True)

Esta clase representa una base de datos de tipos MIME. Por defecto, proporciona acceso a la misma base de datos que el resto de este módulo. La base de datos inicial es una copia de la proporcionada por el módulo, y puede ser extendida cargando archivos adicionales de tipo mime.types en la base de datos usando los métodos read() o readfp(). Los diccionarios de mapeo también pueden ser borrados antes de cargar datos adicionales si no se desean los datos por defecto.

El parámetro opcional filenames puede utilizarse para hacer que se carguen archivos adicionales «encima» de la base de datos predeterminada.

suffix_map

El diccionario mapea sufijos a sufijos. Se utiliza para permitir el reconocimiento de archivos codificados cuya codificación y tipo se indican con la misma extensión. Por ejemplo, la extensión .tgz se mapea a .tar.gz para permitir que la codificación y el tipo se reconozcan por separado. Esto es inicialmente una copia del global suffix_map definido en el módulo.

encodings_map

El diccionario mapea las extensiones de los nombres de archivo a los tipos de codificación. Es inicialmente una copia del global encodings_map definido en el módulo.

types_map

Una tupla que contiene dos diccionarios, mapeando las extensiones de los nombres de archivo a los tipos MIME: el primer diccionario es para los tipos no estándar y el segundo para los tipos estándar. Están inicializados por common_types y types_map.

types_map_inv

Una tupla que contiene dos diccionarios, mapeando los tipos MIME a una lista de extensiones de nombres de archivos: el primer diccionario es para los tipos no estándar y el segundo para los tipos estándar. Están inicializados por common_types y types_map.

guess_extension(type, strict=True)

Similar a la función guess_extension(), usando las tablas almacenadas como parte del objeto.

guess_type(url, strict=True)

Similar a la función guess_type(), usando las tablas almacenadas como parte del objeto.

guess_all_extensions(type, strict=True)

Similar a la función guess_all_extensions(), usando las tablas almacenadas como parte del objeto.

read(filename, strict=True)

Carga información MIME de un archivo llamado filename. Esto usa readfp() para analizar el archivo.

Si strict es True, la información se añadirá a la lista de tipos estándar, si no a la lista de tipos no estándar.

readfp(fp, strict=True)

Carga información de tipo MIME de un archivo abierto fp. El archivo debe tener el formato de los archivos estándar mime.types.

Si strict es True, la información se va a añadir a la lista de tipos estándar, de otro modo se añadirá a la lista de tipos no estándar.

read_windows_registry(strict=True)

Carga información desde el registro de Windows del tipo de metadato MIME.

Disponibilidad: Windows.

Si strict es True, la información se va a añadir a la lista de tipos estándar, de otro modo se añadirá a la lista de tipos no estándar.

Nuevo en la versión 3.2.

base64 — Codificaciones de datos Base16, Base32, Base64, y Base85

Código fuente: Lib/base64.py [https://github.com/python/cpython/tree/3.9/Lib/base64.py]

Este módulo proporciona funciones para codificar datos binarios en caracteres ASCII imprimibles y decodificar dichas codificaciones en datos binarios. Proporciona funciones de codificación y decodificación para las codificaciones especificadas en RFC 3548 [https://tools.ietf.org/html/rfc3548.html], que define los algoritmos Base16, Base32 y Base64, y para las codificaciones estándar de facto Ascii85 y Base85.

Las codificaciones RFC 3548 [https://tools.ietf.org/html/rfc3548.html] son adecuadas para codificar datos binarios para que puedan enviarse de forma segura por correo electrónico, usarse como partes de URL o incluirse como parte de una solicitud HTTP POST. El algoritmo de codificación no es el mismo que el programa uuencode.

Hay dos interfaces proporcionadas por este módulo. La interfaz moderna admite la codificación de objetos similares a bytes a ASCII bytes, y decodificación objetos similares a bytes o cadenas de caracteres que contienen ASCII a bytes. Ambos alfabetos de base 64 definidos en RFC 3548 [https://tools.ietf.org/html/rfc3548.html] (normal y seguro para URL y sistema de archivos) son compatibles.

La interfaz heredada no admite la decodificación desde cadenas de caracteres, pero sí proporciona funciones para codificar y decodificar desde y hacia objetos de archivo. Solo admite el alfabeto estándar Base64 y agrega nuevas líneas cada 76 caracteres según RFC 2045 [https://tools.ietf.org/html/rfc2045.html]. Tenga en cuenta que si está buscando soporte de RFC 2045 [https://tools.ietf.org/html/rfc2045.html], probablemente desee ver el paquete email en su lugar.

Distinto en la versión 3.3: Las cadenas de caracteres Unicode de solo ASCII ahora son aceptadas por las funciones de decodificación de la interfaz moderna.

Distinto en la versión 3.4: Cualquier objeto similar a bytes ahora son aceptados por todas las funciones de codificación y decodificación en este módulo. Ascii85/Base85 soporte agregado.

Las interfaces modernas proporcionan:

base64.b64encode(s, altchars=None)

Codifica el objeto similar a bytes s utilizando Base64 y retorna los bytes codificados.

Los altchars opcionales deben ser un objeto similar a bytes de al menos longitud 2 (se ignoran los caracteres adicionales) que especifica un alfabeto alternativo para los caracteres + y /. Esto permite que una aplicación, por ejemplo, generar URL o cadenas de caracteres de Base64 seguras para el sistema de archivos. El valor predeterminado es None, para el que se utiliza el alfabeto estándar Base64.

base64.b64decode(s, altchars=None, validate=False)

Decodifica el objeto similar a bytes codificado en Base64 o cadena de caracteres ASCII s y retorna los bytes decodificados.

Los altchars opcionales deben ser objetos similares a byte o cadena de caracteres ASCII de al menos longitud 2 (se ignoran los caracteres adicionales) que especifica el alfabeto alternativo utilizado en lugar de los caracteres + y /.

Una excepción binascii.Error se lanza si s está incorrectamente rellenado (padded).

Si validate es False (el valor predeterminado), los caracteres que no están en el alfabeto normal de base 64 ni en el alfabeto alternativo se descartan antes de la verificación del relleno. Si validate es True, estos caracteres no alfabéticos en la entrada dan como resultado binascii.Error.

base64.standard_b64encode(s)

Codifica el objeto similar a bytes s usando el alfabeto estándar Base64 y retorna los bytes codificados.

base64.standard_b64decode(s)

Decodifica un bytes-like object o cadena de caracteres ASCII s utilizando el alfabeto estándar Base64 y retorna los bytes decodificados.

base64.urlsafe_b64encode(s)

Codifica el objecto similar a bytes s usando el alfabeto seguro para URL y sistemas de archivos, que sustituye a - en lugar de + y _ en lugar de / en el alfabeto estándar de Base64, y retorna los bytes codificados. El resultado aún puede contener =.

base64.urlsafe_b64decode(s)

Decodifica objeto similar a bytes o cadena de caracteres ASCII s utilizando el alfabeto seguro para URL y sistema de archivos, que sustituye - en lugar de + y _ en lugar de / en el alfabeto estándar de Base64, y retorna los bytes decodificados.

base64.b32encode(s)

Codifica el objeto similar a bytes s utilizando Base32 y retorna los bytes codificados.

base64.b32decode(s, casefold=False, map01=None)

Decodifica el objeto similar a bytes codificado en Base32 o cadena de caracteres ASCII s y retorna los bytes decodificados.

El opcional casefold es un flag que especifica si un alfabeto en minúscula es aceptable como entrada. Por motivos de seguridad, el valor predeterminado es Falso.

RFC 3548 [https://tools.ietf.org/html/rfc3548.html] permite el mapeo opcional del dígito 0 (cero) a la letra O (oh), y el mapeo opcional del dígito 1 (uno) a la letra I (eye) o la letra L (el) . El argumento opcional map01 cuando no es None, especifica a qué letra se debe asignar el dígito 1 (cuando map01 no es None, el dígito 0 siempre se asigna a la letra O). Por motivos de seguridad, el valor predeterminado es None, por lo que 0 y 1 no están permitidos en la entrada.

Una binascii.Error se lanza si s está incorrectamente rellenado (padded) o si hay caracteres no alfabéticos presentes en la entrada.

base64.b16encode(s)

Codifica el objeto similar a bytes s utilizando Base16 y retorna los bytes codificados.

base64.b16decode(s, casefold=False)

Decodifica el objeto similar a bytes codificado en Base16 o cadena de caracteres ASCII s y retorna los bytes decodificados.

El opcional casefold es un flag que especifica si un alfabeto en minúscula es aceptable como entrada. Por motivos de seguridad, el valor predeterminado es Falso.

Una binascii.Error se lanza si s está incorrectamente rellenado (padded) o si hay caracteres no alfabéticos presentes en la entrada.

base64.a85encode(b, *, foldspaces=False, wrapcol=0, pad=False, adobe=False)

Codifica el objeto similar a bytes b utilizando Ascii85 y retorna los bytes codificados.

foldspaces es un flag opcional que utiliza la secuencia corta especial “y” en lugar de 4 espacios consecutivos (ASCII 0x20) como lo admite “btoa”. Esta característica no es compatible con la codificación Ascii85 «estándar».

wrapcol controla si la salida debe tener caracteres de nueva línea (b'\n') agregados. Si esto no es cero, cada línea de salida tendrá como máximo esta cantidad de caracteres.

pad controla si la entrada se rellena (padded) a un múltiplo de 4 antes de la codificación. Tenga en cuenta que la implementación de btoa siempre es rellenada (pads).

adobe controla si la secuencia de bytes codificada está enmarcada con <~ y ~>, que es utilizada por la implementación de Adobe.

Nuevo en la versión 3.4.

base64.a85decode(b, *, foldspaces=False, adobe=False, ignorechars=b' \t\n\r\v')

Decodifica el objeto similar a bytes codificado en Ascii85 o cadena de caracteres ASCII b y retorna los bytes decodificados.

foldspaces es un flag que especifica si la secuencia corta “y” debe aceptarse como abreviatura durante 4 espacios consecutivos (ASCII 0x20). Esta característica no es compatible con la codificación Ascii85 «estándar».

adobe controla si la secuencia de entrada está en formato Adobe Ascii85 (es decir, se enmarca con <~ y ~>).

ignorechars debe ser un objeto similar a byte o cadena de caracteres ASCII que contiene caracteres para ignorar desde la entrada. Esto solo debe contener caracteres de espacio en blanco, y por defecto contiene todos los caracteres de espacio en blanco en ASCII.

Nuevo en la versión 3.4.

base64.b85encode(b, pad=False)

Codifica el objeto similar a bytes b utilizando base85 (como se usa en por ejemplo, diferencias binarias de estilo git) y retorna los bytes codificados.

Si pad es verdadero, la entrada se rellena con b'\0', por lo que su longitud es un múltiplo de 4 bytes antes de la codificación.

Nuevo en la versión 3.4.

base64.b85decode(b)

Decodifica el objeto similar a bytes codificado en base85 o cadena de caracteres ASCII b y retorna los bytes decodificados. El relleno se elimina implícitamente, si es necesario.

Nuevo en la versión 3.4.

La interfaz antigua:

base64.decode(input, output)

Decodifica el contenido del archivo binario input y escribe los datos binarios resultantes en el archivo output. input y output deben ser objetos archivo. input se leerá hasta que input.readline() retorne un objeto de bytes vacío.

base64.decodebytes(s)

Decodifica el objeto similar a bytes s, que debe contener una o más líneas de datos codificados en base64, y retornará los bytes decodificados.

Nuevo en la versión 3.1.

base64.encode(input, output)

Codifica el contenido del archivo binario input y escribe los datos codificados en base64 resultantes en el archivo output. input y output deben ser objetos archivos. input se leerá hasta que input.read() retorna un objeto de bytes vacío. encode() inserta un carácter de nueva línea (b'\n') después de cada 76 bytes de la salida, además de garantizar que la salida siempre termine con una nueva línea, según RFC 2045 [https://tools.ietf.org/html/rfc2045.html] (MIME).

base64.encodebytes(s)

Codifica el objeto similar a bytes s, que puede contener datos binarios arbitrarios, y retorna bytes que contienen los datos codificados en base64, con líneas nuevas (b'\n') insertado después de cada 76 bytes de salida, y asegurando que haya una nueva línea final, según RFC 2045 [https://tools.ietf.org/html/rfc2045.html] (MIME).

Nuevo en la versión 3.1.

Un ejemplo de uso del módulo:

>>> import base64
>>> encoded = base64.b64encode(b'data to be encoded')
>>> encoded
b'ZGF0YSB0byBiZSBlbmNvZGVk'
>>> data = base64.b64decode(encoded)
>>> data
b'data to be encoded'

Ver también

Módulo binascii

Módulo de soporte que contiene conversiones de ASCII a binario y binario a ASCII.

RFC 1521 [https://tools.ietf.org/html/rfc1521.html] - MIME (Extensiones multipropósito de correo de Internet) Parte uno: Mecanismos para especificar y describir el formato de los cuerpos de mensajes de Internet

La Sección 5.2, «Codificación de transferencia de contenido Base64», proporciona la definición de la codificación base64.

binhex — Codificar y decodificar archivos binhex4

Código fuente: Lib/binhex.py [https://github.com/python/cpython/tree/3.9/Lib/binhex.py]

Obsoleto desde la versión 3.9.

Este módulo codifica y descodifica archivos en formato binhex4, un formato que permite la representación de archivos Macintosh en ASCII. Solo se maneja «data fork».

El módulo binhex define las siguientes funciones:

binhex.binhex(input, output)

Convierta un archivo binario con nombre de archivo input a archivo binhex output. El parámetro output puede ser un nombre de archivo o un objeto similar a un archivo (cualquier objeto que admita un método write() y close()).

binhex.hexbin(input, output)

Descodificar un archivo binhex input. input puede ser un nombre de archivo o un objeto similar a un archivo que admita los métodos read() y close(). El archivo resultante se escribe en un archivo denominado output, a menos que el argumento sea None en cuyo caso el nombre de archivo de salida se lee desde el archivo binhex.

También se define la siguiente excepción:

exception binhex.Error

Excepción que se produce cuando algo no se puede codificar con el formato binhex (por ejemplo, un nombre de archivo demasiado largo para caber en el campo de nombre de archivo) o cuando la entrada no está codificada correctamente como datos binhex.

Ver también

Módulo binascii

Módulo de soporte que contiene conversiones ASCII a binario y de binario a ASCII.

Notas

Hay una interfaz alternativa más potente al codificador y decodificador, ver la fuente para más detalles.

Si codifica o decodifica ficheros de texto en plataformas no Macintosch, aún así se usará la antigua convención de nueva línea de Macintosh (retorno de carro al final de la línea).

binascii — Convertir entre binario y ASCII

El módulo binascii contiene una serie de métodos para convertir entre representaciones binarias y varias representaciones binarias codificadas en ASCII. Normalmente, usted no usará estas funciones directamente, en su lugar utilice módulos envoltorios (wrapper) como uu, base64, o binhex en su lugar. El módulo binascii contiene funciones de bajo nivel escritas en C para una mayor velocidad que son utilizadas por los módulos de nivel superior.

Nota

Las funciones a2b_* aceptan cadenas Unicode que contienen solo caracteres ASCII. Otras funciones solo aceptan objetos tipo binarios (como bytes, bytearray y otros objetos que admiten el protocolo de búfer).

Distinto en la versión 3.3: Las cadenas unicode con sólo caracteres ASCII son ahora aceptadas por las funciones a2b_*.

El módulo binascii define las siguientes funciones:

binascii.a2b_uu(string)

Convierte una sola línea de datos uuencoded de nuevo a binarios y retorna los datos binarios. Las líneas normalmente contienen 45 bytes (binarios), excepto por la última línea. Los datos de línea pueden ir seguidos de espacios en blanco.

binascii.b2a_uu(data, *, backtick=False)

Convierte datos binarios a una línea de caracteres ASCII, el valor retornado es la línea convertida, incluido un carácter de nueva línea. La longitud de data debe ser como máximo 45. Si backtick es verdadero, los ceros se representan mediante '`' en lugar de espacios.

Distinto en la versión 3.7: Se ha añadido el parámetro backtick.

binascii.a2b_base64(string)

Convierte un bloque de datos en base64 de nuevo a binario y retorna los datos binarios. Se puede pasar más de una línea a la vez.

binascii.b2a_base64(data, *, newline=True)

Convierte datos binarios en una línea de caracteres ASCII en codificación base64. El valor retornado es la línea convertida, incluido un carácter de nueva línea si newline es verdadero. La salida de esta función se ajusta a RFC 3548 [https://tools.ietf.org/html/rfc3548.html].

Distinto en la versión 3.6: Se ha añadido el parámetro newline.

binascii.a2b_qp(data, header=False)

Convierte un bloque de datos imprimibles entre comillas a binario y retorna los datos binarios. Se puede pasar más de una línea a la vez. Si el argumento opcional header está presente y es verdadero, los guiones bajos se decodificarán como espacios.

binascii.b2a_qp(data, quotetabs=False, istext=True, header=False)

Convierte datos binarios en una(s) línea(s) de caracteres ASCII en codificación imprimible entre comillas. El valor de retorno son las líneas convertidas. Si el argumento opcional quotetabs está presente y es verdadero, se codificarán todas los tabs y espacios. Si el argumento opcional istext está presente y es verdadero, las nuevas líneas no se codifican, pero se codificarán los espacios en blanco finales. Si el argumento opcional header está presente y es verdadero, los espacios se codificarán como guiones bajos por: rfc: 1522. Si el argumento opcional header está presente y es falso, los caracteres de nueva línea también se codificarán; de lo contrario, la conversión de salto de línea podría dañar el flujo de datos binarios.

binascii.a2b_hqx(string)

Convierte datos ASCII con formato binhex4 a binario, sin descomprimir RLE. La cadena debe contener un número completo de bytes binarios o (en el caso de la última porción de los datos binhex4) tener los bits restantes cero.

Obsoleto desde la versión 3.9.

binascii.rledecode_hqx(data)

Realiza descompresión RLE en los datos, según el estándar binhex4. El algoritmo usa 0x90 después de un byte como indicador de repetición, seguido de un conteo. Un recuento de 0 especifica un valor de byte de 0x90. La rutina retorna los datos descomprimidos, a menos que los datos de entrada de datos terminen en un indicador de repetición huérfano, en cuyo caso se genera la excepción Incomplete.

Distinto en la versión 3.2: Acepta solo objetos bytestring o bytearray como entrada.

Obsoleto desde la versión 3.9.

binascii.rlecode_hqx(data)

Realiza la compresión RLE de estilo binhex4 en data y retorna el resultado.

Obsoleto desde la versión 3.9.

binascii.b2a_hqx(data)

Realiza la traducción de binario hexbin4 a ASCII y retorna la cadena resultante. El argumento ya debe estar codificado en RLE y tener una longitud divisible por 3 (excepto posiblemente por el último fragmento).

Obsoleto desde la versión 3.9.

binascii.crc_hqx(data, value)

Calcula un valor CRC de 16 bits de data, comenzando con value como el CRC inicial, y retorna el resultado. Utiliza el polinomio CRC-CCITT x¹⁶ + x¹² + x⁵ + 1, a menudo representado como 0x1021. Este CRC se utiliza en el formato binhex4.

binascii.crc32(data[, value])

Compute CRC-32, the unsigned 32-bit checksum of data, starting with an initial CRC of value. The default initial CRC is zero. The algorithm is consistent with the ZIP file checksum. Since the algorithm is designed for use as a checksum algorithm, it is not suitable for use as a general hash algorithm. Use as follows:

print(binascii.crc32(b"hello world"))
# Or, in two pieces:
crc = binascii.crc32(b"hello")
crc = binascii.crc32(b" world", crc)
print('crc32 = {:#010x}'.format(crc))

Distinto en la versión 3.0: The result is always unsigned. To generate the same numeric value when using Python 2 or earlier, use crc32(data) & 0xffffffff.

binascii.b2a_hex(data[, sep[, bytes_per_sep=1]])

binascii.hexlify(data[, sep[, bytes_per_sep=1]])

Retorna la representación hexadecimal del binario data. Cada byte de data se convierte en la representación hexadecimal de 2 dígitos correspondiente. Por lo tanto, el objeto de bytes retornado es el doble de largo que la longitud de data.

Una funcionalidad similar (pero que retorna una cadena de texto) también es convenientemente accesible usando el método bytes.hex().

Si se especifica sep, debe ser un solo carácter str o un objeto de bytes. Se insertará en la salida después de cada bytes_per_sep bytes de entrada . La ubicación del separador se cuenta desde el extremo derecho de la salida de forma predeterminada; si desea contar desde el izquierdo, proporcione un valor negativo bytes_per_sep.

>>> import binascii
>>> binascii.b2a_hex(b'\xb9\x01\xef')
b'b901ef'
>>> binascii.hexlify(b'\xb9\x01\xef', '-')
b'b9-01-ef'
>>> binascii.b2a_hex(b'\xb9\x01\xef', b'_', 2)
b'b9_01ef'
>>> binascii.b2a_hex(b'\xb9\x01\xef', b' ', -2)
b'b901 ef'

Distinto en la versión 3.8: Se agregaron los parámetros sep y bytes_per_sep.

binascii.a2b_hex(hexstr)

binascii.unhexlify(hexstr)

Retorna los datos binarios representados por la cadena hexadecimal hexstr. Esta función es la inversa de b2a_hex(). hexstr debe contener un número par de dígitos hexadecimales (que pueden ser mayúsculas o minúsculas), de lo contrario se produce una excepción Error.

Funcionalidad similar (aceptar sólo argumentos de cadena de texto, pero más liberal hacia espacios en blanco) también es accesible mediante el método de clase bytes.fromhex().

exception binascii.Error

Excepción provocada por errores. Estos suelen ser errores de programación.

exception binascii.Incomplete

Excepción provocada por datos incompletos. Por lo general, estos no son errores de programación, pero se pueden controlar leyendo un poco más de datos e intentándolo de nuevo.

Ver también

Módulo base64

Soporte para compatibilidad con RFC de codificación de estilo base64 en base 16, 32, 64 y 85.

Módulo binhex

Soporte para el formato binhex utilizado en Macintosh.

Módulo uu

Soporte para codificación UU usada en Unix.

Módulo quopri

Soporte para codificación imprimible entre comillas utilizada en mensajes de correo electrónico MIME.

quopri — Codificar y decodificar datos MIME imprimibles entre comillas

Código fuente: Lib/quopri.py [https://github.com/python/cpython/tree/3.9/Lib/quopri.py]

Este módulo realiza la codificación y descodificación de transporte imprimible entre comillas, tal como se define en RFC 1521 [https://tools.ietf.org/html/rfc1521.html]: «MIME (Multipurpose Internet Mail Extensions) Parte Uno: Mecanismos para especificar y describir el formato de los cuerpos de mensajes de Internet». La codificación imprimible entre comillas está diseñada para datos donde hay relativamente pocos caracteres no imprimibles; el esquema de codificación base64 disponible a través del módulo base64 es más compacto si hay muchos caracteres de este tipo, como cuando se envía un archivo gráfico.

quopri.decode(input, output, header=False)

Descodificar el contenido del archivo input y escribir los datos binarios descodificados resultantes en el archivo output. input y output deben ser objetos de archivo binario. Si el argumento opcional header está presente y true, el carácter de subrayado se descodificará como espacio. Esto se utiliza para decodificar encabezados codificados en «Q» como se describe en RFC 1522 [https://tools.ietf.org/html/rfc1522.html]: «MIME (Multipurpose Internet Mail Extensions) Parte dos: Extensiones de encabezado de mensaje para texto no ASCII».

quopri.encode(input, output, quotetabs, header=False)

Codifique el contenido del archivo input y escriba los datos imprimibles entre comillas resultantes en el archivo output. input y output deben ser objetos de archivo binario. quotetabs, un indicador no opcional que controla si codificar espacios incrustados y pestañas; cuando true codifica dicho espacio en blanco incrustado, y cuando false los deja sin codificar. Tenga en cuenta que los espacios y pestañas que aparecen al final de las líneas siempre están codificados, según RFC 1521 [https://tools.ietf.org/html/rfc1521.html]. header es un indicador que controla si los espacios están codificados como guiones bajos según RFC 1522 [https://tools.ietf.org/html/rfc1522.html].

quopri.decodestring(s, header=False)

Como decode(), excepto que acepta una fuente bytes y retorna el correspondiente bytes decodificado.

quopri.encodestring(s, quotetabs=False, header=False)

Como encode(), excepto que acepta un origen bytes y retorna el codificado correspondiente bytes. De forma predeterminada, envía un valor False al parámetro quotetabs de la función encode().

Ver también

Módulo base64

Codificar y decodificar datos MIME base64

Herramientas Para Procesar Formatos de Marcado Estructurado

Python soporta una variedad de módulos para trabajar con varias formas de almacenar datos de forma estructurada. Esto incluye módulos para trabajar con el Lenguaje de Marcado Estructurado General (SGML) y el Lenguaje de de Marcado de Hipertexto (HTML), y varias interfaces para trabajar con el Lenguaje de Marcado Estructurado Extensible (XML).

html — Compatibilidad con el Lenguaje de marcado de hipertexto

html.parser — Analizador simple de HTML y XHTML

Aplicación ejemplo de un analizador sintáctico (parser) de HTML

Métodos HTMLParser

Ejemplos

html.entities — Definiciones de entidades generales HTML

Módulos de procesamiento XML

Vulnerabilidades XML

El paquete defusedxml

xml.etree.ElementTree — La API XML de ElementTree

Tutorial

Árbol y elementos XML

Procesando XML

API de consulta para un procesamiento no bloqueante

Encontrando elementos interesantes

Modificando un archivo XML

Construyendo documentos XML

Procesando XML con espacio de nombres

Soporte de XPath

Ejemplo

Sintaxis XPath soportada

Referencia

Funciones

Soporte de XInclude

Ejemplo

Referencia

Funciones

Objetos Element

Objetos ElementTree

Objetos QName

Objetos TreeBuilder

Objetos XMLParser

Objetos XMLPullParser

Excepciones

xml.dom — El API del Modelo de Objetos del Documento

Contenido del Módulo

Objetos en el DOM

Objetos DOMImplementation

Objetos Nodo

Objetos NodeList

Objetos DocumentType

Objetos Documento

Objetos Elemento

Objetos Atributo

Objetos NamedNodeMap

Objetos Comentario

Objetos Texto y CDATASection

Objetos ProcessingInstruction

Excepciones

Conformidad

Mapeo de tipos

Métodos de acceso (accessor)

xml.dom.minidom — Implementación mínima del DOM

Objetos del DOM

Ejemplo de DOM

minidom y el estándar DOM

xml.dom.pulldom — Soporte para la construcción parcial de árboles DOM

Objetos DOMEventStream

XML.sax— Soporte para analizadores SAX2

Objetos SAXException

xml.sax.handler — Clases base para los handlers SAX

Objetos ContentHandler

Objetos DTDHandler

Objetos EntityResolver

Objetos ErrorHandler

xml.sax.saxutils — Utilidades SAX

xml.sax.xmlreader — Interfaz para analizadores XML

Objetos XMLReader

Objetos IncrementalParser

Objetos localizadores

Objetos InputSource

La Interfaz Attributes

La Interfaz AttributesNS

xml.parsers.expat — Análisis rápido XML usando Expat

Objetos XMLParser

Excepciones de ExpatError

Ejemplo

Descripciones del modelo de contenido

Constantes de error de expansión

html — Compatibilidad con el Lenguaje de marcado de hipertexto

Código fuente: Lib/html/__init__.py [https://github.com/python/cpython/tree/3.9/Lib/html/__init__.py]

Este módulo define utilidades para manipular HTML.

html.escape(s, quote=True)

Convierte los caracteres &, < y > de la cadena de caracteres s en secuencias seguras HTML. Utilízalo si necesitas mostrar texto que pueda contener tales caracteres en HTML. Si el flag opcional quote es true, también se traducen los caracteres (") y ('); esto ayuda a la inserción en el valor de un atributo HTML delimitado por comillas, como en <a href="...">.

Nuevo en la versión 3.2.

html.unescape(s)

Convierte todas las referencias de caracteres numéricos y con nombre (por ejemplo &gt;, &#62;, &#x3e;) de la cadena de caracteres s a los caracteres Unicode correspondientes. Esta función utiliza las reglas definidas por el estándar HTML 5 para las referencias de caracteres válidas e inválidas, y la lista de referencia de caracteres con nombre de HTML 5.

Nuevo en la versión 3.4.

Los submódulos del paquete html son:

html.parser – Analizador sintáctico simple de HTML y XHTML

html.entities – Definición general de entidades HTML

html.parser — Analizador simple de HTML y XHTML

Código fuente: Lib/html/parser.py [https://github.com/python/cpython/tree/3.9/Lib/html/parser.py]

Este módulo define una clase HTMLParser que sirve como base para analizar archivos de texto formateados en HTML (HyperText Mark-up Language) y XHTML.

class html.parser.HTMLParser(*, convert_charrefs=True)

Cree una instancia de analizador capaz de analizar marcado no válido.

Si convert_charrefs es True (el valor predeterminado), todas las referencias de caracteres (excepto las de los elementos script/style) se convierten automáticamente en los caracteres Unicode correspondientes.

Una instancia de HTMLParser se alimenta de datos HTML y llama a métodos de manejo cuando se encuentran etiquetas de inicio, etiquetas finales, texto, comentarios y otros elementos de marcado. El usuario debe subclasificar HTMLParser y anular sus métodos para implementar el comportamiento deseado.

Este analizador no verifica que las etiquetas finales coincidan con las etiquetas iniciales ni llame al manejador de etiquetas finales para los elementos que se cierran implícitamente al cerrar un elemento externo.

Distinto en la versión 3.4: argumento de palabra clave convert_charrefs agregado.

Distinto en la versión 3.5: El valor predeterminado para el argumento convert_charrefs ahora es True.

Aplicación ejemplo de un analizador sintáctico (parser) de HTML

Como ejemplo básico, a continuación hay un analizador HTML simple que usa la clase HTMLParser para imprimir etiquetas de inicio, etiquetas finales y datos a medida que se encuentran:

from html.parser import HTMLParser

class MyHTMLParser(HTMLParser):
    def handle_starttag(self, tag, attrs):
        print("Encountered a start tag:", tag)

    def handle_endtag(self, tag):
        print("Encountered an end tag :", tag)

    def handle_data(self, data):
        print("Encountered some data  :", data)

parser = MyHTMLParser()
parser.feed('<html><head><title>Test</title></head>'
            '<body><h1>Parse me!</h1></body></html>')

La salida será entonces:

Encountered a start tag: html
Encountered a start tag: head
Encountered a start tag: title
Encountered some data  : Test
Encountered an end tag : title
Encountered an end tag : head
Encountered a start tag: body
Encountered a start tag: h1
Encountered some data  : Parse me!
Encountered an end tag : h1
Encountered an end tag : body
Encountered an end tag : html

Métodos HTMLParser

instancias de HTMLParser tienen los siguientes métodos:

HTMLParser.feed(data)

Alimente un poco de texto al analizador. Se procesa en la medida en que consta de elementos completos; los datos incompletos se almacenan en el búfer hasta que se introducen más datos o se llama a close(). data debe ser str.

HTMLParser.close()

Fuerce el procesamiento de todos los datos almacenados como si fueran seguidos por una marca de fin de archivo. Este método puede ser redefinido por una clase derivada para definir un procesamiento adicional al final de la entrada, pero la versión redefinida siempre debe llamar a HTMLParser método de clase base close().

HTMLParser.reset()

Restablecer la instancia. Pierde todos los datos no procesados. Esto se llama implícitamente en el momento de la instanciación.

HTMLParser.getpos()

Retorna el número de línea actual y el desplazamiento.

HTMLParser.get_starttag_text()

Retorna el texto de la etiqueta de inicio abierta más recientemente. Normalmente, esto no debería ser necesario para el procesamiento estructurado, pero puede ser útil para tratar con HTML «como implementado» o para volver a generar entradas con cambios mínimos (se puede preservar el espacio en blanco entre los atributos, etc.).

Los siguientes métodos se invocan cuando se encuentran datos o elementos de marcado y deben anularse en una subclase. Las implementaciones de la clase base no hacen nada (excepto handle_startendtag()):

HTMLParser.handle_starttag(tag, attrs)

This method is called to handle the start tag of an element (e.g. <div id="main">).

El argumento tag es el nombre de la etiqueta convertida a minúsculas. El argumento attrs es una lista de pares (nombre, valor) que contienen los atributos encontrados dentro de los corchetes <> de la etiqueta. El name se traducirá a minúsculas, se eliminarán las comillas en el value y se reemplazarán las referencias de caracteres y entidades.

Por ejemplo, para la etiqueta <A HREF="https://www.cwi.nl/">, este método se llamaría como handle_starttag('a', [('href', 'https : //www.cwi.nl/ ')]).

Todas las referencias de entidad de html.entities se reemplazan en los valores de los atributos.

HTMLParser.handle_endtag(tag)

Este método se llama para manejar la etiqueta final de un elemento (por ejemplo, </div>)

El argumento tag es el nombre de la etiqueta convertida a minúsculas.

HTMLParser.handle_startendtag(tag, attrs)

Similar a handle_starttag(), pero llamado cuando el analizador encuentra una etiqueta vacía de estilo XHTML (<img .../>). Este método puede ser anulado por subclases que requieren esta información léxica particular; la implementación predeterminada simplemente llama handle_starttag() y handle_endtag().

HTMLParser.handle_data(data)

Este método se llama para procesar datos arbitrarios (por ejemplo, nodos de texto y el contenido de <script>...</script> y <style>...</style>).

HTMLParser.handle_entityref(name)

Este método se llama para procesar una referencia de caracteres con nombre del formulario &name; (por ejemplo, &gt;), donde name es una referencia de entidad general (por ejemplo, 'gt'). Este método nunca se llama si convert_charrefs es True.

HTMLParser.handle_charref(name)

Este método se llama para procesar referencias de caracteres numéricos decimales y hexadecimales de la forma &#NNN; y &#xNNN;. Por ejemplo, el equivalente decimal para &gt; es &#62;, mientras que el hexadecimal es &#x3E;; en este caso, el método recibirá '62' o 'x3E'. Este método nunca se llama si convert_charrefs es True.

HTMLParser.handle_comment(data)

Este método se llama cuando se encuentra un comentario (por ejemplo, <!--comment-->).

Por ejemplo, el comentario <! - comment -> hará que se llame a este método con el argumento 'comment'.

El contenido de los comentarios condicionales de Internet Explorer (condcoms) también se enviará a este método, por lo tanto, para <!--[if IE 9]>IE9-specific content<![endif]-->, este método recibirá '[if IE 9]>IE9-specific content<![endif]'.

HTMLParser.handle_decl(decl)

Este método se llama para manejar una declaración de tipo de documento HTML (por ejemplo, <!DOCTYPE html>).

El parámetro decl será todo el contenido de la declaración dentro del <!...> markup (por ejemplo, 'DOCTYPE html').

HTMLParser.handle_pi(data)

Método llamado cuando se encuentra una instrucción de procesamiento. El parámetro data contendrá toda la instrucción de procesamiento. Por ejemplo, para la instrucción de procesamiento <?proc color='red'>, este método se llamaría como handle_pi("proc color='red'"). Está destinado a ser anulado por una clase derivada; La implementación de la clase base no hace nada.

Nota

La clase HTMLParser utiliza las reglas sintácticas SGML para procesar instrucciones. Una instrucción de procesamiento XHTML que use el '?' final hará que se incluya el '?' en data.

HTMLParser.unknown_decl(data)

Se llama a este método cuando el analizador lee una declaración no reconocida.

El parámetro data será el contenido completo de la declaración dentro del marcado <! [...]>. A veces es útil ser reemplazado por una clase derivada. La implementación de la clase base no hace nada.

Ejemplos

La siguiente clase implementa un analizador que se utilizará para ilustrar más ejemplos:

from html.parser import HTMLParser
from html.entities import name2codepoint

class MyHTMLParser(HTMLParser):
    def handle_starttag(self, tag, attrs):
        print("Start tag:", tag)
        for attr in attrs:
            print("     attr:", attr)

    def handle_endtag(self, tag):
        print("End tag  :", tag)

    def handle_data(self, data):
        print("Data     :", data)

    def handle_comment(self, data):
        print("Comment  :", data)

    def handle_entityref(self, name):
        c = chr(name2codepoint[name])
        print("Named ent:", c)

    def handle_charref(self, name):
        if name.startswith('x'):
            c = chr(int(name[1:], 16))
        else:
            c = chr(int(name))
        print("Num ent  :", c)

    def handle_decl(self, data):
        print("Decl     :", data)

parser = MyHTMLParser()

Analizando un doctype:

>>> parser.feed('<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" '
...             '"http://www.w3.org/TR/html4/strict.dtd">')
Decl     : DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"

Analizando un elemento con algunos atributos y un título:

>>> parser.feed('<img src="python-logo.png" alt="The Python logo">')
Start tag: img
     attr: ('src', 'python-logo.png')
     attr: ('alt', 'The Python logo')
>>>
>>> parser.feed('<h1>Python</h1>')
Start tag: h1
Data     : Python
End tag  : h1

El contenido de los elementos script y style se retorna tal cual, sin más análisis

>>> parser.feed('<style type="text/css">#python { color: green }</style>')
Start tag: style
     attr: ('type', 'text/css')
Data     : #python { color: green }
End tag  : style

>>> parser.feed('<script type="text/javascript">'
...             'alert("<strong>hello!</strong>");</script>')
Start tag: script
     attr: ('type', 'text/javascript')
Data     : alert("<strong>hello!</strong>");
End tag  : script

Analizando comentarios:

>>> parser.feed('<!-- a comment -->'
...             '<!--[if IE 9]>IE-specific content<![endif]-->')
Comment  :  a comment
Comment  : [if IE 9]>IE-specific content<![endif]

Analizar referencias de caracteres con nombre y numéricos y convertirlos al carácter correcto (nota: estas 3 referencias son todas equivalentes a '>'):

>>> parser.feed('&gt;&#62;&#x3E;')
Named ent: >
Num ent  : >
Num ent  : >

La alimentación de fragmentos incompletos a feed() funciona, pero handle_data() podría llamarse más de una vez (a menos que convert_charrefs esté configurado como True):

>>> for chunk in ['<sp', 'an>buff', 'ered ', 'text</s', 'pan>']:
...     parser.feed(chunk)
...
Start tag: span
Data     : buff
Data     : ered
Data     : text
End tag  : span

Analizar HTML no válido (por ejemplo, atributos sin comillas) también funciona:

>>> parser.feed('<p><a class=link href=#main>tag soup</p ></a>')
Start tag: p
Start tag: a
     attr: ('class', 'link')
     attr: ('href', '#main')
Data     : tag soup
End tag  : p
End tag  : a

html.entities — Definiciones de entidades generales HTML

Código fuente: Lib/html/entities.py [https://github.com/python/cpython/tree/3.9/Lib/html/entities.py]

Este módulo define cuatro diccionarios html5, name2codepoint, codepoint2name, y entitydefs

html.entities.html5

Un diccionario que asigna referencias de caracteres con nombre HTML5 1 a los caracteres Unicode equivalentes, p. Ej. html5['gt;'] == '>'. Tenga en cuenta que el punto y coma al final está incluido en el nombre (por ejemplo, 'gt;'), sin embargo, algunos de los nombres son aceptados por el estándar incluso sin el punto y coma: en este caso, el nombre está presente con y sin el ';'. Consulte también html.unescape().

Nuevo en la versión 3.3.

html.entities.entitydefs

Un diccionario que asigna definiciones de entidad XHTML 1.0 a su texto de reemplazo en ISO Latin-1.

html.entities.name2codepoint

Un diccionario que asigna nombres de entidades HTML a los puntos de código Unicode.

html.entities.codepoint2name

Un diccionario que asigna puntos de código Unicode a nombres de entidades HTML.

Notas al pie

1

See https://html.spec.whatwg.org/multipage/syntax.html#named-character-references

Módulos de procesamiento XML

Código fuente: Lib/xml/ [https://github.com/python/cpython/tree/3.9/Lib/xml/]

Las interfaces de Python para procesar XML están agrupadas en el paquete xml.

Advertencia

Los módulos XML no son seguros contra datos construidos errónea o maliciosamente. Si necesita analizar datos que no son de confianza o no autenticados, consulte las secciones Vulnerabilidades XML y El paquete defusedxml.

Es importante tener en cuenta que los módulos del paquete xml requieren que haya al menos un analizador XML compatible con SAX disponible. El analizador Expat se incluye con Python, por lo que el módulo xml.parsers.expat siempre estará disponible.

La documentación de los paquetes xml.dom y xml.sax es la definición de los enlaces de Python para las interfaces DOM y SAX.

Los submódulos de manejo de XML son:

xml.etree.ElementTree: la API ElementTree, un procesador de XML simple y ligero

xml.dom: la definición de la API DOM

xml.dom.minidom: una implementación mínima de DOM

xml.dom.pulldom: soporte para la construcción de árboles DOM parciales

xml.sax: clases base SAX2 y funciones de conveniencia

xml.parsers.expat: el enlace del analizador Expat

Vulnerabilidades XML

Los módulos de procesamiento XML no son seguros contra datos construidos malintencionadamente. Un atacante puede abusar de las características XML para llevar a cabo ataques de denegación de servicio, acceder a archivos locales, generar conexiones de red a otras máquinas o eludir firewalls.

En la tabla siguiente se ofrece una visión general de los ataques conocidos y si los distintos módulos son vulnerables a ellos.

tipo

sax

etree

minidom

pulldom

xmlrpc

mil millones de risas

Vulnerable (1)

Vulnerable (1)

Vulnerable (1)

Vulnerable (1)

Vulnerable (1)

explosión cuadrática

Vulnerable (1)

Vulnerable (1)

Vulnerable (1)

Vulnerable (1)

Vulnerable (1)

expansión de entidad externa

Safe (5)

Safe (2)

Safe (3)

Safe (5)

Seguro (4)

Recuperación de DTD [https://en.wikipedia.org/wiki/Document_type_definition]

Safe (5)

Seguro

Seguro

Safe (5)

Seguro

bomba de descompresión

Seguro

Seguro

Seguro

Seguro

Vulnerable

Expat 2.4.1 and newer is not vulnerable to the «billion laughs» and «quadratic blowup» vulnerabilities. Items still listed as vulnerable due to potential reliance on system-provided libraries. Check pyexpat.EXPAT_VERSION.

xml.etree.ElementTree no expande entidades externas y lanza un ParserError cuando se produce una entidad.

xml.dom.minidom no expande entidades externas y simplemente retorna la entidad no expandida literalmente.

xmlrpclib no expande entidades externas y las omite.

Desde Python 3.7.1, las entidades generales externas ya no se procesan de forma predeterminada.

mil millones de risas / expansión exponencial de entidad

El ataque Billion Laughs [https://en.wikipedia.org/wiki/Billion_laughs], también conocido como expansión exponencial de entidades, utiliza varios niveles de entidades anidadas. Cada entidad hace referencia a otra entidad varias veces y la definición de entidad final contiene una cadena pequeña. La expansión exponencial da como resultado varios gigabytes de texto y consume mucha memoria y tiempo de CPU.

expansión de entidad de explosión cuadrática

Un ataque de explosión cuadrática es similar a un ataque de Billion Laughs [https://en.wikipedia.org/wiki/Billion_laughs]; también abusa de la expansión de entidad. En lugar de entidades anidadas, repite una entidad grande con un par de miles de caracteres una y otra vez. El ataque no es tan eficaz como el caso exponencial, pero evita desencadenar contramedidas del analizador que prohíben entidades profundamente anidadas.

expansión de entidad externa

Las declaraciones de entidad pueden contener algo más que texto para su reemplazo. También pueden apuntar a recursos externos o archivos locales. El analizador XML tiene acceso al recurso e incrusta el contenido en el documento XML.

Recuperación de DTD [https://en.wikipedia.org/wiki/Document_type_definition]

Algunas bibliotecas XML como xml.dom.pulldom de Python recuperan definiciones de tipo de documento de ubicaciones remotas o locales. La característica tiene implicaciones similares a las del problema de expansión de entidades externas.

bomba de descompresión

Las bombas de descompresión (también conocidas como ZIP bomb [https://en.wikipedia.org/wiki/Zip_bomb]) se aplican a todas las bibliotecas XML que pueden analizar secuencias XML comprimidas, como secuencias HTTP comprimidas con gzip o archivos comprimidos por LZMA. Para un atacante puede reducir la cantidad de datos transmitidos en magnitudes de tres o más.

La documentación de defusedxml [https://pypi.org/project/defusedxml/] en PyPI tiene más información sobre todos los vectores de ataque conocidos con ejemplos y referencias.

El paquete defusedxml

defusedxml [https://pypi.org/project/defusedxml/] es un paquete Python puro con subclases modificadas de todos los analizadores XML stdlib que impiden cualquier operación potencialmente malintencionada. Se recomienda el uso de este paquete para cualquier código de servidor que analice datos XML que no sean de confianza. El paquete también incluye ataques de ejemplo y documentación ampliada sobre más vulnerabilidades XML, como la inyección de XPath.

xml.etree.ElementTree — La API XML de ElementTree

Código fuente: Lib/xml/etree/ElementTree.py [https://github.com/python/cpython/tree/3.9/Lib/xml/etree/ElementTree.py]

El módulo xml.etree.ElementTree implementa una API simple y eficiente para parsear y crear datos XML.

Distinto en la versión 3.3: Este módulo utilizará una implementación rápida siempre que esté disponible.

Obsoleto desde la versión 3.3: El módulo xml.etree.cElementTree es obsoleto.

Advertencia

El módulo xml.etree.ElementTree no es seguro contra datos construidos maliciosamente. Si necesita parsear datos no fiables o no autentificados, vea Vulnerabilidades XML.

Tutorial

Este es un tutorial corto para usar xml.etree.ElementTree (ET en resumen). El objetivo es demostrar algunos de los componentes y conceptos básicos del módulo.

Árbol y elementos XML

XML es un formato de datos inherentemente jerárquico, y la forma más natural de representarlo es con un árbol. ET tiene dos clases para este propósito - ElementTree representa todo el documento XML como un árbol, y Element representa un solo nodo en este árbol. Las interacciones con todo el documento (leer y escribir en/desde archivos) se realizan normalmente en el nivel de ElementTree. Las interacciones con un solo elemento XML y sus sub-elementos se realizan en el nivel Element.

Procesando XML

Usaremos el siguiente documento XML como los datos de muestra para esta sección:

<?xml version="1.0"?>
<data>
    <country name="Liechtenstein">
        <rank>1</rank>
        <year>2008</year>
        <gdppc>141100</gdppc>
        <neighbor name="Austria" direction="E"/>
        <neighbor name="Switzerland" direction="W"/>
    </country>
    <country name="Singapore">
        <rank>4</rank>
        <year>2011</year>
        <gdppc>59900</gdppc>
        <neighbor name="Malaysia" direction="N"/>
    </country>
    <country name="Panama">
        <rank>68</rank>
        <year>2011</year>
        <gdppc>13600</gdppc>
        <neighbor name="Costa Rica" direction="W"/>
        <neighbor name="Colombia" direction="E"/>
    </country>
</data>

Podemos importar estos datos leyendo desde un archivo:

import xml.etree.ElementTree as ET
tree = ET.parse('country_data.xml')
root = tree.getroot()

O directamente desde una cadena de caracteres:

root = ET.fromstring(country_data_as_string)

fromstring() analiza el XML de una cadena de caracteres directamente en un Element, que es el elemento raíz del árbol analizado. Otras funciones de análisis pueden crear un ElementTree. Compruebe la documentación para estar seguro.

Como un Element, root tiene una etiqueta y un diccionario de atributos:

>>> root.tag
'data'
>>> root.attrib
{}

También tiene nodos hijos sobre los cuales podemos iterar:

>>> for child in root:
...     print(child.tag, child.attrib)
...
country {'name': 'Liechtenstein'}
country {'name': 'Singapore'}
country {'name': 'Panama'}

Los hijos están anidados, y podemos acceder a nodos hijos específicos por el índice:

>>> root[0][1].text
'2008'

Nota

No todos los elementos de la entrada XML acabarán siendo elementos del árbol analizado. Actualmente, este módulo omite cualquier comentario XML, instrucciones de procesamiento y declaraciones de tipo documento en la entrada. Sin embargo, los árboles construidos utilizando la API de este módulo, en lugar de analizar el texto XML, pueden contener comentarios e instrucciones de procesamiento, que se incluirán al generar la salida XML. Se puede acceder a una declaración de tipo documento pasando una instancia TreeBuilder personalizada al constructor XMLParser.

API de consulta para un procesamiento no bloqueante

La mayoría de las funciones de análisis proporcionadas por este módulo requieren que se lea todo el documento a la vez antes de retornar cualquier resultado. Es posible utilizar un XMLParser y alimentar los datos en él de forma incremental, pero se trata de una push API que llama a métodos en un objetivo invocable, que es demasiado bajo nivel e inconveniente para la mayoría de las necesidades. A veces, lo que el usuario realmente quiere es ser capaz de analizar XML de forma incremental, sin bloquear las operaciones, mientras disfruta de la comodidad de los objetos Element totalmente construidos.

La herramienta más potente para hacer esto es XMLPullParser. No requiere una lectura de bloqueo para obtener los datos XML, y en su lugar se alimenta de datos de forma incremental con llamadas a XMLPullParser.feed(). Para obtener los elementos XML analizados, llama a XMLPullParser.read_events(). He aquí un ejemplo:

>>> parser = ET.XMLPullParser(['start', 'end'])
>>> parser.feed('<mytag>sometext')
>>> list(parser.read_events())
[('start', <Element 'mytag' at 0x7fa66db2be58>)]
>>> parser.feed(' more text</mytag>')
>>> for event, elem in parser.read_events():
...     print(event)
...     print(elem.tag, 'text=', elem.text)
...
end

El caso de uso obvio es el de las aplicaciones que operan de forma no bloqueante, donde los datos XML se reciben de un socket o se leen de forma incremental desde algún dispositivo de almacenamiento. En estos casos, las lecturas bloqueantes son inaceptables.

Debido a su flexibilidad, XMLPullParser puede ser un inconveniente para los casos de uso más simples. Si no te importa que tu aplicación se bloquee en la lectura de datos XML pero te gustaría tener capacidades de análisis incremental, echa un vistazo a iterparse(). Puede ser útil cuando estás leyendo un documento XML grande y no quieres mantenerlo completamente en memoria.

Encontrando elementos interesantes

Element tiene algunos métodos útiles que ayudan a iterar recursivamente sobre todo el sub-árbol por debajo de él (sus hijos, los hijos de sus hijos, y así sucesivamente). Por ejemplo, Element.iter():

>>> for neighbor in root.iter('neighbor'):
...     print(neighbor.attrib)
...
{'name': 'Austria', 'direction': 'E'}
{'name': 'Switzerland', 'direction': 'W'}
{'name': 'Malaysia', 'direction': 'N'}
{'name': 'Costa Rica', 'direction': 'W'}
{'name': 'Colombia', 'direction': 'E'}

Element.findall() encuentra sólo los elementos con una etiqueta que son hijos directos del elemento actual. Element.find() encuentra el primer hijo con una etiqueta determinada, y Element.text accede al contenido de texto del elemento. Element.get() accede a los atributos del elemento:

>>> for country in root.findall('country'):
...     rank = country.find('rank').text
...     name = country.get('name')
...     print(name, rank)
...
Liechtenstein 1
Singapore 4
Panama 68

Es posible especificar de forma más sofisticada qué elementos buscar utilizando XPath.

Modificando un archivo XML

ElementTree proporciona una forma sencilla de construir documentos XML y escribirlos en archivos. El método ElementTree.write() sirve para este propósito.

Una vez creado, un objeto Element puede ser manipulado cambiando directamente sus campos (como Element.text), añadiendo y modificando atributos (método Element.set()), así como añadiendo nuevos hijos (por ejemplo con Element.append()).

Digamos que queremos añadir uno al rango de cada país, y añadir un atributo updated al elemento rango:

>>> for rank in root.iter('rank'):
...     new_rank = int(rank.text) + 1
...     rank.text = str(new_rank)
...     rank.set('updated', 'yes')
...
>>> tree.write('output.xml')

Nuestro XML tiene ahora este aspecto:

<?xml version="1.0"?>
<data>
    <country name="Liechtenstein">
        <rank updated="yes">2</rank>
        <year>2008</year>
        <gdppc>141100</gdppc>
        <neighbor name="Austria" direction="E"/>
        <neighbor name="Switzerland" direction="W"/>
    </country>
    <country name="Singapore">
        <rank updated="yes">5</rank>
        <year>2011</year>
        <gdppc>59900</gdppc>
        <neighbor name="Malaysia" direction="N"/>
    </country>
    <country name="Panama">
        <rank updated="yes">69</rank>
        <year>2011</year>
        <gdppc>13600</gdppc>
        <neighbor name="Costa Rica" direction="W"/>
        <neighbor name="Colombia" direction="E"/>
    </country>
</data>

Podemos eliminar elementos utilizando Element.remove(). Digamos que queremos eliminar todos los países con un rango superior a 50:

>>> for country in root.findall('country'):
...     # using root.findall() to avoid removal during traversal
...     rank = int(country.find('rank').text)
...     if rank > 50:
...         root.remove(country)
...
>>> tree.write('output.xml')

Tenga en cuenta que la modificación concurrente mientras se itera puede conducir a problemas, al igual que cuando se itera y modifica listas o diccionarios de Python. Por lo tanto, el ejemplo recoge primero todos los elementos coincidentes con root.findall(), y sólo entonces itera sobre la lista de coincidencias.

Nuestro XML tiene ahora este aspecto:

<?xml version="1.0"?>
<data>
    <country name="Liechtenstein">
        <rank updated="yes">2</rank>
        <year>2008</year>
        <gdppc>141100</gdppc>
        <neighbor name="Austria" direction="E"/>
        <neighbor name="Switzerland" direction="W"/>
    </country>
    <country name="Singapore">
        <rank updated="yes">5</rank>
        <year>2011</year>
        <gdppc>59900</gdppc>
        <neighbor name="Malaysia" direction="N"/>
    </country>
</data>

Construyendo documentos XML

La función SubElement() también proporciona una forma cómoda de crear nuevos sub-elementos para un elemento dado:

>>> a = ET.Element('a')
>>> b = ET.SubElement(a, 'b')
>>> c = ET.SubElement(a, 'c')
>>> d = ET.SubElement(c, 'd')
>>> ET.dump(a)
<a><b /><c><d /></c></a>

Procesando XML con espacio de nombres

Si la entrada XML tiene espacio de nombres [https://es.wikipedia.org/wiki/Espacio_de_nombres_XML], las etiquetas y los atributos con prefijos de la forma prefix:sometag se expanden a {uri}sometag donde el prefix se sustituye por el URI completo. Además, si hay un espacio de nombre por defecto [https://www.w3.org/TR/xml-names/#defaulting], ese URI completo se antepone a todas las etiquetas sin prefijo.

A continuación se muestra un ejemplo de XML que incorpora dos espacios de nombres, uno con el prefijo «fictional» y el otro que sirve como espacio de nombres por defecto:

<?xml version="1.0"?>
<actors xmlns:fictional="http://characters.example.com"
        xmlns="http://people.example.com">
    <actor>
        <name>John Cleese</name>
        <fictional:character>Lancelot</fictional:character>
        <fictional:character>Archie Leach</fictional:character>
    </actor>
    <actor>
        <name>Eric Idle</name>
        <fictional:character>Sir Robin</fictional:character>
        <fictional:character>Gunther</fictional:character>
        <fictional:character>Commander Clement</fictional:character>
    </actor>
</actors>

Una forma de buscar y explorar este ejemplo XML es añadir manualmente el URI a cada etiqueta o atributo en el XPath de un find() o findall():

root = fromstring(xml_text)
for actor in root.findall('{http://people.example.com}actor'):
    name = actor.find('{http://people.example.com}name')
    print(name.text)
    for char in actor.findall('{http://characters.example.com}character'):
        print(' |-->', char.text)

Una mejor manera de buscar en el ejemplo de XML con espacio para nombres es crear un diccionario con sus propios prefijos y utilizarlos en las funciones de búsqueda:

ns = {'real_person': 'http://people.example.com',
      'role': 'http://characters.example.com'}

for actor in root.findall('real_person:actor', ns):
    name = actor.find('real_person:name', ns)
    print(name.text)
    for char in actor.findall('role:character', ns):
        print(' |-->', char.text)

Estos dos enfoques dan como resultado:

John Cleese
 |--> Lancelot
 |--> Archie Leach
Eric Idle
 |--> Sir Robin
 |--> Gunther
 |--> Commander Clement

Soporte de XPath

Este módulo proporciona un soporte limitado para las expresiones XPath [https://www.w3.org/TR/xpath] para localizar elementos en un árbol. El objetivo es soportar un pequeño subconjunto de la sintaxis abreviada; un motor XPath completo está fuera del alcance del módulo.

Ejemplo

A continuación se muestra un ejemplo que demuestra algunas de las capacidades de XPath del módulo. Utilizaremos el documento XML countrydata de la sección Parsing XML:

import xml.etree.ElementTree as ET

root = ET.fromstring(countrydata)

# Top-level elements
root.findall(".")

# All 'neighbor' grand-children of 'country' children of the top-level
# elements
root.findall("./country/neighbor")

# Nodes with name='Singapore' that have a 'year' child
root.findall(".//year/..[@name='Singapore']")

# 'year' nodes that are children of nodes with name='Singapore'
root.findall(".//*[@name='Singapore']/year")

# All 'neighbor' nodes that are the second child of their parent
root.findall(".//neighbor[2]")

Para XML con espacios de nombre, use la notación calificada habitual {namespace}tag:

# All dublin-core "title" tags in the document
root.findall(".//{http://purl.org/dc/elements/1.1/}title")

Sintaxis XPath soportada

Sintaxis

Significado

tag

Selecciona todos los elementos hijos con la etiqueta dada. Por ejemplo, spam selecciona todos los elementos hijos llamados spam, y spam/egg selecciona todos los nietos llamados egg en todos los hijos llamados spam. {namespace}* selecciona todas las etiquetas en el espacio de nombres dado, {*}spam selecciona las etiquetas llamadas spam en cualquier (o ningún) espacio de nombres, y {}* sólo selecciona las etiquetas que no están en un espacio de nombres.

Distinto en la versión 3.8: Se ha añadido la posibilidad de utilizar comodines asterisco.

*

Selecciona todos los elementos hijos, incluidos los comentarios y las instrucciones de procesamiento. Por ejemplo, */egg selecciona todos los hijos llamados egg.

.

Selecciona el nodo actual. Esto es útil sobre todo al principio de la ruta, para indicar que es una ruta relativa.

//

Selecciona todos los sub-elementos, en todos los niveles por debajo del elemento actual. Por ejemplo, .//egg selecciona todos los elementos egg en todo el árbol.

..

Selecciona el elemento padre. Retorna None si la ruta intenta llegar a los ancestros del elemento inicial (el elemento find fue invocado).

[@attrib]

Selecciona todos los elementos que tengan el atributo dado.

[@attrib='value']

Selecciona todos los elementos para los que el atributo dado tiene el valor dado. El valor no puede contener comillas.

[tag]

Selecciona todos los elementos que tienen un hijo llamado tag. Sólo se admiten los hijos inmediatos.

[.='text']

Selecciona todos los elementos cuyo contenido de texto completo, incluyendo los descendientes, es igual al «texto» dado.

Nuevo en la versión 3.7.

[tag='text']

Selecciona todos los elementos que tienen un hijo llamado tag cuyo contenido de texto completo, incluyendo los descendientes, es igual al text dado.

[position]

Selecciona todos los elementos que se encuentran en la posición dada. La posición puede ser un número entero (1 es la primera posición), la expresión last() (para la última posición), o una posición relativa a la última posición (por ejemplo, last()-1).

Los predicados (expresiones entre corchetes) deben ir precedidos de un nombre de etiqueta, un asterisco u otro predicado. Los predicados position deben ir precedidos de un nombre de etiqueta.

Referencia

Funciones

xml.etree.ElementTree.canonicalize(xml_data=None, *, out=None, from_file=None, **options)

Función de transformación C14N 2.0 [https://www.w3.org/TR/xml-c14n2/].

La canonización es una forma de normalizar la salida de XML de manera que permita comparaciones byte a byte y firmas digitales. Reduce la libertad que tienen los serializadores XML y en su lugar genera una representación XML más restringida. Las principales restricciones se refieren a la colocación de las declaraciones de espacio de nombres, el orden de los atributos y los espacios en blanco ignorables.

Esta función toma una cadena de datos XML (xml_data) o una ruta de archivo o un objeto tipo archivo (from_file) como entrada, la convierte a la forma canónica y la escribe utilizando el objeto archivo (o tipo archivo) out, si se proporciona, o la devuelve como una cadena de texto si no. El archivo de salida recibe texto, no bytes. Por tanto, debe abrirse en modo texto con codificación utf-8.

Usos típicos:

xml_data = "<root>...</root>"
print(canonicalize(xml_data))

with open("c14n_output.xml", mode='w', encoding='utf-8') as out_file:
    canonicalize(xml_data, out=out_file)

with open("c14n_output.xml", mode='w', encoding='utf-8') as out_file:
    canonicalize(from_file="inputfile.xml", out=out_file)

Las opciones de configuración options son las siguientes:

with_comments: configurar a True para incluir los comentarios (por defecto: False)

strip_text: configurar a True para eliminar los espacios en blanco antes y después del contenido del texto

(por defecto: False)

rewrite_prefixes: configurar a True para sustituir los prefijos de espacios de nombres por «n{number}»

(por defecto: False)

qname_aware_tags: un conjunto de nombres de etiquetas conscientes de qname en el que los prefijos

deben ser reemplazados en el contenido del texto (por defecto: vacío)

qname_aware_attrs: un conjunto de nombres de atributos conscientes de qname en el que los prefijos

deben ser reemplazados en el contenido del texto (por defecto: vacío)

exclude_attrs: un conjunto de nombres de atributos que no deben serializarse

exclude_tags: un conjunto de nombres de etiquetas que no deben serializarse

En la lista de opciones anterior, «un conjunto» se refiere a cualquier colección o iterable de cadenas, no se espera ningún orden.

Nuevo en la versión 3.8.

xml.etree.ElementTree.Comment(text=None)

Fábrica de elementos de comentario. Esta función de fábrica crea un elemento especial que será serializado como un comentario XML por el serializador estándar. La cadena de comentario puede ser una cadena de bytes o una cadena Unicode. text es una cadena que contiene la cadena de comentario. Devuelve una instancia de elemento que representa un comentario.

Tenga en cuenta que XMLParser omite los comentarios en la entrada en lugar de crear objetos de comentario para ellos. Un ElementTree sólo contendrá nodos de comentario si se han insertado en el árbol utilizando uno de los métodos Element.

xml.etree.ElementTree.dump(elem)

Escribe un árbol de elementos o una estructura de elementos en sys.stdout. Esta función debe utilizarse únicamente para debugging.

El formato de salida exacto depende de la implementación. En esta versión, se escribe como un archivo XML ordinario.

elem es un árbol de elementos o un elemento individual.

Distinto en la versión 3.8: La función dump() ahora preserva el orden de atributos especificado por el usuario.

xml.etree.ElementTree.fromstring(text, parser=None)

Analiza una sección XML a partir de una constante de cadena. Igual que XML(). text es una cadena que contiene datos XML. parser es una instancia de parser opcional. Si no se da, se utiliza el analizador estándar XMLParser. Devuelve una instancia de Element.

xml.etree.ElementTree.fromstringlist(sequence, parser=None)

Analiza un documento XML a partir de una secuencia de fragmentos de cadena de caracteres. sequence es una lista u otra secuencia que contiene fragmentos de datos XML. parser es una instancia de parser opcional. Si no se da, se utiliza el analizador estándar XMLParser. Retorna una instancia de Element.

Nuevo en la versión 3.2.

xml.etree.ElementTree.indent(tree, space=" ", level=0)

Añade espacios en blanco al subárbol para indentar el árbol visualmente. Esto puede utilizarse para generar una salida XML con una impresión bonita. tree puede ser un Element o ElementTree. space es la cadena de espacio en blanco que se insertará para cada nivel de indentación, dos caracteres de espacio por defecto. Para indentar subárboles parciales dentro de un árbol ya indentado, pase el nivel de indentación inicial como level.

Nuevo en la versión 3.9.

xml.etree.ElementTree.iselement(element)

Comprueba si un objeto parece ser un objeto elemento válido. element es una instancia de elemento. Retorna True si se trata de un objeto elemento.

xml.etree.ElementTree.iterparse(source, events=None, parser=None)

Analiza una sección XML en un árbol de elementos de forma incremental, e informa al usuario de lo que ocurre. source es un nombre de archivo o un file object que contiene datos XML. events es una secuencia de eventos para informar. Los eventos soportados son las cadenas "start", "end", "comment", "pi", "start-ns" y "end-ns" (los eventos «ns» se utilizan para obtener información detallada del espacio de nombres). Si se omite events, sólo se informará de los eventos "end". parser es una instancia opcional de parser. Si no se da, se utiliza el analizador estándar de XMLParser. parser debe ser una subclase de XMLParser y sólo puede utilizar el TreeBuilder por defecto como objetivo. Devuelve un iterator que proporciona pares (event, elem).

Tenga en cuenta que mientras iterparse() construye el árbol de forma incremental, emite lecturas de bloqueo en la source (o en el fichero que nombra). Por lo tanto, no es adecuado para aplicaciones en las que no se pueden realizar lecturas de bloqueo. Para un análisis completamente no bloqueante, véase XMLPullParser.

Nota

iterparse() sólo garantiza que ha visto el carácter «>» de una etiqueta de inicio cuando emite un evento «start», por lo que los atributos están definidos, pero el contenido de los atributos text y tail está indefinido en ese momento. Lo mismo ocurre con los hijos del elemento; pueden estar presentes o no.

Si necesita un elemento totalmente poblado, busque los eventos «end» en su lugar.

Obsoleto desde la versión 3.4: El argumento parser.

Distinto en la versión 3.8: Los eventos comment y pi han sido añadidos.

xml.etree.ElementTree.parse(source, parser=None)

Analiza una sección XML en un árbol de elementos. source es un nombre de archivo o un objeto de archivo que contiene datos XML. parser es una instancia de parser opcional. Si no se da, se utiliza el analizador estándar XMLParser. Devuelve una instancia de ElementTree.

xml.etree.ElementTree.ProcessingInstruction(target, text=None)

Fábrica de elementos PI. Esta función de fábrica crea un elemento especial que será serializado como una instrucción de procesamiento XML. target es una cadena que contiene el objetivo de PI. text es una cadena que contiene el contenido de PI, si se da. Devuelve una instancia de elemento, representando una instrucción de procesamiento.

Tenga en cuenta que XMLParser omite las instrucciones de procesamiento en la entrada en lugar de crear objetos de comentario para ellas. Un ElementTree sólo contendrá nodos de instrucciones de procesamiento si se han insertado en el árbol utilizando uno de los métodos Element.

xml.etree.ElementTree.register_namespace(prefix, uri)

Registra un prefijo de espacio de nombres. El registro es global, y cualquier asignación existente para el prefijo dado o el URI del espacio de nombres será eliminado. prefix es un prefijo de espacio de nombres. uri es una uri del espacio de nombres. Las etiquetas y los atributos de este espacio de nombres se serializarán con el prefijo dado, si es posible.

Nuevo en la versión 3.2.

xml.etree.ElementTree.SubElement(parent, tag, attrib={}, **extra)

Fábrica de sub-elementos. Esta función crea una instancia de elemento y la añade a un elemento existente.

El nombre del elemento, los nombres de los atributos y los valores de los atributos pueden ser cadenas de bytes o cadenas de caracteres Unicode. parent es el elemento padre. tag es el nombre del sub-elemento. attrib es un diccionario opcional que contiene los atributos del elemento. extra contiene atributos adicionales, dados como argumentos de palabras clave. Devuelve una instancia de elemento.

xml.etree.ElementTree.tostring(element, encoding="us-ascii", method="xml", *, xml_declaration=None, default_namespace=None, short_empty_elements=True)

Genera una representación de cadena de caracteres de un elemento XML, incluyendo todos los sub-elementos. element es una instancia de Element. encoding 1 es la codificación de salida (por defecto es US-ASCII). Utilice encoding="unicode" para generar una cadena de caracteres Unicode (de lo contrario, se genera una cadena de bytes). method es "xml", "html" o "text" (por defecto es "xml"). xml_declaration, default_namespace y short_empty_elements tienen el mismo significado que en ElementTree.write(). Devuelve una cadena (opcionalmente) codificada que contiene los datos XML.

Nuevo en la versión 3.4: El parámetro short_empty_elements.

Nuevo en la versión 3.8: Los parámetros xml_declaration y default_namespace.

Distinto en la versión 3.8: La función tostring() ahora preserva el orden de atributos especificado por el usuario.

xml.etree.ElementTree.tostringlist(element, encoding="us-ascii", method="xml", *, xml_declaration=None, default_namespace=None, short_empty_elements=True)

Genera una representación de cadena de caracteres de un elemento XML, incluyendo todos los sub-elementos. element es una instancia de Element. encoding 1 es la codificación de salida (por defecto es US-ASCII). Utilice encoding="unicode" para generar una cadena de caracteres Unicode (de lo contrario, se genera una cadena de bytes). method es "xml", "html" o "text" (por defecto es "xml"). xml_declaration, default_namespace y short_empty_elements tienen el mismo significado que en ElementTree.write(). Devuelve una lista de cadenas (opcionalmente) codificadas que contienen los datos XML. No garantiza ninguna secuencia específica, excepto que b"".join(tostringlist(element)) == tostring(element).

Nuevo en la versión 3.2.

Nuevo en la versión 3.4: El parámetro short_empty_elements.

Nuevo en la versión 3.8: Los parámetros xml_declaration y default_namespace.

Distinto en la versión 3.8: La función tostringlist() ahora preserva el orden de atributos especificado por el usuario.

xml.etree.ElementTree.XML(text, parser=None)

Analiza una sección XML a partir de una constante de cadena de caracteres. Esta función puede utilizarse para incrustar «literales XML» en el código de Python. text es una cadena de caracteres que contiene datos XML. parser es una instancia de parser opcional. Si no se da, se utiliza el analizador estándar XMLParser. Devuelve una instancia de Element.

xml.etree.ElementTree.XMLID(text, parser=None)

Analiza una sección XML a partir de una constante de cadena de caracteres, y también devuelve un diccionario que mapea los id:s de elementos a elementos. text es una cadena de caracteres que contiene datos XML. parser es una instancia de parser opcional. Si no se da, se utiliza el analizador estándar de XMLParser. Devuelve una tupla que contiene una instancia de Element y un diccionario.

Soporte de XInclude

Este módulo proporciona un soporte limitado para las directivas XInclude [https://www.w3.org/TR/xinclude/], a través del módulo de ayuda xml.etree.ElementInclude. Este módulo puede utilizarse para insertar subárboles y cadenas de texto en árboles de elementos, basándose en la información del árbol.

Ejemplo

Aquí hay un ejemplo que demuestra el uso del módulo XInclude. Para incluir un documento XML en el documento actual, utilice el elemento {http://www.w3.org/2001/XInclude}include y establezca el atributo parse como "xml", y utilice el atributo href para especificar el documento a incluir.

<?xml version="1.0"?>
<document xmlns:xi="http://www.w3.org/2001/XInclude">
  <xi:include href="source.xml" parse="xml" />
</document>

Por defecto, el atributo href se trata como un nombre de archivo. Puede utilizar cargadores personalizados para anular este comportamiento. También tenga en cuenta que el ayudante estándar no soporta la sintaxis XPointer.

Para procesar este archivo, cárguelo como de costumbre y pase el elemento raíz al módulo xml.etree.ElementTree:

from xml.etree import ElementTree, ElementInclude

tree = ElementTree.parse("document.xml")
root = tree.getroot()

ElementInclude.include(root)

El módulo ElementInclude sustituye el elemento {http://www.w3.org/2001/XInclude}include por el elemento raíz del documento source.xml. El resultado podría ser algo así:

<document xmlns:xi="http://www.w3.org/2001/XInclude">
  <para>This is a paragraph.</para>
</document>

Si se omite el atributo parse, el valor por defecto es «xml». El atributo href es obligatorio.

Para incluir un documento de texto, utilice el elemento {http://www.w3.org/2001/XInclude}include y establezca el atributo parse como «text»:

<?xml version="1.0"?>
<document xmlns:xi="http://www.w3.org/2001/XInclude">
  Copyright (c) <xi:include href="year.txt" parse="text" />.
</document>

El resultado podría ser algo así:

<document xmlns:xi="http://www.w3.org/2001/XInclude">
  Copyright (c) 2003.
</document>

Referencia

Funciones

xml.etree.ElementInclude.default_loader(href, parse, encoding=None)

Cargador por defecto. Este cargador por defecto lee un recurso incluido del disco. href es una URL. parse es para el modo de análisis «xml» o «text». encoding es una codificación de texto opcional. Si no se da, la codificación es utf-8. Retorna el recurso expandido. Si el modo de análisis es "xml", es una instancia de ElementTree. Si el modo de análisis es «text», se trata de una cadena Unicode. Si el cargador falla, puede retornar None o lanzar una excepción.

xml.etree.ElementInclude.include(elem, loader=None, base_url=None, max_depth=6)

Esta función expande las directivas XInclude. elem es el elemento raíz. loader es un cargador de recursos opcional. Si se omite, se utiliza por defecto default_loader(). Si se da, debe ser un callable que implemente la misma interfaz que default_loader(). base_url es la URL base del archivo original, para resolver las referencias relativas al archivo de inclusión. max_depth es el número máximo de inclusiones recursivas. Limitado para reducir el riesgo de explosión de contenido malicioso. Pase un valor negativo para desactivar la limitación.

Retorna el recurso expandido. Si el modo de análisis es "xml", se trata de una instancia de ElementTree. Si el modo de análisis es «text», se trata de una cadena Unicode. Si el cargador falla, puede retornar None o lanzar una excepción.

Nuevo en la versión 3.9: Los parámetros base_url y max_depth.

Objetos Element

class xml.etree.ElementTree.Element(tag, attrib={}, **extra)

Clase Element. Esta clase define la interfaz Element, y provee una implementación de referencia de esta interfaz.

El nombre del elemento, los nombres de los atributos y los valores de los atributos pueden ser cadenas de bytes o cadenas Unicode. tag es el nombre del elemento. attrib es un diccionario opcional que contiene los atributos del elemento. extra contiene atributos adicionales, dados como argumentos de palabras clave.

tag

Una cadena de caracteres que identifica qué tipo de datos representa este elemento (el tipo de elemento, en otras palabras).

text

tail

Estos atributos pueden utilizarse para contener datos adicionales asociados al elemento. Sus valores suelen ser cadenas, pero pueden ser cualquier objeto específico de la aplicación. Si el elemento se crea a partir de un archivo XML, el atributo text contiene el texto entre la etiqueta inicial del elemento y su primera etiqueta hija o final, o None, y el atributo tail contiene el texto entre la etiqueta final del elemento y la siguiente etiqueta, o None. Para los datos XML

<a><b>1<c>2<d/>3</c></b>4</a>

el elemento a tiene None para los atributos text y tail, el elemento b tiene text "1" y tail "4", el elemento c tiene text "2" y tail None, y el elemento d tiene text None y tail "3".

Para recoger el texto interior de un elemento, véase itertext(), por ejemplo "".join(element.itertext()).

Las aplicaciones pueden almacenar objetos arbitrarios en estos atributos.

attrib

Un diccionario que contiene los atributos del elemento. Ten en cuenta que aunque el valor attrib es siempre un diccionario mutable real de Python, una implementación de ElementTree puede elegir utilizar otra representación interna, y crear el diccionario sólo si alguien lo pide. Para aprovechar este tipo de implementaciones, utiliza los métodos de diccionario que aparecen a continuación siempre que sea posible.

Los siguientes métodos tipo diccionario funcionan con los atributos de los elementos.

clear()

Restablece un elemento. Esta función elimina todos los sub-elementos, borra todos los atributos y establece los atributos de texto y cola como None.

get(key, default=None)

Obtiene el atributo del elemento llamado key.

Retorna el valor del atributo, o default si el atributo no fue encontrado.

items()

Retorna los atributos del elemento como una secuencia de pares (nombre, valor). Los atributos se retornan en un orden arbitrario.

keys()

Retorna los nombres de los atributos de los elementos como una lista. Los nombres se retornan en un orden arbitrario.

set(key, value)

Establecer el atributo key en el elemento a value.

Los siguientes métodos actúan sobre los hijos del elemento (sub-elementos).

append(subelement)

Añade el elemento subelement al final de la lista interna de sub-elementos de este elemento. Lanza TypeError si subelement no es un Element.

extend(subelements)

Añade subelements de un objeto de secuencia con cero o más elementos. Lanza TypeError si un sub-elemento no es un Element.

Nuevo en la versión 3.2.

find(match, namespaces=None)

Encuentra el primer sub-elemento que coincide con match. match puede ser un nombre de etiqueta o un path. Retorna una instancia de elemento o None. namespaces es un mapeo opcional del prefijo del espacio de nombres al nombre completo. Pasa '' como prefijo para mover todos los nombres de etiquetas sin prefijo en la expresión al espacio de nombres dado.

findall(match, namespaces=None)

Encuentra todos los sub-elementos coincidentes, por nombre de etiqueta o path. Retorna una lista que contiene todos los elementos coincidentes en el orden del documento. namespaces es un mapeo opcional del prefijo del espacio de nombres al nombre completo. Pasa '' como prefijo para mover todos los nombres de etiquetas sin prefijo en la expresión al espacio de nombres dado.

findtext(match, default=None, namespaces=None)

Busca el texto del primer sub-elemento que coincida con match. match puede ser un nombre de etiqueta o un path. Retorna el contenido del texto del primer elemento que coincida, o default si no se encuentra ningún elemento. Tenga en cuenta que si el elemento coincidente no tiene contenido de texto se devuelve una cadena vacía. namespaces es un mapeo opcional del prefijo del espacio de nombres al nombre completo. Pasa '' como prefijo para mover todos los nombres de etiquetas sin prefijo en la expresión al espacio de nombres dado.

insert(index, subelement)

Inserta subelement en la posición dada en este elemento. Lanza TypeError si subelement no es un Element.

iter(tag=None)

Crea un árbol iterator con el elemento actual como raíz. El iterador itera sobre este elemento y todos los elementos por debajo de él, en el orden del documento (profundidad primero). Si tag no es None o '*', sólo los elementos cuya etiqueta es igual a tag son retornados por el iterador. Si la estructura del árbol se modifica durante la iteración, el resultado es indefinido.

Nuevo en la versión 3.2.

iterfind(match, namespaces=None)

Encuentra todos los subelementos que coinciden, por nombre de etiqueta o ruta. Retorna un iterable con todos los elementos coincidentes en el orden del documento. namespaces es un mapeo opcional del prefijo del espacio de nombres al nombre completo.

Nuevo en la versión 3.2.

itertext()

Crea un iterador de texto. El iterador hace un bucle sobre este elemento y todos los subelementos, en el orden del documento, y retorna todo el texto interior.

Nuevo en la versión 3.2.

makeelement(tag, attrib)

Crea un nuevo objeto elemento del mismo tipo que este elemento. No llame a este método, utilice la función de fábrica SubElement() en su lugar.

remove(subelement)

Elimina el subelement del elemento. A diferencia de los métodos find*, este método compara los elementos basándose en la identidad de la instancia, no en el valor de la etiqueta o el contenido.

Los objetos Element también soportan los siguientes métodos de tipo secuencia para trabajar con subelementos: __delitem__(), __getitem__(), __setitem__(), __len__().

Precaución: Los elementos que no tengan subelementos serán evaluados como False. Este comportamiento cambiará en futuras versiones. Utilizar en su lugar el test específico len(elem) o elem is None.

element = root.find('foo')

if not element:  # careful!
    print("element not found, or element has no subelements")

if element is None:
    print("element not found")

Antes de Python 3.8, el orden de serialización de los atributos XML de los elementos se hacía predecible artificialmente ordenando los atributos por su nombre. Basado en el ordenamiento -ahora garantizado- de los diccionarios, este reordenamiento arbitrario fue eliminado en Python 3.8 para preservar el orden en que los atributos fueron originalmente analizados o creados por el código del usuario.

En general, el código del usuario debería intentar no depender de un orden específico de los atributos, dado que el XML Information Set [https://www.w3.org/TR/xml-infoset/] excluye explícitamente el orden de los atributos para transmitir información. El código debe estar preparado para hacer frente a cualquier orden en la entrada. En los casos en los que se requiere una salida XML determinista, por ejemplo, para la firma criptográfica o los conjuntos de datos de prueba, la serialización canónica está disponible con la función canonicalize().

En los casos en los que la salida canónica no es aplicable, pero un orden de atributos específico sigue siendo deseable en la salida, el código debe tratar de crear los atributos directamente en el orden deseado, para evitar desajustes perceptivos para los lectores del código. En los casos en que esto es difícil de lograr, una receta como la siguiente se puede aplicar antes de la serialización para hacer cumplir un orden independientemente de la creación de elementos:

def reorder_attributes(root):
    for el in root.iter():
        attrib = el.attrib
        if len(attrib) > 1:
            # adjust attribute order, e.g. by sorting
            attribs = sorted(attrib.items())
            attrib.clear()
            attrib.update(attribs)

Objetos ElementTree

class xml.etree.ElementTree.ElementTree(element=None, file=None)

Clase envoltorio de un ElementTree. Esta clase representa una jerarquía de elementos completa, y añade algún soporte extra para la serialización hacia y desde XML estándar.

element es el elemento raíz. El árbol se inicializa con el contenido del file XML si se da.

_setroot(element)

Reemplaza el elemento raíz de este árbol. Esto descarta el contenido actual del árbol, y lo reemplaza con el elemento dado. Utilícelo con cuidado. element es una instancia de elemento.

find(match, namespaces=None)

Igual que Element.find(), empezando por la raíz del árbol.

findall(match, namespaces=None)

Igual que Element.findall(), empezando por la raíz del árbol.

findtext(match, default=None, namespaces=None)

Igual que Element.findtext(), empezando por la raíz del árbol.

getroot()

Retorna el elemento raíz de este árbol.

iter(tag=None)

Crea y retorna un iterador de árbol para el elemento raíz. El iterador recorre todos los elementos de este árbol, en orden de sección. tag es la etiqueta a buscar (por defecto devuelve todos los elementos).

iterfind(match, namespaces=None)

Igual que Element.iterfind(), empezando por la raíz del árbol.

Nuevo en la versión 3.2.

parse(source, parser=None)

Carga una sección XML externa en este árbol de elementos. source es un nombre de archivo o un file object. parser es una instancia opcional del analizador. Si no se da, se utiliza el analizador estándar XMLParser. Retorna el elemento raíz de la sección.

write(file, encoding="us-ascii", xml_declaration=None, default_namespace=None, method="xml", *, short_empty_elements=True)

Escribe el árbol de elementos en un archivo, como XML. file es un nombre de archivo, o un file object abierto para escritura. encoding 1 es la codificación de salida (por defecto es US-ASCII). xml_declaration controla si se debe añadir una declaración XML al archivo. Utilice False para nunca, True para siempre, None para sólo si no es US-ASCII o UTF-8 o Unicode (por defecto es None). default_namespace establece el espacio de nombres XML por defecto (para «xmlns»). method es "xml", "html" o "text" (por defecto es "xml"). El parámetro short_empty_elements controla el formato de los elementos sin contenido. Si es True (por defecto), se emiten como una sola etiqueta autocerrada, de lo contrario se emiten como un par de etiquetas de inicio/fin.

La salida es una cadena de caracteres (str) o binaria (bytes). Esto es controlado por el argumento encoding. Si encoding es unicode, la salida es una cadena de caracteres; en caso contrario, es binaria. Tenga en cuenta que esto puede entrar en conflicto con el tipo de file si es un file object abierto; asegúrese de no intentar escribir una cadena en un flujo binario y viceversa.

Nuevo en la versión 3.4: El parámetro short_empty_elements.

Distinto en la versión 3.8: El método write() ahora conserva el orden de los atributos especificado por el usuario.

Este es el archivo XML que será manipulado:

<html>
    <head>
        <title>Example page</title>
    </head>
    <body>
        <p>Moved to <a href="http://example.org/">example.org</a>
        or <a href="http://example.com/">example.com</a>.</p>
    </body>
</html>

Ejemplo de cambio del atributo «target» de cada enlace en el primer párrafo:

>>> from xml.etree.ElementTree import ElementTree
>>> tree = ElementTree()
>>> tree.parse("index.xhtml")
<Element 'html' at 0xb77e6fac>
>>> p = tree.find("body/p")     # Finds first occurrence of tag p in body
>>> p
<Element 'p' at 0xb77ec26c>
>>> links = list(p.iter("a"))   # Returns list of all links
>>> links
[<Element 'a' at 0xb77ec2ac>, <Element 'a' at 0xb77ec1cc>]
>>> for i in links:             # Iterates through all found links
...     i.attrib["target"] = "blank"
>>> tree.write("output.xhtml")

Objetos QName

class xml.etree.ElementTree.QName(text_or_uri, tag=None)

QName wrapper. Se puede utilizar para envolver un valor de atributo QName, con el fin de obtener un manejo adecuado del espacio de nombres en la salida. text_or_uri es una cadena de caracteres que contiene el valor QName, en la forma {uri}local, o, si se da el argumento tag, la parte URI de un QName. Si se da tag, el primer argumento se interpreta como un URI, y este argumento se interpreta como un nombre local. Las instancias de QName son opacas.

Objetos TreeBuilder

class xml.etree.ElementTree.TreeBuilder(element_factory=None, *, comment_factory=None, pi_factory=None, insert_comments=False, insert_pis=False)

Constructor genérico de estructuras de elementos. Este constructor convierte una secuencia de llamadas a los métodos start, data, end, comment y pi en una estructura de elementos bien formada. Puedes utilizar esta clase para construir una estructura de elementos utilizando un analizador XML personalizado, o un analizador para algún otro formato similar a XML.

element_factory, cuando se da, debe ser un callable que acepta dos argumentos posicionales: una etiqueta y un diccionario de atributos. Se espera que retorne una nueva instancia de elemento.

Las funciones comment_factory y pi_factory, cuando se dan, deben comportarse como las funciones Comment() y ProcessingInstruction() para crear comentarios e instrucciones de procesamiento. Si no se dan, se utilizarán las fábricas por defecto. Cuando insert_comments y/o insert_pis es verdadero, los comentarios/pis se insertarán en el árbol si aparecen dentro del elemento raíz (pero no fuera de él).

close()

Vacía los buffers del constructor y retorna el elemento del documento de nivel superior. Retorna una instancia de Element.

data(data)

Añade texto al elemento actual. data es una cadena. Debe ser una cadena de bytes o una cadena Unicode.

end(tag)

Cierra el elemento actual. tag es el nombre del elemento. Retorna el elemento cerrado.

start(tag, attrs)

Abre un nuevo elemento. tag es el nombre del elemento. attrs es un diccionario que contiene los atributos del elemento. Retorna el elemento abierto.

comment(text)

Crea un comentario con el texto dado. Si insert_comments es verdadero, esto también lo añadirá al árbol.

Nuevo en la versión 3.8.

pi(target, text)

Crea un comentario con el nombre target y el texto dados. Si insert_pis es verdadero, esto también lo añadirá al árbol.

Nuevo en la versión 3.8.

Además, un objeto TreeBuilder personalizado puede proporcionar los siguientes métodos:

doctype(name, pubid, system)

Maneja una declaración de doctype. name es el nombre del doctype. pubid es el identificador público. system es el identificador del sistema. Este método no existe en la clase por defecto TreeBuilder.

Nuevo en la versión 3.2.

start_ns(prefix, uri)

Se llama cada vez que el analizador encuentra una nueva declaración de espacio de nombres, antes de la llamada de retorno start() para el elemento de apertura que lo define. prefix es '' para el espacio de nombres por defecto y el nombre del prefijo del espacio de nombres declarado en caso contrario. uri es el URI del espacio de nombres.

Nuevo en la versión 3.8.

end_ns(prefix)

Se llama después de la llamada de retorno end() de un elemento que declaró un mapeo de prefijo de espacio de nombres, con el nombre del prefijo que salió del ámbito.

Nuevo en la versión 3.8.

class xml.etree.ElementTree.C14NWriterTarget(write, *, with_comments=False, strip_text=False, rewrite_prefixes=False, qname_aware_tags=None, qname_aware_attrs=None, exclude_attrs=None, exclude_tags=None)

Un escritor C14N 2.0 [https://www.w3.org/TR/xml-c14n2/]. Los argumentos son los mismos que para la función canonicalize(). Esta clase no construye un árbol, sino que traduce los eventos de devolución de llamada directamente a una forma serializada utilizando la función write.

Nuevo en la versión 3.8.

Objetos XMLParser

class xml.etree.ElementTree.XMLParser(*, target=None, encoding=None)

Esta clase es el bloque de construcción de bajo nivel del módulo. Utiliza xml.parsers.expat para un análisis eficiente de XML basado en eventos. Puede ser alimentada con datos XML de forma incremental con el método feed(), y los eventos de análisis se traducen en una API push - invocando callbacks en el objeto target. Si se omite target, se utiliza la clase estándar TreeBuilder. Si se da encoding 1, el valor anula la codificación especificada en el archivo XML.

Distinto en la versión 3.8: Los parámetros son ahora keyword-only. El argumento html ya no se admite.

close()

Finaliza la alimentación de datos al analizador. Retorna el resultado de llamar al método close() del target pasado durante la construcción; por defecto, es el elemento del documento de nivel superior.

feed(data)

Introduce los datos en el analizador sintáctico. data son datos codificados.

XMLParser.feed() llama al método start(tag, attrs_dict) de target para cada etiqueta de apertura, a su método end(tag) para cada etiqueta de cierre, y los datos son procesados por el método data(data). Para más métodos de callback soportados, véase la clase TreeBuilder. XMLParser.close() llama al método close() de target. XMLParser puede utilizarse no sólo para construir una estructura de árbol. Este es un ejemplo de contar la profundidad máxima de un archivo XML:

>>> from xml.etree.ElementTree import XMLParser
>>> class MaxDepth:                     # The target object of the parser
...     maxDepth = 0
...     depth = 0
...     def start(self, tag, attrib):   # Called for each opening tag.
...         self.depth += 1
...         if self.depth > self.maxDepth:
...             self.maxDepth = self.depth
...     def end(self, tag):             # Called for each closing tag.
...         self.depth -= 1
...     def data(self, data):
...         pass            # We do not need to do anything with data.
...     def close(self):    # Called when all data has been parsed.
...         return self.maxDepth
...
>>> target = MaxDepth()
>>> parser = XMLParser(target=target)
>>> exampleXml = """
... <a>
...   <b>
...   </b>
...   <b>
...     <c>
...       <d>
...       </d>
...     </c>
...   </b>
... </a>"""
>>> parser.feed(exampleXml)
>>> parser.close()
4

Objetos XMLPullParser

class xml.etree.ElementTree.XMLPullParser(events=None)

Un analizador sintáctico pull adecuado para aplicaciones no bloqueantes. Su API de entrada es similar a la de XMLParser, pero en lugar de enviar llamadas a un objetivo de devolución de llamada, XMLPullParser recoge una lista interna de eventos de análisis y permite al usuario leer de ella. events son una secuencia de eventos a reportar. Los eventos soportados son las cadenas "start", "end", "comment", "pi", "start-ns" y "end-ns" (los eventos «ns» se utilizan para obtener información detallada del espacio de nombres). Si se omite events, sólo se informará de los eventos "end".

feed(data)

Introduce los datos de los bytes dados en el analizador.

close()

Señala al analizador que el flujo de datos ha terminado. A diferencia de XMLParser.close(), este método siempre retorna None. Cualquier evento que no haya sido recuperado cuando el analizador se cierra puede ser leído con read_events().

read_events()

Retorna un iterador sobre los eventos que se han encontrado en los datos alimentados al analizador. El iterador retorna pares (event, elem), donde event es una cadena de caracteres que representa el tipo de evento (por ejemplo, "fin") y elem es el objeto Element encontrado, u otro valor de contexto como el siguiente.

start, end: el Element actual.

comment, pi: el comentario / la instrucción de procesamiento actual

start-ns: una tupla (prefix, uri) que nombra el mapeo del espacio de nombres declarado.

end-ns: None (esto puede cambiar en una versión futura)

Los eventos proporcionados en una llamada anterior a read_events() no serán retornados nuevamente. Los eventos se consumen de la cola interna sólo cuando se recuperan del iterador, por lo que múltiples lectores iterando en paralelo sobre iteradores obtenidos de read_events() tendrán resultados impredecibles.

Nota

XMLPullParser sólo garantiza que ha visto el carácter «>» de una etiqueta de inicio cuando emite un evento «start», por lo que los atributos están definidos, pero el contenido de los atributos text y tail está indefinido en ese momento. Lo mismo ocurre con los hijos del elemento; pueden estar presentes o no.

Si necesita un elemento totalmente poblado, busque los eventos «end» en su lugar.

Nuevo en la versión 3.4.

Distinto en la versión 3.8: Los eventos comment y pi han sido añadidos.

Excepciones

class xml.etree.ElementTree.ParseError

Error de análisis de XML, lanzado por los distintos métodos de análisis de este módulo cuando el análisis falla. La representación en cadena de caracteres de una instancia de esta excepción contendrá un mensaje de error fácil de entender. Además, tendrá los siguientes atributos disponibles:

code

Un código de error numérico del analizador sintáctico expat. Consulte la documentación de xml.parsers.expat para ver la lista de códigos de error y sus significados.

position

Una tupla de números de line, column, que especifica dónde se produjo el error.

Notas al pie de página

1(1,2,3,4)

La cadena de caracteres de codificación incluida en la salida XML debe ajustarse a los estándares adecuados. Por ejemplo, «UTF-8» es válido, pero «UTF8» no lo es. Consulte https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl y https://www.iana.org/assignments/character-sets/character-sets.xhtml.

xml.dom — El API del Modelo de Objetos del Documento

Código Fuente: Lib/xml/dom/__init__.py [https://github.com/python/cpython/tree/3.9/Lib/xml/dom/__init__.py]

El Modelo de Objetos del Documento, o «DOM» por sus siglas en inglés, es un lenguaje API del Consorcio World Wide Web (W3C) para acceder y modificar documentos XML. Una implementación del DOM presenta los documento XML como un árbol, o permite al código cliente construir dichas estructuras desde cero para luego darles acceso a la estructura a través de un conjunto de objetos que implementaron interfaces conocidas.

El DOM es extremadamente útil para aplicaciones de acceso directo. SAX sólo te permite la vista de una parte del documento a la vez. Si estás mirando un elemento SAX, no tienes acceso a otro. Si estás viendo un nodo de texto, no tienes acceso al elemento contenedor. Cuando desarrollas una aplicación SAX, necesitas registrar la posición de tu programa en el documento en algún lado de tu código. SAX no lo hace por ti. Además, desafortunadamente no podrás mirar hacia adelante (look ahead) en el documento XML.

Algunas aplicaciones son imposibles en un modelo orientado a eventos sin acceso a un árbol. Por supuesto que puedes construir algún tipo de árbol por tu cuenta en eventos SAX, pero el DOM te evita escribir ese código. El DOM es una representación de árbol estándar para datos XML.

El Modelo de Objetos del Documento es definido por el W3C en fases, o «niveles» en su terminología. El mapeado de Python de la API está basado en la recomendación del DOM nivel 2.

Las aplicaciones DOM típicamente empiezan al diseccionar (parse) el XML en un DOM. Cómo esto funciona no está incluido en el DOM nivel 1, y el nivel 2 provee mejoras limitadas. Existe una clase objeto llamada DOMImplementation que da acceso a métodos de creación de Document, pero de ninguna forma da acceso a los constructores (builders) de reader/parser/Document de una forma independiente a la implementación. No hay una forma clara para acceder a estos método sin un objeto Document existente. En Python, cada implementación del DOM proporcionará una función getDOMImplementation(). El DOM de nivel 3 añade una especificación para Cargar(Load)/Guardar(Store), que define una interfaz al lector (reader), pero no está disponible aún en la librería estándar de Python.

Una vez que tengas un objeto del documento del DOM, puedes acceder a las partes de tu documento XML a través de sus propiedades y métodos. Estas propiedades están definidas en la especificación del DOM; está porción del manual describe la interpretación de la especificación en Python.

La especificación estipulada por el W3C define la DOM API para Java, ECMAScript, y OMG IDL. El mapeo de Python definido aquí está basado en gran parte en la versión IDL de la especificación, pero no se requiere el cumplimiento estricto (aunque las implementaciones son libres de soportar el mapeo estricto de IDL). Véase la sección Conformidad para una discusión detallada del mapeo de los requisitos.

Ver también

Document Object Model (DOM) Level 2 Specification [https://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/]

La recomendación del W3C con la cual se basa el DOM API de Python.

Document Object Model (DOM) Level 1 Specification [https://www.w3.org/TR/REC-DOM-Level-1/]

La recomendación del W3C para el DOM soportada por xml.dom.minidom.

Python Language Mapping Specification [https://www.omg.org/spec/PYTH/1.2/PDF]

Este documento especifica el mapeo de OMG IDL a Python.

Contenido del Módulo

El módulo xml.dom contiene las siguientes funciones:

xml.dom.registerDOMImplementation(name, factory)

Registra la función factory con el nombre name. La función fábrica (factory) debe retornar un objeto que implemente la interfaz DOMImplementation. La función fábrica puede retornar el mismo objeto cada vez que se llame, o uno nuevo por cada llamada, según sea apropiado para la implementación específica (e.g. si la implementación soporta algunas personalizaciones).

xml.dom.getDOMImplementation(name=None, features=())

Retorna una implementación del DOM apropiada. El name es o bien conocido, el nombre del módulo de una implementación DOM, o None. Si no es None importa el módulo correspondiente y retorna un objecto DomImplementation si la importación tiene éxito. Si no se le pasa un nombre, y el entorno de variable PYTHON_DOM ha sido puesto, dicha variable es usada para encontrar la información de la implementación.

Si no se le pasa un nombre, examina las implementaciones disponibles para encontrar uno con el conjunto de características requeridas. Si no se encuentra ninguna implementación, levanta una excepción ImportError. La lista de características debe ser una secuencia de pares (feature,version) que son pasados al método hasFeature() en objetos disponibles de DOMImplementation.

Algunas constantes convenientes son proporcionadas:

xml.dom.EMPTY_NAMESPACE

El valor usado para indicar que ningún espacio de nombres es asociado con un nodo en el DOM. Se encuentra típicamente con el namespaceURI de un nodo, o usado como el parámetro namespaceURI para un método específico del namespace.

xml.dom.XML_NAMESPACE

El espacio de nombres de la URI asociada con el prefijo xml, como se define por Namespaces in XML [https://www.w3.org/TR/REC-xml-names/] (sección 4).

xml.dom.XMLNS_NAMESPACE

El espacio de nombres del URI para declaraciones del espacio de nombres, como se define en Document Object Model (DOM) Level 2 Core Specification [https://www.w3.org/TR/DOM-Level-2-Core/core.html] (sección 1.1.8).

xml.dom.XHTML_NAMESPACE

El URI del espacio de nombres del XHTML como se define en XHTML 1.0: The Extensible HyperText Markup Language [https://www.w3.org/TR/xhtml1/] (sección 3.1.1).

Además, xml.dom contiene una clase base Node y las clases de excepciones del DOM. La clase Node proporcionada por este módulo no implementa ninguno de los métodos o atributos definidos en la especificación DOM; las implementaciones del DOM concretas deben definirlas. La clase Node propuesta por este módulo sí proporciona las constantes usadas por el atributo nodeType en objetos concretos de Node; estas son localizadas dentro de la clase en vez de estar al nivel del módulo para cumplir las especificaciones del DOM.

Objetos en el DOM

La documentación definitiva para el DOM es la especificación del DOM del W3C.

Note que los atributos del DOM también pueden ser manipulados como nodos en vez de simples cadenas de caracteres (strings). Sin embargo, es bastante raro que tengas que hacer esto, por lo que su uso aún no está documentado.

Interfaz

Sección

Propósito

DOMImplementation

Objetos DOMImplementation

Interfaz para las implementaciones subyacentes.

Node

Objetos Nodo

Interfaz base para la mayoría de objetos en un documento.

NodeList

Objetos NodeList

Interfaz para una secuencia de nodos.

DocumentType

Objetos DocumentType

Información acerca de la declaraciones necesarias para procesar un documento.

Document

Objetos Documento

Objeto que representa un documento entero.

Element

Objetos Elemento

Nodos elemento en la jerarquía del documento.

Attr

Objetos Atributo

Nodos de los valores de los atributos en los elementos nodo.

Comment

Objetos Comentario

Representación de los comentarios en el documento fuente.

Text

Objetos Texto y CDATASection

Nodos con contenido textual del documento.

ProcessingInstruction

Objetos ProcessingInstruction

Representación de instrucción del procesamiento.

Una sección adicional describe las excepciones definidas para trabajar con el DOM en Python.

Objetos DOMImplementation

La interfaz DOMImplementation proporciona una forma para que las aplicaciones determinen la disponibilidad de características particulares en el DOM que están usando. El DOM nivel 2 añadió la habilidad de crear nuevos objetos Document y DocumentType usando DOMImplementation también.

DOMImplementation.hasFeature(feature, version)

Retorna True si la característica identificada por el par de cadenas de caracteres feature y version está implementada.

DOMImplementation.createDocument(namespaceUri, qualifiedName, doctype)

Retorna un nuevo objeto Document (la raíz del DOM), con un hijo objeto Element teniendo el namespaceUri y qualifiedName dados. El doctype debe ser un DocumentType creado por createDocumentType() o None. En la DOM API de Python, los primeros argumentos pueden ser None para indicar que ningún hijo Element va a ser creado.

DOMImplementation.createDocumentType(qualifiedName, publicId, systemId)

Retorna un nuevo objeto DocumentType que encapsula las cadenas de caracteres qualifiedName, publicId, y systemId dadas, representando la información contenida en un tipo de declaración de documento XML.

Objetos Nodo

Todos los componentes de un documento XML son sub-clases de Node.

Node.nodeType

Un entero representando el tipo de nodo. Las Constantes simbólicas para los tipos están en el objeto Nodo: ELEMENT_NODE, ATTRIBUTE_NODE, TEXT_NODE, CDATA_SECTION_NODE, ENTITY_NODE, PROCESSING_INSTRUCTION_NODE, COMMENT_NODE, DOCUMENT_NODE, DOCUMENT_TYPE_NODE, NOTATION_NODE. Este es un atributo sólo de lectura.

Node.parentNode

El padre del nodo actual, o None para el nodo del documento. El valor es siempre un objeto Node o None. Para los nodos Element, este será el elemento padre, excepto para el elemento raíz, en cuyo caso será el objeto Document. Para los nodos Attr, este siempre es None. Este es un atributo de sólo lectura.

Node.attributes

Un NamedNodeMap de objetos de atributos. Sólo los elementos tienes un valor real para esto; otros nodos proporcionan None para este atributo. Este es un atributo de sólo lectura.

Node.previousSibling

El nodo que precede inmediatamente este nodo con el mismo padre. Por ejemplo el elemento con una etiqueta final que viene justo antes de la etiqueta del comienzo del elemento self. Por supuesto, los documentos XML está hechos de más que sólo elementos por lo que el hermano anterior puede ser un texto, un comentario, o algo más. Si este nodo es el primer hijo del padre, este atributo será None. Este es un atributo de sólo lectura.

Node.nextSibling

El nodo que sigue inmediatamente este nodo con el mismo padre. Véase también previousSibling. Si este es el último hijo del padre, este atributo será None. Este es un atributo de sólo lectura.

Node.childNodes

Una lista de nodos contenidos dentro de este nodo. Este es un atributo de sólo lectura.

Node.firstChild

El primer hijo del nodo, si hay alguno, o None. Este es un atributo de sólo lectura.

Node.lastChild

El último hijo del nodo, si hay alguno, o None. Este es un atributo de sólo lectura.

Node.localName

La parte del tagName seguido de los dos puntos si hay uno, si no, el tagName entero. El valor es una cadena de caracteres.

Node.prefix

La parte del tagName antes de los dos puntos si hay uno, si no, la cadena de caracteres vacía. El valor es una cadena, o None.

Node.namespaceURI

El espacio de nombres asociado con el nombre del elemento. Este será una cadena de caracteres o None. Este es una atributo de sólo lectura.

Node.nodeName

Este tiene un significado diferente para cada tipo de nodo; véase la especificación del DOM para los detalles. Siempre puedes obtener la información que obtendrías aquí desde otra propiedad como la propiedad tagName para elementos o la propiedad name para atributos. Para todos los tipos de nodo, el valor de este atributo tendrá o una cadena de caracteres o None. Este es un atributo de sólo lectura.

Node.nodeValue

Este tiene un significado diferente para cada tipo de nodo; véase la especificación del DOM para los detalles. La situación es similar a ese con nodeName. El valor es una cadena de caracteres o None.

Node.hasAttributes()

Retorna True si el nodo tiene algún atributo.

Node.hasChildNodes()

Retorna True si el nodo tiene algún nodo hijo.

Node.isSameNode(other)

Retorna True si other hace referencia al mismo nodo como este nodo. Esto es especialmente útil para las implementaciones DOM que usan una arquitectura proxy de cualquier tipo (porque más de un objeto puede hacer referencia al mismo nodo).

Nota

Esto se basa en una DOM API de nivel 3 propuesta que está en la etapa de «borrador de trabajo» («working draft»), pero esta interfaz en particular no parece controversial. Los cambios del W3C necesariamente no afectaran este método en la interfaz del DOM del Python (aunque cualquier nueva API del W3C para esto también sería soportado).

Node.appendChild(newChild)

Añade un nuevo nodo hijo a este nodo al final de la lista de hijos, retornando newChild. Si el nodo ya estaba en el árbol, este se remueve primero.

Node.insertBefore(newChild, refChild)

Inserta un nuevo nodo hijo antes de un hijo existente. Debe ser el caso que refChild sea un hijo de este nodo; si no, ValueError es lanzado. newChild es retornado. Si refChild es None, se inserta a newChild al final de la lista de hijos.

Node.removeChild(oldChild)

Elimina un nodo hijo. oldChild debe ser un hijo de este nodo; si no, ValueError es lanzado. oldChild es retornado si tiene éxito. Si oldChild no será usado más adelante, se debe llamar a su método unlink().

Node.replaceChild(newChild, oldChild)

Reemplaza un nodo existente con un nuevo nodo. Debe ser el caso que oldChild sea un hijo de este nodo; si no, ValueError es lanzado.

Node.normalize()

Une nodos de texto adyacentes para que todos los tramos de texto sean guardados como únicas instancias de Text. Esto simplifica el procesamiento de texto de un árbol del DOM para muchas aplicaciones.

Node.cloneNode(deep)

Clona este nodo. Poner deep significa clonar todos los nodos hijo también. Esto retorna el clon.

Objetos NodeList

Un NodeList representa una secuencia de nodos. Estos objetos se usan de dos formas en la recomendación principal del DOM: un objeto Element proporciona uno como su lista de nodos hijo, y los métodos getElementsByTagName() y getElementsByTagNameNS() de Node retornan objetos con esta interfaz para representar resultados de consulta.

La recomendación del DOM nivel 2 define un método y un atributo para estos objetos:

NodeList.item(i)

Retorna el i-ésimo item de la secuencia, si hay uno, o None. El índice i no puede ser menor que cero o mayor o igual que el tamaño de la secuencia.

NodeList.length

El número de nodos en la secuencia.

Además, la interfaz DOM de Python requiere que un algún soporte adicional sea proporcionado para que los objetos NodeList puedan ser usados como secuencias de Python. Todas las implementaciones de NodeList deben incluir soporte para __len__() y __getitem__(); esto permite la iteración de NodeList en sentencias con for y un soporte apropiado para la función incorporada len().

Si una implementación DOM soporta la modificación del documento, la implementación de NodeList debe también soportar los métodos __setitem__() y __delitem__().

Objetos DocumentType

La información acerca de las notaciones y entidades declaradas por un documento (incluido el subconjunto externo si el analizador lo usa y puede proporcionar información) está disponible desde un objeto DocumentType. El DocumentType para un documento está disponible desde el atributo doctype del objeto Document; si no hay ninguna declaración DOCTYPE para el documento, el atributo doctype del documento se pondrá como None en vez de una instancia de esta interfaz.

DocumentType es una especialización de Node, y añade los siguientes atributos:

DocumentType.publicId

El identificador público para el subconjunto externo de la definición del tipo de documento. Esto será una cadena de caracteres o None.

DocumentType.systemId

El identificador del sistema para el subconjunto externo de la definición del tipo de documento. Esto será una URI como una cadena de caracteres, o None.

DocumentType.internalSubset

Una cadena de caracteres proporcionando el subconjunto interno completo del documento. Esto no incluye los paréntesis que cierran el subconjunto. Si el documento no tiene ningún subconjunto interno, debe ser None.

DocumentType.name

El nombre del elemento raíz como se indica en la declaración DOCTYPE, si está presente.

DocumentType.entities

Este es un NamedNodeMap proporcionando las definiciones de las entidades externas. Para nombres de entidades definidas más de una vez, sólo la primera definición es proporcionada (el resto es ignorado como se requiere por la recomendación de XML). Puede ser None si el analizador no proporciona la información, o si ninguna entidad es definida.

DocumentType.notations

Este es un NamedNodeMap proporcionando las definiciones de las notaciones. Para nombres de notaciones definidas más de una vez, sólo la primera definición es proporcionada (el resto es ignorado como se requiere por la recomendación XML). Puede ser None si el analizador no proporciona la información, o si no hay notaciones definidas.

Objetos Documento

Un Documento representa un documento XML entero, incluyendo sus elementos constituyentes, atributos, instrucciones de procesamiento, comentarios, etc. Recuerda que este hereda propiedades de Node.

Document.documentElement

El único elemento raíz del documento.

Document.createElement(tagName)

Crea y retorna un nuevo elemento nodo. El elemento no se inserta en el documento cuando es creado. Necesitas insertarlo explícitamente con uno de los otros métodos como insertBefore() o appendChild().

Document.createElementNS(namespaceURI, tagName)

Crea y retorna un nuevo elemento con un espacio de nombres. El tagName puede tener un prefijo. El elemento no se inserta en el documento cuando es creado. Necesitas insertarlo explícitamente con uno de los otros métodos como insertBefore() o appendChild().

Document.createTextNode(data)

Crea y retorna un nodo texto conteniendo los datos pasados como parámetros, Como con los otros métodos de creación, este no inserta el nodo en el árbol.

Document.createComment(data)

Crea y retorna un nodo comentario conteniendo los datos pasados como parámetros. Como con los otros métodos de creación, este no inserta el nodo en el árbol.

Document.createProcessingInstruction(target, data)

Crea y retorna una instrucción de procesamiento conteniendo el target y data pasados como parámetros. Como con los otros métodos de creación, este no inserta en nodo en el árbol.

Document.createAttribute(name)

Crea y retorna un nodo atributo. Este método no asocia el nodo atributo con ningún elemento particular. Debes usar setAttributeNode() en el objeto Element apropiado para usar la instancia del atributo recién creada.

Document.createAttributeNS(namespaceURI, qualifiedName)

Crea y retorna un nodo atributo con un espacio de nombres. El tagName puede ser un prefijo. Este método no asocia el nodo atributo con ningún elemento en particular. Debes usar setAttributeNode() en el objeto Element apropiado para usar la instancia del atributo recién creada.

Document.getElementsByTagName(tagName)

Busca todos los descendientes (hijos directos, hijos de los hijos, etc.) con un nombre del tipo de elemento particular.

Document.getElementsByTagNameNS(namespaceURI, localName)

Busca todos los descendientes (hijos directos, hijos de hijos, etc.) con un espacio de nombres URI particular (namespaceURI) y nombre local (localname). El nombre local es parte del espacio de nombres después del prefijo.

Objetos Elemento

Element es una subclase de Node, por lo que hereda todos los atributos de esa clase.

Element.tagName

El nombre del tipo de elemento. En un documento que usa espacios de nombres este puede tener varios dos puntos en el. El valor es una cadena de caracteres.

Element.getElementsByTagName(tagName)

Igual al método equivalente en la clase Document.

Element.getElementsByTagNameNS(namespaceURI, localName)

Igual al método equivalente en la clase Document.

Element.hasAttribute(name)

Retorna True si el elemento tiene un atributo nombrado name.

Element.hasAttributeNS(namespaceURI, localName)

Retorna True si el elemento tiene un atributo nombrado por namespaceURI y localName.

Element.getAttribute(name)

Retorna el valor del atributo nombrado por name como una cadena de caracteres. Si no existe dicho atributo, una cadena vacía es retornada, como si el atributo no tuviera valor.

Element.getAttributeNode(attrname)

Retorna el nodo Attr para el atributo nombrado por attrname.

Element.getAttributeNS(namespaceURI, localName)

Retorna el valor del atributo nombrado por namespaceURI y localName como una cadena de caracteres. Si no existe dicho atributo, una cadena vacía es retornada, como si el atributo no tuviera valor.

Element.getAttributeNodeNS(namespaceURI, localName)

Retorna un valor de atributo como nodo, dado un namespaceURI y localName.

Element.removeAttribute(name)

Remueve un atributo por nombre (name). Si no hay un atributo correspondiente, un NotFoundErr es levantado.

Element.removeAttributeNode(oldAttr)

Remueve y retorna oldAttr de la lista de atributos, si está presenta. Si oldAttr no está presente, NotFoundErr es levantado.

Element.removeAttributeNS(namespaceURI, localName)

Remueve un atributo por nombre (name). Note que esto usa un localName, no un qname. Ninguna excepción es levantada si no existe el atributo correspondiente.

Element.setAttribute(name, value)

Pone un valor de atributo como una cadena de caracteres.

Element.setAttributeNode(newAttr)

Añade un nuevo atributo nodo al elemento, reemplazando un atributo existente si es necesario si el atributo name coincide. Si un reemplazo ocurre, el viejo atributo será retornado. Si newAttr ya está en uso, InuseAttributeErr será lanzado.

Element.setAttributeNodeNS(newAttr)

Añade un nuevo nodo atributo al elemento, reemplazando un atributo existente si es necesario, si el namesapceURI y localName coinciden. Si un reemplazo ocurre, el viejo atributo será retornado. Si newAttr está en uso, InuseAttributeErr será levantado.

Element.setAttributeNS(namespaceURI, qname, value)

Pone un valor de atributo a partir de una cadena de caracteres, dados un namespaceURI y qname. Note que un qname es el nombre completo del atributo. Esto es diferente al de arriba.

Objetos Atributo

Attr hereda de Node, por lo que hereda todos sus atributos.

Attr.name

El nombre del atributo. En un documento que usa espacio de nombres, puede incluir dos puntos.

Attr.localName

La parte del nombre seguido después de los dos puntos si hay uno, si no el nombre entero. Este es un atributo de sólo lectura.

Attr.prefix

La parte del nombre que precede los dos puntos si hay uno, si no la cadena de caracteres vacía.

Attr.value

El valor textual del atributo. Este es un sinónimo para el atributo nodeValue.

Objetos NamedNodeMap

NamedNodeMap no hereda de Node.

NamedNodeMap.length

La longitud de la lista de atributos.

NamedNodeMap.item(index)

Retorna un atributo con un índice particular. El orden en los que obtienes los atributos es arbitrario pero será consistente en la vida de un DOM. Cada item es un nodo atributo. Obtén su valor con el atributo value.

También hay métodos experimentales que dan a esta clase más comportamiento de mapeado. Puedes usarlos o puedes usar la familia de métodos estandarizados getAttribute*() en los objetos Element.

Objetos Comentario

Comment representa un comentario en el documento XML. Es una subclase de Node, pero no puede tener hijos nodo.

Comment.data

El contenido del comentario como una cadena de caracteres. El atributo contiene todos los caracteres entre el <!-- que empieza y el --> que termina, pero no los incluye.

Objetos Texto y CDATASection

La interfaz Text representa el texto en el documento XML. Si el analizador y la implementación del DOM soporta la extensión XML del DOM, las porciones de texto rodeadas secciones marcadas como CDATA se guardan en objetos CDATASection. Estas dos interfaces son idénticas, pero proveen valores diferentes para el atributo nodeType.

Estas interfaces extienden la interfaz Node. No pueden tener nodos hijo.

Text.data

El contenido del nodo texto como una cadena de caracteres.

Nota

El uso de un nodo CDATASection no indica que el nodo represente una sección completa marcada como CDATA, sólo que el contenido del nodo fue parte de una sección CDATA. Una sola sección CDATA puede ser representada por más de un nodo en el árbol del documento. No hay manera de determinar si dos nodos adyacentes CDATASection son representados diferentes a secciones marcadas como CDATA.

Objetos ProcessingInstruction

Representa una instrucción de procesamiento en el documento XML; hereda de la interfaz Node y no puede tener hijos.

ProcessingInstruction.target

El contenido de la instrucción de procesamiento hasta el carácter en blanco. Este es un atributo de sólo lectura.

ProcessingInstruction.data

El contenido de la instrucción de procesamiento después del primer carácter en blanco.

Excepciones

La recomendación del DOM nivel 2 define una sola excepción, DOMException, y un número de constantes que permite que las aplicaciones determinen qué tipo de error ocurrió. las instancias de DOMException llevan un atributo code que proporciona el valor apropiado para la excepción específica.

La interfaz DOM de Python provee las constantes, pero también expande el conjunto de excepciones para que exista una excepción específica para cada uno de los códigos de excepción definidos por el DOM. Las implementaciones deben lanzar la excepción específica apropiada, cada uno de los cuales lleva el valor apropiado para el atributo code.

exception xml.dom.DOMException

Clase base de excepción usada para todas las excepciones del DOM específicas. Esta clase de excepción no puede ser instanciada directamente.

exception xml.dom.DomstringSizeErr

Lanzado cuando un rango de texto específico no cabe en una cadena de caracteres. No se sabe si se usa in las implementación DOM de Python, pero puede ser recibido de otras implementaciones DOM que no hayan sido escritas en Python.

exception xml.dom.HierarchyRequestErr

Lanzado cuando se intenta insertar un nodo donde el tipo de nodo no es permitido.

exception xml.dom.IndexSizeErr

Lanzado cuando un parámetro del índice o tamaño de un método es negativo o excede los valores permitidos.

exception xml.dom.InuseAttributeErr

Lanzado cuando se intenta insertar un nodo Attr que está presente en algún lado en el documento.

exception xml.dom.InvalidAccessErr

Lanzado si un parámetro o una operación no es soportada por el objeto subyacente.

exception xml.dom.InvalidCharacterErr

Esta excepción es lanzada cuando un parámetro de cadena de caracteres contiene un carácter que no está permitido en el contexto que está siendo usado por la recomendación XML 1.0. Por ejemplo, intentar crear un nodo Element con un espacio en el nombre del tipo de elemento causará que se lance este error.

exception xml.dom.InvalidModificationErr

Lanzado cuando se intenta modificar el tipo de un nodo.

exception xml.dom.InvalidStateErr

Lanzado cuando se intenta usar un objeto que no está definido o ya no es usable.

exception xml.dom.NamespaceErr

Si se intenta cambiar cualquier objeto de forma que no sea permitida con respecto a la recomendación Namespaces in XML [https://www.w3.org/TR/REC-xml-names/], esta excepción es lanzada.

exception xml.dom.NotFoundErr

Excepción cuando un nodo no existe en el contexto referenciado. Por ejemplo, NamedNodeMap.removeNamedItem() será lanzado si el nodo pasado no existe en el mapa.

exception xml.dom.NotSupportedErr

Lanzado cuando la implementación no soporta el tipo requerido del objeto u operación.

exception xml.dom.NoDataAllowedErr

Es lanzado si se especifican datos para un nodo que no soporta datos.

exception xml.dom.NoModificationAllowedErr

Lanzado cuando se intenta modificar un objeto donde las modificaciones no son permitidas (tal como los nodos de sólo-lectura).

exception xml.dom.SyntaxErr

Lanzado cuando se especifica una cadena de caracteres inválida o ilegal.

exception xml.dom.WrongDocumentErr

Lanzado cuando un nodo es insertado en un documento diferente al que este actualmente pertenece, y la implementación no soporta migrar el nodo de un documento a otro.

Los códigos de excepción definidos en la recomendación del DOM se mapean a las excepciones descritas arriba de acuerdo a esta tabla:

Constante

Excepción

DOMSTRING_SIZE_ERR

DomstringSizeErr

HIERARCHY_REQUEST_ERR

HierarchyRequestErr

INDEX_SIZE_ERR

IndexSizeErr

INUSE_ATTRIBUTE_ERR

InuseAttributeErr

INVALID_ACCESS_ERR

InvalidAccessErr

INVALID_CHARACTER_ERR

InvalidCharacterErr

INVALID_MODIFICATION_ERR

InvalidModificationErr

INVALID_STATE_ERR

InvalidStateErr

NAMESPACE_ERR

NamespaceErr

NOT_FOUND_ERR

NotFoundErr

NOT_SUPPORTED_ERR

NotSupportedErr

NO_DATA_ALLOWED_ERR

NoDataAllowedErr

NO_MODIFICATION_ALLOWED_ERR

NoModificationAllowedErr

SYNTAX_ERR

SyntaxErr

WRONG_DOCUMENT_ERR

WrongDocumentErr

Conformidad

Esta sección describe los requisitos de conformidad y las relaciones entre el DOM API de Python, las recomendaciones del DOM del W3C, y el mapeo OMG IDL para Python.

Mapeo de tipos

Los tipos IDL usados en la especificación del DOM son mapeados a los tipos de tipos de Python de acuerdo a la siguiente tabla.

Tipo IDL

Tipo en Python

boolean

bool o int

int

int

long int

int

unsigned int

int

DOMString

str o bytes

null

None

Métodos de acceso (accessor)

El mapeo de OMG IDL a python define funciones de acceso para las declaraciones del atributo IDL de la que misma forma en que el mapeo de Java lo hace. Mapear las declaraciones IDL:

readonly attribute string someValue;
         attribute string anotherValue;

produce tres funciones de acceso: un método «get» para someValue (_get_someValue()), y métodos «get» y «set» para anotherValue (_get_anotherValue() y _set_anotherValue()). El mapeado, en particular, no requiere que los atributos IDL sean accesibles como los atributos normales de Python: No es obligatorio que object.someValue funcione, y puede lanzar un AttributeError.

El DOM API de Python, sin embargo, si requiere que los atributos de acceso normales funcionen. Esto significa que no es probable que los típicos sustitutos generados por compiladores de IDL en Python funcionen, y los objetos envoltorio (wrapper) pueden ser necesarios en el cliente si los objetos del DOM son accedidos mediante CORBA. Mientras que esto requiere consideraciones adicionales para clientes DOM en CORBA, los implementadores con experiencia que usen DOM por encima de CORBA desde Python no lo consideran un problema. Los atributos que se declaran readonly pueden no restringir el acceso de escritura en todas las implementaciones DOM.

En el DOM API de Python, las funciones de acceso no son obligatorias. Si se proveen, deben tomar la forma definida por el mapeo IDL de Python, pero estos métodos se consideran innecesarios debido a que los atributos son accesibles directamente desde Python. Nunca se deben proporcionar métodos de acceso (accessor) «Set» para los atributos readonly.

Las definiciones de IDL no encarnan los requisitos del DOM API del W3C por completo, como las nociones de ciertos objetos, como el valor de retorno getElementsByTagName(), siendo «live». El DOM API de Python no requiere que las implementaciones hagan cumplir tales requisitos.

xml.dom.minidom — Implementación mínima del DOM

Código fuente: Lib/xml/dom/minidom.py [https://github.com/python/cpython/tree/3.9/Lib/xml/dom/minidom.py]

xml.dom.minidom es una implementación mínima de la interfaz Document Object Model (Modelo de objetos del documento), con una API similar a la de otros lenguajes. Está destinada a ser más simple que una implementación completa del DOM y también significativamente más pequeña. Aquellos usuarios que aún no dominen el DOM deberían considerar usar el módulo xml.etree.ElementTree en su lugar para su procesamiento XML.

Advertencia

El módulo xml.dom.minidom no es seguro contra datos construidos maliciosamente. Si necesitas analizar datos que no son de confianza o no autenticados, consulta Vulnerabilidades XML.

Las aplicaciones DOM suelen comenzar analizando algún XML en un DOM. Con xml.dom.minidom, esto se hace a través de las funciones de análisis sintáctico:

from xml.dom.minidom import parse, parseString

dom1 = parse('c:\\temp\\mydata.xml')  # parse an XML file by name

datasource = open('c:\\temp\\mydata.xml')
dom2 = parse(datasource)  # parse an open file

dom3 = parseString('<myxml>Some data<empty/> some more data</myxml>')

La función parse() puede tomar un nombre de archivo o un objeto de archivo previamente abierto.

xml.dom.minidom.parse(filename_or_file, parser=None, bufsize=None)

Retorna un Document a partir de la entrada dada. filename_or_file puede ser un nombre de archivo o un objeto similar a un archivo. parser, si se proporciona, debe ser un objeto de un analizador sintáctico SAX2. Esta función intercambiará el controlador de documentos del analizador sintáctico y activará el soporte con el espacio de nombres. Otras configuraciones del analizador sintáctico (como configurar un solucionador de entidades) deben haberse realizado de antemano.

Si tienes XML en una cadena de caracteres, puedes usar la función parseString() en su lugar:

xml.dom.minidom.parseString(string, parser=None)

Retorna un objeto Document que representa a string. Este método crea un objeto io.StringIO para la cadena de caracteres y lo pasa a parse().

Ambas funciones retornan un objeto Document que representa el contenido del documento.

Lo que hacen las funciones parse() y parseString() es conectar un analizador sintáctico de XML con un «constructor DOM» que puede aceptar eventos de análisis de cualquier analizador sintáctico SAX y convertirlos en un árbol DOM. El nombre de las funciones es quizás engañoso, pero es fácil de entender cuando se comprenden las interfaces. El análisis sintáctico del documento se completará antes de que retornen estas funciones, dichas funciones simplemente no proporcionan una implementación del analizador sintáctico por si mismas.

También puedes crear un objeto Document invocando a un método en un objeto de la «Implementación del DOM». Puedes obtener este objeto llamando a la función getDOMImplementation() del paquete xml.dom o del módulo xml.dom.minidom. Una vez que tengas un objeto Document, puedes agregarle nodos secundarios para llenar el DOM:

from xml.dom.minidom import getDOMImplementation

impl = getDOMImplementation()

newdoc = impl.createDocument(None, "some_tag", None)
top_element = newdoc.documentElement
text = newdoc.createTextNode('Some textual content.')
top_element.appendChild(text)

Una vez que tengas un objeto del documento DOM, puedes acceder a las partes de tu documento XML a través de sus propiedades y métodos. Estas propiedades se definen en la especificación DOM. La propiedad principal del objeto del documento es documentElement. Te proporciona el elemento principal en el documento XML: el que contiene a todos los demás. Aquí hay un programa de ejemplo:

dom3 = parseString("<myxml>Some data</myxml>")
assert dom3.documentElement.tagName == "myxml"

Cuando hayas terminado con un árbol DOM, puedes invocar opcionalmente el método unlink() para forzar la limpieza temprana de los objetos ahora innecesarios. unlink() es una extensión de la API del DOM específica del módulo xml.dom.minidom, que hace que el nodo y sus descendientes sean esencialmente inútiles. En caso de no hacer uso de esto, eventualmente el recolector de basura de Python se hará cargo de los objetos en el árbol.

Ver también

Document Object Model (DOM) Level 1 Specification [https://www.w3.org/TR/REC-DOM-Level-1/]

La recomendación del W3C para el DOM soportada por el módulo xml.dom.minidom.

Objetos del DOM

La definición de la API del DOM para Python se proporciona como parte de la documentación del módulo xml.dom. Esta sección simplemente enumera las diferencias entre esta API y el módulo xml.dom.minidom.

Node.unlink()

Rompe las referencias internas dentro del DOM para recolectarlo como basura en las versiones de Python sin recolector de basura cíclico. Incluso cuando se dispone del mismo, su uso puede hacer que grandes cantidades de memoria estén disponibles antes, por lo que es una buena práctica invocar este método en objetos DOM, tan pronto como ya no se necesiten. Solo necesita ser invocado en el objeto Document, pero se puede llamar en los nodos hijos para descartar los hijos de ese nodo concreto.

Puedes evitar invocar este método explícitamente utilizando la declaración with. El siguiente código desvinculará automáticamente dom cuando se salga del bloque with:

with xml.dom.minidom.parse(datasource) as dom:
    ... # Work with dom.

Node.writexml(writer, indent="", addindent="", newl="", encoding=None, standalone=None)

Escribe XML en el objeto escritor. El escritor recibe texto pero no bytes como entrada, debe tener un método write() que coincida con el de la interfaz del objeto de archivo. El parámetro indent es la sangría del nodo actual. El parámetro addindent es la sangría incremental que se utilizará para los subnodos del nodo actual. El parámetro newl especifica la cadena que se utilizará como terminación de las nuevas líneas.

Para el nodo Document, se puede usar el argumento por palabra clave adicional encoding para especificar el valor del campo de codificación del encabezado XML.

Similarly, explicitly stating the standalone argument causes the standalone document declarations to be added to the prologue of the XML document. If the value is set to True, standalone=»yes» is added, otherwise it is set to «no». Not stating the argument will omit the declaration from the document.

Distinto en la versión 3.8: El método writexml() ahora conserva el orden de los atributos especificado por el usuario.

Distinto en la versión 3.9: The standalone parameter was added.

Node.toxml(encoding=None, standalone=None)

Retorna una cadena de caracteres o una cadena de bytes que contiene el XML representado por el nodo DOM.

Si se proporciona de forma explícita un valor para el argumento encoding 1, el resultado es una cadena de bytes con la codificación especificada. Si no se proporciona el argumento encoding, el resultado es una cadena Unicode y la declaración XML en la cadena resultante no especifica una codificación. Codificar esta cadena en una codificación que no sea UTF-8 probablemente sea una práctica incorrecta, ya que UTF-8 es la codificación predeterminada para XML.

El argumento standalone se comporta exactamente como en writexml().

Distinto en la versión 3.8: El método toxml() ahora conserva el orden de los atributos especificado por el usuario.

Distinto en la versión 3.9: The standalone parameter was added.

Node.toprettyxml(indent="\t", newl="\n", encoding=None, standalone=None)

Retorna una versión impresa elegante del documento. indent especifica la cadena de caracteres a usar como sangría y es una tabulación por defecto; newl especifica la cadena de caracteres emitida al final de cada línea y es \n por defecto.

El argumento encoding se comporta como el argumento correspondiente del método toxml().

El argumento standalone se comporta exactamente como en writexml().

Distinto en la versión 3.8: El método toprettyxml() ahora conserva el orden de los atributos especificado por el usuario.

Distinto en la versión 3.9: The standalone parameter was added.

Ejemplo de DOM

Este programa de ejemplo es una demostración bastante realista de un programa simple. En este caso particular, no aprovechamos mucho la flexibilidad del DOM.

import xml.dom.minidom

document = """\
<slideshow>
<title>Demo slideshow</title>
<slide><title>Slide title</title>
<point>This is a demo</point>
<point>Of a program for processing slides</point>
</slide>

<slide><title>Another demo slide</title>
<point>It is important</point>
<point>To have more than</point>
<point>one slide</point>
</slide>
</slideshow>
"""

dom = xml.dom.minidom.parseString(document)

def getText(nodelist):
    rc = []
    for node in nodelist:
        if node.nodeType == node.TEXT_NODE:
            rc.append(node.data)
    return ''.join(rc)

def handleSlideshow(slideshow):
    print("<html>")
    handleSlideshowTitle(slideshow.getElementsByTagName("title")[0])
    slides = slideshow.getElementsByTagName("slide")
    handleToc(slides)
    handleSlides(slides)
    print("</html>")

def handleSlides(slides):
    for slide in slides:
        handleSlide(slide)

def handleSlide(slide):
    handleSlideTitle(slide.getElementsByTagName("title")[0])
    handlePoints(slide.getElementsByTagName("point"))

def handleSlideshowTitle(title):
    print("<title>%s</title>" % getText(title.childNodes))

def handleSlideTitle(title):
    print("<h2>%s</h2>" % getText(title.childNodes))

def handlePoints(points):
    print("<ul>")
    for point in points:
        handlePoint(point)
    print("</ul>")

def handlePoint(point):
    print("<li>%s</li>" % getText(point.childNodes))

def handleToc(slides):
    for slide in slides:
        title = slide.getElementsByTagName("title")[0]
        print("<p>%s</p>" % getText(title.childNodes))

handleSlideshow(dom)

minidom y el estándar DOM

El módulo xml.dom.minidom es esencialmente un DOM compatible con DOM 1.0, con algunas características de DOM 2 (principalmente características del espacio de nombres).

El uso de la interfaz DOM en Python es sencillo. Se aplican las siguientes reglas de mapeo:

Se accede a las interfaces a través de objetos de instancia. Las aplicaciones no deben instanciar las clases en sí mismas; deben usar las funciones de creación disponibles en el objeto Document. Las interfaces derivadas admiten todas las operaciones (y atributos) de las interfaces base, además de cualquier operación nueva.

Las operaciones se utilizan como métodos. Dado que el DOM usa solo parámetros in, los argumentos se pasan en el orden normal (de izquierda a derecha). No hay argumentos opcionales. Las operaciones void retornan None.

Los atributos IDL se asignan a atributos de instancia. Por compatibilidad con el mapeo del lenguaje OMG IDL para Python, también se puede acceder a un atributo foo a través de los métodos de acceso _get_foo() y _set_foo(). Los atributos readonly no deben modificarse; esto no se aplica en tiempo de ejecución.

Los tipos short int, unsigned int, unsigned long long y boolean se asignan todos a objetos enteros de Python.

El tipo DOMString se asigna a cadenas de caracteres de Python. El módulo xml.dom.minidom admite bytes o cadenas de caracteres, pero normalmente producirá cadenas de caracteres. Los valores de tipo DOMString también pueden ser None cuando la especificación DOM del W3C permite tener el valor IDL null.

Las declaraciones const se asignan a variables en su ámbito respectivo (por ejemplo, xml.dom.minidom.Node.PROCESSING_INSTRUCTION_NODE); no deben modificarse.

DOMException no está actualmente soportado por el módulo xml.dom.minidom. En su lugar, xml.dom.minidom usa excepciones estándar de Python como TypeError y AttributeError.

Los objetos de la clase NodeList se implementan usando el tipo lista incorporado de Python. Estos objetos proporcionan la interfaz definida en la especificación DOM, pero en versiones anteriores de Python no son compatibles con la API oficial. Sin embargo, son mucho más «pythónicas» que la interfaz definida en las recomendaciones del W3C.

Las siguientes interfaces no están implementadas en el módulo xml.dom.minidom:

DOMTimeStamp

EntityReference

La mayoría de ellas reflejan información en el documento XML que generalmente no es de utilidad para la mayoría de los usuarios de DOM.

Notas al pie

1

El nombre de codificación incluido en la salida XML debe cumplir con los estándares apropiados. Por ejemplo, «UTF-8» es válido, pero «UTF8» no es válido en la declaración de un documento XML, aunque Python lo acepta como nombre de codificación. Para más detalles, consulta https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl y https://www.iana.org/assignments/character-sets/character-sets.xhtml.

xml.dom.pulldom — Soporte para la construcción parcial de árboles DOM

Source code: Lib/xml/dom/pulldom.py [https://github.com/python/cpython/tree/3.9/Lib/xml/dom/pulldom.py]

El módulo xml.dom.pulldom proporciona un «pull parser» al que también se le puede pedir que produzca DOM-fragmentos del documento accesibles cuando sea necesario. El concepto básico implica extraer «eventos» desde una secuencia (stream) de entrada XML y procesarlos. A diferencia de SAX, que también emplea un modelo de procesamiento orientado a eventos junto con callbacks (retrollamada), el usuario de un analizador de extracción (pull parser) es responsable de extraer explícitamente eventos de la secuencia, recorriendo esos eventos hasta que finalice el procesamiento o se produzca una condición de error.

Advertencia

El módulo xml.dom.pulldom no es seguro contra datos maliciosamente construidos . Si necesita analizar datos que no son confiables o no autenticados, consulte Vulnerabilidades XML.

Distinto en la versión 3.7.1: El analizador SAX ya no procesa entidades externas generales de forma predeterminada para aumentar la seguridad de forma predeterminada. Para habilitar el procesamiento de entidades externas, pase una instancia de analizador personalizada (custom parser instance in::)

from xml.dom.pulldom import parse
from xml.sax import make_parser
from xml.sax.handler import feature_external_ges

parser = make_parser()
parser.setFeature(feature_external_ges, True)
parse(filename, parser=parser)

Ejemplo:

from xml.dom import pulldom

doc = pulldom.parse('sales_items.xml')
for event, node in doc:
    if event == pulldom.START_ELEMENT and node.tagName == 'item':
        if int(node.getAttribute('price')) > 50:
            doc.expandNode(node)
            print(node.toxml())

event es una constante y puede ser uno de:

START_ELEMENT (Iniciar elemento)

END_ELEMENT (Finalizar elemento)

COMMENT (comentario)

START_DOCUMENT (Iniciar documento)

END_DOCUMENT (finalizar documento)

CHARACTERS (caracteres)

PROCESSING_INSTRUCTION (instrucción de procesamiento)

IGNORABLE_WHITESPACE (Espacio en blanco que puede ignorarse)

node es un objeto del tipo xml.dom.minidom.Document, xml.dom.minidom.Element ó xml.dom.minidom.Text.

Puesto que el documento se trata como una secuencia «flat» (plana) de eventos, el documento «tree» (árbol) se atraviesa implícitamente y los elementos deseados se encuentran independientemente de su profundidad en el árbol. En otras palabras, no es necesario tener en cuenta cuestiones jerárquicas como la búsqueda recursiva de los nodos de documento, aunque si el contexto de los elementos fuera importante, es necesario mantener algún estado relacionado con el contexto (es decir, recordar dónde se encuentra en el documento en un momento dado) o hacer uso del método DOMEventStream.expandNode() y cambiar al procesamiento relacionado con DOM.

class xml.dom.pulldom.PullDom(documentFactory=None)

Subclase de xml.sax.handler.ContentHandler.

class xml.dom.pulldom.SAX2DOM(documentFactory=None)

Subclase de xml.sax.handler.ContentHandler.

xml.dom.pulldom.parse(stream_or_string, parser=None, bufsize=None)

Retorna un DOMEventStream de la entrada dada. stream_or_string (secuencia o cadena) puede ser un nombre de archivo o un objeto similar a un archivo, parser, si se indica, debe ser un objeto XMLReader. Esta función cambiará el controlador de documentos del analizador y activará el soporte de espacios de nombres; otra configuración del analizador (como establecer un solucionador de entidades) debe haberse realizado de antemano.

Si tiene XML en una cadena, puede usar en su lugar la función parseString():

xml.dom.pulldom.parseString(string, parser=None)

Retorna una: clase DOMEventStream que representa la cadena (Unicode) strnig (cadena)

xml.dom.pulldom.default_bufsize

Valor predeterminado para el parámetro bufsize para parse().

El valor de las variables puede ser cambiado antes de llamar a parse() y el nuevo valor tendrá efecto.

Objetos DOMEventStream

class xml.dom.pulldom.DOMEventStream(stream, parser, bufsize)

Obsoleto desde la versión 3.8: El soporte para sequence protocol está obsoleto.

getEvent()

Retorna el contenido de la tupla event y del node corriente como xml.dom.minidom.Document si el evento es igual a START_DOCUMENT, xml.dom.minidom.Element si el evento es igual a START_ELEMENT o END_ELEMENT o xml.dom.minidom.Text si el evento es igual a CHARACTERS. El nodo actual no es contiene información sobre sus hijos a menos que se llame a la función expandNode().

expandNode(node)

Expande todos los hijos de node en node (nodo en nodo). Ejemplo:

from xml.dom import pulldom

xml = '<html><title>Foo</title> <p>Some text <div>and more</div></p> </html>'
doc = pulldom.parseString(xml)
for event, node in doc:
    if event == pulldom.START_ELEMENT and node.tagName == 'p':
        # Following statement only prints '<p/>'
        print(node.toxml())
        doc.expandNode(node)
        # Following statement prints node with all its children '<p>Some text <div>and more</div></p>'
        print(node.toxml())

reset()

XML.sax— Soporte para analizadores SAX2

Código fuente: Lib/xml/sax/__init__.py [https://github.com/python/cpython/tree/3.9/Lib/xml/sax/__init__.py]

El paquete xml.sax provee un número de módulos que implementan la API Simple para la interfaz XML (SAX) para Python. El paquete mismo provee las excepciones SAX y las funciones de conveniencia que serán las más usadas por los usuarios de la API SAX.

Advertencia

El módulo XML.sax no es seguro contra datos construidos maliciosamente. Si necesita analizar datos no autenticados o no confiables, mirar Vulnerabilidades XML.

Distinto en la versión 3.7.1: El analizador SAX ya no procesa entidades generales externas por defecto para incrementar seguridad. Antes, el analizador creaba conexiones de red para buscar archivos remotos o archivos locales cargados del sistema de archivos para DTD y entidades. La característica puede ser activadas de nuevo con el método setFeature() en el objeto analizador y el argumento feature_external_ges.

Las funciones de conveniencia son:

xml.sax.make_parser(parser_list=[])

Crea y retorna un objeto SAX XMLReader. El primer analizador encontrado será el que se use. Si se provee parser_list, debe ser un iterable de cadenas de caracteres el cual nombra módulos que tienen una función llamada créate_parser(). Los módulos listados en parser_list serán usados antes de los módulos en la lista de analizadores por defecto.

Distinto en la versión 3.8: El argumento parser_list puede ser cualquier iterable, no sólo una lista.

xml.sax.parse(filename_or_stream, handler, error_handler=handler.ErrorHandler())

Crea un analizador SAD y úsalo para analizar un documento. El documento, aprobado como filename_or_steam, puede ser un nombre de archivo o un objeto de archivo. El parámetro handler necesita ser una instancia SAX ContentHandler. Si se da error_handler, debe ser una instancia ErrorHandler SAX; si es omitido, se lanzará SAXParseException en todos los errores. No hay valor retornado; toda tarea debe ser realizada por el handler aprobado.

xml.sax.parseString(string, handler, error_handler=handler.ErrorHandler())

Similar a parser(), pero analiza desde un búfer string recibido como un parámetro. string debe ser una instancia str o un bytes-like object.

Distinto en la versión 3.5: Agregado soporte de instancias str.

Una aplicación SAX típica usa tres tipos de objetos: lectores, gestores y fuentes de entrada. «Lector» en este contexto es otro término para analizador, por ejemplo, alguna pieza de código que lee los bytes o caracteres de la fuente de entrada, y produce una secuencia de eventos. Los eventos luego se distribuyen a los objetos gestores, por ejemplo el lector invoca un método en el gestor. Una aplicación SAX debe por tanto obtener un objeto lector, crear o abrir una fuente de entrada, crear los gestores, y conectar esos objetos juntos. Como paso final de preparación, el lector es llamado para analizar la entrada. Durante el análisis, los métodos en los objetos gestores son llamados basados en eventos estructurales y sintácticos de los datos introducidos.

Para estos objetos, sólo las interfaces son relevantes; éstos normalmente no son instanciados por la aplicación misma. Ya que Python no tiene una noción explícita de interfaz, éstas son introducidas formalmente como clases, pero las aplicaciones suelen usar implementaciones que no heredan de las clases provistas. Las interfaces InputSource, Locator, Attributes, AttributesNS, y XMLReader son definidas en el módulo xml.sax.xmlreader. Las interfaces de gestión son definidas en xml.sax.handler. Por conveniencia, InputSource (el cual suele ser instanciado directamente) y el gestor de clases están también disponibles desde xml.sax Estas interfaces son descritas a continuación.

En adición a esas clases, xml.sax provee las siguientes clases de excepción.

exception xml.sax.SAXException(msg, exception=None)

Encapsula un error XML o advertencia. Esta clase puede contener errores básicos o información de advertencias ya sea para el analizador XML o la aplicación: esto puede ser heredado para proveer funcionalidad adicionar o para agregar localización. Nota que a pesar de los analizadores definidos en la interfaz ErrorHandler recibe instancias de esta excepción, no es requerido para lanzar la excepción — esto es algo útil como un contenedor para información.

Cuando es instanciado, msg debería ser una descripción del error legible para humanos. El parámetro opcional exception, si es dado, debería ser None o una excepción que fue atrapada por el código analizador y se transmite como información.

Esta es la clase base para las otras clases excepción SAX.

exception xml.sax.SAXParseException(msg, exception, locator)

Subclase de SAXException levantada en errores de análisis. Las instancias de esta clase son pasadas a los métodos de las interfaces SAX ErrorHandler para proveer información sobre el error de análisis. Esta clase soporta la interfaz SAX Locator así como la interfaz SAXException.

exception xml.sax.SAXNotRecognizedException(msg, exception=None)

Subclase de SAXException lanzada cuando una SAX XMLReader es confrontada con una propiedad o característica no reconocida. Las aplicaciones SAX y extensiones pueden usar esta clase para propósitos similares.

exception xml.sax.SAXNotSupportedException(msg, exception=None)

Las subclases de SAXException se lanzan cuando un SAX sax se pregunta para habilitar una característica que no tiene soporte, o para establecer una propiedad a un valor que la implementación no da soporte. Las aplicaciones sAX y las extensiones pueden usar esta clase para propósitos similares.

Ver también

SAX: The Simple API for XML [http://www.saxproject.org/]

Este sitio es el punto focal para la definición de la API SAX. Provee una implementación Java y documentación en línea. Los enlaces para implementaciones e información histórica también están disponibles.

Módulo xml.sax.handler

Definiciones de las interfaces para objetos proporcionados por aplicaciones.

Módulo xml.sax.saxutils

Funciones de conveniencia para usar en aplicaciones SAX.

Módulo xml.sax.xmlreader

Definiciones de las interfaces para objetos que proveen analizadores.

Objetos SAXException

La clase de excepción SAXException da soporte a los siguientes métodos:

SAXException.getMessage()

Retorna un mensaje legible para humanos describiendo la condición de error.

SAXException.getException()

Retorna un objeto excepción encapsulado, o None.

xml.sax.handler — Clases base para los handlers SAX

Source code Lib/xml/sax/handler.py [https://github.com/python/cpython/tree/3.9/Lib/xml/sax/handler.py]

La API de SAX define cuatro tipos de manejadores: manejadores de contenido, manejadores de DTD, manejadores de errores y resolvedores de entidades. Normalmente, las aplicaciones sólo necesitan implementar las interfaces cuyos eventos les interesan; pueden implementar las interfaces en un solo objeto o en múltiples objetos. Las implementaciones de los manejadores deben heredar de las clases base provistas en el módulo xml.sax.handler, de modo que todos los métodos obtengan implementaciones por defecto.

class xml.sax.handler.ContentHandler

Esta es la principal interfaz de devolución de llamada en el SAX, y la más importante para las aplicaciones. El orden de los eventos en esta interfaz refleja el orden de la información en el documento.

class xml.sax.handler.DTDHandler

Manejar eventos de DTD.

Esta interfaz especifica sólo los eventos DTD necesarios para el análisis básico (entidades y atributos no analizados).

class xml.sax.handler.EntityResolver

Interfaz básica para resolver entidades. Si creas un objeto implementando esta interfaz, y luego registras el objeto con tu Parser, el parser (analizador) invocara al método en tu objeto para resolver todas las entidades externas.

class xml.sax.handler.ErrorHandler

Interfaz utilizada por el parser para presentar mensajes de error y advertencia a la aplicación. Los métodos de este objeto controlan si los errores se convierten inmediatamente en excepciones o se manejan de alguna otra manera.

Además de estas clases, xml.sax.handler proporciona constantes simbólicas para los nombres de las características y propiedades.

xml.sax.handler.feature_namespaces

value: "http://xml.org/sax/features/namespaces"

true: Realizar el procesamiento del Namespace (espacio de nombres).

false: Opcionalmente no realizar el procesamiento del Namespace (espacio de nombres) (implica prefijos de espacio de nombres; por defecto).

acceso: (parsing) sólo de lectura; (not parsing) lectura/escritura

xml.sax.handler.feature_namespace_prefixes

value: "http://xml.org/sax/features/namespace-prefixes"

true: Reporte de los nombres prefijados originales y los atributos utilizados para las declaraciones del Namespace (espacio de nombres).

false: No informar de los atributos utilizados para las declaraciones del Namespace (espacio de nombres), y opcionalmente no informar de los nombres prefijados originales (por defecto).

acceso: (parsing) sólo de lectura; (not parsing) lectura/escritura

xml.sax.handler.feature_string_interning

value: "http://xml.org/sax/features/string-interning"

true: Todos los nombres de elementos, prefijos, nombres de atributos, URIs del Namespace (espacio de nombres) y nombres locales son internados usando la función interna incorporada.

false: Los nombres no están necesariamente internados, aunque pueden estarlo (por defecto).

acceso: (parsing) sólo de lectura; (not parsing) lectura/escritura

xml.sax.handler.feature_validation

value: "http://xml.org/sax/features/validation"

true: Reportar de todos los errores de validación (implica entidades generales externas y entidades de parámetros externos).

false: No informe de los errores de validación.

acceso: (parsing) sólo de lectura; (not parsing) lectura/escritura

xml.sax.handler.feature_external_ges

value: "http://xml.org/sax/features/external-parameter-entities"

true: Incluye todas las entidades externas generales de texto (text).

false: No incluya entidades generales externas.

acceso: (parsing) sólo de lectura; (not parsing) lectura/escritura

xml.sax.handler.feature_external_pes

value: "http://xml.org/sax/features/external-parameter-entities"

true: Incluye todas las entidades paramétricas externas, incluyendo el subconjunto DTD externo.

false: No incluya ninguna entidad paramétrica externa, ni siquiera el subconjunto DTD externo.

acceso: (parsing) sólo de lectura; (not parsing) lectura/escritura

xml.sax.handler.all_features

Lista de todas las características.

xml.sax.handler.property_lexical_handler

value: "http://xml.org/sax/properties/lexical-handler"

data type: xml.sax.sax2lib.LexicalHandler (no soportado en Python 2)

descripción: Un handler (manipulador) de extensión opcional para eventos léxicos como los comentarios.

acceso: read/write (leer/escribir)

xml.sax.handler.property_declaration_handler

value: "http://xml.org/sax/properties/declaration-handler"

data type: xml.sax.sax2lib.DeclHandler (no soportado en Python 2)

description: Un gestor de extensión opcional para eventos relacionados con la DTD que no sean anotaciones y entidades no preparadas.

acceso: read/write (leer/escribir)

xml.sax.handler.property_dom_node

value: "http://xml.org/sax/properties/dom-node"

data type: org.w3c.dom.Node (not supported in Python 2)

descripción: Cuando se analiza, el nodo DOM actual que se visita si se trata de un iterador DOM; cuando no se analiza, el nodo DOM raíz para la iteración.

acceso: (parsing) sólo de lectura; (not parsing) lectura/escritura

xml.sax.handler.property_xml_string

value: "http://xml.org/sax/properties/xml-string"

data type: Bytes

description: La cadena literal de caracteres que fue la fuente del evento actual.

acceso: solo-lectura

xml.sax.handler.all_properties

Lista de todos los nombres de propiedades conocidas.

Objetos ContentHandler

Se espera que los usuarios subclasifiquen ContentHandler para apoyar su aplicación. Los siguientes métodos son llamados por el analizador en los eventos apropiados en el documento de entrada:

ContentHandler.setDocumentLocator(locator)

Invocado por el parser (analizador) para dar a la aplicación un localizador para determinar el origen de los eventos del documento.

Se recomienda encarecidamente a los parsers (analizadores) SAX (aunque no es absolutamente necesario) que proporcionen un localizador: si lo hace, debe proporcionar el localizador a la aplicación invocando este método antes de invocar cualquiera de los otros métodos de la interfaz DocumentHandler.

El localizador permite a la aplicación determinar la posición final de cualquier evento relacionado con el documento, incluso si el analizador no informa de un error. Normalmente, la aplicación utilizará esta información para informar de sus propios errores (como el contenido de los caracteres que no coinciden con las reglas de negocio de la aplicación). Es probable que la información retornada por el localizador no sea suficiente para su uso con un motor de búsqueda.

Tenga en cuenta que el localizador retornará la información correcta sólo durante la invocación de los eventos en esta interfaz. La aplicación no debe intentar utilizarlo en ningún otro momento.

ContentHandler.startDocument()

Recibir la notificación del inicio de un documento.

El parser (analizador) SAX invocará este método sólo una vez, antes que cualquier otro método en esta interfaz o en DTDHandler (excepto setDocumentLocator()).

ContentHandler.endDocument()

Recibir una notificación del final de un documento.

El analizador (parser) SAX invocará este método sólo una vez, y será el último método invocado durante el análisis. El analizador no invocará este método hasta que no haya abandonado el análisis sintáctico (debido a un error irrecuperable) o haya llegado al final de la entrada.

ContentHandler.startPrefixMapping(prefix, uri)

Comienza el alcance de un mapeo del prefijo-URI Namespace.

La información de este evento no es necesaria para el procesamiento normal del Namespace (espacio de nombres): el lector de XML SAX sustituirá automáticamente los prefijos de los nombres de elementos y atributos cuando se active la función feature_namespaces default (el valor por defecto).

Sin embargo, hay casos en que las aplicaciones necesitan utilizar prefijos en los datos de los caracteres o en los valores de los atributos, en los que no se pueden expandir automáticamente de forma segura; los eventos startPrefixMapping() y endPrefixMapping() suministran la información a la aplicación para expandir los prefijos en esos contextos por sí mismos, si es necesario.

Note que los eventos startPrefixMapping() y endPrefixMapping() no están garantizados de estar apropiadamente anidados en relación a cada uno: todos los eventos startPrefixMapping() ocurrirán antes del correspondiente evento startElement(), y todos los eventos endPrefixMapping() ocurrirán después del correspondiente evento endElement(), pero su orden no está garantizado.

ContentHandler.endPrefixMapping(prefix)

Terminar con el alcance de un mapeo de prefijos-URI.

Ver startPrefixMapping() para más detalles. Este evento siempre ocurrirá después del correspondiente evento endElement(), pero el orden de los eventos endPrefixMapping() no está garantizado.

ContentHandler.startElement(name, attrs)

Señala el inicio de un elemento en modo no espacial.

El parámetro name contiene el nombre XML 1.0 en bruto del tipo de elemento como una cadena y el parámetro attrs contiene un objeto de la interfaz Attributes (véase La Interfaz Attributes) que contiene los atributos del elemento. El objeto pasado como attrs puede ser reutilizado por el parser (analizador); mantener una referencia a él no es una forma fiable de conservar una copia de los atributos. Para guardar una copia de los atributos, usa el método copy() del objeto attrs.

ContentHandler.endElement(name)

Señala el final de un elemento en modo no espacial.

El parámetro name contiene el nombre del tipo de elemento, al igual que con el evento startElement().

ContentHandler.startElementNS(name, qname, attrs)

Señala el inicio de un elemento en el modo de Namespace (espacio de nombres).

El parámetro name contiene el nombre del tipo de elemento como una tupla (uri, localname), el parámetro qname contiene el nombre XML 1.0 en bruto usado en el documento fuente, y el parámetro attrs contiene una instancia de la interfaz AttributesNS (ver La Interfaz AttributesNS) que contiene los atributos del elemento. Si no hay ningún Namespace (espacio de nombres) asociado al elemento, el componente uri de name será Ninguno. El objeto pasado como attrs puede ser reutilizado por el analizador; mantener una referencia a él no es una forma fiable de conservar una copia de los atributos. Para guardar una copia de los atributos, usa el método copy`() del objeto attrs.

Los parsers (analizadores) pueden establecer el parámetro qname como None, a menos que se active la función feature_namespace_prefixes.

ContentHandler.endElementNS(name, qname)

Señala el final de un elemento en el modo de namespace.

El parámetro name contiene el nombre del tipo de elemento, al igual que con el método startElementNS(), así como el parámetro qname.

ContentHandler.characters(content)

Recibir la notificación de los datos de los caracteres.

El Parser (analizador) llamará a este método para informar de cada dato de carácter. Los parsers (analizadores) SAX pueden retornar todos los datos de caracteres contiguos en un solo trozo, o pueden dividirlos en varios trozos; sin embargo, todos los caracteres de un mismo evento deben provenir de la misma entidad externa para que el Localizador proporcione información útil.

content puede ser una cadena o una instancia de bytes; el módulo lector de «Expat» siempre produce cadenas.

Nota

La anterior interfaz SAX 1 proporcionada por el Grupo de Interés Especial de Python XML utilizaba una interfaz más parecida a Java para este método. Dado que la mayoría de los parsers (analizadores) utilizados de Python no aprovecharon la interfaz más antigua, se eligió la firma más simple para reemplazarla. Para convertir el código antiguo en la nueva interfaz, se utilizó content en lugar de cortar el contenido con los antiguos parámetros offset y length.

ContentHandler.ignorableWhitespace(whitespace)

Recibir notificación de espacios en blanco ignorables en el contenido de los elementos.

Los parsers validadores deben utilizar este método para informar de cada trozo de espacio en blanco desconocido (véase la recomendación W3C XML 1.0, sección 2.10): los analizadores no validadores también pueden utilizar este método si son capaces de analizar y utilizar modelos de contenido.

Los parsers (analizadores) SAX pueden retornar todos los espacios blancos contiguos en un solo trozo, o pueden dividirlo en varios trozos; sin embargo, todos los caracteres de un mismo evento deben provenir de la misma entidad externa, para que el Localizador proporcione información útil.

ContentHandler.processingInstruction(target, data)

Recibir la notificación de una instrucción de procesamiento.

El Parser (analizador) invocará este método una vez por cada instrucción de procesamiento encontrada: nótese que las instrucciones de procesamiento pueden ocurrir antes o después del elemento principal del documento.

Un parser (analizador) SAX nunca debe informar de una declaración XML (XML 1.0, sección 2.8) o una declaración de texto (XML 1.0, sección 4.3.1) utilizando este método.

ContentHandler.skippedEntity(name)

Recibir la notificación de una entidad salteada.

El Parser invocará este método una vez por cada entidad omitida. Los procesos no validadores pueden omitir entidades si no han visto las declaraciones (porque, por ejemplo, la entidad fue declarada en un subconjunto DTD externo). Todos los procesos pueden omitir entidades externas, dependiendo de los valores de las propiedades feature_external_ges y feature_external_pes.

Objetos DTDHandler

DTDHandler instancias proporcionan los siguientes métodos:

DTDHandler.notationDecl(name, publicId, systemId)

Manejar un evento de declaración de anotación.

DTDHandler.unparsedEntityDecl(name, publicId, systemId, ndata)

Manejar un evento de declaración de entidad no preparada.

Objetos EntityResolver

EntityResolver.resolveEntity(publicId, systemId)

Resolver el identificador de sistema de una entidad y retornar ya sea el identificador de sistema para leerlo como una cadena, o una fuente de entrada para leerlo. La implementación por defecto retorna systemId.

Objetos ErrorHandler

Los objetos con esta interfaz se usan para recibir información de error y advertencia del XMLReader. Si creas un objeto que implemente esta interfaz, y luego registras el objeto con tu XMLReader, el parser (analizador) invocará a los métodos de tu objeto para informar de todas las advertencias y errores. Hay tres niveles de errores disponibles: advertencias, (posiblemente) errores recuperables y errores no recuperables. Todos los métodos toman un SAXParseException como único parámetro. Los errores y advertencias pueden ser convertidos en una excepción lanzando el objeto de excepción pasado.

ErrorHandler.error(exception)

Invocación cuando el parser (analizador) encuentra un error recuperable. Si este método no lanza una excepción, el análisis sintáctico puede continuar, pero la aplicación no debe esperar más información del documento. Permitir que el parser (analizador) continúe puede permitir que se descubran errores adicionales en el documento de entrada.

ErrorHandler.fatalError(exception)

Invocación cuando el parser (analizador) encuentra un error del que no puede recuperarse; se espera que el análisis sintáctico termine cuando vuelva este método.

ErrorHandler.warning(exception)

Invocación cuando el parser (analizador) presenta información de advertencia menor a la aplicación. Se espera que el análisis sintáctico continúe cuando vuelva este método, y la información del documento seguirá pasando a la aplicación. Si se lanza una excepción con este método, el análisis sintáctico terminará.

xml.sax.saxutils — Utilidades SAX

Código fuente: Lib/xml/sax/saxutils.py [https://github.com/python/cpython/tree/3.9/Lib/xml/sax/saxutils.py]

El módulo xml.sax.saxutils contiene una serie de clases y funciones que son comúnmente útiles al crear aplicaciones SAX, ya sea como uso directo o como clases base.

xml.sax.saxutils.escape(data, entities={})

Escapar '&', '<' y '>' en una cadena de datos.

Puede escapar otras cadenas de datos pasando un diccionario como el parámetro opcional entities. Las claves y los valores deben ser cadenas; cada clave será reemplazada por su valor correspondiente. Los caracteres '&', '<' y '>' siempre se escapan, incluso si se proporciona entities.

xml.sax.saxutils.unescape(data, entities={})

Quitar el escape '&amp;', '&lt;', y '&gt;' en una cadena de datos.

Puede quitar el escape de otras cadenas de datos pasando un diccionario como el parámetro opcional entities. Las claves y los valores deben ser cadenas; cada clave será reemplazada por su valor correspondiente. A '&amp', '&lt;' y '&gt;' se les quita siempre el escape, incluso si se proporcionan entidades.

xml.sax.saxutils.quoteattr(data, entities={})

Similar a escape(), pero también prepara data para usarse como un valor de atributo. El valor devuelto es una versión entrecomillada de data con los reemplazos adicionales necesarios. quoteattr() seleccionará un carácter de comillas basado en el contenido de data, intentando evitar codificar los caracteres de comillas en la cadena. Si los caracteres de comillas simples y dobles ya están en data, los caracteres de comillas dobles se codificarán y data se envolverá entre comillas dobles. La cadena resultante se puede utilizar directamente como un valor de atributo:

>>> print("<element attr=%s>" % quoteattr("ab ' cd \" ef"))
<element attr="ab ' cd &quot; ef">

Esta función es útil al generar valores de atributo para HTML o cualquier SGML utilizando la sintaxis concreta de referencia.

class xml.sax.saxutils.XMLGenerator(out=None, encoding='iso-8859-1', short_empty_elements=False)

Esta clase implementa la interfaz ContentHandler escribiendo eventos SAX en un documento XML. En otras palabras, el uso de un XMLGenerator como controlador de contenido reproducirá el documento original que se está analizando. out debe ser un objeto similar a un archivo que por defecto sea sys.stdout. encoding es la codificación de la secuencia de salida que tiene como valor predeterminado 'iso-8859-1'. short_empty_elements controla el formato de los elementos que no contienen contenido: si False (valor predeterminado) se emiten como un par de etiquetas de inicio/fin, si se establece en True se emiten como una sola etiqueta autocerrada.

Nuevo en la versión 3.2: El parámetro short_empty_elements.

class xml.sax.saxutils.XMLFilterBase(base)

Esta clase está diseñada para situarse entre un XMLReader y los manejadores de eventos de la aplicación cliente. Por defecto, no hace más que pasar las peticiones al lector y los eventos a los manejadores sin modificar, pero las subclases pueden sobrescribir métodos específicos para modificar el flujo de eventos o las peticiones de configuración a medida que pasan.

xml.sax.saxutils.prepare_input_source(source, base='')

Esta función toma una fuente de entrada y una URL base opcional y devuelve un objeto InputSource totalmente resuelto y listo para ser leído. La fuente de entrada puede ser dada como una cadena, un objeto tipo archivo, o un objeto InputSource; los analizadores usarán esta función para implementar el argumento polimórfico fuente a su método parse().

xml.sax.xmlreader — Interfaz para analizadores XML

Código fuente: Lib/xml/sax/xmlreader.py [https://github.com/python/cpython/tree/3.9/Lib/xml/sax/xmlreader.py]

Los analizadores SAX implementan la interfaz XMLReader. Están implementados en un módulo Python, que debe proveer una función create_parser(). Esta función es invocada por xml.sax.make_parser() sin argumentos para crear un nuevo objeto analizador.

class xml.sax.xmlreader.XMLReader

Clase base que puede ser heredada por analizadores SAX.

class xml.sax.xmlreader.IncrementalParser

En algunos casos, es deseable no analizar una fuente de entrada a la vez, si no alimentar partes del documento a medida que estén disponibles. Tenga en cuenta que el lector normalmente no leerá el fichero completo, si no que también lo leerá por partes, aún así parse() no retornará hasta que el documento por completo es procesado. Por lo tanto, estas interfaces deben utilizarse si el comportamiento de bloqueo parse() no es deseable.

Cuando se crea una instancia del analizador, está listo para comenzar a aceptar información desde el método de alimentación inmediatamente. Después de que el análisis ha finalizado con una llamada para cerrar, se debe llamar al método de reinicio para que el analizador esté listo para aceptar información nueva, ya sea de la fuente o utilizando el método de análisis.

Tenga en cuenta que estos métodos no deben ser llamados durante el análisis, es decir, después de que el análisis ha sido llamado y antes de que regrese.

Por defecto, la clase también implementa el método de análisis de la interfaz XMLReader utilizando los métodos de alimentación, cierre y reinicio de la interfaz IncrementalParser en conveniencia a los escritores de controlador SAX 2.0.

class xml.sax.xmlreader.Locator

La interfaz para asociar un evento SAX con una ubicación del documento. Un objecto localizador retornará resultados válidos sólo durante llamadas a métodos DocumentHandler; en cualquier otro momento, los resultados son impredecibles. Si la información no está disponible, los métodos pueden retornar None.

class xml.sax.xmlreader.InputSource(system_id=None)

La encapsulación de la información necesaria por el XMLReader para leer entidades.

Esta clase puede incluir información sobre el identificador público, identificador del sistema, flujo de bytes (posiblemente con la información de codificación de caracteres) y/o el flujo de caracteres de una entidad.

Las aplicaciones crearán objetos de esta clase para uso en el método XMLReader.parse() y para retornar desde EntityResolver.resolveEntity.

Una InputSource pertenece a la aplicación, el XMLReader no tiene permitido modificar objetos InputSource pasados desde la aplicación, a pesar de que puede hacer copias y modificarlas.

class xml.sax.xmlreader.AttributesImpl(attrs)

Esta es una implementación de la interfaz Attributes (vea la sección La Interfaz Attributes). Este es un objeto de tipo diccionario que representa los atributos de elemento en una llamada startElement(). En adición a las operaciones de diccionario más útiles, soporta una serie de otros métodos como se describe en la interfaz. Los lectores deben crear una instancia de los objetos de esta clase; attrs debe ser un objeto de tipo diccionario que contenga un mapeo de nombres de atributo a valores de atributo.

class xml.sax.xmlreader.AttributesNSImpl(attrs, qnames)

Variante consciente del espacio de nombres de AttributesImpl, que se pasará a startElementNS(). Es derivada de AttributesImpl, pero entiende nombres de atributo como dos tuplas de namespaceURI y localname. En adición, provee una serie de métodos esperando nombres calificados como aparecen en el documento original. Esta clase implementa la interfaz AttributesNS (vea la sección La Interfaz AttributesNS).

Objetos XMLReader

La interfaz XMLReader soporta los siguientes métodos:

XMLReader.parse(source)

Procesa una fuente de entrada, produciendo eventos SAX. El objeto source puede ser un identificador de sistema (una cadena identificando la fuente de entrada – típicamente un nombre de fichero o una URL), un pathlib.Path o un objeto path-like, o un objeto InputSource. Cuando parse() retorna, la entrada es procesada completamente, y el objeto analizador puede ser descartado o reiniciado.

Distinto en la versión 3.5: Agregado soporte de flujo de caracteres.

Distinto en la versión 3.8: Agregado soporte de objetos path-like.

XMLReader.getContentHandler()

Retorna el ContentHandler actual.

XMLReader.setContentHandler(handler)

Establece el ContentHandler actual. Si ningún ContentHandler es establecido, los eventos de contenido serán descartados.

XMLReader.getDTDHandler()

Retorna el DTDHandler actual.

XMLReader.setDTDHandler(handler)

Establece el DTDHandler actual. Si ningún DTDHandler es establecido, los eventos DTD serán descartados.

XMLReader.getEntityResolver()

Retorna el EntityResolver actual.

XMLReader.setEntityResolver(handler)

Establece el EntityResolver actual. Si ningún EntityResolver es establecido, los intentos de resolver una entidad externa resultarán en la apertura del identificador de sistema para la entidad, y un error si no está disponible.

XMLReader.getErrorHandler()

Retorna el ErrorHandler actual.

XMLReader.setErrorHandler(handler)

Establece el manejador de errores actual. Si ningún ErrorHandler es establecido, se lanzarán errores como excepciones, y se imprimirán alertas.

XMLReader.setLocale(locale)

Permite a una aplicación establecer la configuración local para errores y alertas.

Analizadores SAX no son requeridos para proveer localización para errores y alertas; si no pueden soportar la configuración local solicitada, de cualquier forma, lanzarán una excepción SAX. Las aplicaciones pueden solicitar un cambio local en medio del análisis.

XMLReader.getFeature(featurename)

Retorna la configuración actual para la característica featurename. Si la característica no es reconocida, SAXNotRecognizedException es lanzada. Los bien conocidos featurenames son listados en el módulo xml.sax.handler.

XMLReader.setFeature(featurename, value)

Establece el featurename a value. Si la característica no es reconocida, SAXNotRecognizedException es lanzada. Si la característica o su configuración no es soportada por el analizador, SAXNotSupportedException es lanzada.

XMLReader.getProperty(propertyname)

Retorna la configuración actual para la propiedad propertyname. Si la configuración no es reconocida, una SAXNotRecognizedException es lanzada. Las bien conocidas propertynames son listadas en el módulo xml.sax.handler.

XMLReader.setProperty(propertyname, value)

Establece el propertyname a value. Si la propiedad no es reconocida, SAXNotRecognizedException es lanzada. Si la propiedad o su configuración no es soportada por el analizador, SAXNotSupportedException es lanzada.

Objetos IncrementalParser

Las instancias de IncrementalParser ofrecen los siguientes métodos adicionales:

IncrementalParser.feed(data)

Procesa una parte de data.

IncrementalParser.close()

Asume el fin del documento. Eso verificará las condiciones bien formadas que pueden ser verificadas sólo al final, invocar manejadores, y puede limpiar los recursos asignados durante el análisis.

IncrementalParser.reset()

Este método es llamado después de que el cierre ha sido llamado para restablecer el analizador, de forma que esté listo para analizar nuevos documentos. Los resultados de llamar parse o feed después del cierre sin llamar a reset son indefinidos.

Objetos localizadores

Las instancias de Locator proveen estos métodos:

Locator.getColumnNumber()

Retorna el número de columna donde el evento actual comienza.

Locator.getLineNumber()

Retorna el número de línea donde el evento actual comienza.

Locator.getPublicId()

Retorna el identificador público para el evento actual.

Locator.getSystemId()

Retorna el identificador de sistema para el evento actual.

Objetos InputSource

InputSource.setPublicId(id)

Establece el identificador público de esta InputSource.

InputSource.getPublicId()

Retorna el identificador público para esta InputSource.

InputSource.setSystemId(id)

Establece el identificador de sistema de esta InputSource.

InputSource.getSystemId()

Retorna el identificador de sistema para esta InputSource.

InputSource.setEncoding(encoding)

Establece la codificación de caracteres para esta InputSource.

La codificación debe ser una cadena aceptable para una declaración de codificación XML (vea la sección 4.3.3 de la recomendación XML).

El atributo de codificación de la InputSource es ignorado si la InputSource contiene también un flujo de caracteres.

InputSource.getEncoding()

Obtiene la codificación de caracteres de esta InputSource.

InputSource.setByteStream(bytefile)

Establece el flujo de bytes (un binary file) para esta fuente de entrada.

El analizador SAX ignorará esto si existe también un flujo de caracteres especificado, pero utilizará un flujo de bytes en preferencia para abrir una conexión URI en sí.

Si la aplicación conoce la codificación de caracteres del flujo de bytes, debería establecerla con el método setEncoding.

InputSource.getByteStream()

Obtiene el flujo de bytes para esta fuente de entrada.

El método getEncoding retornará la codificación de caracteres para este flujo de bytes, o None si se desconoce.

InputSource.setCharacterStream(charfile)

Establece el flujo de caracteres (un text file) para esta fuente de entrada.

Si existe un flujo de caracteres especificado, el analizador SAX ignorará cualquier flujo de bytes y no intentará abrir una conexión URI al identificador de sistema.

InputSource.getCharacterStream()

Obtiene el flujo de caracteres para esta fuente de entrada.

La Interfaz Attributes

Los objetos Attributes implementa una porción del mapping protocol, incluyendo los métodos copy(), get(), __contains__(), items(), keys(), y values(). Los siguientes métodos también son provistos:

Attributes.getLength()

Retorna el número de atributos.

Attributes.getNames()

Retorna los nombres de los atributos.

Attributes.getType(name)

Retorna el tipo del atributo name, que es normalmente 'CDATA'.

Attributes.getValue(name)

Retorna el valor del atributo name.

La Interfaz AttributesNS

Esta interfaz es un subtipo de la interfaz Attributes (vea la sección La Interfaz Attributes). Todos los métodos soportados por la interfaz están también disponibles en los objetos AttributesNS.

Los siguientes métodos están también disponibles:

AttributesNS.getValueByQName(name)

Retorna el valor para un nombre cualificado.

AttributesNS.getNameByQName(name)

Retorna el par (namespace, localname) para un name cualificado.

AttributesNS.getQNameByName(name)

Retorna el nombre cualificado para un par (namespace, localname).

AttributesNS.getQNames()

Retorna los nombres cualificados para todos los atributos.

xml.parsers.expat — Análisis rápido XML usando Expat

Advertencia

El módulo pyexpat no es seguro contra datos construidos maliciosamente. Si necesita analizar datos que no son de confianza o no autenticados, consulte Vulnerabilidades XML.

El módulo xml.parsers.expat es una interfaz de Python para el analizador XML no validado de Expat. El módulo proporciona un único tipo de extensión, xmlparser, que representa el estado actual de un analizador XML. Después de que se haya creado un objeto xmlparser, se pueden establecer varios atributos del objeto en funciones de controlador. Cuando se envía un documento XML al analizador, se llaman a las funciones del controlador para los datos de caracteres y el marcado en el documento XML.

Este módulo utiliza el módulo pyexpat para proporcionar acceso al analizador Expat. El uso directo del módulo pyexpat está obsoleto.

Este módulo proporciona una excepción y un tipo de objeto:

exception xml.parsers.expat.ExpatError

La excepción que se lanza cuando Expat informa un error. Consulte la sección Excepciones de ExpatError para obtener más información sobre cómo interpretar los errores de Expat.

exception xml.parsers.expat.error

Alias para ExpatError.

xml.parsers.expat.XMLParserType

El tipo de los valores de retorno de la función ParserCreate().

El modulo xml.parsers.expat contiene dos funciones:

xml.parsers.expat.ErrorString(errno)

Retorna una cadena explicativa para un número de error dado errno.

xml.parsers.expat.ParserCreate(encoding=None, namespace_separator=None)

Crea y retorna un nuevo objeto xmlparser. encoding, si se especifica, debe ser una cadena que nombre la codificación utilizada por los datos XML. Expat no admite tantas codificaciones como Python, y su repertorio de codificaciones no se puede ampliar; es compatible con UTF-8, UTF-16, ISO-8859-1 (Latin1) y ASCII. Si se proporciona encoding 1, anulará la codificación implícita o explícita del documento.

Expat puede, opcionalmente, realizar el procesamiento del espacio de nombres XML por usted, habilitado al proporcionar un valor para namespace_separator. El valor debe ser una cadena de un carácter; a ValueError se lanzará si la cadena tiene una longitud ilegal (None se considera lo mismo que una omisión). Cuando el procesamiento de espacios de nombres está habilitado, se expandirán los nombres de tipos de elementos y los nombres de atributos que pertenecen a un espacio de nombres. El nombre del elemento pasado a los controladores de elementos StartElementHandler y EndElementHandler será la concatenación del URI del espacio de nombres, el carácter separador del espacio de nombres y la parte local del nombre. Si el separador del espacio de nombres es un byte cero (chr(0)), el URI del espacio de nombres y la parte local se concatenarán sin ningún separador.

Por ejemplo, si namespace_separator se establece en un carácter de espacio (' ') y se analiza el siguiente documento:

<?xml version="1.0"?>
<root xmlns    = "http://default-namespace.org/"
      xmlns:py = "http://www.python.org/ns/">
  <py:elem1 />
  <elem2 xmlns="" />
</root>

StartElementHandler recibirá las siguientes cadenas para cada elemento:

http://default-namespace.org/ root
http://www.python.org/ns/ elem1
elem2

Debido a las limitaciones en la biblioteca Expat utilizada por pyexpat, la instancia xmlparser retorna solo se puede usar para analizar un solo documento XML. Llame a ParserCreate para cada documento para proporcionar instancias de analizador únicas.

Ver también

El Expat XML Parser [http://www.libexpat.org/]

Página de inicio del proyecto Expat.

Objetos XMLParser

Los objetos xmlparser tienen los siguientes métodos:

xmlparser.Parse(data[, isfinal])

Analiza el contenido de la cadena data, llamando a las funciones del controlador apropiadas para procesar los datos analizados. isfinal debe ser verdadero en la última llamada a este método; permite el análisis de un solo archivo en fragmentos, no el envío de varios archivos. data puede ser la cadena vacía en cualquier momento.

xmlparser.ParseFile(file)

Analizar la lectura de datos XML del objeto file. file solo necesita proporcionar el método read(nbytes), devolviendo la cadena vacía cuando no hay más datos.

xmlparser.SetBase(base)

Establece la base que se utilizará para resolver URIs relativos en identificadores de sistema en declaraciones. La resolución de los identificadores relativos se deja en manos de la aplicación: este valor se pasará como el argumento base a las funciones ExternalEntityRefHandler(), NotationDeclHandler(), y UnparsedEntityDeclHandler().

xmlparser.GetBase()

Retorna una cadena que contiene la base establecida por una llamada anterior a SetBase(), o None si no se ha llamado a SetBase().

xmlparser.GetInputContext()

Retorna los datos de entrada que generaron el evento actual como una cadena. Los datos están en la codificación de la entidad que contiene el texto. Cuando se llama mientras un controlador de eventos no está activo, el valor de retorno es None.

xmlparser.ExternalEntityParserCreate(context[, encoding])

Cree un analizador «child» que se pueda utilizar para analizar una entidad analizada externa a la que hace referencia el contenido analizado por el analizador principal. El parámetro context debe ser la cadena pasada a la función del controlador ExternalEntityRefHandler(), que se describe a continuación. El analizador secundario se crea con order_attributes y specific_attributes establecidos en los valores de este analizador.

xmlparser.SetParamEntityParsing(flag)

Controle el análisis de las entidades de parámetros (incluido el subconjunto DTD externo). Los posibles valores de flag son XML_PARAM_ENTITY_PARSING_NEVER, XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE y XML_PARAM_ENTITY_PARSING_ALWAYS. Retorna verdadero si el establecimiento de la bandera fue exitoso.

xmlparser.UseForeignDTD([flag])

Llamar a esto con un valor verdadero para flag (el predeterminado) hará que Expat llame a ExternalEntityRefHandler con None para todos los argumentos para permitir que se cargue una DTD alternativa. Si el documento no contiene una declaración de tipo de documento, se seguirá llamando a ExternalEntityRefHandler, pero no se llamará a StartDoctypeDeclHandler y EndDoctypeDeclHandler.

Pasar un valor falso para flag cancelará una llamada anterior que pasó un valor verdadero, pero por lo demás no tiene ningún efecto.

Este método sólo se puede llamar antes de que se llamen los métodos Parse() o ParseFile(); llamarlo después de que cualquiera de ellos haya sido llamado causa que ExpatError se lanza con el atributo code establecido en errors.codes[errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING].

xmlparser los objetos tienen los siguientes atributos:

xmlparser.buffer_size

El tamaño del búfer usado cuando buffer_text es verdadero. Se puede establecer un nuevo tamaño de búfer asignando un nuevo valor entero a este atributo. Cuando se cambia el tamaño, el búfer se vaciará.

xmlparser.buffer_text

Establecer esto en true hace que el objeto xmlparser almacene el contenido textual retornado por Expat para evitar múltiples llamadas a la devolución de llamada CharacterDataHandler() siempre que sea posible. Esto puede mejorar sustancialmente el rendimiento ya que Expat normalmente divide los datos de los caracteres en trozos al final de cada línea. Este atributo es falso por defecto y se puede cambiar en cualquier momento.

xmlparser.buffer_used

Si buffer_text está habilitado, el número de bytes almacenados en el búfer. Estos bytes representan texto codificado en UTF-8. Este atributo no tiene una interpretación significativa cuando buffer_text es falso.

xmlparser.ordered_attributes

Establecer este atributo en un número entero distinto de cero hace que los atributos se informen como una lista en lugar de un diccionario. Los atributos se presentan en el orden que se encuentran en el texto del documento. Para cada atributo, se presentan dos entradas de lista: el nombre del atributo y el valor del atributo. (Las versiones anteriores de este módulo también usaban este formato). De forma predeterminada, este atributo es falso; se puede cambiar en cualquier momento.

xmlparser.specified_attributes

Si se establece en un número entero distinto de cero, el analizador informará solo los atributos que se especificaron en la instancia del documento y no los que se derivaron de declaraciones de atributos. Las aplicaciones que establecen esto deben tener especial cuidado al utilizar la información adicional disponible en las declaraciones según sea necesario para cumplir con los estándares para el comportamiento de los procesadores XML. De forma predeterminada, este atributo es falso; se puede cambiar en cualquier momento.

Los siguientes atributos contienen valores relacionados con el error más reciente encontrado por un objeto xmlparser, y solo tendrán los valores correctos una vez que una llamada a Parse() o ParseFile() haya lanzado una excepción xml.parsers.expat.ExpatError.

xmlparser.ErrorByteIndex

Índice de bytes en el que se produjo un error.

xmlparser.ErrorCode

Código numérico que especifica el problema. Este valor puede pasarse a la función ErrorString(), o compararse con una de las constantes definidas en el objeto errors.

xmlparser.ErrorColumnNumber

Número de columna en la que se produjo un error.

xmlparser.ErrorLineNumber

Número de línea en la que ocurrió un error.

Los siguientes atributos contienen valores relacionados con la ubicación actual del análisis en un objeto xmlparser. Durante una devolución de llamada que informa un evento de análisis, indican la ubicación del primero de la secuencia de caracteres que generó el evento. Cuando se llama fuera de una devolución de llamada, la posición indicada estará justo después del último evento de análisis (independientemente de si hubo una devolución de llamada asociada).

xmlparser.CurrentByteIndex

Índice de bytes actual en la entrada del analizador.

xmlparser.CurrentColumnNumber

Número de columna actual en la entrada del analizador.

xmlparser.CurrentLineNumber

Número de línea actual en la entrada del analizador.

Aquí está la lista de controladores que se pueden configurar. Para configurar un controlador en un objeto xmlparser o, use o.handlername = func. handlername debe tomarse de la siguiente lista, y func debe ser un objeto invocable que acepte el número correcto de argumentos. Los argumentos son todos cadenas, a menos que se indique lo contrario.

xmlparser.XmlDeclHandler(version, encoding, standalone)

Se llama cuando se analiza la declaración XML. La declaración XML es la declaración (opcional) de la versión aplicable de la recomendación XML, la codificación del texto del documento y una declaración «independiente» opcional. version y encoding serán cadenas, y standalone será 1 si el documento se declara independiente, 0 si se declara no independiente o -1 si se omitió la cláusula independiente. Esto solo está disponible con la versión Expat 1.95.0 o más reciente.

xmlparser.StartDoctypeDeclHandler(doctypeName, systemId, publicId, has_internal_subset)

Se llama cuando Expat comienza a analizar la declaración del tipo de documento (<! DOCTYPE ...). El doctypeName se proporciona exactamente como se presenta. Los parámetros systemId y publicId dan el sistema y los identificadores públicos si se especifican, o None si se omite. has_internal_subset será verdadero si el documento contiene un subconjunto de declaración de documento interno. Esto requiere Expat versión 1.2 o más reciente.

xmlparser.EndDoctypeDeclHandler()

Se llama cuando Expat termina de analizar la declaración del tipo de documento. Esto requiere Expat versión 1.2 o más reciente.

xmlparser.ElementDeclHandler(name, model)

Se llama una vez para cada declaración de tipo de elemento. name es el nombre del tipo de elemento y model es una representación del modelo de contenido.

xmlparser.AttlistDeclHandler(elname, attname, type, default, required)

Se llama para cada atributo declarado para un tipo de elemento. Si una declaración de lista de atributos declara tres atributos, este controlador se llama tres veces, una para cada atributo. elname es el nombre del elemento al que se aplica la declaración y attname es el nombre del atributo declarado. El tipo de atributo es una cadena pasada como type; los valores posibles son 'CDATA', 'ID', 'IDREF', … default da el valor predeterminado para el atributo utilizado cuando el atributo no está especificado por el instancia de documento, o None si no hay un valor predeterminado (valores #IMPLIED). Si se requiere que el atributo se proporcione en la instancia del documento, required será verdadero. Esto requiere la versión Expat 1.95.0 o más reciente.

xmlparser.StartElementHandler(name, attributes)

Llamado para el inicio de cada elemento. name es una cadena que contiene el nombre del elemento, y attributes son los atributos del elemento. Si order_attributes es verdadero, esta es una lista (ver order_attributes para una descripción completa). De lo contrario, es un diccionario que asigna nombres a valores.

xmlparser.EndElementHandler(name)

Llamado al final de cada elemento.

xmlparser.ProcessingInstructionHandler(target, data)

Llamado para cada instrucción de procesamiento.

xmlparser.CharacterDataHandler(data)

Llamado para datos de personajes. Esto se llamará para datos de caracteres normales, contenido marcado CDATA y espacios en blanco ignorables. Las aplicaciones que deben distinguir estos casos pueden usar las devoluciones de llamada StartCdataSectionHandler, EndCdataSectionHandler, y ElementDeclHandler para recopilar la información requerida.

xmlparser.UnparsedEntityDeclHandler(entityName, base, systemId, publicId, notationName)

Se llama para declaraciones de entidad sin analizar (NDATA). Esto solo está presente para la versión 1.2 de la biblioteca Expat; para versiones más recientes, use EntityDeclHandler en su lugar. (La función subyacente en la biblioteca Expat se ha declarado obsoleta).

xmlparser.EntityDeclHandler(entityName, is_parameter_entity, value, base, systemId, publicId, notationName)

Llamado para todas las declaraciones de entidad. Para parámetros y entidades internas, value será una cadena que proporciona el contenido declarado de la entidad; esto será None para entidades externas. El parámetro notationName será None para las entidades analizadas y el nombre de la notación para las entidades no analizadas. is_parameter_entity será verdadero si la entidad es una entidad de parámetro o falso para las entidades generales (la mayoría de las aplicaciones solo deben preocuparse por las entidades generales). Esto solo está disponible a partir de la versión 1.95.0 de la biblioteca Expat.

xmlparser.NotationDeclHandler(notationName, base, systemId, publicId)

Se llama para declaraciones de notación. notationName, base y systemId y publicId son cadenas si se dan. Si se omite el identificador público, publicId será None.

xmlparser.StartNamespaceDeclHandler(prefix, uri)

Se llama cuando un elemento contiene una declaración de espacio de nombres. Las declaraciones de espacio de nombres se procesan antes de que se llame a StartElementHandler para el elemento en el que se colocan las declaraciones.

xmlparser.EndNamespaceDeclHandler(prefix)

Se llama cuando se alcanza la etiqueta de cierre para un elemento que contiene una declaración de espacio de nombres. Esto se llama una vez para cada declaración de espacio de nombres en el elemento en el orden inverso al que se llamó StartNamespaceDeclHandler para indicar el inicio del alcance de cada declaración de espacio de nombres. Las llamadas a este controlador se realizan después del correspondiente EndElementHandler para el final del elemento.

xmlparser.CommentHandler(data)

Llamado para comentarios. data es el texto del comentario, excluyendo el '<!--' inicial y el final '-->'.

xmlparser.StartCdataSectionHandler()

Llamado al comienzo de una sección CDATA. Esto y EndCdataSectionHandler son necesarios para poder identificar el inicio sintáctico y el final de las secciones CDATA.

xmlparser.EndCdataSectionHandler()

Llamado al final de una sección CDATA.

xmlparser.DefaultHandler(data)

Se invoca por cualquier carácter del documento XML para el que no se ha especificado ningún controlador aplicable. Esto significa caracteres que forman parte de una construcción que se podría informar, pero para los que no se ha proporcionado ningún controlador.

xmlparser.DefaultHandlerExpand(data)

Es lo mismo que DefaultHandler(), pero no inhibe la expansión de entidades internas. La referencia de la entidad no se pasará al controlador predeterminado.

xmlparser.NotStandaloneHandler()

Se llama si el documento XML no se ha declarado como un documento independiente. Esto sucede cuando hay un subconjunto externo o una referencia a una entidad de parámetro, pero la declaración XML no establece independiente en yes en una declaración XML. Si este controlador retorna 0, el analizador lanzará un error XML_ERROR_NOT_STANDALONE. Si este controlador no está configurado, el analizador no lanza ninguna excepción para esta condición.

xmlparser.ExternalEntityRefHandler(context, base, systemId, publicId)

Llamado para referencias a entidades externas. base es la base actual, según lo establecido por una llamada anterior a SetBase(). Los identificadores público y del sistema, systemId y publicId, son cadenas si se dan; si no se proporciona el identificador público, publicId será None. El valor context es opaco y solo debe usarse como se describe a continuación.

Para que se analicen las entidades externas, se debe implementar este controlador. Es responsable de crear el sub-analizador usando ExternalEntityParserCreate(context), inicializándolo con las devoluciones de llamada apropiadas y analizando la entidad. Este controlador debería devolver un número entero; si retorna 0, el analizador lanzará un error XML_ERROR_EXTERNAL_ENTITY_HANDLING; de lo contrario, el análisis continuará.

Si no se proporciona este controlador, las entidades externas se informan mediante la devolución de llamada DefaultHandler, si se proporciona.

Excepciones de ExpatError

Las excepciones ExpatError tienen una serie de atributos interesantes:

ExpatError.code

Número de error interno del expatriado para el error específico. El diccionario errors.messages asigna estos números de error a los mensajes de error de Expat. Por ejemplo:

from xml.parsers.expat import ParserCreate, ExpatError, errors

p = ParserCreate()
try:
    p.Parse(some_xml_document)
except ExpatError as err:
    print("Error:", errors.messages[err.code])

El módulo errors también proporciona constantes de mensajes de error y un diccionario codes mapeando estos mensajes a los códigos de error, ver más abajo.

ExpatError.lineno

Número de línea en la que se detectó el error. La primera línea está numerada como 1.

ExpatError.offset

Carácter desplazado en la línea donde ocurrió el error. La primera columna está numerada como 0.

Ejemplo

El siguiente programa define tres controladores que simplemente imprimen sus argumentos.

import xml.parsers.expat

# 3 handler functions
def start_element(name, attrs):
    print('Start element:', name, attrs)
def end_element(name):
    print('End element:', name)
def char_data(data):
    print('Character data:', repr(data))

p = xml.parsers.expat.ParserCreate()

p.StartElementHandler = start_element
p.EndElementHandler = end_element
p.CharacterDataHandler = char_data

p.Parse("""<?xml version="1.0"?>
<parent id="top"><child1 name="paul">Text goes here</child1>
<child2 name="fred">More text</child2>
</parent>""", 1)

La salida de este programa es:

Start element: parent {'id': 'top'}
Start element: child1 {'name': 'paul'}
Character data: 'Text goes here'
End element: child1
Character data: '\n'
Start element: child2 {'name': 'fred'}
Character data: 'More text'
End element: child2
Character data: '\n'
End element: parent

Descripciones del modelo de contenido

Los modelos de contenido se describen mediante tuplas anidadas. Cada tupla contiene cuatro valores: el tipo, el cuantificador, el nombre y una tupla de niños. Los niños son simplemente descripciones adicionales del modelo de contenido.

Los valores de los dos primeros campos son constantes definidas en el módulo xml.parsers.expat.model. Estas constantes se pueden recopilar en dos grupos: el grupo de tipo de modelo y el grupo de cuantificador.

Las constantes en el grupo de tipos de modelo son:

xml.parsers.expat.model.XML_CTYPE_ANY

Se declaró que el elemento nombrado por el nombre del modelo tiene un modelo de contenido de ANY.

xml.parsers.expat.model.XML_CTYPE_CHOICE

El elemento nombrado permite elegir entre varias opciones; se utiliza para modelos de contenido como (A | B | C).

xml.parsers.expat.model.XML_CTYPE_EMPTY

Los elementos que se declaran EMPTY tienen este tipo de modelo.

xml.parsers.expat.model.XML_CTYPE_MIXED

xml.parsers.expat.model.XML_CTYPE_NAME

xml.parsers.expat.model.XML_CTYPE_SEQ

Los modelos que representan una serie de modelos que siguen uno tras otro se indican con este tipo de modelo. Se utiliza para modelos como (A, B, C).

Las constantes en el grupo cuantificador son:

xml.parsers.expat.model.XML_CQUANT_NONE

No se proporciona ningún modificador, por lo que puede aparecer exactamente una vez, como para A.

xml.parsers.expat.model.XML_CQUANT_OPT

El modelo es opcional: puede aparecer una vez o no aparecer, como para A?.

xml.parsers.expat.model.XML_CQUANT_PLUS

El modelo debe aparecer una o más veces (como A+).

xml.parsers.expat.model.XML_CQUANT_REP

El modelo debe aparecer cero o más veces, como en A*.

Constantes de error de expansión

Las siguientes constantes se proporcionan en el módulo xml.parsers.expat.errors. Estas constantes son útiles para interpretar algunos de los atributos de los objetos de excepción ExpatError que se lanzaran cuando se produce un error. Dado que, por razones de compatibilidad con versiones anteriores, el valor de las constantes es el message de error y no el code de error numérico, puede hacer esto comparando su atributo code con errors.codes[errors.XML_ERROR_CONSTANT_NAME].

El módulo errors tiene los siguientes atributos:

xml.parsers.expat.errors.codes

Un diccionario que asigna descripciones de cadenas a sus códigos de error.

Nuevo en la versión 3.2.

xml.parsers.expat.errors.messages

Un diccionario que asigna códigos de error numéricos a sus descripciones de cadenas.

Nuevo en la versión 3.2.

xml.parsers.expat.errors.XML_ERROR_ASYNC_ENTITY

xml.parsers.expat.errors.XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF

Una referencia de entidad en un valor de atributo se refiere a una entidad externa en lugar de una entidad interna.

xml.parsers.expat.errors.XML_ERROR_BAD_CHAR_REF

Una referencia de carácter se refiere a un carácter que es ilegal en XML (por ejemplo, carácter 0, o “&#0;”).

xml.parsers.expat.errors.XML_ERROR_BINARY_ENTITY_REF

Una referencia de entidad se refería a una entidad que se declaró con una notación, por lo que no se puede analizar.

xml.parsers.expat.errors.XML_ERROR_DUPLICATE_ATTRIBUTE

Un atributo se utilizó más de una vez en una etiqueta de inicio.

xml.parsers.expat.errors.XML_ERROR_INCORRECT_ENCODING

xml.parsers.expat.errors.XML_ERROR_INVALID_TOKEN

Se lanza cuando un byte de entrada no se puede asignar correctamente a un carácter; por ejemplo, un byte NUL (valor 0) en un flujo de entrada UTF-8.

xml.parsers.expat.errors.XML_ERROR_JUNK_AFTER_DOC_ELEMENT

Se produjo algo diferente a los espacios en blanco después del elemento del documento.

xml.parsers.expat.errors.XML_ERROR_MISPLACED_XML_PI

Se encontró una declaración XML en algún lugar que no sea el comienzo de los datos de entrada.

xml.parsers.expat.errors.XML_ERROR_NO_ELEMENTS

El documento no contiene elementos (XML requiere que todos los documentos contengan exactamente un elemento de nivel superior)..

xml.parsers.expat.errors.XML_ERROR_NO_MEMORY

Expat no pudo asignar memoria internamente.

xml.parsers.expat.errors.XML_ERROR_PARAM_ENTITY_REF

Se encontró una referencia de entidad de parámetro donde no estaba permitida.

xml.parsers.expat.errors.XML_ERROR_PARTIAL_CHAR

Se encontró un carácter incompleto en la entrada.

xml.parsers.expat.errors.XML_ERROR_RECURSIVE_ENTITY_REF

Una referencia de entidad contenía otra referencia a la misma entidad; posiblemente a través de un nombre diferente, y posiblemente indirectamente.

xml.parsers.expat.errors.XML_ERROR_SYNTAX

Se encontró algún error de sintaxis no especificado.

xml.parsers.expat.errors.XML_ERROR_TAG_MISMATCH

Una etiqueta final no coincidía con la etiqueta inicial abierta más interna.

xml.parsers.expat.errors.XML_ERROR_UNCLOSED_TOKEN

Algún token (como una etiqueta de inicio) no se cerró antes del final de la transmisión o se encontró el siguiente token.

xml.parsers.expat.errors.XML_ERROR_UNDEFINED_ENTITY

Se hizo referencia a una entidad que no estaba definida.

xml.parsers.expat.errors.XML_ERROR_UNKNOWN_ENCODING

La codificación del documento no es compatible con Expat.

xml.parsers.expat.errors.XML_ERROR_UNCLOSED_CDATA_SECTION

No se cerró una sección marcada con CDATA.

xml.parsers.expat.errors.XML_ERROR_EXTERNAL_ENTITY_HANDLING

xml.parsers.expat.errors.XML_ERROR_NOT_STANDALONE

El analizador determinó que el documento no era «independiente» aunque se declaró en la declaración XML, y el NotStandaloneHandler se estableció y devolvió 0.

xml.parsers.expat.errors.XML_ERROR_UNEXPECTED_STATE

xml.parsers.expat.errors.XML_ERROR_ENTITY_DECLARED_IN_PE

xml.parsers.expat.errors.XML_ERROR_FEATURE_REQUIRES_XML_DTD

Se solicitó una operación que requiere que se compile el soporte DTD, pero Expat se configuró sin soporte DTD. Esto nunca debería ser informado por una compilación estándar del módulo xml.parsers.expat.

xml.parsers.expat.errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING

Se solicitó un cambio de comportamiento después de que comenzó el análisis que solo se puede cambiar antes de que haya comenzado el análisis. Esto (actualmente) solo lanzado por UseForeignDTD().

xml.parsers.expat.errors.XML_ERROR_UNBOUND_PREFIX

Se encontró un prefijo no declarado cuando se habilitó el procesamiento del espacio de nombres.

xml.parsers.expat.errors.XML_ERROR_UNDECLARING_PREFIX

El documento intentó eliminar la declaración de espacio de nombres asociada con un prefijo.

xml.parsers.expat.errors.XML_ERROR_INCOMPLETE_PE

El documento no contenía ningún elemento de documento.

xml.parsers.expat.errors.XML_ERROR_XML_DECL

El documento no contenía ningún elemento de documento.

xml.parsers.expat.errors.XML_ERROR_TEXT_DECL

Se produjo un error al analizar una declaración de texto en una entidad externa.

xml.parsers.expat.errors.XML_ERROR_PUBLICID

Se encontraron caracteres en la identificación pública que no están permitidos.

xml.parsers.expat.errors.XML_ERROR_SUSPENDED

La operación solicitada se realizó en un analizador suspendido, pero no está permitida. Esto incluye intentos de proporcionar información adicional o detener el analizador.

xml.parsers.expat.errors.XML_ERROR_NOT_SUSPENDED

Se realizó un intento de reanudar el analizador cuando no se había suspendido.

xml.parsers.expat.errors.XML_ERROR_ABORTED

Esto no se debe informar a las aplicaciones Python.

xml.parsers.expat.errors.XML_ERROR_FINISHED

La operación solicitada se realizó en un analizador que terminó de analizar la entrada, pero no está permitido. Esto incluye intentos de proporcionar información adicional o detener el analizador.

xml.parsers.expat.errors.XML_ERROR_SUSPEND_PE

Notas al pie

1

La cadena de codificación incluida en la salida XML debe cumplir con los estándares apropiados. Por ejemplo, «UTF-8» es válido, pero «UTF8» no lo es. Consulte https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl y https://www.iana.org/assignments/character-sets/character-sets.xhtml.

Protocolos y soporte de Internet

Los módulos descritos en este capítulo implementan protocolos de Internet y soporte para la tecnología relacionada. Todos ellos se implementan en Python. La mayoría de estos módulos requieren la presencia del módulo dependiente del sistema socket, que actualmente es compatible con las plataformas más populares. Aquí hay una visión general:

webbrowser — Cómodo controlador de navegador web

Objetos controladores de navegador

wsgiref — Utilidades WSGI e implementación de referencia

wsgiref.util – Utilidades de entorno WSGI

wsgiref.headers – Herramientas para cabeceras de respuesta WSGI

wsgiref.simple_server– Un servidor HTTP WSGI simple

wsgiref.validate — Verificador de compatibilidad WSGI

wsgiref.handlers – Clases base servidor/gateway

Ejemplos

urllib — URL módulos de manipulación

urllib.request — Biblioteca extensible para abrir URLs

Objetos Request

Objetos OpenerDirector

Objetos BaseHandler

Objetos HTTPRedirectHandler

Objetos HTTPCookieProcessor

Objetos ProxyHandler

Objetos HTTPPasswordMgr

Objetos HTTPPasswordMgrWithPriorAuth

Objetos AbstractBasicAuthHandler

Objetos HTTPBasicAuthHandler

Objetos ProxyBasicAuthHandler

Objetos AbstractDigestAuthHandler

Objetos HTTPDigestAuthHandler

Objetos ProxyDigestAuthHandler

Objetos HTTPHandler

Objetos HTTPSHandler

Objetos FileHandler

Objetos DataHandler

Objetos FTPHandler

Objetos CacheFTPHandler

Objetos UnknownHandler

Objetos HTTPErrorProcessor

Ejemplos

Interfaz heredada

Restricciones urllib.request

urllib.response — Clases de respuesta usadas por urllib

urllib.parse — Analiza URL en componentes

Análisis de URL

URL parsing security

Análisis de bytes codificados ASCII

Resultados del análisis estructurado

Cita de URL

urllib.error — Clases de excepción lanzadas por urllib.request

urllib.robotparser — Analizador para robots.txt

http — Módulos HTTP

Códigos de estado HTTP

http.client — Cliente de protocolo HTTP

Objetos de HTTPConnection

Objetos de HTTPResponse

Ejemplos

Objetos de HTTPMessage

ftplib — cliente de protocolo FTP

Objetos FTP

Objetos FTP_TLS

poplib — Cliente de protocolo POP3

Objetos POP3

Ejemplo POP3

imaplib — Protocolo del cliente IMAP4

Objetos de IMAP4

Ejemplo IMAP4

smtplib — Cliente de protocolo SMTP

Objetos SMTP

Ejemplo SMTP

uuid — objetos UUID según RFC 4122

Ejemplo

socketserver — Un framework para servidores de red

Notas de creación del servidor

Objetos de servidor

Solicitar objetos de controlador

Ejemplos

socketserver.TCPServer Ejemplo

socketserver.UDPServer Ejemplo

Mixins asincrónicos

http.server — Servidores HTTP

Security Considerations

http.cookies — Gestión del estado HTTP

Objetos de cookie

Objetos Morsel

Ejemplo

http.cookiejar — Manejo de cookies para clientes HTTP

Objetos CookieJar y FileCookieJar

Subclases FileCookieJar y co-operación con navegadores web

Objetos CookiePolicy

Objetos DefaultCookiePolicy

Objetos Cookie

Ejemplos

xmlrpc — Módulos XMLRPC para cliente y servidor

xmlrpc.client — acceso cliente XML-RPC

Objetos ServerProxy

Objetos DateTime

Objetos binarios

Objetos Faults

Objetos ProtocolError

Objectos MultiCall

Funciones de Conveniencia

Ejemplo de Uso de Cliente

Ejemplo de Uso de Cliente y Servidor

xmlrpc.server — Servidores básicos XML-RPC

Objetos SimpleXMLRPCServer

Ejemplo de SimpleXMLRPCServer

CGIXMLRPCRequestHandler

Documentando el servidor XMLRPC

Objetos DocXMLRPCServer

DocCGIXMLRPCRequestHandler

ipaddress — Biblioteca de manipulación IPv4/IPv6

Funciones de fábrica de conveniencia

Direcciones IP

Objetos de dirección

Conversión a cadenas de caracteres y enteros

Operadores

Operadores de comparación

Operadores aritméticos

Definiciones de red IP

Prefijo, máscara de red y máscara de host

Objetos de red

Operadores

Operadores lógicos

Iteración

Redes como contenedores de direcciones

Objetos de interfaz

Operadores

Operadores lógicos

Otras funciones a nivel de módulo

Excepciones personalizadas

webbrowser — Cómodo controlador de navegador web

Código fuente: Lib/webbrowser.py [https://github.com/python/cpython/tree/3.9/Lib/webbrowser.py]

El módulo webbrowser provee una interfaz de alto nivel que permite desplegar documentos basados en la web a los usuarios. Bajo la mayoría de circunstancias, simplemente invocando la función open() desde este módulo se realizará la acción correcta.

En Unix, son privilegiados los navegadores gráficos bajo X11, pero serán usados navegadores en modo texto si los navegadores gráficos no están disponibles o un display X11 no está disponible. Si se usan navegadores en modo texto, el proceso invocador será bloqueado hasta que el usuario salga del navegador.

Si existe la variable de entorno BROWSER, esta es interpretada como la lista de navegadores a probar antes de los predeterminados de la plataforma, separados por os.pathsep. Cuando el valor de una parte de la lista contiene la cadena %s, este es interpretado como una línea de comando literal de un navegador a usar con el argumento URL substituido por %s; si la parte no contiene %s, esta se interpreta simplemente como el nombre del navegador a lanzar. 1

En plataformas no Unix o cuando está disponible un navegador remoto en Unix, el proceso de control no esperará a que el usuario finalice el navegador, sino que permitirá al navegador remoto mantener su propia ventana en la pantalla. Si no están disponibles navegadores remotos en Unix, el proceso de control lanzará un nuevo navegador y esperará.

El script webbrowser puede ser usado como una interfaz de línea de comandos para el módulo. Acepta una URL como argumento. Acepta los siguientes parámetros opcionales: -n abre la URL en una nueva ventana del navegador, si es posible; -t abre la URL en una nueva página del navegador («pestaña»). Las opciones son, naturalmente, mutuamente exclusivas. Ejemplo de uso:

python -m webbrowser -t "https://www.python.org"

La siguiente excepción es definida:

exception webbrowser.Error

Excepción generada cuando ocurre un error de control de navegador.

Las siguientes funciones son definidas:

webbrowser.open(url, new=0, autoraise=True)

Muestra url usando el navegador por defecto. Si new es 0, se abre la url en la misma ventana del navegador si es posible. Si new es 1, se abre una nueva ventana del navegador si es posible. Si new es 2, se abre una nueva página del navegador («pestaña») si es posible. Si autoraise es True, la ventana es lanzada si es posible (ten en cuenta que bajo muchos gestores de ventana esto ocurrirá independientemente de la configuración de esta variable).

Ten en cuenta que en algunas plataformas, tratar de abrir un nombre de archivo usando esta función puede funcionar e iniciar el programa asociado del sistema operativo. Sin embargo, esto no es soportado ni portable.

Lanza un evento de auditoría webbrowser.open con el argumento url.

webbrowser.open_new(url)

Abre url en una nueva ventana del navegador por defecto, si es posible, si no, abre url en la única ventana del navegador.

webbrowser.open_new_tab(url)

Abre url en una nueva página («pestaña») del navegador por defecto, si es posible, si no equivale a open_new().

webbrowser.get(using=None)

Retorna un objeto de controlador para el tipo de navegador using. Si using es None, retorna un controlador de un navegador por defecto apropiado para el entorno del invocador.

webbrowser.register(name, constructor, instance=None, *, preferred=False)

Registra el tipo de navegador name. Una vez que el tipo de navegador es registrado, la función get() puede retornar un controlador para ese tipo de navegador. Si no se provee instance o es None, constructor será invocado sin parámetros al crear una instancia cuando sea necesario. Si se provee instance, constructor no será nunca invocado y puede ser None.

Definir preferred a True hace de este navegador un resultado preferido para una invocación get() sin argumento. De otra manera, este punto de entrada sólo es útil si planeas definir la variable BROWSER o invocar get() con un argumento no vacío correspondiendo con el nombre de un manejador que declaras.

Distinto en la versión 3.7: fue añadido el parámetro sólo de palabra clave preferred.

Un número de tipos de navegador son predefinidos. Esta tabla muestra los nombres de los tipos que se pueden pasar a la función get() y las instanciaciones correspondientes para las clases de los controladores, todas definidas en este módulo.

Nombre de tipo

Nombre de clase

Notas

'mozilla'

Mozilla('mozilla')

'firefox'

Mozilla('mozilla')

'netscape'

Mozilla('netscape')

'galeon'

Galeon('galeon')

'epiphany'

Galeon('epiphany')

'skipstone'

BackgroundBrowser('skipstone')

'kfmclient'

Konqueror()

(1)

'konqueror'

Konqueror()

(1)

'kfm'

Konqueror()

(1)

'mosaic'

BackgroundBrowser('mosaic')

'opera'

Opera()

'grail'

Grail()

'links'

GenericBrowser('links')

'elinks'

Elinks('elinks')

'lynx'

GenericBrowser('lynx')

'w3m'

GenericBrowser('w3m')

'windows-default'

WindowsDefault

(2)

'macosx'

MacOSXOSAScript('default')

(3)

'safari'

MacOSXOSAScript('safari')

(3)

'google-chrome'

Chrome('google-chrome')

'chrome'

Chrome('chrome')

'chromium'

Chromium('chromium')

'chromium-browser'

Chromium('chromium-browser')

Notas:

«Konqueror» es el manejador de archivos para el entorno de escritorio KDE para Unix y sólo tiene sentido usarlo si KDE está en ejecución. Alguna forma de detectar de manera confiable KDE sería genial; la variable KDEDIR no es suficiente. Ten en cuenta también que el nombre «kfm» es usado incluso utilizando el comando konqueror con KDE 2 — la implementación selecciona la mejor estrategia para ejecutar Konqueror.

Sólo en plataformas Windows.

Only on macOS platform.

Nuevo en la versión 3.3: Ha sido añadido soporte para Chrome/Chromium.

Aquí están algunos ejemplos simples:

url = 'https://docs.python.org/'

# Open URL in a new tab, if a browser window is already open.
webbrowser.open_new_tab(url)

# Open URL in new window, raising the window if possible.
webbrowser.open_new(url)

Objetos controladores de navegador

Los controladores de navegador proveen aquellos métodos que son paralelos a tres de las funciones de conveniencia a nivel del módulo:

controller.open(url, new=0, autoraise=True)

Despliega url usando el navegador manejado por este controlador. Si new es 1, se abre una nueva ventana del navegador si es posible. Si new es 2, se abre una nueva página del navegador («pestaña») si es posible.

controller.open_new(url)

Abre url en una nueva ventana del navegador manejado por este controlador, si es posible, si no, abre url en la única ventana del navegador. Alias open_new().

controller.open_new_tab(url)

Abre url en una nueva página («pestaña») del navegador manejado por este controlador, si es posible, si no equivale a open_new().

Notas al pie

1

Los ejecutables nombrados aquí sin una ruta completa serán buscados en los directorios dados en la variable de entorno PATH.

wsgiref — Utilidades WSGI e implementación de referencia

La Interfaz de Pasarela del Servidor Web, o Web Server Gateway Interface en inglés (WSGI), es una interfaz estándar entre el servidor web y aplicaciones web escritas en Python. Con una interfaz estándar es más sencillo usar una aplicación que soporte WSGI con diferentes servidores web.

Sólo los autores de servidores y frameworks web necesitan conocer cada detalle y caso límite del diseño WSGI. No es necesario conocer cada detalle de WSGI sólo para instalar o escribir una aplicación web usando un framework existente.

wsgiref es una implementación de referencia de la especificación WSGI que se puede usar para añadir soporte WSGI a un servidor o framework web. Este módulo provee utilidades para manipular las variables de entorno WSGI y las cabeceras de respuesta, clases base para implementar servidores WSGI, un servidor HTTP de demostración que sirve aplicaciones WSGI, y una herramienta de validación que comprueba la compatibilidad de servidores y aplicaciones WSGI en base a la especificación PEP 3333 [https://www.python.org/dev/peps/pep-3333].

Vea wsgi.readthedocs.io [https://wsgi.readthedocs.io/] para más información sobre WSGI, así como enlaces a tutoriales y otros recursos.

wsgiref.util – Utilidades de entorno WSGI

Este módulo ofrece una variedad de funciones útiles para trabajar con entornos WSGI. Un entorno WSGI es un diccionario que contiene variables de la petición HTTP, descrito en PEP 3333 [https://www.python.org/dev/peps/pep-3333]. Todas las funciones que aceptan un parámetro environ esperan un diccionario compatible con WSGI. Por favor, consulte la especificación detallada en PEP 3333 [https://www.python.org/dev/peps/pep-3333].

wsgiref.util.guess_scheme(environ)

Retorna una deducción del valor para wsgi.url_scheme que debería ser «http» o «https», buscando la variable de entorno HTTPS en el diccionario environ. El valor de retorno es una cadena.

Esta función es útil al crear un gateway que envuelve CGI o un protocolo similar como FastCGI. Habitualmente, los servidores que ofrecen estos protocolos incluyen una variable HTTPS con el valor «1», «yes», o «on» cuando reciben una petición vía SSL. Así, esta función retorna «https» si encuentra ese valor, o «http», en caso contrario.

wsgiref.util.request_uri(environ, include_query=True)

Retorna la URI completa de la petición, opcionalmente la cadena de consulta, usando el algoritmo encontrado en la sección «URL Reconstruction» de PEP 3333 [https://www.python.org/dev/peps/pep-3333]. Si include_query es falso, la cadena de consulta no se incluye en la URI resultante.

wsgiref.util.application_uri(environ)

Similar a request_uri() excepto que se ignoran las variables PATH_INFO y QUERY_STRING. El resultado es la URI base del objeto de aplicación indicado en la petición.

wsgiref.util.shift_path_info(environ)

Desplaza un solo nombre de PATH_INFO a SCRIPT_NAME y retorna el nombre. Se modifica el diccionario environ, por lo que se deberá usar una copia si se quiere mantener PATH_INFO o SCRIPT_NAME intactos.

Si no quedan segmentos en PATH_INFO, retornará None.

Habitualmente, esta rutina se usa para procesar cada porción de la ruta del URI de la petición, por ejemplo, para usar la ruta como una serie de claves en un diccionario. Esta rutina modifica el entorno pasado para permitir invocar otra aplicación WSGI que esté localizada en la URI objetivo. Por ejemplo, si hay una aplicación WSGI en /foo, y la ruta es /foo/bar/baz, y la aplicación WSGI en /foo llama a shift_path_info(), recibirá la cadena «bar», y se actualizará el entorno para pasarlo a una aplicación WSGI en /foo/bar. Es decir, SCRIPT_NAME cambiará de /foo a /foo/bar y PATH_INFO cambiará de /bar/baz a /baz.

Cuando PATH_INFO es únicamente «/», esta rutina retornará una cadena vacía y añadirá una barra final a SCRIPT_NAME, incluso cuando normalmente los segmentos de ruta vacíos se ignoran y SCRIPT_NAME no acaba con una barra. Este comportamiento es intencional, para asegurar que una aplicación puede diferenciar entre URIs que acaban en /x de las que acaban en /x/ cuando usan esta rutina para atravesar objetos.

wsgiref.util.setup_testing_defaults(environ)

Actualiza environ con valores por defecto triviales con propósito de prueba.

Esta rutina añade varios parámetros requeridos por WSGI, incluyendo HTTP_POST, SERVER_NAME, SERVER_PORT, REQUEST_METHOD, SCRIPT_NAME, PATH_INFO, y todas las variables wsgi.* definidas en PEP 3333 [https://www.python.org/dev/peps/pep-3333]. Sólo ofrece valores por defecto y no reemplaza ningún valor existente en esas variables.

Esta rutina pretende facilitar la preparación de entornos ficticios para pruebas unitarias de servidores y aplicaciones WSGI. NO debería usarse en servidores y aplicaciones WSGI reales, ya que los valores son ficticios!

Ejemplo de uso:

from wsgiref.util import setup_testing_defaults
from wsgiref.simple_server import make_server

# A relatively simple WSGI application. It's going to print out the
# environment dictionary after being updated by setup_testing_defaults
def simple_app(environ, start_response):
    setup_testing_defaults(environ)

    status = '200 OK'
    headers = [('Content-type', 'text/plain; charset=utf-8')]

    start_response(status, headers)

    ret = [("%s: %s\n" % (key, value)).encode("utf-8")
           for key, value in environ.items()]
    return ret

with make_server('', 8000, simple_app) as httpd:
    print("Serving on port 8000...")
    httpd.serve_forever()

Además de las funciones de entorno previas, el módulo wsgiref.util también ofrece las siguientes utilidades varias:

wsgiref.util.is_hop_by_hop(header_name)

Retorna True si “header_name” es una cabecera «Hop-by-Hop» HTTP/1.1, como se define en RFC 2616 [https://tools.ietf.org/html/rfc2616.html].

class wsgiref.util.FileWrapper(filelike, blksize=8192)

Un wrapper para convertir un objeto archivo en un iterator. Los objetos resultantes soportan los estilos de iteración __getitem__() y __iter__(), por compatibilidad con Python 2.1 y Jython. A medida que se itera sobre el objeto, el parámetro opcional blksize se pasará repetidamente al método read() del objeto archivo para obtener cadenas de bytes para entregar. Cuando read() retorna una cadena de bytes vacía, la iteración finalizará y no se podrá reiniciar.

Si filelike tiene un método close(), el objeto retornado también tendrá un método close() que llamará al método close() del objeto archivo subyacente.

Ejemplo de uso:

from io import StringIO
from wsgiref.util import FileWrapper

# We're using a StringIO-buffer for as the file-like object
filelike = StringIO("This is an example file-like object"*10)
wrapper = FileWrapper(filelike, blksize=5)

for chunk in wrapper:
    print(chunk)

Obsoleto desde la versión 3.8: El soporte de sequence protocol es obsoleto.

wsgiref.headers – Herramientas para cabeceras de respuesta WSGI

Este módulo ofrece una sola clase, Headers, para la manipulación de cabeceras de respuesta WSGI usando un interfaz de mapa.

class wsgiref.headers.Headers([headers])

Crea un objeto con interfaz de mapa envolviendo headers, que debe ser una lista de tuplas nombre/valor de las cabeceras, como se describe en PEP 3333 [https://www.python.org/dev/peps/pep-3333]. El valor por defecto de headers es una lista vacía.

Los objetos Headers soportan las operaciones de mapa habituales incluyendo __getitem__(), get(), __setitem__(), setdefault(), __delitem__() y __contains__(). Para cada uno de esos métodos, la clave es el nombre de la cabecera, sin distinción entre mayúsculas y minúsculas, y el valor es el primer valor asociado con el nombre de la cabecera. Establecer una cabecera borra cualquier valor previamente existente y añade un nuevo valor al final de la lista de cabeceras. En general, el orden de las cabeceras existentes se mantiene, con las nuevas cabeceras añadidas al final de la lista de cabeceras.

A diferencia de un diccionario, los objetos Headers no lanzan un error cuando se intenta obtener o eliminar una clave que no está en la lista de cabeceras subyacente. Al intentar obtener una clave inexistente simplemente se retornará None, mientras que el intento de eliminación de una cabecera inexistente simplemente no tendrá ningún efecto.

Los objetos Headers también soportan los métodos keys(), values(), y items(). Las listas retornadas por keys() y items() pueden incluir la misma clave más de una vez si se trata de una cabecera de valor múltiple. La len() de un objeto Headers es la misma que la longitud de sus items(), que es la misma que la longitud de la lista de cabeceras envuelta. De hecho, el método items() simplemente retorna una copia de la lista de cabeceras.

La llamada bytes() sobre un objeto Headers retorna una cadena de bytes formateada y lista para su transmisión como cabeceras de respuesta HTTP. Cada cabecera se ubica en una línea con su valor separado por dos puntos y un espacio. Cada línea finaliza con un retorno de carro y un salto de línea, y la cadena de bytes finaliza con una línea en blanco.

Además de la interfaz de mapa y las funcionalidades de formateado, los objetos Headers también ofrecen los siguientes métodos para consultar y añadir cabeceras con múltiples valores, y para añadir cabeceras con parámetros MIME:

get_all(name)

Retorna una lista de todos los valores para la cabecera indicada.

La lista retornada tendrá los valores ordenados según la lista de cabeceras original o según se hayan añadido a esta instancia, y podrá contener duplicados. Cualquier campo eliminado y añadido de nuevo estará al final de la lista. Si no existen campos con el nombre indicado, retornará una lista vacía.

add_header(name, value, **_params)

Añade una cabecera, posiblemente de valor múltiple, con los parámetros MIME opcionales especificados vía argumentos por palabra clave.

name es el nombre de la cabecera a añadir. Se pueden usar argumentos por palabra clave para establecer parámetros MIME para la cabecera. Cada parámetro debe ser una cadena o None. Todos los guiones bajos en los nombres de parámetros se convierten en guiones, dado que los guiones son inválidos en identificadores Python y muchos parámetros MIME incluyen guiones. Si el valor del parámetro es una cadena, se añade a los parámetros del valor de la cabecera con la forma nombre=valor. Si es None, sólo se añade el nombre del parámetro, para reflejar parámetros MIME sin valor. Ejemplo de uso:

h.add_header('content-disposition', 'attachment', filename='bud.gif')

El código anterior añadirá una cabecera como la siguiente:

Content-Disposition: attachment; filename="bud.gif"

Distinto en la versión 3.5: El parámetro headers es opcional.

wsgiref.simple_server– Un servidor HTTP WSGI simple

Este módulo implementa un servidor HTTP simple, basado en http.server, que sirve aplicaciones WSGI. Cada instancia del servidor sirve una aplicación WSGI simple en una máquina y puerto dados. Si se quiere servir múltiples aplicaciones en una misma máquina y puerto, se deberá crear una aplicación WSGI que analiza PATH_INFO para seleccionar qué aplicación invocar para cada petición. Por ejemplo, usando la función shift_path_info() de wsgiref.util.

wsgiref.simple_server.make_server(host, port, app, server_class=WSGIServer, handler_class=WSGIRequestHandler)

Crea un nuevo servidor WSGI que sirve en host y port, aceptando conexiones para app. El valor de retorno es una instancia de server_class y procesará peticiones usando handler_class. app debe ser un objeto aplicación WSGI, como se define en PEP 3333 [https://www.python.org/dev/peps/pep-3333].

Ejemplo de uso:

from wsgiref.simple_server import make_server, demo_app

with make_server('', 8000, demo_app) as httpd:
    print("Serving HTTP on port 8000...")

    # Respond to requests until process is killed
    httpd.serve_forever()

    # Alternative: serve one request, then exit
    httpd.handle_request()

wsgiref.simple_server.demo_app(environ, start_response)

Esta función es una pequeña pero completa aplicación WSGI que retorna una página de texto con el mensaje «Hello world!» y una lista de pares clave/valor obtenida del parámetro environ. Es útil para verificar que un servidor WSGI, como wsgiref.simple_server, es capaz de ejecutar una aplicación WSGI simple correctamente.

class wsgiref.simple_server.WSGIServer(server_address, RequestHandlerClass)

Crea una instancia de WSGIServer. server_address debe ser una tupla (máquina,puerto) y RequestHandlerClass debe ser la subclase de http.server.BaseHTTPRequestHandler que se usará para procesar peticiones.

Normalmente, no es necesario invocar este constructor, ya que la función make_server() puede gestionar todos los detalles.

WSGIServer es una subclase de http.server.HTTPServer, por lo que todos sus métodos, como serve_forever() y handle_request(), están disponibles. WSGIServer también ofrece los siguientes métodos específicos de WSGI:

set_app(application)

Establece el invocable application como la aplicación WSGI que recibirá las peticiones.

get_app()

Retorna la aplicación invocable actual.

Habitualmente, sin embargo, no es necesario usar estos métodos adicionales, ya que set_app() se llama desde make_server() y get_app() existe sobretodo para el beneficio de instancias del gestor de peticiones.

class wsgiref.simple_server.WSGIRequestHandler(request, client_address, server)

Crea un gestor HTTP para la request indicada (es decir un socket), client_address (una tupla ``(máquina,puerto)``), y *server (una instancia WSGIServer).

No es necesario crear instancias de esta clase directamente. Se crean automáticamente bajo demanda por objetos WSGIServer. Sin embargo, se pueden crear subclases de esta clase y proveerlas como handler_class a la función make_server(). Algunos métodos posiblemente relevantes para sobreescribir en estas subclases:

get_environ()

Retorna un diccionario con el entorno WSGI para una petición. La implementación por defecto copia el contenido del diccionario atributo base_environ del objeto WSGIserver y añade varias cabeceras derivadas de la petición HTTP. Cada llamada a este método debe retornar un nuevo diccionario con todas las variables de entorno CGI relevante especificadas en PEP 3333 [https://www.python.org/dev/peps/pep-3333].

get_stderr()

Retorna el objeto que debe usarse como el flujo de wsgi.errors. La implementación por defecto retorna simplemente sys.stderr.

handle()

Procesa la petición HTTP. La implementación por defecto crea una instancia gestora usando una clase wsgiref.handlers para implementar la interfaz de aplicación WSGI real.

wsgiref.validate — Verificador de compatibilidad WSGI

Al crear nuevos objetos aplicación WSGI, frameworks, servidores, o middleware, puede ser útil validar la compatibilidad del nuevo código usando wsgiref.validate. Este módulo ofrece una función que crea objetos de aplicación WSGI que validan las comunicaciones entre un servidor o gateway WSGI y un objeto de aplicación WSGI, para comprobar la compatibilidad del protocolo en ambos lados.

Hay que observar que esta utilidad no garantiza compatibilidad completa con PEP 3333 [https://www.python.org/dev/peps/pep-3333]. La ausencia de errores usando este módulo no implica que no existan errores. Sin embargo, si este módulo produce errores, implica que o el servidor o la aplicación no son 100% compatibles.

Este módulo se basa en el módulo paste.lint de la librería Python Paste de Ian Bicking.

wsgiref.validate.validator(application)

Envuelve application y retorna un nuevo objeto de aplicación WSGI. La aplicación retornada reenviará todas las peticiones a la application original y comprobará que tanto la application como el servidor que la llama son compatibles con la especificación WSGI y con RFC 2616 [https://tools.ietf.org/html/rfc2616.html].

Cualquier incompatibilidad detectada provocará el lanzamiento de un AssertionError. Nótese que, sin embargo, cómo se gestionan estos errores depende del servidor. Por ejemplo, wsgiref.simple_server y otros servidores basados en wsgiref.handlers, que no sobreescriben los métodos de gestión de errores para hacer otras cosas, simplemente escribirán un mensaje de que el error ha ocurrido y volcarán la traza de error en sys.stderr o algún otro flujo de errores.

Este wrapper puede también generar salidas usando el módulo warnings para señalar comportamientos que son cuestionables pero que no están realmente prohibidos por PEP 3333 [https://www.python.org/dev/peps/pep-3333]. A no ser que se suprima esta salida usando opciones de línea de comandos de Python o la API de warnings, cualquier aviso se escribirá en sys.stderr, en lugar de en wsgi.errors, aunque sean el mismo objeto.

Ejemplo de uso:

from wsgiref.validate import validator
from wsgiref.simple_server import make_server

# Our callable object which is intentionally not compliant to the
# standard, so the validator is going to break
def simple_app(environ, start_response):
    status = '200 OK'  # HTTP Status
    headers = [('Content-type', 'text/plain')]  # HTTP Headers
    start_response(status, headers)

    # This is going to break because we need to return a list, and
    # the validator is going to inform us
    return b"Hello World"

# This is the application wrapped in a validator
validator_app = validator(simple_app)

with make_server('', 8000, validator_app) as httpd:
    print("Listening on port 8000....")
    httpd.serve_forever()

wsgiref.handlers – Clases base servidor/gateway

Este módulo ofrece clases gestoras base para implementar servidores y gateways WSGI. Estas clases base gestionan la mayoría del trabajo de comunicarse con una aplicación WSGI, siempre que se les dé un entorno CGI, junto con una entrada, una salida, y un flujo de errores.

class wsgiref.handlers.CGIHandler

Invocación basada en CGI vía sys.stdin, sys.stdout, sys.stderr y os.environ. Esto es útil cuando se quiere ejecutar una aplicación WSGI como un script CGI. Simplemente es necesario invocar CGIHandler().run(app), donde app es el objeto de aplicación WSGI que se quiere invocar.

Esta clase es una subclase de BaseCGIHandler que establece wsgi.run_once a cierto, wsgi.multithread a falso, y wsgi.multiprocess a cierto, y siempre usa sys y os para obtener los flujos y entorno CGI necesarios.

class wsgiref.handlers.IISCGIHandler

Una alternativa especializada a CGIHandler, para usar al desplegar en servidores web Microsoft IIS, sin establecer la opción de configuración allowPathInfo (IIS>=7) o la meta-base allowPathInfoForScriptMappings (IIS<7).

Por defecto, IIS entrega PATH_INFO que duplica SCRIPT_NAME al principio, causando problemas con aplicaciones WSGI que implementan enrutamiento. Este gestor elimina las partes duplicadas de la ruta.

IIS se puede configurar para pasar el PATH_INFO correcto, pero esto causa otro error donde PATH_TRANSLATED es incorrecto. Afortunadamente, esta variable rara vez se usa y no está garantizada por WSGI. Sin embargo, en IIS<7, la configuración solo se puede realizar en un nivel de vhost, lo que afecta a todas las demás asignaciones de scripts, muchas de las cuales se rompen cuando se exponen al error PATH_TRANSLATED. Por esta razón, IIS<7 casi nunca se implementa con la solución (incluso IIS7 rara vez lo usa porque todavía no tiene una interfaz de usuario).

No hay forma de que el código CGI detecte cuándo la opción está activada, por lo que se ofrece una clase gestora separada. Se usa de la misma forma que CGIHandler, p.e. llamando a IISCGIHandler().run(app), donde app es el objeto aplicación WSGI que se desea invocar.

Nuevo en la versión 3.2.

class wsgiref.handlers.BaseCGIHandler(stdin, stdout, stderr, environ, multithread=True, multiprocess=False)

Similar a CGIHandler, pero en lugar de usar los módulos sys y os, el entorno CGI y los flujos de E/S se especifican explícitamente. Los valores multithread y multiprocess se pasan a las aplicaciones ejecutadas por la instancia de gestión como wsgi.multithread y wsgi.multiprocess.

Esta clase es una subclase de SimpleHandler para usarse con servidores HTTP que no reciben peticiones directas de Internet, HTTP origin servers. Al escribir una implementación de un protocolo de pasarela, como CGI, FastCGI, SCGI, etcétera, que use una cabecera Status: para enviar un estado HTTP, probablemente sea adecuado heredar de esta clase, en lugar de SimpleHandler.

class wsgiref.handlers.SimpleHandler(stdin, stdout, stderr, environ, multithread=True, multiprocess=False)

Similar a BaseCGIHandler pero diseñada para usarse con servidores que reciban peticiones directamente de Internet, o HTTP origin servers. Al escribir una implementación de un servidor HTTP, probablemente prefiera heredar de esta clase en lugar de BaseCGIHandler.

Esta clase es una subclase de BaseHandler. Sobreescribe los métodos __init__(), get_stdin(), get_stderr(), add_cgi_vars(), _write() y _flush() para soportar el uso explícito del entorno y los flujos a partir del constructor. El entorno y los flujos especificados se almacenan en los atributos stdin, stdout, stderr y environ.

El método write() de stdout podría escribir cada fragmento de información completamente, como io.BufferedIOBase.

class wsgiref.handlers.BaseHandler

Esta es una clase base abstracta para ejecutar aplicaciones WSGI. Cada instancia gestionará una sola petición HTTP, aunque en principio se podría crear una subclase reutilizable para múltiples peticiones.

Las instancias de BaseHandler tiene un sólo método para uso externo:

run(app)

Ejecuta la aplicación WSGI app indicada.

Todos los otros métodos de BaseHandler se invocan por este método en el proceso de ejecutar la aplicación, es decir, existen principalmente para permitir personalizar el proceso.

Los métodos siguientes DEBEN sobrescribirse en una subclase:

_write(data)

Enviar los bytes data para la transmisión al cliente. Es correcto que este método realmente transmita la información. La clase BaseHandler simplemente separa las operaciones de escritura y liberación para una mayor eficiencia cuando el sistema subyacente realmente hace esa distinción.

_flush()

Forzar la transmisión de los datos en el búfer al cliente. Es correcto si este método no es operativo, p.e., si _write() realmente envía los datos.

get_stdin()

Retorna un objeto de flujo de entrada disponible para usar como wsgi.input de la petición en proceso actualmente.

get_stderr()

Retorna un objeto de flujo de salida disponible para usar como wsgi.errors de la petición en proceso actualmente.

add_cgi_vars()

Inserta las variables CGI para la petición actual en el atributo environ.

A continuación se describen algunos métodos y atributos más que podría ser interesante sobrescribir. Esta lista es sólo un sumario, sin embargo, y no incluye cada método que puede ser sobrescrito. Conviene consultar las docstrings y el código fuente para obtener información adicional antes de intentar crear una subclase de BaseHandler personalizada.

Atributos y métodos para personalizar el entorno WSGI:

wsgi_multithread

El valor a usar en la variable de entorno wsgi.multithread. Por defecto es cierto en BaseHandler, pero puede tener un valor por defecto distinto (o establecerse en el constructor) en otras subclases.

wsgi_multiprocess

El valor a usar en la variable de entorno wsgi.multiprocess. Por defecto es cierto en BaseHandler, pero puede tener un valor por defecto distinto (o establecerse en el constructor) en otras subclases.

wsgi_run_once

El valor a usar en la variable de entorno wsgi.run_once. Por defecto es falso en BaseHandler, pero en CGIHandler es cierto por defecto.

os_environ

Las variables de entorno por defecto que se incluirán en el entorno WSGI de cada petición. Por defecto, es una copia de os.environ cuando se importa wsgiref.handlers, pero otras subclases pueden crear las suyas propias a nivel de clase o de instancia. Se debe tener en cuenta que el diccionario se debe considerar como de sólo lectura, ya que el valor por defecto se comparte entre múltiples clases e instancias.

server_software

Si el atributo origin_server tiene valor, éste se usa para establecer el valor por defecto de la variable de entorno WSGI SERVER_SOFTWARE y un cabecera Server: por defecto en las respuestas HTTP. Las clases gestoras que no son HTTP origin servers, como BaseCGIHandler y CGIHandler, ignoran este atributo.

Distinto en la versión 3.3: El término «Python» se reemplaza con el término específico correspondiente a la implementación del intérprete, como «CPython», «Jython», etc.

get_scheme()

Retorna el esquema usado en la URL para la petición actual. La implementación por defecto utiliza la función guess_scheme() de wsgiref.util para adivinar si el esquema debería ser «http» o «https», basándose en las variables de environ de la petición actual.

setup_environ()

Establece el atributo environ a un entorno WSGI completo. La implementación por defecto utiliza todos los métodos y atributos anteriormente mencionados, más los métodos get_stdin(), get_stderr() y add_cgi_vars(), y el atributo wsgi_file_wrapper. También incluye una clave SERVER_SOFTWARE si no existe, siempre y cuando el atributo origin_server tiene un valor válido y el atributo server_software está establecido.

Métodos y atributos para personalizar el manejo de excepciones:

log_exception(exc_info)

Envía la tupla exc_info al registro del servidor. exc_info es un tupla (type, value, traceback). La implementación por defecto simplemente escribe el seguimiento de la pila en el flujo wsgi.errors de la petición y lo vacía. Las subclases pueden sobrescribir éste método para cambiar el formato o redirigir la salida, enviar mensajes de correo con el seguimiento de pila a un administrador o cualquier otra acción que se considere adecuada.

traceback_limit

El máximo número de marcos a incluir en la salida de seguimientos de pilas por el método por defecto log_exception(). Si vale None, se incluyen todos los marcos.

error_output(environ, start_response)

Este método es una aplicación WSGI para generar una página de error para el usuario. Sólo se invoca si un error ocurre antes de enviar las cabeceras al cliente.

Este método puede acceder a la información de error actual usando sys.exc_info() y debería pasar esa información a start_response cuando es llamada, tal y como se describe en la sección «Error Handling» de PEP 3333 [https://www.python.org/dev/peps/pep-3333].

La implementación por defecto sólo utiliza los atributos error_status, error_headers y error_body para generar una página de salida. Las subclases pueden sobrescribir éste para producir una salida de error dinámica mejor.

Hay que tener en cuenta, sin embargo, que no se recomienda, desde una perspectiva de seguridad, mostrar información de diagnóstico a cualquier usuario antiguo. Idealmente, se debería hacer algo especial para activar la salida de información de diagnóstico, motivo por el que la implementación por defecto no incluye ninguna.

error_status

El estado HTTP utilizado para las respuestas de error. Se debería utilizar una de las cadenas de estado definidas en PEP 3333 [https://www.python.org/dev/peps/pep-3333]. Por defecto es un código 500 y un mensaje.

error_headers

Las cabeceras HTTP utilizadas por las respuestas de error. Debería tratarse de una lista de cabeceras de respuesta WSGI (tuplas (name, value)), tal y como se describe en PEP 3333 [https://www.python.org/dev/peps/pep-3333]. La lista por defecto simplemente establece el tipo de contenido a text/plain.

error_body

El cuerpo de la respuesta de error. Debería ser una cadena de bytes con el cuerpo de la respuesta HTTP. Por defecto contiene el texto plano A server error occurred. Please contact the administrator.

Métodos y atributos para la funcionalidad «Optional Platform-Specific File Handling» de PEP 3333 [https://www.python.org/dev/peps/pep-3333]:

wsgi_file_wrapper

Una factoría wsgi.file_wrapper, o None. El valor por defecto de este atributo es la clase wsgiref.util.FileWrapper.

sendfile()

Sobrescribir para implementar la transmisión de ficheros específica para la plataforma. Este método se llama sólo si el valor de retorno de la aplicación es una instancia de la clase especificada por el atributo wsgi_file_wrapper. Debería retornar un valor cierto si fue capaz de transmitir correctamente el fichero, de modo que el código por defecto de transmisión no será ejecutado. La implementación por defecto de este método simplemente retorna un valor falso.

Métodos y atributos varios:

origin_server

Este atributo debería establecerse a cierto si los métodos _write() y _flush() están siendo usados para comunicar directamente al cliente, en lugar de usar un protocolo de pasarela CGI que requiere el estado HTTP en una cabecera Status: especial.

El valor por defecto de este atributo es cierto en BaseHandler, pero en BaseCGIHandler y CGIHandler es falso.

http_version

Si origin_server es cierto, este atributo de tipo cadena se usa para establecer la versión HTTP de la respuesta enviada al cliente. Por defecto es "1.0".

wsgiref.handlers.read_environ()

Transcodifica las variables CGI de os.environ a cadenas «bytes in unicode» definidas en PEP 3333 [https://www.python.org/dev/peps/pep-3333], retornando un nuevo diccionario. Esta función se usa en CGIHandler y IISCGIHandler en lugar de usar directamente os.environ, lo que no es necesariamente compatible con EWGI en todas las plataformas y servidores web usando Python 3 – específicamente, aquellas en las que el entorno actual del sistema operativo es Unicode, p.e. Windows, o en las que el entorno está en bytes, pero la codificación del sistema usada por Python para descodificar lo es cualquier otro que ISO-8859-1, por ejemplo, sistemas UNIX que usen UTF-8.

Cuando se está implementando un gestor basado en CGI propio, probablemente se requiera usar esta rutina en lugar de sólo copiar directamente los valores de os.environ.

Nuevo en la versión 3.2.

Ejemplos

Ésta es una aplicación WSGI «Hello World» que funciona:

from wsgiref.simple_server import make_server

# Every WSGI application must have an application object - a callable
# object that accepts two arguments. For that purpose, we're going to
# use a function (note that you're not limited to a function, you can
# use a class for example). The first argument passed to the function
# is a dictionary containing CGI-style environment variables and the
# second variable is the callable object.
def hello_world_app(environ, start_response):
    status = '200 OK'  # HTTP Status
    headers = [('Content-type', 'text/plain; charset=utf-8')]  # HTTP Headers
    start_response(status, headers)

    # The returned object is going to be printed
    return [b"Hello World"]

with make_server('', 8000, hello_world_app) as httpd:
    print("Serving on port 8000...")

    # Serve until process is killed
    httpd.serve_forever()

Ejemplo de una aplicación WSGI que sirve el directorio actual, acepta un directorio opcional y un número de puerto (default: 8000) en la línea de comandos:

#!/usr/bin/env python3
'''
Small wsgiref based web server. Takes a path to serve from and an
optional port number (defaults to 8000), then tries to serve files.
Mime types are guessed from the file names, 404 errors are raised
if the file is not found. Used for the make serve target in Doc.
'''
import sys
import os
import mimetypes
from wsgiref import simple_server, util

def app(environ, respond):

    fn = os.path.join(path, environ['PATH_INFO'][1:])
    if '.' not in fn.split(os.path.sep)[-1]:
        fn = os.path.join(fn, 'index.html')
    type = mimetypes.guess_type(fn)[0]

    if os.path.exists(fn):
        respond('200 OK', [('Content-Type', type)])
        return util.FileWrapper(open(fn, "rb"))
    else:
        respond('404 Not Found', [('Content-Type', 'text/plain')])
        return [b'not found']

if __name__ == '__main__':
    path = sys.argv[1] if len(sys.argv) > 1 else os.getcwd()
    port = int(sys.argv[2]) if len(sys.argv) > 2 else 8000
    httpd = simple_server.make_server('', port, app)
    print("Serving {} on port {}, control-C to stop".format(path, port))
    try:
        httpd.serve_forever()
    except KeyboardInterrupt:
        print("Shutting down.")
        httpd.server_close()

urllib — URL módulos de manipulación

Código fuente: Lib/urllib/ [https://github.com/python/cpython/tree/3.9/Lib/urllib/]

urllib es un paquete que reúne varios módulos para trabajar con URLs:

urllib.request para abrir y leer URLs

urllib.error contiene las excepciones propuestas por urllib.request

urllib.parse para parsear URLs

urllib.robotparser para parsear``robots.txt`` archivos

urllib.request — Biblioteca extensible para abrir URLs

Código fuente: Lib/urllib/request.py [https://github.com/python/cpython/tree/3.9/Lib/urllib/request.py]

El módulo urllib.request define funciones y clases que ayudan en la apertura de URLs (la mayoría HTTP) en un mundo complejo — autenticación básica y digest, redirecciones, cookies y más.

Ver también

Se recomienda el paquete Requests [https://requests.readthedocs.io/en/master/] para una interfaz de cliente HTTP de mayor nivel.

El módulo urllib.request define las siguientes funciones:

urllib.request.urlopen(url, data=None, [timeout, ]*, cafile=None, capath=None, cadefault=False, context=None)

Abre la URL url, la cual puede ser una cadena de caracteres o un objeto Request.

data debe ser un objeto que especifique datos adicionales a ser enviados al servidor o None si no se necesitan tales datos. Vea Request para más detalles.

El módulo urllib.request usa HTTP/1.1 e incluye el encabezado Connection:close en sus peticiones HTTP.

El parámetro opcional timeout especifica un tiempo de expiración en segundos para operaciones bloqueantes como el intento de conexión (si no se especifica, será usado el tiempo de expiración global predeterminado). Esto actualmente sólo funciona para conexiones HTTP, HTTPS y FTP.

Si se especifica context, debe ser una instancia ssl.SSLContext describiendo las diferentes opciones SSL. Vea HTTPSConnection para más detalles.

Los parámetros opcionales cafile y capath especifican un conjunto de certificados CA de confianza para peticiones HTTPS. cafile debe apuntar a un único archivo que contenga un paquete de certificados CA, mientras capath debe apuntar a un directorio de archivos de certificado hash. Se puede encontrar más información en ssl.SSLContext.load_verify_locations().

Se ignora el parámetro cadefault.

Esta función siempre retorna un objeto que puede actuar como un gestor de contexto, y tiene las propiedades url, headers y status. Véase urllib.response.addinfourl para más detalles sobre estas propiedades.

Para URLs HTTP y HTTPS, esta función retorna un objeto http.client.HTTPResponse ligeramente modificado. Adicionalmente a los tres nuevos métodos anteriores, el atributo msg contiene la misma información que el atributo reason — la frase de motivo devuelta por el servidor — en lugar de los encabezados de la respuesta como se especifica en la documentación para HTTPResponse.

Para URLs FTP, de archivo y de datos y para peticiones manejadas explícitamente por las clases heredadas URLopener y FancyURLopener, esta función retorna un objeto urllib.response.addinfourl.

Genera URLError en errores de protocolo.

Tenga en cuenta que None puede ser retornado si ningún manejador gestiona la petición (aunque el OpenerDirector global instalado de manera predeterminada usa UnknownHandler para asegurar que esto nunca suceda).

Adicionalmente, si se detectan configuraciones de proxy (por ejemplo, cuando se establece una variable de entorno *_proxy como http_proxy), ProxyHandler está instalada de forma predeterminada y se asegura que las peticiones son gestionadas a través del proxy.

La función heredada de Python 2.6 y anteriores urllib.urlopen ha sido descontinuada, urllib.request.urlopen() corresponde a la antigua urllib2.urlopen. La gestión de proxy, la cual se hacía pasando un parámetro diccionario a urllib.urlopen, puede ser obtenida usando objetos ProxyHandler.

Genera un evento de auditoría urllib.Request con los argumentos fullurl, data, headers, method.

Distinto en la versión 3.2: cafile y capath fueron añadidos.

Distinto en la versión 3.2: Los hosts virtuales HTTPS ahora están soportados si es posible (esto es, si ssl.HAS_SNI es verdadero).

Nuevo en la versión 3.2: data puede ser un objeto iterable.

Distinto en la versión 3.3: cadefault fue añadido.

Distinto en la versión 3.4.3: context fue añadido.

Obsoleto desde la versión 3.6: cafile, capath y cadefault están obsoletos en favor de context. Por favor, use ssl.SSLContext.load_cert_chain() en su lugar o deja a ssl.create_default_context() seleccionar el certificado de confianza CA del sistema por ti.

urllib.request.install_opener(opener)

Instala una instancia OpenerDirector como el abridor global predeterminado. Instalar un abridor sólo es necesario si quieres que urlopen use ese abridor; si no, simplemente invoca OpenerDirector.open() en lugar de urlopen(). El código no comprueba por un OpenerDirector real y cualquier clase con la interfaz apropiada funcionará.

urllib.request.build_opener([handler, ...])

Retorna una instancia OpenerDirector, la cual encadena los manejadores en el orden dado. handlers pueden ser tanto instancias de BaseHandler o subclases de BaseHandler (en cuyo caso debe ser posible invocar el constructor sin ningún parámetro). Instancias de las siguientes clases estarán delante del handlers, a no ser que el handlers las contenga, instancias o subclases de ellas: ProxyHandler (si son detectadas configuraciones de proxy), UnknownHandler, HTTPHandler, HTTPDefaultErrorHandler, HTTPRedirectHandler, FTPHandler, FileHandler, HTTPErrorProcessor.

Si la instalación de Python tiene soporte SSL (ej. si se puede importar el módulo ssl), también será añadida HTTPSHandler.

Una subclase de BaseHandler puede cambiar también su atributo handler_order para modificar su posición en la lista de manejadores.

urllib.request.pathname2url(path)

Convierte el nombre de ruta path desde la sintaxis local para una ruta a la forma usada en el componente ruta de una URL. Esto no produce una URL completa. El valor retornado ya estará entrecomillado usando la función quote().

urllib.request.url2pathname(path)

Convierte el componente ruta path desde una URL codificada con porcentajes a la sintaxis local para una ruta. No acepta una URL completa. Esta función usa unquote() para decodificar path.

urllib.request.getproxies()

This helper function returns a dictionary of scheme to proxy server URL mappings. It scans the environment for variables named <scheme>_proxy, in a case insensitive approach, for all operating systems first, and when it cannot find it, looks for proxy information from System Configuration for macOS and Windows Systems Registry for Windows. If both lowercase and uppercase environment variables exist (and disagree), lowercase is preferred.

Nota

Si la variable del entorno REQUEST_METHOD está definida, lo cual usualmente indica que tu script está ejecutándose en un entorno CGI, la variable de entorno HTTP_PROXY (mayúsculas _PROXY) será ignorada. Esto es porque esa variable puede ser inyectada por un cliente usando el encabezado HTTP «Proxy:». Si necesitas usar un proxy HTTP en un entorno CGI, usa ProxyHandler explícitamente o asegúrate de que el nombre de la variable está en minúsculas (o al menos el sufijo _proxy).

Se proveen las siguientes clases:

class urllib.request.Request(url, data=None, headers={}, origin_req_host=None, unverifiable=False, method=None)

Esta clase es un abstracción de una petición URL.

url debe ser una cadena de caracteres conteniendo una URL válida.

data debe ser un objeto que especifique datos adicionales a enviar al servidor o None si no se necesitan tales datos. Actualmente las peticiones HTTP son las únicas que usan data. Los tipos de objetos soportados incluyen bytes, objetos como archivos e iterables de objetos como bytes. Si no se ha provisto el campo de encabezado Content-Length ni Transfer-Encoding, HTTPHandler establecerá estos encabezados de acuerdo al tipo de data. Content-Length será usado para enviar objetos de bytes, mientras Transfer-Encoding: chunked como se especifica en RFC 7230 [https://tools.ietf.org/html/rfc7230.html], Sección 3.3.1 será usado para enviar archivos y otros iterables.

Para un método de una petición HTTP POST, data debe ser un buffer en el formato estándar application/x-www-form-urlencoded. La función urllib.parse.urlencode() toma un mapeo o una secuencia de tuplas de dos valores y retorna una cadena de caracteres ASCII en este formato. Debe ser codificada a bytes antes de ser usada como el parámetro data.

headers should be a dictionary, and will be treated as if add_header() was called with each key and value as arguments. This is often used to «spoof» the User-Agent header value, which is used by a browser to identify itself – some HTTP servers only allow requests coming from common browsers as opposed to scripts. For example, Mozilla Firefox may identify itself as "Mozilla/5.0 (X11; U; Linux i686) Gecko/20071127 Firefox/2.0.0.11", while urllib’s default user agent string is "Python-urllib/2.6" (on Python 2.6). All header keys are sent in camel case.

Un encabezado apropiado Content-Type debe ser incluido si el argumento data está presente. Si este encabezado no ha sido provisto y data no es None, será añadido Content-Type: application/x-www-form-urlencoded de forma predeterminada.

Los siguientes dos argumentos sólo tienen interés para la gestión correcta de cookies HTTP de terceros:

origin_req_host debe ser el host de la petición de la transacción origen, como define RFC 2965 [https://tools.ietf.org/html/rfc2965.html]. Por defecto es http.cookiejar.request_host(self). Este es el nombre de host o la dirección IP de la petición original que fue iniciada por el usuario. Por ejemplo, si la petición es para una imagen en un documento HTML, debe ser el host de la petición para la página que contiene la imagen.

unverifiable debe indicar si la petición no es verificable, como define RFC 2965 [https://tools.ietf.org/html/rfc2965.html]. Por defecto es False. Una petición no verificable es una cuya URL el usuario no tuvo opción de aprobar. Por ejemplo, si la petición es por una imagen en un documento HTML y el usuario no tuvo opción de aprobar la obtención automática de la imagen, este debe ser verdadero.

method debe ser una cadena que indica el método de la petición HTTP que será usado (ej. 'HEAD'). Si se provee, su valor es almacenado en el atributo method y usado por get_method(). Por defecto es 'GET' si data es None, o 'POST' si no. Las subclases pueden indicar un método predeterminado diferente estableciendo el atributo method es la clase misma.

Nota

La petición no funcionará como se espera si el objeto de datos es incapaz de entregar su contenido más de una vez (ej. un archivo o un iterable que puede producir el contenido sólo una vez) y la petición se reintentará para redirecciones HTTP o autenticación. El data es enviado al servidor HTTP directamente después de los encabezados. No hay soporte para una expectativa de funcionamiento 100% continuo en la biblioteca.

Distinto en la versión 3.3: El argumento Request.method es añadido a la clase Request.

Distinto en la versión 3.4: El atributo predeterminado Request.method puede ser indicado a nivel de clase.

Distinto en la versión 3.6: No se genera un error si el Content-Length no ha sido provisto y data no es None ni un objeto de bytes. En su lugar recurre a la codificación de transferencia fragmentada.

class urllib.request.OpenerDirector

La clase OpenerDirector abre URLs mediante la encadenación conjunta de BaseHandler. Este maneja el encadenamiento de manejadores y la recuperación de errores.

class urllib.request.BaseHandler

Esta es la clase base para todos los manejadores registrados — y manejan sólo las mecánicas simples del registro.

class urllib.request.HTTPDefaultErrorHandler

Una clase la cual define un manejador predeterminado para los errores de respuesta HTTP; todas las respuestas son convertidas en excepciones HTTPError.

class urllib.request.HTTPRedirectHandler

Una clase para manejar redirecciones.

class urllib.request.HTTPCookieProcessor(cookiejar=None)

Una clase para manejar Cookies HTTP.

class urllib.request.ProxyHandler(proxies=None)

Cause requests to go through a proxy. If proxies is given, it must be a dictionary mapping protocol names to URLs of proxies. The default is to read the list of proxies from the environment variables <protocol>_proxy. If no proxy environment variables are set, then in a Windows environment proxy settings are obtained from the registry’s Internet Settings section, and in a macOS environment proxy information is retrieved from the System Configuration Framework.

Para deshabilitar la detección automática de proxy pasa un diccionario vacío.

La variable de entorno no_proxy puede ser usada para especificar hosts los cuales no deben ser alcanzados mediante proxy; si se establece, debe ser una lista separada por comas de sufijos de nombres de host, con :port añadidos opcionalmente, por ejemplo cern.ch,ncsa.uiuc.edu,some.host:8080.

Nota

HTTP_PROXY será ignorado si se establece una variable REQUEST_METHOD; vea la documentación de getproxies().

class urllib.request.HTTPPasswordMgr

Mantiene una base de datos de mapeos (realm, uri) -> (user, password).

class urllib.request.HTTPPasswordMgrWithDefaultRealm

Mantiene una base de datos de mapeos (realm, uri) -> (user, password). Un reino de None se considera un reino caza todo, el cual es buscado si ningún otro reino encaja.

class urllib.request.HTTPPasswordMgrWithPriorAuth

Una variante de HTTPPasswordMgrWithDefaultRealm que también tiene una base de datos de mapeos uri -> is_authenticated. Puede ser usada por un manejador BasicAuth para determinar cuando enviar credenciales de autenticación inmediatamente en lugar de esperar primero a una respuesta 401.

Nuevo en la versión 3.5.

class urllib.request.AbstractBasicAuthHandler(password_mgr=None)

Esta es una clase mixin que ayuda con la autenticación HTTP, tanto al host remoto y a un proxy. Si se proporciona password_mgr, debe ser algo compatible con HTTPPasswordMgr; refiera a la sección Objetos HTTPPasswordMgr para información sobre la interfaz que debe ser soportada. Si passwd_mgr proporciona también métodos is_authenticated y update_authenticated (vea Objetos HTTPPasswordMgrWithPriorAuth), entonces el manejador usará el is_authenticated resultado para una URI dada para determinar el envío o no de credenciales de autenticación con la petición. Si is_authenticated retorna True para la URI, las peticiones subsecuentes a la URI o cualquiera de las super URIs incluirán automáticamente los credenciales de autenticación.

Nuevo en la versión 3.5: Añadido soporte is_authenticated.

class urllib.request.HTTPBasicAuthHandler(password_mgr=None)

Administra autenticación con el host remoto. Si se proporciona password_mgr, debe ser compatible con HTTPPasswordMgr; refiera a la sección Objetos HTTPPasswordMgr para información sobre la interfaz que debe ser soportada. HTTPBasicAuthHandler generará un ValueError cuando se presente con un esquema de Autenticación incorrecto.

class urllib.request.ProxyBasicAuthHandler(password_mgr=None)

Administra autenticación con el proxy. Si se proporciona password_mgr debe ser compatible con HTTPPasswordMgr; refiera a la sección Objetos HTTPPasswordMgr para información sobre la interfaz que debe ser soportada.

class urllib.request.AbstractDigestAuthHandler(password_mgr=None)

Esto es una clase mixin que ayuda con la autenticación HTTP, tanto al host remoto como a un proxy. Si se proporciona password_mgr debe ser compatible con HTTPPasswordMgr; refiera a la sección Objetos HTTPPasswordMgr para información sobre la interfaz que debe ser soportada.

class urllib.request.HTTPDigestAuthHandler(password_mgr=None)

Maneja autenticación con el host remoto. Si se proporciona password_mgr debe ser compatible con HTTPPasswordMgr; refiera a la sección Objetos HTTPPasswordMgr para información sobre la interfaz que debe ser soportada. Cuando se añaden tanto el Manejador de Autenticación Digest (Digest Authentication Handler) como el Manejador de Autenticación Básico (Basic Authentication Handler) la Autenticación Digest siempre se intenta primero. Si la Autenticación Digest retorna una respuesta 40x de nuevo, se envía al controlador de Autenticación Básica para Manejar. Este método Handler generará un ValueError cuando sea presentado con un esquema de autenticación diferente a Digest o Básico.

Distinto en la versión 3.3: Genera ValueError en Esquema de Autenticación no soportado.

class urllib.request.ProxyDigestAuthHandler(password_mgr=None)

Administra autenticación con el proxy. Si se proporciona password_mgr debe ser compatible con HTTPPasswordMgr; refiera a la sección Objetos HTTPPasswordMgr para información sobre la interfaz que debe ser soportada.

class urllib.request.HTTPHandler

Una clase para gestionar apertura de URLs HTTP.

class urllib.request.HTTPSHandler(debuglevel=0, context=None, check_hostname=None)

Una clase para gestionar apertura de URLs HTTPS. context y check_hostname tienen el mismo significado que en http.client.HTTPSConnection.

Distinto en la versión 3.2: context y check_hostname fueron añadidos.

class urllib.request.FileHandler

Abre archivos locales.

class urllib.request.DataHandler

Abre URLs de datos.

Nuevo en la versión 3.4.

class urllib.request.FTPHandler

Abre URLs FTP.

class urllib.request.CacheFTPHandler

Abre URLs FTP, manteniendo una caché de conexiones FTP abiertas para minimizar retrasos.

class urllib.request.UnknownHandler

Una clase caza todo para gestionar URLs desconocidas.

class urllib.request.HTTPErrorProcessor

Procesa errores de respuestas HTTP.

Objetos Request

Los siguientes métodos describen la interfaz pública de Request por lo que pueden ser sobrescritos en subclases. También define varios atributos públicos que pueden ser usado por clientes para inspeccionar la respuesta analizada.

Request.full_url

La URL original pasada al constructor.

Distinto en la versión 3.4.

Request.full_url es una propiedad con setter, getter y deleter. Obtener full_url retorna la petición URL original con el fragmento, si este estaba presente.

Request.type

El esquema de URI.

Request.host

La autoridad de URI, típicamente un host, pero también puede contener un puerto separado por un caracter de doble punto.

Request.origin_req_host

El host original de la petición, sin puerto.

Request.selector

La ruta de URI. Si Request usa un proxy, entonces selector será la URL completa que se pasa al proxy.

Request.data

El cuerpo de la entidad para la solicitud o None si no es especificado.

Distinto en la versión 3.4: Cambiar el valor de Request.data elimina ahora el encabezado «Content-Length» si fue establecido o calculado previamente.

Request.unverifiable

booleano, indica si la petición no es verificable como se define por RFC 2965 [https://tools.ietf.org/html/rfc2965.html].

Request.method

El método de petición HTTP a usar. Por defecto su valor es None, lo que significa que get_method() realizará su cálculo normal del método a usar. Su valor puede ser definido (sobrescribiendo así el cálculo predeterminado en get_method()) tanto proporcionando un valor por defecto estableciéndolo a nivel de clase en una subclase de Request o pasando un valor al constructor de Request por medio del argumento method.

Nuevo en la versión 3.3.

Distinto en la versión 3.4: Un valor predeterminado puede ser establecido ahora en subclases; previamente sólo podía ser definido mediante el argumento del constructor.

Request.get_method()

Retorna una cadena indicando el método de petición HTTP. Si Request.method no es None, retorna su valor, de otra forma retorna 'GET' si Request.data es None o 'POST' si no lo es. Esto sólo es significativo para peticiones HTTP.

Distinto en la versión 3.3: get_method ahora mira el valor de Request.method.

Request.add_header(key, val)

Add another header to the request. Headers are currently ignored by all handlers except HTTP handlers, where they are added to the list of headers sent to the server. Note that there cannot be more than one header with the same name, and later calls will overwrite previous calls in case the key collides. Currently, this is no loss of HTTP functionality, since all headers which have meaning when used more than once have a (header-specific) way of gaining the same functionality using only one header. Note that headers added using this method are also added to redirected requests.

Request.add_unredirected_header(key, header)

Añade un encabezado que no será añadido a una petición redireccionada.

Request.has_header(header)

Retorna si la instancia tiene el encabezado nombrado (comprueba tanto regular como no redirigido).

Request.remove_header(header)

Elimina el encabezado nombrado de la instancia de la petición (desde encabezados regulares y no redireccionados).

Nuevo en la versión 3.4.

Request.get_full_url()

Retorna la URL dada en el constructor.

Distinto en la versión 3.4.

Retorna Request.full_url

Request.set_proxy(host, type)

Prepara la petición conectando a un servidor proxy. Los host y type reemplazarán aquellos de la instancia y el selector de la instancia será la URL original dada en el constructor.

Request.get_header(header_name, default=None)

Retorna el valor del encabezado dado.

Request.header_items()

Retorna una lista de tuplas (header_name, header_value) de los encabezados de la Petición.

Distinto en la versión 3.4: Los métodos de petición add_data, has_data, get_data, get_type, get_host, get_selector, get_origin_req_host y is_unverifiable que quedaron obsoletos desde 3.3 han sido eliminados.

Objetos OpenerDirector

Las instancias de OpenerDirector tienen los siguientes métodos:

OpenerDirector.add_handler(handler)

handler debe ser una instancia de BaseHandler. Los siguientes métodos son buscados y añadidos a las cadenas posibles (tenga en cuenta que los errores HTTP son un caso espacial). Tenga en cuenta que, en los siguientes, protocol debe ser remplazado con el protocolo actual a manejar, por ejemplo http_response() sería el protocolo HTTP del manejador de respuesta. También type debe ser remplazado con el código HTTP actual, por ejemplo http_error_404() manejaría errores HTTP 404.

<protocol>_open() — señala que el manejador sabe como abrir URLs protocol.

Vea BaseHandler.<protocol>_open() para más información.

http_error_<type>() — señala que el manejador sabe como manejar errores HTTP con el código de error type.

Vea BaseHandler.http_error_<nnn>() para más información.

<protocol>_error() — señala que el manejador sabe como manejar errores de (no http) protocol.

<protocol>_request() — señala que el manejador sabe como preprocesar peticiones protocol.

Vea BaseHandler.<protocol>_request() para más información.

<protocol>_response() — señala que el manejador sabe como postprocesar respuestas protocol.

Vea BaseHandler.<protocol>_response() para más información.

OpenerDirector.open(url, data=None[, timeout])

Open the given url (which can be a request object or a string), optionally passing the given data. Arguments, return values and exceptions raised are the same as those of urlopen() (which simply calls the open() method on the currently installed global OpenerDirector). The optional timeout parameter specifies a timeout in seconds for blocking operations like the connection attempt (if not specified, the global default timeout setting will be used). The timeout feature actually works only for HTTP, HTTPS and FTP connections.

OpenerDirector.error(proto, *args)

Maneja un error del protocolo dado. Esto invocará los manejadores de error registrados para el protocolo dado con los argumentos dados (los cuales son específicos del protocolo). El protocolo HTTP es un caso especial el cual usa el código de respuesta HTTP para determinar el manejador de error específico; refiera a los métodos http_error_<type>() de las clases del manejador.

Retorna si los valores y excepciones generadas son las mismas que aquellas de urlopen().

Los objetos OpenerDirector abren URLs en tres etapas:

El orden en el cual esos métodos son invocados dentro de cada etapa es determinado ordenando las instancias manejadoras.

Cada manejador con un método nombrado como <protocol>_request() tiene ese método invocador para preprocesar la petición.

Los manejadores con un método nombrado como <protocol>_open() son invocados para manejar la petición. Esta etapa termina cuando un manejador retorna un valor no None (ej. una respuesta) o genera una excepción (generalmente URLError). Se permite que las excepciones propaguen.

De hecho, el algoritmo anterior se intenta primero para métodos nombrados default_open(). Si todos esos métodos retornan None, el algoritmo se repite para métodos nombrados como <protocol>_open(). Si todos esos métodos retornan None, el algoritmo se repite para métodos nombrados como unknown_open().

Tenga en cuenta que la implementación de esos métodos puede involucrar invocaciones de los métodos open() y error() de la instancia OpenerDirector padre.

Cada manejador con un método nombrado como <protocol>_response() tiene ese método invocado para postprocesar la respuesta.

Objetos BaseHandler

Los objetos BaseHandler proporcionan un par de métodos que son útiles directamente y otros que están destinados a ser utilizados por clases derivadas. Estos están pensados para uso directo:

BaseHandler.add_parent(director)

Añade un director como padre.

BaseHandler.close()

Elimina cualquier padre.

El siguiente atributo y los siguientes métodos sólo deben ser usados por clases derivadas de BaseHandler.

Nota

Se ha adoptado la convención de que las subclases que definen los métodos <protocol>_request() o <protocol>_response() son nombradas *Processor; todas las otras son nombradas *Handler.

BaseHandler.parent

Un OpenerDirector válido, el cual puede ser utilizado para abrir usando un protocolo diferente, o para manejar errores.

BaseHandler.default_open(req)

Este método no es definido en BaseHandler, pero las subclases deben definirlo si quieren cazar todas las URLs.

This method, if implemented, will be called by the parent OpenerDirector. It should return a file-like object as described in the return value of the open() method of OpenerDirector, or None. It should raise URLError, unless a truly exceptional thing happens (for example, MemoryError should not be mapped to URLError).

Este método será invocado antes de cualquier método de apertura específico de protocolo.

BaseHandler.<protocol>_open(req)

Este método no está definido en BaseHandler, pero las subclases deben definirlo si quieren manejar URLs con el protocolo dado.

Este método, si está definido, será invocado por el OpenerDirector padre. Los valores retornados deben ser los mismos que para default_open().

BaseHandler.unknown_open(req)

Este método no está definido en BaseHandler, pero las subclases deben definirlo si quieren cazar todas las URLs sin manejador registrado para abrirlo.

Este método, si está implementado, será invocado por el parent de OpenerDirector. Los valores retornados deben ser los mismos que para default_open().

BaseHandler.http_error_default(req, fp, code, msg, hdrs)

Este método no está definido en BaseHandler, pero las subclases deben sobreescribirlo si pretenden proporcionar una solución general para los errores HTTP que de otro modo no se manejarían. Sería invocado automáticamente por el OpenerDirector obteniendo el error y no debe ser invocado normalmente en otras circunstancias.

req será un objeto Request, fp será un objeto como archivo con el cuerpo de error HTTP, code será el código de error de tres dígitos, msg será la explicación visible para el usuario del código y hdrs será un objeto de mapeo con los encabezados del error.

Los valores de retorno y las excepciones generadas deben ser los mismos que aquellos de urlopen().

BaseHandler.http_error_<nnn>(req, fp, code, msg, hdrs)

nnn debe ser un código de error HTTP de tres dígitos. Este método tampoco está definido en BaseHandler, pero será invocado, si existe, en una instancia de una subclase, cuando ocurra un error HTTP con código nnn.

Las subclases deben sobrescribir este método para manejar errores HTTP específicos.

Los argumentos, valores de retorno y las excepciones generadas deben ser las mismas que para http_error_default().

BaseHandler.<protocol>_request(req)

Este método no está definido en BaseHandler, pero las subclases deben definirlo si pretenden preprocesar peticiones del protocolo dado.

Este método, si está definido, será invocado por el OpenerDirector padre. req será un objeto Request. El valor retornado debe ser un objeto Request.

BaseHandler.<protocol>_response(req, response)

Este método no está definido en BaseHandler, pero las subclases deben definirlo si quieren postprocesar respuestas del protocolo dado.

Este método, si está definido, será invocado por el OpenerDirector padre. req será un objeto Request. response será un objeto que implementa la misma interfaz que el valor retornado de urlopen(). El valor retornado debe implementar la misma interfaz que el valor retornado de urlopen().

Objetos HTTPRedirectHandler

Nota

Algunas redirecciones HTTP requieren acción desde el código del módulo del cliente. Si este es el caso, se genera HTTPError. Vea RFC 2616 [https://tools.ietf.org/html/rfc2616.html] para más detalles de los significados precisos de los diferentes códigos de redirección.

Una excepción HTTPError generada como consideración de seguridad si el HTTPRedirectHandler se presenta con una URL redirigida la cual no es una URL HTTP, HTTPS o FTP.

HTTPRedirectHandler.redirect_request(req, fp, code, msg, hdrs, newurl)

Retorna un Request o None en respuesta a una redirección. Esto es invocado por las implementaciones predeterminadas de los métodos http_error_30*() cuando se recibe una redirección del servidor. Si puede tomar lugar una redirección, retorna un nuevo Request para permitir a http_error_30*() realizar la redirección a newurl. De otra forma, genera HTTPError si ningún otro manejador debe intentar manejar esta URL, o retorna None si no tú pero otro manejador puede.

Nota

La implementación predeterminada de este método no sigue estrictamente RFC 2616 [https://tools.ietf.org/html/rfc2616.html], la cual dice que las respuestas 301 y 302 a peticiones POST no deben ser redirigidas automáticamente sin confirmación por el usuario. En realidad, los navegadores permiten redirección automática de esas respuestas, cambiando el POST a un GET y la implementación predeterminada reproduce este comportamiento.

HTTPRedirectHandler.http_error_301(req, fp, code, msg, hdrs)

Redirecciona a la URL Location: o URI:. Este método es invocado por el OpenerDirector padre al obtener una respuesta HTTP “moved permanently”.

HTTPRedirectHandler.http_error_302(req, fp, code, msg, hdrs)

Lo mismo que http_error_301(), pero invocado para la respuesta “found”.

HTTPRedirectHandler.http_error_303(req, fp, code, msg, hdrs)

Lo mismo que http_error_301(), pero invocado para la respuesta “see other”.

HTTPRedirectHandler.http_error_307(req, fp, code, msg, hdrs)

Lo mismo que http_error_301(), pero invocado para la respuesta “temporary redirect”.

Objetos HTTPCookieProcessor

Las instancias HTTPCookieProcessor tienen un atributo:

HTTPCookieProcessor.cookiejar

El http.cookiejar.CookieJar en el cual las cookies están almacenadas.

Objetos ProxyHandler

ProxyHandler.<protocol>_open(request)

El ProxyHandler tendrá un método <protocol>_open() para cada protocol el cual tiene un proxy en el diccionario proxies dado en el constructor. El método modificará peticiones para ir a través del proxy, invocando request.set_proxy(), e invoca el siguiente manejador en la cadena que ejecuta actualmente el protocolo.

Objetos HTTPPasswordMgr

Estos métodos están disponibles en los objetos HTTPPasswordMgr y HTTPPasswordMgrWithDefaultRealm.

HTTPPasswordMgr.add_password(realm, uri, user, passwd)

uri puede ser una única URI o una secuencia de URIs. realm, user y passwd deben ser cadenas. Esto causa que (user, passwd) se utilice como tokens de autenticación cuando la autenticación para realm y para una super URI de ninguna de las URIs dadas es provista.

HTTPPasswordMgr.find_user_password(realm, authuri)

Obtener usuario/contraseña para el reino y URI dados, si alguno ha sido dado. Este método retornará (None, None) si no hay usuario/contraseña concordante.

Para objetos HTTPPasswordMgrWithDefaultRealm, el reino None será buscado si el realm dado no tiene usuario/contraseña concordante.

Objetos HTTPPasswordMgrWithPriorAuth

Esta manejador de contraseña extiende HTTPPasswordMgrWithDefaultRealm para soportar el seguimiento de URIs para las cuales deben ser enviadas siempre credenciales de autenticación.

HTTPPasswordMgrWithPriorAuth.add_password(realm, uri, user, passwd, is_authenticated=False)

realm, uri, user, passwd son como para HTTPPasswordMgr.add_password(). is_authenticated establece el valor inicial del indicador is_authenticated para la URI o lista de URIs dadas. Si se especifica is_authenticated como True, realm se ignora.

HTTPPasswordMgrWithPriorAuth.find_user_password(realm, authuri)

Lo mismo que para objetos HTTPPasswordMgrWithDefaultRealm

HTTPPasswordMgrWithPriorAuth.update_authenticated(self, uri, is_authenticated=False)

Actualiza el indicador is_authenticated para la uri o lista de URIs dadas.

HTTPPasswordMgrWithPriorAuth.is_authenticated(self, authuri)

Retorna el estado actual del indicador is_authenticated para la URI dada.

Objetos AbstractBasicAuthHandler

AbstractBasicAuthHandler.http_error_auth_reqed(authreq, host, req, headers)

Maneja una autenticación de petición obteniendo un par usuario/contraseña y reintentando la petición. authreq debe ser el nombre del encabezado donde la información sobre el reino se incluye en la petición, host especifica la URL y ruta para la cual autenticar, req debe ser el objeto Request (fallido) y headers deben ser los encabezados de error.

host es una autoridad (ej. "python.org") o una URL conteniendo un componente de autoridad (ej. "http://python.org/"). En cualquier caso, la autoridad no debe contener un componente userinfo (por lo que "python.org" y "python.org:80" están bien, "joe:password@python.org" no).

Objetos HTTPBasicAuthHandler

HTTPBasicAuthHandler.http_error_401(req, fp, code, msg, hdrs)

Reintenta la petición con la información de autenticación, si está disponible.

Objetos ProxyBasicAuthHandler

ProxyBasicAuthHandler.http_error_407(req, fp, code, msg, hdrs)

Reintenta la petición con la información de autenticación, si está disponible.

Objetos AbstractDigestAuthHandler

AbstractDigestAuthHandler.http_error_auth_reqed(authreq, host, req, headers)

authreq debe ser el nombre del encabezado donde la información sobre el reino está incluida en la petición, host debe ser el host al que autenticar, req debe ser el objeto Request (fallido) y headers deben ser los encabezados de error.

Objetos HTTPDigestAuthHandler

HTTPDigestAuthHandler.http_error_401(req, fp, code, msg, hdrs)

Reintenta la petición con la información de autenticación, si está disponible.

Objetos ProxyDigestAuthHandler

ProxyDigestAuthHandler.http_error_407(req, fp, code, msg, hdrs)

Reintenta la petición con la información de autenticación, si está disponible.

Objetos HTTPHandler

HTTPHandler.http_open(req)

Envía una petición HTTP, que puede ser GET o POST, dependiendo de req.has_data().

Objetos HTTPSHandler

HTTPSHandler.https_open(req)

Envía una petición HTTPS, que puede ser GET o POST, dependiendo de req.has_data().

Objetos FileHandler

FileHandler.file_open(req)

Abre el archivo localmente, si no hay nombre de host, o el nombre de host es 'localhost'.

Distinto en la versión 3.2: Este método es aplicable sólo para nombres de host locales. Cuando un nombre de host remoto es dado, se genera una excepción URLError.

Objetos DataHandler

DataHandler.data_open(req)

Lee una URL de datos. Este tipo de URL contiene el contenido codificado en la URL misma. La sintaxis de la URL de datos se especifica en RFC 2397 [https://tools.ietf.org/html/rfc2397.html]. Esta implementación ignora los espacios en blanco en datos codificados como base64 así que la URL puede ser envuelta en cualquier archivo fuente del que proviene. Pero a pesar de que a algunos navegadores no les importa si falta relleno al final de una URL codificada como base64, esta implementación generará un ValueError en este caso.

Objetos FTPHandler

FTPHandler.ftp_open(req)

Abre el archivo FTP indicado por req. El inicio de sesión siempre se realiza con un usuario y contraseña vacíos.

Objetos CacheFTPHandler

Los objetos CacheFTPHandler son objetos FTPHandler con los siguientes métodos adicionales:

CacheFTPHandler.setTimeout(t)

Establece el tiempo de expiración de conexiones a t segundos.

CacheFTPHandler.setMaxConns(m)

Establece el número máximo de conexiones cacheadas a m.

Objetos UnknownHandler

UnknownHandler.unknown_open()

Genera una excepción URLError.

Objetos HTTPErrorProcessor

HTTPErrorProcessor.http_response(request, response)

Procesa errores de respuestas HTTP.

Para códigos de error que no están en el rango de los 200, el objeto de respuesta es retornado inmediatamente.

Para códigos de error que no están en el rango de los 200, esto simplemente pasa el trabajo a los métodos del manejador http_error_<type>(), mediante OpenerDirector.error(). Eventualmente, HTTPDefaultErrorHandler generará un HTTPError si ningún otro manejador maneja el error.

HTTPErrorProcessor.https_response(request, response)

Procesa los errores HTTPS de las respuestas.

Este comportamiento es el mismo que http_response().

Ejemplos

Adicionalmente a los ejemplos siguientes, se dan más ejemplos en HOWTO - Cómo obtener recursos de Internet con el paquete urllib.

Este ejemplo obtiene la página principal python.org y despliega los primeros 300 bytes de ella.

>>> import urllib.request
>>> with urllib.request.urlopen('http://www.python.org/') as f:
...     print(f.read(300))
...
b'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">\n\n\n<html
xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">\n\n<head>\n
<meta http-equiv="content-type" content="text/html; charset=utf-8" />\n
<title>Python Programming '

Tenga en cuenta que urlopen retorna un objeto de bytes. Esto es porque no hay forma para urlopen de determinar automáticamente la codificación del flujo de bytes que recibe del servidor HTTP. En general, un programa decodificará el objeto de bytes retornado a cadena de caracteres una vez que determine o adivine la codificación apropiada.

El siguiente documento W3C, https://www.w3.org/International/O-charset, lista las diferentes formas en la cual un documento (X)HTML o XML podría haber especificado su información de codificación.

Ya que el sitio web python.org usa codificación utf-8 tal y como se especifica en su etiqueta meta, usaremos la misma para decodificar el objeto de bytes.

>>> with urllib.request.urlopen('http://www.python.org/') as f:
...     print(f.read(100).decode('utf-8'))
...
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtm

Es posible conseguir el mismo resultado sin usar la aproximación context manager.

>>> import urllib.request
>>> f = urllib.request.urlopen('http://www.python.org/')
>>> print(f.read(100).decode('utf-8'))
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtm

En el siguiente ejemplo, estamos enviando un flujo de datos a la entrada estándar de un CGI y leyendo los datos que nos retorna. Tenga en cuenta que este ejemplo sólo funcionará cuando la instalación de Python soporte SSL.

>>> import urllib.request
>>> req = urllib.request.Request(url='https://localhost/cgi-bin/test.cgi',
...                       data=b'This data is passed to stdin of the CGI')
>>> with urllib.request.urlopen(req) as f:
...     print(f.read().decode('utf-8'))
...
Got Data: "This data is passed to stdin of the CGI"

El código para el CGI de muestra usado en el ejemplo anterior es:

#!/usr/bin/env python
import sys
data = sys.stdin.read()
print('Content-type: text/plain\n\nGot Data: "%s"' % data)

Aquí hay un ejemplo de realizar una petición PUT usando Request:

import urllib.request
DATA = b'some data'
req = urllib.request.Request(url='http://localhost:8080', data=DATA,method='PUT')
with urllib.request.urlopen(req) as f:
    pass
print(f.status)
print(f.reason)

Uso de Autenticación HTTP Básica:

import urllib.request
# Create an OpenerDirector with support for Basic HTTP Authentication...
auth_handler = urllib.request.HTTPBasicAuthHandler()
auth_handler.add_password(realm='PDQ Application',
                          uri='https://mahler:8092/site-updates.py',
                          user='klem',
                          passwd='kadidd!ehopper')
opener = urllib.request.build_opener(auth_handler)
# ...and install it globally so it can be used with urlopen.
urllib.request.install_opener(opener)
urllib.request.urlopen('http://www.example.com/login.html')

build_opener() proporciona muchos manejadores por defecto, incluyendo un ProxyHandler. De forma predeterminada, ProxyHandler usa las variables de entorno llamadas <scheme>_proxy, donde <scheme> es el esquema URL involucrado. Por ejemplo, se lee la variable de entorno http_proxy para obtener la URL del proxy HTTP.

Este ejemplo reemplaza el ProxyHandler predeterminado por uno que usa URLs de proxy suministradas mediante programación y añade soporte de autorización de proxy con ProxyBasicAuthHandler.

proxy_handler = urllib.request.ProxyHandler({'http': 'http://www.example.com:3128/'})
proxy_auth_handler = urllib.request.ProxyBasicAuthHandler()
proxy_auth_handler.add_password('realm', 'host', 'username', 'password')

opener = urllib.request.build_opener(proxy_handler, proxy_auth_handler)
# This time, rather than install the OpenerDirector, we use it directly:
opener.open('http://www.example.com/login.html')

Añadiendo encabezados HTTP:

Usa el argumento headers en el constructor de Request, o:

import urllib.request
req = urllib.request.Request('http://www.example.com/')
req.add_header('Referer', 'http://www.python.org/')
# Customize the default User-Agent header value:
req.add_header('User-Agent', 'urllib-example/0.1 (Contact: . . .)')
r = urllib.request.urlopen(req)

OpenerDirector añade automáticamente un encabezado User-Agent a cada Request. Para cambiar esto:

import urllib.request
opener = urllib.request.build_opener()
opener.addheaders = [('User-agent', 'Mozilla/5.0')]
opener.open('http://www.example.com/')

También, recuerda que algunos encabezados estándar (Content-Length, Content-Type y Host) son añadidos cuando se pasa Request a urlopen() (o OpenerDirector.open()).

Aquí hay un ejemplo de sesión que usa el método GET para obtener una URL que contiene los parámetros:

>>> import urllib.request
>>> import urllib.parse
>>> params = urllib.parse.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
>>> url = "http://www.musi-cal.com/cgi-bin/query?%s" % params
>>> with urllib.request.urlopen(url) as f:
...     print(f.read().decode('utf-8'))
...

El siguiente ejemplo usa el método POST en su lugar. Tenga en cuenta que la salida de parámetros desde urlencode es codificada a bytes antes de ser enviados a urlopen como datos:

>>> import urllib.request
>>> import urllib.parse
>>> data = urllib.parse.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
>>> data = data.encode('ascii')
>>> with urllib.request.urlopen("http://requestb.in/xrbl82xr", data) as f:
...     print(f.read().decode('utf-8'))
...

El siguiente ejemplo usa un proxy HTTP especificado, sobrescribiendo las configuraciones de entorno:

>>> import urllib.request
>>> proxies = {'http': 'http://proxy.example.com:8080/'}
>>> opener = urllib.request.FancyURLopener(proxies)
>>> with opener.open("http://www.python.org") as f:
...     f.read().decode('utf-8')
...

El siguiente ejemplo no usa proxies, sobrescribiendo las variables de entorno:

>>> import urllib.request
>>> opener = urllib.request.FancyURLopener({})
>>> with opener.open("http://www.python.org/") as f:
...     f.read().decode('utf-8')
...

Interfaz heredada

Las siguientes funciones y clases están portadas desde el módulo urllib de Python 2 (en oposición a urllib2). Ellas pueden estar obsoletas en algún punto del futuro.

urllib.request.urlretrieve(url, filename=None, reporthook=None, data=None)

Copia un objeto de red denotado por una URL a un archivo local. Si la URL apunta a un archivo local, el objeto no será copiado a no ser que sea suministrado un nombre de archivo. Retorna una tupla (filename, headers) donde filename es el nombre de archivo local bajo el cual el objeto puede ser encontrado y headers es lo que retorna el método info() retornado por urlopen() (para un objeto remoto). Las excepciones son las mismas que para urlopen().

El segundo argumento, si está presente, especifica la localización a la que será copiada el objeto (si está ausente, la localización será un archivo temporal con un nombre generado). El tercer argumento, si está presente, es un objeto invocable que será invocado una vez que se establezca la conexión de red y después de eso una vez después de cada lectura de bloque. Al invocable se le pasarán tres argumentos; una cuenta de los bloques transferidos hasta el momento, un tamaño de bloque en bytes y el tamaño total del archivo. El tercer argumento puede ser -1 en servidores FTP antiguos los cuales no retornan un tamaño de archivo en respuesta a una solicitud de recuperación.

El siguiente ejemplo ilustra el escenario de uso más común:

>>> import urllib.request
>>> local_filename, headers = urllib.request.urlretrieve('http://python.org/')
>>> html = open(local_filename)
>>> html.close()

Si la url usa el esquema de identificador http:, el argumento opcional data puede ser dado para especificar una petición POST (normalmente el tipo de petición es GET). El argumento data debe ser un objeto de bytes en formato application/x-www-form-urlencoded; vea la función urllib.parse.urlencode().

urlretrieve() generará ContentTooShortError cuando detecte que la cantidad de datos disponibles sea menor que la cantidad esperada (la cual es el tamaño reportado por un encabezado Content-Length). Esto puede ocurrir, por ejemplo, cuando se interrumpe la descarga.

El Content-Length es tratado como un límite inferior: si no hay más datos a leer, urlretrieve lee más datos, pero si están disponibles menos datos, se genera la excepción.

Puedes seguir obteniendo los datos descargados en este caso, son almacenados en el atributo content de la instancia de la excepción.

Si no fue proporcionado el encabezado Content-Length, urlretrieve no puede comprobar el tamaño de los datos que han sido descargados, y sólo los retorna. En este caso sólo tienes que asumir que la descarga fue exitosa.

urllib.request.urlcleanup()

Limpia archivos temporales que pueden haber quedado tras llamadas anteriores a urlretrieve().

class urllib.request.URLopener(proxies=None, **x509)

Obsoleto desde la versión 3.3.

Clase base para apertura y lectura de URLs. A no ser que necesites soporte de apertura de objetos usando esquemas diferentes a http:, ftp: o file:, probablemente quieras usar FancyURLopener.

Por defecto, la clase URLopener envía un encabezado User-Agent de urllib/VVV, donde VVV es el número de versión urllib. Las aplicaciones pueden definir su propio encabezado User-Agent heredando de URLopener o FancyURLopener y estableciendo el atributo de clase version a un valor de cadena de caracteres apropiado en la definición de la subclase.

El parámetro opcional proxies debe ser un diccionario mapeando nombres de esquemas a URLs de proxy, donde un diccionario vacío apaga los proxies completamente. Su valor predeterminado es None, en cuyo caso las configuraciones de proxy del entorno serán usadas si están presentes, como ha sido discutido en la definición de urlopen(), arriba.

Parámetros adicionales de palabra clave, recogidos en x509, pueden ser usados por autenticación del cliente cuando usan el esquema https:. Las palabras claves key_file y cert_file están soportadas para proveer una clave y certificado SSL; ambos son necesarias para soportar autenticación de cliente.

Los objetos URLopener generarán una excepción OSError si el servidor retorna un código de error.

open(fullurl, data=None)

Abre fullurl usando el protocolo apropiado. Este método configura la información de caché e información de proxy, entonces invoca el método apropiado con sus argumentos de entrada. Si el esquema no está reconocido, se invoca open_unknown(). El argumento data tiene el mismo significado que el argumento data de urlopen().

Este método siempre entrecomilla fullurl usando quote().

open_unknown(fullurl, data=None)

Interfaz sobrescribible para abrir tipos de URL desconocidos.

retrieve(url, filename=None, reporthook=None, data=None)

Obtiene el contenido de url y lo coloca en filename. El valor retornado es una tupla que consiste de un nombre de archivo local y un objeto email.message.Message conteniendo los encabezados de respuesta (para URLs remotas) o None (para URLs locales). El invocador debe entonces abrir y leer los contenidos de filename. Si filename no está dado y la URL refiere a un archivo local, se retorna el nombre de archivo de entrada. Si la URL no es local y no se da filename, el nombre de archivo es la salida de la función tempfile.mktemp() con un sufijo que concuerda con el sufijo del último componente de la ruta de la URL de entrada. Si se da reporthook, debe ser una función que acepte tres parámetros numéricos: Un número de fragmento, se leen los fragmentos de tamaño máximo y el tamaño total de la descarga (-1 si es desconocida). Será invocada una vez al comienzo y después de que cada fragmento de datos sea leído de la red. reporthook es ignorado para URLs locales.

Si la url usa el identificador de esquema http:, el argumento opcional data puede ser dado para especificar una petición POST (normalmente el tipo de petición es GET). El argumento data debe estar en formato estándar application/x-www-form-urlencoded; vea la función urllib.parse.urlencode().

version

Variable que especifica el agente de usuario del objeto abridor. Para obtener urllib para decir a los servidores que es un agente de usuario particular, establece esto en una subclase como una variable de clase o en el constructor antes de invocar el constructor base.

class urllib.request.FancyURLopener(...)

Obsoleto desde la versión 3.3.

FancyURLopener hereda de URLopener proveyendo manejo predeterminado para los siguientes códigos de respuesta HTTP: 301, 302, 303, 307 y 401. Para los códigos de respuesta 30x listados anteriormente, se usa el encabezado Location para obtener la URL actual. Para códigos de respuesta 401 (autenticación requerida), se realiza autenticación HTTP. Para los códigos de respuesta 30x, la recursión está limitada por el valor del atributo maxentries, el cual por defecto es 10.

Para todos los demás códigos de respuesta, se invoca al método http_error_default(), que puede sobrescribir en subclases para manejar el error de manera adecuada.

Nota

De acuerdo a la carta de RFC 2616 [https://tools.ietf.org/html/rfc2616.html], las respuestas a las peticiones POST 301 y 302 no debe ser redireccionadas automáticamente sin confirmación por el usuario. En realidad, los navegadores permiten redirección automática de esas respuestas, cambiando de POST a GET, y urllib reproduce este comportamiento.

Los parámetros del constructor son el mismo que aquellos para URLopener.

Nota

Cuando se realiza autenticación básica, una instancia FancyURLopener invoca a su método prompt_user_passwd(). La implementación predeterminada pregunta a los usuarios la información requerida en la terminal de control. Una subclase puede sobrescribir este método para soportar un comportamiento más apropiado si se necesita.

La clase FancyURLopener ofrece un método adicional que debe ser sobrecargado para proveer el comportamiento apropiado:

prompt_user_passwd(host, realm)

Retorna la información necesaria para autenticar el usuario en el host dado en el reino de seguridad especificado. El valor retornado debe ser una tupla (user, password), la cual puede ser usada para autenticación básica.

La implementación solicita esta información en el terminal; una aplicación debe sobrescribir este método para usar un modelo de interacción apropiado en el entorno local.

Restricciones urllib.request

Actualmente, sólo uno de los siguientes protocolo están soportados: HTTP (versiones 0.9 y 1.0), FTP, archivos locales y URLs de datos.

Distinto en la versión 3.4: Añadido soporte para URLs de datos.

La característica de caché de urlretrieve() ha sido deshabilitada hasta que alguien encuentre el tiempo para hackear el procesamiento adecuado de los encabezados de tiempo de Expiración.

Debería haber una función para consultar si una URL en particular está en la caché.

Para compatibilidad con versiones anteriores, si una URL parece apuntar a un archivo local pero el archivo no puede ser abierto, la URL es reinterpretada usando el protocolo FTP. Esto a veces puede causar mensajes de error confusos.

Las funciones urlopen() y urlretrieve() pueden causar retrasos arbitrariamente largos mientras esperan a que se configure una conexión de red. Esto significa que es difícil construir un cliente Web interactivo usando estas funciones sin utilizar hilos.

Los datos retornados por urlopen() o urlretrieve() son los datos en crudo retornados por el servidor. Estos pueden ser datos binarios (como una imagen), texto plano o (por ejemplo) HTML. El protocolo HTTP provee información de tipo en el encabezado de respuesta, el cual puede ser inspeccionado mirando el encabezado Content-Type. Si los datos retornados son HTML, puedes usar el módulo html.parser para analizarlos.

El código que maneja el protocolo FTP no puede diferenciar entre un archivo y un directorio. Esto puede llevar a un comportamiento inesperado cuando se intenta leer una URL que apunta a un archivo que no es accesible. Si la URL termina en un /, se asume que se refiere a un directorio y será manejada acordemente. Pero si un intento de leer un archivo lleva a un error 550 (lo que significa que la URL no puede ser encontrada o no es accesible, a menudo por razones de permisos), entonces se trata la ruta como un directorio para manejar el caso cuando un directorio es especificado por una URL pero el / trasero ha sido dejado fuera. Esto puede causar resultados erróneos cuando intenta obtener un archivo cuyos permisos de lectura lo hacen inaccesible; el código FTP intentará leerlo, fallará con un error 550 y entonces realizará un listado de directorio para el archivo ilegible. Si se necesita un control más detallado, considere usar el módulo ftplib, heredando FancyURLopener o cambiando _urlopener para ajustarlo a tus necesidades.

urllib.response — Clases de respuesta usadas por urllib

El módulo urllib.response define funciones y clases que definen una interfaz mínima file-like, incluyendo read() y readline(). Las funciones definidas en este módulo son usadas internamente por el módulo urllib.request. El objeto de respuesta típico es una instancia de urllib.response.addinfourl:

class urllib.response.addinfourl

url

:URL del recurso obtenido, comúnmente usado para determinar si se ha seguido una redirección.

headers

Retorna las cabeceras de la respuesta en la forma de una instancia de EmailMessage.

status

Nuevo en la versión 3.9.

Código de estado retornado por el servidor.

geturl()

Obsoleto desde la versión 3.9: Obsoleto en favor de url.

info()

Obsoleto desde la versión 3.9: Obsoleto en favor de headers.

code

Obsoleto desde la versión 3.9: Obsoleto en favor de status.

getstatus()

Obsoleto desde la versión 3.9: Obsoleto en favor de status.

urllib.parse — Analiza URL en componentes

Código fuente: Lib/urllib/parse.py [https://github.com/python/cpython/tree/3.9/Lib/urllib/parse.py]

Este modulo define una interfaz estándar para separar cadenas de texto del Localizador de recursos uniforme (más conocido por las siglas URL, del inglés Uniform Resource Locator) en componentes (esquema de dirección, ubicación de red, ruta de acceso, etc.), para poder combinar los componentes nuevamente en una cadena de texto URL, y convertir una «URL relativa» a una URL absoluta a partir de una «URL base».

Este módulo ha sido diseñado para coincidir con el estándar de Internet RFC de los Localizadores de recursos uniformes relativos. Este modulo soporta los siguientes esquemas URL: file, ftp, gopher, hdl, http, https, imap, mailto, mms, news, nntp, prospero, rsync, rtsp, rtspu, sftp, shttp, sip, sips, snews, svn, svn+ssh, telnet, wais, ws, wss.

El módulo urllib.parse define funciones que se dividen en dos categorías amplias: análisis de URL y cita de URL. Estos se tratan en detalle en las secciones siguientes.

Análisis de URL

Las funciones de análisis de url se centran en dividir una cadena de dirección URL en sus componentes o en combinar componentes de dirección URL en una cadena de dirección URL.

urllib.parse.urlparse(urlstring, scheme='', allow_fragments=True)

Analiza una dirección URL en seis componentes, retornando una tupla nombrada de 6 elementos. Esto corresponde a la estructura general de una URL: scheme://netloc/path;parameters?query#fragment. Cada elemento de la tupla es una cadena, posiblemente vacía. Los componentes no se dividen en piezas más pequeñas (por ejemplo, la ubicación de red es una sola cadena) y los caracteres % de escape no se expanden. Los delimitadores como se muestra anteriormente no forman parte del resultado, excepto una barra diagonal inicial en el componente path, que se conserva si está presente. Por ejemplo:

>>> from urllib.parse import urlparse
>>> urlparse("scheme://netloc/path;parameters?query#fragment")
ParseResult(scheme='scheme', netloc='netloc', path='/path;parameters', params='',
            query='query', fragment='fragment')
>>> o = urlparse("http://docs.python.org:80/3/library/urllib.parse.html?"
...              "highlight=params#url-parsing")
>>> o
ParseResult(scheme='http', netloc='docs.python.org:80',
            path='/3/library/urllib.parse.html', params='',
            query='highlight=params', fragment='url-parsing')
>>> o.scheme
'http'
>>> o.netloc
'docs.python.org:80'
>>> o.hostname
'docs.python.org'
>>> o.port
80
>>> o._replace(fragment="").geturl()
'http://docs.python.org:80/3/library/urllib.parse.html?highlight=params'

Siguiendo las especificaciones de sintaxis en RFC 1808 [https://tools.ietf.org/html/rfc1808.html], urlparse reconoce un netloc sólo si es introducido correctamente por “//”. De lo contrario, se supone que la entrada es una dirección URL relativa y, por lo tanto, comienza con un componente de ruta de acceso.

>>> from urllib.parse import urlparse
>>> urlparse('//www.cwi.nl:80/%7Eguido/Python.html')
ParseResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            params='', query='', fragment='')
>>> urlparse('www.cwi.nl/%7Eguido/Python.html')
ParseResult(scheme='', netloc='', path='www.cwi.nl/%7Eguido/Python.html',
            params='', query='', fragment='')
>>> urlparse('help/Python.html')
ParseResult(scheme='', netloc='', path='help/Python.html', params='',
            query='', fragment='')

El argumento scheme proporciona el esquema de direccionamiento predeterminado, que solo se utilizará si la dirección URL no especifica uno. Debe ser del mismo tipo (texto o bytes) que urlstring, excepto que el valor predeterminado '' siempre está permitido, y se convierte automáticamente a b'' si aplica.

Si el argumento allow_fragments es falso, los identificadores de fragmento no son reconocidos. Sino que, son analizados como parte de la ruta, parámetros o componentes de la consulta y el fragment es configurado como una cadena vacía en el valor retornado.

El valor retornado es un named tuple, lo que significa que se puede tener acceso a sus elementos por índice o como atributos con nombre, que son:

Atributo

Índice

Valor

Valor si no está presente

scheme

0

Especificador de esquema de URL

parámetro scheme

netloc

1

Parte de ubicación de red

cadena vacía

path

2

Hierarchical path

cadena vacía

params

3

Parámetros para el último elemento de ruta de acceso

cadena vacía

query

4

Componente de consulta

cadena vacía

fragment

5

Identificador de fragmento

cadena vacía

username

Nombre de usuario

None

password

Contraseña

None

hostname

Nombre de host (minúsculas)

None

port

Número de puerto como entero, si está presente

None

La lectura del atributo port generará un ValueError si se especifica un puerto no válido en la dirección URL. Consulte la sección Resultados del análisis estructurado para obtener más información sobre el objeto de resultado.

Los corchetes no coincidentes en el atributo netloc generarán un ValueError.

Los caracteres del atributo netloc que se descomponen en la normalización de NFKC (según lo utilizado por la codificación IDNA) en cualquiera de /, ?, #, @ o : lanzará un ValueError. Si la dirección URL se descompone antes del análisis, no se producirá ningún error.

Como es el caso con todas las tuplas con nombre, la subclase tiene algunos métodos y atributos adicionales que son particularmente útiles. Uno de estos métodos es _replace(). El método _replace() retornará un nuevo objeto ParseResult reemplazando los campos especificados por nuevos valores.

>>> from urllib.parse import urlparse
>>> u = urlparse('//www.cwi.nl:80/%7Eguido/Python.html')
>>> u
ParseResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            params='', query='', fragment='')
>>> u._replace(scheme='http')
ParseResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            params='', query='', fragment='')

Advertencia

urlparse() does not perform validation. See URL parsing security for details.

Distinto en la versión 3.2: Se han añadido capacidades de análisis de URL IPv6.

Distinto en la versión 3.3: El fragmento ahora se analiza para todos los esquemas de URL (a menos que allow_fragment sea falso), de acuerdo con RFC 3986 [https://tools.ietf.org/html/rfc3986.html]. Anteriormente, existía una lista blanca de esquemas que admiten fragmentos.

Distinto en la versión 3.6: Los números de puerto fuera de rango ahora generan ValueError, en lugar de retornar None.

Distinto en la versión 3.8: Los caracteres que afectan al análisis de netloc en la normalización de NFKC ahora generarán ValueError.

urllib.parse.parse_qs(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None, separator='&')

Analizar una cadena de consulta proporcionada como argumento de cadena (datos de tipo application/x-www-form-urlencoded). Los datos se retornan como un diccionario. Las claves de diccionario son los nombres de variable de consulta únicos y los valores son listas de valores para cada nombre.

El argumento opcional keep_blank_values es un indicador que indica si los valores en blanco de las consultas codificadas por porcentaje deben tratarse como cadenas en blanco. Un valor verdadero indica que los espacios en blanco deben conservarse como cadenas en blanco. El valor falso predeterminado indica que los valores en blanco deben omitirse y tratarse como si no se hubieran incluido.

El argumento opcional strict_parsing es una marca que indica qué hacer con los errores de análisis. Si es falso (valor predeterminado), los errores se omiten silenciosamente. Si es verdadero, los errores generan una excepción ValueError.

Los parámetros opcionales encoding y errors especifican cómo descodificar secuencias codificadas porcentualmente en caracteres Unicode, tal como lo acepta el método bytes.decode().

El argumento opcional max_num_fields es el número máximo de campos que se van a leer. Si se establece, se produce un ValueError si hay más de max_num_fields campos leídos.

El argumento opcional separator es el símbolo que se usa para separar los argumentos de la cadena de consulta. El valor por defecto es &.

Utilice la función urllib.parse.urlencode() (con el parámetro doseq establecido en True) para convertir dichos diccionarios en cadenas de consulta.

Distinto en la versión 3.2: Agregue los parámetros encoding y errors.

Distinto en la versión 3.8: Añadido parámetro max_num_fields.

Distinto en la versión 3.9.2: Añadido parámetro separator con un valor por defecto de &. Versiones de Python anterior a Python 3.9.2 permitían el uso de ; y & como separadores de la cadena de consulta. Esto ha sido cambiado para aceptar sólo una llave separadora, siendo & en separador por defecto.

urllib.parse.parse_qsl(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None, separator='&')

Analizar una cadena de consulta proporcionada como argumento de cadena (datos de tipo application/x-www-form-urlencoded). Los datos se retornan como una lista de pares de nombre y valor.

El argumento opcional keep_blank_values es un indicador que indica si los valores en blanco de las consultas codificadas por porcentaje deben tratarse como cadenas en blanco. Un valor verdadero indica que los espacios en blanco deben conservarse como cadenas en blanco. El valor falso predeterminado indica que los valores en blanco deben omitirse y tratarse como si no se hubieran incluido.

El argumento opcional strict_parsing es una marca que indica qué hacer con los errores de análisis. Si es falso (valor predeterminado), los errores se omiten silenciosamente. Si es verdadero, los errores generan una excepción ValueError.

Los parámetros opcionales encoding y errors especifican cómo descodificar secuencias codificadas porcentualmente en caracteres Unicode, tal como lo acepta el método bytes.decode().

El argumento opcional max_num_fields es el número máximo de campos que se van a leer. Si se establece, se produce un ValueError si hay más de max_num_fields campos leídos.

El argumento opcional separator es el símbolo que se usa para separar los argumentos de la cadena de consulta. El valor por defecto es &.

Utilice la función urllib.parse.urlencode() para convertir dichas listas de pares en cadenas de consulta.

Distinto en la versión 3.2: Agregue los parámetros encoding y errors.

Distinto en la versión 3.8: Añadido parámetro max_num_fields.

Distinto en la versión 3.9.2: Añadido parámetro separator con un valor por defecto de &. Versiones de Python anterior a Python 3.9.2 permitían el uso de ; y & como separadores de la cadena de consulta. Esto ha sido cambiado para aceptar sólo una llave separadora, siendo & en separador por defecto.

urllib.parse.urlunparse(parts)

Construir una URL a partir de una tupla retornada por urlparse(). El argumento parts puede ser iterable de seis elementos. Esto puede dar lugar a una dirección URL ligeramente diferente, pero equivalente, si la dirección URL que se analizó originalmente tenía delimitadores innecesarios (por ejemplo, un ? con una consulta vacía; la RFC indica que son equivalentes).

urllib.parse.urlsplit(urlstring, scheme='', allow_fragments=True)

Esto es similar a urlparse(), pero no divide los parámetros de la dirección URL. Esto se debe utilizar generalmente en lugar de urlparse() si se desea la sintaxis de URL más reciente que permite aplicar parámetros a cada segmento de la parte path de la dirección URL (consulte RFC 2396 [https://tools.ietf.org/html/rfc2396.html]). Se necesita una función independiente para separar los segmentos y parámetros de ruta. Esta función retorna un 5-item named tuple:

(addressing scheme, network location, path, query, fragment identifier).

El valor retornado es un named tuple, se puede acceder a sus elementos por índice o como atributos con nombre:

Atributo

Índice

Valor

Valor si no está presente

scheme

0

Especificador de esquema de URL

parámetro scheme

netloc

1

Parte de ubicación de red

cadena vacía

path

2

Hierarchical path

cadena vacía

query

3

Componente de consulta

cadena vacía

fragment

4

Identificador de fragmento

cadena vacía

username

Nombre de usuario

None

password

Contraseña

None

hostname

Nombre de host (minúsculas)

None

port

Número de puerto como entero, si está presente

None

La lectura del atributo port generará un ValueError si se especifica un puerto no válido en la dirección URL. Consulte la sección Resultados del análisis estructurado para obtener más información sobre el objeto de resultado.

Los corchetes no coincidentes en el atributo netloc generarán un ValueError.

Los caracteres del atributo netloc que se descomponen en la normalización de NFKC (según lo utilizado por la codificación IDNA) en cualquiera de /, ?, #, @ o : lanzará un ValueError. Si la dirección URL se descompone antes del análisis, no se producirá ningún error.

Following some of the WHATWG spec [https://url.spec.whatwg.org/#concept-basic-url-parser] that updates RFC 3986, leading C0 control and space characters are stripped from the URL. \n, \r and tab \t characters are removed from the URL at any position.

Advertencia

urlsplit() does not perform validation. See URL parsing security for details.

Distinto en la versión 3.6: Los números de puerto fuera de rango ahora generan ValueError, en lugar de retornar None.

Distinto en la versión 3.8: Los caracteres que afectan al análisis de netloc en la normalización de NFKC ahora generarán ValueError.

Distinto en la versión 3.9.5: ASCII newline and tab characters are stripped from the URL.

Distinto en la versión 3.9.17: Leading WHATWG C0 control and space characters are stripped from the URL.

urllib.parse.urlunsplit(parts)

Combine los elementos de una tupla retornados por urlsplit() en una URL completa como una cadena. El argumento parts puede ser iterable de cinco elementos. Esto puede dar lugar a una dirección URL ligeramente diferente, pero equivalente, si la dirección URL que se analizó originalmente tenía delimitadores innecesarios (por ejemplo, un ? con una consulta vacía; la RFC indica que son equivalentes).

urllib.parse.urljoin(base, url, allow_fragments=True)

Construya una URL completa («absoluta») combinando una «URL base» (base) con otra URL (url). Informalmente, esto utiliza componentes de la dirección URL base, en particular el esquema de direccionamiento, la ubicación de red y (parte de) la ruta de acceso, para proporcionar los componentes que faltan en la dirección URL relativa. Por ejemplo:

>>> from urllib.parse import urljoin
>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')
'http://www.cwi.nl/%7Eguido/FAQ.html'

El argumento allow_fragments tiene el mismo significado y el valor predeterminado que para urlparse().

Nota

Si url es una URL absoluta (es decir, comienza con // o scheme://), el nombre de host y/o esquema de url estará presente en el resultado. Por ejemplo:

>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html',
...         '//www.python.org/%7Eguido')
'http://www.python.org/%7Eguido'

Si no desea ese comportamiento, preprocesa las partes url con urlsplit() y urlunsplit(), eliminando posibles partes esquema y netloc.

Distinto en la versión 3.5: Comportamiento actualizado para coincidir con la semántica definida en RFC 3986 [https://tools.ietf.org/html/rfc3986.html].

urllib.parse.urldefrag(url)

Si url contiene un identificador de fragmento, retorne una versión modificada de url sin identificador de fragmento y el identificador de fragmento como una cadena independiente. Si no hay ningún identificador de fragmento en url, retorne url sin modificar y una cadena vacía.

El valor retornado es un named tuple, se puede acceder a sus elementos por índice o como atributos con nombre:

Atributo

Índice

Valor

Valor si no está presente

url

0

URL sin fragmento

cadena vacía

fragment

1

Identificador de fragmento

cadena vacía

Consulte la sección Resultados del análisis estructurado para obtener más información sobre el objeto de resultado.

Distinto en la versión 3.2: El resultado es un objeto estructurado en lugar de una simple tupla de 2.

urllib.parse.unwrap(url)

Extrae la url de una URL envuelta (es decir, una cadena de caracteres formateada como <URL:scheme://host/path>, <scheme://host/path>, URL:scheme://host/path or scheme://host/path). Si url no es una URL envuelta, se retorna sin cambios.

URL parsing security

The urlsplit() and urlparse() APIs do not perform validation of inputs. They may not raise errors on inputs that other applications consider invalid. They may also succeed on some inputs that might not be considered URLs elsewhere. Their purpose is for practical functionality rather than purity.

Instead of raising an exception on unusual input, they may instead return some component parts as empty strings. Or components may contain more than perhaps they should.

We recommend that users of these APIs where the values may be used anywhere with security implications code defensively. Do some verification within your code before trusting a returned component part. Does that scheme make sense? Is that a sensible path? Is there anything strange about that hostname? etc.

Análisis de bytes codificados ASCII

Las funciones de análisis de URL se diseñaron originalmente para funcionar solo en cadenas de caracteres. En la práctica, es útil poder manipular las direcciones URL correctamente citadas y codificadas como secuencias de bytes ASCII. En consecuencia, las funciones de análisis de URL de este módulo funcionan en los objetos bytes y bytearray, además de los objetos str.

Si se pasan datos str, el resultado también contendrá solo los datos str. Si se pasan datos bytes o bytearray, el resultado contendrá solo los datos bytes.

Si intenta mezclar datos str con bytes o bytearray en una sola llamada de función, se producirá un TypeError, mientras que al intentar pasar valores de bytes no ASCII se desencadenará UnicodeDecodeError.

Para admitir una conversión más sencilla de objetos de resultado entre str y bytes, todos los valores retornados de las funciones de análisis de URL proporcionan un método encode() (cuando el resultado contiene str data) o un método decode() (cuando el resultado contiene datos bytes). Las firmas de estos métodos coinciden con las de los métodos correspondientes str y bytes (excepto que la codificación predeterminada es 'ascii” en lugar de 'utf-8”). Cada uno produce un valor de un tipo correspondiente que contiene datos bytes (para los métodos encode()) o str (para decode() métodos).

Las aplicaciones que necesitan operar en direcciones URL potencialmente citadas incorrectamente que pueden contener datos no ASCII tendrán que realizar su propia decodificación de bytes a caracteres antes de invocar los métodos de análisis de URL.

El comportamiento descrito en esta sección solo se aplica a las funciones de análisis de URL. Las funciones de citación de URL utilizan sus propias reglas al producir o consumir secuencias de bytes como se detalla en la documentación de las funciones de citación de URL individuales.

Distinto en la versión 3.2: Las funciones de análisis de URL ahora aceptan secuencias de bytes codificadas en ASCII

Resultados del análisis estructurado

Los objetos resultantes de las funciones urlparse(), urlsplit() y urldefrag() son subclases del tipo tuple. Estas subclases agregan los atributos enumerados en la documentación para esas funciones, el soporte de codificación y decodificación descrito en la sección anterior, así como un método adicional:

urllib.parse.SplitResult.geturl()

Retorna la versión re-combinada de la dirección URL original como una cadena. Esto puede diferir de la dirección URL original en que el esquema se puede normalizar a minúsculas y los componentes vacíos pueden descartarse. En concreto, se quitarán los parámetros vacíos, las consultas y los identificadores de fragmento.

Para los resultados urldefrag(), solo se eliminarán los identificadores de fragmento vacíos. Para los resultados urlsplit() y urlparse(), todos los cambios observados se realizarán en la URL retornada por este método.

El resultado de este método permanece inalterado si se pasa de nuevo a través de la función de análisis original:

>>> from urllib.parse import urlsplit
>>> url = 'HTTP://www.Python.org/doc/#'
>>> r1 = urlsplit(url)
>>> r1.geturl()
'http://www.Python.org/doc/'
>>> r2 = urlsplit(r1.geturl())
>>> r2.geturl()
'http://www.Python.org/doc/'

Las clases siguientes proporcionan las implementaciones de los resultados del análisis estructurado cuando se opera en objetos str:

class urllib.parse.DefragResult(url, fragment)

Clase concreta para los resultados de urldefrag() que contienen datos str. El método encode() retorna una instancia DefragResultBytes.

Nuevo en la versión 3.2.

class urllib.parse.ParseResult(scheme, netloc, path, params, query, fragment)

Clase concreta para los resultados de urlparse() que contiene str data. El método encode() retorna una instancia ParseResultBytes.

class urllib.parse.SplitResult(scheme, netloc, path, query, fragment)

Clase concreta para los resultados de urlsplit() que contiene str data. El método encode() retorna una instancia SplitResultBytes.

Las clases siguientes proporcionan las implementaciones de los resultados del análisis cuando se opera en objetos bytes o bytearray:

class urllib.parse.DefragResultBytes(url, fragment)

Clase concreta para los resultados de urldefrag() que contienen datos bytes. El método decode() retorna una instancia DefragResult.

Nuevo en la versión 3.2.

class urllib.parse.ParseResultBytes(scheme, netloc, path, params, query, fragment)

Clase concreta para los resultados urlparse() que contienen datos bytes. El método decode() retorna una instancia ParseResult.

Nuevo en la versión 3.2.

class urllib.parse.SplitResultBytes(scheme, netloc, path, query, fragment)

Clase concreta para los resultados de urlsplit() que contienen datos bytes. El método decode() retorna una instancia SplitResult.

Nuevo en la versión 3.2.

Cita de URL

Las funciones de citación de URL se centran en tomar datos del programa y hacerlos seguros para su uso como componentes URL citando caracteres especiales y codificando adecuadamente texto no ASCII. También admiten la inversión de estas operaciones para volver a crear los datos originales a partir del contenido de un componente de dirección URL si esa tarea aún no está cubierta por las funciones de análisis de URL anteriores.

urllib.parse.quote(string, safe='/', encoding=None, errors=None)

Reemplaza caracteres especiales en string con la secuencia de escape %xx. Las letras, los dígitos y los caracteres '_.-~' nunca se citan. De forma predeterminada, esta función está pensada para citar la sección de ruta de acceso de la dirección URL. El parámetro opcional safe especifica caracteres ASCII adicionales que no se deben citar — su valor predeterminado es '/'.

string puede ser un objeto str o bytes.

Distinto en la versión 3.7: Se ha movido de RFC 2396 [https://tools.ietf.org/html/rfc2396.html] a RFC 3986 [https://tools.ietf.org/html/rfc3986.html] para citar cadenas URL. Ahora se incluye «~» en el conjunto de caracteres reservados.

Los parámetros opcionales encoding y errors especifican cómo tratar con caracteres no ASCII, tal como lo acepta el método str.encode(). encoding por defecto es 'utf-8'. errors tiene como valor predeterminado 'strict', lo que significa que los caracteres no admitidos generan un UnicodeEncodeError. encoding y errors no se deben proporcionar si string es bytes o se genera TypeError.

Tenga en cuenta que quote(string, safe, encoding, errors) es equivalente a quote_from_bytes(string.encode(encoding, errors), safe).

Ejemplo: quote('/El Niño/') produce '/El%20Ni%C3%B1o/'.

urllib.parse.quote_plus(string, safe='', encoding=None, errors=None)

Como quote(), pero también reemplaza espacios con signos más, como se requiere para citar valores de formularios HTML al momento de construir una cadena de consulta que será parte de una URL. Los signos más en la cadena de caracteres original se escapan, a no ser que se incluyan en safe. Además el valor de safe no es / por defecto.

Ejemplo: quote_plus('/El Niño/') produce '%2FEl+Ni%C3%B1o%2F'.

urllib.parse.quote_from_bytes(bytes, safe='/')

Como quote(), pero acepta un objeto bytes en lugar de un str, y no realiza la codificación de cadena a bytes.

Ejemplo: quote_from_bytes(b'a&\xef') produce 'a%26%EF'.

urllib.parse.unquote(string, encoding='utf-8', errors='replace')

Reemplaza secuencias de escape %xx con los caracteres individuales correspondientes. Los parámetros opcionales encoding y errors especifican cómo descodificar secuencias codificadas porcentualmente a caracteres Unicode, tal como lo acepta el método bytes.decode().

string puede ser un objeto str o bytes.

encoding por defecto es 'utf-8”. errors por defecto es 'replace”, lo que significa que las secuencias no válidas se reemplazan por un carácter de marcador de posición.

Ejemplo: unquote('/El%20Ni%C3%B1o/') produce '/El Niño/'.

Distinto en la versión 3.9: El parámetro string admite bytes y cadenas de caracteres (anteriormente sólo cadenas de caracteres).

urllib.parse.unquote_plus(string, encoding='utf-8', errors='replace')

Como unquote(), pero también reemplaza los signos más por espacios, como es requerido al decodificar valores de formularios HTML.

string debe ser str.

Ejemplo: unquote_plus('/El+Ni%C3%B1o/') produce '/El Niño/'.

urllib.parse.unquote_to_bytes(string)

Reemplaza los escapes %xx por sus equivalentes de un solo octeto y retorna un objeto bytes.

string puede ser un objeto str o bytes.

Si es un str, los caracteres no ASCII sin escapar en string se codifican en bytes UTF-8.

Ejemplo: unquote_to_bytes('a%26%EF') produce b'a&\xef'.

urllib.parse.urlencode(query, doseq=False, safe='', encoding=None, errors=None, quote_via=quote_plus)

Convierta un objeto de asignación o una secuencia de tuplas de dos elementos, que pueden contener objetos str o bytes, en una cadena de texto ASCII codificada porcentualmente. Si la cadena resultante se va a utilizar como una operación data para post con la función URLlib.request.urlopen(), entonces debe codificarse en bytes, de lo contrario resultaría en un TypeError.

La cadena resultante es una serie de pares key=value separados por caracteres '&', donde tanto key como value se citan mediante la función quote_via. De forma predeterminada, quote_plus() se utiliza para citar los valores, lo que significa que los espacios se citan como un carácter '+' y “/” los caracteres se codifican como %2F, que sigue el estándar para las solicitudes GET (application/x-www-form-urlencoded). Una función alternativa que se puede pasar como quote_via es quote(), que codificará espacios como %20 y no codificará caracteres “/”. Para obtener el máximo control de lo que se cita, utilice quote y especifique un valor para safe.

Cuando se utiliza una secuencia de tuplas de dos elementos como argumento query, el primer elemento de cada tupla es una clave y el segundo es un valor. El valor en sí mismo puede ser una secuencia y, en ese caso, si el parámetro opcional doseq se evalúa como True, se generan pares individuales key=value separados por '&' para cada elemento de la secuencia de valores de la clave. El orden de los parámetros de la cadena codificada coincidirá con el orden de las tuplas de parámetros de la secuencia.

Los parámetros safe, encoding y errors se pasan a quote_via (los parámetros encoding y errors solo se pasan cuando un elemento de consulta es str).

Para revertir este proceso de codificación, en este módulo se proporcionan parse_qs() y parse_qsl() para analizar cadenas de consulta en estructuras de datos de Python.

Consulte urllib examples para averiguar cómo se puede utilizar el método urllib.parse.urlencode() para generar una cadena de consulta para una dirección URL o datos para POST.

Distinto en la versión 3.2: El parámetro query admite bytes y objetos de cadena.

Nuevo en la versión 3.5: quote_via.

Ver también

WHATWG [https://url.spec.whatwg.org/] - URL Living standard

Working Group for the URL Standard that defines URLs, domains, IP addresses, the application/x-www-form-urlencoded format, and their API.

RFC 3986 [https://tools.ietf.org/html/rfc3986.html] - Identificadores uniformes de recursos

Este es el estándar actual (STD66). Cualquier cambio en el módulo urllib.parse debe ajustarse a esto. Se podrían observar ciertas desviaciones, que son principalmente para fines de compatibilidad con versiones anteriores y para ciertos requisitos de análisis de facto como se observa comúnmente en los principales navegadores.

RFC 2732 [https://tools.ietf.org/html/rfc2732.html] - Formato de direcciones IPv6 literales en URL.

Esto especifica los requisitos de análisis de las direcciones URL IPv6.

RFC 2396 [https://tools.ietf.org/html/rfc2396.html] - Identificadores uniformes de recursos (URI): Sintaxis genérica

Documento que describe los requisitos sintácticos genéricos para los nombres de recursos uniformes (URL) y los localizadores uniformes de recursos (URL).

RFC 2368 [https://tools.ietf.org/html/rfc2368.html] - El esquema mailto URL.

Análisis de requisitos para esquemas de URL de correo a correo.

RFC 1808 [https://tools.ietf.org/html/rfc1808.html] - Localizadores uniformes de recursos relativos

Esta solicitud de comentarios incluye las reglas para unirse a una URL absoluta y relativa, incluyendo un buen número de «Ejemplos anormales» que rigen el tratamiento de los casos fronterizos.

RFC 1738 [https://tools.ietf.org/html/rfc1738.html] - Localizadores uniformes de recursos (URL)

Esto especifica la sintaxis formal y la semántica de las direcciones URL absolutas.

urllib.error — Clases de excepción lanzadas por urllib.request

Código fuente: Lib/urllib/error.py [https://github.com/python/cpython/tree/3.9/Lib/urllib/error.py]

El módulo urllib.error define las clases de excepción para las excepciones lanzadas por urllib.request. La clase de excepción base es URLError.

Las siguientes excepciones son lanzadas por urllib.error según sea apropiado:

exception urllib.error.URLError

Los gestores lanzan esta excepción (o excepciones derivadas) cuando encuentran un problema. Es una subclase de OSError.

reason

El motivo de este error. Puede ser una cadena de mensaje u otra instancia de una excepción.

Distinto en la versión 3.3: Se ha convertido a URLError en una subclase de OSError en lugar de IOError.

exception urllib.error.HTTPError

A pesar de ser una excepción (una subclase de URLError), un HTTPError también puede funcionar como un valor de retorno no excepcional de tipo archivo (lo mismo que retorna urlopen()). Esto es útil para gestionar errores HTTP exóticos, como peticiones de autentificación.

code

Un código de estado HTTP como los definidos en RFC 2616 [https://tools.ietf.org/html/rfc2616.html]. Este valor numérico se corresponde con un valor de un diccionario de códigos como el que hay en http.server.BaseHTTPRequestHandler.responses.

reason

Normalmente esto es una cadena de caracteres que explica el motivo de este error.

headers

Las cabeceras de la respuesta HTTP de la petición HTTP que causó el HTTPError.

Nuevo en la versión 3.4.

exception urllib.error.ContentTooShortError(msg, content)

Esta excepción se lanza cuando la función urlretrieve() detecta que la cantidad de datos descargados es menor que la esperada (dada por la cabecera Content-Length). El atributo content almacena los datos descargados (y supuestamente truncados).

urllib.robotparser — Analizador para robots.txt

Código fuente: Lib/urllib/robotparser.py [https://github.com/python/cpython/tree/3.9/Lib/urllib/robotparser.py]

Este módulo proporciona una sola clase, RobotFileParser, la cual responde preguntas acerca de si un agente de usuario en particular puede o no obtener una URL en el sitio Web que publico el archivo robots.txt. Para más detalles sobre la estructura del archivo robots.txt, consulte http://www.robotstxt.org/orig.html.

class urllib.robotparser.RobotFileParser(url='')

Esta clase proporciona métodos para leer, analizar y responder preguntas acerca de robots.txt

set_url(url)

Establece la URL que hace referencia a un archivo robots.txt.

read()

Lee la URL robots.txt y la envía al analizador.

parse(lines)

Analiza el argumento lines.

can_fetch(useragent, url)

Retorna True si el useragent tiene permiso para buscar la url de acuerdo con las reglas contenidas en el archivo robots.txt analizado.

mtime()

Retorna la hora en que se recuperó por última vez el archivo robots.txt. Esto es útil para arañas web de larga duración que necesitan buscar nuevos archivos robots.txt periódicamente.

modified()

Establece la hora a la que se recuperó por última vez el archivo robots.txt hasta la hora actual.

crawl_delay(useragent)

Retorna el valor del parámetro Crawl-delay de robots.txt para el useragent en cuestión. Si no existe tal parámetro o no se aplica al useragent especificado o la entrada robots.txt para este parámetro tiene una sintaxis no válida, devuelve None.

Nuevo en la versión 3.6.

request_rate(useragent)

Retorna el contenido del parámetro Request-rate de robots.txt como una tupla nombrada RequestRate(requests, seconds). Si no existe tal parámetro o no se aplica al useragent especificado o la entrada robots.txt para este parámetro tiene una sintaxis no válida, devuelve None.

Nuevo en la versión 3.6.

site_maps()

Retorna el contenido del parámetro Sitemap de robots.txt en forma de list(). Si no existe tal parámetro o la entrada robots.txt para este parámetro tiene una sintaxis no válida, devuelve None.

Nuevo en la versión 3.8.

El siguiente ejemplo demuestra el uso básico de la clase RobotFileParser:

>>> import urllib.robotparser
>>> rp = urllib.robotparser.RobotFileParser()
>>> rp.set_url("http://www.musi-cal.com/robots.txt")
>>> rp.read()
>>> rrate = rp.request_rate("*")
>>> rrate.requests
3
>>> rrate.seconds
20
>>> rp.crawl_delay("*")
6
>>> rp.can_fetch("*", "http://www.musi-cal.com/cgi-bin/search?city=San+Francisco")
False
>>> rp.can_fetch("*", "http://www.musi-cal.com/")
True

http — Módulos HTTP

Código fuente: Lib/http/__init__.py [https://github.com/python/cpython/tree/3.9/Lib/http/__init__.py]

http es un paquete que recopila varios módulos para trabajar con el Protocolo de transferencia de hipertexto:

http.client es un cliente del protocolo HTTP de bajo nivel; para la apertura de URL de alto nivel use urllib.request

http.server contiene clases de servidor HTTP básicas basadas en socketserver

http.cookies tiene utilidades para implementar la gestión de estados mediante cookies

http.cookiejar provee persistencia de cookies

http es también un módulo que define una serie de códigos de estado HTTP y mensajes asociados a través de la enumeración http.HTTPStatus:

class http.HTTPStatus

Nuevo en la versión 3.5.

Una subclase de enum.IntEnum que define un conjunto de códigos de estado HTTP, frases de motivo y descripciones largas escritas en inglés.

Uso:

>>> from http import HTTPStatus
>>> HTTPStatus.OK
<HTTPStatus.OK: 200>
>>> HTTPStatus.OK == 200
True
>>> HTTPStatus.OK.value
200
>>> HTTPStatus.OK.phrase
'OK'
>>> HTTPStatus.OK.description
'Request fulfilled, document follows'
>>> list(HTTPStatus)
[<HTTPStatus.CONTINUE: 100>, <HTTPStatus.SWITCHING_PROTOCOLS: 101>, ...]

Códigos de estado HTTP

Los códigos de estado registrados por IANA [https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml] soportados y disponibles en http.HTTPStatus son:

Código

Nombre de la enumeración

Detalle

100

CONTINUE

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.2.1

101

SWITCHING_PROTOCOLS

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.2.2

102

PROCESSING

WebDAV RFC 2518 [https://tools.ietf.org/html/rfc2518.html], Sección 10.1

103

EARLY_HINTS

Un código de estado HTTP para indicar pistas RFC 8297 [https://tools.ietf.org/html/rfc8297.html]

200

OK

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.3.1

201

CREATED

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.3.2

202

ACCEPTED

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.3.3

203

NON_AUTHORITATIVE_INFORMATION

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.3.4

204

NO_CONTENT

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.3.5

205

RESET_CONTENT

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.3.6

206

PARTIAL_CONTENT

HTTP/1.1 RFC 7233 [https://tools.ietf.org/html/rfc7233.html], Sección 4.1

207

MULTI_STATUS

WebDAV RFC 4918 [https://tools.ietf.org/html/rfc4918.html], Sección 11.1

208

ALREADY_REPORTED

Extensiones de enlace a WebDAV RFC 5842 [https://tools.ietf.org/html/rfc5842.html], Sección 7.1 (Experimental)

226

IM_USED

Codificación delta en HTTP RFC 3229 [https://tools.ietf.org/html/rfc3229.html], Sección 10.4.1

300

MULTIPLE_CHOICES

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.4.1

301

MOVED_PERMANENTLY

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.4.2

302

FOUND

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.4.3

303

SEE_OTHER

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.4.4

304

NOT_MODIFIED

HTTP/1.1 RFC 7232 [https://tools.ietf.org/html/rfc7232.html], Section 4.1

305

USE_PROXY

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.4.5

307

TEMPORARY_REDIRECT

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Section 6.4.7

308

PERMANENT_REDIRECT

Redirección permanente RFC 7238 [https://tools.ietf.org/html/rfc7238.html], Sección 3 (Experimental)

400

BAD_REQUEST

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.5.1

401

UNAUTHORIZED

Autentificación HTTP/1.1 RFC 7235 [https://tools.ietf.org/html/rfc7235.html], Sección 3.1

402

PAYMENT_REQUIRED

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.5.2

403

FORBIDDEN

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.5.3

404

NOT_FOUND

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.5.4

405

METHOD_NOT_ALLOWED

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.5.5

406

NOT_ACCEPTABLE

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.5.6

407

PROXY_AUTHENTICATION_REQUIRED

Autenticación HTTP/1.1 RFC 7235 [https://tools.ietf.org/html/rfc7235.html], Sección 3.2

408

REQUEST_TIMEOUT

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.5.7

409

CONFLICT

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.5.8

410

GONE

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.5.9

411

LENGTH_REQUIRED

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.5.10

412

PRECONDITION_FAILED

HTTP/1.1 RFC 7232 [https://tools.ietf.org/html/rfc7232.html], Sección 4.2

413

REQUEST_ENTITY_TOO_LARGE

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.5.11

414

REQUEST_URI_TOO_LONG

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.5.12

415

UNSUPPORTED_MEDIA_TYPE

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.5.13

416

REQUESTED_RANGE_NOT_SATISFIABLE

Rango de solicitudes HTTP/1.1 RFC 7233 [https://tools.ietf.org/html/rfc7233.html], Sección 4.4

417

EXPECTATION_FAILED

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.5.14

418

IM_A_TEAPOT

HTCPCP/1.0 RFC 2324 [https://tools.ietf.org/html/rfc2324.html], Section 2.3.2

421

MISDIRECTED_REQUEST

HTTP/2 RFC 7540 [https://tools.ietf.org/html/rfc7540.html], Sección 9.1.2

422

UNPROCESSABLE_ENTITY

WebDAV RFC 4918 [https://tools.ietf.org/html/rfc4918.html], Sección 11.2

423

LOCKED

WebDAV RFC 4918 [https://tools.ietf.org/html/rfc4918.html], Sección 11.3

424

FAILED_DEPENDENCY

WebDAV RFC 4918 [https://tools.ietf.org/html/rfc4918.html], Sección 11.4

425

TOO_EARLY

Uso de datos iniciales en HTTP RFC 8470 [https://tools.ietf.org/html/rfc8470.html]

426

UPGRADE_REQUIRED

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.5.15

428

PRECONDITION_REQUIRED

Códigos de estados HTTP adicionales RFC 6585 [https://tools.ietf.org/html/rfc6585.html]

429

TOO_MANY_REQUESTS

Códigos de estados HTTP adicionales RFC 6585 [https://tools.ietf.org/html/rfc6585.html]

431

REQUEST_HEADER_FIELDS_TOO_LARGE

Códigos de estados HTTP adicionales RFC 6585 [https://tools.ietf.org/html/rfc6585.html]

451

UNAVAILABLE_FOR_LEGAL_REASONS

Un código de estado HTTP para reportar obstáculos legales RFC 7725 [https://tools.ietf.org/html/rfc7725.html]

500

INTERNAL_SERVER_ERROR

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.6.1

501

NOT_IMPLEMENTED

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.6.2

502

BAD_GATEWAY

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.6.3

503

SERVICE_UNAVAILABLE

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.6.4

504

GATEWAY_TIMEOUT

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.6.5

505

HTTP_VERSION_NOT_SUPPORTED

HTTP/1.1 RFC 7231 [https://tools.ietf.org/html/rfc7231.html], Sección 6.6.6

506

VARIANT_ALSO_NEGOTIATES

Negociación transparente de contenido en HTTP RFC 2295 [https://tools.ietf.org/html/rfc2295.html], Sección 8.1 (Experimental)

507

INSUFFICIENT_STORAGE

WebDAV RFC 4918 [https://tools.ietf.org/html/rfc4918.html], Sección 11.5

508

LOOP_DETECTED

Extensiones de unión WebDAV RFC 5842 [https://tools.ietf.org/html/rfc5842.html], Sección 7.2 (Experimental)

510

NOT_EXTENDED

Un framework de extensión HTTP RFC 2774 [https://tools.ietf.org/html/rfc2774.html], Sección 7 (Experimental)

511

NETWORK_AUTHENTICATION_REQUIRED

Códigos de estados HTTP adicionales RFC 6585 [https://tools.ietf.org/html/rfc6585.html], Sección 6

Con el fin de preservar la compatibilidad con versiones anteriores, los valores de la enumeración están también presentes en el módulo http.client en forma de constantes. El nombre de la enumeración es el mismo que el nombre de la constante (ej. http.HTTPStatus.OK se encuentra también disponible como http.client.OK).

Distinto en la versión 3.7: Se agregó el código de estado 421 MISDIRECTED_REQUEST.

Nuevo en la versión 3.8: Se agregó el código de estado 451 UNAVAILABLE_FOR_LEGAL_REASONS.

Nuevo en la versión 3.9: Agregados códigos de estado 103 EARLY_HINTS, 418 IM_A_TEAPOT y 425 TOO_EARLY.

http.client — Cliente de protocolo HTTP

Código fuente: Lib/http/client.py [https://github.com/python/cpython/tree/3.9/Lib/http/client.py]

Este módulo define clases que se implementan del lado del cliente de los protocolos HTTP y HTTPS. Normalmente no se usa directamente — el módulo urllib.request lo usa para gestionar URLs que usan HTTP y HTTPS.

Ver también

El Paquete de solicitudes [https://requests.readthedocs.io/en/master/] se recomienda para una interfaz de cliente HTTP de alto nivel.

Nota

El soporte HTTPS solo está disponible si Python se compiló con soporte SSL (a través del módulo ssl).

El módulo proporciona las siguientes clases:

class http.client.HTTPConnection(host, port=None, [timeout, ]source_address=None, blocksize=8192)

Una instancia HTTPConnection representa una transacción con un servidor HTTP. Se debe instanciar pasándole un host y un número de puerto opcional. Si no se pasa ningún número de puerto, el puerto se extrae de la cadena de host si tiene la forma host:port; de lo contrario, se utiliza el puerto HTTP predeterminado (80). Si se proporciona el parámetro opcional timeout, las operaciones de bloqueo (como los intentos de conexión) expirarán después de esos segundos (si no se proporciona, se usa la configuración de tiempo de espera global predeterminada). El parámetro opcional source_address puede ser una tupla de un (host, puerto) para usar como la dirección de origen desde la que se realiza la conexión HTTP. El parámetro opcional blocksize establece el tamaño del búfer en bytes para enviar un cuerpo de mensaje similar a un archivo.

Por ejemplo, las siguientes llamadas crean instancias que se conectan al servidor en el mismo host y puerto:

>>> h1 = http.client.HTTPConnection('www.python.org')
>>> h2 = http.client.HTTPConnection('www.python.org:80')
>>> h3 = http.client.HTTPConnection('www.python.org', 80)
>>> h4 = http.client.HTTPConnection('www.python.org', 80, timeout=10)

Distinto en la versión 3.2: source_address fue adicionado.

Distinto en la versión 3.4: Se eliminó el argumento strict. Las «Respuestas Simples» de estilo HTTP 0.9 ya no son compatibles.

Distinto en la versión 3.7: argumento blocksize fue adicionado.

class http.client.HTTPSConnection(host, port=None, key_file=None, cert_file=None, [timeout, ]source_address=None, *, context=None, check_hostname=None, blocksize=8192)

Una subclase de HTTPConnection que usa SSL para la comunicación con servidores seguros. El puerto predeterminado es 443. Si se especifica context, debe ser una instancia de ssl.SSLContext que describa las diversas opciones de SSL.

Por favor lea Consideraciones de seguridad para obtener más información sobre las mejores prácticas.

Distinto en la versión 3.2: source_address, context y check_hostname fueron adicionados.

Distinto en la versión 3.2: Esta clase ahora soporta hosts virtuales HTTPS si es posible (es decir, si ssl.HAS_SNI es verdadero).

Distinto en la versión 3.4: Se eliminó el argumento strict. Las «Respuestas Simples» de estilo HTTP 0.9 ya no son compatibles.

Distinto en la versión 3.4.3: Esta clase ahora realiza todas las comprobaciones necesarias de certificados y nombres de host de forma predeterminada. Para volver al comportamiento anterior no verificado ssl._create_unverified_context() se puede pasar al argumento context.

Distinto en la versión 3.8: Esta clase ahora habilita TLS 1.3 ssl.SSLContext.post_handshake_auth para el context predeterminado o cuando cert_file se pasa con un context personalizado.

Obsoleto desde la versión 3.6: key_file y cert_file están discontinuadas en favor de context. Por favor use ssl.SSLContext.load_cert_chain() en su lugar, o deje que ssl.create_default_context() seleccione los certificados de CA de confianza del sistema para usted.

El argumento check_hostname también está discontinuado; el atributo ssl.SSLContext.check_hostname de context debe usarse en su lugar.

class http.client.HTTPResponse(sock, debuglevel=0, method=None, url=None)

Clase cuyas instancias se retornan tras una conexión exitosa. No son instancias realizadas directamente por el usuario.

Distinto en la versión 3.4: Se eliminó el argumento strict. Las «Respuestas Simples» del estilo HTTP 0.9 ya no están soportadas.

Este módulo proporciona la siguiente función:

http.client.parse_headers(fp)

Analiza los encabezados desde un puntero de archivo fp que representa una solicitud/respuesta HTTP. El archivo debe ser un lector BufferedIOBase (es decir, no texto) y debe proporcionar un encabezado de estilo válido RFC 2822 [https://tools.ietf.org/html/rfc2822.html].

Esta función retorna una instancia de http.client.HTTPMessage que contiene los campos de encabezado, pero no un payload (lo mismo que HTTPResponse.msg y http.server.BaseHTTPRequestHandler.headers ) Después de regresar, el puntero de archivo fp está listo para leer el cuerpo HTTP.

Nota

parse_headers() no analiza la línea de inicio de un mensaje HTTP; solo analiza las líneas Name: value. El archivo tiene que estar listo para leer estas líneas de campo, por lo que la primera línea ya debe consumirse antes de llamar a la función.

Las siguientes excepciones son lanzadas según corresponda:

exception http.client.HTTPException

La clase base de las otras excepciones en este módulo. Es una subclase de Exception.

exception http.client.NotConnected

Una subclase de HTTPException.

exception http.client.InvalidURL

Una subclase de HTTPException, es lanzada si se proporciona un puerto y no es numérico o está vacío.

exception http.client.UnknownProtocol

Una subclase de HTTPException.

exception http.client.UnknownTransferEncoding

Una subclase de HTTPException.

exception http.client.UnimplementedFileMode

Una subclase de HTTPException.

exception http.client.IncompleteRead

Una subclase de HTTPException.

exception http.client.ImproperConnectionState

Una subclase de HTTPException.

exception http.client.CannotSendRequest

Una subclase de ImproperConnectionState.

exception http.client.CannotSendHeader

Una subclase de ImproperConnectionState.

exception http.client.ResponseNotReady

Una subclase de ImproperConnectionState.

exception http.client.BadStatusLine

Una subclase de HTTPException. Es lanzada si un servidor responde con un código de estado HTTP que no entendemos.

exception http.client.LineTooLong

Una subclase de HTTPException. Es lanzada si se recibe una línea excesivamente larga en el protocolo HTTP del servidor.

exception http.client.RemoteDisconnected

Una subclase de ConnectionResetError y BadStatusLine. Lanzada por HTTPConnection.getresponse() cuando el intento de leer la respuesta no produce datos leídos de la conexión, indica que el extremo remoto ha cerrado la conexión.

Nuevo en la versión 3.5: Previamente, BadStatusLine('') fue lanzada.

Las constantes definidas en este módulo son:

http.client.HTTP_PORT

El puerto predeterminado para el protocolo HTTP (siempre 80).

http.client.HTTPS_PORT

El puerto predeterminado para el protocolo HTTPS (siempre 443).

http.client.responses

Este diccionario asigna los códigos de estado HTTP 1.1 a los nombres W3C.

Ejemplo: http.client.responses[http.client.NOT_FOUND] es 'Not Found'.

Consulte Códigos de estado HTTP para obtener una lista de los códigos de estado HTTP que están disponibles en este módulo como constantes.

Objetos de HTTPConnection

Las instancias HTTPConnection tienen los siguientes métodos:

HTTPConnection.request(method, url, body=None, headers={}, *, encode_chunked=False)

Esto enviará una solicitud al servidor utilizando el método de solicitud HTTP method y el selector url.

Si se especifica body, los datos especificados se envían una vez finalizados los encabezados. Puede ser str, un objeto bytes-like object, un objeto file object abierto, o un iterable de bytes. Si body es una cadena, se codifica como ISO-8859-1, el valor predeterminado para HTTP. Si es un objeto de tipo bytes, los bytes se envían tal cual. Si es un objeto file object, se envía el contenido del archivo; Este objeto de archivo debe soportar al menos el método read(). Si el objeto de archivo es una instancia de io.TextIOBase, los datos retornados por el método read() se codificarán como ISO-8859-1, de lo contrario, los datos retornados por read() se envía como está. Si body es un iterable, los elementos del iterable se envían tal cual hasta que se agota el iterable.

El argumento headers debe ser un mapeo de encabezados HTTP extras para enviar con la solicitud.

Si headers no contiene Content-Length ni Transfer-Encoding, pero hay un cuerpo de solicitud, uno de esos campos de encabezado se agregará automáticamente. Si body es None, el encabezado Content-Length se establece en 0 para los métodos que esperan un cuerpo (PUT, POST y PATCH) . Si body es una cadena de caracteres o un objeto similar a bytes que no es también un file, el encabezado Content-Length se establece en su longitud. Cualquier otro tipo de body (archivos e iterables en general) se codificará en fragmentos, y el encabezado Transfer-Encoding se establecerá automáticamente en lugar de Content-Length.

El argumento encode_chunked solo es relevante si Transfer-Encoding se especifica en headers. Si encode_chunked es False, el objeto HTTPConnection supone que toda la codificación es manejada por el código de llamada. Si es True, el cuerpo estará codificado en fragmentos.

Nota

La codificación de transferencia fragmentada se ha agregado al protocolo HTTP versión 1.1. A menos que se sepa que el servidor HTTP maneja HTTP 1.1, el llamador debe especificar la longitud del contenido o debe pasar un str o un objeto similar a bytes que no sea también un archivo como la representación del cuerpo.

Nuevo en la versión 3.2: body ahora puede ser un iterable.

Distinto en la versión 3.6: Si ni Content-Length ni Transfer-Encoding están configurados en headers, el archivo y los objetos iterables body ahora están codificados en fragmentos. Se agregó el argumento encode_chunked. No se intenta determinar la longitud del contenido para los objetos de archivo.

HTTPConnection.getresponse()

Debe llamarse después de enviar una solicitud para obtener la respuesta del servidor. Retorna una instancia de HTTPResponse.

Nota

Tenga en cuenta que debe haber leído la respuesta completa antes de poder enviar una nueva solicitud al servidor.

Distinto en la versión 3.5: Si una ConnectionError o una subclase fue lanzada, el objeto HTTPConnection estará listo para volver a conectarse cuando se envíe una nueva solicitud.

HTTPConnection.set_debuglevel(level)

Establecer el nivel de depuración. El nivel de depuración predeterminado es 0, lo que significa que no se imprime ninguna salida de depuración. Cualquier valor mayor que 0 hará que todos los resultados de depuración definidos actualmente se impriman en stdout. El debuglevel se pasa a cualquier objeto nuevo HTTPResponse que se cree.

Nuevo en la versión 3.1.

HTTPConnection.set_tunnel(host, port=None, headers=None)

Configure el host y el puerto para el túnel de conexión HTTP. Esto permite ejecutar la conexión a través de un servidor proxy.

Los argumentos de host y puerto especifican el punto final de la conexión realizada por el túnel (es decir, la dirección incluida en la solicitud CONNECT, da not la dirección del servidor proxy).

El argumento de los encabezados debe ser un mapeo de encabezados HTTP adicionales para enviar con la solicitud CONNECT.

Por ejemplo, para hacer un túnel a través de un servidor proxy HTTPS que se ejecuta localmente en el puerto 8080, pasaríamos la dirección del proxy al constructor HTTPSConnection, y la dirección del host al que finalmente queremos llegar al método set_tunnel():

>>> import http.client
>>> conn = http.client.HTTPSConnection("localhost", 8080)
>>> conn.set_tunnel("www.python.org")
>>> conn.request("HEAD","/index.html")

Nuevo en la versión 3.2.

HTTPConnection.connect()

Se conecta al servidor especificado cuando el objeto fue creado. Por defecto, esto se llama automáticamente cuando se realiza una solicitud si el cliente aún no tiene una conexión.

HTTPConnection.close()

Cierre la conexión al servidor.

HTTPConnection.blocksize

Tamaño del búfer en bytes para enviar un archivo como cuerpo del mensaje.

Nuevo en la versión 3.7.

Como alternativa al uso del método request() descrito anteriormente, también puede enviar su solicitud paso a paso, utilizando las cuatro funciones a continuación.

HTTPConnection.putrequest(method, url, skip_host=False, skip_accept_encoding=False)

Esta debería ser la primera llamada después de que se haya realizado la conexión al servidor. Envía una línea al servidor que consta de la cadena de caracteres method, la cadena de caracteres url y la versión HTTP (HTTP/1.1). Para deshabilitar el envío automático de encabezados``Host:`` o Accept-Encoding: (por ejemplo, para aceptar codificaciones de contenido adicionales), especifique skip_host o skip_accept_encoding con valores no Falsos.

HTTPConnection.putheader(header, argument[, ...])

Envía un encabezado de estilo RFC 822 [https://tools.ietf.org/html/rfc822.html]al servidor. Este envía una línea al servidor que consta del encabezado, dos puntos y un espacio, y el primer argumento. Si se dan más argumentos, se envían líneas de continuación, cada una de las cuales consta de tabulación y un argumento.

HTTPConnection.endheaders(message_body=None, *, encode_chunked=False)

Envía una línea en blanco al servidor, señalando el final de los encabezados. El argumento opcional message_body se puede usar para pasar un cuerpo de mensaje asociado a la solicitud.

Si encode_chunked es True, el resultado de cada iteración de message_body se codificará en fragmentos como se especifica en RFC 7230 [https://tools.ietf.org/html/rfc7230.html], Sección 3.3.1. La forma en que se codifican los datos depende del tipo de message_body. Si message_body implementa buffer interface la codificación dará como resultado un solo fragmento. Si message_body es una collections.abc.Iterable, cada iteración de message_body dará como resultado un fragmento. Si message_body es un objeto file object, cada llamada a .read() dará como resultado un fragmento. El método señala automáticamente el final de los datos codificados en fragmentos inmediatamente después de message_body.

Nota

Debido a la especificación de codificación fragmentada, fragmentos vacíos producidos por un cuerpo iterador será ignorado por el codificador de fragmentos. Esto es para evitar la terminación prematura de la lectura de la solicitud por parte del servidor de destino debido a una codificación con formato incorrecto.

Nuevo en la versión 3.6: Soporte de codificación fragmentada. Se agregó el parámetro encode_chunked.

HTTPConnection.send(data)

Envía datos al servidor. Esto debe usarse directamente solo después de que se haya llamado al método endheaders() y antes de que se llame al método getresponse().

Objetos de HTTPResponse

Una instancia de HTTPResponse envuelve la respuesta HTTP del servidor. Proporciona acceso a los encabezados de la solicitud y al cuerpo de la entidad. La respuesta es un objeto iterable y puede usarse en una declaración with.

Distinto en la versión 3.5: La interfaz io.BufferedIOBase ahora está implementada y todas sus operaciones de lectura están soportadas.

HTTPResponse.read([amt])

Lee y retorna el cuerpo de respuesta, o hasta los siguientes bytes amt.

HTTPResponse.readinto(b)

Lee hasta los siguientes bytes len(b) del cuerpo de respuesta en el búfer b. Retorna el número de bytes leídos.

Nuevo en la versión 3.3.

HTTPResponse.getheader(name, default=None)

Retorna el valor del encabezado name o default si no hay un encabezado que coincida con name. Si hay más de un encabezado con el nombre name, retorne todos los valores unidos por “, “. Si es “default” es cualquier iterable que no sea una sola cadena de caracteres, sus elementos se retornan de manera similar unidos por comas.

HTTPResponse.getheaders()

Retorna una lista de tuplas (encabezado, valor).

HTTPResponse.fileno()

Retorna el fileno del socket implícito.

HTTPResponse.msg

Una instancia http.client.HTTPMessage que contiene los encabezados de respuesta. http.client.HTTPMessage es una subclase de email.message.Message.

HTTPResponse.version

Versión del protocolo HTTP utilizada por el servidor. 10 para HTTP/1.0, 11 para HTTP/1.1.

HTTPResponse.url

URL del recurso recuperado, comúnmente utilizado para determinar si se siguió una redirección.

HTTPResponse.headers

Cabeceras de la respuesta en forma de una instancia email.message.EmailMessage.

HTTPResponse.status

Código del estado retornado por el servidor.

HTTPResponse.reason

Una frase de la razón es retornada por el servidor.

HTTPResponse.debuglevel

Un depurador. Si debuglevel es mayor que cero, los mensajes se imprimirán en stdout a medida que se lee y analiza la respuesta.

HTTPResponse.closed

Es True si la transmisión está cerrada.

HTTPResponse.geturl()

Obsoleto desde la versión 3.9: Deprecada a favor de url.

HTTPResponse.info()

Obsoleto desde la versión 3.9: Deprecada a favor de headers.

HTTPResponse.getstatus()

Obsoleto desde la versión 3.9: Deprecada a favor de status.

Ejemplos

Aquí hay una sesión de ejemplo que usa el método GET method:

>>> import http.client
>>> conn = http.client.HTTPSConnection("www.python.org")
>>> conn.request("GET", "/")
>>> r1 = conn.getresponse()
>>> print(r1.status, r1.reason)
200 OK
>>> data1 = r1.read()  # This will return entire content.
>>> # The following example demonstrates reading data in chunks.
>>> conn.request("GET", "/")
>>> r1 = conn.getresponse()
>>> while chunk := r1.read(200):
...     print(repr(chunk))
b'<!doctype html>\n<!--[if"...
...
>>> # Example of an invalid request
>>> conn = http.client.HTTPSConnection("docs.python.org")
>>> conn.request("GET", "/parrot.spam")
>>> r2 = conn.getresponse()
>>> print(r2.status, r2.reason)
404 Not Found
>>> data2 = r2.read()
>>> conn.close()

Aquí hay una sesión de ejemplo que usa el método HEAD. Tenga en cuenta que el método HEAD nunca retorna ningún dato.

>>> import http.client
>>> conn = http.client.HTTPSConnection("www.python.org")
>>> conn.request("HEAD", "/")
>>> res = conn.getresponse()
>>> print(res.status, res.reason)
200 OK
>>> data = res.read()
>>> print(len(data))
0
>>> data == b''
True

Aquí hay una sesión de ejemplo que muestra cómo solicitar POST:

>>> import http.client, urllib.parse
>>> params = urllib.parse.urlencode({'@number': 12524, '@type': 'issue', '@action': 'show'})
>>> headers = {"Content-type": "application/x-www-form-urlencoded",
...            "Accept": "text/plain"}
>>> conn = http.client.HTTPConnection("bugs.python.org")
>>> conn.request("POST", "", params, headers)
>>> response = conn.getresponse()
>>> print(response.status, response.reason)
302 Found
>>> data = response.read()
>>> data
b'Redirecting to <a href="http://bugs.python.org/issue12524">http://bugs.python.org/issue12524</a>'
>>> conn.close()

Las solicitudes HTTP PUT del lado del cliente son muy similares a las solicitudes POST. La diferencia radica solo en el lado del servidor donde el servidor HTTP permitirá que se creen recursos a través de la solicitud PUT. Cabe señalar que los métodos HTTP personalizados también se manejan en urllib.request.Request configurando el atributo de método apropiado. Aquí hay una sesión de ejemplo que muestra cómo enviar una solicitud PUT utilizando http.client:

>>> # This creates an HTTP message
>>> # with the content of BODY as the enclosed representation
>>> # for the resource http://localhost:8080/file
...
>>> import http.client
>>> BODY = "***filecontents***"
>>> conn = http.client.HTTPConnection("localhost", 8080)
>>> conn.request("PUT", "/file", BODY)
>>> response = conn.getresponse()
>>> print(response.status, response.reason)
200, OK

Objetos de HTTPMessage

Una instancia de http.client.HTTPMessage contiene los encabezados de una respuesta HTTP. Se implementa utilizando la clase email.message.Message.

ftplib — cliente de protocolo FTP

Código fuente Lib/ftplib.py [https://github.com/python/cpython/tree/3.9/Lib/ftplib.py]

Este módulo define la clase FTP y algunos elementos relacionados. La clase FTP implementa el lado cliente del protocolo FTP. Puedes usarlo para escribir programas en Python que realizan una variedad de trabajos FTP automatizados, como reflejar otros servidores FTP. También es utilizado por el módulo urllib.request para manejar URLs que usan FTP. Para más información sobre FTP (Protocolo de transferencia de archivos), véase Internet RFC 959 [https://tools.ietf.org/html/rfc959.html].

La codificación predeterminada es UTF-8, siguiendo RFC 2640 [https://tools.ietf.org/html/rfc2640.html].

Aquí hay una sesión de ejemplo usando el módulo ftplib:

>>> from ftplib import FTP
>>> ftp = FTP('ftp.us.debian.org')  # connect to host, default port
>>> ftp.login()                     # user anonymous, passwd anonymous@
'230 Login successful.'
>>> ftp.cwd('debian')               # change into "debian" directory
'250 Directory successfully changed.'
>>> ftp.retrlines('LIST')           # list directory contents
-rw-rw-r--    1 1176     1176         1063 Jun 15 10:18 README
...
drwxr-sr-x    5 1176     1176         4096 Dec 19  2000 pool
drwxr-sr-x    4 1176     1176         4096 Nov 17  2008 project
drwxr-xr-x    3 1176     1176         4096 Oct 10  2012 tools
'226 Directory send OK.'
>>> with open('README', 'wb') as fp:
>>>     ftp.retrbinary('RETR README', fp.write)
'226 Transfer complete.'
>>> ftp.quit()
'221 Goodbye.'

El módulo define los siguientes elementos:

class ftplib.FTP(host='', user='', passwd='', acct='', timeout=None, source_address=None, *, encoding='utf-8')

Retorna una nueva instancia de la clase FTP. Cuando se da host, se realiza la llamada al método connect(host). Cuando se da user, además se realiza la llamada al método login(user, passwd, acct) (donde passwd y acct predeterminan la cadena de caracteres vacía cuando no se dan). El parámetro opcional timeout especifica un tiempo de espera en segundos para bloquear operaciones como el intento de conexión (si no se especifica, se utilizará la configuración de tiempo de espera global predeterminada). source_address es una tupla de dos elementos (host, port) para que el socket se vincule como su dirección de origen antes de conectarse. El parámetro encoding especifica la codificación de directorios y nombres de archivo.

La clase FTP admite la instrucción with, por ejemplo:

>>> from ftplib import FTP
>>> with FTP("ftp1.at.proftpd.org") as ftp:
...     ftp.login()
...     ftp.dir()
...
'230 Anonymous login ok, restrictions apply.'
dr-xr-xr-x   9 ftp      ftp           154 May  6 10:43 .
dr-xr-xr-x   9 ftp      ftp           154 May  6 10:43 ..
dr-xr-xr-x   5 ftp      ftp          4096 May  6 10:43 CentOS
dr-xr-xr-x   3 ftp      ftp            18 Jul 10  2008 Fedora
>>>

Distinto en la versión 3.2: Se agregó compatibilidad con la instrucción with.

Distinto en la versión 3.3: Se agregó el parámetro source_address.

Distinto en la versión 3.9: Si el parámetro timeout se establece en cero, lanzará un ValueError para evitar la creación de un socket sin bloqueo. Se agregó el parámetro encoding, y el valor predeterminado se cambió de Latin-1 a UTF-8 para seguir RFC 2640 [https://tools.ietf.org/html/rfc2640.html].

class ftplib.FTP_TLS(host='', user='', passwd='', acct='', keyfile=None, certfile=None, context=None, timeout=None, source_address=None, *, encoding='utf-8')

Una subclase FTP que agrega compatibilidad con TLS a FTP como se describe en RFC 4217 [https://tools.ietf.org/html/rfc4217.html]. Conéctate como de costumbre al puerto 21 asegurando implícitamente la conexión de control antes de autenticar. Proteger la conexión de datos requiere que el usuario la solicite explícitamente llamando al método prot_p(). context es un objeto ssl.SSLContext que permite agrupar opciones de configuración SSL, certificados y claves privadas en una sola estructura (potencialmente de larga duración). Por favor, lee Consideraciones de seguridad para conocer las mejores prácticas.

keyfile y certfile son una alternativa de legado a context – pueden apuntar a una clave privada en formato PEM y certificar archivos de cadena (respectivamente) para la conexión SSL.

Nuevo en la versión 3.2.

Distinto en la versión 3.3: Se agregó el parámetro source_address.

Distinto en la versión 3.4: La clase ahora admite el chequeo del nombre de host con ssl.SSLContext.check_hostname y Server Name Indication (véase ssl.HAS_SNI).

Obsoleto desde la versión 3.6: keyfile y certfile son rechazados a favor de context. Por favor, usa ssl.SSLContext.load_cert_chain() en su lugar, o deja que ssl.create_default_context() seleccione los certificados CA confiables para ti.

Distinto en la versión 3.9: Si el parámetro timeout se establece en cero, lanzará un ValueError para evitar la creación de un socket sin bloqueo. Se agregó el parámetro encoding, y el valor predeterminado se cambió de Latin-1 a UTF-8 para seguir RFC 2640 [https://tools.ietf.org/html/rfc2640.html].

Aquí hay una sesión de ejemplo que usa la clase FTP_TLS:

>>> ftps = FTP_TLS('ftp.pureftpd.org')
>>> ftps.login()
'230 Anonymous user logged in'
>>> ftps.prot_p()
'200 Data protection level set to "private"'
>>> ftps.nlst()
['6jack', 'OpenBSD', 'antilink', 'blogbench', 'bsdcam', 'clockspeed', 'djbdns-jedi', 'docs', 'eaccelerator-jedi', 'favicon.ico', 'francotone', 'fugu', 'ignore', 'libpuzzle', 'metalog', 'minidentd', 'misc', 'mysql-udf-global-user-variables', 'php-jenkins-hash', 'php-skein-hash', 'php-webdav', 'phpaudit', 'phpbench', 'pincaster', 'ping', 'posto', 'pub', 'public', 'public_keys', 'pure-ftpd', 'qscan', 'qtc', 'sharedance', 'skycache', 'sound', 'tmp', 'ucarp']

exception ftplib.error_reply

Se lanza una excepción cuando una respuesta inesperada se recibe del servidor.

exception ftplib.error_temp

Se genera una excepción cuando se recibe un código de error que refiere a un error temporal (códigos de respuesta en el rango 400-499).

exception ftplib.error_perm

Se lanza una excepción cuando se recibe un código de error que refiere a un error permanente (códigos de respuesta en el rango 500–599).

exception ftplib.error_proto

Se lanza una excepción cuando se recibe una respuesta del servidor que no coincide con las especificaciones de respuesta del protocolo de transferencia de archivos (FTP), es decir, que comienza con un dígito en el rango 1–5.

ftplib.all_errors

El conjunto de todas las excepciones (como una tupla) que los métodos de instancias FTP pueden lanzar como resultado de problemas con la conexión FTP (a diferencia de los errores de programación hechos por el autor de la llamada). Este conjunto incluye las cuatro excepciones enumeradas anteriormente, como también OSError y EOFError.

Ver también

Módulo netrc

Analizador para el formato de archivo .netrc. El archivo .netrc suele ser utilizado por clientes FTP para cargar la información de autenticación de usuario antes de solicitarlo al usuario.

Objetos FTP

Hay varios métodos disponibles en dos versiones: uno para manejar archivos de texto y otro para archivos binarios. Estos reciben el nombre del comando que se utiliza seguido de lines para la versión de texto o binary para la versión binaria.

Las instancias de FTP tienen los siguientes métodos:

FTP.set_debuglevel(level)

Establece el nivel de depuración de la instancia. Esto controla la cantidad de salida de depuración impresa. El valor predeterminado, 0, no produce una salida de depuración. Un valor de 1 produce una cantidad moderada de salida de depuración, generalmente una sola línea por solicitud. Un valor de 2 produce la cantidad máxima de salida de depuración, registrando cada línea enviada y recibida en la conexión de control.

FTP.connect(host='', port=0, timeout=None, source_address=None)

Conéctate al puerto y al host dados. El número de puerto por defecto es 21, como se establece en la especificación de protocolo FTP. Raramente se necesita un número de puerto diferente. Esta función debería llamarse una vez por cada instancia; no debería llamarse si el host fue dado cuando se creó la instancia. Todos los otros métodos se pueden usar solo después de que se hizo una conexión. Si no se pasa ningún parámetro opcional timeout en segundos para el intento de conexión. Si no se pasa ningún timeout, se usará la configuración de tiempo de espera global. source_address is una tupla de 2 (host, port) para que el socket se enlace como su dirección de origen antes de conectarse.

Lanza un evento auditor ftplib.connect con los argumentos self, host, port.

Distinto en la versión 3.3: Se agregó el parámetro source_address.

FTP.getwelcome()

Retornar el mensaje de bienvenida enviado por el servidor como respuesta a la conexión inicial. (Este mensaje a veces contiene renuncias de responsabilidad o información de ayuda que puede ser relevante para el usuario.)

FTP.login(user='anonymous', passwd='', acct='')

Inicia sesión como el usuario dado. Los parámetros passwd y acct son opcionales y tienen como valor predeterminado la cadena vacía. Si no se especifica ningún usuario, toma como valor predeterminado 'anónimo', el valor predeterminado de passwd es 'anonymous@'. Esta función debería ser invocada solo una vez por cada instancia, luego de que se haya establecido una conexión; no debería invocarse en lo absoluto si se dio un anfitrión y un usuario cuando se creó la instancia. La mayoría de los comandos FTP solo están permitidos luego de que el cliente ha iniciado sesión. El parámetro acct proporciona «información contable»; pocos sistemas implementan esto.

FTP.abort()

Anula una transferencia de archivo que está en progreso. Usarlo no siempre funciona, pero vale la pena intentarlo.

FTP.sendcmd(cmd)

Envía una cadena de comando simple al servidor y retorna la cadena de caracteres de respuesta.

Genera un evento auditor ftplib.sendcmd con los argumentos self, cmd.

FTP.voidcmd(cmd)

Envía una cadena de caracteres como comando simple al servidor y maneja la respuesta. No retorna nada si recibe el código de respuesta que corresponde a una transferencia exitosa (códigos en el rango 200–299).Lanza error_reply de lo contrario.

Genera un evento auditor ftplib.sendcmd con los argumentos self, cmd.

FTP.retrbinary(cmd, callback, blocksize=8192, rest=None)

Recupera un archivo en el modo de transferencia binaria. cmd debería ser un comando RETR``apropiado:  ``'RETR filename'. La función callback es invocada por cada bloque de datos recibido, con un único argumento bytes que proporciona el bloque de datos. El argumento opcional blocksize especifica el tamaño máximo de fragmento que se leerá en el socket de bajo nivel creado para hacer la transferencia real (que también será el tamaño máximo de fragmento que se pasará a callback). Se elige un valor predeterminado razonable. rest significa lo mismo que en el método transfercmd().

FTP.retrlines(cmd, callback=None)

Recupera una lista de archivos o directorios en la codificación especificada por el parámetro encoding en la inicialización. cmd debe ser un comando RETR apropiado (ver retrbinary()) o un comando como LIST o NLST (generalmente solo la cadena de caracteres 'LIST'). LIST recupera una lista de archivos e información sobre esos archivos. NLST recupera una lista de nombres de archivos. La función callback se llama para cada línea con un argumento de cadena de caracteres que contiene la línea con el CRLF final eliminado. El callback predeterminado imprime la línea a sys.stdout.

FTP.set_pasv(val)

Habilita el modo pasivo si val es verdadero, de lo contrario lo inhabilita. El modo pasivo es el valor predeterminado.

FTP.storbinary(cmd, fp, blocksize=8192, callback=None, rest=None)

Almacena un archivo en el modo de transferencia binaria. cmd debería ser un comando STOR``apropiado: ``"STOR filename". fp es un file object (abierto en modo binario) que es leído hasta EOF (final del archivo) usando el método read() en bloques de tamaño blocksize para proporcionar los datos que serán almacenados. El argumento blocksize toma 8192 como valor predeterminado. callback es un único parámetro invocable que se llama en cada bloque de datos luego de que fue enviado. rest significa lo mismo que en el método transfercmd().

Distinto en la versión 3.2: Se agregó el parámetro rest.

FTP.storlines(cmd, fp, callback=None)

Almacena un archivo en modo de línea. cmd debe ser un comando STOR apropiado (ver storbinary()). Las líneas se leen hasta EOF del file object fp (abierto en modo binario) usando su método readline() para proporcionar los datos que se almacenarán. callback es un parámetro único opcional que se puede llamar en cada línea después de su envío.

FTP.transfercmd(cmd, rest=None)

Inicia una transferencia sobre la conexión de datos. Si la transferencia es activa, envía un comando EPRT o PORT y el comando de transferencia especificado por cmd, y acepta la conexión. Si el servidor es pasivo, envía un comando EPSV o PASV, lo conecta, e inicia el comando de transferencia. De cualquier manera, retorna el socket para la conexión.

Si se proporciona rest opcional, se envía un comando REST al servidor, pasando rest como argumento. rest suele ser un desplazamiento de bytes en el archivo solicitado, que le indica al servidor que reinicie el envío de los bytes del archivo en el desplazamiento solicitado, omitiendo los bytes iniciales. Sin embargo, tenga en cuenta que el método transfercmd() convierte rest en una cadena de caracteres con el parámetro encoding especificado en la inicialización, pero no se realiza ninguna comprobación del contenido de la cadena de caracteres. Si el servidor no reconoce el comando REST, se lanzará una excepción error_reply. Si esto sucede, simplemente llame a transfercmd() sin un argumento rest.

FTP.ntransfercmd(cmd, rest=None)

Como transfercmd(), pero retorna una tupla de conexión de datos y el tamaño esperado de los datos. Si el tamaño esperado no se pudo computar, retornará None como tal. cmd y rest significan lo mismo que en transfercmd().

FTP.mlsd(path="", facts=[])

Enumera un directorio en un formato estandarizado usando el comando MLSD (RFC 3659 [https://tools.ietf.org/html/rfc3659.html]). Si se omite path, se asume el directorio actual. facts es una lista de cadenas de caracteres que representan el tipo de información deseada (por ejemplo, ["type", "size", "perm"]). Retorna un objeto generador que produce una tupla de dos elementos por cada archivo encontrado en la ruta. El primer elemento es el nombre del archivo, el segundo es un diccionario que contiene datos sobre el nombre del archivo. El contenido de este diccionario puede estar limitado por el argumento facts, pero no se garantiza que el servidor retorne todos los datos solicitados.

Nuevo en la versión 3.3.

FTP.nlst(argument[, ...])

Retorna una lista de nombres de archivos tal como los retorna el comando NLST. El argument opcional es un directorio para listar (el predeterminado es el directorio del servidor actual). Se pueden usar varios argumentos para pasar opciones no estándar al comando NLST.

Nota

Si tu servidor admite el comando, mlsd() ofrece una API mejor.

FTP.dir(argument[, ...])

Produce una lista de directorios como se retorna por el comando LIST, imprimiéndola en una salida estándar. El argument opcional es un directorio a ser listado (el valor predeterminado es el directorio del servidor actual). Se pueden utilizar argumentos múltiples para pasar las opciones que no son estándar al comando LIST. Si el último argumento es una función, se usa como función callback como en retrlines(); el valor predeterminado imprime a sys.stdout. Este método retorna None.

Nota

Si tu servidor admite el comando, mlsd() ofrece una API mejor.

FTP.rename(fromname, toname)

Asigna un nombre nuevo al archivo en el servidor desde fromname a toname.

FTP.delete(filename)

Remueve el archivo nombrado filename del servidor. De ser exitoso, retorna el texto de la respuesta, de lo contrario, lanza error_perm sobre errores de permiso o error_reply sobre otros errores.

FTP.cwd(pathname)

Configura el directorio actual en el servidor.

FTP.mkd(pathname)

Crea un nuevo directorio en el servidor.

FTP.pwd()

Retorna el nombre de ruta del directorio actual en el servidor.

FTP.rmd(dirname)

Elimina el directorio en el servidor llamado dirname.

FTP.size(filename)

Solicita el tamaño del archivo llamado filename en el servidor. De ser exitoso, se retorna el tamaño del archivo como un entero, de lo contrario retorna None. Nótese que el comando SIZE no está estandarizado, pero es admitido por muchas implementaciones comunes de servidor.

FTP.quit()

Envía un comando QUIT al servidor y cierra la conexión. Esta es la forma «políticamente correcta» de cerrar una conexión, pero puede lanzar una excepción si el servidor responde con un error al comando QUIT. Esto implica una llamada al método close() que hace inútil la instancia de FTP para llamadas posteriores (véase más adelante).

FTP.close()

Cierra la conexión de forma unilateral. Esto no debería aplicarse a una conexión ya cerrada, como luego de una llamada exitosa a quit(). Después de esta llamada, la instancia FTP ya no debería utilizarse (luego de una llamada a close() o quit() no puedes abrir nuevamente la conexión emitiendo otro método login().

Objetos FTP_TLS

La clase FTP_TLS hereda de FTP, definiendo los siguientes objetos adicionales:

FTP_TLS.ssl_version

La versión SSL para usar (toma como predeterminado ssl.PROTOCOL_SSLv23).

FTP_TLS.auth()

Establece una conexión de control segura usando TLS o SSL, dependiendo de qué esté especificado en el atributo ssl_version.

Distinto en la versión 3.4: El método ahora admite el chequeo del nombre de host con ssl.SSLContext.check_hostname y Server Name Indication (véase ssl.HAS_SNI).

FTP_TLS.ccc()

Revierte el canal de control a texto plano. Esto puede ser útil para aprovechar cortafuegos que saben manejar NAT con FTP no-seguro sin abrir puertos fijos.

Nuevo en la versión 3.3.

FTP_TLS.prot_p()

Configura conexión de datos segura.

FTP_TLS.prot_c()

Configura la conexión de datos de tipo texto común.

poplib — Cliente de protocolo POP3

Código fuente: Lib/poplib.py [https://github.com/python/cpython/tree/3.9/Lib/poplib.py]

Este módulo define una clase, POP3, que encapsula una conexión a un servidor POP3 e implementa el protocolo como está definido en RFC 1939 [https://tools.ietf.org/html/rfc1939.html]. La clase POP3 soporta los mínimos y opcionales conjuntos de comandos de RFC 1939 [https://tools.ietf.org/html/rfc1939.html]. La clase POP3 también soporta el comando STLS introducido en RFC 2595 [https://tools.ietf.org/html/rfc2595.html] para habilitar comunicación encriptada en una conexión ya establecida.

Adicionalmente, este módulo provee una clase POP3_SSL, que provee soporte para conectar servidores POP3 que usan SSL como una capa de protocolo subyacente.

Note que POP3, aunque ampliamente soportado, es obsoleto. La calidad de implementación de servidores POP3 varía ampliamente, y muchos son bastante pobres. Si su servidor de correo soporta IMAP, sería mejor utilizar la clase imaplib.IMAP4, ya que los servidores IMAP tienden a estar mejor implementados.

El módulo poplib provee dos clases:

class poplib.POP3(host, port=POP3_PORT[, timeout])

Esta clase implementa el protocolo POP3 actual. La conexión es creada cuando la instancia es inicializada. Si port se omite, el puerto POP3 estándar (110) es utilizado. El parámetro opcional timeout especifica un tiempo de espera en segundos para el intento de conexión (si no se especifica, la configuración global de tiempo de espera será utilizada).

Genera un evento de auditoría poplib.connect con argumentos self, host, port.

Genera un evento de auditoría poplib.putline con argumentos self, line.

Distinto en la versión 3.9: If the timeout parameter is set to be zero, it will raise a ValueError to prevent the creation of a non-blocking socket.

class poplib.POP3_SSL(host, port=POP3_SSL_PORT, keyfile=None, certfile=None, timeout=None, context=None)

Esta es una subclase de POP3 que conecta al servidor sobre un socket SSL encriptado. Si port no es especificado, 995, el puerto POP3-over-SSL es utilizado. timeout funciona como en el constructor de la clase POP3. context es un objeto ssl.SSLContext opcional que permite empaquetar opciones de configuración SSL, certificados y llaves privadas en una única (potencialmente longeva) estructura. Por favor lea Consideraciones de seguridad para buenas prácticas.

keyfile y certfile son una alternativa heredada a context - pueden apuntar a llaves privadas PEM - y archivos de cadena de certificados, respectivamente, para la conexión SSL.

Genera un evento de auditoría poplib.connect con argumentos self, host, port.

Genera un evento de auditoría poplib.putline con argumentos self, line.

Distinto en la versión 3.2: Parámetro context agregado.

Distinto en la versión 3.4: La clase ahora soporta verificación de nombre de host con ssl.SSLContext.check_hostname e Indicación de Nombre de Servidor (vea ssl.HAS_SNI).

Obsoleto desde la versión 3.6: keyfile y certfile están obsoletos en favor de context. Por favor utilice ssl.SSLContext.load_cert_chain() en su lugar, o permita que ssl.create_default_context() seleccione el sistema de certificados CA de confianza para usted.

Distinto en la versión 3.9: If the timeout parameter is set to be zero, it will raise a ValueError to prevent the creation of a non-blocking socket.

Una excepción es definida como un atributo del módulo poplib:

exception poplib.error_proto

Excepción generada en cualquier error de este módulo (errores del módulo socket no son capturadas). La razón para la excepción es pasada al constructor como una cadena.

Ver también

Módulo imaplib

El módulo IMAP de Python.

Preguntas Frecuentes Sobre Fetchmail [http://www.catb.org/~esr/fetchmail/fetchmail-FAQ.html]

Las preguntas frecuentes para el cliente POP/IMAP fetchmail colecciona información en las variaciones del servidor POP3 e incumplimiento de RFC que puede ser útil si usted necesita escribir una aplicación basada en el protocolo POP.

Objetos POP3

Todos los comandos POP3 están representados por métodos del mismo nombre, en minúscula; la mayoría retornan el texto de respuesta enviado por el servidor.

Una instancia POP3 tiene los siguientes métodos:

POP3.set_debuglevel(level)

Establece el nivel de depuración de la instancia. Esto controla la cantidad de salida de depuración impresa. Por defecto, 0, no produce salida de depuración. Un valor de 1 produce una moderada cantidad de salida de depuración, generalmente una única línea por solicitud. Un valor de 2 o mayor produce la máxima cantidad de salida de depuración, registrando cada línea enviada y recibida en la conexión de control.

POP3.getwelcome()

Retorna la cadena de saludo enviada por el servidor POP3.

POP3.capa()

Consulta las capacidades del servidor como está especificado en RFC 2449 [https://tools.ietf.org/html/rfc2449.html]. Retorna un diccionario en la forma {'nombre': ['param'...]}.

Nuevo en la versión 3.4.

POP3.user(username)

Envía el comando del usuario, la respuesta debería indicar que una contraseña es requerida.

POP3.pass_(password)

Envía la contraseña, la respuesta incluye un conteo de mensaje y el tamaño del buzón de correo. Nota: el buzón de correo en el servidor está bloqueado hasta que quit() es llamado.

POP3.apop(user, secret)

Utiliza la autenticación APOP (más segura) para registrar en el servidor POP3.

POP3.rpop(user)

Utiliza autenticación RPOP (similar a los comandos r de UNIX) para registrar en el servidor POP3.

POP3.stat()

Obtiene el estado del buzón de correo. El resultado es una tupla de 2 enteros: (conteo de mensaje, tamaño del buzón de correo).

POP3.list([which])

Solicita lista de mensajes, el resultado es en la forma (respuesta, ['mesg_num octets', ...], octets). Si which está establecido, es el mensaje a listar.

POP3.retr(which)

Recupera el número de mensaje completo which, y establece marca de visto. El resultado es en la forma (respuesta, ['line', ...], octets).

POP3.dele(which)

Marca el número de mensaje which para eliminación. En la mayoría de los servidores las eliminaciones no están actualmente presentadas hasta QUIT (la mayor excepción es Eudora QPOP, que deliberadamente viola las RFC haciendo eliminaciones pendientes en cada desconexión).

POP3.rset()

Remueve las marcas de eliminación para el buzón de correo.

POP3.noop()

No hace nada. Puede ser utilizado como keep-alive.

POP3.quit()

Cierra sesión: envía los cambios, desbloquea el buzón de correo, desconecta.

POP3.top(which, howmuch)

Recupera la cabecera del mensaje mas howmuch las líneas del mensaje después del cabecera del número de mensajes which. El resultado es en la forma (respuesta, ['línea', ...]. octets).

El comando TOP POP3 que este método utiliza, a diferencia del comando RETR, no establece la marca de visto del mensaje; desafortunadamente, TOP está pobremente especificado en las RFC y se rompe con frecuencia en servidores off-brand. Pruebe este método a mano contra los servidores POP3 que usted utilizará antes de confiar en él.

POP3.uidl(which=None)

Retorna la lista del resumen de mensajes (id único). Si which es especificado, el resultado contiene el id único para ese mensaje en la forma 'response mesgnum uid, de otra forma el resultado es una lista (respuesta, ['mengnum uid', ...], octets).

POP3.utf8()

Trata de cambiar al modo UTF-8. Retorna la respuesta del servidor si es exitosa, genera error_proto si no. Especificado en RFC 6856 [https://tools.ietf.org/html/rfc6856.html].

Nuevo en la versión 3.5.

POP3.stls(context=None)

Comienza una sesión TLS en la conexión activa como está especificado en RFC 2595 [https://tools.ietf.org/html/rfc2595.html]. Esto es únicamente permitido antes de la autenticación de usuario

El parámetro context es un objeto ssl.SSLContext que permite empaquetar opciones de configuración SSL, certificados y llaves privadas en una única (potencialmente longeva) estructura. Por favor lea Consideraciones de seguridad para buenas prácticas.

Este método soporta verificación de nombre del host vía ssl.SSLContext.check_hostname e Indicación de Nombre del Servidor (vea ssl.HAS_SNI).

Nuevo en la versión 3.4.

Instancias de POP3_SSL no tienen métodos adicionales. La interfaz de esta subclase es idéntica a su padre.

Ejemplo POP3

Este es un ejemplo mínimo (sin chequeo de errores) que abre un buzón de correo y retorna e imprime todos los mensajes:

import getpass, poplib

M = poplib.POP3('localhost')
M.user(getpass.getuser())
M.pass_(getpass.getpass())
numMessages = len(M.list()[1])
for i in range(numMessages):
    for j in M.retr(i+1)[1]:
        print(j)

Al final del módulo, hay una sección de test que contiene un ejemplo más extensivo de uso.

imaplib — Protocolo del cliente IMAP4

Código fuente: Lib/imaplib.py [https://github.com/python/cpython/tree/3.9/Lib/imaplib.py]

Este módulo define tres clases IMAP4, IMAP4_SSL y IMAP4_stream, que encapsula una conexión a un servidor IMAP4 e implementa un gran subconjunto del protocolo de cliente IMAP4rev1 como se define en :rfc :2060. Es compatible con los servidores IMAP4 (RFC 1730 [https://tools.ietf.org/html/rfc1730.html]), pero tenga en cuenta que el comando STATUS no es compatible con IMAP4.

El módulo imaplib proporciona tres clases, IMAP4 es la clase base:

class imaplib.IMAP4(host='', port=IMAP4_PORT, timeout=None)

Esta clase implementa el protocolo IMAP4. La conexión se crea y la versión del protocolo (IMAP4 o IMAP4rev1) se determina cuando se inicializa la instancia. Si no se especifica host, se usa '' (el host local). Si se omite port, se usa el puerto IMAP4 estándar (143). El parámetro opcional timeout especifica un timeout en segundos para intentar realizar la conexión. Si timeout no se especifica, o es None, se usa el timeout global por defecto de sockets.

La clase IMAP4 soporta la sentencia with. Cuando se usa de esta manera, el comando IMAP4 LOGOUT se emite automáticamente cuando se cierra la declaración with. P.ej.:

>>> from imaplib import IMAP4
>>> with IMAP4("domain.org") as M:
...     M.noop()
...
('OK', [b'Nothing Accomplished. d25if65hy903weo.87'])

Distinto en la versión 3.5: Se agregó soporte para la sentencia with.

Distinto en la versión 3.9: El parámetro opcional timeout fue agregado.

Se definen tres excepciones como atributos de la clase IMAP4:

exception IMAP4.error

Excepción lanzada por cualquier error. El motivo de la excepción se pasa al constructor como una cadena de caracteres.

exception IMAP4.abort

Los errores del servidor IMAP4 causan que esta excepción sea lanzada. Esta es una subclase de IMAP4.error. Tenga en cuenta que cerrar la instancia e instanciar una nueva generalmente permitirá la recuperación de esta excepción.

exception IMAP4.readonly

Esta excepción es lanzada cuando el servidor cambia el estado de un buzón de correo de escritura. Esta es una subclase de IMAP4.error. Algún otro cliente ahora tiene permiso de escritura y será necesario volver a abrir el buzón para volver a obtener el permiso de escritura.

También hay una subclase para conexiones seguras:

class imaplib.IMAP4_SSL(host='', port=IMAP4_SSL_PORT, keyfile=None, certfile=None, ssl_context=None, timeout=None)

Esta es una subclase derivada de IMAP4 que se conecta a través de un socket cifrado SSL (para usar esta clase necesita un módulo de socket que se compiló con soporte SSL). Si no se especifica host, se usa '' (el host local). Si se omite port, se usa el puerto IMAP4 estándar sobre SSL (993). ssl_context es un objeto ssl.SSLContext que permite agrupar opciones de configuración SSL, certificados y claves privadas en una estructura única (potencialmente de larga duración). Leer Consideraciones de seguridad para conocer las mejores prácticas.

keyfile y certfile son una alternativa heredada a ssl_context - pueden apuntar a claves privadas con formato PEM y archivos de cadena de certificados para la conexión SSL. Tenga en cuenta que los parámetros keyfile/certfile son mutuamente excluyentes con ssl_context, un ValueError se lanzará si keyfile/certfile se proporciona junto con ssl_context.

El parámetro opcional timeout especifica un timeout en segundos para intentar realizar la conexión. Si timeout no se especifica, o es None, se usa el timeout global por defecto de sockets.

Distinto en la versión 3.3: El parámetro ssl_context fue agregado.

Distinto en la versión 3.4: La clase ahora admite la verificación del nombre de host con ssl.SSLContext.check_hostname y Server Name Indication (ver ssl.HAS_SNI).

Obsoleto desde la versión 3.6: keyfile y certfile están obsoletos en favor de ssl_context. Utilice ssl.SSLContext.load_cert_chain() en su lugar, o deje que ssl.create_default_context() seleccione los certificados CA de confianza del sistema para usted.

Distinto en la versión 3.9: El parámetro opcional timeout fue agregado.

La segunda subclase permite conexiones creadas por un proceso hijo:

class imaplib.IMAP4_stream(command)

Esta es una subclase derivada de IMAP4 que se conecta a los descriptores de archivo stdin/stdout creados al pasar command a subprocess.Popen ().

Se definen las siguientes funciones de utilidad:

imaplib.Internaldate2tuple(datestr)

Analiza una cadena de caracteres IMAP4 INTERNALDATE y retorna la hora local correspondiente. El valor de retorno es una tupla time.struct_time o None si la cadena de caracteres tiene un formato incorrecto.

imaplib.Int2AP(num)

Convierte un número entero en una representación de bytes utilizando caracteres del conjunto [A .. P].

imaplib.ParseFlags(flagstr)

Convierte una respuesta IMAP4 FLAGS a una tupla de indicadores individuales.

imaplib.Time2Internaldate(date_time)

Convierte date_time en una representación IMAP4 INTERNALDATE. El valor de retorno es una cadena de caracteres en la forma: "DD-Mmm-YYYY HH:MM:SS +HHMM" (incluyendo comillas dobles). El argumento date_time puede ser un número (int o float) que representa segundos en un espacio de tiempo (como lo retorna time.time()), una tupla de 9 que representa la hora local como una instancia de time.struct_time (según lo retornado por time.localtime()), una instancia actualizada de datetime.datetime, o una cadena de caracteres entre comillas dobles. En el último caso, se supone que ya está en el formato correcto.

Tenga en cuenta que los números de mensaje IMAP4 cambian a medida que cambia el buzón de correo; en particular, después de que un comando EXPUNGE realiza eliminaciones, los mensajes restantes se vuelven a numerar. Por lo tanto, es muy recomendable usar UIDs en su lugar, con el comando UID.

Al final del módulo, hay una sección de prueba que contiene un ejemplo más extenso de uso.

Ver también

Documentos describiendo el protocolo, y fuentes de servidores que lo implementan, del Centro de Información IMAP de la Universidad de Washington, pueden ser encontrados en (Código Fuente) https://github.com/uw-imap/imap (Fuera de mantención).

Objetos de IMAP4

Todos los comandos IMAP4rev1 están representados por métodos del mismo nombre, mayúsculas o minúsculas.

Todos los argumentos de los comandos se convierten en cadenas de caracteres, excepto AUTENTICATE y el último argumento de APPEND que se pasa como un literal IMAP4. Si es necesario (la cadena de caracteres contiene caracteres sensibles al protocolo IMAP4 y no está entre paréntesis ni comillas dobles), se cita cada cadena. Sin embargo, siempre se cita el argumento password para el comando LOGIN. Si desea evitar que se cite una cadena de argumento (por ejemplo: el argumento flags para STORE), encierre la cadena entre paréntesis (por ejemplo: r'(\Deleted)').

Cada comando retorna una tupla: (type, [data, ...]) donde type suele ser 'OK' o 'NO', y data es el texto de la respuesta del comando o resultados obligatorios del comando. Cada data es un objeto bytes o una tupla. Si es una tupla, la primera parte es el encabezado de la respuesta, y la segunda parte contiene los datos (es decir, el valor “literal”).

Las opciones message_set de los siguientes comandos son una cadena de caracteres que especifica uno o más mensajes sobre los que se debe actuar. Puede ser un número de mensaje simple ('1'), un rango de números de mensaje ('2:4') o un grupo de rangos no contiguos separados por comas ('1:3,6:9'). Un rango puede contener un asterisco para indicar un límite superior infinito ('3:*').

Una instancia de IMAP4 tiene los siguientes métodos:

IMAP4.append(mailbox, flags, date_time, message)

Agregar mensaje al buzón de correo con nombre.

IMAP4.authenticate(mechanism, authobject)

Autenticar comando — requiere procesamiento de respuesta.

mechanism especifica qué mecanismo de autenticación se utilizará; debe aparecer en la variable de instancia capabilities en la forma AUTH=mechanism.

authobject debe ser un objeto invocable:

data = authobject(response)

Se llamará para procesar las respuestas de continuación del servidor; el argumento response que se pasa será bytes. Debería retornar bytes data que se codificarán en base64 y se enviarán al servidor. Debería retornar None si la respuesta de cancelación de cliente * se debe enviar en su lugar.

Distinto en la versión 3.5: los nombres de usuario y las contraseñas de cadena de caracteres ahora están codificados para utf-8 en lugar de limitarse a ASCII.

IMAP4.check()

Control del buzón de correo en el servidor.

IMAP4.close()

Cerrar el buzón de correo seleccionado actualmente. Los mensajes eliminados se eliminan del buzón de correo de escritura. Este es el comando recomendado antes de LOGOUT.

IMAP4.copy(message_set, new_mailbox)

Copia mensajes message_set al final de new_mailbox.

IMAP4.create(mailbox)

Crea un nuevo buzón de correo llamado mailbox.

IMAP4.delete(mailbox)

Elimina el buzón de correo antiguo llamado mailbox.

IMAP4.deleteacl(mailbox, who)

Elimina las ACLs (elimina cualquier derecho) establecidas para quién en el buzón de correo.

IMAP4.enable(capability)

Habilita capability (ver RFC 5161 [https://tools.ietf.org/html/rfc5161.html]). La mayoría de las capacidades no necesitan estar habilitadas. Actualmente solo esta soportada la capacidad UTF8=ACCEPT (consulte RFC 6855 [https://tools.ietf.org/html/rfc6855.html]).

Nuevo en la versión 3.5: El método enable() en sí, y soporte RFC 6855 [https://tools.ietf.org/html/rfc6855.html].

IMAP4.expunge()

Elimina permanentemente los elementos eliminados del buzón de correo seleccionado. Genera una respuesta EXPUNGE para cada mensaje eliminado. Los datos retornados contienen una lista de números de mensaje EXPUNGE en el orden recibido.

IMAP4.fetch(message_set, message_parts)

Obtiene (partes de) mensajes. message_parts debe ser una cadena de nombres de partes de mensajes encerrados entre paréntesis, por ejemplo: "(UID BODY[TEXT])". Los datos retornados son una tupla de mensaje parte sobre y datos.

IMAP4.getacl(mailbox)

Obtiene la ACLs para mailbox. El método no es estándar, pero es compatible con el servidor Cyrus.

IMAP4.getannotation(mailbox, entry, attribute)

Recupera la ANNOTATIONs especificada para mailbox. El método no es estándar, pero es compatible con el servidor Cyrus.

IMAP4.getquota(root)

Obtiene el uso y los límites de los recursos de la quota de root. Este método es parte de la extensión IMAP4 QUOTA definida en rfc2087.

IMAP4.getquotaroot(mailbox)

Obtiene la lista de quota roots para el nombrado mailbox. Este método es parte de la extensión IMAP4 QUOTA definida en rfc2087.

IMAP4.list([directory[, pattern]])

Lista los nombres de buzones de correo en directory coincidiendo pattern. directory por defecto es la carpeta de correo de nivel superior, y pattern por defecto coincide con cualquier cosa. Los datos retornados contienen una lista de respuestas LIST.

IMAP4.login(user, password)

Identifica al cliente con una contraseña de texto sin formato. El password será citado.

IMAP4.login_cram_md5(user, password)

Fuerza el uso de la autenticación CRAM-MD5 al identificar al cliente para proteger la contraseña. Solo funcionará si la respuesta CAPABILITY'' del servidor incluye la frase ``AUTH=CRAM-MD5.

IMAP4.logout()

Cierra la conexión al servidor. Retorna la respuesta BYE desde el servidor .

Distinto en la versión 3.8: El método ya no ignora las excepciones silenciosamente arbitrarias.

IMAP4.lsub(directory='""', pattern='*')

Lista los nombres de buzones de correos suscritos en el patrón de coincidencia del directorio directory por defecto para el directorio de nivel superior y pattern por defecto para que coincida con cualquier buzón de correo. Los datos retornados son una tupla de mensaje parte sobre y datos.

IMAP4.myrights(mailbox)

Muestra mis ACLs para un buzón de correo (es decir, los derechos que tengo sobre el buzón de correo).

IMAP4.namespace()

Retorna espacios de nombres IMAP como se define en RFC 2342 [https://tools.ietf.org/html/rfc2342.html].

IMAP4.noop()

Envía NOOP al servidor.

IMAP4.open(host, port, timeout=None)

Abre un socket a port y host. El parámetro opcional timeout especifica un timeout en segundos para intentar realizar la conexión. Si timeout no se especifica, o es None, se usa el timeout global por defecto de sockets. Nota también que si el parámetro timeout es cero se lanzará un ValueError para evitar crear un socket sin bloqueo. Este método es implícitamente llamado por el constructor IMAP4. Los objetos de conexiones establecidas por este método serán usados en los métodos IMAP4.read(), IMAP4.readline(), IMAP4.send(), y IMAP4.shutdown(). Este método se puede sobreescribir.

Genera un evento de auditoría imaplib.open con argumentos self, host, port.

Distinto en la versión 3.9: El parámetro timeout fue agregado.

IMAP4.partial(message_num, message_part, start, length)

Obtiene partes truncadas de un mensaje. Los datos retornados son una tupla de mensaje parte sobre y datos.

IMAP4.proxyauth(user)

Asume la autenticación como user. Permite a un administrador autorizado hacer un proxy en el buzón de correo de cualquier usuario.

IMAP4.read(size)

Lee size bytes del servidor remoto. Podemos sobrescribir este método.

IMAP4.readline()

Lee una línea del servidor remoto. Podemos sobrescribir este método.

IMAP4.recent()

Solicita al servidor una actualización. Los datos retornados son None si no hay mensajes nuevos, de lo contrario el valor de respuesta es RECENT.

IMAP4.rename(oldmailbox, newmailbox)

Cambia el nombre del buzón de correo llamado oldmailbox a newmailbox.

IMAP4.response(code)

Retorna los datos para la respuesta code si se recibió, o None. Retorna el código dado, en lugar del tipo habitual.

IMAP4.search(charset, criterion[, ...])

Busca en el buzón de correo mensajes coincidentes. El charset puede ser None, en cuyo caso no se especificará CHARSET en la solicitud al servidor. El protocolo IMAP requiere que se especifique al menos un criterio; se lanzará una excepción cuando el servidor retorne un error. charset debe ser None si la capacidad UTF8=ACCEPT se habilitó utilizando el comando enable().

Ejemplo:

# M is a connected IMAP4 instance...
typ, msgnums = M.search(None, 'FROM', '"LDJ"')

# or:
typ, msgnums = M.search(None, '(FROM "LDJ")')

IMAP4.select(mailbox='INBOX', readonly=False)

Seleccione un buzón de correo. Los datos retornados son el recuento de mensajes en mailbox (respuesta EXISTS). El mailbox predeterminado es 'INBOX'. Si se establece el indicador readonly, no se permiten modificaciones en el buzón de correo.

IMAP4.send(data)

Envía data al servidor remoto. Podemos sobrescribir este método.

Lanza un evento de auditoría imaplib.send con argumentos self, data.

IMAP4.setacl(mailbox, who, what)

Establece una ACL para mailbox. El método no es estándar, pero es compatible con el servidor Cyrus.

IMAP4.setannotation(mailbox, entry, attribute[, ...])

Establece ANNOTATIONs para mailbox. El método no es estándar, pero es compatible con el servidor Cyrus.

IMAP4.setquota(root, limits)

Establece los recursos limits de la quota de los root. Este método es parte de la extensión IMAP4 QUOTA definida en rfc2087.

IMAP4.shutdown()

Cierra la conexión establecida en open. Este método es llamado implícitamente por IMAP4.logout(). Podemos sobrescribir este método.

IMAP4.socket()

Retorna la instancia de socket utilizada para conectarse al servidor.

IMAP4.sort(sort_criteria, charset, search_criterion[, ...])

El comando sort es una variante de search con semántica de clasificación para los resultados. Los datos retornados contienen una lista separada por espacios de números de mensajes coincidentes.

Sort tiene dos argumentos antes del argumento (s) search_criterion; una lista entre paréntesis de sort_criteria, y la búsqueda del charset. Tenga en cuenta que, a diferencia de search, el argumento de búsqueda charset es obligatorio. También hay un comando uid sort que corresponde a sort de la misma manera que uid search corresponde a search. El comando sort primero busca en el buzón de correo mensajes que coincidan con los criterios de búsqueda dados utilizando el argumento charset para la interpretación de cadenas de caracteres en los criterios de búsqueda. Luego retorna los números de mensajes coincidentes.

Este es un comando de extensión IMAP4rev1.

IMAP4.starttls(ssl_context=None)

Envía un comando STARTTLS. El argumento ssl_context es opcional y debe ser un objeto ssl.SSLContext. Esto habilitará el cifrado en la conexión IMAP. Leer Consideraciones de seguridad para conocer las mejores prácticas.

Nuevo en la versión 3.2.

Distinto en la versión 3.4: El método ahora admite la verificación del nombre de host con ssl.SSLContext.check_hostname y Server Name Indication (ver ssl.HAS_SNI).

IMAP4.status(mailbox, names)

Solicita condiciones de estado con nombre para mailbox.

IMAP4.store(message_set, command, flag_list)

Altera las disposiciones de los indicadores para los mensajes en el buzón de correo. command esta especificado en la sección 6.4.6 de RFC 2060 [https://tools.ietf.org/html/rfc2060.html] siendo como uno de «FLAGS», «+FLAGS» o «-FLAGS», opcionalmente con un sufijo «.SILENT».

Por ejemplo, para establecer el indicador de eliminación en todos los mensajes:

typ, data = M.search(None, 'ALL')
for num in data[0].split():
   M.store(num, '+FLAGS', '\\Deleted')
M.expunge()

Nota

Crear indicadores que contengan “]” (por ejemplo: «[test]») viola RFC 3501 [https://tools.ietf.org/html/rfc3501.html] (el protocolo IMAP). Sin embargo, imaplib ha permitido históricamente la creación de tales etiquetas, y los servidores IMAP populares, como Gmail, aceptan y producen tales indicadores. Hay programas que no son de Python que también crean tales etiquetas. Aunque es una violación de RFC y se supone que los clientes y servidores IMAP son estrictos, imaplib continúa permitiendo que tales etiquetas se creen por razones de compatibilidad con versiones anteriores y, a partir de Python 3.6, las maneja si se envían desde el servidor, ya que esto mejora la compatibilidad en el mundo real.

IMAP4.subscribe(mailbox)

Suscribe al nuevo buzón de correo.

IMAP4.thread(threading_algorithm, charset, search_criterion[, ...])

El comando thread es una variante de search con semántica de hilos para los resultados. Los datos retornados contienen una lista de miembros de hilos separados por espacios.

Los miembros de del hilo (thread) consisten en cero o más números de mensajes, delimitados por espacios, que indican sucesivos padres e hijos.

Thread tiene dos argumentos antes del argumento (s) search_criterion; un threading_algorithm, y la búsqueda del charset. Tenga en cuenta que, a diferencia de search, el argumento de búsqueda charset es obligatorio. También hay un comando uid thread que corresponde a thread de la misma manera que uid search corresponde a search. El comando thread primero busca en el buzón de correo mensajes que coincidan con los criterios de búsqueda dados utilizando el argumento charset para la interpretación de cadenas de caracteres en los criterios de búsqueda. Luego retorna los mensajes coincidentes enfilados según el algoritmo de subproceso especificado.

Este es un comando de extensión IMAP4rev1.

IMAP4.uid(command, arg[, ...])

Ejecuta argumentos de comando con mensajes identificados por UID, en lugar de número de mensaje. Retorna la respuesta apropiada al comando. Se debe proporcionar al menos un argumento; Si no se proporciona ninguno, el servidor retornará un error y se lanzará una excepción.

IMAP4.unsubscribe(mailbox)

Darse de baja del antiguo buzón de correo.

IMAP4.unselect()

imaplib.IMAP4.unselect() libera recursos del servidor asociados al buzón de correo seleccionado y devuelve el servidor al estado autenticado. Este comando realiza las mismas acciones que imaplib.IMAP4.close(), con la excepción de que ningún mensaje es permanentemente borrado del buzón de correo actualmente seleccionado.

Nuevo en la versión 3.9.

IMAP4.xatom(name[, ...])

Permite comandos de extensión simples notificados por el servidor en la respuesta CAPABILITY.

Los siguientes atributos se definen en instancias de IMAP4:

IMAP4.PROTOCOL_VERSION

El protocolo mas recientemente admitido en la respuesta CAPABILITY desde el servidor.

IMAP4.debug

Valor entero para controlar la salida de depuración. El valor de inicialización se toma de la variable del módulo Debug. Valores mayores de tres rastrean cada comando.

IMAP4.utf8_enabled

Valor booleano que normalmente es False, pero se establece en True si un comando enable() es exitosamente emitido para la capacidad UTF8=ACCEPT.

Nuevo en la versión 3.5.

Ejemplo IMAP4

Aquí hay un ejemplo mínimo (sin verificación de errores) que abre un buzón de correo y recupera e imprime todos los mensajes:

import getpass, imaplib

M = imaplib.IMAP4()
M.login(getpass.getuser(), getpass.getpass())
M.select()
typ, data = M.search(None, 'ALL')
for num in data[0].split():
    typ, data = M.fetch(num, '(RFC822)')
    print('Message %s\n%s\n' % (num, data[0][1]))
M.close()
M.logout()

smtplib — Cliente de protocolo SMTP

Código fuente: Lib/smtplib.py [https://github.com/python/cpython/tree/3.9/Lib/smtplib.py]

El módulo smtplib define un objeto de sesión de cliente SMTP que se puede usar para mandar correo a cualquier máquina de Internet con un demonio de escucha SMTP o ESMTP. Para detalles sobre el funcionamiento de SMTP o ESMTP, consulta RFC 821 [https://tools.ietf.org/html/rfc821.html] (Simple Mail Transfer Protocol) y RFC 1869 [https://tools.ietf.org/html/rfc1869.html] (Extensiones de Servicio SMTP).

class smtplib.SMTP(host='', port=0, local_hostname=None, [timeout, ]source_address=None)

Una instancia SMTP encapsula una conexión SMTP. Tiene métodos que admiten un repertorio completo de operaciones SMTP y ESMTP. Si se proporcionan los parámetros opcionales de host y puerto, el método connect() de SMTP se llama con esos parámetros durante la inicialización. Si se especifica, local_hostname se usa como FQDN del host local in el comando HELO/EHLO. De lo contrario, el hostname local se busca usando socket.getfqdn(). Si la llamada a connect() retorna cualquier cosa que no sea un código de éxito, se lanza un SMTPConnectError. El parámetro timeout opcional especifica un timeout en segundos para bloquear operaciones como el intento de conexión (si no se especifica, se utilizará la configuración global del timeout por defecto). Si el timeout de espera expira, se lanza socket.timeout. El parámetro opcional source_address permite el enlace a alguna dirección de origen específica en una máquina con múltiples interfaces de red, y/o a algún puerto TCP de origen específico. Se necesita una tupla de 2 (host, puerto), para que el socket se enlace como su dirección de origen antes de conectarse. Si se omite (os si el host o el puerto son '' y/o 0 respectivamente) se utilizara el comportamiento por defecto del SO.

Para un uso normal, solo debe requerir los métodos initialization/connect, sendmail() y SMTP.quit(). A continuación se incluye un ejemplo.

La clase SMTP admite la instrucción with. Cuando se usa así, el comando SMTP QUIT se emite automáticamente cuando la with sale de la instrucción. por ejemplo:

>>> from smtplib import SMTP
>>> with SMTP("domain.org") as smtp:
...     smtp.noop()
...
(250, b'Ok')
>>>

Genera un auditing event smtplib.send con argumentos self, data.

Distinto en la versión 3.3: Se agregó soporte para la sentencia with.

Distinto en la versión 3.3: se agrego el argumento source_address.

Nuevo en la versión 3.5: La extensión SMTPUTF8 (RFC 6531 [https://tools.ietf.org/html/rfc6531.html]) ahora es compatible.

Distinto en la versión 3.9: Si el parámetro timeout se mantiene en cero, lanzará un ValueError para evitar la creación de un socket no bloqueante

class smtplib.SMTP_SSL(host='', port=0, local_hostname=None, keyfile=None, certfile=None, [timeout, ]context=None, source_address=None)

Una instancia de SMTP_SSL se comporta exactamente igual que las instancias de SMTP. SMTP_SSL debe usarse para situaciones donde se requiere SSL desde el comienzo de la conexión y el uso starttls() no es apropiado. Si no se especifica host, se utiliza el host local. Si port es cero, se utiliza el puerto estándar SMTP sobre SSL (465). Los argumentos opcionales local_hostname, timeout y source_address tienen el mismo significado que en la clase SMTP. context, también opcional, puede contener una SSLContext y permite configurar varios aspectos de la conexión segura. Por favor lea Consideraciones de seguridad para conocer las mejores prácticas.

keyfile y certfile son una alternativa heredada a context y pueden apuntar a una clave privada con formato PEM y un archivo de cadena de certificados para la conexión SSL.

Distinto en la versión 3.3: se agregó contexto.

Distinto en la versión 3.3: se agrego el argumento source_address.

Distinto en la versión 3.4: La clase ahora admite la verificación del nombre de host con ssl.SSLContext.check_hostname y Server Name Indication (ver ssl.HAS_SNI).

Obsoleto desde la versión 3.6: keyfile y certfile están obsoletos en favor de context. Por favor use ssl.SSLContext.load_cert_chain() en su lugar, o deje que ssl.create_default_context() seleccione los certificados CA confiables del sistema para usted.

Distinto en la versión 3.9: Si el parámetro timeout se mantiene en cero, lanzará un ValueError para evitar la creación de un socket no bloqueante

class smtplib.LMTP(host='', port=LMTP_PORT, local_hostname=None, source_address=None[, timeout])

El protocolo LMTP, que es muy similar a ESMTP, se basa en gran medida en el cliente SMTP estándar. Es común usar sockets Unix para LMTP, por lo que nuestro método connect() debe ser compatible con eso, así como con un servidor host:puerto normal. Los argumentos opcionales local_hostname y source_address tienen el mismo significado que en la clase SMTP. Para especificar un socket Unix, debe usar una ruta absoluta para host, comenzando con “/”.

Se admite la autenticación mediante el mecanismo SMTP habitual. Cuando se usa un socket Unix, LMTP generalmente no admite ni requiere autenticación, pero su millaje puede variar.

Distinto en la versión 3.9: Se ha añadido el parámetro opcional timeout.

También se define una buena selección de excepciones:

exception smtplib.SMTPException

Subclase de OSError que es la clase de excepción base para todas las demás excepciones proporcionadas por este módulo.

Distinto en la versión 3.4: SMTPException se convirtió en subclase de OSError

exception smtplib.SMTPServerDisconnected

Esta excepción se genera cuando el servidor se desconecta inesperadamente o cuando se intenta usar la instancia SMTP antes de conectarlo a un servidor.

exception smtplib.SMTPResponseException

Clase base para todas las excepciones que incluyen un código de error SMTP. Estas excepciones se generan en algunos casos cuando el servidor SMTP devuelve un código de error. El código de error se almacena en el atributo smtp_code del error, y el atributo smtp_error se establece en el mensaje de error.

exception smtplib.SMTPSenderRefused

Dirección del remitente rechazada. Además de los atributos establecidos por todas las excepciones SMTPResponseException, éste establece “remitente” para la cadena de caracteres que el servidor SMTP rechazó.

exception smtplib.SMTPRecipientsRefused

Se rechazaron todas las direcciones de destinatarios. Los errores para cada destinatario son accesibles mediante el atributo recipients, el cual es un diccionario del mismo tipo que el SMTP.sendmail() retorna.

exception smtplib.SMTPDataError

El servidor SMTP se negó a aceptar los datos del mensaje.

exception smtplib.SMTPConnectError

Se produjo un error durante el establecimiento de conexión con el servidor.

exception smtplib.SMTPHeloError

El servidor rechazó nuestro mensaje HELO.

exception smtplib.SMTPNotSupportedError

El servidor no admite el comando o la opción que se intentó.

Nuevo en la versión 3.5.

exception smtplib.SMTPAuthenticationError

La autenticación SMTP salió mal. Lo más probable es que el servidor no aceptó la combinación proporcionada de username/password.

Ver también

RFC 821 [https://tools.ietf.org/html/rfc821.html] - Simple Mail Transfer Protocol

Definición de protocolo para SMTP. Este documento cubre el modelo, el procedimiento operativo y los detalles del protocolo para SMTP.

RFC 1869 [https://tools.ietf.org/html/rfc1869.html] - Extensiones de Servicio SMTP

Definición de las extensiones ESMTP para SMTP. Esto describe un marco para extender SMTP con nuevos comandos, que admite el descubrimiento dinámico de los comandos proporcionados por el servidor y define algunos comandos adicionales.

Objetos SMTP

Una instancia SMTP tiene los siguientes métodos:

SMTP.set_debuglevel(level)

Establezca el nivel de salida de depuración. Un valor de 1 o True para level da como resultado mensajes de depuración para la conexión y para todos los mensajes enviados y recibidos desde el servidor. Un valor de 2 para level da como resultado que estos mensajes tengan una marca de tiempo.

Distinto en la versión 3.5: Se agregó el nivel de depuración 2.

SMTP.docmd(cmd, args='')

Envíe un comando cmd al servidor. El argumento opcional args simplemente se concatena al comando, separado por un espacio.

Esto devuelve una tupla de 2 compuestos por un código de respuesta numérico y la línea de respuesta real (las respuestas de varias líneas se unen en una línea larga).

En funcionamiento normal, no debería ser necesario llamar a este método explícitamente. Se utiliza para implementar otros métodos y puede resultar útil para probar extensiones privadas.

Si se pierde la conexión con el servidor mientras se espera la respuesta, se activará SMTPServerDisconnected.

SMTP.connect(host='localhost', port=0)

Conéctese a un host en un puerto determinado. Los valores predeterminados son para conectarse al host local en el puerto SMTP estándar (25). Si el nombre de host termina con dos puntos (':') seguido de un número, ese sufijo se eliminará y el número se interpretará como el número de puerto a utilizar. El constructor invoca automáticamente este método si se especifica un host durante la instanciación. Devuelve una tupla de 2 del código de respuesta y el mensaje enviado por el servidor en su respuesta de conexión.

Genera un evento de auditoría smtplib.connect con argumentos self, host, port.

SMTP.helo(name='')

Identifíquese en el servidor SMTP usando HELO. El argumento del nombre de host tiene como valor predeterminado el nombre de dominio completo del host local. El mensaje devuelto por el servidor se almacena como el atributo helo_resp del objeto.

En funcionamiento normal, no debería ser necesario llamar a este método explícitamente. Será llamado implícitamente por sendmail() cuando sea necesario.

SMTP.ehlo(name='')

Identifíquese en un servidor ESMTP usando EHLO. El argumento del nombre de host tiene como valor predeterminado el nombre de dominio completo del host local. Examine la respuesta para la opción ESMTP y guárdelos para que los use has_extn(). También establece varios atributos informativos: el mensaje devuelto por el servidor se almacena como el atributo ehlo_resp, does_esmtp se establece en verdadero o falso dependiendo de si el servidor admite ESMTP, y esmtp_features será un diccionario que contiene los nombres de las extensiones de servicio SMTP que admite este servidor, y sus parámetros (si los hay).

A menos que desee utilizar has_extn() antes de enviar correo, no debería ser necesario llamar a este método explícitamente. Se llamará implícitamente por sendmail() cuando sea necesario.

SMTP.ehlo_or_helo_if_needed()

Este método llama a ehlo() o helo() si no ha habido ningún comando EHLO o HELO anterior en esta sesión. Primero prueba ESMTP EHLO.

SMTPHeloError

El servidor no respondió correctamente al saludo HELO.

SMTP.has_extn(name)

Retorna True si name está en el conjunto de extensiones de servicio SMTP devueltas por el servidor, False en caso contrario. El método es insensible a la presencia de mayúsculas en name.

SMTP.verify(address)

Verifique la validez de una dirección en este servidor usando SMTP VRFY. Retorna una tupla que consta del código 250 y una dirección completa RFC 822 [https://tools.ietf.org/html/rfc822.html] (incluido el nombre humano) si la dirección del usuario es válida. De lo contrario, devuelve un código de error SMTP de 400 o más y una cadena de error.

Nota

Muchos sitios desactivan SMTP VRFY para frustrar a los spammers.

SMTP.login(user, password, *, initial_response_ok=True)

Inicie sesión en un servidor SMTP que requiera autenticación. Los argumentos son el nombre de usuario y la contraseña para autenticarse. Si no ha habido ningún comando EHLO o HELO anterior en esta sesión, este método prueba primero ESMTP EHLO. Este método regresará normalmente si la autenticación fue exitosa o puede generar las siguientes excepciones:

SMTPHeloError

El servidor no respondió correctamente al saludo HELO.

SMTPAuthenticationError

El servidor no aceptó la combinación de nombre de username/password.

SMTPNotSupportedError

El servidor no admite el comando AUTH.

SMTPException

No se encontró ningún método de autenticación adecuado.

Cada uno de los métodos de autenticación admitidos por smtplib se prueban a su vez si se anuncian como admitidos por el servidor. Consulte auth() para obtener una lista de los métodos de autenticación admitidos. initial_response_ok se pasa a auth().

El argumento de palabra clave opcional initial_response_ok especifica si, para los métodos de autenticación que lo admiten, se puede enviar una «respuesta inicial» como se especifica en RFC 4954 [https://tools.ietf.org/html/rfc4954.html] junto con el comando AUTH, en lugar de requerir un desafío/respuesta .

Distinto en la versión 3.5: SMTPNotSupportedError se puede generar y se agregó el parámetro initial_response_ok.

SMTP.auth(mechanism, authobject, *, initial_response_ok=True)

Emita un comando SMTP AUTH para el mechanism de autenticación especificado y maneje la respuesta de desafío a través de authobject.

mechanism especifica qué mecanismo de autenticación se utilizará como argumento para el comando AUTH; los valores válidos son los enumerados en el elemento auth de esmtp_features.

authobject debe ser un objeto invocable que tome un único argumento opcional:

data = authobject(challenge=None)

Si la verificación de respuesta inicial devuelve None, o si initial_response_ok es falso, se llamará a authobject() para procesar la respuesta de desafío del servidor; el argumento challenge que se pasa será un bytes. Debería devolver data ASCII str que serán codificados en base64 y enviados al servidor.

Si la verificación de respuesta inicial devuelve None, o si initial_response_ok es falso, se llamará a authobject() para procesar la respuesta de desafío del servidor; el argumento challenge que se pasa será un bytes. Debería devolver data ASCII str que serán codificados en base64 y enviados al servidor.

La clase SMTP proporciona authobjects para los mecanismos CRAM-MD5, PLAIN y LOGIN; se denominan SMTP.auth_cram_md5, SMTP.auth_plain y SMTP.auth_login respectivamente. Todos requieren que las propiedades de user y password de la instancia SMTP se establezcan en los valores adecuados.

El código de usuario normalmente no necesita llamar a auth directamente, sino que puede llamar al método login(), que probará cada uno de los mecanismos anteriores a su vez, en el orden indicado. auth está expuesto para facilitar la implementación de métodos de autenticación que no (o aún no) son compatibles directamente con smtplib.

Nuevo en la versión 3.5.

SMTP.starttls(keyfile=None, certfile=None, context=None)

Ponga la conexión SMTP en modo TLS (Seguridad de la capa de transporte). Todos los comandos SMTP que siguen se cifrarán. Entonces deberías llamar a ehlo() de nuevo.

Si se proporcionan keyfile y certfile, se utilizan para crear una ssl.SSLContext.

El parámetro context opcional es un objeto ssl.SSLContext; Esta es una alternativa al uso de un archivo de claves y un archivo de certificado y, si se especifica, tanto keyfile como certfile deben ser None.

Si no ha habido ningún comando EHLO o HELO anterior en esta sesión, este método intenta ESMTP EHLO primero.

Obsoleto desde la versión 3.6: keyfile y certfile están obsoletos en favor de context. Por favor use ssl.SSLContext.load_cert_chain() en su lugar, o deje que ssl.create_default_context() seleccione los certificados CA confiables del sistema para usted.

SMTPHeloError

El servidor no respondió correctamente al saludo HELO.

SMTPNotSupportedError

El servidor no admite la extensión STARTTLS.

RuntimeError

La compatibilidad con SSL/TLS no está disponible para su intérprete de Python.

Distinto en la versión 3.3: se agregó contexto.

Distinto en la versión 3.4: El método ahora admite la verificación del nombre de host con SSLContext.check_hostname y Server Name Indicator (ver HAS_SNI).

Distinto en la versión 3.5: El error generado por falta de compatibilidad con STARTTLS ahora es la subclase SMTPNotSupportedError en lugar de la base SMTPException.

SMTP.sendmail(from_addr, to_addrs, msg, mail_options=(), rcpt_options=())

Enviar correo. Los argumentos requeridos son RFC 822 [https://tools.ietf.org/html/rfc822.html] cadena de dirección de origen, una lista de RFC 822 [https://tools.ietf.org/html/rfc822.html] cadenas de dirección (una cadena simple se tratará como una lista con 1 dirección) y una cadena de mensaje. La persona que llama puede pasar una lista de opciones de ESMTP (como 8bitmime) para usar en los comandos MAIL FROM como mail_options. Las opciones de ESMTP (como los comandos DSN) que deben usarse con todos los comandos RCPT se pueden pasar como rcpt_options. (Si necesita usar diferentes opciones de ESMTP para diferentes destinatarios, debe usar los métodos de bajo nivel como mail(), rcpt() y data() para enviar el mensaje).

Nota

Los parámetros from_addr y to_addrs se utilizan para construir el sobre del mensaje utilizado por los agentes de transporte. sendmail no modifica los encabezados de los mensajes de ninguna manera.

msg puede ser una cadena que contenga caracteres en el rango ASCII o una cadena de bytes. Una cadena se codifica en bytes utilizando el códec ascii, y los caracteres \r y \n solitarios se convierten en caracteres \ r\n. Una cadena de bytes no se modifica.

Si no ha habido ningún comando EHLO o HELO anterior en esta sesión, este método prueba primero ESMTP EHLO. Si el servidor utiliza ESMTP, se le pasará el tamaño del mensaje y cada una de las opciones especificadas (si la opción está en el conjunto de funciones que anuncia el servidor). Si EHLO falla, se probará HELO y se eliminarán las opciones de ESMTP.

Este método volverá normalmente si se acepta el correo para al menos un destinatario. De lo contrario, generará una excepción. Es decir, si este método no genera una excepción, alguien debería recibir su correo. Si este método no genera una excepción, devuelve un diccionario, con una entrada para cada destinatario rechazado. Cada entrada contiene una tupla del código de error SMTP y el mensaje de error adjunto enviado por el servidor.

Si se incluye SMTPUTF8” en mail_options * y el servidor lo admite, *from_addr y to_addrs pueden contener caracteres no ASCII.

Este método puede lanzar las siguientes excepciones:

SMTPRecipientsRefused

Todos los destinatarios fueron rechazados. Nadie recibió el correo. El atributo recipients del objeto de excepción es un diccionario con información sobre los destinatarios rechazados (como el que se retorna cuando se aceptó al menos un destinatario).

SMTPHeloError

El servidor no respondió correctamente al saludo HELO.

SMTPSenderRefused

El servidor no aceptó el from_addr.

SMTPDataError

El servidor respondió con un código de error inesperado (que no sea el rechazo de un destinatario).

SMTPNotSupportedError

Se proporcionó SMTPUTF8 en mail_options pero el servidor no lo admite.

A menos que se indique lo contrario, la conexión estará abierta incluso después de que se lance una excepción.

Distinto en la versión 3.2: msg puede ser una cadena de bytes.

Distinto en la versión 3.5: Se agregó compatibilidad con SMTPUTF8, y SMTPNotSupportedError puede aparecer si se especifica SMTPUTF8 pero el servidor no lo admite.

SMTP.send_message(msg, from_addr=None, to_addrs=None, mail_options=(), rcpt_options=())

Este es un método conveniente para llamar a sendmail() con el mensaje representado por un objeto email.message.Message. Los argumentos tienen el mismo significado que para sendmail(), excepto que msg es un objeto Mensaje.

Si from_addr es None o to_addrs es None, send_message llena esos argumentos con direcciones extraídas de los encabezados de msg como se especifica en RFC 5322 [https://tools.ietf.org/html/rfc5322.html]: from_addr se establece en el campo Sender si está presente, y de lo contrario, en el campo From. to_addrs combina los valores (si los hay) de los campos To, Cc y Bcc de msg. Si aparece exactamente un conjunto de encabezados Resent-* en el mensaje, los encabezados normales se ignoran y en su lugar se utilizan los encabezados Resent- *. Si el mensaje contiene más de un conjunto de encabezados Resent-*, se lanza un ValueError, ya que no hay forma de detectar sin ambigüedades el conjunto más reciente de encabezados Resent-.

send_message serializa msg usando BytesGenerator con``r n`` como linesep, y llama a sendmail() para transmitir el mensaje resultante. Independientemente de los valores de from_addr y to_addrs, send_message no transmite ningún encabezado Bcc o Resent-Bcc que puedan aparecer en msg. Si alguna de las direcciones en from_addr y to_addrs contiene caracteres que no son ASCII y el servidor no anuncia la compatibilidad con SMTPUTF8, se lanza un error SMTPNotSupported. De lo contrario, el Message se serializa con un clon de su policy con el atributo utf8 establecido en True y SMTPUTF8 y BODY=8BITMIME se agregan a mail_options.

Nuevo en la versión 3.2.

Nuevo en la versión 3.5: Soporte para direcciones internacionalizadas (SMTPUTF8).

SMTP.quit()

Termine la sesión SMTP y cierre la conexión. Retorna el resultado del comando SMTP QUIT.

Los métodos de bajo nivel correspondientes a los comandos estándar SMTP/ESMTP `HELP, RSET, NOOP, MAIL, RCPT, y DATA también están soportados. Normalmente, no es necesario llamarlos directamente, por lo que no se documentan aquí. Para más detalles, consulte el código del módulo.

Ejemplo SMTP

Este ejemplo solicita al usuario las direcciones necesarias en el sobre del mensaje (direcciones “To” y “From” ) y el mensaje que se entregará. Tenga en cuenta que los encabezados que se incluirán con el mensaje deben incluirse en el mensaje tal y como se introdujeron; este ejemplo no procesa los encabezados RFC 822 [https://tools.ietf.org/html/rfc822.html] . En particular, las direcciones “To” y “From deben incluirse explícitamente en los encabezados de los mensajes.

import smtplib

def prompt(prompt):
    return input(prompt).strip()

fromaddr = prompt("From: ")
toaddrs  = prompt("To: ").split()
print("Enter message, end with ^D (Unix) or ^Z (Windows):")

# Add the From: and To: headers at the start!
msg = ("From: %s\r\nTo: %s\r\n\r\n"
       % (fromaddr, ", ".join(toaddrs)))
while True:
    try:
        line = input()
    except EOFError:
        break
    if not line:
        break
    msg = msg + line

print("Message length is", len(msg))

server = smtplib.SMTP('localhost')
server.set_debuglevel(1)
server.sendmail(fromaddr, toaddrs, msg)
server.quit()

Nota

En general, querrá usar las características del paquete email para construir un mensaje de correo electrónico, que luego puede enviar a través de send_message(); ver email: Ejemplos.

uuid — objetos UUID según RFC 4122 [https://tools.ietf.org/html/rfc4122.html]

Código fuente: Lib/uuid.py [https://github.com/python/cpython/tree/3.9/Lib/uuid.py]

Este módulo proporciona objetos UUID inmutables (la clase UUID) y las funciones uuid1(), uuid3(), uuid4(), uuid5() para generar los UUID de las versiones 1, 3, 4 y 5 como se especifica en RFC 4122 [https://tools.ietf.org/html/rfc4122.html].

Si todo lo que quieres es una identificación única, probablemente deberías llamar a uuuid1() o uuid4(). Ten en cuenta que uuid1() puede comprometer la privacidad ya que crea un UUID que contiene la dirección de red del ordenador. uuid4() crea un UUID aleatorio.

Dependiendo del soporte de la plataforma subyacente, uuid1() puede o no retornar un UUID «seguro». Un UUID seguro es aquel que se genera mediante métodos de sincronización que aseguran que ningún proceso pueda obtener el mismo UUID. Todas las instancias de UUID tienen un atributo is_safe que transmite cualquier información sobre la seguridad del UUID, usando esta enumeración:

class uuid.SafeUUID

Nuevo en la versión 3.7.

safe

El UUID fue generado por la plataforma de una manera segura para multiprocesamiento.

unsafe

El UUID no fue generado por la plataforma de una manera segura de multiprocesamiento.

unknown

La plataforma no proporciona información sobre si el UUID se generó de forma segura o no.

class uuid.UUID(hex=None, bytes=None, bytes_le=None, fields=None, int=None, version=None, *, is_safe=SafeUUID.unknown)

Crea un UUID a partir de una cadena de 32 dígitos hexadecimales, una cadena de 16 bytes en orden big-endian como el argumento bytes, una cadena de 16 bytes en orden little-endian como el argumento bytes_le, una tupla de seis enteros (32-bit time_low, 16-bit time_mid, 16-bit time_hi_version, 8-bit clock_seq_hi_variant, 8-bit clock_seq_low, 48-bit node) como el argumento fields, o un solo entero de 128-bit como el argumento int. Cuando se da una cadena de dígitos hexadecimales, los corchetes, los guiones y el prefijo URN son todos opcionales. Por ejemplo, todas estas expresiones producen el mismo UUID:

UUID('{12345678-1234-5678-1234-567812345678}')
UUID('12345678123456781234567812345678')
UUID('urn:uuid:12345678-1234-5678-1234-567812345678')
UUID(bytes=b'\x12\x34\x56\x78'*4)
UUID(bytes_le=b'\x78\x56\x34\x12\x34\x12\x78\x56' +
              b'\x12\x34\x56\x78\x12\x34\x56\x78')
UUID(fields=(0x12345678, 0x1234, 0x5678, 0x12, 0x34, 0x567812345678))
UUID(int=0x12345678123456781234567812345678)

Exactamente uno de hex, bytes, bytes_le, fields, o int debe ser dado. El argumento version es opcional; si se da, el UUID resultante tendrá su variante y número de versión establecidos de acuerdo con RFC 4122 [https://tools.ietf.org/html/rfc4122.html], anulando los bits en la hex, bytes, bytes_le, fields, o int dados.

La comparación de los objetos UUID se hace mediante la comparación de sus atributos UID.int. La comparación con un objeto no UUID produce un TypeError.

str(uuid) retorna una cadena en la forma 12345678-1234-5678-1234-567812345678 donde los 32 dígitos hexadecimales representan el UUID.

Las instancias de UUID tienen estos atributos de sólo lectura:

UUID.bytes

El UUID como una cadena de 16 bytes (que contiene los seis campos enteros en orden de bytes big-endian).

UUID.bytes_le

El UUID como una cadena de 16 bytes (con time_low, time_mid, y time_hi_version en el orden de bytes little-endian).

UUID.fields

Una tupla de los seis campos enteros de la UUID, que también están disponibles como seis atributos individuales y dos atributos derivados:

Campo

Significado

time_low

los primeros 32 bits del UUID

time_mid

los siguientes 16 bits del UUID

time_hi_version

los siguientes 16 bits del UUID

clock_seq_hi_variant

los siguientes 8 bits del UUID

clock_seq_low

los siguientes 8 bits del UUID

node

los siguientes 48 bits del UUID

time

el timestamp de 60-bit

clock_seq

el número de secuencia de 14-bit

UUID.hex

The UUID as a 32-character lowercase hexadecimal string.

UUID.int

El UUID como un entero de 128 bits.

UUID.urn

El UUID como URN como se especifica en RFC 4122 [https://tools.ietf.org/html/rfc4122.html].

UUID.variant

La variante UUID, que determina la disposición interna del UUID. Esta será una de las constantes RESERVED_NCS, RFC_4122, RESERVED_MICROSOFT, o RESERVED_FUTURE.

UUID.version

El número de versión UUID (del 1 al 5, significativo sólo cuando la variante es RFC_4122).

UUID.is_safe

Una enumeración de SafeUUID que indica si la plataforma generó el UUID de forma segura para el multiprocesamiento.

Nuevo en la versión 3.7.

El módulo uuid define las siguientes funciones:

uuid.getnode()

Obtiene la dirección del hardware como un entero positivo de 48 bits. La primera vez que esto se ejecute, puede lanzar un programa separado, que podría ser bastante lento. Si todos los intentos de obtener la dirección de hardware fallan, elegimos un número aleatorio de 48 bits con el bit multicast (el bit menos significativo del primer octeto) puesto a 1 como se recomienda en RFC 4122 [https://tools.ietf.org/html/rfc4122.html]. «Dirección de hardware» significa la dirección MAC de una interfaz de red. En una máquina con múltiples interfaces de red, las direcciones MAC administradas universalmente (es decir, donde el segundo bit menos significativo del primer octeto es unset) se preferirán a las direcciones MAC administradas localmente, pero sin otras garantías de orden.

Distinto en la versión 3.7: Se prefieren las direcciones MAC administradas universalmente a las administradas localmente, ya que se garantiza que las primeras son únicas a nivel mundial, mientras que las segundas no lo son.

uuid.uuid1(node=None, clock_seq=None)

Genera un UUID a partir de un ID de host, número de secuencia y la hora actual. Si no se da node, se usa getnode() para obtener la dirección del hardware. Si se da clock_seq, se utiliza como número de secuencia; de lo contrario se elige un número de secuencia aleatorio de 14 bits.

uuid.uuid3(namespace, name)

Genera un UUID basado en el hash MD5 de un identificador de espacio de nombres (que es un UUID) y un nombre (que es una cadena).

uuid.uuid4()

Genera un UUID aleatorio.

uuid.uuid5(namespace, name)

Genera un UUID basado en el hash SHA-1 de un identificador de espacio de nombres (que es un UUID) y un nombre (que es una cadena).Generar un UUID basado en el hash SHA-1 de un identificador de espacio de nombres (que es un UUID) y un nombre (que es una cadena).

El módulo uuuid define los siguientes identificadores de espacios de nombres para su uso con uuid3() o uuuid5().

uuid.NAMESPACE_DNS

Cuando se especifica este espacio de nombres, la cadena name es un nombre de dominio completamente calificado.

uuid.NAMESPACE_URL

Cuando se especifica este espacio de nombres, la cadena name es una URL.

uuid.NAMESPACE_OID

Cuando se especifica este espacio de nombres, la cadena name es un OID ISO.

uuid.NAMESPACE_X500

Cuando se especifica este espacio de nombres, la cadena name es un X.500 DN en DER o un formato de salida de texto.

El módulo uuid define las siguientes constantes para los posibles valores del atributo variant:

uuid.RESERVED_NCS

Reservado para la compatibilidad con NCS.

uuid.RFC_4122

Especifica el diseño del UUID dado en RFC 4122 [https://tools.ietf.org/html/rfc4122.html].

uuid.RESERVED_MICROSOFT

Reservado para la compatibilidad con Microsoft.

uuid.RESERVED_FUTURE

Reservado para una futura definición.

Ver también

RFC 4122 [https://tools.ietf.org/html/rfc4122.html] - Un espacio de nombres URN de identificador único universal (UUID)

Esta especificación define un espacio de nombres de recursos uniforme para los UUID, el formato interno de los UUID y los métodos de generación de los UUID.

Ejemplo

Aquí hay algunos ejemplos del uso típico del modulo uuid:

>>> import uuid

>>> # make a UUID based on the host ID and current time
>>> uuid.uuid1()
UUID('a8098c1a-f86e-11da-bd1a-00112444be1e')

>>> # make a UUID using an MD5 hash of a namespace UUID and a name
>>> uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org')
UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e')

>>> # make a random UUID
>>> uuid.uuid4()
UUID('16fd2706-8baf-433b-82eb-8c7fada847da')

>>> # make a UUID using a SHA-1 hash of a namespace UUID and a name
>>> uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org')
UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d')

>>> # make a UUID from a string of hex digits (braces and hyphens ignored)
>>> x = uuid.UUID('{00010203-0405-0607-0809-0a0b0c0d0e0f}')

>>> # convert a UUID to a string of hex digits in standard form
>>> str(x)
'00010203-0405-0607-0809-0a0b0c0d0e0f'

>>> # get the raw 16 bytes of the UUID
>>> x.bytes
b'\x00\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f'

>>> # make a UUID from a 16-byte string
>>> uuid.UUID(bytes=x.bytes)
UUID('00010203-0405-0607-0809-0a0b0c0d0e0f')

socketserver — Un framework para servidores de red

Código fuente: Lib/socketserver.py [https://github.com/python/cpython/tree/3.9/Lib/socketserver.py]

El módulo socketserver simplifica la tarea de escribir servidores de red.

Hay cuatro clases básicas de servidores concretos:

class socketserver.TCPServer(server_address, RequestHandlerClass, bind_and_activate=True)

Utiliza el protocolo TCP de Internet, que proporciona flujos continuos de datos entre el cliente y el servidor. Si bind_and_activate es verdadero, el constructor automáticamente intenta invocar a server_bind() y server_activate(). Los otros parámetros se pasan a la clase base BaseServer.

class socketserver.UDPServer(server_address, RequestHandlerClass, bind_and_activate=True)

Esto utiliza datagramas, que son paquetes discretos de información que pueden llegar fuera de servicio o perderse durante el tránsito. Los parámetros son los mismos que para TCPServer.

class socketserver.UnixStreamServer(server_address, RequestHandlerClass, bind_and_activate=True)

class socketserver.UnixDatagramServer(server_address, RequestHandlerClass, bind_and_activate=True)

Estas clases que se usan con menos frecuencia son similares a las clases TCP y UDP, pero usan sockets de dominio Unix; no están disponibles en plataformas que no sean Unix. Los parámetros son los mismos que para TCPServer.

Estas cuatro clases procesan solicitudes sincrónicamente; cada solicitud debe completarse antes de que se pueda iniciar la siguiente. Esto no es adecuado si cada solicitud tarda mucho en completarse, porque requiere mucho cálculo o porque retorna muchos datos que el cliente tarda en procesar. La solución es crear un proceso o hilo independiente para manejar cada solicitud; las clases mixtas ForkingMixIn y ThreadingMixIn pueden usarse para soportar el comportamiento asincrónico.

La creación de un servidor requiere varios pasos. Primero, debes crear una clase de controlador de solicitudes subclasificando la clase BaseRequestHandler y anulando su método handle(); este método procesará las solicitudes entrantes. En segundo lugar, debe crear una instancia de una de las clases de servidor, pasándole la dirección del servidor y la clase del controlador de solicitudes. Se recomienda utilizar el servidor en una declaración with. Luego llame al método handle_request() o serve_forever() del objeto de servidor para procesar una o muchas solicitudes. Finalmente, llame a server_close() para cerrar el socket (a menos que haya usado una with declaración).

Al heredar de ThreadingMixIn para el comportamiento de la conexión con subprocesos, debe declarar explícitamente cómo desea que se comporten sus subprocesos en un cierre abrupto. La clase ThreadingMixIn define un atributo daemon_threads, que indica si el servidor debe esperar o no la terminación del hilo. Debe establecer la bandera explícitamente si desea que los subprocesos se comporten de forma autónoma; el valor predeterminado es False, lo que significa que Python no se cerrará hasta que todos los hilos creados por ThreadingMixIn hayan salido.

Las clases de servidor tienen los mismos métodos y atributos externos, independientemente del protocolo de red que utilicen.

Notas de creación del servidor

Hay cinco clases en un diagrama de herencia, cuatro de las cuales representan servidores síncronos de cuatro tipos:

+------------+
| BaseServer |
+------------+
      |
      v
+-----------+        +------------------+
| TCPServer |------->| UnixStreamServer |
+-----------+        +------------------+
      |
      v
+-----------+        +--------------------+
| UDPServer |------->| UnixDatagramServer |
+-----------+        +--------------------+

Tenga en cuenta que UnixDatagramServer deriva de UDPServer, no de UnixStreamServer — la única diferencia entre una IP y un servidor de flujo Unix es la familia de direcciones, que simplemente se repite en ambos Clases de servidor Unix.

class socketserver.ForkingMixIn

class socketserver.ThreadingMixIn

Se pueden crear versiones de Forking y threading de cada tipo de servidor utilizando estas clases mixtas. Por ejemplo, ThreadingUDPServer se crea de la siguiente manera:

class ThreadingUDPServer(ThreadingMixIn, UDPServer):
    pass

La clase de mezcla es lo primero, ya que anula un método definido en UDPServer. La configuración de los distintos atributos también cambia el comportamiento del mecanismo del servidor subyacente.

ForkingMixIn y las clases de Forking mencionadas a continuación solo están disponibles en plataformas POSIX que admiten os.fork().

socketserver.ForkingMixIn.server_close() espera hasta que se completen todos los procesos secundarios, excepto si socketserver.ForkingMixIn.block_on_close atributo es falso.

socketserver.ThreadingMixIn.server_close() espera hasta que se completen todos los subprocesos que no son demonios, excepto si el atributo socketserver.ThreadingMixIn.block_on_close es falso. Use subprocesos demoníacos configurando ThreadingMixIn.daemon_threads en Verdadero para no esperar hasta que se completen los subprocesos.

Distinto en la versión 3.7: socketserver.ForkingMixIn.server_close() y socketserver.ThreadingMixIn.server_close() ahora espera hasta que se completen todos los procesos secundarios y los subprocesos no demoníacos. Agregue un nuevo atributo de clase socketserver.ForkingMixIn.block_on_close para optar por el comportamiento anterior a 3.7.

class socketserver.ForkingTCPServer

class socketserver.ForkingUDPServer

class socketserver.ThreadingTCPServer

class socketserver.ThreadingUDPServer

Estas clases están predefinidas utilizando las clases mixtas.

Para implementar un servicio, debes derivar una clase de BaseRequestHandler y redefinir su método handle(). Luego, puede ejecutar varias versiones del servicio combinando una de las clases de servidor con su clase de controlador de solicitudes. La clase del controlador de solicitudes debe ser diferente para los servicios de datagramas o flujos. Esto se puede ocultar usando las subclases del controlador StreamRequestHandler o DatagramRequestHandler.

Por supuesto, ¡todavía tienes que usar la cabeza! Por ejemplo, no tiene sentido usar un servidor de bifurcación si el servicio contiene un estado en la memoria que puede ser modificado por diferentes solicitudes, ya que las modificaciones en el proceso hijo nunca alcanzarían el estado inicial que se mantiene en el proceso padre y se pasa a cada hijo. En este caso, puede usar un servidor de subprocesos, pero probablemente tendrá que usar bloqueos para proteger la integridad de los datos compartidos.

Por otro lado, si está creando un servidor HTTP donde todos los datos se almacenan externamente (por ejemplo, en el sistema de archivos), una clase síncrona esencialmente hará que el servicio sea «sordo» mientras se maneja una solicitud, que puede ser durante mucho tiempo si un cliente tarda en recibir todos los datos que ha solicitado. Aquí es apropiado un servidor de enhebrado o bifurcación.

En algunos casos, puede ser apropiado procesar parte de una solicitud de forma síncrona, pero para finalizar el procesamiento en un hijo bifurcado según los datos de la solicitud. Esto se puede implementar usando un servidor sincrónico y haciendo un fork explicito en la clase del controlador de solicitudes el método handle().

Otro enfoque para manejar múltiples solicitudes simultáneas en un entorno que no admite subprocesos ni fork() (o donde estos son demasiado costosos o inapropiados para el servicio) es mantener una tabla explícita de solicitudes parcialmente terminadas y utilizar selectors para decidir en qué solicitud trabajar a continuación (o si manejar una nueva solicitud entrante). Esto es particularmente importante para los servicios de transmisión en los que cada cliente puede potencialmente estar conectado durante mucho tiempo (si no se pueden utilizar subprocesos o subprocesos). Consulte asyncore para ver otra forma de gestionar esto.

Objetos de servidor

class socketserver.BaseServer(server_address, RequestHandlerClass)

Esta es la superclase de todos los objetos de servidor en el módulo. Define la interfaz, que se indica a continuación, pero no implementa la mayoría de los métodos, que se realiza en subclases. Los dos parámetros se almacenan en los atributos respectivos server_address y RequestHandlerClass.

fileno()

Retorna un descriptor de archivo entero para el socket en el que escucha el servidor. Esta función se pasa comúnmente a selectors, para permitir monitorear múltiples servidores en el mismo proceso.

handle_request()

Procese una sola solicitud. Esta función llama a los siguientes métodos en orden: get_request(), verify_request(), y process_request(). Si el método proporcionado por el usuario handle() de la clase del controlador lanza una excepción, se llamará al método handle_error() del servidor. Si no se recibe ninguna solicitud en timeout segundos, se llamará a handle_timeout() y handle_request() regresará.

serve_forever(poll_interval=0.5)

Manejar solicitudes hasta una solicitud explícita shutdown(). Sondeo de apagado cada poll_interval segundos. Ignora el atributo timeout. También llama service_actions(), que puede ser utilizado por una subclase o mixin para proporcionar acciones específicas para un servicio dado. Por ejemplo, la clase ForkingMixIn usa service_actions() para limpiar procesos secundarios zombies.

Distinto en la versión 3.3: Se agregó la llamada service_actions al método serve_forever.

service_actions()

Esto se llama en el ciclo serve_forever(). Este método puede ser reemplazado por subclases o clases mixtas para realizar acciones específicas para un servicio dado, como acciones de limpieza.

Nuevo en la versión 3.3.

shutdown()

Dile al bucle serve_forever() que se detenga y espere hasta que lo haga. shutdown() debe llamarse mientras serve_forever() se está ejecutando en un hilo diferente, de lo contrario, se bloqueará.

server_close()

Limpiar el servidor. Puede ser sobrescrito.

address_family

La familia de protocolos a la que pertenece el socket del servidor. Algunos ejemplos comunes son socket.AF_INET y socket.AF_UNIX.

RequestHandlerClass

La clase de controlador de solicitudes proporcionada por el usuario; se crea una instancia de esta clase para cada solicitud.

server_address

La dirección en la que escucha el servidor. El formato de las direcciones varía según la familia de protocolos; consulte la documentación del módulo socket para obtener más detalles. Para los protocolos de Internet, esta es una tupla que contiene una cadena que proporciona la dirección y un número de puerto entero: ('127.0.0.1', 80), por ejemplo.

socket

El objeto de socket en el que el servidor escuchará las solicitudes entrantes.

Las clases de servidor admiten las siguientes variables de clase:

allow_reuse_address

Si el servidor permitirá la reutilización de una dirección. Este valor predeterminado es False, y se puede establecer en subclases para cambiar la política.

request_queue_size

El tamaño de la cola de solicitudes. Si toma mucho tiempo procesar una sola solicitud, cualquier solicitud que llegue mientras el servidor está ocupado se coloca en una cola, hasta request_queue_size. Una vez que la cola está llena, más solicitudes de clientes obtendrán un error de «Conexión denegada». El valor predeterminado suele ser 5, pero las subclases pueden anularlo.

socket_type

El tipo de socket utilizado por el servidor; socket.SOCK_STREAM y socket.SOCK_DGRAM son dos valores comunes.

timeout

Duración del tiempo de espera, medida en segundos, o None si no se desea un tiempo de espera. Si handle_request() no recibe solicitudes entrantes dentro del período de tiempo de espera, se llama al método handle_timeout().

Hay varios métodos de servidor que pueden ser anulados por subclases de clases de servidor base como TCPServer; estos métodos no son útiles para los usuarios externos del objeto de servidor.

finish_request(request, client_address)

En realidad, procesa la solicitud creando instancias RequestHandlerClass y llamando a su método handle().

get_request()

Debe aceptar una solicitud del socket y retornar una tupla de 2 que contenga el objeto de socket nuevo que se utilizará para comunicarse con el cliente y la dirección del cliente.

handle_error(request, client_address)

Esta función se llama si el método handle() de una instancia RequestHandlerClass lanza una excepción. La acción predeterminada es imprimir el rastreo al error estándar y continuar manejando más solicitudes.

Distinto en la versión 3.6: Ahora solo se solicitan excepciones derivadas de la clase Exception.

handle_timeout()

Esta función se llama cuando el atributo timeout se ha establecido en un valor distinto de None y el tiempo de espera ha pasado sin que se reciban solicitudes. La acción predeterminada para los servidores de forking es recopilar el estado de cualquier proceso hijo que haya salido, mientras que en los servidores de threading este método no hace nada.

process_request(request, client_address)

Llama a finish_request() para crear una instancia de RequestHandlerClass. Si lo desea, esta función puede crear un nuevo proceso o hilo para manejar la solicitud; las clases ForkingMixIn y ThreadingMixIn hacen esto.

server_activate()

Lo llama el constructor del servidor para activar el servidor. El comportamiento predeterminado para un servidor TCP simplemente invoca listen() en el socket del servidor. Puede anularse.

server_bind()

Lo llama el constructor del servidor para vincular el socket a la dirección deseada. Puede anularse.

verify_request(request, client_address)

Debe retornar un valor booleano; si el valor es True, la solicitud se procesará, y si es False, la solicitud será denegada. Esta función se puede anular para implementar controles de acceso para un servidor. La implementación predeterminada siempre retorna True.

Distinto en la versión 3.6: Se agregó soporte para el protocolo context manager. Salir del administrador de contexto es equivalente a llamar a server_close().

Solicitar objetos de controlador

class socketserver.BaseRequestHandler

Esta es la superclase de todos los objetos de manejo de solicitudes. Define la interfaz, que se muestra a continuación. Una subclase de controlador de solicitudes concreta debe definir un nuevo método handle() y puede anular cualquiera de los otros métodos. Se crea una nueva instancia de la subclase para cada solicitud.

setup()

Se llama antes del método handle() para realizar las acciones de inicialización necesarias. La implementación predeterminada no hace nada.

handle()

Esta función debe realizar todo el trabajo necesario para atender una solicitud. La implementación predeterminada no hace nada. Dispone de varios atributos de instancia; la solicitud está disponible como self.request; la dirección del cliente como self.client_address; y la instancia del servidor como self.server, en caso de que necesite acceder a la información por servidor.

El tipo de self.request es diferente para datagramas o servicios de flujo. Para los servicios de transmisión, self.request es un objeto de socket; para servicios de datagramas, self.request es un par de string y socket.

finish()

Se llama después del método handle() para realizar las acciones de limpieza necesarias. La implementación predeterminada no hace nada. Si setup() lanza una excepción, no se llamará a esta función.

class socketserver.StreamRequestHandler

class socketserver.DatagramRequestHandler

Estas subclases BaseRequestHandler anulan los métodos setup() y finish(), y proporcionan self.rfile y self.wfile atributos. Los atributos self.rfile y self.wfile se pueden leer o escribir, respectivamente, para obtener los datos de la solicitud o retornar los datos al cliente.

Los atributos rfile de ambas clases admiten la interfaz legible io.BufferedIOBase, y DatagramRequestHandler.wfile admite la io.BufferedIOBase interfaz de escritura.

Distinto en la versión 3.6: StreamRequestHandler.wfile también admite la interfaz de escritura io.BufferedIOBase.

Ejemplos

socketserver.TCPServer Ejemplo

Este es el lado del servidor:

import socketserver

class MyTCPHandler(socketserver.BaseRequestHandler):
    """
    The request handler class for our server.

    It is instantiated once per connection to the server, and must
    override the handle() method to implement communication to the
    client.
    """

    def handle(self):
        # self.request is the TCP socket connected to the client
        self.data = self.request.recv(1024).strip()
        print("{} wrote:".format(self.client_address[0]))
        print(self.data)
        # just send back the same data, but upper-cased
        self.request.sendall(self.data.upper())

if __name__ == "__main__":
    HOST, PORT = "localhost", 9999

    # Create the server, binding to localhost on port 9999
    with socketserver.TCPServer((HOST, PORT), MyTCPHandler) as server:
        # Activate the server; this will keep running until you
        # interrupt the program with Ctrl-C
        server.serve_forever()

Una clase de controlador de solicitudes alternativa que hace uso de secuencias (objetos similares a archivos que simplifican la comunicación al proporcionar la interfaz de archivo estándar):

class MyTCPHandler(socketserver.StreamRequestHandler):

    def handle(self):
        # self.rfile is a file-like object created by the handler;
        # we can now use e.g. readline() instead of raw recv() calls
        self.data = self.rfile.readline().strip()
        print("{} wrote:".format(self.client_address[0]))
        print(self.data)
        # Likewise, self.wfile is a file-like object used to write back
        # to the client
        self.wfile.write(self.data.upper())

La diferencia es que la llamada readline() en el segundo controlador llamará a recv() varias veces hasta que encuentre un carácter de nueva línea, mientras que la llamada única recv() en el primer controlador simplemente retornará lo que se ha enviado desde el cliente en una llamada sendall() .

Este es el lado del cliente:

import socket
import sys

HOST, PORT = "localhost", 9999
data = " ".join(sys.argv[1:])

# Create a socket (SOCK_STREAM means a TCP socket)
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
    # Connect to server and send data
    sock.connect((HOST, PORT))
    sock.sendall(bytes(data + "\n", "utf-8"))

    # Receive data from the server and shut down
    received = str(sock.recv(1024), "utf-8")

print("Sent:     {}".format(data))
print("Received: {}".format(received))

La salida del ejemplo debería verse así:

Servidor:

$ python TCPServer.py
127.0.0.1 wrote:
b'hello world with TCP'
127.0.0.1 wrote:
b'python is nice'

Cliente:

$ python TCPClient.py hello world with TCP
Sent:     hello world with TCP
Received: HELLO WORLD WITH TCP
$ python TCPClient.py python is nice
Sent:     python is nice
Received: PYTHON IS NICE

socketserver.UDPServer Ejemplo

Este es el lado del servidor:

import socketserver

class MyUDPHandler(socketserver.BaseRequestHandler):
    """
    This class works similar to the TCP handler class, except that
    self.request consists of a pair of data and client socket, and since
    there is no connection the client address must be given explicitly
    when sending data back via sendto().
    """

    def handle(self):
        data = self.request[0].strip()
        socket = self.request[1]
        print("{} wrote:".format(self.client_address[0]))
        print(data)
        socket.sendto(data.upper(), self.client_address)

if __name__ == "__main__":
    HOST, PORT = "localhost", 9999
    with socketserver.UDPServer((HOST, PORT), MyUDPHandler) as server:
        server.serve_forever()

Este es el lado del cliente:

import socket
import sys

HOST, PORT = "localhost", 9999
data = " ".join(sys.argv[1:])

# SOCK_DGRAM is the socket type to use for UDP sockets
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)

# As you can see, there is no connect() call; UDP has no connections.
# Instead, data is directly sent to the recipient via sendto().
sock.sendto(bytes(data + "\n", "utf-8"), (HOST, PORT))
received = str(sock.recv(1024), "utf-8")

print("Sent:     {}".format(data))
print("Received: {}".format(received))

La salida del ejemplo debería verse exactamente como en el ejemplo del servidor TCP.

Mixins asincrónicos

Para construir controladores asincrónicos, use las clases ThreadingMixIn y ForkingMixIn.

Un ejemplo para la clase ThreadingMixIn class

import socket
import threading
import socketserver

class ThreadedTCPRequestHandler(socketserver.BaseRequestHandler):

    def handle(self):
        data = str(self.request.recv(1024), 'ascii')
        cur_thread = threading.current_thread()
        response = bytes("{}: {}".format(cur_thread.name, data), 'ascii')
        self.request.sendall(response)

class ThreadedTCPServer(socketserver.ThreadingMixIn, socketserver.TCPServer):
    pass

def client(ip, port, message):
    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
        sock.connect((ip, port))
        sock.sendall(bytes(message, 'ascii'))
        response = str(sock.recv(1024), 'ascii')
        print("Received: {}".format(response))

if __name__ == "__main__":
    # Port 0 means to select an arbitrary unused port
    HOST, PORT = "localhost", 0

    server = ThreadedTCPServer((HOST, PORT), ThreadedTCPRequestHandler)
    with server:
        ip, port = server.server_address

        # Start a thread with the server -- that thread will then start one
        # more thread for each request
        server_thread = threading.Thread(target=server.serve_forever)
        # Exit the server thread when the main thread terminates
        server_thread.daemon = True
        server_thread.start()
        print("Server loop running in thread:", server_thread.name)

        client(ip, port, "Hello World 1")
        client(ip, port, "Hello World 2")
        client(ip, port, "Hello World 3")

        server.shutdown()

La salida del ejemplo debería verse así:

$ python ThreadedTCPServer.py
Server loop running in thread: Thread-1
Received: Thread-2: Hello World 1
Received: Thread-3: Hello World 2
Received: Thread-4: Hello World 3

La clase ForkingMixIn se usa de la misma manera, excepto que el servidor generará un nuevo proceso para cada solicitud. Disponible solo en plataformas POSIX que admitan fork().

http.server — Servidores HTTP

Código fuente: Lib/http/server.py [https://github.com/python/cpython/tree/3.9/Lib/http/server.py]

Este módulo define clases para implementar servidores HTTP (servidores Web).

Advertencia

http.server is not recommended for production. It only implements basic security checks.

Una clase, HTTPServer, es una subclase socketserver.TCPServer. Crea y escucha en el socket HTTP, enviando las peticiones a un handler. El código para crear y ejecutar el servidor se ve así:

def run(server_class=HTTPServer, handler_class=BaseHTTPRequestHandler):
    server_address = ('', 8000)
    httpd = server_class(server_address, handler_class)
    httpd.serve_forever()

class http.server.HTTPServer(server_address, RequestHandlerClass)

Esta clase se basa en la clase TCPServer almacenando la dirección del servidor como variables de instancia llamadas nombre_del_servidor y puerto_del_servidor. El servidor es accesible por el handler, típicamente a través de la variable de instancia servidor del handler.

class http.server.ThreadingHTTPServer(server_address, RequestHandlerClass)

Esta clase es idéntica a HTTPServer, pero utiliza subprocesos para controlar las solicitudes mediante el uso de ThreadingMixIn. Esto es útil para controlar los sockets de pre-apertura de los navegadores web, en los que HTTPServer esperaría indefinidamente.

Nuevo en la versión 3.7.

El HTTPServer y ThreadingHTTPServer deben recibir un RequestHandlerClass en la creación de instancias, de los cuales este módulo proporciona tres variantes diferentes:

class http.server.BaseHTTPRequestHandler(request, client_address, server)

Esta clase se utiliza para controlar las solicitudes HTTP que llegan al servidor. Por sí mismo, no puede responder a ninguna solicitud HTTP real; debe ser subclase para manejar cada método de solicitud (por ejemplo, GET o POST). BaseHTTPRequestHandler proporciona una serie de variables de clase e instancia, y métodos para su uso por subclases.

El controlador analizará la solicitud y los encabezados y, a continuación, llamará a un método específico del tipo de solicitud. El nombre del método se construye a partir de la solicitud. Por ejemplo, para el método de solicitud SPAM, se llamará al método do_SPAM() sin argumentos. Toda la información relevante se almacena en variables de instancia del controlador. Las subclases no deben tener que reemplazar o extender el método __init__().

BaseHTTPRequestHandler tiene las siguientes variables de instancia:

client_address

Contiene una tupla con el formato (host, port) que hace referencia a la dirección del cliente.

server

Contiene la instancia del servidor.

close_connection

Booleano que se debe establecer antes de handle_one_request() retorna, que indica si se puede esperar otra solicitud o si la conexión debe cerrarse.

requestline

Contiene la representación de cadena de la línea de solicitud HTTP. Se elimina el CRLF de terminación. Este atributo debe establecerse mediante handle_one_request(). Si no se ha procesado ninguna línea de solicitud válida, debe establecerse en la cadena vacía.

command

Contiene el comando (tipo de petición). Por ejemplo, 'GET'.

path

Contains the request path. If query component of the URL is present, then path includes the query. Using the terminology of RFC 3986 [https://tools.ietf.org/html/rfc3986.html], path here includes hier-part and the query.

request_version

Contiene la versión de la cadena de caracteres para la petición. Por ejemplo, HTTP/1.0'.

headers

Contiene una instancia de la clase especificada por la variable de clase MessageClass. Esta instancia analiza y gestiona las cabeceras de la petición HTTP. La función parse_headers() de http.client se usa para parsear las cabeceras y requiere que la petición HTTP proporcione una cabecera válida de estilo RFC 2822 [https://tools.ietf.org/html/rfc2822.html].

rfile

Un flujo de entrada io.BufferedIOBase, listo para leer desde el inicio de los datos de entrada opcionales.

wfile

Contiene el flujo de salida para escribir una respuesta al cliente. Se debe utilizar la adherencia apropiada al protocolo HTTP cuando se escribe en este flujo para lograr una interoperación exitosa con los clientes HTTP.

Distinto en la versión 3.6: Este es un flujo de io.BufferedIOBase.

BaseHTTPRequestHandler tiene los siguientes atributos:

server_version

Especifica la versión del software del servidor. Es posible que desee anular esto. El formato es de múltiples cadenas separadas por espacio en blanco, donde cada cadena es de la forma nombre[/versión]. Por ejemplo, BaseHTTP/0.2'.

sys_version

Contiene la versión del sistema Python, en una forma utilizable por el método version_string y la variable de clase server_version. Por ejemplo, Python/1.4'.

error_message_format

Especifica una cadena de formato que debe ser usada por el método send_error() para construir una respuesta de error al cliente. La cadena se rellena por defecto con variables de responses basadas en el código de estado que pasó a send_error().

error_content_type

Especifica el encabezado HTTP Content-Type de las respuestas de error enviadas al cliente. El valor predeterminado es 'text/html'.

protocol_version

Esto especifica la versión del protocolo HTTP utilizada en las respuestas. Si se establece en 'HTTP/1.1', el servidor permitirá conexiones persistentes HTTP; sin embargo, el servidor debe incluir un encabezado exacto Content-Length (usando send_header()) en todas sus respuestas a los clientes. Para la compatibilidad con versiones anteriores, el valor predeterminado es 'HTTP/1.0'.

MessageClass

Especifica una email.message.Message-como clase para analizar los encabezados HTTP. Típicamente, esto no es anulado, y por defecto es http.client.HTTPMessage.

responses

Este atributo contiene una asignación de enteros de código de error a tuplas de dos elementos que contienen un mensaje corto y largo. Por ejemplo, {code (shortmessage, longmessage)}. El shortmessage se utiliza normalmente como la clave message en una respuesta de error, y longmessage como la clave explain. Es utilizado por send_response_only() y send_error() métodos.

Una instancia BaseHTTPRequestHandler tiene los siguientes métodos:

handle()

Llama handle_one_request() una vez (o, si las conexiones persistentes están habilitadas, varias veces) para manejar las peticiones HTTP entrantes. Nunca debería necesitar anularlo; en su lugar, implemente los métodos apropiados de do_*().

handle_one_request()

Este método analizará y enviará la solicitud al método apropiado do_*(). Nunca deberías necesitar anularlo.

handle_expect_100()

When a HTTP/1.1 compliant server receives an Expect: 100-continue request header it responds back with a 100 Continue followed by 200 OK headers. This method can be overridden to raise an error if the server does not want the client to continue. For e.g. server can choose to send 417 Expectation Failed as a response header and return False.

Nuevo en la versión 3.2.

send_error(code, message=None, explain=None)

Envía y registra una respuesta de error completa al cliente. El code numérico especifica el código de error HTTP, con message como una descripción opcional, corta y legible por el ser humano del error. El argumento explain puede ser usado para proporcionar información más detallada sobre el error; será formateado usando el atributo error_message_format y emitido, después de un conjunto completo de encabezados, como el cuerpo de la respuesta. El atributo responses contiene los valores por defecto para message y explain que se usarán si no se proporciona ningún valor; para los códigos desconocidos el valor por defecto para ambos es la cadena ???. El cuerpo estará vacío si el método es HEAD o el código de respuesta es uno de los siguientes: 1xx, 204 No Content, 205 Reset Content, 304 Not Modified.

Distinto en la versión 3.4: La respuesta de error incluye un encabezado de longitud de contenido. Añadido el argumento explain.

send_response(code, message=None)

Agrega un encabezado de respuesta al búfer de encabezados y registra la solicitud aceptada. La línea de respuesta HTTP se escribe en el búfer interno, seguido de los encabezados Server y Date. Los valores de estos dos encabezados se recogen de los métodos version_string() y date_time_string(), respectivamente. Si el servidor no tiene la intención de enviar ningún otro encabezado utilizando el método send_header(), entonces send_response() debe ir seguido de una llamada end_headers().

Distinto en la versión 3.3: Los encabezados se almacenan en un búfer interno y end_headers() debe llamarse explícitamente.

send_header(keyword, value)

Agrega el encabezado HTTP a un búfer interno que se escribirá en la secuencia de salida cuando se invoca end_headers() o flush_headers(). keyword debe especificar la palabra clave header, con value especificando su valor. Tenga en cuenta que, después de que se realizan las llamadas send_header, end_headers() DEBE llamarse para completar la operación.

Distinto en la versión 3.2: Los encabezados se almacenan en un búfer interno.

send_response_only(code, message=None)

Envía el encabezado de respuesta solamente, usado para los propósitos cuando la respuesta 100 Continue es enviada por el servidor al cliente. Los encabezados no se almacenan en el buffer y envían directamente el flujo de salida. Si no se especifica el message, se envía el mensaje HTTP correspondiente al code de respuesta.

Nuevo en la versión 3.2.

end_headers()

Añade una línea en blanco (indicando el final de las cabeceras HTTP en la respuesta) al buffer de cabeceras y llama a flush_headers().

Distinto en la versión 3.2: Los encabezados del buffer se escriben en el flujo de salida.

flush_headers()

Finalmente envía los encabezados al flujo de salida y limpia el buffer interno de los cabezales.

Nuevo en la versión 3.3.

log_request(code='-', size='-')

Registra una solicitud aceptada (exitosa). El code debe especificar el código numérico HTTP asociado a la respuesta. Si un tamaño de la respuesta está disponible, entonces debe ser pasado como el parámetro size.

log_error(...)

Registra un error cuando una solicitud no puede ser cumplida. Por defecto, pasa el mensaje a log_message(), por lo que toma los mismos argumentos (format y valores adicionales).

log_message(format, ...)

Registra un mensaje arbitrario en sys.stderr. Normalmente se anula para crear mecanismos personalizados de registro de errores. El argumento format es una cadena de formato estándar de estilo de impresión, donde los argumentos adicionales a log_message() se aplican como entradas al formato. La dirección ip del cliente y la fecha y hora actual son prefijadas a cada mensaje registrado.

version_string()

Retorna la cadena de versiones del software del servidor. Esta es una combinación de los atributos server_version y sys_version.

date_time_string(timestamp=None)

Retorna la fecha y la hora dadas por timestamp (que debe ser None o en el formato retornado por time.time`()), formateado para un encabezado de mensaje. Si se omite timestamp, utiliza la fecha y la hora actuales.

El resultado se muestra como Sun, 06 Nov 1994 08:49:37 GMT'.

log_date_time_string()

Retorna la fecha y la hora actuales, formateadas para el registro.

address_string()

Retorna la dirección del cliente.

Distinto en la versión 3.3: Anteriormente, se realizó una búsqueda de nombres. Para evitar retrasos en la resolución del nombre, ahora siempre retorna la dirección IP.

class http.server.SimpleHTTPRequestHandler(request, client_address, server, directory=None)

This class serves files from the directory directory and below, or the current directory if directory is not provided, directly mapping the directory structure to HTTP requests.

Nuevo en la versión 3.7: The directory parameter.

Distinto en la versión 3.9: The directory parameter accepts a path-like object.

La carga de trabajo, como el análisis de la solicitud, lo hace la clase base BaseHTTPRequestHandler. Esta clase implementa las funciones do_GET() y do_HEAD().

Los siguientes se definen como atributos de clase de SimpleHTTPRequestHandler:

server_version

Esto sería "SimpleHTTP/" + __version__, donde __version__ se define a nivel de módulo.

extensions_map

Un diccionario que asigna sufijos a tipos MIME contiene sobreescrituras personalizadas para las asignaciones predeterminadas del sistema. El mapeo se usa sin distinción entre mayúsculas y minúsculas, por lo que solo debe contener claves en minúsculas.

Distinto en la versión 3.9: Este diccionario ya no contiene las asignaciones predeterminadas del sistema, sino que solo contiene anulaciones.

Una instancia SimpleHTTPRequestHandler tiene los siguientes métodos:

do_HEAD()

Este método sirve para el tipo de petición: 'HEAD' envía los encabezados que enviaría para la petición equivalente GET. Ver el método do_GET() para una explicación más completa de los posibles encabezados.

do_GET()

La solicitud se asigna a un archivo local interpretando la solicitud como una ruta relativa al directorio de trabajo actual.

Si la solicitud fue mapeada a un directorio, el directorio se comprueba para un archivo llamado index.html or index.htm (en ese orden). Si se encuentra, se retorna el contenido del archivo; de lo contrario, se genera un listado del directorio llamando al método list_directory(). Este método utiliza os.listdir() para escanear el directorio, y retorna una respuesta de error 404 si falla el listdir().

Si la solicitud fue asignada a un archivo, se abre. Cualquier excepción OSError al abrir el archivo solicitado se asigna a un error 404, 'File not found'. Si había un encabezado 'If-Modified-Since' en la solicitud, y el archivo no fue modificado después de este tiempo, se envía una respuesta 304, 'Not Modified'. De lo contrario, el tipo de contenido se adivina llamando al método guess_type(), que a su vez utiliza la variable extensions_map, y se retorna el contenido del archivo.

Un encabezado de 'Content-type:' con el tipo de contenido adivinado, seguido de un encabezado de 'Content-Length:' con el tamaño del archivo y un encabezado de 'Last-Modified:' con el tiempo de modificación del archivo.

Luego sigue una línea en blanco que significa el final de los encabezados, y luego se imprime el contenido del archivo. Si el tipo MIME del archivo comienza con text/ el archivo se abre en modo de texto; en caso contrario se utiliza el modo binario.

Por ejemplo, ver la implementación de la invocación de la función test() en el módulo http.server.

Distinto en la versión 3.7: Soporta la cabecera 'If-Modified-Since'.

La clase SimpleHTTPRequestHandler puede ser usada de la siguiente manera para crear un servidor web muy básico que sirva archivos relativos al directorio actual:

import http.server
import socketserver

PORT = 8000

Handler = http.server.SimpleHTTPRequestHandler

with socketserver.TCPServer(("", PORT), Handler) as httpd:
    print("serving at port", PORT)
    httpd.serve_forever()

http.server can also be invoked directly using the -m switch of the interpreter. Similar to the previous example, this serves files relative to the current directory:

python -m http.server

The server listens to port 8000 by default. The default can be overridden by passing the desired port number as an argument:

python -m http.server 9000

By default, the server binds itself to all interfaces. The option -b/--bind specifies a specific address to which it should bind. Both IPv4 and IPv6 addresses are supported. For example, the following command causes the server to bind to localhost only:

python -m http.server --bind 127.0.0.1

Nuevo en la versión 3.4: Se introdujo el argumento --bind .

Nuevo en la versión 3.8: El argumento --bind se ha mejorado para soportar IPv6

By default, the server uses the current directory. The option -d/--directory specifies a directory to which it should serve the files. For example, the following command uses a specific directory:

python -m http.server --directory /tmp/

Nuevo en la versión 3.7: --directory argument was introduced.

class http.server.CGIHTTPRequestHandler(request, client_address, server)

Esta clase se utiliza para servir tanto a los archivos como a la salida de los scripts CGI del directorio actual y del siguiente. Note que el mapeo de la estructura jerárquica de HTTP a la estructura del directorio local es exactamente como en SimpleHTTPRequestHandler.

Nota

Los scripts CGI ejecutados por la clase CGIHTTPRequestHandler no pueden ejecutar redirecciones (código HTTP 302), porque el código 200 (la salida del script sigue) se envía antes de la ejecución del script CGI. Esto adelanta el código de estado.

La clase, sin embargo, ejecutará el script CGI, en lugar de servirlo como un archivo, si adivina que es un script CGI. Sólo se usan CGI basados en directorios — la otra configuración común del servidor es tratar las extensiones especiales como denotando los scripts CGI.

Las funciones do_GET() y do_HEAD() se modifican para ejecutar scripts CGI y servir la salida, en lugar de servir archivos, si la petición lleva a algún lugar por debajo de la ruta cgi_directories.

La CGIHTTPRequestHandler define el siguiente miembro de datos:

cgi_directories

Esto por defecto es ['/cgi-bin', '/htbin'] y describe los directorios a tratar como si contuvieran scripts CGI.

La CGIHTTPRequestHandler define el siguiente método:

do_POST()

Este método sirve para el tipo de petición 'POST', sólo permitido para scripts CGI. El error 501, «Can only POST to CGI scripts», se produce cuando se intenta enviar a una url no CGI.

Tenga en cuenta que los scripts CGI se ejecutarán con UID de usuario nobody, por razones de seguridad. Los problemas con el script CGI serán traducidos al error 403.

CGIHTTPRequestHandler puede ser activado en la línea de comandos pasando la opción --cgi:

python -m http.server --cgi

Security Considerations

SimpleHTTPRequestHandler will follow symbolic links when handling requests, this makes it possible for files outside of the specified directory to be served.

Earlier versions of Python did not scrub control characters from the log messages emitted to stderr from python -m http.server or the default BaseHTTPRequestHandler .log_message implementation. This could allow remote clients connecting to your server to send nefarious control codes to your terminal.

Nuevo en la versión 3.9.16: scrubbing control characters from log messages

http.cookies — Gestión del estado HTTP

Source code: Lib/http/cookies.py [https://github.com/python/cpython/tree/3.9/Lib/http/cookies.py]

El módulo http.cookies define clases para abstraer el concepto de cookies, un mecanismo de gestión de estado HTTP. Admite cookies simples de solo cadenas de caracteres y proporciona una abstracción para tener cualquier tipo de datos serializable como valor de cookie.

Anteriormente, el módulo aplicaba estrictamente las reglas de análisis descritas en las especificaciones RFC 2109 [https://tools.ietf.org/html/rfc2109.html] y RFC 2068 [https://tools.ietf.org/html/rfc2068.html]. Desde entonces se ha descubierto que MSIE 3.0x no sigue las reglas de caracteres descritas en esas especificaciones y también muchos navegadores y servidores actuales tienen reglas de análisis relajadas en lo que respecta al manejo de cookies. Como resultado, las reglas de análisis utilizadas son un poco menos estrictas.

El conjunto de caracteres, string.ascii_letters, string.digits y !#$%&'*+-.^_`|~: Denota el conjunto de caracteres válidos permitidos por este módulo en el nombre de la cookie (como key).

Distinto en la versión 3.3: Se permite “:” como un carácter de nombre de cookie válido.

Nota

Al encontrar una cookie no válida, se lanza CookieError, por lo que si los datos de su cookie provienen de un navegador, siempre debe prepararse para los datos no válidos y detectar CookieError en el análisis.

exception http.cookies.CookieError

Error de excepción debido a la invalidez de RFC 2109 [https://tools.ietf.org/html/rfc2109.html]: atributos incorrectos, encabezado Set-Cookie incorrecto, etc.

class http.cookies.BaseCookie([input])

Esta clase es un objeto similar a un diccionario cuyas claves son cadenas de caracteres y cuyos valores son Morsel. Tenga en cuenta que al establecer una clave en un valor, el valor se convierte primero en Morsel que contiene la clave y el valor.

Si se proporciona input, se pasa al método load().

class http.cookies.SimpleCookie([input])

Esta clase se deriva de BaseCookie y anula value_decode() y value_encode(). SimpleCookie admite cadenas de caracteres como valores de cookies. Al establecer el valor, SimpleCookie llama al incorporado str() para convertir el valor en una cadenas de caracteres. Los valores recibidos de HTTP se mantienen como cadenas de caracteres.

Ver también

Módulo http.cookiejar

Manejo de cookies HTTP para web clients. Los módulos http.cookiejar and http.cookies no dependen el uno del otro.

RFC 2109 [https://tools.ietf.org/html/rfc2109.html] - Mecanismo de gestión de estado HTTP

Esta es la especificación de gestión de estado implementada por este módulo.

Objetos de cookie

BaseCookie.value_decode(val)

Retorna una tupla (real_value, coded_value) de una representación de cadena de caracteres. real_value puede ser de cualquier tipo. Este método no decodifica en BaseCookie — existe por lo que puede ser anulado.

BaseCookie.value_encode(val)

Retorna una tupla (real_value, coded_value). val puede ser de cualquier tipo, pero coded_value siempre se convertirá en una cadena de caracteres. Este método no codifica en BaseCookie — existe por lo que se puede anular.

En general, debería darse el caso de que value_encode() y value_decode() sean inversas en el rango de value_decode.

BaseCookie.output(attrs=None, header='Set-Cookie:', sep='\r\n')

Retorna una representación de cadena de caracteres adecuada para enviarse como encabezados HTTP. attrs y header se envían a cada método Morsel’s output(). sep se usa para unir los encabezados y es por defecto la combinación '\r\n' (CRLF).

BaseCookie.js_output(attrs=None)

Retorna un fragmento de código JavaScript que, si se ejecuta en un navegador que admita JavaScript, actuará de la misma forma que si se enviaran los encabezados HTTP.

El significado de attrs es el mismo que en output().

BaseCookie.load(rawdata)

Si rawdata es una cadena de caracteres, analícela como un HTTP_COOKIE y agregue los valores que se encuentran allí como Morsels. Si es un diccionario, equivale a:

for k, v in rawdata.items():
    cookie[k] = v

Objetos Morsel

class http.cookies.Morsel

Resumen de un par clave/valor, que tiene algunos atributos RFC 2109 [https://tools.ietf.org/html/rfc2109.html].

Los Morsels son objetos similares a diccionarios, cuyo conjunto de claves es constante — los atributos válidos RFC 2109 [https://tools.ietf.org/html/rfc2109.html], que son

expires

path

comment

domain

max-age

secure

version

httponly

samesite

El atributo httponly especifica que la cookie solo se transfiere en solicitudes HTTP y no es accesible a través de JavaScript. Esto tiene como objetivo mitigar algunas formas de secuencias de comandos entre sitios.

El atributo samesite especifica que el navegador no puede enviar la cookie junto con solicitudes entre sitios. Esto ayuda a mitigar los ataques CSRF. Los valores válidos para este atributo son «Strict» y «Lax».

Las claves no distinguen entre mayúsculas y minúsculas y su valor predeterminado es ''.

Distinto en la versión 3.5: __eq__() ahora toma key y value en cuenta.

Distinto en la versión 3.7: Los atributos key, value y coded_value son de solo lectura. Utilice set() para configurarlos.

Distinto en la versión 3.8: Se agregó soporte para el atributo samesite.

Morsel.value

El valor de la cookie.

Morsel.coded_value

El valor codificado de la cookie — esto es lo que se debe enviar.

Morsel.key

El nombre de la cookie.

Morsel.set(key, value, coded_value)

Establezca los atributos key, value y coded_value.

Morsel.isReservedKey(K)

Si K es miembro del conjunto de claves de una Morsel.

Morsel.output(attrs=None, header='Set-Cookie:')

Retorna una representación de cadena de caracteres del Morsel, adecuada para enviarse como un encabezado HTTP. De forma predeterminada, se incluyen todos los atributos, a menos que se proporcione attrs, en cuyo caso debería ser una lista de atributos a utilizar. header es por defecto "Set-Cookie:".

Morsel.js_output(attrs=None)

Retorna un fragmento de código JavaScript que, si se ejecuta en un navegador que admita JavaScript, actuará de la misma forma que si se hubiera enviado el encabezado HTTP.

El significado de attrs es el mismo que en output().

Morsel.OutputString(attrs=None)

Retorna una cadena de caracteres que representa el Morsel, sin ningún HTTP o JavaScript circundante.

El significado de attrs es el mismo que en output().

Morsel.update(values)

Actualice los valores en el diccionario Morsel con los valores en el diccionario values. Lanza un error si alguna de las claves en el values dict no es un atributo válido RFC 2109 [https://tools.ietf.org/html/rfc2109.html].

Distinto en la versión 3.5: se lanza un error para claves no válidas.

Morsel.copy(value)

Retorna una copia superficial del objeto Morsel.

Distinto en la versión 3.5: retorna un objeto Morsel en lugar de un dict.

Morsel.setdefault(key, value=None)

Lanza un error si la clave no es un atributo válido RFC 2109 [https://tools.ietf.org/html/rfc2109.html]; de lo contrario, se comporta igual que dict.setdefault().

Ejemplo

El siguiente ejemplo demuestra cómo utilizar el módulo http.cookies.

>>> from http import cookies
>>> C = cookies.SimpleCookie()
>>> C["fig"] = "newton"
>>> C["sugar"] = "wafer"
>>> print(C) # generate HTTP headers
Set-Cookie: fig=newton
Set-Cookie: sugar=wafer
>>> print(C.output()) # same thing
Set-Cookie: fig=newton
Set-Cookie: sugar=wafer
>>> C = cookies.SimpleCookie()
>>> C["rocky"] = "road"
>>> C["rocky"]["path"] = "/cookie"
>>> print(C.output(header="Cookie:"))
Cookie: rocky=road; Path=/cookie
>>> print(C.output(attrs=[], header="Cookie:"))
Cookie: rocky=road
>>> C = cookies.SimpleCookie()
>>> C.load("chips=ahoy; vienna=finger") # load from a string (HTTP header)
>>> print(C)
Set-Cookie: chips=ahoy
Set-Cookie: vienna=finger
>>> C = cookies.SimpleCookie()
>>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";')
>>> print(C)
Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;"
>>> C = cookies.SimpleCookie()
>>> C["oreo"] = "doublestuff"
>>> C["oreo"]["path"] = "/"
>>> print(C)
Set-Cookie: oreo=doublestuff; Path=/
>>> C = cookies.SimpleCookie()
>>> C["twix"] = "none for you"
>>> C["twix"].value
'none for you'
>>> C = cookies.SimpleCookie()
>>> C["number"] = 7 # equivalent to C["number"] = str(7)
>>> C["string"] = "seven"
>>> C["number"].value
'7'
>>> C["string"].value
'seven'
>>> print(C)
Set-Cookie: number=7
Set-Cookie: string=seven

http.cookiejar — Manejo de cookies para clientes HTTP

Código fuente: Lib/http/cookiejar.py [https://github.com/python/cpython/tree/3.9/Lib/http/cookiejar.py]

El módulo http.cookiejar define clases para el manejo automático de cookies HTTP. Es útil para acceder a sitios web que requieren pequeñas piezas de datos – cookies – para establecerse en el equipo del cliente a través de una respuesta HTTP de un servidor web, y que además retornan al servidor más tarde en forma de requests de HTTP.

Se manejan tanto el protocolo de cookies Netscape regular y el protocolo definido por RFC 2965 [https://tools.ietf.org/html/rfc2965.html]. El manejo del RFC 2695 se encuentra desactivado de forma predeterminada. Las cookies RFC 2109 [https://tools.ietf.org/html/rfc2109.html] se analizan como cookies Netscape, y subsecuentemente se tratan como cookies Netscape o RFC 2695 de acuerdo con el «policy» actual. Tenga en cuenta que la gran mayoría de las cookies en el Internet son Netscape cookies. http.cookiejar intenta seguir de-facto el protocolo de cookies Netscape (el cual difiere substancialmente de las especificaciones originales de Netscape), incluyendo los importantes cookie-attribute max-age y port introducidos con RFC 2965.

Nota

Diversos parámetros nombrados que se encuentran en Set-Cookie y Set-Cookie2 (ejem. domain y expires) son convencionalmente referidos como attributes. Para distinguirlos de los atributos de Python, la documentación de este módulo utiliza el término cookie-attribute.

El módulo define la siguiente excepción:

exception http.cookiejar.LoadError

Las instancias de FileCookieJar provocan esta excepción al no cargar las cookies desde un archivo. LoadError es una subclase de OSError.

Distinto en la versión 3.3: LoadError fue transformado a una subclase de OSError en vez de IOError.

Se proporcionan las siguientes clases:

class http.cookiejar.CookieJar(policy=None)

policy es un objeto implementando la interfaz CookiePolicy.

La clase CookieJar almacena HTTP cookies. Ésta extrae cookies de los request de HTTP, y las retorna en forma de responses de HTTP. Las instancias de CookieJar automáticamente expiran las cookies contenidas cuando es necesario. Las subclases también son responsables de almacenar y recuperar cookies de un archivo o base de datos.

class http.cookiejar.FileCookieJar(filename, delayload=None, policy=None)

policy es un objeto implementando la interfaz CookiePolicy. Para los otros argumentos, te recomendamos visitar la documentación correspondiente a los atributos.

Una CookieJar puede cargar cookies de, y posiblemente almacenar, un archivo en el disco. Las cookies NO son cargadas desde un archivo nombrado hasta que alguno de los métodos load() o revert() es llamado. Subclases de esta clase son documentadas en la sección Subclases FileCookieJar y co-operación con navegadores web.

Distinto en la versión 3.8: El parámetro filename soporta un path-like object.

class http.cookiejar.CookiePolicy

Esta clase es responsable de decidir si cada cookie debe ser aceptada del servidor, o retornada al mismo.

class http.cookiejar.DefaultCookiePolicy(blocked_domains=None, allowed_domains=None, netscape=True, rfc2965=False, rfc2109_as_netscape=None, hide_cookie2=False, strict_domain=False, strict_rfc2965_unverifiable=True, strict_ns_unverifiable=False, strict_ns_domain=DefaultCookiePolicy.DomainLiberal, strict_ns_set_initial_dollar=False, strict_ns_set_path=False, secure_protocols=("https", "wss"))

Los argumentos del constructor sólo deben ser dados como argumentos clave. blocked_domains es una secuencia de nombres de dominio cuyas cookies nunca deben de ser aceptadas o retornadas. allowed_domains y no None, es una secuencia de sólo dominios que podemos aceptar y retornar cookies. secure_protocols es una secuencia de protocolos para los que se pueden agregar cookies seguras. De manera predeterminada https y wss (websocket seguro) son considerados protocolos seguros. Para todos los demás argumentos, te recomendamos visitar la documentación para los objetos CookiePolicy y DefaultCookiePolicy.

DefaultCookiePolicy implementa el estándar de reglas aceptar/rechazar para cookies Netscape y RFC 2965 [https://tools.ietf.org/html/rfc2965.html]. De manera predeterminada, las cookies RFC 2109 [https://tools.ietf.org/html/rfc2109.html] (es decir, las cookies que reciben una cabecera Set-Cookie con una versión cookie-attribute de 1) son tratadas de acuerdo con las reglas del RFC 2965. Sin embargo, si el manejo del RFC2965 se encuentra apagado o rfc2109_as_netscape es True, las cookies RFC 2109 son “degradadas” por la instancia CookieJar a las cookies Netscape, configurando la version del atributo de la instancia Cookie como 0. DefaultCookiePolicy también provee algunos parámetros que permiten fine-tunning en el policy.

class http.cookiejar.Cookie

Esta clase representa Netscape, las cookies RFC 2109 [https://tools.ietf.org/html/rfc2109.html] y RFC 2965 [https://tools.ietf.org/html/rfc2965.html]. No se espera que los usuarios de http.cookiejar construyan sus propias instancias de Cookie. En vez de ello, si es necesario, llama al método make_cookies() de la instancia CookieJar.

Ver también

Módulo urllib.request

Apertura de URL con manejo automático de cookies.

Módulo http.cookies

Clases de cookies HTTP, principalmente útiles para código server-side. Los módulos http.cookiejar y http.cookies no dependen uno del otro.

https://curl.se/rfc/cookie_spec.html

La especificación original del protocolo de cookies Netscape. Aunque éste sigue siendo el protocolo dominante, el “protocolo de cookies Netscape” implementado por la mayoría de los navegadores (y el protocolo http.cookiejar) sólo tienen in parecido pasajero con el bosquejado en cookie_spec.html.

RFC 2109 [https://tools.ietf.org/html/rfc2109.html] - Mecanismo de Gestión de Estados HTTP

Obsoleto por RFC 2965 [https://tools.ietf.org/html/rfc2965.html]. Usa Set-Cookie con versión=1.

RFC 2965 [https://tools.ietf.org/html/rfc2965.html] - Mecanismo de Gestión de Estados HTTP

El protocolo Netscape con los errores solucionados. Usa Set-Cookie2 en lugar de Set-Cookie. No es ampliamente usado.

http://kristol.org/cookie/errata.html

Fe de erratas sin finalizar hasta el RFC 2965 [https://tools.ietf.org/html/rfc2965.html].

RFC 2964 [https://tools.ietf.org/html/rfc2964.html] - Mecanismo de Gestión de Estados HTTP

Objetos CookieJar y FileCookieJar

Los objetos CookieJar soportan el protocolo iterator para iterar sobre los objetos Cookie contenidos.

CookieJar tiene los siguientes métodos:

CookieJar.add_cookie_header(request)

Añade la cookie correcta a la cabecera del request.

Si el policy admite (ie. los atributos rfc2965 y hide_cookie2 de la instancia CookieJar del CookiePolicy son de manera respectiva verdadero y falso), la cabecera Cookie2 es igualmente añadido cuando es apropiado.

El objeto request (usualmente una instancia urllib.request.Request) debe de soportar los métodos get_full_url(), get_host(), get_type(), unverifiable(), has_header(), get_header(), header_items(), add_unredirected_header() y el atributo origin_req_host como es documentado en urllib.request.

Distinto en la versión 3.3: el objeto request necesita del atributo origin_req_host. La dependencia en el método deprecado get_origin_req_host() ha sido removida.

CookieJar.extract_cookies(response, request)

Extrae las cookies del response HTTP y las almacena en el CookieJar, donde está permitido por la policy.

El CookieJar buscará por cabeceras Set-Cookie y Set-Cookie2 permitidos en el argumento response, y almacena las cookies cuando es apropiado (sujeto a la aprobación del método CookiePolicy.set_ok()).

El objeto response (usualmente el resultado de llamar urllib.request.urlopen(), o similares) debe de soportar un método info() , el cual retorna una instancia email.message.Message.

El objeto request (usualmente una instancia urllib.request.Request) debe soportar los métodos get_full_url(), get_host(), unverifiable(), y el atributo origin_req_host, como es documentado en urllib.request. La request es utilizada para establecer valores predeterminados en los atributos-cookie así como de comprobar si tiene permitido hacerlo.

Distinto en la versión 3.3: el objeto request necesita del atributo origin_req_host. La dependencia en el método deprecado get_origin_req_host() ha sido removida.

CookieJar.set_policy(policy)

Establece la instancia CookiePolicy para ser usada.

CookieJar.make_cookies(response, request)

Retorna una secuencia de objetos Cookie extraída del objeto response.

Revisa la documentación extract_cookies() para conocer las interfaces necesarias de los argumentos response y request.

CookieJar.set_cookie_if_ok(cookie, request)

Establece una Cookie si la política (policy) dice OK para hacerlo.

CookieJar.set_cookie(cookie)

Establece una Cookie, sin consultar con la política (policy) para ver si se debe de establecer o no.

CookieJar.clear([domain[, path[, name]]])

Borra algunas cookies.

Si se invoca sin argumentos, borra todas las cookies. Si se le da un solo argumento. sólo las cookies que pertenecen a tal domain serán removidas. Si se le da dos argumentos, las cookies pertenecientes al especificado domain y path URL serán removidas. Si se le da tres argumentos, entonces la cookie con el especificado domain, path y name será removida.

Lanza KeyError si no existe ninguna cookie que coincida.

CookieJar.clear_session_cookies()

Descarta todas las cookies de la sesión.

Descarta todas las cookies que tengan un atributo discard true (usualmente porque no tienen max-age o expires atributos’cookie, o un explícito atributo-cookie discard). Para los navegadores interactivos, el fin de la sesión usualmente corresponde con el cierre de la ventana del navegador.

Nota que el método save() no guardará las cookies de la sesión de todas maneras, a menos que de otra manera preguntes para pasar un argumento ignore_discard como true.

FileCookieJar implementa los siguientes métodos adicionales:

FileCookieJar.save(filename=None, ignore_discard=False, ignore_expires=False)

Guarda las cookies en un archivo.

Esta clase base genera NotImplementedError. Las subclases podrían dejar este método sin implementar.

filename es el nombre del archivo en el que se guardarán las cookies. Si filename no es especificado, self.filename es utilizado (cuyo valor predeterminado es el valor que será pasado al constructor, si hay alguno); si self.filename es None, se genera un ValueError.

ignore_discard: almacena incluso las cookies configuradas para ser descartadas. ignore_expires: almacena las cookies que han caducado

El archivo se sobrescribe si ya existe, borrando así todas las cookies que contiene. Las cookies guardadas se pueden restaurar después utilizando los métodos load() o revert().

FileCookieJar.load(filename=None, ignore_discard=False, ignore_expires=False)

Carga las cookies desde un archivo.

Las viejas cookies son guardadas a menos que sean sobre escritas por nuevas recién cargadas.

Los argumentos son en cuanto a save().

El archivo nombrado debe estar en un formato entendible para la clase, o se generará un LoadError. Además, puede generarse un OSError, por ejemplo, si el archivo no existe.

Distinto en la versión 3.3: Solía levantarse un IOError, pero ahora es un alias de OSError.

FileCookieJar.revert(filename=None, ignore_discard=False, ignore_expires=False)

Limpia todas las cookies y recarga las cookies de un archivo guardado.

revert() puede levantar las mismas excepciones que load(). Si hay un fallo. el estado del objeto no se alterará.

Instancias FileCookieJar tienen los siguientes atributos públicos:

FileCookieJar.filename

Nombre del archivo predeterminado para el archivo en donde se almacenan las cookies. Este atributo podría ser asignado.

FileCookieJar.delayload

Si es true, carga perezosamente las cookies desde el disco. Este atributo no se debería de asignar. Esta es solo una pista, debido a que solo el rendimiento, y no al comportamiento (a menos que las cookies en el disco sean cambiadas). Un objeto CookieJar puede ignorarlo. Ninguna de las clases de FileCookieJar incluidas en la librería estándar carga las cookies de manera perezosa.

Subclases FileCookieJar y co-operación con navegadores web

Las siguientes subclases CookieJar son proveídas para lectura y escritura.

class http.cookiejar.MozillaCookieJar(filename, delayload=None, policy=None)

Un FileCookieJar que puede cargar y guardar cookies al disco en el formato de archivo Mozilla cookies.txt (el cual es también utilizado por los navegadores Lynx y Netscape).

Nota

Esto puede perder información acerca de cookies RFC 2965 [https://tools.ietf.org/html/rfc2965.html], y también sobre atributos nuevos o no estándar como port.

Advertencia

Realiza una copia de seguridad de tus cookies antes de guardarlas, especialmente si tienes cookies cuya perdida / corrupción puede ser inconveniente (hay algunas sutilezas que pueden conducir a ligeros cambios en el archivo sobre una carga / guardado round-trip).

También toma en cuenta que las cookies guardadas mientras Mozilla se está ejecutando se volverán torpes debido a Mozilla.

class http.cookiejar.LWPCookieJar(filename, delayload=None, policy=None)

Un FileCookieJar que puede cargar y guardar en disco en formato compatible con el formato de archivo Set-Cookie3 de la librería libwww-perl. Estos es conveniente si tu quieres guardar cookies en un archivo legible para los humanos.

Distinto en la versión 3.8: El parámetro filename soporta un path-like object.

Objetos CookiePolicy

Objetos implementando la interfaz CookiePolicy tienen los siguientes métodos:

CookiePolicy.set_ok(cookie, request)

Retorna un valor booleano indicando si la cookie debe ser aceptada o no desde el servidor.

cookie es una instancia de Cookie. request es un objeto implementando la interfaz definida por la documentación de CookieJar.extract_cookies().

CookiePolicy.return_ok(cookie, request)

Retorna un valor booleano indicando si la cookie debe ser retornada o no al servidor.

cookie es una instancia de Cookie. request es un objeto implementando la interfaz definida por la documentación de CookieJar.add_cookie_header().

CookiePolicy.domain_return_ok(domain, request)

Retorna False si las cookies no deben de ser retornadas, a partir del dominio cookie dado.

Este método es una optimización. Elimina la necesidad de verificar cada cookie con un domino en particular (lo cual puede involucrar la lectura de muchos archivos). Retornando true de domain_return_ok() y path_return_ok() deja todo el trabajo a return_ok().

Si domain_return_ok() retorna true para el dominio de cookies, path_return_ok() es llamado para el path de cookies. De otra manera, path_return_ok() y return_ok() no son nunca llamados para ese dominio de cookies. Si path_return_ok() retorna true, return_ok() es llamado con el objeto Cookie en sí para una revisión completa. De otra manera, return_ok() es nunca llamado para ese path de cookies.

Ten en cuenta que domain_return_ok() es llamado para cada dominio cookie, no solamente para el dominio request. Por ejemplo, la función podría ser llamada con ambos ".example.com" y "www.example.com" si el dominio request es "www.example.com". Lo mismo se aplica para path_return_ok().

El argumento request es tal y como es documentado para return_ok().

CookiePolicy.path_return_ok(path, request)

Retorna False si las cookies no deben de ser retornadas, dado el path de las cookies.

Revisa la documentación para domain_return_ok().

Adicionalmente a los métodos implementados anteriormente, las implementaciones de la interfaz CookiePolicy también deben de proporcionar los siguientes atributos, indicando cuales protocolos deben de ser utilizados, y como. Todos estos atributos se pueden asignar.

CookiePolicy.netscape

Implementa el protocolo Netscape.

CookiePolicy.rfc2965

Implementa el protocolo RFC 2965 [https://tools.ietf.org/html/rfc2965.html].

CookiePolicy.hide_cookie2

No añadas la cabecera Cookie2 a las requests (la presencia de esta cabecera indica al servidor que nosotros entendemos las cookies RFC 2965 [https://tools.ietf.org/html/rfc2965.html]).

El camino más útil para definir una clase CookiePolicy es haciendo una subclase de DefaultCookiePolicy y sobre escribir algunos o todos los métodos anteriores. CookiePolicy en sí misma puede ser utilizada como una “null policy” para permitir establecer y recibir algunas o todas las cookies (esto raramente puede ser útil).

Objetos DefaultCookiePolicy

Implementa las reglas estándar para aceptar y retornar cookies.

Ambas cookies, RFC 2965 [https://tools.ietf.org/html/rfc2965.html] y Netscape son cubiertas. El manejo del RFC 2965 está desactivado de forma predeterminada.

La forma más sencilla de proporcionar tu propia política (policy) es sobre escribir esta clase y llamar sus métodos en tus implementaciones modificadas antes de añadir tu propias comprobaciones adicionales:

import http.cookiejar
class MyCookiePolicy(http.cookiejar.DefaultCookiePolicy):
    def set_ok(self, cookie, request):
        if not http.cookiejar.DefaultCookiePolicy.set_ok(self, cookie, request):
            return False
        if i_dont_want_to_store_this_cookie(cookie):
            return False
        return True

En adición a las características requeridas para implementar la interfaz CookiePolicy, esta clase te permite que bloquees o permitas dominios de establecer y recibir cookies. También hay algunos interruptores estrictos que te permiten ajustar un poco las reglas flojas del protocolo Netscape (a costa de bloquear algunas cookies benignas).

Se proporciona una lista negra y una lista blanca (ambas desactivas de manera predeterminada). Sólo los dominios que no se encuentran en la lista negra y que están presentes en la lista blanca (si la lista blanca se encuentra activada) participan en el establecimiento y regreso de cookies. Usa los argumentos constructor de blocked_domains, y los métodos blocked_domains() y set_blocked_domains() (además de los argumentos y métodos correspondientes para allowed_domains). Si estableces una lista blanca, puedes apagarla de nuevo estableciéndola en None.

Los dominios en las listas de bloqueo o permiso que no pueden empezar con un punto deben de ser iguales al dominio de la cookie para que coincidan. Por ejemplo "example.com" coincide con una entrada de la lista negra de "example.com", pero "www.example.com" no lo hace. Los dominios que empiezan con un punto son también emparejados con dominios más específicos. Por ejemplo, ambas "www.example.com" y "www.coyote.example.com" coinciden con ".example.com" (pero "example.com" en sí misma no). Las direcciones IP son la excepción, y deben coincidir exactamente. Por ejemplo, si bolcked_domains contiene "192.168.1.2" y ".168.1.2", 192.168.1.2 está bloqueado, pero 193.168.1.2 no.

DefaultCookiePolicy implementa los siguientes métodos adicionales:

DefaultCookiePolicy.blocked_domains()

Retorna una secuencia de dominios bloqueados (en forma de tupla).

DefaultCookiePolicy.set_blocked_domains(blocked_domains)

Establece la secuencia de dominios bloqueados.

DefaultCookiePolicy.is_blocked(domain)

Retorna si domain se encuentra en la lista negra o no para establecer o recibir cookies.

DefaultCookiePolicy.allowed_domains()

Retorna None, o la secuencia de los dominios permitidos (en forma de tupla).

DefaultCookiePolicy.set_allowed_domains(allowed_domains)

Establece la secuencia de los dominios permitidos, o None.

DefaultCookiePolicy.is_not_allowed(domain)

Retorna si domain no se encuentra o si en la lista blanca para establecer y recibir cookies.

Las instancias DefaultCookiePolicy tienen los siguientes atributos, que son todos inicializados desde los argumentos del constructor del mismo nombre, y el cual todos pueden ser asignados a.

DefaultCookiePolicy.rfc2109_as_netscape

Si es true, solicita que la instancia CookieJar degrade las cookies RFC 2109 [https://tools.ietf.org/html/rfc2109.html] (es decir, las cookies recibidas en una cabecera Set-Cookie con un cookie-attribute versión de 1) a cookies Netscape al establecer la versión del atributo de la instancia Cookie a 0. El valor predeterminado es None, en cuyo caso las cookies RFC 2109 son degradadas si y sólo si el control de RFC 2965 [https://tools.ietf.org/html/rfc2965.html] se encuentra apagado. Por lo tanto, las cookies RFC 2109 son degradadas de forma predeterminada.

Interruptores generales de rigurosidad:

DefaultCookiePolicy.strict_domain

No permite que los sitios establezcan dominios de dos componentes con dominios country-code top-level como .co.uk, .gov.uk, .co.nz.etc. ¡Esto está lejos de ser perfecto y no está garantizado a que vaya a funcionar!

Interruptores de rigurosidad del protocolo RFC 2965 [https://tools.ietf.org/html/rfc2965.html]:

DefaultCookiePolicy.strict_rfc2965_unverifiable

Siga las reglas :rfc:”2965” sobre transacciones no verificables (normalmente, una transacción no verificable es una del resultado de una redirección o una solicitud de una imagen alojada en otro sitio). Si esto es falso, las cookies nunca se bloquean en base a la verificabilidad

Interruptores de rigurosidad del protocolo Netscape:

DefaultCookiePolicy.strict_ns_unverifiable

Aplica las reglas del RFC 2965 [https://tools.ietf.org/html/rfc2965.html] a transacciones no verificables incluso a cookies Netscape.

DefaultCookiePolicy.strict_ns_domain

Indicadores que señalan que tan estricto deben ser con las reglas de domain-matching para cookies Netscape. Consulte a continuación los valores aceptables.

DefaultCookiePolicy.strict_ns_set_initial_dollar

Ignora las cookies en las cabeceras Set-Cookie: que tengan nombres que comienzan con '$'.

DefaultCookiePolicy.strict_ns_set_path

No permite establecer cookies cuyo path no concuerde con el request URI.

strict_ns_domain es una colección de indicadores. Su valor está construido o siendo construido en conjunto (por ejemplo, DomainStrictNoDots|DomainStrictNonDomain significa que ambos indicadores se encuentran establecidos).

DefaultCookiePolicy.DomainStrictNoDots

Cuando configuras las cookies, el “host prefix” no debe de contener un punto (ejem. www.foo.bar.com no puede establecer una cookie para .bar.com, porque www.foo tiene un punto).

DefaultCookiePolicy.DomainStrictNonDomain

Las cookies que no especifican explícitamente un cookie-attribute domain sólo se pueden retornar a un dominio igual al que estableció la cookie (ejem. spam.example.com no retornará las cookies de example.com que no tuvieran un cookie-attribute domain)

DefaultCookiePolicy.DomainRFC2965Match

Cuando se establecen las cookies, requiere de un completo emparejamiento de dominio RFC 2965 [https://tools.ietf.org/html/rfc2965.html].

Los siguientes atributos son proveídos por conveniencia, y son las combinaciones más útiles de los indicadores anteriores:

DefaultCookiePolicy.DomainLiberal

Equivalente a 0 (es decir, todos los anteriores indicadores de rigurosidad de los dominios Netscape están apagados).

DefaultCookiePolicy.DomainStrict

Equivalente a DomainStrictNoDots|DomainStrictNonDomain.

Objetos Cookie

Las instancias Cookie tienen atributos Python mas o menos correspondientes a los estándar cookie-attribute especificados en los diferentes estándares cookie. La correspondencia no es uno a uno, porque existen complicadas reglas para asignar valores predeterminados, debido a que los cookie-attribute max-age y expires contienen información equivalente, además que las cookies RFC 2109 [https://tools.ietf.org/html/rfc2109.html] pueden estar “downgraded” por http.cookiejar desde la versión 1 a la 0 (Netscape) cookies.

La asignación a estos atributos no debe de ser necesario excepto en raras circunstancias en un método CookiePolicy. La clase no aplica consistencia interna, por lo que tienes que saber lo que estás haciendo si lo estas aplicando.

Cookie.version

Entero o None. Las cookies Netscape tienen version 0. RFC 2965 [https://tools.ietf.org/html/rfc2965.html] y las cookies RFC 2109 [https://tools.ietf.org/html/rfc2109.html] tienen una version del cookie-attribute de 1. Sin embargo, ten en cuenta que http.cookiejar puede “downgrade” las cookies RFC 2109 a Netscape cookies, en cuyo caso version es 0.

Cookie.name

Nombre de la cookie (un string).

Cookie.value

El valor de la cookie (una string), o None.

Cookie.port

String que representa un puerto o un conjunto de puertos (ejem. “80”, o “80,8080”) o incluso None.

Cookie.path

Ruta de la cookie (un string, ejem. '/acme/rocket_launchers').

Cookie.secure

True si cookie sólo debe de ser retornada sobre una conexión segura.

Cookie.expires

Fecha de caducidad entera en segundos desde la parte temporal, o None. Véase también el método is_expired().

Cookie.discard

True si esta es una sesión de cookies.

Cookie.comment

Comentario string del servidor explicando la función de esta cookie, o None.

Cookie.comment_url

URL que enlaza a un comentario desde un servidor explicando la función de esta cookie, o None.

Cookie.rfc2109

True si esta cookie fue recibida como una cookie RFC 2109 [https://tools.ietf.org/html/rfc2109.html] (es decir, la cookie fue recibida en una cabecera Set-Cookie, y el valor del cookie-attribute Versión en la cabecera fue de 1). Este atributo es proveído porque http.cookiejar puede “degradar” cookies RFC 2109 a cookies Netscape, en cuyo caso version es 0.

Cookie.port_specified

True si un puerto o un conjunto de puertos fue explícitamente especificado por el servidor (en la cabecera Set-Cookie / Set-Cookie2).

Cookie.domain_specified

True si un domino fue explícitamente especificado por el servidor.

Cookie.domain_initial_dot

True si el dominio explícitamente especificado por el servidor empieza con un punto ('.').

Las cookies pueden tener cookie-attribute no estándar adicionales. Se pueden acceder a estos usando los siguientes métodos:

Cookie.has_nonstandard_attr(name)

Retorna True si cookie tiene nombrado el cookie-attribute.

Cookie.get_nonstandard_attr(name, default=None)

Si la cookie tiene nombrado el cookie-attribute, retorna su valor. De otra manera, retorna default.

Cookie.set_nonstandard_attr(name, value)

Retorna el valor del nombrado cookie-attribute.

La clase Cookie también define el siguiente método:

Cookie.is_expired(now=None)

True si la cookie ha excedido el tiempo que el servidor solicitó para que expirara. Si now es dado (en segundos desde la parte temporal), retorna si la cookie ha expirado en el momento especificado.

Ejemplos

El primer ejemplo muestra el uso más común de http.cookiejar:

import http.cookiejar, urllib.request
cj = http.cookiejar.CookieJar()
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")

Este ejemplo ilustra como abrir una URL usando tus cookies Netscape, Mozilla, o Lynx (asume la convención Unix/Netscape para la ubicación del archivo de cookies):

import os, http.cookiejar, urllib.request
cj = http.cookiejar.MozillaCookieJar()
cj.load(os.path.join(os.path.expanduser("~"), ".netscape", "cookies.txt"))
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")

El siguiente ejemplo ilustra el uso de DefaultCookiePolicy. Activa las cookies RFC 2965 [https://tools.ietf.org/html/rfc2965.html], es más estricto con respecto a los dominios cuando se establecen o se retornan cookies Netscape, y bloquea algunos dominios para establecer o retornar cookies:

import urllib.request
from http.cookiejar import CookieJar, DefaultCookiePolicy
policy = DefaultCookiePolicy(
    rfc2965=True, strict_ns_domain=Policy.DomainStrict,
    blocked_domains=["ads.net", ".ads.net"])
cj = CookieJar(policy)
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")

xmlrpc — Módulos XMLRPC para cliente y servidor

XML-RPC es un método de Llamada a Procedimiento Remoto (o RPC en inglés) que usa XML usando HTTP como vía de transporte. Con esto, un cliente puede llamar a método con parámetros en un servidor remoto (el servidor se identifica mediante una URI) y traer de vuelta datos de forma estructurada.

xmlrpc es un paquete que agrupa los módulos, tanto de cliente como de servidor, que implementan XML-RPC. Los módulos son:

xmlrpc.client

xmlrpc.server

xmlrpc.client — acceso cliente XML-RPC

Source code: Lib/xmlrpc/client.py [https://github.com/python/cpython/tree/3.9/Lib/xmlrpc/client.py]

XML-RPC es un método de llamada a procedimiento remoto que utiliza XML pasado a través de HTTP(S) como transporte. Con él, un cliente puede llamar a métodos con parámetros en un servidor remoto (el servidor es nombrado por un URI) y recuperar datos estructurados. Este módulo admite la escritura de código de cliente XML-RPC; maneja todos los detalles de la traducción entre objetos de Python conformes y XML en el cable.

Advertencia

El módulo xmlrpc.client no es seguro contra datos construidos maliciosamente. Si necesita analizar datos que no son de confianza o no autenticados, consulte Vulnerabilidades XML.

Distinto en la versión 3.5: Para HTTPS URI, xmlrpc.client ahora realiza todas las comprobaciones necesarias de certificados y nombres de host de forma predeterminada.

class xmlrpc.client.ServerProxy(uri, transport=None, encoding=None, verbose=False, allow_none=False, use_datetime=False, use_builtin_types=False, *, headers=(), context=None)

Una ServerProxy instancia un objeto que gestiona la comunicación con un servidor XML-RPC remoto. El primer argumento requerido es un URI (Uniform Resource Indicator) y normalmente será la URL del servidor. El segundo argumento opcional es una instancia de fábrica de transporte; de forma predeterminada, es una instancia interna SafeTransport para https: URL y una instancia interna HTTP Transport en caso contrario. El tercer argumento opcional es una codificación, por defecto UTF-8. El cuarto argumento opcional es un indicador de depuración.

Los siguientes parámetros rigen el uso de la instancia de proxy retornada. Si allow_none es verdadero, la constante de Python None se traducirá a XML; el comportamiento predeterminado es que None genere un TypeError. Esta es una extensión de uso común para la especificación XML-RPC, pero no todos los clientes y servidores la admiten; ver http://ontosys.com/xml-rpc/extensions.php <https://web.archive.org/web/20130120074804/http://ontosys.com/xml-rpc/extensions.php> _ para una descripción. La flag use_builtin_types puede usarse para hacer que los valores de fecha/hora se presenten como : clase: objetos datetime.datetime y datos binarios que se presenten como objetos datetime.datetime y los datos binarios pueden ser presentados como objetos bytes; esta flag es falsa por defecto. Los objetos datetime.datetime, bytes y bytearray se pueden pasar a las llamadas. El parámetro header es una secuencia opcional de encabezados HTTP para enviar con cada solicitud, expresada como una secuencia de 2 tuplas que representan el nombre y el valor del encabezado. (por ejemplo, [(“Header-Name”, “value”)]). La flag obsoleta use_datetime es similar a use_builtin_types pero solo se aplica a los valores de fecha/hora.

Distinto en la versión 3.3: La flag use_builtin_types fue añadida.

Distinto en la versión 3.8: El parámetro headers fue añadida.

Tanto los transportes HTTP como HTTPS admiten la extensión de sintaxis de URL para la autenticación básica HTTP:http://user:pass@host:port/path. La parte user:pass se codificará en base64 como un encabezado HTTP de “Authorization” y se enviará al servidor remoto como parte del proceso de conexión al invocar un método XML-RPC. Solo necesita usar esto si el servidor remoto requiere un usuario y contraseña de autenticación básica. Si se proporciona una URL HTTPS, el context puede ser ssl.SSLContext y configura la configuración SSL de la conexión HTTPS subyacente.

La instancia retornada es un objeto proxy con métodos que se pueden utilizar para invocar las correspondientes llamadas RPC en el servidor remoto. Si el servidor remoto admite la API de introspección, el proxy también se puede utilizar para consultar al servidor remoto los métodos que admite (descubrimiento de servicios) y recuperar otros metadatos asociados al servidor.

Los tipos que son conformes (por ejemplo, que se pueden clasificar a través de XML) incluyen lo siguiente (y, excepto donde se indique, no se clasifican como el mismo tipo de Python):

Tipo XML-RPC

Tipo de Python

boolean

bool

int, i1, i2, i4, i8 or biginteger

int en el rango de -2147483648 a 2147483647. Los valores obtienen la etiqueta <int> .

double o float

float. Los valores obtienen la etiqueta <double>.

string

str

array

list o tuple que contiene elementos determinados. Las matrices se retornan como lists.

struct

dict. Las claves deben ser cadenas de caracteres, los valores pueden ser de cualquier tipo determinado. Pueden pasarse objetos de clases definidas por el usuario; sólo se transmite su atributo __dict__ .

dateTime.iso8601

DateTime o datetime.datetime. El tipo retornado depende de los valores de los indicadores use_builtin_types y use_datetime .

base64

Binary, bytes o bytearray. El tipo retornado depende del valor de la marca use_builtin_types.

nil

La constante None. Solo se permite pasar si allow_none es verdadero.

bigdecimal

decimal.Decimal. Retornado solo el tipo.

Este es el conjunto completo de tipos de datos admitidos por XML-RPC. Las llamadas a métodos también pueden generar una instancia especial Fault, que se usa para señalar errores del servidor XML-RPC, o ProtocolError que se usa para señalar un error en la capa de transporte HTTP/HTTPS. Ambos Fault y ProtocolError derivan de una clase base llamada Error. Tenga en cuenta que el módulo de cliente xmlrpc actualmente no clasifica instancias de subclases de tipos integrados.

Al pasar cadenas de caracteres, los caracteres especiales de XML como <, > y & se escaparán automáticamente. Sin embargo, es responsabilidad de la persona que llama asegurarse de que la cadena de caracteres esté libre de caracteres que no están permitidos en XML, como los caracteres de control con valores ASCII entre 0 y 31 (excepto, por supuesto, tabulación, nueva línea y retorno de carro); no hacer esto resultará en una solicitud XML-RPC que no es XML bien formado. Si tiene que pasar bytes arbitrarios a través de XML-RPC, use las clases bytes o bytearray o la clase contenedora Binary descrita a continuación.

Server se conserva como un alias para ServerProxy para compatibilidad con versiones anteriores. El nuevo código debe usar ServerProxy.

Distinto en la versión 3.5: Se agregó el argumento context.

Distinto en la versión 3.6: Se agregó soporte para etiquetas de tipo con prefijos (por ejemplo. ex:nil). Se agregó soporte para desagrupar los tipos adicionales utilizados por la implementación Apache XML-RPC para números: i1, i2, i8, biginteger, float y bigdecimal. Consulte http://ws.apache.org/xmlrpc/types.html para obtener una descripción.

Ver también

XML-RPC HOWTO [http://www.tldp.org/HOWTO/XML-RPC-HOWTO/index.html]

Una buena descripción del funcionamiento de XML-RPC y del software cliente en varios idiomas. Contiene prácticamente todo lo que un desarrollador de cliente XML-RPC necesita saber.

XML-RPC Introspection [http://xmlrpc-c.sourceforge.net/introspection.html]

Describe la extensión del protocolo XML-RPC para la introspección.

XML-RPC Specification [http://xmlrpc.scripting.com/spec.html]

La especificación oficial.

Objetos ServerProxy

La instancia de ServerProxy tiene un método correspondiente a cada llamada de procedimiento remoto aceptada por el servidor XML-RPC. Llamar al método realiza un RPC, enviado por nombre y firma de argumento (por ejemplo, el mismo nombre de método puede sobrecargarse con múltiples firmas de argumento). El RPC finaliza retornando un valor, que puede ser datos retornados en un tipo conforme o un objeto Fault o ProtocolError que indica un error.

Los servidores que admiten la API de introspección XML admiten algunos métodos comunes agrupados bajo el atributo reservado system:

ServerProxy.system.listMethods()

Este método retorna una lista de cadenas, una para cada método (que no es del sistema) admitido por el servidor XML-RPC.

ServerProxy.system.methodSignature(name)

Este método toma un parámetro, el nombre de un método implementado por el servidor XML-RPC. Retorna una matriz de posibles firmas para este método. Una firma es una variedad de tipos. El primero de estos tipos es el tipo de retorno del método, el resto son parámetros.

Debido a que se permiten múltiples firmas (es decir, sobrecarga), este método retorna una lista de firmas en lugar de un singleton.

Las propias firmas están restringidas a los parámetros de nivel superior esperados por un método. Por ejemplo, si un método espera una matriz de estructuras como parámetro y retorna una cadena de caracteres, su firma es simplemente «cadena, matriz». Si espera tres enteros y retorna una cadena, su firma es «string, int, int, int».

Si no se define una firma para el método, se retorna un valor que no es una matriz. En Python, esto significa que el tipo de valor retornado será diferente a una lista.

ServerProxy.system.methodHelp(name)

Este método toma un parámetro, el nombre de un método implementado por el servidor XML-RPC. Retorna una cadena de caracteres de documentación que describe el uso de ese método. Si no hay tal cadena de caracteres disponible, se retorna una cadena de caracteres vacía. La cadena de caracteres de documentación puede contener marcado HTML.

Distinto en la versión 3.5: Las instancias de ServerProxy admiten el protocolo context manager para cerrar el transporte subyacente.

A continuación se muestra un ejemplo práctico. El código del servidor:

from xmlrpc.server import SimpleXMLRPCServer

def is_even(n):
    return n % 2 == 0

server = SimpleXMLRPCServer(("localhost", 8000))
print("Listening on port 8000...")
server.register_function(is_even, "is_even")
server.serve_forever()

El código de cliente para el servidor anterior:

import xmlrpc.client

with xmlrpc.client.ServerProxy("http://localhost:8000/") as proxy:
    print("3 is even: %s" % str(proxy.is_even(3)))
    print("100 is even: %s" % str(proxy.is_even(100)))

Objetos DateTime

class xmlrpc.client.DateTime

Esta clase puede inicializarse con segundos desde la época, una tupla de tiempo, una cadena de fecha/hora ISO 8601 o una instancia datetime.datetime. Tiene los siguientes métodos, soportados principalmente para uso interno por el código de clasificación/eliminación de clasificación:

decode(string)

Acepta una cadena de caracteres como el nuevo valor de tiempo de la instancia.

encode(out)

Escribe la codificación XML-RPC de este elemento DateTime en el objeto de flujo out.

También es compatible con algunos de los operadores integrados de Python a través de una rica comparación y métodos __repr__().

A continuación se muestra un ejemplo práctico. El código del servidor:

import datetime
from xmlrpc.server import SimpleXMLRPCServer
import xmlrpc.client

def today():
    today = datetime.datetime.today()
    return xmlrpc.client.DateTime(today)

server = SimpleXMLRPCServer(("localhost", 8000))
print("Listening on port 8000...")
server.register_function(today, "today")
server.serve_forever()

El código de cliente para el servidor anterior:

import xmlrpc.client
import datetime

proxy = xmlrpc.client.ServerProxy("http://localhost:8000/")

today = proxy.today()
# convert the ISO8601 string to a datetime object
converted = datetime.datetime.strptime(today.value, "%Y%m%dT%H:%M:%S")
print("Today: %s" % converted.strftime("%d.%m.%Y, %H:%M"))

Objetos binarios

class xmlrpc.client.Binary

Esta clase puede inicializarse a partir de datos de bytes (que pueden incluir NUL). El acceso principal al contenido de un objeto Binary lo proporciona un atributo:

data

Los datos binarios encapsulados por la instancia Binary. Los datos se proporcionan como un objeto bytes.

Los objetos Binary tienen los siguientes métodos, soportados principalmente para uso interno por el código de clasificación/desagrupación:

decode(bytes)

Acepta un objeto base64 bytes y se descodifica como los nuevos datos de la instancia.

encode(out)

Escribe la codificación XML-RPC base 64 de este elemento binario en el objeto de flujo out.

Los datos codificados tendrán líneas nuevas cada 76 caracteres según RFC 2045 sección 6.8 RFC 2045#section-6.8 [https://tools.ietf.org/html/rfc2045.html#section-6.8], que era la especificación estándar de facto base64 cuando se escribió la especificación XML-RPC.

También admite algunos de los operadores integrados de Python a través de los métodos __eq__() and __ne__().

Ejemplo de uso de los objetos binarios. Vamos a transferir una imagen sobre XMLRPC:

from xmlrpc.server import SimpleXMLRPCServer
import xmlrpc.client

def python_logo():
    with open("python_logo.jpg", "rb") as handle:
        return xmlrpc.client.Binary(handle.read())

server = SimpleXMLRPCServer(("localhost", 8000))
print("Listening on port 8000...")
server.register_function(python_logo, 'python_logo')

server.serve_forever()

El cliente obtiene la imagen y la guarda en un archivo:

import xmlrpc.client

proxy = xmlrpc.client.ServerProxy("http://localhost:8000/")
with open("fetched_python_logo.jpg", "wb") as handle:
    handle.write(proxy.python_logo().data)

Objetos Faults

class xmlrpc.client.Fault

Un objeto Fault encapsula el contenido de una etiqueta de error XML-RPC. Los objetos de error tienen los siguientes atributos:

faultCode

Una cadena de caracteres que indica el tipo de fallo.

faultString

Una cadena de caracteres que contiene un mensaje de diagnóstico asociado con el fallo.

En el siguiente ejemplo vamos a causar intencionalmente un Fault al retornar un objeto de tipo complejo. El código del servidor:

from xmlrpc.server import SimpleXMLRPCServer

# A marshalling error is going to occur because we're returning a
# complex number
def add(x, y):
    return x+y+0j

server = SimpleXMLRPCServer(("localhost", 8000))
print("Listening on port 8000...")
server.register_function(add, 'add')

server.serve_forever()

El código de cliente para el servidor anterior:

import xmlrpc.client

proxy = xmlrpc.client.ServerProxy("http://localhost:8000/")
try:
    proxy.add(2, 5)
except xmlrpc.client.Fault as err:
    print("A fault occurred")
    print("Fault code: %d" % err.faultCode)
    print("Fault string: %s" % err.faultString)

Objetos ProtocolError

class xmlrpc.client.ProtocolError

El objeto ProtocolError describe un error de protocolo en la capa de transporte subyacente (como un error 404 “no encontrado” si el servidor nombrado por el URI no existe). Tiene los siguientes atributos:

url

El URI o URL que provocó el error.

errcode

El código de error.

errmsg

El mensaje de error o la cadena de caracteres de diagnóstico.

headers

Un diccionario que contiene los encabezados de la solicitud HTTP/HTTPS que desencadenó el error.

En el siguiente ejemplo, vamos a causar intencionalmente un ProtocolError proporcionando un URI inválido:

import xmlrpc.client

# create a ServerProxy with a URI that doesn't respond to XMLRPC requests
proxy = xmlrpc.client.ServerProxy("http://google.com/")

try:
    proxy.some_method()
except xmlrpc.client.ProtocolError as err:
    print("A protocol error occurred")
    print("URL: %s" % err.url)
    print("HTTP/HTTPS headers: %s" % err.headers)
    print("Error code: %d" % err.errcode)
    print("Error message: %s" % err.errmsg)

Objectos MultiCall

El objeto MultiCall proporciona una forma de encapsular múltiples llamadas a un servidor remoto en una sola solicitud 1.

class xmlrpc.client.MultiCall(server)

Crea un objeto usado para llamadas al método boxcar. server es el objetivo final de la llamada. Se pueden realizar llamadas al objeto de resultado, pero retornarán inmediatamente None y solo almacenarán el nombre y los parámetros de la llamada en el objeto MultiCall. Llamar al objeto en sí hace que todas las llamadas almacenadas se transmitan como una única solicitud de system.multicall. El resultado de esta llamada es un generator; iterar sobre este generador produce los resultados individuales.

A continuación se muestra un ejemplo de uso de esta clase. El código del servidor:

from xmlrpc.server import SimpleXMLRPCServer

def add(x, y):
    return x + y

def subtract(x, y):
    return x - y

def multiply(x, y):
    return x * y

def divide(x, y):
    return x // y

# A simple server with simple arithmetic functions
server = SimpleXMLRPCServer(("localhost", 8000))
print("Listening on port 8000...")
server.register_multicall_functions()
server.register_function(add, 'add')
server.register_function(subtract, 'subtract')
server.register_function(multiply, 'multiply')
server.register_function(divide, 'divide')
server.serve_forever()

El código de cliente para el servidor anterior:

import xmlrpc.client

proxy = xmlrpc.client.ServerProxy("http://localhost:8000/")
multicall = xmlrpc.client.MultiCall(proxy)
multicall.add(7, 3)
multicall.subtract(7, 3)
multicall.multiply(7, 3)
multicall.divide(7, 3)
result = multicall()

print("7+3=%d, 7-3=%d, 7*3=%d, 7//3=%d" % tuple(result))

Funciones de Conveniencia

xmlrpc.client.dumps(params, methodname=None, methodresponse=None, encoding=None, allow_none=False)

Convierta params en una solicitud XML-RPC. o en una respuesta si methodresponse es verdadero. params puede ser una tupla de argumentos o una instancia de la clase de excepción Fault. Si methodresponse es verdadero, solo se puede devolver un único valor, lo que significa que params debe tener una longitud de 1. encoding, si se proporciona, es la codificación que se utilizará en el XML generado; el predeterminado es UTF-8. El valor de Python None no se puede usar en XML-RPC estándar; para permitir su uso a través de una extensión, proporcione un valor verdadero para allow_none.

xmlrpc.client.loads(data, use_datetime=False, use_builtin_types=False)

Convierte una solicitud o respuesta XML-RPC en objetos Python, un (params, methodname). params es una tupla de argumento; methodname es una cadena de caracteres, o None si no hay ningún nombre de método presente en el paquete. Si el paquete XML-RPC representa una condición de falla, esta función generará una excepción Fault. La flag use_builtin_types puede usarse para hacer que los valores de fecha/hora se presenten como objetos de datetime.datetime y datos binarios que se presenten como objetos de bytes; esta flag es falsa por defecto.

La flag obsoleta use_datetime es similar a use_builtin_types pero esto aplica solo a valores fecha/hora.

Distinto en la versión 3.3: La flag use_builtin_types fue añadida.

Ejemplo de Uso de Cliente

# simple test program (from the XML-RPC specification)
from xmlrpc.client import ServerProxy, Error

# server = ServerProxy("http://localhost:8000") # local server
with ServerProxy("http://betty.userland.com") as proxy:

    print(proxy)

    try:
        print(proxy.examples.getStateName(41))
    except Error as v:
        print("ERROR", v)

Para acceder a un servidor XML-RPC a través de un proxy HTTP, debe definir un transporte personalizado. El siguiente ejemplo muestra cómo:

import http.client
import xmlrpc.client

class ProxiedTransport(xmlrpc.client.Transport):

    def set_proxy(self, host, port=None, headers=None):
        self.proxy = host, port
        self.proxy_headers = headers

    def make_connection(self, host):
        connection = http.client.HTTPConnection(*self.proxy)
        connection.set_tunnel(host, headers=self.proxy_headers)
        self._connection = host, connection
        return connection

transport = ProxiedTransport()
transport.set_proxy('proxy-server', 8080)
server = xmlrpc.client.ServerProxy('http://betty.userland.com', transport=transport)
print(server.examples.getStateName(41))

Ejemplo de Uso de Cliente y Servidor

Vea Ejemplo de SimpleXMLRPCServer.

Pie de notas

1

Este enfoque se presentó por primera vez en una discusión en xmlrpc.com [https://web.archive.org/web/20060624230303/http://www.xmlrpc.com/discuss/msgReader$1208?mode=topic].

xmlrpc.server — Servidores básicos XML-RPC

Código fuente: Lib/xmlrpc/server.py [https://github.com/python/cpython/tree/3.9/Lib/xmlrpc/server.py]

El módulo xmlrpc.server proporciona un marco de servidor básico para servidores XML-RPC escritos en Python. Los servidores pueden ser independientes, utilizando SimpleXMLRPCServer, o integrados en un entorno CGI, utilizando CGIXMLRPCRequestHandler.

Advertencia

El módulo xmlrpc.server no es seguro contra datos construidos maliciosamente. Si necesita analizar sintácticamente datos no confiables o no autentificados, consulte Vulnerabilidades XML.

class xmlrpc.server.SimpleXMLRPCServer(addr, requestHandler=SimpleXMLRPCRequestHandler, logRequests=True, allow_none=False, encoding=None, bind_and_activate=True, use_builtin_types=False)

Crea una nueva instancia de servidor. Esta clase proporciona métodos para el registro de funciones que pueden ser llamados por el protocolo XML-RPC. El parámetro requestHandler debe ser un generador para las instancias del controlador de solicitudes; el valor predeterminado es SimpleXMLRPCRequestHandler. Los parámetros addr y requestHandler se pasan al constructor socketserver. TCPServer. Si logRequests es verdadero (valor predeterminado), se registrarán las solicitudes; establecer este parámetro como falso desactivará el registro. Los parámetros allow_none y encoding se pasan a xmlrpc.client y controlan las respuestas XML-RPC que se devolverán desde el servidor. El parámetro bind_and_activate controla si server_bind() y server_activate() son llamados inmediatamente por el constructor; por defecto es verdadero. Establecerlo como false permite que el código manipule la variable de clase allow_reuse_address antes de enlazar la dirección. El parámetro use_builtin_types se pasa a la función loads() y controla qué tipos se procesan cuando se reciben valores de fecha y hora o datos binarios; el valor predeterminado es false.

Distinto en la versión 3.3: Se ha añadido el indicador use_builtin_types.

class xmlrpc.server.CGIXMLRPCRequestHandler(allow_none=False, encoding=None, use_builtin_types=False)

Crea una nueva instancia para gestionar solicitudes XML-RPC en un entorno CGI. Los parámetros allow_none y encoding se pasan a xmlrpc.client y controlan las respuestas XML-RPC que se devolverán desde el servidor. El parámetro use_builtin_types se pasa a la función loads() y controla qué tipos se procesan cuando se reciben valores de fecha y hora o datos binarios; el valor predeterminado es falso.

Distinto en la versión 3.3: Se ha añadido el indicador use_builtin_types.

class xmlrpc.server.SimpleXMLRPCRequestHandler

Crea una nueva instancia del controlador de solicitudes. Este controlador de solicitudes admite solicitudes POST y modifica el registro para que se respete el parámetro logRequests del parámetro constructor SimpleXMLRPCServer.

Objetos SimpleXMLRPCServer

La clase SimpleXMLRPCServer se basa en socketserver.TCPServer y proporciona un medio para crear servidores XML-RPC simples e independientes.

SimpleXMLRPCServer.register_function(function=None, name=None)

Registra una función que pueda responder a solicitudes XML-RPC. Si se proporciona name, este será el nombre del método asociado con function, en otro caso se utilizará function.__name__. name es una cadena de texto, y puede contener caracteres no permitidos en los identificadores de Python, incluido el caracter de punto.

Este método también se puede utilizar como decorador. Cuando se usa como decorador, name solo se puede dar como un argumento de palabra clave para registrar function bajo nombre. Si no se proporciona name, se usará function.__name__.

Distinto en la versión 3.7: register_function() puede ser usado como decorador.

SimpleXMLRPCServer.register_instance(instance, allow_dotted_names=False)

Registre un objeto que se usa para exponer nombre de métodos que no se han registrado usando register_function(). Si instance contiene un método _dispatch(), este será llamado con el nombre del método solicitado y los parámetros de la solicitud. Su API es def _dispatch(self, method, params) (tenga en cuenta que params no representa una lista de argumentos variables). Si se invoca a una función subyacente para realizar su tarea, esa función es llamada como func(*params), expandiendo la lista de parámetros. El valor de retorno de _dispatch() se retorna al cliente como resultado. Si instance no tiene un método _dispatch(), se busca un atributo que coincida con el nombre del método solicitado.

Si el argumento opcional allow_dotted_names es verdadero y la instancia no tiene un método _dispatch(), entonces si el nombre solicitado contiene puntos, cada componente del nombre del método se busca individualmente, con el efecto con el efecto que produce una búsqueda jerárquica simple. El valor encontrado en esta búsqueda es entonces llamado con los parámetros de la solicitud y el valor de retorno se devuelve al cliente.

Advertencia

Habilitando la opción allow_dotted_names permite a los intrusos acceder a las variables globales de su módulo y puede permitir que los intrusos ejecuten código arbitrario en su máquina. Utilice esta opción únicamente en una red cerrada y segura.

SimpleXMLRPCServer.register_introspection_functions()

Registre las funciones de introspección XML-RPC system.listMethods, system.methodHelp y system.methodSignature.

SimpleXMLRPCServer.register_multicall_functions()

Registre la función de llamada múltiple XML-RPC system.multicall.

SimpleXMLRPCRequestHandler.rpc_paths

Un valor de atributo que debe ser una tupla que enumere porciones de rota válidas de la URL para recibir solicitudes XML-RPC. Las solicitudes publicadas en otras rutas darán como resultado un error HTTP 404 «no existe tal página». Si esta tupla está vacía, todas las rutas se considerarán válidas. El valor predeterminado es ('/', '/RPC2').

Ejemplo de SimpleXMLRPCServer

Código del servidor:

from xmlrpc.server import SimpleXMLRPCServer
from xmlrpc.server import SimpleXMLRPCRequestHandler

# Restrict to a particular path.
class RequestHandler(SimpleXMLRPCRequestHandler):
    rpc_paths = ('/RPC2',)

# Create server
with SimpleXMLRPCServer(('localhost', 8000),
                        requestHandler=RequestHandler) as server:
    server.register_introspection_functions()

    # Register pow() function; this will use the value of
    # pow.__name__ as the name, which is just 'pow'.
    server.register_function(pow)

    # Register a function under a different name
    def adder_function(x, y):
        return x + y
    server.register_function(adder_function, 'add')

    # Register an instance; all the methods of the instance are
    # published as XML-RPC methods (in this case, just 'mul').
    class MyFuncs:
        def mul(self, x, y):
            return x * y

    server.register_instance(MyFuncs())

    # Run the server's main loop
    server.serve_forever()

El siguiente código de cliente llamará a los métodos disponibles por el servidor anterior:

import xmlrpc.client

s = xmlrpc.client.ServerProxy('http://localhost:8000')
print(s.pow(2,3))  # Returns 2**3 = 8
print(s.add(2,3))  # Returns 5
print(s.mul(5,2))  # Returns 5*2 = 10

# Print list of available methods
print(s.system.listMethods())

register_function() también se puede utilizar como decorador. El ejemplo de servidor anterior puede registrar funciones a modo de decorador:

from xmlrpc.server import SimpleXMLRPCServer
from xmlrpc.server import SimpleXMLRPCRequestHandler

class RequestHandler(SimpleXMLRPCRequestHandler):
    rpc_paths = ('/RPC2',)

with SimpleXMLRPCServer(('localhost', 8000),
                        requestHandler=RequestHandler) as server:
    server.register_introspection_functions()

    # Register pow() function; this will use the value of
    # pow.__name__ as the name, which is just 'pow'.
    server.register_function(pow)

    # Register a function under a different name, using
    # register_function as a decorator. *name* can only be given
    # as a keyword argument.
    @server.register_function(name='add')
    def adder_function(x, y):
        return x + y

    # Register a function under function.__name__.
    @server.register_function
    def mul(x, y):
        return x * y

    server.serve_forever()

El siguiente ejemplo incluido en el módulo Lib/xmlrpc/server.py muestra un servidor que permite nombres con puntos y registra una función de llamada múltiple.

Advertencia

Habilitar la opción allow_dotted_names permite a los intrusos acceder a las variables globales de su módulo y puede permitir que los intrusos ejecuten código arbitrario en su máquina. Utilice este ejemplo únicamente dentro de una red cerrada y segura.

import datetime

class ExampleService:
    def getData(self):
        return '42'

    class currentTime:
        @staticmethod
        def getCurrentTime():
            return datetime.datetime.now()

with SimpleXMLRPCServer(("localhost", 8000)) as server:
    server.register_function(pow)
    server.register_function(lambda x,y: x+y, 'add')
    server.register_instance(ExampleService(), allow_dotted_names=True)
    server.register_multicall_functions()
    print('Serving XML-RPC on localhost port 8000')
    try:
        server.serve_forever()
    except KeyboardInterrupt:
        print("\nKeyboard interrupt received, exiting.")
        sys.exit(0)

Esta demostración de ExampleService se puede invocar desde la línea de comando:

python -m xmlrpc.server

El cliente que interactúa con el servidor anterior está incluido en Lib/xmlrpc/client.py:

server = ServerProxy("http://localhost:8000")

try:
    print(server.currentTime.getCurrentTime())
except Error as v:
    print("ERROR", v)

multi = MultiCall(server)
multi.getData()
multi.pow(2,9)
multi.add(1,2)
try:
    for response in multi():
        print(response)
except Error as v:
    print("ERROR", v)

Este cliente que interactúa con el servidor XMLRPC de demostración se puede invocar como:

python -m xmlrpc.client

CGIXMLRPCRequestHandler

La clase CGIXMLRPCRequestHandler se puede usar para manejar solicitudes XML-RPC enviadas a scripts Python CGI.

CGIXMLRPCRequestHandler.register_function(function=None, name=None)

Registra una función que pueda responder a solicitudes XML-RPC. Si se proporciona name, este será el nombre del método asociado con function, en otro caso se utilizará function.__name__. name es una cadena de texto, y puede contener caracteres no permitidos en los identificadores de Python, incluido el caracter de punto.

Este método también se puede utilizar como decorador. Cuando se usa como decorador, name solo se puede dar como un argumento de palabra clave para registrar function bajo nombre. Si no se proporciona name, se usará function.__name__.

Distinto en la versión 3.7: register_function() puede ser usado como decorador.

CGIXMLRPCRequestHandler.register_instance(instance)

Registra un objeto que se usa para exponer nombres de métodos que no se han registrado usando register_function(). Si la instancia contiene un método _dispatch(), se llama con el nombre del método solicitado y los parámetros de la solicitud; el valor de retorno se devuelve al cliente como resultado. Si la instancia no tiene un método _dispatch(), se busca un atributo que coincida con el nombre del método solicitado; si el nombre del método contiene puntos, cada componente del nombre del método se busca individualmente, con el efecto con el efecto que produce una búsqueda jerárquica simple. El valor encontrado en esta búsqueda es entonces llamado con los parámetros de la solicitud y el valor de retorno se devuelve al cliente.

CGIXMLRPCRequestHandler.register_introspection_functions()

Registra las funciones de introspección system.listMethods, system.methodHelp y system.methodSignature.

CGIXMLRPCRequestHandler.register_multicall_functions()

Registra la función de llamada múltiple XML-RPC system.multicall.

CGIXMLRPCRequestHandler.handle_request(request_text=None)

Maneja una solicitud XML-RPC. Si se proporciona request_text, deberían ser los datos POST proporcionados por el servidor HTTP, de lo contrario se utilizará el contenido de stdin.

Ejemplo:

class MyFuncs:
    def mul(self, x, y):
        return x * y

handler = CGIXMLRPCRequestHandler()
handler.register_function(pow)
handler.register_function(lambda x,y: x+y, 'add')
handler.register_introspection_functions()
handler.register_instance(MyFuncs())
handler.handle_request()

Documentando el servidor XMLRPC

Estas clases amplían las clases anteriores para proporcionar documentación HTML en respuesta a solicitudes HTTP GET. Los servidores pueden ser independientes, usando DocXMLRPCServer, o integrados en un entorno CGI, usando DocCGIXMLRPCRequestHandler.

class xmlrpc.server.DocXMLRPCServer(addr, requestHandler=DocXMLRPCRequestHandler, logRequests=True, allow_none=False, encoding=None, bind_and_activate=True, use_builtin_types=True)

Crea una nueva instancia de servidor. Todos los parámetros tienen el mismo significado que para SimpleXMLRPCServer; requestHandler tiene como valor predeterminado DocXMLRPCRequestHandler.

Distinto en la versión 3.3: Se ha añadido el indicador use_builtin_types.

class xmlrpc.server.DocCGIXMLRPCRequestHandler

Crea una nueva instancia para manejar solicitudes XML-RPC en un entorno CGI.

class xmlrpc.server.DocXMLRPCRequestHandler

Crea una nueva instancia de controlador de solicitudes. Este controlador de solicitudes admite solicitudes XML-RPC POST, solicitudes GET de documentación y modifica el registro para que se respete el parámetro logRequests del parámetro constructor DocXMLRPCServer.

Objetos DocXMLRPCServer

La clase DocXMLRPCServer se deriva de SimpleXMLRPCServer y proporciona un medio para crear servidores XML-RPC autónomos y autodocumentados. Las solicitudes HTTP POST se manejan como llamadas al método XML-RPC. Las solicitudes HTTP GET se manejan generando documentación HTML al estilo pydoc. Esto permite que un servidor proporcione su propia documentación basada en web.

DocXMLRPCServer.set_server_title(server_title)

Establezca el título utilizado en la documentación HTML generada. Este título se utilizará dentro del elemento HTML «title».

DocXMLRPCServer.set_server_name(server_name)

Establezca el nombre utilizado en la documentación HTML generada. Este nombre aparecerá en la parte superior de la documentación generada dentro de un elemento «h1».

DocXMLRPCServer.set_server_documentation(server_documentation)

Establezca la descripción utilizada en la documentación HTML generada. Esta descripción aparecerá como un párrafo, debajo del nombre del servidor, en la documentación.

DocCGIXMLRPCRequestHandler

La clase DocCGIXMLRPCRequestHandler se deriva de CGIXMLRPCRequestHandler y proporciona un medio para crear scripts CGI XML-RPC autodocumentados. Las solicitudes HTTP POST se manejan como llamadas al método XML-RPC. Las solicitudes HTTP GET se manejan generando documentación HTML al estilo pydoc. Esto permite que un servidor proporcione su propia documentación basada en web.

DocCGIXMLRPCRequestHandler.set_server_title(server_title)

Establezca el título utilizado en la documentación HTML generada. Este título se utilizará dentro del elemento HTML «title».

DocCGIXMLRPCRequestHandler.set_server_name(server_name)

Establezca el nombre utilizado en la documentación HTML generada. Este nombre aparecerá en la parte superior de la documentación generada dentro de un elemento «h1».

DocCGIXMLRPCRequestHandler.set_server_documentation(server_documentation)

Establezca la descripción utilizada en la documentación HTML generada. Esta descripción aparecerá como un párrafo, debajo del nombre del servidor, en la documentación.

ipaddress — Biblioteca de manipulación IPv4/IPv6

Código fuente: Lib/ipaddress.py [https://github.com/python/cpython/tree/3.9/Lib/ipaddress.py]

ipaddress proporciona las capacidades para crear, manipular y operar en direcciones y redes IPv4 e IPv6.

Las funciones y clases de este módulo facilitan el control de varias tareas relacionadas con las direcciones IP, incluido comprobar si dos hosts están en la misma subred o no, iterar sobre todos los hosts de una subred determinada, comprobar si una cadena de caracteres representa o no una dirección IP válida o una definición de red, etc.

Esta es la referencia completa de la API del módulo: para obtener información general y una introducción, véase Introducción al modulo ipaddress.

Nuevo en la versión 3.3.

Funciones de fábrica de conveniencia

El módulo ipaddress proporciona funciones de fábrica para crear convenientemente direcciones IP, redes e interfaces:

ipaddress.ip_address(address)

Return an IPv4Address or IPv6Address object depending on the IP address passed as argument. Either IPv4 or IPv6 addresses may be supplied; integers less than 2**32 will be considered to be IPv4 by default. A ValueError is raised if address does not represent a valid IPv4 or IPv6 address.

>>> ipaddress.ip_address('192.168.0.1')
IPv4Address('192.168.0.1')
>>> ipaddress.ip_address('2001:db8::')
IPv6Address('2001:db8::')

ipaddress.ip_network(address, strict=True)

Return an IPv4Network or IPv6Network object depending on the IP address passed as argument. address is a string or integer representing the IP network. Either IPv4 or IPv6 networks may be supplied; integers less than 2**32 will be considered to be IPv4 by default. strict is passed to IPv4Network or IPv6Network constructor. A ValueError is raised if address does not represent a valid IPv4 or IPv6 address, or if the network has host bits set.

>>> ipaddress.ip_network('192.168.0.0/28')
IPv4Network('192.168.0.0/28')

ipaddress.ip_interface(address)

Return an IPv4Interface or IPv6Interface object depending on the IP address passed as argument. address is a string or integer representing the IP address. Either IPv4 or IPv6 addresses may be supplied; integers less than 2**32 will be considered to be IPv4 by default. A ValueError is raised if address does not represent a valid IPv4 or IPv6 address.

Una desventaja de estas funciones de conveniencia es que la necesidad de manejar ambos formatos IPv4 e IPv6 significa que los mensajes de error proveen información mínima sobre el error preciso, ya que las funciones no saben si se pretendía usar el formato IPv4 o IPv6. Un reporte de error más detallado se puede obtener llamando directamente a los constructores de clase específicos para la versión apropiada.

Direcciones IP

Objetos de dirección

Los objetos IPv4Address y IPv6Address comparten muchos atributos comunes. Algunos atributos que son sólo significativos para direcciones IPv6 también están implementados para los objetos IPv4Address, para que sea más fácil escribir código que maneje ambas versiones de IP correctamente. Los objetos de dirección son hashable, por lo que se pueden utilizar como claves en diccionarios.

class ipaddress.IPv4Address(address)

Construye una dirección IPv4. Se genera un AddressValueError si address no es una dirección IPv4 válida.

Lo siguiente constituye una dirección IPv4 válida:

A string in decimal-dot notation, consisting of four decimal integers in the inclusive range 0–255, separated by dots (e.g. 192.168.0.1). Each integer represents an octet (byte) in the address. Leading zeroes are not tolerated to prevent confusion with octal notation.

Un entero que cabe en 32 bits.

Un entero empaquetado en un objeto bytes de longitud 4 (el octeto más significativo primero).

>>> ipaddress.IPv4Address('192.168.0.1')
IPv4Address('192.168.0.1')
>>> ipaddress.IPv4Address(3232235521)
IPv4Address('192.168.0.1')
>>> ipaddress.IPv4Address(b'\xC0\xA8\x00\x01')
IPv4Address('192.168.0.1')

Distinto en la versión 3.8: Leading zeros are tolerated, even in ambiguous cases that look like octal notation.

Distinto en la versión 3.10: Leading zeros are no longer tolerated and are treated as an error. IPv4 address strings are now parsed as strict as glibc inet_pton().

Distinto en la versión 3.9.5: The above change was also included in Python 3.9 starting with version 3.9.5.

Distinto en la versión 3.8.12: The above change was also included in Python 3.8 starting with version 3.8.12.

version

El número de versión apropiado: 4 para IPv4, 6 para IPv6.

max_prefixlen

El número total de bits en la representación de la dirección para esta versión: 32 para IPv4, 128 para IPv6.

El prefijo define el número de bits iniciales en una dirección que son comparados para determinar si una dirección es o no parte de una red.

compressed

exploded

La representación de cadena de caracteres en notación decimal con puntos. Los ceros a la izquierda nunca se incluyen en la representación.

Como IPv4 no define una notación abreviada para direcciones con octetos establecidos en cero, estos dos atributos son siempre los mismos que str(addr) para direcciones IPv4. Exponer estos atributos hace que sea más fácil escribir código de visualización que pueda manejar direcciones IPv4 e IPv46.

packed

La representación binaria de esta dirección - un objeto bytes de la longitud apropiada (octeto más significativo primero). Esta es 4 bytes para IPv4 y 16 bytes para IPv6.

reverse_pointer

El nombre del registro PTR DNS inverso para la dirección IP, por ejemplo:

>>> ipaddress.ip_address("127.0.0.1").reverse_pointer
'1.0.0.127.in-addr.arpa'
>>> ipaddress.ip_address("2001:db8::1").reverse_pointer
'1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa'

Este es el nombre que podría usarse para realizar una búsqueda PTR, no el nombre de host resuelto en sí.

Nuevo en la versión 3.5.

is_multicast

True si la dirección está reservada para uso de multidifusión. Véase RFC 3171 [https://tools.ietf.org/html/rfc3171.html] (para IPv4) o RFC 2373 [https://tools.ietf.org/html/rfc2373.html] (para IPv6).

is_private

True si la dirección está asignada a redes privadas. Véase iana-ipv4-special-registry [https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml] (para IPv4) o iana-ipv6-special-registry [https://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.xhtml] (para IPv6).

is_global

True si la dirección está asignada a redes públicas. Véase iana-ipv4-special-registry [https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml] (para IPv4) o iana-ipv6-special-registry [https://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.xhtml] (para IPv6).

Nuevo en la versión 3.4.

is_unspecified

True si la dirección no está especificada. Véase RFC 5735 [https://tools.ietf.org/html/rfc5735.html] (para IPv4) o RFC 2373 [https://tools.ietf.org/html/rfc2373.html] (para IPv6).

is_reserved

True si la dirección está reservada por la IETF.

is_loopback

True si esta es una dirección de loopback. Véase RFC 3330 [https://tools.ietf.org/html/rfc3330.html] (para IPv4) o RFC 2373 [https://tools.ietf.org/html/rfc2373.html] (para IPv6).

is_link_local

True si la dirección está reservada para uso de enlace-local. Véase RFC 3927 [https://tools.ietf.org/html/rfc3927.html].

IPv4Address.__format__(fmt)

Retorna una representación en cadena de caracteres de la dirección IP, controlada por una cadena de formato explícito. fmt puede ser uno de los siguientes: 's', la opción predeterminada, equivalente a str(), 'b' para una cadena binaria con relleno de ceros, 'X' o 'x' para una representación hexadecimal en mayúsculas o minúsculas, o 'n', que es equivalente a 'b' para direcciones IPv4 y 'x' para IPv6. Para representaciones binarias y hexadecimales, el especificador de formulario '#' y la opción de agrupación '_' están disponibles. __format__ es utilizado por format, str.format y f-strings.

>>> format(ipaddress.IPv4Address('192.168.0.1'))
'192.168.0.1'
>>> '{:#b}'.format(ipaddress.IPv4Address('192.168.0.1'))
'0b11000000101010000000000000000001'
>>> f'{ipaddress.IPv6Address("2001:db8::1000"):s}'
'2001:db8::1000'
>>> format(ipaddress.IPv6Address('2001:db8::1000'), '_X')
'2001_0DB8_0000_0000_0000_0000_0000_1000'
>>> '{:#_n}'.format(ipaddress.IPv6Address('2001:db8::1000'))
'0x2001_0db8_0000_0000_0000_0000_0000_1000'

Nuevo en la versión 3.9.

class ipaddress.IPv6Address(address)

Construye una dirección IPv6. Se genera un AddressValueError si address no es una dirección IPv6 válida.

Lo siguiente constituye una dirección IPv6 válida:

Una cadena de caracteres que consta de 8 grupos de cuatro dígitos hexadecimales, cada grupo representa 16 bits. Los grupos son separados por dos puntos. Esto describe una notación completa (larga). La cadena también puede ser comprimida (notación corta) de varias maneras. Véase RFC 4291 [https://tools.ietf.org/html/rfc4291.html] para más detalles. Por ejemplo, "0000:0000:0000:0000:0000:0abc:0007:0def" puede ser comprimida a "::abc:7:def".

Opcionalmente, la cadena de caracteres también puede tener un ID alcance, expresado con un sufijo %scope_id. Si está presente, el ID de alcance no debe estar vacío y no puede contener %. Consulte RFC 4007 [https://tools.ietf.org/html/rfc4007.html] para obtener más detalles. Por ejemplo, fe80::1234% 1 podría identificar la dirección fe80::1234 en el primer enlace del nodo.

Un entero que cabe en 128 bits.

Un entero empaquetado en un objeto bytes de longitud 16, big-endian.

>>> ipaddress.IPv6Address('2001:db8::1000')
IPv6Address('2001:db8::1000')
>>> ipaddress.IPv6Address('ff02::5678%1')
IPv6Address('ff02::5678%1')

compressed

La forma abreviada de la representación de la dirección, omitiendo los ceros a la izquierda en los grupos y la secuencia más larga de grupos que consisten completamente de ceros colapsada en un sólo grupo vacío.

Este es también el valor retornado por str(addr) para direcciones IPv6.

exploded

La forma larga de la representación de la dirección, incluidos todos los ceros iniciales y los grupos que consisten completamente de ceros.

Para los siguientes atributos, véase la documentación correspondiente de la clase IPv4Address:

packed

reverse_pointer

version

max_prefixlen

is_multicast

is_private

is_global

is_unspecified

is_reserved

is_loopback

is_link_local

Nuevo en la versión 3.4: is_global

is_site_local

True si la dirección está reservada para el uso local del sitio. Tenga en cuenta que el espacio de direcciones locales del sitio ha quedado en desuso por RFC 3879 [https://tools.ietf.org/html/rfc3879.html]. Utilice is_private para probar si esta dirección está en el espacio de direcciones locales únicas según lo definido por RFC 4193 [https://tools.ietf.org/html/rfc4193.html].

ipv4_mapped

Para las direcciones que parecen ser direcciones IPv4 mapeadas (comenzando con ::FFFF/96), esta propiedad informará la dirección IPv4 incrustada. Para cualquier otra dirección, esta propiedad será None.

scope_id

Para las direcciones con alcance como es definido por RFC 4007 [https://tools.ietf.org/html/rfc4007.html], esta propiedad identifica la zona particular del alcance de la dirección a la que pertenece dicha dirección, como una cadena de caracteres. Cuando no se especifica ninguna zona de alcance, esta propiedad será None.

sixtofour

Para las direcciones que parecen ser direcciones 6to4 (comenzando con 2002::/16) según lo definido por RFC 3056 [https://tools.ietf.org/html/rfc3056.html], esta propiedad reportará la dirección IPv4 incrustada. Para cualquier otra dirección, esta propiedad será None.

teredo

Para las direcciones que parecen ser direcciones Teredo (comenzando con 2001::/32) según lo definido en RFC 4380 [https://tools.ietf.org/html/rfc4380.html], esta propiedad reportará el par de direcciones IP (servidor, cliente) incrustadas. Para cualquier otra dirección, esta propiedad será None.

IPv6Address.__format__(fmt)

Consulta en IPv4Address la documentación de atributos correspondiente.

Nuevo en la versión 3.9.

Conversión a cadenas de caracteres y enteros

Para interoperar con interfaces de red como el módulo socket, las direcciones se deben convertir en cadenas de caracteres o enteros. Esto se gestiona usando las funciones str() e int() incorporadas:

>>> str(ipaddress.IPv4Address('192.168.0.1'))
'192.168.0.1'
>>> int(ipaddress.IPv4Address('192.168.0.1'))
3232235521
>>> str(ipaddress.IPv6Address('::1'))
'::1'
>>> int(ipaddress.IPv6Address('::1'))
1

Tenga en cuenta que las direcciones IPv6 con alcance se convierten en números enteros sin ID de zona de alcance.

Operadores

Los objetos de dirección admiten algunos operadores. A menos que se indique lo contrario, los operadores solo se pueden aplicar entre objetos compatibles (es decir, IPv4 con IPv4, IPv6 con IPv6).

Operadores de comparación

Los objetos de dirección pueden compararse con el conjunto usual de operadores de comparación. Las mismas direcciones IPv6 con diferentes ID de zona de alcance no son iguales. Algunos ejemplos:

>>> IPv4Address('127.0.0.2') > IPv4Address('127.0.0.1')
True
>>> IPv4Address('127.0.0.2') == IPv4Address('127.0.0.1')
False
>>> IPv4Address('127.0.0.2') != IPv4Address('127.0.0.1')
True
>>> IPv6Address('fe80::1234') == IPv6Address('fe80::1234%1')
False
>>> IPv6Address('fe80::1234%1') != IPv6Address('fe80::1234%2')
True

Operadores aritméticos

Los enteros pueden ser sumados o restados de objetos de dirección. Algunos ejemplos:

>>> IPv4Address('127.0.0.2') + 3
IPv4Address('127.0.0.5')
>>> IPv4Address('127.0.0.2') - 3
IPv4Address('126.255.255.255')
>>> IPv4Address('255.255.255.255') + 1
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ipaddress.AddressValueError: 4294967296 (>= 2**32) is not permitted as an IPv4 address

Definiciones de red IP

Los objetos IPv4Network y IPv6Network proveen un mecanismo para definir e inspeccionar definiciones de redes IP. Una definición de red consiste en una máscara y una dirección de red, y como tal define un rango de direcciones IP que son iguales a la dirección de red cuando se enmascaran (AND binario) con la máscara. Por ejemplo, una definición de red con la máscara 255.255.255.0 y la dirección de red 192.168.1.0 consiste de las direcciones IP en el rango inclusivo 192.168.1.0 a 192.168.1.255.

Prefijo, máscara de red y máscara de host

Hay varias maneras equivalentes de especificar máscaras de red IP. Un prefijo es una notación que denota cuántos bits de orden superior se establecen en la máscara de red. Una máscara de red es una dirección IP con cierto número de bits de orden superior establecidos. Por lo tanto, el prefijo /24 es equivalente a la máscara de red 255.255.255.0 en IPv4, o ffff:ff00:: en IPv6. Además, una máscara del host es la inversa lógica de una máscara de red, y se utiliza a veces (por ejemplo en las listas de control de acceso de Cisco) para denotar una máscara de red. La máscara de host equivalente a /24 en IPv4 es 0.0.0.255.

Objetos de red

Todos los atributos implementados por los objetos de dirección también se implementan mediante objetos de red. Además, los objetos de red implementan atributos adicionales. Todos estos son comunes entre IPv4Network y IPv6Network, por lo que para evitar la duplicación solo están documentados para IPv4Network. Los objetos de red son hashable, por lo que se pueden utilizar como claves en diccionarios.

class ipaddress.IPv4Network(address, strict=True)

Construye una definición de red IPv4. address puede ser uno de los siguientes:

Una cadena de caracteres de una dirección IP y una máscara opcional, separadas por una barra diagonal (/). La dirección IP es la dirección de red, y la máscara puede ser un número único, lo que significa que es un prefijo, o una representación de una dirección IPv4. Si es la última, la máscara se interpreta como una máscara de red si comienza con un campo distinto de cero, o como una máscara de host si comienza con un campo igual a cero, con la única excepción de una máscara con todos ceros que es tratada como una máscara de red. Si no se proporciona una máscara, se considera \32.

Por ejemplo, las siguientes especificaciones de address son equivalentes: 192.168.1.0/24, 192.168.1.0/255.255.255.0 y 192.168.1.0/0.0.0.255.

Un entero que cabe en 32 bits. Este es equivalente a una red de una sola dirección, siendo address la dirección de red y /32 la máscara.

Un entero empaquetado en un objeto bytes de longitud 4, big-endian. La interpretación es similar a un entero address.

Una tupla con dos elementos con una descripción de dirección y una máscara de red, donde la descripción de dirección es una cadena de caracteres, un entero de 32 bits, un entero empaquetado de 4 bytes, o un objeto IPv4Address existente; y una máscara de red es un entero que representa la longitud del prefijo (por ejemplo 24) o una cadena de caracteres que representa la máscara de prefijo (por ejemplo 255.255.255.0).

Se genera un AddressValueError si address no es una dirección IPv4 válida. Se genera un NetmaskValueError si la máscara no es válida para un dirección IPv4.

Si strict es True y los bits de host están establecidos en la dirección proporcionada, se genera ValueError. De lo contrario, los bits de host se enmascaran para determinar la dirección de red adecuada.

A menos que se indique lo contrario, todos los métodos de red que acepten otros objetos de red/dirección generarán TypeError si la versión IP del argumento es incompatible con self.

Distinto en la versión 3.5: Se agregó la forma de tupla con dos elementos para el parámetro address del constructor.

version

max_prefixlen

Consulta en IPv4Address la documentación de atributos correspondiente.

is_multicast

is_private

is_unspecified

is_reserved

is_loopback

is_link_local

Estos atributos son verdaderos para la red en su conjunto si son verdaderos tanto para la dirección de red como para la dirección de difusión.

network_address

La dirección de red para la red. La dirección de red y la longitud del prefijo juntas definen de forma única una red.

broadcast_address

La dirección de difusión para la red. Los paquetes enviados a la dirección de difusión deberían ser recibidos por cada host en la red.

hostmask

La máscara de host, como un objeto IPv4Address.

netmask

La máscara de red, como un objeto IPv4Address.

with_prefixlen

compressed

exploded

Una representación en cadena de caracteres de la red, con la máscara en notación de prefijo.

with_prefixlen y compressed son siempre lo mismo que str(network). exploded usa la forma completa de la dirección de red.

with_netmask

Una representación en cadena de caracteres de la red, con la máscara en notación de máscara de red.

with_hostmask

Una representación de cadena de caracteres de la red, con la máscara en notación de máscara de host.

num_addresses

El número total de direcciones en la red.

prefixlen

Longitud del prefijo de red, en bits.

hosts()

Retorna un iterador a través de los hosts utilizables de la red. Los hosts utilizables son todas las direcciones IP que pertenecen a la red, excepto la propia dirección de red y la dirección de difusión de red. Para las redes con una longitud de máscara de 31, la dirección de red y la dirección de difusión de red también se incluyen en el resultado. Las redes con una máscara de 32 retornarán una lista que contiene la única dirección de host.

>>> list(ip_network('192.0.2.0/29').hosts())
[IPv4Address('192.0.2.1'), IPv4Address('192.0.2.2'),
 IPv4Address('192.0.2.3'), IPv4Address('192.0.2.4'),
 IPv4Address('192.0.2.5'), IPv4Address('192.0.2.6')]
>>> list(ip_network('192.0.2.0/31').hosts())
[IPv4Address('192.0.2.0'), IPv4Address('192.0.2.1')]
>>> list(ip_network('192.0.2.1/32').hosts())
[IPv4Address('192.0.2.1')]

overlaps(other)

True si esta red está parcial o totalmente contenida en other u other está totalmente contenida en esta red.

address_exclude(network)

Calcula las definiciones de red que resultan de eliminar network de esta red. Retorna un iterador de objetos de red. Se genera ValueError si network no está completamente contenida en esta red.

>>> n1 = ip_network('192.0.2.0/28')
>>> n2 = ip_network('192.0.2.1/32')
>>> list(n1.address_exclude(n2))
[IPv4Network('192.0.2.8/29'), IPv4Network('192.0.2.4/30'),
 IPv4Network('192.0.2.2/31'), IPv4Network('192.0.2.0/32')]

subnets(prefixlen_diff=1, new_prefix=None)

Las subredes que se unen para crear la definición de red actual, en función de los valores de argumento. prefixlen_diff es la cantidad en la que debería aumentarse nuestra longitud de prefijo. new_prefix es el nuevo prefijo deseado de las subredes; debe ser más grande que nuestro prefijo. Se debe establecer uno y solo uno de prefixlen_diff y new_prefix. Retorna un iterador de objetos de red.

>>> list(ip_network('192.0.2.0/24').subnets())
[IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/25')]
>>> list(ip_network('192.0.2.0/24').subnets(prefixlen_diff=2))
[IPv4Network('192.0.2.0/26'), IPv4Network('192.0.2.64/26'),
 IPv4Network('192.0.2.128/26'), IPv4Network('192.0.2.192/26')]
>>> list(ip_network('192.0.2.0/24').subnets(new_prefix=26))
[IPv4Network('192.0.2.0/26'), IPv4Network('192.0.2.64/26'),
 IPv4Network('192.0.2.128/26'), IPv4Network('192.0.2.192/26')]
>>> list(ip_network('192.0.2.0/24').subnets(new_prefix=23))
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
    raise ValueError('new prefix must be longer')
ValueError: new prefix must be longer
>>> list(ip_network('192.0.2.0/24').subnets(new_prefix=25))
[IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/25')]

supernet(prefixlen_diff=1, new_prefix=None)

La superred que contiene esta definición de red, dependiendo de los valores de los argumentos. prefixlen_diff es la cantidad en la que debería reducirse la longitud de nuestro prefijo. new_prefix es el nuevo prefijo deseado de la superred; debe ser más pequeño que nuestro prefijo. Se debe establecer uno y solo uno de prefixlen_diff y new_prefix. Retorna un único objeto de red.

>>> ip_network('192.0.2.0/24').supernet()
IPv4Network('192.0.2.0/23')
>>> ip_network('192.0.2.0/24').supernet(prefixlen_diff=2)
IPv4Network('192.0.0.0/22')
>>> ip_network('192.0.2.0/24').supernet(new_prefix=20)
IPv4Network('192.0.0.0/20')

subnet_of(other)

Retorna True si esta red es una subred de other.

>>> a = ip_network('192.168.1.0/24')
>>> b = ip_network('192.168.1.128/30')
>>> b.subnet_of(a)
True

Nuevo en la versión 3.7.

supernet_of(other)

Retorna True si esta red es una superred de other.

>>> a = ip_network('192.168.1.0/24')
>>> b = ip_network('192.168.1.128/30')
>>> a.supernet_of(b)
True

Nuevo en la versión 3.7.

compare_networks(other)

Compara esta red con other. En esta comparación solo se consideran las direcciones de red; los bits de host no. Retorna -1, 0 o 1.

>>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.2/32'))
-1
>>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.0/32'))
1
>>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.1/32'))
0

Obsoleto desde la versión 3.7: Utiliza el mismo algoritmo de ordenación y comparación que «<», «==», y «>»

class ipaddress.IPv6Network(address, strict=True)

Construye una definición de red IPv6. address puede ser uno de los siguientes:

Una cadena de caracteres que consta de una dirección IP y una longitud de prefijo opcional, separadas por una barra diagonal (/). La dirección IP es la dirección de red y la longitud del prefijo debe ser un solo número, el prefijo. Si no se proporciona ninguna longitud de prefijo, se considera que es /128.

Note that currently expanded netmasks are not supported. That means 2001:db00::0/24 is a valid argument while 2001:db00::0/ffff:ff00:: is not.

Un entero que cabe en 128 bits. Este es equivalente a una red de una sola dirección, siendo address la dirección de red y /128 la máscara.

Un entero empaquetado en un objeto bytes de longitud 16, big-endian. La interpretación es similar a un entero address.

Una tupla con dos elementos con una descripción de dirección y una máscara de red, donde la descripción de dirección es una cadena de caracteres, un entero de 128 bits, un entero empaquetado de 16 bytes, o un objeto IPv6Address existente; y una máscara de red es un entero que representa la longitud del prefijo.

Se genera un AddressValueError si address no es una dirección IPv6 válida. Se genera un NetmaskValueError si la máscara no es válida para una dirección IPv6.

Si strict es True y los bits de host están establecidos en la dirección proporcionada, se genera ValueError. De lo contrario, los bits de host se enmascaran para determinar la dirección de red adecuada.

Distinto en la versión 3.5: Se agregó la forma de tupla con dos elementos para el parámetro address del constructor.

version

max_prefixlen

is_multicast

is_private

is_unspecified

is_reserved

is_loopback

is_link_local

network_address

broadcast_address

hostmask

netmask

with_prefixlen

compressed

exploded

with_netmask

with_hostmask

num_addresses

prefixlen

hosts()

Retorna un iterador sobre los hosts utilizables de la red. Los hosts utilizables son todas las direcciones IP que pertenecen a la red, excepto la dirección anycast Subnet-Router. Para las redes con una longitud de máscara de 127, la dirección anycast Subnet-Router también se incluye en el resultado. Las redes con una máscara de 128 retornarán una lista que contiene la única dirección de host.

overlaps(other)

address_exclude(network)

subnets(prefixlen_diff=1, new_prefix=None)

supernet(prefixlen_diff=1, new_prefix=None)

subnet_of(other)

supernet_of(other)

compare_networks(other)

Consulta en IPv4Network la documentación de atributos correspondiente.

is_site_local

Este atributo es verdadero para la red en su conjunto si es verdadero tanto para la dirección de red como para la dirección de difusión.

Operadores

Los objetos de red admiten algunos operadores. A menos que se indique lo contrario, los operadores solo se pueden aplicar entre objetos compatibles (es decir, IPv4 con IPv4, IPv6 con IPv6).

Operadores lógicos

Los objetos de red pueden compararse con el conjunto usual de operadores lógicos. Los objetos de red son ordenados primero por dirección de red, y después por máscara de red.

Iteración

Los objetos de red se pueden iterar para listar todas las direcciones que pertenecen a la red. Para la iteración, se retornan todos los hosts, incluyendo hosts inutilizables (para hosts utilizables, se usa el método hosts()). Un ejemplo:

>>> for addr in IPv4Network('192.0.2.0/28'):
...     addr
...
IPv4Address('192.0.2.0')
IPv4Address('192.0.2.1')
IPv4Address('192.0.2.2')
IPv4Address('192.0.2.3')
IPv4Address('192.0.2.4')
IPv4Address('192.0.2.5')
IPv4Address('192.0.2.6')
IPv4Address('192.0.2.7')
IPv4Address('192.0.2.8')
IPv4Address('192.0.2.9')
IPv4Address('192.0.2.10')
IPv4Address('192.0.2.11')
IPv4Address('192.0.2.12')
IPv4Address('192.0.2.13')
IPv4Address('192.0.2.14')
IPv4Address('192.0.2.15')

Redes como contenedores de direcciones

Los objetos de red pueden actuar como contenedores de direcciones. Algunos ejemplos:

>>> IPv4Network('192.0.2.0/28')[0]
IPv4Address('192.0.2.0')
>>> IPv4Network('192.0.2.0/28')[15]
IPv4Address('192.0.2.15')
>>> IPv4Address('192.0.2.6') in IPv4Network('192.0.2.0/28')
True
>>> IPv4Address('192.0.3.6') in IPv4Network('192.0.2.0/28')
False

Objetos de interfaz

Los objetos de interfaz son hashable, por lo que se pueden utilizar como claves en diccionarios.

class ipaddress.IPv4Interface(address)

Construye una interfaz IPv4. El significado de address es el mismo que en el constructor de IPv4Network, excepto que las direcciones de host arbitrarias son siempre aceptadas.

IPv4Interface es una subclase de IPv4Address, así que hereda todos los atributos de esa clase. Adicionalmente, los siguientes atributos están disponibles:

ip

La dirección (IPv4Address) sin información de red.

>>> interface = IPv4Interface('192.0.2.5/24')
>>> interface.ip
IPv4Address('192.0.2.5')

network

La red (IPv4Network) a la que pertenece esta interfaz.

>>> interface = IPv4Interface('192.0.2.5/24')
>>> interface.network
IPv4Network('192.0.2.0/24')

with_prefixlen

Una representación en cadena de caracteres de la interfaz con la máscara en notación de prefijo.

>>> interface = IPv4Interface('192.0.2.5/24')
>>> interface.with_prefixlen
'192.0.2.5/24'

with_netmask

Una representación en cadena de caracteres de la interfaz con la red como una máscara de red.

>>> interface = IPv4Interface('192.0.2.5/24')
>>> interface.with_netmask
'192.0.2.5/255.255.255.0'

with_hostmask

Una representación de la interfaz con la red como una máscara de host.

>>> interface = IPv4Interface('192.0.2.5/24')
>>> interface.with_hostmask
'192.0.2.5/0.0.0.255'

class ipaddress.IPv6Interface(address)

Construye una interfaz IPv6. El significado de address es el mismo que en el constructor de IPv6Network, excepto que las direcciones de host arbitrarias son siempre aceptadas.

IPv6Interface es una subclase de IPv6Address, así que hereda todos los atributos de esa clase. Adicionalmente, los siguientes atributos están disponibles:

ip

network

with_prefixlen

with_netmask

with_hostmask

Consulta en IPv4Interface la documentación de atributos correspondiente.

Operadores

Los objetos de interfaz admiten algunos operadores. A menos que se indique lo contrario, los operadores solo se pueden aplicar entre objetos compatibles (es decir, IPv4 con IPv4, IPv6 con IPv6).

Operadores lógicos

Los objetos de interfaz pueden compararse con el conjunto usual de operadores lógicos.

Para la comparación de igualdad (== and !=), tanto la dirección IP como la red deben ser iguales para que los objetos sean iguales. Una interfaz no será igual a ningún objeto de dirección o de red.

Para el ordenamiento (<, >, etc.) las reglas son diferentes. Los objetos de interfaz y de dirección con la misma versión de IP se pueden comparar, y los objetos de dirección siempre se ordenarán antes que los objetos de interfaz. Dos objetos de interfaz se comparan primero por sus redes y, si son iguales, luego por sus direcciones IP.

Otras funciones a nivel de módulo

El módulo también provee las siguientes funciones a nivel de módulo:

ipaddress.v4_int_to_packed(address)

Representa una dirección como 4 bytes empaquetados en orden de red (big-endian). address es una representación en entero de una dirección IPv4. Se genera un ValueError si el entero es negativo o demasiado grande para ser una dirección IPv4.

>>> ipaddress.ip_address(3221225985)
IPv4Address('192.0.2.1')
>>> ipaddress.v4_int_to_packed(3221225985)
b'\xc0\x00\x02\x01'

ipaddress.v6_int_to_packed(address)

Representa una dirección como 16 bytes empaquetados en orden de red (big-endian). address es una representación en entero de una dirección IPv6. Se genera un ValueError si el entero es negativo o demasiado grande para ser una dirección IPv6.

ipaddress.summarize_address_range(first, last)

Retorna un iterador del rango de red resumido dadas la primera y la última dirección IP. first es la primera IPv4Address o IPv6Address en el rango y last es la última IPv4Address o IPv6Address en el rango. Se genera un TypeError si first o last no son direcciones IP o no son de la misma versión. Se genera un ValueError si last no es mayor que first o si la versión de first no es 4 o 6.

>>> [ipaddr for ipaddr in ipaddress.summarize_address_range(
...    ipaddress.IPv4Address('192.0.2.0'),
...    ipaddress.IPv4Address('192.0.2.130'))]
[IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/31'), IPv4Network('192.0.2.130/32')]

ipaddress.collapse_addresses(addresses)

Retorna un iterador de los objetos colapsados IPv4Network o IPv6Network. addresses es un iterador de objetos IPv4Network o IPv6Network. Se genera un TypeError si addresses contiene objetos de versiones distintas.

>>> [ipaddr for ipaddr in
... ipaddress.collapse_addresses([ipaddress.IPv4Network('192.0.2.0/25'),
... ipaddress.IPv4Network('192.0.2.128/25')])]
[IPv4Network('192.0.2.0/24')]

ipaddress.get_mixed_type_key(obj)

Retorna una clave adecuada para ordenar entre redes y direcciones. Los objetos de dirección y red no son ordenables por defecto; son fundamentalmente diferentes, así que la expresión:

IPv4Address('192.0.2.0') <= IPv4Network('192.0.2.0/24')

no tiene sentido. Sin embargo, hay veces donde se desearía hacer que ipaddress las ordene de cualquier forma. Si se necesita hacer esto, se puede usar esta función como el argumento key de sorted().

obj es un objeto de red o de dirección.

Excepciones personalizadas

Para soportar un reporte de errores más específico desde los constructores de clase, el módulo define las siguientes excepciones:

exception ipaddress.AddressValueError(ValueError)

Cualquier valor de error relacionado a la dirección.

exception ipaddress.NetmaskValueError(ValueError)

Cualquier valor de error relacionado a la máscara de red.

Servicios Multimedia

Los módulos descritos en este capítulo implementan varios algoritmos o interfaces que son útiles principalmente para aplicaciones multimedia. Su disponibilidad depende de la instalación. He aquí una visión general:

wave — Leer y escribir archivos WAV

Los objetos Wave_read

Los objetos Wave_write

colorsys — Conversiones entre sistemas de color

wave — Leer y escribir archivos WAV

Código fuente: Lib/wave.py [https://github.com/python/cpython/tree/3.9/Lib/wave.py]

El módulo wave proporciona una interfaz conveniente para el formato de sonido WAV. No es compatible con la compresión/descompresión, pero sí es compatible con mono/estéreo.

El módulo wave define la siguiente función y excepción:

wave.open(file, mode=None)

Si file es una cadena, abra el archivo con ese nombre, de lo contrario trátelo como un objeto similar a un archivo. mode puede ser:

'rb'

Modo de solo lectura.

'wb'

Modo de solo escritura.

Tenga en cuenta que no permite archivos WAV de lectura/escritura.

Un mode de 'rb' retorna un objeto Wave_read, mientras que un mode de 'wb' retorna un objeto Wave_write. Si se omite mode y se pasa un objeto similar a un archivo como file, file.mode se usa como el valor predeterminado para mode.

Si pasa un objeto similar a un archivo, el objeto wave no lo cerrará cuando se llame al método close(); es responsabilidad del invocador cerrar el objeto de archivo.

La función open() se puede utilizar en una declaración with. Cuando el bloque with se completa, el método Wave_read.close() o el método Wave_write.close() es invocado.

Distinto en la versión 3.4: Se agregó soporte para archivos no encontrados.

exception wave.Error

Error que se produce cuando algo es imposible porque viola la especificación WAV o alcanza una deficiencia de implementación.

Los objetos Wave_read

Los objetos Wave_read, tal como lo retorna open(), tienen los siguientes métodos:

Wave_read.close()

Cierra la secuencia si fue abierta por wave, y hace que la instancia sea inutilizable. Esto es llamado automáticamente en la colección de objetos.

Wave_read.getnchannels()

Retorna el número de canales de audio (1 para mono, 2 para estéreo).

Wave_read.getsampwidth()

Retorna el ancho de la muestra en bytes.

Wave_read.getframerate()

Retorna la frecuencia del muestreo.

Wave_read.getnframes()

Retorna el número de cuadros del audio.

Wave_read.getcomptype()

Retorna el tipo de compresión ('NONE' es el único tipo admitido).

Wave_read.getcompname()

Versión legible para humanos de getcomptype(). Generalmente 'not compressed' significa 'NONE'.

Wave_read.getparams()

Retorna un namedtuple() (nchannels, sampwidth, framerate, nframes, comptype, compname), equivalente a la salida de los métodos get*().

Wave_read.readframes(n)

Lee y retorna como máximo n cuadros de audio, como un objeto bytes.

Wave_read.rewind()

Rebobina el puntero del archivo hasta el principio de la secuencia de audio.

Los dos métodos siguientes se definen por compatibilidad con el módulo aifc, y no hacen nada interesante.

Wave_read.getmarkers()

Retorna None.

Wave_read.getmark(id)

Lanza un error.

Los dos métodos siguientes definen un término «posición» que es compatible entre ellos y, es dependiente de la implementación.

Wave_read.setpos(pos)

Establece el puntero del archivo en la posición especificada.

Wave_read.tell()

Retorna la posición actual del puntero del archivo.

Los objetos Wave_write

Para las secuencias de salida que se pueden buscar, el encabezado de wave se actualizará automáticamente para reflejar el número de cuadros realmente escritos. Para secuencias que no se pueden buscar, el valor nframes debe ser preciso cuando se escriben los datos del primer cuadro. Se puede lograr un valor nframes preciso llamando a setnframes() o setparams() con el número de cuadros que se escribirán antes de que se llame a close() y luego se usa writeframesraw() para escribir los datos del cuadro, o llamando a writeframes() con todos los datos del cuadro que se escribirán. En el último caso writeframes() calculará el número de cuadros en los datos y establecerá nframes como consecuencia antes de escribir los datos del cuadro.

Los objetos Wave_write, retornados por open(), tienen los siguientes métodos:

Distinto en la versión 3.4: Se agregó soporte para archivos no encontrados.

Wave_write.close()

Asegúrese de que nframes sea correcto y cierre el archivo si fue abierto por wave. Este método es invocado en la colección de objetos. Levantará una excepción si la secuencia de salida no se puede buscar y nframes no coinciden con el número de cuadros realmente escritos.

Wave_write.setnchannels(n)

Configure el número de canales.

Wave_write.setsampwidth(n)

Establezca el ancho de la muestra en n bytes.

Wave_write.setframerate(n)

Establezca la velocidad del cuadro en n.

Distinto en la versión 3.2: Una entrada no-entera para este método se redondea al número entero más cercano.

Wave_write.setnframes(n)

Establezca el número de cuadros en n. Esto se cambiará más adelante si el número de cuadros realmente escritos es diferente (este intento de actualización levantará un error si no se encuentra la secuencia de salida).

Wave_write.setcomptype(type, name)

Establece el tipo de compresión y la descripción. Por el momento, solo se admite el tipo de compresión NONE, lo que significa que no hay compresión.

Wave_write.setparams(tuple)

La tupla debe ser (nchannels, sampwidth, framerate, nframes, comptype, compname), con valores válidos para los métodos set *(). Establece todos los parámetros.

Wave_write.tell()

Retorna la posición actual en el archivo, con el mismo descargo para los métodos Wave_read.tell() y Wave_read.setpos().

Wave_write.writeframesraw(data)

Escribe cuadros de audio, sin corregir nframes.

Distinto en la versión 3.4: Todo bytes-like object ahora es aceptado.

Wave_write.writeframes(data)

Escribe cuadros de audio y se asegura de que nframes sea correcto. Levantará un error si no se puede encontrar la secuencia de salida y si el número total de cuadros que se han escrito después de que se haya escrito data no coincide con el valor establecido previamente para nframes.

Distinto en la versión 3.4: Todo bytes-like object ahora es aceptado.

Tenga en cuenta que no es válido establecer ningún parámetro después de invocar a writeframes() o writeframesraw(), y cualquier intento de hacerlo levantará wave.Error.

colorsys — Conversiones entre sistemas de color

Código fuente: Lib/colorsys.py [https://github.com/python/cpython/tree/3.9/Lib/colorsys.py]

El módulo colorsys define conversiones bidireccionales de valores de color entre colores expresados en el espacio de color RGB (sigla en inglés de Red Green Blue, en español Rojo Verde Azul) utilizado en monitores de ordenador y otros tres sistemas de coordenadas: YIQ, HLS (sigla en inglés de Hue Lightness Saturation, en español Matiz Luminosidad Saturación) y HSV (sigla en inglés de Hue Saturation Value, en español Matiz Saturación Valor). Las coordenadas en todos estos espacios de color son números de punto flotante. En el espacio YIQ, la coordenada Y está entre 0 y 1, pero las coordenadas I y Q pueden ser positivas o negativas. En todos los demás espacios, las coordenadas están todas entre 0 y 1.

Ver también

Puede encontrar más información sobre los espacios de color en http://poynton.ca/ColorFAQ.html y https://www.cambridgeincolour.com/tutorials/color-spaces.htm.

El módulo colorsys define las siguientes funciones:

colorsys.rgb_to_yiq(r, g, b)

Convierte el color de las coordenadas RGB en coordenadas YIQ.

colorsys.yiq_to_rgb(y, i, q)

Convierte el color de las coordenadas YIQ en coordenadas RGB.

colorsys.rgb_to_hls(r, g, b)

Convierte el color de las coordenadas RGB en coordenadas HLS.

colorsys.hls_to_rgb(h, l, s)

Convierte el color de las coordenadas HLS en coordenadas RGB.

colorsys.rgb_to_hsv(r, g, b)

Convierte el color de las coordenadas RGB en coordenadas HSV.

colorsys.hsv_to_rgb(h, s, v)

Convierte el color de las coordenadas HSV en coordenadas RGB.

Ejemplo:

>>> import colorsys
>>> colorsys.rgb_to_hsv(0.2, 0.4, 0.4)
(0.5, 0.5, 0.4)
>>> colorsys.hsv_to_rgb(0.5, 0.5, 0.4)
(0.2, 0.4, 0.4)

Internacionalización

Los módulos descritos en este capítulo te ayudan a escribir software que es independiente del idioma y lugar al proporcionar mecanismos para seleccionar un idioma a ser usado en mensajes de programas o adaptar la salida para que coincida con las convenciones locales.

La lista de módulos descritos en este capítulo es:

gettext — Servicios de internacionalización multilingües

GNU API gettext

API basada en clases

La clase NullTranslations

La clase GNUTranslations

Soporte de catálogo de mensajes de Solaris

El constructor del catálogo

Internacionalizando sus programas y módulos

Agregar configuración regional a su módulo

Agregar configuración regional a su aplicación

Cambiar idiomas sobre la marcha

Traducciones diferidas

Agradecimientos

locale — Servicios de internacionalización

Segundo plano, detalles, indicaciones, consejos y advertencias

Para escritores de extensión y programas que incrustan Python

Acceso a los catálogos de mensajes

gettext — Servicios de internacionalización multilingües

Código fuente: Lib/gettext.py [https://github.com/python/cpython/tree/3.9/Lib/gettext.py]

El módulo gettext proporciona servicios de internacionalización (I18N) y localización (L10N) para sus módulos y aplicaciones Python. Admite tanto la API del catálogo de mensajes GNU gettext como una API basada en clases de nivel superior que puede ser más apropiada para los archivos Python. La interfaz que se describe a continuación le permite escribir sus mensajes de módulo y aplicación en un idioma natural, y proporcionar un catálogo de mensajes traducidos para ejecutar en diferentes idiomas naturales.

También se dan algunas sugerencias para localizar sus módulos y aplicaciones Python.

GNU API gettext

El módulo gettext define la siguiente API, que es muy similar al programa GNU gettext API. Si usa esta API, afectará la traducción de toda su aplicación a nivel mundial. A menudo, esto es lo que desea si su aplicación es monolingüe, y la elección del idioma depende de la configuración regional de su usuario. Si está localizando un módulo de Python, o si su aplicación necesita cambiar idiomas sobre la marcha, probablemente desee utilizar la API basada en clases.

gettext.bindtextdomain(domain, localedir=None)

Enlaza (bind) el domain al directorio de configuración regional localedir. Más concretamente, gettext buscará archivos binarios .mo para el dominio dado usando la ruta (en Unix): localedir/language/LC_MESSAGES /domain.mo, donde se busca language en las variables de entorno LANGUAGE, LC_ALL, LC_MESSAGES y LANG respectivamente.

Si localedir se omite o es None, se retorna el enlace actual para domain. 1

gettext.bind_textdomain_codeset(domain, codeset=None)

Enlaza (bind) el domain al codeset, cambiando la codificación de las cadenas de bytes retornadas por las funciones lgettext(), ldgettext(), lngettext() y ldngettext(). Si se omite codeset, se retorna el enlace (binding) actual.

Deprecated since version 3.8, will be removed in version 3.10.

gettext.textdomain(domain=None)

Cambia o consulta el dominio global actual. Si domain es None, se retorna el dominio global actual; de lo contrario, el dominio global se establece en domain, que se retorna.

gettext.gettext(message)

Retorna la traducción localizada de message, en función del dominio global actual, el idioma y el directorio de configuración regional. Esta función generalmente tiene un alias como _() en el espacio de nombres local (ver ejemplos a continuación).

gettext.dgettext(domain, message)

Como gettext(), pero busque el mensaje en el domain especificado.

gettext.ngettext(singular, plural, n)

Como gettext(), pero considere formas plurales. Si se encuentra una traducción, aplique la fórmula plural a n y retorna el mensaje resultante (algunos idiomas tienen más de dos formas plurales). Si no se encuentra ninguna traducción, retorna singular if n es 1; retorna plural de lo contrario.

La fórmula Plural se toma del encabezado del catálogo. Es una expresión C o Python que tiene una variable libre n; la expresión se evalúa como el índice del plural en el catálogo. Consulte la documentación de GNU gettext [https://www.gnu.org/software/gettext/manual/gettext.html] para conocer la sintaxis precisa que se utilizará en archivos .po y las fórmulas para un variedad de idiomas.

gettext.dngettext(domain, singular, plural, n)

Como ngettext(), pero busque el mensaje en el domain especificado.

gettext.pgettext(context, message)

gettext.dpgettext(domain, context, message)

gettext.npgettext(context, singular, plural, n)

gettext.dnpgettext(domain, context, singular, plural, n)

Similar a las funciones correspondientes sin la p en el prefijo (es decir, gettext(), dgettext(), ngettext(), dngettext()), pero la traducción está restringida al mensaje dado context.

Nuevo en la versión 3.8.

gettext.lgettext(message)

gettext.ldgettext(domain, message)

gettext.lngettext(singular, plural, n)

gettext.ldngettext(domain, singular, plural, n)

Equivalente a las funciones correspondientes sin el prefijo l (gettext(), dgettext(), ngettext() y dngettext()), pero la traducción se retorna como una cadena de bytes codificada en la codificación del sistema preferida si no se estableció explícitamente otra codificación con bind_textdomain_codeset().

Advertencia

Estas funciones deben evitarse en Python 3, ya que retornan bytes codificados. Es mucho mejor usar alternativas que retornan cadenas Unicode, ya que la mayoría de las aplicaciones de Python querrán manipular el texto legible por humanos como cadenas en lugar de bytes. Además, es posible que obtenga excepciones inesperadas relacionadas con Unicode si hay problemas de codificación con las cadenas traducidas.

Deprecated since version 3.8, will be removed in version 3.10.

Tenga en cuenta que GNU gettext también define un método dcgettext(), pero esto no se consideró útil, por lo que actualmente no está implementado.

Aquí hay un ejemplo del uso típico de esta API:

import gettext
gettext.bindtextdomain('myapplication', '/path/to/my/language/directory')
gettext.textdomain('myapplication')
_ = gettext.gettext
# ...
print(_('This is a translatable string.'))

API basada en clases

La API basada en clases del módulo gettext le brinda más flexibilidad y mayor comodidad que la API GNU gettext. Es la forma recomendada de localizar sus aplicaciones y módulos de Python. gettext define una clase GNUTranslations que implementa el análisis de archivos de formato GNU .mo, y tiene métodos para retornar cadenas. Las instancias de esta clase también pueden instalarse en el espacio de nombres incorporado como la función _().

gettext.find(domain, localedir=None, languages=None, all=False)

Esta función implementa el algoritmo de búsqueda de archivos estándar .mo. Toma un domain, idéntico al que toma textdomain(). Opcional localedir es como en bindtextdomain(). languages opcionales es una lista de cadenas, donde cada cadena es un código de idioma.

Si no se proporciona localedir, se utiliza el directorio de configuración regional predeterminado del sistema. 2 Si no se proporcionan languages, se buscan las siguientes variables de entorno: LANGUAGE, LC_ALL, LC_MESSAGES, y LANG. El primero que retorna un valor no vacío se usa para la variable languages. Las variables de entorno deben contener una lista de idiomas separados por dos puntos, que se dividirá en dos puntos para producir la lista esperada de cadenas de código de idioma.

find() luego expande y normaliza los idiomas, y luego los itera, buscando un archivo existente construido con estos componentes:

localedir/language/LC_MESSAGES/domain.mo

El primer nombre de archivo que existe es retornado por find(). Si no se encuentra dicho archivo, se retorna None. Si se proporciona all, retorna una lista de todos los nombres de archivo, en el orden en que aparecen en la lista de idiomas o las variables de entorno.

gettext.translation(domain, localedir=None, languages=None, class_=None, fallback=False, codeset=None)

Retorna una instancia de *Translations basada en domain, localedir y languages, que primero se pasan a find() para obtener una lista del archivo asociado de rutas .mo. Instancias con idéntico nombres de archivo .mo se almacenan en caché. La clase real instanciada es class_ si se proporciona, de lo contrario GNUTranslations. El constructor de la clase debe tomar un solo argumento file object. Si se proporciona, codeset cambiará el juego de caracteres utilizado para codificar cadenas traducidas en los métodos lgettext() y lngettext().

Si se encuentran varios archivos, los archivos posteriores se utilizan como retrocesos para los anteriores. Para permitir la configuración de la reserva, copy.copy() se utiliza para clonar cada objeto de traducción del caché; los datos de la instancia real aún se comparten con el caché.

Si no se encuentra el archivo .mo, esta función genera OSError si fallback es falso (que es el valor predeterminado) y retorna una instancia de NullTranslations si fallback is verdadero.

Distinto en la versión 3.3: IOError solía aparecer en lugar de OSError.

Deprecated since version 3.8, will be removed in version 3.10: El parámetro codeset.

gettext.install(domain, localedir=None, codeset=None, names=None)

Esto instala la función _() en el espacio de nombres incorporado de Python, basado en domain, localedir y codeset que se pasan a la función translation().

Para el parámetro names, consulte la descripción del método del objeto de traducción install().

Como se ve a continuación, generalmente marca las cadenas en su aplicación que son candidatas para la traducción, envolviéndolas en una llamada a la función _(), como esta:

print(_('This string will be translated.'))

Para mayor comodidad, desea que la función _() se instale en el espacio de nombres integrado de Python, para que sea fácilmente accesible en todos los módulos de su aplicación.

Deprecated since version 3.8, will be removed in version 3.10: El parámetro codeset.

La clase NullTranslations

Las clases de traducción son las que realmente implementan la traducción de cadenas de mensajes del archivo fuente original a cadenas de mensajes traducidas. La clase base utilizada por todas las clases de traducción es NullTranslations; Esto proporciona la interfaz básica que puede utilizar para escribir sus propias clases de traducción especializadas. Estos son los métodos de NullTranslations:

class gettext.NullTranslations(fp=None)

Toma un término opcional file object fp, que es ignorado por la clase base. Inicializa las variables de instancia «protegidas» _info y _charset que se establecen mediante clases derivadas, así como _fallback, que se establece a través de add_fallback(). Luego llama a self._parse(fp) if fp no es None.

_parse(fp)

No operativo en la clase base, este método toma el objeto de archivo fp y lee los datos del archivo, inicializando su catálogo de mensajes. Si tiene un formato de archivo de catálogo de mensajes no admitido, debe sobrescribir este método para analizar su formato.

add_fallback(fallback)

Agrega fallback como el objeto de respaldo para el objeto de traducción actual. Un objeto de traducción debe consultar la reserva si no puede proporcionar una traducción para un mensaje dado.

gettext(message)

Si se ha establecido una reserva, reenvíe gettext() a la reserva. De lo contrario, retorna message. Anulado en clases derivadas.

ngettext(singular, plural, n)

Si se ha establecido una reserva, reenvíe ngettext() a la reserva. De lo contrario, retorna singular si n es 1; volver plural de lo contrario. Anulado en clases derivadas.

pgettext(context, message)

Si se ha establecido una reserva, reenvía pgettext() a la reserva. De lo contrario, retorna el mensaje traducido. Anulado en clases derivadas.

Nuevo en la versión 3.8.

npgettext(context, singular, plural, n)

Si se ha establecido una reserva, reenvía npgettext() a la reserva. De lo contrario, retorna el mensaje traducido. Anulado en clases derivadas.

Nuevo en la versión 3.8.

lgettext(message)

lngettext(singular, plural, n)

Equivalente a gettext() y ngettext(), pero la traducción se retorna como una cadena de bytes codificada en la codificación del sistema preferida si no se estableció explícitamente ninguna codificación con set_output_charset(). Anulado en clases derivadas.

Advertencia

Estos métodos deben evitarse en Python 3. Consulte la advertencia para la función lgettext().

Deprecated since version 3.8, will be removed in version 3.10.

info()

Retorna la variable «protected» _info, un diccionario que contiene los metadatos encontrados en el archivo del catálogo de mensajes.

charset()

Retorna la codificación del archivo de catálogo de mensajes.

output_charset()

Retorna la codificación utilizada para retornar mensajes traducidos en lgettext() y lngettext().

Deprecated since version 3.8, will be removed in version 3.10.

set_output_charset(charset)

Cambiar la codificación utilizada para retornar mensajes traducidos.

Deprecated since version 3.8, will be removed in version 3.10.

install(names=None)

Este método instala gettext() en el espacio de nombres incorporado, vinculándolo a _.

Si se proporciona el parámetro names, debe ser una secuencia que contenga los nombres de las funciones que desea instalar en el espacio de nombres incorporado además de _(). Los nombres admitidos son 'gettext', 'ngettext', 'pgettext', 'npgettext', 'lgettext', y 'lngettext'.

Tenga en cuenta que esta es solo una forma, aunque la más conveniente, para que la función _() esté disponible para su aplicación. Debido a que afecta a toda la aplicación globalmente, y específicamente al espacio de nombres incorporado, los módulos localizados nunca deberían instalarse _(). En su lugar, deberían usar este código para hacer que _() esté disponible para su módulo:

import gettext
t = gettext.translation('mymodule', ...)
_ = t.gettext

Esto pone _() solo en el espacio de nombres global del módulo y, por lo tanto, solo afecta las llamadas dentro de este módulo.

Distinto en la versión 3.8: Se agregó 'pgettext' y 'npgettext'.

La clase GNUTranslations

El módulo gettext proporciona una clase adicional derivada de NullTranslations: GNUTranslations. Esta clase anula _parse() para permitir la lectura de formato GNU gettext archivos .mo en formato big-endian y little-endian.

GNUTranslations analiza los metadatos opcionales del catálogo de traducción. Es una convención con GNU gettext para incluir metadatos como la traducción de la cadena vacía. Estos metadatos están en estilos pares RFC 822 [https://tools.ietf.org/html/rfc822.html]key: value, y deben contener la clave Project-Id-Version. Si se encuentra la clave Content-Type, entonces la propiedad charset se usa para inicializar la variable de instancia «protected» _charset, con el valor predeterminado None si no se encuentra. Si se especifica la codificación del juego de caracteres, todos los identificadores de mensajes y las cadenas de mensajes leídos del catálogo se convierten a Unicode utilizando esta codificación, de lo contrario se asume ASCII.

Dado que los identificadores de mensaje también se leen como cadenas Unicode, todos los métodos *gettext() asumirán los identificadores de mensaje como cadenas Unicode, no cadenas de bytes.

El conjunto completo de pares clave/valor se colocan en un diccionario y se establece como la variable de instancia «protegida» _info.

Si el número mágico del archivo .mo no es válido, el número de versión principal es inesperado, o si se producen otros problemas al leer el archivo, se crea una instancia de GNUTranslations puede generar OSError.

class gettext.GNUTranslations

Los siguientes métodos se anulan desde la implementación de la clase base:

gettext(message)

Busca el message id en el catálogo y retorna la cadena de caracteres de mensaje correspondiente, como una cadena Unicode. Si no hay una entrada en el catálogo para el message id, y se ha establecido una retroceso (fallback), la búsqueda se reenvía al método de retroceso gettext(). De lo contrario, se retorna el message id.

ngettext(singular, plural, n)

Realiza una búsqueda de formas plurales de una identificación de mensaje. singular se usa como la identificación del mensaje para fines de búsqueda en el catálogo, mientras que n se usa para determinar qué forma plural usar. La cadena del mensaje retornado es una cadena de caracteres Unicode.

Si la identificación del mensaje no se encuentra en el catálogo y se especifica una reserva, la solicitud se reenvía al método de reserva ngettext(). De lo contrario, cuando n es 1 se retorna singular, y plural se retorna en todos los demás casos.

Aquí hay un ejemplo:

n = len(os.listdir('.'))
cat = GNUTranslations(somefile)
message = cat.ngettext(
    'There is %(num)d file in this directory',
    'There are %(num)d files in this directory',
    n) % {'num': n}

pgettext(context, message)

Busca el context y message id en el catálogo y retorna la cadena de de caracteres mensaje correspondiente, como una cadena de caracteres Unicode. Si no hay ninguna entrada en el catálogo para el message id y context, y se ha establecido un retroceso (fallback), la búsqueda se reenvía al método de retroceso pgettext(). De lo contrario, se retorna el message id.

Nuevo en la versión 3.8.

npgettext(context, singular, plural, n)

Realiza una búsqueda de formas plurales de una identificación de mensaje. singular se usa como la identificación del mensaje para fines de búsqueda en el catálogo, mientras que n se usa para determinar qué forma plural usar.

Si la identificación del mensaje para context no se encuentra en el catálogo y se especifica una reserva, la solicitud se reenvía al método de reserva npgettext(). De lo contrario, cuando n * es 1 se retorna *singular, y plural se retorna en todos los demás casos.

Nuevo en la versión 3.8.

lgettext(message)

lngettext(singular, plural, n)

Equivalente a gettext() y ngettext(), pero la traducción se retorna como una cadena de bytes codificada en la codificación del sistema preferida si no se estableció explícitamente ninguna codificación con set_output_charset().

Advertencia

Estos métodos deben evitarse en Python 3. Consulte la advertencia para la función lgettext().

Deprecated since version 3.8, will be removed in version 3.10.

Soporte de catálogo de mensajes de Solaris

El sistema operativo Solaris define su propio formato de archivo binario .mo, pero como no se puede encontrar documentación sobre este formato, no es compatible en este momento.

El constructor del catálogo

GNOME usa una versión del módulo gettext de James Henstridge, pero esta versión tiene una API ligeramente diferente. Su uso documentado fue:

import gettext
cat = gettext.Catalog(domain, localedir)
_ = cat.gettext
print(_('hello world'))

Para la compatibilidad con este módulo anterior, la función Catalog() es un alias para la función translation() descrita anteriormente.

Una diferencia entre este módulo y el de Henstridge: sus objetos de catálogo admitían el acceso a través de una API de mapeo, pero esto parece estar sin usar y, por lo tanto, actualmente no es compatible.

Internacionalizando sus programas y módulos

La internacionalización (I18N) se refiere a la operación mediante la cual un programa conoce varios idiomas. La localización (L10N) se refiere a la adaptación de su programa, una vez internacionalizado, al idioma local y los hábitos culturales. Para proporcionar mensajes multilingües para sus programas de Python, debe seguir los siguientes pasos:

prepare su programa o módulo marcando especialmente cadenas traducibles

ejecuta un conjunto de herramientas sobre tus archivos marcados para generar catálogos de mensajes sin procesar

crear traducciones específicas del idioma de los catálogos de mensajes

use el módulo gettext para que las cadenas de caracteres de mensajes se traduzcan correctamente

Para preparar su código para I18N, debe mirar todas las cadenas en sus archivos. Cualquier cadena que deba traducirse debe marcarse envolviéndola en _('...') — es decir, una llamada a la función _(). Por ejemplo:

filename = 'mylog.txt'
message = _('writing a log message')
with open(filename, 'w') as fp:
    fp.write(message)

En este ejemplo, la cadena de caracteres 'writing a log message' está marcada como candidata para la traducción, mientras que las cadenas 'mylog.txt' y 'w' no lo están.

Existen algunas herramientas para extraer las cadenas destinadas a la traducción. El programa GNU original gettext solo admitía el código fuente C o C++, pero su versión extendida xgettext escanea el código escrito en varios idiomas, incluido Python, para encontrar cadenas marcadas como traducibles. Babel [http://babel.pocoo.org/] es una biblioteca de internacionalización de Python que incluye un script pybabel para extraer y compilar catálogos de mensajes. El programa de François Pinard llamado xpot hace un trabajo similar y está disponible como parte de su paquete po-utils [https://github.com/pinard/po-utils].

(Python también incluye versiones de Python puro de estos programas, llamadas pygettext.py y msgfmt.py; algunas distribuciones de Python las instalarán por usted. pygettext.py es similar a xgettext, pero solo entiende el código fuente de Python y no puede manejar otros lenguajes de programación como C o C++. pygettext.py admite una interfaz de línea de comandos similar a xgettext; para detalles sobre su uso, ejecute pygettext.py --help. msgfmt.py es binario compatible con GNU msgfmt. Con estos dos programas, es posible que no necesite el paquete GNU gettext para internacionalizar sus aplicaciones Python.)

xgettext, pygettext, y herramientas similares generan archivos .po que son catálogos de mensajes. Son archivos estructurados legibles por humanos que contienen cada cadena marcada en el código fuente, junto con un marcador de posición para las versiones traducidas de estas cadenas.

Las copias de estos archivos .po se entregan a los traductores humanos individuales que escriben traducciones para cada lenguaje natural compatible. Envían las versiones completas específicas del idioma como un archivo <nombre-idioma >.po que se compila en un archivo binario .mo de lectura mecánica utilizando el programa msgfmt . Los archivos .mo son utilizados por el módulo gettext para el procesamiento de traducción real en tiempo de ejecución.

Como use el módulo gettext en su código depende de si está internacionalizando un solo módulo o toda su aplicación. Las siguientes dos secciones discutirán cada caso.

Agregar configuración regional a su módulo

Si está aplicando configuración regional a su módulo, debe tener cuidado de no realizar cambios globales, por ejemplo, al espacio de nombres integrado. No debe utilizar la API GNU gettext, sino la API basada en clases.

Digamos que su módulo se llama «spam» y los diversos archivos .mo de traducciones del lenguaje natural del módulo residen en /usr/share/locale en formato GNU gettext. Esto es lo que pondría en la parte superior de su módulo:

import gettext
t = gettext.translation('spam', '/usr/share/locale')
_ = t.gettext

Agregar configuración regional a su aplicación

Si está aplicando configuración regional a su aplicación, puede instalar la función _() globalmente en el espacio de nombres incorporado, generalmente en el archivo del controlador principal de su aplicación. Esto permitirá que todos los archivos específicos de su aplicación usen _('...') sin tener que instalarlo explícitamente en cada archivo.

En el caso simple, entonces, solo necesita agregar el siguiente bit de código al archivo del controlador principal de su aplicación:

import gettext
gettext.install('myapplication')

Si necesita establecer el directorio de configuración regional, puede pasarlo a la función install():

import gettext
gettext.install('myapplication', '/usr/share/locale')

Cambiar idiomas sobre la marcha

Si su programa necesita admitir muchos idiomas al mismo tiempo, es posible que desee crear varias instancias de traducción y luego cambiar entre ellas explícitamente, de esta manera:

import gettext

lang1 = gettext.translation('myapplication', languages=['en'])
lang2 = gettext.translation('myapplication', languages=['fr'])
lang3 = gettext.translation('myapplication', languages=['de'])

# start by using language1
lang1.install()

# ... time goes by, user selects language 2
lang2.install()

# ... more time goes by, user selects language 3
lang3.install()

Traducciones diferidas

En la mayoría de las situaciones de codificación, las cadenas se traducen donde se codifican. Sin embargo, ocasionalmente, debe marcar cadenas para la traducción, pero diferir la traducción real hasta más tarde. Un ejemplo clásico es:

animals = ['mollusk',
           'albatross',
           'rat',
           'penguin',
           'python', ]
# ...
for a in animals:
    print(a)

Aquí, desea marcar las cadenas en la lista de animals como traducibles, pero en realidad no desea traducirlas hasta que se impriman.

Aquí hay una manera de manejar esta situación:

def _(message): return message

animals = [_('mollusk'),
           _('albatross'),
           _('rat'),
           _('penguin'),
           _('python'), ]

del _

# ...
for a in animals:
    print(_(a))

Esto funciona porque la definición ficticia de _() simplemente retorna la cadena sin cambios. Y esta definición ficticia anulará temporalmente cualquier definición de _() en el espacio de nombres incorporado (hasta el comando del). Sin embargo, tenga cuidado si tiene una definición previa de _() en el espacio de nombres local.

Tenga en cuenta que el segundo uso de _() no identificará «a» como traducible al programa gettext, porque el parámetro no es un literal de cadena.

Otra forma de manejar esto es con el siguiente ejemplo:

def N_(message): return message

animals = [N_('mollusk'),
           N_('albatross'),
           N_('rat'),
           N_('penguin'),
           N_('python'), ]

# ...
for a in animals:
    print(_(a))

En este caso, está marcando cadenas traducibles con la función N_(), que no entrará en conflicto con ninguna definición de _(). Sin embargo, deberá enseñar a su programa de extracción de mensajes a buscar cadenas traducibles marcadas con N_(). xgettext, pygettext, pybabel extract, y xpot todos soportan esto mediante el uso de -k interruptor de línea de comando. La elección de N_() aquí es totalmente arbitraria; podría haber sido igual de fácil MarkThisStringForTranslation().

Agradecimientos

Las siguientes personas contribuyeron con código, comentarios, sugerencias de diseño, implementaciones anteriores y una valiosa experiencia para la creación de este módulo:

Peter Funk

James Henstridge

Juan David Ibáñez Palomar

Marc-André Lemburg

Martin von Löwis

François Pinard

Barry Warsaw

Gustavo Niemeyer

Notas al pie

1

El directorio de configuración regional predeterminado depende del sistema; por ejemplo, en RedHat Linux es /usr/share/locale, pero en Solaris es /usr/lib/locale. El módulo gettext no intenta admitir estos valores predeterminados dependientes del sistema; en cambio, su valor predeterminado es sys.base_prefix/share/locale (ver sys.base_prefix). Por esta razón, siempre es mejor llamar a bindtextdomain() con una ruta absoluta explícita al inicio de su aplicación.

2

Vea la nota al pie de página para bindtextdomain() arriba.

locale — Servicios de internacionalización

Source code: Lib/locale.py [https://github.com/python/cpython/tree/3.9/Lib/locale.py]

El módulo locale abre el acceso a la base de datos y la funcionalidad de POSIX locale. El mecanismo POSIX locale permite a los programadores tratar ciertos problemas culturales en una aplicación, sin requerir que el programador conozca todos los detalles de cada país donde se ejecuta el software.

El módulo locale se implementa en la parte superior del módulo _locale, que a su vez utiliza una implementación de configuración regional ANSI C si está disponible.

El módulo locale define las siguientes excepciones y funciones:

exception locale.Error

Cuando el locale pasado a setlocale() no es reconocido, se lanza una excepción.

locale.setlocale(category, locale=None)

Si locale está dado y no es None, setlocale() modifica la configuración de localización para category. Las categorías disponibles se enumeran en la descripción de los datos que figura a continuación. locale puede ser una cadena de caracteres, o una iterable de dos cadenas de caracteres (código de idioma y codificación). Si es iterable, se convierte a un nombre de configuración regional usando el motor de aliasing de la configuración regional. Una cadena de caracteres vacía especifica la configuración predeterminada del usuario. Si la modificación de la localización falla, se genera la excepción Error . Si tiene éxito, se retorna la nueva configuración de localización.

Si se omite locale o es None, se retorna la configuración actual para category.

setlocale() no es seguro para subprocesos en la mayoría de los sistemas. Las aplicaciones normalmente comienzan con una llamada de

import locale
locale.setlocale(locale.LC_ALL, '')

Esto establece la configuración regional de todas las categorías en la configuración predeterminada del usuario (normalmente especificada en la variable de entorno LANG ). Si la configuración regional no se cambia a partir de entonces, el uso de multiprocesamiento, no debería causar problemas.

locale.localeconv()

retorna la base de datos de las convenciones locales como diccionario. Este diccionario tiene las siguientes cadenas de caracteres como claves:

Categoría

Clave

Significado

LC_NUMERIC

'decimal_point'

Carácter de punto decimal.

'agrupación'

Secuencia de números que especifica qué posiciones relativas se espera el 'miles_sep'. Si la secuencia termina con CHAR_MAX, no se realiza ninguna agrupación adicional. Si la secuencia termina con un 0, el último tamaño de grupo se usa repetidamente.

'thousands_sep'

Carácter utilizado entre grupos.

LC_MONETARY

'int_curr_symbol'

Símbolo de moneda internacional.

'currency_symbol'

Símbolo de moneda local.

'p_cs_precedes/n_cs_precedes'

Si el símbolo de moneda precede al valor (para valores positivos o negativos).

'p_sep_by_space/n_sep_by_space'

Si el símbolo de moneda está separado del valor por un espacio (para valores positivos o negativos).

'mon_decimal_point'

Punto decimal utilizado para valores monetarios.

'frac_digits'

Número de dígitos fraccionarios utilizados en el formateo local de valores monetarios.

'int_frac_digits'

Número de dígitos fraccionarios utilizados en el formateo internacional de valores monetarios.

'mon_thousands_sep'

Separador de grupo utilizado para valores monetarios.

'mon_grouping'

Equivalente a 'grouping', utilizada para valores monetarios.

'positive_sign'

Símbolo utilizado para anotar un valor monetario positivo.

'negative_sign'

Símbolo utilizado para anotar un valor monetario negativo.

'p_sign_posn/n_sign_posn'

La posición del signo (para respuestas positivas. valores negativos), ver abajo.

Todos los valores numéricos se pueden establecer a CHAR_MAX para indicar que no hay ningún valor especificado en esta configuración regional.

Los valores posibles para 'p_sign_posn' y `` “n_sign_posn”`` se dan a continuación.

Valor

Explicación

0

Moneda y valor están rodeados por paréntesis.

1

El signo debe preceder al valor y al símbolo de moneda.

2

El signo debe seguir el valor y el símbolo de moneda.

3

El signo debe preceder inmediatamente al valor.

4

El signo debe seguir inmediatamente al valor.

CHAR_MAX

No se especifica nada en esta configuración regional.

La función establece temporalmente el LC_CTYPE de configuración regional al LC_NUMERIC de la configuración regional o el LC_MONETARY de la configuración local si las configuraciones locales son diferentes y las cadenas de caracteres numéricas o monetarias no son ASCII. Este cambio temporal afecta a otros hilos.

Distinto en la versión 3.7: La función ahora establece temporalmente el LC_CTYPE de la configuración local al LC_NUMERIC en algunos casos.

locale.nl_langinfo(option)

retorna información específica de la configuración regional como una cadena de caracteres. Esta función no está disponible en todos los sistemas, y el conjunto de opciones posibles también puede variar entre plataformas. Los posibles valores de argumento son números, para los cuales las constantes simbólicas están disponibles en el módulo de configuración regional.

La función nl_langinfo() acepta una de las siguientes claves. La mayoría de las descripciones están tomadas de la descripción correspondiente en la biblioteca C de GNU.

locale.CODESET

Obtiene una cadena de caracteres con el nombre de la codificación de caracteres utilizada en la configuración regional seleccionada.

locale.D_T_FMT

Obtiene una cadena de caracteres que se puede utilizar como cadena de caracteres de formato para time.strftime() para representar la fecha y la hora de una manera específica de la configuración regional.

locale.D_FMT

Obtiene una cadena de caracteres que se puede utilizar como cadena de formato para time.strftime() para representar una fecha de una manera específica de la configuración regional.

locale.T_FMT

Obtiene una cadena de caracteres que se puede utilizar como cadena de formato para time.strftime() para representar un tiempo de una manera específica de la configuración regional.

locale.T_FMT_AMPM

Obtiene una cadena de caracteres de formato para time.strftime() para representar el tiempo en el formato am/pm.

DAY_1 ... DAY_7

Consigue el nombre del n-ésimo día de la semana.

Nota

Esto sigue la convención estadounidense de DAY_1 siendo domingo, no la convención internacional (ISO 8601) que el lunes es el primer día de la semana.

ABDAY_1 ... ABDAY_7

Obtener el nombre abreviado del n-ésimo día de la semana.

MON_1 ... MON_12

Obtener el nombre del n-ésimo mes.

ABMON_1 ... ABMON_12

Obtener el nombre abreviado del enésimo mes.

locale.RADIXCHAR

Obtener el carácter radical (punto decimal, coma decimal, etc.).

locale.THOUSEP

Obtener el carácter separador de miles (grupos de tres dígitos).

locale.YESEXPR

Obtener una expresión regular que se pueda usar con la función regex para reconocer una respuesta positiva a una pregunta de sí / no.

Nota

La expresión está en la sintaxis adecuada para la función regex() de la biblioteca C, que podría diferir de la sintaxis utilizada en re.

locale.NOEXPR

Obtener una expresión regular que se puede usar con la función regex(3) para reconocer una respuesta negativa a una pregunta de sí/no.

locale.CRNCYSTR

Obtener el símbolo de moneda, precedido por «-» si el símbolo debe aparecer antes del valor, «+» si el símbolo debe aparecer después del valor, o «.» si el símbolo debe reemplazar el carácter raíz.

locale.ERA

Obtener una cadena de caracteres que represente la era utilizada en la configuración regional actual.

La mayoría de las configuraciones regionales no definen este valor. Un ejemplo de una localidad que sí define este valor es la japonesa. En Japón, la representación tradicional de fechas incluye el nombre de la época correspondiente al reinado del entonces emperador.

Normalmente no debería ser necesario utilizar este valor directamente. Especificar el modificador E en sus cadenas de caracteres de formato hace que la función time.strftime() use esta información. El formato de la cadena de caracteres retornada no está especificado, y por lo tanto no debe asumir conocimiento de él en diferentes sistemas.

locale.ERA_D_T_FMT

Obtener una cadena de caracteres de formato para time.strftime() para representar la fecha y la hora de una manera específica de la era.

locale.ERA_D_FMT

Obtener una cadena de caracteres de formato para time.strftime() para representar una fecha de una manera basada en una era específica.

locale.ERA_T_FMT

Obtener una cadena de caracteres de formato para time.strftime() para representar una hora de una manera basada en una era específica.

locale.ALT_DIGITS

Obtener una representación de hasta 100 valores utilizados para representar los valores 0 a 99.

locale.getdefaultlocale([envvars])

Intenta determinar la configuración regional por defecto y los retorna como una tupla del formulario (código de idioma, codificación).

De acuerdo con POSIX, un programa que no ha llamado a setlocale(LC_ALL, '') se ejecuta utilizando la configuración regional portátil `` “C “`` . Llamar a setlocale(LC_ALL, ' ') le permite usar la configuración regional predeterminada definida por la variable LANG . Dado que no queremos interferir con la configuración de configuración regional actual, emulamos el comportamiento de la manera descrita anteriormente.

Para mantener la compatibilidad con otras plataformas, no sólo se prueba la variable LANG sino una lista de variables dadas como parámetro envvars. Se utilizará la primera que se encuentre definida. envvars por defecto a la ruta de búsqueda utilizada en GNU gettext; siempre debe contener el nombre de la variable 'LANG '. La ruta de búsqueda GNU gettext contiene 'LC_ALL ', 'LC_CTYPE ', 'LANG ' y 'LANGUAGE ', en ese orden.

Excepto por el código 'C', el código de lenguaje corresponde a RFC 1766 [https://tools.ietf.org/html/rfc1766.html]. language code y encoding pueden ser None si sus valores no pueden determinarse.

locale.getlocale(category=LC_CTYPE)

retorna la configuración actual para la categoría de configuración regional dada como secuencia que contiene language code, coding. category puede ser uno de los valores LC_  * excepto LC_ALL. Por defecto es LC_CTYPE.

Excepto por el código 'C', el código de lenguaje corresponde a RFC 1766 [https://tools.ietf.org/html/rfc1766.html]. language code y encoding pueden ser None si sus valores no pueden determinarse.

locale.getpreferredencoding(do_setlocale=True)

retorna la codificación utilizada para los datos de texto, según las preferencias del usuario. Las preferencias del usuario se expresan de manera diferente en diferentes sistemas, y puede que no estén disponibles programáticamente en algunos sistemas, por lo que esta función solo retorna una suposición.

En algunos sistemas, es necesario invocar setlocale() para obtener las preferencias del usuario, por lo que esta función no es segura para subprocesos. Si invocar setlocale no es necesario o deseado, do_setlocale se debe ajustar a False.

En Android o en el modo UTF-8 (-X utf8 opción), siempre retorna 'UTF-8 ', se ignoran la configuración regional y el argumento do_setlocale.

Distinto en la versión 3.7: La función ahora siempre retorna UTF-8 en Android o si el modo UTF-8 está habilitado.

locale.normalize(localename)

retorna un código de configuración regional normalizado para el nombre configuración regional dado. El código de configuración regional retornado está formateado para usarse con setlocale(). Si la normalización falla, el nombre original se retorna sin cambios.

Si no se conoce la codificación dada, la función por defecto codifica el código de configuración regional como setlocale().

locale.resetlocale(category=LC_ALL)

Establece la configuración regional de category a la configuración predeterminada.

La configuración predeterminada se determina llamando a getdefaultlocale(). category por defecto a LC_ALL.

locale.strcoll(string1, string2)

Compara dos cadenas según la configuración actual LC_COLLATE . Como cualquier otra función de comparación, retorna un valor negativo o positivo, o 0, dependiendo de si string1 compila antes o después de string2 o es igual a él.

locale.strxfrm(string)

Transforma una cadena en una que se puede utilizar en comparaciones de localización. Por ejemplo, strxfrm(s1) < strxfrm(s2) es equivalente a strcoll(s1, s2) < 0. Esta función se puede utilizar cuando la misma cadena se compara repetidamente, p. ej., al agrupar una secuencia de cadenas.

locale.format_string(format, val, grouping=False, monetary=False)

Formatea un número val según la configuración actual LC_NUMERIC . El formato sigue las convenciones del operador %. Para los valores en coma flotante, el punto decimal se modifica si procede. Si grouping es verdadero, también se tiene en cuenta el agrupamiento.

Si monetary es verdadero, la conversión utiliza separador monetario de miles y cadenas de caracteres de agrupación.

Procesa especificadores de formato como en format % val, pero tiene en cuenta los ajustes de configuración regional actuales.

Distinto en la versión 3.7: Se añadió el parámetro de la palabra clave monetary.

locale.format(format, val, grouping=False, monetary=False)

Tenga en cuenta que esta función funciona como format_string() pero sólo funcionará para exactamente un especificador %char. Por ejemplo, '%f' y '%. 0f' son especificadores válidos, pero '%f KiB' no lo es.

Para cadenas de caracteres de formato completas, use format_string().

Obsoleto desde la versión 3.7: Use format_string() en su lugar.

locale.currency(val, symbol=True, grouping=False, international=False)

Formatea un número val según la configuración actual LC_MONETARY .

La cadena de caracteres retornada incluye el símbolo de moneda si symbol es verdadero, que es el valor predeterminado. Si grouping es verdadero (que no es el valor predeterminado), la agrupación se realiza con el valor. Si international es verdadero (que no es el valor predeterminado), se utiliza el símbolo de moneda internacional.

Tenga en cuenta que esta función no funcionará con la configuración regional “C”, por lo que primero debe establecer una configuración regional (locale) a través de setlocale() .

locale.str(float)

Formatea un número de punto flotante usando el mismo formato que la función integrada str(float), pero toma en cuenta el punto decimal.

locale.delocalize(string)

Convierte una cadena de caracteres en una cadena de números normalizada, siguiendo la configuración LC_NUMERIC.

Nuevo en la versión 3.5.

locale.atof(string, func=float)

Converts a string to a number, following the LC_NUMERIC settings, by calling func on the result of calling delocalize() on string.

locale.atoi(string)

Convierte una cadena de caracteres a un entero, siguiendo las convenciones LC_NUMERIC .

locale.LC_CTYPE

Configuración regional de localización para las funciones de tipo caracter. Dependiendo de la configuración de esta categoría, las funciones del módulo string que se ocupan de casos cambian su comportamiento.

locale.LC_COLLATE

Categoría de configuración regional para ordenar cadenas de caracteres. Las funciones strcoll() y strxfrm() del módulo locale están afectadas.

locale.LC_TIME

Categoría de configuración regional para el formateo de hora. La función time.strftime() sigue estas convenciones.

locale.LC_MONETARY

Categoría de configuración regional para el formateo de valores monetarios. Las opciones disponibles están disponibles en la función localeconv() .

locale.LC_MESSAGES

Categoría de configuración regional para visualización de mensajes. Python actualmente no admite mensajes de configuración regional específicos de la aplicación. Los mensajes mostrados por el sistema operativo, como los retornados por os.strerror() podrían verse afectados por esta categoría.

locale.LC_NUMERIC

Categoría de configuración regional para formateo de números. Las funciones format(), atoi(), atof() y str() del módulo locale están afectados por esa categoría. Todas las demás operaciones de formato numérico no están afectadas.

locale.LC_ALL

Combinación de todos los ajustes de configuración regional. Si se utiliza este indicador cuando se cambia la localización, se intenta establecer la localización para todas las categorías. Si eso falla para cualquier categoría, ninguna categoría se cambia en absoluto. Cuando la configuración regional se recupera usando este indicador, se retorna una cadena de caracteres que indica la configuración para todas las categorías. Esta cadena de caracteres se puede usar más tarde para restaurar la configuración.

locale.CHAR_MAX

Esta es una constante simbólica utilizada para diferentes valores retornados por localeconv().

Ejemplo:

>>> import locale
>>> loc = locale.getlocale()  # get current locale
# use German locale; name might vary with platform
>>> locale.setlocale(locale.LC_ALL, 'de_DE')
>>> locale.strcoll('f\xe4n', 'foo')  # compare a string containing an umlaut
>>> locale.setlocale(locale.LC_ALL, '')   # use user's preferred locale
>>> locale.setlocale(locale.LC_ALL, 'C')  # use default (C) locale
>>> locale.setlocale(locale.LC_ALL, loc)  # restore saved locale

Segundo plano, detalles, indicaciones, consejos y advertencias

El estándar C define la configuración regional como una propiedad de todo el programa que puede ser relativamente costosa de cambiar. Además de eso, alguna implementación se rompe de tal manera que los cambios de configuración local frecuentes pueden causar volcados de núcleo. Esto hace que la configuración regional sea algo dolorosa de usar correctamente.

Inicialmente, cuando se inicia un programa, la configuración regional es la configuración regional C, no importa cuál sea la configuración regional preferida por el usuario. Hay una excepción: la categoría LC_CTYPE se cambia al inicio para establecer la codificación de la configuración regional actual en la codificación de configuración regional preferida del usuario. El programa debe decir explícitamente que quiere la configuración regional preferida del usuario para otras categorías llamando a setlocale(LC_ALL, '').

Generalmente es una mala idea llamar setlocale() en alguna rutina de biblioteca, ya que como efecto secundario afecta a todo el programa. Guardar y restaurar es casi igual de malo: es caro y afecta a otros hilos que se ejecutan antes de que los ajustes se hayan restaurado.

Si, al codificar un módulo para uso general, se necesita una versión configuración regional independiente de una operación que se ve afectada por la localización (como ciertos formatos utilizados con time.strftime()), tendrá que encontrar una manera de hacerlo sin usar la rutina de biblioteca estándar. Aún mejor es convencerse a sí mismo de que el uso de la configuración regional está bien. Sólo como último recurso debe documentar que su módulo no es compatible con la configuración regional no- C.

La única manera de realizar operaciones numéricas según la configuración regional es utilizar las funciones especiales definidas por este módulo: atof(), atoi(), formato(), str().

No hay manera de realizar conversiones de casos y clasificaciones de caracteres de acuerdo a la configuración regional. Para cadenas de texto (Unicode) estas se hacen de acuerdo con el valor de carácter solamente, mientras que para cadenas de bytes, las conversiones y clasificaciones se hacen de acuerdo con el valor ASCII del byte, y bytes cuyo bit alto se establece (es decir, bytes no ASCII) nunca se convierten o se consideran parte de una clase de caracteres como letra o espacio en blanco.

Para escritores de extensión y programas que incrustan Python

Los módulos de extensión nunca deben llamar a setlocale(), excepto para averiguar cuál es la configuración regional actual. Pero dado que el valor de retorno sólo se puede utilizar portablemente para restaurarlo, eso no es muy útil (excepto quizás para averiguar si la localización es o no es C).

Cuando el código de Python utiliza el módulo locale para cambiar la configuración regional, esto también afecta a la aplicación de incrustación. Si la aplicación de incrustación no quiere que esto suceda, debe eliminar el módulo de extensión _locale (que hace todo el trabajo) de la tabla de módulos incorporados en el archivo de configuración config.c, y asegúrese de que el módulo _locale no es accesible como una biblioteca compartida.

Acceso a los catálogos de mensajes

locale.gettext(msg)

locale.dgettext(domain, msg)

locale.dcgettext(domain, msg, category)

locale.textdomain(domain)

locale.bindtextdomain(domain, dir)

El módulo de configuración regional expone la interfaz gettext de la biblioteca C en sistemas que proporcionan esta interfaz. Consta de las funciones gettext(), dgettext(), dcgettext(), textdomain(), binddomaintext(), y bind_textdomain_codeset(). Estas son similares a las mismas funciones en el módulo gettext , pero usan el formato binario de la biblioteca C para catálogos de mensajes, y los algoritmos de búsqueda de la biblioteca C para localizar catálogos de mensajes.

Las aplicaciones de Python normalmente no deberían tener que invocar estas funciones, y deberían usar gettext en su lugar. Una excepción conocida a esta regla son las aplicaciones que enlazan con bibliotecas C adicionales que invocan internamente gettext() o dcgettext(). Para estas aplicaciones, puede ser necesario vincular el dominio de texto, para que las bibliotecas puedan localizar adecuadamente sus catálogos de mensajes.

Frameworks de programa

Los módulos descritos en este capitulo son frameworks que dictarán en gran medida la estructura de su programa. Actualmente, los módulos descritos aquí están orientados para escribir en las interfaces de línea de comandos.

La lista completa de módulos descritos en este capítulo es:

turtle — Gráficos con Turtle

Introducción

Reseña de los métodos disponibles para Turtle y Screen

Métodos Turtle

Métodos de TurtleScreen/Screen

Métodos de RawTurtle/Turtle Y sus correspondientes funciones

Movimiento de Turtle

Mostrar el estado de la tortuga

Configuración de las medidas

Control del lápiz

Estado de dibujo

Control del color

Relleno

Más controles de dibujo

Estado de la Tortuga

Visibilidad

Apariencia

Usando eventos

Métodos especiales de Turtle

Formas compuestas

Métodos de TurtleScreen/Screen y sus correspondientes funciones

Control de ventana

Control de animación

Usando eventos de pantalla

Métodos de entrada

Configuración y métodos especiales

Métodos específicos de Screen, no heredados de TurtleScreen

Clases públicas

Ayuda y configuración

Cómo usar la ayuda

Traducción de cadenas de documentos a diferentes idiomas

Cómo configurar Screen and Turtles

turtledemo — Scripts de demostración

Cambios desde Python 2.6

Cambios desde Python 3.0

cmd — Soporte para intérpretes orientados a línea de comandos

Objetos Cmd

Ejemplo Cmd

shlex — Análisis léxico simple

objetos shlex

Reglas de análisis

Compatibilidad mejorada con intérprete de comandos

turtle — Gráficos con Turtle

Código fuente: Lib/turtle.py [https://github.com/python/cpython/tree/3.9/Lib/turtle.py]

Introducción

Gráficas Turtle es una forma muy habitual de introducción a la programación para niñas y niños. Era parte original del lenguaje de programación Logo, desarrollado por Wally Feurzeig, Seymour Papert y Cynthia Solomon en 1967.

Imagina una tortuga robot que empieza en las coordenadas (0, 0) en un plano x-y. Después de un import turtle, dele el comando turtle.forward(15), y se mueve (¡en la pantalla!) 15 pixeles en la dirección en la que se encuentra, dibujando una línea mientras se mueve. Dele el comando turtle.right(25), y rotará en el lugar, 25 grados, en sentido horario.

Turtle star

Turtle puede dibujar figuras intrincadas usando programas que repiten movimientos simples.

from turtle import *
color('red', 'yellow')
begin_fill()
while True:
    forward(200)
    left(170)
    if abs(pos()) < 1:
        break
end_fill()
done()

Al combinar estos comandos y otros similares, se pueden dibujar figuras intrincadas y formas.

El módulo turtle es una reimplementación extendida del mismo módulo de la distribución estándar Python hasta la versión 2.5.

Trata de mantener los méritos del viejo módulo y ser (casi) 100% compatible con él. Esto implica en primer lugar, habilitar al programador que está aprendiendo, el uso de todos los comandos, clases y métodos de forma interactiva cuando usa el módulo desde el IDLE ejecutado con la opción -n.

El módulo turtle provee las primitivas gráficas, tanto en orientación procedimental como orientada a objetos. Como usa el módulo tkinter para las gráficas subyacentes, necesita tener instalada una versión de Python con soporte TK.

La interface orientada a objetos usa esencialmente clases dos+dos:

La clase TurtleScreen define una ventana gráfica como base para las tortugas dibujantes. Su constructor necesita una clase tkinter.Canvas o una a ScrolledCanvas como argumento. Se debe usar cuando turtle es usado como parte de una aplicación.

La función Screen() devuelve un objeto singleton de la subclase TurtleScreen. Esta función debe utilizarse cuando turtle se usa como una herramienta independiente para hacer gráficos. Siendo un objeto singleton, no es posible que tenga herencias de su clase.

Todos los métodos de TurtleScreen/Screen también existen como funciones. Por ejemplo. como parte de la interface orientada a procedimientos.

RawTurtle (alias: RawPen) Define los objetos Turtle con los cuales dibujar con la clase TurtleScreen. Su constructor necesita como argumento un Canvas, ScrolledCanvas o TurtleScreen, así el objeto RawTurtle sabe donde dibujar.

Derivada de RawTurtle está la subclase Turtle (alias: Pen), que dibuja en «la» instancia Screen que se crea automáticamente, si no está presente.

Todos los métodos de RawTurtle/Turtle también existen como funciones. Por ejemplo, como parte de la interface orientada a procedimientos.

La interface procedimental provee funciones que son derivadas de los métodos de las clases Screen y Turtle. Tienen los mismos nombres que los métodos correspondientes. Un objeto Screen es creado automáticamente cada vez que una función derivada de un método Screen es llamado. Un objeto Turtle (innombrado) se crea automáticamente cada vez que se llama a una función derivada de un método Turtle.

Para usar varias tortugas en una pantalla se tiene que usar la interface orientada a objetos.

Nota

En la siguiente documentación se proporciona la listas de argumentos para las funciones. Los métodos, por su puesto, tienen el argumento principal adicional self que se omite aquí.

Reseña de los métodos disponibles para Turtle y Screen

Métodos Turtle

Movimiento de Turtle

Mover y dibujar

forward() | fd()

backward() | bk() | back()

right() | rt()

left() | lt()

goto() | setpos() | setposition()

setx()

sety()

setheading() | seth()

home()

circle()

dot()

stamp()

clearstamp()

clearstamps()

undo()

speed()

Mostrar el estado de la tortuga

position() | pos()

towards()

xcor()

ycor()

heading()

distance()

Ajuste y unidades de medida

degrees()

radians()

Control del lápiz

Estado de dibujo

pendown() | pd() | down()

penup() | pu() | up()

pensize() | width()

pen()

isdown()

Control del color

color()

pencolor()

fillcolor()

Relleno

filling()

begin_fill()

end_fill()

Más controles de dibujo

reset()

clear()

write()

Estado de la Tortuga

Visibilidad

showturtle() | st()

hideturtle() | ht()

isvisible()

Apariencia

shape()

resizemode()

shapesize() | turtlesize()

shearfactor()

settiltangle()

tiltangle()

tilt()

shapetransform()

get_shapepoly()

Usando eventos

onclick()

onrelease()

ondrag()

Métodos especiales de Turtle

begin_poly()

end_poly()

get_poly()

clone()

getturtle() | getpen()

getscreen()

setundobuffer()

undobufferentries()

Métodos de TurtleScreen/Screen

Control de ventana

bgcolor()

bgpic()

clearscreen()

resetscreen()

screensize()

setworldcoordinates()

Control de animación

delay()

tracer()

update()

Usando eventos de pantalla

listen()

onkey() | onkeyrelease()

onkeypress()

onclick() | onscreenclick()

ontimer()

mainloop() | done()

Configuración y métodos especiales

mode()

colormode()

getcanvas()

getshapes()

register_shape() | addshape()

turtles()

window_height()

window_width()

Métodos de entrada

textinput()

numinput()

Métodos específicos para Screen

bye()

exitonclick()

setup()

title()

Métodos de RawTurtle/Turtle Y sus correspondientes funciones

Casi todos los ejemplos de esta sección se refieren a una instancia Turtle llamada turtle.

Movimiento de Turtle

turtle.forward(distance)

turtle.fd(distance)

Parámetros

distance – un número (entero o flotante)

Mover hacia adelante la tortuga la ditance especificada, en la dirección en la que la tortuga apunta.

>>> turtle.position()
(0.00,0.00)
>>> turtle.forward(25)
>>> turtle.position()
(25.00,0.00)
>>> turtle.forward(-75)
>>> turtle.position()
(-50.00,0.00)

turtle.back(distance)

turtle.bk(distance)

turtle.backward(distance)

Parámetros

distance – un número

Mover hacia atrás la tortuga la distance especificada, opuesta a la dirección en que la tortuga apunta. No cambia la dirección de la tortuga.

>>> turtle.position()
(0.00,0.00)
>>> turtle.backward(30)
>>> turtle.position()
(-30.00,0.00)

turtle.right(angle)

turtle.rt(angle)

Parámetros

angle – un número (entero o flotante)

Gira la tortuga a la derecha tomando los angle como unidad de medida. (La unidad de medida por defecto son los grado, pero se puede configurar a través de las funciones degrees() y radians().) La orientación de los ángulos depende del modo en que está la tortuga, ver mode().

>>> turtle.heading()
22.0
>>> turtle.right(45)
>>> turtle.heading()
337.0

turtle.left(angle)

turtle.lt(angle)

Parámetros

angle – un número (entero o flotante)

Gira la tortuga a la izquierda tomando los ángulos como unidad de medida. (La unidad de medida por defecto son los grado, pero se puede configurar a través de las funciones degrees() y radians().) La orientación de los ángulos depende del modo en que está la tortuga, ver mode().

>>> turtle.heading()
22.0
>>> turtle.left(45)
>>> turtle.heading()
67.0

turtle.goto(x, y=None)

turtle.setpos(x, y=None)

turtle.setposition(x, y=None)

Parámetros

x – un número o un par/vector de números

y – un número o None

Si y es None, x debe ser un par de coordenadas o un Vec2D (ejemplo: según lo devuelto por pos()).

Mueve la tortuga a una posición absoluta. Si el lápiz está bajo, traza una linea. No cambia la orientación de la tortuga.

 >>> tp = turtle.pos()
 >>> tp
 (0.00,0.00)
 >>> turtle.setpos(60,30)
 >>> turtle.pos()
 (60.00,30.00)
 >>> turtle.setpos((20,80))
 >>> turtle.pos()
 (20.00,80.00)
 >>> turtle.setpos(tp)
 >>> turtle.pos()
 (0.00,0.00)

turtle.setx(x)

Parámetros

x – un número (entero o flotante)

Establece la primera coordenada de la tortuga a x, deja la segunda coordenada sin cambios.

>>> turtle.position()
(0.00,240.00)
>>> turtle.setx(10)
>>> turtle.position()
(10.00,240.00)

turtle.sety(y)

Parámetros

y – un número (entero o flotante)

Establece la segunda coordenada de la tortuga a y, deja la primera coordenada sin cambios.

>>> turtle.position()
(0.00,40.00)
>>> turtle.sety(-10)
>>> turtle.position()
(0.00,-10.00)

turtle.setheading(to_angle)

turtle.seth(to_angle)

Parámetros

to_angle – un número (entero o flotante)

Establece la orientación de la tortuga a to_angle. Aquí hay algunas direcciones comunes en grados:

modo estándar

modo logo

0 - este

0 - norte

90 - norte

90 - este

180 - oeste

180 - sur

270 - sur

270 - oeste

>>> turtle.setheading(90)
>>> turtle.heading()
90.0

turtle.home()

Mueve la tortuga al origen – coordenadas (0,0) – y establece la orientación a la orientación original (que depende del modo, ver mode()).

>>> turtle.heading()
90.0
>>> turtle.position()
(0.00,-10.00)
>>> turtle.home()
>>> turtle.position()
(0.00,0.00)
>>> turtle.heading()
0.0

turtle.circle(radius, extent=None, steps=None)

Parámetros

radius – un número

extent – un número (o None)

steps – un entero (o None)

Dibuja un círculo con el radius (radio) dado. El centro es radius unidades a la izquierda de la tortuga; extent – un ángulo – determina que parte del círculo se dibuja. Si no se pasa extent, dibuja el círculo entero. Si extent no es un círculo completo, un punto final del arco es la posición actual de lápiz. Dibuja el arco en dirección antihorario si radius es positivo, si no en dirección horaria. Finalmente la dirección de la tortuga es modificada por el aumento de extent.

Como el círculo se aproxima a un polígono regular inscripto, steps determina el número de pasos a usar. Si no se da, será calculado automáticamente. Puede ser usado para dibujar polígonos regulares.

>>> turtle.home()
>>> turtle.position()
(0.00,0.00)
>>> turtle.heading()
0.0
>>> turtle.circle(50)
>>> turtle.position()
(-0.00,0.00)
>>> turtle.heading()
0.0
>>> turtle.circle(120, 180)  # draw a semicircle
>>> turtle.position()
(0.00,240.00)
>>> turtle.heading()
180.0

turtle.dot(size=None, *color)

Parámetros

size – un entero >= 1 (si se da)

color – un colorstring o una tupla numérica de color

Dibuja un punto circular con diámetro size, usando color. Si size no se da, el máximo de pensize+4 y 2*pensize es usado.

>>> turtle.home()
>>> turtle.dot()
>>> turtle.fd(50); turtle.dot(20, "blue"); turtle.fd(50)
>>> turtle.position()
(100.00,-0.00)
>>> turtle.heading()
0.0

turtle.stamp()

Estampa una copia de la forma de la tortuga en el lienzo en la posición actual. Devuelve un stamp_id por cada estampa, que puede ser usado para borrarlo al llamar clearstamp(stamp_id).

>>> turtle.color("blue")
>>> turtle.stamp()
11
>>> turtle.fd(50)

turtle.clearstamp(stampid)

Parámetros

stampid – un entero, debe devolver el valor de la llamada previa de la función stamp() call

Borra la estampa con el stampid dado.

>>> turtle.position()
(150.00,-0.00)
>>> turtle.color("blue")
>>> astamp = turtle.stamp()
>>> turtle.fd(50)
>>> turtle.position()
(200.00,-0.00)
>>> turtle.clearstamp(astamp)
>>> turtle.position()
(200.00,-0.00)

turtle.clearstamps(n=None)

Parámetros

n – un entero (o None)

Borra todas o las primeros/últimos n estampas de la tortuga. Si n es None , borra todas las estampas, Si n > 0 borra la primera estampa n, sino y n < 0 borra la última estampa n.

>>> for i in range(8):
...     turtle.stamp(); turtle.fd(30)
13
14
15
16
17
18
19
20
>>> turtle.clearstamps(2)
>>> turtle.clearstamps(-2)
>>> turtle.clearstamps()

turtle.undo()

Deshace (repetidamente) la(s) última(s) acción(es) de la tortuga. El número de acciones a deshacer es determinado por el tamaño del undobuffer.

>>> for i in range(4):
...     turtle.fd(50); turtle.lt(80)
...
>>> for i in range(8):
...     turtle.undo()

turtle.speed(speed=None)

Parámetros

speed – un entero en el rango 0..10 o un speedstring (ver abajo)

Establecer la velocidad de la tortuga a un valor entero en el rango 0..10. Si no se pasa ningún argumento, vuelve a la velocidad actual.

Si el parámetro de entrada es un número mayor que 10 o menor que 0.5, la velocidad se establece a 0. La frase acerca de la velocidad es mapeada a valores de velocidad de la siguiente manera:

«fastest»: 0

«fast»: 10

«normal»: 6

«slow»: 3

«slowest»: 1

Velocidades de 1 a 10 generan una animación cada vez más rápida al dibujar las líneas y en el giro de la tortuga.

Atención: speed = 0 implica que no habrá ninguna animación. Los métodos fordward/back harán que la tortuga salte, de la misma manera que left/right hará que la tortuga gire instantáneamente.

>>> turtle.speed()
3
>>> turtle.speed('normal')
>>> turtle.speed()
6
>>> turtle.speed(9)
>>> turtle.speed()
9

Mostrar el estado de la tortuga

turtle.position()

turtle.pos()

Devuelve la posición actual de la tortuga (x,y) (como un vector Vec2D)

>>> turtle.pos()
(440.00,-0.00)

turtle.towards(x, y=None)

Parámetros

x – un número o par de vectores numéricos o una instancia de la tortuga

y – un número si x es un número, si no None

Retorna el ángulo entre la línea en la posición de la tortuga a la posición especificada en (x, y), el vector o la otra tortuga. Esto depende de la posición inicial de la tortuga, que depende del modo - «standard»/»world» o «logo».

>>> turtle.goto(10, 10)
>>> turtle.towards(0,0)
225.0

turtle.xcor()

Devuelve la coordinada x de la tortuga.

>>> turtle.home()
>>> turtle.left(50)
>>> turtle.forward(100)
>>> turtle.pos()
(64.28,76.60)
>>> print(round(turtle.xcor(), 5))
64.27876

turtle.ycor()

Devuelve la coordenada y de la tortuga.

>>> turtle.home()
>>> turtle.left(60)
>>> turtle.forward(100)
>>> print(turtle.pos())
(50.00,86.60)
>>> print(round(turtle.ycor(), 5))
86.60254

turtle.heading()

Devuelve la orientación actual de la tortuga (el valor depende del modo de la tortuga, ver mode()).

>>> turtle.home()
>>> turtle.left(67)
>>> turtle.heading()
67.0

turtle.distance(x, y=None)

Parámetros

x – un número o par de vectores numéricos o una instancia de la tortuga

y – un número si x es un número, si no None

Devuelve la distancia desde la tortuga al vector (x,y) dado, otra instancia de la tortuga, el valor es unidad pasos de tortuga.

>>> turtle.home()
>>> turtle.distance(30,40)
50.0
>>> turtle.distance((30,40))
50.0
>>> joe = Turtle()
>>> joe.forward(77)
>>> turtle.distance(joe)
77.0

Configuración de las medidas

turtle.degrees(fullcircle=360.0)

Parámetros

fullcircle – un número

Establece la unidad de medida del ángulo, por ejemplo establece el número de «grados» para un círculo completo. El valor por defecto es 36 grados.

>>> turtle.home()
>>> turtle.left(90)
>>> turtle.heading()
90.0

Change angle measurement unit to grad (also known as gon,
grade, or gradian and equals 1/100-th of the right angle.)
>>> turtle.degrees(400.0)
>>> turtle.heading()
100.0
>>> turtle.degrees(360)
>>> turtle.heading()
90.0

turtle.radians()

Establece la unidad de medida del ángulo a radianes. Equivalente a degrees(2*math.pi).

>>> turtle.home()
>>> turtle.left(90)
>>> turtle.heading()
90.0
>>> turtle.radians()
>>> turtle.heading()
1.5707963267948966

Control del lápiz

Estado de dibujo

turtle.pendown()

turtle.pd()

turtle.down()

Baja el lápiz – dibuja mientras se mueve.

turtle.penup()

turtle.pu()

turtle.up()

Levanta el lápiz – no dibuja mientras se mueve.

turtle.pensize(width=None)

turtle.width(width=None)

Parámetros

width – un número positivo

Establece el grosos de la línea a width o lo devuelve. Si resizemode se establece a «auto» y turtleshape es un polígono, ese polígono es dibujado con el mismo grosor de línea. Si no se dan argumentos, devuelve el grosor del lápiz actual.

>>> turtle.pensize()
1
>>> turtle.pensize(10)   # from here on lines of width 10 are drawn

turtle.pen(pen=None, **pendict)

Parámetros

pen – un diccionario con algunos o todos las claves listadas debajo

pendict – uno o más argumentos-palabras claves con las claves listadas debajo como palabras claves

Devuelve o establece los atributos del lápiz en un «diccionario-lápiz» con el siguiente para de valores/claves:

«shown»: True/False

«pendown»: True/False

«pencolor»: color-string or color-tuple

«fillcolor»: color-string or color-tuple

«pensize»: número positivo

«speed»: número en el rango 0..10

«resizemode»: «auto» or «user» or «noresize»

«stretchfactor»: (número positivo, número positivo)

«outline»: número positivo

«tilt»: número

Este diccionario puede usarse como argumento de una llamada subsecuente a la función pen() para restaurar el estado anterior del lápiz. Más aún, uno o más de estos atributos pueden darse como argumentos claves. Esto puede usarse para establecer diferentes atributos del lápiz en una sola definición.

>>> turtle.pen(fillcolor="black", pencolor="red", pensize=10)
>>> sorted(turtle.pen().items())
[('fillcolor', 'black'), ('outline', 1), ('pencolor', 'red'),
 ('pendown', True), ('pensize', 10), ('resizemode', 'noresize'),
 ('shearfactor', 0.0), ('shown', True), ('speed', 9),
 ('stretchfactor', (1.0, 1.0)), ('tilt', 0.0)]
>>> penstate=turtle.pen()
>>> turtle.color("yellow", "")
>>> turtle.penup()
>>> sorted(turtle.pen().items())[:3]
[('fillcolor', ''), ('outline', 1), ('pencolor', 'yellow')]
>>> turtle.pen(penstate, fillcolor="green")
>>> sorted(turtle.pen().items())[:3]
[('fillcolor', 'green'), ('outline', 1), ('pencolor', 'red')]

turtle.isdown()

Devuelve True``si el lápiz está abajo, si está arriba ``False.

>>> turtle.penup()
>>> turtle.isdown()
False
>>> turtle.pendown()
>>> turtle.isdown()
True

Control del color

turtle.pencolor(*args)

Devuelve o establece el color del lápiz.

Se permiten cuatro formatos de entrada:

pencolor()

Devuelve el color del lápiz actual como una palabra específica de algún color o como una tupla (ver ejemplo). Puede ser usado como una entrada para otra llamada de color/pencolor/fillcolor.

pencolor(colorstring)

Establece el color del lápiz a colorstring, que es una palabra que especifica un color Tk, tales como "red", "yellow", o "#33cc8c".

pencolor((r, g, b))

Establece el color del lápiz representado como una tupla de r, g, y b. Cada valor r, g, y b debe ser un valor entero en el rango 0..colormode, donde colormode es 1.0 o 255 (ver colormode()).

pencolor(r, g, b)

Establece el color del lápiz al color RGB representado por r, g, y b. Cada valor r, g, y b debe estar en el rango 0..colormode.

Si turtleshape es un polígono, la línea del polígono es dibujado con el muevo color de lápiz elegido.

 >>> colormode()
 1.0
 >>> turtle.pencolor()
 'red'
 >>> turtle.pencolor("brown")
 >>> turtle.pencolor()
 'brown'
 >>> tup = (0.2, 0.8, 0.55)
 >>> turtle.pencolor(tup)
 >>> turtle.pencolor()
 (0.2, 0.8, 0.5490196078431373)
 >>> colormode(255)
 >>> turtle.pencolor()
 (51.0, 204.0, 140.0)
 >>> turtle.pencolor('#32c18f')
 >>> turtle.pencolor()
 (50.0, 193.0, 143.0)

turtle.fillcolor(*args)

Return or set the fillcolor.

Se permiten cuatro formatos de entrada:

fillcolor()

Devuelve el valor actual de fillcolor como una palabra, posiblemente en formato de tupla (ver ejemplo). Puede ser usado como entrada de otra llamada color/pencolor/fillcolor.

fillcolor(colorstring)

Establece fillcolor a colorstring, que es un color TK especificado como una palabra (en inglés), tales como «red», «yellow», o «#33cc8c»`.

fillcolor((r, g, b))

Establece fillcolor al color RGB representado por la tupla r, g, y b. Cada uno de los valores r, g, y b debe estar en el rango 0..colormode, donde colormode es 1.0 o 255 (ver colormode()).

fillcolor(r, g, b)

Establece fillcolor al color RGB representado por r, g, y b. Cada uno de los valores r, g y b debe ser un valor en el rango 0..colormode.

Si turtleshape es un polígono, el interior de ese polígono es dibujado con el color establecido en fillcolor.

 >>> turtle.fillcolor("violet")
 >>> turtle.fillcolor()
 'violet'
 >>> turtle.pencolor()
 (50.0, 193.0, 143.0)
 >>> turtle.fillcolor((50, 193, 143))  # Integers, not floats
 >>> turtle.fillcolor()
 (50.0, 193.0, 143.0)
 >>> turtle.fillcolor('#ffffff')
 >>> turtle.fillcolor()
 (255.0, 255.0, 255.0)

turtle.color(*args)

Retorna o establece pencolor (el color del lápiz) y fillcolor (el color de relleno).

Se permiten varios formatos de entrada. Usan de 0 a 3 argumentos como se muestra a continuación:

color()

Devuelve el valor actual de pencolor y el valor actual de fillcolor como un par de colores especificados como palabras o tuplas, como devuelven las funciones pencolor() y fillcolor().

color(colorstring), color((r,g,b)), color(r,g,b)

Entradas como en pencolor(), establece al valor dado tanto, fillcolor como pencolor.

color(colorstring1, colorstring2), color((r1,g1,b1), (r2,g2,b2))

Equivalente a pencolor(colorstring1) y fillcolor(colorstring2) y análogamente si se usa el otro formato de entrada.

Si turtleshape es un polígono, la línea y el interior de ese polígono e dibujado con los nuevos colores que se establecieron.

 >>> turtle.color("red", "green")
 >>> turtle.color()
 ('red', 'green')
 >>> color("#285078", "#a0c8f0")
 >>> color()
 ((40.0, 80.0, 120.0), (160.0, 200.0, 240.0))

Ver también: Método Screeen colormode().

Relleno

turtle.filling()

Devuelve fillstate (True si está lleno, sino False).

 >>> turtle.begin_fill()
 >>> if turtle.filling():
 ...    turtle.pensize(5)
 ... else:
 ...    turtle.pensize(3)

turtle.begin_fill()

Para ser llamada justo antes de dibujar una forma a rellenar.

turtle.end_fill()

Rellena la forma dibujada después de última llamada a la función begin_fill().

Superponer o no, regiones de polígonos auto-intersectados o múltiples formas, estas son rellenadas dependiendo de los gráficos del sistema operativo, tipo de superposición y número de superposiciones. Por ejemplo, la flecha de la tortuga de arriba, puede ser toda amarilla o tener algunas regiones blancas.

>>> turtle.color("black", "red")
>>> turtle.begin_fill()
>>> turtle.circle(80)
>>> turtle.end_fill()

Más controles de dibujo

turtle.reset()

Borra el dibujo de la tortuga de la pantalla, centra la tortuga y establece las variables a los valores por defecto.

>>> turtle.goto(0,-22)
>>> turtle.left(100)
>>> turtle.position()
(0.00,-22.00)
>>> turtle.heading()
100.0
>>> turtle.reset()
>>> turtle.position()
(0.00,0.00)
>>> turtle.heading()
0.0

turtle.clear()

Borra el dibujo de la tortuga de la pantalla. No mueve la tortuga. El estado y posición de la tortuga así como los todos los dibujos de las otras tortugas no son afectados.

turtle.write(arg, move=False, align="left", font=("Arial", 8, "normal"))

Parámetros

arg – objeto que se escribirá en TurtleScreen

move – True/False

align – una de las frases «left», «center» o «right»

font – un trio (nombre de fuente, tamaño de fuente, tipo de fuente)

Escribe texto - la representación de cadena de caracteres de arg - en la posición actual de la tortuga de acuerdo con align («izquierda», «centro» o «derecha») y con la fuente dada. Si mov es verdadero, el lápiz se mueve a la esquina inferior derecha del texto. De forma predeterminada, move es False.

>>> turtle.write("Home = ", True, align="center")
>>> turtle.write((0,0), True)

Estado de la Tortuga

Visibilidad

turtle.hideturtle()

turtle.ht()

Hace invisible a la tortuga, Es una buena idea hacer eso mientras está haciendo dibujos complejos, ya que esconder a la tortuga acelera dibujo de manera observable.

>>> turtle.hideturtle()

turtle.showturtle()

turtle.st()

Hace visible la tortuga.

>>> turtle.showturtle()

turtle.isvisible()

Devuelve True si la tortuga se muestra, False si está oculta.

>>> turtle.hideturtle()
>>> turtle.isvisible()
False
>>> turtle.showturtle()
>>> turtle.isvisible()
True

Apariencia

turtle.shape(name=None)

Parámetros

name – una cadena de caracteres que es un nombre de forma válido

Establece la forma de la tortuga al name que se establece o, si no se establece un nombre, devuelve el nombre actual de su forma. La forma name debe existir en el diccionario de formas de TurtleScreen. Inicialmente están las siguientes formas poligonales: «arrow», «turtle», «circle», «square», «triangle», «classic». Para aprender como trabajar con estas formas ver los métodos de Screen register_shape().

>>> turtle.shape()
'classic'
>>> turtle.shape("turtle")
>>> turtle.shape()
'turtle'

turtle.resizemode(rmode=None)

Parámetros

rmode – una de las cadenas «auto», «user», «noresize»

Establece resizemode a alguno de los valores: «auto», «user», «noresize». Si mode no se aporta, devuelve el actual resizemode. Distintos resizemode tienen los siguientes efectos:

«auto»: adapta la apariencia de la tortuga al correspondiente valor del lápiz.

«user»: adapta la apariencia de la tortuga de acuerdo a los valores de sretchfactor y outlinewidth (contorno), que se establece con la función shapesize().

«noresize»: no se adapta la apariencia de la tortuga.

resizemode("user") es llamado por la función shapesize() cuando se usa con argumentos.

>>> turtle.resizemode()
'noresize'
>>> turtle.resizemode("auto")
>>> turtle.resizemode()
'auto'

turtle.shapesize(stretch_wid=None, stretch_len=None, outline=None)

turtle.turtlesize(stretch_wid=None, stretch_len=None, outline=None)

Parámetros

stretch_wid – número positivo

stretch_len – número positivo

outline – número positivo

Devuelve o establece los atributos del lápiz los factores x/y de estiramiento y contorno. Establece resizemode a «user» si y solo si resizemode está definido como «user», la tortuga será verá estirada acorde a sus factores de estiramiento: stretch_wid es el factor de estiramiento perpendicular a su orientación, stretch_len es su factor de estiramiento en dirección a su orientación, outline determina el grosor de contorno de la forma.

>>> turtle.shapesize()
(1.0, 1.0, 1)
>>> turtle.resizemode("user")
>>> turtle.shapesize(5, 5, 12)
>>> turtle.shapesize()
(5, 5, 12)
>>> turtle.shapesize(outline=8)
>>> turtle.shapesize()
(5, 5, 8)

turtle.shearfactor(shear=None)

Parámetros

shear – número (opcional)

Establece o devuelve el valor actual del estiramiento. Estira la forma de la tortuga de acuerdo a la inclinación del factor de corte, que es la tangente del ángulo de corte. No cambia el rumbo de la tortuga (dirección del movimiento). Si no de da un valor de inclinación: devuelve el factor actual, por ejemplo la tangente del ángulo de inclinación, por el cual se cortan la líneas paralelas al rumbo de la tortuga.

 >>> turtle.shape("circle")
 >>> turtle.shapesize(5,2)
 >>> turtle.shearfactor(0.5)
 >>> turtle.shearfactor()
 0.5

turtle.tilt(angle)

Parámetros

angle – un número

Rota la forma de la tortuga en ángulo desde su ángulo de inclinación actual, pero no cambia el rumbo de la tortuga (dirección del movimiento).

>>> turtle.reset()
>>> turtle.shape("circle")
>>> turtle.shapesize(5,2)
>>> turtle.tilt(30)
>>> turtle.fd(50)
>>> turtle.tilt(30)
>>> turtle.fd(50)

turtle.settiltangle(angle)

Parámetros

angle – un número

Rota la forma de la tortuga apuntando en la dirección especificada por el ángulo, independientemente de su ángulo de dirección actual. No cambia el rumbo de la tortuga (dirección de movimiento).

>>> turtle.reset()
>>> turtle.shape("circle")
>>> turtle.shapesize(5,2)
>>> turtle.settiltangle(45)
>>> turtle.fd(50)
>>> turtle.settiltangle(-45)
>>> turtle.fd(50)

Obsoleto desde la versión 3.1.

turtle.tiltangle(angle=None)

Parámetros

angle – un número (opcional)

Establece o devuelve el ángulo de inclinación actual. Si se otorga un ángulo, rota la forma de la tortuga para apuntar en la dirección del ángulo especificado, independientemente de su actual ángulo de inclinación. No cambia el rumbo de la tortuga (dirección del movimiento). Si no se da el ángulo: devuelve el ángulo de inclinación actual, por ejemplo: el ángulo entre la orientación de la forma de la tortuga y el rumbo de la tortuga (su dirección de movimiento).

>>> turtle.reset()
>>> turtle.shape("circle")
>>> turtle.shapesize(5,2)
>>> turtle.tilt(45)
>>> turtle.tiltangle()
45.0

turtle.shapetransform(t11=None, t12=None, t21=None, t22=None)

Parámetros

t11 – un número (opcional)

t12 – un número (opcional)

t21 – un número (opcional)

t12 – un número (opcional)

Establece o devuelve la matriz de transformación actual de la forma de la tortuga.

Si no se proporciona ninguno de los elementos de la matriz, retorna la matriz de transformación como una tupla de 4 elementos. De lo contrario, establezca los elementos dados y transforme la forma de tortuga de acuerdo con la matriz que consta de la primera fila t11, t12 y la segunda fila t21, t22. El determinante t11 * t22 - t12 * t21 no debe ser cero, de lo contrario se genera un error. Modifique el factor de estiramiento, el factor de corte y el ángulo de inclinación de acuerdo con la matriz dada.

>>> turtle = Turtle()
>>> turtle.shape("square")
>>> turtle.shapesize(4,2)
>>> turtle.shearfactor(-0.5)
>>> turtle.shapetransform()
(4.0, -1.0, -0.0, 2.0)

turtle.get_shapepoly()

Devuelve el polígono de la forma actual como tupla de pares de coordenadas. Esto puede ser usado para definir una nueva forma o componentes de una forma compuesta.

>>> turtle.shape("square")
>>> turtle.shapetransform(4, -1, 0, 2)
>>> turtle.get_shapepoly()
((50, -20), (30, 20), (-50, 20), (-30, -20))

Usando eventos

turtle.onclick(fun, btn=1, add=None)

Parámetros

fun – una función con dos argumentos que se invocará con las coordenadas del punto en el que se hizo clic en el lienzo

btn – número del botón del mouse, el valor predeterminado es 1 (botón izquierdo del mouse)

add – True o False – si es True, se agrega un nuevo enlace, de lo contrario reemplazará el enlace anterior

Enlaza acciones divertidas a eventos de click en la tortuga. Si la accion es None, las acciones asociadas son borradas. Ejemplo para la tortuga anónima, en la forma procedimental:

>>> def turn(x, y):
...     left(180)
...
>>> onclick(turn)  # Now clicking into the turtle will turn it.
>>> onclick(None)  # event-binding will be removed

turtle.onrelease(fun, btn=1, add=None)

Parámetros

fun – una función con dos argumentos que se invocará con las coordenadas del punto en el que se hizo clic en el lienzo

btn – número del botón del mouse, el valor predeterminado es 1 (botón izquierdo del mouse)

add – True o False – si es True, se agrega un nuevo enlace, de lo contrario reemplazará el enlace anterior

Enlaza acciones divertidas a eventos del tipo soltar botón del mouse en la tortuga. SI la acción es None, las acciones asociadas son borradas.

>>> class MyTurtle(Turtle):
...     def glow(self,x,y):
...         self.fillcolor("red")
...     def unglow(self,x,y):
...         self.fillcolor("")
...
>>> turtle = MyTurtle()
>>> turtle.onclick(turtle.glow)     # clicking on turtle turns fillcolor red,
>>> turtle.onrelease(turtle.unglow) # releasing turns it to transparent.

turtle.ondrag(fun, btn=1, add=None)

Parámetros

fun – una función con dos argumentos que se invocará con las coordenadas del punto en el que se hizo clic en el lienzo

btn – número del botón del mouse, el valor predeterminado es 1 (botón izquierdo del mouse)

add – True o False – si es True, se agrega un nuevo enlace, de lo contrario reemplazará el enlace anterior

Enlaza acciones divertidas a eventos en los movimientos del mouse. Si la acción es None, las acciones asociadas son borradas.

Observación: cada secuencia de los eventos de movimiento del mouse en una tortuga es precedida por un evento de click del mouse en esa tortuga.

>>> turtle.ondrag(turtle.goto)

Subsecuentemente, clickear y arrastrar la Tortuga la moverá a través de la pantalla produciendo dibujos a mano alzada (si el lápiz está abajo).

Métodos especiales de Turtle

turtle.begin_poly()

Comienza a grabar los vértices de un polígono. La posición actual de la tortuga es el primer vértice del polígono.

turtle.end_poly()

Deja de grabar los vértices de un polígono. La posición actual de la tortuga es el último vértice del polígono. Esto se conectará con el primer vértice.

turtle.get_poly()

Devuelve el último polígono grabado.

>>> turtle.home()
>>> turtle.begin_poly()
>>> turtle.fd(100)
>>> turtle.left(20)
>>> turtle.fd(30)
>>> turtle.left(60)
>>> turtle.fd(50)
>>> turtle.end_poly()
>>> p = turtle.get_poly()
>>> register_shape("myFavouriteShape", p)

turtle.clone()

Crea y devuelve un clon de la tortuga con la misma posición, dirección y propiedades de la tortuga.

>>> mick = Turtle()
>>> joe = mick.clone()

turtle.getturtle()

turtle.getpen()

Devuelve el objeto Tortuga en si. El único uso razonable: es como una función para devolver la «tortuga anónima»:

>>> pet = getturtle()
>>> pet.fd(50)
>>> pet
<turtle.Turtle object at 0x...>

turtle.getscreen()

Devuelve el objeto TurtleScreen sobre el cual la tortuga está dibujando. Los métodos TurtleScreen luego pueden ser llamados para ese objeto.

>>> ts = turtle.getscreen()
>>> ts
<turtle._Screen object at 0x...>
>>> ts.bgcolor("pink")

turtle.setundobuffer(size)

Parámetros

size – un entero o None

Establecer o deshabilitar deshacer búfer. Si size es un número entero, se instala un búfer de deshacer vacío de un tamaño determinado. size da el número máximo de acciones de tortuga que se pueden deshacer mediante el método/función undo(). Si size es None, el búfer para deshacer está deshabilitado.

>>> turtle.setundobuffer(42)

turtle.undobufferentries()

Devuelve el número de entradas en el buffer para deshacer acciones.

>>> while undobufferentries():
...     undo()

Formas compuestas

Para usar formas complejas con la tortuga, que consiste en varios polígonos de diferentes colores, deberá usar la clase de ayuda Shape explícitamente como se describe debajo:

Crear una objeto de forma vacía del tipo compound.

Agregar todos los componentes deseados a este objeto, usando el método addcomponent().

Por ejemplo:

>>> s = Shape("compound")
>>> poly1 = ((0,0),(10,-5),(0,10),(-10,-5))
>>> s.addcomponent(poly1, "red", "blue")
>>> poly2 = ((0,0),(10,-5),(-10,-5))
>>> s.addcomponent(poly2, "blue", "red")

Ahora agregar la forma a la lista de formas de la pantalla y úsela:

>>> register_shape("myshape", s)
>>> shape("myshape")

Nota

La clase Shape es usada internamente por el método register_shape() en maneras diferentes. El programador deberá lidiar con la clase Shape ¡solo cuando use formas compuestas como las que se mostraron arriba!

Métodos de TurtleScreen/Screen y sus correspondientes funciones

La mayoría de los ejemplos en esta sección se refieren a la instancia de TurtleScreen llamada screen.

Control de ventana

turtle.bgcolor(*args)

Parámetros

args – una cadena de color o tres números en el rango 0..*colormode* o una tupla de 3 de esos números

Establece o devuelve el color de fondo de TurtleScreen.

>>> screen.bgcolor("orange")
>>> screen.bgcolor()
'orange'
>>> screen.bgcolor("#800080")
>>> screen.bgcolor()
(128.0, 0.0, 128.0)

turtle.bgpic(picname=None)

Parámetros

picname – una cadena, nombre o archivo gif o "nopic", o None

Establece la imagen de fondo o devuelve el nombre de la imagen de fondo actual. Si picname es un nombre de archivo, establece la imagen correspondiente como fondo. Si picname es "nopic", borra la imagen de fondo, si hay alguna presente. Si picname es None, devuelve el nombre de archivo de la imagen de fondo actual.

>>> screen.bgpic()
'nopic'
>>> screen.bgpic("landscape.gif")
>>> screen.bgpic()
"landscape.gif"

turtle.clear()

Nota

Este método de TurtleScreen está disponible como una función global solo bajo el nombre clearscreen`. La función global clear es otra, derivada del método de Turtle clear.

turtle.clearscreen()

Borra todos los dibujos y todas las tortugas del la pantalla de la tortuga. Reinicia la ahora vacía pantalla de la tortuga a su estado inicial: fondo blanco, sin imagen de fondo, sin enlaces a eventos o seguimientos.

turtle.reset()

Nota

Este método TurtleScreen esta disponible como una función global solo bajo el nombre resetscreen. La función global reset es otra, derivada del método Turtle reset.

turtle.resetscreen()

Reinicia todas las tortugas de la pantalla a su estado inicial.

turtle.screensize(canvwidth=None, canvheight=None, bg=None)

Parámetros

canvwidth – entero positivo, nueva anchura del lienzo en pixeles

canvheight – entero positivo, nueva altura del lienzo en pixeles

bg – colorstrng o tupla de color, muevo color de fondo

Si no se dan argumentos, devuelve el actual (ancho y alto del lienzo). Sino redimensiona el lienzo en el que la tortuga está dibujando. No altera la ventana de dibujo. Para ver las partes ocultas del lienzo, use la barra de desplazamiento. Con este método, se pueden hacer visibles aquellas partes de un dibujo que antes estaban fuera del lienzo.

>>> screen.screensize()
(400, 300)
>>> screen.screensize(2000,1500)
>>> screen.screensize()
(2000, 1500)

ej. buscar una tortuga que se escapó por error ;-)

turtle.setworldcoordinates(llx, lly, urx, ury)

Parámetros

llx – un número, coordenada x de la esquina inferior izquierda del lienzo

lly – un número, coordenada y de la esquina inferior izquierda del lienzo

urx – un número, coordenada x de la esquina superior derecha del lienzo

ury – un número, coordenada z de la esquina superior derecha del lienzo

Configura coordenadas definidas por el usuario y cambia al modo world si es necesario. Esto realiza un screen.reset(). Si el modo world ya está activo, todos los dibujos se re dibujan de acuerdo a las nuevas coordenadas.

ATENCIÓN: en los sistemas de coordenadas definidos por el usuario, los ángulos pueden aparecer distorsionados.

>>> screen.reset()
>>> screen.setworldcoordinates(-50,-7.5,50,7.5)
>>> for _ in range(72):
...     left(10)
...
>>> for _ in range(8):
...     left(45); fd(2)   # a regular octagon

Control de animación

turtle.delay(delay=None)

Parámetros

delay – entero positivo

Establece o retorna el retraso del dibujo en mili segundos. ( Este es aproximadamente, el tiempo de intervalo entre dos actualizaciones consecutivas del lienzo). Mientras más largo sea el retraso, más lenta la animación.

Argumento opcional:

>>> screen.delay()
10
>>> screen.delay(5)
>>> screen.delay()
5

turtle.tracer(n=None, delay=None)

Parámetros

n – entero no negativo

delay – entero no negativo

Activa o desactiva la animación de la tortuga y establece el retraso para la actualización de los dibujos. Si se da n, solo cada enésima actualización regular de pantalla se realiza realmente. (Puede usarse para acelerar los dibujos de gráficos complejos). Cuando es llamada sin argumentos, devuelve el valor de n guardado actualmente. El segundo argumento establece el valor de retraso (ver delay()).

>>> screen.tracer(8, 25)
>>> dist = 2
>>> for i in range(200):
...     fd(dist)
...     rt(90)
...     dist += 2

turtle.update()

Realiza una actualización de la pantalla de la tortuga. Para ser usada cuando tracer está deshabilitada.

Ver también el método RawTurtle/Turtle speed().

Usando eventos de pantalla

turtle.listen(xdummy=None, ydummy=None)

Establece el foco en la pantalla de la tortuga (para recoger eventos de teclado). Los argumentos dummy se proveen en orden de ser capaces de pasar listen() a los métodos onclick.

turtle.onkey(fun, key)

turtle.onkeyrelease(fun, key)

Parámetros

fun – una función sin argumentos o None

key – una cadena de caracteres: tecla (por ejemplo, «a») o una acción del teclado (por ejemplo, «space»)

Vincula fun a un evento de liberación de una tecla. Si fun es None, los eventos vinculados son removidos. Aclaración: para poder registrar eventos de teclado, TurtleScreen tiene que tener el foco. (ver el método listen().)

>>> def f():
...     fd(50)
...     lt(60)
...
>>> screen.onkey(f, "Up")
>>> screen.listen()

turtle.onkeypress(fun, key=None)

Parámetros

fun – una función sin argumentos o None

key – una cadena de caracteres: tecla (por ejemplo, «a») o una acción del teclado (por ejemplo, «space»)

Vincula fun a un evento de pulsado de una tecla, o a cualquier evento de pulsado de tecla si no se da una. Aclaración: para poder registrar eventos de teclado, TurtleScreen tiene que tener el foco. (ver el método listen().)

>>> def f():
...     fd(50)
...
>>> screen.onkey(f, "Up")
>>> screen.listen()

turtle.onclick(fun, btn=1, add=None)

turtle.onscreenclick(fun, btn=1, add=None)

Parámetros

fun – una función con dos argumentos que se invocará con las coordenadas del punto en el que se hizo clic en el lienzo

btn – número del botón del mouse, el valor predeterminado es 1 (botón izquierdo del mouse)

add – True o False – si es True, se agrega un nuevo enlace, de lo contrario reemplazará el enlace anterior

Vincula fun a eventos de click del mouse en esta pantalla. Si fun es None, los vínculos existentes son removidos.

Ejemplo de una instancia TurtleScreen llamada screen y una instancia Turtle llamada turtle:

>>> screen.onclick(turtle.goto) # Subsequently clicking into the TurtleScreen will
>>>                             # make the turtle move to the clicked point.
>>> screen.onclick(None)        # remove event binding again

Nota

Este método TurtleScreen está disponible como una función global solo bajo el nombre onscreenclick`. La función global onclick es otra derivada del método Turtle onclick.

turtle.ontimer(fun, t=0)

Parámetros

fun – una función sin argumentos

t – un número >= 0

Instala un temporizador que llama a fun cada t milisegundos.

>>> running = True
>>> def f():
...     if running:
...         fd(50)
...         lt(60)
...         screen.ontimer(f, 250)
>>> f()   ### makes the turtle march around
>>> running = False

turtle.mainloop()

turtle.done()

Comienza un bucle de evento - llamando a la función mainloop del Tkinter. Debe ser la última declaración en un programa gráfico de turtle. No debe ser usado si algún script es corrido dentro del IDLE en modo -n (Sin subproceso) - para uso interactivo de gráficos turtle.:

>>> screen.mainloop()

Métodos de entrada

turtle.textinput(title, prompt)

Parámetros

title – cadena de caracteres

prompt – cadena de caracteres

Abre una ventana de diálogo para ingresar una cadena de caracteres. El parámetro title es el título de la ventana de diálogo, prompt es un texto que usualmente describe que información se debe ingresar. Devuelve la cadena ingresada. Si el diálogo es cancelado, devuelve None`.

>>> screen.textinput("NIM", "Name of first player:")

turtle.numinput(title, prompt, default=None, minval=None, maxval=None)

Parámetros

title – cadena de caracteres

prompt – cadena de caracteres

default – número (opcional)

minval – número (opcional)

maxval – número (opcional)

Abre una ventana de diálogo para el ingreso de un número. title es el título de la ventana de diálogo, prompt es un texto que usualmente describe qué información numérica ingresar. default: valor por defecto, minval: mínimo valor aceptado, maxval: máximo valor aceptado. Si se aportan estos parámetros, el número a ingresar debe estar en el rango minval..*maxval*. Si no, se da una pista y el diálogo permanece abierto para su corrección. Devuelve el número ingresado. Si el diálogo es cancelado, devuelve None.:

>>> screen.numinput("Poker", "Your stakes:", 1000, minval=10, maxval=10000)

Configuración y métodos especiales

turtle.mode(mode=None)

Parámetros

mode – una de las cadenas «standard», «logo» o «world»

Establece el mode de la tortuga («standard», «logo» o «world») y realiza un reinicio. Si no se da «mode», retorna el modo actual.

El modo «standard» es compatible con el antiguo turtle. El modo «logo» es compatible con la mayoría de los gráficos de tortuga Logo. El modo «world» usa coordenadas de mundo definidas por el usuario. Atención: en este modo los ángulos aparecen distorsionados si la relación de unidad x/y no es igual a 1.

Modo

Rumbo inicial de la tortuga

ángulos positivos

«standard»

hacia la derecha (este)

sentido antihorario

«logo»

hacia arriba (norte)

sentido horario

>>> mode("logo")   # resets turtle heading to north
>>> mode()
'logo'

turtle.colormode(cmode=None)

Parámetros

cmode – uno de los valores 1.0 o 255

Devuelve el colormode o lo establece a 1.0 o 255. Subsecuentemente, los valores triples de color r, g, b tienen que estar en el rango 0..cmode.

>>> screen.colormode(1)
>>> turtle.pencolor(240, 160, 80)
Traceback (most recent call last):
     ...
TurtleGraphicsError: bad color sequence: (240, 160, 80)
>>> screen.colormode()
1.0
>>> screen.colormode(255)
>>> screen.colormode()
255
>>> turtle.pencolor(240,160,80)

turtle.getcanvas()

Devuelve el lienzo de este TurtleScreen. Útil para conocedores que saben que hace con un TKinter Canvas.

>>> cv = screen.getcanvas()
>>> cv
<turtle.ScrolledCanvas object ...>

turtle.getshapes()

Devuelve la lista de nombres de todas las formas de la tortuga actualmente disponibles.

>>> screen.getshapes()
['arrow', 'blank', 'circle', ..., 'turtle']

turtle.register_shape(name, shape=None)

turtle.addshape(name, shape=None)

Hay tres formas distintas de llamar a esta función:

name es el nombre de un archivo gif y shape es None: instala la imagen correspondiente.

>>> screen.register_shape("turtle.gif")

Nota

Las imágenes de tipo shapes no rotan cuando la tortuga gira, así que ellas ¡no muestran el rumbo de la tortuga!

name es una cadena de caracteres arbitraria y shape es una tupla de pares de coordenadas: Instala la forma poligonal correspondiente.

>>> screen.register_shape("triangle", ((5,-3), (0,5), (-5,-3)))

name es una cadena de caracteres arbitraria y shape es un objeto Shape (compuesto): Instala la correspondiente forma compuesta.

Agregar una forma de tortuga a la lista de formas de TurtleScreen. Solo las formas registradas de esta manera pueden ser usadas invocando el comando shape(shapename).

turtle.turtles()

Devuelve la lista de tortugas en la pantalla.

>>> for turtle in screen.turtles():
...     turtle.color("red")

turtle.window_height()

Devuelve la altura de la ventana de la tortuga.

>>> screen.window_height()
480

turtle.window_width()

Devuelve el ancho de la ventana de la tortuga.

>>> screen.window_width()
640

Métodos específicos de Screen, no heredados de TurtleScreen

turtle.bye()

Apaga la ventana gráfica de la tortuga.

turtle.exitonclick()

Ata el método bye() al click del ratón sobre la pantalla.

Si el valor «using_IDLE» en la configuración del diccionario es False (valor por defecto), también ingresa mainloop. Observaciones: si se usa la IDLE con el modificador (no subproceso) -n, este valor debe establecerse a True en turtle.cfg. En este caso el propio mainloop de la IDLE está activa también para script cliente.

turtle.setup(width=_CFG["width"], height=_CFG["height"], startx=_CFG["leftright"], starty=_CFG["topbottom"])

Establece el tamaño y la posición de la ventana principal. Los valores por defecto de los argumentos son guardados en el diccionario de configuración y puede ser cambiado a través del archivo turtle.cfg.

Parámetros

width – si es un entero, el tamaño en pixeles, si es un número flotante, una fracción de la pantalla; el valor por defecto es 50% de la pantalla

height – si es un entero, la altura en pixeles, si es un número flotante, una fracción de la pantalla; el valor por defecto es 75% de la pantalla

startx – si es positivo, punto de inicio en pixeles desde la esquina izquierda de la pantalla, si es negativo desde la esquina derecha de la pantalla, si es None, centra la ventana horizontalmente

starty – si es positivo, punto de inicio en pixeles desde la parte superior de la pantalla, si es negativo desde la parte inferior de la pantalla, si es None, centra la ventana verticalmente

>>> screen.setup (width=200, height=200, startx=0, starty=0)
>>>              # sets window to 200x200 pixels, in upper left of screen
>>> screen.setup(width=.75, height=0.5, startx=None, starty=None)
>>>              # sets window to 75% of screen by 50% of screen and centers

turtle.title(titlestring)

Parámetros

titlestring – una cadena de caracteres que se muestra en la barra de título de la ventana gráfica de la tortuga

Establece el título de la ventana de la tortuga a titlestring.

>>> screen.title("Welcome to the turtle zoo!")

Clases públicas

class turtle.RawTurtle(canvas)

class turtle.RawPen(canvas)

Parámetros

canvas – una clase tkinter.Canvas, una ScrolledCanvas o una clase TurtleScreen

Crea una tortuga. La tortuga tiene todos los métodos descriptos anteriormente como «métodos de «Turtle/RawTurtle».

class turtle.Turtle

Subclase de RawTurtle, tiene la misma interface pero dibuja sobre una objeto por defecto Screen creado automáticamente cuando es necesario por primera vez.

class turtle.TurtleScreen(cv)

Parámetros

cv – un tkinter.Canvas

Provee métodos orientados a la pantalla como setbg() etc. descriptos anteriormente.

class turtle.Screen

Subclase de TurtleScreen, con cuatro métodos agregados.

class turtle.ScrolledCanvas(master)

Parámetros

master – algunos widgets TKinter para contener el ScrollCanvas, por ejemplo un lienzo Tkinter con barras de desplazamiento agregadas

Usado por la clase Screen, que proporciona automáticamente un ScrolledCanvas como espacio de trabajo para las tortugas.

class turtle.Shape(type_, data)

Parámetros

type_ – una de las cadenas de caracteres «polygon», «image», «compound»

Estructura de datos que modela las formas. El par (type_, data)` debe seguir estas especificaciones:

type_

data

«polygon»

una tupla para el polígono, por ejemplo: una tupla de par de coordenadas

«image»

una imagen (en esta forma solo se usa ¡internamente!)

«compound»

None (una forma compuesta tiene que ser construida usando el método addcomponent())

addcomponent(poly, fill, outline=None)

Parámetros

poly – un polígono, por ejemplo una tupla de pares de números

fill – un color con el que el polígono será llenado

outline – un color con el que se delineará el polígono (se de ingresa)

Ejemplo:

>>> poly = ((0,0),(10,-5),(0,10),(-10,-5))
>>> s = Shape("compound")
>>> s.addcomponent(poly, "red", "blue")
>>> # ... add more components and then use register_shape()

Ver Formas compuestas.

class turtle.Vec2D(x, y)

Una clase de vectores bidimensionales, usado como clase de ayuda para implementar gráficos de tortuga. Puede ser útil para los programas de gráficos de tortugas también. Derivado de la tupla, ¡por lo que un vector es una tupla!

Proporciona (para a, b vectores, k números)

a + b suma de vectores

a - b resta de vectores

a * b producto interno

k * a y a * k multiplicación con escalar

abs(a) valor absoluto de a

a.rotate(angle) rotación

Ayuda y configuración

Cómo usar la ayuda

Los métodos públicos de las clases Screen y Turtle están ampliamente documentados a través de cadenas de documentación. Por lo tanto, estos se pueden usar como ayuda en línea a través de las instalaciones de ayuda de Python:

Cuando se usa IDLE, la información sobre herramientas muestra las firmas y las primeras líneas de las cadenas de documentos de las llamadas de función/método escritas.

Llamar a help() en métodos o funciones muestra los docstrings:

>>> help(Screen.bgcolor)
Help on method bgcolor in module turtle:

bgcolor(self, *args) unbound turtle.Screen method
    Set or return backgroundcolor of the TurtleScreen.

    Arguments (if given): a color string or three numbers
    in the range 0..colormode or a 3-tuple of such numbers.

      >>> screen.bgcolor("orange")
      >>> screen.bgcolor()
      "orange"
      >>> screen.bgcolor(0.5,0,0.5)
      >>> screen.bgcolor()
      "#800080"

>>> help(Turtle.penup)
Help on method penup in module turtle:

penup(self) unbound turtle.Turtle method
    Pull the pen up -- no drawing when moving.

    Aliases: penup | pu | up

    No argument

    >>> turtle.penup()

Los docstrings de las funciones que se derivan de los métodos tienen una forma modificada:

>>> help(bgcolor)
Help on function bgcolor in module turtle:

bgcolor(*args)
    Set or return backgroundcolor of the TurtleScreen.

    Arguments (if given): a color string or three numbers
    in the range 0..colormode or a 3-tuple of such numbers.

    Example::

      >>> bgcolor("orange")
      >>> bgcolor()
      "orange"
      >>> bgcolor(0.5,0,0.5)
      >>> bgcolor()
      "#800080"

>>> help(penup)
Help on function penup in module turtle:

penup()
    Pull the pen up -- no drawing when moving.

    Aliases: penup | pu | up

    No argument

    Example:
    >>> penup()

Estos docstrings modificados se crean automáticamente junto con las definiciones de función que se derivan de los métodos en el momento de la importación.

Traducción de cadenas de documentos a diferentes idiomas

Existe una utilidad para crear un diccionario cuyas claves son los nombres de los métodos y cuyos valores son los docstrings de los métodos públicos de las clases Screen y Turtle.

turtle.write_docstringdict(filename="turtle_docstringdict")

Parámetros

filename – una cadena de caracteres, utilizada como nombre de archivo

Crea y escribe un diccionario-docstring en un script de Python con el nombre de archivo dado. Esta función tiene que ser llamada explícitamente (no es utilizada por las clases de gráficos de tortugas). El diccionario de docstrings se escribirá en el script de Python filename.py. Está destinado a servir como plantilla para la traducción de las cadenas de documentos a diferentes idiomas.

Si usted (o sus estudiantes) desea utilizar turtle con ayuda en línea en su idioma nativo, debe traducir los docstrings y guardar el archivo resultante como, por ejemplo, turtle_docstringdict_german.py.

Si tiene una entrada adecuada en su archivo turtle.cfg, este diccionario se leerá en el momento de la importación y reemplazará los docstrings originales en inglés.

En el momento de escribir este artículo, existen diccionarios de docstrings en alemán e italiano. (Solicitudes por favor a glingl@aon.at.)

Cómo configurar Screen and Turtles

La configuración predeterminada incorporada imita la apariencia y el comportamiento del antiguo módulo de tortuga para mantener la mejor compatibilidad posible con él.

Si desea utilizar una configuración diferente que refleje mejor las características de este módulo o que se adapte mejor a sus necesidades, por ejemplo, para su uso en un aula, puede preparar un archivo de configuración turtle.cfg que se leerá en el momento de la importación y modificará la configuración de acuerdo con su configuración.

La configuración incorporada correspondería al siguiente turtle.cfg:

width = 0.5
height = 0.75
leftright = None
topbottom = None
canvwidth = 400
canvheight = 300
mode = standard
colormode = 1.0
delay = 10
undobuffersize = 1000
shape = classic
pencolor = black
fillcolor = black
resizemode = noresize
visible = True
language = english
exampleturtle = turtle
examplescreen = screen
title = Python Turtle Graphics
using_IDLE = False

Breve explicación de las entradas seleccionadas:

Las primeras cuatro líneas corresponden a los argumentos del método Screen.setup().

Las líneas 5 y 6 corresponden a los argumentos del método Screen.screensize().

shape puede ser cualquiera de las formas integradas, por ejemplo: arrow, turtle, etc. Para obtener más información, pruebe con help(shape).

Si no desea usar color de relleno (es decir, hacer que la tortuga sea transparente), debe escribir fillcolor = "" (pero todas las cadenas no vacías no deben tener comillas en el archivo cfg).

Si desea reflejar el estado de la tortuga, debe usar resizemode = auto.

Si establece, por ejemplo, language = italian el docstringdict turtle_docstringdict_italian.py se cargará en el momento de la importación (si está presente en la ruta de importación, por ejemplo, en el mismo directorio que turtle.

Las entradas exampleturtle y examplescreen definen los nombres de estos objetos a medida que aparecen en las cadenas de documentos. La transformación de método-docstrings en función-docstrings eliminará estos nombres de las docstrings.

using_IDLE: establezca esto en True si trabaja regularmente con IDLE y su interruptor -n («sin subproceso»). Esto evitará que exitonclick() ingrese al bucle principal.

Puede haber un archivo turtle.cfg en el directorio donde se almacena turtle y uno adicional en el directorio de trabajo actual. Este último anulará la configuración del primero.

El directorio Lib/turtledemo contiene un archivo turtle.cfg. Puede estudiarlo como un ejemplo y ver sus efectos al ejecutar las demostraciones (preferiblemente no desde el visor de demostraciones).

turtledemo — Scripts de demostración

El paquete turtledemo incluye un conjunto de scripts de demostración. Estos scripts se pueden ejecutar y visualizar utilizando el visor de demostración suministrado de la siguiente manera:

python -m turtledemo

Alternativamente, puede ejecutar los scripts de demostración individualmente. Por ejemplo,

python -m turtledemo.bytedesign

El directorio del paquete turtledemo contiene:

Un visor de demostración __main__.py que se puede utilizar para ver el código fuente de los scripts y ejecutarlos al mismo tiempo.

Múltiples scripts que demuestran diferentes características del módulo turtle. Se puede acceder a los ejemplos a través del menú de ejemplos. También se pueden ejecutar de forma independiente.

Un archivo turtle.cfg que sirve como ejemplo de cómo escribir y usar dichos archivos.

Los scripts de demostración son:

Nombre

Descripción

Características

bytedesign

patrón de gráficos de tortuga clásica compleja

tracer(), retrasar (delay), update()

caos

gráficos dinámicos de Verhulst, muestra que los cálculos de la computadora pueden generar resultados a veces contra las expectativas del sentido común

coordenadas mundiales

reloj

reloj analógico que muestra la hora de su computadora

tortugas como manecillas de reloj, temporizador

colormixer

experimento con r, g, b

ondrag()

bosque

3 árboles de ancho primero

aleatorización

fractalcurves

Curvas Hilbert & Koch

recursión

lindenmayer

etnomatemáticas (kolams indios)

Sistema-L

minimal_hanoi

Torres de Hanoi

Tortugas rectangulares como discos de Hanoi (shape, tamaño de forma)

nim

juega el clásico juego de nim con tres montones de palos contra la computadora.

tortugas como nimsticks, impulsado por eventos (mouse, teclado)

pintar

programa de dibujo super minimalista

onclick()

paz

elemental

turtle: apariencia y animación

penrose

embaldosado aperiódico con cometas y dardos

stamp()

planet_and_moon

simulación de sistema gravitacional

formas compuestas, Vec2D

round_dance

tortugas bailarinas que giran por parejas en dirección opuesta

formas compuestas, clonar tamaño de forma, tilt, get_shapepoly, update

sorting_animate

demostración visual de diferentes métodos de ordenamiento

alineación simple, aleatorización

árbol

un primer árbol de amplitud (gráfico, usando generadores)

clone()

two_canvases

diseño simple

tortugas en dos lienzos (two_canvases)

wikipedia

un patrón del artículo de wikipedia sobre gráficos de tortuga (turtle)

clone(), undo()

yinyang

otro ejemplo elemental

circle()

¡Diviértete!

Cambios desde Python 2.6

Los métodos Turtle.tracer(), Turtle.window_width() y Turtle.window_height() han sido eliminados. Los métodos con estos nombres y funciones ahora están disponibles solo como métodos de Screen. Las funciones derivadas de estos permanecen disponibles. (De hecho, ya en Python 2.6 estos métodos eran simplemente duplicaciones de los métodos correspondientes TurtleScreen/Screen).

El método Turtle.fill() ha sido eliminado. El comportamiento de begin_fill() y end_fill() ha cambiado ligeramente: ahora cada proceso de llenado debe completarse con una llamada end_fill().

Se ha añadido un método Turtle.filling(). Retorna un valor booleano: True si hay un proceso de llenado en curso, False en caso contrario. Este comportamiento corresponde a una llamada fill() sin argumentos en Python 2.6.

Cambios desde Python 3.0

Se han añadido los métodos Turtle.shearfactor(), Turtle.shapetransform() y Turtle.get_shapepoly(). Por lo tanto, ahora está disponible la gama completa de transformaciones lineales regulares para transformar formas de tortugas. Turtle.tiltangle() se ha mejorado en funcionalidad: ahora se puede usar para obtener o establecer el tiltangle. Turtle.settiltangle() ha quedado obsoleto.

El método Screen.onkeypress() se ha agregado como complemento a Screen.onkey() que, de hecho, une las acciones al evento keyrelease. En consecuencia, este último tiene un alias: Screen.onkeyrelease().

Se ha añadido el método Screen.mainloop(). Entonces, cuando se trabaja solo con objetos Screen y Turtle, ya no se debe importar adicionalmente mainloop().

Se han añadido dos métodos de entrada Screen.textinput() y Screen.numinput(). Estos cuadros de diálogo de entrada emergentes y retornan cadenas y números respectivamente.

Se han agregado dos scripts de ejemplo tdemo_nim.py y tdemo_round_dance.py al directorio Lib/turtledemo.

cmd — Soporte para intérpretes orientados a línea de comandos

Código fuente: Lib/cmd.py [https://github.com/python/cpython/tree/3.9/Lib/cmd.py]

La clase Cmd proporciona un framework simple para escribir intérpretes de comandos orientados a línea. A menudo son útiles para agentes de prueba, herramientas administrativas y prototipos que luego se incluirán en una interfaz más sofisticada.

class cmd.Cmd(completekey='tab', stdin=None, stdout=None)

Una instancia Cmd o subclase de la instancia es un framework intérprete orientado a líneas. No hay una buena razón para crear instancias Cmd; mas bien, es útil como una super clase de una clase intérprete que usted define con el fin de heredar métodos Cmd y encapsular métodos de acción.

El argumento opcional completekey es el nombre readline de una llave de finalización; por defecto es Tab. Si completekey no es None y readline está disponible, el comando de finalización es hecho automáticamente.

Los argumentos opcionales stdin y stdout especifican la entrada y salida de los objetos archivo que la instancia Cmd o la instancia subclase usará para la entrada y salida. Si no está especificado, se predeterminarán a sys.stdin y sys.stdout.

Si desea un stdin dado a ser usado, asegúrese de establecer las instancias atributo use_rawinput a False, de lo contrario stdin será ignorado.

Objetos Cmd

Una instancia Cmd tiene los siguientes métodos:

Cmd.cmdloop(intro=None)

Emita repetidamente una solicitud, acepte la entrada, analice un prefijo inicial de la entrada recibida y envíe a los métodos de acción, pasándoles el resto de la línea como argumento.

El argumento opcional es un banner o cadena de caracteres introductoria que se tramitará antes del primer mensaje (esto anula el atributo de clase intro).

Si el módulo readline es cargado, la entrada heredará automáticamente bash-como edición historia-lista (e.g. Control-P retorna al último comando, Control-N adelanta al siguiente, Control-F mueve el cursor a la derecha no destructivamente, Control-B mueve el cursor a la izquierda no destructivamente, etc.).

Un fin-de-archivo en la entrada es retornado como cadena de caracteres ’EOF’.

Una instancia del intérprete reconocerá un nombre de comando foo si y solo si tiene un método do_foo(). Como un caso especial, una línea comenzando con el carácter ’?’ es enviada al método do_help(). Como otro caso especial, una línea comenzando con el carácter ’!’ es enviada al método do_shell() (Si dicho método está definido).

Este método retornará cuando el método postcmd() retorna un valor verdadero. El argumento stop a postcmd() es el valor de retorno de los comandos correspondientes al método do_*().

Si completar está habilitado, comandos de completar se realizarán automáticamente y la finalización de los comandos args es realizada llamando complete_foo() con los argumentos text, line, begidx, y endidx. text es el prefijo de la cadena de caracteres que estamos intentando emparejar: todos los emparejamientos retornados deben comenzar con él. line es la linea de entrada actual con el espacio en blanco inicial eliminado, begidx y endidx son los índices iniciales y finales del texto prefijo, que podrían usarse para proporcionar un completar diferente dependiendo de la posición en la que se encuentre el argumento.

Todas las subclases de Cmd heredan un do_help() predefinido. Este método, llamado con el argumento 'bar', invoca el método correspondiente help_bar(), y si eso no está presente, imprime el docstring de do_bar(), si está disponible. Sin argumentos, do_help() enumera todos los temas de ayuda disponibles (Es decir, todos los comandos con los métodos correspondientes help_*() o los comandos que tienen docstrings), y también enumera cualquier comando no documentado.

Cmd.onecmd(str)

Interprete el argumento como si hubiera sido escrito en respuesta a la solicitud. Esto puede ser anulado, pero normalmente no debería ser necesario; vea los métodos precmd() y postcmd() para enlaces de ejecución útiles. El valor de retorno es una bandera que indica si la interpretación de los comandos por parte del intérprete debe detenerse. Si hay un método do_*() para el comando str, se retorna el valor de retorno de ese método; de lo contrario, se retorna el valor de retorno del método default().

Cmd.emptyline()

Método llamado cuando se ingresa una línea vacía en respuesta a la solicitud. Si este método no se anula, repite el último comando no vacío ingresado.

Cmd.default(line)

Método llamado en una línea de entrada cuando no se reconoce el prefijo del comando. Si este método no se anula, imprime un mensaje de error y retorna.

Cmd.completedefault(text, line, begidx, endidx)

Método llamado para completar una línea de entrada cuando no hay un comando específico, método complete_*`() está disponible. Por defecto, retorna una lista vacía.

Cmd.precmd(line)

Método de enlace ejecutado justo antes de que se interprete la línea de comando line, pero después de que se genere y emita la solicitud de entrada. Este método es un trozo en Cmd; existe para ser anulado por subclases. El valor de retorno es utilizado como el comando que se ejecutará mediante el método onecmd(); la implementación precmd() puede reescribir el comando o simplemente retornar line sin cambios.

Cmd.postcmd(stop, line)

Método de enlace ejecutado justo después de que finaliza un despacho de comando. Este método es un trozo en Cmd; existe para ser anulado por subclases. line es la línea de comando que se ejecutó, y stop es una bandera que indica si la ejecución finalizará después de la llamada a postcmd(); este será el valor de retorno del método onecmd(). El valor de retorno de este método será usado como el nuevo valor para la bandera interna que corresponde a stop; retornando falso hará que la interpretación continúe.

Cmd.preloop()

Método de enlace ejecutado una vez cuando cmdloop() es llamado. Este método es un trozo en Cmd; existe para ser anulado por subclases.

Cmd.postloop()

Método de enlace ejecutado una vez cuando cmdloop() está a punto de retornar. Este método es un trozo en Cmd; existe para ser anulado por subclases.

Instancias de subclases Cmd tienen algunas variables de instancia públicas:

Cmd.prompt

El aviso emitido para solicitar entradas.

Cmd.identchars

La cadena de caracteres aceptada para el prefijo del comando.

Cmd.lastcmd

El último prefijo de comando no vacío visto.

Cmd.cmdqueue

Una lista de líneas de entrada puestas en cola. La lista cmdqueue es verificada en cmdloop() cuando una nueva entrada es necesitada; Si es no vacía, sus elementos serán procesados en orden, como si se ingresara en la solicitud.

Cmd.intro

Una cadena para emitir como introducción o banner. Puede ser anulado dando un argumento al método cmdloop().

Cmd.doc_header

El encabezado a tramitar si la salida de ayuda tiene una sección para comandos documentados.

Cmd.misc_header

El encabezado a tramitar si la salida de ayuda tiene una sección para temas de ayuda misceláneos (Es decir, hay métodos help_*() sin los métodos correspondientes do_*() ).

Cmd.undoc_header

El encabezado a tramitar si la salida de ayuda tiene una sección para comandos no documentados (Es decir, hay métodos do_*() sin los métodos correspondientes help_*()).

Cmd.ruler

El carácter utilizado para dibujar líneas separadoras debajo de los encabezados mensajes-ayuda. Si está vacío, no se dibuja una línea regla. El valor predeterminado es ’=‘.

Cmd.use_rawinput

Una bandera, por defecto verdadera. Si es verdadera, cmdloop() usa input() para mostrar un mensaje y leer el siguiente comando; si es falsa, sys.stdout.write() y sys.stdin.readline() son usados. (Esto significa que importando readline, en sistemas que lo soportan, el intérprete soportará automáticamente Emacs-basados y comandos-historial de teclado.)

Ejemplo Cmd

El módulo cmd es principalmente útil para construir shells personalizados que permiten al usuario trabajar con un programa de forma interactiva.

Esta sección presenta un ejemplo simple de cómo construir un shell alrededor de algunos de los comandos en el módulo turtle.

Comandos turtle básicos como forward() son añadidos a la subclase Cmd con un método llamado do_forward(). El argumento es convertido a un número y enviado al módulo turtle. El docstring se utiliza en la utilidad de ayuda proporcionada por el shell.

El ejemplo también incluye un registro básico y facilidad de reproducción implementado con el método precmd() el cuál es el responsable de convertir la entrada a minúscula y escribir los comandos en un archivo. El método do_playback() lee el archivo y añade los comandos grabados al cmdqueue para una reproducción inmediata:

import cmd, sys
from turtle import *

class TurtleShell(cmd.Cmd):
    intro = 'Welcome to the turtle shell.   Type help or ? to list commands.\n'
    prompt = '(turtle) '
    file = None

    # ----- basic turtle commands -----
    def do_forward(self, arg):
        'Move the turtle forward by the specified distance:  FORWARD 10'
        forward(*parse(arg))
    def do_right(self, arg):
        'Turn turtle right by given number of degrees:  RIGHT 20'
        right(*parse(arg))
    def do_left(self, arg):
        'Turn turtle left by given number of degrees:  LEFT 90'
        left(*parse(arg))
    def do_goto(self, arg):
        'Move turtle to an absolute position with changing orientation.  GOTO 100 200'
        goto(*parse(arg))
    def do_home(self, arg):
        'Return turtle to the home position:  HOME'
        home()
    def do_circle(self, arg):
        'Draw circle with given radius an options extent and steps:  CIRCLE 50'
        circle(*parse(arg))
    def do_position(self, arg):
        'Print the current turtle position:  POSITION'
        print('Current position is %d %d\n' % position())
    def do_heading(self, arg):
        'Print the current turtle heading in degrees:  HEADING'
        print('Current heading is %d\n' % (heading(),))
    def do_color(self, arg):
        'Set the color:  COLOR BLUE'
        color(arg.lower())
    def do_undo(self, arg):
        'Undo (repeatedly) the last turtle action(s):  UNDO'
    def do_reset(self, arg):
        'Clear the screen and return turtle to center:  RESET'
        reset()
    def do_bye(self, arg):
        'Stop recording, close the turtle window, and exit:  BYE'
        print('Thank you for using Turtle')
        self.close()
        bye()
        return True

    # ----- record and playback -----
    def do_record(self, arg):
        'Save future commands to filename:  RECORD rose.cmd'
        self.file = open(arg, 'w')
    def do_playback(self, arg):
        'Playback commands from a file:  PLAYBACK rose.cmd'
        self.close()
        with open(arg) as f:
            self.cmdqueue.extend(f.read().splitlines())
    def precmd(self, line):
        line = line.lower()
        if self.file and 'playback' not in line:
            print(line, file=self.file)
        return line
    def close(self):
        if self.file:
            self.file.close()
            self.file = None

def parse(arg):
    'Convert a series of zero or more numbers to an argument tuple'
    return tuple(map(int, arg.split()))

if __name__ == '__main__':
    TurtleShell().cmdloop()

Aquí hay una sesión de muestra con la turle shell mostrando las funciones de ayuda, de ayuda, usando líneas en blanco para repetir comandos, un registro simple y facilidad de reproducción:

Welcome to the turtle shell.   Type help or ? to list commands.

(turtle) ?

Documented commands (type help <topic>):
========================================
bye     color    goto     home  playback  record  right
circle  forward  heading  left  position  reset   undo

(turtle) help forward
Move the turtle forward by the specified distance:  FORWARD 10
(turtle) record spiral.cmd
(turtle) position
Current position is 0 0

(turtle) heading
Current heading is 0

(turtle) reset
(turtle) circle 20
(turtle) right 30
(turtle) circle 40
(turtle) right 30
(turtle) circle 60
(turtle) right 30
(turtle) circle 80
(turtle) right 30
(turtle) circle 100
(turtle) right 30
(turtle) circle 120
(turtle) right 30
(turtle) circle 120
(turtle) heading
Current heading is 180

(turtle) forward 100
(turtle)
(turtle) right 90
(turtle) forward 100
(turtle)
(turtle) right 90
(turtle) forward 400
(turtle) right 90
(turtle) forward 500
(turtle) right 90
(turtle) forward 400
(turtle) right 90
(turtle) forward 300
(turtle) playback spiral.cmd
Current position is 0 0

Current heading is 0

Current heading is 180

(turtle) bye
Thank you for using Turtle

shlex — Análisis léxico simple

Código fuente: Lib/shlex.py [https://github.com/python/cpython/tree/3.9/Lib/shlex.py]

La clase shlex facilita la escritura de analizadores léxicos para sintaxis simples que se parecen al intérprete de comandos de Unix. Esto será a menudo útil para escribir pequeños lenguajes, (por ejemplo, en archivos de control para aplicaciones Python) o para analizar cadenas de texto citadas.

El módulo shlex define las siguientes funciones:

shlex.split(s, comments=False, posix=True)

Divide la cadena de caracteres s usando una sintaxis similar a la de un intérprete de comandos. Si comments es False (por defecto), el análisis de los comentarios en la cadena de caracteres dada sera deshabilitada (estableciendo el atributo commenters de la instancia shlex a la cadena de caracteres vacía). Esta función trabaja en modo POSIX por defecto, pero utiliza el modo non-POSIX si el argumento posix es falso.

Nota

Como la función split() inicia una instancia shlex, al pasar None por s se leerá la cadena de caracteres para separarse de la entrada estándar.

Obsoleto desde la versión 3.9: Passing None for s will raise an exception in future Python versions.

shlex.join(split_command)

Concatena los tokens de la lista split_command y retorna una cadena. Esta función es la inversa de split().

>>> from shlex import join
>>> print(join(['echo', '-n', 'Multiple words']))
echo -n 'Multiple words'

El valor retornado se escapa del intérprete de comandos para protegerlo contra vulnerabilidades de inyección (consulte quote()).

Nuevo en la versión 3.8.

shlex.quote(s)

Retorna una versión con escape del intérprete de comandos de la cadena s. El valor retornado es una cadena que se puede usar de forma segura como un token en un intérprete de línea de comandos, para los casos en los que no se puede usar una lista.

Este idioma sería inseguro:

>>> filename = 'somefile; rm -rf ~'
>>> command = 'ls -l {}'.format(filename)
>>> print(command)  # executed by a shell: boom!
ls -l somefile; rm -rf ~

quote() te permite tapar el agujero de seguridad:

>>> from shlex import quote
>>> command = 'ls -l {}'.format(quote(filename))
>>> print(command)
ls -l 'somefile; rm -rf ~'
>>> remote_command = 'ssh home {}'.format(quote(command))
>>> print(remote_command)
ssh home 'ls -l '"'"'somefile; rm -rf ~'"'"''

La cita es compatible con los intérpretes de comandos UNIX y con split():

>>> from shlex import split
>>> remote_command = split(remote_command)
>>> remote_command
['ssh', 'home', "ls -l 'somefile; rm -rf ~'"]
>>> command = split(remote_command[-1])
>>> command
['ls', '-l', 'somefile; rm -rf ~']

Nuevo en la versión 3.3.

El módulo shlex define las siguientes clases:

class shlex.shlex(instream=None, infile=None, posix=False, punctuation_chars=False)

Una instancia o instancia de la subclase shlex es un objeto de analizador léxico. El argumento de inicialización, si está presente, especifica de dónde leer caracteres. Debe ser un objeto similar a un archivo/stream con los métodos read() y readline() o una cadena de caracteres. Si no se da ningún argumento, la entrada se tomará de sys.stdin. El segundo argumento opcional es una cadena de nombre de archivo, que establece el valor inicial del atributo infile. Si el argumento instream es omitido o es igual a sys.stdin, este segundo argumento tiene como valor predeterminado «stdin». El argumento posix define el modo operativo: cuando posix no es true (predeterminado), la instancia shlex funcionará en modo de compatibilidad. Cuando se opera en modo POSIX, shlex intentará estar lo más cerca posible de las reglas de análisis de el intérprete de comandos POSIX. El argumento punctuation_chars proporciona una manera de hacer que el comportamiento sea aún más cercano a la forma en que se analizan los intérpretes de comandos reales. Esto puede tomar una serie de valores: el valor predeterminado, False, conserva el comportamiento visto en Python 3.5 y versiones anteriores. Si se establece en True, se cambia el análisis de los caracteres ();<>|&: cualquier ejecución de estos caracteres (caracteres considerados de puntuación) se retorna como un único token. Si se establece en una cadena de caracteres no vacía, esos caracteres se utilizarán como caracteres de puntuación. Los caracteres del atributo wordchars que aparecen en punctuation_chars se eliminarán de wordchars. Consulte Compatibilidad mejorada con intérprete de comandos para obtener más información. punctuation_chars solo se puede establecer en la creación de la instancia shlex y no se puede modificar más adelante.

Distinto en la versión 3.6: Se añadió el parámetro punctuation_chars.

Ver también

Módulo configparser

Analizador de archivos de configuración similares a los archivos .ini de Windows.

objetos shlex

Una instancia shlex tiene los siguientes métodos:

shlex.get_token()

Retorna un token. Si los tokens han sido apiladas usando push_token(), saca una ficha de la pila. De lo contrario, lee uno de la secuencia de entrada. Si la lectura encuentra un fin de archivo inmediato, eof se retorna (la cadena de caracteres vacía ('') en modo no-POSIX, y None en modo POSIX).

shlex.push_token(str)

Coloca el argumento en la pila de tokens.

shlex.read_token()

Lee un token sin procesar. Ignora la pila de retroceso y no interpreta las peticiones de la fuente. (Este no es normalmente un punto de entrada útil, y está documentado aquí sólo para completarlo.)

shlex.sourcehook(filename)

Cuando shlex detecta una petición de fuente (ver source abajo) este método recibe el siguiente token como argumento, y se espera que retorne una tupla que consista en un nombre de archivo y un archivo abierto como objeto.

Normalmente, este método primero elimina las comillas del argumento. Si el resultado es un nombre de ruta absoluto, o no había ninguna solicitud de origen anterior en vigor, o el origen anterior era una secuencia (como sys.stdin), el resultado se deja solo. De lo contrario, si el resultado es un nombre de ruta relativo, la parte del directorio del nombre del archivo se pone inmediatamente antes en la pila de inclusión de origen (este comportamiento es similar a la forma en que el preprocesador de C controla #include "file.h").

El resultado de las manipulaciones se trata como un nombre de archivo y se retorna como el primer componente de la tupla, con open() llamado en él para producir el segundo componente. (Nota: esto es lo contrario del orden de los argumentos en la inicialización de instancia!)

Este enlace se expone para que pueda usarlo para implementar rutas de búsqueda de directorios, adición de extensiones de archivo y otros trucos de espacios de nombres. No hay ningún enlace “close” correspondiente, pero una instancia de shlex llamará el método close() de la secuencia de entrada de origen cuando retorna EOF.

Para un control más explícito del apilamiento de código fuente, utilice los métodos push_source() y pop_source().

shlex.push_source(newstream, newfile=None)

Inserta una secuencia de fuente de entrada en la pila de entrada. Si se especifica el argumento de nombre de archivo, más adelante estará disponible para su uso en mensajes de error. Este es el mismo método utilizado internamente por el método sourcehook().

shlex.pop_source()

Saca la última fuente de entrada de la pila de entrada. Este es el mismo método que el analizador léxico utiliza cuando llega al EOF en una secuencia de entrada apilada.

shlex.error_leader(infile=None, lineno=None)

Este método genera un mensaje de error líder en el formato de una etiqueta de error del compilador de Unix C; el formato es '"%s", line %d: ', donde el %s es reemplazado con el nombre del archivo fuente actual y el %d con el número de línea de entrada actual (los argumentos opcionales pueden ser usado para sobrescribir estos).

Esta conveniencia se proporciona para animar a los usuarios de shlex a generar mensajes de error en el formato estándar y analizable que entienden Emacs y otras herramientas de Unix.

Las instancias de las subclases shlex tienen algunas variables de instancia pública que controlan el análisis léxico o pueden ser usadas para la depuración:

shlex.commenters

La cadena de caracteres que son reconocidos como comentarios de principiantes. Todos los caracteres desde el comentario principiante hasta el final de la línea son ignorados. Incluye sólo '#' por defecto.

shlex.wordchars

La cadena de caracteres que se acumulará en tokens de varios caracteres. Por defecto, incluye todos los alfanuméricos ASCII y el subrayado. En el modo POSIX, los caracteres acentuados del conjunto Latin-1 también están incluidos. Si punctuation_chars no está vacío, los caracteres ~-./*?=, que pueden aparecer en las especificaciones del nombre de archivo y en los parámetros de la línea de comandos, también se incluirán en este atributo, y cualquier carácter que aparezca en punctuation_chars será eliminado de wordchars si están presentes allí. Si whitespace_split se establece en True, esto no tendrá ningún efecto.

shlex.whitespace

Caracteres que serán considerados como espacio en blanco y salteados. El espacio blanco limita los tokens. Por defecto, incluye espacio, tabulación, salto de línea y retorno de carro.

shlex.escape

Caracteres que serán considerados como de escape. Esto sólo se usará en el modo POSIX, e incluye sólo '\' por defecto.

shlex.quotes

Los caracteres que serán considerados como citas de la cadena. El token se acumula hasta que la misma cita se encuentra de nuevo (así, los diferentes tipos de citas se protegen entre sí como en el intérprete de comandos.) Por defecto, incluye ASCII comillas simples y dobles.

shlex.escapedquotes

Caracteres en quotes que interpretarán los caracteres de escape definidos en escape. Esto sólo se usa en el modo POSIX, e incluye sólo '"' por defecto.

shlex.whitespace_split

Si es True, los tokens sólo se dividirán en espacios en blanco. Esto es útil, por ejemplo, para analizar las líneas de comando con shlex, obteniendo los tokens de forma similar a los argumentos de el intérprete de comandos. Cuando se utiliza en combinación con puntuation_chars, los tokens se dividirán en espacios en blanco además de esos caracteres.

Distinto en la versión 3.8: El atributo puntuation_chars se hizo compatible con el atributo whitespace_split.

shlex.infile

El nombre del archivo de entrada actual, como se estableció inicialmente al momento de la instanciación de la clase o apilado por solicitudes de fuente posteriores. Puede ser útil examinar esto cuando se construyan mensajes de error.

shlex.instream

El flujo de entrada del cual esta instancia shlex está leyendo caracteres.

shlex.source

Este atributo es None por defecto. Si le asignas una cadena, esa cadena será reconocida como una solicitud de inclusión a nivel léxico similar a la palabra clave source en varios intérpretes de comandos. Es decir, el token inmediatamente siguiente se abrirá como un nombre de archivo y la entrada se tomará de ese flujo hasta EOF, en cuyo momento se llamará al método close() de ese flujo y la fuente de entrada se convertirá de nuevo en el flujo de entrada original. Las peticiones de origen pueden ser apiladas a cualquier número de niveles de profundidad.

shlex.debug

Si este atributo es numérico y 1 o más, una instancia shlex imprimirá una salida de progreso verboso en su comportamiento. Si necesitas usar esto, puedes leer el código fuente del módulo para conocer los detalles.

shlex.lineno

Numero de linea de fuente (conteo de las nuevas lineas vistas hasta ahora mas uno).

shlex.token

El buffer de tokens. Puede ser útil examinarlo cuando se capturan excepciones.

shlex.eof

Token usado para determinar el final del archivo. Esto se ajustará a la cadena de caracteres vacía (''), en el modo no-POSIX, y a None en el modo POSIX.

shlex.punctuation_chars

Una propiedad de sólo lectura. Caracteres que serán considerados como puntuación. Las series de caracteres de puntuación se retornarán como un único token. Sin embargo, tenga en cuenta que no se realizará ninguna comprobación de validez semántica: por ejemplo, “>>>” podría ser retornado como un token, aunque no sea reconocido como tal por los intérpretes de comandos.

Nuevo en la versión 3.6.

Reglas de análisis

Cuando se opera en modo no-POSIX, shlex intentará obedecer las siguientes reglas.

Los caracteres entre comillas no son reconocidos dentro de las palabras (Do"Not"Separate es analizado como la única palabra Do"Not"Separate);

Los caracteres de escape no son reconocidos;

El encerrar los caracteres entre comillas preserva el valor literal de todos los caracteres dentro de las comillas;

Las comillas finales separan las palabras ("Do"Separate es analizado como "Do" y Separate);

Si whitepace_split es False, cualquier carácter que no sea declarado como un carácter de palabra, espacio en blanco, o una cita será retornado como un token de un solo carácter. Si es True, shlex sólo dividirá las palabras en espacios en blanco;

EOF es señalado con una cadena de caracteres vacía ('');

No es posible analizar cadenas de caracteres vacías, incluso si se citan.

Cuando se opera en el modo POSIX, shlex intentará obedecer a las siguientes reglas de análisis.

Las comillas se eliminan y no separan las palabras ("Do"Not"Separate" se analiza como la sola palabra DoNotSeparate);

Los caracteres de escape no citados (por ejemplo '\') conservan el valor literal del siguiente carácter que continua;

Encerrar caracteres entre comillas que no forman parte de escapedquotes (por ejemplo, "") conservan el valor literal de todos los caracteres dentro de las comillas;

Encerrar caracteres entre comillas que forman parte de escapedquotes (por ejemplo, "") conserva el valor literal de todos los caracteres dentro de las comillas, con la excepción de los caracteres mencionados en escape. Los caracteres de escape conservan su significado especial solo cuando van seguidos de la comilla en uso, o el propio carácter de escape. De lo contrario, el carácter de escape sera considerado un carácter normal.

EOF es señalado con un valor None;

Se permiten cadenas de caracteres vacías entrecomilladas ('').

Compatibilidad mejorada con intérprete de comandos

Nuevo en la versión 3.6.

La clase shlex provee compatibilidad con el análisis realizado por los intérprete de comandos comunes de Unix como bash, dash y sh. Para aprovechar esta compatibilidad, especifica el argumento punctuation_chars en el constructor. Esto por defecto es False, el cual conserva el comportamiento pre-3.6. Sin embargo, si se establece como True, entonces se cambia el análisis de los caracteres ();<>|&: cualquier ejecución de estos caracteres se retorna como un único token. Mientras que esto se queda corto en un analizador completo para los intérprete de comandos (que estaría fuera del alcance de la biblioteca estándar, dada la multiplicidad de intérpretes de comandos que hay), te permite realizar el procesamiento de las líneas de comandos más fácilmente de lo que podrías hacerlo de otra manera. Para ilustrarlo, puede ver la diferencia en el siguiente fragmento:

 >>> import shlex
 >>> text = "a && b; c && d || e; f >'abc'; (def \"ghi\")"
 >>> s = shlex.shlex(text, posix=True)
 >>> s.whitespace_split = True
 >>> list(s)
 ['a', '&&', 'b;', 'c', '&&', 'd', '||', 'e;', 'f', '>abc;', '(def', 'ghi)']
 >>> s = shlex.shlex(text, posix=True, punctuation_chars=True)
 >>> s.whitespace_split = True
 >>> list(s)
 ['a', '&&', 'b', ';', 'c', '&&', 'd', '||', 'e', ';', 'f', '>', 'abc', ';',
 '(', 'def', 'ghi', ')']

Por supuesto, se retornarán tokens que no son válidos para los intérpretes de comandos y deberá implementar sus propias comprobaciones de errores en los tokens retornados.

En lugar de pasar True como valor para el parámetro punctuation_chars, puede pasar una cadena con caracteres específicos, que se usará para determinar qué caracteres constituyen puntuación. Por ejemplo:

>>> import shlex
>>> s = shlex.shlex("a && b || c", punctuation_chars="|")
>>> list(s)
['a', '&', '&', 'b', '||', 'c']

Nota

Cuando es especificado punctuation_chars, el atributo wordchars se aumenta con los caracteres ~-./*?=. Esto se debe a que estos caracteres pueden aparecer en los nombres de archivo (incluidos los comodines) y en los argumentos de la línea de comandos (por ejemplo, --color=auto). Por lo tanto:

>>> import shlex
>>> s = shlex.shlex('~/a && b-c --color=auto || d *.py?',
...                 punctuation_chars=True)
>>> list(s)
['~/a', '&&', 'b-c', '--color=auto', '||', 'd', '*.py?']

Sin embargo, para que coincida con el intérprete de comandos lo más cerca posible, se recomienda utilizar siempre posix y whitespace_split cuando se utiliza punctuation_chars, el cual negará por completo wordchars.

Para obtener el mejor efecto, punctuation_chars debe establecerse junto con posix=True. (Tenga en cuenta que posix=False es el valor predeterminado para shlex.)

Interfaces gráficas de usuario con Tk

Tk/Tcl ha sido durante mucho tiempo una parte integral de Python. Proporciona un conjunto de herramientas robusto e independiente de la plataforma para administrar ventanas. Disponible para desarrolladores a través del paquete tkinter y sus extensiones, los módulos tkinter.tix y tkinter.ttk.

The tkinter package is a thin object-oriented layer on top of Tcl/Tk. To use tkinter, you don’t need to write Tcl code, but you will need to consult the Tk documentation, and occasionally the Tcl documentation. tkinter is a set of wrappers that implement the Tk widgets as Python classes.

tkinter’s chief virtues are that it is fast, and that it usually comes bundled with Python. Although its standard documentation is weak, good material is available, which includes: references, tutorials, a book and others. tkinter is also famous for having an outdated look and feel, which has been vastly improved in Tk 8.5. Nevertheless, there are many other GUI libraries that you could be interested in. The Python wiki lists several alternative GUI frameworks and tools [https://wiki.python.org/moin/GuiProgramming].

tkinter — Interface de Python para Tcl/Tk

Módulos Tkinter

Guía de supervivencia de Tkinter

Cómo usar esta sección

Un simple programa Hola Mundo

Una (muy) rápida mirada a Tcl/Tk

Mapeo básico de Tk en Tkinter

Cómo se relacionan Tk y Tkinter

Guía práctica

Configuración de opciones

El empaquetador

Opciones del empaquetador

Asociación de variables de widget

El gestor de ventanas

Tipos de datos de opciones Tk

Enlaces y eventos

El parámetro índice

Imágenes

Gestor de archivos

tkinter.colorchooser — Diálogo de elección de color

tkinter.font — Envoltorio de fuente Tkinter

Diálogos Tkinter

tkinter.simpledialog —Diálogos de entrada estándar de Tkinter

Diálogos de selección de archivos

Diálogos nativos de carga/guardado

tkinter.commondialog — Plantillas de ventanas de diálogo

tkinter.messagebox — Indicadores de mensajes de Tkinter

tkinter.scrolledtext — Widget de texto desplazado

tkinter.dnd — Soporte de arrastrar y soltar

tkinter.ttk — Tk widgets temáticos

Uso de Ttk

Ttk widgets

Widget

Opciones estándar

Opciones de widgets desplegables

Opciones de etiqueta

Opciones de compatibilidad

Estados del widget

ttk.Widget

Combobox

Opciones

Eventos virtuales

ttk.Combobox

Spinbox

Opciones

Eventos virtuales

ttk.Spinbox

Notebook

Opciones

Opciones de pestañas

Identificadores de pestañas

Eventos virtuales

ttk.Notebook

Progressbar

Opciones

ttk.Progressbar

Separator

Opciones

Sizegrip

Notas específicas por plataforma

Errores detectados

Treeview

Opciones

Opciones de elementos

Opciones de etiqueta

Identificadores de columna

Eventos virtuales

ttk.Treeview

Ttk Styling

Diseños

tkinter.tix — Ampliación de widgets para Tk

Usando Tix

Widgets de Tix

Widgets Básicos

Selectores de Archivos

ListBox jerárquico

ListBox Tabular

Gestores de Widgets

Tipos de Imágenes

Widgets Varios

Gestor de Geometría de Formulario

Comandos Tix

IDLE

Menús

Menú de archivo (Shell y Editor)

Menú editar (Shell y Editor)

Menú de formato (solo ventana del Editor)

Menú ejecutar (solo ventana Editor)

Menú de shell (solo ventana de shell)

Menú de depuración (solo ventana de shell)

Menú de opciones (Shell y editor)

Menú de ventana (shell y editor)

Menú de ayuda (shell y editor)

Menús contextuales

Edición y navegación

Ventana del editor

Atajos de teclado

Indentación automática

Terminaciones

Sugerencias de llamada

Contexto del código

Shell de Python

Colores del texto

Inicio y ejecución de código

Uso de línea de comando

Error de inicio

Ejecutando código del usuario

Salida del usuario en consola

Desarrollando aplicaciones tkinter

Ejecutando sin un subproceso

Ayuda y preferencias

Recursos de ayuda

Preferencias de configuración

IDLE en macOS

Extensiones

tkinter — Interface de Python para Tcl/Tk

Código fuente: Lib/tkinter/__init__.py [https://github.com/python/cpython/tree/3.9/Lib/tkinter/__init__.py]

The tkinter package («Tk interface») is the standard Python interface to the Tcl/Tk GUI toolkit. Both Tk and tkinter are available on most Unix platforms, including macOS, as well as on Windows systems.

Ejecutar python -m tkinter desde la línea de comandos debería abrir una ventana que demuestre una interfaz Tk simple para saber si tkinter está instalado correctamente en su sistema. También muestra qué versión de Tcl/Tk está instalada para que pueda leer la documentación de Tcl/Tk específica de esa versión.

Ver también

TkDocs [http://tkdocs.com/]

Extensive tutorial on creating user interfaces with Tkinter. Explains key concepts, and illustrates recommended approaches using the modern API.

Tkinter 8.5 reference: a GUI for Python [https://www.tkdocs.com/shipman/]

Reference documentation for Tkinter 8.5 detailing available classes, methods, and options.

Tcl/Tk Resources:

Comandos Tk [https://www.tcl.tk/man/tcl8.6/TkCmd/contents.htm]

Comprehensive reference to each of the underlying Tcl/Tk commands used by Tkinter.

Tcl/Tk Home Page [https://www.tcl.tk]

Additional documentation, and links to Tcl/Tk core development.

Books:

Modern Tkinter for Busy Python Developers [https://tkdocs.com/book.html]

By Mark Roseman. (ISBN 978-1999149567)

Python and Tkinter Programming [https://www.packtpub.com/product/python-gui-programming-with-tkinter/9781788835886]

By Alan Moore. (ISBN 978-1788835886)

Programming Python [http://learning-python.com/about-pp4e.html]

By Mark Lutz; has excellent coverage of Tkinter. (ISBN 978-0596158101)

Tcl and the Tk Toolkit (2nd edition) [https://www.amazon.com/exec/obidos/ASIN/032133633X]

By John Ousterhout, inventor of Tcl/Tk, and Ken Jones; does not cover Tkinter. (ISBN 978-0321336330)

Módulos Tkinter

Support for Tkinter is spread across several modules. Most applications will need the main tkinter module, as well as the tkinter.ttk module, which provides the modern themed widget set and API:

from tkinter import *
from tkinter import ttk

class tkinter.Tk(screenName=None, baseName=None, className='Tk', useTk=True, sync=False, use=None)

Construct a toplevel Tk widget, which is usually the main window of an application, and initialize a Tcl interpreter for this widget. Each instance has its own associated Tcl interpreter.

The Tk class is typically instantiated using all default values. However, the following keyword arguments are currently recognized:

screenName

When given (as a string), sets the DISPLAY environment variable. (X11 only)

baseName

Name of the profile file. By default, baseName is derived from the program name (sys.argv[0]).

className

Name of the widget class. Used as a profile file and also as the name with which Tcl is invoked (argv0 in interp).

useTk

If True, initialize the Tk subsystem. The tkinter.Tcl() function sets this to False.

sync

If True, execute all X server commands synchronously, so that errors are reported immediately. Can be used for debugging. (X11 only)

use

Specifies the id of the window in which to embed the application, instead of it being created as an independent toplevel window. id must be specified in the same way as the value for the -use option for toplevel widgets (that is, it has a form like that returned by winfo_id()).

Note that on some platforms this will only work correctly if id refers to a Tk frame or toplevel that has its -container option enabled.

Tk reads and interprets profile files, named .className.tcl and .baseName.tcl, into the Tcl interpreter and calls exec() on the contents of .className.py and .baseName.py. The path for the profile files is the HOME environment variable or, if that isn’t defined, then os.curdir.

tk

The Tk application object created by instantiating Tk. This provides access to the Tcl interpreter. Each widget that is attached the same instance of Tk has the same value for its tk attribute.

master

The widget object that contains this widget. For Tk, the master is None because it is the main window. The terms master and parent are similar and sometimes used interchangeably as argument names; however, calling winfo_parent() returns a string of the widget name whereas master returns the object. parent/child reflects the tree-like relationship while master/slave reflects the container structure.

children

The immediate descendants of this widget as a dict with the child widget names as the keys and the child instance objects as the values.

tkinter.Tcl(screenName=None, baseName=None, className='Tk', useTk=False)

La función Tcl() es una función de fábrica que crea un objeto muy similar al creado por la clase Tk, excepto que no inicializa el subsistema Tk. Esto suele ser útil cuando se maneja el intérprete de Tcl en un entorno en el que no se desean crear ventanas de nivel superior extrañas o donde no se puede (como los sistemas Unix/Linux sin un servidor X). Un objeto creado por el objeto Tcl() puede tener una ventana Toplevel creada (y el subsistema Tk inicializado) llamando a su método loadtk().

The modules that provide Tk support include:

tkinter

Main Tkinter module.

tkinter.colorchooser

Cuadro de diálogo que permite al usuario elegir un color.

tkinter.commondialog

Clase base para cuadros de diálogo definidos en los otros módulos listados aquí.

tkinter.filedialog

Cuadros de diálogo por defecto que permiten al usuario especificar un archivo para abrir o guardar.

tkinter.font

Utilidades para ayudar a trabajar con fuentes.

tkinter.messagebox

Acceso a cuadros de diálogo estándar de Tk.

tkinter.scrolledtext

Widget de texto con una barra de desplazamiento vertical integrada.

tkinter.simpledialog

Cuadros de diálogo simples y funciones útiles.

tkinter.ttk

Themed widget set introduced in Tk 8.5, providing modern alternatives for many of the classic widgets in the main tkinter module.

Additional modules:

_tkinter

A binary module that contains the low-level interface to Tcl/Tk. It is automatically imported by the main tkinter module, and should never be used directly by application programmers. It is usually a shared library (or DLL), but might in some cases be statically linked with the Python interpreter.

idlelib

Python’s Integrated Development and Learning Environment (IDLE). Based on tkinter.

tkinter.constants

Symbolic constants that can be used in place of strings when passing various parameters to Tkinter calls. Automatically imported by the main tkinter module.

tkinter.dnd

(experimental) Drag-and-drop support for tkinter. This will become deprecated when it is replaced with the Tk DND.

tkinter.tix

(deprecated) An older third-party Tcl/Tk package that adds several new widgets. Better alternatives for most can be found in tkinter.ttk.

turtle

Gráficos de tortuga en una ventana Tk.

Guía de supervivencia de Tkinter

Esta sección no está diseñada para ser un tutorial exhaustivo sobre Tk o Tkinter. Más bien, está pensado como un espacio intermedio que proporciona una orientación introductoria en el sistema.

Créditos:

Tk fue escrito por John Ousterhout mientras estaba en Berkeley.

Tkinter fue escrito por Steen Lumholt y Guido van Rossum.

Esta guía de supervivencia fue escrita por Matt Conway en la Universidad de Virginia.

El renderizado HTML, y algunas ediciones libres, fueron producidas a partir de una versión de FrameMaker por Ken Manheimer.

Fredrik Lundh elaboró ​​y revisó las descripciones de la interfaz de clase para actualizarlas con Tk 4.2.

Mike Clarkson convirtió la documentación a LaTeX y compiló el capítulo de Interfaz de usuario del manual de referencia.

Cómo usar esta sección

Esta sección está diseñada en dos partes: la primera mitad (aproximadamente) cubre el material de fondo, mientras que la segunda mitad se puede llevar al teclado como referencia práctica.

Al tratar de responder preguntas sobre cómo hacer «esto o aquello», a menudo es mejor descubrir cómo hacerlo en Tk y luego convertirlo a la función correspondiente tkinter. Los programadores de Python a menudo pueden adivinar el comando Python correcto consultando la documentación de Tk. Esto significa que para usar Tkinter deberá conocer un poco sobre Tk. Este documento no puede cumplir esa función, por lo que lo mejor que podemos hacer es señalarle la mejor documentación que existe. Aquí hay algunos consejos:

Los autores sugieren encarecidamente obtener una copia de las páginas del manual de Tk. Específicamente, las páginas del directorio manN son las más útiles. Las páginas del manual man3 describen la interfaz C para la biblioteca Tk y, por lo tanto, no son especialmente útiles para los desarrolladores de scripts.

Addison-Wesley publica un libro llamado «Tcl and the Tk Toolkit» de John Ousterhout (ISBN 0-201-63337-X) que es una buena introducción a Tcl y Tk para novatos. El libro no es exhaustivo y para muchos detalles difiere de las páginas del manual.

tkinter/__init__.py es el último recurso para la mayoría, pero puede ser un buen lugar para ir cuando nada más tiene sentido.

Un simple programa Hola Mundo

import tkinter as tk

class Application(tk.Frame):
    def __init__(self, master=None):
        super().__init__(master)
        self.master = master
        self.pack()
        self.create_widgets()

    def create_widgets(self):
        self.hi_there = tk.Button(self)
        self.hi_there["text"] = "Hello World\n(click me)"
        self.hi_there["command"] = self.say_hi
        self.hi_there.pack(side="top")

        self.quit = tk.Button(self, text="QUIT", fg="red",
                              command=self.master.destroy)
        self.quit.pack(side="bottom")

    def say_hi(self):
        print("hi there, everyone!")

root = tk.Tk()
app = Application(master=root)
app.mainloop()

Una (muy) rápida mirada a Tcl/Tk

La jerarquía de clases parece complicada, pero en la práctica, los programadores de aplicaciones casi siempre se refieren a las clases en la parte inferior de la jerarquía.

Notas:

Estas clases se proporcionan con el propósito de organizar ciertas funciones en un solo un espacio de nombres. No están destinadas a ser instanciadas independientemente.

La clase Tk está destinada a ser instanciada solo una vez en una aplicación. Los desarrolladores no necesitan crear una instancia explícitamente. El sistema crea una cada vez que se instancia cualquiera de las otras clases.

La clase Widget no está destinada a ser instanciada, solo está destinada a subclases para crear widgets «reales» (en C++, esto se llama una “clase abstracta”).

Para hacer uso de este material de referencia, habrá momentos en los que necesitará saber cómo leer pasajes cortos de Tk y cómo identificar las diversas partes de un comando Tk. Consulte la sección Mapeo básico de Tk en Tkinter para los equivalentes tkinter de lo que se muestra a continuación.

Los scripts Tk son programas Tcl. Como todos los programas Tcl, los scripts Tk son solo listas de tokens separados por espacios. Un widget Tk es solo su clase, las opciones que ayudan a configurarlo y las acciones que lo hacen hacer cosas útiles.

Para hacer un widget en Tk, el comando siempre tiene la siguiente forma:

classCommand newPathname options

classCommand

denota qué tipo de widget hacer (un botón, una etiqueta, un menú…)

newPathname

es el nuevo nombre para este widget. Todos los nombres en Tk deben ser únicos. Para ayudar a aplicar esto, los widgets en Tk se nombran con rutas, al igual que los archivos en un sistema de archivos. El widget de nivel superior, el root, se llama . (punto) y los elementos secundarios están delimitados por más puntos. Por ejemplo, .myApp.controlPanel.okButton podría ser el nombre de un widget.

options

configurar la apariencia del widget y, en algunos casos, su comportamiento. Las opciones vienen en forma de una lista de parámetros y valores. Los parámetros están precedidas por un “-”, como los parámetros en una shell de Unix, y los valores se ponen entre comillas si son más de una palabra.

Por ejemplo:

button   .fred   -fg red -text "hi there"
   ^       ^     \______________________/
   |       |                |
 class    new            options
command  widget  (-opt val -opt val ...)

Una vez creado, la ruta de acceso al widget se convierte en un nuevo comando. Este nuevo comando de widget es el identificador para que el nuevo widget realice alguna acción. En C, expresarías esto como someAction(fred, someOptions); en C++, expresarías esto como fred.someAction(someOptions), y en Tk:

.fred someAction someOptions

Tenga en cuenta que el nombre del objeto, .fred, comienza con un punto.

Como era de esperar, los valores legales para someAction dependerán de la clase del widget: .fred disable funciona si fred es un botón (se atenúa), pero no funciona si fred es una etiqueta (la desactivación de etiquetas no es compatible con Tk).

Los valores legales de someOptions dependen de la acción. Algunas acciones, como disable, no requieren argumentos; otras, como el comando delete de un cuadro de entrada de texto, necesitarían argumentos para especificar qué rango de texto eliminar.

Mapeo básico de Tk en Tkinter

Los comandos de clase en Tk corresponden a constructores de clase en Tkinter.:

button .fred                =====>  fred = Button()

El constructor de un objeto está implícito en el nuevo nombre que se le dio durante la creación. En Tkinter, los constructores se especifican explícitamente.

button .panel.fred          =====>  fred = Button(panel)

Las opciones de configuración en Tk se dan en listas de etiquetas con guiones seguidas de valores. En Tkinter, las opciones se especifican como argumentos de palabras clave en el constructor de instancias y argumentos de palabras clave para llamadas de configuración o como índices de instancias, en estilo diccionario, para instancias establecidas. Consulte la sección Configuración de opciones sobre las opciones de configuración.

button .fred -fg red        =====>  fred = Button(panel, fg="red")
.fred configure -fg red     =====>  fred["fg"] = red
                            OR ==>  fred.config(fg="red")

En Tk, para realizar una acción en un widget, use el nombre del widget como un comando y siga con un nombre de acción, posiblemente con argumentos (opciones). En Tkinter, llamas a métodos en la instancia de clase para invocar acciones en el widget. Las acciones (métodos) que puede realizar un widget determinado se enumeran en tkinter/__init__.py.

.fred invoke                =====>  fred.invoke()

Para pasar el widget al empaquetador (que administra el diseño de la pantalla) en Tk, llame al comando pack con argumentos opcionales. En Tkinter, la clase Pack tiene todas estas funcionalidades y las diferentes formas del comando pack se implementan como métodos. Todos los widgets en tkinter son subclases del empaquetador, por lo que heredan todos los métodos de empaquetado. Consulte la documentación del módulo tkinter.tix para obtener más información sobre el administrador de diseño de formularios.

pack .fred -side left       =====>  fred.pack(side="left")

Cómo se relacionan Tk y Tkinter

De arriba para abajo:

Tu aplicación (Python)

Una aplicación Python hace una llamada tkinter.

tkinter (paquete de Python)

Esta llamada (por ejemplo, crear un widget de botón) se implementa en el paquete tkinter, que está escrito en Python. Esta función de Python analizará los comandos y los argumentos y los convertirá en una forma que los haga ver como si vinieran de un script Tk en lugar de un script Python.

_tkinter (C)

Estos comandos y sus argumentos se pasarán a una función C en el módulo de extensión _tkinter -obsérvese el guión bajo-.

Tk Widgets (C y Tcl)

Esta función en C puede realizar llamadas a otros módulos C, incluidas las funciones de C que forman la biblioteca Tk. Tk se implementa usando C y un poco de Tcl. La parte Tcl de los widgets Tk se usa para vincular ciertos comportamientos predeterminados de los widgets, y se ejecuta una vez cuando se importa el paquete Python tkinter (el usuario nunca ve esta etapa).

Tk (C)

La parte Tk de los widgets Tk implementa el mapeo final a…

Xlib (C)

la biblioteca Xlib para dibujar elementos gráficos en la pantalla.

Guía práctica

Configuración de opciones

Las opciones controlan parámetros como el color y el ancho del borde de un widget. Las opciones se pueden configurar de tres maneras:

En el momento de la creación del objeto, utilizando argumentos de palabras clave

fred = Button(self, fg="red", bg="blue")

Después de la creación del objeto, tratando el nombre de la opción como un índice de diccionario

fred["fg"] = "red"
fred["bg"] = "blue"

Usando el método config() para actualizar múltiples atributos después de la creación del objeto

fred.config(fg="red", bg="blue")

Para obtener una explicación completa de las opciones y su comportamiento, consulte las páginas de manual de Tk para el widget en cuestión.

Tenga en cuenta que las páginas del manual enumeran «OPCIONES ESTÁNDAR» y «OPCIONES ESPECÍFICAS DE WIDGET» para cada widget. La primera es una lista de opciones que son comunes a muchos widgets, la segunda son las opciones que son específicas para ese widget en particular. Las opciones estándar están documentadas en la página del manual options(3).

No se hace distinción entre las opciones estándar y las opciones específicas del widget en este documento. Algunas opciones no se aplican a algunos tipos de widgets. Si un determinado widget responde a una opción particular depende de la clase del widget. Los botones tienen la opción command, las etiquetas no.

Las opciones admitidas por un widget dado se enumeran en la página de manual de ese widget, o se pueden consultar en tiempo de ejecución llamando al método config() sin argumentos, o llamando al método keys() en ese widget. El valor retornado en esas llamadas es un diccionario cuya clave es el nombre de la opción como una cadena (por ejemplo, 'relief') y cuyo valor es una tupla de 5 elementos.

Algunas opciones, como bg, son sinónimos de opciones comunes con nombres largos (bg es la abreviatura de «background»). Al pasar el método config(), el nombre de una opción abreviada retornará una tupla de 2 elementos (en lugar de 5). Esta tupla contiene nombres de sinónimos y nombres de opciones «reales» (como ('bg', 'background')).

Índice

Significado

Ejemplo

0

nombre de la opción

'relief'

1

nombre de la opción para la búsqueda en la base de datos

'relief'

2

clase de la opción para la consulta de base de datos

'Relief'

3

valor por defecto

'raised'

4

valor actual

'groove'

Ejemplo:

>>> print(fred.config())
{'relief': ('relief', 'relief', 'Relief', 'raised', 'groove')}

Por supuesto, el diccionario impreso incluirá todas las opciones disponibles y sus valores. Esto es solo un ejemplo.

El empaquetador

El empaquetador es uno de los mecanismos de gestión de geometría de Tk. Los administradores de geometría se utilizan para especificar la posición relativa de los widgets dentro de su contenedor: su master mutuo. En contraste con el placer más engorroso (que se usa con menos frecuencia, y no cubrimos aquí), el empaquetador toma la especificación de relación cualitativa - above, to the left of, filling, etc - y funciona todo para determinar las coordenadas de ubicación exactas para usted.

El tamaño de cualquier widget master está determinado por el tamaño del «widget esclavo» interno. El empaquetador se usa para controlar dónde se colocará el widget esclavo en el widget maestro de destino. Para lograr el diseño deseado, puede empaquetar el widget en un marco y luego empaquetar ese marco en otro. Además, una vez empaquetado, la disposición se ajusta dinámicamente de acuerdo con los cambios de configuración posteriores.

Tenga en cuenta que los widgets no aparecen hasta que su geometría no se haya especificado con un administrador de diseño de pantalla. Es un error común de principiante ignorar la especificación de la geometría, y luego sorprenderse cuando se crea el widget pero no aparece nada. Un objeto gráfico solo aparece después que, por ejemplo, se le haya aplicado el método pack() del empaquetador.

Se puede llamar al método pack() con pares palabra-clave/valor que controlan dónde debe aparecer el widget dentro de su contenedor y cómo se comportará cuando se cambie el tamaño de la ventana principal de la aplicación. Aquí hay unos ejemplos:

fred.pack()                     # defaults to side = "top"
fred.pack(side="left")
fred.pack(expand=1)

Opciones del empaquetador

Para obtener más información sobre el empaquetador y las opciones que puede tomar, consulte el manual y la página 183 del libro de John Ousterhout.

anchor

Tipo de anclaje. Indica dónde debe colocar el empaquetador a cada esclavo en su espacio.

expand

Un valor booleano, 0 o 1.

fill

Los valores legales son: 'x', 'y', 'both', 'none'.

ipadx y ipady

Una distancia que designa el relleno interno a cada lado del widget esclavo.

padx y pady

Una distancia que designa el relleno externo a cada lado del widget esclavo.

side

Los valores legales son: 'left', 'right', 'top', 'bottom'.

Asociación de variables de widget

La asignación de un valor a ciertos objetos gráficos (como los widgets de entrada de texto) se puede vincular directamente a variables en su aplicación utilizando opciones especiales. Estas opciones son variable, textvariable, onvalue, offvalue, y value. Esta conexión funciona en ambos sentidos: si la variable cambia por algún motivo, el widget al que está conectado se actualizará para reflejar el nuevo valor.

Desafortunadamente, en la implementación actual de tkinter no es posible entregar una variable arbitraria de Python a un widget a través de una opción variable o textvariable . Los únicos tipos de variables para las cuales esto funciona son variables que son subclases de la clase Variable, definida en tkinter.

Hay muchas subclases útiles de Variable ya definidas: StringVar, IntVar, DoubleVar, and BooleanVar. Para leer el valor actual de dicha variable, es necesario llamar al método get(), y para cambiar su valor, al método set(). Si se sigue este protocolo, el widget siempre rastreará el valor de la variable, sin ser necesaria ninguna otra intervención.

Por ejemplo:

import tkinter as tk

class App(tk.Frame):
    def __init__(self, master):
        super().__init__(master)
        self.pack()

        self.entrythingy = tk.Entry()
        self.entrythingy.pack()

        # Create the application variable.
        self.contents = tk.StringVar()
        # Set it to some value.
        self.contents.set("this is a variable")
        # Tell the entry widget to watch this variable.
        self.entrythingy["textvariable"] = self.contents

        # Define a callback for when the user hits return.
        # It prints the current value of the variable.
        self.entrythingy.bind('<Key-Return>',
                             self.print_contents)

    def print_contents(self, event):
        print("Hi. The current entry content is:",
              self.contents.get())

root = tk.Tk()
myapp = App(root)
myapp.mainloop()

El gestor de ventanas

En Tk hay un comando útil, wm, para interactuar con el gestor de ventanas. Las opciones del comando wm le permiten controlar cosas como títulos, ubicación, iconos de ventana y similares. En tkinter, estos comandos se han implementado como métodos de la clase Wm. Los widgets de Toplevel son subclases de Wm, por lo que se puede llamar directamente a los métodos de Wm.

Para acceder a la ventana Toplevel que contiene un objeto gráfico dado, a menudo puede simplemente referirse al padre de este objeto gráfico. Por supuesto, si el objeto gráfico fue empaquetado dentro de un marco, el padre no representará la ventana de nivel superior. Para acceder a la ventana de nivel superior que contiene un objeto gráfico arbitrario, puede llamar al método _root() . Este método comienza con un subrayado para indicar que esta función es parte de la implementación y no de una interfaz a la funcionalidad Tk.

Aquí hay algunos ejemplos típicos:

import tkinter as tk

class App(tk.Frame):
    def __init__(self, master=None):
        super().__init__(master)
        self.pack()

# create the application
myapp = App()

#
# here are method calls to the window manager class
#
myapp.master.title("My Do-Nothing Application")
myapp.master.maxsize(1000, 400)

# start the program
myapp.mainloop()

Tipos de datos de opciones Tk

anchor

Los valores legales son los puntos de la brújula: "n", "ne", "e", "se", "s", "sw", "w", "nw", y también "center".

bitmap

Hay ocho nombres de bitmaps integrados: 'error', 'gray25', 'gray50', 'hourglass', 'info', 'questhead', 'question', 'warning'. Para especificar un nombre de archivo de mapa de bits de X, indique la ruta completa del archivo, precedida por una @, como en "@/usr/contrib/bitmap/gumby.bit".

boolean

Se puede pasar enteros 0 o 1 o las cadenas "yes" or "no".

callback

Esto es cualquier función de Python que no toma argumentos. Por ejemplo:

def print_it():
    print("hi there")
fred["command"] = print_it

color

Colors can be given as the names of X colors in the rgb.txt file, or as strings representing RGB values in 4 bit: "#RGB", 8 bit: "#RRGGBB", 12 bit: "#RRRGGGBBB", or 16 bit: "#RRRRGGGGBBBB" ranges, where R,G,B here represent any legal hex digit. See page 160 of Ousterhout’s book for details.

cursor

Los nombres estándar del cursor X de cursorfont.h se pueden usar sin el prefijo XC_. Por ejemplo, para obtener un cursor de mano (XC_hand2), use la cadena "hand2". También se puede especificar su propio mapa de bits y archivo de máscara. Ver página 179 del libro de Ousterhout.

distance

Las distancias de pantalla se pueden especificar tanto en píxeles como en distancias absolutas. Los píxeles se dan como números y las distancias absolutas como cadenas con el carácter final que indica unidades: c para centímetros, i para pulgadas, m para milímetros, p para puntos de impresora. Por ejemplo, 3.5 pulgadas se expresa como "3.5i".

font

Tk usa un formato de lista para los nombres de fuentes, como {courier 10 bold}. Los tamaños de fuente expresados en números positivos se miden en puntos, mientras que los tamaños con números negativos se miden en píxeles.

geometry

Es una cadena de caracteres del estilo widthxheight, donde el ancho y la altura se miden en píxeles para la mayoría de los widgets (en caracteres para widgets que muestran texto). Por ejemplo: fred["geometry"] = "200x100".

justify

Los valores legales son las cadenas de caracteres: "left", "center", "right", y "fill".

region

Es una cadena de caracteres con cuatro elementos delimitados por espacios, cada uno de ellos es una distancia legal (ver arriba). Por ejemplo: "2 3 4 5" , "3i 2i 4.5i 2i" y "3c 2c 4c 10.43c" son todas regiones legales.

relief

Determina cuál será el estilo de borde de un widget. Los valores legales son: "raised", "sunken", "flat", "groove", y "ridge".

scrollcommand

Este es casi siempre el método set() de algún widget de barra de desplazamiento, pero puede ser cualquier método de un widget que tome un solo argumento.

wrap

Debe ser uno de estos: "none", "char", o "word".

Enlaces y eventos

El método de enlace (binding) del comando del widget le permite observar ciertos eventos y hacer que la función de devolución de llamada se active cuando se produce ese tipo de evento. La forma del método de enlace es:

def bind(self, sequence, func, add=''):

donde:

sequence

es una cadena que denota el tipo de evento objetivo. Para obtener más información, consulte la página del manual de Bind y la página 201 del libro de John Ousterhout.

func

es una función de Python que toma un argumento y se llama cuando ocurre el evento. La instancia del evento se pasa como el argumento mencionado. (Las funciones implementadas de esta manera a menudo se llaman callbacks.)

add

es opcional, ya sea '' o '+'. Pasar una cadena de caracteres vacía indica que este enlace anulará cualquier otro enlace asociado con este evento. Pasar '+' agrega esta función a la lista de funciones vinculadas a este tipo de evento.

Por ejemplo:

def turn_red(self, event):
    event.widget["activeforeground"] = "red"

self.button.bind("<Enter>", self.turn_red)

Observe cómo se accede al campo del widget del evento en la devolución de llamada turn_red(). Este campo contiene el widget que capturó el evento de X. La siguiente tabla enumera los otros campos de eventos a los que puede acceder y cómo se indican en Tk, lo que puede ser útil cuando se hace referencia a las páginas del manual de Tk.

Tk

Campo evento de Tkinter

Tk

Campo evento de Tkinter

%f

focus

%A

char

%h

height

%E

send_event

%k

keycode

%K

keysym

%s

state

%N

keysym_num

%t

time

%T

type

%w

width

%W

widget

%x

x

%X

x_root

%y

y

%Y

y_root

El parámetro índice

Muchos widgets requieren que se pase un parámetro índice. Se utiliza para señalar ubicaciones específicas en el widget de texto, caracteres específicos en el widget de entrada, o elementos particulares en el widget de menú.

Índice de widget de entrada (índice, índice de vista, etc.)

El widget entrada tiene una opción para referirse a la posición de los caracteres del texto que se muestra. Puede acceder a estos puntos especiales en un widget de texto utilizando la siguiente función de tkinter:

Índice de widget de texto

La notación de índice del widget de texto es muy rica y se detalla mejor en las páginas del manual de Tk.

Índices de menú (menu.invoke(), menu.entryconfig(), etc.)

Algunas opciones y métodos para menús manipulan entradas de menú específicas. Cada vez que se necesita un índice de menú para una opción o un parámetro, se puede pasar:

un número entero que se refiere a la posición numérica de la entrada en el widget, contada desde arriba, comenzando con 0;

la cadena "active", que se refiere a la posición del menú que está actualmente debajo del cursor;

la cadena de caracteres "last" que se refiere al último elemento del menú;

Un número entero precedido por @, como en @6, donde el entero es interpretado como una coordenada y de píxeles en el sistema de coordenadas del menú;

la cadena de caracteres "none", que indica que no hay entrada de menú, usado frecuentemente con menu.activate() para desactivar todas las entradas; y, finalmente,

una cadena de texto cuyo patrón coincide con la etiqueta de la entrada del menú, tal como se explora desde la parte superior del menú hasta la parte inferior. Tenga en cuenta que este tipo de índice se considera después de todos los demás, lo que significa que las coincidencias para los elementos del menú etiquetados last, active, o none pueden interpretarse de hecho como los literales anteriores.

Imágenes

Se pueden crear imágenes de diferentes formatos a través de la correspondiente subclase de tkinter.Image:

BitmapImage para imágenes en formato XBM.

PhotoImage para imágenes en formatos PGM, PPM, GIF y PNG. Este último es compatible a partir de Tk 8.6.

Cualquier tipo de imagen se crea a través de la opción file o data (también hay otras opciones disponibles).

El objeto imagen se puede usar siempre que algún widget admita una opción de image (por ejemplo, etiquetas, botones, menús). En estos casos, Tk no mantendrá una referencia a la imagen. Cuando se elimina la última referencia de Python al objeto de imagen, los datos de la imagen también se eliminan, y Tk mostrará un cuadro vacío donde se utilizó la imagen.

Ver también

El paquete Pillow [http://python-pillow.org/] añade soporte para los formatos del tipo BMP, JPEG, TIFF, y WebP, entre otros.

Gestor de archivos

Tk permite registrar y anular el registro de una función de devolución de llamada que se llamará desde el mainloop de Tk cuando la E/S sea posible en un descriptor de archivo. Solo se puede registrar un controlador por descriptor de archivo. Código de ejemplo:

import tkinter
widget = tkinter.Tk()
mask = tkinter.READABLE | tkinter.WRITABLE
widget.tk.createfilehandler(file, mask, callback)
...
widget.tk.deletefilehandler(file)

Esta función no está disponible en Windows.

Dado que no se sabe cuántos bytes están disponibles para su lectura, no use métodos de BufferedIOBase o TextIOBase read() o readline(), ya que estos requieren leer un número predefinido de bytes. Para sockets, los métodos recv() o recvfrom() trabajan bien; para otros archivos, use lectura sin formato o os.read(file.fileno(), maxbytecount).

Widget.tk.createfilehandler(file, mask, func)

Registra la función callback gestor de archivos func. El argumento file puede ser un objeto con un método fileno() (como un archivo u objeto de socket), o un descriptor de archivo entero. El argumento mask es una combinación ORed de cualquiera de las tres constantes que siguen. La retrollamada se llama de la siguiente manera:

callback(file, mask)

Widget.tk.deletefilehandler(file)

Anula el registro de un gestor de archivos.

tkinter.READABLE

tkinter.WRITABLE

tkinter.EXCEPTION

Constantes utilizadas en los argumentos mask.

tkinter.colorchooser — Diálogo de elección de color

Código fuente: Lib/tkinter/colorchooser.py [https://github.com/python/cpython/tree/3.9/Lib/tkinter/colorchooser.py]

El módulo tkinter.colorchooser proporciona la clase Chooser como una interfaz para el diálogo del selector de color nativo. Chooser implementa una ventana de diálogo de elección de color modal. La clase Chooser hereda de la clase Dialog.

class tkinter.colorchooser.Chooser(master=None, **options)

tkinter.colorchooser.askcolor(color=None, **options)

Cree un cuadro de diálogo de elección de color. Una llamada a este método mostrará la ventana, esperará a que el usuario haga una selección y devolverá el color seleccionado (o None) a la persona que llama.

Ver también

Módulo tkinter.commondialog

Módulo de diálogo estándar de Tkinter

tkinter.font — Envoltorio de fuente Tkinter

Código fuente: Lib/tkinter/font.py [https://github.com/python/cpython/tree/3.9/Lib/tkinter/font.py]

El módulo tkinter.font proporciona la clase Font para crear y usar fuentes con nombre.

Los diferentes pesos e inclinaciones de la fuente son:

tkinter.font.NORMAL

tkinter.font.BOLD

tkinter.font.ITALIC

tkinter.font.ROMAN

class tkinter.font.Font(root=None, font=None, name=None, exists=False, **options)

La clase Font representa una fuente con nombre. Las instancias Font reciben nombres únicos y se pueden especificar por su configuración de familia, tamaño y estilo. Las fuentes con nombre son el método de Tk para crear e identificar fuentes como un solo objeto, en lugar de especificar una fuente por sus atributos con cada aparición.

argumentos:

font - tupla de especificador de fuente (familia, tamaño, opciones)

name - nombre de fuente único

exists - self apunta a la fuente con nombre existente si es verdadera

opciones de palabras clave adicionales (ignoradas si se especifica font):

family - familia de la fuente, es decir, Courier, Times

size - tamaño de fuente

Si size es positivo, se interpreta como tamaño en puntos.

Si size es un número negativo, se trata su valor absoluto

como tamaño en píxeles.

weight - énfasis de fuente (NORMAL, BOLD)

slant - ROMAN, ITALIC

underline - subrayado de fuente (0 - ninguno, 1 - subrayado)

overstrike - tachado de fuente (0 - ninguno, 1 - tachado)

actual(option=None, displayof=None)

Retorna los atributos de la fuente.

cget(option)

Recupera un atributo de la fuente.

config(**options)

Modifica los atributos de la fuente.

copy()

Retorna una nueva instancia de la fuente actual.

measure(text, displayof=None)

Retorna la cantidad de espacio que ocuparía el texto en la pantalla especificada cuando se formatee en la fuente actual. Si no se especifica ninguna pantalla, se asume la ventana principal de la aplicación.

metrics(*options, **kw)

Retorna datos específicos de la fuente. Las opciones incluyen:

ascent - distancia entre la línea de base y el punto más alto que un

el carácter de la fuente puede ocupar

descent - distancia entre la línea de base y el punto más bajo que un

el carácter de la fuente puede ocupar

linespace - separación vertical mínima necesaria entre dos

caracteres de la fuente que aseguran que no haya superposición vertical entre líneas.

fixed - 1 si la fuente es de ancho fijo en caso contrario 0

tkinter.font.families(root=None, displayof=None)

Retorna las diferentes familias de fuentes.

tkinter.font.names(root=None)

Retorna los nombres de las fuentes definidas.

tkinter.font.nametofont(name)

Retorna una representación Font de una fuente con nombre tk.

Diálogos Tkinter

tkinter.simpledialog —Diálogos de entrada estándar de Tkinter

Código fuente: Lib/tkinter/simpledialog.py [https://github.com/python/cpython/tree/3.9/Lib/tkinter/simpledialog.py]

El módulo tkinter.simpledialog contiene clases y funciones convenientes para crear diálogos modales simples para obtener un valor de entrada del usuario.

tkinter.simpledialog.askfloat(title, prompt, **kw)

tkinter.simpledialog.askinteger(title, prompt, **kw)

tkinter.simpledialog.askstring(title, prompt, **kw)

Las tres funciones anteriores proporcionan diálogos que piden al usuario que introduzca un valor del tipo deseado.

class tkinter.simpledialog.Dialog(parent, title=None)

La clase base para los diálogos personalizados.

body(master)

Sobrescribir para construir la interfaz del dialogo y retornar el widget que debe tener el foco inicial.

buttonbox()

El comportamiento por defecto añade los botones OK y Cancelar. Sobrescribir para diseños de botones personalizados.

Diálogos de selección de archivos

Código fuente: Lib/tkinter/filedialog.py [https://github.com/python/cpython/tree/3.9/Lib/tkinter/filedialog.py]

El módulo tkinter.filedialog proporciona clases y funciones de factoría para crear ventanas de selección de archivos/directorios.

Diálogos nativos de carga/guardado

Las siguientes clases y funciones proporcionan ventanas de diálogo de archivos que combinan un aspecto nativo con opciones de configuración para personalizar el comportamiento. Los siguientes argumentos son aplicables a las clases y funciones enumeradas a continuación:

parent - la ventana sobre la que se situará el diálogo

title - el título de la ventana

initialdir - el directorio en el que inicia el diálogo

initialfile - el archivo seleccionado al abrir el diálogo

filetypes - una secuencia de tuplas (label, pattern), se permite el comodín “*”

defaultextension - extensión por defecto para añadir al archivo (diálogos de guardado)

multiple - cuando es verdadero, se permite la selección de múltiples elementos

Funciones estáticas de factoría

Las siguientes funciones, al ser invocadas, crean un diálogo modal de aspecto nativo, esperan la selección del usuario y retornan el(los) valor(es) seleccionado(s) o Ninguno a la llamada.

tkinter.filedialog.askopenfile(mode="r", **options)

tkinter.filedialog.askopenfiles(mode="r", **options)

Las dos funciones anteriores crean un diálogo Open y retornan el( los) objeto(s) de archivo(s) abierto(s) en modo de sólo lectura.

tkinter.filedialog.asksaveasfile(mode="w", **options)

Crea un diálogo SaveAs y retorna un objeto de un archivo abierto en modo de sólo escritura.

tkinter.filedialog.askopenfilename(**options)

tkinter.filedialog.askopenfilenames(**options)

Las dos funciones anteriores crean un diálogo Open y retornan el( los) nombre(s) de archivo(s) seleccionado(s) que corresponde(n) a un(os) archivo(s) existente(s).

tkinter.filedialog.asksaveasfilename(**options)

Crea un diálogo SaveAs y retorna el nombre del archivo seleccionado.

tkinter.filedialog.askdirectory(**options)

Pide al usuario que seleccione un directorio.

Argumento opcional adicional:

mustexist - determina si la selección debe ser un directorio existente.

class tkinter.filedialog.Open(master=None, **options)

class tkinter.filedialog.SaveAs(master=None, **options)

Las dos clases anteriores proporcionan ventanas de diálogo nativas para guardar y cargar archivos.

Clases de conveniencia

Las siguientes clases se utilizan para crear ventanas de archivos/directorios desde cero. Estas no emulan el aspecto nativo de la plataforma.

class tkinter.filedialog.Directory(master=None, **options)

Crear un diálogo que solicite al usuario que seleccione un directorio.

Nota

La clase FileDialog debe ser subclasificada para el manejo de eventos y comportamiento personalizados.

class tkinter.filedialog.FileDialog(master, title=None)

Crear un diálogo básico de selección de archivos.

cancel_command(event=None)

Activa la terminación de la ventana de diálogo.

dirs_double_event(event)

Manejador de eventos para el evento de doble clic sobre un directorio.

dirs_select_event(event)

Manejador de eventos para el evento de clic sobre un directorio.

files_double_event(event)

Manejador de eventos para el evento de doble clic sobre un archivo.

files_select_event(event)

Manejador de eventos para el evento de un solo clic sobre un archivo.

filter_command(event=None)

Filtra los archivos por directorio.

get_filter()

Recupera el filtro de archivos que se está utilizando actualmente.

get_selection()

Recupera el elemento seleccionado actualmente.

go(dir_or_file=os.curdir, pattern="*", default="", key=None)

Renderiza el diálogo e inicia el bucle de eventos.

ok_event(event)

Salir del diálogo retornando la selección actual.

quit(how=None)

Salir del diálogo retornando el nombre del archivo, si lo hay.

set_filter(dir, pat)

Establece el filtro de archivos.

set_selection(file)

Actualiza la selección de archivos actual a archivo.

class tkinter.filedialog.LoadFileDialog(master, title=None)

Una subclase de FileDialog que crea una ventana de diálogo para seleccionar un archivo existente.

ok_command()

Comprueba que se proporciona un archivo y que la selección indica un archivo ya existente.

class tkinter.filedialog.SaveFileDialog(master, title=None)

Una subclase de FileDialog que crea una ventana de diálogo para seleccionar un archivo de destino.

ok_command()

Comprueba si la selección apunta a un archivo válido que no es un directorio. Se requiere confirmación si se selecciona un archivo ya existente.

tkinter.commondialog — Plantillas de ventanas de diálogo

Código fuente: Lib/tkinter/commondialog.py [https://github.com/python/cpython/tree/3.9/Lib/tkinter/commondialog.py]

El módulo tkinter.commondialog proporciona la clase Dialog que es la clase base para los diálogos definidos en otros módulos de soporte.

class tkinter.commondialog.Dialog(master=None, **options)

show(color=None, **options)

Renderiza la ventana de diálogo.

Ver también

Módulos tkinter.messagebox, Leyendo y escribiendo archivos

tkinter.messagebox — Indicadores de mensajes de Tkinter

Código fuente: Lib/tkinter/messagebox.py [https://github.com/python/cpython/tree/3.9/Lib/tkinter/messagebox.py]

El módulo tkinter.messagebox proporciona una clase base de plantilla, así como una variedad de métodos convenientes para configuraciones de uso común. Los cuadros de mensaje son modales y devolverán un subconjunto de (Verdadero, Falso, OK, Ninguno, Sí, No) según la selección del usuario. Los estilos y diseños de cuadros de mensajes comunes incluyen, entre otros:

class tkinter.messagebox.Message(master=None, **options)

Crea un cuadro de mensaje de información predeterminado.

Cuadro de mensaje de información

tkinter.messagebox.showinfo(title=None, message=None, **options)

Cuadros de mensaje de advertencia

tkinter.messagebox.showwarning(title=None, message=None, **options)

tkinter.messagebox.showerror(title=None, message=None, **options)

Cuadros de mensajes de preguntas

tkinter.messagebox.askquestion(title=None, message=None, **options)

tkinter.messagebox.askokcancel(title=None, message=None, **options)

tkinter.messagebox.askretrycancel(title=None, message=None, **options)

tkinter.messagebox.askyesno(title=None, message=None, **options)

tkinter.messagebox.askyesnocancel(title=None, message=None, **options)

tkinter.scrolledtext — Widget de texto desplazado

Código fuente: Lib/tkinter/scrolledtext.py [https://github.com/python/cpython/tree/3.9/Lib/tkinter/scrolledtext.py]

El módulo tkinter.scrolledtext proporciona una clase del mismo nombre que implementa un widget de texto básico que tiene una barra de desplazamiento vertical configurada para hacer «lo correcto». Usar la clase ScrolledText es mucho más fácil que configurar un widget de texto y una barra de desplazamiento directamente.

El widget de texto y la barra de desplazamiento se empaquetan juntos en un Frame, y los métodos de los administradores de geometría Grid y Pack se adquieren del objeto Frame. Esto permite que el widget ScrolledText sea usado directamente para lograr el funcionamiento más normal del administrador de geometría.

Si fuera necesario un control más específico, los siguientes atributos están disponibles:

class tkinter.scrolledtext.ScrolledText(master=None, **kw)

frame

El marco que rodea el texto y los widgets de la barra de desplazamiento.

vbar

El widget de la barra de desplazamiento.

tkinter.dnd — Soporte de arrastrar y soltar

Código fuente: Lib/tkinter/dnd.py [https://github.com/python/cpython/tree/3.9/Lib/tkinter/dnd.py]

Nota

Esto es experimental y quedará obsoleto cuando se sustituya por el Tk DND.

El módulo tkinter.dnd proporciona soporte para arrastrar y soltar objetos dentro de una sola aplicación, dentro de la misma ventana o entre ventanas. Para permitir que se arrastre un objeto, debe crear un enlace de evento para él que inicie el proceso de arrastrar y soltar. Por lo general, vincula un evento ButtonPress a una función de devolución de llamada que escribe (consulte Enlaces y eventos). La función debe llamar a dnd_start(), donde “fuente” es el objeto que se va a arrastrar y “evento” es el evento que invoca la llamada (el argumento de la función de devolución de llamada).

La selección de un objeto de destino ocurre de la siguiente manera:

Búsqueda de arriba hacia abajo del área debajo del mouse para el widget de destino

El widget de destino debe tener un atributo dnd_accept invocable

Si dnd_accept no está presente o devuelve None, la búsqueda se mueve al widget principal

Si no se encuentra ningún widget de destino, el objeto de destino es None

Llama a <old_target>.dnd_leave(source, event)

Llama a <new_target>.dnd_enter(source, event)

Llama a <target>.dnd_commit(source, event) para notificar la caída

Llama a <source>.dnd_end(target, event) para señalar el final de arrastrar y soltar

class tkinter.dnd.DndHandler(source, event)

La clase DndHandler maneja los eventos de arrastrar y soltar que rastrean los eventos Motion y ButtonRelease en la raíz del widget de eventos.

cancel(event=None)

Cancela el proceso de arrastrar y soltar.

finish(event, commit=0)

Ejecuta el fin de las funciones de arrastrar y soltar.

on_motion(event)

Inspecciona el área debajo del mouse en busca de objetos de destino mientras se realiza el arrastre.

on_release(event)

Señal de fin de arrastre cuando se activa el patrón de liberación.

tkinter.dnd.dnd_start(source, event)

Función de fábrica para el proceso de arrastrar y soltar.

Ver también

Enlaces y eventos

tkinter.ttk — Tk widgets temáticos

Código fuente: Lib/tkinter/ttk.py [https://github.com/python/cpython/tree/3.9/Lib/tkinter/ttk.py]

El módulo tkinter.ttk proporciona acceso al conjunto de widgets temáticos Tk, introducido en Tk 8.5. Si Python no se ha compilado con Tk 8.5, todavía se puede acceder a este módulo si se ha instalado Tile. El método anterior que utiliza Tk 8.5 proporciona ventajas adicionales, incluida la representación de fuentes suavizada en X11 y la transparencia de ventanas (requiere un administrador de ventanas de composición en X11).

La idea básica de tkinter.ttk es separar, en la medida de lo posible, el comportamiento de un widget del código que implementa su apariencia.

Ver también

Soporte para estilos de Widgets Tk [https://core.tcl.tk/tips/doc/trunk/tip/48.md]

Un documento que presenta apoyo temático para Tk

Uso de Ttk

Para empezar a utilizar Ttk, hay que importar su módulo:

from tkinter import ttk

Para anular los widgets Tk básicos, la importación debe seguir la importación de Tk:

from tkinter import *
from tkinter.ttk import *

Ese código hace que varios widgets tkinter.ttk (Button, Checkbutton, Entry, Frame, Label, LabelFrame, Menubutton, PanedWindow, Radiobutton, Scale y Scrollbar) reemplacen automáticamente los widgets Tk.

Esto tiene el beneficio de usar los nuevos widgets que dan una mejor apariencia en todas las plataformas; sin embargo, el reemplazo de widgets no es completamente compatible. La principal diferencia es que las opciones de widgets como «fg», «bg» y otras relacionadas con el estilo del widget ya no están presentes en los widgets de Ttk. En su lugar, utiliza la clase ttk.Style para mejorar los efectos de estilo.

Ver también

Conversión de aplicaciones existentes para usar widgets Tile [http://tktable.sourceforge.net/tile/doc/converting.txt]

Una monografía (utilizando la terminología Tcl) sobre las diferencias que normalmente se encuentran al modificar aplicaciones para usar los nuevos widgets.

Ttk widgets

Ttk viene con 18 widgets, doce de los cuales ya existían en tkinter: Button, Checkbutton, Entry, Frame, Label, LabelFrame, Menubutton, PanedWindow, Radiobutton, Scale, Scrollbar y Spinbox. Los otros seis son nuevos: Combobox, Notebook, Progressbar, Separator, Sizegrip y Treeview. Y todas ellas son subclases de Widget.

El uso de los widgets Ttk le da a la aplicación un aspecto mejorado. Como se ha mencionado anteriormente, hay diferencias en cómo se codifica el estilo.

Código Tk:

l1 = tkinter.Label(text="Test", fg="black", bg="white")
l2 = tkinter.Label(text="Test", fg="black", bg="white")

Código Ttk:

style = ttk.Style()
style.configure("BW.TLabel", foreground="black", background="white")

l1 = ttk.Label(text="Test", style="BW.TLabel")
l2 = ttk.Label(text="Test", style="BW.TLabel")

Para obtener más información acerca de TtkStyling, consulta la documentación de la clase Style.

Widget

ttk.Widget define las opciones y métodos estándar compatibles con los widgets temáticos de Tk y no se crea una instancia directamente.

Opciones estándar

Todos los widgets ttk aceptan las siguientes opciones:

Opción

Descripción

class

Especifica la clase de ventana. La clase se usa cuando se consulta la base de datos de opciones para las otras opciones de la ventana, para determinar las etiquetas de enlace (bindtags) predeterminadas para la ventana y para seleccionar el diseño y estilo predeterminados del widget. Esta opción es de solo lectura y solo se puede especificar cuando se crea la ventana.

cursor

Especifica el cursor del mouse que se utilizará para el widget. Si se establece en la cadena vacía (el valor predeterminado), el cursor se hereda para el widget principal.

takefocus

Determina si la ventana acepta el foco durante el recorrido del teclado. Se retorna 0, 1 o una cadena vacía. Si se retorna 0, significa que la ventana debe omitirse por completo durante el recorrido del teclado. Si es 1, significa que la ventana debe recibir el foco de entrada siempre que sea visible. Y una cadena vacía significa que los scripts transversales toman la decisión sobre si enfocarse o no en la ventana.

style

Se puede usar para especificar un estilo personalizado para el widget.

Opciones de widgets desplegables

Los widgets controlados por una barra deslizante presentan las siguientes opciones.

Opción

Descripción

xscrollcommand

Se usa para interactuar con las barras deslizantes horizontales.

Cuando la vista en la ventana del widget cambia, el widget generará un comando Tcl basado en el scrollcommand.

Por lo general, esta opción consiste en el método Scrollbar.set() de barras deslizantes. Esto hará que la barra deslizante se actualice cada vez que cambie la vista de la ventana.

yscrollcommand

Se utiliza para comunicarse con las barras deslizantes verticales. Para obtener más información, consulta más arriba.

Opciones de etiqueta

Las siguientes opciones son compatibles con etiquetas, botones y otros widgets similares a botones.

Opción

Descripción

text

Especifica una cadena de texto que se mostrará dentro del widget.

textvariable

Especifica un nombre cuyo valor se utilizará en lugar del recurso de opción de texto.

underline

Si se activa, especifica el índice (empezando por 0) de un carácter que se va a subrayar en la cadena de texto. El carácter subrayado se utiliza para la activación mnemotécnica.

image

Especifica una imagen que se va a mostrar. Es una lista de 1 o más elementos. El primer elemento es el nombre de imagen predeterminado. El resto de la lista es una secuencia de pares statespec/value según lo definido por Style.map(), especificando diferentes imágenes para usar cuando el widget está en un estado determinado o una combinación de estados. Todas las imágenes de la lista deben tener el mismo tamaño.

compound

Especifica cómo mostrar la imagen en relación con el texto, en el caso de que estén presentes las opciones de texto e imágenes. Los valores válidos son:

text: mostrar solo texto

image: mostrar solo la imagen

top, bottom, left, right: muestra la imagen por encima, por debajo, a la izquierda o a la derecha del texto, respectivamente.

none: valor predeterminado. Mostrar la imagen si está presente, de lo contrario el texto.

width

Si es mayor que cero, especifica cuánto espacio, en ancho de caracteres, se debe asignar para la etiqueta de texto; si es menor que cero, especifica un ancho mínimo. Si es cero o no se especifica, se utiliza el ancho natural de la etiqueta de texto.

Opciones de compatibilidad

Opción

Descripción

state

Se puede establecer en «normal» o «deshabilitado» para controlar el bit de estado «deshabilitado». Esta es una opción de solo escritura: establecerlo cambia el estado del widget, pero el método Widget.state() no afecta a esta opción.

Estados del widget

El estado del widget es un mapa de bits de indicadores de estado independientes.

Indicador de estado

Descripción

active

El puntero está sobre el widget y clickeando sobre él producirá alguna acción

disabled

El widget está desactivado bajo el control del programa

focus

El widget tiene el enfoque del teclado

pressed

El widget está siendo pulsado

selected

«On», «true» o «current» para aspectos como Checkbuttons y radiobuttons

background

Windows y Mac tienen el concepto de ventana «activa» o en primer plano. El estado background se establece para los widgets en una ventana de fondo y se borra para los que están en la ventana en primer plano

readonly

El widget no debe permitir la modificación del usuario

alternate

Un formato de visualización alternativo específico del widget

invalid

El valor del widget no es válido

Una especificación de estado es una secuencia de nombres de estado, opcionalmente prefijados con un signo de exclamación que indica que el bit está desactivado.

ttk.Widget

Además de los métodos descritos a continuación, el ttk.Widget soporta los métodos tkinter.Widget.cget() y tkinter.Widget.configure().

class tkinter.ttk.Widget

identify(x, y)

Retorna el nombre del elemento en la posición x y o la cadena vacía si el punto no se encuentra dentro de ningún elemento.

x e y son coordenadas en píxeles relativas al widget.

instate(statespec, callback=None, *args, **kw)

Prueba el estado del widget. Si no se especifica una retrollamada, retorna True si el estado del widget coincide con statespec y False en caso contrario. Si se especifica la retrollamada, se llama con argumentos (args) si el estado del widget coincide con statespec.

state(statespec=None)

Modifica o pregunta el estado del widget. Si se especifica statespec, establece el estado del widget según éste y retorna un nuevo statespec que indica qué indicadores se han cambiado. Si no se especifica statespec, retorna los indicadores de estado habilitados actualmente.

statespec es generalmente una lista o una tupla.

Combobox

El widget ttk.Combobox combina un campo de texto con una lista desplegable de valores. Este widget es una subclase de Entry.

Además de los métodos heredados de Widget: Widget.cget(), Widget.configure(), Widget.identify(), Widget.instate() y Widget.state(), y los siguientes heredados de Entry: Entry.bbox(), Entry.delete(), Entry.icursor(), Entry.index(), Entry.insert(), Entry.selection(), Entry.xview(), tiene algunos otros métodos, descritos en ttk.Combobox.

Opciones

Este widget acepta las siguientes opciones específicas:

Opción

Descripción

exportselection

Valor booleano. Si se establece, la selección del widget está vinculada a la selección del Administrador de ventanas (que se puede retornar invocando Misc.selection_get, por ejemplo).

justify

Especifica cómo el texto se alinea en el widget. Uno de «left», «center» o «right».

height

Especifica el largo/altura del cuadro de la lista desplegable, en filas.

postcommand

Un script (posiblemente registrado con Misc.register) que se llama inmediatamente antes de mostrar los valores. Puede especificar qué valores mostrar.

state

Uno de «normal», «readonly» o «disabled». En el estado «readonly» el valor no se puede editar directamente y el usuario solo puede seleccionar los valores de la lista desplegable. En el estado «normal» el campo de texto se puede editar directamente. En el estado «deshabilitado» no es posible ninguna interacción.

textvariable

Especifica un nombre cuyo valor está vinculado al valor del widget. Cada vez que cambia el valor asociado a ese nombre, se actualiza el valor del widget y viceversa. Véase tkinter.StringVar.

values

Especifica la lista de valores que se mostrarán en el cuadro de lista desplegable.

width

Especifica un valor entero que indica el ancho deseado de la ventana de entrada, en caracteres de tamaño medio de la fuente del widget.

Eventos virtuales

Los widgets de cuadro combinado generan un evento virtual <<ComboboxSelected>> cuando el usuario selecciona un elemento de la lista de valores.

ttk.Combobox

class tkinter.ttk.Combobox

current(newindex=None)

Si se especifica newindex, establece el valor del cuadro combinado en la posición del elemento newindex. De lo contrario, retorna el índice del valor actual o -1 si el valor actual no está en la lista de valores.

get()

Retorna el valor actual del cuadro combinado.

set(value)

Establece el valor del cuadro combinado a value.

Spinbox

El widget ttk.Spinbox es un ttk.Entry mejorado con flechas de incremento y decremento. Se puede utilizar para números o listas de valores de cadena. Este widget es una subclase de Entry.

Además de los métodos heredados de Widget: Widget.cget(), Widget.configure(), Widget.identify(), Widget.instate() y Widget.state(), y los siguientes heredados de Entry: Entry.bbox(), Entry.delete(), Entry.icursor(), Entry.index(), Entry.insert(), Entry.xview(), tiene algunos otros métodos, descritos en ttk.Spinbox.

Opciones

Este widget acepta las siguientes opciones específicas:

Opción

Descripción

from

Valor flotante. Si se establece, este es el valor mínimo al que se reducirá el botón de disminución. Debe escribirse como from_ cuando se usa como argumento, ya que from es una palabra clave de Python.

to

Valor flotante. Si se establece, este es el valor máximo al que se incrementará el botón de incremento.

increment

Valor flotante. Especifica la cantidad por la cual los botones de incremento/disminución cambian el valor. Por defecto la cantidad es de 1.0.

values

Secuencia de valores de cadena o flotantes. Si se especifica, los botones de incremento/disminución recorrerán los elementos de esta secuencia en lugar de incrementar o disminuir los números.

wrap

Valor booleano. Si es True, los botones de incremento y disminución pasarán del valor to al valor from o del valor from al valor to, respectivamente.

format

Valor de cadena. Especifica el formato de los números establecidos por los botones de incremento/disminución. Debe tener la forma «%W.Pf», donde W es el ancho de relleno del valor, P es la precisión, y “%” y “f” son literales.

command

Python invocable. Se llamará sin argumentos cada vez que se presione alguno de los botones de incremento o disminución.

Eventos virtuales

El widget spinbox genera un evento virtual <<Increment>> cuando el usuario presiona <Up>, y un evento virtual <<Decrement>> cuando el usuario presiona <Down>.

ttk.Spinbox

class tkinter.ttk.Spinbox

get()

Retorna el valor actual del spinbox.

set(value)

Establece el valor del spinbox a value.

Notebook

El widget Ttk Notebook administra una colección de ventanas y muestra una sola a la vez. Cada ventana secundaria está asociada a una pestaña, que el usuario puede seleccionar para cambiar la ventana que se muestra actualmente.

Opciones

Este widget acepta las siguientes opciones específicas:

Opción

Descripción

height

Si está presente y es mayor que cero, especifica la altura deseada del área del panel (sin incluir el relleno interno o las pestañas). De lo contrario, se utiliza la altura máxima de todos los paneles.

padding

Especifica la cantidad de espacio adicional que se va a agregar alrededor del exterior del bloc de notas. El relleno es una lista de hasta cuatro especificaciones de longitud izquierda superior derecha inferior. Si se especifican menos de cuatro elementos, el valor predeterminado inferior es el superior, el valor predeterminado de la derecha es el de la izquierda y el valor predeterminado superior es el de la izquierda.

width

Si está presente y es mayor que cero, especifica el ancho deseado del área del panel (sin incluir el relleno interno). De lo contrario, se utiliza el ancho máximo de todos los paneles.

Opciones de pestañas

Las opciones específicas para pestañas son:

Opción

Descripción

state

O bien «normal», «disabled» o «hidden». Si es «disabled», la pestaña no se puede seleccionar. Si es «hidden», la pestaña no se muestra.

sticky

Especifica cómo se coloca la ventana secundaria dentro del área del panel. Value es una cadena que contiene cero o más de los caracteres «n», «s», «e» o «w». Cada letra se refiere a un lado (norte, sur, este u oeste) al que se pegará la ventana secundaria, según el administrador de geometría grid().

padding

Especifica la cantidad de espacio adicional que se va a agregar entre el notebook y este panel. La sintaxis es la misma que para el relleno de opciones utilizado por Notebook.

text

Especifica un texto que se muestra en la pestaña.

image

Especifica una imagen que se muestra en la pestaña. Consulta la opción de imagen descrita en Widget.

compound

Especifica cómo mostrar la imagen en relación con el texto, en el caso de que tanto el texto como la imagen estén presentes. Consulta Label Options para obtener valores válidos.

underline

Especifica el índice (basado en 0) de un carácter que se va a subrayar en la cadena de texto. El carácter subrayado se utiliza para la activación mnemotécnica si se llama a Notebook.enable_traversal().

Identificadores de pestañas

El tab_id presente en varios métodos de ttk.Notebook puede tener cualquiera de las siguientes formas:

Un entero entre cero y el número de pestañas

El nombre de una ventana secundaria

Un especificación de posición de la forma «@x,y» que identifique la pestaña

El valor «current» que identifica la pestaña seleccionada actualmente

El valor «end» que retorna el número de pestañas (válido solo para Notebook.index())

Eventos virtuales

Este widget genera un evento virtual <<NotebookTabChanged>> después de seleccionar una nueva pestaña.

ttk.Notebook

class tkinter.ttk.Notebook

add(child, **kw)

Añade una nueva pestaña al notebook.

Si la ventana está actualmente administrada por el notebook pero oculta, se restaura a su posición anterior.

Consulta Tab Options para la lista de opciones disponibles.

forget(tab_id)

Quita la pestaña especificada por tab_id, desasigna y quita la ventana asociada.

hide(tab_id)

Oculta la pestaña especificada por tab_id.

La pestaña no se mostrará, pero la ventana asociada permanece administrada por el notebook y se recordará su configuración. Las pestañas ocultas se pueden restaurar con el comando add().

identify(x, y)

Retorna el nombre del elemento de la pestaña en la posición x, y o cadena vacía si no hay ninguno.

index(tab_id)

Retorna el índice numérico de la pestaña especificada por tab_id, o el número total de pestañas si tab_id es la cadena «end».

insert(pos, child, **kw)

Añade un panel en la posición especificada.

pos es la cadena «end», un índice entero o el nombre de un elemento secundario administrado. Si el bloc de notas ya administra child, lo mueve a la posición especificada.

Consulta Tab Options para la lista de opciones disponibles.

select(tab_id=None)

Selecciona el tab_id especificado.

Se mostrará la ventana secundaria asociada y la ventana previamente seleccionada (si es diferente) no se debe asignar. Si se omite tab_id, retorna el nombre del widget del panel seleccionado actualmente.

tab(tab_id, option=None, **kw)

Consultar o modificar las opciones del tab_id específico.

Si no se proporciona kw, retorna un diccionario de los valores de las opciones de pestañas. Si se especifica option, retorna el valor de esa option. De lo contrario, establece las opciones en los valores correspondientes.

tabs()

Retorna una lista de ventanas administradas por el notebook.

enable_traversal()

Habilita la tabulación para una ventana de nivel superior que contenga este notebook.

Esto extenderá los enlaces para la ventana de nivel superior que contiene el notebook del siguiente modo:

Control-Tab: selecciona la pestaña siguiente a la seleccionada actualmente.

Shift-Control-Tab: selecciona la pestaña precedente a la seleccionada actualmente.

Alt-K: donde K es el carácter mnemotécnico (subrayado) de cualquier pestaña, seleccionará esa pestaña.

Se pueden habilitar varios notebooks en un único nivel superior para la tabulación, incluidos los notebooks anidados. Sin embargo, la tabulación entre notebooks solo funciona correctamente si todos los paneles tienen el notebook en el que se encuentran como maestro.

Progressbar

El widget ttk.Progressbar muestra el estado de una operación de larga duración. Puede funcionar en dos modos: 1) el modo determinado que muestra la cantidad completada en función de la cantidad total de trabajo a realizar y 2) el modo indeterminado que proporciona una pantalla animada para que el usuario sepa que la operación está en curso.

Opciones

Este widget acepta las siguientes opciones específicas:

Opción

Descripción

orient

Puede ser «horizontal» o «vertical». Especifica la orientación de la barra de progreso.

length

Especifica la longitud del eje largo de la barra de progreso (ancho si horizontal, alto si es vertical).

mode

Puede ser «determinate» o «indeterminate».

maximum

Número que especifica el valor máximo. Por defecto el valor es 100.

value

El valor actual de la barra de progreso. En el modo «determinado», representa la cantidad de trabajo completado. En el modo «indeterminado», se interpreta como módulo maximum, es decir, la barra de progreso completa un «ciclo» cuando su valor aumenta en maximum.

variable

Nombre vinculado al valor de la opción. Si se especifica, el valor de la barra de progreso se establece automáticamente en el valor de este nombre cada vez que se modifica dicho valor.

phase

Variable de solo lectura. El widget incrementa periódicamente el valor de esta opción siempre que su valor sea mayor que 0 y, en modo determinado, menor que el máximo. Esta opción puede ser utilizada por el tema actual para proporcionar efectos de animación adicionales.

ttk.Progressbar

class tkinter.ttk.Progressbar

start(interval=None)

Inicia el modo de incremento automático: programa un evento timer periódico que llama a Progressbar.step() cada interval milisegundos. Si se omite, interval tiene como valor predeterminado 50 milisegundos.

step(amount=None)

Incrementa el valor de la barra de progreso en amount.

amount vale 1.0 por defecto si se omite.

stop()

Para el modo de incremento automático: cancela cualquier evento timer periódico iniciado por Progressbar.start() para la barra de progreso en cuestión.

Separator

El widget ttk.Separator muestra una barra de separación horizontal o vertical.

No tiene otros métodos aparte de aquellos heredados de ttk.Widget.

Opciones

Este widget acepta las opción específica siguiente:

Opción

Descripción

orient

Puede ser «horizontal» o «vertical». Especifica la orientación del separador.

Sizegrip

El widget ttk.Sizegrip (también conocido como grow box) permite al usuario cambiar el tamaño de la ventana de nivel superior que lo contiene presionando y arrastrando la esquina.

Este widget no tiene ni opciones ni métodos específicos, aparte de aquellos heredados de ttk.Widget.

Notas específicas por plataforma

On macOS, toplevel windows automatically include a built-in size grip by default. Adding a Sizegrip is harmless, since the built-in grip will just mask the widget.

Errores detectados

Si la posición del nivel superior que lo contiene se especifica en relación con la parte derecha o inferior de la pantalla (por ejemplo,…), el widget Sizegrip no cambiará el tamaño de la ventana.

El widget solo soporta el cambio de tamaño desde la esquina inferior derecha.

Treeview

El widget ttk.Treeview muestra una colección en árbol de elementos. Cada elemento tiene una etiqueta textual, una imagen opcional y una lista opcional de valores de datos. Los valores de datos se muestran en columnas sucesivas después de la etiqueta de árbol.

El orden en que se muestran los valores de datos se puede controlar estableciendo la opción de widget displaycolumns. El Treeview también puede mostrar encabezados. Se puede acceder a las columnas por número o nombres simbólicos enumerados en las columnas de opciones del widget. Consulte Column Identifiers.

Cada elemento se identifica con un nombre único. El widget genera IDs para los elementos si no se proporcionan en la declaración. Hay un elemento raíz distinguido, denominado {}. El elemento raíz en sí no se muestra; sus hijos aparecen en el nivel superior de la jerarquía.

Cada elemento también tiene una lista de etiquetas que se pueden usar para asociar enlaces de eventos con elementos individuales y controlar la apariencia del elemento.

El widget Treeview admite el deslizamiento horizontal y vertical, según las opciones descritas en Scrollable Widget Options y los métodos Treeview.xview() y Treeview.yview().

Opciones

Este widget acepta las siguientes opciones específicas:

Opción

Descripción

columns

Una lista de identificadores de columna, que especifican el número de columnas y sus nombres.

displaycolumns

Una lista de identificadores de columna (índices simbólicos o enteros) que especifican qué columnas de datos se muestran y el orden en que aparecen, o la cadena «#all».

height

Especifica el número de filas que deben estar visibles. Nota: el ancho solicitado se determina a partir de la suma de los anchos de columna.

padding

Especifica el relleno interno del widget. El relleno es una lista de hasta cuatro especificaciones de longitud.

selectmode

Controla cómo los enlaces de clase integrados administran la selección. Puede ser «extended», «browse» o «none». Si se establece en «extended» (valor predeterminado), se pueden seleccionar varios elementos. Si se elige «browse», se seleccionará un solo elemento a la vez. Si se elige «none», la selección no se cambiará.

Tenga en cuenta que el código de la aplicación y los enlaces de etiqueta pueden establecer la selección como deseen, independientemente del valor de esta opción.

show

Una lista que contiene cero o más de los siguientes valores, especificando qué elementos del árbol se van a mostrar.

tree: muestra las etiquetas del árbol en la columna #0.

headings: muestra la fila de encabezado.

El valor predeterminado es «tree headings», es decir, mostrar todos los elementos.

Nota: la columna #0 siempre hace referencia a la columna del árbol, incluso si no se especifica show=»tree».

Opciones de elementos

Las siguientes opciones de elemento se pueden especificar para los elementos de los comandos de inserción y de elementos del widget.

Opción

Descripción

text

La etiqueta textual que se va a mostrar para el elemento.

image

Una imagen Tk, que se muestra a la izquierda de la etiqueta.

values

La lista de valores asociados al elemento.

Cada elemento debe tener el mismo número de valores que las columnas de opciones del widget. Si hay menos valores que columnas, los valores restantes se asumen vacíos. Si hay más valores que columnas, se omiten los valores adicionales.

open

Valor True/False que indica si los elementos secundarios deben mostrarse u ocultarse.

tags

La lista de etiquetas asociadas al elemento.

Opciones de etiqueta

Se pueden especificar las opciones siguientes para etiquetas:

Opción

Descripción

foreground

Especifica el color de primer plano del texto.

background

Especifica el color de fondo de la celda o elemento.

font

Especifica la fuente que se utilizará al añadir texto.

image

Especifica la imagen del elemento, en caso de que la opción de imagen del elemento esté vacía.

Identificadores de columna

Los identificadores de columna toman cualquiera de los siguientes formas:

Un nombre simbólico de la lista de opciones de columna.

Un entero n, especificando la enésima columna de datos.

Una cadena de la forma #n, donde n es un entero, especificando la enésima columna mostrada.

Notas:

Los valores de opciones del elemento se pueden mostrar en un orden diferente al orden en el que se almacenan.

La columna #0 siempre hace referencia a la columna del árbol, incluso si no se especifica show=»tree».

Un número de columna de datos es un índice en la lista de valores de opciones de un elemento; el número de columna se visualiza en el árbol donde se muestran los valores. Las etiquetas de árbol se muestran en la columna #0. Si no se establece la opción displaycolumns, la columna de datos n se muestra en la columna #n+1. Una vez más, la columna #0 siempre hace referencia a la columna del árbol.

Eventos virtuales

El widget Treeview genera los siguientes eventos virtuales.

Evento

Descripción

<<TreeviewSelect>>

Se genera cada vez que cambia la selección.

<<TreeviewOpen>>

Generado justo antes configurar el elemento de resalto a open=True.

<<TreeviewClose>>

Generado justo después de establecer el elemento de resalto a open=False.

Los métodos Treeview.focus() y Treeview.selection() se pueden utilizar para determinar el elemento o elementos afectados.

ttk.Treeview

class tkinter.ttk.Treeview

bbox(item, column=None)

Retorna el cuadro delimitador (en relación con la ventana del widget de Treeview) del item especificado con el formato (x, y, ancho, alto).

Si se especifica column, retorna el cuadro delimitador de esa celda. Si el item no está visible (es decir, si es descendiente de un elemento cerrado o se desplaza fuera de la pantalla), retorna una cadena vacía.

get_children(item=None)

Retorna la lista de elementos secundarios que pertenecen a item.

Si no se especifica item, retorna la raíz.

set_children(item, *newchildren)

Reemplaza el elemento secundario de item por newchildren.

Los elementos secundarios presentes en item que no están presentes en newchildren se separan del árbol. Ningún elemento de newchildren puede ser un antecesor de item. Tenga en cuenta que si no se especifica newchildren se desasocian los elementos secundarios de item.

column(column, option=None, **kw)

Consultar o modificar las opciones para la columna especificada.

Si no se proporciona kw, retorna un diccionario de los valores de opciones de columna. Si se especifica option, se retorna el valor de esa option. De lo contrario, establece las opciones en los valores correspondientes.

Las opciones/valores válidos son:

id

Retorna el nombre de la columna. Esta es una opción de solo lectura.

ancla: Uno de los valores de ancla Tk estándar.

Especifica cómo se debe alinear el texto de esta columna con respecto a la celda.

minwidth: width

El ancho mínimo de la columna en píxeles. El widget Treeview no hará que la columna sea más pequeña de lo especificado por esta opción cuando se cambie el tamaño del widget o el usuario arrastre una columna.

stretch: True/False

Especifica si el ancho de la columna debe ajustarse cuando se cambia el tamaño del widget.

width: ancho

El ancho de la columna en píxeles.

Se puede establecer column = «#0» para configurar el árbol de la columna.

delete(*items)

Elimina todos los items especificados y todos sus descendientes.

El elemento raíz no se elimina.

detach(*items)

Desvincula todos los items especificados del árbol.

Los objetos y todos sus descendientes todavía existen, y pueden ser reinsertados en otro punto del árbol, pero no se mostrarán.

El elemento raíz no se desvincula.

exists(item)

Retorna True si el item especificado está presente en el árbol.

focus(item=None)

Si se especifica item, establece el elemento de foco en item. De lo contrario, retorna el elemento de foco actual o “” si no hay ninguno.

heading(column, option=None, **kw)

Consulta o modifica las opciones de encabezado para la column especificada.

Si no se proporciona kw, retorna un diccionario de los valores de opciones de encabezado. Si se especifica option, se retorna el valor de esa option. De lo contrario, establece las opciones en los valores correspondientes.

Las opciones/valores válidos son:

text: texto

El texto se muestra en el encabezado de la columna.

image: imageName

Especifica una imagen para mostrar en la parte derecha del encabezado de la columna.

anchor: ancla

Especifica el alineamiento del texto del encabezado. Es uno de los valores estándar de Tk anchor.

command: callback

Una retrollamada que se ejecutará cuando se presione la etiqueta de encabezado.

Se especifica column =»#0» para configurar el encabezado de la columna de árbol.

identify(component, x, y)

Retorna una descripción del component especificado bajo el punto dado por x e y, o la cadena vacía si no existe dicho component en esa posición.

identify_row(y)

Retorna el identificador del elemento en la posición y.

identify_column(x)

Retorna el identificador de los datos de columna de la celda en la posición x.

La columna del árbol tiene ID #0.

identify_region(x, y)

Retorna uno de:

zona

significado

heading

Zona de encabezado del árbol.

separator

Espacio entre dos encabezados de columna.

tree

La zona del árbol.

cell

Datos de celda.

Disponibilidad: Tk 8.6.

identify_element(x, y)

Retorna el elemento en la posición x, y.

Disponibilidad: Tk 8.6.

index(item)

Retorna el índice entero de item dentro de la lista de elementos secundarios de su elemento primario.

insert(parent, index, iid=None, **kw)

Crea un nuevo elemento y retorna el identificador del elemento recién creado.

parent es el identificador del elemento primario o la cadena vacía para crear un nuevo elemento de nivel superior. index es un entero, o el valor «end», especificando dónde insertar el nuevo elemento en la lista de elementos secundarios del elemento primario. Si index es menor o igual que cero, el nuevo nodo se inserta al principio; si index es mayor o igual que el número actual de elementos secundarios, se inserta al final. Si se especifica iid, se utiliza como identificador de elemento; iid no debe existir en el árbol previamente. De lo contrario, se genera un nuevo identificador único.

Consulte Item Options para obtener la lista de puntos disponibles.

item(item, option=None, **kw)

Consulta o modifica las opciones para el item especificado.

Si no se proporciona ninguna opción, se retorna un diccionario con opciones/valores para el elemento. Si se especifica option, se retorna el valor de esa opción. De lo contrario, establece las opciones en los valores correspondientes según kw.

move(item, parent, index)

Mueve item a la posición index en la lista de elementos secundarios de parent.

No se permite mover un elemento bajo uno de sus descendientes. Si index es menor o igual que cero, item se mueve al principio; si es mayor o igual que el número de hijos, se mueve hasta el final. Si item se desvincula, se vuelve a conectar.

next(item)

Retorna el identificador del siguiente elemento de item, o “” si item es el último elemento secundario de su elemento primario.

parent(item)

Retorna el identificador del elemento primario de item o “” si item está en el nivel superior de la jerarquía.

prev(item)

Retorna el identificador del elemento anterior de item, o “” si item es el primer elemento secundario de su elemento primario.

reattach(item, parent, index)

Un alias para Treeview.move().

see(item)

Garantiza que item está visible.

Establece todas las opciones modificables de los antecesores de item a True y desplaza el widget si es necesario para que item esté dentro de la parte visible del árbol.

selection()

Retorna una tupla de los elementos seleccionados.

Distinto en la versión 3.8: selection() ya no toma argumentos. Para cambiar el estado de selección, utiliza los siguientes métodos de selección.

selection_set(*items)

items se convierte en la nueva selección.

Distinto en la versión 3.6: items se pueden pasar como argumentos separados, no solo como una sola tupla.

selection_add(*items)

Añade items a la selección.

Distinto en la versión 3.6: items se pueden pasar como argumentos separados, no solo como una sola tupla.

selection_remove(*items)

Elimina elementos de la selección.

Distinto en la versión 3.6: items se pueden pasar como argumentos separados, no solo como una sola tupla.

selection_toggle(*items)

Alterna el estado de selección de cada elemento en items.

Distinto en la versión 3.6: items se pueden pasar como argumentos separados, no solo como una sola tupla.

set(item, column=None, value=None)

Con un argumento, retorna un diccionario de pares columna/valor para el item especificado. Con dos argumentos, retorna el valor actual de la columna especificada. Con tres argumentos, establece el valor de determinado column en un item determinado en el value especificado.

tag_bind(tagname, sequence=None, callback=None)

Enlaza una retrollamada para el evento sequence a la etiqueta tagname. Cuando se entrega un evento a un elemento, se llama a las retrollamadas de cada una de las etiquetas del elemento.

tag_configure(tagname, option=None, **kw)

Consulta o modifica las opciones para el tagname especificado.

Si no se proporciona kw, retorna un diccionario de la configuración de opciones para tagname. Si se especifica option, retorna el valor de esa option para el tagname especificado. De lo contrario, establece las opciones en los valores correspondientes para el tagname dado.

tag_has(tagname, item=None)

Si se especifica item, retorna 1 o 0 dependiendo de si el item tiene el tagname especificado. De lo contrario, retorna una lista de todos los elementos que tienen la etiqueta especificada.

Disponibilidad: Tk 8.6

xview(*args)

Consulta o modifica la posición horizontal de la vista de árbol.

yview(*args)

Consulta o modifica la posición vertical de la vista de árbol.

Ttk Styling

A cada widget en ttk se le asigna un estilo, que especifica el conjunto de elementos que componen el widget y cómo se organizan, junto con la configuración dinámica y predeterminada para las opciones de elemento. De forma predeterminada, el nombre del estilo es el mismo que el nombre de clase del widget, pero puede ser reemplazado por la opción de estilo del widget. Si no conoces el nombre de clase de un widget, utiliza el método Misc.winfo_class() (somewidget.winfo_class()).

Ver también

Presentación de la conferencia Tcl’2004 [http://tktable.sourceforge.net/tile/tile-tcl2004.pdf]

Este documento explica cómo funciona el motor de temas

class tkinter.ttk.Style

Esta clase se utiliza para manipular la base de datos de estilos.

configure(style, query_opt=None, **kw)

Consulta o establece el valor predeterminado de las opciones especificadas en style.

Cada clave en kw es una opción y cada valor es una cadena que identifica el valor de esa opción.

Por ejemplo, para cambiar cualquier botón por defecto a un botón plano con borde interno y un color de fondo distinto:

from tkinter import ttk
import tkinter

root = tkinter.Tk()

ttk.Style().configure("TButton", padding=6, relief="flat",
   background="#ccc")

btn = ttk.Button(text="Sample")
btn.pack()

root.mainloop()

map(style, query_opt=None, **kw)

Consulta o establece valores dinámicos de opciones específicas en style.

Cada clave en kw es una opción y cada valor es una lista o tupla (generalmente) que contiene statespecs agrupados en tuplas, listas o alguna otra preferencia. Una statespec es un compuesto de uno o más estados y un valor.

Un ejemplo puede hacerlo más comprensible:

import tkinter
from tkinter import ttk

root = tkinter.Tk()

style = ttk.Style()
style.map("C.TButton",
    foreground=[('pressed', 'red'), ('active', 'blue')],
    background=[('pressed', '!disabled', 'black'), ('active', 'white')]
    )

colored_btn = ttk.Button(text="Test", style="C.TButton").pack()

root.mainloop()

Ten en cuenta que el orden de las secuencias (estado, valor) para una opción es importante, si se cambia el orden a [('active', 'blue'), ('pressed', 'red')] en la opción en primer plano, por ejemplo, el resultado sería un primer plano azul cuando el widget se encuentre en los estados active o pressed.

lookup(style, option, state=None, default=None)

Retorna el valor especificado para option en style.

Si state se especifica, se espera que sea una secuencia de uno o más estados. Si se establece el argumento default, se usa como valor de reserva en caso de que no se especifique una opción.

Para verificar qué fuente usa un Button por defecto:

from tkinter import ttk

print(ttk.Style().lookup("TButton", "font"))

layout(style, layoutspec=None)

Define el diseño del widget para un estilo dado. Si se omite layoutspec, retorna la especificación de diseño para un estilo determinado.

layoutspec, si se especifica, se espera que sea una lista o algún otro tipo de secuencia (excluyendo cadenas), donde cada elemento debe ser una tupla y el primer elemento es el nombre de diseño y el segundo elemento debe tener el formato descrito en Layouts.

Para entender el formato, consulta el siguiente ejemplo (no está pensado para hacer nada útil):

from tkinter import ttk
import tkinter

root = tkinter.Tk()

style = ttk.Style()
style.layout("TMenubutton", [
   ("Menubutton.background", None),
   ("Menubutton.button", {"children":
       [("Menubutton.focus", {"children":
           [("Menubutton.padding", {"children":
               [("Menubutton.label", {"side": "left", "expand": 1})]
           })]
       })]
   }),
])

mbtn = ttk.Menubutton(text='Text')
mbtn.pack()
root.mainloop()

element_create(elementname, etype, *args, **kw)

Crea un nuevo elemento en el tema actual, del etype dado, que se espera que sea «image», «from» o «vsapi». Este último solo está disponible en Tk 8.6a para Windows XP y Vista y no se describe aquí.

Si se utiliza «image», args debe contener el nombre de imagen predeterminado seguido de pares statespec/value (esta es imagespec), y kw puede tener las siguientes opciones:

border=padding

el relleno interno es una lista de hasta cuatro enteros, especificando los bordes izquierdo, superior, derecho e inferior, respectivamente.

height=height

Especifica una altura mínima para el elemento. Si es menor que cero, la altura de la imagen base se utiliza como valor predeterminado.

padding=padding

Especifica el relleno interior del elemento. El valor predeterminado es el valor del borde si no se especifica.

sticky=spec

Especifica cómo se coloca la imagen dentro de la sección. spec contiene cero o más caracteres «n», «s», «w» o «e».

width=width

Especifica un ancho mínimo para el elemento. Si es menor que cero, el ancho de la imagen base se utiliza como valor predeterminado.

Si se utiliza «from» como valor de etype, element_create() clonará un elemento existente. args contiene un themename, desde el que se clonará el elemento y, opcionalmente, un elemento desde el que clonar. Si no se especifica este elemento para clonar, se usará un elemento vacío. kw se descarta.

element_names()

Retorna la lista de elementos definidos en le tema actual.

element_options(elementname)

Retorna la lista de opciones de elementname.

theme_create(themename, parent=None, settings=None)

Crea un tema nuevo.

Es un error si themename ya existe. Si se especifica parent, el nuevo tema heredará estilos, elementos y diseños del tema primario. Si se especifica settings, se espera que tengan la misma sintaxis utilizada para theme_settings().

theme_settings(themename, settings)

Establece temporalmente el tema actual en themename, aplica los settings especificados y, a continuación, restaura el tema anterior.

Cada clave en settings es un estilo y cada valor puede contener las teclas “configure”, “map”, “layout” y “element create” y se espera que tengan el mismo formato especificado por los métodos Style.configure(), Style.map(), Style.layout() y Style.element_create() respectivamente.

Como ejemplo, vamos a cambiar un poco el Combobox por el tema predeterminado:

from tkinter import ttk
import tkinter

root = tkinter.Tk()

style = ttk.Style()
style.theme_settings("default", {
   "TCombobox": {
       "configure": {"padding": 5},
       "map": {
           "background": [("active", "green2"),
                          ("!disabled", "green4")],
           "fieldbackground": [("!disabled", "green3")],
           "foreground": [("focus", "OliveDrab1"),
                          ("!disabled", "OliveDrab2")]
       }
   }
})

combo = ttk.Combobox().pack()

root.mainloop()

theme_names()

Retorna una lista de temas conocidos.

theme_use(themename=None)

Si no se proporciona themename, retorna el tema en uso. De lo contrario, establece el tema actual en themename, actualiza todos los widgets y emite un evento <<ThemeChanged>>.

Diseños

Un diseño puede ser simplemente None, si no tiene opciones, o un diccionario de opciones que especifica cómo organizar el elemento. El mecanismo de diseño utiliza una versión simplificada del paquete de gestión de geometría: dada una cavidad inicial, a cada elemento se le asigna una sección. Las opciones/valores válidos son:

side: whichside

Especifica en qué lado de la cavidad colocar el elemento; sea arriba, derecha, abajo o izquierda. Si se omite, el elemento ocupa toda la cavidad.

sticky: nswe

Especifica dónde se coloca el elemento dentro de su sección asignada.

unit: 0 or 1

Si se establece en 1, hace que el elemento y todos sus descendientes sean tratados como un único elemento en métodos como Widget.identify() y otros. Se utiliza para cosas como los thumbs de la barra de desplazamiento.

children: [sublayout… ]

Especifica una lista de elementos para colocar dentro del elemento. Cada elemento es una tupla (u otro tipo de secuencia) donde el primer elemento es el nombre de diseño y el otro es un Layout.

tkinter.tix — Ampliación de widgets para Tk

Código fuente: Lib/tkinter/tix.py [https://github.com/python/cpython/tree/3.9/Lib/tkinter/tix.py]

Obsoleto desde la versión 3.6: Esta ampliación de Tk no está mantenida y no debe ser usada en nuevo código. Use tkinter.ttk en su lugar.

El módulo tkinter.tix (Tk Interface Extension en inglés) proporciona un conjunto abundante de widgets adicionales. Aunque la biblioteca estándar Tk tiene muchos widgets útiles, están lejos de ser completos. La biblioteca tkinter.tix proporciona la mayoría de los widgets comúnmente necesarios que no están en el estándar Tk: HList, ComboBox, Control (alias SpinBox) y una selección de widgets desplazables. tkinter.tix también incluye muchos más widgets que son generalmente útiles en un rango amplio de aplicaciones: NoteBook, FileEntry, PanedWindow, etc; hay más de 40 de ellos.

Con todos estos nuevos widgets, puedes introducir nuevas técnicas de interacción en aplicaciones, creando interfaces de usuario más útiles y más intuitivas. Puedes diseñar tu aplicación al escoger los widgets más apropiados que combinen con las necesidades especiales de tu aplicación y usuarios.

Ver también

Tix Homepage [http://tix.sourceforge.net/]

La página de inicio de Tix. Incluye enlaces a documentación adicional y descargas.

Tix Man Pages [http://tix.sourceforge.net/dist/current/man/]

Versión en línea de las páginas del manual y material de referencia.

Tix Programming Guide [http://tix.sourceforge.net/dist/current/docs/tix-book/tix.book.html]

Versión en línea del material de referencia del programador.

Tix Development Applications [http://tix.sourceforge.net/Tixapps/src/Tide.html]

Aplicaciones de Tix para el desarrollo de programas de Tix y Tkinter. Las aplicaciones de Tide (por Tix Integrated Development Environment en sus siglas de inglés) trabajan bajo Tk o Tkinter, e incluyen TixInspect, un inspector para modificar y depurar aplicaciones Tix/Tk/Tkinter remotamente.

Usando Tix

class tkinter.tix.Tk(screenName=None, baseName=None, className='Tix')

Un widget de alto nivel de Tix que representa generalmente la ventana principal de una aplicación. Tiene un intérprete Tcl asociado.

Las clases en el módulo tkinter.tix heredan de la clases en tkinter. El primero importa el segundo, por lo que para usar tkinter.tix con Tkinter, todo lo que necesitas hacer es importar un módulo. En general, puedes importar tkinter.tix, y reemplazar las invocaciones de alto nivel a tkinter.Tk con tix.Tk:

from tkinter import tix
from tkinter.constants import *
root = tix.Tk()

Para usar tkinter.tix, debes tener los widgets Tix instalados, usualmente junto a tu instalación de los widgets Tk. Para probar tu instalación, intenta lo siguiente:

from tkinter import tix
root = tix.Tk()
root.tk.eval('package require Tix')

Widgets de Tix

Tix [http://tix.sourceforge.net/dist/current/man/html/TixCmd/TixIntro.htm] introduce más de 40 clases de widget al repertorio de tkinter.

Widgets Básicos

class tkinter.tix.Balloon

Un Globo [http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixBalloon.htm] que aparece sobre un widget para proporcionar ayuda. Cuando el usuario mueve el cursor dentro de un widget al cual el widget Globo está ligado, una pequeña ventana emergente con un mensaje descriptivo se mostrará en la pantalla.

class tkinter.tix.ButtonBox

El widget ButtonBox [http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixButtonBox.htm] crea una caja de botones, tal como es comúnmente usado para Ok Cancelar.

class tkinter.tix.ComboBox

El widget ComboBox [http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixComboBox.htm] es similar al control de caja de selección combinada en MS Windows. El usuario puede seleccionar una opción escribiendo en el subwidget de entrada o seleccionando de la caja de lista del subwidget.

class tkinter.tix.Control

El widget Control [http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixControl.htm] es también conocido como el widget SpinBox. El usuario puede ajustar el valor al presionar los dos botones de flecha o al ingresar el valor directamente en la entrada. El nuevo valor será comparado con los límites superiores e inferiores definidos por el usuario.

class tkinter.tix.LabelEntry

El widget LabelEntry [http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixLabelEntry.htm] empaqueta un widget de entrada y una etiqueta en un mega widget. Puede ser usado para simplificar la creación de los tipos de interfaz de «formularios de entrada».

class tkinter.tix.LabelFrame

El widget LabelFrame [http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixLabelFrame.htm] empaqueta un widget frame y una etiqueta en un mega widget. Para crear widgets dentro de un widget LabelFrame, uno crea los nuevos widgets relativos al subwidget frame y los gestiona dentro del subwidget frame.

class tkinter.tix.Meter

El widget Meter [http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixMeter.htm] puede ser usado para mostrar el progreso de un trabajo en segundo plano que puede tomar un largo tiempo de ejecución.

class tkinter.tix.OptionMenu

El widget OptionMenu [http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixOptionMenu.htm] crea un botón de menú de opciones.

class tkinter.tix.PopupMenu

El widget PopupMenu [http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixPopupMenu.htm] puede ser usado como un reemplazo del comando tk_popup. La ventaja del widget PopupMenu de Tix es que requiere menos código de aplicación para manipular.

class tkinter.tix.Select

El widget Select [http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixSelect.htm] es un contenedor de subwidgets botón. Puede ser usado para proporcionar opciones de selección de estilos radio-box o check-box para el usuario.

class tkinter.tix.StdButtonBox

El widget StdButtonBox [http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixStdButtonBox.htm] es un grupo de botones estándares para cajas de diálogo similares a Motif.

Selectores de Archivos

class tkinter.tix.DirList

El widget DirList [http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirList.htm] muestra una vista de lista de un directorio, sus directorios previos, y sus sub-directorios. El usuario puede mostrar uno de los directorios mostrados en la lista o cambiar a otro directorio.

class tkinter.tix.DirTree

El widget DirTree [http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirTree.htm] muestra una vista de árbol de un directorio, sus directorios previos y sus sub-directorios. El usuario puede escoger uno de los directorios mostrados en la lista o cambiar a otro directorio.

class tkinter.tix.DirSelectDialog

El widget DirSelectDialog [http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirSelectDialog.htm] presenta los directorios en el sistema de archivos en una ventana de diálogo. El usuario puede usar esta ventana de diálogo para navegar a través del sistema de archivos para seleccionar el directorio deseado.

class tkinter.tix.DirSelectBox

El widget DirSelectBox es similar al cuadro de selección de directorio estándar de Motif(TM). Es generalmente usado para que el usuario escoja un directorio. DirSelectBox guarda los directorios seleccionados recientemente en un widget de cuadro combinado para que puedan ser seleccionados rápidamente de nuevo.

class tkinter.tix.ExFileSelectBox

El widget ExFileSelectBox [http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixExFileSelectBox.htm] es usualmente embebido en un widget tixExFileSelectDialog. Proporciona un método conveniente para que el usuario seleccione archivos. El estilo del widget ExFileSelectBox es muy similar al diálogo de archivo estándar en MS Windows 3.1.

class tkinter.tix.FileSelectBox

El widget FileSelectBox [http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixFileSelectBox.htm] es similar al cuadro de selección de archivo estándar de Motif(TM). Es generalmente usado para que el usuario escoja un archivo. FileSelectBox guarda los archivos recientemente seleccionados en un widget ComboBox para que puedan ser rápidamente seleccionados de nuevo.

class tkinter.tix.FileEntry

El widget FileEntry [http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixFileEntry.htm] puede ser usado para ingresar un nombre de archivo. El usuario puede tipear el nombre de archivo manualmente. Alternativamente, el usuario puede presionar el widget de botón que está al lado de la entrada, que mostrará un diálogo de selección de archivo.

ListBox jerárquico

class tkinter.tix.HList

El widget HList [http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixHList.htm] puede ser usado para mostrar cualquier dato que tenga una estructura jerárquica, por ejemplo, árboles del directorio del sistema de archivos. Las entradas de las líneas son sangradas y conectadas por líneas de ramas de acuerdo a sus lugares en la jerarquía.

class tkinter.tix.CheckList

El widget CheckList [http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixCheckList.htm] muestra una lista de objetos a ser seleccionados por el usuario. CheckList actúa de forma similar a los widget Tk checkbutton o radiobutton, excepto que es capaz de manejar muchos más objetos que los widgets checkbutton o radiobutton.

class tkinter.tix.Tree

Se puede usar el widget Tree [http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixTree.htm] para mostrar datos jerárquicos en una forma de árbol. El usuario puede ajustar la vista del árbol al abrir o cerrar partes del árbol.

ListBox Tabular

class tkinter.tix.TList

Se puede usar el widget TList [http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixTList.htm] para mostrar datos en un formato tabular. Las entradas de lista de un widget TList son similares a las entradas del widget listbox. Las principales diferencias son (1) el widget TList puede mostrar las entradas de la lista en un formato de dos dimensiones y (2) puedes usar imágenes gráficas así como también como múltiples colores y fuentes para las entradas de lista.

Gestores de Widgets

class tkinter.tix.PanedWindow

El widget PanedWindow [http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixPanedWindow.htm] permite que el usuario manipule interactivamente los tamaños de varios paneles. Los paneles pueden ser ordenados o verticalmente u horizontalmente. El usuario cambia los tamaños de los paneles al arrastrar el asa de redimensionamiento entre dos paneles.

class tkinter.tix.ListNoteBook

El widget ListNoteBook [http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixListNoteBook.htm] es muy similar al widget TixNoteBook: puede ser usado para mostrar muchas ventanas en un espacio limitado usando la metáfora del cuaderno (notebook). El cuaderno es dividido en una pila de páginas (ventanas). Sólo una de estas páginas se muestra a la vez. El usuario puede navegar a través de estas páginas al escoger el nombre de la página deseada en el subwidget hlist.

class tkinter.tix.NoteBook

Se puede usar el widget NoteBook [http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixNoteBook.htm] para mostrar muchas ventanas en un espacio limitado usando la metáfora del cuaderno (notebook). El notebook es dividido en una pila de páginas. Sólo una de estas páginas se puede mostrar a la vez. El usuario puede navegar a través de estas páginas al escoger las «pestañas» visuales arriba del widget NoteBook.

Tipos de Imágenes

El módulo tkinter.tix añade:

capacidades de pixmap [http://tix.sourceforge.net/dist/current/man/html/TixCmd/pixmap.htm] a todos los widgets de tkinter.tix y tkinter para crear imágenes de color a partir de archivos XPM.

se pueden usar los tipos de imágenes Compound [http://tix.sourceforge.net/dist/current/man/html/TixCmd/compound.htm] para crear imágenes que consisten en múltiples líneas horizontales; cada línea es compuesta de una serie de objetos (texto, bitmaps, imágenes, o espacios) ordenados de izquierda a derecha. Por ejemplo, una imagen compuesta puede ser usada para mostrar un bitmap y una cadena de texto simultáneamente en un widget Tk Button.

Widgets Varios

class tkinter.tix.InputOnly

Los widgets InputOnly [http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixInputOnly.htm] van a aceptar entradas del usuario, que pueden ser realizadas con el comando bind (sólo para Unix).

Gestor de Geometría de Formulario

Además, tkinter.tix mejora a tkinter al proporcionar:

class tkinter.tix.Form

El gestor de geometría de Formulario [http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixForm.htm] basado en reglas de anexo para todos los widgets Tk.

Comandos Tix

class tkinter.tix.tixCommand

Los comandos tix [http://tix.sourceforge.net/dist/current/man/html/TixCmd/tix.htm] proporcionan acceso a elementos misceláneos del estado interno de Tix y del contexto de la aplicación de Tix. La mayoría de la información manipulada por estos métodos le pertenece a la aplicación en conjunto, o a una pantalla o monitor, en vez de una ventana en particular.

Para ver las configuraciones actuales, el uso común es:

from tkinter import tix
root = tix.Tk()
print(root.tix_configure())

tixCommand.tix_configure(cnf=None, **kw)

Consulta o modifica las opciones de configuración del contexto de la aplicación Tix. Si no se especifica ninguna opción, retorna un diccionario con todas las opciones disponibles. Si la opción es especificada sin ningún valor, entonces el método retorna una lista describiendo la opción nombrada (esta lista será idéntica a la sublista correspondiente de los valores retornados si no se especifica ninguna opción). Si uno o más pares opción-valor son especificados, entonces el método modifica las opciones dadas para tener los valores dados; en este caso el método retorna una cadena de caracteres vacía. La opción puede ser cualquiera de las opciones de configuración.

tixCommand.tix_cget(option)

Retorna el valor actual de la opción de configuración dada por option. La opción puede ser cualquiera de las opciones configurables.

tixCommand.tix_getbitmap(name)

Localiza un archivo bitmap con el nombre name.xpm o name en uno de los directorios bitmap (véase el método tix_addbitmapdir()). Al usar tix_getbitmap(), puedes evitar codificar directamente los nombres de ruta de los archivos bitmap en tu aplicación. Cuando tiene éxito, retorna el nombre de ruta completo del archivo bitmap, prefijado con el carácter @. El valor retornado puede ser usado para configurar la opción bitmap de los widgets de Tk y Tix.

tixCommand.tix_addbitmapdir(directory)

Tix mantiene una lista de directorios bajo los cuales los métodos tix_getimage() y tix_getbitmap() buscarán archivos de imágenes. El directorio de bitmap estándar es $TIX_LIBRARY/bitmaps. El método tix_addbitmapdir() añade directory a la lista. Al usar este método, los archivos de imagen de una aplicación pueden ser localizados usando el método tix_getimage() o tix_getbitmap().

tixCommand.tix_filedialog([dlgclass])

Retorna el diálogo de selección de archivo que puede ser compartido entre diferentes invocaciones de esta aplicación. Este método creará una widget de diálogo de selección de archivos cuando es invocado la primera vez. Este diálogo será retornado por las subsiguientes invocaciones de tix_filedialog(). Un parámetro dlgclass opcional puede ser pasado como cadena para especificar qué tipo de widget de selección de diálogo es deseado. Las opciones posibles son tix, FileSelectDialog, o tixExFileSelectDialog.

tixCommand.tix_getimage(self, name)

Localiza un archivo de imagen con el nombre name.xpm, name.xbm o name.ppm en uno de los directorios de bitmap (véase el método tix_addbitmapdir() arriba). Si existe más de un archivo con el mismo nombre (pero con diferentes extensiones), entonces el tipo de imagen es escogido de acuerdo a la profundidad del monitor X: las imágenes xbm son escogidas en monitores monocromos e imágenes de color son escogidas en monitores de color. Al usar tex_getimage(), puedes evitar codificar de forma directa los nombres de ruta de los archivos de imagen en tu aplicación. Cuando tiene éxito, este método retorna el nombre de la imagen recién creada, que puede ser usada para configurar la opción image de los widgets Tk y Tix.

tixCommand.tix_option_get(name)

Obtiene las opciones mantenidas por el mecanismo de esquema de Tix.

tixCommand.tix_resetoptions(newScheme, newFontSet[, newScmPrio])

Reinicia el esquema y conjunto de fuentes de la aplicación Tix a newScheme y newFontSet, respectivamente. Afecta sólo a los widgets creados después de esta invocación. Por lo tanto, es mejor invocar al método resetoptions antes de la creación de cualquier widget en una aplicación Tix.

Se le puede dar el parámetro opcional newScmPrio para reiniciar el nivel de prioridad de las opciones de Tk definidas por los esquemas de Tix.

Debido a la manera en que Tk gestiona la opción de la base de datos X, después de que Tix se haya importado e inicializado, no es posible reiniciar el esquema de colores y conjunto de fuentes usando el método tix_config() método. En vez de eso, se debe usar el método tix_resetoptions().

IDLE

Código fuente: Lib/idlelib/ [https://github.com/python/cpython/tree/3.9/Lib/idlelib/]

IDLE es el entorno de desarrollo integrado de Python.

IDLE tiene las siguientes características:

escrito 100% en Python puro, usando el kit de herramientas GUI tkinter

multiplataforma: funciona en su mayoría igual en Windows, Unix y macOS

La ventana del shell de Python (interprete interactivo) con coloreado de código de entrada, salida y mensajes de error

editor de texto multiventana con deshacer múltiple, coloreación Python, indentado inteligente, sugerencias de llamadas a funciones, autocompletado y otras características

búsqueda dentro de cualquier ventana, reemplazo dentro de las ventanas del editor, y búsqueda a través de múltiples archivos (grep)

depurador con breakpoints persistentes, por pasos y visualización de espacios de nombres globales y locales

configuración, navegadores y otros cuadros de diálogo

Menús

IDLE tiene dos tipos de ventana principales, la ventana del shell y la ventana del editor. Es posible tener múltiples ventanas de edición simultáneamente. En Windows y Linux, cada una tiene su propio menú principal. Cada menú documentado abajo indica con cuál tipo de ventana está asociada esta.

Las ventanas de salida, como las que se usan para Editar => Encontrar en archivos, son un subtipo de la ventana de edición. Actualmente tienen el mismo menú principal pero un título predeterminado y un menú contextual diferente.

En macOS, hay un menú de aplicación. Este cambia dinámicamente de acuerdo la ventana actualmente seleccionada. Tiene un menú IDLE y algunas de las entradas descritas a continuación se mueven de acuerdo con las pautas de Apple.

Menú de archivo (Shell y Editor)

Nuevo archivo

Crea una nueva ventana de edición de archivos.

Abrir…

Abre un archivo existente con un cuadro de dialogo para abrir.

Archivos recientes

Abre una lista de archivos recientes. Haga click en alguno para abrirlo.

Abrir módulo…

Abre un módulo existente (buscar en sys.path).

Navegador de clases

Muestra las funciones, clases y métodos en estructura de árbol en el archivo actual del Editor. En el shell, primero abra un módulo.

Navegador de ruta

Muestra directorios, módulos, funciones, clases y métodos de sys.path en una estructura de árbol.

Guardar

Guarda la ventana actual en el archivo asociado, si existe alguno. Las ventanas que han sido modificadas desde que se abrieron o se guardaron por última vez tienen un * antes y después del título de la ventana. Si no hay un archivo asociado, ejecute Guardar como en su lugar.

Guardar Como…

Guarda la ventana actual con un cuadro de diálogo Guardar como. El archivo guardado se convierte en el nuevo archivo asociado para esta ventana.

Guardar copia como…

Guarda la ventana actual en un archivo diferente sin cambiar el archivo asociado.

Imprimir ventana

Imprime la ventana actual en la impresora predeterminada.

Close Window

Close the current window (if an unsaved editor, ask to save; if an unsaved Shell, ask to quit execution). Calling exit() or close() in the Shell window also closes Shell. If this is the only window, also exit IDLE.

Exit IDLE

Close all windows and quit IDLE (ask to save unsaved edit windows).

Menú editar (Shell y Editor)

Deshacer

Deshace el último cambio a la ventana actual. Se puede deshacer un máximo de 1000 cambios.

Rehacer

Vuelve a aplicar el último cambio deshecho a la ventana actual.

Cortar

Copia la selección en el portapapeles global; después elimina la selección.

Copiar

Copia la selección en el portapapeles global.

Pegar

Inserta el contenido del portapapeles global en la ventana actual.

Las funciones del portapapeles también están disponibles en los menús contextuales.

Seleccionar todo

Selecciona el contenido completo de la ventana actual.

Encontrar…

Abre un cuadro de diálogo de búsqueda con muchas opciones

Buscar de nuevo

Repite la última búsqueda, si hay alguna.

Encontrar selección

Busca la cadena de caracteres seleccionada actualmente, si hay alguna.

Encontrar en Archivos…

Abre un cuadro de diálogo de búsqueda de archivos. Presenta los resultados en una nueva ventana de salida.

Reemplazar…

Abre un cuadro de diálogo de búsqueda y reemplazo.

Ir a la línea

Mueve el cursor al inicio de la línea solicitada y hace que esa línea sea visible. Una solicitud a partir del final del archivo lo lleva al final. Borra cualquier selección y actualiza el estado de la línea y la columna.

Mostrar complementos

Open a scrollable list allowing selection of existing names. See Completions in the Editing and navigation section below.

Expandir palabra

Completa un prefijo que se ha escrito para que coincida con una palabra completa en la misma ventana; intente nuevamente para obtener un complemento diferente.

Mostrar sugerencias de llamada

Después de un paréntesis abierto para una función, abre una pequeña ventana con sugerencias sobre parámetros de función. Consultar Sugerencias de llamada en la sección Edición y navegación a continuación.

Mostrar los paréntesis alrededor

Resalta los paréntesis.

Menú de formato (solo ventana del Editor)

Zona de indentación

Desplaza las líneas seleccionadas a la derecha en un nivel de indentación (por defecto 4 espacios).

Zona de deindentación

Desplaza las líneas seleccionadas hacia la izquierda en un nivel de indentación (por defecto 4 espacios).

Zona comentada

Inserta ## delante de las líneas seleccionadas.

Zona descomentada

Elimina los # o ## al inicio de las líneas seleccionadas.

Zona tabulada

Transforma los tramos de espacios iniciales en tabs. (Nota: Recomendamos usar 4 bloques de espacio para indentar el código de Python).

Zona destabulada

Transforma todos los tabs en el número correcto de espacios.

Alternar tabs

Abre un cuadro de diálogo para cambiar entre indentado con espacios y tabs.

Nuevo tamaño de indentación

Abre un cuadro de diálogo para cambiar el tamaño de indentación. El valor predeterminado aceptado por la comunidad de Python es de 4 espacios.

Formatear párrafo

Reformatea el párrafo actual delimitado por líneas en blanco en un bloque de comentarios o una cadena de caracteres multilínea o una línea seleccionada en una cadena de caracteres. Todas las líneas en el párrafo estarán formateadas con menos de N columnas, donde N por defecto es 72.

Remover espacios en blanco al final

Elimina el espacio final en la línea y otros caracteres de espacio en blanco después del último carácter que no sea un espacio en blanco aplicando str.rstrip a cada línea, incluyendo las líneas dentro de cadenas de caracteres multilíneas. Excepto para las ventanas de consola, elimina nuevas líneas adicionales al final del archivo.

Menú ejecutar (solo ventana Editor)

Módulo ejecutar

Hace lo que dice en Verificar módulo. Si no hay errores, reinicia el shell para limpiar el entorno, luego ejecuta el módulo. La salida es mostrada en la ventana de shell. Tener en cuenta que la visualización requiere el uso de print o write. Cuando finaliza la ejecución, el shell permanece activo y muestra un mensaje. En este punto, se puede explorar interactivamente el resultado de la ejecución. Esto es similar a ejecutar un archivo con python -i file en una línea de comando.

Ejecutar… Personalizado

Igual que Módulo ejecutar, pero ejecuta el módulo con parámetros personalizados. Los argumentos de la línea de comandos extienden sys.argv como si se pasaran por una línea de comando. El módulo se puede ejecutar en el shell sin reiniciar.

Verificar módulo

Comprueba la sintaxis del módulo actualmente abierto en la ventana de edición. Si el módulo no ha sido guardado IDLE solicitará al usuario que guarde o guarde automáticamente, como se seleccionó en la pestaña General del cuadro de diálogo Configuración de inactividad. Si hay algún error de sintaxis, la ubicación aproximada será indicada en la ventana del Editor.

Shell de Python

Abrir o activar la ventana del shell de Python.

Menú de shell (solo ventana de shell)

Ver el último reinicio

Navega la ventana del shell hasta el último reinicio del mismo.

Reiniciar shell

Restart the shell to clean the environment and reset display and exception handling.

Historial anterior

Recorre los comandos anteriores en el historial que coinciden con la entrada actual.

Historial siguiente

Recorre los comandos posteriores en el historial que coinciden con la entrada actual.

Ejecución de interrupción

Detiene un programa en ejecución.

Menú de depuración (solo ventana de shell)

Ir al Archivo/Línea

Busca en la línea actual, con el cursor y la línea de arriba para un nombre de archivo y número de línea. Si lo encuentra, abre el archivo si aún no está abierto y muestra la línea. Usa esto para ver las líneas de origen referenciadas en un rastreo de excepción y las líneas encontradas por Buscar en archivos. También disponible en el menú contextual de la ventana del shell y las ventanas de salida.

Depurador (alternar)

Cuando esta función está habilitada, el código ingresado en el shell o ejecutado desde el editor se ejecutará con el depurador. En el editor, los breakpoints se pueden establecer con el menú contextual. Esta funcionalidad aún está incompleta y es en cierto modo experimental.

Visualizador de pila

Muestra el seguimiento de la pila de la última excepción en un complemento de árbol, con acceso a locales y globales.

Auto-abrir visualizador de pila

Activa/desactiva automáticamente el visualizador de pila en una excepción no controlada.

Menú de opciones (Shell y editor)

Configurar IDLE

Abre un cuadro de diálogo de configuración y cambia las preferencias por lo siguiente: fuentes, indentación, combinaciones de teclas, temas de color de texto, ventanas y tamaño de inicio, fuentes de ayuda adicionales y extensiones. En macOS, abre el cuadro de diálogo de configuración seleccionando Preferencias en el menú de la aplicación. Para obtener más detalles, consultar Configurar preferencias en Ayuda y preferencias.

La mayoría de los ajustes de configuración se aplican a todas las ventanas, abiertas o no. Los siguientes elementos de opción se aplican solo a la ventana activa.

Mostrar/Ocultar el contexto del código (solo ventana del Editor)

Abre un panel en la parte superior de la ventana de edición el cual muestra el contexto de bloque de código que se ha desplazado sobre la parte superior de la ventana. Consultar Contexto de código en la sección Edición y Navegación a continuación.

Mostrar/Ocultar números de línea (solo ventana del Editor)

Abre una columna a la izquierda de la ventana de edición que muestra el número de cada línea de texto. El valor por defecto de esta característica es desactivado, este puede modificarse en las preferencias (consultar Configuración de preferencias).

Ampliar/Restaurar altura

Alterna la ventana entre el tamaño normal y la altura máxima. El tamaño inicial predeterminado es 40 líneas por 80 caracteres a menos que se cambie en la pestaña General del cuadro de diálogo Configurar IDLE. La altura máxima para una pantalla es determinada maximizando momentáneamente una ventana la primera vez que se acerca la pantalla. Cambiar la configuración de la pantalla puede invalidar la altura guardada. Este alternado no tiene efecto cuando se maximiza una ventana.

Menú de ventana (shell y editor)

Enumera los nombres de todas las ventanas abiertas; seleccione uno para ponerlo en primer plano (deiconificándolo si es necesario).

Menú de ayuda (shell y editor)

Acerca de IDLE

Muestra la versión, derechos de autor, licencia, créditos y más.

Ayuda de IDLE

Muestra este documento IDLE, que detalla las opciones del menú, edición y navegación básica y otros consejos.

Documentación de Python

Accede a la documentación local de Python, si está instalada, o inicia un navegador web y abre docs.python.org mostrando la última documentación de Python.

Demostración Turtle

Ejecuta el módulo turtledemo con ejemplos de código Python y dibujos de tortugas.

Se pueden agregar fuentes de ayuda adicionales aquí con el cuadro de diálogo Configurar IDLE en la pestaña General. Consultar la subsección Fuentes de ayuda a continuación para obtener más información sobre las opciones del menú Ayuda.

Menús contextuales

Se abre un menú contextual haciendo click derecho en una ventana (Control-click en macOS). Los menús contextuales tienen las funciones estándar del portapapeles también en el menú Editar.

Cortar

Copia la selección en el portapapeles global; después elimina la selección.

Copiar

Copia la selección en el portapapeles global.

Pegar

Inserta el contenido del portapapeles global en la ventana actual.

Las ventanas del editor también tienen funciones de breakpoint. Las líneas con un conjunto de breakpoints están especialmente marcadas. Los breakpoints solo tienen efecto cuando se ejecutan bajo el depurador. Los breakpoints para un archivo se guardan en el directorio .idlerc del usuario.

Establecer breakpoint

Establecer un breakpoint en la línea actual.

Eliminar breakpoint

Eliminar el breakpoint en esa línea.

Las ventanas de shell y de salida también tienen los siguientes elementos.

Ir a archivo/línea

Hace lo mismo que el menú depurar.

La ventana de shell también tiene una función de squeezing de salida explicada en la subsección ventana de shell de Python a continuación.

Exprimir

Si el cursor está sobre una línea de salida, comprime toda la salida entre el código de arriba y el mensaje de abajo hasta la etiqueta “Texto squeezed”.

Edición y navegación

Ventana del editor

IDLE puede abrir ventanas del editor cuando se inicia, dependiendo de la configuración y de cómo inicies el IDLE. A partir de ahí, usar el menú Archivo. Solo puede haber una ventana de editor abierta para un archivo determinado.

La barra de título contiene el nombre del archivo, la ruta completa y la versión de Python e IDLE que ejecuta la ventana. La barra de estado contiene el número de línea (“Ln”) y el número de columna (“Col”). Los números de línea comienzan con 1; los números de columna con 0.

El IDLE supone que los archivos con una extensión .py* conocida contienen código Python y que los otros archivos no. Ejecuta el código Python con el menú Ejecutar.

Atajos de teclado

En esta sección, “C” hace referencia a la tecla Control en Windows y Unix y la tecla Command en macOS.

Backspace borra hacia la izquierda; Del borra hacia la derecha

C-Backspace borra la palabra a la izquierda; C-Del borra la palabra a la derecha

Las teclas con flechas y Page Up/Page Down para moverse alrededor

C-LeftArrow y C-RightArrow para moverse por palabras

Home/End para ir al inicio/fin de la línea

C-Home/C-End para ir al inicio/fin del archivo

Algunos atajos útiles de Emacs son heredados de Tcl / Tk:

C-a al inicio de la línea

C-e al final de la línea

C-k corta la línea (pero no la pone en el portapapeles)

C-l centra la ventana alrededor del punto de inserción

C-b retrocede un carácter sin eliminarlo (generalmente también se puede usar la tecla de cursor para esto)

C-f avanza un carácter sin eliminarlo (generalmente también se puede usar la tecla de cursor para esto)

C-p sube una línea (generalmente también se puede usar la tecla del cursor para esto)

C-d borra el siguiente carácter

Las combinaciones de teclas estándar (como C-c para copiar y C-v para pegar) pueden funcionar. Las combinaciones de teclas se seleccionan en el cuadro de diálogo Configurar IDLE.

Indentación automática

Después de una declaración de apertura de bloque, la siguiente línea está indentada por 4 espacios (en la ventana del shell de Python por un tab). Después de ciertas palabras clave (saltar, retornar, etc.), la siguiente línea se deindenta. En la indentación principal, Backspace elimina hasta 4 espacios si están allí. Tab inserta espacios (en la ventana del shell de Python un tab), el número depende del tamaño de la indentación. Actualmente, los tabs están restringidos a cuatro espacios debido a las limitaciones de Tcl/Tk.

Consulte también los comandos de zona de indexación/deindentación en Menú de formato.

Terminaciones

Cuando se solicitan y están disponibles, se suministran complementos para los nombres de los módulos, los atributos de las clases o las funciones, o los nombres de los archivos. Cada método de solicitud muestra un cuadro para completar con los nombres existentes. (Para cualquier cuadro, cambie el nombre que se está completando y el elemento resaltado en el cuadro escribiendo y borrando caracteres; pulsando las teclas Up, Down, PageUp, PageDown, Home, y End; y con un solo clic dentro del cuadro. Cierra la caja con las teclas Escape, Enter y doble Tab o con clics fuera de la caja. Un doble clic dentro de la caja selecciona y cierra.

Una forma de abrir una caja es escribir un carácter clave y esperar un intervalo predefinido. Este intervalo es por defecto de 2 segundos; se puede modificar en el diálogo de configuración. (Para evitar las ventanas emergentes automáticas, establezca el retardo a un número grande de milisegundos, como 100000000). Para nombres de módulos importados o atributos de clases o funciones, escriba “.”. Para nombres de archivos en el directorio raíz, escriba os.sep o os.altsep inmediatamente después de una comilla de apertura. (En Windows, se puede especificar una unidad de disco primero.) Muévase a los subdirectorios escribiendo un nombre de directorio y un separador.

En lugar de esperar, o después de cerrar una caja, abra una caja de finalización inmediatamente con Mostrar finalizaciones en el menú Edición. La tecla rápida por defecto es C-espacio. Si se teclea un prefijo para el nombre deseado antes de abrir el cuadro, la primera coincidencia o casi coincidencia se hace visible. El resultado es el mismo que si se introduce un prefijo después de mostrar la caja. Mostrar las terminaciones después de una cita completa de los nombres de archivo en el directorio actual en lugar de un directorio raíz.

Pulsar Tab después de un prefijo suele tener el mismo efecto que el de mostrar las terminaciones. (Sin prefijo, se indenta.) Sin embargo, si sólo hay una coincidencia con el prefijo, esa coincidencia se añade inmediatamente al texto del editor sin abrir una caja.

Al invocar “Mostrar las terminaciones”, o al pulsar Tab después de un prefijo, fuera de una cadena y sin un “.” precedente, se abre un cuadro con las palabras clave, los nombres incorporados y los nombres disponibles a nivel de módulo.

Cuando se edita el código en un editor (a diferencia de Shell), aumentar los nombres disponibles a nivel de módulo mediante la ejecución de su código y no reiniciar el Shell después. Esto es especialmente útil después de añadir importaciones en la parte superior de un archivo. Esto también aumenta las posibles terminaciones de atributos.

Completion boxes initially exclude names beginning with “_” or, for modules, not included in “__all__”. The hidden names can be accessed by typing “_” after “.”, either before or after the box is opened.

Sugerencias de llamada

A calltip is shown automatically when one types ( after the name of an accessible function. A function name expression may include dots and subscripts. A calltip remains until it is clicked, the cursor is moved out of the argument area, or ) is typed. Whenever the cursor is in the argument part of a definition, select Edit and «Show Call Tip» on the menu or enter its shortcut to display a calltip.

La sugerencia de llamada consiste en la firma de la función y el docstring hasta la primera línea en blanco de este último o la quinta línea no en blanco. (Algunas funciones incorporadas carecen de una firma accesible.) Un “/” o “*” en la firma indica que los argumentos anteriores o posteriores se pasan sólo por posición o por nombre (palabra clave). Los detalles están sujetos a cambios.

En Shell, las funciones accesibles dependen de los módulos que se hayan importado en el proceso del usuario, incluidos los importados por el propio Idle, y de las definiciones que se hayan ejecutado, todo ello desde el último reinicio.

For example, restart the Shell and enter itertools.count(. A calltip appears because Idle imports itertools into the user process for its own use. (This could change.) Enter turtle.write( and nothing appears. Idle does not itself import turtle. The menu entry and shortcut also do nothing. Enter import turtle. Thereafter, turtle.write( will display a calltip.

In an editor, import statements have no effect until one runs the file. One might want to run a file after writing import statements, after adding function definitions, or after opening an existing file.

Contexto del código

Dentro de una ventana del editor que contiene código Python, el contexto del código se puede alternar para mostrar u ocultar un panel en la parte superior de la ventana. Cuando se muestra, este panel congela las líneas de apertura por bloques de código, como aquellos que comienzan con las palabras clave class, def, o if, que de otro modo se habrían desplazado fuera de la vista. El tamaño del panel se expandirá y contraerá según sea necesario para mostrar todos los niveles actuales de contexto, hasta el número máximo de líneas definidas en el cuadro de diálogo Configurar IDLE (que por defecto es 15). Si no hay líneas de contexto actuales y la función está activada, se visualizará una sola línea en blanco. Al hacer click en una línea en el panel de contexto, esa línea se moverá a la parte superior del editor.

El texto y los colores de fondo para el panel de contexto se pueden configurar en la pestaña destacados en el cuadro de diálogo Configurar IDLE.

Shell de Python

Con el shell del IDLE, se ingresa, edita y hace recae declaraciones completas. La mayoría de consolas y terminales solo funcionan con una sola línea física a la vez.

Cuando se pega código en el shell, este no es compilado y posiblemente ejecutado hasta que se teclea Return. Se puede editar el código pegado primero. Si se pega más de una declaración en el shell, el resultado será un SyntaxError cuando se compilan varias declaraciones como si fueran una sola.

Las funciones de edición descritas en subsecciones anteriores funcionan cuando se ingresa código de forma interactiva. La ventana de shell del IDLE también responde a las siguientes combinaciones de teclas.

C-c interrumpe la ejecución del comando

C-d lo envía el final del archivo; la ventana se cierra si se escribe en un mensaje >>>

Alt-/ (Expandir palabra) también es útil para reducir la escritura

Historial de comandos

Alt-p recupera el comando anterior que coincide con lo que ha escrito. En macOS use C-p.

Alt-n recupera el siguiente. En macOS use C-n.

Return ingresando en un comando anterior, recupera ese comando

Colores del texto

El idle por defecto es negro sobre texto blanco, pero colorea el texto con significados especiales. Para el shell, estos son: la salida del shell, error del shell, salida del usuario y error del usuario. Para el código Python, en el indicador de comandos de shell o en un editor, estos son: palabras clave, nombres de funciones y clases incorporadas, los siguientes nombres class and def, cadenas de caracteres y comentarios. Para cualquier ventana de texto, estos son: el cursor (cuando está presente), el texto encontrado (cuando sea posible) y el texto seleccionado.

La coloración del texto se realiza en segundo plano, por lo que ocasionalmente se puede ver el texto sin colorear. Para cambiar la combinación de colores, use la pestaña Resaltar en el cuadro de diálogo Configurar IDLE. El marcado de líneas de breakpoint del depurador en el editor y el texto en ventanas emergentes y cuadros de diálogo no es configurable por el usuario.

Inicio y ejecución de código

Al iniciar con la opción -s, el IDLE ejecutará el archivo al que hacen referencia las variables de entorno IDLESTARTUP o PYTHONSTARTUP. El IDLE primero verifica IDLESTARTUP; si IDLESTARTUP está presente, se ejecuta el archivo al que se hace referencia. Si IDLESTARTUP no está presente, IDLE verifica PYTHONSTARTUP. Los archivos referenciados por estas variables de entorno son lugares convenientes para almacenar funciones que son usadas con frecuencia desde el shell del IDLE o para ejecutar declaraciones importadas para importar módulos comunes.

Además, Tk también carga un archivo de inicio si este está presente. Tenga en cuenta que el archivo Tk se carga incondicionalmente. Este archivo adicional es .Idle.py y es buscado en el directorio de inicio del usuario. Las declaraciones en este archivo se ejecutarán en el espacio de nombres Tk, por lo que este archivo no es útil para importar funciones que se utilizarán desde el shell de Python del IDLE.

Uso de línea de comando

idle.py [-c command] [-d] [-e] [-h] [-i] [-r file] [-s] [-t title] [-] [arg] ...

-c command  run command in the shell window
-d          enable debugger and open shell window
-e          open editor window
-h          print help message with legal combinations and exit
-i          open shell window
-r file     run file in shell window
-s          run $IDLESTARTUP or $PYTHONSTARTUP first, in shell window
-t title    set title of shell window
-           run stdin in shell (- must be last option before args)

Si están los argumentos:

Si se usa -, -c o r, todos los argumentos se colocan en sys.argv [1:...] `` y ``sys.argv[0] se establece en '', '-c' o '-r'. No se abre ninguna ventana del editor, incluso si ese es el conjunto predeterminado en el cuadro de diálogo opciones.

De lo contrario, los argumentos son archivos abiertos para edición y sys.argv refleja los argumentos pasados al IDLE.

Error de inicio

IDLE uses a socket to communicate between the IDLE GUI process and the user code execution process. A connection must be established whenever the Shell starts or restarts. (The latter is indicated by a divider line that says “RESTART”). If the user process fails to connect to the GUI process, it usually displays a Tk error box with a “cannot connect” message that directs the user here. It then exits.

One specific connection failure on Unix systems results from misconfigured masquerading rules somewhere in a system’s network setup. When IDLE is started from a terminal, one will see a message starting with ** Invalid host:. The valid value is 127.0.0.1 (idlelib.rpc.LOCALHOST). One can diagnose with tcpconnect -irv 127.0.0.1 6543 in one terminal window and tcplisten <same args> in another.

Una causa común de falla se da cuando un archivo escrito por el usuario tiene el mismo nombre de un módulo de biblioteca estándar, como random.py y tkinter.py. Cuando dicho archivo se encuentra en el mismo directorio que un archivo que está por ejecutarse, el IDLE no puede importar el archivo stdlib. La solución actual es cambiar el nombre del archivo del usuario.

Aunque es menos común que en el pasado, un programa de antivirus o firewall puede detener la conexión. Si el programa no se puede configurar para permitir la conexión, debe estar apagado para que funcione el IDLE. Es seguro permitir esta conexión interna porque no hay datos visibles en puertos externos. Un problema similar es una configuración incorrecta de la red que bloquea las conexiones.

Los problemas de instalación de Python ocasionalmente detienen el IDLE: puede darse un conflicto entre versiones o una sola instalación puede requerir privilegios de administrador. Si se soluciona el conflicto o no se puede o quiere ejecutar como administrador, puede ser más fácil desinstalar completamente Python y comenzar de nuevo.

Un proceso zombie pythonw.exe podría ser un problema. En Windows, use el Administrador de tareas para buscar uno y detenerlo si lo hay. A veces, un reinicio iniciado por un bloqueo del programa o una interrupción del teclado (control-C) puede fallar al conectarse. Descartar el cuadro de error o usar Reiniciar Shell en el menú del Shell puede solucionar un problema temporal.

Cuando el IDLE se inicia por primera vez, intenta leer los archivos de configuración de usuario en ~/.idlerc/ (~ este es el directorio principal). Si hay un problema, se mostrará un mensaje de error. Dejando de lado los fallos aleatorios del disco, esto se puede evitar si nunca se editan los archivos a mano. En su lugar, utilice el cuadro de diálogo de configuración, en Opciones. Una vez que hay un error en un archivo de configuración de usuario, la mejor solución puede ser eliminarlo y empezar de nuevo con el cuadro de diálogo de configuración.

Si el IDLE se cierra sin mensaje y este no fue iniciado desde una consola, intente iniciarlo desde una consola o terminal (python -m idlelib) y observe si esto genera un mensaje de error.

On Unix-based systems with tcl/tk older than 8.6.11 (see About IDLE) certain characters of certain fonts can cause a tk failure with a message to the terminal. This can happen either if one starts IDLE to edit a file with such a character or later when entering such a character. If one cannot upgrade tcl/tk, then re-configure IDLE to use a font that works better.

Ejecutando código del usuario

With rare exceptions, the result of executing Python code with IDLE is intended to be the same as executing the same code by the default method, directly with Python in a text-mode system console or terminal window. However, the different interface and operation occasionally affect visible results. For instance, sys.modules starts with more entries, and threading.active_count() returns 2 instead of 1.

De forma predeterminada, el IDLE ejecuta el código de usuario en un proceso separado del sistema operativo en lugar de hacerlo en el proceso de la interfaz de usuario que ejecuta el shell y el editor. En el proceso de ejecución, este reemplaza sys.stdin, sys.stdout, y sys.stderr con objetos que recuperan las entradas desde y envían las salidas hacia la ventana de la consola. Los valores originales almacenados en sys.__stdin__, sys.__stdout__, y sys.__stderr__ no se ven afectados, pero pueden ser None.

El envío de la salida de impresión de un proceso a un widget de texto en otro es más lento que la impresión a un terminal del sistema en el mismo proceso. Esto tiene el mayor efecto cuando se imprimen múltiples argumentos, ya que la cadena de cada argumento, cada separador y la nueva línea se envían por separado. Para el desarrollo, esto no suele ser un problema, pero si uno quiere imprimir más rápido en IDLE, formatea y une todo lo que quiere mostrar junto y luego imprime una sola cadena. Tanto las cadenas de formato como str.join() pueden ayudar a combinar campos y líneas.

Las sustituciones de flujo estándar del IDLE no son heredadas por subprocesos creados en el proceso de ejecución, siendo directamente por código de usuario o por módulos como el multiprocesamiento. Si tal subproceso usa input desde sys.stdin o print o write hacia sys.stdout o sys.stderr, el IDLE debe ser iniciado en una ventana de línea de comando. El subproceso secundario será adjuntado a esa ventana para entrada y salida.

Si sys es restablecido mediante un código de usuario, tal como importlib.reload(sys), los cambios del IDLE se perderán y la entrada del teclado y la salida de la pantalla no funcionarán correctamente.

Cuando el shell está en primer plano, controla el teclado y la pantalla. Este es transparente normalmente, pero las funciones que acceden directamente al teclado y la pantalla no funcionarán. Estas incluyen funciones específicas del sistema que determinan si se ha presionado una tecla y de ser así, cuál.

La ejecución de código del IDLE en el proceso de ejecución agrega marcos a la pila de llamadas que de otro modo no estarían allí. el IDLE encapsula sys.getrecursionlimit y sys.setrecursionlimit para reducir el efecto de los marcos de pila adicionales.

Cuando el código de usuario genera SystemExit directamente o llamando a sys.exit, el IDLE regresa al visualizador del Shell en lugar de salir.

Salida del usuario en consola

Cuando un programa muestra texto, el resultado está determinado por el dispositivo de salida correspondiente. Cuando el IDLE ejecuta el código de usuario sys.stdout y sys.stderr se conectan al área de visualización del Shell del IDLE. Algunas de estas características son heredadas de los widgets de texto Tk subyacentes. Otras son adiciones programadas. Donde es importante, el shell está diseñado para el desarrollo en lugar de la ejecución de producción.

Por ejemplo, el Shell nunca elimina la salida. Un programa que envía salidas ilimitadas al Shell eventualmente llenará la memoria, lo que resultará en un error de memoria. Por el contrario, algunas ventanas de texto del sistema solo conservan las últimas n líneas de salida. Una consola de Windows, por ejemplo, mantiene una línea configurable por el usuario de 1 a 9999, con 300 por defecto.

Un widget de texto de Tk, y por lo tanto el Shell de IDLE, muestra caracteres (puntos de código) en el subconjunto BMP (plano multilingual básico) de Unicode. Aquellos caracteres que se muestran con un glifo adecuado y los cuales con una caja de reemplazo depende del sistema operativo y las fuentes instaladas. Los caracteres de tabulación hacen que el texto siguiente comience después de la siguiente tabulación. (Ocurre cada 8 “caracteres”). Los caracteres de nueva línea hacen que el texto siguiente aparezca en una nueva línea. Otros caracteres de control se omiten o se muestran como un espacio, cuadro u otra cosa, dependiendo del sistema operativo y la fuente. (Mover el cursor del texto a través de esa salida con las teclas de flecha puede mostrar algún comportamiento de espaciado sorpresivo.)

>>> s = 'a\tb\a<\x02><\r>\bc\nd'  # Enter 22 chars.
>>> len(s)
14
>>> s  # Display repr(s)
'a\tb\x07<\x02><\r>\x08c\nd'
>>> print(s, end='')  # Display s as is.
# Result varies by OS and font.  Try it.

La función repr es usada para la visualización interactiva del valor de las expresiones. Esta retorna una versión modificada de la cadena de caracteres de entrada en la que los códigos de control, algunos puntos de código BMP y todos los puntos de código que no son BMP son reemplazados con caracteres de escape. Como se demostró anteriormente, esto permite identificar los caracteres en una cadena de caracteres, independientemente de cómo sean mostrados.

La salida normal y de error generalmente se mantienen separadas (en líneas separadas) de la entrada de código y entre sí. Cada una obtiene diferentes colores de resaltado.

Para el traceback de SyntaxError, el marcado normal “^” dónde se detectó el error se reemplaza coloreando el texto con un resaltado de error. Cuando el código ejecutado desde un archivo causa otras excepciones, se puede hacer click derecho en un traceback para saltar a la línea correspondiente en un editor del IDLE. El archivo se abrirá si es necesario.

El Shell tiene una funcionalidad especial para exprimir las líneas de salida hasta una etiqueta de “Texto Squeezed”. Esto se hace automáticamente para una salida sobre N líneas (N = 50 por defecto). N se puede cambiar en la sección PyShell de la página General del cuadro de diálogo Configuración. La salida con menos líneas puede ser squeezed haciendo click derecho en la salida. Esto puede ser útil en líneas suficientemente largas para bajar el tiempo de desplazamiento.

La salida squeezed se expande en su lugar haciendo doble click en la etiqueta. También se puede enviar al portapapeles o a una ventana de vista separada haciendo click derecho en la etiqueta.

Desarrollando aplicaciones tkinter

El IDLE es intencionalmente diferente de Python estándar para facilitar el desarrollo de programas tkinter. Ingrese import tkinter as tk; root = tk.Tk() en Python estándar y no aparecerá nada. Ingrese lo mismo en el IDLE y aparecerá una ventana tk. En Python estándar, también se debe ingresar root.update() para ver la ventana. El IDLE hace el equivalente en segundo plano, aproximadamente 20 veces por segundo, lo que es aproximadamente cada 50 milisegundos. Luego ingrese b = tk.Button(root, text='button'); b.pack(). Del mismo modo, no hay cambios visibles en Python estándar hasta que ingrese root.update().

La mayoría de los programas tkinter ejecutan root.mainloop(), que generalmente no retorna hasta que se destruye la aplicación tk. Si el programa se ejecuta con python -i o desde un editor del IDLE, no aparecerá un mensaje >>> del shell hasta que retorne mainloop(), momento en el cual no queda nada con lo que interactuar.

Al ejecutar un programa tkinter desde un editor IDLE, se puede comentar la llamada de bucle principal. Luego se recibe un aviso del shell inmediatamente y se puede interactuar con la aplicación en vivo. Solo se debe recordar reactivar la llamada al bucle principal cuando se ejecuta en Python estándar.

Ejecutando sin un subproceso

Por defecto, el IDLE ejecuta el código de usuario en un subproceso separado a través de un socket, el cual utiliza la interfaz de bucle interno. Esta conexión no es visible externamente y no son enviados ni recibidos datos de Internet. Si el software de cortafuego sigue presentando problemas, puede ignorarlo.

Si el intento de conexión del socket falla, IDLE lo notificará. Este tipo de falla a veces es temporal, pero si persiste, el problema puede provenir de un cortafuego que bloquea la conexión o de una mala configuración en un sistema en particular. Hasta que se solucione el problema, se puede ejecutar el Idle con el modificador de línea de comandos -n.

Si el IDLE se inicia con el modificador de línea de comandos -n, se ejecutará en un único proceso y no creará el subproceso que ejecuta el servidor de ejecución de Python RPC. Esto puede ser útil si Python no puede crear el subproceso o la interfaz de socket RPC en su plataforma. Sin embargo, en este modo el código de usuario no está aislado en sí del IDLE. Además, el entorno no se reinicia cuando se selecciona Ejecutar/Ejecutar módulo (F5). Si el código se ha modificado, se debe volver a cargar() los módulos afectados y volver a importar cualquier elemento específico (por ejemplo, desde foo importar baz) para que los cambios surtan efecto. Por estas razones, es preferible ejecutar el IDLE con el subproceso predeterminado si es posible.

Obsoleto desde la versión 3.4.

Ayuda y preferencias

Recursos de ayuda

La entrada del menú Ayuda «Ayuda IDLE» muestra una versión HTML formateada del capítulo IDLE de la Referencia de la biblioteca. El resultado, en una ventana de texto tkinter de solo lectura, está cerca de lo que se ve en un navegador web. Navegue por el texto con la rueda del ratón, la barra de desplazamiento o presionando las teclas de flecha arriba y abajo. O haga click en el botón TDC (Tabla de contenido) y seleccione un encabezado de sección en el cuadro abierto.

La entrada del menú de ayuda «Documentos de Python» abre amplias fuentes de ayuda, incluyendo tutoriales, disponibles en docs.python.org/x.y, donde “x.y” es la versión de Python actualmente en ejecución. Si su sistema tiene una copia fuera de línea de los documentos (esta puede ser una opción de instalación), esta se abrirá en su lugar.

Las URL seleccionadas se pueden agregar o eliminar del menú de ayuda en cualquier momento utilizando la pestaña General del cuadro de diálogo Configurar IDLE.

Preferencias de configuración

Las preferencias de fuente, resaltado, teclas y preferencias generales se pueden cambiar en Configurar IDLE en el menú opción. Las configuraciones de usuario no predeterminadas se guardan en un directorio .idlerc en el directorio de inicio del usuario. Los problemas causados por archivos de configuración de usuario incorrectos se resuelven editando o eliminando uno o más de los archivos en .idlerc.

En la pestaña Fuentes (Font), consulte la muestra de texto para ver el efecto de la fuente y el tamaño de la fuente en varios caracteres en varios idiomas. Edite la muestra para agregar otros caracteres de interés personal. Use la muestra para seleccionar fuentes monoespaciadas. Si determinados caracteres tienen problemas en el shell o en el editor, agréguelos a la parte inicial de la muestra e intente cambiar primero el tamaño y luego la fuente.

En la pestaña Resaltado y Teclas (Highlights and Keys), seleccione un tema de color integrado o personalizado y un conjunto de teclas. Para utilizar un nuevo tema de color integrado o un conjunto de teclas con IDLE más antiguos, guárdelo como un nuevo tema personalizado o conjunto de teclas y será accesible para los IDLE más antiguos.

IDLE en macOS

En Preferencias del sistema: Dock, puede establecer «Preferencias de pestañas al abrir documentos» en el valor «Siempre». Este parámetro no es compatible con la interfaz gráfica de usuario del framework tk/tkinter utilizado por IDLE y rompe algunas funcionalidades del IDLE.

Extensiones

IDLE incluye una herramienta de extensiones. Las preferencias para las extensiones se pueden cambiar con la pestaña Extensiones de la ventana de preferencias. Lea el inicio de config-extensions.def en la carpeta idlelib para obtener más información. La única extensión utilizada actualmente por defecto es zzdummy, un ejemplo que también se utiliza para realizar pruebas.

Herramientas de desarrollo

Los módulos descritos en este capítulo le ayudan a escribir software. Por ejemplo, el módulo pydoc toma un módulo y genera documentación basada en el contenido del módulo. Los módulos doctest y unittest contienen frameworks para escribir pruebas unitarias que ejecutan y validan automáticamente el código, verificando que se produce la salida esperada. 2to3 puede traducir el código fuente de Python 2.x en código válido de Python 3.x.

La lista de módulos descritos en este capítulo es:

typing — Soporte para type hints

Relevant PEPs

Alias de tipo

NewType

Callable

Genéricos

Tipos genéricos definidos por el usuario

El tipo Any

Subtipado nominal vs estructural

Contenido del módulo

Primitivos especiales de tipado

Tipos especiales

Formas especiales

Tipos de construcción de genéricos

Otras directivas especiales

Colecciones genéricas concretas

Correspondientes a tipos integrados

Correspondiente a tipos en collections

Otros tipos concretos

Clase base abstracta para tipos genéricos

Correspondientes a las colecciones en collections.abc

Correspondiente a otros tipos en collections.abc

Programación asíncrona

Tipos del administrador de contextos

Protocolos

Funciones y decoradores

Ayudas de introspección

Constantes

pydoc — Generador de documentación y Sistema de ayuda en línea

Modo de desarrollo de Python

Efectos del modo de desarrollo de Python

Ejemplo de ResourceWarning

Ejemplo de error de descriptor de archivo incorrecto

doctest – Prueba ejemplos interactivos de Python

Uso simple: verificar ejemplos en docstrings

Uso Simple: Verificar ejemplos en un Archivo de Texto

Cómo funciona

¿Qué docstrings son examinados?

¿Cómo se reconocen los ejemplos de docstring?

¿Cuál es el contexto de ejecución?

¿Y las excepciones?

Banderas de Opción

Directivas

Advertencias

API básica

API de unittest

API avanzada

Objetos DocTest

Objetos Example

Objetos DocTestFinder

Objetos DocTestParser

Objetos DocTestRunner

Objetos OutputChecker

Depuración

Plataforma improvisada

unittest — Infraestructura de tests unitarios

Ejemplo sencillo

Interfaz de línea de comandos

Opciones de la línea de órdenes

Descubrimiento de pruebas

Organización del código de pruebas

Reutilización de código de prueba anterior

Omitir tests y fallos esperados

Distinguiendo iteraciones de tests empleando subtests

Clases y funciones

Casos de test

Alias obsoletos

Agrupando tests

Cargando y ejecutando tests

load_tests protocolo

Instalaciones para clases y módulos

setUpClass y tearDownClass

setUpModule y tearDownModule

Manejo de señales

unittest.mock — Biblioteca de objetos simulados

Guía rápida

La clase Mock

Llamar a los objetos simulados

Eliminar atributos

Los nombres de los objetos simulados y el atributo name

Adjuntar objetos simulados como atributos

Parcheadores

patch

patch.object

patch.dict

patch.multiple

Métodos start y stop de patch

Parchear objetos incorporados (builtins)

TEST_PREFIX

Anidando decoradores patch

Dónde parchear

Parcheando descriptores y objetos proxy

MagicMock y el soporte de métodos mágicos

Simular métodos mágicos

Magic Mock

Ayudantes

sentinel

DEFAULT

call

create_autospec

ANY

FILTER_DIR

mock_open

Autoespecificación

Sellar objetos simulados

unittest.mock — primeros pasos

Usando Mock

Métodos de parcheo Mock

Mock de llamadas a métodos sobre un objeto

Clases Mocking

Nombrando tus mocks

Siguiendo todas las llamadas

Establecer valores de retorno y atributos

Generar excepciones con mocks

Funciones de efectos secundarios e iterables

Iteradores asincrónicos de Mocking

El gestor de contexto asincrónico de Mocking

Creando un mock desde un objeto existente

Decoradores de Parches

Otros Ejemplos

Mocking de llamadas encadenadas

Mocking parcial

Mocking de un Método Generador

Aplicar el mismo parche a cada método de prueba

Mocking de métodos sin enlazar

Comprobación de varias llamadas con mock

Copiando con argumentos mutables

Anidando Parches

Mocking a un diccionario usando MagickMock

Mock de subclases y sus atributos

Importaciones de Mocking con patch.dict

Seguimiento del orden de las llamadas y de las aserciones de llamadas menos detalladas

Coincidencia de argumentos más compleja

2to3 - Traducción de código Python 2 a 3

Usando 2to3

Fixers

lib2to3 - librería 2to3

test — Paquete de pruebas de regresión para Python

Escritura de pruebas unitarias para el paquete test

Ejecución de pruebas utilizando la interfaz de línea de comandos

test.support — Utilidades para el conjunto de pruebas de Python

test.support.socket_helper — Utilidades para pruebas de socket

test.support.script_helper —Utilidades para las pruebas de ejecución de Python

test.support.bytecode_helper — Herramientas de apoyo para comprobar la correcta generación de bytecode

typing — Soporte para type hints

Nuevo en la versión 3.5.

Source code: Lib/typing.py [https://github.com/python/cpython/tree/3.9/Lib/typing.py]

Nota

En tiempo de ejecución, Python no impone las anotaciones de tipado en funciones y variables. Pueden ser utilizadas por herramientas de terceros como validadores de tipado, IDEs, linters, etc.

This module provides runtime support for type hints. The most fundamental support consists of the types Any, Union, Callable, TypeVar, and Generic. For a full specification, please see PEP 484 [https://www.python.org/dev/peps/pep-0484]. For a simplified introduction to type hints, see PEP 483 [https://www.python.org/dev/peps/pep-0483].

La siguiente función toma y retorna una cadena de texto, que se anota de la siguiente manera:

def greeting(name: str) -> str:
    return 'Hello ' + name

En la función greeting, se espera que el argumento name sea de tipo str y que el tipo retornado sea str. Los subtipos también son aceptados como argumento válido.

New features are frequently added to the typing module. The typing_extensions [https://pypi.org/project/typing-extensions/] package provides backports of these new features to older versions of Python.

Relevant PEPs

Since the initial introduction of type hints in PEP 484 [https://www.python.org/dev/peps/pep-0484] and PEP 483 [https://www.python.org/dev/peps/pep-0483], a number of PEPs have modified and enhanced Python’s framework for type annotations. These include:

PEP 526 [https://www.python.org/dev/peps/pep-0526]: Syntax for Variable Annotations

Introducing syntax for annotating variables outside of function definitions, and ClassVar

PEP 544 [https://www.python.org/dev/peps/pep-0544]: Protocols: Structural subtyping (static duck typing)

Introducing Protocol and the @runtime_checkable decorator

PEP 585 [https://www.python.org/dev/peps/pep-0585]: Type Hinting Generics In Standard Collections

Introducing types.GenericAlias and the ability to use standard library classes as generic types

PEP 586 [https://www.python.org/dev/peps/pep-0586]: Literal Types

Introducing Literal

PEP 589 [https://www.python.org/dev/peps/pep-0589]: TypedDict: Type Hints for Dictionaries with a Fixed Set of Keys

Introducing TypedDict

PEP 591 [https://www.python.org/dev/peps/pep-0591]: Adding a final qualifier to typing

Introducing Final and the @final decorator

PEP 593 [https://www.python.org/dev/peps/pep-0593]: Flexible function and variable annotations

Introducing Annotated

Alias de tipo

Un alias de tipo se define asignando el tipo al alias. En este ejemplo, Vector y List[float] serán tratados como sinónimos intercambiables:

Vector = list[float]

def scale(scalar: float, vector: Vector) -> Vector:
    return [scalar * num for num in vector]

# typechecks; a list of floats qualifies as a Vector.
new_vector = scale(2.0, [1.0, -4.2, 5.4])

Los alias de tipo son útiles para simplificar indicadores de tipo complejos. Por ejemplo:

from collections.abc import Sequence

ConnectionOptions = dict[str, str]
Address = tuple[str, int]
Server = tuple[Address, ConnectionOptions]

def broadcast_message(message: str, servers: Sequence[Server]) -> None:
    ...

# The static type checker will treat the previous type signature as
# being exactly equivalent to this one.
def broadcast_message(
        message: str,
        servers: Sequence[tuple[tuple[str, int], dict[str, str]]]) -> None:
    ...

Nótese que None como indicador de tipo es un caso especial y es substituido por type(None).

NewType

Use the NewType() helper to create distinct types:

from typing import NewType

UserId = NewType('UserId', int)
some_id = UserId(524313)

El validador estático de tipos tratará el nuevo tipo como si fuera una subclase del tipo original. Esto es útil para capturar errores lógicos:

def get_user_name(user_id: UserId) -> str:
    ...

# typechecks
user_a = get_user_name(UserId(42351))

# does not typecheck; an int is not a UserId
user_b = get_user_name(-1)

Se pueden realizar todas las operaciones de int en una variable de tipo UserId, pero el resultado siempre será de tipo int. Esto permite pasar un UserId allí donde se espere un int, pero evitará la creación accidental de un UserId de manera incorrecta:

# 'output' is of type 'int', not 'UserId'
output = UserId(23413) + UserId(54341)

Note that these checks are enforced only by the static type checker. At runtime, the statement Derived = NewType('Derived', Base) will make Derived a callable that immediately returns whatever parameter you pass it. That means the expression Derived(some_value) does not create a new class or introduce any overhead beyond that of a regular function call.

Más concretamente, la expresión some_value is Derived(some_value) será siempre verdadera en tiempo de ejecución.

Esto también implica que no es posible crear un subtipo de Derived ya que, en tiempo de ejecución, es una función de identidad, no un tipo propiamente dicho:

from typing import NewType

UserId = NewType('UserId', int)

# Fails at runtime and does not typecheck
class AdminUserId(UserId): pass

Sin embargo, es posible crear un NewType() basado en un NewType “derivado”:

from typing import NewType

UserId = NewType('UserId', int)

ProUserId = NewType('ProUserId', UserId)

y la comprobación de tipo para ProUserId funcionará como se espera.

Véase PEP 484 [https://www.python.org/dev/peps/pep-0484] para más detalle.

Nota

Recuérdese que el uso de alias de tipo implica que los dos tipos son equivalentes entre sí. Haciendo Alias = Original provocará que el Validador estático de tipos trate Alias como algo exactamente equivalente a Original en todos los casos. Esto es útil para cuando se quiera simplificar indicadores de tipo complejos.

En cambio, NewType declara un tipo que es subtipo de otro. Haciendo Derived = NewType('Derived', Original) hará que el Validador estático de tipos trate Derived como una subclase de Original, lo que implica que un valor de tipo Original no puede ser usado allí donde se espere un valor de tipo Derived. Esto es útil para prevenir errores lógicos con un coste de ejecución mínimo.

Nuevo en la versión 3.5.2.

Callable

Entidades que esperen llamadas a funciones con interfaces específicas puede ser anotadas usando Callable[[Arg1Type, Arg2Type], ReturnType].

Por ejemplo:

from collections.abc import Callable

def feeder(get_next_item: Callable[[], str]) -> None:
    # Body

def async_query(on_success: Callable[[int], None],
                on_error: Callable[[int, Exception], None]) -> None:
    # Body

async def on_update(value: str) -> None:
    # Body
callback: Callable[[str], Awaitable[None]] = on_update

Es posible declarar el tipo de retorno de un callable (invocable) sin especificar tipos en los parámetros substituyendo la lista de argumentos por unos puntos suspensivos (…) en el indicador de tipo: Callable[..., ReturnType].

Genéricos

Ya que no es posible inferir estáticamente y de una manera genérica la información de tipo de objetos dentro de contenedores, las clases base abstractas han sido mejoradas para permitir sintaxis de subíndice para denotar los tipos esperados en elementos contenedores.

from collections.abc import Mapping, Sequence

def notify_by_email(employees: Sequence[Employee],
                    overrides: Mapping[str, str]) -> None: ...

Generics can be parameterized by using a factory available in typing called TypeVar.

from collections.abc import Sequence
from typing import TypeVar

T = TypeVar('T')      # Declare type variable

def first(l: Sequence[T]) -> T:   # Generic function
    return l[0]

Tipos genéricos definidos por el usuario

Una clase definida por el usuario puede ser definida como una clase genérica.

from typing import TypeVar, Generic
from logging import Logger

T = TypeVar('T')

class LoggedVar(Generic[T]):
    def __init__(self, value: T, name: str, logger: Logger) -> None:
        self.name = name
        self.logger = logger
        self.value = value

    def set(self, new: T) -> None:
        self.log('Set ' + repr(self.value))
        self.value = new

    def get(self) -> T:
        self.log('Get ' + repr(self.value))
        return self.value

    def log(self, message: str) -> None:
        self.logger.info('%s: %s', self.name, message)

Generic[T] como clase base define que la clase LoggedVar toma un solo parámetro T. Esto también implica que T es un tipo válido dentro del cuerpo de la clase.

The Generic base class defines __class_getitem__() so that LoggedVar[t] is valid as a type:

from collections.abc import Iterable

def zero_all_vars(vars: Iterable[LoggedVar[int]]) -> None:
    for var in vars:
        var.set(0)

A generic type can have any number of type variables. All varieties of TypeVar are permissible as parameters for a generic type:

from typing import TypeVar, Generic, Sequence

T = TypeVar('T', contravariant=True)
B = TypeVar('B', bound=Sequence[bytes], covariant=True)
S = TypeVar('S', int, str)

class WeirdTrio(Generic[T, B, S]):
    ...

Cada argumento de variable de tipo en una clase Generic debe ser distinto. Así, no será válido:

from typing import TypeVar, Generic
...

T = TypeVar('T')

class Pair(Generic[T, T]):   # INVALID
    ...

Se puede utilizar herencia múltiple con Generic:

from collections.abc import Sized
from typing import TypeVar, Generic

T = TypeVar('T')

class LinkedList(Sized, Generic[T]):
    ...

Cuando se hereda de clases genéricas, se pueden fijar algunas variables de tipo:

from collections.abc import Mapping
from typing import TypeVar

T = TypeVar('T')

class MyDict(Mapping[str, T]):
    ...

En este caso MyDict tiene un solo parámetro, T.

Al usar una clase genérica sin especificar parámetros de tipo se asume Any para todas las posiciones. En el siguiente ejemplo, MyIterable no es genérico pero hereda implícitamente de Iterable[Any]:

from collections.abc import Iterable

class MyIterable(Iterable): # Same as Iterable[Any]

Son posibles los alias de tipos genéricos definidos por el usuario. Ejemplos:

from collections.abc import Iterable
from typing import TypeVar, Union
S = TypeVar('S')
Response = Union[Iterable[S], int]

# Return type here is same as Union[Iterable[str], int]
def response(query: str) -> Response[str]:
    ...

T = TypeVar('T', int, float, complex)
Vec = Iterable[tuple[T, T]]

def inproduct(v: Vec[T]) -> T: # Same as Iterable[tuple[T, T]]
    return sum(x*y for x, y in v)

Distinto en la versión 3.7: Generic ya no posee una metaclase personalizable.

Un clase genérica definida por el usuario puede tener clases ABC como clase base sin conflicto de metaclase. Las metaclases genéricas no están permitidas. El resultado de parametrizar clases genéricas se cachea, y la mayoría de los tipos en el módulo typing pueden tener un hash y ser comparables por igualdad (equality).

El tipo Any

Un caso especial de tipo es Any. Un Validador estático de tipos tratará cualquier tipo como compatible con Any, y Any como compatible con todos los tipos.

Esto significa que es posible realizar cualquier operación o llamada a un método en un valor de tipo Any y asignarlo a cualquier variable:

from typing import Any

a: Any = None
a = []          # OK
a = 2           # OK

s: str = ''
s = a           # OK

def foo(item: Any) -> int:
    # Typechecks; 'item' could be any type,
    # and that type might have a 'bar' method
    item.bar()
    ...

Nótese que no se realiza comprobación de tipo cuando se asigna un valor de tipo Any a un tipo más preciso. Por ejemplo, el Validador estático de tipos no reportó ningún error cuando se asignó a a s, aún cuando se declaró s como de tipo str y recibió un valor int en tiempo de ejecución!

Además, todas las funciones sin un tipo de retorno o tipos en los parámetros serán asignadas implícitamente a Any por defecto:

def legacy_parser(text):
    ...
    return data

# A static type checker will treat the above
# as having the same signature as:
def legacy_parser(text: Any) -> Any:
    ...
    return data

Este comportamiento permite que Any sea usado como una vía de escape cuando es necesario mezclar código tipado estática y dinámicamente.

Compárese el comportamiento de Any con el de object. De manera similar a Any, todo tipo es un subtipo de object. Sin embargo, en oposición a Any, lo contrario no es cierto: object no es un subtipo de ningún otro tipo.

Esto implica que cuando el tipo de un valor es object, un validador de tipos rechazará prácticamente todas las operaciones con él, y al asignarlo a una variable (o usarlo como valor de retorno) de un tipo más preciso será un error de tipo. Por ejemplo:

def hash_a(item: object) -> int:
    # Fails; an object does not have a 'magic' method.
    item.magic()
    ...

def hash_b(item: Any) -> int:
    # Typechecks
    item.magic()
    ...

# Typechecks, since ints and strs are subclasses of object
hash_a(42)
hash_a("foo")

# Typechecks, since Any is compatible with all types
hash_b(42)
hash_b("foo")

Úsese object para indicar que un valor puede ser de cualquier tipo de manera segura. Úsese Any para indicar que un valor es de tipado dinámico.

Subtipado nominal vs estructural

Initially PEP 484 [https://www.python.org/dev/peps/pep-0484] defined the Python static type system as using nominal subtyping. This means that a class A is allowed where a class B is expected if and only if A is a subclass of B.

Este requisito también se aplicaba anteriormente a clases base abstractas (ABC), tales como Iterable. El problema con esta estrategia es que una clase debía de ser marcada explícitamente para proporcionar tal funcionalidad, lo que resulta poco pythónico (idiomático) y poco ajustado a lo que uno normalmente haría en un código Python tipado dinámicamente. Por ejemplo, esto sí se ajusta al PEP 484 [https://www.python.org/dev/peps/pep-0484]:

from collections.abc import Sized, Iterable, Iterator

class Bucket(Sized, Iterable[int]):
    ...
    def __len__(self) -> int: ...
    def __iter__(self) -> Iterator[int]: ...

El PEP 544 [https://www.python.org/dev/peps/pep-0544] permite resolver este problema al permitir escribir el código anterior sin una clase base explícita en la definición de la clase, permitiendo que el Validador estático de tipo considere implícitamente que Bucket es un subtipo tanto de Sized como de Iterable[int]. Esto se conoce como tipado estructural (o duck-typing estático):

from collections.abc import Iterator, Iterable

class Bucket:  # Note: no base classes
    ...
    def __len__(self) -> int: ...
    def __iter__(self) -> Iterator[int]: ...

def collect(items: Iterable[int]) -> int: ...
result = collect(Bucket())  # Passes type check

Asimismo, creando subclases de la clase especial Protocol, el usuario puede definir nuevos protocolos personalizados y beneficiarse del tipado estructural (véanse los ejemplos de abajo).

Contenido del módulo

El módulo define las siguientes clases, funciones y decoradores.

Nota

Este módulo define algunos tipos que son subclases de clases que ya existen en la librería estándar, y que además extienden Generic para soportar variables de tipo dentro de []. Estos tipos se vuelven redundantes en Python 3.9 ya que las clases correspondientes fueron mejoradas para soportar [].

Los tipos redundantes están descontinuados con Python 3.9 pero el intérprete no mostrará ninguna advertencia. Se espera que los verificadores de tipo marquen estos tipos como obsoletos cuando el programa a verificar apunte a Python 3.9 o superior.

Los tipos obsoletos serán removidos del módulo Generic en la primera versión de Python que sea lanzada 5 años después del lanzamiento de Python 3.9.0. Véase los detalles en PEP 585 [https://www.python.org/dev/peps/pep-0585] – Sugerencias de tipo genéricas en las Colecciones Estándar.

Primitivos especiales de tipado

Tipos especiales

Estos pueden ser usados como tipos en anotaciones y no soportan [].

typing.Any

Tipo especial que indica un tipo sin restricciones.

Todos los tipos son compatibles con Any.

Any es compatible con todos los tipos.

typing.NoReturn

Tipo especial que indica que una función nunca retorna un valor. Por ejemplo:

from typing import NoReturn

def stop() -> NoReturn:
    raise RuntimeError('no way')

Nuevo en la versión 3.5.4.

Nuevo en la versión 3.6.2.

Formas especiales

Estas se pueden usar como anotaciones de tipo usando [], cada cual tiene una sintaxis única.

typing.Tuple

El tipo Tuple, Tuple[X, Y] es el tipo de una tupla de dos ítems con el primer ítem de tipo X y el segundo de tipo Y. El tipo de una tupla vacía se puede escribir así: Tuple[()].

Ejemplo: Tuple[T1, T2] es una tupla de dos elementos con sus correspondientes variables de tipo T1 y T2. Tuple[int, float, str] es un tupla con un número entero, un número de punto flotante y una cadena de texto.

Para especificar una tupla de longitud variable y tipo homogéneo, se usan puntos suspensivos, p. ej. Tuple[int, ...]. Un simple Tuple es equivalente a Tuple[Any, ...] y, a su vez, a tuple.

Obsoleto desde la versión 3.9: builtins.tuple ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

typing.Union

Tipo unión; Union[X, Y] significa que o bien X o bien Y.

Para definir una unión, úsese p. ej. Union[int, str]. Más detalles:

Los argumentos deben ser tipos y haber al menos uno.

Las uniones de uniones se simplifican (se aplanan), p. ej.:

Union[Union[int, str], float] == Union[int, str, float]

Las uniones con un solo argumento se eliminan, p. ej.:

Union[int] == int  # The constructor actually returns int

Argumentos repetidos se omiten, p. ej.:

Union[int, str, int] == Union[int, str]

Cuando se comparan uniones, el orden de los argumentos se ignoran, p. ej.:

Union[int, str] == Union[str, int]

No se puede derivar (subclass) o instanciar una unión.

No es posible escribir Union[X][Y].

Se puede usar Optional[X] como una versión corta de Union[X, None].

Distinto en la versión 3.7: No elimina subclases explícitas de una unión en tiempo de ejecución.

typing.Optional

Tipo Optional.

Optional[X] es equivalente a Union[X, None].

Nótese que no es lo mismo que un argumento opcional, que es aquel que tiene un valor por defecto. Un argumento opcional con un valor por defecto no necesita el indicador Optional en su anotación de tipo simplemente por que sea opcional. Por ejemplo:

def foo(arg: int = 0) -> None:
    ...

Por otro lado, si se permite un valor None, es apropiado el uso de Optional, independientemente de que sea opcional o no. Por ejemplo:

def foo(arg: Optional[int] = None) -> None:
    ...

typing.Callable

Tipo Callable (invocable); Callable[[int], str] es una función de (int) -> str.

La sintaxis de subscripción (con corchetes []) debe usarse siempre con dos valores: la lista de argumentos y el tipo de retorno. La lista de argumentos debe ser una lista de tipos o unos puntos suspensivos; el tipo de retorno debe ser un único tipo.

No existe una sintaxis para indicar argumentos opcionales o con clave (keyword); tales funciones rara vez se utilizan como tipos para llamadas. Callable[..., ReturnType] (puntos suspensivos) se puede usar para indicar que un callable admite un número indeterminado de argumentos y retorna ReturnType. Un simple Callable es equivalente a Callable[..., Any] y, a su vez, a collections.abc.Callable.

Obsoleto desde la versión 3.9: collections.abc.Callable ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

class typing.Type(Generic[CT_co])

Una variable indicada como C puede aceptar valores de tipo C. Sin embargo, un variable indicada como Type[C] puede aceptar valores que son clases en sí mismas – específicamente, aceptará el objecto clase de C. Por ejemplo.:

a = 3         # Has type 'int'
b = int       # Has type 'Type[int]'
c = type(a)   # Also has type 'Type[int]'

Nótese que Type[C] es covariante:

class User: ...
class BasicUser(User): ...
class ProUser(User): ...
class TeamUser(User): ...

# Accepts User, BasicUser, ProUser, TeamUser, ...
def make_new_user(user_class: Type[User]) -> User:
    # ...
    return user_class()

El hecho de que Type[C] sea covariante implica que todas las subclases de C deben implementar la misma interfaz del constructor y las mismas interfaces de los métodos de clase que C. El validador de tipos marcará cualquier incumplimiento de esto, pero permitirá llamadas al constructor que coincida con la llamada al constructor de la clase base indicada. El modo en que el validador de tipos debe gestionar este caso particular podría cambiar en futuras revisiones de PEP 484 [https://www.python.org/dev/peps/pep-0484].

Lo únicos parámetros válidos de Type son clases, Any, type variables, y uniones de cualquiera de los tipos anteriores. Por ejemplo:

def new_non_team_user(user_class: Type[Union[BasicUser, ProUser]]): ...

Type[Any] es equivalente a Type, que a su vez es equivalente a type, que es la raíz de la jerarquía de metaclases de Python.

Nuevo en la versión 3.5.2.

Obsoleto desde la versión 3.9: builtins.type ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

typing.Literal

Un tipo que puede ser utilizado para indicar a los validadores de tipos que una variable o un parámetro de una función tiene un valor equivalente al valor literal proveído (o uno de los proveídos). Por ejemplo:

def validate_simple(data: Any) -> Literal[True]:  # always returns True
    ...

MODE = Literal['r', 'rb', 'w', 'wb']
def open_helper(file: str, mode: MODE) -> str:
    ...

open_helper('/some/path', 'r')  # Passes type check
open_helper('/other/path', 'typo')  # Error in type checker

Literal[...] no puede ser derivado. En tiempo de ejecución, se permite un valor arbitrario como argumento de tipo de Literal[...], pero los validadores de tipos pueden imponer sus restricciones. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] para más detalles sobre tipos literales.

Nuevo en la versión 3.8.

Distinto en la versión 3.9.1: Literal now de-duplicates parameters. Equality comparisons of Literal objects are no longer order dependent. Literal objects will now raise a TypeError exception during equality comparisons if one of their parameters are not hashable.

typing.ClassVar

Construcción especial para tipado para marcar variables de clase.

Tal y como introduce PEP 526 [https://www.python.org/dev/peps/pep-0526], una anotación de variable rodeada por ClassVar indica que la intención de un atributo dado es ser usado como variable de clase y que no debería ser modificado en las instancias de esa misma clase. Uso:

class Starship:
    stats: ClassVar[dict[str, int]] = {} # class variable
    damage: int = 10                     # instance variable

ClassVar solo acepta tipos y no admite más niveles de subíndices.

ClassVar no es un clase en sí misma, y no debe ser usado con isinstance() o issubclass(). ClassVar no modifica el comportamiento de Python en tiempo de ejecución pero puede ser utilizado por validadores de terceros. Por ejemplo, un validador de tipos puede marcar el siguiente código como erróneo:

enterprise_d = Starship(3000)
enterprise_d.stats = {} # Error, setting class variable on instance
Starship.stats = {}     # This is OK

Nuevo en la versión 3.5.3.

typing.Final

Un construcción especial para tipado que indica a los validadores de tipo que un nombre no puede ser reasignado o sobrescrito en una subclase. Por ejemplo:

MAX_SIZE: Final = 9000
MAX_SIZE += 1  # Error reported by type checker

class Connection:
    TIMEOUT: Final[int] = 10

class FastConnector(Connection):
    TIMEOUT = 1  # Error reported by type checker

No hay comprobación en tiempo de ejecución para estas propiedades. Véase PEP 591 [https://www.python.org/dev/peps/pep-0591] para más detalles.

Nuevo en la versión 3.8.

typing.Annotated

A type, introduced in PEP 593 [https://www.python.org/dev/peps/pep-0593] (Flexible function and variable annotations), to decorate existing types with context-specific metadata (possibly multiple pieces of it, as Annotated is variadic). Specifically, a type T can be annotated with metadata x via the typehint Annotated[T, x]. This metadata can be used for either static analysis or at runtime. If a library (or tool) encounters a typehint Annotated[T, x] and has no special logic for metadata x, it should ignore it and simply treat the type as T. Unlike the no_type_check functionality that currently exists in the typing module which completely disables typechecking annotations on a function or a class, the Annotated type allows for both static typechecking of T (which can safely ignore x) together with runtime access to x within a specific application.

En última instancia, la responsabilidad de cómo interpretar las anotaciones (si es que la hay) es de la herramienta o librería que encuentra el tipo Annotated. Una herramienta o librería que encuentra un tipo Annotated puede escanear las anotaciones para determinar si son de interés. (por ejemplo, usando isinstance()).

Cuando una herramienta o librería no soporta anotaciones o encuentra una anotación desconocida, simplemente debe ignorarla o tratar la anotación como el tipo subyacente.

Depende de la herramienta que consume las anotaciones decidir si el cliente puede tener varias anotaciones en un tipo y cómo combinar esas anotaciones.

Dado que el tipo Annotated permite colocar varias anotaciones del mismo (o diferente) tipo(s) en cualquier nodo, las herramientas o librerías que consumen dichas anotaciones están a cargo de ocuparse de potenciales duplicados. Por ejemplo, si se está realizando un análisis de rango, esto se debería permitir:

T1 = Annotated[int, ValueRange(-10, 5)]
T2 = Annotated[T1, ValueRange(-20, 3)]

Pasar include_extras=True a get_type_hints() permite acceder a las anotaciones extra en tiempo de ejecución.

Los detalles de la sintaxis:

El primer argumento en Annotated debe ser un tipo válido

Se permiten varias anotaciones de tipo (Annotated admite argumentos variádicos):

Annotated[int, ValueRange(3, 10), ctype("char")]

Annotated debe ser llamado con al menos dos argumentos (Annotated[int] no es válido)

Se mantiene el orden de las anotaciones y se toma en cuenta para chequeos de igualdad:

Annotated[int, ValueRange(3, 10), ctype("char")] != Annotated[
    int, ctype("char"), ValueRange(3, 10)
]

Los tipos Annotated anidados son aplanados con los metadatos ordenados empezando por la anotación más interna:

Annotated[Annotated[int, ValueRange(3, 10)], ctype("char")] == Annotated[
    int, ValueRange(3, 10), ctype("char")
]

Anotaciones duplicadas no son removidas:

Annotated[int, ValueRange(3, 10)] != Annotated[
    int, ValueRange(3, 10), ValueRange(3, 10)
]

Anotated puede ser usado con alias anidados y genéricos:

T = TypeVar('T')
Vec = Annotated[list[tuple[T, T]], MaxLen(10)]
V = Vec[int]

V == Annotated[list[tuple[int, int]], MaxLen(10)]

Nuevo en la versión 3.9.

Tipos de construcción de genéricos

Estos no son utilizados en anotaciones. Son utilizados como bloques para crear tipos genéricos.

class typing.Generic

Clase base abstracta para tipos genéricos.

Un tipo genérico se declara habitualmente heredando de una instancia de esta clase con una o más variables de tipo. Por ejemplo, un tipo de mapeo genérico se podría definir como:

class Mapping(Generic[KT, VT]):
    def __getitem__(self, key: KT) -> VT:
        ...
        # Etc.

Entonces, esta clase se puede usar como sigue:

X = TypeVar('X')
Y = TypeVar('Y')

def lookup_name(mapping: Mapping[X, Y], key: X, default: Y) -> Y:
    try:
        return mapping[key]
    except KeyError:
        return default

class typing.TypeVar

Variable de tipo.

Uso:

T = TypeVar('T')  # Can be anything
S = TypeVar('S', bound=str)  # Can be any subtype of str
A = TypeVar('A', str, bytes)  # Must be exactly str or bytes

Las variables de tipo son principalmente para ayudar a los validadores estáticos de tipos. Sirven tanto como de parámetros para tipos genéricos como para definición de funciones genéricas. Véase Generic para más información sobre tipos genéricos. Las funciones genéricas funcionan de la siguiente manera:

def repeat(x: T, n: int) -> Sequence[T]:
    """Return a list containing n references to x."""
    return [x]*n

def print_capitalized(x: S) -> S:
    """Print x capitalized, and return x."""
    print(x.capitalize())
    return x

def concatenate(x: A, y: A) -> A:
    """Add two strings or bytes objects together."""
    return x + y

Note that type variables can be bound, constrained, or neither, but cannot be both bound and constrained.

Constrained type variables and bound type variables have different semantics in several important ways. Using a constrained type variable means that the TypeVar can only ever be solved as being exactly one of the constraints given:

a = concatenate('one', 'two')  # Ok, variable 'a' has type 'str'
b = concatenate(StringSubclass('one'), StringSubclass('two'))  # Inferred type of variable 'b' is 'str',
                                                               # despite 'StringSubclass' being passed in
c = concatenate('one', b'two')  # error: type variable 'A' can be either 'str' or 'bytes' in a function call, but not both

Using a bound type variable, however, means that the TypeVar will be solved using the most specific type possible:

print_capitalized('a string')  # Ok, output has type 'str'

class StringSubclass(str):
    pass

print_capitalized(StringSubclass('another string'))  # Ok, output has type 'StringSubclass'
print_capitalized(45)  # error: int is not a subtype of str

Type variables can be bound to concrete types, abstract types (ABCs or protocols), and even unions of types:

U = TypeVar('U', bound=str|bytes)  # Can be any subtype of the union str|bytes
V = TypeVar('V', bound=SupportsAbs)  # Can be anything with an __abs__ method

Bound type variables are particularly useful for annotating classmethods that serve as alternative constructors. In the following example (© Raymond Hettinger [https://www.youtube.com/watch?v=HTLu2DFOdTg]), the type variable C is bound to the Circle class through the use of a forward reference. Using this type variable to annotate the with_circumference classmethod, rather than hardcoding the return type as Circle, means that a type checker can correctly infer the return type even if the method is called on a subclass:

import math

C = TypeVar('C', bound='Circle')

class Circle:
    """An abstract circle"""

    def __init__(self, radius: float) -> None:
        self.radius = radius

    # Use a type variable to show that the return type
    # will always be an instance of whatever ``cls`` is
    @classmethod
    def with_circumference(cls: type[C], circumference: float) -> C:
        """Create a circle with the specified circumference"""
        radius = circumference / (math.pi * 2)
        return cls(radius)

class Tire(Circle):
    """A specialised circle (made out of rubber)"""

    MATERIAL = 'rubber'

c = Circle.with_circumference(3)  # Ok, variable 'c' has type 'Circle'
t = Tire.with_circumference(4)  # Ok, variable 't' has type 'Tire' (not 'Circle')

En tiempo de ejecución, isinstance(x, T) lanzará una excepción TypeError. En general, isinstance() y issubclass() no se deben usar con variables de tipo.

Type variables may be marked covariant or contravariant by passing covariant=True or contravariant=True. See PEP 484 [https://www.python.org/dev/peps/pep-0484] for more details. By default, type variables are invariant.

typing.AnyStr

AnyStr is a constrained type variable defined as AnyStr = TypeVar('AnyStr', str, bytes).

Su objetivo es ser usada por funciones que pueden aceptar cualquier tipo de cadena de texto sin permitir mezclar diferentes tipos al mismo tiempo. Por ejemplo:

def concat(a: AnyStr, b: AnyStr) -> AnyStr:
    return a + b

concat(u"foo", u"bar")  # Ok, output has type 'unicode'
concat(b"foo", b"bar")  # Ok, output has type 'bytes'
concat(u"foo", b"bar")  # Error, cannot mix unicode and bytes

class typing.Protocol(Generic)

Clase base para clases protocolo. Las clases protocolo se definen así:

class Proto(Protocol):
    def meth(self) -> int:
        ...

Tales clases son usadas principalmente con validadores estáticos de tipos que detectan subtipado estructural (duck-typing estático), por ejemplo:

class C:
    def meth(self) -> int:
        return 0

def func(x: Proto) -> int:
    return x.meth()

func(C())  # Passes static type check

Véase PEP 544 [https://www.python.org/dev/peps/pep-0544] para más detalles. Las clases protocolo decoradas con runtime_checkable() (que se explica más adelante) se comportan como protocolos simplistas en tiempo de ejecución que solo comprueban la presencia de atributos dados, ignorando su firma de tipo.

Las clases protocolo pueden ser genéricas, por ejemplo:

class GenProto(Protocol[T]):
    def meth(self) -> T:
        ...

Nuevo en la versión 3.8.

@typing.runtime_checkable

Marca una clase protocolo como aplicable en tiempo de ejecución (lo convierte en un runtime protocol).

Tal protocolo se puede usar con isinstance() y issubclass(). Esto lanzará una excepción TypeError cuando se aplique a una clase que no es un protocolo. Esto permite una comprobación estructural simple, muy semejante a «one trick ponies» en collections.abc con Iterable. Por ejemplo:

@runtime_checkable
class Closable(Protocol):
    def close(self): ...

assert isinstance(open('/some/file'), Closable)

Nota

runtime_checkable() comprobará únicamente la presencia de los métodos requeridos, no sus firmas de tipo! Por ejemplo, builtins.complex implementa __float__(), por lo cual pasaría la comprobación issubclass() contra SupportsFloat. Sin embargo, el método complex.__float__ existe únicamente para lanzar un TypeError con un mensaje más informativo.

Nuevo en la versión 3.8.

Otras directivas especiales

Estos no son utilizados en anotaciones. Son utilizados como bloques para crear tipos genéricos.

class typing.NamedTuple

Versión para anotación de tipos de collections.namedtuple().

Uso:

class Employee(NamedTuple):
    name: str
    id: int

Esto es equivalente a:

Employee = collections.namedtuple('Employee', ['name', 'id'])

Para proporcionar a un campo un valor por defecto se puede asignar en el cuerpo de la clase:

class Employee(NamedTuple):
    name: str
    id: int = 3

employee = Employee('Guido')
assert employee.id == 3

Los campos con un valor por defecto deben ir después de los campos sin valor por defecto.

The resulting class has an extra attribute __annotations__ giving a dict that maps the field names to the field types. (The field names are in the _fields attribute and the default values are in the _field_defaults attribute, both of which are part of the namedtuple() API.)

Las subclases de NamedTuple también pueden tener docstrings y métodos:

class Employee(NamedTuple):
    """Represents an employee."""
    name: str
    id: int = 3

    def __repr__(self) -> str:
        return f'<Employee {self.name}, id={self.id}>'

Uso retrocompatible:

Employee = NamedTuple('Employee', [('name', str), ('id', int)])

Distinto en la versión 3.6: Soporte añadido para la sintaxis de anotación de variables propuesto en PEP 526 [https://www.python.org/dev/peps/pep-0526].

Distinto en la versión 3.6.1: Soporte añadido para valores por defecto, métodos y docstrings.

Distinto en la versión 3.8: Los atributos _field_types y __annotations__ son simples diccionarios en vez de instancias de OrderedDict.

Distinto en la versión 3.9: Se remueve el atributo _field_types en favor del atributo más estándar __annotations__ que tiene la misma información.

typing.NewType(name, tp)

Un función auxiliar para indicar un tipo distinguible a los validadores de tipos, véase NewType. En tiempo de ejecución, retorna una función que retorna su argumento. Uso:

UserId = NewType('UserId', int)
first_user = UserId(1)

Nuevo en la versión 3.5.2.

class typing.TypedDict(dict)

Es una construcción especial para añadir indicadores de tipo a un diccionario. En tiempo de ejecución es un dict simple.

TypedDict crea un tipo de diccionario que espera que todas sus instancias tenga un cierto conjunto de claves, donde cada clave está asociada con un valor de un tipo determinado. Esta exigencia no se comprueba en tiempo de ejecución y solo es aplicada por validadores de tipo. Uso:

class Point2D(TypedDict):
    x: int
    y: int
    label: str

a: Point2D = {'x': 1, 'y': 2, 'label': 'good'}  # OK
b: Point2D = {'z': 3, 'label': 'bad'}           # Fails type check

assert Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first')

To allow using this feature with older versions of Python that do not support PEP 526 [https://www.python.org/dev/peps/pep-0526], TypedDict supports two additional equivalent syntactic forms:

Using a literal dict as the second argument:

Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str})

Using keyword arguments:

Point2D = TypedDict('Point2D', x=int, y=int, label=str)

The functional syntax should also be used when any of the keys are not valid identifiers, for example because they are keywords or contain hyphens. Example:

# raises SyntaxError
class Point2D(TypedDict):
    in: int  # 'in' is a keyword
    x-y: int  # name with hyphens

# OK, functional syntax
Point2D = TypedDict('Point2D', {'in': int, 'x-y': int})

By default, all keys must be present in a TypedDict. It is possible to override this by specifying totality. Usage:

class Point2D(TypedDict, total=False):
    x: int
    y: int

# Alternative syntax
Point2D = TypedDict('Point2D', {'x': int, 'y': int}, total=False)

This means that a Point2D TypedDict can have any of the keys omitted. A type checker is only expected to support a literal False or True as the value of the total argument. True is the default, and makes all items defined in the class body required.

It is possible for a TypedDict type to inherit from one or more other TypedDict types using the class-based syntax. Usage:

class Point3D(Point2D):
    z: int

Point3D has three items: x, y and z. It is equivalent to this definition:

class Point3D(TypedDict):
    x: int
    y: int
    z: int

A TypedDict cannot inherit from a non-TypedDict class, notably including Generic. For example:

class X(TypedDict):
    x: int

class Y(TypedDict):
    y: int

class Z(object): pass  # A non-TypedDict class

class XY(X, Y): pass  # OK

class XZ(X, Z): pass  # raises TypeError

T = TypeVar('T')
class XT(X, Generic[T]): pass  # raises TypeError

A TypedDict can be introspected via __annotations__, __total__, __required_keys__, and __optional_keys__.

__total__

Point2D.__total__ gives the value of the total argument. Example:

>>> from typing import TypedDict
>>> class Point2D(TypedDict): pass
>>> Point2D.__total__
True
>>> class Point2D(TypedDict, total=False): pass
>>> Point2D.__total__
False
>>> class Point3D(Point2D): pass
>>> Point3D.__total__
True

__required_keys__

__optional_keys__

Point2D.__required_keys__ and Point2D.__optional_keys__ return frozenset objects containing required and non-required keys, respectively. Currently the only way to declare both required and non-required keys in the same TypedDict is mixed inheritance, declaring a TypedDict with one value for the total argument and then inheriting it from another TypedDict with a different value for total. Usage:

>>> class Point2D(TypedDict, total=False):
...     x: int
...     y: int
...
>>> class Point3D(Point2D):
...     z: int
...
>>> Point3D.__required_keys__ == frozenset({'z'})
True
>>> Point3D.__optional_keys__ == frozenset({'x', 'y'})
True

Véase PEP 589 [https://www.python.org/dev/peps/pep-0589] para más ejemplos y reglas detalladas del uso de TypedDict.

Nuevo en la versión 3.8.

Colecciones genéricas concretas

Correspondientes a tipos integrados

class typing.Dict(dict, MutableMapping[KT, VT])

Una versión genérica de dict. Útil para anotar tipos de retorno. Para anotar argumentos es preferible usar un tipo abstracto de colección como Mapping.

Este tipo se puede usar de la siguiente manera:

def count_words(text: str) -> Dict[str, int]:
    ...

Obsoleto desde la versión 3.9: builtins.dict ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

class typing.List(list, MutableSequence[T])

Versión genérica de list. Útil para anotar tipos de retorno. Para anotar argumentos es preferible usar un tipo abstracto de colección como Sequence o Iterable.

Este tipo se puede usar del siguiente modo:

T = TypeVar('T', int, float)

def vec2(x: T, y: T) -> List[T]:
    return [x, y]

def keep_positives(vector: Sequence[T]) -> List[T]:
    return [item for item in vector if item > 0]

Obsoleto desde la versión 3.9: builtins.list ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

class typing.Set(set, MutableSet[T])

Una versión genérica de builtins.set. Útil para anotar tipos de retornos. Para anotar argumentos es preferible usar un tipo abstracto de colección como AbstractSet.

Obsoleto desde la versión 3.9: builtins.set ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

class typing.FrozenSet(frozenset, AbstractSet[T_co])

Una versión genérica de builtins.frozenset.

Obsoleto desde la versión 3.9: builtins.frozenset ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

Nota

Tuple es una forma especial.

Correspondiente a tipos en collections

class typing.DefaultDict(collections.defaultdict, MutableMapping[KT, VT])

Una versión genérica de collections.defaultdict.

Nuevo en la versión 3.5.2.

Obsoleto desde la versión 3.9: collections.defaultdict ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

class typing.OrderedDict(collections.OrderedDict, MutableMapping[KT, VT])

Una versión genérica de collections.OrderedDict.

Nuevo en la versión 3.7.2.

Obsoleto desde la versión 3.9: collections.OrderedDict ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

class typing.ChainMap(collections.ChainMap, MutableMapping[KT, VT])

Una versión genérica de collections.ChainMap.

Nuevo en la versión 3.5.4.

Nuevo en la versión 3.6.1.

Obsoleto desde la versión 3.9: collections.ChainMap ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

class typing.Counter(collections.Counter, Dict[T, int])

Una versión genérica de collections.Counter.

Nuevo en la versión 3.5.4.

Nuevo en la versión 3.6.1.

Obsoleto desde la versión 3.9: collections.Counter ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

class typing.Deque(deque, MutableSequence[T])

Una versión genérica de collections.deque.

Nuevo en la versión 3.5.4.

Nuevo en la versión 3.6.1.

Obsoleto desde la versión 3.9: collections.deque ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

Otros tipos concretos

class typing.IO

class typing.TextIO

class typing.BinaryIO

Generic type IO[AnyStr] and its subclasses TextIO(IO[str]) and BinaryIO(IO[bytes]) represent the types of I/O streams such as returned by open().

Deprecated since version 3.8, will be removed in version 3.12: These types are also in the typing.io namespace, which was never supported by type checkers and will be removed.

class typing.Pattern

class typing.Match

These type aliases correspond to the return types from re.compile() and re.match(). These types (and the corresponding functions) are generic in AnyStr and can be made specific by writing Pattern[str], Pattern[bytes], Match[str], or Match[bytes].

Deprecated since version 3.8, will be removed in version 3.12: These types are also in the typing.re namespace, which was never supported by type checkers and will be removed.

Obsoleto desde la versión 3.9: Las clases Pattern y Match de re ahora soportan []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

class typing.Text

Text es un alias para str. Ésta disponible para proporcionar un mecanismo compatible hacia delante para código en Python 2: en Python 2, Text es un alias de unicode.

Úsese Text para indicar que un valor debe contener una cadena de texto Unicode de manera que sea compatible con Python 2 y Python 3:

def add_unicode_checkmark(text: Text) -> Text:
    return text + u' \u2713'

Nuevo en la versión 3.5.2.

Clase base abstracta para tipos genéricos

Correspondientes a las colecciones en collections.abc

class typing.AbstractSet(Sized, Collection[T_co])

Una versión genérica de collections.abc.Set.

Obsoleto desde la versión 3.9: collections.abc.Set ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

class typing.ByteString(Sequence[int])

Una versión genérica de collections.abc.ByteString.

Este tipo representa a los tipos bytes, bytearray, y memoryview de secuencias de bytes.

Como abreviación para este tipo, bytes se puede usar para anotar argumentos de cualquiera de los tipos mencionados arriba.

Obsoleto desde la versión 3.9: collections.abc.ByteString ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

class typing.Collection(Sized, Iterable[T_co], Container[T_co])

Una versión genérica de collections.abc.Collection

Nuevo en la versión 3.6.0.

Obsoleto desde la versión 3.9: collections.abc.Collection ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

class typing.Container(Generic[T_co])

Una versión genérica de collections.abc.Container.

Obsoleto desde la versión 3.9: collections.abc.Container ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

class typing.ItemsView(MappingView, Generic[KT_co, VT_co])

Una versión genérica de collections.abc.ItemsView.

Obsoleto desde la versión 3.9: collections.abc.ItemsView ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

class typing.KeysView(MappingView[KT_co], AbstractSet[KT_co])

Una versión genérica de collections.abc.KeysView.

Obsoleto desde la versión 3.9: collections.abc.KeysView ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

class typing.Mapping(Sized, Collection[KT], Generic[VT_co])

Una versión genérica de collections.abc.Mapping. Este tipo se puede usar de la siguiente manera:

def get_position_in_index(word_list: Mapping[str, int], word: str) -> int:
    return word_list[word]

Obsoleto desde la versión 3.9: collections.abc.Mapping ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

class typing.MappingView(Sized, Iterable[T_co])

Una versión genérica de collections.abc.MappingView.

Obsoleto desde la versión 3.9: collections.abc.MappingView ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

class typing.MutableMapping(Mapping[KT, VT])

Una versión genérica de collections.abc.MutableMapping.

Obsoleto desde la versión 3.9: collections.abc.MutableMapping ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

class typing.MutableSequence(Sequence[T])

Una versión genérica de collections.abc.MutableSequence.

Obsoleto desde la versión 3.9: collections.abc.MutableSequence ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

class typing.MutableSet(AbstractSet[T])

Una versión genérica de collections.abc.MutableSet.

Obsoleto desde la versión 3.9: collections.abc.MutableSet ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

class typing.Sequence(Reversible[T_co], Collection[T_co])

Una versión genérica de collections.abc.Sequence.

Obsoleto desde la versión 3.9: collections.abc.Sequence ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

class typing.ValuesView(MappingView[VT_co])

Una versión genérica de collections.abc.ValuesView.

Obsoleto desde la versión 3.9: collections.abc.ValuesView ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

Correspondiente a otros tipos en collections.abc

class typing.Iterable(Generic[T_co])

Una versión genérica de collections.abc.Iterable.

Obsoleto desde la versión 3.9: collections.abc.Iterable ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

class typing.Iterator(Iterable[T_co])

Una versión genérica de collections.abc.Iterator.

Obsoleto desde la versión 3.9: collections.abc.Iterator ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

class typing.Generator(Iterator[T_co], Generic[T_co, T_contra, V_co])

Un generador puede ser anotado con el tipo genérico Generator[YieldType, SendType, ReturnType]. Por ejemplo:

def echo_round() -> Generator[int, float, str]:
    sent = yield 0
    while sent >= 0:
        sent = yield round(sent)
    return 'Done'

Nótese que en contraste con muchos otros genéricos en el módulo typing, el SendType de Generator se comporta como contravariante, no covariante ni invariante.

Si tu generador solo retornará valores con yield, establece SendType y ReturnType como None:

def infinite_stream(start: int) -> Generator[int, None, None]:
    while True:
        yield start
        start += 1

Opcionalmente, anota tu generador con un tipo de retorno de Iterable[YieldType] o Iterator[YieldType]:

def infinite_stream(start: int) -> Iterator[int]:
    while True:
        yield start
        start += 1

Obsoleto desde la versión 3.9: collections.abc.Generator ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

class typing.Hashable

An alias to collections.abc.Hashable.

class typing.Reversible(Iterable[T_co])

Una versión genérica de collections.abc.Reversible.

Obsoleto desde la versión 3.9: collections.abc.Reversible ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

class typing.Sized

An alias to collections.abc.Sized.

Programación asíncrona

class typing.Coroutine(Awaitable[V_co], Generic[T_co, T_contra, V_co])

Una versión genérica de collections.abc.Coroutine.y orden de las variables de tipo se corresponde con aquellas de Generator, por ejemplo:

from collections.abc import Coroutine
c: Coroutine[list[str], str, int]  # Some coroutine defined elsewhere
x = c.send('hi')                   # Inferred type of 'x' is list[str]
async def bar() -> None:
    y = await c                    # Inferred type of 'y' is int

Nuevo en la versión 3.5.3.

Obsoleto desde la versión 3.9: collections.abc.Coroutine ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

class typing.AsyncGenerator(AsyncIterator[T_co], Generic[T_co, T_contra])

Un generador asíncrono se puede anotar con el tipo genérico AsyncGenerator[YieldType, SendType]. Por ejemplo:

async def echo_round() -> AsyncGenerator[int, float]:
    sent = yield 0
    while sent >= 0.0:
        rounded = await round(sent)
        sent = yield rounded

A diferencia de los generadores normales, los generadores asíncronos no pueden retornar un valor, por lo que no hay un parámetro de tipo``ReturnType``. Igual que Generator, SendType se comporta como contravariante.

Si tu generador solo retornará valores con yield, establece el SendType como None:

async def infinite_stream(start: int) -> AsyncGenerator[int, None]:
    while True:
        yield start
        start = await increment(start)

Opcionalmente, anota el generador con un tipo de retorno AsyncIterable[YieldType] o AsyncIterator[YieldType]:

async def infinite_stream(start: int) -> AsyncIterator[int]:
    while True:
        yield start
        start = await increment(start)

Nuevo en la versión 3.6.1.

Obsoleto desde la versión 3.9: collections.abc.AsycGenerator ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

class typing.AsyncIterable(Generic[T_co])

Una versión genérica de collections.abc.AsyncIterable.

Nuevo en la versión 3.5.2.

Obsoleto desde la versión 3.9: collections.abc.AsyncIterable ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

class typing.AsyncIterator(AsyncIterable[T_co])

Una versión genérica de collections.abc.AsyncIterator.

Nuevo en la versión 3.5.2.

Obsoleto desde la versión 3.9: collections.abc.AsyncIterator ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

class typing.Awaitable(Generic[T_co])

Una versión genérica de collections.abc.Awaitable.

Nuevo en la versión 3.5.2.

Obsoleto desde la versión 3.9: collections.abc.Awaitable ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

Tipos del administrador de contextos

class typing.ContextManager(Generic[T_co])

Una versión genérica de contextlib.AbstractContextManager.

Nuevo en la versión 3.5.4.

Nuevo en la versión 3.6.0.

Obsoleto desde la versión 3.9: contextlib.AbstractContextManager ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

class typing.AsyncContextManager(Generic[T_co])

Una versión genérica de contextlib.AbstractAsyncContextManager.

Nuevo en la versión 3.5.4.

Nuevo en la versión 3.6.2.

Obsoleto desde la versión 3.9: contextlib.AbstractAsyncContextManager ahora soporta []. Véase PEP 585 [https://www.python.org/dev/peps/pep-0585] y Tipo Alias Genérico.

Protocolos

Estos protocolos se decoran con runtime_checkable().

class typing.SupportsAbs

Una ABC con un método abstracto __abs__ que es covariante en su tipo retornado.

class typing.SupportsBytes

Una ABC con un método abstracto __bytes__.

class typing.SupportsComplex

Una ABC con un método abstracto __complex__.

class typing.SupportsFloat

Una ABC con un método abstracto __float__.

class typing.SupportsIndex

Una ABC con un método abstracto __index__.

Nuevo en la versión 3.8.

class typing.SupportsInt

Una ABC con un método abstracto __int__.

class typing.SupportsRound

Una ABC con un método abstracto __round__ que es covariantes en su tipo retornado.

Funciones y decoradores

typing.cast(typ, val)

Convertir un valor a su tipo.

Esto retorna el valor sin modificar. Para el validador de tipos esto indica que el valor de retorno tiene el tipo señalado pero, de manera intencionada, no se comprobará en tiempo de ejecución (para maximizar la velocidad).

@typing.overload

El decorador @overload permite describir funciones y métodos que soportan diferentes combinaciones de tipos de argumento. A una serie de definiciones decoradas con @overload` debe seguir exactamente una definición no decorada con ``@overload (para la misma función o método). Las definiciones decoradas con @overload son solo para beneficio del validador de tipos, ya que serán sobrescritas por la definición no decorada con @overload. Esta última se usa en tiempo de ejecución y debería ser ignorada por el validador de tipos. En tiempo de ejecución, llamar a una función decorada con @overload lanzará directamente NotImplementedError. Un ejemplo de sobrecarga que proporciona un tipo más preciso se puede expresar con una unión o una variable de tipo:

@overload
def process(response: None) -> None:
    ...
@overload
def process(response: int) -> tuple[int, str]:
    ...
@overload
def process(response: bytes) -> str:
    ...
def process(response):
    <actual implementation>

Véase PEP 484 [https://www.python.org/dev/peps/pep-0484] para más detalle, y compárese con otras semánticas de tipado.

@typing.final

Un decorador que indica a los validadores de tipos que el método decorado no se puede sobreescribir, o que la clase decorada no se puede derivar (subclassed). Por ejemplo:

class Base:
    @final
    def done(self) -> None:
        ...
class Sub(Base):
    def done(self) -> None:  # Error reported by type checker
        ...

@final
class Leaf:
    ...
class Other(Leaf):  # Error reported by type checker
    ...

No hay comprobación en tiempo de ejecución para estas propiedades. Véase PEP 591 [https://www.python.org/dev/peps/pep-0591] para más detalles.

Nuevo en la versión 3.8.

@typing.no_type_check

Un decorador para indicar que la anotaciones no deben ser comprobadas como indicadores de tipo.

Esto funciona como un decorator (decorador) de clase o función. Con una clase, se aplica recursivamente a todos los métodos definidos en dichas clase (pero no a lo métodos definidos en sus superclases y subclases).

Esto modifica la función o funciones in situ.

@typing.no_type_check_decorator

Un decorador que asigna a otro decorador el efecto de no_type_check() (no comprobar tipo).

Esto hace que el decorador decorado añada el efecto de no_type_check() a la función decorada.

@typing.type_check_only

Un decorador que marca una clase o función como no disponible en tiempo de ejecución.

Este decorador no está disponible en tiempo de ejecución. Existe principalmente para marcar clases que se definen en archivos stub para cuando una implementación retorna una instancia de una clase privada:

@type_check_only
class Response:  # private or not available at runtime
    code: int
    def get_header(self, name: str) -> str: ...

def fetch_response() -> Response: ...

Nótese que no se recomienda retornar instancias de clases privadas. Normalmente es preferible convertirlas en clases públicas.

Ayudas de introspección

typing.get_type_hints(obj, globalns=None, localns=None, include_extras=False)

Retorna un diccionario que contiene indicaciones de tipo para una función, método, módulo o objeto clase.

Habitualmente, esto es lo mismo que obj.__annotations__. Además, las referencias indicadas como cadenas de texto se gestionan evaluándolas en los espacios de nombres``globals`` y locals. Si es necesario, se añade``Optional[t]`` para anotar una función o método, si se establece None como valor por defecto. Para una clase C, se retorna un diccionario construido por la combinación de __annotations__ y C.__mro en orden inverso.

La función reemplaza todos los Annotated[T, ...] con T de manera recursiva, a menos que include_extras se defina como True ( véase Annotated para más información). Por ejemplo:

class Student(NamedTuple):
    name: Annotated[str, 'some marker']

get_type_hints(Student) == {'name': str}
get_type_hints(Student, include_extras=False) == {'name': str}
get_type_hints(Student, include_extras=True) == {
    'name': Annotated[str, 'some marker']
}

Distinto en la versión 3.9: Se agregan los parámetros include_extras como parte de PEP 593 [https://www.python.org/dev/peps/pep-0593].

typing.get_args(tp)

typing.get_origin(tp)

Provee introspección básica para tipos genéricos y construcciones especiales de tipado.

Para un objeto de tipado de la forma X[Y,Z, ...], estas funciones retornan X y (Y, Z, ...). Si X es un alias genérico para una clase integrada o una clase de collections, se normaliza a su clase original. Si X es una Union o Literal contenidos en otro tipo genérico, el orden de (Y, Z, ...) podría ser distinto al orden de los argumentos originales [Y, Z, ...] debido al cacheo de tipos. Los objetos no soportados retornan None y () correspondientemente. Ejemplos:

assert get_origin(Dict[str, int]) is dict
assert get_args(Dict[int, str]) == (int, str)

assert get_origin(Union[int, str]) is Union
assert get_args(Union[int, str]) == (int, str)

Nuevo en la versión 3.8.

class typing.ForwardRef

A class used for internal typing representation of string forward references. For example, List["SomeClass"] is implicitly transformed into List[ForwardRef("SomeClass")]. This class should not be instantiated by a user, but may be used by introspection tools.

Nota

PEP 585 [https://www.python.org/dev/peps/pep-0585] generic types such as list["SomeClass"] will not be implicitly transformed into list[ForwardRef("SomeClass")] and thus will not automatically resolve to list[SomeClass].

Nuevo en la versión 3.7.4.

Constantes

typing.TYPE_CHECKING

Una constante especial que se asume como cierta (True) por validadores estáticos de tipos de terceros. Es falsa (False) en tiempo de ejecución. Uso:

if TYPE_CHECKING:
    import expensive_mod

def fun(arg: 'expensive_mod.SomeType') -> None:
    local_var: expensive_mod.AnotherType = other_fun()

Nótese que la primera anotación de tipo debe estar rodeada por comillas, convirtiéndola en una «referencia directa», para ocultar al intérprete la referencia expensive_mod en tiempo de ejecución. Las anotaciones de tipo para variables locales no se evalúan, así que la segunda anotación no necesita comillas.

Nota

If from __future__ import annotations is used, annotations are not evaluated at function definition time. Instead, they are stored as strings in __annotations__. This makes it unnecessary to use quotes around the annotation (see PEP 563 [https://www.python.org/dev/peps/pep-0563]).

Nuevo en la versión 3.5.2.

pydoc — Generador de documentación y Sistema de ayuda en línea

Código fuente: Lib/pydoc.py [https://github.com/python/cpython/tree/3.9/Lib/pydoc.py]

El módulo pydoc genera automáticamente documentación de módulos de Python. La documentación se puede presentar como páginas de texto en la consola, servidos en un buscador web, o guardados en archivos HTML.

Para módulos, clases, funciones y métodos, la documentación mostrada es derivada del docstring (i.e. el atributo __doc__) del objeto, y recursivamente de sus miembros que se puedan documentar. Si no existe el docstring, pydoc trata de obtener una descripción del bloque de comentarios arriba de la definición de la clase, función o método en el archivo fuente, o encima del módulo (véase inspect.getcomments()).

La función incorporada help() invoca el sistema de ayuda en línea en el interpretador interactivo, que usa pydoc para generar su documentación como texto en la consola. La misma documentación del texto se puede ver desde afuera del interpretador de python al ejecutar pydoc como un script en la consola del sistema operativo. Por ejemplo, ejecutando

pydoc sys

en la entrada de la consola mostrará la documentación sobre el módulo sys, en un estilo similar a las páginas del manual que se muestran por el comando man de Unix. El argumento de pydoc puede ser el nombre de una función, módulo, o paquete, o una referencia con puntos (dotted reference) de una clase, método, o función dentro de un módulo o módulo en un paquete. Si el argumento de pydoc se parece a una ruta (path) (es decir, que contiene el separador de rutas para tu sistema operativo como una barra en Unix), y hace referencia a un archivo fuente de Python existente, entonces se produce la documentación para ese archivo.

Nota

Para encontrar los objetos y su documentación, pydoc importa el módulo o los módulos que serán documentados. Por lo tanto, cualquier código a nivel de módulo va a ser ejecutado en esa ocasión. Use if __name__=='__main__': como protección para sólo ejecutar código cuando un archivo es invocado como un script y no sólo importado.

Cuando se imprime la salida a la consola, pydoc intenta paginar la salida para una lectura más fácil. Si la variable de entorno PAGER está puesta, pydoc usará su valor como el programa de paginación.

Especificar un bandera (flag) -w antes del argumento hará que la documentación HTML sea escrita en un archivo de la carpeta actual, en vez de mostrar el texto en la consola.

Especificar una bandera (flag) -k antes del argumento buscará las líneas de la sinopsis de todos los módulos disponibles por la palabra clave (keyword) dada como argumento, de nuevo en una manera similar al comando man de Unix. La sinopsis de un módulo es la primera línea de su cadena de documentación.

Puedes usar pydoc para empezar un servidor HTTP en la máquina local que va a servir la documentación para buscadores Web invitados. pydoc -p 1234 empezará un servidor HTTP en el puerto 1234, permitiéndote buscar la documentación en http://localhost:1234/ en tu buscador de preferencia. Especificar 0 como el número de puerto seleccionará un puerto arbitrario no usado.

pydoc -n <hostname> empezará el servidor escuchando al hostname (nombre del servidor) dado. Por defecto, el nombre del servidor es “localhost” pero si quieres que se llegue al servidor desde otras máquinas, quizás quieras cambiar el nombre por el cual el servidor responde. Durante el desarrollo esto es especialmente útil si quieres correr pydoc desde dentro de un contenedor.

pydoc -b empezará un servidor y adicionalmente abrirá un buscador web con una página del índice del módulo. Cada página servida tiene una barra de navegación arriba donde puedes obtener (Get) ayuda sobre una sección individual, buscar (Search) todos los módulos con una palabra clave y sus sinopsis, e ir a las páginas del índice del módulo (Module index), temas (Topics), y palabras clave (Keywords).

Cuando pydoc genera la documentación, se usa el entorno y ruta actual para localizar los módulos. Así, invocar pydoc spam precisamente documenta la versión del módulo que tu obtendrías si empezaras el interpretador de Python y escribieras import spam.

Se asume que la documentación del módulos principales residen en https://docs.python.org/X.Y/library/ donde X y Y son la versión mayor y menor de tu interpretador de Python. Esto puede ser sobre-escrito al poner a la variable de entorno PYTHONDOCS una URL diferente o un directorio local conteniendo la páginas de referencia.

Distinto en la versión 3.2: Se añadió la opción -b.

Distinto en la versión 3.3: La opción de la línea de comandos -g se eliminó.

Distinto en la versión 3.4: pydoc ahora usa inspect.signature() en vez de inspect.getfullargspec() para extraer la información distintiva de los invocables (callables).

Distinto en la versión 3.7: Se añadió la opción -n.

Modo de desarrollo de Python

Nuevo en la versión 3.7.

El modo de desarrollo de Python introduce comprobaciones adicionales en tiempo de ejecución que son muy costosas para ser activadas por defecto. No debería ser más verboso que el predeterminado si el código es correcto; sólo se emiten nuevas advertencias cuando se detecta un problema.

Puede activarse mediante la opción de línea de comandos -X dev o estableciendo la variable de entorno PYTHONDEVMODE en 1.

Efectos del modo de desarrollo de Python

Activar el modo de desarrollo de Python es similar al siguiente comando, pero con efectos adicionales que se describen a continuación:

PYTHONMALLOC=debug PYTHONASYNCIODEBUG=1 python3 -W default -X faulthandler

Efectos del modo de desarrollo de Python:

Añadir default filtro de avisos.Se muestran las siguientes advertencias:

DeprecationWarning

ImportWarning

PendingDeprecationWarning

ResourceWarning

Normalmente, los advertencias son filtradas por defecto warning filters.

Se comporta como si se utilizara la opción de línea de comandos -W default.

Utilice la opción de línea de comandos -W error o establezca la variable de entorno PYTHONWARNINGS en error para tratar las advertencias como errores.

Instalar hooks(enganches) de depuración en los asignadores de memoria para comprobar:

Desbordamiento del búfer

Sobrecarga del búfer

Violación de la API del asignador de memoria

Uso inseguro del GIL

Ver la función en C PyMem_SetupDebugHooks().

Se comporta como si la variable de entorno PYTHONMALLOC estuviera establecida en debug.

Para activar el modo de desarrollo de Python sin instalar ganchos de depuración en los asignadores de memoria, establezca la variable de entorno PYTHONMALLOC a default.

Llama a faulthandler.enable() al inicio de Python para instalar los handlers(manejadores) de las señales SIGSEGV, SIGFPE, SIGABRT, SIGBUS y SIGILL para volcar la traza de Python en caso de fallo.

Se comporta como si se utilizara la opción de línea de comandos -X faulthandler o si la variable de entorno PYTHONFAULTHANDLER se establece en 1.

Habilitar asyncio debug mode. Por ejemplo, asyncio comprueba las corutinas que no fueron esperadas y las registra.

Se comporta como si la variable de entorno PYTHONASYNCIODEBUG estuviera establecida en 1.

Comprueba los argumentos encoding y errors para las operaciones de codificación y decodificación de cadenas. Ejemplos: open(), str.encode() y bytes.decode().

Por defecto, para un mejor rendimiento, el argumento errors sólo se comprueba en el primer error de codificación/decodificación y el argumento encoding a veces se ignora para las cadenas vacías.

El destructor de io.IOBase registra las excepciones close().

Establece el atributo dev_mode de sys.flags a True.

El Modo de Desarrollo de Python no habilita el módulo tracemalloc por defecto, porque el costo de la sobrecarga (para el rendimiento y la memoria) sería demasiado grande. Activar el módulo tracemalloc proporciona información adicional sobre el origen de algunos errores. Por ejemplo, ResourceWarning registra la traza donde se asignó el recurso, y un error de desbordamiento de búfer registra la traza donde se asignó el bloque de memoria.

El modo de desarrollo de Python no impide que la opción de línea de comandos -O elimine las declaraciones assert ni que establezca __debug__ a False.

Distinto en la versión 3.8: El destructor de io.IOBase ahora registra las excepciones close().

Distinto en la versión 3.9: Los argumentos enconding y errors se comprueban ahora para las operaciones de codificación y descodificación de cadenas.

Ejemplo de ResourceWarning

Ejemplo de un script que cuenta el número de líneas del archivo de texto especificado en la línea de comandos:

import sys

def main():
    fp = open(sys.argv[1])
    nlines = len(fp.readlines())
    print(nlines)
    # The file is closed implicitly

if __name__ == "__main__":
    main()

El script no cierra el archivo explícitamente. Por defecto, Python no emite ninguna advertencia. Ejemplo usando README.txt, que tiene 269 líneas:

$ python3 script.py README.txt
269

Al activar el modo de desarrollo de Python aparece una advertencia ResourceWarning:

$ python3 -X dev script.py README.txt
269
script.py:10: ResourceWarning: unclosed file <_io.TextIOWrapper name='README.rst' mode='r' encoding='UTF-8'>
  main()
ResourceWarning: Enable tracemalloc to get the object allocation traceback

Además, al activar tracemalloc se muestra la línea en la que se abrió el archivo:

$ python3 -X dev -X tracemalloc=5 script.py README.rst
269
script.py:10: ResourceWarning: unclosed file <_io.TextIOWrapper name='README.rst' mode='r' encoding='UTF-8'>
  main()
Object allocated at (most recent call last):
  File "script.py", lineno 10
    main()
  File "script.py", lineno 4
    fp = open(sys.argv[1])

La solución es cerrar explícitamente el archivo. Ejemplo utilizando un gestor de contexto:

def main():
    # Close the file explicitly when exiting the with block
    with open(sys.argv[1]) as fp:
        nlines = len(fp.readlines())
    print(nlines)

No cerrar un recurso explícitamente puede dejar un recurso abierto durante mucho más tiempo del estimado; puede causar graves problemas al salir de Python. Es malo en CPython, pero es aún peor en PyPy. Cerrar los recursos explícitamente hace que una aplicación sea más detallista y más fiable.

Ejemplo de error de descriptor de archivo incorrecto

Script que muestra la primera línea de sí mismo:

import os

def main():
    fp = open(__file__)
    firstline = fp.readline()
    print(firstline.rstrip())
    os.close(fp.fileno())
    # The file is closed implicitly

main()

Por defecto, Python no emite ninguna advertencia:

$ python3 script.py
import os

El modo de desarrollo de Python muestra un ResourceWarning y registra un error «Bad file descriptor» cuando termina el objeto archivo:

$ python3 script.py
import os
script.py:10: ResourceWarning: unclosed file <_io.TextIOWrapper name='script.py' mode='r' encoding='UTF-8'>
  main()
ResourceWarning: Enable tracemalloc to get the object allocation traceback
Exception ignored in: <_io.TextIOWrapper name='script.py' mode='r' encoding='UTF-8'>
Traceback (most recent call last):
  File "script.py", line 10, in <module>
    main()
OSError: [Errno 9] Bad file descriptor

os.close(fp.fileno()) cierra el descriptor de archivo. Cuando el finalizador de objetos de archivo intenta cerrar el descriptor de archivo de nuevo, falla con el error Bad file descriptor. Un descriptor de archivo debe cerrarse sólo una vez. En el peor de los casos, cerrarlo dos veces puede provocar un fallo (ver bpo-18748 [https://bugs.python.org/issue?@action=redirect&bpo=18748] para un ejemplo).

La solución es eliminar la línea os.close(fp.fileno()), o abrir el archivo con closefd=False.

doctest – Prueba ejemplos interactivos de Python

Código fuente: Lib/doctest.py [https://github.com/python/cpython/tree/3.9/Lib/doctest.py]

El módulo doctest busca pedazos de texto que lucen como sesiones interactivas de Python, y entonces ejecuta esas sesiones para verificar que funcionen exactamente como son mostradas. Hay varias maneras de usar doctest:

Para revisar que los docstrings de un módulo están al día al verificar que todos los ejemplos interactivos todavía trabajan como está documentado.

Para realizar pruebas de regresión al verificar que los ejemplos interactivos de un archivo de pruebas o un objeto de pruebas trabaje como sea esperado.

Para escribir documentación de tutorial para un paquete, generosamente ilustrado con ejemplos de entrada-salida. Dependiendo si los ejemplos o el texto expositivo son enfatizados, tiene el sabor de «pruebas literarias» o «documentación ejecutable».

Aquí hay un módulo de ejemplo completo pero pequeño:

"""
This is the "example" module.

The example module supplies one function, factorial().  For example,

>>> factorial(5)
120
"""

def factorial(n):
    """Return the factorial of n, an exact integer >= 0.

    >>> [factorial(n) for n in range(6)]
    [1, 1, 2, 6, 24, 120]
    >>> factorial(30)
    265252859812191058636308480000000
    >>> factorial(-1)
    Traceback (most recent call last):
        ...
    ValueError: n must be >= 0

    Factorials of floats are OK, but the float must be an exact integer:
    >>> factorial(30.1)
    Traceback (most recent call last):
        ...
    ValueError: n must be exact integer
    >>> factorial(30.0)
    265252859812191058636308480000000

    It must also not be ridiculously large:
    >>> factorial(1e100)
    Traceback (most recent call last):
        ...
    OverflowError: n too large
    """

    import math
    if not n >= 0:
        raise ValueError("n must be >= 0")
    if math.floor(n) != n:
        raise ValueError("n must be exact integer")
    if n+1 == n:  # catch a value like 1e300
        raise OverflowError("n too large")
    result = 1
    factor = 2
    while factor <= n:
        result *= factor
        factor += 1
    return result

if __name__ == "__main__":
    import doctest
    doctest.testmod()

Si tu ejecutas example.py directamente desde la línea de comandos, doctest hará su magia:

$ python example.py
$

¡No hay salida! Eso es normal, y significa que todos los ejemplos funcionaron. Pasa -v al script, y doctest imprime un registro detallado de lo que está intentando, e imprime un resumen al final:

$ python example.py -v
Trying:
    factorial(5)
Expecting:
    120
ok
Trying:
    [factorial(n) for n in range(6)]
Expecting:
    [1, 1, 2, 6, 24, 120]
ok

Y demás, eventualmente terminando con:

Trying:
    factorial(1e100)
Expecting:
    Traceback (most recent call last):
        ...
    OverflowError: n too large
ok
2 items passed all tests:
   1 tests in __main__
   8 tests in __main__.factorial
9 tests in 2 items.
9 passed and 0 failed.
Test passed.
$

¡Eso es todo lo que necesitas saber para empezar a hacer uso productivo de doctest! Lánzate. Las siguientes secciones proporcionan detalles completos. Note que hay muchos ejemplos de doctests en el conjunto de pruebas estándar de Python y bibliotecas. Especialmente ejemplos útiles se pueden encontrar en el archivo de pruebas estándar Lib/test/test_doctest.py.

Uso simple: verificar ejemplos en docstrings

La forma más simple para empezar a usar doctest (pero no necesariamente la forma que continuarás usándolo) es terminar cada módulo M con:

if __name__ == "__main__":
    import doctest
    doctest.testmod()

doctest entonces examina docstrings en el módulo M.

Ejecutar el módulo como un script causa que los ejemplos en los docstrings se ejecuten y verifiquen:

python M.py

No mostrará nada a menos que un ejemplo falle, en cuyo caso el ejemplo fallido o ejemplos fallidos y sus causas de la falla son imprimidas a stdout, y la línea final de salida es ***Test Failed*** N failures., donde N es el número de ejemplos que fallaron.

Ejecútalo con el modificador -v en su lugar:

python M.py -v

y un reporte detallado de todos los ejemplos intentados es impreso a la salida estándar, junto con resúmenes clasificados al final.

Puedes forzar el modo verboso al pasar verbose=True a testmod(), o prohibirlo al pasarlo verbose=False. En cualquiera de estas casos, sys.argv no es examinado por testmod() (por lo que pasar o no -v, no tiene efecto).

También hay un atajo de línea de comandos para ejecutar testmod(). Puedes instruir al intérprete de Python para ejecutar el módulo doctest directamente de la biblioteca estándar y pasar los nombres del módulo en la línea de comandos:

python -m doctest -v example.py

Esto importará example.py como un módulo independiente y ejecutará a testmod(). Note que esto puede no funcionar correctamente si el archivo es parte de un paquete e importa otros submódulos de ese paquete.

Para más información de testmod(), véase la sección API básica.

Uso Simple: Verificar ejemplos en un Archivo de Texto

Otra simple aplicación de doctest es probar ejemplos interactivos en un archivo de texto. Esto puede ser hecho con la función testfile():

import doctest
doctest.testfile("example.txt")

Este script corto ejecuta y verifica cualquier ejemplo interactivo de Python contenido en el archivo example.txt. El contenido del archivo es tratado como si fuese un solo gran docstring; ¡el archivo no necesita contener un programa de Python! Por ejemplo, tal vez example.txt contenga esto:

The ``example`` module
======================

Using ``factorial``
-------------------

This is an example text file in reStructuredText format.  First import
``factorial`` from the ``example`` module:

    >>> from example import factorial

Now use it:

    >>> factorial(6)
    120

Ejecutar doctest.testfile("example.txt") entonces encuentra el error en esta documentación:

File "./example.txt", line 14, in example.txt
Failed example:
    factorial(6)
Expected:
    120
Got:
    720

Como con testmod(), testfile() no mostrará nada a menos que un ejemplo falle. Si un ejemplo no falla, entonces los ejemplos fallidos y sus causas son impresas a stdout, usando el mismo formato como testmod().

Por defecto, testfile() busca archivos en el directorio del módulo al que se llama. Véase la sección API básica para una descripción de los argumentos opcionales que pueden ser usados para decirle que busque archivos en otros lugares.

Como testmod(), la verbosidad de testfile() puede ser establecida con el modificador de la línea de comandos -v o con el argumento por palabra clave opcional verbose.

También hay un atajo de línea de comandos para ejecutar testfile(). Puedes indicar al intérprete de Python para correr el módulo doctest directamente desde la biblioteca estándar y pasar el nombre de los archivos en la línea de comandos:

python -m doctest -v example.txt

Porque el nombre del archivo no termina con .py, doctest infiere que se debe ejecutar con testfile(), no testmod().

Para más información en testfile(), véase la sección API básica.

Cómo funciona

Esta sección examina en detalle cómo funciona doctest: qué docstrings revisa, cómo encuentra ejemplos interactivos, qué contexto de ejecución usa, cómo maneja las excepciones, y cómo las banderas pueden ser usadas para controlar su comportamiento. Esta es la información que necesitas saber para escribir ejemplos de doctest; para información sobre ejecutar doctest en estos ejemplos, véase las siguientes secciones.

¿Qué docstrings son examinados?

Se busca en el docstring del módulo, y todos los docstrings de las funciones, clases, y métodos. Los objetos importados en el módulo no se buscan.

Además, si M.__test__ existe y «es verdaderos», debe ser un diccionario, y cada entrada mapea un nombre (cadena de caracteres) a un objeto de función, objeto de clase, o cadena de caracteres. Se buscan los docstrings de los objetos de función o de clase encontrados de M.__test__, y las cadenas de caracteres son tratadas como si fueran docstrings. En la salida, una clave K en M.__test__ aparece con el nombre:

<name of M>.__test__.K

Todas las clases encontradas se buscan recursivamente de manera similar, para probar docstrings en sus métodos contenidos y clases anidadas.

CPython implementation detail: Prior to version 3.4, extension modules written in C were not fully searched by doctest.

¿Cómo se reconocen los ejemplos de docstring?

En la mayoría de los casos un copiar y pegar de una sesión de consola interactiva funciona bien, pero doctest no está intentando hacer una emulación exacta de ningún shell específico de Python.

>>> # comments are ignored
>>> x = 12
>>> x
12
>>> if x == 13:
...     print("yes")
... else:
...     print("no")
...     print("NO")
...     print("NO!!!")
...
no
NO
NO!!!
>>>

Cualquier salida esperada debe seguir inmediatamente el final de la línea '>>>' o '...' conteniendo el código, y la salida esperada (si la hubiera) se extiende hasta el siguiente '>>>' o la línea en blanco.

La letra pequeña:

La salida esperada no puede contener una línea de espacios en blanco, ya que ese tipo de línea se toma para indicar el fin de la salida esperada. Si la salida esperada de verdad contiene una línea en blanco, pon <BLANKLINE> en tu ejemplo de doctest en cada lugar donde una línea en blanco sea esperada.

Todos los caracteres de tabulación se expanden a espacios, usando paradas de tabulación de 8 -columnas. Las tabulaciones generadas por el código en pruebas no son modificadas. Ya que todas las tabulaciones en la salida de prueba son expandidas, significa que si el código de salida incluye tabulaciones, la única manera de que el doctest pueda pasar es si la opción NORMALIZE_WHITESPACE o directive está en efecto. Alternativamente, la prueba puede ser reescrita para capturar la salida y compararla a un valor esperado como parte de la prueba. Se llegó a este tratamiento de tabulaciones en la fuente a través de prueba y error, y ha demostrado ser la manera menos propensa a errores de manejarlos. Es posible usar un algoritmo diferente para manejar tabulaciones al escribir una clase DocTestParser personalizada.

La salida a stdout es capturada, pero no la salida a stderr (los rastreos de la excepción son capturados a través de maneras diferentes).

Si continuas una línea poniendo una barra invertida en una sesión interactiva, o por cualquier otra razón usas una barra invertida, debes usar un docstring crudo, que preservará tus barras invertidas exactamente como las escribes:

>>> def f(x):
...     r'''Backslashes in a raw docstring: m\n'''
>>> print(f.__doc__)
Backslashes in a raw docstring: m\n

De otra manera, la barra invertida será interpretada como parte de una cadena. Por ejemplo, el \n arriba sería interpretado como un carácter de nueva línea. Alternativamente, puedes duplicar cada barra invertida en la versión de doctest (y no usar una cadena de caracteres cruda):

>>> def f(x):
...     '''Backslashes in a raw docstring: m\\n'''
>>> print(f.__doc__)
Backslashes in a raw docstring: m\n

La columna inicial no importa:

>>> assert "Easy!"
      >>> import math
          >>> math.floor(1.9)
          1

y tantos espacios en blanco al principio se eliminan de la salida esperada como aparece en la línea '>>>' inicial que empezó el ejemplo.

¿Cuál es el contexto de ejecución?

Por defecto, cada vez que un doctest encuentre un docstring para probar, usa una copia superficial de los globales de M, por lo que ejecutar pruebas no cambia los globales reales del módulo, y por lo que una prueba en M no puede dejar atrás migajas que permitan a otras pruebas trabajar. Significa que los ejemplos pueden usar libremente cualquier nombre definido en el nivel superior en M, y nombres definidos más temprano en los docstrings siendo ejecutados. Los ejemplos no pueden ver nombres definidos en otros docstrings.

Puedes forzar el uso de tus propios diccionarios como contexto de ejecución al pasar globs=your_dict a testmod() o testfile() en su lugar.

¿Y las excepciones?

No hay problema, siempre que el rastreo sea la única salida producida por el ejemplo: sólo copia el rastreo. 1 Ya que los rastreos contienen detalles que probablemente cambien rápidamente (por ejemplo, rutas de archivos exactas y números de línea), este es un caso donde doctest trabaja duro para ser flexible en lo que acepta.

Ejemplo simple:

>>> [1, 2, 3].remove(42)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: list.remove(x): x not in list

El doctest tiene éxito si se lanza ValueError, con el detalle list.remove(x): x not in list como se muestra.

La salida esperada para una excepción debe empezar con una cabecera de rastreo, que puede ser una de las siguientes dos líneas, con el mismo sangrado de la primera línea del ejemplo:

Traceback (most recent call last):
Traceback (innermost last):

La cabecera de rastreo es seguida por una pila de rastreo opcional, cuyo contenido es ignorado por doctest. La pila de rastreo es típicamente omitida, o copiada palabra por palabra de una sesión interactiva.

La pila de rastreo es seguida por la parte más interesante: la línea o líneas conteniendo el tipo de excepción y detalle. Esto es usualmente la última línea de un rastreo, pero se puede extender a través de múltiples líneas si la excepción tiene un detalle de varias líneas:

>>> raise ValueError('multi\n    line\ndetail')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: multi
    line
detail

Las últimas tres líneas (empezando con ValueError) son comparados con el tipo de excepción y detalle, y el resto es ignorado.

La mejor práctica es omitir la pila de rastreo, a menos que añada valor de documentación significante al ejemplo. Por lo que el último ejemplo es probablemente mejor como:

>>> raise ValueError('multi\n    line\ndetail')
Traceback (most recent call last):
    ...
ValueError: multi
    line
detail

Note que los rastreos son tratados de manera especial. En particular, en el ejemplo reescrito, el uso de ... es independiente de la opción ELLIPSIS de doctest. Se pueden excluir los puntos suspensivos en ese ejemplo, así como también pueden haber tres (o trescientas) comas o dígitos, o una transcripción sangrada de un sketch de Monty Python.

Algunos detalles que debes leer una vez, pero no necesitarás recordar:

Doctest no puede adivinar si tu salida esperada vino de una excepción de rastreo o de una impresión ordinaria. Así que, un ejemplo que espera ValueError: 42 is prime pasará, ya sea si de hecho se lance ValueError o si el ejemplo simplemente imprime ese texto de rastreo. En la práctica, la salida ordinaria raramente comienza con una línea de cabecera de rastreo, por lo que esto no crea problemas reales.

Cada línea de la pila de rastreo (si se presenta) debe estar más sangrada que la primera línea del ejemplo, o empezar con un carácter no alfanumérico. la primera línea que sigue a la cabecera de rastreo sangrada de igual forma y empezando con un alfanumérico es considerado el inicio del detalle de la excepción. Por supuesto que esto es lo correcto para rastreos genuinos.

Cuando se especifica la opción IGNORE_EXCEPTION_DETAIL de doctest. todo lo que sigue a los dos puntos más a la izquierda y cualquier otra información del módulo en el nombre de la excepción se ignora.

El shell interactivo omite la línea de la cabecera de rastreo para algunos SyntaxError. Pero doctest usa la línea de la cabecera de rastreo para distinguir excepciones de los que no son. Así que en algunos casos raros donde necesitas probar un SyntaxError que omite la cabecera de rastreo, necesitarás poner manualmente la línea de cabecera de rastreo en tu ejemplo de prueba.

Para algunos SyntaxError, Python muestra la posición del carácter del error de sintaxis, usando un marcador ^:

>>> 1 1
  File "<stdin>", line 1
    1 1
      ^
SyntaxError: invalid syntax

Ya que las líneas mostrando la posición del error vienen antes del tipo de excepción y detalle, no son revisadas por doctest. Por ejemplo, el siguiente test pasaría, a pesar de que pone el marcador ^ en la posición equivocada:

>>> 1 1
Traceback (most recent call last):
  File "<stdin>", line 1
    1 1
    ^
SyntaxError: invalid syntax

Banderas de Opción

Varias banderas de opción controlan diversos aspectos del comportamiento de doctest. Los nombres simbólicos para las banderas son proporcionados como constantes del módulo, que se pueden conectar mediante *OR* bit a bit y pasar a varias funciones. Los nombres también pueden ser usados en las directivas de doctest, y se pueden pasar a la interfaz de la línea de comandos de doctest a través de la opción -o.

Nuevo en la versión 3.4: La opción de la línea de comandos -o.

El primer grupo de opciones definen las semánticas de la prueba, controlando aspectos de cómo doctest decide si la salida de hecho concuerda con la salida esperada del ejemplo:

doctest.DONT_ACCEPT_TRUE_FOR_1

Por defecto, si un bloque de salida esperada contiene sólo 1, se considera igual a un bloque de salida real conteniendo sólo 1 o true, y similarmente para 0 contra False. Cuando se especifica DONT_ACCEPT_TRUE_FOR_1`, no se permite ninguna sustitución. El comportamiento por defecto atiende a que Python cambió el tipo de retorno de muchas funciones de enteros a booleanos; los doctest esperando salidas «de pequeño enteros» todavía trabajan en estos casos. Esta opción probablemente se vaya, pero no por muchos años.

doctest.DONT_ACCEPT_BLANKLINE

Por defecto, si un bloque de salida esperada contiene una línea que sólo tiene la cadena de caracteres <BLANKLINE>, entonces esa línea corresponderá a una línea en blanco en la salida real. Ya que una línea en blanca auténtica delimita la salida esperada, esta es la única manera de comunicar que una línea en blanco es esperada. Cuando se especifica DONT_ACCEPT_BLANKLINE, esta substitución no se permite.

doctest.NORMALIZE_WHITESPACE

Cuando se especifica, todas las secuencias de espacios en blanco (vacías y nuevas líneas) son tratadas como iguales. Cualquier secuencia de espacios en blanco dentro de la salida esperada corresponderá a cualquier secuencia de espacios en blanco dentro de la salida real. Por defecto, los espacios en blanco deben corresponderse exactamente. NORMALIZE_WHITESPACE es especialmente útil cuando una línea de la salida esperada es muy larga, y quieres envolverla a través de múltiples líneas en tu código fuente.

doctest.ELLIPSIS

Cuando se especifica, un marcador de puntos suspensivos (...) en la salida esperada puede corresponder a cualquier cadena de caracteres en la salida real. Esto incluye las cadenas de caracteres que abarcan límites de líneas, y cadenas de caracteres vacías, por lo que es mejor mantener su uso simple. Usos complicados pueden conducir a los mismo tipos de sorpresa de «ups, coincidió demasiado» que .* es propenso a hacer en expresiones regulares.

doctest.IGNORE_EXCEPTION_DETAIL

When specified, doctests expecting exceptions pass so long as an exception of the expected type is raised, even if the details (message and fully-qualified exception name) don’t match.

For example, an example expecting ValueError: 42 will pass if the actual exception raised is ValueError: 3*14, but will fail if, say, a TypeError is raised instead. It will also ignore any fully-qualified name included before the exception class, which can vary between implementations and versions of Python and the code/libraries in use. Hence, all three of these variations will work with the flag specified:

>>> raise Exception('message')
Traceback (most recent call last):
Exception: message

>>> raise Exception('message')
Traceback (most recent call last):
builtins.Exception: message

>>> raise Exception('message')
Traceback (most recent call last):
__main__.Exception: message

Note that ELLIPSIS can also be used to ignore the details of the exception message, but such a test may still fail based on whether the module name is present or matches exactly.

Distinto en la versión 3.2: IGNORE_EXCEPTION_DETAIL también ignora cualquier información relacionada al módulo conteniendo la excepción bajo prueba.

doctest.SKIP

Cuando se especifica, no ejecuta el ejemplo del todo. Puede ser útil en contextos donde los ejemplos de doctest sirven como documentación y casos de prueba a la vez, y un ejemplo debe ser incluido para propósitos de documentación, pero no debe ser revisado. P. ej., la salida del ejemplo puede ser aleatoria, o el ejemplo puede depender de recursos que no estarían disponibles para el controlador de pruebas.

La bandera SKIP también se puede usar para temporalmente «quitar» ejemplos.

doctest.COMPARISON_FLAGS

Una máscara de bits o juntadas lógicamente todas las banderas de arriba.

El segundo grupo de opciones controla cómo las fallas de las pruebas son reportadas:

doctest.REPORT_UDIFF

Cuando se especifica, las fallas que involucran salidas multilínea esperadas y reales son mostradas usando una diferencia (diff) unificada.

doctest.REPORT_CDIFF

Cuando se especifica, las fallas que involucran salidas multilínea esperadas y reales se mostrarán usando una diferencia (diff) contextual.

doctest.REPORT_NDIFF

Cuando se especifica, las diferencias son computadas por difflib.Differ, usando el mismo algoritmo que la popular utilidad ndiff.py. Este es el único método que marca diferencias dentro de líneas también como a través de líneas. Por ejemplo, si una línea de salida esperada contiene el dígito 1 donde la salida actual contiene la letra l, se inserta una línea con una marca de inserción marcando la posición de las columnas que no coinciden.

doctest.REPORT_ONLY_FIRST_FAILURE

Cuando se especifica, muestra el primer ejemplo fallido en cada doctest, pero suprime la salida para todos ejemplos restantes. Esto evitará que doctest reporte los ejemplos correctos que se rompen por causa de fallos tempranos; pero también puede esconder ejemplos incorrectos que fallen independientemente de la primera falla. Cuando se especifica REPORT_ONLY_FIRST_FAILURE, los ejemplos restantes aún se ejecutan, y aún cuentan para el número total de fallas reportadas, sólo se suprime la salida.

doctest.FAIL_FAST

Cuando se especifica, sale después del primer ejemplo fallido y no intenta ejecutar los ejemplos restantes. Por consiguiente, el número de fallas reportadas será como mucho 1. Esta bandera puede ser útil durante la depuración, ya que los ejemplos después de la primera falla ni siquiera producirán salida de depuración.

La línea de comandos de doctest acepta la opción -f como un atajo para -o FAIL_FAST.

Nuevo en la versión 3.4.

doctest.REPORTING_FLAGS

Una máscara de bits o todas las banderas de reporte arriba combinadas.

También hay una manera de registrar nombres de nuevas opciones de banderas, aunque esto no es útil a menos que intentes extender doctest a través de herencia:

doctest.register_optionflag(name)

Crea una nueva bandera de opción con un nombre dado, y retorna el valor entero de la nueva bandera. se puede usar register_optionflag() cuando se hereda OutputChecker o DocTestRunner para crear nuevas opciones que sean compatibles con tus clases heredadas. register_optionflag() siempre debe ser llamado usando la siguiente expresión:

MY_FLAG = register_optionflag('MY_FLAG')

Directivas

Se pueden usar las directivas de doctest para modificar las banderas de opción para un ejemplo individual. Las directivas de doctest son comentarios de Python especiales que siguen el código fuente de un ejemplo:

directive             ::=  "#" "doctest:" directive_options
directive_options     ::=  directive_option ("," directive_option)\*
directive_option      ::=  on_or_off directive_option_name
on_or_off             ::=  "+" \| "-"
directive_option_name ::=  "DONT_ACCEPT_BLANKLINE" \| "NORMALIZE_WHITESPACE" \| ...

No se permite el espacio en blanco entre el + o - y el nombre de la opción de directiva (directive option name). El nombre de la opción de directiva puede ser cualquiera de los nombres de las banderas de opciones explicadas arriba.

Las directivas de doctest de un ejemplo modifican el comportamiento de doctest para ese único ejemplo. Usa + para habilitar el comportamiento nombrado, o - para deshabilitarlo.

Por ejemplo, esta prueba pasa:

>>> print(list(range(20)))
[0,   1,  2,  3,  4,  5,  6,  7,  8,  9,
10,  11, 12, 13, 14, 15, 16, 17, 18, 19]

Sin la directiva esto fallaría, porque la salida real no tiene dos espacios en blanco antes los elementos de la lista de un dígito, y porque la salida real está en una sola línea. Esta prueba también pasa, y también requiere directivas para hacerlo:

>>> print(list(range(20)))
[0, 1, ..., 18, 19]

Se pueden usar múltiples directivas en una sola línea física, separadas por comas:

>>> print(list(range(20)))
[0,    1, ...,   18,    19]

Si múltiples directivas se usan para un sólo ejemplo, entonces son combinadas:

>>> print(list(range(20)))
...
[0,    1, ...,   18,    19]

Como muestran los ejemplos previos, puedes añadir líneas de ... a tus ejemplos conteniendo sólo directivas. Puede ser útil cuando un ejemplo es demasiado largo para que una directiva pueda caber cómodamente en la misma línea:

>>> print(list(range(5)) + list(range(10, 20)) + list(range(30, 40)))
...
[0, ..., 4, 10, ..., 19, 30, ..., 39]

Tenga en cuenta que ya que todas las opciones están deshabilitadas por defecto, y las directivas sólo aplican a los ejemplos en los que aparecen, habilitarlas (a través de + en la directiva) usualmente es la única opción significativa. Sin embargo, las banderas de opciones también pueden ser pasadas a funciones que ejecutan doctests, estableciendo valores por defecto diferentes. En tales casos, deshabilitar una opción a través de - en una directiva puede ser útil.

Advertencias

doctest es serio acerca de requerir coincidencias exactas en la salida esperada. Si incluso un solo carácter no coincide, el test falla. Esto probablemente te sorprenderá algunas veces, mientras aprendes exactamente lo que Python asegura y no asegura sobre la salida. Por ejemplo, cuando se imprime un conjunto, Python no asegura que el elemento sea impreso en ningún orden particular, por lo que una prueba como

>>> foo()
{"Hermione", "Harry"}

¡es vulnerable! Una solución puede ser hacer

>>> foo() == {"Hermione", "Harry"}
True

es su lugar. Otra es hacer

>>> d = sorted(foo())
>>> d
['Harry', 'Hermione']

Nota

Antes de Python 3.6, cuando se imprime un diccionario, Python no aseguraba que los pares de claves y valores sean impresos en ningún orden en particular.

Existen otros casos, pero ya captas la idea.

Otra mala idea es imprimir cosas que incorporan una dirección de un objeto, como

>>> id(1.0) # certain to fail some of the time
7948648
>>> class C: pass
>>> C()   # the default repr() for instances embeds an address
<__main__.C instance at 0x00AC18F0>

La directiva ELLIPSIS da un buen enfoque para el último ejemplo:

>>> C()
<__main__.C instance at 0x...>

Los números de coma flotante también son sujetos a pequeñas variaciones de la salida a través de las plataformas, porque Python defiere a la librería C de la plataforma para el formato de flotantes, y las librerías de C varían extensamente en calidad aquí.

>>> 1./7  # risky
0.14285714285714285
>>> print(1./7) # safer
0.142857142857
>>> print(round(1./7, 6)) # much safer
0.142857

Números de la forma I/2.**J son seguros a lo largo de todas las plataformas, y yo frecuentemente planeo ejemplos de doctest para producir números de esa forma:

>>> 3./4  # utterly safe
0.75

Las facciones simples también son más fáciles de entender para las personas, y eso conduce a una mejor documentación.

API básica

Las funciones testmod() y testfile() proporcionan una interfaz simple para doctest que debe ser suficiente para la mayoría de los usos básicos. Para una introducción menos formal a estas funciones, véase las secciones Uso simple: verificar ejemplos en docstrings y Uso Simple: Verificar ejemplos en un Archivo de Texto.

doctest.testfile(filename, module_relative=True, name=None, package=None, globs=None, verbose=None, report=True, optionflags=0, extraglobs=None, raise_on_error=False, parser=DocTestParser(), encoding=None)

Todos los argumentos excepto filename son opcionales, y deben ser especificados en forma de palabras claves.

Prueba los ejemplos en el archivo con nombre filename. Retorna (failure_count, test_count).

El argumento opcional module_relative especifica cómo el nombre de archivo debe ser interpretado:

Si module_relative es True (el valor por defecto), entonces filename especifica una ruta relativa al módulo que es independiente del SO. Por defecto, esta ruta es relativa al directorio del módulo que lo invoca; pero si el argumento package es especificado, entonces es relativo a ese paquete. Para asegurar la independencia del SO, filename debe usar caracteres / para separar segmentos, y no puede ser una ruta absoluta (por ejemplo., no puede empezar con /).

Si module_relative es False, entonces filename especifica una ruta especifica del SO. La ruta puede ser absoluta o relativa; las rutas relativas son resueltas con respecto al directorio de trabajo actual.

El argumento opcional name proporciona el nombre de la prueba; por defecto, o si es None, se usa os.path.basename(filename).

El argumento opcional package es un paquete de Python o el nombre de una paquete de Python cuyo directorio debe ser usado como el directorio base para un nombre de archivo relativo al módulo. Si no se especifica ningún paquete, entonces el directorio del módulo que invoca se usa como el directorio base para los nombres de archivos relativos al módulo. Es un error especificar package si module_relative es False.

El argumento opcional globs proporciona un diccionario a ser usado como los globales cuando se ejecuten los ejemplos. Se crea una nueva copia superficial de este diccionario para el doctest, por lo que sus ejemplos empiezan con una pizarra en blanco. Por defecto, o si es None, se usa un nuevo diccionario vacío.

El argumento opcional extraglobs proporciona un diccionario mezclado con los globales usados para ejecutar ejemplos. Funciona como dict.update(): si globs y extraglobs tienen una clave en común, el valor asociado en extraglobs aparece en el diccionario combinado. Por defecto, o si es None, no se usa ninguna variable global. Es una característica avanzada que permite la parametrización de doctests. Por ejemplo, un doctest puede ser escribo para una clase base, usando un nombre genérico para la clase, y luego reusado para probar cualquier número de clases heredadas al pasar un diccionario de extraglobs mapeando el nombre genérico a la clase heredada para ser probada.

El argumento opcional verbose imprime un montón de cosas si es verdadero, e imprime sólo las fallas si es falso; por defecto, o si es None, es verdadero si y sólo si '-v' está en sys.argv.

El argumento opcional report imprime un resumen al final cuando es verdadero; si no, no imprime nada al final. En modo verboso (verbose), el resumen es detallado; si no, el resumen es muy corto (de hecho, vacío si todos las pruebas pasan).

El argumento opcional optionflags (valor por defecto 0) toma las banderas de opciones juntadas lógicamente por un OR. Véase la sección Banderas de Opción.

El argumento opcional raise_on_error tiene como valor por defecto false. Si es true, se levanta una excepción sobre la primera falla o excepción no esperada en un ejemplo. Esto permite que los fallos sean depurados en un análisis a posteriori. El comportamiento por defecto es continuar corriendo los ejemplos.

El argumento opcional parser especifica un DocTestParser (o subclase) que debe ser usado para extraer las pruebas de los archivos. Su valor por defecto es un analizador sintáctico normal (i.e., DocTestParser()).

El argumento opcional encoding especifica una codificación que debe ser usada para convertir el archivo a unicode.

doctest.testmod(m=None, name=None, globs=None, verbose=None, report=True, optionflags=0, extraglobs=None, raise_on_error=False, exclude_empty=False)

Todos los argumentos son opcionales, y todos excepto por m deben ser especificados en forma de palabras claves.

Prueba los ejemplos en los docstring de las funciones y clases alcanzables desde el módulo m (o desde el módulo __main__ si m no es proporcionado o es None), empezando con m.__doc__.

También prueba los ejemplos alcanzables desde el diccionario de m.__test__, si existe y no es None. m.__test__ mapea los nombres (cadenas de caracteres) a funciones, clases y cadenas de caracteres; se buscan los ejemplos de las funciones y clases; se buscan las cadenas de caracteres directamente como si fueran docstrings.

Sólo se buscan los docstrings anexados a los objetos pertenecientes al módulo m.

Retorna (failure_count, test_count).

El argumento opcional name proporciona el nombre del módulo; por defecto, o si es None, se usa m.__name__.

El argumento opcional exclude_empty es por defecto false. Si es verdadero, se excluyen los objetos por los cuales no se encuentren doctest. El valor por defecto es un hack de compatibilidad hacia atrás, por lo que el código que use doctest.master.summarize() en conjunto con testmod() continua obteniendo la salida para objetos sin pruebas. El argumento exclude_empty para el más nuevo constructor DocTestFinder es por defecto verdadero.

Los argumentos opcionales extraglobs, verbose, report, optionflags, raise_on_error, y globs son los mismos en cuanto a la función testfile() arriba, excepto que globs es por defecto m.__dict__.

doctest.run_docstring_examples(f, globs, verbose=False, name="NoName", compileflags=None, optionflags=0)

Prueba los ejemplos asociados con el objeto f; por ejemplo, f puede ser una cadena de caracteres, un módulo, una función, o un objeto clase.

Una copia superficial del diccionario del argumento globs se usa para la ejecución del contexto.

Se usa el argumento opcional name en mensajes de fallos, y por defecto es "NoName".

Si el argumento opcional verbose es verdadero, la salida se genera incluso si no hay fallas. Por defecto, la salida se genera sólo en caso de la falla de un ejemplo.

El argumento opcional compileflags proporciona el conjunto de banderas que se deben usar por el compilador de Python cuando se corran los ejemplos. Por defecto, o si es None, las banderas se deducen correspondiendo al conjunto de características futuras encontradas en globs.

El argumento opcional optionflags trabaja con respecto a la función testfile() de arriba.

API de unittest

Mientras crece tu colección de módulos probados con doctest, vas a querer una forma de ejecutar todos sus doctests sistemáticamente. doctest proporciona dos funciones que se pueden usar para crear un banco de pruebas (test suite) de unittest desde módulos y archivos de texto que contienen doctests. Para integrarse con el descubrimiento de pruebas de unittest , incluye una función load_tests() en tu módulo de pruebas:

import unittest
import doctest
import my_module_with_doctests

def load_tests(loader, tests, ignore):
    tests.addTests(doctest.DocTestSuite(my_module_with_doctests))
    return tests

Hay dos funciones principales para crear instancias de unittest.TestSuite desde los archivos de texto y módulos con doctests:

doctest.DocFileSuite(*paths, module_relative=True, package=None, setUp=None, tearDown=None, globs=None, optionflags=0, parser=DocTestParser(), encoding=None)

Convierte las pruebas de doctest de uno o más archivos de texto a una unittest.TestSuite.

El unittest.TestSuite que se retorne será ejecutado por el framework de unittest y ejecuta los ejemplos interactivos en cada archivo. Si un ejemplo en cualquier archivo falla, entonces la prueba unitaria sintetizada falla, y una excepción failureException se lanza mostrando el nombre del archivo conteniendo la prueba y un número de línea (algunas veces aproximado).

Pasa una o más rutas (como cadenas de caracteres) a archivos de texto para ser examinados.

Se pueden proporcionar las opciones como argumentos por palabra clave:

El argumento opcional module_relative especifica cómo los nombres de archivos en paths se deben interpretar:

Si module_relative is True (el valor por defecto), entonces cada archivo de nombre en paths especifica una ruta relativa al módulo independiente del SO. Por defecto, esta ruta es relativa al directorio del módulo lo está invocando; pero si se especifica el argumento package, entonces es relativo a ese paquete. Para asegurar la independencia del SO, cada nombre de archivo debe usar caracteres / para separar los segmentos de rutas, y puede no ser una ruta absoluta (i.e., puede no empezar con /).

Si module_relative es False, entonces cada archivo de nombre en paths especifica una ruta especifica al SO. La ruta puede ser absoluta o relativa; las rutas relativas son resueltas con respecto a directorio de trabajo actual.

El argumento opcional package es un paquete de Python o el nombre de un paquete de Python cuyo directorio debe ser usado como el directorio base para los nombres de archivos relativos al módulo en paths. Si no se especifica ningún paquete, entonces el directorio del módulo que lo está invocando se usa como el directorio base para los archivos de nombres relativos al módulo. Es un error especificar package si module_relative es False.

El argumento opcional setUp especifica una función de configuración para el banco de pruebas. Es invocado antes de ejecutar las pruebas en cada archivo. La función setUp se pasará a un objeto DocTest. La función setUp puede acceder a las variables globales de prueba como el atributo globs de la prueba pasada.

El argumento opcional tearDown especifica una función de destrucción para el banco de pruebas. Es invocado después de ejecutar las pruebas en cada archivo. Se pasará un objeto DocTest a la función tearDown. La función setUp de configuración puede acceder a los globales de la prueba como el atributo globs de la prueba pasada.

El argumento opcional globs es un diccionario que contiene las variables globales iniciales para las pruebas. Se crea una nueva copia de este diccionario para cada prueba. Por defecto, globs es un nuevo diccionario vacío.

El argumento opcional optionflags especifica las opciones de doctest por defecto para las pruebas, creado al juntar lógicamente las opciones de bandera individuales. Véase la sección Banderas de Opción. Véase la función set_unittest_reportflags() abajo para una mejor manera de definir las opciones de informe.

El argumento opcional parser especifica un DocTestParser (o subclase) que debe ser usado para extraer las pruebas de los archivos. Su valor por defecto es un analizador sintáctico normal (i.e., DocTestParser()).

El argumento opcional encoding especifica una codificación que debe ser usada para convertir el archivo a unicode.

Se añade el global __file__ a los globales proporcionados a los doctests cargados desde un archivo de texto usando DocFileSuite().

doctest.DocTestSuite(module=None, globs=None, extraglobs=None, test_finder=None, setUp=None, tearDown=None, checker=None)

Convierte las pruebas de doctest para un módulo a un unittest.TestSuite.

El unittest.TestSuite que se retorne será ejecutado por el framework de unittest y corre cada doctest en el módulo. Si cualquiera de los doctests falla, entonces la prueba unitaria combinada falla, y se lanza una excepción failureException mostrando el nombre del archivo que contiene la prueba y un número de línea (a veces aproximado).

El argumento opcional module proporciona el módulo a probar. Puede ser un objeto de módulo o un nombre (posiblemente punteado) de módulo. Si no se especifica, se usa el módulo que invoca esta función.

El argumento opcional globs es un diccionario que contiene las variables globales iniciales para las pruebas. Se crea una nueva copia de este diccionario para cada prueba. Por defecto, globs es un nuevo diccionario vacío.

El argumento opcional extraglobs especifica un conjunto de variables globales adicionales que son mezcladas con globs. Por defecto, no se usa ningún global adicional.

El argumento opcional test_finder es el objeto DocTestFinder (o un reemplazo directo) que se usa para extraer doctests desde el módulo.

Los argumentos opcionales setUp, tearDown, y optionflags son lo mismo con respecto a la función DocFileSuite() arriba.

Esta función usa la misma técnica de búsqueda que testmod().

Distinto en la versión 3.5: DocTestSuite() retorna un unittest.TestSuite vacío si module no contiene ningún docstring en vez de lanzar un ValueError.

Por detrás, DocTestSuite() crea un unittest.TestSuite de las instancias de doctest.DocTestCase, y DocTestCase es una subclase de unittest.TestCase. DocTestCase no está documentado aquí (es un detalle interno), pero estudiar su código puede responder preguntas sobre los detalles exactos de la integración de unittest.

De manera similar, DocFileSuite() crea un unittest.TestSuite de las instancias de doctest.DocFileCase, y DocFileCase es una subclase de DocTestCase.

Por lo que ambas formas de crear un unittest.TestSuite ejecutan instancias de DocTestCase. Esto es importante por una razón sutil: cuando ejecutas las funciones de doctest por ti mismo, puedes controlar las opciones de doctest en uso directamente, al pasar las banderas de opciones a las funciones de doctest. Sin embargo, si estás escribiendo un framework de unittest, básicamente unittest controla cuándo y cómo se ejecutan las pruebas. El autor del framework típicamente, quiere controlar las opciones de reporte de doctest (quizás, p.ej., especificadas por las opciones de la línea de comandos), pero no hay forma de pasar opciones a través de unittest al probador de ejecución (test runner) de doctest.

Por esta razón, doctest también admite una noción de banderas de informe de doctest específicas para la compatibilidad con unittest, a través de esta función:

doctest.set_unittest_reportflags(flags)

Establece las banderas de informe de doctest a usar.

El argumento flags toma la combinación por el operador OR de las banderas de opciones. Véase la sección Banderas de Opción. Sólo se pueden usar las «banderas de informe».

Esta es una configuración global del módulo, y afecta a todos los doctests futuros a ejecutar por unittest: el método runTest() de DocTestCase revisa las banderas de opciones especificadas para el caso de prueba cuando la instancia de DocTestCase fue construida. Si no se especificó ninguna bandera de informe (que es el caso típico y esperado), las banderas de informe -pertenecientes a doctest- de unittest son combinadas por la operación Or en las banderas de opciones, y las banderas de opciones aumentadas se pasan a la instancia de DocTestRunner creada para ejecutar los doctest. Si se especificó alguna bandera de informe cuando el DocTestCase fue construido, se ignoran las banderas de informe -pertenecientes a doctest- de unittest.

La función retorna el valor de las banderas de informe de unittest en efecto antes de que la función fuera invocada.

API avanzada

La API básica es un simple envoltorio que sirve para hacer los doctest fáciles de usar. Es bastante flexible, y debe cumplir las necesidades de la mayoría de los usuarios; si requieres un control más preciso en las pruebas, o deseas extender las capacidades de doctest, entonces debes usar la API avanzada.

La API avanzada gira en torno a dos clases contenedoras, que se usan para guardar los ejemplos interactivos extraídos de los casos doctest:

Example: Un statement de Python, emparejado con su salida esperada.

DocTest: Una colección de clases Example, típicamente extraídos de un sólo docstring o archivo de texto.

Se definen clases de procesamiento adicionales para encontrar, analizar sintácticamente, y ejecutar, y comprobar ejemplos de doctest:

DocTestFinder: Encuentra todos los docstrings en un módulo dado, y usa un DocTestParser para crear un DocTest de cada docstring que contiene ejemplos interactivos.

DocTestParser: Crea un objeto DocTest de una cadena de caracteres (tal como un docstring de un objeto).

DocTestRunner: Ejecuta los ejemplos en un DocTest, y usa un OutputChecker para verificar su salida.

OutputChecker: Compara la salida real de un ejemplo de doctest con la salida esperada, y decide si coinciden.

Las relaciones entre estas clases de procesamiento se resumen en el siguiente diagrama:

                            list of:
+------+                   +---------+
|module| --DocTestFinder-> | DocTest | --DocTestRunner-> results
+------+    |        ^     +---------+     |       ^    (printed)
            |        |     | Example |     |       |
            v        |     |   ...   |     v       |
           DocTestParser   | Example |   OutputChecker
                           +---------+

Objetos DocTest

class doctest.DocTest(examples, globs, name, filename, lineno, docstring)

Una colección de ejemplos de doctest que deben ejecutarse en un sólo nombre de espacios. Se usan los argumentos del constructor para inicializar los atributos de los mismos nombres.

DocTest define los siguientes atributos. Son inicializados por el constructor, y no deben ser modificados directamente.

examples

Una lista de objetos Example codificando los ejemplos interactivos de Python individuales que esta prueba debe ejecutar.

globs

El nombre de espacios (alias globals) en que los ejemplos se deben ejecutar. Este es un diccionario que mapea nombres a valores. Cualquier cambio al nombre de espacios hecho por los ejemplos (tal como juntar nuevas variables) se reflejará en globs después de que se ejecute la prueba.

name

Un nombre de cadena de caracteres que identifica el DocTest. Normalmente, este es el nombre del objeto o archivo del que se extrajo la prueba.

filename

El nombre del archivo del que se extrajo este DocTest; o None si el nombre del archivo se desconoce, o si DocTest no se extrajo de un archivo.

lineno

El número de línea dentro de filename donde este DocTest comienza, o None si el número de línea no está disponible. Este número de línea es comienza en 0 con respecto al comienzo del archivo.

docstring

La cadena de caracteres del que se extrajo la cadena, o None si la cadena no está disponible, o si la prueba no se extrajo de una cadena de caracteres.

Objetos Example

class doctest.Example(source, want, exc_msg=None, lineno=0, indent=0, options=None)

Un sólo ejemplo interactivo, que consta de una sentencia de Python y su salida esperada. Los argumentos del constructor se usan para inicializar los atributos del mismo nombre.

La clase Example define los siguientes atributos. Son inicializados por el constructor, y no deben ser modificados directamente.

source

Una cadena de caracteres que contiene el código fuente del ejemplo. Este código fuente consiste de una sola sentencia Python, y siempre termina en una nueva línea; el constructor añade una nueva línea cuando sea necesario.

want

La salida esperada de ejecutar el código fuente del ejemplo (o desde la salida estándar, o un seguimiento en caso de una excepción). wants termina con una nueva línea a menos que no se espera ninguna salida, en cuyo caso es una cadena vacía. El constructor añade una nueva línea cuando sea necesario.

exc_msg

El mensaje de excepción que el ejemplo genera, si se espera que el ejemplo genere una excepción; o None si no se espera que genere una excepción. Se compara este mensaje de excepción con el valor de retorno de traceback.format_exception_only(). exc_msg termina con una nueva línea a menos que sea None. El constructor añade una nueva línea si se necesita.

lineno

El número de línea dentro de la cadena de caracteres que contiene este ejemplo donde el ejemplo comienza. Este número de línea comienza en 0 con respecto al comienzo de la cadena que lo contiene.

indent

La sangría del ejemplo en la cadena que lo contiene; i.e., el número de caracteres de espacio que preceden la primera entrada del ejemplo.

options

Un diccionario que mapea de las banderas de opciones a True o False, que se usa para anular las opciones por defecto para este ejemplo. Cualquier bandera de opción que no contiene este diccionario se deja con su valor por defecto (como se especifica por los optionflags de DocTestRunner). Por defecto, no se establece ninguna opción.

Objetos DocTestFinder

class doctest.DocTestFinder(verbose=False, parser=DocTestParser(), recurse=True, exclude_empty=True)

Una clase de procesamiento que se usa para extraer los DocTest que son relevantes para un objeto dado, desde su docstring y los docstring de sus objetos contenidos. Se puede extraer los DocTest de los módulos, clases, funciones, métodos, métodos estáticos, métodos de clase, y propiedades.

Se puede usar el argumento opcional verbose para mostrar los objetos buscados por finder. Su valor por defecto es False (ninguna salida).

El argumento opcional parser especifica el objeto DocTestParser (o un reemplazo directo) que se usa para extraer doctests desde docstrings.

Si el argumento opcional recurse es falso, entonces el método DocTestFinder.find() sólo examinará el objeto dado, y no cualquier objeto contenido.

Si el argumento opcional exclude_empty es falso, entonces DocTestFinder.find() incluirá pruebas para objetos con docstrings vacíos.

DocTestFinder define los siguientes métodos:

find(obj[, name][, module][, globs][, extraglobs])

Retorna una lista de los Doctest que se definen por el docstring de obj, o por cualquiera de los docstring de sus objetos contenidos.

El argumento opcional name especifica el nombre del objeto; este nombre será usado para construir los nombres de los DocTest retornados. Si name no se especifica, entonces se usa obj.__name__.

El parámetro opcional module es el módulo que contiene el objeto dado. Si no se especifica el módulo o si es None, entonces el buscador de pruebas tratará de determinar automáticamente el módulo correcto. Se usa el módulo del objeto:

Como un espacio de nombres por defecto, si no se especifica globs.

Para evitar que DocTestFinder extraiga DocTests desde objetos que se importan desde otros módulos. (Se ignoran objetos contenidos con módulos aparte de module.)

Para encontrar el nombre del archivo conteniendo el objeto.

Para ayudar a encontrar el número de línea del objeto dentro de su archivo.

Si module es falso, no se hará ningún intento de encontrar el módulo. Es poco claro, de uso mayormente para probar doctest en si mismo: si module es False, o es None pero no se puede encontrar automáticamente, entonces todos los objetos se consideran que pertenecen al módulo (inexistente), por lo que todos los objetos contenidos se buscarán (recursivamente) por doctests.

Los globales para cada DocTest se forma al combinar globs y extraglobs (los enlaces en extraglobs anulan los enlaces en globs). Se crea una nueva copia superficial del diccionario de globales para cada DocTest. Si globs no se especifica, entonces su valor por defecto es el __dict__ del módulo, si se especifica, o es {} de lo contrario, si extraglobs no se especifica, entonces su valor por defecto es {}.

Objetos DocTestParser

class doctest.DocTestParser

Un clase de procesamiento usada para extraer ejemplos interactivos de una cadena de caracteres, y usarlos para crear un objeto DocTest.

DocTestParser define los siguientes métodos:

get_doctest(string, globs, name, filename, lineno)

Extrae todos los ejemplos de doctest de una cadena dada, y los recolecta en un objeto DocTest.

globs, name, filename, y lineno son atributos para el nuevo objeto DocTest. Véase la documentación de DocTest para más información.

get_examples(string, name='<string>')

Extrae todos los ejemplos de la cadena de caracteres dada, y los retorna como una lista de objetos Example. Los números de línea empiezan en 0. El argumento opcional name es una nombre identificando esta cadena, y sólo es usada para mensajes de errores.

parse(string, name='<string>')

Divide el string dado en ejemplos y texto intermedio, y los retorna como una lista que alterna entre objetos Example y cadenas de caracteres. Los números de línea para los objetos Example empiezan en 0. El argumento opcional name es un nombre identificando esta cadena, y sólo se usa en mensajes de error.

Objetos DocTestRunner

class doctest.DocTestRunner(checker=None, verbose=None, optionflags=0)

Una clase de procesamiento usada para ejecutar y verificar los ejemplos interactivos en un DocTest.

La comparación entre salidas esperadas y salidas reales se hace por un OutputChecker. Esta comparación puede ser personalizada con un número de banderas de opción; véase la sección Banderas de Opción para más información. Si las banderas de opción son insuficientes, entonces la comparación también puede ser personalizada al pasar una subclase de OutputChecker al constructor.

La salida de la pantalla del test runner se puede controlar de dos maneras. Primero, se puede pasar una función de salida a TestRunner.run(); esta función se invocará con cadenas que deben mostrarse. Su valor por defecto es sys.stdout.write. Si no es suficiente capturar el resultado, entonces la salida de la pantalla también se puede personalizar al heredar de DocTestRunner, y sobreescribir los métodos report_start(), report_success(), report_unexpected_exception(), y report_failure().

El argumento por palabra clave opcional checker especifica el objeto OutputChecker (o un reemplazo directo) que se debe usar para comparar las salidas esperadas con las salidas reales de los ejemplos de doctest.

El argumento por palabra clave opcional verbose controla la verbosidad de DocTestRunner. Si verbose es True, entonces la información de cada ejemplo se imprime , mientras se ejecuta. Si verbose es False, entonces sólo las fallas se imprimen. Si verbose no se especifica, o es None, entonces la salida verbosa se usa si y sólo se usa el modificador de la línea de comandos``-v``.

El argumento por palabra clave opcional optionflags se puede usar para controlar cómo el test runner compara la salida esperada con una salida real, y cómo muestra las fallas. Para más información, véase la sección Banderas de Opción.

DocTestParser define los siguientes métodos:

report_start(out, test, example)

Notifica que el test runner está a punto de procesar el ejemplo dado. Este método es proporcionado para permitir que clases heredadas de DocTestRunner personalicen su salida; no debe ser invocado directamente.

example es el ejemplo a punto de ser procesado. test es la prueba que contiene a example. out es la función de salida que se pasó a DocTestRunner.run().

report_success(out, test, example, got)

Notifica que el ejemplo dado se ejecutó correctamente. Este método es proporcionado para permitir que las clases heredadas de DocTestRunner personalicen su salida; no debe ser invocado directamente.

example es el ejemplo a punto de ser procesado. got es la salida real del ejemplo. test es la prueba conteniendo example. out es la función de salida que se pasa a DocTestRunner.run().

report_failure(out, test, example, got)

Notifica que el ejemplo dado falló. Este método es proporcionado para permitir que clases heredadas de DocTestRunner personalicen su salida; no debe ser invocado directamente.

example es el ejemplo a punto de ser procesado. got es la salida real del ejemplo. test es la prueba conteniendo example. out es la función de salida que se pasa a DocTestRunner.run().

report_unexpected_exception(out, test, example, exc_info)

Notifica que el ejemplo dado lanzó una excepción inesperada. Este método es proporcionado para permitir que las clases heredadas de DocTestRunner personalicen su salida; no debe ser invocado directamente.

example es el ejemplo a punto de ser procesado, exc_info es una tupla que contiene información sobre la excepción inesperada (como se retorna por sys.exc_info()). test es la prueba conteniendo example. out es la función de salida que debe ser pasada a DocTestRunner.run().

run(test, compileflags=None, out=None, clear_globs=True)

Ejecuta los ejemplos en test (un objeto DocTest), y muestra los resultados usando función de escritura out.

Los ejemplo se ejecutan en el espacio de nombres test.globs. Si clear_globs es verdadero (el valor por defecto), entonces este espacio de nombres será limpiado después de la prueba se ejecute, para ayudar con la colección de basura. Si quisieras examinar el espacio de nombres después de que la prueba se complete, entonces use clear_globs=False.

compileflags da el conjunto de banderas que se deben usar por el compilador de Python cuando se ejecutan los ejemplos. Si no se especifica, entonces su valor por defecto será el conjunto de banderas de future-import que aplican a globs.

La salida de cada ejemplo es revisada usando el output checker del DocTestRunner, y los resultados se formatean por los métodos de DocTestRunner.report_*().

summarize(verbose=None)

Imprime un resumen de todos los casos de prueba que han sido ejecutados por este DocTestRunner, y retorna un named tuple TestResults(failed, attempted).

El argumento opcional verbose controla qué tan detallado es el resumen. Si no se especifica la verbosidad, entonces se usa la verbosidad de DocTestRunner.

Objetos OutputChecker

class doctest.OutputChecker

Una clase que se usa para verificar si la salida real de un ejemplo de doctest coincide con la salida esperada. OutputChecker define dos métodos: check_output(), que compara un par de salidas dadas, y retorna True si coinciden; y output_difference(), que retorna una cadena que describe las diferencias entre las dos salidas.

OutputChecker define los siguientes métodos:

check_output(want, got, optionflags)

Retorna True si y sólo si la salida real de un ejemplo (got) coincide con la salida esperada (want). Siempre se considera que estas cadenas coinciden si son idénticas; pero dependiendo de qué banderas de opción el test runner esté usando, varias coincidencias inexactas son posibles. Véase la sección Banderas de Opción para más información sobre las banderas de opción.

output_difference(example, got, optionflags)

Retorna una cadena que describe las diferencias entre la salida esperada para un ejemplo dado (example) y la salida real (got). optionflags es el conjunto de banderas de opción usado para comparar want y got.

Depuración

Doctest proporciona varios mecanismos para depurar los ejemplos de doctest:

Varias funciones convierten los doctest en programas de Python ejecutables, que pueden ser ejecutadas bajo el depurador de Python, pdb.

La clase DebugRunner es una subclase de DocTestRunner que lanza una excepción por el primer ejemplo fallido, conteniendo información sobre ese ejemplo. Esta información se puede usar para realizar depuración a posteriori en el ejemplo.

Los casos de unittest generados por DocTestSuite() admiten el método debug() definido por unittest.TestCase.

Puedes añadir una llamada a pdb.set_trace() en un ejemplo de doctest, y bajarás al depurador de Python cuando esa línea sea ejecutada. Entonces puedes inspeccionar los valores de las variables, y demás. Por ejemplo, supongamos que a.py contiene sólo este docstring de módulo:

"""
>>> def f(x):
...     g(x*2)
>>> def g(x):
...     print(x+3)
...     import pdb; pdb.set_trace()
>>> f(3)
9
"""

Entonces una sesión interactiva puede lucir como esta:

>>> import a, doctest
>>> doctest.testmod(a)
--Return--
> <doctest a[1]>(3)g()->None
-> import pdb; pdb.set_trace()
(Pdb) list
  1     def g(x):
  2         print(x+3)
  3  ->     import pdb; pdb.set_trace()
[EOF]
(Pdb) p x
6
(Pdb) step
--Return--
> <doctest a[0]>(2)f()->None
-> g(x*2)
(Pdb) list
  1     def f(x):
  2  ->     g(x*2)
[EOF]
(Pdb) p x
3
(Pdb) step
--Return--
> <doctest a[2]>(1)?()->None
-> f(3)
(Pdb) cont
(0, 3)
>>>

Funciones que convierten los doctest a código de Python, y posiblemente ejecuten el código sintetizado debajo del depurador:

doctest.script_from_examples(s)

Convierte texto con ejemplos a un script.

El argumento s es una cadena que contiene los ejemplos de doctest. La cadena se convierte a un script de Python, donde los ejemplos de doctest en s se convierten en código regular, y todo lo demás se convierte en comentarios de Python. El script generado se retorna como una cadena: Por ejemplo,

import doctest
print(doctest.script_from_examples(r"""
    Set x and y to 1 and 2.
    >>> x, y = 1, 2

    Print their sum:
    >>> print(x+y)
    3
"""))

muestra:

# Set x and y to 1 and 2.
x, y = 1, 2
#
# Print their sum:
print(x+y)
# Expected:
## 3

Esta función se usa internamente por otras funciones (véase más abajo), pero también pueden ser útiles cuando quieres transformar una sesión de Python interactiva en un script de Python.

doctest.testsource(module, name)

Convierte el doctest para un objeto en un script.

El argumento module es un objeto módulo, o un nombre por puntos de un módulo, que contiene el objeto cuyos doctest son de interés. El argumento name es el nombre (dentro del módulo) del objeto con los doctest de interés. El resultado es una cadena de caracteres, que contiene el docstring del objeto convertido en un script de Python, como se describe por script_from_examples() arriba. Por ejemplo, si el módulo a.py contiene un función de alto nivel f(), entonces

import a, doctest
print(doctest.testsource(a, "a.f"))

imprime una versión de script del docstring de la función f(), con los doctest convertidos en código, y el resto puesto en comentarios.

doctest.debug(module, name, pm=False)

Depura los doctest para un objeto.

Los argumentos module y name son los mismos que para la función testsource() arriba. El script de Python sintetizado para el docstring del objeto nombrado es escrito en un archivo temporal, y entonces ese archivo es ejecutado bajo el control del depurador de PYthon, pdb.

Se usa una copia superficial de module.__dict__ para el contexto de ejecución local y global.

El argumento opcional pm controla si se usa la depuración post-mortem. Si pm tiene un valor verdadero, el archivo de script es ejecutado directamente, y el depurador está involucrado sólo si el script termina a través del lanzamiento de una excepción. Si lo hace, entonces la depuración post-mortem es invocada, a través de pdb.post_mortem(), pasando el objeto de rastreo desde la excepción sin tratar. Si no se especifica pm, o si es falso, el script se ejecuta bajo el depurador desde el inicio, a través de una llamada de exec() apropiada a pdb.run().

doctest.debug_src(src, pm=False, globs=None)

Depura los doctest en una cadena de caracteres.

Es como la función function debug() arriba, excepto que una cadena de caracteres que contiene los ejemplos de doctest se especifica directamente, a través del argumento src.

El argumento opcional pm tiene el mismo significado como en la función debug() arriba.

El argumento opcional globs proporciona un diccionario a usar como contexto de ejecución local y global. Si no se especifica, o es None, se usa un diccionario vacío. Si se especifica, se usa una copia superficial del diccionario.

La clase DebugRunner, y las excepciones especiales que puede lanzar, son de más interés a los autores de frameworks de pruebas, y sólo serán descritos brevemente aquí. Véase el código fuente, y especialmente el docstring de DebugRunner (¡que es un doctest!) para más detalles:

class doctest.DebugRunner(checker=None, verbose=None, optionflags=0)

Una subclase de DocTestRunner que lanza una excepción tan pronto como se encuentra una falla. Si ocurre una excepción inesperada, se lanza una excepción UnexpectedException, conteniendo la prueba, el ejemplo, y la excepción original. Si la salida no coincide, entonces se lanza una excepción DocTestFailure, conteniendo la prueba, el ejemplo, y la salida real.

Para información sobre los parámetros de construcción y los métodos, véase la documentación para DocTestRunner en la sección API avanzada.

Hay dos excepciones que se pueden lanzar por instancias de DebugRunner:

exception doctest.DocTestFailure(test, example, got)

Una excepción lanzada por DocTestRunner para señalar que la salida real del ejemplo de un doctest no coincidió con su salida esperada. Los argumentos del constructor se usan para inicializar los atributos del mismo nombre.

DocTestFailure define los siguientes atributos:

DocTestFailure.test

El objeto DocTest que estaba siendo ejecutado cuando el ejemplo falló.

DocTestFailure.example

El objeto Example que falló.

DocTestFailure.got

La salida real del ejemplo.

exception doctest.UnexpectedException(test, example, exc_info)

Una excepción lanzada por DocTestRunner para señalar que un ejemplo de doctest lanzó una excepción inesperada. Los argumentos del constructor se usan para inicializar los atributos del mismo nombre.

UnexpectedException define los siguientes atributos:

UnexpectedException.test

El objeto DocTest que estaba siendo ejecutado cuando el ejemplo falló.

UnexpectedException.example

El objeto Example que falló.

UnexpectedException.exc_info

Una tupla que contiene información sobre la excepción inesperada, como es retornado por sys.exc_info().

Plataforma improvisada

Como se menciona en la introducción, doctest ha crecido para tener tres usos primarios:

Verificar los ejemplos en los docstring.

Pruebas de regresión.

Documentación ejecutable / pruebas literarias.

Estos usos tienen diferentes requerimientos, y es importante distinguirlos. En particular, llenar tus docstring con casos de prueba desconocidos conduce a mala documentación.

Cuando se escribe un docstring, escoja ejemplos de docstring con cuidado. Hay un arte para eso que se debe aprender – puede no ser natural al comienzo. Los ejemplos deben añadir valor genuino a la documentación. Un buen ejemplo a menudo puede valer muchas palabras. Si se hace con cuidado, los ejemplos serán invaluables para tus usuarios, y compensarán el tiempo que toma recolectarlos varias veces mientras los años pasan y las cosas cambian. Todavía estoy sorprendido de qué tan frecuente uno de mis ejemplos de doctest paran de funcionar después de un cambio «inofensivo».

Doctest también es una excelente herramienta para pruebas de regresión, especialmente si no escatimas en texto explicativo. Al intercalar prosa y ejemplos, se hace mucho más fácil mantener el seguimiento de lo que realmente se está probando, y por qué. Cuando una prueba falla, buena prosa puede hacer mucho más fácil comprender cuál es el problema, y cómo debe ser arreglado. Es verdad que puedes escribir comentarios extensos en pruebas basadas en código, pero pocos programadores lo hacen. Quizás es porque simplemente doctest hace escribir pruebas mucho más fácil que escribir código, mientras que escribir comentarios en código es mucho más difícil. Pienso que va más allá de eso: la actitud natural cuando se escribe una prueba basada en doctest es que quieres explicar los puntos finos de tu software, e ilustrarlos con ejemplos. Esto naturalmente lleva a archivos de pruebas que empiezan con las características más simples, y lógicamente progresan a complicaciones y casos extremos. Una narrativa coherente es el resultado, en vez de una colección de funciones aisladas que pruebas trozos aislados de funcionalidad aparentemente al azar. Es una actitud diferente, y produce resultados diferentes, difuminando la distinción entre probar y explicar.

Pruebas de regresión se limitan mejor a objetos o archivos dedicados. Hay varias opciones para organizar pruebas:

Escribe archivos de texto que contienen los casos de prueba como ejemplos interactivos, y prueba los archivos usando testfile() o DocFileSuite(). Esto es lo recomendado, aunque es más fácil hacerlo para nuevos proyectos, diseñados desde el comienzo para usar doctest.

Define funciones nombradas _regrtest_topic que consisten en docstrings únicas, que contienen casos de prueba por los tópicos nombrados. Estas funciones se pueden incluir en el mismo archivo que el módulo, o separadas en un archivo de prueba separado.

Define un diccionario __test__ que asigna desde temas de prueba de integración a los docstring que contienen casos de prueba.

Cuando has puesto tus pruebas en un módulo, el módulo puede ser el mismo test runner. Cuando una prueba falla, puedes hacer que tu test runner vuelva a ejecutar sólo los doctest fallidos mientras que tu depuras el problema. Aquí hay un ejemplo mínimo de tal test runner:

if __name__ == '__main__':
    import doctest
    flags = doctest.REPORT_NDIFF|doctest.FAIL_FAST
    if len(sys.argv) > 1:
        name = sys.argv[1]
        if name in globals():
            obj = globals()[name]
        else:
            obj = __test__[name]
        doctest.run_docstring_examples(obj, globals(), name=name,
                                       optionflags=flags)
    else:
        fail, total = doctest.testmod(optionflags=flags)
        print("{} failures out of {} tests".format(fail, total))

Notas al pie de página

1

No se admiten los ejemplos que contienen una salida esperada y una excepción. Intentar adivinar dónde una termina y la otra empieza es muy propenso a errores, y da lugar a una prueba confusa.

unittest — Infraestructura de tests unitarios

Código fuente: Lib/unittest/__init__.py [https://github.com/python/cpython/tree/3.9/Lib/unittest/__init__.py]

(Si ya estás familiarizado con los conceptos básicos de realización de tests, puedes saltar a la lista de métodos de aserción.)

La infraestructura de tests unitarios unittest se inspiró en primera instancia en JUnit y ofrece aspectos similares a las principales estructuras de tests unitarios más importantes de otros lenguajes. Da soporte a automatización de tests, inicialización compartida, código de cierre de los tests, agregación de los tests en colecciones e independencia de los tests de la infraestructura que los reporta.

Para conseguir esto, unittest da soporte a ciertos conceptos importantes de una forma orientada a objetos:

configuración de prueba (fixture)

Un test fixture representa los preparativos para realizar una o más pruebas y las acciones de limpieza asociadas. Esto puede incluir, por ejemplo, la creación de bases de datos temporales, directorios o el arranque de procesos del servidor.

caso de prueba

Un test case es la unidad mínima de prueba. Verifica la respuesta específica a un juego particular de entradas. unittest proporciona una clase base, TestCase, que se puede utilizar para crear nuevos casos de uso.

conjunto de pruebas

Un test suite es una colección de casos de prueba, juegos de prueba o ambos. Se usa para agrupar pruebas que se han de ejecutar juntas.

ejecutor de pruebas

Un test runner es un componente que dirige la ejecución de las pruebas y proporciona un resultado. El ejecutor puede disponer de una interfaz gráfica, de texto o devolver un valor especial que indique el resultado de la ejecución de las pruebas.

Ver también

Módulo doctest

Otro módulo de soporte a pruebas con una solución muy diferente.

Simple Smalltalk Testing: With Patterns [https://web.archive.org/web/20150315073817/http://www.xprogramming.com/testfram.htm]

El documento original de Kent Beck sobre infraestructuras de prueba mediante el patrón que utiliza unittest.

pytest [https://docs.pytest.org/]

Una infraestructura de pruebas unitarias de otro proveedor con una sintaxis más ligera de escritura de pruebas, por ejemplo: assert func(10) == 42.

The Python Testing Tools Taxonomy [https://wiki.python.org/moin/PythonTestingToolsTaxonomy]

Una lista extensa de herramientas de prueba para Python incluyendo infraestructuras de pruebas funcionales y librerías de objetos sucedáneos.

Testing in Python Mailing List [http://lists.idyll.org/listinfo/testing-in-python]

Grupo especializado en debate sobre las pruebas y las herramientas de prueba de Python.

El script Tools/unittestgui/unittestgui.py de la distribución de fuentes de Python es una herramienta gráfica para el descubrimiento y ejecución de pruebas. Está orientado sobre todo a principiantes en el tema de pruebas. Para entornos de producción se recomienda que las pruebas sean dirigidas por un sistema de integración continua como Buildbot [https://buildbot.net/], Jenkins [https://jenkins.io/] o Hudson [http://hudson-ci.org/].

Ejemplo sencillo

El módulo unittest proporciona un conjunto de herramientas para construir y ejecutar pruebas. Esta sección demuestra que un pequeño subconjunto de las herramientas es suficiente para satisfacer las necesidades de la mayoría.

He aquí un breve script para probar estros tres métodos de cadena:

import unittest

class TestStringMethods(unittest.TestCase):

    def test_upper(self):
        self.assertEqual('foo'.upper(), 'FOO')

    def test_isupper(self):
        self.assertTrue('FOO'.isupper())
        self.assertFalse('Foo'.isupper())

    def test_split(self):
        s = 'hello world'
        self.assertEqual(s.split(), ['hello', 'world'])
        # check that s.split fails when the separator is not a string
        with self.assertRaises(TypeError):
            s.split(2)

if __name__ == '__main__':
    unittest.main()

Para crear un caso de prueba se genera una subclase de unittest.TestCase. Las tres pruebas se definen con métodos cuyos nombres comienzan por las letras test. Esta convención sobre nombres indica al ejecutor de pruebas qué métodos representan pruebas.

El quid de cada test es la llamada a assertEqual() para verificar un resultado esperado; assertTrue() o assertFalse() para verificar una condición; o assertRaises() para asegurar que se lanza una excepción específica. Se utilizan estos métodos en lugar de la sentencia assert para que el ejecutor de pruebas pueda acumular todos los resultados de la prueba de cara a realizar un informe.

Los métodos setUp() y tearDown() permiten definir instrucciones que han de ser ejecutadas antes y después, respectivamente, de cada método de prueba. Se describen con mas detalle en la sección Organización del código de pruebas.

El bloque final muestra un modo sencillo de ejecutar las pruebas. unittest.main() proporciona una interfaz de línea de órdenes para el script de prueba. Cuando se ejecuta desde la línea de órdenes, el script anterior produce una salida como:

...
----------------------------------------------------------------------
Ran 3 tests in 0.000s

OK

Si se le pasa una opción -v al script de prueba, se establecerá un nivel mayor de detalle del proceso de unittest.main() y se obtendrá la siguiente salida:

test_isupper (__main__.TestStringMethods) ... ok
test_split (__main__.TestStringMethods) ... ok
test_upper (__main__.TestStringMethods) ... ok

----------------------------------------------------------------------
Ran 3 tests in 0.001s

OK

Los ejemplos anteriores muestra las características más usuales de unittest, que son suficientes para solventar las necesidades cotidianas de pruebas. El resto de la documentación explora el juego completo de características, que abundan en los mismos principios.

Interfaz de línea de comandos

Se puede usar el módulo unittest desde la línea de órdenes para ejecutar pruebas de módulos, clases o hasta métodos de prueba individuales:

python -m unittest test_module1 test_module2
python -m unittest test_module.TestClass
python -m unittest test_module.TestClass.test_method

Se puede pasar una lista con cualquier combinación de nombres de módulo, así como clases o métodos completamente cualificados.

Se puede especificar los módulos de prueba por ruta de fichero también:

python -m unittest tests/test_something.py

Esto permite usar el completado automático de nombre de fichero de la shell para especificar el módulo de pruebas. El fichero especificado aún debe ser susceptible de importarse como módulo. La ruta se convierte en nombre de módulo eliminando “.py” y convirtiendo el separador de directorios por “.”. Si se desea ejecutar un fichero de prueba que no se puede importar como módulo, se ha de ejecutar el fichero directamente.

Se pueden ejecutar las pruebas con más nivel de detalle (mayor verbosidad) pasando el parámetro -v:

python -m unittest -v test_module

Cuando se ejecuta sin argumentos, se inicia Descubrimiento de pruebas:

python -m unittest

Para obtener una lista de todas las opciones de línea de órdenes:

python -m unittest -h

Distinto en la versión 3.2: En versiones anteriores sólo era posible ejecutar métodos de prueba individuales, pero no módulos ni clases.

Opciones de la línea de órdenes

unittest da soporte a las siguientes opciones de línea de órdenes:

-b, --buffer

Los flujos de datos de salida estándar y error estándar se acumulan en un búfer durante la ejecución de pruebas. La salida de las pruebas correctas se descarta. La salida de las pruebas que fallan o devuelven un error se añade a los mensajes de fallo.

-c, --catch

La pulsación de Control-C durante la ejecución de pruebas espera a que termine la prueba en curso y da un informe de los resultados hasta ese momento. Una segunda pulsación de Control-C lanza la excepción KeyboardInterrupt usual.

Consultar en Gestión de señales las funciones que proporcionan esta funcionalidad.

-f, --failfast

Finaliza la ejecución tras el primer error o fallo.

-k

Only run test methods and classes that match the pattern or substring. This option may be used multiple times, in which case all test cases that match any of the given patterns are included.

Los patrones que contengan un comodín (*) se comprueban contra el nombre de la prueba usando fnmatch.fnmatchcase(); si no lo contienen, se usa una comprobación de contenido simple sensible a mayúsculas.

Los patrones se comprueban contra el nombre del método completamente cualificado como lo importa el cargador de pruebas.

Por ejemplo, -k foo coincide con foo_tests.SomeTest.test_something y con bar_tests.SomeTest.test_foo, pero no con bar_tests.FooTest.test_something.

--locals

Mostrar las variables locales en las trazas.

Nuevo en la versión 3.2: Se añadieron las opciones de línea de órdenes -b, -c y -f.

Nuevo en la versión 3.5: La opción de línea de órdenes --locals.

Nuevo en la versión 3.7: La opción de línea de órdenes -k.

La línea de órdenes también se puede usar para descubrimiento de pruebas, para ejecutar todas las pruebas de un proyecto o un subconjunto de éstas.

Descubrimiento de pruebas

Nuevo en la versión 3.2.

Unittest da soporte al descubrimiento de pruebas simples. Para ser compatible con el descubrimiento de pruebas, todos los ficheros de prueba deben ser módulos o paquetes (incluyendo paquetes nominales) importables desde el directorio superior del proyecto (por lo que sus nombres han de ser identificadores válidos).

El descubrimiento de pruebas está implementado en TestLoader.discover(), pero también se puede usar desde la línea de órdenes. La línea de órdenes básica es:

cd project_directory
python -m unittest discover

Nota

Como atajo, python -m unittest es el equivalente de python -m unittest discover. Si se desea pasar argumentos al descubrimiento de pruebas, hay que pasar la sub-orden discover explícitamente.

La sub-orden discover cuenta con las siguientes opciones:

-v, --verbose

Salida verbosa

-s, --start-directory directory

Directorio de inicio para el descubrimiento (. si se omite)

-p, --pattern pattern

Patrón para la búsqueda de ficheros de prueba (test*.py si se omite)

-t, --top-level-directory directory

Directorio superior del proyecto (el directorio inicial si se omite)

Las opciones -s, -p, y -t se pueden pasar por posición en el orden mostrado. Las siguientes líneas de órdenes son equivalentes:

python -m unittest discover -s project_directory -p "*_test.py"
python -m unittest discover project_directory "*_test.py"

Además de pasar una ruta, es posible pasar el nombre de un paquete, por ejemplo myproject.subpackage.test, como directorio de inicio. El nombre de paquete proporcionado será importado y su ubicación en el sistema de archivos será utilizada como directorio de inicio.

Prudencia

El descubrimiento de pruebas carga las pruebas importándolas. Una vez que el descubrimiento ha encontrado todos los ficheros de prueba a partir del directorio inicial, especificado, convierte las rutas en nombres de paquetes a importar. Por ejemplo, foo/bar/baz.py será importado como foo.bar.baz.

Si hay un paquete instalado globalmente y se intenta hacer un descubrimiento sobre una copia diferente a la instalada del paquete, podría ocurrir que se importe la versión incorrecta. Si ocurre esto, el descubrimiento lanza una advertencia y abandona.

Si se proporciona el directorio de inicio como nombre de paquete en lugar de ruta a un directorio, el descubrimiento asume que la ubicación importada es la deseada, así que no se da la advertencia descrita.

Los módulos y paquetes de prueba pueden personalizar la carta y descubrimiento de pruebas mediante el protocolo load_tests.

Distinto en la versión 3.4: Test discovery supports namespace packages for the start directory. Note that you need to specify the top level directory too (e.g. python -m unittest discover -s root/namespace -t root).

Organización del código de pruebas

Los bloques de construcción básicos de las pruebas unitarias son los test cases, escenarios simples que se han de configurar y cuya corrección hay que comprobar. En unittest, los casos de prueba están representados por instancias de unittest.TestCase. Para crear nuevos casos de prueba, hay que escribir subclases de TestCase o usar FunctionTestCase.

El código de pruebas de una instancia de TestCase debería ser completamente autónomo, de tal modo que se pueda ejecutar aisladamente o en una combinación arbitraria con otras clases de prueba.

La subclase más simple de TestCase se limita a implementar un método test (o un método que empiece por test) para realizar código de prueba específico:

import unittest

class DefaultWidgetSizeTestCase(unittest.TestCase):
    def test_default_widget_size(self):
        widget = Widget('The widget')
        self.assertEqual(widget.size(), (50, 50))

Adviértase que para probar algo, usamos uno de los métodos assert*() proporcionados por la clase base TestCase. Si la prueba no tiene éxito, se lanzará una excepción con un mensaje explicativo y unittest identificará el caso como failure. Cualquier otra excepción se considerará un errors.

Las pruebas pueden ser muchas y su preparación puede ser repetitiva. Por suerte, se puede «sacar factor común» a la preparación implementando un método setUp(), al que la infraestructura de prueba llamará para cada prueba que se ejecute:

import unittest

class WidgetTestCase(unittest.TestCase):
    def setUp(self):
        self.widget = Widget('The widget')

    def test_default_widget_size(self):
        self.assertEqual(self.widget.size(), (50,50),
                         'incorrect default size')

    def test_widget_resize(self):
        self.widget.resize(100,150)
        self.assertEqual(self.widget.size(), (100,150),
                         'wrong size after resize')

Nota

El orden en que se ejecutan las diversas pruebas se determina por orden alfabético de los nombres de métodos de prueba.

Si el método setUp() lanza una excepción mientras se ejecuta la prueba, la infraestructura considerará que la prueba ha sufrido un error y no se ejecutará el método de prueba propiamente dicho.

Análogamente, se puede proporcionar un método tearDown() que haga limpieza después de que se ejecute el método de prueba:

import unittest

class WidgetTestCase(unittest.TestCase):
    def setUp(self):
        self.widget = Widget('The widget')

    def tearDown(self):
        self.widget.dispose()

Si setUp() se ejecuta sin errores, tearDown() se ejecutará tanto si el método de prueba tuvo éxito como si no.

Un entorno de trabajo así para el código de pruebas se llama test fixture . Se crea una nueva instancia de TestCase como juego de datos de prueba que se utiliza para cada método de prueba. De este modo, setUp(), tearDown() y __init__() se llamarán una vez por prueba.

Se recomienda usar implementaciones de TestCase para agrupar las pruebas de acuerdo con las características probadas. unittest proporciona una mecanismo para esto: el test suite, representado por la clase TestSuite de unittest. En la mayor parte de los casos, llamar a unittest.main() hará lo correcto y recolectará todos los casos de prueba del módulo para su ejecución.

Sin embargo, si se desea personalizar la construcción del paquete de pruebas, se puede hacer:

def suite():
    suite = unittest.TestSuite()
    suite.addTest(WidgetTestCase('test_default_widget_size'))
    suite.addTest(WidgetTestCase('test_widget_resize'))
    return suite

if __name__ == '__main__':
    runner = unittest.TextTestRunner()
    runner.run(suite())

Se puede poner las definiciones de los casos de prueba y de los paquetes de prueba en los mismos módulos que el código que prueban.(tal como widget.py), pero sacarlos a un módulo aparte como test_widget.py tiene diversas ventajas:

El módulo de pruebas se puede ejecutar aisladamente desde la línea de órdenes.

El código de pruebas se puede separar con más facilidad del código de producción.

Disminuye la tentación de cambiar el código de prueba para ajustarse al código bajo prueba.

El código de pruebas debería modificarse con mucha menor frecuencia que el código bajo prueba.

Es más sencillo refactorizar el código bajo prueba.

El código para probar módulos escritos en C ha de estar en módulos aparte, así que ¿por qué no mantener la consistencia?

Si cambia la estrategia de prueba, no hay razón para cambiar el código fuente principal.

Reutilización de código de prueba anterior

Habrá personas que tengan código de prueba previo que deseen ejecutar desde unittest, sin conversión previa de cada antigua función de prueba a una subclase de TestCase.

Por esto, unittest proporciona una clase FunctionTestCase. Se puede utilizar esta subclase de TestCase para envolver una función de prueba existente. Se pueden proporcionar también funciones de preparación y desmontaje.

Dada la siguiente función de prueba:

def testSomething():
    something = makeSomething()
    assert something.name is not None
    # ...

se puede crear una instancia de caso de prueba de la siguiente manera, con métodos opcionales de preparación y desmontaje:

testcase = unittest.FunctionTestCase(testSomething,
                                     setUp=makeSomethingDB,
                                     tearDown=deleteSomethingDB)

Nota

Aunque se puede usar FunctionTestCase para convertir rápidamente unas pruebas existentes a un sistema basado en unittest, no es una vía recomendada. Tomarse el tiempo de construir subclases bien construidas de TestCase hará las futuras refactorizaciones de pruebas futura considerablemente más fácil.

En algunos casos, los tests existentes pueden haber sido escritos usando el módulo doctest. En ese caso, doctest tiene una clase DocTestSuite que puede construir automáticamente instancias de unittest.TestSuite partiendo de los test basados en doctest.

Omitir tests y fallos esperados

Nuevo en la versión 3.1.

Unittest soporta omitir métodos individuales de tests e incluso clases completas de tests. Además, soporta marcar un test como un «fallo esperado», un test que está roto y va a fallar, pero no debería ser contado como fallo en TestResult.

Omitir un test es solo cuestión de emplear el decorator skip() o una de sus variantes condicionales, llamando a TestCase.skipTest() dentro de setUp() o en un método de test, o lanzando SkipTest directamente.

La omisión más básica tiene la siguiente forma:

class MyTestCase(unittest.TestCase):

    @unittest.skip("demonstrating skipping")
    def test_nothing(self):
        self.fail("shouldn't happen")

    @unittest.skipIf(mylib.__version__ < (1, 3),
                     "not supported in this library version")
    def test_format(self):
        # Tests that work for only a certain version of the library.
        pass

    @unittest.skipUnless(sys.platform.startswith("win"), "requires Windows")
    def test_windows_support(self):
        # windows specific testing code
        pass

    def test_maybe_skipped(self):
        if not external_resource_available():
            self.skipTest("external resource not available")
        # test code that depends on the external resource
        pass

Esta es la salida de ejecutar el ejemplo superior en modo verboso:

test_format (__main__.MyTestCase) ... skipped 'not supported in this library version'
test_nothing (__main__.MyTestCase) ... skipped 'demonstrating skipping'
test_maybe_skipped (__main__.MyTestCase) ... skipped 'external resource not available'
test_windows_support (__main__.MyTestCase) ... skipped 'requires Windows'

----------------------------------------------------------------------
Ran 4 tests in 0.005s

OK (skipped=4)

Las clases pueden ser omitidas igual que los métodos:

@unittest.skip("showing class skipping")
class MySkippedTestCase(unittest.TestCase):
    def test_not_run(self):
        pass

TestCase.setUp() puede omitir también el test. Esto es útil cuando un recurso que necesita ser puesto a punto no está disponible.

Los fallos esperados emplean el decorador expectedFailure().

class ExpectedFailureTestCase(unittest.TestCase):
    @unittest.expectedFailure
    def test_fail(self):
        self.assertEqual(1, 0, "broken")

Es fácil lanzar tus propios decoradores que omitan haciendo un decorador que llame a skip() en el test cuando quiere ser omitido. Este decorador omite el test a menos que el objeto pasado tenga un cierto atributo:

def skipUnlessHasattr(obj, attr):
    if hasattr(obj, attr):
        return lambda func: func
    return unittest.skip("{!r} doesn't have {!r}".format(obj, attr))

Los siguientes decoradores y la excepción implementan la omisión de tests y los fallos esperados:

@unittest.skip(reason)

Omitir incondicionalmente el test decorado. reason debe describir porqué el test está siendo omitido.

@unittest.skipIf(condition, reason)

Omitir el test decorado si condition es verdadero.

@unittest.skipUnless(condition, reason)

Omitir el test decorado a menos que condition sea verdadero.

@unittest.expectedFailure

Mark the test as an expected failure or error. If the test fails or errors in the test function itself (rather than in one of the test fixture methods) then it will be considered a success. If the test passes, it will be considered a failure.

exception unittest.SkipTest(reason)

Esta excepción es lanzada para omitir un test.

Normalmente puedes usar directamente TestCase.skipTest() o uno de los decoradores de omisión en vez de lanzar esta excepción.

Los tests omitidos no ejecutarán setUp() o tearDown(). Las clases omitidas no ejecutarán setUpClass() o tearDownClass(). Los módulos omitidos no ejecutarán setUpModule() o tearDownModule().

Distinguiendo iteraciones de tests empleando subtests

Nuevo en la versión 3.4.

Cuando hay diferencias muy pequeñas entre tus tests, por ejemplo algunos parámetros, unittest te permite distinguirlos dentro del cuerpo de un método de test empleando el administrador de contexto subTest() .

Por ejemplo, el siguiente test:

class NumbersTest(unittest.TestCase):

    def test_even(self):
        """
        Test that numbers between 0 and 5 are all even.
        """
        for i in range(0, 6):
            with self.subTest(i=i):
                self.assertEqual(i % 2, 0)

producirá la siguiente salida:

======================================================================
FAIL: test_even (__main__.NumbersTest) (i=1)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "subtests.py", line 32, in test_even
    self.assertEqual(i % 2, 0)
AssertionError: 1 != 0

======================================================================
FAIL: test_even (__main__.NumbersTest) (i=3)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "subtests.py", line 32, in test_even
    self.assertEqual(i % 2, 0)
AssertionError: 1 != 0

======================================================================
FAIL: test_even (__main__.NumbersTest) (i=5)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "subtests.py", line 32, in test_even
    self.assertEqual(i % 2, 0)
AssertionError: 1 != 0

Sin usar un subtest, la ejecución se pararía después del primer fallo, y el error sería más difícil de diagnosticar porque el valor de i no se mostraría:

======================================================================
FAIL: test_even (__main__.NumbersTest)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "subtests.py", line 32, in test_even
    self.assertEqual(i % 2, 0)
AssertionError: 1 != 0

Clases y funciones

Esta sección describe en detalle la API de unittest.

Casos de test

class unittest.TestCase(methodName='runTest')

Las instancias de la clase TestCase representan las unidades lógicas de test en el universo de unittest. Esta clase está pensada para ser utilizada como clase base, con los test específicos siendo implementados por subclases concretas. Esta clase implementa la interfaz que necesita el ejecutor de tests para permitirle llevar a cabo los tests, y métodos que el código de test puede utilizar para chequear y reportar distintos tipos de fallo.

Cada instancia de TestCase ejecutará un solo método base: el método llamado methodName. En la mayoría de usos de TestCase, no tendrás que cambiar el methodName ni reimplementar el método por defecto runTest().

Distinto en la versión 3.2: TestCase puede instancias con éxito sin dar un methodName. Esto permite experimentar de manera sencilla con TestCase en el intérprete interactivo.

Las instancias de TestCase proveen tres grupos de métodos: un grupo empleado para ejecutar el test, otro usado para que la implementación del test chequee condiciones y reporte fallos, y algunos métodos de indagación que permiten recopilar información sobre el test en si mismo.

Los métodos en el primer grupo (ejecutando el test) son:

setUp()

Método llamado para preparar el banco de test. Es invocado inmediatamente antes de llamar al método de test; cualquier excepción lanzada por este método que no sea AssertionError o SkipTest será considerada un error en vez de un fallo del test. La implementación por defecto no hace nada.

tearDown()

Método llamado inmediatamente después de que se haya llamado el método de prueba y se haya registrado el resultado. Se llama así aunque el método de ensayo haya planteado una excepción, por lo que la aplicación en las subclases puede tener que ser especialmente cuidadosa en cuanto a la comprobación del estado interno. Cualquier excepción, que no sea AssertionError o SkipTest, planteada por este método se considerará un error adicional en lugar de un fallo de la prueba (aumentando así el número total de errores reportados). Este método sólo se llamará si setUp() tiene éxito, independientemente del resultado del método de prueba. La implementación por defecto no hace nada.

setUpClass()

Un método de clase llamado antes de que los tests en una clase individual sean ejecutados. setUpClass es llamado con la clase como el único argumento y debe ser decorada como classmethod():

@classmethod
def setUpClass(cls):
    ...

Vea Class and Module Fixtures para más detalles.

Nuevo en la versión 3.2.

tearDownClass()

Un método de clase llamado después de que se hayan realizado tests en una clase individual. tearDownClass se llama con la clase como único argumento y debe ser decorado como un classmethod():

@classmethod
def tearDownClass(cls):
    ...

Vea Class and Module Fixtures para más detalles.

Nuevo en la versión 3.2.

run(result=None)

Ejecutar la prueba, recogiendo el resultado en el objeto TestResult pasado como result. Si se omite result o None, se crea un objeto resultado temporal (llamando al método defaultTestResult()) y se emplea ese. El objeto resultante se devuelve al invocador de run().

El mismo efecto puede conseguirse simplemente llamando a la instancia TestCase.

Distinto en la versión 3.3: Las versiones previas de run no retornaban el resultado. Tampoco lo hacía la llamada a una instancia.

skipTest(reason)

Llamar a esto durante un método de prueba o setUp() se salta el test actual. Ver Omitir tests y fallos esperados para más información.

Nuevo en la versión 3.1.

subTest(msg=None, **params)

Retorna un gestor de contexto que ejecuta el bloque de código adjunto como un subtest. msg y params son valores opcionales y arbitrarios que se muestran cuando falla un subtest, permitiéndole identificarlos claramente.

Un caso de test puede contener cualquier número de declaraciones de subtest, y pueden anidarse arbitrariamente.

Ver Distinguiendo iteraciones de tests empleando subtests para más información.

Nuevo en la versión 3.4.

debug()

Realice el test sin recoger el resultado. Esto permite que las excepciones planteadas por el test se propaguen al invocado, y puede utilizarse para apoyar la ejecución de tests bajo un depurador.

La clase TestCase proporciona varios métodos de afirmación para comprobar y reportar fallos. En la siguiente tabla se enumeran los métodos más utilizados (consulte las tablas siguientes para ver más métodos de afirmación):

Método

Comprueba que

Nuevo en

assertEqual(a, b)

a == b

assertNotEqual(a, b)

a != b

assertTrue(x)

bool(x) is True

assertFalse(x)

bool(x) is False

assertIs(a, b)

a is b

3.1

assertIsNot(a, b)

a is not b

3.1

assertIsNone(x)

x is None

3.1

assertIsNotNone(x)

x is not None

3.1

assertIn(a, b)

a in b

3.1

assertNotIn(a, b)

a not in b

3.1

assertIsInstance(a, b)

isinstance(a, b)

3.2

assertNotIsInstance(a, b)

not isinstance(a, b)

3.2

Todos los métodos de aserción aceptan un argumento msg que, si se especifica, se utiliza como mensaje de error en caso de fallo (véase también longMessage). Tenga en cuenta que el argumento de la palabra clave msg puede pasarse a assertRaises(), assertRaisesRegex(), assertWarns(), assertWarnsRegex() sólo cuando se utilizan como gestor de contexto.

assertEqual(first, second, msg=None)

Testea que first y second son iguales. Si los valores no comparan como iguales, el test fallará.

Además, si first y second son exactamente del mismo tipo y uno de lista, tuple, dict, set, frozenset o str o cualquier tipo que una subclase registre con addTypeEqualityFunc() se llamará a la función de igualdad específica del tipo para generar un mensaje de error por defecto más útil (véase también la lista de métodos específicos del tipo).

Distinto en la versión 3.1: Añadida la llamada automática de la función de igualdad de tipo específico.

Distinto en la versión 3.2: assertMultiLineEqual() añadido como la función por defecto para igualdad de tipos cuando se comparan cadenas.

assertNotEqual(first, second, msg=None)

Testea que first y second no son iguales. Si los valores son iguales, el test fallará.

assertTrue(expr, msg=None)

assertFalse(expr, msg=None)

Testea que expr es verdadero (o falso).

Note que esto es equivalente a bool(expr) is True y no a expr is True (use assertIs(expr, True) para lo último). Este método también debe evitarse cuando se disponga de métodos más específicos (por ejemplo, assertEqual(a, b) en lugar de assertTrue(a == b)), porque proporcionan un mejor mensaje de error en caso de fallo.

assertIs(first, second, msg=None)

assertIsNot(first, second, msg=None)

Testea si first y second son (o no) el mismo objeto.

Nuevo en la versión 3.1.

assertIsNone(expr, msg=None)

assertIsNotNone(expr, msg=None)

Testea que expr es (o no es) None.

Nuevo en la versión 3.1.

assertIn(member, container, msg=None)

assertNotIn(member, container, msg=None)

Testea que member está (o no está) en container.

Nuevo en la versión 3.1.

assertIsInstance(obj, cls, msg=None)

assertNotIsInstance(obj, cls, msg=None)

Testea que obj es (o no es) una instancia de cls (que puede ser una clase o una tupla de clases, de la misma forma que soporta isinstance()). Para chequear por el tipo exacto, use assertIs(type(obj), cls).

Nuevo en la versión 3.2.

Es también posible chequear la producción de excepciones, advertencias y mensajes de log usando los siguientes métodos:

Método

Comprueba que

Nuevo en

assertRaises(exc, fun, *args, **kwds)

fun(*args, **kwds) lanza exc

assertRaisesRegex(exc, r, fun, *args, **kwds)

fun(*args, **kwds) lanza exc y el mensaje coincide con regex r

3.1

assertWarns(warn, fun, *args, **kwds)

fun(*args, **kwds) lanza warn

3.2

assertWarnsRegex(warn, r, fun, *args, **kwds)

fun(*args, **kwds) lanza warn y el mensaje coincide con regex r

3.2

assertLogs(logger, level)

El bloque with vuelca sus logs a logger con el level mínimo

3.4

assertRaises(exception, callable, *args, **kwds)

assertRaises(exception, *, msg=None)

Testea que se lanza una excepción cuando se llama a callable con cualquier argumento posicional o de palabra clave que también se pasa a assertRaises(). El test pasa si se lanza exception, es un error si se lanza otra excepción, o falla si no se lanza ninguna excepción. Para tener en cuenta cualquiera de un grupo de excepciones, una tupla que contenga las clases de excepción puede ser pasada como exception.

Si sólo se dan los argumentos de exception y posiblemente msg, retorna un administrador de contexto para que el código testado pueda ser escrito en línea en lugar de como una función:

with self.assertRaises(SomeException):
    do_something()

Cuando se emplea como un administrador de contexto, assertRaises() acepta el argumento por palabra clave adicional msg.

El gestor de contexto almacenará el objeto de excepción capturado en su atributo exception . Esto puede ser útil si la intención es realizar comprobaciones adicionales sobre la excepción planteada:

with self.assertRaises(SomeException) as cm:
    do_something()

the_exception = cm.exception
self.assertEqual(the_exception.error_code, 3)

Distinto en la versión 3.1: Añadió la capacidad de usar assertRaises() como gestor de contexto.

Distinto en la versión 3.2: Añadido el atributo exception .

Distinto en la versión 3.3: Añadido el argumento por palabra clave msg cuando se emplea un gestor de contexto.

assertRaisesRegex(exception, regex, callable, *args, **kwds)

assertRaisesRegex(exception, regex, *, msg=None)

Como assertRaises() pero también testea que regex coincide en la representación de la cadena de la excepción planteada. regex puede ser un objeto de expresión regular o una cadena que contiene una expresión regular adecuada para ser usada por re.search(). Ejemplos:

self.assertRaisesRegex(ValueError, "invalid literal for.*XYZ'$",
                       int, 'XYZ')

o:

with self.assertRaisesRegex(ValueError, 'literal'):
   int('XYZ')

Nuevo en la versión 3.1: Añadido bajo el nombre de assertRaisesRegexp.

Distinto en la versión 3.2: Renombrado a assertRaisesRegex().

Distinto en la versión 3.3: Añadido el argumento por palabra clave msg cuando se emplea un gestor de contexto.

assertWarns(warning, callable, *args, **kwds)

assertWarns(warning, *, msg=None)

Testea que una advertencia se activa cuando se llama a callable con cualquier argumento posicional o de palabra clave que también se pasa a assertWarns(). El test pasa si se activa el warning y falla si no lo hace. Cualquier excepción es un error. Para considerar cualquiera de un grupo de advertencias, una tupla que contenga las clases de advertencia puede ser pasada como warnings.

Si sólo se dan los argumentos de advertencia y msg, retorna un gestor de contexto para que el código testado pueda ser escrito en línea en lugar de como una función:

with self.assertWarns(SomeWarning):
    do_something()

Cuando se usa como gestor de contexto, assertWarns() acepta el argumento de palabra clave adicional msg.

El gestor de contexto almacenará el objeto de advertencia capturado en su atributo warning, y la línea del código que disparó las advertencias en los atributos filename y lineno . Esto puede ser útil si la intención es realizar comprobaciones adicionales sobre la advertencia capturada:

with self.assertWarns(SomeWarning) as cm:
    do_something()

self.assertIn('myfile.py', cm.filename)
self.assertEqual(320, cm.lineno)

Este método funciona independientemente de los filtros de aviso que estén en su lugar cuando se llame.

Nuevo en la versión 3.2.

Distinto en la versión 3.3: Añadido el argumento por palabra clave msg cuando se emplea un gestor de contexto.

assertWarnsRegex(warning, regex, callable, *args, **kwds)

assertWarnsRegex(warning, regex, *, msg=None)

Como assertWarns() pero también testea que regex coincide en el mensaje del aviso disparado. regex puede ser un objeto de expresión regular o una cadena que contiene una expresión regular adecuada para ser usada por re.search(). Ejemplo:

self.assertWarnsRegex(DeprecationWarning,
                      r'legacy_function\(\) is deprecated',
                      legacy_function, 'XYZ')

o:

with self.assertWarnsRegex(RuntimeWarning, 'unsafe frobnicating'):
    frobnicate('/etc/passwd')

Nuevo en la versión 3.2.

Distinto en la versión 3.3: Añadido el argumento por palabra clave msg cuando se emplea un gestor de contexto.

assertLogs(logger=None, level=None)

Un gestor de contexto para comprobar que al menos un mensaje está registrado en el logger o en uno de sus hijos, con al menos el level dado.

Si se da, logger debería ser un objeto logging.Logger o un str dando el nombre de un logger. El valor por defecto es el root logger, que captará todos los mensajes.

Si se da, level debe ser un nivel de logging numérico o su equivalente en cadena (por ejemplo, o bien ”ERROR” o logging.ERROR). El valor por defecto es logging.INFO.

El test pasa si al menos un mensaje emitido dentro del bloque with coincide con las condiciones de logger y level, de lo contrario falla.

El objeto devuelto por el gestor de contexto es un ayudante de grabación que lleva un registro de los mensajes de registro que coinciden. Tiene dos atributos:

records

Una lista de objetos logging.LogRecord de los mensajes de log coincidentes.

output

Una lista de objetos str con la salida forrajeada en los mensajes coincidentes.

Ejemplo:

with self.assertLogs('foo', level='INFO') as cm:
   logging.getLogger('foo').info('first message')
   logging.getLogger('foo.bar').error('second message')
self.assertEqual(cm.output, ['INFO:foo:first message',
                             'ERROR:foo.bar:second message'])

Nuevo en la versión 3.4.

Hay también otros métodos empleados para realizar comprobaciones más específicas, tales como:

Método

Comprueba que

Nuevo en

assertAlmostEqual(a, b)

round(a-b, 7) == 0

assertNotAlmostEqual(a, b)

round(a-b, 7) != 0

assertGreater(a, b)

a > b

3.1

assertGreaterEqual(a, b)

a >= b

3.1

assertLess(a, b)

a < b

3.1

assertLessEqual(a, b)

a <= b

3.1

assertRegex(s, r)

r.search(s)

3.1

assertNotRegex(s, r)

not r.search(s)

3.2

assertCountEqual(a, b)

a y b tienen los mismos elementos y en el mismo número, sin importar su orden.

3.2

assertAlmostEqual(first, second, places=7, msg=None, delta=None)

assertNotAlmostEqual(first, second, places=7, msg=None, delta=None)

Testea que first y second son aproximadamente (o no aproximadamente) iguales calculando su diferencia, redondeando al número dado de puntos places decimales (por defecto 7), y comparado a cero. Nótese que estos métodos redondean los valores al número dado de puntos decimales (por ejemplo como la función round()) y no cifras significativas.

Si se suministra delta en vez de places que entonces la diferencia entre first y second deba ser menor o igual a (o mayor que) delta.

Suministrar tanto delta como places lanza un TypeError.

Distinto en la versión 3.2: assertAlmostEqual() considera automáticamente casi iguales a los objetos que se comparan igual. assertNotAlmostEqual() falla automáticamente si los objetos comparan iguales. Añadido el argumento de palabra clave delta.

assertGreater(first, second, msg=None)

assertGreaterEqual(first, second, msg=None)

assertLess(first, second, msg=None)

assertLessEqual(first, second, msg=None)

Prueba que first es respectivamente >, >=, < o <= que second dependiendo del nombre del método. Si no, el test fallará:

>>> self.assertGreaterEqual(3, 4)
AssertionError: "3" unexpectedly not greater than or equal to "4"

Nuevo en la versión 3.1.

assertRegex(text, regex, msg=None)

assertNotRegex(text, regex, msg=None)

Testea que una búsqueda regex coincide (o no coincide) con el text. En caso de fallo, el mensaje de error incluirá el patrón y el text (o el patrón y la parte de text que coincida inesperadamente). regex puede ser un objeto de expresión regular o una cadena que contiene una expresión regular adecuada para ser utilizada por re.search().

Nuevo en la versión 3.1: Añadido bajo el nombre de assertRegexpMatches.

Distinto en la versión 3.2: El método assertRegexpMatches() ha sido renombrado a assertRegex().

Nuevo en la versión 3.2: assertNotRegex().

Nuevo en la versión 3.5: El nombre assertNotRegexpMatches es un alias obsoleto para assertNotRegex().

assertCountEqual(first, second, msg=None)

Testea que la secuencia first contiene los mismos elementos que second, independientemente de su orden. Cuando no lo hagan, se generará un mensaje de error con las diferencias entre las secuencias.

Los elementos duplicados no son ignorados cuando se comparan first y second. Verifica si cada elemento tiene la misma cuenta en ambas secuencias. Equivalente a: assertEqual(Counter(list(first)), Counter(list(second))) pero funciona también con secuencias de objetos que no son hashable.

Nuevo en la versión 3.2.

El método assertEqual() envía la comprobación de igualdad de los objetos del mismo tipo a diferentes métodos específicos de tipo. Estos métodos ya están implementados para la mayoría de los tipos incorporados, pero también es posible registrar nuevos métodos usando addTypeEqualityFunc():

addTypeEqualityFunc(typeobj, function)

Registra un método específico de tipo llamado por assertEqual() para comprobar si dos objetos del mismo typeobj (no subclases) comparan como iguales. function debe tomar dos argumentos posicionales y un tercer argumento de palabra clave msg=None tal y como lo hace assertEqual(). Debe lanzar self.failureException(msg) cuando se detecta una desigualdad entre los dos primeros parámetros, posiblemente proporcionando información útil y explicando las desigualdades en detalle en el mensaje de error.

Nuevo en la versión 3.1.

La lista de métodos específicos de tipo utilizados automáticamente por assertEqual() se resumen en la siguiente tabla. Tenga en cuenta que normalmente no es necesario invocar estos métodos directamente.

Método

Usado para comparar

Nuevo en

assertMultiLineEqual(a, b)

strings

3.1

assertSequenceEqual(a, b)

sequences

3.1

assertListEqual(a, b)

lists

3.1

assertTupleEqual(a, b)

tuples

3.1

assertSetEqual(a, b)

sets or frozensets

3.1

assertDictEqual(a, b)

dicts

3.1

assertMultiLineEqual(first, second, msg=None)

Testea que la cadena multilínea first es igual a la cadena second. Cuando no sea igual, una diferencia de las dos cadenas que resalte las diferencias se incluirá en el mensaje de error. Este método se utiliza por defecto cuando se comparan cadenas con assertEqual().

Nuevo en la versión 3.1.

assertSequenceEqual(first, second, msg=None, seq_type=None)

Testea que dos secuencias son iguales. Si se suministra un seq_type, tanto first como second deben ser instancias de seq_type o se lanzará un fallo. Si las secuencias son diferentes se construye un mensaje de error que muestra la diferencia entre las dos.

Este método no es llamado directamente por assertEqual(), pero se usa para implementar assertListEqual() y assertTupleEqual().

Nuevo en la versión 3.1.

assertListEqual(first, second, msg=None)

assertTupleEqual(first, second, msg=None)

Testea que dos listas o tuplas son iguales. Si no es así, se construye un mensaje de error que muestra sólo las diferencias entre las dos. También se lanza un error si alguno de los parámetros es del tipo equivocado. Estos métodos se utilizan por defecto cuando se comparan listas o tuplas con assertEqual().

Nuevo en la versión 3.1.

assertSetEqual(first, second, msg=None)

Testea que dos conjuntos son iguales. Si no es así, se construye un mensaje de error que enumera las diferencias entre los conjuntos. Este método se utiliza por defecto cuando se comparan los conjuntos o frozensets con assertEqual().

Falla si cualquiera de first o second no tiene un método de set.difference().

Nuevo en la versión 3.1.

assertDictEqual(first, second, msg=None)

Testea que dos diccionarios son iguales. Si no es así, se construye un mensaje de error que muestra las diferencias en los diccionarios. Este método se usará por defecto para comparar los diccionarios en las llamadas a assertEqual().

Nuevo en la versión 3.1.

Finalmente, TestCase proporciona los siguientes métodos y atributos:

fail(msg=None)

Señala un fallo del test incondicionalmente, con msg o None para el mensaje de error.

failureException

Este atributo de clase da la excepción lanzada por el método de test. Si un marco de pruebas necesita utilizar una excepción especializada, posiblemente para llevar información adicional, debe subclasificar esta excepción para «jugar limpio» con el marco. El valor inicial de este atributo es AssertionError.

longMessage

Este atributo de clase determina lo que ocurre cuando se pasa un mensaje de fallo personalizado como el argumento msg a una llamada assertXYY que falla. True es el valor por defecto. En este caso, el mensaje personalizado se añade al final del mensaje de fallo estándar. Cuando se establece en False, el mensaje personalizado reemplaza al mensaje estándar.

La configuración de la clase puede ser anulada en los métodos de test individuales asignando un atributo de instancia, self.longMessage, a True o False antes de llamar a los métodos assert.

La configuración de la clase se reajusta antes de cada llamada de test.

Nuevo en la versión 3.1.

maxDiff

Este atributo controla la longitud máxima de las diferencias de salida de métodos assert que reportan diferencias en caso de fallo. El valor predeterminado es de 80*8 caracteres. Los métodos assert afectados por este atributo son assertSequenceEqual() (incluyendo todos los métodos de comparación de secuencias que le delegan), assertDictEqual() y assertMultiLineEqual().

Poner maxDiff en None significa que no hay una longitud máxima de diferencias.

Nuevo en la versión 3.2.

Los marcos de test pueden utilizar los siguientes métodos para reunir información sobre el test:

countTestCases()

Retorna el número de tests representados por este objeto de test. Para las instancias de TestCase, este siempre será 1.

defaultTestResult()

Retorna una instancia de la clase de resultado de test que debería utilizarse para esta clase de caso de test (si no se proporciona otra instancia de resultado al método run()).

Para las instancias de TestCase, ésta siempre será una instancia de TestResult; las subclases de TestCase deben anular esto según sea necesario.

id()

Devuelva una cadena que identifique el caso de test específico. Normalmente es el nombre completo del método de test, incluyendo el nombre del módulo y de la clase.

shortDescription()

Devuelve una descripción de la prueba, o None si no se ha proporcionado ninguna descripción. La implementación por defecto de este método devuelve la primera línea de la docstring del método de test, si está disponible, o None .

Distinto en la versión 3.1: En 3.1 esto se cambió para añadir el nombre del test a la descripción corta incluso en presencia de una docstring. Esto causó problemas de compatibilidad con las extensiones de unittest y la adición del nombre de test fue movida a la TextTestResult en Python 3.2.

addCleanup(function, /, *args, **kwargs)

Añade una función que se llamará después de tearDown() a los recursos de limpieza utilizados durante el test. Las funciones se llamarán en orden inverso al orden en que se agregan (LIFO). Se llaman con cualquier argumento y argumentos de palabra clave que se pase a addCleanup() cuando se agregan.

Si setUp() falla, lo que significa que tearDown() no se llama, entonces cualquier función de limpieza añadida seguirá siendo llamada.

Nuevo en la versión 3.1.

doCleanups()

Este método se llama incondicionalmente después de tearDown(), o después de setUp() si setUp() lanza una excepción.

Es responsable de llamar a todas las funciones de limpieza añadidas por addCleanup(). Si necesitas que las funciones de limpieza se llamen con anterioridad a tearDown() entonces puedes llamar a doCleanups() tú mismo.

doCleanups() saca los métodos de la pila de funciones de limpieza uno a uno, así que se puede llamar en cualquier momento.

Nuevo en la versión 3.1.

classmethod addClassCleanup(function, /, *args, **kwargs)

Añade una función que se llamará después de tearDownClass() para limpiar recursos utilizados durante la clase de test. Las funciones se llamarán en orden inverso al orden en que se agregan (LIFO). Se llaman con cualquier argumento y argumento de palabra clave que se pase a addClassCleanup() cuando se añadan.

Si setUpClass() falla, lo que significa que tearDownClass() no se invoca, entonces cualquier función de limpieza añadida seguirá siendo llamada.

Nuevo en la versión 3.8.

classmethod doClassCleanups()

Este método se llama incondicionalmente después de tearDownClass(), o después de setUpClass() si setUpClass() lanza una excepción.

Es responsable de llamar a todas las funciones de limpieza añadidas por addCleanupClass(). Si necesitas que las funciones de limpieza se llamen con anterioridad a tearDownClass() entonces puedes llamar a doCleanupsClass() tú mismo.

doCleanupsClass() saca los métodos de la pila de funciones de limpieza de uno en uno, así que se puede llamar en cualquier momento.

Nuevo en la versión 3.8.

class unittest.IsolatedAsyncioTestCase(methodName='runTest')

Esta clase proporciona una API similar a TestCase y también acepta corutinas como funciones de test.

Nuevo en la versión 3.8.

coroutine asyncSetUp()

Método llamado para preparar la configuración de test. Esto se llama después de setUp(). Se llama inmediatamente antes de llamar al método de test; aparte de AssertionError o SkipTest, cualquier excepción lanzada por este método se considerará un error más que un fallo del test. La implementación por defecto no hace nada.

coroutine asyncTearDown()

Método llamado inmediatamente después de que se haya llamado el método de test y se haya registrado el resultado. Esto se llama antes de tearDown(). Se llama así aunque el método de test haya lanzado una excepción, por lo que la implementación en las subclases puede necesitar ser particularmente cuidadosa en la comprobación del estado interno. Cualquier excepción, que no sea AssertionError o SkipTest, lanzada por este método se considerará un error adicional en lugar de un fallo del test (aumentando así el número total de errores reportados). Este método sólo se llamará si asyncSetUp() tiene éxito, independientemente del resultado del método de test. La implementación por defecto no hace nada.

addAsyncCleanup(function, /, *args, **kwargs)

Este método acepta una corutina que puede ser utilizada como función de limpieza.

run(result=None)

Establece un nuevo bucle de eventos para ejecutar el test, recogiendo el resultado en el objeto TestResult pasado como result. Si se omite result o None, se crea un objeto resultado temporal (llamando al método defaultTestResult()) y se utiliza. El objeto resultante se devuelve al invocado de run(). Al final del test se cancelan todas las tareas del bucle de eventos.

Un ejemplo ilustrando el orden:

from unittest import IsolatedAsyncioTestCase

events = []

class Test(IsolatedAsyncioTestCase):

    def setUp(self):
        events.append("setUp")

    async def asyncSetUp(self):
        self._async_connection = await AsyncConnection()
        events.append("asyncSetUp")

    async def test_response(self):
        events.append("test_response")
        response = await self._async_connection.get("https://example.com")
        self.assertEqual(response.status_code, 200)
        self.addAsyncCleanup(self.on_cleanup)

    def tearDown(self):
        events.append("tearDown")

    async def asyncTearDown(self):
        await self._async_connection.close()
        events.append("asyncTearDown")

    async def on_cleanup(self):
        events.append("cleanup")

if __name__ == "__main__":
    unittest.main()

Después de ejecutar el test, events contendría [“setUp”, “asyncSetUp”, “test_response”, “asyncTearDown”, “tearDown”, “cleanup”].

class unittest.FunctionTestCase(testFunc, setUp=None, tearDown=None, description=None)

Esta clase implementa la porción de la interfaz TestCase que permite al corredor de tests conducir los tests, pero no proporciona los métodos que el código de test puede utilizar para comprobar e informar de los errores. Se utiliza para crear casos de test utilizando código de prueba heredado, lo que permite que se integre en un marco de tests basado en unittest.

Alias obsoletos

Por razones históricas, algunos de los métodos de TestCase tenían uno o más alias que ahora están obsoletos. La siguiente tabla lista los nombres correctos junto con sus alias obsoletos:

Nombre del método

Alias deprecado

Alias deprecado

assertEqual()

failUnlessEqual

assertEquals

assertNotEqual()

failIfEqual

assertNotEquals

assertTrue()

failUnless

assert_

assertFalse()

failIf

assertRaises()

failUnlessRaises

assertAlmostEqual()

failUnlessAlmostEqual

assertAlmostEquals

assertNotAlmostEqual()

failIfAlmostEqual

assertNotAlmostEquals

assertRegex()

assertRegexpMatches

assertNotRegex()

assertNotRegexpMatches

assertRaisesRegex()

assertRaisesRegexp

Obsoleto desde la versión 3.1: Los alias de fail* que figuran en la segunda columna han sido declarados obsoletos.

Obsoleto desde la versión 3.2: Los alias de aserción* que figuran en la tercera columna han sido declarados obsoletos.

Obsoleto desde la versión 3.2: assertRegexpMatches y assertRaisesRegexp han sido renombrados a assertRegex() y assertRaisesRegex().

Obsoleto desde la versión 3.5: El nombre assertNotRegexpMatches se ha declarado obsoleto en favor de assertNotRegex().

Agrupando tests

class unittest.TestSuite(tests=())

Esta clase representa una agregación de casos de test individuales y conjuntos de tests. La clase presenta la interfaz que necesita el corredor de tests para poder ser ejecutado como cualquier otro caso de test. Ejecutar una instancia TestSuite es lo mismo que iterar sobre el conjunto, ejecutando cada test individualmente.

Si se indican tests, debe ser un iterable de casos de test individuales u otros conjuntos de tests que se usarán para construir el conjunto inicialmente. Se proporcionan métodos adicionales para añadir casos de test y conjuntos a la colección más adelante.

Los objetos de TestSuite se comportan de manera muy parecida a los objetos de TestCase, excepto que no implementan un test. En cambio, se usan para agregar tests en grupos de tests que deben ser ejecutados juntos. Existen algunos métodos adicionales para agregar tests a las instancias de TestSuite:

addTest(test)

Añade un TestCase o TestSuite al conjunto.

addTests(tests)

Añade todos los tests de un iterable de TestCase y TestSuite a este conjunto de tests.

Esto equivale a iterar sobre tests, llamando a addTest() para cada elemento.

TestSuite comparte los siguientes métodos con TestCase:

run(result)

Ejecuta los tests asociados a este conjunto, recogiendo el resultado en el objeto de resultado del test pasado como result. Tenga en cuenta que a diferencia de TestCase.run(), TestSuite.run() requiere que se pase el objeto resultado.

debug()

Ejecuta los tests asociados con este conjunto sin recoger los resultados. Esto permite que las excepciones lanzadas por este test sean propagadas al invocador y puedes ser usadas para apoyar tests que están ejecutándose con un debugger.

countTestCases()

Retorna el numero de tests representados por este objeto de test, incluidos todos los test individuales y los sub-conjuntos.

__iter__()

Los tests agrupados por una TestSuite se acceden siempre por iteración. Las subclases pueden proporcionar tests anulando __iter__(). Tenga en cuenta que este método puede ser invocado varias veces en un mismo conjunto (por ejemplo, cuando se cuentan los tests o se comparan por igualdad), por lo que los tests retornados por iteraciones repetidas antes de TestSuite.run() deben ser los mismos para cada iteración de invocación. Después de TestSuite.run(), los invocados no deben confiar en los tests retornados por este método a menos que el invocado utilice una subclase que anule TestSuite._removeTestAtIndex() para preservar las referencias de los tests.

Distinto en la versión 3.2: En versiones anteriores la TestSuite accedía a los test directamente en lugar de a través de la iteración, por lo que anular __iter__() no era suficiente para proporcionar los tests.

Distinto en la versión 3.4: En versiones anteriores, la TestSuite tenía referencias a cada TestCase después de TestSuite.run(). Las subclases pueden restaurar ese comportamiento anulando TestSuite._removeTestAtIndex().

En el uso típico de un objeto TestSuite, el método run() es invocado por un TestRunner en lugar de por el marco de test de pruebas automático del usuario final.

Cargando y ejecutando tests

class unittest.TestLoader

La clase TestLoader se utiliza para crear conjuntos de tests a partir de clases y módulos. Normalmente, no es necesario crear una instancia de esta clase; el módulo unittest proporciona una instancia que puede ser compartida como unittest.defaultTestLoader. Sin embargo, el uso de una subclase o instancia permite la personalización de algunas propiedades configurables.

Los objetos TestLoader tienen los siguientes atributos:

errors

Una lista de los errores no fatales encontrados durante los tests de carga. No reseteados por el cargador en ningún momento. Los errores fatales son señalados por el método relevante que lanza una excepción al invocador. Los errores no fatales también son indicados por una prueba sintética que lanzará el error original cuando se ejecute.

Nuevo en la versión 3.5.

Los objetos TestLoader tienen los siguientes métodos:

loadTestsFromTestCase(testCaseClass)

Devuelve un conjunto de todos los casos de test contenidos en la TestCasederivada de testCaseClass.

Se crea una instancia de caso de test para cada método nombrado por getTestCaseNames(). Por defecto, estos son los nombres de los métodos que comienzan con test. Si getTestCaseNames() no retorna ningún método, pero se implementa el método runTest(), se crea un único caso de test para ese método.

loadTestsFromModule(module, pattern=None)

Devuelva un conjunto de todos los casos de test contenidos en el módulo dado. Este método busca en module clases derivadas de TestCase y crea una instancia de la clase para cada método de test definido para la clase.

Nota

Aunque el uso de una jerarquía de clases derivadas de TestCase puede ser conveniente para compartir configuraciones y funciones de ayuda, la definición de métodos de test en clases base que no están destinadas a ser instanciadas directamente no complementa bien con este método. Hacerlo, sin embargo, puede ser útil cuando las configuraciones son diferentes y están definidas en subclases.

Si un módulo proporciona una función load_tests será llamado para cargar los tests. Esto permite a los módulos personalizar la carga de los tests. Este es el load_tests protocol. El argumento pattern se pasa como tercer argumento a load_tests.

Distinto en la versión 3.2: Se ha añadido soporte para load_tests.

Distinto en la versión 3.5: El argumento por defecto use_load_tests no documentado y no oficial es obsoleto e ignorado, aunque sigue siendo aceptado por la retrocompatibilidad. El método también acepta ahora un argumento de sólo palabra clave pattern que se pasa a load_tests como tercer argumento.

loadTestsFromName(name, module=None)

Retorna un conjunto de todos los casos de test dado un especificador de cadena.

El especificador name es un «nombre punteado» que puede resolverse ya sea a un módulo, una clase de caso de test, un método de test dentro de una clase de caso de test, una instancia TestSuite, o un objeto invocable que devuelve una instancia TestCase o TestSuite. Estas comprobaciones se aplican en el orden que se indica aquí; es decir, un método en una posible clase de caso de test se recogerá como «un método de test dentro de una clase de caso de test”, en lugar de «un objeto invocable”.

Por ejemplo, si tiene un módulo SampleTests que contiene una clase derivada de TestCase SampleTestCase con tres métodos de test (test_one(), test_two(), y test_three()), el especificador SampleTests.SampleTestCase' haría que este método devolviera una suite que ejecutara los tres métodos de prueba. El uso del especificador SampleTests.SampleTestCase.test_two' provocaría que este método devolviera una suite de tests que ejecutaría sólo el método de test test_two(). El especificador puede referirse a los módulos y paquetes que no han sido importados; serán importados como un efecto secundario.

El método opcionalmente resuelve name relativo al module dado.

Distinto en la versión 3.5: Si un ImportError o AttributeError ocurre mientras atraviesa name entonces se devolverá un test sintético que lanza ese error cuando se ejecuta. Estos errores están incluidos en los errores acumulados por self.errors.

loadTestsFromNames(names, module=None)

Similar a loadTestsFromName(), pero toma una secuencia de nombres en lugar de un solo nombre. El valor de retorno es una suite de tests que soporta todos los test definidos para cada nombre.

getTestCaseNames(testCaseClass)

Devuelve una secuencia ordenada de nombres de métodos encontrados dentro de testCaseClass; esta debería ser una subclase de TestCase.

discover(start_dir, pattern='test*.py', top_level_dir=None)

Encuentra todos los módulos de prueba recurriendo a subdirectorios del directorio de inicio especificado, y retorna un objeto de TestSuite que los contenga. Sólo se cargarán los archivos de test que coincidan con el pattern. (Utilizando la coincidencia de patrones de estilo de shell.) Sólo se cargarán los nombres de los módulos que sean importables (es decir, que sean identificadores Python válidos).

Todos los módulos de test deben ser importables desde el nivel superior del proyecto. Si el directorio de inicio no es el directorio de nivel superior, entonces el directorio de nivel superior debe ser especificado por separado.

Si la importación de un módulo falla, por ejemplo debido a un error de sintaxis, entonces esto se registrará como un error único y el descubrimiento continuará. Si el fallo en la importación se debe a que SkipTest se ha lanzado, se registrará como un salto en lugar de un error.

Si se encuentra un paquete (un directorio que contiene un archivo llamado __init__.py), se comprobará si el paquete tiene una función load_tests. Si existe, entonces se invocará package.load_tests(loader, tests, pattern). Test discovery se encarga de asegurar que un paquete sólo se comprueba una vez durante una invocación, incluso si la propia función load_tests llama a loader.discover.

Si load_tests existe, entonces el descubrimiento no recurre en el paquete, load_tests es responsable de cargar todos los tests en el paquete.

El patrón no se almacena deliberadamente como atributo cargador para que los paquetes puedan continuar descubriéndose a sí mismos. top_level_dir se almacena de forma que load_tests no necesita pasar este argumento a loader.discover().

start_dir puede ser un nombre de módulo punteado así como un directorio.

Nuevo en la versión 3.2.

Distinto en la versión 3.4: Los módulos que lanzan SkipTest en la importación se registran como saltos, no como errores.

Distinto en la versión 3.4: start_dir puede ser un paquete de espacios de nombres.

Distinto en la versión 3.4: Las rutas se ordenan antes de ser importadas para que el orden de ejecución sea el mismo, incluso si el orden del sistema de archivos subyacente no depende del nombre del archivo.

Distinto en la versión 3.5: Los paquetes encontrados son ahora comprobados para load_tests sin importar si su ruta coincide con el pattern, porque es imposible que el nombre de un paquete coincida con el patrón por defecto.

Los siguientes atributos de un TestLoader pueden ser configurados ya sea por subclasificación o asignación en una instancia:

testMethodPrefix

Cadena que da el prefijo de los nombres de métodos que serán interpretados como métodos de test. El valor por defecto es 'test'.

Esto afecta a getTestCaseNames() y a todos los métodos loadTestsFrom*() .

sortTestMethodsUsing

Función que se utiliza para comparar los nombres de los métodos al clasificarlos en getTestCaseNames() y todos los métodos loadTestsFrom*().

suiteClass

Objeto invocable que construye un conjunto de pruebas a partir de una lista de pruebas. No se necesitan métodos en el objeto resultante. El valor por defecto es la clase TestSuite.

Esto afecta a todos los métodos loadTestsFrom*().

testNamePatterns

Lista de patrones de nombres de test de comodines al estilo del shell de Unix que los métodos de test tienen que coincidir con para ser incluidos en las suites de test (ver opción -v).

Si este atributo no es None (el predeterminado), todos los métodos de test que se incluyan en los paquetes de test deben coincidir con uno de los patrones de esta lista. Tenga en cuenta que las coincidencias se realizan siempre utilizando fnmatch.fnmatchcase(), por lo que a diferencia de los patrones pasados a la opción -v, los patrones de subcadena simple tendrán que ser convertidos utilizando los comodines *.

Esto afecta a todos los métodos loadTestsFrom*().

Nuevo en la versión 3.7.

class unittest.TestResult

Esta clase se utiliza para recopilar información sobre qué tests han tenido éxito y cuáles han fracasado.

Un objeto TestResult almacena los resultados de una serie de pruebas. Las clases TestCase y TestSuite aseguran que los resultados se registren correctamente; los autores de los tests no tienen que preocuparse de registrar el resultado de las mismas.

Los marcos de pruebas construidos sobre unittest pueden querer acceder al objeto TestResult generado por la ejecución de un conjunto de tests con fines de reporte; una instancia TestResult es devuelta por el método TestRunner.run() para este propósito.

Las instancias de TestResult tienen los siguientes atributos que serán de interés cuando se inspeccionen los resultados de la ejecución de un conjunto de tests:

errors

Una lista que contiene 2 tuplas de instancias TestCase y cadenas con formato de tracebacks. Cada tupla representa una prueba que lanzó una excepción inesperada.

failures

Una lista que contiene 2 tuplas de instancias TestCase y cadenas con formato de traceback. Cada tupla representa un test en el que un fallo fue explícitamente señalado usando los métodos TestCase.assert*().

skipped

Una lista que contiene 2 tuplas de instancias de TestCase y cadenas que contienen la razón para saltarse el test.

Nuevo en la versión 3.1.

expectedFailures

Una lista que contiene 2 tuplas de instancias TestCase y cadenas con formato de traceback. Cada tupla representa un fallo esperado del caso de test.

unexpectedSuccesses

Una lista que contiene instancias de TestCase que fueron marcadas como fracasos esperados, pero tuvieron éxito.

shouldStop

Puesto en True cuando la ejecución de los tests se detenga por stop().

testsRun

El número total de tests realizados hasta ahora.

buffer

Si se ajusta a true, sys.stdout y sys.stderr serán almacenados entre startTest() y stopTest() siendo llamados. La salida recolectada sólo tendrá eco en el verdadero sys.stdout y sys.stderr si la prueba falla o se equivoca. Cualquier salida también se adjunta al mensaje de fallo / error.

Nuevo en la versión 3.2.

failfast

Si se ajusta a true stop() se llamará al primer fallo o error, deteniendo la ejecución de la prueba.

Nuevo en la versión 3.2.

tb_locals

Si se ajusta a true entonces las variables locales se mostrarán en los tracebacks.

Nuevo en la versión 3.5.

wasSuccessful()

Devuelve True si todas las pruebas realizadas hasta ahora han pasado, de lo contrario devuelve False.

Distinto en la versión 3.4: Devuelve False si hubo algún unexpectedSuccesses de las pruebas marcadas con el decorador expectedFailure().

stop()

Este método puede ser llamado para señalar que el conjunto de pruebas que se están ejecutando debe ser abortado poniendo el atributo shouldStop en True. TestRunner los objetos deben respetar esta bandera y regresar sin ejecutar ninguna prueba adicional.

Por ejemplo, esta característica es utilizada por la clase TextTestRunner para detener el marco de pruebas cuando el usuario señala una interrupción desde el teclado. Las herramientas interactivas que proporcionan implementaciones de TestRunner pueden usar esto de manera similar.

Los siguientes métodos de la clase TestResult se utilizan para mantener las estructuras de datos internos, y pueden ampliarse en subclases para apoyar los requisitos de información adicionales. Esto es particularmente útil para construir herramientas que apoyen la presentación de informes interactivos mientras se ejecutan las pruebas.

startTest(test)

Llamado cuando el caso de prueba test está a punto de ser ejecutado.

stopTest(test)

Llamado después de que el caso de prueba prueba haya sido ejecutado, independientemente del resultado.

startTestRun()

Llamado una vez antes de que se ejecute cualquier prueba.

Nuevo en la versión 3.1.

stopTestRun()

Llamado una vez después de que se ejecuten todas las pruebas.

Nuevo en la versión 3.1.

addError(test, err)

Llamado cuando el caso de prueba test plantea una excepción inesperada. err es una tupla de la forma devuelta por sys.exc_info(): (type, value, traceback).

La implementación por defecto añade una tupla (test, formatted_err) al atributo errors de la instancia, donde formatted_err es una traza formateada derivada de err.

addFailure(test, err)

Llamado cuando el caso de prueba test señala un fallo. err es una tupla de la forma devuelta por sys.exc_info(): (type, value, traceback).

La implementación por defecto añade una tupla (test, formatted_err) al atributo failures de la instancia, donde formatted_err es una traza formateada derivada de err.

addSuccess(test)

Llamado cuando el caso de prueba test tenga éxito.

La implementación por defecto no hace nada.

addSkip(test, reason)

Llamado cuando se salta el caso de prueba test. reason es la razón que la prueba dio para saltarse.

La implementación por defecto añade una tupla (test, reason) al atributo skipped de la instancia.

addExpectedFailure(test, err)

Llamó cuando el caso de prueba test falla, pero fue marcado con el decorador expectedFailure().

La implementación por defecto añade una tupla (test, formatted_err) al atributo expectedFailures de la instancia, donde formatted_err es una traza formateada derivada de err.

addUnexpectedSuccess(test)

Llamó cuando el caso de prueba test se marcó con el decorador expectedFailure(), pero tuvo éxito.

La implementación por defecto añade la prueba al atributo unexpectedSuccesses de la instancia.

addSubTest(test, subtest, outcome)

Llamado cuando termina una subtest. test es el caso de prueba correspondiente al método de test. subtest es una instancia personalizada TestCase que describe el test.

Si outcome es None, el subtest tuvo éxito. De lo contrario, falló con una excepción en la que outcome es una tupla de la forma devuelta por sys.exc_info(): (type, value, traceback).

La implementación por defecto no hace nada cuando el resultado es un éxito, y registra los fallos del subtest como fallos normales.

Nuevo en la versión 3.4.

class unittest.TextTestResult(stream, descriptions, verbosity)

Una implementación concreta de TestResult utilizado por el TextTestRunner.

Nuevo en la versión 3.2: Esta clase se llamaba anteriormente _TextTestResult. El antiguo nombre todavía existe como un alias pero está obsoleto.

unittest.defaultTestLoader

Instancia de la clase TestLoader destinada a ser compartida. Si no es necesario personalizar la clase TestLoader, esta instancia puede utilizarse en lugar de crear repetidamente nuevas instancias.

class unittest.TextTestRunner(stream=None, descriptions=True, verbosity=1, failfast=False, buffer=False, resultclass=None, warnings=None, *, tb_locals=False)

Una implementación básica del test runner que produce resultados en una corriente. Si stream es None, el valor por defecto, sys.stderr se utiliza como flujo de salida. Esta clase tiene unos pocos parámetros configurables, pero es esencialmente muy simple. Las aplicaciones gráficas que ejecutan las suites de prueba deben proporcionar implementaciones alternativas. Tales implementaciones deberían aceptar **kwargs como interfaz para construir los cambios de los corredores cuando se añaden características a unittest.

Por defecto este runner muestra DeprecationWarning, PendingDeprecationWarning, ResourceWarning y ImportWarning aunque estén ignorados por defecto. Las advertencias de deprecación causadas por métodos deprecated unittest también tienen un caso especial y, cuando los filtros de advertencia están 'default' o 'always', aparecerán sólo una vez por módulo, para evitar demasiados mensajes de advertencia. Este comportamiento puede ser anulado usando las opciones -Wd o -Wa de Python (ver Control de advertencias) y dejando warnings a None.

Distinto en la versión 3.2: Añadió el argumento warnings.

Distinto en la versión 3.2: El flujo por defecto está configurado como sys.stderr en tiempo de instanciación en lugar de tiempo de importación.

Distinto en la versión 3.5: Añadido el parámetro tb_locals.

_makeResult()

Este método devuelve la instancia de TestResult usada por run(). No está destinado a ser llamado directamente, pero puede ser anulado en subclases para proporcionar un TestResult personalizado.

_makeResult() instanciando la clase o el pasaje llamado en el constructor TextTestRunner como el argumento de resultclass. Por defecto es TextTestResult si no se proporciona ninguna resultclass. La clase de resultado se instanciará con los siguientes argumentos:

stream, descriptions, verbosity

run(test)

Este método es la principal interfaz pública del TextTestRunner. Este método toma una instancia TestSuite o TestCase. Se crea una TestResult llamando a _makeResult() y se ejecuta(n) la(s) prueba(s) y se imprimen los resultados a stdout.

unittest.main(module='__main__', defaultTest=None, argv=None, testRunner=None, testLoader=unittest.defaultTestLoader, exit=True, verbosity=1, failfast=None, catchbreak=None, buffer=None, warnings=None)

Un programa de línea de comandos que carga un conjunto de pruebas de módulo y las ejecuta; esto es principalmente para hacer los módulos de prueba convenientemente ejecutables. El uso más simple de esta función es incluir la siguiente línea al final de un guión de prueba:

if __name__ == '__main__':
    unittest.main()

Puedes hacer pruebas con información más detallada pasando el argumento de la verbosity:

if __name__ == '__main__':
    unittest.main(verbosity=2)

El argumento defaultTest es el nombre de una prueba única o un iterable de nombres de pruebas a ejecutar si no se especifican nombres de pruebas a través de argv. Si no se especifica o Ninguno y no se proporcionan nombres de pruebas vía argv, se ejecutan todas las pruebas encontradas en modulo.

El argumento argv puede ser una lista de opciones pasadas al programa, siendo el primer elemento el nombre del programa. Si no se especifica o Ninguno, se utilizan los valores de sys.argv.

El argumento testRunner puede ser una clase de corredor de prueba o una instancia ya creada de él. Por defecto main llama sys.exit() con un código de salida que indica el éxito o el fracaso de la ejecución de las pruebas.

El argumento testLoader tiene que ser una instancia TestLoader, y por defecto defaultTestLoader.

main apoya el uso del intérprete interactivo pasando el argumento exit=False. Esto muestra el resultado en la salida estándar sin llamar a sys.exit():

>>> from unittest import main
>>> main(module='test_module', exit=False)

Los parámetros failfast, catchbreak y buffer tienen el mismo efecto que las command-line options del mismo nombre.

El argumento warnings especifica el filtro de aviso que debe ser usado mientras se realizan los tests. Si no se especifica, permanecerá como None si se pasa una opción -W a python (ver Warning control), de lo contrario se establecerá como ’default’.

Invocar main en realidad devuelve una instancia de la clase TestProgram. Esto almacena el resultado de las pruebas ejecutadas como el atributo result.

Distinto en la versión 3.1: El parámetro exit fue añadido.

Distinto en la versión 3.2: Los parámetros verbosity, failfast, catchbreak, buffer y warnings fueron añadidos.

Distinto en la versión 3.4: El parámetro defaultTest fue cambiado para aceptar también un iterable de nombres de pruebas.

load_tests protocolo

Nuevo en la versión 3.2.

Los módulos o paquetes pueden personalizar la forma en que se cargan las pruebas a partir de ellos durante las ejecuciones de prueba normales o el descubrimiento de pruebas mediante la implementación de una función llamada load_tests.

Si un módulo de tests define load_tests será llamado por TestLoader.loadTestsFromModule() con los siguientes argumentos:

load_tests(loader, standard_tests, pattern)

donde pattern se pasa directamente desde loadTestsFromModule. Por defecto es None.

Debe retornar una TestSuite.

loader es la instancia de TestLoader haciendo la carga. standard_tests son los tests que se cargarían por defecto desde el módulo. Es común que los módulos de test sólo quieran añadir o quitar tests del conjunto de tests estándar. El tercer argumento se usa cuando se cargan paquetes como parte del descubrimiento de tests.

Una típica función de load_tests que carga pruebas de un conjunto específico de TestCase`class:`TestCase puede ser como:

test_cases = (TestCase1, TestCase2, TestCase3)

def load_tests(loader, tests, pattern):
    suite = TestSuite()
    for test_class in test_cases:
        tests = loader.loadTestsFromTestCase(test_class)
        suite.addTests(tests)
    return suite

Si discovery se inicia en un directorio que contiene un paquete, ya sea desde la línea de comandos o llamando a TestLoader.discover(), entonces el paquete __init__.py se comprobará por load_tests. Si esa función no existe, discover se reincorporará al paquete como si fuera un directorio más. De lo contrario, el descubrimiento de los tests del paquete se dejará en load_tests que se llama con los siguientes argumentos:

load_tests(loader, standard_tests, pattern)

Esto debería devolver un TestSuite que represente todas las pruebas del paquete. (test_estándar sólo contendrá las pruebas recogidas de __init__.py.)

Debido a que el patrón se pasa a load_tests el paquete es libre de continuar (y potencialmente modificar) el descubrimiento de pruebas. Una función de “no hace nada” load_test para un paquete de pruebas se vería como:

def load_tests(loader, standard_tests, pattern):
    # top level directory cached on loader instance
    this_dir = os.path.dirname(__file__)
    package_tests = loader.discover(start_dir=this_dir, pattern=pattern)
    standard_tests.addTests(package_tests)
    return standard_tests

Distinto en la versión 3.5: Discovery ya no comprueba si los nombres de los paquetes coinciden con el patrón debido a la imposibilidad de que los nombres de los paquetes coincidan con el patrón por defecto.

Instalaciones para clases y módulos

Los accesorios de nivel de clase y módulo se implementan en TestSuite. Cuando el conjunto de pruebas se encuentra con una prueba de una nueva clase entonces se llama tearDownClass() de la clase anterior (si existe), seguido de setUpClass() de la nueva clase.

Del mismo modo, si una prueba es de un módulo diferente de la prueba anterior, entonces se ejecuta DesmontarMódulo del módulo anterior, seguido de DesmontarMódulo del nuevo módulo.

Después de todas las pruebas, se ejecutan los últimos tearDownClass y tearDownModule.

Tenga en cuenta que los accesorios compartidos no juegan bien con las características [potenciales] como la paralelización de la prueba y rompen el aislamiento de la prueba. Deben ser usados con cuidado.

El orden por defecto de las pruebas creadas por los cargadores de pruebas unitarias es agrupar todas las pruebas de los mismos módulos y clases. Esto llevará a que setUpClass / setUpModule (etc) sea llamado exactamente una vez por clase y módulo. Si se aleatoriza el orden, de manera que las pruebas de diferentes módulos y clases sean adyacentes entre sí, entonces estas funciones compartidas de fixture pueden ser llamadas varias veces en una sola ejecución de prueba.

Los accesorios compartidos no están pensados para trabajar con suites con pedidos no estándar. Todavía existe una BaseTestSuite para los marcos de trabajo que no quieren soportar accesorios compartidos.

Si hay alguna excepción planteada durante una de las funciones compartidas del aparato, la prueba se notifica como un error. Debido a que no hay una instancia de prueba correspondiente, se crea un objeto _ErrorHolder (que tiene la misma interfaz que un TestCase) para representar el error. Si sólo estás usando el standard unittest test runner entonces este detalle no importa, pero si eres un autor de marcos de trabajo puede ser relevante.

setUpClass y tearDownClass

Estos deben ser implementados como métodos de clase:

import unittest

class Test(unittest.TestCase):
    @classmethod
    def setUpClass(cls):
        cls._connection = createExpensiveConnectionObject()

    @classmethod
    def tearDownClass(cls):
        cls._connection.destroy()

Si quieres que se invoque a SetUpClass y BreakdownClass en clases base, debes llamarlos tú mismo. Las implementaciones en TestCase están vacías.

Si se lanza una excepción durante una setUpClass, entonces los tests de la clase no se ejecutan y la tearDownClass no se ejecuta. Las clases que se salten no tendrán setUpClass o tearDownClass. Si la excepción es una SkipTest entonces la clase será reportada como salteada en lugar de como un error.

setUpModule y tearDownModule

Estos deben ser implementados como funciones:

def setUpModule():
    createConnection()

def tearDownModule():
    closeConnection()

Si se lanza una excepción en un setUpModule, entonces no se ejecutará ninguna de las pruebas del módulo y no se ejecutará el tearDownModule. Si la excepción es una SkipTest entonces el módulo será reportado como saltado en lugar de como un error.

Para agregar código de limpieza que se debe ejecutar incluso en el caso de una excepción, utilice addModuleCleanup:

unittest.addModuleCleanup(function, /, *args, **kwargs)

Añade una función que se llamará después de tearDownModule() para limpiar los recursos utilizados durante la clase de test. Las funciones se llamarán en orden inverso al orden en que se agregan (LIFO). Se llaman con cualquier argumento y palabra clave que se pase a addModuleCleanup() cuando se añadan.

Si setUpModule() falla, lo que significa que tearDownModule() no se invoca, entonces cualquier función de limpieza añadida seguirá siendo invocada.

Nuevo en la versión 3.8.

unittest.doModuleCleanups()

Esta función se llama incondicionalmente después de tearDownModule(), o después de setUpModule() si setUpModule() lanza una excepción.

It is responsible for calling all the cleanup functions added by addModuleCleanup(). If you need cleanup functions to be called prior to tearDownModule() then you can call doModuleCleanups() yourself.

doModuleCleanups() saca los métodos de la pila de funciones de limpieza uno a uno, así que se puede llamar en cualquier momento.

Nuevo en la versión 3.8.

Manejo de señales

Nuevo en la versión 3.2.

La opción -c/--catch línea de comando para unittest, junto con el parámetro catchbreak de unittest.main(), proporcionan un manejo más amigable del control-C durante una prueba. Con el comportamiento catch break habilitado, control-C permitirá que se complete la prueba que se está ejecutando actualmente, y la ejecución de la prueba terminará y reportará todos los resultados hasta ahora. Un segundo control-C lanzará una KeyboardInterrupt de la manera habitual.

El manejador de señales de manejo de control-c intenta permanecer compatible con el código o las pruebas que instalan su propio manejador signal.SIGINT . Si se llama al manejador unittest pero no es el manejador signal.SIGINT instalado, es decir, ha sido reemplazado por el sistema bajo test y delegado, entonces llama al manejador por defecto. Este será normalmente el comportamiento esperado por el código que reemplaza un manejador instalado y delega en él. Para las pruebas individuales que necesiten el manejo de control-c de unittest deshabilitado se puede usar el decorador removeHandler().

Hay algunas funciones de utilidad para que los autores de marcos de trabajo habiliten la funcionalidad de control de control-c dentro de los marcos de prueba.

unittest.installHandler()

Instala el controlador de control-c. Cuando se recibe una signal.SIGINT (normalmente en respuesta a que el usuario presione control-c) todos los resultados registrados tienen stop() llamado.

unittest.registerResult(result)

Registrar un objeto TestResult para el manejo de control-c. El registro de un resultado almacena una referencia débil a él, por lo que no evita que el resultado sea recogido por el recolector de basura.

El registro de un objeto TestResult no tiene efectos secundarios si el manejo de control-c no está habilitado, por lo que los marcos de pruebas pueden registrar incondicionalmente todos los resultados que crean independientemente de si el manejo está habilitado o no.

unittest.removeResult(result)

Elimine un resultado registrado. Una vez que un resultado ha sido eliminado, stop() ya no se llamará en ese objeto de resultado en respuesta a un control-c.

unittest.removeHandler(function=None)

Cuando se llama sin argumentos, esta función quita el gestor control-c si se ha instalado. Esta función también se puede utilizar como decorador de tests para quitar temporalmente el controlador mientras se ejecuta el test:

@unittest.removeHandler
def test_signal_handling(self):
    ...

unittest.mock — Biblioteca de objetos simulados

Nuevo en la versión 3.3.

Source code: Lib/unittest/mock.py [https://github.com/python/cpython/tree/3.9/Lib/unittest/mock.py]

unittest.mock es una biblioteca para pruebas de software en Python. Te permite reemplazar partes del sistema bajo prueba con objetos simulados y hacer aserciones sobre cómo se han utilizado.

El módulo unittest.mock proporciona una clase principal Mock eliminando la necesidad de crear una gran cantidad de stubs en todo el conjunto de pruebas. Después de realizar una determinada acción, puedes hacer aserciones sobre qué métodos/atributos se usaron y los argumentos con los que se llamaron. También puedes especificar valores de retorno y establecer los atributos necesarios de la forma habitual.

Además, mock proporciona un decorador patch() que puede manejar el parcheo de atributos a nivel de clase y de módulo dentro del ámbito de una prueba, junto con sentinel para crear objetos únicos. Consulta quick guide para ver algunos ejemplos de cómo utilizar Mock, MagicMock y patch().

Mock is designed for use with unittest and is based on the “action -> assertion” pattern instead of “record -> replay” used by many mocking frameworks.

Hay un backport del módulo unittest.mock para versiones anteriores de Python disponible en PyPI [https://pypi.org/project/mock].

Guía rápida

Los objetos de las clases Mock y MagicMock van creando todos los atributos y métodos a medida que se accede a ellos y almacenan detalles de cómo se han utilizado. Puedes configurarlos para especificar valores de retorno o limitar qué atributos están disponibles y posteriormente hacer aserciones sobre cómo han sido utilizados:

>>> from unittest.mock import MagicMock
>>> thing = ProductionClass()
>>> thing.method = MagicMock(return_value=3)
>>> thing.method(3, 4, 5, key='value')
3
>>> thing.method.assert_called_with(3, 4, 5, key='value')

side_effect te permite implementar efectos colaterales, lo que incluye lanzar una excepción cuando se llama a un objeto simulado:

>>> mock = Mock(side_effect=KeyError('foo'))
>>> mock()
Traceback (most recent call last):
 ...
KeyError: 'foo'

>>> values = {'a': 1, 'b': 2, 'c': 3}
>>> def side_effect(arg):
...     return values[arg]
...
>>> mock.side_effect = side_effect
>>> mock('a'), mock('b'), mock('c')
(1, 2, 3)
>>> mock.side_effect = [5, 4, 3, 2, 1]
>>> mock(), mock(), mock()
(5, 4, 3)

Existen muchas otras formas de configurar y controlar el comportamiento de Mock. Por ejemplo, el argumento spec configura el objeto simulado para que tome su especificación de otro objeto. Cualquier intento de acceder a atributos o métodos en el objeto simulado que no existan en la especificación fallará lanzando una excepción AttributeError.

El decorador / gestor de contexto patch() facilita la simulación de clases u objetos en un módulo bajo prueba. El objeto que especifiques será reemplazado por un objeto simulado (u otro objeto) durante la prueba y será restaurado cuando esta finalice:

>>> from unittest.mock import patch
>>> @patch('module.ClassName2')
... @patch('module.ClassName1')
... def test(MockClass1, MockClass2):
...     module.ClassName1()
...     module.ClassName2()
...     assert MockClass1 is module.ClassName1
...     assert MockClass2 is module.ClassName2
...     assert MockClass1.called
...     assert MockClass2.called
...
>>> test()

Nota

Cuando anidas decoradores patch, los objetos simulados se pasan a la función decorada en el mismo orden en el que fueron aplicados (el orden normal en el que se aplican los decoradores en Python). Esto significa de abajo hacia arriba, por lo que en el ejemplo anterior se pasa primero el objeto simulado para module.ClassName1.

Al usar patch() es importante que parchees los objetos en el espacio de nombres donde son buscados. Esto normalmente es sencillo, pero para una guía rápida, lee dónde parchear.

Además de decorador, la función patch() se puede usar como gestor de contexto en una declaración with:

>>> with patch.object(ProductionClass, 'method', return_value=None) as mock_method:
...     thing = ProductionClass()
...     thing.method(1, 2, 3)
...
>>> mock_method.assert_called_once_with(1, 2, 3)

También existe la función patch.dict() que permite establecer valores en un diccionario dentro de un ámbito y restaurar el diccionario a su estado original cuando finaliza la prueba:

>>> foo = {'key': 'value'}
>>> original = foo.copy()
>>> with patch.dict(foo, {'newkey': 'newvalue'}, clear=True):
...     assert foo == {'newkey': 'newvalue'}
...
>>> assert foo == original

Mock admite la simulación de los métodos mágicos de Python. La forma más sencilla de utilizar métodos mágicos es mediante la clase MagicMock. Te permite hacer cosas como:

>>> mock = MagicMock()
>>> mock.__str__.return_value = 'foobarbaz'
>>> str(mock)
'foobarbaz'
>>> mock.__str__.assert_called_with()

Mock también permite asignar funciones (u otras instancias de Mock) a métodos mágicos y se asegura de que serán llamadas de forma apropiada. La clase MagicMock es solo una variante de Mock con la diferencia de que tiene todos los métodos mágicos previamente creados para ti (bueno, todos los que son útiles).

El siguiente es un ejemplo de uso de métodos mágicos utilizando la clase Mock ordinaria:

>>> mock = Mock()
>>> mock.__str__ = Mock(return_value='wheeeeee')
>>> str(mock)
'wheeeeee'

Para asegurarte de que los objetos simulados en tus pruebas tienen exactamente la misma API que los objetos que están reemplazando, puedes usar autoespecificación. La autoespecificación se puede realizar a través del argumento autospec de patch, o mediante la función create_autospec(). La autoespecificación crea objetos simulados que tienen los mismos atributos y métodos que los objetos que están reemplazando, y todas las función y métodos (incluidos los constructores) tienen la misma firma de llamada que los objetos reales.

Esto asegura que tus simulaciones fallarán, si se utilizan incorrectamente, de la misma manera que lo haría tu código en producción:

>>> from unittest.mock import create_autospec
>>> def function(a, b, c):
...     pass
...
>>> mock_function = create_autospec(function, return_value='fishy')
>>> mock_function(1, 2, 3)
'fishy'
>>> mock_function.assert_called_once_with(1, 2, 3)
>>> mock_function('wrong arguments')
Traceback (most recent call last):
 ...
TypeError: <lambda>() takes exactly 3 arguments (1 given)

create_autospec() también se puede usar en clases, donde copia la firma del método __init__, y en objetos invocables, donde copia la firma del método __call__.

La clase Mock

Mock es un objeto simulado flexible, destinado a reemplazar el uso de stubs y dobles de prueba en todo tu código. Los objetos Mock son invocables y crean atributos en el mismo momento que se accede a ellos como nuevos objetos Mock 1. Acceder al mismo atributo siempre retornará el mismo objeto Mock. Además, registran cómo los usas, lo que te permite hacer aserciones sobre cómo tu código ha interaccionado con ellos.

MagicMock es una subclase de Mock con todos los métodos mágicos creados previamente y listos para ser usados. También hay variantes no invocables, útiles cuando se están simulando objetos que no se pueden llamar: NonCallableMock y NonCallableMagicMock

Los decoradores patch() facilitan la sustitución temporal de clases en un módulo en particular con un objeto Mock. Por defecto, patch() creará un objeto MagicMock automáticamente. Se puede especificar una clase alternativa a Mock usando el argumento new_callable de patch().

class unittest.mock.Mock(spec=None, side_effect=None, return_value=DEFAULT, wraps=None, name=None, spec_set=None, unsafe=False, **kwargs)

Crea un nuevo objeto Mock. Mock toma varios argumentos opcionales que especifican el comportamiento del objeto Mock:

spec: Puede ser una lista de cadenas de caracteres o un objeto existente previamente (una clase o una instancia) que actúa como la especificación del objeto simulado. Si pasas un objeto, se forma una lista de cadenas llamando a la función dir en el objeto (excluyendo los métodos y atributos mágicos no admitidos). Acceder a cualquier atributo que no esté en esta lista generará una excepción AttributeError.

Si spec es un objeto (en lugar de una lista de cadenas de caracteres), __class__ retorna la clase del objeto especificado. Esto permite que los objetos simulados pasen las pruebas de isinstance().

spec_set: Una variante más estricta de spec. Si se utiliza, cualquier intento de establecer u obtener un atributo del objeto simulado que no esté en el objeto pasado como spec_set lanzará una excepción AttributeError.

side_effect: Una función que se llamará cada vez que el objeto simulado sea invocado. Consultar el atributo side_effect para más información. Es útil para lanzar excepciones o para cambiar dinámicamente valores de retorno. La función se llama con los mismos argumentos que el objeto simulado, y a menos que retorne DEFAULT, su valor de retorno se utiliza como valor de retorno del propio objeto simulado.

Alternativamente side_effect puede ser una clase o instancia de excepción. En este caso, se lanza la excepción cuando se llama al objeto simulado.

Si side_effect es un iterable, cada llamada al objeto simulado retornará el siguiente valor del iterable.

Un side_effect se puede desactivar estableciéndolo en None.

return_value: El valor retornado cuando se llama al objeto simulado. Por defecto, este es una nueva instancia de la clase Mock (creada en el primer acceso). Consultar el atributo return_value para más detalles.

unsafe: Por defecto, si cualquier atributo comienza con assert o assret y se intenta acceder a él, se lanza una excepción AttributeError. Pasar unsafe=True permitirá el acceso a estos atributos.

Nuevo en la versión 3.5.

wraps: objeto a envolver (simular) por la instancia de Mock. Si wraps no es None, al llamar al objeto Mock se pasa la llamada a través del objeto envuelto (retornando el resultado real). Acceder a un atributo del objeto simulado retornará otro objeto Mock que envuelve al atributo correspondiente del objeto real envuelto (de modo que intentar acceder a un atributo que no existe lanzará una excepción AttributeError).

Si el objeto simulado tiene un return_value explícito establecido, las llamadas no se pasan al objeto envuelto y return_value se retorna en su lugar.

name: Si el objeto simulado tiene un nombre, será utilizado en la representación imprimible del mismo. Esto puede ser útil para la depuración. El nombre se propaga a los objetos simulados hijos.

Los objetos simulados también pueden ser invocados con argumentos por palabra clave arbitrarios. Estos serán utilizados para establecer atributos en el objeto simulado una vez creado. Consultar el método configure_mock() para más detalles.

assert_called()

Aserta si el objeto simulado se ha invocado al menos una vez.

>>> mock = Mock()
>>> mock.method()
<Mock name='mock.method()' id='...'>
>>> mock.method.assert_called()

Nuevo en la versión 3.6.

assert_called_once()

Aserta si el objeto simulado se ha invocado exactamente una vez.

>>> mock = Mock()
>>> mock.method()
<Mock name='mock.method()' id='...'>
>>> mock.method.assert_called_once()
>>> mock.method()
<Mock name='mock.method()' id='...'>
>>> mock.method.assert_called_once()
Traceback (most recent call last):
...
AssertionError: Expected 'method' to have been called once. Called 2 times.

Nuevo en la versión 3.6.

assert_called_with(*args, **kwargs)

Este método es una manera apropiada de asertar si la última llamada se ha realizado de una manera particular:

>>> mock = Mock()
>>> mock.method(1, 2, 3, test='wow')
<Mock name='mock.method()' id='...'>
>>> mock.method.assert_called_with(1, 2, 3, test='wow')

assert_called_once_with(*args, **kwargs)

Assert that the mock was called exactly once and that call was with the specified arguments.

>>> mock = Mock(return_value=None)
>>> mock('foo', bar='baz')
>>> mock.assert_called_once_with('foo', bar='baz')
>>> mock('other', bar='values')
>>> mock.assert_called_once_with('other', bar='values')
Traceback (most recent call last):
  ...
AssertionError: Expected 'mock' to be called once. Called 2 times.

assert_any_call(*args, **kwargs)

Aserta si el objeto simulado se ha invocado con los argumentos especificados.

La aserción pasa si el objeto simulado se ha invocado en algún momento, a diferencia de assert_called_with() y assert_called_once_with(), con los que sólo pasa la aserción si la llamada es la más reciente, y en el caso de assert_called_once_with() también debe ser la única llamada realizada.

>>> mock = Mock(return_value=None)
>>> mock(1, 2, arg='thing')
>>> mock('some', 'thing', 'else')
>>> mock.assert_any_call(1, 2, arg='thing')

assert_has_calls(calls, any_order=False)

Aserta si el objeto simulado se ha invocado con las llamadas especificadas. La lista mock_calls se compara con la lista de llamadas.

Si any_order es falso entonces las llamadas deben ser secuenciales. No puede haber llamadas adicionales antes o después de las llamadas especificadas.

Si any_order es verdadero, las llamadas pueden estar en cualquier orden, pero deben aparecer todas en mock_calls.

>>> mock = Mock(return_value=None)
>>> mock(1)
>>> mock(2)
>>> mock(3)
>>> mock(4)
>>> calls = [call(2), call(3)]
>>> mock.assert_has_calls(calls)
>>> calls = [call(4), call(2), call(3)]
>>> mock.assert_has_calls(calls, any_order=True)

assert_not_called()

Aserta si el objeto simulado nunca fue invocado.

>>> m = Mock()
>>> m.hello.assert_not_called()
>>> obj = m.hello()
>>> m.hello.assert_not_called()
Traceback (most recent call last):
  ...
AssertionError: Expected 'hello' to not have been called. Called 1 times.

Nuevo en la versión 3.5.

reset_mock(*, return_value=False, side_effect=False)

El método reset_mock restablece todos los atributos de llamada en un objeto simulado:

>>> mock = Mock(return_value=None)
>>> mock('hello')
>>> mock.called
True
>>> mock.reset_mock()
>>> mock.called
False

Distinto en la versión 3.6: Se añadieron dos argumentos por palabra clave a la función reset_mock.

Esto puede ser útil cuando se quiere hacer una serie de aserciones que reutilizan el mismo objeto. Ten en cuenta que por defecto reset_mock() no borra el valor de retorno, side_effect, ni cualquier atributo hijo que hayas establecido mediante asignación normal. En caso de que quieras restablecer return_value o side_effect, debes pasar el parámetro correspondiente como True. Los objetos simulados hijos y el objeto simulado que conforma el valor de retorno (si los hay) se restablecen también.

Nota

return_value y side_effect son argumentos por palabra clave exclusivamente.

mock_add_spec(spec, spec_set=False)

Agrega una especificación a un objeto simulado. spec puede ser un objeto o una lista de cadenas de caracteres. Sólo los atributos presentes en spec pueden ser obtenidos desde el objeto simulado.

Si spec_set es verdadero, solo los atributos de la especificación pueden ser establecidos.

attach_mock(mock, attribute)

Adjunta otro objeto simulado como un atributo de la instancia actual, substituyendo su nombre y su padre. Las llamadas al objeto simulado adjuntado se registrarán en los atributos method_calls y mock_calls del padre.

configure_mock(**kwargs)

Establece los atributos del objeto simulado por medio de argumentos por palabra clave.

Los atributos, los valores de retorno y los efectos de colaterales se pueden configurar en los objetos simulados hijos usando la notación de punto estándar y desempaquetando un diccionario en la llamada al método:

>>> mock = Mock()
>>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError}
>>> mock.configure_mock(**attrs)
>>> mock.method()
3
>>> mock.other()
Traceback (most recent call last):
  ...
KeyError

Lo mismo se puede lograr en la llamada al constructor de los objetos simulados:

>>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError}
>>> mock = Mock(some_attribute='eggs', **attrs)
>>> mock.some_attribute
'eggs'
>>> mock.method()
3
>>> mock.other()
Traceback (most recent call last):
  ...
KeyError

configure_mock() existe con el fin de facilitar la configuración después de que el objeto simulado haya sido creado.

__dir__()

Los objetos Mock limitan los resultados de dir(some_mock) a resultados útiles. Para los objetos simulados con una especificación (spec), esto incluye todos los atributos permitidos para el mismo.

Consultar FILTER_DIR para conocer que hace este filtrado y la forma de desactivarlo.

_get_child_mock(**kw)

Crea los objetos simulados hijos para los atributos y el valor de retorno. Por defecto los objetos simulados hijos serán del mismo tipo que el padre. Las subclases de Mock pueden redefinir este método para personalizar la forma en la que se construye el objeto simulado hijo.

Para objetos simulados no invocables la variante invocable será utilizada (en lugar de cualquier subclase personalizada).

called

Un booleano que representa si el objeto simulado ha sido invocado o no:

>>> mock = Mock(return_value=None)
>>> mock.called
False
>>> mock()
>>> mock.called
True

call_count

Un entero que le indica cuántas veces el objeto simulado ha sido invocado:

>>> mock = Mock(return_value=None)
>>> mock.call_count
0
>>> mock()
>>> mock()
>>> mock.call_count
2

return_value

Establece este atributo para configurar el valor a retornar cuando se llama al objeto simulado:

>>> mock = Mock()
>>> mock.return_value = 'fish'
>>> mock()
'fish'

El valor de retorno por defecto es otro objeto simulado y se puede configurar de forma habitual:

>>> mock = Mock()
>>> mock.return_value.attribute = sentinel.Attribute
>>> mock.return_value()
<Mock name='mock()()' id='...'>
>>> mock.return_value.assert_called_with()

return_value también se puede establecer directamente en el constructor:

>>> mock = Mock(return_value=3)
>>> mock.return_value
3
>>> mock()
3

side_effect

Este atributo puede ser una función a ser llamada cuando se llame al objeto simulado, un iterable o una excepción (clase o instancia) para ser lanzada.

Si pasas una función, será llamada con los mismos argumentos que el objeto simulado y, a menos que la función retorne el singleton DEFAULT, la llamada al objeto simulado retornará lo mismo que retorna la función. En cambio, si la función retorna DEFAULT, entonces el objeto simulado retornará su valor normal (el del atributo return_value).

Si pasas un iterable, se utiliza para obtener un iterador a partir del mismo que debe producir un valor en cada llamada. Este valor puede ser una instancia de la excepción a ser lanzada o un valor a retornar al llamar al objeto simulado (el manejo de DEFAULT es igual que en el caso en el que se pasa una función).

Un ejemplo de un objeto simulado que genera una excepción (para probar el manejo de excepciones de una API):

>>> mock = Mock()
>>> mock.side_effect = Exception('Boom!')
>>> mock()
Traceback (most recent call last):
  ...
Exception: Boom!

Usando side_effect para retornar una secuencia de valores:

>>> mock = Mock()
>>> mock.side_effect = [3, 2, 1]
>>> mock(), mock(), mock()
(3, 2, 1)

Usando un objeto invocable:

>>> mock = Mock(return_value=3)
>>> def side_effect(*args, **kwargs):
...     return DEFAULT
...
>>> mock.side_effect = side_effect
>>> mock()
3

side_effect se puede establecer en el constructor. Aquí hay un ejemplo que suma uno al valor del objeto simulado invocado y lo retorna:

>>> side_effect = lambda value: value + 1
>>> mock = Mock(side_effect=side_effect)
>>> mock(3)
4
>>> mock(-8)
-7

Establecer side_effect en None lo desactiva:

>>> m = Mock(side_effect=KeyError, return_value=3)
>>> m()
Traceback (most recent call last):
 ...
KeyError
>>> m.side_effect = None
>>> m()
3

call_args

Este atributo es None (si el objeto simulado no ha sido invocado) o los argumentos con los que se llamó por última vez. En este último caso, será una tupla con dos elementos: el primer miembro, que también es accesible a través de la propiedad args, son los argumentos posicionales con los que el objeto simulado se llamó (o una tupla vacía si no se pasó ninguno) y el segundo miembro, que también es accesible mediante la propiedad kwargs, son los argumento por palabra clave pasados (o un diccionario vacío si no se pasó ninguno).

>>> mock = Mock(return_value=None)
>>> print(mock.call_args)
None
>>> mock()
>>> mock.call_args
call()
>>> mock.call_args == ()
True
>>> mock(3, 4)
>>> mock.call_args
call(3, 4)
>>> mock.call_args == ((3, 4),)
True
>>> mock.call_args.args
(3, 4)
>>> mock.call_args.kwargs
{}
>>> mock(3, 4, 5, key='fish', next='w00t!')
>>> mock.call_args
call(3, 4, 5, key='fish', next='w00t!')
>>> mock.call_args.args
(3, 4, 5)
>>> mock.call_args.kwargs
{'key': 'fish', 'next': 'w00t!'}

El atributo call_args, junto con los miembros de las listas call_args_list, method_calls y mock_calls son objetos call. Estos objetos son tuplas, con la finalidad de que puedan ser desempaquetadas para acceder a los argumentos individuales y hacer aserciones más complejas. Consultar objetos call como tuplas para más información.

Distinto en la versión 3.8: Added args and kwargs properties.

call_args_list

Este argumento es una lista de todas las llamadas consecutivas realizadas al objeto simulado (por lo que la longitud de la lista es el número de veces que se ha invocado). Previamente a que se hayan realizado llamadas es una lista vacía. El objeto call se puede utilizar para construir convenientemente las listas de llamadas a comparar con call_args_list.

>>> mock = Mock(return_value=None)
>>> mock()
>>> mock(3, 4)
>>> mock(key='fish', next='w00t!')
>>> mock.call_args_list
[call(), call(3, 4), call(key='fish', next='w00t!')]
>>> expected = [(), ((3, 4),), ({'key': 'fish', 'next': 'w00t!'},)]
>>> mock.call_args_list == expected
True

Los miembros de call_args_list son objetos call. Estos pueden ser desempaquetados como tuplas para acceder a los argumentos individuales. Consultar objetos call como tuplas para más información.

method_calls

Igual que realizan un seguimiento de las llamadas hechas a sí mismos, los objetos simulados también realizan un seguimiento a sus métodos y atributos, así como de las llamadas hechas a los mismos:

>>> mock = Mock()
>>> mock.method()
<Mock name='mock.method()' id='...'>
>>> mock.property.method.attribute()
<Mock name='mock.property.method.attribute()' id='...'>
>>> mock.method_calls
[call.method(), call.property.method.attribute()]

Los miembros de method_calls son objetos call. Estos pueden ser desempaquetados como tuplas para acceder a los atributos individuales. Consultar objetos call como tuplas para más información.

mock_calls

mock_calls registra todas las llamadas al objeto simulado, sus métodos, métodos mágicos y objetos simulados del valor de retorno.

>>> mock = MagicMock()
>>> result = mock(1, 2, 3)
>>> mock.first(a=3)
<MagicMock name='mock.first()' id='...'>
>>> mock.second()
<MagicMock name='mock.second()' id='...'>
>>> int(mock)
1
>>> result(1)
<MagicMock name='mock()()' id='...'>
>>> expected = [call(1, 2, 3), call.first(a=3), call.second(),
... call.__int__(), call()(1)]
>>> mock.mock_calls == expected
True

Los miembros de mock_calls son objetos call. Estos pueden ser desempaquetados como tuplas para acceder a los argumentos individuales. Consultar objetos call como tuplas para más información.

Nota

La forma como se registra el atributo mock_calls implica que cuando se realizan llamadas anidadas, los parámetros de las llamadas previas no se registran, por lo que siempre resultan iguales al comparar:

>>> mock = MagicMock()
>>> mock.top(a=3).bottom()
<MagicMock name='mock.top().bottom()' id='...'>
>>> mock.mock_calls
[call.top(a=3), call.top().bottom()]
>>> mock.mock_calls[-1] == call.top(a=-1).bottom()
True

__class__

Normalmente, el atributo de un objeto __class__ retornará su tipo. Para un objeto simulado con un spec, __class__ retorna la clase especificada en su lugar. Esto permite a los objetos simulados pasar los test de isinstance() para el objeto que están reemplazando / enmascarando:

>>> mock = Mock(spec=3)
>>> isinstance(mock, int)
True

El atributo __class__ es asignable, esto permite al objeto simulado pasar una verificación de isinstance() sin verse forzado a utilizar una especificación:

>>> mock = Mock()
>>> mock.__class__ = dict
>>> isinstance(mock, dict)
True

class unittest.mock.NonCallableMock(spec=None, wraps=None, name=None, spec_set=None, **kwargs)

Una versión no invocable de Mock. Los parámetros del constructor tienen el mismo significado que en Mock, con la excepción de return_value y side_effect que no tienen sentido en un objeto simulado no invocable.

Los objetos simulados que usan una clase o una instancia como spec o spec_set son capaces de pasar los test de isinstance():

>>> mock = Mock(spec=SomeClass)
>>> isinstance(mock, SomeClass)
True
>>> mock = Mock(spec_set=SomeClass())
>>> isinstance(mock, SomeClass)
True

Las clases Mock tienen soporte para simular los métodos mágicos. Consultar la sección dedicada a los métodos mágicos para ver los detalles.

Las clases simuladas y los decoradores patch() aceptan todas argumentos por palabra clave arbitrarios para la configuración. En los decoradores patch() los argumentos por palabra clave se pasan al constructor del objeto simulado creado. Estos argumentos se usan para configurar los atributos del propio objeto simulado:

>>> m = MagicMock(attribute=3, other='fish')
>>> m.attribute
3
>>> m.other
'fish'

Tanto el valor de retorno como el efecto colateral del objeto simulado pueden ser establecidos de la misma manera, mediante notación de punto. En cambio, si se quieren establecer mediante el constructor, dado que no se puede utilizar notación de punto directamente en una llamada, se tiene que crear un diccionario y desempaquetarlo usando **:

>>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError}
>>> mock = Mock(some_attribute='eggs', **attrs)
>>> mock.some_attribute
'eggs'
>>> mock.method()
3
>>> mock.other()
Traceback (most recent call last):
  ...
KeyError

Un objeto simulado invocable que fue creado con un spec (o un spec_set) introspeccionará la firma del objeto de la especificación en el momento de emparejar las llamadas al objeto simulado. Esto le permite hacer coincidir sus argumentos con los argumentos de la llamada real, independientemente de si se pasaron por posición o por nombre:

>>> def f(a, b, c): pass
...
>>> mock = Mock(spec=f)
>>> mock(1, 2, c=3)
<Mock name='mock()' id='140161580456576'>
>>> mock.assert_called_with(1, 2, 3)
>>> mock.assert_called_with(a=1, b=2, c=3)

Esto se aplica a assert_called_with(), assert_called_once_with(), assert_has_calls() y assert_any_call(). Cuando se hace uso de Autoespecificación, también se aplicará a las llamadas a los métodos del objeto simulado.

Distinto en la versión 3.4: Se añadió introspección de firma en objetos simulados especificados y autoespecificados.

class unittest.mock.PropertyMock(*args, **kwargs)

Un objeto simulado destinado a ser utilizado en una clase como una propiedad, u otro descriptor. La clase PropertyMock proporciona los métodos __get__() y __set__(), por lo que puedes especificar un valor de retorno para cuando su valor es requerido.

La obtención de una instancia PropertyMock desde un objeto ocasiona una llamada al objeto simulado, sin argumentos. Establecer su valor también llama al objeto simulado, con el valor a establecer como argumento.

>>> class Foo:
...     @property
...     def foo(self):
...         return 'something'
...     @foo.setter
...     def foo(self, value):
...         pass
...
>>> with patch('__main__.Foo.foo', new_callable=PropertyMock) as mock_foo:
...     mock_foo.return_value = 'mockity-mock'
...     this_foo = Foo()
...     print(this_foo.foo)
...     this_foo.foo = 6
...
mockity-mock
>>> mock_foo.mock_calls
[call(), call(6)]

Debido a la forma en que se almacenan los atributos simulados, no es posible conectar directamente un PropertyMock a un objeto simulado. En su lugar se puede conectar al tipo (type) del objeto simulado:

>>> m = MagicMock()
>>> p = PropertyMock(return_value=3)
>>> type(m).foo = p
>>> m.foo
3
>>> p.assert_called_once_with()

class unittest.mock.AsyncMock(spec=None, side_effect=None, return_value=DEFAULT, wraps=None, name=None, spec_set=None, unsafe=False, **kwargs)

An asynchronous version of MagicMock. The AsyncMock object will behave so the object is recognized as an async function, and the result of a call is an awaitable.

>>> mock = AsyncMock()
>>> asyncio.iscoroutinefunction(mock)
True
>>> inspect.isawaitable(mock())
True

El resultado de mock() es una función asíncrona que proporcionará el resultado de side_effect o de return_value después de haber sido aguardada:

si side_effect es una función, la función asíncrona retornará el resultado de esa función,

si side_effect es una excepción, la función asíncrona lanzará la excepción,

si side_effect es un iterable, la función asíncrona retornará el siguiente valor del iterable, sin embargo, si se agota la secuencia de resultados, se lanza una excepción StopAsyncIteration inmediatamente,

si side_effect no está definido, la función asíncrona retornará el valor definido por return_value, por lo tanto, la función asíncrona retorna un nuevo objeto AsyncMock por defecto.

Establecer el argumento spec de un objeto Mock o MagicMock en una función asíncrona resultará en que un objeto corrutina será retornado después de la llamada al objeto.

>>> async def async_func(): pass
...
>>> mock = MagicMock(async_func)
>>> mock
<MagicMock spec='function' id='...'>
>>> mock()
<coroutine object AsyncMockMixin._mock_call at ...>

Establecer el argumento spec de un objeto Mock, MagicMock o AsyncMock en una clase que tiene simultáneamente funciones asíncronas y síncronas hará que se detecten automáticamente las funciones sincrónicas y las establecerá como MagicMock (si el objeto simulado padre es AsyncMock o MagicMock) o Mock (si el objeto simulado padre es Mock) . Todas las funciones asíncronas serán AsyncMock.

>>> class ExampleClass:
...     def sync_foo():
...         pass
...     async def async_foo():
...         pass
...
>>> a_mock = AsyncMock(ExampleClass)
>>> a_mock.sync_foo
<MagicMock name='mock.sync_foo' id='...'>
>>> a_mock.async_foo
<AsyncMock name='mock.async_foo' id='...'>
>>> mock = Mock(ExampleClass)
>>> mock.sync_foo
<Mock name='mock.sync_foo' id='...'>
>>> mock.async_foo
<AsyncMock name='mock.async_foo' id='...'>

Nuevo en la versión 3.8.

assert_awaited()

Aserta si el objeto simulado fue aguardado al menos una vez. Ten en cuenta que, independientemente del objeto que ha sido invocado, la palabra clave await debe ser utilizada:

>>> mock = AsyncMock()
>>> async def main(coroutine_mock):
...     await coroutine_mock
...
>>> coroutine_mock = mock()
>>> mock.called
True
>>> mock.assert_awaited()
Traceback (most recent call last):
...
AssertionError: Expected mock to have been awaited.
>>> asyncio.run(main(coroutine_mock))
>>> mock.assert_awaited()

assert_awaited_once()

Aserta si el objeto simulado fue aguardado exactamente una vez.

>>> mock = AsyncMock()
>>> async def main():
...     await mock()
...
>>> asyncio.run(main())
>>> mock.assert_awaited_once()
>>> asyncio.run(main())
>>> mock.method.assert_awaited_once()
Traceback (most recent call last):
...
AssertionError: Expected mock to have been awaited once. Awaited 2 times.

assert_awaited_with(*args, **kwargs)

Aserta si el último aguardo (await) fue con los argumentos especificados.

>>> mock = AsyncMock()
>>> async def main(*args, **kwargs):
...     await mock(*args, **kwargs)
...
>>> asyncio.run(main('foo', bar='bar'))
>>> mock.assert_awaited_with('foo', bar='bar')
>>> mock.assert_awaited_with('other')
Traceback (most recent call last):
...
AssertionError: expected call not found.
Expected: mock('other')
Actual: mock('foo', bar='bar')

assert_awaited_once_with(*args, **kwargs)

Aserta si que el objeto simulado se ha aguardado exactamente una vez y con los argumentos especificados.

>>> mock = AsyncMock()
>>> async def main(*args, **kwargs):
...     await mock(*args, **kwargs)
...
>>> asyncio.run(main('foo', bar='bar'))
>>> mock.assert_awaited_once_with('foo', bar='bar')
>>> asyncio.run(main('foo', bar='bar'))
>>> mock.assert_awaited_once_with('foo', bar='bar')
Traceback (most recent call last):
...
AssertionError: Expected mock to have been awaited once. Awaited 2 times.

assert_any_await(*args, **kwargs)

Aserta si el objeto simulado nunca se ha aguardado con los argumentos especificados.

>>> mock = AsyncMock()
>>> async def main(*args, **kwargs):
...     await mock(*args, **kwargs)
...
>>> asyncio.run(main('foo', bar='bar'))
>>> asyncio.run(main('hello'))
>>> mock.assert_any_await('foo', bar='bar')
>>> mock.assert_any_await('other')
Traceback (most recent call last):
...
AssertionError: mock('other') await not found

assert_has_awaits(calls, any_order=False)

Aserta si el objeto simulado ha sido aguardado con las llamadas especificadas. Para comprobar los aguardos (awaits) se utiliza la lista await_args_list.

Si any_order es falso, los aguardos (awaits) deben ser secuenciales. No puede haber llamadas adicionales antes o después de los aguardos especificados.

Si any_order es verdadero, entonces los aguardos (awaits) pueden estar en cualquier orden, pero deben aparecer todos en await_args_list.

>>> mock = AsyncMock()
>>> async def main(*args, **kwargs):
...     await mock(*args, **kwargs)
...
>>> calls = [call("foo"), call("bar")]
>>> mock.assert_has_awaits(calls)
Traceback (most recent call last):
...
AssertionError: Awaits not found.
Expected: [call('foo'), call('bar')]
Actual: []
>>> asyncio.run(main('foo'))
>>> asyncio.run(main('bar'))
>>> mock.assert_has_awaits(calls)

assert_not_awaited()

Aserta si el objeto simulado nunca ha sido aguardado.

>>> mock = AsyncMock()
>>> mock.assert_not_awaited()

reset_mock(*args, **kwargs)

Consultar Mock.reset_mock(). Además, también establece await_count a 0, await_args a None y borra await_args_list.

await_count

Un registro entero de cuántas veces se ha aguardado el objeto simulado.

>>> mock = AsyncMock()
>>> async def main():
...     await mock()
...
>>> asyncio.run(main())
>>> mock.await_count
1
>>> asyncio.run(main())
>>> mock.await_count
2

await_args

Este atributo es None (si el objeto simulado no se ha aguardado) o los argumentos con los que fue aguardado la última vez. Su funcionamiento es idéntico al de Mock.call_args.

>>> mock = AsyncMock()
>>> async def main(*args):
...     await mock(*args)
...
>>> mock.await_args
>>> asyncio.run(main('foo'))
>>> mock.await_args
call('foo')
>>> asyncio.run(main('bar'))
>>> mock.await_args
call('bar')

await_args_list

Es una lista de todas los aguardos (awaits) realizados en el objeto simulado de forma secuencial (por lo que la longitud de la lista es el número de veces que se ha aguardado el objeto). Si no se han realizado aguardos previos, es una lista vacía.

>>> mock = AsyncMock()
>>> async def main(*args):
...     await mock(*args)
...
>>> mock.await_args_list
[]
>>> asyncio.run(main('foo'))
>>> mock.await_args_list
[call('foo')]
>>> asyncio.run(main('bar'))
>>> mock.await_args_list
[call('foo'), call('bar')]

Llamar a los objetos simulados

Los objetos Mock son invocables. La llamada a uno retornará el valor establecido en el atributo return_value. El valor de retorno por defecto es un nuevo objeto Mock, el cual se crea la primera vez que se accede al valor de retorno (ya sea explícitamente o llamando al objeto Mock). Una vez creado, se almacena y el mismo objeto es retornado cada vez que se solicita.

Las llamadas realizadas al objeto serán registradas en los atributos call_args y call_args_list.

Si side_effect se establece, será invocado después de que la llamada haya sido registrada, por lo que la llamada se registra aunque side_effect lance una excepción.

La forma más sencilla de hacer que un objeto simulado lance de una excepción cuando sea invocado es establecer su atributo side_effect como una clase o instancia de excepción:

>>> m = MagicMock(side_effect=IndexError)
>>> m(1, 2, 3)
Traceback (most recent call last):
  ...
IndexError
>>> m.mock_calls
[call(1, 2, 3)]
>>> m.side_effect = KeyError('Bang!')
>>> m('two', 'three', 'four')
Traceback (most recent call last):
  ...
KeyError: 'Bang!'
>>> m.mock_calls
[call(1, 2, 3), call('two', 'three', 'four')]

Si side_effect es una función, la llamada al objeto simulado retornará lo que sea que esta función retorne. La función establecida en side_effect se llama con los mismos argumentos con los que el objeto simulado ha sido invocado. Esto te permite variar el valor de retorno de la llamada dinámicamente, en función de la entrada:

>>> def side_effect(value):
...     return value + 1
...
>>> m = MagicMock(side_effect=side_effect)
>>> m(1)
2
>>> m(2)
3
>>> m.mock_calls
[call(1), call(2)]

Si se desea que el objeto simulado aún retorne el valor por defecto (un nuevo objeto simulado), o cualquier valor de retorno establecido, entonces existen dos maneras de proceder. Se puede retornar tanto el atributo mock.return_value como DEFAULT desde side_effect:

>>> m = MagicMock()
>>> def side_effect(*args, **kwargs):
...     return m.return_value
...
>>> m.side_effect = side_effect
>>> m.return_value = 3
>>> m()
3
>>> def side_effect(*args, **kwargs):
...     return DEFAULT
...
>>> m.side_effect = side_effect
>>> m()
3

Para eliminar un side_effect, volviendo al comportamiento predeterminado, establece el atributo side_effect en None:

>>> m = MagicMock(return_value=6)
>>> def side_effect(*args, **kwargs):
...     return 3
...
>>> m.side_effect = side_effect
>>> m()
3
>>> m.side_effect = None
>>> m()
6

El atributo side_effect también puede ser cualquier objeto iterable. En este caso, las llamadas repetidas al objeto simulado irán retornando valores del iterable (hasta que el iterable se agote, momento en el que se lanza una excepción StopIteration):

>>> m = MagicMock(side_effect=[1, 2, 3])
>>> m()
1
>>> m()
2
>>> m()
3
>>> m()
Traceback (most recent call last):
  ...
StopIteration

Si cualquier miembro del iterable es una excepción, se lanzará en lugar de retornarse:

>>> iterable = (33, ValueError, 66)
>>> m = MagicMock(side_effect=iterable)
>>> m()
33
>>> m()
Traceback (most recent call last):
 ...
ValueError
>>> m()
66

Eliminar atributos

Los objetos simulados crean atributos en demanda. Esto les permite hacerse pasar por objetos de cualquier tipo.

Es posible que desees que un objeto simulado retorne False al llamar a hasattr(), o que lance una excepción AttributeError cuando se intenta obtener un atributo. Puedes hacer todo esto proporcionando un objeto adecuado al atributo spec del objeto simulado, pero no siempre es conveniente.

Puedes «bloquear» atributos eliminándolos. Una vez eliminado, el acceso a un atributo lanzará una excepción AttributeError.

>>> mock = MagicMock()
>>> hasattr(mock, 'm')
True
>>> del mock.m
>>> hasattr(mock, 'm')
False
>>> del mock.f
>>> mock.f
Traceback (most recent call last):
    ...
AttributeError: f

Los nombres de los objetos simulados y el atributo name

Dado que «name» es un argumento para el constructor de la clase Mock, si quieres que tu objeto simulado tenga un atributo «name», no puedes simplemente pasarlo al constructor en tiempo de creación. Hay dos alternativas. Una opción es usar el método configure_mock():

>>> mock = MagicMock()
>>> mock.configure_mock(name='my_name')
>>> mock.name
'my_name'

Una opción más sencilla es simplemente establecer el atributo «name» después de la creación del objeto simulado:

>>> mock = MagicMock()
>>> mock.name = "foo"

Adjuntar objetos simulados como atributos

Cuando se adjunta un objeto simulado como un atributo de otro objeto simulado (o como su valor de retorno) se convierte en un «hijo» del mismo. Las llamadas a los hijos se registran en los atributos method_calls y mock_calls del padre. Esto es útil para configurar objetos simulados hijos para después adjuntarlos al padre, o para adjuntar objetos simulados a un padre que se encargará de registrar todas las llamadas a los hijos, permitiéndote hacer aserciones sobre el orden de las llamadas entre objetos simulados:

>>> parent = MagicMock()
>>> child1 = MagicMock(return_value=None)
>>> child2 = MagicMock(return_value=None)
>>> parent.child1 = child1
>>> parent.child2 = child2
>>> child1(1)
>>> child2(2)
>>> parent.mock_calls
[call.child1(1), call.child2(2)]

La excepción a lo anterior es si el objeto simulado tiene un nombre. Esto te permite evitar el comportamiento de «parentesco» explicado previamente, si por alguna razón no deseas que suceda.

>>> mock = MagicMock()
>>> not_a_child = MagicMock(name='not-a-child')
>>> mock.attribute = not_a_child
>>> mock.attribute()
<MagicMock name='not-a-child()' id='...'>
>>> mock.mock_calls
[]

Los objetos simulados creados automáticamente por la función patch() también reciben nombres automáticamente. Para adjuntar un objeto simulado con nombre a un padre debes utilizar el método attach_mock():

>>> thing1 = object()
>>> thing2 = object()
>>> parent = MagicMock()
>>> with patch('__main__.thing1', return_value=None) as child1:
...     with patch('__main__.thing2', return_value=None) as child2:
...         parent.attach_mock(child1, 'child1')
...         parent.attach_mock(child2, 'child2')
...         child1('one')
...         child2('two')
...
>>> parent.mock_calls
[call.child1('one'), call.child2('two')]

1

Las únicas excepciones son los métodos y atributos mágicos (aquellos que tienen doble subrayado al principio y al final). Mock no los crea automáticamente, sino que lanza una excepción AttributeError. Esto se debe a que el intérprete a menudo solicitará implícitamente estos métodos y terminaría muy confundido si obtiene un nuevo objeto Mock cuando espera un método mágico. Si necesitas soporte para métodos mágicos, consulta métodos mágicos.

Parcheadores

Los decoradores patch se utilizan para parchear los objetos sólo dentro del ámbito de la función que decoran. Se encargan automáticamente de desparchear una vez terminada la prueba, incluso si se lanzan excepciones. Todas estas funciones también se pueden utilizar con declaraciones o como decoradores de clase.

patch

Nota

The key is to do the patching in the right namespace. See the section where to patch.

unittest.mock.patch(target, new=DEFAULT, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs)

patch() actúa como decorador de función, decorador de clase o como gestor de contexto. Ya sea en el interior del cuerpo de una función o dentro de una declaración with, target es parcheado con un objeto new. Cuando la función / declaración with termina su ejecución el parche se deshace automáticamente.

Si se omite new, entonces el objetivo se reemplaza por un objeto AsyncMock si el objeto parcheado es una función asíncrona, o con un objeto MagicMock en caso contrario. Si se utiliza patch() como decorador y se omite new, el objeto simulado creado se pasa como un argumento adicional a la función decorada. Si se utiliza patch() como un gestor de contexto, el objeto simulado creado es retornado por el gestor de contexto.

target debe ser una cadena de la forma 'paquete.modulo.NombreDeLaClase'. target es importado y el objeto especificado reemplazado por el objeto new, por lo que target debe ser importable desde el entorno desde el cual estás llamando a patch(). Hay que tener presente que target es importado cuando se ejecuta la función decorada, no en tiempo de decoración.

Los argumentos spec y spec_set se pasan a MagicMock si patch está creando automáticamente uno para ti.

Además, puedes pasar spec=True o spec_set=True, lo que causa que patch pase el objeto que está siendo simulado como el objeto spec/spec_set.

new_callable te permite especificar una clase diferente, o un objeto invocable, que será invocada para crear el objeto new. Por defecto se utiliza AsyncMock para las funciones asíncronas y MagicMock para el resto.

Una variante más poderosa de spec es autospec. Si estableces autospec=True el objeto simulado se creará con una especificación del objeto que está siendo reemplazado. Todos los atributos del objeto simulado también tendrán la especificación del atributo correspondiente del objeto que está siendo reemplazado. Los argumentos de los métodos y funciones simulados son comprobados y se lanzará una excepción TypeError si se les llama con la firma incorrecta. Para los objetos simulados que sustituyen a una clase, su valor de retorno (la “instancia”) tendrá la misma especificación que la clase. Consultar la función create_autospec() y Autoespecificación para más detalles.

En lugar de autospec=True, puedes pasar autospec=some_object para utilizar un objeto arbitrario como especificación en lugar del objeto reemplazado.

Por defecto, patch() fallará al intentar reemplazar atributos que no existen. Si pasas create=True y no existe el atributo, patch crea el atributo cuando la función se llama y lo elimina de nuevo en cuanto termina de ejecutarse . Esto es útil para implementar pruebas para atributos que tu código de producción crea en tiempo de ejecución. Está desactivado por defecto, ya que puede ser peligroso. ¡Al activarlo se pueden implementar pruebas que validen APIs que en realidad no existen!

Nota

Distinto en la versión 3.5: Si estás parcheando objetos incorporados (builtins) en un módulo, no es necesario pasar create=True, ya que en este caso se agrega de forma predeterminada.

Patch puede ser usado como un decorador de la clase TestCase. Funciona decorando cada uno de los métodos de prueba presentes en la clase. Esto reduce el código repetitivo cuando tus métodos de prueba comparten un conjunto de parcheo común. patch() encuentra las pruebas mediante la búsqueda de métodos cuyos nombres comienzan con patch.TEST_PREFIX. Por defecto es 'test', que coincide con la forma en que unittest busca las pruebas. Se puede especificar un prefijo alternativo estableciendo un nuevo valor para el atributo patch.TEST_PREFIX.

Patch puede ser usado como un gestor de contexto, con la declaración with. En este caso el parcheo se aplica al bloque sangrado inmediatamente después de la declaración with. Si utilizas «as», el objeto parcheado será enlazado al nombre especificado después de «as»; muy útil si patch() está creando un objeto simulado automáticamente.

patch() takes arbitrary keyword arguments. These will be passed to AsyncMock if the patched object is asynchronous, to MagicMock otherwise or to new_callable if specified.

patch.dict(...), patch.multiple(...) y patch.object(...) están disponibles para casos de uso alternativos.

patch() como decorador de función, crea el objeto simulado por ti y lo pasa a la función decorada:

>>> @patch('__main__.SomeClass')
... def function(normal_argument, mock_class):
...     print(mock_class is SomeClass)
...
>>> function(None)
True

Parchear una clase sustituye a la clase por una instancia de MagicMock. Si la clase se instancia en el código bajo prueba, el atributo return_value del objeto simulado será el utilizado.

Si la clase se instancia en múltiples ocasiones, puedes utilizar el atributo side_effect para retornar un nuevo objeto simulado cada vez. O también puedes establecer return_value para que sea lo que tu quieras.

Para configurar valores de retorno de métodos en instancias de la clase parcheada debes hacer uso del atributo return_value. Por ejemplo:

>>> class Class:
...     def method(self):
...         pass
...
>>> with patch('__main__.Class') as MockClass:
...     instance = MockClass.return_value
...     instance.method.return_value = 'foo'
...     assert Class() is instance
...     assert Class().method() == 'foo'
...

Si utilizas spec o spec_set y patch() está reemplazando una clase, el valor de retorno del objeto simulado creado tendrá las mismas especificaciones:

>>> Original = Class
>>> patcher = patch('__main__.Class', spec=True)
>>> MockClass = patcher.start()
>>> instance = MockClass()
>>> assert isinstance(instance, Original)
>>> patcher.stop()

El argumento new_callable es útil cuando deseas utilizar una clase por defecto alternativa a MagicMock para el objeto simulado creado. Por ejemplo, si quieres que se use una clase NonCallableMock por defecto:

>>> thing = object()
>>> with patch('__main__.thing', new_callable=NonCallableMock) as mock_thing:
...     assert thing is mock_thing
...     thing()
...
Traceback (most recent call last):
  ...
TypeError: 'NonCallableMock' object is not callable

Otro caso de uso podría ser la sustitución de un objeto por una instancia de io.StringIO:

>>> from io import StringIO
>>> def foo():
...     print('Something')
...
>>> @patch('sys.stdout', new_callable=StringIO)
... def test(mock_stdout):
...     foo()
...     assert mock_stdout.getvalue() == 'Something\n'
...
>>> test()

Cuando patch() crea un objeto simulado para ti, a menudo lo primero que tienes que hacer es configurar el objeto simulado recién creado. Parte de la configuración se puede hacer en la propia llamada a patch. Cualquier palabra clave arbitraria que pases a la llamada será utilizada para establecer los atributos del objeto simulado creado:

>>> patcher = patch('__main__.thing', first='one', second='two')
>>> mock_thing = patcher.start()
>>> mock_thing.first
'one'
>>> mock_thing.second
'two'

Los atributos de los objetos simulados hijos, como return_value y side_effect, también puede ser configurados en la llamada, dado que los objetos simulados hijos son atributos en si mismos del objeto simulado padre creado. Eso si, estos no son sintácticamente válidos para ser pasados directamente como argumentos por palabras clave a la función patch, pero un diccionario con ellos como claves si que puede ser expandido en una llama a patch() usando **:

>>> config = {'method.return_value': 3, 'other.side_effect': KeyError}
>>> patcher = patch('__main__.thing', **config)
>>> mock_thing = patcher.start()
>>> mock_thing.method()
3
>>> mock_thing.other()
Traceback (most recent call last):
  ...
KeyError

Por defecto, el intento de parchear una función en un módulo (o un método o atributo en una clase) que no existe fallará lanzando una excepción AttributeError:

>>> @patch('sys.non_existing_attribute', 42)
... def test():
...     assert sys.non_existing_attribute == 42
...
>>> test()
Traceback (most recent call last):
  ...
AttributeError: <module 'sys' (built-in)> does not have the attribute 'non_existing_attribute'

pero añadir create=True en la llamada a patch() hará que el ejemplo previo funcione como se esperaba:

>>> @patch('sys.non_existing_attribute', 42, create=True)
... def test(mock_stdout):
...     assert sys.non_existing_attribute == 42
...
>>> test()

Distinto en la versión 3.8: patch() ahora retorna una instancia de AsyncMock si el objetivo es una función asíncrona.

patch.object

patch.object(target, attribute, new=DEFAULT, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs)

parchea el miembro attribute invocado de un objeto target con un objeto simulado.

patch.object() se puede utilizar como un decorador, decorador de clase o un gestor de contexto. Los argumentos new, spec, create, spec_set, autospec y new_callable tienen el mismo significado que en la función patch(). Al igual que patch(), patch.object() toma argumentos por palabras clave arbitrarios para la configuración del objeto simulado que crea.

Cuando se utiliza como un decorador de clase patch.object() se rige por patch.TEST_PREFIX a la hora de elegir los métodos a envolver.

Puedes llamar a patch.object() con tres argumentos o con dos argumentos. La forma de tres argumento toma el objeto a parchear, el nombre del atributo y el objeto con el que reemplazar el atributo.

Al llamar usando la variante de dos argumento se omite el objeto de sustitución, por lo tanto se crea un objeto simulado automáticamente y se pasa como argumento adicional a la función decorada:

>>> @patch.object(SomeClass, 'class_method')
... def test(mock_method):
...     SomeClass.class_method(3)
...     mock_method.assert_called_with(3)
...
>>> test()

spec, create y el resto de argumentos de patch.object() tienen el mismo significado que en la función patch().

patch.dict

patch.dict(in_dict, values=(), clear=False, **kwargs)

Parchea un diccionario o un objeto similar a un diccionario y posteriormente lo restaura a su estado original una vez terminada la prueba.

in_dict puede ser un diccionario o un contenedor similar a uno. Si se trata de un objeto similar a un diccionario, debe soportar como mínimo el establecimiento, la obtención y la eliminación de elementos, además de permitir la iteración sobre las claves.

in_dict también puede ser una cadena que especifique el nombre del diccionario a parchear, el nombre es usado para obtener el diccionario mediante importación.

values puede ser otro diccionario con valores para ser añadidos al diccionario. values también puede ser un iterable de parejas (clave, valor).

Si clear es verdadero, el contenido del diccionario se borrará antes de establecer los nuevos valores.

La función patch.dict() también puede ser invocada con argumentos por palabra clave arbitrarios para establecer los valores en el diccionario.

Distinto en la versión 3.8: La función patch.dict() ahora retorna el diccionario parcheado cuando se utiliza como gestor de contexto.

patch.dict() se puede utilizar como gestor de contexto, decorador o decorador de clase:

>>> foo = {}
>>> @patch.dict(foo, {'newkey': 'newvalue'})
... def test():
...     assert foo == {'newkey': 'newvalue'}
>>> test()
>>> assert foo == {}

Cuando se utiliza patch.dict() como decorador de clase, se rige por patch.TEST_PREFIX (por defecto 'test') a la hora de elegir qué métodos envolver:

>>> import os
>>> import unittest
>>> from unittest.mock import patch
>>> @patch.dict('os.environ', {'newkey': 'newvalue'})
... class TestSample(unittest.TestCase):
...     def test_sample(self):
...         self.assertEqual(os.environ['newkey'], 'newvalue')

Si deseas utilizar un prefijo diferente para tu prueba, puede informar a los parcheadores del nuevo prefijo a usar estableciendo patch.TEST_PREFIX. Para más detalles sobre cómo cambiar el valor del atributo consultar TEST_PREFIX.

patch.dict() puede utilizarse para agregar miembros a un diccionario, o simplemente para dejar que una prueba modifique un diccionario y asegurarte de que el diccionario será restablecido cuando finalice la misma.

>>> foo = {}
>>> with patch.dict(foo, {'newkey': 'newvalue'}) as patched_foo:
...     assert foo == {'newkey': 'newvalue'}
...     assert patched_foo == {'newkey': 'newvalue'}
...     # You can add, update or delete keys of foo (or patched_foo, it's the same dict)
...     patched_foo['spam'] = 'eggs'
...
>>> assert foo == {}
>>> assert patched_foo == {}

>>> import os
>>> with patch.dict('os.environ', {'newkey': 'newvalue'}):
...     print(os.environ['newkey'])
...
newvalue
>>> assert 'newkey' not in os.environ

Se pueden utilizar argumentos por palabra clave en la llamada a patch.dict() para establecer valores en el diccionario:

>>> mymodule = MagicMock()
>>> mymodule.function.return_value = 'fish'
>>> with patch.dict('sys.modules', mymodule=mymodule):
...     import mymodule
...     mymodule.function('some', 'args')
...
'fish'

patch.dict() se puede utilizar con objetos similares a un diccionario, que no son realmente diccionarios. Estos objetos como mínimo deben permitir obtener, establecer y borrar elementos, además de soportar la iteración o la prueba de pertenencia. Dichas funcionalidades se corresponden a los métodos mágicos __getitem__(), __setitem__(), __delitem__() e __iter__() o __contains__().

>>> class Container:
...     def __init__(self):
...         self.values = {}
...     def __getitem__(self, name):
...         return self.values[name]
...     def __setitem__(self, name, value):
...         self.values[name] = value
...     def __delitem__(self, name):
...         del self.values[name]
...     def __iter__(self):
...         return iter(self.values)
...
>>> thing = Container()
>>> thing['one'] = 1
>>> with patch.dict(thing, one=2, two=3):
...     assert thing['one'] == 2
...     assert thing['two'] == 3
...
>>> assert thing['one'] == 1
>>> assert list(thing) == ['one']

patch.multiple

patch.multiple(target, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs)

Realiza múltiples parches en una sola llamada. Se toma el objeto a ser parcheado (ya sea como un objeto o una cadena de caracteres con el nombre del mismo para obtener el objeto mediante importación) y los argumentos por palabras clave para los parches:

with patch.multiple(settings, FIRST_PATCH='one', SECOND_PATCH='two'):
    ...

Usa DEFAULT como valor si deseas que la función patch.multiple() cree objetos simulados automáticamente por ti. En este caso, los objetos simulados creados son pasados ​​a la función decorada mediante palabra clave y se retorna un diccionario cuando patch.multiple() se utiliza como gestor de contexto.

La función patch.multiple() se puede utilizar como un decorador, decorador de clase o como gestor de contexto. La argumentos spec, spec_set, create, autospec y new_callable tienen el mismo significado que en la función patch(). Estos argumentos se aplicarán a todos los parches realizados por patch.multiple().

Cuando se utiliza como decorador de clase, patch.multiple() se rige por patch.TEST_PREFIX a la hora de elegir qué métodos envolver.

Si deseas que patch.multiple() cree objetos simulados automáticamente por ti, puedes utilizar DEFAULT como valor. Si utilizas patch.multiple() como decorador, entonces los objetos simulados creados se pasan a la función decorada por palabra clave:

>>> thing = object()
>>> other = object()

>>> @patch.multiple('__main__', thing=DEFAULT, other=DEFAULT)
... def test_function(thing, other):
...     assert isinstance(thing, MagicMock)
...     assert isinstance(other, MagicMock)
...
>>> test_function()

patch.multiple() se puede anidar junto a otros decoradores patch, pero los argumentos pasados ​​por palabra clave se deben agregar después de cualquier argumento estándar creado por patch():

>>> @patch('sys.exit')
... @patch.multiple('__main__', thing=DEFAULT, other=DEFAULT)
... def test_function(mock_exit, other, thing):
...     assert 'other' in repr(other)
...     assert 'thing' in repr(thing)
...     assert 'exit' in repr(mock_exit)
...
>>> test_function()

Si patch.multiple() se utiliza como un gestor de contexto, el valor retornado por el mismo es un diccionario en el que los objetos simulados creados son almacenados, usando sus nombres como claves:

>>> with patch.multiple('__main__', thing=DEFAULT, other=DEFAULT) as values:
...     assert 'other' in repr(values['other'])
...     assert 'thing' in repr(values['thing'])
...     assert values['thing'] is thing
...     assert values['other'] is other
...

Métodos start y stop de patch

Todos los parcheadores tienen los métodos start() y stop(). Esto facilita parchear en los métodos setUp o cuando deseas hacer múltiples parches sin usar decoradores anidados o declaraciones with.

Para utilizar estos métodos, llama a patch(), patch.object() o patch.dict() como haces normalmente y mantén una referencia al objeto patcher retornado. A continuación, puedes llamar al método start() para aplicar el parche y a stop() para deshacerlo.

Si estás utilizando patch() para crear un objeto simulado automáticamente, este será retornado por la llamada a patcher.start:

>>> patcher = patch('package.module.ClassName')
>>> from package import module
>>> original = module.ClassName
>>> new_mock = patcher.start()
>>> assert module.ClassName is not original
>>> assert module.ClassName is new_mock
>>> patcher.stop()
>>> assert module.ClassName is original
>>> assert module.ClassName is not new_mock

Un uso típico de esto podría ser realizar múltiples parches en el método setUp de un TestCase:

>>> class MyTest(unittest.TestCase):
...     def setUp(self):
...         self.patcher1 = patch('package.module.Class1')
...         self.patcher2 = patch('package.module.Class2')
...         self.MockClass1 = self.patcher1.start()
...         self.MockClass2 = self.patcher2.start()
...
...     def tearDown(self):
...         self.patcher1.stop()
...         self.patcher2.stop()
...
...     def test_something(self):
...         assert package.module.Class1 is self.MockClass1
...         assert package.module.Class2 is self.MockClass2
...
>>> MyTest('test_something').run()

Prudencia

Si se utiliza esta técnica debes asegurarte de que el parcheo está «sin aplicar» llamando a stop. Esto puede ser más complicado de lo que parece, ya que si se produce una excepción en el setUp no se llama a tearDown a continuación. unittest.TestCase.addCleanup() hace que esto sea más fácil:

>>> class MyTest(unittest.TestCase):
...     def setUp(self):
...         patcher = patch('package.module.Class')
...         self.MockClass = patcher.start()
...         self.addCleanup(patcher.stop)
...
...     def test_something(self):
...         assert package.module.Class is self.MockClass
...

Como beneficio adicional, ya no es necesario mantener una referencia al objeto patcher.

También es posible detener todos los parches que han sido iniciados usando patch.stopall().

patch.stopall()

Detiene todos los parches activos. Sólo se detienen parches iniciados con start.

Parchear objetos incorporados (builtins)

Puedes parchear cualquier objeto incorporado dentro de un módulo. El siguiente ejemplo parchea la función incorporada ord():

>>> @patch('__main__.ord')
... def test(mock_ord):
...     mock_ord.return_value = 101
...     print(ord('c'))
...
>>> test()
101

TEST_PREFIX

Todos los parcheadores se puede utilizar como decoradores de clase. Cuando se usan de esta forma, todos los métodos a probar en la clase son envueltos. Los parcheadores reconocen los métodos que comienzan con 'test' como métodos a probar. Esta es la misma forma que la clase unittest.TestLoader usa para encontrar métodos de prueba por defecto.

Cabe la posibilidad de que desees utilizar un prefijo diferente para las pruebas. Puedes informar a los parcheadores del cambio de prefijo estableciendo el atributo patch.TEST_PREFIX:

>>> patch.TEST_PREFIX = 'foo'
>>> value = 3
>>>
>>> @patch('__main__.value', 'not three')
... class Thing:
...     def foo_one(self):
...         print(value)
...     def foo_two(self):
...         print(value)
...
>>>
>>> Thing().foo_one()
not three
>>> Thing().foo_two()
not three
>>> value
3

Anidando decoradores patch

Si deseas aplicar múltiples parches, solo tienes que apilar los decoradores.

Puede apilar múltiples decoradores patch usando el siguiente patrón:

>>> @patch.object(SomeClass, 'class_method')
... @patch.object(SomeClass, 'static_method')
... def test(mock1, mock2):
...     assert SomeClass.static_method is mock1
...     assert SomeClass.class_method is mock2
...     SomeClass.static_method('foo')
...     SomeClass.class_method('bar')
...     return mock1, mock2
...
>>> mock1, mock2 = test()
>>> mock1.assert_called_once_with('foo')
>>> mock2.assert_called_once_with('bar')

Ten en cuenta que los decoradores se aplican desde abajo hacia arriba. Esta es la manera estándar de Python para aplicar decoradores. El orden en el que los objetos simulados generados se pasan a la función de prueba coincide con este orden.

Dónde parchear

patch() funciona cambiando (temporalmente) el objeto al que apunta name con otro. Puede haber muchos nombres apuntando a cualquier objeto individual, por lo que para que el parcheo funcione, debes asegurarte de parchear el nombre utilizado para el objeto por el sistema concreto bajo prueba.

El principio básico es parchear donde un objeto es buscado, que no es necesariamente el mismo lugar donde está definido. Un par de ejemplos ayudarán a aclarar esto.

Imaginemos que tenemos un proyecto, que queremos probar, con la siguiente estructura:

a.py
    -> Defines SomeClass

b.py
    -> from a import SomeClass
    -> some_function instantiates SomeClass

Ahora queremos probar some_function, pero queremos simular SomeClass utilizando patch(). El problema es que cuando importamos el módulo b, lo cual tenemos que hacer obligatoriamente, se importa SomeClass del módulo a. Si utilizamos patch() para simular a.SomeClass, no tendrá ningún efecto en nuestra prueba; el módulo b ya tiene una referencia a la SomeClass real, por lo que parece que nuestro parcheo no tuvo ningún efecto.

La clave es parchear SomeClass donde se utiliza (o donde es buscado). En este caso some_function realmente va a buscar SomeClass en el módulo b, donde lo hemos importado. La aplicación de parches debe ser similar a:

@patch('b.SomeClass')

Sin embargo, ten en cuenta el escenario alternativo donde en el módulo b en lugar de from a import SomeClass se hace import a y some_function usa a.SomeClass. Ambas formas de importación son comunes. En este caso, la clase que queremos parchear está siendo buscada en el módulo, por lo que tenemos que parchear a.SomeClass:

@patch('a.SomeClass')

Parcheando descriptores y objetos proxy

Tanto patch como patch.object parchean descriptores correctamente y los restauran posteriormente: métodos de clase, métodos estáticos y propiedades. Los descriptores deben ser parcheados en la clase y no en una instancia. También funcionan con algunos objetos que actúan como proxy en el acceso a atributos, como el objeto de configuraciones de django (django settings object [http://www.voidspace.org.uk/python/weblog/arch_d7_2010_12_04.shtml#e1198]).

MagicMock y el soporte de métodos mágicos

Simular métodos mágicos

Mock soporta la simulación de los métodos de protocolo de Python, también conocidos como «métodos mágicos». Esto permite a los objetos simulados reemplazar contenedores u otros objetos que implementan protocolos de Python.

Dado que los métodos mágicos se buscan de manera diferente a los métodos normales 2, este soporte ha sido especialmente implementado. Esto significa que sólo es compatible con métodos mágicos específicos. La lista de métodos soportados incluye casi todos los existentes. Si hay alguno que falta y que consideras necesario, por favor háznoslo saber.

Puedes simular métodos mágicos estableciendo el método que te interesa en una función o en una instancia simulada. Si utilizas una función, debe aceptar self como primer argumento 3.

>>> def __str__(self):
...     return 'fooble'
...
>>> mock = Mock()
>>> mock.__str__ = __str__
>>> str(mock)
'fooble'

>>> mock = Mock()
>>> mock.__str__ = Mock()
>>> mock.__str__.return_value = 'fooble'
>>> str(mock)
'fooble'

>>> mock = Mock()
>>> mock.__iter__ = Mock(return_value=iter([]))
>>> list(mock)
[]

Un caso de uso para esto es simular objetos usados ​​como gestores de contexto en una declaración with:

>>> mock = Mock()
>>> mock.__enter__ = Mock(return_value='foo')
>>> mock.__exit__ = Mock(return_value=False)
>>> with mock as m:
...     assert m == 'foo'
...
>>> mock.__enter__.assert_called_with()
>>> mock.__exit__.assert_called_with(None, None, None)

Las llamadas a métodos mágicos no aparecen registradas en method_calls, aunque si se registran en mock_calls.

Nota

Si se utiliza el argumento por palabra clave spec para crear un objeto simulado, intentar después establecer un método mágico que no está en la especificación lanzará una excepción AttributeError.

La lista completa de los métodos mágicos soportados es la siguiente:

__hash__, __sizeof__, __repr__ y __str__

__dir__, __format__ y __subclasses__

__round__, __floor__, __trunc__ y __ceil__

Comparaciones: __lt__, __gt__, __le__, __ge__, __eq__ y __ne__

Métodos de contenedores: __getitem__, __setitem__, __delitem__, __contains__, __len__, __iter__, __reversed__ y __missing__

Administrador de contexto: __enter__, __exit__, __aenter__ y __aexit__

Métodos numéricos unarios: __neg__, __pos__ y __invert__

Los métodos numéricos (incluyendo los métodos estándar y las variantes in-place): __add__, __sub__, __mul__, __matmul__, __div__, __truediv__, __floordiv__, __mod__, __divmod__, __lshift__, __rshift__, __and__, __xor__, __or__, y __pow__

Métodos de conversión numérica: __complex__, __int__, __float__ y __index__

Métodos de descriptores: __get__, __set__ y __delete__

Pickling: __reduce__, __reduce_ex__, __getinitargs__, __getnewargs__, __getstate__ y __setstate__

Representación de rutas del sistema de archivos: __fspath__

Métodos de iteración asíncronos: __aiter__ y __anext__

Distinto en la versión 3.8: Se añadió soporte para os.PathLike.__fspath__().

Distinto en la versión 3.8: Se añadió soporte para __aenter__, __aexit__, __aiter__ y __anext__.

Los siguientes métodos existen pero no están soportados, ya sea porque son usados por el propio objeto simulado, porque no se pueden establecer dinámicamente o porque pueden causar problemas:

__getattr__, __setattr__, __init__ y __new__

__prepare__, __instancecheck__, __subclasscheck__ y __del__

Magic Mock

Hay dos variantes de MagicMock: MagicMock y NonCallableMagicMock.

class unittest.mock.MagicMock(*args, **kw)

MagicMock es una subclase de Mock con implementaciones por defecto de la mayoría de los métodos mágicos. Puedes utilizar MagicMock para crear objetos simulados sin tener que establecer los métodos mágicos por ti mismo.

Los parámetros del constructor tienen el mismo significado que en Mock.

Si utilizas los argumentos spec o spec_set entonces solo los métodos mágicos que existan en la especificación serán creados.

class unittest.mock.NonCallableMagicMock(*args, **kw)

Una versión no invocable de MagicMock.

Los parámetros del constructor tienen el mismo significado que en MagicMock, con la excepción de return_value y side_effect que no tienen significado en un objeto simulado no invocable.

Los métodos mágicos están implementados mediante objetos MagicMock, por lo que puedes configurarlos y utilizarlos de la forma habitual:

>>> mock = MagicMock()
>>> mock[3] = 'fish'
>>> mock.__setitem__.assert_called_with(3, 'fish')
>>> mock.__getitem__.return_value = 'result'
>>> mock[2]
'result'

Por defecto, muchos de los métodos de protocolo están obligados a retornar objetos de un tipo específico. Estos métodos están preconfigurados con un valor de retorno por defecto, de manera que puedan ser utilizados sin tener que hacer nada más, siempre que no estés interesado en el valor de retorno. En todo caso, puedes establecer el valor de retorno de forma manual si deseas cambiar el valor predeterminado.

Métodos y sus valores por defecto:

__lt__: NotImplemented

__gt__: NotImplemented

__le__: NotImplemented

__ge__: NotImplemented

__int__: 1

__contains__: False

__len__: 0

__iter__: iter([])

__exit__: False

__aexit__: False

__complex__: 1j

__float__: 1.0

__bool__: True

__index__: 1

__hash__: hash predeterminado del objeto simulado

__str__: str predeterminado del objeto simulado

__sizeof__: sizeof predeterminado del objeto simulado

Por ejemplo:

>>> mock = MagicMock()
>>> int(mock)
1
>>> len(mock)
0
>>> list(mock)
[]
>>> object() in mock
False

Los dos métodos de igualdad, __eq__() y __ne__(), son especiales. Realizan la comparación de igualdad predeterminada basada en la identidad, utilizando el atributo side_effect, a menos que cambies su valor de retorno para que retorne alguna otra cosa:

>>> MagicMock() == 3
False
>>> MagicMock() != 3
True
>>> mock = MagicMock()
>>> mock.__eq__.return_value = True
>>> mock == 3
True

El valor de retorno de MagicMock.__iter__() puede ser cualquier objeto iterable, no se requiere que sea un iterador:

>>> mock = MagicMock()
>>> mock.__iter__.return_value = ['a', 'b', 'c']
>>> list(mock)
['a', 'b', 'c']
>>> list(mock)
['a', 'b', 'c']

Si el valor de retorno es un iterador, iterar sobre él una vez que se consume, y cualquier iteración posterior, resultará en una lista vacía:

>>> mock.__iter__.return_value = iter(['a', 'b', 'c'])
>>> list(mock)
['a', 'b', 'c']
>>> list(mock)
[]

MagicMock tiene todos los métodos mágicos soportados configurados a excepción de algunos de los más oscuros y obsoletos. De todas formas, puedes configurar estos también si lo deseas.

Los métodos mágicos que son compatibles, pero que no están configurados por defecto en MagicMock son:

__subclasses__

__dir__

__format__

__get__, __set__ y __delete__

__reversed__ y __missing__

__reduce__, __reduce_ex__, __getinitargs__, __getnewargs__, __getstate__ y __setstate__

__getformat__ y __setformat__

2

Los métodos mágicos deben ser buscados en la clase en lugar de en la instancia. Diferentes versiones de Python son inconsistentes sobre la aplicación de esta regla. Los métodos de protocolo soportados deben trabajar con todas las versiones de Python.

3

La función está básicamente conectada a la clase, pero cada instancia Mock se mantiene aislada de las demás.

Ayudantes

sentinel

unittest.mock.sentinel

El objeto sentinel proporciona una manera conveniente de proporcionar objetos únicos para tus pruebas.

Los atributos se crean a demanda, en el instante en el que se accede a ellos por su nombre por primera vez. El acceso al mismo atributo siempre retornará el mismo objeto. Los objetos retornados tienen una reproducción (repr) apropiada para que los mensajes de error de la prueba sean legibles.

Distinto en la versión 3.7: Los atributos sentinel ahora preservan su identidad cuando son copiados o serializados con pickle.

A veces, cuando implementas pruebas, necesitas probar que un determinado objeto se pasa como argumento a otro método, o se retorna. Crear objetos centinela con un nombre para probar esto puede ser una práctica común. sentinel proporciona una manera conveniente de crear y probar la identidad de este tipo de objetos.

En el siguiente ejemplo, parcheamos method para retornar sentinel.some_object:

>>> real = ProductionClass()
>>> real.method = Mock(name="method")
>>> real.method.return_value = sentinel.some_object
>>> result = real.method()
>>> assert result is sentinel.some_object
>>> result
sentinel.some_object

DEFAULT

unittest.mock.DEFAULT

El objeto DEFAULT es un centinela pre-creado (actualmente sentinel.DEFAULT). Puede ser usado por las funciones side_effect para indicar que el valor de retorno normal debe ser utilizado.

call

unittest.mock.call(*args, **kwargs)

call() es un objeto ayudante que puede usarse para hacer aserciones simples, para comparar con call_args, call_args_list, mock_calls y method_calls. call() y también se puede utilizar con assert_has_calls().

>>> m = MagicMock(return_value=None)
>>> m(1, 2, a='foo', b='bar')
>>> m()
>>> m.call_args_list == [call(1, 2, a='foo', b='bar'), call()]
True

call.call_list()

Para un objeto call que representa múltiples llamadas, el método call_list() retorna una lista con todas las llamadas intermedias, así como la llamada final.

call_list es particularmente útil para hacer aserciones sobre «llamadas encadenadas». Una llamada encadenada es varias llamadas en una sola línea de código. Esto resulta en múltiples entradas en el atributo mock_calls de un objeto simulado. Construir manualmente la secuencia de llamadas puede ser tedioso.

call_list() puede construir la secuencia de llamadas desde la misma llamada encadenada:

>>> m = MagicMock()
>>> m(1).method(arg='foo').other('bar')(2.0)
<MagicMock name='mock().method().other()()' id='...'>
>>> kall = call(1).method(arg='foo').other('bar')(2.0)
>>> kall.call_list()
[call(1),
 call().method(arg='foo'),
 call().method().other('bar'),
 call().method().other()(2.0)]
>>> m.mock_calls == kall.call_list()
True

Un objeto call, dependiendo de cómo fuera construido, puede ser una tupla de la forma (argumentos posicionales, argumentos por palabras clave) o bien de la forma (nombre, argumentos posicionales, argumentos por palabras clave). Esto no es particularmente interesante cuando los construyes por ti mismo, pero la introspección de los objetos call que conforman los atributos Mock.call_args, Mock.call_args_list y Mock.mock_calls si pueden ser de utilidad para para acceder a los argumentos individuales que contienen.

Los objetos call en Mock.call_args y Mock.call_args_list están conformados por dos tuplas (argumentos posicionales, argumentos por palabra clave) mientras que los objetos call en Mock.mock_calls, junto con los que construyas por ti mismo, constan de tres tuplas (nombre, argumentos posicionales, argumentos por palabra clave).

Puedes utilizar esta presentación en forma de tuplas para obtener los argumentos individuales, con la finalidad de llevar a cabo introspección y aserciones más complejas. Los argumentos posicionales son una tupla (vacía si no hay ninguno) y los argumentos por palabra clave son un diccionario:

>>> m = MagicMock(return_value=None)
>>> m(1, 2, 3, arg='one', arg2='two')
>>> kall = m.call_args
>>> kall.args
(1, 2, 3)
>>> kall.kwargs
{'arg': 'one', 'arg2': 'two'}
>>> kall.args is kall[0]
True
>>> kall.kwargs is kall[1]
True

>>> m = MagicMock()
>>> m.foo(4, 5, 6, arg='two', arg2='three')
<MagicMock name='mock.foo()' id='...'>
>>> kall = m.mock_calls[0]
>>> name, args, kwargs = kall
>>> name
'foo'
>>> args
(4, 5, 6)
>>> kwargs
{'arg': 'two', 'arg2': 'three'}
>>> name is m.mock_calls[0][0]
True

create_autospec

unittest.mock.create_autospec(spec, spec_set=False, instance=False, **kwargs)

Crea un nuevo objeto simulado utilizando otro objeto (spec) como especificación. Los atributos del objeto simulado utilizarán el atributo correspondiente del objeto spec como su especificación.

Los argumentos de las funciones o métodos simulados se validarán para asegurarse de que son invocados con la firma correcta.

Si spec_set es True, tratar de establecer atributos que no existen en el objeto especificado lanzará una excepción AttributeError.

Si se utiliza una clase como especificación, el valor de retorno del objeto simulado (la instancia de la clase) tendrá la misma especificación. Se puede utilizar una clase como especificación de una instancia pasando instance=True. El objeto simulado retornado sólo será invocable si las instancias del objeto simulado son también invocables.

create_autospec() también acepta argumentos por palabra clave arbitrarios, que son pasados al constructor del objeto simulado creado.

Consultar Autoespecificación para ver ejemplos de cómo utilizar la autoespecificación mediante create_autospec() y el argumento autospec de patch().

Distinto en la versión 3.8: create_autospec() ahora retorna un objeto AsyncMock si el objetivo a simular es una función asíncrona.

ANY

unittest.mock.ANY

A veces puede que necesites hacer aserciones sobre algunos de los argumentos de una llamada al objeto simulado, pero sin preocuparte por el resto, o puede que quieras hacer uso de ellos de forma individual fuera de call_args y hacer aserciones más complejas con ellos.

Para ignorar ciertos argumentos puedes pasar objetos que se comparan como iguales con cualquier cosa. En este caso, las llamadas a assert_called_with() y assert_called_once_with() tendrán éxito sin importar lo que se haya pasado realmente.

>>> mock = Mock(return_value=None)
>>> mock('foo', bar=object())
>>> mock.assert_called_once_with('foo', bar=ANY)

ANY también se puede utilizar en las comparaciones con las listas de llamadas, como mock_calls:

>>> m = MagicMock(return_value=None)
>>> m(1)
>>> m(1, 2)
>>> m(object())
>>> m.mock_calls == [call(1), call(1, 2), ANY]
True

FILTER_DIR

unittest.mock.FILTER_DIR

FILTER_DIR es una variable definida a nivel de módulo que controla la forma en la que los objetos simulados responden a dir() (sólo para Python 2.6 y en adelante). El valor predeterminado es True, que utiliza el filtrado descrito a continuación, con la finalidad de mostrar solo los miembros considerados como útiles. Si no te gusta este filtrado, o necesitas desactivarlo con fines de diagnóstico, simplemente establece mock.FILTER_DIR = False.

Con el filtrado activado, dir(some_mock) mostrará solo atributos útiles y además incluirá cualquier atributo creado dinámicamente, que normalmente no se mostraría. Si el objeto simulado fue creado con un spec (o autospec) se muestran todos los atributos del objeto original, incluso si no se ha accedido a ellos todavía:

>>> dir(Mock())
['assert_any_call',
 'assert_called',
 'assert_called_once',
 'assert_called_once_with',
 'assert_called_with',
 'assert_has_calls',
 'assert_not_called',
 'attach_mock',
 ...
>>> from urllib import request
>>> dir(Mock(spec=request))
['AbstractBasicAuthHandler',
 'AbstractDigestAuthHandler',
 'AbstractHTTPHandler',
 'BaseHandler',
 ...

Muchos de los atributos con subrayado y doble subrayado no muy útiles (atributos privados de Mock y no del objeto real que se está simulando) se han filtrado del resultado de llamar a dir() en un objeto Mock. Si no te gusta este comportamiento, puedes desactivarlo estableciendo el modificador a nivel de módulo FILTER_DIR:

>>> from unittest import mock
>>> mock.FILTER_DIR = False
>>> dir(mock.Mock())
['_NonCallableMock__get_return_value',
 '_NonCallableMock__get_side_effect',
 '_NonCallableMock__return_value_doc',
 '_NonCallableMock__set_return_value',
 '_NonCallableMock__set_side_effect',
 '__call__',
 '__class__',
 ...

Como alternativa, puedes usar vars(my_mock) (miembros de instancia) y dir(type(my_mock)) (miembros de tipo) para omitir el filtrado con independencia del valor de mock.FILTER_DIR.

mock_open

unittest.mock.mock_open(mock=None, read_data=None)

Una función auxiliar que permite crear un objeto simulado con la finalidad de reemplazar el uso de open(). Funciona para simular llamadas directas a open() y para aquellos casos en los que es utilizada como gestor de contexto.

El argumento mock es el objeto simulado a configurar. Si es None (por defecto) un objeto MagicMock se creará para ti, con la API limitada a métodos o atributos disponibles en los gestores de fichero estándares.

read_data es una cadena de caracteres para los métodos read(), readline() y readlines() del gestor de fichero a retornar. Las llamadas a los métodos tomarán datos de read_data hasta que se agote. El objeto simulado de estos métodos es bastante simple: cada vez que el mock se llama, read_data se rebobina hasta el principio. Si necesitas más control sobre los datos que estás proporcionando al código de prueba tendrás que personalizar el objeto simulado. Cuando eso no sea suficiente, alguno de los paquetes que implementan sistemas de archivos en memoria disponible en PyPI [https://pypi.org] puede ofrecer un sistema de archivos realista para usar en las pruebas.

Distinto en la versión 3.4: Se añadió soporte para readline() y readlines(). El objeto simulado de read() ahora consume datos de read_data, en lugar de retornarlo en cada llamada.

Distinto en la versión 3.5: read_data ahora es restablecido en cada llamada al mock.

Distinto en la versión 3.8: Se añadió el método __iter__() a la implementación, de manera que la iteración (como ocurre en los bucles) consume apropiadamente read_data.

Usar open() como gestor de contexto es una buena manera de asegurarse de que los gestores de archivos se cierren correctamente al terminar y se está convirtiendo en una práctica común:

with open('/some/path', 'w') as f:
    f.write('something')

El problema es que, incluso si simulas la llamada a open(), es el objeto retornado el que se utiliza como gestor de contexto (lo que conlleva que sus métodos __enter__() y __exit__() son invocados).

Simular gestores de contexto con un MagicMock es lo suficientemente común y complicado como para que una función auxiliar sea útil:

>>> m = mock_open()
>>> with patch('__main__.open', m):
...     with open('foo', 'w') as h:
...         h.write('some stuff')
...
>>> m.mock_calls
[call('foo', 'w'),
 call().__enter__(),
 call().write('some stuff'),
 call().__exit__(None, None, None)]
>>> m.assert_called_once_with('foo', 'w')
>>> handle = m()
>>> handle.write.assert_called_once_with('some stuff')

Y para la lectura de archivos:

>>> with patch('__main__.open', mock_open(read_data='bibble')) as m:
...     with open('foo') as h:
...         result = h.read()
...
>>> m.assert_called_once_with('foo')
>>> assert result == 'bibble'

Autoespecificación

La autoespecificación se basa en la característica spec ya existente en el objeto simulado. Limita la API de los objetos simulados a la API del objeto original (la especificación), pero es recursiva (implementada de forma perezosa), de modo que los atributos del objeto simulado sólo tienen la misma API que los atributos de la especificación. Además, las funciones / métodos simuladas tienen la misma firma de llamada que la original y lanzan una excepción TypeError si se les llama incorrectamente.

Antes de explicar cómo funciona la autoespecificación, he aquí por qué se necesita.

Mock es un objeto muy potente y flexible, pero adolece de dos defectos cuando se utiliza para simular objetos de un sistema bajo prueba. Uno de estos defectos es específico de la API de Mock y el otro es un problema más genérico referente al uso de objetos simulados.

En primer lugar, el problema específico a Mock. Mock tiene dos métodos de aserción que son extremadamente útiles: assert_called_with() y assert_called_once_with().

>>> mock = Mock(name='Thing', return_value=None)
>>> mock(1, 2, 3)
>>> mock.assert_called_once_with(1, 2, 3)
>>> mock(1, 2, 3)
>>> mock.assert_called_once_with(1, 2, 3)
Traceback (most recent call last):
 ...
AssertionError: Expected 'mock' to be called once. Called 2 times.

Debido a que los objetos simulados crean automáticamente atributos según demanda y además permiten que se les llame con argumentos arbitrarios, si escribes mal uno de estos métodos de aserción, la utilidad de esa aserción desaparece:

>>> mock = Mock(name='Thing', return_value=None)
>>> mock(1, 2, 3)
>>> mock.assret_called_once_with(4, 5, 6)  # Intentional typo!

Tus pruebas pueden pasar silenciosamente y de forma incorrecta debido al error tipográfico.

El segundo problema es algo más general en las simulaciones. Si refactorizas parte de tu código, cambias el nombre de los miembros, etc., las pruebas para el código que siguen utilizando la antigua API, pero utilizan objetos simulados en lugar de los objetos reales, todavía pasarán las pruebas. Esto significa que tus pruebas pueden validarlo todo sin problemas, a pesar de que el código esté roto.

Ten en cuenta que esta es otra razón por la que necesitas pruebas de integración además de pruebas unitarias. Probar todo de forma aislada está muy bien, pero si no pruebas cómo están «conectadas entre sí» tus unidades, todavía hay mucho espacio para errores que las pruebas deberían haber detectado.

mock ya proporciona una característica para ayudar con esto, llamada especificación. Si se utiliza una clase o instancia como atributo spec de un objeto simulado, entonces solo puedes acceder a los atributos del mismo que existe en la clase real:

>>> from urllib import request
>>> mock = Mock(spec=request.Request)
>>> mock.assret_called_with  # Intentional typo!
Traceback (most recent call last):
 ...
AttributeError: Mock object has no attribute 'assret_called_with'

La especificación sólo se aplica al propio objeto simulado, por lo que aún tenemos el mismo problema con cualquiera de los métodos del mismo:

>>> mock.has_data()
<mock.Mock object at 0x...>
>>> mock.has_data.assret_called_with()  # Intentional typo!

La autoespecificación resuelve este problema. Puedes pasar autospec=True a patch() / patch.object() o utilizar la función create_autospec() para crear un objeto simulado con una especificación. Si utilizas el argumento autospec=True de patch(), el objeto que se va a reemplazar se utiliza como objeto de especificación. Debido a que la especificación se hace «perezosamente» (la especificación se crea en el instante en el que se accede a los atributos del objeto simulado, no antes), se puede utilizar con objetos muy complejos o anidadas (como módulos que importan módulos que, a su vez, importan otros módulos) sin un gran impacto en el rendimiento.

He aquí un ejemplo de ello en acción:

>>> from urllib import request
>>> patcher = patch('__main__.request', autospec=True)
>>> mock_request = patcher.start()
>>> request is mock_request
True
>>> mock_request.Request
<MagicMock name='request.Request' spec='Request' id='...'>

Se puede ver que request.Request tiene una especificación. request.Request toma dos argumentos en el constructor (uno de los cuales es self). Esto es lo que sucede si tratamos de llamarlo de forma incorrecta:

>>> req = request.Request()
Traceback (most recent call last):
 ...
TypeError: <lambda>() takes at least 2 arguments (1 given)

La especificación también se aplica a las clases instanciadas (es decir, el valor de retorno de los objetos simulados especificados):

>>> req = request.Request('foo')
>>> req
<NonCallableMagicMock name='request.Request()' spec='Request' id='...'>

Los objetos de la clase Request no son invocables, por lo que el valor de retorno de una instancia de nuestro objeto simulado de request.Request no es invocable. Con la especificación, en cambio, cualquier error tipográfico en nuestras aserciones generará el error correcto:

>>> req.add_header('spam', 'eggs')
<MagicMock name='request.Request().add_header()' id='...'>
>>> req.add_header.assret_called_with  # Intentional typo!
Traceback (most recent call last):
 ...
AttributeError: Mock object has no attribute 'assret_called_with'
>>> req.add_header.assert_called_with('spam', 'eggs')

En muchos casos, podrás simplemente añadir autospec=True a tus llamadas patch() existentes y así estar protegido contra errores tipográficos y cambios de la API.

Además de poder usar autospec a través de patch(), existe la función create_autospec() para crear directamente objetos simulados autoespecificados:

>>> from urllib import request
>>> mock_request = create_autospec(request)
>>> mock_request.Request('foo', 'bar')
<NonCallableMagicMock name='mock.Request()' spec='Request' id='...'>

Sin embargo, este no es el comportamiento predeterminado, ya que no está exento de advertencias y restricciones. Con el fin de conocer qué atributos están disponibles en el objeto especificado, autospec tiene que hacer uso de introspección sobre la especificación (acceder a los atributos). A medida que recorres los atributos en el objeto simulado, se produce paralelamente y de forma soterrada un recorrido del objeto original. Si alguno de tus objetos especificados tienen propiedades o descriptores que puedan desencadenar la ejecución de código, quizás no deberías utilizar la autoespecificación. De todas formas, es siempre mucho mejor diseñar tus objetos de modo que la introspección sea segura 4.

Un problema más serio es que es común que los atributos de instancia sean creados en el método __init__() y que no existan a nivel de clase. autospec no puede tener conocimiento de ningún atributo creado dinámicamente, por lo que restringe la API a atributos visibles:

>>> class Something:
...   def __init__(self):
...     self.a = 33
...
>>> with patch('__main__.Something', autospec=True):
...   thing = Something()
...   thing.a
...
Traceback (most recent call last):
  ...
AttributeError: Mock object has no attribute 'a'

Hay diferentes formas de resolver este problema. La forma más sencilla, pero no necesariamente la menos molesta, es simplemente establecer los atributos necesarios en el objeto simulado después de la creación del mismo. El hecho de que autospec no te permita buscar atributos que no existen en la especificación no impide que los establezcas manualmente después:

>>> with patch('__main__.Something', autospec=True):
...   thing = Something()
...   thing.a = 33
...

Existe una versión más agresiva de spec y autospec que impide establecer atributos inexistentes. Esto es útil si deseas asegurarte de que tu código solo establece atributos válidos, pero obviamente evitando este escenario en particular:

>>> with patch('__main__.Something', autospec=True, spec_set=True):
...   thing = Something()
...   thing.a = 33
...
Traceback (most recent call last):
 ...
AttributeError: Mock object has no attribute 'a'

Probablemente la mejor manera de resolver el problema es añadir atributos de clase como valores por defecto para los miembros de instancia inicializados en el método __init__(). Ten en cuenta que, si sólo estás estableciendo atributos predeterminados en __init__(), proporcionarlos a través de atributos de clase (que , por supuesto, son compartidos entre instancias) también es más rápido.

class Something:
    a = 33

Esto nos plantea otro problema. Es relativamente común proporcionar un valor predeterminado de None para los miembros que posteriormente se convertirán en objetos de un tipo diferente. None es inútil como especificación dado que no permite acceder a ningún atributo o método. Como None nunca será útil como especificación, y probablemente indica un miembro que normalmente será de algún otro tipo en el futuro, la autoespecificación no usa una especificación para aquellos miembros configurados con None como valor. Estos serán simplemente objetos simulados ordinarios (MagicMocks en realidad):

>>> class Something:
...     member = None
...
>>> mock = create_autospec(Something)
>>> mock.member.foo.bar.baz()
<MagicMock name='mock.member.foo.bar.baz()' id='...'>

Si modificar tus clases en producción para agregar valores predeterminados no es de tu agrado, dispones de otras opciones. Una de ellas es simplemente usar una instancia como especificación en lugar de la clase. La otra es crear una subclase de la clase en producción y agregar los valores predeterminados a la subclase, sin afectar a la clase en producción. Ambas alternativas requieren que uses un objeto alternativo como especificación. Afortunadamente patch() admite esto, simplemente tienes que pasar el objeto alternativo mediante el argumento autospec:

>>> class Something:
...   def __init__(self):
...     self.a = 33
...
>>> class SomethingForTest(Something):
...   a = 33
...
>>> p = patch('__main__.Something', autospec=SomethingForTest)
>>> mock = p.start()
>>> mock.a
<NonCallableMagicMock name='Something.a' spec='int' id='...'>

4

Esto sólo se aplica a las clases u objetos ya instanciados. Llamar a una clase simulada para crear una instancia simulada no crea una instancia real. Solo se llevan a cabo las búsqueda de atributos (mediante llamadas a dir()).

Sellar objetos simulados

unittest.mock.seal(mock)

Seal desactivará la creación automática de objetos simulados al acceder a un atributo del objeto simulado que está siendo sellado, o a cualquiera de sus atributos que ya sean objetos simulados de forma recursiva.

Si una instancia simulada con un nombre o una especificación es asignada a un atributo no será considerada en la cadena de sellado. Esto permite evitar que seal fije partes del objeto simulado.

>>> mock = Mock()
>>> mock.submock.attribute1 = 2
>>> mock.not_submock = mock.Mock(name="sample_name")
>>> seal(mock)
>>> mock.new_attribute  # This will raise AttributeError.
>>> mock.submock.attribute2  # This will raise AttributeError.
>>> mock.not_submock.attribute2  # This won't raise.

Nuevo en la versión 3.7.

unittest.mock — primeros pasos

Nuevo en la versión 3.3.

Usando Mock

Métodos de parcheo Mock

Usos comunes para objetos Mock incluye:

Métodos de parcheo

Métodos de grabación de llamadas sobre objetos

Es posible que desee reemplazar un método en un objeto para comprobar que se llama con los argumentos correctos por otra parte del sistema:

>>> real = SomeClass()
>>> real.method = MagicMock(name='method')
>>> real.method(3, 4, 5, key='value')
<MagicMock name='method()' id='...'>

Una vez que se ha utilizado nuestro mock (real.method en este ejemplo) tiene métodos y atributos que le permiten hacer afirmaciones sobre cómo se ha utilizado.

Nota

En la mayoría de estos ejemplos, las clases Mock y MagicMock son intercambiables. Como el MagicMock es la clase más capaz, hace que sea sensato usarlo por defecto.

Una vez que el mock ha sido llamado su atributo called se establece en True. Lo que es más importante, podemos usar el método assert_called_with() o assert_called_once_with() para comprobar que se llamó con los argumentos correctos.

En este ejemplo se prueba que llamar a ProductionClass().method da como resultado una llamada al método something:

>>> class ProductionClass:
...     def method(self):
...         self.something(1, 2, 3)
...     def something(self, a, b, c):
...         pass
...
>>> real = ProductionClass()
>>> real.something = MagicMock()
>>> real.method()
>>> real.something.assert_called_once_with(1, 2, 3)

Mock de llamadas a métodos sobre un objeto

En el último ejemplo, parcheamos un método directamente en un objeto para comprobar que se llamó correctamente. Otro caso de uso común es pasar un objeto a un método (o a alguna parte del sistema sometido a prueba) y, a continuación, comprobar que se utiliza de la manera correcta.

La sencilla ProductionClass a continuación tiene un método closer. Si se llama con un objeto, entonces llama a close en él.

>>> class ProductionClass:
...     def closer(self, something):
...         something.close()
...

Así que para probarlo necesitamos pasar un objeto con un método close y comprobar que se llamó correctamente.

>>> real = ProductionClass()
>>> mock = Mock()
>>> real.closer(mock)
>>> mock.close.assert_called_with()

No tenemos que hacer ningún trabajo para proporcionar el método de “close” en nuestro mock. El acceso al cierre lo crea. Por lo tanto, si “close” aún no se ha llamado, entonces acceder a él en la prueba lo creará, pero assert_called_with() generará una excepción de error.

Clases Mocking

Un caso de uso común es simular las clases que crea la instancia del código que se está probando. Cuando se aplica un parche a una clase, esa clase se reemplaza por un mock. Las instancias se crean llamando a la clase. Esto significa que tiene acceso a la «instancia mock» examinando el valor devuelto de la clase simulada.

En el ejemplo siguiente tenemos una función some_function que crea una instancia de Foo y llama a un método en él. La llamada a patch() reemplaza la clase Foo con un mock. La instancia Foo es el resultado de llamar al mock, por lo que se configura modificando el mock -Mock.return_value.

>>> def some_function():
...     instance = module.Foo()
...     return instance.method()
...
>>> with patch('module.Foo') as mock:
...     instance = mock.return_value
...     instance.method.return_value = 'the result'
...     result = some_function()
...     assert result == 'the result'

Nombrando tus mocks

Puede ser útil poner un nombre a tus mocks. El nombre se muestra en la reproducción del mock y puede ser útil cuando el mock aparece en los mensajes de error de la prueba. El nombre también se propaga a los atributos o métodos del mock:

>>> mock = MagicMock(name='foo')
>>> mock
<MagicMock name='foo' id='...'>
>>> mock.method
<MagicMock name='foo.method' id='...'>

Siguiendo todas las llamadas

A menudo, desea realizar un seguimiento de más de una llamada a un método. El atributo mock_calls registra todas las llamadas a los atributos secundarios del mock, y también a sus hijos.

>>> mock = MagicMock()
>>> mock.method()
<MagicMock name='mock.method()' id='...'>
>>> mock.attribute.method(10, x=53)
<MagicMock name='mock.attribute.method()' id='...'>
>>> mock.mock_calls
[call.method(), call.attribute.method(10, x=53)]

Si realiza una afirmación sobre mock_calls y se ha llamado a cualquier método inesperado, la aserción fallará. Esto es útil porque además de afirmar que se han realizado las llamadas que esperaba, también está comprobando que se hicieron en el orden correcto y sin llamadas adicionales:

Utiliza el objeto call para construir listas y compararlas con mock_calls:

>>> expected = [call.method(), call.attribute.method(10, x=53)]
>>> mock.mock_calls == expected
True

Sin embargo, los parámetros de las llamadas que devuelven mocks no se registran, lo que significa que no es posible realizar un seguimiento de las llamadas anidadas donde los parámetros utilizados para crear ancestros son importantes:

>>> m = Mock()
>>> m.factory(important=True).deliver()
<Mock name='mock.factory().deliver()' id='...'>
>>> m.mock_calls[-1] == call.factory(important=False).deliver()
True

Establecer valores de retorno y atributos

Establecer los valores de retorno en un objeto mock es sumamente fácil:

>>> mock = Mock()
>>> mock.return_value = 3
>>> mock()
3

Por supuesto, puede hacer lo mismo con los métodos en el mock:

>>> mock = Mock()
>>> mock.method.return_value = 3
>>> mock.method()
3

El valor devuelto también se puede establecer en el constructor:

>>> mock = Mock(return_value=3)
>>> mock()
3

Si necesitas una configuración de atributo en su mock, simplemente haga:

>>> mock = Mock()
>>> mock.x = 3
>>> mock.x
3

A veces desea simular una situación más compleja, como por ejemplo mock.connection.cursor().execute("SELECT 1"). Si esperamos que esta llamada devuelva una lista, entonces tenemos que configurar el resultado de la llamada anidada.

Podemos usar call para construir el conjunto de llamadas en una «llamada encadenada» como esta para una fácil afirmación después:

>>> mock = Mock()
>>> cursor = mock.connection.cursor.return_value
>>> cursor.execute.return_value = ['foo']
>>> mock.connection.cursor().execute("SELECT 1")
['foo']
>>> expected = call.connection.cursor().execute("SELECT 1").call_list()
>>> mock.mock_calls
[call.connection.cursor(), call.connection.cursor().execute('SELECT 1')]
>>> mock.mock_calls == expected
True

Es la llamada a .call_list() la que convierte nuestro objeto de llamada en una lista de llamadas que representan las llamadas encadenadas.

Generar excepciones con mocks

Un atributo útil es side_effect. Si establece esto en una clase o instancia de excepción, se producirá la excepción cuando se llame al mock.

>>> mock = Mock(side_effect=Exception('Boom!'))
>>> mock()
Traceback (most recent call last):
  ...
Exception: Boom!

Funciones de efectos secundarios e iterables

side_effect también se puede asignar en una función o en una iterable. El caso de uso para side_effect como un iterable es donde se va a llamar a su mock varias veces, y desea que cada llamada devuelva un valor diferente. Cuando se asigna side_effect en un iterable cada llamada al mock devuelve el siguiente valor de lo iterable:

>>> mock = MagicMock(side_effect=[4, 5, 6])
>>> mock()
4
>>> mock()
5
>>> mock()
6

Para casos de uso más avanzados, como variar dinámicamente los valores devueltos en función de cómo se llame al mock, side_effect puede ser una función. Se llamará a la función con los mismos argumentos que el mock. Lo que sea que la función devuelve es lo que devuelve la llamada:

>>> vals = {(1, 2): 1, (2, 3): 2}
>>> def side_effect(*args):
...     return vals[args]
...
>>> mock = MagicMock(side_effect=side_effect)
>>> mock(1, 2)
1
>>> mock(2, 3)
2

Iteradores asincrónicos de Mocking

Desde Python 3.8, AsyncMock y MagicMock tienen soporte para mock Iteradores asíncronos through __aiter__. El return_value atributo de __aiter__ puede ser usado para asignar los valores de retorno que podrían ser usados por iteración.

>>> mock = MagicMock()  # AsyncMock also works here
>>> mock.__aiter__.return_value = [1, 2, 3]
>>> async def main():
...     return [i async for i in mock]
...
>>> asyncio.run(main())
[1, 2, 3]

El gestor de contexto asincrónico de Mocking

Desde Python 3.8, AsyncMock y MagicMock tienen soporte para mock Gestores de Contexto Asíncronos a través de __aenter__ y __aexit__. De forma predeterminada, las instancias __aenter__ y __aexit__ son instancias de AsyncMock que devuelven una función asincrónica.

>>> class AsyncContextManager:
...     async def __aenter__(self):
...         return self
...     async def __aexit__(self, exc_type, exc, tb):
...         pass
...
>>> mock_instance = MagicMock(AsyncContextManager())  # AsyncMock also works here
>>> async def main():
...     async with mock_instance as result:
...         pass
...
>>> asyncio.run(main())
>>> mock_instance.__aenter__.assert_awaited_once()
>>> mock_instance.__aexit__.assert_awaited_once()

Creando un mock desde un objeto existente

Un problema con el uso excesivo de mocking es que combina sus pruebas a la implementación de sus mocks en lugar de su código real. Supongamos que tiene una clase que implementa some_method. En una prueba para otra clase, se proporciona un mock de este objeto que also proporciona some_method. Si más tarde refactoriza la primera clase, para que ya no tenga some_method - entonces sus pruebas seguirán pasando a pesar de que su código está ahora roto!

Mock le permite proporcionar un objeto como especificación para el mock, utilizando el argumento de palabra clave spec. El acceso a métodos / atributos en el mock que no existen en el objeto de especificación generará inmediatamente un error de atributo. Si cambia la implementación de la especificación, las pruebas que usan esa clase comenzarán a fallar inmediatamente sin tener que crear instancias de la clase en esas pruebas.

>>> mock = Mock(spec=SomeClass)
>>> mock.old_method()
Traceback (most recent call last):
   ...
AttributeError: object has no attribute 'old_method'

El uso de una especificación también permite una coincidencia más inteligente de las llamadas realizadas al mock, independientemente de si algunos parámetros se pasaron como argumentos posicionales o con nombre:

>>> def f(a, b, c): pass
...
>>> mock = Mock(spec=f)
>>> mock(1, 2, 3)
<Mock name='mock()' id='140161580456576'>
>>> mock.assert_called_with(a=1, b=2, c=3)

Si desea que esta coincidencia más inteligente también funcione con llamadas de método en el mock, puede usar auto-speccing.

Si desea una forma más fuerte de especificación que impida la configuración de atributos arbitrarios, así como la obtención de ellos, entonces puede usar spec_set en lugar de spec.

Decoradores de Parches

Nota

Con patch() importa que parchee objetos en el espacio de nombres donde se buscan. Esto es normalmente sencillo, pero para una guía rápida lea where to patch.

Una necesidad común en las pruebas es aplicar revisiones a un atributo de clase o a un atributo de módulo, por ejemplo, aplicar revisiones a una clase integrada o parchear una clase en un módulo para probar que se crea una instancia. Los módulos y las clases son efectivamente globales, por lo que el parcheo en ellos tiene que deshacerse después de la prueba o el parche persistirá en otras pruebas y causará problemas difíciles de diagnosticar.

mock proporciona tres decoradores convenientes para esto: patch(), patch.object() y patch.dict(). patch toma una sola cadena del formulario package.module.Class.attribute para especificar el atributo que está parcheando. También, opcionalmente, toma un valor con el que desea que se reemplace el atributo (o clase o lo que sea). “patch.object” toma un objeto y el nombre del atributo con el que desea parchear, además, opcionalmente, del valor con el que parcharlo.

patch.object:

>>> original = SomeClass.attribute
>>> @patch.object(SomeClass, 'attribute', sentinel.attribute)
... def test():
...     assert SomeClass.attribute == sentinel.attribute
...
>>> test()
>>> assert SomeClass.attribute == original

>>> @patch('package.module.attribute', sentinel.attribute)
... def test():
...     from package.module import attribute
...     assert attribute is sentinel.attribute
...
>>> test()

Si está parcheando un módulo (incluyendo builtins) entonces use patch() en lugar de patch.object():

>>> mock = MagicMock(return_value=sentinel.file_handle)
>>> with patch('builtins.open', mock):
...     handle = open('filename', 'r')
...
>>> mock.assert_called_with('filename', 'r')
>>> assert handle == sentinel.file_handle, "incorrect file handle returned"

EL nombre del módulo puede ser “dotted”, en el formulario package.module si es necesario:

>>> @patch('package.module.ClassName.attribute', sentinel.attribute)
... def test():
...     from package.module import ClassName
...     assert ClassName.attribute == sentinel.attribute
...
>>> test()

Un buen patrón en realidad es decorar los métodos de pruebas propios:

>>> class MyTest(unittest.TestCase):
...     @patch.object(SomeClass, 'attribute', sentinel.attribute)
...     def test_something(self):
...         self.assertEqual(SomeClass.attribute, sentinel.attribute)
...
>>> original = SomeClass.attribute
>>> MyTest('test_something').test_something()
>>> assert SomeClass.attribute == original

Si desea parchear con un Mock, puede usar patch() con un solo argumento (o patch.object() con dos argumentos). El mock se creará para usted y se pasará a la función de prueba / método:

>>> class MyTest(unittest.TestCase):
...     @patch.object(SomeClass, 'static_method')
...     def test_something(self, mock_method):
...         SomeClass.static_method()
...         mock_method.assert_called_with()
...
>>> MyTest('test_something').test_something()

Puede apilar varios decoradores de parches utilizando este patrón:

>>> class MyTest(unittest.TestCase):
...     @patch('package.module.ClassName1')
...     @patch('package.module.ClassName2')
...     def test_something(self, MockClass2, MockClass1):
...         self.assertIs(package.module.ClassName1, MockClass1)
...         self.assertIs(package.module.ClassName2, MockClass2)
...
>>> MyTest('test_something').test_something()

Al anidar decoradores de parches, los mocks se pasan a la función decorada en el mismo orden en que se aplicaron (el orden normal Python que se aplican los decoradores). Esto significa de abajo hacia arriba, así que en el ejemplo anterior el simulacro de test_module.ClassName2 se pasa primero.

También está patch.dict() para establecer valores en un diccionario solo durante un ámbito y restaurar el diccionario a su estado original cuando finaliza la prueba:

>>> foo = {'key': 'value'}
>>> original = foo.copy()
>>> with patch.dict(foo, {'newkey': 'newvalue'}, clear=True):
...     assert foo == {'newkey': 'newvalue'}
...
>>> assert foo == original

patch, patch.object and patch.dict se pueden utilizar como gestores de contexto.

Donde utilice patch() para crear un simulacro para usted, puede obtener una referencia al simulacro utilizando la forma «as» de la instrucción with:

>>> class ProductionClass:
...     def method(self):
...         pass
...
>>> with patch.object(ProductionClass, 'method') as mock_method:
...     mock_method.return_value = None
...     real = ProductionClass()
...     real.method(1, 2, 3)
...
>>> mock_method.assert_called_with(1, 2, 3)

Como alternativa patch, patch.object and patch.dict se pueden utilizar como decoradores de clase. Cuando se utiliza de esta manera es lo mismo que aplicar el decorador individualmente a cada método cuyo nombre comienza con «test».

Otros Ejemplos

Estos son algunos ejemplos más para algunos escenarios ligeramente más avanzados.

Mocking de llamadas encadenadas

Mocking de las llamadas encadenadas es en realidad sencillo con mock una vez que entiende el atributo return_value . Cuando se llama a un mock por primera vez, o se obtiene su return_value antes de que se llame, se crea un nuevo Mock.

Esto significa que puede ver cómo se ha utilizado el objeto devuelto de una llamada a un objeto simulado interrogando el simulado return_value:

>>> mock = Mock()
>>> mock().foo(a=2, b=3)
<Mock name='mock().foo()' id='...'>
>>> mock.return_value.foo.assert_called_with(a=2, b=3)

Desde aquí es un paso simple para configurar y luego hacer aserciones sobre llamadas encadenadas. Por supuesto, otra alternativa es escribir su código de una manera más comprobable en primer lugar…

Por lo tanto, supongamos que tenemos algún código que se ve un poco como este:

>>> class Something:
...     def __init__(self):
...         self.backend = BackendProvider()
...     def method(self):
...         response = self.backend.get_endpoint('foobar').create_call('spam', 'eggs').start_call()
...         # more code

Suponiendo que BackendProvider ya está bien probado, ¿cómo probamos method()? En concreto, queremos probar que la sección de código # more code usa el objeto de respuesta de la manera correcta.

A medida que esta cadena de llamadas se realiza a partir de un atributo de instancia, podemos parchear el atributo backend en una instancia de Something. En este caso en particular sólo estamos interesados en el valor devuelto de la llamada final a start_call por lo que no tenemos mucha configuración que hacer. Supongamos que el objeto que devuelve es “similar a un archivo”, por lo que nos aseguraremos de que nuestro objeto de respuesta utilice el compilado open() as its spec.

Para ello creamos una instancia mock como nuestro back-end simulado y creamos un objeto de respuesta mock para ella. Para establecer la respuesta como el valor devuelto de ese start_call final podríamos hacer lo siguiente:

mock_backend.get_endpoint.return_value.create_call.return_value.start_call.return_value = mock_response

Podemos hacerlo de una manera un poco mejor usando el método configure_mock() para establecer directamente el valor devuelto para nosotros:

>>> something = Something()
>>> mock_response = Mock(spec=open)
>>> mock_backend = Mock()
>>> config = {'get_endpoint.return_value.create_call.return_value.start_call.return_value': mock_response}
>>> mock_backend.configure_mock(**config)

Con estos monkey patch el «backend simulado» en su lugar y puede hacer la llamada real:

>>> something.backend = mock_backend
>>> something.method()

Usando mock_calls podemos comprobar la llamada encadenada con una sola afirmación. Una llamada encadenada es varias llamadas en una línea de código, por lo que habrá varias entradas en mock_calls. Podemos usar call.call_list() para crear esta lista de llamadas para nosotros:

>>> chained = call.get_endpoint('foobar').create_call('spam', 'eggs').start_call()
>>> call_list = chained.call_list()
>>> assert mock_backend.mock_calls == call_list

Mocking parcial

En algunas pruebas quería un mock de una llamada a datetime.date.today() para devolver una fecha conocida, pero no quería evitar que el código sometido a prueba creara nuevos objetos de fecha. Desafortunadamente datetime.date está escrito en C, por lo que no podía simplemente parchear mono el método estático date.today() .

Encontré una forma sencilla de hacer esto que implicaba ajustar eficazmente la clase date con un mock, pero pasar llamadas al constructor a la clase real (y devolver instancias reales).

El patch decorator se utiliza aquí como un mock de la clase date en el módulo en pruebas. A continuación, el atributo side_effect de la clase de fecha simulada se establece en una función lambda que devuelve una fecha real. Cuando la clase de fecha simulada se denomina fecha real, se construirá y devolverá side_effect.

>>> from datetime import date
>>> with patch('mymodule.date') as mock_date:
...     mock_date.today.return_value = date(2010, 10, 8)
...     mock_date.side_effect = lambda *args, **kw: date(*args, **kw)
...
...     assert mymodule.date.today() == date(2010, 10, 8)
...     assert mymodule.date(2009, 6, 8) == date(2009, 6, 8)

Tenga en cuenta que no parcheamos datetime.date globalmente, parcheamos date en el módulo que uses. Consulte where to patch.

Cuando date.today() es llamada se retorna una fecha conocida, pero llama al constructor date(...) este constructor todavía devuelve fechas normales. Sin esto, puede encontrarse teniendo que calcular un resultado esperado utilizando exactamente el mismo algoritmo que el código en prueba, que es un anti-patrón de prueba clásico.

Las llamadas al constructor de fecha se registran en los atributos mock_date (call_count y amigos) que también pueden ser útiles para las pruebas.

Una forma alternativa de tratar con fechas de mock, u otras clases integradas, se discute en esta entrada de blog [https://williambert.online/2011/07/how-to-unit-testing-in-django-with-mocking-and-patching/].

Mocking de un Método Generador

Un generador de Python es una función o método que utiliza la instrucción yield para devolver una serie de valores cuando se itera sobre 1.

Se llama a un método / función del generador para devolver el objeto generador. Es el objeto generador que luego se itera. El método de protocolo para la iteración es __iter__(), por lo que podemos hacer mock de esto usando una MagicMock.

Aquí hay una clase de ejemplo con un método «iter» implementado como generador:

>>> class Foo:
...     def iter(self):
...         for i in [1, 2, 3]:
...             yield i
...
>>> foo = Foo()
>>> list(foo.iter())
[1, 2, 3]

¿Cómo haríamos un mock de esta clase y, en particular, de su método «iter»?

Para configurar los valores devueltos desde la iteración (implícita en la llamada a list), necesitamos configurar el objeto devuelto por la llamada a foo.iter().

>>> mock_foo = MagicMock()
>>> mock_foo.iter.return_value = iter([1, 2, 3])
>>> list(mock_foo.iter())
[1, 2, 3]

1

También hay expresiones generadoras y más usos avanzados <http://www.dabeaz.com/coroutines/index.html>”_ de generadores, pero no nos preocupan los que están aquí. Una muy buena introducción a los generadores y lo potentes que son es: Generator Tricks for Systems Programmers [http://www.dabeaz.com/generators/].

Aplicar el mismo parche a cada método de prueba

Si desea que se coloquen varias revisiones para varios métodos de prueba, la forma obvia es aplicar los decoradores de parches a cada método. Esto puede parecer una repetición innecesaria. Para Python 2.6 o más reciente puede utilizar patch() (en todas sus diversas formas) como decorador de clases. Esto aplica las revisiones a todos los métodos de prueba de la clase. Un método de prueba se identifica mediante métodos cuyos nombres comienzan con test:

>>> @patch('mymodule.SomeClass')
... class MyTest(unittest.TestCase):
...
...     def test_one(self, MockSomeClass):
...         self.assertIs(mymodule.SomeClass, MockSomeClass)
...
...     def test_two(self, MockSomeClass):
...         self.assertIs(mymodule.SomeClass, MockSomeClass)
...
...     def not_a_test(self):
...         return 'something'
...
>>> MyTest('test_one').test_one()
>>> MyTest('test_two').test_two()
>>> MyTest('test_two').not_a_test()
'something'

Una forma alternativa de administrar parches es usar Métodos start y stop de patch. Estos le permiten mover el parche en sus métodos setUp y tearDown.

>>> class MyTest(unittest.TestCase):
...     def setUp(self):
...         self.patcher = patch('mymodule.foo')
...         self.mock_foo = self.patcher.start()
...
...     def test_foo(self):
...         self.assertIs(mymodule.foo, self.mock_foo)
...
...     def tearDown(self):
...         self.patcher.stop()
...
>>> MyTest('test_foo').run()

Si utiliza esta técnica, debe asegurarse de que la aplicación de parches se «undone» llamando a stop. Esto puede ser más complicado de lo que podría pensar, porque si se produce una excepción en el setUp, no se llama a tearDown. unittest.TestCase.addCleanup() hace que esto sea más fácil:

>>> class MyTest(unittest.TestCase):
...     def setUp(self):
...         patcher = patch('mymodule.foo')
...         self.addCleanup(patcher.stop)
...         self.mock_foo = patcher.start()
...
...     def test_foo(self):
...         self.assertIs(mymodule.foo, self.mock_foo)
...
>>> MyTest('test_foo').run()

Mocking de métodos sin enlazar

Mientras escribía pruebas hoy en día, necesitaba parchear un método unbound method (parchear el método en la clase en lugar de en la instancia). Necesitaba que se pasara a sí mismo como primer argumento porque quiero hacer aserciones sobre qué objetos estaban llamando a este método en particular. El problema es que no se puede parchear con un mock para esto, porque si reemplaza un método independiente con un mock, no se convierte en un método enlazado cuando se obtiene de la instancia, por lo que no se pasa por sí mismo. La solución es revisar el método independiente con una función real en su lugar. El decorador patch() hace que sea tan simple parchear métodos con un mock que tener que crear una función real se convierte en una molestia.

Si pasa autospec=True al parche, entonces hace el parche con un objeto de función real. Este objeto de función tiene la misma firma que el que está reemplazando, pero delega en un mock bajo el capó. Usted todavía consigue su mock de auto-creado exactamente de la misma manera que antes. Lo que significa, sin embargo, es que si lo usa para parchear un método independiente en una clase, la función simulada se convertirá en un método enlazado si se obtiene de una instancia. Tendrá self pasado como el primer argumento, que es exactamente lo que quería:

>>> class Foo:
...   def foo(self):
...     pass
...
>>> with patch.object(Foo, 'foo', autospec=True) as mock_foo:
...   mock_foo.return_value = 'foo'
...   foo = Foo()
...   foo.foo()
...
'foo'
>>> mock_foo.assert_called_once_with(foo)

Si no usamos autospec=True entonces el método independiente se parchea con una instancia de Mock en su lugar, y no se llama con self.

Comprobación de varias llamadas con mock

mock tiene una buena API para hacer aserciones sobre cómo se usan sus objetos ficticios.

>>> mock = Mock()
>>> mock.foo_bar.return_value = None
>>> mock.foo_bar('baz', spam='eggs')
>>> mock.foo_bar.assert_called_with('baz', spam='eggs')

Si su mock solo se llama una vez, puede usar el método assert_called_once_with() que también afirma que call_count es uno.

>>> mock.foo_bar.assert_called_once_with('baz', spam='eggs')
>>> mock.foo_bar()
>>> mock.foo_bar.assert_called_once_with('baz', spam='eggs')
Traceback (most recent call last):
    ...
AssertionError: Expected to be called once. Called 2 times.

Tanto assert_called_with como assert_called_once_with hacen afirmaciones sobre la llamada más reciente. Si su mock va a ser llamado varias veces, y desea hacer aserciones sobre todas esas llamadas que puede utilizar call_args_list:

>>> mock = Mock(return_value=None)
>>> mock(1, 2, 3)
>>> mock(4, 5, 6)
>>> mock()
>>> mock.call_args_list
[call(1, 2, 3), call(4, 5, 6), call()]

El helper call facilita la toma de aserciones sobre estas llamadas. Puede crear una lista de llamadas esperadas y compararla con call_args_list. Esto se ve notablemente similar al repr de la call_args_list:

>>> expected = [call(1, 2, 3), call(4, 5, 6), call()]
>>> mock.call_args_list == expected
True

Copiando con argumentos mutables

Otra situación es rara, pero puede morderte, es cuando se llama a tu mock con argumentos mutables. call_args y call_args_list almacenan referencias a los argumentos. Si el código sometido a prueba muta los argumentos ya no puede realizar aserciones sobre cuáles eran los valores cuando se llamó al mock.

Este es un código de ejemplo que muestra el problema. Imagine las siguientes funciones definidas en “mymodule”:

def frob(val):
    pass

def grob(val):
    "First frob and then clear val"
    frob(val)
    val.clear()

Cuando tratamos de probar que grob llama frob con el argumento correcto mira lo que sucede:

>>> with patch('mymodule.frob') as mock_frob:
...     val = {6}
...     mymodule.grob(val)
...
>>> val
set()
>>> mock_frob.assert_called_with({6})
Traceback (most recent call last):
    ...
AssertionError: Expected: (({6},), {})
Called with: ((set(),), {})

Una posibilidad sería que el mock copiara los argumentos que pasa. Esto podría causar problemas si realiza aserciones que se basan en la identidad del objeto para la igualdad.

Aquí hay una solución que utiliza la funcionalidad side_effect. Si proporciona una función side_effect para un mock, se llamará a side_effect con los mismos argumentos que el mock. Esto nos da la oportunidad de copiar los argumentos y almacenarlos para aserciones posteriores. En este ejemplo estoy usando otro mock para almacenar los argumentos de modo que pueda usar los métodos ficticios para hacer la aserción. Una vez más, una función auxiliar configura esto para mí.

>>> from copy import deepcopy
>>> from unittest.mock import Mock, patch, DEFAULT
>>> def copy_call_args(mock):
...     new_mock = Mock()
...     def side_effect(*args, **kwargs):
...         args = deepcopy(args)
...         kwargs = deepcopy(kwargs)
...         new_mock(*args, **kwargs)
...         return DEFAULT
...     mock.side_effect = side_effect
...     return new_mock
...
>>> with patch('mymodule.frob') as mock_frob:
...     new_mock = copy_call_args(mock_frob)
...     val = {6}
...     mymodule.grob(val)
...
>>> new_mock.assert_called_with({6})
>>> new_mock.call_args
call({6})

copy_call_args se llama con el mock que se llamará. Devuelve un nuevo mock en el que hacemos la aserción. La función side_effect hace una copia de los args y llama a nuestro new_mock con la copia.

Nota

Si su simulacro solo se va a usar una vez, hay una forma más fácil de verificar los argumentos en el punto en que se llaman. Simplemente puede hacer la comprobación dentro de una función side_effect.

>>> def side_effect(arg):
...     assert arg == {6}
...
>>> mock = Mock(side_effect=side_effect)
>>> mock({6})
>>> mock(set())
Traceback (most recent call last):
    ...
AssertionError

Un enfoque alternativo es crear una subclase de Mock o MagicMock que copie (usando copy.deepcopy()) los argumentos. A continuación se muestra un ejemplo de implementación:

>>> from copy import deepcopy
>>> class CopyingMock(MagicMock):
...     def __call__(self, /, *args, **kwargs):
...         args = deepcopy(args)
...         kwargs = deepcopy(kwargs)
...         return super().__call__(*args, **kwargs)
...
>>> c = CopyingMock(return_value=None)
>>> arg = set()
>>> c(arg)
>>> arg.add(1)
>>> c.assert_called_with(set())
>>> c.assert_called_with(arg)
Traceback (most recent call last):
    ...
AssertionError: Expected call: mock({1})
Actual call: mock(set())
>>> c.foo
<CopyingMock name='mock.foo' id='...'>

Cuando subclases Mock o MagicMock todos los atributos creados dinámicamente, y el return_value usará tu subclase automáticamente. Eso significa que todos los elementos secundarios de un CopyingMock también tendrán el tipo CopyingMock.

Anidando Parches

Usar parches como administradores de contexto es bueno, pero si haces varios parches, puedes terminar con instrucciones anidadas que se sangran cada vez más a la derecha:

>>> class MyTest(unittest.TestCase):
...
...     def test_foo(self):
...         with patch('mymodule.Foo') as mock_foo:
...             with patch('mymodule.Bar') as mock_bar:
...                 with patch('mymodule.Spam') as mock_spam:
...                     assert mymodule.Foo is mock_foo
...                     assert mymodule.Bar is mock_bar
...                     assert mymodule.Spam is mock_spam
...
>>> original = mymodule.Foo
>>> MyTest('test_foo').test_foo()
>>> assert mymodule.Foo is original

Con las funciones unittest cleanup y Métodos start y stop de patch podemos lograr el mismo efecto sin la sangría anidada. Un método auxiliar simple, create_patch, pone el parche en su lugar y devuelve el mock creado para nosotros:

>>> class MyTest(unittest.TestCase):
...
...     def create_patch(self, name):
...         patcher = patch(name)
...         thing = patcher.start()
...         self.addCleanup(patcher.stop)
...         return thing
...
...     def test_foo(self):
...         mock_foo = self.create_patch('mymodule.Foo')
...         mock_bar = self.create_patch('mymodule.Bar')
...         mock_spam = self.create_patch('mymodule.Spam')
...
...         assert mymodule.Foo is mock_foo
...         assert mymodule.Bar is mock_bar
...         assert mymodule.Spam is mock_spam
...
>>> original = mymodule.Foo
>>> MyTest('test_foo').run()
>>> assert mymodule.Foo is original

Mocking a un diccionario usando MagickMock

Es posible que desee simular un diccionario u otro objeto contenedor, registrando todo el acceso a él mientras todavía se comporta como un diccionario.

Podemos hacer esto con MagicMock, que se comportará como un diccionario, y usando side_effect para delegar el acceso del diccionario a un diccionario subyacente real que está bajo nuestro control.

Cuando se llama a los métodos __getitem__() y __setitem__() de nuestro MagicMock (acceso normal al diccionario), entonces se llama a side_effect con la clave (y en el caso de __setitem__ el valor también). También podemos controlar lo que se devuelve.

Después de que se haya utilizado el MagicMock podemos usar atributos como call_args_list para afirmar cómo se usó el diccionario:

>>> my_dict = {'a': 1, 'b': 2, 'c': 3}
>>> def getitem(name):
...      return my_dict[name]
...
>>> def setitem(name, val):
...     my_dict[name] = val
...
>>> mock = MagicMock()
>>> mock.__getitem__.side_effect = getitem
>>> mock.__setitem__.side_effect = setitem

Nota

Una alternativa al uso de MagicMock es usar Mock y solo proporcionar los métodos mágicos que desea específicamente:

>>> mock = Mock()
>>> mock.__getitem__ = Mock(side_effect=getitem)
>>> mock.__setitem__ = Mock(side_effect=setitem)

Una tercera opción es usar MagicMock pero pasando dict como el argumento spec (o spec_set) para que el MagicMock creado solo tenga métodos mágicos de diccionario disponibles:

>>> mock = MagicMock(spec_set=dict)
>>> mock.__getitem__.side_effect = getitem
>>> mock.__setitem__.side_effect = setitem

Con estas funciones de efectos secundarios en su lugar, el mock se comportará como un diccionario normal pero registrando el acceso. Incluso genera un KeyError si intenta acceder a una clave que no existe.

>>> mock['a']
1
>>> mock['c']
3
>>> mock['d']
Traceback (most recent call last):
    ...
KeyError: 'd'
>>> mock['b'] = 'fish'
>>> mock['d'] = 'eggs'
>>> mock['b']
'fish'
>>> mock['d']
'eggs'

Una vez utilizado, puede realizar aserciones sobre el acceso utilizando los métodos y atributos mock normales:

>>> mock.__getitem__.call_args_list
[call('a'), call('c'), call('d'), call('b'), call('d')]
>>> mock.__setitem__.call_args_list
[call('b', 'fish'), call('d', 'eggs')]
>>> my_dict
{'a': 1, 'b': 'fish', 'c': 3, 'd': 'eggs'}

Mock de subclases y sus atributos

Hay varias razones por las que es posible que desee crear subclases Mock Una razón podría ser agregar métodos auxiliares. Aquí hay un ejemplo simple:

>>> class MyMock(MagicMock):
...     def has_been_called(self):
...         return self.called
...
>>> mymock = MyMock(return_value=None)
>>> mymock
<MyMock id='...'>
>>> mymock.has_been_called()
False
>>> mymock()
>>> mymock.has_been_called()
True

El comportamiento estándar para las instancias Mock es que los atributos y los simulacros de valor devuelto son del mismo tipo que el simulacro en el que se accede a ellos. Esto garantiza que los atributos Mock son Mocks y los atributos MagicMock son MagicMocks 2. Por lo tanto, si está creando subclases para agregar métodos auxiliares, también estarán disponibles en los atributos y el valor devuelto mock de las instancias de su subclase.

>>> mymock.foo
<MyMock name='mock.foo' id='...'>
>>> mymock.foo.has_been_called()
False
>>> mymock.foo()
<MyMock name='mock.foo()' id='...'>
>>> mymock.foo.has_been_called()
True

A veces esto es inconveniente. Por ejemplo, un usuario [https://code.google.com/archive/p/mock/issues/105] está creando subclases de mock para crear un Twisted adaptor [https://twistedmatrix.com/documents/11.0.0/api/twisted.python.components.html]. Tener esto aplicado a los atributos también puede causar errores en realidad.

Mock (en todos sus sabores) utiliza un método llamado _get_child_mock para crear estos «sub-mocks» para atributos y valores devueltos. Puede evitar que la subclase se utilice para los atributos invalidando este método. La firma es que toma argumentos de palabra clave arbitrarios (**kwargs) que luego se pasan al constructor ficticio:

>>> class Subclass(MagicMock):
...     def _get_child_mock(self, /, **kwargs):
...         return MagicMock(**kwargs)
...
>>> mymock = Subclass()
>>> mymock.foo
<MagicMock name='mock.foo' id='...'>
>>> assert isinstance(mymock, Subclass)
>>> assert not isinstance(mymock.foo, Subclass)
>>> assert not isinstance(mymock(), Subclass)

2

Una excepción a esta regla son los mock no invocables. Los atributos usan la variante a la que se puede llamar porque, de lo contrario, los simulacros a los que no se puede llamar no podrían tener métodos a los que se puede llamar.

Importaciones de Mocking con patch.dict

Una situación en la que un mocking puede ser difícil es cuando tiene una importación local dentro de una función. Estos son más difíciles de simular porque no están usando un objeto del espacio de nombres del módulo que podemos revisar.

Por lo general, deben evitarse las importaciones locales. A veces se hacen para evitar dependencias circulares, para las que hay generalmente una manera mucho mejor de resolver el problema (refactorizar el código) o para evitar «costos iniciales» retrasando la importación. Esto también se puede resolver de mejores maneras que una importación local incondicional (almacenar el módulo como una clase o atributo de módulo y solo hacer la importación en el primer uso).

Aparte de eso, hay una manera de usar mock para afectar los resultados de una importación. La importación obtiene un objeto del diccionario sys.modules. Tenga en cuenta que obtiene un objeto, que no tiene por qué ser un módulo. La importación de un módulo por primera vez da como resultado que un objeto de módulo se coloque en sys.modules, por lo que normalmente cuando importa algo, recupera un módulo. Sin embargo, este no tiene por qué ser el caso.

Esto significa que puede usar patch.dict() para temporalmente poner un mock en su lugar sobre sys.modules. Cualquier importación mientras este parche está activo recuperará el mock. Cuando el parche está completo (la función decorada sale, el cuerpo de la instrucción with está completo o se llama a patcher.stop()) entonces lo que había anteriormente se restaurará de forma segura.

Aquí hay un ejemplo de mock del módulo “fooble”.

>>> import sys
>>> mock = Mock()
>>> with patch.dict('sys.modules', {'fooble': mock}):
...    import fooble
...    fooble.blob()
...
<Mock name='mock.blob()' id='...'>
>>> assert 'fooble' not in sys.modules
>>> mock.blob.assert_called_once_with()

Como puede ver, el import fooble tiene éxito, pero al salir no queda ningún “fooble” en sys.modules.

Esto también funciona para el formulario from module import name:

>>> mock = Mock()
>>> with patch.dict('sys.modules', {'fooble': mock}):
...    from fooble import blob
...    blob.blip()
...
<Mock name='mock.blob.blip()' id='...'>
>>> mock.blob.blip.assert_called_once_with()

Con un poco más de trabajo también puede simular las importaciones de paquetes:

>>> mock = Mock()
>>> modules = {'package': mock, 'package.module': mock.module}
>>> with patch.dict('sys.modules', modules):
...    from package.module import fooble
...    fooble()
...
<Mock name='mock.module.fooble()' id='...'>
>>> mock.module.fooble.assert_called_once_with()

Seguimiento del orden de las llamadas y de las aserciones de llamadas menos detalladas

La clase Mock le permite realizar un seguimiento del orden de las llamadas a métodos en sus objetos mock a través del atributo method_calls. Esto no le permite rastrear el orden de las llamadas entre objetos simulados separados, sin embargo, podemos usar mock_calls para lograr el mismo efecto.

Debido a que los mocks rastrean las llamadas a mocks secundarios en mock_calls, y el acceso a un atributo arbitrario de un mock crea un mock secundario, podemos crear nuestros mocks separados de uno primario. Las llamadas a esos mocks hijos se grabarán, en orden, en el mock_calls del padre:

>>> manager = Mock()
>>> mock_foo = manager.foo
>>> mock_bar = manager.bar

>>> mock_foo.something()
<Mock name='mock.foo.something()' id='...'>
>>> mock_bar.other.thing()
<Mock name='mock.bar.other.thing()' id='...'>

>>> manager.mock_calls
[call.foo.something(), call.bar.other.thing()]

A continuación, podemos realizar afirmaciones sobre las llamadas, incluido el orden, comparando con el atributo mock_calls en el mock administrador:

>>> expected_calls = [call.foo.something(), call.bar.other.thing()]
>>> manager.mock_calls == expected_calls
True

Si patch está creando y poniendo en su lugar, sus mocks, puede adjuntarlos a un mock administrador usando el método attach_mock() . Después de adjuntar las llamadas se registrarán en mock_calls del administrador.

>>> manager = MagicMock()
>>> with patch('mymodule.Class1') as MockClass1:
...     with patch('mymodule.Class2') as MockClass2:
...         manager.attach_mock(MockClass1, 'MockClass1')
...         manager.attach_mock(MockClass2, 'MockClass2')
...         MockClass1().foo()
...         MockClass2().bar()
<MagicMock name='mock.MockClass1().foo()' id='...'>
<MagicMock name='mock.MockClass2().bar()' id='...'>
>>> manager.mock_calls
[call.MockClass1(),
call.MockClass1().foo(),
call.MockClass2(),
call.MockClass2().bar()]

Si se han realizado muchas llamadas, pero solo está interesado en una secuencia particular de ellas, entonces una alternativa es usar el método assert_has_calls() . Esto toma una lista de llamadas (construidas con el objeto call). Si esa secuencia de llamadas sobre mock_calls, la aserción se realiza correctamente.

>>> m = MagicMock()
>>> m().foo().bar().baz()
<MagicMock name='mock().foo().bar().baz()' id='...'>
>>> m.one().two().three()
<MagicMock name='mock.one().two().three()' id='...'>
>>> calls = call.one().two().three().call_list()
>>> m.assert_has_calls(calls)

Aunque la llamada encadenada m.one().two().three() no son las únicas llamadas que se han realizado al mock, la aserción aún tiene éxito.

A veces, un mock puede tener varias llamadas, y solo le interesa afirmar sobre algunas de esas llamadas. Puede que ni siquiera importe el pedido. En este caso, puede pasar any_order=True a assert_has_calls:

>>> m = MagicMock()
>>> m(1), m.two(2, 3), m.seven(7), m.fifty('50')
(...)
>>> calls = [call.fifty('50'), call(1), call.seven(7)]
>>> m.assert_has_calls(calls, any_order=True)

Coincidencia de argumentos más compleja

Usando el mismo concepto básico que ANY podemos implementar comparadores para hacer afirmaciones más complejas en objetos usados como argumentos para mocks.

Supongamos que esperamos que algún objeto se pase a un mock que, por defecto, se compara igual en función de la identidad del objeto (que es el valor predeterminado de Python para las clases definidas por el usuario). Para usar assert_called_with() tendríamos que pasar exactamente el mismo objeto. Si solo estamos interesados en algunos de los atributos de este objeto, podemos crear un comparador que verifique estos atributos por nosotros.

Puede ver en este ejemplo cómo una llamada “estándar” a assert_called_with no es suficiente:

>>> class Foo:
...     def __init__(self, a, b):
...         self.a, self.b = a, b
...
>>> mock = Mock(return_value=None)
>>> mock(Foo(1, 2))
>>> mock.assert_called_with(Foo(1, 2))
Traceback (most recent call last):
    ...
AssertionError: Expected: call(<__main__.Foo object at 0x...>)
Actual call: call(<__main__.Foo object at 0x...>)

Una función de comparación para nuestra clase Foo podría verse así:

>>> def compare(self, other):
...     if not type(self) == type(other):
...         return False
...     if self.a != other.a:
...         return False
...     if self.b != other.b:
...         return False
...     return True
...

Y un objeto comparador que puede usar funciones de comparación como esta para su operación de igualdad se vería así:

>>> class Matcher:
...     def __init__(self, compare, some_obj):
...         self.compare = compare
...         self.some_obj = some_obj
...     def __eq__(self, other):
...         return self.compare(self.some_obj, other)
...

Poniendo todo esto junto:

>>> match_foo = Matcher(compare, Foo(1, 2))
>>> mock.assert_called_with(match_foo)

El Matcher es instanciado con nuestra función de comparación y el objeto Foo con el que queremos comparar. En assert_called_with se llamará al método de igualdad Matcher, que compara el objeto con el que se llamó al mock con el que creamos nuestro matcher. Si coinciden, entonces pasa assert_called_with, y si no lo hacen, se generará un AssertionError:

>>> match_wrong = Matcher(compare, Foo(3, 4))
>>> mock.assert_called_with(match_wrong)
Traceback (most recent call last):
    ...
AssertionError: Expected: ((<Matcher object at 0x...>,), {})
Called with: ((<Foo object at 0x...>,), {})

Con un poco de ajuste, podría hacer que la función de comparación genere el AssertionError directamente y proporcione un mensaje de falla más útil.

A partir de la versión 1.5, la biblioteca de pruebas de Python PyHamcrest [https://pyhamcrest.readthedocs.io/] proporciona una funcionalidad similar, que puede ser útil aquí, en la forma de su comparador de igualdad (hamcrest.library.integration.match_equality [https://pyhamcrest.readthedocs.io/en/release-1.8/integration/#module-hamcrest.library.integration.match_equality]).

2to3 - Traducción de código Python 2 a 3

2to3 es un programa de Python que lee el código fuente de Python 2.x y aplica una serie de fixers para transformarlo en un código válido de Python 3.x. La biblioteca estándar contiene un amplio conjunto de arreglos que manejarán casi todo el código. Biblioteca de soporte 2to3 lib2to3 es, sin embargo, una biblioteca flexible y genérica, por lo que es posible escribir sus propios arreglos para 2to3.

Usando 2to3

2to3 generalmente estará instalada con el interprete de Python como un script. También se encuentra ubicada en el directorio Tools/scripts en la raíz de Python.

Los argumentos básicos de 2to3 son una lista de archivos o directorios a convertir. Los directorios se recorren recursivamente en búsqueda de archivos en Python.

Este es un ejemplo de un archivo en Python 2.x, example.py:

def greet(name):
    print "Hello, {0}!".format(name)
print "What's your name?"
name = raw_input()
greet(name)

Puede ser convertido a Python 3.x vía 2to3 desde la línea de comandos:

$ 2to3 example.py

Se imprime un diff del archivo fuente original. 2to3 también puede escribir las modificaciones necesarias directamente en el archivo fuente. (Se hace una copia de respaldo del archivo original a menos que se proporcione -n.) La escritura de los cambios se habilita con la opción -w:

$ 2to3 -w example.py

Después de la conversión, example.py se ve de la siguiente manera:

def greet(name):
    print("Hello, {0}!".format(name))
print("What's your name?")
name = input()
greet(name)

Los comentarios y la identación exacta se conservan durante todo el proceso de conversión.

Por defecto, 2to3 corre un conjunto de fixers predefinidos. La opción -l lista todos los fixers posibles. Se puede pasar un conjunto explícito de fixers con la opción -x. Asimismo la opción -x deshabilita el fixer que se explicita. El siguiente ejemplo corre solo solo los fixers imports y has_key:

$ 2to3 -f imports -f has_key example.py

Este comando corre todos los fixers excepto el apply fixer:

$ 2to3 -x apply example.py

Algunos fixers son explícitos, esto quiere decir que no corren por defecto y deben ser listados en la línea de comando para que se ejecuten. Acá, además de los fixers por defectos, se ejecuta el fixer idioms:

$ 2to3 -f all -f idioms example.py

Puede observarse que pasar all habilita todos los fixers por defecto.

Algunas veces 2to3 va a encontrar algo en su código que necesita ser modificado, pero 2to3 no puede hacerlo automáticamente. En estos casos, 2to3 va a imprimir una advertencia debajo del diff del archivo. Deberá tomar nota de la advertencia para obtener un código compatible con 3.x.

2to3 también puede refactorizar doctest. Para habilitar este modo, use la opción -d. Tenga en cuenta que solo los doctest serán refactorizados. Esto tampoco requiere que el módulo sea válido en Python. Por ejemplo, doctest de ejemplo en un documento reST también pueden ser refactorizados con esta opción.

La opción -v habilita la salida de más información en el proceso de conversión.

Dado que algunas declaraciones de impresión se pueden analizar como llamadas a funciones o declaraciones, 2to3 no siempre puede leer archivos que contienen la función de impresión. Cuando 2to3 detecta la presencia de la directiva del compilador from __future__ import print_function, modifica su gramática interna para interpretar print() como una función. Este cambio también se puede habilitar manualmente con la opción -p. Utilice -p para ejecutar correctores en el código que ya tiene sus declaraciones de impresión convertidas. También -e puede usarse para hacer exec() una función.

La opción -o o la opción --output-dir permiten designar un directorio alternativo para que se guarden los archivos procesados. La opción -n es necesaria ya que los archivos de respaldo no tienen sentido cuando no se sobreescriben los archivos originales.

Nuevo en la versión 3.2.3: Se agregó la opción :option:` !-o`.

La opción -W o --write-unchanged-files le dice a 2to3 que siempre escriba archivos de salida, incluso si no se requieren hacer cambios en el archivo. Esto es muy útil con la opción -o para que copie el árbol completo de código Python con su conversión de un directorio a otro. Esta opción incluye a la opción -w ya que no tendría sentido de otra manera.

Nuevo en la versión 3.2.3: Se agregó la opción -W.

La opción --add-suffix agrega un texto al final de todos los nombres de archivo. La opción -n es necesaria, ya que las copias de respaldo no son necesarias cuando escribimos a un archivo con distinto nombre. Ejemplo:

$ 2to3 -n -W --add-suffix=3 example.py

Hará que se escriba una archivo convertido con el nombre example.py3.

Nuevo en la versión 3.2.3: Se agrega la opción --add-suffix.

Para convertir un proyecto entero de un árbol de directorios a otro use:

$ 2to3 --output-dir=python3-version/mycode -W -n python2-version/mycode

Fixers

Cada paso de la transformación del código es encapsulado en un fixer. El comando 2to3 -l los lista. Como se explicó arriba, cada uno de estos puede habilitarse o deshabilitarse individualmente. En esta sección se los describe más detalladamente.

apply

Elimina el uso de apply(). Por ejemplo apply(function, *args, **kwargs) es convertido a function(*args, **kwargs).

asserts

Reemplaza los nombre de método unittest en desuso por los correctos.

De

A

failUnlessEqual(a, b)

assertEqual(a, b)

assertEquals(a, b)

assertEqual(a, b)

failIfEqual(a, b)

assertNotEqual(a, b)

assertNotEquals(a, b)

assertNotEqual(a, b)

failUnless(a)

assertTrue(a)

assert_(a)

assertTrue(a)

failIf(a)

assertFalse(a)

failUnlessRaises(exc, cal)

assertRaises(exc, cal)

failUnlessAlmostEqual(a, b)

assertAlmostEqual(a, b)

assertAlmostEquals(a, b)

assertAlmostEqual(a, b)

failIfAlmostEqual(a, b)

assertNotAlmostEqual(a, b)

assertNotAlmostEquals(a, b)

assertNotAlmostEqual(a, b)

basestring

Convierte basestring a str.

buffer

Convierte buffer a memoryview. Este fixer es opcional porque la API memoryview es similar pero no exactamente la misma que la del buffer.

dict

Corrige los métodos de iteración del diccionario, dict.iteritems() es convertido a dict.items(), dict.iterkeys() a dict.keys(), y dict.itervalues() a dict.values(). Del mismo modo, dict.viewitems(), dict.viewkeys() y dict.viewvalues() son convertidos respectivamente a dict.items(), dict.keys() y dict.values(). También incluye los usos existentes de dict.items(), dict.keys(), y dict.values() en una llamada a list.

except

Convierte except X, T a except X as T.

exec

Convierte la declaración exec a la función exec().

execfile

Elimina el uso de la función execfile(). El argumento para execfile() es encapsulado para las funciones open(), compile(), y exec().

exitfunc

Cambia la declaración de sys.exitfunc para usar el módulo atexit.

filter

Encapsula la función filter() usando una llamada para la clase list.

funcattrs

Corrige los atributos de la función que fueron renombrados. Por ejemplo, my_function.func_closure es convertido a my_function.__closure__.

future

Elimina la declaración from __future__ import new_feature.

getcwdu

Renombra la función os.getcwdu() a os.getcwd().

has_key

Cambia dict.has_key(key) a key in dict.

idioms

Este fixer opcional ejecuta varias transformaciones que tornan el código Python más idiomático. Comparaciones de tipo como type(x) is SomeClass y type(x) == SomeClass son convertidas a isinstance(x, SomeClass).``while 1`` cambia a while True. Este fixer también intenta hacer uso de sorted() en los lugares apropiados. Por ejemplo, en este bloque:

L = list(some_iterable)
L.sort()

es convertido a

L = sorted(some_iterable)

import

Detecta las importaciones entre hermanos y las convierte en importaciones relativas.

imports

Maneja los cambios de nombre de módulo en la librería estándar.

imports2

Maneja otros cambios de nombre de módulo en la biblioteca estándar. Está separada del fixer imports solo por motivos de limitaciones técnicas.

input

Convierte input(prompt) a eval(input(prompt)).

intern

Convierte intern() a sys.intern().

isinstance

Corrige tipos duplicados en el segundo argumento de isinstance(). Por ejemplo,``isinstance(x, (int, int))`` es convertido a isinstance(x, int) y isinstance(x, (int, float, int)) es convertido a isinstance(x, (int, float)).

itertools_imports

Elimina importaciones de itertools.ifilter(), itertools.izip(), y itertools.imap(). Importación de itertools.ifilterfalse() también se cambian a itertools.filterfalse().

itertools

Cambia el uso de itertools.ifilter(), itertools.izip(), y itertools.imap() para sus equivalentes integrados itertools.ifilterfalse() es cambiado a itertools.filterfalse().

long

Renombra long a int.

map

Encapsula map() en una llamada a list. También cambia map(None, x) a list(x). Usando``from future_builtins import map`` se deshabilita este fixer.

metaclass

Convierte la vieja sintaxis de metaclase (__metaclass__ = Meta en el cuerpo de la clase) a la nueva sintaxis (class X(metaclass=Meta)).

methodattrs

Corrige nombres de atributos de métodos antiguos. Por ejemplo, meth.im_func is convertido a meth.__func__.

ne

Convierte la antigua sintaxis no-igual, <>, a !=.

next

Convierte el uso de métodos iteradores next() para la función next(). También renombra métodos next() a __next__().

nonzero

Renames definitions of methods called __nonzero__() to __bool__().

numliterals

Convierte literales octales a la nueva sintaxis.

operator

Convierte llamadas para varias funciones en el módulo operator a otras, pero equivalentes, llamadas de funciones. Cuando es necesario, se agregan las declaraciones import apropiadas, por ejemplo import collections.abc. Se realizan los siguientes mapeos:

De

A

operator.isCallable(obj)

callable(obj)

operator.sequenceIncludes(obj)

operator.contains(obj)

operator.isSequenceType(obj)

isinstance(obj, collections.abc.Sequence)

operator.isMappingType(obj)

isinstance(obj, collections.abc.Mapping)

operator.isNumberType(obj)

isinstance(obj, numbers.Number)

operator.repeat(obj, n)

operator.mul(obj, n)

operator.irepeat(obj, n)

operator.imul(obj, n)

paren

Agrega los paréntesis extra donde sean necesarios en las listas de comprensión. Por ejemplo [x for x in 1, 2] se convierte en [x for x in (1, 2)].

print

Convierte la declaración print en la función print().

raise

Convierte raise E, V a raise E(V), y raise E, V, T a raise E(V).with_traceback(T). SI E es una tupla, la conversión será incorrecta porque sustituir tuplas por excepciones fue eliminado en Python 3.0.

raw_input

Conviertes raw_input() to input().

reduce

Maneja el movimiento de reduce() a functools.reduce().

reload

Convierte reload() a importlib.reload().

renames

Cambia sys.maxint a sys.maxsize.

repr

Sustituye el backtick repr por la función repr().

set_literal

Sustituye el uso de la clase constructora set por su literal. Este fixer es opcional.

standarderror

Renombra StandardError a Exception.

sys_exc

Cambia los sys.exc_value, sys.exc_type, sys.exc_traceback en desuso para usar la función sys.exc_info().

throw

Corrige el cambio de la API en el método generador throw().

tuple_params

Elimina el desempaquetamiento implícito del parámetro de tupla. Este fixer inserta variables temporarias.

types

Corrige el código roto por la remoción de algunos miembros en el módulo types.

unicode

Renombra unicode a str.

urllib

Maneja el renombramiento de los módulos urllib y urllib2 para el paquete urllib.

ws_comma

Remueve el exceso de espacios blancos de los ítems separados por coma. Este fixer es opcional.

xrange

Renombra xrange() a range() y encapsula la llamada a la función existente range() con list.

xreadlines

Cambia for x in file.xreadlines() por for x in file.

zip

Encapsula el uso de la función zip() en una llamada a la clase list. Esto está deshabilitado cuando from future_builtins import zip aparece.

lib2to3 - librería 2to3

Código fuente: Lib/lib2to3/ [https://github.com/python/cpython/tree/3.9/Lib/lib2to3/]

Obsoleto desde la versión 3.10: Python 3.9 cambiará a un analizador PEG (ver PEP 617 [https://www.python.org/dev/peps/pep-0617]), y Python 3.10 puede incluir una nueva sintaxis de lenguaje que no es analizable por el analizador LL(1) de lib2to3. El módulo lib2to3 puede eliminarse de la biblioteca estándar en una versión futura de Python. Considere alternativas de terceros como LibCST [https://libcst.readthedocs.io/] o parso [https://parso.readthedocs.io/].

Nota

La API del módulo lib2to3 debe considerarse inestable y puede cambiar drásticamente en el futuro.

test — Paquete de pruebas de regresión para Python

Nota

El paquete test está destinado solo para uso interno de Python. Está documentado para beneficio de los desarrolladores principales de Python. Se desaconseja el uso de este paquete fuera de la biblioteca estándar de Python, ya que el código mencionado aquí puede cambiar o eliminarse sin previo aviso entre versiones de Python.

El paquete test contiene todas las pruebas de regresión para Python, así como los módulos test.support y test.regrtest. Se utiliza test.support para mejorar sus pruebas, mientras que test.regrtest maneja el conjunto de pruebas.

Cada módulo en el paquete test cuyo nombre comienza con test_ es un conjunto de pruebas para un módulo o característica específica. Todas las pruebas nuevas deben escribirse usando el módulo unittest o doctest. Algunas pruebas anteriores se escriben utilizando un estilo de prueba «tradicional» que compara la salida impresa con sys.stdout; este estilo de prueba se considera obsoleto.

Ver también

Módulo unittest

Escritura de pruebas de regresión de PyUnit.

Módulo doctest

Pruebas integradas en cadenas de caracteres de documentación.

Escritura de pruebas unitarias para el paquete test

Se prefiere que las pruebas que utilizan el módulo unittest sigan algunas pautas. Una es nombrar el módulo de prueba comenzándolo con test_ y terminarlo con el nombre del módulo que se está probando. Los métodos de prueba en el módulo de prueba deben comenzar con test_ y terminar con una descripción de lo que el método está probando. Esto es necesario para que el controlador de prueba reconozca los métodos como métodos de prueba. Por lo tanto, no se debe incluir una cadena de caracteres de documentación para el método. Se debe usar un comentario (como # Tests function returns only True or False) para proporcionar documentación para los métodos de prueba. Esto se hace porque las cadenas de documentación se imprimen si existen y, por lo tanto, no se indica qué prueba se está ejecutando.

A menudo se usa una plantilla básica:

import unittest
from test import support

class MyTestCase1(unittest.TestCase):

    # Only use setUp() and tearDown() if necessary

    def setUp(self):
        ... code to execute in preparation for tests ...

    def tearDown(self):
        ... code to execute to clean up after tests ...

    def test_feature_one(self):
        # Test feature one.
        ... testing code ...

    def test_feature_two(self):
        # Test feature two.
        ... testing code ...

    ... more test methods ...

class MyTestCase2(unittest.TestCase):
    ... same structure as MyTestCase1 ...

... more test classes ...

if __name__ == '__main__':
    unittest.main()

Este patrón de código permite que el conjunto de pruebas sea ejecutado por test.regrtest, como un script que admite la CLI unittest, o mediante la CLI python -m unittest.

El objetivo de las pruebas de regresión es intentar romper el código. Esto lleva a algunas pautas a seguir:

El conjunto de pruebas debe ejercer todas las clases, funciones y constantes. Esto incluye no solo la API externa que se presentará al mundo exterior sino también el código «privado».

Se prefiere la prueba de caja blanca (examinar el código que se prueba cuando se escriben las pruebas). Las pruebas de caja negra (probar solo la interfaz de usuario publicada) no son lo suficientemente completas como para garantizar que se prueben todos los casos límite y límite.

Asegúrese de que todos los valores posibles son probados, incluidos los no válidos. Esto asegura que no solo todos los valores válidos sean aceptables, sino que los valores incorrectos se manejen correctamente.

Agote tantas rutas de código cómo sea posible. Pruebe donde se produce la ramificación y, por lo tanto, adapte la entrada para asegurarse de que se toman muchas rutas diferentes a través del código.

Añada una prueba explícita para cualquier error descubierto para el código probado. Esto asegurará que el error no vuelva a aparecer si el código se cambia en el futuro.

Asegúrese de limpiar después de sus pruebas (así como cerrar y eliminar todos los archivos temporales).

Si una prueba depende de una condición específica del sistema operativo, verifique que la condición ya existe antes de intentar la prueba.

Importe la menor cantidad de módulos posible y hágalo lo antes posible. Esto minimiza las dependencias externas de las pruebas y también minimiza el posible comportamiento anómalo de los efectos secundarios de importar un módulo.

Intente maximizar la reutilización del código. En ocasiones, las pruebas variarán en algo tan pequeño como qué tipo de entrada se utiliza. Minimice la duplicación de código usando como clase base una clase de prueba básica con una clase que especifique la entrada:

class TestFuncAcceptsSequencesMixin:

    func = mySuperWhammyFunction

    def test_func(self):
        self.func(self.arg)

class AcceptLists(TestFuncAcceptsSequencesMixin, unittest.TestCase):
    arg = [1, 2, 3]

class AcceptStrings(TestFuncAcceptsSequencesMixin, unittest.TestCase):
    arg = 'abc'

class AcceptTuples(TestFuncAcceptsSequencesMixin, unittest.TestCase):
    arg = (1, 2, 3)

Cuando use este patrón, recuerde que todas las clases que heredan unittest.TestCase se ejecutan como pruebas. La clase Mixin en el ejemplo anterior no tiene ningún dato y, por lo tanto, no se puede ejecutar solo, por lo tanto, no hereda de unittest.TestCase.

Ver también

Desarrollo dirigido por pruebas (Test Driven Development)

Un libro de Kent Beck sobre pruebas de escritura antes del código.

Ejecución de pruebas utilizando la interfaz de línea de comandos

El paquete test puede ejecutarse como un script para controlar el conjunto de pruebas de regresión de Python, gracias a la opción -m : python -m test. Internamente, se utiliza test.regrtest; la llamada python -m test.regrtest utilizada en versiones anteriores de Python todavía funciona. Ejecuta el script por sí mismo automáticamente y comienza a ejecutar todas las pruebas de regresión en el paquete test.regrtest. Lo hace buscando todos los módulos en el paquete cuyo nombre comienza con ``test_`, importándolos y ejecutando la función test_main() si está presente o cargando las pruebas a través de unittest.TestLoader.loadTestsFromModule si test_main no existe. Los nombres de las pruebas a ejecutar también se pueden pasar al script. La especificación de una prueba de regresión única (python -m test test_spam) minimizará la salida y solo imprimirá si la prueba pasó o no.

Ejecutando test directamente permite establecer qué recursos están disponibles para que se usen las pruebas. Para ello, use la opción de línea de comandos -u. Al especificar all como el valor para la opción -u se habilitan todos los recursos posibles: python -m test -uall. Si se desean todos los recursos menos uno (un caso más común), se puede enumerar una lista de recursos separados por comas que no se desean después de all. El comando python -m test -uall,-audio,-largefile ejecutará test con todos los recursos excepto los recursos audio y largefile. Para obtener una lista de todos los recursos y más opciones de línea de comandos, ejecute python -m test -h.

Algunas otras formas de ejecutar las pruebas de regresión dependen de en qué plataforma se ejecuten las pruebas. En Unix, puede ejecutar make test en el directorio de nivel superior donde se construyó Python. En Windows, ejecutar rt.bat desde su directorio PCbuild ejecutará todas las pruebas de regresión.

test.support — Utilidades para el conjunto de pruebas de Python

El módulo test.support proporciona soporte para el conjunto de pruebas de regresión de Python.

Nota

test.support no es un módulo público. Está documentado aquí para ayudar a los desarrolladores de Python a escribir pruebas. La API de este módulo está sujeta a cambios sin problemas de compatibilidad con versiones anteriores entre versiones.

Este módulo define las siguientes excepciones:

exception test.support.TestFailed

Excepción que se lanzará cuando una prueba falle. Esto está en desuso a favor de pruebas basadas en unittesty en métodos de aserción unittest.TestCase

exception test.support.ResourceDenied

La subclase de unittest.SkipTest. Se lanza cuando un recurso (como una conexión de red) no está disponible. Lanzado por la función requires().

El módulo test.support define las siguientes constantes:

test.support.verbose

True cuando la salida detallada está habilitada. Debe verificarse cuando se desea información más detallada sobre una prueba en ejecución. verbose está establecido por test.regrtest.

test.support.is_jython

True si el intérprete en ejecución es Jython.

test.support.is_android

True si el sistema es Android.

test.support.unix_shell

Ruta del shell si no está en Windows; de otra manera None.

test.support.FS_NONASCII

Un carácter no codificable ASCII codificable por os.fsencode().

test.support.TESTFN

Establecido a un nombre que sea seguro de usar como nombre de un archivo temporal. Cualquier archivo temporal que se cree debe cerrarse y desvincularse (eliminarse).

test.support.TESTFN_UNICODE

Establecido un nombre que no sea ASCII para un archivo temporal.

test.support.TESTFN_ENCODING

Establecido en sys.getfilesystemencoding().

test.support.TESTFN_UNENCODABLE

Establecido un nombre de archivo (tipo str) que no se pueda codificar mediante la codificación del sistema de archivos en modo estricto. Puede ser None si no es posible generar dicho nombre de archivo.

test.support.TESTFN_UNDECODABLE

Establecido un nombre de archivo (tipo de bytes) que no pueda descodificarse mediante la codificación del sistema de archivos en modo estricto. Puede ser None si no es posible generar dicho nombre de archivo.

test.support.TESTFN_NONASCII

Establecido un nombre de archivo que contiene el carácter FS_NONASCII.

test.support.LOOPBACK_TIMEOUT

Tiempo de espera en segundos para las pruebas que utilizan un servidor de red que escucha en la interfaz local de loopback de la red como 127.0.0.1.

El tiempo de espera es lo suficientemente largo para evitar el fracaso de la prueba: tiene en cuenta que el cliente y el servidor pueden ejecutarse en diferentes hilos o incluso en diferentes procesos.

El tiempo de espera debe ser lo suficientemente largo para los métodos connect(), recv() y send() de socket.socket.

Su valor por defecto es de 5 segundos.

Ver también INTERNET_TIMEOUT.

test.support.INTERNET_TIMEOUT

Tiempo de espera en segundos para las solicitudes de red que van a Internet.

El tiempo de espera es lo suficientemente corto como para evitar que una prueba espere demasiado tiempo si la solicitud de Internet se bloquea por cualquier motivo.

Normalmente, un tiempo de espera utilizando INTERNET_TIMEOUT no debería marcar una prueba como fallida, sino que debería omitir la prueba: ver transient_internet().

Su valor por defecto es de 1 minuto.

Ver también LOOPBACK_TIMEOUT.

test.support.SHORT_TIMEOUT

Tiempo de espera en segundos para marcar una prueba como fallida si la prueba tarda «demasiado».

El valor del tiempo de espera depende de la opción de línea de comandos regrtest --timeout.

Si una prueba que utiliza SHORT_TIMEOUT empieza a fallar aleatoriamente en buildbots lentos, utilice en su lugar LONG_TIMEOUT.

Su valor por defecto es de 30 segundos.

test.support.LONG_TIMEOUT

Tiempo de espera en segundos para detectar cuando se cuelga una prueba.

Es lo suficientemente largo como para reducir el riesgo de fracaso de la prueba en los buildbots de Python más lentos. No debe utilizarse para marcar una prueba como fallida si la prueba tarda «demasiado». El valor del tiempo de espera depende de la opción de línea de comandos regrtest --timeout.

Su valor por defecto es de 5 minutos.

Ver también LOOPBACK_TIMEOUT, INTERNET_TIMEOUT y SHORT_TIMEOUT.

test.support.SAVEDCWD

Establecido os.getcwd().

test.support.PGO

Establecido cuando se pueden omitir las pruebas cuando no son útiles para PGO.

test.support.PIPE_MAX_SIZE

Una constante que probablemente sea más grande que el tamaño del búfer de la tubería (pipe) del sistema operativo subyacente, para bloquear las escrituras.

test.support.SOCK_MAX_SIZE

Una constante que probablemente sea más grande que el tamaño del búfer del socket del sistema operativo subyacente para bloquear las escrituras.

test.support.TEST_SUPPORT_DIR

Establecido en el directorio de nivel superior que contiene test.support.

test.support.TEST_HOME_DIR

Establecido en el directorio de nivel superior para el paquete de prueba.

test.support.TEST_DATA_DIR

Establecido en el directorio data dentro del paquete de prueba.

test.support.MAX_Py_ssize_t

Establecido sys.maxsize para pruebas de gran memoria.

test.support.max_memuse

Establecido por set_memlimit() como límite de memoria para pruebas de memoria grande. Limitado por MAX_Py_ssize_t.

test.support.real_max_memuse

Establecido por set_memlimit() como límite de memoria para pruebas de memoria grande. No limitado por MAX_Py_ssize_t.

test.support.MISSING_C_DOCSTRINGS

Retorna True si se ejecuta en CPython, no en Windows, y la configuración no está configurada con WITH_DOC_STRINGS.

test.support.HAVE_DOCSTRINGS

Verifica la presencia de cadenas de documentos (docstrings).

test.support.TEST_HTTP_URL

Define la URL de un servidor HTTP dedicado para las pruebas de red.

test.support.ALWAYS_EQ

Objeto que es igual a cualquier cosa. Se utiliza para probar la comparación de tipos mixtos.

test.support.NEVER_EQ

Objeto que no es igual a nada (incluso a ALWAYS_EQ). Se utiliza para probar la comparación de tipos mixtos.

test.support.LARGEST

Objeto que es mayor que cualquier cosa (excepto a sí mismo). Se utiliza para probar la comparación de tipos mixtos.

test.support.SMALLEST

Objeto que es menor que cualquier cosa (excepto él mismo). Se utiliza para probar la comparación de tipos mixtos.

El módulo test.support define las siguientes funciones:

test.support.forget(module_name)

Elimina el módulo llamado module_name de sys.modules y elimina los archivos compilados por bytes del módulo.

test.support.unload(name)

Elimina name de sys.modules.

test.support.unlink(filename)

Call os.unlink() on filename. On Windows platforms, this is wrapped with a wait loop that checks for the existence of the file.

test.support.rmdir(filename)

Llama a os.rmdir() en filename. En las plataformas Windows, esto está envuelto con un ciclo de espera que verifica la existencia del archivo.

test.support.rmtree(path)

Llama a shutil.rmtree() en path o os.lstat() y os.rmdir() para eliminar una ruta y su contenido. En las plataformas Windows, esto está envuelto con un ciclo de espera que verifica la existencia de los archivos.

test.support.make_legacy_pyc(source)

Mueve un archivo pyc de PEP 3147 [https://www.python.org/dev/peps/pep-3147]/PEP 488 [https://www.python.org/dev/peps/pep-0488] a su ubicación heredada y retorna la ruta del sistema de archivos al archivo de pyc heredado. El valor de origen es la ruta del sistema de archivos al archivo fuente. No es necesario que exista, sin embargo, debe existir el archivo PEP 3147/488 pyc.

test.support.is_resource_enabled(resource)

Retorna True si resource está habilitado y disponible. La lista de recursos disponibles solo se establece cuando test.regrtest está ejecutando las pruebas.

test.support.python_is_optimized()

Retorna True si Python no fue construido con -O0 o -Og.

test.support.with_pymalloc()

Retorna _testcapi.WITH_PYMALLOC.

test.support.requires(resource, msg=None)

Lanza ResourceDenied si resource no está disponible. msg es el argumento para ResourceDenied si se lanza. Siempre retorna True si es invocado por una función cuyo __name__ es '__main__'. Se usa cuando se ejecutan pruebas por test.regrtest.

test.support.system_must_validate_cert(f)

Lanza unittest.SkipTest en fallos de validación de certificación TLS.

test.support.sortdict(dict)

Retorna una representación del diccionario con las claves ordenadas.

test.support.findfile(filename, subdir=None)

Retorna la ruta al archivo llamado filename. Si no se encuentra ninguna coincidencia, se retorna filename. Esto no equivale a un fallo, ya que podría ser la ruta al archivo.

La configuración subdir indica una ruta relativa a utilizar para encontrar el archivo en lugar de buscar directamente en los directorios de ruta.

test.support.create_empty_file(filename)

Crea un archivo vacío con filename. Si ya existe, truncarlo.

test.support.fd_count()

Cuenta el número de descriptores de archivo abiertos.

test.support.match_test(test)

Hace coincidir test con los patrones establecidos en set_match_tests().

test.support.set_match_tests(patterns)

Define una prueba de coincidencia con una expresión regular patterns.

test.support.run_unittest(*classes)

Ejecuta subclases unittest.TestCase pasadas a la función. La función escanea las clases en busca de métodos que comiencen con el prefijo test_ y ejecuta las pruebas individualmente.

También está permitido pasar cadenas de caracteres como parámetros; Estas deberían ser claves en sys.modules. Cada módulo asociado será escaneado por unittest.TestLoader.loadTestsFromModule(). Esto generalmente se ve en la siguiente función test_main():

def test_main():
    support.run_unittest(__name__)

Esto ejecutará todas las pruebas definidas en el módulo nombrado.

test.support.run_doctest(module, verbosity=None, optionflags=0)

Ejecuta doctest.testmod() en module dado. Retorna (failure_count, test_count).

Si verbosity es None, la doctest.testmod() se ejecuta con verbosity establecido en verbose. De lo contrario, se ejecuta con verbosidad establecida en None. optionflags se pasa como optionflags to doctest.testmod().

test.support.setswitchinterval(interval)

Establecido sys.setswitchinterval() en el intervalo dado. Define un intervalo mínimo para los sistemas Android para evitar que el sistema se cuelgue.

test.support.check_impl_detail(**guards)

Usa esta comprobación para proteger las pruebas específicas de implementación de CPython o para ejecutarlas solo en las implementaciones protegidas por los argumentos:

check_impl_detail()               # Only on CPython (default).
check_impl_detail(jython=True)    # Only on Jython.
check_impl_detail(cpython=False)  # Everywhere except CPython.

test.support.check_warnings(*filters, quiet=True)

Un envoltorio de conveniencia para warnings.catch_warnings() que hace que sea más fácil probar que una advertencia se lanzó correctamente. Es aproximadamente equivalente a llamar a warnings.catch_warnings(record=True) con warnings.simplefilter() establecido en always y con la opción de validar automáticamente los resultados que se registran.

check_warnings acepta 2 tuplas de la forma ("mensaje regexp", WarningCategory) como argumentos posicionales. Si se proporcionan uno o más filters, o si el argumento opcional de palabra clave quiet es False, se verifica para asegurarse de que las advertencias sean las esperadas: cada filtro especificado debe coincidir con al menos una de las advertencias lanzadas por el código adjunto o la prueba falla, y si se lanzan advertencias que no coinciden con ninguno de los filtros especificados, la prueba falla. Para deshabilitar la primera de estas comprobaciones, configure quiet en True.

Si no se especifican argumentos, el valor predeterminado es:

check_warnings(("", Warning), quiet=True)

En este caso, se capturan todas las advertencias y no se lanzaran errores.

En la entrada al administrador de contexto, se retorna una instancia de WarningRecorder. La lista de advertencias subyacentes de catch_warnings() está disponible a través del atributo warnings del objeto del registrador. Como conveniencia, también se puede acceder directamente a los atributos del objeto que representa la advertencia más reciente a través del objeto grabador (vea el ejemplo a continuación). Si no se ha lanzado ninguna advertencia, cualquiera de los atributos que de otro modo se esperarían en un objeto que representa una advertencia retornará None.

El objeto grabador (recorder object) también tiene un método reset(), que borra la lista de advertencias.

El administrador de contexto está diseñado para usarse así:

with check_warnings(("assertion is always true", SyntaxWarning),
                    ("", UserWarning)):
    exec('assert(False, "Hey!")')
    warnings.warn(UserWarning("Hide me!"))

En este caso, si no se generó ninguna advertencia, o si surgió alguna otra advertencia, check_warnings() lanzaría un error.

Cuando una prueba necesita analizar más profundamente las advertencias, en lugar de simplemente verificar si ocurrieron o no, se puede usar un código como este:

with check_warnings(quiet=True) as w:
    warnings.warn("foo")
    assert str(w.args[0]) == "foo"
    warnings.warn("bar")
    assert str(w.args[0]) == "bar"
    assert str(w.warnings[0].args[0]) == "foo"
    assert str(w.warnings[1].args[0]) == "bar"
    w.reset()
    assert len(w.warnings) == 0

Aquí se capturarán todas las advertencias, y el código de prueba prueba las advertencias capturadas directamente.

Distinto en la versión 3.2: Nuevos argumentos opcionales filters y quiet.

test.support.check_no_resource_warning(testcase)

Gestor de contexto para comprobar que no se ha lanzado un ResourceWarning . Debe eliminar el objeto que puede emitir ResourceWarning antes del final del administrador de contexto.

test.support.set_memlimit(limit)

Establece los valores para max_memuse y real_max_memuse para pruebas de memoria grande.

test.support.record_original_stdout(stdout)

Almacene el valor de stdout. Está destinado a mantener el stdout en el momento en que comenzó el regrtest.

test.support.get_original_stdout()

Retorna el stdout original establecido por record_original_stdout() o sys.stdout si no está configurado.

test.support.args_from_interpreter_flags()

Retorna una lista de argumentos de línea de comandos que reproducen la configuración actual en sys.flags y sys.warnoptions.

test.support.optim_args_from_interpreter_flags()

Retorna una lista de argumentos de línea de comandos que reproducen la configuración de optimización actual en sys.flags.

test.support.captured_stdin()

test.support.captured_stdout()

test.support.captured_stderr()

Un administrador de contexto que reemplaza temporalmente la secuencia nombrada con un objeto io.StringIO.

Ejemplo de uso con flujos de salida:

with captured_stdout() as stdout, captured_stderr() as stderr:
    print("hello")
    print("error", file=sys.stderr)
assert stdout.getvalue() == "hello\n"
assert stderr.getvalue() == "error\n"

Ejemplo de uso con flujo de entrada:

with captured_stdin() as stdin:
    stdin.write('hello\n')
    stdin.seek(0)
    # call test code that consumes from sys.stdin
    captured = input()
self.assertEqual(captured, "hello")

test.support.temp_dir(path=None, quiet=False)

Un administrador de contexto que crea un directorio temporal en path y produce el directorio.

Si path es None, el directorio temporal se crea usando tempfile.mkdtemp(). Si quiet es False, el administrador de contexto lanza una excepción en caso de error. De lo contrario, si se especifica path y no se puede crear, solo se emite una advertencia.

test.support.change_cwd(path, quiet=False)

Un administrador de contexto que cambia temporalmente el directorio de trabajo actual a path y produce el directorio.

Si quiet es False, el administrador de contexto lanza una excepción en caso de error. De lo contrario, solo emite una advertencia y mantiene el directorio de trabajo actual igual.

test.support.temp_cwd(name='tempcwd', quiet=False)

Un administrador de contexto que crea temporalmente un nuevo directorio y cambia el directorio de trabajo actual (CWD).

El administrador de contexto crea un directorio temporal en el directorio actual con el nombre name antes de cambiar temporalmente el directorio de trabajo actual. Si name es None , el directorio temporal se crea usando tempfile.mkdtemp().

Si quiet es False y no es posible crear o cambiar el CWD, se lanza un error. De lo contrario, solo se lanza una advertencia y se utiliza el CWD original.

test.support.temp_umask(umask)

Un administrador de contexto que establece temporalmente el proceso umask.

test.support.disable_faulthandler()

Un administrador de contexto que remplaza sys.stderr con sys.__stderr__.

test.support.gc_collect()

Se fuerza la mayor cantidad posible de objetos para ser recolectados. Esto es necesario porque el recolector de basura no garantiza la desasignación oportuna. Esto significa que los métodos __del__ pueden llamarse más tarde de lo esperado y las referencias débiles pueden permanecer vivas por más tiempo de lo esperado.

test.support.disable_gc()

Un administrador de contexto que deshabilita el recolector de basura al entrar y lo vuelve a habilitar al salir.

test.support.swap_attr(obj, attr, new_val)

Administrador de contexto para intercambiar un atributo con un nuevo objeto.

Uso:

with swap_attr(obj, "attr", 5):
    ...

Esto establecerá obj.attr en 5 durante la duración del bloque with, restaurando el valor anterior al final del bloque. Si attr no existe en obj, se creará y luego se eliminará al final del bloque.

El valor anterior (o None si no existe) se asignará al objetivo de la cláusula «como», si existe.

test.support.swap_item(obj, attr, new_val)

Administrador de contexto para intercambiar un elemento con un nuevo objeto.

Uso:

with swap_item(obj, "item", 5):
    ...

Esto establecerá obj ["item"] a 5 durante la duración del bloque with, restaurando el valor anterior al final del bloque. Si item no existe en obj, se creará y luego se eliminará al final del bloque.

El valor anterior (o None si no existe) se asignará al objetivo de la cláusula «como», si existe.

test.support.print_warning(msg)

Imprime una advertencia en sys.__stderr__. Formatea el mensaje como: f "Warning -- {msg}". Si msg se compone de varias líneas, añade el prefijo "Warning --" a cada línea.

Nuevo en la versión 3.9.

test.support.wait_process(pid, *, exitcode, timeout=None)

Espere hasta que el proceso pid termine y comprobará que el código de salida del proceso es exitcode.

Lanza un AssertionError si el código de salida del proceso no es igual a exitcode.

Si el proceso se ejecuta durante más tiempo que timeout en segundos (SHORT_TIMEOUT por defecto), mata el proceso y lanza un AssertionError. La función de tiempo de espera no está disponible en Windows.

Nuevo en la versión 3.9.

test.support.wait_threads_exit(timeout=60.0)

El administrador de contexto debe esperar hasta que salgan todos los hilos creados en la declaración with.

test.support.start_threads(threads, unlock=None)

Administrador de contexto para iniciar threads. Intenta unir los hilos al salir.

test.support.calcobjsize(fmt)

Retorna struct.calcsize() para nP{fmt}0n o, si gettotalrefcount existe, 2PnP{fmt}0P.

test.support.calcvobjsize(fmt)

Retorna struct.calcsize() para nPn{fmt}0n o, si gettotalrefcount existe, 2PnPn{fmt}0P.

test.support.checksizeof(test, o, size)

Para el caso de prueba (testcase), se aserciona que el sys.getsizeof para o más el tamaño del encabezado GC es igual a size.

test.support.can_symlink()

Retorna True si el sistema operativo admite links simbólicos, de lo contrario False.

test.support.can_xattr()

Retorna True si el sistema operativo admite xattr, de lo contrario False.

@test.support.skip_unless_symlink

Un decorador para ejecutar pruebas que requieren soporte para enlaces simbólicos.

@test.support.skip_unless_xattr

Un decorador para ejecutar pruebas que requieren soporte para xattr.

@test.support.anticipate_failure(condition)

Un decorador para marcar condicionalmente las pruebas con unittest.expectedFailure(). Cualquier uso de este decorador debe tener un comentario asociado que identifique el problema relevante del rastreador.

@test.support.run_with_locale(catstr, *locales)

Un decorador para ejecutar una función en una configuración regional diferente, restableciéndola correctamente una vez que ha finalizado. catstr es la categoría de configuración regional como una cadena (por ejemplo, "LC_ALL"). Las locales aprobadas se probarán secuencialmente y se utilizará la primera configuración regional válida.

@test.support.run_with_tz(tz)

Un decorador para ejecutar una función en una zona horaria específica, restableciéndola correctamente una vez que haya finalizado.

@test.support.requires_freebsd_version(*min_version)

Decorador para la versión mínima cuando se ejecuta la prueba en FreeBSD. Si la versión de FreeBSD es inferior al mínimo, aumente unittest.SkipTest.

@test.support.requires_linux_version(*min_version)

Decorador para la versión mínima cuando se ejecuta la prueba en Linux. Si la versión de Linux es inferior al mínimo, aumente unittest.SkipTest.

@test.support.requires_mac_version(*min_version)

Decorator for the minimum version when running test on macOS. If the macOS version is less than the minimum, raise unittest.SkipTest.

@test.support.requires_IEEE_754

Decorador para omitir pruebas en plataformas que no son IEEE 754.

@test.support.requires_zlib

Decorador para omitir pruebas si zlib no existe.

@test.support.requires_gzip

Decorador para omitir pruebas si gzip no existe.

@test.support.requires_bz2

Decorador para omitir pruebas si bz2 no existe.

@test.support.requires_lzma

Decorador para omitir pruebas si lzma no existe.

@test.support.requires_resource(resource)

Decorador para omitir pruebas si resource no está disponible.

@test.support.requires_docstrings

Decorador para ejecutar solo la prueba si HAVE_DOCSTRINGS.

@test.support.cpython_only(test)

Decorador para pruebas solo aplicable a CPython.

@test.support.impl_detail(msg=None, **guards)

Decorador para invocar check_impl_detail() en guards. Si eso retorna False, entonces usa msg como la razón para omitir la prueba.

@test.support.no_tracing(func)

Decorador para desactivar temporalmente el seguimiento durante la duración de la prueba.

@test.support.refcount_test(test)

Decorador para pruebas que implican conteo de referencias. El decorador no ejecuta la prueba si CPython no la ejecuta. Cualquier función de rastreo no se establece durante la duración de la prueba para evitar conteos de referencia(refcounts) inesperados causados ​​por la función de rastreo.

@test.support.reap_threads(func)

Decorador para garantizar que los hilos se limpien incluso si la prueba falla.

@test.support.bigmemtest(size, memuse, dry_run=True)

Decorador para pruebas bigmem.

size es un tamaño solicitado para la prueba (en unidades arbitrarias interpretadas por la prueba). memuse es el número de bytes por unidad para la prueba, o una buena estimación de la misma. Por ejemplo, una prueba que necesita dos búfers de byte, de 4 GiB cada uno, podría decorarse con @bigmemtest(size=_4G, memuse=2).

El argumento size normalmente se pasa al método de prueba decorado como un argumento adicional. Si dry_run es True, el valor pasado al método de prueba puede ser menor que el valor solicitado. Si dry_run es False, significa que la prueba no admite ejecuciones ficticias cuando no se especifica -M.

@test.support.bigaddrspacetest(f)

Decorador para pruebas que llenan el espacio de direcciones. f es la función para envolver.

test.support.make_bad_fd()

Se crea un descriptor de archivo no válido abriendo y cerrando un archivo temporal y retornando su descriptor.

test.support.check_syntax_error(testcase, statement, errtext='', *, lineno=None, offset=None)

Prueba los errores de sintaxis en statement intentando compilar statement. testcase es la instancia unittest para la prueba. errtext es la expresión regular que debe coincidir con la representación de cadena de caracteres que es lanza en SyntaxError. Si lineno no es None, se compara con la línea de la excepción. Si offset no es None, se compara con el desplazamiento de la excepción.

test.support.check_syntax_warning(testcase, statement, errtext='', *, lineno=1, offset=None)

Prueba la advertencia de sintaxis en statement intentando compilar statement. Pruebe también que SyntaxWarning se emite solo una vez, y que se convertirá en SyntaxError cuando se convierta en error. testcase es la instancia unittest para la prueba. errtext es la expresión regular que debe coincidir con la representación de cadena del emitido SyntaxWarning y lanza SyntaxError . Si lineno no es None, se compara con la línea de advertencia y excepción. Si offset no es None, se compara con el desplazamiento de la excepción.

Nuevo en la versión 3.8.

test.support.open_urlresource(url, *args, **kw)

Abre url. Si la apertura falla, se lanza TestFailed.

test.support.import_module(name, deprecated=False, *, required_on())

Esta función importa y retorna el módulo nombrado. A diferencia de una importación normal, esta función lanza unittest.SkipTest si el módulo no se puede importar.

Los mensajes de deprecación de módulos y paquetes se suprimen durante esta importación si deprecated es True. Si se requiere un módulo en una plataforma pero es opcional para otros, establezca required_on en un iterable de prefijos de plataforma que se compararán con sys.platform.

Nuevo en la versión 3.1.

test.support.import_fresh_module(name, fresh=(), blocked=(), deprecated=False)

Esta función importa y retorna una copia nueva del módulo Python nombrado eliminando el módulo nombrado de sys.modules antes de realizar la importación. Tenga en cuenta que a diferencia de reload(), el módulo original no se ve afectado por esta operación.

fresh es un iterable de nombres de módulos adicionales que también se eliminan del caché sys.modules antes de realizar la importación.

bloqueado es un iterable de nombres de módulos que se reemplazan con None en la memoria caché del módulo durante la importación para garantizar que los intentos de importarlos generen ImportError.

El módulo nombrado y los módulos nombrados en los parámetros fresh y bloqueado se guardan antes de comenzar la importación y luego se vuelven a insertar en sys.modules cuando se completa la importación fresca.

Los mensajes de deprecación de módulos y paquetes se suprimen durante esta importación si deprecated es True.

Esta función lanzará ImportError si el módulo nombrado no puede importarse.

Ejemplo de uso:

# Get copies of the warnings module for testing without affecting the
# version being used by the rest of the test suite. One copy uses the
# C implementation, the other is forced to use the pure Python fallback
# implementation
py_warnings = import_fresh_module('warnings', blocked=['_warnings'])
c_warnings = import_fresh_module('warnings', fresh=['_warnings'])

Nuevo en la versión 3.1.

test.support.modules_setup()

Retorna una copia de sys.modules.

test.support.modules_cleanup(oldmodules)

Elimina los módulos a excepción de oldmodules y encodings para preservar la memoria caché interna.

test.support.threading_setup()

Retorna el recuento del hilo actual y copia de subprocesos colgantes.

test.support.threading_cleanup(*original_values)

Se limpia los hilos no especificados en original_values. Diseñado para emitir una advertencia si una prueba deja hilos en ejecución en segundo plano.

test.support.join_thread(thread, timeout=30.0)

Se une un thread dentro de timeout. Lanza un AssertionError si el hilo sigue vivo después de unos segundos de timeout.

test.support.reap_children()

Se utiliza esto al final de test_main siempre que se inicien subprocesos. Esto ayudará a garantizar que ningún proceso hijo adicional (zombies) se quede para acumular recursos y crear problemas al buscar refleaks.

test.support.get_attribute(obj, name)

Obtiene un atributo, lanzando unittest.SkipTest si AttributeError está activado.

test.support.catch_threading_exception()

El administrador de contexto captura threading.Thread excepción usando threading.excepthook().

Attributes set when an exception is caught:

exc_type

exc_value

exc_traceback

thread

Consulte la documentación para threading.excepthook().

Estos atributos se eliminan en la salida del administrador de contexto.

Uso:

with support.catch_threading_exception() as cm:
    # code spawning a thread which raises an exception
    ...

    # check the thread exception, use cm attributes:
    # exc_type, exc_value, exc_traceback, thread
    ...

# exc_type, exc_value, exc_traceback, thread attributes of cm no longer
# exists at this point
# (to avoid reference cycles)

Nuevo en la versión 3.8.

test.support.catch_unraisable_exception()

El administrador de contexto detectando excepciones imposibles de evaluar usando sys.unraisablehook().

El almacenamiento del valor de excepción (cm.unraisable.exc_value) crea un ciclo de referencia. El ciclo de referencia se interrumpe explícitamente cuando sale el administrador de contexto.

El almacenamiento del objeto (cm.unraisable.object) puede resucitarlo si se establece en un objeto que se está finalizando. Salir del administrador de contexto borra el objeto almacenado.

Uso:

with support.catch_unraisable_exception() as cm:
    # code creating an "unraisable exception"
    ...

    # check the unraisable exception: use cm.unraisable
    ...

# cm.unraisable attribute no longer exists at this point
# (to break a reference cycle)

Nuevo en la versión 3.8.

test.support.load_package_tests(pkg_dir, loader, standard_tests, pattern)

La implementación genérica del protocolo unittest load_tests para usar en paquetes de prueba. pkg_dir es el directorio raíz del paquete; loader, standard_tests y pattern son los argumentos esperados por load_tests. En casos simples, el paquete de prueba __init __. Py puede ser el siguiente:

import os
from test.support import load_package_tests

def load_tests(*args):
    return load_package_tests(os.path.dirname(__file__), *args)

test.support.fs_is_case_insensitive(directory)

Retorna True si el sistema de archivos para directory no distingue entre mayúsculas y minúsculas.

test.support.detect_api_mismatch(ref_api, other_api, *, ignore=())

Retorna el conjunto de atributos, funciones o métodos de ref_api que no se encuentra en other_api *, excepto por una lista definida de elementos que se ignorarán en esta comprobación especificada en *ignore.

De forma predeterminada, omite los atributos privados que comienzan con “_” pero incluye todos los métodos mágicos, es decir, los que comienzan y terminan en “__”.

Nuevo en la versión 3.5.

test.support.patch(test_instance, object_to_patch, attr_name, new_value)

Se anula object_to_patch.attr_name con new_value. Se agrega también el procedimiento de limpieza a test_instance para restaurar object_to_patch para attr_name. Attr_name debe ser un atributo válido para object_to_patch.

test.support.run_in_subinterp(code)

Ejecuta code en el subinterpretador. Lanza unittest.SkipTest si tracemalloc está habilitado.

test.support.check_free_after_iterating(test, iter, cls, args=())

Aserciona que iter se desasigna después de iterar.

test.support.missing_compiler_executable(cmd_names=[])

Verifica la existencia de los ejecutables del compilador cuyos nombres figuran en cmd_names o todos los ejecutables del compilador cuando cmd_names está vacío y retorna el primer ejecutable faltante o None cuando no se encuentra ninguno.

test.support.check__all__(test_case, module, name_of_module=None, extra=(), blacklist=())

Aserciona que la variable _all__ de module contiene todos los nombres públicos.

Los nombres públicos del módulo (su API) se detectan automáticamente en función de si coinciden con la convención de nombres públicos y se definieron en module.

El argumento name_of_module puede especificar (como una cadena o tupla del mismo) qué módulo(s) se podría definir una API para ser detectada como una API pública. Un caso para esto es cuando module importa parte de su API pública desde otros módulos, posiblemente un backend de C (como csv y su _csv).

El argumento extra puede ser un conjunto de nombres que de otro modo no se detectarían automáticamente como «públicos» («public»), como objetos sin un atributo adecuado __module__. Si se proporciona, se agregará a los detectados automáticamente.

El argumento blacklist puede ser un conjunto de nombres que no deben tratarse como parte de la API pública aunque sus nombres indiquen lo contrario.

Ejemplo de uso:

import bar
import foo
import unittest
from test import support

class MiscTestCase(unittest.TestCase):
    def test__all__(self):
        support.check__all__(self, foo)

class OtherTestCase(unittest.TestCase):
    def test__all__(self):
        extra = {'BAR_CONST', 'FOO_CONST'}
        blacklist = {'baz'}  # Undocumented name.
        # bar imports part of its API from _bar.
        support.check__all__(self, bar, ('bar', '_bar'),
                             extra=extra, blacklist=blacklist)

Nuevo en la versión 3.6.

test.support.adjust_int_max_str_digits(max_digits)

This function returns a context manager that will change the global sys.set_int_max_str_digits() setting for the duration of the context to allow execution of test code that needs a different limit on the number of digits when converting between an integer and string.

Nuevo en la versión 3.9.14.

El módulo test.support define las siguientes clases:

class test.support.TransientResource(exc, **kwargs)

Las instancias son un administrador de contexto que lanza ResourceDenied si se lanza el tipo de excepción especificado. Cualquier argumento de palabra clave se trata como pares de atributo / valor para compararlo con cualquier excepción lanzada dentro de with. Solo si todos los pares coinciden correctamente con los atributos de la excepción se lanza ResourceDenied.

class test.support.EnvironmentVarGuard

Clase utilizada para establecer o deshabilitar temporalmente las variables de entorno. Las instancias se pueden usar como un administrador de contexto y tienen una interfaz de diccionario completa para consultar/modificar el os.environ subyacente. Después de salir del administrador de contexto, todos los cambios en las variables de entorno realizados a través de esta instancia se revertirán.

Distinto en la versión 3.1: Añadido una interfaz de diccionario.

EnvironmentVarGuard.set(envvar, value)

Se establece temporalmente la variable de entorno envvar en el valor de value.

EnvironmentVarGuard.unset(envvar)

Deshabilita temporalmente la variable de entorno envvar.

class test.support.SuppressCrashReport

Un administrador de contexto suele intentar evitar ventanas emergentes de diálogo de bloqueo en las pruebas que se espera que bloqueen un subproceso.

En Windows, deshabilita los cuadros de diálogo de Informe de errores de Windows usando SetErrorMode [https://msdn.microsoft.com/en-us/library/windows/desktop/ms680621.aspx].

En UNIX, resource.setrlimit() se usa para establecer resource.RLIMIT_CORE del límite flexible a 0 para evitar la creación de archivos coredump.

En ambas plataformas, el valor anterior se restaura mediante __exit__().

class test.support.CleanImport(*module_names)

Un administrador de contexto para forzar la importación para que retorne una nueva referencia de módulo. Esto es útil para probar comportamientos a nivel de módulo, como la emisión de una Advertencia de desaprobación en la importación. Ejemplo de uso:

with CleanImport('foo'):
    importlib.import_module('foo')  # New reference.

class test.support.DirsOnSysPath(*paths)

Un administrador de contexto para agregar temporalmente directorios a sys.path.

Esto hace una copia de sys.path, agrega cualquier directorio dado como argumento posicional, luego revierte sys.path a la configuración copiada cuando finaliza el contexto.

Tenga en cuenta que all sys.path produce modificaciones en el cuerpo del administrador de contexto, incluida la sustitución del objeto, se revertirán al final del bloque.

class test.support.SaveSignals

Clase para guardar y restaurar manejadores (handlers) de señal registrados por el manejador de señal Python.

class test.support.Matcher

matches(self, d, **kwargs)

Intenta hacer coincidir una sola sentencia con los argumentos proporcionados.

match_value(self, k, dv, v)

Intenta hacer coincidir un único valor almacenado (dv) con un valor proporcionado (v).

class test.support.WarningsRecorder

La clase utilizada para registrar advertencias para pruebas unitarias. Consulte la documentación de check_warnings() arriba para obtener más detalles.

class test.support.BasicTestRunner

run(test)

Retorna test y retorna el resultado..

class test.support.FakePath(path)

Simple path-like object. Se implementa el método __fspath__() que simplemente retorna el argumento path. Si path es una excepción, se lanzará en __ fspath__().

test.support.socket_helper — Utilidades para pruebas de socket

El módulo test.support.socket_helper proporciona soporte para las pruebas de socket.

Nuevo en la versión 3.9.

test.support.socket_helper.IPV6_ENABLED

Se establece como True si IPv6 está habilitado en este host, False en caso contrario.

test.support.socket_helper.find_unused_port(family=socket.AF_INET, socktype=socket.SOCK_STREAM)

Retorna un puerto no utilizado que debería ser adecuado para el enlace. Esto se logra creando un socket temporal con la misma familia y tipo que el parámetro sock (el valor predeterminado es AF_INET, SOCK_STREAM) y vinculándolo a la dirección de host especificada (por defecto es 0.0.0.0) con el puerto establecido en 0, provocando un puerto efímero no utilizado del sistema operativo. El socket temporal se cierra y se elimina, y se retorna el puerto efímero.

Este método o bind_port() debe usarse para cualquier prueba en la que un socket del servidor deba estar vinculado a un puerto en particular durante la duración de la prueba. Cuál usar depende de si el código de llamada está creando un socket Python, o si un puerto no utilizado debe proporcionarse en un constructor o pasar a un programa externo (es decir, el argumento -accept al modo s_server de openssl). Siempre es preferible bind_port() sobre find_unused_port() donde sea posible. Se desaconseja el uso de un puerto codificado ya que puede hacer que varias instancias de la prueba sean imposibles de ejecutar simultáneamente, lo cual es un problema para los buildbots.

test.support.socket_helper.bind_port(sock, host=HOST)

Se enlaza el socket a un puerto libre y retorna el número de puerto. Se basa en puertos efímeros para garantizar que estemos utilizando un puerto independiente. Esto es importante ya que muchas pruebas pueden ejecutarse simultáneamente, especialmente en un entorno buildbot. Este método lanza una excepción si sock.family es AF_INET y sock.type es SOCK_STREAM, y el socket tiene SO_REUSEADDR o SO_REUSEPORT establecido en él. Las pruebas nunca deben configurar estas opciones de socket para los sockets TCP/IP. El único caso para configurar estas opciones es probar la multidifusión (multicasting) a través de múltiples sockets UDP.

Además, si la opción de socket SO_EXCLUSIVEADDRUSE está disponible (es decir, en Windows), se establecerá en el socket. Esto evitará que otras personas se vinculen a nuestro host/puerto mientras dure la prueba.

test.support.socket_helper.bind_unix_socket(sock, addr)

Enlace un socket Unix, lanzando unittest.SkipTest si PermissionError es lanzado.

@test.support.socket_helper.skip_unless_bind_unix_socket

Un decorador para ejecutar pruebas que requieren un enlace(bind()) funcional para sockets en sistemas Unix.

test.support.socket_helper.transient_internet(resource_name, *, timeout=30.0, errnos=())

Un gestor de contexto que lanza ResourceDenied cuando varios problemas con la conexión a Internet se manifiestan como excepciones.

test.support.script_helper —Utilidades para las pruebas de ejecución de Python

El módulo test.support.script_helper proporciona soporte para las pruebas de ejecución de script de Python.

test.support.script_helper.interpreter_requires_environment()

Retorna True` si el sys.executable interpreter requiere variables de entorno para poder ejecutarse.

Esto está diseñado para usarse con @unittest.skipIf() para anotar pruebas que necesitan usar una función assert_python*() para iniciar un modo aislado (-I) o sin entorno proceso de subinterpretador de modo (-E).

Una compilación y prueba normal no se encuentra en esta situación, pero puede suceder cuando se intenta ejecutar el conjunto de pruebas de biblioteca estándar desde un intérprete que no tiene un directorio principal obvio con la lógica de búsqueda de directorio principal actual de Python.

La configuración PYTHONHOME es una forma de hacer que la mayoría del testuite se ejecute en esa situación. PYTHONPATH o PYTHONUSERSITE son otras variables de entorno comunes que pueden afectar si el intérprete puede o no comenzar.

test.support.script_helper.run_python_until_end(*args, **env_vars)

Configura el entorno basado en env_vars para ejecutar el intérprete en un subproceso. Los valores pueden incluir __isolated, __cleanenv, __cwd y TERM.

Distinto en la versión 3.9: La función ya no elimina los espacios en blanco de stderr.

test.support.script_helper.assert_python_ok(*args, **env_vars)

Aserción de que ejecutar el intérprete con arg y variables de entorno opcionales env_vars tiene éxito (rc == 0) y retorna una tupla (código de retorno, stdout, stderr).

Si se establece la palabra clave __cleanenv, env_vars se usa como un entorno nuevo.

Python se inicia en modo aislado (opción de línea de comando -I), excepto si la palabra clave __isolated se establece en False.

Distinto en la versión 3.9: La función ya no elimina los espacios en blanco de stderr.

test.support.script_helper.assert_python_failure(*args, **env_vars)

Aserciona que la ejecución del intérprete con args y variables de entorno opcionales env_vars falla (rc! = 0) y retorna una tupla (return code, stdout, stderr).

Consulte assert_python_ok() para más opciones.

Distinto en la versión 3.9: La función ya no elimina los espacios en blanco de stderr.

test.support.script_helper.spawn_python(*args, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, **kw)

Ejecuta un subproceso de Python con los argumentos dados.

kw es un argumento adicional de palabras clave para pasar a subprocess.Popen(). Retorna un objeto a subprocess.Popen.

test.support.script_helper.kill_python(p)

Ejecuta el proceso dado subprocess.Popen hasta que finalice y retorne stdout.

test.support.script_helper.make_script(script_dir, script_basename, source, omit_suffix=False)

Crea un script que contiene source en la ruta script_dir y script_basename. Si omit_suffix es False, agregue .py al nombre. Retorna la ruta completa del script.

test.support.script_helper.make_zip_script(zip_dir, zip_basename, script_name, name_in_zip=None)

Crea un archivo zip en zip_dir y zip_basename con la extensión zip que contiene los archivos en script_name. name_in_zip es el nombre del archivo. Retorna una tupla que contiene (ruta completa, ruta completa del nombre del archivo).

test.support.script_helper.make_pkg(pkg_dir, init_source='')

Crea un directorio llamado pkg_dir que contiene un archivo __init__ con init_source como su contenido.

test.support.script_helper.make_zip_pkg(zip_dir, zip_basename, pkg_name, script_basename, source, depth=1, compiled=False)

Crea un directorio de paquete zip con una ruta de zip_dir y zip_basename que contiene un archivo __init__ vacío y un archivo script_basename que contiene el source. Si compilado es True, ambos archivos fuente se compilarán y se agregarán al paquete zip. Retorna una tupla de la ruta zip completa y el nombre de archivo para el archivo zip.

test.support.bytecode_helper — Herramientas de apoyo para comprobar la correcta generación de bytecode

El módulo test.support.bytecode_helper proporciona soporte para probar e inspeccionar la generación de código de bytes.

Nuevo en la versión 3.9.

El módulo define la siguiente clase:

class test.support.bytecode_helper.BytecodeTestCase(unittest.TestCase)

Esta clase tiene métodos de aserción personalizados para inspeccionar el código de bytes.

BytecodeTestCase.get_disassembly_as_string(co)

Retorna el desensamblaje de co como cadena.

BytecodeTestCase.assertInBytecode(x, opname, argval=_UNSPECIFIED)

Retorna instr si se encuentra opname, de lo contrario lanza AssertionError.

BytecodeTestCase.assertNotInBytecode(x, opname, argval=_UNSPECIFIED)

Lanza AssertionError si se encuentra opname.

Depuración y perfilado

Estas bibliotecas le ayudan con el desarrollo de Python: el depurador le permite recorrer paso a paso el código, analizar marcos de pila y establecer puntos de interrupción, etc., y los perfiladores ejecutan código y le proporcionan un desglose detallado de los tiempos de ejecución, lo que le permite identificar cuellos de botella en sus programas. Los eventos de auditoría proporcionan visibilidad de los comportamientos en tiempo de ejecución que, de lo contrario, requerirían depuración o parches intrusivos.

Tabla de auditoría de eventos

bdb — Framework de depuración

faulthandler — Volcar el rastreo de Python

Volcar el rastreo

Estado del gestor de fallos

Volcar los rastreos después de un tiempo de espera

Volcar el rastreo en una señal del usuario

Problema con descriptores de archivo

Ejemplo

pdb — El Depurador de Python

Comandos del depurador

Los perfiladores de Python

Introducción a los perfiladores

Manual instantáneo de usuario

Referencia del módulo profile y cProfile

La clase Stats

¿Qué es el perfil determinista?

Limitaciones

Calibración

Usando un temporizador personalizado

timeit — Mide el tiempo de ejecución de pequeños fragmentos de código

Ejemplos básicos

Interfaz de Python

Interfaz de línea de comandos

Ejemplos

trace — Rastrear la ejecución de la declaración de Python

Uso de la línea de comandos

Opciones principales

Modificadores

Filtros

Interfaz programática

tracemalloc— Rastrea la asignación de memoria

Ejemplos

Mostrar los 10 principales

Calcula las diferencias

Consigue el seguimiento del bloque de memoria

Los 10 más bonitos

Graba los tamaños actual y máximo de todos los bloques de memoria rastreados

API

Funciones

Filtro de dominio

Filtro

Cuadro

Captura instantánea

Estadística

StatisticDiff

Rastro

Seguimiento

Tabla de auditoría de eventos

This table contains all events raised by sys.audit() or PySys_Audit() calls throughout the CPython runtime and the standard library. These calls were added in 3.8.0 or later (see PEP 578 [https://www.python.org/dev/peps/pep-0578]).

Ver sys.addaudithook() y PySys_AddAuditHook() para informarse en el manejo de estos eventos.

CPython implementation detail: Esta tabla es generada desde la documentación de CPython, y no debe guardar eventos lanzados por otras implementaciones. Ver la documentación de tus especificaciones en tiempo de ejecución para los eventos lanzados recientemente.

Audit event

Arguments

References

array.__new__

typecode, initializer

[1]

builtins.breakpoint

breakpointhook

[1]

builtins.id

id

[1]

builtins.input

prompt

[1]

builtins.input/result

result

[1]

code.__new__

code, filename, name, argcount, posonlyargcount, kwonlyargcount, nlocals, stacksize, flags

[1]

compile

source, filename

[1]

cpython.PyInterpreterState_Clear

[1]

cpython.PyInterpreterState_New

[1]

cpython._PySys_ClearAuditHooks

[1]

cpython.run_command

command

[1]

cpython.run_file

filename

[1]

cpython.run_interactivehook

hook

[1]

cpython.run_module

module-name

[1]

cpython.run_startup

filename

[1]

cpython.run_stdin

[1]

ctypes.addressof

obj

[1]

ctypes.call_function

func_pointer, arguments

[1]

ctypes.cdata

address

[1]

ctypes.cdata/buffer

pointer, size, offset

[1][2]

ctypes.create_string_buffer

init, size

[1]

ctypes.create_unicode_buffer

init, size

[1]

ctypes.dlopen

name

[1]

ctypes.dlsym

library, name

[1]

ctypes.dlsym/handle

handle, name

[1]

ctypes.get_errno

[1]

ctypes.get_last_error

[1]

ctypes.seh_exception

code

[1]

ctypes.set_errno

errno

[1]

ctypes.set_last_error

error

[1]

ctypes.string_at

address, size

[1]

ctypes.wstring_at

address, size

[1]

ensurepip.bootstrap

root

[1]

exec

code_object

[1][2]

fcntl.fcntl

fd, cmd, arg

[1]

fcntl.flock

fd, operation

[1]

fcntl.ioctl

fd, request, arg

[1]

fcntl.lockf

fd, cmd, len, start, whence

[1]

ftplib.connect

self, host, port

[1]

ftplib.sendcmd

self, cmd

[1][2]

function.__new__

code

[1]

gc.get_objects

generation

[1]

gc.get_referents

objs

[1]

gc.get_referrers

objs

[1]

glob.glob

pathname, recursive

[1][2]

imaplib.open

self, host, port

[1]

imaplib.send

self, data

[1]

import

module, filename, sys.path, sys.meta_path, sys.path_hooks

[1]

marshal.dumps

value, version

[1]

marshal.load

[1]

marshal.loads

bytes

[1]

mmap.__new__

fileno, length, access, offset

[1]

msvcrt.get_osfhandle

fd

[1]

msvcrt.locking

fd, mode, nbytes

[1]

msvcrt.open_osfhandle

handle, flags

[1]

nntplib.connect

self, host, port

[1][2]

nntplib.putline

self, line

[1][2]

object.__delattr__

obj, name

[1]

object.__getattr__

obj, name

[1]

object.__setattr__

obj, name, value

[1]

open

file, mode, flags

[1][2][3]

os.add_dll_directory

path

[1]

os.chdir

path

[1][2]

os.chflags

path, flags

[1][2]

os.chmod

path, mode, dir_fd

[1][2][3]

os.chown

path, uid, gid, dir_fd

[1][2][3]

os.exec

path, args, env

[1]

os.fork

[1]

os.forkpty

[1]

os.fwalk

top, topdown, onerror, follow_symlinks, dir_fd

[1]

os.getxattr

path, attribute

[1]

os.kill

pid, sig

[1]

os.killpg

pgid, sig

[1]

os.link

src, dst, src_dir_fd, dst_dir_fd

[1]

os.listdir

path

[1]

os.listxattr

path

[1]

os.lockf

fd, cmd, len

[1]

os.mkdir

path, mode, dir_fd

[1][2]

os.posix_spawn

path, argv, env

[1][2]

os.putenv

key, value

[1]

os.remove

path, dir_fd

[1][2][3]

os.removexattr

path, attribute

[1]

os.rename

src, dst, src_dir_fd, dst_dir_fd

[1][2][3]

os.rmdir

path, dir_fd

[1]

os.scandir

path

[1]

os.setxattr

path, attribute, value, flags

[1]

os.spawn

mode, path, args, env

[1]

os.startfile

path, operation

[1]

os.symlink

src, dst, dir_fd

[1]

os.system

command

[1]

os.truncate

fd, length

[1][2]

os.unsetenv

key

[1]

os.utime

path, times, ns, dir_fd

[1]

os.walk

top, topdown, onerror, followlinks

[1]

pathlib.Path.glob

self, pattern

[1]

pathlib.Path.rglob

self, pattern

[1]

pdb.Pdb

[1]

pickle.find_class

module, name

[1]

poplib.connect

self, host, port

[1][2]

poplib.putline

self, line

[1][2]

pty.spawn

argv

[1]

resource.prlimit

pid, resource, limits

[1]

resource.setrlimit

resource, limits

[1]

setopencodehook

[1]

shutil.chown

path, user, group

[1]

shutil.copyfile

src, dst

[1][2][3]

shutil.copymode

src, dst

[1][2]

shutil.copystat

src, dst

[1][2]

shutil.copytree

src, dst

[1]

shutil.make_archive

base_name, format, root_dir, base_dir

[1]

shutil.move

src, dst

[1]

shutil.rmtree

path

[1]

shutil.unpack_archive

filename, extract_dir, format

[1]

signal.pthread_kill

thread_id, signalnum

[1]

smtplib.connect

self, host, port

[1]

smtplib.send

self, data

[1]

socket.__new__

self, family, type, protocol

[1]

socket.bind

self, address

[1]

socket.connect

self, address

[1][2]

socket.getaddrinfo

host, port, family, type, protocol

[1]

socket.gethostbyaddr

ip_address

[1]

socket.gethostbyname

hostname

[1][2]

socket.gethostname

[1]

socket.getnameinfo

sockaddr

[1]

socket.getservbyname

servicename, protocolname

[1]

socket.getservbyport

port, protocolname

[1]

socket.sendmsg

self, address

[1]

socket.sendto

self, address

[1]

socket.sethostname

name

[1]

sqlite3.connect

database

[1]

subprocess.Popen

executable, args, cwd, env

[1]

sys._current_frames

[1]

sys._getframe

[1]

sys.addaudithook

[1][2]

sys.excepthook

hook, type, value, traceback

[1]

sys.set_asyncgen_hooks_finalizer

[1]

sys.set_asyncgen_hooks_firstiter

[1]

sys.setprofile

[1]

sys.settrace

[1]

sys.unraisablehook

hook, unraisable

[1]

syslog.closelog

[1]

syslog.openlog

ident, logoption, facility

[1]

syslog.setlogmask

maskpri

[1]

syslog.syslog

priority, message

[1]

telnetlib.Telnet.open

self, host, port

[1]

telnetlib.Telnet.write

self, buffer

[1]

tempfile.mkdtemp

fullpath

[1][2]

tempfile.mkstemp

fullpath

[1][2][3]

urllib.Request

fullurl, data, headers, method

[1]

webbrowser.open

url

[1]

winreg.ConnectRegistry

computer_name, key

[1]

winreg.CreateKey

key, sub_key, access

[1][2]

winreg.DeleteKey

key, sub_key, access

[1][2]

winreg.DeleteValue

key, value

[1]

winreg.DisableReflectionKey

key

[1]

winreg.EnableReflectionKey

key

[1]

winreg.EnumKey

key, index

[1]

winreg.EnumValue

key, index

[1]

winreg.ExpandEnvironmentStrings

str

[1]

winreg.LoadKey

key, sub_key, file_name

[1]

winreg.OpenKey

key, sub_key, access

[1]

winreg.OpenKey/result

key

[1][2][3]

winreg.PyHKEY.Detach

key

[1]

winreg.QueryInfoKey

key

[1]

winreg.QueryReflectionKey

key

[1]

winreg.QueryValue

key, sub_key, value_name

[1][2]

winreg.SaveKey

key, file_name

[1]

winreg.SetValue

key, sub_key, type, value

[1][2]

Los siguientes eventos se generan internamente y no corresponden a ninguna API pública de CPython:

Evento de auditoría

Argumentos

_winapi.CreateFile

file_name, desired_access, share_mode, creation_disposition, flags_and_attributes

_winapi.CreateJunction

src_path, dst_path

_winapi.CreateNamedPipe

name, open_mode, pipe_mode

_winapi.CreatePipe

_winapi.CreateProcess

application_name, command_line, current_directory

_winapi.OpenProcess

process_id, desired_access

_winapi.TerminateProcess

handle, exit_code

ctypes.PyObj_FromPtr

obj

bdb — Framework de depuración

Source code: Lib/bdb.py [https://github.com/python/cpython/tree/3.9/Lib/bdb.py]

El módulo bdb maneja las funciones básicas del depurador, como establecer puntos de interrupción o gestionar la ejecución a través del mismo.

La siguiente excepción es definida:

exception bdb.BdbQuit

Excepción lanzada por la clase Bdb al salir del depurador.

El módulo bdb también define dos clases:

class bdb.Breakpoint(self, file, line, temporary=0, cond=None, funcname=None)

Esta clase implementa puntos de interrupción temporales, permitiendo ignorar recuentos, desactivar y (re-)activar puntos de interrupción y definir condiciones de interrupción para los mismos.

Los puntos de interrupción se indexan numéricamente mediante una lista llamada bpbynumber y por pares (archivo, linea) mediante bplist. En el primer caso se apunta a una única instancia de Breakpoint. En el segundo caso se apunta a una lista de tales instancias, ya que puede haber más de un punto de interrupción por línea.

Al crear un punto de interrupción, el nombre del archivo asociado debe estar en su forma canónica. Si se define un nombre de función funcname, se contará el punto de interrupción cuando se ejecute la primera línea de esa función. Los puntos de interrupción condicionales siempre cuentan los alcances.

Las instancias de la clase Breakpoint tienen los siguientes métodos:

deleteMe()

Elimina el punto de interrupción de la lista asociada a un archivo/línea. Si es el último punto de interrupción en esa posición, también borra la entrada correspondiente del archivo/línea correspondiente.

enable()

Marca el punto de interrupción como habilitado.

disable()

Marca el punto de interrupción como deshabilitado.

bpformat()

Retorna una cadena de caracteres que contiene toda la información sobre el punto de interrupción, apropiadamente formateada:

El número del punto de interrupción.

Si es temporal o no.

Su archivo, la posición de la línea.

La condición que causa la interrupción.

Si debe ignorarse las próximas N veces.

El recuento de alcances del punto de interrupción.

Nuevo en la versión 3.2.

bpprint(out=None)

Imprime la salida de bpformat() en el archivo out, o en la salida estándar si es None.

class bdb.Bdb(skip=None)

La clase Bdb actúa como clase base del depurador genérico de Python.

Esta clase se encarga de los detalles de la funcionalidad de seguimiento; una clase derivada debería encargarse de implementar la interacción con el usuario. Un ejemplo es la clase de depuración estándar (pdb.Pdb).

El argumento skip, si se proporciona, debe ser un iterable con patrones de nombre de archivo, al estilo del módulo glob. El depurador no entrará en aquellos marcos de ejecución que se originen en un módulo que coincida con uno de estos patrones. Para determinar si un marco de ejecución se origina en un módulo determinado, se hace uso de __name__ en las variables globales del marco de ejecución dado.

Nuevo en la versión 3.1: El argumento skip.

Los siguientes métodos de la clase Bdb normalmente no necesitan ser redefinidos.

canonic(filename)

Método auxiliar para obtener el nombre del archivo en su forma canónica, es decir, como una ruta absoluta normalizada entre mayúsculas y minúsculas (en sistemas de archivos que no distinguen entre ambas) y despojada de los corchetes angulares circundantes.

reset()

Establece los atributos botframe, stopframe, returnframe y quitting con valores preparados para comenzar la depuración.

trace_dispatch(frame, event, arg)

Esta función se instala como función de seguimiento de los marcos de ejecución depurados. Su valor de retorno es la nueva función de seguimiento a usar (en la mayoría de los casos, ella misma).

La implementación predeterminada decide cómo despachar un marco de ejecución, dependiendo del tipo de evento (pasado como una cadena) que está a punto de ejecutarse. event puede tomar uno de los siguientes valores:

"line": Se va a ejecutar una nueva línea de código.

"call": Está a punto de llamarse a una función o se ha entrado en otro bloque de código.

"return": Una función u otro bloque de código está a punto de retornar.

"exception": Ha ocurrido una excepción.

"c_call": Una función de C está a punto de llamarse .

"c_return": Una función de C ha retornado.

"c_exception": Una función de C ha lanzado una excepción.

Para los eventos de Python, son llamadas funciones especializadas (ver más abajo). En cambio, para los eventos de C no se realiza ninguna acción.

El parámetro arg depende del evento previo.

Consulta la documentación de sys.settrace() para obtener más información sobre la función de seguimiento. Para obtener más información sobre los objetos código y los objetos marco consulte Jerarquía de tipos estándar.

dispatch_line(frame)

Si el depurador tiene que detenerse en la línea actual, invoca el método user_line() (que debe ser redefinido en las subclases). Genera una excepción BdbQuit si se establece el flag Bdb.quitting (que se puede establecer mediante user_line()). Retorna una referencia al método trace_dispatch() para realizar un seguimiento adicional en ese ámbito.

dispatch_call(frame, arg)

Si el depurador tiene que detenerse en esta llamada de función, invoca el método user_call() (que debe ser redefinido en las subclases). Lanza una excepción BdbQuit si se establece el flag Bdb.quitting (que se puede establecer mediante user_call()). Retorna una referencia al método trace_dispatch() para realizar un seguimiento adicional en ese ámbito.

dispatch_return(frame, arg)

Si el depurador tiene que detenerse en el retorno de esta función, invoca el método user_return() (que debe ser redefinido en las subclases). Lanza una excepción BdbQuit si se establece el flag Bdb.quitting (que se puede establecer mediante user_return()). Retorna una referencia al método trace_dispatch() para realizar un seguimiento adicional en ese ámbito.

dispatch_exception(frame, arg)

Si el depurador tiene que detenerse en esta excepción, invoca el método user_exception() (que debe ser redefinido en las subclases). Lanza una excepción BdbQuit si se establece el flag Bdb.quitting (que se puede establecer mediante user_exception()). Retorna una referencia al método trace_dispatch() para realizar un seguimiento adicional en ese ámbito.

Las clases derivadas normalmente no necesitan redefinir los siguientes métodos, pero pueden hacerlo si necesitan redefinir la definición de parada y los puntos de interrupción.

stop_here(frame)

Este método comprueba si el frame está en cualquier posición debajo de botframe en la pila de llamadas. botframe es el marco de ejecución en el que comenzó la depuración.

break_here(frame)

Este método comprueba si hay un punto de interrupción en el nombre de archivo y la línea pertenecientes a frame o, al menos, en la función actual. Si el punto de interrupción es temporal, este método lo elimina.

break_anywhere(frame)

Este método comprueba si hay un punto de interrupción en el nombre de archivo del marco de ejecución actual.

Las clases derivadas deben redefinir estos métodos para adquirir el control sobre las operaciones de depuración.

user_call(frame, argument_list)

Este método se llama desde dispatch_call() cuando existe la posibilidad de que sea necesaria una interrupción en cualquier lugar dentro de la función llamada.

user_line(frame)

Este método se llama desde dispatch_line() cuando stop_here() o break_here() generan True.

user_return(frame, return_value)

Este método se llama desde dispatch_return() cuando stop_here() genera True.

user_exception(frame, exc_info)

Este método se llama desde dispatch_exception() cuando stop_here() genera True.

do_clear(arg)

Maneja cómo un punto de interrupción debe ser eliminado cuando es temporal.

Este método debe ser implementado por las clases derivadas.

Las clases derivadas y los clientes pueden llamar a los siguientes métodos para influir en el estado de transición.

set_step()

Se detiene después de una línea de código.

set_next(frame)

Se detiene en la siguiente línea del marco de ejecución dado o en la de uno inferior.

set_return(frame)

Se detiene cuando se retorna desde el marco de ejecución dado.

set_until(frame)

Se detiene cuando se alcanza un número de línea superior al de la línea actual o se retorna desde el marco de ejecución actual.

set_trace([frame])

Inicia la depuración desde el marco de ejecución frame. Si frame no se especifica, la depuración se inicia desde el marco de ejecución que produce la llamada.

set_continue()

Se detiene solo en los puntos de interrupción o cuando haya terminado. Si no hay puntos de interrupción, se configura la función de seguimiento del sistema en None.

set_quit()

Establece el atributo quitting en True. Esto lanza una excepción BdbQuit en la siguiente llamada a uno de los métodos dispatch_*() que tenga lugar.

Las clases derivadas y los clientes pueden llamar a los siguientes métodos para manipular los puntos de interrupción. Estos métodos retornan una cadena de caracteres que contiene un mensaje de error si algo fue mal, o None si todo fue correctamente.

set_break(filename, lineno, temporary=0, cond, funcname)

Establece un nuevo punto de interrupción. Si la línea en la posición lineno no existe en el archivo con nombre filename pasado como argumento, se retorna un mensaje de error. filename debe estar en su forma canónica, tal como se describe en el método canonic().

clear_break(filename, lineno)

Elimina el punto de interrupción en el archivo filename y número de linea lineno. Si no se ha establecido ninguno, se retorna un mensaje de error.

clear_bpbynumber(arg)

Elimina el punto de interrupción que tiene el índice arg en Breakpoint.bpbynumber. Si arg no es un valor numérico o es un indice fuera de rango, se retorna un mensaje de error.

clear_all_file_breaks(filename)

Elimina todos los puntos de interrupción en el archivo filename. Si no se ha establecido ninguno, se retorna un mensaje de error.

clear_all_breaks()

Elimina todos los puntos de interrupción que existen.

get_bpbynumber(arg)

Retorna un punto de interrupción especificado por el número dado. Si arg es una cadena de caracteres, será convertida en un número. Si arg es una cadena no numérica, o el punto de interrupción dado nunca existió o ya ha sido eliminado, se lanza una excepción ValueError.

Nuevo en la versión 3.2.

get_break(filename, lineno)

Comprueba si hay un punto de interrupción en la linea número lineno del archivo filename.

get_breaks(filename, lineno)

Retorna todos los puntos de interrupción en la linea número lineno del archivo filename, o una lista vacía si no se ha establecido ninguno.

get_file_breaks(filename)

Retorna todos los puntos de interrupción en el archivo filename, o una lista vacía si no hay ninguno establecido.

get_all_breaks()

Retorna todos los puntos de interrupción establecidos.

Las clases derivadas y clientes pueden llamar los siguientes métodos para obtener una estructura de datos que representa un seguimiento de pila.

get_stack(f, t)

Obtiene una lista de registros para un marco de ejecución y todos los marcos de ejecución superiores (que han ocasionado la llamadas previas) e inferiores, además del tamaño de la parte superior.

format_stack_entry(frame_lineno, lprefix=': ')

Retorna una cadena con información sobre una entrada de pila, identificada por una tupla de la forma (cuadro de ejecución, número de línea):

La forma canónica del nombre del archivo que contiene el marco de ejecución.

El nombre de la función o "<lambda>".

Los argumentos de entrada.

El valor de retorno.

La linea de código (si existe).

Los dos métodos descritos a continuación pueden ser llamados por los clientes para usar un depurador que se encargue de depurar un statement, proporcionado como una cadena de caracteres.

run(cmd, globals=None, locals=None)

Depura una sentencia ejecutada a través de la función exec(). globals por defecto es __main __.__ dict__, mientras que locals es globals por defecto.

runeval(expr, globals=None, locals=None)

Depura una expresión ejecutada mediante la función eval(). globals y locals tienen el mismo significado que en run().

runctx(cmd, globals, locals)

Definido solo por compatibilidad con versiones anteriores. Llama al método run().

runcall(func, /, *args, **kwds)

Depura una única llamada a función y retorna su resultado.

Por último, el módulo también define las siguientes funciones:

bdb.checkfuncname(b, frame)

Comprueba si se debería interrumpir la ejecución en éste punto, dependiendo de la forma en que se estableció el punto de interrupción b.

Si se estableció usando el número de línea, verifica si b.line es el mismo que el del marco de ejecución que también se pasó como argumento. Si el punto de interrupción se estableció mediante el nombre de la función, tenemos que comprobar que estamos en el cuadro de ejecución correcto (la función correcta) y si estamos en su primera línea ejecutable.

bdb.effective(file, line, frame)

Determina si hay un punto de interrupción efectivo (activo) en esta línea de código. Retorna una tupla con el punto de interrupción y un valor booleano que indica si es correcto eliminar un punto de interrupción temporal. Retorna (None, None) si no hay un punto de interrupción coincidente.

bdb.set_trace()

Inicia la depuración usando una instancia de Bdb, partiendo desde el marco de ejecución que realiza la llamada.

faulthandler — Volcar el rastreo de Python

Nuevo en la versión 3.3.

Este módulo contiene funciones para volcar los rastreos de Python explícitamente, en un fallo, después de un tiempo de espera o en una señal del usuario. Llame a faulthandler.enable() para instalar los gestores de fallos para las señales SIGSEGV, SIGFPE, SIGABRT, SIGBUS, y SIGILL. También puede activarlos al inicio estableciendo la variable de entorno PYTHONFAULTHANDLER o usando la opción de línea de comandos -X faulthandler.

El gestor de fallos es compatible con el gestor de fallos del sistema como Apport o el gestor de fallos de Windows. El módulo utiliza una pila alternativa para los gestores de señales si la función sigaltstack() está disponible. Esto le permite volcar el rastreo incluso en un desbordamiento de pila.

El gestor de fallos se llama en casos catastróficos y, por lo tanto, solo puede utilizar funciones seguras en señales (por ejemplo, no puede asignar memoria en el heap). Debido a esta limitación, el volcado del rastreo es mínimo comparado a los rastreos normales de Python:

Solo se soporta ASCII. El gestor de errores backslashreplace se utiliza en la codificación.

Cada cadena de caracteres está limitada a 500 caracteres.

Solo se muestran el nombre de archivo, el nombre de la función y el número de línea. (sin código fuente)

Está limitado a 100 frames y 100 hilos.

El orden se invierte: la llamada más reciente se muestra primero.

Por defecto, el rastreo de Python se escribe en sys.stderr. Para ver los rastreos, las aplicaciones deben ejecutarse en la terminal. Alternativamente se puede pasar un archivo de registro a faulthandler.enable().

El módulo está implementado en C, así los rastreos se pueden volcar en un fallo o cuando Python está en bloqueo mutuo.

El Modo de Desarrollo Python llama a failurehandler.enable() al inicio de Python.

Volcar el rastreo

faulthandler.dump_traceback(file=sys.stderr, all_threads=True)

Vuelca los rastreos de todos los hilos en el archivo file. Si all_threads es False, vuelca solo el hilo actual.

Distinto en la versión 3.5: Se añadió soporte para pasar el descriptor de archivo a esta función.

Estado del gestor de fallos

faulthandler.enable(file=sys.stderr, all_threads=True)

Activa el gestor de fallos: instala gestores para las señales SIGSEGV, SIGFPE, SIGABRT, SIGBUS y SIGILL para volcar el rastreo de Python. Si all_threads es True, produce rastreos por cada hilo activo. De lo contrario, vuelca solo el hilo actual.

El archivo file se debe mantener abierto hasta que se desactive el gestor de fallos: ver problema con descriptores de archivo.

Distinto en la versión 3.5: Se añadió soporte para pasar el descriptor de archivo a esta función.

Distinto en la versión 3.6: En Windows, también se instaló un gestor para la excepción de Windows.

faulthandler.disable()

Desactiva el gestor de fallos: desinstala los gestores de señales instalados por enable().

faulthandler.is_enabled()

Comprueba si el gestor de fallos está activado.

Volcar los rastreos después de un tiempo de espera

faulthandler.dump_traceback_later(timeout, repeat=False, file=sys.stderr, exit=False)

Vuelca los rastreos de todos los hilos, después de un tiempo de espera de timeout segundos, o cada timeout segundos si repeat es True. Si exit es True, llama a _exit() con status=1 después de volcar los rastreos. (Nota: _exit() termina el proceso inmediatamente, lo que significa que no hace ninguna limpieza como vaciar los buffers de archivos.) Si la función se llama dos veces, la nueva llamada reemplaza los parámetros previos y reinicia el tiempo de espera. El temporizador tiene una resolución de menos de un segundo.

El archivo file se debe mantener abierto hasta que se vuelque el rastreo o se llame a cancel_dump_traceback_later(): ver problema con descriptores de archivo.

Esta función está implementada utilizando un hilo vigilante.

Distinto en la versión 3.7: Ahora esta función está siempre disponible.

Distinto en la versión 3.5: Se añadió soporte para pasar el descriptor de archivo a esta función.

faulthandler.cancel_dump_traceback_later()

Cancela la última llamada a dump_traceback_later().

Volcar el rastreo en una señal del usuario

faulthandler.register(signum, file=sys.stderr, all_threads=True, chain=False)

Registra una señal del usuario: instala un gestor para la señal signum para volcar el rastreo de todos los hilos, o del hilo actual si all_threads es False, en el archivo file. Llama al gestor previo si chain es True.

El archivo file se debe mantener abierto hasta que la señal sea anulada por unregister(): ver problema con descriptores de archivo.

No está disponible en Windows.

Distinto en la versión 3.5: Se añadió soporte para pasar el descriptor de archivo a esta función.

faulthandler.unregister(signum)

Anula una señal del usuario: desinstala el gestor de la señal signum instalada por register(). Retorna True si la señal fue registrada, False en otro caso.

No está disponible en Windows.

Problema con descriptores de archivo

enable(), dump_traceback_later() y register() guardan el descriptor de archivo de su argumento file. Si se cierra el archivo y su descriptor de archivo es reutilizado por un nuevo archivo, o si se usa os.dup2() para reemplazar el descriptor de archivo, el rastreo se escribirá en un archivo diferente. Llame a estas funciones nuevamente cada vez que se reemplace el archivo.

Ejemplo

Ejemplo de un fallo de segmentación en Linux con y sin activar el gestor de fallos:

$ python3 -c "import ctypes; ctypes.string_at(0)"
Segmentation fault

$ python3 -q -X faulthandler
>>> import ctypes
>>> ctypes.string_at(0)
Fatal Python error: Segmentation fault

Current thread 0x00007fb899f39700 (most recent call first):
  File "/home/python/cpython/Lib/ctypes/__init__.py", line 486 in string_at
  File "<stdin>", line 1 in <module>
Segmentation fault

pdb — El Depurador de Python

Código fuente: Lib/unittest/mock.py [https://github.com/python/cpython/tree/3.9/Lib/unittest/mock.py]

El módulo pdb define un depurador de código fuente interactivo para programas Python. Soporta el establecimiento de puntos de ruptura (condicionales) y pasos sencillos a nivel de línea de código fuente, inspección de marcos de pila, listado de código fuente, y evaluación de código Python arbitrario en el contexto de cualquier marco de pila. También soporta depuración post-mortem y puede ser llamado bajo control del programa.

El depurador es extensible – en realidad se define como la clase Pdb. Esto no está actualmente documentado pero se entiende fácilmente leyendo la fuente. La interfaz de extensión usa los módulos bdb y cmd.

El mensaje del depurador es (Pdb). El uso típico para ejecutar un programa bajo el control del depurador es:

>>> import pdb
>>> import mymodule
>>> pdb.run('mymodule.test()')
> <string>(0)?()
(Pdb) continue
> <string>(1)?()
(Pdb) continue
NameError: 'spam'
> <string>(1)?()
(Pdb)

Distinto en la versión 3.3: La finalización de tabulación a través del módulo readline está disponible para comandos y argumentos de comando, por ejemplo. Los nombres globales y locales actuales se ofrecen como argumentos del comando p.

pdb.py también puede ser invocado como un script para depurar otros scripts. Por ejemplo:

python3 -m pdb myscript.py

Cuando se invoca como script, pdb entrará automáticamente en la depuración post-mortem si el programa que se depura sale de forma anormal. Después de la depuración post-mortem (o después de la salida normal del programa), pdb reiniciará el programa. El reinicio automático preserva el estado de pdb (como los puntos de ruptura) y en la mayoría de los casos es más útil que abandonar el depurador al salir del programa.

Nuevo en la versión 3.2: pdb.py ahora acepta una opción -c que ejecuta comandos como si se dieran en un archivo .pdbrc, ver Comandos del depurador.

Nuevo en la versión 3.7: pdb.py ahora acepta una opción -m que ejecuta módulos similares a los que python3 -m hace. Como con un script, el depurador detendrá la ejecución justo antes de la primera línea del módulo.

The typical usage to break into the debugger is to insert:

import pdb; pdb.set_trace()

at the location you want to break into the debugger, and then run the program. You can then step through the code following this statement, and continue running without the debugger using the continue command.

Nuevo en la versión 3.7: La breakpoint() incorporada cuando se llama con los valores por defecto, puede ser usado en lugar del import pdb; pdb.set_trace().

El uso típico para inspeccionar un programa que se ha estrellado es:

>>> import pdb
>>> import mymodule
>>> mymodule.test()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "./mymodule.py", line 4, in test
    test2()
  File "./mymodule.py", line 3, in test2
    print(spam)
NameError: spam
>>> pdb.pm()
> ./mymodule.py(3)test2()
-> print(spam)
(Pdb)

El módulo define las siguientes funciones; cada una de ellas entra en el depurador de una manera ligeramente diferente:

pdb.run(statement, globals=None, locals=None)

Ejecutar el statement (dado como una cadena o un objeto de código) bajo el control del depurador. El prompt del depurador aparece antes de que se ejecute cualquier código; puedes establecer puntos de ruptura y escribir continue, o puedes pasar por la declaración usando step o next (todos estos comandos se explican más abajo). Los argumentos opcionales globals y locals especifican el entorno en el que se ejecuta el código; por defecto se utiliza el diccionario del módulo __main__. (Ver la explicación de las funciones incorporadas exec() o eval()).

pdb.runeval(expression, globals=None, locals=None)

Evalúa la expression (dada como una cadena o un objeto de código) bajo el control del depurador. Cuando vuelve runeval(), retorna el valor de la expresión. En caso contrario, esta función es similar a run().

pdb.runcall(function, *args, **kwds)

Llama a la function (un objeto de función o método, no una cadena) con los argumentos dados. Cuando runcall() retorna, retorna lo que sea que la llamada de la función haya retornado. El aviso del depurador aparece tan pronto como se introduce la función.

pdb.set_trace(*, header=None)

Entra en el depurador en el marco de la pila de llamadas. Esto es útil para codificar duramente un punto de interrupción en un punto dado de un programa, incluso si el código no se depura de otra manera (por ejemplo, cuando una afirmación falla). Si se da, se imprime el header en la consola justo antes de que comience la depuración.

Distinto en la versión 3.7: El argumento de la palabra clave header.

pdb.post_mortem(traceback=None)

Ingresa a la depuración post-mortem del objeto traceback dado. Si no se da un traceback, utiliza el de la excepción que se está manejando actualmente (una excepción debe ser manejada si se va a utilizar el predeterminado).

pdb.pm()

Ingresa a la depuración post-mortem de la traza encontrada en sys.last_traceback.

Las funciones run* y set_trace() son alias para instanciar la clase Pdb y llamar al método del mismo nombre. Si quieres acceder a más funciones, tienes que hacerlo tú mismo:

class pdb.Pdb(completekey='tab', stdin=None, stdout=None, skip=None, nosigint=False, readrc=True)

Pdb es la clase de depuración.

Los argumentos completekey, stdin y stdout se pasan a la subyacente cmd.Cmd class; ver la descripción allí.

El argumento skip, si se da, debe ser un iterable de los patrones de nombre de los módulos de estilo global. El depurador no entrará en marcos que se originen en un módulo que coincida con uno de estos patrones. 1

Por defecto, Pdb establece un manejador para la señal de SIGINT (que se envía cuando el usuario presiona Ctrl-C en la consola) cuando da un comando de continue. Esto te permite entrar en el depurador de nuevo presionando Ctrl-C. Si quieres que Pdb no toque el manejador de SIGINT, pon nosigint en true.

El argumento * readrc * por defecto es verdadero y controla si Pdb cargará archivos .pdbrc desde el sistema de archivos.

Ejemplo de llamada para permitir el rastreo con skip:

import pdb; pdb.Pdb(skip=['django.*']).set_trace()

Levanta una auditing event pdb.Pdb sin argumentos.

Nuevo en la versión 3.1: El argumento skip.

Nuevo en la versión 3.2: El argumento del nosigint. Anteriormente, un manejador SIGINT nunca fue establecido por Pdb.

Distinto en la versión 3.6: El argumento readrc.

run(statement, globals=None, locals=None)

runeval(expression, globals=None, locals=None)

runcall(function, *args, **kwds)

set_trace()

Véase la documentación para las funciones explicadas anteriormente.

Comandos del depurador

Los comandos reconocidos por el depurador se enumeran a continuación. La mayoría de los comandos pueden abreviarse a una o dos letras como se indica; por ejemplo, h(elp) significa que se puede usar h o help para introducir el comando de ayuda (pero no he o hel, ni H o Help o HELP). Los argumentos de los comandos deben estar separados por espacios en blanco (espacios o tabulaciones). Los argumentos opcionales están encerrados entre corchetes ([]) en la sintaxis del comando; los corchetes no deben escribirse. Las alternativas en la sintaxis de los comandos están separadas por una barra vertical (|).

Introducir una línea en blanco repite el último comando introducido. Excepción: si el último comando fue un list comando, las siguientes 11 líneas están listadas.

Se supone que los comandos que el depurador no reconoce son declaraciones en Python y se ejecutan en el contexto del programa que se está depurando. Las declaraciones en Python también pueden ser precedidas por un signo de exclamación (!). Esta es una manera poderosa de inspeccionar el programa que se está depurando; incluso es posible cambiar una variable o llamar a una función. Cuando se produce una excepción en una sentencia de este tipo, se imprime el nombre de la excepción pero no se cambia el estado del depurador.

El depurador soporta aliases. Los alias pueden tener parámetros que permiten un cierto nivel de adaptabilidad al contexto que se está examinando.

Multiple commands may be entered on a single line, separated by ;;. (A single ; is not used as it is the separator for multiple commands in a line that is passed to the Python parser.) No intelligence is applied to separating the commands; the input is split at the first ;; pair, even if it is in the middle of a quoted string. A workaround for strings with double semicolons is to use implicit string concatenation ';'';' or ";"";".

Si un archivo .pdbrc existe en el directorio principal del usuario o en el directorio actual, se lee y se ejecuta como si se hubiera escrito en el prompt del depurador. Esto es particularmente útil para los alias. Si ambos archivos existen, el del directorio principal se lee primero y los alias definidos allí pueden ser anulados por el archivo local.

Distinto en la versión 3.2: .pdbrc puede ahora contener comandos que continúan depurando, como continue o next. Anteriormente, estos comandos no tenían ningún efecto.

h(elp) [command]

Sin argumento, imprime la lista de comandos disponibles. Con un command como argumento, imprime la ayuda sobre ese comando. help pdb muestra la documentación completa (el docstring del módulo pdb). Como el argumento command debe ser un identificador, hay que introducir help exec para obtener ayuda sobre el comando !.

w(here)

Imprime un rastro de la pila (stack trace), con el marco más reciente en la parte inferior. Una flecha indica el marco actual, que determina el contexto de la mayoría de los comandos.

d(own) [count]

Mueve los niveles del marco actual count (por defecto uno) hacia abajo en el trazado de la pila (stack trace) (a un marco más nuevo).

u(p) [count]

Mueve el marco actual count (por defecto uno) niveles hacia arriba en el trazado de la pila (stack trace) (a un marco más antiguo).

b(reak) [([filename:]lineno | function) [, condition]]

Con un argumento lineno, establece una ruptura allí en el archivo actual. Con un argumento function, establece una ruptura en la primera declaración ejecutable dentro de esa función. El número de línea puede ir precedido de un nombre de archivo y dos puntos, para especificar un punto de interrupción en otro archivo (probablemente uno que aún no se haya cargado). El archivo se busca en sys.path. Observe que a cada punto de interrupción se le asigna un número al que se refieren todos los demás comandos de puntos de interrupción.

Si un segundo argumento está presente, es una expresión que debe ser evaluada como verdadera antes de que el punto de ruptura sea honrado.

Sin argumento, enumere todas las interrupciones, incluyendo para cada punto de interrupción, el número de veces que se ha alcanzado ese punto de interrupción, el conteo de ignorancia actual y la condición asociada, si la hay.

tbreak [([filename:]lineno | function) [, condition]]

Punto de interrupción temporal, que se elimina automáticamente cuando se ejecuta por primera vez. Los argumentos son los mismos que para break.

cl(ear) [filename:lineno | bpnumber ...]

Con el argumento filename:lineno, despeja todos los puntos de interrupción en esta línea. Con una lista de números de puntos de interrupción separados por espacios, despeja esos puntos de interrupción. Sin el argumento, despeja todos los puntos de interrupción (pero primero pide confirmación).

disable [bpnumber ...]

Deshabilitar los puntos de ruptura interrupción como una lista de números de puntos de ruptura separados por espacios. Desactivar un punto de interrupción significa que no puede hacer que el programa detenga la ejecución, pero a diferencia de borrar un punto de interrupción, permanece en la lista de puntos de interrupción y puede ser (re)activado.

enable [bpnumber ...]

Habilitar los puntos de interrupción especificados.

ignore bpnumber [count]

Establece el conteo de ignorar el número de punto de interrupción dado. Si se omite el recuento, el recuento de ignorar se establece en 0. Un punto de interrupción se activa cuando el recuento de ignorar es cero. Cuando no es cero, el conteo se decrementa cada vez que se alcanza el punto de ruptura y el punto de ruptura no se desactiva y cualquier condición asociada se evalúa como verdadera.

condition bpnumber [condition]

Establece una nueva condition para el punto de interrupción, una expresión que debe evaluarse como verdadera antes de que el punto de ruptura sea honrado. Si la condición está ausente, se elimina cualquier condición existente, es decir, el punto de ruptura se hace incondicional.

commands [bpnumber]

Especifique una lista de comandos para el número del punto de interrupción bpnumber. Los comandos mismos aparecen en las siguientes líneas. Escriba una línea que contenga sólo end para terminar los comandos. Un ejemplo:

(Pdb) commands 1
(com) p some_variable
(com) end
(Pdb)

Para eliminar todos los comandos de un punto de interrupción, escribe commands y sigue inmediatamente con end , es decir, no des órdenes.

Sin el argumento bpnumber, commands se refiere al último punto de interrupción establecido.

Puede utilizar los comandos de punto de interrupción para iniciar el programa de nuevo. Simplemente usa el comando continue, o step, o cualquier otro comando que reanude la ejecución.

Al especificar cualquier comando que reanude la ejecución (actualmente continue, step, next, return, jump, quit y sus abreviaturas) se termina la lista de comandos (como si ese comando fuera inmediatamente seguido de end.) Esto se debe a que cada vez que se reanuda la ejecución (incluso con un simple siguiente o paso), puede encontrarse con otro punto de interrupción, que podría tener su propia lista de comandos, lo que conduce a ambigüedades sobre qué lista ejecutar.

Si utiliza el comando “silent” en la lista de comandos, no se imprime el mensaje habitual sobre la parada en un punto de interrupción. Esto puede ser deseable para los puntos de interrupción que deben imprimir un mensaje específico y luego continuar. Si ninguno de los otros comandos imprime nada, no se ve ninguna señal de que se haya alcanzado el punto de interrupción.

s(tep)

Ejecutar la línea actual, detenerse en la primera ocasión posible (ya sea en una función que se llame o en la siguiente línea de la función actual).

n(ext)

Continúe la ejecución hasta que se alcance la siguiente línea de la función actual o vuelva. (La diferencia entre next y step es que step se detiene dentro de una función llamada, mientras que next ejecuta las funciones llamadas a (casi) toda velocidad, deteniéndose sólo en la siguiente línea de la función actual).

unt(il) [lineno]

Sin argumento, continúe la ejecución hasta que se alcance la línea con un número mayor que el actual.

Con un número de línea, continúe la ejecución hasta que se alcance una línea con un número mayor o igual a ese. En ambos casos, también se detiene cuando vuelve la trama actual.

Distinto en la versión 3.2: Permita dar un número de línea explícito.

r(eturn)

Continúe la ejecución hasta que vuelva la función actual.

c(ont(inue))

Continúa la ejecución, sólo se detiene cuando se encuentra un punto de ruptura.

j(ump) lineno

Establezca la siguiente línea que será ejecutada. Sólo disponible en el marco de más bajo. Esto te permite saltar hacia atrás y ejecutar el código de nuevo, o saltar hacia adelante para saltar el código que no quieres ejecutar.

Cabe señalar que no todos los saltos están permitidos – por ejemplo, no es posible saltar en medio de un bucle for o fuera de una cláusula finally.

l(ist) [first[, last]]

Enumere el código fuente del archivo actual. Sin argumentos, enumere 11 líneas alrededor de la línea actual o continúe la lista anterior. Con . como argumento, enumere 11 líneas alrededor de la línea actual. Con un argumento, enumere 11 líneas alrededor de esa línea. Con dos argumentos, enumere el rango dado; si el segundo argumento es menor que el primero, se interpreta como un conteo.

La línea actual en el cuadro actual se indica con ->. Si se está depurando una excepción, la línea donde la excepción fue originalmente planteada o propagada se indica con >>, si difiere de la línea actual.

Nuevo en la versión 3.2: El marcador >> .

ll | longlist

Enumere todos los códigos fuente de la función o marco actual. Las líneas interesantes están marcadas como list.

Nuevo en la versión 3.2.

a(rgs)

Imprime la lista de argumentos de la función actual.

p expression

Evalúa la expression en el contexto actual e imprime su valor.

Nota

print() también se puede usar, pero no es un comando de depuración — esto ejecuta la función Python print().

pp expression

Como el comando p, excepto que el valor de la expresión se imprime bastante usando el módulo pprint.

whatis expression

Imprime el tipo de la expression.

source expression

Intenta obtener el código fuente del objeto dado y mostrarlo.

Nuevo en la versión 3.2.

display [expression]

Muestra el valor de la expresión si ha cambiado, cada vez que se detenga la ejecución en el marco actual.

Sin expresión, enumere todas las expresiones de visualización para el cuadro actual.

Nuevo en la versión 3.2.

undisplay [expression]

No muestren más la expresión en el cuadro actual. Sin la expresión, borre todas las expresiones de la pantalla para el marco actual.

Nuevo en la versión 3.2.

interact

Inicie un intérprete interactivo (usando el módulo code) cuyo espacio de nombres global contiene todos los nombres (globales y locales) que se encuentran en el ámbito actual.

Nuevo en la versión 3.2.

alias [name [command]]

Crear un alias llamado name que ejecute el command. El comando no debe estar entre comillas. Los parámetros reemplazables pueden ser indicados por %1, %2, y así sucesivamente, mientras que %* es reemplazado por todos los parámetros. Si no se da ningún comando, se muestra el alias actual de name. Si no se dan argumentos, se muestran todos los alias.

Los alias pueden anidarse y pueden contener cualquier cosa que se pueda teclear legalmente en el prompt de pdb. Tenga en cuenta que los comandos internos de pdb pueden ser anulados por los alias. Dicho comando se oculta hasta que se elimina el alias. El alias se aplica de forma recursiva a la primera palabra de la línea de comandos; todas las demás palabras de la línea se dejan en paz.

Como ejemplo, aquí hay dos alias útiles (especialmente cuando se colocan en el archivo .pdbrc):

# Print instance variables (usage "pi classInst")
alias pi for k in %1.__dict__.keys(): print("%1.",k,"=",%1.__dict__[k])
# Print instance variables in self
alias ps pi self

unalias name

Elimine el alias especificado.

! statement

Ejecute (una línea) statement en el contexto del marco de la pila actual. El signo de exclamación puede ser omitido a menos que la primera palabra de la declaración se parezca a un comando de depuración. Para establecer una variable global, puede anteponer al comando de asignación una declaración global en la misma línea, por ejemplo:

(Pdb) global list_options; list_options = ['-l']
(Pdb)

run [args ...]

restart [args ...]

Reinicie el programa Python depurado. Si se suministra un argumento, se divide con shlex y el resultado se utiliza como el nuevo sys.argv. Se conservan el historial, los puntos de interrupción, las acciones y las opciones del depurador. restart es un alias de run.

q(uit)

Salga del depurador. El programa que se está ejecutando fue abortado.

debug code

Introduce un depurador recursivo que pasa por el argumento del código (que es una expresión o declaración arbitraria que debe ejecutarse en el entorno actual).

retval

Print the return value for the last return of a function.

Notas de pie de página

1

Si se considera que un marco se origina en un determinado módulo se determina por el __name__ en el marcos globales.

Los perfiladores de Python

Código fuente: Lib/profile.py [https://github.com/python/cpython/tree/3.9/Lib/profile.py] y Lib/pstats.py [https://github.com/python/cpython/tree/3.9/Lib/pstats.py]

Introducción a los perfiladores

cProfile y profile proporcionan deterministic profiling de los programas de Python. profile es un conjunto de estadísticas que describe con qué frecuencia y durante cuánto tiempo se ejecutaron varias partes del programa. Estas estadísticas pueden formatearse en informes a través del módulo pstats.

La biblioteca estándar de Python proporciona dos implementaciones diferentes de la misma interfaz de creación de perfiles:

cProfile se recomienda para la mayoría de los usuarios; Es una extensión C con una sobrecarga razonable que la hace adecuada para perfilar programas de larga duración. Basado en lsprof, aportado por Brett Rosen y Ted Czotter.

profile, un módulo Python puro cuya interfaz es imitada por cProfile, pero que agrega una sobrecarga significativa a los programas perfilados. Si está intentando extender el generador de perfiles de alguna manera, la tarea podría ser más fácil con este módulo. Originalmente diseñado y escrito por Jim Roskind.

Nota

Los módulos del generador de perfiles están diseñados para proporcionar un perfil de ejecución para un programa determinado, no para fines de evaluación comparativa (para eso, está timeit que permite obtener resultados razonablemente precisos). Esto se aplica particularmente a la evaluación comparativa del código Python contra el código C: los perfiladores introducen gastos generales para el código Python, pero no para las funciones de nivel C, por lo que el código C parecería más rápido que cualquier Python.

Manual instantáneo de usuario

Esta sección se proporciona a los usuarios que «no quieren leer el manual». Proporciona una visión general muy breve y permite a un usuario realizar perfiles rápidamente en una aplicación existente.

Para perfilar una función que toma un solo argumento, puede hacer:

import cProfile
import re
cProfile.run('re.compile("foo|bar")')

(Use profile en lugar de cProfile si este último no está disponible en su sistema.)

La acción anterior ejecutaría re.compile() e imprime resultados de perfil como los siguientes:

      197 function calls (192 primitive calls) in 0.002 seconds

Ordered by: standard name

ncalls  tottime  percall  cumtime  percall filename:lineno(function)
     1    0.000    0.000    0.001    0.001 <string>:1(<module>)
     1    0.000    0.000    0.001    0.001 re.py:212(compile)
     1    0.000    0.000    0.001    0.001 re.py:268(_compile)
     1    0.000    0.000    0.000    0.000 sre_compile.py:172(_compile_charset)
     1    0.000    0.000    0.000    0.000 sre_compile.py:201(_optimize_charset)
     4    0.000    0.000    0.000    0.000 sre_compile.py:25(_identityfunction)
   3/1    0.000    0.000    0.000    0.000 sre_compile.py:33(_compile)

La primera línea indica que se monitorearon 197 llamadas. De esas llamadas, 192 fueron primitive, lo que significa que la llamada no fue inducida por recursividad. La siguiente línea: Ordered by: standard name, indica que la cadena de texto en la columna del extremo derecho se utilizó para ordenar la salida. Los encabezados de columna incluyen:

ncalls

por el número de llamadas.

tottime

para el tiempo total empleado en la función dada (y excluyendo el tiempo realizado en llamadas a subfunciones)

percall

es el cociente de tottime dividido por ncalls

cumtime

es el tiempo acumulado empleado en esta y todas las subfunciones (desde la invocación hasta la salida). Esta cifra es precisa incluso para funciones recursivas.

percall

es el cociente de cumtime dividido por llamadas primitivas

filename:lineno(function)

proporciona los datos respectivos de cada función

Cuando hay dos números en la primera columna (por ejemplo, 3/1), significa que la función se repite. El segundo valor es el número de llamadas primitivas y el primero es el número total de llamadas. Tenga en cuenta que cuando la función no se repite, estos dos valores son iguales y solo se imprime la figura.

En lugar de imprimir la salida al final de la ejecución del perfil, puede guardar los resultados en un archivo especificando un nombre de archivo en la función run():

import cProfile
import re
cProfile.run('re.compile("foo|bar")', 'restats')

La clase pstats.Stats lee los resultados del perfil desde un archivo y los formatea de varias maneras.

Los archivos cProfile y profile también se pueden invocar como un script para perfilar otro script. Por ejemplo:

python -m cProfile [-o output_file] [-s sort_order] (-m module | myscript.py)

-o escribe los resultados del perfil en un archivo en lugar de stdout

-s especifica uno de los valores de clasificación sort_stats() para ordenar la salida. Esto solo se aplica cuando -o no se suministra.

-m especifica que se está perfilando un módulo en lugar de un script.

Nuevo en la versión 3.7: Se agregó la opción -m a cProfile.

Nuevo en la versión 3.8: Se agregó la opción -m a profile.

Los módulos pstats clase Stats tienen una variedad de métodos para manipular e imprimir los datos guardados en un archivo de resultados de perfil:

import pstats
from pstats import SortKey
p = pstats.Stats('restats')
p.strip_dirs().sort_stats(-1).print_stats()

El método strip_dirs() eliminó la ruta extraña de todos los nombres de módulos. El método sort_stats() clasificó todas las entradas de acuerdo con el módulo/línea/nombre de cadena de caracteres estándar que se imprime. El método print_stats() imprimió todas las estadísticas. Puede intentar las siguientes llamadas de clasificación:

p.sort_stats(SortKey.NAME)
p.print_stats()

La primera llamada realmente ordenará la lista por nombre de función, y la segunda llamada imprimirá las estadísticas. Las siguientes son algunas llamadas interesantes para experimentar:

p.sort_stats(SortKey.CUMULATIVE).print_stats(10)

Esto ordena el perfil por tiempo acumulado en una función y luego solo imprime las diez líneas más significativas. Si desea comprender qué algoritmos están tomando tiempo, la línea anterior es lo que usaría.

Si estuviera buscando ver qué funciones se repetían mucho y toman mucho tiempo, usted haría:

p.sort_stats(SortKey.TIME).print_stats(10)

para ordenar según el tiempo dedicado a cada función y luego imprimir las estadísticas de las diez funciones principales.

También puedes probar:

p.sort_stats(SortKey.FILENAME).print_stats('__init__')

Esto ordenará todas las estadísticas por nombre de archivo y luego imprimirá estadísticas solo para los métodos de inicio de clase (ya que están escritos con __init__ en ellos). Como último ejemplo, puedes probar:

p.sort_stats(SortKey.TIME, SortKey.CUMULATIVE).print_stats(.5, 'init')

Esta línea clasifica las estadísticas con una clave primaria de tiempo y una clave secundaria de tiempo acumulado, y luego imprime algunas de las estadísticas. Para ser específicos, la lista primero se reduce al 50% (re: .5) de su tamaño original, luego solo se mantienen las líneas que contienen `init y se imprime esa sub-sublista.

Si se preguntó qué funciones denominaban las funciones anteriores, ahora podría (p todavía está ordenada según el último criterio) hacer:

p.print_callers(.5, 'init')

y obtendría una lista de llamadas para cada una de las funciones enumeradas.

Si desea más funcionalidad, tendrá que leer el manual o adivinar lo que hacen las siguientes funciones:

p.print_callees()
p.add('restats')

Invocado como un script, el módulo pstats es un navegador de estadísticas para leer y examinar volcados de perfil. Tiene una interfaz simple orientada a la línea de comandos (implementada usando cmd) y ayuda interactiva.

Referencia del módulo profile y cProfile

Los módulos profile y cProfile proporcionan las siguientes funciones:

profile.run(command, filename=None, sort=-1)

Esta función toma un único argumento que se puede pasar a la función exec() y un nombre de archivo opcional. En todos los casos esta rutina ejecuta:

exec(command, __main__.__dict__, __main__.__dict__)

y recopila estadísticas de perfiles de la ejecución. Si no hay ningún nombre de archivo, esta función crea automáticamente una instancia de Stats e imprime un informe de perfil simple. Si se especifica el valor de clasificación, se pasa a esta instancia Stats para controlar cómo se ordenan los resultados.

profile.runctx(command, globals, locals, filename=None, sort=-1)

Esta función es similar a run(), con argumentos agregados para proporcionar los diccionarios globales y locales para la cadena de caracteres command. Esta rutina ejecuta:

exec(command, globals, locals)

y recopila estadísticas de perfiles como en la función run() anterior.

class profile.Profile(timer=None, timeunit=0.0, subcalls=True, builtins=True)

Esta clase normalmente solo es usada si se necesita un control más preciso sobre la creación de perfiles que el que proporciona la función cProfile.run().

Se puede suministrar un temporizador personalizado para medir cuánto tiempo tarda el código en ejecutarse mediante el argumento timer. Esta debe ser una función que retorna un solo número que representa la hora actual. Si el número es un entero, la timeunit especifica un multiplicador que especifica la duración de cada unidad de tiempo. Por ejemplo, si el temporizador retorna tiempos medidos en miles de segundos, la unidad de tiempo sería .001.

El uso directo de la clase Profile permite formatear los resultados del perfil sin escribir los datos del perfil en un archivo:

import cProfile, pstats, io
from pstats import SortKey
pr = cProfile.Profile()
pr.enable()
# ... do something ...
pr.disable()
s = io.StringIO()
sortby = SortKey.CUMULATIVE
ps = pstats.Stats(pr, stream=s).sort_stats(sortby)
ps.print_stats()
print(s.getvalue())

La clase Profile también se puede usar como administrador de contexto (solo se admite en el módulo cProfile. Ver Tipos Gestores de Contexto):

import cProfile

with cProfile.Profile() as pr:
    # ... do something ...

pr.print_stats()

Distinto en la versión 3.8: Se agregó soporte de administrador de contexto.

enable()

Comienza a recopilar datos de perfiles. Solo en cProfile.

disable()

Deja de recopilar datos de perfiles. Solo en cProfile.

create_stats()

Deja de recopilar datos de perfiles y registre los resultados internamente como el perfil actual.

print_stats(sort=-1)

Crea un objeto Stats en función del perfil actual e imprima los resultados en stdout.

dump_stats(filename)

Escribe los resultados del perfil actual en filename.

run(cmd)

Perfila el cmd a través de exec().

runctx(cmd, globals, locals)

Perfila el cmd a través de exec() con el entorno global y local especificado.

runcall(func, /, *args, **kwargs)

Perfila func(*args, **kwargs)

Tenga en cuenta que la creación de perfiles solo funcionará si el comando/función llamado realmente regresa. Si el intérprete se termina (por ejemplo, a través de una llamada a sys.exit() durante la ejecución del comando/función llamado) no se imprimirán resultados de generación de perfiles.

La clase Stats

El análisis de los datos del generador de perfiles es realizado utilizando la clase Stats.

class pstats.Stats(*filenames or profile, stream=sys.stdout)

Este constructor de clase crea una instancia de un «objeto de estadísticas» a partir de un filename (o una lista de nombres de archivo) o de una instancia Profile. La salida se imprimirá en la secuencia especificada por stream.

El archivo seleccionado por el constructor anterior debe haber sido creado por la versión correspondiente de profile o cProfile. Para ser específicos, no hay compatibilidad de archivos garantizada con futuras versiones de este generador de perfiles, y no hay compatibilidad con archivos producidos por otros perfiladores, o el mismo generador de perfiles ejecutado en un sistema operativo diferente. Si se proporcionan varios archivos, se combinarán todas las estadísticas para funciones idénticas, de modo que se pueda considerar una vista general de varios procesos en un solo informe. Si es necesario combinar archivos adicionales con datos en un objeto existente Stats, se puede usar el método add().

En lugar de leer los datos del perfil de un archivo, se puede usar un objeto cProfile.Profile o profile.Profile como fuente de datos del perfil.

los objetos Stats tienen los siguientes métodos:

strip_dirs()

Este método para la clase Stats elimina toda la información de ruta principal de los nombres de archivo. Es muy útil para reducir el tamaño de la impresión para que quepa en (cerca de) 80 columnas. Este método modifica el objeto y se pierde la información eliminada. Después de realizar una operación de tira, se considera que el objeto tiene sus entradas en un orden «aleatorio», como lo fue justo después de la inicialización y carga del objeto. Si strip_dirs() hace que dos nombres de funciones no se puedan distinguir (están en la misma línea del mismo nombre de archivo y tienen el mismo nombre de función), entonces las estadísticas para estas dos entradas se acumulan en un sola entrada.

add(*filenames)

Este método de la clase Stats acumula información de perfil adicional en el objeto de perfil actual. Sus argumentos deben referirse a los nombres de archivo creados por la versión correspondiente de profile.run() or cProfile.run(). Las estadísticas para funciones con nombre idéntico (re: archivo, línea, nombre) se acumulan automáticamente en estadísticas de función única.

dump_stats(filename)

Guarda los datos cargados en el objeto Stats en un archivo llamado filename. El archivo se crea si no existe y se sobrescribe si ya existe. Esto es equivalente al método del mismo nombre en las clases: class profile.Profile y cProfile.Profile.

sort_stats(*keys)

Este método modifica el objeto Stats ordenándolo de acuerdo con los criterios proporcionados. El argumento puede ser una cadena de caracteres o una enumeración SortKey que identifica la base de una clasificación (ejemplo: 'time', 'name', SortKey.TIME o SortKey.NAME). El argumento enumeraciones SortKey tiene ventaja sobre el argumento de cadena de caracteres en que es más robusto y menos propenso a errores.

Cuando se proporciona más de una llave, se utilizan llaves adicionales como criterios secundarios cuando hay igualdad en todas las llaves seleccionadas antes que ellas. Por ejemplo, sort_stats(SortKey.NAME, SortKey.FILE) ordenará todas las entradas de acuerdo con el nombre de su función y resolverá todos los vínculos (nombres de función idénticos) clasificándolos por nombre de archivo.

Para el argumento de cadena de caracteres, se pueden usar abreviaturas para cualquier nombre de llaves, siempre que la abreviatura no sea ambigua.

Los siguientes son la cadena de caracteres válida y SortKey:

Arg de cadena de caracteres válido

Arg de enumeración válido

Significado

'calls'

SortKey.CALLS

recuento de llamadas

'cumulative'

SortKey.CUMULATIVE

tiempo acumulado

'cumtime'

N/A

tiempo acumulado

'file'

N/A

nombre de archivo

'filename'

SortKey.FILENAME

nombre de archivo

'module'

N/A

nombre de archivo

'ncalls'

N/A

recuento de llamadas

'pcalls'

SortKey.PCALLS

recuento de llamadas primitivas

'line'

SortKey.LINE

número de línea

'name'

SortKey.NAME

nombre de la función

'nfl'

SortKey.NFL

nombre/archivo/línea

'stdname'

SortKey.STDNAME

nombre estándar

'time'

SortKey.TIME

tiempo interno

'tottime'

N/A

tiempo interno

Tenga en cuenta que todos los tipos de estadísticas están en orden descendente (colocando primero los elementos que requieren más tiempo), donde las búsquedas de nombre, archivo y número de línea están en orden ascendente (alfabético). La sutil distinción entre SortKey.NFL y SortKey.STDNAME es que el nombre estándar es una especie de nombre tal como está impreso, lo que significa que los números de línea incrustados se comparan de manera extraña. Por ejemplo, las líneas 3, 20 y 40 aparecerían (si los nombres de los archivos fueran los mismos) en el orden de las cadenas 20, 3 y 40. En contraste, SortKey.NFL hace una comparación numérica de los números de línea. De hecho, sort_stats(SortKey.NFL) es lo mismo que sort_stats(SortKey.NAME, SortKey.FILENAME, SortKey.LINE).

Por razones de compatibilidad con versiones anteriores, se permiten los argumentos numéricos -1, 0, 1, y 2. Se interpretan como 'stdname', 'calls', 'time', y 'cumulative' respectivamente. Si se usa este formato de estilo antiguo (numérico), solo se usará una clave de clasificación (la tecla numérica) y los argumentos adicionales se ignorarán en silencio.

Nuevo en la versión 3.7: Enumeración SortKey añadida.

reverse_order()

Este método para la clase Stats invierte el orden de la lista básica dentro del objeto. Tenga en cuenta que, de forma predeterminada, el orden ascendente vs descendente se selecciona correctamente en función de la llave de clasificación elegida.

print_stats(*restrictions)

Este método para la clase Stats imprime un informe como se describe en la definición profile.run().

El orden de la impresión se basa en la última operación sort_stats() realizada en el objeto (sujeto a advertencias en add() y strip_dirs()).

Los argumentos proporcionados (si los hay) se pueden usar para limitar la lista a las entradas significativas. Inicialmente, se considera que la lista es el conjunto completo de funciones perfiladas. Cada restricción es un número entero (para seleccionar un recuento de líneas), o una fracción decimal entre 0.0 y 1.0 inclusive (para seleccionar un porcentaje de líneas), o una cadena que se interpretará como una expresión regular (para que el patrón coincida con el nombre estándar eso está impreso). Si se proporcionan varias restricciones, se aplican secuencialmente. Por ejemplo:

print_stats(.1, 'foo:')

primero limitaría la impresión al primer 10% de la lista, y luego solo imprimiría las funciones que formaban parte del nombre del archivo .*foo:. En contraste, el comando:

print_stats('foo:', .1)

limitaría la lista a todas las funciones que tengan nombres de archivo: archivo .*foo:, y luego procedería a imprimir solo el primer 10% de ellas.

print_callers(*restrictions)

Este método para la clase Stats imprime una lista de todas las funciones que llamaron a cada función en la base de datos perfilada. El orden es idéntico al proporcionado por print_stats(), y la definición del argumento de restricción también es idéntica. Cada persona que llama se informa en su propia línea. El formato difiere ligeramente según el generador de perfiles que produjo las estadísticas:

Con profile, se muestra un número entre paréntesis después de cada llamada para mostrar cuántas veces se realizó esta llamada específica. Por conveniencia, un segundo número sin paréntesis repite el tiempo acumulado empleado en la función de la derecha.

Con cProfile, cada persona que llama está precedida por tres números: la cantidad de veces que se realizó esta llamada específica y los tiempos totales y acumulativos gastados en la función actual mientras fue invocada por esta persona que llama.

print_callees(*restrictions)

Este método para la clase Stats imprime una lista de todas las funciones que fueron llamadas por la función indicada. Aparte de esta inversión de la dirección de las llamadas (re: llamado vs fue llamado por), los argumentos y el orden son idénticos al método print_callers().

get_stats_profile()

Este método retorna una instancia de StatsProfile, la cual contiene un mapeo de nombres de función a instancias de FunctionProfile. Cada instancia de FunctionProfile mantiene información relacionada al perfil de la función, como cuánto demoró la función en ejecutarse, cuantas veces fue llamada, etc…

Nuevo en la versión 3.9: Añadidas las siguientes clases de datos: StatsProfile, FunctionProfile. Añadida la siguiente función: get_stats_profile.

¿Qué es el perfil determinista?

Deterministic profiling está destinada a reflejar el hecho de que se supervisan todos los eventos function call, function return, y exception, y se realizan temporizaciones precisas para los intervalos entre estos eventos (durante los cuales el código del usuario se está ejecutando). Por el contrario, statistical profiling (que no se realiza en este módulo) muestrea aleatoriamente el puntero de instrucción efectivo y deduce dónde se está gastando el tiempo. La última técnica tradicionalmente implica menos sobrecarga (ya que el código no necesita ser instrumentado), pero proporciona solo indicaciones relativas de dónde se está gastando el tiempo.

En Python, dado que hay un intérprete activo durante la ejecución, no se requiere la presencia de código instrumentado para realizar un perfil determinista. Python proporciona automáticamente un hook (retrollamada opcional) para cada evento. Además, la naturaleza interpretada de Python tiende a agregar tanta sobrecarga a la ejecución, que los perfiles deterministas tienden a agregar solo una pequeña sobrecarga de procesamiento en aplicaciones típicas. El resultado es que el perfil determinista no es tan costoso, pero proporciona estadísticas extensas de tiempo de ejecución sobre la ejecución de un programa Python.

Las estadísticas de recuento de llamadas se pueden usar para identificar errores en el código (recuentos sorprendentes) e identificar posibles puntos de expansión en línea (recuentos altos de llamadas). Las estadísticas de tiempo interno se pueden utilizar para identificar «bucles activos» que deben optimizarse cuidadosamente. Las estadísticas de tiempo acumulativo deben usarse para identificar errores de alto nivel en la selección de algoritmos. Tenga en cuenta que el manejo inusual de los tiempos acumulativos en este generador de perfiles permite que las estadísticas de implementaciones recursivas de algoritmos se comparen directamente con implementaciones iterativas.

Limitaciones

Una limitación tiene que ver con la precisión de la información de sincronización. Hay un problema fundamental con los perfiladores deterministas que implican precisión. La restricción más obvia es que el «reloj» subyacente solo funciona a una velocidad (típicamente) de aproximadamente 0,001 segundos. Por lo tanto, ninguna medición será más precisa que el reloj subyacente. Si se toman suficientes medidas, entonces el «error» tenderá a promediar. Desafortunadamente, eliminar este primer error induce una segunda fuente de error.

El segundo problema es que «lleva un tiempo» desde que se distribuye un evento hasta que la llamada del generador de perfiles para obtener la hora en realidad obtiene el estado del reloj. Del mismo modo, hay un cierto retraso al salir del controlador de eventos del generador de perfiles desde el momento en que se obtuvo el valor del reloj (y luego se retiró), hasta que el código del usuario se está ejecutando nuevamente. Como resultado, las funciones que se llaman muchas veces, o llaman a muchas funciones, generalmente acumularán este error. El error que se acumula de esta manera es típicamente menor que la precisión del reloj (menos de un tic de reloj), pero puede acumularse y volverse muy significativo.

El problema es más importante con profile que con la sobrecarga inferior cProfile. Por esta razón, profile proporciona un medio para calibrarse a sí mismo para una plataforma dada para que este error pueda ser eliminado probabilísticamente (en promedio). Después de calibrar el generador de perfiles, será más preciso (en un sentido al menos cuadrado), pero a veces producirá números negativos (cuando el recuento de llamadas es excepcionalmente bajo y los dioses de la probabilidad trabajan en su contra :-) ) No se alarme por los números negativos en el perfil. Deberían aparecer solo si ha calibrado su generador de perfiles, y los resultados son realmente mejores que sin calibración.

Calibración

El generador de perfiles del módulo profile resta una constante de cada tiempo de manejo de eventos para compensar la sobrecarga de llamar a la función de tiempo y eliminar los resultados. Por defecto, la constante es 0. El siguiente procedimiento se puede usar para obtener una mejor constante para una plataforma dada (ver Limitaciones).

import profile
pr = profile.Profile()
for i in range(5):
    print(pr.calibrate(10000))

The method executes the number of Python calls given by the argument, directly and again under the profiler, measuring the time for both. It then computes the hidden overhead per profiler event, and returns that as a float. For example, on a 1.8Ghz Intel Core i5 running macOS, and using Python’s time.process_time() as the timer, the magical number is about 4.04e-6.

El objetivo de este ejercicio es obtener un resultado bastante consistente. Si su computadora es muy rápida, o su función de temporizador tiene una resolución pobre, es posible que tenga que pasar 100000, o incluso 1000000, para obtener resultados consistentes.

Cuando tiene una respuesta consistente, hay tres formas de usarla:

import profile

# 1. Apply computed bias to all Profile instances created hereafter.
profile.Profile.bias = your_computed_bias

# 2. Apply computed bias to a specific Profile instance.
pr = profile.Profile()
pr.bias = your_computed_bias

# 3. Specify computed bias in instance constructor.
pr = profile.Profile(bias=your_computed_bias)

Si tiene una opción, es mejor que elija una constante más pequeña, y luego sus resultados «con menos frecuencia» se mostrarán como negativos en las estadísticas del perfil.

Usando un temporizador personalizado

Si desea cambiar la forma en que se determina el tiempo actual (por ejemplo, para forzar el uso del tiempo del reloj de pared o el tiempo transcurrido del proceso), pase la función de temporización que desee a la clase constructora Profile:

pr = profile.Profile(your_time_func)

El generador de perfiles resultante llamará a your_time_func. Dependiendo de si está utilizando profile.Profile o cProfile.Profile, el valor de retorno de your_time_func se interpretará de manera diferente:

profile.Profile

your_time_func debería retornar un solo número o una lista de números cuya suma es la hora actual (como lo que os.times() retorna). Si la función retorna un número de tiempo único o la lista de números retornados tiene una longitud de 2, obtendrá una versión especialmente rápida de la rutina de envío.

Tenga en cuenta que debe calibrar la clase de generador de perfiles para la función de temporizador que elija (consulte Calibración). Para la mayoría de las máquinas, un temporizador que retorna un valor entero solitario proporcionará los mejores resultados en términos de baja sobrecarga durante la creación de perfiles. (os.times() es bastante malo, ya que retorna una tupla de valores de coma flotante). Si desea sustituir un temporizador mejor de la manera más limpia, obtenga una clase y conecte un método de envío de reemplazo que maneje mejor su llamada de temporizador, junto con la constante de calibración adecuada.

cProfile.Profile

your_time_func debería retornar un solo número. Si retorna enteros, también puede invocar al constructor de la clase con un segundo argumento que especifique la duración real de una unidad de tiempo. Por ejemplo, si your_integer_time_func retorna tiempos medidos en miles de segundos, construiría la instancia Profile de la siguiente manera:

pr = cProfile.Profile(your_integer_time_func, 0.001)

Como la clase cProfile.Profile no se puede calibrar, las funciones de temporizador personalizadas deben usarse con cuidado y deben ser lo más rápidas posible. Para obtener los mejores resultados con un temporizador personalizado, puede ser necesario codificarlo en la fuente C del módulo interno _lsprof.

Python 3.3 agrega varias funciones nuevas en time que se puede usar para realizar mediciones precisas del proceso o el tiempo del reloj de pared (wall-clock time). Por ejemplo, vea time.perf_counter().

timeit — Mide el tiempo de ejecución de pequeños fragmentos de código

Código fuente: Lib/timeit.py [https://github.com/python/cpython/tree/3.9/Lib/timeit.py]

This module provides a simple way to time small bits of Python code. It has both a Interfaz de línea de comandos as well as a callable one. It avoids a number of common traps for measuring execution times. See also Tim Peters” introduction to the «Algorithms» chapter in the second edition of Python Cookbook, published by O’Reilly.

Ejemplos básicos

En el ejemplo siguiente se muestra cómo se puede utilizar Interfaz de línea de comandos para comparar tres expresiones diferentes:

$ python3 -m timeit '"-".join(str(n) for n in range(100))'
10000 loops, best of 5: 30.2 usec per loop
$ python3 -m timeit '"-".join([str(n) for n in range(100)])'
10000 loops, best of 5: 27.5 usec per loop
$ python3 -m timeit '"-".join(map(str, range(100)))'
10000 loops, best of 5: 23.2 usec per loop

Esto se puede lograr desde Interfaz de Python con:

>>> import timeit
>>> timeit.timeit('"-".join(str(n) for n in range(100))', number=10000)
0.3018611848820001
>>> timeit.timeit('"-".join([str(n) for n in range(100)])', number=10000)
0.2727368790656328
>>> timeit.timeit('"-".join(map(str, range(100)))', number=10000)
0.23702679807320237

Un invocable también se puede pasar desde el Interfaz de Python:

>>> timeit.timeit(lambda: "-".join(map(str, range(100))), number=10000)
0.19665591977536678

Sin embargo, tenga en cuenta que timeit() determinará automáticamente el número de repeticiones solo cuando se utiliza la interfaz de línea de comandos. En la sección Ejemplos puede encontrar ejemplos más avanzados.

Interfaz de Python

El módulo define tres funciones de conveniencia y una clase pública:

timeit.timeit(stmt='pass', setup='pass', timer=<default timer>, number=1000000, globals=None)

Cree una instancia de Timer con la instrucción dada, el código setup y la función timer y ejecute su método timeit() con las ejecuciones number. El argumento globals opcional especifica un espacio de nombres en el que se ejecutará el código.

Distinto en la versión 3.5: El parámetro opcional globals fue añadido.

timeit.repeat(stmt='pass', setup='pass', timer=<default timer>, repeat=5, number=1000000, globals=None)

Crea una instancia de Timer con la instrucción dada, el código setup y la función timer y ejecuta su método repeat() con las ejecuciones repeat y number dadas. El argumento globals opcional especifica un espacio de nombres en el que se ejecutará el código.

Distinto en la versión 3.5: El parámetro opcional globals fue añadido.

Distinto en la versión 3.7: El valor por defecto para repeat cambió de 3 a 5.

timeit.default_timer()

El temporizador por defecto, que es siempre time.perf_counter().

Distinto en la versión 3.3: time.perf_counter() es ahora el temporizador por defecto.

class timeit.Timer(stmt='pass', setup='pass', timer=<timer function>, globals=None)

Clase para la velocidad de tiempo de ejecución de pequeños fragmentos de código.

El constructor toma una instrucción que se cronometra, una instrucción adicional utilizada para la instalación, y una función de temporizador. Ambas instrucciones tienen como valor predeterminado 'pass'; la función del temporizador depende de la plataforma (consulte la cadena doc del módulo). stmt y setup también pueden contener varias instrucciones separadas por ; o líneas nuevas, siempre y cuando no contengan literales de cadena de varias líneas. La instrucción se ejecutará de forma predeterminada dentro del espacio de nombres timeit; este comportamiento se puede controlar pasando un espacio de nombres a globals.

Para medir el tiempo de ejecución de la primera instrucción, utilice el método timeit(). Los métodos repeat() y autorange() son métodos de conveniencia para llamar al método timeit() varias veces.

El tiempo de ejecución de setup se excluye de la ejecución de tiempo total.

Los parámetros stmt y setup también pueden tomar objetos a los que se puede llamar sin argumentos. Esto embebe llamadas a ellos en una función de temporizador que luego será ejecutada por timeit(). Tenga en cuenta que la sobrecarga de tiempo es un poco mayor en este caso debido a las llamadas de función adicionales.

Distinto en la versión 3.5: El parámetro opcional globals fue añadido.

timeit(number=1000000)

Tiempo number ejecuciones de la instrucción principal. Esto ejecuta la instrucción setup una vez y, a continuación, retorna el tiempo que se tarda en ejecutar la instrucción principal varias veces, medida en segundos como un float. El argumento es el número de veces que se ejecuta el bucle, por defecto a un millón. La instrucción principal, la instrucción setup y la función timer que se va a utilizar se pasan al constructor.

Nota

De forma predeterminada, timeit() desactiva temporalmente garbage collection durante la medición. La ventaja de este enfoque es que hace que los tiempos independientes sean más comparables. La desventaja es que GC puede ser un componente importante del rendimiento de la función que se está midiendo. Si es así, GC se puede volver a habilitar como la primera instrucción en la cadena setup. Por ejemplo:

timeit.Timer('for i in range(10): oct(i)', 'gc.enable()').timeit()

autorange(callback=None)

Determina automáticamente cuántas veces llamar a timeit().

Esta es una función de conveniencia que llama a timeit() repetidamente para que el tiempo total >= 0,2 segundos, retornando el eventual (número de bucles, tiempo tomado para ese número de bucles). Este método llama a timeit() con números crecientes de la secuencia 1, 2, 5, 10, 20, 50, … hasta que el tiempo necesario sea de al menos 0.2 segundos.

Si callback se da y no es None, se llamará después de cada prueba con dos argumentos: callback(number, time_taken).

Nuevo en la versión 3.6.

repeat(repeat=5, number=1000000)

Llama a timeit() algunas veces.

Esta es una función de conveniencia que llama a timeit() repetidamente, retornando una lista de resultados. El primer argumento especifica cuántas veces se debe llamar a timeit(). El segundo argumento especifica el argumento number para timeit().

Nota

Es tentador calcular la media y la desviación estándar del vector de resultados e informar de estos. Sin embargo, esto no es muy útil. En un caso típico, el valor más bajo proporciona un límite inferior para la rapidez con la que el equipo puede ejecutar el fragmento de código especificado; valores más altos en el vector de resultado normalmente no son causados por la variabilidad en la velocidad de Python, sino por otros procesos que interfieren con su precisión de sincronización. Así que el min() del resultado es probablemente el único número que debería estar interesado en. Después de eso, usted debe mirar todo el vector y aplicar el sentido común en lugar de las estadísticas.

Distinto en la versión 3.7: El valor por defecto para repeat cambió de 3 a 5.

print_exc(file=None)

Ayudante para imprimir un seguimiento desde el código cronometrado.

Uso típico:

t = Timer(...)       # outside the try/except
try:
    t.timeit(...)    # or t.repeat(...)
except Exception:
    t.print_exc()

La ventaja sobre el seguimiento estándar es que se mostrarán las líneas de origen de la plantilla compilada. El argumento opcional file dirige dónde se envía el seguimiento; por defecto a sys.stderr.

Interfaz de línea de comandos

Cuando se llama como un programa desde la línea de comandos, se utiliza el siguiente formulario:

python -m timeit [-n N] [-r N] [-u U] [-s S] [-h] [statement ...]

Cuando las siguientes opciones son entendidas:

-n N, --number=N

cuantas veces para ejecutar “statement”

-r N, --repeat=N

cuantas veces se va a repetir el temporizador (predeterminado 5)

-s S, --setup=S

instrucción a ser ejecutada una vez inicialmente (por defecto pass)

-p, --process

mide el tiempo de proceso, no el tiempo total de ejecución, utilizando time.process_time() en lugar de time.perf_counter(), que es el valor predeterminado

Nuevo en la versión 3.3.

-u, --unit=U

especifica una unidad de tiempo para la salida del temporizador; puede ser nsec, usec, msec o sec

Nuevo en la versión 3.5.

-v, --verbose

imprime los resultados de tiempo en bruto; repetir para más dígitos de precisión

-h, --help

imprime un mensaje de uso corto y sale

Se puede dar una instrucción de varias líneas especificando cada línea como un argumento de instrucción independiente; Las líneas con sangría son posibles entrecomillando un argumento y utilizando espacios iniciales. Múltiples opciones -s se tratan de forma similar.

Si no se da -n, se calcula un número adecuado de bucles intentando aumentar los números de la secuencia 1, 2, 5, 10, 20, 50, … hasta que el tiempo total sea de al menos 0.2 segundos.

Las mediciones de default_timer() pueden verse afectadas por otros programas que se ejecutan en la misma máquina, por lo que lo mejor que se puede hacer cuando es necesario una medición de tiempo precisa es repetir la medición un par de veces y utilizar el mejor tiempo. La opción -r es buena para esto; el valor predeterminado de 5 repeticiones es probablemente suficiente en la mayoría de los casos. Puede usar time.process_time() para medir el tiempo de CPU.

Nota

Hay una cierta sobrecarga de línea base asociada con la ejecución de una instrucción pass. El código aquí no intenta ocultarlo, pero debe ser consciente de ello. La sobrecarga de línea base se puede medir invocando el programa sin argumentos y puede diferir entre versiones de Python.

Ejemplos

Es posible proporcionar una instrucción setup que se ejecuta solo una vez al inicio:

$ python -m timeit -s 'text = "sample string"; char = "g"'  'char in text'
5000000 loops, best of 5: 0.0877 usec per loop
$ python -m timeit -s 'text = "sample string"; char = "g"'  'text.find(char)'
1000000 loops, best of 5: 0.342 usec per loop

In the output, there are three fields. The loop count, which tells you how many times the statement body was run per timing loop repetition. The repetition count (“best of 5”) which tells you how many times the timing loop was repeated, and finally the time the statement body took on average within the best repetition of the timing loop. That is, the time the fastest repetition took divided by the loop count.

>>> import timeit
>>> timeit.timeit('char in text', setup='text = "sample string"; char = "g"')
0.41440500499993504
>>> timeit.timeit('text.find(char)', setup='text = "sample string"; char = "g"')
1.7246671520006203

Se puede hacer lo mismo usando la clase Timer y sus métodos:

>>> import timeit
>>> t = timeit.Timer('char in text', setup='text = "sample string"; char = "g"')
>>> t.timeit()
0.3955516149999312
>>> t.repeat()
[0.40183617287970225, 0.37027556854118704, 0.38344867356679524, 0.3712595970846668, 0.37866875250654886]

En los ejemplos siguientes se muestra cómo cronometrar expresiones que contienen varias líneas. Aquí comparamos el coste de usar hasattr() frente a try/except para probar los atributos de objeto faltantes y presentes:

$ python -m timeit 'try:' '  str.__bool__' 'except AttributeError:' '  pass'
20000 loops, best of 5: 15.7 usec per loop
$ python -m timeit 'if hasattr(str, "__bool__"): pass'
50000 loops, best of 5: 4.26 usec per loop

$ python -m timeit 'try:' '  int.__bool__' 'except AttributeError:' '  pass'
200000 loops, best of 5: 1.43 usec per loop
$ python -m timeit 'if hasattr(int, "__bool__"): pass'
100000 loops, best of 5: 2.23 usec per loop

>>> import timeit
>>> # attribute is missing
>>> s = """\
... try:
...     str.__bool__
... except AttributeError:
...     pass
... """
>>> timeit.timeit(stmt=s, number=100000)
0.9138244460009446
>>> s = "if hasattr(str, '__bool__'): pass"
>>> timeit.timeit(stmt=s, number=100000)
0.5829014980008651
>>>
>>> # attribute is present
>>> s = """\
... try:
...     int.__bool__
... except AttributeError:
...     pass
... """
>>> timeit.timeit(stmt=s, number=100000)
0.04215312199994514
>>> s = "if hasattr(int, '__bool__'): pass"
>>> timeit.timeit(stmt=s, number=100000)
0.08588060699912603

Para dar al módulo timeit acceso a las funciones que defina, puede pasar un parámetro setup que contenga una instrucción import:

def test():
    """Stupid test function"""
    L = [i for i in range(100)]

if __name__ == '__main__':
    import timeit
    print(timeit.timeit("test()", setup="from __main__ import test"))

Otra opción es pasar globals() al parámetro globals, lo que hará que el código se ejecute dentro del espacio de nombres global actual. Esto puede ser más conveniente que especificar individualmente las importaciones:

def f(x):
    return x**2
def g(x):
    return x**4
def h(x):
    return x**8

import timeit
print(timeit.timeit('[func(42) for func in (f,g,h)]', globals=globals()))

trace — Rastrear la ejecución de la declaración de Python

Código fuente: Lib/trace.py [https://github.com/python/cpython/tree/3.9/Lib/trace.py]

El módulo trace le permite rastrear la ejecución del programa, generar listas de cobertura de declaraciones anotadas, imprimir relaciones entre llamador/destinatario y listar funciones ejecutadas durante la ejecución de un programa. Se puede utilizar en otro programa o desde la línea de comandos.

Ver también

Coverage.py [https://coverage.readthedocs.io/]

Una herramienta popular de terceros de cobertura que proporciona salida HTML junto con funciones avanzadas como cobertura de sucursales.

Uso de la línea de comandos

El módulo trace se puede invocar desde la línea de comandos. Puede ser tan simple como

python -m trace --count -C . somefile.py ...

Lo anterior ejecutará somefile.py y generará listados anotados de todos los módulos de Python importados durante la ejecución en el directorio actual.

--help

Muestra uso y sale.

--version

Muestra la versión del módulo y sale.

Nuevo en la versión 3.8: Se agregó la opción --module que permite ejecutar un módulo ejecutable.

Opciones principales

Se debe especificar al menos una de las siguientes opciones al invocar trace. La opción --listfuncs es mutuamente excluyente con las opciones --trace y --count. Cuando se proporciona --listfuncs, no se aceptan --count ni --trace, y viceversa.

-c, --count

Genera un conjunto de archivos de lista anotados al finalizar el programa que muestra cuántas veces se ejecutó cada instrucción. Vea también --coverdir, --file y --no-report a continuación.

-t, --trace

Muestra las líneas a medida que se ejecutan.

-l, --listfuncs

Muestra las funciones ejecutadas al ejecutar el programa.

-r, --report

Genera una lista anotada de una ejecución del programa anterior que utilizó la opción --count y --file. Esto no ejecuta ningún código.

-T, --trackcalls

Muestra las relaciones de llamada expuestas al ejecutar el programa.

Modificadores

-f, --file=<file>

Nombre de un archivo para acumular recuentos durante varias ejecuciones de seguimiento. Debe usarse con la opción --count.

-C, --coverdir=<dir>

Directorio donde van los archivos del informe. El informe de cobertura para paquete.modulo se escribe en el archivo directorio/paquete/modulo.cobertura.

-m, --missing

Al generar listados anotados, marque las líneas que no se ejecutaron con >>>>>>.

-s, --summary

Cuando use --count o --report, escriba un breve resumen en stdout para cada archivo procesado.

-R, --no-report

No genera listados anotados. Esto es útil si tiene la intención de realizar varias ejecuciones con --count, y luego producir un solo conjunto de listados anotados al final.

-g, --timing

Prefija cada línea con la hora desde que se inició el programa. Solo se usa durante el rastreo.

Filtros

Estas opciones pueden repetirse varias veces.

--ignore-module=<mod>

Ignora cada uno de los nombres de módulo dados y sus submódulos (si es un paquete). El argumento puede ser una lista de nombres separados por una coma.

--ignore-dir=<dir>

Ignora todos los módulos y paquetes en el directorio y subdirectorios nombrados. El argumento puede ser una lista de directorios separados por os.pathsep.

Interfaz programática

class trace.Trace(count=1, trace=1, countfuncs=0, countcallers=0, ignoremods=(), ignoredirs=(), infile=None, outfile=None, timing=False)

Crea un objeto para rastrear la ejecución de una sola declaración o expresión. Todos los parámetros son opcionales. count habilita el conteo de números de línea. trace habilita el seguimiento de ejecución de línea. countfuncs habilita la lista de las funciones llamadas durante la ejecución. countcallers habilita el seguimiento de la relación de llamadas. ignoremods es una lista de módulos o paquetes para ignorar. ignoredirs es una lista de directorios cuyos módulos o paquetes deben ignorarse. infile es el nombre del archivo desde el cual leer la información de conteo almacenada. outfile es el nombre del archivo en el que se escribe la información de conteo actualizada. timing permite mostrar una marca de tiempo relativa al momento en que se inició el seguimiento.

run(cmd)

Ejecuta el comando y recopile estadísticas de la ejecución con los parámetros de seguimiento actuales. cmd debe ser una cadena o un objeto de código, adecuado para pasar a exec().

runctx(cmd, globals=None, locals=None)

Ejecuta el comando y recopile estadísticas de la ejecución con los parámetros de seguimiento actuales, en los entornos globales y locales definidos. Si no está definido, globals y locals por defecto son diccionarios vacíos.

runfunc(func, /, *args, **kwds)

Llama a func con los argumentos dados bajo el control del objeto Trace con los parámetros de rastreo actuales.

results()

Retorna un objeto CoverageResults que contiene los resultados acumulativos de todas las llamadas anteriores a run, runctx y runfunc para la instancia dada Trace. No restablece los resultados de seguimiento acumulados.

class trace.CoverageResults

Un contenedor para los resultados de la cobertura, creado por Trace.results(). No debe ser creado directamente por el usuario.

update(other)

Fusiona datos de otro objeto CoverageResults.

write_results(show_missing=True, summary=False, coverdir=None)

Escribe los resultados de la cobertura. Configure show_missing para mostrar las líneas que no tuvieron coincidencias. Configurar summary para incluir en la salida el resumen de cobertura por módulo. coverdir especifica el directorio en el que se enviarán los archivos de resultado de cobertura. Si es None, los resultados de cada archivo fuente se colocan en su directorio.

Un ejemplo simple que demuestra el uso de la interfaz programática:

import sys
import trace

# create a Trace object, telling it what to ignore, and whether to
# do tracing or line-counting or both.
tracer = trace.Trace(
    ignoredirs=[sys.prefix, sys.exec_prefix],
    trace=0,
    count=1)

# run the new command using the given tracer
tracer.run('main()')

# make a report, placing output in the current directory
r = tracer.results()
r.write_results(show_missing=True, coverdir=".")

tracemalloc— Rastrea la asignación de memoria

Nuevo en la versión 3.4.

Código fuente: Lib/tracemalloc.py [https://github.com/python/cpython/tree/3.9/Lib/tracemalloc.py]

El módulo tracemalloc es una herramienta de depuración para rastrear los espacios de memoria asignados por Python. Este proporciona la siguiente información:

El rastreo al lugar de origen del objeto asignado

Las estadísticas en los espacios de memoria asignados por nombre de archivo y por número de línea: tamaño total, número y tamaño promedio de los espacios de memoria asignados

Calcula las diferencias entre dos informes instantáneos para detectar alguna filtración en la memoria

Para rastrear la mayoría de los espacios de memoria asignados por Python; el módulo debe empezar tan pronto como sea posible configurando la variable del entorno PYTHONTRACEMALLOC a 1, o usando la opción del comando de línea -X tracemalloc. La función tracemalloc.start() puede ser llamada en tiempo de ejecución para empezar a rastrear las asignaciones de memoria de Python.

Por defecto, el rastreo de un espacio de memoria asignado solo guarda el cuadro mas reciente (1 cuadro). Para guardar 25 cuadros desde el PYTHONTRACEMALLOC`comienzo, configura la variable del entorno a ``25`, o usa -X tracemalloc=25 en la opción de línea de comando.

Ejemplos

Mostrar los 10 principales

Mostrar los 10 archivos asignando la mayor cantidad de memoria:

import tracemalloc

tracemalloc.start()

# ... run your application ...

snapshot = tracemalloc.take_snapshot()
top_stats = snapshot.statistics('lineno')

print("[ Top 10 ]")
for stat in top_stats[:10]:
    print(stat)

Ejemplo de la salida del conjunto de pruebas de Python:

[ Top 10 ]
<frozen importlib._bootstrap>:716: size=4855 KiB, count=39328, average=126 B
<frozen importlib._bootstrap>:284: size=521 KiB, count=3199, average=167 B
/usr/lib/python3.4/collections/__init__.py:368: size=244 KiB, count=2315, average=108 B
/usr/lib/python3.4/unittest/case.py:381: size=185 KiB, count=779, average=243 B
/usr/lib/python3.4/unittest/case.py:402: size=154 KiB, count=378, average=416 B
/usr/lib/python3.4/abc.py:133: size=88.7 KiB, count=347, average=262 B
<frozen importlib._bootstrap>:1446: size=70.4 KiB, count=911, average=79 B
<frozen importlib._bootstrap>:1454: size=52.0 KiB, count=25, average=2131 B
<string>:5: size=49.7 KiB, count=148, average=344 B
/usr/lib/python3.4/sysconfig.py:411: size=48.0 KiB, count=1, average=48.0 KiB

Se puede ver que Python ha cargado 4855 KiB de data (código de bytes y constantes) desde los módulos y que el modulo collections asigno 24KiB para crear tipos namedtuple.

Mira Snapshot.statistics() para más opciones.

Calcula las diferencias

Toma dos capturas instantáneas y muestra las diferencias:

import tracemalloc
tracemalloc.start()
# ... start your application ...

snapshot1 = tracemalloc.take_snapshot()
# ... call the function leaking memory ...
snapshot2 = tracemalloc.take_snapshot()

top_stats = snapshot2.compare_to(snapshot1, 'lineno')

print("[ Top 10 differences ]")
for stat in top_stats[:10]:
    print(stat)

Ejemplo de la salida antes y después de probar el conjunto de pruebas de Python:

[ Top 10 differences ]
<frozen importlib._bootstrap>:716: size=8173 KiB (+4428 KiB), count=71332 (+39369), average=117 B
/usr/lib/python3.4/linecache.py:127: size=940 KiB (+940 KiB), count=8106 (+8106), average=119 B
/usr/lib/python3.4/unittest/case.py:571: size=298 KiB (+298 KiB), count=589 (+589), average=519 B
<frozen importlib._bootstrap>:284: size=1005 KiB (+166 KiB), count=7423 (+1526), average=139 B
/usr/lib/python3.4/mimetypes.py:217: size=112 KiB (+112 KiB), count=1334 (+1334), average=86 B
/usr/lib/python3.4/http/server.py:848: size=96.0 KiB (+96.0 KiB), count=1 (+1), average=96.0 KiB
/usr/lib/python3.4/inspect.py:1465: size=83.5 KiB (+83.5 KiB), count=109 (+109), average=784 B
/usr/lib/python3.4/unittest/mock.py:491: size=77.7 KiB (+77.7 KiB), count=143 (+143), average=557 B
/usr/lib/python3.4/urllib/parse.py:476: size=71.8 KiB (+71.8 KiB), count=969 (+969), average=76 B
/usr/lib/python3.4/contextlib.py:38: size=67.2 KiB (+67.2 KiB), count=126 (+126), average=546 B

Se puede ver que Python cargó 8173 KiB de información del modulo (código de bytes y constantes), y que eso es `4428KiB más de lo que ha sido cargado antes de los test, cuando la anterior captura de pantalla fue tomada. De manera similar, el modulo linecache ha almacenado en caché``940 KiB`` del código fuente de Python para formatear los seguimientos, todo desde la captura instantánea.

Si el sistema tiene poca memoria libre, los informes instantáneos pueden ser escritos en el disco usando el método Snapshot.dump() para analizar el informe instantáneo offline. Después usa el método Snapshot.load() para actualizar el informe.

Consigue el seguimiento del bloque de memoria

Código para configurar el seguimiento del bloque de memoria más grande:

import tracemalloc

# Store 25 frames
tracemalloc.start(25)

# ... run your application ...

snapshot = tracemalloc.take_snapshot()
top_stats = snapshot.statistics('traceback')

# pick the biggest memory block
stat = top_stats[0]
print("%s memory blocks: %.1f KiB" % (stat.count, stat.size / 1024))
for line in stat.traceback.format():
    print(line)

Ejemplo de la salida del conjunto de pruebas de Python (rastreo limitado a 25 cuadros):

903 memory blocks: 870.1 KiB
  File "<frozen importlib._bootstrap>", line 716
  File "<frozen importlib._bootstrap>", line 1036
  File "<frozen importlib._bootstrap>", line 934
  File "<frozen importlib._bootstrap>", line 1068
  File "<frozen importlib._bootstrap>", line 619
  File "<frozen importlib._bootstrap>", line 1581
  File "<frozen importlib._bootstrap>", line 1614
  File "/usr/lib/python3.4/doctest.py", line 101
    import pdb
  File "<frozen importlib._bootstrap>", line 284
  File "<frozen importlib._bootstrap>", line 938
  File "<frozen importlib._bootstrap>", line 1068
  File "<frozen importlib._bootstrap>", line 619
  File "<frozen importlib._bootstrap>", line 1581
  File "<frozen importlib._bootstrap>", line 1614
  File "/usr/lib/python3.4/test/support/__init__.py", line 1728
    import doctest
  File "/usr/lib/python3.4/test/test_pickletools.py", line 21
    support.run_doctest(pickletools)
  File "/usr/lib/python3.4/test/regrtest.py", line 1276
    test_runner()
  File "/usr/lib/python3.4/test/regrtest.py", line 976
    display_failure=not verbose)
  File "/usr/lib/python3.4/test/regrtest.py", line 761
    match_tests=ns.match_tests)
  File "/usr/lib/python3.4/test/regrtest.py", line 1563
    main()
  File "/usr/lib/python3.4/test/__main__.py", line 3
    regrtest.main_in_temp_cwd()
  File "/usr/lib/python3.4/runpy.py", line 73
    exec(code, run_globals)
  File "/usr/lib/python3.4/runpy.py", line 160
    "__main__", fname, loader, pkg_name)

Se puede ver que la mayor parte de la memoria fue asignada en el módulo importlib para cargar datos (códigos de bytes y constantes) desde módulos 870.1 KiB. El rastreo esta donde el módulo importlib cargó datos más recientemente: en la linea import pdb el módulo doctest.

Los 10 más bonitos

Codifica para configurar las 10 líneas que asignan gran parte de la memoria con una salida bonita, ignorando los archivos``<frozen importlib._bootstrap>`` y <unkownn>:

import linecache
import os
import tracemalloc

def display_top(snapshot, key_type='lineno', limit=10):
    snapshot = snapshot.filter_traces((
        tracemalloc.Filter(False, "<frozen importlib._bootstrap>"),
        tracemalloc.Filter(False, "<unknown>"),
    ))
    top_stats = snapshot.statistics(key_type)

    print("Top %s lines" % limit)
    for index, stat in enumerate(top_stats[:limit], 1):
        frame = stat.traceback[0]
        print("#%s: %s:%s: %.1f KiB"
              % (index, frame.filename, frame.lineno, stat.size / 1024))
        line = linecache.getline(frame.filename, frame.lineno).strip()
        if line:
            print('    %s' % line)

    other = top_stats[limit:]
    if other:
        size = sum(stat.size for stat in other)
        print("%s other: %.1f KiB" % (len(other), size / 1024))
    total = sum(stat.size for stat in top_stats)
    print("Total allocated size: %.1f KiB" % (total / 1024))

tracemalloc.start()

# ... run your application ...

snapshot = tracemalloc.take_snapshot()
display_top(snapshot)

Ejemplo de la salida del conjunto de pruebas de Python:

Top 10 lines
#1: Lib/base64.py:414: 419.8 KiB
    _b85chars2 = [(a + b) for a in _b85chars for b in _b85chars]
#2: Lib/base64.py:306: 419.8 KiB
    _a85chars2 = [(a + b) for a in _a85chars for b in _a85chars]
#3: collections/__init__.py:368: 293.6 KiB
    exec(class_definition, namespace)
#4: Lib/abc.py:133: 115.2 KiB
    cls = super().__new__(mcls, name, bases, namespace)
#5: unittest/case.py:574: 103.1 KiB
    testMethod()
#6: Lib/linecache.py:127: 95.4 KiB
    lines = fp.readlines()
#7: urllib/parse.py:476: 71.8 KiB
    for a in _hexdig for b in _hexdig}
#8: <string>:5: 62.0 KiB
#9: Lib/_weakrefset.py:37: 60.0 KiB
    self.data = set()
#10: Lib/base64.py:142: 59.8 KiB
    _b32tab2 = [a + b for a in _b32tab for b in _b32tab]
6220 other: 3602.8 KiB
Total allocated size: 5303.1 KiB

Mira Snapshot.statistics() para más opciones.

Graba los tamaños actual y máximo de todos los bloques de memoria rastreados

El siguiente código calcula dos sumas como 0 + 1 + 2 + ... de forma ineficiente, creando una lista con estos números. Esta lista consume mucha memoria de forma temporal. Podemos usar get_traced_memory() y reset_peak() para observar el pequeño uso de memoria después de que la suma es calculada, así como también el uso máximo de memoria durante el cálculo:

import tracemalloc

tracemalloc.start()

# Example code: compute a sum with a large temporary list
large_sum = sum(list(range(100000)))

first_size, first_peak = tracemalloc.get_traced_memory()

tracemalloc.reset_peak()

# Example code: compute a sum with a small temporary list
small_sum = sum(list(range(1000)))

second_size, second_peak = tracemalloc.get_traced_memory()

print(f"{first_size=}, {first_peak=}")
print(f"{second_size=}, {second_peak=}")

Salida:

first_size=664, first_peak=3592984
second_size=804, second_peak=29704

El uso de reset_peak() asegura que podemos registrar precisamente el uso máximo de memoria durante el cálculo de small_sum, incluso si es mucho menor al máximo total desde la llamada a start(). Sin la llamada a reset_peak(), second_peak seguiría siendo el uso máximo de memoria del cálculo de large_sum (es decir, igual a first_peak). En este caso ambos máximos son mucho mayores al uso final de memoria, lo que sugiere que podemos optimizar (removiendo la llamada innecesaria a list, y escribiendo sum(range(...))).

API

Funciones

tracemalloc.clear_traces()

Limpia los rastros de los bloques de memoria asignados por Python.

Mira también la función stop().

tracemalloc.get_object_traceback(obj)

Obtiene el rastreo de donde el objeto de Python fue asignado. Retorna una instancia Traceback o None si el módulo tracemalloc no esta rastreando ninguna asignación de memoria o no rastreó la asignación del objeto.

Mira también las funciones gc.get_referrers() y sys.getsizeof().

tracemalloc.get_traceback_limit()

Obtiene el número máximo de cuadros guardados en el seguimiento de un rastro.

El módulo tracemalloc debe rastrear las asignaciones de memoria para obtener el límite, de otra manera se inicia una excepción.

El limite es establecido por la función start().

tracemalloc.get_traced_memory()

Obtiene el tamaño actual y tamaño pico de los bloques de memorias rastreados por el módulo tracemalloc como una tupla: (current: int, peak: int).

tracemalloc.reset_peak()

Establece el tamaño máximo de los bloques de memorias rastreados por el módulo tracemalloc al tamaño actual.

No realiza ninguna acción si el módulo tracemalloc no está rastreando asignaciones de memoria.

Esta función sólo modifica el valor guardado para el uso máximo de memoria, y no modifica o borra ningún rastreo, no como clear_traces(). Capturas tomadas con take_snapshot() antes de una llamada a reset_peak() pueden ser comparadas significativamente con capturas hechas después de la llamada.

Mira también la función get_traced_memory().

Nuevo en la versión 3.9.

tracemalloc.get_tracemalloc_memory()

Obtiene el uso de la memoria en bytes desde el modulo tracemalloc usado para guardar rastreos de bloques de memoria. Retorna una clase int.

tracemalloc.is_tracing()

Si el módulo tracemalloc esta rastreando asignaciones de memoria de Python retorna True sino retorna False.

También mira las funciones start() y stop().

tracemalloc.start(nframe: int=1)

Empieza a rastrear las asignaciones de memoria de Python: instala hooks en las asignaciones de memoria de Python. Los rastreos coleccionados van a estar limitados a nframe. Por defecto, un rastro de un bloque de memoria solo guarda el cuadro mas reciente: el limite es 1. nframe debe ser mayor o igual a 1.

El número original de cuadros totales que componen el seguimiento observando el atributo Traceback.total_nframe.

Guardar mas de 1 cuadro es solo útil para calcular estadísticas agrupadas por seguimiento o para calcular estadísticas acumulativa: mira las funciones Snapshot.compare_to() y Snapshot.statistics().

Guardar mas cuadros aumenta la memoria y la sobrecargar de la CPU del modulo tracemalloc. Usa la función get_tracemalloc_memory() para medir cuanta memoria se usa por el módulo tracemalloc.

La variable del entorno PYTHONTRACEMALLOC (PYTHONTRACEMALLOC=NFRAME) y la opción de comando de linea -X tracemalloc=NFRAME se puede usar para empezar a rastrear desde el inicio.

También mira las funciones stop(), is_tracing() y get_traceback_limit().

tracemalloc.stop()

Detiene el rastreo de las asignaciones de memoria de Python: desinstala los hooks. También limpia todos los rastros de memoria recolectados acerca de los bloques de memoria asignados por Python.

Llama a la función take_snapshot() para tomar una captura instantánea de los rastreos, antes de limpiarlos.

También mira las funciones start(), is_tracing() y clear_traces().

tracemalloc.take_snapshot()

Toma una captura instantánea de los bloques de memoria asignados por Python. Retorna una nueva instancia de la clase Snapshot.

La captura instantánea no incluye ningún bloque de memoria asignado antes de que el módulo tracemalloc haya empezado a rastrear asignaciones de memoria.

Los seguimientos de los rastros son limitados por la función get_traceback_limit(). Usa el parámetro nframe de la función start() para guardar mas cuadros.

El módulo tracemalloc debe empezar a rastrear las asignaciones de memoria para tomar una captura instantánea. Mira la función start().

También mira la función get_object_traceback().

Filtro de dominio

class tracemalloc.DomainFilter(inclusive: bool, domain: int)

Filtra los rastros de los bloques de memoria por su espacio de dirección (dominio)

Nuevo en la versión 3.6.

inclusive

Si inclusive es True (incluye), relaciona los bloques de memoria asignados en el espacio de dirección domain.

Si inclusive es False (excluye), relaciona los bloques de memoria no asignados en el espacio de dirección domain.

domain

Espacio de dirección de un bloque de memoria (int). Propiedad solo-lectura.

Filtro

class tracemalloc.Filter(inclusive: bool, filename_pattern: str, lineno: int=None, all_frames: bool=False, domain: int=None)

Filtra los rastros de los bloques de memoria.

También mira la función fnmatch.fnmatch() para la sintaxis de filename_pattern. La extensión '.pyc' es remplazada por '.py'.

Ejemplos:

Filter(True, subprocess.__file__) solo incluye los rastros de el módulo subprocess

Filter(False, tracemalloc.__file__) excluye los rastros de memoria del módulo tracemalloc

Filter(False, "<unknown>") excluye los seguimientos vacíos

Distinto en la versión 3.5: La extensión '.pyo' ya no se remplaza con '.py'.

Distinto en la versión 3.6: Agregado el atributo domain .

domain

El espacio de dirección de un bloque de memoria (int o None).

tracemalloc usa el dominio 0 para rastrear las asignaciones de memoria hechas por Python. Las extensiones C pueden usar otros dominios para rastrear otros recursos.

inclusive

Si inclusive es True (incluye), solo relaciona los bloques de memoria asignados en un archivo con el nombre coincidiendo con el atributo filename_pattern en el número de línea del atributo lineno.

Si inclusive es False (excluye), ignora los bloques de memoria asignados en un archivo con el nombre coincidiendo con el atributo filename_pattern en el número de línea del atributo lineno.

lineno

El número de linea (int) del filtro. Si lineno es None, el filtro se relaciona con cualquier número de linea.

filename_pattern

El patrón del nombre de archivo del filtro (str). Propiedad solo-lectura.

all_frames

Si all_frames es True, todos los cuadros de los rastreos son chequeados. Si all_frames es False, solo el cuadro mas reciente es chequeado.

El atributo no tiene efecto si el limite de rastreo es 1. Mira la función get_traceback_limit() y el atributo Snapshot.traceback_limit.

Cuadro

class tracemalloc.Frame

Cuadro de un rastreo.

La clase Traceback es una secuencia de las instancias de la clase Frame.

filename

Nombre de archivo (str).

lineno

Número de línea (int).

Captura instantánea

class tracemalloc.Snapshot

Captura instantánea de los rastros de los bloques de memoria asignados por Python.

La función take_snapshot() crea una instancia de captura instantánea.

compare_to(old_snapshot: Snapshot, key_type: str, cumulative: bool=False)

Calcula las diferencias con una vieja captura instantánea. Obtiene las estadísticas en una lista ordenada de instancias de la clase StatisticDiff agrupadas por key_type.

Mira el método Snapshot.statistics() para los parámetros key_type y cumulative.

El resultado esta guardado desde el más grande al más pequeño por los valores absolutos de StatisticDiff.size_diff(), StatisticDiff.size(), el valor absoluto de StatisticDiff.count_diff(), Statistic.count() y después por el atributo StatisticDiff.traceback().

dump(filename)

Escribe la captura instantánea en un archivo.

Usa el método load() para recargar la captura instantánea.

filter_traces(filters)

Crea una nueva instancia de clase Snapshot con una secuencia de traces filtrados, filters es una lista de las instancias de DomainFilter y Filter. Si filters es una lista vacía, retorna una nueva instancia de clase Snapshot con una copia de los rastreos.

Los filtros todo incluido se aplican de a uno, si los filtros no incluidos coinciden. Si al menos un filtro exclusivo coincide, se ignora un rastro.

Distinto en la versión 3.6: Las instancias de clase DomainFilter ahora también son aceptadas en filters.

classmethod load(filename)

Carga la captura instantánea desde un archivo.

También mira el método dump().

statistics(key_type: str, cumulative: bool=False)

Obtiene estadísticas como una lista ordenada, de instancias de Statistic agrupadas por key_type:

key_type

descripción

'filename'

nombre del archivo

'lineno'

nombre del archivo y número de línea

'traceback'

seguimiento

Si cumulative es True, acumula el tamaño y cuenta los bloques de memoria de todos los cuadros del seguimiento de un rastro, no solo el cuadro mas reciente. El modo acumulativo solo puede ser usado cuando key_type se iguala a 'filename' y 'lineno'.

El resultado se organiza desde el más grande hasta el más pequeño por el atributo Statistic.size, Statistic.count y después por Statistic.traceback.

traceback_limit

El número máximo de cuadros organizados en el rastreo del atributo traces: resulta de la función get_traceback_limit cuando la captura instantánea fue tomada.

traces

Rastros de todos los bloques de memoria asignados por Python: secuencia de instancias de Trace.

La secuencia tiene un orden que no esta definido. Usa el método Snapshot.statistics() para obtener una lista ordenada de estadísticas.

Estadística

class tracemalloc.Statistic

Estadística de las asignaciones de memoria.

Snapshot.statistics() retorna una lista de instancias de la clase Statistic.

También mira la clase StatisticDiff.

count

Número de bloques de memoria (int).

size

El tamaño total de los bloques de memoria en bytes (int).

traceback

Rastrea donde un bloque de memoria fue asignado, la instancia de la clase Traceback.

StatisticDiff

class tracemalloc.StatisticDiff

La diferencia de estadística en las asignaciones de memoria entre una vieja y una nueva instancia de clase Snapshot.

Snapshot.compare_to() retorna una lista de instancias de la clase StatisticDiff. Mira también la clase Statistic.

count

El número de bloques de memoria en la nueva captura de pantalla (int): 0 si los bloques de memoria han sido liberados en la nueva captura instantánea.

count_diff

La diferencia de los números de los bloques de memoria entre las capturas viejas y nuevas (int): 0 si el bloque de memoria ha sido asignado en la nueva captura instantánea.

size

El tamaño total de los bloques de memoria en bytes en la nueva captura instantánea (int): 0 si el bloque de memoria ha sido liberado en la nueva captura instantánea.

size_diff

La diferencia de el tamaño total de un bloque de memoria en bytes entre las capturas instantáneas viejas y nuevas (int): 0 si el bloque de memoria ha sido asignado en la nueva captura instantánea.

traceback

Rastrea donde los bloques de memoria han sido asignados, instancia de la clase Traceback.

Rastro

class tracemalloc.Trace

Rastro de un bloque de memoria.

El atributo Snapshot.traces es una secuencia de las instancias de la clase Trace.

Distinto en la versión 3.6: Agregado el atributo domain .

domain

Espacio de dirección de un bloque de memoria (int). Propiedad solo-lectura.

tracemalloc usa el dominio 0 para rastrear las asignaciones de memoria hechas por Python. Las extensiones C pueden usar otros dominios para rastrear otros recursos.

size

Tamaño de un bloque de memoria en bytes (int).

traceback

Rastrea donde un bloque de memoria fue asignado, la instancia de la clase Traceback.

Seguimiento

class tracemalloc.Traceback

La secuencia de las instancias de la clase Frame organizadas desde el cuadro mas antiguo al más reciente.

Un seguimiento contiene por lo menos 1 cuadro. Si el módulo tracemalloc falla al traer un cuadro, se usa el nombre del archivo "<unknown>" en el número de linea 0.

Cuando se toma una captura, los seguimientos de los rastreos se limitan a get_traceback_limit() cuadros. Ver la función take_snapshot(). El número original de cuadros del seguimiento se guarda en el atributo Traceback.total_nframe. Esto permite saber si un seguimiento fue truncado por el límite de seguimientos.

El atributo Trace.traceback es una instancia de la clase Traceback.

Distinto en la versión 3.7: Los cuadros están organizados desde el mas antiguo hasta el más reciente, en vez de el más reciente al más antiguo.

total_nframe

Número total de cuadros que componen el seguimiento antes de ser truncado. Este atributo puede ser None si no hay información disponible.

Distinto en la versión 3.9: El atributo Traceback.total_nframe fue añadido.

format(limit=None, most_recent_first=False)

Format the traceback as a list of lines. Use the linecache module to retrieve lines from the source code. If limit is set, format the limit most recent frames if limit is positive. Otherwise, format the abs(limit) oldest frames. If most_recent_first is True, the order of the formatted frames is reversed, returning the most recent frame first instead of last.

Similar a la función traceback.format_tb(), excepto por el método format() que no incluye nuevas líneas.

Ejemplo:

print("Traceback (most recent call first):")
for line in traceback:
    print(line)

Salida:

Traceback (most recent call first):
  File "test.py", line 9
    obj = Object()
  File "test.py", line 12
    tb = tracemalloc.get_object_traceback(f())

Empaquetado y distribución de software

Estas bibliotecas te ayudan a publicar e instalar software de Python. Aunque estos módulos están diseñados para funcionar junto con Python Package Index [https://pypi.org], también pueden ser utilizados con un servidor de indexado local, o sin servidor de indexado.

distutils — Creación e instalación de módulos Python

ensurepip — Ejecutando el instalador pip

Interfaz de línea de comandos

API del módulo

venv — Creación de entornos virtuales

Creación de entornos virtuales

API

Un ejemplo de la extensión de EnvBuilder

zipapp — Gestiona archivadores zip ejecutables de Python

Ejemplo básico

Interfaz de línea de comando

API de Python

Ejemplos

Especificar el intérprete

Creando aplicaciones independientes con zipapp

Hacer un ejecutable para Windows

Advertencias

El formato de archivado Zip de aplicaciones Python

distutils — Creación e instalación de módulos Python

El paquete distutils proporciona soporte para crear e instalar módulos adicionales en una instalación de Python. Los nuevos módulos pueden ser 100% Python puro, o pueden ser módulos de extensión escritos en C, o pueden ser colecciones de paquetes de Python que incluyen módulos programados en Python y C.

La mayoría de los usuarios de Python no querrán utilizar este módulo directamente, sino que usarán las herramientas de versión cruzada mantenidas por la Python Packaging Authority. En particular, setuptools [https://setuptools.readthedocs.io/en/latest/] es una alternativa mejorada a distutils que proporciona:

soporte para declarar dependencias del proyecto

mecanismos adicionales para configurar cuáles archivos incluir en lanzamientos de código fuente (incluyendo plugins para la integración con sistemas de control de versiones)

la capacidad de declarar «puntos de entrada» del proyecto, los cuales pueden ser utilizados como base para los sistemas de plugins de aplicaciones

la capacidad de generar, automáticamente, ejecutables de línea de comandos de Windows en el momento de la instalación, en lugar de tener que compilarlos previamente

comportamiento consistente en todas las versiones de Python soportadas

El instalador pip [https://pip.pypa.io/] recomendado ejecuta todos los scripts setup.py con setuptools, incluso si el propio script sólo importa distutils. Consulte la Python Packaging User Guide [https://packaging.python.org] para más información.

Para beneficio de los autores de herramientas de empaquetado y los usuarios que buscan una comprensión más profunda de los detalles del sistema actual de empaquetado y distribución, la documentación de usuario heredada basada en distutils y la referencia de la API permanecen disponibles:

Instalación de Módulos de Python (versión antigua)

Distribución de módulos de Python (versión heredada)

ensurepip — Ejecutando el instalador pip

Nuevo en la versión 3.4.

El paquete ensurepip proporciona soporte para ejecutar el instalador pip en una instalación de Python existente o en un entorno virtual. Este enfoque de arranque refleja el hecho de que pip es un proyecto independiente con su propio ciclo de lanzamiento, y la última versión estable disponible se incluye con el mantenimiento y las versiones de características del intérprete de referencia CPython.

En la mayoría de los casos, los usuarios finales de Python no deberían tener que invocar este módulo directamente (como pip deben arrancarse de forma predeterminada), pero puede ser necesario si se omitió la instalación de pip al instalar Python (o al crear un entorno virtual) o después de desinstalar explícitamente pip.

Nota

Este módulo no accede a Internet. Todos los componentes necesarios para ejecutar pip se incluyen como partes internas del paquete.

Ver también

Instalando módulos de Python

La guía del usuario final para instalar paquetes python

PEP 453 [https://www.python.org/dev/peps/pep-0453]: Arranque explícito de pip en instalaciones de Python

La justificación original y la especificación de este módulo.

Interfaz de línea de comandos

La interfaz de línea de comandos se invoca mediante el modificador -m del intérprete.

La invocación más simple posible es:

python -m ensurepip

Esta invocación instalará pip si aún no está instalado, pero de lo contrario no hace nada. Para asegurarse de que la versión instalada de pip es al menos tan reciente como la incluida con ensurepip, pase la opción --upgrade:

python -m ensurepip --upgrade

De forma predeterminada, pip se instala en el entorno virtual actual (si uno está activo) o en los paquetes de sitio del sistema (si no hay ningún entorno virtual activo). La ubicación de instalación se puede controlar a través de dos opciones de línea de comandos adicionales:

--root <dir>: Instala pip en relación con el directorio raíz dado en lugar de la raíz del entorno virtual activo actualmente (si existe) o la raíz predeterminada para la instalación actual de Python.

--user: Instala pip en el directorio de paquetes de sitio de usuario en lugar de globalmente para la instalación actual de Python (esta opción no está permitida dentro de un entorno virtual activo).

De forma predeterminada, se instalarán los scripts pipX y pipX.Y (donde X.Y representa la versión de Python utilizada para invocar ensurepip). Los scripts instalados se pueden controlar a través de dos opciones de línea de comandos adicionales:

--altinstall: si se solicita una instalación alternativa, no se instalará el script pipX.

--default-pip: si se solicita una instalación de «pip predeterminado», se instalará el script pip además de los dos scripts regulares.

Proporcionar ambas opciones de selección de script desencadenará una excepción.

API del módulo

ensurepip expone dos funciones para su uso programático:

ensurepip.version()

Retorna una cadena de caracteres que especifica la versión incluida de pip que se instalará al ejecutarlo en un entorno.

ensurepip.bootstrap(root=None, upgrade=False, user=False, altinstall=False, default_pip=False, verbosity=0)

Ejecuta pip en el entorno actual o designado.

root especifica un directorio raíz alternativo para instalar en relación con. Si root es None, la instalación utiliza la ubicación de instalación predeterminada para el entorno actual.

upgrade indica si se debe actualizar o no una instalación existente de una versión anterior de pip a la versión incluida.

user indica si se debe utilizar el esquema de usuario en lugar de instalar globalmente.

De forma predeterminada, se instalarán los scripts pipX y pipX.Y (donde X.Y representa la versión actual de Python).

Si se establece altinstall, no se instalará pipX.

Si se establece default_pip, se instalará pip además de los dos scripts normales.

Establecer tanto altinstall como default_pip desencadenará ValueError.

verbosity controla el nivel de salida a sys.stdout de la operación de ejecución.

Genera un evento auditing ensurepip.bootstrap con el argumento root.

Nota

El proceso de ejecución tiene efectos secundarios tanto en sys.path como os.environ. Invocar la interfaz de línea de comandos en un subproceso en su lugar permite evitar estos efectos secundarios.

Nota

El proceso de ejecución puede instalar módulos adicionales requeridos por pip, pero otro software no debe asumir que esas dependencias siempre estarán presentes de forma predeterminada (ya que las dependencias se pueden eliminar en una versión futura de pip).

venv — Creación de entornos virtuales

Nuevo en la versión 3.3.

Código fuente: Lib/venv/ [https://github.com/python/cpython/tree/3.9/Lib/venv/]

El módulo venv proporciona soporte para crear «entornos virtuales» ligeros con sus propios directorios de ubicación, aislados opcionalmente de los directorios de ubicación del sistema. Cada entorno virtual tiene su propio binario Python (que coincide con la versión del binario que se utilizó para crear este entorno) y puede tener su propio conjunto independiente de paquetes Python instalados en sus directorios de ubicación.

Ver PEP 405 [https://www.python.org/dev/peps/pep-0405] para más información sobre los entornos virtuales de Python.

Ver también

Guía del usuario de la Paquetería Python: Creación y uso de entornos virtuales [https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment]

Creación de entornos virtuales

Creation of virtual environments is done by executing the command venv:

python3 -m venv /path/to/new/virtual/environment

Running this command creates the target directory (creating any parent directories that don’t exist already) and places a pyvenv.cfg file in it with a home key pointing to the Python installation from which the command was run (a common name for the target directory is .venv). It also creates a bin (or Scripts on Windows) subdirectory containing a copy/symlink of the Python binary/binaries (as appropriate for the platform or arguments used at environment creation time). It also creates an (initially empty) lib/pythonX.Y/site-packages subdirectory (on Windows, this is Lib\site-packages). If an existing directory is specified, it will be re-used.

Obsoleto desde la versión 3.6: pyvenv was the recommended tool for creating virtual environments for Python 3.3 and 3.4, and is deprecated in Python 3.6 [https://docs.python.org/dev/whatsnew/3.6.html#deprecated-features].

Distinto en la versión 3.5: The use of venv is now recommended for creating virtual environments.

On Windows, invoke the venv command as follows:

c:\>c:\Python35\python -m venv c:\path\to\myenv

Alternatively, if you configured the PATH and PATHEXT variables for your Python installation:

c:\>python -m venv c:\path\to\myenv

The command, if run with -h, will show the available options:

usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear]
            [--upgrade] [--without-pip] [--prompt PROMPT] [--upgrade-deps]
            ENV_DIR [ENV_DIR ...]

Creates virtual Python environments in one or more target directories.

positional arguments:
  ENV_DIR               A directory to create the environment in.

optional arguments:
  -h, --help            show this help message and exit
  --system-site-packages
                        Give the virtual environment access to the system
                        site-packages dir.
  --symlinks            Try to use symlinks rather than copies, when symlinks
                        are not the default for the platform.
  --copies              Try to use copies rather than symlinks, even when
                        symlinks are the default for the platform.
  --clear               Delete the contents of the environment directory if it
                        already exists, before environment creation.
  --upgrade             Upgrade the environment directory to use this version
                        of Python, assuming Python has been upgraded in-place.
  --without-pip         Skips installing or upgrading pip in the virtual
                        environment (pip is bootstrapped by default)
  --prompt PROMPT       Provides an alternative prompt prefix for this
                        environment.
  --upgrade-deps        Upgrade core dependencies: pip setuptools to the
                        latest version in PyPI

Once an environment has been created, you may wish to activate it, e.g. by
sourcing an activate script in its bin directory.

Distinto en la versión 3.9: Add --upgrade-deps option to upgrade pip + setuptools to the latest on PyPI

Distinto en la versión 3.4: Installs pip by default, added the --without-pip and --copies options

Distinto en la versión 3.4: In earlier versions, if the target directory already existed, an error was raised, unless the --clear or --upgrade option was provided.

Nota

While symlinks are supported on Windows, they are not recommended. Of particular note is that double-clicking python.exe in File Explorer will resolve the symlink eagerly and ignore the virtual environment.

Nota

On Microsoft Windows, it may be required to enable the Activate.ps1 script by setting the execution policy for the user. You can do this by issuing the following PowerShell command:

PS C:> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

See About Execution Policies [https://go.microsoft.com/fwlink/?LinkID=135170] for more information.

The created pyvenv.cfg file also includes the include-system-site-packages key, set to true if venv is run with the --system-site-packages option, false otherwise.

Unless the --without-pip option is given, ensurepip will be invoked to bootstrap pip into the virtual environment.

Multiple paths can be given to venv, in which case an identical virtual environment will be created, according to the given options, at each provided path.

Once a virtual environment has been created, it can be «activated» using a script in the virtual environment’s binary directory. The invocation of the script is platform-specific (<venv> must be replaced by the path of the directory containing the virtual environment):

Platform

Shell

Command to activate virtual environment

POSIX

bash/zsh

$ source <venv>/bin/activate

fish

$ source <venv>/bin/activate.fish

csh/tcsh

$ source <venv>/bin/activate.csh

PowerShell Core

$ <venv>/bin/Activate.ps1

Windows

cmd.exe

C:\> <venv>\Scripts\activate.bat

PowerShell

PS C:\> <venv>\Scripts\Activate.ps1

When a virtual environment is active, the VIRTUAL_ENV environment variable is set to the path of the virtual environment. This can be used to check if one is running inside a virtual environment.

You don’t specifically need to activate an environment; activation just prepends the virtual environment’s binary directory to your path, so that «python» invokes the virtual environment’s Python interpreter and you can run installed scripts without having to use their full path. However, all scripts installed in a virtual environment should be runnable without activating it, and run with the virtual environment’s Python automatically.

You can deactivate a virtual environment by typing «deactivate» in your shell. The exact mechanism is platform-specific and is an internal implementation detail (typically a script or shell function will be used).

Nuevo en la versión 3.4: fish and csh activation scripts.

Nuevo en la versión 3.8: PowerShell activation scripts installed under POSIX for PowerShell Core support.

Nota

Un entorno virtual es un entorno Python en el que el intérprete Python, las bibliotecas y los scripts instalados en él están aislados de los instalados en otros entornos virtuales, y (por defecto) cualquier biblioteca instalada en un «sistema» Python, es decir, uno que esté instalado como parte de tu sistema operativo.

Un entorno virtual es un árbol de directorios que contiene archivos ejecutables de Python y otros archivos que indican que es un entorno virtual.

Las herramientas de instalación habituales como setuptools [https://pypi.org/project/setuptools/] y pip [https://pypi.org/project/pip/] funcionan como se espera con entornos virtuales. En otras palabras, cuando un entorno virtual está activo, instalan los paquetes Python en el entorno virtual sin necesidad de que se les diga explícitamente que lo hagan.

Cuando un entorno virtual está activo (es decir, el intérprete de Python del entorno virtual se está ejecutando), los atributos sys.prefix y sys.exec_prefix apuntan al directorio base del entorno virtual, mientras que sys.base_prefix y sys.base_exec_prefix apuntan a la instalación Python del entorno no virtual que se utilizó para crear el entorno virtual. Si un entorno virtual no está activo, entonces sys.prefix es lo mismo que sys.base_prefix y sys.exec_prefix es lo mismo que sys.base_exec_prefix (todos ellos apuntan a una instalación Python de entorno no virtual).

Cuando un entorno virtual está activo, cualquier opción que cambie la ruta de instalación será ignorada de todos los archivos de configuración de distutils para evitar que los proyectos se instalen inadvertidamente fuera del entorno virtual.

Cuando se trabaja en una consola, las/los usuarias/os pueden hacer que un entorno virtual se active ejecutando un script activate en el directorio de ejecutables del entorno virtual (el nombre preciso del archivo y el comando para utilizarlo dependen del entorno de consola), que envía previamente el directorio de ejecutables del entorno virtual a la variable de entorno PATH para la consola en ejecución. En otras circunstancias no debería ser necesario activar un entorno virtual; los scripts instalados en entornos virtuales tienen una línea «shebang» que apunta al intérprete Python del entorno virtual. Esto significa que el script se ejecutará con ese intérprete sin importar el valor de PATH. En Windows, el procesamiento de la línea «shebang» está soportado si tienes instalado el Python Launcher para Windows (este fue añadido a Python en 3.3 - ver PEP 397 [https://www.python.org/dev/peps/pep-0397] para más detalles). Por lo tanto, al hacer doble clic en un script instalado en una ventana del Explorador de Windows se debería ejecutar el script con el intérprete correcto sin necesidad de que haya ninguna referencia a su entorno virtual en PATH.

API

El método de alto nivel descrito anteriormente utiliza una sencilla API que proporciona mecanismos para que les creadores de entornos virtuales de terceras/os puedan personalizar la creación de entornos según sus necesidades, la clase EnvBuilder.

class venv.EnvBuilder(system_site_packages=False, clear=False, symlinks=False, upgrade=False, with_pip=False, prompt=None, upgrade_deps=False)

La clase EnvBuilder acepta los siguientes argumentos de palabras clave en la instanciación:

system_site_packages – un valor booleano que indica que los site-packages del sistema Python deben estar disponibles para el entorno (por defecto es False).

clear – un valor booleano que, si es verdadero, borrará el contenido de cualquier directorio de destino existente, antes de crear el entorno.

symlinks – un valor booleano que indica si se debe intentar crear un enlace simbólico del binario de Python en lugar de copiarlo.

upgrade – un valor booleano que, si es verdadero, actualizará un entorno existente con el Python en ejecución – para ser usado cuando ese Python haya sido actualizado in situ (por defecto es False).

with_pip – un valor booleano que, si es verdadero, asegura que pip está instalado en el entorno virtual. Esto usa ensurepip con la opción --default-pip.

prompt – una cadena de caracteres que se utilizará después de que se active el entorno virtual (el valor predeterminado es None, lo que significa que se utilizaría el nombre del directorio del entorno). Si se proporciona la cadena especial ".", el nombre base del directorio actual se utiliza como indicador.

upgrade_deps – actualiza los módulos venv base a lo último en PyPI

Distinto en la versión 3.4: Añadido el parámetro with_pip

Nuevo en la versión 3.6: Añadido el parámetro prompt

Nuevo en la versión 3.9: Se agregó el parámetro upgrade_deps

Las/Los creadoras/es de herramientas de entorno virtual de terceros/as serán libres de usar la clase EnvBuilder proporcionada como clase base.

El env-builder retornado es un objeto que tiene un método, create:

create(env_dir)

Crear un entorno virtual especificando el directorio de destino (de forma absoluta o relativa al directorio actual) que ha de contener el entorno virtual. El método create creará el entorno en el directorio especificado, o lanzará la correspondiente excepción.

El método create de la clase EnvBuilder ilustra los enlaces disponibles para la personalización de la subclase:

def create(self, env_dir):
    """
    Create a virtualized Python environment in a directory.
    env_dir is the target directory to create an environment in.
    """
    env_dir = os.path.abspath(env_dir)
    context = self.ensure_directories(env_dir)
    self.create_configuration(context)
    self.setup_python(context)
    self.setup_scripts(context)
    self.post_setup(context)

Cada uno de los métodos ensure_directories(), create_configuration(), setup_python(), setup_scripts() y post_setup() pueden ser anulados.

ensure_directories(env_dir)

Crea el directorio del entorno y todos los directorios necesarios, y retorna un objeto de contexto. Esto es sólo un soporte para atributos (como rutas), para ser usado por los otros métodos. Se permite que los directorios ya existan, siempre y cuando se haya especificado clear o upgrade para permitir operar en un directorio de entorno existente.

create_configuration(context)

Crea el archivo de configuración pyvenv.cfg en el entorno.

setup_python(context)

Crea una copia o enlace simbólico al ejecutable Python en el entorno. En los sistemas POSIX, si se usó un ejecutable específico python3.x, se crearán enlaces simbólicos a python y python3 apuntando a ese ejecutable, a menos que ya existan archivos con esos nombres.

setup_scripts(context)

Instala los scripts de activación apropiados para la plataforma en el entorno virtual.

upgrade_dependencies(context)

Actualiza los paquetes de dependencia principales de venv (actualmente pip y setuptools) en el entorno. Esto se hace desembolsando el ejecutable pip en el entorno.

Nuevo en la versión 3.9.

post_setup(context)

Un método de marcador de posición que puede ser anulado en implementaciones de terceros/as para previo instalar paquetes en el entorno virtual o realizar otros pasos posteriores a la creación.

Distinto en la versión 3.7.2: Windows ahora usa scripts de redireccionamiento para python[w].exe en lugar de copiar los propios binarios. Para 3.7.2 solamente setup_python() no hace nada a menos que se ejecute desde una compilación en el árbol de directorios fuente.

Distinto en la versión 3.7.3: Windows copia los scripts de redireccionamiento como parte de setup_python() en lugar de setup_scripts(). Este no era el caso para 3.7.2. Cuando se usan enlaces simbólicos, los ejecutables originales se enlazan.

Además, EnvBuilder proporciona este método de utilidad que puede ser llamado desde setup_scripts() o post_setup() en subclases para ayudar a instalar scripts personalizados en el entorno virtual.

install_scripts(context, path)

path es la ruta a un directorio que debería contener los subdirectorios «common», «posix», «nt», cada uno de los cuales contiene scripts destinados al directorio bin del entorno. El contenido de «common» y el directorio correspondiente a os.name se copian después de algún reemplazo de texto de los marcadores de posición:

__VENV_DIR__ se sustituye por la ruta absoluta del directorio del entorno.

__VENV_NAME__ se sustituye por el nombre del entorno (parte final de la ruta del directorio del entorno).

__VENV_PROMPT__ se sustituye por el prompt (el nombre del entorno entre paréntesis y con un espacio posterior)

__VENV_BIN_NAME__ se sustituye con el nombre del directorio bin (ya sea bin o Scripts).

__VENV_PYTHON__ se sustituye con la ruta absoluta del ejecutable del entorno.

Se permite la existencia de los directorios (para cuando se está actualizando un entorno existente).

También hay una función de conveniencia a nivel de módulo:

venv.create(env_dir, system_site_packages=False, clear=False, symlinks=False, with_pip=False, prompt=None)

Crea un EnvBuilder con los argumentos de la palabra clave dada, y llama a su método create() con el argumento env_dir.

Nuevo en la versión 3.3.

Distinto en la versión 3.4: Añadido el parámetro with_pip

Distinto en la versión 3.6: Añadido el parámetro prompt

Un ejemplo de la extensión de EnvBuilder

El siguiente script muestra como extender EnvBuilder implementando una subclase que instala setuptools y pip en un entorno virtual creado:

import os
import os.path
from subprocess import Popen, PIPE
import sys
from threading import Thread
from urllib.parse import urlparse
from urllib.request import urlretrieve
import venv

class ExtendedEnvBuilder(venv.EnvBuilder):
    """
    This builder installs setuptools and pip so that you can pip or
    easy_install other packages into the created virtual environment.

    :param nodist: If true, setuptools and pip are not installed into the
                   created virtual environment.
    :param nopip: If true, pip is not installed into the created
                  virtual environment.
    :param progress: If setuptools or pip are installed, the progress of the
                     installation can be monitored by passing a progress
                     callable. If specified, it is called with two
                     arguments: a string indicating some progress, and a
                     context indicating where the string is coming from.
                     The context argument can have one of three values:
                     'main', indicating that it is called from virtualize()
                     itself, and 'stdout' and 'stderr', which are obtained
                     by reading lines from the output streams of a subprocess
                     which is used to install the app.

                     If a callable is not specified, default progress
                     information is output to sys.stderr.
    """

    def __init__(self, *args, **kwargs):
        self.nodist = kwargs.pop('nodist', False)
        self.nopip = kwargs.pop('nopip', False)
        self.progress = kwargs.pop('progress', None)
        self.verbose = kwargs.pop('verbose', False)
        super().__init__(*args, **kwargs)

    def post_setup(self, context):
        """
        Set up any packages which need to be pre-installed into the
        virtual environment being created.

        :param context: The information for the virtual environment
                        creation request being processed.
        """
        os.environ['VIRTUAL_ENV'] = context.env_dir
        if not self.nodist:
            self.install_setuptools(context)
        # Can't install pip without setuptools
        if not self.nopip and not self.nodist:
            self.install_pip(context)

    def reader(self, stream, context):
        """
        Read lines from a subprocess' output stream and either pass to a progress
        callable (if specified) or write progress information to sys.stderr.
        """
        progress = self.progress
        while True:
            s = stream.readline()
            if not s:
                break
            if progress is not None:
                progress(s, context)
            else:
                if not self.verbose:
                    sys.stderr.write('.')
                else:
                    sys.stderr.write(s.decode('utf-8'))
                sys.stderr.flush()
        stream.close()

    def install_script(self, context, name, url):
        _, _, path, _, _, _ = urlparse(url)
        fn = os.path.split(path)[-1]
        binpath = context.bin_path
        distpath = os.path.join(binpath, fn)
        # Download script into the virtual environment's binaries folder
        urlretrieve(url, distpath)
        progress = self.progress
        if self.verbose:
            term = '\n'
        else:
            term = ''
        if progress is not None:
            progress('Installing %s ...%s' % (name, term), 'main')
        else:
            sys.stderr.write('Installing %s ...%s' % (name, term))
            sys.stderr.flush()
        # Install in the virtual environment
        args = [context.env_exe, fn]
        p = Popen(args, stdout=PIPE, stderr=PIPE, cwd=binpath)
        t1 = Thread(target=self.reader, args=(p.stdout, 'stdout'))
        t1.start()
        t2 = Thread(target=self.reader, args=(p.stderr, 'stderr'))
        t2.start()
        p.wait()
        t1.join()
        t2.join()
        if progress is not None:
            progress('done.', 'main')
        else:
            sys.stderr.write('done.\n')
        # Clean up - no longer needed
        os.unlink(distpath)

    def install_setuptools(self, context):
        """
        Install setuptools in the virtual environment.

        :param context: The information for the virtual environment
                        creation request being processed.
        """
        url = 'https://bitbucket.org/pypa/setuptools/downloads/ez_setup.py'
        self.install_script(context, 'setuptools', url)
        # clear up the setuptools archive which gets downloaded
        pred = lambda o: o.startswith('setuptools-') and o.endswith('.tar.gz')
        files = filter(pred, os.listdir(context.bin_path))
        for f in files:
            f = os.path.join(context.bin_path, f)
            os.unlink(f)

    def install_pip(self, context):
        """
        Install pip in the virtual environment.

        :param context: The information for the virtual environment
                        creation request being processed.
        """
        url = 'https://bootstrap.pypa.io/get-pip.py'
        self.install_script(context, 'pip', url)

def main(args=None):
    compatible = True
    if sys.version_info < (3, 3):
        compatible = False
    elif not hasattr(sys, 'base_prefix'):
        compatible = False
    if not compatible:
        raise ValueError('This script is only for use with '
                         'Python 3.3 or later')
    else:
        import argparse

        parser = argparse.ArgumentParser(prog=__name__,
                                         description='Creates virtual Python '
                                                     'environments in one or '
                                                     'more target '
                                                     'directories.')
        parser.add_argument('dirs', metavar='ENV_DIR', nargs='+',
                            help='A directory in which to create the '
                                 'virtual environment.')
        parser.add_argument('--no-setuptools', default=False,
                            action='store_true', dest='nodist',
                            help="Don't install setuptools or pip in the "
                                 "virtual environment.")
        parser.add_argument('--no-pip', default=False,
                            action='store_true', dest='nopip',
                            help="Don't install pip in the virtual "
                                 "environment.")
        parser.add_argument('--system-site-packages', default=False,
                            action='store_true', dest='system_site',
                            help='Give the virtual environment access to the '
                                 'system site-packages dir.')
        if os.name == 'nt':
            use_symlinks = False
        else:
            use_symlinks = True
        parser.add_argument('--symlinks', default=use_symlinks,
                            action='store_true', dest='symlinks',
                            help='Try to use symlinks rather than copies, '
                                 'when symlinks are not the default for '
                                 'the platform.')
        parser.add_argument('--clear', default=False, action='store_true',
                            dest='clear', help='Delete the contents of the '
                                               'virtual environment '
                                               'directory if it already '
                                               'exists, before virtual '
                                               'environment creation.')
        parser.add_argument('--upgrade', default=False, action='store_true',
                            dest='upgrade', help='Upgrade the virtual '
                                                 'environment directory to '
                                                 'use this version of '
                                                 'Python, assuming Python '
                                                 'has been upgraded '
                                                 'in-place.')
        parser.add_argument('--verbose', default=False, action='store_true',
                            dest='verbose', help='Display the output '
                                               'from the scripts which '
                                               'install setuptools and pip.')
        options = parser.parse_args(args)
        if options.upgrade and options.clear:
            raise ValueError('you cannot supply --upgrade and --clear together.')
        builder = ExtendedEnvBuilder(system_site_packages=options.system_site,
                                       clear=options.clear,
                                       symlinks=options.symlinks,
                                       upgrade=options.upgrade,
                                       nodist=options.nodist,
                                       nopip=options.nopip,
                                       verbose=options.verbose)
        for d in options.dirs:
            builder.create(d)

if __name__ == '__main__':
    rc = 1
    try:
        main()
        rc = 0
    except Exception as e:
        print('Error: %s' % e, file=sys.stderr)
    sys.exit(rc)

Este script está también disponible para su descarga online [https://gist.github.com/vsajip/4673395].

zipapp — Gestiona archivadores zip ejecutables de Python

Nuevo en la versión 3.5.

Código fuente: Lib/zipapp.py [https://github.com/python/cpython/tree/3.9/Lib/zipapp.py]

Este módulo provee herramientas para administrar la creación de archivos zip que contengan código Python, los que pueden ser ejecutados directamente por el intérprete de Python. El módulo provee tanto una Interfaz de línea de comando y una API de Python.

Ejemplo básico

El siguiente ejemplo muestra cómo la Interfaz de línea de comando puede utilizarse para crear un archivador ejecutable de un directorio que contenga código en Python. Al ponerse en funcionamiento, el archivador ejecutará la función main del módulo myapp en el archivador.

$ python -m zipapp myapp -m "myapp:main"
$ python myapp.pyz
<output from myapp>

Interfaz de línea de comando

En la ejecución como programa desde la línea de comandos, se utiliza el siguiente formato:

$ python -m zipapp source [options]

Si source es un directorio, se creará un archivador zip para los contenidos de source. Si source es un archivo, debería ser un archivador, y se copiará al archivador de destino (o los contenidos de su línea shebang se mostrarán si se especifica la opción –info).

Se aceptan las siguientes opciones:

-o <output>, --output=<output>

Escribe la salida a un archivo llamado output. Si esta opción no está especificada, el nombre del archivo de salida será el mismo que la entrada source, con la extensión .pyz agregada. Si se provee de un nombre de archivo explícito, se usa tal como está (por lo que una extensión .pyz debería incluirse si esto se requiere).

Un nombre de archivo de salida debe especificarse si source es un archivador (y en ese caso, output no debería ser igual que source).

-p <interpreter>, --python=<interpreter>

Agrega una línea #! al archivador especificando interpreter como comando a ejecutar. También en POSIX, convierte al archivador en ejecutable. La opción por defecto es no escribir una línea #!, y no hacer que el archivo sea ejecutable.

-m <mainfn>, --main=<mainfn>

Escribe un archivo __main__.py en el archivador que ejecuta mainfn. El argumento mainfn debería tener la forma «pkg.mod:fn», donde «pkg.mod» is un paquete/módulo en el archivador, y «fn» es un invocable (callable) en ese módulo. El archivo __main__.py ejecutará ese invocable.

--main no puede especificarse al copiar un archivador.

-c, --compress

Comprime los archivos con el método deflate, lo que reduce el tamaño del archivo de salida. Por defecto, los archivos se guardan sin comprimir en el archivador.

--compress no surte efecto al copiar un archivador.

Nuevo en la versión 3.7.

--info

Muestra el intérprete incrustado en el archivador, para diagnósticos. En este caso cualquier otra opción se ignora, y SOURCE debe ser un archivador, no un directorio.

-h, --help

Muestra un breve mensaje sobre el modo de uso, y sale.

API de Python

El módulo define dos funciones convenientes:

zipapp.create_archive(source, target=None, interpreter=None, main=None, filter=None, compressed=False)

Crea un archivador de aplicación a partir de source. Este source (origen), puede ser cualquiera de los siguientes:

El nombre de un directorio, o un path-like object que se refiera a un directorio, en cuyo caso un nuevo archivador de aplicación se creará a partir del contenido de dicho directorio.

El nombre de un archivador de aplicación existente o un path-like object que refiera a dicho archivo, en cuyo caso el archivo se copiará al destino (modificándolo para reflejar el valor dado por el argumento interpreter. El nombre de archivo debería incluir la extensión .pyz, si se requiere.

Un objeto archivo abierto para lectura en modo bytes. El contenido del archivo debería ser un archivador de aplicación. Se infiere que el objeto archivo está posicionado al comienzo del archivador.

El argumento target determina dónde quedará escrito el archivador resultante:

Si es el nombre de un archivo, o un path-like object, el archivador será escrito a ese archivo.

Si es un objeto archivo abierto, el archivador se escribirá en ese objeto archivo, el cual debe estar abierto para escritura en modo bytes.

Si el destino (target) se omite (o es None), el origen (source) debe ser un directorio, y el destino será un archivo con el mismo nombre que el origen, con la extensión .pyz añadida.

El argumento interpreter especifica el nombre del intérprete Python con el que el archivador será ejecutado. Se escribe como una línea «shebang» al comienzo del archivador. En POSIX, el Sistema Operativo será quien lo interprete, y en Windows será gestionado por el lanzador Python. Omitir el interpreter tendrá como consecuencia que no se escribirá ninguna línea shebang. Si se especifica un intérprete y el destino (target) es un nombre de archivo, el bit de ejecución del archivo destino será activado.

El argumento main especifica el nombre de un invocable (callable) que se utilizará como programa principal para el archivador. Solamente se puede especificar si el origen (source) es un directorio que no contiene un archivo __main__.py. El argumento main debería tener la forma «pkg.module:callable», y el archivador será ejecutado importando «pkg.module» y ejecutando el callable sin argumentos. Es un error omitir main si el origen es un directorio que no contiene un archivo __main__.py, ya que esto resultaría en un archivador no ejecutable.

El argumento opcional filter especifica una función callback que se pasa como objeto Path, para representar el path (ruta) al archivo que se está añadiendo (ruta relativa al directorio origen, source). Debería retornar True si el archivo será añadido.

El argumento opcional compressed determina si los archivos están comprimidos. Si se define como True, los archivos en el archivador serán comprimidos con el método deflate.

Si se especifica un objeto archivo para source o target, es responsabilidad de quien invoca cerrarlo luego de invocar a create_archive.

Al copiar un archivador existente, los objetos archivo provistos, solamente necesitan los métodos read y readline, o bien write. Al crear un archivador a partir de un directorio, si el destino (target) es un objeto archivo, éste se pasará a la clase zipfile.ZipFile, y debe proveer los métodos que esa clase necesita.

Nuevo en la versión 3.7: Añadidos los argumentos filter y compressed.

zipapp.get_interpreter(archive)

Retorna el intérprete especificado en la línea #! al comienzo del archivador. Si no hay línea #!, retorna None. El argumento archive (archivador), puede ser un nombre de archivo o un objeto tipo archivo abierto para lectura en modo bytes. Se supone que está al principio del archivador.

Ejemplos

Empaqueta un directorio en un archivador, y lo ejecuta.

$ python -m zipapp myapp
$ python myapp.pyz
<output from myapp>

Lo mismo puede lograrse utilizando la función create_archive():

>>> import zipapp
>>> zipapp.create_archive('myapp', 'myapp.pyz')

Para que la aplicación sea ejecutable directamente en POSIX, especifica un intérprete.

$ python -m zipapp myapp -p "/usr/bin/env python"
$ ./myapp.pyz
<output from myapp>

Para reemplazar la línea shebang en un archivador existente, cree un archivador modificado, utilizando la función create_archive():

>>> import zipapp
>>> zipapp.create_archive('old_archive.pyz', 'new_archive.pyz', '/usr/bin/python3')

Para actualizar el archivo en el lugar, reemplaza en memoria utilizando un objeto BytesIO, y luego sobreescribe el origen (source). Nótese que hay un riesgo al sobreescribir un archivo en el lugar, ya que un error resultará en la pérdida del archivo original. Este código no ofrece protección contra este tipo de errores, sino que el código de producción debería hacerlo. Además, este método solamente funcionará si el archivador cabe en la memoria:

>>> import zipapp
>>> import io
>>> temp = io.BytesIO()
>>> zipapp.create_archive('myapp.pyz', temp, '/usr/bin/python2')
>>> with open('myapp.pyz', 'wb') as f:
>>>     f.write(temp.getvalue())

Especificar el intérprete

Nótese que si se especifica el intérprete y luego se distribuye el archivador de aplicación, es necesario asegurarse de que el intérprete utilizado es portable. El lanzador Python para Windows soporta las formas más comunes de líneas #! POSIX, pero hay otras cuestiones a considerar:

Si se utiliza «/usr/bin/env python» (u otras formas del comando «python», como «/usr/bin/python»), es necesario considerar que los usuarios quizá tengan tanto Python2 como Python3 como versión por defecto, y el código debe escribirse bajo ambas versiones.

Si se utiliza una versión específica, por ejemplo «/usr/bin/env python3», la aplicación no funcionará para los usuarios que no tengan esa versión. (Esta puede ser la opción deseada si no se hecho el código compatible con Python 2).

No hay manera de decir «python X.Y o posterior», así que se debe ser cuidadoso al utilizar una versión exacta, tal como «/usr/bin/env python3.4», ya que será necesario cambiar la línea shebang para usuarios de Python 3.5, por ejemplo.

Normalmente, se debería utilizar «/usr/bin/env python2» o «/usr/bin/env python3», según si el código está escrito para Python 2 ó 3.

Creando aplicaciones independientes con zipapp

Utilizando el módulo zipapp, es posible crear programas Python auto-contenidos, que pueden ser distribuidos a usuarios finales que solo necesitarán una versión adecuada de Python instalada en sus sistemas. La clave es empaquetar todas las dependencias de la aplicación dentro del archivador, junto al código de la misma.

Los pasos para crear un archivador independiente son los siguientes:

Crea tu aplicación en un directorio normalmente, tal que tengas una directorio myapp que contenga un archivo __main__.py, y cualquier código extra de la aplicación.

Instala todas las dependencias de la aplicación en el directorio myapp, usando pip:

$ python -m pip install -r requirements.txt --target myapp

(se supone que tienes los requisitos de tu proyecto en un archivo requirements.txt, de lo contrario, puedes listar manualmente las dependencias en la línea de comandos de pip).

Opcionalmente, borra los directorios .dist-info creados por pip en el directorio myapp. Éstos tienen metadatos para que pip gestione los paquetes, y como ya no se utilizará pip, no hace falta que permanezcan (aunque no causará ningún problema si los dejas).

Empaqueta la aplicación utilizando:

$ python -m zipapp -p "interpreter" myapp

Esto producirá un ejecutable independiente, que puede ser ejecutado en cualquier máquina que disponga del intérprete apropiado. Véase Especificar el intérprete para más detalles. Puede enviarse a los usuarios como un solo archivo.

En Unix, el archivo myapp.pyz será ejecutable tal como está. Puede ser renombrado, para quitar la extensión .pyz si se prefiere un nombre de comando «simple». En Windows, el archivo myapp.pyz[w] es ejecutable, ya que el intérprete Python registra las extensiones .pyz y pyzw al ser instalado.

Hacer un ejecutable para Windows

En Windows, registrar la extensión .pyz es opcional, y además hay ciertos sitios que no reconocen las extensiones registradas de manera «transparente» (el ejemplo más simple es que subprocess.run(['myapp']) no va a encontrar la aplicación, es necesario especificar explícitamente la extensión).

Por lo tanto, en Windows, suele ser preferible crear un ejecutable a partir del zipapp. Esto es relativamente fácil, aunque requiere un compilador de C. La estrategia básica se basa en que los archivos zip pueden tener datos arbitrarios antepuestos, y los archivos exe de Windows pueden tener datos arbitrarios agregados. Entonces, si se crea un lanzador adecuado mudando el archivo .pyz al final del mismo, se obtiene un solo archivo ejecutable que corre la aplicación.

Un lanzador adecuado puede ser así de simple:

#define Py_LIMITED_API 1
#include "Python.h"

#define WIN32_LEAN_AND_MEAN
#include <windows.h>

#ifdef WINDOWS
int WINAPI wWinMain(
    HINSTANCE hInstance,      /* handle to current instance */
    HINSTANCE hPrevInstance,  /* handle to previous instance */
    LPWSTR lpCmdLine,         /* pointer to command line */
    int nCmdShow              /* show state of window */
)
#else
int wmain()
#endif
{
    wchar_t **myargv = _alloca((__argc + 1) * sizeof(wchar_t*));
    myargv[0] = __wargv[0];
    memcpy(myargv + 1, __wargv, __argc * sizeof(wchar_t *));
    return Py_Main(__argc+1, myargv);
}

Si se define el símbolo de preprocesador WINDOWS, se generará una GUI (interfaz gráfica de usuario) ejecutable, y sin este símbolo, un ejecutable de consola.

Para compilar el ejecutable, se puede usar únicamente la línea de comando estándar MSVC, o se puede aprovechar la ventaja de que distutils sabe cómo compilar código fuente Python:

>>> from distutils.ccompiler import new_compiler
>>> import distutils.sysconfig
>>> import sys
>>> import os
>>> from pathlib import Path

>>> def compile(src):
>>>     src = Path(src)
>>>     cc = new_compiler()
>>>     exe = src.stem
>>>     cc.add_include_dir(distutils.sysconfig.get_python_inc())
>>>     cc.add_library_dir(os.path.join(sys.base_exec_prefix, 'libs'))
>>>     # First the CLI executable
>>>     objs = cc.compile([str(src)])
>>>     cc.link_executable(objs, exe)
>>>     # Now the GUI executable
>>>     cc.define_macro('WINDOWS')
>>>     objs = cc.compile([str(src)])
>>>     cc.link_executable(objs, exe + 'w')

>>> if __name__ == "__main__":
>>>     compile("zastub.c")

El lanzador resultante utiliza «Limited ABI», así que correrá sin cambios con cualquier versión de Python 3.x. Todo lo que necesita es que Python (python3.dll) esté en el PATH del usuario.

Para una distribución completamente independiente, se puede distribuir el lanzador con la aplicación incluida, empaquetada con la distribución «embedded» de Python. Va a funcionar en cualquier PC con la arquitectura adecuada (32 o 64 bits).

Advertencias

Hay algunas limitaciones para empaquetar la aplicación en un solo archivo. In la mayoría, si no en todos los casos, se pueden abordar sin que haga falta ningún cambio importante en la aplicación.

Si la aplicación depende de un paquete que incluye una extensión C, ese paquete no puede ser ejecutado desde un archivo zip (esta es una limitación del sistema operativo, dado que el código ejecutable debe estar presente en el sistema de archivos para que el loader del SO lo pueda cargar). En este caso, se puede excluir la dependencia del archivo zip, y requerir que los usuarios la tengan instalada, o bien distribuirla conjuntamente con el archivo zip, y agregar código al __main__.py para que incluya el directorio que contiene el módulo descomprimido en sys.path. En este caso, será necesario asegurarse de distribuir los binarios adecuados para la/s arquitectura/s a las que esté destinada la aplicación (y potencialmente elegir la versión correcta para agregar a sys.path en tiempo de ejecución, basándose en la máquina del usuario).

Al distribuir ejecutables Windows tal como se describe más arriba, hay que asegurarse de que los usuarios tienen python3.dll en su PATH (lo cual no es una opción por defecto en el instalador), o bien empaquetar la aplicación con la distribución embedded.

El lanzador que se sugiere más arriba, utiliza la API de incrustación de Python (Python embedding API). Esto significa que sys.executable será la aplicación, y no el intérprete Python convencional. El código y sus dependencias deben estar preparados para esta posibilidad. Por ejemplo, si la aplicación utiliza el módulo multiprocessing, necesitará invocar a multiprocessing.set_executable() para permitir que el módulo sepa dónde encontrar el intérprete Python estándar.

El formato de archivado Zip de aplicaciones Python

Python puede ejecutar archivadores zip que contengan un archivo __main__.py desde la versión 2.6. Para que sea ejecutada por Python, basta con que una aplicación de archivador sea un archivo zip estándar que contenga un archivo __main__.py, el cual será ejecutado como punto de entrada para la aplicación. Como es usual para cualquier script Python, el elemento padre del script (en este caso, el archivo zip), será ubicado en sys.path, por lo que pueden importarse otros módulos desde el archivo zip.

El formato de archivo zip, permite que se antepongan al archivo datos arbitrarios. El formato de aplicación zip utiliza esta capacidad para anteponer una línea «shebang» POSIX estándar al archivo (#!/ruta/al/interprete).

Formalmente, el Formato de archivado Zip de aplicaciones Python es:

Una línea shebang opcional, conteniendo los caracteres``b”#!”`` seguidos por un nombre de intérprete, y luego un carácter de nueva línea (b'\n'). El nombre del intérprete puede ser cualquiera que sea aceptable para el procesamiento de shebang del Sistema Operativo, o el lanzador Python en Windows. El intérprete debería estar codificado en UTF-8 en Windows, y en sys.getfilesystemencoding() en POSIX.

Los datos estándares de archivo zip, tal como se generan en el módulo zipfile. El contenido del archivo zip debe incluir un archivo llamado __main__.py (que debe estar en la «raíz» del archivo zip, es decir, no puede estar en un subdirectorio). El los datos del archivo zip pueden estar comprimidos o no.

Si un archivador de aplicación tiene una línea de shebang, puede tener el bit de ejecución activado en los sistemas POSIX, para permitir que sea ejecutado directamente.

No se requiere que las herramientas de este módulo sean las que se utilicen para crear archivadores de aplicación. El módulo es útil, pero cualquier archivo que esté en el formato descripto anteriormente es aceptable para Python, no importa cómo haya sido creado.

Servicios en tiempo de ejecución de Python

Los módulos descritos en este capítulo proporcionan una amplia gama de servicios relacionados con el intérprete de Python y su interacción con su entorno. Esta es una descripción general:

sys — Parámetros y funciones específicos del sistema

sysconfig — Proporciona acceso a la información de configuración de Python

Variables de configuración

Rutas de instalación

Otras funciones

Usando sysconfig como un script

builtins — Objetos incorporados

__main__ — Entorno de script del nivel superior

warnings — Control de advertencias

Categorías de advertencia

El filtro de advertencias

Descripción de los filtros de advertencia

Filtro de advertencia predeterminado

Anulando el filtro por defecto

Eliminación temporal de las advertencias

Advertencias de prueba

Actualización del código para las nuevas versiones de las dependencias

Funciones Disponibles

Gestores de Contexto disponibles

dataclasses — Clases de datos

Decoradores, clases y funciones del módulo

Procesamiento posterior a la inicialización

Variables de clase

Variable de solo inicialización

Instancias congeladas

Herencia

Funciones fábrica por defecto

Valores por defecto mutables

Excepciones

contextlib — Utilidades para declaraciones de contexto with

Utilidades

Ejemplos y recetas

Apoyando un número variable de gestores de contexto

Capturando excepciones de los métodos __enter__

Limpieza en una implementación __enter__

Reemplazar cualquier uso de try-finally y marcar variables

Usar un gestor de contexto como decorador de funciones

Gestores de contexto de uso único, reutilizables y reentrantes

Gestores contextuales reentrantes

Gestores contextuales reutilizables

abc — Clases de Base Abstracta

atexit — Gestores de Salida

Ejemplo con atexit

traceback — Imprimir o recuperar un seguimiento de pila

Objetos TracebackException

Objetos StackSummary

Objetos FrameSummary

Ejemplos de seguimiento de pila

__future__ — Definiciones de declaraciones futuras

gc — Interfaz del recolector de basura

inspect — Inspeccionar objetos vivos

Tipos y miembros

Recuperar el código fuente

Introspección de los invocables con el objeto Signature

Clases y funciones

La pila del interprete

Obteniendo atributos estáticamente

Estado actual de los Generadores y las Corutinas

Objetos de código Bit Flags

Interfaz de la línea de comando

site — Enlace (hook) de configuración específico del sitio

Configuración de Readline

Contenido del módulo

Interfaz de línea de comando

sys — Parámetros y funciones específicos del sistema

Este módulo provee acceso a algunas variables usadas o mantenidas por el intérprete y a funciones que interactúan fuertemente con el intérprete. Siempre está disponible.

sys.abiflags

En los sistemas POSIX donde Python se construyó con el script estándar configure, este contiene los indicadores ABI según lo especificado por PEP 3149 [https://www.python.org/dev/peps/pep-3149].

Distinto en la versión 3.8: Los flags por defecto se convirtieron en una cadena de caracteres vacía (el flag m para pymalloc ha sido eliminado).

Nuevo en la versión 3.2.

sys.addaudithook(hook)

Append the callable hook to the list of active auditing hooks for the current (sub)interpreter.

When an auditing event is raised through the sys.audit() function, each hook will be called in the order it was added with the event name and the tuple of arguments. Native hooks added by PySys_AddAuditHook() are called first, followed by hooks added in the current (sub)interpreter. Hooks can then log the event, raise an exception to abort the operation, or terminate the process entirely.

Calling sys.addaudithook() will itself raise an auditing event named sys.addaudithook with no arguments. If any existing hooks raise an exception derived from RuntimeError, the new hook will not be added and the exception suppressed. As a result, callers cannot assume that their hook has been added unless they control all existing hooks.

See the audit events table for all events raised by CPython, and PEP 578 [https://www.python.org/dev/peps/pep-0578] for the original design discussion.

Nuevo en la versión 3.8.

Distinto en la versión 3.8.1: Las excepciones derivadas de Exception pero no RuntimeError ya no se suprimen.

CPython implementation detail: Cuando el rastreo está habilitado (ver settrace()), los ganchos de Python solo se rastrean si el invocable tiene un miembro __cantrace__ que se establece en un valor verdadero. De lo contrario, las funciones de seguimiento omitirán el enlace.

sys.argv

La lista de argumentos de la línea de comandos pasados a un script de Python. argv[0] es el nombre del script (depende del sistema operativo si se trata de una ruta completa o no). Si el comando se ejecutó usando la opción -c de la línea de comandos del intérprete, argv[0] se establece en la cadena de caracteres '-c'. Si no se pasó ningún nombre de secuencia de comandos al intérprete de Python, argv[0] es la cadena de caracteres vacía.

Para recorrer la entrada estándar, o la lista de archivos dada en la línea de comando, vea el módulo fileinput.

Nota

En Unix, los argumentos de la línea de comandos se pasan por bytes desde el sistema operativo. Python los decodifica con la codificación del sistema de archivos y el controlador de errores «surrogateescape». Cuando necesite bytes originales, puede obtenerlos mediante [os.fsencode (arg) for arg in sys.argv].

sys.audit(event, *args)

Activar un evento de auditoría y activar cualquier hook de auditoría activo. event es una cadena que identifica el evento, y args puede contener argumentos opcionales con más información sobre el evento. El número y los tipos de argumentos para un evento determinado se consideran una API pública y estable y no deberían modificarse entre versiones.

Por ejemplo, un evento de auditoría se llama os.chdir. Este evento tiene un argumento llamado path que contendrá el nuevo directorio de trabajo solicitado.

sys.audit() llamará a los ganchos de auditoría existentes, pasando el nombre del evento y los argumentos, y volverá a lanzar la primera excepción de cualquier hook. En general, si se lanza una excepción, no debería ser manejada y el proceso debería terminar lo más rápidamente posible. Esto permite que las implementaciones de los hook decidan cómo responder a determinados eventos: pueden limitarse a registrar el evento o abortar la operación lanzando una excepción.

Los ganchos se agregan usando las funciones sys.addaudithook() o PySys_AddAuditHook().

El equivalente nativo de esta función es PySys_Audit(). Se prefiere usar la función nativa cuando sea posible.

Consulte la tabla de eventos de auditoría para todos los eventos lanzados por CPython.

Nuevo en la versión 3.8.

sys.base_exec_prefix

Se establece durante el inicio de Python, antes de que se ejecute site.py, en el mismo valor que exec_prefix. Si no se ejecuta en un entorno virtual, los valores permanecerán iguales; Si site.py encuentra que se está utilizando un entorno virtual, los valores de prefix y exec_prefix se cambiarán para apuntar al entorno virtual, mientras que base_prefix y base_exec_prefix seguirá apuntando a la instalación base de Python (aquella desde la que se creó el entorno virtual).

Nuevo en la versión 3.3.

sys.base_prefix

Se establece durante el inicio de Python, antes de que se ejecute site.py, al mismo valor que prefix. Si no se ejecuta en un entorno virtual, los valores permanecerán iguales; si site.py encuentra que se está utilizando un entorno virtual, los valores de prefix y exec_prefix se cambiarán para apuntar al entorno virtual, mientras que base_prefix y base_exec_prefix seguirá apuntando a la instalación base de Python (aquella desde la que se creó el entorno virtual).

Nuevo en la versión 3.3.

sys.byteorder

Un indicador del orden de bytes nativo. Esto tendrá el valor 'big' en las plataformas big-endian (el byte más significativo primero) y 'little' en las plataformas little-endian (el byte menos significativo primero).

sys.builtin_module_names

Una tupla de cadenas de caracteres que proporciona los nombres de todos los módulos que se compilan en este intérprete de Python. (Esta información no está disponible de ninguna otra manera — modules.keys() solo enumera los módulos importados.)

sys.call_tracing(func, args)

Llame a func(*args), mientras el rastreo está habilitado. El estado de seguimiento se guarda y se restaura posteriormente. Esto está destinado a ser llamado desde un depurador desde un punto de control, para depurar recursivamente algún otro código.

sys.copyright

Una cadena de caracteres que contiene los derechos de autor pertenecientes al intérprete de Python.

sys._clear_type_cache()

Borre la caché de tipo interno. La caché de tipos se utiliza para acelerar las búsquedas de métodos y atributos. Utilice la función solo para eliminar referencias innecesarias durante la depuración de fugas de referencia.

Esta función debe usarse solo para fines internos y especializados.

sys._current_frames()

Retorna un diccionario que asigna el identificador de cada subproceso al marco de pila superior actualmente activo en ese subproceso en el momento en que se llama a la función. Tenga en cuenta que las funciones en el módulo traceback pueden construir la pila de llamadas dado tal marco.

Esto es más útil para depurar deadlock: esta función no requiere la cooperación de los subprocesos con deadlock, y las pilas de llamadas de dichos subprocesos se congelan mientras permanezcan en deadlock. El marco retornado para un subproceso no en deadlock puede no tener relación con la actividad actual de ese subproceso en el momento en que el código de llamada examina el marco.

Esta función debe usarse solo para fines internos y especializados.

Lanza un auditing event sys._current_frames sin argumentos.

sys.breakpointhook()

Esta función de gancho es llamada por built-in breakpoint(). De forma predeterminada, lo coloca en el depurador pdb, pero se puede configurar en cualquier otra función para que pueda elegir qué depurador se utiliza.

La firma de esta función depende de lo que llame. Por ejemplo, el enlace predeterminado (por ejemplo, pdb.set_trace()) no espera argumentos, pero puede vincularlo a una función que espera argumentos adicionales (posicional o palabra clave). La función incorporada breakpoint() pasa sus *args y **kws directamente. Lo que sea que retorne breakpointhooks() se retorna desde breakpoint().

La implementación predeterminada consulta primero la variable de entorno PYTHONBREAKPOINT. Si se establece en "0", esta función vuelve inmediatamente; es decir, no es una operación. Si la variable de entorno no se establece, o se establece en la cadena vacía, se llama a pdb.set_trace(). De lo contrario, esta variable debería nombrar una función para ejecutar, utilizando la nomenclatura de importación con puntos de Python, por ejemplo package.subpackage.module.function. En este caso, se importaría package.subpackage.module y el módulo resultante debe tener un invocable llamado function(). Esto se ejecuta, pasando *args y **kws, y lo que sea que function() retorna, sys.breakpointhook() retorna a la función breakpoint().

Tenga en cuenta que si algo sale mal al importar el invocable nombrado por PYTHONBREAKPOINT, se informa un RuntimeWarning y se ignora el punto de interrupción (breakpoint).

También tenga en cuenta que si sys.breakpointhook() se anula mediante programación, PYTHONBREAKPOINT no se consulta.

Nuevo en la versión 3.7.

sys._debugmallocstats()

Imprime información de bajo nivel para stderr sobre el estado del asignador de memoria de CPython.

Si Python está configurado –with-pydebug, también realiza algunas comprobaciones de consistencia internas costosas.

Nuevo en la versión 3.3.

CPython implementation detail: Esta función es específica de CPython. El formato exacto de salida no se define aquí y puede cambiar.

sys.dllhandle

Número entero que especifica el identificador de la DLL de Python.

Disponibilidad: Windows.

sys.displayhook(value)

Si value no es None, esta función imprime repr(value) en sys.stdout y guarda value en builtins._. Si repr(value) no se puede codificar en sys.stdout.encoding con el controlador de errores sys.stdout.errors (que probablemente sea 'strict'), codifíquelo para sys.stdout.encoding con el controlador de errores 'backslashreplace'.

Se llama a sys.displayhook como resultado de evaluar un expression ingresado en una sesión interactiva de Python. La visualización de estos valores se puede personalizar asignando otra función de un argumento a sys.displayhook.

Pseudo-código:

def displayhook(value):
    if value is None:
        return
    # Set '_' to None to avoid recursion
    builtins._ = None
    text = repr(value)
    try:
        sys.stdout.write(text)
    except UnicodeEncodeError:
        bytes = text.encode(sys.stdout.encoding, 'backslashreplace')
        if hasattr(sys.stdout, 'buffer'):
            sys.stdout.buffer.write(bytes)
        else:
            text = bytes.decode(sys.stdout.encoding, 'strict')
            sys.stdout.write(text)
    sys.stdout.write("\n")
    builtins._ = value

Distinto en la versión 3.2: Usa el manejador de error 'backslashreplace' en UnicodeEncodeError.

sys.dont_write_bytecode

Si esto es cierto, Python no intentará escribir archivos .pyc en la importación de módulos fuente. Este valor se establece inicialmente en True o False según la opción -B de la línea de comando y la variable de entorno PYTHONDONTWRITEBYTECODE, pero puede configurarlo usted mismo para controlar el código de bytes generación de archivos.

sys.pycache_prefix

Si esto está configurado (no None), Python escribirá archivos de bytecode-cache .pyc en (y los leerá desde) un árbol de directorios paralelo enraizado en este directorio, en lugar de __pycache__ directorios en el árbol de código fuente. Cualquier directorio __pycache__ en el árbol de código fuente será ignorado y los nuevos archivos .pyc se escribirán dentro del prefijo pycache. Por lo tanto, si usa compileall como paso previo a la compilación, debe asegurarse de ejecutarlo con el mismo prefijo de pycache (si lo hay) que usará en tiempo de ejecución.

Una ruta relativa se interpreta en relación con el directorio de directorio actual.

Este valor se establece inicialmente en función del valor de la opción de línea de comandos -X pycache_prefix=PATH o la variable de entorno PYTHONPYCACHEPREFIX (la línea de comandos tiene prioridad). Si no se establece ninguno, es None.

Nuevo en la versión 3.8.

sys.excepthook(type, value, traceback)

Esta función imprime un rastreo y una excepción dados a sys.stderr.

Cuando se genera una excepción y no se detecta, el intérprete llama a sys.excepthook con tres argumentos, la clase de excepción, la instancia de excepción y un objeto de rastreo. En una sesión interactiva, esto sucede justo antes de que se retorna el control al indicador; en un programa de Python esto sucede justo antes de que el programa salga. El manejo de tales excepciones de nivel superior se puede personalizar asignando otra función de tres argumentos a sys.excepthook.

Lanza un auditing event sys.excepthook con argumentos hook, type, value, traceback.

Ver también

La función sys.unraisablehook() maneja las excepciones que no se pueden evaluar y la función threading.excepthook() maneja la excepción lanzada por threading.Thread.run().

sys.__breakpointhook__

sys.__displayhook__

sys.__excepthook__

sys.__unraisablehook__

Estos objetos contienen los valores originales de breakpointhook, displayhook, excepthook y unraisablehook al inicio del programa. Se guardan para que breakpointhook, displayhook y excepthook, unraisablehook se puedan restaurar en caso de que sean reemplazados por objetos rotos o alternativos.

Nuevo en la versión 3.7: __breakpointhook__

Nuevo en la versión 3.8: __unraisablehook__

sys.exc_info()

Esta función retorna una tupla de tres valores que proporcionan información sobre la excepción que se está manejando actualmente. La información retornada es específica tanto del hilo actual como del marco de pila actual. Si el marco de pila actual no está manejando una excepción, la información se toma del marco de pila que llama, o de quien la llama, y así sucesivamente hasta que se encuentra un marco de pila que está manejando una excepción. Aquí, «manejar una excepción» se define como «ejecutar una cláusula except». Para cualquier marco de pila, solo se puede acceder a la información sobre la excepción que se maneja actualmente.

Si no se maneja ninguna excepción en ninguna parte de la pila, se retorna una tupla que contiene tres valores None. De lo contrario, los valores retornados son (type, value, traceback). Su significado es: type obtiene el tipo de excepción que se está manejando (una subclase de BaseException); value obtiene la instancia de excepción (una instancia del tipo de excepción); traceback obtiene un objeto traceback que encapsula la pila de llamadas en el punto donde ocurrió originalmente la excepción.

sys.exec_prefix

Una cadena de caracteres que proporciona el prefijo de directorio específico del sitio donde están instalados los archivos Python dependientes de la plataforma; de forma predeterminada, también es '/usr/local'. Esto se puede configurar en el momento de la compilación con el argumento --exec-prefix del script configure. Específicamente, todos los archivos de configuración (por ejemplo, el archivo de encabezado pyconfig.h) se instalan en el directorio exec_prefix/lib/pythonXY/config, y los módulos de la biblioteca compartida se instalan en exec_prefix/lib/pythonXY/lib-dynload, donde XY es el número de versión de Python, por ejemplo,``3.2``.

Nota

Si un virtual environment está en efecto, este valor se cambiará en site.py para apuntar al entorno virtual. El valor para la instalación de Python seguirá estando disponible a través de base_exec_prefix.

sys.executable

Una cadena de caracteres que proporciona la ruta absoluta del binario ejecutable para el intérprete de Python, en sistemas donde esto tiene sentido. Si Python no puede recuperar la ruta real a su ejecutable, sys.executable será una cadena de caracteres vacía o None.

sys.exit([arg])

Raise a SystemExit exception, signaling an intention to exit the interpreter.

El argumento opcional arg puede ser un número entero que dé el estado de salida (por defecto es cero) u otro tipo de objeto. Si es un número entero, cero se considera «terminación exitosa» y cualquier valor distinto de cero se considera «terminación anormal» por los shells y similares. La mayoría de los sistemas requieren que esté en el rango 0-127 y, de lo contrario, producen resultados indefinidos. Algunos sistemas tienen una convención para asignar significados específicos a códigos de salida específicos, pero estos generalmente están subdesarrollados; Los programas Unix generalmente usan 2 para errores de sintaxis de línea de comandos y 1 para todos los demás tipos de errores. Si se pasa otro tipo de objeto, None equivale a pasar cero, y cualquier otro objeto se imprime en stderr y da como resultado un código de salida de 1. En particular, sys.exit("algún mensaje de error") es una forma rápida de salir de un programa cuando ocurre un error.

Since exit() ultimately «only» raises an exception, it will only exit the process when called from the main thread, and the exception is not intercepted. Cleanup actions specified by finally clauses of try statements are honored, and it is possible to intercept the exit attempt at an outer level.

Distinto en la versión 3.6: Si se produce un error en la limpieza después de que el intérprete de Python haya detectado SystemSalir (como un error al vaciar los datos almacenados en el búfer en los flujos estándar), el estado de salida cambia a 120.

sys.flags

El named tuple flags expone el estado de los indicadores de la línea de comando. Los atributos son de solo lectura.

atributo

flag

debug

-d

inspect

-i

interactive

-i

isolated

-I

optimize

-O o -OO

dont_write_bytecode

-B

no_user_site

-s

no_site

-S

ignore_environment

-E

verbose

-v

bytes_warning

-b

quiet

-q

hash_randomization

-R

dev_mode

-X dev (Modo de desarrollo de Python)

utf8_mode

-X utf8

int_max_str_digits

-X int_max_str_digits (integer string conversion length limitation)

Distinto en la versión 3.2: Agregado el atributo quiet para el nuevo flag -q.

Nuevo en la versión 3.2.3: El atributo hash_randomization.

Distinto en la versión 3.3: Eliminado el atributo obsoleto division_warning.

Distinto en la versión 3.4: Agregado el atributo isolated para el flag -I isolated.

Distinto en la versión 3.7: Added the dev_mode attribute for the new Python Development Mode and the utf8_mode attribute for the new -X utf8 flag.

Distinto en la versión 3.9.14: Added the int_max_str_digits attribute.

sys.float_info

Un named tuple que contiene información sobre el tipo de flotante. Contiene información de bajo nivel sobre la precisión y la representación interna. Los valores corresponden a las diversas constantes de coma flotante definidas en el archivo de encabezado estándar float.h para el lenguaje de programación “C”; consulte la sección 5.2.4.2.2 de la norma ISO/IEC C de 1999 [C99], “Características de los tipos flotantes”, para obtener más detalles.

atributo

macro float.h

explicación

epsilon

DBL_EPSILON

diferencia entre 1.0 y el menor valor mayor que 1.0 que es representable como flotante

Vea también math.ulp().

dig

DBL_DIG

número máximo de dígitos decimales que se pueden representar fielmente en un flotante; véase a continuación

mant_dig

DBL_MANT_DIG

precisión de flotantes: el número de dígitos base-radix en el significando de un flotante

max

DBL_MAX

máximo punto flotante positivo representable

max_exp

DBL_MAX_EXP

entero máximo e tal que radix**(e-1) es un flotante finito representable

max_10_exp

DBL_MAX_10_EXP

entero máximo e tal que 10**e está en el rango de flotantes finitos representables

min

DBL_MIN

flotante normalizado mínimo representable positivo

Usa math.ulp(0.0) para obtener el menor flotante positivo denormalizado representable.

min_exp

DBL_MIN_EXP

entero mínimo e tal que radix**(e-1) es un flotante normalizado

min_10_exp

DBL_MIN_10_EXP

entero mínimo e tal que 10**e es un valor flotante normalizado

radix

FLT_RADIX

base de representación de exponente

rounds

FLT_ROUNDS

constante entera que representa el modo de redondeo utilizado para operaciones aritméticas. Esto refleja el valor de la macro FLT_ROUNDS del sistema en el momento de inicio del intérprete. Consulte la sección 5.2.4.2.2 del estándar C99 para obtener una explicación de los posibles valores y sus significados.

El atributo sys.float_info.dig necesita más explicación. Si s es cualquier cadena que represente un número decimal con como máximo sys.float_info.dig dígitos significativos, entonces la conversión de s a un flotante y viceversa recuperará una cadena que representa el mismo decimal valor:

>>> import sys
>>> sys.float_info.dig
15
>>> s = '3.14159265358979'    # decimal string with 15 significant digits
>>> format(float(s), '.15g')  # convert to float and back -> same value
'3.14159265358979'

Pero para cadenas con más de sys.float_info.dig dígitos significativos, esto no siempre es cierto:

>>> s = '9876543211234567'    # 16 significant digits is too many!
>>> format(float(s), '.16g')  # conversion changes value
'9876543211234568'

sys.float_repr_style

Una cadena que indica cómo se comporta la función repr() para los flotantes. Si la cadena tiene el valor 'short', entonces para un flotante finito x, repr(x) tiene como objetivo producir una cadena corta con la propiedad de que float(repr(x)) == x. Este es el comportamiento habitual en Python 3.1 y posteriores. De lo contrario, float_repr_style tiene el valor 'legacy' y repr(x) se comporta de la misma manera que en las versiones de Python anteriores a la 3.1.

Nuevo en la versión 3.1.

sys.getallocatedblocks()

Retorna el número de bloques de memoria asignados actualmente por el intérprete, independientemente de su tamaño. Esta función es principalmente útil para rastrear y depurar pérdidas de memoria. Debido a los cachés internos del intérprete, el resultado puede variar de una llamada a otra; puede que tenga que llamar a _clear_type_cache() y gc.collect() para obtener resultados más predecibles.

Si una construcción o implementación de Python no puede calcular razonablemente esta información, getallocatedblocks() puede retornar 0 en su lugar.

Nuevo en la versión 3.4.

sys.getandroidapilevel()

Retorna la versión de la API de tiempo de compilación de Android como un número entero.

Disponibilidad: Android.

Nuevo en la versión 3.7.

sys.getdefaultencoding()

Retorna el nombre de la codificación de cadena predeterminada actual utilizada por la implementación de Unicode.

sys.getdlopenflags()

Retorna el valor actual de las flags que se utilizan para llamadas dlopen(). Los nombres simbólicos para los valores de las flags se pueden encontrar en el módulo os (constantes RTLD_xxx, por ejemplo os.RTLD_LAZY).

Disponibilidad: Unix.

sys.getfilesystemencoding()

Retorna el nombre de la codificación utilizada para convertir entre nombres de archivo Unicode y nombres de archivo en bytes. Para una mejor compatibilidad, se debe utilizar str para los nombres de archivo en todos los casos, aunque también se admite la representación de nombres de archivo como bytes. Las funciones que aceptan o retornan nombres de archivo deben admitir str o bytes y se deben convertir internamente a la representación preferida del sistema.

Esta codificación es siempre compatible con ASCII.

os.fsencode() y os.fsdecode() deben usarse para garantizar que se utilizan la codificación correcta y el modo de errores.

En el modo UTF-8, la codificación es utf-8 en cualquier plataforma.

En macOS, la codificación es 'utf-8'.

En Unix, la codificación es la codificación local.

En Windows, la codificación puede ser 'utf-8' o 'mbcs', según la configuración del usuario.

En Android, la codificación es 'utf-8'.

En VxWorks, la codificación es 'utf-8'.

Distinto en la versión 3.2: el resultado de getfilesystemencoding() ya no puede ser None.

Distinto en la versión 3.6: Ya no se garantiza que Windows retorne 'mbcs'. Consulte PEP 529 [https://www.python.org/dev/peps/pep-0529] y _enablelegacywindowsfsencoding() para obtener más información.

Distinto en la versión 3.7: Retorna “utf-8” en el modo UTF-8.

sys.getfilesystemencodeerrors()

Retorna el nombre del modo de error utilizado para convertir entre nombres de archivo Unicode y nombres de archivo en bytes. El nombre de la codificación se retorna desde getfilesystemencoding().

os.fsencode() y os.fsdecode() deben usarse para garantizar que se utilizan la codificación correcta y el modo de errores.

Nuevo en la versión 3.6.

sys.get_int_max_str_digits()

Returns the current value for the integer string conversion length limitation. See also set_int_max_str_digits().

Nuevo en la versión 3.9.14.

sys.getrefcount(object)

Retorna el recuento de referencias del object. El recuento retornado es generalmente uno más alto de lo que cabría esperar, porque incluye la referencia (temporal) como argumento para getrefcount().

sys.getrecursionlimit()

Retorna el valor actual del límite de recursividad, la profundidad máxima de la pila de intérpretes de Python. Este límite evita que la recursividad infinita cause un desbordamiento de la pila C y bloquee Python. Se puede configurar mediante setrecursionlimit().

sys.getsizeof(object[, default])

Retorna el tamaño de un objeto en bytes. El objeto puede ser cualquier tipo de objeto. Todos los objetos integrados retornarán resultados correctos, pero esto no tiene por qué ser cierto para las extensiones de terceros, ya que es una implementación específica.

Solo se tiene en cuenta el consumo de memoria atribuido directamente al objeto, no el consumo de memoria de los objetos a los que se refiere.

Si se proporciona, se retornará predeterminado si el objeto no proporciona los medios para recuperar el tamaño. De lo contrario, se generará un TypeError.

getsizeof() llama al método __sizeof__ del objeto y agrega una sobrecarga adicional del recolector de basura si el objeto es administrado por el recolector de basura.

Consulte receta de sizeof recursivo [https://code.activestate.com/recipes/577504] para ver un ejemplo del uso de getsizeof() de forma recursiva para encontrar el tamaño de los contenedores y todo su contenido.

sys.getswitchinterval()

Retorna el «intervalo de cambio de hilo» del intérprete; ver setswitchinterval().

Nuevo en la versión 3.2.

sys._getframe([depth])

Retorna un objeto de marco de la pila de llamadas. Si se proporciona un entero opcional depth, retorna el objeto de marco que muchas llamadas debajo de la parte superior de la pila. Si eso es más profundo que la pila de llamadas, se lanza ValueError. El valor predeterminado de depth es cero, lo que retorna el marco en la parte superior de la pila de llamadas.

Lanza un auditing event sys._getframe sin argumentos.

CPython implementation detail: Esta función debe utilizarse únicamente para fines internos y especializados. No se garantiza que exista en todas las implementaciones de Python.

sys.getprofile()

Obtiene la función de generador de perfiles establecida por setprofile().

sys.gettrace()

Obtiene la función de seguimiento (trace) establecida por settrace().

CPython implementation detail: La función gettrace() está pensada solo para implementar depuradores, perfiladores, herramientas de cobertura y similares. Su comportamiento es parte de la plataforma de implementación, en lugar de parte de la definición del lenguaje y, por lo tanto, es posible que no esté disponible en todas las implementaciones de Python.

sys.getwindowsversion()

Retorna una tupla con nombre que describe la versión de Windows que se está ejecutando actualmente. Los elementos nombrados son major, minor, build, platform, service_pack, service_pack_minor, service_pack_major, suite_mask, product_type y platform_version. service_pack contiene una cadena de caracteres, platform_version una tupla de 3 y todos los demás valores son números enteros. También se puede acceder a los componentes por su nombre, por lo que sys.getwindowsversion()[0] es equivalente a sys.getwindowsversion().major. Para compatibilidad con versiones anteriores, solo los primeros 5 elementos se pueden recuperar mediante la indexación.

platform será 2 (VER_PLATFORM_WIN32_NT).

product_type puede ser uno de los siguientes valores:

Constante

Significado

1 (VER_NT_WORKSTATION)

El sistema es una estación de trabajo.

2 (VER_NT_DOMAIN_CONTROLLER)

El sistema es un controlador de dominio.

3 (VER_NT_SERVER)

El sistema es un servidor, pero no un controlador de dominio.

Esta función envuelve la función Win32 GetVersionEx(); consulte la documentación de Microsoft en OSVERSIONINFOEX() para obtener más información sobre estos campos.

platform_version returns the major version, minor version and build number of the current operating system, rather than the version that is being emulated for the process. It is intended for use in logging rather than for feature detection.

Nota

platform_version derives the version from kernel32.dll which can be of a different version than the OS version. Please use platform module for achieving accurate OS version.

Disponibilidad: Windows.

Distinto en la versión 3.2: Cambiada a una tupla con nombre y agregado service_pack_minor, service_pack_major, suite_mask, y product_type.

Distinto en la versión 3.6: Agregado platform_version

sys.get_asyncgen_hooks()

Retorna un objeto asyncgen_hooks, que es similar a namedtuple de la forma (firstiter, finalizer), donde se espera que firstiter y finalizer sean None o funciones que toman un asynchronous generator iterator como argumento, y se utilizan para programar la finalización de un generador asíncrono mediante un bucle de eventos.

Nuevo en la versión 3.6: Ver PEP 525 [https://www.python.org/dev/peps/pep-0525] para más detalles.

Nota

Esta función se ha añadido de forma provisional (consulte PEP 411 [https://www.python.org/dev/peps/pep-0411] para obtener más detalles).

sys.get_coroutine_origin_tracking_depth()

Obtiene la profundidad de seguimiento del origen de la corrutina actual, según lo establecido por set_coroutine_origin_tracking_depth().

Nuevo en la versión 3.7.

Nota

Esta función se ha añadido de forma provisional (consulte PEP 411 [https://www.python.org/dev/peps/pep-0411] para obtener más detalles). Úsela sólo para fines de depuración.

sys.hash_info

A named tuple dando parámetros de la implementación de hash numérico. Para obtener más detalles sobre el hash de tipos numéricos, consulte Calculo del hash de tipos numéricos.

atributo

explicación

width

ancho en bits usado para valores hash

modulus

primer módulo P utilizado para el esquema de hash numérico

inf

valor hash retornado para un infinito positivo

nan

valor hash retornado para un nan

imag

multiplicador utilizado para la parte imaginaria de un número complejo

algorithm

nombre del algoritmo para el hash de str, bytes y memoryview

hash_bits

tamaño de salida interno del algoritmo hash

seed_bits

tamaño de la clave semilla del algoritmo hash

Nuevo en la versión 3.2.

Distinto en la versión 3.4: Agregado algoritmo, hash_bits y seed_bits

sys.hexversion

El número de versión codificado como un solo entero. Se garantiza que esto aumentará con cada versión, incluido el soporte adecuado para versiones que no son de producción. Por ejemplo, para probar que el intérprete de Python es al menos la versión 1.5.2, use:

if sys.hexversion >= 0x010502F0:
    # use some advanced feature
    ...
else:
    # use an alternative implementation or warn the user
    ...

Esto se llama hexversion ya que solo parece realmente significativo cuando se ve como el resultado de pasarlo a la función incorporada hex(). El named tuple sys.version_info puede usarse para una codificación más amigable para los humanos de la misma información.

Se pueden encontrar más detalles de hexversion en Versiones de API y ABI.

sys.implementation

Un objeto que contiene información sobre la implementación del intérprete de Python en ejecución. Los siguientes atributos deben existir en todas las implementaciones de Python.

name es el identificador de la implementación, por ejemplo 'cpython'. La cadena de caracteres real está definida por la implementación de Python, pero se garantiza que estará en minúsculas.

version es una tupla con nombre, en el mismo formato que sys.version_info. Representa la versión de la implementación de Python. Esto tiene un significado distinto de la versión específica del lenguaje de Python al que se ajusta el intérprete que se está ejecutando actualmente, que representa sys.version_info. Por ejemplo, para PyPy 1.8 sys.implementation.version podría ser sys.version_info(1, 8, 0, 'final', 0), mientras que sys.version_info sería sys.version_info(2, 7, 2, 'final', 0). Para CPython tienen el mismo valor, ya que es la implementación de referencia.

hexversion es la versión de implementación en formato hexadecimal, como sys.hexversion.

cache_tag es la etiqueta utilizada por la maquinaria de importación en los nombres de archivo de los módulos almacenados en caché. Por convención, sería una combinación del nombre y la versión de la implementación, como 'cpython-33'. Sin embargo, una implementación de Python puede usar algún otro valor si corresponde. Si cache_tag está configurado como None, indica que el almacenamiento en caché del módulo debe estar deshabilitado.

sys.implementation puede contener atributos adicionales específicos de la implementación de Python. Estos atributos no estándar deben comenzar con un guion bajo y no se describen aquí. Independientemente de su contenido, sys.implementation no cambiará durante la ejecución del intérprete, ni entre las versiones de implementación. (Sin embargo, puede cambiar entre las versiones del lenguaje Python). Consulte PEP 421 [https://www.python.org/dev/peps/pep-0421] para obtener más información.

Nuevo en la versión 3.3.

Nota

La adición de nuevos atributos obligatorios debe pasar por el proceso normal de PEP. Consulte PEP 421 [https://www.python.org/dev/peps/pep-0421] para obtener más información.

sys.int_info

Un named tuple que contiene información sobre la representación interna de Python de los enteros. Los atributos son de solo lectura.

Atributo

Explicación

bits_per_digit

número de bits retenidos en cada dígito. Los enteros de Python se almacenan internamente en la base 2**int_info.bits_per_digit

sizeof_digit

tamaño en bytes del tipo C utilizado para representar un dígito

default_max_str_digits

default value for sys.get_int_max_str_digits() when it is not otherwise explicitly configured.

str_digits_check_threshold

minimum non-zero value for sys.set_int_max_str_digits(), PYTHONINTMAXSTRDIGITS, or -X int_max_str_digits.

Nuevo en la versión 3.1.

Distinto en la versión 3.9.14: Added default_max_str_digits and str_digits_check_threshold.

sys.__interactivehook__

Cuando existe este atributo, su valor se llama automáticamente (sin argumentos) cuando se lanza el intérprete en modo interactivo. Esto se hace después de leer el archivo PYTHONSTARTUP, para que pueda establecer este enlace allí. El módulo site establece este.

Lanza un auditing event cpython.run_interactivehook con el argumento hook.

Nuevo en la versión 3.4.

sys.intern(string)

Ingresa string en la tabla de cadenas de caracteres «internadas» y retorna la cadena de caracteres interna, que es string en sí misma o una copia. Internar cadenas de caracteres es útil para obtener un poco de rendimiento en la búsqueda de diccionario: si las claves en un diccionario están internadas y la clave de búsqueda está interna, las comparaciones de claves (después del hash) se pueden realizar mediante una comparación de punteros en lugar de una comparación de cadenas. Normalmente, los nombres utilizados en los programas de Python se internan automáticamente, y los diccionarios utilizados para contener los atributos de módulo, clase o instancia tienen claves internas.

Las cadenas de caracteres internas no son inmortales; debe mantener una referencia al valor de retorno de intern() para beneficiarse de él.

sys.is_finalizing()

Retorna True si el intérprete de Python es shutting down, False en caso contrario.

Nuevo en la versión 3.5.

sys.last_type

sys.last_value

sys.last_traceback

Estas tres variables no siempre están definidas; se establecen cuando no se maneja una excepción y el intérprete imprime un mensaje de error y un seguimiento de la pila. Su uso previsto es permitir que un usuario interactivo importe un módulo depurador y realice una depuración post-mortem sin tener que volver a ejecutar el comando que provocó el error. (El uso típico es import pdb; pdb.pm() para ingresar al depurador post-mortem; consulte módulo pdb para obtener más información).

El significado de las variables es el mismo que el de los valores retornados de exc_info() arriba.

sys.maxsize

Un entero que da el valor máximo que puede tomar una variable de tipo Py_ssize_t. Suele ser 2**31 - 1 en una plataforma de 32 bits y 2** 63 - 1 en una plataforma de 64 bits.

sys.maxunicode

Un número entero que da el valor del punto de código Unicode más grande, es decir, 1114111 (0x10FFFF en hexadecimal).

Distinto en la versión 3.3: Antes PEP 393 [https://www.python.org/dev/peps/pep-0393], sys.maxunicode solía ser 0xFFFF o 0x10FFFF, dependiendo de la opción de configuración que especificaba si los caracteres Unicode se almacenaban como UCS-2 o UCS-4.

sys.meta_path

Una lista de objetos meta path finder que tienen sus métodos find_spec() llamados para ver si uno de los objetos puede encontrar el módulo que se va a importar. Se llama al método find_spec() con al menos el nombre absoluto del módulo que se está importando. Si el módulo que se va a importar está contenido en un paquete, el atributo del paquete principal __path__ se pasa como segundo argumento. El método retorna module spec, o None si no se puede encontrar el módulo.

Ver también

importlib.abc.MetaPathFinder

La clase base abstracta que define la interfaz de los objetos del buscador en meta_path.

importlib.machinery.ModuleSpec

La clase concreta que find_spec() debería retornar instancias de.

Distinto en la versión 3.4: Especificaciones del módulo se introdujeron en Python 3.4, por PEP 451 [https://www.python.org/dev/peps/pep-0451]. Las versiones anteriores de Python buscaban un método llamado find_module(). Esto todavía se llama como una alternativa si una entrada meta_path no tiene un método find_spec().

sys.modules

Este es un diccionario que asigna los nombres de los módulos a los módulos que ya se han cargado. Esto se puede manipular para forzar la recarga de módulos y otros trucos. Sin embargo, reemplazar el diccionario no necesariamente funcionará como se esperaba y eliminar elementos esenciales del diccionario puede hacer que Python falle.

sys.path

Una lista de cadenas de caracteres que especifica la ruta de búsqueda de módulos. Inicializado desde la variable de entorno PYTHONPATH, más un valor predeterminado que depende de la instalación.

Como se inicializó al iniciar el programa, el primer elemento de esta lista, path[0], es el directorio que contiene el script que se utilizó para invocar al intérprete de Python. Si el directorio de la secuencia de comandos no está disponible (por ejemplo, si el intérprete se invoca de forma interactiva o si la secuencia de comandos se lee desde la entrada estándar), path[0] es la cadena de caracteres vacía, que dirige a Python a buscar módulos en el directorio actual primero. Observe que el directorio del script se inserta antes de las entradas insertadas como resultado de PYTHONPATH.

Un programa es libre de modificar esta lista para sus propios fines. Solo se deben agregar cadenas de caracteres y bytes a sys.path; todos los demás tipos de datos se ignoran durante la importación.

Ver también

Módulo site Esto describe cómo usar archivos .pth para extender sys.path.

sys.path_hooks

Una lista de invocables que toman un argumento de ruta para intentar crear un finder para la ruta. Si se puede crear un buscador, el invocable debe retornar; de lo contrario, lanza ImportError.

Especificado originalmente en PEP 302 [https://www.python.org/dev/peps/pep-0302].

sys.path_importer_cache

Un diccionario que actúa como caché para objetos finder. Las claves son rutas que se han pasado a sys.path_hooks y los valores son los buscadores que se encuentran. Si una ruta es una ruta de sistema de archivos válida pero no se encuentra ningún buscador en sys.path_hooks, entonces se almacena None.

Especificado originalmente en PEP 302 [https://www.python.org/dev/peps/pep-0302].

Distinto en la versión 3.3: None se almacena en lugar de imp.NullImporter cuando no se encuentra ningún buscador.

sys.platform

Esta cadena de caracteres contiene un identificador de plataforma que se puede usar para agregar componentes específicos de la plataforma a sys.path, por ejemplo.

Para los sistemas Unix, excepto en Linux y AIX, este es el nombre del sistema operativo en minúsculas como lo retorna uname -s con la primera parte de la versión retornada por uname -r adjunta, por ejemplo 'sunos5' o 'freebsd8', en el momento en que se construyó Python. A menos que desee probar una versión específica del sistema, se recomienda utilizar el siguiente idioma:

if sys.platform.startswith('freebsd'):
    # FreeBSD-specific code here...
elif sys.platform.startswith('linux'):
    # Linux-specific code here...
elif sys.platform.startswith('aix'):
    # AIX-specific code here...

Para otros sistemas, los valores son:

Sistema

valor platform

AIX

'aix'

Linux

'linux'

Windows

'win32'

Windows/Cygwin

'cygwin'

macOS

'darwin'

Distinto en la versión 3.3: En Linux, sys.platform ya no contiene la versión principal. Siempre es 'linux', en lugar de 'linux2' o 'linux3'. Dado que las versiones anteriores de Python incluyen el número de versión, se recomienda utilizar siempre el idioma startswith presentado anteriormente.

Distinto en la versión 3.8: En AIX, sys.platform ya no contiene la versión principal. Siempre es 'aix', en lugar de 'aix5' o 'aix7'. Dado que las versiones anteriores de Python incluyen el número de versión, se recomienda utilizar siempre el idioma startswith presentado anteriormente.

Ver también

os.name tiene una granularidad más gruesa. os.uname() proporciona información de versión dependiente del sistema.

El módulo platform proporciona comprobaciones detalladas de la identidad del sistema.

sys.platlibdir

Nombre del directorio de la biblioteca específica de la plataforma. Se utiliza para construir la ruta de la biblioteca estándar y las rutas de los módulos de extensión instalados.

Es igual a "lib" en la mayoría de las plataformas. En Fedora y SuSE, es igual a "lib64" en plataformas de 64 bits, lo que da las siguientes rutas sys.path (donde X.Y es la versión mayor.menor de Python):

/usr/lib64/pythonX.Y/: Biblioteca estándar (como os.py del módulo os)

/usr/lib64/pythonX.Y/lib-dynload/: Módulos de extensión C de la biblioteca estándar (como el módulo errno, el nombre exacto del archivo es específico de la plataforma)

/usr/lib/pythonX.Y/site-packages/ (utilice siempre lib, no sys.platlibdir): Módulos de terceros

/usr/lib64/pythonX.Y/site-packages/: Módulos de extensión C de paquetes de terceros

Nuevo en la versión 3.9.

sys.prefix

A string giving the site-specific directory prefix where the platform independent Python files are installed; on Unix, the default is '/usr/local'. This can be set at build time with the --prefix argument to the configure script. See Rutas de instalación for derived paths.

Nota

Si un virtual environment está en efecto, este valor se cambiará en site.py para apuntar al entorno virtual. El valor para la instalación de Python seguirá estando disponible a través de base_prefix.

sys.ps1

sys.ps2

Cadenas de caracteres que especifican el indicador principal y secundario del intérprete. Estos solo se definen si el intérprete está en modo interactivo. Sus valores iniciales en este caso son '>>>' y '...'. Si se asigna un objeto que no es una cadena a cualquiera de las variables, su str() se vuelve a evaluar cada vez que el intérprete se prepara para leer un nuevo comando interactivo; esto se puede utilizar para implementar un mensaje dinámico.

sys.setdlopenflags(n)

Establece los indicadores utilizados por el intérprete para llamadas dlopen(), como cuando el intérprete carga módulos de extensión. Entre otras cosas, esto permitirá una resolución diferida de símbolos al importar un módulo, si se llama como sys.setdlopenflags(0). Para compartir símbolos entre módulos de extensión, llame como sys.setdlopenflags(os.RTLD_GLOBAL). Los nombres simbólicos para los valores de las banderas se pueden encontrar en el módulo os (constantes RTLD_xxx, por ejemplo os.RTLD_LAZY).

Disponibilidad: Unix.

sys.set_int_max_str_digits(n)

Set the integer string conversion length limitation used by this interpreter. See also get_int_max_str_digits().

Nuevo en la versión 3.9.14.

sys.setprofile(profilefunc)

Configura la función de perfil del sistema, que le permite implementar un generador de perfiles de código fuente de Python en Python. Consulte el capítulo Los perfiladores de Python para obtener más información sobre el generador de perfiles de Python. La función de perfil del sistema se llama de manera similar a la función de seguimiento del sistema (ver settrace()), pero se llama con diferentes eventos, por ejemplo, no se llama para cada línea de código ejecutada (solo al llamar y regresar, pero el evento de retorno se informa incluso cuando se ha establecido una excepción). La función es específica de subprocesos, pero el generador de perfiles no tiene forma de conocer los cambios de contexto entre subprocesos, por lo que no tiene sentido usar esto en presencia de varios subprocesos. Además, su valor de retorno no se usa, por lo que simplemente puede retornar None. Un error en la función del perfil provocará su desarmado.

Las funciones de perfil deben tener tres argumentos: frame, event y arg. frame es el marco de pila actual. event es una cadena de caracteres: 'call', 'return', 'c_call', 'c_return', o 'c_exception'. arg depende del tipo de evento.

Lanza un auditing event sys.setprofile sin argumentos.

Los eventos tienen el siguiente significado:

'call'

Se llama a una función (o se ingresa algún otro bloque de código). Se llama a la función de perfil; arg es None.

'return'

Una función (u otro bloque de código) está a punto de regresar. Se llama a la función de perfil; arg es el valor que se retornará, o None si el evento es causado por una excepción.

'c_call'

Una función C está a punto de ser llamada. Esta puede ser una función de extensión o una incorporada. arg es el objeto de función de C.

'c_return'

Ha vuelto una función C. arg es el objeto de función de C.

'c_exception'

Una función C ha generado una excepción. arg es el objeto de función de C.

sys.setrecursionlimit(limit)

Establece la profundidad máxima de la pila de intérpretes de Python en limit. Este límite evita que la recursividad infinita cause un desbordamiento de la pila C y bloquee Python.

El límite más alto posible depende de la plataforma. Un usuario puede necesitar establecer un límite más alto cuando tiene un programa que requiere una recursividad profunda y una plataforma que admite un límite más alto. Esto debe hacerse con cuidado, ya que un límite demasiado alto puede provocar un accidente.

Si el nuevo límite es demasiado bajo en la profundidad de recursividad actual, se genera una excepción RecursionError.

Distinto en la versión 3.5.1: A la excepción RecursionError ahora se lanza si el nuevo límite es demasiado bajo en la profundidad de recursión actual.

sys.setswitchinterval(interval)

Establece el intervalo de cambio de hilo del intérprete (en segundos). Este valor de punto flotante determina la duración ideal de los «segmentos de tiempo» asignados a los subprocesos de Python que se ejecutan simultáneamente. Tenga en cuenta que el valor real puede ser mayor, especialmente si se utilizan funciones o métodos internos de larga duración. Además, qué hilo se programa al final del intervalo es decisión del sistema operativo. El intérprete no tiene su propio programador.

Nuevo en la versión 3.2.

sys.settrace(tracefunc)

Configura la función de seguimiento del sistema, que le permite implementar un depurador de código fuente de Python en Python. La función es específica del hilo; para que un depurador admita múltiples subprocesos, debe registrar una función de seguimiento usando settrace() para cada subproceso que se depura o use threading.settrace().

Las funciones de seguimiento deben tener tres argumentos: frame, event y arg. frame es el marco de pila actual. event es una cadena de caracteres: 'call', 'line', 'return', 'exception' or 'opcode'. arg depende del tipo de evento.

La función de rastreo se invoca (con event establecido en 'call') cada vez que se ingresa un nuevo ámbito local; debe retornar una referencia a una función de rastreo local que se usará para el nuevo alcance, o None si no se debe rastrear el alcance.

La función de seguimiento local debe retornar una referencia a sí misma (o a otra función para realizar un seguimiento adicional en ese ámbito), o None para desactivar el seguimiento en ese ámbito.

Si se produce algún error en la función de seguimiento, se desarmará, al igual que se llama a settrace(None).

Los eventos tienen el siguiente significado:

'call'

Se llama a una función (o se ingresa algún otro bloque de código). Se llama a la función de rastreo global; arg es None; el valor de retorno especifica la función de rastreo local.

'line'

El intérprete está a punto de ejecutar una nueva línea de código o volver a ejecutar la condición de un bucle. Se llama a la función de rastreo local; arg es None; el valor de retorno especifica la nueva función de rastreo local. Consulte Objects/lnotab_notes.txt para obtener una explicación detallada de cómo funciona. Los eventos por línea se pueden deshabilitar para un marco estableciendo f_trace_lines to False en ese marco.

'return'

Una función (u otro bloque de código) está a punto de regresar. Se llama a la función de rastreo local; arg es el valor que se retornará, o None si el evento es causado por una excepción. Se ignora el valor de retorno de la función de seguimiento.

'exception'

Ha ocurrido una excepción. Se llama a la función de rastreo local; arg es una tupla (exception, value, traceback); el valor de retorno especifica la nueva función de rastreo local.

'opcode'

El intérprete está a punto de ejecutar un nuevo código de operación (ver dis para detalles del código de operación). Se llama a la función de rastreo local; arg es None; el valor de retorno especifica la nueva función de rastreo local. Los eventos por código de operación no se emiten de forma predeterminada: deben solicitarse explícitamente configurando f_trace_opcodes en True en el marco.

Tenga en cuenta que como una excepción se propaga a lo largo de la cadena de llamadas de funciones, se lanza un evento de 'excepción' en cada nivel.

Para un uso más detallado, es posible establecer una función de seguimiento asignando frame.f_trace = tracefunc explícitamente, en lugar de confiar en que se establezca indirectamente a través del valor de retorno de una función de seguimiento ya instalada. Esto también es necesario para activar la función de seguimiento en el marco actual, lo cual settrace() no funciona. Tenga en cuenta que para que esto funcione, se debe haber instalado una función de rastreo global con settrace() para habilitar la maquinaria de rastreo en tiempo de ejecución, pero no necesita ser la misma función de rastreo (por ejemplo, podría ser una función de rastreo de sobrecarga baja que simplemente retorna None para deshabilitarse inmediatamente en cada cuadro).

Para obtener más información sobre los objetos de código y marco, consulte Jerarquía de tipos estándar.

Lanza un auditing event sys.settrace sin argumentos.

CPython implementation detail: La función settrace() está pensada únicamente para implementar depuradores, perfiladores, herramientas de cobertura y similares. Su comportamiento es parte de la plataforma de implementación, en lugar de parte de la definición del lenguaje y, por lo tanto, es posible que no esté disponible en todas las implementaciones de Python.

Distinto en la versión 3.7: Se agregó el tipo de evento 'opcode'; atributos f_trace_lines y f_trace_opcodes agregados a los marcos (frames)

sys.set_asyncgen_hooks(firstiter, finalizer)

Acepta dos argumentos de palabras clave opcionales que son invocables que aceptan un asynchronous generator iterator como argumento. Se llamará al firstiter invocable cuando se repita un generador asincrónico por primera vez. Se llamará al finalizer cuando un generador asincrónico esté a punto de ser recolectado como basura.

Lanza un auditing event sys.set_asyncgen_hooks_firstiter sin argumentos.

Lanza un auditing event sys.set_asyncgen_hooks_finalizer sin argumentos.

Se lanzan dos eventos de auditoría porque la API subyacente consta de dos llamadas, cada una de las cuales debe generar su propio evento.

Nuevo en la versión 3.6: Ver PEP 525 [https://www.python.org/dev/peps/pep-0525] para más detalles, y para un ejemplo de referencia de un método finalizer ver la implementación de asyncio.Loop.shutdown_asyncgens en Lib/asyncio/base_events.py [https://github.com/python/cpython/tree/3.9/Lib/asyncio/base_events.py]

Nota

Esta función se ha añadido de forma provisional (consulte PEP 411 [https://www.python.org/dev/peps/pep-0411] para obtener más detalles).

sys.set_coroutine_origin_tracking_depth(depth)

Permite habilitar o deshabilitar el seguimiento de origen de rutina. Cuando está habilitado, el atributo cr_origin en los objetos de corrutina contendrá una tupla de (nombre de archivo, número de línea, nombre de función) tuplas que describen el rastreo donde se creó el objeto de corrutina, con la llamada más reciente primero. Cuando esté deshabilitado, cr_origin será None.

Para habilitarlo, pase un valor de depth mayor que cero; esto establece el número de fotogramas cuya información será capturada. Para deshabilitar, pase set depth a cero.

Esta configuración es específica de cada hilo.

Nuevo en la versión 3.7.

Nota

Esta función se ha añadido de forma provisional (consulte PEP 411 [https://www.python.org/dev/peps/pep-0411] para obtener más detalles). Úsela sólo para fines de depuración.

sys._enablelegacywindowsfsencoding()

Cambia la codificación predeterminada del sistema de archivos y el modo de errores a “mbcs” y “replace” respectivamente, para mantener la coherencia con las versiones de Python anteriores a la 3.6.

Esto es equivalente a definir la variable de entorno PYTHONLEGACYWINDOWSFSENCODING antes de iniciar Python.

Disponibilidad: Windows.

Nuevo en la versión 3.6: Consulte PEP 529 [https://www.python.org/dev/peps/pep-0529] para obtener más detalles.

sys.stdin

sys.stdout

sys.stderr

Objetos de archivo utilizado por el intérprete para entradas, salidas y errores estándar:

stdin se usa para todas las entradas interactivas (incluidas las llamadas a input());

stdout se usa para la salida de print() y expression y para las solicitudes de input();

Las propias indicaciones del intérprete y sus mensajes de error van a stderr.

Estos flujos son regulares archivos de texto como los retornados por la función open(). Sus parámetros se eligen de la siguiente manera:

La codificación de caracteres depende de la plataforma. Las plataformas que no son de Windows utilizan la codificación local (consulte locale.getpreferredencoding()).

En Windows, se usa UTF-8 para el dispositivo de consola. Los dispositivos que no son caracteres, como archivos de disco y tuberías, utilizan la codificación de la configuración regional del sistema (es decir, la página de códigos ANSI). Los dispositivos de caracteres que no son de consola, como NUL (es decir, donde isatty() retorna True) utilizan el valor de las páginas de códigos de entrada y salida de la consola al inicio, respectivamente para stdin y stdout/stderr. Este valor predeterminado es la codificación de la configuración regional del sistema si el proceso no se adjunta inicialmente a una consola.

El comportamiento especial de la consola se puede anular configurando la variable de entorno PYTHONLEGACYWINDOWSSTDIO antes de iniciar Python. En ese caso, las páginas de códigos de la consola se utilizan como para cualquier otro dispositivo de caracteres.

En todas las plataformas, puede anular la codificación de caracteres configurando la variable de entorno PYTHONIOENCODING antes de iniciar Python o usando la nueva -X utf8 opción de línea de comando y PYTHONUTF8 variable de entorno. Sin embargo, para la consola de Windows, esto solo se aplica cuando PYTHONLEGACYWINDOWSSTDIO también está configurado.

Cuando es interactivo, el flujo de stdout se almacena en búfer de línea. En caso contrario, se almacena en búfer de bloque como los archivos de texto normales. El flujo stderr tiene un búfer de línea en ambos casos. Puede hacer que ambos flujos no tengan búfer pasando la opción de línea de comandos -u o estableciendo la variable de entorno PYTHONUNBUFFERED.

Distinto en la versión 3.9: Ahora, stderr no interactivo tiene búfer de línea en lugar de búfer completo.

Nota

Para escribir o leer datos binarios desde/hacia los flujos estándar, use el objeto binario subyacente buffer. Por ejemplo, para escribir bytes en stdout, use sys.stdout.buffer.write(b'abc').

Sin embargo, si está escribiendo una biblioteca (y no controla en qué contexto se ejecutará su código), tenga en cuenta que las transmisiones estándar pueden reemplazarse con objetos similares a archivos como io.StringIO que no admiten el atributo buffer.

sys.__stdin__

sys.__stdout__

sys.__stderr__

Estos objetos contienen los valores originales de stdin, stderr y stdout al inicio del programa. Se utilizan durante la finalización y podrían ser útiles para imprimir en el flujo estándar real sin importar si el objeto sys.std* ha sido redirigido.

También se puede utilizar para restaurar los archivos reales a objetos de archivo de trabajo conocidos en caso de que se hayan sobrescrito con un objeto roto. Sin embargo, la forma preferida de hacer esto es guardar explícitamente la secuencia anterior antes de reemplazarla y restaurar el objeto guardado.

Nota

En algunas condiciones, stdin, stdout y stderr, así como los valores originales __stdin__, __stdout__ y __stderr__ pueden ser None . Suele ser el caso de las aplicaciones GUI de Windows que no están conectadas a una consola y las aplicaciones Python que comienzan con pythonw.

sys.thread_info

Un named tuple que contiene información sobre la implementación del hilo.

Atributo

Explicación

name

Nombre de la implementación de hilos (thread implementation):

'nt': hilos de Windows

'pthread': hilos de POSIX

'solaris': hilos de Solaris

lock

Nombre de la implementación de bloqueo (lock implementation):

'semaphore': un bloqueo que utiliza un semáforo

'mutex+cond': un bloqueo que utiliza un mutex y una variable de condición

None si esta información es desconocida

version

Nombre y versión de la biblioteca de subprocesos. Es una cadena de caracteres, o None si se desconoce esta información.

Nuevo en la versión 3.3.

sys.tracebacklimit

Cuando esta variable se establece en un valor entero, determina el número máximo de niveles de información de rastreo que se imprime cuando ocurre una excepción no controlada. El valor predeterminado es 1000. Cuando se establece en 0 o menos, toda la información de rastreo se suprime y solo se imprimen el tipo y el valor de excepción.

sys.unraisablehook(unraisable, /)

Maneja una excepción que no se puede lanzar.

Se llama cuando se ha producido una excepción pero no hay forma de que Python la maneje. Por ejemplo, cuando un destructor lanza una excepción o durante la recolección de basura (gc.collect()).

El argumento unraisable tiene los siguientes atributos:

exc_type: Tipo de excepción.

exc_value: Valor de excepción, puede ser None.

exc_traceback: Rastreo de excepción, puede ser None.

err_msg: Mensaje de error, puede ser None.

objeto: Objeto que causa la excepción, puede ser None.

Los formatos de gancho predeterminados err_msg y object como: f'{err_msg}:{object!R}'; use el mensaje de error «Excepción ignorada en» si err_msg es None.

sys.unraisablehook() se puede anular para controlar cómo se manejan las excepciones que no se pueden evaluar.

Almacenar exc_value usando un gancho personalizado puede crear un ciclo de referencia. Debe borrarse explícitamente para romper el ciclo de referencia cuando la excepción ya no sea necesaria.

Almacenar object usando un gancho personalizado puede resucitarlo si se establece en un objeto que se está finalizando. Evite almacenar object después de que se complete el gancho personalizado para evitar resucitar objetos.

Véase también excepthook() que maneja excepciones no capturadas.

Lanza un evento de auditoría sys.unraisablehook con argumentos hook, unraisable cuando ocurre una excepción que no se puede manejar. El objeto no lanzable es el mismo que se pasará al gancho. Si no se ha colocado ningún gancho, hook puede ser None.

Nuevo en la versión 3.8.

sys.version

Una cadena de caracteres que contiene el número de versión del intérprete de Python más información adicional sobre el número de compilación y el compilador utilizado. Esta cadena se muestra cuando se inicia el intérprete interactivo. No extraiga información de la versión de él, en su lugar, use version_info y las funciones proporcionadas por el módulo platform.

sys.api_version

La versión de API C para este intérprete. Los programadores pueden encontrar esto útil al depurar conflictos de versiones entre Python y módulos de extensión.

sys.version_info

Una tupla que contiene los cinco componentes del número de versión: major, minor, micro, releaselevel, y serial. Todos los valores excepto releaselevel son números enteros; el nivel de lanzamiento es 'alpha', 'beta', 'candidate', o 'final'. El valor de version_info correspondiente a la versión 2.0 de Python es (2, 0, 0, 'final', 0). También se puede acceder a los componentes por su nombre, por lo que sys.version_info[0] es equivalente a sys.version_info.major y así sucesivamente.

Distinto en la versión 3.1: Se agregaron atributos de componentes con nombre.

sys.warnoptions

Este es un detalle de implementación del marco de advertencias; No modifique este valor. Consulte el módulo warnings para obtener más información sobre el marco de advertencias.

sys.winver

El número de versión utilizado para formar claves de registro en plataformas Windows. Esto se almacena como recurso de cadena 1000 en la DLL de Python. El valor son normalmente los primeros tres caracteres de version. Se proporciona en el módulo sys con fines informativos; la modificación de este valor no tiene ningún efecto sobre las claves de registro que utiliza Python.

Disponibilidad: Windows.

sys._xoptions

Un diccionario de las diversas flags específicas de la implementación pasa a través de la opción de línea de comandos -X. Los nombres de las opciones se asignan a sus valores, si se dan explícitamente, o a True. Ejemplo:

$ ./python -Xa=b -Xc
Python 3.2a3+ (py3k, Oct 16 2010, 20:14:50)
[GCC 4.4.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys._xoptions
{'a': 'b', 'c': True}

CPython implementation detail: Esta es una forma específica de CPython de acceder a las opciones que se pasan a través de -X. Otras implementaciones pueden exportarlos a través de otros medios, o no exportarlos.

Nuevo en la versión 3.2.

Citas

C99

ISO/IEC 9899:1999. «Programming languages – C.» A public draft of this standard is available at http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf.

sysconfig — Proporciona acceso a la información de configuración de Python

Nuevo en la versión 3.2.

Código fuente: Lib/sysconfig.py [https://github.com/python/cpython/tree/3.9/Lib/sysconfig.py]

El módulo sysconfig proporcionado acceso a la información de configuración de Python, como la lista de rutas de instalación y las variables de configuración relevantes para la plataforma actual.

Variables de configuración

Una distribución de Python contiene un Makefile y un archivo de cabecera pyconfig.h que son necesarios para construir tanto el propio binario de Python como las extensiones C de terceros compiladas usando distutils.

sysconfig coloca todas las variables que se encuentran en estos archivos un diccionario al que se puede acceder usando get_config_vars() o get_config_var().

Tenga en cuenta que en Windows, es un conjunto mucho más pequeño.

sysconfig.get_config_vars(*args)

Sin argumentos, retorna un diccionario de todas las variables de configuración relevantes para la plataforma actual.

Con argumentos, retorna un lista de valores que resultan de buscar cada argumento en el diccionario de variables de configuración.

Por cada argumento, si no se encuentra el valor, retorna None.

sysconfig.get_config_var(name)

Retorna el valor de un solo nombre de variable (name). Equivalente a get_config_vars().get(name).

Si no se encuentra name, retorna None.

Ejemplos de uso:

>>> import sysconfig
>>> sysconfig.get_config_var('Py_ENABLE_SHARED')
0
>>> sysconfig.get_config_var('LIBDIR')
'/usr/local/lib'
>>> sysconfig.get_config_vars('AR', 'CXX')
['ar', 'g++']

Rutas de instalación

Python usa un esquema de instalación que difiere según la plataforma y en las opciones de instalación. Estos esquemas son almacenados en sysconfig con identificadores únicos basados en el valor retornado por os.name.

Cada nuevo componente que se instala usando distutils o un sistema basado en Distutils seguirá el mismo esquema para copiar su archivo en los lugares correctos.

Python currently supports six schemes:

posix_prefix: scheme for POSIX platforms like Linux or macOS. This is the default scheme used when Python or a component is installed.

posix_home: esquema para plataformas POSIX usado cuando se usa una opción home en la instalación. Este esquema se usa cuando se instala un componente a través de Disutils con un prefijo de inicio específico.

posix_user: esquema para plataformas POSIX usado cuando se instala un componente a través de Distutils y se usa la opción user. Este esquema define rutas ubicadas bajo el directorio de inicio del usuario.

nt: esquema para plataformas NT como Windows.

nt_user: esquema para plataformas NT, cuando se usa la opción user.

osx_framework_user: scheme for macOS, when the user option is used.

Cada esquema está compuesto por una serie de rutas y cada ruta tiene un identificador único. Python actualmente usa ocho rutas:

stdlib: directorio que contiene los archivos de la biblioteca estándar de Python que no son específicos de la plataforma.

platstdlib: directorio que contiene los archivos de la biblioteca estándar de Python que son específicos de la plataforma.

platlib: directorio para archivos específicos del sitio, específicos de la plataforma.

purelib: directorio para archivos específicos del sitio, no específicos de la plataforma.

include: directorio para archivos de encabezado no específicos de plataforma.

platinclude: directorio para archivos de encabezado específicos de la plataforma.

scripts: directorio para archivos de script.

data: directorio para archivos de datos.

sysconfig proporciona algunas funciones para determinar estas rutas.

sysconfig.get_scheme_names()

Retorna una tupla que contiene todos los esquemas admitidos actualmente en sysconfig.

sysconfig.get_path_names()

Retorna una tupla que contiene todo los nombres de rutas admitidos actualmente en sysconfig.

sysconfig.get_path(name[, scheme[, vars[, expand]]])

Retorna una ruta de instalación correspondiente a la ruta name, del esquema de instalación denominado scheme.

name tiene que ser un valor de la lista retornado por get_path_names().

sysconfig almacena las rutas de instalación correspondientes a cada nombre de ruta, para cada plataforma, con variables que se expandirán. Por ejemplo, la ruta stdlib para el esquema nt es: {base}/Lib.

get_path() utilizará las variables retornadas por get_config_vars() para expandir la ruta. Todas las variables tienen valores predeterminados para cada plataforma, por lo que se puede llamar a esta función y obtener el valor predeterminado.

Si se proporciona el esquema (scheme), debe ser un valor de la lista retornada por get_scheme_names(). De lo contrario, se utiliza el esquema predeterminado para la plataforma actual.

Si se proporciona vars, debe ser un diccionario de variables que actualizará el retorno del diccionario mediante get_config_vars().

Si expand se establece en False, la ruta no se expandirá usando las variables.

If name is not found, raise a KeyError.

sysconfig.get_paths([scheme[, vars[, expand]]])

Retorna un diccionario de contiene todas las rutas de instalación correspondientes a un esquema de instalación. Consulte get_path() para obtener más información.

Si no se proporciona el esquema (scheme), utilizará el esquema predeterminado para la plataforma actual.

Si se proporciona vars, debe ser un diccionario de variables que actualizará el diccionario utilizado para expandir las rutas.

Si expand se establece en falso, las rutas no se expandirán.

Si scheme no es un esquema existente, get_paths() lanzará un KeyError.

Otras funciones

sysconfig.get_python_version()

Retorna el número de versión versión MAJOR.MINOR de Python como una cadena. Similar a '%d.%d' % sys.version_info[:2].

sysconfig.get_platform()

Retorna una cadena que identifica la plataforma actual.

Se utiliza principalmente para distinguir los directorios de compilación específicos de la plataforma y las distribuciones compiladas específicas de la plataforma. Por lo general se incluye el nombre y la versión del sistema operativo y la arquitectura (como lo proporciona “os.uname()”), aunque la información exacta incluida depende del sistema operativo: por ejemplo, en Linux, la versión del kernel no es particularmente importante.

Ejemplo de valores retornados:

linux-i586

linux-alpha (?)

solaris-2.6-sun4u

Windows retornará uno de:

win-amd64 (Windows de 64 bits en AMD64, también conocido como x86_64, Intel64 y EM64T)

win32 (todos los demás - específicamente se retorna sys.platform)

macOS can return:

macosx-10.6-ppc

macosx-10.4-ppc64

macosx-10.3-i386

macosx-10.4-fat

Para otras plataformas que no son POSIX, actualmente solo retorna sys.platform.

sysconfig.is_python_build()

Retorna True si el intérprete de Python en ejecución se compiló a partir de la fuente y se está ejecutando desde su ubicación compilada, y no desde una ubicación resultante de por ejemplo ejecutando make install o instalando a través de un instalador binario.

sysconfig.parse_config_h(fp[, vars])

Analiza un archivo de estilo config.h.

fp es un objeto similar a un archivo que apunta al archivo similar a config.h.

Se retorna un diccionario que contiene pares de nombre/valor. Si se pasa un diccionario opcional como un segundo argumento, se utiliza en lugar de un nuevo diccionario y se actualiza con los valores leídos en el archivo.

sysconfig.get_config_h_filename()

Retorna la ruta de pyconfig.h.

sysconfig.get_makefile_filename()

Retorna la ruta de Makefile.

Usando sysconfig como un script

Puedes usar sysconfig como un script con la opción -m de Python:

$ python -m sysconfig
Platform: "macosx-10.4-i386"
Python version: "3.2"
Current installation scheme: "posix_prefix"

Paths:
        data = "/usr/local"
        include = "/Users/tarek/Dev/svn.python.org/py3k/Include"
        platinclude = "."
        platlib = "/usr/local/lib/python3.2/site-packages"
        platstdlib = "/usr/local/lib/python3.2"
        purelib = "/usr/local/lib/python3.2/site-packages"
        scripts = "/usr/local/bin"
        stdlib = "/usr/local/lib/python3.2"

Variables:
        AC_APPLE_UNIVERSAL_BUILD = "0"
        AIX_GENUINE_CPLUSPLUS = "0"
        AR = "ar"
        ARFLAGS = "rc"
        ...

Esta llamada imprimirá en la salida estándar la información retornada por get_platform(), get_python_version(), get_path() y get_config_vars().

builtins — Objetos incorporados

Este módulo proporciona acceso directo a todos los identificadores “incorporados” de Python. Por ejemplo, builtins.open es el nombre completo de la función incorporada open(). Vea Funciones Built-in y Constantes incorporadas para documentación.

Este módulo normalmente no es accedido explícitamente por la mayoría de las aplicaciones, pero puede ser útil en módulos que provean objetos con el mismo nombre que un valor incorporado, pero que sea necesario también el incorporado con ese nombre. Por ejemplo, en un módulo que quiera implementar una función open() que envuelva la integrada open(), este módulo puede se usado directamente:

import builtins

def open(path):
    f = builtins.open(path, 'r')
    return UpperCaser(f)

class UpperCaser:
    '''Wrapper around a file that converts output to upper-case.'''

    def __init__(self, f):
        self._f = f

    def read(self, count=-1):
        return self._f.read(count).upper()

    # ...

Como un detalle de implementación, la mayoría de los módulos tienen el nombre __builtins__ disponible como parte de sus globales. El valor de __builtins__ es normalmente o este módulo o el valor del atributo __dict__ de este módulo. Como este es un detalle de implementación, puede que no sea usado por implementaciones alternativas de Python.

__main__ — Entorno de script del nivel superior

'__main__' es el nombre del ámbito en el que se ejecuta el código de nivel superior. El atributo __name__ de un módulo se establece igual a '__main__' cuando se lee desde una entrada estándar, un script o un prompt interactivo.

Un módulo puede descubrir si se está ejecutando o no en el ámbito principal al verificar su propio __name__, lo cual permite un idioma común para ejecutar código condicionalmente en un modulo cuando este se ejecuta como un script o con python -m pero no cuando este es importado:

if __name__ == "__main__":
    # execute only if run as a script
    main()

Para un paquete, se puede lograr el mismo efecto incluyendo un modulo __main__.py, cuyo contenido se ejecutara cuando el modulo se ejecute con -m.

warnings — Control de advertencias

Código fuente: Lib/warnings.py [https://github.com/python/cpython/tree/3.9/Lib/warnings.py]

Los mensajes de advertencia suelen emitirse en situaciones en las que es útil alertar al usuario de alguna condición en un programa, cuando esa condición (normalmente) no justifica que se haga una excepción y se termine el programa. Por ejemplo, se puede emitir una advertencia cuando un programa utiliza un módulo obsoleto.

Los programadores de Python emiten advertencias llamando a la función warn() definida en este módulo. (Los programadores de C usan PyErr_WarnEx(); ver Manejo de excepciones para más detalles)

Los mensajes de advertencia se escriben normalmente en sys.stderr, pero su disposición puede cambiarse de manera flexible, desde ignorar todas las advertencias hasta convertirlas en excepciones. La disposición de las advertencias puede variar en función de la warning category, el texto del mensaje de advertencia y la ubicación de la fuente donde se emite. Las repeticiones de una advertencia particular para la misma ubicación de la fuente son típicamente suprimidas.

El control de las advertencias consta de dos etapas: en primer lugar, cada vez que se emite una advertencia, se determina si se debe emitir un mensaje o no; en segundo lugar, si se debe emitir un mensaje, se le da formato y se imprime utilizando un gancho establecido por el usuario.

La determinación de si se debe emitir un mensaje de advertencia está controlada por el warning filter, que es una secuencia de reglas y acciones que coinciden. Se pueden añadir reglas al filtro llamando a filterwarnings() y restablecer su estado por defecto llamando a resetwarnings().

La impresión de los mensajes de advertencia se realiza llamando a showwarning(), que puede ser anulado; la implementación por defecto de esta función da formato al mensaje llamando a formatwarning(), que también está disponible para su uso en implementaciones personalizadas.

Ver también

logging.captureWarnings() permite manejar todas las advertencias con la infraestructura de registro estándar.

Categorías de advertencia

Hay una serie de excepciones incorporadas que representan categorías de advertencia. Esta categorización es útil para poder filtrar grupos de advertencias.

Aunque técnicamente se trata de built-in exceptions, están documentadas aquí, porque pertenecen al mecanismo de advertencias.

El código de usuario puede definir categorías de advertencia adicionales mediante la subclasificación de una de las categorías de advertencia estándar. Una categoría de advertencia siempre debe ser una subclase de la clase Warning class.

Actualmente están definidas las siguientes clases de categorías de advertencias:

Clase

Descripción

Warning

Esta es la clase principal para todas las clases que pertenecen a la categoría de advertencia. Es una subclase de Exception.

UserWarning

La categoría por defecto para warn().

DeprecationWarning

Categoría principal para advertencias sobre características obsoletas cuando esas advertencias están destinadas a otros desarrolladores de Python (ignoradas por defecto, a menos que sean activadas por el código en __main__).

SyntaxWarning

Categoría principal para las advertencias sobre características sintácticas dudosas.

RuntimeWarning

Categoría principal para las advertencias sobre características dudosas de tiempo de ejecución.

FutureWarning

Categoría principal para las advertencias sobre características obsoletas cuando esas advertencias están destinadas a los usuarios finales de aplicaciones escritas en Python.

PendingDeprecationWarning

Categoría principal para las advertencias sobre las características que serán desaprobadas en el futuro (ignoradas por defecto).

ImportWarning

Categoría principal para las advertencias que se activan durante el proceso de importación de un módulo (se ignoran por defecto).

UnicodeWarning

Categoría principal para las advertencias relacionadas con Unicode.

BytesWarning

Categoría principal para las advertencias relacionadas con bytes y bytearray.

ResourceWarning

Base category for warnings related to resource usage (ignored by default).

Distinto en la versión 3.7: Anteriormente DeprecationWarning y FutureWarning se distinguían en función de si una característica se eliminaba por completo o se cambiaba su comportamiento. Ahora se distinguen en función de su público objetivo y de la forma en que son manejados por los filtros de advertencia predeterminados.

El filtro de advertencias

El filtro de advertencias controla si las advertencias se ignoran, se muestran o se convierten en errores (planteando una excepción).

Conceptualmente, el filtro de advertencias mantiene una lista ordenada de especificaciones de filtros; cualquier advertencia específica se compara con cada especificación de filtro de la lista por turno hasta que se encuentra una coincidencia; el filtro determina la disposición de la coincidencia. Cada entrada es una tupla de la forma (action, message, category, module, lineno), donde:

action es una de las siguientes cadenas:

Valor

Disposición

"default"

imprime la primera ocurrencia de advertencias coincidentes para cada lugar (módulo + número de línea) donde se emite la advertencia

"error"

convertir las advertencias de coincidencia en excepciones

"ignore"

nunca imprime advertencias que coincidan

"always"

siempre imprime advertencias que coinciden

"module"

imprime la primera ocurrencia de advertencias coincidentes para cada módulo en el que se emite la advertencia (independientemente del número de línea)

"once"

imprime sólo la primera aparición de advertencias coincidentes, independientemente de la ubicación

message es una cadena que contiene una expresión regular que el inicio del mensaje de advertencia debe coincidir. La expresión está compilada para que siempre sea insensible a las mayúsculas y minúsculas.

category es una clase (una subclase de Warning) de la cual la categoría de advertencia debe ser una subclase para poder coincidir.

module es una cadena que contiene una expresión regular que el nombre del módulo debe coincidir. La expresión se compila para que distinga entre mayúsculas y minúsculas.

lineno es un número entero que el número de línea donde ocurrió la advertencia debe coincidir, o 0 para coincidir con todos los números de línea.

Como la clase Warning se deriva de la clase Excepción incorporada, para convertir una advertencia en un error simplemente elevamos la category(message).

Si se informa de una advertencia y no coincide con ningún filtro registrado, se aplica la acción «por defecto» (de ahí su nombre).

Descripción de los filtros de advertencia

El filtro de advertencias se inicializa con -W options pasado a la línea de comandos del intérprete de Python y la variable de entorno PYTHONWARNINGS. El intérprete guarda los argumentos de todas las entradas suministradas sin interpretación en sys.warnoptions; el módulo warnings los analiza cuando se importa por primera vez (las opciones no válidas se ignoran, después de imprimir un mensaje a sys.stderr).

Los filtros de advertencia individuales se especifican como una secuencia de campos separados por dos puntos:

action:message:category:module:line

El significado de cada uno de estos campos es como se describe en El filtro de advertencias. Cuando se enumeran varios filtros en una sola línea (como en PYTHONWARNINGS), los filtros individuales se separan por comas y los filtros que se enumeran más tarde tienen prioridad sobre los que se enumeran antes de ellos (ya que se aplican de izquierda a derecha, y los filtros aplicados más recientemente tienen prioridad sobre los anteriores).

Los filtros de advertencia comúnmente utilizados se aplican a todas las advertencias, a las advertencias de una categoría particular o a las advertencias planteadas por módulos o paquetes particulares. Algunos ejemplos:

default                      # Show all warnings (even those ignored by default)
ignore                       # Ignore all warnings
error                        # Convert all warnings to errors
error::ResourceWarning       # Treat ResourceWarning messages as errors
default::DeprecationWarning  # Show DeprecationWarning messages
ignore,default:::mymodule    # Only report warnings triggered by "mymodule"
error:::mymodule[.*]         # Convert warnings to errors in "mymodule"
                             # and any subpackages of "mymodule"

Filtro de advertencia predeterminado

Por defecto, Python instala varios filtros de advertencia, que pueden ser anulados por la opción de línea de comandos -W, la variable de entorno PYTHONWARNINGS y llamadas a filterwarnings().

En versiones regulares, el filtro de advertencia por defecto tiene las siguientes entradas (en orden de precedencia):

default::DeprecationWarning:__main__
ignore::DeprecationWarning
ignore::PendingDeprecationWarning
ignore::ImportWarning
ignore::ResourceWarning

En versiones de depuración (debug builds), la lista de filtros de advertencia por defecto está vacía.

Distinto en la versión 3.2: DeprecationWarning es ahora ignorado por defecto además de PendingDeprecationWarning.

Distinto en la versión 3.7: DeprecationWarning se muestra de nuevo por defecto cuando se activa directamente por código en __main__.

Distinto en la versión 3.7: BytesWarning ya no aparece en la lista de filtros por defecto y en su lugar se configura a través de sys.warnoptions cuando -b se especifica dos veces.

Anulando el filtro por defecto

Los desarrolladores de aplicaciones escritas en Python pueden desear ocultar todas las advertencias de nivel de Python a sus usuarios por defecto, y sólo mostrarlas cuando se realizan pruebas o se trabaja de otra manera en la aplicación. El atributo sys.warnoptions utilizado para pasar las configuraciones de los filtros al intérprete puede utilizarse como marcador para indicar si las advertencias deben ser desactivadas o no:

import sys

if not sys.warnoptions:
    import warnings
    warnings.simplefilter("ignore")

Se aconseja a los desarrolladores de pruebas de código Python que se aseguren de que todas las advertencias se muestren por defecto para el código que se está probando, usando un código como:

import sys

if not sys.warnoptions:
    import os, warnings
    warnings.simplefilter("default") # Change the filter in this process
    os.environ["PYTHONWARNINGS"] = "default" # Also affect subprocesses

Por último, se aconseja a los desarrolladores de shells interactivos que ejecuten el código de usuario en un espacio de nombres distinto de __main__ que se aseguren de que los mensajes DeprecationWarning se hagan visibles por defecto, utilizando un código como el siguiente (donde user_ns es el módulo utilizado para ejecutar el código introducido interactivamente):

import warnings
warnings.filterwarnings("default", category=DeprecationWarning,
                                   module=user_ns.get("__name__"))

Eliminación temporal de las advertencias

Si está utilizando un código que sabe que va a provocar una advertencia, como una función obsoleta, pero no quiere ver la advertencia (incluso cuando las advertencias se han configurado explícitamente a través de la línea de comandos), entonces es posible suprimir la advertencia utilizando el gestor de contexto catch_warnings:

import warnings

def fxn():
    warnings.warn("deprecated", DeprecationWarning)

with warnings.catch_warnings():
    warnings.simplefilter("ignore")
    fxn()

Mientras que dentro del gestor de contexto todas las advertencias serán simplemente ignoradas. Esto le permite utilizar el código conocido como obsoleto sin tener que ver la advertencia, mientras que no suprime la advertencia para otro código que podría no ser consciente de su uso de código obsoleto. Nota: esto sólo puede garantizarse en una aplicación de un solo hilo. Si dos o más hilos utilizan el gestor de contexto catch_warnings al mismo tiempo, el comportamiento es indefinido.

Advertencias de prueba

Para probar las advertencias planteadas por el código, use el administrador de contexto catch_warnings. Con él puedes mutar temporalmente el filtro de advertencias para facilitar tus pruebas. Por ejemplo, haz lo siguiente para capturar todas las advertencias levantadas para comprobar:

import warnings

def fxn():
    warnings.warn("deprecated", DeprecationWarning)

with warnings.catch_warnings(record=True) as w:
    # Cause all warnings to always be triggered.
    warnings.simplefilter("always")
    # Trigger a warning.
    fxn()
    # Verify some things
    assert len(w) == 1
    assert issubclass(w[-1].category, DeprecationWarning)
    assert "deprecated" in str(w[-1].message)

También se puede hacer que todas las advertencias sean excepciones usando error en lugar de always. Una cosa que hay que tener en cuenta es que si una advertencia ya se ha planteado debido a una regla de once o default, entonces no importa qué filtros estén establecidos, la advertencia no se verá de nuevo a menos que el registro de advertencias relacionadas con la advertencia se haya borrado.

Una vez que se cierra el gestor de contexto, el filtro de advertencias se restablece al estado en que se encontraba al entrar en el contexto. Esto evita que las pruebas cambien el filtro de advertencias de forma inesperada entre una prueba y otra, y que se produzcan resultados indeterminados en las pruebas. La función showwarning() del módulo también se restaura a su valor original. Nota: esto sólo puede garantizarse en una aplicación de un solo hilo. Si dos o más hilos utilizan el gestor de contexto catch_warnings al mismo tiempo, el comportamiento es indefinido.

Cuando se prueban múltiples operaciones que plantean el mismo tipo de advertencia, es importante probarlas de manera que se confirme que cada operación plantea una nueva advertencia (por ejemplo, establecer advertencias que se planteen como excepciones y comprobar que las operaciones plantean excepciones, comprobar que la longitud de la lista de advertencias siga aumentando después de cada operación, o bien suprimir las entradas anteriores de la lista de advertencias antes de cada nueva operación).

Actualización del código para las nuevas versiones de las dependencias

Las categorías de advertencia que interesan principalmente a los desarrolladores de Python (más que a los usuarios finales de aplicaciones escritas en Python) se ignoran por defecto.

En particular, esta lista de «ignorados por defecto» incluye DeprecationWarning (para cada módulo excepto``__main__``), lo que significa que los desarrolladores deben asegurarse de probar su código con advertencias típicamente ignoradas hechas visibles para recibir notificaciones oportunas de futuros cambios del API a última hora(ya sea en la biblioteca estándar o en paquetes de terceros).

En el caso ideal, el código tendrá un conjunto de pruebas adecuado, y el corredor de pruebas se encargará de habilitar implícitamente todas las advertencias cuando se ejecuten las pruebas (el corredor de pruebas proporcionado por el módulo unittest hace esto).

En casos menos ideales, las aplicaciones pueden ser revisadas por el uso de interfaces desaprobadas pasando -Wd al intérprete de Python (esto es la abreviatura de -W default) o ajustando PYTHONWARNINGS=default en el entorno. Esto permite el manejo por defecto de todas las advertencias, incluyendo aquellas que son ignoradas por defecto. Para cambiar la acción que se lleva a cabo para las advertencias encontradas puede cambiar el argumento que se pasa a -W (por ejemplo -W error). Consulte el indicador -W para obtener más detalles sobre lo que es posible.

Funciones Disponibles

warnings.warn(message, category=None, stacklevel=1, source=None)

Emite una advertencia, o tal vez la ignorar o lanza una excepción. El argumento category, si se da, debe ser un warning category class; por defecto es UserWarning. Alternativamente, message puede ser una instancia Warning, en cuyo caso category será ignorada y se usará message.__class__. En este caso, el texto del mensaje será str(message). Esta función hace una excepción si la advertencia particular emitida es convertida en un error por el warnings filter. El argumento stacklevel puede ser usado por funciones de envoltura escritas en Python, como esta:

def deprecation(message):
    warnings.warn(message, DeprecationWarning, stacklevel=2)

Esto hace que la advertencia se refiera al invocador de deprecation(), en lugar de a la fuente de deprecation() en sí (ya que esta última perdería el propósito del mensaje de advertencia).

source, si se suministra, es el objeto destruido que emitió un ResourceWarning.

Distinto en la versión 3.6: Añadido parámetro source.

warnings.warn_explicit(message, category, filename, lineno, module=None, registry=None, module_globals=None, source=None)

Se trata de una interfaz de bajo nivel para la funcionalidad de warn(), pasando explícitamente el mensaje, la categoría, el nombre de archivo y el número de línea, y opcionalmente el nombre del módulo y el registro (que debería ser el diccionario __warningregistry__ del módulo). El nombre del módulo por defecto es el nombre de archivo con .py desmembrado; si no se pasa el registro, la advertencia nunca se suprime. message debe ser una cadena y category una subclase de Warning o message puede ser una instancia Warning, en cuyo caso category será ignorada.

module_globals, si se suministra, debe ser el espacio de nombres global en uso por el código para el que se emite la advertencia. (Este argumento se utiliza para apoyar la visualización de la fuente de los módulos que se encuentran en los archivos zip o en otras fuentes de importación que no son del sistema de archivos).

source, si se suministra, es el objeto destruido que emitió un ResourceWarning.

Distinto en la versión 3.6: Añade el parámetro source.

warnings.showwarning(message, category, filename, lineno, file=None, line=None)

Escriba una advertencia en un archivo. La implementación por defecto llama formatwarning(message, category, filename, lineno, line) y escribe la cadena resultante a file, que por defecto es sys.stderr. Puede reemplazar esta función con cualquier interlocutor asignando a warnings.showwarning. line es una línea de código fuente que se incluirá en el mensaje de advertencia; si no se proporciona line, showwarning() intentará leer la línea especificada por nombre de archivo y lineno.

warnings.formatwarning(message, category, filename, lineno, line=None)

Formatea una advertencia de la manera estándar. Esto retorna una cadena que puede contener nuevas líneas incrustadas y termina en una nueva línea. line es una línea de código fuente a incluir en el mensaje de advertencia; si line no se suministra, formatwarning() intentará leer la línea especificada por el nombre de fichero filename y lineno.

warnings.filterwarnings(action, message='', category=Warning, module='', lineno=0, append=False)

Inserta una entrada en la lista de warnings filter specifications. La entrada se inserta por defecto en el frente; si append es verdadero, se inserta al final. Esto comprueba los tipos de los argumentos, compila las expresiones regulares message y module, y las inserta como una tupla en la lista de filtros de aviso. Las entradas más cercanas al principio de la lista anulan las entradas posteriores de la lista, si ambas coinciden con una advertencia en particular. Los argumentos omitidos predeterminan un valor que coincide con todo.

warnings.simplefilter(action, category=Warning, lineno=0, append=False)

Inserte una simple entrada en la lista de warnings filter specifications. El significado de los parámetros de la función es el mismo que el de filterwarnings(), pero no se necesitan expresiones regulares ya que el filtro insertado siempre coincide con cualquier mensaje de cualquier módulo siempre que la categoría y el número de línea coincidan.

warnings.resetwarnings()

Reajusta el filtro de advertencias. Esto descarta el efecto de todas las llamadas previas a filterwarnings(), incluyendo la de las opciones de línea de comandos de -W y las llamadas a simplefilter().

Gestores de Contexto disponibles

class warnings.catch_warnings(*, record=False, module=None)

Un gestor de contexto que copia y, al salir, restaura el filtro de advertencias y la función showwarning(). Si el argumento record es False (por defecto) el gestor de contextos retorna None al entrar. Si record es True, se retorna una lista que se va poblando progresivamente de objetos como se ve por una función personalizada de showwarning() (que también suprime la salida a sys.stdout). Cada objeto de la lista tiene atributos con los mismos nombres que los argumentos de showwarning().

El argumento module toma un módulo que será usado en lugar del módulo retornado cuando se importa warnings cuyo filtro será protegido. Este argumento existe principalmente para probar el propio módulo warnings.

Nota

El gestor catch_warnings funciona reemplazando y luego restaurando la función showwarning() del módulo y la lista interna de especificaciones del filtro. Esto significa que el gestor de contexto está modificando el estado global y por lo tanto no es seguro para los hilos.

dataclasses — Clases de datos

Código fuente: Lib/dataclasses.py [https://github.com/python/cpython/tree/3.9/Lib/dataclasses.py]

Este módulo provee un decorador y funciones para añadir métodos especiales automáticamente, como __init__() y __repr__() por ejemplo, a clases definidas por el usuario. Fue originalmente descrito en PEP 557 [https://www.python.org/dev/peps/pep-0557].

The member variables to use in these generated methods are defined using PEP 526 [https://www.python.org/dev/peps/pep-0526] type annotations. For example, this code:

from dataclasses import dataclass

@dataclass
class InventoryItem:
    """Class for keeping track of an item in inventory."""
    name: str
    unit_price: float
    quantity_on_hand: int = 0

    def total_cost(self) -> float:
        return self.unit_price * self.quantity_on_hand

will add, among other things, a __init__() that looks like:

def __init__(self, name: str, unit_price: float, quantity_on_hand: int = 0):
    self.name = name
    self.unit_price = unit_price
    self.quantity_on_hand = quantity_on_hand

Es importante observar que este método es añadido a la clase automáticamente; está implícito en la definición de InventoryItem implementada arriba.

Nuevo en la versión 3.7.

Decoradores, clases y funciones del módulo

@dataclasses.dataclass(*, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False)

Esta función es un decorator utilizado para añadir a las clases los métodos especiales generados, como se describe a continuación.

The dataclass() decorator examines the class to find fields. A field is defined as a class variable that has a type annotation. With two exceptions described below, nothing in dataclass() examines the type specified in the variable annotation.

El orden de los campos en los métodos generados es el mismo en el que se encuentran en la definición de la clase.

The dataclass() decorator will add various «dunder» methods to the class, described below. If any of the added methods already exist in the class, the behavior depends on the parameter, as documented below. The decorator returns the same class that it is called on; no new class is created.

Si dataclass() es llamado como un simple decorador sin parámetros, actúa con los valores por defecto documentados aquí. Específicamente, los siguientes tres usos de dataclass() son equivalentes:

@dataclass
class C:
    ...

@dataclass()
class C:
    ...

@dataclass(init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False)
class C:
   ...

Los parámetros de dataclass() son:

init: Si es verdadero (valor por defecto), el método __init__() será generado.

Si la clase ya define __init__(), este parámetro es ignorado.

repr: Si es verdadero (valor por defecto), el método __repr__() es generado. La cadena de representación generada tendrá el nombre de la clase junto al nombre y la representación de cada uno de sus campos, en el mismo orden en el que están definidos en la clase. Es posible indicar que ciertos campos no sean incluidos en la representación. Por ejemplo: InventoryItem(name='widget', unit_price=3.0, quantity_on_hand=10).

Si la clase ya define __repr__(), este parámetro es ignorado.

eq: Si es verdadero (por defecto), el método __eq__() es generado. Este método compara entre instancias de la clase representando cada una de ellas mediante una tupla, siendo los elementos de la misma los campos de la clase ubicados en el mismo orden en el que fueron definidos (dos tuplas son iguales si, y sólo si, sus campos son iguales).

Si la clase ya define __eq__(), este parámetro es ignorado.

order: Si es verdadero (False es el valor por defecto), los métodos __lt__(), __le__(), __gt__() y __ge__() serán generados. Estos métodos comparan la clase como si fuera una tupla con sus campos, en orden. Ambas instancias en la comparación deben ser del mismo tipo. Si order es verdadero y eq falso, se lanza una excepción ValueError.

Si la clase ya define __lt__(), __le__(), __gt__() o __ge__(), se lanza una excepción TypeError.

unsafe_hash: Si es False (por defecto), se genera el método __hash__() de acuerdo a los valores de eq y frozen definidos.

__hash__() es utilizado por la función incorporada hash() y cuando los objetos definidos por la clase son añadidos a colecciones hash, como por ejemplo diccionarios y conjuntos. Definir el método __hash__() en una clase implica que sus instancias son inmutables. La mutabilidad es una propiedad compleja, ya que depende de cómo el programador utilice el objeto, la existencia y comportamiento de __eq__() y del valor asignado a las flags eq y frozen en el decorador dataclass().

Por defecto, dataclass() no añade de forma implícita el método __hash__() a menos que sea seguro hacerlo. Tampoco añade o cambia un método __hash__() previamente definido de forma explícita. Definir el atributo de clase __hash__ = None tiene un significado específico en Python, descrito en la documentación dedicada a __hash__().

Si __hash__() no está definido explícitamente, o si está configurado como None, entonces dataclass() puede agregar un método implícito __hash__(). Aunque no se recomienda, puede forzar un dataclass() a crear un método __hash__() con unsafe_hash=True. Este podría ser el caso si su clase es lógicamente inmutable pero, no obstante, puede mutar. Este es un caso de uso especializado y debe considerarse detenidamente.

A continuación se explican las reglas que se aplican en la creación implícita del método __hash__(). Observar que no es compatible definir explícitamente un método __hash__() en su clase de datos y al mismo tiempo asignar unsafe_hash=True; esto lanza una excepción TypeError.

Si eq y frozen son ambos verdaderos, dataclass() genera por defecto un método hash() por ti. En el caso que eq sea verdadero y frozen falso, a __hash__() se le asigna None, en consecuencia será unhashable (lo cual es deseable, ya que es mutable). Si eq es falso, __hash__() permanece sin cambios, por lo que en este caso se hará uso del método hash() heredado de la superclase (lo que implica que si la superclase es object, se aplicará el hashing basado en el id de los objetos).

frozen: Si es verdadero (el valor por defecto es False), cualquier intento de asignación a un campo de la clase lanza una excepción. Esto emula el comportamiento de las instancias congeladas (frozen) de sólo lectura. Si __setattr__() o __delattr__() son definidos en la clase, se lanzará una excepción TypeError. Esto es ampliado más abajo.

Los fields pueden especificar un valor por defecto opcionalmente, simplemente usando la sintaxis normal de Python:

@dataclass
class C:
    a: int       # 'a' has no default value
    b: int = 0   # assign a default value for 'b'

En este ejemplo, tanto a como b serán incluidos en el método __init__() agregado, el cual será definido como sigue:

def __init__(self, a: int, b: int = 0):

TypeError will be raised if a field without a default value follows a field with a default value. This is true whether this occurs in a single class, or as a result of class inheritance.

dataclasses.field(*, default=MISSING, default_factory=MISSING, repr=True, hash=None, init=True, compare=True, metadata=None)

Para casos de uso común, estas funcionalidades son suficientes. Sin embargo, existen otras características de las clases de datos que requieren información adicional en ciertos campos. Para satisfacer esta necesidad, es posible reemplazar cualquier valor por defecto de un campo mediante una llamada a la función field(). Por ejemplo:

@dataclass
class C:
    mylist: list[int] = field(default_factory=list)

c = C()
c.mylist += [1, 2, 3]

Como se muestra arriba, el valor MISSING es un objeto centinela utilizado para detectar si los parámetros default y default_factory son provistos. Este objeto centinela es utilizado debido a que None es un valor válido para default. Ningún procedimiento debe utilizar directamente el valor MISSING.

Los parámetros de field() son:

default: Si es provisto, este será el valor por defecto para este campo. Es necesario que sea definido ya que la propia llamada a field() reemplaza la posición normal del valor por defecto.

default_factory: Si es provisto, debe ser un objeto invocable sin argumentos, el cual será llamado cuando el valor por defecto de este campo sea necesario. Además de otros propósitos, puede ser utilizado para especificar campos con valores por defecto mutables, como se explica a continuación. Especificar tanto default como default_factory resulta en un error.

init: Si es verdadero (por defecto), este campo es incluido como parámetro del método __init__() generado.

repr: Si es verdadero (por defecto), este campo es incluido en la cadena de caracteres que retorna el método __repr__() generado.

compare: Si es verdadero (por defecto), este campo es incluido en los métodos de comparación generados (__eq__(), __gt__() y otros).

hash: Su valor puede ser de tipo booleano o None. Si es verdadero, este campo es incluido en el método __hash__() generado. Si es None (por defecto), utiliza el valor de compare: normalmente éste es el comportamiento esperado. Un campo debería ser considerado para el hash si es compatible con operaciones de comparación. Está desaconsejado establecer este valor en algo que no sea None.

Una posible razón para definir hash=False y compare=True podría ser el caso en el que computar el valor hash para dicho campo es costoso pero el campo es necesario para los métodos de comparación, siempre que existan otros campos que contribuyen al valor hash del tipo. Incluso si un campo se excluye del hash, se seguirá utilizando a la hora de comparar.

metadata: Puede ser un mapeo o None. None es tratado como un diccionario vacío. Este valor es envuelto en MappingProxyType() para que sea de sólo lectura y visible en el objeto Field. No es utilizado por las clases de datos, mas bien es provisto como un mecanismo de extensión de terceros. Varios terceros pueden tener su propia clave para utilizar como espacio de nombres en metadata.

Si el valor por defecto de un campo es especificado por una llamada a field(), los atributos de clase para este campo serán reemplazados por los especificados en el valor default. Si el valor de default no es provisto, el atributo de clase será eliminado. La idea es que, después que la ejecución del decorador dataclass(), todos los atributos de la clase contengan los valores por defecto de cada campo, como si fueran definidos uno por uno. Por ejemplo, luego de:

@dataclass
class C:
    x: int
    y: int = field(repr=False)
    z: int = field(repr=False, default=10)
    t: int = 20

El atributo de clase C.z será 10, el atributo de clase C.t será 20 y los atributos de clase C.x y C.y no serán definidos.

class dataclasses.Field

Los objetos Field describen cada campo definido. Estos objetos son creados internamente y son retornados por el método fields() definido en este módulo (explicado más abajo). Los usuarios no deben instanciar un objeto Field directamente. Sus atributos documentados son:

name: El nombre del campo.

type: El tipo del campo.

default, default_factory, init, repr, hash, compare y metadata tienen los mismos valores y significados respecto a la declaración de field() (ver arriba).

Pueden existir otros atributos, pero son privados y no deberían ser considerados ni depender de ellos.

dataclasses.fields(class_or_instance)

Retorna una tupla de objetos Field que definen los campos para esta clase de datos. Acepta tanto una clase de datos como una instancia de esta. Lanza una excepción TypeError si se le pasa cualquier otro objeto. No retorna pseudocampos, que son ClassVar o InitVar.

dataclasses.asdict(obj, *, dict_factory=dict)

Converts the dataclass obj to a dict (by using the factory function dict_factory). Each dataclass is converted to a dict of its fields, as name: value pairs. dataclasses, dicts, lists, and tuples are recursed into. Other objects are copied with copy.deepcopy().

Example of using asdict() on nested dataclasses:

@dataclass
class Point:
     x: int
     y: int

@dataclass
class C:
     mylist: list[Point]

p = Point(10, 20)
assert asdict(p) == {'x': 10, 'y': 20}

c = C([Point(0, 0), Point(10, 4)])
assert asdict(c) == {'mylist': [{'x': 0, 'y': 0}, {'x': 10, 'y': 4}]}

To create a shallow copy, the following workaround may be used:

dict((field.name, getattr(obj, field.name)) for field in fields(obj))

asdict() raises TypeError if obj is not a dataclass instance.

dataclasses.astuple(obj, *, tuple_factory=tuple)

Converts the dataclass obj to a tuple (by using the factory function tuple_factory). Each dataclass is converted to a tuple of its field values. dataclasses, dicts, lists, and tuples are recursed into. Other objects are copied with copy.deepcopy().

Continuando con el ejemplo anterior:

assert astuple(p) == (10, 20)
assert astuple(c) == ([(0, 0), (10, 4)],)

To create a shallow copy, the following workaround may be used:

tuple(getattr(obj, field.name) for field in dataclasses.fields(obj))

astuple() raises TypeError if obj is not a dataclass instance.

dataclasses.make_dataclass(cls_name, fields, *, bases=(), namespace=None, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False)

Crea una nueva clase de datos con el nombre cls_name, con los campos definidos en fields, con las clases base dadas en bases e inicializada con el espacio de nombres dado en namespace. fields es un iterable que cumple con una de estas formas: name, (name, type) o (name, type, Field). Si solo name es proporcionado, typing.Any es usado para type. Los valores init, repr, eq, order, unsafe_hash y frozen tienen el mismo significado que en la función dataclass().

Esta función no es estrictamente necesaria debido a que cualquier mecanismo de Python para crear una nueva clase con __annotations__ puede usar la función dataclass() para convertir esa clase en una clase de datos. Esta función se proporciona simplemente por comodidad. Por ejemplo:

C = make_dataclass('C',
                   [('x', int),
                     'y',
                    ('z', int, field(default=5))],
                   namespace={'add_one': lambda self: self.x + 1})

Es equivalente a:

@dataclass
class C:
    x: int
    y: 'typing.Any'
    z: int = 5

    def add_one(self):
        return self.x + 1

dataclasses.replace(obj, /, **changes)

Creates a new object of the same type as obj, replacing fields with values from changes. If obj is not a Data Class, raises TypeError. If values in changes do not specify fields, raises TypeError.

El objeto recién retornado es creado llamando al método __init__() de la clase de datos. Esto asegura que __post_init__(), si existe, también será llamado.

Las variables de solo inicialización sin valores predeterminados, si existen, deben especificarse en la llamada a replace() para que puedan pasarse a __init__() y __post_init__().

Es un error que changes contenga cualquier campo que esté definido como init=False. Una excepción ValueError se lanzará en este caso.

Tenga en cuenta cómo funcionan los campos init=False durante una llamada a replace(). No se copian del objeto de origen, sino que, de inicializarse, lo hacen en __post_init__(). Se espera que los campos init=False se utilicen en contadas ocasiones y con prudencia. Si se utilizan, podría ser conveniente tener constructores de clase alternativos, o quizás un método personalizado replace() (o con un nombre similar) que maneje la copia de instancias.

dataclasses.is_dataclass(obj)

Retorna True si su parámetro es una clase de datos o una instancia de una, en caso contrario retorna False.

Si se necesita conocer si una clase es una instancia de dataclass (y no una clase de datos en si misma), se debe agregar una verificación adicional para not isinstance(obj, type):

def is_dataclass_instance(obj):
    return is_dataclass(obj) and not isinstance(obj, type)

Procesamiento posterior a la inicialización

El código del método generado __init__() llamará a un método llamado __post_init__(), si __post_init__() está definido en la clase. Normalmente se llamará como self.__post_init__(). Sin embargo, si se define algún campo InitVar, también se pasarán a __post_init__() en el orden en que se definieron en la clase. Si no se genera el método __init__(), entonces __post_init__() no se llamará automáticamente.

Entre otros usos, esto permite inicializar valores de campo que dependen de uno o más campos. Por ejemplo:

@dataclass
class C:
    a: float
    b: float
    c: float = field(init=False)

    def __post_init__(self):
        self.c = self.a + self.b

The __init__() method generated by dataclass() does not call base class __init__() methods. If the base class has an __init__() method that has to be called, it is common to call this method in a __post_init__() method:

@dataclass
class Rectangle:
    height: float
    width: float

@dataclass
class Square(Rectangle):
    side: float

    def __post_init__(self):
        super().__init__(self.side, self.side)

Note, however, that in general the dataclass-generated __init__() methods don’t need to be called, since the derived dataclass will take care of initializing all fields of any base class that is a dataclass itself.

Consulta la sección sobre variables de solo inicialización que hay a continuación para conocer las posibles formas de pasar parámetros a __post_init__(). También vea la advertencia sobre cómo replace() maneja los campos init = False.

Variables de clase

Uno de los dos casos donde dataclass() realmente inspecciona el tipo de un campo, es para determinar si dicho campo es una variable de clase como se define en PEP 526 [https://www.python.org/dev/peps/pep-0526]. Lo hace comprobando si el tipo del campo es typing.ClassVar. Si un campo es una ClassVar, se deja de considerar como campo y los mecanismos de las clases de datos lo ignoran. Tales pseudocampos ClassVar no son retornados por la función del módulo fields().

Variable de solo inicialización

El otro caso donde dataclass() inspecciona una anotación de tipo es para determinar si un campo es una variable de solo inicialización. Lo hace comprobando si el tipo de un campo es dataclasses.InitVar. Si un campo es un InitVar, se considera un pseudocampo llamado “campo de solo inicialización”. Como no es un campo verdadero, no es retornado por la función del módulo fields(). Los campos de solo inicialización se agregan como parámetros al método generado __init__() y se pasan al método opcional __post_init__(). No son utilizados de otra manera por las clases de datos.

Por ejemplo, supongamos que se va a inicializar un campo desde una base de datos, de no proporcionarse un valor al crear la clase:

@dataclass
class C:
    i: int
    j: int = None
    database: InitVar[DatabaseType] = None

    def __post_init__(self, database):
        if self.j is None and database is not None:
            self.j = database.lookup('j')

c = C(10, database=my_database)

En este caso, fields() retornará objetos Field para i y j, pero no para database.

Instancias congeladas

No es posible crear objetos verdaderamente inmutables en Python. Sin embargo, se puede emular la inmutabilidad pasando frozen=True al decorador dataclass(). En este caso, las clases de datos añadirán los métodos __setattr__() y __delattr__() a la clase. Estos métodos lanzarán una excepción FrozenInstanceError cuando sean llamados.

Hay una pequeña penalización de rendimiento cuando se usa frozen=True, esto se debe a que __init__() no puede usar una asignación simple para inicializar campos, viéndose obligado a usar object.__setattr__().

Herencia

Cuando la clase de datos está siendo creada por el decorador dataclass(), revisa todas las clases base de la clase en el MRO invertido (es decir, comenzando en object) y, para cada clase de datos que encuentra, agrega los campos de esa clase base a un mapeo ordenado. Después de agregar todos los campos de la clase base, agrega sus propios campos al mapeo. Todos los métodos generados utilizarán este mapeo ordenado calculado combinando los campos. Como los campos están en orden de inserción, las clases derivadas anulan las clases base. Un ejemplo:

@dataclass
class Base:
    x: Any = 15.0
    y: int = 0

@dataclass
class C(Base):
    z: int = 10
    x: int = 15

La lista final de campos es, en orden, x, y, z. El tipo final de x es int, como se especifica en la clase C.

El método __init__() generado para C se verá como:

def __init__(self, x: int = 15, y: int = 0, z: int = 10):

Funciones fábrica por defecto

Si un field() especifica una default_factory, se llama sin argumentos cuando se necesita un valor predeterminado para el campo. Por ejemplo, para crear una nueva instancia de una lista, debe usarse:

mylist: list = field(default_factory=list)

Si un campo está excluido de __init__() (usando init = False) y el campo también especifica default_factory, entonces la función de fábrica predeterminada siempre se llamará desde la función generada __init__(). Esto sucede porque no existe otra forma de darle al campo un valor inicial.

Valores por defecto mutables

Python almacena los valores miembros por defecto en atributos de clase. Considera este ejemplo, sin usar clases de datos:

class C:
    x = []
    def add(self, element):
        self.x.append(element)

o1 = C()
o2 = C()
o1.add(1)
o2.add(2)
assert o1.x == [1, 2]
assert o1.x is o2.x

Tenga en cuenta que, tal como cabe esperar, las dos instancias de la clase C comparten la misma variable de clase x.

Usando clases de datos, si este código fuera válido:

@dataclass
class D:
    x: List = []
    def add(self, element):
        self.x += element

generaría un código similar a:

class D:
    x = []
    def __init__(self, x=x):
        self.x = x
    def add(self, element):
        self.x += element

assert D().x is D().x

Este tiene el mismo problema que el ejemplo original usando la clase C. Es decir, dos instancias de la clase D que no especifican un valor para x, al crear una instancia de la clase, compartirán la misma copia de x. Debido a que las clases de datos usan simplemente el mecanismo normal de creación de clases de Python, también comparten este comportamiento. No existe una forma genérica de que las clases de datos detecten esta condición. En su lugar, las clases de datos generarán una excepción TypeError si detectan un parámetro predeterminado de tipo list, dict o set (contenedores incorporados mutables). Esta es una solución parcial, pero protege contra muchos de los errores más comunes.

Usar las funciones fábrica por defecto es una forma de crear nuevas instancias de tipos mutables como valores por defecto para campos:

@dataclass
class D:
    x: list = field(default_factory=list)

assert D().x is not D().x

Excepciones

exception dataclasses.FrozenInstanceError

Raised when an implicitly defined __setattr__() or __delattr__() is called on a dataclass which was defined with frozen=True. It is a subclass of AttributeError.

contextlib — Utilidades para declaraciones de contexto with

Código fuente: Lib/contextlib.py [https://github.com/python/cpython/tree/3.9/Lib/contextlib.py]

Este módulo proporciona utilidades para tareas comunes que involucran la declaración with. Para obtener más información, consulte también Tipos Gestores de Contexto y Gestores de Contexto en la Declaración with.

Utilidades

Funciones y clases proporcionadas:

class contextlib.AbstractContextManager

Una clase base abstracta para clases que implementan object.__aenter__() y object.__exit__(). Se proporciona una implementación predeterminada para object.__enter__() que retorna self mientras que object.__exit__() es un método abstracto que por defecto retorna None. Véase también la definición de Tipos Gestores de Contexto.

Nuevo en la versión 3.6.

class contextlib.AbstractAsyncContextManager

Una clase base abstracta para clases que implementan object.__aenter__() y object.__aexit__(). Se proporciona una implementación predeterminada para object.__aenter__() que retorna self mientras que object.__aexit__() es un método abstracto que por defecto retorna None. Véase también la definición de Gestores de Contexto Asíncronos.

Nuevo en la versión 3.7.

@contextlib.contextmanager

Esta función es decorador que se puede usar para definir una función de fábrica para gestores de contexto de declaración with, sin necesidad de crear una clase o separar __enter__() y __exit__() métodos.

Si bien muchos objetos admiten de forma nativa el uso con declaraciones, a veces es necesario administrar un recurso que no sea un administrador de contexto por sí mismo y no implemente un método close() para usar con contextlib.close

Un ejemplo abstracto sería el siguiente para garantizar la gestión correcta de los recursos:

from contextlib import contextmanager

@contextmanager
def managed_resource(*args, **kwds):
    # Code to acquire resource, e.g.:
    resource = acquire_resource(*args, **kwds)
    try:
        yield resource
    finally:
        # Code to release resource, e.g.:
        release_resource(resource)

>>> with managed_resource(timeout=3600) as resource:
...     # Resource is released at the end of this block,
...     # even if code in the block raises an exception

La función que se está decorando debe retornar un iterador generador cuando se llama. Este iterador debe producir exactamente un valor, que estará vinculado a los objetivos en la with declaración de la cláusula as, si existe.

En el punto donde el generador cede, se ejecuta el bloque anidado en la palabra clave with. El generador se reanuda luego de salir del bloque. Si se produce una excepción no controlada en el bloque, se vuelve a plantear dentro del generador en el punto donde se produjo el rendimiento. Por lo tanto, puede usar una declaración try…except…finally para atrapar el error (si lo hay), o asegurarse de que se realice una limpieza. Si una excepción queda atrapada simplemente para registrarla o realizar alguna acción (en lugar de suprimirla por completo), el generador debe volver a generar esa excepción. De lo contrario, el administrador de contexto del generador indicará a la palabra clave with que se ha manejado la excepción, y la ejecución se reanudará con la declaración inmediatamente siguiente a la palabra clave with.

contextmanager() usa ContextDecorator para que los gestores de contexto que crea se puedan usar como decoradores, así como en declaraciones with. Cuando se usa como decorador, se crea implícitamente una nueva instancia de generador en cada llamada de función (esto permite que los gestores de contexto «de-un-tiro» creados por contextmanager() cumplan el requisito de que los gestores de contexto admitan múltiples invocaciones para ser utilizado como decoradores).

Distinto en la versión 3.2: Uso de ContextDecorator.

@contextlib.asynccontextmanager

Similar a contextmanager(), pero crea un administrador de contexto asíncrono.

Esta función es decorador que se puede utilizar para definir una función de fábrica para gestores de contexto asíncrono de declaración async with, sin necesidad de crear una clase o separar __aenter__() y métodos __aexit__(). Debe aplicarse a una función asynchronous generator.

Un ejemplo simple:

from contextlib import asynccontextmanager

@asynccontextmanager
async def get_connection():
    conn = await acquire_db_connection()
    try:
        yield conn
    finally:
        await release_db_connection(conn)

async def get_all_users():
    async with get_connection() as conn:
        return conn.query('SELECT ...')

Nuevo en la versión 3.7.

contextlib.closing(thing)

retorna un gestor de contexto que cierra thing al completar el bloque. Esto es básicamente equivalente a:

from contextlib import contextmanager

@contextmanager
def closing(thing):
    try:
        yield thing
    finally:
        thing.close()

Y te permite escribir código como este:

from contextlib import closing
from urllib.request import urlopen

with closing(urlopen('https://www.python.org')) as page:
    for line in page:
        print(line)

sin necesidad de cerrar explícitamente la page. Incluso si se produce un error, se llamará a page.close() cuando salga el bloque with.

contextlib.nullcontext(enter_result=None)

retorna un gestor de contexto que retorna enter_result de __enter__, pero de lo contrario no hace nada. Está destinado a ser utilizado como un sustituto para un administrador de contexto opcional, por ejemplo:

def myfunction(arg, ignore_exceptions=False):
    if ignore_exceptions:
        # Use suppress to ignore all exceptions.
        cm = contextlib.suppress(Exception)
    else:
        # Do not ignore any exceptions, cm has no effect.
        cm = contextlib.nullcontext()
    with cm:
        # Do something

Un ejemplo usando enter_result:

def process_file(file_or_path):
    if isinstance(file_or_path, str):
        # If string, open file
        cm = open(file_or_path)
    else:
        # Caller is responsible for closing file
        cm = nullcontext(file_or_path)

    with cm as file:
        # Perform processing on the file

Nuevo en la versión 3.7.

contextlib.suppress(*exceptions)

Return a context manager that suppresses any of the specified exceptions if they occur in the body of a with statement and then resumes execution with the first statement following the end of the with statement.

Al igual que con cualquier otro mecanismo que suprima completamente las excepciones, este administrador de contexto debe usarse solo para cubrir errores muy específicos en los que se sabe que continuar silenciosamente con la ejecución del programa es lo correcto.

Por ejemplo:

from contextlib import suppress

with suppress(FileNotFoundError):
    os.remove('somefile.tmp')

with suppress(FileNotFoundError):
    os.remove('someotherfile.tmp')

Este código es equivalente a:

try:
    os.remove('somefile.tmp')
except FileNotFoundError:
    pass

try:
    os.remove('someotherfile.tmp')
except FileNotFoundError:
    pass

Este gestor de contexto es reentrant.

Nuevo en la versión 3.4.

contextlib.redirect_stdout(new_target)

Administrador de contexto para redirigir temporalmente sys.stdout a otro archivo u objeto similar a un archivo.

Esta herramienta agrega flexibilidad a las funciones o clases existentes cuya salida está programada para stdout.

For example, the output of help() normally is sent to sys.stdout. You can capture that output in a string by redirecting the output to an io.StringIO object. The replacement stream is returned from the __enter__ method and so is available as the target of the with statement:

with redirect_stdout(io.StringIO()) as f:
    help(pow)
s = f.getvalue()

Para enviar la salida de help() a un archivo en el disco, redirija la salida a un archivo normal:

with open('help.txt', 'w') as f:
    with redirect_stdout(f):
        help(pow)

Para enviar la salida de help() a sys.stderr:

with redirect_stdout(sys.stderr):
    help(pow)

Tenga en cuenta que el efecto secundario global en sys.stdout significa que este administrador de contexto no es adecuado para su uso en el código de la biblioteca y en la mayoría de las aplicaciones con subprocesos. Tampoco tiene efecto en la salida de subprocesos. Sin embargo, sigue siendo un enfoque útil para muchos scripts de utilidad.

Este gestor de contexto es reentrant.

Nuevo en la versión 3.4.

contextlib.redirect_stderr(new_target)

Similar a redirect_stdout() pero redirigiendo sys.stderr a otro archivo u objeto similar a un archivo.

Este gestor de contexto es reentrant.

Nuevo en la versión 3.5.

class contextlib.ContextDecorator

Una clase base que permite que un administrador de contexto también se use como decorador.

Los gestores de contexto que heredan de ContextDecorator tienen que implementar __enter__ y __exit__ de manera normal. __exit__ conserva su manejo opcional de excepciones incluso cuando se usa como decorador.

ContextDecorator es utilizado por contextmanager(), por lo que obtiene esta funcionalidad automáticamente.

Ejemplo de ContextDecorator:

from contextlib import ContextDecorator

class mycontext(ContextDecorator):
    def __enter__(self):
        print('Starting')
        return self

    def __exit__(self, *exc):
        print('Finishing')
        return False

>>> @mycontext()
... def function():
...     print('The bit in the middle')
...
>>> function()
Starting
The bit in the middle
Finishing

>>> with mycontext():
...     print('The bit in the middle')
...
Starting
The bit in the middle
Finishing

Este cambio es solo azúcar sintáctico para cualquier construcción de la siguiente forma:

def f():
    with cm():
        # Do stuff

ContextDecorator le permite escribir en su lugar:

@cm()
def f():
    # Do stuff

Deja en claro que el cm se aplica a toda la función, en lugar de solo una parte de ella (y guardar un nivel de sangría también es bueno).

Los gestores de contexto existentes que ya tienen una clase base pueden ampliarse utilizando ContextDecorator como una clase mezcla (mixin):

from contextlib import ContextDecorator

class mycontext(ContextBaseClass, ContextDecorator):
    def __enter__(self):
        return self

    def __exit__(self, *exc):
        return False

Nota

Como la función decorada debe poder llamarse varias veces, el gestor de contexto subyacente debe admitir el uso en múltiples declaraciones with. Si este no es el caso, se debe utilizar la construcción original con la declaración explícita with dentro de la función.

Nuevo en la versión 3.2.

class contextlib.ExitStack

Un gestor de contexto que está diseñado para facilitar la combinación programática de otros gestores de contexto y funciones de limpieza, especialmente aquellas que son opcionales o que de otro modo son impulsadas por los datos de entrada.

Por ejemplo, un conjunto de archivos puede manejarse fácilmente en una sola declaración de la siguiente manera:

with ExitStack() as stack:
    files = [stack.enter_context(open(fname)) for fname in filenames]
    # All opened files will automatically be closed at the end of
    # the with statement, even if attempts to open files later
    # in the list raise an exception

The __enter__() method returns the ExitStack instance, and performs no additional operations.

Cada instancia mantiene una pila de retrollamadas registradas que se llaman en orden inverso cuando la instancia se cierra (ya sea explícita o implícitamente al final de una instrucción with). Tenga en cuenta que las retrollamadas no se invocan implícitamente cuando la instancia de la pila de contexto se recolecta basura.

Este modelo de pila se utiliza para que los administradores de contexto que adquieren sus recursos en su método __init__ (como los objetos de archivo) se puedan manejar correctamente.

Dado que las retrollamadas registradas se invocan en el orden inverso del registro, esto termina comportándose como si se hubieran utilizado múltiples instrucciones anidadas with con el conjunto registrado de retrollamadas. Esto incluso se extiende al manejo de excepciones: si una retrollamada interna suprime o reemplaza una excepción, las retrollamadas externas se pasarán argumentos basados en ese estado actualizado.

Esta es una API de nivel relativamente bajo que se ocupa de los detalles de desenrollar correctamente la pila de retrollamadas de salida. Proporciona una base adecuada para administradores de contexto de nivel superior que manipulan la pila de salida en formas específicas de la aplicación.

Nuevo en la versión 3.3.

enter_context(cm)

Ingresa a un nuevo administrador de contexto y agrega su método __exit__() a la pila de retrollamada. El valor de retorno es el resultado del método propio del administrador de contexto __enter__().

Estos administradores de contexto pueden suprimir excepciones tal como lo harían normalmente si se usaran directamente como parte de una declaración with.

push(exit)

Agrega un método de gestor de contexto __exit__() a la pila de retrollamada.

Como __enter__ no se invoca, este método se puede usar para cubrir parte de una implementación __enter__() con un método propio del gestor de contexto __exit__().

Si se pasa un objeto que no es un administrador de contexto, este método supone que es una retrollamada con la misma firma que el método __exit__() de un gestor de contexto y lo agrega directamente a la pila de retrollamada.

Al retornar valores verdaderos, estas retrollamadas pueden suprimir excepciones de la misma manera que el gestor de contexto los métodos __exit__() pueden hacerlo.

El objeto pasado se retorna desde la función, lo que permite que este método se use como decorador de funciones.

callback(callback, /, *args, **kwds)

Acepta una función de retrollamada arbitraria y argumentos y la agrega a la pila de retrollamada.

A diferencia de los otros métodos, las retrollamadas agregadas de esta manera no pueden suprimir excepciones (ya que nunca se pasan los detalles de excepción).

La retrollamada pasada se retorna desde la función, lo que permite que este método se use como decorador de funciones.

pop_all()

Transfiere la pila de retrollamada a una instancia fresca ExitStack y la retorna. Esta operación no invoca retrollamadas; en cambio, ahora se invocarán cuando se cierre la nueva pila (ya sea explícita o implícitamente al final de una instrucción with).

Por ejemplo, un grupo de archivos se puede abrir como una operación de «todo o nada» de la siguiente manera:

with ExitStack() as stack:
    files = [stack.enter_context(open(fname)) for fname in filenames]
    # Hold onto the close method, but don't call it yet.
    close_files = stack.pop_all().close
    # If opening any file fails, all previously opened files will be
    # closed automatically. If all files are opened successfully,
    # they will remain open even after the with statement ends.
    # close_files() can then be invoked explicitly to close them all.

close()

Inmediatamente desenrolla la pila de retrollamada, invocando retrollamadas en el orden inverso de registro. Para los administradores de contexto y las retrollamadas de salida registradas, los argumentos pasados indicarán que no se produjo ninguna excepción.

class contextlib.AsyncExitStack

Un gestor de contexto asíncrono, similar a ExitStack, que admite la combinación de gestores de contexto síncrono y asíncrono, además de tener rutinas para la lógica de limpieza.

El método close() no está implementado, aclose() debe usarse en su lugar.

coroutine enter_async_context(cm)

Similar a enter_context() pero espera un administrador de contexto asíncrono.

push_async_exit(exit)

Similar a push() pero espera un gestor de contexto asíncrono o una función de rutina.

push_async_callback(callback, /, *args, **kwds)

Similar a callback() pero espera una función de rutina.

coroutine aclose()

Similar a close() pero maneja adecuadamente los objetos de espera.

Continuando con el ejemplo para asynccontextmanager():

async with AsyncExitStack() as stack:
    connections = [await stack.enter_async_context(get_connection())
        for i in range(5)]
    # All opened connections will automatically be released at the end of
    # the async with statement, even if attempts to open a connection
    # later in the list raise an exception.

Nuevo en la versión 3.7.

Ejemplos y recetas

Esta sección describe algunos ejemplos y recetas para hacer un uso efectivo de las herramientas proporcionadas por contextlib.

Apoyando un número variable de gestores de contexto

El caso de uso principal para ExitStack es el que se proporciona en la documentación de la clase: admite un número variable de gestores de contexto y otras operaciones de limpieza en una sola with. La variabilidad puede provenir de la cantidad de gestores de contexto que necesitan ser impulsados por la entrada del usuario (como abrir una colección de archivos especificada por el usuario), o de que algunos de los gestores de contexto sean opcionales:

with ExitStack() as stack:
    for resource in resources:
        stack.enter_context(resource)
    if need_special_resource():
        special = acquire_special_resource()
        stack.callback(release_special_resource, special)
    # Perform operations that use the acquired resources

Como se muestra, ExitStack también hace que sea bastante fácil de usar with para administrar recursos arbitrarios que no admiten de forma nativa el protocolo de gestión de contexto.

Capturando excepciones de los métodos __enter__

Ocasionalmente es deseable capturar excepciones de una implementación del método __enter__, sin capturar inadvertidamente excepciones del cuerpo de la declaración with o el método __exit__ del gestor de contexto. Al usar ExitStack, los pasos en el protocolo de gestor de contexto se pueden separar ligeramente para permitir esto:

stack = ExitStack()
try:
    x = stack.enter_context(cm)
except Exception:
    # handle __enter__ exception
else:
    with stack:
        # Handle normal case

Es probable que la necesidad de hacer esto indique que la API subyacente debería proporcionar una interfaz de administración de recursos directa para usar con try/except/finally, pero no todas las API están bien diseñados en ese sentido. Cuando un administrador de contexto es la única API de administración de recursos proporcionada, entonces ExitStack puede facilitar el manejo de diversas situaciones que no se pueden manejar directamente en una declaración with.

Limpieza en una implementación __enter__

Como se señala en la documentación de ExitStack.push(), este método puede ser útil para limpiar un recurso ya asignado si fallan los pasos posteriores en __enter__().

Aquí hay un ejemplo de cómo hacer esto para un administrador de contexto que acepta funciones de adquisición y liberación de recursos, junto con una función de validación opcional, y las asigna al protocolo de administración de contexto:

from contextlib import contextmanager, AbstractContextManager, ExitStack

class ResourceManager(AbstractContextManager):

    def __init__(self, acquire_resource, release_resource, check_resource_ok=None):
        self.acquire_resource = acquire_resource
        self.release_resource = release_resource
        if check_resource_ok is None:
            def check_resource_ok(resource):
                return True
        self.check_resource_ok = check_resource_ok

    @contextmanager
    def _cleanup_on_error(self):
        with ExitStack() as stack:
            stack.push(self)
            yield
            # The validation check passed and didn't raise an exception
            # Accordingly, we want to keep the resource, and pass it
            # back to our caller
            stack.pop_all()

    def __enter__(self):
        resource = self.acquire_resource()
        with self._cleanup_on_error():
            if not self.check_resource_ok(resource):
                msg = "Failed validation for {!r}"
                raise RuntimeError(msg.format(resource))
        return resource

    def __exit__(self, *exc_details):
        # We don't need to duplicate any of our resource release logic
        self.release_resource()

Reemplazar cualquier uso de try-finally y marcar variables

Un patrón que a veces verá es una declaración de try-finally con una variable de indicador para indicar si el cuerpo de la cláusula finally debe ejecutarse o no. En su forma más simple (que ya no puede manejarse simplemente usando una cláusula except en su lugar), se parece a esto:

cleanup_needed = True
try:
    result = perform_operation()
    if result:
        cleanup_needed = False
finally:
    if cleanup_needed:
        cleanup_resources()

Al igual que con cualquier código basado en la declaración try, esto puede causar problemas de desarrollo y revisión, porque el código de configuración y el código de limpieza pueden terminar separados por secciones de código arbitrariamente largas.

ExitStack hace posible registrar una retrollamada para su ejecución al final de una instrucción with, y luego decide omitir la ejecución de esa retrollamada:

from contextlib import ExitStack

with ExitStack() as stack:
    stack.callback(cleanup_resources)
    result = perform_operation()
    if result:
        stack.pop_all()

Esto permite que el comportamiento de limpieza previsto se haga explícito por adelantado, en lugar de requerir una variable de indicador separada.

Si una aplicación particular usa mucho este patrón, puede simplificarse aún más por medio de una pequeña clase auxiliar:

from contextlib import ExitStack

class Callback(ExitStack):
    def __init__(self, callback, /, *args, **kwds):
        super().__init__()
        self.callback(callback, *args, **kwds)

    def cancel(self):
        self.pop_all()

with Callback(cleanup_resources) as cb:
    result = perform_operation()
    if result:
        cb.cancel()

Si la limpieza del recurso no está bien agrupada en una función independiente, entonces todavía es posible usar la forma decoradora de ExitStack.callback() para declarar la limpieza del recurso por adelantado:

from contextlib import ExitStack

with ExitStack() as stack:
    @stack.callback
    def cleanup_resources():
        ...
    result = perform_operation()
    if result:
        stack.pop_all()

Debido a la forma en que funciona el protocolo decorador, una función de retrollamada declarada de esta manera no puede tomar ningún parámetro. En cambio, se debe acceder a los recursos que se liberarán como variables de cierre.

Usar un gestor de contexto como decorador de funciones

ContextDecorator hace posible usar un gestor de contexto tanto en una instrucción ordinaria with como también como decorador de funciones.

Por ejemplo, a veces es útil envolver funciones o grupos de declaraciones con un registrador que puede rastrear la hora de entrada y la hora de salida. En lugar de escribir tanto un decorador de funciones como un administrador de contexto para la tarea, heredar de ContextDecorator proporciona ambas capacidades en una sola definición:

from contextlib import ContextDecorator
import logging

logging.basicConfig(level=logging.INFO)

class track_entry_and_exit(ContextDecorator):
    def __init__(self, name):
        self.name = name

    def __enter__(self):
        logging.info('Entering: %s', self.name)

    def __exit__(self, exc_type, exc, exc_tb):
        logging.info('Exiting: %s', self.name)

Las instancias de esta clase se pueden usar como un gestor de contexto:

with track_entry_and_exit('widget loader'):
    print('Some time consuming activity goes here')
    load_widget()

Y también como decorador de funciones:

@track_entry_and_exit('widget loader')
def activity():
    print('Some time consuming activity goes here')
    load_widget()

Tenga en cuenta que hay una limitación adicional cuando se usan administradores de contexto como decoradores de funciones: no hay forma de acceder al valor de retorno de __enter__(). Si se necesita ese valor, aún es necesario usar una declaración explícita with.

Ver también

PEP 343 [https://www.python.org/dev/peps/pep-0343] - La declaración «with»

La especificación, antecedentes y ejemplos de la declaración de Python with.

Gestores de contexto de uso único, reutilizables y reentrantes

La mayoría de los gestores de contexto están escritos de una manera que significa que solo se pueden usar de manera efectiva en una declaración with una vez. Estos administradores de contexto de un solo uso deben crearse de nuevo cada vez que se usan; si intenta usarlos por segunda vez, se activará una excepción o, de lo contrario, no funcionará correctamente.

Esta limitación común significa que generalmente es aconsejable crear gestores de contexto directamente en el encabezado de la palabra clave with donde se usan (como se muestra en todos los ejemplos de uso anteriores).

Los archivos son un ejemplo de gestores de contexto de un solo uso, ya que la primera with cerrará el archivo, evitando cualquier otra operación de E/S que use ese objeto de archivo.

Los gestores de contexto creados usando contextmanager() también son gestores de contexto de un solo uso, y se quejarán de la falla del generador subyacente si se intenta usarlos por segunda vez:

>>> from contextlib import contextmanager
>>> @contextmanager
... def singleuse():
...     print("Before")
...     yield
...     print("After")
...
>>> cm = singleuse()
>>> with cm:
...     pass
...
Before
After
>>> with cm:
...     pass
...
Traceback (most recent call last):
    ...
RuntimeError: generator didn't yield

Gestores contextuales reentrantes

Los gestores de contexto más sofisticados pueden ser «reentrantes». Estos administradores de contexto no solo se pueden usar en múltiples declaraciones with, sino que también se pueden usar inside a with que ya está usando el mismo gestor de contexto.

threading.RLock es un ejemplo de un administrador de contexto reentrante, como son suppress() y redirect_stdout(). Aquí hay un ejemplo muy simple de uso reentrante:

>>> from contextlib import redirect_stdout
>>> from io import StringIO
>>> stream = StringIO()
>>> write_to_stream = redirect_stdout(stream)
>>> with write_to_stream:
...     print("This is written to the stream rather than stdout")
...     with write_to_stream:
...         print("This is also written to the stream")
...
>>> print("This is written directly to stdout")
This is written directly to stdout
>>> print(stream.getvalue())
This is written to the stream rather than stdout
This is also written to the stream

Es más probable que los ejemplos del mundo real de reentrada impliquen múltiples funciones que se llaman entre sí y, por lo tanto, sean mucho más complicadas que este ejemplo.

Tenga en cuenta también que ser reentrante no es lo mismo que ser seguro para subprocesos. redirect_stdout(), por ejemplo, definitivamente no es seguro para subprocesos, ya que realiza una modificación global al estado del sistema al vincular sys.stdout a una secuencia diferente.

Gestores contextuales reutilizables

Distintos de los administradores de contexto de uso único y reentrante son los administradores de contexto «reutilizables» (o, para ser completamente explícitos, los administradores de contexto «reutilizables, pero no reentrantes», ya que los administradores de contexto reentrantes también son reutilizables). Estos administradores de contexto admiten que se usen varias veces, pero fallarán (o de lo contrario no funcionarán correctamente) si la instancia específica del administrador de contexto ya se ha utilizado en una declaración que contiene.

threading.Lock es un ejemplo de un gestor de contexto reutilizable, pero no reentrante (para un bloqueo reentrante, es necesario usar threading.RLock en su lugar).

Otro ejemplo de un administrador de contexto reutilizable, pero no reentrante es ExitStack, ya que invoca all las retrollamadas registradas actualmente al dejar cualquier con declaración, independientemente de dónde se agregaron esas retrollamadas:

>>> from contextlib import ExitStack
>>> stack = ExitStack()
>>> with stack:
...     stack.callback(print, "Callback: from first context")
...     print("Leaving first context")
...
Leaving first context
Callback: from first context
>>> with stack:
...     stack.callback(print, "Callback: from second context")
...     print("Leaving second context")
...
Leaving second context
Callback: from second context
>>> with stack:
...     stack.callback(print, "Callback: from outer context")
...     with stack:
...         stack.callback(print, "Callback: from inner context")
...         print("Leaving inner context")
...     print("Leaving outer context")
...
Leaving inner context
Callback: from inner context
Callback: from outer context
Leaving outer context

Como muestra el resultado del ejemplo, la reutilización de un solo objeto de pila en múltiples con declaraciones funciona correctamente, pero intentar anidarlos hará que la pila se borre al final de la declaración más interna, lo que es poco probable que sea un comportamiento deseable.

El uso de instancias separadas ExitStack en lugar de reutilizar una sola instancia evita ese problema:

>>> from contextlib import ExitStack
>>> with ExitStack() as outer_stack:
...     outer_stack.callback(print, "Callback: from outer context")
...     with ExitStack() as inner_stack:
...         inner_stack.callback(print, "Callback: from inner context")
...         print("Leaving inner context")
...     print("Leaving outer context")
...
Leaving inner context
Callback: from inner context
Leaving outer context
Callback: from outer context

abc — Clases de Base Abstracta

Código fuente: Lib/abc.py [https://github.com/python/cpython/tree/3.9/Lib/abc.py]

Este módulo proporciona la infraestructura para definir clases de base abstracta (CBAs) en Python, como se describe en PEP 3119 [https://www.python.org/dev/peps/pep-3119]; consulte en el PEP el porqué fue agregado a Python. (Véase también PEP 3141 [https://www.python.org/dev/peps/pep-3141] y el módulo numbers con respecto a una jerarquía de tipos para números basados en CBAs.)

El módulo collections tiene algunas clases concretas que se derivan de ABC; estos, por supuesto, pueden derivarse más. Además, el submódulo collections.abc tiene algunos ABC que se pueden usar para probar si una clase o instancia proporciona una interfaz en particular, por ejemplo, si es hash o si es un mapeo.

Este módulo provee la metaclase ABCMeta para definir CBAs y una clase auxiliar ABC para definir CBAs alternativamente a través de herencia:

class abc.ABC

Una clase auxiliar que tiene una ABCMeta como su metaclase. Con esta clase, una clase de base abstracta puede ser creada simplemente derivándola desde ABC evitando el uso de metaclases algunas veces confusos, por ejemplo:

from abc import ABC

class MyABC(ABC):
    pass

Tenga en cuenta que el tipo de ABC sigue siendo ABCMeta, por lo tanto, heredar de ABC requiere las precauciones habituales con respecto al uso de metaclases, ya que la herencia múltiple puede dar lugar a conflictos de metaclases. También se puede definir una clase base abstracta pasando la palabra clave metaclase y usando ABCMeta directamente, por ejemplo:

from abc import ABCMeta

class MyABC(metaclass=ABCMeta):
    pass

Nuevo en la versión 3.4.

class abc.ABCMeta

Metaclases para definir Clases de Base Abstracta (CBAs).

Utilice esta metaclase para crear una CBA. Una CBA puede ser heredada directamente y así, actuar como una clase mixta. También se puede registrar clases concretas no relacionadas (incluso clases integradas) y CBAs no relacionadas como «subclases virtuales» – estas y sus descendientes serán consideradas subclases del CBA registrado por la función integrada issubclass(), pero la CBA registrada no aparecerá en su MRO (Orden de Resolución de Métodos) ni las implementaciones de método definidas por la CBA registrada serán invocables (ni siquiera a través de super()). 1

Las clases creadas con una metaclase de ABCMeta tienen el siguiente método:

register(subclass)

Registre la subclase como una «subclase virtual» de esta CBA. Por ejemplo:

from abc import ABC

class MyABC(ABC):
    pass

MyABC.register(tuple)

assert issubclass(tuple, MyABC)
assert isinstance((), MyABC)

Distinto en la versión 3.3: Retorna la subclase registrada, para permitir su uso como decorador de clase.

Distinto en la versión 3.4: Para detectar llamadas a register(), se puede usar la función get_cache_token().

También se puede redefinir este método en una clase de base abstracta:

__subclasshook__(subclass)

(Debe ser definido como un método de clase.)

Compruebe si la subclase se considera una subclase de esta CBA. Esto significa que puede personalizar aún más el comportamiento de issubclass sin necesidad de llamar a register() en cada clase que desee considerar una subclase de la CBA. (Este método de clase es llamado desde el método __subclasscheck__() del CBA.)

Este método debe retornar True, False o NotImplemented. Si retorna True, la subclase se considera una subclase de esta CBA. Si retorna False, la subclase no se considera una subclase de esta CBA, incluso si normalmente fuese una. Si retorna NotImplemented, la comprobación de subclase se continúa con el mecanismo usual.

Para una demostración de estos conceptos, vea este ejemplo de la definición CBA:

class Foo:
    def __getitem__(self, index):
        ...
    def __len__(self):
        ...
    def get_iterator(self):
        return iter(self)

class MyIterable(ABC):

    @abstractmethod
    def __iter__(self):
        while False:
            yield None

    def get_iterator(self):
        return self.__iter__()

    @classmethod
    def __subclasshook__(cls, C):
        if cls is MyIterable:
            if any("__iter__" in B.__dict__ for B in C.__mro__):
                return True
        return NotImplemented

MyIterable.register(Foo)

La CBA MyIterable define el método iterable estándar, __iter__(), como un método abstracto. La implementación dada aquí aún se puede llamar desde subclases. El método get_iterator() también forma parte de la clase de base abstracta MyIterable, pero no tiene que ser reemplazado en clases derivadas no abstractas.

El método de la clase __subclasshook__() definido aquí dice que cualquier clase que tenga un método __iter__() en su __dict__ (o en la de una de sus clases base, a la que se accede a través de la lista __mro__) también se considera un MyIterable.

Por último, la última línea convierte Foo en una subclase virtual de MyIterable, aunque no define un método __iter__() (utiliza el protocolo iterable al estilo antiguo, definido en términos de __len__() y __getitem__()). Tenga en cuenta que esto no hará que get_iterator esté disponible como un método de Foo, por lo que es proporcionado por separado.

El módulo abc también proporciona el siguiente decorador:

@abc.abstractmethod

Un decorador que indica métodos abstractos.

El uso de este decorador requiere que la metaclase de la clase sea ABCMeta o se derive de esta. Una clase que tiene una metaclase derivada de ABCMeta no puede ser instanciada, a menos que todas sus propiedades y métodos abstractos sean anulados. Los métodos abstractos se pueden invocar usando cualquiera de los mecanismos de “super” invocación normales. abstractmethod() se puede utilizar para declarar métodos abstractos para propiedades y descriptores.

No se admite la adición dinámica de métodos abstractos a una clase o el intento de modificar el estado de abstracción de un método o clase una vez creado. El abstractmethod() sólo afecta a las subclases derivadas mediante herencia regular; las «subclases virtuales» registradas con el método register() de CBAs no son afectadas.

Cuando abstractmethod() se aplica en combinación con otros descriptores de método, se debe aplicar como el decorador más interno, como se muestra en los siguientes ejemplos de uso:

class C(ABC):
    @abstractmethod
    def my_abstract_method(self, arg1):
        ...
    @classmethod
    @abstractmethod
    def my_abstract_classmethod(cls, arg2):
        ...
    @staticmethod
    @abstractmethod
    def my_abstract_staticmethod(arg3):
        ...

    @property
    @abstractmethod
    def my_abstract_property(self):
        ...
    @my_abstract_property.setter
    @abstractmethod
    def my_abstract_property(self, val):
        ...

    @abstractmethod
    def _get_x(self):
        ...
    @abstractmethod
    def _set_x(self, val):
        ...
    x = property(_get_x, _set_x)

Para interoperar correctamente con la maquinaria de clase de base abstracta, el descriptor debe identificarse como abstracto utilizando __isabstractmethod__. En general, este atributo debe ser True si alguno de los métodos utilizados para componer el descriptor es abstracto. Por ejemplo, la clase de propiedad integrada de Python property hace el equivalente de:

class Descriptor:
    ...
    @property
    def __isabstractmethod__(self):
        return any(getattr(f, '__isabstractmethod__', False) for
                   f in (self._fget, self._fset, self._fdel))

Nota

A diferencia de los métodos abstractos de Java, estos métodos abstractos pueden tener una implementación. Esta implementación se puede llamar a través del mecanismo super() de la clase que lo invalida. Esto podría ser útil como un end-point para una super llamada en un framework que use herencia múltiple cooperativa.

El módulo abc también es compatible con los siguientes decoradores heredados:

@abc.abstractclassmethod

Nuevo en la versión 3.2.

Obsoleto desde la versión 3.3: Ahora es posible utilizar classmethod con abstractmethod(), lo cual hace que este decorador sea redundante.

Una subclase de la classmethod() incorporada, indicando un método de clase abstracto. De otra forma, es similar a abstractmethod().

Este caso especial está obsoleto, ya que el decorador classmethod() ahora es identificado correctamente como abstracto cuando se aplica a un método abstracto:

class C(ABC):
    @classmethod
    @abstractmethod
    def my_abstract_classmethod(cls, arg):
        ...

@abc.abstractstaticmethod

Nuevo en la versión 3.2.

Obsoleto desde la versión 3.3: Ahora es posible utilizar staticmethod con abstractmethod(), haciendo que este decorador sea redundante.

Una subclase de la staticmethod() incorporada, indicando un método estático abstracto. De otra forma, es similar a abstractmethod().

Este caso especial está obsoleto, ya que el decorador staticmethod() ahora es identificado correctamente como abstracto cuando se aplica a un método abstracto:

class C(ABC):
    @staticmethod
    @abstractmethod
    def my_abstract_staticmethod(arg):
        ...

@abc.abstractproperty

Obsoleto desde la versión 3.3: Ahora es posible utilizar property, property.getter(), property.setter() y property.deleter() con abstractmethod(), lo cual hace que este decorador sea redundante.

Una subclase de la property() integrada, que indica una propiedad abstracta.

Este caso especial está obsoleto, ya que el decorador property() ahora es identificado correctamente como abstracto cuando es aplicado a un método abstracto:

class C(ABC):
    @property
    @abstractmethod
    def my_abstract_property(self):
        ...

En el ejemplo anterior se define una propiedad de solo lectura; también se puede definir una propiedad abstracta de lectura y escritura marcando adecuadamente uno o varios de los métodos subyacentes como abstractos:

class C(ABC):
    @property
    def x(self):
        ...

    @x.setter
    @abstractmethod
    def x(self, val):
        ...

Si solo algunos componentes son abstractos, solo estos componentes necesitan ser actualizados para crear una propiedad concreta en una subclase:

class D(C):
    @C.x.setter
    def x(self, val):
        ...

El módulo abc también proporciona las siguientes funciones:

abc.get_cache_token()

Retorna el token de caché de la clase base abstracta actual.

El token es un objeto opaco (que admite pruebas de igualdad) que identifica la versión actual de la caché de clases de base abstractas para subclases virtuales. El token cambia con cada llamada a ABCMeta.register() en cualquier CBA.

Nuevo en la versión 3.4.

Notas al pie

1

Los desarrolladores de C++ pueden notar que el concepto de clase base virtual de Python no es el mismo que en C++.

atexit — Gestores de Salida

El módulo atexit define funciones para registrar y cancelar el registro de las funciones de limpieza. Las funciones así registradas se ejecutan automáticamente cuando el intérprete se detiene normalmente. El módulo atexit realiza estas funciones en el orden inverso en el que se registraron; si ingresa A, B, y C, cuando el intérprete se detenga, se ejecutarán en el orden C, B, A.

Nota: Las funciones registradas a través de este módulo no se invocan cuando el programa es eliminado por una señal no gestionada por Python, cuando se detecta un error fatal interno en Python o cuando se llama a la función os._exit().

Distinto en la versión 3.7: Cuando se usan con sub-intérpretes API C, las funciones registradas son locales para el intérprete en el que se registraron.

atexit.register(func, *args, **kwargs)

Registra func como una función que se ejecutará cuando el intérprete se detenga. Cualquier argumento opcional que deba pasarse a func debe pasarse como un argumento para la función register(). Es posible registrar las mismas funciones y argumentos más de una vez.

En la finalización normal del programa (por ejemplo, si se llama a la función sys.exit() o finaliza la ejecución del módulo principal), todas las funciones registradas se invocan en el orden último en entrar, primero en salir. Se supone que los módulos de nivel más bajo normalmente se importarán antes que los módulos de nivel alto y, por lo tanto, se limpiarán al final.

If an exception is raised during execution of the exit handlers, a traceback is printed (unless SystemExit is raised) and the exception information is saved. After all exit handlers have had a chance to run, the last exception to be raised is re-raised.

Esta función retorna func, lo que hace posible usarlo como decorador.

atexit.unregister(func)

Remove func from the list of functions to be run at interpreter shutdown. unregister() silently does nothing if func was not previously registered. If func has been registered more than once, every occurrence of that function in the atexit call stack will be removed. Equality comparisons (==) are used internally during unregistration, so function references do not need to have matching identities.

Ver también

Módulo readline

Un ejemplo útil del uso de atexit para leer y escribir archivos de historial readline.

Ejemplo con atexit

El siguiente ejemplo simple muestra cómo un módulo puede inicializar un contador desde un archivo cuando se importa, y guardar el valor del contador actualizado automáticamente cuando finaliza el programa, sin necesidad de que la aplicación realice una llamada explícita en este módulo cuando el intérprete se detiene.

try:
    with open('counterfile') as infile:
        _count = int(infile.read())
except FileNotFoundError:
    _count = 0

def incrcounter(n):
    global _count
    _count = _count + n

def savecounter():
    with open('counterfile', 'w') as outfile:
        outfile.write('%d' % _count)

import atexit

atexit.register(savecounter)

Los argumentos posicionales y de palabras clave también se pueden pasar a register() para volver a pasar a la función registrada cuando se llama:

def goodbye(name, adjective):
    print('Goodbye %s, it was %s to meet you.' % (name, adjective))

import atexit

atexit.register(goodbye, 'Donny', 'nice')
# or:
atexit.register(goodbye, adjective='nice', name='Donny')

Usar como un decorator:

import atexit

@atexit.register
def goodbye():
    print('You are now leaving the Python sector.')

Esto solo funciona con funciones que se pueden invocar sin argumentos.

traceback — Imprimir o recuperar un seguimiento de pila

Código fuente: Lib/traceback.py [https://github.com/python/cpython/tree/3.9/Lib/traceback.py]

Este módulo brinda una interfaz estándar para extraer, formatear y mostrar trazas de pilas de programas de Python. Dicho módulo copia el comportamiento del intérprete de Python cuando muestra una traza de pila. Es útil a la hora de querer mostrar trazas de pilas bajo el control del programa, como si de un wrapper alrededor del intérprete se tratara.

El módulo utiliza objetos traceback — Este es el tipo de objeto que se almacena en la variable sys.last_traceback y es retornada como el tercer elemento de sys.exc_info().

El módulo define las siguientes funciones:

traceback.print_tb(tb, limit=None, file=None)

Muestra hasta limit entradas de trazas de pila desde el objeto traceback tb (empezando desde el marco de la llamada) si limit es positivo. De lo contrario, muestra las últimas abs(limit) entradas. Si limit es omitido o None, todas las entradas se muestran. Si file es omitido o None, la salida va a sys.stderr; de lo contrario, debería ser un archivo o un objeto de tipo similar a un archivo para recibir la salida.

Distinto en la versión 3.5: Soporte para limit negativo añadido

traceback.print_exception(etype, value, tb, limit=None, file=None, chain=True)

Muestra información de excepciones y entradas de trazas de pila desde el objeto traceback tb a file. Esto difiere de print_tb() de las siguientes maneras:

si tb no es None, muestra una cabecera Traceback (most recent call last):

muestra la excepción etype y value después de la traza de pila

si type(value) es SyntaxError y value tiene el formato apropiado, muestra la línea donde el error sintáctico ha ocurrido con un cursor indicando la posición aproximada del error.

El argumento opcional limit tiene el mismo significado que para print_tb(). Si chain es verdad (por defecto), entonces excepciones encadenadas (__cause__ o __context__ atributos de la excepción) también se imprimirán, como lo hace el propio intérprete al imprimir una excepción no controlada.

Distinto en la versión 3.5: El argumento etype es ignorado e infiere desde el tipo de value.

traceback.print_exc(limit=None, file=None, chain=True)

Esto es un atajo para print_exception(*sys.exc_info(), limit, file, chain).

traceback.print_last(limit=None, file=None, chain=True)

Esto es un atajo para print_exception(sys.last_type, sys.last_value, sys.last_traceback, limit, file, chain). En general, solo funciona después de que una excepción ha alcanzado un promt interactivo (ver sys.last_type).

traceback.print_stack(f=None, limit=None, file=None)

Muestra hasta limit entradas de trazas de pila (empezando desde el punto de invocación) si limit es positivo. De lo contrario, muestra las últimas abs(limit) entradas. Si limit es omitido o None, todas las entradas se muestran. El argumento opcional f puede ser usado para especificar un marco de pila alternativo para empezar. El argumento opcional file tiene el mismo significado que para print_tb().

Distinto en la versión 3.5: Soporte para limit negativo añadido

traceback.extract_tb(tb, limit=None)

Retorna un objeto StackSummary representando una lista de entradas de trazas de pila «pre-procesadas» extraídas del objeto traceback tb. Esto es útil para el formateo alternativo de trazas de pila. El argumento opcional limit tiene el mismo significado que para print_tb(). Una entrada de traza de pila «pre-procesada» es un objeto FrameSummary que contiene los atributos filename, lineno, name, y line representando la información que normalmente es mostrada por una traza de pila. El atributo line es una cadena con espacios en blanco iniciales y finales stripped; si la fuente no está disponible, es None.

traceback.extract_stack(f=None, limit=None)

Extrae el seguimiento de pila crudo desde el marco de pila actual. El valor retornado tiene el mismo formato que para extract_tb(). Los argumentos opcionales f y limit tienen el mismo significado que para print_stack().

traceback.format_list(extracted_list)

Dada una lista de tuplas u objetos FrameSummary según lo retornado por extract_tb() o extract_stack(), retorna una lista de cadenas preparadas para ser mostradas. Cada cadena en la lista resultante corresponde con el elemento con el mismo índice en la lista de argumentos. Cada cadena finaliza en una nueva línea; las cadenas pueden contener nuevas líneas internas también, para aquellos elementos cuya línea de texto de origen no es None.

traceback.format_exception_only(etype, value)

Formatea la parte de excepción de un seguimiento de pila. Los argumentos son el tipo de excepción y el valor como los dados por sys.last_type y sys.last_value. El valor retornado es una lista de cadenas, acabando cada una en una nueva línea. Normalmente, la lista contiene una sola cadena; sin embargo, para las excepciones SyntaxError, esta lista contiene múltiples líneas que (cuando se muestran), imprimen información detallada sobre dónde ha ocurrido el error sintáctico. El mensaje indicador de qué excepción ha ocurrido es siempre la última cadena de la lista.

traceback.format_exception(etype, value, tb, limit=None, chain=True)

Formatea una traza de pila y la información de la excepción. Los argumentos tienen el mismo significado que los argumentos correspondientes a print_exception(). El valor retornado es una lista de cadenas, acabando cada una en una nueva línea y algunas contienen nuevas líneas internas. Cuando estas líneas son concatenadas y mostradas, exactamente el mismo texto es mostrado como hace print_exception().

Distinto en la versión 3.5: El argumento etype es ignorado e infiere desde el tipo de value.

traceback.format_exc(limit=None, chain=True)

Esto es como print_exc(limit) pero retorna una cadena en lugar de imprimirlo en un archivo.

traceback.format_tb(tb, limit=None)

Un atajo para format_list(extract_tb(tb, limit)).

traceback.format_stack(f=None, limit=None)

Un atajo para format_list(extract_stack(f, limit)).

traceback.clear_frames(tb)

Limpia las variables locales de todos los marcos de pila en un seguimiento de pila tb llamando al método clear() de cada objeto de marco.

Nuevo en la versión 3.4.

traceback.walk_stack(f)

Recorre una pila siguiendo f.f_back desde el marco dado, produciendo el marco y el número de línea de cada marco. Si f es None, la pila actual es usada. Este auxiliar es usado con StackSummary.extract().

Nuevo en la versión 3.5.

traceback.walk_tb(tb)

Recorre un seguimiento de pila siguiendo tb_next produciendo el marco y el número de línea de cada marco. Este auxiliar es usado con StackSummary.extract().

Nuevo en la versión 3.5.

El módulo también define las siguientes clases:

Objetos TracebackException

Nuevo en la versión 3.5.

Los objetos TracebackException son creados a partir de excepciones reales para capturar datos para su posterior impresión de una manera ligera.

class traceback.TracebackException(exc_type, exc_value, exc_traceback, *, limit=None, lookup_lines=True, capture_locals=False)

Captura una excepción para su posterior procesado. limit, lookup_lines y capture_locals son como para la clase StackSummary.

Tenga en cuenta que cuando se capturan locales, también se muestran en el rastreo.

__cause__

Una clase TracebackException del original __cause__.

__context__

Una clase TracebackException del original __context__.

__suppress_context__

El valor __suppress_context__ de la excepción original.

stack

Una clase StackSummary representando el seguimiento de pila.

exc_type

La clase del seguimiento de pila original.

filename

Para errores sintácticos - el nombre del archivo donde el error ha ocurrido.

lineno

Para errores sintácticos - el número de línea donde el error ha ocurrido.

text

Para errores sintácticos - el texto donde el error ha ocurrido.

offset

Para errores sintácticos - el offset en el texto donde el error ha ocurrido.

msg

Para errores sintácticos - el mensaje de error del compilador.

classmethod from_exception(exc, *, limit=None, lookup_lines=True, capture_locals=False)

Captura una excepción para su posterior procesado. limit, lookup_lines y capture_locals son como para la clase StackSummary.

Tenga en cuenta que cuando se capturan locales, también se muestran en el rastreo.

format(*, chain=True)

Formatea la excepción.

Si chain no es True, __cause__ y __context__ no serán formateados.

El valor retornado es un generador de cadenas, donde cada una acaba en una nueva línea y algunas contienen nuevas líneas internas. print_exception() es un contenedor alrededor de este método que simplemente muestra las líneas de un archivo.

El mensaje que indica qué excepción ocurrió siempre es la última cadena en la salida.

format_exception_only()

Formatea la parte de la excepción de un seguimiento de pila.

El valor retornado es un generador de cadenas, donde cada una acaba en una nueva línea.

Normalmente, el generador emite una sola cadena, sin embargo, para excepciones SyntaxError, este emite múltiples líneas que (cuando son mostradas) imprimen información detallada sobre dónde ha ocurrido el error sintáctico.

El mensaje que indica qué excepción ocurrió siempre es la última cadena en la salida.

Objetos StackSummary

Nuevo en la versión 3.5.

Los objetos StackSummary representan una pila de llamadas lista para formatear.

class traceback.StackSummary

classmethod extract(frame_gen, *, limit=None, lookup_lines=True, capture_locals=False)

Construye un objeto StackSummary desde un generador de marcos (tal como es retornado por walk_stack() o walk_tb()).

Si limit es suministrado, solo esta cantidad de cuadros son tomados de frame_gen. Si lookup_lines es False, los objeto FrameSummary retornados aún no han leído sus líneas, lo que hace que el costo de crear StackSummary será más barato (lo que puede ser valioso si no se formatea). Si capture_locals es True, las variables locales en cada FrameSummary son capturadas como representaciones de objetos.

classmethod from_list(a_list)

Construye un objeto StackSummary desde una lista suministrada de objetos FrameSummary o una lista antigua de tuplas. Cada tupa debe ser una 4-tupla con nombre de archivo, número de líneas, nombre, línea como los elementos.

format()

Retorna una lista de cadenas lista para mostrarse. Cada cadena en la lista resultante corresponde a un único marco de la pila. Cada cadena termina en una nueva línea;las cadenas también pueden contener nuevas líneas internas, para aquellos elementos con líneas de texto fuente.

Para secuencias largas del mismo marco y línea, se muestran las primeras repeticiones, seguidas de una línea de resumen que indica el número exacto de repeticiones adicionales.

Distinto en la versión 3.6: Las secuencias largas de cuadros repetidos ahora se abrevian.

Objetos FrameSummary

Nuevo en la versión 3.5.

Los objetos FrameSummary representan un único marco en el seguimiento de pila.

class traceback.FrameSummary(filename, lineno, name, lookup_line=True, locals=None, line=None)

Representa un único marco en el seguimiento de pila o pila que es formateado o mostrado. Opcionalmente, puede tener una versión en cadena de los marcos locales incluidos en él. Si lookup_line es False, el código fuente no se busca hasta que FrameSummary tenga el atributo line accedido (lo que también sucede cuando lo conviertes en una tupla). line puede proporcionarse directamente y evitará que se realicen búsquedas de línea. locals es un diccionario de variables locales opcional y, si se proporciona, las representaciones de variables se almacenan en el resumen para su posterior visualización.

Ejemplos de seguimiento de pila

Este ejemplo sencillo implementa un bucle de lectura, evaluación e impresión básico, similar a (pero menos útil) el bucle del intérprete interactivo estándar de Python. Para una implementación más completa del bucle del intérprete, ir al módulo code

import sys, traceback

def run_user_code(envdir):
    source = input(">>> ")
    try:
        exec(source, envdir)
    except Exception:
        print("Exception in user code:")
        print("-"*60)
        traceback.print_exc(file=sys.stdout)
        print("-"*60)

envdir = {}
while True:
    run_user_code(envdir)

El siguiente ejemplo demuestra las diferentes manera para mostrar y formatear la excepción y el seguimiento de pila:

import sys, traceback

def lumberjack():
    bright_side_of_death()

def bright_side_of_death():
    return tuple()[0]

try:
    lumberjack()
except IndexError:
    exc_type, exc_value, exc_traceback = sys.exc_info()
    print("*** print_tb:")
    traceback.print_tb(exc_traceback, limit=1, file=sys.stdout)
    print("*** print_exception:")
    # exc_type below is ignored on 3.5 and later
    traceback.print_exception(exc_type, exc_value, exc_traceback,
                              limit=2, file=sys.stdout)
    print("*** print_exc:")
    traceback.print_exc(limit=2, file=sys.stdout)
    print("*** format_exc, first and last line:")
    formatted_lines = traceback.format_exc().splitlines()
    print(formatted_lines[0])
    print(formatted_lines[-1])
    print("*** format_exception:")
    # exc_type below is ignored on 3.5 and later
    print(repr(traceback.format_exception(exc_type, exc_value,
                                          exc_traceback)))
    print("*** extract_tb:")
    print(repr(traceback.extract_tb(exc_traceback)))
    print("*** format_tb:")
    print(repr(traceback.format_tb(exc_traceback)))
    print("*** tb_lineno:", exc_traceback.tb_lineno)

La salida para el ejemplo podría ser similar a esto:

*** print_tb:
  File "<doctest...>", line 10, in <module>
    lumberjack()
*** print_exception:
Traceback (most recent call last):
  File "<doctest...>", line 10, in <module>
    lumberjack()
  File "<doctest...>", line 4, in lumberjack
    bright_side_of_death()
IndexError: tuple index out of range
*** print_exc:
Traceback (most recent call last):
  File "<doctest...>", line 10, in <module>
    lumberjack()
  File "<doctest...>", line 4, in lumberjack
    bright_side_of_death()
IndexError: tuple index out of range
*** format_exc, first and last line:
Traceback (most recent call last):
IndexError: tuple index out of range
*** format_exception:
['Traceback (most recent call last):\n',
 '  File "<doctest...>", line 10, in <module>\n    lumberjack()\n',
 '  File "<doctest...>", line 4, in lumberjack\n    bright_side_of_death()\n',
 '  File "<doctest...>", line 7, in bright_side_of_death\n    return tuple()[0]\n',
 'IndexError: tuple index out of range\n']
*** extract_tb:
[<FrameSummary file <doctest...>, line 10 in <module>>,
 <FrameSummary file <doctest...>, line 4 in lumberjack>,
 <FrameSummary file <doctest...>, line 7 in bright_side_of_death>]
*** format_tb:
['  File "<doctest...>", line 10, in <module>\n    lumberjack()\n',
 '  File "<doctest...>", line 4, in lumberjack\n    bright_side_of_death()\n',
 '  File "<doctest...>", line 7, in bright_side_of_death\n    return tuple()[0]\n']
*** tb_lineno: 10

El siguiente ejemplo muestra las diferentes maneras de imprimir y formatear la pila:

>>> import traceback
>>> def another_function():
...     lumberstack()
...
>>> def lumberstack():
...     traceback.print_stack()
...     print(repr(traceback.extract_stack()))
...     print(repr(traceback.format_stack()))
...
>>> another_function()
  File "<doctest>", line 10, in <module>
    another_function()
  File "<doctest>", line 3, in another_function
    lumberstack()
  File "<doctest>", line 6, in lumberstack
    traceback.print_stack()
[('<doctest>', 10, '<module>', 'another_function()'),
 ('<doctest>', 3, 'another_function', 'lumberstack()'),
 ('<doctest>', 7, 'lumberstack', 'print(repr(traceback.extract_stack()))')]
['  File "<doctest>", line 10, in <module>\n    another_function()\n',
 '  File "<doctest>", line 3, in another_function\n    lumberstack()\n',
 '  File "<doctest>", line 8, in lumberstack\n    print(repr(traceback.format_stack()))\n']

Este último ejemplo demuestra las últimas funciones de formateo:

>>> import traceback
>>> traceback.format_list([('spam.py', 3, '<module>', 'spam.eggs()'),
...                        ('eggs.py', 42, 'eggs', 'return "bacon"')])
['  File "spam.py", line 3, in <module>\n    spam.eggs()\n',
 '  File "eggs.py", line 42, in eggs\n    return "bacon"\n']
>>> an_error = IndexError('tuple index out of range')
>>> traceback.format_exception_only(type(an_error), an_error)
['IndexError: tuple index out of range\n']

__future__ — Definiciones de declaraciones futuras

Código fuente: Lib/__future__.py [https://github.com/python/cpython/tree/3.9/Lib/__future__.py]

__future__ es un módulo real y tiene tres propósitos:

Para evitar confundir las herramientas existentes que analizan las declaraciones de importación y esperan encontrar los módulos que están importando.

Para garantizar que las declaraciones futuras se ejecuten en versiones anteriores a 2.1 al menos produzcan excepciones en tiempo de ejecución (la importación de __future__ fallará, porque no había ningún módulo con ese nombre antes de 2.1).

Documentar cuándo se introdujeron cambios incompatibles y cuándo serán — o fueron — obligatorios. Esta es una forma de documentación ejecutable y se puede inspeccionar mediante programación importando __future__ y examinando su contenido.

Cada declaración en __future__.py tiene la forma:

FeatureName = _Feature(OptionalRelease, MandatoryRelease,
                       CompilerFlag)

donde, normalmente, OptionalRelease es menor que MandatoryRelease y ambos son 5-tuplas de la misma forma que sys.version_info:

(PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int
 PY_MINOR_VERSION, # the 1; an int
 PY_MICRO_VERSION, # the 0; an int
 PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string
 PY_RELEASE_SERIAL # the 3; an int
)

OptionalRelease registra la primera versión en la que se aceptó la característica.

En el caso de un MandatoryRelease que aún no se ha producido, MandatoryRelease predice el lanzamiento en el que la característica pasará a formar parte del lenguaje.

De otro modo, MandatoryRelease registra cuándo la característica se convirtió en parte del lenguaje; en versiones en o después de este, los módulos ya no necesitan una declaración futura para usar la característica en cuestión, pero pueden continuar usando dichas importaciones.

MandatoryRelease también puede ser None, lo que significa que se eliminó una característica planificada.

Las instancias de la clase _Feature tienen dos métodos correspondientes, getOptionalRelease() y getMandatoryRelease().

CompilerFlag es el indicador (campo de bits) que debe pasarse en el cuarto argumento a la función incorporada compile() para habilitar la característica en código compilado dinámicamente. Esta bandera se almacena en el atributo compiler_flag en las instancias _Feature.

Ninguna descripción de característica se eliminará de __future__. Desde su introducción en Python 2.1, las siguientes características han encontrado su camino en el lenguaje usando este mecanismo:

característica

opcional en

obligatorio en

efecto

nested_scopes

2.1.0b1

2.2

PEP 227 [https://www.python.org/dev/peps/pep-0227]: Ámbitos anidados estáticamente

generadores

2.2.0a1

2.3

PEP 255 [https://www.python.org/dev/peps/pep-0255]: Generadores simples

división

2.2.0a2

3.0

PEP 238 [https://www.python.org/dev/peps/pep-0238]: Cambio de operador de división

absolute_import

2.5.0a1

3.0

PEP 328 [https://www.python.org/dev/peps/pep-0328]: Importaciones: Multilínea y Absoluto/Relativo

with_statement

2.5.0a1

2.6

PEP 343 [https://www.python.org/dev/peps/pep-0343]: La declaración «with»

print_function

2.6.0a2

3.0

PEP 3105 [https://www.python.org/dev/peps/pep-3105]: Hacer de print una función

unicode_literals

2.6.0a2

3.0

PEP 3112 [https://www.python.org/dev/peps/pep-3112]: Bytes literales en Python 3000

generator_stop

3.5.0b1

3.7

PEP 479 [https://www.python.org/dev/peps/pep-0479]: Manejo de StopIteration dentro de generadores

anotaciones

3.7.0b1

TBD 1

PEP 563 [https://www.python.org/dev/peps/pep-0563]: Evaluación pospuesta de anotaciones

1

from __future__ import annotations was previously scheduled to become mandatory in Python 3.10, but the Python Steering Council twice decided to delay the change (announcement for Python 3.10 [https://mail.python.org/archives/list/python-dev@python.org/message/CLVXXPQ2T2LQ5MP2Y53VVQFCXYWQJHKZ/]; announcement for Python 3.11 [https://mail.python.org/archives/list/python-dev@python.org/message/VIZEBX5EYMSYIJNDBF6DMUMZOCWHARSO/]). No final decision has been made yet. See also PEP 563 [https://www.python.org/dev/peps/pep-0563] and PEP 649 [https://www.python.org/dev/peps/pep-0649].

Ver también

Declaraciones Futuras

Cómo trata el compilador las importaciones futuras.

gc — Interfaz del recolector de basura

Este módulo proporciona una interfaz para el recolector de basura opcional (recolector de basura cíclico generacional). Proporciona la capacidad de deshabilitar el recolector, ajustar la frecuencia de recolección y establecer opciones de depuración. También proporciona acceso a objetos inaccesibles (unreachables) que el recolector encontró pero no pudo liberar. Dado que el recolector de basura complementa el conteo de referencias, que ya se utiliza en Python, es posible desactivarlo siempre que se esté seguro de que el programa no crea referencias cíclicas. La recolección automática se puede desactivar llamando a gc.disable(). Para depurar un programa con fugas de memoria, se debe llamar a gc.set_debug(gc.DEBUG_LEAK). Se debe tener en cuenta que la llamada anterior incluye gc.DEBUG_SAVEALL, lo que hace que los objetos recolectados se guarden en gc.garbage para su inspección.

El módulo gc proporciona las siguientes funciones:

gc.enable()

Habilita la recolección automática de basura.

gc.disable()

Deshabilita la recolección automática de basura.

gc.isenabled()

Retorna True si la recolección automática está habilitada.

gc.collect(generation=2)

Sin argumentos, ejecuta una recolección completa. El argumento opcional generation debe ser un número entero que especifica qué generación recolectar (de 0 a 2). Una excepción ValueError será lanzada si el número de generación no es válido. Se retorna el número de objetos inaccesibles encontrados.

Las listas libres mantenidas para varios tipos incorporados son borradas cada vez que se ejecuta una recolección completa o una recolección de la generación más alta (2). No obstante, no todos los elementos de algunas listas libres pueden ser liberados, particularmente float, debido a su implementación particular.

gc.set_debug(flags)

Establece las flags de depuración para la recolección de basura. La información de depuración se escribirá en sys.stderr. A continuación se puede consultar una lista con las flags de depuración disponibles, que se pueden combinar mediante operaciones de bits para controlar la depuración.

gc.get_debug()

Retorna las flags de depuración actualmente establecidas.

gc.get_objects(generation=None)

Retorna una lista de todos los objetos rastreados por el recolector, excluyendo la lista retornada. Si generation no es None, retorna solo los objetos rastreados por el recolector que pertenecen a esa generación.

Distinto en la versión 3.8: Se agregó el parámetro generation.

Lanza un evento de auditoría gc.get_objects con el argumento generation.

gc.get_stats()

Retorna una lista de tres diccionarios, uno por cada generación, que contienen estadísticas de recolección desde el inicio del intérprete. El número de claves puede cambiar en el futuro, pero actualmente cada diccionario contendrá los siguientes elementos:

collections es el número de veces que se recolectó esta generación;

collected es el número total de objetos recolectados dentro de esta generación;

uncollectable es el número total de objetos que se consideraron no recolectables (y por lo tanto, se movieron a la lista garbage) dentro de esta generación.

Nuevo en la versión 3.4.

gc.set_threshold(threshold0[, threshold1[, threshold2]])

Establece los umbrales de recolección (la frecuencia de recolección). Si se establece threshold0 en cero se deshabilita la recolección.

El recolector de basura (GC por sus siglas en inglés) clasifica los objetos en tres generaciones dependiendo de cuántos barridos de colección hayan sobrevivido. Los nuevos objetos se colocan en la generación más joven (generación 0). Si un objeto sobrevive a una colección, se traslada a la siguiente generación anterior. Dado que la generación 2 es la generación más antigua, los objetos de esa generación permanecen allí después de una colección. Para decidir cuándo ejecutar, el recopilador realiza un seguimiento del número de asignaciones y desasignaciones de objetos desde la última recopilación. Cuando el número de asignaciones menos el número de desasignaciones supera el treshold0, comienza la recopilación. Inicialmente solo se examina la generación 0. Si la generación 0 se ha examinado más de treshold1 veces desde que se examinó la generación 1, también se examina la generación 1. Con la tercera generación, las cosas son un poco más complicadas, consulte Recopilación de la generación más antigua [https://devguide.python.org/garbage_collector/#collecting-the-oldest-generation] para obtener más información.

gc.get_count()

Retorna los recuentos de la recolección actual como una tupla de la forma (count0, count1, count2).

gc.get_threshold()

Retorna los umbrales de la recolección actual como una tupla de la forma (threshold0, threshold1, threshold2).

gc.get_referrers(*objs)

Retorna la lista de objetos que referencian de forma directa a cualquiera de objs. Esta función solo localizará aquellos contenedores que admitan la recolección de basura; no se localizarán los tipos de extensión que referencian a otros objetos pero que no admiten la recolección de basura.

Téngase en cuenta que los objetos que ya se han desreferenciado, pero que tienen referencias cíclicas y aún no han sido recolectados por el recolector de basura pueden enumerarse entre las referencias resultantes. Para obtener solo los objetos activos actualmente, llame a collect() antes de llamar a get_referrers().

Advertencia

Se debe tener un especial cuidado cuando se usan objetos retornados por get_referrers() dado que algunos de ellos aún podrían estar en construcción y por tanto en un estado temporalmente inválido. Debe evitarse el uso de get_referrers() para cualquier propósito que no sea la depuración.

Lanza un evento de auditoría gc.get_referrers con el argumento objs.

gc.get_referents(*objs)

Retorna una lista de objetos a los que hace referencia directamente cualquiera de los argumentos. Las referencias retornadas son aquellos objetos visitados por los métodos tp_traverse a nivel de C de los argumentos (si los hay) y es posible que no todos los objetos sean directamente accesibles realmente. Los métodos tp_traverse solo son compatibles con los objetos que admiten recolección de basura y solo se requieren para visitar objetos que pueden estar involucrados en un ciclo de referencias. Lo que quiere decir que, por ejemplo, si se puede acceder directamente a un número entero desde uno de los argumento, ese objeto entero puede aparecer o no en la lista de resultados.

Lanza un evento de auditoría gc.get_referents con el argumento objs.

gc.is_tracked(obj)

Retorna True si el recolector de basura rastrea actualmente el objeto y False en caso contrario. Como regla general, las instancias de tipos atómicos no se rastrean y las instancias de tipos no atómicos (contenedores, objetos definidos por el usuario …) sí. Sin embargo, algunas optimizaciones específicas de tipo pueden estar presentes para suprimir el impacto del recolector de basura en instancias simples (por ejemplo, diccionarios que contienen solo claves y valores atómicos):

>>> gc.is_tracked(0)
False
>>> gc.is_tracked("a")
False
>>> gc.is_tracked([])
True
>>> gc.is_tracked({})
False
>>> gc.is_tracked({"a": 1})
False
>>> gc.is_tracked({"a": []})
True

Nuevo en la versión 3.1.

gc.is_finalized(obj)

Retorna True si el objeto dado ha sido finalizado por el recolector de basura, False en caso contrario.

>>> x = None
>>> class Lazarus:
...     def __del__(self):
...         global x
...         x = self
...
>>> lazarus = Lazarus()
>>> gc.is_finalized(lazarus)
False
>>> del lazarus
>>> gc.is_finalized(x)
True

Nuevo en la versión 3.9.

gc.freeze()

Congela todos los objetos rastreados por el recolector de basura - los mueve a una generación permanente e ignora todas las recolecciones futuras. Esto se puede usar antes de una llamada a fork() de POSIX para hacer el recolector de basura amigable con copy-on-write («copiar al escribir») o para acelerar la recolección. Además, la recolección antes de una llamada fork() de POSIX puede liberar páginas para futuras asignaciones, lo que también puede causar copy-on-write, por lo que se recomienda deshabilitar el recolector de basura en el proceso principal, congelar antes de la bifurcación y habilitarlo posteriormente en el proceso secundario.

Nuevo en la versión 3.7.

gc.unfreeze()

Descongela los objetos de la generación permanente y vuelve a colocarlos en la generación más antigua.

Nuevo en la versión 3.7.

gc.get_freeze_count()

Retorna el número de objetos de la generación permanente.

Nuevo en la versión 3.7.

Las siguientes variables se proporcionan para acceso de solo lectura (se pueden mutar los valores pero no se deben vincular de nuevo):

gc.garbage

Una lista de objetos que el recolector consideró inaccesibles pero que no pudieron ser liberados (objetos que no se pueden recolectar). A partir de Python 3.4, esta lista debe estar vacía la mayor parte del tiempo, excepto cuando se utilizan instancias de tipos de extensión C en los que la ranura (slot) tp_del no sea NULL.

Si se establece DEBUG_SAVEALL, todos los objetos inaccesibles se agregarán a esta lista en lugar de ser liberados.

Distinto en la versión 3.2: Si la lista no está vacía en el momento del interpreter shutdown, se emite un ResourceWarning, que es silencioso de forma predeterminada. Si se establece DEBUG_UNCOLLECTABLE, además se imprimen todos los objetos no recolectables.

Distinto en la versión 3.4: Cumpliendo con PEP 442 [https://www.python.org/dev/peps/pep-0442], los objetos con un método __del__() ya no terminan en gc.garbage.

gc.callbacks

Una lista de retrollamadas que el recolector de basura invocará antes y después de la recolección. Las retrollamadas serán llamadas con dos argumentos, phase e info.

phase puede tomar uno de estos valores:

«start»: la recolección de basura está a punto de comenzar.

«stop»: la recolección de basura ha terminado.

info es un diccionario que proporciona información adicional para la retrollamada. Las siguientes claves están definidas actualmente:

«generation»: la generación más antigua que ha sido recolectada.

«collected»: cuando phase es «stop», el número de objetos recolectados satisfactoriamente.

«uncollectable»: cuando phase es «stop», el número de objetos que no pudieron ser recolectados y fueron ubicados en garbage.

Las aplicaciones pueden agregar sus propias retrollamadas a esta lista. Los principales casos de uso son:

Recopilar estadísticas sobre la recolección de basura, como la frecuencia con la que se recolectan varias generaciones y cuánto tiempo lleva la recolección.

Permitir que las aplicaciones identifiquen y borren sus propios tipos no recolectables cuando aparecen en garbage.

Nuevo en la versión 3.3.

Las siguientes constantes son proporcionadas para ser usadas con set_debug():

gc.DEBUG_STATS

Imprime estadísticas durante la recolección. Esta información puede resultar útil para ajustar la frecuencia de recolección.

gc.DEBUG_COLLECTABLE

Imprime información sobre los objetos recolectables encontrados.

gc.DEBUG_UNCOLLECTABLE

Imprime información sobre los objetos no recolectables encontrados (objetos inaccesibles, pero que el recolector no puede liberar). Estos objetos se agregarán a la lista garbage.

Distinto en la versión 3.2: También imprime el contenido de la lista garbage durante interpreter shutdown, si no está vacía.

gc.DEBUG_SAVEALL

Cuando se establece, todos los objetos inaccesibles encontrados se agregarán a garbage en lugar de ser liberados. Esto puede resultar útil para depurar un programa con fugas de memoria.

gc.DEBUG_LEAK

Las flags de depuración necesarias para que el recolector imprima información sobre un programa con fugas de memoria (igual a DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE | DEBUG_SAVEALL).

inspect — Inspeccionar objetos vivos

Código fuente: Lib/inspect.py [https://github.com/python/cpython/tree/3.9/Lib/inspect.py]

El módulo inspect proporciona varias funciones útiles para ayudar a obtener información sobre objetos vivos como módulos, clases, métodos, funciones, tracebacks, objetos de marco y objetos de código. Por ejemplo, puede ayudarte a examinar el contenido de una clase, recuperar el código fuente de un método, extraer y dar formato a la lista de argumentos de una función, u obtener toda la información que necesitas para mostrar un traceback detallado.

Hay cuatro tipos principales de servicios que ofrece este módulo: comprobación de tipos, obtención del código fuente, inspección de clases y funciones, y examinar la pila del intérprete.

Tipos y miembros

La función getmembers() recupera los miembros de un objeto como una clase o un módulo. Las funciones cuyos nombres comienzan con «is» se proveen principalmente como opciones convenientes para el segundo argumento de getmembers(). También ayudan a determinar cuándo se puede esperar encontrar los siguientes atributos especiales:

Tipo

Atributo

Descripción

módulo

__doc__

cadena de caracteres de documentación

__file__

nombre de archivo (falta para los módulos incorporados)

clase

__doc__

cadena de caracteres de documentación

__name__

nombre con el que se definió esta clase

__qualname__

nombre calificado

__module__

nombre del módulo en el que se definió esta clase

método

__doc__

cadena de caracteres de documentación

__name__

nombre con el que se definió este método

__qualname__

nombre calificado

__func__

objeto función que contiene la implementación del método

__self__

instancia a la que este método está ligado, o None

__module__

nombre del módulo en el cual este método fue definido

función

__doc__

cadena de caracteres de documentación

__name__

nombre con el que se definió esta función

__qualname__

nombre calificado

__code__

objeto de código que contiene la función compilada bytecode

__defaults__

tupla de cualquier valor por defecto para los parámetros de posición o de palabras clave

__kwdefaults__

mapeo de cualquier valor predeterminado para parámetros de sólo palabras clave

__globals__

namespace global en el que se definió esta función

__annotations__

mapeo de los nombres de parámetros a las anotaciones; la tecla "return" está reservada para las anotaciones de retorno.

__module__

nombre del módulo en el cual esta función fue definida

traceback

tb_frame

enmarcar el objeto a este nivel

tb_lasti

índice del último intento de instrucción en código de bytes

tb_lineno

número de línea actual en el código fuente de Python

tb_next

el siguiente objeto de traceback interno (llamado por este nivel)

marco

f_back

el siguiente objeto exterior del marco (el que llama a este marco)

f_builtins

construye el namespace visto por este marco

f_code

objeto de código que se ejecuta en este marco

f_globals

el namespace global visto por este marco

f_lasti

índice del último intento de instrucción en código de bytes

f_lineno

número de línea actual en el código fuente de Python

f_locals

el namespace local visto por este marco

f_trace

función de rastreo para este marco, o None

code

co_argcount

número de argumentos (sin incluir los argumentos de palabras clave, * o ** args)

co_code

cadena de bytecode compilados en bruto

co_cellvars

tupla de nombres de variables de celda (referenciados por contener alcances)

co_consts

tupla de constantes utilizadas en el bytecode

co_filename

nombre del archivo en el que este objeto código fue creado

co_firstlineno

número de la primera línea del código fuente de Python

co_flags

mapa de bits de los flags CO_*, leer más aquí

co_lnotab

mapeo codificado de los números de línea a los índices de bytecode

co_freevars

tupla de nombres de variables libres (referenciados a través del cierre de una función)

co_posonlyargcount

número de argumentos solo posicionales

co_kwonlyargcount

número de argumentos de sólo palabras clave (sin incluir el ** arg)

co_name

nombre con el que se definió este objeto de código

co_names

tupla de nombres de variables locales

co_nlocals

número de variables locales

co_stacksize

se requiere espacio en la pila de máquina virtual

co_varnames

tupla de nombres de argumentos y variables locales

generador

__name__

nombre

__qualname__

nombre calificado

gi_frame

marco

gi_running

¿Está el generador en ejecución?

gi_code

code

gi_yieldfrom

el objeto siendo iterado por yield from, o None

corutina

__name__

nombre

__qualname__

nombre calificado

cr_await

objeto al que se espera, o None

cr_frame

marco

cr_running

¿Está la corutina en ejecución?

cr_code

code

cr_origin

donde se creó la corutina, o None. Ver sys.set_coroutine_origin_tracking_depth()

incorporado

__doc__

cadena de caracteres de documentación

__name__

nombre original de esta función o método

__qualname__

nombre calificado

__self__

instancia a la que está ligada un método, o None

Distinto en la versión 3.5: Agrega atributos __qualname__ y gi_yieldfrom a los generadores.

El atributo __name__ de los generadores se establece ahora a partir del nombre de la función, en lugar del nombre del código, y ahora puede ser modificado.

Distinto en la versión 3.7: Agrega el atributo cr_origin a las corutinas.

inspect.getmembers(object[, predicate])

Retorna todos los miembros de un objeto en una lista de pares (name, value) ordenados por nombre. Si se proporciona el argumento predicate opcional, que se llamará con el objeto value de cada miembro, solo se incluyen los miembros para los que el predicado retorna un valor verdadero.

Nota

getmembers() sólo retornará los atributos de clase definidos en la metaclase cuando el argumento sea una clase y esos atributos hayan sido listados en la costumbre de la metaclase __dir__().

inspect.getmodulename(path)

Retorna el nombre del módulo nombrado por el ruta de archivo, sin incluir los nombres de los paquetes adjuntos. La extensión del archivo se comprueba con todas las entradas en importlib.machinery.all_suffixes(). Si coincide, el componente final de la ruta se retorna con la extensión eliminada. En caso contrario, se retorna None.

Ten en cuenta que esta función sólo retorna un nombre significativo para los módulos reales de Python - las rutas que potencialmente se refieren a los paquetes de Python seguirán retornando None.

Distinto en la versión 3.3: La función se basa directamente en importlib.

inspect.ismodule(object)

Retorna True si el objeto es un módulo.

inspect.isclass(object)

Retorna True si el objeto es una clase, ya sea incorporada o creada en código Python.

inspect.ismethod(object)

Retorna True si el objeto es un método ligado escrito en Python.

inspect.isfunction(object)

Retorna True si el objeto es una función de Python, que incluye funciones creadas por una expresión lambda.

inspect.isgeneratorfunction(object)

Retorna True si el objeto es una función generadora de Python.

Distinto en la versión 3.8: Funciones envueltas en functools.partial() ahora retornan True si la función envuelta es una función Python generadora.

inspect.isgenerator(object)

Retorna True si el objeto es un generador.

inspect.iscoroutinefunction(object)

Retorna True si el objeto es una coroutine function (una función definida con una sintaxis async def).

Nuevo en la versión 3.5.

Distinto en la versión 3.8: Funciones envueltas en functools.partial() ahora retornan True si la función envuelta es un coroutine function.

inspect.iscoroutine(object)

Retorna verdadero si el objeto es un coroutine creado por una función async def.

Nuevo en la versión 3.5.

inspect.isawaitable(object)

Retorna True si el objeto puede ser usado en la expresión await.

También se puede utilizar para distinguir las corutinas basadas en generadores de los generadores normales:

def gen():
    yield
@types.coroutine
def gen_coro():
    yield

assert not isawaitable(gen())
assert isawaitable(gen_coro())

Nuevo en la versión 3.5.

inspect.isasyncgenfunction(object)

Retorna True si el objeto es una función asynchronous generator, por ejemplo:

>>> async def agen():
...     yield 1
...
>>> inspect.isasyncgenfunction(agen)
True

Nuevo en la versión 3.6.

Distinto en la versión 3.8: Funciones envueltas en functools.partial() ahora retornan True si la función envuelta es una función asynchronous generator.

inspect.isasyncgen(object)

Retorna verdadero si el objeto es un asynchronous generator iterator creado por una función asynchronous generator.

Nuevo en la versión 3.6.

inspect.istraceback(object)

Retorna True si el objeto es un traceback.

inspect.isframe(object)

Retorna True si el objeto es un marco.

inspect.iscode(object)

Retorna True si el objeto es un código.

inspect.isbuiltin(object)

Retorna True si el objeto es una función incorporada o un método ligado incorporado.

inspect.isroutine(object)

Retorna True si el objeto es una función o método definido por el usuario o incorporado.

inspect.isabstract(object)

Retorna True si el objeto es una clase base abstracta.

inspect.ismethoddescriptor(object)

Retorna True si el objeto es un descriptor de método, pero no si ismethod(), isclass(), isfunction() o isbuiltin() son verdaderos.

Esto, por ejemplo, es cierto para int.__add__. Un objeto que pasa esta prueba tiene un método __get__() pero no un método __set__(), pero más allá de eso el conjunto de atributos varía. Un atributo __name__ suele ser sensato, y __doc__ a menudo lo es.

Los métodos implementados a través de descriptores que también pasan una de las otras pruebas retornan False a la prueba ismethoddescriptor(), simplemente porque las otras pruebas prometen más – puede, por ejemplo, contar con tener el atributo __func__ (etc) cuando un objeto pasa ismethod().

inspect.isdatadescriptor(object)

Retorna True si el objeto es un descriptor de datos.

Los descriptores de datos tienen un método __set__ o un método __delete__. Los ejemplos son propiedades (definidas en Python), conjuntos y miembros. Los dos últimos están definidos en C y hay pruebas más específicas disponibles para esos tipos, lo cual es robusto en todas las implementaciones de Python. Típicamente, los descriptores de datos también tendrán los atributos __name__ y __doc__ (las propiedades, conjuntos y miembros tienen ambos atributos), pero esto no está garantizado.

inspect.isgetsetdescriptor(object)

Retorna True si el objeto es un descriptor de conjunto.

CPython implementation detail: conjuntos son atributos definidos en módulos de extensión a través de estructuras PyGetSetDef. Para implementaciones de Python sin tales tipos, este método siempre retornará False.

inspect.ismemberdescriptor(object)

Retorna True si el objeto es un descriptor de miembro.

CPython implementation detail: Los descriptores de miembros son atributos definidos en los módulos de extensión a través de las estructuras PyMemberDef. Para implementaciones de Python sin tales tipos, este método siempre retornará False.

Recuperar el código fuente

inspect.getdoc(object)

Obtener la cadena de documentación de un objeto, limpiado con cleandoc(). Si no se proporciona la cadena de documentación de un objeto y el objeto es una clase, un método, una propiedad o un descriptor, recupera la cadena de documentación de la jerarquía de la herencia.

Distinto en la versión 3.5: Las cadenas de documentación son ahora heredadas, si no anuladas.

inspect.getcomments(object)

Retorna en una sola cadena las líneas de comentarios que preceden inmediatamente al código fuente del objeto (para una clase, función o método), o en la parte superior del archivo fuente de Python (si el objeto es un módulo). Si el código fuente del objeto no está disponible, retorna None. Esto podría suceder si el objeto ha sido definido en C o en el shell interactivo.

inspect.getfile(object)

Retorna el nombre del archivo (de texto o binario) en el que se definió un objeto. Esto fallará con un TypeError si el objeto es un módulo, clase o función incorporada.

inspect.getmodule(object)

Intenta adivinar en qué módulo se definió un objeto.

inspect.getsourcefile(object)

Retorna el nombre del archivo fuente de Python en el que se definió un objeto. Esto fallará con un TypeError si el objeto es un módulo, clase o función incorporada.

inspect.getsourcelines(object)

Retorna una lista de líneas de origen y el número de línea de inicio de un objeto. El argumento puede ser un objeto módulo, clase, método, función, traceback, marco o código. El código fuente es retornado como una lista de las líneas correspondientes al objeto y el número de línea que indica dónde se encontró la primera línea de código en el archivo fuente original. Un OSError es lanzado si el código fuente no puede ser recuperado.

Distinto en la versión 3.3: OSError se eleva en lugar de IOError, ahora un alias del primero.

inspect.getsource(object)

Retorna el texto del código fuente de un objeto. El argumento puede ser un objeto de módulo, clase, método, función, rastreo, marco o código. El código fuente se retorna como una sola cadena. Un OSError es lanzado si el código fuente no puede ser recuperado.

Distinto en la versión 3.3: OSError se eleva en lugar de IOError, ahora un alias del primero.

inspect.cleandoc(doc)

Limpiar la indentación de los docstrings que están indentados para alinearse con los bloques de código.

Todos los espacios blancos principales se eliminan de la primera línea. Cualquier espacio blanco principal que pueda ser uniformemente removido de la segunda línea en adelante es removido. Las líneas vacías al principio y al final se eliminan posteriormente. Además, todas las pestañas se expanden a los espacios.

Introspección de los invocables con el objeto Signature

Nuevo en la versión 3.3.

El objeto Signature representa la firma de llamada de un objeto invocable y su anotación de retorno. Para recuperar un objeto Signature, utilice la función signature().

inspect.signature(callable, *, follow_wrapped=True)

Retorna un objeto Signature para el callable dado:

>>> from inspect import signature
>>> def foo(a, *, b:int, **kwargs):
...     pass

>>> sig = signature(foo)

>>> str(sig)
'(a, *, b:int, **kwargs)'

>>> str(sig.parameters['b'])
'b:int'

>>> sig.parameters['b'].annotation
<class 'int'>

Acepta un amplio rango de invocables de Python, desde funciones y clases simples hasta objetos functools.partial().

Lanza ValueError si no se puede proporcionar un signature, y TypeError si ese tipo de objeto no es soportado.

Una barra (/) en la signature de una función denota que los parámetros anteriores a ella son sólo posicionales. Para más información, ver la pregunta frecuente en parámetros solo posicionales.

Nuevo en la versión 3.5: parámetro follow_wrapped. Pasa False para obtener un signature de callable específicamente (callable.__wrapped__ no se usará para desenvolver los invocables decorados.)

Nota

Algunos invocables pueden no ser introspeccionables en ciertas implementaciones de Python. Por ejemplo, en CPython, algunas funciones incorporadas definidas en C no proporcionan metadatos sobre sus argumentos.

class inspect.Signature(parameters=None, *, return_annotation=Signature.empty)

Un objeto Signature representa la firma de llamada de una función y su anotación de retorno. Por cada parámetro aceptado por la función, almacena un objeto Parameter en su colección parameters.

El argumento opcional parámetros es una secuencia de objetos Parameter, que se valida para comprobar que no hay parámetros con nombres duplicados, y que los parámetros están en el orden correcto, es decir, primero sólo de posición, luego de posición o palabra clave, y que los parámetros con valores por defecto siguen a los parámetros sin valores por defecto.

El argumento opcional return_annotation, puede ser un objeto Python arbitrario, es la anotación «return» del invocable.

Los objetos signature son inmutables. Usar Signature.replace() para hacer una copia modificada.

Distinto en la versión 3.5: Los objetos Signature se pueden seleccionar y se pueden manipular.

empty

Un marcador especial de clase para especificar la ausencia de una anotación de retorno.

parameters

Un mapeo ordenado de los nombres de los parámetros a los correspondientes objetos Parameter. Los parámetros aparecen en estricto orden de definición, incluyendo parámetros de sólo palabras clave.

Distinto en la versión 3.7: Python sólo garantizó explícitamente que conservaba el orden de declaración de los parámetros de sólo palabras clave a partir de la versión 3.7, aunque en la práctica este orden siempre se había conservado en Python 3.

return_annotation

La anotación de «retorno» para el invocable. Si el invocable no tiene ninguna anotación de «return», este atributo se establece en Signature.empty.

bind(*args, **kwargs)

Crear un mapeo de argumentos posicionales y de palabras clave a los parámetros. Retorna BoundArguments si *args y **kwargs coinciden con el signature, o lanza un TypeError.

bind_partial(*args, **kwargs)

Funciona de la misma manera que Signature.bind(), pero permite la omisión de algunos argumentos requeridos (imita el comportamiento de functools.partial().) Retorna BoundArguments, o lanza un TypeError si los argumentos pasados no coinciden con la firma.

replace(*[, parameters][, return_annotation])

Crear una nueva instancia Signature basada en la instancia sobre la que se invocó el reemplazo. Es posible pasar diferentes parámetros y/o return_annotation para sobreescribir las propiedades correspondientes de la firma base. Para eliminar return_annotation del Signature copiado, pasar en Signature.empty.

>>> def test(a, b):
...     pass
>>> sig = signature(test)
>>> new_sig = sig.replace(return_annotation="new return anno")
>>> str(new_sig)
"(a, b) -> 'new return anno'"

classmethod from_callable(obj, *, follow_wrapped=True)

Retorna un objeto Signature (o su subclase) para un determinado obj invocable. Pasa follow_wrapped=False para obtener una firma de obj sin desenvolver su cadena __wrapped__.

Este método simplifica la subclasificación de Signature:

class MySignature(Signature):
    pass
sig = MySignature.from_callable(min)
assert isinstance(sig, MySignature)

Nuevo en la versión 3.5.

class inspect.Parameter(name, kind, *, default=Parameter.empty, annotation=Parameter.empty)

Los objetos parámetros son inmutables. En lugar de modificar un objeto Parámetro, puedes usar Parameter.replace() para crear una copia modificada.

Distinto en la versión 3.5: Los objetos Parámetro se pueden seleccionar y manipular.

empty

Un marcador especial de clase para especificar la ausencia de valores predeterminados y anotaciones.

name

El nombre del parámetro como una cadena. El nombre debe ser un identificador Python válido.

CPython implementation detail: CPython genera nombres de parámetros implícitos de la forma .0 en los objetos de código utilizados para implementar expresiones de comprensiones y generadores.

Distinto en la versión 3.6: Los nombres de estos parámetros son expuestos por este módulo como nombres como implicit0.

default

El valor por defecto del parámetro. Si el parámetro no tiene un valor por defecto, este atributo se establece en Parameter.empty.

annotation

La anotación para el parámetro. Si el parámetro no tiene ninguna anotación, este atributo se establece como Parameter.empty.

kind

Describe cómo los valores de los argumentos están vinculados al parámetro. Valores posibles (accesibles a través de Parameter, como Parameter.KEYWORD_ONLY):

Nombre

Significado

POSITIONAL_ONLY

El valor debe proporcionarse como un argumento posicional. Los parámetros solo posicionales son aquellos que aparecen antes de una entrada / (si está presente) en una definición de función de Python. aceptan sólo uno o dos parámetros) los aceptan.

POSITIONAL_OR_KEYWORD

El valor puede ser suministrado como una palabra clave o como un argumento posicional (este es el comportamiento estándar de unión para las funciones implementadas en Python)

VAR_POSITIONAL

Una tupla de argumentos posicionales que no están ligados a ningún otro parámetro. Esto corresponde a un parámetro *args en una definición de función Python.

KEYWORD_ONLY

El valor debe ser suministrado como argumento de la palabra clave. Los parámetros de sólo palabras clave son los que aparecen después de una entrada * o *args en una definición de función Python.

VAR_KEYWORD

Un dictado de argumentos de palabras clave que no están ligadas a ningún otro parámetro. Esto corresponde a un parámetro **kwargs en una definición de función Python.

Ejemplo: imprimir todos los argumentos de sólo palabras clave sin valores por defecto:

>>> def foo(a, b, *, c, d=10):
...     pass

>>> sig = signature(foo)
>>> for param in sig.parameters.values():
...     if (param.kind == param.KEYWORD_ONLY and
...                        param.default is param.empty):
...         print('Parameter:', param)
Parameter: c

kind.description

Describe un valor enum como Parameter.kind.

Nuevo en la versión 3.8.

Ejemplo: imprimir todas las descripciones de los argumentos:

>>> def foo(a, b, *, c, d=10):
...     pass

>>> sig = signature(foo)
>>> for param in sig.parameters.values():
...     print(param.kind.description)
positional or keyword
positional or keyword
keyword-only
keyword-only

replace(*[, name][, kind][, default][, annotation])

Crear una nueva instancia de parámetros basada en la instancia en la que se invocó la sustitución. Para anular un atributo Parameter, pasa el argumento correspondiente. Para eliminar un valor por defecto y/o una anotación de un parámetro, pasa Parameter.empty.

>>> from inspect import Parameter
>>> param = Parameter('foo', Parameter.KEYWORD_ONLY, default=42)
>>> str(param)
'foo=42'

>>> str(param.replace()) # Will create a shallow copy of 'param'
'foo=42'

>>> str(param.replace(default=Parameter.empty, annotation='spam'))
"foo:'spam'"

Distinto en la versión 3.4: En Python 3.3 se permitía que los objetos Parámetro tuvieran el name puesto en None si su kind estaba puesto en POSITIONAL_ONLY. Esto ya no está permitido.

class inspect.BoundArguments

Resultado de una llamada Signature.bind() o Signature.bind_partial(). Mantiene el mapeo de los argumentos a los parámetros de la función.

arguments

Un mapeo mutable de los nombres de los parámetros a los valores de los argumentos. Contiene solo argumentos vinculados explícitamente. Los cambios en arguments se reflejarán en args y kwargs.

Debe ser usado en conjunto con Signature.parameters para cualquier propósito de procesamiento de argumentos.

Nota

Los argumentos para los cuales Signature.bind() o Signature.bind_partial() se basaban en un valor por defecto se saltan. Sin embargo, si es necesario, use BoundArguments.apply_defaults() para añadirlos.

Distinto en la versión 3.9: arguments ahora es de tipo dict. Anteriormente, era de tipo collections.OrderedDict.

args

Una tupla de valores de argumentos posicionales. Calculados dinámicamente a partir del atributo arguments.

kwargs

Un diccionario de valores de argumentos de palabras clave. Calculados dinámicamente a partir del atributo arguments.

signature

Una referencia al objeto padre Signature.

apply_defaults()

Establece valores por defecto para los argumentos que faltan.

Para los argumentos de posición variable (*args) el valor por defecto es una tupla vacía.

Para los argumentos de palabras clave variables (**kwargs) el valor por defecto es un diccionario vacío.

>>> def foo(a, b='ham', *args): pass
>>> ba = inspect.signature(foo).bind('spam')
>>> ba.apply_defaults()
>>> ba.arguments
{'a': 'spam', 'b': 'ham', 'args': ()}

Nuevo en la versión 3.5.

Las propiedades args y kwargs pueden ser usadas para invocar funciones:

def test(a, *, b):
    ...

sig = signature(test)
ba = sig.bind(10, b=20)
test(*ba.args, **ba.kwargs)

Ver también

PEP 362 [https://www.python.org/dev/peps/pep-0362] - Función Objeto Signature.

La especificación detallada, los detalles de implementación y los ejemplos.

Clases y funciones

inspect.getclasstree(classes, unique=False)

Organizar la lista de clases dada en una jerarquía de listas anidadas. Cuando aparece una lista anidada, contiene clases derivadas de la clase cuya entrada precede inmediatamente a la lista. Cada entrada es una tupla de 2 valores que contienen una clase y una tupla de sus clases base. Si el argumento unique es cierto, aparece exactamente una entrada en la estructura retornada para cada clase de la lista dada. De lo contrario, las clases que utilizan la herencia múltiple y sus descendientes aparecerán varias veces.

inspect.getargspec(func)

Obtener los nombres y valores por defecto de los parámetros de una función de Python. A named tuple ArgSpec(args, varargs, keywords, defaults) es retornado. args es una lista de los nombres de los parámetros. varargs y keywords son los nombres de los parámetros * y ** o None. defaults es una tupla de valores de los argumentos por defecto o None si no hay argumentos por defecto; si esta tupla tiene n elementos, corresponden a los últimos n elementos listados en args.

Obsoleto desde la versión 3.0: Use getfullargspec() para una API actualizada que suele ser un sustituto de la que no se necesita, pero que también maneja correctamente las anotaciones de la función y los parámetros de sólo palabras clave.

Alternativamente, use signature() y Objeto Signature, que proporcionan una API de introspección más estructurada para los invocables.

inspect.getfullargspec(func)

Obtener los nombres y valores por defecto de los parámetros de una función de Python. Se retorna un named tuple:

FullArgSpec(args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations)

args es una lista de los nombres de los parámetros posicionales. varargs es el nombre del parámetro * o None si no se aceptan argumentos posicionales arbitrarios. varkw es el nombre del parámetro ** o None si no se aceptan argumentos de palabras clave arbitrarias. defaults es una n-tupla de valores de argumentos por defecto que corresponden a los últimos parámetros de posición n, o None si no hay tales valores por defecto definidos. kwonlyargs es una lista de nombres de parámetros de sólo palabras clave en orden de declaración. kwonlydefaults es un diccionario que asigna los nombres de los parámetros de kwonlyargs a los valores por defecto utilizados si no se suministra ningún argumento. annotations es un diccionario que asigna los nombres de los parámetros a las anotaciones. La tecla especial "return" se utiliza para informar de la anotación del valor de retorno de la función (si existe).

Observe que signature() y Objeto Signature proporcionan la API recomendada para la introspección invocable, y soportan comportamientos adicionales (como los argumentos de sólo posición) que a veces se encuentran en las API de los módulos de extensión. Esta función se conserva principalmente para su uso en el código que necesita mantener la compatibilidad con la API de módulos de inspect de Python 2.

Distinto en la versión 3.4: Esta función se basa ahora en signature(), pero sigue ignorando los atributos __wrapped__ e incluye el primer parámetro ya ligado en la salida del signature para los métodos ligados.

Distinto en la versión 3.6: Este método fue documentado anteriormente como obsoleto en favor de signature() en Python 3.5, pero esa decisión ha sido revocada para restaurar una interfaz estándar claramente soportada para el código de una sola fuente en Python 2/3 que se aleja de la API heredada getargspec().

Distinto en la versión 3.7: Python sólo garantizó explícitamente que conservaba el orden de declaración de los parámetros de sólo palabras clave a partir de la versión 3.7, aunque en la práctica este orden siempre se había conservado en Python 3.

inspect.getargvalues(frame)

Obtener información sobre los argumentos pasados en un marco particular. Un named tuple ArgInfo(args, varargs, keywords, locals) es retornado. args es una lista de los nombres de los argumentos. varargs y keywords son los nombres de los argumentos *` y ``** o None. locals es el diccionario local del marco dado.

Nota

Esta función fue inadvertidamente marcada como obsoleta en Python 3.5.

inspect.formatargspec(args[, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations[, formatarg, formatvarargs, formatvarkw, formatvalue, formatreturns, formatannotations]])

Formatea un bonito argumento de los valores retornados por getfullargspec().

Los primeros siete argumentos son (args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations).

Los otros seis argumentos son funciones que se llaman para convertir los nombres de los argumentos, el nombre del argumento *, el nombre del argumento **, los valores por defecto, la anotación de retorno y las anotaciones individuales en cadenas, respectivamente.

Por ejemplo:

>>> from inspect import formatargspec, getfullargspec
>>> def f(a: int, b: float):
...     pass
...
>>> formatargspec(*getfullargspec(f))
'(a: int, b: float)'

Obsoleto desde la versión 3.5: Usar signature() y Objeto Signature, que proporcionan un mejor API de introspección para los invocables.

inspect.formatargvalues(args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue])

Formatea una bonita especificación de argumentos de los cuatro valores retornados por getargvalues(). Los argumentos de formato* son las correspondientes funciones de formato opcionales que se llaman para convertir nombres y valores en cadenas.

Nota

Esta función fue inadvertidamente marcada como obsoleta en Python 3.5.

inspect.getmro(cls)

Retorna una tupla de clases base de cls, incluyendo cls, en orden de resolución de métodos. Ninguna clase aparece más de una vez en esta tupla. Obsérvese que el orden de resolución de los métodos depende del tipo de cls. A menos que se utilice un meta tipo muy peculiar definido por el usuario, cls será el primer elemento de la tupla.

inspect.getcallargs(func, /, *args, **kwds)

Ata los args y kwds a los nombres de los argumentos de la función o método func de Python, como si se llamara con ellos. Para los métodos ligados, liga también el primer argumento (típicamente llamado self) a la instancia asociada. Se retorna un diccionario, mapeando los nombres de los argumentos (incluyendo los nombres de los argumentos * y **, si los hay) a sus valores de args y kwds. En caso de invocar func incorrectamente, es decir, siempre que func(*args, **kwds) plantee una excepción por firma incompatible, se plantea una excepción del mismo tipo y del mismo o similar mensaje. Por ejemplo:

>>> from inspect import getcallargs
>>> def f(a, b=1, *pos, **named):
...     pass
>>> getcallargs(f, 1, 2, 3) == {'a': 1, 'named': {}, 'b': 2, 'pos': (3,)}
True
>>> getcallargs(f, a=2, x=4) == {'a': 2, 'named': {'x': 4}, 'b': 1, 'pos': ()}
True
>>> getcallargs(f)
Traceback (most recent call last):
...
TypeError: f() missing 1 required positional argument: 'a'

Nuevo en la versión 3.2.

Obsoleto desde la versión 3.5: Usa Signature.bind() y Signature.bind_partial() en su lugar.

inspect.getclosurevars(func)

Obtener el mapeo de referencias de nombres externos en una función o método func de Python a sus valores actuales. Un named tuple ClosureVars(nonlocals, globals, builtins, unbound) es retornado. nonlocals asigna los nombres referidos a las variables de cierre léxicas, globals a los globals de los módulos de la función y builtins a los builtins visibles desde el cuerpo de la función. unbound es el conjunto de nombres referenciados en la función que no pudieron ser resueltos en absoluto dados los actuales globals y builtins del módulo.

TypeError es lanzado si func no es una función o método de Python.

Nuevo en la versión 3.3.

inspect.unwrap(func, *, stop=None)

Obtiene el objeto envuelto por func. Sigue la cadena de atributos __wrapped__ retornando el último objeto de la cadena.

stop es una retrollamada opcional que acepta un objeto de la cadena envuelta como único argumento que permite terminar el desenvolvimiento antes de tiempo si la retrollamada retorna un valor real. Si la retrollamada nunca retorna un valor verdadero, el último objeto de la cadena se retorna como de costumbre. Por ejemplo, signature() utiliza esto para detener el desenvolvimiento si algún objeto de la cadena tiene definido el atributo __signature__.

ValueError es lanzado si se encuentra un ciclo.

Nuevo en la versión 3.4.

La pila del interprete

Cuando las siguientes funciones retornan «registros de cuadro», cada registro es un named tuple FrameInfo(frame, filename, lineno, function, code_context, index). La tupla contiene el objeto marco, el nombre de archivo, el número de línea de la línea actual, el nombre de la función, una lista de líneas de contexto del código fuente, y el índice de la línea actual dentro de esa lista.

Distinto en la versión 3.5: Retorna una tupla con nombre en lugar de una tupla.

Nota

Mantener referencias a los objetos marco, como se encuentra en el primer elemento de los registros marco que estas funciones retornan, puede hacer que su programa cree ciclos de referencia. Una vez creado un ciclo de referencia, la vida útil de todos los objetos a los que se puede acceder desde los objetos que forman el ciclo puede ser mucho mayor, incluso si el detector de ciclos opcional de Python está activado. Si es necesario crear tales ciclos, es importante asegurarse de que se rompen explícitamente para evitar la destrucción retardada de los objetos y el aumento del consumo de memoria que se produce.

Aunque el detector de ciclos los captará, la destrucción de los marcos (y las variables locales) puede hacerse determinísticamente eliminando el ciclo en una cláusula de finally. Esto también es importante si el detector de ciclos fue desactivado cuando se compiló Python o usando gc.disable(). Por ejemplo:

def handle_stackframe_without_leak():
    frame = inspect.currentframe()
    try:
        # do something with the frame
    finally:
        del frame

Si quieres mantener el marco alrededor (por ejemplo para imprimir una traceback más tarde), también puedes romper los ciclos de referencia utilizando el método frame.clear().

El argumento opcional de context, apoyado por la mayoría de estas funciones, especifica el número de líneas de contexto a retornar, que se centran en la línea actual.

inspect.getframeinfo(frame, context=1)

Obtener información sobre un marco o un objeto de traceback. Un named tuple Traceback(filename, lineno, function, code_context, index) es retornado.

inspect.getouterframes(frame, context=1)

Obtener una lista de registros marco para un marco y de todos los marcos exteriores. Estos marcos representan las llamadas que conducen a la creación de frame. La primera entrada de la lista retornada representa frame; la última entrada representa la llamada más exterior en la pila de frame.

Distinto en la versión 3.5: Una lista de named tuples FrameInfo(frame, filename, lineno, function, code_context, index) es retornada.

inspect.getinnerframes(traceback, context=1)

Consigue una lista de registros de marcos para un marco de traceback y todos los marcos internos. Estos marcos representan llamadas hechas como consecuencia de frame. La primera entrada de la lista representa traceback; la última entrada representa donde se lanzó la excepción.

Distinto en la versión 3.5: Una lista de named tuples FrameInfo(frame, filename, lineno, function, code_context, index) es retornada.

inspect.currentframe()

Retorna el objeto marco para el marco de la pila del que llama.

CPython implementation detail: Esta función se basa en el soporte del marco de la pila de Python en el intérprete, que no está garantizado que exista en todas las implementaciones de Python. Si se ejecuta en una implementación sin soporte de marcos de pila de Python, esta función retorna None.

inspect.stack(context=1)

Retorna una lista de registros de marco para la pila del que llama. La primera entrada de la lista retornada representa al que llama; la última entrada representa la llamada más exterior de la pila.

Distinto en la versión 3.5: Una lista de named tuples FrameInfo(frame, filename, lineno, function, code_context, index) es retornada.

inspect.trace(context=1)

Retorna una lista de registros de marco para la pila entre el marco actual y el marco en la que se lanzó una excepción que se está manejando actualmente. La primera entrada de la lista representa al que llama; la última entrada representa el lugar donde se lanzó la excepción.

Distinto en la versión 3.5: Una lista de named tuples FrameInfo(frame, filename, lineno, function, code_context, index) es retornada.

Obteniendo atributos estáticamente

Tanto getattr() como hasattr() pueden desencadenar la ejecución del código al buscar o comprobar la existencia de atributos. Los descriptores, como las propiedades, serán invocados y se podrá llamar a __getattr__() y __getattribute__().

Para los casos en los que se quiera una introspección pasiva, como las herramientas de documentación, esto puede ser un inconveniente. getattr_static() tiene la misma firma que getattr() pero evita la ejecución de código cuando obtiene atributos.

inspect.getattr_static(obj, attr, default=None)

Recuperar los atributos sin activar la búsqueda dinámica a través del protocolo descriptor, __getattr__() o __getattribute__().

Nota: es posible que esta función no pueda recuperar todos los atributos que getattr puede recuperar (como los atributos creados dinámicamente) y puede encontrar atributos que getattr no puede (como los descriptores que lanzan AttributeError). También puede retornar objetos descriptores en lugar de miembros de la instancia.

Si la instancia __dict__ es ensombrecida por otro miembro (por ejemplo una propiedad) entonces esta función no podrá encontrar miembros de la instancia.

Nuevo en la versión 3.2.

getattr_static() no resuelve los descriptores, por ejemplo los descriptores de ranura o los descriptores de getset en los objetos implementados en C. El objeto descriptor se retorna en lugar del atributo subyacente.

Puedes manejar esto con un código como el siguiente. Tenga en cuenta que la invocación de los descriptores de getset arbitrarios pueden desencadenar la ejecución del código:

# example code for resolving the builtin descriptor types
class _foo:
    __slots__ = ['foo']

slot_descriptor = type(_foo.foo)
getset_descriptor = type(type(open(__file__)).name)
wrapper_descriptor = type(str.__dict__['__add__'])
descriptor_types = (slot_descriptor, getset_descriptor, wrapper_descriptor)

result = getattr_static(some_object, 'foo')
if type(result) in descriptor_types:
    try:
        result = result.__get__()
    except AttributeError:
        # descriptors can raise AttributeError to
        # indicate there is no underlying value
        # in which case the descriptor itself will
        # have to do
        pass

Estado actual de los Generadores y las Corutinas

Al implementar los programadores de corutinas y para otros usos avanzados de los generadores, es útil determinar si un generador se está ejecutando actualmente, si está esperando para iniciarse o reanudarse o si ya ha terminado. getgeneratorstate() permite determinar fácilmente el estado actual de un generador.

inspect.getgeneratorstate(generator)

Obtener el estado actual de un generador-iterador.

Los posibles estados son:

GEN_CREATED: Esperando para iniciar la ejecución.

GEN_RUNNING: Actualmente está siendo ejecutado por el intérprete.

GEN_SUSPENDED: Actualmente suspendido en una expresión yield.

GEN_CLOSED: La ejecución se ha completado.

Nuevo en la versión 3.2.

inspect.getcoroutinestate(coroutine)

Obtener el estado actual de un objeto de corutina. La función está pensada para ser usada con objetos de corutina creados por las funciones async def, pero aceptará cualquier objeto de corutina que tenga los atributos cr_running y cr_frame.

Los posibles estados son:

CORO_CREATED: Esperando para iniciar la ejecución.

CORO_RUNNING: Actualmente está siendo ejecutado por el intérprete.

CORO_SUSPENDED: Actualmente suspendido en una expresión de espera.

CORO_CLOSED: La ejecución se ha completado.

Nuevo en la versión 3.5.

También se puede consultar el estado interno actual del generador. Esto es mayormente útil para fines de prueba, para asegurar que el estado interno se actualiza como se espera:

inspect.getgeneratorlocals(generator)

Consigue el mapeo de las variables vivas locales en generator a sus valores actuales. Se retorna un diccionario que mapea de los nombres de las variables a los valores. Esto es el equivalente a llamar locals() en el cuerpo del generador, y se aplican todas las mismas advertencias.

Si generator es un generator sin marco asociado actualmente, entonces se retorna un diccionario vacío. TypeError es lanzado si generator no es un objeto generador de Python.

CPython implementation detail: Esta función se basa en que el generador exponga un marco de pila de Python para la introspección, lo cual no está garantizado en todas las implementaciones de Python. En tales casos, esta función siempre retornará un diccionario vacío.

Nuevo en la versión 3.3.

inspect.getcoroutinelocals(coroutine)

Esta función es análoga a getgeneratorlocals(), pero funciona para los objetos de corutina creados por funciones async def.

Nuevo en la versión 3.5.

Objetos de código Bit Flags

Los objetos de código Python tienen un atributo co_flags, que es un mapa de bits de los siguientes flags:

inspect.CO_OPTIMIZED

El objeto del código está optimizado, usando locales rápidas (fast locals).

inspect.CO_NEWLOCALS

Si se establece, se creará un nuevo diccionario para el marco f_locals cuando se ejecute el objeto código.

inspect.CO_VARARGS

El objeto del código tiene un parámetro posicional variable (similar a *args).

inspect.CO_VARKEYWORDS

El objeto del código tiene un parámetro de palabra clave variable (similar a **kwargs).

inspect.CO_NESTED

El flag se fija cuando el objeto del código es una función anidada.

inspect.CO_GENERATOR

El flag se fija cuando el objeto del código es una función generadora, es decir, un objeto generador es retornado cuando el objeto del código se ejecuta.

inspect.CO_NOFREE

El flag se configura si no hay variables libres o de celda.

inspect.CO_COROUTINE

El flag se configura cuando el objeto del código es una función de corutina. Cuando el objeto código se ejecuta, retorna un objeto de corutina. Ver PEP 492 [https://www.python.org/dev/peps/pep-0492] para más detalles.

Nuevo en la versión 3.5.

inspect.CO_ITERABLE_COROUTINE

El flag se utiliza para transformar generadores en corutinas basadas en generadores. Los objetos generadores con este flag pueden ser usados en la expresión await, y objetos de corutina yield from. Ver PEP 492 [https://www.python.org/dev/peps/pep-0492] para más detalles.

Nuevo en la versión 3.5.

inspect.CO_ASYNC_GENERATOR

El flag se configura cuando el objeto del código es una función generadora asíncrona. Cuando el objeto código se ejecuta, retorna un objeto generador asíncrono. Ver PEP 525 [https://www.python.org/dev/peps/pep-0525] para más detalles.

Nuevo en la versión 3.6.

Nota

Los flags son específicos de CPython, y no pueden ser definidas en otras implementaciones de Python. Además, los flags son un detalle de la implementación, y pueden ser eliminados o desaprobados en futuras versiones de Python. Se recomienda utilizar las APIs públicas del módulo inspect para cualquier necesidad de introspección.

Interfaz de la línea de comando

El módulo inspect también proporciona una capacidad básica de introspección desde la línea de comandos.

Por defecto, acepta el nombre de un módulo e imprime la fuente de ese módulo. Una clase o función dentro del módulo puede imprimirse en su lugar añadiendo dos puntos y el nombre calificado del objeto objetivo.

--details

Imprimir información sobre el objeto especificado en lugar del código fuente

site — Enlace (hook) de configuración específico del sitio

Código Fuente: Lib/site.py [https://github.com/python/cpython/tree/3.9/Lib/site.py]

Este módulo se importa automáticamente durante la inicialización. La importación automática se puede suprimir utilizando la opción del intérprete opción -S .

La importación de este módulo agregará rutas específicas del sitio a la ruta de búsqueda del módulo y agregará algunas incorporaciones, a menos que -S se haya utilizado. En este caso , este módulo se puede importar de forma segura sin modificaciones automáticas en la ruta de búsqueda del módulo o adiciones a los módulos incorporados. Para activar explícitamente las adiciones habituales específicas del sitio, llame a sitio.principal() función.

Distinto en la versión 3.3: Importar el módulo utilizado para activar la manipulación de rutas incluso cuando se utiliza -S.

It starts by constructing up to four directories from a head and a tail part. For the head part, it uses sys.prefix and sys.exec_prefix; empty heads are skipped. For the tail part, it uses the empty string and then lib/site-packages (on Windows) or lib/pythonX.Y/site-packages (on Unix and macOS). For each of the distinct head-tail combinations, it sees if it refers to an existing directory, and if so, adds it to sys.path and also inspects the newly added path for configuration files.

Distinto en la versión 3.5: Se ha eliminado la compatibilidad con el directorio «site-python».

Si un archivo llamado «pyvenv.cfg» existe un directorio por encima de sys.executable, sys.prefix y sys.exec_prefix se establecen en ese directorio y también se comprueba si hay paquetes de sitio (sys.base_prefix y sys.base_exec_prefix siempre serán los prefijos «reales» de la instalación de Python). Si «pyvenv.cfg» (un archivo de configuración de arranque) contiene la clave «include-system-site-packages» configurada con un valor diferente a «true» (no distingue entre mayúsculas y minúsculas), no se buscarán los prefijos de nivel de sistema para paquetes de sitio; de lo contrario lo harán.

Un archivo de configuración de ruta es un archivo cuyo nombre tiene la forma name.pth y existe en uno de los cuatro directorios mencionados anteriormente; su contenido son elementos adicionales (uno por línea) que se agregarán a sys.path. Los elementos que no existen nunca se agregan a sys.path y no se comprueba que el elemento se refiera a un directorio en lugar de a un archivo. No se agrega ningún elemento a sys.path más de una vez. Se omiten las líneas en blanco y las que comienzan con #. Se ejecutan las líneas que comienzan con import (seguidas de un espacio o tabulación).

Nota

Una línea ejecutable en un archivo .pth se ejecuta en cada inicio de Python, independientemente de si se va a utilizar un módulo en particular. Por tanto, su impacto debería reducirse al mínimo. El propósito principal de las líneas ejecutables es hacer que los módulos correspondientes se puedan importar (cargar ganchos de importación de terceros, ajustar PATH, etc.). Se supone que cualquier otra inicialización se debe realizar en la importación real de un módulo, siempre y cuando ocurra. Limitar un fragmento de código a una sola línea es una medida deliberada para desalentar la inclusión de algo más complejo aquí.

Por ejemplo, supongamos que sys.prefix y sys.exec_prefix están configurados en /usr/local. La biblioteca Python X.Y se instala en /usr/local/lib/pythonX.Y. Supongamos que tiene un subdirectorio /usr/local/lib/pythonX.Y/site-packages con tres subsubdirectorios, foo, bar y spam, y dos archivos de configuración de ruta, foo.pth y bar.pth. Suponga foo.pth contiene lo siguiente:

# foo package configuration

foo
bar
bletch

y bar.pth contiene:

# bar package configuration

bar

Luego, los siguientes directorios específicos de la versión se agregan a sys.path, en este orden:

/usr/local/lib/pythonX.Y/site-packages/bar
/usr/local/lib/pythonX.Y/site-packages/foo

Tenga en cuenta que bletch se omite porque no existe; el directorio bar precede al directorio foo porque bar.pth viene alfabéticamente antes de foo.pth; y spam se omite porque no se menciona en ninguno de los archivos de configuración de ruta.

Después de estas manipulaciones de ruta, se intenta importar un módulo llamado sitecustomize, que puede realizar personalizaciones arbitrarias específicas del sitio. Normalmente lo crea un administrador del sistema en el directorio site-packages. Si esta importación falla con un ImportError o su excepción de subclase, y el atributo name de la excepción es igual a 'sitecustomize', se ignora silenciosamente. Si Python se inicia sin flujos de salida disponibles, como con pythonw.exe en Windows (que se usa de forma predeterminada para iniciar IDLE), se ignora el intento de salida de sitecustomize. Cualquier otra excepción provoca una falla silenciosa y quizás misteriosa del proceso.

Después de esto, se intenta importar un módulo llamado usercustomize, que puede realizar personalizaciones arbitrarias específicas del usuario, si ENABLE_USER_SITE es verdadero. Este archivo está destinado a ser creado en el directorio site-packages del usuario (ver más abajo), que es parte de sys.path a menos que esté desactivado por -s. Si esta importación falla con una excepción ImportError o su subclase, y el atributo name de la excepción es igual a 'usercustomize', se ignora silenciosamente.

Tenga en cuenta que para algunos sistemas que no son Unix, sys.prefix y sys.exec_prefix están vacíos y se omiten las manipulaciones de la ruta; sin embargo, se sigue intentando importar sitecustomize y usercustomize.

Configuración de Readline

En los sistemas que admiten readline, este módulo también importará y configurará el módulo rlcompleter, si Python se inicia en modo interactivo y sin la opción -S. El comportamiento predeterminado es habilitar la finalización de tabulación y usar ~/.python_history como archivo de guardado del historial. Para deshabilitarlo, borre (o anule) el atributo sys.__interactivehook__ en su sitecustomize o usercustomize module o su archivo PYTHONSTARTUP.

Distinto en la versión 3.4: La activación de rlcompleter y el historial se hizo automática.

Contenido del módulo

site.PREFIXES

Una lista de prefijos para directorios de site-packages.

site.ENABLE_USER_SITE

Flag que muestra el estado del directorio site-packages del usuario. True significa que está habilitado y se agregó a sys.path. False significa que fue deshabilitado por solicitud del usuario (con -s o PYTHONNOUSERSITE). None significa que fue deshabilitado por razones de seguridad (falta de coincidencia entre la identificación de usuario o grupo y la identificación efectiva) o por un administrador.

site.USER_SITE

Path to the user site-packages for the running Python. Can be None if getusersitepackages() hasn’t been called yet. Default value is ~/.local/lib/pythonX.Y/site-packages for UNIX and non-framework macOS builds, ~/Library/Python/X.Y/lib/python/site-packages for macOS framework builds, and %APPDATA%\Python\PythonXY\site-packages on Windows. This directory is a site directory, which means that .pth files in it will be processed.

site.USER_BASE

Path to the base directory for the user site-packages. Can be None if getuserbase() hasn’t been called yet. Default value is ~/.local for UNIX and macOS non-framework builds, ~/Library/Python/X.Y for macOS framework builds, and %APPDATA%\Python for Windows. This value is used by Distutils to compute the installation directories for scripts, data files, Python modules, etc. for the user installation scheme. See also PYTHONUSERBASE.

site.main()

Agrega todos los directorios estándar específicos del sitio a la ruta de búsqueda del módulo. Esta función se llama automáticamente cuando se importa este módulo, a menos que el intérprete de Python se haya iniciado con la opción -S.

Distinto en la versión 3.3: Esta función solía llamarse incondicionalmente.

site.addsitedir(sitedir, known_paths=None)

Agrega un directorio a sys.path y procesa sus archivos .pth. Típicamente utilizado en sitecustomize o usercustomize (ver arriba).

site.getsitepackages()

Retorna una lista que contiene todos los directorios site-packages globales.

Nuevo en la versión 3.2.

site.getuserbase()

Retorna la ruta del directorio base del usuario USER_BASE. Si este aún no fue inicializado, esta función también lo configurará, respetando PYTHONUSERBASE.

Nuevo en la versión 3.2.

site.getusersitepackages()

Return the path of the user-specific site-packages directory, USER_SITE. If it is not initialized yet, this function will also set it, respecting USER_BASE. To determine if the user-specific site-packages was added to sys.path ENABLE_USER_SITE should be used.

Nuevo en la versión 3.2.

Interfaz de línea de comando

El módulo site también proporciona una forma de obtener los directorios del usuario desde la línea de comandos:

$ python3 -m site --user-site
/home/user/.local/lib/python3.3/site-packages

Si se llama sin argumentos, imprimirá el contenido de sys.path en la salida estándar, seguido del valor de USER_BASE y si el directorio existe, entonces lo mismo para USER_SITE, y finalmente el valor de ENABLE_USER_SITE.

--user-base

Imprime la ruta al directorio base del usuario.

--user-site

Imprime la ruta al directorio site-packages del usuario.

Si se dan ambas opciones, la ruta del directorio base y la del directorio site-packages del usuario se imprimirán (siempre en este orden), separados por os.pathsep.

Si se da alguna opción, el script saldrá con uno de estos valores: `` 0`` si el directorio site-packages del usuario está habilitado, `` 1`` si fue deshabilitado por el usuario, `` 2`` si está deshabilitado por razones de seguridad o por un administrador, y un valor mayor que 2 si hay un error.

Ver también

PEP 370 [https://www.python.org/dev/peps/pep-0370] - Directorio site-packages de cada usuario

Intérpretes de Python personalizados

Los módulos descritos en este capítulo permiten escribir interfaces similares al intérprete interactivo de Python. Si desea un intérprete de Python que admita alguna característica especial además del lenguaje Python, debe mirar el módulo code. (El módulo codeop es de más bajo nivel y se utiliza para soportar la compilación de un fragmento posiblemente incompleto de código Python).

La lista completa de módulos descritos en este capítulo es:

code — Clases básicas de intérpretes

Objetos de intérprete interactivo

Objetos de consola interactiva

codeop — Compila código Python

code — Clases básicas de intérpretes

Código fuente:: Lib/code.py [https://github.com/python/cpython/tree/3.9/Lib/code.py]

El módulo de code proporciona facilidades para implementar bucles de lectura-evaluación-impresión en Python. Se incluyen dos clases y funciones de conveniencia que se pueden usar para crear aplicaciones que brinden un prompt interactivo del intérprete.

class code.InteractiveInterpreter(locals=None)

Esta clase se ocupa del estado del intérprete y del análisis sintáctico (el espacio de nombres del usuario); no se ocupa del almacenamiento en búfer de entrada o de la solicitud o la denominación de archivos de entrada (el nombre de archivo siempre se pasa explícitamente). El argumento opcional locals especifica el diccionario en el que se ejecutará el código; por defecto es un diccionario recién creado con la clave '__name __' establecida en '__console __' y la clave '__doc __' en None.

class code.InteractiveConsole(locals=None, filename="<console>")

Emula estrictamente el comportamiento del intérprete interactivo de Python. Esta clase se basa en InteractiveInterpreter y agrega solicitudes y búfer de entrada usando los conocidos sys.ps1 y sys.ps2.

code.interact(banner=None, readfunc=None, local=None, exitmsg=None)

Función de conveniencia para ejecutar un ciclo de lectura-evaluación-impresión (read-eval-print). Esto crea una nueva instancia de InteractiveConsole y establece readfunc -si se proporciona- para ser utilizado como el método InteractiveConsole.raw_input(). Si se proporciona local, se pasa al constructor InteractiveConsole para usarlo como el espacio de nombres predeterminado para el bucle del intérprete. El método interact() de la instancia se ejecuta con banner y exitmsg, estos se pasan como bandera y mensaje de salida para usar nuevamente, si se proporciona. El objeto de la consola se descarta después de su uso.

Distinto en la versión 3.6: Se agregó el parámetro exitmsg.

code.compile_command(source, filename="<input>", symbol="single")

Esta función es útil para programas que desean emular el bucle principal del intérprete de Python (también conocido como bucle read-eval-print). La parte complicada es determinar cuándo el usuario ha ingresado un comando incompleto que se puede completar ingresando más texto (en lugar de un comando completo o un error de sintaxis). Esta función casi siempre toma la misma decisión que el bucle principal del intérprete real.

source es la cadena de caracteres fuente; filename es el nombre de archivo opcional desde el que se leyó la fuente, por defecto es '<input>'; y symbol es el símbolo de inicio gramatical opcional, que debería ser 'single' (el predeterminado), 'eval' o 'exec'.

Retorna un objeto de código (lo mismo que compile(source, filename, symbol)) si el comando está completo y es válido; None si el comando está incompleto; lanza SyntaxError si el comando está completo y contiene un error de sintaxis, o lanza OverflowError o ValueError si el comando contiene un literal no válido.

Objetos de intérprete interactivo

InteractiveInterpreter.runsource(source, filename="<input>", symbol="single")

Compila y ejecuta alguna fuente en el intérprete. Los argumentos son los mismos que para compile_command(); el valor predeterminado para filename es '<input>', y para symbol es 'single'. Puede suceder una de varias cosas:

La entrada es incorrecta; compile_command() generó una excepción (SyntaxError o OverflowError). Se imprime un seguimiento de sintaxis llamando al método showsyntaxerror(). runsource() retorna False.

La entrada está incompleta y se requiere más información; compile_command() retorna None. runsource() retorna True.

La entrada está completa; compile_command() retornó un objeto de código. El código se ejecuta llamando a runcode() (que también maneja excepciones en tiempo de ejecución, excepto SystemExit). runsource() retorna False.

El valor de retorno se puede usar para decidir si usar sys.ps1 o sys.ps2 para solicitar la siguiente línea.

InteractiveInterpreter.runcode(code)

Ejecuta un objeto de código. Cuando ocurre una excepción, se llama a showtraceback() para mostrar un seguimiento del código. Se capturan todas las excepciones excepto SystemExit, que puede propagarse.

Una nota sobre KeyboardInterrupt: esta excepción puede ocurrir en otra parte de este código y no siempre se detecta. Quien llama la función debe estar preparado para manejar esto.

InteractiveInterpreter.showsyntaxerror(filename=None)

Muestra el error de sintaxis que acaba de ocurrir. Esto no muestra la traza de seguimiento porque no la hay para errores de sintaxis. Si se proporciona filename, se incluirá en la excepción en lugar del nombre de archivo predeterminado proporcionado por el analizador de Python, ya que siempre usa '<string>' cuando lee de una cadena de caracteres. La salida se escribe mediante el método write().

InteractiveInterpreter.showtraceback()

Muestra la excepción que acaba de ocurrir. Eliminamos el primer elemento de la pila porque está dentro de la implementación del intérprete. La salida se escribe mediante el método write().

Distinto en la versión 3.5: Se muestra la traza de seguimiento encadenada completa en lugar de solo la traza primaria de pila.

InteractiveInterpreter.write(data)

Escribe una cadena de caracteres en el flujo de error estándar (sys.stderr). Las clases derivadas deben reemplazar esto para proporcionar el manejo de salida apropiado según sea necesario.

Objetos de consola interactiva

La clase InteractiveConsole es una subclase de InteractiveInterpreter, por lo que ofrece todos los métodos de los objetos del intérprete, así como las siguientes adiciones.

InteractiveConsole.interact(banner=None, exitmsg=None)

Emula estrictamente la consola interactiva de Python. El argumento opcional banner especifica la bandera a imprimir antes de la primera interacción; de forma predeterminada, imprime una bandera similar al impreso por el intérprete estándar de Python, seguido del nombre de clase del objeto de la consola entre paréntesis (para no confundir esto con el intérprete real, ¡ya que está muy cerca!)

El argumento opcional exitmsg especifica un mensaje de salida que se imprime al salir. Pase la cadena de caracteres vacía para suprimir el mensaje de salida. Si no se proporciona exitmsg o es None, se imprime el mensaje predeterminado.

Distinto en la versión 3.4: Para suprimir la impresión de cualquier bandera, pase una cadena de caracteres vacía.

Distinto en la versión 3.6: Imprime un mensaje de salida al salir.

InteractiveConsole.push(line)

Envía una línea de texto fuente al intérprete. La línea no debe tener un salto de línea al final; puede tener nuevas líneas internas. La línea se agrega a un búfer y se llama al método runsource() del intérprete con el contenido concatenado del búfer y la nueva fuente. Si indica que el comando se ejecutó o no es válido, el búfer se restablece; de lo contrario, el comando está incompleto y el búfer se deja como estaba después de agregar la línea. Si se requieren más entradas el valor de retorno es True, False si la línea se procesó de alguna manera (esto es lo mismo que runsource()).

InteractiveConsole.resetbuffer()

Elimina cualquier texto fuente no gestionado del búfer de entrada.

InteractiveConsole.raw_input(prompt="")

Escribe un prompt y lee una línea. La línea retornada no incluye el salto de línea final. Cuando el usuario ingresa la secuencia de teclas EOF, se lanza OFError. La implementación base lee de sys.stdin; una subclase puede reemplazar esto con una implementación diferente.

codeop — Compila código Python

Código fuente: Lib/codeop.py [https://github.com/python/cpython/tree/3.9/Lib/codeop.py]

El módulo codeop proporciona herramientas para emular el bucle principal del intérprete de Python (también conocido como read-eval-print), tal como se hace en el módulo code. Por lo tanto, este módulo no está diseñado para utilizarlo directamente; si desea incluir un ciclo de este tipo en su programa, probablemente es mejor utilizar el módulo code en su lugar.

Esta actividad consta de dos partes:

Ser capaz de identificar si una línea de entrada completa una sentencia de Python: en resumen, decir si se debe imprimir a continuación “>>>” o “...” .

Recordar qué sentencias posteriores ha ingresado el usuario, para que estas entradas sean incluidas al momento de compilar.

El módulo codeop proporciona formas de realizar estas dos partes, tanto de forma independiente, como en conjunto.

Para hacer lo anterior:

codeop.compile_command(source, filename="<input>", symbol="single")

Intenta compilar source, que debe ser una cadena de caracteres de código Python y retorna un objeto si source es código Python válido. En este caso, el atributo del nombre del archivo del objeto va a ser filename, el cuál por defecto es '<input>'. Retorna None si source no es código Python válido, pero es un prefijo de código Python válido.

Si hay un problema con source, se lanzará una excepción. SyntaxError se lanza si hay una sintaxis de Python no válida, y OverflowError o ValueError si hay un literal no válido.

El argumento symbol determina si source se compila como una declaración ('single', el valor predeterminado) o como un expression ('eval'). Cualquier otro valor hará que se lance ValueError.

Nota

Es posible (pero no probable) que el analizador deje de analizar con un resultado exitoso antes de llegar al final de la fuente; en este caso, los símbolos finales pueden ignorarse en lugar de provocar un error. Por ejemplo, una barra invertida seguida de dos nuevas líneas puede ir seguida de basura arbitraria. Esto se solucionará una vez que la API para el analizador sea mejor.

class codeop.Compile

Las instancias de esta clase tienen __call__() métodos idénticos en firma a la función incorporada compile(), pero con la diferencia de que si la instancia compila el texto del programa que contiene una instrucción __future__, la instancia “recuerda” y compila todos los textos de programa posteriores con la declaración en vigor.

class codeop.CommandCompiler

Las instancias de esta clase tienen __call__() métodos idénticos en firma a compile_command(); la diferencia es que si la instancia compila un texto de programa que contiene una declaración __future__, la instancia “recuerda” y compila todos los textos de programa posteriores con la declaración en vigor.

Importando módulos

Los módulos descritos en este capítulo proporcionan nuevas formas de importar otros módulos de Python y ganchos para personalizar los procesos de importación.

La lista completa de módulos descritos en este capítulo es:

zipimport — Importar módulos desde archivos zip

Objetos zipimporter

Ejemplos

pkgutil — Utilidad de extensión de paquete

modulefinder — Buscar módulos usados por un script

Ejemplo de uso de ModuleFinder

runpy — Localización y ejecución de módulos Python

importlib — La implementación de import

Introducción

Funciones

importlib.abc – Clases base abstractas relacionadas con la importación

importlib.resources – Recursos

importlib.machinery – Importadores y enlaces de ruta

importlib.util – Código de utilidad para importadores

Ejemplos

Importar programáticamente

Comprobando si se puede importar un módulo

Importar un archivo fuente directamente

Configurar un importador

Aproximando importlib.import_module()

Usando importlib.metadata

Descripción general

API funcional

Puntos de entrada

Metadatos de distribución

Versiones de distribución

Archivos de distribución

Requerimientos de la distribución

Distribuciones

Extendiendo el algoritmo de búsqueda

zipimport — Importar módulos desde archivos zip

Código fuente: Lib/zipimport.py [https://github.com/python/cpython/tree/3.9/Lib/zipimport.py]

Este módulo añade la capacidad de importar módulos de Python (*.py, *.pyc) y paquetes de archivos de formato ZIP. Por lo general, no es necesario utilizar el módulo zipimport explícitamente; se utiliza automáticamente por el mecanismo incorporado import para los ítems sys.path que son rutas a archivos ZIP.

Típicamente sys.path es una lista de cadenas con nombres de directorios. Este módulo también permite a un elemento de sys.path ser una cadena con la que se nombre a un archivo ZIP. El archivo ZIP puede contener una estructura de subdirectorios para soportar la importación de paquetes, y una ruta dentro del archivo puede ser especificada para únicamente importar desde un subdirectorio. Por ejemplo, la ruta example.zip/lib/ sólo importaría desde el subdirectorio lib/ dentro del archivo.

Any files may be present in the ZIP archive, but importers are only invoked for .py and .pyc files. ZIP import of dynamic modules (.pyd, .so) is disallowed. Note that if an archive only contains .py files, Python will not attempt to modify the archive by adding the corresponding .pyc file, meaning that if a ZIP archive doesn’t contain .pyc files, importing may be rather slow.

Distinto en la versión 3.8: Anteriormente, los archivos ZIP con un comentario de archivo no eran compatibles.

Ver también

PKZIP Nota de aplicación [https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT]

Documentación sobre el formato de archivo ZIP por Phil Katz, el creador del formato y algoritmos utilizados.

PEP 273 [https://www.python.org/dev/peps/pep-0273] - Importar módulos de archivos Zip

Escrito por James C. Ahlstrom, quien también proporcionó una implementación. Python 2.3 sigue la especificación en PEP 273, pero utiliza una implementación escrita por Just van Rossum que utiliza los ganchos importados descritos en PEP 302.

PEP 302 [https://www.python.org/dev/peps/pep-0302] - Nuevos ganchos de importación

El PEP para agregar los ganchos de importación que ayudan a este módulo a funcionar.

Este módulo define una excepción:

exception zipimport.ZipImportError

Excepción lanzada por objetos zipimporter. Es una subclase de ImportError, por lo que también puede ser capturada como ImportError.

Objetos zipimporter

zipimporter es la clase para importar archivos ZIP.

class zipimport.zipimporter(archivepath)

Crea una nueva instancia zipimporter. archivepath debe ser una ruta a un archivo ZIP, o a una ruta específica dentro de un archivo ZIP. Por ejemplo, un archivepath de foo/bar.zip/lib buscará módulos en el directorio lib dentro del archivo ZIP foo/bar.zip (siempre que exista).

ZipImportError es lanzada si archivepath no apunta a un archivo ZIP válido.

find_module(fullname[, path])

Busca un módulo especificado por fullname. fullname debe ser el nombre completo del módulo (punteado). Retorna la propia instancia zipimporter si el módulo fue encontrado, o None si no. El argumento opcional path es ignorado — está ahí por compatibilidad con el protocolo del importador.

get_code(fullname)

Retorna el objeto de código para el módulo especificado. Lanza ZipImportError si el módulo no pudo ser encontrado.

get_data(pathname)

Retorna los datos asociados con pathname. Lanza OSError si el archivo no fue encontrado.

Distinto en la versión 3.3: IOError solía lanzarse en lugar de OSError.

get_filename(fullname)

Retorna el valor que se le habría asignado a __file__ si el módulo especificado fue importado. Lanza ZipImportError si el módulo no pudo ser encontrado.

Nuevo en la versión 3.1.

get_source(fullname)

Retorna el código fuente para el módulo especificado. Lanza ZipImportError si el módulo no pudo ser encontrado, retorna None si el archivo no contiene al módulo, pero no tiene fuente para ello.

is_package(fullname)

Retorna True si el módulo especificado por fullname es un paquete. Lanza ZipImportError si el módulo no pudo ser encontrado.

load_module(fullname)

Cargue el módulo especificado por fullname. fullname debe ser el nombre completo de módulo (punteado). Retorna el módulo importado, o lanza ZipImportError si no fue encontrado.

archive

El nombre de archivo del archivo ZIP asociado del importador, sin una posible sub-ruta.

prefix

La sub-ruta dentro del archivo ZIP donde se buscan los módulos. Esta es la cadena vacía para objetos zipimporter la cual apunta a la raíz del archivo ZIP.

Los atributos archive y prefix, cuando son combinados con una barra diagonal, son iguales al argumento original archivepath dado al constructor zipimporter.

Ejemplos

Este es un ejemplo que importa un módulo de un archivo ZIP - tenga en cuenta que el módulo zipimport no está usado explícitamente.

$ unzip -l example.zip
Archive:  example.zip
  Length     Date   Time    Name
 --------    ----   ----    ----
     8467  11-26-02 22:30   jwzthreading.py
 --------                   -------
     8467                   1 file
$ ./python
Python 2.3 (#1, Aug 1 2003, 19:54:32)
>>> import sys
>>> sys.path.insert(0, 'example.zip')  # Add .zip file to front of path
>>> import jwzthreading
>>> jwzthreading.__file__
'example.zip/jwzthreading.py'

pkgutil — Utilidad de extensión de paquete

Código fuente: Lib/pkgutil.py [https://github.com/python/cpython/tree/3.9/Lib/pkgutil.py]

Este módulo proporciona utilidades para el sistema de importación, en particular soporte para paquetes.

class pkgutil.ModuleInfo(module_finder, name, ispkg)

Una tupla nombrada que contiene un breve resumen de la información del módulo.

Nuevo en la versión 3.6.

pkgutil.extend_path(path, name)

Extiende la ruta de búsqueda de los módulos que componen un paquete. El uso previsto es colocar el siguiente código en __init__.py: de un paquete:

from pkgutil import extend_path
__path__ = extend_path(__path__, __name__)

This will add to the package’s __path__ all subdirectories of directories on sys.path named after the package. This is useful if one wants to distribute different parts of a single logical package as multiple directories.

También busca archivos *.pkg donde * coincide con el argumento name. Esta característica es similar a archivos *.pth (vea el módulo site para más información) excepto que no incluye líneas de casos especiales que comienzan con ìmport. Un archivo *.pkg es confiable al pie de la letra: además de buscar duplicados, todas las entradas encontradas en un *.pkg se agregan a la ruta, independientemente de si existen en el sistema de archivos. (Esto es una funcionalidad).

Si la ruta de entrada no es una lista (como es el caso de los paquetes congelados), se retorna sin cambios. La ruta de entrada no se modifica; se retorna una copia ampliada. Los elementos solo se adjuntan a la copia al final.

Se supone que sys.path es una secuencia. Los elementos de sys.path que no sean cadenas de caracteres que se refieran a directorios existentes se ignoran. Los elementos Unicode en sys.path que causan errores cuando se utilizan como nombres de archivo pueden hacer que esta función lance una excepción (en línea con el comportamiento de os.path.isdir()).

class pkgutil.ImpImporter(dirname=None)

Buscador PEP 302 [https://www.python.org/dev/peps/pep-0302] que envuelve el algoritmo de importación «clásico» de Python.

Si dirname es una cadena de caracteres, se crea un buscador PEP 302 [https://www.python.org/dev/peps/pep-0302] que busca ese directorio. Si dirname es None, se crea un buscador PEP 302 [https://www.python.org/dev/peps/pep-0302] que busca en el actual sys.path, más cualquier módulo que esté congelado o incorporado.

Tenga en cuenta que ImpImporter no admite actualmente el uso de ubicación sys.meta_path.

Obsoleto desde la versión 3.3: Esta emulación ya no es necesaria, ya que ahora lo es el mecanismo de importación estándar totalmente compatible con PEP 302 [https://www.python.org/dev/peps/pep-0302] y disponible en importlib.

class pkgutil.ImpLoader(fullname, file, filename, etc)

Loader que envuelve el algoritmo de importación «clásico» de Python.

Obsoleto desde la versión 3.3: Esta emulación ya no es necesaria, ya que ahora lo es el mecanismo de importación estándar totalmente compatible con PEP 302 [https://www.python.org/dev/peps/pep-0302] y disponible en importlib.

pkgutil.find_loader(fullname)

Recupera un módulo loader para un fullname dado.

Este es un contenedor de compatibilidad con versiones anteriores de importlib.util.find_spec() que convierte la mayoría de los errores en ImportError y solo retorna el cargador en lugar del completo ModuleSpec.

Distinto en la versión 3.3: Actualizado para basarse directamente en importlib en lugar de depender del paquete interno PEP 302 [https://www.python.org/dev/peps/pep-0302] emulación de importación.

Distinto en la versión 3.4: Actualizado basado en PEP 451 [https://www.python.org/dev/peps/pep-0451]

pkgutil.get_importer(path_item)

Recupera un finder para el path_item.

El buscador retornado se almacena en caché en sys.path_importer_cache si fue creado recientemente por un enlace de ruta.

La caché (o parte de ella) puede ser borrada manualmente si el escaneo de sys.path_hooks es necesario.

Distinto en la versión 3.3: Actualizado para basarse directamente en importlib en lugar de depender del paquete interno PEP 302 [https://www.python.org/dev/peps/pep-0302] emulación de importación.

pkgutil.get_loader(module_or_name)

Obtiene un objeto loader para module_or_name.

Si se puede acceder al módulo o paquete a través del mecanismo de importación normal, se devuelve un contenedor alrededor de la parte relevante de esa maquinaria. Retorna None si el módulo no se puede encontrar o importar. Si el módulo nombrado aún no se ha importado, se importa el paquete que lo contiene (si lo hay), para establecer el paquete __path__.

Distinto en la versión 3.3: Actualizado para basarse directamente en importlib en lugar de depender del paquete interno PEP 302 [https://www.python.org/dev/peps/pep-0302] emulación de importación.

Distinto en la versión 3.4: Actualizado basado en PEP 451 [https://www.python.org/dev/peps/pep-0451]

pkgutil.iter_importers(fullname='')

Cede (yield) objectos finder para el nombre de módulo dado.

If fullname contains a '.', the finders will be for the package containing fullname, otherwise they will be all registered top level finders (i.e. those on both sys.meta_path and sys.path_hooks).

Si el módulo nombrado está en un paquete, ese paquete se importa como un efecto secundario de invocar esta función.

Si no se especifica ningún nombre de módulo, se generan todos los buscadores de nivel superior.

Distinto en la versión 3.3: Actualizado para basarse directamente en importlib en lugar de depender del paquete interno PEP 302 [https://www.python.org/dev/peps/pep-0302] emulación de importación.

pkgutil.iter_modules(path=None, prefix='')

Yields ModuleInfo for all submodules on path, or, if path is None, all top-level modules on sys.path.

path tendría que ser None o una list de rutas en las que buscar módulos.

prefix es una cadena para mostrar delante de cada nombre de módulo en la salida.

Nota

Sólo funciona para un finder que define un método iter_modules(). Esta interfaz no es estándar, por lo que el módulo también proporciona implementaciones para importlib.machinery.FileFinder y zipimport.zipimporter.

Distinto en la versión 3.3: Actualizado para basarse directamente en importlib en lugar de depender del paquete interno PEP 302 [https://www.python.org/dev/peps/pep-0302] emulación de importación.

pkgutil.walk_packages(path=None, prefix='', onerror=None)

Cede (yield) ModuleInfo para todos los módulos de forma recursiva en path, o, si path es None, todos los módulos accesibles.

path tendría que ser None o una list de rutas en las que buscar módulos.

prefix es una cadena para mostrar delante de cada nombre de módulo en la salida.

Note que esta función debe importar todos los packages (¡no todos los módulos!) en el path especificado, para acceder al atributo __path__ para encontrar submódulos.

onerror es una función que se llama con un argumento (el nombre del paquete que se estaba importando) si se produce alguna excepción al intentar importar un paquete. Si no se proporciona ninguna función onerror, los ImportError se capturan e ignoran, mientras que todas las demás excepciones se propagan, terminando la búsqueda.

Ejemplos:

# list all modules python can access
walk_packages()

# list all submodules of ctypes
walk_packages(ctypes.__path__, ctypes.__name__ + '.')

Nota

Sólo funciona para un finder que define un método iter_modules(). Esta interfaz no es estándar, por lo que el módulo también proporciona implementaciones para importlib.machinery.FileFinder y zipimport.zipimporter.

Distinto en la versión 3.3: Actualizado para basarse directamente en importlib en lugar de depender del paquete interno PEP 302 [https://www.python.org/dev/peps/pep-0302] emulación de importación.

pkgutil.get_data(package, resource)

Obtiene un recurso de un paquete.

Esto es un contenedor para la API loader get_data. El argumento package debe ser el nombre de un paquete, en formato de módulo estándar (foo.bar).El argumento resource debe tener la forma de un nombre de archivo relativo, utilizando / como separador de ruta.El nombre del directorio principal .. no está permitido, ni tampoco un nombre raíz (empezando por /).

La función retorna una cadena de caracteres binaria que es el contenido del recurso especificado.

Para los paquetes ubicados en el sistema de archivos, que ya se han importado, este es el equivalente aproximado de:

d = os.path.dirname(sys.modules[package].__file__)
data = open(os.path.join(d, resource), 'rb').read()

Si el paquete no puede ser localizado o cargado, o usa un loader el cuál no soporta get_data, entonces retorna None. En particular, el: término loader para namespace packages no soporta get_data.

pkgutil.resolve_name(name)

Resuelve un nombre a un objeto.

Esta funcionalidad es usada en numerosos lugares en la librería estándar (ver bpo-12915 [https://bugs.python.org/issue?@action=redirect&bpo=12915]) - y existe funcionalidad equivalente también en librerías de terceros ampliamente usadas, tales como setuptools, Django y Pyramid.

Se espera que name sea una cadena de caracteres en uno de los siguientes formatos, donde W representa un identificador de Python válido, y un punto representa literalmente un punto en las siguientes pseudo-expresiones regulares:

W(.W)*

W(.W)*:(W(.W)*)?

La primera forma existe sólo para mantener compatibilidad con versiones anteriores. Asume que parte del nombre con puntos es un paquete, y el resto es un objeto en algún lugar dentro de ese paquete, posiblemente anidado dentro de otros objetos. Dado que el lugar donde el paquete termina y la jerarquía de objetos comienza no puede ser inferida por inspección, con esta forma se debe realizar repetidos intentos de importación.

En la segunda forma, el usuario hace claro el punto de división al proveer un signo de dos puntos: el nombre con puntos a la izquierda de los dos puntos es el paquete a ser importado, y el nombre con puntos a la derecha es la jerarquía de nombres dentro de ese paquete. Sólo una importación se necesaria con esta forma. Si termina con dos puntos, entonces se retorna un objeto módulo.

La función retornará un objeto (el cual puede ser un módulo), o lanzará una de las siguientes excepciones:

ValueError – si name no tiene un formato reconocido.

ImportError – si una importación falló cuando no lo debería haber hecho.

AttributeError – Si un fallo ocurrió mientras se atravesaba la jerarquía de objetos dentro del paquete importado para obtener el objeto deseado.

Nuevo en la versión 3.9.

modulefinder — Buscar módulos usados por un script

Código fuente: Lib/modulefinder.py [https://github.com/python/cpython/tree/3.9/Lib/modulefinder.py]

Este módulo provee una clase ModuleFinder que puede ser usada para determinar el conjunto de módulos importados en un script. modulefinder.py puede también ejecutarse como un script, dando el nombre de un archivo de Python como argumento, tras lo cual se imprimirá un reporte de los módulos importados.

modulefinder.AddPackagePath(pkg_name, path)

Registra que el paquete llamado pkg_name pueda ser encontrado en el path especificado.

modulefinder.ReplacePackage(oldname, newname)

Permite especificar que el módulo llamado oldname es de hecho el paquete llamado newname.

class modulefinder.ModuleFinder(path=None, debug=0, excludes=[], replace_paths=[])

Esta clase provee los métodos run_script() y report() que determinan el conjunto de módulos importados por un script. path puede ser un listado de directorios a buscar por módulos; si no es especificado, se usará sys.path. debug define el nivel de depuración; valores más altos hacen que la clase imprima mensajes de depuración acerca de lo que está haciendo. excludes es una lista de nombres de módulos que serán excluidos del análisis. replace_paths es una lista de tuplas (oldpath, newpath) que serán remplazadas en las rutas de los módulos.

report()

Imprime un reporte a la salida estándar que lista los módulos importados por el script y sus rutas, así como los módulos que faltan o parecieran faltar.

run_script(pathname)

Analiza los contenidos del archivo pathname, que debe contener código Python.

modules

Un diccionario que mapea los nombres de los módulos a los módulos. Vea Ejemplo de uso de ModuleFinder.

Ejemplo de uso de ModuleFinder

El script que será analizado más adelante (bacon.py):

import re, itertools

try:
    import baconhameggs
except ImportError:
    pass

try:
    import guido.python.ham
except ImportError:
    pass

El script que generará el reporte de bacon.py:

from modulefinder import ModuleFinder

finder = ModuleFinder()
finder.run_script('bacon.py')

print('Loaded modules:')
for name, mod in finder.modules.items():
    print('%s: ' % name, end='')
    print(','.join(list(mod.globalnames.keys())[:3]))

print('-'*50)
print('Modules not imported:')
print('\n'.join(finder.badmodules.keys()))

Resultado de ejemplo (puede variar dependiendo de la arquitectura):

Loaded modules:
_types:
copyreg:  _inverted_registry,_slotnames,__all__
sre_compile:  isstring,_sre,_optimize_unicode
_sre:
sre_constants:  REPEAT_ONE,makedict,AT_END_LINE
sys:
re:  __module__,finditer,_expand
itertools:
__main__:  re,itertools,baconhameggs
sre_parse:  _PATTERNENDERS,SRE_FLAG_UNICODE
array:
types:  __module__,IntType,TypeType
---------------------------------------------------
Modules not imported:
guido.python.ham
baconhameggs

runpy — Localización y ejecución de módulos Python

Código Fuente: Lib/runpy.py [https://github.com/python/cpython/tree/3.9/Lib/runpy.py]

El modulo runpy es usado para localizar y correr módulos Python sin importarlo primero. Su uso principal es implementar la opción -m cambiando la linea de comando que permite que los scripts se ubiquen utilizando el espacio de nombres del módulo de Python en lugar del sistema de archivos.

Tenga en cuenta que este no es un módulo de espacio aislado - Todo el código es ejecutado en el proceso actual, y cualquier efecto secundario (como las importaciones en cache de otros módulos) permanecerán en su lugar después de que las funciones hayan retornado.

Además, no se garantiza que las funciones y clases definidas por el código ejecutado funcionen correctamente después de que se haya devuelto la función runpy. Si esa limitación no es aceptable para un caso de uso determinado, es probable que importlib sea una opción más adecuada que este módulo.

El modulo runpy proporciona dos funciones:

runpy.run_module(mod_name, init_globals=None, run_name=None, alter_sys=False)

Ejecute el código del módulo especificado y devuelva el diccionario de globales de módulo resultante. El código del módulo se encuentra primero mediante el mecanismo de importación estándar (consulte PEP 302 [https://www.python.org/dev/peps/pep-0302] para obtener más información) y, a continuación, se ejecuta en un espacio de nombres de módulo nuevo.

El argumento mod_name debe ser un nombre de módulo absoluto. Si el nombre del paquete se refiere a un paquete en lugar de un módulo normal, entonces ese paquete es importado y el submódulo __main__ dentro de ese paquete luego se ejecuta y se devuelve el diccionario global del módulo resultante.

El argumento de diccionario opcional init_globals se puede utilizar para rellenar previamente el diccionario global del módulo antes de ejecutar el código. El diccionario suministrado no se modificará. Si alguna de las variables globales especiales siguientes se define en el diccionario proporcionado, esas definiciones se reemplazan por run_module().

Las variables globales especiales __name__, __spec__, __file__, __cached__, __loader__ y __package__ se establecen en el diccionario global antes del que el código del módulo sea ejecutado (tenga en cuenta que esto es un conjunto mínimo de variables - otras variables pueden establecerse implícitamente como un detalle de implementación del intérprete).

__name__ se establece en run_name si el argumento opcional no es None, para mod_name + ‘.__main__’` si módulo nombrado es un paquete y al argumento mod_name en caso contrario.

__spec__ se configura apropiadamente para el modulo realmente importado (es decir, __spec__.name siempre será un mod_name o mod_name + ‘.__main__, jamas run_name).

__file__, __cached__, __loader__ y __package__ son basados en la especificación del modulo set as normal.

Si el argumento alter_sys es proporcionado y evaluado a True, entonces sys.argv[0] es actualizado y el valor de __file__ y sys.modules[__name__] es actualizado con un objeto de módulo temporal para el módulo que se esta ejecutado. Ambas sys.argv[0]` y sys.modules[__name__] son restauradas a sus valores originales antes del retorno de la función.

Tenga en cuenta que esta manipulación de sys no es segura para subprocesos. Otros subprocesos pueden ver el módulo parcialmente inicializado, así como la lista alterada de argumentos. Se recomienda que el módulo sys se deje solo al invocar esta función desde código roscado.

Ver también

La opción -m ofrece una funcionalidad equivalente desde la linea de comandos.

Distinto en la versión 3.1: Se agrego la capacidad de ejecutar paquetes buscando un submódulo __main__.

Distinto en la versión 3.2: Se agrego la variable global __cached__ (consultar PEP 3147 [https://www.python.org/dev/peps/pep-3147]).

Distinto en la versión 3.4: Se ha actualizado para aprovechar la función de especificación de módulo agregada por PEP 451 [https://www.python.org/dev/peps/pep-0451]. Esto permite que __cached__ se establezca correctamente para que los módulos se ejecuten de esta manera, así como asegurarse de que el nombre real del módulo siempre sea accesible como __spec__.name.

runpy.run_path(path_name, init_globals=None, run_name=None)

Ejecute el código en la ubicación del sistema de archivos con nombre y devuelva el diccionario de globales de módulo resultante. Al igual que con un nombre de script proporcionado a la línea de comandos de CPython, la ruta de acceso proporcionada puede hacer referencia a un archivo de origen de Python, un archivo de código de bytes compilado o una entrada sys.path válida que contiene un módulo __main__ (por ejemplo, un archivo zip que contiene un archivo __main__.py de nivel superior).

Para un script simple, el código especificado se ejecuta simplemente en un espacio de nombres de un módulo nuevo. Para un entrada sys.path valida (comúnmente es un archivo zip o un directorio), la entrada se agrega primero al comienzo de sys.path. La función busca y ejecuta un modulo __main__ usando la ruta actualizada. Tenga en cuenta que no existe una protección especial contra la invocación de una entrada existente __main__ ubicada en otro lugar en sys.path si no hay tal módulo en la ubicación especificada.

El argumento de diccionario opcional init_globals se puede utilizar para rellenar previamente el diccionario global del módulo antes de ejecutar el código. El diccionario suministrado no se modificará. Si alguna de las variables globales especiales siguientes se define en el diccionario proporcionado, esas definiciones se reemplazan por run_path().

Las variables globales especiales __name__, __spec__, __file__, __cached__, __loader__ y __package__ se establecen en el diccionario global antes del que el código del módulo sea ejecutado (tenga en cuenta que esto es un conjunto mínimo de variables - otras variables pueden establecerse implícitamente como un detalle de implementación del intérprete).

__name__ se establece para run_name si el argumento opcional no es None y a '<run_path>' de lo contrario.

Si la ruta proporcionada hace referencia a un archivo script (ya sea como fuente o un código de byte precompilado), entonces __file__ se establecerá en la ruta proporcionada, y __spec__, __cached__, __loader__ y __package__ se establecerán todos en None.

Si la ruta proporciona es una referencia a una entrada sys.path valida, entonces __spec__ se establece apropiadamente para la importación del modulo __main__``(es decir, ``__spec__.name siempre deberá ser __main__). __file__, __cached__, __loader__ y __package__ estarán basadas en la especificación del modulo establecidas como normal.

A number of alterations are also made to the sys module. Firstly, sys.path may be altered as described above. sys.argv[0] is updated with the value of path_name and sys.modules[__name__] is updated with a temporary module object for the module being executed. All modifications to items in sys are reverted before the function returns.

Tenga en cuenta que, diferente a run_module(), las alteraciones hecha a sys no son opcionales en esta función ya que estos ajustes son esenciales para permitir la ejecución de entradas sys.path. Como aún se aplican las limitaciones de seguridad de los subprocesos, el uso de esta función en un código procesado debe serializarse con el bloqueo de importación o delegarse a un proceso separado.

Ver también

Opciones de interfaz para una funcionalidad equivalente en la linea de comandos (python path/to/script).

Nuevo en la versión 3.2.

Distinto en la versión 3.4: Actualizado para aprovechar la función de especificación del módulo agregada por PEP 451 [https://www.python.org/dev/peps/pep-0451]. Esto permite que __cached__ se configure correctamente en el caso de que __main__ se importe de una entrada sys.path valida en lugar de ejecutarse directamente.

Ver también

PEP 338 [https://www.python.org/dev/peps/pep-0338] – Ejecutando módulos como scripts

PEP escrito y implementado por Nick Coghlan.

PEP 366 [https://www.python.org/dev/peps/pep-0366] – Importaciones relativas explícitas del módulo principal

PEP escrito y implementado por Nick Coghlan.

PEP 451 [https://www.python.org/dev/peps/pep-0451] — Un tipo ModuleSpec para el sistema de Importación

PEP escrito y implementado por Eric Snow

Línea de comandos y entorno - Detalles de la linea de comandos CPython

La función importlib.import_module()

importlib — La implementación de import

Nuevo en la versión 3.1.

Código fuente: Lib/importlib/__init__.py [https://github.com/python/cpython/tree/3.9/Lib/importlib/__init__.py]

Introducción

El propósito del paquete importlib es doble. Uno es proveer la implementación de la declaración de import, (y así, por extensión, el método __import__() ) en el código fuente de Python. Esto provee una implementación de la import la cual es compatible con cualquier interprete de Python. También provee una implementación que es más fácil de comprender que otras implementaciones, en lenguajes diferentes a Python.

Dos, los componentes incluidos para implementar import están expuestos en este paquete para que sea más fácil para los usuarios crear sus propios objetos (conocidos de forma genérica como importer) para participar en el proceso de importación.

Ver también

La declaración import

La referencia en el lenguaje para la declaración de import.

Especificaciones de paquetes [https://www.python.org/doc/essays/packages/]

Especificaciones originales de los paquetes. Algunas semánticas han cambiado desde que este documento fue escrito (ejemplo, redirección de acuerdo a None en sys.modules).

La función __import__()

La declaración de import es una decoración sintáctica para esta función.

PEP 235 [https://www.python.org/dev/peps/pep-0235]

Importar en sistemas que no distinguen entre mayúsculas y minúsculas

PEP 263 [https://www.python.org/dev/peps/pep-0263]

Definiendo las codificaciones del código fuente de Python

PEP 302 [https://www.python.org/dev/peps/pep-0302]

Nuevos ganchos de importación

pep:328

Importaciones: Multilíneas, y absolutos/relativos

PEP 366 [https://www.python.org/dev/peps/pep-0366]

Importaciones relativas, explicitas, del módulo principal

PEP 420 [https://www.python.org/dev/peps/pep-0420]

Paquetes implícitos en el espacio de nombres

PEP 451 [https://www.python.org/dev/peps/pep-0451]

Un tipo de ModuleSpec para el sistema de importación

PEP 488 [https://www.python.org/dev/peps/pep-0488]

Eliminación de archivos PYO

PEP 489 [https://www.python.org/dev/peps/pep-0489]

Inicialización de extensión de módulo en múltiples fases

PEP 552 [https://www.python.org/dev/peps/pep-0552]

Pycs determinísticos

PEP 3120 [https://www.python.org/dev/peps/pep-3120]

Usando UTF-8 como la codificación fuente por defecto

PEP 3147 [https://www.python.org/dev/peps/pep-3147]

Repositorio de directorios PYC

Funciones

importlib.__import__(name, globals=None, locals=None, fromlist=(), level=0)

Una implementación de la función __import__() incorporada.

Nota

La importación programática los módulos debe usar import_module() en lugar de esta función.

importlib.import_module(name, package=None)

Importar un módulo. El argumento llamado name especifica qué módulo importar en términos absolutos o relativos (ejemplo, puede ser pkg.mod o ..mod). Si el nombre fuera especificado en términos relativos, entonces el argumento llamado package debe ser igual al nombre del paquete que será el ancla para resolver el nombre del paquete (ejemplo import_module('..mod', 'pkg.subpkg') importará pkg.mod).

La función import_module() actúa como un envoltorio simplificador alrededor de importlib.__import__(). Esto quiere decir que las semánticas de la función son derivadas de importlib.__import__(). La diferencia más importante entre las dos funciones es que import_module() retorna el paquete especificado o el módulo (ejemplo pkg.mod), mientras que __import__() retorna el paquete o módulo del nivel superior (ejemplo pkg).

Si está importando dinámicamente un módulo que se creó desde que el intérprete comenzó la ejecución (por ejemplo, creó un archivo fuente de Python), es posible que deba llamar a invalidate_caches() para que el nuevo módulo sea detectado por el sistema de importación.

Distinto en la versión 3.3: Paquetes padres son importados automáticamente.

importlib.find_loader(name, path=None)

Encuentra el cargador de un módulo, opcionalmente con el especificado en path.Si el módulo esta en sys.modules, entonces retorna el sys.modules[name].__loader__` (a menos que el cargador sea None o no haya uno especificado, en tal caso se eleva un ValueError).Si no se encuentra ahí, se hace una búsqueda usando sys.meta_path. Se retorna None si no se encuentra un cargador.

Un nombre con puntos no tiene sus ascendientes importados implícitamente, ya que eso requeriría cargarlo y eso podría no ser deseado. Para importar un sub-módulo correctamente debes importar todos los paquetes ascendientes del sub-módulo y pase el argumento correcto a path.

Nuevo en la versión 3.3.

Distinto en la versión 3.4: Si el __loader__ no está configurado, eleva un ValueError, igual a si el atributo fuera None.

Obsoleto desde la versión 3.4: Utilice importlib.util.find_spec() en su lugar.

importlib.invalidate_caches()

Invalide los cache internos de ubicadores encontrados en sys.meta_path.Si un buscador implementa invalidate_caches() entonces será llamado para realizar la invalidación.Esta función debe ser llamada si cualquier módulo ha sido creado/instalado mientras tu programa esta siendo ejecutado para garantizar que todos los buscadores noten la existencia del nuevo módulo.

Nuevo en la versión 3.3.

importlib.reload(module)

Recarga un modulo previamente importado. El argumento debe ser un objeto módulo, por lo que debe haber sido importado exitosamente. Esto es útil cuando has editado el código fuente de un archivo usando un editor externo y deseas probar la nueva versión sin abandonar el interprete de Python. El valor retornado es el objeto módulo (que puede ser diferente si la reimportación crea un nuevo objeto en sys.modules).

Cuando reload() es ejecutada:

El código de un módulo de Python es recompilado y el código del módulo reejecutado, definiendo un nuevo conjunto de objetos que son asignados a los nombres de los módulos en el diccionario, reusando el loader que originalmente carga los módulos. El método init de los módulos de extension no es llamado de nuevo.

Al igual que con todos los demás objetos en Python, los objetos antiguos solo se recuperan después de que sus recuentos de referencias caen a cero.

Los nombres en el espacio de nombres del módulo se actualizan para señalar cualquier objeto nuevo o modificado.

Otras referencias a los objetos antiguos (como los nombres externos al módulo) no se vuelven a vincular para hacer referencia a los nuevos objetos y deben actualizarse en cada espacio de nombres donde se produzcan si se desea.

Hay una serie de otras advertencias:

Cuando se vuelve a cargar un módulo, se conserva su diccionario (que contiene las variables globales del módulo). Las redefiniciones de nombres anularán las antiguas definiciones, por lo que generalmente esto no es un problema. Si la nueva versión de un módulo no define un nombre que fue definido por la versión anterior, la definición anterior permanece. Esta característica se puede utilizar en beneficio del módulo si mantiene una tabla global o caché de objetos — con una declaración try puede probar la presencia de la tabla y omitir su inicialización si lo desea:

try:
    cache
except NameError:
    cache = {}

Por lo general, no es muy útil recargar módulos integrados o cargados dinámicamente. No se recomienda recargar sys, __main__, builtins y otros módulos clave. En muchos casos, los módulos de extensión no están diseñados para inicializarse más de una vez y pueden fallar de manera arbitraria cuando se vuelven a cargar.

Si un módulo importa objetos de otro módulo usando from … import …, al llamar a reload() para el otro módulo no redefine los objetos importados de él — una forma de evitar esto es volver a ejecutar la instrucción from, otra es usar import y nombres calificados (module.name) en su lugar.

Si un módulo crea instancias de una clase, volver a cargar el módulo que define la clase no afecta las definiciones de método de las instancias — continúan usando la definición de clase anterior. Lo mismo ocurre con las clases derivadas.

Nuevo en la versión 3.4.

Distinto en la versión 3.7: ModuleNotFoundError se lanza cuando el módulo que se está recargando carece de ModuleSpec.

importlib.abc – Clases base abstractas relacionadas con la importación

Código fuente: Lib/importlib/abc.py [https://github.com/python/cpython/tree/3.9/Lib/importlib/abc.py]

El módulo importlib.abc contiene todas las clases base abstractas principales utilizadas por import. También se proporcionan algunas subclases de las clases base abstractas centrales para ayudar a implementar los ABC centrales.

Jerarquía ABC:

object
 +-- Finder (deprecated)
 |    +-- MetaPathFinder
 |    +-- PathEntryFinder
 +-- Loader
      +-- ResourceLoader --------+
      +-- InspectLoader          |
           +-- ExecutionLoader --+
                                 +-- FileLoader
                                 +-- SourceLoader

class importlib.abc.Finder

Una clase base abstracta que representa finder.

Obsoleto desde la versión 3.3: Utilice MetaPathFinder o PathEntryFinder en su lugar.

abstractmethod find_module(fullname, path=None)

Un método abstracto para encontrar un loader para el módulo especificado. Originalmente especificado en PEP 302 [https://www.python.org/dev/peps/pep-0302], este método estaba destinado a ser utilizado en sys.meta_path y en el subsistema de importación basado en rutas.

Distinto en la versión 3.4: Retorna None cuando se llama en lugar de generar NotImplementedError.

class importlib.abc.MetaPathFinder

Una clase base abstracta que representa un meta path finder. Por compatibilidad, esta es una subclase de Finder.

Nuevo en la versión 3.3.

find_spec(fullname, path, target=None)

Un método abstracto para encontrar un spec para el módulo especificado. Si se trata de una importación de nivel superior, el path será None. De lo contrario, esta es una búsqueda de un subpaquete o módulo y path será el valor de __path__ del paquete principal. Si no se puede encontrar una especificación, se retorna None. Cuando se pasa, target es un objeto de módulo que el buscador puede usar para hacer una suposición más informada sobre qué especificación retornar. importlib.util.spec_from_loader() puede ser útil para implementar MetaPathFinders concretos.

Nuevo en la versión 3.4.

find_module(fullname, path)

Un método heredado para encontrar un loader para el módulo especificado. Si se trata de una importación de nivel superior, el path será None. De lo contrario, esta es una búsqueda de un subpaquete o módulo y path será el valor de __path__ del paquete principal. Si no se puede encontrar un cargador, se retorna None.

Si se define find_spec(), se proporciona una funcionalidad compatible con versiones anteriores.

Distinto en la versión 3.4: Retorna None cuando se llama en lugar de generar NotImplementedError. Puede usar find_spec() para proporcionar funcionalidad.

Obsoleto desde la versión 3.4: Use find_spec() en su lugar.

invalidate_caches()

Un método opcional que, cuando se llama, debería invalidar cualquier caché interno utilizado por el buscador. Utilizado por importlib.invalidate_caches() al invalidar los cachés de todos los buscadores en sys.meta_path.

Distinto en la versión 3.4: Retorna None cuando se llama en lugar de NotImplemented.

class importlib.abc.PathEntryFinder

Una clase base abstracta que representa un path entry finder. Aunque tiene algunas similitudes con MetaPathFinder, PathEntryFinder está diseñado para usarse solo dentro del subsistema de importación basado en rutas proporcionado por PathFinder. Este ABC es una subclase de Finder solo por razones de compatibilidad.

Nuevo en la versión 3.3.

find_spec(fullname, target=None)

Un método abstracto para encontrar un spec para el módulo especificado. El buscador buscará el módulo solo dentro del path entry a la que está asignado. Si no se puede encontrar una especificación, se retorna None. Cuando se pasa, target es un objeto de módulo que el buscador puede usar para hacer una suposición más informada sobre qué especificación retornar. importlib.util.spec_from_loader() puede ser útil para implementar PathEntryFinders concretos.

Nuevo en la versión 3.4.

find_loader(fullname)

Un método heredado para encontrar un loader para el módulo especificado. Retorna una tupla de 2 de (loader, portion) donde portion es una secuencia de ubicaciones del sistema de archivos que contribuyen a parte de un paquete de espacio de nombres. El cargador puede ser None mientras se especifica portion para indicar la contribución de las ubicaciones del sistema de archivos a un paquete de espacio de nombres. Se puede usar una lista vacía para portion para indicar que el cargador no es parte de un paquete de espacio de nombres. Si loader es None y portion es la lista vacía, entonces no se encontró ningún cargador o ubicación para un paquete de espacio de nombres (es decir, no se pudo encontrar nada para el módulo).

Si se define find_spec(), se proporciona una funcionalidad compatible con versiones anteriores.

Distinto en la versión 3.4: Retorna (None, []) en lugar de lanzar NotImplementedError. Usa find_spec() cuando está disponible para proporcionar funcionalidad.

Obsoleto desde la versión 3.4: Use find_spec() en su lugar.

find_module(fullname)

Una implementación concreta de Finder.find_module() que es equivalente a self.find_loader(fullname)[0].

Obsoleto desde la versión 3.4: Use find_spec() en su lugar.

invalidate_caches()

Un método opcional que, cuando se llama, debería invalidar cualquier caché interno utilizado por el buscador. Usado por PathFinder.invalidate_caches() al invalidar las cachés de todos los buscadores en caché.

class importlib.abc.Loader

Una clase base abstracta para un loader. Consulte PEP 302 [https://www.python.org/dev/peps/pep-0302] para obtener la definición exacta de cargador.

Los cargadores que deseen admitir la lectura de recursos deben implementar un método get_resource_reader(fullname) según lo especificado por importlib.abc.ResourceReader.

Distinto en la versión 3.7: Introdujo el método opcional get_resource_reader().

create_module(spec)

Un método que retorna el objeto de módulo que se utilizará al importar un módulo. Este método puede retornar None, lo que indica que se debe llevar a cabo la semántica de creación de módulos predeterminada.

Nuevo en la versión 3.4.

Distinto en la versión 3.5: A partir de Python 3.6, este método no será opcional cuando se defina exec_module().

exec_module(module)

Un método abstracto que ejecuta el módulo en su propio espacio de nombres cuando se importa o se vuelve a cargar un módulo. El módulo ya debería estar inicializado cuando se llama a exec_module(). Cuando existe este método, se debe definir create_module().

Nuevo en la versión 3.4.

Distinto en la versión 3.6: create_module() también debe definirse.

load_module(fullname)

Un método heredado para cargar un módulo. Si el módulo no se puede cargar, se lanza ImportError; de lo contrario, se retorna el módulo cargado.

Si el módulo solicitado ya existe en sys.modules, ese módulo debe usarse y recargarse. De lo contrario, el cargador debe crear un nuevo módulo e insertarlo en sys.modules antes de que comience la carga, para evitar la recursividad de la importación. Si el cargador insertó un módulo y la carga falla, el cargador debe eliminarlo de sys.modules; los módulos que ya están en sys.modules antes de que el cargador comenzara a ejecutarse deben dejarse en paz (ver importlib.util.module_for_loader()).

El cargador debe establecer varios atributos en el módulo. (Tenga en cuenta que algunos de estos atributos pueden cambiar cuando se recarga un módulo):

__name__

El nombre del módulo.

__file__

La ruta hacia donde se almacenan los datos del módulo (no configurada para módulos integrados).

__cached__

La ruta a la que se debe almacenar una versión compilada del módulo (no se establece cuando el atributo sería inapropiado).

__path__

Una lista de cadenas de caracteres que especifican la ruta de búsqueda dentro de un paquete. Este atributo no se establece en módulos.

__package__

El nombre completo del paquete bajo el cual se cargó el módulo como submódulo (o la cadena de caracteres vacía para los módulos de nivel superior). Para los paquetes, es lo mismo que __name__. El decorador importlib.util.module_for_loader() puede manejar los detalles de __package__.

__loader__

El cargador utilizado para cargar el módulo. El decorador importlib.util.module_for_loader() puede manejar los detalles de __package__.

Cuando exec_module() está disponible, se proporciona una funcionalidad compatible con versiones anteriores.

Distinto en la versión 3.4: Lanza ImportError cuando se llama en lugar de NotImplementedError. Funcionalidad proporcionada cuando exec_module() está disponible.

Obsoleto desde la versión 3.4: La API recomendada para cargar un módulo es exec_module() (y create_module()). Los cargadores deberían implementarlo en lugar de load_module(). La maquinaria de importación se encarga de todas las demás responsabilidades de load_module() cuando se implementa exec_module().

module_repr(module)

Un método heredado que, cuando se implementa, calcula y retorna la repr del módulo dado, como una cadena. El repr() predeterminado del tipo de módulo utilizará el resultado de este método según corresponda.

Nuevo en la versión 3.3.

Distinto en la versión 3.4: Hecho opcional en vez de un método abstracto (abstractmethod)

Obsoleto desde la versión 3.4: La maquinaria de importación ahora se encarga de esto automáticamente.

class importlib.abc.ResourceReader

Superseded by TraversableResources

Un abstract base class para proporcionar la capacidad de leer resources.

Desde la perspectiva de este ABC, un resource es un artefacto binario que se envía dentro de un paquete. Por lo general, esto es algo así como un archivo de datos que se encuentra junto al archivo __init__.py del paquete. El propósito de esta clase es ayudar a abstraer el acceso a dichos archivos de datos de modo que no importe si el paquete y sus archivos de datos se almacenan en un, por ejemplo, zip en comparación con el sistema de archivos.

Para cualquiera de los métodos de esta clase, se espera que un argumento resource sea un path-like object que representa conceptualmente solo un nombre de archivo. Esto significa que no se deben incluir rutas de subdirectorio en el argumento resource. Esto se debe a que la ubicación del paquete para el que está ubicado el lector actúa como el «directorio». Por lo tanto, la metáfora de los directorios y los nombres de los archivos son los paquetes y los recursos, respectivamente. Esta es también la razón por la que se espera que las instancias de esta clase se correlacionen directamente con un paquete específico (en lugar de representar potencialmente varios paquetes o un módulo).

Se espera que los cargadores que deseen admitir la lectura de recursos proporcionen un método llamado get_resource_reader(fullname) que retorna un objeto que implementa la interfaz de este ABC. Si el módulo especificado por fullname no es un paquete, este método debería devolver None. Un objeto compatible con este ABC solo debe retornarse cuando el módulo especificado es un paquete.

Nuevo en la versión 3.7.

abstractmethod open_resource(resource)

Retorna un, file-like object abierto para la lectura binaria del resource.

Si no se puede encontrar el recurso, se lanza FileNotFoundError.

abstractmethod resource_path(resource)

Retorna la ruta del sistema de archivos al resource.

Si el recurso no existe concretamente en el sistema de archivos, lanza FileNotFoundError.

abstractmethod is_resource(name)

Retorna True si el name nombrado se considera un recurso. FileNotFoundError se lanza si name no existe.

abstractmethod contents()

Retorna un iterable de cadenas de caracteres sobre el contenido del paquete. Tenga en cuenta que no es necesario que todos los nombres retornados por el iterador sean recursos reales, por ejemplo, es aceptable retornar nombres para los que is_resource() sería falso.

Al permitir que se retornen nombres que no son de recursos es para permitir situaciones en las que se conoce a priori cómo se almacenan un paquete y sus recursos y los nombres que no son de recursos serían útiles. Por ejemplo, se permite el retorno de nombres de subdirectorios para que cuando se sepa que el paquete y los recursos están almacenados en el sistema de archivos, esos nombres de subdirectorios se puedan usar directamente.

El método abstracto retorna un iterable de ningún elemento.

class importlib.abc.ResourceLoader

Una clase base abstracta para un loader que implementa el protocolo opcional PEP 302 [https://www.python.org/dev/peps/pep-0302] para cargar recursos arbitrarios desde el back-end de almacenamiento.

Obsoleto desde la versión 3.7: Este ABC está en desuso a favor de admitir la carga de recursos a través de importlib.abc.ResourceReader.

abstractmethod get_data(path)

Un método abstracto para devolver los bytes de los datos ubicados en path. Los cargadores que tienen un back-end de almacenamiento similar a un archivo que permite almacenar datos arbitrarios pueden implementar este método abstracto para dar acceso directo a los datos almacenados. OSError se lanza si no se puede encontrar el path. Se espera que la path se construya utilizando el atributo __file__ de un módulo o un elemento de un paquete __path__.

Distinto en la versión 3.4: Lanza OSError en vez de NotImplementedError.

class importlib.abc.InspectLoader

Una clase base abstracta para un loader que implementa el protocolo opcional PEP 302 [https://www.python.org/dev/peps/pep-0302] para cargadores que inspeccionan módulos.

get_code(fullname)

Retorna el objeto código para un módulo, o None si el módulo no tiene un objeto código (como sería el caso, por ejemplo, para un módulo integrado). Lanza un ImportError si el cargador no puede encontrar el módulo solicitado.

Nota

Si bien el método tiene una implementación predeterminada, se sugiere que se anule si es posible para mejorar el rendimiento.

Distinto en la versión 3.4: Ya no es un método abstracto y se proporciona una implementación concreta.

abstractmethod get_source(fullname)

Un método abstracto para retornar la fuente de un módulo. Se retorna como una cadena de caracteres de texto usando universal newlines, traduciendo todos los separadores de línea reconocidos en caracteres ' '. Retorna None si no hay una fuente disponible (por ejemplo, un módulo integrado). Lanza ImportError si el cargador no puede encontrar el módulo especificado.

Distinto en la versión 3.4: Lanza ImportError en vez de NotImplementedError.

is_package(fullname)

An optional method to return a true value if the module is a package, a false value otherwise. ImportError is raised if the loader cannot find the module.

Distinto en la versión 3.4: Lanza ImportError en vez de NotImplementedError.

static source_to_code(data, path='<string>')

Cree un objeto de código a partir de la fuente de Python.

El argumento data puede ser cualquier cosa que admita la función compile() (es decir, cadena de caracteres o bytes). El argumento path debe ser la «ruta» de donde se originó el código fuente, que puede ser un concepto abstracto (por ejemplo, ubicación en un archivo zip).

Con el objeto de código subsiguiente, uno puede ejecutarlo en un módulo ejecutando exec(code, module.__dict__).

Nuevo en la versión 3.4.

Distinto en la versión 3.5: Hace el método estático.

exec_module(module)

Implementación de Loader.exec_module().

Nuevo en la versión 3.4.

load_module(fullname)

Implementación de Loader.load_module().

Obsoleto desde la versión 3.4: use exec_module() en su lugar.

class importlib.abc.ExecutionLoader

Una clase base abstracta que hereda de InspectLoader que, cuando se implementa, ayuda a que un módulo se ejecute como un script. El ABC representa un protocolo opcional PEP 302 [https://www.python.org/dev/peps/pep-0302].

abstractmethod get_filename(fullname)

Un método abstracto que retorna el valor de __file__ para el módulo especificado. Si no hay una ruta disponible, se lanza ImportError.

Si el código fuente está disponible, entonces el método debe devolver la ruta al archivo fuente, independientemente de si se utilizó un código de bytes para cargar el módulo.

Distinto en la versión 3.4: Lanza ImportError en vez de NotImplementedError.

class importlib.abc.FileLoader(fullname, path)

Una clase base abstracta que hereda de ResourceLoader y ExecutionLoader, proporcionando implementaciones concretas de ResourceLoader.get_data() y ExecutionLoader.get_filename().

El argumento fullname es un nombre completamente resuelto del módulo que el cargador debe manejar. El argumento path es la ruta al archivo del módulo.

Nuevo en la versión 3.3.

name

El nombre del módulo que puede manejar el cargador.

path

Ruta al archivo del módulo.

load_module(fullname)

Llama a super’s load_module().

Obsoleto desde la versión 3.4: Utilice Loader.exec_module() en su lugar.

abstractmethod get_filename(fullname)

Retorna path.

abstractmethod get_data(path)

Lee path como un archivo binario y devuelve los bytes de él.

class importlib.abc.SourceLoader

Una clase base abstracta para implementar la carga de archivos fuente (y opcionalmente bytecode). La clase hereda tanto de ResourceLoader como de ExecutionLoader, lo que requiere la implementación de:

ResourceLoader.get_data()

ExecutionLoader.get_filename()

Solo debe devolver la ruta al archivo de origen; la carga sin fuente no es compatible.

Los métodos abstractos definidos por esta clase son para agregar soporte de archivo de código de bytes opcional. No implementar estos métodos opcionales (o hacer que se lance NotImplementedError) hace que el cargador solo funcione con el código fuente. La implementación de los métodos permite que el cargador trabaje con archivos fuente y código de bytes; no permite la carga sin fuente donde solo se proporciona un código de bytes. Los archivos de código de bytes son una optimización para acelerar la carga al eliminar el paso de análisis del compilador de Python, por lo que no se expone ninguna API específica de código de bytes.

path_stats(path)

Método abstracto opcional que devuelve un dict que contiene metadatos sobre la ruta especificada. Las claves de diccionario admitidas son:

'mtime' (obligatorio): un número entero o de punto flotante que representa la hora de modificación del código fuente;

'size' (opcional): el tamaño en bytes del código fuente.

Cualquier otra clave del diccionario se ignora para permitir futuras extensiones. Si no se puede manejar la ruta, se genera OSError.

Nuevo en la versión 3.3.

Distinto en la versión 3.4: Lanza OSError en vez de NotImplementedError.

path_mtime(path)

Método abstracto opcional que retorna la hora de modificación de la ruta especificada.

Obsoleto desde la versión 3.3: Este método está obsoleto en favor de path_stats(). No tiene que implementarlo, pero aún está disponible para fines de compatibilidad. Lanza OSError si la ruta no se puede manejar.

Distinto en la versión 3.4: Lanza OSError en vez de NotImplementedError.

set_data(path, data)

Método abstracto opcional que escribe los bytes especificados en una ruta de archivo. Los directorios intermedios que no existan se crearán automáticamente.

Cuando la escritura en la ruta falla porque la ruta es de solo lectura (errno.EACCES/PermissionError), no propague la excepción.

Distinto en la versión 3.4: Ya no lanza NotImplementedError cuando se llama.

get_code(fullname)

Implementación concreta de InspectLoader.get_code().

exec_module(module)

Implementación concreta de Loader.exec_module().

Nuevo en la versión 3.4.

load_module(fullname)

Implementación concreta de Loader.load_module().

Obsoleto desde la versión 3.4: Utilice exec_module() en su lugar.

get_source(fullname)

Implementación concreta de InspectLoader.get_source().

is_package(fullname)

Implementación concreta de InspectLoader.is_package(). Se determina que un módulo es un paquete si su ruta de archivo (proporcionada por ExecutionLoader.get_filename()) es un archivo llamado __init__ cuando se elimina la extensión del archivo y el nombre del módulo sí lo hace no termina en __init__.

class importlib.abc.Traversable

Un objeto con un subconjunto de métodos pathlib.Path adecuados para recorrer directorios y abrir archivos.

Nuevo en la versión 3.9.

abstractmethod name()

The base name of this object without any parent references.

abstractmethod iterdir()

Yield Traversable objects in self.

abstractmethod is_dir()

Return True if self is a directory.

abstractmethod is_file()

Return True if self is a file.

abstractmethod joinpath(child)

Return Traversable child in self.

abstractmethod __truediv__(child)

Return Traversable child in self.

abstractmethod open(mode='r', *args, **kwargs)

mode may be “r” or “rb” to open as text or binary. Return a handle suitable for reading (same as pathlib.Path.open).

When opening as text, accepts encoding parameters such as those accepted by io.TextIOWrapper.

read_bytes()

Read contents of self as bytes.

read_text(encoding=None)

Read contents of self as text.

Note: In Python 3.11 and later, this class is found in importlib.resources.abc.

class importlib.abc.TraversableResources

Una clase base abstracta para lectores de recursos capaz de servir la interfaz de files. Subclases ResourceReader y proporciona implementaciones concretas de los métodos abstractos de ResourceReader. Por lo tanto, cualquier cargador que suministre TraversableReader también suministra ResourceReader.

Nuevo en la versión 3.9.

Note: In Python 3.11 and later, this class is found in importlib.resources.abc.

importlib.resources – Recursos

Código fuente: Lib/importlib/resources.py [https://github.com/python/cpython/tree/3.9/Lib/importlib/resources.py]

Nuevo en la versión 3.7.

Este módulo aprovecha el sistema de importación de Python para proporcionar acceso a resources dentro de packages. Si puede importar un paquete, puede acceder a los recursos dentro de ese paquete. Los recursos se pueden abrir o leer, ya sea en modo binario o texto.

Los recursos son similares a los archivos dentro de los directorios, aunque es importante tener en cuenta que esto es solo una metáfora. Los recursos y paquetes no tienen que existir como archivos y directorios físicos en el sistema de archivos.

Nota

Este módulo proporciona una funcionalidad similar a pkg_resources [https://setuptools.readthedocs.io/en/latest/pkg_resources.html] Acceso Básico a Recursos [http://setuptools.readthedocs.io/en/latest/pkg_resources.html#basic-resource-access] sin la sobrecarga de rendimiento de ese paquete. Esto facilita la lectura de los recursos incluidos en los paquetes, con una semántica más estable y coherente.

El backport independiente de este módulo proporciona más información sobre usar importlib.resources [http://importlib-resources.readthedocs.io/en/latest/using.html] y migrar desde pkg_resources a importlib.resources [http://importlib-resources.readthedocs.io/en/latest/migration.html].

Los cargadores que deseen admitir la lectura de recursos deben implementar un método get_resource_reader(fullname) según lo especificado por importlib.abc.ResourceReader.

Se definen los siguientes tipos.

importlib.resources.Package

El tipo Package se define como Union[str, ModuleType]. Esto significa que cuando la función describe la aceptación de un Package, puede pasar una cadena de caracteres o un módulo. Los objetos de módulo deben tener un __spec__.submodule_search_locations que se pueda resolver que no sea None.

importlib.resources.Resource

Este tipo describe los nombres de los recursos que se pasan a las distintas funciones de este paquete. Esto se define como Union[str, os.PathLike].

Están disponibles las siguientes funciones.

importlib.resources.files(package)

Returns an importlib.abc.Traversable object representing the resource container for the package (think directory) and its resources (think files). A Traversable may contain other containers (think subdirectories).

package es un nombre o un objeto de módulo que cumple con los requisitos de Package.

Nuevo en la versión 3.9.

importlib.resources.as_file(traversable)

Given a importlib.abc.Traversable object representing a file, typically from importlib.resources.files(), return a context manager for use in a with statement. The context manager provides a pathlib.Path object.

Exiting the context manager cleans up any temporary file created when the resource was extracted from e.g. a zip file.

Use as_file when the Traversable methods (read_text, etc) are insufficient and an actual file on the file system is required.

Nuevo en la versión 3.9.

importlib.resources.open_binary(package, resource)

Abra para lectura binaria el resource dentro del package.

package es un nombre o un objeto de módulo que cumple con los requisitos de Package. resource es el nombre del recurso a abrir dentro de package; puede que no contenga separadores de ruta y puede que no tenga sub-recursos (es decir, no puede ser un directorio). Esta función retorna una instancia de typing.BinaryIO, un flujo de E/S binario abierto para lectura.

importlib.resources.open_text(package, resource, encoding='utf-8', errors='strict')

Se abre para leer el texto del resource dentro del package. De forma predeterminada, el recurso está abierto para lectura como UTF-8.

package es un nombre o un objeto de módulo que cumple con los requisitos de Package. resource es el nombre del recurso a abrir dentro de package; puede que no contenga separadores de ruta y puede que no tenga sub-recursos (es decir, no puede ser un directorio). encoding y errors tienen el mismo significado que con la función integrada open().

Esta función retorna una instancia de typing.TextIO, un flujo de E/S de texto abierto para lectura.

importlib.resources.read_binary(package, resource)

Lee y retorna el contenido del resource dentro del package como bytes.

package es un nombre o un objeto de módulo que cumple con los requisitos de Package. resource es el nombre del recurso a abrir dentro de package; puede que no contenga separadores de ruta y puede que no tenga sub-recursos (es decir, no puede ser un directorio). Esta función retorna el contenido del recurso como bytes.

importlib.resources.read_text(package, resource, encoding='utf-8', errors='strict')

Lee y retorna el contenido de resource dentro de package como un str. De forma predeterminada, los contenidos se leen como UTF-8 estricto.

package es un nombre o un objeto de módulo que cumple con los requisitos de Package. resource es el nombre del recurso a abrir dentro de package; puede que no contenga separadores de ruta y puede que no tenga sub-recursos (es decir, no puede ser un directorio). encoding y errors tienen el mismo significado que con la función integrada open(). Esta función retorna el contenido del recurso como str.

importlib.resources.path(package, resource)

Retorna la ruta al resource como una ruta real del sistema de archivos. Esta función retorna un administrador de contexto para usar en una declaración with. El administrador de contexto proporciona un objeto pathlib.Path.

Salir del administrador de contexto limpia cualquier archivo temporal creado cuando el recurso necesita ser extraído, por ejemplo, un archivo zip.

package es un nombre o un objeto de módulo que cumple con los requisitos de Package. resource es el nombre del recurso a abrir dentro de package; puede que no contenga separadores de ruta y puede que no tenga sub-recursos (es decir, no puede ser un directorio).

importlib.resources.is_resource(package, name)

Retorna True si hay un recurso llamado name en el paquete; de lo contrario, False. ¡Recuerde que los directorios no son recursos! package es un nombre o un objeto de módulo que cumple con los requisitos de Package.

importlib.resources.contents(package)

Retorna un iterable sobre los elementos nombrados dentro del paquete. El iterable retorna recursos str (por ejemplo, archivos) y no-recursos (por ejemplo, directorios). El iterable no recurre a subdirectorios.

package es un nombre o un objeto de módulo que cumple con los requisitos de Package.

importlib.machinery – Importadores y enlaces de ruta

Código fuente: Lib/importlib/machinery.py [https://github.com/python/cpython/tree/3.9/Lib/importlib/machinery.py]

Este módulo contiene varios objetos que ayudan import buscar y cargar módulos.

importlib.machinery.SOURCE_SUFFIXES

Una lista de cadenas de caracteres que representan los sufijos de archivo reconocidos para los módulos de origen.

Nuevo en la versión 3.3.

importlib.machinery.DEBUG_BYTECODE_SUFFIXES

Una lista de cadenas que representan los sufijos de archivo para módulos de código de bytes no optimizados.

Nuevo en la versión 3.3.

Obsoleto desde la versión 3.5: Utilice BYTECODE_SUFFIXES en su lugar.

importlib.machinery.OPTIMIZED_BYTECODE_SUFFIXES

Una lista de cadenas de caracteres que representan los sufijos de archivo para módulos de código de bytes optimizados.

Nuevo en la versión 3.3.

Obsoleto desde la versión 3.5: Utilice BYTECODE_SUFFIXES en su lugar.

importlib.machinery.BYTECODE_SUFFIXES

Una lista de cadenas de caracteres que representan los sufijos de archivo reconocidos para los módulos de código de bytes (incluido el punto inicial).

Nuevo en la versión 3.3.

Distinto en la versión 3.5: El valor ya no depende de __debug__.

importlib.machinery.EXTENSION_SUFFIXES

Una lista de cadenas de caracteres que representan los sufijos de archivo reconocidos para los módulos de extensión.

Nuevo en la versión 3.3.

importlib.machinery.all_suffixes()

Retorna una lista combinada de cadenas de caracteres que representan todos los sufijos de archivo para módulos reconocidos por la maquinaria de importación estándar. Este es un ayudante para el código que simplemente necesita saber si una ruta del sistema de archivos potencialmente se refiere a un módulo sin necesidad de detalles sobre el tipo de módulo (por ejemplo, inspect.getmodulename()).

Nuevo en la versión 3.3.

class importlib.machinery.BuiltinImporter

Un importer para módulos integrados. Todos los módulos integrados conocidos se enumeran en sys.builtin_module_names. Esta clase implementa los ABC importlib.abc.MetaPathFinder y importlib.abc.InspectLoader.

Esta clase solo define los métodos de clase para aliviar la necesidad de instanciación.

Distinto en la versión 3.5: Como parte de PEP 489 [https://www.python.org/dev/peps/pep-0489], el importador integrado ahora implementa Loader.create_module() y Loader.exec_module()

class importlib.machinery.FrozenImporter

Un importer para módulos congelados. Esta clase implementa los ABC importlib.abc.MetaPathFinder y importlib.abc.InspectLoader.

Esta clase solo define los métodos de clase para aliviar la necesidad de instanciación.

Distinto en la versión 3.4: Métodos obtenidos create_module() y exec_module().

class importlib.machinery.WindowsRegistryFinder

Finder para los módulos declarados en el registro de Windows. Esta clase implementa el importlib.abc.MetaPathFinder ABC.

Esta clase solo define los métodos de clase para aliviar la necesidad de instanciación.

Nuevo en la versión 3.3.

Obsoleto desde la versión 3.6: Utilice la configuración de site en su lugar. Es posible que las versiones futuras de Python no habiliten este buscador de forma predeterminada.

class importlib.machinery.PathFinder

Un Finder para sys.path y atributos del paquete __path__. Esta clase implementa el importlib.abc.MetaPathFinder ABC.

Esta clase solo define los métodos de clase para aliviar la necesidad de instanciación.

classmethod find_spec(fullname, path=None, target=None)

Método de clase que intenta encontrar un spec para el módulo especificado por fullname en sys.path o, si está definido, en path. Para cada entrada de ruta que se busca, se comprueba sys.path_importer_cache. Si se encuentra un objeto que no es falso, se utiliza como path entry finder para buscar el módulo que se está buscando. Si no se encuentra ninguna entrada en sys.path_importer_cache, entonces sys.path_hooks se busca un buscador para la entrada de ruta y, si se encuentra, se almacena en sys.path_importer_cache junto con ser consultado sobre el módulo. Si nunca se encuentra ningún buscador, entonces None se almacena en el caché y se retorna.

Nuevo en la versión 3.4.

Distinto en la versión 3.5: Si el directorio de trabajo actual, representado por una cadena de caracteres vacía, ya no es válido, se retorna``None`` pero no se almacena ningún valor en sys.path_importer_cache.

classmethod find_module(fullname, path=None)

Una envoltura heredada alrededor de find_spec().

Obsoleto desde la versión 3.4: Use find_spec() en su lugar.

classmethod invalidate_caches()

Llama importlib.abc.PathEntryFinder.invalidate_caches() en todos los buscadores almacenados en sys.path_importer_cache que definen el método. De lo contrario, las entradas en sys.path_importer_cache establecidas en None se eliminan.

Distinto en la versión 3.7: Se eliminan las entradas de None en sys.path_importer_cache.

Distinto en la versión 3.4: Llama a objetos en sys.path_hooks con el directorio de trabajo actual para '' (es decir, la cadena de caracteres vacía).

class importlib.machinery.FileFinder(path, *loader_details)

Una implementación concreta de importlib.abc.PathEntryFinder que almacena en caché los resultados del sistema de archivos.

El argumento path es el directorio que el buscador se encarga de buscar.

El argumento loader_details es un número variable de tuplas de 2 elementos, cada una de las cuales contiene un cargador y una secuencia de sufijos de archivo que el cargador reconoce. Se espera que los cargadores sean invocables que acepten dos argumentos del nombre del módulo y la ruta al archivo encontrado.

El buscador almacenará en caché el contenido del directorio según sea necesario, haciendo llamadas estadísticas para cada búsqueda de módulo para verificar que la caché no esté desactualizada. Debido a que la obsolescencia de la caché se basa en la granularidad de la información de estado del sistema operativo del sistema de archivos, existe una condición de carrera potencial de buscar un módulo, crear un nuevo archivo y luego buscar el módulo que representa el nuevo archivo. Si las operaciones ocurren lo suficientemente rápido como para ajustarse a la granularidad de las llamadas estadísticas, la búsqueda del módulo fallará. Para evitar que esto suceda, cuando cree un módulo dinámicamente, asegúrese de llamar a importlib.invalidate_caches().

Nuevo en la versión 3.3.

path

La ruta en la que buscará el buscador.

find_spec(fullname, target=None)

Intente encontrar la especificación para manejar fullname dentro de path.

Nuevo en la versión 3.4.

find_loader(fullname)

Intente encontrar el cargador para manejar fullname dentro de path.

invalidate_caches()

Borrar el caché interno.

classmethod path_hook(*loader_details)

Un método de clase que devuelve un cierre para su uso en sys.path_hooks. Una instancia de FileFinder es retornada por el cierre usando el argumento de ruta dado al cierre directamente y loader_details indirectamente.

Si el argumento del cierre no es un directorio existente, se lanza ImportError.

class importlib.machinery.SourceFileLoader(fullname, path)

Una implementación concreta de importlib.abc.SourceLoader subclasificando importlib.abc.FileLoader y proporcionando algunas implementaciones concretas de otros métodos.

Nuevo en la versión 3.3.

name

El nombre del módulo que manejará este cargador.

path

La ruta al archivo de origen.

is_package(fullname)

Devuelve True si path parece ser para un paquete.

path_stats(path)

Implementación concreta de importlib.abc.SourceLoader.path_stats().

set_data(path, data)

Implementación concreta de importlib.abc.SourceLoader.set_data().

load_module(name=None)

Implementación concreta de importlib.abc.Loader.load_module() donde especificar el nombre del módulo a cargar es opcional.

Obsoleto desde la versión 3.6: Utilice importlib.abc.Loader.exec_module() en su lugar.

class importlib.machinery.SourcelessFileLoader(fullname, path)

Una implementación concreta de importlib.abc.FileLoader que puede importar archivos de código de bytes (es decir, no existen archivos de código fuente).

Tenga en cuenta que el uso directo de archivos de código de bytes (y, por lo tanto, no de archivos de código fuente) impide que sus módulos sean utilizables por todas las implementaciones de Python o las nuevas versiones de Python que cambian el formato de código de bytes.

Nuevo en la versión 3.3.

name

El nombre del módulo que manejará el cargador.

path

La ruta al archivo de código de bytes.

is_package(fullname)

Determina si el módulo es un paquete basado en path.

get_code(fullname)

Retorna el objeto de código para name creado a partir de path.

get_source(fullname)

Devuelve None ya que los archivos de código de bytes no tienen fuente cuando se usa este cargador.

load_module(name=None)

Implementación concreta de importlib.abc.Loader.load_module() donde especificar el nombre del módulo a cargar es opcional.

Obsoleto desde la versión 3.6: Utilice importlib.abc.Loader.exec_module() en su lugar.

class importlib.machinery.ExtensionFileLoader(fullname, path)

Una implementación concreta de importlib.abc.ExecutionLoader para módulos de extensión.

El argumento fullname especifica el nombre del módulo que el cargador debe admitir. El argumento path es la ruta al archivo del módulo de extensión.

Nuevo en la versión 3.3.

name

Nombre del módulo que admite el cargador.

path

Ruta al módulo de extensión.

create_module(spec)

Crea el objeto de módulo a partir de la especificación dada de acuerdo con PEP 489 [https://www.python.org/dev/peps/pep-0489].

Nuevo en la versión 3.5.

exec_module(module)

Inicializa el objeto de módulo dado de acuerdo con PEP 489 [https://www.python.org/dev/peps/pep-0489].

Nuevo en la versión 3.5.

is_package(fullname)

Retorna True si la ruta del archivo apunta al módulo __init__ de un paquete basado en EXTENSION_SUFFIXES.

get_code(fullname)

Retorna None ya que los módulos de extensión carecen de un objeto de código.

get_source(fullname)

Retorna None ya que los módulos de extensión no tienen código fuente.

get_filename(fullname)

Retorna path.

Nuevo en la versión 3.4.

class importlib.machinery.ModuleSpec(name, loader, *, origin=None, loader_state=None, is_package=None)

Una especificación para el estado relacionado con el sistema de importación de un módulo. Esto generalmente se expone como el atributo __spec__ del módulo. En las descripciones siguientes, los nombres entre paréntesis dan el atributo correspondiente disponible directamente en el objeto del módulo, por ejemplo, module.__spec__.origin == module.__file__. Sin embargo, tenga en cuenta que, si bien los values suelen ser equivalentes, pueden diferir ya que no hay sincronización entre los dos objetos. Por lo tanto, es posible actualizar el __path__ del módulo en tiempo de ejecución, y esto no se reflejará automáticamente en __spec__.submodule_search_locations.

Nuevo en la versión 3.4.

name

(__name__)

Una cadena de caracteres para el nombre completo del módulo.

loader

(__loader__)

El Loader que debe usarse al cargar el módulo. Finders siempre debe establecer esto.

origin

(__file__)

Nombre del lugar desde el que se carga el módulo, por ejemplo «incorporado» (builtin) para los módulos incorporados y el nombre de archivo para los módulos cargados desde la fuente. Normalmente se debe establecer «origen», pero puede ser None (el valor predeterminado), lo que indica que no está especificado (por ejemplo, para paquetes de espacio de nombres).

submodule_search_locations

(__path__)

Lista de cadenas de caracteres de dónde encontrar submódulos, si es un paquete (None de lo contrario).

loader_state

Contenedor de datos adicionales específicos del módulo para usar durante la carga (o None).

cached

(__cached__)

Cadena de caracteres para el lugar donde se debe almacenar el módulo compilado (o None).

parent

(__package__)

(Solo lectura) El nombre completo del paquete bajo el cual se debe cargar el módulo como submódulo (o la cadena de caracteres vacía para los módulos de nivel superior). Para los paquetes, es lo mismo que __name__.

has_location

Booleano que indica si el atributo «origen» del módulo se refiere a una ubicación cargable.

importlib.util – Código de utilidad para importadores

Código fuente: Lib/importlib/util.py [https://github.com/python/cpython/tree/3.9/Lib/importlib/util.py]

Este módulo contiene los diversos objetos que ayudan en la construcción de un importer.

importlib.util.MAGIC_NUMBER

Los bytes que representan el número de versión del código de bytes. Si necesita ayuda para cargar/escribir código de bytes, considere importlib.abc.SourceLoader.

Nuevo en la versión 3.4.

importlib.util.cache_from_source(path, debug_override=None, *, optimization=None)

Retorna la ruta PEP 3147 [https://www.python.org/dev/peps/pep-3147]/PEP 488 [https://www.python.org/dev/peps/pep-0488] al archivo compilado por bytes asociado con la path de origen. Por ejemplo, si path es /foo/bar/baz.py, el valor de retorno sería /foo/bar/__pycache__/baz.cpython-32.pyc para Python 3.2. La cadena de caracteres cpython-32 proviene de la etiqueta mágica actual (ver get_tag(); si sys.implementation.cache_tag no está definido, se lanzará NotImplementedError).

El parámetro optimization se utiliza para especificar el nivel de optimización del archivo de código de bytes. Una cadena de caracteres vacía no representa optimización, por lo que /foo/bar/baz.py con una optimization de '' dará como resultado una ruta de código de bytes de /foo/bar/__pycache__/baz.cpython-32.pyc. None hace que se utilice el nivel de optimización del intérprete. Se usa la representación de cadena de caracteres de cualquier otro valor, por lo que /foo/bar/baz.py con una optimization de 2 conducirá a la ruta del código de bytes de /foo/bar/__pycache__/baz.cpython-32.opt-2.pyc. La representación de cadena de caracteres optimization solo puede ser alfanumérica, de lo contrario se lanza ValueError.

El parámetro debug_override está obsoleto y se puede usar para anular el valor del sistema para __debug__. Un valor True es el equivalente a establecer optimization en la cadena de caracteres vacía. Un valor False es lo mismo que establecer optimization en 1. Si tanto debug_override como optimization no es None, entonces se lanza TypeError.

Nuevo en la versión 3.4.

Distinto en la versión 3.5: Se agregó el parámetro optimization y el parámetro debug_override quedó obsoleto.

Distinto en la versión 3.6: Acepta un path-like object.

importlib.util.source_from_cache(path)

Dado el path a un nombre de archivo PEP 3147 [https://www.python.org/dev/peps/pep-3147], retorna la ruta del archivo del código fuente asociado. Por ejemplo, si path es /foo/bar/__pycache__/baz.cpython-32.pyc, la ruta retornada sería /foo/bar/baz.py. path no necesita existir, sin embargo, si no se ajusta al formato PEP 3147 [https://www.python.org/dev/peps/pep-3147] o PEP 488 [https://www.python.org/dev/peps/pep-0488], se lanza un ValueError. Si sys.implementation.cache_tag no está definido, se lanza NotImplementedError.

Nuevo en la versión 3.4.

Distinto en la versión 3.6: Acepta un path-like object.

importlib.util.decode_source(source_bytes)

Decodifica los bytes dados que representan el código fuente y los retorna como una cadena de caracteres con nuevas líneas universales (como lo requiere importlib.abc.InspectLoader.get_source()).

Nuevo en la versión 3.4.

importlib.util.resolve_name(name, package)

Resuelve un nombre de módulo relativo a uno absoluto.

Si name no tiene puntos iniciales, entonces name simplemente se retorna. Esto permite el uso como importlib.util.resolve_name('sys', __spec__.parent) sin hacer una verificación para ver si se necesita el argumento package.

ImportError se lanza si name es un nombre de módulo relativo pero package es un valor falso (por ejemplo, None o la cadena de caracteres vacía). También se lanza ImportError un nombre relativo que escaparía del paquete que lo contiene (por ejemplo, solicitando ..bacon desde el paquete spam).

Nuevo en la versión 3.3.

Distinto en la versión 3.9: Para mejorar la coherencia con las declaraciones de importación, aumente ImportError en lugar de ValueError para intentos de importación relativa no válidos.

importlib.util.find_spec(name, package=None)

Busca el spec para un módulo, opcionalmente relativo al nombre del package especificado. Si el módulo está en sys.modules, se retorna sys.modules[name].__spec__ (a menos que la especificación sea None o no esté establecida, en cuyo caso se lanza ValueError). De lo contrario, se realiza una búsqueda utilizando sys.meta_path. Se retorna None si no se encuentra ninguna especificación.

Si name es para un submódulo (contiene un punto), el módulo principal se importa automáticamente.

name y package funcionan igual que para import_module().

Nuevo en la versión 3.4.

Distinto en la versión 3.7: Lanza ModuleNotFoundError en lugar de AttributeError si package no es de hecho un paquete (es decir, carece de un atributo __path__).

importlib.util.module_from_spec(spec)

Cree un nuevo módulo basado en spec y spec.loader.create_module.

Si spec.loader.create_module no retorna None, no se restablecerán los atributos preexistentes. Además, no se lanzará AttributeError si se activa mientras se accede a spec o se establece un atributo en el módulo.

Esta función es preferible a usar types.ModuleType para crear un nuevo módulo ya que spec se usa para establecer tantos atributos de importación controlados en el módulo como sea posible.

Nuevo en la versión 3.5.

@importlib.util.module_for_loader

Un decorator para importlib.abc.Loader.load_module() para manejar la selección del objeto de módulo adecuado para cargar. Se espera que el método decorado tenga una firma de llamada que tome dos argumentos posicionales (por ejemplo, load_module(self, module)) para los cuales el segundo argumento será el módulo object que usará el cargador. Tenga en cuenta que el decorador no funcionará con métodos estáticos debido a la suposición de dos argumentos.

El método decorado tomará el name del módulo que se cargará como se esperaba para un loader. Si el módulo no se encuentra en sys.modules, se construye uno nuevo. Independientemente de la procedencia del módulo, __loader__ se establece en self y __package__ se establece en función de lo que retorna importlib.abc.InspectLoader.is_package() (si está disponible) . Estos atributos se establecen incondicionalmente para admitir la recarga.

Si el método decorado lanza una excepción y se agrega un módulo a sys.modules, entonces el módulo se eliminará para evitar que un módulo parcialmente inicializado quede en sys.modules. Si el módulo ya estaba en sys.modules entonces se deja solo.

Distinto en la versión 3.3: __loader__ y __package__ se configuran automáticamente (cuando es posible).

Distinto en la versión 3.4: Establece __name__, __loader__ __package__ incondicionalmente para apoyar la recarga.

Obsoleto desde la versión 3.4: La maquinaria de importación ahora realiza directamente toda la funcionalidad proporcionada por esta función.

@importlib.util.set_loader

Un decorator para importlib.abc.Loader.load_module() para establecer el atributo __loader__ en el módulo retornado. Si el atributo ya está configurado, el decorador no hace nada. Se asume que el primer argumento posicional del método envuelto (es decir, self) es lo que se debe establecer en __loader__.

Distinto en la versión 3.4: Establece __loader__ si está configurado como None, como si el atributo no existiera.

Obsoleto desde la versión 3.4: La maquinaria de importación se encarga de esto automáticamente.

@importlib.util.set_package

Un decorator para importlib.abc.Loader.load_module() para establecer el atributo __package__ en el módulo retornado. Si __package__ está configurado y tiene un valor diferente a None, no se cambiará.

Obsoleto desde la versión 3.4: La maquinaria de importación se encarga de esto automáticamente.

importlib.util.spec_from_loader(name, loader, *, origin=None, is_package=None)

Una función de fábrica para crear una instancia ModuleSpec basada en un cargador. Los parámetros tienen el mismo significado que para ModuleSpec. La función utiliza APIs disponibles loader, como InspectLoader.is_package(), para completar cualquier información que falte en la especificación.

Nuevo en la versión 3.4.

importlib.util.spec_from_file_location(name, location, *, loader=None, submodule_search_locations=None)

Una función de fábrica para crear una instancia ModuleSpec basada en la ruta a un archivo. La información que falte se completará en la especificación mediante el uso de las API de carga y la implicación de que el módulo estará basado en archivos.

Nuevo en la versión 3.4.

Distinto en la versión 3.6: Acepta un path-like object.

importlib.util.source_hash(source_bytes)

Retorna el hash de source_bytes como bytes. Un archivo .pyc basado en hash incrusta source_hash() del contenido del archivo fuente correspondiente en su encabezado.

Nuevo en la versión 3.7.

class importlib.util.LazyLoader(loader)

Una clase que pospone la ejecución del cargador de un módulo hasta que el módulo tiene acceso a un atributo.

Esta clase solo funciona con cargadores que definen exec_module() ya que se requiere control sobre qué tipo de módulo se usa para el módulo. Por esas mismas razones, el método del cargador create_module() debe retornar None o un tipo para el cual su atributo __class__ se puede mutar junto con no usar slots. Finalmente, los módulos que sustituyen el objeto colocado en sys.modules no funcionarán ya que no hay forma de reemplazar correctamente las referencias del módulo en todo el intérprete de forma segura; ValueError se genera si se detecta tal sustitución.

Nota

Para proyectos donde el tiempo de inicio es crítico, esta clase permite minimizar potencialmente el costo de cargar un módulo si nunca se usa. Para proyectos en los que el tiempo de inicio no es esencial, el uso de esta clase se desaconseja en gran medida debido a que los mensajes de error creados durante la carga se posponen y, por lo tanto, ocurren fuera de contexto.

Nuevo en la versión 3.5.

Distinto en la versión 3.6: Comenzó a llamar create_module(), eliminando la advertencia de compatibilidad para importlib.machinery.BuiltinImporter y importlib.machinery.ExtensionFileLoader.

classmethod factory(loader)

Un método estático que devuelve un invocable que crea un cargador diferido. Esto está destinado a utilizarse en situaciones en las que el cargador se pasa por clase en lugar de por instancia.

suffixes = importlib.machinery.SOURCE_SUFFIXES
loader = importlib.machinery.SourceFileLoader
lazy_loader = importlib.util.LazyLoader.factory(loader)
finder = importlib.machinery.FileFinder(path, (lazy_loader, suffixes))

Ejemplos

Importar programáticamente

Para importar un módulo mediante programación, use importlib.import_module().

import importlib

itertools = importlib.import_module('itertools')

Comprobando si se puede importar un módulo

Si necesita averiguar si un módulo se puede importar sin realmente realizar la importación, entonces debe usar importlib.util.find_spec().

import importlib.util
import sys

# For illustrative purposes.
name = 'itertools'

if name in sys.modules:
    print(f"{name!r} already in sys.modules")
elif (spec := importlib.util.find_spec(name)) is not None:
    # If you chose to perform the actual import ...
    module = importlib.util.module_from_spec(spec)
    sys.modules[name] = module
    spec.loader.exec_module(module)
    print(f"{name!r} has been imported")
else:
    print(f"can't find the {name!r} module")

Importar un archivo fuente directamente

Para importar un archivo fuente de Python directamente, use la siguiente receta (solo Python 3.5 y más reciente):

import importlib.util
import sys

# For illustrative purposes.
import tokenize
file_path = tokenize.__file__
module_name = tokenize.__name__

spec = importlib.util.spec_from_file_location(module_name, file_path)
module = importlib.util.module_from_spec(spec)
sys.modules[module_name] = module
spec.loader.exec_module(module)

Configurar un importador

Para personalizaciones profundas de la importación, normalmente desea implementar un importador. Esto significa administrar tanto el lado finder como loader de las cosas. Para los buscadores, hay dos sabores para elegir según sus necesidades: un meta path finder o un path entry finder. El primero es lo que pondrías en sys.meta_path mientras que el segundo es lo que creas usando un path entry hook en sys.path_hooks que funciona con sys .path entradas para crear potencialmente un buscador. Este ejemplo le mostrará cómo registrar sus propios importadores para que import los utilice (para crear un importador para usted, lea la documentación de las clases apropiadas definidas dentro de este paquete):

import importlib.machinery
import sys

# For illustrative purposes only.
SpamMetaPathFinder = importlib.machinery.PathFinder
SpamPathEntryFinder = importlib.machinery.FileFinder
loader_details = (importlib.machinery.SourceFileLoader,
                  importlib.machinery.SOURCE_SUFFIXES)

# Setting up a meta path finder.
# Make sure to put the finder in the proper location in the list in terms of
# priority.
sys.meta_path.append(SpamMetaPathFinder)

# Setting up a path entry finder.
# Make sure to put the path hook in the proper location in the list in terms
# of priority.
sys.path_hooks.append(SpamPathEntryFinder.path_hook(loader_details))

Aproximando importlib.import_module()

La importación en sí está implementada en código Python, lo que permite exponer la mayor parte de la maquinaria de importación a través de importlib. Lo siguiente ayuda a ilustrar las diversas API que importlib expone al proporcionar una implementación aproximada de importlib.import_module() (Python 3.4 y más reciente para el uso de importlib, Python 3.6 y más reciente para otras partes del código).

import importlib.util
import sys

def import_module(name, package=None):
    """An approximate implementation of import."""
    absolute_name = importlib.util.resolve_name(name, package)
    try:
        return sys.modules[absolute_name]
    except KeyError:
        pass

    path = None
    if '.' in absolute_name:
        parent_name, _, child_name = absolute_name.rpartition('.')
        parent_module = import_module(parent_name)
        path = parent_module.__spec__.submodule_search_locations
    for finder in sys.meta_path:
        spec = finder.find_spec(absolute_name, path)
        if spec is not None:
            break
    else:
        msg = f'No module named {absolute_name!r}'
        raise ModuleNotFoundError(msg, name=absolute_name)
    module = importlib.util.module_from_spec(spec)
    sys.modules[absolute_name] = module
    spec.loader.exec_module(module)
    if path is not None:
        setattr(parent_module, child_name, module)
    return module

Usando importlib.metadata

Source code: Lib/importlib/metadata.py [https://github.com/python/cpython/tree/3.9/Lib/importlib/metadata.py]

Nuevo en la versión 3.8.

Nota

Esta funcionalidad es provisional y puede desviarse de la versión habitual de la semántica de la librería estándar.

importlib.metadata is a library that provides for access to installed package metadata. Built in part on Python’s import system, this library intends to replace similar functionality in the entry point API [https://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry-points] and metadata API [https://setuptools.readthedocs.io/en/latest/pkg_resources.html#metadata-api] of pkg_resources. Along with importlib.resources in Python 3.7 and newer (backported as importlib_resources [https://importlib-resources.readthedocs.io/en/latest/index.html] for older versions of Python), this can eliminate the need to use the older and less efficient pkg_resources package.

By «installed package» we generally mean a third-party package installed into Python’s site-packages directory via tools such as pip [https://pypi.org/project/pip/]. Specifically, it means a package with either a discoverable dist-info or egg-info directory, and metadata defined by PEP 566 [https://www.python.org/dev/peps/pep-0566] or its older specifications. By default, package metadata can live on the file system or in zip archives on sys.path. Through an extension mechanism, the metadata can live almost anywhere.

Descripción general

Supongamos que desea obtener la cadena de versión para un paquete que ha instalado con pip. Comenzamos creando un entorno virtual e instalando algo en él:

$ python3 -m venv example
$ source example/bin/activate
(example) $ pip install wheel

Se puede obtener la cadena de versión para wheel ejecutando lo siguiente:

(example) $ python
>>> from importlib.metadata import version
>>> version('wheel')
'0.32.3'

También se puede obtener el conjunto de los puntos de entrada clasificados usando el grupo, como console_scripts, distutils.commands y otros, como claves. Cada grupo contiene una secuencia de objetos EntryPoint.

Se pueden obtener los metadatos para una distribución:

>>> list(metadata('wheel'))
['Metadata-Version', 'Name', 'Version', 'Summary', 'Home-page', 'Author', 'Author-email', 'Maintainer', 'Maintainer-email', 'License', 'Project-URL', 'Project-URL', 'Project-URL', 'Keywords', 'Platform', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Requires-Python', 'Provides-Extra', 'Requires-Dist', 'Requires-Dist']

También se puede obtener el número de versión de una distribución, enumerar sus archivos constituyentes y obtener una lista de los Requerimientos de la distribución de la distribución.

API funcional

Este paquete provee la siguiente funcionalidad a través de su API pública.

Puntos de entrada

The entry_points() function returns a dictionary of all entry points, keyed by group. Entry points are represented by EntryPoint instances; each EntryPoint has a .name, .group, and .value attributes and a .load() method to resolve the value. There are also .module, .attr, and .extras attributes for getting the components of the .value attribute:

>>> eps = entry_points()
>>> list(eps)
['console_scripts', 'distutils.commands', 'distutils.setup_keywords', 'egg_info.writers', 'setuptools.installation']
>>> scripts = eps['console_scripts']
>>> wheel = [ep for ep in scripts if ep.name == 'wheel'][0]
>>> wheel
EntryPoint(name='wheel', value='wheel.cli:main', group='console_scripts')
>>> wheel.module
'wheel.cli'
>>> wheel.attr
'main'
>>> wheel.extras
[]
>>> main = wheel.load()
>>> main
<function main at 0x103528488>

The group and name are arbitrary values defined by the package author and usually a client will wish to resolve all entry points for a particular group. Read the setuptools docs [https://setuptools.readthedocs.io/en/latest/setuptools.html#dynamic-discovery-of-services-and-plugins] for more information on entry points, their definition, and usage.

Metadatos de distribución

Cada distribución incluye algunos metadatos, que puede extraer utilizando la función metadata():

>>> wheel_metadata = metadata('wheel')

Las claves de la estructura de datos retornada 1 nombran las palabras clave de los metadatos y sus valores se retornan sin analizar de los metadatos de distribución:

>>> wheel_metadata['Requires-Python']
'>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'

Versiones de distribución

La función version() es la forma más rápida para obtener el número de versión de una distribución, como una cadena de caracteres:

>>> version('wheel')
'0.32.3'

Archivos de distribución

You can also get the full set of files contained within a distribution. The files() function takes a distribution package name and returns all of the files installed by this distribution. Each file object returned is a PackagePath, a pathlib.PurePath derived object with additional dist, size, and hash properties as indicated by the metadata. For example:

>>> util = [p for p in files('wheel') if 'util.py' in str(p)][0]
>>> util
PackagePath('wheel/util.py')
>>> util.size
859
>>> util.dist
<importlib.metadata._hooks.PathDistribution object at 0x101e0cef0>
>>> util.hash
<FileHash mode: sha256 value: bYkw5oMccfazVCoYQwKkkemoVyMAFoR34mmKBx8R1NI>

Una vez que se tiene el archivo, también se puede leer su contenido:

>>> print(util.read_text())
import base64
import sys
...
def as_bytes(s):
    if isinstance(s, text_type):
        return s.encode('utf-8')
    return s

You can also use the locate method to get a the absolute path to the file:

>>> util.locate()
PosixPath('/home/gustav/example/lib/site-packages/wheel/util.py')

En el caso de que el archivo de metadatos que enumera los archivos (RECORD o SOURCES.txt) falte, files() retornará None. Para evitar esta condición, si no se sabe si la distribución de destino contiene los metadatos, se puede envolver las llamadas a files() con always_iterable [https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.always_iterable] u otra protección similar.

Requerimientos de la distribución

Para obtener el conjunto completo de los requerimientos de una distribución, usa la función requires():

>>> requires('wheel')
["pytest (>=3.0.0) ; extra == 'test'", "pytest-cov ; extra == 'test'"]

Distribuciones

Si bien la API de arriba es el uso más común y conveniente, se puede obtener toda esa información de la clase Distribution. Una instancia de Distribution es un objeto abstracto que representa los metadatos de un paquete de Python. Se puede obtener la instancia de Distribución de la siguiente forma:

>>> from importlib.metadata import distribution
>>> dist = distribution('wheel')

Por lo tanto, una forma alternativa de obtener el número de versión es mediante la instancia de Distribución:

>>> dist.version
'0.32.3'

Hay todo tipo de metadatos disponibles adicionales en la instancia de Distribution:

>>> dist.metadata['Requires-Python']
'>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'
>>> dist.metadata['License']
'MIT'

The full set of available metadata is not described here. See PEP 566 [https://www.python.org/dev/peps/pep-0566] for additional details.

Extendiendo el algoritmo de búsqueda

Debido a que los metadatos de los paquetes no están disponibles a través de las búsquedas en sys.path, o en los cargadores de paquetes directamente, los metadatos de un paquete se encuentran a través del sistema de importación finders. Para encontrar los metadatos de un paquete de distribución, importlib.metadata consulta la lista de meta path finders en sys.meta_path.

El PathFinder predeterminado para Python incluye un enlace que llama a importlib.metadata.MetadataPathFinder para encontrar distribuciones cargadas desde rutas basadas en sistemas de archivos típicos.

The abstract class importlib.abc.MetaPathFinder defines the interface expected of finders by Python’s import system. importlib.metadata extends this protocol by looking for an optional find_distributions callable on the finders from sys.meta_path and presents this extended interface as the DistributionFinder abstract base class, which defines this abstract method:

@abc.abstractmethod
def find_distributions(context=DistributionFinder.Context()):
    """Return an iterable of all Distribution instances capable of
    loading the metadata for packages for the indicated ``context``.
    """

The DistributionFinder.Context object provides .path and .name properties indicating the path to search and name to match and may supply other relevant context.

Lo que esto significa en la práctica es que, para soportar la búsqueda de metadatos en paquetes de distribución en ubicaciones distintas al sistema de archivos, se debe subclasificar Distribution e implementar sus métodos abstractos. Luego, en el método find_distributions() de un buscador personalizado no hay más que retornar instancias de esta Distribution derivada.

Notas al pie

1

Técnicamente, el objeto de metadatos de distribución devuelto es una instancia email.message.EmailMessage, pero esto es un detalle de implementación, y no forma parte de la API estable. Para acceder al contenido de los metadatos sólo debe utilizar métodos y sintaxis de tipo diccionario.

Servicios del lenguaje Python

Python proporciona una serie de módulos para ayudar a trabajar con el lenguaje Python. Estos módulos admiten tokenización, análisis, análisis sintáctico, desensamblado de código de bytes, entre otras funciones.

Estos módulos incluyen:

parser — Acceder a árboles de análisis sintáctico de Python

Crear objetos ST

Convertir objetos ST

Consultas en objetos ST

Manejo de errores y excepciones

Objetos ST

Ejemplo: Emulación de compile()

ast — Árboles de sintaxis abstracta

Gramática abstracta

Clases Nodo

Literals

Variables

Expressions

Subscripting

Comprehensions

Statements

Imports

Control flow

Function and class definitions

Async and await

Ayudantes de ast

Compiler Flags

Command-Line Usage

symtable — Acceso a la tabla de símbolos del compilador

Generando tablas de símbolos

Examinando la tabla de símbolos

symbol — Constantes utilizadas con árboles de análisis de Python

token— Constantes usadas con árboles de sintaxis de Python

keyword — Pruebas para palabras clave en Python

tokenize — Conversor a tokens para código Python

Convirtiendo la entrada en tokens

Uso como línea de comandos

Ejemplos

tabnanny — Detección de indentación ambigua

pyclbr — Soporte para navegador de módulos Python

Objetos Function

Objetos Class

py_compile` — Compila archivos fuente Python

compileall — Bibliotecas de Python de compilación de bytes

Uso de la línea de comandos

Funciones públicas

dis — Desensamblador para bytecode de Python

Análisis de bytecode

Funciones de análisis

Instrucciones bytecode de Python

Colecciones opcode

pickletools — Herramientas para desarrolladores pickle

Uso de la línea de comandos

Opciones de línea de comandos

Interfaz programática

parser — Acceder a árboles de análisis sintáctico de Python

El módulo parser proporciona una interfaz para el analizador sintáctico interno de Python y para el compilador de código de bytes. El propósito principal de esta interfaz es permitir que el código Python edite el árbol de análisis sintáctico de una expresión Python y cree código ejecutable a partir de este. Esto es mejor que intentar analizar y modificar una cadena de caracteres que conforma un fragmento de código Python arbitrario, porque el análisis se realiza de una manera idéntica al código que construye la aplicación. También es más rápido.

Advertencia

The parser module is deprecated and will be removed in future versions of Python. For the majority of use cases you can leverage the Abstract Syntax Tree (AST) generation and compilation stage, using the ast module.

Hay algunas cosas a tener en cuenta sobre este módulo, que son importantes para hacer un uso correcto de las estructuras de datos creadas. Este no es un tutorial sobre cómo editar los árboles de análisis sintáctico para código Python, no obstante, sí que se proporcionan algunos ejemplos de uso del módulo parser.

Lo más importante es que se requiere una buena comprensión de la gramática de Python procesada por el analizador sintáctico interno. Para obtener información completa sobre la sintaxis del lenguaje, consulta Referencia del Lenguaje Python. El analizador sintáctico en sí se crea a partir de una especificación gramatical definida en el archivo Grammar/Grammar en la distribución estándar de Python. Los árboles de análisis sintáctico almacenados en los objetos ST creados por este módulo son la salida real del analizador interno cuando son creados por las funciones expr() o suite(), descritas a continuación. Los objetos ST creados por sequence2st() simulan fielmente esas estructuras. Ten en cuenta que los valores de las secuencias que se consideran «correctas» variarán de una versión de Python a otra, a medida que se revise la gramática formal del lenguaje. Por el contrario, portar código fuente en forma de texto de una versión de Python a otra siempre permitirá crear árboles de análisis correctos en la versión de destino, con la única restricción de la migración a una versión anterior del intérprete que no admita construcciones del lenguaje más recientes. Los árboles de análisis sintáctico no suelen ser compatibles de una versión a otra, aunque el código fuente suele ser compatible con versiones posteriores dentro de una misma serie de versiones principales.

Cada elemento de las secuencias retornadas por st2list() o st2tuple() tiene una forma simple. Las secuencias que representan elementos no terminales en la gramática siempre tienen una longitud mayor que uno. El primer elemento es un número entero que identifica una regla de producción gramatical. Estos números enteros reciben nombres simbólicos en el archivo de cabecera Include/graminit.h de C y en el módulo symbol de Python. Cada elemento adicional de la secuencia representa un componente de la producción tal como se reconoce en la cadena de entrada: siempre son secuencias que tienen la misma forma que la original. Un aspecto importante de esta estructura que debe tenerse en cuenta es que las palabras clave utilizadas para identificar el tipo de nodo principal, como la palabra clave if en una if_stmt, se incluyen en el árbol de nodos sin ningún tratamiento especial. Por ejemplo, la palabra clave if está representada por la tupla (1, 'if'), donde 1 es el valor numérico asociado con todos los tokens NAME, incluidos los nombres de variables y funciones definidos por el usuario. En una forma alternativa, que se retorna cuando se solicita información sobre el número de línea, el mismo token podría representarse como (1, 'if', 12), donde el 12 representa el número de línea en el que se encontró el símbolo terminal.

Los elementos terminales se representan de la misma manera, pero sin ningún elemento secundario y sin la adición del texto fuente que se identificó. El anterior ejemplo de la palabra clave if es representativo de esto. Los diversos tipos de símbolos terminales se definen en el archivo de cabecera Include/token.h de C y en el módulo token de Python.

Los objetos ST no son necesarios para soportar la funcionalidad de este módulo, pero se proporcionan para tres propósitos: para permitir que una aplicación amortice el coste de procesar árboles de análisis sintáctico complejos, para proporcionar una representación en forma de árbol de análisis sintáctico que preserve espacio en memoria, en comparación con la representación una lista o tupla de Python, y para facilitar la creación de módulos adicionales en C que manipulen árboles de análisis sintáctico. Se puede crear una simple clase «contenedora» en Python para ocultar el uso de objetos ST.

El módulo parser define funciones para varios propósitos distintos. Los más importantes son crear objetos ST y convertir objetos ST en otras representaciones, como árboles de análisis sintáctico y objetos de código compilado. También existen funciones que sirven para consultar el tipo de árbol de análisis sintáctico representado por un objeto ST.

Ver también

Módulo symbol

Constantes útiles que representan los nodos internos del árbol de análisis sintáctico.

Módulo token

Constantes útiles que representan nodos hoja del árbol de análisis sintáctico y funciones para probar valores de nodos.

Crear objetos ST

Los objetos ST pueden crearse a partir del código fuente o de un árbol de análisis sintáctico. Al crear un objeto ST a partir del código fuente, se utilizan diferentes funciones para crear las formas 'eval' y 'exec'.

parser.expr(source)

La función expr() analiza el parámetro source como si fuera una entrada para compile(source, 'file.py', 'eval'). Si el análisis sintáctico tiene éxito, se crea un objeto ST para contener la representación del árbol de análisis sintáctico interno; de lo contrario, se lanza una excepción apropiada.

parser.suite(source)

La función suite() analiza el parámetro source como si fuera una entrada válida para compile(source, 'file.py', 'exec'). Si el análisis sintáctico tiene éxito, se crea un objeto ST para contener la representación del árbol de análisis sintáctico interno; de lo contrario, se lanza una excepción apropiada.

parser.sequence2st(sequence)

Esta función acepta un árbol de análisis sintáctico representado como una secuencia y construye una representación interna si es posible. Si puede validar que el árbol se ajusta a la gramática de Python y que todos los nodos son tipos de nodo válidos en la versión anfitriona de Python, se crea un objeto ST a partir de la representación interna y se retorna a quien la invocó. Si hay un problema creando la representación interna, o si el árbol no se puede validar, se lanza una excepción ParserError. No se debe dar por supuesto que un objeto ST creado de esta manera se compila correctamente; las excepciones normalmente generadas en el proceso de compilación aún pueden iniciarse cuando el objeto ST se pasa a compilest(). Esto puede indicar problemas no relacionados con la sintaxis (como una excepción MemoryError), pero también puede deberse a construcciones como el resultado de analizar del f(0), que escapa al analizador de Python pero es verificado por el compilador de código de bytes.

Las secuencias que representan tokens terminales pueden representarse como listas de dos elementos de la forma (1, 'nombre') o como listas de tres elementos de la forma (1, 'nombre', 56). Si el tercer elemento está presente, se supone que es un número de línea válido. El número de línea puede especificarse para cualquier subconjunto de los símbolos terminales en el árbol de entrada.

parser.tuple2st(sequence)

Esta es la misma función que sequence2st(). Este punto de entrada se mantiene solo por compatibilidad con versiones anteriores.

Convertir objetos ST

Los objetos ST, independientemente de la entrada utilizada para crearlos, pueden convertirse en árboles de análisis sintáctico representados como árboles de listas o tuplas, o pueden compilarse en objetos de código ejecutable. Los árboles de análisis sintáctico se pueden extraer con o sin información de numeración de línea.

parser.st2list(st, line_info=False, col_info=False)

Esta función acepta un objeto ST de quien la invoca mediante el argumento st y retorna una lista de Python que representa el árbol de análisis sintáctico equivalente. La representación de la lista resultante se puede utilizar para la inspección o la creación de un nuevo árbol de análisis sintáctico en forma de lista. Esta función no falla mientras haya memoria disponible para construir la representación de la lista. Si el árbol de análisis sintáctico sólo va a ser usado con fines de inspección, se debe usar st2tuple() en su lugar para reducir el consumo de memoria y la fragmentación. Cuando se requiere la representación en forma de lista, esta función es significativamente más rápida que recuperar una representación en forma de tupla y convertirla posteriormente en listas anidadas.

Si line_info es verdadero, la información del número de línea se incluirá para todos los tokens terminales como un tercer elemento de la lista que representa el token. Ten en cuenta que el número de línea proporcionado especifica la línea en la que el token termina. Esta información se omite si el indicador es falso o se omite.

parser.st2tuple(st, line_info=False, col_info=False)

Esta función acepta un objeto ST de quien la llama mediante el argumento st y retorna una tupla de Python que representa el árbol de análisis sintáctico equivalente. Aparte de retornar una tupla en lugar de una lista, esta función es idéntica a st2list().

Si line_info es verdadero, la información del número de línea se incluirá para todos los tokens terminales como un tercer elemento de la lista que representa el token. Esta información se omite si el indicador es falso o se omite.

parser.compilest(st, filename='<syntax-tree>')

El compilador de bytes de Python se puede invocar en un objeto ST para producir objetos de código que se pueden usar como parte de una llamada a las funciones incorporadas exec() o eval(). Esta función proporciona la interfaz para el compilador, pasando el árbol de análisis sintáctico interno de st al analizador sintáctico, utilizando el nombre del archivo fuente especificado por el parámetro filename. El valor predeterminado proporcionado para filename indica que la fuente era un objeto ST.

La compilación de un objeto ST puede resultar en excepciones relacionadas con la compilación. Un ejemplo sería la excepción SyntaxError causada por el árbol de análisis sintáctico para del f(0): esta declaración se considera legal dentro de la gramática formal de Python pero no es una construcción del lenguaje legal. La excepción SyntaxError lanzada para esta condición es realmente generada por el compilador de bytes de Python, por lo que puede ser lanzada en este punto por el módulo parser. La mayoría de las causas de errores de compilación se pueden diagnosticar programáticamente mediante la inspección del árbol de análisis sintáctico.

Consultas en objetos ST

Se proporcionan dos funciones que permiten a una aplicación determinar si un ST se creó como una expresión o una suite. Ninguna de estas funciones se puede utilizar para determinar si un ST se creó a partir del código fuente a través de expr() o suite(), o desde un árbol de análisis mediante sequence2st().

parser.isexpr(st)

Esta función retorna True cuando st representa una forma 'eval' y retorna False en caso contrario. Esto es útil, ya que los objetos de código normalmente no se pueden consultar para esta información utilizando las funciones incorporadas existentes. Ten en cuenta que los objetos de código creados por compilest() tampoco pueden consultarse así, además, son idénticos a los creados por la función incorporada compile().

parser.issuite(st)

Esta función es un espejo de isexpr(), en el sentido de que informa si un objeto ST representa una forma 'exec', comúnmente conocida como «suite». No es seguro asumir que esta función es equivalente a not isexpr(st), ya que es posible que se admitan fragmentos sintácticos adicionales en el futuro.

Manejo de errores y excepciones

El módulo parser define una única excepción, pero también puede lanzar otras excepciones incorporadas en otras partes del entorno de ejecución de Python. Consulta cada función para obtener información sobre las excepciones que puede generar.

exception parser.ParserError

Excepción lanzada cuando se produce un fallo dentro del módulo parser. Esto generalmente se produce ante fallos de validación, en lugar de la excepción incorporada SyntaxError, lanzada durante el análisis normal. El argumento de la excepción puede ser una cadena de caracteres que describa la razón del error, o también una tupla que contenga la secuencia causante del fallo en el árbol de análisis pasado a sequence2st() y una cadena explicativa. Las llamadas a sequence2st() deben poder manejar ambos tipos de excepciones, mientras que las llamadas a otras funciones en el módulo solo necesitarán tener en cuenta los valores de cadena simples.

Ten en cuenta que las funciones compilest(), expr() y suite() pueden lanzar excepciones que normalmente son generadas por el proceso de análisis y compilación. Estas incluyen las excepciones incorporadas MemoryError, OverflowError, SyntaxError y SystemError. En estos casos, estas excepciones tienen todo el significado que normalmente se asocia a ellas. Consulta las descripciones de cada función para obtener información detallada.

Objetos ST

Se admiten comparaciones de orden y de igualdad entre objetos ST. También se admite la serialización de objetos ST (utilizando el módulo pickle).

parser.STType

El tipo de los objetos retornados por expr(), suite() y sequence2st().

Los objetos ST tienen los siguientes métodos:

ST.compile(filename='<syntax-tree>')

Igual que compilest(st, filename).

ST.isexpr()

Igual que isexpr(st).

ST.issuite()

Igual que issuite(st).

ST.tolist(line_info=False, col_info=False)

Igual que st2list(st, line_info, col_info).

ST.totuple(line_info=False, col_info=False)

Igual que st2tuple(st, line_info, col_info).

Ejemplo: Emulación de compile()

Si bien muchas operaciones útiles pueden tener lugar entre el análisis y la generación del códigos de bytes, la operación más simple es no hacer nada. Para este propósito, usar el módulo parser para producir una estructura de datos intermedia es equivalente al siguiente código:

>>> code = compile('a + 5', 'file.py', 'eval')
>>> a = 5
>>> eval(code)
10

La operación equivalente usando el módulo parser es algo más larga y permite que el árbol de análisis sintáctico interno intermedio se conserve como un objeto ST:

>>> import parser
>>> st = parser.expr('a + 5')
>>> code = st.compile('file.py')
>>> a = 5
>>> eval(code)
10

Una aplicación que necesita tanto ST como objetos de código puede empaquetar este código en funciones fácilmente disponibles:

import parser

def load_suite(source_string):
    st = parser.suite(source_string)
    return st, st.compile()

def load_expression(source_string):
    st = parser.expr(source_string)
    return st, st.compile()

ast — Árboles de sintaxis abstracta

Código fuente: Lib/ast.py [https://github.com/python/cpython/tree/3.9/Lib/ast.py]

El módulo ast ayuda a las aplicaciones de Python a procesar árboles de la gramática de sintaxis abstracta de Python. La sintaxis abstracta en sí misma puede cambiar con cada versión de Python; Este módulo ayuda a descubrir mediante programación cómo se ve la gramática actual.

Se puede generar un árbol de sintaxis abstracta pasando ast.PyCF_ONLY_AST como un indicador de la función incorporada compile(), o usando el ayudante parse() provisto en este módulo. El resultado será un árbol de objetos cuyas clases todas heredan de ast.AST. Se puede compilar un árbol de sintaxis abstracta en un objeto de código Python utilizando la función incorporada compile().

Gramática abstracta

La gramática abstracta se define actualmente de la siguiente manera:

-- ASDL's 4 builtin types are:
-- identifier, int, string, constant

module Python
{
    mod = Module(stmt* body, type_ignore* type_ignores)
        | Interactive(stmt* body)
        | Expression(expr body)
        | FunctionType(expr* argtypes, expr returns)

    stmt = FunctionDef(identifier name, arguments args,
                       stmt* body, expr* decorator_list, expr? returns,
                       string? type_comment)
          | AsyncFunctionDef(identifier name, arguments args,
                             stmt* body, expr* decorator_list, expr? returns,
                             string? type_comment)

          | ClassDef(identifier name,
             expr* bases,
             keyword* keywords,
             stmt* body,
             expr* decorator_list)
          | Return(expr? value)

          | Delete(expr* targets)
          | Assign(expr* targets, expr value, string? type_comment)
          | AugAssign(expr target, operator op, expr value)
          -- 'simple' indicates that we annotate simple name without parens
          | AnnAssign(expr target, expr annotation, expr? value, int simple)

          -- use 'orelse' because else is a keyword in target languages
          | For(expr target, expr iter, stmt* body, stmt* orelse, string? type_comment)
          | AsyncFor(expr target, expr iter, stmt* body, stmt* orelse, string? type_comment)
          | While(expr test, stmt* body, stmt* orelse)
          | If(expr test, stmt* body, stmt* orelse)
          | With(withitem* items, stmt* body, string? type_comment)
          | AsyncWith(withitem* items, stmt* body, string? type_comment)

          | Raise(expr? exc, expr? cause)
          | Try(stmt* body, excepthandler* handlers, stmt* orelse, stmt* finalbody)
          | Assert(expr test, expr? msg)

          | Import(alias* names)
          | ImportFrom(identifier? module, alias* names, int? level)

          | Global(identifier* names)
          | Nonlocal(identifier* names)
          | Expr(expr value)
          | Pass | Break | Continue

          -- col_offset is the byte offset in the utf8 string the parser uses
          attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

          -- BoolOp() can use left & right?
    expr = BoolOp(boolop op, expr* values)
         | NamedExpr(expr target, expr value)
         | BinOp(expr left, operator op, expr right)
         | UnaryOp(unaryop op, expr operand)
         | Lambda(arguments args, expr body)
         | IfExp(expr test, expr body, expr orelse)
         | Dict(expr* keys, expr* values)
         | Set(expr* elts)
         | ListComp(expr elt, comprehension* generators)
         | SetComp(expr elt, comprehension* generators)
         | DictComp(expr key, expr value, comprehension* generators)
         | GeneratorExp(expr elt, comprehension* generators)
         -- the grammar constrains where yield expressions can occur
         | Await(expr value)
         | Yield(expr? value)
         | YieldFrom(expr value)
         -- need sequences for compare to distinguish between
         -- x < 4 < 3 and (x < 4) < 3
         | Compare(expr left, cmpop* ops, expr* comparators)
         | Call(expr func, expr* args, keyword* keywords)
         | FormattedValue(expr value, int? conversion, expr? format_spec)
         | JoinedStr(expr* values)
         | Constant(constant value, string? kind)

         -- the following expression can appear in assignment context
         | Attribute(expr value, identifier attr, expr_context ctx)
         | Subscript(expr value, expr slice, expr_context ctx)
         | Starred(expr value, expr_context ctx)
         | Name(identifier id, expr_context ctx)
         | List(expr* elts, expr_context ctx)
         | Tuple(expr* elts, expr_context ctx)

         -- can appear only in Subscript
         | Slice(expr? lower, expr? upper, expr? step)

          -- col_offset is the byte offset in the utf8 string the parser uses
          attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

    expr_context = Load | Store | Del

    boolop = And | Or

    operator = Add | Sub | Mult | MatMult | Div | Mod | Pow | LShift
                 | RShift | BitOr | BitXor | BitAnd | FloorDiv

    unaryop = Invert | Not | UAdd | USub

    cmpop = Eq | NotEq | Lt | LtE | Gt | GtE | Is | IsNot | In | NotIn

    comprehension = (expr target, expr iter, expr* ifs, int is_async)

    excepthandler = ExceptHandler(expr? type, identifier? name, stmt* body)
                    attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

    arguments = (arg* posonlyargs, arg* args, arg? vararg, arg* kwonlyargs,
                 expr* kw_defaults, arg? kwarg, expr* defaults)

    arg = (identifier arg, expr? annotation, string? type_comment)
           attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

    -- keyword arguments supplied to call (NULL identifier for **kwargs)
    keyword = (identifier? arg, expr value)
               attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

    -- import name with optional 'as' alias.
    alias = (identifier name, identifier? asname)

    withitem = (expr context_expr, expr? optional_vars)

    type_ignore = TypeIgnore(int lineno, string tag)
}

Clases Nodo

class ast.AST

Esta es la base de todas las clases de nodo AST. Las clases de nodo reales se derivan del archivo Parser/Python.asdl, que se reproduce abajo. Se definen en el módulo _ast C y se reexportan en ast.

Hay una clase definida para cada símbolo del lado izquierdo en la gramática abstracta (por ejemplo, ast.stmt o ast.expr). Además, hay una clase definida para cada constructor en el lado derecho; estas clases heredan de las clases para los árboles del lado izquierdo. Por ejemplo, ast.BinOp hereda de ast.expr. Para las reglas de producción con alternativas (también conocidas como «sumas»), la clase del lado izquierdo es abstracta: solo se crean instancias de nodos de constructor específicos.

_fields

Cada clase concreta tiene un atributo _fields que proporciona los nombres de todos los nodos secundarios.

Cada instancia de una clase concreta tiene un atributo para cada nodo secundario, del tipo definido en la gramática. Por ejemplo, las instancias ast.BinOp tienen un atributo left de tipo ast.expr.

Si estos atributos están marcados como opcionales en la gramática (usando un signo de interrogación), el valor podría ser None. Si los atributos pueden tener cero o más valores (marcados con un asterisco), los valores se representan como listas de Python. Todos los atributos posibles deben estar presentes y tener valores válidos al compilar un AST con compile().

lineno

col_offset

end_lineno

end_col_offset

Instances of ast.expr and ast.stmt subclasses have lineno, col_offset, end_lineno, and end_col_offset attributes. The lineno and end_lineno are the first and last line numbers of the source text span (1-indexed so the first line is line 1), and the col_offset and end_col_offset are the corresponding UTF-8 byte offsets of the first and last tokens that generated the node. The UTF-8 offset is recorded because the parser uses UTF-8 internally.

Tenga en cuenta que el compilador no requiere las posiciones finales y, por lo tanto, son opcionales. El desplazamiento final es después del último símbolo, por ejemplo, uno puede obtener el segmento fuente de un nodo de expresión de una línea usando source_line[node.col_offset: node.end_col_offset].

El constructor de una clase ast.T analiza sus argumentos de la siguiente manera:

Si hay argumentos posicionales, debe haber tantos como elementos en T._fields; serán asignados como atributos de estos nombres.

Si hay argumentos de palabras clave, establecerán los atributos de los mismos nombres a los valores dados.

Por ejemplo, para crear y completar un nodo ast.UnaryOp, puede usar

node = ast.UnaryOp()
node.op = ast.USub()
node.operand = ast.Constant()
node.operand.value = 5
node.operand.lineno = 0
node.operand.col_offset = 0
node.lineno = 0
node.col_offset = 0

o la más compacta

node = ast.UnaryOp(ast.USub(), ast.Constant(5, lineno=0, col_offset=0),
                   lineno=0, col_offset=0)

Distinto en la versión 3.8: La clase ast.Constant ahora se usa para todas las constantes.

Distinto en la versión 3.9: Simple indices are represented by their value, extended slices are represented as tuples.

Obsoleto desde la versión 3.8: Old classes ast.Num, ast.Str, ast.Bytes, ast.NameConstant and ast.Ellipsis are still available, but they will be removed in future Python releases. In the meantime, instantiating them will return an instance of a different class.

Obsoleto desde la versión 3.9: Old classes ast.Index and ast.ExtSlice are still available, but they will be removed in future Python releases. In the meantime, instantiating them will return an instance of a different class.

Nota

The descriptions of the specific node classes displayed here were initially adapted from the fantastic Green Tree Snakes [https://greentreesnakes.readthedocs.io/en/latest/] project and all its contributors.

Literals

class ast.Constant(value)

A constant value. The value attribute of the Constant literal contains the Python object it represents. The values represented can be simple types such as a number, string or None, but also immutable container types (tuples and frozensets) if all of their elements are constant.

>>> print(ast.dump(ast.parse('123', mode='eval'), indent=4))
Expression(
    body=Constant(value=123))

class ast.FormattedValue(value, conversion, format_spec)

Node representing a single formatting field in an f-string. If the string contains a single formatting field and nothing else the node can be isolated otherwise it appears in JoinedStr.

value is any expression node (such as a literal, a variable, or a function call).

conversion is an integer:

-1: no formatting

115: !s string formatting

114: !r repr formatting

97: !a ascii formatting

format_spec is a JoinedStr node representing the formatting of the value, or None if no format was specified. Both conversion and format_spec can be set at the same time.

class ast.JoinedStr(values)

An f-string, comprising a series of FormattedValue and Constant nodes.

>>> print(ast.dump(ast.parse('f"sin({a}) is {sin(a):.3}"', mode='eval'), indent=4))
Expression(
    body=JoinedStr(
        values=[
            Constant(value='sin('),
            FormattedValue(
                value=Name(id='a', ctx=Load()),
                conversion=-1),
            Constant(value=') is '),
            FormattedValue(
                value=Call(
                    func=Name(id='sin', ctx=Load()),
                    args=[
                        Name(id='a', ctx=Load())],
                    keywords=[]),
                conversion=-1,
                format_spec=JoinedStr(
                    values=[
                        Constant(value='.3')]))]))

class ast.List(elts, ctx)

class ast.Tuple(elts, ctx)

A list or tuple. elts holds a list of nodes representing the elements. ctx is Store if the container is an assignment target (i.e. (x,y)=something), and Load otherwise.

>>> print(ast.dump(ast.parse('[1, 2, 3]', mode='eval'), indent=4))
Expression(
    body=List(
        elts=[
            Constant(value=1),
            Constant(value=2),
            Constant(value=3)],
        ctx=Load()))
>>> print(ast.dump(ast.parse('(1, 2, 3)', mode='eval'), indent=4))
Expression(
    body=Tuple(
        elts=[
            Constant(value=1),
            Constant(value=2),
            Constant(value=3)],
        ctx=Load()))

class ast.Set(elts)

A set. elts holds a list of nodes representing the set’s elements.

>>> print(ast.dump(ast.parse('{1, 2, 3}', mode='eval'), indent=4))
Expression(
    body=Set(
        elts=[
            Constant(value=1),
            Constant(value=2),
            Constant(value=3)]))

class ast.Dict(keys, values)

A dictionary. keys and values hold lists of nodes representing the keys and the values respectively, in matching order (what would be returned when calling dictionary.keys() and dictionary.values()).

When doing dictionary unpacking using dictionary literals the expression to be expanded goes in the values list, with a None at the corresponding position in keys.

>>> print(ast.dump(ast.parse('{"a":1, **d}', mode='eval'), indent=4))
Expression(
    body=Dict(
        keys=[
            Constant(value='a'),
            None],
        values=[
            Constant(value=1),
            Name(id='d', ctx=Load())]))

Variables

class ast.Name(id, ctx)

A variable name. id holds the name as a string, and ctx is one of the following types.

class ast.Load

class ast.Store

class ast.Del

Variable references can be used to load the value of a variable, to assign a new value to it, or to delete it. Variable references are given a context to distinguish these cases.

>>> print(ast.dump(ast.parse('a'), indent=4))
Module(
    body=[
        Expr(
            value=Name(id='a', ctx=Load()))],
    type_ignores=[])

>>> print(ast.dump(ast.parse('a = 1'), indent=4))
Module(
    body=[
        Assign(
            targets=[
                Name(id='a', ctx=Store())],
            value=Constant(value=1))],
    type_ignores=[])

>>> print(ast.dump(ast.parse('del a'), indent=4))
Module(
    body=[
        Delete(
            targets=[
                Name(id='a', ctx=Del())])],
    type_ignores=[])

class ast.Starred(value, ctx)

A *var variable reference. value holds the variable, typically a Name node. This type must be used when building a Call node with *args.

>>> print(ast.dump(ast.parse('a, *b = it'), indent=4))
Module(
    body=[
        Assign(
            targets=[
                Tuple(
                    elts=[
                        Name(id='a', ctx=Store()),
                        Starred(
                            value=Name(id='b', ctx=Store()),
                            ctx=Store())],
                    ctx=Store())],
            value=Name(id='it', ctx=Load()))],
    type_ignores=[])

Expressions

class ast.Expr(value)

When an expression, such as a function call, appears as a statement by itself with its return value not used or stored, it is wrapped in this container. value holds one of the other nodes in this section, a Constant, a Name, a Lambda, a Yield or YieldFrom node.

>>> print(ast.dump(ast.parse('-a'), indent=4))
Module(
    body=[
        Expr(
            value=UnaryOp(
                op=USub(),
                operand=Name(id='a', ctx=Load())))],
    type_ignores=[])

class ast.UnaryOp(op, operand)

A unary operation. op is the operator, and operand any expression node.

class ast.UAdd

class ast.USub

class ast.Not

class ast.Invert

Unary operator tokens. Not is the not keyword, Invert is the ~ operator.

>>> print(ast.dump(ast.parse('not x', mode='eval'), indent=4))
Expression(
    body=UnaryOp(
        op=Not(),
        operand=Name(id='x', ctx=Load())))

class ast.BinOp(left, op, right)

A binary operation (like addition or division). op is the operator, and left and right are any expression nodes.

>>> print(ast.dump(ast.parse('x + y', mode='eval'), indent=4))
Expression(
    body=BinOp(
        left=Name(id='x', ctx=Load()),
        op=Add(),
        right=Name(id='y', ctx=Load())))

class ast.Add

class ast.Sub

class ast.Mult

class ast.Div

class ast.FloorDiv

class ast.Mod

class ast.Pow

class ast.LShift

class ast.RShift

class ast.BitOr

class ast.BitXor

class ast.BitAnd

class ast.MatMult

Binary operator tokens.

class ast.BoolOp(op, values)

A boolean operation, “or” or “and”. op is Or or And. values are the values involved. Consecutive operations with the same operator, such as a or b or c, are collapsed into one node with several values.

This doesn’t include not, which is a UnaryOp.

>>> print(ast.dump(ast.parse('x or y', mode='eval'), indent=4))
Expression(
    body=BoolOp(
        op=Or(),
        values=[
            Name(id='x', ctx=Load()),
            Name(id='y', ctx=Load())]))

class ast.And

class ast.Or

Boolean operator tokens.

class ast.Compare(left, ops, comparators)

A comparison of two or more values. left is the first value in the comparison, ops the list of operators, and comparators the list of values after the first element in the comparison.

>>> print(ast.dump(ast.parse('1 <= a < 10', mode='eval'), indent=4))
Expression(
    body=Compare(
        left=Constant(value=1),
        ops=[
            LtE(),
            Lt()],
        comparators=[
            Name(id='a', ctx=Load()),
            Constant(value=10)]))

class ast.Eq

class ast.NotEq

class ast.Lt

class ast.LtE

class ast.Gt

class ast.GtE

class ast.Is

class ast.IsNot

class ast.In

class ast.NotIn

Comparison operator tokens.

class ast.Call(func, args, keywords, starargs, kwargs)

A function call. func is the function, which will often be a Name or Attribute object. Of the arguments:

args holds a list of the arguments passed by position.

keywords holds a list of keyword objects representing arguments passed by keyword.

When creating a Call node, args and keywords are required, but they can be empty lists. starargs and kwargs are optional.

>>> print(ast.dump(ast.parse('func(a, b=c, *d, **e)', mode='eval'), indent=4))
Expression(
    body=Call(
        func=Name(id='func', ctx=Load()),
        args=[
            Name(id='a', ctx=Load()),
            Starred(
                value=Name(id='d', ctx=Load()),
                ctx=Load())],
        keywords=[
            keyword(
                arg='b',
                value=Name(id='c', ctx=Load())),
            keyword(
                value=Name(id='e', ctx=Load()))]))

class ast.keyword(arg, value)

A keyword argument to a function call or class definition. arg is a raw string of the parameter name, value is a node to pass in.

class ast.IfExp(test, body, orelse)

An expression such as a if b else c. Each field holds a single node, so in the following example, all three are Name nodes.

>>> print(ast.dump(ast.parse('a if b else c', mode='eval'), indent=4))
Expression(
    body=IfExp(
        test=Name(id='b', ctx=Load()),
        body=Name(id='a', ctx=Load()),
        orelse=Name(id='c', ctx=Load())))

class ast.Attribute(value, attr, ctx)

Attribute access, e.g. d.keys. value is a node, typically a Name. attr is a bare string giving the name of the attribute, and ctx is Load, Store or Del according to how the attribute is acted on.

>>> print(ast.dump(ast.parse('snake.colour', mode='eval'), indent=4))
Expression(
    body=Attribute(
        value=Name(id='snake', ctx=Load()),
        attr='colour',
        ctx=Load()))

class ast.NamedExpr(target, value)

A named expression. This AST node is produced by the assignment expressions operator (also known as the walrus operator). As opposed to the Assign node in which the first argument can be multiple nodes, in this case both target and value must be single nodes.

>>> print(ast.dump(ast.parse('(x := 4)', mode='eval'), indent=4))
Expression(
    body=NamedExpr(
        target=Name(id='x', ctx=Store()),
        value=Constant(value=4)))

Subscripting

class ast.Subscript(value, slice, ctx)

A subscript, such as l[1]. value is the subscripted object (usually sequence or mapping). slice is an index, slice or key. It can be a Tuple and contain a Slice. ctx is Load, Store or Del according to the action performed with the subscript.

>>> print(ast.dump(ast.parse('l[1:2, 3]', mode='eval'), indent=4))
Expression(
    body=Subscript(
        value=Name(id='l', ctx=Load()),
        slice=Tuple(
            elts=[
                Slice(
                    lower=Constant(value=1),
                    upper=Constant(value=2)),
                Constant(value=3)],
            ctx=Load()),
        ctx=Load()))

class ast.Slice(lower, upper, step)

Regular slicing (on the form lower:upper or lower:upper:step). Can occur only inside the slice field of Subscript, either directly or as an element of Tuple.

>>> print(ast.dump(ast.parse('l[1:2]', mode='eval'), indent=4))
Expression(
    body=Subscript(
        value=Name(id='l', ctx=Load()),
        slice=Slice(
            lower=Constant(value=1),
            upper=Constant(value=2)),
        ctx=Load()))

Comprehensions

class ast.ListComp(elt, generators)

class ast.SetComp(elt, generators)

class ast.GeneratorExp(elt, generators)

class ast.DictComp(key, value, generators)

List and set comprehensions, generator expressions, and dictionary comprehensions. elt (or key and value) is a single node representing the part that will be evaluated for each item.

generators is a list of comprehension nodes.

>>> print(ast.dump(ast.parse('[x for x in numbers]', mode='eval'), indent=4))
Expression(
    body=ListComp(
        elt=Name(id='x', ctx=Load()),
        generators=[
            comprehension(
                target=Name(id='x', ctx=Store()),
                iter=Name(id='numbers', ctx=Load()),
                ifs=[],
                is_async=0)]))
>>> print(ast.dump(ast.parse('{x: x**2 for x in numbers}', mode='eval'), indent=4))
Expression(
    body=DictComp(
        key=Name(id='x', ctx=Load()),
        value=BinOp(
            left=Name(id='x', ctx=Load()),
            op=Pow(),
            right=Constant(value=2)),
        generators=[
            comprehension(
                target=Name(id='x', ctx=Store()),
                iter=Name(id='numbers', ctx=Load()),
                ifs=[],
                is_async=0)]))
>>> print(ast.dump(ast.parse('{x for x in numbers}', mode='eval'), indent=4))
Expression(
    body=SetComp(
        elt=Name(id='x', ctx=Load()),
        generators=[
            comprehension(
                target=Name(id='x', ctx=Store()),
                iter=Name(id='numbers', ctx=Load()),
                ifs=[],
                is_async=0)]))

class ast.comprehension(target, iter, ifs, is_async)

One for clause in a comprehension. target is the reference to use for each element - typically a Name or Tuple node. iter is the object to iterate over. ifs is a list of test expressions: each for clause can have multiple ifs.

is_async indicates a comprehension is asynchronous (using an async for instead of for). The value is an integer (0 or 1).

>>> print(ast.dump(ast.parse('[ord(c) for line in file for c in line]', mode='eval'),
...                indent=4)) # Multiple comprehensions in one.
Expression(
    body=ListComp(
        elt=Call(
            func=Name(id='ord', ctx=Load()),
            args=[
                Name(id='c', ctx=Load())],
            keywords=[]),
        generators=[
            comprehension(
                target=Name(id='line', ctx=Store()),
                iter=Name(id='file', ctx=Load()),
                ifs=[],
                is_async=0),
            comprehension(
                target=Name(id='c', ctx=Store()),
                iter=Name(id='line', ctx=Load()),
                ifs=[],
                is_async=0)]))

>>> print(ast.dump(ast.parse('(n**2 for n in it if n>5 if n<10)', mode='eval'),
...                indent=4)) # generator comprehension
Expression(
    body=GeneratorExp(
        elt=BinOp(
            left=Name(id='n', ctx=Load()),
            op=Pow(),
            right=Constant(value=2)),
        generators=[
            comprehension(
                target=Name(id='n', ctx=Store()),
                iter=Name(id='it', ctx=Load()),
                ifs=[
                    Compare(
                        left=Name(id='n', ctx=Load()),
                        ops=[
                            Gt()],
                        comparators=[
                            Constant(value=5)]),
                    Compare(
                        left=Name(id='n', ctx=Load()),
                        ops=[
                            Lt()],
                        comparators=[
                            Constant(value=10)])],
                is_async=0)]))

>>> print(ast.dump(ast.parse('[i async for i in soc]', mode='eval'),
...                indent=4)) # Async comprehension
Expression(
    body=ListComp(
        elt=Name(id='i', ctx=Load()),
        generators=[
            comprehension(
                target=Name(id='i', ctx=Store()),
                iter=Name(id='soc', ctx=Load()),
                ifs=[],
                is_async=1)]))

Statements

class ast.Assign(targets, value, type_comment)

An assignment. targets is a list of nodes, and value is a single node.

Multiple nodes in targets represents assigning the same value to each. Unpacking is represented by putting a Tuple or List within targets.

type_comment

type_comment is an optional string with the type annotation as a comment.

>>> print(ast.dump(ast.parse('a = b = 1'), indent=4)) # Multiple assignment
Module(
    body=[
        Assign(
            targets=[
                Name(id='a', ctx=Store()),
                Name(id='b', ctx=Store())],
            value=Constant(value=1))],
    type_ignores=[])

>>> print(ast.dump(ast.parse('a,b = c'), indent=4)) # Unpacking
Module(
    body=[
        Assign(
            targets=[
                Tuple(
                    elts=[
                        Name(id='a', ctx=Store()),
                        Name(id='b', ctx=Store())],
                    ctx=Store())],
            value=Name(id='c', ctx=Load()))],
    type_ignores=[])

class ast.AnnAssign(target, annotation, value, simple)

An assignment with a type annotation. target is a single node and can be a Name, a Attribute or a Subscript. annotation is the annotation, such as a Constant or Name node. value is a single optional node. simple is a boolean integer set to True for a Name node in target that do not appear in between parenthesis and are hence pure names and not expressions.

>>> print(ast.dump(ast.parse('c: int'), indent=4))
Module(
    body=[
        AnnAssign(
            target=Name(id='c', ctx=Store()),
            annotation=Name(id='int', ctx=Load()),
            simple=1)],
    type_ignores=[])

>>> print(ast.dump(ast.parse('(a): int = 1'), indent=4)) # Annotation with parenthesis
Module(
    body=[
        AnnAssign(
            target=Name(id='a', ctx=Store()),
            annotation=Name(id='int', ctx=Load()),
            value=Constant(value=1),
            simple=0)],
    type_ignores=[])

>>> print(ast.dump(ast.parse('a.b: int'), indent=4)) # Attribute annotation
Module(
    body=[
        AnnAssign(
            target=Attribute(
                value=Name(id='a', ctx=Load()),
                attr='b',
                ctx=Store()),
            annotation=Name(id='int', ctx=Load()),
            simple=0)],
    type_ignores=[])

>>> print(ast.dump(ast.parse('a[1]: int'), indent=4)) # Subscript annotation
Module(
    body=[
        AnnAssign(
            target=Subscript(
                value=Name(id='a', ctx=Load()),
                slice=Constant(value=1),
                ctx=Store()),
            annotation=Name(id='int', ctx=Load()),
            simple=0)],
    type_ignores=[])

class ast.AugAssign(target, op, value)

Augmented assignment, such as a += 1. In the following example, target is a Name node for x (with the Store context), op is Add, and value is a Constant with value for 1.

The target attribute connot be of class Tuple or List, unlike the targets of Assign.

>>> print(ast.dump(ast.parse('x += 2'), indent=4))
Module(
    body=[
        AugAssign(
            target=Name(id='x', ctx=Store()),
            op=Add(),
            value=Constant(value=2))],
    type_ignores=[])

class ast.Raise(exc, cause)

A raise statement. exc is the exception object to be raised, normally a Call or Name, or None for a standalone raise. cause is the optional part for y in raise x from y.

>>> print(ast.dump(ast.parse('raise x from y'), indent=4))
Module(
    body=[
        Raise(
            exc=Name(id='x', ctx=Load()),
            cause=Name(id='y', ctx=Load()))],
    type_ignores=[])

class ast.Assert(test, msg)

An assertion. test holds the condition, such as a Compare node. msg holds the failure message.

>>> print(ast.dump(ast.parse('assert x,y'), indent=4))
Module(
    body=[
        Assert(
            test=Name(id='x', ctx=Load()),
            msg=Name(id='y', ctx=Load()))],
    type_ignores=[])

class ast.Delete(targets)

Represents a del statement. targets is a list of nodes, such as Name, Attribute or Subscript nodes.

>>> print(ast.dump(ast.parse('del x,y,z'), indent=4))
Module(
    body=[
        Delete(
            targets=[
                Name(id='x', ctx=Del()),
                Name(id='y', ctx=Del()),
                Name(id='z', ctx=Del())])],
    type_ignores=[])

class ast.Pass

A pass statement.

>>> print(ast.dump(ast.parse('pass'), indent=4))
Module(
    body=[
        Pass()],
    type_ignores=[])

Other statements which are only applicable inside functions or loops are described in other sections.

Imports

class ast.Import(names)

An import statement. names is a list of alias nodes.

>>> print(ast.dump(ast.parse('import x,y,z'), indent=4))
Module(
    body=[
        Import(
            names=[
                alias(name='x'),
                alias(name='y'),
                alias(name='z')])],
    type_ignores=[])

class ast.ImportFrom(module, names, level)

Represents from x import y. module is a raw string of the “from” name, without any leading dots, or None for statements such as from . import foo. level is an integer holding the level of the relative import (0 means absolute import).

>>> print(ast.dump(ast.parse('from y import x,y,z'), indent=4))
Module(
    body=[
        ImportFrom(
            module='y',
            names=[
                alias(name='x'),
                alias(name='y'),
                alias(name='z')],
            level=0)],
    type_ignores=[])

class ast.alias(name, asname)

Both parameters are raw strings of the names. asname can be None if the regular name is to be used.

>>> print(ast.dump(ast.parse('from ..foo.bar import a as b, c'), indent=4))
Module(
    body=[
        ImportFrom(
            module='foo.bar',
            names=[
                alias(name='a', asname='b'),
                alias(name='c')],
            level=2)],
    type_ignores=[])

Control flow

Nota

Optional clauses such as else are stored as an empty list if they’re not present.

class ast.If(test, body, orelse)

An if statement. test holds a single node, such as a Compare node. body and orelse each hold a list of nodes.

elif clauses don’t have a special representation in the AST, but rather appear as extra If nodes within the orelse section of the previous one.

>>> print(ast.dump(ast.parse("""
... if x:
...    ...
... elif y:
...    ...
... else:
...    ...
... """), indent=4))
Module(
    body=[
        If(
            test=Name(id='x', ctx=Load()),
            body=[
                Expr(
                    value=Constant(value=Ellipsis))],
            orelse=[
                If(
                    test=Name(id='y', ctx=Load()),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))],
                    orelse=[
                        Expr(
                            value=Constant(value=Ellipsis))])])],
    type_ignores=[])

class ast.For(target, iter, body, orelse, type_comment)

A for loop. target holds the variable(s) the loop assigns to, as a single Name, Tuple or List node. iter holds the item to be looped over, again as a single node. body and orelse contain lists of nodes to execute. Those in orelse are executed if the loop finishes normally, rather than via a break statement.

type_comment

type_comment is an optional string with the type annotation as a comment.

>>> print(ast.dump(ast.parse("""
... for x in y:
...     ...
... else:
...     ...
... """), indent=4))
Module(
    body=[
        For(
            target=Name(id='x', ctx=Store()),
            iter=Name(id='y', ctx=Load()),
            body=[
                Expr(
                    value=Constant(value=Ellipsis))],
            orelse=[
                Expr(
                    value=Constant(value=Ellipsis))])],
    type_ignores=[])

class ast.While(test, body, orelse)

A while loop. test holds the condition, such as a Compare node.

>> print(ast.dump(ast.parse("""
... while x:
...    ...
... else:
...    ...
... """), indent=4))
Module(
    body=[
        While(
            test=Name(id='x', ctx=Load()),
            body=[
                Expr(
                    value=Constant(value=Ellipsis))],
            orelse=[
                Expr(
                    value=Constant(value=Ellipsis))])],
    type_ignores=[])

class ast.Break

class ast.Continue

The break and continue statements.

>>> print(ast.dump(ast.parse("""\
... for a in b:
...     if a > 5:
...         break
...     else:
...         continue
...
... """), indent=4))
Module(
    body=[
        For(
            target=Name(id='a', ctx=Store()),
            iter=Name(id='b', ctx=Load()),
            body=[
                If(
                    test=Compare(
                        left=Name(id='a', ctx=Load()),
                        ops=[
                            Gt()],
                        comparators=[
                            Constant(value=5)]),
                    body=[
                        Break()],
                    orelse=[
                        Continue()])],
            orelse=[])],
    type_ignores=[])

class ast.Try(body, handlers, orelse, finalbody)

try blocks. All attributes are list of nodes to execute, except for handlers, which is a list of ExceptHandler nodes.

>>> print(ast.dump(ast.parse("""
... try:
...    ...
... except Exception:
...    ...
... except OtherException as e:
...    ...
... else:
...    ...
... finally:
...    ...
... """), indent=4))
Module(
    body=[
        Try(
            body=[
                Expr(
                    value=Constant(value=Ellipsis))],
            handlers=[
                ExceptHandler(
                    type=Name(id='Exception', ctx=Load()),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))]),
                ExceptHandler(
                    type=Name(id='OtherException', ctx=Load()),
                    name='e',
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])],
            orelse=[
                Expr(
                    value=Constant(value=Ellipsis))],
            finalbody=[
                Expr(
                    value=Constant(value=Ellipsis))])],
    type_ignores=[])

class ast.ExceptHandler(type, name, body)

A single except clause. type is the exception type it will match, typically a Name node (or None for a catch-all except: clause). name is a raw string for the name to hold the exception, or None if the clause doesn’t have as foo. body is a list of nodes.

>>> print(ast.dump(ast.parse("""\
... try:
...     a + 1
... except TypeError:
...     pass
... """), indent=4))
Module(
    body=[
        Try(
            body=[
                Expr(
                    value=BinOp(
                        left=Name(id='a', ctx=Load()),
                        op=Add(),
                        right=Constant(value=1)))],
            handlers=[
                ExceptHandler(
                    type=Name(id='TypeError', ctx=Load()),
                    body=[
                        Pass()])],
            orelse=[],
            finalbody=[])],
    type_ignores=[])

class ast.With(items, body, type_comment)

A with block. items is a list of withitem nodes representing the context managers, and body is the indented block inside the context.

type_comment

type_comment is an optional string with the type annotation as a comment.

class ast.withitem(context_expr, optional_vars)

A single context manager in a with block. context_expr is the context manager, often a Call node. optional_vars is a Name, Tuple or List for the as foo part, or None if that isn’t used.

>>> print(ast.dump(ast.parse("""\
... with a as b, c as d:
...    something(b, d)
... """), indent=4))
Module(
    body=[
        With(
            items=[
                withitem(
                    context_expr=Name(id='a', ctx=Load()),
                    optional_vars=Name(id='b', ctx=Store())),
                withitem(
                    context_expr=Name(id='c', ctx=Load()),
                    optional_vars=Name(id='d', ctx=Store()))],
            body=[
                Expr(
                    value=Call(
                        func=Name(id='something', ctx=Load()),
                        args=[
                            Name(id='b', ctx=Load()),
                            Name(id='d', ctx=Load())],
                        keywords=[]))])],
    type_ignores=[])

Function and class definitions

class ast.FunctionDef(name, args, body, decorator_list, returns, type_comment)

A function definition.

name is a raw string of the function name.

args is an arguments node.

body is the list of nodes inside the function.

decorator_list is the list of decorators to be applied, stored outermost first (i.e. the first in the list will be applied last).

returns is the return annotation.

type_comment

type_comment is an optional string with the type annotation as a comment.

class ast.Lambda(args, body)

lambda is a minimal function definition that can be used inside an expression. Unlike FunctionDef, body holds a single node.

>>> print(ast.dump(ast.parse('lambda x,y: ...'), indent=4))
Module(
    body=[
        Expr(
            value=Lambda(
                args=arguments(
                    posonlyargs=[],
                    args=[
                        arg(arg='x'),
                        arg(arg='y')],
                    kwonlyargs=[],
                    kw_defaults=[],
                    defaults=[]),
                body=Constant(value=Ellipsis)))],
    type_ignores=[])

class ast.arguments(posonlyargs, args, vararg, kwonlyargs, kw_defaults, kwarg, defaults)

The arguments for a function.

posonlyargs, args and kwonlyargs are lists of arg nodes.

vararg and kwarg are single arg nodes, referring to the *args, **kwargs parameters.

kw_defaults is a list of default values for keyword-only arguments. If one is None, the corresponding argument is required.

defaults is a list of default values for arguments that can be passed positionally. If there are fewer defaults, they correspond to the last n arguments.

class ast.arg(arg, annotation, type_comment)

A single argument in a list. arg is a raw string of the argument name, annotation is its annotation, such as a Str or Name node.

type_comment

type_comment is an optional string with the type annotation as a comment

>>> print(ast.dump(ast.parse("""\
... @decorator1
... @decorator2
... def f(a: 'annotation', b=1, c=2, *d, e, f=3, **g) -> 'return annotation':
...     pass
... """), indent=4))
Module(
    body=[
        FunctionDef(
            name='f',
            args=arguments(
                posonlyargs=[],
                args=[
                    arg(
                        arg='a',
                        annotation=Constant(value='annotation')),
                    arg(arg='b'),
                    arg(arg='c')],
                vararg=arg(arg='d'),
                kwonlyargs=[
                    arg(arg='e'),
                    arg(arg='f')],
                kw_defaults=[
                    None,
                    Constant(value=3)],
                kwarg=arg(arg='g'),
                defaults=[
                    Constant(value=1),
                    Constant(value=2)]),
            body=[
                Pass()],
            decorator_list=[
                Name(id='decorator1', ctx=Load()),
                Name(id='decorator2', ctx=Load())],
            returns=Constant(value='return annotation'))],
    type_ignores=[])

class ast.Return(value)

A return statement.

>>> print(ast.dump(ast.parse('return 4'), indent=4))
Module(
    body=[
        Return(
            value=Constant(value=4))],
    type_ignores=[])

class ast.Yield(value)

class ast.YieldFrom(value)

A yield or yield from expression. Because these are expressions, they must be wrapped in a Expr node if the value sent back is not used.

>>> print(ast.dump(ast.parse('yield x'), indent=4))
Module(
    body=[
        Expr(
            value=Yield(
                value=Name(id='x', ctx=Load())))],
    type_ignores=[])

>>> print(ast.dump(ast.parse('yield from x'), indent=4))
Module(
    body=[
        Expr(
            value=YieldFrom(
                value=Name(id='x', ctx=Load())))],
    type_ignores=[])

class ast.Global(names)

class ast.Nonlocal(names)

global and nonlocal statements. names is a list of raw strings.

>>> print(ast.dump(ast.parse('global x,y,z'), indent=4))
Module(
    body=[
        Global(
            names=[
                'x',
                'y',
                'z'])],
    type_ignores=[])

>>> print(ast.dump(ast.parse('nonlocal x,y,z'), indent=4))
Module(
    body=[
        Nonlocal(
            names=[
                'x',
                'y',
                'z'])],
    type_ignores=[])

class ast.ClassDef(name, bases, keywords, starargs, kwargs, body, decorator_list)

A class definition.

name is a raw string for the class name

bases is a list of nodes for explicitly specified base classes.

keywords is a list of keyword nodes, principally for “metaclass”. Other keywords will be passed to the metaclass, as per PEP-3115 [https://www.python.org/dev/peps/pep-3115/].

starargs and kwargs are each a single node, as in a function call. starargs will be expanded to join the list of base classes, and kwargs will be passed to the metaclass.

body is a list of nodes representing the code within the class definition.

decorator_list is a list of nodes, as in FunctionDef.

>>> print(ast.dump(ast.parse("""\
... @decorator1
... @decorator2
... class Foo(base1, base2, metaclass=meta):
...     pass
... """), indent=4))
Module(
    body=[
        ClassDef(
            name='Foo',
            bases=[
                Name(id='base1', ctx=Load()),
                Name(id='base2', ctx=Load())],
            keywords=[
                keyword(
                    arg='metaclass',
                    value=Name(id='meta', ctx=Load()))],
            body=[
                Pass()],
            decorator_list=[
                Name(id='decorator1', ctx=Load()),
                Name(id='decorator2', ctx=Load())])],
    type_ignores=[])

Async and await

class ast.AsyncFunctionDef(name, args, body, decorator_list, returns, type_comment)

An async def function definition. Has the same fields as FunctionDef.

class ast.Await(value)

An await expression. value is what it waits for. Only valid in the body of an AsyncFunctionDef.

>>> print(ast.dump(ast.parse("""\
... async def f():
...     await other_func()
... """), indent=4))
Module(
    body=[
        AsyncFunctionDef(
            name='f',
            args=arguments(
                posonlyargs=[],
                args=[],
                kwonlyargs=[],
                kw_defaults=[],
                defaults=[]),
            body=[
                Expr(
                    value=Await(
                        value=Call(
                            func=Name(id='other_func', ctx=Load()),
                            args=[],
                            keywords=[])))],
            decorator_list=[])],
    type_ignores=[])

class ast.AsyncFor(target, iter, body, orelse, type_comment)

class ast.AsyncWith(items, body, type_comment)

async for loops and async with context managers. They have the same fields as For and With, respectively. Only valid in the body of an AsyncFunctionDef.

Nota

When a string is parsed by ast.parse(), operator nodes (subclasses of ast.operator, ast.unaryop, ast.cmpop, ast.boolop and ast.expr_context) on the returned tree will be singletons. Changes to one will be reflected in all other occurrences of the same value (e.g. ast.Add).

Ayudantes de ast

Además de las clases de nodo, el módulo ast define estas funciones y clases de utilidad para atravesar árboles de sintaxis abstracta:

ast.parse(source, filename='<unknown>', mode='exec', *, type_comments=False, feature_version=None)

Analiza la fuente en un nodo AST. Equivalente a compile(source, filename, mode, ast.PyCF_ONLY_AST).

Si se proporciona type_comments=True, el analizador se modifica para verificar y retornar los comentarios de tipo según lo especificado por PEP 484 [https://www.python.org/dev/peps/pep-0484] y PEP 526 [https://www.python.org/dev/peps/pep-0526]. Esto es equivalente a agregar ast.PyCF_TYPE_COMMENTS a los flags pasados a compile(). Esto informará errores de sintaxis para comentarios de tipo fuera de lugar. Sin este flag, los comentarios de tipo se ignorarán y el campo type_comment en los nodos AST seleccionados siempre será None. Además, las ubicaciones de los comentarios # type: ignore se retornarán como el atributo type_ignores de Module (de lo contrario, siempre es una lista vacía).

Además, si modo es 'func_type', la sintaxis de entrada se modifica para corresponder a PEP 484 [https://www.python.org/dev/peps/pep-0484] «comentarios de tipo de firma», por ejemplo (str, int) -> List[str].

Además, establece feature_version en una tupla (major, minor) intentará analizar usando la gramática de esa versión de Python. Actualmente major debe ser igual a 3. Por ejemplo, establece feature_version=(3, 4) permitirá el uso de async y await como nombres de variables. La versión más baja admitida es (3, 4); la más alto es sys.version_info[0:2].

If source contains a null character (“0”), ValueError is raised.

Advertencia

Note that successfully parsing source code into an AST object doesn’t guarantee that the source code provided is valid Python code that can be executed as the compilation step can raise further SyntaxError exceptions. For instance, the source return 42 generates a valid AST node for a return statement, but it cannot be compiled alone (it needs to be inside a function node).

In particular, ast.parse() won’t do any scoping checks, which the compilation step does.

Advertencia

Es posible bloquear el intérprete de Python con una cadena de caracteres suficientemente grande/compleja debido a las limitaciones de profundidad de pila en el compilador AST de Python.

Distinto en la versión 3.8: Se agregaron type_comments, mode='func_type' y feature_version.

ast.unparse(ast_obj)

Unparse an ast.AST object and generate a string with code that would produce an equivalent ast.AST object if parsed back with ast.parse().

Advertencia

The produced code string will not necessarily be equal to the original code that generated the ast.AST object (without any compiler optimizations, such as constant tuples/frozensets).

Advertencia

Trying to unparse a highly complex expression would result with RecursionError.

Nuevo en la versión 3.9.

ast.literal_eval(node_or_string)

Evalúa de forma segura un nodo de expresión o una cadena de caracteres que contenga un literal de Python o un visualizador de contenedor. La cadena o nodo proporcionado solo puede consistir en las siguientes estructuras literales de Python: cadenas de caracteres, bytes, números, tuplas, listas, diccionarios, conjuntos, booleanos y None.

Esto se puede usar para evaluar de forma segura las cadenas de caracteres que contienen valores de Python de fuentes no confiables sin la necesidad de analizar los valores uno mismo. No es capaz de evaluar expresiones complejas arbitrariamente, por ejemplo, que involucran operadores o indexación.

Advertencia

Es posible bloquear el intérprete de Python con una cadena de caracteres suficientemente grande/compleja debido a las limitaciones de profundidad de pila en el compilador AST de Python.

Distinto en la versión 3.2: Ahora permite bytes y establece literales.

Distinto en la versión 3.9: Now supports creating empty sets with 'set()'.

ast.get_docstring(node, clean=True)

Retorna la cadena de caracteres de documentación del node dado (que debe ser un nodo FunctionDef, AsyncFunctionDef, ClassDef, o Module), o None si no tiene docstring. Si clean es verdadero, limpia la sangría del docstring con inspect.cleandoc().

Distinto en la versión 3.5: AsyncFunctionDef ahora está soportada.

ast.get_source_segment(source, node, *, padded=False)

Obtenga el segmento de código fuente del source que generó node. Si falta información de ubicación (lineno, end_lineno, col_offset, o end_col_offset), retorna None.

Si padded es True, la primera línea de una declaración de varias líneas se rellenará con espacios para que coincidan con su posición original.

Nuevo en la versión 3.8.

ast.fix_missing_locations(node)

Cuando compila un árbol de nodos con compile(), el compilador espera los atributos lineno y col_offset para cada nodo que los soporta. Es bastante tedioso completar los nodos generados, por lo que este ayudante agrega estos atributos de forma recursiva donde aún no están establecidos, configurándolos en los valores del nodo principal. Funciona de forma recursiva comenzando en node.

ast.increment_lineno(node, n=1)

Incremente el número de línea y el número de línea final de cada nodo en el árbol comenzando en node por n. Esto es útil para «mover código» a una ubicación diferente en un archivo.

ast.copy_location(new_node, old_node)

Copia la ubicación de origen (lineno, col_offset, end_lineno, y end_col_offset) de old_node a new_node si es posible, y retorna new_node.

ast.iter_fields(node)

Produce (yield) una tupla de (fieldname, value) para cada campo en node._fields que está presente en node.

ast.iter_child_nodes(node)

Cede todos los nodos secundarios directos de node, es decir, todos los campos que son nodos y todos los elementos de campos que son listas de nodos.

ast.walk(node)

Recursivamente produce todos los nodos descendientes en el árbol comenzando en node (incluido node en sí mismo), en ningún orden especificado. Esto es útil si solo desea modificar los nodos en su lugar y no le importa el contexto.

class ast.NodeVisitor

Una clase base de visitante de nodo que recorre el árbol de sintaxis abstracta y llama a una función de visitante para cada nodo encontrado. Esta función puede retornar un valor que se reenvía mediante el método visit().

Esta clase está destinada a ser subclase, con la subclase agregando métodos de visitante.

visit(node)

Visita un nodo. La implementación predeterminada llama al método llamado self.visit_classname donde classname es el nombre de la clase de nodo, o generic_visit() si ese método no existe.

generic_visit(node)

Este visitante llama visit() en todos los hijos del nodo.

Tenga en cuenta que los nodos secundarios de los nodos que tienen un método de visitante personalizado no se visitarán a menos que el visitante llame generic_visit() o los visite a sí mismo.

No use NodeVisitor si desea aplicar cambios a los nodos durante el recorrido. Para esto existe un visitante especial (NodeTransformer) que permite modificaciones.

Obsoleto desde la versión 3.8: Los métodos visit_Num(), visit_Str(), visit_Bytes(), visit_NameConstant() y visit_Ellipsis() están en desuso ahora y no serán llamados en futuras versiones de Python. Agregue el método visit_Constant() para manejar todos los nodos constantes.

class ast.NodeTransformer

Una subclase de NodeVisitor que recorre el árbol de sintaxis abstracta y permite la modificación de nodos.

La clase NodeTransformer recorrerá el AST y usará el valor de retorno de los métodos del visitante para reemplazar o eliminar el nodo anterior. Si el valor de retorno del método de visitante es None, el nodo se eliminará de su ubicación; de lo contrario, se reemplazará con el valor de retorno. El valor de retorno puede ser el nodo original, en cuyo caso no se realiza ningún reemplazo.

Aquí hay un transformador de ejemplo que reescribe todas las apariciones de búsquedas de nombres (foo) en data['foo']:

class RewriteName(NodeTransformer):

    def visit_Name(self, node):
        return Subscript(
            value=Name(id='data', ctx=Load()),
            slice=Constant(value=node.id),
            ctx=node.ctx
        )

Tenga en cuenta que si el nodo en el que está operando tiene nodos secundarios, debe transformar los nodos secundarios usted mismo o llamar primero al método generic_visit() para el nodo.

Para los nodos que formaban parte de una colección de declaraciones (que se aplica a todos los nodos de declaración), el visitante también puede retornar una lista de nodos en lugar de solo un nodo.

Si NodeTransformer introduce nuevos nodos (que no eran parte del árbol original) sin darles información de ubicación (como lineno), fix_missing_locations() debería llamarse con el nuevo sub-árbol para recalcular la información de ubicación

tree = ast.parse('foo', mode='eval')
new_tree = fix_missing_locations(RewriteName().visit(tree))

Usualmente usas el transformador así:

node = YourTransformer().visit(node)

ast.dump(node, annotate_fields=True, include_attributes=False, *, indent=None)

Retorna un volcado formateado del árbol en node. Esto es principalmente útil para propósitos de depuración. Si annotate_fields es verdadero (por defecto), la cadena de caracteres retornada mostrará los nombres y los valores de los campos. Si annotate_fields es falso, la cadena de resultados será más compacta omitiendo nombres de campo no ambiguos. Los atributos como los números de línea y las compensaciones de columna no se vuelcan de forma predeterminada. Si esto se desea, include_attributes se puede establecer en verdadero.

If indent is a non-negative integer or string, then the tree will be pretty-printed with that indent level. An indent level of 0, negative, or "" will only insert newlines. None (the default) selects the single line representation. Using a positive integer indent indents that many spaces per level. If indent is a string (such as "\t"), that string is used to indent each level.

Distinto en la versión 3.9: Added the indent option.

Compiler Flags

The following flags may be passed to compile() in order to change effects on the compilation of a program:

ast.PyCF_ALLOW_TOP_LEVEL_AWAIT

Enables support for top-level await, async for, async with and async comprehensions.

Nuevo en la versión 3.8.

ast.PyCF_ONLY_AST

Generates and returns an abstract syntax tree instead of returning a compiled code object.

ast.PyCF_TYPE_COMMENTS

Enables support for PEP 484 [https://www.python.org/dev/peps/pep-0484] and PEP 526 [https://www.python.org/dev/peps/pep-0526] style type comments (# type: <type>, # type: ignore <stuff>).

Nuevo en la versión 3.8.

Command-Line Usage

Nuevo en la versión 3.9.

The ast module can be executed as a script from the command line. It is as simple as:

python -m ast [-m <mode>] [-a] [infile]

The following options are accepted:

-h, --help

Show the help message and exit.

-m <mode>

--mode <mode>

Specify what kind of code must be compiled, like the mode argument in parse().

--no-type-comments

Don’t parse type comments.

-a, --include-attributes

Include attributes such as line numbers and column offsets.

-i <indent>

--indent <indent>

Indentation of nodes in AST (number of spaces).

If infile is specified its contents are parsed to AST and dumped to stdout. Otherwise, the content is read from stdin.

Ver también

Green Tree Snakes [https://greentreesnakes.readthedocs.io/], un recurso de documentación externo, tiene buenos detalles sobre cómo trabajar con Python AST.

ASTTokens [https://asttokens.readthedocs.io/en/latest/user-guide.html] annotates Python ASTs with the positions of tokens and text in the source code that generated them. This is helpful for tools that make source code transformations.

leoAst.py [http://leoeditor.com/appendices.html#leoast-py] unifies the token-based and parse-tree-based views of python programs by inserting two-way links between tokens and ast nodes.

LibCST [https://libcst.readthedocs.io/] parses code as a Concrete Syntax Tree that looks like an ast tree and keeps all formatting details. It’s useful for building automated refactoring (codemod) applications and linters.

Parso [https://parso.readthedocs.io] is a Python parser that supports error recovery and round-trip parsing for different Python versions (in multiple Python versions). Parso is also able to list multiple syntax errors in your python file.

symtable — Acceso a la tabla de símbolos del compilador

Código fuente: Lib/symtable.py [https://github.com/python/cpython/tree/3.9/Lib/symtable.py]

Las tablas de símbolos son generadas por el compilador a partir del AST justo antes de que el bytecode sea generado. La tabla de símbolos es responsable de calcular el ámbito de cada identificador en el código. symtable provee una interfaz para examinar esas tablas.

Generando tablas de símbolos

symtable.symtable(code, filename, compile_type)

Retorna la SymbolTable del nivel más alto para el código Python code. filename es el nombre del archivo conteniendo el código. compile_type es como el argumento mode de la función compile().

Examinando la tabla de símbolos

class symtable.SymbolTable

Un espacio de nombres para el bloque. El constructor no es público.

get_type()

Retorna el tipo de la tabla de símbolos. Los valores posibles son 'class', 'module' y 'function'.

get_id()

Retorna el identificador de la tabla.

get_name()

Retorna el nombre de la tabla. Este es el nombre de la clase si la tabla es para una clase, el nombre de la función si la tabla es para una función, o 'top' si la tabla es global (get_type() retorna 'module').

get_lineno()

Retorna el número de la primera línea en el bloque que esta tabla representa.

is_optimized()

Retorna True si los locales en esta tabla pueden ser optimizados.

is_nested()

Retorna True si el bloque es una clase o función anidadas.

has_children()

Retorna True si el bloque contiene espacios de nombres anidados en él. Estos pueden ser obtenidos con get_children().

get_identifiers()

Retorna una lista con los nombres de los símbolos en esta tabla.

lookup(name)

Busca name en la tabla y retorna una instancia de Symbol.

get_symbols()

Retorna una lista de instancias de Symbol de los nombres en la tabla.

get_children()

Retorna una lista de las tablas de símbolos anidadas.

class symtable.Function

Un espacio de nombres para una función o método. Esta clase hereda de SymbolTable.

get_parameters()

Retorna una tupla conteniendo los nombres de los parámetros de esta función.

get_locals()

Retorna una tupla conteniendo los nombres de los locales en esta función.

get_globals()

Retorna una tupla conteniendo los nombres de los globales en esta función.

get_nonlocals()

Retorna una tupla conteniendo los nombres de los no locales en esta función.

get_frees()

Retorna una tupla conteniendo los nombres de las variables libres en esta función.

class symtable.Class

Un espacio de nombres de una clase. Esta clase hereda de SymbolTable.

get_methods()

Retorna una tupla conteniendo los nombres de los métodos declarados en la clase.

class symtable.Symbol

Una entrada en una SymbolTable correspondiente a un identificador en el código. El constructor no es público.

get_name()

Retorna el nombre del símbolo.

is_referenced()

Retorna True si el símbolo es usado en su bloque.

is_imported()

Retorna True si el símbolo es creado desde una instrucción import.

is_parameter()

Retorna True si el símbolo es un parámetro.

is_global()

Retorna True si el símbolo es global.

is_nonlocal()

Retorna True si el símbolo es no local.

is_declared_global()

Retorna True si el símbolo es declarado global con una instrucción global.

is_local()

Retorna True si el símbolo es local a su bloque.

is_annotated()

Retorna True si el símbolo está anotado.

Nuevo en la versión 3.6.

is_free()

Retorna True si el símbolo es referenciado en su bloque pero no asignado.

is_assigned()

Retorna True si el símbolo es asignado en su bloque.

is_namespace()

Retorna True si la vinculación de nombres introduce un nuevo espacio de nombres.

Si el nombre es usado como objetivo de una instrucción function o class retornará verdadero.

Por ejemplo:

>>> table = symtable.symtable("def some_func(): pass", "string", "exec")
>>> table.lookup("some_func").is_namespace()
True

Note que un solo nombre puede estar vinculado a varios objetos. Si el resultado es True, el nombre puede estar vinculado también a otros objetos, como un entero o una lista, esto no introduce un nuevo espacio de nombres.

get_namespaces()

Retorna una lista de espacios de nombres vinculados a este nombre.

get_namespace()

Retorna el espacio de nombres vinculado a este nombre. Si más de un espacio de nombres esta vinculado se lanza un ValueError.

symbol — Constantes utilizadas con árboles de análisis de Python

Código fuente: Lib/symbol.py [https://github.com/python/cpython/tree/3.9/Lib/symbol.py]

Este módulo proporciona constantes que representan los valores numéricos de nodos internos del árbol de análisis. A diferencia de la mayoría de las constantes de Python, estas utilizan nombres en minúsculas. Refiérase al archivo Grammar/Grammar en la distribución de Python para las definiciones de los nombres en el contexto de la gramática del lenguaje. Los valores numéricos específicos que corresponden a los nombres pueden variar entre versiones de Python.

Advertencia

The symbol module is deprecated and will be removed in future versions of Python.

Este módulo también proporciona un objecto de datos adicional:

symbol.sym_name

Diccionario que mapea los valores numéricos de las constantes definidas en este módulo a cadenas de nombre, lo que permite generar una representación más legible por humanos de árboles de análisis.

token— Constantes usadas con árboles de sintaxis de Python

Código fuente: Lib/token.py [https://github.com/python/cpython/tree/3.9/Lib/token.py]

Este módulo provee constantes que representan los valores numéricos de nodos hoja de un árbol de sintaxis (tokens terminales). Referirse al archivo Grammar/Grammar en la distribución de Python para las definiciones de los nombres en el contexto de gramática del lenguaje. Los valores numéricos específicos a los que los nombres mapean pueden cambiar entre versiones de Python.

El módulo también proporciona un mapeo de códigos numéricos a nombres y algunas funciones. Las funciones asemejan definiciones en los archivos Python C encabezados.

token.tok_name

Diccionario que mapea los valores numéricos de las constantes definidas en este módulo a cadenas de nombres, permitiendo una representación de árboles de sintaxis a ser generados más legible para humanos.

token.ISTERMINAL(x)

Retorna True para valores token terminales.

token.ISNONTERMINAL(x)

Retorna True para valores token no terminales.

token.ISEOF(x)

Retorna True si x es el marcador indicando el final del input.

Las constantes de token son:

token.ENDMARKER

token.NAME

token.NUMBER

token.STRING

token.NEWLINE

token.INDENT

token.DEDENT

token.LPAR

Token value for "(".

token.RPAR

Token value for ")".

token.LSQB

Token value for "[".

token.RSQB

Token value for "]".

token.COLON

Token value for ":".

token.COMMA

Token value for ",".

token.SEMI

Token value for ";".

token.PLUS

Token value for "+".

token.MINUS

Token value for "-".

token.STAR

Token value for "*".

token.SLASH

Token value for "/".

token.VBAR

Token value for "|".

token.AMPER

Token value for "&".

token.LESS

Token value for "<".

token.GREATER

Token value for ">".

token.EQUAL

Token value for "=".

token.DOT

Token value for ".".

token.PERCENT

Token value for "%".

token.LBRACE

Token value for "{".

token.RBRACE

Token value for "}".

token.EQEQUAL

Token value for "==".

token.NOTEQUAL

Token value for "!=".

token.LESSEQUAL

Token value for "<=".

token.GREATEREQUAL

Token value for ">=".

token.TILDE

Token value for "~".

token.CIRCUMFLEX

Token value for "^".

token.LEFTSHIFT

Token value for "<<".

token.RIGHTSHIFT

Token value for ">>".

token.DOUBLESTAR

Token value for "**".

token.PLUSEQUAL

Token value for "+=".

token.MINEQUAL

Token value for "-=".

token.STAREQUAL

Token value for "*=".

token.SLASHEQUAL

Token value for "/=".

token.PERCENTEQUAL

Token value for "%=".

token.AMPEREQUAL

Token value for "&=".

token.VBAREQUAL

Token value for "|=".

token.CIRCUMFLEXEQUAL

Token value for "^=".

token.LEFTSHIFTEQUAL

Token value for "<<=".

token.RIGHTSHIFTEQUAL

Token value for ">>=".

token.DOUBLESTAREQUAL

Token value for "**=".

token.DOUBLESLASH

Token value for "//".

token.DOUBLESLASHEQUAL

Token value for "//=".

token.AT

Token value for "@".

token.ATEQUAL

Token value for "@=".

token.RARROW

Token value for "->".

token.ELLIPSIS

Token value for "...".

token.COLONEQUAL

Token value for ":=".

token.OP

token.AWAIT

token.ASYNC

token.TYPE_IGNORE

token.TYPE_COMMENT

token.ERRORTOKEN

token.N_TOKENS

token.NT_OFFSET

Los siguientes tipos de valores tokens no son usados por el tokenizador C pero son necesarios para el modulo tokenizador.

token.COMMENT

Valores token usados para indicar un comentario.

token.NL

Valor token usado para indicar una nueva línea no terminante. El token NEWLINE indica el final de una línea lógica de código Python; los tokens NL son generados cuando una línea lógica de código es continuada sobre múltiples líneas físicas.

token.ENCODING

Valor de token que indica la codificación usada para decodificar los bytes de origen en texto. El primer token retornado por tokenize.tokenize() siempre será un token ENCODING.

token.TYPE_COMMENT

Valor token indicando que un tipo comentario fue reconocido. Dichos tokens solo son producidos cuando ast.parse() es invocado con type_comments=True.

Distinto en la versión 3.5: Agregados los tokens AWAIT y ASYNC.

Distinto en la versión 3.7: Agregados los tokens COMMENT, NL y ENCODING.

Distinto en la versión 3.7: Removidos los tokens AWAIT y ASYNC. «async» y «await» son ahora tokenizados como NAME tokens.

Distinto en la versión 3.8: Agregados TYPE_COMMENT, TYPE_IGNORE, COLONEQUAL. Agregados de regreso los tokens AWAIT y ASYNC (son necesarios para dar soporte en la sintaxis de versiones más antiguas de Python para ast.parse() con feature_version establecido a 6 o menor).

keyword — Pruebas para palabras clave en Python

Código fuente: Lib/keyword.py [https://github.com/python/cpython/tree/3.9/Lib/keyword.py]

Este módulo permite a un programa Python determinar si una cadena de caracteres es una palabra clave.

keyword.iskeyword(s)

Retorna True si s es una palabra clave Python.

keyword.kwlist

Secuencia que contiene todos las palabras clave definidos para el intérprete. Si cualquier palabra clave es definida para estar activa sólo cuando las declaraciones particulares __future__ están vigentes, estas se incluirán también.

keyword.issoftkeyword(s)

Retorna True si s es una palabra clave de Python suave.

Nuevo en la versión 3.9.

keyword.softkwlist

Secuencia que contiene todos las palabras clave suaves definidas para el intérprete. Si se define alguna palabra clave blanda para que solo esté activa cuando las declaraciones particulares __future__ están en vigor, estas también se incluirán.

Nuevo en la versión 3.9.

tokenize — Conversor a tokens para código Python

Código fuente: Lib/tokenize.py [https://github.com/python/cpython/tree/3.9/Lib/tokenize.py]

El módulo tokenize provee un analizador léxico para código fuente Python, implementado en Python. Este analizador también retorna comentarios como tokens, siendo útil para implementar «pretty-printers», como colorizers para impresiones en pantalla.

Para simplificar el manejo de flujos de tokens, todos los tokens operator y delimiter y Ellipsis se retorna usando el tipo genérico OP. El tipo exacto se puede determinar usando la propiedad exact_type en la named tuple retornada por tokenize.tokenize().

Convirtiendo la entrada en tokens

El punto de entrada principal es un generador:

tokenize.tokenize(readline)

El generador tokenize() requiere un argumento, readline, que debe ser un objeto invocable que provee la misma interfaz que el método io.IOBase.readline() de los objetos archivos. Cada llamada a la función debe retornar una línea de entrada como bytes.

El generador produce una tupla con los siguientes 5 miembros: El tipo de token, la cadena del token, una tupla (srow, scol) de enteros especificando la fila y columna donde el token empieza en el código, una (erow, ecol) de enteros especificando la fila y columna donde el token acaba en el código, y la línea en la que se encontró el token. La línea pasada (el último elemento de la tupla) es la línea física. La tupla se retorna como una named tuple con los campos: type string start end line.

La named tuple retorna tiene una propiedad adicional llamada exact_type que contiene el tipo de operador exacto para tokens OP. Para todos los otros tipos de token, exact_type es el valor del campo type de la tupla con su respectivo nombre.

Distinto en la versión 3.1: Añadido soporte para tuplas con nombre.

Distinto en la versión 3.3: Añadido soporte para exact_type.

tokenize() determina la codificación del fichero buscando una marca BOM UTF-8 o una cookie de codificación, de acuerdo con PEP 263 [https://www.python.org/dev/peps/pep-0263].

tokenize.generate_tokens(readline)

Convertir a tokens una fuente leyendo cadenas unicode en lugar de bytes.

Como tokenize(), el argumento readline es un invocable que retorna una sola línea de entrada. Sin embargo, generate_tokens() espera que readline retorne un objeto str en lugar de bytes.

El resultado es un iterador que produce tuplas con nombre, exactamente como tokenize(). No produce un token ENCODING.

Todas las constantes del módulo token se exportan también desde tokenize.

Otra función se encarga de invertir el proceso de conversión. Esto es útil para crear herramientas que convierten a tokens un script, modificar el flujo de token, y escribir el script modificado.

tokenize.untokenize(iterable)

Convierte los tokens de vuelta en código fuente Python. El iterable debe retornar secuencias con al menos dos elementos, el tipo de token y la cadena del token. Cualquier otro elemento de la secuencia es ignorado.

El script reconstruido se retorna como una cadena simple. El resultado está garantizado de que se convierte en tokens de vuelta a la misma entrada, de modo que la conversión no tiene pérdida y que las conversiones de ida y de vuelta están aseguradas. La garantía aplica sólo al tipo y la cadena del token, ya que el espaciado entre tokens (posiciones de columna) pueden variar.

Retorna bytes, codificados usando el token ENCODING, que es el primer elemento de la secuencia retornada por tokenize(). Si no hay un token de codificación en la entrada, retorna una cadena.

tokenize() necesita detectar la codificación de los ficheros fuente que convierte a tokens. La función que utiliza para hacer esto está disponible como:

tokenize.detect_encoding(readline)

La función detect_encoding() se usa para detectar la codificación que debería usarse al leer un fichero fuente Python. Requiere un argumento, readline, del mismo modo que el generador tokenize().

Llamará a readline un máximo de dos veces, retornando la codificación usada, como cadena, y una lista del resto de líneas leídas, no descodificadas de bytes.

Detecta la codificación a partir de la presencia de una marca BOM UTF-8 o una cookie de codificación, como se especifica en PEP 263 [https://www.python.org/dev/peps/pep-0263]. Si ambas están presentes pero en desacuerdo, se lanzará un SyntaxError. Resaltar que si se encuentra la marca BOM, se retornará 'utf-8-sig' como codificación.

Si no se especifica una codificación, por defecto se retornará 'utf-8'.

Usa open() para abrir ficheros fuente Python: Ésta utiliza detect_encoding() para detectar la codificación del fichero.

tokenize.open(filename)

Abrir un fichero en modo sólo lectura usando la codificación detectada por detect_encoding().

Nuevo en la versión 3.2.

exception tokenize.TokenError

Lanzada cuando una expresión o docstring que puede separarse en más líneas no está completa en el fichero, por ejemplo:

"""Beginning of
docstring

o:

[1,
 2,
 3

Destacar que cadenas con comillas simples sin finalizar no lanzan un error. Se convertirán en tokens como ERRORTOKEN, seguido de la conversión de su contenido.

Uso como línea de comandos

Nuevo en la versión 3.3.

El módulo tokenize se puede ejecutar como script desde la línea de comandos. Es tan simple como:

python -m tokenize [-e] [filename.py]

Se aceptan las siguientes opciones:

-h, --help

muestra el mensaje de ayuda y sale

-e, --exact

muestra los nombres de token usando el tipo exacto

Si se especifica filename.py, se convierte su contenido a tokens por la salida estándar. En otro caso, se convierte la entrada estándar.

Ejemplos

Ejemplo de un script que transforma literales float en objetos Decimal:

from tokenize import tokenize, untokenize, NUMBER, STRING, NAME, OP
from io import BytesIO

def decistmt(s):
    """Substitute Decimals for floats in a string of statements.

    >>> from decimal import Decimal
    >>> s = 'print(+21.3e-5*-.1234/81.7)'
    >>> decistmt(s)
    "print (+Decimal ('21.3e-5')*-Decimal ('.1234')/Decimal ('81.7'))"

    The format of the exponent is inherited from the platform C library.
    Known cases are "e-007" (Windows) and "e-07" (not Windows).  Since
    we're only showing 12 digits, and the 13th isn't close to 5, the
    rest of the output should be platform-independent.

    >>> exec(s)  #doctest: +ELLIPSIS
    -3.21716034272e-0...7

    Output from calculations with Decimal should be identical across all
    platforms.

    >>> exec(decistmt(s))
    -3.217160342717258261933904529E-7
    """
    result = []
    g = tokenize(BytesIO(s.encode('utf-8')).readline)  # tokenize the string
    for toknum, tokval, _, _, _ in g:
        if toknum == NUMBER and '.' in tokval:  # replace NUMBER tokens
            result.extend([
                (NAME, 'Decimal'),
                (OP, '('),
                (STRING, repr(tokval)),
                (OP, ')')
            ])
        else:
            result.append((toknum, tokval))
    return untokenize(result).decode('utf-8')

Ejemplo de conversión desde la línea de comandos. El script:

def say_hello():
    print("Hello, World!")

say_hello()

se convertirá en la salida siguiente, donde la primera columna es el rango de coordenadas línea/columna donde se encuentra el token, la segunda columna es el nombre del token, y la última columna es el valor del token, si lo hay

$ python -m tokenize hello.py
0,0-0,0:            ENCODING       'utf-8'
1,0-1,3:            NAME           'def'
1,4-1,13:           NAME           'say_hello'
1,13-1,14:          OP             '('
1,14-1,15:          OP             ')'
1,15-1,16:          OP             ':'
1,16-1,17:          NEWLINE        '\n'
2,0-2,4:            INDENT         '    '
2,4-2,9:            NAME           'print'
2,9-2,10:           OP             '('
2,10-2,25:          STRING         '"Hello, World!"'
2,25-2,26:          OP             ')'
2,26-2,27:          NEWLINE        '\n'
3,0-3,1:            NL             '\n'
4,0-4,0:            DEDENT         ''
4,0-4,9:            NAME           'say_hello'
4,9-4,10:           OP             '('
4,10-4,11:          OP             ')'
4,11-4,12:          NEWLINE        '\n'
5,0-5,0:            ENDMARKER      ''

Los nombres de tipos de token exactos se pueden mostrar con la opción -e:

$ python -m tokenize -e hello.py
0,0-0,0:            ENCODING       'utf-8'
1,0-1,3:            NAME           'def'
1,4-1,13:           NAME           'say_hello'
1,13-1,14:          LPAR           '('
1,14-1,15:          RPAR           ')'
1,15-1,16:          COLON          ':'
1,16-1,17:          NEWLINE        '\n'
2,0-2,4:            INDENT         '    '
2,4-2,9:            NAME           'print'
2,9-2,10:           LPAR           '('
2,10-2,25:          STRING         '"Hello, World!"'
2,25-2,26:          RPAR           ')'
2,26-2,27:          NEWLINE        '\n'
3,0-3,1:            NL             '\n'
4,0-4,0:            DEDENT         ''
4,0-4,9:            NAME           'say_hello'
4,9-4,10:           LPAR           '('
4,10-4,11:          RPAR           ')'
4,11-4,12:          NEWLINE        '\n'
5,0-5,0:            ENDMARKER      ''

Ejemplo de tokenización de un fichero programáticamente, leyendo cadenas unicode en lugar de bytes con generate_tokens():

import tokenize

with tokenize.open('hello.py') as f:
    tokens = tokenize.generate_tokens(f.readline)
    for token in tokens:
        print(token)

O leyendo bytes directamente con tokenize():

import tokenize

with open('hello.py', 'rb') as f:
    tokens = tokenize.tokenize(f.readline)
    for token in tokens:
        print(token)

tabnanny — Detección de indentación ambigua

Código fuente: Lib/tabnanny.py [https://github.com/python/cpython/tree/3.9/Lib/tabnanny.py]

Por el momento, este módulo está pensado para ser llamado como un script. Sin embargo, es posible importarlo en un IDE y usar la función check() que se describe a continuación.

Nota

Es probable que la API proporcionada por este módulo cambie en versiones futuras; dichos cambios pueden no ser compatibles con versiones anteriores.

tabnanny.check(file_or_dir)

Si file_or_dir es un directorio y no un enlace simbólico, desciende recursivamente en el árbol de directorios nombrado por file_or_dir, verificando todos los archivos .py al mismo tiempo. Si file_or_dir es un archivo fuente normal de Python, se comprueba si hay problemas relacionados con los espacios en blanco. Los mensajes de diagnóstico se escriben en la salida estándar mediante la función print().

tabnanny.verbose

Marcador que indica si se deben imprimir mensajes detallados. Esto se incrementa con la opción -v si se llama como un script.

tabnanny.filename_only

Marcador que indica si se deben imprimir solo los nombres de archivo de los archivos que contienen problemas relacionados con los espacios en blanco. Esto se establece como verdadero con la opción -q si se llama como un script.

exception tabnanny.NannyNag

Invocada por process_tokens() sí detecta una indentación ambigua. Capturada y gestionada en check().

tabnanny.process_tokens(tokens)

Esta función es utilizada por check() para procesar los tokens generados por el módulo tokenize.

Ver también

Módulo tokenize

Escáner léxico para código fuente Python.

pyclbr — Soporte para navegador de módulos Python

Código fuente: Lib/pyclbr.py [https://github.com/python/cpython/tree/3.9/Lib/pyclbr.py]

El módulo pyclbr proporciona información limitada sobre las funciones, clases y métodos definidos en un módulo de Python. La información es suficiente para implementar un navegador de módulos. La información se extrae del código fuente de Python en lugar de importar el módulo, por lo que este módulo es seguro de usar con código que no es de confianza. Esta restricción hace que sea imposible utilizar este módulo con módulos no implementados en Python, incluidos todos los módulos de extensión estándar y opcionales.

pyclbr.readmodule(module, path=None)

Retorna un diccionario que asigna nombres de clase a nivel de módulo con descriptores de clase. Si es posible, se incluyen descriptores para las clases base importadas. El parámetro module es una cadena con el nombre del módulo que se va a leer; puede ser el nombre de un módulo dentro de un paquete. Si se indica, path es una secuencia de rutas de directorios antepuesto a sys.path, que se utiliza para localizar el código fuente del módulo.

Esta función es la interfaz original y sólo se mantiene por compatibilidad. Retorna una versión filtrada de lo siguiente.

pyclbr.readmodule_ex(module, path=None)

Retorna un árbol basado en diccionarios que contiene un descriptor de función o clase para cada función y clase definida en el módulo con una instrucción def o class. El diccionario retornado asigna nombres de clase y función a nivel de módulo con sus descriptores. Los objetos anidados se introducen en el diccionario hijo de su elemento padre. Al igual que con readmodule, module nombra el módulo que se va a leer y path se antepone a sys.path. Si el módulo que se lee es un paquete, el diccionario retornado tiene una clave '__path__' cuyo valor es una lista que contiene la ruta del paquete.

Nuevo en la versión 3.7: Descriptores para definiciones anidadas. Se accede a ellos a través del nuevo atributo children. Cada uno tiene un nuevo atributo parent.

Los descriptores retornados por estas funciones son instancias de las clases Function y Class. No se espera que los usuarios creen instancias de estas clases.

Objetos Function

Las instancias de la clase Function describen funciones definidas por instrucciones def. Tienen los siguientes atributos:

Function.file

Nombre del archivo en el cual la función está definida.

Function.module

El nombre del módulo que define la función descrita.

Function.name

El nombre de la función.

Function.lineno

El número de línea el en archivo donde inicia la definición.

Function.parent

Para funciones en el nivel más alto, None. Para funciones anidadas, el padre.

Nuevo en la versión 3.7.

Function.children

Un diccionario asignando nombres con descriptores para las clases y funciones anidadas.

Nuevo en la versión 3.7.

Objetos Class

Las instancias de las clase Class describen clases definidas por instrucciones class. Tienen los mismos atributos que Functions y dos más.

Class.file

Nombre del archivo en el que la clase está definida.

Class.module

Nombre del módulo que define la clase descrita.

Class.name

El nombre de la clase.

Class.lineno

El número de línea el en archivo donde inicia la definición.

Class.parent

Para clases en el nivel más alto, None. Para clases anidadas, el padre.

Nuevo en la versión 3.7.

Class.children

Un diccionario asignando nombres con descriptores para las clases y funciones anidadas.

Nuevo en la versión 3.7.

Class.super

Una lista de objetos Class que describen las clases base inmediatas de la clase que se está describiendo. Las clases que se denominan superclases pero que no son detectables por readmodule_ex() se enumeran como una cadena con el nombre de clase en lugar de objetos Class.

Class.methods

Un diccionario asignando los nombres de los métodos a sus números de línea. Esto se puede derivar del reciente diccionario children, pero permanece por compatibilidad.

py_compile` — Compila archivos fuente Python

Código fuente Lib/py_compile.py [https://github.com/python/cpython/tree/3.9/Lib/py_compile.py]

El módulo py_compile provee una función para generar un archivo de código de bytes de un archivo fuente, y otra función usada cuando el módulo archivo fuente es invocado como un script.

Aunque no es necesario seguidamente, esta función puede ser útil cuando se instalan módulos para uso compartido, especialmente si algunos de los usuarios pueden no tener permisos para escribir el archivo caché de bytes en el directorio conteniendo el código fuente.

exception py_compile.PyCompileError

Cuando un error ocurre mientras se intenta compilar el archivo, se lanza una excepción.

py_compile.compile(file, cfile=None, dfile=None, doraise=False, optimize=-1, invalidation_mode=PycInvalidationMode.TIMESTAMP, quiet=0)

Compila un archivo fuente en código de bytes y escriba el archivo de caché de código de bytes. El código fuente se carga desde el archivo llamado file. El código de bytes se escribe en cfile, que por defecto es la ruta PEP 3147 [https://www.python.org/dev/peps/pep-3147]/PEP 488 [https://www.python.org/dev/peps/pep-0488], que termina en .pyc. Por ejemplo, si file es /foo/bar/baz.py cfile se establecerá de forma predeterminada en /foo/bar/__pycache__/baz.cpython-32.pyc para Python 3.2. Si se especifica dfile, se usa como el nombre del archivo de origen en los mensajes de error en lugar de file. Si doraise es verdadero, se lanza un PyCompileError cuando se encuentra un error al compilar file. Si doraise es falso (el valor predeterminado), se escribe una cadena de error en sys.stderr, pero no se genera ninguna excepción. Esta función retorna la ruta al archivo compilado por bytes, es decir, cualquier valor cfile que se haya utilizado.

Los argumentos doraise y quiet determinan cómo los errores son gestionados mientras se compila el archivo. Si quiet es 0 o 1, y doraise es falso, la conducta por defecto es habilitada: un error cadena de caracteres es escrito a sys.stderr, y la función retorna None en vez de una ruta. Si doraise es verdadero, se lanzará un PyCompileError. Sin embargo si quiet es 2, ningún mensaje es escrito y doraise no tiene efecto.

Si la ruta que cfile se convierte (sea especificada explícitamente o computada) es un enlace simbólico o archivo no regular, se lanzará FileExistsError. Esto es para actuar como una advertencia que la importación convertirá esas rutas en archivos regulares si ésta tiene permitido escribir archivos compilados en bytes a esas rutas. Este es un efecto secundario de importar usando el renombramiento de archivos para colocar el archivo de bytes compilado final en el lugar para prevenir problemas de escritura en archivos simultáneos.

optimize controla el nivel de optimización y si es pasado a la función construida compile(). El predeterminado de -1 selecciona el nivel de optimización del intérprete actual.

invalidation_mode debería ser un miembro del enum PycInvalidationMode y controla cómo el caché de código de bytes generado es invalidado en el tiempo de ejecución. El predeterminado es PycInvalidationMode.CHECKED_HASH si la variable de entorno SOURCE_DATE_EPOCH está establecida, de otra manera el predeterminado es PycInvalidationMode.TIMESTAMP.

Distinto en la versión 3.2: Cambiado el valor por defecto de cfile para que cumpla PEP 3147 [https://www.python.org/dev/peps/pep-3147]. El por defecto anterior era file + 'c' ('o' si la optimización estaba habilitada). También agregado el parámetro optimize.

Distinto en la versión 3.4: Se cambió el código para usar importlib para la escritura del archivo almacenado de código de bytes. Esto significa que la semántica de la creación/escritura del archivo ahora coincide con lo que importlib hace, por ejemplo permisos, semántica de escribir-y-mover, etc. Además se agregó la consideración de que FileExistsError es lanzado si cfile es un enlace simbólico o un archivo no regular.

Distinto en la versión 3.7: El parámetro invalidation_mode fue agregado como se especificó en PEP 552 [https://www.python.org/dev/peps/pep-0552]. Si la variable de entorno SOURCE_DATE_EPOCH se establece, invalidation_mode será forzada a PycInvalidationMode.CHECKED_HASH.

Distinto en la versión 3.7.2: La variable de entorno SOURCE_DATE_EPOCH ya no sobreescribe el valor del argumento invalidation_mode, y en vez de eso determina su valor por defecto.

Distinto en la versión 3.8: El parámetro quiet fue agregado.

class py_compile.PycInvalidationMode

Una enumeración de métodos posibles que el intérprete puede usar para determinar si un archivo de bytes está actualizado con un archivo fuente. El archivo .pyc indica el modo invalidación deseado en su encabezado. Ver Invalidación del código de bytes en caché para más información en cómo Python invalida archivos .pyc en tiempo de ejecución.

Nuevo en la versión 3.7.

TIMESTAMP

El archivo .pyc incluye una marca de tiempo y tamaño del archivo fuente, el cual Python comparará contra los metadatos del archivo fuente durante el tiempo de ejecución para determinar si el archivo .pyc necesita ser regenerado.

CHECKED_HASH

El archivo .pyc incluye un hash del contenido del archivo fuente, el cual Python comparará contra la fuente durante el tiempo de ejecución para determinar si el archivo .pyc necesita ser regenerado.

UNCHECKED_HASH

Como CHECKED_HASH, el archivo .pyc incluye un has del contenido del archivo fuente. Sin embargo, Python asumirá durante el tiempo de ejecución que el archivo .pyc está actualizado y no validará el .pyc contra el archivo fuente en lo absoluto.

Esta opción es útil cuando los .pucs se mantienen actualizados al día por algún sistema externo a Python como un sistema de compilación.

py_compile.main(args=None)

Compila varios archivos fuente. Los archivos mencionados en args (o en la línea de comandos si args es None) son compilados y el código de bytes resultante es almacenado de la manera normal. Esta función no busca una estructura de directorio para localizar archivos fuente; éste sólo compila archivos nombrados explícitamente. Si '-' es el único parámetro en args, la lista de archivos es tomada de una entrada estándar.

Distinto en la versión 3.2: Agregado soporte para '-'.

Cuando este módulo se ejecuta como un script, el main() es usado para compilar todos los archivos llamados en la línea de comandos. El estado de salida es no cero si uno de los archivos no se pudo compilar.

Ver también

Módulo compileall

Utilidades para compilar todos los archivos fuente Python en el árbol del directorio.

compileall — Bibliotecas de Python de compilación de bytes

Código fuente: Lib/compileall.py [https://github.com/python/cpython/tree/3.9/Lib/compileall.py]

Este módulo proporciona algunas funciones de utilidad para admitir la instalación de bibliotecas Python. Estas funciones compilan archivos fuente de Python en un árbol de directorios. Este módulo se puede usar para crear los archivos de código de bytes almacenados en caché en el momento de la instalación de la biblioteca, que los hace disponibles para su uso incluso por usuarios que no tienen permiso de escritura en los directorios de la biblioteca.

Uso de la línea de comandos

Este módulo puede funcionar como un script (usando python -m compileall) para compilar fuentes de Python.

directory ...

file ...

Los argumentos posicionales son archivos para compilar o directorios que contienen archivos fuente, recorridos recursivamente. Si no se proporciona ningún argumento, se comporta como si la línea de comando fuera -l <directories from sys.path>.

-l

No se recurre en subdirectorios, solo compila archivos de código fuente contenidos en directorios nombrados o implícitos.

-f

Forzar la reconstrucción incluso si las marcas de tiempo están actualizadas.

-q

No imprimir la lista de archivos compilados. Si se pasa una vez, los mensajes de error se imprimirán. Si se pasa dos veces, (-qq), se suprime toda la salida.

-d destdir

Directorio antepuesto a la ruta de cada archivo que está siendo compilado. Esto aparecerá en las devoluciones de tiempo de compilación, y también se compila en el archivo de código de bytes, donde se usará en las devoluciones de seguimiento y otros mensajes en casos donde el archivo fuente no existe al momento en que el archivo de código de bytes se ejecuta.

-s strip_prefix

-p prepend_prefix

Elimina (-s) o agrega (-p) el prefijo dado de rutas registradas en los archivos .pyc. No se puede combinar con -d.

-x regex

regex se usa para buscar la ruta completa a cada archivo considerado para compilación, y si la regex produce una coincidencia, se omite el archivo.

-i list

Leer el archivo list y cada línea que contiene la lista de archivos y directorios a compilar. Si list es -, leer líneas desde stdin.

-b

Escribir los archivos de código de byte en las locaciones y nombres de herencia, que pueden sobreescribir los archivos de código de bytes creado para otra versión de Python. El comportamiento por defecto es escribir archivos en sus locaciones y nombres PEP 3147 [https://www.python.org/dev/peps/pep-3147], lo cual permite que archivos de código de byte de versiones múltiples de Python coexistan.

-r

Controlar el nivel máximo de recurrencia para subdirectorios. Si esto está dado, la opción -l no se tendrá en cuenta. python -m compileall <directory> -r 0 es equivalente a python -m compileall <directory> -l.

-j N

Usar workers N para compilar los archivos dentro del directorio dado. Si `0 se usa, entonces se usa el resultado de os.cpu_count().

--invalidation-mode [timestamp|checked-hash|unchecked-hash]

Controlar cómo los archivos de código de byte generados se invalidan al momento de ejecución. El valor timestamp significa que se generarán los archivos .pyc con la marca de tiempo fuente y el tamaño insertados. Los valores checked-hash y unchecked-hash generan pycs basados en hash. Los pycs basados en hash del archivo insertan un hash de los contenidos del archivo fuente, en lugar de una marca de tiempo. Véase Invalidación del código de bytes en caché para mayor información sobre cómo Python valida archivos de cache de código de bytes. El valor por defecto es timestamp si la variable de entorno SOURCE_DATE_EPOCH no está definida, y checked-hash si la variable de entorno SOURCE_DATE_EPOCH` está definida.

-o level

Compila con el nivel de optimización dado. Puede usarse varias veces para compilar varios niveles a la vez (por ejemplo, compileall -o 1 -o 2).

-e dir

Ignora los enlaces simbólicos que apuntan fuera del directorio dado.

--hardlink-dupes

Si dos archivos .pyc con diferente nivel de optimización tienen el mismo contenido, use enlaces físicos para consolidar los archivos duplicados.

Distinto en la versión 3.2: Se agregaron las opciones -i, -b y -h.

Distinto en la versión 3.5: Se agregaron las opciones -j, -r, and -qq. La opción -q se cambió a un valor multinivel. -b siempre producirá un archivo de código de byte que termina en .pyc, nunca .pyo.

Distinto en la versión 3.7: Se agregó la opción --invalidation-mode.

Distinto en la versión 3.9: Se agregaron las opciones -s, -p, -e y --hardlink-dupes. Se elevó el límite de recursividad predeterminado de 10 a sys.getrecursionlimit(). Se agregó la posibilidad de especificar la opción -o varias veces.

No hay opción de línea de comando para controlar el nivel de optimización que usa la función compile() porque el intérprete de Python en sí mismo ya proporciona la opción: python -O -m compileall.

De manera similar, la función compile() respeta la configuración sys.pycache_prefix. El cache de código de byte generado sólo será útil si compile() se ejecuta con el mismo sys.pycache_prefix (si es que existe alguno) que se utilizará en el momento de ejecución.

Funciones públicas

compileall.compile_dir(dir, maxlevels=sys.getrecursionlimit(), ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, workers=1, invalidation_mode=None, *, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)

Descender recursivamente el árbol de directorio invocado por dir, compilando todos los archivos .py que encuentra en el camino. Devolver un valor verdadero si todos los archivos se compilan exitosamente, y un valor falso en el caso contrario.

El parámetro maxlevels se usar para limitar la profundidad de la recursión; toma como valor predeterminado sys.getrecursionlimit().

Si ddir está dado, se antepone a la ruta de cada archivo que se compila para usar en los rastreos de tiempo de compilación, y también se compilar en el archivo código de byte, donde se usarán en trazas y otros mensajes en casos donde el archivo fuente no existe en el momento cuando el archivo de código de byte se ejecuta.

Si force es verdadero, los módulos se re-compilan aun cuando las marcas de tiempo están actualizadas.

If rx is given, its search method is called on the complete path to each file considered for compilation, and if it returns a true value, the file is skipped. This can be used to exclude files matching a regular expression, given as a re.Pattern object.

Si quiet es False o 0 (el valor predeterminado), los nombres de archivo y otra información se imprimen en salida estándar. Si se configura en 1, solo se imprimen los errores. Si se configura en 2, se suprime toda la salida.

Si legacy es verdadero, los archivos de código de byte se escriben en sus locaciones y nombres de herencia, que pueden sobreescribir los archivos de código de byte creado por otra versión de Python. El comportamiento por defecto es escribir archivos en sus locaciones y nombres PEP 3147 [https://www.python.org/dev/peps/pep-3147], lo cual permite que archivos de código de byte de múltiples versiones de Python coexistan.

optimize especifica el nivel de optimización para el compilador. Se pasa a una función incorporada compile(). Acepta también una secuencia de niveles de optimización que conducen a múltiples compilaciones de un archivo .py en una llamada.

El argumento workers especifica cuántos workers se usan para compilar archivos en paralelo. El comportamiento por defecto es no usar múltiples workers. Si la plataforma no puede usar workers múltiples y el argumento workers está dado, la compilación secuencial se usará como fallback. Si workers es 0, el número de núcleos se usa en el sistema. Si workers es menor que 0, se genera un ValueError.

invalidation_mode debería ser un miembro de la enumeración py_compile.PycInvalidationMode y controla cómo se invalidan los pycs generados en el momento de ejecución.

Los argumentos stripdir, prependdir y limit_sl_dest corresponden a las opciones -s, -p y -e descritas anteriormente. Pueden especificarse como str, bytes o os.PathLike.

Si hardlink_dupes es verdadero y dos archivos .pyc con diferente nivel de optimización tienen el mismo contenido, use enlaces físicos para consolidar los archivos duplicados.

Distinto en la versión 3.2: Se agregó el parámetro legacy y optimize.

Distinto en la versión 3.5: Se agregó el parámetro workers.

Distinto en la versión 3.5: El parámetro quiet se cambió a un valor multinivel.

Distinto en la versión 3.5: El parámetro legacy solo escribe archivos .pyc, no archivos .pyo, no import cuál sea el valor de optimize.

Distinto en la versión 3.6: Acepta un path-like object.

Distinto en la versión 3.7: Se agregó el parámetro invalidation_mode.

Distinto en la versión 3.7.2: El valor predeterminado del parámetro invalidation_mode se actualiza a None.

Distinto en la versión 3.8: Configurar workers a 0 ahora elige el número óptimo de núcleos.

Distinto en la versión 3.9: Se agregaron los argumentos stripdir, prependdir, limit_sl_dest y hardlink_dupes. El valor predeterminado de maxlevels se cambió de 10 a sys.getrecursionlimit()

compileall.compile_file(fullname, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, invalidation_mode=None, *, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)

Compilar el archivo con ruta fullname. Retorna un valor verdadero si el archivo se compila exitosamente, y uno falso en el caso contrario.

Si ddir está dado, se antepone a la ruta del archivo que está siendo compilado para su uso en las trazas de tiempo de compilación, y también se compilar en el archivo de código de bytes, donde será utilizado en trazas y otros mensajes en casos donde el archivo fuente no existe en el momento en que el archivo de código de bytes es ejecutado.

If rx is given, its search method is passed the full path name to the file being compiled, and if it returns a true value, the file is not compiled and True is returned. This can be used to exclude files matching a regular expression, given as a re.Pattern object.

Si quiet es False o 0 (el valor predeterminado), los nombres de archivo y otra información se imprimen en salida estándar. Si se configura en 1, solo se imprimen los errores. Si se configura en 2, se suprime toda la salida.

Si legacy es verdadero, los archivos de código de byte se escriben en sus locaciones y nombres de herencia, que pueden sobreescribir los archivos de código de byte creado por otra versión de Python. El comportamiento por defecto es escribir archivos en sus locaciones y nombres PEP 3147 [https://www.python.org/dev/peps/pep-3147], lo cual permite que archivos de código de byte de múltiples versiones de Python coexistan.

optimize especifica el nivel de optimización para el compilador. Se pasa a una función incorporada compile(). Acepta también una secuencia de niveles de optimización que conducen a múltiples compilaciones de un archivo .py en una llamada.

invalidation_mode debería ser un miembro de la enumeración py_compile.PycInvalidationMode y controla cómo se invalidan los pycs generados en el momento de ejecución.

Los argumentos stripdir, prependdir y limit_sl_dest corresponden a las opciones -s, -p y -e descritas anteriormente. Pueden especificarse como str, bytes o os.PathLike.

Si hardlink_dupes es verdadero y dos archivos .pyc con diferente nivel de optimización tienen el mismo contenido, use enlaces físicos para consolidar los archivos duplicados.

Nuevo en la versión 3.2.

Distinto en la versión 3.5: El parámetro quiet se cambió a un valor multinivel.

Distinto en la versión 3.5: El parámetro legacy solo escribe archivos .pyc, no archivos .pyo, no import cuál sea el valor de optimize.

Distinto en la versión 3.7: Se agregó el parámetro invalidation_mode.

Distinto en la versión 3.7.2: El valor predeterminado del parámetro invalidation_mode se actualiza a None.

Distinto en la versión 3.9: Se agregaron los argumentos stripdir, prependdir, limit_sl_dest y hardlink_dupes.

compileall.compile_path(skip_curdir=True, maxlevels=0, force=False, quiet=0, legacy=False, optimize=-1, invalidation_mode=None)

Compila en bytes todos los archivos .py a lo largo de sys.path. Retorna un valor verdadero si todos los archivos se compilan exitosamente, y uno falso en el caso contrario.

Si skip_curdir es verdadero (el valor predeterminado), el directorio actual no está incluido en la búsqueda. Todos los otros parámetros se pasan a la función compile_dir(). Nótese que, al contrario de las otras funciones de compilación, maxlevels tomar 0 como valor predeterminado.

Distinto en la versión 3.2: Se agregó el parámetro legacy y optimize.

Distinto en la versión 3.5: El parámetro quiet se cambió a un valor multinivel.

Distinto en la versión 3.5: El parámetro legacy solo escribe archivos .pyc, no archivos .pyo, no import cuál sea el valor de optimize.

Distinto en la versión 3.7: Se agregó el parámetro invalidation_mode.

Distinto en la versión 3.7.2: El valor predeterminado del parámetro invalidation_mode se actualiza a None.

Para forzar la re-compilación del los archivos .py en el subdirectorio Lib/ y todos sus subdirectorios:

import compileall

compileall.compile_dir('Lib/', force=True)

# Perform same compilation, excluding files in .svn directories.
import re
compileall.compile_dir('Lib/', rx=re.compile(r'[/\\][.]svn'), force=True)

# pathlib.Path objects can also be used.
import pathlib
compileall.compile_dir(pathlib.Path('Lib/'), force=True)

Ver también

Módulo py_compile

Compilación byte de un solo archivo fuente.

dis — Desensamblador para bytecode de Python

Código fuente: Lib/dis.py [https://github.com/python/cpython/tree/3.9/Lib/dis.py]

El módulo dis admite el análisis de CPython bytecode al desarmarlo. El bytecode de CPython que este módulo toma como entrada se define en el archivo Include/opcode.h y lo utilizan el compilador y el intérprete.

CPython implementation detail: Bytecode es un detalle de implementación del intérprete CPython. No se garantiza que el bytecode no se agregará, eliminará ni cambiará entre las versiones de Python. El uso de este módulo no debe considerarse para trabajar en diferentes máquinas virtuales Python o versiones de Python.

Distinto en la versión 3.6: Use 2 bytes para cada instrucción. Anteriormente, el número de bytes variaba según la instrucción.

Ejemplo: dada la función myfunc():

def myfunc(alist):
    return len(alist)

el siguiente comando se puede utilizar para mostrar el desensamblaje de myfunc():

>>> dis.dis(myfunc)
  2           0 LOAD_GLOBAL              0 (len)
              2 LOAD_FAST                0 (alist)
              4 CALL_FUNCTION            1
              6 RETURN_VALUE

(El «2» es un número de línea).

Análisis de bytecode

Nuevo en la versión 3.4.

La API de análisis de bytecode permite que partes del código Python se envuelvan en un objeto Bytecode que proporciona un fácil acceso a los detalles del código compilado.

class dis.Bytecode(x, *, first_line=None, current_offset=None)

Analiza el bytecode correspondiente a una función, generador, generador asíncrono, corutina, método, cadena de código fuente o un objeto de código (como lo retorna compile()).

Este es un contenedor conveniente para muchas de las funciones enumeradas a continuación, en particular get_instructions(), ya que iterar sobre una instancia de Bytecode produce las operaciones de bytecode como instancias de Instruction.

Si first_line no es None, indica el número de línea que se debe informar para la primera línea de origen en el código desmontado. De lo contrario, la información de la línea de origen (si la hay) se toma directamente del objeto de código desmontado.

Si current_offset no es None, se refiere a un desplazamiento de instrucción en el código desmontado. Establecer esto significa dis() mostrará un marcador de «instrucción actual» contra el código de operación especificado.

classmethod from_traceback(tb)

Construye una instancia de Bytecode a partir del traceback dado, estableciendo current_offset en la instrucción responsable de la excepción.

codeobj

El objeto de código compilado.

first_line

La primera línea de origen del objeto de código (si está disponible)

dis()

Retorna una vista formateada de las operaciones de bytecode (lo mismo que impreso por dis.dis(), pero retornado como una cadena de caracteres multilínea).

info()

Retorna una cadena de caracteres multilínea formateada con información detallada sobre el objeto de código, como code_info().

Distinto en la versión 3.7: Esto ahora puede manejar objetos generadores asíncronos y de corutinas.

Ejemplo:

>>> bytecode = dis.Bytecode(myfunc)
>>> for instr in bytecode:
...     print(instr.opname)
...
LOAD_GLOBAL
LOAD_FAST
CALL_FUNCTION
RETURN_VALUE

Funciones de análisis

El módulo dis también define las siguientes funciones de análisis que convierten la entrada directamente en la salida deseada. Pueden ser útiles si solo se realiza una sola operación, por lo que el objeto de análisis intermedio no es útil:

dis.code_info(x)

Retorna una cadena de caracteres multilínea formateada con información detallada del objeto de código para la función, generador, generador asíncrono, corutina, método, cadena de código fuente u objeto de código suministrados.

Tenga en cuenta que el contenido exacto de las cadenas de información de código depende en gran medida de la implementación y puede cambiar arbitrariamente en las diferentes máquinas virtuales Python o las versiones de Python.

Nuevo en la versión 3.2.

Distinto en la versión 3.7: Esto ahora puede manejar objetos generadores asíncronos y de corutinas.

dis.show_code(x, *, file=None)

Imprime información detallada del objeto de código para la función, método, cadena de código fuente u objeto de código suministrado en file (o sys.stdout si file no está especificado).

Esta es una abreviatura conveniente para print(code_info(x), file=file), destinado a la exploración interactiva en el indicador del intérprete (prompt).

Nuevo en la versión 3.2.

Distinto en la versión 3.4: Agrega un parámetro file.

dis.dis(x=None, *, file=None, depth=None)

Desmontar el objeto x. x puede denotar un módulo, una clase, un método, una función, un generador, un generador asíncrono, una corutina, un objeto de código, una cadena de código fuente o una secuencia de bytes de código de bytes sin procesar. Para un módulo, desmonta todas las funciones. Para una clase, desmonta todos los métodos (incluidos los métodos de clase y estáticos). Para un objeto de código o secuencia de bytecode sin procesar, imprime una línea por instrucción de bytecode. También desmonta recursivamente objetos de código anidados (el código de comprensiones, expresiones generadoras y funciones anidadas, y el código utilizado para construir clases anidadas). Las cadenas de caracteres se compilan primero en objetos de código con la función incorporada compile() antes de desmontarse. Si no se proporciona ningún objeto, esta función desmonta el último rastreo.

El desensamblaje se escribe como texto en el argumento file proporcionado si se proporciona y, de lo contrario, sys.stdout.

La profundidad máxima de recursión está limitada por depth a menos que sea None. depth=0 significa que no hay recursión.

Distinto en la versión 3.4: Agrega un parámetro file.

Distinto en la versión 3.7: Desensamblaje recursivo implementado y parámetro agregado depth.

Distinto en la versión 3.7: Esto ahora puede manejar objetos generadores asíncronos y de corutinas.

dis.distb(tb=None, *, file=None)

Desmonta la función de inicio de pila de un rastreo, utilizando el último rastreo si no se pasó ninguno. Se indica la instrucción que causa la excepción.

El desensamblaje se escribe como texto en el argumento file proporcionado si se proporciona y, de lo contrario, sys.stdout.

Distinto en la versión 3.4: Agrega un parámetro file.

dis.disassemble(code, lasti=-1, *, file=None)

dis.disco(code, lasti=-1, *, file=None)

Desmonta un objeto de código, que indica la última instrucción si se proporcionó lasti. La salida se divide en las siguientes columnas:

el número de línea, para la primera instrucción de cada línea

la instrucción actual, indicada como -->,

una instrucción etiquetada, indicada con >>,

la dirección de la instrucción,

el nombre del código de operación,

parámetros de operación, y

interpretación de los parámetros entre paréntesis.

La interpretación de parámetros reconoce nombres de variables locales y globales, valores constantes, objetivos de ramificación y operadores de comparación.

El desensamblaje se escribe como texto en el argumento file proporcionado si se proporciona y, de lo contrario, sys.stdout.

Distinto en la versión 3.4: Agrega un parámetro file.

dis.get_instructions(x, *, first_line=None)

Retorna un iterador sobre las instrucciones en la función, método, cadena de código fuente u objeto de código suministrado.

El iterador genera una serie de tuplas con nombre Instruction que dan los detalles de cada operación en el código suministrado.

Si first_line no es None, indica el número de línea que se debe informar para la primera línea de origen en el código desmontado. De lo contrario, la información de la línea de origen (si la hay) se toma directamente del objeto de código desmontado.

Nuevo en la versión 3.4.

dis.findlinestarts(code)

Esta función de generador utiliza los atributos co_firstlineno y co_lnotab del objeto de código code para encontrar los desplazamientos que son comienzos de líneas en el código fuente. Se generan como pares (offset, lineno). Ver Objects/lnotab_notes.txt [https://github.com/python/cpython/tree/3.9/Objects/lnotab_notes.txt] para el formato co_lnotab y cómo decodificarlo.

Distinto en la versión 3.6: Los números de línea pueden estar disminuyendo. Antes, siempre estaban aumentando.

dis.findlabels(code)

Detecta todos los desplazamientos en la cadena de caracteres de código de byte compilada code que son objetivos de salto y retorna una lista de estos desplazamientos.

dis.stack_effect(opcode, oparg=None, *, jump=None)

Calcula el efecto de pila de opcode con el argumento oparg.

Si el código tiene un objetivo de salto y jump es True, stack_effect() retornará el efecto de pila del salto. Si jump es False, retornará el efecto de acumulación de no saltar. Y si jump es None (predeterminado), retornará el efecto de acumulación máxima de ambos casos.

Nuevo en la versión 3.4.

Distinto en la versión 3.8: Agrega un parámetro jump.

Instrucciones bytecode de Python

La función get_instructions() y clase Bytecode proporcionan detalles de las instrucciones bytecode como instancias Instruction:

class dis.Instruction

Detalles para una operación de bytecode

opcode

código numérico para la operación, correspondiente a los valores del opcode listados a continuación y los valores de bytecode en Colecciones opcode.

opname

nombre legible por humanos para la operación

arg

argumento numérico para la operación (si existe), de lo contrario None

argval

valor arg resuelto (si se conoce), de lo contrario igual que arg

argrepr

descripción legible por humanos del argumento de operación

offset

índice de inicio de operación dentro de la secuencia de bytecode

starts_line

línea iniciada por este código de operación (si existe), de lo contrario None

is_jump_target

True si otro código salta aquí, de lo contrario, False

Nuevo en la versión 3.4.

El compilador de Python actualmente genera las siguientes instrucciones de bytecode.

Instrucciones generales

NOP

Código que hace nada. Utilizado como marcador de posición por el optimizador de código de bytes.

POP_TOP

Elimina el elemento de la parte superior de la pila (TOS).

ROT_TWO

Intercambia los dos elementos más apilados.

ROT_THREE

Levanta el segundo y tercer elemento de la pila una posición hacia arriba, mueve el elemento superior hacia abajo a la posición tres.

ROT_FOUR

Eleva los elementos de la segunda, tercera y cuarta pila una posición hacia arriba, se mueve de arriba hacia abajo a la posición cuatro.

Nuevo en la versión 3.8.

DUP_TOP

Duplica la referencia en la parte superior de la pila.

Nuevo en la versión 3.2.

DUP_TOP_TWO

Duplica las dos referencias en la parte superior de la pila, dejándolas en el mismo orden.

Nuevo en la versión 3.2.

Operaciones unarias

Las operaciones unarias toman la parte superior de la pila, aplican la operación y retornan el resultado a la pila.

UNARY_POSITIVE

Implementa TOS = +TOS.

UNARY_NEGATIVE

Implementa TOS = -TOS.

UNARY_NOT

Implementa TOS = not TOS.

UNARY_INVERT

Implementa TOS = ~TOS.

GET_ITER

Implementa TOS = iter(TOS).

GET_YIELD_FROM_ITER

Si TOS es un iterador generador o un objeto corutina se deja como está. De lo contrario, implementa TOS = iter(TOS).

Nuevo en la versión 3.5.

Operaciones binarias

Las operaciones binarias eliminan el elemento superior de la pila (TOS) y el segundo elemento de la pila superior (TOS1) de la pila. Realizan la operación y retornan el resultado a la pila.

BINARY_POWER

Implementa TOS = TOS1 ** TOS.

BINARY_MULTIPLY

Implementa TOS = TOS1 * TOS.

BINARY_MATRIX_MULTIPLY

Implementa TOS = TOS1 @ TOS.

Nuevo en la versión 3.5.

BINARY_FLOOR_DIVIDE

Implementa TOS = TOS1 // TOS.

BINARY_TRUE_DIVIDE

Implementa TOS = TOS1 / TOS.

BINARY_MODULO

Implementa TOS = TOS1 % TOS.

BINARY_ADD

Implementa TOS = TOS1 + TOS.

BINARY_SUBTRACT

Implementa TOS = TOS1 - TOS.

BINARY_SUBSCR

Implementa TOS = TOS1[TOS].

BINARY_LSHIFT

Implementa TOS = TOS1 << TOS.

BINARY_RSHIFT

Implementa TOS = TOS1 >> TOS.

BINARY_AND

Implementa TOS = TOS1 & TOS.

BINARY_XOR

Implementa TOS = TOS1 ^ TOS.

BINARY_OR

Implementa TOS = TOS1 | TOS.

Operaciones en su lugar

Las operaciones en el lugar son como operaciones binarias, ya que eliminan TOS y TOS1, y retornan el resultado a la pila, pero la operación se realiza en el lugar cuando TOS1 lo admite, y el TOS resultante puede ser (pero no tiene ser) el TOS1 original.

INPLACE_POWER

Implementa en su lugar TOS = TOS1 ** TOS.

INPLACE_MULTIPLY

Implementa en su lugar TOS = TOS1 * TOS.

INPLACE_MATRIX_MULTIPLY

Implementa en su lugar TOS = TOS1 @ TOS.

Nuevo en la versión 3.5.

INPLACE_FLOOR_DIVIDE

Implementa en su lugar TOS = TOS1 // TOS.

INPLACE_TRUE_DIVIDE

Implementa en su lugar TOS = TOS1 / TOS.

INPLACE_MODULO

Implementa en su lugar TOS = TOS1 % TOS.

INPLACE_ADD

Implementa en su lugar TOS = TOS1 + TOS.

INPLACE_SUBTRACT

Implementa en su lugar TOS = TOS1 - TOS.

INPLACE_LSHIFT

Implementa en su lugar TOS = TOS1 << TOS.

INPLACE_RSHIFT

Implementa en su lugar TOS = TOS1 >> TOS.

INPLACE_AND

Implementa en su lugar TOS = TOS1 & TOS.

INPLACE_XOR

Implementa en su lugar TOS = TOS1 ^ TOS.

INPLACE_OR

Implementa en su lugar TOS = TOS1 | TOS.

STORE_SUBSCR

Implementa TOS1[TOS] = TOS2.

DELETE_SUBSCR

Implementa del TOS1[TOS].

Opcodes de corutinas

GET_AWAITABLE

Implementa TOS = get_awaitable(TOS), donde get_awaitable(o) retorna o si o es un objeto de corutina o un objeto generador con el indicador CO_ITERABLE_COROUTINE, o resuelve o.__await__.

Nuevo en la versión 3.5.

GET_AITER

Implementa TOS = TOS.__aiter__().

Nuevo en la versión 3.5.

Distinto en la versión 3.7: Ya no se admite el retorno de objetos awaitable de __aiter__.

GET_ANEXT

Implementa PUSH(get_awaitable(TOS.__anext__())). Consulte GET_AWAITABLE para obtener detalles sobre get_awaitable

Nuevo en la versión 3.5.

END_ASYNC_FOR

Termina un bucle async for. Maneja una excepción planteada cuando se espera un próximo elemento. Si TOS es StopAsyncIteration desapila 7 valores de la pila y restaura el estado de excepción utilizando los tres últimos. De lo contrario, vuelva a lanzar la excepción utilizando los tres valores de la pila. Se elimina un bloque de controlador de excepción de la pila de bloques.

Nuevo en la versión 3.8.

BEFORE_ASYNC_WITH

Resuelve __aenter__ y __aexit__ del objeto en la parte superior de la pila. Apila __aexit__ y el resultado de __aenter__() a la pila.

Nuevo en la versión 3.5.

SETUP_ASYNC_WITH

Crea un nuevo objeto marco.

Nuevo en la versión 3.5.

Opcodes misceláneos

PRINT_EXPR

Implementa la declaración de expresión para el modo interactivo. TOS se elimina de la pila y se imprime. En modo no interactivo, una declaración de expresión termina con POP_TOP.

SET_ADD(i)

Llama a set.add(TOS1[-i], TOS). Se utiliza para implementar comprensiones de conjuntos.

LIST_APPEND(i)

Llama a list.append(TOS1[-i], TOS). Se utiliza para implementar listas por comprensión.

MAP_ADD(i)

Llama a dict.__setitem__(TOS1[-i], TOS1, TOS). Se utiliza para implementar comprensiones de diccionarios.

Nuevo en la versión 3.1.

Distinto en la versión 3.8: El valor del mapa es TOS y la clave del mapa es TOS1. Antes, esos fueron revertidos.

Para todas las instrucciones SET_ADD, LIST_APPEND y MAP_ADD, mientras el valor agregado o el par clave/valor aparece, el objeto contenedor permanece en la pila para que quede disponible para futuras iteraciones del bucle.

RETURN_VALUE

Retorna con TOS a quien llama la función.

YIELD_VALUE

Desapila TOS y lo genera (yield) de un generator.

YIELD_FROM

Desapila TOS y delega en él como un subiterador de un generator.

Nuevo en la versión 3.3.

SETUP_ANNOTATIONS

Comprueba si __anotaciones__ está definido en locals(), si no está configurado como un dict vacío. Este código de operación solo se emite si el cuerpo de una clase o módulo contiene anotaciones de variables estáticamente.

Nuevo en la versión 3.6.

IMPORT_STAR

Carga todos los símbolos que no comienzan con '_' directamente desde el TOS del módulo al espacio de nombres local. El módulo se desapila después de cargar todos los nombres. Este opcode implementa from module import *.

POP_BLOCK

Elimina un bloque de la pila de bloques. Por cuadro, hay una pila de bloques, que denota declaraciones try, y tal.

POP_EXCEPT

Elimina un bloque de la pila de bloques. El bloque desapilado debe ser un bloque de controlador de excepción, como se crea implícitamente al ingresar un controlador de excepción. Además de desapilar valores extraños de la pila de cuadros, los últimos tres valores desapilados se utilizan para restaurar el estado de excepción.

RERAISE

Vuelve a lanzar la excepción actualmente en la parte superior de la pila.

Nuevo en la versión 3.9.

WITH_EXCEPT_START

Llama a la función en la posición 7 de la pila con los tres elementos superiores de la pila como argumentos. Se usa para implementar la llamada context_manager.__ exit __(*exc_info()) cuando se ha producido una excepción en una sentencia with.

Nuevo en la versión 3.9.

LOAD_ASSERTION_ERROR

Inserta AssertionError en la pila. Utilizado por la declaración assert.

Nuevo en la versión 3.9.

LOAD_BUILD_CLASS

Apila builtins.__build_class__() en la pila. Más tarde se llama por CALL_FUNCTION para construir una clase.

SETUP_WITH(delta)

This opcode performs several operations before a with block starts. First, it loads __exit__() from the context manager and pushes it onto the stack for later use by WITH_EXCEPT_START. Then, __enter__() is called, and a finally block pointing to delta is pushed. Finally, the result of calling the __enter__() method is pushed onto the stack. The next opcode will either ignore it (POP_TOP), or store it in (a) variable(s) (STORE_FAST, STORE_NAME, or UNPACK_SEQUENCE).

Nuevo en la versión 3.2.

Todos los siguientes códigos de operación utilizan sus argumentos.

STORE_NAME(namei)

Implementa name = TOS. namei es el índice de name en el atributo co_names del objeto de código. El compilador intenta usar STORE_FAST o STORE_GLOBAL si es posible.

DELETE_NAME(namei)

Implementa del name, donde namei es el índice en atributo co_names del objeto de código.

UNPACK_SEQUENCE(count)

Descomprime TOS en count valores individuales, que se colocan en la pila de derecha a izquierda.

UNPACK_EX(counts)

Implementa la asignación con un objetivo destacado: desempaqueta un iterable en TOS en valores individuales, donde el número total de valores puede ser menor que el número de elementos en el iterable: uno de los nuevos valores será una lista de todos los elementos sobrantes.

El byte bajo de count es el número de valores antes del valor de la lista, el byte alto de count es el número de valores después de él. Los valores resultantes se colocan en la pila de derecha a izquierda.

STORE_ATTR(namei)

Implementa TOS.name = TOS1, donde namei es el índice del nombre en co_names.

DELETE_ATTR(namei)

Implementa del TOS.name, usando namei como índice en co_names.

STORE_GLOBAL(namei)

Funciona como STORE_NAME, pero almacena el nombre como global.

DELETE_GLOBAL(namei)

Funciona como DELETE_NAME, pero elimina un nombre global.

LOAD_CONST(consti)

Apila co_consts[consti] en la pila.

LOAD_NAME(namei)

Apila el valor asociado con co_names [namei] en la pila.

BUILD_TUPLE(count)

Crea una tupla que consume elementos count de la pila, y apila la tupla resultante a la pila.

BUILD_LIST(count)

Funciona como BUILD_TUPLE, pero crea una lista.

BUILD_SET(count)

Funciona como BUILD_TUPLE, pero crea un conjunto.

BUILD_MAP(count)

Apila un nuevo objeto de diccionario en la pila. Desapila 2 * count elementos para que el diccionario contenga count entradas: {..., TOS3: TOS2, TOS1: TOS}.

Distinto en la versión 3.5: El diccionario se crea a partir de elementos de la pila en lugar de crear un diccionario vacío dimensionado previamente para contener count elementos.

BUILD_CONST_KEY_MAP(count)

La versión de BUILD_MAP especializada para claves constantes. Desapila el elemento superior en la pila que contiene una tupla de claves, luego, a partir de TOS1, muestra los valores count para formar valores en el diccionario incorporado.

Nuevo en la versión 3.6.

BUILD_STRING(count)

Concatena count cadenas de caracteres de la pila y empuja la cadena de caracteres resultante en la pila.

Nuevo en la versión 3.6.

LIST_TO_TUPLE

Saca una lista de la pila y empuja una tupla que contiene los mismos valores.

Nuevo en la versión 3.9.

LIST_EXTEND(i)

Llama a list.extend(TOS1[-i], TOS). Se utiliza para crear listas.

Nuevo en la versión 3.9.

SET_UPDATE(i)

Llama a set.update(TOS1[-i], TOS). Se usa para construir decorados.

Nuevo en la versión 3.9.

DICT_UPDATE(i)

Llama a dict.update(TOS1[-i], TOS). Se usa para construir dictados.

Nuevo en la versión 3.9.

DICT_MERGE

Como DICT_UPDATE pero lanza una excepción para claves duplicadas.

Nuevo en la versión 3.9.

LOAD_ATTR(namei)

Reemplaza TOS con getattr(TOS, co_names[namei]).

COMPARE_OP(opname)

Realiza una operación booleana. El nombre de la operación se puede encontrar en cmp_op[opname].

IS_OP(invert)

Realiza una comparación is o is not si invert es 1.

Nuevo en la versión 3.9.

CONTAINS_OP(invert)

Realiza una comparación in o not in si invert es 1.

Nuevo en la versión 3.9.

IMPORT_NAME(namei)

Importa el módulo co_names[namei]. TOS y TOS1 aparecen y proporcionan los argumentos fromlist y level de __import__(). El objeto del módulo se empuja a la pila. El espacio de nombres actual no se ve afectado: para una instrucción de importación adecuada, una instrucción posterior STORE_FAST modifica el espacio de nombres.

IMPORT_FROM(namei)

Carga el atributo co_names[namei] del módulo que se encuentra en TOS. El objeto resultante se apila en la pila, para luego ser almacenado por la instrucción STORE_FAST.

JUMP_FORWARD(delta)

Incrementa el contador de bytecode en delta.

POP_JUMP_IF_TRUE(target)

Si TOS es true, establece el contador de bytecode en target. TOS es desapilado (popped).

Nuevo en la versión 3.1.

POP_JUMP_IF_FALSE(target)

Si TOS es falso, establece el contador de bytecode en target. TOS es desapilado (popped).

Nuevo en la versión 3.1.

JUMP_IF_NOT_EXC_MATCH(target)

Comprueba si el segundo valor de la pila es una excepción que coincide con el TOS y salta si no lo es. Saca dos valores de la pila.

Nuevo en la versión 3.9.

JUMP_IF_TRUE_OR_POP(target)

Si TOS es verdadero, establece el contador de bytecode en target y deja TOS en la pila. De lo contrario (TOS es falso), TOS se desapila.

Nuevo en la versión 3.1.

JUMP_IF_FALSE_OR_POP(target)

Si TOS es falso, establece el contador de bytecode en target y deja TOS en la pila. De lo contrario (TOS es verdadero), TOS se desapila.

Nuevo en la versión 3.1.

JUMP_ABSOLUTE(target)

Establezca el contador de bytecode en target.

FOR_ITER(delta)

TOS es un iterador. Llama a su método __next__(). Si esto produce un nuevo valor, lo apila en la pila (dejando el iterador debajo de él). Si el iterador indica que está agotado, se abre TOS y el contador de código de bytes se incrementa en delta.

LOAD_GLOBAL(namei)

Carga el nombre global co_names[namei] en la pila.

SETUP_FINALLY(delta)

Apila un bloque try de una cláusula try-finally o try-except en la pila de bloques. delta apunta al último bloque o al primero excepto el bloque.

LOAD_FAST(var_num)

Apila una referencia al local co_varnames[var_num] sobre la pila.

STORE_FAST(var_num)

Almacena TOS en el local co_varnames[var_num].

DELETE_FAST(var_num)

Elimina la co_varnames[var_num] local.

LOAD_CLOSURE(i)

Apila una referencia a la celda contenida en la ranura i de la celda y el almacenamiento variable libre. El nombre de la variable es co_cellvars[i] si i es menor que la longitud de co_cellvars. De lo contrario, es co_freevars[i - len(co_cellvars)].

LOAD_DEREF(i)

Carga la celda contenida en la ranura i de la celda y el almacenamiento variable libre. Apila una referencia al objeto que contiene la celda en la pila.

LOAD_CLASSDEREF(i)

Al igual que LOAD_DEREF pero primero verifica el diccionario local antes de consultar la celda. Esto se usa para cargar variables libres en los cuerpos de clase.

Nuevo en la versión 3.4.

STORE_DEREF(i)

Almacena TOS en la celda contenida en la ranura i de la celda y almacenamiento variable libre.

DELETE_DEREF(i)

Vacía la celda contenida en la ranura i de la celda y el almacenamiento variable libre. Utilizado por la declaración del.

Nuevo en la versión 3.2.

RAISE_VARARGS(argc)

Provoca una excepción utilizando una de las 3 formas de la declaración raise, dependiendo del valor de argc:

0: raise (vuelve a lanzar la excepción anterior)

1: raise TOS (lanza instancia de excepción o un tipo en TOS)

2: raise TOS1 desde TOS (lanza una instancia de excepción o tipo en TOS1 con __cause__ establecida en `` TOS``)

CALL_FUNCTION(argc)

Llama a un objeto invocable con argumentos posicionales. argc indica el número de argumentos posicionales. La parte superior de la pila contiene argumentos posicionales, con el argumento más a la derecha en la parte superior. Debajo de los argumentos hay un objeto invocable para llamar. CALL_FUNCTION saca todos los argumentos y el objeto invocable de la pila, llama al objeto invocable con esos argumentos y empuja el valor de retorno retornado por el objeto invocable.

Distinto en la versión 3.6: Este código de operación se usa solo para llamadas con argumentos posicionales.

CALL_FUNCTION_KW(argc)

Llama a un objeto invocable con argumentos posicionales (si los hay) y palabras clave. argc indica el número total de argumentos posicionales y de palabras clave. El elemento superior de la pila contiene una tupla con los nombres de los argumentos de la palabra clave, que deben ser cadenas de caracteres. Debajo están los valores para los argumentos de la palabra clave, en el orden correspondiente a la tupla. Debajo están los argumentos posicionales, con el parámetro más a la derecha en la parte superior. Debajo de los argumentos hay un objeto invocable para llamar. CALL_FUNCTION_KW saca todos los argumentos y el objeto invocable de la pila, llama al objeto invocable con esos argumentos y empuja el valor de retorno retornado por el objeto invocable.

Distinto en la versión 3.6: Los argumentos de palabras clave se empaquetan en una tupla en lugar de un diccionario, argc indica el número total de argumentos.

CALL_FUNCTION_EX(flags)

Llama a un objeto invocable con un conjunto variable de argumentos posicionales y de palabras clave. Si se establece el bit más bajo de flags, la parte superior de la pila contiene un objeto de mapeo que contiene argumentos de palabras clave adicionales. Antes de que se llame al invocable, el objeto de mapeo y el objeto iterable se «desempaquetan» y su contenido se pasa como palabra clave y argumentos posicionales, respectivamente. CALL_FUNCTION_EX saca todos los argumentos y el objeto invocable de la pila, llama al objeto invocable con esos argumentos y empuja el valor de retorno devuelto por el objeto invocable.

Nuevo en la versión 3.6.

LOAD_METHOD(namei)

Carga un método llamado co_names[namei] desde el objeto TOS. TOS aparece. Este bytecode distingue dos casos: si TOS tiene un método con el nombre correcto, el bytecode apila el método no vinculado y TOS. TOS se usará como primer argumento (self) por CALL_METHOD cuando se llama al método independiente. De lo contrario, NULL y el objeto retornado por la búsqueda de atributos son apilados.

Nuevo en la versión 3.7.

CALL_METHOD(argc)

Llama a un método. argc es el número de argumentos posicionales. Los argumentos de palabras clave no son compatibles. Este código de operación está diseñado para usarse con LOAD_METHOD. Los argumentos posicionales están en la parte superior de la pila. Debajo de ellos, los dos elementos descritos en LOAD_METHOD están en la pila (self y un objeto de método independiente o NULL y un invocable arbitrario). Todos ellos aparecen y se apila el valor de retorno.

Nuevo en la versión 3.7.

MAKE_FUNCTION(flags)

Apila un nuevo objeto de función en la pila. De abajo hacia arriba, la pila consumida debe constar de valores si el argumento lleva un valor de marca especificado

0x01, una tupla de valores predeterminados para solo parámetros posicionales y posicionales o de palabras clave en orden posicional

0x02 un diccionario de valores predeterminados de solo palabras clave

0x04 un diccionario de anotaciones

0x08 una tupla que contiene celdas para variables libres, haciendo un cierre (closure)

el código asociado con la función (en TOS1)

el nombre calificado de la función (en TOS)

BUILD_SLICE(argc)

Apila un objeto de rebanada en la pila. argc debe ser 2 o 3. Si es 2, se apila slice(TOS1, TOS); si es 3, se apila slice(TOS2, TOS1, TOS). Consulte la función incorporada slice() para obtener más información.

EXTENDED_ARG(ext)

Prefija cualquier código de operación que tenga un argumento demasiado grande para caber en el byte predeterminado. ext contiene un byte adicional que actúa como bits más altos en el argumento. Para cada opcode, como máximo se permiten tres prefijos EXTENDED_ARG, formando un argumento de dos bytes a cuatro bytes.

FORMAT_VALUE(flags)

Se utiliza para implementar cadenas literales formateadas (cadenas de caracteres f). Desapila un fmt_spec opcional de la pila, luego un value requerido. flags se interpreta de la siguiente manera:

(flags & 0x03) == 0x00: value es formateado como está.

(flags & 0x03) == 0x01: llama str() sobre value antes de formatearlo.

(flags & 0x03) == 0x02: llama repr() sobre value antes de formatearlo.

(flags & 0x03) == 0x03: llama ascii() sobre value antes de formatearlo.

(flags & 0x04) == 0x04: desapila fmt_spec de la pila y lo usa, de lo contrario usa un fmt_spec vacío.

El formateo se realiza usando PyObject_Format(). El resultado se apila en la pila.

Nuevo en la versión 3.6.

HAVE_ARGUMENT

Esto no es realmente un opcode. Identifica la línea divisoria entre los opcode que no usan su argumento y los que lo hacen (< HAVE_ARGUMENT y >= HAVE_ARGUMENT, respectivamente).

Distinto en la versión 3.6: Ahora cada instrucción tiene un argumento, pero los códigos de operación <HAVE_ARGUMENT la ignoran. Antes, solo los códigos de operación > = HAVE_ARGUMENT tenían un argumento.

Colecciones opcode

Estas colecciones se proporcionan para la introspección automática de instrucciones de bytecode:

dis.opname

Secuencia de nombres de operaciones, indexable utilizando el bytecode.

dis.opmap

Nombres de operaciones de mapeo de diccionario a bytecodes.

dis.cmp_op

Secuencia de todos los nombres de operaciones de comparación.

dis.hasconst

Secuencia de bytecodes que acceden a una constante.

dis.hasfree

Secuencia de bytecodes que acceden a una variable libre (tenga en cuenta que “libre” en este contexto se refiere a nombres en el alcance actual a los que hacen referencia los ámbitos internos o los nombres en los ámbitos externos a los que se hace referencia desde este ámbito. No incluye referencias a ámbitos globales o integrados).

dis.hasname

Secuencia de bytecodes que acceden a un atributo por nombre.

dis.hasjrel

Secuencia de bytecodes que tienen un objetivo de salto relativo.

dis.hasjabs

Secuencia de bytecodes que tienen un objetivo de salto absoluto.

dis.haslocal

Secuencia de códigos de bytes que acceden a una variable local.

dis.hascompare

Secuencia de bytecodes de operaciones booleanas.

pickletools — Herramientas para desarrolladores pickle

Código fuente: Lib/pickletools.py [https://github.com/python/cpython/tree/3.9/Lib/pickletools.py]

Este módulo contiene varias constantes relacionadas con los detalles íntimos del módulo pickle, algunos comentarios largos sobre la implementación y algunas funciones útiles para analizar pickled data. El contenido de este módulo es útil para los desarrolladores principales de Python que están trabajando en el pickle; los usuarios ordinarios del módulo pickle probablemente no encontrarán relevante el módulo pickletools.

Uso de la línea de comandos

Nuevo en la versión 3.2.

Cuando se invoca desde la línea de comandos, python -m pickletools desensamblará el contenido de uno o más archivos pickle. Tenga en cuenta que si desea ver el objeto Python almacenado en el pickle en lugar de los detalles del formato de pickle, es posible que desee utilizar -m pickle en su lugar. Sin embargo, cuando el archivo de pickle que desea examinar proviene de una fuente que no es de confianza, -m pickletools es una opción más segura porque no ejecuta el código de bytes de pickle.

Por ejemplo, con una tupla (1, 2) pickled en el archivo x.pickle:

$ python -m pickle x.pickle
(1, 2)

$ python -m pickletools x.pickle
    0: \x80 PROTO      3
    2: K    BININT1    1
    4: K    BININT1    2
    6: \x86 TUPLE2
    7: q    BINPUT     0
    9: .    STOP
highest protocol among opcodes = 2

Opciones de línea de comandos

-a, --annotate

Anote cada línea con una breve descripción del código de operación.

-o, --output=<file>

Nombre de un archivo donde se debe escribir la salida.

-l, --indentlevel=<num>

Número de espacios en blanco por los que se aplica una sangría a un nuevo nivel de MARK.

-m, --memo

Cuando se desensamblan varios objetos, conserve la nota entre los ensamblajes.

-p, --preamble=<preamble>

Cuando se especifica más de un archivo pickle, imprima un preámbulo determinado antes de cada desensamblado.

Interfaz programática

pickletools.dis(pickle, out=None, memo=None, indentlevel=4, annotate=0)

Produce un desensamblado simbólico del pickle en el objeto similar a un archivo salida, de forma predeterminada en sys.stdout. pickle puede ser una cadena o un objeto similar a un archivo. memo puede ser un diccionario Python que se utilizará como nota del pickle; se puede utilizar para realizar ensamblajes de desuso en varios pickles creados por el mismo selector. Los niveles sucesivos, indicados por los códigos de operación MARK en la secuencia, son indentados por espacios indentlevel. Si se da un valor distinto de cero a anotar, cada código de operación de la salida se anota con una breve descripción. El valor de anotar se utiliza como sugerencia para la columna donde debe comenzar la anotación.

Nuevo en la versión 3.2: El argumento anotar.

pickletools.genops(pickle)

Proporciona un iterator sobre todos los códigos de operación en un pickle, retornando una secuencia de triples (opcode, arg, pos). opcode es una instancia de una clase OpcodeInfo; arg es el valor descodificado, como un objeto Python, del argumento del código de operación; pos es la posición en la que se encuentra este código de operación. pickle puede ser una cadena o un objeto similar a un archivo.

pickletools.optimize(picklestring)

Retorna una nueva cadena pickle equivalente después de eliminar los códigos de operación PUT no utilizados. El pickle optimizado es más corto, toma menos tiempo de transmisión, requiere menos espacio de almacenamiento y se restaura de manera más eficiente.

Servicios varios

Los módulos descritos en este capítulo proporcionan varios servicios que están disponibles en todas las versiones de Python. Esta es una descripción general:

formatter — Formateo de salida genérica

La interfaz Formateador

Implementaciones del formateador

La interfaz Escritor

Implementaciones del escritor

formatter — Formateo de salida genérica

Obsoleto desde la versión 3.4: Debido a la falta de uso, el módulo formateador ha quedado obsoleto.

Este módulo admite dos definiciones de interfaz, cada una con múltiples implementaciones: la interfaz formateador y la interfaz escritor que es requerida por la interfaz formateadora.

Los objetos formateadores transforman un flujo abstracto de eventos de formato en eventos de salida específicos en los objetos del escritor. Los formateadores gestionan varias estructuras de pila para permitir cambiar y restaurar varias propiedades de un objeto escritor; los escritores no necesitan poder manejar cambios relativos ni ningún tipo de operación de «retroceso». Las propiedades específicas del escritor que se pueden controlar a través de los objetos del formateador son la alineación horizontal, la fuente y las sangrías del margen izquierdo. Se proporciona un mecanismo que también permite proporcionar configuraciones de estilo arbitrarias y no exclusivas a un escritor. Las interfaces adicionales facilitan el formateo de eventos que no son reversibles, como la separación de párrafos.

Los objetos escritores encapsulan las interfaces de los dispositivos. Se admiten dispositivos abstractos, como formatos de archivo, así como dispositivos físicos. Todas las implementaciones proporcionadas funcionan con dispositivos abstractos. La interfaz pone a disposición mecanismos para establecer las propiedades que administran los objetos del formateador e insertar datos en la salida.

La interfaz Formateador

Las interfaces para crear formateadores dependen de la clase de formateador específica que se instancia. Las interfaces que se describen a continuación son las interfaces necesarias que todos los formateadores deben admitir una vez inicializados.

Un elemento de datos se define a nivel de módulo:

formatter.AS_IS

Valor que se puede usar en la especificación de fuente pasada al método push_font () descrito a continuación, o como el nuevo valor a cualquier otro método push_property(). Al presionar el valor AS_IS, se puede llamar al método correspondiente pop_property() sin tener que rastrear si se cambió la propiedad.

Los siguientes atributos están definidos para los objetos de instancia del formateador:

formatter.writer

La instancia de escritor con la que interactúa el formateador.

formatter.end_paragraph(blanklines)

Cierra todos los párrafos abiertos e inserta al menos blanklines antes del siguiente párrafo.

formatter.add_line_break()

Agrega un salto de línea duro si aún no existe uno. Esto no rompe el párrafo lógico.

formatter.add_hor_rule(*args, **kw)

Inserta una regla horizontal en la salida. Se inserta una ruptura dura si hay datos en el párrafo actual, pero el párrafo lógico no está roto. Los argumentos y palabras clave se pasan al método del escritor send_line_break().

formatter.add_flowing_data(data)

Proporciona datos que deben formatearse con espacios en blanco contraídos. Los espacios en blanco de llamadas anteriores y sucesivas a add_flowing_data() también se consideran cuando se realiza el colapso de espacios en blanco. Se espera que los datos que se pasan a este método estén envueltos en palabras por el dispositivo de salida. Tenga en cuenta que el objeto escritor debe realizar cualquier ajuste de texto debido a la necesidad de depender de la información del dispositivo y la fuente.

formatter.add_literal_data(data)

Proporciona datos que deben pasarse al escritor sin cambios. Los espacios en blanco, incluidos los caracteres de nueva línea y tabulación, se consideran legales en el valor de data.

formatter.add_label_data(format, counter)

Inserta una etiqueta que debe colocarse a la izquierda del margen izquierdo actual. Esto debe usarse para construir listas numeradas o con viñetas. Si el valor de format es una cadena, se interpreta como una especificación de formato para counter, que debe ser un número entero. El resultado de este formato se convierte en el valor de la etiqueta; si format no es una cadena, se utiliza directamente como valor de etiqueta. El valor de la etiqueta se pasa como el único argumento del método del escritor send_label_data(). La interpretación de valores de etiquetas que no son cadenas depende del escritor asociado.

Las especificaciones de formato son cadenas que, en combinación con un valor de contador, se utilizan para calcular valores de etiqueta. Cada carácter de la cadena de formato se copia al valor de la etiqueta, y algunos caracteres se reconocen para indicar una transformación en el valor del contador. Específicamente, el carácter '1' representa el formateador del valor del contador como un número arábigo, los caracteres 'A' y 'a' representan representaciones alfabéticas del valor del contador en mayúsculas y minúsculas , respectivamente, y 'I' y 'i' representan el valor del contador en números romanos, en mayúsculas y minúsculas. Tenga en cuenta que las transformaciones alfabética y romana requieren que el valor del contador sea mayor que cero.

formatter.flush_softspace()

Envía cualquier espacio en blanco pendiente almacenado en búfer de una llamada anterior a add_flowing_data() al objeto escritor asociado. Esto debe llamarse antes de cualquier manipulación directa del objeto de escritura.

formatter.push_alignment(align)

Empuja una nueva configuración de alineación en la pila de alineación. Puede ser AS_IS si no se desea ningún cambio. Si el valor de alineación se cambia con respecto a la configuración anterior, se llama al método del escritor new_alignment() con el valor align.

formatter.pop_alignment()

Restaura la alineación anterior.

formatter.push_font((size, italic, bold, teletype))

Cambia algunas o todas las propiedades de fuente del objeto de escritura. Las propiedades que no se establecen en AS_IS se establecen en los valores pasados, mientras que otras se mantienen en su configuración actual. Se llama al método del escritor new_font() con la especificación de fuente completamente resuelta.

formatter.pop_font()

Restaura la fuente anterior.

formatter.push_margin(margin)

Aumenta el número de sangrías del margen izquierdo en uno, asociando la etiqueta lógica margin con la nueva sangría. El nivel de margen inicial es 0. Los valores modificados de la etiqueta lógica deben ser valores verdaderos; los valores falsos distintos de AS_IS no son suficientes para cambiar el margen.

formatter.pop_margin()

Restaura el margen anterior.

formatter.push_style(*styles)

Empuja cualquier número de especificaciones de estilo arbitrarias. Todos los estilos se insertan en la pila de estilos en orden. Una tupla que representa la pila completa, incluidos los valores AS_IS, se pasa al método new_styles() del escritor.

formatter.pop_style(n=1)

Muestra las últimas n especificaciones de estilo pasadas a push_style(). Una tupla que representa la pila revisada, que incluye los valores AS_IS, se pasa al método new_styles() del escritor.

formatter.set_spacing(spacing)

Establece el estilo de espaciado para el escritor.

formatter.assert_line_data(flag=1)

Informa al formateador que se han agregado datos al párrafo actual fuera de banda. Esto debe usarse cuando el escritor haya sido manipulado directamente. El argumento flag opcional se puede establecer en falso si las manipulaciones del escritor produjeron un salto de línea duro al final de la salida.

Implementaciones del formateador

Este módulo proporciona dos implementaciones de objetos formateadores. La mayoría de las aplicaciones pueden utilizar una de estas clases sin modificación ni subclases.

class formatter.NullFormatter(writer=None)

Un formateador que no hace nada. Si se omite writer, se crea una instancia NullWriter. Ningún método del escritor es llamado por instancias NullFormatter. Las implementaciones deben heredar de esta clase si implementan una interfaz de escritor, pero no necesitan heredar ninguna implementación.

class formatter.AbstractFormatter(writer)

El formateador estándar. Esta implementación ha demostrado una amplia aplicabilidad para muchos escritores y puede usarse directamente en la mayoría de las circunstancias. Se ha utilizado para implementar un navegador World Wide Web con todas las funciones.

La interfaz Escritor

Las interfaces para crear escritores dependen de la clase de escritor específica que se instancia. Las interfaces que se describen a continuación son las interfaces necesarias que todos los escritores deben admitir una vez inicializadas. Tenga en cuenta que, si bien la mayoría de las aplicaciones pueden usar la clase AbstractFormatter como formateador, el escritor generalmente debe ser proporcionado por la aplicación.

writer.flush()

Vacía cualquier salida almacenada o eventos de control de dispositivos.

writer.new_alignment(align)

Define el estilo de alineación. El valor align puede ser cualquier objeto, pero por convención es una cadena o None, donde None indica que se debe usar la alineación «preferida» del escritor. Los valores de align convencionales son “left”`, 'center', 'right', y 'justify'.

writer.new_font(font)

Establece el estilo de fuente. El valor de font será None, lo que indica que se debe usar la fuente predeterminada del dispositivo, o una tupla de la forma (tamaño, cursiva, negrita, teletipo). El tamaño será una cadena que indica el tamaño de fuente que se debe utilizar; cadenas específicas y su interpretación deben ser definidas por la aplicación. Los valores cursiva, negrita y teletipo son valores booleanos que especifican cuál de esos atributos de fuente debe usarse.

writer.new_margin(margin, level)

Establece el nivel de margen en el entero level y la etiqueta lógica en margin. La interpretación de la etiqueta lógica queda a discreción del escritor; la única restricción sobre el valor de la etiqueta lógica es que no sea un valor falso para valores distintos de cero de level.

writer.new_spacing(spacing)

Establece el estilo de espaciado en spacing.

writer.new_styles(styles)

Establece estilos adicionales. El valor de styles es una tupla de valores arbitrarios; el valor AS_IS debe ignorarse. La tupla styles se puede interpretar como un conjunto o como una pila dependiendo de los requisitos de la aplicación y la implementación del escritor.

writer.send_line_break()

Rompe la línea actual.

writer.send_paragraph(blankline)

Produce una separación de párrafos de al menos blankline líneas en blanco, o su equivalente. El valor de blankline será un número entero. Tenga en cuenta que la implementación recibirá una llamada a send_line_break() antes de esta llamada si se necesita un salto de línea; este método no debe incluir terminar la última línea del párrafo. Solo es responsable del espacio vertical entre párrafos.

writer.send_hor_rule(*args, **kw)

Muestra una regla horizontal en el dispositivo de salida. Los argumentos de este método son completamente específicos de la aplicación y del escritor, y deben interpretarse con cuidado. La implementación del método puede asumir que ya se ha emitido un salto de línea a través de send_line_break().

writer.send_flowing_data(data)

Datos de caracteres de salida que se pueden ajustar en palabras y volver a fluir según sea necesario. Dentro de cualquier secuencia de llamadas a este método, el escritor puede asumir que se han contraído tramos de múltiples caracteres de espacio en blanco a caracteres de un solo espacio.

writer.send_literal_data(data)

Salida de datos de caracteres que ya se formatearon para su visualización. En general, esto debe interpretarse en el sentido de que los saltos de línea indicados por caracteres de nueva línea deben conservarse y no deben introducirse nuevos saltos de línea. Los datos pueden contener caracteres de tabulación y nueva línea incrustados, a diferencia de los datos proporcionados en la interfaz send_formatted_data().

writer.send_label_data(data)

Establece data a la izquierda del margen izquierdo actual, si es posible. El valor de data no está restringido; el tratamiento de los valores que no son cadenas depende completamente de la aplicación y del escritor. Este método solo se llamará al comienzo de una línea.

Implementaciones del escritor

Este módulo proporciona tres implementaciones de la interfaz de objetos del escritor como ejemplos. La mayoría de las aplicaciones necesitarán derivar nuevas clases de escritor de la clase NullWriter.

class formatter.NullWriter

Un escritor que solo proporciona la definición de la interfaz; no se toman acciones sobre ningún método. Esta debería ser la clase base para todos los escritores que no necesitan heredar ningún método de implementación.

class formatter.AbstractWriter

Un escritor que se puede utilizar para depurar formateadores, pero no mucho más. Cada método simplemente se anuncia a sí mismo imprimiendo su nombre y argumentos en la salida estándar.

class formatter.DumbWriter(file=None, maxcol=72)

Clase de escritor simple que escribe la salida en el file object pasado como file o, si se omite file, en la salida estándar. La salida simplemente se ajusta en palabras al número de columnas especificado por maxcol. Esta clase es adecuada para reajustar una secuencia de párrafos.

Servicios Específicos para MS Windows

Este capítulo describe los módulos que sólo están disponibles en plataformas MS Windows.

msvcrt — Rutinas útiles del entorno de ejecución MS VC++

Operaciones con archivos

Consola E/S

Otras funciones

winreg — Acceso al registro de Windows

Funciones

Constantes

HKEY_* Constantes

Access Rights

Específico de 64 bits

Tipos de valor

Objetos de control del registro

:mod:”winsound” — Interfaz de reproducción de sonido para Windows

msvcrt — Rutinas útiles del entorno de ejecución MS VC++

Estas funciones dan acceso a ciertas capacidades útiles en plataformas Windows. Algunos módulos de más alto nivel usan estas funciones para crear las implementaciones en Windows de sus servicios. Por ejemplo, el módulo getpass usa esto en la implementación de la función getpass().

Más información sobre estas funciones se pueden encontrar en la documentación de la API de la plataforma.

El módulo implementa las variantes tanto de caracteres normales como amplios de la API E/S de la consola (se codifican en más de 8 bits, pudiendo llegar hasta 32). La API normal se ocupa solamente de caracteres ASCII y es de uso limitado a aplicaciones internacionales. La API para caracteres amplios se recomienda usar siempre que sea posible.

Distinto en la versión 3.3: Las operaciones en este módulo lanzan ahora OSError donde antes se lanzaba IOError.

Operaciones con archivos

msvcrt.locking(fd, mode, nbytes)

Bloquea parte de un archivo basado en el descriptor del archivo fd del entorno de ejecución C. Lanza una excepción OSError si falla. La región que ha sido bloqueada se extiende desde la posición del archivo actual hasta nbytes bytes y puede que continúe aún habiendo llegado al final del archivo. mode tiene que ser una de las constantes LK_* que están enumeradas más abajo. Se pueden bloquear varias regiones de un mismo archivo pero no se pueden superponer. Las regiones adyacentes no se combinan; tienen que ser desbloqueadas manualmente.

Lanza un evento de auditoría msvcrt.locking con los argumentos fd, mode, nbytes.

msvcrt.LK_LOCK

msvcrt.LK_RLCK

Bloquea los bytes especificados. Si no se pueden bloquear, el programa lo intenta de nuevo tras 1 segundo. Si, tras 10 intentos, no puede bloquear los bytes, se lanza una excepción OSError.

msvcrt.LK_NBLCK

msvcrt.LK_NBRLCK

Bloquea los bytes especificados. Si no se pueden bloquear, lanza una excepción OSError.

msvcrt.LK_UNLCK

Desbloquea los bytes especificados que han sido previamente bloqueados.

msvcrt.setmode(fd, flags)

Establece el modo traducción del final de línea del descriptor de un archivo fd. Si se establece como modo texto, flags debería ser os.O_TEXT; para establecerlo como modo binario, debería ser os.O_BINARY.

msvcrt.open_osfhandle(handle, flags)

Crea un descriptor de archivo en el entorno de ejecución de C desde el manejador de archivo handle. El parámetro flags debe ser un OR bit a bit de os.O_APPEND, os.O_RDONLY, y os.O_TEXT. El descriptor de archivo retornado se puede utilizar como parámetro para os.fdopen() para crear un objeto archivo.

Lanza un evento de auditoría msvcrt.open_osfhandle con los argumentos handle, flags.

msvcrt.get_osfhandle(fd)

Retorna el manejador de archivo para un descriptor de archivo fd. Lanza una excepción OSError si fd no se reconoce.

Lanza un evento de auditoría msvcrt.get_osfhandle con el argumento fd.

Consola E/S

msvcrt.kbhit()

Retorna True si hay una pulsación de tecla está esperando para ser leída.

msvcrt.getch()

Lee una pulsación de la tecla y retorna el carácter resultante como una cadena de caracteres de bytes. Nada se muestra en la consola. Esta llamada se bloqueará si una pulsación de la tecla aún no está disponible, pero no esperará a que se presione Enter. Si la tecla pulsada era una tecla de función especial, esto retornará '\000' o 'xe0'; la siguiente llamada retornará el código de la tecla pulsada. La pulsación de la tecla Control-C no se puede leer con esta función.

msvcrt.getwch()

Variante de carácter amplio de getch(), retornando un valor Unicode.

msvcrt.getche()

Similar a la función getch(), pero la pulsación de la tecla se imprime si representa un carácter imprimible.

msvcrt.getwche()

Variante de carácter amplio de getche(), retornando un valor Unicode.

msvcrt.putch(char)

Imprime la cadena de caracteres de bytes char a la consola sin almacenamiento en buffer.

msvcrt.putwch(unicode_char)

Variante de carácter amplio de putch(), admitiendo un valor Unicode.

msvcrt.ungetch(char)

Provoca que la cadena de caracteres de bytes char sea «colocada de nuevo» en el buffer de la consola, será el siguiente carácter que lea la función getch() o getche().

msvcrt.ungetwch(unicode_char)

Variante de carácter amplio de ungetch(), admitiendo un valor Unicode.

Otras funciones

msvcrt.heapmin()

Fuerza a la pila malloc() a que se limpie y retorne los bloques sin usar al sistema operativo. En el caso de que ocurriera algún fallo, se lanzaría una excepción OSError.

winreg — Acceso al registro de Windows

Estas funciones exponen la API de registro de Windows a Python. En lugar de utilizar un número entero como identificador de registro, se utiliza un handle object para garantizar que los identificadores se cierren correctamente, incluso si el programador se niega a cerrarlos explícitamente.

Distinto en la versión 3.3: Varias funciones de este módulo solían lanzar un WindowsError, que ahora es un alias de OSError.

Funciones

Este módulo ofrece las siguientes funciones:

winreg.CloseKey(hkey)

Cierra una clave de registro abierta previamente. El argumento hkey especifica una clave abierta previamente.

Nota

Si hkey no se cierra con este método (o mediante hkey.Close()), se cierra cuando Python destruye el objeto hkey.

winreg.ConnectRegistry(computer_name, key)

Establece una conexión con un identificador de registro predefinido en otra computadora y retorna un handle object.

computer_name es el nombre de la computadora remota, de la forma r”\\computername”. Si es None, se utiliza la computadora local.

key es el identificador predefinido al que conectarse.

El valor de retorno es el identificador de la llave abierta. Si la función falla, se lanza una excepción OSError.

Lanza un auditing event winreg.ConnectRegistry con argumentos computer_name, key.

Distinto en la versión 3.3: Ver above.

winreg.CreateKey(key, sub_key)

Crea o abre la clave especificada, retornando un handle object.

key es una clave ya abierta, o una de las predefinidas HKEY_* constants.

sub_key es una cadena de caracteres que nombra la clave que este método abre o crea.

Si key es una de las claves predefinidas, sub_key puede ser None. En ese caso, el identificador retornado es el mismo identificador de clave que se pasó a la función.

Si la clave ya existe, esta función abre la clave existente.

El valor de retorno es el identificador de la llave abierta. Si la función falla, se lanza una excepción OSError.

Lanza un auditing event winreg.CreateKey con los argumentos key, sub_key, access.

Lanza un auditing event winreg.OpenKey/result con el argumento key.

Distinto en la versión 3.3: Ver above.

winreg.CreateKeyEx(key, sub_key, reserved=0, access=KEY_WRITE)

Crea o abre la clave especificada, retornando un handle object.

key es una clave ya abierta, o una de las predefinidas HKEY_* constants.

sub_key es una cadena de caracteres que nombra la clave que este método abre o crea.

reserved es un número entero reservado y debe ser cero. El valor predeterminado es cero.

access es un número entero que especifica una máscara de acceso que describe el acceso de seguridad deseado para la clave. El valor predeterminado es KEY_WRITE. Ver Access Rights para otros valores permitidos.

Si key es una de las claves predefinidas, sub_key puede ser None. En ese caso, el identificador retornado es el mismo identificador de clave que se pasó a la función.

Si la clave ya existe, esta función abre la clave existente.

El valor de retorno es el identificador de la llave abierta. Si la función falla, se lanza una excepción OSError.

Lanza un auditing event winreg.CreateKey con los argumentos key, sub_key, access.

Lanza un auditing event winreg.OpenKey/result con el argumento key.

Nuevo en la versión 3.2.

Distinto en la versión 3.3: Ver above.

winreg.DeleteKey(key, sub_key)

Elimina la clave especificada.

key es una clave ya abierta, o una de las predefinidas HKEY_* constants.

sub_key es una cadena de caracteres que debe ser una subclave de la clave identificada por el parámetro key. Este valor no debe ser None, y es posible que la clave no tenga subclaves.

Este método no puede eliminar claves con subclaves.

Si el método tiene éxito, se elimina toda la clave, incluidos todos sus valores. Si el método falla, se lanza una excepción OSError.

Lanza un auditing event winreg.DeleteKey con los argumentos key`, sub_key, access.

Distinto en la versión 3.3: Ver above.

winreg.DeleteKeyEx(key, sub_key, access=KEY_WOW64_64KEY, reserved=0)

Elimina la clave especificada.

Nota

La función DeleteKeyEx() se implementa con la función RegDeleteKeyEx de la API de Windows, que es específica de las versiones de Windows de 64 bits. Consulte la RegDeleteKeyEx documentation [https://msdn.microsoft.com/en-us/library/ms724847%28VS.85%29.aspx].

key es una clave ya abierta, o una de las predefinidas HKEY_* constants.

sub_key es una cadena de caracteres que debe ser una subclave de la clave identificada por el parámetro key. Este valor no debe ser None, y es posible que la clave no tenga subclaves.

reserved es un número entero reservado y debe ser cero. El valor predeterminado es cero.

access es un número entero que especifica una máscara de acceso que describe el acceso de seguridad deseado para la clave. El valor predeterminado es KEY_WOW64_64KEY. Ver Access Rights para otros valores permitidos.

Este método no puede eliminar claves con subclaves.

Si el método tiene éxito, se elimina toda la clave, incluidos todos sus valores. Si el método falla, se lanza una excepción OSError.

En versiones de Windows no compatibles, se lanza NotImplementedError.

Lanza un auditing event winreg.DeleteKey con los argumentos key`, sub_key, access.

Nuevo en la versión 3.2.

Distinto en la versión 3.3: Ver above.

winreg.DeleteValue(key, value)

Elimina un valor con nombre de una clave de registro.

key es una clave ya abierta, o una de las predefinidas HKEY_* constants.

value es una cadena que identifica el valor a eliminar.

Lanza un auditing event winreg.DeleteValue con argumentos key, value.

winreg.EnumKey(key, index)

Enumera las subclaves de una clave de registro abierta y retorna una cadena de caracteres.

key es una clave ya abierta, o una de las predefinidas HKEY_* constants.

index es un número entero que identifica el índice de la clave a recuperar.

La función recupera el nombre de una subclave cada vez que se llama. Normalmente se llama repetidamente hasta que se lanza una excepción OSError, lo que indica que no hay más valores disponibles.

Lanza un auditing event winreg.EnumKey con argumentos key, index.

Distinto en la versión 3.3: Ver above.

winreg.EnumValue(key, index)

Enumera los valores de una clave de registro abierta y retorna una tupla.

key es una clave ya abierta, o una de las predefinidas HKEY_* constants.

index es un número entero que identifica el índice del valor a recuperar.

La función recupera el nombre de una subclave cada vez que se llama. Normalmente se llama repetidamente, hasta que se lanza una excepción OSError, lo que indica que no hay más valores.

El resultado es una tupla de 3 elementos:

Índice

Significado

0

Una cadena de caracteres que identifica el nombre del valor

1

Un objeto que contiene los datos del valor y cuyo tipo depende del tipo de registro subyacente

2

Un número entero que identifica el tipo de datos de valor (consulte la tabla en los documentos para SetValueEx())

Lanza un auditing event winreg.EnumValue con argumentos key, index.

Distinto en la versión 3.3: Ver above.

winreg.ExpandEnvironmentStrings(str)

Expande los marcadores de posición de la variable de entorno %NAME% en cadenas como REG_EXPAND_SZ:

>>> ExpandEnvironmentStrings('%windir%')
'C:\\Windows'

Lanza un auditing event winreg.ExpandEnvironmentStrings con el argumento str.

winreg.FlushKey(key)

Escribe todos los atributos de una clave en el registro.

key es una clave ya abierta, o una de las predefinidas HKEY_* constants.

No es necesario llamar a FlushKey() para cambiar una clave. Los cambios en el registro se descargan en el disco mediante el registro mediante su vaciador diferido. Los cambios en el registro también se vacían en el disco cuando se apaga el sistema. A diferencia de CloseKey(), el método FlushKey() retorna solo cuando todos los datos se han escrito en el registro. Una aplicación solo debe llamar a FlushKey() si requiere absoluta certeza de que los cambios de registro están en el disco.

Nota

Si no sabe si se requiere una llamada FlushKey(), probablemente no lo sea.

winreg.LoadKey(key, sub_key, file_name)

Crea una subclave bajo la clave especificada y almacena la información de registro de un archivo especificado en esa subclave.

key es un identificador retornado por ConnectRegistry() o una de las constantes HKEY_USERS o HKEY_LOCAL_MACHINE.

sub_key es una cadena de caracteres que identifica la subclave a cargar.

file_name es el nombre del archivo desde el que cargar los datos de registro. Este archivo debe haber sido creado con la función SaveKey(). En el sistema de archivos de la tabla de asignación de archivos (FAT), es posible que el nombre del archivo no tenga extensión.

Una llamada a LoadKey() falla si el proceso de llamada no tiene el privilegio SE_RESTORE_PRIVILEGE. Tenga en cuenta que los privilegios son diferentes de los permisos; consulte la RegLoadKey documentation [https://msdn.microsoft.com/en-us/library/ms724889%28v=VS.85%29.aspx] para obtener más detalles.

Si key es un identificador retornado por ConnectRegistry(), entonces la ruta especificada en file_name es relativa a la computadora remota.

Lanza un auditing event winreg.LoadKey con los argumentos key, sub_key, file_name.

winreg.OpenKey(key, sub_key, reserved=0, access=KEY_READ)

winreg.OpenKeyEx(key, sub_key, reserved=0, access=KEY_READ)

Abre la clave especificada, retornando a handle object.

key es una clave ya abierta, o una de las predefinidas HKEY_* constants.

sub_key es una cadena de caracteres que identifica la sub_key para abrir.

reserved es un número entero reservado y debe ser cero. El valor predeterminado es cero.

access es un número entero que especifica una máscara de acceso que describe el acceso de seguridad deseado para la clave. El valor predeterminado es KEY_READ. Ver Access Rights para otros valores permitidos.

El resultado es un nuevo identificador para la clave especificada.

Si la función falla, se lanza OSError.

Lanza un auditing event winreg.OpenKey con los argumentos key, sub_key, access.

Lanza un auditing event winreg.OpenKey/result con el argumento key.

Distinto en la versión 3.2: Permite el uso de argumentos con nombre.

Distinto en la versión 3.3: Ver above.

winreg.QueryInfoKey(key)

Retorna información sobre una clave, como una tupla.

key es una clave ya abierta, o una de las predefinidas HKEY_* constants.

El resultado es una tupla de 3 elementos:

Índice

Significado

0

Un número entero que indica el número de subclaves que tiene esta clave.

1

Un número entero que da el número de valores que tiene esta clave.

2

Un número entero que indica la última vez que se modificó la clave (si está disponible) como cientos de nanosegundos desde el 1 de enero de 1601.

Lanza un auditing event winreg.QueryInfoKey con el argumento key.

winreg.QueryValue(key, sub_key)

Recupera el valor sin nombre de una clave, como una cadena de caracteres.

key es una clave ya abierta, o una de las predefinidas HKEY_* constants.

sub_key es una cadena de caracteres que contiene el nombre de la subclave con la que está asociado el valor. Si este parámetro es None o está vacío, la función recupera el valor establecido por el método SetValue() para la clave identificada por key.

Los valores del registro tienen componentes de nombre, tipo y datos. Este método recupera los datos del primer valor de una clave que tiene un nombre NULL. Pero la llamada a la API subyacente no retorna el tipo, así que siempre use QueryValueEx() si es posible.

Lanza un auditing event winreg.QueryValue con los argumentos key, sub_key, value_name.

winreg.QueryValueEx(key, value_name)

Recupera el tipo y los datos de un nombre de valor especificado asociado con una clave de registro abierta.

key es una clave ya abierta, o una de las predefinidas HKEY_* constants.

value_name es una cadena de caracteres que indica el valor a consultar.

El resultado es una tupla de 2 elementos:

Índice

Significado

0

El valor del elemento de registro.

1

Un número entero que proporciona el tipo de registro para este valor (consulte la tabla en docs para SetValueEx())

Lanza un auditing event winreg.QueryValue con los argumentos key, sub_key, value_name.

winreg.SaveKey(key, file_name)

Guarda la clave especificada y todas sus subclaves en el archivo especificado.

key es una clave ya abierta, o una de las predefinidas HKEY_* constants.

file_name es el nombre del archivo en el que se guardarán los datos del registro. Este archivo no puede existir ya. Si este nombre de archivo incluye una extensión, no se puede usar en sistemas de archivos de tabla de asignación de archivos (FAT) mediante el método LoadKey().

Si key representa una clave en una computadora remota, la ruta descrita por file_name es relativa a la computadora remota. La persona que llama a este método debe poseer el privilegio de seguridad SeBackupPrivilege. Tenga en cuenta que los privilegios son diferentes a los permisos – consulte la documentación sobre conflictos entre derechos de usuario y permisos <https://msdn.microsoft.com/en-us/library/ms724878%28v=VS.85%29.aspx>`__ para más detalles.

Esta función pasa NULL para security_attributes a la API.

Lanza un auditing event winreg.SaveKey con los argumentos key, file_name.

winreg.SetValue(key, sub_key, type, value)

Asocia un valor con una clave especificada.

key es una clave ya abierta, o una de las predefinidas HKEY_* constants.

sub_key es una cadena de caracteres que nombra la subclave con la que está asociado el valor.

type es un número entero que especifica el tipo de datos. Actualmente debe ser REG_SZ, lo que significa que solo se admiten cadenas de caracteres. Utilice la función: SetValueEx() para admitir otros tipos de datos.

value es una cadena de caracteres que especifica el nuevo valor.

Si la clave especificada por el parámetro sub_key no existe, la función SetValue la crea.

Las longitudes de los valores están limitadas por la memoria disponible. Los valores largos (más de 2048 bytes) deben almacenarse como archivos con los nombres de archivo almacenados en el registro de configuración. Esto ayuda a que el registro funcione de manera eficiente.

La clave identificada por el parámetro key debe haber sido abierta con acceso KEY_SET_VALUE.

Lanza un auditing event winreg.SetValue con argumentos key, sub_key, type, value.

winreg.SetValueEx(key, value_name, reserved, type, value)

Almacena datos en el campo de valor de una clave de registro abierta.

key es una clave ya abierta, o una de las predefinidas HKEY_* constants.

value_name es una cadena de caracteres que nombra la subclave con la que está asociado el valor.

reserved puede ser cualquier cosa — cero siempre se pasa a la API.

type es un número entero que especifica el tipo de datos. Consulte Value Types para los tipos disponibles.

value es una cadena de caracteres que especifica el nuevo valor.

Este método también puede establecer un valor adicional e información de tipo para la clave especificada. La clave identificada por el parámetro clave debe haber sido abierta con acceso KEY_SET_VALUE.

Para abrir la clave, use los métodos CreateKey() o OpenKey().

Las longitudes de los valores están limitadas por la memoria disponible. Los valores largos (más de 2048 bytes) deben almacenarse como archivos con los nombres de archivo almacenados en el registro de configuración. Esto ayuda a que el registro funcione de manera eficiente.

Lanza un auditing event winreg.SetValue con argumentos key, sub_key, type, value.

winreg.DisableReflectionKey(key)

Desactiva la reflexión del registro para los procesos de 32 bits que se ejecutan en un sistema operativo de 64 bits.

key es una clave ya abierta, o una de las predefinidas HKEY_* constants.

Generalmente lanzará NotImplementedError si se ejecuta en un sistema operativo de 32 bits.

Si la clave no está en la lista de reflexión, la función tiene éxito pero no tiene ningún efecto. La desactivación de la reflexión de una clave no afecta la reflexión de ninguna subclave.

Lanza un auditing event winreg.DisableReflectionKey con el argumento key.

winreg.EnableReflectionKey(key)

Restaura la reflexión del registro para la clave deshabilitada especificada.

key es una clave ya abierta, o una de las predefinidas HKEY_* constants.

Generalmente lanzará NotImplementedError si se ejecuta en un sistema operativo de 32 bits.

La restauración de la reflexión de una clave no afecta la reflexión de ninguna subclave.

Lanza un auditing event winreg.EnableReflectionKey con el argumento key.

winreg.QueryReflectionKey(key)

Determina el estado de reflexión para la clave especificada.

key es una clave ya abierta, o una de las predefinidas HKEY_* constants.

Retorna True si la reflexión está deshabilitada.

Generalmente lanzará NotImplementedError si se ejecuta en un sistema operativo de 32 bits.

Lanza un auditing event winreg.QueryReflectionKey con el argumento key.

Constantes

Las siguientes constantes están definidas para su uso en muchas funciones _winreg.

HKEY_* Constantes

winreg.HKEY_CLASSES_ROOT

Las entradas de registro subordinadas a esta clave definen tipos (o clases) de documentos y las propiedades asociadas con esos tipos. Las aplicaciones Shell y COM utilizan la información almacenada en esta clave.

winreg.HKEY_CURRENT_USER

Las entradas de registro subordinadas a esta clave definen las preferencias del usuario actual. Estas preferencias incluyen la configuración de variables de entorno, datos sobre grupos de programas, colores, impresoras, conexiones de red y preferencias de la aplicación.

winreg.HKEY_LOCAL_MACHINE

Las entradas de registro subordinadas a esta clave definen el estado físico de la computadora, incluidos los datos sobre el tipo de bus, la memoria del sistema y el hardware y software instalados.

winreg.HKEY_USERS

Las entradas de registro subordinadas a esta clave definen la configuración de usuario predeterminada para nuevos usuarios en la computadora local y la configuración de usuario para el usuario actual.

winreg.HKEY_PERFORMANCE_DATA

Las entradas de registro subordinadas a esta clave le permiten acceder a los datos de rendimiento. Los datos no se almacenan realmente en el registro; las funciones de registro hacen que el sistema recopile los datos de su fuente.

winreg.HKEY_CURRENT_CONFIG

Contiene información sobre el perfil de hardware actual del sistema informático local.

winreg.HKEY_DYN_DATA

Esta clave no se usa en versiones de Windows posteriores a la 98.

Access Rights

Para más información, ver Registry Key Security and Access [https://msdn.microsoft.com/en-us/library/ms724878%28v=VS.85%29.aspx].

winreg.KEY_ALL_ACCESS

Combina los derechos de acceso STANDARD_RIGHTS_REQUIRED, KEY_QUERY_VALUE, KEY_SET_VALUE, KEY_CREATE_SUB_KEY, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY, y KEY_CREATE_LINK.

winreg.KEY_WRITE

Combina los derechos de acceso STANDARD_RIGHTS_WRITE, KEY_SET_VALUE, y KEY_CREATE_SUB_KEY.

winreg.KEY_READ

Combina los valores STANDARD_RIGHTS_READ, KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, y KEY_NOTIFY.

winreg.KEY_EXECUTE

Equivalente a KEY_READ.

winreg.KEY_QUERY_VALUE

Requerido para consultar los valores de una clave de registro.

winreg.KEY_SET_VALUE

Requerido para crear, eliminar o establecer un valor de registro.

winreg.KEY_CREATE_SUB_KEY

Necesario para crear una subclave de una clave de registro.

winreg.KEY_ENUMERATE_SUB_KEYS

Requerido para enumerar las subclaves de una clave de registro.

winreg.KEY_NOTIFY

Requerido para solicitar notificaciones de cambio para una clave de registro o para subclaves de una clave de registro.

winreg.KEY_CREATE_LINK

Reservado para uso del sistema.

Específico de 64 bits

Para más información, ver Accessing an Alternate Registry View [https://msdn.microsoft.com/en-us/library/aa384129(v=VS.85).aspx].

winreg.KEY_WOW64_64KEY

Indica que una aplicación en Windows de 64 bits debería funcionar en la vista de registro de 64 bits.

winreg.KEY_WOW64_32KEY

Indica que una aplicación en Windows de 64 bits debería funcionar en la vista de registro de 32 bits.

Tipos de valor

Para más información, ver Registry Value Types [https://msdn.microsoft.com/en-us/library/ms724884%28v=VS.85%29.aspx].

winreg.REG_BINARY

Datos binarios en cualquier forma.

winreg.REG_DWORD

Número de 32 bits.

winreg.REG_DWORD_LITTLE_ENDIAN

Un número de 32 bits en formato little-endian. Equivalente a REG_DWORD.

winreg.REG_DWORD_BIG_ENDIAN

Un número de 32 bits en formato big-endian.

winreg.REG_EXPAND_SZ

Cadena de caracteres terminada en nulo que contiene referencias a variables de entorno (%PATH%).

winreg.REG_LINK

Un enlace simbólico Unicode.

winreg.REG_MULTI_SZ

Una secuencia de cadenas de caracteres terminadas en nulo, terminadas por dos caracteres nulos. (Python maneja esta terminación automáticamente).

winreg.REG_NONE

Sin tipo de valor definido.

winreg.REG_QWORD

Un número de 64 bits.

Nuevo en la versión 3.6.

winreg.REG_QWORD_LITTLE_ENDIAN

Un número de 64 bits en formato little-endian. Equivalente a REG_QWORD.

Nuevo en la versión 3.6.

winreg.REG_RESOURCE_LIST

Una lista de recursos de controladores de dispositivo.

winreg.REG_FULL_RESOURCE_DESCRIPTOR

Una configuración de hardware.

winreg.REG_RESOURCE_REQUIREMENTS_LIST

Una lista de recursos de hardware.

winreg.REG_SZ

Una cadena de caracteres terminada en nulo.

Objetos de control del registro

Este objeto envuelve un objeto HKEY de Windows y lo cierra automáticamente cuando se destruye. Para garantizar la limpieza, puede llamar al método Close() en el objeto, o a la función CloseKey().

Todas las funciones de registro de este módulo retornan uno de estos objetos.

Todas las funciones de registro de este módulo que aceptan un objeto identificador también aceptan un número entero, sin embargo, se recomienda el uso del objeto identificador.

Los objetos de control proporcionan semántica para __bool__() – así

if handle:
    print("Yes")

imprimirá Yes si el controlador es válido actualmente (no se ha cerrado o desprendido).

El objeto también admite la semántica de comparación, por lo que los objetos de identificador se compararán con verdadero si ambos hacen referencia al mismo valor de identificador de Windows subyacente.

Los objetos de identificador se pueden convertir a un número entero (por ejemplo, usando la función incorporada int() function), en cuyo caso se retorna el valor de identificador de Windows subyacente. También puede usar el método Detach() para retornar el identificador de enteros y también desconectar el identificador de Windows del objeto identificador.

PyHKEY.Close()

Cierra el identificador de Windows subyacente.

Si el controlador ya está cerrado, no se lanza ningún error.

PyHKEY.Detach()

Separa el identificador de Windows del objeto identificador.

El resultado es un número entero que contiene el valor del identificador antes de que se separe. Si el controlador ya está separado o cerrado, esto retornará cero.

Después de llamar a esta función, el identificador se invalida efectivamente, pero el identificador no se cierra. Llamaría a esta función cuando necesite que el identificador Win32 subyacente exista más allá de la vida útil del objeto identificador.

Lanza un auditing event winreg.PyHKEY.Detach con el argumento key.

PyHKEY.__enter__()

PyHKEY.__exit__(*exc_info)

El objeto HKEY implementa __enter__() y __exit__() y, por lo tanto, admite el protocolo de contexto para la declaración with:

with OpenKey(HKEY_LOCAL_MACHINE, "foo") as key:
    ...  # work with key

cerrará automáticamente key cuando el control abandone el bloque with.

:mod:”winsound” — Interfaz de reproducción de sonido para Windows

El modulo winsound permite acceder a la maquinaria básica de reproducción de sonidos proporcionada por la plataformas Windows. Incluye funciones y varias constantes.

winsound.Beep(frequency, duration)

Hace sonar el altavoz del PC. El parámetro frequency especifica la frecuencia, en hercio (hz), de la señal de audio y debe estar en el rango de 37 a 32.767 hz. El parámetro duration especifica el numero de milisegundo de duración de la señal de audio. Si el sistema no puede hacer sonar el altavoz, se lanza RuntimeError.

winsound.PlaySound(sound, flags)

Llama a la función responsable de PlaySound() desde el API de la plataforma. El parámetro sound puede ser un nombre de archivo, un alias de sonido del sistema, datos de audio como un bytes-like object , o None. Su interpretación depende del valor de flags, que puede ser una combinación ORed de las constantes descritas a continuación. Si el parámetro de sound es None, cualquier sonido de forma de onda que se esté reproduciendo en ese momento se detiene. Si el sistema indica un error, se lanza RuntimeError` .

winsound.MessageBeep(type=MB_OK)

Llama a la función responsable de MensajeBeep() de la API de la plataforma. Esto reproduce un sonido como se especifica en el registro. El argumento type especifica qué sonido se reproduce; los valores posibles son -1, MB_ICONASTERISK, MB_ICONEXCLAMATION, MB_ICONHAND, MB_ICONQUESTION, y MB_OK, todos descritos a continuación. El valor «1» produce un «simple pitido»; este es el último recurso si un sonido no puede ser reproducido de otra manera. Si el sistema indica un error, se lanza RuntimeError.

winsound.SND_FILENAME

El parámetro sound es el nombre de un archivo WAV. No lo uses con SND_ALIAS.

winsound.SND_ALIAS

El parámetro sound es un nombre de asociación de sonido del registro. Si el registro no contiene tal nombre, reproduce el sonido por defecto del sistema a menos que SND_NODEFAULT también se especifique. Si no se registra ningún sonido por defecto, se lanza RuntimeError. No lo uses con SND_FILENAME.

Todos los sistemas Win32 soportan al menos lo siguiente; la mayoría de los sistemas soportan muchos más:

PlaySound() name

Panel de control correspondiente nombre (name) del sonido

'SystemAsterisk'

Asterisco

'SystemExclamation'

Exclamación

'SystemExit'

Salir de Windows

'SystemHand'

Parada crítica

'SystemQuestion'

Pregunta

Por ejemplo:

import winsound
# Play Windows exit sound.
winsound.PlaySound("SystemExit", winsound.SND_ALIAS)

# Probably play Windows default sound, if any is registered (because
# "*" probably isn't the registered name of any sound).
winsound.PlaySound("*", winsound.SND_ALIAS)

winsound.SND_LOOP

Reproducir el sonido repetidamente. El flag SND_ASYNC también debe ser usada para evitar el bloqueo. No puede ser usada con SND_MEMORY.

winsound.SND_MEMORY

El parámetro sound de PlaySound() es una imagen de memoria de un archivo WAV, como un bytes-like object.

Nota

Este módulo no admite la reproducción desde una imagen de memoria de forma sincrónica, por lo que una combinación de este indicador y SND_ASYNC se lanza RuntimeError.

winsound.SND_PURGE

Detiene la reproducción de todas las instancias de un sonido específico.

Nota

Esta flag no esta soportado en las plataformas modernas de Windows.

winsound.SND_ASYNC

Retorna inmediatamente, permitiendo que los sonidos se reproduzcan asincrónicamente.

winsound.SND_NODEFAULT

Si no se puede encontrar el audio especificado, no reproduce el sonido predeterminado del sistema.

winsound.SND_NOSTOP

No interrumpe los sonidos que se están reproduciendo.

winsound.SND_NOWAIT

Retorna inmediatamente en caso de que el controlador de sonido está ocupado.

Nota

Esta flag no esta soportado en las plataformas modernas de Windows.

winsound.MB_ICONASTERISK

Reproduce el sonido SystemDefault.

winsound.MB_ICONEXCLAMATION

Reproduce el sonido SystemExclamation.

winsound.MB_ICONHAND

Reproduce el sonido SystemHand.

winsound.MB_ICONQUESTION

Reproduce el sonido SystemQuestion.

winsound.MB_OK

Reproduce el sonido SystemDefault.

Servicios específicos de Unix

Los módulos descritos en este capítulo proporcionan interfaces para las características exclusivas del sistema operativo Unix o, en algunos casos, para algunas o muchas variantes del mismo. He aquí una visión general:

posix — Las llamadas más comunes al sistema POSIX

Soporte de archivos grandes

Contenido notable del módulo

pwd — La base de datos de contraseñas

grp — La base de datos de grupo

termios —Control tty estilo POSIX

Ejemplo

tty — Funciones de control de terminal

pty — Utilidades para Pseudo-terminal

Ejemplo

fcntl — Las llamadas a sistema fcntl y ioctl

resource — Información sobre el uso de recursos

Límites de recursos

Utilización de recursos

syslog — Rutinas de la biblioteca syslog de Unix

Ejemplos

Ejemplo sencillo

posix — Las llamadas más comunes al sistema POSIX

Este módulo proporciona acceso a la funcionalidad del sistema operativo que está estandarizada por el estándar C y el estándar POSIX (una interfaz Unix finamente disfrazada).

No importe este módulo directamente. En su lugar, importe el módulo os, que proporciona una versión portable de esta interfaz. En Unix, el módulo os proporciona un superconjunto de la interfaz posix. En sistemas operativos que no son Unix, el módulo posix no está disponible, pero un subconjunto siempre está disponible a través de la interfaz os. Una vez que se importa os, no hay penalización de rendimiento en su uso en lugar de posix. Además, os proporciona algunas funciones adicionales, como llamar automáticamente a putenv() cuando se cambia una entrada en os.environ.

Los errores se notifican como excepciones; las excepciones habituales se proporcionan para los errores de tipo, mientras que los errores notificados por las llamadas del sistema lanzan OSError.

Soporte de archivos grandes

Varios sistemas operativos (incluidos AIX, HP-UX, Irix y Solaris) proporcionan compatibilidad con archivos de más de 2 GiB de un modelo de programación C donde int y long son valores de 32 bits. Esto se logra normalmente definiendo el tamaño relevante y los tipos de desplazamiento como valores de 64 bits. Tales archivos se conocen a veces como large files.

La compatibilidad con archivos grandes está habilitada en Python cuando el tamaño de un off_t es mayor que un long y long long es al menos tan grande como off_t. Puede ser necesario configurar y compilar Python con ciertos indicadores del compilador para habilitar este modo. Por ejemplo, está habilitado de forma predeterminada con las versiones recientes de Irix, pero con Solaris 2.6 y 2.7 debe hacer algo como:

CFLAGS="`getconf LFS_CFLAGS`" OPT="-g -O2 $CFLAGS" \
        ./configure

En sistemas Linux con capacidad para archivos grandes, esto podría funcionar:

CFLAGS='-D_LARGEFILE64_SOURCE -D_FILE_OFFSET_BITS=64' OPT="-g -O2 $CFLAGS" \
        ./configure

Contenido notable del módulo

Además de muchas funciones descritas en la documentación del módulo os, posix define el siguiente elemento de datos:

posix.environ

Diccionario que representa el entorno de cadena en el momento en que se inició el intérprete. Las claves y los valores son bytes en Unix y str en Windows. Por ejemplo, environ[b'HOME'] (environ['HOME'] en Windows) es el nombre de ruta de acceso de su directorio principal, equivalente a getenv("HOME") en C.

La modificación de este diccionario no afecta al entorno de cadena que transmite execv(), popen() o system(); si necesita cambiar el entorno, pase environ a execve() o agregue asignaciones variables y declaraciones de exportación a la cadena de comandos para system() o popen().

Distinto en la versión 3.2: En Unix, las claves y los valores son bytes.

Nota

El módulo os proporciona una implementación alternativa de environ que actualiza el entorno en la modificación. Tenga en cuenta también que la actualización os.environ hará que este diccionario sea obsoleto. El uso de la versión del módulo os de esto se recomienda sobre el acceso directo al módulo posix.

pwd — La base de datos de contraseñas

Este módulo proporciona acceso a la base de datos de cuentas de usuario y contraseñas de Unix. Está disponible en todas las versiones de Unix.

Las entradas de la base de datos de contraseñas se reportan como un objeto de tipo tupla, cuyos atributos corresponden a los miembros de la estructura passwd (campo Atributo abajo, ver <pwd.h>):

Índice

Atributo

Significado

0

pw_name

Nombre de usuario

1

pw_passwd

Contraseña encriptada opcional

2

pw_uid

Identificación numérica de usuario

3

pw_gid

Identificación del grupo numérico

4

pw_gecos

Nombre de usuario o campo de comentarios

5

pw_dir

El directorio home del usuario

6

pw_shell

Intérprete de comandos de usuario

Los elementos uid y gid son enteros, todos los demás son cadenas. KeyError se lanza si la entrada pedida no se encuentra.

Nota

En Unix tradicional, el campo pw_passwd generalmente contiene una contraseña cifrada con un algoritmo derivado de DES (ver módulo crypt). Sin embargo, la mayoría de los sistemas operativos modernos utilizan un sistema llamado shadow password. En esos unices, el campo pw_passwd solo contiene un asterisco ('*') o la letra 'x' donde la contraseña cifrada se almacena en un archivo /etc/shadow que no es legible por todo el mundo. Si el campo pw_passwd contiene algo útil depende del sistema. Si está disponible, el módulo spwd debe usarse donde se requiera acceso a la contraseña encriptada.

Define los siguientes elementos:

pwd.getpwuid(uid)

Retorna la entrada de la base de datos de contraseñas para el ID de usuario numérico dado.

pwd.getpwnam(name)

Retorna la entrada de la base de datos de contraseñas para el nombre de usuario dado.

pwd.getpwall()

Retorna una lista de todas las entradas de la base de datos de contraseñas disponibles, en orden arbitrario.

Ver también

Módulo grp

Una interfaz para la base de datos de grupos, similar a esta.

Módulo spwd

Una interfaz para la base de datos de contraseñas ocultas, similar a esta.

grp — La base de datos de grupo

Este módulo proporciona acceso a la base de datos del grupo Unix. Está disponible en todas las versiones de Unix.

Group database entries are reported as a tuple-like object, whose attributes correspond to the members of the group structure (Attribute field below, see <grp.h>):

Índice

Atributo

Significado

0

gr_name

el nombre del grupo

1

gr_passwd

El grupo contraseña (encriptado); usualmente vacío

2

gr_gid

el grupo ID numérico

3

gr_mem

todos los nombres de usuario de los miembros del grupo

El gid es un número entero, el nombre y la contraseña son cadenas y la lista de miembros es una lista de cadenas. (Tenga en cuenta que la mayoría de los usuarios no se enumeran explícitamente como miembros del grupo en el que se encuentran de acuerdo con la base de datos de contraseñas. Consulte ambas bases de datos para obtener información completa sobre la membresía. También tenga en cuenta que un ‘’gr_name’’ que comienza con un + o - es probable que sea una referencia de YP/NIS y puede que no sea accesible vía getgrnam() o getgrgid().)

Define los siguientes elementos:

grp.getgrgid(gid)

Retorna la entrada de la base de datos del grupo para el ID de grupo numérico dado. Se genera KeyError si no se puede encontrar la entrada solicitada.

Obsoleto desde la versión 3.6: Desde Python 3.6, la compatibilidad con argumentos no enteros como flotantes o cadenas en getgrgid() está obsoleta.

grp.getgrnam(name)

Retorna la entrada de la base de datos del grupo para el nombre de grupo dado. Se genera KeyError si no se puede encontrar la entrada solicitada.

grp.getgrall()

Retorna una lista de todas las entradas de grupo disponibles, en orden arbitrario.

Ver también

Módulo pwd

Una interfaz para la base de datos de usuarios, similar a esta.

Módulo spwd

Una interfaz para la base de datos de contraseñas ocultas, similar a esta.

termios —Control tty estilo POSIX

Este módulo proporciona una interfaz para las llamadas POSIX para el control de E/S (entrada/salida) tty. Para obtener una descripción completa de estas llamadas, consulte termios (3) Página de manual de Unix. Solo está disponible para aquellas versiones de Unix que admitan el control de E/S tty estilo POSIX termios configurado durante la instalación.

Todas las funciones de este módulo toman un descriptor de archivo fd como primer argumento. Puede ser un descriptor de archivo entero, como el que retorna sys.stdin.fileno(), o un file object, como el propio sys.stdin`.

Este módulo también define todas las constantes necesarias para trabajar con las funciones proporcionadas aquí; tienen el mismo nombre que sus contrapartes en C. Consulte la documentación de su sistema para obtener más información sobre el uso de estas interfaces de control de terminal.

El módulo define las siguientes funciones:

termios.tcgetattr(fd)

Retorna una lista que contiene los atributos tty para el descriptor de archivo fd, como se muestra a continuación: [iflag, oflag, cflag, lflag, ispeed, ospeed, cc] donde cc es una lista de los caracteres especiales tty (cada una es una cadena de longitud 1, excepto los elementos con índices VMIN and VTIME, que son números enteros cuando se definen estos campos). La interpretación de las banderas y las velocidades, así como la indexación en el arreglo cc, debe realizarse utilizando las constantes simbólicas definidas en el módulo termios .

termios.tcsetattr(fd, when, attributes)

Establezca los atributos tty para el descriptor de archivo fd de los atributos, que es una lista como la retornada por tcgetattr(). El argumento when determina cuándo se cambian los atributos: TCSANOW para cambiar inmediatamente, TCSADRAIN para cambiar después de transmitir toda la salida en cola, o TCSAFLUSH para cambiar después de transmitir toda la salida en cola y descartar toda la entrada en cola.

termios.tcsendbreak(fd, duration)

Envíe una pausa en el descriptor de archivo fd. Una duración cero envía una pausa de 0.25 a 0.5 segundos; una duración distinta de cero tiene un significado dependiente del sistema.

termios.tcdrain(fd)

Espere hasta que se haya transmitido toda la salida escrita en el descriptor de archivo fd.

termios.tcflush(fd, queue)

Descartar datos en cola en el descriptor de archivo fd. El selector queue especifica qué cola: TCIFLUSH para la cola de entrada, TCOFLUSH para la cola de salida, o TCIOFLUSH para ambas colas.

termios.tcflow(fd, action)

Suspender o reanudar la entrada o salida en el descriptor de archivo fd. El argumento action puede ser TCOOFF para suspender la salida, TCOON para reiniciar la salida, TCIOFF para suspender la entrada, o TCION para reiniciar la entrada.

Ver también

Módulo tty

Funciones de conveniencia para operaciones comunes de control de terminal.

Ejemplo

Aquí hay una función que solicita una contraseña con el eco desactivado. Tenga en cuenta la técnica utilizando una llamada separada tcgetattr() y una sentencia try … finally para asegurarse de que los antiguos atributos tty se restauran exactamente sin importar lo que suceda:

def getpass(prompt="Password: "):
    import termios, sys
    fd = sys.stdin.fileno()
    old = termios.tcgetattr(fd)
    new = termios.tcgetattr(fd)
    new[3] = new[3] & ~termios.ECHO          # lflags
    try:
        termios.tcsetattr(fd, termios.TCSADRAIN, new)
        passwd = input(prompt)
    finally:
        termios.tcsetattr(fd, termios.TCSADRAIN, old)
    return passwd

tty — Funciones de control de terminal

Código fuente: Lib/tty.py [https://github.com/python/cpython/tree/3.9/Lib/tty.py]

El módulo tty define funciones para poner la tty en los modos cbreak y raw.

Dado que requiere el módulo termios, solamente funciona en Unix.

El módulo tty define las siguientes funciones:

tty.setraw(fd, when=termios.TCSAFLUSH)

Cambia el modo del descriptor de archivo fd a raw. Si se omite when, el valor por defecto es termios.TCSAFLUSH, que se pasa a termios.tcsetattr().

tty.setcbreak(fd, when=termios.TCSAFLUSH)

Cambia el modo del descriptor de archivo fd a cbreak. Si se omite when, el valor por defecto es termios.TCSAFLUSH, que se pasa a termios.tcsetattr().

Ver también

Módulo termios

Interfaz de control de la terminal de bajo nivel.

pty — Utilidades para Pseudo-terminal

Código Fuente: Lib/pty.py [https://github.com/python/cpython/tree/3.9/Lib/pty.py]

El módulo pty define las operaciones para manejar el concepto de pseudo-terminal: iniciar otro proceso para poder escribir y leer desde su propia terminal mediante programación.

Debido a que el manejo de una pseudo-terminal depende en gran medida de la plataforma, este código es solo para Linux (se supone que el código de Linux funciona para otras plataformas, pero este aún no se ha probado)

El modulo pty define las siguientes funciones:

pty.fork()

Bifurcación. Conectar en su propia terminal (terminal hijo) una pseudo-terminal. El valor de retorno es (pid, fd). Tener en cuenta que la terminal hijo tiene como valor pid 0 y fd es invalid. El valor de retorno del padre es el pid del hijo, y fd es un descriptor de archivo conectado a la terminal hijo (también a la salida y entrada estándar de la terminal hijo)

pty.openpty()

Abre un nuevo par de pseudo-terminales, usando os.openpty(), o código de emulación para sistemas genéricos de Unix. Retorna un par de descriptores de archivo (master, slave), para el master y el slave respectivamente.

pty.spawn(argv[, master_read[, stdin_read]])

Genera un proceso conectado a su terminal con el io estándar del proceso actual. Esto se usa a frecuentemente para confundir programas que insisten en leer desde la terminal de control. Se espera que el proceso generado detrás de pty sea finalizado y cuando lo haga spawn se retornará.

Las funciones master_read y stdin_read se les envía como parámetro un descriptor de archivo y siempre deben retornar una cadena de bytes. A fin de que se obligue a spawn a retornar antes que el proceso hijo salga se debe lanzar un OSError.

La implementación predeterminada para ambas funciones retornará hasta 1024 bytes cada vez que se llamen. El dato retornado de master_read se pasa al descriptor de archivo maestro para leer la salida del proceso hijo, y stdin_read pasa el descriptor de archivo 0, para leer desde la entrada del proceso padre.

Retornando una cadena de bytes vacía de cualquier llamado es interpretado como una condición de fin de archivo (EOF), y el llamado no se realizará después de eso. Si stdin_read retorna EOF la terminal de control ya no puede comunicarse con el proceso padre o el proceso hijo. A menos que el proceso hijo se cierre sin ninguna entrada spawn se repetirá para siempre. Si master_read retorna EOF se produce el mismo comportamiento (al menos en Linux)

Si ambas retrollamadas retornan EOF entonces spawn probablemente nunca retorne algo, a menos que select entregue un error en su plataforma cuando pasan tres listas vacías. Esto es un error documentado en issue 26228 [https://bugs.python.org/issue26228].

Retorna el valor del estado de salida de os.waitpid() en el proceso hijo.

waitstatus_to_exitcode() se puede utilizar para convertir el estado de salida en un código de salida.

Lanza un evento de auditoria pty.spawn con el argumento argv.

Distinto en la versión 3.4: spawn() ahora retorna el valor de estado de os.waitpid() para los procesos hijos.

Ejemplo

El siguiente programa actúa como el comando de Unix script(1), usando una pseudo-terminal para registrar todas las entradas y salidas de una sesión en «typescript».

import argparse
import os
import pty
import sys
import time

parser = argparse.ArgumentParser()
parser.add_argument('-a', dest='append', action='store_true')
parser.add_argument('-p', dest='use_python', action='store_true')
parser.add_argument('filename', nargs='?', default='typescript')
options = parser.parse_args()

shell = sys.executable if options.use_python else os.environ.get('SHELL', 'sh')
filename = options.filename
mode = 'ab' if options.append else 'wb'

with open(filename, mode) as script:
    def read(fd):
        data = os.read(fd, 1024)
        script.write(data)
        return data

    print('Script started, file is', filename)
    script.write(('Script started on %s\n' % time.asctime()).encode())

    pty.spawn(shell, read)

    script.write(('Script done on %s\n' % time.asctime()).encode())
    print('Script done, file is', filename)

fcntl — Las llamadas a sistema fcntl y ioctl

Este módulo realiza control de archivos y control de E/S en descriptores de ficheros. Es una interfaz para las rutinas de Unix fcntl() y ioctl(). Para una completa descripción de estas llamadas, ver las páginas del manual de Unix fcntl(2) y ioctl(2).

Todas las funciones de este módulo toman un descriptor de fichero fd como su primer argumento. Puede ser un descriptor de fichero entero, como el retornado por sys.stdin.fileno(), o un objeto io.IOBase, como sys.stdin`, que proporciona un fileno() que retornan un descriptor de fichero original.

Distinto en la versión 3.3: Las operaciones en este módulo solían lanzar un IOError donde ahora lanzan un OSError.

Distinto en la versión 3.8: El módulo fcntl ahora contiene las constantes F_ADD_SEALS, F_GET_SEALS, y F_SEAL_* para sellar los descriptores de fichero os.memfd_create().

Distinto en la versión 3.9: On macOS, the fcntl module exposes the F_GETPATH constant, which obtains the path of a file from a file descriptor. On Linux(>=3.15), the fcntl module exposes the F_OFD_GETLK, F_OFD_SETLK and F_OFD_SETLKW constants, which are used when working with open file description locks.

El módulo define las siguientes funciones:

fcntl.fcntl(fd, cmd, arg=0)

Realice la operación cmd en el descriptor de fichero fd (los objetos de fichero que proporcionan un método fileno() también son aceptados). Los valores utilizados para cmd dependen del sistema operativo y están disponibles como constantes en el módulo fcntl, utilizando los mismos nombres que se utilizan en los archivos de cabecera C relevantes. El argumento arg puede ser un valor entero o un objeto bytes. Con un valor entero, el valor retorno de esta función es el valor entero retornado por la llamada en C fcntl() . Cuando el argumento son bytes representa una estructura binaria, e.g. creada por struct.pack(). Los datos binarios se copian en un búfer cuya dirección se pasa a la llamada en C :fcntl(). El valor de retorno después de una llamada correcta es el contenido del búfer, convertido en un objeto bytes. La longitud del objeto retornado será la misma que la longitud del argumento arg. Esta longitud está limitada a 1024 bytes. Si la información retornada en el búfer por el sistema operativo es mayor que 1024 bytes, lo más probable es que se produzca una violación de segmento o a una corrupción de datos más sutil.

Si se produce un error en fcntl(), se lanza un OSError.

Lanza un auditing event fcntl.fcntl con argumentos fd, cmd, arg.

fcntl.ioctl(fd, request, arg=0, mutate_flag=True)

Esta función es idéntica a la función fcntl(), excepto por el manejo de los argumentos que es aún más complicado.

El parámetro request se encuentra limitado a valores que encajen en 32-bits. Se pueden encontrar constantes adicionales de interés para usar como argumento request en el módulo termios, con los mismos nombres que se usan en los archivos de cabecera C relevantes.

El parámetro arg puede ser un entero, un objeto que admita una interfaz de búfer de solo lectura (como bytes) o un objeto que admita una interfaz de búfer de lectura-escritura (como: clase bytearray).

En todos los casos excepto en el último, el comportamiento es el de la función fcntl().

Si se pasa un búfer mutable, el comportamiento estará determinado por el valor del parámetro mutate_flag.

Si es falso, la mutabilidad del búfer se ignorará y el comportamiento será como el de un búfer de solo lectura, excepto por el límite de 1024 bytes mencionado arriba, que será evitado – siempre que el búfer que pase sea al menos tan largo como el sistema operativo quiera colocar allí, las cosas deberían funcionar.

Si mutate_flag es verdadero (valor predeterminado), entonces el búfer se pasa (en efecto) a la llamada al sistema subyacente ioctl(), el código de retorno de éste último se retorna al Python que llama, y ​​el nuevo contenido del búfer refleja la acción de ioctl(). Esto es una ligera simplificación, porque si el búfer proporcionado tiene menos de 1024 bytes de longitud, primero se copia en un búfer estático de 1024 bytes de longitud que luego se pasa a ioctl() y se copia de nuevo en el búfer proporcionado.

Si ioctl() falla, se lanza la excepción OSError.

Un ejemplo:

>>> import array, fcntl, struct, termios, os
>>> os.getpgrp()
13341
>>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, "  "))[0]
13341
>>> buf = array.array('h', [0])
>>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1)
0
>>> buf
array('h', [13341])

Lanza un evento auditing event fcntl.ioctl con argumentos fd, request, arg.

fcntl.flock(fd, operation)

Realiza la operación de bloqueo operation sobre el descriptor de fichero fd (los objetos de fichero que proporcionan un método fileno() también son aceptados). Ver el manual de Unix flock(2) para más detalles. (En algunos sistemas, esta función es emulada usando fcntl().)

Si flock() falla, una excepción OSError se lanza.

Lanza un auditing event fcntl.flock con argumentos fd, operation.

fcntl.lockf(fd, cmd, len=0, start=0, whence=0)

Esto es esencialmente un «wrapper» de las llamadas de bloqueo fcntl() . * fd * es el descriptor de fichero (los objetos de fichero que proporcionan un método fileno() también se aceptan) del archivo para bloquear o desbloquear, y cmd es uno de los siguientes valores:

LOCK_UN – desbloquear

LOCK_SH – adquirir un bloqueo compartido

LOCK_EX – adquirir un bloqueo exclusivo

Cuando cmd es LOCK_SH o LOCK_EX, también se puede usar OR bit a bit con LOCK_NB para evitar el bloqueo en la adquisición de bloqueos. Si se usa LOCK_NB y no se puede adquirir el bloqueo, se generará un LOCK_NB y la excepción tendrá un atributo errno establecido a EACCES o EAGAIN (según el sistema operativo; para la portabilidad, compruebe ambos valores). En al menos algunos sistemas, LOCK_EX solo se puede usar si el descriptor de fichero se refiere a un archivo abierto para escritura.

len es el número de bytes a bloquear, start es el byte de «offset» en el cual comienza el bloqueo, relativo a whence, y whence es como con io.IOBase.seek(), específicamente:

0 – relativo al comienzo del archivo (os.SEEK_SET)

1 – relativa a la posición actual del búfer (os.SEEK_CUR)

2 – relativo al final del archivo (os.SEEK_END)

El valor por defecto de*start* es 0, lo que significa que comienza al inicio del archivo. El valor por defecto para len es 0 lo que significa bloquear hasta el final del archivo. El valor por defecto para whence también es 0.

Lanza un auditing event fcntl.lockf con argumentos fd, cmd, len, start, whence.

Ejemplos (todos en un sistema compatible con SVR4):

import struct, fcntl, os

f = open(...)
rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY)

lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0)
rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata)

Tenga en cuenta que en el primer ejemplo, la variable de valor de retorno rv contendrá un valor entero; en el segundo ejemplo contendrá un objeto bytes. El diseño de la estructura para la variable lockdata depende del sistema — por lo tanto, usar la llamada flock() puede ser mejor.

Ver también

Módulo os

Si los flags de bloqueo O_SHLOCK y O_EXLOCK están presentes en el módulo os (sólo en BSD), la función os.open() proporciona una alternativa a las funciones lockf() y flock().

resource — Información sobre el uso de recursos

Este módulo proporciona mecanismos básicos para medir y controlar los recursos del sistema utilizados por un programa.

Las constantes simbólicas se utilizan para especificar recursos concretos del sistema y para solicitar información de uso sobre el proceso actual o sus elementos secundarios.

Se genera un OSError cuando la llamada al sistema (syscall) falla.

exception resource.error

Un alias en desuso de OSError.

Distinto en la versión 3.3: Tras PEP 3151 [https://www.python.org/dev/peps/pep-3151] esta clase se convirtió en un alias de OSError.

Límites de recursos

El uso de recursos se puede limitar usando la función setrlimit() que se describe a continuación. Cada recurso está controlado por un par de límites: un límite flexible y un límite duro. El límite flexible es el límite actual, y puede ser reducido o elevado con el tiempo mediante un proceso. El límite flexible nunca puede exceder el límite duro. El límite duro se puede reducir a cualquier valor mayor que el del límite flexible, pero no se puede elevar. (Solo los procesos con el UID efectivo del superusuario pueden aumentar un límite duro.)

Los recursos específicos que se pueden limitar dependen del sistema. Se describen en la página de manual getrlimit(2). Los recursos enumerados a continuación se admiten cuando el sistema operativo subyacente los admite; los recursos que no pueden ser verificados o controlados por el sistema operativo no se definen en este módulo para esas plataformas.

resource.RLIM_INFINITY

Constante utilizada para representar el límite de un recurso ilimitado.

resource.getrlimit(resource)

Retorna una tupla (soft, hard) con los límites flexible y duro actuales de resource. Genera ValueError si se especifica un recurso no válido o error si la llamada al sistema subyacente falla inesperadamente.

resource.setrlimit(resource, limits)

Establece nuevos límites para el consumo de resource. El argumento limits debe ser una tupla de dos enteros (soft, hard) que describe los nuevos límites. Un valor de RLIM_INFINITY se puede utilizar para solicitar un límite ilimitado.

Genera ValueError si se especifica un recurso no válido, si el nuevo límite flexible excede el límite duro, o si un proceso intenta aumentar el límite duro. Si se especifica un límite de RLIM_INFINITY cuando el límite duro o el límite del sistema para ese recurso no son ilimitados, se producirá un ValueError. Un proceso con el UID efectivo de superusuario puede solicitar cualquier valor de límite válido, incluso ilimitado, pero se generará un ValueError si el límite solicitado excede el límite impuesto por el sistema.

setrlimit también puede generar un error si falla la llamada al sistema subyacente.

VxWorks solo admite configurar RLIMIT_NOFILE.

Genera un auditing event resource.setrlimit con los argumentos resource, limits.

resource.prlimit(pid, resource[, limits])

Combina setrlimit() y getrlimit() en una sola función y admite obtener y establecer los límites de recursos de un proceso arbitrario. Si pid es 0, entonces la llamada se aplica al proceso actual. resource y limits tienen el mismo significado que en setrlimit(), excepto por que limits es opcional.

Cuando no se proporciona limits la función retorna el límite de resource del proceso pid. Cuando se proporciona limits, se establece el límite de resource del proceso y se retorna el límite de recursos anterior.

Genera ProcessLookupError cuando no se encuentra pid y PermissionError cuando el usuario no tiene CAP_SYS_RESOURCE para el proceso.

Genera un evento de auditoría resource.prlimit con los argumentos pid, resource, limits.

Disponibilidad: Linux 2.6.36 o posterior con glibc 2.13 o posterior.

Nuevo en la versión 3.4.

Estos símbolos definen los recursos cuyo consumo se puede controlar usando las funciones setrlimit() y getrlimit() que se describen más abajo. Los valores de estos símbolos son exactamente las constantes utilizadas por programas en C.

La página de manual de Unix para getrlimit(2) detalla los recursos disponibles. Tenga en cuenta que no todos los sistemas usan el mismo símbolo o el mismo valor para referirse al mismo recurso. Este módulo no pretende enmascarar las diferencias entre plataformas — los símbolos no definidos para una plataforma no estarán disponibles en este módulo en esa plataforma.

resource.RLIMIT_CORE

El tamaño máximo (en bytes) de un archivo central que puede crear el proceso actual. Esto podría resultar en la creación de un archivo central parcial si se requiriera uno más grande para contener la imagen del proceso entera.

resource.RLIMIT_CPU

La cantidad máxima de tiempo del procesador (en segundos) que puede utilizar un proceso. Si se excede este límite se envía una señal SIGXCPU al proceso. (Vea la documentación del módulo signal para más información sobre cómo detectar esta señal y hacer algo productivo, p. ej. descargar los archivos abiertos al disco).

resource.RLIMIT_FSIZE

El tamaño máximo de un archivo que pueda crear el proceso.

resource.RLIMIT_DATA

El tamaño máximo (en bytes) de la memoria heap del proceso.

resource.RLIMIT_STACK

El tamaño máximo (en bytes) de la pila de llamadas para el proceso actual. Esto afecta únicamente a la pila del hilo principal en un proceso multi-hilo.

resource.RLIMIT_RSS

El tamaño máximo del conjunto residente (RSS) del que puede disponer el proceso.

resource.RLIMIT_NPROC

El número máximo de procesos que puede crear el proceso actual.

resource.RLIMIT_NOFILE

El número máximo de descriptores de archivo abierto para el proceso actual.

resource.RLIMIT_OFILE

El nombre BDS para RLIMIT_NOFILE.

resource.RLIMIT_MEMLOCK

El espacio de direcciones máximo que se puede bloquear en la memoria.

resource.RLIMIT_VMEM

El área de memoria mapeada más grande que puede ocupar el proceso.

resource.RLIMIT_AS

El área máxima (en bytes) de espacio de direcciones que puede tomar el proceso.

resource.RLIMIT_MSGQUEUE

El número de bytes que se pueden asignar a las colas de mensajes POSIX.

Disponibilidad: Linux 2.6.8 o posterior.

Nuevo en la versión 3.4.

resource.RLIMIT_NICE

El techo del nivel del proceso nice (calculado como 20 - rlim_cur).

Disponibilidad: Linux 2.6.12 o posterior.

Nuevo en la versión 3.4.

resource.RLIMIT_RTPRIO

El techo de la prioridad en tiempo real.

Disponibilidad: Linux 2.6.12 o posterior.

Nuevo en la versión 3.4.

resource.RLIMIT_RTTIME

El límite de tiempo (en microsegundos) en tiempo de CPU que puede dedicar un proceso de programación en tiempo real sin hacer una llamada al sistema de bloqueo.

Disponibilidad: Linux 2.6.25 o posterior.

Nuevo en la versión 3.4.

resource.RLIMIT_SIGPENDING

El número de señales que el proceso puede poner en cola.

Disponibilidad: Linux 2.6.8 o posterior.

Nuevo en la versión 3.4.

resource.RLIMIT_SBSIZE

El tamaño máximo (en bytes) de uso del búfer del socket para este usuario. Esto limita la cantidad de memoria de red, y por lo tanto la cantidad de mbufs, que este usuario puede retener en todo momento.

Disponibilidad: FreeBSD 9 o posterior.

Nuevo en la versión 3.4.

resource.RLIMIT_SWAP

The maximum size (in bytes) of the swap space that may be reserved or used by all of this user id’s processes. This limit is enforced only if bit 1 of the vm.overcommit sysctl is set. Please see tuning(7) [https://www.freebsd.org/cgi/man.cgi?query=tuning&sektion=7] for a complete description of this sysctl.

Disponibilidad: FreeBSD 9 o posterior.

Nuevo en la versión 3.4.

resource.RLIMIT_NPTS

El número máximo de pseudo-terminales que puede crear esta ID de usuario.

Disponibilidad: FreeBSD 9 o posterior.

Nuevo en la versión 3.4.

Utilización de recursos

Estas funciones se usan para recuperar la información de utilización de recursos:

resource.getrusage(who)

Esta función retorna un objeto que describe los recursos consumidos por el proceso actual o sus elementos secundarios, según como esté especificado en el parámetro who. El parámetro who debe especificarse usando una de las constantes RUSAGE_* descritas más abajo.

Un ejemplo sencillo:

from resource import *
import time

# a non CPU-bound task
time.sleep(3)
print(getrusage(RUSAGE_SELF))

# a CPU-bound task
for i in range(10 ** 8):
   _ = 1 + 1
print(getrusage(RUSAGE_SELF))

Los campos del valor retornado describen cómo se ha utilizado un recurso específico, p. ej. la cantidad de tiempo dedicada a la ejecución en modo usuario o el número de veces que el proceso ha sido intercambiado desde la memoria principal. Algunos valores dependen del intervalo de tic del reloj, p. ej. la cantidad de memoria que está usando el proceso.

Por compatibilidad con versiones anteriores, el valor retornado es accesible también como una tupla de 16 elementos.

Los campos ru_utime y ru_stime del valor retornado son valores de coma flotante que representan la cantidad de tiempo dedicada a la ejecución en modo usuario y la cantidad de tiempo dedicada a la ejecución en modo sistema respectivamente. Los valores restantes son enteros. Consulte la página del manual getrusage(2) para información detallada sobre estos valores. A continuación se presenta un breve resumen:

Índice

Campo

Recurso

0

ru_utime

tiempo en modo usuario (flotante en segundos)

1

ru_stime

tiempo en modo sistema (flotante en segundos)

2

ru_maxrss

tamaño máximo del conjunto residente

3

ru_ixrss

tamaño de memoria compartida

4

ru_idrss

tamaño de memoria no compartida

5

ru_isrss

tamaño de la pila no compartida

6

ru_minflt

fallos de página que no requieran E/S

7

ru_majflt

fallos de página que requieran E/S

8

ru_nswap

número de intercambios

9

ru_inblock

bloque de operaciones de entrada

10

ru_oublock

bloque de operaciones de salida

11

ru_msgsnd

mensajes enviados

12

ru_msgrcv

mensajes recibidos

13

ru_nsignals

señales recibidas

14

ru_nvcsw

intercambios de contexto voluntarios

15

ru_nivcsw

intercambios de contexto involuntarios

Esta función generará un ValueError si el parámetro who especificado no es válido. También puede generar una excepción error en circunstancias inusuales.

resource.getpagesize()

Retorna el número de bytes en una página de sistema. (Esta no es necesariamente del mismo tamaño que la página de hardware).

Los siguientes símbolos RUSAGE_* se pasan a la función getrusage() para especificar qué información de procesos se debería proporcionar.

resource.RUSAGE_SELF

Pasar a getrusage() para solicitar recursos consumidos por el proceso de llamada, que es la suma de recursos utilizados por todos los hilos en el proceso.

resource.RUSAGE_CHILDREN

Pasar a getrusage() para solicitar recursos consumidos por procesos secundarios del proceso de llamada que se han terminado o a los que se les está esperando.

resource.RUSAGE_BOTH

Pasar a getrusage() para solicitar recursos consumidos por el proceso actual y sus procesos secundarios. Puede que no esté disponible en todos los sistemas.

resource.RUSAGE_THREAD

Pasa a getrusage() para solicitar recursos consumidos por el hilo actual. Puede que no esté disponible en todos los sistemas.

Nuevo en la versión 3.2.

syslog — Rutinas de la biblioteca syslog de Unix

Este módulo ofrece una interfaz a las rutinas de la biblioteca syslog de Unix. Consulte las páginas del manual de Unix para una descripción detallada de la facility (es así como se llama en la documentación a un subsistema de aplicaciones) syslog.

Este módulo envuelve la familia de rutinas de syslog. En el módulo logging.handlers está disponible SysLogHandler, una biblioteca en Python puro que puede comunicarse con un servidor syslog.

El módulo define las siguientes funciones:

syslog.syslog(message)

syslog.syslog(priority, message)

Envía la cadena de caracteres message al registrador del sistema. Se añade un final de línea si es necesario. Cada mensaje se etiqueta con una prioridad compuesta por una facility y un nivel. El argumento opcional priority, que por defecto es LOG_INFO, determina la prioridad del mensaje. Si la facility no está codificada en priority usando un OR lógico (LOG_INFO | LOG_USER), se usará el valor con el que se llama a openlog().

Si openlog() no se ha llamado antes de la llamada a syslog(), openlog() se llamará sin argumentos.

Lanza un evento de auditoría syslog.syslog con los argumentos priority, message.

syslog.openlog([ident[, logoption[, facility]]])

Las opciones de registro de las llamadas a syslog() pueden establecerse llamando a la función openlog(). syslog() llamará a openlog() sin argumentos si el registro no está abierto actualmente.

El argumento por palabra clave opcional ident es una cadena de caracteres que precede a cada mensaje, y por defecto es sys.argv[0] retirando los componentes delanteros de la ruta. El argumento nombrado opcional logoption (por defecto es 0) es un campo de tipo bit – véanse a continuación los posibles valores que pueden combinarse. El argumento nombrado opcional facility (por defecto es LOG_USER) establece una facility por defecto para mensajes que no tienen una facility explícitamente codificada.

Lanza un evento de auditoría syslog.openlog con los argumentos ident, logoption, facility.

Distinto en la versión 3.2: En versiones anteriores, los argumentos nombrados no estaban permitidos, y ident era obligatorio. El valor por defecto de ident dependía de las librerías del sistema, y a menudo era python en lugar del nombre del fichero del programa en Python.

syslog.closelog()

Reinicia los valores del módulo syslog y llama a la librería del sistema closelog().

Esto provoca que el módulo actúe como lo hacía cuando fue importado inicialmente. Por ejemplo, se llamará a openlog() en la primera llamada a syslog() (si no se ha llamado a openlog() ya), e ident y otros parámetros de openlog() se reiniciarán a sus valores por defecto.

Lanza un evento de auditoría syslog.closelog sin argumentos.

syslog.setlogmask(maskpri)

Asigna la máscara de prioridad a maskpri y retorna el valor anterior de la máscara. Las llamadas a syslog() con un nivel de prioridad no asignado en maskpri se ignoran. El comportamiento por defecto es registrar todas las prioridades. La función LOG_MASK(pri) calcula la máscara para la prioridad individual pri. La función LOG_UPTO(pri) calcula la máscara para todas las prioridades mayores o iguales que pri.

Lanza un evento de auditoría syslog.setlogmask con argumento maskpri.

El módulo define las siguientes constantes:

Niveles de prioridad (de más alto a más bajo):

LOG_EMERG, LOG_ALERT, LOG_CRIT, LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO, LOG_DEBUG.

Facilities:

LOG_KERN, LOG_USER, LOG_MAIL, LOG_DAEMON, LOG_AUTH, LOG_LPR, LOG_NEWS, LOG_UUCP, LOG_CRON, LOG_SYSLOG,de LOG_LOCAL0 a LOG_LOCAL7, y, si está definida en <syslog.h>, LOG_AUTHPRIV.

Opciones de registro:

LOG_PID, LOG_CONS, LOG_NDELAY, y, si están definidas en <syslog.h>, LOG_ODELAY, LOG_NOWAIT, y LOG_PERROR.

Ejemplos

Ejemplo sencillo

Un conjunto sencillo de ejemplos:

import syslog

syslog.syslog('Processing started')
if error:
    syslog.syslog(syslog.LOG_ERR, 'Processing started')

Un ejemplo de configuración de varias opciones de registro, que incluirán el identificador del proceso en los mensajes registrados, y escribirán los mensajes a la facility de destino usada para el registro de correo:

syslog.openlog(logoption=syslog.LOG_PID, facility=syslog.LOG_MAIL)
syslog.syslog('E-mail processing initiated...')

Módulos Reemplazados

Los módulos descritos en este capítulo se encuentran obsoletos, y sólo se conservan por compatibilidad con versiones anteriores. Han sido reemplazados por otros módulos.

aifc — Lee y escribe archivos AIFF y AIFC

asynchat — Gestor de comandos/respuestas en sockets asíncronos

Ejemplo de asynchat

asyncore — controlador de socket asincrónico

Ejemplo asyncore de cliente HTTP básico

Ejemplo asyncore de servidor de eco básico

audioop — Manipula datos de audio sin procesar

cgi — Soporte de Interfaz de Entrada Común (CGI)

Introducción

Usando el módulo CGI

Interfaz de Nivel Superior

Funciones

Preocuparse por la seguridad

Instalando su script de CGI en un sistema Unix

Probando su script de CGI

Depurando scripts de CGI

Problemas comunes y soluciones

cgitb — Administrador traceback para scripts CGI.

chunk — Lee los datos de los trozos de IFF

crypt — Función para verificar contraseñas Unix

Métodos de hashing

Atributos del módulo

Funciones del módulo

Ejemplos

:mod:”imghdr” — Determinar el tipo de imagen

imp — Acceda a import internamente

Ejemplos

mailcap — Manejo de archivos Mailcap

msilib — Leer y escribir archivos Microsoft Installer

Objetos Database

Objetos View

Objetos Summary Information

Objetos Record

Errores

Objetos CAB

Objetos Directory

Features

Clases GUI

Tablas pre-calculadas

nis — Interfaz a Sun’s NIS (Páginas amarillas)

nntplib — Protocolo de cliente NNTP

Objetos NNTP

Atributos

Métodos

Funciones de utilidad

optparse — Analizador sintáctico (parser) para opciones de línea de comandos

Contexto

Terminología

¿Qué finalidad tienen las opciones?

¿Qué finalidad tienen los argumentos posicionales?

Tutorial

Comprendiendo las acciones de opción

La acción store

Manejo de opciones booleanas (flags)

Otras acciones

Valores por defecto

Generando ayuda

Agrupando opciones

Imprimir una cadena de caracteres con la versión del programa

Cómo maneja los errores el módulo optparse

Reuniendo todas las piezas

Guía de referencia

Creando el analizador sintáctico (parser)

Completando el analizador con opciones

Definiendo las opciones

Atributos de opción

Acciones de opción estándares

Tipos de opción estándares

Analizando los argumentos

Consultar y manipular el analizador de opciones

Conflictos entre opciones

Limpieza

Otros métodos

Retrollamadas de opción

Definición de una opción con retrollamada

Cómo son invocadas las retrollamadas

Lanzando errores en una retrollamada

Ejemplo de retrollamada 1: una retrollamada trivial

Ejemplo de retrollamada 2: comprobar el orden de las opciones

Ejemplo de retrollamada 3: comprobar el orden de las opciones (generalizado)

Ejemplo de retrollamada 4: comprobar una condición arbitraria

Ejemplo de retrollamada 5: argumentos fijos

Ejemplo de retrollamada 6: argumentos variables

Extendiendo el módulo optparse

Agregando nuevos tipos

Agregando nuevas acciones

ossaudiodev — Acceso a dispositivos de audio compatibles con OSS

Objetos de dispositivo de audio

Objetos del dispositivo mezclador

pipes — Interfaz para tuberías de shell

Objetos Template

smtpd — Servidor SMTP

Objetos SMTPServer

Objetos DebuggingServer

Objetos PureProxy

Objetos MailmanProxy

Objetos SMTPChannel

sndhdr — Determinar el tipo de archivo de sonido

spwd — La base de datos de contraseñas ocultas

sunau — Lectura y escritura de ficheros Sun AU

Objetos AU_read

Objetos AU_write

telnetlib — cliente Telnet

Objetos Telnet

Ejemplo de Telnet

uu — Codifica y decodifica archivos UUEncode

xdrlib — Codificar y decodificar datos XDR

Instancias de la clase Packer

Instancias de la clase Unpacker

Excepciones

aifc — Lee y escribe archivos AIFF y AIFC

Código fuente: Lib/aifc.py [https://github.com/python/cpython/tree/3.9/Lib/aifc.py]

Obsoleto desde la versión 3.11: The aifc module is deprecated (see PEP 594 [https://www.python.org/dev/peps/pep-0594#aifc] for details).

Este módulo provee soporte para la lectura y escritura de archivos AIFF y AIFF-C. AIFF son las siglas de Formato de Intercambio de Archivos de Audio (Audio Interchange File Format), un formato para almacenar muestras de audio digital en un archivo. AIFF-C es una nueva versión del formato que incluye la habilidad de comprimir los datos de audio.

Los archivos de audio tienen una serie de parámetros que describen los datos de audio. La tasa de muestreo o tasa de fotogramas se refiere a la cantidad de veces por segundo que se toman muestras del sonido. El número de canales indica si el audio es mono, estéreo o cuadrafónico. Cada fotograma está compuesto de una muestra por canal. El tamaño de la muestra es el tamaño en bytes de cada muestra. De esta manera, un fotograma está formado por nchannels * samplesize bytes, y un segundo de audio está formado por nchannels * samplesize * framerate bytes.

Por ejemplo, el audio de calidad de CD tiene un tamaño de muestreo de 2 bytes (16 bits), usa dos canales (estéreo) y tiene una tasa de fotogramas de 44.100 fotogramas/segundo. Esto da como resultado un tamaño del fotograma de 4 bytes (2*2), y un segundo de audio en esta calidad ocupa 2*2*44.100 bytes (176.400 bytes).

El módulo aifc define a la siguiente función:

aifc.open(file, mode=None)

Abre un archivo AIFF o AIFF-C y retorna una instancia de objeto con los métodos descriptos más abajo. El argumento file puede ser tanto una cadena de caracteres nombrando a un archivo como un file object. mode debe ser 'r' o 'rb' cuando el archivo sea abierto para lectura, o 'w' o 'wb' cuando lo sea para escritura. Si este argumento se omite, se usará file.mode si es que existe; en caso contrario se usará 'rb' . Cuando se use para escribir el objeto archivo deberá ser «buscable» (seekable), a menos que se sepa por adelantado cuántas muestras se escribirán en total y use writeframesraw() and setnframes(). La función open() se puede usar dentro de una sentencia with. Cuando el bloque with se complete, se invocará al método close().

Distinto en la versión 3.4: Se agregó soporte para las sentencias with.

Los objetos que retorna open() cuando un archivo es abierto para lectura contienen los siguientes métodos:

aifc.getnchannels()

Retorna el número de canales de audio (1 para mono, 2 para estéreo).

aifc.getsampwidth()

Retorna el tamaño en bytes de cada muestra.

aifc.getframerate()

Retorna la tasa de muestreo (cantidad de fotogramas de audio por segundo).

aifc.getnframes()

Retorna el número de fotogramas de audio en el archivo.

aifc.getcomptype()

Retorna un arreglo de bytes de longitud 4 que describe el tipo de compresión usada en el archivo de audio. Para archivos AIFF, el valor que retorna es b’NONE’.

aifc.getcompname()

Retorna un arreglo de bytes con una descripción legible para humanos del tipo de compresión usada en el archivo de audio. Para archivos AIFF, el valor que retorna es b’not compressed’ (no comprimido).

aifc.getparams()

Retorna una tupla nombrada namedtuple() (nchannels, sampwidth, framerate, nframes, comptype, compname), equivalente a la salida de los métodos get*().

aifc.getmarkers()

Retorna una lista de los marcadores en el archivo de audio. Un marcador consiste de una tupla de tres elementos. El primero es el identificador de marca (mark ID, un número entero); el segundo es la posición de la marca, en fotogramas, desde el comienzo de los datos (un número entero); el tercero es el nombre de la marca (una cadena de caracteres).

aifc.getmark(id)

Retorna una tupla tal como se describe en getmarkers() para la marca con el id dado.

aifc.readframes(nframes)

Lee y retorna los nframes fotogramas siguientes del archivo de audio. Los datos los retorna como una cadena de caracteres que contiene, por cada fotograma, las muestras sin comprimir de todos los canales.

aifc.rewind()

Rebobina el puntero de lectura. La próxima ejecución de readframes() comenzará desde el comienzo del archivo.

aifc.setpos(pos)

Busca el número de fotograma especificado.

aifc.tell()

Retorna el número de fotograma actual.

aifc.close()

Cierra el archivo AIFF. Después de invocar este método, el objeto no puede usarse más.

Cuando un archivo se abre para escritura, los objetos que retorna open() poseen todos los métodos mencionados más arriba, excepto readframes() y setpos(). Adicionalmente se incluyen los métodos abajo descriptos. Los métodos get*() sólo pueden ser invocados después de haber invocado su correspondiente método set*(). Antes de invocar por primera vez writeframes() o writeframesraw(), todos los parámetros -excepto el número de fotogramas- deben estar completos.

aifc.aiff()

Crea un archivo AIFF. Por defecto se crea un archivo AIFF-C, excepto que el nombre del archivo termine en '.aiff', en cuyo caso se creará un archivo AIFF.

aifc.aifc()

Crea un archivo AIFF-C. La acción por defecto es que cree un archivo AIFF-C, excepto que el nombre del archivo termine en '.aiff', en cuyo caso se crea por defecto un archivo AIFF.

aifc.setnchannels(nchannels)

Especifica el número de canales en el archivo de audio.

aifc.setsampwidth(width)

Especifica el tamaño en bytes de las muestras de audio.

aifc.setframerate(rate)

Especifica la frecuencia de muestreo en fotogramas por segundo.

aifc.setnframes(nframes)

Especifica el número de fotogramas que se escribirán en el archivo de audio. Si este parámetro no es definido, o si no se lo define correctamente, el archivo necesitará soporte de búsqueda (seeking).

aifc.setcomptype(type, name)

Especifica el tipo de compresión. Si no es especificada, los datos de audio no serán comprimidos. En los archivos AIFF la compresión no está disponible. El parámetro de nombre name deberá ser una descripción del tipo de compresión legible por humanos, en forma de un arreglo de bytes. El parámetro de tipo type deberá ser un arreglo de bytes de longitud 4. Actualmente se soportan los siguientes tipos de compresión: b'NONE', b'ULAW', b'ALAW', b'G722'.

aifc.setparams(nchannels, sampwidth, framerate, comptype, compname)

Establece de una vez todos los parámetros mostrados arriba. El argumento es una tupla compuesta por estos parámetros. Esto quiere decir que es posible usar el resultado de una llamada getparams() como argumento para setparams().

aifc.setmark(id, pos, name)

Agrega una marca con el identificador id dado (mayor a 0) y el nombre name dado, en la posición pos dada. Este método se puede invocar en cualquier momento antes de close().

aifc.tell()

Retorna la posición de escritura actual en el archivo de salida. Es útil en combinación con setmark().

aifc.writeframes(data)

Escribe los datos al archivo de salida. Este método sólo se puede invocar una vez establecidos los parámetros del archivo de audio.

Distinto en la versión 3.4: Acepta cualquier bytes-like object.

aifc.writeframesraw(data)

Funciona igual que writeframes(), excepto que el encabezado del archivo de audio no es actualizado.

Distinto en la versión 3.4: Acepta cualquier bytes-like object.

aifc.close()

Cierra el archivo AIFF. El encabezado del archivo se actualiza para reflejar el tamaño real de los datos de audio. Después de invocar a este método, el objeto no puede usarse más.

asynchat — Gestor de comandos/respuestas en sockets asíncronos

Código fuente: Lib/asynchat.py [https://github.com/python/cpython/tree/3.9/Lib/asynchat.py]

Obsoleto desde la versión 3.6: asynchat will be removed in Python 3.12 (see PEP 594 [https://www.python.org/dev/peps/pep-0594#asynchat] for details). Please use asyncio instead.

Nota

Este módulo existe únicamente por motivos de retrocompatibilidad. Para nuevo código, es recomendable usar asyncio.

Este módulo se construye en la infraestructura de asyncore, simplificando los clientes y servidores asíncronos y facilitando la gestión de protocolos cuyos elementos son terminados por cadenas de texto arbitrarias, o que son de longitud variable. asynchat define la clase abstracta async_chat de la que se debe heredar, implementado los métodos collect_incoming_data() y found_terminator(). Utiliza el mismo bucle asíncrono que asyncore, y los dos tipos de canal, asyncore.dispatcher y asynchat.async_chat, se pueden mezclar libremente en el mapa de canal. Normalmente un canal de servidor asyncore.dispatcher genera nuevos objetos de canal asynchat.async_chat, al recibir peticiones de conexión entrantes.

class asynchat.async_chat

Esta clase es una subclase abstracta de asyncore.dispatcher. Para el uso práctico del código se debe heredar async_chat, definiendo los métodos significativos collect_incoming_data() y found_terminator(). Los métodos de asyncore.dispatcher se pueden utilizar, aunque no todos tienen sentido en un contexto de mensaje/respuesta.

Al igual que asyncore.dispatcher, async_chat define una serie de eventos generados por un análisis sobre las condiciones de _socket_, tras una llamada a select(). Una vez que el bucle de _polling_ haya sido iniciado, los métodos de los objetos async_chat son llamados por el _framework_ que procesa los eventos, sin que tengamos que programar ninguna acción a mayores.

Se pueden modificar dos atributos de clase, para mejorar el rendimiento o incluso hasta para ahorrar memoria.

ac_in_buffer_size

El tamaño del _buffer_ de entrada asíncrona (por defecto 4096).

ac_out_buffer_size

El tamaño del _buffer_ de salida asíncrona (por defecto 4096).

Al contrario que asyncore.dispatcher, async_chat permite definir una cola FIFO de productores (producers). Un productor necesita tener un solo método, more(), que debe devolver los datos que se vayan a transmitir en el canal. Cuando el método more() devuelve un objeto bytes vacío, significa que el productor ya se ha agotado (por ejemplo, que no contiene más datos). En este punto, el objeto async_chat elimina el productor de la cola y empieza a usar el siguiente productor, si existiese. Cuando la cola de productores está vacía, el método handle_write() no hace nada. El método set_terminator() de los objetos de canal se utiliza para describir cómo reconocer, en una transmisión entrante desde el punto remoto, el final de esta transmisión o un punto de ruptura importante en la misma.

Para construir una subclase funcional de async_chat, los métodos de entrada collect_incoming_data() and found_terminator() deben tratar los datos que el canal recibe asíncronamente. Los métodos se describen a continuación.

async_chat.close_when_done()

Añade un None en la cola de productores. Cuando este productor se extrae de la cola, hace que el canal se cierre.

async_chat.collect_incoming_data(data)

Llamado con data, conteniendo una cantidad arbitraria de datos recibidos. El método por defecto, que debe ser reemplazado, lanza una excepción NotImplementedError.

async_chat.discard_buffers()

En situaciones de emergencia, este método descarta cualquier dato albergado en los búfers de entrada y/o salida y en la cola del productor.

async_chat.found_terminator()

Llamado cuando el flujo de datos de entrada coincide con la condición de finalización establecida por set_terminator(). El método por defecto, que debe ser reemplazado, lanza una excepción NotImplementedError. Los datos de entrada en búfer deberían estar disponibles a través de un atributo de instancia.

async_chat.get_terminator()

Retorna el terminador actual del canal.

async_chat.push(data)

Añade datos en la cola del canal para asegurarse de su transmisión. Esto es todo lo que se necesita hacer para que el canal envíe los datos a la red, aunque es posible usar productores personalizados en esquemas más complejos para implementar características como encriptación o fragmentación.

async_chat.push_with_producer(producer)

Obtiene un objeto productor y lo añade a la cola de productores asociada al canal. Cuando todos los productores añadidos actualmente han sido agotados, el canal consumirá los datos de este productor llamando al método more(), y enviando los datos al punto remoto.

async_chat.set_terminator(term)

Establece la condición de finalización que será reconocida en este canal. term puede ser uno de los tres tipos de valores posibles, correspondientes a tres formas diferentes de tratar los datos de protocolo entrantes.

término

Descripción

string

Llamará a found_terminator() cuando la cadena de caracteres se encuentre en el flujo de datos de entrada

integer

Llamará a found_terminator() cuando el número de caracteres indicado se haya recibido

None

El canal continúa recopilando datos indefinidamente

Téngase en cuenta que cualquier dato posterior al terminador estará disponible para ser leído por el canal después de llamar a found_terminator().

Ejemplo de asynchat

El siguiente ejemplo parcial muestra cómo se pueden leer peticiones HTTP con async_chat. Un servidor web podría crear un objeto http_request_handler para cada conexión de cliente entrante. Téngase en cuenta que, inicialmente, el terminador del canal está configurado para detectar la línea vacía presente al final de las cabeceras HTTP, y una bandera indica que las cabeceras se están leyendo.

Una vez que las cabeceras se hayan leído, si la petición es de tipo POST (lo cual indica que hay más datos disponibles en el flujo de entrada), la cabecera Content-Length: se utiliza para establecer un terminador numérico para leer la cantidad de datos correcta en el canal.

El método handle_request() se llama una vez todas las entradas relevantes han sido serializadas (marshalled), tras establecer el terminador del canal a None para asegurarse de que cualquier dato extraño enviado por el cliente web es ignorado.

import asynchat

class http_request_handler(asynchat.async_chat):

    def __init__(self, sock, addr, sessions, log):
        asynchat.async_chat.__init__(self, sock=sock)
        self.addr = addr
        self.sessions = sessions
        self.ibuffer = []
        self.obuffer = b""
        self.set_terminator(b"\r\n\r\n")
        self.reading_headers = True
        self.handling = False
        self.cgi_data = None
        self.log = log

    def collect_incoming_data(self, data):
        """Buffer the data"""
        self.ibuffer.append(data)

    def found_terminator(self):
        if self.reading_headers:
            self.reading_headers = False
            self.parse_headers(b"".join(self.ibuffer))
            self.ibuffer = []
            if self.op.upper() == b"POST":
                clen = self.headers.getheader("content-length")
                self.set_terminator(int(clen))
            else:
                self.handling = True
                self.set_terminator(None)
                self.handle_request()
        elif not self.handling:
            self.set_terminator(None)  # browsers sometimes over-send
            self.cgi_data = parse(self.headers, b"".join(self.ibuffer))
            self.handling = True
            self.ibuffer = []
            self.handle_request()

asyncore — controlador de socket asincrónico

Código fuente: Lib/asyncore.py [https://github.com/python/cpython/tree/3.9/Lib/asyncore.py]

Obsoleto desde la versión 3.6: asyncore will be removed in Python 3.12 (see PEP 594 [https://www.python.org/dev/peps/pep-0594#asyncore] for details). Please use asyncio instead.

Nota

Este módulo solo existe para compatibilidad con versiones anteriores. Para el nuevo código recomendamos usar asyncio.

Este módulo proporciona la infraestructura básica para escribir servicio de socket asincrónicos, clientes y servidores.

Sólo hay dos maneras de que un programa en un solo procesador haga «más de una cosa a la vez». La programación multiproceso es la forma más sencilla y popular de hacerlo, pero hay otra técnica muy diferente, que le permite tener casi todas las ventajas de multiproceso, sin usar realmente varios subprocesos. Es realmente sólo práctico si su programa está en gran parte limitado por el I/O. Si el programa está limitado por el procesador, los subprocesos programados preventivos son probablemente lo que realmente necesita. Sin embargo, los servidores de red rara vez están limitado al procesador.

Si su sistema operativo es compatible con la llamada del sistema select() en su biblioteca de I/O (y casi todos lo son), puede usarla para hacer malabares con varios canales de comunicación a la vez; haciendo otro trabajo mientras su I/O está teniendo lugar en el «fondo». Aunque esta estrategia puede parecer extraña y compleja, especialmente al principio, es en muchos sentidos más fácil de entender y controlar que la programación multiproceso. El módulo asyncore resuelve muchos de los problemas difíciles para usted, haciendo que la tarea de construir sofisticados servidores de red de alto rendimiento y clientes sea fácil. Para aplicaciones y protocolos «conversacionales», el módulo complementario asynchat es invaluable.

La idea básica detrás de ambos módulos es crear uno o más canales de red, instancias de clase asyncore.dispatcher y asynchat.async_chat. La creación de los canales los agrega a un mapa global, utilizado por la función loop() si no lo proporciona con su propio map.

Una vez creados los canales iniciales, llamar a la función loop() activa el servicio de canal, que continúa hasta que se cierra el último canal (incluido el que se ha agregado al mapa durante el servicio asincrónico).

asyncore.loop([timeout[, use_poll[, map[, count]]]])

Ingresa un bucle de sondeo que termina después de que se hayan cerrado los pases de conteo o todos los canales abiertos. Todos los argumentos son opcionales. El parámetro count tiene como valor predeterminado None, lo que da como resultado que el bucle termine solo cuando se hayan cerrado todos los canales. El argumento timeout establece el parámetro de tiempo de espera para la llamada adecuada a select() o poll(), medida en segundos; el valor predeterminado es 30 segundos. El parámetro use_poll, si es true, indica que poll() debe utilizarse en lugar de select() (el valor predeterminado es False).

El parámetro map es un diccionario cuyos elementos son los canales a observar. A medida que se cierran los canales, se eliminan del mapa. Si se omite map, se utiliza un mapa global. Los canales (instancias de asyncore.dispatcher, asynchat.async_chat y subclases de los mismos) se pueden mezclar libremente en el mapa.

class asyncore.dispatcher

La clase dispatcher es un contenedor fino alrededor de un objeto de socket de bajo nivel. Para hacerlo más útil, tiene algunos métodos para el control de eventos que se llaman desde el bucle asincrónico. De lo contrario, se puede tratar como un objeto de socket normal sin bloqueo.

La activación de eventos de bajo nivel en determinados momentos o en determinados estados de conexión indica al bucle asincrónico que se han producido ciertos eventos de nivel superior. Por ejemplo, si hemos pedido un socket para conectarse a otro host, sabemos que la conexión se ha realizado cuando el socket se vuelve grabable por primera vez (en este punto sabe que puede escribir a él con la expectativa de éxito). Los eventos de nivel superior implícitos son:

Evento

Descripción

handle_connect()

Implícito en el primer proceso de lectura o escritura

handle_close()

Implícito en un evento de lectura sin datos disponibles

handle_accepted()

Implícito en un evento de lectura en un socket de escucha

Durante el procesamiento asincrónico, se utilizan los métodos readable() y writable() de cada canal asignado para determinar si el socket del canal deberían ser agregados a la lista de canales seleccionados o encuestados para eventos de lectura y escritura.

Por lo tanto, el conjunto de eventos de canal es mayor que los eventos básicos del socket. El conjunto completo de métodos que se pueden invalidar en la subclase es el siguiente:

handle_read()

Se llama cuando el bucle asincrónico detecta que una llamada read() en el socket del canal tendrá éxito.

handle_write()

Se llama cuando el bucle asincrónico detecta que se puede escribir un socket grabable. A menudo, este método implementará el almacenamiento en búfer necesario para el rendimiento. Por ejemplo:

def handle_write(self):
    sent = self.send(self.buffer)
    self.buffer = self.buffer[sent:]

handle_expt()

Se llama cuando hay datos fuera de banda (OOB) para una conexión de socket. Esto casi nunca sucederá, ya que OOB es tenuemente compatible y rara vez se utiliza.

handle_connect()

Se llama cuando el socket del abridor activo realmente hace una conexión. Puede enviar un banner de «bienvenido» o iniciar una negociación de protocolo con el punto de conexión remoto, por ejemplo.

handle_close()

Se llama cuando el socket está cerrado.

handle_error()

Se llama cuando se genera una excepción y no se controla de otro modo. La versión predeterminada imprime un traceback condensado.

handle_accept()

Se llama en los canales de escucha (abridores pasivos) cuando se puede establecer una conexión con un nuevo punto de conexión remoto que ha emitido una llamada connect() para el punto de conexión local. En desuso en la versión 3.2; use handle_accepted() en su lugar.

Obsoleto desde la versión 3.2.

handle_accepted(sock, addr)

Se llama en los canales de escucha (abridores pasivos) cuando se ha establecido una conexión con un nuevo punto de conexión remoto que ha emitido una llamada connect() para el punto de conexión local. sock es un objeto de socket new utilizable para enviar y recibir datos en la conexión, y addr es la dirección enlazada al socket en el otro extremo de la conexión.

Nuevo en la versión 3.2.

readable()

Se llama en cada momento alrededor del bucle asincrónico para determinar si se debe agregar el socket de un canal a la lista en la que se pueden producir eventos de lectura. El método predeterminado simplemente retorna True, lo que indica que, de forma predeterminada, todos los canales estarán interesados en eventos de lectura.

writable()

Se llama cada vez alrededor del bucle asincrónico para determinar si se debe agregar el socket de un canal a la lista en la que se pueden producir eventos de escritura. El método predeterminado simplemente retorna True, lo que indica que, de forma predeterminada, todos los canales estarán interesados en eventos de escritura.

Además, cada canal delega o extiende muchos de los métodos de socket. La mayoría de estos son casi idénticos a sus socios de socket.

create_socket(family=socket.AF_INET, type=socket.SOCK_STREAM)

Esto es idéntico a la creación de un socket normal y usará las mismas opciones para la creación. Consulte la documentación socket para obtener información sobre la creación de sockets.

Distinto en la versión 3.3: Los argumentos family y type se pueden omitir.

connect(address)

Al igual que con el objeto de socket normal, address es una tupla con el primer elemento al que se va a conectar el host y el segundo el número de puerto.

send(data)

Envía data al punto final remoto del socket.

recv(buffer_size)

Lee como máximo los bytes buffer_size desde el punto final remoto del socket. Un objeto bytes vacío implica que el canal se ha cerrado desde el otro extremo.

Tenga en cuenta que recv() puede elevar BlockingIOError, aunque select.select() o select.poll() ha informado del socket listo para la lectura.

listen(backlog)

Escucha las conexiones realizadas al socket. El argumento backlog especifica el número máximo de conexiones en cola y debe ser al menos 1; el valor máximo depende del sistema (normalmente 5).

bind(address)

Enlaza el socket a address. El socket no debe estar enlazado ya. (El formato de address depende de la familia de direcciones — consulte la documentación socket para obtener más información.) Para marcar el socket como reutilizable (estableciendo la opción SO_REUSEADDR), llame al método set_reuse_addr() del objeto dispatcher.

accept()

Acepta una conexión. El socket debe estar enlazado a una dirección y escuchar las conexiones. El valor retornado puede ser None o un par (conn, address) donde conn es un objeto de socket new utilizable para enviar y recibir datos en la conexión, y address es la dirección enlazada al socket en el otro extremo de la conexión. Cuando se retorna None significa que la conexión no se llevó a cabo, en cuyo caso el servidor debe ignorar este evento y seguir escuchando otras conexiones entrantes.

close()

Cierra el socket. Se producirá un error en todas las operaciones futuras en el objeto de socket. El punto final remoto no recibirá más datos (después de vaciar los datos en cola). Los sockets se cierran automáticamente cuando se recogen como elementos no utilizados.

class asyncore.dispatcher_with_send

Una subclase dispatcher que agrega capacidad de salida almacenada en búfer simple, útil para clientes simples. Para un uso más sofisticado, utilice asynchat.async_chat.

class asyncore.file_dispatcher

Un file_dispatcher toma un descriptor de archivo o file object junto con un argumento de mapa opcional y lo ajusta para su uso con las funciones poll() o loop(). Si se proporciona un objeto de archivo o cualquier cosa con un método fileno(), ese método se llamará y se pasará al constructor file_wrapper.

Disponibilidad: Unix.

class asyncore.file_wrapper

Un file_wrapper toma un descriptor de archivo entero y llama a os.dup() para duplicar el identificador de modo que el identificador original se pueda cerrar independientemente del file_wrapper. Esta clase implementa métodos suficientes emulando un socket para su uso por la clase file_dispatcher.

Disponibilidad: Unix.

Ejemplo asyncore de cliente HTTP básico

Aquí hay una llamada básica al cliente HTTP que usa la clase dispatcher para implementar su controlador de socket:

import asyncore

class HTTPClient(asyncore.dispatcher):

    def __init__(self, host, path):
        asyncore.dispatcher.__init__(self)
        self.create_socket()
        self.connect( (host, 80) )
        self.buffer = bytes('GET %s HTTP/1.0\r\nHost: %s\r\n\r\n' %
                            (path, host), 'ascii')

    def handle_connect(self):
        pass

    def handle_close(self):
        self.close()

    def handle_read(self):
        print(self.recv(8192))

    def writable(self):
        return (len(self.buffer) > 0)

    def handle_write(self):
        sent = self.send(self.buffer)
        self.buffer = self.buffer[sent:]

client = HTTPClient('www.python.org', '/')
asyncore.loop()

Ejemplo asyncore de servidor de eco básico

Aquí hay un servidor de eco básico que utiliza la clase dispatcher para aceptar conexiones y distribuye las conexiones entrantes a un controlador:

import asyncore

class EchoHandler(asyncore.dispatcher_with_send):

    def handle_read(self):
        data = self.recv(8192)
        if data:
            self.send(data)

class EchoServer(asyncore.dispatcher):

    def __init__(self, host, port):
        asyncore.dispatcher.__init__(self)
        self.create_socket()
        self.set_reuse_addr()
        self.bind((host, port))
        self.listen(5)

    def handle_accepted(self, sock, addr):
        print('Incoming connection from %s' % repr(addr))
        handler = EchoHandler(sock)

server = EchoServer('localhost', 8080)
asyncore.loop()

audioop — Manipula datos de audio sin procesar

Obsoleto desde la versión 3.11: The audioop module is deprecated (see PEP 594 [https://www.python.org/dev/peps/pep-0594#audioop] for details).

El módulo audioop contiene algunas operaciones útiles sobre fragmentos de sonido. Opera en fragmentos de sonido que consisten en muestras de enteros de 8, 16, 24, o 32 bits, guardados en objetos parecidos a bytes. Todos los elementos escalares son enteros, a menos que se especifique lo contrario.

Distinto en la versión 3.4: La compatibilidad para muestras de 24-bit fue añadida. Todas las funciones ahora aceptan cualquier bytes-like object. La entrada de cadenas de caracteres ahora resulta en un error inmediato.

Este módulo proporciona compatibilidad con las codificaciones a-LAW, u-LAW e Intel/DVI ADPCM.

Algunas de las operaciones más complicadas sólo toman muestras de 16-bit, si no, el tamaño de la entrada (en bytes) siempre es un parámetro de la operación.

El módulo define las siguientes variables y funciones:

exception audioop.error

Esta excepción es lanzada en todos los errores, tal como números desconocidos de bytes por entrada, etc.

audioop.add(fragment1, fragment2, width)

Retorna un fragmento que es la adición de dos entradas pasadas como parámetros. width es la longitud de la muestra en bytes, o 1, 2, 3, o 4. Ambos fragmentos deben tener la misma longitud. Las muestras son truncadas en caso de desbordamiento.

audioop.adpcm2lin(adpcmfragment, width, state)

Decodifica un fragmento codificado con Intel/DVI ADPCM en un fragmento lineal. Véase la descripción de lin2adpcm() por detalles sobre la codificación ADPCM. Retorna una tupla (sample, newstate) donde la entrada tiene la longitud especificada en width.

audioop.alaw2lin(fragment, width)

Convierte los fragmentos de sonido codificados con a-LAW en fragmentos de sonido linealmente codificados. La codificación a-LAW siempre usa muestras de 8 bits, por lo que width hace referencia sólo a la longitud de la entrada del fragmento de salida aquí.

audioop.avg(fragment, width)

Retorna el promedio de todas las muestras en el fragmento.

audioop.avgpp(fragment, width)

Retorna el promedio del valor de pico a pico de todas las muestras en el fragmento. No se hace ningún filtrado, por lo que la utilidad de esta rutina es cuestionable.

audioop.bias(fragment, width, bias)

Retorna un fragmento que es el fragmento original con un bias añadido a cada muestra. Las muestras se envuelven en caso de desbordamiento.

audioop.byteswap(fragment, width)

Intercambia los bytes («Byteswap») de todas las muestras en un fragmento y retorna el fragmento modificado. Convierte muestras big-endian en little-endian y viceversa.

Nuevo en la versión 3.4.

audioop.cross(fragment, width)

Retorna el número de cruces por 0 en el fragmento pasado como un argumento.

audioop.findfactor(fragment, reference)

Retorna un factor F tal que rms(add(fragment, mul(reference, -F))) sea mínimo, i.e., retorna el factor con el cual debes multiplicar la reference para hacerlo coincidir tanto como sea posible a fragment. Los fragmentos deben contener muestras de 2-byte.

El tiempo tomado por esta rutina es proporcional a len(fragment.

audioop.findfit(fragment, reference)

Intenta hacer coincidir reference tanto bien como sea posible a un fragment (que debe ser el fragmento más largo). Esto es (conceptualmente) hecho al tomar segmentos de fragment, usando findfactor() para computar la mejor coincidencia, y minimizando el resultado. Los fragmentos deben contener muestras de 2-byte. Retorna una tupla (offset, factor) donde offset (entero) es el offset en fragment donde la coincidencia más óptima empezó y factor es el (número flotante) factor según findfactor().

audioop.findmax(fragment, length)

Inspecciona fragment por un segmento de longitud length muestras (¡no bytes!) con la energía máxima, i.e., retorna i por el cual rms(fragment[i*2:(i+length)*2]) es máximo. Los fragmentos deben contener muestras de 2 bytes.

La rutina tarda proporcionalmente a len(fragment).

audioop.getsample(fragment, width, index)

Retorna el valor de la muestra index del fragmento.

audioop.lin2adpcm(fragment, width, state)

Convierte las muestras en codificaciones Intel/DVI ADPCM de 4 bits. La codificación ADPCM es un esquema de codificación adaptativo a través del cual cada número de 4 bits es la diferencia entre una muestra y la siguiente, dividido por un paso (inconsistente). El algoritmo de Intel/DVI ADPCM ha sido seleccionado para su uso por el IMA, por lo que bien puede convertirse en un estándar.

state es una tupla que contiene el estado del codificador. El codificador retorna una tupla (adpcmfrag, newstate), y el newstate debe pasarse a la siguiente llamada de lin2adpcm(). En la llamada inicial, se puede pasar None como estado. adpcmfrag es el fragmento codificado ADPCM empaquetado 2 valores de 4 bits por byte.

audioop.lin2alaw(fragment, width)

Convierte las muestras en el fragmento de audio en una codificación a-LAW y los retorna como un objeto de bytes. a-LAW es un formato de codificación de audio a través del cual obtienes un rango dinámico de cerca de 13 bits usando sólo muestras de 8 bits. Es usado por el hardware de audio Sun, entre otros.

audioop.lin2lin(fragment, width, newwidth)

Convierte muestras entre formatos de 1, 2, 3, y 4 bytes.

Nota

En algunos formatos de audio, como archivos .WAV, las entradas de 16, 24, y 32 bits tienen signo, pero las entradas de 8 bits no tienen signo. Por lo que cuando se convierta en entradas de 8 bits para estas entradas, también necesitas añadir 128 al resultado:

new_frames = audioop.lin2lin(frames, old_width, 1)
new_frames = audioop.bias(new_frames, 1, 128)

Lo mismo, al revés, tiene que ser aplicado cuando se convierta muestras de 8 bits en muestras de 16, 24, o 32 bits.

audioop.lin2ulaw(fragment, width)

Convierte muestras en el fragmento de audio en codificaciones u-LAW y lo retorna como un objeto de bytes. u-LAW es un formato de codificación de audio a través del cual obtienes un rango dinámico de cerca de 14 bits usando sólo muestras de 8 bits. Es usado por el hardware de audio Sun, entre otros.

audioop.max(fragment, width)

Retorna el máximo de los valores absolutos de las entradas en un fragmento.

audioop.maxpp(fragment, width)

Retorna el valor de pico a pico máximo en el fragmento de sonido.

audioop.minmax(fragment, width)

Retorna una tupla que consiste de los valores mínimos y máximos de todas las entradas en el fragmento de sonido.

audioop.mul(fragment, width, factor)

Retorna un fragmento que tiene todas las entradas en el fragmento original multiplicado por el valor de punto flotante factor. Las muestras son truncadas en caso de desbordamiento.

audioop.ratecv(fragment, width, nchannels, inrate, outrate, state[, weightA[, weightB]])

Convierte el ratio de fotogramas del fragmento de entrada.

state es una tupla que contiene el estado del convertidor. El convertidor retorna una tupla (newfragment, newstate), y newstate debe ser pasado a la siguiente llamada de ratecv(). La llamada inicial debe pasar None como el estado.

Los argumentos weightA y weightB son parámetros para un filtro digital simple y sus valores por defecto son 1 y 0 respectivamente.

audioop.reverse(fragment, width)

Invierte las entradas en un fragmento y retorna el fragmento modificado.

audioop.rms(fragment, width)

Retorna la media cuadrática del fragmento, i.e. sqrt(sum(S_i^2)/n).

Este es una medida del poder en una señal de audio.

audioop.tomono(fragment, width, lfactor, rfactor)

Convierte un fragmento estéreo en una fragmento mono. El canal izquierdo es multiplicado por Ifactor y el derecho por rfactor antes de añadir los dos canales para dar una señal mono.

audioop.tostereo(fragment, width, lfactor, rfactor)

Genera un fragmento estéreo de un fragmento mono. Cada par de muestras en el fragmento estéreo son computados de la entrada mono, a través del cual las muestras del canal izquierdo son multiplicadas por Ifactor y del canal derecho por rfactor.

audioop.ulaw2lin(fragment, width)

Convierte los fragmentos de sonido en codificaciones u-LAW en fragmentos de sonidos linealmente codificados. Las codificaciones u-LAW siempre usan muestras de 8 bits, por lo que width hace referencia a la longitud de la muestra del fragmento de salida aquí.

Note que operaciones tales como mul() o max() no hacen distinción entre fragmentos mono y estéreo, i.e. todas las muestras son tratadas iguales. Si este es un problema, el fragmento estéreo debe ser dividido en dos fragmentos mono primero y recombinado después. Aquí hay un ejemplo de como hacerlo:

def mul_stereo(sample, width, lfactor, rfactor):
    lsample = audioop.tomono(sample, width, 1, 0)
    rsample = audioop.tomono(sample, width, 0, 1)
    lsample = audioop.mul(lsample, width, lfactor)
    rsample = audioop.mul(rsample, width, rfactor)
    lsample = audioop.tostereo(lsample, width, 1, 0)
    rsample = audioop.tostereo(rsample, width, 0, 1)
    return audioop.add(lsample, rsample, width)

Si usas el codificador ADPCM para construir paquetes de redes y quieres que tu protocolo no tenga estado (stateless) (i.e. para ser capaz de tolerar pérdida de paquetes) no sólo debes transmitir los datos pero también el estado. Note que debes enviar el estado inicial (initial) (el que pasas a lin2adpcm()) junto con el decodificador, no el estado final (como es retornado por el codificador). Si quieres usar un struct.Struct para almacenar el estado en binario puedes codificar el primer elemento (el valor predicho) en 16 bits y el segundo (el índice delta) en 8.

Los codificadores ADPCM nunca se han probado en contra de otros codificadores ADPCM, sólo contra ellos mismos. Bien puede ser que malinterpreté los estándares en cuyo caso ellos no serán interoperables con los estándares respectivos.

La rutinas find*() pueden parecer un poco raras a primera vista. Sirven principalmente para hacer echo de la cancelación. Una manera razonablemente rápida para hacerlo es coger la pieza más energética de la muestra de la salida, localizarla en la muestra de la entrada y substraer la muestra de la salida completa de la muestra de entrada:

def echocancel(outputdata, inputdata):
    pos = audioop.findmax(outputdata, 800)    # one tenth second
    out_test = outputdata[pos*2:]
    in_test = inputdata[pos*2:]
    ipos, factor = audioop.findfit(in_test, out_test)
    # Optional (for better cancellation):
    # factor = audioop.findfactor(in_test[ipos*2:ipos*2+len(out_test)],
    #              out_test)
    prefill = '\0'*(pos+ipos)*2
    postfill = '\0'*(len(inputdata)-len(prefill)-len(outputdata))
    outputdata = prefill + audioop.mul(outputdata, 2, -factor) + postfill
    return audioop.add(inputdata, outputdata, 2)

cgi — Soporte de Interfaz de Entrada Común (CGI)

Código fuente: Lib/cgi.py [https://github.com/python/cpython/tree/3.9/Lib/cgi.py]

Obsoleto desde la versión 3.11: The cgi module is deprecated (see PEP 594 [https://www.python.org/dev/peps/pep-0594#cgi] for details and alternatives).

Módulo de soporte para scripts de la Interfaz de Entrada Común (CGI)

Este módulo define una serie de utilidades para el uso de scripts CGI escritos en Python.

Introducción

Un script de CGI es invocado por un servidor HTTP, generalmente para procesar entradas de usuario entregadas mediante un elemento HTML <FORM> o <ISINDEX>.

Muy a menudo, los scripts CGI viven en el directorio especial cgi-bin del servidor. El servidor HTTP coloca todo tipo de información sobre la solicitud (como el nombre de host del cliente, la dirección URL solicitada, la cadena de búsqueda (query string) y muchas otras consultas) en el entorno de shell del script, ejecuta el script y envía la salida del script al cliente.

La entrada del script también está conectada al cliente, y a veces los datos del formulario se leen de esta manera; en otras ocasiones los datos del formulario se pasan a través de la parte «cadena de caracteres de búsqueda (query string)» de la dirección URL. Este módulo está diseñado para ocuparse de los diferentes casos y proporcionar una interfaz más simple al script de Python. También proporciona una serie de utilidades que ayudan en la depuración de scripts, y la última adición es la compatibilidad con cargas de archivos desde un formulario (si el navegador lo admite).

La salida de un script CGI debe constar de dos secciones, separadas por una línea en blanco. La primera sección contiene una serie de encabezados, indicando al cliente qué tipo de datos sigue. El código de Python para generar una sección de encabezado mínima tiene este aspecto:

print("Content-Type: text/html")    # HTML is following
print()                             # blank line, end of headers

La segunda sección suele ser HTML, lo que permite al software cliente mostrar texto bien formateado con encabezado, imágenes en línea, etc. Aquí está el código Python que imprime una simple pieza de HTML:

print("<TITLE>CGI script output</TITLE>")
print("<H1>This is my first CGI script</H1>")
print("Hello, world!")

Usando el módulo CGI

Empieza escribiendo import cgi.

Cuando escribas un nuevo script, considera añadir estas líneas:

import cgitb
cgitb.enable()

Esto activa un manejador de excepciones especial que mostrará informes detallados en el explorador Web si se produce algún error. Si prefiere no mostrar en detalle su programa a los usuarios de su script, puede tener los informes guardados en archivos en su lugar, con código como este:

import cgitb
cgitb.enable(display=0, logdir="/path/to/logdir")

Es muy útil usar esta característica durante el desarrollo de scripts. Los informes producidos por cgitb proporcionan información que puede ahorrarle mucho tiempo en el seguimiento de errores. Siempre puede eliminar la línea cgitb más adelante cuando haya probado su script y esté seguro de que funciona correctamente.

To get at submitted form data, use the FieldStorage class. If the form contains non-ASCII characters, use the encoding keyword parameter set to the value of the encoding defined for the document. It is usually contained in the META tag in the HEAD section of the HTML document or by the Content-Type header. This reads the form contents from the standard input or the environment (depending on the value of various environment variables set according to the CGI standard). Since it may consume standard input, it should be instantiated only once.

La instancia FieldStorage puede ser indexada como un diccionario Python. Permite las pruebas de afiliación con el operador in, y también es compatible con el método de diccionario estándar keys() y la función incorporada len(). Los campos de formulario que contienen cadenas de caracteres vacías son ignoradas y no aparecen en el diccionario; para mantener estos valores, proporciona un valor verdadero para el parámetro de palabra clave opcional keep_blank_values al crear la instancia FieldStorage.

Por ejemplo, el código siguiente (que supone que el encabezado Content-Type y la línea en blanco ya se han impreso) comprueba que los campos name y addr son ambos establecidos a una cadena de caracteres no vacía:

form = cgi.FieldStorage()
if "name" not in form or "addr" not in form:
    print("<H1>Error</H1>")
    print("Please fill in the name and addr fields.")
    return
print("<p>name:", form["name"].value)
print("<p>addr:", form["addr"].value)
...further form processing here...

Aquí los campos, a los que se accede a través de form[key], son por sí mismos las instancias de FieldStorage (o MiniFieldStorage, dependiendo de la codificación del formulario). El atributo value de la instancia produce el valor de cadena de caracteres del campo. El método getvalue() retorna este valor de cadena de caracteres directamente; también acepta un segundo argumento opcional como valor predeterminado para retornar si la clave solicitada no está presente.

Si los datos del formulario enviados contienen más de un campo con el mismo nombre, el objeto recuperado por form[key] no es una instancia FieldStorage o MiniFieldStorage, sino una lista de dichas instancias. De forma similar, en esta situación, form.getvalue(key) retornaría una lista de cadenas de caracteres. Si espera esta posibilidad (cuando su formulario HTML contiene múltiples campos con el mismo nombre), utilice el método getlist(), que siempre retorna una lista de valores (para que no sea necesario poner en mayúsculas y minúsculas en el caso de un solo elemento). Por ejemplo, este código concatena cualquier número de campos de nombre de usuario, separados por comas:

value = form.getlist("username")
usernames = ",".join(value)

Si un campo representa un archivo cargado, el acceso al valor a través del atributo value o el método getvalue() lee todo el archivo en memoria como bytes. Puede que esto no sea lo que quiera que ocurra. Puede probar un archivo cargado probando el atributo filename o el atributo file. Después, puede leer los datos del atributo file antes de que se cierre automáticamente como parte de la recolección de elementos no utilizados de la instancia FieldStorage (los métodos read() y readline() retornarán bytes):

fileitem = form["userfile"]
if fileitem.file:
    # It's an uploaded file; count lines
    linecount = 0
    while True:
        line = fileitem.file.readline()
        if not line: break
        linecount = linecount + 1

Los objetos FieldStorage también permiten ser usados en una sentencia with , lo que automáticamente los cerrará cuando termine la sentencia.

Si un error es encontrado al obtener el contenido de un archivo cargado (por ejemplo, cuando el usuario interrumpe el envío del formulario haciendo clic en un botón Atrás o Cancelar), el atributo done del objeto para el campo se establecerá en el valor -1.

El borrador de archivo de carga estándar presenta la posibilidad de cargar varios archivos desde un campo (utilizando una codificación recursiva multipart/*). Cuando esto ocurre, el elemento será un elemento similar a un diccionario FieldStorage. Esto se puede determinar probando su atributo type, que debe ser multipart/form-data (o tal vez otro tipo MIME que coincida multipart/*). En este caso, se puede iterar recursivamente al igual que el objeto de formulario de nivel superior.

Cuando se envía un formulario en el formato «antiguo» (como la cadena de caracteres de consulta (query string) o como una sola parte de datos de tipo application/x-www-form-urlencoded), los elementos serán realmente instancias de la clase MiniFieldStorage. En este caso, los atributos list, file y filename siempre son None.

Un formulario enviado a través de POST que también tiene una cadena de caracteres de consulta (query string) contendrá los elementos FieldStorage y MiniFieldStorage.

Distinto en la versión 3.4: El atributo file se cierra automáticamente con el recolector de basura de la instancia creada FieldStorage.

Distinto en la versión 3.5: Agregado soporte para el protocolo de administrador de contexto a la clase FieldStorage .

Interfaz de Nivel Superior

La sección anterior explica cómo leer datos de un formulario CGI usando la clase FieldStorage. Esta sección describe un nivel de interfaz superior que se añadió a esta clase para permitir que uno lo haga de una manera más legible e intuitiva. La interfaz no hace que las técnicas descritas en las secciones anteriores estén obsoletas – por ejemplo, siguen siendo útiles para procesar la carga de archivos de manera eficiente.

La interfaz consiste en dos métodos simples. Usando los métodos puedes procesar datos de formulario de una manera genérica, sin la necesidad de preocuparte si solo se publicaron uno o más valores con un solo nombre.

En la sección anterior, aprendiste a escribir el siguiente código cada vez que esperabas que un usuario publicara más de un valor con un nombre:

item = form.getvalue("item")
if isinstance(item, list):
    # The user is requesting more than one item.
else:
    # The user is requesting only one item.

Esta situación es común, por ejemplo, cuando un formulario contiene un grupo de múltiples casillas de verificación (checkboxes) con el mismo nombre:

<input type="checkbox" name="item" value="1" />
<input type="checkbox" name="item" value="2" />

En la mayoría de las situaciones, sin embargo, solo hay un control de formulario con un nombre determinado en un formulario y así, espera y solo necesita un valor asociado con este nombre. Así que escribe un script que contiene, por ejemplo, este código:

user = form.getvalue("user").upper()

El problema con el código es que nunca debe esperar que un cliente proporcione una entrada válida a los scripts. Por ejemplo, si un usuario curioso anexa otro par user=foo a la cadena de caracteres de consulta (query string), el script se bloquearía, porque en esta situación la llamada al método getvalue("user") retorna una lista en lugar de una cadena de caracteres. Llamar al método upper() en una lista no es válido (ya que las listas no tienen un método con este nombre) y se produce una excepción AttributeError.

Por lo tanto, la forma adecuada de leer los valores de datos de formulario era usar siempre el código que comprueba si el valor obtenido es un valor único o una lista de valores. Eso es molesto y conduce a scripts menos legibles.

Un enfoque más conveniente es utilizar los métodos getfirst() y getlist() proporcionados por esta interfaz de nivel superior.

FieldStorage.getfirst(name, default=None)

Este método siempre retorna solo un valor asociado con el campo de formulario name. El método retorna solo el primer valor en caso de que se registraran más valores con dicho nombre. Tenga en cuenta que el orden en que se reciben los valores puede variar de un navegador a otro y no debe darse por sentado. 1 Si no existe ningún campo o valor de formulario, el método retorna el valor especificado por el parámetro opcional default. Este parámetro tiene como valor predeterminado None si no se especifica.

FieldStorage.getlist(name)

Este método siempre retorna una lista de valores asociados con el campo de formulario name. El método retorna una lista vacía si no existe tal campo o valor de formulario para name. Retorna una lista que consta de un elemento si solo existe un valor de este tipo.

Usando estos métodos puede escribir código compacto agradable:

import cgi
form = cgi.FieldStorage()
user = form.getfirst("user", "").upper()    # This way it's safe.
for item in form.getlist("item"):
    do_something(item)

Funciones

Estas son útiles si desea más control, o si desea emplear algunos de los algoritmos implementados en este módulo en otras circunstancias.

cgi.parse(fp=None, environ=os.environ, keep_blank_values=False, strict_parsing=False, separator="&")

Analiza una consulta en el entorno o desde un archivo (el archivo predeterminado es sys.stdin). Los parámetros keep_blank_values, strict_parsing y separator se pasan a urllib.parse.parse_qs() sin cambios.

cgi.parse_multipart(fp, pdict, encoding="utf-8", errors="replace", separator="&")

Analiza la entrada de tipo multipart/form-data (para cargas de archivos). Los argumentos son fp para el archivo de entrada, pdict para un diccionario que contiene otros parámetros en el encabezado Content-Type y encoding, la codificación de la solicitud.

Retorna un diccionario al igual que urllib.parse.parse_qs(): las claves son los nombres de campo, cada valor es una lista de valores para ese campo. Para los campos que no son de archivo, el valor es una lista de cadenas de caracteres.

Esto es fácil de usar pero no muy bueno si espera que se carguen megabytes — en ese caso, utilice la clase FieldStorage en su lugar, que es mucho más flexible.

Distinto en la versión 3.7: Se agregaron los parámetros encoding y errors. Para los campos que no son de archivo, el valor es ahora una lista de cadenas de caracteres, no bytes.

Distinto en la versión 3.9.2: Agregado el parámetro separator.

cgi.parse_header(string)

Analiza un encabezado MIME (como Content-Type) en un valor principal y un diccionario de parámetros.

cgi.test()

Robust test CGI script, usable as main program. Writes minimal HTTP headers and formats all information provided to the script in HTML format.

cgi.print_environ()

Da formato al entorno del shell en HTML.

cgi.print_form(form)

Da formato a un formulario en HTML.

cgi.print_directory()

Da formato al directorio actual en HTML.

cgi.print_environ_usage()

Imprime una lista de variables de entorno útiles (utilizadas por CGI) en HTML.

Preocuparse por la seguridad

There’s one important rule: if you invoke an external program (via os.system(), os.popen() or other functions with similar functionality), make very sure you don’t pass arbitrary strings received from the client to the shell. This is a well-known security hole whereby clever hackers anywhere on the Web can exploit a gullible CGI script to invoke arbitrary shell commands. Even parts of the URL or field names cannot be trusted, since the request doesn’t have to come from your form!

Para estar en el lado seguro, si debe pasar una cadena de caracteres de un formulario a un comando de shell, debe asegurarse de que la cadena de caracteres contiene solo caracteres alfanuméricos, guiones, guiones bajos y puntos.

Instalando su script de CGI en un sistema Unix

Lea la documentación del servidor HTTP y consulte con el administrador del sistema local para encontrar el directorio donde se deben instalar los scripts CGI; por lo general, esto se encuentra en un directorio cgi-bin en el árbol del servidor.

Asegúrese de que el script es legible y ejecutable por «otros»; el modo de archivo Unix debe ser octal 0o755 (utilice chmod 0755 filename). Asegúrese de que la primera línea del script contiene #! a partir de la columna 1 seguida del nombre de ruta del intérprete de Python, por ejemplo:

#!/usr/local/bin/python

Asegúrese que el intérprete de Python exista y sea ejecutable por «otros».

Asegúrese de que cualquier archivo que su script necesite leer o escribir sea legible o tenga permiso de escritura, respectivamente, por «otros» — su modo debe ser 0o644 para legible y 0o666 para escribir. Esto se debe a que, por razones de seguridad, el servidor HTTP ejecuta el script como usuario «nadie», sin ningún privilegio especial. Sólo puede leer (escribir, ejecutar) archivos que todo el mundo puede leer (escribir, ejecutar). El directorio actual en tiempo de ejecución también es diferente (normalmente es el directorio cgi-bin del servidor) y el conjunto de variables de entorno también es diferente de lo que se obtiene al iniciar sesión. En particular, no cuente con la ruta de búsqueda del shell para ejecutables (PATH) o la ruta de búsqueda del módulo Python (PYTHONPATH) que se establecerá en cualquier cosa interesante.

Si necesita cargar módulos desde un directorio el cual no está en la ruta de búsqueda de módulos predeterminada de Python, puede cambiar la ruta en su script, antes de importar otros módulos. Por ejemplo:

import sys
sys.path.insert(0, "/usr/home/joe/lib/python")
sys.path.insert(0, "/usr/local/lib/python")

(¡De esta manera, el directorio insertado de último será buscado primero!)

Las instrucciones para sistemas que no son Unix pueden variar; consulte la documentación de su servidor HTTP (usualmente tendrá una sección sobre scripts CGI).

Probando su script de CGI

Desafortunadamente, un script CGI generalmente no se ejecutará cuando lo pruebe desde la línea de comandos, y un script que funcione perfectamente desde la línea de comandos puede fallar misteriosamente cuando se ejecuta desde el servidor. Hay una razón por la que debe probar el script desde la línea de comandos: si contiene un error de sintaxis, el intérprete de Python no lo ejecutará en absoluto y lo más probable es que el servidor HTTP envíe un error críptico al cliente.

Asumiendo que su script no tiene errores de sintaxis, pero este no funciona, no tiene más opción que leer la siguiente sección.

Depurando scripts de CGI

First of all, check for trivial installation errors — reading the section above on installing your CGI script carefully can save you a lot of time. If you wonder whether you have understood the installation procedure correctly, try installing a copy of this module file (cgi.py) as a CGI script. When invoked as a script, the file will dump its environment and the contents of the form in HTML format. Give it the right mode etc., and send it a request. If it’s installed in the standard cgi-bin directory, it should be possible to send it a request by entering a URL into your browser of the form:

http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home

Si esto da un error de tipo 404, el servidor no puede encontrar el script – quizás necesite instalarlo en un directorio diferente. Si este da otro error, hay un problema con la instalación que debería intentar solucionar antes de continuar. Si obtiene una lista bien formateada del entorno y el contenido del formulario (en este ejemplo, los campos deberían estar listados como «addr» con el valor «At Home» y «name» con el valor «Joe Blow»), el script cgi.py ha sido instalado correctamente. Si sigue el mismo procedimiento para su propio script, ya debería poder depurarlo.

El siguiente paso podría ser llamar a la función test() del módulo cgi de su script: reemplace su código principal con la declaración única

cgi.test()

Esto debería producir los mismos resultados que los obtenidos al instalar el archivo cgi.py en sí.

Cuando un script de Python normal lanza una excepción no controlada (por cualquier razón: de un error tipográfico en un nombre de módulo, un archivo que no se puede abrir, etc.), el intérprete de Python imprime un traceback sutil y sale. Aunque el intérprete de Python seguirá haciendo esto cuando el script CGI lance una excepción, lo más probable es que el traceback termine en uno de los archivos de registro del servidor HTTP o se descarte por completo.

Afortunadamente, una vez que haya logrado que su script ejecute algún código, puede enviar fácilmente tracebacks al navegador web utilizando el módulo cgitb. Si aún no lo ha hecho, solo añada las líneas:

import cgitb
cgitb.enable()

al principio de su script. Luego intente ejecutarlo de nuevo; cuando un problema ocurra, debería ver un informe detallado que probablemente muestre la causa del error.

Si sospecha que puede haber un problema al importar el módulo cgitb, puede usar un enfoque aún más robusto (que solo usa módulos integrados):

import sys
sys.stderr = sys.stdout
print("Content-Type: text/plain")
print()
...your code here...

Esto se basa en el intérprete de Python para imprimir el traceback. El tipo de contenido de la salida se establece en texto plano, lo que deshabilita todo el procesamiento HTML. Si el script funciona, el cliente mostrará el código HTML sin formato. Si lanza una excepción, lo más probable es que después que se hayan impreso las dos primeras líneas, se mostrará un traceback. Dado que no se está realizando ninguna interpretación HTML, el traceback será legible.

Problemas comunes y soluciones

La mayoría de servidores HTTP almacenan en búfer la salida de los scripts CGI hasta que el script esté completado. Esto significa que no es posible mostrar un reporte del progreso en la parte del cliente mientras que el script se esté ejecutando.

Compruebe las instrucciones de instalación anteriores.

Verifique los archivos de registro (logs) del servidor HTTP. (¡Usar tail -f logfile en una ventana separada puede ser útil!)

Siempre verifique un script para encontrar errores de sintaxis primero, haciendo algo como python script.py.

Si su script no tiene ningún error sintáctico, pruebe añadiendo import cgitb; cgitb.enable() en la parte superior del script.

Cuando se invoquen programas externos, asegúrese de que pueden ser encontrados. Generalmente esto significa usar nombres de ruta absolutos — PATH generalmente no se establece en un valor útil en un script CGI.

Al leer o escribir archivos externos, asegúrese de que puedan ser leídas o escritas por el userid por el que su script CGI se va a ejecutar: es típico que esto sea el userid bajo el que el servidor web se está ejecutando, o algún userid especificado explícitamente por la función suexec del servidor web.

No intente darle un modo set-uid a un script CGI. Esto no funciona en la mayoría de sistemas, además de ser un riesgo de seguridad.

Notas al pie

1

Tenga en cuenta que algunas versiones recientes de las especificaciones de HTML establecen en qué orden se deben suministrar los valores de campo, pero saber si se recibió una solicitud de un navegador adaptado, o incluso desde un navegador siquiera, es tedioso y propenso a errores.

cgitb — Administrador traceback para scripts CGI.

Código fuente: Lib/cgitb.py [https://github.com/python/cpython/tree/3.9/Lib/cgitb.py]

Obsoleto desde la versión 3.11: The cgitb module is deprecated (see PEP 594 [https://www.python.org/dev/peps/pep-0594#cgitb] for details).

El modulo cgitb proporciona un manejador de excepciones especial para script de Python. (Su nombre es un poco engañoso. Fue diseñado originalmente para mostrar una amplia información de traceback en HTML para los scripts CGI). Más tarde se generalizó para mostrar también esta información en texto plano). Después de activar este módulo, si se produce una excepción no capturada, se mostrará un informe detallado y formateado. El informe incluye un traceback que muestra extractos del código fuente para cada nivel, así como los valores de los argumentos y las variables locales de las funciones que se están ejecutando actualmente, para ayudar a depurar el problema. Opcionalmente, puede guardar esta información en un archivo en lugar de enviarla al navegador.

Para activar esta función, simplemente añada lo siguiente a la parte superior de su script CGI:

import cgitb
cgitb.enable()

Las opciones de la función enable() controlan si el informe se muestra en el explorador y si este se registra en un archivo para su posterior análisis.

cgitb.enable(display=1, logdir=None, context=5, format="html")

Esta función hace que el módulo cgitb se encargue del control predeterminado del intérprete para las excepciones estableciendo el valor de sys.excepthook.

El argumento opcional display tiene como valor predeterminado 1 y se puede establecer en 0 para suprimir el envío de la traza al navegador. Si el argumento logdir está presente, los informes de traceback se escriben en los archivos. El valor de logdir debe ser un directorio donde se estos archivos serán colocados. El argumento opcional context es el número de líneas de contexto que se mostrarán alrededor de la línea actual del código fuente en el traceback; esto tiene como valor predeterminado 5. Si el argumento opcional format es "html", la salida se formatea como HTML. Cualquier otro valor fuerza la salida de texto sin formato. El valor predeterminado es "html".

cgitb.text(info, context=5)

Esta función controla la excepción descrita por info (una tupla de 3 que contiene el resultado de sys..exc_info()), dando formato a su traceback como texto y retornando el resultado como una cadena de caracteres. El argumento opcional context es el número de líneas de contexto que se mostrarán alrededor de la línea actual de código fuente en el traceback; esto tiene como valor predeterminado 5.

cgitb.html(info, context=5)

Esta función controla la excepción descrita por info (una tupla de 3 que contiene el resultado de sys..exc_info()), dando formato a su traceback como HTML y retornando el resultado como una cadena de caracteres. El argumento opcional context es el número de líneas de contexto que se mostrarán alrededor de la línea actual de código fuente en el traceback; esto tiene como valor predeterminado 5.

cgitb.handler(info=None)

Esta función maneja una excepción utilizando la configuración predeterminada (es decir, mostrar un informe en el navegador, pero no registrar en un archivo). Esto puede ser usado cuando has capturado una excepción y quieres reportarla usando cgitb. El argumento opcional info debería ser una tupla de 3 que contenga un tipo de excepción, un valor de excepción y un objeto de traceback, exactamente como la tupla retornada por sys.exc_info(). Si no se proporciona el argumento info, la excepción actual se obtiene de sys.exc_info().

chunk — Lee los datos de los trozos de IFF

Código fuente: Lib/chunk.py [https://github.com/python/cpython/tree/3.9/Lib/chunk.py]

Obsoleto desde la versión 3.11: The chunk module is deprecated (see PEP 594 [https://www.python.org/dev/peps/pep-0594#chunk] for details).

Este módulo proporciona una interfaz para leer archivos que usan trozos de EA IFF 85. 1 Este formato se utiliza al menos en el formato Audio Interchange File Format (AIFF/AIFF-C) y en el formato Real Media File Format (RMFF). El formato de archivo de audio WAVE está estrechamente relacionado y también puede ser leído usando este módulo.

Un trozo tiene la siguiente estructura:

Desplazamiento

Longitud

Contenido

0

4

ID del trozo

4

4

El tamaño del trozo en el orden de bytes big-endian, sin incluir el encabezado

8

n

Bytes de datos, donde n es el tamaño dado en el campo anterior

8 + n

0 o 1

Se necesita un byte de relleno si n es impar y se utiliza la alineación de trozos

La ID es una cadena de 4 bytes que identifica el tipo de trozo.

El campo de tamaño (un valor de 32 bits, codificado utilizando el orden de bytes big-endian) da el tamaño de los datos de los trozos, sin incluir el encabezamiento de 8 bytes.

Normalmente un archivo de tipo IFF consiste en uno o más trozos. El uso propuesto de la clase Chunk definido aquí es declarar una instancia al principio de cada trozo y leer de la instancia hasta que llegue al final, después de lo cual se puede declarar una nueva instancia. Al final del archivo, la creación de una nueva instancia fallará con una excepción EOFError.

class chunk.Chunk(file, align=True, bigendian=True, inclheader=False)

Clase que representa un trozo. Se espera que el argumento file sea un objeto parecido a un archivo. Una instancia de esta clase está específicamente permitida. El único método que se necesita es read(). Si los métodos seek() y tell() están presentes y no plantean una excepción, también se utilizan. Si estos métodos están presentes y hacen una excepción, se espera que no hayan alterado el objeto. Si el argumento opcional align es cierto, se supone que los trozos están alineados en los límites de 2 bytes. Si align es falso, se asume que no hay alineación. El valor por defecto es true. Si el argumento opcional bigendian es falso, se asume que el tamaño de los trozos está en orden little-endian. Esto es necesario para los archivos de audio WAVE. El valor por defecto es true. Si el argumento opcional inclheader es true, el tamaño dado en la cabecera del trozo incluye el tamaño de la cabecera. El valor por defecto es false.

Un objeto Chunk soporta los siguientes métodos:

getname()

Retorna el nombre (ID) del trozo. Estos son los primeros 4 bytes del trozo.

getsize()

Retorna el tamaño del trozo.

close()

Cierra y salta al final del trozo. Esto no cierra el archivo subyacente.

El resto de los métodos se levantarán OsError si se llama después de que el método close() haya sido llamado. Antes de Python 3.3, solían levantar IOError, ahora un alias de OSError.

isatty()

Retorna False.

seek(pos, whence=0)

Establece la posición actual del trozo. El argumento whence es opcional y por defecto es 0 (posicionamiento absoluto del archivo); otros valores son 1 (búsqueda relativa a la posición actual) y 2 (búsqueda relativa al final del archivo). No hay ningún valor de retorno. Si el archivo subyacente no permite la búsqueda, sólo se permiten las búsquedas hacia adelante.

tell()

Retorna la posición actual en el trozo.

read(size=-1)

Leer como máximo size bytes del trozo (menos si la lectura llega al final del trozo antes de obtener size bytes). Si el argumento size es negativo u omitido, lee todos los datos hasta el final del trozo. Un objeto de bytes vacío se retorna cuando el final del trozo se encuentra inmediatamente.

skip()

Salta al final del trozo. Todas las llamadas posteriores a read() para el trozo retorna b''. Si no estás interesado en el contenido del trozo, este método debe ser llamado para que el archivo apunte al comienzo del siguiente trozo.

Notas a pie de página

1

«EA IFF 85» Standard for Interchange Format Files, Jerry Morrison, Electronic Arts, enero 1985.

crypt — Función para verificar contraseñas Unix

Código fuente: Lib/crypt.py [https://github.com/python/cpython/tree/3.9/Lib/crypt.py]

Obsoleto desde la versión 3.11: The crypt module is deprecated (see PEP 594 [https://www.python.org/dev/peps/pep-0594#crypt] for details and alternatives). The hashlib module is a potential replacement for certain use cases.

Este módulo implementa una interfaz para la rutina crypt(3), el cual es una función hash unidireccional basada en un algoritmo DES modificado; consulte la página del manual de Unix para obtener más detalles. Los posibles usos incluyen el almacenamiento de contraseñas cifradas para que puedas verificar las contraseñas sin almacenar la contraseña real o intentar descifrar contraseñas Unix con un diccionario.

Tenga en cuenta que el comportamiento de este módulo depende en la implementación real de la rutina crypt(3) en el sistema en ejecución. Por lo tanto, cualquier extensión disponible en la implementación actual también estará disponible en este módulo.

Disponibilidad: Unix. No disponible en VxWorks.

Métodos de hashing

Nuevo en la versión 3.3.

El módulo crypt define la lista de métodos de cifrado (no todos los métodos están disponibles en todas las plataformas):

crypt.METHOD_SHA512

Un método de formato modular crypt con salt de 16 caracteres y hash de 86 caracteres basado en la función hash SHA-512. Este es el método más fuerte.

crypt.METHOD_SHA256

Otro método de formato modular crypt con salt de 16 caracteres y hash de 43 caracteres basado en la función hash SHA-256.

crypt.METHOD_BLOWFISH

Otro método de formato modular crypt con salt de 22 caracteres y hash de 31 caracteres basado en el cifrado Blowfish.

Nuevo en la versión 3.7.

crypt.METHOD_MD5

Otro método de formato modular crypt con salt de 8 caracteres y hash de 22 caracteres basado en la función hash MD5.

crypt.METHOD_CRYPT

El método tradicional con un salt de 2 caracteres y hash de 13 caracteres. Este es el método más débil.

Atributos del módulo

Nuevo en la versión 3.3.

crypt.methods

Una lista de algoritmos hash de contraseña disponibles, como objetos crypt.METHOD_*. Esta lista está ordenada de la más fuerte a la más débil.

Funciones del módulo

El módulo crypt define las siguientes funciones:

crypt.crypt(word, salt=None)

word will usually be a user’s password as typed at a prompt or in a graphical interface. The optional salt is either a string as returned from mksalt(), one of the crypt.METHOD_* values (though not all may be available on all platforms), or a full encrypted password including salt, as returned by this function. If salt is not provided, the strongest method available in methods will be used.

La verificación de una contraseña generalmente se hace pasando la contraseña de texto plano como word y los resultados completos de una llamada anterior a crypt(), que debería ser igual a los resultados de esta llamada.

salt (ya sea una cadena aleatoria de 2 o 16 caracteres, posiblemente con el prefijo $digit$ para indicar el método) que se utilizará para perturbar el algoritmo de cifrado. Los caracteres en salt deben estar en el conjunto [./a-zA-Z0-9], con la excepción del formato modular crypt que antepone un $digit$.

Retorna una contraseña con hash como una cadena, que estará compuesta por caracteres del mismo alfabeto que salt.

Dado que algunas extensiones de crypt(3) permiten diferentes valores, con diferentes tamaños en salt, se recomienda utilizar la contraseña encriptada completa como salt al buscar una contraseña.

Distinto en la versión 3.3: Acepta los valores crypt.METHOD_* además de las cadenas para salt.

crypt.mksalt(method=None, *, rounds=None)

Return a randomly generated salt of the specified method. If no method is given, the strongest method available in methods is used.

El valor de retorno es una cadena adecuada para pasar como argumento salt a crypt().

rounds especifica el número de rondas para METHOD_SHA256, METHOD_SHA512 y METHOD_BLOWFISH. Para METHOD_SHA256 y METHOD_SHA512 debe ser un entero entre 1000 y 999_999_999, el valor predeterminado es 5000. Para METHOD_BLOWFISH debe ser una potencia de dos entre 16 (2⁴) y 2_147_483_648 (2³¹), el valor predeterminado es 4096 (2¹²).

Nuevo en la versión 3.3.

Distinto en la versión 3.7: Se agregó el parámetro rounds.

Ejemplos

Un simple ejemplo que ilustra el uso típico (se necesita una operación de comparación de tiempo constante para limitar la exposición a los ataques de tiempo. hmac.compare_digest() es adecuado para este propósito):

import pwd
import crypt
import getpass
from hmac import compare_digest as compare_hash

def login():
    username = input('Python login: ')
    cryptedpasswd = pwd.getpwnam(username)[1]
    if cryptedpasswd:
        if cryptedpasswd == 'x' or cryptedpasswd == '*':
            raise ValueError('no support for shadow passwords')
        cleartext = getpass.getpass()
        return compare_hash(crypt.crypt(cleartext, cryptedpasswd), cryptedpasswd)
    else:
        return True

Para generar un hash de una contraseña utilizando el método más fuerte disponible y compararlo con el original:

import crypt
from hmac import compare_digest as compare_hash

hashed = crypt.crypt(plaintext)
if not compare_hash(hashed, crypt.crypt(plaintext, hashed)):
    raise ValueError("hashed version doesn't validate against original")

:mod:”imghdr” — Determinar el tipo de imagen

Código fuente: :source:”Lib/imghdr.py”

Obsoleto desde la versión 3.11: The imghdr module is deprecated (see PEP 594 [https://www.python.org/dev/peps/pep-0594#imghdr] for details and alternatives).

El módulo imghdr determina el tipo de imagen contenida en un archivo o secuencia de bytes.

El módulo imghdr define la siguiente función:

imghdr.what(filename, h=None)

Comprueba los datos de imagen contenidos en el archivo mencionado en filename y retorna una cadena de caracteres que describe el tipo de imagen. Si se proporciona el argumento opcional h, se ignora filename y se supone que h contiene la secuencia de bytes que se va a analizar.

Distinto en la versión 3.6: Acepta un path-like object.

Se reconocen los siguientes tipos de imagen, enumerados a continuación con el valor devuelto de what():

Valor

Formato de imagen

'rgb'

Archivos SGI ImgLib

'gif'

Archivos GIF 87a y 89a

'pbm'

Archivos Portable Bitmap

'pgm'

Archivos Portable Graymap

'ppm'

Archivos Portable Pixmap

'tiff'

Archivos TIFF

'rast'

Archivos Sun Raster

'xbm'

Archivos X Bitmap

'jpeg'

Datos JPEG en formatos JFIF o Exif

'bmp'

Archivos BMP

'png'

Portable Network Graphics

'webp'

Archivos WebP

'exr'

Archivos OpenEXR

Nuevo en la versión 3.5: Se añadieron los formatos exr y webp.

Puede ampliar la lista de tipos de archivo que imghdr puede reconocer agregándolos a esta variable:

imghdr.tests

Una lista de funciones que realizan las comprobaciones individuales. Cada función toma dos argumentos: la secuencia de bytes y un objeto abierto de tipo archivo. Cuando what() es llamada con una secuencia de bytes, el objeto de tipo archivo será None.

La función de comprobación debería retornar una cadena de caracteres que describa el tipo de imagen si la comprobación se realizó correctamente o “”Ninguno”” si ha fallado.

Ejemplo:

>>> import imghdr
>>> imghdr.what('bass.gif')
'gif'

imp — Acceda a import internamente

Código fuente: Lib/imp.py [https://github.com/python/cpython/tree/3.9/Lib/imp.py]

Obsoleto desde la versión 3.4: El módulo imp está obsoleto en favor de importlib.

Este módulo proporciona una interfaz a los mecanismos utilizados para implementar la sentencia import. Define las siguientes constantes y funciones:

imp.get_magic()

Retorna el valor de la cadena de caracteres mágica que se utiliza para reconocer archivos de código compilados por bytes (archivos .pyc). (Este valor puede ser diferente para cada versión de Python).

Obsoleto desde la versión 3.4: Utilice importlib.util.MAGIC_NUMBER en su lugar.

imp.get_suffixes()

Retorna una lista de tuplas de 3 elementos, cada una de las cuales describe un tipo particular de módulo. Cada triple tiene la forma (suffix, mode, type), donde suffix es una cadena de caracteres que se agregará al nombre del módulo para formar el nombre de archivo a buscar, mode es la cadena de caracteres de modo para pasar a la función incorporada open() para abrir el archivo (esto puede ser 'r' para archivos de texto o 'rb' para archivos binarios), y type es el tipo de archivo, que tiene uno de los valores PY_SOURCE, PY_COMPILED, o C_EXTENSION, que se describen a continuación.

Obsoleto desde la versión 3.3: Utilice las constantes definidas en importlib.machinery en su lugar.

imp.find_module(name[, path])

Intente encontrar el módulo name. Si se omite path o None, se busca la lista de nombres de directorio dados por sys.path, pero primero se buscan algunos lugares especiales: la función intenta encontrar un módulo integrado con el nombre dado (C_BUILTIN), a continuación, un módulo congelado (PY_FROZEN), y en algunos sistemas algunos otros lugares se buscan también (en Windows, se ve en el registro que puede apuntar a un archivo específico).

De lo contrario, path debe ser una lista de nombres de directorio; cada directorio se busca archivos con cualquiera de los sufijos retornados por get_suffixes() arriba. Los nombres no válidos de la lista se omiten silenciosamente (pero todos los elementos de lista deben ser cadenas).

Si la búsqueda se realiza correctamente, el valor retornado es una tupla de 3 elementos (file, pathname, description):

file es un abierto file object posicionado al principio, pathname es el nombre de ruta del archivo encontrado, y description es una tupla de 3 elementos tal como se encuentra en la lista retornada por get_suffixes() que describe el tipo de módulo encontrado.

Si el módulo no vive en un archivo, el archivo file retornado es None, pathname es la cadena vacía y la tupla description contiene cadenas vacías para su sufijo y modo; el tipo de módulo se indica como se indica entre paréntesis arriba. Si la búsqueda no se realiza correctamente, se provoca ImportError. Otras excepciones indican problemas con los argumentos o el entorno.

Si el módulo es un paquete, file es None, pathname es la ruta de acceso del paquete y el último elemento de la tupla description es PKG_DIRECTORY.

Esta función no controla los nombres de módulo jerárquico (nombres que contienen puntos). Para encontrar P.M, es decir, submódulo M del paquete P, use find_module() y load_module() para buscar y cargar el paquete P, y luego use find_module() con el argumento path establecido en P.__path__. Cuando P tenga un nombre punteado, aplique esta receta de forma recursiva.

Obsoleto desde la versión 3.3: Utilice importlib.util.find_spec() en su lugar a menos que se requiera compatibilidad con Python 3.3, en cuyo caso use importlib.find_loader(). Para ver el uso del caso anterior, consulte la sección Ejemplos de la documentación importlib.

imp.load_module(name, file, pathname, description)

Cargue un módulo que fue encontrado anteriormente por find_module() (o por una búsqueda realizada de otro modo que produce resultados compatibles). Esta función hace más que importar el módulo: si el módulo ya estaba importado, se recargará el módulo! El argumento name indica el nombre completo del módulo (incluido el nombre del paquete, si se trata de un submódulo de un paquete). El argumento file es un archivo abierto y pathname es el nombre de archivo correspondiente; pueden ser None y '', respectivamente, cuando el módulo es un paquete o no se carga desde un archivo. El argumento description es una tupla, como sería retornada por get_suffixes(), que describe qué tipo de módulo se debe cargar.

Si la carga se realiza correctamente, el valor retornado es el objeto modulo; de lo contrario, se produce una excepción (normalmente ImportError).

Importante: el autor de la llamada es responsable de cerrar el argumento file, si no era None, incluso cuando se genera una excepción. Esto se hace mejor usando una declaración try … finally.

Obsoleto desde la versión 3.3: Si se utiliza anteriormente junto con imp.find_module() considere usar importlib.import_module(), de lo contrario utilice el cargador retornado por el reemplazo que eligió para imp.find_module(). Si llamó a imp.load_module() y funciones relacionadas directamente con argumentos de ruta de archivo, utilice una combinación de importlib.util.spec_from_file_location() y importlib.util.module_from_spec(). Consulte la sección Ejemplos de la documentación importlib para obtener más información sobre los distintos enfoques.

imp.new_module(name)

Retorna un nuevo objeto de módulo vacío denominado name. Este objeto es not insertado en sys.modules.

Obsoleto desde la versión 3.4: Utilice importlib.util.module_from_spec() en su lugar.

imp.reload(module)

Vuelva a cargar un módulo importado anteriormente. El argumento debe ser un objeto module, por lo que debe haberse importado correctamente antes. Esto es útil si ha editado el archivo de origen del módulo utilizando un editor externo y desea probar la nueva versión sin salir del intérprete de Python. El valor retornado es el objeto module (el mismo que el argumento module).

Cuando se ejecuta reload(module):

El código de los módulos de Python se vuelve a compilar y se vuelve a ejecutar el código de nivel de módulo, definiendo un nuevo conjunto de objetos que están enlazados a nombres en el diccionario del módulo. La función init de los módulos de extensión no se llama una segunda vez.

Al igual que con todos los demás objetos de Python, los objetos antiguos solo se recuperan después de que sus recuentos de referencia caigan a cero.

Los nombres del espacio de nombres del módulo se actualizan para que apunten a cualquier objeto nuevo o modificado.

Otras referencias a los objetos antiguos (como nombres externos al módulo) no se rebotan para hacer referencia a los nuevos objetos y deben actualizarse en cada espacio de nombres donde se producen si se desea.

Hay una serie de otras advertencias:

Cuando se vuelve a cargar un módulo, se conserva su diccionario (que contiene las variables globales del módulo). Las redefiniciones de nombres invalidarán las definiciones antiguas, por lo que esto generalmente no es un problema. Si la nueva versión de un módulo no define un nombre previamente definido, la definición anterior permanece. Esta característica se puede utilizar en beneficio del módulo si mantiene una tabla global o caché de objetos — con una instrucción try puede probar la presencia de la tabla y omitir su inicialización si se desea:

try:
    cache
except NameError:
    cache = {}

Es legal, aunque generalmente no es muy útil para recargar módulos incorporados o cargados dinámicamente, excepto para sys, __main__ y builtins. En muchos casos, sin embargo, los módulos de extensión no están diseñados para inicializarse más de una vez y pueden fallar de forma arbitraria cuando se vuelven a cargar.

Si un módulo importa objetos de otro módulo utilizando from… import …, llamando a reload() para el otro módulo no redefine los objetos importados de él — de una manera alrededor de esto es volver a ejecutar la sentencia from, otra es usar import y nombres calificados (module.*name*) en su lugar.

Si un módulo crea instancias de una clase, volver a cargar el módulo que define la clase no afecta a las definiciones de método de las instancias — siguen utilizando la definición de clase antigua. Lo mismo es cierto para las clases derivadas.

Distinto en la versión 3.3: Se basa en que tanto __name__ como __loader__ que se definen en el módulo que se está recargando en lugar de simplemente __name__.

Obsoleto desde la versión 3.4: Utilice importlib.reload() en su lugar.

Las siguientes funciones son comodidades para controlar las rutas de acceso de archivo PEP 3147 [https://www.python.org/dev/peps/pep-3147] compiladas en bytes.

Nuevo en la versión 3.2.

imp.cache_from_source(path, debug_override=None)

Retorna la ruta de acceso PEP 3147 [https://www.python.org/dev/peps/pep-3147] al archivo compilado por bytes asociado con la ruta path de origen. Por ejemplo, si path es /foo/bar/baz.py el valor retornado sería /foo/bar/__pycache__/baz.cpython-32.pyc para Python 3.2. La cadena cpython-32 proviene de la etiqueta mágica actual (consulte get_tag(); si sys.implementation.cache_tag no está definida entonces NotImplementedError se generará). Al pasar True o False para debug_override puede reemplazar el valor del sistema para __debug__, lo que da lugar a un código de bytes optimizado.

ruta no necesita existir.

Distinto en la versión 3.3: Lanza NotImplementedError cuando no se define sys.implementation.cache_tag.

Obsoleto desde la versión 3.4: Utilice importlib.util.source_from_cache() en su lugar.

Distinto en la versión 3.5: El parámetro debug_override ya no crea un archivo .pyo.

imp.source_from_cache(path)

Dada la ruta path a un nombre de archivo PEP 3147 [https://www.python.org/dev/peps/pep-3147], retorne la ruta de acceso del archivo de código fuente asociada. Por ejemplo, si path es /foo/bar/__pycache__/baz.cpython-32.pyc la ruta retornada sería /foo/bar/baz.py. path no necesita existir, sin embargo, si no se ajusta al formato PEP 3147 [https://www.python.org/dev/peps/pep-3147], se genera un ValueError. Si sys.implementation.cache_tag no está definido, se genera NotImplementedError.

Distinto en la versión 3.3: Provoca NotImplementedError cuando no se define sys.implementation.cache_tag.

Obsoleto desde la versión 3.4: Utilice importlib.util.source_from_cache() en su lugar.

imp.get_tag()

Retorna la cadena de etiqueta mágica PEP 3147 [https://www.python.org/dev/peps/pep-3147] que coincida con esta versión del número mágico de Python, como lo retorna get_magic().

Obsoleto desde la versión 3.4: Utilice sys.implementation.cache_tag directamente a partir de Python 3.3.

Las siguientes funciones ayudan a interactuar con el mecanismo de bloqueo interno del sistema de importación. La semántica de bloqueo de las importaciones es un detalle de implementación que puede variar de una versión a una. Sin embargo, Python garantiza que las importaciones circulares funcionen sin interbloqueos.

imp.lock_held()

Retorna True si el bloqueo de importación global está actualmente retenido, de lo contrario, False. En plataformas sin hilos, siempre retorna False.

En plataformas con subprocesos, un subproceso que ejecuta una importación primero contiene un bloqueo de importación global y, a continuación, configura un bloqueo por módulo para el resto de la importación. Esto impide que otros subprocesos importen el mismo módulo hasta que se complete la importación original, lo que impide que otros subprocesos vean objetos de módulo incompletos construidos por el subproceso original. Se hace una excepción para las importaciones circulares, que por construcción tienen que exponer un objeto de módulo incompleto en algún momento.

Distinto en la versión 3.3: El esquema de bloqueo ha cambiado a bloqueos por módulo en su mayor parte. Se mantiene un bloqueo de importación global para algunas tareas críticas, como la inicialización de los bloqueos por módulo.

Obsoleto desde la versión 3.4.

imp.acquire_lock()

Adquiera el bloqueo de importación global del intérprete para el subproceso actual. Este bloqueo debe ser utilizado por los ganchos de importación para garantizar la seguridad de subprocesos al importar módulos.

Una vez que un subproceso ha adquirido el bloqueo de importación, el mismo subproceso puede adquirirlo de nuevo sin bloquear; el subproceso debe liberarlo una vez por cada vez que lo ha adquirido.

En plataformas sin subprocesos, esta función no hace nada.

Distinto en la versión 3.3: El esquema de bloqueo ha cambiado a bloqueos por módulo en su mayor parte. Se mantiene un bloqueo de importación global para algunas tareas críticas, como la inicialización de los bloqueos por módulo.

Obsoleto desde la versión 3.4.

imp.release_lock()

Suelte el bloqueo de importación global del intérprete. En plataformas sin subprocesos, esta función no hace nada.

Distinto en la versión 3.3: El esquema de bloqueo ha cambiado a bloqueos por módulo en su mayor parte. Se mantiene un bloqueo de importación global para algunas tareas críticas, como la inicialización de los bloqueos por módulo.

Obsoleto desde la versión 3.4.

Las siguientes constantes con valores enteros, definidas en este módulo, se utilizan para indicar el resultado de búsqueda de find_module().

imp.PY_SOURCE

El módulo se encontró como un archivo de origen.

Obsoleto desde la versión 3.3.

imp.PY_COMPILED

El módulo se encontró como un archivo de objeto de código compilado.

Obsoleto desde la versión 3.3.

imp.C_EXTENSION

El módulo se encontró como biblioteca compartida cargable dinámicamente.

Obsoleto desde la versión 3.3.

imp.PKG_DIRECTORY

El módulo se encontró como un directorio de paquetes.

Obsoleto desde la versión 3.3.

imp.C_BUILTIN

El módulo fue encontrado como un módulo incorporado.

Obsoleto desde la versión 3.3.

imp.PY_FROZEN

El módulo fue encontrado como un módulo congelado.

Obsoleto desde la versión 3.3.

class imp.NullImporter(path_string)

El tipo NullImporter es un enlace de importación PEP 302 [https://www.python.org/dev/peps/pep-0302] que controla cadenas de ruta de acceso que no son de directorio al no encontrar ningún módulo. Llamar a este tipo con un directorio existente o una cadena vacía genera ImportError. De lo contrario, se retorna una instancia NullImporter.

Las instancias solo tienen un método:

find_module(fullname[, path])

Este método siempre retorna None, lo que indica que no se pudo encontrar el módulo solicitado.

Distinto en la versión 3.3: None se inserta en sys.path_importer_cache en lugar de una instancia de NullImporter.

Obsoleto desde la versión 3.4: Inserte None en sys.path_importer_cache en su lugar.

Ejemplos

La siguiente función emula lo que era la instrucción de importación estándar hasta Python 1.4 (sin nombres de módulo jerárquico). (Esta implementación no funcionaría en esa versión, ya que find_module() se ha ampliado y load_module() se ha añadido en 1.4.)

import imp
import sys

def __import__(name, globals=None, locals=None, fromlist=None):
    # Fast path: see if the module has already been imported.
    try:
        return sys.modules[name]
    except KeyError:
        pass

    # If any of the following calls raises an exception,
    # there's a problem we can't handle -- let the caller handle it.

    fp, pathname, description = imp.find_module(name)

    try:
        return imp.load_module(name, fp, pathname, description)
    finally:
        # Since we may exit via an exception, close fp explicitly.
        if fp:
            fp.close()

mailcap — Manejo de archivos Mailcap

Código fuente: Lib/mailcap.py [https://github.com/python/cpython/tree/3.9/Lib/mailcap.py]

Obsoleto desde la versión 3.11: The mailcap module is deprecated (see PEP 594 [https://www.python.org/dev/peps/pep-0594#mailcap] for details). The mimetypes module provides an alternative.

Los archivos mailcap se utilizan para configurar la manera en las que aplicaciones conscientes de formatos MIME como lectores de correo y navegadores web reaccionan a archivos con diferentes tipos MIME. (El nombre «mailcap» viene de la frase «mail capability».) Por ejemplo, un archivo mailcap puede contener una linea como video/mpeg; xmpeg %s. Entonces, si el usuario encuentra un mensaje de correo o un documento web con el tipo MIME video/mpeg, %s será reemplazado por un nombre de archivo (por lo general, uno que pertenezca a un archivo temporal) y el programa xmpeg puede ser iniciado de manera automática para visualizar el archivo.

El formato mailcap está documentado en RFC 1524 [https://tools.ietf.org/html/rfc1524.html], «A User Agent Configuration Mechanism For Multimedia Mail Format Information», pero no es un estándar de Internet. Sin embargo, los archivos mailcap tienen soporte en la mayoría de los sistemas Unix.

mailcap.findmatch(caps, MIMEtype, key='view', filename='/dev/null', plist=[])

Retorna una tupla; el primer elemento es una cadena que contiene la línea de comando a ser ejecutada (la cual puede ser pasada a la función os.system()), y el segundo elemento es la entrada mailcap para el tipo MIME proporcionado. Si no se encuentra un tipo MIME que coincida, entonces se retornan los valores de (None, None).

key es el nombre del campo deseado, que representa el tipo de actividad a realizar; el valor por defecto es “view”, ya que en el caso más común se quiere simplemente ver el cuerpo de los datos tecleados en MIME. Otros posibles valores podrían ser “compose” y “edit”, si se quisiera crear un nuevo cuerpo del tipo MIME dado o alterar los datos del cuerpo existente. Consulta RFC 1524 [https://tools.ietf.org/html/rfc1524.html] para una lista completa de estos campos.

filename es el nombre de fichero que debe ser sustituido por %s en la línea de comandos; el valor por defecto es '/dev/null' que casi seguro no es lo que quieres, así que normalmente lo anularás especificando un nombre de archivo.

plist puede ser una lista que contenga parámetros con nombre; el valor por defecto es simplemente una lista vacía. Cada entrada de la lista debe ser una cadena que contenga el nombre del parámetro, un signo igual ('=') y el valor del parámetro. Las entradas de mailcap pueden contener parámetros con nombre como %{foo}, que serán reemplazados por el valor del parámetro llamado “foo”. Por ejemplo, si la línea de comandos showpartial %{id} %{number} %{total} estaba en un archivo mailcap, y plist estaba establecido como ['id=1', 'number=2', 'total=3'], la línea de comandos resultante sería 'showpartial 1 2 3'.

En un archivo mailcap, el campo «test» puede especificarse opcionalmente para probar alguna condición externa (como la arquitectura de la máquina, o el sistema de ventanas en uso) para determinar si se aplica o no la línea mailcap. La función findmatch() comprobará automáticamente dichas condiciones y omitirá la entrada si la comprobación falla.

Distinto en la versión 3.9.16: To prevent security issues with shell metacharacters (symbols that have special effects in a shell command line), findmatch will refuse to inject ASCII characters other than alphanumerics and @+=:,./-_ into the returned command line.

If a disallowed character appears in filename, findmatch will always return (None, None) as if no entry was found. If such a character appears elsewhere (a value in plist or in MIMEtype), findmatch will ignore all mailcap entries which use that value. A warning will be raised in either case.

mailcap.getcaps()

Retorna un diccionario que mapea los tipos de MIME a una lista de entradas de archivos mailcap. Este diccionario debe ser pasado a la función findmatch(). Una entrada se almacena como una lista de diccionarios, pero no debería ser necesario conocer los detalles de esta representación.

La información se deriva de todos los archivos mailcap que se encuentran en el sistema. Los ajustes en el archivo mailcap del usuario $HOME/.mailcap anularán los ajustes en los archivos mailcap del sistema /etc/mailcap, /usr/etc/mailcap, y /usr/local/etc/mailcap.

Un ejemplo de uso:

>>> import mailcap
>>> d = mailcap.getcaps()
>>> mailcap.findmatch(d, 'video/mpeg', filename='tmp1223')
('xmpeg tmp1223', {'view': 'xmpeg %s'})

msilib — Leer y escribir archivos Microsoft Installer

Código fuente: Lib/msilib/__init__.py [https://github.com/python/cpython/tree/3.9/Lib/msilib/__init__.py]

Obsoleto desde la versión 3.11: The msilib module is deprecated (see PEP 594 [https://www.python.org/dev/peps/pep-0594#msilib] for details).

El msilib soporta la creación de archivos Microsoft Installer (.msi). Como estos archivos a menudo contienen archivos cabinet (.cab) embebidos, se expone también una API para crear archivos CAB. El soporte para leer archivos .cab todavía no está implementado; el soporte a lectura de base de datos .msi es posible.

Este paquete se centra en proveer acceso completo a todas las tablas de un archivo .msi, por lo que se puede considerar una API de bajo nivel. Dos aplicaciones principales de este paquete son el comando bdist_msi de distutils, y la creación del propio paquete instalador de Python (aunque utiliza una versión diferente de msilib).

El contenido del paquete se puede dividir en cuatro partes: rutinas CAB de bajo nivel, rutinas MSI de bajo nivel, rutinas MSI de alto nivel, y estructuras de tabla estándar.

msilib.FCICreate(cabname, files)

Crea un nuevo archivo CAB llamado cabname. files debe ser una lista de tuplas, donde cada una contiene el nombre del archivo en disco, y el nombre del archivo dentro del archivo CAB.

Los archivos son añadidos al archivo CAB en el orden en el cual aparecen en la lista. Todos los archivos son añadidos a un solo archivo CAB, utilizando el algoritmo de compresión MSZIP.

Las retrollamadas a Python para los diferentes pasos de la creación de MSI no están actualmente expuestas.

msilib.UuidCreate()

Retorna la representación de un nuevo identificador único como cadena de caracteres. Esto envuelve las funciones UuidCreate() y UuidToString() de la API de Windows.

msilib.OpenDatabase(path, persist)

Retorna una nueva base de datos llamando a MsiOpenDatabase. path es el nombre del archivo MSI; persist puede ser una de las constantes MSIDBOPEN_CREATEDIRECT, MSIDBOPEN_CREATE, MSIDBOPEN_DIRECT, MSIDBOPEN_READONLY o MSIDBOPEN_TRANSACT, y puede incluir la bandera MSIDBOPEN_PATCHFILE. El significado de estas banderas se puede consultar en la documentación de Microsoft; dependiendo de las banderas, se abrirá una base de datos existente, o se creará una nueva.

msilib.CreateRecord(count)

Retorna un nuevo objeto de registro llamando a MSICreateRecord(). count es el número de campos del registro.

msilib.init_database(name, schema, ProductName, ProductCode, ProductVersion, Manufacturer)

Crea y retorna una nueva base de datos name, la inicializa con schema, y establece las propiedades ProductName, ProductCode, ProductVersion y Manufacturer.

schema debe ser un objeto módulo que contenga los atributos tables y _Validation_records; normalmente se debería usar msilib.schema.

La base de datos contendrá únicamente el esquema y los registros de validación cuando esta función retorne.

msilib.add_data(database, table, records)

Añade todos los records de la tabla llamada table a database.

El argumento table debe ser una de las tablas predefinidas en el esquema MSI, como 'Feature', 'File', 'Component', 'Dialog', 'Control', etc.

records debería ser una lista de tuplas, donde cada una contenga todos los campos de un registro, acorde al esquema de la tabla. Para los campos opcionales se puede asignar None.

Los valores de los campos pueden ser enteros, cadenas de caracteres o instancias de la clase Binary.

class msilib.Binary(filename)

Representa entradas en la tabla Binary; insertar un objeto así utilizando add_data() lee el archivo llamado filename en la tabla.

msilib.add_tables(database, module)

Añade todos los contenidos de la tabla de module a database. module debe contener un atributo tables, que liste todas las tablas cuyos contenidos deban ser añadidos, y un atributo por tabla que contenga el propio contenido.

Esto suele utilizarse para instalar las tablas secuenciales.

msilib.add_stream(database, name, path)

Añade el archivo path en la tabla _Stream de database, con el nombre del flujo name.

msilib.gen_uuid()

Retorna un nuevo UUID, en el formato que MSI suele requerir (entre llaves, con todos los dígitos hexadecimales en mayúsculas).

Ver también

FCICreate [https://msdn.microsoft.com/en-us/library/bb432265.aspx] UuidCreate [https://msdn.microsoft.com/en-us/library/windows/desktop/aa379205.aspx] UuidToString [https://msdn.microsoft.com/en-us/library/windows/desktop/aa379352.aspx]

Objetos Database

Database.OpenView(sql)

Retorna un objeto de vista, llamando a MSIDatabaseOpenView(). sql es la sentencia SQL a ejecutar.

Database.Commit()

Persiste (commit) los cambios pendientes en la transacción actual, llamando a MSIDatabaseCommit().

Database.GetSummaryInformation(count)

Retorna un nuevo objeto de información resumida, llamando a MsiGetSummaryInformation(). count es el número máximo de valores actualizados.

Database.Close()

Cierra el objeto de base de datos, mediante MsiCloseHandle().

Nuevo en la versión 3.7.

Ver también

MSIDatabaseOpenView [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370082.aspx] MSIDatabaseCommit [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370075.aspx] MSIGetSummaryInformation [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370301.aspx] MsiCloseHandle [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370067.aspx]

Objetos View

View.Execute(params)

Ejecuta la consulta SQL de la vista, mediante MSIViewExecute(). Si params no es None, es un registro que describe los valores actuales de los tokens del parámetro en la consulta.

View.GetColumnInfo(kind)

Retorna un registro que describe las columnas de la vista, llamando a MsiViewGetColumnInfo(). kind puede ser MSICOLINFO_NAMES o MSICOLINFO_TYPES.

View.Fetch()

Retorna un registro de resultado de la consulta, llamando a MsiViewFetch().

View.Modify(kind, data)

Modifica la vista, llamando a MsiViewModify(). kind puede ser MSIMODIFY_SEEK, MSIMODIFY_REFRESH, MSIMODIFY_INSERT, MSIMODIFY_UPDATE, MSIMODIFY_ASSIGN, MSIMODIFY_REPLACE, MSIMODIFY_MERGE, MSIMODIFY_DELETE, MSIMODIFY_INSERT_TEMPORARY, MSIMODIFY_VALIDATE, MSIMODIFY_VALIDATE_NEW, MSIMODIFY_VALIDATE_FIELD o MSIMODIFY_VALIDATE_DELETE.

data debe ser un registro que describa los nuevos datos.

View.Close()

Cierra la vista, mediante MsiViewClose().

Ver también

MsiViewExecute [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370513.aspx] MSIViewGetColumnInfo [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370516.aspx] MsiViewFetch [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370514.aspx] MsiViewModify [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370519.aspx] MsiViewClose [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370510.aspx]

Objetos Summary Information

SummaryInformation.GetProperty(field)

Retorna una propiedad del resumen, mediante MsiSummaryInfoGetProperty(). field es el nombre de la propiedad, y puede ser una de las constantes: PID_CODEPAGE, PID_TITLE, PID_SUBJECT, PID_AUTHOR, PID_KEYWORDS, PID_COMMENTS, PID_TEMPLATE, PID_LASTAUTHOR, PID_REVNUMBER, PID_LASTPRINTED, PID_CREATE_DTM, PID_LASTSAVE_DTM, PID_PAGECOUNT, PID_WORDCOUNT, PID_CHARCOUNT, PID_APPNAME o PID_SECURITY.

SummaryInformation.GetPropertyCount()

Retorna el número de propiedades del resumen, mediante MsiSummaryInfoGetPropertyCount().

SummaryInformation.SetProperty(field, value)

Establece una propiedad mediante MsiSummaryInfoSetProperty(). field puede tener los mismos valores que en GetProperty(); value es el nuevo valor de la propiedad. Los tipos de los valores pueden ser enteros o cadenas de caracteres.

SummaryInformation.Persist()

Escribe las propiedades modificadas al flujo de información resumida, mediante MsiSummaryInfoPersist().

Ver también

MsiSummaryInfoGetProperty [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370409.aspx] MsiSummaryInfoGetPropertyCount [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370488.aspx] MsiSummaryInfoSetProperty [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370491.aspx] MsiSummaryInfoPersist [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370490.aspx]

Objetos Record

Record.GetFieldCount()

Retorna el número de campos del registro, mediante MsiRecordGetFieldCount().

Record.GetInteger(field)

Retorna el valor de field como entero cuando sea posible. field debe ser un entero.

Record.GetString(field)

Retorna el valor de field como una cadena de caracteres cuando sea posible. field debe ser un entero.

Record.SetString(field, value)

Establece field a value mediante MsiRecordSetString(). field debe ser un entero; value una cadena de caracteres.

Record.SetStream(field, value)

Establece field al contenido del archivo llamado value, mediante MsiRecordSetStream(). field debe ser un entero; value una cadena de caracteres.

Record.SetInteger(field, value)

Establece field a value mediante MsiRecordSetInteger(). field y value deben ser enteros.

Record.ClearData()

Establece todos los campos del registro a 0, mediante MsiRecordClearData().

Ver también

MsiRecordGetFieldCount [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370366.aspx] MsiRecordSetString [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370373.aspx] MsiRecordSetStream [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370372.aspx] MsiRecordSetInteger [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370371.aspx] MsiRecordClearData [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370364.aspx]

Errores

Todos los wrappers sobre funciones MSI lanzan MSIError; la cadena de caracteres dentro de la excepción contendrá más detalles.

Objetos CAB

class msilib.CAB(name)

La clase CAB representa un archivo CAB. Durante la construcción del MSI, los archivos se añadirán simultáneamente a la table Files, y a un archivo CAB. Después, cuando todos los archivos sean añadidos, el archivo CAB puede ser sobreescrito, y finalmente añadido al archivo MSI.

name es el nombre del archivo CAB dentro del archivo MSI.

append(full, file, logical)

Añade el archivo con la ruta full al archivo CAB, bajo el nombre logical. Si ya existe algún archivo llamado logical, se creará un nuevo archivo.

Retorna el índice del archivo dentro del archivo CAB, y el nuevo nombre del archivo dentro del archivo CAB.

commit(database)

Genera un archivo CAB, lo añade como un flujo al archivo MSI, lo añade a la tabla Media, y elimina el archivo generado del disco.

Objetos Directory

class msilib.Directory(database, cab, basedir, physical, logical, default[, componentflags])

Crea un nuevo directorio en la tabla Directory. Hay un componente actual en cada punto temporal para el directorio, el cual es, o bien explícitamente creado mediante start_component(), o bien implícito cuando los archivos se añaden por primera vez. Los archivos son añadidos en el componente actual, y al archivo CAB. Para crear un directorio, un objeto de directorio base tiene que ser especificado (puede ser None), la ruta al directorio físico, y un nombre de directorio lógico. default especifica el zócalo DefaultDir en la table de directorio. componentflags especifica las banderas por defecto que obtendrán los nuevos componentes.

start_component(component=None, feature=None, flags=None, keyfile=None, uuid=None)

Añade una entrada a la tabla Component, y hace este componente el actual componente para este directorio. Si no se especifica ningún nombre de componente, se usará el nombre del directorio. Si no se especifica ninguna feature, se usará la característica actual. Si no se especifican flags, se usarán las banderas por defecto del directorio. Si no se especifica ningún keyfile, el KeyPath quedará nulo en la tabla Component.

add_file(file, src=None, version=None, language=None)

Añade el archivo al componente actual del directorio, inicializando uno nuevo si no existe un componente actual. Por defecto, el nombre del archivo en el origen y la tabla del archivo serán idénticos. Si se especifica el archivo src, se interpretará como relativo al directorio actual. Opcionalmente, se pueden especificar una version y un language para la entrada en la tabla File.

glob(pattern, exclude=None)

Añade una lista de archivos al componente actual, como se especifica en el patrón glob. Se pueden excluir archivos individualmente en la lista exclude.

remove_pyc()

Elimina los archivos .pyc al desinstalar.

Ver también

Directory Table [https://msdn.microsoft.com/en-us/library/windows/desktop/aa368295.aspx] File Table [https://msdn.microsoft.com/en-us/library/windows/desktop/aa368596.aspx] Component Table [https://msdn.microsoft.com/en-us/library/windows/desktop/aa368007.aspx] FeatureComponents Table [https://msdn.microsoft.com/en-us/library/windows/desktop/aa368579.aspx]

Features

class msilib.Feature(db, id, title, desc, display, level=1, parent=None, directory=None, attributes=0)

Añade un nuevo registro a la tabla Feature, usando los valores id, parent.id, title, desc, display, level, directory y attributes. El objeto de característica resultante se le puede dar al método start_component() de Directory.

set_current()

Establece esta característica como la actual característica de msilib. Los nuevos componentes serán añadidos automáticamente a la característica por defecto, a no ser que se especifique explícitamente una característica.

Ver también

Feature Table [https://msdn.microsoft.com/en-us/library/windows/desktop/aa368585.aspx]

Clases GUI

msilib dispone de varias clases que envuelven a las tablas GUI en una base de datos MSI. Sin embargo, no se dispone de ninguna interfaz de usuario estándar; se puede usar bdist_msi para crear archivos MSI con una interfaz de usuario para instalar paquetes Python.

class msilib.Control(dlg, name)

Clase base de los controles de diálogo. dlg es el objeto de diálogo al que pertenece el control, y name es el nombre del control.

event(event, argument, condition=1, ordering=None)

Crea una entrada en la tabla ControlEvent para este control.

mapping(event, attribute)

Crea una entrada en la tabla EventMapping para este control.

condition(action, condition)

Crea una entrada en la tabla ControlCondition para este control.

class msilib.RadioButtonGroup(dlg, name, property)

Crea un control de botón de selección llamado name. property es la propiedad del instalador que se establece cuando un botón de selección es seleccionado.

add(name, x, y, width, height, text, value=None)

Añade un botón de selección llamado name al grupo, en las coordenadas x, y, width, height, con la etiqueta text. Si value es None, se establecerá por defecto a name.

class msilib.Dialog(db, name, x, y, w, h, attr, title, first, default, cancel)

Retorna un nuevo objeto Dialog. Se creará una entrada en la tabla Dialog con las coordenadas, atributos de diálogo y título especificados, así como los nombres del primer control y los controles por defecto y de cancelación.

control(name, type, x, y, width, height, attributes, property, text, control_next, help)

Retorna un nuevo objeto Control. Se creará una entrada en la tabla Control con los parámetros especificados.

Este es un método genérico; para tipos específicos hay métodos especializados disponibles.

text(name, x, y, width, height, attributes, text)

Añade y retorna un control Text.

bitmap(name, x, y, width, height, text)

Añade y retorna un control Bitmap.

line(name, x, y, width, height)

Añade y retorna un control Line.

pushbutton(name, x, y, width, height, attributes, text, next_control)

Añade y retorna un control PushButton.

radiogroup(name, x, y, width, height, attributes, property, text, next_control)

Añade y retorna un control RadioButtonGroup.

checkbox(name, x, y, width, height, attributes, property, text, next_control)

Añade y retorna un control CheckBox.

Ver también

Dialog Table [https://msdn.microsoft.com/en-us/library/windows/desktop/aa368286.aspx] Control Table [https://msdn.microsoft.com/en-us/library/windows/desktop/aa368044.aspx] Control Types [https://msdn.microsoft.com/en-us/library/windows/desktop/aa368039.aspx] ControlCondition Table [https://msdn.microsoft.com/en-us/library/windows/desktop/aa368035.aspx] ControlEvent Table [https://msdn.microsoft.com/en-us/library/windows/desktop/aa368037.aspx] EventMapping Table [https://msdn.microsoft.com/en-us/library/windows/desktop/aa368559.aspx] RadioButton Table [https://msdn.microsoft.com/en-us/library/windows/desktop/aa370962.aspx]

Tablas pre-calculadas

msilib proporciona algunos subpaquetes que contienen únicamente definiciones de esquema y tabla. Actualmente, estas definiciones están basadas en la versión 2.0 de MSI.

msilib.schema

Este es el esquema estándar MSI para MSI 2.0, con la variable tables proporcionando una lista de definición de tablas, y _Validation_records proporcionando la información para la validación MSI.

msilib.sequence

Este módulo alberga los contenidos de la tabla para las tablas de secuencia estándar: AdminExecuteSequence, AdminUISequence, AdvtExecuteSequence, InstallExecuteSequence, and InstallUISequence.

msilib.text

Este módulo contiene definiciones para las tablas UIText y ActionText, para las acciones estándar del instalador.

nis — Interfaz a Sun’s NIS (Páginas amarillas)

Obsoleto desde la versión 3.11: The nis module is deprecated (see PEP 594 [https://www.python.org/dev/peps/pep-0594#nis] for details).

El modulo nis da una envoltura alrededor de la biblioteca NIS, útil para la administración central de varios hosts.

Debido a que la NIS sólo existe en sistemas Unix, este módulo sólo está disponible para Unix.

El módulo nis define las siguientes funciones:

nis.match(key, mapname, domain=default_domain)

Retorna la coincidencia para key en el mapa mapname, o retorna un error (nis.error) si es none. Ambas deben ser cadenas, key es 8 bits limpios. El valor de retorno es un array arbitrario de bytes (puede contener NULL y otros placeres).

Tenga en cuenta que mapname se comprueba primero si es un alias de otro nombre.

El argumento domain permite anular el dominio NIS utilizado para la búsqueda. Si no se especifica, la búsqueda se realiza en el dominio NIS por defecto.

nis.cat(mapname, domain=default_domain)

Retorna un diccionario de mapeo de key a value de tal manera que match(key, mapname)==value. Tenga en cuenta que tanto las claves como los valores del diccionario son arreglos arbitrarios de bytes.

Tenga en cuenta que mapname se comprueba primero si es un alias de otro nombre.

El argumento domain permite anular el dominio NIS utilizado para la búsqueda. Si no se especifica, la búsqueda se realiza en el dominio NIS por defecto.

nis.maps(domain=default_domain)

Retorna una lista de todos los mapas válidos.

El argumento domain permite anular el dominio NIS utilizado para la búsqueda. Si no se especifica, la búsqueda se realiza en el dominio NIS por defecto.

nis.get_default_domain()

Retorna el dominio NIS por defecto del sistema.

El módulo nis define la siguiente excepción:

exception nis.error

Un error que se produce cuando una función NIS retorna un código de error.

nntplib — Protocolo de cliente NNTP

Código fuente: Lib/nntplib.py [https://github.com/python/cpython/tree/3.9/Lib/nntplib.py]

Obsoleto desde la versión 3.11: The nntplib module is deprecated (see PEP 594 [https://www.python.org/dev/peps/pep-0594] for details).

Este módulo define la clase NNTP que implementa el lado del cliente del Protocolo de transferencia de noticias por red. Se puede utilizar para implementar un lector o póster de noticias, o procesadores de noticias automatizados. Es compatible con RFC 3977 [https://tools.ietf.org/html/rfc3977.html] así como con los antiguos RFC 977 [https://tools.ietf.org/html/rfc977.html] y RFC 2980 [https://tools.ietf.org/html/rfc2980.html].

Aquí hay dos pequeños ejemplos de cómo se puede utilizar. Para enumerar algunas estadísticas sobre un grupo de noticias e imprimir los temas de los últimos 10 artículos:

>>> s = nntplib.NNTP('news.gmane.io')
>>> resp, count, first, last, name = s.group('gmane.comp.python.committers')
>>> print('Group', name, 'has', count, 'articles, range', first, 'to', last)
Group gmane.comp.python.committers has 1096 articles, range 1 to 1096
>>> resp, overviews = s.over((last - 9, last))
>>> for id, over in overviews:
...     print(id, nntplib.decode_header(over['subject']))
...
1087 Re: Commit privileges for Łukasz Langa
1088 Re: 3.2 alpha 2 freeze
1089 Re: 3.2 alpha 2 freeze
1090 Re: Commit privileges for Łukasz Langa
1091 Re: Commit privileges for Łukasz Langa
1092 Updated ssh key
1093 Re: Updated ssh key
1094 Re: Updated ssh key
1095 Hello fellow committers!
1096 Re: Hello fellow committers!
>>> s.quit()
'205 Bye!'

Para publicar un artículo desde un archivo binario (esto supone que el artículo tiene encabezados válidos y que tienes permitido publicar en el grupo de noticias en particular):

>>> s = nntplib.NNTP('news.gmane.io')
>>> f = open('article.txt', 'rb')
>>> s.post(f)
'240 Article posted successfully.'
>>> s.quit()
'205 Bye!'

El módulo en sí define las siguientes clases:

class nntplib.NNTP(host, port=119, user=None, password=None, readermode=None, usenetrc=False[, timeout])

Retorna un nuevo objeto NNTP que representa una conexión con el servidor NNTP ejecutándose en el host host, escuchando en el puerto port. Se puede especificar un timeout opcional para la conexión de socket. Si se proporcionan las credenciales opcionales user y password, o si hay credenciales adecuadas en /.netrc y el indicador opcional usenetrc es verdadero, los comandos AUTHINFO USER y AUTHINFO PASS se utilizan para identificar y autenticar al usuario en el servidor. Si el indicador opcional readermode es verdadero, se envía un comando mode reader antes de que se realice la autenticación. El modo de lector a veces es necesario si se conecta a un servidor NNTP en el equipo local y tiene la intención de llamar a comandos específicos del lector, como group. Si obtienes un valor inesperado NNTPPermanentError, es posible que debas establecer readermode. La clase NNTP admite la instrucción with para consumir incondicionalmente las excepciones OSError y para cerrar la conexión NNTP cuando haya terminado, e.g.:

>>> from nntplib import NNTP
>>> with NNTP('news.gmane.io') as n:
...     n.group('gmane.comp.python.committers')
...
('211 1755 1 1755 gmane.comp.python.committers', 1755, 1, 1755, 'gmane.comp.python.committers')
>>>

Genera un evento de auditoría nntplib.connect con los argumentos self, host, port.

Genera un evento de auditoría nntplib.putline con los argumentos self, line.

Distinto en la versión 3.2: usenetrc es ahora False por defecto.

Distinto en la versión 3.3: El soporte para la declaración with fue añadido.

Distinto en la versión 3.9: Si el parámetro timeout se establece en cero, lanzará un ValueError para evitar la creación de un socket sin bloqueo.

class nntplib.NNTP_SSL(host, port=563, user=None, password=None, ssl_context=None, readermode=None, usenetrc=False[, timeout])

Retorna un nuevo objeto NNTP_SSL, que representa una conexión cifrada con el servidor NNTP ejecutándose en el host host, escuchando en el puerto port. Los objetos NNTP_SSL tienen los mismos métodos que los objetos NNTP. Si se omite el port se utiliza el puerto 563 (NNTPS). ssl_context también es opcional, y también el objeto SSLContext. Por favor, lea Consideraciones de seguridad para conocer las buenas prácticas. Todos los demás parámetros se comportan igual que para NNTP.

Tenga en cuenta que SSL-on-563 no es recomendado por RFC 4642 [https://tools.ietf.org/html/rfc4642.html], en favor de STARTTLS como se describe abajo. Sin embargo, algunos servidores solo admiten el primero.

Genera un evento de auditoría nntplib.connect con los argumentos self, host, port.

Genera un evento de auditoría nntplib.putline con los argumentos self, line.

Nuevo en la versión 3.2.

Distinto en la versión 3.4: La clase ahora admite la verificación del nombre de host con ssl.SSLContext.check_hostname e Indicador del nombre del servidor (SNI por sus siglas en inglés, consulte ssl.HAS_SNI).

Distinto en la versión 3.9: Si el parámetro timeout se establece en cero, lanzará un ValueError para evitar la creación de un socket sin bloqueo.

exception nntplib.NNTPError

Derivado de la excepción estándar Exception, esta es la clase base para todas las excepciones generadas por el módulo nntplib. Las instancias de esta clase tienen el siguiente atributo:

response

La respuesta del servidor, si está disponible, como un objeto str.

exception nntplib.NNTPReplyError

Excepción generada cuando se recibe una respuesta inesperada del servidor.

exception nntplib.NNTPTemporaryError

Excepción generada cuando se recibe un código de respuesta dentro del rango del 400–499.

exception nntplib.NNTPPermanentError

Excepción generada cuando se recibe un código de respuesta dentro del rango del 500–599.

exception nntplib.NNTPProtocolError

Excepción generada cuando se recibe una respuesta del servidor que no comienza con un dígito dentro del rango 1–5.

exception nntplib.NNTPDataError

Excepción generada cuando hay algún error en los datos de la respuesta.

Objetos NNTP

Cuando están conectados, los objetos NNTP y NNTP_SSL admiten los siguientes métodos y atributos.

Atributos

NNTP.nntp_version

Un entero que representa la versión del protocolo NNTP compatible con el servidor. En la práctica, esto debería ser 2 para los servidores que anuncian el cumplimiento RFC 3977 [https://tools.ietf.org/html/rfc3977.html] y 1 para otros.

Nuevo en la versión 3.2.

NNTP.nntp_implementation

Cadena que describe el nombre de software y la versión del servidor NNTP, o None si el servidor no lo anuncia.

Nuevo en la versión 3.2.

Métodos

La response que es retornada como el primer elemento de la tupla de retorno de casi todos los métodos es la respuesta del servidor: una cadena que comienza con un código de tres dígitos. Si la respuesta del servidor indica un error, el método genera una de las excepciones anteriores.

Muchos de los métodos siguientes toman un argumento opcional de solamente palabra clave file. Cuando se proporciona el argumento file, debe ser un file object abierto para la escritura binaria o el nombre de un archivo en disco a ser escrito. El método escribirá los datos retornados por el servidor (excepto la línea de respuesta y el punto de terminación) en el archivo; cualquier lista de líneas, tuplas u objetos que el método retorna normalmente estará vacía.

Distinto en la versión 3.2: Muchos de los siguientes métodos se han rediseñado y corregido, lo que los hace incompatibles con sus contrapartes 3.1.

NNTP.quit()

Envía un comando QUIT y cierra la conexión. Una vez que se ha invocado este método, no se debe invocar ningún otro método del objeto NNTP.

NNTP.getwelcome()

Retorna el mensaje de bienvenida enviado por el servidor en respuesta a la conexión inicial. (Este mensaje a veces contiene aclaraciones o información de ayuda que puede ser relevante para el usuario.)

NNTP.getcapabilities()

Retorna las capacidades RFC 3977 [https://tools.ietf.org/html/rfc3977.html] anunciadas por el servidor, como una instancia dict mapeando nombres de capacidades a listas de valores (posiblemente vacías). En los servidores heredados que no entienden el comando CAPABILITIES, se retorna un diccionario vacío en su lugar.

>>> s = NNTP('news.gmane.io')
>>> 'POST' in s.getcapabilities()
True

Nuevo en la versión 3.2.

NNTP.login(user=None, password=None, usenetrc=True)

Envía comandos AUTHINFO con el nombre de usuario y la contraseña. Si user y password son None y usenetrc es verdadero, se utilizarán las credenciales de ~/.netrc si su uso es posible.

A menos que se retrase intencionalmente, el inicio de sesión se realiza normalmente durante la inicialización del objeto NNTP y no es necesario invocar esta función por separado. Para forzar el retraso de la autenticación, no debes establecer user o password al crear el objeto y debes establecer usenetrc en False.

Nuevo en la versión 3.2.

NNTP.starttls(context=None)

Envía un comando STARTTLS. Esto habilitará el cifrado en la conexión NNTP. El argumento context es opcional y debe ser el objeto ssl. SSLContext. Por favor lea Consideraciones de seguridad para conocer las buenas prácticas.

Tenga en cuenta que esto no se puede hacer después de que se haya transmitido la información de autenticación y la autenticación se produce de forma predeterminada, si es posible, durante la inicialización de un objeto NNTP. Consulte NNTP.login() para obtener información sobre cómo suprimir este comportamiento.

Nuevo en la versión 3.2.

Distinto en la versión 3.4: El método ahora admite la comprobación del nombre de host con ssl. SSLContext.check_hostname y Indicador del nombre del servidor (SNI por sus siglas en inglés, consulte ssl.HAS_SNI).

NNTP.newgroups(date, *, file=None)

Envía un comando NEWGROUPS. El argumento date debe ser un objeto datetime.date o datetime.datetime. Retorna un par (response, groups) donde groups es una lista que representa los grupos que son nuevos desde la fecha determinada. Sin embargo, si se proporciona file, entonces groups estará vacío.

>>> from datetime import date, timedelta
>>> resp, groups = s.newgroups(date.today() - timedelta(days=3))
>>> len(groups)
85
>>> groups[0]
GroupInfo(group='gmane.network.tor.devel', last='4', first='1', flag='m')

NNTP.newnews(group, date, *, file=None)

Envía un comando NEWNEWS. Aquí, group es un nombre de grupo o '*', y date tiene el mismo significado que para newgroups(). Retorna un par (response, articles) donde articles es una lista de identificadores de mensaje.

Este comando es inhabilitado frecuentemente por los administradores del servidor NNTP.

NNTP.list(group_pattern=None, *, file=None)

Envía un comando LIST o LIST ACTIVE. Retorna un par (response, list) donde list es una lista de tuplas que representan todos los grupos disponibles desde este servidor NNTP, opcionalmente coincidiendo con el patrón de cadena group_pattern. Cada tupla tiene el formato (group, last, first, flag), donde group es un nombre de grupo, last y first son los últimos y primeros números de artículo, y flag suele tomar uno de estos valores:

y: Se permiten publicaciones locales y artículos de pares.

m: El grupo está moderado y todas las publicaciones deben ser aprobadas.

n: No se permiten publicaciones locales, solo artículos de pares.

j: Los artículos de pares se archivan en el grupo de basura en su lugar.

x: No hay publicaciones locales y los artículos de pares son ignorados.

=foo.bar: Los artículos se archivan en el grupo foo.bar en su lugar.

Si flag tiene otro valor, el estado del grupo de noticias debe considerarse como desconocido.

Este comando puede devolver resultados muy grandes, especialmente si no se especifica group_pattern. Es mejor almacenar en caché los resultados sin conexión a menos que realmente necesite actualizarlos.

Distinto en la versión 3.2: group_pattern fue añadido.

NNTP.descriptions(grouppattern)

Envía un comando LIST NEWSGROUPS, donde grouppattern es una cadena comodín como se especifica en RFC 3977 [https://tools.ietf.org/html/rfc3977.html] (es esencialmente lo mismo que las cadenas comodín de shell DOS o UNIX). Retorna un par (response, descriptions), donde descriptions es un diccionario que asigna nombres de grupos a descripciones textuales.

>>> resp, descs = s.descriptions('gmane.comp.python.*')
>>> len(descs)
295
>>> descs.popitem()
('gmane.comp.python.bio.general', 'BioPython discussion list (Moderated)')

NNTP.description(group)

Obtiene una descripción para un único grupo group. Si más de un grupo coincide (si “group” es una cadena comodín real), retorna la primera coincidencia. Si ningún grupo coincide, retorna una cadena vacía.

Esto elude el código de respuesta del servidor. Si necesita el código de respuesta, use descriptions().

NNTP.group(name)

Envía un comando GROUP, donde name es el nombre del grupo. El grupo se selecciona como el grupo actual, si este existe. Retorna una tupla (response, count, first, last, name) donde count es el número (estimado) de artículos en el grupo, first es el primer número de artículo del grupo, last es el último número de artículo en el grupo y name es el nombre del grupo.

NNTP.over(message_spec, *, file=None)

Envía un comando OVER o un comando XOVER en servidores heredados. message_spec puede ser una cadena que represente un identificador de mensaje o una tupla de números (first, None) que indique un rango de artículos en el grupo actual, o una tupla (first, None) que indique un rango de artículos comenzando desde first hasta el último artículo del grupo actual, o None para seleccionar el artículo actual en el grupo actual.

Retorna un par (response, overviews). overviews es una lista de tuplas del tipo (article_number, overview), una para cada artículo seleccionado por message_spec. Cada overview es un diccionario con el mismo número de elementos, pero este número depende del servidor. Estos elementos son encabezados de mensajes (la clave es entonces el nombre del encabezado en minúsculas) o elementos de metadatos (la clave es entonces el nombre de los metadatos precedido de ":"). Se garantiza la presencia de los siguientes elementos por la especificación NNTP:

los encabezados subject, from, date, message-id y references

los metadatos :bytes: el número de bytes en todo el artículo sin procesar (incluidos los encabezados y el cuerpo)

los metadatos :lines: el número de líneas en el cuerpo del artículo

El valor de cada elemento es una cadena o None si no está presente.

Es aconsejable utilizar la función decode_header() en los valores del encabezado cuando pueden contener caracteres no-ASCII:

>>> _, _, first, last, _ = s.group('gmane.comp.python.devel')
>>> resp, overviews = s.over((last, last))
>>> art_num, over = overviews[0]
>>> art_num
117216
>>> list(over.keys())
['xref', 'from', ':lines', ':bytes', 'references', 'date', 'message-id', 'subject']
>>> over['from']
'=?UTF-8?B?Ik1hcnRpbiB2LiBMw7Z3aXMi?= <martin@v.loewis.de>'
>>> nntplib.decode_header(over['from'])
'"Martin v. Löwis" <martin@v.loewis.de>'

Nuevo en la versión 3.2.

NNTP.help(*, file=None)

Envía un comando HELP. Retorna un par (response, list) donde list es una lista de cadenas de caracteres de ayuda.

NNTP.stat(message_spec=None)

Envía un comando STAT, donde message_spec es un identificador de mensaje (incluido en '<' y '>') o un número de artículo en el grupo actual. Si se omite message_spec o es None se considera el artículo actual del grupo actual. Retorna un triple (response, number, id) donde number es el número de artículo e id es el identificador del mensaje.

>>> _, _, first, last, _ = s.group('gmane.comp.python.devel')
>>> resp, number, message_id = s.stat(first)
>>> number, message_id
(9099, '<20030112190404.GE29873@epoch.metaslash.com>')

NNTP.next()

Envía un comando NEXT. Retorna como para stat().

NNTP.last()

Envía un comando LAST. Retorna como para stat().

NNTP.article(message_spec=None, *, file=None)

Envía un comando ARTICLE, donde message_spec tiene el mismo significado que para stat(). Retorna una tupla (response, info) donde info es un namedtuple con tres atributos number, message_id y lines (en ese orden). number es el número de artículo del grupo (o 0 si la información no está disponible), message_id el identificador del mensaje como una cadena y lines una lista de líneas (sin terminar líneas nuevas) que comprende el mensaje sin procesar, incluidos los encabezados y el cuerpo.

>>> resp, info = s.article('<20030112190404.GE29873@epoch.metaslash.com>')
>>> info.number
0
>>> info.message_id
'<20030112190404.GE29873@epoch.metaslash.com>'
>>> len(info.lines)
65
>>> info.lines[0]
b'Path: main.gmane.org!not-for-mail'
>>> info.lines[1]
b'From: Neal Norwitz <neal@metaslash.com>'
>>> info.lines[-3:]
[b'There is a patch for 2.3 as well as 2.2.', b'', b'Neal']

NNTP.head(message_spec=None, *, file=None)

Igual que article(), pero envía un comando HEAD. Las lines retornadas (o escritas a file) solo contendrán los encabezados del mensaje, no el cuerpo.

NNTP.body(message_spec=None, *, file=None)

Igual que article(), pero envía un comando BODY. Las lines retornadas (o escritas a file) solo contendrán los encabezados del mensaje, no el cuerpo.

NNTP.post(data)

Publica un artículo utilizando el comando POST. El argumento data es un file object abierto para la lectura binaria o cualquier iterable de objetos bytes (que representa las líneas sin procesar del artículo que se va a publicar). Debe representar un artículo de noticias bien formado, incluidos los encabezados requeridos. El método post() escapa automáticamente las líneas que comienzan con . y añade la línea de terminación.

Si el método tiene éxito, se retorna la respuesta del servidor. Si el servidor se niega a publicarlo, se genera un NNTPReplyError.

NNTP.ihave(message_id, data)

Envía un comando IHAVE. message_id es el identificador del mensaje que se enviará al servidor (incluido entre '<' y '>'). El parámetro data y el valor de retorno son los mismos que para post().

NNTP.date()

Devuelve un par (response, date). date es un objeto datetime que contiene la fecha y hora actuales del servidor.

NNTP.slave()

Envía un comando SLAVE. Retorna la response del servidor.

NNTP.set_debuglevel(level)

Establece el nivel de depuración de la instancia. Esto controla la cantidad de salida de depuración impresa. El valor por defecto, 0, no produce salida de depuración. Un valor de 1 produce una cantidad moderada de salida de depuración, generalmente una sola línea por solicitud o por respuesta. Un valor de 2 o superior produce la cantidad máxima de salida de depuración, registrando cada línea enviada y recibida en la conexión (incluyendo el texto del mensaje).

Las siguientes son extensiones NNTP opcionales definidas en RFC 2980 [https://tools.ietf.org/html/rfc2980.html]. Algunas de ellas han sido reemplazados por comandos más nuevos en RFC 3977 [https://tools.ietf.org/html/rfc3977.html].

NNTP.xhdr(hdr, str, *, file=None)

Envía un comando XHDR. El argumento hdr es una palabra clave de encabezado, por ejemplo 'subject'. El argumento str debe tener la forma 'first-last' donde first y last son el primer y último número de artículo para buscar. Retorna un par (response, list), donde list es una lista de pares (id, text), donde id es un número de artículo (como una cadena) y text es el texto del encabezado solicitado para ese artículo. Si se proporciona el parámetro file, entonces la salida del comando XHDR se almacena en un archivo. Si file es una cadena, entonces el método abrirá un archivo con ese nombre, que escribirá en él y luego lo cerrará. Si file es un file object, entonces comenzará invocando write() en él para almacenar las líneas de la salida del comando. Si se proporciona file, entonces retorna list o una lista vacía.

NNTP.xover(start, end, *, file=None)

Envía un comando XOVER. start and end son números de artículo que delimitan el rango de artículos a seleccionar. El valor de retorno es el mismo que para over(). Se recomienda usar over() en su lugar, ya que se usará automáticamente el comando más nuevo OVER si está disponible.

Funciones de utilidad

El módulo también define la siguiente función de utilidad:

nntplib.decode_header(header_str)

Decodifica un valor de encabezado, eliminando los caracteres de escape que no sean ASCII. header_str debe ser un objeto str. Se retorna el valor sin escape. Se recomienda utilizar esta función para mostrar algunos encabezados en una forma legible por humanos:

>>> decode_header("Some subject")
'Some subject'
>>> decode_header("=?ISO-8859-15?Q?D=E9buter_en_Python?=")
'Débuter en Python'
>>> decode_header("Re: =?UTF-8?B?cHJvYmzDqG1lIGRlIG1hdHJpY2U=?=")
'Re: problème de matrice'

optparse — Analizador sintáctico (parser) para opciones de línea de comandos

Source code: Lib/optparse.py [https://github.com/python/cpython/tree/3.9/Lib/optparse.py]

Obsoleto desde la versión 3.2: El módulo optparse está obsoleto y no será desarrollado de aquí en adelante. El desarrollo continuará en el módulo argparse.

optparse es una biblioteca más conveniente, flexible y poderosa para analizar opciones de línea de comandos que el antiguo módulo getopt. optparse usa un estilo más declarativo: creas una instancia de OptionParser, le añades las opciones deseadas y realizas el análisis sintáctico de la línea de comandos. optparse permite a los usuarios especificar opciones siguiendo la sintaxis convencional de GNU/POSIX, además de generar mensajes de uso y de ayuda automáticamente.

A continuación puedes ver un ejemplo de uso de optparse mediante un script simple:

from optparse import OptionParser
...
parser = OptionParser()
parser.add_option("-f", "--file", dest="filename",
                  help="write report to FILE", metavar="FILE")
parser.add_option("-q", "--quiet",
                  action="store_false", dest="verbose", default=True,
                  help="don't print status messages to stdout")

(options, args) = parser.parse_args()

Con estas pocas líneas de código, los usuarios de tu script ahora pueden hacer un uso «normal» del mismo mediante la línea de comandos, por ejemplo:

<yourscript> --file=outfile -q

A medida que analiza la línea de comandos, optparse establece los atributos del objeto options retornado por parse_args() basándose en los valores de la línea de comandos proporcionada por el usuario. Cuando parse_args() termina de analizar esta línea de comandos, options.filename será "outfile" y options.verbose será False. optparse admite opciones largas y cortas, fusionar opciones cortas y asociar opciones con sus argumentos de diversas formas. Por lo tanto, las siguientes líneas de comandos son todas equivalentes al ejemplo previo:

<yourscript> -f outfile --quiet
<yourscript> --quiet --file outfile
<yourscript> -q -foutfile
<yourscript> -qfoutfile

Además, los usuarios pueden ejecutar uno de los siguientes:

<yourscript> -h
<yourscript> --help

y optparse imprimirá un breve resumen de las opciones de tu script:

Usage: <yourscript> [options]

Options:
  -h, --help            show this help message and exit
  -f FILE, --file=FILE  write report to FILE
  -q, --quiet           don't print status messages to stdout

donde el valor de yourscript se determina en tiempo de ejecución (normalmente a partir de sys.argv [0]).

Contexto

optparse ha sido diseñado explícitamente para fomentar la creación de programas con interfaces de línea de comandos convencionales y sencillas. Con ese fin en mente, solo admite la sintaxis y semántica de línea de comandos más común y convencionalmente usada en Unix. Si no estás familiarizado con estas convenciones, lee esta sección para familiarizarte con ellas.

Terminología

argumento

una cadena de caracteres ingresada en la línea de comandos y pasada mediante la shell a execl() o execv(). En Python, los argumentos son elementos de sys.argv[1:] (dado que sys.argv[0] es el propio nombre del programa que se está ejecutando). Las shells de Unix también usan el término «word» (“palabra”) para referirse a ellos.

En ocasiones es deseable proporcionar una lista de argumentos que no sea sys.argv[1:], por lo que deberías considerar un “argumento” como “un elemento de sys.argv[1:] o de alguna otra lista proporcionada como sustituto de sys.argv[1:]”.

opción

un argumento utilizado para proporcionar información adicional con la finalidad de guiar o personalizar la ejecución de un programa. Existen muchas sintaxis diferentes para especificar opciones. La sintaxis tradicional de Unix es un guion (“-”) seguido de una sola letra, por ejemplo -x o -F. La sintaxis tradicional de Unix permite además fusionar múltiples opciones en un solo argumento, por ejemplo -x -F es equivalente a -xF. Por otro lado, el proyecto GNU introdujo -- seguido de una serie de palabras separadas por guiones, por ejemplo --file o --dry-run. Estas son las dos únicas sintaxis para opciones que el módulo optparse proporciona.

Algunas de las otras sintaxis para opciones que el mundo ha visto son:

un guion seguido de algunas letras, por ejemplo -pf (esto no es lo mismo que múltiples opciones fusionadas en un solo argumento)

un guion seguido de una palabra completa, por ejemplo -file (esto es técnicamente equivalente a la sintaxis anterior, pero generalmente no se ven ambas en un mismo programa)

un signo más seguido de una sola letra, unas pocas letras o una palabra, por ejemplo +f o +rgb

una barra seguida de una letra, de unas pocas letras o de una palabra, por ejemplo /f o /file

These option syntaxes are not supported by optparse, and they never will be. This is deliberate: the first three are non-standard on any environment, and the last only makes sense if you’re exclusively targeting Windows or certain legacy platforms (e.g. VMS, MS-DOS).

argumento de opción

un argumento que sigue a una opción, está estrechamente asociado con ella y se consume de la lista de argumentos cuando esa opción es consumida. Con optparse, los argumentos de las opciones pueden estar en un argumento separado de su opción:

-f foo
--file foo

o incluidos en el mismo argumento:

-ffoo
--file=foo

Normalmente, una opción dada puede aceptar o no un argumento. Mucha gente desea una característica de «argumentos de opción opcionales», lo que implica que algunas opciones aceptarán un argumento si está presente y no lo aceptarán si no lo está. Esto es algo controvertido, porque hace que el análisis sea ambiguo: si -a toma un argumento opcional y -b es otra opción completamente distinta, ¿cómo interpretamos -ab? Debido a esta ambigüedad, optparse no es compatible con esta funcionalidad.

argumento posicional

es algo que queda en la lista de argumentos después de que las opciones hayan sido analizadas sintácticamente, es decir, después de que las opciones y sus argumentos hayan sido analizados y eliminados de la lista de argumentos.

opción requerida

es una opción que debe proporcionarse forzosamente en la línea de comandos. Ten en cuenta que la frase «opción requerida» se contradice a si misma. optparse no te impide implementar opciones requeridas, pero tampoco brinda mucha ayuda para ello.

Por ejemplo, considera esta hipotética linea de comandos:

prog -v --report report.txt foo bar

-v y --report son ambas opciones. report.txt es un argumento de opción, suponiendo que --report toma un argumento. En cambio, foo y bar son ambos argumentos posicionales.

¿Qué finalidad tienen las opciones?

Las opciones se utilizan para poder proporcionar información adicional con el fin de ajustar o personalizar la ejecución de un programa. Por si aún no ha quedado claro, las opciones suelen ser opcionales. Un programa debería poder ejecutarse sin problemas sin ninguna opción. (Elija un programa aleatorio del conjunto de herramientas de Unix o GNU. ¿Puede ejecutarse sin ninguna opción y aún así tener sentido? Las principales excepciones son find, tar y dd—los cuales son todos bichos raros mutantes que han sido apropiadamente criticados por su sintaxis no estándar y por tener interfaces confusas).

Como se ha comentado, mucha gente quiere que sus programas tengan «opciones requeridas». Pero pensemos en ello detenidamente. ¡Si es necesario, entonces no es opcional! Si hay una pieza de información absolutamente requerida para que tu programa pueda ejecutarse correctamente no uses opciones, para eso están los argumentos posicionales.

Como ejemplo de un buen diseño de una interfaz de línea de comandos, considera la humilde herramienta cp para copiar archivos. No tiene mucho sentido intentar copiar archivos sin proporcionar un destino y al menos una fuente de origen. Por lo tanto, cp falla si lo ejecutas sin argumentos. Sin embargo, tiene una sintaxis flexible y útil que no requiere ninguna opción:

cp SOURCE DEST
cp SOURCE ... DEST-DIR

Puedes hacer mucho simplemente con eso. La mayoría de las implementaciones de cp proporcionan un montón de opciones para modificar exactamente cómo se copian los archivos: se puede preservar el modo y la fecha de modificación, evitar que se sigan enlaces simbólicos, preguntar antes de sobrescribir el contenido de archivos existentes, etc. Pero nada de esto distrae de la misión principal de cp, que consiste en copiar uno o varios archivos en otro directorio.

¿Qué finalidad tienen los argumentos posicionales?

Los argumentos posicionales son adecuados para aquellas piezas de información que tu programa, absolutamente y sin duda alguna, requiere para funcionar.

Una buena interfaz de usuario debería tener la menor cantidad de requisitos absolutos posibles. Si tu programa requiere 17 piezas distintas de información para ejecutarse correctamente, no importa mucho cómo obtengas esa información del usuario; la mayoría de ellos se rendirán y se irán antes de ejecutar con éxito el programa. Esto se aplica tanto si la interfaz de usuario es una línea de comandos, un archivo de configuración o una GUI: si hace demasiadas demandas a sus usuarios, la mayoría simplemente se rendirá.

En resumen, trata de minimizar la cantidad de información que los usuarios están absolutamente obligados a proporcionar, utiliza valores predeterminados sensatos siempre que sea posible. Como es natural, también deseas que tus programas sean razonablemente flexibles, para eso están las opciones. De nuevo, no importa si son entradas en un archivo de configuración, widgets en un cuadro de diálogo de «Preferencias» de una GUI u opciones en la línea de comandos; cuantas más opciones implementes, más flexible será tu programa y más complicada se vuelve su implementación. Una excesiva flexibilidad evidentemente también tiene inconvenientes, demasiadas opciones pueden abrumar a los usuarios y hacer que tu código sea mucho más difícil de mantener.

Tutorial

Si bien optparse es bastante flexible y potente, también es sencillo de usar en la mayoría de los casos. Esta sección cubre los patrones de código comunes a cualquier programa basado en optparse.

En primer lugar, necesitas importar la clase OptionParser y luego, al comienzo del programa principal, crear una instancia de ella:

from optparse import OptionParser
...
parser = OptionParser()

Ahora ya puedes comenzar a definir opciones. La sintaxis básica es:

parser.add_option(opt_str, ...,
                  attr=value, ...)

Cada opción tiene una o más cadenas de caracteres de opción, como -f o --file y varios atributos de opción que le dicen a optparse qué esperar y qué hacer cuando encuentra esa opción en la línea de comandos.

Normalmente, cada opción tendrá una cadena de opción corta y una cadena de opción larga, por ejemplo:

parser.add_option("-f", "--file", ...)

Puedes definir tantas cadenas de opción cortas y tantas largas como desees (incluso ninguna), siempre que haya al menos una cadena de opción en total.

Las cadenas de opción pasadas a OptionParser.add_option() son en definitiva etiquetas para la opción definida por esa llamada. Simplemente por brevedad, con frecuencia nos referiremos a encontrar una opción en la línea de comandos. En realidad, optparse encuentra cadenas de caracteres de opción y busca opciones en ellas.

Una vez que todas tus opciones estén definidas, indica a optparse que analice sintácticamente la línea de comandos de tu programa:

(options, args) = parser.parse_args()

(Si lo deseas, puedes pasar una lista de argumentos personalizada a parse_args(), pero eso rara vez es necesario: por defecto se usa sys.argv [1:].)

parse_args() retorna dos valores:

options, un objeto que contiene valores para todas tus opciones. Por ejemplo, si --file toma un argumento de una sola cadena de caracteres, entonces options.file será el nombre del archivo proporcionado por el usuario o None si el usuario no proporcionó esa opción en la linea de comandos

args, la lista de argumentos posicionales que quedan después de analizar las opciones

Este tutorial solo cubre los cuatro atributos de opción más importantes: action, type, dest (destino) y help. De todos ellos, action es el fundamental.

Comprendiendo las acciones de opción

Las acciones le dicen a optparse qué hacer cuando encuentra una determinada opción en la línea de comandos. Hay un conjunto fijo de acciones codificadas en optparse. Agregar nuevas acciones es un tema avanzado cubierto en la sección Extendiendo el módulo optparse. La mayoría de las acciones indican a optparse que almacene un valor en alguna variable, por ejemplo, tomar una cadena de caracteres de la línea de comandos y almacenarla en un atributo del objeto options.

Si no se especifica una acción para la opción, optparse usa por defecto store.

La acción store

La acción para opciones más común es store, que le dice a optparse que tome el siguiente argumento (o el resto del argumento actual), se asegure de que sea del tipo correcto y lo guarde en el destino elegido.

Por ejemplo:

parser.add_option("-f", "--file",
                  action="store", type="string", dest="filename")

Ahora creamos una línea de comandos simulada y le pedimos a optparse que la analice:

args = ["-f", "foo.txt"]
(options, args) = parser.parse_args(args)

Cuando optparse se encuentra con la cadena de opción -f, consume el siguiente argumento, foo.txt y lo almacena en options.filename. Por lo tanto, después de la llamada a parse_args(), options.filename será "foo.txt".

Algunos de los otros tipos de opción admitidos por optparse son int y float. Aquí hay una opción que espera un argumento entero:

parser.add_option("-n", type="int", dest="num")

Ten en cuenta que esta opción no tiene una cadena de opción larga, lo cual es perfectamente aceptable. Además, no hay ninguna acción explícita, ya que el valor predeterminado es store.

Analicemos otra línea de comandos simulada. En esta ocasión, vamos a proporcionar el argumento de la opción pegado junto a la misma, sin separación entre ambos: dado que -n42 (un argumento) es equivalente a -n 42 (dos argumentos), el código:

(options, args) = parser.parse_args(["-n42"])
print(options.num)

imprimirá 42.

Si no se especifica un tipo, optparse asume string. Esto, combinado con el hecho de que la acción predeterminada es store, implica que nuestro primer ejemplo puede implementarse de forma mucho más concisa:

parser.add_option("-f", "--file", dest="filename")

Si no se proporciona un destino, optparse infiere un destino por defecto adecuado a partir de las cadenas de opción proporcionadas: si la primera cadena de opción larga es --foo-bar, entonces el destino predeterminado es foo_bar. Si no hay cadenas de opción largas, optparse mira la primera cadena de opción corta: por ejemplo, el destino predeterminado para -f es f.

optparse también incluye el tipo incorporado complex. La adición de nuevos tipos se cubre en la sección Extendiendo el módulo optparse.

Manejo de opciones booleanas (flags)

Las opciones flags—establecen una variable en verdadero o falso cuando se encuentra una opción en particular— son bastante comunes. optparse las admite con dos acciones diferenciadas, store_true y store_false. Por ejemplo, puedes tener un flag verbose que se activa con -v y se desactiva con -q:

parser.add_option("-v", action="store_true", dest="verbose")
parser.add_option("-q", action="store_false", dest="verbose")

Aquí tenemos dos opciones diferentes con el mismo destino, lo cual es totalmente correcto. Solo significa que debes tener un poco de cuidado al establecer los valores predeterminados, lo veremos a continuación.

Cuando optparse encuentra -v en la línea de comandos, establece options.verbose en True; cuando encuentra -q, options.verbose se establece en False.

Otras acciones

Algunas de las otras acciones soportadas por optparse son:

"store_const"

almacena un valor constante

"append"

agrega el argumento de esta opción a una lista

"count"

incrementa un contador en uno

"callback"

llama a una función específica

Estas acciones se tratan en la sección Guía de referencia y en la sección Retrollamadas de opción.

Valores por defecto

Todos los ejemplos anteriores implican establecer alguna variable (el «destino») cuando aparecen ciertas opciones en la línea de comandos. ¿Qué pasa si esas opciones nunca se encuentran? Dado que no proporcionamos ningún valor predeterminado, todas las variables están establecidas en None. Por lo general, esto está bien, pero a veces se desea tener más control. optparse permite proporcionar un valor predeterminado para cada destino, que es asignado antes de analizar la línea de comandos.

Primero, considera el ejemplo verbose/quiet anterior. Si queremos que optparse establezca verbose en True a menos que encuentre -q, entonces podemos hacer lo siguiente:

parser.add_option("-v", action="store_true", dest="verbose", default=True)
parser.add_option("-q", action="store_false", dest="verbose")

Dado que los valores predeterminados se aplican a destination en lugar de a cualquier opción en particular y que estas dos opciones tienen el mismo destino, lo anterior es exactamente equivalente a:

parser.add_option("-v", action="store_true", dest="verbose")
parser.add_option("-q", action="store_false", dest="verbose", default=True)

Considera lo siguiente:

parser.add_option("-v", action="store_true", dest="verbose", default=False)
parser.add_option("-q", action="store_false", dest="verbose", default=True)

Nuevamente, el valor predeterminado para verbose será True: el último valor predeterminado proporcionado para cualquier destino en particular es el único que se tendrá en cuenta.

Una forma más clara de especificar valores predeterminados es el método set_defaults() de OptionParser, al que puedes llamar en cualquier momento antes de llamar a parse_args():

parser.set_defaults(verbose=True)
parser.add_option(...)
(options, args) = parser.parse_args()

Como vimos antes, el último valor especificado para un destino de opción dado es el que cuenta. Para mayor claridad, intenta utilizar un método u otro para establecer valores predeterminados, no ambos.

Generando ayuda

La capacidad de optparse para generar ayuda y texto de uso automáticamente es útil para crear interfaces de línea de comandos fáciles de usar. Todo lo que tienes que hacer es proporcionar un valor help para cada opción y, opcionalmente, un breve mensaje de uso para el programa en general. A continuación hay un OptionParser al que se le han añadido múltiples opciones fáciles de usar (documentadas):

usage = "usage: %prog [options] arg1 arg2"
parser = OptionParser(usage=usage)
parser.add_option("-v", "--verbose",
                  action="store_true", dest="verbose", default=True,
                  help="make lots of noise [default]")
parser.add_option("-q", "--quiet",
                  action="store_false", dest="verbose",
                  help="be vewwy quiet (I'm hunting wabbits)")
parser.add_option("-f", "--filename",
                  metavar="FILE", help="write output to FILE")
parser.add_option("-m", "--mode",
                  default="intermediate",
                  help="interaction mode: novice, intermediate, "
                       "or expert [default: %default]")

Si optparse encuentra -h o --help en la línea de comandos, o si simplemente se llama al método parser.print_help(), se imprime lo siguiente en la salida estándar:

Usage: <yourscript> [options] arg1 arg2

Options:
  -h, --help            show this help message and exit
  -v, --verbose         make lots of noise [default]
  -q, --quiet           be vewwy quiet (I'm hunting wabbits)
  -f FILE, --filename=FILE
                        write output to FILE
  -m MODE, --mode=MODE  interaction mode: novice, intermediate, or
                        expert [default: intermediate]

(Si la salida de ayuda se activa mediante una opción de ayuda, optparse termina la ejecución después de imprimir el texto de ayuda.)

Estamos haciendo muchas cosas aquí con el fin de ayudar a que optparse genere el mejor mensaje de ayuda posible:

el script define su propio mensaje de uso:

usage = "usage: %prog [options] arg1 arg2"

optparse expande % prog en la cadena de uso reemplazándolo por el nombre del programa actual, es decir, os.path.basename (sys.argv [0]). A continuación, la cadena expandida se imprime antes de la ayuda detallada de la opción.

Si no proporcionas una cadena de uso, optparse usa un valor predeterminado anodino pero apropiado: "Usage: %prog [options]", lo cual está bien si tu script no toma ningún argumento posicional.

cada opción simplemente define una cadena de ayuda y no se preocupa por el ajuste de línea. optparse se encarga de ajustar las líneas y hacer que la salida de ayuda se vea bien.

las opciones que toman un valor indican este hecho en su mensaje de ayuda generado automáticamente, por ejemplo, para la opción «mode»:

-m MODE, --mode=MODE

Aquí, a «MODE» se le denomina una metavariable: representa el argumento que se espera que el usuario proporcione a -m/--mode. De forma predeterminada, optparse convierte el nombre de la variable de destino a mayúsculas y lo usa para la metavariable. En ocasiones, eso no es lo que se desea, por ejemplo, la opción --filename establece explícitamente metavar="FILE", lo que da como resultado la siguiente descripción de opción generada automáticamente:

-f FILE, --filename=FILE

Sin embargo, esto es importante para algo más que para ahorrar espacio: el texto de ayuda escrito manualmente utiliza la metavariable FILE para indicarle al usuario que hay una conexión entre la sintaxis semiformal -f FILE y la descripción semántica informal «escribir la salida en FILE». Esta es una manera simple pero efectiva de hacer que tu texto de ayuda sea mucho más claro y útil para los usuarios finales.

las opciones que tienen un valor predeterminado pueden incluir %default en la cadena de ayuda, en cuyo caso, optparse lo reemplazará por el resultado de aplicar str() al valor por defecto de esa opción. Si una opción no tiene un valor por defecto (o el valor por defecto es None), %default se reemplazará por none.

Agrupando opciones

Cuando se trabaja con muchas opciones, suele ser conveniente agruparlas para obtener una mejor salida de ayuda. La clase OptionParser puede contener varios grupos de opciones, cada uno de los cuales puede contener múltiples opciones.

Podemos obtener un grupo de opciones usando la clase OptionGroup:

class optparse.OptionGroup(parser, title, description=None)

donde

parser es la instancia de OptionParser en la que se insertará el grupo

title es el título dado al grupo

description, opcional, es la descripción larga del grupo

la clase OptionGroup hereda de OptionContainer (al igual que OptionParser), por lo que el método add_option() se puede usar para agregar una opción al grupo.

Una vez que se han declarado todas las opciones, usando el método add_option_group() de la clase OptionParser el grupo se agrega al analizador sintáctico previamente definido.

Agregar un OptionGroup a un analizador es fácil, continuando con el analizador definido en la sección anterior:

group = OptionGroup(parser, "Dangerous Options",
                    "Caution: use these options at your own risk.  "
                    "It is believed that some of them bite.")
group.add_option("-g", action="store_true", help="Group option.")
parser.add_option_group(group)

Esto daría como resultado la siguiente salida de ayuda:

Usage: <yourscript> [options] arg1 arg2

Options:
  -h, --help            show this help message and exit
  -v, --verbose         make lots of noise [default]
  -q, --quiet           be vewwy quiet (I'm hunting wabbits)
  -f FILE, --filename=FILE
                        write output to FILE
  -m MODE, --mode=MODE  interaction mode: novice, intermediate, or
                        expert [default: intermediate]

  Dangerous Options:
    Caution: use these options at your own risk.  It is believed that some
    of them bite.

    -g                  Group option.

Un ejemplo un poco más completo podría implicar el uso de más de un grupo, ampliando el ejemplo anterior:

group = OptionGroup(parser, "Dangerous Options",
                    "Caution: use these options at your own risk.  "
                    "It is believed that some of them bite.")
group.add_option("-g", action="store_true", help="Group option.")
parser.add_option_group(group)

group = OptionGroup(parser, "Debug Options")
group.add_option("-d", "--debug", action="store_true",
                 help="Print debug information")
group.add_option("-s", "--sql", action="store_true",
                 help="Print all SQL statements executed")
group.add_option("-e", action="store_true", help="Print every action done")
parser.add_option_group(group)

lo que da como resultado la siguiente salida:

Usage: <yourscript> [options] arg1 arg2

Options:
  -h, --help            show this help message and exit
  -v, --verbose         make lots of noise [default]
  -q, --quiet           be vewwy quiet (I'm hunting wabbits)
  -f FILE, --filename=FILE
                        write output to FILE
  -m MODE, --mode=MODE  interaction mode: novice, intermediate, or expert
                        [default: intermediate]

  Dangerous Options:
    Caution: use these options at your own risk.  It is believed that some
    of them bite.

    -g                  Group option.

  Debug Options:
    -d, --debug         Print debug information
    -s, --sql           Print all SQL statements executed
    -e                  Print every action done

Otro método interesante, particularmente cuando se trabaja programáticamente con grupos de opciones, es:

OptionParser.get_option_group(opt_str)

Retorna el OptionGroup al que pertenece la cadena de opción corta o larga opt_str (por ejemplo, '-o' o ' --option'). Si no existe dicho OptionGroup, el método retorna None.

Imprimir una cadena de caracteres con la versión del programa

De forma similar a lo que ocurre con la cadena de uso abreviada, optparse también puede imprimir una cadena de versión para tu programa. Debes proporcionar la cadena mediante el argumento version de OptionParser:

parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")

%prog se expande al igual que en usage. Aparte de eso, version puede contener cualquier cosa que desees. Cuando se proporciona, optparse agrega automáticamente una opción --version al analizador. Si encuentra esta opción en la línea de comandos, expande la cadena version (reemplazando %prog), la imprime en la salida estándar y termina la ejecución.

Por ejemplo, si tu script se llama /usr/bin/foo:

$ /usr/bin/foo --version
foo 1.0

Para imprimir y obtener la cadena de caracteres version, se pueden utilizar cualquiera de los siguientes métodos:

OptionParser.print_version(file=None)

Imprime el mensaje con la versión del programa actual (self.version) en file (por defecto, la salida estándar). Al igual que con print_usage(), cualquier aparición de %prog en self.version se reemplaza con el nombre del programa actual. El método no hace nada si self.version está vacío o no está definido.

OptionParser.get_version()

Igual que print_version(), pero retorna la cadena de versión en lugar de imprimirla.

Cómo maneja los errores el módulo optparse

A grandes rasgos, hay dos clases de errores de los que optparse tiene que preocuparse: errores del programador y errores del usuario. Los errores del programador suelen ser el resultado de llamadas erróneas a OptionParser.add_option(), como cadenas de opción no válidas, atributos de opción desconocidos, atributos de opción que faltan, etc. Se tratan de la forma habitual: generan una excepción (ya sea optparse.OptionError o TypeError) y hacen que el programa se bloquee.

Manejar los errores del usuario es mucho más importante, ya que está garantizado que sucederán sin importar cuán estable sea el código. optparse puede detectar automáticamente algunos errores del usuario, como argumentos de opción incorrectos (pasar -n 4x donde -n toma un argumento entero) o la falta de argumentos (-n al final de la línea de comandos, donde -n toma un argumento de cualquier tipo). Además de esto, puedes llamar a OptionParser.error() para establecer una condición de error definida por la propia aplicación:

(options, args) = parser.parse_args()
...
if options.a and options.b:
    parser.error("options -a and -b are mutually exclusive")

En cualquier caso, optparse maneja el error de la misma manera: imprime el mensaje de uso del programa junto a un mensaje de error en la salida de errores estándar y termina la ejecución con el estado de error 2.

Considera el primero de los dos ejemplos anteriores, donde el usuario pasa 4x a una opción que toma un número entero:

$ /usr/bin/foo -n 4x
Usage: foo [options]

foo: error: option -n: invalid integer value: '4x'

O, en el caso en el que el usuario definitivamente no pase ningún valor:

$ /usr/bin/foo -n
Usage: foo [options]

foo: error: -n option requires an argument

Los mensajes de error generados por optparse tienen siempre cuidado de mencionar la opción involucrada en el error. Asegúrate de hacer lo mismo cuando llames a OptionParser.error() desde el código de tu aplicación.

Si el comportamiento del manejo de errores predeterminado de optparse no se adapta a tus necesidades, deberás subclasificar OptionParser y redefinir su método exit() y/o error().

Reuniendo todas las piezas

Así es como los scripts basados en optparse usualmente se ven:

from optparse import OptionParser
...
def main():
    usage = "usage: %prog [options] arg"
    parser = OptionParser(usage)
    parser.add_option("-f", "--file", dest="filename",
                      help="read data from FILENAME")
    parser.add_option("-v", "--verbose",
                      action="store_true", dest="verbose")
    parser.add_option("-q", "--quiet",
                      action="store_false", dest="verbose")
    ...
    (options, args) = parser.parse_args()
    if len(args) != 1:
        parser.error("incorrect number of arguments")
    if options.verbose:
        print("reading %s..." % options.filename)
    ...

if __name__ == "__main__":
    main()

Guía de referencia

Creando el analizador sintáctico (parser)

El primer paso para poder usar optparse es crear una instancia de OptionParser.

class optparse.OptionParser(...)

El constructor de la clase OptionParser no tiene argumentos obligatorios, pero sí varios argumentos opcionales por palabra clave. Siempre deben pasarse como argumentos por palabras clave, es decir, no se debe confiar nunca en el orden en que se declaran los argumentos.

usage (por defecto: "%prog [options]")

El resumen de uso a imprimir cuando el programa se ejecuta incorrectamente o con una opción de ayuda. Cuando optparse imprime la cadena de uso, reemplaza %prog con os.path.basename(sys.argv[0]) (o con prog si se proporcionó eso argumento por palabra clave). Para suprimir un mensaje de uso, se debe pasar el valor especial optparse.SUPPRESS_USAGE.

option_list (por defecto: [])

Una lista de objetos Option con los que poblar el analizador. Las opciones en option_list se agregan después de cualquier opción en standard_option_list (un atributo de clase que puede ser establecido por las subclases de OptionParser), pero antes de cualquier versión u opción de ayuda. Obsoleto: usar en su lugar el método add_option(), una vez creado el analizador.

option_class (por defecto: optparse.Option)

Clase usada por el método add_option() para añadir opciones al analizador.

version (por defecto: None)

Una cadena de caracteres con la versión del programa a imprimir cuando el usuario proporciona una opción de versión. Si se proporciona un valor verdadero para version, optparse agrega automáticamente una opción de versión con --version como única cadena de opción. La subcadena %prog se expande de la misma manera que en usage.

conflict_handler (por defecto: "error")

Especifica qué hacer cuando se agregan al analizador opciones con cadenas de opción en conflicto entre si. Ver sección Conflictos entre opciones.

description (por defecto: None)

Un párrafo de texto que ofrece una breve descripción del programa. optparse reformatea este párrafo para que se ajuste al ancho actual de la terminal y lo imprime cuando el usuario solicita ayuda (después de usage, pero antes de la lista de opciones).

formatter (por defecto: una nueva instancia de la clase IndentedHelpFormatter)

Una instancia de la clase optparse.HelpFormatter que será usada para imprimir el texto de ayuda. El módulo optparse proporciona dos clases concretas para este propósito: IndentedHelpFormatter y TitledHelpFormatter.

add_help_option (por defecto: True)

Si es verdadero, optparse agregará al analizador una opción de ayuda (con las cadenas de opción -h y --help).

prog

La cadena de caracteres a usar como substituta de os.path.basename(sys.argv[0]) cuando se expanda %prog en usage y en version.

epilog (por defecto: None)

Un párrafo con texto de ayuda que se imprimirá después de la opción de ayuda.

Completando el analizador con opciones

Hay varias formas de agregar las opciones al analizador. La forma preferida es mediante el método OptionParser.add_option(), tal como se muestra en la sección del Tutorial. El método add_option() se puede llamar de dos formas diferentes:

pasándole una instancia de Option (como la que retorna make_option())

pasándole cualquier combinación de argumentos posicionales y por palabra clave que sean aceptables para make_option() (es decir, para el constructor de la clase Option), lo que creará la instancia Option automáticamente

La otra alternativa es pasar una lista de instancias de Option previamente construidas al constructor OptionParser, como en el siguiente ejemplo:

option_list = [
    make_option("-f", "--filename",
                action="store", type="string", dest="filename"),
    make_option("-q", "--quiet",
                action="store_false", dest="verbose"),
    ]
parser = OptionParser(option_list=option_list)

(make_option() es una función fábrica para crear instancias Option. Actualmente es simplemente un alias para el constructor Option, pero es posible que una futura versión de optparse pueda dividir Option en varias clases, en cuyo caso, make_option() elegirá la clase correcta a instanciar. Esta es la razón por la que no se debe instanciar Option directamente.)

Definiendo las opciones

Cada instancia de Option representa un conjunto de cadenas de opción sinónimas para la línea de comandos, por ejemplo -f y --file. Se puede especificar cualquier número de cadenas de opción cortas o largas, pero se debe proporcionar al menos una cadena de opción en total.

La forma canónica de crear una instancia de Option es mediante el método add_option() de la clase OptionParser.

OptionParser.add_option(option)

OptionParser.add_option(*opt_str, attr=value, ...)

Para definir una opción con solo una cadena de opción corta:

parser.add_option("-f", attr=value, ...)

Y para definir una opción con solo una cadena de opción larga:

parser.add_option("--foo", attr=value, ...)

Los argumentos por palabra clave definen atributos para el nuevo objeto Option. El atributo de opción más importante es action, que determina en gran medida qué otros atributos son apropiados u obligatorios. Si se pasan atributos de opción no apropiados, o no se pasan los requeridos, optparse lanza una excepción OptionError explicando el error.

La acción (action) de una opción determina que hace el módulo optparse cuando encuentra dicha opción en la línea de comandos. Las acciones de opción estándares codificadas en optparse son:

"store"

almacena el argumento de esta opción (por defecto)

"store_const"

almacena un valor constante

"store_true"

almacena True

"store_false"

almacena False

"append"

agrega el argumento de esta opción a una lista

"append_const"

agrega un valor constante a una lista

"count"

incrementa un contador en uno

"callback"

llama a una función específica

"help"

imprime un mensaje de uso que incluye todas las opciones y la documentación correspondiente

(Si no se proporciona una acción, el valor predeterminado es "store". Para esta acción en concreto, también se pueden proporcionar los atributos de opción type y dest. Consultar Acciones de opción estándares para más información.)

Como se puede observar, la mayoría de las acciones implican almacenar o actualizar un valor en algún lugar. optparse siempre crea un objeto especial para esto, convencionalmente llamado options (que resulta ser una instancia de optparse.Values). Los argumentos de opción (y algunos otros valores) se almacenan como atributos de este objeto, de acuerdo con el atributo de opción dest (destino) establecido.

Por ejemplo, cuando se llama a:

parser.parse_args()

una de las primeras cosas que hace el módulo optparse es crear el objeto options:

options = Values()

Si una de las opciones de este analizador es definida con:

parser.add_option("-f", "--file", action="store", type="string", dest="filename")

y la línea de comandos que se analiza incluye cualquiera de las siguientes variantes:

-ffoo
-f foo
--file=foo
--file foo

entonces el módulo optparse, al encontrar esta opción, hará algo equivalente a:

options.filename = "foo"

Los atributos de opción type y dest son casi tan importantes como action, pero action es el único de ellos que es apropiado para todas las opciones.

Atributos de opción

Los siguientes atributos de opción pueden pasarse como argumentos por palabra clave al método OptionParser.add_option(). Si se pasa un atributo de opción que no es apropiado para una opción en particular, o no se pasa un atributo de opción obligatorio, optparse lanza una excepción OptionError.

Option.action

(por defecto: "store")

Determina el comportamiento del módulo optparse cuando esta opción se encuentra en la línea de comandos. Las opciones disponibles están documentadas aquí.

Option.type

(por defecto: "string")

El tipo de argumento esperado para esta opción (por ejemplo, "string" o "int"). Los tipos de opción disponibles están documentados aquí.

Option.dest

(por defecto: derivado de las cadenas de opción)

Si la acción asociada a la opción implica escribir o modificar un valor en algún lugar, este atributo le dice a optparse dónde escribirlo: dest es el nombre de un atributo del objeto options que optparse construye a medida que analiza la línea de comandos.

Option.default

El valor que se utilizará como destino de esta opción si la opción no aparece en la línea de comandos. Ver también OptionParser.set_defaults().

Option.nargs

(por defecto: 1)

Cuántos argumentos de tipo type deben consumirse cuando se encuentre esta opción. Si es mayor a 1, optparse almacenará una tupla con los valores de los argumentos en dest.

Option.const

Para acciones que almacenan un valor constante, el valor constante a almacenar.

Option.choices

Para opciones de tipo "choice", la lista con las cadenas que el usuario puede elegir.

Option.callback

Para las opciones con la acción "callback" asignada, el objeto invocable a llamar cuando se encuentra esta opción. Consultar la sección Retrollamadas de opción para obtener más detalles sobre los argumentos que son pasados al objeto invocable.

Option.callback_args

Option.callback_kwargs

Argumentos posicionales y por palabra clave adicionales para ser pasados a callback después de los cuatro argumentos pasados a la retrollamada estándar.

Option.help

Texto de ayuda a imprimir para esta opción cuando se enumeran todas las opciones disponibles, después de que el usuario proporcione una opción help (como --help). Si no se proporciona ningún texto de ayuda, la opción seguirá apareciendo, solo que sin texto de ayuda. Para ocultar esta opción completamente, se debe asignar al atributo el valor especial optparse.SUPPRESS_HELP.

Option.metavar

(por defecto: derivado de las cadenas de opción)

Reemplazo para los argumentos de opción que se utilizará al imprimir el texto de ayuda. Consultar la sección Tutorial para ver un ejemplo.

Acciones de opción estándares

Las diversas acciones de opción tienen requisitos y efectos ligeramente diferentes. La mayoría de las acciones tienen varios atributos de opción relacionados que puedes especificar para dirigir el comportamiento del módulo optparse. Además, algunas de ellas tienen atributos requeridos, que se deben especificar para cualquier opción que utilice esa acción.

"store" [atributos relacionados: type, dest, nargs, choices]

La opción debe ir seguida de un argumento, que se convierte en un valor de acuerdo a type y se almacena en dest. Si nargs es mayor que 1, se consumirán varios argumentos de la línea de comandos. Todos ellos se convertirán de acuerdo a type y se almacenarán en dest como una tupla. Consultar la sección Tipos de opción estándares para más información.

Si se proporciona choices (una lista o tupla de cadenas de caracteres), el tipo por defecto es "choice".

Si no se proporciona type, el tipo por defecto es "string".

Si dest no se proporciona, optparse infiere un destino de la primera cadena de opción larga (por ejemplo, --foo-bar implica que se usará foo_bar como destino). Si no hay cadenas de opción largas, optparse obtiene el destino a partir de la primera cadena de opción corta (por ejemplo, -f conlleva que se usará f).

Ejemplo:

parser.add_option("-f")
parser.add_option("-p", type="float", nargs=3, dest="point")

Mientras analiza la línea de comandos:

-f foo.txt -p 1 -3.5 4 -fbar.txt

optparse establecerá:

options.f = "foo.txt"
options.point = (1.0, -3.5, 4.0)
options.f = "bar.txt"

"store_const" [atributo requerido: const; atributo relacionado: dest]

El valor const es almacenado en dest.

Ejemplo:

parser.add_option("-q", "--quiet",
                  action="store_const", const=0, dest="verbose")
parser.add_option("-v", "--verbose",
                  action="store_const", const=1, dest="verbose")
parser.add_option("--noisy",
                  action="store_const", const=2, dest="verbose")

Si se encuentra --noisy, optparse establecerá:

options.verbose = 2

"store_true" [atributo relacionado: dest]

Un caso especial de "store_const" que almacena True en dest.

"store_false" [atributo relacionado: dest]

Como "store_true", pero almacena False.

Ejemplo:

parser.add_option("--clobber", action="store_true", dest="clobber")
parser.add_option("--no-clobber", action="store_false", dest="clobber")

"append" [atributos relacionados: type, dest, nargs, choices]

La opción debe ir seguida de un argumento, que se añade a la lista de dest. Si no se proporciona un valor predeterminado para dest, se crea automáticamente una lista vacía cuando optparse encuentra por primera vez esta opción en la línea de comandos. Si nargs es mayor que 1, se consumen varios argumentos y se agrega una tupla de longitud nargs a dest.

Los valores por defecto para los atributos type y dest son los mismos que para la acción "store".

Ejemplo:

parser.add_option("-t", "--tracks", action="append", type="int")

Si se encuentra -t3 en la línea de comandos, optparse procede de forma equivalente a:

options.tracks = []
options.tracks.append(int("3"))

Si, un poco más adelante, se encuentra --tracks=4, procede así:

options.tracks.append(int("4"))

La acción append llama al método append con el valor actual de la opción. Esto significa que cualquier valor por defecto especificado debe tener un método append. También significa que si existe un valor por defecto, los elementos por defecto estarán presentes en el valor analizado para la opción, con todos los valores de la línea de comandos agregados a la lista a continuación de ellos:

>>> parser.add_option("--files", action="append", default=['~/.mypkg/defaults'])
>>> opts, args = parser.parse_args(['--files', 'overrides.mypkg'])
>>> opts.files
['~/.mypkg/defaults', 'overrides.mypkg']

"append_const" [atributo requerido: const; atributo relacionado: dest]

Igual que "store_const", pero el valor const se agrega a dest. Como ocurre con "append", dest por defecto es None y se crea automáticamente una lista vacía la primera vez que se encuentra la opción en la linea de comandos.

"count" [atributo relacionado: dest]

Incrementa el entero almacenado en dest. Si no se proporciona un valor por defecto, dest se establece en cero antes de incrementarse por primera vez.

Ejemplo:

parser.add_option("-v", action="count", dest="verbosity")

La primera vez que se encuentra -v en la línea de comandos, optparse procede de forma equivalente a:

options.verbosity = 0
options.verbosity += 1

Cada aparición posterior de -v da como resultado:

options.verbosity += 1

"callback" [atributo requerido: callback; atributos relacionados: type, nargs, callback_args, callback_kwargs]

Llama a la función especificada por callback, que es llamada como:

func(option, opt_str, value, parser, *args, **kwargs)

Ver sección Retrollamadas de opción para más detalles.

"help"

Imprime un mensaje de ayuda completo para todas las opciones presentes en el analizador de opciones actual. El mensaje de ayuda se construye a partir de la cadena usage, pasada al constructor de OptionParser, y la cadena help, pasada a cada opción.

Si no se proporciona una cadena help para una opción, dicha opción seguirá apareciendo en el mensaje de ayuda. Para omitir una opción por completo, debe usarse el valor especial optparse.SUPPRESS_HELP.

El módulo optparse agrega automáticamente una opción help a todos los OptionParsers, por lo que normalmente no es necesario crear una.

Ejemplo:

from optparse import OptionParser, SUPPRESS_HELP

# usually, a help option is added automatically, but that can
# be suppressed using the add_help_option argument
parser = OptionParser(add_help_option=False)

parser.add_option("-h", "--help", action="help")
parser.add_option("-v", action="store_true", dest="verbose",
                  help="Be moderately verbose")
parser.add_option("--file", dest="filename",
                  help="Input file to read data from")
parser.add_option("--secret", help=SUPPRESS_HELP)

Si optparse encuentra -h o --help en la línea de comandos, imprimirá un mensaje de ayuda en la salida estándar como el siguiente (asumiendo que sys.argv [0] es "foo.py"):

Usage: foo.py [options]

Options:
  -h, --help        Show this help message and exit
  -v                Be moderately verbose
  --file=FILENAME   Input file to read data from

Después de imprimir el mensaje de ayuda, optparse termina su proceso con sys.exit(0).

"version"

Imprime el número de versión proporcionado a OptionParser en la salida estándar y termina la ejecución. El número de versión en realidad es formateado e impreso por el método print_version() de OptionParser. Generalmente solo es relevante si el argumento version se proporciona al constructor de OptionParser. Al igual que en el caso de las opciones help, rara vez será necesario crear opciones de version, ya que optparse las agrega automáticamente cuando es necesario.

Tipos de opción estándares

El módulo optparse proporciona cinco tipos de opción incorporados: "string", "int", "choice", "float" y "complex". Consultar la sección Extendiendo el módulo optparse si se necesitan agregar nuevos tipos de opción.

Los argumentos de las opciones en la cadena ingresada no se verifican ni se convierten de ninguna manera: el texto de la línea de comandos se almacena en el destino (o se pasa a la retrollamada) tal cual.

Los argumentos enteros (tipo "int") se analizan de la siguiente manera:

si el número comienza con 0x, se analiza como un número hexadecimal

si el número comienza con 0, se analiza como un número octal

si el número comienza con 0b, se analiza como un número binario

en cualquier otro caso, el número se analiza como un número decimal

La conversión se realiza llamando a int() con la base apropiada (2, 8, 10 o 16). Si esto falla, también lo hará optparse, aunque mostrando un mensaje de error más útil para el usuario.

Los argumentos de las opciones de tipo "float" y "complex" se convierten directamente usando float() y complex() respectivamente, con un manejo de errores similar.

Las opciones de tipo "choice" son un subtipo de las opciones "string". El atributo de opción choices (que es una secuencia de cadenas) define el conjunto de argumentos de opción permitidos. Posteriormente, optparse.check_choice() comparará los argumentos de las opciones proporcionadas por el usuario con esta lista maestra y generará una excepción OptionValueError si se proporciona una cadena no válida.

Analizando los argumentos

El objetivo primario de crear y agregar opciones a un OptionParser es llamar a su método parse_args():

(options, args) = parser.parse_args(args=None, values=None)

donde los parámetros de entrada son

args

la lista de argumentos a procesar (por defecto: sys.argv [1:])

values

un objeto de la clase optparse.Values para almacenar en él los argumentos de las opciones. Por defecto es una nueva instancia de la clase Values. Si se proporciona un objeto previamente creado, los valores predeterminados de la opción no se inicializarán en el mismo

y los valores de retorno son

options

el mismo objeto que se pasó como values, o la instancia optparse.Values ​​creada por optparse

args

los argumentos posicionales que quedan en la linea de comandos después de que se hayan procesado todas las opciones

El uso más habitual es no proporcionar ningún argumento por palabra clave. Si se proporciona values, dicho argumento será modificado mediante llamadas repetidas a setattr() (aproximadamente una por cada argumento de opción a almacenar en un destino de opción) y finalmente será retornado por el método parse_args().

Si el método parse_args() encuentra algún error en la lista de argumentos, llama al método error() de OptionParser con un mensaje de error apropiado para el usuario final. Esto causa que el proceso termine con un estado de salida de 2 (el estado de salida tradicional en Unix para errores en la línea de comandos).

Consultar y manipular el analizador de opciones

El comportamiento predeterminado del analizador de opciones se puede personalizar ligeramente. También se puede indagar en el analizador de opciones y ver qué hay en él. OptionParser proporciona varios métodos para ayudar con éstos propósitos:

OptionParser.disable_interspersed_args()

Configura el análisis para que se detenga en lo primero que encuentre que no sea una opción. Por ejemplo, si -a y -b son opciones simples que no toman argumentos, optparse normalmente acepta esta sintaxis:

prog -a arg1 -b arg2

y la trata de forma equivalente a:

prog -a -b arg1 arg2

Para deshabilitar esta funcionalidad, se debe llamar al método disable_interspersed_args(). Esto restaura la sintaxis tradicional usada en Unix, donde el análisis de opción se detiene con el primer argumento que no es una opción.

Se debe usar este método si se dispone de un procesador de comandos que ejecuta otro comando con sus propias opciones y se desea asegurarse de que estas opciones no se confunden entre si. Lo que puede ocurrir si, por ejemplo, cada comando tiene un conjunto diferente de opciones.

OptionParser.enable_interspersed_args()

Configura el análisis para que no se detenga si encuentra un argumento que no sea una opción, lo que permite intercalar modificadores con argumentos de linea de comandos. Este es el comportamiento por defecto.

OptionParser.get_option(opt_str)

Retorna la instancia de Option con la cadena de opción opt_str, o None si ninguna opción tiene esa cadena de opción.

OptionParser.has_option(opt_str)

Retorna True si OptionParser tiene una opción con la cadena de opción opt_str (por ejemplo, -q o --verbose).

OptionParser.remove_option(opt_str)

Si OptionParser tiene una opción correspondiente a opt_str, esa opción es eliminada. Si esa opción proporcionó cualquier otra cadena de opción, todas esas cadenas de opción quedan invalidadas. Si opt_str no aparece en ninguna opción que pertenezca a este OptionParser, se lanza una excepción ValueError.

Conflictos entre opciones

Si no se tiene cuidado, es fácil definir opciones con cadenas de opción en conflicto entre si:

parser.add_option("-n", "--dry-run", ...)
...
parser.add_option("-n", "--noisy", ...)

(Esto es particularmente cierto si se ha definido una subclase propia de OptionParser con algunas opciones estándar.)

Cada vez que se agrega una opción, optparse comprueba si existen conflictos con las opciones ya existentes. Si encuentra alguno, invoca el mecanismo de manejo de conflictos actualmente establecido. Se puede establecer el mecanismo de manejo de conflictos desde el propio constructor:

parser = OptionParser(..., conflict_handler=handler)

o mediante una llamada separada:

parser.set_conflict_handler(handler)

Los administradores de conflictos disponibles son:

"error" (por defecto)

se asume que los conflictos entre opciones son un error de programación y, por tanto, generarán una excepción OptionConflictError

"resolve"

resuelve conflictos de opciones de forma inteligente (ver más abajo)

Como ejemplo, vamos a definir un OptionParser que resuelva conflictos de manera inteligente y agregaremos algunas opciones conflictivas:

parser = OptionParser(conflict_handler="resolve")
parser.add_option("-n", "--dry-run", ..., help="do no harm")
parser.add_option("-n", "--noisy", ..., help="be noisy")

En este punto, optparse detecta que una opción agregada anteriormente ya está usando la cadena de opción -n. Dado que conflict_handler es "resolve", resuelve la situación eliminando -n de la lista de cadenas de opción de la opción previa. Ahora --dry-run es la única forma que el usuario tiene para poder activar esa opción. Si el usuario solicita ayuda, el mensaje de ayuda reflejará la nueva situación:

Options:
  --dry-run     do no harm
  ...
  -n, --noisy   be noisy

Es posible reducir las cadenas de opción para una opción agregada previamente hasta que no quede ninguna, de forma que el usuario no tenga forma de invocar esa opción desde la línea de comandos. En ese caso, optparse eliminará esa opción por completo, por lo que no aparecerá en el texto de ayuda ni en ningún otro lugar. Continuando con nuestro analizador de opciones previo:

parser.add_option("--dry-run", ..., help="new dry-run option")

En este punto, la opción original -n/--dry-run ya no es accesible, por lo que optparse la elimina, dejando el siguiente texto de ayuda:

Options:
  ...
  -n, --noisy   be noisy
  --dry-run     new dry-run option

Limpieza

Las instancias de OptionParser tienen varias referencias cíclicas. Esto no debería ser un problema para el recolector de basura de Python, pero es posible que se desee romper las referencias cíclicas explícitamente llamando al método destroy() de la instancia OptionParser una vez que se haya terminado. Esto es particularmente útil en aplicaciones de larga ejecución en las que OptionParser puede terminar accediendo a grafos de objetos considerablemente grandes.

Otros métodos

OptionParser admite varios métodos públicos más:

OptionParser.set_usage(usage)

Establece la cadena de caracteres de uso de acuerdo a las reglas descritas anteriormente para el argumento por palabra clave usage del constructor. Si se pasa None se establece la cadena de uso por defecto. Para suprimir el mensaje de uso totalmente, se debe pasar el valor especial optparse.SUPPRESS_USAGE.

OptionParser.print_usage(file=None)

Imprime el mensaje de uso del programa actual (self.usage) en file (que por defecto es la salida estándar). Cualquier aparición de la cadena de caracteres %prog en self.usage es reemplazada con el nombre del programa actual. No hace nada si self.usage está vacío o no ha sido definido.

OptionParser.get_usage()

Igual que print_usage() pero retorna la cadena de uso en vez de imprimirla.

OptionParser.set_defaults(dest=value, ...)

Establece valores por defecto para varios destinos de opción a la vez. Usar el método set_defaults() es la forma preferida de establecer valores por defecto para las opciones, ya que varias opciones pueden compartir el mismo destino. Por ejemplo, si varias opciones de mode tienen el mismo destino, cualquiera de ellas puede establecer el valor por defecto, pero el último establecido es el que finalmente queda establecido:

parser.add_option("--advanced", action="store_const",
                  dest="mode", const="advanced",
                  default="novice")    # overridden below
parser.add_option("--novice", action="store_const",
                  dest="mode", const="novice",
                  default="advanced")  # overrides above setting

Para evitar esta confusión, usa el método set_defaults():

parser.set_defaults(mode="advanced")
parser.add_option("--advanced", action="store_const",
                  dest="mode", const="advanced")
parser.add_option("--novice", action="store_const",
                  dest="mode", const="novice")

Retrollamadas de opción

Cuando las acciones y tipos incorporados de optparse no son suficientes para tus necesidades, tienes dos opciones: extender optparse o definir una opción con una retrollamada asociada. Extender optparse es más general, pero algo exagerado para muchos casos simples. Es frecuente que una simple retrollamada sea todo lo que necesitas.

Hay dos pasos a seguir para definir una opción con retrollamada:

definir la opción en sí usando la acción "callback"

escribir la retrollamada. Esta es una función (o método) que toma al menos cuatro argumentos, los cuales son descritos a continuación

Definición de una opción con retrollamada

Generalmente, la forma más sencilla de definir una opción con retrollamada es mediante el método OptionParser.add_option(). Aparte de action, el único atributo de opción que debes especificar es callback, que es la función a llamar:

parser.add_option("-c", action="callback", callback=my_callback)

callback es una función (u otro objeto invocable), lo que implica que my_callback() debe haber sido definida antes de la la creación de esta opción con retrollamada. En este caso simple, optparse ni siquiera sabe si -c toma algún argumento, lo que generalmente significa que la opción no toma argumentos—la mera presencia de -c en la línea de comandos es todo lo que necesita saber. Sin embargo, en algunas circunstancias, es posible que se desee que la retrollamada consuma una cantidad arbitraria de argumentos de la propia línea de comandos. Es aquí donde escribir retrollamadas se vuelve complicado; se tratará más adelante en esta sección.

optparse siempre pasa cuatro argumentos concretos a la retrollamada. El método solo pasará argumentos adicionales si se especifica explícitamente a través de callback_args y callback_kwargs. Por lo tanto, la firma mínima de la retrollamada es:

def my_callback(option, opt, value, parser):

Los cuatro argumentos para la retrollamada se describen a continuación.

Hay varios atributos de opción adicionales que se pueden proporcionar cuando se define una opción con retrollamada:

type

tiene su significado habitual: al igual que en las acciones "store" o "append", indica a optparse que debe consumir un argumento y convertirlo a type . Sin embargo, en lugar de almacenar el valor (o valores) convertido en algún lugar, optparse lo pasa a la retrollamada.

nargs

también tiene su significado habitual: si se proporciona y es mayor que 1, optparse consumirá nargs argumentos de la línea de comandos, cada uno de los cuales debe ser convertible a type. Hecho esto, se pasa una tupla con los valores convertidos a la retrollamada.

callback_args

una tupla con los argumentos posicionales adicionales para pasar a la retrollamada

callback_kwargs

un diccionario con los argumentos por palabra clave para pasar a la retrollamada

Cómo son invocadas las retrollamadas

Todas las retrollamadas son invocadas de la siguiente forma:

func(option, opt_str, value, parser, *args, **kwargs)

donde

option

es la instancia de Option que invoca a la retrollamada

opt_str

es la cadena de opción encontrada en la línea de comandos que activa la retrollamada. (Si se utilizó una opción larga abreviada, opt_str será la cadena de opción canónica completa— por ejemplo, si el usuario ingresa --foo en la línea de comandos como una abreviatura de --foobar, entonces opt_str será "--foobar".)

value

es el argumento de esta opción encontrado en la línea de comandos. optparse solo esperará un argumento si type está establecido. El tipo de value será el tipo implícito en el tipo de la propia opción. Si type es None para esta opción (no se espera ningún argumento), entonces value será también None. Si nargs es mayor que 1, value será una tupla con los valores del tipo apropiado.

parser

es la instancia de OptionParser que controla todo. Su utilidad principal radica en que permite acceder a otros datos de interés a través de sus atributos de instancia:

parser.largs

la lista actual de argumentos que sobran, es decir, argumentos que se han consumido pero que no son opciones ni argumentos de opción. Siéntete libre de modificar parser.largs, por ejemplo, agregando más argumentos. (Esta lista se convertirá en args, el segundo valor de retorno del método parse_args().)

parser.rargs

la lista actual de argumentos restantes, es decir, los argumentos que quedan a continuación de opt_str y value (si corresponde), una vez eliminados ambos. Siéntete libre de modificar parser.rargs, por ejemplo, consumiendo más argumentos.

parser.values

el objeto donde los valores de las opciones son almacenados por defecto (una instancia de optparse.OptionValues). Esto permite que las retrollamadas utilicen el mismo mecanismo que el resto de optparse para almacenar valores de las opciones; no es necesario perder el tiempo con globales o clausuras. También se puede acceder a los valores de las opciones o modificarlos si ya se encuentran en la línea de comandos.

args

es una tupla de argumentos posicionales arbitrarios suministrados a través del atributo de opción callback_args.

kwargs

es un diccionario con argumentos por palabra clave arbitrarios proporcionados por callback_kwargs.

Lanzando errores en una retrollamada

La retrollamada debería lanzar una excepción OptionValueError si hay algún problema con la opción o su(s) argumento(s). Esto permite a optparse detectar el problema y finalizar el programa, imprimiendo el mensaje de error que hayas proporciones en la salida de error estándar. El mensaje debe ser claro, conciso, preciso y mencionar la opción que causa la excepción. De lo contrario, el usuario tendrá dificultades para descubrir qué hizo mal.

Ejemplo de retrollamada 1: una retrollamada trivial

Aquí hay un ejemplo de una opción con retrollamada que no tiene argumentos y simplemente registra que se encontró la opción en la línea de comandos:

def record_foo_seen(option, opt_str, value, parser):
    parser.values.saw_foo = True

parser.add_option("--foo", action="callback", callback=record_foo_seen)

Ciertamente, se puede hacer lo mismo simplemente con la acción "store_true".

Ejemplo de retrollamada 2: comprobar el orden de las opciones

Aquí tenemos un ejemplo un poco más interesante: registra el hecho de que se ha encontrado -a, pero lanza un error si viene después de -b en la línea de comandos

def check_order(option, opt_str, value, parser):
    if parser.values.b:
        raise OptionValueError("can't use -a after -b")
    parser.values.a = 1
...
parser.add_option("-a", action="callback", callback=check_order)
parser.add_option("-b", action="store_true", dest="b")

Ejemplo de retrollamada 3: comprobar el orden de las opciones (generalizado)

Si deseas reutilizar esta misma retrollamada para varias opciones similares (establecer un flag, pero lanzar un error si ya se ha encontrado -b), necesitas un poco más de trabajo: tanto el mensaje de error como el flag que estableces deben generalizarse:

def check_order(option, opt_str, value, parser):
    if parser.values.b:
        raise OptionValueError("can't use %s after -b" % opt_str)
    setattr(parser.values, option.dest, 1)
...
parser.add_option("-a", action="callback", callback=check_order, dest='a')
parser.add_option("-b", action="store_true", dest="b")
parser.add_option("-c", action="callback", callback=check_order, dest='c')

Ejemplo de retrollamada 4: comprobar una condición arbitraria

Por supuesto, puedes poner cualquier condición aquí, no estás limitado a verificar los valores de las opciones previamente definidas. Por ejemplo, si tienes opciones que no deberían llamarse cuando hay luna llena, todo lo que tienes que hacer es lo siguiente:

def check_moon(option, opt_str, value, parser):
    if is_moon_full():
        raise OptionValueError("%s option invalid when moon is full"
                               % opt_str)
    setattr(parser.values, option.dest, 1)
...
parser.add_option("--foo",
                  action="callback", callback=check_moon, dest="foo")

(La definición de is_moon_full() se deja como ejercicio para el lector).

Ejemplo de retrollamada 5: argumentos fijos

Las cosas se ponen un poco más interesantes cuando se definen opciones con retrollamada que toman un número fijo de argumentos. Especificar que una opción con retrollamada toma argumentos es similar a definir una opción "store" o "append": si se define type, entonces la opción toma un argumento que debe poder convertirse a ese tipo; si además se define nargs, entonces la opción toma nargs argumentos.

Aquí hay un ejemplo que simplemente emula la acción "store" estándar:

def store_value(option, opt_str, value, parser):
    setattr(parser.values, option.dest, value)
...
parser.add_option("--foo",
                  action="callback", callback=store_value,
                  type="int", nargs=3, dest="foo")

Ten en cuenta que optparse se encarga de consumir 3 argumentos y convertirlos a números enteros por ti; todo lo que tienes que hacer es almacenarlos. (En cualquier caso, obviamente no necesitas hacer uso de una retrollamada para este ejemplo).

Ejemplo de retrollamada 6: argumentos variables

Las cosas se complican si quieres que una opción pueda tomar un número variable de argumentos. En este caso, si que deberás escribir una retrollamada, ya que el módulo optparse no proporciona ninguna capacidad incorporada para ello. Además, tienes que lidiar con ciertos entresijos del análisis convencional de la línea de comandos de Unix, que optparse normalmente maneja por ti. En concreto, las retrollamadas deben implementar las reglas convencionales para los argumentos -- y - desnudos:

tanto -- como - pueden ser argumentos de opción

-- desnudo (si no es el argumento de alguna opción): detener el procesamiento de la línea de comandos y descartar el --

- desnudo (si no es el argumento de alguna opción): detener el procesamiento de la línea de comandos pero mantener el - (añadiéndolo a parser.largs)

Si deseas que una opción tenga un número variable de argumentos, hay varios problemas sutiles y complicados de los que deberás preocuparte. La implementación exacta que elijas dependerá de los sacrificios que estés dispuesto a hacer en tu aplicación (razón por la cual, el módulo optparse no admite directamente este tipo de cosas).

En cualquier caso, aquí hay un intento de una retrollamada para una opción con un número de argumentos variable:

def vararg_callback(option, opt_str, value, parser):
    assert value is None
    value = []

    def floatable(str):
        try:
            float(str)
            return True
        except ValueError:
            return False

    for arg in parser.rargs:
        # stop on --foo like options
        if arg[:2] == "--" and len(arg) > 2:
            break
        # stop on -a, but not on -3 or -3.0
        if arg[:1] == "-" and len(arg) > 1 and not floatable(arg):
            break
        value.append(arg)

    del parser.rargs[:len(value)]
    setattr(parser.values, option.dest, value)

...
parser.add_option("-c", "--callback", dest="vararg_attr",
                  action="callback", callback=vararg_callback)

Extendiendo el módulo optparse

Dado que los dos factores principales que controlan como el módulo optparse interpreta las opciones de la línea de comandos son la acción y el tipo de cada opción, los objetivos más probables de extensión son agregar nuevas acciones y nuevos tipos.

Agregando nuevos tipos

Para añadir nuevos tipos, necesitas definir tu propia subclase de la clase Option de optparse. Esta clase tiene un par de atributos que definen los tipos de optparse: TYPES y TYPE_CHECKER.

Option.TYPES

Una tupla con nombres de tipos. En tu subclase, simplemente define una nueva tupla TYPES que se base en la estándar.

Option.TYPE_CHECKER

Un diccionario que asigna nombres de tipos a funciones de verificación de tipo. Una función de verificación de tipo tiene la siguiente firma:

def check_mytype(option, opt, value)

donde option es una instancia de Option, opt es una cadena de opción (por ejemplo, -f) y value es la cadena de caracteres de la línea de comandos que debe comprobarse y convertirse al tipo deseado. check_mytype() debería retornar un objeto del tipo hipotético mytype. El valor retornado por una función de verificación de tipo terminará formando parte de la instancia de OptionValues retornada por el método OptionParser.parse_args() o será pasada a una retrollamada como parámetro value.

Tu función de verificación de tipo debería lanzar una excepción OptionValueError si encuentra algún problema. OptionValueError toma una cadena de caracteres como único argumento, que es pasada tal cual al método error() de la clase OptionParser, que a su vez antepone a la misma el nombre del programa y la cadena "error:" e imprime todo en la salida de error estándar antes de finalizar el proceso.

Aquí hay un ejemplo absurdo que demuestra cómo agregar un tipo de opción "complex" para analizar números complejos al estilo Python en la línea de comandos. (Esto es aún más absurdo de lo que en principio parece, porque en al versión 1.3 de optparse se agregó soporte incorporado para números complejos, pero no importa).

Primero, las importaciones necesarias:

from copy import copy
from optparse import Option, OptionValueError

En primer lugar, debes definir tu verificador de tipo, ya que se hace referencia a él más adelante (en el atributo de clase TYPE_CHECKER de tu subclase de Option):

def check_complex(option, opt, value):
    try:
        return complex(value)
    except ValueError:
        raise OptionValueError(
            "option %s: invalid complex value: %r" % (opt, value))

Finalmente, la subclase de Option:

class MyOption (Option):
    TYPES = Option.TYPES + ("complex",)
    TYPE_CHECKER = copy(Option.TYPE_CHECKER)
    TYPE_CHECKER["complex"] = check_complex

(Si no hacemos una copia (mediante copy()), de Option.TYPE_CHECKER, terminaríamos modificando el atributo TYPE_CHECKER de la clase Option de optparse. Tratándose de Python, nada te impide hacer eso, excepto los buenos modales y el sentido común.)

¡Y eso es todo! Ahora puedes escribir un script que use tu nuevo tipo de opción como cualquier otro script basado en optparse, excepto que debes indicarle a tu OptionParser que use MyOption en lugar de Option:

parser = OptionParser(option_class=MyOption)
parser.add_option("-c", type="complex")

Alternativamente, puedes crear tu propia lista de opciones y pasarla a OptionParser; si no usas add_option() de la manera anterior, no necesitas decirle a OptionParser qué clase de opción usar:

option_list = [MyOption("-c", action="store", type="complex", dest="c")]
parser = OptionParser(option_list=option_list)

Agregando nuevas acciones

Agregar nuevas acciones es un poco más complicado, dado que hay que comprender que optparse establece un par de categorías para las acciones:

Acciones «store»

acciones que dan como resultado que optparse almacene un valor en un atributo de la instancia actual de OptionValues. Estas opciones requieren un atributo dest para que pueda ser proporcionado al constructor de Option.

Acciones «typed»

acciones que toman un valor de la línea de comandos, esperando que sea de cierto tipo; o mejor dicho, una cadena de caracteres que se pueda convertir a un determinado tipo. Estas opciones requieren un atributo type para el constructor de Option.

Ambas categorías se solapan entre si: algunas acciones store predeterminadas son "store", "store_const", "append" y "count", mientras que las acciones «typed» predeterminadas son "store", "append" y "callback".

Cuando agregas una acción, debes categorizarla enumerándola en al menos uno de los siguientes atributos de clase de la clase Option (todos ellos son listas de cadenas de caracteres):

Option.ACTIONS

Todas las acciones deben aparecer en ACTIONS.

Option.STORE_ACTIONS

Las acciones «store» también se enumeran aquí.

Option.TYPED_ACTIONS

Las acciones «typed» también se enumeran aquí.

Option.ALWAYS_TYPED_ACTIONS

Las acciones que siempre toman un tipo (es decir, aquellas cuyas opciones siempre toman un valor) también deben enumerarse aquí. La única consecuencia de esto es que optparse asigna el tipo predeterminado, string, a las opciones cuya acción se enumera en ALWAYS_TYPED_ACTIONS pero que no tienen asignado un tipo explícito.

Para implementar realmente tu nueva acción, debes redefinir el método take_action() de Option, implementando un nuevo método que reconozca tu acción.

Por ejemplo, agreguemos una nueva acción "extend". Esta es similar a la acción estándar "append", pero en lugar de tomar un solo valor de la línea de comandos y agregarlo a una lista existente, "extend" tomará múltiples valores en una sola cadena de caracteres delimitada por comas y amplía una lista previamente existente con ellos. Es decir, si --names es una opción "extend" de tipo "string", la línea de comandos

--names=foo,bar --names blah --names ding,dong

daría como resultado una lista como la siguiente:

["foo", "bar", "blah", "ding", "dong"]

De nuevo, definimos una subclase de Option:

class MyOption(Option):

    ACTIONS = Option.ACTIONS + ("extend",)
    STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",)
    TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",)
    ALWAYS_TYPED_ACTIONS = Option.ALWAYS_TYPED_ACTIONS + ("extend",)

    def take_action(self, action, dest, opt, value, values, parser):
        if action == "extend":
            lvalue = value.split(",")
            values.ensure_value(dest, []).extend(lvalue)
        else:
            Option.take_action(
                self, action, dest, opt, value, values, parser)

Detalles a tener en cuenta:

"extend" espera un valor en la línea de comandos y también almacena ese valor en algún lugar, por lo que lo agregamos tanto a STORE_ACTIONS como a TYPED_ACTIONS.

para asegurarnos de que optparse asigna el tipo predeterminado "string" a las acciones "extend", agregamos también la acción "extend" a ALWAYS_TYPED_ACTIONS.

el método MyOption.take_action() solo se encarga de implementar esta nueva acción y posteriormente le pasa el control al método Option.take_action() para las acciones estándar de optparse.

values es una instancia de la clase optparse_parser.Values, que proporciona el útil método ensure_value(). El método ensure_value() es en esencia lo mismo que getattr() pero con un mecanismo de seguridad agregado. Es llamado como:

values.ensure_value(attr, value)

Si el atributo attr de values no existe o es None, entonces ensure_value() primero lo establece en value y luego retorna el atributo actualizado. Esto es muy útil para acciones como "extend", "append" y "count", dado que todas ellas acumulan datos en una variable y esperan que esa variable sea de cierto tipo (una lista para las dos primeras, un número entero para la última). Usar el método ensure_value() significa que los scripts que usan tu acción no tienen que preocuparse por establecer un valor predeterminado para los destinos de opción en cuestión; simplemente pueden dejar el valor predeterminado como None y secure_value() se encargará de que todo esté correcto cuando sea necesario.

ossaudiodev — Acceso a dispositivos de audio compatibles con OSS

Obsoleto desde la versión 3.11: The ossaudiodev module is deprecated (see PEP 594 [https://www.python.org/dev/peps/pep-0594#ossaudiodev] for details).

Este módulo le permite acceder a la interfaz de audio OSS (Open Sound System). OSS está disponible para una amplia gama de Unices comerciales y de código abierto, y es la interfaz de audio estándar para Linux y versiones recientes de FreeBSD.

Distinto en la versión 3.3: Las operaciones en este módulo ahora generan OSError donde IOError` es generado.

Ver también

Open Sound System Programmer’s Guide [http://www.opensound.com/pguide/oss.pdf]

la documentación oficial de la API de OSS C

El módulo define una gran cantidad de constantes suministradas por el controlador de dispositivo OSS; consulte <sys/soundcard.h> en Linux o FreeBSD para obtener un listado.

ossaudiodev define las siguientes variables y funciones:

exception ossaudiodev.OSSAudioError

Esta excepción se genera en ciertos errores. El argumento es una cadena que describe qué salió mal.

(Si ossaudiodev` recibe un error de una llamada al sistema como open(), write(), o ioctl(), genera OSError. Los errores detectados directamente por ossaudiodev dan como resultado OSSAudioError.)

(Para compatibilidad con versiones anteriores, la clase de excepción también está disponible como ossaudiodev.error.)

ossaudiodev.open(mode)

ossaudiodev.open(device, mode)

Abra un dispositivo de audio y retorne un objeto de dispositivo de audio OSS. Este objeto admite muchos métodos similares a archivos, como read(), write(), and fileno() (aunque existen diferencias sutiles entre la semántica de lectura/escritura convencional de Unix y la de audio OSS dispositivos). También es compatible con varios métodos específicos de audio; vea a continuación la lista completa de métodos.

device es el nombre de archivo del dispositivo de audio que se utilizará. Si no se especifica, este módulo primero busca en la variable de entorno AUDIODEV para un dispositivo a usar. Si no se encuentra, vuelve a /dev/dsp.

mode es uno de ’r’ para acceso de solo lectura (grabación), ’w’ para acceso de solo escritura (reproducción) y ’rw’ para ambos. Dado que muchas tarjetas de sonido solo permiten que un proceso tenga la grabadora o el reproductor abiertos a la vez, es una buena idea abrir el dispositivo solo para la actividad necesaria. Además, algunas tarjetas de sonido son semidúplex: se pueden abrir para leer o escribir, pero no ambas a la vez.

Tenga en cuenta la sintaxis de llamada inusual: el first argumento es opcional y el segundo es obligatorio. Este es un artefacto histórico para la compatibilidad con el módulo anterior linuxaudiodev que ossaudiodev reemplaza.

ossaudiodev.openmixer([device])

Abra un dispositivo mezclador y retorne un objeto de dispositivo mezclador OSS. device es el nombre de archivo del dispositivo mezclador que se utilizará. Si no se especifica, este módulo primero busca en la variable de entorno MIXERDEV para usar un dispositivo. Si no se encuentra, vuelve a /dev/mixer.

Objetos de dispositivo de audio

Antes de poder escribir o leer desde un dispositivo de audio, debe llamar a tres métodos en el orden correcto:

setfmt() para configurar el formato de salida

channels() para configurar el número de canales

speed() para configurar la frecuencia de muestreo

Alternativamente, puede usar el método setparameters() para configurar los tres parámetros de audio a la vez. Esto es más conveniente, pero puede que no sea tan flexible en todos los casos.

Los objetos de dispositivo de audio retornados por open() definen los siguientes métodos y atributos (de solo lectura):

oss_audio_device.close()

Cierre explícitamente el dispositivo de audio. Cuando haya terminado de escribir o leer desde un dispositivo de audio, debe cerrarlo explícitamente. Un dispositivo cerrado no se puede volver a utilizar.

oss_audio_device.fileno()

Retorna el descriptor de archivo asociado con el dispositivo.

oss_audio_device.read(size)

Leer size bytes de la entrada de audio y retornarlos como una cadena de Python. A diferencia de la mayoría de los controladores de dispositivos Unix, los dispositivos de audio OSS en modo de bloqueo (el predeterminado) bloquearán read() hasta que esté disponible toda la cantidad de datos solicitada.

oss_audio_device.write(data)

Escriba un bytes-like object data en el dispositivo de audio y retorne el número de bytes escritos. Si el dispositivo de audio está en modo de bloqueo (el predeterminado), todos los datos siempre se escriben (nuevamente, esto es diferente de la semántica habitual del dispositivo Unix). Si el dispositivo está en modo sin bloqueo, es posible que algunos datos no se escriban—see writeall().

Distinto en la versión 3.5: Ahora se aceptan objetos con permisos de escritura con formato bytes-like object.

oss_audio_device.writeall(data)

Escriba un bytes-like object data en el dispositivo de audio: espera hasta que el dispositivo de audio sea capaz de aceptar datos, escribe tantos datos como acepte y repite hasta que data se hayan escrito por completo. Si el dispositivo está en modo de bloqueo (el predeterminado), esto tiene el mismo efecto que write(); writeall() solo es útil en el modo sin bloqueo. No tiene valor de retorno, ya que la cantidad de datos escritos siempre es igual a la cantidad de datos suministrados.

Distinto en la versión 3.5: Ahora se aceptan objetos con permisos de escritura con formato bytes-like object.

Distinto en la versión 3.2: Los objetos de dispositivo de audio también admiten el protocolo de gestión de contexto, es decir, se pueden utilizar en una declaración with.

Los siguientes métodos se asignan exactamente a una llamada al sistema ioctl(). La correspondencia es obvia: por ejemplo, setfmt() corresponde al SNDCTL_DSP_SETFMT ioctl, y sync() a SNDCTL_DSP_SYNC (esto puede ser útil cuando se consulta la documentación de OSS). Si el subyacente ioctl() falla, todos generan OSError.

oss_audio_device.nonblock()

Ponga el dispositivo en modo sin bloqueo. Una vez en el modo sin bloqueo, no hay forma de volverlo al modo de bloqueo.

oss_audio_device.getfmts()

Retorna una máscara de bits de los formatos de salida de audio admitidos por la tarjeta de sonido. Algunos de los formatos admitidos por OSS son:

Formato

Descripción

AFMT_MU_LAW

una codificación logarítmica (utilizada por los archivos Sun .au y /dev/audio)

AFMT_A_LAW

una codificación logarítmica

AFMT_IMA_ADPCM

un formato comprimido 4:1 definido por la Interactive Multimedia Association

AFMT_U8

Audio de 8 bits sin firmar

AFMT_S16_LE

Orden de bytes little-endian firmado, audio de 16 bits (como lo utilizan los procesadores Intel)

AFMT_S16_BE

Orden de bytes big-endian firmado, audio de 16 bits (como lo utilizan 68k, PowerPC, Sparc)

AFMT_S8

Firmado, audio de 8 bits

AFMT_U16_LE

Audio little-endian de 16 bits sin firmar

AFMT_U16_BE

Audio big-endian de 16 bits sin firmar

Consulte la documentación de OSS para obtener una lista completa de los formatos de audio y tenga en cuenta que la mayoría de los dispositivos solo admiten un subconjunto de estos formatos. Algunos dispositivos antiguos solo admiten AFMT_U8; el formato más común utilizado hoy en día es AFMT_S16_LE.

oss_audio_device.setfmt(format)

Intente establecer el formato de audio actual en format—consulte getfmts() para obtener una lista. Retorna el formato de audio en el que se configuró el dispositivo, que puede no ser el formato solicitado. También se puede utilizar para retornar el formato de audio actual. Haga esto pasando un «formato de audio» de AFMT_QUERY.

oss_audio_device.channels(nchannels)

Establezca el número de canales de salida en nchannels. Un valor de 1 indica sonido monofónico, 2 estereofónico. Algunos dispositivos pueden tener más de 2 canales y algunos dispositivos de gama alta pueden no admitir mono. Retorna el número de canales en los que se configuró el dispositivo.

oss_audio_device.speed(samplerate)

Intente establecer la frecuencia de muestreo de audio en samplerate muestras por segundo. Retorna la tasa realmente establecida. La mayoría de los dispositivos de sonido no admiten frecuencias de muestreo arbitrarias. Las tarifas comunes son:

Velocidad

Descripción

8000

tasa predeterminada para /dev/audio

11025

grabación de voz

22050

44100

Audio con calidad de CD (a 16 bits/muestra y 2 canales)

96000

Audio con calidad de DVD (a 24 bits/muestra)

oss_audio_device.sync()

Espere hasta que el dispositivo de sonido haya reproducido todos los bytes de su búfer. (Esto sucede implícitamente cuando el dispositivo está cerrado). La documentación de OSS recomienda cerrar y volver a abrir el dispositivo en lugar de usar sync().

oss_audio_device.reset()

Deje de reproducir o grabar inmediatamente y retorne el dispositivo a un estado en el que pueda aceptar comandos. La documentación de OSS recomienda cerrar y volver a abrir el dispositivo después de llamar reset().

oss_audio_device.post()

Dígale al controlador que es probable que haya una pausa en la salida, lo que hace posible que el dispositivo maneje la pausa de manera más inteligente. Puede usar esto después de reproducir un efecto de sonido puntual, antes de esperar la entrada del usuario o antes de realizar E/S de disco.

Los siguientes métodos de conveniencia combinan varios ioctl, o un ioctl y algunos cálculos simples.

oss_audio_device.setparameters(format, nchannels, samplerate[, strict=False])

Configure los parámetros clave de muestreo de audio (formato de muestra, número de canales y frecuencia de muestreo) en una llamada de método. format, nchannels, y samplerate deben ser como se especifica en los métodos setfmt(), channels(), y speed(). Si strict es verdadero, setparameters() comprueba si cada parámetro se estableció realmente en el valor solicitado, y genera OSSAudioError si no es así. Retorna una tupla (format, nchannels, samplerate) que indica los valores de los parámetros que realmente estableció el controlador del dispositivo (es decir, los mismos que los valores retornados de setfmt(), channels(), y speed()).

Por ejemplo,

(fmt, channels, rate) = dsp.setparameters(fmt, channels, rate)

es equivalente a

fmt = dsp.setfmt(fmt)
channels = dsp.channels(channels)
rate = dsp.rate(rate)

oss_audio_device.bufsize()

Retorna el tamaño del búfer de hardware, en muestras.

oss_audio_device.obufcount()

Retorna el número de muestras que están en el búfer de hardware que aún no se han reproducido.

oss_audio_device.obuffree()

Retorna el número de muestras que se podrían poner en cola en el búfer de hardware para reproducirse sin bloqueos.

Los objetos de dispositivo de audio también admiten varios atributos de solo lectura:

oss_audio_device.closed

Booleano que indica si el dispositivo se ha cerrado.

oss_audio_device.name

Cadena que contiene el nombre del archivo del dispositivo.

oss_audio_device.mode

El modo de E/S para el archivo, ya sea "r", "rw", o "w".

Objetos del dispositivo mezclador

El objeto del mezclador proporciona dos métodos similares a archivos:

oss_mixer_device.close()

Este método cierra el archivo del dispositivo mezclador abierto. Cualquier otro intento de usar el mezclador después de que este archivo esté cerrado generará un OSError.

oss_mixer_device.fileno()

Retorna el número de identificador de archivo del archivo del dispositivo mezclador abierto.

Distinto en la versión 3.2: Los objetos Mixer también admiten el protocolo de gestión de contexto.

Los métodos restantes son específicos para la mezcla de audio:

oss_mixer_device.controls()

Este método retorna una máscara de bits que especifica los controles del mezclador disponibles («Control» es un «canal» mezclable específico, como SOUND_MIXER_PCM o SOUND_MIXER_SYNTH). Esta máscara de bits indica un subconjunto de todos los controles de mezclador disponibles — las constantes SOUND_MIXER_* definidas a nivel de módulo. Para determinar si, por ejemplo, el objeto mezclador actual admite un mezclador PCM, utilice el siguiente código Python:

mixer=ossaudiodev.openmixer()
if mixer.controls() & (1 << ossaudiodev.SOUND_MIXER_PCM):
    # PCM is supported
    ... code ...

Para la mayoría de los propósitos, los controles SOUND_MIXER_VOLUME (volumen maestro) y SOUND_MIXER_PCM deberían ser suficientes — pero el código que usa el mezclador debe ser flexible cuando se trata de elegir los controles del mezclador. En el Ultrasonido Gravis, por ejemplo, SOUND_MIXER_VOLUME no existe.

oss_mixer_device.stereocontrols()

Retorna una máscara de bits que indica los controles del mezclador estéreo. Si se establece un bit, el control correspondiente es estéreo; si no está configurado, el control es monofónico o no es compatible con el mezclador (úselo en combinación con controls() para determinar cuál).

Consulte el ejemplo de código de la función controls() para ver un ejemplo de cómo obtener datos de una máscara de bits.

oss_mixer_device.reccontrols()

Retorna una máscara de bits que especifica los controles del mezclador que se pueden usar para grabar. Consulte el ejemplo de código de controls() para ver un ejemplo de lectura desde una máscara de bits.

oss_mixer_device.get(control)

Retorna el volumen de un control de mezcla determinado. El volumen retornado es una tupla de 2 (left_volume,right_volume). Los volúmenes se especifican como números del 0 (silencioso) al 100 (volumen completo). Si el control es monofónico, todavía se retorna una tupla de 2, pero ambos volúmenes son iguales.

Genera OSSAudioError si se especifica un control no válido, o OSError si se especifica un control no admitido.

oss_mixer_device.set(control, (left, right))

Establece el volumen para un control de mezclador dado en (left,right). left y right deben ser enteros y estar entre 0 (silencio) y 100 (volumen completo). En caso de éxito, el nuevo volumen se retorna como 2 tuplas. Tenga en cuenta que puede que no sea exactamente el mismo que el volumen especificado, debido a la resolución limitada de algunos mezcladores de tarjetas de sonido.

Aumenta OSSAudioError si se especificó un control de mezcla no válido, o si los volúmenes especificados estaban fuera de rango.

oss_mixer_device.get_recsrc()

Este método retorna una máscara de bits que indica qué control(es) se están utilizando actualmente como fuente de grabación.

oss_mixer_device.set_recsrc(bitmask)

Llame a esta función para especificar una fuente de grabación. Retorna una máscara de bits que indica la nueva fuente de grabación (o fuentes) si tiene éxito; plantea OSError si se especificó una fuente no válida. Para configurar la fuente de grabación actual a la entrada del micrófono:

mixer.setrecsrc (1 << ossaudiodev.SOUND_MIXER_MIC)

pipes — Interfaz para tuberías de shell

Código fuente: Lib/pipes.py [https://github.com/python/cpython/tree/3.9/Lib/pipes.py]

Obsoleto desde la versión 3.11: The pipes module is deprecated (see PEP 594 [https://www.python.org/dev/peps/pep-0594#pipes] for details). Please use the subprocess module instead.

El módulo pipes define una clase para abstraer el concepto de una tubería — una secuencia de conversores de un archivo a otro.

Debido a que el módulo utiliza líneas de comando /bin/sh, se requiere una interfaz POSIX o un shell compatible para ejecutar os.system() y os.popen().

El módulo pipes define la siguiente clase:

class pipes.Template

Una abstracción de una tubería.

Ejemplo:

>>> import pipes
>>> t = pipes.Template()
>>> t.append('tr a-z A-Z', '--')
>>> f = t.open('pipefile', 'w')
>>> f.write('hello world')
>>> f.close()
>>> open('pipefile').read()
'HELLO WORLD'

Objetos Template

Las instancias Template tienen los siguientes métodos:

Template.reset()

Recupera el estado inicial del Template de una tubería.

Template.clone()

Retorna una nueva y equivalente instancia del Template de una tubería.

Template.debug(flag)

Si flag es verdadero, activa la depuración. Si no, la depuración no se activa. Cuando la depuración está activada, los comandos a ejecutar son impresos, y se le añade el comando set -x a la shell para ser más verboso.

Template.append(cmd, kind)

Añade una nueva acción al final. La variable cmd tiene que ser un comando válido de Bourne Shell. La variable kind está formada por dos letras.

La primera letra puede ser tanto '-' (que significa que el comando lee su entrada de datos estándar), 'f' (que significa que el comando lee un fichero desde línea de comandos) o '.' (que significa que el comando no lee ninguna entrada de datos, y por tanto tiene que ser el primero.)

De manera parecida, la segunda letra puede ser tanto '-' (que significa que el comando escribe a la salida de datos estándar), 'f' (que significa que el comando escribirá a un fichero de la línea de comandos) o '.' (que significa que el comando no escribe nada, por lo que debe ser el primero)

Template.prepend(cmd, kind)

Añade una nueva acción al principio. Ver append() para la explicación de los argumentos.

Template.open(file, mode)

Retorna un objeto similar a un fichero, abierto a file, pero leído o escrito por la tubería. Destacar que solo una de 'r' o 'w' puede ser añadida.

Template.copy(infile, outfile)

Copia infile a outfile a través de la tubería.

smtpd — Servidor SMTP

Source code: Lib/smtpd.py [https://github.com/python/cpython/tree/3.9/Lib/smtpd.py]

Este módulo ofrece varias clases para implementar servidores SMTP (correo electrónico).

Obsoleto desde la versión 3.6: smtpd will be removed in Python 3.12 (see PEP 594 [https://www.python.org/dev/peps/pep-0594#smtpd] for details). The aiosmtpd [https://aiosmtpd.readthedocs.io/] package is a recommended replacement for this module. It is based on asyncio and provides a more straightforward API.

Este módulo ofrece varias implementaciones del servidor; una es una implementación genérica de no hace nada, pero cuyos métodos pueden ser sobrescritos para crear una implementación concreta, mientras que las otras dos ofrecen estrategias específicas de envío de correo.

Además, SMTPChannel puede ampliarse para implementar un comportamiento de interacción muy específico con clientes SMTP.

El código admite RFC 5321 [https://tools.ietf.org/html/rfc5321.html], más las extensiones RFC 1870 [https://tools.ietf.org/html/rfc1870.html] SIZE y RFC 6531 [https://tools.ietf.org/html/rfc6531.html] SMTPUTF8.

Objetos SMTPServer

class smtpd.SMTPServer(localaddr, remoteaddr, data_size_limit=33554432, map=None, enable_SMTPUTF8=False, decode_data=False)

Crea un nuevo objeto SMTPServer, que se vincula a la dirección local localaddr. Tratará remoteaddr como un transmisor SMTP ascendente. Tanto localaddr como remoteaddr deben ser una tupla (host, port). El objeto hereda de asyncore.dispatcher, por lo que se insertará en el bucle de eventos de asyncore en la instanciación.

data_size_limit especifica el número máximo de bytes que se aceptarán en un comando DATA. Un valor de None o 0 significa que no hay límite.

map es el mapa de conectores que se utilizará para las conexiones (un diccionario inicialmente vacío es un valor adecuado). Si no se especifica, se utiliza el mapa de socket global asyncore.

enable_SMTPUTF8 determina si la extensión SMTPUTF8 (como se define en RFC 6531 [https://tools.ietf.org/html/rfc6531.html]) debe estar habilitada. El valor predeterminado es False. Cuando es True, SMTPUTF8 se acepta como parámetro para el comando MAIL y cuando está presente se pasa a process_message() en la lista kwargs[‘mail_options’] . decode_data y enable_SMTPUTF8 no se pueden establecer en True al mismo tiempo.

decode_data especifica si la porción de datos de la transacción SMTP debe decodificarse usando UTF-8. Cuando decode_data es False (el valor predeterminado), el servidor anuncia la extensión 8BITMIME (RFC 6152 [https://tools.ietf.org/html/rfc6152.html]), acepta el parámetro BODY=8BITMIME al comando MAIL, y cuando está presente lo pasa a process_message() en la lista kwargs['mail_options']. decode_data y enable_SMTPUTF8 no se pueden establecer en True al mismo tiempo.

process_message(peer, mailfrom, rcpttos, data, **kwargs)

Lanza una excepción NotImplementedError. Sobrescribe este método en subclases para hacer algo útil con este mensaje. Todo lo que se haya pasado en el constructor como remoteaddr estará disponible en el atributo _remoteaddr. peer es la dirección del host remoto, mailfrom es el creador del sobre, rcpttos son los destinatarios del sobre y data es una cadena de caracteres que contiene el contenido del correo electrónico (que debe estar en formato RFC 5321 [https://tools.ietf.org/html/rfc5321.html]).

Si la palabra clave del constructor decode_data se establece en True, el argumento data será una cadena Unicode. Si se establece en False, será un objeto de bytes.

kwargs es un diccionario que contiene información adicional. Está vacío si se proporcionó decode_data=True como argumento de inicialización; de lo contrario, contiene las siguientes claves:

mail_options:

una lista de todos los parámetros recibidos para el comando MAIL (los elementos son cadenas en mayúsculas; ejemplo: ['BODY=8BITMIME', 'SMTPUTF8']).

rcpt_options:

igual que mail_options pero para el comando RCPT. Actualmente, no se admiten las opciones RCPT TO, por lo que, por ahora, siempre será una lista vacía.

Las implementaciones de process_message deben usar la firma **kwargs para aceptar argumentos por palabra clave arbitrarios, ya que las mejoras de características futuras pueden agregar claves al diccionario de argumentos de palabras clave.

Retorne None para solicitar una respuesta normal de 250 Ok; de lo contrario, retorne la cadena de respuesta deseada en formato RFC 5321 [https://tools.ietf.org/html/rfc5321.html].

channel_class

Sobrescriba este método en las subclases para usar una clase SMTPChannel personalizada para administrar clientes SMTP.

Nuevo en la versión 3.4: El argumento del constructor map.

Distinto en la versión 3.5: localaddr y remoteaddr ahora pueden contener direcciones IPv6.

Nuevo en la versión 3.5: Los parámetros del constructor decode_data y enable_SMTPUTF8, y el parámetro kwargs para process_message() cuando decode_data es False.

Distinto en la versión 3.6: decode_data ahora es False por defecto.

Objetos DebuggingServer

class smtpd.DebuggingServer(localaddr, remoteaddr)

Crea un nuevo servidor de depuración. Los argumentos son iguales que en SMTPServer. Los mensajes se descartarán y se imprimirán en la salida estándar.

Objetos PureProxy

class smtpd.PureProxy(localaddr, remoteaddr)

Crea un nuevo servidor proxy puro. Los argumentos son iguales que en SMTPServer. Todo se transmitirá a remoteaddr. Tenga en cuenta que ejecutar esto implica una buena posibilidad de convertirlo en un relé abierto, así que tenga cuidado.

Objetos MailmanProxy

class smtpd.MailmanProxy(localaddr, remoteaddr)

Deprecated since version 3.9, will be removed in version 3.11: MailmanProxy is deprecated, it depends on a Mailman module which no longer exists and therefore is already broken.

Crea un nuevo servidor proxy puro. Los argumentos son iguales que en SMTPServer. Todo se transmitirá a remoteaddr, a menos que las configuraciones locales de mailman conozcan una dirección, en cuyo caso se manejará a través de mailman. Tenga en cuenta que ejecutar esto implica una buena posibilidad de convertirlo en un relé abierto, así que tenga cuidado.

Objetos SMTPChannel

class smtpd.SMTPChannel(server, conn, addr, data_size_limit=33554432, map=None, enable_SMTPUTF8=False, decode_data=False)

Crea un nuevo objeto SMTPChannel que gestiona la comunicación entre el servidor y un único cliente SMTP.

conn y addr son según las variables de instancia que se describen a continuación.

data_size_limit especifica el número máximo de bytes que se aceptarán en un comando DATA. Un valor de None o 0 significa que no hay límite.

enable_SMTPUTF8 determina si la extensión SMTPUTF8 (como se define en RFC 6531 [https://tools.ietf.org/html/rfc6531.html]) debe estar habilitada. El valor predeterminado es False. decode_data y enable_SMTPUTF8 no se pueden establecer en True al mismo tiempo.

Se puede especificar un diccionario en map para evitar el uso de un mapa de socket global.

decode_data especifica si la porción de datos de la transacción SMTP debe decodificarse usando UTF-8. El valor predeterminado es False. decode_data y enable_SMTPUTF8 no se pueden establecer en True al mismo tiempo.

Para utilizar una implementación SMTPChannel personalizada, debe anular SMTPServer.channel_class de su SMTPServer.

Distinto en la versión 3.5: Se agregaron los parámetros decode_data y enable_SMTPUTF8.

Distinto en la versión 3.6: decode_data ahora es False por defecto.

La clase SMTPChannel tiene las siguientes variables de instancia:

smtp_server

Contiene el SMTPServer que generó este canal.

conn

Contiene el objeto de socket que se conecta al cliente.

addr

Contiene la dirección del cliente, el segundo valor retornado por socket.accept

received_lines

Contiene una lista de las cadenas de línea (decodificadas mediante UTF-8) recibidas del cliente. Las líneas tienen su final de línea "\r\n" traducido a "\n".

smtp_state

Contiene el estado actual del canal. Será COMMAND inicialmente y luego DATA después de que el cliente envíe una línea «DATA».

seen_greeting

Contiene una cadena de caracteres que contiene el saludo enviado por el cliente en su «HELO».

mailfrom

Contiene una cadena de caracteres que contiene la dirección identificada en la línea «MAIL FROM:» del cliente.

rcpttos

Contiene una lista de cadenas de caracteres que contienen las direcciones identificadas en las líneas «RCPT TO:» del cliente.

received_data

Contiene una cadena de caracteres que contiene todos los datos enviados por el cliente durante el estado de DATA, hasta pero sin incluir la terminación "\r\n.\r\n".

fqdn

Contiene el nombre de dominio completo del servidor como lo retorna socket.getfqdn().

peer

Contiene el nombre del par del cliente como lo retorna conn.getpeername() donde conn es conn.

La clase SMTPChannel opera invocando métodos llamados smtp_<command> al recibir una línea de comando del cliente. Construidos en la clase base SMTPChannel, son métodos para manejar los siguientes comandos (y responder a ellos de manera apropiada):

Comando

Acción tomada

HELO

Acepta el saludo del cliente y lo almacena en seen_greeting. Establece el servidor en el modo de comando base.

EHLO

Acepta el saludo del cliente y lo almacena en seen_greeting. Establece el servidor en el modo de comando extendido.

NOOP

No realiza ninguna acción.

QUIT

Cierra la conexión limpiamente.

MAIL

Acepta la sintaxis «MAIL FROM:» y almacena la dirección proporcionada como mailfrom. En el modo de comando extendido, acepta el atributo RFC 1870 [https://tools.ietf.org/html/rfc1870.html] SIZE y responde apropiadamente según el valor de data_size_limit.

RCPT

Acepta la sintaxis «RCPT TO:» y almacena las direcciones proporcionadas en la lista rcpttos.

RSET

Restablece mailfrom, rcpttos y received_data, pero no el saludo.

DATA

Establece el estado interno en DATA y almacena las líneas restantes del cliente en received_data hasta que se recibe el terminador ”\r\n.\r\n”.

HELP

Retorna información mínima sobre la sintaxis del comando

VRFY

Retorna el código 252 (el servidor no sabe si la dirección es válida)

EXPN

Informa que el comando no está implementado.

sndhdr — Determinar el tipo de archivo de sonido

Código fuente: Lib/sndhdr.py [https://github.com/python/cpython/tree/3.9/Lib/sndhdr.py]

Obsoleto desde la versión 3.11: The sndhdr module is deprecated (see PEP 594 [https://www.python.org/dev/peps/pep-0594#sndhdr] for details and alternatives).

El sndhdr proporciona funciones de utilidad que intentan determinar el tipo de datos de sonido que hay en un archivo. Cuando estas funciones son capaces de determinar qué tipo de datos sonoros se almacenan en un archivo, retornan un namedtuple(), que contiene cinco atributos: (filetype, framerate, nchannels, nframes, sampwidth). El valor de type indica el tipo de datos y será una de las cadenas siguientes cadenas: 'aifc', 'aiff', 'au', 'hcom', 'sndr', 'sndt', 'voc', 'wav', '8svx', 'sb', 'ub', o 'ul'. El sampling_rate será el valor actual o 0 si es desconocido o difícil de decodificar. De forma similar, channels será el número de canales o 0 si no se puede determinar o si el valor es difícil de decodificar. El valor de frames será el número de fotogramas o -1. El último elemento de la tupla, bits_per_sample, será el tamaño de la muestra en bits, 'A' para A-LAW o 'U' para u-LAW.

sndhdr.what(filename)

Determina el tipo de datos de sonido almacenados en el archivo filename usando whathdr(). Si se tiene éxito, retorna una namedtuple como se describe arriba, de lo contrario retorna None.

Distinto en la versión 3.5: El resultado cambió de una tupla a una namedtuple.

sndhdr.whathdr(filename)

Determina el tipo de dato de sonido almacenado en un archivo basado en el encabezado del archivo. El nombre del archivo viene dado por filename. Esta función retorna una namedtuple como se ha descrito anteriormente en caso de éxito o None.

Distinto en la versión 3.5: El resultado cambió de una tupla a una namedtuple.

spwd — La base de datos de contraseñas ocultas

Obsoleto desde la versión 3.11: The spwd module is deprecated (see PEP 594 [https://www.python.org/dev/peps/pep-0594#spwd] for details and alternatives).

Este módulo proporciona acceso a la base de datos de contraseñas ocultas de Unix. Está disponible en varias versiones de Unix.

Debe tener suficientes privilegios para acceder a la base de datos de contraseñas ocultas (esto generalmente significa que debe ser root).

Las entradas de la base de datos de contraseñas ocultas se informan como un objeto similar a una tupla, cuyos atributos corresponden a los miembros de la estructura spwd (campo de atributo a continuación, consulte <shadow.h>):

Índice

Atributo

Significado

0

sp_namp

Nombre de inicio de sesión

1

sp_pwdp

Contraseña encriptada

2

sp_lstchg

Fecha del último cambio

3

sp_min

Número mínimo de días entre cambios

4

sp_max

Número máximo de días entre cambios

5

sp_warn

Número de días antes de que expire la contraseña para advertir al usuario sobre ello

6

sp_inact

Número de días desde que caduca la contraseña hasta que se deshabilita la cuenta

7

sp_expire

Número de días desde 1970-01-01 cuando expira la cuenta

8

sp_flag

Reservado

Los elementos sp_namp y sp_pwdp son cadenas, todos los demás son números enteros. Se lanza KeyError si no se puede encontrar la entrada solicitada.

Se definen las siguientes funciones:

spwd.getspnam(name)

Retorna la entrada de la base de datos de contraseñas ocultas para el nombre de usuario especificado.

Distinto en la versión 3.6: Lanza un PermissionError en vez de KeyError si el usuario no tiene privilegios.

spwd.getspall()

Retorna una lista de todas las entradas de la base de datos de contraseñas ocultas disponibles, en orden arbitrario.

Ver también

Módulo grp

Una interfaz para la base de datos del grupo, similar a esta.

Módulo pwd

Una interfaz para la base de datos de contraseñas normal, similar a esta.

sunau — Lectura y escritura de ficheros Sun AU

Código fuente: Lib/sunau.py [https://github.com/python/cpython/tree/3.9/Lib/sunau.py]

Obsoleto desde la versión 3.11: The sunau module is deprecated (see PEP 594 [https://www.python.org/dev/peps/pep-0594#sunau] for details).

El módulo sunau provee una interfaz conveniente para el formato de sonido Sun AU. Note que este módulo es de interfaz compatible con los módulos aifc y wave.

Un fichero de audio consiste de un encabezado seguido por la información. Los campos del encabezado son:

Campo

Contenido

palabra mágica

Los cuatro bytes .snd.

tamaño del encabezado

Tamaño del encabezado, incluyendo información, en bytes.

tamaño de la información

Tamaño físico de la información, en bytes.

codificación

Indica cómo las muestras de audio están codificadas.

tasa de muestra

La tasa de muestreo.

# de canales

El número de canales en las muestras.

información

Cadena de caracteres ASCII dando una descripción del fichero de audio (rellenada con bytes nulos).

Aparte del campo de información, todos los campos de encabezado tienen 4 bytes de tamaño. Todos ellos son enteros sin signo codificados en orden de bytes big-endian.

El módulo sunau define las siguientes funciones:

sunau.open(file, mode)

Si file es una cadena, abre el fichero por ese nombre, de otra forma lo trata como un objeto similar a un fichero buscable. mode puede ser cualquiera de

'r'

Modo de sólo lectura.

'w'

Modo de sólo escritura.

Note que no acepta ficheros de lectura/escritura.

Un mode de 'r' retorna un objeto AU_read, mientras un mode de 'w' o 'wb' retorna un objeto AU_write.

El módulo sunau define la siguiente excepción:

exception sunau.Error

Un error generado cuando algo es imposible por especificaciones de Sun AU o deficiencia de implementación.

El módulo sunau define los siguientes ítems de información:

sunau.AUDIO_FILE_MAGIC

Un entero por cada fichero Sun AU válido comienza con, almacenada en la forma big-endian. Esto es la cadena .snd interpretada como un entero.

sunau.AUDIO_FILE_ENCODING_MULAW_8

sunau.AUDIO_FILE_ENCODING_LINEAR_8

sunau.AUDIO_FILE_ENCODING_LINEAR_16

sunau.AUDIO_FILE_ENCODING_LINEAR_24

sunau.AUDIO_FILE_ENCODING_LINEAR_32

sunau.AUDIO_FILE_ENCODING_ALAW_8

Valores del campo de codificación para el encabezado AU que son soportados por este módulo.

sunau.AUDIO_FILE_ENCODING_FLOAT

sunau.AUDIO_FILE_ENCODING_DOUBLE

sunau.AUDIO_FILE_ENCODING_ADPCM_G721

sunau.AUDIO_FILE_ENCODING_ADPCM_G722

sunau.AUDIO_FILE_ENCODING_ADPCM_G723_3

sunau.AUDIO_FILE_ENCODING_ADPCM_G723_5

Valores adicionales conocidos por el campo de codificación del encabezado AU, pero que no son soportados por este módulo.

Objetos AU_read

Objetos AU_read, como se retornan por open() arriba, tienen los siguientes métodos:

AU_read.close()

Cierra el flujo, y hace que la instancia sea inutilizable. (Esto es llamado automáticamente en la eliminación.)

AU_read.getnchannels()

Retorna el número de canales de audio (1 para mono, 2 para estéreo).

AU_read.getsampwidth()

Retorna el ancho de muestra en bytes.

AU_read.getframerate()

Retorna la frecuencia de muestreo.

AU_read.getnframes()

Retorna el número de cuadros por segundo de audio.

AU_read.getcomptype()

Retorna el tipo de compresión. Los tipos de compresión soportados son 'ULAW', 'ALAW' y 'NONE'.

AU_read.getcompname()

Versión legible por humanos de getcomptype(). Los tipos soportados tienen los nombres respectivos 'CCITT G.711 u-law', 'CCITT G.711 A-law' y 'not compressed'.

AU_read.getparams()

Retorna un namedtuple() (nchannels, sampwidth, framerate, nframes, comptype, compname), equivalente a la salida de los métodos get*().

AU_read.readframes(n)

Lee y retorna al menos n fotogramas de audio, como un objeto bytes. La información será retornada en formato linear. Si la información original está en formato u-LAW, será convertida.

AU_read.rewind()

Rebobina el puntero del fichero al comienzo del flujo de audio.

Los siguientes dos métodos definen un término «position» el cual es compatible entre ellos, y es de otra manera dependiente de la implementación.

AU_read.setpos(pos)

Establece el puntero del fichero a la posición especificada. Sólo valores retornados desde tell() deberían ser utilizados por pos.

AU_read.tell()

Retorna la posición actual del puntero de fichero. Note que el valor retornado no tiene nada que ver con la posición actual en el fichero.

Las siguientes dos funciones están definidas por compatibilidad con el aifc, y no hace nada interesante.

AU_read.getmarkers()

Retorna None.

AU_read.getmark(id)

Lanza un error.

Objetos AU_write

Objetos AU_write, como se retornan por open() arriba, tienen los siguientes métodos:

AU_write.setnchannels(n)

Establece el número de canales.

AU_write.setsampwidth(n)

Establece el ancho de muestra (en bytes.)

Distinto en la versión 3.4: Agregado soporte para muestras de 24 bits.

AU_write.setframerate(n)

Establece la velocidad de cuadros por segundo.

AU_write.setnframes(n)

Establece el número de cuadros por segundo. Esto puede ser cambiado más adelante, cuando y si más cuadros por segundo son escritos.

AU_write.setcomptype(type, name)

Establece el tipo de compresión y descripción. Sólo 'NONE' y 'ULAW' son soportados en salida.

AU_write.setparams(tuple)

La tuple debería ser (nchannels, sampwidth, framerate, nframes, comptype, compname), con valores válidos para los métodos set*(). Establece todos los parámetros.

AU_write.tell()

Retorna la posición actual en el fichero, con los mismos descargos de responsabilidad para los métodos AU_read.tell() y AU_read.setpos().

AU_write.writeframesraw(data)

Escribe cuadros por segundo de audio, sin corregir nframes.

Distinto en la versión 3.4: Cualquier bytes-like object es aceptado ahora.

AU_write.writeframes(data)

Escribe cuadros por segundo de audio y se asegura que nframes sea correcto.

Distinto en la versión 3.4: Cualquier bytes-like object es aceptado ahora.

AU_write.close()

Se asegura que nframes sea correcto, y cierra el fichero.

Este método es llamado después de la eliminación.

Note que es inválido establecer cualquier parámetro después de llamar writeframes() o writeframesraw().

telnetlib — cliente Telnet

Código fuente: Lib/telnetlib.py [https://github.com/python/cpython/tree/3.9/Lib/telnetlib.py]

Obsoleto desde la versión 3.11: The telnetlib module is deprecated (see PEP 594 [https://www.python.org/dev/peps/pep-0594#telnetlib] for details and alternatives).

El módulo telnetlib proporciona una clase Telnet que implementa el protocolo Telnet. Consulte RFC 854 [https://tools.ietf.org/html/rfc854.html] para obtener más información sobre el protocolo. Además, proporciona constantes simbólicas para los caracteres de protocolo (ver más abajo) y para las opciones telnet. Los nombres simbólicos de las opciones de telnet siguen las definiciones de arpa/telnet.h, con el TELOPT_ principal eliminado. Para conocer los nombres simbólicos de las opciones que tradicionalmente no se incluyen en arpa/telnet.h, consulte la propia fuente del módulo.

Las constantes simbólicas para los comandos telnet son: IAC, DONT, DO, WONT, WILL, SE (Subnegotiation End), NOP (No Operation), DM (Data Mark), BRK (Break), IP (Interrupt process), AO (Abort output), AYT (Are You There), EC (Eliminar Character), EL (Erase Line), GA (Go Ahead), SB (Subnegotiation Begin).

class telnetlib.Telnet(host=None, port=0[, timeout])

Telnet representa una conexión a un servidor Telnet. La instancia inicialmente no está conectada de forma predeterminada; el método open() debe utilizarse para establecer una conexión. Como alternativa, el nombre de host y el número de puerto opcional también se pueden pasar al constructor, en cuyo caso se establecerá la conexión con el servidor antes de que se retorne el constructor. El parámetro opcional timeout especifica un tiempo de espera en segundos para bloquear operaciones como el intento de conexión (si no se especifica, se usará la configuración de tiempo de espera predeterminada global).

No vuelve a abrir una instancia ya conectada.

Esta clase tiene muchos métodos read_*(). Tenga en cuenta que algunos de ellos generan EOFError cuando se lee el final de la conexión, porque pueden retornar una cadena vacía por otros motivos. Vea las descripciones individuales a continuación.

Un objeto Telnet es un gestor de contexto y se puede utilizar en una instrucción with. Cuando finaliza el bloque with, se llama al método close():

>>> from telnetlib import Telnet
>>> with Telnet('localhost', 23) as tn:
...     tn.interact()
...

Distinto en la versión 3.6: Soporte de gestor de contexto añadido

Ver también

RFC 854 [https://tools.ietf.org/html/rfc854.html] - Especificación del protocolo Telnet

Definición del protocolo Telnet.

Objetos Telnet

Las instancias Telnet contienen los siguientes métodos:

Telnet.read_until(expected, timeout=None)

Lee hasta que se encuentre una cadena de bytes determinada, expected, o hasta que hayan pasado los segundos timeout.

Cuando no se encuentra ninguna coincidencia, retorna lo que esté disponible en su lugar, posiblemente bytes vacíos. Lanza EOFError si la conexión está cerrada y no hay datos cocinados disponibles.

Telnet.read_all()

Lee todos los datos hasta EOF como bytes; bloquea hasta que se cierre la conexión.

Telnet.read_some()

Lee al menos un byte de datos cocinados a menos que se golpee EOF. Retorna b'' si se llega a EOF. Bloquea si no hay datos disponibles inmediatamente.

Telnet.read_very_eager()

Lee todo lo que puede ser sin bloquear en E/S (ansioso).

Lanza EOFError si la conexión está cerrada y no hay datos cocidos disponibles. Retorna b'' si no hay datos cocinados disponibles de otra manera. No bloquea a menos que esté en medio de una secuencia IAC.

Telnet.read_eager()

Lee los datos disponibles.

Lanza EOFError si la conexión está cerrada y no hay datos cocidos disponibles. Retorna b'' si no hay datos cocinados disponibles de otra manera. No bloquea a menos que esté en medio de una secuencia IAC.

Telnet.read_lazy()

Procesa y retorna datos ya en las colas (perezoso).

Lanza EOFError si la conexión está cerrada y no hay datos disponibles. Retorna b'' si no hay datos cocinados disponibles de otra manera. No bloquea a menos que esté en medio de una secuencia IAC.

Telnet.read_very_lazy()

Retorna los datos disponibles en la cola cocida (muy perezoso).

Lanza EOFError si la conexión está cerrada y no hay datos disponibles. Retorna b'' si no hay datos cocinados disponibles de otra manera. Este método nunca se bloquea.

Telnet.read_sb_data()

Retorna los datos recopilados entre un par SB/SE (suboption begin/end). La retrollamada debe tener acceso a estos datos cuando se invocó con un comando SE. Este método nunca se bloquea.

Telnet.open(host, port=0[, timeout])

Conecta a un host. El segundo argumento opcional es el número de puerto, que tiene como valor predeterminado el puerto Telnet estándar (23). El parámetro opcional timeout especifica un tiempo de espera en segundos para bloquear operaciones como el intento de conexión (si no se especifica, se usará la configuración de tiempo de espera predeterminada global).

No intente volver a abrir una instancia ya conectada.

Genera un evento de auditoría telnetlib. Telnet.open con argumentos self, host, port.

Telnet.msg(msg, *args)

Imprime un mensaje de depuración cuando el nivel de depuración sea > 0. Si hay argumentos adicionales, se sustituyen en el mensaje mediante el operador de formato de cadena de caracteres estándar.

Telnet.set_debuglevel(debuglevel)

Establece el nivel de depuración. Cuanto mayor sea el valor de debuglevel, más salida de depuración obtendrá (en sys.stdout).

Telnet.close()

Cierra la conexión.

Telnet.get_socket()

Retorna el objeto de socket utilizado internamente.

Telnet.fileno()

Retorna el descriptor de archivo del objeto de socket utilizado internamente.

Telnet.write(buffer)

Escribe una cadena de bytes en el socket, duplicando los caracteres IAC. Esto puede bloquearse si la conexión está bloqueada. Puede generar OSError si la conexión está cerrada.

Lanza un evento de auditoría telnetlib.Telnet.write con argumentos self, buffer.

Distinto en la versión 3.3: Este método se utiliza para lanzar socket.error, que ahora es un alias de OSError.

Telnet.interact()

Función de interacción, emula a un cliente Telnet muy tonto.

Telnet.mt_interact()

Versión multiproceso de interact().

Telnet.expect(list, timeout=None)

Lee hasta que uno de una lista de expresiones regulares coincida.

El primer argumento es una lista de expresiones regulares, compiladas (objetos regex) o no compiladas (cadenas de bytes). El segundo argumento opcional es un tiempo de espera, en segundos; el valor predeterminado es bloquear indefinidamente.

Retorna una tupla de tres elementos: el índice de la lista de la primera expresión regular que coincide; el objeto de coincidencia retornado; y los bytes leen hasta e incluyendo la coincidencia.

Si se encuentra el final del archivo y no se leyó ningún bytes, lanza EOFError. De lo contrario, cuando nada coincide, retorna (-1, None, data) donde data es los bytes recibidos hasta ahora (pueden ser bytes vacíos si se ha producido un tiempo de espera).

Si una expresión regular termina con una coincidencia expansiva (como .*) o si más de una expresión puede coincidir con la misma entrada, los resultados no son deterministas y pueden depender de la sincronización de E/S.

Telnet.set_option_negotiation_callback(callback)

Cada vez que se lee una opción telnet en el flujo de entrada, se llama a esta callback (si se establece) con los siguientes parámetros: callback(telnet socket, command (DO/DONT/WILL/WONT), opción). No hay ninguna otra acción se realiza después por telnetlib.

Ejemplo de Telnet

Un ejemplo sencillo que ilustra el uso típico:

import getpass
import telnetlib

HOST = "localhost"
user = input("Enter your remote account: ")
password = getpass.getpass()

tn = telnetlib.Telnet(HOST)

tn.read_until(b"login: ")
tn.write(user.encode('ascii') + b"\n")
if password:
    tn.read_until(b"Password: ")
    tn.write(password.encode('ascii') + b"\n")

tn.write(b"ls\n")
tn.write(b"exit\n")

print(tn.read_all().decode('ascii'))

uu — Codifica y decodifica archivos UUEncode

Código fuente: Lib/uu.py [https://github.com/python/cpython/tree/3.9/Lib/uu.py]

Obsoleto desde la versión 3.11: The uu module is deprecated (see PEP 594 [https://www.python.org/dev/peps/pep-0594#uu-and-the-uu-encoding] for details). base64 is a modern alternative.

Este módulo codifica y decodifica archivos en formato UUEncode, permitiendo la transmisión de datos binarios arbitrarios sobre conexiones de solo ASCII. Allí donde se espera un archivo como argumento, los métodos aceptan un objeto similar a un archivo. Por compatibilidad con versiones anteriores, una cadena que contenga un nombre de ruta también es aceptada, y el archivo correspondiente será abierto para lectura y escritura; el nombre de ruta '-' es entendido como la entrada o salida estándar. Sin embargo, esta interface es obsoleta; es mejor que el invocador abra el archivo por sí mismo y asegurarse de que, cuando se requiera, el modo sea 'rb' o 'wb' en Windows.

Este código fue contribuido por Lance Ellinghouse y modificado por Jack Jansen.

El módulo uu define las siguientes funciones:

uu.encode(in_file, out_file, name=None, mode=None, *, backtick=False)

Codificar con UUEncode el archivo in_file en el archivo out_file. El archivo codificado con UUEncode tendrá un encabezado especificando name y mode como valores por defecto para los resultados de la decodificación del archivo. Los valores por defecto iniciales son tomados de in_file, o '-' y 0o666 respectivamente. Si backtick es verdadero, los ceros son representados por '`' en lugar de espacios.

Distinto en la versión 3.7: Agregado el parámetro backtick.

uu.decode(in_file, out_file=None, mode=None, quiet=False)

Esta invocación decodifica el archivo codificado en UUEncode in_file y coloca el resultado en el archivo out_file. Si out_file es un nombre de ruta, mode es usado para establecer los bits de permiso si el archivo debe ser creado. Valores por defecto para out_file y mode se toman del encabezado UUEncode. Sin embargo, si el archivo especificado en el encabezado existe, se genera un uu.Error.

decode() puede imprimir una advertencia a error estándar si la entrada fue producida por un UUEncoder incorrecto y Python pudo recobrarse de ese error. Si se establece quiet a un valor verdadero se suprime esta advertencia.

exception uu.Error

Subclase de Exception, esta puede ser generada por uu.decode() en diversas situaciones, como las descriptas arriba, pero también si se incluye un encabezado mal formado o un archivo de entrada truncado.

Ver también

Módulo binascii

Módulo de soporte que contiene conversiones de ASCII a binario y de binario a ASCII.

xdrlib — Codificar y decodificar datos XDR

Código fuente: Lib/xdrlib.py [https://github.com/python/cpython/tree/3.9/Lib/xdrlib.py]

Obsoleto desde la versión 3.11: The xdrlib module is deprecated (see PEP 594 [https://www.python.org/dev/peps/pep-0594#xdrlib] for details).

El módulo xdrlib soporta el estándar de representación externa de datos (External Data Representation Standard) como se describe en RFC 1014 [https://tools.ietf.org/html/rfc1014.html], escrito por Sun Microsystems, Inc. en junio de 1987. Soporta la mayoría de los tipos de datos descritos en el RFC.

El módulo xdrlib define dos clases, una para empaquetar variables en la representación XDR, y otra para desempaquetar valores de la representación XDR. También hay dos clases de excepciones.

class xdrlib.Packer

Packer es la clase para empaquetar datos en la representación XDR. La clase Packer es instanciada sin argumentos.

class xdrlib.Unpacker(data)

Unpacker es la clase complementaria que desempaqueta los valores de datos XDR de un búfer de cadena. El búfer de entrada se proporciona como data.

Ver también

RFC 1014 [https://tools.ietf.org/html/rfc1014.html] - XDR: estándar de representación externa de datos

Este RFC definió la codificación de datos que era XDR en el momento en que este módulo fue escrito originalmente. Aparentemente ha quedado obsoleto, siendo reemplazado por RFC 1832 [https://tools.ietf.org/html/rfc1832.html].

RFC 1832 [https://tools.ietf.org/html/rfc1832.html] - XDR: estándar de representación externa de datos

El RFC más reciente que proporciona una definición revisada de XDR.

Instancias de la clase Packer

Las instancias de la clase Packer poseen los siguientes métodos:

Packer.get_buffer()

Retorna el búfer del paquete actual como una cadena de caracteres.

Packer.reset()

Restablece el búfer del paquete a la cadena de caracteres vacía.

En general, puedes empaquetar cualquiera de los tipos de datos XDR más comunes, invocando el método pack_tipo() apropiado. Cada método toma un solo argumento, el valor a empaquetar. Los siguientes métodos simples de empaquetado de tipos de datos son soportados: pack_uint(), pack_int(), pack_enum(), pack_bool(), pack_uhyper(), y pack_hyper().

Packer.pack_float(value)

Empaqueta el número de punto flotante de precisión simple, value.

Packer.pack_double(value)

Empaqueta el número de punto flotante de doble precisión, value.

Los siguientes métodos soportan el empaquetado de cadenas de caracteres, bytes y datos opacos:

Packer.pack_fstring(n, s)

Empaqueta una cadena de caracteres de longitud fija, s. n es la longitud de la cadena de caracteres pero no es empaquetada en el búfer de datos. La cadena de caracteres es rellenada con bytes nulos si es necesario, para garantizar que la longitud de los datos sea un múltiplo de 4 bytes.

Packer.pack_fopaque(n, data)

Empaqueta un flujo de datos opaco de longitud fija, similar a pack_fstring().

Packer.pack_string(s)

Empaqueta una cadena de caracteres de longitud variable, s. En primer lugar, la longitud de la cadena de caracteres es empaquetada como un entero sin signo, luego los datos de la cadena de caracteres son empaquetados con pack_fstring().

Packer.pack_opaque(data)

Empaqueta una cadena de caracteres de datos opacos de longitud variable, similar a pack_string().

Packer.pack_bytes(bytes)

Empaqueta una secuencia de bytes de longitud variable, similar a pack_string().

Los siguientes métodos soportan el empaquetamiento de arreglos y listas:

Packer.pack_list(list, pack_item)

Empaqueta una lista de elementos homogéneos. Este método es útil para listas con longitud indeterminada; en otras palabras, el tamaño no está disponible hasta que se haya recorrido toda la lista. Para cada elemento de la lista, un entero sin signo 1 se empaqueta primero, seguido del valor de datos de la lista. pack_item es la función que se llama para empaquetar el elemento individual. Al final de la lista, se empaqueta un entero sin signo 0.

Por ejemplo, para empaquetar una lista de enteros, el código podría parecerse a esto:

import xdrlib
p = xdrlib.Packer()
p.pack_list([1, 2, 3], p.pack_int)

Packer.pack_farray(n, array, pack_item)

Empaqueta una lista (arreglo) de elementos homogéneos de longitud fija. n es la longitud de la lista; no es empaquetada en el búfer, pero una excepción ValueError es lanzada si len(array) no es igual a n. Al igual que en el método anterior, pack_item es la función usada para empaquetar cada elemento.

Packer.pack_array(list, pack_item)

Empaqueta una lista de elementos homogéneos de longitud variable. Primero, la longitud de la lista es empaquetada como un entero sin signo, luego cada elemento es empaquetado como en el método pack_farray() de arriba.

Instancias de la clase Unpacker

La clase Unpacker ofrece los siguientes métodos:

Unpacker.reset(data)

Restablece el búfer de cadena de caracteres a la data especificada.

Unpacker.get_position()

Retorna la posición actual desempaquetada en el búfer de datos.

Unpacker.set_position(position)

Establece la posición de desempaquetado del búfer de datos en la posición position. Debes tener cuidado al usar los métodos get_position() y set_position().

Unpacker.get_buffer()

Retorna el búfer de datos actual desempaquetado como una cadena de caracteres.

Unpacker.done()

Indica se ha completado el proceso de desempaquetado. Lanza una excepción Error si no se han desempaquetado todos los datos.

Además, cada tipo de datos que puede ser empaquetados con un Packer, puede ser desempaquetado con un Unpacker. Los métodos de desempaquetados son de la forma unpack_tipo(), y no tienen argumentos. Estos retornan el objeto desempaquetado.

Unpacker.unpack_float()

Desempaqueta un número de punto flotante de precisión simple.

Unpacker.unpack_double()

Desempaqueta un número de punto flotante de doble precisión, similar a unpack_float().

Adicionalmente, los siguientes métodos desempaquetan cadenas de caracteres, bytes y datos opacos:

Unpacker.unpack_fstring(n)

Desempaqueta y retorna una cadena de caracteres de longitud fija. n es el número de caracteres esperados. Se asume un relleno con bytes nulos hasta que la longitud de los datos sea un múltiplo de 4 bytes.

Unpacker.unpack_fopaque(n)

Desempaqueta y retorna un flujo de datos opaco de longitud fija, similar a unpack_fstring().

Unpacker.unpack_string()

Desempaqueta y retorna una cadena de caracteres de longitud variable. La longitud de la cadena de caracteres es desempaquetada primero como un entero sin signo, luego los datos de la cadena de caracteres son desempaquetados con el método unpack_fstring().

Unpacker.unpack_opaque()

Desempaqueta y retorna un flujo de datos opaco de longitud variable, similar a unpack_string().

Unpacker.unpack_bytes()

Desempaqueta y retorna una secuencia de bytes de longitud variable, similar a unpack_string().

Los siguientes métodos soportan el desempaquetado de arreglos y listas:

Unpacker.unpack_list(unpack_item)

Desempaqueta y retorna una lista de elementos homogéneos. La lista se desempaqueta un elemento a la vez desempaquetando primero un indicador entero sin signo. Si el flag es 1, el elemento se desempaqueta y se agrega a la lista. Un flag de 0 indica el final de la lista. unpack_item es la función a la que se invoca para desempaquetar los elementos.

Unpacker.unpack_farray(n, unpack_item)

Desempaqueta y retorna (como una lista) un arreglo de elementos homogéneos de longitud fija. n es el número de elementos de la lista que se esperan en el búfer. Como se mostró anteriormente, unpack_item es la función empleada para desempaquetar cada elemento.

Unpacker.unpack_array(unpack_item)

Desempaqueta y retorna una lista de elementos homogéneos de longitud variable. En primer lugar, la longitud de la lista se desempaqueta como un entero sin signo, luego cada elemento se desempaqueta como en el método unpack_farray() de arriba.

Excepciones

En este módulo, las excepciones se codifican como instancias de clase:

exception xdrlib.Error

La clase de excepción base. Error tiene un único atributo público, msg, que contiene la descripción del error.

exception xdrlib.ConversionError

Clase derivada de Error. No contiene variables de instancia adicionales.

A continuación se muestra un ejemplo de cómo detectarías una de estas excepciones:

import xdrlib
p = xdrlib.Packer()
try:
    p.pack_double(8.01)
except xdrlib.ConversionError as instance:
    print('packing the double failed:', instance.msg)

Security Considerations

The following modules have specific security considerations:

cgi: CGI security considerations

hashlib: all constructors take a «usedforsecurity» keyword-only argument disabling known insecure and blocked algorithms

http.server is not suitable for production use, only implementing basic security checks. See the security considerations.

logging: Logging configuration uses eval()

multiprocessing: Connection.recv() uses pickle

pickle: Restricting globals in pickle

random shouldn’t be used for security purposes, use secrets instead

shelve: shelve is based on pickle and thus unsuitable for dealing with untrusted sources

ssl: SSL/TLS security considerations

subprocess: Subprocess security considerations

tempfile: mktemp is deprecated due to vulnerability to race conditions

xml: XML vulnerabilities

zipfile: maliciously prepared .zip files can cause disk volume exhaustion

Ampliación e incrustación del intérprete de Python

Este documento describe cómo escribir módulos en C o C++ para extender el intérprete de Python con nuevos módulos. Esos módulos no solo pueden definir nuevas funciones sino también nuevos tipos de objetos y sus métodos. El documento también describe cómo incrustar el intérprete de Python en otra aplicación, para usarlo como un lenguaje de extensión. Finalmente, muestra cómo compilar y vincular módulos de extensión para que puedan cargarse dinámicamente (en tiempo de ejecución) en el intérprete, si el sistema operativo subyacente admite esta característica.

Este documento asume conocimientos básicos sobre Python. Para una introducción informal al lenguaje, consulte Tutorial de Python. Referencia del Lenguaje Python da una definición más formal del lenguaje. La Biblioteca Estándar de Python documenta los tipos de objetos, funciones y módulos existentes (tanto incorporados como escritos en Python) que le dan al lenguaje su amplio rango de aplicaciones.

Para obtener una descripción detallada de toda la API de Python/C, consulte el apartado separado Manual de referencia de la API en C de Python.

Herramientas de terceros recomendadas

Esta guía solo cubre las herramientas básicas para crear extensiones proporcionadas como parte de esta versión de CPython. Herramientas de terceros como Cython [http://cython.org/], cffi [https://cffi.readthedocs.io], SWIG [http://www.swig.org] y Numba [https://numba.pydata.org/] ofrecen enfoques más simples y sofisticados para crear extensiones C y C++ para Python.

Ver también

Guía del Usuario de Empaquetamiento de Python: Extensiones binarias [https://packaging.python.org/guides/packaging-binary-extensions/]

La Guía del Usuario de Empaquetamiento de Python no solo cubre varias herramientas disponibles que simplifican la creación de extensiones binarias, sino que también discute las diversas razones por las cuales crear un módulo de extensión puede ser deseable en primer lugar.

Crear extensiones sin herramientas de terceros

Esta sección de la guía cubre la creación de extensiones C y C++ sin la ayuda de herramientas de terceros. Está destinado principalmente a los creadores de esas herramientas, en lugar de ser una forma recomendada de crear sus propias extensiones C.

1. Extendiendo Python con C o C++

1.1. Un ejemplo simple

1.2. Intermezzo: errores y excepciones

1.3. De vuelta al ejemplo

1.4. La tabla de métodos del módulo y la función de inicialización

1.5. Compilación y Enlazamiento

1.6. Llamando funciones Python desde C

1.7. Extracción de parámetros en funciones de extensión

1.8. Parámetros de palabras clave para funciones de extensión

1.9. Construyendo Valores Arbitrarios

1.10. Conteo de Referencias

1.11. Escribiendo Extensiones en C++

1.12. Proporcionar una API C para un módulo de extensión

2. Definición de tipos de extensión: Tutorial

2.1. Lo Básico

2.2. Agregar datos y métodos al ejemplo básico

2.3. Proporcionar un control más preciso sobre los atributos de datos

2.4. Apoyo a la recolección de basura cíclica

2.5. Subclases de otros tipos

3. Definición de tipos de extensión: temas variados

3.1. Finalización y desasignación

3.2. Presentación de Objetos

3.3. Gestión de atributos

3.4. Comparación de Objetos

3.5. Soporte de protocolo abstracto

3.6. Soporte de referencia débil

3.7. Más Sugerencias

4. Construyendo Extensiones C y C++

4.1. Construyendo Extensiones C y C++ con distutils

4.2. Distribuyendo sus módulos de extensión

5. Creación de extensiones C y C++ en Windows

5.1. Un enfoque de libro de cocina

5.2. Diferencias entre Unix y Windows

5.3. Usar DLL en la práctica

Incrustar el tiempo de ejecución de CPython en una aplicación más grande

A veces, en lugar de crear una extensión que se ejecute dentro del intérprete de Python como la aplicación principal, es conveniente incorporar el tiempo de ejecución de CPython dentro de una aplicación más grande. Esta sección cubre algunos de los detalles involucrados en hacerlo con éxito.

1. Incrustando Python en Otra Aplicación

1.1. Incrustación de muy alto nivel

1.2. Más allá de la incrustación de muy alto nivel: una visión general

1.3. Incrustación pura

1.4. Extendiendo Python Incrustado

1.5. Incrustando Python en C++

1.6. Compilar y enlazar bajo sistemas tipo Unix

1. Extendiendo Python con C o C++

Es muy fácil agregar nuevos módulos incorporados a Python, si sabe cómo programar en C. Tales como módulos de extensión pueden hacer dos cosas que no se pueden hacer directamente en Python: pueden implementar nuevos tipos objetos incorporados, y pueden llamar a funciones de biblioteca C y llamadas de sistema.

Para admitir extensiones, la API de Python (interfaz de programadores de aplicaciones) define un conjunto de funciones, macros y variables que proporcionan acceso a la mayoría de los aspectos del sistema de tiempo de ejecución de Python. La API de Python se incorpora en un archivo fuente C incluyendo el encabezado "Python.h".

La compilación de un módulo de extensión depende de su uso previsto, así como de la configuración de su sistema; los detalles se dan en capítulos posteriores.

Nota

La interfaz de extensión C es específica de CPython, y los módulos de extensión no funcionan en otras implementaciones de Python. En muchos casos, es posible evitar escribir extensiones C y preservar la portabilidad a otras implementaciones. Por ejemplo, si su caso de uso es llamar a funciones de biblioteca C o llamadas de sistema, debería considerar usar el módulo ctypes o la biblioteca cffi [https://cffi.readthedocs.io/] en lugar de escribir código personalizado C. Estos módulos le permiten escribir código Python para interactuar con el código C y son más portátiles entre las implementaciones de Python que escribir y compilar un módulo de extensión C.

1.1. Un ejemplo simple

Creemos un módulo de extensión llamado spam (la comida favorita de los fanáticos de Monty Python …) y digamos que queremos crear una interfaz de Python para la función de biblioteca C system() 1 . Esta función toma una cadena de caracteres con terminación nula como argumento y retorna un entero. Queremos que esta función se pueda llamar desde Python de la siguiente manera:

>>> import spam
>>> status = spam.system("ls -l")

Comience creando un archivo spammodule.c. (Históricamente, si un módulo se llama spam, el archivo C que contiene su implementación se llama spammodule.c; si el nombre del módulo es muy largo, como spammify, el nombre del módulo puede sea solo spammify.c.)

Las dos primeras líneas de nuestro archivo pueden ser:

#define PY_SSIZE_T_CLEAN
#include <Python.h>

que extrae la API de Python (puede agregar un comentario que describa el propósito del módulo y un aviso de copyright si lo desea).

Nota

Dado que Python puede definir algunas definiciones de preprocesador que afectan los encabezados estándar en algunos sistemas, debe incluir Python.h antes de incluir encabezados estándar.

Se recomienda definir siempre PY_SSIZE_T_CLEAN antes de incluir Python.h. Consulte Extracción de parámetros en funciones de extensión para obtener una descripción de esta macro.

Todos los símbolos visibles para el usuario definidos por Python.h tienen un prefijo Py o PY, excepto los definidos en los archivos de encabezado estándar. Por conveniencia, y dado que el intérprete de Python los usa ampliamente, "Python.h" incluye algunos archivos de encabezado estándar: <stdio.h>, <string.h>, <errno.h>, y <stdlib.h>. Si el último archivo de encabezado no existe en su sistema, declara las funciones malloc(), free() y realloc() directamente.

Lo siguiente que agregamos a nuestro archivo de módulo es la función C que se llamará cuando se evalúe la expresión Python spam.system(string) (veremos en breve cómo termina siendo llamado):

static PyObject *
spam_system(PyObject *self, PyObject *args)
{
    const char *command;
    int sts;

    if (!PyArg_ParseTuple(args, "s", &command))
        return NULL;
    sts = system(command);
    return PyLong_FromLong(sts);
}

Hay una traducción directa de la lista de argumentos en Python (por ejemplo, la única expresión "ls -l") a los argumentos pasados a la función C. La función C siempre tiene dos argumentos, llamados convencionalmente self y args.

El argumento self apunta al objeto del módulo para funciones a nivel de módulo; para un método apuntaría a la instancia del objeto.

El argumento args será un puntero a un objeto de tupla de Python que contiene los argumentos. Cada elemento de la tupla corresponde a un argumento en la lista de argumentos de la llamada. Los argumentos son objetos de Python — para hacer algo con ellos en nuestra función C tenemos que convertirlos a valores C. La función PyArg_ParseTuple() en la API de Python verifica los tipos de argumento y los convierte a valores C. Utiliza una cadena de plantilla para determinar los tipos requeridos de los argumentos, así como los tipos de las variables C en las que almacenar los valores convertidos. Más sobre esto más tarde.

PyArg_ParseTuple() retorna verdadero (distinto de cero) si todos los argumentos tienen el tipo correcto y sus componentes se han almacenado en las variables cuyas direcciones se pasan. Retorna falso (cero) si se pasó una lista de argumentos no válidos. En el último caso, también genera una excepción apropiada para que la función de llamada pueda retornar NULL inmediatamente (como vimos en el ejemplo).

1.2. Intermezzo: errores y excepciones

An important convention throughout the Python interpreter is the following: when a function fails, it should set an exception condition and return an error value (usually -1 or a NULL pointer). Exception information is stored in three members of the interpreter’s thread state. These are NULL if there is no exception. Otherwise they are the C equivalents of the members of the Python tuple returned by sys.exc_info(). These are the exception type, exception instance, and a traceback object. It is important to know about them to understand how errors are passed around.

La API de Python define una serie de funciones para establecer varios tipos de excepciones.

El más común es PyErr_SetString(). Sus argumentos son un objeto de excepción y una cadena C. El objeto de excepción suele ser un objeto predefinido como PyExc_ZeroDivisionError. La cadena C indica la causa del error y se convierte en un objeto de cadena Python y se almacena como el «valor asociado» de la excepción.

Otra función útil es PyErr_SetFromErrno(), que solo toma un argumento de excepción y construye el valor asociado mediante la inspección de la variable global errno. La función más general es PyErr_SetObject(), que toma dos argumentos de objeto, la excepción y su valor asociado. No necesita Py_INCREF() los objetos pasados a cualquiera de estas funciones.

Puede probar de forma no destructiva si se ha establecido una excepción con PyErr_Occurred(). Esto retorna el objeto de excepción actual o NULL si no se ha producido ninguna excepción. Normalmente no necesita llamar a PyErr_Occurred() para ver si se produjo un error en una llamada a la función, ya que debería poder distinguir el valor de retorno.

Cuando una función f que llama a otra función g detecta que la última falla, f debería retornar un valor de error (generalmente NULL o -1). Debería no llamar a una de las funciones PyErr_*() — una ya ha sido llamada por g. Se supone que la persona que llama f también debe retornar una indicación de error a su persona que llama, de nuevo sin llamar PyErr_*(), y así sucesivamente — la causa más detallada del error ya fue informado por la función que lo detectó por primera vez. Una vez que el error llega al bucle principal del intérprete de Python, esto anula el código de Python que se está ejecutando actualmente e intenta encontrar un controlador de excepción especificado por el programador de Python.

(Hay situaciones en las que un módulo puede dar un mensaje de error más detallado llamando a otra función PyErr_*(), y en tales casos está bien hacerlo. Como regla general, sin embargo, esto es no es necesario y puede causar que se pierda información sobre la causa del error: la mayoría de las operaciones pueden fallar por varias razones.)

Para ignorar una excepción establecida por una llamada de función que falló, la condición de excepción debe borrarse explícitamente llamando a PyErr_Clear(). La única vez que el código C debe llamar PyErr_Clear() es si no quiere pasar el error al intérprete pero quiere manejarlo completamente por sí mismo (posiblemente probando algo más o pretendiendo que nada salió mal) )

Cada llamada fallida a malloc() debe convertirse en una excepción — la persona que llama directamente de malloc() (o realloc()) debe llamar PyErr_NoMemory() y retorna un indicador de falla en sí mismo. Todas las funciones de creación de objetos (por ejemplo, PyLong_FromLong()) ya hacen esto, por lo que esta nota solo es relevante para aquellos que llaman malloc() directamente.

También tenga en cuenta que, con la importante excepción de PyArg_ParseTuple() y sus amigos, las funciones que retornan un estado entero generalmente retornan un valor positivo o cero para el éxito y -1 para el fracaso, como las llamadas al sistema Unix.

Finalmente, tenga cuidado de limpiar la basura (haciendo Py_XDECREF() o Py_DECREF() requiere objetos que ya ha creado) cuando retorna un indicador de error!

La elección de qué excepción lanzar es totalmente suya. Hay objetos C declarados previamente que corresponden a todas las excepciones de Python incorporadas, como PyExc_ZeroDivisionError, que puede usar directamente. Por supuesto, debe elegir sabiamente las excepciones — no use PyExc_TypeError para significar que no se puede abrir un archivo (probablemente debería ser PyExc_IOError). Si algo anda mal con la lista de argumentos, la función PyArg_ParseTuple() generalmente genera PyExc_TypeError. Si tiene un argumento cuyo valor debe estar en un rango particular o debe satisfacer otras condiciones, PyExc_ValueError es apropiado.

También puede definir una nueva excepción que sea exclusiva de su módulo. Para esto, generalmente declara una variable de objeto estático al comienzo de su archivo:

static PyObject *SpamError;

y lo inicializa en la función de inicialización de su módulo (PyInit_spam()) con un objeto de excepción:

PyMODINIT_FUNC
PyInit_spam(void)
{
    PyObject *m;

    m = PyModule_Create(&spammodule);
    if (m == NULL)
        return NULL;

    SpamError = PyErr_NewException("spam.error", NULL, NULL);
    Py_XINCREF(SpamError);
    if (PyModule_AddObject(m, "error", SpamError) < 0) {
        Py_XDECREF(SpamError);
        Py_CLEAR(SpamError);
        Py_DECREF(m);
        return NULL;
    }

    return m;
}

Tenga en cuenta que el nombre de Python para el objeto de excepción es spam.error. La función PyErr_NewException() puede crear una clase con la clase base siendo Exception (a menos que se pase otra clase en lugar de NULL), descrita en Excepciones incorporadas.

Tenga en cuenta también que la variable SpamError retiene una referencia a la clase de excepción recién creada; esto es intencional! Como la excepción podría eliminarse del módulo mediante un código externo, se necesita una referencia propia de la clase para garantizar que no se descarte, lo que hace que SpamError se convierta en un puntero colgante. Si se convierte en un puntero colgante, el código C que genera la excepción podría causar un volcado del núcleo u otros efectos secundarios no deseados.

Discutimos el uso de PyMODINIT_FUNC como un tipo de retorno de función más adelante en esta muestra.

La excepción spam.error se puede generar en su módulo de extensión mediante una llamada a PyErr_SetString() como se muestra a continuación:

static PyObject *
spam_system(PyObject *self, PyObject *args)
{
    const char *command;
    int sts;

    if (!PyArg_ParseTuple(args, "s", &command))
        return NULL;
    sts = system(command);
    if (sts < 0) {
        PyErr_SetString(SpamError, "System command failed");
        return NULL;
    }
    return PyLong_FromLong(sts);
}

1.3. De vuelta al ejemplo

Volviendo a nuestra función de ejemplo, ahora debería poder comprender esta declaración:

if (!PyArg_ParseTuple(args, "s", &command))
    return NULL;

Retorna NULL (el indicador de error para las funciones que retornan punteros de objeto) si se detecta un error en la lista de argumentos, basándose en la excepción establecida por PyArg_ParseTuple(). De lo contrario, el valor de cadena del argumento se ha copiado en la variable local command. Esta es una asignación de puntero y no se supone que modifique la cadena a la que apunta (por lo tanto, en el Estándar C, la variable command debería declararse correctamente como const char * command).

La siguiente declaración es una llamada a la función Unix system(), pasándole la cadena que acabamos de obtener de PyArg_ParseTuple():

sts = system(command);

Nuestra función spam.system() debe retornar el valor de sts como un objeto Python. Esto se hace usando la función PyLong_FromLong().

return PyLong_FromLong(sts);

En este caso, retornará un objeto entero. (Sí, ¡incluso los enteros son objetos en el montículo (heap) en Python!)

Si tiene una función C que no retorna ningún argumento útil (una función que retorna void), la función Python correspondiente debe retornar None. Necesita este modismo para hacerlo (que se implementa mediante la macro Py_RETURN_NONE):

Py_INCREF(Py_None);
return Py_None;

Py_None es el nombre C para el objeto especial de Python None. Es un objeto genuino de Python en lugar de un puntero NULL, que significa «error» en la mayoría de los contextos, como hemos visto.

1.4. La tabla de métodos del módulo y la función de inicialización

Prometí mostrar cómo spam_system() se llama desde los programas de Python. Primero, necesitamos enumerar su nombre y dirección en una «tabla de métodos»:

static PyMethodDef SpamMethods[] = {
    ...
    {"system",  spam_system, METH_VARARGS,
     "Execute a shell command."},
    ...
    {NULL, NULL, 0, NULL}        /* Sentinel */
};

Tenga en cuenta la tercera entrada (METH_VARARGS). Esta es una bandera que le dice al intérprete la convención de llamada que se utilizará para la función C. Normalmente debería ser siempre METH_VARARGS o METH_VARARGS | METH_KEYWORDS; un valor de 0 significa que se usa una variante obsoleta de PyArg_ParseTuple().

Cuando se usa solo METH_VARARGS, la función debe esperar que los parámetros a nivel de Python se pasen como una tupla aceptable para el análisis mediante PyArg_ParseTuple(); A continuación se proporciona más información sobre esta función.

El bit METH_KEYWORDS se puede establecer en el tercer campo si se deben pasar argumentos de palabras clave a la función. En este caso, la función C debería aceptar un tercer parámetro PyObject * que será un diccionario de palabras clave. Use PyArg_ParseTupleAndKeywords() para analizar los argumentos de dicha función.

La tabla de métodos debe ser referenciada en la estructura de definición del módulo:

static struct PyModuleDef spammodule = {
    PyModuleDef_HEAD_INIT,
    "spam",   /* name of module */
    spam_doc, /* module documentation, may be NULL */
    -1,       /* size of per-interpreter state of the module,
                 or -1 if the module keeps state in global variables. */
    SpamMethods
};

Esta estructura, a su vez, debe pasarse al intérprete en la función de inicialización del módulo. La función de inicialización debe llamarse PyInit_name(), donde name es el nombre del módulo y debe ser el único elemento no static definido en el archivo del módulo:

PyMODINIT_FUNC
PyInit_spam(void)
{
    return PyModule_Create(&spammodule);
}

Tenga en cuenta que PyMODINIT_FUNC declara la función como PyObject * tipo de retorno, declara cualquier declaración de vinculación especial requerida por la plataforma, y para C++ declara la función como extern "C".

Cuando el programa Python importa el módulo spam por primera vez, se llama PyInit_spam(). (Consulte a continuación los comentarios sobre la incorporación de Python). Llama a PyModule_Create(), que retorna un objeto de módulo e inserta objetos de función incorporados en el módulo recién creado en función de la tabla (un arreglo de estructuras PyMethodDef) encontradas en la definición del módulo. PyModule_Create() retorna un puntero al objeto del módulo que crea. Puede abortar con un error fatal para ciertos errores, o retornar NULL si el módulo no se pudo inicializar satisfactoriamente. La función init debe retornar el objeto del módulo a su llamador, para que luego se inserte en sys.modules.

Al incrustar Python, la función PyInit_spam() no se llama automáticamente a menos que haya una entrada en la tabla PyImport_Inittab. Para agregar el módulo a la tabla de inicialización, use PyImport_AppendInittab(), seguido opcionalmente por una importación del módulo:

int
main(int argc, char *argv[])
{
    wchar_t *program = Py_DecodeLocale(argv[0], NULL);
    if (program == NULL) {
        fprintf(stderr, "Fatal error: cannot decode argv[0]\n");
        exit(1);
    }

    /* Add a built-in module, before Py_Initialize */
    if (PyImport_AppendInittab("spam", PyInit_spam) == -1) {
        fprintf(stderr, "Error: could not extend in-built modules table\n");
        exit(1);
    }

    /* Pass argv[0] to the Python interpreter */
    Py_SetProgramName(program);

    /* Initialize the Python interpreter.  Required.
       If this step fails, it will be a fatal error. */
    Py_Initialize();

    /* Optionally import the module; alternatively,
       import can be deferred until the embedded script
       imports it. */
    PyObject *pmodule = PyImport_ImportModule("spam");
    if (!pmodule) {
        PyErr_Print();
        fprintf(stderr, "Error: could not import module 'spam'\n");
    }

    ...

    PyMem_RawFree(program);
    return 0;
}

Nota

Eliminar entradas de sys.modules o importar módulos compilados en múltiples intérpretes dentro de un proceso (o seguir un fork() sin una intervención exec()) puede crear problemas para algunas extensiones de módulos. Los autores de módulos de extensiones deben tener precaución al inicializar estructuras de datos internas.

Se incluye un módulo de ejemplo más sustancial en la distribución fuente de Python como Modules/xxmodule.c. Este archivo puede usarse como plantilla o simplemente leerse como ejemplo.

Nota

A diferencia de nuestro ejemplo de spam, xxmodule usa inicialización de múltiples fases (nuevo en Python 3.5), donde se retorna una estructura PyModuleDef de PyInit_spam, y la creación del módulo se deja al maquinaria de importación. Para obtener detalles sobre la inicialización múltiples fases, consulte PEP 489 [https://www.python.org/dev/peps/pep-0489].

1.5. Compilación y Enlazamiento

Hay dos cosas más que hacer antes de que pueda usar su nueva extensión: compilarla y vincularla con el sistema Python. Si usa carga dinámica, los detalles pueden depender del estilo de carga dinámica que usa su sistema; Para obtener más información al respecto, consulte los capítulos sobre la creación de módulos de extensión (capítulo Construyendo Extensiones C y C++) e información adicional que se refiere solo a la construcción en Windows (capítulo Creación de extensiones C y C++ en Windows).

Si no puede utilizar la carga dinámica, o si desea que su módulo sea una parte permanente del intérprete de Python, tendrá que cambiar la configuración (setup) y reconstruir el intérprete. Afortunadamente, esto es muy simple en Unix: simplemente coloque su archivo (spammodule.c por ejemplo) en el directorio Modules/ ` de una distribución fuente desempaquetada, agregue una línea al archivo :file:`Modules/Setup.local que describe su archivo:

spam spammodule.o

y reconstruya el intérprete ejecutando make en el directorio de nivel superior. También puede ejecutar make en el subdirectorio Modules/, pero primero debe reconstruir Makefile ejecutando “make Makefile”. (Esto es necesario cada vez que cambia el archivo Configuración).

Si su módulo requiere bibliotecas adicionales para vincular, también se pueden enumerar en la línea del archivo de configuración, por ejemplo:

spam spammodule.o -lX11

1.6. Llamando funciones Python desde C

Hasta ahora nos hemos concentrado en hacer que las funciones de C puedan llamarse desde Python. Lo contrario también es útil: llamar a las funciones de Python desde C. Este es especialmente el caso de las bibliotecas que admiten las llamadas funciones de «retrollamada». Si una interfaz C utiliza retrollamadas, el Python equivalente a menudo necesita proporcionar un mecanismo de retrollamada al programador de Python; la implementación requerirá llamar a las funciones de retrollamada de Python desde una retrollamada en C. Otros usos también son imaginables.

Afortunadamente, el intérprete de Python se llama fácilmente de forma recursiva, y hay una interfaz estándar para llamar a una función de Python. (No me detendré en cómo llamar al analizador Python con una cadena particular como entrada — si está interesado, eche un vistazo a la implementación de la opción de línea de comando -c en Modules/main.c del código fuente de Python.)

Llamar a una función de Python es fácil. Primero, el programa Python debe de alguna manera pasar el objeto de función Python. Debe proporcionar una función (o alguna otra interfaz) para hacer esto. Cuando se llama a esta función, guarde un puntero en el objeto de la función Python (tenga cuidado de usar Py_INCREF()) En una variable global — o donde mejor le parezca. Por ejemplo, la siguiente función podría ser parte de una definición de módulo:

static PyObject *my_callback = NULL;

static PyObject *
my_set_callback(PyObject *dummy, PyObject *args)
{
    PyObject *result = NULL;
    PyObject *temp;

    if (PyArg_ParseTuple(args, "O:set_callback", &temp)) {
        if (!PyCallable_Check(temp)) {
            PyErr_SetString(PyExc_TypeError, "parameter must be callable");
            return NULL;
        }
        Py_XINCREF(temp);         /* Add a reference to new callback */
        Py_XDECREF(my_callback);  /* Dispose of previous callback */
        my_callback = temp;       /* Remember new callback */
        /* Boilerplate to return "None" */
        Py_INCREF(Py_None);
        result = Py_None;
    }
    return result;
}

Esta función debe registrarse con el intérprete utilizando el indicador METH_VARARGS; esto se describe en la sección La tabla de métodos del módulo y la función de inicialización. La función PyArg_ParseTuple() y sus argumentos están documentados en la sección Extracción de parámetros en funciones de extensión.

Las macros Py_XINCREF() y Py_XDECREF() incrementan/disminuyen el recuento de referencia de un objeto y son seguros en presencia de punteros NULL (pero tenga en cuenta que temp no lo hará ser NULL en este contexto). Más información sobre ellos en la sección Conteo de Referencias.

Más tarde, cuando es hora de llamar a la función, llama a la función C PyObject_CallObject(). Esta función tiene dos argumentos, ambos punteros a objetos arbitrarios de Python: la función Python y la lista de argumentos. La lista de argumentos siempre debe ser un objeto de tupla, cuya longitud es el número de argumentos. Para llamar a la función Python sin argumentos, pase NULL o una tupla vacía; para llamarlo con un argumento, pasa una tupla singleton. Py_BuildValue() retorna una tupla cuando su cadena de formato consta de cero o más códigos de formato entre paréntesis. Por ejemplo:

int arg;
PyObject *arglist;
PyObject *result;
...
arg = 123;
...
/* Time to call the callback */
arglist = Py_BuildValue("(i)", arg);
result = PyObject_CallObject(my_callback, arglist);
Py_DECREF(arglist);

PyObject_CallObject() retorna un puntero de objeto Python: este es el valor de retorno de la función Python. PyObject_CallObject() es «recuento-referencia-neutral» con respecto a sus argumentos. En el ejemplo, se creó una nueva tupla para servir como lista de argumentos, a la cual se le llama Py_DECREF() inmediatamente después de la llamada PyObject_CallObject().

El valor de retorno de PyObject_CallObject() es «nuevo»: o bien es un objeto nuevo o es un objeto existente cuyo recuento de referencias se ha incrementado. Por lo tanto, a menos que desee guardarlo en una variable global, debería de alguna manera Py_DECREF() el resultado, incluso (¡especialmente!) Si no está interesado en su valor.

Sin embargo, antes de hacer esto, es importante verificar que el valor de retorno no sea NULL. Si es así, la función de Python terminó generando una excepción. Si el código C que llamó PyObject_CallObject() se llama desde Python, ahora debería retornar una indicación de error a su llamador de Python, para que el intérprete pueda imprimir un seguimiento de la pila, o el código de Python que llama puede manejar la excepción. Si esto no es posible o deseable, la excepción se debe eliminar llamando a PyErr_Clear(). Por ejemplo:

if (result == NULL)
    return NULL; /* Pass error back */
...use result...
Py_DECREF(result);

Dependiendo de la interfaz deseada para la función de retrollamada de Python, es posible que también deba proporcionar una lista de argumentos para PyObject_CallObject(). En algunos casos, el programa Python también proporciona la lista de argumentos, a través de la misma interfaz que especificó la función de retrollamada. Luego se puede guardar y usar de la misma manera que el objeto de función. En otros casos, puede que tenga que construir una nueva tupla para pasarla como lista de argumentos. La forma más sencilla de hacer esto es llamar a Py_BuildValue(). Por ejemplo, si desea pasar un código de evento integral, puede usar el siguiente código:

PyObject *arglist;
...
arglist = Py_BuildValue("(l)", eventcode);
result = PyObject_CallObject(my_callback, arglist);
Py_DECREF(arglist);
if (result == NULL)
    return NULL; /* Pass error back */
/* Here maybe use the result */
Py_DECREF(result);

¡Observe la ubicación de Py_DECREF(arglist) inmediatamente después de la llamada, antes de la verificación de errores! También tenga en cuenta que, estrictamente hablando, este código no está completo: Py_BuildValue() puede quedarse sin memoria, y esto debe verificarse.

También puede llamar a una función con argumentos de palabras clave utilizando PyObject_Call(), que admite argumentos y argumentos de palabras clave. Como en el ejemplo anterior, usamos Py_BuildValue() para construir el diccionario.

PyObject *dict;
...
dict = Py_BuildValue("{s:i}", "name", val);
result = PyObject_Call(my_callback, NULL, dict);
Py_DECREF(dict);
if (result == NULL)
    return NULL; /* Pass error back */
/* Here maybe use the result */
Py_DECREF(result);

1.7. Extracción de parámetros en funciones de extensión

La función PyArg_ParseTuple() se declara de la siguiente manera:

int PyArg_ParseTuple(PyObject *arg, const char *format, ...);

El argumento arg debe ser un objeto de tupla que contenga una lista de argumentos pasada de Python a una función C. El argumento format debe ser una cadena de formato, cuya sintaxis se explica en Analizando argumentos y construyendo valores en el Manual de referencia de la API de Python/C. Los argumentos restantes deben ser direcciones de variables cuyo tipo está determinado por la cadena de formato.

Tenga en cuenta que si bien PyArg_ParseTuple() verifica que los argumentos de Python tengan los tipos requeridos, no puede verificar la validez de las direcciones de las variables C pasadas a la llamada: si comete errores allí, su código probablemente se bloqueará o al menos sobrescribir bits aleatorios en la memoria. ¡Así que ten cuidado!

Tenga en cuenta que las referencias de objetos de Python que se proporcionan a quien llama son referencias prestadas (borrowed); ¡no disminuya su recuento de referencias!

Algunas llamadas de ejemplo:

#define PY_SSIZE_T_CLEAN  /* Make "s#" use Py_ssize_t rather than int. */
#include <Python.h>

int ok;
int i, j;
long k, l;
const char *s;
Py_ssize_t size;

ok = PyArg_ParseTuple(args, ""); /* No arguments */
    /* Python call: f() */

ok = PyArg_ParseTuple(args, "s", &s); /* A string */
    /* Possible Python call: f('whoops!') */

ok = PyArg_ParseTuple(args, "lls", &k, &l, &s); /* Two longs and a string */
    /* Possible Python call: f(1, 2, 'three') */

ok = PyArg_ParseTuple(args, "(ii)s#", &i, &j, &s, &size);
    /* A pair of ints and a string, whose size is also returned */
    /* Possible Python call: f((1, 2), 'three') */

{
    const char *file;
    const char *mode = "r";
    int bufsize = 0;
    ok = PyArg_ParseTuple(args, "s|si", &file, &mode, &bufsize);
    /* A string, and optionally another string and an integer */
    /* Possible Python calls:
       f('spam')
       f('spam', 'w')
       f('spam', 'wb', 100000) */
}

{
    int left, top, right, bottom, h, v;
    ok = PyArg_ParseTuple(args, "((ii)(ii))(ii)",
             &left, &top, &right, &bottom, &h, &v);
    /* A rectangle and a point */
    /* Possible Python call:
       f(((0, 0), (400, 300)), (10, 10)) */
}

{
    Py_complex c;
    ok = PyArg_ParseTuple(args, "D:myfunction", &c);
    /* a complex, also providing a function name for errors */
    /* Possible Python call: myfunction(1+2j) */
}

1.8. Parámetros de palabras clave para funciones de extensión

La función PyArg_ParseTupleAndKeywords() se declara de la siguiente manera:

int PyArg_ParseTupleAndKeywords(PyObject *arg, PyObject *kwdict,
                                const char *format, char *kwlist[], ...);

Los parámetros arg y format son idénticos a los de la función PyArg_ParseTuple(). El parámetro kwdict es el diccionario de palabras clave recibidas como tercer parámetro del tiempo de ejecución de Python. El parámetro kwlist es una lista de cadenas terminadas en NULL que identifican los parámetros; los nombres se corresponden con la información de tipo de format de izquierda a derecha. En caso de éxito, PyArg_ParseTupleAndKeywords() retorna verdadero; de lo contrario, retorna falso y genera una excepción apropiada.

Nota

¡Las tuplas anidadas no se pueden analizar al usar argumentos de palabras clave! Los parámetros de palabras clave pasados que no están presentes en la kwlist provocarán que se genere TypeError.

Aquí hay un módulo de ejemplo que usa palabras clave, basado en un ejemplo de Geoff Philbrick (philbrick@hks.com):

#define PY_SSIZE_T_CLEAN  /* Make "s#" use Py_ssize_t rather than int. */
#include <Python.h>

static PyObject *
keywdarg_parrot(PyObject *self, PyObject *args, PyObject *keywds)
{
    int voltage;
    const char *state = "a stiff";
    const char *action = "voom";
    const char *type = "Norwegian Blue";

    static char *kwlist[] = {"voltage", "state", "action", "type", NULL};

    if (!PyArg_ParseTupleAndKeywords(args, keywds, "i|sss", kwlist,
                                     &voltage, &state, &action, &type))
        return NULL;

    printf("-- This parrot wouldn't %s if you put %i Volts through it.\n",
           action, voltage);
    printf("-- Lovely plumage, the %s -- It's %s!\n", type, state);

    Py_RETURN_NONE;
}

static PyMethodDef keywdarg_methods[] = {
    /* The cast of the function is necessary since PyCFunction values
     * only take two PyObject* parameters, and keywdarg_parrot() takes
     * three.
     */
    {"parrot", (PyCFunction)(void(*)(void))keywdarg_parrot, METH_VARARGS | METH_KEYWORDS,
     "Print a lovely skit to standard output."},
    {NULL, NULL, 0, NULL}   /* sentinel */
};

static struct PyModuleDef keywdargmodule = {
    PyModuleDef_HEAD_INIT,
    "keywdarg",
    NULL,
    -1,
    keywdarg_methods
};

PyMODINIT_FUNC
PyInit_keywdarg(void)
{
    return PyModule_Create(&keywdargmodule);
}

1.9. Construyendo Valores Arbitrarios

Esta función es la contraparte de PyArg_ParseTuple(). Se declara de la siguiente manera:

PyObject *Py_BuildValue(const char *format, ...);

Reconoce un conjunto de unidades de formato similares a las reconocidas por PyArg_ParseTuple(), pero los argumentos (que son de entrada a la función, no de salida) no deben ser punteros, solo valores. Retorna un nuevo objeto Python, adecuado para regresar de una función C llamada desde Python.

Una diferencia con PyArg_ParseTuple(): mientras que este último requiere que su primer argumento sea una tupla (ya que las listas de argumentos de Python siempre se representan como tuplas internamente), Py_BuildValue() no siempre construye una tupla . Construye una tupla solo si su cadena de formato contiene dos o más unidades de formato. Si la cadena de formato está vacía, retorna None; si contiene exactamente una unidad de formato, retorna el objeto que describa esa unidad de formato. Para forzarlo a retornar una tupla de tamaño 0 o uno, agregar paréntesis a la cadena de formato.

Ejemplos (a la izquierda la llamada, a la derecha el valor de Python resultante):

Py_BuildValue("")                        None
Py_BuildValue("i", 123)                  123
Py_BuildValue("iii", 123, 456, 789)      (123, 456, 789)
Py_BuildValue("s", "hello")              'hello'
Py_BuildValue("y", "hello")              b'hello'
Py_BuildValue("ss", "hello", "world")    ('hello', 'world')
Py_BuildValue("s#", "hello", 4)          'hell'
Py_BuildValue("y#", "hello", 4)          b'hell'
Py_BuildValue("()")                      ()
Py_BuildValue("(i)", 123)                (123,)
Py_BuildValue("(ii)", 123, 456)          (123, 456)
Py_BuildValue("(i,i)", 123, 456)         (123, 456)
Py_BuildValue("[i,i]", 123, 456)         [123, 456]
Py_BuildValue("{s:i,s:i}",
              "abc", 123, "def", 456)    {'abc': 123, 'def': 456}
Py_BuildValue("((ii)(ii)) (ii)",
              1, 2, 3, 4, 5, 6)          (((1, 2), (3, 4)), (5, 6))

1.10. Conteo de Referencias

En lenguajes como C o C++, el programador es responsable de la asignación dinámica y la desasignación de memoria en el montón. En C, esto se hace usando las funciones malloc() y free(). En C++, los operadores new y delete se usan esencialmente con el mismo significado y restringiremos la siguiente discusión al caso C.

Cada bloque de memoria asignado con malloc() eventualmente debería ser retorna al grupo de memoria disponible exactamente por una llamada a free(). Es importante llamar a free() en el momento adecuado. Si se olvida la dirección de un bloque pero free() no se solicita, la memoria que ocupa no se puede reutilizar hasta que finalice el programa. Esto se llama fuga de memoria. Por otro lado, si un programa llama free() para un bloque y luego continúa usando el bloque, crea un conflicto con la reutilización del bloque a través de otra llamada a malloc(). Esto se llama usando memoria liberada. Tiene las mismas malas consecuencias que hacer referencia a datos no inicializados: volcados de núcleos, resultados incorrectos, bloqueos misteriosos.

Las causas comunes de pérdidas de memoria son rutas inusuales a través del código. Por ejemplo, una función puede asignar un bloque de memoria, hacer algunos cálculos y luego liberar el bloque nuevamente. Ahora, un cambio en los requisitos de la función puede agregar una prueba al cálculo que detecta una condición de error y puede regresar prematuramente de la función. Es fácil olvidar liberar el bloque de memoria asignado al tomar esta salida prematura, especialmente cuando se agrega más tarde al código. Tales filtraciones, una vez introducidas, a menudo pasan desapercibidas durante mucho tiempo: la salida del error se toma solo en una pequeña fracción de todas las llamadas, y la mayoría de las máquinas modernas tienen mucha memoria virtual, por lo que la filtración solo se hace evidente en un proceso de larga ejecución que usa la función de fugas con frecuencia. Por lo tanto, es importante evitar que se produzcan fugas mediante una convención o estrategia de codificación que minimice este tipo de errores.

Dado que Python hace un uso intensivo de malloc() y free(), necesita una estrategia para evitar pérdidas de memoria, así como el uso de memoria liberada. El método elegido se llama recuento de referencias. El principio es simple: cada objeto contiene un contador, que se incrementa cuando se almacena una referencia al objeto en algún lugar, y que se reduce cuando se elimina una referencia al mismo. Cuando el contador llega a cero, la última referencia al objeto se ha eliminado y el objeto se libera.

Una estrategia alternativa se llama recolección automática de basura. (A veces, el recuento de referencias también se conoce como una estrategia de recolección de basura, de ahí mi uso de «automático» para distinguir los dos). La gran ventaja de la recolección automática de basura es que el usuario no necesita llamar a free() explícitamente. (Otra ventaja afirmada es una mejora en la velocidad o el uso de la memoria; sin embargo, esto no es un hecho difícil). La desventaja es que para C, no hay un recolector de basura automático verdaderamente portátil, mientras que el conteo de referencias se puede implementar de forma portátil (siempre que las funciones malloc() y free() están disponibles — que garantiza el estándar C). Tal vez algún día un recolector de basura automático lo suficientemente portátil estará disponible para C. Hasta entonces, tendremos que vivir con recuentos de referencia.

Si bien Python utiliza la implementación tradicional de conteo de referencias, también ofrece un detector de ciclos que funciona para detectar ciclos de referencia. Esto permite que las aplicaciones no se preocupen por crear referencias circulares directas o indirectas; Estas son las debilidades de la recolección de basura implementada utilizando solo el conteo de referencias. Los ciclos de referencia consisten en objetos que contienen referencias (posiblemente indirectas) a sí mismos, de modo que cada objeto en el ciclo tiene un recuento de referencias que no es cero. Las implementaciones típicas de recuento de referencias no pueden recuperar la memoria que pertenece a algún objeto en un ciclo de referencia, o referenciada a partir de los objetos en el ciclo, a pesar de que no hay más referencias al ciclo en sí.

El detector de ciclos puede detectar ciclos de basura y puede reclamarlos. El módulo gc expone una forma de ejecutar el detector (la función collect()), así como las interfaces de configuración y la capacidad de desactivar el detector en tiempo de ejecución. El detector de ciclo se considera un componente opcional; aunque se incluye de manera predeterminada, se puede deshabilitar en el momento de la compilación utilizando la opción --without-cycle-gc al script configure en plataformas Unix (incluido Mac OS X). Si el detector de ciclos está deshabilitado de esta manera, el módulo gc no estará disponible.

1.10.1. Conteo de Referencias en Python

Hay dos macros, Py_INCREF(x) y Py_DECREF(x), que manejan el incremento y la disminución del recuento de referencias. Py_DECREF() también libera el objeto cuando el recuento llega a cero. Por flexibilidad, no llama a free() directamente — más bien, realiza una llamada a través de un puntero de función en el objeto type object. Para este propósito (y otros), cada objeto también contiene un puntero a su objeto de tipo.

La gran pregunta ahora permanece: ¿cuándo usar Py_INCREF(x) y Py_DECREF(x)? Primero introduzcamos algunos términos. Nadie «posee» un objeto; sin embargo, puede poseer una referencia a un objeto. El recuento de referencias de un objeto ahora se define como el número de referencias que posee. El propietario de una referencia es responsable de llamar a Py_DECREF() cuando la referencia ya no es necesaria. La propiedad de una referencia puede ser transferida. Hay tres formas de deshacerse de una referencia de propiedad: pasarla, almacenarla o llamar a Py_DECREF(). Olvidar deshacerse de una referencia de propiedad crea una pérdida de memoria.

También es posible tomar prestada 2 una referencia a un objeto. El prestatario de una referencia no debe llamar a Py_DECREF(). El prestatario no debe retener el objeto por más tiempo que el propietario del cual fue prestado. El uso de una referencia prestada después de que el propietario la haya eliminado corre el riesgo de usar memoria liberada y debe evitarse por completo 3.

La ventaja de pedir prestado sobre tener una referencia es que no necesita ocuparse de disponer de la referencia en todas las rutas posibles a través del código — en otras palabras, con una referencia prestada no corre el riesgo de fugas cuando se toma una salida prematura. La desventaja de pedir prestado sobre la posesión es que hay algunas situaciones sutiles en las que, en un código aparentemente correcto, una referencia prestada se puede usar después de que el propietario del que se tomó prestado la haya eliminado.

Una referencia prestada se puede cambiar en una referencia de propiedad llamando a Py_INCREF(). Esto no afecta el estado del propietario del cual se tomó prestada la referencia: crea una nueva referencia de propiedad y otorga responsabilidades completas al propietario (el nuevo propietario debe disponer de la referencia correctamente, así como el propietario anterior).

1.10.2. Reglas de Propiedad

Cuando una referencia de objeto se pasa dentro o fuera de una función, es parte de la especificación de la interfaz de la función si la propiedad se transfiere con la referencia o no.

La mayoría de las funciones que retornan una referencia a un objeto pasan de propiedad con la referencia. En particular, todas las funciones cuya función es crear un nuevo objeto, como PyLong_FromLong() y Py_BuildValue(), pasan la propiedad al receptor. Incluso si el objeto no es realmente nuevo, aún recibirá la propiedad de una nueva referencia a ese objeto. Por ejemplo, PyLong_FromLong() mantiene un caché de valores populares y puede retornar una referencia a un elemento en caché.

Muchas funciones que extraen objetos de otros objetos también transfieren la propiedad con la referencia, por ejemplo PyObject_GetAttrString(). Sin embargo, la imagen es menos clara aquí, ya que algunas rutinas comunes son excepciones: PyTuple_GetItem(), PyList_GetItem(), PyDict_GetItem(), y PyDict_GetItemString() todas las referencias retornadas que tomaste prestadas de la tupla, lista o diccionario.

La función PyImport_AddModule() también retorna una referencia prestada, aunque en realidad puede crear el objeto que retorna: esto es posible porque una referencia de propiedad del objeto se almacena en sys.modules.

Cuando pasa una referencia de objeto a otra función, en general, la función toma prestada la referencia de usted — si necesita almacenarla, usará Py_INCREF() para convertirse en un propietario independiente. Hay exactamente dos excepciones importantes a esta regla: PyTuple_SetItem() y PyList_SetItem(). Estas funciones se hacen cargo de la propiedad del artículo que se les pasa, ¡incluso si fallan! (Tenga en cuenta que PyDict_SetItem() y sus amigos no se hacen cargo de la propiedad — son «normales»)

Cuando se llama a una función C desde Python, toma de la persona que llama referencias a sus argumentos. Quien llama posee una referencia al objeto, por lo que la vida útil de la referencia prestada está garantizada hasta que la función regrese. Solo cuando dicha referencia prestada debe almacenarse o transmitirse, debe convertirse en una referencia propia llamando a Py_INCREF().

La referencia de objeto retornada desde una función C que se llama desde Python debe ser una referencia de propiedad: la propiedad se transfiere de la función a su llamador.

1.10.3. Hielo delgado

Hay algunas situaciones en las que el uso aparentemente inofensivo de una referencia prestada puede generar problemas. Todo esto tiene que ver con invocaciones implícitas del intérprete, lo que puede hacer que el propietario de una referencia se deshaga de él.

El primer y más importante caso que debe conocer es el uso de Py_DECREF() en un objeto no relacionado mientras toma prestada una referencia a un elemento de la lista. Por ejemplo:

void
bug(PyObject *list)
{
    PyObject *item = PyList_GetItem(list, 0);

    PyList_SetItem(list, 1, PyLong_FromLong(0L));
    PyObject_Print(item, stdout, 0); /* BUG! */
}

Esta función primero toma prestada una referencia a list[0], luego reemplaza list[1] con el valor 0, y finalmente imprime la referencia prestada. Parece inofensivo, ¿verdad? ¡Pero no lo es!

Sigamos el flujo de control en PyList_SetItem(). La lista posee referencias a todos sus elementos, por lo que cuando se reemplaza el elemento 1, debe deshacerse del elemento original 1. Ahora supongamos que el elemento original 1 era una instancia de una clase definida por el usuario, y supongamos además que la clase definió un método __del__(). Si esta instancia de clase tiene un recuento de referencia de 1, al eliminarla llamará a su método __del__().

Como está escrito en Python, el método __del__() puede ejecutar código arbitrario de Python. ¿Podría hacer algo para invalidar la referencia a item en error()? ¡Tenlo por seguro! Suponiendo que la lista pasado a bug() es accesible para el método __del__(), podría ejecutar una declaración en el sentido de del list[0], y suponiendo que este fuera el última referencia a ese objeto, liberaría la memoria asociada con él, invalidando así el elemento.

La solución, una vez que conoce el origen del problema, es fácil: incremente temporalmente el recuento de referencia. La versión correcta de la función dice:

void
no_bug(PyObject *list)
{
    PyObject *item = PyList_GetItem(list, 0);

    Py_INCREF(item);
    PyList_SetItem(list, 1, PyLong_FromLong(0L));
    PyObject_Print(item, stdout, 0);
    Py_DECREF(item);
}

Esta es una historia real. Una versión anterior de Python contenía variantes de este error y alguien pasó una cantidad considerable de tiempo en un depurador C para descubrir por qué sus métodos __del__() fallaban …

El segundo caso de problemas con una referencia prestada es una variante que involucra hilos. Normalmente, varios hilos en el intérprete de Python no pueden interponerse entre sí, porque hay un bloqueo global que protege todo el espacio de objetos de Python. Sin embargo, es posible liberar temporalmente este bloqueo usando la macro Py_BEGIN_ALLOW_THREADS, y volver a adquirirlo usando Py_END_ALLOW_THREADS. Esto es común al bloquear las llamadas de E/S, para permitir que otros subprocesos usen el procesador mientras esperan que se complete la E/S. Obviamente, la siguiente función tiene el mismo problema que la anterior:

void
bug(PyObject *list)
{
    PyObject *item = PyList_GetItem(list, 0);
    Py_BEGIN_ALLOW_THREADS
    ...some blocking I/O call...
    Py_END_ALLOW_THREADS
    PyObject_Print(item, stdout, 0); /* BUG! */
}

1.10.4. Punteros NULL

En general, las funciones que toman referencias de objetos como argumentos no esperan que les pase los punteros NULL, y volcará el núcleo (o causará volcados de núcleo posteriores) si lo hace. Las funciones que retornan referencias a objetos generalmente retornan NULL solo para indicar que ocurrió una excepción. La razón para no probar los argumentos NULL es que las funciones a menudo pasan los objetos que reciben a otra función — si cada función probara NULL, habría muchas pruebas redundantes y el código correría más lentamente.

Es mejor probar NULL solo en «source:» cuando se recibe un puntero que puede ser NULL, por ejemplo, de malloc() o de una función que puede plantear una excepción.

Las macros Py_INCREF() y Py_DECREF() no comprueban los punteros NULL — sin embargo, sus variantes Py_XINCREF() y Py_XDECREF() lo hacen.

Las macros para verificar un tipo de objeto en particular (Pytype_Check()) no verifican los punteros NULL — nuevamente, hay mucho código que llama a varios de estos en una fila para probar un objeto contra varios tipos esperados diferentes, y esto generaría pruebas redundantes. No hay variantes con comprobación NULL.

El mecanismo de llamada a la función C garantiza que la lista de argumentos pasada a las funciones C (args en los ejemplos) nunca sea NULL — de hecho, garantiza que siempre sea una tupla 4.

Es un error grave dejar que un puntero NULL «escape» al usuario de Python.

1.11. Escribiendo Extensiones en C++

Es posible escribir módulos de extensión en C++. Se aplican algunas restricciones. Si el compilador de C compila y vincula el programa principal (el intérprete de Python), no se pueden usar objetos globales o estáticos con constructores. Esto no es un problema si el programa principal está vinculado por el compilador de C++. Las funciones que serán llamadas por el intérprete de Python (en particular, las funciones de inicialización del módulo) deben declararse usando extern "C". No es necesario encerrar los archivos de encabezado de Python en extern "C" {...} — ya usan este formulario si el símbolo __cplusplus está definido (todos los compiladores recientes de C++ definen este símbolo) .

1.12. Proporcionar una API C para un módulo de extensión

Muchos módulos de extensión solo proporcionan nuevas funciones y tipos para ser utilizados desde Python, pero a veces el código en un módulo de extensión puede ser útil para otros módulos de extensión. Por ejemplo, un módulo de extensión podría implementar un tipo de «colección» que funciona como listas sin orden. Al igual que el tipo de lista Python estándar tiene una API C que permite a los módulos de extensión crear y manipular listas, este nuevo tipo de colección debe tener un conjunto de funciones C para la manipulación directa desde otros módulos de extensión.

A primera vista, esto parece fácil: simplemente escriba las funciones (sin declararlas static, por supuesto), proporcione un archivo de encabezado apropiado y documente la API de C. Y, de hecho, esto funcionaría si todos los módulos de extensión siempre estuvieran vinculados estáticamente con el intérprete de Python. Sin embargo, cuando los módulos se usan como bibliotecas compartidas, los símbolos definidos en un módulo pueden no ser visibles para otro módulo. Los detalles de visibilidad dependen del sistema operativo; algunos sistemas usan un espacio de nombres global para el intérprete de Python y todos los módulos de extensión (Windows, por ejemplo), mientras que otros requieren una lista explícita de símbolos importados en el momento del enlace del módulo (AIX es un ejemplo) u ofrecen una variedad de estrategias diferentes (la mayoría Unices). E incluso si los símbolos son visibles a nivel mundial, ¡el módulo cuyas funciones uno desea llamar podría no haberse cargado todavía!

Por lo tanto, la portabilidad requiere no hacer suposiciones sobre la visibilidad del símbolo. Esto significa que todos los símbolos en los módulos de extensión deben declararse static, excepto la función de inicialización del módulo, para evitar conflictos de nombres con otros módulos de extensión (como se discutió en la sección La tabla de métodos del módulo y la función de inicialización). Y significa que los símbolos que deberían ser accesibles desde otros módulos de extensión deben exportarse de una manera diferente.

Python proporciona un mecanismo especial para pasar información de nivel C (punteros) de un módulo de extensión a otro: Cápsulas. Una cápsula es un tipo de datos de Python que almacena un puntero (void *). Las cápsulas solo se pueden crear y acceder a través de su API de C, pero se pueden pasar como cualquier otro objeto de Python. En particular, pueden asignarse a un nombre en el espacio de nombres de un módulo de extensión. Otros módulos de extensión pueden importar este módulo, recuperar el valor de este nombre y luego recuperar el puntero de la Cápsula.

Hay muchas formas en que las Cápsulas se pueden usar para exportar la API de C de un módulo de extensión. Cada función podría tener su propia cápsula, o todos los punteros de API C podrían almacenarse en una matriz cuya dirección se publica en una cápsula. Y las diversas tareas de almacenamiento y recuperación de los punteros se pueden distribuir de diferentes maneras entre el módulo que proporciona el código y los módulos del cliente.

Sea cual sea el método que elija, es importante nombrar sus cápsulas correctamente. La función PyCapsule_New() toma un parámetro de nombre (const char *); se le permite pasar un nombre NULL, pero le recomendamos que especifique un nombre. Las cápsulas correctamente nombradas proporcionan un grado de seguridad de tipo de tiempo de ejecución; no hay una manera factible de distinguir una Cápsula sin nombre de otra.

En particular, las cápsulas utilizadas para exponer las API de C deben recibir un nombre siguiendo esta convención:

modulename.attributename

La función de conveniencia PyCapsule_Import() facilita la carga de una API C proporcionada a través de una cápsula, pero solo si el nombre de la cápsula coincide con esta convención. Este comportamiento brinda a los usuarios de C API un alto grado de certeza de que la Cápsula que cargan contiene la API de C correcta.

El siguiente ejemplo demuestra un enfoque que pone la mayor parte de la carga en el escritor del módulo de exportación, que es apropiado para los módulos de biblioteca de uso común. Almacena todos los punteros de API C (¡solo uno en el ejemplo!) En un arreglo de punteros void que se convierte en el valor de una cápsula. El archivo de encabezado correspondiente al módulo proporciona una macro que se encarga de importar el módulo y recuperar sus punteros de API C; Los módulos de cliente solo tienen que llamar a esta macro antes de acceder a la API de C.

El módulo de exportación es una modificación del módulo spam de la sección Un ejemplo simple. La función spam.system() no llama a la función de la biblioteca C system() directamente, sino una función PySpam_System(), que por supuesto haría algo más complicado en realidad (como agregar «spam» a cada comando). Esta función PySpam_System() también se exporta a otros módulos de extensión.

La función PySpam_System() es una función C simple, declarada static como todo lo demás:

static int
PySpam_System(const char *command)
{
    return system(command);
}

La función spam_system() se modifica de manera trivial:

static PyObject *
spam_system(PyObject *self, PyObject *args)
{
    const char *command;
    int sts;

    if (!PyArg_ParseTuple(args, "s", &command))
        return NULL;
    sts = PySpam_System(command);
    return PyLong_FromLong(sts);
}

Al comienzo del módulo, justo después de la línea:

#include <Python.h>

se deben agregar dos líneas más:

#define SPAM_MODULE
#include "spammodule.h"

El #define se usa para decirle al archivo de encabezado que se está incluyendo en el módulo de exportación, no en un módulo de cliente. Finalmente, la función de inicialización del módulo debe encargarse de inicializar la matriz de punteros de API C:

PyMODINIT_FUNC
PyInit_spam(void)
{
    PyObject *m;
    static void *PySpam_API[PySpam_API_pointers];
    PyObject *c_api_object;

    m = PyModule_Create(&spammodule);
    if (m == NULL)
        return NULL;

    /* Initialize the C API pointer array */
    PySpam_API[PySpam_System_NUM] = (void *)PySpam_System;

    /* Create a Capsule containing the API pointer array's address */
    c_api_object = PyCapsule_New((void *)PySpam_API, "spam._C_API", NULL);

    if (PyModule_AddObject(m, "_C_API", c_api_object) < 0) {
        Py_XDECREF(c_api_object);
        Py_DECREF(m);
        return NULL;
    }

    return m;
}

Tenga en cuenta que PySpam_API se declara static; de lo contrario, la matriz de punteros desaparecería cuando PyInit_spam() finalice!

La mayor parte del trabajo está en el archivo de encabezado spammodule.h, que se ve así:

#ifndef Py_SPAMMODULE_H
#define Py_SPAMMODULE_H
#ifdef __cplusplus
extern "C" {
#endif

/* Header file for spammodule */

/* C API functions */
#define PySpam_System_NUM 0
#define PySpam_System_RETURN int
#define PySpam_System_PROTO (const char *command)

/* Total number of C API pointers */
#define PySpam_API_pointers 1

#ifdef SPAM_MODULE
/* This section is used when compiling spammodule.c */

static PySpam_System_RETURN PySpam_System PySpam_System_PROTO;

#else
/* This section is used in modules that use spammodule's API */

static void **PySpam_API;

#define PySpam_System \
 (*(PySpam_System_RETURN (*)PySpam_System_PROTO) PySpam_API[PySpam_System_NUM])

/* Return -1 on error, 0 on success.
 * PyCapsule_Import will set an exception if there's an error.
 */
static int
import_spam(void)
{
    PySpam_API = (void **)PyCapsule_Import("spam._C_API", 0);
    return (PySpam_API != NULL) ? 0 : -1;
}

#endif

#ifdef __cplusplus
}
#endif

#endif /* !defined(Py_SPAMMODULE_H) */

Todo lo que un módulo cliente debe hacer para tener acceso a la función PySpam_System() es llamar a la función (o más bien macro) import_spam() en su función de inicialización:

PyMODINIT_FUNC
PyInit_client(void)
{
    PyObject *m;

    m = PyModule_Create(&clientmodule);
    if (m == NULL)
        return NULL;
    if (import_spam() < 0)
        return NULL;
    /* additional initialization can happen here */
    return m;
}

La principal desventaja de este enfoque es que el archivo spammodule.h es bastante complicado. Sin embargo, la estructura básica es la misma para cada función que se exporta, por lo que solo se debe aprender una vez.

Finalmente, debe mencionarse que las cápsulas ofrecen una funcionalidad adicional, que es especialmente útil para la asignación de memoria y la desasignación del puntero almacenado en una cápsula. Los detalles se describen en el Manual de referencia de Python/C API en la sección Cápsulas y en la implementación de Capsules (archivos Include/pycapsule.h y Objects/pycapsule.c en la distribución del código fuente de Python).

Notas al pie de página

1

Ya existe una interfaz para esta función en el módulo estándar os — se eligió como un ejemplo simple y directo.

2

La metáfora de «pedir prestado» una referencia no es completamente correcta: el propietario todavía tiene una copia de la referencia.

3

¡Comprobar que el recuento de referencia es al menos 1 no funciona — el recuento de referencia en sí podría estar en la memoria liberada y, por lo tanto, puede reutilizarse para otro objeto!

4

Estas garantías no se cumplen cuando utiliza la convención de llamadas de estilo «antiguo», que todavía se encuentra en muchos códigos existentes.

2. Definición de tipos de extensión: Tutorial

Python le permite al escritor de un módulo de extensión C definir nuevos tipos que pueden ser manipulados desde el código Python, al igual que los tipos incorporados str y list. El código para todos los tipos de extensión sigue un patrón, pero hay algunos detalles que debe comprender antes de comenzar. Este documento es una introducción suave al tema.

2.1. Lo Básico

El tiempo de ejecución CPython ve todos los objetos de Python como variables de tipo PyObject*, que sirve como un «tipo base» para todos los objetos de Python. La estructura PyObject solo contiene el reference count del objeto y un puntero al «objeto tipo» del objeto. Aquí es donde está la acción; el objeto tipo determina qué funciones (C) llama el intérprete cuando, por ejemplo, se busca un atributo en un objeto, se llama un método o se multiplica por otro objeto. Estas funciones de C se denominan «métodos de tipo».

Por lo tanto, si desea definir un nuevo tipo de extensión, debe crear un nuevo objeto de tipo.

Este tipo de cosas solo se pueden explicar con un ejemplo, por lo que aquí hay un módulo mínimo, pero completo, que define un nuevo tipo llamado Custom dentro de un módulo de extensión C custom:

Nota

Lo que estamos mostrando aquí es la forma tradicional de definir tipos de extensión estáticos. Debe ser adecuado para la mayoría de los usos. La API de C también permite definir tipos de extensiones asignadas en el montón utilizando la función PyType_FromSpec(), que no se trata en este tutorial.

#define PY_SSIZE_T_CLEAN
#include <Python.h>

typedef struct {
    PyObject_HEAD
    /* Type-specific fields go here. */
} CustomObject;

static PyTypeObject CustomType = {
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "custom.Custom",
    .tp_doc = PyDoc_STR("Custom objects"),
    .tp_basicsize = sizeof(CustomObject),
    .tp_itemsize = 0,
    .tp_flags = Py_TPFLAGS_DEFAULT,
    .tp_new = PyType_GenericNew,
};

static PyModuleDef custommodule = {
    PyModuleDef_HEAD_INIT,
    .m_name = "custom",
    .m_doc = "Example module that creates an extension type.",
    .m_size = -1,
};

PyMODINIT_FUNC
PyInit_custom(void)
{
    PyObject *m;
    if (PyType_Ready(&CustomType) < 0)
        return NULL;

    m = PyModule_Create(&custommodule);
    if (m == NULL)
        return NULL;

    Py_INCREF(&CustomType);
    if (PyModule_AddObject(m, "Custom", (PyObject *) &CustomType) < 0) {
        Py_DECREF(&CustomType);
        Py_DECREF(m);
        return NULL;
    }

    return m;
}

Ahora, eso es bastante para asimilar a la vez, pero espero que los fragmentos le resulten familiares del capítulo anterior. Este archivo define tres cosas:

Lo que contiene un objeto Custom: esta es la estructura CustomObject, que se asigna una vez para cada instancia de Custom.

Cómo se comporta Custom type: esta es la estructura CustomType, que define un conjunto de indicadores y punteros de función que el intérprete inspecciona cuando se solicitan operaciones específicas.

Cómo inicializar el módulo custom: esta es la función PyInit_custom y la estructura asociada custommodule.

La primera parte es:

typedef struct {
    PyObject_HEAD
} CustomObject;

This is what a Custom object will contain. PyObject_HEAD is mandatory at the start of each object struct and defines a field called ob_base of type PyObject, containing a pointer to a type object and a reference count (these can be accessed using the macros Py_TYPE and Py_REFCNT respectively). The reason for the macro is to abstract away the layout and to enable additional fields in debug builds.

Nota

No hay punto y coma (;) arriba después de la macro PyObject_HEAD. Tenga cuidado de agregar uno por accidente: algunos compiladores se quejarán.

Por supuesto, los objetos generalmente almacenan datos adicionales además del estándar PyObject_HEAD repetitivo; por ejemplo, aquí está la definición de puntos flotantes del estándar de Python:

typedef struct {
    PyObject_HEAD
    double ob_fval;
} PyFloatObject;

La segunda parte es la definición del tipo de objecto.

static PyTypeObject CustomType = {
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "custom.Custom",
    .tp_doc = PyDoc_STR("Custom objects"),
    .tp_basicsize = sizeof(CustomObject),
    .tp_itemsize = 0,
    .tp_flags = Py_TPFLAGS_DEFAULT,
    .tp_new = PyType_GenericNew,
};

Nota

Recomendamos utilizar los inicializadores designados al estilo C99 como se indica arriba, para evitar enumerar todos los campos PyTypeObject que no le interesan y también para evitar preocuparse por el orden de declaración de los campos.

La definición real de PyTypeObject en object.h tiene muchos más campos que la definición anterior. El compilador de C rellenará los campos restantes con ceros, y es una práctica común no especificarlos explícitamente a menos que los necesite.

Lo vamos a separar, un campo a la vez:

PyVarObject_HEAD_INIT(NULL, 0)

Esta línea es obligatoria para inicializar el campo ob_base mencionado anteriormente.

.tp_name = "custom.Custom",

El nombre de nuestro tipo. Esto aparecerá en la representación textual predeterminada de nuestros objetos y en algunos mensajes de error, por ejemplo:

>>> "" + custom.Custom()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: can only concatenate str (not "custom.Custom") to str

Tenga en cuenta que el nombre es un nombre punteado que incluye tanto el nombre del módulo como el nombre del tipo dentro del módulo. El módulo en este caso es custom y el tipo es Custom, por lo que establecemos el nombre del tipo en custom.Custom. Usar la ruta de importación punteada real es importante para que su tipo sea compatible con los módulos pydoc y pickle.

.tp_basicsize = sizeof(CustomObject),
.tp_itemsize = 0,

Esto es para que Python sepa cuánta memoria asignar al crear instancias nuevas Custom. tp_itemsize solo se usa para objetos de tamaño variable y, de lo contrario, debería ser cero.

Nota

Si desea que su tipo pueda tener subclases desde Python, y su tipo tiene el mismo tp_basicsize como su tipo base, puede tener problemas con la herencia múltiple. Una subclase de Python de su tipo tendrá que enumerar su tipo primero en su __bases__, o de lo contrario no podrá llamar al método de su tipo __new__() sin obtener un error. Puede evitar este problema asegurándose de que su tipo tenga un valor mayor para tp_basicsize que su tipo base. La mayoría de las veces, esto será cierto de todos modos, porque su tipo base será object, o de lo contrario agregará miembros de datos a su tipo base y, por lo tanto, aumentará su tamaño.

Configuramos las banderas de clase a Py_TPFLAGS_DEFAULT.

.tp_flags = Py_TPFLAGS_DEFAULT,

Todos los tipos deben incluir esta constante en sus banderas. Habilita todos los miembros definidos hasta al menos Python 3.3. Si necesita más miembros, necesitará O (OR) las banderas correspondientes.

Proporcionamos una cadena de documentos para el tipo en tp_doc.

.tp_doc = PyDoc_STR("Custom objects"),

Para habilitar la creación de objetos, debemos proporcionar un controlador tp_new. Este es el equivalente del método Python __new__(), pero debe especificarse explícitamente. En este caso, podemos usar la implementación predeterminada proporcionada por la función API PyType_GenericNew().

.tp_new = PyType_GenericNew,

Todo lo demás en el archivo debe ser familiar, excepto algún código en PyInit_custom():

if (PyType_Ready(&CustomType) < 0)
    return;

Esto inicializa el tipo Custom, completando un número de miembros con los valores predeterminados apropiados, que incluyen ob_type que inicialmente configuramos en NULL.

Py_INCREF(&CustomType);
if (PyModule_AddObject(m, "Custom", (PyObject *) &CustomType) < 0) {
    Py_DECREF(&CustomType);
    Py_DECREF(m);
    return NULL;
}

Esto agrega el tipo al diccionario del módulo. Esto nos permite crear instancias Custom llamando la clase Custom:

>>> import custom
>>> mycustom = custom.Custom()

¡Eso es! Todo lo que queda es construirlo; ponga el código anterior en un archivo llamado custom.c y:

from distutils.core import setup, Extension
setup(name="custom", version="1.0",
      ext_modules=[Extension("custom", ["custom.c"])])

en un archivo llamado setup.py; luego escribiendo

$ python setup.py build

en un shell debería producir un archivo custom.so en un subdirectorio; muévete a ese directorio y abre Python — deberías poder import custom y jugar con objetos personalizados.

Eso no fue tan difícil, ¿verdad?

Por supuesto, el tipo personalizado actual es bastante poco interesante. No tiene datos y no hace nada. Ni siquiera se puede subclasificar.

Nota

Si bien esta documentación muestra el módulo estándar distutils para construir extensiones C, se recomienda en casos de uso del mundo real utilizar la biblioteca setuptools más nueva y mejor mantenida. La documentación sobre cómo hacer esto está fuera del alcance de este documento y se puede encontrar en la Guía de usuario del Empaquetamiento de Python [https://packaging.python.org/tutorials/distributing-packages/].

2.2. Agregar datos y métodos al ejemplo básico

Extendamos el ejemplo básico para agregar algunos datos y métodos. También hagamos que el tipo sea utilizable como una clase base. Crearemos un nuevo módulo, custom2 que agrega estas capacidades:

#define PY_SSIZE_T_CLEAN
#include <Python.h>
#include "structmember.h"

typedef struct {
    PyObject_HEAD
    PyObject *first; /* first name */
    PyObject *last;  /* last name */
    int number;
} CustomObject;

static void
Custom_dealloc(CustomObject *self)
{
    Py_XDECREF(self->first);
    Py_XDECREF(self->last);
    Py_TYPE(self)->tp_free((PyObject *) self);
}

static PyObject *
Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
{
    CustomObject *self;
    self = (CustomObject *) type->tp_alloc(type, 0);
    if (self != NULL) {
        self->first = PyUnicode_FromString("");
        if (self->first == NULL) {
            Py_DECREF(self);
            return NULL;
        }
        self->last = PyUnicode_FromString("");
        if (self->last == NULL) {
            Py_DECREF(self);
            return NULL;
        }
        self->number = 0;
    }
    return (PyObject *) self;
}

static int
Custom_init(CustomObject *self, PyObject *args, PyObject *kwds)
{
    static char *kwlist[] = {"first", "last", "number", NULL};
    PyObject *first = NULL, *last = NULL, *tmp;

    if (!PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist,
                                     &first, &last,
                                     &self->number))
        return -1;

    if (first) {
        tmp = self->first;
        Py_INCREF(first);
        self->first = first;
        Py_XDECREF(tmp);
    }
    if (last) {
        tmp = self->last;
        Py_INCREF(last);
        self->last = last;
        Py_XDECREF(tmp);
    }
    return 0;
}

static PyMemberDef Custom_members[] = {
    {"first", T_OBJECT_EX, offsetof(CustomObject, first), 0,
     "first name"},
    {"last", T_OBJECT_EX, offsetof(CustomObject, last), 0,
     "last name"},
    {"number", T_INT, offsetof(CustomObject, number), 0,
     "custom number"},
    {NULL}  /* Sentinel */
};

static PyObject *
Custom_name(CustomObject *self, PyObject *Py_UNUSED(ignored))
{
    if (self->first == NULL) {
        PyErr_SetString(PyExc_AttributeError, "first");
        return NULL;
    }
    if (self->last == NULL) {
        PyErr_SetString(PyExc_AttributeError, "last");
        return NULL;
    }
    return PyUnicode_FromFormat("%S %S", self->first, self->last);
}

static PyMethodDef Custom_methods[] = {
    {"name", (PyCFunction) Custom_name, METH_NOARGS,
     "Return the name, combining the first and last name"
    },
    {NULL}  /* Sentinel */
};

static PyTypeObject CustomType = {
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "custom2.Custom",
    .tp_doc = PyDoc_STR("Custom objects"),
    .tp_basicsize = sizeof(CustomObject),
    .tp_itemsize = 0,
    .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,
    .tp_new = Custom_new,
    .tp_init = (initproc) Custom_init,
    .tp_dealloc = (destructor) Custom_dealloc,
    .tp_members = Custom_members,
    .tp_methods = Custom_methods,
};

static PyModuleDef custommodule = {
    PyModuleDef_HEAD_INIT,
    .m_name = "custom2",
    .m_doc = "Example module that creates an extension type.",
    .m_size = -1,
};

PyMODINIT_FUNC
PyInit_custom2(void)
{
    PyObject *m;
    if (PyType_Ready(&CustomType) < 0)
        return NULL;

    m = PyModule_Create(&custommodule);
    if (m == NULL)
        return NULL;

    Py_INCREF(&CustomType);
    if (PyModule_AddObject(m, "Custom", (PyObject *) &CustomType) < 0) {
        Py_DECREF(&CustomType);
        Py_DECREF(m);
        return NULL;
    }

    return m;
}

Esta versión del módulo tiene una serie de cambios.

Hemos agregado una inclusión adicional:

#include <structmember.h>

Esto incluye declaraciones que usamos para manejar atributos, como se describe un poco más adelante.

El tipo Custom ahora tiene tres atributos de datos en su estructura C, first, last y number. Las variables first y last son cadenas de caracteres de Python que contienen nombres y apellidos. El atributo number es un entero C.

La estructura del objeto se actualiza en consecuencia:

typedef struct {
    PyObject_HEAD
    PyObject *first; /* first name */
    PyObject *last;  /* last name */
    int number;
} CustomObject;

Debido a que ahora tenemos datos para administrar, debemos ser más cuidadosos con la asignación de objetos y la desasignación. Como mínimo, necesitamos un método de desasignación:

static void
Custom_dealloc(CustomObject *self)
{
    Py_XDECREF(self->first);
    Py_XDECREF(self->last);
    Py_TYPE(self)->tp_free((PyObject *) self);
}

que se asigna al miembro tp_dealloc:

.tp_dealloc = (destructor) Custom_dealloc,

Este método primero borra los recuentos de referencia de los dos atributos de Python. Py_XDECREF() maneja correctamente el caso donde su argumento es NULL (lo que podría ocurrir aquí si tp_new fallara a mitad de camino). Luego llama al miembro tp_free del tipo de objeto (calculado por Py_TYPE(self)) para liberar la memoria del objeto. Tenga en cuenta que el tipo de objeto podría no ser CustomType, porque el objeto puede ser una instancia de una subclase.

Nota

La conversión explícita a destructor anterior es necesaria porque definimos Custom_dealloc para tomar un argumento CustomObject *, pero el puntero de función tp_dealloc espera recibir un argumento PyObject *. De lo contrario, el compilador emitirá una advertencia. Este es un polimorfismo orientado a objetos, en C!

Queremos asegurarnos de que el nombre y el apellido se inicialicen en cadenas de caracteres vacías, por lo que proporcionamos una implementación tp_new:

static PyObject *
Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
{
    CustomObject *self;
    self = (CustomObject *) type->tp_alloc(type, 0);
    if (self != NULL) {
        self->first = PyUnicode_FromString("");
        if (self->first == NULL) {
            Py_DECREF(self);
            return NULL;
        }
        self->last = PyUnicode_FromString("");
        if (self->last == NULL) {
            Py_DECREF(self);
            return NULL;
        }
        self->number = 0;
    }
    return (PyObject *) self;
}

e instalarlo en el miembro tp_new:

.tp_new = Custom_new,

El controlador tp_new es responsable de crear (en lugar de inicializar) objetos del tipo. Está expuesto en Python como el método __new__(). No es necesario definir un miembro tp_new, y de hecho muchos tipos de extensiones simplemente reutilizarán PyType_GenericNew() como se hizo en la primera versión del tipo Personalizado anterior. En este caso, usamos el controlador tp_new para inicializar los atributos first y last a valores predeterminados que no sean NULL.

tp_new se pasa el tipo que se instancia (no necesariamente CustomType, si se instancia una subclase) y cualquier argumento pasado cuando se llamó al tipo, y se espera que retorna la instancia creada. Los manejadores tp_new siempre aceptan argumentos posicionales y de palabras clave, pero a menudo ignoran los argumentos, dejando el manejo de argumentos al inicializador (también conocido como, tp_init en C o __init__ en Python).

Nota

tp_new no debería llamar explícitamente a tp_init, ya que el intérprete lo hará por sí mismo.

La implementación tp_new llama al tp_alloc para asignar memoria:

self = (CustomObject *) type->tp_alloc(type, 0);

Como la asignación de memoria puede fallar, debemos verificar el resultado tp_alloc contra NULL antes de continuar.

Nota

No llenamos la ranura tp_alloc nosotros mismos. Más bien PyType_Ready() lo llena para nosotros al heredarlo de nuestra clase base, que es object por defecto. La mayoría de los tipos utilizan la estrategia de asignación predeterminada.

Nota

Si está creando una cooperativa tp_new (una que llama a un tipo base tp_new o __new__()), no debe intentar determinar a qué método llamar utilizando el orden de resolución del método en tiempo de ejecución. Siempre determine estáticamente a qué tipo va a llamar, y llame a su tp_new directamente, o mediante type->tp_base->tp_new. Si no hace esto, las subclases de Python de su tipo que también heredan de otras clases definidas por Python pueden no funcionar correctamente. (Específicamente, es posible que no pueda crear instancias de tales subclases sin obtener un TypeError).

También definimos una función de inicialización que acepta argumentos para proporcionar valores iniciales para nuestra instancia:

static int
Custom_init(CustomObject *self, PyObject *args, PyObject *kwds)
{
    static char *kwlist[] = {"first", "last", "number", NULL};
    PyObject *first = NULL, *last = NULL, *tmp;

    if (!PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist,
                                     &first, &last,
                                     &self->number))
        return -1;

    if (first) {
        tmp = self->first;
        Py_INCREF(first);
        self->first = first;
        Py_XDECREF(tmp);
    }
    if (last) {
        tmp = self->last;
        Py_INCREF(last);
        self->last = last;
        Py_XDECREF(tmp);
    }
    return 0;
}

rellenando la ranura tp_init.

.tp_init = (initproc) Custom_init,

La ranura tp_init está expuesta en Python como el método __init__(). Se utiliza para inicializar un objeto una vez creado. Los inicializadores siempre aceptan argumentos posicionales y de palabras clave, y deben retornar 0 en caso de éxito o -1 en caso de error.

A diferencia del controlador tp_new, no hay garantía de que se llame a tp_init (por ejemplo, el módulo pickle por defecto no llama a __init__() en instancias no controladas ) También se puede llamar varias veces. Cualquiera puede llamar al método __init__() en nuestros objetos. Por esta razón, debemos tener mucho cuidado al asignar los nuevos valores de atributo. Podríamos sentirnos tentados, por ejemplo, a asignar el primer miembro de esta manera:

if (first) {
    Py_XDECREF(self->first);
    Py_INCREF(first);
    self->first = first;
}

Pero esto sería arriesgado. Nuestro tipo no restringe el tipo del primer miembro, por lo que podría ser cualquier tipo de objeto. Podría tener un destructor que haga que se ejecute código que intente acceder al primer miembro; o ese destructor podría liberar el Global Interpreter Lock y permite que se ejecute código arbitrario en otros hilos que acceden y modifican nuestro objeto.

Para ser paranoicos y protegernos de esta posibilidad, casi siempre reasignamos miembros antes de disminuir sus recuentos de referencias. ¿Cuándo no tenemos que hacer esto?

cuando sabemos absolutamente que el recuento de referencia es mayor que 1;

cuando sabemos que la desasignación del objeto 1 no liberará el GIL ni causará ninguna llamada al código de nuestro tipo;

al disminuir un recuento de referencias en un manejador tp_dealloc en un tipo que no admite la recolección de basura cíclica 2.

Queremos exponer nuestras variables de instancia como atributos. Hay varias formas de hacerlo. La forma más simple es definir definiciones de miembros:

static PyMemberDef Custom_members[] = {
    {"first", T_OBJECT_EX, offsetof(CustomObject, first), 0,
     "first name"},
    {"last", T_OBJECT_EX, offsetof(CustomObject, last), 0,
     "last name"},
    {"number", T_INT, offsetof(CustomObject, number), 0,
     "custom number"},
    {NULL}  /* Sentinel */
};

y poner las definiciones en la ranura tp_members:

.tp_members = Custom_members,

Cada definición de miembro tiene un nombre de miembro, tipo, desplazamiento, banderas de acceso y cadena de caracteres de documentación. Consulte la sección Gestión de atributos genéricos a continuación para obtener más detalles.

Una desventaja de este enfoque es que no proporciona una forma de restringir los tipos de objetos que se pueden asignar a los atributos de Python. Esperamos que el nombre y el apellido sean cadenas, pero se pueden asignar objetos de Python. Además, los atributos se pueden eliminar, configurando los punteros C en NULL. Si bien podemos asegurarnos de que los miembros se inicialicen en valores que no sean NULL, los miembros se pueden establecer en NULL si se eliminan los atributos.

Definimos un método único, Custom.name(), que genera el nombre de los objetos como la concatenación de los nombres y apellidos.

static PyObject *
Custom_name(CustomObject *self, PyObject *Py_UNUSED(ignored))
{
    if (self->first == NULL) {
        PyErr_SetString(PyExc_AttributeError, "first");
        return NULL;
    }
    if (self->last == NULL) {
        PyErr_SetString(PyExc_AttributeError, "last");
        return NULL;
    }
    return PyUnicode_FromFormat("%S %S", self->first, self->last);
}

El método se implementa como una función C que toma una instancia de Custom (o subclase Custom) como primer argumento. Los métodos siempre toman una instancia como primer argumento. Los métodos a menudo también toman argumentos posicionales y de palabras clave, pero en este caso no tomamos ninguno y no necesitamos aceptar una tupla de argumentos posicionales o un diccionario de argumentos de palabras clave. Este método es equivalente al método Python:

def name(self):
    return "%s %s" % (self.first, self.last)

Tenga en cuenta que tenemos que verificar la posibilidad de que nuestros miembros first y last sean NULL. Esto se debe a que se pueden eliminar, en cuyo caso se establecen en NULL. Sería mejor evitar la eliminación de estos atributos y restringir los valores de los atributos para que sean cadenas de caracteres. Veremos cómo hacerlo en la siguiente sección.

Ahora que hemos definido el método, necesitamos crear un arreglo de definiciones de métodos:

static PyMethodDef Custom_methods[] = {
    {"name", (PyCFunction) Custom_name, METH_NOARGS,
     "Return the name, combining the first and last name"
    },
    {NULL}  /* Sentinel */
};

(tenga en cuenta que usamos el indicador METH_NOARGS para indicar que el método no espera argumentos distintos de self)

y asignarlo a la ranura tp_methods:

.tp_methods = Custom_methods,

Finalmente, haremos que nuestro tipo sea utilizable como una clase base para la subclase. Hemos escrito nuestros métodos cuidadosamente hasta ahora para que no hagan suposiciones sobre el tipo de objeto que se está creando o utilizando, por lo que todo lo que tenemos que hacer es agregar Py_TPFLAGS_BASETYPE a nuestra definición de bandera de clase:

.tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,

Cambiamos el nombre de PyInit_custom() a PyInit_custom2(), actualizamos el nombre del módulo en la estructura PyModuleDef y actualizamos el nombre completo de la clase en la estructura PyTypeObject.

Finalmente, actualizamos nuestro archivo setup.py para construir el nuevo módulo:

from distutils.core import setup, Extension
setup(name="custom", version="1.0",
      ext_modules=[
         Extension("custom", ["custom.c"]),
         Extension("custom2", ["custom2.c"]),
         ])

2.3. Proporcionar un control más preciso sobre los atributos de datos

En esta sección, proporcionaremos un control más preciso sobre cómo se establecen los atributos first y last en el ejemplo Custom. En la versión anterior de nuestro módulo, las variables de instancia first y last podrían establecerse en valores que no sean de cadena o incluso eliminarse. Queremos asegurarnos de que estos atributos siempre contengan cadenas.

#define PY_SSIZE_T_CLEAN
#include <Python.h>
#include "structmember.h"

typedef struct {
    PyObject_HEAD
    PyObject *first; /* first name */
    PyObject *last;  /* last name */
    int number;
} CustomObject;

static void
Custom_dealloc(CustomObject *self)
{
    Py_XDECREF(self->first);
    Py_XDECREF(self->last);
    Py_TYPE(self)->tp_free((PyObject *) self);
}

static PyObject *
Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
{
    CustomObject *self;
    self = (CustomObject *) type->tp_alloc(type, 0);
    if (self != NULL) {
        self->first = PyUnicode_FromString("");
        if (self->first == NULL) {
            Py_DECREF(self);
            return NULL;
        }
        self->last = PyUnicode_FromString("");
        if (self->last == NULL) {
            Py_DECREF(self);
            return NULL;
        }
        self->number = 0;
    }
    return (PyObject *) self;
}

static int
Custom_init(CustomObject *self, PyObject *args, PyObject *kwds)
{
    static char *kwlist[] = {"first", "last", "number", NULL};
    PyObject *first = NULL, *last = NULL, *tmp;

    if (!PyArg_ParseTupleAndKeywords(args, kwds, "|UUi", kwlist,
                                     &first, &last,
                                     &self->number))
        return -1;

    if (first) {
        tmp = self->first;
        Py_INCREF(first);
        self->first = first;
        Py_DECREF(tmp);
    }
    if (last) {
        tmp = self->last;
        Py_INCREF(last);
        self->last = last;
        Py_DECREF(tmp);
    }
    return 0;
}

static PyMemberDef Custom_members[] = {
    {"number", T_INT, offsetof(CustomObject, number), 0,
     "custom number"},
    {NULL}  /* Sentinel */
};

static PyObject *
Custom_getfirst(CustomObject *self, void *closure)
{
    Py_INCREF(self->first);
    return self->first;
}

static int
Custom_setfirst(CustomObject *self, PyObject *value, void *closure)
{
    PyObject *tmp;
    if (value == NULL) {
        PyErr_SetString(PyExc_TypeError, "Cannot delete the first attribute");
        return -1;
    }
    if (!PyUnicode_Check(value)) {
        PyErr_SetString(PyExc_TypeError,
                        "The first attribute value must be a string");
        return -1;
    }
    tmp = self->first;
    Py_INCREF(value);
    self->first = value;
    Py_DECREF(tmp);
    return 0;
}

static PyObject *
Custom_getlast(CustomObject *self, void *closure)
{
    Py_INCREF(self->last);
    return self->last;
}

static int
Custom_setlast(CustomObject *self, PyObject *value, void *closure)
{
    PyObject *tmp;
    if (value == NULL) {
        PyErr_SetString(PyExc_TypeError, "Cannot delete the last attribute");
        return -1;
    }
    if (!PyUnicode_Check(value)) {
        PyErr_SetString(PyExc_TypeError,
                        "The last attribute value must be a string");
        return -1;
    }
    tmp = self->last;
    Py_INCREF(value);
    self->last = value;
    Py_DECREF(tmp);
    return 0;
}

static PyGetSetDef Custom_getsetters[] = {
    {"first", (getter) Custom_getfirst, (setter) Custom_setfirst,
     "first name", NULL},
    {"last", (getter) Custom_getlast, (setter) Custom_setlast,
     "last name", NULL},
    {NULL}  /* Sentinel */
};

static PyObject *
Custom_name(CustomObject *self, PyObject *Py_UNUSED(ignored))
{
    return PyUnicode_FromFormat("%S %S", self->first, self->last);
}

static PyMethodDef Custom_methods[] = {
    {"name", (PyCFunction) Custom_name, METH_NOARGS,
     "Return the name, combining the first and last name"
    },
    {NULL}  /* Sentinel */
};

static PyTypeObject CustomType = {
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "custom3.Custom",
    .tp_doc = PyDoc_STR("Custom objects"),
    .tp_basicsize = sizeof(CustomObject),
    .tp_itemsize = 0,
    .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,
    .tp_new = Custom_new,
    .tp_init = (initproc) Custom_init,
    .tp_dealloc = (destructor) Custom_dealloc,
    .tp_members = Custom_members,
    .tp_methods = Custom_methods,
    .tp_getset = Custom_getsetters,
};

static PyModuleDef custommodule = {
    PyModuleDef_HEAD_INIT,
    .m_name = "custom3",
    .m_doc = "Example module that creates an extension type.",
    .m_size = -1,
};

PyMODINIT_FUNC
PyInit_custom3(void)
{
    PyObject *m;
    if (PyType_Ready(&CustomType) < 0)
        return NULL;

    m = PyModule_Create(&custommodule);
    if (m == NULL)
        return NULL;

    Py_INCREF(&CustomType);
    if (PyModule_AddObject(m, "Custom", (PyObject *) &CustomType) < 0) {
        Py_DECREF(&CustomType);
        Py_DECREF(m);
        return NULL;
    }

    return m;
}

Para proporcionar un mayor control sobre los atributos first y last, usaremos funciones personalizadas getter y setter. Estas son las funciones para obtener y configurar el atributo first:

static PyObject *
Custom_getfirst(CustomObject *self, void *closure)
{
    Py_INCREF(self->first);
    return self->first;
}

static int
Custom_setfirst(CustomObject *self, PyObject *value, void *closure)
{
    PyObject *tmp;
    if (value == NULL) {
        PyErr_SetString(PyExc_TypeError, "Cannot delete the first attribute");
        return -1;
    }
    if (!PyUnicode_Check(value)) {
        PyErr_SetString(PyExc_TypeError,
                        "The first attribute value must be a string");
        return -1;
    }
    tmp = self->first;
    Py_INCREF(value);
    self->first = value;
    Py_DECREF(tmp);
    return 0;
}

La función getter se pasa al objeto Custom y un «cierre» (closure), que es un puntero nulo. En este caso, se ignora el cierre. (El cierre admite un uso avanzado en el que los datos de definición se pasan al captador y al definidor. Esto podría, por ejemplo, usarse para permitir un solo conjunto de funciones de captador y definidor que deciden que el atributo se obtenga o establezca en función de los datos en el cierre.)

La función setter pasa el objeto Custom, el nuevo valor y el cierre. El nuevo valor puede ser NULL, en cuyo caso se está eliminando el atributo. En nuestro setter, generamos un error si el atributo se elimina o si su nuevo valor no es una cadena.

Creamos un arreglo de estructuras PyGetSetDef:

static PyGetSetDef Custom_getsetters[] = {
    {"first", (getter) Custom_getfirst, (setter) Custom_setfirst,
     "first name", NULL},
    {"last", (getter) Custom_getlast, (setter) Custom_setlast,
     "last name", NULL},
    {NULL}  /* Sentinel */
};

y lo registra en la ranura tp_getset:

.tp_getset = Custom_getsetters,

El último elemento en la estructura PyGetSetDef es el «cierre» (closure) mencionado anteriormente. En este caso, no estamos usando un cierre, por lo que simplemente pasamos NULL.

También eliminamos las definiciones de miembro para estos atributos:

static PyMemberDef Custom_members[] = {
    {"number", T_INT, offsetof(CustomObject, number), 0,
     "custom number"},
    {NULL}  /* Sentinel */
};

También necesitamos actualizar el manejador tp_init para permitir que solo se pasen las cadenas 3:

static int
Custom_init(CustomObject *self, PyObject *args, PyObject *kwds)
{
    static char *kwlist[] = {"first", "last", "number", NULL};
    PyObject *first = NULL, *last = NULL, *tmp;

    if (!PyArg_ParseTupleAndKeywords(args, kwds, "|UUi", kwlist,
                                     &first, &last,
                                     &self->number))
        return -1;

    if (first) {
        tmp = self->first;
        Py_INCREF(first);
        self->first = first;
        Py_DECREF(tmp);
    }
    if (last) {
        tmp = self->last;
        Py_INCREF(last);
        self->last = last;
        Py_DECREF(tmp);
    }
    return 0;
}

Con estos cambios, podemos asegurar que los miembros primero y último nunca sean NULL, por lo que podemos eliminar las comprobaciones de los valores NULL en casi todos los casos. Esto significa que la mayoría de las llamadas Py_XDECREF() se pueden convertir en llamadas Py_DECREF(). El único lugar donde no podemos cambiar estas llamadas es en la implementación tp_dealloc, donde existe la posibilidad de que la inicialización de estos miembros falle en tp_new.

También cambiamos el nombre de la función de inicialización del módulo y el nombre del módulo en la función de inicialización, como lo hicimos antes, y agregamos una definición adicional al archivo setup.py.

2.4. Apoyo a la recolección de basura cíclica

Python tiene un recolector de basura cíclico (GC) que puede identificar objetos innecesarios incluso cuando sus recuentos de referencia no son cero. Esto puede suceder cuando los objetos están involucrados en ciclos. Por ejemplo, considere:

>>> l = []
>>> l.append(l)
>>> del l

En este ejemplo, creamos una lista que se contiene a sí misma. Cuando lo eliminamos, todavía tiene una referencia de sí mismo. Su recuento de referencia no cae a cero. Afortunadamente, el recolector cíclico de basura de Python finalmente descubrirá que la lista es basura y la liberará.

En la segunda versión del ejemplo Custom, permitimos que cualquier tipo de objeto se almacene en first o last atributos 4. Además, en la segunda y tercera versión, permitimos subclases Custom, y las subclases pueden agregar atributos arbitrarios. Por cualquiera de esos dos motivos, los objetos Custom pueden participar en ciclos:

>>> import custom3
>>> class Derived(custom3.Custom): pass
...
>>> n = Derived()
>>> n.some_attribute = n

Para permitir que una instancia de Custom que participa en un ciclo de referencia sea detectada y recolectada correctamente por el GC cíclico, nuestro tipo Custom necesita llenar dos espacios adicionales y habilitar un indicador que permita estos espacios:

#define PY_SSIZE_T_CLEAN
#include <Python.h>
#include "structmember.h"

typedef struct {
    PyObject_HEAD
    PyObject *first; /* first name */
    PyObject *last;  /* last name */
    int number;
} CustomObject;

static int
Custom_traverse(CustomObject *self, visitproc visit, void *arg)
{
    Py_VISIT(self->first);
    Py_VISIT(self->last);
    return 0;
}

static int
Custom_clear(CustomObject *self)
{
    Py_CLEAR(self->first);
    Py_CLEAR(self->last);
    return 0;
}

static void
Custom_dealloc(CustomObject *self)
{
    PyObject_GC_UnTrack(self);
    Custom_clear(self);
    Py_TYPE(self)->tp_free((PyObject *) self);
}

static PyObject *
Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
{
    CustomObject *self;
    self = (CustomObject *) type->tp_alloc(type, 0);
    if (self != NULL) {
        self->first = PyUnicode_FromString("");
        if (self->first == NULL) {
            Py_DECREF(self);
            return NULL;
        }
        self->last = PyUnicode_FromString("");
        if (self->last == NULL) {
            Py_DECREF(self);
            return NULL;
        }
        self->number = 0;
    }
    return (PyObject *) self;
}

static int
Custom_init(CustomObject *self, PyObject *args, PyObject *kwds)
{
    static char *kwlist[] = {"first", "last", "number", NULL};
    PyObject *first = NULL, *last = NULL, *tmp;

    if (!PyArg_ParseTupleAndKeywords(args, kwds, "|UUi", kwlist,
                                     &first, &last,
                                     &self->number))
        return -1;

    if (first) {
        tmp = self->first;
        Py_INCREF(first);
        self->first = first;
        Py_DECREF(tmp);
    }
    if (last) {
        tmp = self->last;
        Py_INCREF(last);
        self->last = last;
        Py_DECREF(tmp);
    }
    return 0;
}

static PyMemberDef Custom_members[] = {
    {"number", T_INT, offsetof(CustomObject, number), 0,
     "custom number"},
    {NULL}  /* Sentinel */
};

static PyObject *
Custom_getfirst(CustomObject *self, void *closure)
{
    Py_INCREF(self->first);
    return self->first;
}

static int
Custom_setfirst(CustomObject *self, PyObject *value, void *closure)
{
    if (value == NULL) {
        PyErr_SetString(PyExc_TypeError, "Cannot delete the first attribute");
        return -1;
    }
    if (!PyUnicode_Check(value)) {
        PyErr_SetString(PyExc_TypeError,
                        "The first attribute value must be a string");
        return -1;
    }
    Py_INCREF(value);
    Py_CLEAR(self->first);
    self->first = value;
    return 0;
}

static PyObject *
Custom_getlast(CustomObject *self, void *closure)
{
    Py_INCREF(self->last);
    return self->last;
}

static int
Custom_setlast(CustomObject *self, PyObject *value, void *closure)
{
    if (value == NULL) {
        PyErr_SetString(PyExc_TypeError, "Cannot delete the last attribute");
        return -1;
    }
    if (!PyUnicode_Check(value)) {
        PyErr_SetString(PyExc_TypeError,
                        "The last attribute value must be a string");
        return -1;
    }
    Py_INCREF(value);
    Py_CLEAR(self->last);
    self->last = value;
    return 0;
}

static PyGetSetDef Custom_getsetters[] = {
    {"first", (getter) Custom_getfirst, (setter) Custom_setfirst,
     "first name", NULL},
    {"last", (getter) Custom_getlast, (setter) Custom_setlast,
     "last name", NULL},
    {NULL}  /* Sentinel */
};

static PyObject *
Custom_name(CustomObject *self, PyObject *Py_UNUSED(ignored))
{
    return PyUnicode_FromFormat("%S %S", self->first, self->last);
}

static PyMethodDef Custom_methods[] = {
    {"name", (PyCFunction) Custom_name, METH_NOARGS,
     "Return the name, combining the first and last name"
    },
    {NULL}  /* Sentinel */
};

static PyTypeObject CustomType = {
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "custom4.Custom",
    .tp_doc = PyDoc_STR("Custom objects"),
    .tp_basicsize = sizeof(CustomObject),
    .tp_itemsize = 0,
    .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC,
    .tp_new = Custom_new,
    .tp_init = (initproc) Custom_init,
    .tp_dealloc = (destructor) Custom_dealloc,
    .tp_traverse = (traverseproc) Custom_traverse,
    .tp_clear = (inquiry) Custom_clear,
    .tp_members = Custom_members,
    .tp_methods = Custom_methods,
    .tp_getset = Custom_getsetters,
};

static PyModuleDef custommodule = {
    PyModuleDef_HEAD_INIT,
    .m_name = "custom4",
    .m_doc = "Example module that creates an extension type.",
    .m_size = -1,
};

PyMODINIT_FUNC
PyInit_custom4(void)
{
    PyObject *m;
    if (PyType_Ready(&CustomType) < 0)
        return NULL;

    m = PyModule_Create(&custommodule);
    if (m == NULL)
        return NULL;

    Py_INCREF(&CustomType);
    if (PyModule_AddObject(m, "Custom", (PyObject *) &CustomType) < 0) {
        Py_DECREF(&CustomType);
        Py_DECREF(m);
        return NULL;
    }

    return m;
}

Primero, el método transversal permite que el GC cíclico conozca los subobjetos que podrían participar en los ciclos:

static int
Custom_traverse(CustomObject *self, visitproc visit, void *arg)
{
    int vret;
    if (self->first) {
        vret = visit(self->first, arg);
        if (vret != 0)
            return vret;
    }
    if (self->last) {
        vret = visit(self->last, arg);
        if (vret != 0)
            return vret;
    }
    return 0;
}

Para cada subobjeto que puede participar en ciclos, necesitamos llamar a la función visit(), que se pasa al método transversal. La función visit() toma como argumentos el subobjeto y el argumento extra arg pasados al método transversal. Retorna un valor entero que debe retornarse si no es cero.

Python proporciona una macro Py_VISIT() que automatiza las funciones de visita de llamada. Con Py_VISIT(), podemos minimizar la cantidad de repeticiones en Custom_traverse:

static int
Custom_traverse(CustomObject *self, visitproc visit, void *arg)
{
    Py_VISIT(self->first);
    Py_VISIT(self->last);
    return 0;
}

Nota

La implementación tp_traverse debe nombrar sus argumentos exactamente visit y arg para usar Py_VISIT().

En segundo lugar, debemos proporcionar un método para borrar cualquier subobjeto que pueda participar en los ciclos:

static int
Custom_clear(CustomObject *self)
{
    Py_CLEAR(self->first);
    Py_CLEAR(self->last);
    return 0;
}

Observe el uso de la macro Py_CLEAR(). Es la forma recomendada y segura de borrar los atributos de datos de tipos arbitrarios al tiempo que disminuye sus recuentos de referencia. Si tuviera que llamar a Py_XDECREF() en lugar del atributo antes de establecerlo en NULL, existe la posibilidad de que el destructor del atributo vuelva a llamar al código que lee el atributo nuevamente (especialmente si hay un ciclo de referencia).

Nota

Puede emular Py_CLEAR() escribiendo:

PyObject *tmp;
tmp = self->first;
self->first = NULL;
Py_XDECREF(tmp);

Sin embargo, es mucho más fácil y menos propenso a errores usar siempre Py_CLEAR() al eliminar un atributo. ¡No intentes micro-optimizar a expensas de la robustez!

El desasignador Custom_dealloc puede llamar a un código arbitrario al borrar los atributos. Significa que el GC circular se puede activar dentro de la función. Dado que el GC asume que el recuento de referencias no es cero, debemos destrabar el objeto del GC llamando a PyObject_GC_UnTrack() antes de borrar los miembros. Aquí está nuestro reubicador reimplementado usando PyObject_GC_UnTrack() y Custom_clear:

static void
Custom_dealloc(CustomObject *self)
{
    PyObject_GC_UnTrack(self);
    Custom_clear(self);
    Py_TYPE(self)->tp_free((PyObject *) self);
}

Finalmente, agregamos el indicador Py_TPFLAGS_HAVE_GC a los indicadores de clase:

.tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC,

Eso es prácticamente todo. Si hubiéramos escrito controladores personalizados tp_alloc o tp_free, tendríamos que modificarlos para la recolección de basura cíclica. La mayoría de las extensiones usarán las versiones proporcionadas automáticamente.

2.5. Subclases de otros tipos

Es posible crear nuevos tipos de extensión que se derivan de los tipos existentes. Es más fácil heredar de los tipos incorporados, ya que una extensión puede usar fácilmente PyTypeObject que necesita. Puede ser difícil compartir estas estructuras PyTypeObject entre módulos de extensión.

En este ejemplo crearemos un tipo SubList que hereda del tipo incorporado list. El nuevo tipo será completamente compatible con las listas regulares, pero tendrá un método adicional increment() que aumenta un contador interno:

>>> import sublist
>>> s = sublist.SubList(range(3))
>>> s.extend(s)
>>> print(len(s))
6
>>> print(s.increment())
1
>>> print(s.increment())
2

#define PY_SSIZE_T_CLEAN
#include <Python.h>

typedef struct {
    PyListObject list;
    int state;
} SubListObject;

static PyObject *
SubList_increment(SubListObject *self, PyObject *unused)
{
    self->state++;
    return PyLong_FromLong(self->state);
}

static PyMethodDef SubList_methods[] = {
    {"increment", (PyCFunction) SubList_increment, METH_NOARGS,
     PyDoc_STR("increment state counter")},
    {NULL},
};

static int
SubList_init(SubListObject *self, PyObject *args, PyObject *kwds)
{
    if (PyList_Type.tp_init((PyObject *) self, args, kwds) < 0)
        return -1;
    self->state = 0;
    return 0;
}

static PyTypeObject SubListType = {
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "sublist.SubList",
    .tp_doc = PyDoc_STR("SubList objects"),
    .tp_basicsize = sizeof(SubListObject),
    .tp_itemsize = 0,
    .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,
    .tp_init = (initproc) SubList_init,
    .tp_methods = SubList_methods,
};

static PyModuleDef sublistmodule = {
    PyModuleDef_HEAD_INIT,
    .m_name = "sublist",
    .m_doc = "Example module that creates an extension type.",
    .m_size = -1,
};

PyMODINIT_FUNC
PyInit_sublist(void)
{
    PyObject *m;
    SubListType.tp_base = &PyList_Type;
    if (PyType_Ready(&SubListType) < 0)
        return NULL;

    m = PyModule_Create(&sublistmodule);
    if (m == NULL)
        return NULL;

    Py_INCREF(&SubListType);
    if (PyModule_AddObject(m, "SubList", (PyObject *) &SubListType) < 0) {
        Py_DECREF(&SubListType);
        Py_DECREF(m);
        return NULL;
    }

    return m;
}

Como puede ver, el código fuente se parece mucho a los ejemplos Custom en secciones anteriores. Desglosaremos las principales diferencias entre ellos.

typedef struct {
    PyListObject list;
    int state;
} SubListObject;

La diferencia principal para los objetos de tipo derivado es que la estructura de objeto del tipo base debe ser el primer valor. El tipo base ya incluirá PyObject_HEAD() al comienzo de su estructura.

Cuando un objeto Python es una instancia de SubList, su puntero PyObject * se puede convertir de forma segura tanto en PyListObject * como en SubListObject *:

static int
SubList_init(SubListObject *self, PyObject *args, PyObject *kwds)
{
    if (PyList_Type.tp_init((PyObject *) self, args, kwds) < 0)
        return -1;
    self->state = 0;
    return 0;
}

Vemos arriba cómo llamar al método __init__ del tipo base.

Este patrón es importante cuando se escribe un tipo con miembros personalizados tp_new y tp_dealloc. El manejador tp_new no debería crear realmente la memoria para el objeto con su tp_alloc, pero deja que la clase base lo maneje llamando a su propio tp_new.

La estructura PyTypeObject admite a tp_base especificando la clase base concreta del tipo. Debido a problemas de compilación multiplataforma, no puede llenar ese campo directamente con una referencia a PyList_Type; debe hacerse más tarde en la función de inicialización del módulo:

PyMODINIT_FUNC
PyInit_sublist(void)
{
    PyObject* m;
    SubListType.tp_base = &PyList_Type;
    if (PyType_Ready(&SubListType) < 0)
        return NULL;

    m = PyModule_Create(&sublistmodule);
    if (m == NULL)
        return NULL;

    Py_INCREF(&SubListType);
    if (PyModule_AddObject(m, "SubList", (PyObject *) &SubListType) < 0) {
        Py_DECREF(&SubListType);
        Py_DECREF(m);
        return NULL;
    }

    return m;
}

Antes de llamar a PyType_Ready(), la estructura de tipo debe tener el espacio tp_base rellenado. Cuando derivamos un tipo existente, no es necesario completar el tp_alloc ranura con PyType_GenericNew() – la función de asignación del tipo base será heredada.

Después de eso, llamar a PyType_Ready() y agregar el objeto tipo al módulo es lo mismo que con los ejemplos básicos Custom.

Notas al pie

1

Esto es cierto cuando sabemos que el objeto es un tipo básico, como una cadena o un flotador.

2

Nos basamos en esto en el manejador tp_dealloc en este ejemplo, porque nuestro tipo no admite la recolección de basura.

3

Ahora sabemos que el primer y el último miembro son cadenas de caracteres, por lo que quizás podríamos ser menos cuidadosos al disminuir sus recuentos de referencia, sin embargo, aceptamos instancias de subclases de cadenas. A pesar de que la desasignación de cadenas normales no volverá a llamar a nuestros objetos, no podemos garantizar que la desasignación de una instancia de una subclase de cadena de caracteres no vuelva a llamar a nuestros objetos.

4

Además, incluso con nuestros atributos restringidos a instancias de cadenas, el usuario podría pasar subclases arbitrarias str y, por lo tanto, seguir creando ciclos de referencia.

3. Definición de tipos de extensión: temas variados

Esta sección tiene como objetivo dar un vistazo rápido a los diversos métodos de tipo que puede implementar y lo que hacen.

Aquí está la definición de PyTypeObject, con algunos campos solo utilizados en las versiones de depuración omitidas:

typedef struct _typeobject {
    PyObject_VAR_HEAD
    const char *tp_name; /* For printing, in format "<module>.<name>" */
    Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */

    /* Methods to implement standard operations */

    destructor tp_dealloc;
    Py_ssize_t tp_vectorcall_offset;
    getattrfunc tp_getattr;
    setattrfunc tp_setattr;
    PyAsyncMethods *tp_as_async; /* formerly known as tp_compare (Python 2)
                                    or tp_reserved (Python 3) */
    reprfunc tp_repr;

    /* Method suites for standard classes */

    PyNumberMethods *tp_as_number;
    PySequenceMethods *tp_as_sequence;
    PyMappingMethods *tp_as_mapping;

    /* More standard operations (here for binary compatibility) */

    hashfunc tp_hash;
    ternaryfunc tp_call;
    reprfunc tp_str;
    getattrofunc tp_getattro;
    setattrofunc tp_setattro;

    /* Functions to access object as input/output buffer */
    PyBufferProcs *tp_as_buffer;

    /* Flags to define presence of optional/expanded features */
    unsigned long tp_flags;

    const char *tp_doc; /* Documentation string */

    /* call function for all accessible objects */
    traverseproc tp_traverse;

    /* delete references to contained objects */
    inquiry tp_clear;

    /* rich comparisons */
    richcmpfunc tp_richcompare;

    /* weak reference enabler */
    Py_ssize_t tp_weaklistoffset;

    /* Iterators */
    getiterfunc tp_iter;
    iternextfunc tp_iternext;

    /* Attribute descriptor and subclassing stuff */
    struct PyMethodDef *tp_methods;
    struct PyMemberDef *tp_members;
    struct PyGetSetDef *tp_getset;
    struct _typeobject *tp_base;
    PyObject *tp_dict;
    descrgetfunc tp_descr_get;
    descrsetfunc tp_descr_set;
    Py_ssize_t tp_dictoffset;
    initproc tp_init;
    allocfunc tp_alloc;
    newfunc tp_new;
    freefunc tp_free; /* Low-level free-memory routine */
    inquiry tp_is_gc; /* For PyObject_IS_GC */
    PyObject *tp_bases;
    PyObject *tp_mro; /* method resolution order */
    PyObject *tp_cache;
    PyObject *tp_subclasses;
    PyObject *tp_weaklist;
    destructor tp_del;

    /* Type attribute cache version tag. Added in version 2.6 */
    unsigned int tp_version_tag;

    destructor tp_finalize;

} PyTypeObject;

Esos son muchos métodos. Sin embargo, no se preocupe demasiado: si tiene un tipo que desea definir, es muy probable que solo implemente un puñado de estos.

Como probablemente espera ahora, vamos a repasar esto y daremos más información sobre los diversos controladores. No iremos en el orden en que se definen en la estructura, porque hay mucho equipaje histórico que afecta el orden de los campos. A menudo es más fácil encontrar un ejemplo que incluya los campos que necesita y luego cambiar los valores para adaptarlos a su nuevo tipo.

const char *tp_name; /* For printing */

El nombre del tipo – como se mencionó en el capítulo anterior, aparecerá en varios lugares, casi por completo para fines de diagnóstico. ¡Intente elegir algo que sea útil en tal situación!

Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */

Estos campos le dicen al tiempo de ejecución cuánta memoria asignar cuando se crean nuevos objetos de este tipo. Python tiene algún soporte incorporado para estructuras de longitud variable (piense: cadenas, tuplas) que es donde entra el campo tp_itemsize. Esto se tratará más adelante.

const char *tp_doc;

Aquí puede poner una cadena de caracteres (o su dirección) que desea que se retorne cuando el script de Python haga referencia a obj.__doc__ para recuperar el docstring.

Ahora llegamos a los métodos de tipo básicos: los que implementarán la mayoría de los tipos de extensión.

3.1. Finalización y desasignación

destructor tp_dealloc;

Se llama a esta función cuando el recuento de referencia de la instancia de su tipo se reduce a cero y el intérprete de Python quiere reclamarlo. Si su tipo tiene memoria para liberar u otra limpieza para realizar, puede ponerla aquí. El objeto en sí mismo necesita ser liberado aquí también. Aquí hay un ejemplo de esta función:

static void
newdatatype_dealloc(newdatatypeobject *obj)
{
    free(obj->obj_UnderlyingDatatypePtr);
    Py_TYPE(obj)->tp_free((PyObject *)obj);
}

If your type supports garbage collection, the destructor should call PyObject_GC_UnTrack() before clearing any member fields:

static void
newdatatype_dealloc(newdatatypeobject *obj)
{
    PyObject_GC_UnTrack(obj);
    Py_CLEAR(obj->other_obj);
    ...
    Py_TYPE(obj)->tp_free((PyObject *)obj);
}

Un requisito importante de la función desasignador es que deja solo las excepciones pendientes. Esto es importante ya que los desasignadores se llaman con frecuencia cuando el intérprete desenrolla la pila de Python; cuando la pila se desenrolla debido a una excepción (en lugar de retornos normales), no se hace nada para proteger a los desasignadores de memoria (deallocator) de ver que ya se ha establecido una excepción. Cualquier acción que realice un desasignador que pueda hacer que se ejecute código Python adicional puede detectar que se ha establecido una excepción. Esto puede conducir a errores engañosos del intérprete. La forma correcta de protegerse contra esto es guardar una excepción pendiente antes de realizar la acción insegura y restaurarla cuando haya terminado. Esto se puede hacer usando las funciones PyErr_Fetch() y PyErr_Restore():

static void
my_dealloc(PyObject *obj)
{
    MyObject *self = (MyObject *) obj;
    PyObject *cbresult;

    if (self->my_callback != NULL) {
        PyObject *err_type, *err_value, *err_traceback;

        /* This saves the current exception state */
        PyErr_Fetch(&err_type, &err_value, &err_traceback);

        cbresult = PyObject_CallNoArgs(self->my_callback);
        if (cbresult == NULL)
            PyErr_WriteUnraisable(self->my_callback);
        else
            Py_DECREF(cbresult);

        /* This restores the saved exception state */
        PyErr_Restore(err_type, err_value, err_traceback);

        Py_DECREF(self->my_callback);
    }
    Py_TYPE(obj)->tp_free((PyObject*)self);
}

Nota

Existen limitaciones para lo que puede hacer de manera segura en una función de desasignación. Primero, si su tipo admite la recolección de basura (usando tp_traverse o tp_clear), algunos de los miembros del objeto pueden haber sido borrados o finalizados por el time tp_dealloc es llamado. Segundo, en tp_dealloc, su objeto está en un estado inestable: su recuento de referencia es igual a cero. Cualquier llamada a un objeto o API no trivial (como en el ejemplo anterior) podría terminar llamando tp_dealloc nuevamente, causando una doble liberación y un bloqueo.

Comenzando con Python 3.4, se recomienda no poner ningún código de finalización complejo en tp_dealloc, y en su lugar use el nuevo método de tipo tp_finalize.

Ver también

PEP 442 [https://www.python.org/dev/peps/pep-0442] explica el nuevo esquema de finalización.

3.2. Presentación de Objetos

En Python, hay dos formas de generar una representación textual de un objeto: la función repr(), y la función str(). (La función print() solo llama a str().) Estos controladores son opcionales.

reprfunc tp_repr;
reprfunc tp_str;

El manejador tp_repr debe retornar un objeto de cadena que contenga una representación de la instancia para la que se llama. Aquí hay un ejemplo simple:

static PyObject *
newdatatype_repr(newdatatypeobject * obj)
{
    return PyUnicode_FromFormat("Repr-ified_newdatatype{{size:%d}}",
                                obj->obj_UnderlyingDatatypePtr->size);
}

Si no se especifica tp_repr, el intérprete proporcionará una representación que utiliza los tipos tp_name y un valor de identificación único para el objeto.

El manejador tp_str es para str() lo que el manejador tp_repr descrito arriba es para repr(); es decir, se llama cuando el código Python llama str() en una instancia de su objeto. Su implementación es muy similar a la función tp_repr, pero la cadena resultante está destinada al consumo humano. Si tp_str no se especifica, en su lugar se utiliza el controlador tp_repr.

Aquí hay un ejemplo simple:

static PyObject *
newdatatype_str(newdatatypeobject * obj)
{
    return PyUnicode_FromFormat("Stringified_newdatatype{{size:%d}}",
                                obj->obj_UnderlyingDatatypePtr->size);
}

3.3. Gestión de atributos

Para cada objeto que puede soportar atributos, el tipo correspondiente debe proporcionar las funciones que controlan cómo se resuelven los atributos. Es necesario que haya una función que pueda recuperar atributos (si hay alguna definida), y otra para establecer atributos (si se permite establecer atributos). La eliminación de un atributo es un caso especial, para el cual el nuevo valor pasado al controlador es NULL.

Python admite dos pares de controladores de atributos; un tipo que admite atributos solo necesita implementar las funciones para un par. La diferencia es que un par toma el nombre del atributo como a char*, mientras que el otro acepta un PyObject*. Cada tipo puede usar el par que tenga más sentido para la conveniencia de la implementación.

getattrfunc  tp_getattr;        /* char * version */
setattrfunc  tp_setattr;
/* ... */
getattrofunc tp_getattro;       /* PyObject * version */
setattrofunc tp_setattro;

Si acceder a los atributos de un objeto es siempre una operación simple (esto se explicará en breve), existen implementaciones genéricas que se pueden utilizar para proporcionar la versión PyObject* de las funciones de gestión de atributos. La necesidad real de controladores de atributos específicos de tipo desapareció casi por completo a partir de Python 2.2, aunque hay muchos ejemplos que no se han actualizado para utilizar algunos de los nuevos mecanismos genéricos que están disponibles.

3.3.1. Gestión de atributos genéricos

La mayoría de los tipos de extensión solo usan atributos simple. Entonces, ¿qué hace que los atributos sean simples? Solo hay un par de condiciones que se deben cumplir:

El nombre de los atributos debe ser conocido cuando PyType_Ready() es llamado.

No se necesita un procesamiento especial para registrar que un atributo se buscó o se configuró, ni se deben tomar acciones basadas en el valor.

Tenga en cuenta que esta lista no impone restricciones a los valores de los atributos, cuándo se calculan los valores o cómo se almacenan los datos relevantes.

Cuando se llama a PyType_Ready(), utiliza tres tablas a las que hace referencia el objeto de tipo para crear descriptor que se colocan en el diccionario del objeto de tipo. Cada descriptor controla el acceso a un atributo del objeto de instancia. Cada una de las tablas es opcional; si los tres son NULL, las instancias del tipo solo tendrán atributos que se heredan de su tipo base, y deberían dejar tp_getattro y los campos tp_setattro NULL también, permitiendo que el tipo base maneje los atributos.

Las tablas se declaran como tres campos del tipo objeto:

struct PyMethodDef *tp_methods;
struct PyMemberDef *tp_members;
struct PyGetSetDef *tp_getset;

Si tp_methods no es NULL, debe referirse a un arreglo de estructuras PyMethodDef. Cada entrada en la tabla es una instancia de esta estructura:

typedef struct PyMethodDef {
    const char  *ml_name;       /* method name */
    PyCFunction  ml_meth;       /* implementation function */
    int          ml_flags;      /* flags */
    const char  *ml_doc;        /* docstring */
} PyMethodDef;

Se debe definir una entrada para cada método proporcionado por el tipo; No se necesitan entradas para los métodos heredados de un tipo base. Se necesita una entrada adicional al final; es un centinela el que marca el final del arreglo. El campo ml_name del centinela debe ser NULL.

La segunda tabla se utiliza para definir atributos que se asignan directamente a los datos almacenados en la instancia. Se admite una variedad de tipos C primitivos, y el acceso puede ser de solo lectura o lectura-escritura. Las estructuras en la tabla se definen como:

typedef struct PyMemberDef {
    const char *name;
    int         type;
    int         offset;
    int         flags;
    const char *doc;
} PyMemberDef;

Para cada entrada en la tabla, se construirá un descriptor y se agregará al tipo que podrá extraer un valor de la estructura de la instancia. El campo type debe contener uno de los códigos de tipo definidos en el encabezado structmember.h; el valor se usará para determinar cómo convertir los valores de Python hacia y desde los valores de C. El campo flags se usa para almacenar flags que controlan cómo se puede acceder al atributo.

Las siguientes constantes de flag se definen en structmember.h; se pueden combinar usando OR bit a bit (bitwise-OR).

Constante

Significado

READONLY

Nunca escribible.

READ_RESTRICTED

No legible en modo restringido.

WRITE_RESTRICTED

No se puede escribir en modo restringido.

RESTRICTED

No se puede leer ni escribir en modo restringido.

Una ventaja interesante de usar la tabla tp_members para crear descriptores que se usan en tiempo de ejecución es que cualquier atributo definido de esta manera puede tener un docstring asociada simplemente al proporcionar el texto en la tabla. Una aplicación puede usar la API de introspección para recuperar el descriptor del objeto de clase y obtener el docstring utilizando su atributo __doc__.

Al igual que con la tabla tp_methods, se requiere una entrada de centinela con un valor name de NULL.

3.3.2. Gestión de atributos específicos de tipo

Para simplificar, aquí solo se demostrará la versión char *; el tipo de parámetro de nombre es la única diferencia entre las variaciones de la interfaz char* y PyObject*. Este ejemplo efectivamente hace lo mismo que el ejemplo genérico anterior, pero no utiliza el soporte genérico agregado en Python 2.2. Explica cómo se llaman las funciones del controlador, de modo que si necesita ampliar su funcionalidad, comprenderá lo que debe hacerse.

Se llama al manejador tp_getattr cuando el objeto requiere una búsqueda de atributo. Se llama en las mismas situaciones donde se llamaría el método __getattr__() de una clase.

Aquí hay un ejemplo:

static PyObject *
newdatatype_getattr(newdatatypeobject *obj, char *name)
{
    if (strcmp(name, "data") == 0)
    {
        return PyLong_FromLong(obj->data);
    }

    PyErr_Format(PyExc_AttributeError,
                 "'%.50s' object has no attribute '%.400s'",
                 tp->tp_name, name);
    return NULL;
}

Se llama al manejador tp_setattr cuando se llama al método __setattr__() o __delattr__() de una instancia de clase. Cuando se debe eliminar un atributo, el tercer parámetro será NULL. Aquí hay un ejemplo que simplemente plantea una excepción; si esto fuera realmente todo lo que deseaba, el controlador tp_setattr debería establecerse en NULL.

static int
newdatatype_setattr(newdatatypeobject *obj, char *name, PyObject *v)
{
    PyErr_Format(PyExc_RuntimeError, "Read-only attribute: %s", name);
    return -1;
}

3.4. Comparación de Objetos

richcmpfunc tp_richcompare;

Se llama al manejador tp_richcompare cuando se necesitan comparaciones. Es análogo a métodos de comparación ricos, como __lt__(), y también llamado por PyObject_RichCompare() y PyObject_RichCompareBool().

This function is called with two Python objects and the operator as arguments, where the operator is one of Py_EQ, Py_NE, Py_LE, Py_GE, Py_LT or Py_GT. It should compare the two objects with respect to the specified operator and return Py_True or Py_False if the comparison is successful, Py_NotImplemented to indicate that comparison is not implemented and the other object’s comparison method should be tried, or NULL if an exception was set.

Aquí hay una implementación de muestra, para un tipo de datos que se considera igual si el tamaño de un puntero interno es igual:

static PyObject *
newdatatype_richcmp(PyObject *obj1, PyObject *obj2, int op)
{
    PyObject *result;
    int c, size1, size2;

    /* code to make sure that both arguments are of type
       newdatatype omitted */

    size1 = obj1->obj_UnderlyingDatatypePtr->size;
    size2 = obj2->obj_UnderlyingDatatypePtr->size;

    switch (op) {
    case Py_LT: c = size1 <  size2; break;
    case Py_LE: c = size1 <= size2; break;
    case Py_EQ: c = size1 == size2; break;
    case Py_NE: c = size1 != size2; break;
    case Py_GT: c = size1 >  size2; break;
    case Py_GE: c = size1 >= size2; break;
    }
    result = c ? Py_True : Py_False;
    Py_INCREF(result);
    return result;
 }

3.5. Soporte de protocolo abstracto

Python admite una variedad de protocolos abstractos; las interfaces específicas proporcionadas para usar estas interfaces están documentadas en Capa de objetos abstractos.

Varias de estas interfaces abstractas se definieron temprano en el desarrollo de la implementación de Python. En particular, los protocolos de número, mapeo y secuencia han sido parte de Python desde el principio. Se han agregado otros protocolos con el tiempo. Para los protocolos que dependen de varias rutinas de controlador de la implementación de tipo, los protocolos más antiguos se han definido como bloques opcionales de controladores a los que hace referencia el objeto de tipo. Para los protocolos más nuevos, hay espacios adicionales en el objeto de tipo principal, con un bit de marca que se establece para indicar que los espacios están presentes y el intérprete debe verificarlos. (El bit de indicador no indica que los valores de intervalo no son NULL. El indicador puede establecerse para indicar la presencia de un intervalo, pero un intervalo aún puede estar vacío.):

PyNumberMethods   *tp_as_number;
PySequenceMethods *tp_as_sequence;
PyMappingMethods  *tp_as_mapping;

Si desea que su objeto pueda actuar como un número, una secuencia o un objeto de mapeo, entonces coloca la dirección de una estructura que implementa el tipo C PyNumberMethods, PySequenceMethods, o PyMappingMethods, respectivamente. Depende de usted completar esta estructura con los valores apropiados. Puede encontrar ejemplos del uso de cada uno de estos en el directorio Objects de la distribución fuente de Python.

hashfunc tp_hash;

Esta función, si elige proporcionarla, debería retornar un número hash para una instancia de su tipo de datos. Aquí hay un ejemplo simple:

static Py_hash_t
newdatatype_hash(newdatatypeobject *obj)
{
    Py_hash_t result;
    result = obj->some_size + 32767 * obj->some_number;
    if (result == -1)
       result = -2;
    return result;
}

Py_hash_t es un tipo entero con signo con un ancho que varia dependiendo de la plataforma.retornar -1 de tp_hash indica un error, por lo que debe tener cuidado de evitar retornarlo cuando el cálculo de hash sea exitoso, como se vio anteriormente.

ternaryfunc tp_call;

Esta función se llama cuando una instancia de su tipo de datos se «llama», por ejemplo, si obj1 es una instancia de su tipo de datos y el script de Python contiene obj1('hello'), el controlador tp_call se invoca.

Esta función toma tres argumentos:

self es la instancia del tipo de datos que es el sujeto de la llamada. Si la llamada es obj1('hola'), entonces self es obj1.

args es una tupla que contiene los argumentos de la llamada. Puede usar PyArg_ParseTuple() para extraer los argumentos.

kwds es un diccionario de argumentos de palabras clave que se pasaron. Si no es NULL y admite argumentos de palabras clave, use PyArg_ParseTupleAndKeywords() para extraer los argumentos. Si no desea admitir argumentos de palabras clave y esto no es NULL, genere un TypeError con un mensaje que indique que los argumentos de palabras clave no son compatibles.

Aquí hay una implementación de juguete tp_call:

static PyObject *
newdatatype_call(newdatatypeobject *self, PyObject *args, PyObject *kwds)
{
    PyObject *result;
    const char *arg1;
    const char *arg2;
    const char *arg3;

    if (!PyArg_ParseTuple(args, "sss:call", &arg1, &arg2, &arg3)) {
        return NULL;
    }
    result = PyUnicode_FromFormat(
        "Returning -- value: [%d] arg1: [%s] arg2: [%s] arg3: [%s]\n",
        obj->obj_UnderlyingDatatypePtr->size,
        arg1, arg2, arg3);
    return result;
}

/* Iterators */
getiterfunc tp_iter;
iternextfunc tp_iternext;

Estas funciones proporcionan soporte para el protocolo iterador. Ambos manejadores toman exactamente un parámetro, la instancia para la que están siendo llamados, y retornan una nueva referencia. En el caso de un error, deben establecer una excepción y retornar NULL. tp_iter corresponde al método Python __iter__(), mientras que tp_iternext corresponde al método Python __next__().

Cualquier objeto iterable debe implementar el manejador tp_iter, que debe retornar un objeto iterator. Aquí se aplican las mismas pautas que para las clases de Python:

Para colecciones (como listas y tuplas) que pueden admitir múltiples iteradores independientes, cada llamada debe crear y retornar un nuevo iterador a tp_iter.

Los objetos que solo se pueden iterar una vez (generalmente debido a los efectos secundarios de la iteración, como los objetos de archivo) pueden implementar tp_iter retornando una nueva referencia a ellos mismos y, por lo tanto, también deben implementar el manejador tp_iternext.

Cualquier objeto iterator debe implementar tanto tp_iter como tp_iternext. El manejador de un iterador tp_iter debería retornar una nueva referencia al iterador. Su controlador tp_iternext debería retornar una nueva referencia al siguiente objeto en la iteración, si hay uno. Si la iteración ha llegado al final, tp_iternext puede retornar NULL sin establecer una excepción, o puede establecer StopIteration además para retornar NULL; evitar la excepción puede producir un rendimiento ligeramente mejor. Si se produce un error real, tp_iternext siempre debe establecer una excepción y retornar NULL.

3.6. Soporte de referencia débil

Uno de los objetivos de la implementación de referencia débil de Python es permitir que cualquier tipo participe en el mecanismo de referencia débil sin incurrir en la sobrecarga de objetos críticos para el rendimiento (como los números).

Ver también

Documentación para el módulo weakref.

Para que un objeto sea débilmente referenciable, el tipo de extensión debe hacer dos cosas:

Incluya el campo a PyObject* en la estructura del objeto C dedicada al mecanismo de referencia débil. El constructor del objeto debe dejarlo NULL (que es automático cuando se usa el valor predeterminado tp_alloc).

Establezca el miembro de tipo tp_weaklistoffset en el desplazamiento del campo mencionado anteriormente en la estructura del objeto C, para que el intérprete sepa cómo acceder y modificar ese campo.

Concretamente, así es como una estructura de objeto trivial se aumentaría con el campo requerido:

typedef struct {
    PyObject_HEAD
    PyObject *weakreflist;  /* List of weak references */
} TrivialObject;

Y el miembro correspondiente en el objeto de tipo declarado estáticamente:

static PyTypeObject TrivialType = {
    PyVarObject_HEAD_INIT(NULL, 0)
    /* ... other members omitted for brevity ... */
    .tp_weaklistoffset = offsetof(TrivialObject, weakreflist),
};

La única adición adicional es que tp_dealloc necesita borrar cualquier referencia débil (llamando a PyObject_ClearWeakRefs()) si el campo no es NULL

static void
Trivial_dealloc(TrivialObject *self)
{
    /* Clear weakrefs first before calling any destructors */
    if (self->weakreflist != NULL)
        PyObject_ClearWeakRefs((PyObject *) self);
    /* ... remainder of destruction code omitted for brevity ... */
    Py_TYPE(self)->tp_free((PyObject *) self);
}

3.7. Más Sugerencias

Para aprender a implementar cualquier método específico para su nuevo tipo de datos, obtenga el código fuente CPython. Vaya al directorio: file:Objects, luego busque en los archivos fuente C tp_ más la función que desee (por ejemplo, tp_richcompare). Encontrará ejemplos de la función que desea implementar.

Cuando necesite verificar que un objeto es una instancia concreta del tipo que está implementando, use la función PyObject_TypeCheck(). Una muestra de su uso podría ser algo como lo siguiente:

if (!PyObject_TypeCheck(some_object, &MyType)) {
    PyErr_SetString(PyExc_TypeError, "arg #1 not a mything");
    return NULL;
}

Ver también

Descargue las versiones de origen de CPython.

https://www.python.org/downloads/source/

El proyecto CPython en GitHub, donde se desarrolla el código fuente de CPython.

https://github.com/python/cpython

4. Construyendo Extensiones C y C++

Una extensión C para CPython es una biblioteca compartida (por ejemplo, un archivo .so en Linux, .pyd en Windows), que exporta una función de inicialización.

Para que sea importable, la biblioteca compartida debe estar disponible en PYTHONPATH, y debe tener el nombre del módulo, con una extensión adecuada. Cuando se usan distutils, el nombre de archivo correcto se genera automáticamente.

La función de inicialización tiene la firma:

PyObject* PyInit_modulename(void)

Retorna un módulo completamente inicializado o una instancia PyModuleDef. Ver Inicializando módulos en C para más detalles.

Para los módulos con nombres solo ASCII, la función debe llamarse PyInit_<modulename>, con <modulename> reemplazado por el nombre del módulo. Cuando se usa Inicialización multifase, se permiten nombres de módulos que no sean ASCII. En este caso, el nombre de la función de inicialización es PyInitU_<modulename>, con <modulename> codificado usando la codificación punycode de Python con guiones reemplazados por guiones bajos. En Python:

def initfunc_name(name):
    try:
        suffix = b'_' + name.encode('ascii')
    except UnicodeEncodeError:
        suffix = b'U_' + name.encode('punycode').replace(b'-', b'_')
    return b'PyInit' + suffix

Es posible exportar múltiples módulos desde una única biblioteca compartida definiendo múltiples funciones de inicialización. Sin embargo, importarlos requiere el uso de enlaces simbólicos o un importador personalizado, porque de forma predeterminada solo se encuentra la función correspondiente al nombre del archivo. Consulte la sección «Múltiples módulos en una biblioteca» en PEP 489 [https://www.python.org/dev/peps/pep-0489] para más detalles.

4.1. Construyendo Extensiones C y C++ con distutils

Los módulos de extensión se pueden construir utilizando distutils, que se incluye en Python. Dado que distutils también admite la creación de paquetes binarios, los usuarios no necesitan necesariamente un compilador y distutils para instalar la extensión.

Un paquete distutils contiene un script de controlador, setup.py. Este es un archivo Python simple, que, en el caso más simple, podría verse así:

from distutils.core import setup, Extension

module1 = Extension('demo',
                    sources = ['demo.c'])

setup (name = 'PackageName',
       version = '1.0',
       description = 'This is a demo package',
       ext_modules = [module1])

Con esto setup.py, y un archivo demo.c, ejecutando:

python setup.py build

compilará demo.c, y producirá un módulo de extensión llamado demo en el directorio build. Dependiendo del sistema, el archivo del módulo terminará en un subdirectorio build/lib.system, y puede tener un nombre como demo.so o demo.pyd.

En setup.py, toda la ejecución se realiza llamando a la función setup. Esto toma un número variable de argumentos de palabras clave, de los cuales el ejemplo anterior usa solo un subconjunto. Específicamente, el ejemplo especifica metainformación para construir paquetes, y especifica el contenido del paquete. Normalmente, un paquete contendrá módulos adicionales, como módulos fuente Python, documentación, subpaquetes, etc. Consulte la documentación de distutils en Distribución de módulos de Python (versión heredada) para obtener más información sobre las características de distutils; Esta sección explica la construcción de módulos de extensión solamente.

Es común precalcular argumentos para setup(), para estructurar mejor el script del controlador. En el ejemplo anterior, el argumento ext_modules para setup() es una lista de módulos de extensión, cada uno de los cuales es una instancia de Extension . En el ejemplo, la instancia define una extensión llamada demo que se construye compilando un solo archivo fuente demo.c.

En muchos casos, construir una extensión es más complejo, ya que es posible que se necesiten preprocesadores adicionales y bibliotecas. Esto se demuestra en el siguiente ejemplo.

from distutils.core import setup, Extension

module1 = Extension('demo',
                    define_macros = [('MAJOR_VERSION', '1'),
                                     ('MINOR_VERSION', '0')],
                    include_dirs = ['/usr/local/include'],
                    libraries = ['tcl83'],
                    library_dirs = ['/usr/local/lib'],
                    sources = ['demo.c'])

setup (name = 'PackageName',
       version = '1.0',
       description = 'This is a demo package',
       author = 'Martin v. Loewis',
       author_email = 'martin@v.loewis.de',
       url = 'https://docs.python.org/extending/building',
       long_description = '''
This is really just a demo package.
''',
       ext_modules = [module1])

En este ejemplo, se llama a setup() con metainformación adicional, que se recomienda cuando se deben construir paquetes de distribución. Para la extensión en sí, especifica las definiciones de preprocesador, incluye directorios, directorios de biblioteca y bibliotecas. Dependiendo del compilador, distutils pasa esta información de diferentes maneras al compilador. Por ejemplo, en Unix, esto puede resultar en los comandos de compilación:

gcc -DNDEBUG -g -O3 -Wall -Wstrict-prototypes -fPIC -DMAJOR_VERSION=1 -DMINOR_VERSION=0 -I/usr/local/include -I/usr/local/include/python2.2 -c demo.c -o build/temp.linux-i686-2.2/demo.o

gcc -shared build/temp.linux-i686-2.2/demo.o -L/usr/local/lib -ltcl83 -o build/lib.linux-i686-2.2/demo.so

Estas líneas son solo para fines de demostración; Los usuarios de distutils deben confiar en que distutils obtiene las invocaciones correctas.

4.2. Distribuyendo sus módulos de extensión

Cuando una extensión se ha creado correctamente, hay tres formas de usarla.

Los usuarios finales generalmente querrán instalar el módulo, lo hacen ejecutando:

python setup.py install

Los mantenedores de módulos deben producir paquetes fuente; para hacerlo, ejecutan:

python setup.py sdist

En algunos casos, se deben incluir archivos adicionales en una distribución de origen; esto se hace a través de un archivo MANIFEST.in; ver Especificar los archivos a distribuir para más detalles.

Si la distribución de origen se ha creado correctamente, los encargados del mantenimiento también pueden crear distribuciones binarias. Dependiendo de la plataforma, se puede usar uno de los siguientes comandos para hacerlo.:

python setup.py bdist_wininst
python setup.py bdist_rpm
python setup.py bdist_dumb

5. Creación de extensiones C y C++ en Windows

Este capítulo explica brevemente cómo crear un módulo de extensión de Windows para Python usando Microsoft Visual C++, y sigue con información de fondo más detallada sobre cómo funciona. El material explicativo es útil tanto para el programador de Windows que está aprendiendo a construir extensiones de Python como para el programador de Unix interesado en producir software que se pueda construir con éxito tanto en Unix como en Windows.

Se alienta a los autores de módulos a utilizar el enfoque distutils para construir módulos de extensión, en lugar del descrito en esta sección. Aún necesitará el compilador de C que se utilizó para construir Python; típicamente Microsoft Visual C++.

Nota

Este capítulo menciona varios nombres de archivo que incluyen un número de versión codificado de Python. Estos nombres de archivo se representan con el número de versión que se muestra como XY; en la práctica, 'X' será el número de versión principal y 'Y' será el número de versión menor de la versión de Python con la que está trabajando. Por ejemplo, si está utilizando Python 2.2.1, XY en realidad será 22.

5.1. Un enfoque de libro de cocina

Hay dos enfoques para construir módulos de extensión en Windows, al igual que en Unix: use el paquete distutils para controlar el proceso de construcción, o haga las cosas manualmente. El enfoque distutils funciona bien para la mayoría de las extensiones; La documentación sobre el uso de distutils para compilar y empaquetar módulos de extensión está disponible en Distribución de módulos de Python (versión heredada). Si encuentra que realmente necesita hacer las cosas manualmente, puede ser instructivo estudiar el archivo del proyecto para el módulo de biblioteca estándar winsound [https://github.com/python/cpython/tree/3.9/PCbuild/winsound.vcxproj].

5.2. Diferencias entre Unix y Windows

Unix y Windows usan paradigmas completamente diferentes para la carga de código en tiempo de ejecución. Antes de intentar construir un módulo que se pueda cargar dinámicamente, tenga en cuenta cómo funciona su sistema.

En Unix, un archivo de objeto compartido (.so) contiene código para ser utilizado por el programa, y también los nombres de funciones y datos que espera encontrar en el programa. Cuando el archivo se une al programa, todas las referencias a esas funciones y datos en el código del archivo se cambian para apuntar a las ubicaciones reales en el programa donde las funciones y los datos se colocan en la memoria. Esto es básicamente una operación de enlace.

En Windows, un archivo de biblioteca de enlace dinámico (.dll) no tiene referencias colgantes. En cambio, un acceso a funciones o datos pasa por una tabla de búsqueda. Por lo tanto, el código DLL no tiene que repararse en tiempo de ejecución para referirse a la memoria del programa; en cambio, el código ya usa la tabla de búsqueda de la DLL, y la tabla de búsqueda se modifica en tiempo de ejecución para apuntar a las funciones y los datos.

En Unix, solo hay un tipo de archivo de biblioteca (.a) que contiene código de varios archivos de objeto (.o). Durante el paso de enlace para crear un archivo de objeto compartido (.so), el enlazador puede encontrar que no sabe dónde se define un identificador. El enlazador lo buscará en los archivos de objetos en las bibliotecas; si lo encuentra, incluirá todo el código de ese archivo de objeto.

En Windows, hay dos tipos de biblioteca, una biblioteca estática y una biblioteca de importación (ambas llamadas .lib). Una biblioteca estática es como un archivo Unix .a; Contiene código para ser incluido según sea necesario. Una biblioteca de importación se usa básicamente solo para asegurarle al enlazador que cierto identificador es legal y estará presente en el programa cuando se cargue la DLL. Por lo tanto, el enlazador utiliza la información de la biblioteca de importación para crear la tabla de búsqueda para usar identificadores que no están incluidos en la DLL. Cuando se vincula una aplicación o una DLL, se puede generar una biblioteca de importación, que deberá usarse para todas las DLL futuras que dependan de los símbolos en la aplicación o DLL.

Suponga que está creando dos módulos de carga dinámica, B y C, que deberían compartir otro bloque de código A. En Unix, no pasaría A.a al enlazador para B.so y C.so; eso haría que se incluyera dos veces, de modo que B y C tengan cada uno su propia copia. En Windows, compilar A.dll también compilará A.lib. Usted si pasa A.lib al enlazador para B y C. A.lib no contiene código; solo contiene información que se usará en tiempo de ejecución para acceder al código de A.

En Windows, usar una biblioteca de importación es como usar importar spam; le da acceso a los nombres de spam, pero no crea una copia separada. En Unix, vincular con una biblioteca es más como from spam import*; crea una copia separada.

5.3. Usar DLL en la práctica

Windows Python is built in Microsoft Visual C++; using other compilers may or may not work. The rest of this section is MSVC++ specific.

Al crear archivos DLL en Windows, debe pasar pythonXY.lib al enlazador. Para construir dos DLL, spam y ni (que usa funciones C que se encuentran en el spam), puede usar estos comandos:

cl /LD /I/python/include spam.c ../libs/pythonXY.lib
cl /LD /I/python/include ni.c spam.lib ../libs/pythonXY.lib

El primer comando creó tres archivos: spam.obj, spam.dll y spam.lib. Spam.dll no contiene ninguna función de Python (como PyArg_ParseTuple()), pero sabe cómo encontrar el código de Python gracias a pythonXY.lib.

El segundo comando creó ni.dll (y .obj y .lib), que sabe cómo encontrar las funciones necesarias del spam, y también del ejecutable de Python.

No todos los identificadores se exportan a la tabla de búsqueda. Si desea que cualquier otro módulo (incluido Python) pueda ver sus identificadores, debe decir _declspec(dllexport), como en void _declspec(dllexport) initspam(void) o PyObject_declspec(dllexport) *NiGetSpamData(void).

Developer Studio incluirá muchas bibliotecas de importación que realmente no necesita, agregando aproximadamente 100K a su ejecutable. Para deshacerse de ellos, use el cuadro de diálogo Configuración del proyecto, pestaña Enlace, para especificar ignorar las bibliotecas predeterminadas. Agregue el archivo correcto msvcrtxx.lib a la lista de bibliotecas.

1. Incrustando Python en Otra Aplicación

Los capítulos anteriores discutieron cómo extender Python, es decir, cómo extender la funcionalidad de Python al adjuntarle una biblioteca de funciones C. También es posible hacerlo al revés: enriquezca su aplicación C/C++ incrustando Python en ella. La incrustación proporciona a su aplicación la capacidad de implementar parte de la funcionalidad de su aplicación en Python en lugar de C o C++. Esto se puede usar para muchos propósitos; Un ejemplo sería permitir a los usuarios adaptar la aplicación a sus necesidades escribiendo algunos scripts en Python. También puede usarlo usted mismo si parte de la funcionalidad se puede escribir en Python más fácilmente.

Incrustar Python es similar a extenderlo, pero no del todo. La diferencia es que cuando extiende Python, el programa principal de la aplicación sigue siendo el intérprete de Python, mientras que si incrusta Python, el programa principal puede no tener nada que ver con Python — en cambio, algunas partes de la aplicación ocasionalmente llaman al Intérprete de Python para ejecutar algún código de Python.

Entonces, si está incrustando Python, está proporcionando su propio programa principal. Una de las cosas que tiene que hacer este programa principal es inicializar el intérprete de Python. Como mínimo, debe llamar a la función Py_Initialize(). Hay llamadas opcionales para pasar argumentos de línea de comandos a Python. Luego, puede llamar al intérprete desde cualquier parte de la aplicación.

Hay varias formas diferentes de llamar al intérprete: puede pasar una cadena que contiene declaraciones de Python a PyRun_SimpleString(), o puede pasar un puntero de archivo estándar y un nombre de archivo (solo para identificación en mensajes de error) a PyRun_SimpleFile(). También puede llamar a las operaciones de nivel inferior descritas en los capítulos anteriores para construir y usar objetos de Python.

Ver también

Manual de referencia de la API en C de Python

Los detalles de la interfaz C de Python se dan en este manual. Una gran cantidad de información necesaria se puede encontrar aquí.

1.1. Incrustación de muy alto nivel

La forma más simple de incrustar Python es el uso de la interfaz de muy alto nivel. Esta interfaz está diseñada para ejecutar un script de Python sin necesidad de interactuar directamente con la aplicación. Esto puede usarse, por ejemplo, para realizar alguna operación en un archivo.

#define PY_SSIZE_T_CLEAN
#include <Python.h>

int
main(int argc, char *argv[])
{
    wchar_t *program = Py_DecodeLocale(argv[0], NULL);
    if (program == NULL) {
        fprintf(stderr, "Fatal error: cannot decode argv[0]\n");
        exit(1);
    }
    Py_SetProgramName(program);  /* optional but recommended */
    Py_Initialize();
    PyRun_SimpleString("from time import time,ctime\n"
                       "print('Today is', ctime(time()))\n");
    if (Py_FinalizeEx() < 0) {
        exit(120);
    }
    PyMem_RawFree(program);
    return 0;
}

La función Py_SetProgramName() debe llamarse antes de Py_Initialize() para informar al intérprete sobre las rutas a las bibliotecas de tiempo de ejecución de Python. A continuación, el intérprete de Python se inicializa con Py_Initialize(), seguido de la ejecución de un script Python codificado que imprime la fecha y la hora. Luego, la llamada Py_FinalizeEx() cierra el intérprete, seguido por el final del programa. En un programa real, es posible que desee obtener el script de Python de otra fuente, tal vez una rutina de editor de texto, un archivo o una base de datos. Obtener el código Python de un archivo se puede hacer mejor usando la función PyRun_SimpleFile(), que le ahorra la molestia de asignar espacio de memoria y cargar el contenido del archivo.

1.2. Más allá de la incrustación de muy alto nivel: una visión general

La interfaz de alto nivel le permite ejecutar piezas arbitrarias de código Python desde su aplicación, pero el intercambio de valores de datos es bastante engorroso, por decir lo menos. Si lo desea, debe usar llamadas de nivel inferior. A costa de tener que escribir más código C, puede lograr casi cualquier cosa.

Cabe señalar que extender Python e incrustar Python es la misma actividad, a pesar de la intención diferente. La mayoría de los temas tratados en los capítulos anteriores siguen siendo válidos. Para mostrar esto, considere lo que realmente hace el código de extensión de Python a C:

Convierte valores de datos de Python a C,

Realice una llamada de función a una rutina C usando los valores convertidos, y

Convierte los valores de datos de la llamada de C a Python.

Al incrustar Python, el código de interfaz hace:

Convierte valores de datos de C a Python,

Realice una llamada de función a una rutina de interfaz de Python utilizando los valores convertidos, y

Convierte los valores de datos de la llamada de Python a C.

Como puede ver, los pasos de conversión de datos simplemente se intercambian para acomodar la dirección diferente de la transferencia de idiomas cruzados. La única diferencia es la rutina que llama entre ambas conversiones de datos. Al extender, llama a una rutina C, al incrustar, llama a una rutina Python.

Este capítulo no discutirá cómo convertir datos de Python a C y viceversa. Además, se supone que se entiende el uso adecuado de las referencias y el tratamiento de errores. Dado que estos aspectos no difieren de extender el intérprete, puede consultar los capítulos anteriores para obtener la información requerida.

1.3. Incrustación pura

El primer programa tiene como objetivo ejecutar una función en un script Python. Al igual que en la sección sobre la interfaz de muy alto nivel, el intérprete de Python no interactúa directamente con la aplicación (pero eso cambiará en la siguiente sección).

El código para ejecutar una función definida en un script de Python es:

#define PY_SSIZE_T_CLEAN
#include <Python.h>

int
main(int argc, char *argv[])
{
    PyObject *pName, *pModule, *pFunc;
    PyObject *pArgs, *pValue;
    int i;

    if (argc < 3) {
        fprintf(stderr,"Usage: call pythonfile funcname [args]\n");
        return 1;
    }

    Py_Initialize();
    pName = PyUnicode_DecodeFSDefault(argv[1]);
    /* Error checking of pName left out */

    pModule = PyImport_Import(pName);
    Py_DECREF(pName);

    if (pModule != NULL) {
        pFunc = PyObject_GetAttrString(pModule, argv[2]);
        /* pFunc is a new reference */

        if (pFunc && PyCallable_Check(pFunc)) {
            pArgs = PyTuple_New(argc - 3);
            for (i = 0; i < argc - 3; ++i) {
                pValue = PyLong_FromLong(atoi(argv[i + 3]));
                if (!pValue) {
                    Py_DECREF(pArgs);
                    Py_DECREF(pModule);
                    fprintf(stderr, "Cannot convert argument\n");
                    return 1;
                }
                /* pValue reference stolen here: */
                PyTuple_SetItem(pArgs, i, pValue);
            }
            pValue = PyObject_CallObject(pFunc, pArgs);
            Py_DECREF(pArgs);
            if (pValue != NULL) {
                printf("Result of call: %ld\n", PyLong_AsLong(pValue));
                Py_DECREF(pValue);
            }
            else {
                Py_DECREF(pFunc);
                Py_DECREF(pModule);
                PyErr_Print();
                fprintf(stderr,"Call failed\n");
                return 1;
            }
        }
        else {
            if (PyErr_Occurred())
                PyErr_Print();
            fprintf(stderr, "Cannot find function \"%s\"\n", argv[2]);
        }
        Py_XDECREF(pFunc);
        Py_DECREF(pModule);
    }
    else {
        PyErr_Print();
        fprintf(stderr, "Failed to load \"%s\"\n", argv[1]);
        return 1;
    }
    if (Py_FinalizeEx() < 0) {
        return 120;
    }
    return 0;
}

Este código carga un script de Python usando argv[1] y llama a la función nombrada en argv[2]. Sus argumentos enteros son los otros valores del arreglo argv. Si usted compila y enlaza este programa (llamemos al ejecutable terminado call), y úselo para ejecutar un script Python, como:

def multiply(a,b):
    print("Will compute", a, "times", b)
    c = 0
    for i in range(0, a):
        c = c + b
    return c

entonces el resultado debería ser:

$ call multiply multiply 3 2
Will compute 3 times 2
Result of call: 6

Aunque el programa es bastante grande por su funcionalidad, la mayor parte del código es para la conversión de datos entre Python y C, y para informes de errores. La parte interesante con respecto a incrustar Python comienza con:

Py_Initialize();
pName = PyUnicode_DecodeFSDefault(argv[1]);
/* Error checking of pName left out */
pModule = PyImport_Import(pName);

Después de inicializar el intérprete, el script se carga usando PyImport_Import(). Esta rutina necesita una cadena Python como argumento, que se construye utilizando la rutina de conversión de datos PyUnicode_FromString().

pFunc = PyObject_GetAttrString(pModule, argv[2]);
/* pFunc is a new reference */

if (pFunc && PyCallable_Check(pFunc)) {
    ...
}
Py_XDECREF(pFunc);

Una vez que se carga el script, el nombre que estamos buscando se recupera usando PyObject_GetAttrString(). Si el nombre existe y el objeto retornado es invocable, puede asumir con seguridad que es una función. Luego, el programa continúa construyendo una tupla de argumentos como de costumbre. La llamada a la función Python se realiza con:

pValue = PyObject_CallObject(pFunc, pArgs);

Al regresar la función, pValue es NULL o contiene una referencia al valor de retorno de la función. Asegúrese de liberar la referencia después de examinar el valor.

1.4. Extendiendo Python Incrustado

Hasta ahora, el intérprete de Python incorporado no tenía acceso a la funcionalidad de la aplicación misma. La API de Python lo permite al extender el intérprete incorporado. Es decir, el intérprete incorporado se amplía con las rutinas proporcionadas por la aplicación. Si bien suena complejo, no es tan malo. Simplemente olvide por un momento que la aplicación inicia el intérprete de Python. En cambio, considere que la aplicación es un conjunto de subrutinas y escriba un código de pegamento que le otorgue a Python acceso a esas rutinas, al igual que escribiría una extensión normal de Python. Por ejemplo:

static int numargs=0;

/* Return the number of arguments of the application command line */
static PyObject*
emb_numargs(PyObject *self, PyObject *args)
{
    if(!PyArg_ParseTuple(args, ":numargs"))
        return NULL;
    return PyLong_FromLong(numargs);
}

static PyMethodDef EmbMethods[] = {
    {"numargs", emb_numargs, METH_VARARGS,
     "Return the number of arguments received by the process."},
    {NULL, NULL, 0, NULL}
};

static PyModuleDef EmbModule = {
    PyModuleDef_HEAD_INIT, "emb", NULL, -1, EmbMethods,
    NULL, NULL, NULL, NULL
};

static PyObject*
PyInit_emb(void)
{
    return PyModule_Create(&EmbModule);
}

Inserte el código anterior justo encima de la función main(). Además, inserte las siguientes dos declaraciones antes de la llamada a Py_Initialize():

numargs = argc;
PyImport_AppendInittab("emb", &PyInit_emb);

Estas dos líneas inicializan la variable numargs y hacen que la función emb.numargs() sea accesible para el intérprete de Python incorporado. Con estas extensiones, el script de Python puede hacer cosas como

import emb
print("Number of arguments", emb.numargs())

En una aplicación real, los métodos expondrán una API de la aplicación a Python.

1.5. Incrustando Python en C++

También es posible incrustar Python en un programa C++; precisamente cómo se hace esto dependerá de los detalles del sistema C++ utilizado; en general, necesitará escribir el programa principal en C++ y usar el compilador de C++ para compilar y vincular su programa. No es necesario volver a compilar Python usando C++.

1.6. Compilar y enlazar bajo sistemas tipo Unix

No es necesariamente trivial encontrar los indicadores correctos para pasar a su compilador (y enlazador) para incrustar el intérprete de Python en su aplicación, particularmente porque Python necesita cargar módulos de biblioteca implementados como extensiones dinámicas en C (archivos .so) enlazados en su contra.

Para conocer los indicadores necesarios del compilador y el enlazador, puede ejecutar el script pythonX.Y-config que se genera como parte del proceso de instalación (también puede estar disponible un script python3-config ) Este script tiene varias opciones, de las cuales las siguientes serán directamente útiles para usted:

pythonX.Y-config --cflags le dará las banderas recomendadas al compilar:

$ /opt/bin/python3.4-config --cflags
-I/opt/include/python3.4m -I/opt/include/python3.4m -DNDEBUG -g -fwrapv -O3 -Wall -Wstrict-prototypes

pythonX.Y-config --ldflags le dará las banderas recomendadas al vincular:

$ /opt/bin/python3.4-config --ldflags
-L/opt/lib/python3.4/config-3.4m -lpthread -ldl -lutil -lm -lpython3.4m -Xlinker -export-dynamic

Nota

Para evitar confusiones entre varias instalaciones de Python (y especialmente entre el sistema Python y su propio Python compilado), se recomienda que use la ruta absoluta a pythonX.Y-config, como en el ejemplo anterior.

Si este procedimiento no funciona para usted (no se garantiza que funcione para todas las plataformas tipo Unix; sin embargo, le damos la bienvenida informes de errores) deberá leer la documentación de su sistema sobre dinámica vincular o examinar Python Makefile (use sysconfig.get_makefile_filename() para encontrar su ubicación) y las opciones de compilación. En este caso, el módulo sysconfig es una herramienta útil para extraer mediante programación los valores de configuración que querrá combinar. Por ejemplo:

>>> import sysconfig
>>> sysconfig.get_config_var('LIBS')
'-lpthread -ldl  -lutil'
>>> sysconfig.get_config_var('LINKFORSHARED')
'-Xlinker -export-dynamic'

Manual de referencia de la API en C de Python

Este manual documenta la API utilizada por los programadores de C y C ++ que desean escribir módulos de extensión o incorporar Python. Es un complemento de Ampliación e incrustación del intérprete de Python, que describe los principios generales de la escritura de extensión pero no documenta las funciones API en detalle.

Introducción

Estándares de codificación

Archivos de cabecera (Include)

Macros útiles

Objetos, tipos y conteos de referencias

Excepciones

Integración de Python

Depuración de compilaciones

Interfaz binaria de aplicación estable

La capa de muy alto nivel

Conteo de referencias

Manejo de excepciones

Impresión y limpieza

Lanzando excepciones

Emitir advertencias

Consultando el indicador de error

Manejo de señal

Clases de Excepción

Objetos Excepción

Objectos Unicode de Excepción

Control de Recursión

Excepciones Estándar

Categorías de advertencia estándar

Utilidades

Utilidades del sistema operativo

Funciones del Sistema

Control de procesos

Importando Módulos

Soporte de empaquetado (marshalling) de datos

Analizando argumentos y construyendo valores

Conversión y formato de cadenas de caracteres

Reflexión

Registro de códec y funciones de soporte

Capa de objetos abstractos

Protocolo de objeto

Protocolo de llamada

Protocolo de números

Protocolo de secuencia

Protocolo de mapeo

Protocolo iterador

Protocolo Búfer

Protocolo de búfer antiguo

Capa de objetos concretos

Objetos fundamentales

Objetos numéricos

Objetos de secuencia

Objetos contenedor

Objetos de función

Otros objetos

Inicialización, Finalización e Hilos

Antes de la inicialización de Python

Variables de configuración global

Inicializando y finalizando el intérprete

Parámetros de todo el proceso

Estado del hilo y el bloqueo global del intérprete

Soporte de subinterprete

Notificaciones asincrónicas

Perfilado y Rastreo

Soporte avanzado del depurador

Soporte de almacenamiento local de hilo

Configuración de inicialización de Python

PyWideStringList

PyStatus

PyPreConfig

Preinicialización con PyPreConfig

PyConfig

Inicialización con PyConfig

Configuración aislada

Configuración de Python

Configuración de ruta

Py_RunMain()

Py_GetArgcArgv()

API Provisional Privada de Inicialización Multifásica

Gestión de la memoria

Visión general

Interfaz de memoria sin procesar

Interfaz de memoria

Asignadores de objetos

Asignadores de memoria predeterminados

Personalizar asignadores de memoria

El asignador pymalloc

tracemalloc C API

Ejemplos

Soporte de implementación de objetos

Asignación de objetos en el montículo

Estructuras de objetos comunes

Objetos Tipo

Estructuras de Objetos de Números

Estructuras de Objetos Mapeo

Estructuras de objetos secuencia

Estructuras de Objetos Búfer

Estructuras de objetos asíncronos

Tipo Ranura typedefs

Ejemplos

Apoyo a la recolección de basura cíclica

Versiones de API y ABI

Introducción

La interfaz del programador de aplicaciones (API) con Python brinda a los programadores de C y C++ acceso al intérprete de Python en una variedad de niveles. La API es igualmente utilizable desde C++, pero por brevedad generalmente se conoce como la API Python/C. Hay dos razones fundamentalmente diferentes para usar la API Python/C. La primera razón es escribir módulos de extensión para propósitos específicos; Estos son módulos C que extienden el intérprete de Python. Este es probablemente el uso más común. La segunda razón es usar Python como componente en una aplicación más grande; Esta técnica se conoce generalmente como integración (embedding) Python en una aplicación.

Escribir un módulo de extensión es un proceso relativamente bien entendido, donde un enfoque de «libro de cocina» (cookbook) funciona bien. Hay varias herramientas que automatizan el proceso hasta cierto punto. Si bien las personas han integrado Python en otras aplicaciones desde su existencia temprana, el proceso de integrar Python es menos sencillo que escribir una extensión.

Muchas funciones API son útiles independientemente de si está integrando o extendiendo Python; Además, la mayoría de las aplicaciones que integran Python también necesitarán proporcionar una extensión personalizada, por lo que probablemente sea una buena idea familiarizarse con la escritura de una extensión antes de intentar integrar Python en una aplicación real.

Estándares de codificación

Si está escribiendo código C para su inclusión en CPython, debe seguir las pautas y estándares definidos en PEP 7 [https://www.python.org/dev/peps/pep-0007]. Estas pautas se aplican independientemente de la versión de Python a la que esté contribuyendo. Seguir estas convenciones no es necesario para sus propios módulos de extensión de terceros, a menos que eventualmente espere contribuir con ellos a Python.

Archivos de cabecera (Include)

Todas las definiciones de función, tipo y macro necesarias para usar la API Python/C se incluyen en su código mediante la siguiente línea:

#define PY_SSIZE_T_CLEAN
#include <Python.h>

Esto implica la inclusión de los siguientes archivos de encabezado estándar: <stdio.h>, <string.h>, <errno.h>, <limits.h>, <assert.h> y <stdlib.h> (si está disponible).

Nota

Dado que Python puede definir algunas definiciones de preprocesador que afectan los encabezados estándar en algunos sistemas, debe incluir Python.h antes de incluir encabezados estándar.

Se recomienda definir siempre PY_SSIZE_T_CLEAN antes de incluir Python.h. Consulte Analizando argumentos y construyendo valores para obtener una descripción de este macro.

Todos los nombres visibles del usuario definidos por Python.h (excepto los definidos por los encabezados estándar incluidos) tienen uno de los prefijos Py o _Py. Los nombres que comienzan con _Py son para uso interno de la implementación de Python y no deben ser utilizados por escritores de extensiones. Los nombres de miembros de estructura no tienen un prefijo reservado.

Nota

El código de usuario nunca debe definir nombres que comiencen con Py o _Py. Esto confunde al lector y pone en peligro la portabilidad del código de usuario para futuras versiones de Python, que pueden definir nombres adicionales que comienzan con uno de estos prefijos.

Los archivos de encabezado generalmente se instalan con Python. En Unix, estos se encuentran en los directorios prefix/include/pythonversion/ y exec_prefix/include/pythonversion/, donde prefix y exec_prefix están definidos por los parámetros correspondientes al programa de Python configure y version es '%d.%d' % sys.version_info[:2]. En Windows, los encabezados se instalan en prefix/include, donde prefix es el directorio de instalación especificado para el instalador.

Para incluir los encabezados, coloque ambos directorios (si son diferentes) en la ruta de búsqueda de su compilador para incluir. No coloque los directorios principales en la ruta de búsqueda y luego use #include <pythonX.Y/Python.h>; esto se romperá en las compilaciones multiplataforma ya que los encabezados independientes de la plataforma bajo prefix incluyen los encabezados específicos de la plataforma de exec_prefix.

Los usuarios de C++ deben tener en cuenta que aunque la API se define completamente usando C, los archivos de encabezado declaran correctamente que los puntos de entrada son extern "C". Como resultado, no es necesario hacer nada especial para usar la API desde C++.

Macros útiles

Varias macros útiles se definen en los archivos de encabezado de Python. Muchos se definen más cerca de donde son útiles (por ejemplo Py_RETURN_NONE). Otros de una utilidad más general se definen aquí. Esto no es necesariamente una lista completa.

Py_UNREACHABLE()

Use esto cuando tenga una ruta de código a la que no se pueda acceder por diseño. Por ejemplo, en la cláusula default: en una declaración switch para la cual todos los valores posibles están cubiertos en declaraciones case. Use esto en lugares donde podría tener la tentación de poner una llamada assert(0) o abort().

En el modo de lanzamiento, la macro ayuda al compilador a optimizar el código y evita una advertencia sobre el código inalcanzable. Por ejemplo, la macro se implementa con __builtin_unreachable() en GCC en modo de lanzamiento.

Un uso de Py_UNREACHABLE() es seguir una llamada a una función que nunca retorna pero que no está declarada _Py_NO_RETURN.

Si una ruta de código es un código muy poco probable pero se puede acceder en casos excepcionales, esta macro no debe utilizarse. Por ejemplo, en condiciones de poca memoria o si una llamada al sistema retorna un valor fuera del rango esperado. En este caso, es mejor informar el error a la persona que llama. Si no se puede informar del error a la persona que llama, se puede utilizar Py_FatalError().

Nuevo en la versión 3.7.

Py_ABS(x)

Retorna el valor absoluto de x.

Nuevo en la versión 3.3.

Py_MIN(x, y)

Retorna el valor mínimo entre x e y.

Nuevo en la versión 3.3.

Py_MAX(x, y)

Retorna el valor máximo entre x e y.

Nuevo en la versión 3.3.

Py_STRINGIFY(x)

Convierte x en una cadena de caracteres C. Por ejemplo, Py_STRINGIFY(123) retorna "123".

Nuevo en la versión 3.4.

Py_MEMBER_SIZE(type, member)

Retorna el tamaño de una estructura (type) member en bytes.

Nuevo en la versión 3.6.

Py_CHARMASK(c)

El argumento debe ser un carácter o un número entero en el rango [-128, 127] o [0, 255]. Este macro retorna la conversión c a un unsigned char.

Py_GETENV(s)

Al igual que getenv(s), pero retorna NULL si: la opción -E se pasó en la línea de comando (es decir, si se establece Py_IgnoreEnvironmentFlag).

Py_UNUSED(arg)

Use esto para argumentos no utilizados en una definición de función para silenciar las advertencias del compilador. Ejemplo: int func(int a, int Py_UNUSED(b)) {return a; }.

Nuevo en la versión 3.4.

Py_DEPRECATED(version)

Use esto para declaraciones obsoletas. El macro debe colocarse antes del nombre del símbolo.

Ejemplo:

Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);

Distinto en la versión 3.8: Soporte para MSVC fue agregado.

PyDoc_STRVAR(name, str)

Crea una variable con el nombre name que se puede usar en docstrings. Si Python se construye sin docstrings, el valor estará vacío.

Utilice PyDoc_STRVAR para que los docstrings admitan la construcción de Python sin docstrings, como se especifica en PEP 7 [https://www.python.org/dev/peps/pep-0007].

Ejemplo:

PyDoc_STRVAR(pop_doc, "Remove and return the rightmost element.");

static PyMethodDef deque_methods[] = {
    // ...
    {"pop", (PyCFunction)deque_pop, METH_NOARGS, pop_doc},
    // ...
}

PyDoc_STR(str)

Crea un docstring para la cadena de caracteres de entrada dada o una cadena vacía si los docstrings están deshabilitados.

Utilice PyDoc_STR al especificar docstrings para admitir la construcción de Python sin docstrings, como se especifica en PEP 7 [https://www.python.org/dev/peps/pep-0007].

Ejemplo:

static PyMethodDef pysqlite_row_methods[] = {
    {"keys", (PyCFunction)pysqlite_row_keys, METH_NOARGS,
        PyDoc_STR("Returns the keys of the row.")},
    {NULL, NULL}
};

Objetos, tipos y conteos de referencias

La mayoría de las funciones de Python/C API tienen uno o más argumentos, así como un valor de retorno de tipo PyObject*. Este tipo es un puntero a un tipo de datos opaco que representa un objeto arbitrario de Python. Dado que todos los tipos de objetos Python son tratados de la misma manera por el lenguaje Python en la mayoría de las situaciones (por ejemplo, asignaciones, reglas de alcance y paso de argumentos), es apropiado que estén representados por un solo tipo C. Casi todos los objetos de Python viven en el montículo (heap): nunca declaras una variable automática o estática de tipo PyObject, solo se pueden declarar variables de puntero de tipo PyObject*. La única excepción son los objetos tipo; como nunca deben desasignarse, son típicamente objetos estáticos PyTypeObject.

Todos los objetos de Python (incluso los enteros de Python) tienen un tipo (type) y un conteo de referencia (reference count). El tipo de un objeto determina qué tipo de objeto es (por ejemplo, un número entero, una lista o una función definida por el usuario; hay muchos más como se explica en Jerarquía de tipos estándar). Para cada uno de los tipos conocidos hay un macro para verificar si un objeto es de ese tipo; por ejemplo, PyList_Check(a) es verdadero si (y solo si) el objeto al que apunta a es una lista de Python.

Conteo de Referencias

El conteo de referencia es importante porque las computadoras de hoy tienen un tamaño de memoria finito (y a menudo muy limitado); cuenta cuántos lugares diferentes hay los cuales tienen una referencia a un objeto. Tal lugar podría ser otro objeto, o una variable C global (o estática), o una variable local en alguna función C. Cuando el recuento de referencia de un objeto se convierte en cero, el objeto se desasigna. Si contiene referencias a otros objetos, su recuento de referencias se reduce. Esos otros objetos pueden ser desasignados a su vez, si esta disminución hace que su recuento de referencia sea cero, y así sucesivamente. (Hay un problema obvio con los objetos que se refieren entre sí aquí; por ahora, la solución es «no hagas eso»).

Los conteos de referencias siempre se manipulan explícitamente. La forma normal es usar el macro Py_INCREF() para incrementar el conteo de referencia de un objeto en uno, y Py_DECREF() para disminuirlo en uno. El macro Py_DECREF() es considerablemente más compleja que la incref, ya que debe verificar si el recuento de referencia se convierte en cero y luego hacer que se llame al desasignador (deallocator) del objeto. El desasignador es un puntero de función contenido en la estructura de tipo del objeto. El desasignador específico del tipo se encarga de disminuir los recuentos de referencia para otros objetos contenidos en el objeto si este es un tipo de objeto compuesto, como una lista, así como realizar cualquier finalización adicional que sea necesaria. No hay posibilidad de que el conteo de referencia se desborde; se utilizan al menos tantos bits para contener el recuento de referencia como ubicaciones de memoria distintas en la memoria virtual (suponiendo sizeof(Py_ssize_t) >= sizeof(void*)). Por lo tanto, el incremento del recuento de referencia es una operación simple.

No es necesario incrementar el conteo de referencia de un objeto para cada variable local que contiene un puntero a un objeto. En teoría, el conteo de referencia del objeto aumenta en uno cuando se hace que la variable apunte hacia él y disminuye en uno cuando la variable se sale del alcance. Sin embargo, estos dos se cancelan entre sí, por lo que al final el recuento de referencias no ha cambiado. La única razón real para usar el recuento de referencia es evitar que el objeto pierda su asignación mientras nuestra variable lo apunte. Si sabemos que hay al menos otra referencia al objeto que vive al menos tanto como nuestra variable, no hay necesidad de incrementar el recuento de referencias temporalmente. Una situación importante donde esto surge es en los objetos que se pasan como argumentos a las funciones de C en un módulo de extensión que se llama desde Python; El mecanismo de llamada garantiza mantener una referencia a cada argumento durante la duración de la llamada.

Sin embargo, una trampa común es extraer un objeto de una lista y mantenerlo por un tiempo sin incrementar su conteo de referencia. Es posible que alguna otra operación elimine el objeto de la lista, disminuya su conteo de referencias y posiblemente lo desasigne. El peligro real es que las operaciones de aspecto inocente pueden invocar código arbitrario de Python que podría hacer esto; hay una ruta de código que permite que el control vuelva al usuario desde a Py_DECREF(), por lo que casi cualquier operación es potencialmente peligrosa.

Un enfoque seguro es utilizar siempre las operaciones genéricas (funciones cuyo nombre comienza con PyObject_, PyNumber_, PySequence_ o PyMapping_). Estas operaciones siempre incrementan el recuento de referencia del objeto que retornan. Esto deja a la persona que llama con la responsabilidad de llamar Py_DECREF() cuando hayan terminado con el resultado; Esto pronto se convierte en una segunda naturaleza.

Detalles del conteo de referencia

El comportamiento del conteo de referencias de funciones en la API de Python/C se explica mejor en términos de propiedad de las referencias. La propiedad pertenece a referencias, nunca a objetos (los objetos no son propiedad: siempre se comparten). «Poseer una referencia» significa ser responsable de llamar a Py_DECREF cuando ya no se necesita la referencia. La propiedad también se puede transferir, lo que significa que el código que recibe la propiedad de la referencia se hace responsable de eventualmente decretarla llamando a Py_DECREF() o Py_XDECREF() cuando ya no es necesario — o transmitir esta responsabilidad (generalmente a la persona que llama). Cuando una función transfiere la propiedad de una referencia a su llamador, se dice que el que llama recibe una nueva referencia. Cuando no se transfiere ninguna propiedad, se dice que la persona que llama toma prestada la referencia. No es necesario hacer nada para obtener una referencia prestada.

Por el contrario, cuando una función de llamada pasa una referencia a un objeto, hay dos posibilidades: la función roba una referencia al objeto, o no lo hace. Robar una referencia significa que cuando pasa una referencia a una función, esa función asume que ahora posee esa referencia, y usted ya no es responsable de ella.

Pocas funciones roban referencias; las dos excepciones notables son PyList_SetItem() y PyTuple_SetItem(), que roban una referencia al elemento (¡pero no a la tupla o lista en la que se coloca el elemento!). Estas funciones fueron diseñadas para robar una referencia debido a un idioma común para poblar una tupla o lista con objetos recién creados; por ejemplo, el código para crear la tupla (1, 2, "tres") podría verse así (olvidando el manejo de errores por el momento; una mejor manera de codificar esto se muestra a continuación):

PyObject *t;

t = PyTuple_New(3);
PyTuple_SetItem(t, 0, PyLong_FromLong(1L));
PyTuple_SetItem(t, 1, PyLong_FromLong(2L));
PyTuple_SetItem(t, 2, PyUnicode_FromString("three"));

Aquí PyLong_FromLong() retorna una nueva referencia que es inmediatamente robada por PyTuple_SetItem(). Cuando quiera seguir usando un objeto aunque se le robe la referencia, use Py_INCREF() para tomar otra referencia antes de llamar a la función de robo de referencias.

Por cierto, PyTuple_SetItem() es la única forma de establecer elementos de tupla; PySequence_SetItem() y PyObject_SetItem() se niegan a hacer esto ya que las tuplas son un tipo de datos inmutable. Solo debe usar PyTuple_SetItem() para las tuplas que está creando usted mismo.

El código equivalente para llenar una lista se puede escribir usando PyList_New() y PyList_SetItem().

Sin embargo, en la práctica, rara vez utilizará estas formas de crear y completar una tupla o lista. Hay una función genérica, Py_BuildValue(), que puede crear los objetos más comunes a partir de valores C, dirigidos por un una cadena de caracteres de formato (format string). Por ejemplo, los dos bloques de código anteriores podrían reemplazarse por lo siguiente (que también se ocupa de la comprobación de errores):

PyObject *tuple, *list;

tuple = Py_BuildValue("(iis)", 1, 2, "three");
list = Py_BuildValue("[iis]", 1, 2, "three");

Es mucho más común usar PyObject_SetItem() y amigos con elementos cuyas referencias solo está prestando, como argumentos que se pasaron a la función que está escribiendo. En ese caso, su comportamiento con respecto a los recuentos de referencias es mucho más sensato, ya que no tiene que incrementar un recuento de referencias para poder regalar una referencia («robarla»). Por ejemplo, esta función establece todos los elementos de una lista (en realidad, cualquier secuencia mutable) en un elemento dado:

int
set_all(PyObject *target, PyObject *item)
{
    Py_ssize_t i, n;

    n = PyObject_Length(target);
    if (n < 0)
        return -1;
    for (i = 0; i < n; i++) {
        PyObject *index = PyLong_FromSsize_t(i);
        if (!index)
            return -1;
        if (PyObject_SetItem(target, index, item) < 0) {
            Py_DECREF(index);
            return -1;
        }
        Py_DECREF(index);
    }
    return 0;
}

La situación es ligeramente diferente para los valores de retorno de la función. Si bien pasar una referencia a la mayoría de las funciones no cambia sus responsabilidades de propiedad para esa referencia, muchas funciones que retornan una referencia a un objeto le otorgan la propiedad de la referencia. La razón es simple: en muchos casos, el objeto retornado se crea sobre la marcha, y la referencia que obtiene es la única referencia al objeto. Por lo tanto, las funciones genéricas que retornan referencias de objeto, como PyObject_GetItem() y PySequence_GetItem(), siempre retornan una nueva referencia (la entidad que llama se convierte en el propietario de la referencia).

Es importante darse cuenta de que si posee una referencia retornada por una función depende de a qué función llame únicamente — el plumaje (el tipo del objeto pasado como argumento a la función) no entra en él! Por lo tanto, si extrae un elemento de una lista usando PyList_GetItem(), no posee la referencia — pero si obtiene el mismo elemento de la misma lista usando PySequence_GetItem() (que toma exactamente los mismos argumentos), usted posee una referencia al objeto retornado.

Aquí hay un ejemplo de cómo podría escribir una función que calcule la suma de los elementos en una lista de enteros; una vez usando PyList_GetItem(), y una vez usando PySequence_GetItem().

long
sum_list(PyObject *list)
{
    Py_ssize_t i, n;
    long total = 0, value;
    PyObject *item;

    n = PyList_Size(list);
    if (n < 0)
        return -1; /* Not a list */
    for (i = 0; i < n; i++) {
        item = PyList_GetItem(list, i); /* Can't fail */
        if (!PyLong_Check(item)) continue; /* Skip non-integers */
        value = PyLong_AsLong(item);
        if (value == -1 && PyErr_Occurred())
            /* Integer too big to fit in a C long, bail out */
            return -1;
        total += value;
    }
    return total;
}

long
sum_sequence(PyObject *sequence)
{
    Py_ssize_t i, n;
    long total = 0, value;
    PyObject *item;
    n = PySequence_Length(sequence);
    if (n < 0)
        return -1; /* Has no length */
    for (i = 0; i < n; i++) {
        item = PySequence_GetItem(sequence, i);
        if (item == NULL)
            return -1; /* Not a sequence, or other failure */
        if (PyLong_Check(item)) {
            value = PyLong_AsLong(item);
            Py_DECREF(item);
            if (value == -1 && PyErr_Occurred())
                /* Integer too big to fit in a C long, bail out */
                return -1;
            total += value;
        }
        else {
            Py_DECREF(item); /* Discard reference ownership */
        }
    }
    return total;
}

Tipos

Hay algunos otros tipos de datos que juegan un papel importante en la API de Python/C; la mayoría son tipos C simples como int, long, double y char*. Algunos tipos de estructura se usan para describir tablas estáticas que se usan para enumerar las funciones exportadas por un módulo o los atributos de datos de un nuevo tipo de objeto, y otro se usa para describir el valor de un número complejo. Estos serán discutidos junto con las funciones que los usan.

Py_ssize_t

A signed integral type such that sizeof(Py_ssize_t) == sizeof(size_t). C99 doesn’t define such a thing directly (size_t is an unsigned integral type). See PEP 353 [https://www.python.org/dev/peps/pep-0353] for details. PY_SSIZE_T_MAX is the largest positive value of type Py_ssize_t.

Excepciones

El programador de Python solo necesita lidiar con excepciones si se requiere un manejo específico de errores; las excepciones no manejadas se propagan automáticamente a la persona que llama, luego a la persona que llama, y así sucesivamente, hasta que llegan al intérprete de nivel superior, donde se informan al usuario acompañado de un seguimiento de pila (stack traceback).

Para los programadores de C, sin embargo, la comprobación de errores siempre tiene que ser explícita. Todas las funciones en la API Python/C pueden generar excepciones, a menos que se señale explícitamente en la documentación de una función. En general, cuando una función encuentra un error, establece una excepción, descarta cualquier referencia de objeto que posea y retorna un indicador de error. Si no se documenta lo contrario, este indicador es NULL o -1, dependiendo del tipo de retorno de la función. Algunas funciones retornan un resultado booleano verdadero/falso, con falso que indica un error. Muy pocas funciones no retornan ningún indicador de error explícito o tienen un valor de retorno ambiguo, y requieren pruebas explícitas de errores con PyErr_Occurred(). Estas excepciones siempre se documentan explícitamente.

El estado de excepción se mantiene en el almacenamiento por subproceso (esto es equivalente a usar el almacenamiento global en una aplicación sin subprocesos). Un subproceso puede estar en uno de dos estados: se ha producido una excepción o no. La función PyErr_Occurred() puede usarse para verificar esto: retorna una referencia prestada al objeto de tipo de excepción cuando se produce una excepción, y NULL de lo contrario. Hay una serie de funciones para establecer el estado de excepción: PyErr_SetString() es la función más común (aunque no la más general) para establecer el estado de excepción, y PyErr_Clear() borra la excepción estado.

El estado de excepción completo consta de tres objetos (todos los cuales pueden ser NULL): el tipo de excepción, el valor de excepción correspondiente y el rastreo. Estos tienen los mismos significados que el resultado de Python de sys.exc_info(); sin embargo, no son lo mismo: los objetos Python representan la última excepción manejada por una declaración de Python try … except, mientras que el estado de excepción de nivel C solo existe mientras se está pasando una excepción entre las funciones de C hasta que llega al bucle principal del intérprete de código de bytes (bytecode) de Python, que se encarga de transferirlo a sys.exc_info() y amigos.

Tenga en cuenta que a partir de Python 1.5, la forma preferida y segura de subprocesos para acceder al estado de excepción desde el código de Python es llamar a la función sys.exc_info(), que retorna el estado de excepción por subproceso para el código de Python. Además, la semántica de ambas formas de acceder al estado de excepción ha cambiado de modo que una función que detecta una excepción guardará y restaurará el estado de excepción de su hilo para preservar el estado de excepción de su llamador. Esto evita errores comunes en el código de manejo de excepciones causado por una función de aspecto inocente que sobrescribe la excepción que se maneja; También reduce la extensión de vida útil a menudo no deseada para los objetos a los que hacen referencia los marcos de pila en el rastreo.

Como principio general, una función que llama a otra función para realizar alguna tarea debe verificar si la función llamada generó una excepción y, de ser así, pasar el estado de excepción a quien la llama (caller). Debe descartar cualquier referencia de objeto que posea y retornar un indicador de error, pero no debe establecer otra excepción — que sobrescribirá la excepción que se acaba de generar y perderá información importante sobre la causa exacta del error.

Un ejemplo simple de detectar excepciones y pasarlas se muestra en el ejemplo sum_sequence() anterior. Sucede que este ejemplo no necesita limpiar ninguna referencia de propiedad cuando detecta un error. La siguiente función de ejemplo muestra algunos errores de limpieza. Primero, para recordar por qué le gusta Python, le mostramos el código Python equivalente:

def incr_item(dict, key):
    try:
        item = dict[key]
    except KeyError:
        item = 0
    dict[key] = item + 1

Aquí está el código C correspondiente, en todo su esplendor:

int
incr_item(PyObject *dict, PyObject *key)
{
    /* Objects all initialized to NULL for Py_XDECREF */
    PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;
    int rv = -1; /* Return value initialized to -1 (failure) */

    item = PyObject_GetItem(dict, key);
    if (item == NULL) {
        /* Handle KeyError only: */
        if (!PyErr_ExceptionMatches(PyExc_KeyError))
            goto error;

        /* Clear the error and use zero: */
        PyErr_Clear();
        item = PyLong_FromLong(0L);
        if (item == NULL)
            goto error;
    }
    const_one = PyLong_FromLong(1L);
    if (const_one == NULL)
        goto error;

    incremented_item = PyNumber_Add(item, const_one);
    if (incremented_item == NULL)
        goto error;

    if (PyObject_SetItem(dict, key, incremented_item) < 0)
        goto error;
    rv = 0; /* Success */
    /* Continue with cleanup code */

 error:
    /* Cleanup code, shared by success and failure path */

    /* Use Py_XDECREF() to ignore NULL references */
    Py_XDECREF(item);
    Py_XDECREF(const_one);
    Py_XDECREF(incremented_item);

    return rv; /* -1 for error, 0 for success */
}

Este ejemplo representa un uso aprobado de la declaración goto en C! Ilustra el uso de PyErr_ExceptionMatches() y PyErr_Clear() para manejar excepciones específicas, y el uso de Py_XDECREF() para eliminar referencias propias que pueden ser NULL (tenga en cuenta la 'X'” en el nombre; Py_DECREF() se bloqueará cuando se enfrente con una referencia NULL). Es importante que las variables utilizadas para contener referencias propias se inicialicen en NULL para que esto funcione; Del mismo modo, el valor de retorno propuesto se inicializa a -1 (falla) y solo se establece en éxito después de que la última llamada realizada sea exitosa.

Integración de Python

La única tarea importante de la que solo tienen que preocuparse los integradores (a diferencia de los escritores de extensión) del intérprete de Python es la inicialización, y posiblemente la finalización, del intérprete de Python. La mayor parte de la funcionalidad del intérprete solo se puede usar después de que el intérprete se haya inicializado.

La función básica de inicialización es Py_Initialize(). Esto inicializa la tabla de módulos cargados y crea los módulos fundamentales builtins, __main__, y sys. También inicializa la ruta de búsqueda del módulo (sys.path).

Py_Initialize() no establece la «lista de argumentos de script» (sys.argv). Si el código de Python necesita esta variable que se ejecutará más adelante, debe establecerse explícitamente con una llamada a PySys_SetArgvEx(argc, argv, updatepath) después de la llamada a Py_Initialize().

En la mayoría de los sistemas (en particular, en Unix y Windows, aunque los detalles son ligeramente diferentes), Py_Initialize() calcula la ruta de búsqueda del módulo basándose en su mejor estimación de la ubicación del ejecutable del intérprete de Python estándar, suponiendo que la biblioteca de Python se encuentra en una ubicación fija en relación con el ejecutable del intérprete de Python. En particular, busca un directorio llamado lib/pythonX.Y relativo al directorio padre donde se encuentra el ejecutable llamado python en la ruta de búsqueda del comando shell (la variable de entorno PATH).

Por ejemplo, si el ejecutable de Python se encuentra en /usr/local/bin/python, se supondrá que las bibliotecas están en /usr/local/lib/pythonX.Y. (De hecho, esta ruta particular también es la ubicación «alternativa», utilizada cuando no se encuentra un archivo ejecutable llamado python junto con PATH.) El usuario puede anular este comportamiento configurando la variable de entorno PYTHONHOME, o inserte directorios adicionales delante de la ruta estándar estableciendo PYTHONPATH.

La aplicación de integración puede dirigir la búsqueda llamando a Py_SetProgramName(file) antes llamando Py_Initialize(). Tenga en cuenta que PYTHONHOME todavía anula esto y PYTHONPATH todavía se inserta frente a la ruta estándar. Una aplicación que requiere un control total debe proporcionar su propia implementación de Py_GetPath(), Py_GetPrefix(), Py_GetExecPrefix(), y Py_GetProgramFullPath() (todo definido en Modules/getpath.c).

A veces, es deseable «no inicializar» Python. Por ejemplo, la aplicación puede querer comenzar de nuevo (hacer otra llamada a Py_Initialize()) o la aplicación simplemente se hace con el uso de Python y quiere liberar memoria asignada por Python. Esto se puede lograr llamando a Py_FinalizeEx(). La función Py_IsInitialized() retorna verdadero si Python se encuentra actualmente en el estado inicializado. Se proporciona más información sobre estas funciones en un capítulo posterior. Tenga en cuenta que Py_FinalizeEx() no libera toda la memoria asignada por el intérprete de Python, por ejemplo, la memoria asignada por los módulos de extensión actualmente no se puede liberar.

Depuración de compilaciones

Python se puede construir con varios macros para permitir verificaciones adicionales del intérprete y los módulos de extensión. Estas comprobaciones tienden a agregar una gran cantidad de sobrecarga al tiempo de ejecución, por lo que no están habilitadas de forma predeterminada.

Una lista completa de los diversos tipos de compilaciones de depuración se encuentra en el archivo Misc/SpecialBuilds.txt en la distribución fuente de Python. Hay compilaciones disponibles que admiten el rastreo de los conteos de referencia, la depuración del asignador de memoria o la creación de perfiles de bajo nivel del bucle principal del intérprete. Solo las compilaciones más utilizadas se describirán en el resto de esta sección.

Compilar el intérprete con el macro Py_DEBUG definido produce lo que generalmente se entiende por «una compilación de depuración» de Python. Py_DEBUG se habilita en la compilación de Unix agregando --with-pydebug al comando ./configure. También está implícito en la presencia del macro no específico de Python _DEBUG. Cuando Py_DEBUG está habilitado en la compilación de Unix, la optimización del compilador está deshabilitada.

Además de la depuración del recuento de referencia que se describe a continuación, se realizan las siguientes verificaciones adicionales:

Se agregan comprobaciones adicionales al asignador de objetos.

Se agregan verificaciones adicionales al analizador y compilador.

Las conversiones de tipos hacia abajo (downcasting) de tipos anchos a tipos estrechos se comprueban por pérdida de información.

Se agregan varias aserciones al diccionario y se establecen implementaciones. Además, el objeto set adquiere un método test_c_api().

Las comprobaciones de cordura (sanity checks) de los argumentos de entrada se agregan a la creación del marco.

El almacenamiento para ints se inicializa con un patrón no válido conocido para capturar referencias a dígitos no inicializados.

El seguimiento de bajo nivel y la comprobación de excepciones adicionales se agregan a la máquina virtual en tiempo de ejecución.

Se agregan verificaciones adicionales a la implementación de la arena de memoria.

Se agrega depuración adicional al módulo de hilos.

Puede haber controles adicionales no mencionados aquí.

Definiendo Py_TRACE_REFS habilita el rastreo de referencias. Cuando se define, se mantiene una lista circular doblemente vinculada de objetos activos al agregar dos campos adicionales a cada PyObject. También se realiza un seguimiento de las asignaciones totales. Al salir, se imprimen todas las referencias existentes. (En modo interactivo, esto sucede después de cada declaración ejecutada por el intérprete). Implicado por Py_DEBUG.

Consulte Misc/SpecialBuilds.txt en la distribución fuente de Python para obtener información más detallada.

Interfaz binaria de aplicación estable

Tradicionalmente, la API en C de Python cambiará con cada lanzamiento. La mayoría de los cambios serán compatibles con la fuente, generalmente solo agregando API, en lugar de cambiar la API existente o eliminar la API (aunque algunas interfaces se eliminan después de ser desaprobadas primero).

Desafortunadamente, la compatibilidad API no se extiende a la compatibilidad binaria (el ABI). La razón es principalmente la evolución de las definiciones de estructura, donde la adición de un nuevo campo, o el cambio del tipo de campo, puede no romper la API, pero puede romper la ABI. Como consecuencia, los módulos de extensión deben volver a compilarse para cada versión de Python (aunque es posible una excepción en Unix cuando no se utiliza ninguna de las interfaces afectadas). Además, en Windows, los módulos de extensión se vinculan con un pythonXY.dll específico y deben recompilarse para vincularse con uno más nuevo.

Desde Python 3.2, se ha declarado un subconjunto de la API para garantizar un ABI estable. Los módulos de extensión que deseen utilizar esta API (llamada «API limitada») deben definir Py_LIMITED_API. Varios detalles del intérprete se ocultan del módulo de extensión; a cambio, se construye un módulo que funciona en cualquier versión 3.x (x> = 2) sin recompilación.

En algunos casos, el ABI estable debe ampliarse con nuevas funciones. Los módulos de extensión que deseen utilizar estas nuevas API deben establecer Py_LIMITED_API en el valor PY_VERSION_HEX (ver Versiones de API y ABI) de la versión mínima de Python que desean admitir (por ejemplo,``0x03030000`` para Python 3.3). Dichos módulos funcionarán en todas las versiones posteriores de Python, pero no se cargarán (debido a la falta de símbolos) en las versiones anteriores.

A partir de Python 3.2, el conjunto de funciones disponibles para la API limitada se documenta en PEP 384 [https://www.python.org/dev/peps/pep-0384]. En la documentación de la API de C, los elementos de la API que no forman parte de la API limitada se marcan como «No forma parte de la API limitada».

La capa de muy alto nivel

Las funciones en este capítulo te permitirán ejecutar código fuente de Python desde un archivo o un búfer, pero no te permitirán interactuar de una manera detallada con el intérprete.

Varias de estas funciones aceptan un símbolo de inicio de la gramática como parámetro. Los símbolos de inicio disponibles son Py_eval_input, Py_file_input, y Py_single_input. Estos se describen siguiendo las funciones que los aceptan como parámetros.

Tenga en cuenta también que varias de estas funciones toman parámetros FILE*. Una cuestión particular que debe manejarse con cuidado es que la estructura FILE para diferentes bibliotecas en C puede ser diferente e incompatible. En Windows (al menos), es posible que las extensiones vinculadas dinámicamente utilicen diferentes bibliotecas, por lo que se debe tener cuidado de que los parámetros FILE* solo se pasen a estas funciones si es seguro que estaban creado por la misma biblioteca que está utilizando el tiempo de ejecución de Python.

int Py_Main(int argc, wchar_t **argv)

El programa principal para el intérprete estándar. Está disponible para programas que incorporan Python. Los parámetros argc y argv deben prepararse exactamente como los que se pasan a la función main() de un programa en C (convertido a wchar_t de acuerdo con la configuración regional del usuario). Es importante tener en cuenta que la lista de argumentos puede ser modificada (pero el contenido de las cadenas de caracteres señaladas por la lista de argumentos no lo es). El valor de retorno será 0 si el intérprete acaba normalmente (es decir, sin excepción), 1 si el intérprete acaba debido a una excepción, o 2 si la lista de parámetros no representa una línea de comando Python válida.

Tenga en cuenta que si se lanza un SystemExit no manejado, esta función no retornará 1, pero saldrá del proceso, siempre que Py_InspectFlag no esté configurado.

int Py_BytesMain(int argc, char **argv)

Similar a Py_Main() pero argv es un arreglo de cadenas de caracteres de bytes.

Nuevo en la versión 3.8.

int PyRun_AnyFile(FILE *fp, const char *filename)

Esta es una interfaz simplificada para PyRun_AnyFileExFlags() más abajo, dejando closeit establecido a 0 y flags establecido a NULL.

int PyRun_AnyFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

Esta es una interfaz simplificada para PyRun_AnyFileExFlags() más abajo, dejando closeit establecido a 0.

int PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit)

Esta es una interfaz simplificada para PyRun_AnyFileExFlags() más abajo, dejando flags establecido a NULL.

int PyRun_AnyFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)

If fp refers to a file associated with an interactive device (console or terminal input or Unix pseudo-terminal), return the value of PyRun_InteractiveLoop(), otherwise return the result of PyRun_SimpleFile(). filename is decoded from the filesystem encoding (sys.getfilesystemencoding()). If filename is NULL, this function uses "???" as the filename. If closeit is true, the file is closed before PyRun_SimpleFileExFlags() returns.

int PyRun_SimpleString(const char *command)

Esta es una interfaz simplificada para PyRun_SimpleStringFlags() más abajo, dejando el argumento PyCompilerFlags* establecido a NULL.

int PyRun_SimpleStringFlags(const char *command, PyCompilerFlags *flags)

Ejecuta el código fuente de Python desde command en el módulo __main__ de acuerdo con el argumento flags. Si __main__ aún no existe, se crea. Retorna 0 en caso de éxito o -1 si se produjo una excepción. Si hubo un error, no hay forma de obtener la información de excepción. Para el significado de flags, ver abajo.

Tenga en cuenta que si no se maneja de otro modo SystemExit, esta función no retornará -1, pero saldrá del proceso, siempre que Py_InspectFlag no esté configurado.

int PyRun_SimpleFile(FILE *fp, const char *filename)

Esta es una interfaz simplificada para PyRun_SimpleStringFlags() más abajo, dejando closeit establecido a 0 y flags establecido a NULL.

int PyRun_SimpleFileEx(FILE *fp, const char *filename, int closeit)

Esta es una interfaz simplificada para PyRun_SimpleStringFlags() más abajo, dejando flags establecido a NULL.

int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)

Similar a PyRun_SimpleStringFlags(), pero el código fuente de Python se lee desde fp en lugar de una cadena de caracteres en memoria. filename debe ser el nombre del archivo, se decodifica a partir de la codificación del sistema de archivos (sys.getfilesystemencoding()). Si closeit es verdadero, el archivo se cierra antes de que PyRun_SimpleFileExFlags retorne.

Nota

En Windows, fp debe abrirse en modo binario (por ejemplo, fopen(filename, "rb"). De lo contrario, Python puede no manejar correctamente el archivo de script con la terminación de línea LF.

int PyRun_InteractiveOne(FILE *fp, const char *filename)

Esta es una interfaz simplificada para PyRun_InteractiveOneFlags() más abajo, dejando flags establecido a NULL.

int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

Lee y ejecuta declaraciones de un archivo asociado con un dispositivo interactivo de acuerdo al argumento flags. Se le solicitará al usuario usando sys.ps1 y sys.ps2. filename se decodifica a partir de la codificación del sistema de archivos (sys.getfilesystemencoding()).

Retorna 0 cuando la entrada se ejecuta con éxito, -1 si hubo una excepción, o un código de error del archivo errcode.h distribuido como parte de Python si hubo un error de análisis gramatical. (Tenga en cuenta que errcode.h no está incluido en Python.h, por lo que debe incluirse específicamente si es necesario).

int PyRun_InteractiveLoop(FILE *fp, const char *filename)

Esta es una interfaz simplificada para PyRun_InteractiveLoopFlags() más abajo, dejando flags establecido a NULL.

int PyRun_InteractiveLoopFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

Lee y ejecuta declaraciones de un archivo asociado con un dispositivo interactivo hasta llegar al EOF. Se le solicitará al usuario usando sys.ps1 y sys.ps2. filename se decodifica a partir de la codificación del sistema de archivos (sys.getfilesystemencoding()). Retorna 0 en EOF o un número negativo en caso de falla.

int (*PyOS_InputHook)(void)

Se puede configurar para que apunte a una función con el prototipo int func(void). Se llamará a la función cuando el indicador del intérprete de Python esté a punto de estar inactivo y espere la entrada del usuario desde el terminal. El valor de retorno es ignorado. Sobrescribiendo este enlace se puede utilizar para integrar la solicitud del intérprete con otros bucles de eventos, como se hace en Modules/_tkinter.c en el código fuente de Python.

char* (*PyOS_ReadlineFunctionPointer)(FILE *, FILE *, const char *)

Se puede configurar para que apunte a una función con el prototipo char *func (FILE *stdin, FILE *stdout, char *prompt), sobrescribiendo la función predeterminada utilizada para leer una sola línea de entrada desde el intérprete. Se espera que la función genere la cadena de caracteres prompt si no es NULL, y luego lea una línea de entrada del archivo de entrada estándar proporcionado, retornando la cadena de caracteres resultante. Por ejemplo, el módulo readline establece este enlace para proporcionar funciones de edición de línea y finalización de tabulación.

El resultado debe ser una cadena de caracteres alocado por PyMem_RawMalloc() o PyMem_RawRealloc(), o NULL si ocurre un error.

Distinto en la versión 3.4: El resultado debe ser alocado por PyMem_RawMalloc() o PyMem_RawRealloc(), en vez de ser alocado por PyMem_Malloc() o PyMem_Realloc().

struct _node* PyParser_SimpleParseString(const char *str, int start)

Esta es una interfaz simplificada para PyParser_SimpleParseStringFlagsFilename() más abajo, dejando filename establecido a NULL y flags establecido a 0.

Deprecated since version 3.9, will be removed in version 3.10.

struct _node* PyParser_SimpleParseStringFlags(const char *str, int start, int flags)

Esta es una interfaz simplificada para PyParser_SimpleParseStringFlagsFilename() más abajo, dejando filename establecido a NULL.

Deprecated since version 3.9, will be removed in version 3.10.

struct _node* PyParser_SimpleParseStringFlagsFilename(const char *str, const char *filename, int start, int flags)

Analiza gramaticalmente el código fuente de Python desde str usando el token de inicio start de acuerdo con el argumento flags. El resultado se puede usar para crear un objeto de código que se puede evaluar de manera eficiente. Esto es útil si un fragmento de código debe evaluarse muchas veces. filename se decodifica a partir de la codificación del sistema de archivos (sys.getfilesystemencoding()).

Deprecated since version 3.9, will be removed in version 3.10.

struct _node* PyParser_SimpleParseFile(FILE *fp, const char *filename, int start)

Esta es una interfaz simplificada para PyParser_SimpleParseFileFlags() más abajo, dejando flags establecido a 0.

Deprecated since version 3.9, will be removed in version 3.10.

struct _node* PyParser_SimpleParseFileFlags(FILE *fp, const char *filename, int start, int flags)

Similar a PyParser_SimpleParseStringFlagsFilename(), pero el código fuente de Python se lee desde fp en lugar de una cadena de caracteres en memoria.

Deprecated since version 3.9, will be removed in version 3.10.

PyObject* PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)

Return value: New reference.

Esta es una interfaz simplificada para PyRun_StringFlags() más abajo, dejando flags establecido a NULL.

PyObject* PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)

Return value: New reference.

Ejecuta el código fuente de Python desde str en el contexto especificado por los objetos globals y locals con los indicadores del compilador especificados por flags. globals debe ser un diccionario; locals puede ser cualquier objeto que implemente el protocolo de mapeo. El parámetro start especifica el token de inicio que se debe usar para analizar el código fuente.

Retorna el resultado de ejecutar el código como un objeto Python, o NULL” si se produjo una excepción.

PyObject* PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)

Return value: New reference.

Esta es una interfaz simplificada para PyRun_FileExFlags() más abajo, dejando closeit establecido a 0 y flags establecido a NULL.

PyObject* PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)

Return value: New reference.

Esta es una interfaz simplificada para PyRun_FileExFlags() más abajo, dejando flags establecido a NULL.

PyObject* PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)

Return value: New reference.

Esta es una interfaz simplificada para PyRun_FileExFlags() más abajo, dejando closeit establecido a 0.

PyObject* PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)

Return value: New reference.

Similar a PyRun_StringFlags(), pero el código fuente de Python se lee desde fp en lugar de una cadena de caracteres en memoria. filename debe ser el nombre del archivo, se decodifica a partir de la codificación del sistema de archivos (sys.getfilesystemencoding()). Si closeit es verdadero, el archivo se cierra antes que PyRun_FileExFlags() retorne.

PyObject* Py_CompileString(const char *str, const char *filename, int start)

Return value: New reference.

Esta es una interfaz simplificada para Py_CompileStringFlags() más abajo, dejando flags establecido a NULL.

PyObject* Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags)

Return value: New reference.

Esta es una interfaz simplificada para Py_CompileStringExFlags() más abajo, con optimize establecido a -1.

PyObject* Py_CompileStringObject(const char *str, PyObject *filename, int start, PyCompilerFlags *flags, int optimize)

Return value: New reference.

Analiza gramaticalmente y compila el código fuente de Python en str, retornando el objeto de código resultante. El token de inicio viene dado por start; esto se puede usar para restringir el código que se puede compilar y debe ser Py_eval_input, Py_file_input, o Py_single_input. El nombre de archivo especificado por filename se usa para construir el objeto de código y puede aparecer en tracebacks o mensajes de excepción SyntaxError. Esto retorna NULL” si el código no se puede analizar gramaticalmente o compilar.

El número entero optimize especifica el nivel de optimización del compilador; un valor de -1 selecciona el nivel de optimización del intérprete como se indica en las opciones -O. Los niveles explícitos son 0 (sin optimización; __debug__ es verdadero), 1 (los asserts se eliminan, __debug__ es falso) o 2 (los docstrings también se eliminan) )

Nuevo en la versión 3.4.

PyObject* Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize)

Return value: New reference.

Como Py_CompileStringObject(), pero filename es una cadena de caracteres de byte decodificado desde la codificación del sistema de archivos (os.fsdecode()).

Nuevo en la versión 3.2.

PyObject* PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals)

Return value: New reference.

Esta es una interfaz simplificada para PyEval_EvalCodeEx(), con solo el objeto de código y las variables globales y locales. Los otros argumentos están establecidos en NULL.

PyObject* PyEval_EvalCodeEx(PyObject *co, PyObject *globals, PyObject *locals, PyObject *const *args, int argcount, PyObject *const *kws, int kwcount, PyObject *const *defs, int defcount, PyObject *kwdefs, PyObject *closure)

Return value: New reference.

Evaluar un objeto de código precompilado, dado un entorno particular para su evaluación. Este entorno consta de un diccionario de variables globales, un objeto de mapeo de variables locales, arreglos de argumentos, palabras clave y valores predeterminados, un diccionario de valores predeterminados para argumentos keyword-only y una tupla de cierre de células.

PyFrameObject

La estructura en C de los objetos utilizados para describir objetos del marco. Los campos de este tipo están sujetos a cambios en cualquier momento.

PyObject* PyEval_EvalFrame(PyFrameObject *f)

Return value: New reference.

Evaluar un marco de ejecución. Esta es una interfaz simplificada para PyEval_EvalFrameEx(), para compatibilidad con versiones anteriores.

PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)

Return value: New reference.

Esta es la función principal sin barnizar de la interpretación de Python. El objeto de código asociado con el marco de ejecución del marco f se ejecuta, interpretando el código de bytes y ejecutando llamadas según sea necesario. El parámetro adicional throwflag se puede ignorar por lo general; si es verdadero, entonces se genera una excepción de inmediato; esto se usa para los métodos throw() de objetos generadores.

Distinto en la versión 3.4: Esta función ahora incluye una afirmación de depuración para ayudar a garantizar que no descarte silenciosamente una excepción activa.

int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)

Esta función cambia los flags del marco de evaluación actual, y retorna verdad (true) en caso de éxito, falso (false) en caso de fallo.

int Py_eval_input

El símbolo de inicio de la gramática de Python para expresiones aisladas; para usar con Py_CompileString().

int Py_file_input

El símbolo de inicio de la gramática de Python para secuencias de declaración leídos desde un archivo u otra fuente; para usar con Py_CompileString(). Este es el símbolo usado cuando se compile un código fuente en Python arbitrariamente largo.

int Py_single_input

El símbolo de inicio de la gramática de Python para una declaración única; para usar con Py_CompileString(). Este es el símbolo usado para el bucle interactivo del intérprete.

struct PyCompilerFlags

Esta es la estructura usada para contener los flags del compilador. En casos donde el código es sólo compilado, es pasado como int flags, y en casos donde el código es ejecutado, es pasado como PyCompilerFlags *flags. En este caso, from __future__ import puede modificar los flags.

Siempre y cuando PyCompilerFlags *flags es NULL, cf_flags es tratado como igual a 0, y cualquier modificación debido a from __future__ import es descartada.

int cf_flags

Flags del compilador.

int cf_feature_version

cf_feature_version es la versión menor de Python. Debe ser inicializado a PY_MINOR_VERSION.

El campo es ignorado por defecto, es usado si y solo si el flag PyCF_ONLY_AST está configurado en cf_flags.

Distinto en la versión 3.8: Agregado el campo cf_feature_version.

int CO_FUTURE_DIVISION

Este bit puede ser configurado en flags para causar que un operador de división / sea interpretado como una «división real» de acuerdo a PEP 238 [https://www.python.org/dev/peps/pep-0238].

Conteo de referencias

Los macros de esta sección se utilizan para administrar conteos de referencia de objetos Python.

void Py_INCREF(PyObject *o)

Incrementa el conteo de referencia para el objeto o. El objeto no debe ser NULL; si no está seguro de que no sea NULL, use Py_XINCREF().

void Py_XINCREF(PyObject *o)

Incrementa el conteo de referencia para el objeto o. El objeto puede ser NULL, en cuyo caso el macro no tiene efecto.

void Py_DECREF(PyObject *o)

Disminuye el conteo de referencia para el objeto o. El objeto no debe ser NULL; si no está seguro de que no sea NULL, use Py_XDECREF(). Si el conteo de referencia llega a cero, se invoca la función de desasignación del tipo de objeto (que no debe ser NULL).

Advertencia

La función de desasignación puede hacer que se invoque un código arbitrario de Python (por ejemplo, cuando se desasigna una instancia de clase con un método __del__()). Si bien las excepciones en dicho código no se propagan, el código ejecutado tiene acceso libre a todas las variables globales de Python. Esto significa que cualquier objeto al que se pueda acceder desde una variable global debe estar en un estado coherente antes de invocar Py_DECREF(). Por ejemplo, el código para eliminar un objeto de una lista debe copiar una referencia al objeto eliminado en una variable temporal, actualizar la estructura de datos de la lista y luego llamar a Py_DECREF() para la variable temporal.

void Py_XDECREF(PyObject *o)

Disminuye el conteo de referencia para el objeto o. El objeto puede ser NULL, en cuyo caso el macro no tiene efecto; de lo contrario, el efecto es el mismo que para Py_DECREF(), y se aplica la misma advertencia.

void Py_CLEAR(PyObject *o)

Disminuye el conteo de referencia para el objeto o. El objeto puede ser NULL, en cuyo caso el macro no tiene efecto; de lo contrario, el efecto es el mismo que para Py_DECREF(), excepto que el argumento también se establece en NULL. La advertencia para Py_DECREF() no se aplica con respecto al objeto pasado porque el macro usa cuidadosamente una variable temporal y establece el argumento en NULL antes de disminuir su conteo de referencia.

Es una buena idea usar este macro siempre que disminuya el conteo de referencia de un objeto que pueda atravesarse durante la recolección de basura.

Las siguientes funciones son para la incorporación dinámica de Python en tiempo de ejecución: Py_IncRef(PyObject *o), Py_DecRef(PyObject *o). Simplemente son versiones de funciones exportadas de Py_XINCREF() y Py_XDECREF(), respectivamente.

Las siguientes funciones o macros son solo para uso dentro del núcleo del intérprete: _Py_Dealloc(), _Py_ForgetReference(), _Py_NewReference(), así como la variable global _Py_RefTotal.

Manejo de excepciones

Las funciones descritas en este capítulo le permitirán manejar y aumentar las excepciones de Python. Es importante comprender algunos de los conceptos básicos del manejo de excepciones de Python. Funciona de manera similar a la variable POSIX errno: hay un indicador global (por subproceso) del último error que ocurrió. La mayoría de las funciones de C API no borran esto en caso de éxito, pero lo configurarán para indicar la causa del error en caso de falla. La mayoría de las funciones de C API también retornan un indicador de error, generalmente NULL si se supone que retornan un puntero, o -1 si retornan un número entero (excepción: las funciones PyArg_*() retornan 1 para el éxito y 0 para el fracaso).

Concretamente, el indicador de error consta de tres punteros de objeto: el tipo de excepción, el valor de la excepción y el objeto de rastreo. Cualquiera de esos punteros puede ser NULL si no está configurado (aunque algunas combinaciones están prohibidas, por ejemplo, no puede tener un rastreo no NULL si el tipo de excepción es NULL).

Cuando una función debe fallar porque alguna función que llamó falló, generalmente no establece el indicador de error; la función que llamó ya lo configuró. Es responsable de manejar el error y borrar la excepción o regresar después de limpiar cualquier recurso que tenga (como referencias de objetos o asignaciones de memoria); debería no continuar normalmente si no está preparado para manejar el error. Si regresa debido a un error, es importante indicarle a la persona que llama que se ha establecido un error. Si el error no se maneja o se propaga cuidadosamente, es posible que las llamadas adicionales a la API de Python/C no se comporten como se espera y pueden fallar de manera misteriosa.

Nota

El indicador de error es no el resultado de sys.exc_info(). El primero corresponde a una excepción que aún no se detecta (y, por lo tanto, todavía se está propagando), mientras que el segundo retorna una excepción después de que se detecta (y, por lo tanto, ha dejado de propagarse).

Impresión y limpieza

void PyErr_Clear()

Borra el indicador de error. Si el indicador de error no está configurado, no hay efecto.

void PyErr_PrintEx(int set_sys_last_vars)

Imprime un rastreo estándar en sys.stderr y borra el indicador de error. A menos que el error sea un Salida del sistema, en ese caso no se imprime ningún rastreo y el proceso de Python se cerrará con el código de error especificado por la instancia de Salida del sistema.

Llame a esta función solo cuando el indicador de error está configurado. De lo contrario, provocará un error fatal!

Si set_sys_last_vars no es cero, las variables sys.last_type, sys.last_value y sys.last_traceback se establecerán en el tipo, valor y rastreo de la excepción impresa, respectivamente.

void PyErr_Print()

Alias para PyErr_PrintEx(1).

void PyErr_WriteUnraisable(PyObject *obj)

Llama sys.unraisablehook() utilizando la excepción actual y el argumento obj.

Esta función de utilidad imprime un mensaje de advertencia en sys.stderr cuando se ha establecido una excepción, pero es imposible que el intérprete la active. Se usa, por ejemplo, cuando ocurre una excepción en un método __del__().

La función se llama con un solo argumento obj que identifica el contexto en el que ocurrió la excepción que no se evalúa. Si es posible, la repr obj se imprimirá en el mensaje de advertencia.

Se debe establecer una excepción al llamar a esta función.

Lanzando excepciones

Estas funciones lo ayudan a configurar el indicador de error del hilo actual. Por conveniencia, algunas de estas funciones siempre retornarán un puntero NULL para usar en una declaración return.

void PyErr_SetString(PyObject *type, const char *message)

This is the most common way to set the error indicator. The first argument specifies the exception type; it is normally one of the standard exceptions, e.g. PyExc_RuntimeError. You need not increment its reference count. The second argument is an error message; it is decoded from 'utf-8'.

void PyErr_SetObject(PyObject *type, PyObject *value)

Esta función es similar a PyErr_SetString() pero le permite especificar un objeto Python arbitrario para el «valor» de la excepción.

PyObject* PyErr_Format(PyObject *exception, const char *format, ...)

Return value: Always NULL.

Esta función establece el indicador de error y retorna NULL. exception debe ser una clase de excepción Python. El format y los parámetros posteriores ayudan a formatear el mensaje de error; tienen el mismo significado y valores que en PyUnicode_FromFormat(). format es una cadena de caracteres codificada en ASCII.

PyObject* PyErr_FormatV(PyObject *exception, const char *format, va_list vargs)

Return value: Always NULL.

Igual que PyErr_Format(), pero tomando un argumento va_list en lugar de un número variable de argumentos.

Nuevo en la versión 3.5.

void PyErr_SetNone(PyObject *type)

Esta es una abreviatura de PyErr_SetObject(type, Py_None).

int PyErr_BadArgument()

Esta es una abreviatura de PyErr_SetString(PyExc_TypeError, message), donde message indica que se invocó una operación incorporada con un argumento ilegal. Es principalmente para uso interno.

PyObject* PyErr_NoMemory()

Return value: Always NULL.

Esta es una abreviatura de PyErr_SetNone(PyExc_MemoryError); retorna NULL para que una función de asignación de objetos pueda escribir return PyErr_NoMemory(); cuando se queda sin memoria.

PyObject* PyErr_SetFromErrno(PyObject *type)

Return value: Always NULL.

Esta es una función conveniente para generar una excepción cuando una función de biblioteca C ha retornado un error y establece la variable C errno. Construye un objeto tupla cuyo primer elemento es el valor entero errno y cuyo segundo elemento es el mensaje de error correspondiente (obtenido de strerror()), y luego llama a PyErr_SetObject(type , objeto). En Unix, cuando el valor errno es EINTR, que indica una llamada interrumpida del sistema, esto llama PyErr_CheckSignals(), y si eso establece el indicador de error, lo deja configurado a ese. La función siempre retorna NULL, por lo que una función envolvente alrededor de una llamada del sistema puede escribir return PyErr_SetFromErrno (type); cuando la llamada del sistema retorna un error.

PyObject* PyErr_SetFromErrnoWithFilenameObject(PyObject *type, PyObject *filenameObject)

Return value: Always NULL.

Similar a PyErr_SetFromErrno(), con el comportamiento adicional de que si filenameObject * no es ``NULL``, se pasa al constructor de *type como tercer parámetro. En el caso de la excepción OSError, se utiliza para definir el atributo filename de la instancia de excepción.

PyObject* PyErr_SetFromErrnoWithFilenameObjects(PyObject *type, PyObject *filenameObject, PyObject *filenameObject2)

Return value: Always NULL.

Similar a PyErr_SetFromErrnoWithFilenameObject(), pero toma un segundo objeto de nombre de archivo, para generar errores cuando falla una función que toma dos nombres de archivo.

Nuevo en la versión 3.4.

PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)

Return value: Always NULL.

Similar a PyErr_SetFromErrnoWithFilenameObject(), pero el nombre del archivo se da como una cadena de caracteres de C. filename se decodifica a partir de la codificación del sistema de archivos (os.fsdecode()).

PyObject* PyErr_SetFromWindowsErr(int ierr)

Return value: Always NULL.

Esta es una función conveniente para subir WindowsError. Si se llama con ierr de 0, el código de error retornado por una llamada a GetLastError() se usa en su lugar. Llama a la función Win32 FormatMessage() para recuperar la descripción de Windows del código de error proporcionado por ierr o GetLastError(), luego construye un objeto de tupla cuyo primer elemento es el ierr valor y cuyo segundo elemento es el mensaje de error correspondiente (obtenido de FormatMessage()), y luego llama a PyErr_SetObject(PyExc_WindowsError, object). Esta función siempre retorna NULL.

Disponibilidad: Windows.

PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)

Return value: Always NULL.

Similar a PyErr_SetFromWindowsErr(), con un parámetro adicional que especifica el tipo de excepción que se generará.

Disponibilidad: Windows.

PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)

Return value: Always NULL.

Similar a PyErr_SetFromWindowsErrWithFilenameObject(), pero el nombre del archivo se da como una cadena de caracteres de C. filename se decodifica a partir de la codificación del sistema de archivos (os.fsdecode()).

Disponibilidad: Windows.

PyObject* PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)

Return value: Always NULL.

Similar a PyErr_SetFromWindowsErrWithFilenameObject(), con un parámetro adicional que especifica el tipo de excepción que se generará.

Disponibilidad: Windows.

PyObject* PyErr_SetExcFromWindowsErrWithFilenameObjects(PyObject *type, int ierr, PyObject *filename, PyObject *filename2)

Return value: Always NULL.

Similar a PyErr_SetExcFromWindowsErrWithFilenameObject(), pero acepta un segundo objeto de nombre de archivo.

Disponibilidad: Windows.

Nuevo en la versión 3.4.

PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename)

Return value: Always NULL.

Similar a PyErr_SetFromWindowsErrWithFilename(), con un parámetro adicional que especifica el tipo de excepción que se generará.

Disponibilidad: Windows.

PyObject* PyErr_SetImportError(PyObject *msg, PyObject *name, PyObject *path)

Return value: Always NULL.

Esta es una función conveniente para subir ImportError. msg se establecerá como la cadena de mensaje de la excepción. name y path, que pueden ser NULL, se establecerán como atributos respectivos name y path de ImportError.

Nuevo en la versión 3.3.

PyObject* PyErr_SetImportErrorSubclass(PyObject *exception, PyObject *msg, PyObject *name, PyObject *path)

Return value: Always NULL.

Al igual que PyErr_SetImportError() pero esta función permite especificar una subclase de ImportError para aumentar.

Nuevo en la versión 3.6.

void PyErr_SyntaxLocationObject(PyObject *filename, int lineno, int col_offset)

Establece información de archivo, línea y desplazamiento para la excepción actual. Si la excepción actual no es un SyntaxError, establece atributos adicionales, lo que hace que el sub sistema de impresión de excepciones piense que la excepción es SyntaxError.

Nuevo en la versión 3.4.

void PyErr_SyntaxLocationEx(const char *filename, int lineno, int col_offset)

Como PyErr_SyntaxLocationObject(), pero filename es una cadena de bytes decodificada a partir de la codificación del sistema de archivos (os.fsdecode()).

Nuevo en la versión 3.2.

void PyErr_SyntaxLocation(const char *filename, int lineno)

Like PyErr_SyntaxLocationEx(), but the col_offset parameter is omitted.

void PyErr_BadInternalCall()

Esta es una abreviatura de PyErr_SetString(PyExc_SystemError, message), donde message indica que se invocó una operación interna (por ejemplo, una función de Python/C API) con un argumento ilegal. Es principalmente para uso interno.

Emitir advertencias

Use estas funciones para emitir advertencias desde el código C. Reflejan funciones similares exportadas por el módulo Python warnings. Normalmente imprimen un mensaje de advertencia a sys.stderr; sin embargo, también es posible que el usuario haya especificado que las advertencias se conviertan en errores, y en ese caso generarán una excepción. También es posible que las funciones generen una excepción debido a un problema con la maquinaria de advertencia. El valor de retorno es 0 si no se genera una excepción, o -1 si se genera una excepción. (No es posible determinar si realmente se imprime un mensaje de advertencia, ni cuál es el motivo de la excepción; esto es intencional). Si se produce una excepción, la persona que llama debe hacer su manejo normal de excepciones (por ejemplo, referencias propiedad de Py_DECREF() y retornan un valor de error).

int PyErr_WarnEx(PyObject *category, const char *message, Py_ssize_t stack_level)

Emite un mensaje de advertencia. El argumento category es una categoría de advertencia (ver más abajo) o NULL; el argumento message es una cadena de caracteres codificada en UTF-8. stack_level es un número positivo que proporciona una cantidad de marcos de pila; la advertencia se emitirá desde la línea de código que se está ejecutando actualmente en ese marco de pila. Un stack_level de 1 es la función que llama PyErr_WarnEx(), 2 es la función por encima de eso, y así sucesivamente.

Las categorías de advertencia deben ser subclases de PyExc_Warning; PyExc_Warning es una subclase de PyExc_Exception; la categoría de advertencia predeterminada es PyExc_RuntimeWarning. Las categorías de advertencia estándar de Python están disponibles como variables globales cuyos nombres se enumeran en Categorías de advertencia estándar.

Para obtener información sobre el control de advertencia, consulte la documentación del módulo warnings y la opción -W en la documentación de la línea de comandos. No hay API de C para el control de advertencia.

int PyErr_WarnExplicitObject(PyObject *category, PyObject *message, PyObject *filename, int lineno, PyObject *module, PyObject *registry)

Issue a warning message with explicit control over all warning attributes. This is a straightforward wrapper around the Python function warnings.warn_explicit(); see there for more information. The module and registry arguments may be set to NULL to get the default effect described there.

Nuevo en la versión 3.4.

int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)

Similar a PyErr_WarnExplicitObject() excepto que message y module son cadenas codificadas UTF-8, y filename se decodifica de la codificación del sistema de archivos (os.fsdecode()).

int PyErr_WarnFormat(PyObject *category, Py_ssize_t stack_level, const char *format, ...)

Función similar a PyErr_WarnEx(), pero usa PyUnicode_FromFormat() para formatear el mensaje de advertencia. format es una cadena de caracteres codificada en ASCII.

Nuevo en la versión 3.2.

int PyErr_ResourceWarning(PyObject *source, Py_ssize_t stack_level, const char *format, ...)

Función similar a PyErr_WarnFormat(), pero category es ResourceWarning y pasa source a warnings.WarningMessage().

Nuevo en la versión 3.6.

Consultando el indicador de error

PyObject* PyErr_Occurred()

Return value: Borrowed reference.

Prueba si el indicador de error está configurado. Si se establece, retorna la excepción type (el primer argumento de la última llamada a una de las funciones PyErr_Set*() o PyErr_Restore()). Si no está configurado, retorna NULL. No posee una referencia al valor de retorno, por lo que no necesita usar Py_DECREF().

La persona que llama debe retener el GIL.

Nota

No compare el valor de retorno con una excepción específica; use PyErr_ExceptionMatches() en su lugar, como se muestra a continuación. (La comparación podría fallar fácilmente ya que la excepción puede ser una instancia en lugar de una clase, en el caso de una excepción de clase, o puede ser una subclase de la excepción esperada).

int PyErr_ExceptionMatches(PyObject *exc)

Equivalente a PyErr_GivenExceptionMatches(PyErr_Occurred(), exc). Esto solo debería llamarse cuando se establece una excepción; se producirá una infracción de acceso a la memoria si no se ha producido ninguna excepción.

int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)

Retorna verdadero si la excepción dada coincide con el tipo de excepción en exc. Si exc es un objeto de clase, esto también retorna verdadero cuando dado es una instancia de una subclase. Si exc es una tupla, se busca una coincidencia en todos los tipos de excepción en la tupla (y recursivamente en sub tuplas).

void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)

Recupere el indicador de error en tres variables cuyas direcciones se pasan. Si el indicador de error no está configurado, configure las tres variables en NULL. Si está configurado, se borrará y usted tendrá una referencia a cada objeto recuperado. El objeto de valor y rastreo puede ser NULL incluso cuando el objeto de tipo no lo es.

Nota

Normalmente, esta función solo la usa el código que necesita capturar excepciones o el código que necesita guardar y restaurar el indicador de error temporalmente, por ejemplo:

{
   PyObject *type, *value, *traceback;
   PyErr_Fetch(&type, &value, &traceback);

   /* ... code that might produce other errors ... */

   PyErr_Restore(type, value, traceback);
}

void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)

Establece el indicador de error de los tres objetos. Si el indicador de error ya está configurado, se borra primero. Si los objetos son NULL, el indicador de error se borra. No pase un tipo NULL y un valor o rastreo no NULL. El tipo de excepción debería ser una clase. No pase un tipo o valor de excepción no válido. (Violar estas reglas causará problemas sutiles más adelante). Esta llamada quita una referencia a cada objeto: debe tener una referencia a cada objeto antes de la llamada y después de la llamada ya no posee estas referencias. (Si no comprende esto, no use esta función. Se lo advertí).

Nota

Normalmente, esta función solo la usa el código que necesita guardar y restaurar el indicador de error temporalmente. Use PyErr_Fetch() para guardar el indicador de error actual.

void PyErr_NormalizeException(PyObject **exc, PyObject **val, PyObject **tb)

Bajo ciertas circunstancias, los valores retornados por PyErr_Fetch() a continuación pueden ser «no normalizados», lo que significa que *exc es un objeto de clase pero *val no es una instancia de la misma clase . Esta función se puede utilizar para crear instancias de la clase en ese caso. Si los valores ya están normalizados, no pasa nada. La normalización retrasada se implementa para mejorar el rendimiento.

Nota

Esta función no establece implícitamente el atributo __traceback__ en el valor de excepción. Si se desea establecer el rastreo de manera adecuada, se necesita el siguiente fragmento adicional:

if (tb != NULL) {
  PyException_SetTraceback(val, tb);
}

void PyErr_GetExcInfo(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)

Recupere la información de excepción, como se conoce de sys.exc_info(). Esto se refiere a una excepción que ya fue capturada, no a una excepción que se planteó recientemente. Retorna nuevas referencias para los tres objetos, cualquiera de los cuales puede ser NULL. No modifica el estado de información de excepción.

Nota

Esta función normalmente no es utilizada por el código que quiere manejar excepciones. En cambio, se puede usar cuando el código necesita guardar y restaurar el estado de excepción temporalmente. Use PyErr_SetExcInfo() para restaurar o borrar el estado de excepción.

Nuevo en la versión 3.3.

void PyErr_SetExcInfo(PyObject *type, PyObject *value, PyObject *traceback)

Establezca la información de excepción, como se conoce de sys.exc_info(). Esto se refiere a una excepción que ya fue capturada, no a una excepción que se planteó recientemente. Esta función roba las referencias de los argumentos. Para borrar el estado de excepción, pase NULL para los tres argumentos. Para ver las reglas generales sobre los tres argumentos, consulte PyErr_Restore().

Nota

Esta función normalmente no es utilizada por el código que quiere manejar excepciones. En cambio, se puede usar cuando el código necesita guardar y restaurar el estado de excepción temporalmente. Use PyErr_GetExcInfo() para leer el estado de excepción.

Nuevo en la versión 3.3.

Manejo de señal

int PyErr_CheckSignals()

Esta función interactúa con el manejo de la señal de Python. Comprueba si se ha enviado una señal a los procesos y, de ser así, invoca el controlador de señal correspondiente. Si el módulo signal es compatible, esto puede invocar un controlador de señal escrito en Python. En todos los casos, el efecto predeterminado para SIGINT es aumentar la excepción KeyboardInterrupt. Si se produce una excepción, se establece el indicador de error y la función retorna -1; de lo contrario, la función retorna 0. El indicador de error puede o no borrarse si se configuró previamente.

void PyErr_SetInterrupt()

Simule el efecto de la llegada de una señal SIGINT. La próxima vez se llama PyErr_CheckSignals(), se llamará al manejador de señal de Python para SIGINT.

Si SIGINT no es manejado por Python (se configuró en signal.SIG_DFL o signal.SIG_IGN), esta función no hace nada.

int PySignal_SetWakeupFd(int fd)

Esta función de utilidad especifica un descriptor de archivo en el que el número de señal se escribe como un solo byte cada vez que se recibe una señal. fd debe ser sin bloqueo. retorna el descriptor de archivo anterior.

El valor -1 desactiva la función; Este es el estado inicial. Esto es equivalente a signal.set_wakeup_fd() en Python, pero sin verificación de errores. fd debe ser un descriptor de archivo válido. La función solo debe llamarse desde el hilo principal.

Distinto en la versión 3.5: En Windows, la función ahora también admite controladores de socket.

Clases de Excepción

PyObject* PyErr_NewException(const char *name, PyObject *base, PyObject *dict)

Return value: New reference.

Esta función de utilidad crea y retorna una nueva clase de excepción. El argumento name debe ser el nombre de la nueva excepción, una cadena de caracteres en C de la forma module.classname. Los argumentos base y dict son normalmente NULL. Esto crea un objeto de clase derivado de Exception (accesible en C como PyExc_Exception).

El atributo __module__ de la nueva clase se establece en la primera parte (hasta el último punto) del argumento name, y el nombre de la clase se establece en la última parte (después del último punto). El argumento base se puede usar para especificar clases base alternativas; puede ser solo una clase o una tupla de clases. El argumento dict se puede usar para especificar un diccionario de variables de clase y métodos.

PyObject* PyErr_NewExceptionWithDoc(const char *name, const char *doc, PyObject *base, PyObject *dict)

Return value: New reference.

Igual que PyErr_NewException(), excepto que la nueva clase de excepción puede recibir fácilmente una cadena de documentación: si doc no es NULL, se utilizará como la cadena de documentación para la clase de excepción.

Nuevo en la versión 3.2.

Objetos Excepción

PyObject* PyException_GetTraceback(PyObject *ex)

Return value: New reference.

Retorna el rastreo asociado con la excepción como una nueva referencia, accesible desde Python a través de __traceback__. Si no hay un rastreo asociado, esto retorna NULL.

int PyException_SetTraceback(PyObject *ex, PyObject *tb)

Establezca el rastreo asociado con la excepción a tb. Use Py_None para borrarlo.

PyObject* PyException_GetContext(PyObject *ex)

Return value: New reference.

Retorna el contexto (otra instancia de excepción durante cuyo manejo ex se generó) asociado con la excepción como una nueva referencia, accesible desde Python a través de __context__. Si no hay un contexto asociado, esto retorna NULL.

void PyException_SetContext(PyObject *ex, PyObject *ctx)

Establece el contexto asociado con la excepción a ctx. Use NULL para borrarlo. No hay verificación de tipo para asegurarse de que ctx es una instancia de excepción. Esto roba una referencia a ctx.

PyObject* PyException_GetCause(PyObject *ex)

Return value: New reference.

Retorna la causa (ya sea una instancia de excepción, o None, establecida por raise ... from ...) asociada con la excepción como una nueva referencia, como accesible desde Python a través de __causa__.

void PyException_SetCause(PyObject *ex, PyObject *cause)

Establece la causa asociada con la excepción a cause. Use NULL para borrarlo. No hay verificación de tipo para asegurarse de que cause sea una instancia de excepción o None. Esto roba una referencia a cause.

__suppress_context__ es implícitamente establecido en True por esta función.

Objectos Unicode de Excepción

Las siguientes funciones se utilizan para crear y modificar excepciones Unicode de C.

PyObject* PyUnicodeDecodeError_Create(const char *encoding, const char *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)

Return value: New reference.

Crea un objeto UnicodeDecodeError con los atributos encoding, object, length, start, end y reason. encoding y reason son cadenas codificadas UTF-8.

PyObject* PyUnicodeEncodeError_Create(const char *encoding, const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)

Return value: New reference.

Crea un objeto UnicodeEncodeError con los atributos encoding, object, length, start, end y reason. encoding y reason son cadenas codificadas UTF-8.

Obsoleto desde la versión 3.3: 3.11

Py_UNICODE está obsoleto desde Python 3.3. Migre por favor a PyObject_CallFunction(PyExc_UnicodeEncodeError, "sOnns", ...).

PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)

Return value: New reference.

Crea un objeto UnicodeTranslateError con los atributos encoding, object, length, start, end y reason. encoding y reason son cadenas codificadas UTF-8.

Obsoleto desde la versión 3.3: 3.11

Py_UNICODE está obsoleto desde Python 3.3. Migre por favor a PyObject_CallFunction(PyExc_UnicodeTranslateError, "sOnns", ...).

PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc)

PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc)

Return value: New reference.

Retorna el atributo encoding del objeto de excepción dado.

PyObject* PyUnicodeDecodeError_GetObject(PyObject *exc)

PyObject* PyUnicodeEncodeError_GetObject(PyObject *exc)

PyObject* PyUnicodeTranslateError_GetObject(PyObject *exc)

Return value: New reference.

Retorna el atributo object del objeto de excepción dado.

int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start)

int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start)

int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start)

Obtiene el atributo start del objeto de excepción dado y lo coloca en *start. start no debe ser NULL. retorna 0 en caso de éxito, -1 en caso de error.

int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start)

int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start)

int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start)

Establece el atributo start del objeto de excepción dado en start. Retorna 0 en caso de éxito, -1 en caso de error.

int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end)

int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end)

int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end)

Obtiene el atributo end del objeto de excepción dado y lo coloca en *end. end no debe ser NULL. retorna 0 en caso de éxito, -1 en caso de error.

int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end)

int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end)

int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end)

Establece el atributo end del objeto de excepción dado en end. Retorna 0 en caso de éxito, -1 en caso de error.

PyObject* PyUnicodeDecodeError_GetReason(PyObject *exc)

PyObject* PyUnicodeEncodeError_GetReason(PyObject *exc)

PyObject* PyUnicodeTranslateError_GetReason(PyObject *exc)

Return value: New reference.

Retorna el atributo reason del objeto de excepción dado.

int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason)

int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason)

int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason)

Establece el atributo reason del objeto de excepción dado en reason. Retorna 0 en caso de éxito, -1 en caso de error.

Control de Recursión

Estas dos funciones proporcionan una forma de realizar llamadas recursivas seguras en el nivel C, tanto en el núcleo como en los módulos de extensión. Son necesarios si el código recursivo no invoca necesariamente el código Python (que rastrea su profundidad de recursión automáticamente). Tampoco son necesarios para las implementaciones de tp_call porque call protocol se encarga del manejo de la recursividad.

int Py_EnterRecursiveCall(const char *where)

Marca un punto donde una llamada recursiva de nivel C está a punto de realizarse.

Si USE_STACKCHECK está definido, esta función verifica si la pila del SO se desbordó usando PyOS_CheckStack(). En este caso, establece un MemoryError y retorna un valor distinto de cero.

La función verifica si se alcanza el límite de recursión. Si este es el caso, se establece a RecursionError y se retorna un valor distinto de cero. De lo contrario, se retorna cero.

where debería ser una cadena de caracteres codificada en UTF-8 como "en la comprobación de instancia" para concatenarse con el mensaje RecursionError causado por el límite de profundidad de recursión.

Distinto en la versión 3.9: Esta función ahora también está disponible en la API limitada.

void Py_LeaveRecursiveCall(void)

Termina una Py_EnterRecursiveCall(). Se debe llamar una vez por cada invocación exitosa de Py_EnterRecursiveCall().

Distinto en la versión 3.9: Esta función ahora también está disponible en la API limitada.

La implementación adecuada de tp_repr para los tipos de contenedor requiere un manejo de recursión especial. Además de proteger la pila, tp_repr también necesita rastrear objetos para evitar ciclos. Las siguientes dos funciones facilitan esta funcionalidad. Efectivamente, estos son los C equivalentes a reprlib.recursive_repr().

int Py_ReprEnter(PyObject *object)

Llamado al comienzo de la implementación tp_repr para detectar ciclos.

Si el objeto ya ha sido procesado, la función retorna un entero positivo. En ese caso, la implementación tp_repr debería retornar un objeto de cadena que indique un ciclo. Como ejemplos, los objetos dict retornan {...} y los objetos list retornan [...].

La función retornará un entero negativo si se alcanza el límite de recursión. En ese caso, la implementación tp_repr normalmente debería retornar NULL.

De lo contrario, la función retorna cero y la implementación tp_repr puede continuar normalmente.

void Py_ReprLeave(PyObject *object)

Termina a Py_ReprEnter(). Se debe llamar una vez por cada invocación de Py_ReprEnter() que retorna cero.

Excepciones Estándar

Todas las excepciones estándar de Python están disponibles como variables globales cuyos nombres son PyExc_ seguidos del nombre de excepción de Python. Estos tienen el tipo PyObject*; todos son objetos de clase. Para completar, aquí están todas las variables:

Nombre en C

Nombre en Python

Notas

PyExc_BaseException

BaseException

1

PyExc_Exception

Exception

1

PyExc_ArithmeticError

ArithmeticError

1

PyExc_AssertionError

AssertionError

PyExc_AttributeError

AttributeError

PyExc_BlockingIOError

BlockingIOError

PyExc_BrokenPipeError

BrokenPipeError

PyExc_BufferError

BufferError

PyExc_ChildProcessError

ChildProcessError

PyExc_ConnectionAbortedError

ConnectionAbortedError

PyExc_ConnectionError

ConnectionError

PyExc_ConnectionRefusedError

ConnectionRefusedError

PyExc_ConnectionResetError

ConnectionResetError

PyExc_EOFError

EOFError

PyExc_FileExistsError

FileExistsError

PyExc_FileNotFoundError

FileNotFoundError

PyExc_FloatingPointError

FloatingPointError

PyExc_GeneratorExit

GeneratorExit

PyExc_ImportError

ImportError

PyExc_IndentationError

IndentationError

PyExc_IndexError

IndexError

PyExc_InterruptedError

InterruptedError

PyExc_IsADirectoryError

IsADirectoryError

PyExc_KeyError

KeyError

PyExc_KeyboardInterrupt

KeyboardInterrupt

PyExc_LookupError

LookupError

1

PyExc_MemoryError

MemoryError

PyExc_ModuleNotFoundError

ModuleNotFoundError

PyExc_NameError

NameError

PyExc_NotADirectoryError

NotADirectoryError

PyExc_NotImplementedError

NotImplementedError

PyExc_OSError

OSError

1

PyExc_OverflowError

OverflowError

PyExc_PermissionError

PermissionError

PyExc_ProcessLookupError

ProcessLookupError

PyExc_RecursionError

RecursionError

PyExc_ReferenceError

ReferenceError

PyExc_RuntimeError

RuntimeError

PyExc_StopAsyncIteration

StopAsyncIteration

PyExc_StopIteration

StopIteration

PyExc_SyntaxError

SyntaxError

PyExc_SystemError

SystemError

PyExc_SystemExit

SystemExit

PyExc_TabError

TabError

PyExc_TimeoutError

TimeoutError

PyExc_TypeError

TypeError

PyExc_UnboundLocalError

UnboundLocalError

PyExc_UnicodeDecodeError

UnicodeDecodeError

PyExc_UnicodeEncodeError

UnicodeEncodeError

PyExc_UnicodeError

UnicodeError

PyExc_UnicodeTranslateError

UnicodeTranslateError

PyExc_ValueError

ValueError

PyExc_ZeroDivisionError

ZeroDivisionError

Nuevo en la versión 3.3: PyExc_BlockingIOError, PyExc_BrokenPipeError, PyExc_ChildProcessError, PyExc_ConnectionError, PyExc_ConnectionAbortedError, PyExc_ConnectionRefusedError, PyExc_ConnectionResetError, PyExc_FileExistsError, PyExc_FileNotFoundError, PyExc_InterruptedError, PyExc_IsADirectoryError, PyExc_NotADirectoryError, PyExc_PermissionError, PyExc_ProcessLookupError y PyExc_TimeoutError fueron introducidos luego de PEP 3151 [https://www.python.org/dev/peps/pep-3151].

Nuevo en la versión 3.5: PyExc_StopAsyncIteration y PyExc_RecursionError.

Nuevo en la versión 3.6: PyExc_ModuleNotFoundError.

Estos son alias de compatibilidad para PyExc_OSError:

Nombre en C

Notas

PyExc_EnvironmentError

PyExc_IOError

PyExc_WindowsError

2

Distinto en la versión 3.3: Estos alias solían ser tipos de excepción separados.

Notas:

1(1,2,3,4,5)

Esta es una clase base para otras excepciones estándar.

2

Solo se define en Windows; proteja el código que usa esto probando que la macro del preprocesador MS_WINDOWS está definida.

Categorías de advertencia estándar

Todas las categorías de advertencia estándar de Python están disponibles como variables globales cuyos nombres son PyExc_ seguidos del nombre de excepción de Python. Estos tienen el tipo PyObject*; todos son objetos de clase. Para completar, aquí están todas las variables:

Nombre en C

Nombre en Python

Notas

PyExc_Warning

Warning

3

PyExc_BytesWarning

BytesWarning

PyExc_DeprecationWarning

DeprecationWarning

PyExc_FutureWarning

FutureWarning

PyExc_ImportWarning

ImportWarning

PyExc_PendingDeprecationWarning

PendingDeprecationWarning

PyExc_ResourceWarning

ResourceWarning

PyExc_RuntimeWarning

RuntimeWarning

PyExc_SyntaxWarning

SyntaxWarning

PyExc_UnicodeWarning

UnicodeWarning

PyExc_UserWarning

UserWarning

Nuevo en la versión 3.2: PyExc_ResourceWarning.

Notas:

3

Esta es una clase base para otras categorías de advertencia estándar.

Utilidades

Las funciones de este capítulo realizan varias tareas de utilidad, que van desde ayudar a que el código C sea más portátil en todas las plataformas, usar módulos Python desde C y analizar argumentos de funciones y construir valores Python a partir de valores C.

Utilidades del sistema operativo

Funciones del Sistema

Control de procesos

Importando Módulos

Soporte de empaquetado (marshalling) de datos

Analizando argumentos y construyendo valores

Analizando argumentos

Cadena de caracteres y búferes

Números

Otros objetos

Funciones API

Construyendo valores

Conversión y formato de cadenas de caracteres

Reflexión

Registro de códec y funciones de soporte

API de búsqueda de códec

API de registro para controladores de errores de codificación Unicode

Utilidades del sistema operativo

PyObject* PyOS_FSPath(PyObject *path)

Return value: New reference.

Retorna la representación del sistema de archivos para path. Si el objeto es str o bytes, entonces su conteo de referencias se incrementa. Si el objeto implementa la interfaz os.PathLike, entonces __fspath__() se retorna siempre que sea un objeto str o bytes. De lo contrario TypeError se lanza y se retorna NULL.

Nuevo en la versión 3.6.

int Py_FdIsInteractive(FILE *fp, const char *filename)

Retorna verdadero (distinto de cero) si el archivo de E/S (I/O) estándar fp con nombre filename se considera interactivo. Este es el caso de los archivos para los que isatty(fileno(fp)) es verdadero. Si el indicador global Py_InteractiveFlag es verdadero, esta función también retorna verdadero si el puntero filename es NULL o si el nombre es igual a una de las cadenas de caracteres '<stdin>' o '???'.

void PyOS_BeforeFork()

Función para preparar algún estado interno antes de una bifurcación de proceso (process fork). Esto debería llamarse antes de llamar a fork() o cualquier función similar que clone el proceso actual. Solo disponible en sistemas donde fork() está definido.

Advertencia

La llamada C fork() solo debe hacerse desde hilo «principal» (del intérprete «principal»). Lo mismo es cierto para PyOS_BeforeFork().

Nuevo en la versión 3.7.

void PyOS_AfterFork_Parent()

Función para actualizar algún estado interno después de una bifurcación de proceso. Se debe invocar desde el proceso principal después de llamar a fork() o cualquier función similar que clone el proceso actual, independientemente de si la clonación del proceso fue exitosa. Solo disponible en sistemas donde fork() está definido.

Advertencia

La llamada C fork() solo debe hacerse desde hilo «principal» (del intérprete «principal»). Lo mismo es cierto para PyOS_AfterFork_Parent().

Nuevo en la versión 3.7.

void PyOS_AfterFork_Child()

Función para actualizar el estado del intérprete interno después de una bifurcación de proceso (process fork). Debe llamarse desde el proceso secundario después de llamar a fork(), o cualquier función similar que clone el proceso actual, si existe alguna posibilidad de que el proceso vuelva a llamar al intérprete de Python. Solo disponible en sistemas donde fork() está definido.

Advertencia

La llamada C fork() solo debe hacerse desde hilo «principal» (del intérprete «principal»). Lo mismo es cierto para PyOS_AfterFork_Child().

Nuevo en la versión 3.7.

Ver también

os.register_at_fork() permite registrar funciones personalizadas de Python a las que puede llamar PyOS_BeforeFork(), PyOS_AfterFork_Parent() y PyOS_AfterFork_Child().

void PyOS_AfterFork()

Función para actualizar algún estado interno después de una bifurcación de proceso (process fork); Esto debería llamarse en el nuevo proceso si el intérprete de Python continuará siendo utilizado. Si se carga un nuevo ejecutable en el nuevo proceso, no es necesario llamar a esta función.

Obsoleto desde la versión 3.7: Esta función es reemplazada por PyOS_AfterFork_Child().

int PyOS_CheckStack()

Retorna verdadero cuando el intérprete se queda sin espacio de pila (stack space). Esta es una verificación confiable, pero solo está disponible cuando USE_STACKCHECK está definido (actualmente en Windows usando el compilador Microsoft Visual C++). USE_STACKCHECK se definirá automáticamente; nunca debe cambiar la definición en su propio código.

PyOS_sighandler_t PyOS_getsig(int i)

Retorna el controlador de señal actual para la señal i. Esta es una pequeña envoltura alrededor de sigaction() o signal(). ¡No llame a esas funciones directamente! PyOS_sighandler_t es un alias typedef para void (*)(int).

PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)

Configura el controlador de señal para la señal i como h; retorna el antiguo manejador de señal. Esta es una pequeña envoltura alrededor de sigaction() o signal(). ¡No llame a esas funciones directamente! PyOS_sighandler_t es un alias typedef para void (*)(int).

wchar_t* Py_DecodeLocale(const char* arg, size_t *size)

Decodifica una cadena de bytes de la codificación de configuración regional con controlador de error de subrogateescape: los bytes no codificables se decodifican como caracteres en el rango U+DC80..U+DCFF. Si una secuencia de bytes se puede decodificar como un carácter sustituto, escape los bytes usando el controlador de error de escape sustituto en lugar de decodificarlos.

Codificación, de máxima prioridad a menor prioridad:

`` UTF-8`` en macOS, Android y VxWorks;

UTF-8 en Windows si Py_LegacyWindowsFSEncodingFlag es cero;

`` UTF-8`` si el modo Python UTF-8 está habilitado;

ASCII si la configuración regional LC_CTYPE es "C", nl_langinfo (CODESET) retorna la codificación ASCII (o un alias) y las funciones mbstowcs() y wcstombs() utilizan la codificación ISO-8859-1.

la codificación de la configuración regional actual.

Retorna un puntero a una cadena de caracteres anchos recientemente asignada, use PyMem_RawFree() para liberar la memoria. Si el tamaño no es NULL, escribe el número de caracteres anchos excluyendo el carácter nulo en *size

Retorna NULL en caso de error de decodificación o error de asignación de memoria. Si size no es NULL, *size se establece en (size_t) -1 en caso de error de memoria o en (size_t) -2 en caso de error de decodificación.

Los errores de decodificación nunca deberían ocurrir, a menos que haya un error en la biblioteca C.

Utilice la función Py_EncodeLocale() para codificar la cadena de caracteres en una cadena de bytes.

Ver también

Las funciones PyUnicode_DecodeFSDefaultAndSize() y PyUnicode_DecodeLocaleAndSize().

Nuevo en la versión 3.5.

Distinto en la versión 3.7: La función ahora usa la codificación UTF-8 en el modo UTF-8.

Distinto en la versión 3.8: La función ahora usa la codificación UTF-8 en Windows si Py_LegacyWindowsFSEncodingFlag es cero;

char* Py_EncodeLocale(const wchar_t *text, size_t *error_pos)

Codifica una cadena de caracteres anchos en la codificación de configuración regional con controlador de error de surrogateescape: los caracteres sustitutos en el rango U+DC80..U+DCFF se convierten en bytes 0x80..0xFF.

Codificación, de máxima prioridad a menor prioridad:

`` UTF-8`` en macOS, Android y VxWorks;

UTF-8 en Windows si Py_LegacyWindowsFSEncodingFlag es cero;

`` UTF-8`` si el modo Python UTF-8 está habilitado;

ASCII si la configuración regional LC_CTYPE es "C", nl_langinfo (CODESET) retorna la codificación ASCII (o un alias) y las funciones mbstowcs() y wcstombs() utilizan la codificación ISO-8859-1.

la codificación de la configuración regional actual.

La función utiliza la codificación UTF-8 en el modo Python UTF-8.

Return a pointer to a newly allocated byte string, use PyMem_Free() to free the memory. Return NULL on encoding error or memory allocation error.

Si error_pos no es NULL, *error_pos se establece en (size_t)-1 en caso de éxito, o se establece en el índice del carácter no válido en el error de codificación.

Use la función Py_DecodeLocale() para decodificar la cadena de bytes en una cadena de caracteres anchos.

Ver también

Las funciones PyUnicode_EncodeFSDefault() y PyUnicode_EncodeLocale().

Nuevo en la versión 3.5.

Distinto en la versión 3.7: La función ahora usa la codificación UTF-8 en el modo UTF-8.

Distinto en la versión 3.8: The function now uses the UTF-8 encoding on Windows if Py_LegacyWindowsFSEncodingFlag is zero.

Funciones del Sistema

Estas son funciones de utilidad que hacen que la funcionalidad del módulo sys sea accesible para el código C. Todos funcionan con el diccionario del módulo sys del subproceso actual del intérprete, que está contenido en la estructura interna del estado del subproceso.

PyObject *PySys_GetObject(const char *name)

Return value: Borrowed reference.

Retorna el objeto name del módulo sys o NULL si no existe, sin establecer una excepción.

int PySys_SetObject(const char *name, PyObject *v)

Establece name en el módulo sys en v a menos que v sea NULL, en cuyo caso name se elimina del módulo sys. Retorna 0 en caso de éxito, -1 en caso de error.

void PySys_ResetWarnOptions()

Restablece sys.warnoptions a una lista vacía. Esta función puede llamarse antes de Py_Initialize().

void PySys_AddWarnOption(const wchar_t *s)

Agrega s a sys.warnoptions. Esta función debe llamarse antes de Py_Initialize() para afectar la lista de filtros de advertencias.

void PySys_AddWarnOptionUnicode(PyObject *unicode)

Agrega unicode a sys.warnoptions.

Nota: esta función no se puede utilizar actualmente desde fuera de la implementación de CPython, ya que debe llamarse antes de la importación implícita de warnings en Py_Initialize() para que sea efectiva, pero no se puede llamar hasta que se haya inicializado suficiente tiempo de ejecución para permitir la creación de objetos Unicode.

void PySys_SetPath(const wchar_t *path)

Establece sys.path en un objeto lista de rutas que se encuentra en path, que debería ser una lista de rutas separadas con el delimitador de ruta de búsqueda de la plataforma (: en Unix, ; en Windows )

void PySys_WriteStdout(const char *format, ...)

Escribe la cadena de caracteres de salida descrita por format en sys.stdout. No se lanzan excepciones, incluso si se produce el truncamiento (ver más abajo).

format debe limitar el tamaño total de la cadena de caracteres de salida formateada a 1000 bytes o menos; después de 1000 bytes, la cadena de caracteres de salida se trunca. En particular, esto significa que no deben existir formatos «%s» sin restricciones; estos deben limitarse usando «%.<N>s» donde <N> es un número decimal calculado de modo que <N> más el tamaño máximo de otro texto formateado no exceda los 1000 bytes. También tenga cuidado con «%f», que puede imprimir cientos de dígitos para números muy grandes.

Si ocurre un problema, o sys.stdout no está configurado, el mensaje formateado se escribe en el real (nivel C) stdout.

void PySys_WriteStderr(const char *format, ...)

Como PySys_WriteStdout(), pero escribe a sys.stderr o stderr en su lugar.

void PySys_FormatStdout(const char *format, ...)

Función similar a PySys_WriteStdout() pero formatea el mensaje usando PyUnicode_FromFormatV() y no trunca el mensaje a una longitud arbitraria.

Nuevo en la versión 3.2.

void PySys_FormatStderr(const char *format, ...)

Como PySys_FormatStdout(), pero escribe a sys.stderr o stderr en su lugar.

Nuevo en la versión 3.2.

void PySys_AddXOption(const wchar_t *s)

Analiza (parse) s como un conjunto de opciones -X y los agrega a la asignación de opciones actual tal como lo retorna PySys_GetXOptions(). Esta función puede llamarse antes de Py_Initialize().

Nuevo en la versión 3.2.

PyObject *PySys_GetXOptions()

Return value: Borrowed reference.

Retorna el diccionario actual de opciones -X, de manera similar a sys._xoptions. En caso de error, se retorna NULL y se establece una excepción.

Nuevo en la versión 3.2.

int PySys_Audit(const char *event, const char *format, ...)

Lanza un evento de auditoría con cualquier gancho activo. Retorna cero para el éxito y no cero con una excepción establecida en caso de error.

Si se han agregado ganchos, format y otros argumentos se utilizarán para construir una tupla para pasar. Además de N, están disponibles los mismos caracteres de formato que los utilizados en Py_BuildValue(). Si el valor generado no es una tupla, se agregará a una tupla de un solo elemento. (La opción de formato N consume una referencia, pero dado que no hay forma de saber si se consumirán argumentos para esta función, su uso puede causar fugas de referencia).

Note that # format characters should always be treated as Py_ssize_t, regardless of whether PY_SSIZE_T_CLEAN was defined.

sys.audit() realiza la misma función del código Python.

Nuevo en la versión 3.8.

Distinto en la versión 3.8.2: Require Py_ssize_t for # format characters. Previously, an unavoidable deprecation warning was raised.

int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData)

Append the callable hook to the list of active auditing hooks. Return zero on success and non-zero on failure. If the runtime has been initialized, also set an error on failure. Hooks added through this API are called for all interpreters created by the runtime.

El puntero userData se pasa a la función gancho. Dado que las funciones de enlace pueden llamarse desde diferentes tiempos de ejecución, este puntero no debe referirse directamente al estado de Python.

Es seguro llamar a esta función antes de Py_Initialize(). Cuando se llama después de la inicialización del tiempo de ejecución, se notifican los enlaces de auditoría existentes y pueden anular silenciosamente la operación al generar un error subclasificado de Excepción (otros errores no se silenciarán).

La función gancho (hook) es de tipo int (*)(const char *event, PyObject *args, void *userData), donde args está garantizado como un PyTupleObject. La función gancho siempre se llama con el GIL en poder del intérprete de Python que lanzó el evento.

Ver PEP 578 [https://www.python.org/dev/peps/pep-0578] para una descripción detallada de la auditoría. Las funciones en el tiempo de ejecución y la biblioteca estándar que generan eventos se enumeran en table de eventos de auditoria. Los detalles se encuentran en la documentación de cada función.

Lanza un evento de auditoria sys.addaudithook sin argumentos.

Nuevo en la versión 3.8.

Control de procesos

void Py_FatalError(const char *message)

Imprime un mensaje de error fatal y elimina el proceso. No se realiza limpieza. Esta función solo debe invocarse cuando se detecta una condición que haría peligroso continuar usando el intérprete de Python; por ejemplo, cuando la administración del objeto parece estar dañada. En Unix, se llama a la función de biblioteca C estándar abort() que intentará producir un archivo core.

La función Py_FatalError() se reemplaza con una macro que registra automáticamente el nombre de la función actual, a menos que se defina la macro Py_LIMITED_API.

Distinto en la versión 3.9: Registra el nombre de la función automáticamente.

void Py_Exit(int status)

Sale del proceso actual. Esto llama Py_FinalizeEx() y luego llama a la función estándar de la biblioteca C exit(status). Si Py_FinalizeEx() indica un error, el estado de salida se establece en 120.

Distinto en la versión 3.6: Los errores de finalización ya no se ignoran.

int Py_AtExit(void (*func)())

Registra una función de limpieza a la que llamará Py_FinalizeEx(). Se llamará a la función de limpieza sin argumentos y no debería retornar ningún valor. Como máximo se pueden registrar 32 funciones de limpieza. Cuando el registro es exitoso, Py_AtExit() retorna 0; en caso de error, retorna -1. La última función de limpieza registrada se llama primero. Cada función de limpieza se llamará como máximo una vez. Dado que la finalización interna de Python se habrá completado antes de la función de limpieza, func no debería llamar a las API de Python.

Importando Módulos

PyObject* PyImport_ImportModule(const char *name)

Return value: New reference.

Esta es una interfaz simplificada para PyImport_ImportModuleEx() a continuación, dejando los argumentos globals y locals establecidos en NULL y level establecidos en 0. Cuando el argumento name contiene un punto (cuando especifica un submódulo de un paquete), el argumento fromlist se establece en la lista ['*'] para que el valor de retorno sea el módulo con nombre en lugar del paquete de nivel superior que lo contiene como lo haría de lo contrario sea el caso. (Desafortunadamente, esto tiene un efecto secundario adicional cuando name de hecho especifica un subpaquete en lugar de un submódulo: los submódulos especificados en la variable __all__ del paquete están cargados). Retorna una nueva referencia al módulo importado, o NULL con una excepción establecida en caso de error. Una importación fallida de un módulo no deja el módulo en sys.modules.

Esta función siempre usa importaciones absolutas.

PyObject* PyImport_ImportModuleNoBlock(const char *name)

Return value: New reference.

Esta función es un alias obsoleto de PyImport_ImportModule().

Distinto en la versión 3.3: Esta función solía fallar inmediatamente cuando el bloqueo de importación era retenido por otro hilo. Sin embargo, en Python 3.3, el esquema de bloqueo cambió a bloqueos por módulo para la mayoría de los propósitos, por lo que el comportamiento especial de esta función ya no es necesario.

PyObject* PyImport_ImportModuleEx(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)

Return value: New reference.

Importa un módulo. Esto se describe mejor haciendo referencia a la función Python incorporada __import__().

El valor de retorno es una nueva referencia al módulo importado o paquete de nivel superior, o NULL con una excepción establecida en caso de error. Al igual que para __import__(), el valor de retorno cuando se solicitó un submódulo de un paquete normalmente es el paquete de nivel superior, a menos que se proporcione un fromlist no vacío.

Las importaciones que fallan eliminan objetos de módulo incompletos, como con PyImport_ImportModule().

PyObject* PyImport_ImportModuleLevelObject(PyObject *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)

Return value: New reference.

Importa un módulo. Esto se describe mejor haciendo referencia a la función Python incorporada __import__(), ya que la función estándar __import__() llama a esta función directamente.

El valor de retorno es una nueva referencia al módulo importado o paquete de nivel superior, o NULL con una excepción establecida en caso de error. Al igual que para __import__(), el valor de retorno cuando se solicitó un submódulo de un paquete normalmente es el paquete de nivel superior, a menos que se proporcione un fromlist no vacío.

Nuevo en la versión 3.3.

PyObject* PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)

Return value: New reference.

Similar a PyImport_ImportModuleLevelObject(), pero el nombre es una cadena de caracteres codificada UTF-8 en lugar de un objeto Unicode.

Distinto en la versión 3.3: Los valores negativos para level ya no se aceptan.

PyObject* PyImport_Import(PyObject *name)

Return value: New reference.

Esta es una interfaz de nivel superior que llama a la «función de enlace de importación» actual (con un nivel explícito de 0, que significa importación absoluta). Invoca la función __import__() de las __builtins__ de los globales (globals) actuales. Esto significa que la importación se realiza utilizando los ganchos de importación instalados en el entorno actual.

Esta función siempre usa importaciones absolutas.

PyObject* PyImport_ReloadModule(PyObject *m)

Return value: New reference.

Recarga un módulo. Retorna una nueva referencia al módulo recargado, o NULL con una excepción establecida en caso de error (el módulo todavía existe en este caso).

PyObject* PyImport_AddModuleObject(PyObject *name)

Return value: Borrowed reference.

Retorna el objeto módulo correspondiente a un nombre de módulo. El argumento name puede tener la forma package.module. Primero revise el diccionario de módulos si hay uno allí, y si no, crea uno nuevo y lo agrega al diccionario de módulos. Retorna NULL con una excepción establecida en caso de error.

Nota

Esta función no carga ni importa el módulo; si el módulo no estaba cargado, obtendrá un objeto de módulo vacío. Utilice PyImport_ImportModule() o una de sus variantes para importar un módulo. Las estructuras de paquete implicadas por un nombre punteado para name no se crean si aún no están presentes.

Nuevo en la versión 3.3.

PyObject* PyImport_AddModule(const char *name)

Return value: Borrowed reference.

Similar a PyImport_AddModuleObject(), pero el nombre es una cadena de caracteres codificada UTF-8 en lugar de un objeto Unicode.

PyObject* PyImport_ExecCodeModule(const char *name, PyObject *co)

Return value: New reference.

Dado un nombre de módulo (posiblemente de la forma package.module) y un objeto código leído desde un archivo de bytecode de Python u obtenido de la función incorporada compile(), carga el módulo. Retorna una nueva referencia al objeto módulo, o NULL con una excepción establecida si se produjo un error. name se elimina de sys.modules en casos de error, incluso si name ya estaba en sys.modules en la entrada a PyImport_ExecCodeModule(). Dejar módulos inicializados de forma incompleta en sys.modules es peligroso, ya que las importaciones de dichos módulos no tienen forma de saber que el objeto del módulo es un estado desconocido (y probablemente dañado con respecto a las intenciones del autor del módulo).

Los módulos __spec__ y __loader__ se establecerán, si no se han configurado ya, con los valores apropiados. El cargador de la especificación se establecerá en el módulo __loader__ (si está configurado) y en una instancia de SourceFileLoader de lo contrario.

El atributo del módulo __file__ se establecerá en el objeto código co_filename. Si corresponde, también se establecerá __cached__.

Esta función volverá a cargar el módulo si ya se importó. Consulte PyImport_ReloadModule() para conocer la forma prevista de volver a cargar un módulo.

Si name apunta a un nombre punteado de la forma package.module, cualquier estructura de paquete que no se haya creado aún no se creará.

Ver también PyImport_ExecCodeModuleEx() y PyImport_ExecCodeModuleWithPathnames().

PyObject* PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname)

Return value: New reference.

Como PyImport_ExecCodeModule(), pero el atributo __file__ del objeto del módulo se establece en pathname si no es NULL.

Ver también PyImport_ExecCodeModuleWithPathnames().

PyObject* PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)

Return value: New reference.

Como PyImport_ExecCodeModuleEx(), pero el atributo __cached__ del objeto módulo se establece en cpathname si no es NULL. De las tres funciones, esta es la recomendada para usar.

Nuevo en la versión 3.3.

PyObject* PyImport_ExecCodeModuleWithPathnames(const char *name, PyObject *co, const char *pathname, const char *cpathname)

Return value: New reference.

Como PyImport_ExecCodeModuleObject(), pero name, pathname y cpathname son cadenas de caracteres codificadas UTF-8. También se intenta averiguar cuál debe ser el valor de pathname de cpathname si el primero se establece en NULL.

Nuevo en la versión 3.2.

Distinto en la versión 3.3: Utiliza imp.source_from_cache() para calcular la ruta de origen si solo se proporciona la ruta del bytecode.

long PyImport_GetMagicNumber()

Retorna el número mágico para los archivos de bytecode de Python (también conocido como archivos .pyc). El número mágico debe estar presente en los primeros cuatro bytes del archivo de código de bytes, en orden de bytes little-endian. Retorna -1 en caso de error.

Distinto en la versión 3.3: Retorna un valor de -1 en caso de error.

const char * PyImport_GetMagicTag()

Retorna la cadena de caracteres de etiqueta mágica para nombres de archivo de código de bytes Python en formato PEP 3147 [https://www.python.org/dev/peps/pep-3147]. Tenga en cuenta que el valor en sys.implementation.cache_tag es autoritario y debe usarse en lugar de esta función.

Nuevo en la versión 3.2.

PyObject* PyImport_GetModuleDict()

Return value: Borrowed reference.

Retorna el diccionario utilizado para la administración del módulo (también conocido como sys.modules). Tenga en cuenta que esta es una variable por intérprete.

PyObject* PyImport_GetModule(PyObject *name)

Return value: New reference.

Retorna el módulo ya importado con el nombre dado. Si el módulo aún no se ha importado, retorna NULL pero no establece un error. Retorna NULL y establece un error si falla la búsqueda.

Nuevo en la versión 3.7.

PyObject* PyImport_GetImporter(PyObject *path)

Return value: New reference.

Retorna un objeto buscador para un elemento path sys.path/pkg.__path__, posiblemente obteniéndolo del diccionario sys.path_importer_cache. Si aún no estaba en caché, atraviesa sys.path_hooks hasta que se encuentre un gancho (hook) que pueda manejar el elemento de ruta. Retorna None si ningún gancho podría; esto le dice a la persona que llama que path based finder no pudo encontrar un buscador para este elemento de ruta. Guarda en el resultado (caché) en sys.path_importer_cache. Retorna una nueva referencia al objeto del buscador.

int PyImport_ImportFrozenModuleObject(PyObject *name)

Return value: New reference.

Carga un módulo congelado llamado name. Retorna 1 para el éxito, 0 si no se encuentra el módulo y -1 con una excepción establecida si falla la inicialización. Para acceder al módulo importado con una carga exitosa, use PyImport_ImportModule(). (Tenga en cuenta el nombre inapropiado — esta función volvería a cargar el módulo si ya se importó).

Nuevo en la versión 3.3.

Distinto en la versión 3.4: El atributo __file__ ya no está establecido en el módulo.

int PyImport_ImportFrozenModule(const char *name)

Similar a PyImport_ImportFrozenModuleObject(), pero el nombre es una cadena de caracteres codificada UTF-8 en lugar de un objeto Unicode.

struct _frozen

Esta es la definición del tipo de estructura para los descriptores de módulos congelados, según lo generado con la herramienta freeze (ver Tools/freeze en la distribución de código fuente de Python). Su definición, que se encuentra en Include/import.h, es:

struct _frozen {
    const char *name;
    const unsigned char *code;
    int size;
};

const struct _frozen* PyImport_FrozenModules

Este puntero se inicializa para apuntar a un arreglo de registros struct _frozen, terminado por uno cuyos miembros son todos NULL o cero. Cuando se importa un módulo congelado, se busca en esta tabla. El código de terceros podría jugar trucos con esto para proporcionar una colección de módulos congelados creada dinámicamente.

int PyImport_AppendInittab(const char *name, PyObject* (*initfunc)(void))

Agrega un solo módulo a la tabla existente de módulos incorporados. Este es un contenedor conveniente PyImport_ExtendInittab(), que retorna -1 si la tabla no se puede extender. El nuevo módulo se puede importar con el nombre name, y utiliza la función initfunc como la función de inicialización llamada en el primer intento de importación. Esto debería llamarse antes de Py_Initialize().

struct _inittab

Estructura que describe una sola entrada en la lista de módulos incorporados. Cada una de estas estructuras proporciona el nombre y la función de inicialización de un módulo incorporado en el intérprete. El nombre es una cadena de caracteres codificada ASCII. Los programas que incorporan Python pueden usar una matriz de estas estructuras junto con PyImport_ExtendInittab() para proporcionar módulos integrados adicionales. La estructura se define en Include/import.h como:

struct _inittab {
    const char *name;           /* ASCII encoded string */
    PyObject* (*initfunc)(void);
};

int PyImport_ExtendInittab(struct _inittab *newtab)

Add a collection of modules to the table of built-in modules. The newtab array must end with a sentinel entry which contains NULL for the name field; failure to provide the sentinel value can result in a memory fault. Returns 0 on success or -1 if insufficient memory could be allocated to extend the internal table. In the event of failure, no modules are added to the internal table. This must be called before Py_Initialize().

If Python is initialized multiple times, PyImport_AppendInittab() or PyImport_ExtendInittab() must be called before each Python initialization.

Soporte de empaquetado (marshalling) de datos

Estas rutinas permiten que el código C funcione con objetos serializados utilizando el mismo formato de datos que el módulo marshal. Hay funciones para escribir datos en el formato de serialización y funciones adicionales que se pueden usar para volver a leer los datos. Los archivos utilizados para almacenar datos ordenados deben abrirse en modo binario.

Los valores numéricos se almacenan con el byte menos significativo primero.

El módulo admite dos versiones del formato de datos: la versión 0 es la versión histórica, la versión 1 comparte cadenas de caracteres internas en el archivo y al desempaquetar (unmarshalling). La versión 2 usa un formato binario para números de punto flotante. Py_MARSHAL_VERSION indica el formato de archivo actual (actualmente 2).

void PyMarshal_WriteLongToFile(long value, FILE *file, int version)

Empaqueta (marshal) un entero long, value, a un archivo file. Esto solo escribirá los 32 bits menos significativos de value; independientemente del tamaño del tipo nativo long. version indica el formato del archivo.

This function can fail, in which case it sets the error indicator. Use PyErr_Occurred() to check for that.

void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)

Empaqueta (marshal) un objeto Python, value, a un archivo file. version indica el formato del archivo.

This function can fail, in which case it sets the error indicator. Use PyErr_Occurred() to check for that.

PyObject* PyMarshal_WriteObjectToString(PyObject *value, int version)

Return value: New reference.

Retorna un objeto de bytes que contiene la representación empaquetada (marshalled) de value. version indica el formato del archivo.

Las siguientes funciones permiten volver a leer los valores empaquetados (marshalled).

long PyMarshal_ReadLongFromFile(FILE *file)

Retorna un C long del flujo de datos en un FILE* abierto para lectura. Solo se puede leer un valor de 32 bits con esta función, independientemente del tamaño nativo de long.

En caso de error, establece la excepción apropiada (EOFError) y retorna -1.

int PyMarshal_ReadShortFromFile(FILE *file)

Retorna un C short desde el flujo de datos en un FILE* abierto para lectura. Solo se puede leer un valor de 16 bits con esta función, independientemente del tamaño nativo de short.

En caso de error, establece la excepción apropiada (EOFError) y retorna -1.

PyObject* PyMarshal_ReadObjectFromFile(FILE *file)

Return value: New reference.

Retorna un objeto Python del flujo de datos en un FILE* abierto para lectura.

En caso de error, establece la excepción apropiada (EOFError, ValueError o TypeError) y retorna NULL.

PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)

Return value: New reference.

Retorna un objeto Python del flujo de datos en un FILE* abierto para lectura. A diferencia de PyMarshal_ReadObjectFromFile(), esta función asume que no se leerán más objetos del archivo, lo que le permite cargar agresivamente los datos del archivo en la memoria para que la deserialización pueda operar desde los datos en la memoria en lugar de leer un byte a la vez desde el archivo. Solo use esta variante si está seguro de que no leerá nada más del archivo.

En caso de error, establece la excepción apropiada (EOFError, ValueError o TypeError) y retorna NULL.

PyObject* PyMarshal_ReadObjectFromString(const char *data, Py_ssize_t len)

Return value: New reference.

Retorna un objeto Python del flujo de datos en un búfer de bytes que contiene len bytes a los que apunta data.

En caso de error, establece la excepción apropiada (EOFError, ValueError o TypeError) y retorna NULL.

Analizando argumentos y construyendo valores

Estas funciones son útiles al crear sus propias funciones y métodos de extensiones. Información y ejemplos adicionales están disponibles en Ampliación e incrustación del intérprete de Python.

Las tres primeras de estas funciones descritas, PyArg_ParseTuple(), PyArg_ParseTupleAndKeywords(), y PyArg_Parse(), todas usan cadenas de caracteres de formato que se utilizan para contarle a la función sobre los argumentos esperados. Las cadenas de caracteres de formato utilizan la misma sintaxis para cada una de estas funciones.

Analizando argumentos

Una cadena de formato consta de cero o más «unidades de formato.» Una unidad de formato describe un objeto Python; por lo general es un solo carácter o una secuencia de unidades formato entre paréntesis. Con unas pocas excepciones, una unidad de formato que no es una secuencia entre paréntesis normalmente corresponde a un único argumento de dirección de estas funciones. En la siguiente descripción, la forma citada es la unidad de formato; la entrada en paréntesis (redondos) es el tipo de objeto Python que coincida con la unidad de formato; y la entrada entre corchetes [cuadrados] es el tipo de la variable(s) C cuya dirección debe ser pasada.

Cadena de caracteres y búferes

Estos formatos permiten acceder a un objeto como un bloque contiguo de memoria. Usted no tiene que proporcionar almacenamiento en bruto para el Unicode o área de bytes retornada.

En general, cuando un formato establece un puntero a un búfer, el búfer es gestionado por el objeto de Python correspondiente, y el búfer comparte la vida útil de este objeto. Usted no tendrá que liberar cualquier memoria usted mismo. Las únicas excepciones son es, es#, et y et#.

Sin embargo, cuando una estructura Py_buffer se llena, la memoria intermedia subyacente está bloqueada de manera que la persona que llama puede posteriormente utilizar la memoria intermedia incluso dentro de un bloque Py_BEGIN_ALLOW_THREADS sin el riesgo de que los datos mutables sean redimensionados o destruidos. Como resultado, usted tiene que llamar PyBuffer_Release() después de haber terminado de procesar los datos (o en caso de aborto temprano).

A menos que se indique lo contrario, los búferes no son terminados en NULL (NUL-terminated).

Algunos formatos requieren bytes-like object de sólo lectura, y establecen un puntero en lugar de una estructura de búfer. Trabajan comprobando que el campo del objeto PyBufferProcs.bf_releasebuffer es NULL, que no permite objetos mutables como bytearray.

Nota

Para todas las variantes de formato de # ( s#, y#, etc.), el tipo del argumento length (int o Py_ssize_t) es controlado por la definición de la macro PY_SSIZE_T_CLEAN antes de incluir Python.h. Si se ha definido la macro, lenght es un Py_ssize_t en lugar de un int. Este comportamiento va a cambiar en futuras versiones de Python para soportar únicamente Py_ssize_t y dejar el soporte de int. Es mejor definir siempre PY_SSIZE_T_CLEAN.

s (str) [const char *]

Convierte un objeto Unicode a un puntero C a una cadena de caracteres. Un puntero a una cadena de caracteres existente se almacena en la variable puntero del carácter cuya dirección se pasa. La cadena de caracteres en C es terminada en NULL. La cadena de caracteres de Python no debe contener puntos de código incrustado nulos; si lo hace, se lanza una excepción ValueError. Los objetos Unicode se convierten en cadenas de caracteres de C utilizando codificación 'utf-8'. Si esta conversión fallase lanza un UnicodeError.

Nota

Este formato no acepta objetos de tipo bytes. Si desea aceptar los caminos del sistema de archivos y convertirlos en cadenas de caracteres C, es preferible utilizar el formato O& con PyUnicode_FSConverter() como convertidor.

Distinto en la versión 3.5: Anteriormente, TypeError se lanzó cuando se encontraron puntos de código nulos incrustados en la cadena de caracteres de Python.

s* (str o bytes-like object) [Py_buffer]

Este formato acepta objetos Unicode, así como objectos de tipo bytes. Llena una estructura Py_buffer proporcionada por la persona que llama. En este caso la cadena de caracteres de C resultante puede contener bytes NUL embebidos. Los objetos Unicode se convierten en cadenas de caracteres C utilizando codificación 'utf-8'.

s# (str, bytes-like object de sólo lectura) [const char *, int o Py_ssize_t]

Como s*, excepto que no acepta los objetos mutables. El resultado se almacena en dos variables de C, la primera un puntero a una cadena de caracteres C, el segundo es su longitud. La cadena de caracteres puede contener caracteres nulos incrustados. Los objetos Unicode se convierten en cadenas de caracteres C utilizando codificación 'utf-8'.

z (str o None) [const char *]

Como s, pero el objeto Python también puede ser None, en cuyo caso el puntero C se establece en NULL.

z* (str, bytes-like object o None) [Py_buffer]

Como s*, pero el objeto Python también puede ser None, en cuyo caso el miembro de buf de la estructura Py_buffer se establece en NULL.

z# (str, bytes-like object de sólo lectura o None) [const char *, int o Py_ssize_t]

Como s#, pero el objeto Python también puede ser None, en cuyo caso el puntero C se establece en NULL.

y (bytes-like object de sólo lectura) [const char *]

Este formato convierte un objecto de tipo bytes a un puntero C a una cadena de caracteres; no acepta objetos Unicode. El búfer de bytes no debe contener bytes nulos incrustados; si lo hace, se lanza una excepción ValueError.

Distinto en la versión 3.5: Anteriormente, TypeError se lanzó cuando bytes nulos incrustados se encontraron en el buffer de bytes.

y* (bytes-like object) [Py_buffer]

Esta variante de s* no acepta objetos Unicode, solamente los objetos de tipo bytes. Esta es la forma recomendada para aceptar datos binarios.

y# (bytes-like object de sólo lectura) [const char *, int o Py_ssize_t]

Esta variante en s# no acepta objetos Unicode, solo objetos similares a bytes.

S (bytes) [PyBytesObject *]

Requiere que el objeto Python es un objeto bytes, sin intentar ninguna conversión. Lanza TypeError si el objeto no es un objeto bytes. La variable C también puede ser declarado como PyObject*.

Y (bytearray) [PyByteArrayObject *]

Requiere que el objeto Python es un objeto bytearray, sin intentar ninguna conversión. Lanza TypeError si el objeto no es un objecto bytearray. La variable C también puede ser declarada como PyObject*.

u (str) [const Py_UNICODE *]

Convierte un objeto Unicode de Python a un puntero a un búfer C NUL terminado de caracteres Unicode. Debe pasar la dirección de una variable de puntero Py_UNICODE, que se llena con el puntero a un búfer Unicode existente. Tenga en cuenta que el ancho de un carácter Py_UNICODE depende de las opciones de compilación (que es 16 o 32 bits). La cadena de Python no debe contener puntos de código incrustado nulos; si lo hace, se lanza una excepción ValueError.

Distinto en la versión 3.5: Anteriormente, TypeError se lanzó cuando se encontraron puntos de código nulos incrustados en la cadena de caracteres de Python.

Deprecated since version 3.3, will be removed in version 3.12: Parte de la API de viejo estilo Py_UNICODE; favor migrar al uso de PyUnicode_AsWideCharString().

u# (str) [const Py_UNICODE *, int o Py_ssize_t]

Esta variante en u almacena en dos variables de C, el primero un puntero a un búfer de datos Unicode, el segundo de su longitud. Esta variante permite puntos de código nulos.

Deprecated since version 3.3, will be removed in version 3.12: Parte de la API de viejo estilo Py_UNICODE; favor migrar al uso de PyUnicode_AsWideCharString().

Z (str o None) [const Py_UNICODE *]

Como u, pero el objeto Python también puede ser None, en cuyo caso el puntero Py_UNICODE se establece en NULL.

Deprecated since version 3.3, will be removed in version 3.12: Parte de la API de viejo estilo Py_UNICODE; favor migrar al uso de PyUnicode_AsWideCharString().

Z# (str o None) [const Py_UNICODE *, int o Py_ssize_t]

Al igual que u#, pero el objeto Python también puede ser None, en cuyo caso el puntero Py_UNICODE se establece en NULL.

Deprecated since version 3.3, will be removed in version 3.12: Parte de la API de viejo estilo Py_UNICODE; favor migrar al uso de PyUnicode_AsWideCharString().

U (str) [PyObject *]

Requiere que el objeto Python es un objeto Unicode, sin intentar ninguna conversión. Lanza TypeError si el objeto no es un objeto Unicode. La variable C también puede ser declarada como PyObject*.

w* (bytes-like object de lectura y escritura) [Py_buffer]

Este formato acepta cualquier objeto que implemente la interfaz del búfer de lectura-escritura. Llena la estructura Py_buffer proporcionada por quien llama. El búfer puede contener bytes nulos incrustados. Quien llama tiene que llamar PyBuffer_Release() cuando termina con el búfer.

es (str) [const char *encoding, char **buffer]

Esta variante en s se usa para codificar Unicode en un búfer de caracteres. Solo funciona para datos codificados sin bytes NUL integrados.

Este formato requiere dos argumentos. El primero solo se usa como entrada, y debe ser const char* que apunta al nombre de una codificación como una cadena de caracteres terminada en NUL, o NULL, en cuyo caso se utiliza la codificación 'utf-8'. Se lanza una excepción si Python no conoce la codificación con nombre. El segundo argumento debe ser char**; el valor del puntero al que hace referencia se establecerá en un búfer con el contenido del texto del argumento. El texto se codificará en la codificación especificada por el primer argumento.

PyArg_ParseTuple() asignará un búfer del tamaño necesitado, copiará los datos codificados en este búfer y ajustará *buffer para referenciar el nuevo almacenamiento asignado. Quien llama es responsable para llamar PyMem_Free() para liberar el búfer asignado después de su uso.

et (str, bytes o bytearray) [const char *encoding, char **buffer]

Igual que es, excepto que los objetos de cadena de caracteres de bytes se pasan sin recodificarlos. En cambio, la implementación supone que el objeto de cadena de caracteres de bytes utiliza la codificación que se pasa como parámetro.

es# (str) [const char *encoding, char **buffer, int o Py_ssize_t *buffer_length]

Esta variante en s# se usa para codificar Unicode en un búfer de caracteres. A diferencia del formato es, esta variante permite datos de entrada que contienen caracteres NUL.

Requiere tres argumentos. El primero solo se usa como entrada, y debe ser const char* que apunta al nombre de una codificación como una cadena de caracteres terminada en NUL, o NULL, en cuyo caso Se utiliza la codificación 'utf-8'. Se lanza una excepción si Python no conoce la codificación con nombre. El segundo argumento debe ser char**; El valor del puntero al que hace referencia se establecerá en un búfer con el contenido del texto del argumento. El texto se codificará en la codificación especificada por el primer argumento. El tercer argumento debe ser un puntero a un entero; el número entero referenciado se establecerá en el número de bytes en el búfer de salida.

Hay dos modos de operación:

Si *buffer señala un puntero NULL, la función asignará un búfer del tamaño necesario, copiará los datos codificados en este búfer y configurará *buffer para hacer referencia al almacenamiento recién asignado. Quien llama es responsable de llamar a PyMem_Free() para liberar el búfer asignado después del uso.

Si *buffer apunta a un puntero no NULL (un búfer ya asignado), PyArg_ParseTuple() usará esta ubicación como el búfer e interpretará el valor inicial de *buffer_length como el tamaño del búfer. Luego copiará los datos codificados en el búfer y los terminará en NUL. Si el búfer no es lo suficientemente grande, se establecerá a ValueError.

En ambos casos, *buffer_length se establece a la longitud de los datos codificados sin el byte NUL final.

et# (str, bytes o bytearray) [const char *encoding, char **buffer, int o Py_ssize_t *buffer_length]

Igual que es#, excepto que los objetos de cadena de caracteres de bytes se pasan sin recodificarlos. En cambio, la implementación supone que el objeto de cadena de caracteres de bytes utiliza la codificación que se pasa como parámetro.

Números

b (int) [unsigned char]

Convierte un entero de Python no negativo en un pequeño int sin signo, almacenado en un unsigned char de C.

B (int) [unsigned char]

Convierte un entero de Python en un pequeño int sin comprobación de desbordamiento, almacenado en un unsigned char de C.

h (int) [short int]

Convierte un entero de Python a un short int de C.

H (int) [unsigned short int]

Convierte un entero de Python a un unsigned short int de C, sin verificación de desbordamiento.

i (int) [int]

Convierte un entero Python a un int de C plano.

I (int) [unsigned int]

Convierte un entero de Python a un unsigned int de C, sin verificación de desbordamiento.

l (int) [long int]

Convierte un entero Python a un long int de C.

k (int) [unsigned long]

Convierte un entero de Python a un unsigned long de C, sin verificación de desbordamiento.

L (int) [long long]

Convierte un entero de Python a un long long de C.

K (int) [unsigned long long]

Convierte un entero de Python a un unsigned long long de C, sin verificación de desbordamiento.

n (int) [Py_ssize_t]

Convierte un entero de Python a un Py_ssize_t de C.

c (bytes o bytearray de largo 1) [char]

Convierte un byte de Python, representado como un objeto bytes o bytearray de longitud 1, a un char de C.

Distinto en la versión 3.3: Permite objetos bytearray.

C (str de largo 1) [int]

Convierte un carácter Python, representado como un objeto str de longitud 1, a un tipo int de C.

f (float) [float]

Convierte un número de punto flotante de Python a un float de C.

d (float) [double]

Convierte un número de punto flotante de Python a un double de C.

D (complex) [Py_complex]

Convierte un número complejo de Python en una estructura Py_complex de C.

Otros objetos

O (object) [PyObject *]

Almacena un objeto Python (sin ninguna conversión) en un puntero de objeto C. El programa C recibe así el objeto real que se pasó. El recuento de referencia del objeto no aumenta. El puntero almacenado no es NULL.

O! (object) [typeobject, PyObject *]

Almacena un objeto Python en un puntero de objeto C. Esto es similar a O, pero toma dos argumentos C: el primero es la dirección de un objeto de tipo Python, el segundo es la dirección de la variable C (de tipo PyObject*) en el que se almacena el puntero del objeto. Si el objeto Python no tiene el tipo requerido, se lanza TypeError.

O& (object) [converter, anything]

Convierte un objeto Python en una variable C a través de una función converter. Esto requiere dos argumentos: el primero es una función, el segundo es la dirección de una variable C (de tipo arbitrario), convertida a void *. La función converter a su vez se llama de la siguiente manera:

status = converter(object, address);

donde object es el objeto de Python a convertir y address es el argumento void* que se pasó a la función PyArg_Parse*(). El status retornado debe ser 1 para una conversión exitosa y 0 si la conversión ha fallado. Cuando la conversión falla, la función converter debería generar una excepción y dejar el contenido de address sin modificar.

Si el converter retorna Py_CLEANUP_SUPPORTED, se puede llamar por segunda vez si el análisis del argumento finalmente falla, dando al convertidor la oportunidad de liberar cualquier memoria que ya haya asignado. En esta segunda llamada, el parámetro object será NULL; address tendrá el mismo valor que en la llamada original.

Distinto en la versión 3.1: Py_CLEANUP_SUPPORTED fue agregada.

p (bool) [int]

Prueba el valor pasado por verdad (un booleano predicado p) y convierte el resultado a su valor entero C verdadero/falso entero equivalente. Establece int en 1 si la expresión era verdadera y 0 si era falsa. Esto acepta cualquier valor válido de Python. Consulte Evaluar como valor verdadero/falso para obtener más información sobre cómo Python prueba los valores por verdad.

Nuevo en la versión 3.3.

(items) (tuple) [matching-items]

El objeto debe ser una secuencia de Python cuya longitud es el número de unidades de formato en items. Los argumentos C deben corresponder a las unidades de formato individuales en items. Las unidades de formato para secuencias pueden estar anidadas.

Es posible pasar enteros «largos» (enteros cuyo valor excede el de la plataforma LONG_MAX), sin embargo, no se realiza una verificación de rango adecuada — los bits más significativos se truncan silenciosamente cuando el campo receptor es demasiado pequeño para recibir el valor (en realidad, la semántica se hereda de las descargas en C — su kilometraje puede variar).

Algunos otros caracteres tienen un significado en una cadena de formato. Esto puede no ocurrir dentro de paréntesis anidados. Son:

|

Indica que los argumentos restantes en la lista de argumentos de Python son opcionales. Las variables C correspondientes a argumentos opcionales deben inicializarse a su valor predeterminado — cuando no se especifica un argumento opcional, PyArg_ParseTuple() no toca el contenido de las variables C correspondientes.

$

PyArg_ParseTupleAndKeywords() solamente: indica que los argumentos restantes en la lista de argumentos de Python son solo palabras clave. Actualmente, todos los argumentos de solo palabras clave también deben ser argumentos opcionales, por lo que | siempre debe especificarse antes de $ en la cadena de formato.

Nuevo en la versión 3.3.

:

La lista de unidades de formato termina aquí; la cadena después de los dos puntos se usa como el nombre de la función en los mensajes de error (el «valor asociado» de la excepción que PyArg_ParseTuple() lanza).

;

La lista de unidades de formato termina aquí; la cadena después del punto y coma se usa como mensaje de error en lugar de del mensaje de error predeterminado. : y ; se excluyen mutuamente.

Tenga en cuenta que las referencias de objetos de Python que se proporcionan a la persona que llama son referencias prestadas (borrowed); ¡no disminuya su conteo de referencias!

Los argumentos adicionales pasados a estas funciones deben ser direcciones de variables cuyo tipo está determinado por la cadena de formato; Estos se utilizan para almacenar valores de la tupla de entrada. Hay algunos casos, como se describe en la lista de unidades de formato anterior, donde estos parámetros se utilizan como valores de entrada; deben coincidir con lo especificado para la unidad de formato correspondiente en ese caso.

Para que la conversión tenga éxito, el objeto arg debe coincidir con el formato y el formato debe estar agotado. En caso de éxito, las funciones PyArg_Parse*() retornan verdadero; de lo contrario, retornan falso y generan una excepción apropiada. Cuando las funciones PyArg_Parse*() fallan debido a un error de conversión en una de las unidades de formato, las variables en las direcciones correspondientes y las siguientes unidades de formato quedan intactas.

Funciones API

int PyArg_ParseTuple(PyObject *args, const char *format, ...)

Analiza los parámetros de una función que solo toma parámetros posicionales en variables locales. Retorna verdadero en el éxito; en caso de fallo, retorna falso y genera la excepción apropiada.

int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)

Idéntico a PyArg_ParseTuple(), excepto que acepta una va_list en lugar de un número variable de argumentos .

int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)

Analiza los parámetros de una función que toma parámetros posicionales y de palabras clave en variables locales. El argumento keywords es un arreglo terminado en NULL de nombres de parámetros de palabras clave. Los nombres vacíos denotan parámetros solo posicionales. Retorna verdadero cuando hay éxito; en caso de fallo, retorna falso y genera la excepción apropiada.

Distinto en la versión 3.6: Soporte agregado para sólo parámetros posicionales.

int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)

Idéntico a PyArg_ParseTupleAndKeywords(), excepto que acepta una va_list en lugar de un número variable de argumentos.

int PyArg_ValidateKeywordArguments(PyObject *)

Asegúrese de que las claves en el diccionario de argumentos de palabras clave son cadenas. Esto solo es necesario si PyArg_ParseTupleAndKeywords() no se utiliza, ya que este último ya hace esta comprobación.

Nuevo en la versión 3.2.

int PyArg_Parse(PyObject *args, const char *format, ...)

Función utilizada para deconstruir las listas de argumentos de las funciones de «estilo antiguo» — estas son funciones que usan el método de análisis de parámetros METH_OLDARGS, que se ha eliminado en Python 3. No se recomienda su uso en el análisis de parámetros en código nuevo, y la mayoría del código en el intérprete estándar se ha modificado para que ya no se use para ese propósito. Sin embargo, sigue siendo una forma conveniente de descomponer otras tuplas, y puede continuar usándose para ese propósito.

int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)

Una forma más simple de recuperación de parámetros que no utiliza una cadena de formato para especificar los tipos de argumentos. Las funciones que utilizan este método para recuperar sus parámetros deben declararse como METH_VARARGS en las tablas de funciones o métodos. La tupla que contiene los parámetros reales debe pasarse como args; en realidad debe ser una tupla. La longitud de la tupla debe ser al menos min y no más de max; min y max pueden ser iguales. Se deben pasar argumentos adicionales a la función, cada uno de los cuales debe ser un puntero a una variable PyObject*; estos se completarán con los valores de args; contendrán referencias prestadas. Las variables que corresponden a parámetros opcionales no dados por args no se completarán; estos deben ser inicializados por quien llama. Esta función retorna verdadero en caso de éxito y falso si args no es una tupla o contiene el número incorrecto de elementos; se establecerá una excepción si hubo una falla.

Este es un ejemplo del uso de esta función, tomado de las fuentes del módulo auxiliar _weakref para referencias débiles:

static PyObject *
weakref_ref(PyObject *self, PyObject *args)
{
    PyObject *object;
    PyObject *callback = NULL;
    PyObject *result = NULL;

    if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {
        result = PyWeakref_NewRef(object, callback);
    }
    return result;
}

La llamada a PyArg_UnpackTuple() en este ejemplo es completamente equivalente a esta llamada a PyArg_ParseTuple():

PyArg_ParseTuple(args, "O|O:ref", &object, &callback)

Construyendo valores

PyObject* Py_BuildValue(const char *format, ...)

Return value: New reference.

Crea un nuevo valor basado en una cadena de formato similar a los aceptados por la familia de funciones PyArg_Parse*() y una secuencia de valores. Retorna el valor o NULL en caso de error; se generará una excepción si se retorna NULL.

Py_BuildValue() no siempre genera una tupla. Construye una tupla solo si su cadena de formato contiene dos o más unidades de formato. Si la cadena de formato está vacía, retorna None; si contiene exactamente una unidad de formato, retorna el objeto que describa esa unidad de formato. Para forzarlo a retornar una tupla de tamaño 0 o uno, paréntesis la cadena de formato.

Cuando los búfer de memoria se pasan como parámetros para suministrar datos para construir objetos, como para los formatos s y s#, los datos requeridos se copian. Las memorias intermedias proporcionadas por quien llama nunca son referenciadas por los objetos creados por Py_BuildValue(). En otras palabras, si su código invoca malloc() y pasa la memoria asignada a Py_BuildValue(), su código es responsable de llamar a free() para esa memoria una vez retorna Py_BuildValue().

En la siguiente descripción, la cadena de caracteres entre comillas, así, es la unidad de formato; la entrada entre paréntesis (redondos) es el tipo de objeto Python que retornará la unidad de formato; y la entrada entre corchetes [cuadrados] es el tipo de los valores C que se pasarán.

Los caracteres espacio, tabulación, dos puntos y coma se ignoran en las cadenas de formato (pero no dentro de las unidades de formato como s#). Esto se puede usar para hacer que las cadenas de formato largo sean un poco más legibles.

s (str o None) [const char *]

Convierte una cadena de caracteres C terminada en nulo en un objeto Python str usando la codificación 'utf-8'. Si el puntero de la cadena de caracteres C es NULL, se usa None.

s# (str o None) [const char *, int o Py_ssize_t]

Convierte una cadena de caracteres de C y su longitud en un objeto Python str utilizando la codificación 'utf-8'. Si el puntero de la cadena de caracteres de C es NULL, la longitud se ignora y se retorna None.

y (bytes) [const char *]

Esto convierte una cadena de caracteres de C en un objeto Python bytes. Si el puntero de la cadena de caracteres de C es NULL, se retorna None.

y# (bytes) [const char *, int o Py_ssize_t]

Esto convierte una cadena de caracteres de C y sus longitudes en un objeto Python. Si el puntero de la cadena de caracteres de C es NULL, se retorna None.

z (str o None) [const char *]

Igual que s.

z# (str o None) [const char *, int o Py_ssize_t]

Igual que s#.

u (str) [const wchar_t *]

Convierte un búfer wchar_t de datos Unicode (UTF-16 o UCS-4) en un objeto Python Unicode. Si el puntero del búfer Unicode es NULL, se retorna None.

u# (str) [const wchar_t *, int o Py_ssize_t]

Convierte un búfer de datos Unicode (UTF-16 o UCS-4) y su longitud en un objeto Python Unicode. Si el puntero del búfer Unicode es NULL, la longitud se ignora y se retorna None.

U (str o None) [const char *]

Igual que s.

U# (str o None) [const char *, int o Py_ssize_t]

Igual que s#.

i (int) [int]

Convierte un int plano de C a un objeto entero de Python.

b (int) [char]

Convierte un char plano de C a un objeto entero de Python.

h (int) [short int]

Convierte un short int plano de C a un objeto entero de Python.

l (int) [long int]

Convierta un long int de C en un objeto entero de Python.

B (int) [unsigned char]

Convierte un unsigned char de C a un entero de Python.

H (int) [unsigned short int]

Convierte un unsigned short int de C a un entero de Python.

I (int) [unsigned int]

Convierte un unsigned int de C a un entero de Python.

k (int) [unsigned long]

Convierte un unsigned long de C a un entero de Python.

L (int) [long long]

Convierte un long long de C en un objeto entero de Python.

K (int) [unsigned long long]

Convierte un unsigned long long de C a un entero de Python.

n (int) [Py_ssize_t]

Convierte un Py_ssize_t de C a un entero de Python.

c (bytes de largo 1) [char]

Convierte un int de C representando un byte a un objecto bytes de Python de largo 1.

C (str de largo 1) [int]

Convierte un int de C representando un carácter a un objecto str de Python de largo 1.

d (float) [double]

Convierte un double de C a un número de punto flotante de Python.

f (float) [float]

Convierte un float de C a un número de punto flotante de Python.

D (complex) [Py_complex *]

Convierte una estructura Py_complex de C en un número complejo de Python.

O (object) [PyObject *]

Pasa un objeto Python sin tocarlo (excepto por su recuento de referencia, que se incrementa en uno). Si el objeto pasado es un puntero NULL, se supone que esto fue causado porque la llamada que produjo el argumento encontró un error y estableció una excepción. Por lo tanto, Py_BuildValue() retornará NULL pero no lanzará una excepción. Si aún no se ha producido ninguna excepción, se establece SystemError.

S (object) [PyObject *]

Igual que O.

N (object) [PyObject *]

Igual que O, excepto que no incrementa el recuento de referencia en el objeto. Útil cuando el objeto se crea mediante una llamada a un constructor de objetos en la lista de argumentos.

O& (object) [converter, anything]

Convierte anything a un objeto Python a través de una función converter. La función se llama con anything (que debería ser compatible con void*) como argumento y debería retornar un «nuevo» objeto de Python, o NULL si se produjo un error.

(items) (tuple) [matching-items]

Convierta una secuencia de valores C en una tupla de Python con el mismo número de elementos.

[items] (list) [matching-items]

Convierte una secuencia de valores C en una lista de Python con el mismo número de elementos.

{items} (dict) [matching-items]

Convierte una secuencia de valores C en un diccionario Python. Cada par de valores C consecutivos agrega un elemento al diccionario, que sirve como clave y valor, respectivamente.

Si hay un error en la cadena de formato, se establece la excepción SystemError y se retorna NULL.

PyObject* Py_VaBuildValue(const char *format, va_list vargs)

Return value: New reference.

Idéntico a Py_BuildValue(), excepto que acepta una va_list en lugar de un número variable de argumentos.

Conversión y formato de cadenas de caracteres

Funciones para conversión de números y salida de cadena de caracteres formateadas.

int PyOS_snprintf(char *str, size_t size, const char *format, ...)

Salida de no más de size bytes a str según la cadena de caracteres de formato format y los argumentos adicionales. Consulte la página de manual de Unix snprintf(3).

int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)

Salida de no más de size bytes a str según la cadena de caracteres de formato format y la lista de argumentos variables va. Página de manual de Unix vsnprintf(3).

PyOS_snprintf() y PyOS_vsnprintf() envuelven las funciones estándar de la biblioteca C snprintf() y vsnprintf(). Su propósito es garantizar un comportamiento consistente en casos de esquina (corner cases), que las funciones del Estándar C no hacen.

Las envolturas aseguran que str[size-1] sea siempre '\0' al retornar. Nunca se escriben más de size bytes (incluido el '\0' del final) en str. Ambas funciones requieren que str != NULL, size > 0 y format != NULL.

Si la plataforma no tiene vsnprintf() y el tamaño del búfer necesario para evitar el truncamiento excede size en más de 512 bytes, Python aborta con a Py_FatalError().

El valor de retorno (rv) para estas funciones debe interpretarse de la siguiente manera:

Cuando 0 <= rv < size, la conversión de salida fue exitosa y los caracteres rv se escribieron en str (excluyendo el byte '\0' final en str[rv]).

Cuando rv >= size, la conversión de salida se truncó y se habría necesitado un búfer con rv + 1 bytes para tener éxito. str[size-1] es '\0' en este caso.

Cuando rv < 0, «sucedió algo malo». str[size-1] es '\0' en este caso también, pero el resto de str no está definido. La causa exacta del error depende de la plataforma subyacente.

Las siguientes funciones proporcionan cadenas de caracteres independientes de la configuración regional para numerar las conversiones.

double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)

Convierte una cadena de caracteres s en un double, generando una excepción de Python en caso de falla. El conjunto de cadenas de caracteres aceptadas corresponde al conjunto de cadenas aceptadas por el constructor de Python float(), excepto que s no debe tener espacios en blanco iniciales o finales. La conversión es independiente de la configuración regional actual.

Si endptr es NULL, convierte toda la cadena de caracteres. Lanza ValueError y retorna -1.0 si la cadena de caracteres no es una representación válida de un número de punto flotante.

Si endptr no es NULL, convierte la mayor cantidad posible de la cadena de caracteres y configura *endptr para que apunte al primer carácter no convertido. Si ningún segmento inicial de la cadena de caracteres es la representación válida de un número de punto flotante, configura *endptr para que apunte al comienzo de la cadena de caracteres, lanza ValueError y retorna -1.0.

Si s representa un valor que es demasiado grande para almacenar en un flotante (por ejemplo, "1e500" es una cadena de caracteres de este tipo en muchas plataformas), entonces si overflow_exception es NULL retorna Py_HUGE_VAL (con un signo apropiado) y no establece ninguna excepción. De lo contrario, overflow_exception debe apuntar a un objeto excepción de Python; lanza esa excepción y retorna -1.0. En ambos casos, configura *endptr para que apunte al primer carácter después del valor convertido.

Si se produce algún otro error durante la conversión (por ejemplo, un error de falta de memoria), establece la excepción Python adecuada y retorna -1.0.

Nuevo en la versión 3.1.

char* PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)

Convierte un double val en una cadena de caracteres usando format_code, precision y flags suministrados.

format_code debe ser uno de 'e', 'E', 'f', 'F', 'g', 'G' or 'r'. Para 'r', la precision suministrada debe ser 0 y se ignora. El código de formato 'r' especifica el formato estándar repr().

flags puede ser cero o más de los valores Py_DTSF_SIGN, Py_DTSF_ADD_DOT_0, o Py_DTSF_ALT, unidos por or (or-ed) juntos:

Py_DTSF_SIGN significa preceder siempre a la cadena de caracteres retornada con un carácter de signo, incluso si val no es negativo.

Py_DTSF_ADD_DOT_0 significa asegurarse de que la cadena de caracteres retornada no se verá como un número entero.

Py_DTSF_ALT significa aplicar reglas de formato «alternativas». Consulte la documentación del especificador PyOS_snprintf`() “#”` para obtener más detalles.

Si ptype no es NULL, el valor al que apunta se establecerá en uno de Py_DTST_FINITE, Py_DTST_INFINITE o Py_DTST_NAN, lo que significa que val es un número finito, un número infinito o no es un número, respectivamente.

El valor de retorno es un puntero a buffer con la cadena de caracteres convertida o NULL si la conversión falla. La persona que llama es responsable de liberar la cadena de caracteres retornada llamando a PyMem_Free().

Nuevo en la versión 3.1.

int PyOS_stricmp(const char *s1, const char *s2)

Comparación no sensible a mayúsculas y minúsculas en cadenas de caracteres. La función se comporta casi de manera idéntica a strcmp(), excepto que ignora el caso.

int PyOS_strnicmp(const char *s1, const char *s2, Py_ssize_t  size)

Comparación no sensible a mayúsculas y minúsculas en cadenas de caracteres. La función se comporta casi de manera idéntica a strncmp(), excepto que ignora el caso.

Reflexión

PyObject* PyEval_GetBuiltins(void)

Return value: Borrowed reference.

Retorna un diccionario de las construcciones en el marco de ejecución actual, o el intérprete del estado del hilo si no se está ejecutando ningún marco actualmente.

PyObject* PyEval_GetLocals(void)

Return value: Borrowed reference.

Retorna un diccionario de las variables locales en el marco de ejecución actual, o NULL si actualmente no se está ejecutando ningún marco.

PyObject* PyEval_GetGlobals(void)

Return value: Borrowed reference.

Retorna un diccionario de las variables globales en el marco de ejecución actual, o NULL si actualmente no se está ejecutando ningún marco.

PyFrameObject* PyEval_GetFrame(void)

Return value: Borrowed reference.

Retorna el marco del estado del hilo actual, que es NULL si actualmente no se está ejecutando ningún marco.

Vea también PyThreadState_GetFrame().

PyFrameObject* PyFrame_GetBack(PyFrameObject *frame)

Obtiene el frame siguiente marco (frame) exterior.

Devuelve una referencia fuerte o NULL si frame no tiene un marco exterior.

frame no debe ser NULL.

Nuevo en la versión 3.9.

PyCodeObject* PyFrame_GetCode(PyFrameObject *frame)

Obtiene el código frame.

Retorna una referencia fuerte.

frame no debe ser NULL. El resultado (código del marco) no puede ser NULL.

Nuevo en la versión 3.9.

int PyFrame_GetLineNumber(PyFrameObject *frame)

Retorna el número de línea que frame está ejecutando actualmente.

frame no debe ser NULL.

const char* PyEval_GetFuncName(PyObject *func)

Retorna el nombre de func si es una función, clase u objeto de instancia; de lo contrario, el nombre del tipo funcs.

const char* PyEval_GetFuncDesc(PyObject *func)

Retorna una cadena de caracteres de descripción, según el tipo de func. Los valores de retorno incluyen «()» para funciones y métodos, «constructor», «instancia» y «objeto». Concatenado con el resultado de PyEval_GetFuncName(), el resultado será una descripción de func.

Registro de códec y funciones de soporte

int PyCodec_Register(PyObject *search_function)

Registra una nueva función de búsqueda de códec.

Como efecto secundario, intenta cargar el paquete encodings, si aún no lo ha hecho, para asegurarse de que siempre esté primero en la lista de funciones de búsqueda.

int PyCodec_KnownEncoding(const char *encoding)

Retorna 1 o 0 dependiendo de si hay un códec registrado para el encoding dado. Esta función siempre finaliza con éxito.

PyObject* PyCodec_Encode(PyObject *object, const char *encoding, const char *errors)

Return value: New reference.

API de codificación genérica basada en códec.

object se pasa a través de la función de codificador encontrada por el encoding dado usando el método de manejo de errores definido por errors. errors pueden ser NULL para usar el método predeterminado definido para el códec. Lanza un LookupError si no se puede encontrar el codificador.

PyObject* PyCodec_Decode(PyObject *object, const char *encoding, const char *errors)

Return value: New reference.

API de decodificación basada en códec genérico.

object se pasa a través de la función de decodificador encontrada por el encoding dado usando el método de manejo de errores definido por errors. errors puede ser NULL para usar el método predeterminado definido para el códec. Lanza un LookupError si no se puede encontrar el codificador.

API de búsqueda de códec

En las siguientes funciones, la cadena de caracteres encoding se busca convertida a todos los caracteres en minúscula, lo que hace que las codificaciones se busquen a través de este mecanismo sin distinción entre mayúsculas y minúsculas. Si no se encuentra ningún códec, se establece un KeyError y se retorna NULL.

PyObject* PyCodec_Encoder(const char *encoding)

Return value: New reference.

Obtiene una función de codificador para el encoding dado.

PyObject* PyCodec_Decoder(const char *encoding)

Return value: New reference.

Obtiene una función de decodificador para el encoding dado.

PyObject* PyCodec_IncrementalEncoder(const char *encoding, const char *errors)

Return value: New reference.

Obtiene un objeto IncrementalEncoder para el encoding dada.

PyObject* PyCodec_IncrementalDecoder(const char *encoding, const char *errors)

Return value: New reference.

Obtiene un objeto IncrementalDecoder para el encoding dado.

PyObject* PyCodec_StreamReader(const char *encoding, PyObject *stream, const char *errors)

Return value: New reference.

Obtiene una función de fábrica StreamReader para el encoding dado.

PyObject* PyCodec_StreamWriter(const char *encoding, PyObject *stream, const char *errors)

Return value: New reference.

Obtiene una función de fábrica StreamWriter por el encoding dado.

API de registro para controladores de errores de codificación Unicode

int PyCodec_RegisterError(const char *name, PyObject *error)

Registra la función de devolución de llamada de manejo de errores error bajo el nombre name dado. Esta función de devolución de llamada será llamada por un códec cuando encuentre caracteres no codificables / bytes no codificables y name se especifica como parámetro de error en la llamada a la función de codificación / decodificación.

La devolución de llamada obtiene un único argumento, una instancia de UnicodeEncodeError, UnicodeDecodeError o UnicodeTranslateError que contiene información sobre la secuencia problemática de caracteres o bytes y su desplazamiento en la cadena original (consulte Objectos Unicode de Excepción para funciones para extraer esta información). La devolución de llamada debe generar la excepción dada o retornar una tupla de dos elementos que contiene el reemplazo de la secuencia problemática, y un número entero que proporciona el desplazamiento en la cadena original en la que se debe reanudar la codificación / decodificación.

Retorna 0 en caso de éxito, -1 en caso de error.

PyObject* PyCodec_LookupError(const char *name)

Return value: New reference.

Busca la función de devolución de llamada de manejo de errores registrada con name. Como caso especial se puede pasar NULL, en cuyo caso se retornará la devolución de llamada de manejo de errores para «estricto».

PyObject* PyCodec_StrictErrors(PyObject *exc)

Return value: Always NULL.

Lanza exc como una excepción.

PyObject* PyCodec_IgnoreErrors(PyObject *exc)

Return value: New reference.

Ignora el error Unicode, omitiendo la entrada defectuosa.

PyObject* PyCodec_ReplaceErrors(PyObject *exc)

Return value: New reference.

Reemplaza el error de codificación Unicode con ? o U+FFFD.

PyObject* PyCodec_XMLCharRefReplaceErrors(PyObject *exc)

Return value: New reference.

Reemplaza el error de codificación Unicode con referencias de caracteres XML.

PyObject* PyCodec_BackslashReplaceErrors(PyObject *exc)

Return value: New reference.

Reemplaza el error de codificación Unicode con escapes de barra invertida (\x, \u y \U).

PyObject* PyCodec_NameReplaceErrors(PyObject *exc)

Return value: New reference.

Reemplaza el error de codificación Unicode con escapes \N{...}.

Nuevo en la versión 3.5.

Capa de objetos abstractos

Las funciones de este capítulo interactúan con los objetos de Python independientemente de su tipo, o con amplias clases de tipos de objetos (por ejemplo, todos los tipos numéricos o todos los tipos de secuencia). Cuando se usan en tipos de objetos para los que no se aplican, generarán una excepción de Python.

No es posible utilizar estas funciones en objetos que no se inicializan correctamente, como un objeto de lista que ha sido creado por PyList_New(), pero cuyos elementos no se han establecido en algunos valores no-``NULL`` aún.

Protocolo de objeto

Protocolo de llamada

El protocolo tp_call

El protocolo vectorcall

Control de recursión

API de soporte para vectorcall

API para invocar objetos

API de soporte de llamadas

Protocolo de números

Protocolo de secuencia

Protocolo de mapeo

Protocolo iterador

Protocolo Búfer

Estructura de búfer

Tipos de solicitud búfer

campos independientes de solicitud

formato de sólo lectura

formas, strides, suboffsets

solicitudes de contigüidad

solicitudes compuestas

Arreglos complejos

Estilo NumPy: forma y strides

Estilo PIL: forma, strides y suboffsets

Funciones relacionadas a búfer

Protocolo de búfer antiguo

Protocolo de objeto

PyObject* Py_NotImplemented

El singleton NotImplemented, se usa para indicar que una operación no está implementada para la combinación de tipos dada.

Py_RETURN_NOTIMPLEMENTED

Maneja adecuadamente el retorno Py_NotImplemented desde una función C (es decir, incremente el recuento de referencias de NotImplemented y lo retorna).

int PyObject_Print(PyObject *o, FILE *fp, int flags)

Imprime un objeto o, en el archivo fp. Retorna -1 en caso de error. El argumento de las banderas se usa para habilitar ciertas opciones de impresión. La única opción actualmente admitida es Py_PRINT_RAW; si se proporciona, se escribe str() del objeto en lugar de repr().

int PyObject_HasAttr(PyObject *o, PyObject *attr_name)

Retorna 1 si o tiene el atributo attr_name, y 0 en caso contrario. Esto es equivalente a la expresión de Python hasattr(o, attr_name). Esta función siempre finaliza exitosamente.

Tenga en cuenta que las excepciones que se producen al llamar a los métodos a __getattr__() y __getattribute__() se suprimirán. Para obtener informe de errores, utilice PyObject_GetAttr() alternativamente.

int PyObject_HasAttrString(PyObject *o, const char *attr_name)

Retorna 1 si o tiene el atributo attr_name, y 0 en caso contrario. Esto es equivalente a la expresión de Python hasattr(o, attr_name). Esta función siempre finaliza exitosamente.

Tenga en cuenta que las excepciones que se producen al llamar a __getattr__() y __getattribute__() y al crear un objeto de cadena temporal se suprimirán. Para obtener informes de errores, utilice PyObject_GetAttrString() en su lugar.

PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name)

Return value: New reference.

Recupera un atributo llamado attr_name del objeto o. Retorna el valor del atributo en caso de éxito o NULL en caso de error. Este es el equivalente de la expresión de Python o.attr_name.

PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name)

Return value: New reference.

Recupera un atributo llamado attr_name del objeto o. Retorna el valor del atributo en caso de éxito o NULL en caso de error. Este es el equivalente de la expresión de Python o.attr_name.

PyObject* PyObject_GenericGetAttr(PyObject *o, PyObject *name)

Return value: New reference.

Función getter de atributo genérico que debe colocarse en la ranura tp_getattro de un objeto tipo. Busca un descriptor en el diccionario de clases en el MRO del objeto, así como un atributo en el objeto __ dict__ (si está presente). Como se describe en Implementando Descriptores, los descriptores de datos tienen preferencia sobre los atributos de instancia, mientras que los descriptores que no son de datos no lo hacen. De lo contrario, se genera un AttributeError.

int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)

Establece el valor del atributo llamado attr_name, para el objeto o, en el valor v. Genera una excepción y retorna -1 en caso de falla; retorna 0 en caso de éxito. Este es el equivalente de la declaración de Python o.attr_name = v.

If v is NULL, the attribute is deleted. This behaviour is deprecated in favour of using PyObject_DelAttr(), but there are currently no plans to remove it.

int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)

Establece el valor del atributo llamado attr_name, para el objeto o, en el valor v. Genera una excepción y retorna -1 en caso de falla; retorna 0 en caso de éxito. Este es el equivalente de la declaración de Python o.attr_name = v.

If v is NULL, the attribute is deleted, but this feature is deprecated in favour of using PyObject_DelAttrString().

int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)

Establecimiento de atributo genérico y función de eliminación que está destinada a colocarse en la ranura de un objeto tipo tp_setattro. Busca un descriptor de datos en el diccionario de clases en el MRO del objeto y, si se encuentra, tiene preferencia sobre la configuración o eliminación del atributo en el diccionario de instancias. De lo contrario, el atributo se establece o elimina en el objeto __dict__ (si está presente). En caso de éxito, se retorna 0; de lo contrario, se genera un AttributeError y se retorna -1.

int PyObject_DelAttr(PyObject *o, PyObject *attr_name)

Elimina el atributo llamado attr_name, para el objeto o. Retorna -1 en caso de falla. Este es el equivalente de la declaración de Python del o.attr_name.

int PyObject_DelAttrString(PyObject *o, const char *attr_name)

Elimina el atributo llamado attr_name, para el objeto o. Retorna -1 en caso de falla. Este es el equivalente de la declaración de Python del o.attr_name.

PyObject* PyObject_GenericGetDict(PyObject *o, void *context)

Return value: New reference.

Una implementación genérica para obtener un descriptor __dict__. Crea el diccionario si es necesario.

Nuevo en la versión 3.3.

int PyObject_GenericSetDict(PyObject *o, PyObject *value, void *context)

Una implementación genérica para el creador de un descriptor __dict__. Esta implementación no permite que se elimine el diccionario.

Nuevo en la versión 3.3.

PyObject* PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)

Return value: New reference.

Compara los valores de o1 y o2 utilizando la operación especificada por opid, que debe ser uno de los siguientes Py_LT, Py_LE, Py_EQ, Py_NE, Py_GT, o Py_GE, correspondiente a <, <=, ==, !=, > o >= respectivamente. Este es el equivalente de la expresión de Python o1 op o2, donde op es el operador correspondiente a opid. Retorna el valor de la comparación en caso de éxito o NULL en caso de error.

int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)

Compara los valores de o1 y o2 utilizando la operación especificada por opid, que debe ser uno de los siguientes Py_LT, Py_LE, Py_EQ, Py_NE, Py_GT, o Py_GE, correspondiente a <, <=, ==, !=, > o >= respectivamente. Retorna -1 en caso de error, 0 si el resultado es falso, 1 en caso contrario. Este es el equivalente de la expresión de Python o1 op o2, donde op es el operador correspondiente a opid.

Nota

Si o1 y o2 son el mismo objeto, PyObject_RichCompareBool() siempre retornará 1 para Py_EQ y 0 para Py_NE.

PyObject* PyObject_Repr(PyObject *o)

Return value: New reference.

Calcula una representación de cadena de caracteres del objeto o. Retorna la representación de cadena de caracteres en caso de éxito, NULL en caso de error. Este es el equivalente de la expresión de Python repr(o). Llamado por la función incorporada repr().

Distinto en la versión 3.4: Esta función ahora incluye una afirmación de depuración para ayudar a garantizar que no descarte silenciosamente una excepción activa.

PyObject* PyObject_ASCII(PyObject *o)

Return value: New reference.

Como PyObject_Repr(), calcula una representación de cadena de caracteres del objeto o, pero escapa los caracteres no ASCII en la cadena de caracteres retornada por PyObject_Repr() con \x, \u o \U escapa. Esto genera una cadena de caracteres similar a la que retorna PyObject_Repr() en Python 2. Llamado por la función incorporada ascii().

PyObject* PyObject_Str(PyObject *o)

Return value: New reference.

Calcula una representación de cadena de caracteres del objeto o. Retorna la representación de cadena de caracteres en caso de éxito, NULL en caso de error. Llamado por la función incorporada str() y, por lo tanto, por la función print().

Distinto en la versión 3.4: Esta función ahora incluye una afirmación de depuración para ayudar a garantizar que no descarte silenciosamente una excepción activa.

PyObject* PyObject_Bytes(PyObject *o)

Return value: New reference.

Calcula una representación de bytes del objeto o. NULL se retorna en caso de error y un objeto de bytes en caso de éxito. Esto es equivalente a la expresión de Python bytes(o), cuando o no es un número entero. A diferencia de bytes(o), se lanza un TypeError cuando o es un entero en lugar de un objeto de bytes con inicialización cero.

int PyObject_IsSubclass(PyObject *derived, PyObject *cls)

Retorna 1 si la clase derived es idéntica o derivada de la clase cls; de lo contrario, retorna 0. En caso de error, retorna -1.

Si cls es una tupla, la verificación se realizará con cada entrada en cls. El resultado será 1 cuando al menos una de las verificaciones retorne 1, de lo contrario será 0.

Si cls tiene un método __subclasscheck__(), se llamará para determinar el estado de la subclase como se describe en PEP 3119 [https://www.python.org/dev/peps/pep-3119]. De lo contrario, derived es una subclase de cls si es una subclase directa o indirecta, es decir, contenida en cls.__ mro__.

Normalmente, solo los objetos clase, es decir, las instancias de type o una clase derivada, se consideran clases. Sin embargo, los objetos pueden anular esto al tener un atributo __bases__ (que debe ser una tupla de clases base).

int PyObject_IsInstance(PyObject *inst, PyObject *cls)

Retorna 1 si inst es una instancia de la clase cls o una subclase de cls, o 0 si no. En caso de error, retorna -1 y establece una excepción.

Si cls es una tupla, la verificación se realizará con cada entrada en cls. El resultado será 1 cuando al menos una de las verificaciones retorne 1, de lo contrario será 0.

Si cls tiene un método __instancecheck__(), se llamará para determinar el estado de la subclase como se describe en PEP 3119 [https://www.python.org/dev/peps/pep-3119]. De lo contrario, inst es una instancia de cls si su clase es una subclase de cls.

Una instancia inst puede anular lo que se considera su clase al tener un atributo __class__.

Un objeto cls puede anular si se considera una clase y cuáles son sus clases base, al tener un atributo __bases__ (que debe ser una tupla de clases base).

Py_hash_t PyObject_Hash(PyObject *o)

Calcula y retorna el valor hash de un objeto o. En caso de fallo, retorna -1. Este es el equivalente de la expresión de Python hash(o).

Distinto en la versión 3.2: The return type is now Py_hash_t. This is a signed integer the same size as Py_ssize_t.

Py_hash_t PyObject_HashNotImplemented(PyObject *o)

Establece un TypeError indicando que type(o) no es hashable y retorna -1. Esta función recibe un tratamiento especial cuando se almacena en una ranura tp_hash, lo que permite que un tipo indique explícitamente al intérprete que no es hashable.

int PyObject_IsTrue(PyObject *o)

Retorna 1 si el objeto o se considera verdadero y 0 en caso contrario. Esto es equivalente a la expresión de Python not not o. En caso de error, retorna -1.

int PyObject_Not(PyObject *o)

Retorna 0 si el objeto o se considera verdadero, y 1 de lo contrario. Esto es equivalente a la expresión de Python not o. En caso de error, retorna -1.

PyObject* PyObject_Type(PyObject *o)

Return value: New reference.

When o is non-NULL, returns a type object corresponding to the object type of object o. On failure, raises SystemError and returns NULL. This is equivalent to the Python expression type(o). This function increments the reference count of the return value. There’s really no reason to use this function instead of the Py_TYPE() function, which returns a pointer of type PyTypeObject*, except when the incremented reference count is needed.

int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)

Retorna verdadero si el objeto o es de tipo type o un subtipo de type. Ambos parámetros no deben ser NULL.

Py_ssize_t PyObject_Size(PyObject *o)

Py_ssize_t PyObject_Length(PyObject *o)

Retorna la longitud del objeto o. Si el objeto o proporciona los protocolos de secuencia y mapeo, se retorna la longitud de la secuencia. En caso de error, se retorna -1. Este es el equivalente a la expresión de Python len(o).

Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t defaultvalue)

Return an estimated length for the object o. First try to return its actual length, then an estimate using __length_hint__(), and finally return the default value. On error return -1. This is the equivalent to the Python expression operator.length_hint(o, defaultvalue).

Nuevo en la versión 3.4.

PyObject* PyObject_GetItem(PyObject *o, PyObject *key)

Return value: New reference.

Retorna el elemento de o correspondiente a la clave key del objeto o NULL en caso de error. Este es el equivalente de la expresión de Python o[key].

int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)

Asigna el objeto key al valor v. Genera una excepción y retorna -1 en caso de error; retorna 0 en caso de éxito. Este es el equivalente de la declaración de Python o[key] = v. Esta función no roba una referencia a v.

int PyObject_DelItem(PyObject *o, PyObject *key)

Elimina la asignación para el objeto key del objeto o. Retorna -1 en caso de falla. Esto es equivalente a la declaración de Python del o[key].

PyObject* PyObject_Dir(PyObject *o)

Return value: New reference.

Esto es equivalente a la expresión de Python dir(o), que retorna una lista (posiblemente vacía) de cadenas de caracteres apropiadas para el argumento del objeto, o NULL si hubo un error. Si el argumento es NULL, es como el Python dir(), que retorna los nombres de los locales actuales; en este caso, si no hay un marco de ejecución activo, se retorna NULL pero PyErr_Occurred() retornará falso.

PyObject* PyObject_GetIter(PyObject *o)

Return value: New reference.

Esto es equivalente a la expresión de Python iter(o). Retorna un nuevo iterador para el argumento del objeto, o el propio objeto si el objeto ya es un iterador. Lanza TypeError y retorna NULL si el objeto no puede iterarse.

Protocolo de llamada

CPython admite dos protocolos de llamada diferentes: tp_call y vectorcall.

El protocolo tp_call

Las instancias de clases que establecen tp_call son invocables. La firma del slot es:

PyObject *tp_call(PyObject *callable, PyObject *args, PyObject *kwargs);

Se realiza una llamada usando una tupla para los argumentos posicionales y un dict para los argumentos de palabras clave, de manera similar a callable(*args, **kwargs) en el código Python. args debe ser no NULL (use una tupla vacía si no hay argumentos) pero kwargs puede ser NULL si no hay argumentos de palabra clave.

Esta convención no solo es utilizada por tp_call: tp_new y tp_init también pasan argumentos de esta manera.

To call an object, use PyObject_Call() or another call API.

El protocolo vectorcall

Nuevo en la versión 3.9.

El protocolo vectorcall se introdujo en PEP 590 [https://www.python.org/dev/peps/pep-0590] como un protocolo adicional para hacer que las llamadas sean más eficientes.

Como regla general, CPython preferirá el vectorcall para llamadas internas si el invocable lo admite. Sin embargo, esta no es una regla estricta. Además, algunas extensiones de terceros usan tp_call directamente (en lugar de usar PyObject_Call()). Por lo tanto, una clase que admita vectorcall también debe implementar tp_call. Además, el invocable debe comportarse de la misma manera independientemente del protocolo que se utilice. La forma recomendada de lograr esto es configurando tp_call en PyVectorcall_Call(). Vale la pena repetirlo:

Advertencia

Una clase que admita vectorcall debe también implementar tp_call con la misma semántica.

Una clase no debería implementar vectorcall si eso fuera más lento que tp_call. Por ejemplo, si el destinatario de la llamada necesita convertir los argumentos a una tupla args y un dict kwargs de todos modos, entonces no tiene sentido implementar vectorcall.

Las clases pueden implementar el protocolo vectorcall habilitando el indicador Py_TPFLAGS_HAVE_VECTORCALL y la configuración tp_vectorcall_offset al desplazamiento dentro de la estructura del objeto donde aparece un vectorcallfunc. Este es un puntero a una función con la siguiente firma:

PyObject *(*vectorcallfunc)(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)

callable es el objeto siendo invocado.

args es un arreglo en C que consta de los argumentos posicionales seguidos por el

valores de los argumentos de la palabra clave. Puede ser NULL si no hay argumentos.

nargsf es el número de argumentos posicionales más posiblemente el

flag PY_VECTORCALL_ARGUMENTS_OFFSET. Para obtener el número real de argumentos posicionales de nargsf, use PyVectorcall_NARGS().

kwnames es una tupla que contiene los nombres de los argumentos de la palabra clave;

en otras palabras, las claves del diccionario kwargs. Estos nombres deben ser cadenas (instancias de str o una subclase) y deben ser únicos. Si no hay argumentos de palabras clave, entonces kwnames puede ser NULL.

PY_VECTORCALL_ARGUMENTS_OFFSET

Si este flag se establece en un argumento vectorcall nargsf, el destinatario de la llamada puede cambiar temporalmente args[-1]. En otras palabras, args apunta al argumento 1 (no 0) en el vector asignado. El destinatario de la llamada debe restaurar el valor de args[-1] antes de regresar.

Para PyObject_VectorcallMethod(), este flag significa en cambio que args[0] puede cambiarse.

Siempre que puedan hacerlo de forma económica (sin asignación adicional), se anima a las personas que llaman a utilizar PY_VECTORCALL_ARGUMENTS_OFFSET. Si lo hace, permitirá que las personas que llaman, como los métodos enlazados, realicen sus llamadas posteriores (que incluyen un argumento self antepuesto) de manera muy eficiente.

Para llamar a un objeto que implementa vectorcall, use una función call API como con cualquier otro invocable. PyObject_Vectorcall() normalmente será más eficiente.

Nota

En CPython 3.8, la API de vectorcall y las funciones relacionadas estaban disponibles provisionalmente bajo nombres con un guión bajo inicial: _PyObject_Vectorcall, _Py_TPFLAGS_HAVE_VECTORCALL, _PyObject_VectorcallMethod, _PyVectorcall_Function, _PyObject_CallMethodNoArgs, _PyObject_CallMethodOneArg. Además, PyObject_VectorcallDict estaba disponible como _PyObject_FastCallDict. Los nombres antiguos todavía se definen como alias de los nuevos nombres no subrayados.

Control de recursión

Cuando se usa tp_call, los destinatarios no necesitan preocuparse por recursividad: CPython usa Py_EnterRecursiveCall() y Py_LeaveRecursiveCall() para llamadas realizadas usando tp_call.

Por eficiencia, este no es el caso de las llamadas realizadas mediante vectorcall: el destinatario de la llamada debe utilizar Py_EnterRecursiveCall y Py_LeaveRecursiveCall si es necesario.

API de soporte para vectorcall

Py_ssize_t PyVectorcall_NARGS(size_t nargsf)

Dado un argumento vectorcall nargsf, retorna el número real de argumentos. Actualmente equivalente a:

(Py_ssize_t)(nargsf & ~PY_VECTORCALL_ARGUMENTS_OFFSET)

Sin embargo, la función PyVectorcall_NARGS debe usarse para permitir futuras extensiones.

Esta función no es parte de la API limitada.

Nuevo en la versión 3.8.

vectorcallfunc PyVectorcall_Function(PyObject *op)

Si op no admite el protocolo vectorcall (ya sea porque el tipo no lo hace o porque la instancia específica no lo hace), retorna NULL. De lo contrario, retorna el puntero de la función vectorcall almacenado en op. Esta función nunca lanza una excepción.

Esto es principalmente útil para verificar si op admite vectorcall, lo cual se puede hacer marcando PyVectorcall_Function(op) != NULL.

Esta función no es parte de la API limitada.

Nuevo en la versión 3.8.

PyObject* PyVectorcall_Call(PyObject *callable, PyObject *tuple, PyObject *dict)

Llama a la vectorcallfunc de callable con argumentos posicionales y de palabras clave dados en una tupla y dict, respectivamente.

Esta es una función especializada, destinada a colocarse en el slot tp_call o usarse en una implementación de tp_call. No comprueba el flag Py_TPFLAGS_HAVE_VECTORCALL y no vuelve a tp_call.

Esta función no es parte de la API limitada.

Nuevo en la versión 3.8.

API para invocar objetos

Various functions are available for calling a Python object. Each converts its arguments to a convention supported by the called object – either tp_call or vectorcall. In order to do as little conversion as possible, pick one that best fits the format of data you have available.

La siguiente tabla resume las funciones disponibles; consulte la documentación individual para obtener más detalles.

Función

invocable

args

kwargs

PyObject_Call()

PyObject *

tupla

dict/NULL

PyObject_CallNoArgs()

PyObject *

—

—

PyObject_CallOneArg()

PyObject *

1 objeto

—

PyObject_CallObject()

PyObject *

tuple/NULL

—

PyObject_CallFunction()

PyObject *

formato

—

PyObject_CallMethod()

obj + char*

formato

—

PyObject_CallFunctionObjArgs()

PyObject *

variadica

—

PyObject_CallMethodObjArgs()

obj + nombre

variadica

—

PyObject_CallMethodNoArgs()

obj + nombre

—

—

PyObject_CallMethodOneArg()

obj + nombre

1 objeto

—

PyObject_Vectorcall()

PyObject *

vectorcall

vectorcall

PyObject_VectorcallDict()

PyObject *

vectorcall

dict/NULL

PyObject_VectorcallMethod()

arg + nombre

vectorcall

vectorcall

PyObject* PyObject_Call(PyObject *callable, PyObject *args, PyObject *kwargs)

Return value: New reference.

Llama a un objeto de Python invocable callable, con argumentos dados por la tupla args, y argumentos con nombre dados por el diccionario kwargs.

args no debe ser NULL; use una tupla vacía si no se necesitan argumentos. Si no se necesitan argumentos con nombre, kwargs puede ser NULL.

Retorna el resultado de la llamada en caso de éxito o genera una excepción y retorna NULL en caso de error.

Este es el equivalente de la expresión de Python: callable(*args, **kwargs).

PyObject* PyObject_CallNoArgs(PyObject *callable)

Llama a un objeto de Python invocable callable sin ningún argumento. Es la forma más eficiente de llamar a un objeto Python invocable sin ningún argumento.

Retorna el resultado de la llamada en caso de éxito o genera una excepción y retorna NULL en caso de error.

Nuevo en la versión 3.9.

PyObject* PyObject_CallOneArg(PyObject *callable, PyObject *arg)

Llama a un objeto de Python invocable callable con exactamente 1 argumento posicional arg y sin argumentos de palabra clave.

Retorna el resultado de la llamada en caso de éxito o genera una excepción y retorna NULL en caso de error.

Esta función no es parte de la API limitada.

Nuevo en la versión 3.9.

PyObject* PyObject_CallObject(PyObject *callable, PyObject *args)

Return value: New reference.

Llama a un objeto de Python invocable callable, con argumentos dados por la tupla args. Si no se necesitan argumentos, entonces args puede ser NULL.

Retorna el resultado de la llamada en caso de éxito o genera una excepción y retorna NULL en caso de error.

Este es el equivalente de la expresión de Python: callable(*args).

PyObject* PyObject_CallFunction(PyObject *callable, const char *format, ...)

Return value: New reference.

Llama a un objeto de Python invocable callable, con un número variable de argumentos C. Los argumentos de C se describen usando una cadena de caracteres de formato de estilo Py_BuildValue(). El formato puede ser NULL, lo que indica que no se proporcionan argumentos.

Retorna el resultado de la llamada en caso de éxito o genera una excepción y retorna NULL en caso de error.

Este es el equivalente de la expresión de Python: callable(*args).

Tenga en cuenta que si solo pasa PyObject * args, PyObject_CallFunctionObjArgs() es una alternativa más rápida.

Distinto en la versión 3.4: El tipo de format se cambió desde char *.

PyObject* PyObject_CallMethod(PyObject *obj, const char *name, const char *format, ...)

Return value: New reference.

Llama al método llamado name del objeto obj con un número variable de argumentos en C. Los argumentos de C se describen mediante una cadena de formato Py_BuildValue() que debería producir una tupla.

El formato puede ser NULL, lo que indica que no se proporcionan argumentos.

Retorna el resultado de la llamada en caso de éxito o genera una excepción y retorna NULL en caso de error.

Este es el equivalente de la expresión de Python: obj.name(arg1, arg2, ...).

Tenga en cuenta que si solo pasa PyObject * args, PyObject_CallMethodObjArgs() es una alternativa más rápida.

Distinto en la versión 3.4: Los tipos de name y format se cambiaron desde char *.

PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ...)

Return value: New reference.

Llame a un objeto de Python invocable callable, con un número variable de argumentos PyObject *. Los argumentos se proporcionan como un número variable de parámetros seguidos de NULL.

Retorna el resultado de la llamada en caso de éxito o genera una excepción y retorna NULL en caso de error.

Este es el equivalente de la expresión de Python: callable(arg1, arg2, ...).

PyObject* PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ...)

Return value: New reference.

Llama a un método del objeto de Python obj, donde el nombre del método se proporciona como un objeto de cadena de caracteres de Python en name. Se llama con un número variable de argumentos PyObject *. Los argumentos se proporcionan como un número variable de parámetros seguidos de NULL.

Retorna el resultado de la llamada en caso de éxito o genera una excepción y retorna NULL en caso de error.

PyObject* PyObject_CallMethodNoArgs(PyObject *obj, PyObject *name)

Llama a un método del objeto de Python obj sin argumentos, donde el nombre del método se da como un objeto de cadena de caracteres de Python en name.

Retorna el resultado de la llamada en caso de éxito o genera una excepción y retorna NULL en caso de error.

Esta función no es parte de la API limitada.

Nuevo en la versión 3.9.

PyObject* PyObject_CallMethodOneArg(PyObject *obj, PyObject *name, PyObject *arg)

Llame a un método del objeto de Python obj con un único argumento posicional arg, donde el nombre del método se proporciona como un objeto de cadena de caracteres de Python en name.

Retorna el resultado de la llamada en caso de éxito o genera una excepción y retorna NULL en caso de error.

Esta función no es parte de la API limitada.

Nuevo en la versión 3.9.

PyObject* PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)

Llama a un objeto de Python invocable callable. Los argumentos son los mismos que para vectorcallfunc. Si callable admite vectorcall, esto llama directamente a la función vectorcall almacenada en callable.

Retorna el resultado de la llamada en caso de éxito o genera una excepción y retorna NULL en caso de error.

Esta función no es parte de la API limitada.

Nuevo en la versión 3.9.

PyObject* PyObject_VectorcallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)

Llamada invocable con argumentos posicionales pasados exactamente como en el protocolo vectorcall, pero con argumentos de palabras clave pasados como un diccionario kwdict. El arreglo args contiene solo los argumentos posicionales.

Independientemente del protocolo que se utilice internamente, es necesario realizar una conversión de argumentos. Por lo tanto, esta función solo debe usarse si la persona que llama ya tiene un diccionario listo para usar para los argumentos de palabras clave, pero no una tupla para los argumentos posicionales.

Esta función no es parte de la API limitada.

Nuevo en la versión 3.9.

PyObject* PyObject_VectorcallMethod(PyObject *name, PyObject *const *args, size_t nargsf, PyObject *kwnames)

Llama a un método usando la convención de llamada vectorcall. El nombre del método se proporciona como una cadena de Python name. El objeto cuyo método se llama es args[0], y el arreglo args que comienza en args [1] representa los argumentos de la llamada. Debe haber al menos un argumento posicional. nargsf es el número de argumentos posicionales que incluyen args [0], más PY_VECTORCALL_ARGUMENTS_OFFSET si el valor de args[0] puede cambiarse temporalmente. Los argumentos de palabras clave se pueden pasar como en PyObject_Vectorcall().

Si el objeto tiene la característica Py_TPFLAGS_METHOD_DESCRIPTOR, esto llamará al objeto de método independiente con el vector args completo como argumentos.

Retorna el resultado de la llamada en caso de éxito o genera una excepción y retorna NULL en caso de error.

Esta función no es parte de la API limitada.

Nuevo en la versión 3.9.

API de soporte de llamadas

int PyCallable_Check(PyObject *o)

Determina si el objeto o es invocable. Retorna 1 si el objeto es invocable y 0 en caso contrario. Esta función siempre finaliza con éxito.

Protocolo de números

int PyNumber_Check(PyObject *o)

Retorna 1 si el objeto o proporciona protocolos numéricos, y falso en caso contrario. Esta función siempre finaliza con éxito.

Distinto en la versión 3.8: Retorna 1 si o es un índice entero.

PyObject* PyNumber_Add(PyObject *o1, PyObject *o2)

Return value: New reference.

Retorna el resultado de agregar o1 y o2, o NULL en caso de falla. Este es el equivalente de la expresión de Python o1 + o2.

PyObject* PyNumber_Subtract(PyObject *o1, PyObject *o2)

Return value: New reference.

Retorna el resultado de restar o2 de o1, o NULL en caso de falla. Este es el equivalente de la expresión de Python o1 - o2.

PyObject* PyNumber_Multiply(PyObject *o1, PyObject *o2)

Return value: New reference.

Retorna el resultado de multiplicar o1 y o2, o NULL en caso de error. Este es el equivalente de la expresión de Python o1 * o2.

PyObject* PyNumber_MatrixMultiply(PyObject *o1, PyObject *o2)

Return value: New reference.

Retorna el resultado de la multiplicación de matrices en o1 y o2, o NULL en caso de falla. Este es el equivalente de la expresión de Python o1 @ o2.

Nuevo en la versión 3.5.

PyObject* PyNumber_FloorDivide(PyObject *o1, PyObject *o2)

Return value: New reference.

Return the floor of o1 divided by o2, or NULL on failure. This is the equivalent of the Python expression o1 // o2.

PyObject* PyNumber_TrueDivide(PyObject *o1, PyObject *o2)

Return value: New reference.

Return a reasonable approximation for the mathematical value of o1 divided by o2, or NULL on failure. The return value is «approximate» because binary floating point numbers are approximate; it is not possible to represent all real numbers in base two. This function can return a floating point value when passed two integers. This is the equivalent of the Python expression o1 / o2.

PyObject* PyNumber_Remainder(PyObject *o1, PyObject *o2)

Return value: New reference.

Retorna el resto de dividir o1 entre o2 o NULL en caso de error. Este es el equivalente de la expresión de Python o1% o2.

PyObject* PyNumber_Divmod(PyObject *o1, PyObject *o2)

Return value: New reference.

Vea la función incorporada divmod(). Retorna NULL en caso de falla. Este es el equivalente de la expresión de Python divmod (o1, o2).

PyObject* PyNumber_Power(PyObject *o1, PyObject *o2, PyObject *o3)

Return value: New reference.

Consulte la función incorporada pow(). Retorna NULL en caso de falla. Este es el equivalente de la expresión de Python pow(o1, o2, o3), donde o3 es opcional. Si se ignora o3, pase Py_None en su lugar (pasar NULL por o3 provocaría un acceso ilegal a la memoria).

PyObject* PyNumber_Negative(PyObject *o)

Return value: New reference.

Retorna la negación de o en caso de éxito o NULL en caso de error. Este es el equivalente de la expresión de Python -o.

PyObject* PyNumber_Positive(PyObject *o)

Return value: New reference.

Retorna o en caso de éxito o NULL en caso de error. Este es el equivalente de la expresión de Python +o.

PyObject* PyNumber_Absolute(PyObject *o)

Return value: New reference.

Retorna el valor absoluto de o o NULL en caso de error. Este es el equivalente de la expresión de Python abs(o).

PyObject* PyNumber_Invert(PyObject *o)

Return value: New reference.

Retorna la negación bit a bit de o en caso de éxito o NULL en caso de error. Este es el equivalente de la expresión de Python ~o.

PyObject* PyNumber_Lshift(PyObject *o1, PyObject *o2)

Return value: New reference.

Retorna el resultado del desplazamiento a la izquierda o1 por o2 en caso de éxito o NULL en caso de error. Este es el equivalente de la expresión de Python o1 << o2.

PyObject* PyNumber_Rshift(PyObject *o1, PyObject *o2)

Return value: New reference.

Retorna el resultado del desplazamiento a la derecha o1 por o2 en caso de éxito o NULL en caso de error. Este es el equivalente de la expresión de Python o1 >> o2.

PyObject* PyNumber_And(PyObject *o1, PyObject *o2)

Return value: New reference.

Retorna el «bit a bit y» (bitwise and) de o1 y o2 en caso de éxito y NULL en caso de error. Este es el equivalente de la expresión de Python o1 & o2.

PyObject* PyNumber_Xor(PyObject *o1, PyObject *o2)

Return value: New reference.

Retorna el «bit a bit o exclusivo» (bitwise exclusive or) de o1 por o2 en caso de éxito, o NULL en caso de error. Este es el equivalente de la expresión de Python o1 ^ o2.

PyObject* PyNumber_Or(PyObject *o1, PyObject *o2)

Return value: New reference.

Retorna el «bit a bit o» (bitwise or) de o1 y o2 en caso de éxito, o NULL en caso de error. Este es el equivalente de la expresión de Python o1 | o2.

PyObject* PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2)

Return value: New reference.

Retorna el resultado de agregar o1 y o2, o NULL en caso de falla. La operación se realiza en su lugar (in-place) cuando o1 lo admite. Este es el equivalente de la declaración de Python o1 += o2.

PyObject* PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2)

Return value: New reference.

Retorna el resultado de restar o2 de o1, o NULL en caso de falla. La operación se realiza en su lugar (in-place) cuando o1 lo admite. Este es el equivalente de la declaración de Python o1 -= o2.

PyObject* PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2)

Return value: New reference.

Retorna el resultado de multiplicar o1 y o2, o NULL en caso de error. La operación se realiza en su lugar (in-place) cuando o1 lo admite. Este es el equivalente de la declaración de Python o1 *= o2.

PyObject* PyNumber_InPlaceMatrixMultiply(PyObject *o1, PyObject *o2)

Return value: New reference.

Retorna el resultado de la multiplicación de matrices en o1 y o2, o NULL en caso de falla. La operación se realiza en su lugar (in-place) cuando o1 lo admite. Este es el equivalente de la declaración de Python o1 @= o2.

Nuevo en la versión 3.5.

PyObject* PyNumber_InPlaceFloorDivide(PyObject *o1, PyObject *o2)

Return value: New reference.

Retorna el piso matemático de dividir o1 por o2, o NULL en caso de falla. La operación se realiza en su lugar (in-place) cuando o1 lo admite. Este es el equivalente de la declaración de Python o1 //= o2.

PyObject* PyNumber_InPlaceTrueDivide(PyObject *o1, PyObject *o2)

Return value: New reference.

Return a reasonable approximation for the mathematical value of o1 divided by o2, or NULL on failure. The return value is «approximate» because binary floating point numbers are approximate; it is not possible to represent all real numbers in base two. This function can return a floating point value when passed two integers. The operation is done in-place when o1 supports it. This is the equivalent of the Python statement o1 /= o2.

PyObject* PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2)

Return value: New reference.

Retorna el resto de dividir o1 entre o2 o NULL en caso de error. La operación se realiza en su lugar (in-place) cuando o1 lo admite. Este es el equivalente de la declaración de Python o1%= o2.

PyObject* PyNumber_InPlacePower(PyObject *o1, PyObject *o2, PyObject *o3)

Return value: New reference.

Consulte la función incorporada pow(). Retorna NULL en caso de falla. La operación se realiza en su lugar (in-place) cuando o1 lo admite. Este es el equivalente de la declaración de Python o1 **= o2 cuando o3 es Py_None, o una variante en su lugar (in-place) de pow (o1, o2, o3) de lo contrario. Si se ignora o3, pase Py_None en su lugar (pasar NULL para o3 provocaría un acceso ilegal a la memoria).

PyObject* PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2)

Return value: New reference.

Retorna el resultado del desplazamiento a la izquierda o1 por o2 en caso de éxito o NULL en caso de error. La operación se realiza en su sitio (in-place) cuando o1 lo admite. Este es el equivalente de la declaración de Python o1 <<= o2.

PyObject* PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2)

Return value: New reference.

Retorna el resultado del desplazamiento a la derecha o1 por o2 en caso de éxito o NULL en caso de error. La operación se realiza en su lugar (in-place) cuando o1 lo admite. Este es el equivalente de la declaración de Python o1 >>= o2.

PyObject* PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2)

Return value: New reference.

Retorna el «bit a bit y» (bitwise and) de o1 y o2 en caso de éxito y NULL en caso de error. La operación se realiza en su lugar (in-place) cuando o1 lo admite. Este es el equivalente de la declaración de Python o1 &= o2.

PyObject* PyNumber_InPlaceXor(PyObject *o1, PyObject *o2)

Return value: New reference.

Retorna el «bit a bit o exclusivo» (bitwise exclusive or) de o1 por o2 en caso de éxito, o NULL en caso de error. La operación se realiza en su lugar (in-place) cuando o1 lo admite. Este es el equivalente de la declaración de Python o1 ^= o2.

PyObject* PyNumber_InPlaceOr(PyObject *o1, PyObject *o2)

Return value: New reference.

Retorna el «bit a bit o» (bitwise or) de o1 y o2 en caso de éxito, o NULL en caso de error. La operación se realiza en su lugar in-place cuando o1 lo admite. Este es el equivalente de la declaración de Python o1 |= o2.

PyObject* PyNumber_Long(PyObject *o)

Return value: New reference.

Retorna el o convertido a un objeto entero en caso de éxito, o NULL en caso de error. Este es el equivalente de la expresión de Python int(o).

PyObject* PyNumber_Float(PyObject *o)

Return value: New reference.

Retorna el o convertido a un objeto flotante en caso de éxito o NULL en caso de error. Este es el equivalente de la expresión de Python float(o).

PyObject* PyNumber_Index(PyObject *o)

Return value: New reference.

Retorna el o convertido aun entero de Python (int) en caso de éxito o NULL con una excepción TypeError generada en caso de error.

PyObject* PyNumber_ToBase(PyObject *n, int base)

Return value: New reference.

Retorna el entero n convertido a base base como una cadena de caracteres. El argumento base debe ser uno de 2, 8, 10 o 16. Para la base 2, 8 o 16, la cadena retornada está prefijada con un marcador base de '0b'”, '0o' o '0x', respectivamente. Si n no es un entero (int) Python, primero se convierte con PyNumber_Index().

Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc)

Returns o converted to a Py_ssize_t value if o can be interpreted as an integer. If the call fails, an exception is raised and -1 is returned.

If o can be converted to a Python int but the attempt to convert to a Py_ssize_t value would raise an OverflowError, then the exc argument is the type of exception that will be raised (usually IndexError or OverflowError). If exc is NULL, then the exception is cleared and the value is clipped to PY_SSIZE_T_MIN for a negative integer or PY_SSIZE_T_MAX for a positive integer.

int PyIndex_Check(PyObject *o)

Returns 1 if o is an index integer (has the nb_index slot of the tp_as_number structure filled in), and 0 otherwise. This function always succeeds.

Protocolo de secuencia

int PySequence_Check(PyObject *o)

Return 1 if the object provides the sequence protocol, and 0 otherwise. Note that it returns 1 for Python classes with a __getitem__() method, unless they are dict subclasses, since in general it is impossible to determine what type of keys the class supports. This function always succeeds.

Py_ssize_t PySequence_Size(PyObject *o)

Py_ssize_t PySequence_Length(PyObject *o)

Retorna el número de objetos en secuencia o en caso de éxito y -1 en caso de error. Esto es equivalente a la expresión de Python len(o).

PyObject* PySequence_Concat(PyObject *o1, PyObject *o2)

Return value: New reference.

Retorna la concatenación de o1 y o2 en caso de éxito, y NULL en caso de error. Este es el equivalente de la expresión de Python o1+o2.

PyObject* PySequence_Repeat(PyObject *o, Py_ssize_t count)

Return value: New reference.

Retorna el resultado de repetir el objeto de secuencia o count veces, o NULL en caso de falla. Este es el equivalente de la expresión de Python o*count.

PyObject* PySequence_InPlaceConcat(PyObject *o1, PyObject *o2)

Return value: New reference.

Retorna la concatenación de o1 y o2 en caso de éxito, y NULL en caso de error. La operación se realiza en su lugar in-place cuando o1 lo admite. Este es el equivalente de la expresión de Python o1+=o2.

PyObject* PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count)

Return value: New reference.

Retorna el resultado de repetir el objeto de secuencia o count veces, o NULL en caso de falla. La operación se realiza en su lugar (in-place) cuando o lo admite. Este es el equivalente de la expresión de Python o*=count.

PyObject* PySequence_GetItem(PyObject *o, Py_ssize_t i)

Return value: New reference.

Retorna el elemento i-ésimo de o o NULL en caso de error. Este es el equivalente de la expresión de Python o[i].

PyObject* PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)

Return value: New reference.

Retorna la rebanada del objeto secuencia o entre i1 y i2, o NULL en caso de error. Este es el equivalente de la expresión de Python o[i1:i2].

int PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v)

Asigna el objeto v al elemento i-ésimo de o. Lanza una excepción y retorna -1 en caso de falla; retorna 0 en caso de éxito. Este es el equivalente de la declaración de Python o[i]=v. Esta función no roba una referencia a v.

If v is NULL, the element is deleted, but this feature is deprecated in favour of using PySequence_DelItem().

int PySequence_DelItem(PyObject *o, Py_ssize_t i)

Elimina el elemento i-ésimo del objeto o. Retorna -1 en caso de falla. Este es el equivalente de la declaración de Python del o[i].

int PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2, PyObject *v)

Asigna el objeto secuencia v al segmento en el objeto secuencia o de i1 a i2. Este es el equivalente de la declaración de Python o[i1:i2]=v.

int PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)

Elimina el segmento en el objeto secuencia o de i1 a i2. Retorna -1 en caso de falla. Este es el equivalente de la declaración de Python del o[i1:i2].

Py_ssize_t PySequence_Count(PyObject *o, PyObject *value)

Retorna el número de apariciones de value en o, es decir, retorna el número de claves para las que o[clave]==value. En caso de fallo, retorna -1. Esto es equivalente a la expresión de Python o.count(value).

int PySequence_Contains(PyObject *o, PyObject *value)

Determine si o contiene valor. Si un elemento en o es igual a value, retorna 1; de lo contrario, retorna 0. En caso de error, retorna -1. Esto es equivalente a la expresión de Python value in o.

Py_ssize_t PySequence_Index(PyObject *o, PyObject *value)

Retorna el primer índice i para el que o[i]==value. En caso de error, retorna -1. Esto es equivalente a la expresión de Python o.index(value).

PyObject* PySequence_List(PyObject *o)

Return value: New reference.

Retorna un objeto lista con el mismo contenido que la secuencia o iterable o, o NULL en caso de error. La lista retornada está garantizada como nueva. Esto es equivalente a la expresión de Python list(o).

PyObject* PySequence_Tuple(PyObject *o)

Return value: New reference.

Retorna un objeto tupla con el mismo contenido que la secuencia o iterable o, o NULL en caso de error. Si o es una tupla, se retornará una nueva referencia; de lo contrario, se construirá una tupla con el contenido apropiado. Esto es equivalente a la expresión de Python tupla(o).

PyObject* PySequence_Fast(PyObject *o, const char *m)

Return value: New reference.

Retorna la secuencia o iterable o como un objeto utilizable por la otra familia de funciones PySequence_Fast*. Si el objeto no es una secuencia o no es iterable, lanza TypeError con m como texto del mensaje. Retorna NULL en caso de falla.

Las funciones PySequence_Fast* se denominan así porque suponen que o es un PyTupleObject o un PyListObject y acceden a los campos de datos de o directamente.

Como detalle de implementación de CPython, si o ya es una secuencia o lista, se retornará.

Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o)

Returns the length of o, assuming that o was returned by PySequence_Fast() and that o is not NULL. The size can also be retrieved by calling PySequence_Size() on o, but PySequence_Fast_GET_SIZE() is faster because it can assume o is a list or tuple.

PyObject* PySequence_Fast_GET_ITEM(PyObject *o, Py_ssize_t i)

Return value: Borrowed reference.

Retorna el elemento i-ésimo de o, suponiendo que o haya sido retornado por PySequence_Fast(), o no es NULL y que i está dentro de los límites.

PyObject** PySequence_Fast_ITEMS(PyObject *o)

Retorna el arreglo subyacente de punteros PyObject. Asume que o fue retornado por PySequence_Fast() y o no es NULL.

Tenga en cuenta que si una lista cambia de tamaño, la reasignación puede reubicar el arreglo de elementos. Por lo tanto, solo use el puntero de arreglo subyacente en contextos donde la secuencia no puede cambiar.

PyObject* PySequence_ITEM(PyObject *o, Py_ssize_t i)

Return value: New reference.

Retorna el elemento i-ésimo de o o NULL en caso de error. Es la forma más rápida de PySequence_GetItem() pero sin verificar que PySequence_Check() en o es verdadero y sin ajuste para índices negativos.

Protocolo de mapeo

Consulte también PyObject_GetItem(), PyObject_SetItem() y PyObject_DelItem().

int PyMapping_Check(PyObject *o)

Return 1 if the object provides the mapping protocol or supports slicing, and 0 otherwise. Note that it returns 1 for Python classes with a __getitem__() method, since in general it is impossible to determine what type of keys the class supports. This function always succeeds.

Py_ssize_t PyMapping_Size(PyObject *o)

Py_ssize_t PyMapping_Length(PyObject *o)

Retorna el número de claves en el objeto o en caso de éxito, y -1 en caso de error. Esto es equivalente a la expresión de Python len(o).

PyObject* PyMapping_GetItemString(PyObject *o, const char *key)

Return value: New reference.

Retorna el elemento de o correspondiente a la cadena de caracteres key o NULL en caso de error. Este es el equivalente de la expresión de Python o[key]. Ver también PyObject_GetItem().

int PyMapping_SetItemString(PyObject *o, const char *key, PyObject *v)

Asigna la cadena de caracteres key al valor v en el objeto o. Retorna -1 en caso de falla. Este es el equivalente de la declaración de Python o[key] = v. Ver también PyObject_SetItem(). Esta función no roba una referencia a v.

int PyMapping_DelItem(PyObject *o, PyObject *key)

Elimina la asignación para el objeto key del objeto o. Retorna -1 en caso de falla. Esto es equivalente a la declaración de Python del o[key]. Este es un alias de PyObject_DelItem().

int PyMapping_DelItemString(PyObject *o, const char *key)

Elimina la asignación de la cadena de caracteres key del objeto o. Retorna -1 en caso de falla. Esto es equivalente a la declaración de Python del o[key].

int PyMapping_HasKey(PyObject *o, PyObject *key)

Retorna 1 si el objeto de mapeo tiene la clave key y 0 de lo contrario. Esto es equivalente a la expresión de Python key in o. Esta función siempre finaliza con éxito.

Tenga en cuenta que las excepciones que se producen al llamar al método __getitem__() se suprimirán. Para obtener informes de errores, utilice PyObject_GetItem() en su lugar.

int PyMapping_HasKeyString(PyObject *o, const char *key)

Retorna 1 si el objeto de mapeo tiene la clave key y 0 de lo contrario. Esto es equivalente a la expresión de Python key in o. Esta función siempre finaliza con éxito.

Tenga en cuenta que las excepciones que se producen al llamar al método __getitem__() y al crear un objeto de cadena de caracteres temporal se suprimirán. Para obtener informes de errores, utilice PyMapping_GetItemString() en su lugar.

PyObject* PyMapping_Keys(PyObject *o)

Return value: New reference.

En caso de éxito, retorna una lista de las claves en el objeto o. En caso de fallo, retorna NULL.

Distinto en la versión 3.7: Anteriormente, la función retornaba una lista o una tupla.

PyObject* PyMapping_Values(PyObject *o)

Return value: New reference.

En caso de éxito, retorna una lista de los valores en el objeto o. En caso de fallo, retorna NULL.

Distinto en la versión 3.7: Anteriormente, la función retornaba una lista o una tupla.

PyObject* PyMapping_Items(PyObject *o)

Return value: New reference.

En caso de éxito, retorna una lista de los elementos en el objeto o, donde cada elemento es una tupla que contiene un par clave-valor (key-value). En caso de fallo, retorna NULL.

Distinto en la versión 3.7: Anteriormente, la función retornaba una lista o una tupla.

Protocolo iterador

Hay dos funciones específicas para trabajar con iteradores.

int PyIter_Check(PyObject *o)

Retorna verdadero si el objeto o admite el protocolo iterador. Esta función siempre finaliza con éxito.

PyObject* PyIter_Next(PyObject *o)

Return value: New reference.

Retorna el siguiente valor de la iteración o. El objeto debe ser un iterador (depende de quién llama comprobar esto). Si no quedan valores restantes, retorna NULL sin establecer ninguna excepción. Si se produce un error al recuperar el elemento, retorna NULL y pasa la excepción.

Para escribir un bucle que itera sobre un iterador, el código en C debería verse así:

PyObject *iterator = PyObject_GetIter(obj);
PyObject *item;

if (iterator == NULL) {
    /* propagate error */
}

while ((item = PyIter_Next(iterator))) {
    /* do something with item */
    ...
    /* release reference when done */
    Py_DECREF(item);
}

Py_DECREF(iterator);

if (PyErr_Occurred()) {
    /* propagate error */
}
else {
    /* continue doing useful work */
}

Protocolo Búfer

Ciertos objetos disponibles en Python ajustan el acceso a un arreglo de memoria subyacente o buffer. Dichos objetos incluyen el incorporado bytes y bytearray, y algunos tipos de extensión como array.array. Las bibliotecas de terceros pueden definir sus propios tipos para fines especiales, como el procesamiento de imágenes o el análisis numérico.

Si bien cada uno de estos tipos tiene su propia semántica, comparten la característica común de estar respaldados por un búfer de memoria posiblemente grande. Es deseable, en algunas situaciones, acceder a ese búfer directamente y sin copia intermedia.

Python proporciona una instalación de este tipo en el nivel C en la forma de protocolo búfer. Este protocolo tiene dos lados:

en el lado del productor, un tipo puede exportar una «interfaz de búfer» que permite a los objetos de ese tipo exponer información sobre su búfer subyacente. Esta interfaz se describe en la sección Estructuras de Objetos Búfer;

en el lado del consumidor, hay varios medios disponibles para obtener un puntero a los datos subyacentes sin procesar de un objeto (por ejemplo, un parámetro de método).

Los objetos simples como bytes y bytearray exponen su búfer subyacente en forma orientada a bytes. Otras formas son posibles; por ejemplo, los elementos expuestos por un array.array pueden ser valores de varios bytes.

Un consumidor de ejemplo de la interfaz del búfer es el método write() de objetos de archivo: cualquier objeto que pueda exportar una serie de bytes a través de la interfaz del búfer puede escribirse en un archivo. Mientras que write() solo necesita acceso de solo lectura a los contenidos internos del objeto que se le pasa, otros métodos como readinto() necesitan acceso de escritura a los contenidos de su argumento. La interfaz del búfer permite que los objetos permitan o rechacen selectivamente la exportación de búferes de lectura-escritura y solo lectura.

Hay dos formas para que un consumidor de la interfaz del búfer adquiera un búfer sobre un objeto de destino:

llamar PyObject_GetBuffer() con los parámetros correctos;

llamar PyArg_ParseTuple() (o uno de sus hermanos) con uno de los y*, w* o s* códigos de formato.

En ambos casos, se debe llamar a PyBuffer_Release() cuando ya no se necesita el búfer. De lo contrario, podrían surgir varios problemas, como pérdidas de recursos.

Estructura de búfer

Las estructuras de búfer (o simplemente «búferes») son útiles como una forma de exponer los datos binarios de otro objeto al programador de Python. También se pueden usar como un mecanismo de corte de copia cero. Usando su capacidad para hacer referencia a un bloque de memoria, es posible exponer cualquier información al programador Python con bastante facilidad. La memoria podría ser una matriz grande y constante en una extensión C, podría ser un bloque de memoria sin procesar para su manipulación antes de pasar a una biblioteca del sistema operativo, o podría usarse para pasar datos estructurados en su formato nativo en memoria .

Contrariamente a la mayoría de los tipos de datos expuestos por el intérprete de Python, los búferes no son punteros PyObject sino estructuras C simples. Esto les permite ser creados y copiados de manera muy simple. Cuando se necesita un contenedor genérico alrededor de un búfer, un objeto memoryview puede ser creado.

Para obtener instrucciones breves sobre cómo escribir un objeto de exportación, consulte Estructuras de objetos búfer. Para obtener un búfer, consulte PyObject_GetBuffer().

Py_buffer

void *buf

Un puntero al inicio de la estructura lógica descrita por los campos del búfer. Puede ser cualquier ubicación dentro del bloque de memoria física subyacente del exportador. Por ejemplo, con negativo strides el valor puede apuntar al final del bloque de memoria.

Para arreglos contiguous, el valor apunta al comienzo del bloque de memoria.

void *obj

Una nueva referencia al objeto exportador. La referencia es propiedad del consumidor y automáticamente disminuye y se establece en NULL por PyBuffer_Release(). El campo es el equivalente del valor de retorno de cualquier función estándar de C-API.

Como un caso especial, para los búferes temporary que están envueltos por PyMemoryView_FromBuffer() o PyBuffer_FillInfo() este campo es NULL. En general, los objetos de exportación NO DEBEN usar este esquema.

Py_ssize_t len

product(shape) * itemize. Para arreglos contiguos, esta es la longitud del bloque de memoria subyacente. Para arreglos no contiguos, es la longitud que tendría la estructura lógica si se copiara en una representación contigua.

Accede a ((char *)buf)[0] hasta ((char *)buf)[len-1] solo es válido si el búfer se ha obtenido mediante una solicitud que garantiza la contigüidad. En la mayoría de los casos, dicha solicitud será PyBUF_SIMPLE o PyBUF_WRITABLE.

int readonly

Un indicador de si el búfer es de solo lectura. Este campo está controlado por el indicador PyBUF_WRITABLE.

Py_ssize_t itemsize

Tamaño del elemento en bytes de un solo elemento. Igual que el valor de struct.calcsize() invocado en valores no NULL format.

Excepción importante: si un consumidor solicita un búfer sin el indicador PyBUF_FORMAT, format se establecerá en NULL, pero itemsize todavía tiene el valor para el formato original.

Si shape está presente, la igualdad product(shape) * itemsize == len aún se mantiene y el consumidor puede usar itemsize para navegar el búfer.

Si shape es NULL como resultado de un PyBUF_SIMPLE o un PyBUF_WRITABLE, el consumidor debe ignorar itemsize y asume itemsize == 1.

const char *format

Una cadena de caracteres terminada en NUL en sintaxis de estilo del modulo struct que describe el contenido de un solo elemento. Si esto es NULL, se supone "B" (bytes sin signo).

Este campo está controlado por el indicador PyBUF_FORMAT.

int ndim

El número de dimensiones que representa la memoria como un arreglo n-dimensional. Si es `` 0``, buf apunta a un solo elemento que representa un escalar. En este caso, shape, strides y suboffsets DEBE ser NULL.

La macro PyBUF_MAX_NDIM limita el número máximo de dimensiones a 64. Los exportadores DEBEN respetar este límite, los consumidores de búfer multidimensionales DEBEN poder manejar hasta dimensiones PyBUF_MAX_NDIM.

Py_ssize_t *shape

Un arreglo de Py_ssize_t de longitud ndim que indica la forma de la memoria como un arreglo n-dimensional. Tenga en cuenta que shape[0] * ... * shape[ndim-1] * itemsize DEBE ser igual a len.

Los valores de forma están restringidos a shape[n] >= 0. El caso shape[n] == 0 requiere atención especial. Vea arreglos complejos (complex arrays) para más información.

El arreglo de formas es de sólo lectura para el consumidor.

Py_ssize_t *strides

Un arreglo de Py_ssize_t de longitud ndim que proporciona el número de bytes que se omiten para llegar a un nuevo elemento en cada dimensión.

Los valores de stride pueden ser cualquier número entero. Para los arreglos regulares, los pasos son generalmente positivos, pero un consumidor DEBE ser capaz de manejar el caso strides[n] <= 0. Ver complex arrays para más información.

El arreglo strides es de sólo lectura para el consumidor.

Py_ssize_t *suboffsets

Un arreglo de Py_ssize_t de longitud ndim. Si suboffsets[n] >= 0, los valores almacenados a lo largo de la enésima dimensión son punteros y el valor del suboffsets dicta cuántos bytes agregar a cada puntero después de desreferenciarlos. Un valor de suboffsets negativo indica que no debe producirse una desreferenciación (striding en un bloque de memoria contiguo).

Si todos los suboffsets son negativos (es decir, no se necesita desreferenciar), entonces este campo debe ser NULL (el valor predeterminado).

Python Imaging Library (PIL) utiliza este tipo de representación de arreglos. Consulte complex arrays para obtener más información sobre cómo acceder a los elementos de dicho arreglo.

El arreglo de suboffsets es de sólo lectura para el consumidor.

void *internal

Esto es para uso interno del objeto exportador. Por ejemplo, el exportador podría volver a emitirlo como un número entero y utilizarlo para almacenar indicadores sobre si las matrices de forma, strides y suboffsets deben liberarse cuando se libera el búfer. El consumidor NO DEBE alterar este valor.

Tipos de solicitud búfer

Los búferes obtienen generalmente enviando una solicitud de búfer a un objeto de exportación a través de PyObject_GetBuffer(). Dado que la complejidad de la estructura lógica de la memoria puede variar drásticamente, el consumidor usa el argumento flags para especificar el tipo de búfer exacto que puede manejar.

Todos los campos Py_buffer están definidos inequívocamente por el tipo de solicitud.

campos independientes de solicitud

Los siguientes campos no están influenciados por flags y siempre deben completarse con los valores correctos: obj, buf, len, itemsize, ndim.

formato de sólo lectura

PyBUF_WRITABLE

Controla el campo readonly. Si se establece, el exportador DEBE proporcionar un búfer de escritura o, de lo contrario, informar de un error. De lo contrario, el exportador PUEDE proporcionar un búfer de solo lectura o de escritura, pero la elección DEBE ser coherente para todos los consumidores.

PyBUF_FORMAT

Controla el campo format. Si se establece, este campo DEBE completarse correctamente. De lo contrario, este campo DEBE ser NULL.

PyBUF_WRITABLE puede ser |”d a cualquiera de las banderas en la siguiente sección. Dado que PyBUF_SIMPLE se define como 0, PyBUF_WRITABLE puede usarse como un indicador independiente para solicitar un búfer de escritura simple.

PyBUF_FORMAT puede ser |”d para cualquiera de las banderas excepto PyBUF_SIMPLE. Este último ya implica el formato B (bytes sin signo).

formas, strides, suboffsets

Las banderas que controlan la estructura lógica de la memoria se enumeran en orden decreciente de complejidad. Tenga en cuenta que cada bandera contiene todos los bits de las banderas debajo de ella.

Solicitud

forma

strides

suboffsets

PyBUF_INDIRECT

sí

sí

si es necesario

PyBUF_STRIDES

sí

sí

NULL

PyBUF_ND

sí

NULL

NULL

PyBUF_SIMPLE

NULL

NULL

NULL

solicitudes de contigüidad

La contigüidad C o Fortran se puede solicitar explícitamente, con y sin información de paso. Sin información de paso, el búfer debe ser C-contiguo.

Solicitud

forma

strides

suboffsets

contig

PyBUF_C_CONTIGUOUS

sí

sí

NULL

C

PyBUF_F_CONTIGUOUS

sí

sí

NULL

F

PyBUF_ANY_CONTIGUOUS

sí

sí

NULL

C o F

PyBUF_ND

sí

NULL

NULL

C

solicitudes compuestas

Todas las solicitudes posibles están completamente definidas por alguna combinación de las banderas en la sección anterior. Por conveniencia, el protocolo de memoria intermedia proporciona combinaciones de uso frecuente como indicadores únicos.

En la siguiente tabla U significa contigüidad indefinida. El consumidor tendría que llamar a PyBuffer_IsContiguous() para determinar la contigüidad.

Solicitud

forma

strides

suboffsets

contig

sólo lectura

formato

PyBUF_FULL

sí

sí

si es necesario

U

0

sí

PyBUF_FULL_RO

sí

sí

si es necesario

U

1 o 0

sí

PyBUF_RECORDS

sí

sí

NULL

U

0

sí

PyBUF_RECORDS_RO

sí

sí

NULL

U

1 o 0

sí

PyBUF_STRIDED

sí

sí

NULL

U

0

NULL

PyBUF_STRIDED_RO

sí

sí

NULL

U

1 o 0

NULL

PyBUF_CONTIG

sí

NULL

NULL

C

0

NULL

PyBUF_CONTIG_RO

sí

NULL

NULL

C

1 o 0

NULL

Arreglos complejos

Estilo NumPy: forma y strides

La estructura lógica de las matrices de estilo NumPy está definida por itemsize, ndim, shape y strides.

Si ndim == 0, la ubicación de memoria señalada por buf se interpreta como un escalar de tamaño itemsize. En ese caso, tanto shape como strides son NULL.

Si strides es NULL, el arreglo se interpreta como un arreglo C n-dimensional estándar. De lo contrario, el consumidor debe acceder a un arreglo n-dimensional de la siguiente manera:

ptr = (char *)buf + indices[0] * strides[0] + ... + indices[n-1] * strides[n-1];
item = *((typeof(item) *)ptr);

Como se señaló anteriormente, buf puede apuntar a cualquier ubicación dentro del bloque de memoria real. Un exportador puede verificar la validez de un búfer con esta función:

def verify_structure(memlen, itemsize, ndim, shape, strides, offset):
    """Verify that the parameters represent a valid array within
       the bounds of the allocated memory:
           char *mem: start of the physical memory block
           memlen: length of the physical memory block
           offset: (char *)buf - mem
    """
    if offset % itemsize:
        return False
    if offset < 0 or offset+itemsize > memlen:
        return False
    if any(v % itemsize for v in strides):
        return False

    if ndim <= 0:
        return ndim == 0 and not shape and not strides
    if 0 in shape:
        return True

    imin = sum(strides[j]*(shape[j]-1) for j in range(ndim)
               if strides[j] <= 0)
    imax = sum(strides[j]*(shape[j]-1) for j in range(ndim)
               if strides[j] > 0)

    return 0 <= offset+imin and offset+imax+itemsize <= memlen

Estilo PIL: forma, strides y suboffsets

Además de los elementos normales, los arreglos de estilo PIL pueden contener punteros que deben seguirse para llegar al siguiente elemento en una dimensión. Por ejemplo, el arreglo C tridimensional regular char v[2][2][3] también se puede ver como un arreglo de 2 punteros a 2 arreglos bidimensionales: char (*v[2])[2][3]. En la representación de suboffsets, esos dos punteros pueden incrustarse al comienzo de buf, apuntando a dos matrices char x[2][3] que pueden ubicarse en cualquier lugar de la memoria.

Aquí hay una función que retorna un puntero al elemento en un arreglo N-D a la que apunta un índice N-dimensional cuando hay strides y suboffsets no NULL:

void *get_item_pointer(int ndim, void *buf, Py_ssize_t *strides,
                       Py_ssize_t *suboffsets, Py_ssize_t *indices) {
    char *pointer = (char*)buf;
    int i;
    for (i = 0; i < ndim; i++) {
        pointer += strides[i] * indices[i];
        if (suboffsets[i] >=0 ) {
            pointer = *((char**)pointer) + suboffsets[i];
        }
    }
    return (void*)pointer;
}

Funciones relacionadas a búfer

int PyObject_CheckBuffer(PyObject *obj)

Retorna 1 si obj admite la interfaz de búfer; de lo contrario, 0 cuando se retorna 1, no garantiza que PyObject_GetBuffer() tenga éxito. Esta función siempre finaliza con éxito.

int PyObject_GetBuffer(PyObject *exporter, Py_buffer *view, int flags)

Envía una solicitud al exporter para completar la view según lo especificado por flags. Si el exportador no puede proporcionar un búfer del tipo exacto, DEBE lanzar PyExc_BufferError, establecer view->obj en NULL y retornar -1.

Si tiene éxito, completa view, establece view->obj en una nueva referencia a exporter y retorna 0. En el caso de proveedores de búfer encadenados que redirigen las solicitudes a un solo objeto, view->obj PUEDE referirse a este objeto en lugar de exporter (Ver Estructuras de objetos de búfer).

Las llamadas exitosas a PyObject_GetBuffer() deben combinarse con las llamadas a PyBuffer_Release(), similar a malloc() y free(). Por lo tanto, después de que el consumidor haya terminado con el búfer, PyBuffer_Release() debe llamarse exactamente una vez.

void PyBuffer_Release(Py_buffer *view)

Libera el búfer view y disminuye el conteo de referencias para view->obj. Esta función DEBE llamarse cuando el búfer ya no se utiliza, de lo contrario, pueden producirse fugas de referencia.

Es un error llamar a esta función en un búfer que no se obtuvo a través de PyObject_GetBuffer().

Py_ssize_t PyBuffer_SizeFromFormat(const char *format)

Retorna el itemsize implícito de format. En caso de error, lanza una excepción y retorna -1.

Nuevo en la versión 3.9.

int PyBuffer_IsContiguous(Py_buffer *view, char order)

Retorna 1 si la memoria definida por view es de estilo C (order es 'C') o de estilo Fortran (order es 'F') contiguous o uno cualquiera (order es 'A'). Retorna 0 de lo contrario. Esta función siempre finaliza con éxito.

void* PyBuffer_GetPointer(Py_buffer *view, Py_ssize_t *indices)

Obtiene el área de memoria señalada por los indices dentro del view dado. indices deben apuntar a un arreglo de índices view->ndim.

int PyBuffer_FromContiguous(Py_buffer *view, void *buf, Py_ssize_t len, char fort)

Copia len bytes contiguos de buf a view. fort puede ser 'C' o 'F' (para pedidos al estilo C o al estilo Fortran). 0 se retorna en caso de éxito, -1 en caso de error.

int PyBuffer_ToContiguous(void *buf, Py_buffer *src, Py_ssize_t len, char order)

Copia len bytes de src a su representación contigua en buf. order puede ser 'C' o 'F' o ''A' (para pedidos al estilo C o al estilo Fortran o cualquiera) 0 se retorna en caso de éxito, -1 en caso de error.

Esta función falla si len != src->len.

void PyBuffer_FillContiguousStrides(int ndims, Py_ssize_t *shape, Py_ssize_t *strides, int itemsize, char order)

Rellena el arreglo strides con bytes de paso de un contiguous (estilo C si order es 'C' o estilo Fortran si order es 'F ' ) arreglo de la forma dada con el número dado de bytes por elemento.

int PyBuffer_FillInfo(Py_buffer *view, PyObject *exporter, void *buf, Py_ssize_t len, int readonly, int flags)

Maneje las solicitudes de búfer para un exportador que quiera exponer buf de tamaño len con capacidad de escritura establecida de acuerdo con readonly. buf se interpreta como una secuencia de bytes sin signo.

El argumento flags indica el tipo de solicitud. Esta función siempre llena view según lo especificado por flags, a menos que buf haya sido designado como solo lectura y PyBUF_WRITABLE esté configurado en flags.

Si tiene éxito, establece view->obj en una nueva referencia a exporter y retorna 0. De lo contrario, aumenta PyExc_BufferError, establece view->obj en NULL y retorna -1;

Si esta función se usa como parte de a getbufferproc, exporter DEBE establecerse en el objeto exportador y flags deben pasarse sin modificaciones. De lo contrario, exporter DEBE ser NULL.

Protocolo de búfer antiguo

Obsoleto desde la versión 3.0.

Estas funciones formaban parte de la API del «antiguo protocolo de búfer» en Python 2. En Python 3, este protocolo ya no existe, pero las funciones aún están expuestas para facilitar la transferencia del código 2.x. Actúan como una envoltura de compatibilidad alrededor del nuevo protocolo de búfer, pero no le dan control sobre la vida útil de los recursos adquiridos cuando se exporta un búfer.

Por lo tanto, se recomienda que llame PyObject_GetBuffer() (o y*``o ``w* format codes con la familia de funciones PyArg_ParseTuple()) para obtener una vista de búfer sobre un objeto, y PyBuffer_Release() cuando se puede liberar la vista de búfer.

int PyObject_AsCharBuffer(PyObject *obj, const char **buffer, Py_ssize_t *buffer_len)

Retorna un puntero a una ubicación de memoria de solo lectura que se puede usar como entrada basada en caracteres. El argumento obj debe admitir la interfaz de búfer de caracteres de segmento único. En caso de éxito, retorna 0, establece buffer en la ubicación de memoria y buffer_len en la longitud del búfer. Retorna -1 y lanza TypeError en caso de error.

int PyObject_AsReadBuffer(PyObject *obj, const void **buffer, Py_ssize_t *buffer_len)

Retorna un puntero a una ubicación de memoria de solo lectura que contiene datos arbitrarios. El argumento obj debe admitir la interfaz de búfer legible de segmento único. En caso de éxito, retorna 0, establece buffer en la ubicación de memoria y buffer_len en la longitud del búfer. Retorna -1 y lanza un TypeError en caso de error.

int PyObject_CheckReadBuffer(PyObject *o)

Retorna 1 si o admite la interfaz de búfer legible de segmento único. De lo contrario, retorna 0. Esta función siempre finaliza con éxito.

Tenga en cuenta que esta función intenta obtener y liberar un búfer, y las excepciones que se producen al llamar a las funciones correspondientes se suprimirán. Para obtener informes de errores, utilice PyObject_GetBuffer() en su lugar.

int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len)

Retorna un puntero a una ubicación de memoria de escritura. El argumento obj debe admitir la interfaz de búfer de caracteres de segmento único. En caso de éxito, retorna 0, establece buffer en la ubicación de memoria y buffer_len en la longitud del búfer. Retorna -1 y lanza un TypeError en caso de error.

Capa de objetos concretos

Las funciones de este capítulo son específicas de ciertos tipos de objetos de Python. Pasarles un objeto del tipo incorrecto no es una buena idea; si recibe un objeto de un programa Python y no está seguro de que tenga el tipo correcto, primero debe realizar una verificación de tipo; por ejemplo, para verificar que un objeto es un diccionario, utilice PyDict_Check(). El capítulo está estructurado como el «árbol genealógico» de los tipos de objetos Python.

Advertencia

Si bien las funciones descritas en este capítulo verifican cuidadosamente el tipo de objetos que se pasan, muchos de ellos no verifican si se pasa NULL en lugar de un objeto válido. Permitir que se pase NULL puede causar violaciones de acceso a la memoria y la terminación inmediata del intérprete.

Objetos fundamentales

Esta sección describe los objetos de tipo Python y el objeto singleton None.

Objetos Tipos

Crear tipos asignados en montículo (heap)

El objeto None

Objetos numéricos

Objetos Enteros

Objetos Booleanos

Objetos de punto flotante

Objetos de números complejos

Números complejos como estructuras C

Números complejos como objetos de Python

Objetos de secuencia

Las operaciones genéricas en los objetos de secuencia se discutieron en el capítulo anterior; Esta sección trata sobre los tipos específicos de objetos de secuencia que son intrínsecos al lenguaje Python.

Objetos Bytes

Objetos de arreglos de bytes (bytearrays)

Macros de verificación de tipos

Funciones API directas

Macros

Objetos y códecs Unicode

Objetos Unicode

Tipo Unicode

Propiedades de caracteres Unicode

Creando y accediendo a cadenas de caracteres Unicode

APIs de Py_UNICODE deprecadas

Codificación regional

Codificación del sistema de archivos

soporte wchar_t

Códecs incorporados

Códecs genéricos

Códecs UTF-8

Códecs UTF-32

Códecs UTF-16

Códecs UTF-7

Códecs Unicode escapado

Códecs para Unicode escapado en bruto

Códecs Latin-1

Códecs ASCII

Códecs de mapa de caracteres

Códecs MBCS para Windows

Métodos & Ranuras (Slots)

Métodos y funciones de ranura (Slot)

Objetos Tuplas

Objetos de secuencia de estructura

Objetos lista

Objetos contenedor

Objetos Diccionarios

Objetos Conjunto

Objetos de función

Objetos función

Objetos de método de instancia

Objetos método

Objetos Celda

Objetos Código

Otros objetos

Objetos archivo

Objectos Modulo

Inicializando módulos en C

Inicialización monofásica

Inicialización multifase

Funciones de creación de módulos de bajo nivel

Funciones de soporte

Búsqueda de módulos

Objetos iteradores

Objetos descriptores

Objeto rebanada (slice)

Objeto Elipsis

Objetos de vista de memoria (MemoryView)

Objetos de referencia débil

Cápsulas

Objetos Generadores

Objetos corrutina

Objetos de variables de contexto

Objetos DateTime

Objects for Type Hinting

Objetos Tipos

PyTypeObject

La estructura C de los objetos utilizados para describir los tipos incorporados.

PyTypeObject PyType_Type

Este es el objeto tipo para objetos tipo; es el mismo objeto que type en la capa Python.

int PyType_Check(PyObject *o)

Retorna un valor distinto de cero si el objeto o es un objeto tipo, incluidas las instancias de tipos derivados del objeto de tipo estándar. Retorna 0 en todos los demás casos. Esta función siempre finaliza con éxito.

int PyType_CheckExact(PyObject *o)

Retorna un valor distinto de cero si el objeto o es un objeto tipo, pero no un subtipo del objeto tipo estándar. Retorna 0 en todos los demás casos. Esta función siempre finaliza con éxito.

unsigned int PyType_ClearCache()

Borra la caché de búsqueda interna. Retorna la etiqueta (tag) de la versión actual.

unsigned long PyType_GetFlags(PyTypeObject* type)

Retorna el miembro tp_flags de type. Esta función está destinada principalmente para su uso con Py_LIMITED_API; se garantiza que los bits de bandera (flag) individuales serán estables en las versiones de Python, pero el acceso a tp_flags en sí mismo no forma parte de la API limitada.

Nuevo en la versión 3.2.

Distinto en la versión 3.4: El tipo de retorno es ahora unsigned long en vez de long.

void PyType_Modified(PyTypeObject *type)

Invalida la memoria caché de búsqueda interna para el tipo y todos sus subtipos. Esta función debe llamarse después de cualquier modificación manual de los atributos o clases base del tipo.

int PyType_HasFeature(PyTypeObject *o, int feature)

Retorna un valor distinto de cero si el tipo objeto o establece la característica feature. Las características de tipo se indican mediante flags de un solo bit.

int PyType_IS_GC(PyTypeObject *o)

Retorna verdadero si el objeto tipo incluye soporte para el detector de ciclo; Esto prueba el indicador de tipo Py_TPFLAGS_HAVE_GC.

int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b)

Retorna verdadero si a es un subtipo de b.

Esta función solo busca subtipos reales, lo que significa que __subclasscheck__() no se llama en b. Llama PyObject_IsSubclass() para hacer el mismo chequeo que issubclass() haría.

PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)

Return value: New reference.

Controlador genérico para la ranura tp_alloc de un objeto tipo. Usa el mecanismo de asignación de memoria predeterminado de Python para asignar una nueva instancia e inicializar todo su contenido a NULL.

PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)

Return value: New reference.

Controlador genérico para la ranura tp_new de un objeto tipo. Crea una nueva instancia utilizando la ranura del tipo tp_alloc.

int PyType_Ready(PyTypeObject *type)

Finalizar un objeto tipo. Se debe llamar a todos los objetos tipo para finalizar su inicialización. Esta función es responsable de agregar ranuras heredadas de la clase base de un tipo. Retorna 0 en caso de éxito o retorna -1 y establece una excepción en caso de error.

Nota

If some of the base classes implements the GC protocol and the provided type does not include the Py_TPFLAGS_HAVE_GC in its flags, then the GC protocol will be automatically implemented from its parents. On the contrary, if the type being created does include Py_TPFLAGS_HAVE_GC in its flags then it must implement the GC protocol itself by at least implementing the tp_traverse handle.

void* PyType_GetSlot(PyTypeObject *type, int slot)

Retorna el puntero de función almacenado en la ranura dada. Si el resultado es NULL, esto indica que la ranura es NULL o que la función se llamó con parámetros no válidos. Las personas que llaman suelen convertir el puntero de resultado en el tipo de función apropiado.

Consulte PyType_Slot.slot para conocer los posibles valores del argumento slot.

Se lanza una excepción si type no es un tipo montículo (heap).

Nuevo en la versión 3.4.

PyObject* PyType_GetModule(PyTypeObject *type)

Retorna el objeto módulo asociado con el tipo dado cuando se creó el tipo usando PyType_FromModuleAndSpec().

Si no hay ningún módulo asociado con el tipo dado, establece TypeError y retorna NULL.

Esta función se suele utilizar para obtener el módulo en el que se define un método. Tenga en cuenta que en un método de este tipo, es posible que PyType_GetModule(Py_TYPE(self)) no retorne el resultado deseado. Py_TYPE(self) puede ser una subclass de la clase deseada, y las subclases no están necesariamente definidas en el mismo módulo que su superclase. Consulte PyCMethod para obtener la clase que define el método.

Nuevo en la versión 3.9.

void* PyType_GetModuleState(PyTypeObject *type)

Retorna el estado del objeto de módulo asociado con el tipo dado. Este es un atajo para llamar PyModule_GetState() en el resultado de PyType_GetModule().

Si no hay ningún módulo asociado con el tipo dado, establece TypeError y retorna NULL.

Si el tipo type tiene un módulo asociado pero su estado es NULL, retorna NULL sin establecer una excepción.

Nuevo en la versión 3.9.

Crear tipos asignados en montículo (heap)

Las siguientes funciones y estructuras se utilizan para crear heap types.

PyObject* PyType_FromModuleAndSpec(PyObject *module, PyType_Spec *spec, PyObject *bases)

Return value: New reference.

Crea y retorna un objeto montículo (heap) a partir de spec (Py_TPFLAGS_HEAPTYPE).

Si bases es una tupla, el tipo montículo (heap) creado contiene todos los tipos contenidos en él como tipos básicos.

Si bases es NULL, en su lugar se usa la ranura Py_tp_base. Si eso también es NULL, en su lugar, se utiliza la ranura Py_tp_base. Si eso también es NULL, el nuevo tipo se deriva de object.

The module argument can be used to record the module in which the new class is defined. It must be a module object or NULL. If not NULL, the module is associated with the new type and can later be retrieved with PyType_GetModule(). The associated module is not inherited by subclasses; it must be specified for each class individually.

Esta función llama PyType_Ready() en el tipo nuevo.

Nuevo en la versión 3.9.

PyObject* PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases)

Return value: New reference.

Equivalente a PyType_FromModuleAndSpec(NULL, spec, bases).

Nuevo en la versión 3.3.

PyObject* PyType_FromSpec(PyType_Spec *spec)

Return value: New reference.

Equivalente a PyType_FromSpecWithBases(spec, NULL).

PyType_Spec

Estructura que define el comportamiento de un tipo.

const char* PyType_Spec.name

Nombre del tipo, utilizado para establecer PyTypeObject.tp_name.

int PyType_Spec.basicsize

int PyType_Spec.itemsize

Tamaño de la instancia en bytes, utilizado para establecer PyTypeObject.tp_basicsize y PyTypeObject.tp_itemsize.

int PyType_Spec.flags

Banderas (flags) del tipo, que se usan para establecer PyTypeObject.tp_flags.

Si el indicador Py_TPFLAGS_HEAPTYPE no está establecido, PyType_FromSpecWithBases() lo establece automáticamente.

PyType_Slot *PyType_Spec.slots

Arreglo de estructuras PyType_Slot. Terminado por el valor de ranura especial {0, NULL}.

PyType_Slot

Estructura que define la funcionalidad opcional de un tipo, que contiene una ranura ID y un puntero de valor.

int PyType_Slot.slot

Una ranura ID.

Las ranuras IDs se nombran como los nombres de campo de las estructuras PyTypeObject, PyNumberMethods, PySequenceMethods, PyMappingMethods y PyAsyncMethods con un prefijo Py_ agregado. Por ejemplo, use:

Py_tp_dealloc para establecer PyTypeObject.tp_dealloc

Py_nb_add para establecer PyNumberMethods.nb_add

Py_sq_length para establecer PySequenceMethods.sq_length

Los siguientes campos no se pueden configurar en absoluto usando PyType_Spec y PyType_Slot:

tp_dict

tp_mro

tp_cache

tp_subclasses

tp_weaklist

tp_vectorcall

tp_weaklistoffset (vea PyMemberDef)

tp_dictoffset (vea PyMemberDef)

tp_vectorcall_offset (vea PyMemberDef)

Los siguientes campos no se pueden establecer usando PyType_Spec y PyType_Slot cuando se utiliza la API limitada:

bf_getbuffer

bf_releasebuffer

Estableciendo Py_tp_bases o Py_tp_base puede ser problemático en algunas plataformas. Para evitar problemas, use el argumento bases de PyType_FromSpecWithBases() en su lugar.

Distinto en la versión 3.9: Slots in PyBufferProcs may be set in the unlimited API.

void *PyType_Slot.pfunc

El valor deseado de la ranura. En la mayoría de los casos, este es un puntero a una función.

Puede no ser NULL.

El objeto None

Tenga en cuenta que PyTypeObject para None no está expuesto directamente en la API de Python/C. Como None es un singleton, es suficiente probar la identidad del objeto (usando == en C). No existe la función PyNone_Check() por la misma razón.

PyObject* Py_None

El objeto None de Python, denota falta de valor. Este objeto no tiene métodos. Debe tratarse como cualquier otro objeto con respecto a los recuentos de referencia.

Py_RETURN_NONE

Maneje adecuadamente el retorno Py_None desde una función en C (es decir, incremente el recuento de referencia de None y devuélvalo).

Objetos Enteros

Todos los enteros se implementan como objetos enteros «largos» (long) de tamaño arbitrario.

En caso de error, la mayoría de las API PyLong_As* retornan (tipo de retorno) -1 que no se puede distinguir de un número. Use PyErr_Occurred() para desambiguar.

PyLongObject

Este subtipo de PyObject representa un objeto entero de Python.

PyTypeObject PyLong_Type

Esta instancia de PyTypeObject representa el tipo entero de Python. Este es el mismo objeto que int en la capa de Python.

int PyLong_Check(PyObject *p)

Retorna verdadero si su argumento es un PyLongObject o un subtipo de PyLongObject. Esta función siempre finaliza con éxito.

int PyLong_CheckExact(PyObject *p)

Retorna verdadero si su argumento es un PyLongObject, pero no un subtipo de PyLongObject. Esta función siempre finaliza con éxito.

PyObject* PyLong_FromLong(long v)

Return value: New reference.

Retorna un objeto PyLongObject nuevo desde v, o NULL en caso de error.

The current implementation keeps an array of integer objects for all integers between -5 and 256. When you create an int in that range you actually just get back a reference to the existing object.

PyObject* PyLong_FromUnsignedLong(unsigned long v)

Return value: New reference.

Retorna un objeto PyLongObject nuevo desde un C unsigned long, o NULL en caso de error.

PyObject* PyLong_FromSsize_t(Py_ssize_t v)

Return value: New reference.

Retorna un objeto PyLongObject nuevo desde un C Py_ssize_t, o NULL en caso de error.

PyObject* PyLong_FromSize_t(size_t v)

Return value: New reference.

Retorna un objeto PyLongObject nuevo desde un C size_t, o NULL en caso de error.

PyObject* PyLong_FromLongLong(long long v)

Return value: New reference.

Retorna un objeto PyLongObject nuevo desde un C long long, o NULL en caso de error.

PyObject* PyLong_FromUnsignedLongLong(unsigned long long v)

Return value: New reference.

Retorna un objeto PyLongObject nuevo desde un C unsigned long long, o NULL en caso de error.

PyObject* PyLong_FromDouble(double v)

Return value: New reference.

Retorna un nuevo objeto PyLongObject de la parte entera de v, o NULL en caso de error.

PyObject* PyLong_FromString(const char *str, char **pend, int base)

Return value: New reference.

Retorna un nuevo PyLongObject basado en el valor de cadena de caracteres en str, que se interpreta de acuerdo con la raíz en base. Si pend no es NULL, * pend apuntará al primer carácter en str que sigue a la representación del número. Si base es 0, str se interpreta utilizando la definición Literales enteros; en este caso, los ceros a la izquierda en un número decimal distinto de cero lanzan un ValueError. Si base no es 0, debe estar entre 2 y 36, inclusive. Se ignoran los espacios iniciales y los guiones bajos individuales después de un especificador base y entre dígitos. Si no hay dígitos, se lanzará ValueError.

PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base)

Return value: New reference.

Convierte una secuencia de dígitos Unicode en un valor entero de Python.

Deprecated since version 3.3, will be removed in version 3.10: Parte de la API de viejo estilo Py_UNICODE; por favor migrar para usar PyLong_FromUnicodeObject().

PyObject* PyLong_FromUnicodeObject(PyObject *u, int base)

Return value: New reference.

Convierte una secuencia de dígitos Unicode en la cadena de caracteres u en un valor entero de Python.

Nuevo en la versión 3.3.

PyObject* PyLong_FromVoidPtr(void *p)

Return value: New reference.

Crea un entero de Python desde el puntero p. El valor del puntero se puede recuperar del valor resultante usando PyLong_AsVoidPtr().

long PyLong_AsLong(PyObject *obj)

Retorna una representación de C long de obj. Si obj no es una instancia de PyLongObject, primero llama a su método __index__() o __int__() (si está presente) para convertirlo en un PyLongObject.

Lanza OverflowError si el valor de obj está fuera de rango para un long.

Retorna -1 en caso de error. Use PyErr_Occurred() para desambiguar.

Distinto en la versión 3.8: Use __index__() si está disponible.

Obsoleto desde la versión 3.8: Usar __int__() está deprecado.

long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)

Retorna una representación de C long de obj. Si obj no es una instancia de PyLongObject, primero llama a su método __index__() o __int__() (si está presente) para convertirlo en un PyLongObject.

Si el valor de obj es mayor que LONG_MAX o menor que LONG_MIN, establece *overflow * en ``1`` o ``-1``, respectivamente, y retorna ``-1``; de lo contrario, establece **overflow en 0. Si se produce alguna otra excepción, configura *overflow en 0 y retorna -1 como de costumbre.

Retorna -1 en caso de error. Use PyErr_Occurred() para desambiguar.

Distinto en la versión 3.8: Use __index__() si está disponible.

Obsoleto desde la versión 3.8: Usar __int__() está deprecado.

long long PyLong_AsLongLong(PyObject *obj)

Retorna una representación de C long long de obj. Si obj no es una instancia de PyLongObject, primero llama a su método __index__() o __int__() (si está presente) para convertirlo en un PyLongObject.

Lanza OverflowError si el valor de obj está fuera de rango para un long long.

Retorna -1 en caso de error. Use PyErr_Occurred() para desambiguar.

Distinto en la versión 3.8: Use __index__() si está disponible.

Obsoleto desde la versión 3.8: Usar __int__() está deprecado.

long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)

Retorna una representación de C long long de obj. Si obj no es una instancia de PyLongObject, primero llama a su método __index__() o __int__() (si está presente) para convertirlo en un PyLongObject.

Si el valor de obj es mayor que LLONG_MAX o menor que LLONG_MIN, establece *overflow en 1 o -1, respectivamente, y retorna -1; de lo contrario, establece *overflow en 0. Si se produce alguna otra excepción, configura *overflow en 0 y retorna -1 como de costumbre.

Retorna -1 en caso de error. Use PyErr_Occurred() para desambiguar.

Nuevo en la versión 3.2.

Distinto en la versión 3.8: Use __index__() si está disponible.

Obsoleto desde la versión 3.8: Usar __int__() está deprecado.

Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)

Retorna una representación de C Py_ssize_t de pylong. pylong debe ser una instancia de PyLongObject.

Lanza OverflowError si el valor de pylong está fuera de rango para un Py_ssize_t.

Retorna -1 en caso de error. Use PyErr_Occurred() para desambiguar.

unsigned long PyLong_AsUnsignedLong(PyObject *pylong)

Retorna una representación de C unsigned long de pylong. pylong debe ser una instancia de PyLongObject.

Lanza OverflowError si el valor de pylong está fuera de rango para un unsigned long.

Retorna (unsigned long)-1 en caso de error. Use PyErr_Occurred() para desambiguar.

size_t PyLong_AsSize_t(PyObject *pylong)

Retorna una representación de C size_t de pylong. pylong debe ser una instancia de PyLongObject.

Lanza OverflowError si el valor de pylong está fuera de rango para un size_t.

Retorna (size_t) -1 en caso de error. Use PyErr_Occurred() para desambiguar.

unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)

Retorna una representación de C unsigned long long de pylong. pylong debe ser una instancia de PyLongObject.

Lanza OverflowError si el valor de pylong está fuera de rango para un unsigned long long.

Retorna (unsigned long long) -1 en caso de error. Use PyErr_Occurred() para desambiguar.

Distinto en la versión 3.1: Ahora un pylong negativo lanza un OverflowError, no TypeError.

unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)

Retorna una representación de C unsigned long de obj. Si obj no es una instancia de PyLongObject, primero llama a su método __index__() o __int__() (si está presente) para convertirlo en un PyLongObject.

Si el valor de obj está fuera del rango para unsigned long, retorna la reducción de ese valor módulo ULONG_MAX + 1.

Retorna (unsigned long)-1 en caso de error. Use PyErr_Occurred() para desambiguar.

Distinto en la versión 3.8: Use __index__() si está disponible.

Obsoleto desde la versión 3.8: Usar __int__() está deprecado.

unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)

Retorna una representación de C unsigned long long de obj. Si obj no es una instancia de PyLongObject, primero llama a su método __index__() o __int__() (si está presente) para convertirlo en un PyLongObject.

Si el valor de obj está fuera del rango para unsigned long long, retorna la reducción de ese valor módulo ULLONG_MAX + 1.

Retorna (unsigned long long) -1 por error. Use PyErr_Occurred() para desambiguar.

Distinto en la versión 3.8: Use __index__() si está disponible.

Obsoleto desde la versión 3.8: Usar __int__() está deprecado.

double PyLong_AsDouble(PyObject *pylong)

Retorna una representación de C double de pylong. pylong debe ser una instancia de PyLongObject.

Lanza OverflowError si el valor de pylong está fuera de rango para un double.

Retorna -1.0 en caso de error. Use PyErr_Occurred() para desambiguar.

void* PyLong_AsVoidPtr(PyObject *pylong)

Convierte un entero Python pylong en un puntero C void. Si pylong no se puede convertir, se generará un OverflowError. Esto solo se garantiza para producir un puntero utilizable void para valores creados con PyLong_FromVoidPtr().

Retorna NULL en caso de error. Use PyErr_Occurred() para desambiguar.

Objetos Booleanos

Los booleanos en Python se implementan como una subclase de enteros. Solo hay dos booleanos Py_False y Py_True. Como tal, las funciones normales de creación y eliminación no se aplican a los booleanos. Sin embargo, los siguientes macros están disponibles.

int PyBool_Check(PyObject *o)

Retorna verdadero si o es de tipo PyBool_Type. Esta función siempre finaliza con éxito.

PyObject* Py_False

El objeto False de Python. Este objeto no tiene métodos. Debe tratarse como cualquier otro objeto con respecto a los recuentos de referencia.

PyObject* Py_True

El objeto True de Python. Este objeto no tiene métodos. Debe tratarse como cualquier otro objeto con respecto a los recuentos de referencia.

Py_RETURN_FALSE

Retorna Py_False de una función, incrementando adecuadamente su recuento de referencia.

Py_RETURN_TRUE

Retorna Py_True desde una función, incrementando adecuadamente su recuento de referencia.

PyObject* PyBool_FromLong(long v)

Return value: New reference.

Retorna una nueva referencia a Py_True o Py_False dependiendo del valor de verdad de v.

Objetos de punto flotante

PyFloatObject

Este subtipo de PyObject representa un objeto de punto flotante de Python.

PyTypeObject PyFloat_Type

Esta instancia de PyTypeObject representa el tipo de punto flotante de Python. Este es el mismo objeto que float en la capa de Python.

int PyFloat_Check(PyObject *p)

Retorna verdadero si su argumento es un PyFloatObject o un subtipo de PyFloatObject. Esta función siempre finaliza con éxito.

int PyFloat_CheckExact(PyObject *p)

Retorna verdadero si su argumento es un PyFloatObject, pero no un subtipo de PyFloatObject. Esta función siempre finaliza con éxito.

PyObject* PyFloat_FromString(PyObject *str)

Return value: New reference.

Crea un objeto PyFloatObject en función del valor de cadena de caracteres en str o NULL en caso de error.

PyObject* PyFloat_FromDouble(double v)

Return value: New reference.

Crea un objeto PyFloatObject a partir de v, o NULL en caso de error.

double PyFloat_AsDouble(PyObject *pyfloat)

Retorna una representación C double de los contenidos de pyfloat. Si pyfloat no es un objeto de punto flotante de Python pero tiene un método __float__(), primero se llamará a este método para convertir pyfloat en un flotante. Si __float __() no está definido, entonces recurre a __index__(). Este método retorna -1.0 en caso de falla, por lo que se debe llamar a PyErr_Occurred() para verificar si hay errores.

Distinto en la versión 3.8: Utilice __index__() si está disponible.

double PyFloat_AS_DOUBLE(PyObject *pyfloat)

Retorna una representación C double de los contenidos de pyfloat, pero sin verificación de errores.

PyObject* PyFloat_GetInfo(void)

Return value: New reference.

Retorna una instancia de structseq que contiene información sobre la precisión, los valores mínimos y máximos de un flotante. Es una envoltura delgada alrededor del archivo de encabezado float.h.

double PyFloat_GetMax()

Retorna el máximo flotante finito representable DBL_MAX como C double.

double PyFloat_GetMin()

Retorna el flotante positivo normalizado mínimo DBL_MIN como C double.

Objetos de números complejos

Los objetos de números complejos de Python se implementan como dos tipos distintos cuando se ven desde la API de C: uno es el objeto de Python expuesto a los programas de Python, y el otro es una estructura en C que representa el valor de número complejo real. La API proporciona funciones para trabajar con ambos.

Números complejos como estructuras C

Tenga en cuenta que las funciones que aceptan estas estructuras como parámetros y las retornan como resultados lo hacen por valor en lugar de desreferenciarlas a través de punteros. Esto es consistente en toda la API.

Py_complex

La estructura C que corresponde a la porción de valor de un objeto de número complejo de Python. La mayoría de las funciones para tratar con objetos de números complejos utilizan estructuras de este tipo como valores de entrada o salida, según corresponda. Se define como:

typedef struct {
   double real;
   double imag;
} Py_complex;

Py_complex _Py_c_sum(Py_complex left, Py_complex right)

Retorna la suma de dos números complejos, utilizando la representación C Py_complex.

Py_complex _Py_c_diff(Py_complex left, Py_complex right)

Retorna la diferencia entre dos números complejos, usando la representación C Py_complex.

Py_complex _Py_c_neg(Py_complex num)

Return the negation of the complex number num, using the C Py_complex representation.

Py_complex _Py_c_prod(Py_complex left, Py_complex right)

Retorna el producto de dos números complejos, usando la representación C Py_complex.

Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)

Retorna el cociente de dos números complejos, utilizando la representación C Py_complex.

Si divisor es nulo, este método retorna cero y establece errno en EDOM.

Py_complex _Py_c_pow(Py_complex num, Py_complex exp)

Retorna la exponenciación de num por exp, utilizando la representación C Py_complex.

Si num es nulo y exp no es un número real positivo, este método retorna cero y establece errno a EDOM.

Números complejos como objetos de Python

PyComplexObject

Este subtipo de PyObject representa un objeto de número complejo de Python.

PyTypeObject PyComplex_Type

Esta instancia de PyTypeObject representa el tipo de número complejo de Python. Es el mismo objeto que complex en la capa de Python.

int PyComplex_Check(PyObject *p)

Retorna verdadero si su argumento es un PyComplexObject o un subtipo de PyComplexObject. Esta función siempre finaliza con éxito.

int PyComplex_CheckExact(PyObject *p)

Retorna verdadero si su argumento es un PyComplexObject, pero no un subtipo de PyComplexObject. Esta función siempre finaliza con éxito.

PyObject* PyComplex_FromCComplex(Py_complex v)

Return value: New reference.

Crea un nuevo objeto de número complejo de Python a partir de un valor C Py_complex.

PyObject* PyComplex_FromDoubles(double real, double imag)

Return value: New reference.

Retorna un nuevo objeto PyComplexObject de real e imag.

double PyComplex_RealAsDouble(PyObject *op)

Retorna la parte real de op como double en C.

double PyComplex_ImagAsDouble(PyObject *op)

Retorna la parte imaginaria de op como un double de C.

Py_complex PyComplex_AsCComplex(PyObject *op)

Retorna el valor Py_complex del número complejo op.

Si op no es un objeto de número complejo de Python pero tiene un método __complex__(), primero se llamará a este método para convertir op en un objeto de número complejo de Python. Si __complex__() no está definido, vuelve a __float__(). Si __float__() no está definido, entonces recurre a __index__(). En caso de falla, este método retorna -1.0 como un valor real.

Distinto en la versión 3.8: Use __index__() si está disponible.

Objetos Bytes

These functions raise TypeError when expecting a bytes parameter and called with a non-bytes parameter.

PyBytesObject

Este subtipo de PyObject representa un objeto bytes de Python.

PyTypeObject PyBytes_Type

Esta instancia de PyTypeObject representa el tipo bytes de Python; es el mismo objeto que bytes en la capa de Python.

int PyBytes_Check(PyObject *o)

Retorna verdadero si el objeto o es un objeto bytes o una instancia de un subtipo del tipo bytes. Esta función siempre finaliza con éxito.

int PyBytes_CheckExact(PyObject *o)

Retorna verdadero si el objeto o es un objeto bytes, pero no una instancia de un subtipo del tipo bytes. Esta función siempre finaliza con éxito.

PyObject* PyBytes_FromString(const char *v)

Return value: New reference.

Retorna un nuevo objeto bytes con una copia de la cadena de caracteres v como valor en caso de éxito y NULL en caso de error. El parámetro v no debe ser NULL; no se comprobará.

PyObject* PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)

Return value: New reference.

Retorna un nuevo objeto bytes con una copia de la cadena de caracteres v como valor y longitud len en caso de éxito y NULL en caso de error. Si v es NULL, el contenido del objeto bytes no se inicializa.

PyObject* PyBytes_FromFormat(const char *format, ...)

Return value: New reference.

Toma una cadena de caracteres format del estilo C printf() y un número variable de argumentos, calcula el tamaño del objeto bytes Python resultante y retorna un objeto bytes con los valores formateados. Los argumentos variables deben ser tipos C y deben corresponder exactamente a los caracteres de formato en la cadena de caracteres format. Se permiten los siguientes caracteres de formato:

Caracteres de formato

Tipo

Comentario

%%

n/a

El carácter literal %.

%c

int

Un solo byte, representado como un C int.

%d

int

Equivalente a printf("%d"). 1

%u

unsigned int

Equivalente a printf("%u"). 1

%ld

long

Equivalente a printf("%ld"). 1

%lu

unsigned long

Equivalente a printf("%lu"). 1

%zd

Py_ssize_t

Equivalente a printf("%zd"). 1

%zu

size_t

Equivalente a printf("%zu"). 1

%i

int

Equivalente a printf("%i"). 1

%x

int

Equivalente a printf("%x"). 1

%s

const char*

Un arreglo de caracteres C terminados en nulo.

%p

const void*

La representación hexadecimal de un puntero en C. Principalmente equivalente a printf("%p") excepto que se garantiza que comience con el literal 0x, independientemente de lo que produzca el printf de la plataforma.

Un carácter de formato no reconocido hace que todo el resto de la cadena de caracteres de formato se copie como está en el objeto de resultado y se descartan los argumentos adicionales.

1(1,2,3,4,5,6,7,8)

Para especificadores de enteros (d, u, ld, lu, zd, zu, i, x): el indicador de conversión 0 tiene efecto incluso cuando se proporciona una precisión.

PyObject* PyBytes_FromFormatV(const char *format, va_list vargs)

Return value: New reference.

Idéntica a PyBytes_FromFormat() excepto que toma exactamente dos argumentos.

PyObject* PyBytes_FromObject(PyObject *o)

Return value: New reference.

Retorna la representación en bytes del objeto o que implementa el protocolo de búfer.

Py_ssize_t PyBytes_Size(PyObject *o)

Retorna la longitud de los bytes en el objeto bytes o.

Py_ssize_t PyBytes_GET_SIZE(PyObject *o)

Forma macro de PyBytes_Size() pero sin verificación de errores.

char* PyBytes_AsString(PyObject *o)

Retorna un puntero al contenido de o. El puntero se refiere al búfer interno de o, que consiste en bytes len(o) + 1. El último byte en el búfer siempre es nulo, independientemente de si hay otros bytes nulos. Los datos no deben modificarse de ninguna manera, a menos que el objeto se haya creado usando PyBytes_FromStringAndSize(NULL, size). No debe ser desasignado. Si o no es un objeto de bytes en absoluto, PyBytes_AsString() retorna NULL y lanza un TypeError.

char* PyBytes_AS_STRING(PyObject *string)

Forma macro de PyBytes_AsString() pero sin verificación de errores.

int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)

Retorna los contenidos terminados en nulo del objeto obj a través de las variables de salida buffer y length.

Si length es NULL, el objeto bytes no puede contener bytes nulos incrustados; si lo hace, la función retorna -1 y se genera un ValueError.

El búfer se refiere a un búfer interno de obj, que incluye un byte nulo adicional al final (sin contar en length). Los datos no deben modificarse de ninguna manera, a menos que el objeto se haya creado usando PyBytes_FromStringAndSize(NULL, size). No debe ser desasignado. Si obj no es un objeto bytes en absoluto, PyBytes_AsStringAndSize() retorna -1 y lanza TypeError.

Distinto en la versión 3.5: Anteriormente, TypeError se lanzaba cuando se encontraban bytes nulos incrustados en el objeto bytes.

void PyBytes_Concat(PyObject **bytes, PyObject *newpart)

Crea un nuevo objeto de bytes en *bytes que contiene el contenido de newpart agregado a bytes; la persona que llama poseerá la nueva referencia. La referencia al valor anterior de bytes será robada. Si no se puede crear el nuevo objeto, la referencia anterior a bytes se seguirá descartando y el valor de *bytes se establecerá en NULL; Se establecerá la excepción apropiada.

void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)

Crea un nuevo objeto de bytes en *bytes que contenga el contenido de newpart agregado a bytes. Esta versión disminuye el recuento de referencias de newpart.

int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)

Una forma de cambiar el tamaño de un objeto bytes aunque sea «inmutable». Solo use esto para construir un nuevo objeto bytes; no use esto si los bytes ya pueden ser conocidos en otras partes del código. Es un error llamar a esta función si el recuento en el objeto bytes de entrada no es uno. Pasa la dirección de un objeto de bytes existente como un lvalue (puede escribirse en él) y el nuevo tamaño deseado. En caso de éxito, *bytes retiene el objeto de bytes redimensionados y se retorna 0; la dirección en *bytes puede diferir de su valor de entrada. Si la reasignación falla, el objeto de bytes original en *bytes se desasigna, *bytes se establece en NULL, MemoryError se establece y se retorna -1 .

Objetos de arreglos de bytes (bytearrays)

PyByteArrayObject

Este subtipo de PyObject representa un objeto arreglo de bytes de Python.

PyTypeObject PyByteArray_Type

Esta instancia de PyTypeObject representa el tipo arreglo de bytes de Python; es el mismo objeto que bytearray en la capa de Python.

Macros de verificación de tipos

int PyByteArray_Check(PyObject *o)

Retorna verdadero si el objeto o es un objeto de arreglo de bytes o una instancia de un subtipo del tipo arreglo de bytes. Esta función siempre finaliza con éxito.

int PyByteArray_CheckExact(PyObject *o)

Retorna verdadero si el objeto o es un objeto de arreglo de bytes, pero no una instancia de un subtipo del tipo arreglo de bytes. Esta función siempre finaliza con éxito.

Funciones API directas

PyObject* PyByteArray_FromObject(PyObject *o)

Return value: New reference.

Retorna un nuevo objeto de arreglo de bytes de cualquier objeto, o, que implementa el buffer protocol.

PyObject* PyByteArray_FromStringAndSize(const char *string, Py_ssize_t len)

Return value: New reference.

Crea un nuevo objeto de arreglo de bytes a partir de string y su longitud, len. En caso de fallo, se retorna NULL.

PyObject* PyByteArray_Concat(PyObject *a, PyObject *b)

Return value: New reference.

Une los arreglos de bytes (bytearrays) a y b y retorna un nuevo arreglo de bytes (bytearray) con el resultado.

Py_ssize_t PyByteArray_Size(PyObject *bytearray)

Retorna el tamaño de bytearray después de buscar un puntero NULL.

char* PyByteArray_AsString(PyObject *bytearray)

Retorna el contenido de bytearray como un arreglo de caracteres después de verificar un puntero NULL. La arreglo retornado siempre tiene un byte nulo adicional agregado.

int PyByteArray_Resize(PyObject *bytearray, Py_ssize_t len)

Cambia el tamaño del búfer interno de bytearray a len.

Macros

Estos macros intercambian seguridad por velocidad y no comprueban punteros.

char* PyByteArray_AS_STRING(PyObject *bytearray)

Versión macro de PyByteArray_AsString().

Py_ssize_t PyByteArray_GET_SIZE(PyObject *bytearray)

Versión macro de PyByteArray_Size().

Objetos y códecs Unicode

Objetos Unicode

Desde la implementación del PEP 393 [https://www.python.org/dev/peps/pep-0393] en Python 3.3, los objetos Unicode utilizan internamente una variedad de representaciones, para permitir el manejo del rango completo de caracteres Unicode mientras se mantiene la eficiencia de memoria. Hay casos especiales para cadenas de caracteres donde todos los puntos de código están por debajo de 128, 256 o 65536; de lo contrario, los puntos de código deben estar por debajo de 1114112 (que es el rango completo de Unicode).

Py_UNICODE * y las representaciones UTF-8 se crean a pedido y se almacenan en caché en el objeto Unicode. La representación Py_UNICODE * está en desuso y es ineficiente; debe evitarse en situaciones sensibles al rendimiento o la memoria.

Debido a la transición entre las API antiguas y las API nuevas, los objetos Unicode pueden estar internamente en dos estados dependiendo de cómo se crearon:

Los objetos Unicode «canónicos» son todos los objetos creados por una API Unicode no obsoleta. Utilizan la representación más eficiente permitida por la implementación.

Los objetos Unicode «heredados» se han creado a través de una de las API obsoletas (normalmente PyUnicode_FromUnicode()) y solo tienen la representación Py_UNICODE*; Será necesario llamar a PyUnicode_READY() en ellos antes de llamar a cualquier otra API.

Nota

El objeto Unicode «heredado» se eliminará en Python 3.12 con APIs obsoletas. Todos los objetos Unicode serán «canónicos» desde entonces. Consulte PEP 623 [https://www.python.org/dev/peps/pep-0623] para obtener más información.

Tipo Unicode

Estos son los tipos básicos de objetos Unicode utilizados para la implementación de Unicode en Python:

Py_UCS4

Py_UCS2

Py_UCS1

Estos tipos son definiciones de tipo (typedefs) para los tipos “enteros sin signo” (unsigned int) lo suficientemente anchos como para contener caracteres de 32 bits, 16 bits y 8 bits, respectivamente. Cuando se trate con caracteres Unicode individuales, use Py_UCS4.

Nuevo en la versión 3.3.

Py_UNICODE

Este es una definición de tipo (typedef) de wchar_t, que es un tipo de 16 bits o de 32 bits dependiendo de la plataforma.

Distinto en la versión 3.3: En versiones anteriores, este era un tipo de 16 bits o de 32 bits, dependiendo de si seleccionó una versión Unicode «estrecha» o «amplia» de Python en el momento de la compilación.

PyASCIIObject

PyCompactUnicodeObject

PyUnicodeObject

Estos subtipos de PyObject representan un objeto Python Unicode. En casi todos los casos, no deben usarse directamente, ya que todas las funciones API que se ocupan de objetos Unicode toman y retornan punteros PyObject.

Nuevo en la versión 3.3.

PyTypeObject PyUnicode_Type

Esta instancia de PyTypeObject representa el tipo Python Unicode. Está expuesto al código de Python como str.

Las siguientes API son realmente macros de C y se pueden utilizar para realizar comprobaciones rápidas y acceder a datos internos de solo lectura de objetos Unicode:

int PyUnicode_Check(PyObject *o)

Retorna verdadero si el objeto o es un objeto Unicode o una instancia de un subtipo Unicode.

int PyUnicode_CheckExact(PyObject *o)

Retorna verdadero (True) si el objeto o es un objeto Unicode, pero no una instancia de un subtipo.

int PyUnicode_READY(PyObject *o)

Asegura que el objeto de cadena de caracteres o esté en la representación «canónica». Esto es necesario antes de usar cualquiera de las macros de acceso que se describen a continuación.

Retorna 0 en caso de éxito y -1 con una excepción establecida en caso de error, que ocurre en particular si falla la asignación de memoria.

Nuevo en la versión 3.3.

Deprecated since version 3.10, will be removed in version 3.12: Esta API será removida con PyUnicode_FromUnicode().

Py_ssize_t PyUnicode_GET_LENGTH(PyObject *o)

Retorna la longitud de la cadena de caracteres Unicode, en puntos de código. o tiene que ser un objeto Unicode en la representación «canónica» (no marcada).

Nuevo en la versión 3.3.

Py_UCS1* PyUnicode_1BYTE_DATA(PyObject *o)

Py_UCS2* PyUnicode_2BYTE_DATA(PyObject *o)

Py_UCS4* PyUnicode_4BYTE_DATA(PyObject *o)

Retorna un puntero a la representación canónica emitida a los tipos enteros UCS1, UCS2 o UCS4 para el acceso directo a los caracteres. No se realizan verificaciones si la representación canónica tiene el tamaño de carácter correcto; use PyUnicode_KIND() para seleccionar el macro correcto. Asegúrese de que se haya llamado a PyUnicode_READY() antes de acceder a esto.

Nuevo en la versión 3.3.

PyUnicode_WCHAR_KIND

PyUnicode_1BYTE_KIND

PyUnicode_2BYTE_KIND

PyUnicode_4BYTE_KIND

Retorna los valores de la macro PyUnicode_KIND().

Nuevo en la versión 3.3.

Deprecated since version 3.10, will be removed in version 3.12: PyUnicode_WCHAR_KIND está deprecada.

unsigned int PyUnicode_KIND(PyObject *o)

Retorna una de las constantes de tipo PyUnicode (ver arriba) que indican cuántos bytes por carácter utiliza este objeto Unicode para almacenar sus datos. o tiene que ser un objeto Unicode en la representación «canónica» (no marcada).

Nuevo en la versión 3.3.

void* PyUnicode_DATA(PyObject *o)

Retorna un puntero vacío al búfer Unicode sin formato. o tiene que ser un objeto Unicode en la representación «canónica» (no marcada).

Nuevo en la versión 3.3.

void PyUnicode_WRITE(int kind, void *data, Py_ssize_t index, Py_UCS4 value)

Escribe en una representación canónica data (como se obtiene con PyUnicode_DATA()). Esta macro no realiza ninguna comprobación de cordura y está diseñado para su uso en bucles. La persona que llama debe almacenar en caché el valor kind y el puntero data como se obtiene de otras llamadas de la macro. index es el índice en la cadena de caracteres (comienza en 0) y value es el nuevo valor del punto de código que debe escribirse en esa ubicación.

Nuevo en la versión 3.3.

Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index)

Lee un punto de código de una representación canónica data (obtenido con PyUnicode_DATA()). No se realizan verificaciones ni llamadas preparadas.

Nuevo en la versión 3.3.

Py_UCS4 PyUnicode_READ_CHAR(PyObject *o, Py_ssize_t index)

Lee un carácter de un objeto Unicode o, que debe estar en la representación «canónica». Esto es menos eficiente que PyUnicode_READ() si realiza varias lecturas consecutivas.

Nuevo en la versión 3.3.

PyUnicode_MAX_CHAR_VALUE(o)

Retorna el punto de código máximo adecuado para crear otra cadena de caracteres basada en o, que debe estar en la representación «canónica». Esto siempre es una aproximación pero más eficiente que iterar sobre la cadena.

Nuevo en la versión 3.3.

Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)

Retorna el tamaño de la representación en desuso Py_UNICODE, en unidades de código (esto incluye pares sustitutos como 2 unidades). o tiene que ser un objeto Unicode (no marcado).

Deprecated since version 3.3, will be removed in version 3.12: Parte de la API Unicode de estilo antiguo, por favor migrar para usar PyUnicode_GET_LENGTH().

Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)

Retorna el tamaño de la representación en desuso Py_UNICODE en bytes. o tiene que ser un objeto Unicode (no marcado).

Deprecated since version 3.3, will be removed in version 3.12: Parte de la API Unicode de estilo antiguo, por favor migrar para usar PyUnicode_GET_LENGTH().

Py_UNICODE* PyUnicode_AS_UNICODE(PyObject *o)

const char* PyUnicode_AS_DATA(PyObject *o)

Retorna un puntero a una representación Py_UNICODE del objeto. El búfer retornado siempre termina con un punto de código nulo adicional. También puede contener puntos de código nulo incrustados, lo que provocaría que la cadena de caracteres se truncara cuando se usara en la mayoría de las funciones de C. La forma AS_DATA arroja el puntero a const char *. El argumento o tiene que ser un objeto Unicode (no marcado).

Distinto en la versión 3.3: Esta macro ahora es ineficiente, porque en muchos casos la representación Py_UNICODE no existe y necesita ser creada, y puede fallar (retornar NULL con un conjunto de excepciones). Intente portar el código para usar las nuevas macros PyUnicode_nBYTE_DATA() o use PyUnicode_WRITE() o PyUnicode_READ().

Deprecated since version 3.3, will be removed in version 3.12: Parte de la antigua API Unicode, por favor migre para usar la familia de macros PyUnicode_nBYTE_DATA().

int PyUnicode_IsIdentifier(PyObject *o)

Retorna 1 si la cadena de caracteres es un identificador válido de acuerdo con la definición del lenguaje, sección Identificadores y palabras clave. Retorna 0 de lo contrario.

Distinto en la versión 3.9: La función ya no llama a Py_FatalError() si la cadena de caracteres no está lista.

Propiedades de caracteres Unicode

Unicode proporciona muchas propiedades de caracteres diferentes. Los que se necesitan con mayor frecuencia están disponibles a través de estas macros que se asignan a las funciones de C según la configuración de Python.

int Py_UNICODE_ISSPACE(Py_UCS4 ch)

Retorna 1 o 0 dependiendo de si ch es un carácter de espacio en blanco.

int Py_UNICODE_ISLOWER(Py_UCS4 ch)

Retorna 1 o 0 dependiendo de si ch es un carácter en minúscula.

int Py_UNICODE_ISUPPER(Py_UCS4 ch)

Retorna 1 o 0 dependiendo de si ch es un carácter en mayúscula.

int Py_UNICODE_ISTITLE(Py_UCS4 ch)

Retorna 1 o 0 dependiendo de si ch es un carácter en caso de título (titlecase).

int Py_UNICODE_ISLINEBREAK(Py_UCS4 ch)

Retorna 1 o 0 dependiendo de si ch es un carácter de salto de línea.

int Py_UNICODE_ISDECIMAL(Py_UCS4 ch)

Retorna 1 o 0 dependiendo de si ch es un carácter decimal o no.

int Py_UNICODE_ISDIGIT(Py_UCS4 ch)

Retorna 1 o 0 dependiendo de si ch es un carácter de dígitos.

int Py_UNICODE_ISNUMERIC(Py_UCS4 ch)

Retorna 1 o 0 dependiendo de si ch es un carácter numérico.

int Py_UNICODE_ISALPHA(Py_UCS4 ch)

Retorna 1 o 0 dependiendo de si ch es un carácter alfabético.

int Py_UNICODE_ISALNUM(Py_UCS4 ch)

Retorna 1 o 0 dependiendo de si ch es un carácter alfanumérico.

int Py_UNICODE_ISPRINTABLE(Py_UCS4 ch)

Retorna 1 o 0 dependiendo de si ch es un carácter imprimible. Los caracteres no imprimibles son aquellos definidos en la base de datos de caracteres Unicode como «Otro» o «Separador», excepto el espacio ASCII (0x20) que se considera imprimible. (Tenga en cuenta que los caracteres imprimibles en este contexto son aquellos a los que no se debe escapar cuando repr() se invoca en una cadena de caracteres. No tiene relación con el manejo de cadenas de caracteres escritas en sys.stdout o sys.stderr.)

Estas API se pueden usar para conversiones caracteres rápidas y directos:

Py_UCS4 Py_UNICODE_TOLOWER(Py_UCS4 ch)

Retorna el carácter ch convertido a minúsculas.

Obsoleto desde la versión 3.3: Esta función utiliza conversiones simples.

Py_UCS4 Py_UNICODE_TOUPPER(Py_UCS4 ch)

Retorna el carácter ch convertido a mayúsculas.

Obsoleto desde la versión 3.3: Esta función utiliza conversiones simples.

Py_UCS4 Py_UNICODE_TOTITLE(Py_UCS4 ch)

Retorna el carácter ch convertido a formato de título (titlecase).

Obsoleto desde la versión 3.3: Esta función utiliza conversiones simples.

int Py_UNICODE_TODECIMAL(Py_UCS4 ch)

Retorna el carácter ch convertido a un entero positivo decimal. Retorna -1 si esto no es posible. Esta macro no genera excepciones.

int Py_UNICODE_TODIGIT(Py_UCS4 ch)

Retorna el carácter ch convertido a un entero de un solo dígito. Retorna -1 si esto no es posible. Esta macro no genera excepciones.

double Py_UNICODE_TONUMERIC(Py_UCS4 ch)

Retorna el carácter ch convertido a doble. retorne -1.0 si esto no es posible. Esta macro no genera excepciones.

Estas API se pueden usar para trabajar con sustitutos:

Py_UNICODE_IS_SURROGATE(ch)

Comprueba si ch es un sustituto (0xD800 <= ch <= 0xDFFF).

Py_UNICODE_IS_HIGH_SURROGATE(ch)

Comprueba si ch es un sustituto alto (0xD800 <= ch <= 0xDFFF).

Py_UNICODE_IS_LOW_SURROGATE(ch)

Comprueba si ch es un sustituto bajo (0xD800 <= ch <= 0xDFFF).

Py_UNICODE_JOIN_SURROGATES(high, low)

Une dos caracteres sustitutos y retorna un solo valor Py_UCS4. high y low son respectivamente los sustitutos iniciales y finales en un par sustituto.

Creando y accediendo a cadenas de caracteres Unicode

Para crear objetos Unicode y acceder a sus propiedades de secuencia básicas, use estas API:

PyObject* PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)

Return value: New reference.

Crea un nuevo objeto Unicode. maxchar debe ser el punto de código máximo que se colocará en la cadena de caracteres. Como una aproximación, se puede redondear al valor más cercano en la secuencia 127, 255, 65535, 1114111.

Esta es la forma recomendada de asignar un nuevo objeto Unicode. Los objetos creados con esta función no se pueden redimensionar.

Nuevo en la versión 3.3.

PyObject* PyUnicode_FromKindAndData(int kind, const void *buffer, Py_ssize_t size)

Return value: New reference.

Crea un nuevo objeto Unicode con el tipo kind dado (los valores posibles son PyUnicode_1BYTE_KIND etc., según lo retornado por PyUnicode_KIND()). El búfer debe apuntar a un vector (array) de tamaño unidades de 1, 2 o 4 bytes por carácter, según el tipo.

Nuevo en la versión 3.3.

PyObject* PyUnicode_FromStringAndSize(const char *u, Py_ssize_t size)

Return value: New reference.

Crea un objeto Unicode desde el búfer de caracteres u. Los bytes se interpretarán como codificados en UTF-8. El búfer se copia en el nuevo objeto. Si el búfer no es NULL, el valor de retorno podría ser un objeto compartido, es decir, no se permite la modificación de los datos.

Si u es NULL, esta función se comporta como PyUnicode_FromUnicode() con el búfer establecido en NULL. Este uso se considera obsoleto (deprecated) en favor de PyUnicode_New().

PyObject *PyUnicode_FromString(const char *u)

Return value: New reference.

Crea un objeto Unicode a partir de un búfer u de caracteres terminado en nulo y codificado en UTF-8.

PyObject* PyUnicode_FromFormat(const char *format, ...)

Return value: New reference.

Toma una cadena de caracteres format con el estilo de printf() en C y un número variable de argumentos, calcula el tamaño de la cadena Python Unicode resultante y retorna una cadena de caracteres con los valores formateados. Los argumentos variables deben ser tipos de C y deben corresponder exactamente a los caracteres de formato en la cadena de caracteres format codificada en ASCII. Se permiten los siguientes caracteres de formato:

Formatear caracteres

Tipo

Comentario

%%

n/a

El carácter literal %.

%c

int

Un solo carácter, representado como un entero (int) de C.

%d

int

Equivalente a printf("%d"). 1

%u

unsigned int

Equivalente a printf("%u"). 1

%ld

long

Equivalente a printf("%ld"). 1

%li

long

Equivalente a printf("%li"). 1

%lu

unsigned long

Equivalente a printf("%lu"). 1

%lld

long long

Equivalente a printf("%lld"). 1

%lli

long long

Equivalente a printf("%lli"). 1

%llu

unsigned long long

Equivalente a printf("%llu"). 1

%zd

Py_ssize_t

Equivalente a printf("%zd"). 1

%zi

Py_ssize_t

Equivalente a printf("%zi"). 1

%zu

size_t

Equivalente a printf("%zu"). 1

%i

int

Equivalente a printf("%i"). 1

%x

int

Equivalente a printf("%x"). 1

%s

const char*

Un arreglo de caracteres de C terminada en nulo.

%p

const void*

La representación hexadecimal de un puntero en C. Principalmente equivalente a printf("%p") excepto que se garantiza que comience con el literal 0x, independiente de lo que produzca el printf de la plataforma.

%A

PyObject*

El resultado de llamar ascii().

%U

PyObject*

Un objeto Unicode.

%V

PyObject*, const char*

Un objeto Unicode (que puede ser NULL) y un arreglo de caracteres de C terminada en nulo como segundo parámetro (que se utilizará, si el primer parámetro es NULL).

%S

PyObject*

El resultado de llamar PyObject_Str().

%R

PyObject*

El resultado de llamar PyObject_Repr().

Un carácter de formato no reconocido hace que todo el resto de la cadena de formato se copie tal cual a la cadena de resultado y se descartan los argumentos adicionales.

Nota

La unidad del formateador de ancho es el número de caracteres en lugar de bytes. La unidad del formateador de precisión es la cantidad de bytes para "%s" y "%V" `` (si el argumento ``PyObject* es NULL), y una cantidad de caracteres para "%A", "%U", "%S", "%R" y "%V" (si el argumento PyObject* no es NULL).

1(1,2,3,4,5,6,7,8,9,10,11,12,13)

Para especificadores de enteros (d, u, ld, li, lu, lld, lli, llu, zd, zi, zu, i, x): el indicador de conversión 0 tiene efecto incluso cuando se proporciona una precisión.

Distinto en la versión 3.2: Soporte agregado para "%lld" y "%llu".

Distinto en la versión 3.3: Soporte agregado para "%li", "%lli" y "%zi".

Distinto en la versión 3.4: Soporte agregado para formateadores de anchura y precisión para "%s", "%A", "%U", "%V", "%S", "%R".

PyObject* PyUnicode_FromFormatV(const char *format, va_list vargs)

Return value: New reference.

Idéntico a PyUnicode_FromFormat() excepto que toma exactamente dos argumentos.

PyObject* PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)

Return value: New reference.

Decodifica un objeto codificado obj en un objeto Unicode.

bytes, bytearray y otros los objetos similares a bytes se decodifican de acuerdo con el encoding dado y utilizan el manejo de errores definido por errors. Ambos pueden ser NULL para que la interfaz use los valores predeterminados (ver Códecs incorporados para más detalles).

Todos los demás objetos, incluidos los objetos Unicode, hacen que se establezca un TypeError.

La API retorna NULL si hubo un error. La entidad que hace la llamadas es la responsable de desreferenciar los objetos retornados.

Py_ssize_t PyUnicode_GetLength(PyObject *unicode)

Retorna la longitud del objeto Unicode, en puntos de código.

Nuevo en la versión 3.3.

Py_ssize_t PyUnicode_CopyCharacters(PyObject *to, Py_ssize_t to_start, PyObject *from, Py_ssize_t from_start, Py_ssize_t how_many)

Copia caracteres de un objeto Unicode en otro. Esta función realiza la conversión de caracteres cuando es necesario y recurre a memcpy() si es posible. Retorna -1 y establece una excepción en caso de error; de lo contrario, retorna el número de caracteres copiados.

Nuevo en la versión 3.3.

Py_ssize_t PyUnicode_Fill(PyObject *unicode, Py_ssize_t start, Py_ssize_t length, Py_UCS4 fill_char)

Rellena una cadena con un carácter: escriba fill_char en unicode[inicio:inicio+longitud].

Falla si fill_char es más grande que el carácter máximo de la cadena, o si la cadena tiene más de 1 referencia.

Retorna el número de caracteres escritos o retorna -1 y genera una excepción en caso de error.

Nuevo en la versión 3.3.

int PyUnicode_WriteChar(PyObject *unicode, Py_ssize_t index, Py_UCS4 character)

Escribe un carácter en una cadena de caracteres. La cadena debe haberse creado a través de PyUnicode_New(). Dado que se supone que las cadenas de caracteres Unicode son inmutables, la cadena no debe compartirse o no se ha cifrado todavía.

Esta función comprueba que unicode es un objeto Unicode, que el índice no está fuera de los límites y que el objeto se puede modificar de forma segura (es decir, si su número de referencia es uno).

Nuevo en la versión 3.3.

Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)

Lee un carácter de una cadena de caracteres. Esta función verifica que unicode es un objeto Unicode y que el índice no está fuera de límites, en contraste con la versión de macro PyUnicode_READ_CHAR().

Nuevo en la versión 3.3.

PyObject* PyUnicode_Substring(PyObject *str, Py_ssize_t start, Py_ssize_t end)

Return value: New reference.

Retorna una subcadena de caracteres de str, desde el índice de caracteres start (incluido) al índice de caracteres end (excluido). Los índices negativos no son compatibles.

Nuevo en la versión 3.3.

Py_UCS4* PyUnicode_AsUCS4(PyObject *u, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null)

Copia la cadena de caracteres u en un búfer UCS4, incluido un carácter nulo, si copy_null está configurado. Retorna NULL y establece una excepción en caso de error (en particular, a SystemError si buflen es menor que la longitud de u). buffer se retorna en caso de éxito.

Nuevo en la versión 3.3.

Py_UCS4* PyUnicode_AsUCS4Copy(PyObject *u)

Copia la cadena de caracteres u en un nuevo búfer UCS4 que se asigna usando PyMem_Malloc(). Si esto falla, se retorna NULL con un MemoryError establecido. El búfer retornado siempre tiene un punto de código nulo adicional agregado.

Nuevo en la versión 3.3.

APIs de Py_UNICODE deprecadas

Deprecated since version 3.3, will be removed in version 3.12.

Estas funciones API están en desuso con la implementación de PEP 393 [https://www.python.org/dev/peps/pep-0393]. Los módulos de extensión pueden continuar usándolos, ya que no se eliminarán en Python 3.x, pero deben ser conscientes de que su uso ahora puede causar problemas de rendimiento y memoria.

PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)

Return value: New reference.

Crea un objeto Unicode desde el búfer Py_UNICODE u del tamaño dado. u puede ser NULL, lo que hace que el contenido no esté definido. Es responsabilidad del usuario completar los datos necesarios. El búfer se copia en el nuevo objeto.

Si el búfer no es NULL, el valor de retorno podría ser un objeto compartido. Por lo tanto, la modificación del objeto Unicode resultante solo se permite cuando u es NULL.

Si el búfer es NULL, se debe llamar a PyUnicode_READY() una vez que se haya llenado el contenido de la cadena de caracteres antes de usar cualquiera de las macros de acceso, como PyUnicode_KIND().

Deprecated since version 3.3, will be removed in version 3.12: Por favor migrar para usar PyUnicode_FromKindAndData(), PyUnicode_FromWideChar() o PyUnicode_New().

Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)

Retorna un puntero de solo lectura al búfer Py_UNICODE interno del objeto Unicode, o NULL en caso de error. Esto creará la representación Py_UNICODE* del objeto si aún no está disponible. El búfer siempre termina con un punto de código nulo adicional. Tenga en cuenta que la cadena de caracteres resultante Py_UNICODE también puede contener puntos de código nulo incrustados, lo que provocaría que la cadena se truncara cuando se usara en la mayoría de las funciones de C.

Deprecated since version 3.3, will be removed in version 3.12: Parte del estilo antiguo de la API Unicode, por favor migrar para usar PyUnicode_AsUCS4(), PyUnicode_AsWideChar(), PyUnicode_ReadChar() o APIs nuevas similares.

Deprecated since version 3.3, will be removed in version 3.10.

PyObject* PyUnicode_TransformDecimalToASCII(Py_UNICODE *s, Py_ssize_t size)

Return value: New reference.

Crea un objeto Unicode reemplazando todos los dígitos decimales en el búfer Py_UNICODE del size dado por dígitos ASCII 0–9 de acuerdo con su valor decimal. Retorna NULL si ocurre una excepción.

Deprecated since version 3.3, will be removed in version 3.11: Parte del estilo antiguo de la API Py_UNICODE; por favor migrar para usar Py_UNICODE_TODECIMAL().

Py_UNICODE* PyUnicode_AsUnicodeAndSize(PyObject *unicode, Py_ssize_t *size)

Como PyUnicode_AsUnicode(), pero también guarda la longitud del arreglo Py_UNICODE() (excluyendo el terminador nulo adicional) en size. Tenga en cuenta que la cadena de caracteres resultante Py_UNICODE* puede contener puntos de código nulo incrustados, lo que provocaría que la cadena se truncara cuando se usara en la mayoría de las funciones de C.

Nuevo en la versión 3.3.

Deprecated since version 3.3, will be removed in version 3.12: Parte del estilo antiguo de la API Unicode, por favor migrar para usar PyUnicode_AsUCS4(), PyUnicode_AsWideChar(), PyUnicode_ReadChar() o APIs nuevas similares.

Py_UNICODE* PyUnicode_AsUnicodeCopy(PyObject *unicode)

Crea una copia de una cadena de caracteres Unicode que termina con un punto de código nulo. Retorna NULL y genera una excepción MemoryError en caso de fallo de asignación de memoria; de lo contrario, retorna un nuevo búfer asignado (use PyMem_Free() para liberar el búfer). Tenga en cuenta que la cadena de caracteres resultante Py_UNICODE* puede contener puntos de código nulo incrustados, lo que provocaría que la cadena se truncara cuando se usara en la mayoría de las funciones de C.

Nuevo en la versión 3.2.

Por favor migrar para usar PyUnicode_AsUCS4Copy() o API nuevas similares.

Py_ssize_t PyUnicode_GetSize(PyObject *unicode)

Retorna el tamaño de la representación en desuso Py_UNICODE, en unidades de código (esto incluye pares sustitutos como 2 unidades).

Deprecated since version 3.3, will be removed in version 3.12: Parte de la API Unicode de estilo antiguo, por favor migrar para usar PyUnicode_GET_LENGTH().

PyObject* PyUnicode_FromObject(PyObject *obj)

Return value: New reference.

Copia una instancia de un subtipo Unicode a un nuevo objeto Unicode verdadero si es necesario. Si obj ya es un verdadero objeto Unicode (no un subtipo), retorna la referencia con un recuento incrementado.

Los objetos que no sean Unicode o sus subtipos causarán un TypeError.

Codificación regional

La codificación local actual se puede utilizar para decodificar texto del sistema operativo.

PyObject* PyUnicode_DecodeLocaleAndSize(const char *str, Py_ssize_t len, const char *errors)

Return value: New reference.

Decodifica una cadena de caracteres UTF-8 en Android y VxWorks, o de la codificación de configuración regional actual en otras plataformas. Los manejadores de errores admitidos son "estricto" y "subrogateescape" (PEP 383 [https://www.python.org/dev/peps/pep-0383]). El decodificador usa el controlador de errores "estricto" si errors es``NULL``. str debe terminar con un carácter nulo pero no puede contener caracteres nulos incrustados.

Utilice PyUnicode_DecodeFSDefaultAndSize() para decodificar una cadena de Py_FileSystemDefaultEncoding (la codificación de la configuración regional leída al iniciar Python).

Esta función ignora el modo Python UTF-8.

Ver también

La función Py_DecodeLocale().

Nuevo en la versión 3.3.

Distinto en la versión 3.7: La función ahora también usa la codificación de configuración regional actual para el controlador de errores subrogateescape, excepto en Android. Anteriormente, Py_DecodeLocale() se usaba para el subrogateescape, y la codificación local actual se usaba para estricto.

PyObject* PyUnicode_DecodeLocale(const char *str, const char *errors)

Return value: New reference.

Similar a PyUnicode_DecodeLocaleAndSize(), pero calcula la longitud de la cadena de caracteres usando strlen().

Nuevo en la versión 3.3.

PyObject* PyUnicode_EncodeLocale(PyObject *unicode, const char *errors)

Return value: New reference.

Codifica un objeto Unicode UTF-8 en Android y VxWorks, o en la codificación local actual en otras plataformas. Los manejadores de errores admitidos son "estricto" `` y ``"subrogateescape" (PEP 383 [https://www.python.org/dev/peps/pep-0383]). El codificador utiliza el controlador de errores "estricto" si errors es NULL. Retorna un objeto bytes. unicode no puede contener caracteres nulos incrustados.

Utilice PyUnicode_EncodeFSDefault() para codificar una cadena de caracteres en Py_FileSystemDefaultEncoding (la codificación de la configuración regional leída al iniciar Python).

Esta función ignora el modo Python UTF-8.

Ver también

La función Py_EncodeLocale().

Nuevo en la versión 3.3.

Distinto en la versión 3.7: La función ahora también usa la codificación de configuración regional actual para el controlador de errores subrogateescape, excepto en Android. Anteriormente, Py_EncodeLocale() se usaba para el subrogateescape, y la codificación local actual se usaba para estricto.

Codificación del sistema de archivos

Para codificar y decodificar nombres de archivo y otras cadenas de caracteres de entorno, Py_FileSystemDefaultEncoding debe usarse como codificación, y Py_FileSystemDefaultEncodeErrors debe usarse como controlador de errores (PEP 383 [https://www.python.org/dev/peps/pep-0383] y PEP 529 [https://www.python.org/dev/peps/pep-0529]). Para codificar nombres de archivo a bytes durante el análisis de argumentos, se debe usar el convertidor "O&", pasando PyUnicode_FSConverter() como la función de conversión:

int PyUnicode_FSConverter(PyObject* obj, void* result)

Convertidor ParseTuple : codificar objetos str – obtenidos directamente o mediante la interfaz os.PathLike – a bytes usando PyUnicode_EncodeFSDefault(); los objetos bytes se emiten tal cual. result debe ser un PyBytesObject* que debe liberarse cuando ya no se use.

Nuevo en la versión 3.1.

Distinto en la versión 3.6: Acepta un objeto similar a una ruta (path-like object).

Para decodificar nombres de archivo a str durante el análisis de argumentos, se debe usar el convertidor "O&", pasando PyUnicode_FSDecoder() como la función de conversión:

int PyUnicode_FSDecoder(PyObject* obj, void* result)

Conversor ParseTuple: decodifica objetos bytes – obtenidos directa o indirectamente a través de la interfaz os.PathLike – a str usando PyUnicode_DecodeFSDefaultAndSize(); los objetos str se generan tal cual. result debe ser PyUnicodeObject* que debe liberarse cuando ya no se use.

Nuevo en la versión 3.2.

Distinto en la versión 3.6: Acepta un objeto similar a una ruta (path-like object).

PyObject* PyUnicode_DecodeFSDefaultAndSize(const char *s, Py_ssize_t size)

Return value: New reference.

Decodifica una cadena usando Py_FileSystemDefaultEncoding y el controlador de errores Py_FileSystemDefaultEncodeErrors.

Si Py_FileSystemDefaultEncoding no está configurado, recurre a la codificación de configuración regional.

Py_FileSystemDefaultEncoding se inicializa al inicio desde la codificación local y no se puede modificar más tarde. Si se necesita decodificar una cadena de caracteres de la codificación local actual, utilice PyUnicode_DecodeLocaleAndSize().

Ver también

La función Py_DecodeLocale().

Distinto en la versión 3.6: Utilice el controlador de errores Py_FileSystemDefaultEncodeErrors.

PyObject* PyUnicode_DecodeFSDefault(const char *s)

Return value: New reference.

Decodifique una cadena terminada en nulo usando Py_FileSystemDefaultEncoding y el Py_FileSystemDefaultEncodeErrors controlador de errores.

Si Py_FileSystemDefaultEncoding no está configurado, recurre a la codificación de configuración regional.

Utilice PyUnicode_DecodeFSDefaultAndSize() si conoce la longitud de la cadena.

Distinto en la versión 3.6: Utilice el controlador de errores Py_FileSystemDefaultEncodeErrors.

PyObject* PyUnicode_EncodeFSDefault(PyObject *unicode)

Return value: New reference.

Codifica un objeto Unicode para Py_FileSystemDefaultEncoding con el manejador de errores Py_FileSystemDefaultEncodeErrors, y retorna bytes. Tenga en cuenta que el objeto resultante bytes puede contener bytes nulos.

Si Py_FileSystemDefaultEncoding no está configurado, recurre a la codificación de configuración regional.

Py_FileSystemDefaultEncoding se inicializa al inicio desde la codificación local y no se puede modificar más tarde. Si necesita codificar una cadena a la codificación local actual, utilice PyUnicode_EncodeLocale().

Ver también

La función Py_EncodeLocale().

Nuevo en la versión 3.2.

Distinto en la versión 3.6: Utilice el controlador de errores Py_FileSystemDefaultEncodeErrors.

soporte wchar_t

soporte wchar_t para plataformas que lo soportan:

PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)

Return value: New reference.

Crea un objeto Unicode a partir del búfer wchar_t w del tamaño size dado. Pasar -1 como size indica que la función debe calcular la longitud, usando wcslen. Retorna NULL en caso de falla.

Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *w, Py_ssize_t size)

Copia el contenido del objeto Unicode en el búfer wchar_t w. A lo sumo size se copian los caracteres wchar_t (excluyendo un posible carácter de terminación nulo final). Retorna el número de caracteres wchar_t copiados o -1 en caso de error. Tenga en cuenta que la cadena resultante wchar_t* puede o no tener terminación nula. Es responsabilidad de la persona que llama asegurarse de que la cadena wchar_t* tenga una terminación nula en caso de que la aplicación lo requiera. Además, tenga en cuenta que la cadena wchar_t* podría contener caracteres nulos, lo que provocaría que la cadena se truncara cuando se usara con la mayoría de las funciones de C.

wchar_t* PyUnicode_AsWideCharString(PyObject *unicode, Py_ssize_t *size)

Convierte el objeto Unicode en una cadena de caracteres ancha. La cadena de salida siempre termina con un carácter nulo. Si size no es NULL, escribe el número de caracteres anchos (excluyendo el carácter de terminación nulo final) en *size. Tenga en cuenta que la cadena resultante wchar_t podría contener caracteres nulos, lo que provocaría que la cadena se truncara cuando se usara con la mayoría de las funciones de C. Si size es NULL y la cadena wchar_t* contiene caracteres nulos un ValueError aparece.

Retorna un búfer asignado por PyMem_Alloc() (utilice PyMem_Free() para liberarlo) en caso de éxito. En caso de error, retorna NULL y *size no está definido. Provoca un MemoryError si falla la asignación de memoria.

Nuevo en la versión 3.2.

Distinto en la versión 3.7: Provoca un ValueError si size es NULL y la cadena wchar_t* contiene caracteres nulos.

Códecs incorporados

Python proporciona un conjunto de códecs integrados que están escritos en C para mayor velocidad. Todos estos códecs se pueden usar directamente a través de las siguientes funciones.

Muchas de las siguientes API toman dos argumentos de encoding y errors, y tienen la misma semántica que las del constructor de objetos de cadena incorporado str().

Establecer la codificación en NULL hace que se use la codificación predeterminada, que es ASCII. Las llamadas al sistema de archivos deben usar PyUnicode_FSConverter() para codificar nombres de archivos. Esto utiliza la variable Py_FileSystemDefaultEncoding internamente. Esta variable debe tratarse como de solo lectura: en algunos sistemas, será un puntero a una cadena de caracteres estática, en otros, cambiará en tiempo de ejecución (como cuando la aplicación invoca setlocale).

El manejo de errores se establece mediante errors que también pueden establecerse en NULL, lo que significa usar el manejo predeterminado definido para el códec. El manejo de errores predeterminado para todos los códecs integrados es «estricto» (se lanza ValueError).

The codecs all use a similar interface. Only deviations from the following generic ones are documented for simplicity.

Códecs genéricos

Estas son las APIs de códecs genéricos:

PyObject* PyUnicode_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)

Return value: New reference.

Crea un objeto Unicode decodificando size bytes de la cadena codificada s. encoding y errors tienen el mismo significado que los parámetros del mismo nombre en la función incorporada str(). El códec que se utilizará se busca utilizando el registro de códec Python. Retorna NULL si el códec provocó una excepción.

PyObject* PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)

Return value: New reference.

Codifica un objeto Unicode y retorna el resultado como un objeto de bytes de Python. encoding y errors tienen el mismo significado que los parámetros del mismo nombre en el método Unicode encode(). El códec que se utilizará se busca utilizando el registro de códec Python. Retorna NULL si el códec provocó una excepción.

PyObject* PyUnicode_Encode(const Py_UNICODE *s, Py_ssize_t size, const char *encoding, const char *errors)

Return value: New reference.

Codifica el búfer Py_UNICODE s del tamaño size dado y retorna un objeto de bytes de Python. encoding y errors tienen el mismo significado que los parámetros del mismo nombre en el método Unicode encode(). El códec que se utilizará se busca utilizando el registro de códec Python. Retorna NULL si el códec provocó una excepción.

Deprecated since version 3.3, will be removed in version 3.11: Parte del viejo estilo de la API Py_UNICODE; por favor migrar para usar PyUnicode_AsEncodedString().

Códecs UTF-8

Estas son las APIs del códec UTF-8:

PyObject* PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors)

Return value: New reference.

Crea un objeto Unicode decodificando size bytes de la cadena codificada UTF-8 s. Retorna NULL si el códec provocó una excepción.

PyObject* PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)

Return value: New reference.

Si consumed es NULL, se comporta como PyUnicode_DecodeUTF8(). Si consumed no es NULL, las secuencias de bytes UTF-8 incompletas no se tratarán como un error. Esos bytes no serán decodificados y la cantidad de bytes que han sido decodificados se almacenará en consumed.

PyObject* PyUnicode_AsUTF8String(PyObject *unicode)

Return value: New reference.

Codifica un objeto Unicode usando UTF-8 y retorna el resultado como un objeto de bytes de Python. El manejo de errores es «estricto». Retorna NULL si el códec provocó una excepción.

const char* PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size)

Retorna un puntero a la codificación UTF-8 del objeto Unicode y almacena el tamaño de la representación codificada (en bytes) en size. El argumento size puede ser NULL; en este caso no se almacenará el tamaño. El búfer retornado siempre tiene un byte nulo adicional agregado (no incluido en size), independientemente de si hay otros puntos de código nulo.

En caso de error, se retorna NULL con un conjunto de excepciones y no se almacena size.

This caches the UTF-8 representation of the string in the Unicode object, and subsequent calls will return a pointer to the same buffer. The caller is not responsible for deallocating the buffer. The buffer is deallocated and pointers to it become invalid when the Unicode object is garbage collected.

Nuevo en la versión 3.3.

Distinto en la versión 3.7: El tipo de retorno ahora es const char * en lugar de char *.

const char* PyUnicode_AsUTF8(PyObject *unicode)

Como PyUnicode_AsUTF8AndSize(), pero no almacena el tamaño.

Nuevo en la versión 3.3.

Distinto en la versión 3.7: El tipo de retorno ahora es const char * en lugar de char *.

PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors)

Return value: New reference.

Codifica el búfer Py_UNICODE s del tamaño size dado usando UTF-8 y retorna un objeto de bytes de Python. Retorna NULL si el códec provocó una excepción.

Deprecated since version 3.3, will be removed in version 3.11: Parte del viejo estilo de la API Py_UNICODE; por favor migrar para usar PyUnicode_AsUTF8String(), PyUnicode_AsUTF8AndSize() o PyUnicode_AsEncodedString().

Códecs UTF-32

Estas son las APIs de códecs para UTF-32:

PyObject* PyUnicode_DecodeUTF32(const char *s, Py_ssize_t size, const char *errors, int *byteorder)

Return value: New reference.

Decodifica size bytes de una cadena de búfer codificada UTF-32 y retorna el objeto Unicode correspondiente. errors (si no es NULL) define el manejo de errores. Su valor predeterminado es «estricto».

Si byteorder no es NULL, el decodificador comienza a decodificar utilizando el orden de bytes dado:

*byteorder == -1: little endian
*byteorder == 0:  native order
*byteorder == 1:  big endian

Si *byteorder es cero, y los primeros cuatro bytes de los datos de entrada son una marca de orden de bytes (BOM), el decodificador cambia a este orden de bytes y la BOM no se copia en la cadena de caracteres Unicode resultante. Si *byteorder es -1 o 1, cualquier marca de orden de bytes se copia en la salida.

Una vez completado, *byteorder se establece en el orden de bytes actual al final de los datos de entrada.

Si byteorder es NULL, el códec se inicia en modo de orden nativo.

Retorna NULL si el códec provocó una excepción.

PyObject* PyUnicode_DecodeUTF32Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)

Return value: New reference.

Si consumed es NULL, se comporta como PyUnicode_DecodeUTF32(). Si consumed no es NULL, PyUnicode_DecodeUTF32Stateful() no tratará las secuencias de bytes UTF-32 incompletas finales (como un número de bytes no divisible por cuatro) como un error. Esos bytes no serán decodificados y la cantidad de bytes que han sido decodificados se almacenará en consumed.

PyObject* PyUnicode_AsUTF32String(PyObject *unicode)

Return value: New reference.

Retorna una cadena de bytes de Python usando la codificación UTF-32 en orden de bytes nativo. La cadena siempre comienza con una marca BOM. El manejo de errores es «estricto». Retorna NULL si el códec provocó una excepción.

PyObject* PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)

Return value: New reference.

Retorna un objeto de bytes de Python que contiene el valor codificado UTF-32 de los datos Unicode en s. La salida se escribe de acuerdo con el siguiente orden de bytes:

byteorder == -1: little endian
byteorder == 0:  native byte order (writes a BOM mark)
byteorder == 1:  big endian

Si byteorder es 0, la cadena de caracteres de salida siempre comenzará con la marca Unicode BOM (U+FEFF). En los otros dos modos, no se antepone ninguna marca BOM.

Si Py_UNICODE_WIDE no está definido, los pares sustitutos se mostrarán como un único punto de código.

Retorna NULL si el códec provocó una excepción.

Deprecated since version 3.3, will be removed in version 3.11: Parte del viejo estilo de la API Py_UNICODE; por favor migrar para usar PyUnicode_AsUTF32String(). o PyUnicode_AsEncodedString().

Códecs UTF-16

Estas son las APIs de códecs para UTF-16:

PyObject* PyUnicode_DecodeUTF16(const char *s, Py_ssize_t size, const char *errors, int *byteorder)

Return value: New reference.

Decodifica size bytes de una cadena de caracteres de búfer codificada UTF-16 y retorna el objeto Unicode correspondiente. errors (si no es NULL) define el manejo de errores. Su valor predeterminado es «estricto».

Si byteorder no es NULL, el decodificador comienza a decodificar utilizando el orden de bytes dado:

*byteorder == -1: little endian
*byteorder == 0:  native order
*byteorder == 1:  big endian

Si *byteorder es cero, y los primeros dos bytes de los datos de entrada son una marca de orden de bytes (BOM), el decodificador cambia a este orden de bytes y la BOM no se copia en la cadena de caracteres Unicode resultante. Si *byteorder es -1 o 1, cualquier marca de orden de bytes se copia en la salida (donde dará como resultado un \ufeff o un carácter \ufffe).

After completion, *byteorder is set to the current byte order at the end of input data.

Si byteorder es NULL, el códec se inicia en modo de orden nativo.

Retorna NULL si el códec provocó una excepción.

PyObject* PyUnicode_DecodeUTF16Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)

Return value: New reference.

Si consumed es NULL, se comporta como PyUnicode_DecodeUTF16(). Si consumed no es NULL, PyUnicode_DecodeUTF16Stateful() no tratará las secuencias de bytes UTF-16 incompletas finales (como un número impar de bytes o un par sustituto dividido) como un error. Esos bytes no serán decodificados y la cantidad de bytes que han sido decodificados se almacenará en consumed.

PyObject* PyUnicode_AsUTF16String(PyObject *unicode)

Return value: New reference.

Retorna una cadena de bytes de Python usando la codificación UTF-16 en orden de bytes nativo. La cadena siempre comienza con una marca BOM. El manejo de errores es «estricto». Retorna NULL si el códec provocó una excepción.

PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)

Return value: New reference.

Retorna un objeto de bytes de Python que contiene el valor codificado UTF-16 de los datos Unicode en s. La salida se escribe de acuerdo con el siguiente orden de bytes:

byteorder == -1: little endian
byteorder == 0:  native byte order (writes a BOM mark)
byteorder == 1:  big endian

Si byteorder es 0, la cadena de caracteres de salida siempre comenzará con la marca Unicode BOM (U+FEFF). En los otros dos modos, no se antepone ninguna marca BOM.

Si se define Py_UNICODE_WIDE, un solo valor de Py_UNICODE puede representarse como un par sustituto. Si no está definido, cada uno de los valores Py_UNICODE se interpreta como un carácter UCS-2.

Retorna NULL si el códec provocó una excepción.

Deprecated since version 3.3, will be removed in version 3.11: Parte del viejo estilo de la API Py_UNICODE; por favor migrar para usar PyUnicode_AsUTF16String(). o PyUnicode_AsEncodedString().

Códecs UTF-7

Estas son las APIs del códec UTF-7:

PyObject* PyUnicode_DecodeUTF7(const char *s, Py_ssize_t size, const char *errors)

Return value: New reference.

Crea un objeto Unicode decodificando size bytes de la cadena de caracteres codificada UTF-7 s. Retorna NULL si el códec provocó una excepción.

PyObject* PyUnicode_DecodeUTF7Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)

Return value: New reference.

Si consumed es NULL, se comporta como PyUnicode_DecodeUTF7(). Si consumed no es NULL, las secciones UTF-7 base-64 incompletas no se tratarán como un error. Esos bytes no serán decodificados y la cantidad de bytes que han sido decodificados se almacenará en consumed.

PyObject* PyUnicode_EncodeUTF7(const Py_UNICODE *s, Py_ssize_t size, int base64SetO, int base64WhiteSpace, const char *errors)

Return value: New reference.

Codifica el búfer Py_UNICODE del tamaño dado usando UTF-7 y retorna un objeto de bytes de Python. Retorna NULL si el códec provocó una excepción.

Si base64SetO no es cero, «Set O» (puntuación que no tiene un significado especial) se codificará en base-64. Si base64WhiteSpace no es cero, el espacio en blanco se codificará en base-64. Ambos se establecen en cero para el códec Python «utf-7».

Deprecated since version 3.3, will be removed in version 3.11: Parte del viejo estilo de la API Py_UNICODE; por favor migrar para usar PyUnicode_AsEncodedString().

Códecs Unicode escapado

Estas son las APIs de códecs para Unicode escapado:

PyObject* PyUnicode_DecodeUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)

Return value: New reference.

Crea un objeto Unicode decodificando size bytes de la cadena codificada Unicode escapada (Unicode-Escape) s. Retorna NULL si el códec provocó una excepción.

PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode)

Return value: New reference.

Codifica un objeto Unicode usando Unicode escapado (Unicode-Escape) y retorna el resultado como un objeto de bytes. El manejo de errores es «estricto». Retorna NULL si el códec provocó una excepción.

PyObject* PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)

Return value: New reference.

Codifica el búfer Py_UNICODE del tamaño size dado utilizando Unicode escapado y retorna un objeto de bytes. Retorna NULL si el códec provocó una excepción.

Deprecated since version 3.3, will be removed in version 3.11: Parte del viejo estilo de la API Py_UNICODE; por favor migrar para usar PyUnicode_AsUnicodeEscapeString().

Códecs para Unicode escapado en bruto

Estas son las API del códec Unicode escapado en bruto (Raw Unicode Escape):

PyObject* PyUnicode_DecodeRawUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)

Return value: New reference.

Crea un objeto Unicode decodificando size bytes de la cadena de caracteres codificada Unicode escapada en bruto (Raw-Unicode-Escape) s. Retorna NULL si el códec provocó una excepción.

PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)

Return value: New reference.

Codifica un objeto Unicode usando Unicode escapado en bruto (Raw-Unicode-Escape) y retorna el resultado como un objeto de bytes. El manejo de errores es «estricto». Retorna NULL si el códec provocó una excepción.

PyObject* PyUnicode_EncodeRawUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)

Return value: New reference.

Codifica el búfer Py_UNICODE del tamaño size dado usando Unicode escapado en bruto (Raw-Unicode-Escape) y retorna un objeto de bytes. Retorna NULL si el códec provocó una excepción.

Deprecated since version 3.3, will be removed in version 3.11: Parte del viejo estilo de la API Py_UNICODE; por favor migrar para usar PyUnicode_AsRawUnicodeEscapeString() o PyUnicode_AsEncodedString().

Códecs Latin-1

Estas son las API del códec Latin-1: Latin-1 corresponde a los primeros 256 ordinales Unicode y solo estos son aceptados por los códecs durante la codificación.

PyObject* PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors)

Return value: New reference.

Crea un objeto Unicode decodificando size bytes de la cadena de caracteres codificada en latin-1 s. Retorna NULL si el códec provocó una excepción.

PyObject* PyUnicode_AsLatin1String(PyObject *unicode)

Return value: New reference.

Codifica un objeto Unicode usando Latin-1 y retorna el resultado como un objeto de bytes Python. El manejo de errores es «estricto». Retorna NULL si el códec provocó una excepción.

PyObject* PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors)

Return value: New reference.

Codifica el búfer Py_UNICODE del tamaño size dado usando Latin-1 y retorna un objeto de bytes de Python. Retorna NULL si el códec provocó una excepción.

Deprecated since version 3.3, will be removed in version 3.11: Parte del viejo estilo de la API Py_UNICODE; por favor migrar para usar PyUnicode_AsLatin1String() o PyUnicode_AsEncodedString().

Códecs ASCII

Estas son las API del códec ASCII. Solo se aceptan datos ASCII de 7 bits. Todos los demás códigos generan errores.

PyObject* PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors)

Return value: New reference.

Crea un objeto Unicode decodificando size bytes de la cadena de caracteres codificada ASCII s. Retorna NULL si el códec provocó una excepción.

PyObject* PyUnicode_AsASCIIString(PyObject *unicode)

Return value: New reference.

Codifica un objeto Unicode usando ASCII y retorna el resultado como un objeto de bytes de Python. El manejo de errores es «estricto». Retorna NULL si el códec provocó una excepción.

PyObject* PyUnicode_EncodeASCII(const Py_UNICODE *s, Py_ssize_t size, const char *errors)

Return value: New reference.

Codifica el búfer Py_UNICODE del tamaño size dado utilizando ASCII y retorna un objeto de bytes de Python. Retorna NULL si el códec provocó una excepción.

Deprecated since version 3.3, will be removed in version 3.11: Parte del viejo estilo de la API Py_UNICODE; por favor migrar para usar PyUnicode_AsASCIIString() o PyUnicode_AsEncodedString().

Códecs de mapa de caracteres

This codec is special in that it can be used to implement many different codecs (and this is in fact what was done to obtain most of the standard codecs included in the encodings package). The codec uses mappings to encode and decode characters. The mapping objects provided must support the __getitem__() mapping interface; dictionaries and sequences work well.

Estos son las API de códec de mapeo:

PyObject* PyUnicode_DecodeCharmap(const char *data, Py_ssize_t size, PyObject *mapping, const char *errors)

Return value: New reference.

Crea un objeto Unicode decodificando size bytes de la cadena de caracteres codificada s usando el objeto mapping dado. Retorna NULL si el códec provocó una excepción.

Si mapping es NULL, se aplicará la decodificación Latin-1. De lo contrario, mapping debe asignar bytes ordinales (enteros en el rango de 0 a 255) a cadenas de caracteres Unicode, enteros (que luego se interpretan como ordinales Unicode) o None. Los bytes de datos sin asignar - los que causan un LookupError, así como los que se asignan a None, 0xFFFE o '\ ufffe', se tratan como asignaciones indefinidas y causan un error.

PyObject* PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)

Return value: New reference.

Codifica un objeto Unicode usando el objeto mapping dado y retorna el resultado como un objeto de bytes. El manejo de errores es «estricto». Retorna NULL si el códec provocó una excepción.

El objeto mapping debe asignar enteros ordinales Unicode a objetos de bytes, enteros en el rango de 0 a 255 o None. Los ordinales de caracteres no asignados (los que causan un LookupError), así como los asignados a Ninguno, se tratan como «mapeo indefinido» y causan un error.

PyObject* PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)

Return value: New reference.

Codifica el búfer Py_UNICODE del tamaño size dado utilizando el objeto mapping dado y retorna el resultado como un objeto de bytes. Retorna NULL si el códec provocó una excepción.

Deprecated since version 3.3, will be removed in version 3.11: Parte del viejo estilo de la API Py_UNICODE; por favor migrar para usar PyUnicode_AsCharmapString() o PyUnicode_AsEncodedString().

La siguiente API de códec es especial en que asigna Unicode a Unicode.

PyObject* PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors)

Return value: New reference.

Traduce una cadena de caracteres aplicando una tabla de mapeo y retornando el objeto Unicode resultante. Retorna NULL cuando el códec provocó una excepción.

La tabla de mapeo debe mapear enteros ordinales Unicode a enteros ordinales Unicode o None (causando la eliminación del carácter).

Las tablas de mapeo solo necesitan proporcionar la interfaz __getitem__(); Los diccionarios y las secuencias funcionan bien. Los ordinales de caracteres no asignados (los que causan un LookupError) se dejan intactos y se copian tal cual.

errors tiene el significado habitual para los códecs. Puede ser NULL, lo que indica que debe usar el manejo de errores predeterminado.

PyObject* PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)

Return value: New reference.

Traduce un búfer Py_UNICODE del tamaño size dado al aplicarle una tabla de mapping de caracteres y retornar el objeto Unicode resultante. Retorna NULL cuando el códec provocó una excepción.

Deprecated since version 3.3, will be removed in version 3.11: Parte del viejo estilo de la API Py_UNICODE; por favor migrar para usar PyUnicode_Translate(). o generic codec based API

Códecs MBCS para Windows

Estas son las API de códec MBCS. Actualmente solo están disponibles en Windows y utilizan los convertidores Win32 MBCS para implementar las conversiones. Tenga en cuenta que MBCS (o DBCS) es una clase de codificaciones, no solo una. La codificación de destino está definida por la configuración del usuario en la máquina que ejecuta el códec.

PyObject* PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors)

Return value: New reference.

Crea un objeto Unicode decodificando size bytes de la cadena de caracteres codificada con MBCS s. Retorna NULL si el códec provocó una excepción.

PyObject* PyUnicode_DecodeMBCSStateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)

Return value: New reference.

Si consumed es NULL, se comporta como PyUnicode_DecodeMBCS(). Si consumed no es NULL, PyUnicode_DecodeMBCSStateful() no decodificará el byte inicial y el número de bytes que se han decodificado se almacenará en consumed.

PyObject* PyUnicode_AsMBCSString(PyObject *unicode)

Return value: New reference.

Codifica un objeto Unicode usando MBCS y retorna el resultado como un objeto de bytes de Python. El manejo de errores es «estricto». Retorna NULL si el códec provocó una excepción.

PyObject* PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors)

Return value: New reference.

Codifica el objeto Unicode utilizando la página de códigos especificada y retorna un objeto de bytes de Python. Retorna NULL si el códec provocó una excepción. Use la página de códigos CP_ACP para obtener el codificador MBCS.

Nuevo en la versión 3.3.

PyObject* PyUnicode_EncodeMBCS(const Py_UNICODE *s, Py_ssize_t size, const char *errors)

Return value: New reference.

Codifica el búfer Py_UNICODE del tamaño size dado usando MBCS y retorna un objeto de bytes de Python. Retorna NULL si el códec provocó una excepción.

Deprecated since version 3.3, will be removed in version 4.0: Parte del viejo estilo Py_UNICODE de la API; por favor migrar a PyUnicode_AsMBCSString(), PyUnicode_EncodeCodePage() o PyUnicode_AsEncodedString().

Métodos & Ranuras (Slots)

Métodos y funciones de ranura (Slot)

Las siguientes API son capaces de manejar objetos Unicode y cadenas de caracteres en la entrada (nos referimos a ellos como cadenas de caracteres en las descripciones) y retorna objetos Unicode o enteros según corresponda.

Todos retornan NULL o -1 si ocurre una excepción.

PyObject* PyUnicode_Concat(PyObject *left, PyObject *right)

Return value: New reference.

Une dos cadenas de caracteres que dan una nueva cadena de caracteres Unicode.

PyObject* PyUnicode_Split(PyObject *s, PyObject *sep, Py_ssize_t maxsplit)

Return value: New reference.

Divide una cadena de caracteres dando una lista de cadenas de caracteres Unicode. Si sep es NULL, la división se realizará en todas las subcadenas de espacios en blanco. De lo contrario, las divisiones ocurren en el separador dado. A lo sumo se realizarán maxsplit divisiones. Si es negativo, no se establece ningún límite. Los separadores no están incluidos en la lista resultante.

PyObject* PyUnicode_Splitlines(PyObject *s, int keepend)

Return value: New reference.

Split a Unicode string at line breaks, returning a list of Unicode strings. CRLF is considered to be one line break. If keepend is 0, the line break characters are not included in the resulting strings.

PyObject* PyUnicode_Join(PyObject *separator, PyObject *seq)

Return value: New reference.

Une una secuencia de cadenas de caracteres usando el separator dado y retorna la cadena de caracteres Unicode resultante.

Py_ssize_t PyUnicode_Tailmatch(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)

Retorna 1 si substr coincide con str[start:end] en el final de cola dado (direction == -1 significa hacer una coincidencia de prefijo, direction == 1 una coincidencia de sufijo), 0 de lo contrario. retorne -1 si ocurrió un error.

Py_ssize_t PyUnicode_Find(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)

Retorna la primera posición de substr en str[start:end] usando la direction dada (direction == 1 significa hacer una búsqueda hacia adelante, direction == -1 una búsqueda hacia atrás). El valor de retorno es el índice de la primera coincidencia; un valor de -1 indica que no se encontró ninguna coincidencia, y -2 indica que se produjo un error y se ha establecido una excepción.

Py_ssize_t PyUnicode_FindChar(PyObject *str, Py_UCS4 ch, Py_ssize_t start, Py_ssize_t end, int direction)

Retorna la primera posición del carácter ch en str[inicio:fin] usando la direction dada (direction == 1 significa hacer una búsqueda hacia adelante, direction == -1 una búsqueda hacia atrás). El valor de retorno es el índice de la primera coincidencia; un valor de -1 indica que no se encontró ninguna coincidencia, y -2 indica que se produjo un error y se ha establecido una excepción.

Nuevo en la versión 3.3.

Distinto en la versión 3.7: start y end ahora están ajustados para comportarse como str[start:end].

Py_ssize_t PyUnicode_Count(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end)

Retorna el número de ocurrencias no superpuestas de substr en str[start:end]. Retorna -1 si ocurrió un error.

PyObject* PyUnicode_Replace(PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)

Return value: New reference.

Reemplaza como máximo maxcount ocurrencias de substr en str con replstr y retorna el objeto Unicode resultante. maxcount == -1 significa reemplazar todas las ocurrencias.

int PyUnicode_Compare(PyObject *left, PyObject *right)

Compara dos cadenas de caracteres y retorna -1, 0, 1 para menor que, igual y mayor que, respectivamente.

Esta función retorna -1 en caso de falla, por lo que se debe llamar a PyErr_Occurred() para verificar si hay errores.

int PyUnicode_CompareWithASCIIString(PyObject *uni, const char *string)

Compare un objeto Unicode, uni, con string y retorna -1, 0, 1 para menor que, igual y mayor que, respectivamente. Es mejor pasar solo cadenas de caracteres codificadas en ASCII, pero la función interpreta la cadena de entrada como ISO-8859-1 si contiene caracteres no ASCII.

Esta función no genera excepciones.

PyObject* PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)

Return value: New reference.

Comparación enriquecida de dos cadenas de caracteres Unicode y retorna uno de los siguientes:

NULL en caso de que se produzca una excepción

Py_True o Py_False para comparaciones exitosas

Py_NotImplemented en caso que se desconozca la combinación de tipos

Los posibles valores para op son Py_GT, Py_GE, Py_EQ, Py_NE, Py_LT, y Py_LE.

PyObject* PyUnicode_Format(PyObject *format, PyObject *args)

Return value: New reference.

Retorna un nuevo objeto de cadena de caracteres desde format y args; esto es análogo al format % args.

int PyUnicode_Contains(PyObject *container, PyObject *element)

Comprueba si element está contenido en container y retorna verdadero o falso en consecuencia.

element tiene que convertir a una cadena de caracteres Unicode. Se retorna -1 si hubo un error.

void PyUnicode_InternInPlace(PyObject **string)

Interna el argumento *string en su lugar. El argumento debe ser la dirección de una variable de puntero que apunta a un objeto Unicode de cadena de caracteres Python. Si hay una cadena de caracteres interna existente que es igual a *string, establece *string (disminuyendo el recuento de referencias del objeto de cadena de caracteres anterior e incrementando el recuento de referencias del objeto de cadena de caracteres interna), de lo contrario deja solo *string y lo interna (incrementando su recuento de referencias). (Aclaración: a pesar de que se habla mucho sobre el recuento de referencias, piense en esta función como neutral de recuento de referencia; usted es el propietario del objeto después de la llamada si y solo si lo tenía antes de la llamada).

PyObject* PyUnicode_InternFromString(const char *v)

Return value: New reference.

Una combinación de PyUnicode_FromString() y PyUnicode_InternInPlace(), que retorna un nuevo objeto de cadena de caracteres Unicode que ha sido creado internamente o una nueva referencia(«propia») a un objeto de cadena de caracteres interno anterior con el mismo valor.

Objetos Tuplas

PyTupleObject

Este subtipo de PyObject representa un objeto tupla de Python.

PyTypeObject PyTuple_Type

Esta instancia de PyTypeObject representa el tipo tupla de Python; es el mismo objeto que tuple en la capa de Python.

int PyTuple_Check(PyObject *p)

Retorna verdadero si p es un objeto tupla o una instancia de un subtipo del tipo tupla. Esta función siempre finaliza con éxito.

int PyTuple_CheckExact(PyObject *p)

Retorna verdadero si p es un objeto tupla pero no una instancia de un subtipo del tipo tupla. Esta función siempre finaliza con éxito.

PyObject* PyTuple_New(Py_ssize_t len)

Return value: New reference.

Retorna un nuevo objeto tupla de tamaño len o NULL en caso de falla.

PyObject* PyTuple_Pack(Py_ssize_t n, ...)

Return value: New reference.

Retorna un nuevo objeto tupla de tamaño n, o NULL en caso de falla. Los valores de tupla se inicializan en los argumentos C posteriores n que apuntan a objetos de Python. PyTuple_Pack (2, a, b) es equivalente a Py_BuildValue("(OO)", a, b).

Py_ssize_t PyTuple_Size(PyObject *p)

Toma un puntero a un objeto de tupla y retorna el tamaño de esa tupla.

Py_ssize_t PyTuple_GET_SIZE(PyObject *p)

Retorna el tamaño de la tupla p, que no debe ser NULL y apunta a una tupla; No se realiza ninguna comprobación de errores.

PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)

Return value: Borrowed reference.

Retorna el objeto en la posición pos en la tupla señalada por p. Si pos está fuera de los límites, retorna NULL y establece una excepción IndexError.

PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)

Return value: Borrowed reference.

Como PyTuple_GetItem(), pero no verifica sus argumentos.

PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)

Return value: New reference.

Retorna la porción de la tupla señalada por p entre low y high, o NULL en caso de falla. Este es el equivalente de la expresión de Python p[bajo:alto]. La indexación desde el final de la lista no es compatible.

int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)

Inserta una referencia al objeto o en la posición pos de la tupla señalada por p. Retorna 0 en caso de éxito. Si pos está fuera de límites, retorna -1 y establece una excepción IndexError.

Nota

Esta función «roba» una referencia a o y descarta una referencia a un elemento que ya está en la tupla en la posición afectada.

void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)

Al igual que PyTuple_SetItem(), pero no realiza ninguna comprobación de errores, y debe solo usarse para completar tuplas nuevas.

Nota

Este macro «roba» una referencia a o y, a diferencia de PyTuple_SetItem(), no descarta una referencia a ningún elemento que se está reemplazando; cualquier referencia en la tupla en la posición pos se filtrará.

int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)

Se puede usar para cambiar el tamaño de una tupla. newsize será el nuevo tamaño de la tupla. Debido a que se supone que las tuplas son inmutables, esto solo debe usarse si solo hay una referencia al objeto. No use esto si la tupla ya puede ser conocida por alguna otra parte del código. La tupla siempre crecerá o disminuirá al final. Piense en esto como destruir la antigua tupla y crear una nueva, solo que de manera más eficiente. Retorna 0 en caso de éxito. El código del cliente nunca debe suponer que el valor resultante de *p será el mismo que antes de llamar a esta función. Si se reemplaza el objeto referenciado por *p, se destruye el original *p. En caso de fallo, retorna -1 y establece *p en NULL, y lanza MemoryError o SystemError.

Objetos de secuencia de estructura

Los objetos de secuencia de estructura son el equivalente en C de los objetos namedtuple(), es decir, una secuencia a cuyos elementos también se puede acceder a través de atributos. Para crear una secuencia de estructura, primero debe crear un tipo de secuencia de estructura específico.

PyTypeObject* PyStructSequence_NewType(PyStructSequence_Desc *desc)

Return value: New reference.

Crea un nuevo tipo de secuencia de estructura a partir de los datos en desc, que se describen a continuación. Las instancias del tipo resultante se pueden crear con PyStructSequence_New().

void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc)

Inicializa una secuencia de estructura tipo type desde desc en su lugar.

int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc)

Lo mismo que PyStructSequence_InitType, pero retorna 0 en caso de éxito y -1 en caso de error.

Nuevo en la versión 3.4.

PyStructSequence_Desc

Contiene la meta información de un tipo de secuencia de estructura para crear.

Campo

Tipo C

Significado

name

const char *

nombre del tipo de secuencia de estructura

doc

const char *

puntero al docstring para el tipo o NULL para omitir

fields

PyStructSequence_Field *

puntero al arreglo terminado en NULL con nombres de campo del nuevo tipo

n_in_sequence

int

cantidad de campos visibles para el lado de Python (si se usa como tupla)

PyStructSequence_Field

Describe un campo de una secuencia de estructura. Como una secuencia de estructura se modela como una tupla, todos los campos se escriben como PyObject*. El índice en el arreglo fields de PyStructSequence_Desc determina qué campo de la secuencia de estructura se describe.

Campo

Tipo C

Significado

name

const char *

nombre para el campo o NULL para finalizar la lista de campos con nombre, establece en PyStructSequence_UnnamedField para dejar sin nombre

doc

const char *

campo docstring o NULL para omitir

const char * const PyStructSequence_UnnamedField

Valor especial para un nombre de campo para dejarlo sin nombre.

Distinto en la versión 3.9: El tipo se cambió de char *.

PyObject* PyStructSequence_New(PyTypeObject *type)

Return value: New reference.

Crea una instancia de type, que debe haberse creado con PyStructSequence_NewType().

PyObject* PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos)

Return value: Borrowed reference.

Retorna el objeto en la posición pos en la secuencia de estructura apuntada por p. No se realiza la comprobación de límites.

PyObject* PyStructSequence_GET_ITEM(PyObject *p, Py_ssize_t pos)

Return value: Borrowed reference.

Macro equivalente de PyStructSequence_GetItem().

void PyStructSequence_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)

Establece el campo en el índice pos de la secuencia de estructura p en el valor o. Como PyTuple_SET_ITEM(), esto solo debe usarse para completar instancias nuevas.

Nota

Esta función «roba» una referencia a o.

void PyStructSequence_SET_ITEM(PyObject *p, Py_ssize_t *pos, PyObject *o)

Macro equivalente de PyStructSequence_SetItem().

Nota

Esta función «roba» una referencia a o.

Objetos lista

PyListObject

Este subtipo de PyObject representa un objeto lista de Python.

PyTypeObject PyList_Type

Esta instancia de PyTypeObject representa el tipo de lista de Python. Este es el mismo objeto que list en la capa de Python.

int PyList_Check(PyObject *p)

Retorna verdadero si p es un objeto de lista o una instancia de un subtipo del tipo lista. Esta función siempre finaliza con éxito.

int PyList_CheckExact(PyObject *p)

Retorna verdadero si p es un objeto lista, pero no una instancia de un subtipo del tipo lista. Esta función siempre finaliza con éxito.

PyObject* PyList_New(Py_ssize_t len)

Return value: New reference.

Retorna una nueva lista de longitud len en caso de éxito o NULL en caso de error.

Nota

Si len es mayor que cero, los elementos del objeto de la lista retornada se establecen en NULL. Por lo tanto, no puede utilizar funciones API abstractas como PySequence_SetItem() o exponer el objeto al código Python antes de configurar todos los elementos en un objeto real con PyList_SetItem().

Py_ssize_t PyList_Size(PyObject *list)

Retorna la longitud del objeto lista en list; esto es equivalente a len(list) en un objeto lista.

Py_ssize_t PyList_GET_SIZE(PyObject *list)

Forma macro de PyList_Size() sin comprobación de errores.

PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index)

Return value: Borrowed reference.

Retorna el objeto en la posición index en la lista a la que apunta list. La posición no debe ser negativa; La indexación desde el final de la lista no es compatible. Si index está fuera de los límites (<0 o >= len(list)), retorna NULL y establece una excepción IndexError.

PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i)

Return value: Borrowed reference.

Forma macro de PyList_GetItem() sin comprobación de errores.

int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)

Establece el elemento en el índice index en la lista a item. Retorna 0 en caso de éxito. Si index está fuera de límites, retorna -1 y establece una excepción IndexError.

Nota

Esta función «roba» una referencia a item y descarta una referencia a un elemento que ya está en la lista en la posición afectada.

void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)

Forma macro de PyList_SetItem() sin comprobación de errores. Esto normalmente solo se usa para completar nuevas listas donde no hay contenido anterior.

Nota

Este macro «roba» una referencia a item y, a diferencia de PyList_SetItem(), no descarta una referencia a ningún elemento que se está reemplazando; cualquier referencia en list en la posición i se filtrará.

int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)

Inserta el elemento item en la lista list delante del índice index. Retorna 0 si tiene éxito; retorna -1 y establece una excepción si no tiene éxito. Análogo a list.insert(index, item).

int PyList_Append(PyObject *list, PyObject *item)

Agrega el objeto item al final de la lista list. Retorna 0 si tiene éxito; retorna -1 y establece una excepción si no tiene éxito. Análogo a list.append(item).

PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)

Return value: New reference.

Retorna una lista de los objetos en list que contiene los objetos between, low y high. Retorna NULL y establece una excepción si no tiene éxito. Análogo a list[low:high]. La indexación desde el final de la lista no es compatible.

int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)

Establece el segmento de list entre low y high para el contenido de itemlist. Análogo a list[low:high] = itemlist. La lista itemlist puede ser NULL, lo que indica la asignación de una lista vacía (eliminación de segmentos). Retorna 0 en caso de éxito, -1 en caso de error. La indexación desde el final de la lista no es compatible.

int PyList_Sort(PyObject *list)

Ordena los elementos de list en su lugar. Retorna 0 en caso de éxito, -1 en caso de error. Esto es equivalente a list.sort().

int PyList_Reverse(PyObject *list)

Invierte los elementos de la lista list en su lugar. Retorna 0 en caso de éxito, -1 en caso de error. Este es el equivalente de list.reverse().

PyObject* PyList_AsTuple(PyObject *list)

Return value: New reference.

Retorna un nuevo objeto tupla que contiene el contenido de list; equivalente a tuple(list).

Objetos Diccionarios

PyDictObject

Este subtipo de PyObject representa un objeto diccionario de Python.

PyTypeObject PyDict_Type

Esta instancia de PyTypeObject representa el tipo diccionario de Python. Este es el mismo objeto que dict en la capa de Python.

int PyDict_Check(PyObject *p)

Retorna verdadero si p es un objeto dict o una instancia de un subtipo del tipo dict. Esta función siempre finaliza con éxito.

int PyDict_CheckExact(PyObject *p)

Retorna verdadero si p es un objeto dict, pero no una instancia de un subtipo del tipo dict. Esta función siempre finaliza con éxito.

PyObject* PyDict_New()

Return value: New reference.

Retorna un nuevo diccionario vacío, o NULL en caso de falla.

PyObject* PyDictProxy_New(PyObject *mapping)

Return value: New reference.

Retorna un objeto a types.MappingProxyType para una asignación que imponga un comportamiento de solo lectura. Esto normalmente se usa para crear una vista para evitar la modificación del diccionario para los tipos de clase no dinámicos.

void PyDict_Clear(PyObject *p)

Vacía un diccionario existente de todos los pares clave-valor (key-value).

int PyDict_Contains(PyObject *p, PyObject *key)

Determine si el diccionario p contiene key. Si un elemento en p coincide con la clave key, retorna 1; de lo contrario, retorna 0. En caso de error, retorna -1. Esto es equivalente a la expresión de Python key in p.

PyObject* PyDict_Copy(PyObject *p)

Return value: New reference.

Retorna un nuevo diccionario que contiene los mismos pares clave-valor (key-value) que p.

int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)

Inserta val en el diccionario p con una clave key. key debe ser hashable; si no lo es, se lanzará TypeError. Retorna 0 en caso de éxito o -1 en caso de error. Esta función no roba una referencia a val.

int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)

Inserta val en el diccionario p usando key como clave. key debe ser un const char*. El objeto clave se crea usando PyUnicode_FromString(key). Retorna 0 en caso de éxito o -1 en caso de error. Esta función no roba una referencia a val.

int PyDict_DelItem(PyObject *p, PyObject *key)

Elimina la entrada en el diccionario p con la clave key. key debe ser hashable; si no lo es, se lanza TypeError. Si key no está en el diccionario, se lanza KeyError. Retorna 0 en caso de éxito o -1 en caso de error.

int PyDict_DelItemString(PyObject *p, const char *key)

Elimina la entrada en el diccionario p que tiene una clave especificada por la cadena de caracteres key. Si key no está en el diccionario, se lanza KeyError. Retorna 0 en caso de éxito o -1 en caso de error.

PyObject* PyDict_GetItem(PyObject *p, PyObject *key)

Return value: Borrowed reference.

Retorna el objeto del diccionario p que tiene una clave key. Retorna NULL si la clave key no está presente, pero sin lanzar una excepción.

Tenga en cuenta que las excepciones que se producen al llamar __hash__() y __eq__() se suprimirán los métodos. Para obtener informes de errores, utilice PyDict_GetItemWithError () en su lugar.

PyObject* PyDict_GetItemWithError(PyObject *p, PyObject *key)

Return value: Borrowed reference.

Variante de PyDict_GetItem() que no suprime las excepciones. Retorna NULL con una excepción establecida si se produjo una excepción. Retorna NULL sin una excepción establecida si la clave no estaba presente.

PyObject* PyDict_GetItemString(PyObject *p, const char *key)

Return value: Borrowed reference.

Esto es lo mismo que PyDict_GetItem(), pero key se especifica como un const char*, en lugar de un PyObject*.

Tenga en cuenta que las excepciones que se producen al llamar a __hash__() y __eq__() y al crear un objeto de cadena de caracteres temporal se suprimirán. Para obtener informes de errores, utilice PyDict_GetItemWithError() en su lugar.

PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)

Return value: Borrowed reference.

Esto es lo mismo al nivel de Python dict.setdefault(). Si está presente, retorna el valor correspondiente a key del diccionario p. Si la clave no está en el dict, se inserta con el valor defaultobj y se retorna defaultobj. Esta función evalúa la función hash de key solo una vez, en lugar de evaluarla independientemente para la búsqueda y la inserción.

Nuevo en la versión 3.4.

PyObject* PyDict_Items(PyObject *p)

Return value: New reference.

Retorna un PyListObject que contiene todos los elementos del diccionario.

PyObject* PyDict_Keys(PyObject *p)

Return value: New reference.

Retorna un PyListObject que contiene todas las claves del diccionario.

PyObject* PyDict_Values(PyObject *p)

Return value: New reference.

Retorna un PyListObject que contiene todos los valores del diccionario p.

Py_ssize_t PyDict_Size(PyObject *p)

Retorna el número de elementos en el diccionario. Esto es equivalente a len(p) en un diccionario.

int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)

Itera sobre todos los pares clave-valor en el diccionario p. El Py_ssize_t al que se refiere ppos debe inicializarse a 0 antes de la primera llamada a esta función para iniciar la iteración; la función retorna verdadero para cada par en el diccionario y falso una vez que todos los pares han sido reportados. Los parámetros pkey y pvalue deben apuntar a variables PyObject* que se completarán con cada clave y valor, respectivamente, o pueden ser NULL. Todas las referencias retornadas a través de ellos se toman prestadas. ppos no debe modificarse durante la iteración. Su valor representa compensaciones dentro de la estructura del diccionario interno y, dado que la estructura es escasa, las compensaciones no son consecutivas.

Por ejemplo:

PyObject *key, *value;
Py_ssize_t pos = 0;

while (PyDict_Next(self->dict, &pos, &key, &value)) {
    /* do something interesting with the values... */
    ...
}

El diccionario p no debe mutarse durante la iteración. Es seguro modificar los valores de las claves a medida que recorre el diccionario, pero solo mientras el conjunto de claves no cambie. Por ejemplo:

PyObject *key, *value;
Py_ssize_t pos = 0;

while (PyDict_Next(self->dict, &pos, &key, &value)) {
    long i = PyLong_AsLong(value);
    if (i == -1 && PyErr_Occurred()) {
        return -1;
    }
    PyObject *o = PyLong_FromLong(i + 1);
    if (o == NULL)
        return -1;
    if (PyDict_SetItem(self->dict, key, o) < 0) {
        Py_DECREF(o);
        return -1;
    }
    Py_DECREF(o);
}

int PyDict_Merge(PyObject *a, PyObject *b, int override)

Itera sobre el objeto de mapeo b agregando pares clave-valor al diccionario a. b puede ser un diccionario o cualquier objeto que soporte PyMapping_Keys() y PyObject_GetItem(). Si override es verdadero, los pares existentes en a se reemplazarán si se encuentra una clave coincidente en b, de lo contrario, los pares solo se agregarán si no hay una clave coincidente en a. Retorna 0 en caso de éxito o -1 si se lanza una excepción.

int PyDict_Update(PyObject *a, PyObject *b)

Esto es lo mismo que PyDict_Merge(a, b, 1) en C, y es similar a a.update(b) en Python excepto que PyDict_Update() no vuelve a la iteración sobre una secuencia de pares de valores clave si el segundo argumento no tiene el atributo «claves». Retorna 0 en caso de éxito o -1 si se produjo una excepción.

int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)

Actualiza o combina en el diccionario a, desde los pares clave-valor en seq2. seq2 debe ser un objeto iterable que produzca objetos iterables de longitud 2, vistos como pares clave-valor. En el caso de claves duplicadas, el último gana si override es verdadero, de lo contrario, el primero gana. Retorna 0 en caso de éxito o -1 si se produjo una excepción. El equivalente en Python (excepto el valor de retorno)

def PyDict_MergeFromSeq2(a, seq2, override):
    for key, value in seq2:
        if override or key not in a:
            a[key] = value

Objetos Conjunto

This section details the public API for set and frozenset objects. Any functionality not listed below is best accessed using either the abstract object protocol (including PyObject_CallMethod(), PyObject_RichCompareBool(), PyObject_Hash(), PyObject_Repr(), PyObject_IsTrue(), PyObject_Print(), and PyObject_GetIter()) or the abstract number protocol (including PyNumber_And(), PyNumber_Subtract(), PyNumber_Or(), PyNumber_Xor(), PyNumber_InPlaceAnd(), PyNumber_InPlaceSubtract(), PyNumber_InPlaceOr(), and PyNumber_InPlaceXor()).

PySetObject

This subtype of PyObject is used to hold the internal data for both set and frozenset objects. It is like a PyDictObject in that it is a fixed size for small sets (much like tuple storage) and will point to a separate, variable sized block of memory for medium and large sized sets (much like list storage). None of the fields of this structure should be considered public and all are subject to change. All access should be done through the documented API rather than by manipulating the values in the structure.

PyTypeObject PySet_Type

Esta es una instancia de PyTypeObject que representa el tipo Python set.

PyTypeObject PyFrozenSet_Type

Esta es una instancia de PyTypeObject que representa el tipo Python frozenset.

Los siguientes macros de comprobación de tipos funcionan en punteros a cualquier objeto de Python. Del mismo modo, las funciones del constructor funcionan con cualquier objeto Python iterable.

int PySet_Check(PyObject *p)

Retorna verdadero si p es un objeto set o una instancia de un subtipo. Esta función siempre finaliza con éxito.

int PyFrozenSet_Check(PyObject *p)

Retorna verdadero si p es un objeto frozenset o una instancia de un subtipo. Esta función siempre finaliza con éxito.

int PyAnySet_Check(PyObject *p)

Retorna verdadero si p es un objeto set, un objeto frozenset, o una instancia de un subtipo. Esta función siempre finaliza con éxito.

int PyAnySet_CheckExact(PyObject *p)

Retorna verdadero si p es un objeto set o un objeto frozenset pero no una instancia de un subtipo. Esta función siempre finaliza con éxito.

int PyFrozenSet_CheckExact(PyObject *p)

Retorna verdadero si p es un objeto frozenset pero no una instancia de un subtipo. Esta función siempre finaliza con éxito.

PyObject* PySet_New(PyObject *iterable)

Return value: New reference.

Retorna un nuevo set que contiene objetos retornados por iterable. El iterable puede ser NULL para crear un nuevo conjunto vacío. Retorna el nuevo conjunto en caso de éxito o NULL en caso de error. Lanza TypeError si iterable no es realmente iterable. El constructor también es útil para copiar un conjunto (c=set(s)).

PyObject* PyFrozenSet_New(PyObject *iterable)

Return value: New reference.

Retorna un nuevo frozenset que contiene objetos retornados por iterable. El iterable puede ser NULL para crear un nuevo conjunto congelado vacío. Retorna el nuevo conjunto en caso de éxito o NULL en caso de error. Lanza TypeError si iterable no es realmente iterable.

Las siguientes funciones y macros están disponibles para instancias de set o frozenset o instancias de sus subtipos.

Py_ssize_t PySet_Size(PyObject *anyset)

Retorna la longitud de un objeto set o frozenset. Equivalente a len(anyset). Lanza un PyExc_SystemError si anyset no es set, frozenset, o una instancia de un subtipo.

Py_ssize_t PySet_GET_SIZE(PyObject *anyset)

Forma macro de PySet_Size() sin comprobación de errores.

int PySet_Contains(PyObject *anyset, PyObject *key)

Retorna 1 si se encuentra, 0 si no se encuentra y -1 si se encuentra un error. A diferencia del método Python __contains__(), esta función no convierte automáticamente conjuntos no compartibles en congelados temporales. Lanza un TypeError si la key no se puede compartir. Lanza PyExc_SystemError si anyset no es un set, frozenset, o una instancia de un subtipo.

int PySet_Add(PyObject *set, PyObject *key)

Add key to a set instance. Also works with frozenset instances (like PyTuple_SetItem() it can be used to fill in the values of brand new frozensets before they are exposed to other code). Return 0 on success or -1 on failure. Raise a TypeError if the key is unhashable. Raise a MemoryError if there is no room to grow. Raise a SystemError if set is not an instance of set or its subtype.

Las siguientes funciones están disponibles para instancias de set o sus subtipos, pero no para instancias de frozenset o sus subtipos.

int PySet_Discard(PyObject *set, PyObject *key)

Retorna 1 si se encuentra y se elimina, 0 si no se encuentra (no se realiza ninguna acción) y -1 si se encuentra un error. No lanza KeyError por faltar claves. Lanza un TypeError si la key no se puede compartir. A diferencia del método Python discard(), esta función no convierte automáticamente conjuntos no compartibles en congelados temporales. Lanza PyExc_SystemError si set no es una instancia de set o su subtipo.

PyObject* PySet_Pop(PyObject *set)

Return value: New reference.

Retorna una nueva referencia a un objeto arbitrario en el set y elimina el objeto del set. Retorna NULL en caso de falla. Lanza KeyError si el conjunto está vacío. Lanza a SystemError si set no es una instancia de set o su subtipo.

int PySet_Clear(PyObject *set)

Vacía un conjunto existente de todos los elementos.

Objetos función

Hay algunas funciones específicas para las funciones de Python.

PyFunctionObject

La estructura C utilizada para las funciones.

PyTypeObject PyFunction_Type

Esta es una instancia de PyTypeObject y representa el tipo función de Python. Está expuesto a los programadores de Python como types.FunctionType.

int PyFunction_Check(PyObject *o)

Retorna verdadero si o es un objeto función (tiene tipo PyFunction_Type). El parámetro no debe ser NULL. Esta función siempre finaliza con éxito.

PyObject* PyFunction_New(PyObject *code, PyObject *globals)

Return value: New reference.

Retorna un nuevo objeto función asociado con el objeto código code. globals debe ser un diccionario con las variables globales accesibles para la función.

El docstring y el nombre de la función se obtiene del objeto código. __module__ se obtiene de globals *. El argumento *defaults, annotations y closure se establecen en NULL. __qualname__ se establece en el mismo valor que el nombre de la función.

PyObject* PyFunction_NewWithQualName(PyObject *code, PyObject *globals, PyObject *qualname)

Return value: New reference.

Como PyFunction_New(), pero también permite configurar el atributo __qualname__ del objeto función. qualname debe ser un objeto unicode o NULL; si es NULL, el atributo __qualname__ se establece en el mismo valor que su atributo __name__.

Nuevo en la versión 3.3.

PyObject* PyFunction_GetCode(PyObject *op)

Return value: Borrowed reference.

Retorna el objeto código asociado con el objeto función op.

PyObject* PyFunction_GetGlobals(PyObject *op)

Return value: Borrowed reference.

Retorna el diccionario global asociado con el objeto función op.

PyObject* PyFunction_GetModule(PyObject *op)

Return value: Borrowed reference.

Retorna el atributo __module__ del objeto función op. Normalmente es una cadena de caracteres que contiene el nombre del módulo, pero se puede establecer en cualquier otro objeto mediante el código Python.

PyObject* PyFunction_GetDefaults(PyObject *op)

Return value: Borrowed reference.

Retorna los valores predeterminados del argumento del objeto función op. Esto puede ser una tupla de argumentos o NULL.

int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)

Establece los valores predeterminados del argumento para el objeto función op. defaults deben ser Py_None o una tupla.

Lanza SystemError y retorna -1 en caso de error.

PyObject* PyFunction_GetClosure(PyObject *op)

Return value: Borrowed reference.

Retorna el cierre asociado con el objeto función op. Esto puede ser NULL o una tupla de objetos celda.

int PyFunction_SetClosure(PyObject *op, PyObject *closure)

Establece el cierre asociado con el objeto función op. cierre debe ser Py_None o una tupla de objetos celda.

Lanza SystemError y retorna -1 en caso de error.

PyObject *PyFunction_GetAnnotations(PyObject *op)

Return value: Borrowed reference.

Retorna las anotaciones del objeto función op. Este puede ser un diccionario mutable o NULL.

int PyFunction_SetAnnotations(PyObject *op, PyObject *annotations)

Establece las anotaciones para el objeto función op. annotations debe ser un diccionario o Py_None.

Lanza SystemError y retorna -1 en caso de error.

Objetos de método de instancia

Un método de instancia es un contenedor para una PyCFunction y la nueva forma de vincular una PyCFunction a un objeto de clase. Reemplaza la llamada anterior PyMethod_New (func, NULL, class).

PyTypeObject PyInstanceMethod_Type

Esta instancia de PyTypeObject representa el tipo de método de instancia de Python. No está expuesto a los programas de Python.

int PyInstanceMethod_Check(PyObject *o)

Retorna verdadero si o es un objeto de método de instancia (tiene tipo PyInstanceMethod_Type). El parámetro no debe ser NULL. Esta función siempre finaliza con éxito.

PyObject* PyInstanceMethod_New(PyObject *func)

Return value: New reference.

Return a new instance method object, with func being any callable object. func is the function that will be called when the instance method is called.

PyObject* PyInstanceMethod_Function(PyObject *im)

Return value: Borrowed reference.

Retorna el objeto de función asociado con el método de instancia im.

PyObject* PyInstanceMethod_GET_FUNCTION(PyObject *im)

Return value: Borrowed reference.

Versión macro de PyInstanceMethod_Function() que evita la comprobación de errores.

Objetos método

Los métodos son objetos de función enlazados. Los métodos siempre están vinculados a una instancia de una clase definida por el usuario. Los métodos no vinculados (métodos vinculados a un objeto de clase) ya no están disponibles.

PyTypeObject PyMethod_Type

Esta instancia de PyTypeObject representa el tipo de método Python. Esto está expuesto a los programas de Python como types.MethodType.

int PyMethod_Check(PyObject *o)

Retorna verdadero si o es un objeto de método (tiene tipo PyMethod_Type). El parámetro no debe ser NULL. Esta función siempre finaliza con éxito.

PyObject* PyMethod_New(PyObject *func, PyObject *self)

Return value: New reference.

Retorna un nuevo objeto de método, con func como cualquier objeto invocable y self la instancia en la que se debe vincular el método. func es la función que se llamará cuando se llame al método. self no debe ser NULL.

PyObject* PyMethod_Function(PyObject *meth)

Return value: Borrowed reference.

Retorna el objeto de función asociado con el método meth.

PyObject* PyMethod_GET_FUNCTION(PyObject *meth)

Return value: Borrowed reference.

Versión macro de PyMethod_Function() que evita la comprobación de errores.

PyObject* PyMethod_Self(PyObject *meth)

Return value: Borrowed reference.

Retorna la instancia asociada con el método meth.

PyObject* PyMethod_GET_SELF(PyObject *meth)

Return value: Borrowed reference.

Versión macro de PyMethod_Self() que evita la comprobación de errores.

Objetos Celda

Los objetos celda (cell) se utilizan para implementar variables a las que hacen referencia varios ámbitos. Para cada variable, se crea un objeto de celda para almacenar el valor; Las variables locales de cada marco de pila que hace referencia al valor contienen una referencia a las celdas de ámbitos externos que también usan esa variable. Cuando se accede al valor, se utiliza el valor contenido en la celda en lugar del objeto de la celda en sí. Esta desreferenciación del objeto de celda requiere soporte del código de bytes generado; estos no se eliminan automáticamente cuando se accede a ellos. No es probable que los objetos celda sean útiles en otros lugares.

PyCellObject

La estructura C utilizada para objetos celda.

PyTypeObject PyCell_Type

El objeto tipo correspondiente a los objetos celda.

int PyCell_Check(ob)

Retorna verdadero si ob es un objeto de celda; ob no debe ser NULL. Esta función siempre finaliza con éxito.

PyObject* PyCell_New(PyObject *ob)

Return value: New reference.

Crea y retorna un nuevo objeto de celda que contiene el valor ob. El parámetro puede ser NULL.

PyObject* PyCell_Get(PyObject *cell)

Return value: New reference.

Retorna el contenido de la celda cell.

PyObject* PyCell_GET(PyObject *cell)

Return value: Borrowed reference.

Retorna el contenido de la celda cell, pero sin verificar que cell no sea NULL y que sea un objeto de celda.

int PyCell_Set(PyObject *cell, PyObject *value)

Establece el contenido del objeto de celda cell con el valor value. Esto libera la referencia a cualquier contenido actual de la celda. value puede ser NULL. cell no debe ser NULL; Si no es un objeto de celda, se retornará -1. En caso de éxito, se retornará 0.

void PyCell_SET(PyObject *cell, PyObject *value)

Establece el valor del objeto de celda cell en el valor value. No se ajustan los recuentos de referencia y no se realizan verificaciones de seguridad; cell no debe ser NULL y debe ser un objeto de celda.

Objetos Código

Los objetos código son un detalle de bajo nivel de la implementación de CPython. Cada uno representa un fragmento de código ejecutable que aún no se ha vinculado a una función.

PyCodeObject

La estructura en C de los objetos utilizados para describir objetos código. Los campos de este tipo están sujetos a cambios en cualquier momento.

PyTypeObject PyCode_Type

Esta es una instancia de PyTypeObject que representa el tipo Python code.

int PyCode_Check(PyObject *co)

Retorna verdadero si co es un objeto code. Esta función siempre finaliza con éxito.

int PyCode_GetNumFree(PyCodeObject *co)

Retorna el número de variables libres en co.

PyCodeObject* PyCode_New(int argcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, int firstlineno, PyObject *lnotab)

Return value: New reference.

Retorna un nuevo objeto de código. Si necesita un objeto de código ficticio para crear un marco (frame), use PyCode_NewEmpty() en su lugar. Llamando PyCode_New() directamente puede enlazarlo a una versión precisa de Python ya que la definición del código de bytes cambia a menudo.

PyCodeObject* PyCode_NewWithPosOnlyArgs(int argcount, int posonlyargcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, int firstlineno, PyObject *lnotab)

Return value: New reference.

Similar a PyCode_New(), pero con un «posonlyargcount» adicional para argumentos solo posicionales.

Nuevo en la versión 3.8.

PyCodeObject* PyCode_NewEmpty(const char *filename, const char *funcname, int firstlineno)

Return value: New reference.

Retorna un nuevo objeto de código vacío con el nombre de archivo especificado, el nombre de la función y el número de la primera línea. Es ilegal utilizar exec() o eval() en el objeto de código resultante.

Objetos archivo

Estas API son una emulación mínima de la API Python 2 en C para objetos de archivo incorporados, que solía depender del soporte de E/S (I/O) almacenadas en la memoria intermedia (FILE*) de la biblioteca estándar C. En Python 3, los archivos y las secuencias utilizan el nuevo módulo io, que define varias capas sobre las E/S sin búfer de bajo nivel del sistema operativo. Las funciones que se describen a continuación son envoltorios en C de conveniencia sobre estas nuevas API y están destinadas principalmente a la notificación de errores internos en el intérprete; se recomienda que el código de terceros acceda a las API io.

PyObject* PyFile_FromFd(int fd, const char *name, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd)

Return value: New reference.

Crea un objeto archivo Python a partir del descriptor de archivo de un archivo ya abierto fd. Los argumentos name, encoding, errors y newline pueden ser NULL para usar los valores predeterminados; buffering puede ser -1 para usar el valor predeterminado. name se ignora y se mantiene por compatibilidad con versiones anteriores. Retorna NULL en caso de error. Para obtener una descripción más completa de los argumentos, consulte la documentación de la función io.open().

Advertencia

Dado que las transmisiones (streams) de Python tienen su propia capa de almacenamiento en búfer, combinarlas con descriptores de archivos a nivel del sistema operativo puede producir varios problemas (como un pedido inesperado de datos).

Distinto en la versión 3.2: Ignora el atributo name.

int PyObject_AsFileDescriptor(PyObject *p)

Retorna el descriptor de archivo asociado con p como int. Si el objeto es un entero, se retorna su valor. Si no, se llama al método fileno() del objeto si existe; el método debe retornar un número entero, que se retorna como el valor del descriptor de archivo. Establece una excepción y retorna -1 en caso de error.

PyObject* PyFile_GetLine(PyObject *p, int n)

Return value: New reference.

Equivalente a p.readline([n]), esta función lee una línea del objeto p. p puede ser un objeto archivo o cualquier objeto con un método readline(). Si n es 0, se lee exactamente una línea, independientemente de la longitud de la línea. Si n es mayor que 0, no se leerán más de n bytes del archivo; se puede retornar una línea parcial. En ambos casos, se retorna una cadena de caracteres vacía si se llega al final del archivo de inmediato. Si n es menor que 0, sin embargo, se lee una línea independientemente de la longitud, pero EOFError se lanza si se llega al final del archivo de inmediato.

int PyFile_SetOpenCodeHook(Py_OpenCodeHookFunction handler)

Sobrescribe el comportamiento normal de io.open_code() para pasar su parámetro a través del controlador proporcionado.

El controlador es una función de tipo PyObject *(*)(PyObject *path, void *userData), donde se garantiza que path sea PyUnicodeObject.

El puntero userData se pasa a la función de enlace. Dado que las funciones de enlace pueden llamarse desde diferentes tiempos de ejecución, este puntero no debe referirse directamente al estado de Python.

Como este hook se usa intencionalmente durante la importación, evite importar nuevos módulos durante su ejecución a menos que se sepa que están congelados o disponibles en sys.modules.

Una vez que se ha establecido un hook, no se puede quitar ni reemplazar, y luego llamadas a PyFile_SetOpenCodeHook() fallarán. En caso de error, la función retorna -1 y establece una excepción si el intérprete se ha inicializado.

Es seguro llamar a esta función antes de Py_Initialize().

Genera un evento de auditoría setopencodehook sin argumentos.

Nuevo en la versión 3.8.

int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)

Escribe el objecto obj en el objeto archivo p. El único indicador admitido para flags es Py_PRINT_RAW; si se proporciona, se escribe el str() del objeto en lugar de repr(). Retorna 0 en caso de éxito o -1 en caso de error; se establecerá la excepción apropiada.

int PyFile_WriteString(const char *s, PyObject *p)

Escribe la cadena s en el objeto archivo p. Retorna 0 en caso de éxito o -1 en caso de error; se establecerá la excepción apropiada.

Objectos Modulo

PyTypeObject PyModule_Type

Esta instancia de PyTypeObject representa el tipo de módulo Python. Esto está expuesto a los programas de Python como types.ModuleType.

int PyModule_Check(PyObject *p)

Retorna verdadero si p es un objeto de módulo o un subtipo de un objeto de módulo. Esta función siempre finaliza con éxito.

int PyModule_CheckExact(PyObject *p)

Retorna verdadero si p es un objeto módulo, pero no un subtipo de PyModule_Type. Esta función siempre finaliza con éxito.

PyObject* PyModule_NewObject(PyObject *name)

Return value: New reference.

Retorna un nuevo objeto módulo con el atributo __name__ establecido en name. Los atributos del módulo __name__, __doc__, __package__, y __loader__ se completan (todos menos __name__ están configurados en None); quien llama es responsable de proporcionar un atributo __file__.

Nuevo en la versión 3.3.

Distinto en la versión 3.4: __package__ y __loader__ están configurados en None.

PyObject* PyModule_New(const char *name)

Return value: New reference.

Similar a PyModule_NewObject(), pero el nombre es una cadena de caracteres codificada UTF-8 en lugar de un objeto Unicode.

PyObject* PyModule_GetDict(PyObject *module)

Return value: Borrowed reference.

Retorna el objeto del diccionario que implementa el espacio de nombres de module; este objeto es el mismo que el atributo __dict__ del objeto módulo. Si module no es un objeto módulo (o un subtipo de un objeto de módulo), SystemError se genera y se retorna NULL.

Se recomienda que las extensiones utilicen otras funciones PyModule_*() y PyObject_*() en lugar de manipular directamente el módulo __dict__.

PyObject* PyModule_GetNameObject(PyObject *module)

Return value: New reference.

Retorna el valor __name__ del module. Si el módulo no proporciona uno, o si no es una cadena de caracteres, SystemError se lanza y se retorna NULL.

Nuevo en la versión 3.3.

const char* PyModule_GetName(PyObject *module)

Similar a PyModule_GetNameObject() pero retorna el nombre codificado a 'utf-8'.

void* PyModule_GetState(PyObject *module)

Retorna el «estado» del módulo, es decir, un puntero al bloque de memoria asignado en el momento de la creación del módulo, o NULL. Ver PyModuleDef.m_size.

PyModuleDef* PyModule_GetDef(PyObject *module)

Retorna un puntero a la estructura PyModuleDef a partir de la cual se creó el módulo, o NULL si el módulo no se creó a partir de una definición.

PyObject* PyModule_GetFilenameObject(PyObject *module)

Return value: New reference.

Retorna el nombre del archivo desde el cual module se cargó utilizando el atributo __file__ del module. Si esto no está definido, o si no es una cadena de caracteres unicode, lanza SystemError y retornar NULL; de lo contrario, retorna una referencia a un objeto Unicode.

Nuevo en la versión 3.2.

const char* PyModule_GetFilename(PyObject *module)

Similar a PyModule_GetFilenameObject() pero retorna el nombre de archivo codificado a “utf-8”.

Obsoleto desde la versión 3.2: PyModule_GetFilename() lanza UnicodeEncodeError en nombres de archivo no codificables, use PyModule_GetFilenameObject() en su lugar.

Inicializando módulos en C

Los objetos módulos generalmente se crean a partir de módulos de extensión (bibliotecas compartidas que exportan una función de inicialización) o módulos compilados (donde la función de inicialización se agrega usando PyImport_AppendInittab()). Consulte Construyendo Extensiones C y C++ o Extendiendo Python Incrustado para más detalles.

La función de inicialización puede pasar una instancia de definición de módulo a PyModule_Create(), y retornar el objeto módulo resultante, o solicitar una «inicialización de múltiples fases» retornando la estructura de definición.

PyModuleDef

La estructura de definición de módulo, que contiene toda la información necesaria para crear un objeto módulo. Por lo general, solo hay una variable estáticamente inicializada de este tipo para cada módulo.

PyModuleDef_Base m_base

Siempre inicialice este miembro a PyModuleDef_HEAD_INIT.

const char *m_name

Nombre para el nuevo módulo.

const char *m_doc

Docstring para el módulo; por lo general, se usa una variable docstring creada con PyDoc_STRVAR.

Py_ssize_t m_size

El estado del módulo se puede mantener en un área de memoria por módulo que se puede recuperar con PyModule_GetState(), en lugar de en globales estáticos. Esto hace que los módulos sean seguros para su uso en múltiples sub-interpretadores.

Esta área de memoria se asigna en base a m_size en la creación del módulo, y se libera cuando el objeto del módulo se desasigna, después de que se haya llamado a la función m_free, si está presente.

Establecer m_size en -1 significa que el módulo no admite sub-interpretadores, porque tiene un estado global.

Establecerlo en un valor no negativo significa que el módulo se puede reinicializar y especifica la cantidad adicional de memoria que requiere para su estado. Se requiere m_size no negativo para la inicialización de múltiples fases.

Ver PEP 3121 [https://www.python.org/dev/peps/pep-3121] para más detalles.

PyMethodDef* m_methods

Un puntero a una tabla de funciones de nivel de módulo, descrito por valores PyMethodDef. Puede ser NULL si no hay funciones presentes.

PyModuleDef_Slot* m_slots

Un conjunto de definiciones de ranura para la inicialización de múltiples fases, terminadas por una entrada {0, NULL}. Cuando se utiliza la inicialización monofásica, m_slots debe ser NULL.

Distinto en la versión 3.5: Antes de la versión 3.5, este miembro siempre estaba configurado en NULL y se definía como:

inquiry m_reload

traverseproc m_traverse

Una función transversal para llamar durante el recorrido GC del objeto del módulo, o NULL si no es necesario.

Esta función no se llama si se solicitó el estado del módulo pero aún no se asignó. Este es el caso inmediatamente después de que se crea el módulo y antes de que se ejecute (la función Py_mod_exec). Más precisamente, esta función no se llama si m_size es mayor que 0 y el estado del módulo (como lo retorna PyModule_GetState()) es NULL.

Distinto en la versión 3.9: Ya no se llama antes de que se asigne el estado del módulo.

inquiry m_clear

Una función clara para llamar durante la limpieza GC del objeto del módulo, o NULL si no es necesario.

Esta función no se llama si se solicitó el estado del módulo pero aún no se asignó. Este es el caso inmediatamente después de que se crea el módulo y antes de que se ejecute (la función Py_mod_exec). Más precisamente, esta función no se llama si m_size es mayor que 0 y el estado del módulo (como lo retorna PyModule_GetState()) es NULL.

Like PyTypeObject.tp_clear, this function is not always called before a module is deallocated. For example, when reference counting is enough to determine that an object is no longer used, the cyclic garbage collector is not involved and m_free is called directly.

Distinto en la versión 3.9: Ya no se llama antes de que se asigne el estado del módulo.

freefunc m_free

Una función para llamar durante la desasignación del objeto del módulo, o NULL si no es necesario.

Esta función no se llama si se solicitó el estado del módulo pero aún no se asignó. Este es el caso inmediatamente después de que se crea el módulo y antes de que se ejecute (la función Py_mod_exec). Más precisamente, esta función no se llama si m_size es mayor que 0 y el estado del módulo (como lo retorna PyModule_GetState()) es NULL.

Distinto en la versión 3.9: Ya no se llama antes de que se asigne el estado del módulo.

Inicialización monofásica

La función de inicialización del módulo puede crear y retornar el objeto módulo directamente. Esto se conoce como «inicialización monofásica» y utiliza una de las siguientes funciones de creación de dos módulos:

PyObject* PyModule_Create(PyModuleDef *def)

Return value: New reference.

Crea un nuevo objeto módulo, dada la definición en def. Esto se comporta como PyModule_Create2() con module_api_version establecido en PYTHON_API_VERSION.

PyObject* PyModule_Create2(PyModuleDef *def, int module_api_version)

Return value: New reference.

Crea un nuevo objeto de módulo, dada la definición en def, asumiendo la versión de API module_api_version. Si esa versión no coincide con la versión del intérprete en ejecución, se emite un RuntimeWarning.

Nota

La mayoría de los usos de esta función deberían usar PyModule_Create() en su lugar; solo use esto si está seguro de que lo necesita.

Antes de que se retorne desde la función de inicialización, el objeto del módulo resultante normalmente se llena utilizando funciones como PyModule_AddObject().

Inicialización multifase

Una forma alternativa de especificar extensiones es solicitar una «inicialización de múltiples fases». Los módulos de extensión creados de esta manera se comportan más como los módulos de Python: la inicialización se divide entre la fase de creación (creation phase), cuando se crea el objeto módulo, y la fase de ejecución (execution phase), cuando se llena. La distinción es similar a los métodos de clases __new__() y __init__().

A diferencia de los módulos creados con la inicialización monofásica, estos módulos no son singletons: si se elimina la entrada sys.modules y el módulo se vuelve a importar, se crea un nuevo objeto módulo y el módulo anterior está sujeto a la recolección normal de basura – Al igual que con los módulos de Python. Por defecto, los módulos múltiples creados a partir de la misma definición deberían ser independientes: los cambios en uno no deberían afectar a los demás. Esto significa que todo el estado debe ser específico para el objeto del módulo (usando, por ejemplo, usando PyModule_GetState()), o su contenido (como el módulo __dict__ o clases individuales creadas con PyType_FromSpec()).

Se espera que todos los módulos creados mediante la inicialización de múltiples fases admitan sub-interpretadores. Asegurándose de que varios módulos sean independientes suele ser suficiente para lograr esto.

Para solicitar la inicialización de múltiples fases, la función de inicialización (PyInit_modulename) retorna una instancia de PyModuleDef con un m_slots no vacío. Antes de que se retorna, la instancia PyModuleDef debe inicializarse con la siguiente función:

PyObject* PyModuleDef_Init(PyModuleDef *def)

Return value: Borrowed reference.

Asegura que la definición de un módulo sea un objeto Python correctamente inicializado que informe correctamente su tipo y conteo de referencias.

Retorna def convertido a PyObject* o NULL si se produjo un error.

Nuevo en la versión 3.5.

El miembro m_slots de la definición del módulo debe apuntar a un arreglo de estructuras PyModuleDef_Slot:

PyModuleDef_Slot

int slot

Una ranura ID, elegida entre los valores disponibles que se explican a continuación.

void* value

Valor de la ranura, cuyo significado depende de la ID de la ranura.

Nuevo en la versión 3.5.

El arreglo m_slots debe estar terminada por una ranura con id 0.

Los tipos de ranura disponibles son:

Py_mod_create

Especifica una función que se llama para crear el objeto del módulo en sí. El puntero value de este espacio debe apuntar a una función de la firma:

PyObject* create_module(PyObject *spec, PyModuleDef *def)

La función recibe una instancia de ModuleSpec, como se define en PEP 451 [https://www.python.org/dev/peps/pep-0451], y la definición del módulo. Debería retornar un nuevo objeto de módulo, o establecer un error y retornar NULL.

Esta función debe mantenerse mínima. En particular, no debería llamar a código arbitrario de Python, ya que intentar importar el mismo módulo nuevamente puede dar como resultado un bucle infinito.

Múltiples ranuras Py_mod_create no pueden especificarse en una definición de módulo.

Si no se especifica Py_mod_create, la maquinaria de importación creará un objeto de módulo normal usando PyModule_New(). El nombre se toma de spec, no de la definición, para permitir que los módulos de extensión se ajusten dinámicamente a su lugar en la jerarquía de módulos y se importen bajo diferentes nombres a través de enlaces simbólicos, todo mientras se comparte una definición de módulo único.

No es necesario que el objeto retornado sea una instancia de PyModule_Type. Se puede usar cualquier tipo, siempre que admita la configuración y la obtención de atributos relacionados con la importación. Sin embargo, solo se pueden retornar instancias PyModule_Type si el PyModuleDef no tiene NULL m_traverse, m_clear, m_free; m_size distinto de cero; o ranuras que no sean Py_mod_create.

Py_mod_exec

Especifica una función que se llama para ejecutar (execute) el módulo. Esto es equivalente a ejecutar el código de un módulo Python: por lo general, esta función agrega clases y constantes al módulo. La firma de la función es:

int exec_module(PyObject* module)

Si se especifican varias ranuras Py_mod_exec, se procesan en el orden en que aparecen en el arreglo m_slots.

Ver PEP 489 [https://www.python.org/dev/peps/pep-0489] para más detalles sobre la inicialización de múltiples fases.

Funciones de creación de módulos de bajo nivel

Las siguientes funciones se invocan en segundo plano cuando se utiliza la inicialización de múltiples fases. Se pueden usar directamente, por ejemplo, al crear objetos de módulo de forma dinámica. Tenga en cuenta que tanto PyModule_FromDefAndSpec como PyModule_ExecDef deben llamarse para inicializar completamente un módulo.

PyObject * PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)

Return value: New reference.

Cree un nuevo objeto módulo, dada la definición en module y ModuleSpec spec. Esto se comporta como PyModule_FromDefAndSpec2() con module_api_version establecido en PYTHON_API_VERSION.

Nuevo en la versión 3.5.

PyObject * PyModule_FromDefAndSpec2(PyModuleDef *def, PyObject *spec, int module_api_version)

Return value: New reference.

Cree un nuevo objeto módulo, dada la definición en module y ModuleSpec spec, asumiendo la versión de API module_api_version. Si esa versión no coincide con la versión del intérprete en ejecución, se emite un RuntimeWarning.

Nota

La mayoría de los usos de esta función deberían usar PyModule_FromDefAndSpec() en su lugar; solo use esto si está seguro de que lo necesita.

Nuevo en la versión 3.5.

int PyModule_ExecDef(PyObject *module, PyModuleDef *def)

Procesa cualquier ranura de ejecución (Py_mod_exec) dado en def.

Nuevo en la versión 3.5.

int PyModule_SetDocString(PyObject *module, const char *docstring)

Establece la cadena de caracteres de documentación para module en docstring. Esta función se llama automáticamente cuando se crea un módulo desde PyModuleDef, usando PyModule_Create o PyModule_FromDefAndSpec.

Nuevo en la versión 3.5.

int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)

Agrega las funciones del arreglo functions terminadas en NULL a module. Consulte la documentación de PyMethodDef para obtener detalles sobre entradas individuales (debido a la falta de un espacio de nombres de módulo compartido, las «funciones» de nivel de módulo implementadas en C generalmente reciben el módulo como su primer parámetro, haciéndolos similares a la instancia métodos en clases de Python). Esta función se llama automáticamente cuando se crea un módulo desde PyModuleDef, usando PyModule_Create o PyModule_FromDefAndSpec.

Nuevo en la versión 3.5.

Funciones de soporte

La función de inicialización del módulo (si usa la inicialización de fase única) o una función llamada desde un intervalo de ejecución del módulo (si usa la inicialización de múltiples fases), puede usar las siguientes funciones para ayudar a inicializar el estado del módulo:

int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)

Agrega un objeto a module como name. Esta es una función conveniente que se puede utilizar desde la función de inicialización del módulo. Esto roba una referencia al value en caso de éxito. Retorna -1 en caso de error, 0 en caso de éxito.

Nota

A diferencia de otras funciones que roban referencias, PyModule_AddObject() solo disminuye el conteo de referencias de value en caso de éxito.

Esto significa que su valor de retorno debe ser verificado, y el código de llamada debe Py_DECREF() value manualmente en caso de error. Ejemplo de uso:

Py_INCREF(spam);
if (PyModule_AddObject(module, "spam", spam) < 0) {
    Py_DECREF(module);
    Py_DECREF(spam);
    return NULL;
}

int PyModule_AddIntConstant(PyObject *module, const char *name, long value)

Agrega una constante entera a module como name. Esta función de conveniencia se puede usar desde la función de inicialización del módulo. Retorna -1 en caso de error, 0 en caso de éxito.

int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)

Agrega una constante de cadena a module como name. Esta función de conveniencia se puede usar desde la función de inicialización del módulo. La cadena de caracteres value debe estar terminada en NULL. Retorna -1 en caso de error, 0 en caso de éxito.

int PyModule_AddIntMacro(PyObject *module, macro)

Agrega una constante int a module. El nombre y el valor se toman de macro. Por ejemplo, PyModule_AddIntMacro(module, AF_INET) agrega la constante int AF_INET con el valor de AF_INET a module. Retorna -1 en caso de error, 0 en caso de éxito.

int PyModule_AddStringMacro(PyObject *module, macro)

Agrega una constante de cadena de caracteres a module.

int PyModule_AddType(PyObject *module, PyTypeObject *type)

Agrega un objeto tipo a module. El objeto tipo se finaliza llamando internamente PyType_Ready(). El nombre del objeto tipo se toma del último componente de tp_name después del punto. Retorna -1 en caso de error, 0 en caso de éxito.

Nuevo en la versión 3.9.

Búsqueda de módulos

La inicialización monofásica crea módulos singleton que se pueden buscar en el contexto del intérprete actual. Esto permite que el objeto módulo se recupere más tarde con solo una referencia a la definición del módulo.

Estas funciones no funcionarán en módulos creados mediante la inicialización de múltiples fases, ya que se pueden crear múltiples módulos de este tipo desde una sola definición.

PyObject* PyState_FindModule(PyModuleDef *def)

Return value: Borrowed reference.

Retorna el objeto módulo que se creó a partir de def para el intérprete actual. Este método requiere que el objeto módulo se haya adjuntado al estado del intérprete con PyState_AddModule() de antemano. En caso de que el objeto módulo correspondiente no se encuentre o no se haya adjuntado al estado del intérprete, retornará NULL.

int PyState_AddModule(PyObject *module, PyModuleDef *def)

Adjunta el objeto del módulo pasado a la función al estado del intérprete. Esto permite que se pueda acceder al objeto del módulo a través de PyState_FindModule().

Solo es efectivo en módulos creados con la inicialización monofásica.

Python llama a PyState_AddModule automáticamente después de importar un módulo, por lo que es innecesario (pero inofensivo) llamarlo desde el código de inicialización del módulo. Solo se necesita una llamada explícita si el propio código de inicio del módulo llama posteriormente PyState_FindModule. La función está destinada principalmente a implementar mecanismos de importación alternativos (ya sea llamándolo directamente o refiriéndose a su implementación para obtener detalles de las actualizaciones de estado requeridas).

La persona que llama debe retener el GIL.

Retorna 0 en caso de éxito o -1 en caso de error.

Nuevo en la versión 3.3.

int PyState_RemoveModule(PyModuleDef *def)

Elimina el objeto del módulo creado a partir de def del estado del intérprete. Retorna 0 en caso de éxito o -1 en caso de error.

La persona que llama debe retener el GIL.

Nuevo en la versión 3.3.

Objetos iteradores

Python proporciona dos objetos iteradores de propósito general. El primero, un iterador de secuencia, funciona con una secuencia arbitraria que admite el método __getitem__(). El segundo funciona con un objeto invocable y un valor centinela, llamando al invocable para cada elemento de la secuencia y finalizando la iteración cuando se retorna el valor centinela.

PyTypeObject PySeqIter_Type

Objeto tipo para objetos iteradores retornados por PySeqIter_New() y la forma de un argumento de la función incorporada iter() para los tipos de secuencia incorporados.

int PySeqIter_Check(op)

Retorna verdadero si el tipo de op es PySeqIter_Type. Esta función siempre finaliza con éxito.

PyObject* PySeqIter_New(PyObject *seq)

Return value: New reference.

Retorna un iterador que funciona con un objeto de secuencia general, seq. La iteración termina cuando la secuencia lanza IndexError para la operación de suscripción.

PyTypeObject PyCallIter_Type

Objeto tipo para los objetos iteradores retornados por PyCallIter_New() y la forma de dos argumentos de la función incorporada iter().

int PyCallIter_Check(op)

Retorna verdadero si el tipo de op es PyCallIter_Type. Esta función siempre finaliza con éxito.

PyObject* PyCallIter_New(PyObject *callable, PyObject *sentinel)

Return value: New reference.

Retorna un nuevo iterador. El primer parámetro, callable, puede ser cualquier objeto invocable de Python que se pueda invocar sin parámetros; cada llamada debe retornar el siguiente elemento en la iteración. Cuando callable retorna un valor igual a sentinel, la iteración finalizará.

Objetos descriptores

Los «descriptores» son objetos que describen algún atributo de un objeto. Se encuentran en el diccionario de objetos tipo.

PyTypeObject PyProperty_Type

El objeto de tipo para los tipos de descriptor incorporado.

PyObject* PyDescr_NewGetSet(PyTypeObject *type, struct PyGetSetDef *getset)

Return value: New reference.

PyObject* PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *meth)

Return value: New reference.

PyObject* PyDescr_NewMethod(PyTypeObject *type, struct PyMethodDef *meth)

Return value: New reference.

PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped)

Return value: New reference.

PyObject* PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method)

Return value: New reference.

int PyDescr_IsData(PyObject *descr)

Retorna verdadero si el descriptor objetos descr describe un atributo de datos, o falso si describe un método. descr debe ser un objeto descriptor; No hay comprobación de errores.

PyObject* PyWrapper_New(PyObject *, PyObject *)

Return value: New reference.

Objeto rebanada (slice)

PyTypeObject PySlice_Type

El objeto tipo para objetos rebanadas. Esto es lo mismo que slice en la capa de Python.

int PySlice_Check(PyObject *ob)

Retorna verdadero si ob es un objeto rebanada; ob no debe ser NULL. Esta función siempre finaliza con éxito.

PyObject* PySlice_New(PyObject *start, PyObject *stop, PyObject *step)

Return value: New reference.

Retorna un nuevo objeto rebanada con los valores dados. Los parámetros start, stop y step se utilizan como los valores de los atributos del objeto rebanada de los mismos nombres. Cualquiera de los valores puede ser NULL, en cuyo caso se usará None para el atributo correspondiente. Retorna NULL si no se puedo asignar el nuevo objeto.

int PySlice_GetIndices(PyObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step)

Recupera los índices start, stop y step del objeto rebanada slice, suponiendo una secuencia de longitud length. Trata los índices mayores que length como errores.

Retorna 0 en caso de éxito y -1 en caso de error sin excepción establecida (a menos que uno de los índices no sea None y no se haya convertido a un entero, en cuyo caso``- 1`` se retorna con una excepción establecida).

Probablemente no quiera usar esta función.

Distinto en la versión 3.2: El tipo de parámetro para el parámetro slice era PySliceObject* antes.

int PySlice_GetIndicesEx(PyObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step, Py_ssize_t *slicelength)

Reemplazo utilizable para PySlice_GetIndices(). Recupera los índices de start, stop, y step del objeto rebanada slice asumiendo una secuencia de longitud length, y almacena la longitud de la rebanada en slicelength. Los índices fuera de los límites se recortan de manera coherente con el manejo de sectores normales.

Retorna 0 en caso de éxito y -1 en caso de error con excepción establecida.

Nota

Esta función se considera no segura para secuencias redimensionables. Su invocación debe ser reemplazada por una combinación de PySlice_Unpack() y PySlice_AdjustIndices() donde:

if (PySlice_GetIndicesEx(slice, length, &start, &stop, &step, &slicelength) < 0) {
    // return error
}

es reemplazado por:

if (PySlice_Unpack(slice, &start, &stop, &step) < 0) {
    // return error
}
slicelength = PySlice_AdjustIndices(length, &start, &stop, step);

Distinto en la versión 3.2: El tipo de parámetro para el parámetro slice era PySliceObject* antes.

Distinto en la versión 3.6.1: Si Py_LIMITED_API no se establece o establece el valor entre 0x03050400 y 0x03060000 (sin incluir) o 0x03060100 o un superior PySlice_GetIndicesEx() se implementa como un macro usando PySlice_Unpack() y PySlice_AdjustIndices(). Los argumentos start, stop y step se evalúan más de una vez.

Obsoleto desde la versión 3.6.1: Si Py_LIMITED_API se establece en un valor menor que 0x03050400 o entre 0x03060000 y 0x03060100 (sin incluir) PySlice_GetIndicesEx() es una función obsoleta.

int PySlice_Unpack(PyObject *slice, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step)

Extrae los miembros de datos start, stop, y step de un objeto rebanada como enteros en C. Reduce silenciosamente los valores mayores que PY_SSIZE_T_MAX a PY_SSIZE_T_MAX, aumenta silenciosamente los valores start y stop inferiores a PY_SSIZE_T_MIN a PY_SSIZE_T_MIN, y silenciosamente aumenta los valores de step a menos de -PY_SSE `` a ``-PY_SSIZE_T_MAX.

Retorna -1 en caso de error, 0 en caso de éxito.

Nuevo en la versión 3.6.1.

Py_ssize_t PySlice_AdjustIndices(Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t step)

Ajusta los índices de corte de inicio/fin asumiendo una secuencia de la longitud especificada. Los índices fuera de los límites se recortan de manera coherente con el manejo de sectores normales.

Retorna la longitud de la rebanada. Siempre exitoso. No llama al código de Python.

Nuevo en la versión 3.6.1.

Objeto Elipsis

PyObject *Py_Ellipsis

El objeto Elipsis de Python. Este objeto no tiene métodos. Debe tratarse como cualquier otro objeto con respecto a los recuentos de referencia. Como Py_None es un objeto singleton.

Objetos de vista de memoria (MemoryView)

Un objeto memoryview expone la interfaz de búfer a nivel de C como un objeto Python que luego puede pasarse como cualquier otro objeto.

PyObject *PyMemoryView_FromObject(PyObject *obj)

Return value: New reference.

Crea un objeto de vista de memoria memoryview a partir de un objeto que proporciona la interfaz del búfer. Si obj admite exportaciones de búfer de escritura, el objeto de vista de memoria será de lectura/escritura, de lo contrario puede ser de solo lectura o de lectura/escritura a discreción del exportador.

PyObject *PyMemoryView_FromMemory(char *mem, Py_ssize_t size, int flags)

Return value: New reference.

Crea un objeto de vista de memoria usando mem como el búfer subyacente. flags pueden ser uno de PyBUF_READ o PyBUF_WRITE.

Nuevo en la versión 3.3.

PyObject *PyMemoryView_FromBuffer(Py_buffer *view)

Return value: New reference.

Crea un objeto de vista de memoria que ajuste la estructura de búfer dada view. Para memorias intermedias de bytes simples, PyMemoryView_FromMemory() es la función preferida.

PyObject *PyMemoryView_GetContiguous(PyObject *obj, int buffertype, char order)

Return value: New reference.

Crea un objeto de vista de memoria memoryview para un fragmento de memoria contiguo (contiguous, en order “C” o “F” de Fortran) desde un objeto que define la interfaz del búfer. Si la memoria es contigua, el objeto de vista de memoria apunta a la memoria original. De lo contrario, se realiza una copia y la vista de memoria apunta a un nuevo objeto de bytes.

int PyMemoryView_Check(PyObject *obj)

Retorna verdadero si el objeto obj es un objeto de vista de memoria. Actualmente no está permitido crear subclases de memoryview. Esta función siempre finaliza con éxito.

Py_buffer *PyMemoryView_GET_BUFFER(PyObject *mview)

Retorna un puntero a la copia privada de la vista de memoria del búfer del exportador. mview debe ser una instancia de memoryview; este macro no verifica su tipo, debe hacerlo usted mismo o correrá el riesgo de fallas.

Py_buffer *PyMemoryView_GET_BASE(PyObject *mview)

Retorna un puntero al objeto de exportación en el que se basa la vista de memoria o NULL si la vista de memoria ha sido creada por una de las funciones PyMemoryView_FromMemory() o PyMemoryView_FromBuffer(). mview debe ser una instancia de memoryview.

Objetos de referencia débil

Python soporta referencias débiles como objetos de primera clase. Hay dos tipos de objetos específicos que implementan directamente referencias débiles. El primero es un objeto con referencia simple, y el segundo actúa como un proxy del objeto original tanto como pueda.

int PyWeakref_Check(ob)

Retorna verdadero (true) si ob es una referencia o un objeto proxy. Esta función siempre finaliza con éxito.

int PyWeakref_CheckRef(ob)

Retorna verdadero (true) si ob es un objeto de referencia. Esta función siempre finaliza con éxito.

int PyWeakref_CheckProxy(ob)

Retorna verdadero (true) si ob es un objeto proxy. Esta función siempre finaliza con éxito.

PyObject* PyWeakref_NewRef(PyObject *ob, PyObject *callback)

Return value: New reference.

Retorna un objeto de referencia débil para el objeto ob. Esto siempre retornará una nueva referencia, pero no garantiza la creación de un objeto nuevo; un objeto de referencia ya existente puede ser retornado. El segundo parámetro, callback, puede ser un objeto invocable que recibe una notificación cuando ob es recolectado como basura; debe aceptar un solo parámetro, el cual será el mismo objeto de referencia débil. callback también puede ser None o NULL. Si ob no es un objeto que puede ser referido de forma débil, o si callback no es invocable, None, o NULL, esto retornará NULL y causará un TypeError.

PyObject* PyWeakref_NewProxy(PyObject *ob, PyObject *callback)

Return value: New reference.

Retorna un objeto proxy de referencia débil para el objeto ob. Esto siempre retornará una nueva referencia, pero no garantiza la creación de un objeto nuevo; un objeto proxy de referencia ya existente puede ser retornado. El segundo parámetro, callback, puede ser un objeto invocable que recibe una notificación cuando ob es recolectado como basura; debe aceptar un solo parámetro, el cual será el mismo objeto de referencia débil. callback también puede ser None o NULL. Si ob no es un objeto que puede ser referido de forma débil, o si callback no es invocable, None, o NULL, esto retornará NULL y causará un TypeError.

PyObject* PyWeakref_GetObject(PyObject *ref)

Return value: Borrowed reference.

Retorna el objeto referenciado desde una referencia débil, ref. Si el referente no está vivo, retornará Py_None.

Nota

Esta función retorna una referencia prestada al objeto referenciado. Esto significa que siempre debes llamar Py_INCREF() en el objeto excepto si sabes que no puede ser destruido mientras lo estés usando.

PyObject* PyWeakref_GET_OBJECT(PyObject *ref)

Return value: Borrowed reference.

Similar a PyWeakref_GetObject(), pero implementado como un macro que no verifica errores.

Cápsulas

Consulta Proporcionar una API C para un módulo de extensión para obtener más información sobre el uso de estos objetos.

Nuevo en la versión 3.1.

PyCapsule

Este subtipo de PyObject representa un valor opaco, útil para los módulos de extensión C que necesitan pasar un valor opaco (como un puntero void*) a través del código Python a otro código C . A menudo se usa para hacer que un puntero de función C definido en un módulo esté disponible para otros módulos, por lo que el mecanismo de importación regular se puede usar para acceder a las API C definidas en módulos cargados dinámicamente.

PyCapsule_Destructor

El tipo de devolución de llamada de un destructor para una cápsula. Definido como:

typedef void (*PyCapsule_Destructor)(PyObject *);

Consulte PyCapsule_New() para conocer la semántica de las devoluciones de llamada de PyCapsule_Destructor.

int PyCapsule_CheckExact(PyObject *p)

Retorna verdadero si su argumento es a PyCapsule. Esta función siempre finaliza con éxito.

PyObject* PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)

Return value: New reference.

Crea un PyCapsule encapsulando el pointer. El argumento pointer puede no ser NULL.

En caso de falla, establece una excepción y retorna NULL.

La cadena de caracteres name puede ser NULL o un puntero a una cadena C válida. Si no es NULL, esta cadena de caracteres debe sobrevivir a la cápsula. (Aunque está permitido liberarlo dentro del destructor).

Si el argumento destructor no es NULL, se llamará con la cápsula como argumento cuando se destruya.

Si esta cápsula se almacenará como un atributo de un módulo, el nombre name debe especificarse como modulename.attributename. Esto permitirá que otros módulos importen la cápsula usando PyCapsule_Import().

void* PyCapsule_GetPointer(PyObject *capsule, const char *name)

Recupera el pointer almacenado en la cápsula. En caso de falla, establece una excepción y retorna NULL.

El parámetro name debe compararse exactamente con el nombre almacenado en la cápsula. Si el nombre almacenado en la cápsula es NULL, el name pasado también debe ser NULL. Python usa la función C strcmp() para comparar nombres de cápsulas.

PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)

Retorna el destructor actual almacenado en la cápsula. En caso de falla, establece una excepción y retorna NULL.

Es legal que una cápsula tenga un destructor NULL. Esto hace que un código de retorno NULL sea algo ambiguo; use PyCapsule_IsValid() o PyErr_Occurred() para desambiguar.

void* PyCapsule_GetContext(PyObject *capsule)

Retorna el contexto actual almacenado en la cápsula. En caso de falla, establece una excepción y retorna NULL.

Es legal que una cápsula tenga un contexto NULL. Esto hace que un código de retorno NULL sea algo ambiguo; use PyCapsule_IsValid() o PyErr_Occurred() para desambiguar.

const char* PyCapsule_GetName(PyObject *capsule)

Retorna el nombre actual almacenado en la cápsula. En caso de falla, establece una excepción y retorna NULL.

Es legal que una cápsula tenga un nombre NULL. Esto hace que un código de retorno NULL sea algo ambiguo; use PyCapsule_IsValid() o PyErr_Occurred() para desambiguar.

void* PyCapsule_Import(const char *name, int no_block)

Importa un puntero a un objeto C desde un atributo cápsula en un módulo. El parámetro name debe especificar el nombre completo del atributo, como en module.attribute. El nombre name almacenado en la cápsula debe coincidir exactamente con esta cadena de caracteres. Si no_block es verdadero, importa el módulo sin bloquear (usando PyImport_ImportModuleNoBlock()). Si no_block es falso, importa el módulo convencionalmente (usando PyImport_ImportModule()).

Retorna el puntero pointer interno de la cápsula en caso de éxito. En caso de falla, establece una excepción y retorna NULL.

int PyCapsule_IsValid(PyObject *capsule, const char *name)

Determina si capsule es o no una cápsula válida. Una cápsula válida no es NULL, pasa PyCapsule_CheckExact(), tiene un puntero no NULL almacenado y su nombre interno coincide con el parámetro name. (Consulte PyCapsule_GetPointer() para obtener información sobre cómo se comparan los nombres de las cápsulas).

En otras palabras, si PyCapsule_IsValid() retorna un valor verdadero, las llamadas a cualquiera de las funciones de acceso (cualquier función que comience con PyCapsule_Get()) tienen éxito.

Retorna un valor distinto de cero si el objeto es válido y coincide con el nombre pasado. Retorna 0 de lo contrario. Esta función no fallará.

int PyCapsule_SetContext(PyObject *capsule, void *context)

Establece el puntero de contexto dentro de capsule a context.

Retorna 0 en caso de éxito. Retorna distinto de cero y establece una excepción en caso de error.

int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)

Establece el destructor dentro de capsule en destructor.

Retorna 0 en caso de éxito. Retorna distinto de cero y establece una excepción en caso de error.

int PyCapsule_SetName(PyObject *capsule, const char *name)

Establece el nombre dentro de capsule a name. Si no es NULL, el nombre debe sobrevivir a la cápsula. Si el name anterior almacenado en la cápsula no era NULL, no se intenta liberarlo.

Retorna 0 en caso de éxito. Retorna distinto de cero y establece una excepción en caso de error.

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)

Establece el puntero vacío dentro de capsule a pointer. El puntero puede no ser NULL.

Retorna 0 en caso de éxito. Retorna distinto de cero y establece una excepción en caso de error.

Objetos Generadores

Los objetos generadores son lo que Python usa para implementar iteradores generadores. Normalmente se crean iterando sobre una función que produce valores, en lugar de llamar explícitamente PyGen_New() o PyGen_NewWithQualName().

PyGenObject

La estructura en C utilizada para los objetos generadores.

PyTypeObject PyGen_Type

El objeto tipo correspondiente a los objetos generadores.

int PyGen_Check(PyObject *ob)

Retorna verdadero si ob es un objeto generador; ob no debe ser NULL. Esta función siempre finaliza con éxito.

int PyGen_CheckExact(PyObject *ob)

Retorna verdadero si el tipo de ob es PyGen_Type; ob no debe ser NULL. Esta función siempre finaliza con éxito.

PyObject* PyGen_New(PyFrameObject *frame)

Return value: New reference.

Crea y retorna un nuevo objeto generador basado en el objeto frame. Una referencia a frame es robada por esta función. El argumento no debe ser NULL.

PyObject* PyGen_NewWithQualName(PyFrameObject *frame, PyObject *name, PyObject *qualname)

Return value: New reference.

Crea y retorna un nuevo objeto generador basado en el objeto frame, con __name__ y __qualname__ establecido en name y qualname. Una referencia a frame es robada por esta función. El argumento frame no debe ser NULL.

Objetos corrutina

Nuevo en la versión 3.5.

Los objetos de corrutina son las funciones declaradas con un retorno de palabra clave async.

PyCoroObject

La estructura en C utilizada para objeto corrutina.

PyTypeObject PyCoro_Type

El tipo de objeto correspondiente a los objetos corrutina.

int PyCoro_CheckExact(PyObject *ob)

Retorna verdadero si el tipo de ob es PyCoro_Type; ob no debe ser NULL. Esta función siempre finaliza con éxito.

PyObject* PyCoro_New(PyFrameObject *frame, PyObject *name, PyObject *qualname)

Return value: New reference.

Crea y retorna un nuevo objeto corrutina basado en el objeto frame, con __name__ y __qualname__ establecido en name y qualname. Una referencia a frame es robada por esta función. El argumento frame no debe ser NULL.

Objetos de variables de contexto

Nota

Distinto en la versión 3.7.1:

En Python 3.7.1, las firmas de todas las variables de contexto C APIs fueron cambiadas para usar punteros PyObject en lugar de PyContext, PyContextVar, y PyContextToken, por ejemplo:

// in 3.7.0:
PyContext *PyContext_New(void);

// in 3.7.1+:
PyObject *PyContext_New(void);

Ver bpo-34762 [https://bugs.python.org/issue?@action=redirect&bpo=34762] para más detalles.

Nuevo en la versión 3.7.

Esta sección detalla la API pública de C para el módulo contextvars.

PyContext

La estructura C utilizada para representar un objeto contextvars.Context.

PyContextVar

La estructura C utilizada para representar un objeto contextvars.ContextVar.

PyContextToken

La estructura C solía representar un objeto contextvars.Token.

PyTypeObject PyContext_Type

El objeto de tipo que representa el tipo context.

PyTypeObject PyContextVar_Type

El objeto tipo que representa el tipo variable de contexto.

PyTypeObject PyContextToken_Type

El tipo objeto que representa el tipo token de variable de contexto.

Macros de verificación de tipo:

int PyContext_CheckExact(PyObject *o)

Retorna verdadero si o es de tipo PyContext_Type. o no debe ser NULL. Esta función siempre finaliza con éxito.

int PyContextVar_CheckExact(PyObject *o)

Retorna verdadero si o es de tipo PyContextVar_Type. o no debe ser NULL. Esta función siempre finaliza con éxito.

int PyContextToken_CheckExact(PyObject *o)

Retorna verdadero si o es de tipo PyContextToken_Type. o no debe ser NULL. Esta función siempre finaliza con éxito.

Funciones de gestión de objetos de contexto:

PyObject *PyContext_New(void)

Return value: New reference.

Crea un nuevo objeto de contexto vacío. Retorna NULL si se ha producido un error.

PyObject *PyContext_Copy(PyObject *ctx)

Return value: New reference.

Crea una copia superficial del objeto de contexto ctx pasado. Retorna NULL si se ha producido un error.

PyObject *PyContext_CopyCurrent(void)

Return value: New reference.

Crea una copia superficial del contexto actual del hilo. Retorna NULL si se ha producido un error.

int PyContext_Enter(PyObject *ctx)

Establece ctx como el contexto actual para el hilo actual. Retorna 0 en caso de éxito y -1 en caso de error.

int PyContext_Exit(PyObject *ctx)

Desactiva el contexto ctx y restaura el contexto anterior como el contexto actual para el hilo actual. Retorna 0 en caso de éxito y -1 en caso de error.

Funciones variables de contexto:

PyObject *PyContextVar_New(const char *name, PyObject *def)

Return value: New reference.

Create a new ContextVar object. The name parameter is used for introspection and debug purposes. The def parameter specifies a default value for the context variable, or NULL for no default. If an error has occurred, this function returns NULL.

int PyContextVar_Get(PyObject *var, PyObject *default_value, PyObject **value)

Obtiene el valor de una variable de contexto. Retorna -1 si se produjo un error durante la búsqueda y 0 si no se produjo ningún error, se haya encontrado o no un valor.

Si se encontró la variable de contexto, value será un puntero a ella. Si la variable de contexto not se encontró, value apuntará a:

default_value, si no es NULL;

el valor predeterminado de var, si no es NULL;

NULL

Except for NULL, the function returns a new reference.

PyObject *PyContextVar_Set(PyObject *var, PyObject *value)

Return value: New reference.

Set the value of var to value in the current context. Returns a new token object for this change, or NULL if an error has occurred.

int PyContextVar_Reset(PyObject *var, PyObject *token)

Restablece el estado de la variable de contexto var a la que estaba antes PyContextVar_Set() que retornó el token fue llamado. Esta función retorna 0 en caso de éxito y -1 en caso de error.

Objetos DateTime

El módulo datetime proporciona varios objetos de fecha y hora. Antes de usar cualquiera de estas funciones, el archivo de encabezado datetime.h debe estar incluido en su fuente (tenga en cuenta que esto no está incluido en el archivo Python.h), y la macro PyDateTime_IMPORT debe llamarse, generalmente como parte de la función de inicialización del módulo. La macro coloca un puntero a una estructura C en una variable estática, PyDateTimeAPI, que utilizan las siguientes macros.

Macro para acceder al singleton UTC:

PyObject* PyDateTime_TimeZone_UTC

Retorna la zona horaria singleton que representa UTC, el mismo objeto que datetime.timezone.utc.

Nuevo en la versión 3.7.

Macros de verificación de tipo:

int PyDate_Check(PyObject *ob)

Retorna verdadero si ob es de tipo PyDateTime_DateType o un subtipo de PyDateTime_DateType. ob no debe ser NULL. Esta función siempre finaliza con éxito.

int PyDate_CheckExact(PyObject *ob)

Retorna verdadero si ob es de tipo PyDateTime_DateType. ob no debe ser NULL. Esta función siempre finaliza con éxito.

int PyDateTime_Check(PyObject *ob)

Retorna verdadero si ob es de tipo PyDateTime_DateTimeType o un subtipo de PyDateTime_DateTimeType. ob no debe ser NULL. Esta función siempre finaliza con éxito.

int PyDateTime_CheckExact(PyObject *ob)

Retorna verdadero si ob es de tipo PyDateTime_DateTimeType. ob no debe ser NULL. Esta función siempre finaliza con éxito.

int PyTime_Check(PyObject *ob)

Retorna verdadero si ob es de tipo PyDateTime_TimeType o un subtipo de PyDateTime_TimeType. ob no debe ser NULL. Esta función siempre finaliza con éxito.

int PyTime_CheckExact(PyObject *ob)

Retorna verdadero si ob es de tipo PyDateTime_TimeType. ob no debe ser NULL. Esta función siempre finaliza con éxito.

int PyDelta_Check(PyObject *ob)

Retorna verdadero si ob es de tipo PyDateTime_DeltaType o un subtipo de PyDateTime_DeltaType. ob no debe ser NULL. Esta función siempre finaliza con éxito.

int PyDelta_CheckExact(PyObject *ob)

Retorna verdadero si ob es de tipo PyDateTime_DeltaType. ob no debe ser NULL. Esta función siempre finaliza con éxito.

int PyTZInfo_Check(PyObject *ob)

Retorna verdadero si ob es de tipo PyDateTime_TZInfoType o un subtipo de PyDateTime_TZInfoType. ob no debe ser NULL. Esta función siempre finaliza con éxito.

int PyTZInfo_CheckExact(PyObject *ob)

Retorna verdadero si ob es de tipo PyDateTime_TZInfoType. ob no debe ser NULL. Esta función siempre finaliza con éxito.

Macros para crear objetos:

PyObject* PyDate_FromDate(int year, int month, int day)

Return value: New reference.

Retorna un objeto datetime.date con el año, mes y día especificados.

PyObject* PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond)

Return value: New reference.

Retorna un objeto datetime.datetime con el año, mes, día, hora, minuto, segundo y micro segundo especificados.

PyObject* PyDateTime_FromDateAndTimeAndFold(int year, int month, int day, int hour, int minute, int second, int usecond, int fold)

Return value: New reference.

Retorna un objeto datetime.datetime con el año, mes, día, hora, minuto, segundo, micro segundo y doblez especificados.

Nuevo en la versión 3.6.

PyObject* PyTime_FromTime(int hour, int minute, int second, int usecond)

Return value: New reference.

Retorna un objeto datetime.time con la hora, minuto, segundo y micro segundo especificados.

PyObject* PyTime_FromTimeAndFold(int hour, int minute, int second, int usecond, int fold)

Return value: New reference.

Retorna un objeto datetime.time con la hora, minuto, segundo, micro segundo y doblez especificados.

Nuevo en la versión 3.6.

PyObject* PyDelta_FromDSU(int days, int seconds, int useconds)

Return value: New reference.

Retorna un objeto datetime.timedelta que representa el número dado de días, segundos y micro segundos. La normalización se realiza de modo que el número resultante de micro segundos y segundos se encuentre en los rangos documentados para los objetos datetime.timedelta.

PyObject* PyTimeZone_FromOffset(PyDateTime_DeltaType* offset)

Return value: New reference.

Retorna un objeto datetime.timezone con un desplazamiento fijo sin nombre representado por el argumento offset.

Nuevo en la versión 3.7.

PyObject* PyTimeZone_FromOffsetAndName(PyDateTime_DeltaType* offset, PyUnicode* name)

Return value: New reference.

Retorna un objeto datetime.timezone con un desplazamiento fijo representado por el argumento offset y con tzname name.

Nuevo en la versión 3.7.

Macros para extraer campos de objetos de fecha. El argumento debe ser una instancia de PyDateTime_Date, incluidas las subclases (como PyDateTime_DateTime). El argumento no debe ser NULL y el tipo no está marcado:

int PyDateTime_GET_YEAR(PyDateTime_Date *o)

Regrese el año, como un int positivo.

int PyDateTime_GET_MONTH(PyDateTime_Date *o)

Regresa el mes, como int del 1 al 12.

int PyDateTime_GET_DAY(PyDateTime_Date *o)

Retorna el día, como int del 1 al 31.

Macros para extraer campos de objetos de fecha y hora. El argumento debe ser una instancia de PyDateTime_DateTime, incluidas las subclases. El argumento no debe ser NULL y el tipo no es comprobado:

int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)

Retorna la hora, como un int de 0 hasta 23.

int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)

Retorna el minuto, como un int de 0 hasta 59.

int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)

Retorna el segundo, como un int de 0 hasta 59.

int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)

Retorna el micro segundo, como un int de 0 hasta 999999.

int PyDateTime_DATE_GET_FOLD(PyDateTime_DateTime *o)

Return the fold, as an int from 0 through 1.

Nuevo en la versión 3.6.

Macros para extraer campos de objetos de tiempo. El argumento debe ser una instancia de PyDateTime_Time, incluidas las subclases. El argumento no debe ser NULL y el tipo no está marcado:

int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)

Retorna la hora, como un int de 0 hasta 23.

int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)

Retorna el minuto, como un int de 0 hasta 59.

int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)

Retorna el segundo, como un int de 0 hasta 59.

int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)

Retorna el micro segundo, como un int de 0 hasta 999999.

int PyDateTime_TIME_GET_FOLD(PyDateTime_Time *o)

Return the fold, as an int from 0 through 1.

Nuevo en la versión 3.6.

Macros para extraer campos de objetos delta de tiempo. El argumento debe ser una instancia de PyDateTime_Delta, incluidas las subclases. El argumento no debe ser NULL y el tipo no está marcado:

int PyDateTime_DELTA_GET_DAYS(PyDateTime_Delta *o)

Retorna el número de días, como un int desde -999999999 a 999999999.

Nuevo en la versión 3.3.

int PyDateTime_DELTA_GET_SECONDS(PyDateTime_Delta *o)

Retorna el número de segundos, como un int de 0 a 86399.

Nuevo en la versión 3.3.

int PyDateTime_DELTA_GET_MICROSECONDS(PyDateTime_Delta *o)

Retorna el número de micro segundos, como un int de 0 a 999999.

Nuevo en la versión 3.3.

Macros para la conveniencia de módulos que implementan la API DB:

PyObject* PyDateTime_FromTimestamp(PyObject *args)

Return value: New reference.

Crea y retorna un nuevo objeto datetime.datetime dado una tupla de argumentos adecuada para pasar a datetime.datetime.fromtimestamp().

PyObject* PyDate_FromTimestamp(PyObject *args)

Return value: New reference.

Crea y retorna un nuevo objeto datetime.date dado una tupla de argumentos adecuada para pasar a datetime.date.fromtimestamp().

Objects for Type Hinting

Various built-in types for type hinting are provided. Only GenericAlias is exposed to C.

PyObject* Py_GenericAlias(PyObject *origin, PyObject *args)

Create a GenericAlias object. Equivalent to calling the Python class types.GenericAlias. The origin and args arguments set the GenericAlias’s __origin__ and __args__ attributes respectively. origin should be a PyTypeObject*, and args can be a PyTupleObject* or any PyObject*. If args passed is not a tuple, a 1-tuple is automatically constructed and __args__ is set to (args,). Minimal checking is done for the arguments, so the function will succeed even if origin is not a type. The GenericAlias’s __parameters__ attribute is constructed lazily from __args__. On failure, an exception is raised and NULL is returned.

Here’s an example of how to make an extension type generic:

...
static PyMethodDef my_obj_methods[] = {
    // Other methods.
    ...
    {"__class_getitem__", (PyCFunction)Py_GenericAlias, METH_O|METH_CLASS, "See PEP 585"}
    ...
}

Ver también

The data model method __class_getitem__().

Nuevo en la versión 3.9.

PyTypeObject Py_GenericAliasType

The C type of the object returned by Py_GenericAlias(). Equivalent to types.GenericAlias in Python.

Nuevo en la versión 3.9.

Inicialización, Finalización e Hilos

Consulte también Configuración de inicialización de Python.

Antes de la inicialización de Python

En una aplicación que incorpora Python, se debe llamar a la función Py_Initialize() antes de usar cualquier otra función de API Python/C; con la excepción de algunas funciones y variables de configuración global.

Las siguientes funciones se pueden invocar de forma segura antes de que se inicializa Python:

Funciones de configuración:

PyImport_AppendInittab()

PyImport_ExtendInittab()

PyInitFrozenExtensions()

PyMem_SetAllocator()

PyMem_SetupDebugHooks()

PyObject_SetArenaAllocator()

Py_SetPath()

Py_SetProgramName()

Py_SetPythonHome()

Py_SetStandardStreamEncoding()

PySys_AddWarnOption()

PySys_AddXOption()

PySys_ResetWarnOptions()

Funciones informativas:

Py_IsInitialized()

PyMem_GetAllocator()

PyObject_GetArenaAllocator()

Py_GetBuildInfo()

Py_GetCompiler()

Py_GetCopyright()

Py_GetPlatform()

Py_GetVersion()

Utilidades:

Py_DecodeLocale()

Asignadores de memoria:

PyMem_RawMalloc()

PyMem_RawRealloc()

PyMem_RawCalloc()

PyMem_RawFree()

Nota

Las siguientes funciones no deben llamarse antes de Py_Initialize(): Py_EncodeLocale(), Py_GetPath(), Py_GetPrefix(), Py_GetExecPrefix(), Py_GetProgramFullPath(), Py_GetPythonHome(), Py_GetProgramName() y PyEval_InitThreads().

Variables de configuración global

Python tiene variables para la configuración global para controlar diferentes características y opciones. De forma predeterminada, estos indicadores están controlados por opciones de línea de comando.

Cuando una opción establece un indicador, el valor del indicador es la cantidad de veces que se configuró la opción. Por ejemplo, -b establece Py_BytesWarningFlag en 1 y -bb establece Py_BytesWarningFlag en 2.

int Py_BytesWarningFlag

Emite una advertencia al comparar bytes o bytearray con str o bytes con int. Emite un error si es mayor o igual a 2.

Establecido por la opción -b.

int Py_DebugFlag

Activa la salida de depuración del analizador (solo para expertos, según las opciones de compilación).

Establecido por la opción -d y la variable de entorno PYTHONDEBUG.

int Py_DontWriteBytecodeFlag

Si se establece en un valor distinto de cero, Python no intentará escribir archivos .pyc en la importación de módulos fuente.

Establecido por la opción -B y la variable de entorno PYTHONDONTWRITEBYTECODE.

int Py_FrozenFlag

Suprime los mensajes de error al calcular la ruta de búsqueda del módulo en Py_GetPath().

Indicador privado utilizado por los programas _freeze_importlib y frozenmain.

int Py_HashRandomizationFlag

Se establece en 1 si la variable de entorno PYTHONHASHSEED se establece en una cadena de caracteres no vacía.

Si el indicador no es cero, lee la variable de entorno PYTHONHASHSEED para inicializar la semilla de hash secreta.

int Py_IgnoreEnvironmentFlag

Ignorar todas las variables de entorno PYTHON*, por ejemplo PYTHONPATH y PYTHONHOME, eso podría establecerse.

Establecido por las opciones -E y -I.

int Py_InspectFlag

Cuando se pasa una secuencia de comandos (script) como primer argumento o se usa la opción -c, ingresa al modo interactivo después de ejecutar la secuencia de comandos o el comando, incluso cuando sys.stdin no parece ser un terminal.

Establecido por la opción -i y la variable de entorno PYTHONINSPECT.

int Py_InteractiveFlag

Establecido por la opción -i.

int Py_IsolatedFlag

Ejecuta Python en modo aislado. En modo aislado sys.path no contiene ni el directorio de la secuencia de comandos (script) ni el directorio de paquetes del sitio del usuario (site-pacages).

Establecido por la opción -I.

Nuevo en la versión 3.4.

int Py_LegacyWindowsFSEncodingFlag

Si el indicador no es cero, use la codificación mbcs en lugar de la codificación UTF-8 para la codificación del sistema de archivos.

Establece en 1 si la variable de entorno PYTHONLEGACYWINDOWSFSENCODING está configurada en una cadena de caracteres no vacía.

Ver PEP 529 [https://www.python.org/dev/peps/pep-0529] para más detalles.

Disponibilidad: Windows.

int Py_LegacyWindowsStdioFlag

Si el indicador no es cero, use io.FileIO en lugar de WindowsConsoleIO para secuencias estándar sys.

Establece en 1 si la variable de entorno PYTHONLEGACYWINDOWSSTDIO está configurada en una cadena de caracteres no vacía.

Ver PEP 528 [https://www.python.org/dev/peps/pep-0528] para más detalles.

Disponibilidad: Windows.

int Py_NoSiteFlag

Deshabilita la importación del módulo site y las manipulaciones dependientes del sitio de sys.path que conlleva. También deshabilita estas manipulaciones si site se importa explícitamente más tarde (llama a site.main() si desea que se activen).

Establecido por la opción -S.

int Py_NoUserSiteDirectory

No agregue el directorio de paquetes de sitio del usuario (site-packages) a sys.path.

Establecido por las opciones -s y -I, y la variable de entorno PYTHONNOUSERSITE.

int Py_OptimizeFlag

Establecido por la opción -O y la variable de entorno PYTHONOPTIMIZE.

int Py_QuietFlag

No muestre los mensajes de copyright y de versión incluso en modo interactivo.

Establecido por la opción -q.

Nuevo en la versión 3.2.

int Py_UnbufferedStdioFlag

Obliga a las secuencias stdout y stderr a que no tengan búfer.

Establecido por la opción -u y la variable de entorno PYTHONUNBUFFERED.

int Py_VerboseFlag

Imprime un mensaje cada vez que se inicializa un módulo, mostrando el lugar (nombre de archivo o módulo incorporado) desde el que se carga. Si es mayor o igual a 2, imprime un mensaje para cada archivo que se verifica al buscar un módulo. También proporciona información sobre la limpieza del módulo a la salida.

Establecido por la opción -v y la variable de entorno PYTHONVERBOSE.

Inicializando y finalizando el intérprete

void Py_Initialize()

Inicializa el intérprete de Python. En una aplicación que incorpora Python, se debe llamar antes de usar cualquier otra función de API Python/C; vea Antes de la inicialización de Python para ver algunas excepciones.

Esto inicializa la tabla de módulos cargados (sys.modules) y crea los módulos fundamentales builtins, __main__ y sys. También inicializa la ruta de búsqueda del módulo (sys.path). No establece sys.argv; use PySys_SetArgvEx() para eso. Este es un no-op cuando se llama por segunda vez (sin llamar primero a Py_FinalizeEx()). No hay valor de retorno; es un error fatal si falla la inicialización.

Nota

En Windows, cambia el modo de consola de O_TEXT a O_BINARY, lo que también afectará los usos de la consola que no sean de Python utilizando C Runtime.

void Py_InitializeEx(int initsigs)

Esta función funciona como Py_Initialize() si initsigs es 1. Si initsigs es 0, omite el registro de inicialización de los manejadores de señal, lo que podría ser útil cuando Python está incrustado.

int Py_IsInitialized()

Retorna verdadero (distinto de cero) cuando el intérprete de Python se ha inicializado, falso (cero) si no. Después de que se llama a Py_FinalizeEx(), esto retorna falso hasta que Py_Initialize() se llama de nuevo.

int Py_FinalizeEx()

Deshace todas las inicializaciones realizadas por Py_Initialize() y el uso posterior de las funciones de Python/C API, y destruye todos los sub-intérpretes (ver Py_NewInterpreter() a continuación) que se crearon y aún no se destruyeron desde el última llamada a Py_Initialize(). Idealmente, esto libera toda la memoria asignada por el intérprete de Python. Este es un no-op cuando se llama por segunda vez (sin llamar a Py_Initialize() nuevamente primero). Normalmente el valor de retorno es 0. Si hubo errores durante la finalización (lavado de datos almacenados en el búfer), se retorna -1.

Esta función se proporciona por varias razones. Una aplicación de incrustación puede querer reiniciar Python sin tener que reiniciar la aplicación misma. Una aplicación que ha cargado el intérprete de Python desde una biblioteca cargable dinámicamente (o DLL) puede querer liberar toda la memoria asignada por Python antes de descargar la DLL. Durante una búsqueda de pérdidas de memoria en una aplicación, un desarrollador puede querer liberar toda la memoria asignada por Python antes de salir de la aplicación.

Errores y advertencias: La destrucción de módulos y objetos en módulos se realiza en orden aleatorio; esto puede causar que los destructores (métodos __del__()) fallen cuando dependen de otros objetos (incluso funciones) o módulos. Los módulos de extensión cargados dinámicamente cargados por Python no se descargan. Es posible que no se liberen pequeñas cantidades de memoria asignadas por el intérprete de Python (si encuentra una fuga, informe por favor). La memoria atada en referencias circulares entre objetos no se libera. Es posible que parte de la memoria asignada por los módulos de extensión no se libere. Algunas extensiones pueden no funcionar correctamente si su rutina de inicialización se llama más de una vez; Esto puede suceder si una aplicación llama a Py_Initialize() y Py_FinalizeEx() más de una vez.

Genera un evento de auditoría cpython._PySys_ClearAuditHooks sin argumentos.

Nuevo en la versión 3.6.

void Py_Finalize()

Esta es una versión compatible con versiones anteriores de Py_FinalizeEx() que ignora el valor de retorno.

Parámetros de todo el proceso

int Py_SetStandardStreamEncoding(const char *encoding, const char *errors)

Esta función debería llamarse antes de Py_Initialize(), si es que se llama. Especifica qué codificación y manejo de errores usar con IO estándar, con los mismos significados que en str.encode().

Reemplaza los valores PYTHONIOENCODING, y permite incrustar código para controlar la codificación IO cuando la variable de entorno no funciona.

codificación o errores pueden ser NULL para usar PYTHONIOENCODING o valores predeterminados (dependiendo de otras configuraciones).

Tenga en cuenta que sys.stderr siempre usa el controlador de error «backslashreplace», independientemente de esta configuración (o cualquier otra).

Si se llama a Py_FinalizeEx(), será necesario volver a llamar a esta función para afectar las llamadas posteriores a Py_Initialize().

Retorna 0 si tiene éxito, un valor distinto de cero en caso de error (por ejemplo, llamar después de que el intérprete ya se haya inicializado)

Nuevo en la versión 3.4.

void Py_SetProgramName(const wchar_t *name)

Esta función debería llamarse antes Py_Initialize() se llama por primera vez, si es que se llama. Le dice al intérprete el valor del argumento argv[0] para la función main() del programa (convertido a caracteres anchos). Esto es utilizado por Py_GetPath() y algunas otras funciones a continuación para encontrar las bibliotecas de tiempo de ejecución de Python relativas al ejecutable del intérprete. El valor predeterminado es 'python'. El argumento debe apuntar a una cadena de caracteres anchos terminada en cero en almacenamiento estático cuyo contenido no cambiará mientras dure la ejecución del programa. Ningún código en el intérprete de Python cambiará el contenido de este almacenamiento.

Use Py_DecodeLocale() para decodificar una cadena de bytes para obtener una cadena wchar_ *.

wchar* Py_GetProgramName()

Retorna el nombre del programa establecido con Py_SetProgramName(), o el valor predeterminado. La cadena de caracteres retornada apunta al almacenamiento estático; la persona que llama no debe modificar su valor.

wchar_t* Py_GetPrefix()

Retorna el prefijo prefix para los archivos instalados independientes de la plataforma. Esto se deriva a través de una serie de reglas complicadas del nombre del programa establecido con Py_SetProgramName() y algunas variables de entorno; por ejemplo, si el nombre del programa es '/usr/local/bin/python', el prefijo es '/usr/local'. La cadena de caracteres retornada apunta al almacenamiento estático; la persona que llama no debe modificar su valor. Esto corresponde a la variable prefix en el archivo de nivel superior Makefile y el argumento --prefix a la secuencia de comandos (script) configure en tiempo de compilación. El valor está disponible para el código de Python como sys.prefix. Solo es útil en Unix. Ver también la siguiente función.

wchar_t* Py_GetExecPrefix()

Retorna el exec-prefix para los archivos instalados dependientes de la plataforma. Esto se deriva a través de una serie de reglas complicadas del nombre del programa establecido con Py_SetProgramName() y algunas variables de entorno; por ejemplo, si el nombre del programa es '/usr/local/bin/python', el prefijo exec es '/usr/local'. La cadena de caracteres retornada apunta al almacenamiento estático; la persona que llama no debe modificar su valor. Esto corresponde a la variable exec_prefix en el archivo de nivel superior Makefile y el argumento --exec-prefix a la secuencia de comandos (script) configure en tiempo de compilación. El valor está disponible para el código de Python como sys.exec_prefix. Solo es útil en Unix.

Antecedentes: el prefijo exec difiere del prefijo cuando los archivos dependientes de la plataforma (como ejecutables y bibliotecas compartidas) se instalan en un árbol de directorios diferente. En una instalación típica, los archivos dependientes de la plataforma pueden instalarse en el subárbol /usr/local/plat mientras que la plataforma independiente puede instalarse en /usr/local.

En términos generales, una plataforma es una combinación de familias de hardware y software, por ejemplo, las máquinas Sparc que ejecutan el sistema operativo Solaris 2.x se consideran la misma plataforma, pero las máquinas Intel que ejecutan Solaris 2.x son otra plataforma, y las máquinas Intel que ejecutan Linux son otra plataforma más. Las diferentes revisiones importantes del mismo sistema operativo generalmente también forman plataformas diferentes. Los sistemas operativos que no son Unix son una historia diferente; Las estrategias de instalación en esos sistemas son tan diferentes que el prefijo y el prefijo exec no tienen sentido y se configuran en la cadena vacía. Tenga en cuenta que los archivos de bytecode compilados de Python son independientes de la plataforma (¡pero no independientes de la versión de Python con la que fueron compilados!).

Los administradores de sistemas sabrán cómo configurar los programas mount o automount para compartir /usr/local entre plataformas mientras que /usr/local/plat sea un sistema de archivos diferente para cada plataforma.

wchar_t* Py_GetProgramFullPath()

Retorna el nombre completo del programa del ejecutable de Python; esto se calcula como un efecto secundario de derivar la ruta de búsqueda predeterminada del módulo del nombre del programa (establecido por Py_SetProgramName() arriba). La cadena de caracteres retornada apunta al almacenamiento estático; la persona que llama no debe modificar su valor. El valor está disponible para el código de Python como sys.executable.

wchar_t* Py_GetPath()

Return the default module search path; this is computed from the program name (set by Py_SetProgramName() above) and some environment variables. The returned string consists of a series of directory names separated by a platform dependent delimiter character. The delimiter character is ':' on Unix and macOS, ';' on Windows. The returned string points into static storage; the caller should not modify its value. The list sys.path is initialized with this value on interpreter startup; it can be (and usually is) modified later to change the search path for loading modules.

void Py_SetPath(const wchar_t *)

Set the default module search path. If this function is called before Py_Initialize(), then Py_GetPath() won’t attempt to compute a default search path but uses the one provided instead. This is useful if Python is embedded by an application that has full knowledge of the location of all modules. The path components should be separated by the platform dependent delimiter character, which is ':' on Unix and macOS, ';' on Windows.

Esto también hace que sys.executable se configure en la ruta completa del programa (consulte Py_GetProgramFullPath()) y para sys.prefix y sys.exec_prefix a estar vacío. Depende de la persona que llama modificarlos si es necesario después de llamar Py_Initialize().

Use Py_DecodeLocale() para decodificar una cadena de bytes para obtener una cadena wchar_ *.

El argumento de ruta se copia internamente, por lo que la persona que llama puede liberarlo después de que se complete la llamada.

Distinto en la versión 3.8: La ruta completa del programa ahora se usa para sys.executable, en lugar del nombre del programa.

const char* Py_GetVersion()

Retorna la versión de este intérprete de Python. Esta es una cadena de caracteres que se parece a

"3.0a5+ (py3k:63103M, May 12 2008, 00:53:55) \n[GCC 4.2.3]"

The first word (up to the first space character) is the current Python version; the first characters are the major and minor version separated by a period. The returned string points into static storage; the caller should not modify its value. The value is available to Python code as sys.version.

const char* Py_GetPlatform()

Return the platform identifier for the current platform. On Unix, this is formed from the «official» name of the operating system, converted to lower case, followed by the major revision number; e.g., for Solaris 2.x, which is also known as SunOS 5.x, the value is 'sunos5'. On macOS, it is 'darwin'. On Windows, it is 'win'. The returned string points into static storage; the caller should not modify its value. The value is available to Python code as sys.platform.

const char* Py_GetCopyright()

Retorna la cadena de caracteres de copyright oficial para la versión actual de Python, por ejemplo

'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'

La cadena de caracteres retornada apunta al almacenamiento estático; la persona que llama no debe modificar su valor. El valor está disponible para el código de Python como sys.copyright.

const char* Py_GetCompiler()

Retorna una indicación del compilador utilizado para construir la versión actual de Python, entre corchetes, por ejemplo:

"[GCC 2.7.2.2]"

La cadena de caracteres retornada apunta al almacenamiento estático; la persona que llama no debe modificar su valor. El valor está disponible para el código Python como parte de la variable sys.version.

const char* Py_GetBuildInfo()

Retorna información sobre el número de secuencia y la fecha y hora de compilación de la instancia actual de intérprete de Python, por ejemplo:

"#67, Aug  1 1997, 22:34:28"

La cadena de caracteres retornada apunta al almacenamiento estático; la persona que llama no debe modificar su valor. El valor está disponible para el código Python como parte de la variable sys.version.

void PySys_SetArgvEx(int argc, wchar_t **argv, int updatepath)

Establece sys.argv basado en argc y argv. Estos parámetros son similares a los pasados a la función del programa main() con la diferencia de que la primera entrada debe referirse al archivo de la secuencia de comandos (script) que se ejecutará en lugar del ejecutable que aloja el intérprete de Python. Si no se ejecuta una secuencia de comandos (script), la primera entrada en argv puede ser una cadena de caracteres vacía. Si esta función no puede inicializar sys.argv, una condición fatal se señala usando Py_FatalError().

Si updatepath es cero, esto es todo lo que hace la función. Si updatepath no es cero, la función también modifica sys.path de acuerdo con el siguiente algoritmo:

Si el nombre de una secuencia de comandos (script) existente se pasa en argv[0], la ruta absoluta del directorio donde se encuentra el script se antepone a sys.path.

De lo contrario (es decir, si argc es 0 o argv[0] no apunta a un nombre de archivo existente), una cadena de caracteres vacía se antepone a sys.path, que es lo mismo que anteponer el directorio de trabajo actual (".").

Use Py_DecodeLocale() para decodificar una cadena de bytes para obtener una cadena wchar_ *.

Nota

Se recomienda que las aplicaciones que incorporan el intérprete de Python para otros fines que no sean ejecutar una sola secuencia de comandos (script) pasen 0 como updatepath y actualicen sys.path si lo desean. Ver CVE-2008-5983 <https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2008-5983> _.

En las versiones anteriores a 3.1.3, puede lograr el mismo efecto quitando manualmente el primer elemento (popping) sys.path después de haber llamado PySys_SetArgv(), por ejemplo usando

PyRun_SimpleString("import sys; sys.path.pop(0)\n");

Nuevo en la versión 3.1.3.

void PySys_SetArgv(int argc, wchar_t **argv)

Esta función funciona como PySys_SetArgvEx() con updatepath establecido en 1 a menos que el intérprete python se haya iniciado con la opción -I.

Use Py_DecodeLocale() para decodificar una cadena de bytes para obtener una cadena wchar_ *.

Distinto en la versión 3.4: El valor updatepath depende de la opción -I.

void Py_SetPythonHome(const wchar_t *home)

Establece el directorio «inicio» («home») predeterminado, es decir, la ubicación de las bibliotecas estándar de Python. Ver PYTHONHOME para el significado de la cadena de caracteres de argumento.

El argumento debe apuntar a una cadena de caracteres terminada en cero en el almacenamiento estático cuyo contenido no cambiará mientras dure la ejecución del programa. Ningún código en el intérprete de Python cambiará el contenido de este almacenamiento.

Use Py_DecodeLocale() para decodificar una cadena de bytes para obtener una cadena wchar_ *.

w_char* Py_GetPythonHome()

Retorna el «inicio» (home) predeterminado, es decir, el valor establecido por una llamada anterior a Py_SetPythonHome(), o el valor de la variable de entorno PYTHONHOME si está configurado.

Estado del hilo y el bloqueo global del intérprete

El intérprete de Python no es completamente seguro para hilos (thread-safe). Para admitir programas Python multiproceso, hay un bloqueo global, denominado global interpreter lock o GIL, que debe mantener el hilo actual antes de que pueda acceder de forma segura a los objetos Python. Sin el bloqueo, incluso las operaciones más simples podrían causar problemas en un programa de hilos múltiples: por ejemplo, cuando dos hilos incrementan simultáneamente el conteo de referencias del mismo objeto, el conteo de referencias podría terminar incrementándose solo una vez en lugar de dos veces.

Por lo tanto, existe la regla de que solo el hilo que ha adquirido GIL puede operar en objetos Python o llamar a funciones API Python/C. Para emular la concurrencia de ejecución, el intérprete regularmente intenta cambiar los hilos (ver sys.setswitchinterval()). El bloqueo también se libera para bloquear potencialmente las operaciones de E/S, como leer o escribir un archivo, para que otros hilos de Python puedan ejecutarse mientras tanto.

El intérprete de Python mantiene cierta información de contabilidad específica de hilos dentro de una estructura de datos llamada PyThreadState. También hay una variable global que apunta a la actual PyThreadState: se puede recuperar usando PyThreadState_Get().

Liberando el GIL del código de extensión

La mayoría del código de extensión que manipula el GIL tiene la siguiente estructura simple

Save the thread state in a local variable.
Release the global interpreter lock.
... Do some blocking I/O operation ...
Reacquire the global interpreter lock.
Restore the thread state from the local variable.

Esto es tan común que existen un par de macros para simplificarlo:

Py_BEGIN_ALLOW_THREADS
... Do some blocking I/O operation ...
Py_END_ALLOW_THREADS

La macro Py_BEGIN_ALLOW_THREADS abre un nuevo bloque y declara una variable local oculta; la macro Py_END_ALLOW_THREADS cierra el bloque.

El bloque anterior se expande al siguiente código:

PyThreadState *_save;

_save = PyEval_SaveThread();
... Do some blocking I/O operation ...
PyEval_RestoreThread(_save);

Así es como funcionan estas funciones: el bloqueo global del intérprete se usa para proteger el puntero al estado actual del hilo. Al liberar el bloqueo y guardar el estado del hilo, el puntero del estado del hilo actual debe recuperarse antes de que se libere el bloqueo (ya que otro hilo podría adquirir inmediatamente el bloqueo y almacenar su propio estado de hilo en la variable global). Por el contrario, al adquirir el bloqueo y restaurar el estado del hilo, el bloqueo debe adquirirse antes de almacenar el puntero del estado del hilo.

Nota

Llamar a las funciones de E/S del sistema es el caso de uso más común para liberar el GIL, pero también puede ser útil antes de llamar a cálculos de larga duración que no necesitan acceso a objetos de Python, como las funciones de compresión o criptográficas que operan sobre memorias intermedias. Por ejemplo, los módulos estándar zlib y hashlib liberan el GIL al comprimir o mezclar datos.

Hilos creados sin Python

Cuando se crean hilos utilizando las API dedicadas de Python (como el módulo threading), se les asocia automáticamente un estado del hilo y, por lo tanto, el código que se muestra arriba es correcto. Sin embargo, cuando los hilos se crean desde C (por ejemplo, por una biblioteca de terceros con su propia administración de hilos), no contienen el GIL, ni existe una estructura de estado de hilos para ellos.

Si necesita llamar al código Python desde estos subprocesos (a menudo esto será parte de una API de devolución de llamada proporcionada por la biblioteca de terceros mencionada anteriormente), primero debe registrar estos subprocesos con el intérprete creando una estructura de datos de estado del subproceso, luego adquiriendo el GIL, y finalmente almacenando su puntero de estado de hilo, antes de que pueda comenzar a usar la API Python/C Cuando haya terminado, debe restablecer el puntero del estado del hilo, liberar el GIL y finalmente liberar la estructura de datos del estado del hilo.

Las funciones PyGILState_Ensure() y PyGILState_Release() hacen todo lo anterior automáticamente. El idioma típico para llamar a Python desde un hilo C es:

PyGILState_STATE gstate;
gstate = PyGILState_Ensure();

/* Perform Python actions here. */
result = CallSomeFunction();
/* evaluate result or handle exception */

/* Release the thread. No Python API allowed beyond this point. */
PyGILState_Release(gstate);

Tenga en cuenta que las funciones PyGILState_*() suponen que solo hay un intérprete global (creado automáticamente por Py_Initialize()). Python admite la creación de intérpretes adicionales (usando Py_NewInterpreter()), pero la mezcla de múltiples intérpretes y la API PyGILState_*() no son compatibles.

Precauciones sobre fork()

Otra cosa importante a tener en cuenta sobre los hilos es su comportamiento frente a la llamada C fork(). En la mayoría de los sistemas con fork(), después de que un proceso se bifurca, solo existirá el hilo que emitió el fork. Esto tiene un impacto concreto tanto en cómo se deben manejar las cerraduras como en todo el estado almacenado en el tiempo de ejecución de CPython.

El hecho de que solo permanezca al hilo «actual» significa que ningún bloqueo retenido por otros hilos nunca se liberará. Python resuelve esto para os.fork() adquiriendo los bloqueos que usa internamente antes de la bifurcación (fork) y soltándolos después. Además, restablece cualquier Objetos tipo lock en el elemento secundario. Al extender o incrustar Python, no hay forma de informar a Python de bloqueos adicionales (que no sean Python) que deben adquirirse antes o restablecerse después de una bifurcación. Las instalaciones del sistema operativo como pthread_atfork() tendrían que usarse para lograr lo mismo. Además, al extender o incrustar Python, llamando fork() directamente en lugar de a través de os.fork() (y retornar o llamar a Python) puede resultar en un punto muerto (deadlock) por uno de los bloqueos internos de Python. sostenido por un hilo que no funciona después del fork. PyOS_AfterFork_Child() intenta restablecer los bloqueos necesarios, pero no siempre puede hacerlo.

El hecho de que todos los otros hilos desaparezcan también significa que el estado de ejecución de CPython debe limpiarse correctamente, lo que os.fork() lo hace. Esto significa finalizar todos los demás objetos PyThreadState que pertenecen al intérprete actual y todos los demás objetos PyInterpreterState. Debido a esto y a la naturaleza especial del intérprete «principal», fork() solo debería llamarse en el hilo «principal» de ese intérprete, donde el CPython global el tiempo de ejecución se inicializó originalmente. La única excepción es si exec() se llamará inmediatamente después.

API de alto nivel

Estos son los tipos y funciones más utilizados al escribir código de extensión C o al incrustar el intérprete de Python:

PyInterpreterState

Esta estructura de datos representa el estado compartido por varios subprocesos cooperantes. Los hilos que pertenecen al mismo intérprete comparten la administración de su módulo y algunos otros elementos internos. No hay miembros públicos en esta estructura.

Los hilos que pertenecen a diferentes intérpretes inicialmente no comparten nada, excepto el estado del proceso como memoria disponible, descriptores de archivos abiertos y demás. El bloqueo global del intérprete también es compartido por todos los hilos, independientemente de a qué intérprete pertenezcan.

PyThreadState

Esta estructura de datos representa el estado de un solo hilo. El único miembro de datos públicos es interp (PyInterpreterState *), que apunta al estado del intérprete de este hilo.

void PyEval_InitThreads()

Función deprecada que no hace nada.

En Python 3.6 y versiones anteriores, esta función creaba el GIL si no existía.

Distinto en la versión 3.9: La función ahora no hace nada.

Distinto en la versión 3.7: Esta función ahora es llamada por Py_Initialize(), por lo que ya no tiene que llamarla usted mismo.

Distinto en la versión 3.2: Esta función ya no se puede llamar antes de Py_Initialize().

Deprecated since version 3.9, will be removed in version 3.11.

int PyEval_ThreadsInitialized()

Retorna un valor distinto de cero si se ha llamado a PyEval_InitThreads(). Esta función se puede invocar sin mantener el GIL y, por lo tanto, se puede utilizar para evitar llamadas a la API de bloqueo cuando se ejecuta un solo hilo.

Distinto en la versión 3.7: El término GIL ahora se inicializa con Py_Initialize().

Deprecated since version 3.9, will be removed in version 3.11.

PyThreadState* PyEval_SaveThread()

Libere el bloqueo global del intérprete (si se ha creado) y restablezca el estado del hilo a NULL, retornando el estado del hilo anterior (que no es NULL). Si se ha creado el bloqueo, el hilo actual debe haberlo adquirido.

void PyEval_RestoreThread(PyThreadState *tstate)

Adquiera el bloqueo global del intérprete (si se ha creado) y establezca el estado del hilo en tstate, que no debe ser NULL. Si se ha creado el bloqueo, el hilo actual no debe haberlo adquirido, de lo contrario se produce un deadlock.

Nota

Llamar a esta función desde un hilo cuando finalice el tiempo de ejecución terminará el hilo, incluso si Python no creó el hilo. Puede usar _Py_IsFinalizing() o sys.is_finalizing() para verificar si el intérprete está en proceso de finalización antes de llamar a esta función para evitar una terminación no deseada.

PyThreadState* PyThreadState_Get()

Retorna el estado actual del hilo. Se debe mantener el bloqueo global del intérprete. Cuando el estado actual del hilo es NULL, esto genera un error fatal (por lo que la persona que llama no necesita verificar NULL).

PyThreadState* PyThreadState_Swap(PyThreadState *tstate)

Cambia el estado del hilo actual con el estado del hilo dado por el argumento tstate, que puede ser NULL. El bloqueo global del intérprete debe mantenerse y no se libera.

Las siguientes funciones utilizan almacenamiento local de hilos y no son compatibles con subinterpretes:

PyGILState_STATE PyGILState_Ensure()

Asegúrese de que el subproceso actual esté listo para llamar a la API de Python C, independientemente del estado actual de Python o del bloqueo global del intérprete. Esto se puede invocar tantas veces como lo desee un subproceso siempre que cada llamada coincida con una llamada a PyGILState_Release(). En general, se pueden usar otras API relacionadas con subprocesos entre PyGILState_Ensure() y PyGILState_Release() invoca siempre que el estado del subproceso se restablezca a su estado anterior antes del Release(). Por ejemplo, el uso normal de las macros Py_BEGIN_ALLOW_THREADS y Py_END_ALLOW_THREADS es aceptable.

El valor de retorno es un «identificador» opaco al estado del hilo cuando PyGILState_Ensure() fue llamado, y debe pasarse a PyGILState_Release() para asegurar que Python se deje en el mismo estado. Aunque las llamadas recursivas están permitidas, estos identificadores no pueden compartirse; cada llamada única a PyGILState_Ensure() debe guardar el identificador para su llamada a PyGILState_Release().

Cuando la función regrese, el hilo actual contendrá el GIL y podrá llamar a código arbitrario de Python. El fracaso es un error fatal.

Nota

Llamar a esta función desde un hilo cuando finalice el tiempo de ejecución terminará el hilo, incluso si Python no creó el hilo. Puede usar _Py_IsFinalizing() o sys.is_finalizing() para verificar si el intérprete está en proceso de finalización antes de llamar a esta función para evitar una terminación no deseada.

void PyGILState_Release(PyGILState_STATE)

Libera cualquier recurso previamente adquirido. Después de esta llamada, el estado de Python será el mismo que antes de la llamada correspondiente PyGILState_Ensure() (pero en general este estado será desconocido para la persona que llama, de ahí el uso de la API GILState).

Cada llamada a PyGILState_Ensure() debe coincidir con una llamada a PyGILState_Release() en el mismo hilo.

PyThreadState* PyGILState_GetThisThreadState()

Obtenga el estado actual del hilo para este hilo. Puede retornar NULL si no se ha utilizado la API GILState en el hilo actual. Tenga en cuenta que el subproceso principal siempre tiene dicho estado de subproceso, incluso si no se ha realizado una llamada de estado de subproceso automático en el subproceso principal. Esta es principalmente una función auxiliar y de diagnóstico.

int PyGILState_Check()

Retorna 1 si el hilo actual mantiene el GIL y 0 de lo contrario. Esta función se puede llamar desde cualquier hilo en cualquier momento. Solo si se ha inicializado el hilo de Python y actualmente mantiene el GIL, retornará 1. Esta es principalmente una función auxiliar y de diagnóstico. Puede ser útil, por ejemplo, en contextos de devolución de llamada o funciones de asignación de memoria cuando saber que el GIL está bloqueado puede permitir que la persona que llama realice acciones confidenciales o se comporte de otra manera de manera diferente.

Nuevo en la versión 3.4.

Las siguientes macros se usan normalmente sin punto y coma final; busque, por ejemplo, el uso en la distribución fuente de Python.

Py_BEGIN_ALLOW_THREADS

Esta macro se expande a {PyThreadState *_save; _save = PyEval_SaveThread();. Tenga en cuenta que contiene una llave de apertura; debe coincidir con la siguiente macro Py_END_ALLOW_THREADS. Ver arriba para una discusión más detallada de esta macro.

Py_END_ALLOW_THREADS

Esta macro se expande a PyEval_RestoreThread(_save); }. Tenga en cuenta que contiene una llave de cierre; debe coincidir con una macro anterior Py_BEGIN_ALLOW_THREADS. Ver arriba para una discusión más detallada de esta macro.

Py_BLOCK_THREADS

Esta macro se expande a PyEval_RestoreThread(_save);: es equivalente a Py_END_ALLOW_THREADS sin la llave de cierre.

Py_UNBLOCK_THREADS

Esta macro se expande a _save = PyEval_SaveThread();: es equivalente a Py_BEGIN_ALLOW_THREADS sin la llave de apertura y la declaración de variable.

API de bajo nivel

Todas las siguientes funciones deben llamarse después de Py_Initialize().

Distinto en la versión 3.7: Py_Initialize() ahora inicializa el GIL.

PyInterpreterState* PyInterpreterState_New()

Crea un nuevo objeto de estado de intérprete. No es necesario retener el bloqueo global del intérprete, pero se puede retener si es necesario para serializar llamadas a esta función.

Genera un evento de auditoría python.PyInterpreterState_New sin argumentos.

void PyInterpreterState_Clear(PyInterpreterState *interp)

Restablece toda la información en un objeto de estado de intérprete. Se debe mantener el bloqueo global del intérprete.

Lanza una eventos de auditoría python.PyInterpreterState Clear sin argumentos.

void PyInterpreterState_Delete(PyInterpreterState *interp)

Destruye un objeto de estado de intérprete. No es necesario mantener el bloqueo global del intérprete. El estado del intérprete debe haberse restablecido con una llamada previa a PyInterpreterState_Clear().

PyThreadState* PyThreadState_New(PyInterpreterState *interp)

Crea un nuevo objeto de estado de hilo que pertenece al objeto de intérprete dado. No es necesario retener el bloqueo global del intérprete, pero se puede retener si es necesario para serializar llamadas a esta función.

void PyThreadState_Clear(PyThreadState *tstate)

Restablece toda la información en un objeto de estado de hilo. Se debe mantener el bloqueo global del intérprete.

Distinto en la versión 3.9: Esta función ahora llama a la retrollamada PyThreadState.on_delete. Anteriormente, eso sucedía en PyThreadState_Delete().

void PyThreadState_Delete(PyThreadState *tstate)

Destruye un objeto de estado de hilo. No es necesario mantener el bloqueo global del intérprete. El estado del hilo debe haberse restablecido con una llamada previa a PyThreadState_Clear().

void PyThreadState_DeleteCurrent(void)

Destruye un objeto de estado de hilo y suelta el bloqueo del intérprete global. Como PyThreadState_Delete(), no es necesario mantener el bloqueo del intérprete global. El estado del hilo debe haberse restablecido con una llamada anterior a PyThreadState_Clear().

PyFrameObject* PyThreadState_GetFrame(PyThreadState *tstate)

Obtiene el marco actual del estado del hilo de Python tstate.

Retorna una referencia sólida. Retorna NULL si no se está ejecutando ningún marco.

Vea también PyEval_GetFrame().

tstate no debe ser NULL.

Nuevo en la versión 3.9.

uint64_t PyThreadState_GetID(PyThreadState *tstate)

Obtiene el identificador de estado de subproceso único del estado del hilo de Python tstate.

tstate no debe ser NULL.

Nuevo en la versión 3.9.

PyInterpreterState* PyThreadState_GetInterpreter(PyThreadState *tstate)

Obtiene el intérprete del estado del hilo de Python tstate.

tstate no debe ser NULL.

Nuevo en la versión 3.9.

PyInterpreterState* PyInterpreterState_Get(void)

Obtiene el intérprete actual.

Emite un error fatal si no hay un estado actual del hilo de Python o no hay un intérprete actual. No puede retornar NULL.

La persona que llama debe retener el GIL.

Nuevo en la versión 3.9.

int64_t PyInterpreterState_GetID(PyInterpreterState *interp)

Retorna la identificación única del intérprete. Si hubo algún error al hacerlo, entonces se retorna -1 y se establece un error.

La persona que llama debe retener el GIL.

Nuevo en la versión 3.7.

PyObject* PyInterpreterState_GetDict(PyInterpreterState *interp)

Retorna un diccionario en el que se pueden almacenar datos específicos del intérprete. Si esta función retorna NULL, no se ha producido ninguna excepción y la persona que llama debe suponer que no hay disponible una instrucción específica del intérprete.

Esto no reemplaza a PyModule_GetState(), que las extensiones deben usar para almacenar información de estado específica del intérprete.

Nuevo en la versión 3.8.

PyObject* (*_PyFrameEvalFunction)(PyThreadState *tstate, PyFrameObject *frame, int throwflag)

Tipo de función de evaluación de marcos.

El parámetro throwflag es usado por el método de generadores throw(): si no es cero, maneja la excepción actual.

Distinto en la versión 3.9: La función ahora recibe un parámetro tstate.

_PyFrameEvalFunction _PyInterpreterState_GetEvalFrameFunc(PyInterpreterState *interp)

Obtiene la función de evaluación de marcos.

Consulte PEP 523 [https://www.python.org/dev/peps/pep-0523] «Adición de una API de evaluación de marcos a CPython».

Nuevo en la versión 3.9.

void _PyInterpreterState_SetEvalFrameFunc(PyInterpreterState *interp, _PyFrameEvalFunction eval_frame)

Configura la función de evaluación del marco.

Consulte PEP 523 [https://www.python.org/dev/peps/pep-0523] «Adición de una API de evaluación de marcos a CPython».

Nuevo en la versión 3.9.

PyObject* PyThreadState_GetDict()

Return value: Borrowed reference.

Retorna un diccionario en el que las extensiones pueden almacenar información de estado específica del hilo. Cada extensión debe usar una clave única para almacenar el estado en el diccionario. Está bien llamar a esta función cuando no hay un estado del hilo actual disponible. Si esta función retorna NULL, no se ha producido ninguna excepción y la persona que llama debe asumir que no hay disponible ningún estado del hilo actual.

int PyThreadState_SetAsyncExc(unsigned long id, PyObject *exc)

Asincrónicamente lanza una excepción en un hilo. El argumento id es el id del hilo del hilo de destino; exc es el objeto de excepción que se debe generar. Esta función no roba ninguna referencia a exc. Para evitar el uso indebido ingenuo, debe escribir su propia extensión C para llamar a esto. Debe llamarse con el GIL retenido. Retorna el número de estados de hilo modificados; normalmente es uno, pero será cero si no se encuentra la identificación del hilo. Si exc es NULL, se borra la excepción pendiente (si existe) para el hilo. Esto no lanza excepciones.

Distinto en la versión 3.7: El tipo del parámetro id cambia de long a unsigned long.

void PyEval_AcquireThread(PyThreadState *tstate)

Adquiere el bloqueo global del intérprete y establece el estado actual del hilo en tstate, que no debe ser NULL. El bloqueo debe haber sido creado anteriormente. Si este hilo ya tiene el bloqueo, se produce un deadlock.

Nota

Llamar a esta función desde un hilo cuando finalice el tiempo de ejecución terminará el hilo, incluso si Python no creó el hilo. Puede usar _Py_IsFinalizing() o sys.is_finalizing() para verificar si el intérprete está en proceso de finalización antes de llamar a esta función para evitar una terminación no deseada.

Distinto en la versión 3.8: Actualiza para ser coherente con PyEval_RestoreThread(), Py_END_ALLOW_THREADS(), y PyGILState_Ensure(), y termina el hilo actual si se llama mientras el intérprete está finalizando.

PyEval_RestoreThread() es una función de nivel superior que siempre está disponible (incluso cuando los subprocesos no se han inicializado).

void PyEval_ReleaseThread(PyThreadState *tstate)

Restablece el estado actual del hilo a NULL y libera el bloqueo global del intérprete. El bloqueo debe haberse creado antes y debe estar retenido por el hilo actual. El argumento tstate, que no debe ser NULL, solo se usa para verificar que representa el estado actual del hilo — si no lo es, se informa un error fatal.

PyEval_SaveThread() es una función de nivel superior que siempre está disponible (incluso cuando los hilos no se han inicializado).

void PyEval_AcquireLock()

Adquiera el bloqueo global de intérprete. El bloqueo debe haber sido creado anteriormente. Si este hilo ya tiene el bloqueo, se produce un deadlock.

Obsoleto desde la versión 3.2: Esta función no actualiza el estado actual del hilo. Utilice PyEval_RestoreThread() o PyEval_AcquireThread() en su lugar.

Nota

Llamar a esta función desde un hilo cuando finalice el tiempo de ejecución terminará el hilo, incluso si Python no creó el hilo. Puede usar _Py_IsFinalizing() o sys.is_finalizing() para verificar si el intérprete está en proceso de finalización antes de llamar a esta función para evitar una terminación no deseada.

Distinto en la versión 3.8: Actualiza para ser coherente con PyEval_RestoreThread(), Py_END_ALLOW_THREADS(), y PyGILState_Ensure(), y termina el hilo actual si se llama mientras el intérprete está finalizando.

void PyEval_ReleaseLock()

Libere el bloqueo global del intérprete. El bloqueo debe haber sido creado anteriormente.

Obsoleto desde la versión 3.2: Esta función no actualiza el estado actual del hilo. Utilice PyEval_SaveThread() o PyEval_ReleaseThread() en su lugar.

Soporte de subinterprete

Si bien en la mayoría de los usos, solo incrustará un solo intérprete de Python, hay casos en los que necesita crear varios intérpretes independientes en el mismo proceso y tal vez incluso en el mismo hilo. Los subinterpretes le permiten hacer eso.

El intérprete «principal» es el primero creado cuando se inicializa el tiempo de ejecución. Suele ser el único intérprete de Python en un proceso. A diferencia de los subinterpretes, el intérprete principal tiene responsabilidades globales de proceso únicas, como el manejo de señales. También es responsable de la ejecución durante la inicialización del tiempo de ejecución y generalmente es el intérprete activo durante la finalización del tiempo de ejecución. La función PyInterpreterState_Main() retorna un puntero a su estado.

Puede cambiar entre subinterpretes utilizando la función PyThreadState_Swap(). Puede crearlos y destruirlos utilizando las siguientes funciones:

PyThreadState* Py_NewInterpreter()

Crea un nuevo subinterprete. Este es un entorno (casi) totalmente separado para la ejecución de código Python. En particular, el nuevo intérprete tiene versiones separadas e independientes de todos los módulos importados, incluidos los módulos fundamentales builtins, __main__ y sys. La tabla de módulos cargados (sys.modules) y la ruta de búsqueda del módulo (sys.path) también están separados. El nuevo entorno no tiene variable sys.argv. Tiene nuevos objetos de archivo de flujo de E/S estándar sys.stdin, sys.stdout y sys.stderr (sin embargo, estos se refieren a los mismos descriptores de archivo subyacentes).

El valor de retorno apunta al primer estado del hilo creado en el nuevo subinterprete. Este estado de hilo se realiza en el estado de hilo actual. Tenga en cuenta que no se crea ningún hilo real; vea la discusión de los estados del hilo a continuación. Si la creación del nuevo intérprete no tiene éxito, se retorna NULL; no se establece ninguna excepción, ya que el estado de excepción se almacena en el estado actual del hilo y es posible que no haya un estado actual del hilo. (Al igual que todas las otras funciones de Python/C API, el bloqueo global del intérprete debe mantenerse antes de llamar a esta función y aún se mantiene cuando regresa; sin embargo, a diferencia de la mayoría de las otras funciones de Python/C API, no es necesario que haya un estado del hilo actual en entrada.)

Los módulos de extensión se comparten entre (sub) intérpretes de la siguiente manera:

Para módulos que usan inicialización multifase, por ejemplo PyModule_FromDefAndSpec(), se crea e inicializa un objeto de módulo separado para cada intérprete. Solo las variables estáticas y globales de nivel C se comparten entre estos objetos de módulo.

Para módulos que utilizan inicialización monofásica, por ejemplo PyModule_Create(), la primera vez que se importa una extensión en particular, se inicializa normalmente y una copia (superficial) del diccionario de su módulo se guarda. Cuando otro (sub) intérprete importa la misma extensión, se inicializa un nuevo módulo y se llena con el contenido de esta copia; no se llama a la función init de la extensión. Los objetos en el diccionario del módulo terminan compartidos entre (sub) intérpretes, lo que puede causar un comportamiento no deseado (ver Errores y advertencias (Bugs and caveats) a continuación).

Tenga en cuenta que esto es diferente de lo que sucede cuando se importa una extensión después de que el intérprete se haya reiniciado por completo llamando a Py_FinalizeEx() y Py_Initialize(); en ese caso, la función initmodule de la extensión es llamada nuevamente. Al igual que con la inicialización de múltiples fases, esto significa que solo se comparten variables estáticas y globales de nivel C entre estos módulos.

void Py_EndInterpreter(PyThreadState *tstate)

Destruye el (sub) intérprete representado por el estado del hilo dado. El estado del hilo dado debe ser el estado del hilo actual. Vea la discusión de los estados del hilo a continuación. Cuando la llamada regresa, el estado actual del hilo es NULL. Todos los estados de hilo asociados con este intérprete se destruyen. (El bloqueo global del intérprete debe mantenerse antes de llamar a esta función y aún se mantiene cuando vuelve). Py_FinalizeEx() destruirá todos los subinterpretes que no se hayan destruido explícitamente en ese punto.

Errores y advertencias

Debido a que los subinterpretes (y el intérprete principal) son parte del mismo proceso, el aislamiento entre ellos no es perfecto — por ejemplo, usando operaciones de archivos de bajo nivel como os.close() pueden (accidentalmente o maliciosamente) afectar los archivos abiertos del otro. Debido a la forma en que las extensiones se comparten entre (sub) intérpretes, algunas extensiones pueden no funcionar correctamente; esto es especialmente probable cuando se utiliza la inicialización monofásica o las variables globales (estáticas). Es posible insertar objetos creados en un subinterprete en un espacio de nombres de otro (sub) intérprete; Esto debe evitarse si es posible.

Se debe tener especial cuidado para evitar compartir funciones, métodos, instancias o clases definidas por el usuario entre los subinterpretes, ya que las operaciones de importación ejecutadas por dichos objetos pueden afectar el diccionario (sub-) intérprete incorrecto de los módulos cargados. Es igualmente importante evitar compartir objetos desde los que se pueda acceder a lo anterior.

También tenga en cuenta que la combinación de esta funcionalidad con PyGILState_*() API es delicada, porque estas API suponen una biyección entre los estados de hilo de Python e hilos a nivel del sistema operativo, una suposición rota por la presencia de subinterpretes. Se recomienda encarecidamente que no cambie los subinterpretes entre un par de llamadas coincidentes PyGILState_Ensure() y PyGILState_Release(). Además, las extensiones (como ctypes) que usan estas API para permitir la llamada de código Python desde hilos no creados por Python probablemente se rompan cuando se usan subinterpretes.

Notificaciones asincrónicas

Se proporciona un mecanismo para hacer notificaciones asincrónicas al hilo principal del intérprete. Estas notificaciones toman la forma de un puntero de función y un argumento de puntero nulo.

int Py_AddPendingCall(int (*func)(void *), void *arg)

Programa una función para que se llame desde el hilo principal del intérprete. En caso de éxito, se retorna 0 y se pone en cola func para ser llamado en el hilo principal. En caso de fallo, se retorna -1 sin establecer ninguna excepción.

Cuando se puso en cola con éxito, func será eventualmente invocado desde el hilo principal del intérprete con el argumento arg. Se llamará de forma asincrónica con respecto al código Python que se ejecuta normalmente, pero con ambas condiciones cumplidas:

en un límite bytecode;

con el hilo principal que contiene el global interpreter lock (func, por lo tanto, puede usar la API C completa).

func debe retornar 0 en caso de éxito o -1 en caso de error con una excepción establecida. func no se interrumpirá para realizar otra notificación asíncrona de forma recursiva, pero aún se puede interrumpir para cambiar hilos si se libera el bloqueo global del intérprete.

Esta función no necesita un estado de hilo actual para ejecutarse y no necesita el bloqueo global del intérprete.

Para llamar a esta función en un subinterprete, quien llama debe mantener el GIL. De lo contrario, la función func se puede programar para que se llame desde el intérprete incorrecto.

Advertencia

Esta es una función de bajo nivel, solo útil para casos muy especiales. No hay garantía de que func se llame lo más rápido posible. Si el hilo principal está ocupado ejecutando una llamada al sistema, no se llamará func antes de que vuelva la llamada del sistema. Esta función generalmente no es adecuada para llamar a código Python desde hilos C arbitrarios. En su lugar, use PyGILState API.

Distinto en la versión 3.9: Si esta función se llama en un subinterprete, la función func ahora está programada para ser llamada desde el subinterprete, en lugar de ser llamada desde el intérprete principal. Cada subinterprete ahora tiene su propia lista de llamadas programadas.

Nuevo en la versión 3.1.

Perfilado y Rastreo

El intérprete de Python proporciona soporte de bajo nivel para adjuntar funciones de creación de perfiles y seguimiento de ejecución. Estos se utilizan para herramientas de análisis de perfiles, depuración y cobertura.

Esta interfaz C permite que el código de perfilado o rastreo evite la sobrecarga de llamar a través de objetos invocables a nivel de Python, haciendo una llamada directa a la función C en su lugar. Los atributos esenciales de la instalación no han cambiado; la interfaz permite instalar funciones de rastreo por hilos, y los eventos básicos informados a la función de rastreo son los mismos que se informaron a las funciones de rastreo a nivel de Python en versiones anteriores.

int (*Py_tracefunc)(PyObject *obj, PyFrameObject *frame, int what, PyObject *arg)

El tipo de la función de rastreo registrada usando PyEval_SetProfile() y PyEval_SetTrace(). El primer parámetro es el objeto pasado a la función de registro como obj, frame es el objeto de marco al que pertenece el evento, what es una de las constantes PyTrace_CALL, PyTrace_EXCEPTION , PyTrace_LINE, PyTrace_RETURN, PyTrace_C_CALL, PyTrace_C_EXCEPTION, PyTrace_C_RETURN, o PyTrace_OPCODE, y arg depende de el valor de what:

Valor de what

Significado de arg

PyTrace_CALL

Siempre Py_None.

PyTrace_EXCEPTION

Información de excepción retornada por sys.exc_info().

PyTrace_LINE

Siempre Py_None.

PyTrace_RETURN

Valor retornado al que llama, o NULL si es causado por una excepción.

PyTrace_C_CALL

Objeto función que se llaman.

PyTrace_C_EXCEPTION

Objeto función que se llaman.

PyTrace_C_RETURN

Objeto función que se llaman.

PyTrace_OPCODE

Siempre Py_None.

int PyTrace_CALL

El valor del parámetro what para una función Py_tracefunc cuando se informa una nueva llamada a una función o método, o una nueva entrada en un generador. Tenga en cuenta que la creación del iterador para una función de generador no se informa ya que no hay transferencia de control al código de bytes de Python en la marco correspondiente.

int PyTrace_EXCEPTION

El valor del parámetro what para una función Py_tracefunc cuando se ha producido una excepción. La función de devolución de llamada se llama con este valor para what cuando después de que se procese cualquier bytecode, después de lo cual la excepción se establece dentro del marco que se está ejecutando. El efecto de esto es que a medida que la propagación de la excepción hace que la pila de Python se desenrolle, el retorno de llamada se llama al retornar a cada marco a medida que se propaga la excepción. Solo las funciones de rastreo reciben estos eventos; el perfilador (profiler) no los necesita.

int PyTrace_LINE

El valor pasado como parámetro what a una función Py_tracefunc (pero no una función de creación de perfiles) cuando se informa un evento de número de línea. Puede deshabilitarse para un marco configurando f_trace_lines en 0 en ese marco.

int PyTrace_RETURN

El valor para el parámetro what para Py_tracefunc funciona cuando una llamada está por regresar.

int PyTrace_C_CALL

El valor del parámetro what para Py_tracefunc funciona cuando una función C está a punto de ser invocada.

int PyTrace_C_EXCEPTION

El valor del parámetro what para funciones Py_tracefunc cuando una función C ha lanzado una excepción.

int PyTrace_C_RETURN

El valor del parámetro what para Py_tracefunc funciona cuando una función C ha retornado.

int PyTrace_OPCODE

El valor del parámetro what para funciones Py_tracefunc (pero no funciones de creación de perfiles) cuando un nuevo código de operación está a punto de ejecutarse. Este evento no se emite de forma predeterminada: debe solicitarse explícitamente estableciendo f_trace_opcodes en 1 en el marco.

void PyEval_SetProfile(Py_tracefunc func, PyObject *obj)

Establece la función del generador de perfiles en func. El parámetro obj se pasa a la función como su primer parámetro, y puede ser cualquier objeto de Python o NULL. Si la función de perfilado necesita mantener el estado, el uso de un valor diferente para obj para cada hilo proporciona un lugar conveniente y seguro para guardarlo. Se llama a la función de perfilado para todos los eventos supervisados, excepto PyTrace_LINE PyTrace_OPCODE y PyTrace_EXCEPTION.

La persona que llama debe mantener el GIL.

void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)

Establece la función de rastreo en func. Esto es similar a PyEval_SetProfile(), excepto que la función de rastreo recibe eventos de número de línea y eventos por código de operación, pero no recibe ningún evento relacionado con los objetos de la función C. Cualquier función de rastreo registrada con PyEval_SetTrace() no recibirá PyTrace_C_CALL, PyTrace_C_EXCEPTION o PyTrace_C_RETURN como valor para el parámetro what.

La persona que llama debe mantener el GIL.

Soporte avanzado del depurador

Estas funciones solo están destinadas a ser utilizadas por herramientas de depuración avanzadas.

PyInterpreterState* PyInterpreterState_Head()

Retorna el objeto de estado del intérprete al principio de la lista de todos esos objetos.

PyInterpreterState* PyInterpreterState_Main()

Retorna el objeto de estado del intérprete principal.

PyInterpreterState* PyInterpreterState_Next(PyInterpreterState *interp)

Retorna el siguiente objeto de estado de intérprete después de interp de la lista de todos esos objetos.

PyThreadState * PyInterpreterState_ThreadHead(PyInterpreterState *interp)

Retorna el puntero al primer objeto PyThreadState en la lista de hilos asociados con el intérprete interp.

PyThreadState* PyThreadState_Next(PyThreadState *tstate)

Retorna el siguiente objeto de estado del hilo después de tstate de la lista de todos los objetos que pertenecen al mismo objeto PyInterpreterState.

Soporte de almacenamiento local de hilo

El intérprete de Python proporciona soporte de bajo nivel para el almacenamiento local de hilos (TLS) que envuelve la implementación de TLS nativa subyacente para admitir la API de almacenamiento local de hilos de nivel Python (threading.local). Las API de nivel CPython C son similares a las ofrecidas por pthreads y Windows: use una clave de hilo y funciones para asociar un valor de void* por hilo.

El GIL no necesita ser retenido al llamar a estas funciones; proporcionan su propio bloqueo.

Tenga en cuenta que Python.h no incluye la declaración de las API de TLS, debe incluir pythread.h para usar el almacenamiento local de hilos.

Nota

Ninguna de estas funciones API maneja la administración de memoria en nombre de los valores void*. Debe asignarlos y desasignarlos usted mismo. Si los valores void* son PyObject*, estas funciones tampoco realizan operaciones de conteo de referencias en ellos.

API de almacenamiento específico de hilo (TSS, Thread Specific Storage)

La API de TSS se introduce para reemplazar el uso de la API TLS existente dentro del intérprete de CPython. Esta API utiliza un nuevo tipo Py_tss_t en lugar de int para representar las claves del hilo.

Nuevo en la versión 3.7.

Ver también

«Una nueva C-API para Thread-Local Storage en CPython» (PEP 539 [https://www.python.org/dev/peps/pep-0539])

Py_tss_t

Esta estructura de datos representa el estado de una clave del hilo, cuya definición puede depender de la implementación de TLS subyacente, y tiene un campo interno que representa el estado de inicialización de la clave. No hay miembros públicos en esta estructura.

Cuando Py_LIMITED_API no está definido, la asignación estática de este tipo por Py_tss_NEEDS_INIT está permitida.

Py_tss_NEEDS_INIT

Esta macro se expande al inicializador para variables Py_tss_t. Tenga en cuenta que esta macro no se definirá con Py_LIMITED_API.

Asignación dinámica

Asignación dinámica de Py_tss_t, requerida en los módulos de extensión construidos con Py_LIMITED_API, donde la asignación estática de este tipo no es posible debido a que su implementación es opaca en el momento de la compilación.

Py_tss_t* PyThread_tss_alloc()

Retorna un valor que es el mismo estado que un valor inicializado con Py_tss_NEEDS_INIT, o NULL en caso de falla de asignación dinámica.

void PyThread_tss_free(Py_tss_t *key)

Libera la clave key asignada por PyThread_tss_alloc(), después de llamar por primera vez PyThread_tss_delete() para asegurarse de que los hilos locales asociados no hayan sido asignados. Esto es un no-op si el argumento key es NULL.

Nota

A freed key becomes a dangling pointer. You should reset the key to NULL.

Métodos

El parámetro key de estas funciones no debe ser NULL. Además, los comportamientos de PyThread_tss_set() y PyThread_tss_get() no están definidos si el Py_tss_t dado no ha sido inicializado por PyThread_tss_create().

int PyThread_tss_is_created(Py_tss_t *key)

Retorna un valor distinto de cero si Py_tss_t ha sido inicializado por PyThread_tss_create().

int PyThread_tss_create(Py_tss_t *key)

Retorna un valor cero en la inicialización exitosa de una clave TSS. El comportamiento no está definido si el valor señalado por el argumento key no se inicializa con Py_tss_NEEDS_INIT. Esta función se puede invocar repetidamente en la misma tecla: llamarla a una tecla ya inicializada es un no-op e inmediatamente retorna el éxito.

void PyThread_tss_delete(Py_tss_t *key)

Destruye una clave TSS para olvidar los valores asociados con la clave en todos los hilos y cambie el estado de inicialización de la clave a no inicializado. Una clave destruida se puede inicializar nuevamente mediante PyThread_tss_create(). Esta función se puede invocar repetidamente en la misma llave; llamarla en una llave ya destruida es un no-op.

int PyThread_tss_set(Py_tss_t *key, void *value)

Retorna un valor cero para indicar la asociación exitosa de un valor a void* con una clave TSS en el hilo actual. Cada hilo tiene un mapeo distinto de la clave a un valor void*.

void* PyThread_tss_get(Py_tss_t *key)

Retorna el valor void* asociado con una clave TSS en el hilo actual. Esto retorna NULL si no hay ningún valor asociado con la clave en el hilo actual.

API de almacenamiento local de hilos (TLS, Thread Local Storage)

Obsoleto desde la versión 3.7: Esta API es reemplazada por API de Almacenamiento Específico de Hilos (TSS, por sus significado en inglés *Thread Specific Storage*).

Nota

Esta versión de la API no es compatible con plataformas donde la clave TLS nativa se define de una manera que no se puede transmitir de forma segura a int. En tales plataformas, PyThread_create_key() regresará inmediatamente con un estado de falla, y las otras funciones TLS serán no operativas en tales plataformas.

Debido al problema de compatibilidad mencionado anteriormente, esta versión de la API no debe usarse en código nuevo.

int PyThread_create_key()

void PyThread_delete_key(int key)

int PyThread_set_key_value(int key, void *value)

void* PyThread_get_key_value(int key)

void PyThread_delete_key_value(int key)

void PyThread_ReInitTLS()

Configuración de inicialización de Python

Nuevo en la versión 3.8.

Estructuras:

PyConfig

PyPreConfig

PyStatus

PyWideStringList

Funciones:

PyConfig_Clear()

PyConfig_InitIsolatedConfig()

PyConfig_InitPythonConfig()

PyConfig_Read()

PyConfig_SetArgv()

PyConfig_SetBytesArgv()

PyConfig_SetBytesString()

PyConfig_SetString()

PyConfig_SetWideStringList()

PyPreConfig_InitIsolatedConfig()

PyPreConfig_InitPythonConfig()

PyStatus_Error()

PyStatus_Error()

PyStatus_Error()

PyStatus_IsError()

PyStatus_IsExit()

PyStatus_NoMemory()

PyStatus_Ok()

PyWideStringList_Append()

PyWideStringList_Insert()

Py_ExitStatusException()

Py_InitializeFromConfig()

Py_PreInitialize()

Py_PreInitializeFromArgs()

Py_PreInitializeFromBytesArgs()

Py_RunMain()

Py_GetArgcArgv()

La preconfiguración (tipo PyPreConfig) se almacena en _PyRuntime.preconfig y la configuración (tipo PyConfig) se almacena en PyInterpreterState.config.

Consulte también Inicialización, finalización y subprocesos.

Ver también

PEP 587 [https://www.python.org/dev/peps/pep-0587] «Configuración de inicialización de Python».

PyWideStringList

PyWideStringList

Lista de cadenas de caracteres wchar_t*.

Si length no es cero, items no deben ser NULL y todas las cadenas de caracteres deben ser no NULL.

Métodos:

PyStatus PyWideStringList_Append(PyWideStringList *list, const wchar_t *item)

Agregar item a list.

Python debe estar preinicializado para llamar a esta función.

PyStatus PyWideStringList_Insert(PyWideStringList *list, Py_ssize_t index, const wchar_t *item)

Inserta item en list en index.

Si index es mayor o igual que el largo de list, agrega item a list.

index debe ser mayor o igual que 0.

Python debe estar preinicializado para llamar a esta función.

Campos de estructura:

Py_ssize_t length

Longitud de la lista.

wchar_t** items

Elementos de la lista.

PyStatus

PyStatus

Estructura para almacenar el estado de una función de inicialización: éxito, error o salida.

Para un error, puede almacenar el nombre de la función C que creó el error.

Campos de estructura:

int exitcode

Código de salida El argumento pasó a exit().

const char *err_msg

Mensaje de error.

const char *func

El nombre de la función que creó un error puede ser NULL.

Funciones para crear un estado:

PyStatus PyStatus_Ok(void)

Éxito.

PyStatus PyStatus_Error(const char *err_msg)

Error de inicialización con un mensaje.

PyStatus PyStatus_NoMemory(void)

Error de asignación de memoria (sin memoria).

PyStatus PyStatus_Exit(int exitcode)

Sale de Python con el código de salida especificado.

Funciones para manejar un estado:

int PyStatus_Exception(PyStatus status)

¿Es el estado un error o una salida? Si es verdadero, la excepción debe ser manejada; por ejemplo llamando a Py_ExitStatusException().

int PyStatus_IsError(PyStatus status)

¿Es el resultado un error?

int PyStatus_IsExit(PyStatus status)

¿El resultado es una salida?

void Py_ExitStatusException(PyStatus status)

Llama a exit(exitcode) si status es una salida. Imprime el mensaje de error y sale con un código de salida distinto de cero si status es un error. Solo se debe llamar si PyStatus_Exception(status) no es cero.

Nota

Internamente, Python usa macros que establecen PyStatus.func, mientras que las funciones para crear un estado establecen func en NULL.

Ejemplo:

PyStatus alloc(void **ptr, size_t size)
{
    *ptr = PyMem_RawMalloc(size);
    if (*ptr == NULL) {
        return PyStatus_NoMemory();
    }
    return PyStatus_Ok();
}

int main(int argc, char **argv)
{
    void *ptr;
    PyStatus status = alloc(&ptr, 16);
    if (PyStatus_Exception(status)) {
        Py_ExitStatusException(status);
    }
    PyMem_Free(ptr);
    return 0;
}

PyPreConfig

PyPreConfig

Estructura utilizada para preinicializar Python:

Establece el asignador de memoria de Python

Configure el entorno local LC_CTYPE

Establece el modo UTF-8

Función para inicializar una preconfiguración:

void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)

Inicializa la preconfiguración con Configuración de Python.

void PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)

Inicializa la preconfiguración con Configuración aislada.

Campos de estructura:

int allocator

Nombre del asignador de memoria:

PYMEM_ALLOCATOR_NOT_SET (0): no cambie los asignadores de memoria (use los valores predeterminados)

PYMEM_ALLOCATOR_DEFAULT (1): asignadores de memoria predeterminados

PYMEM_ALLOCATOR_DEBUG (2): asignadores de memoria predeterminados con ganchos de depuración

PYMEM_ALLOCATOR_MALLOC (3): fuerza el uso de malloc()

PYMEM_ALLOCATOR_MALLOC_DEBUG (4): fuerza el uso de malloc() con ganchos de depuración

PYMEM_ALLOCATOR_PYMALLOC (5): Python pymalloc memory allocator

PYMEM_ALLOCATOR_PYMALLOC_DEBUG (6): Python pymalloc memory allocator con ganchos de depuración

PYMEM_ALLOCATOR_PYMALLOC y PYMEM_ALLOCATOR_PYMALLOC_DEBUG no son compatibles si Python está configurado con --with-pymalloc

Ver Administración de memorias.

int configure_locale

¿Establece la configuración regional LC_CTYPE en la configuración regional preferida por el usuario? Si es igual a 0, establece coerce_c_locale y coerce_c_locale_warn en 0.

int coerce_c_locale

Si es igual a 2, coaccione la configuración regional C; si es igual a 1, lea la configuración regional LC_CTYPE para decidir si debe ser forzado.

int coerce_c_locale_warn

Si no es cero, emita una advertencia si la configuración regional C está coaccionada.

int dev_mode

Ver PyConfig.dev_mode.

int isolated

Ver PyConfig.isolated.

int legacy_windows_fs_encoding(Windows only)

Si no es cero, desactive el modo UTF-8, configure la codificación del sistema de archivos Python en mbcs, configure el controlador de errores del sistema de archivos en replace.

Solo disponible en Windows. La macro #ifdef MS_WINDOWS se puede usar para el código específico de Windows.

int parse_argv

Si no es cero, Py_PreInitializeFromArgs() y Py_PreInitializeFromBytesArgs() analizan su argumento argv de la misma manera que Python analiza los argumentos de la línea de comandos: ver Argumentos de línea de comandos.

int use_environment

Ver PyConfig.use_environment.

int utf8_mode

Si no es cero, habilita el modo UTF-8.

Preinicialización con PyPreConfig

Funciones para preinicializar Python:

PyStatus Py_PreInitialize(const PyPreConfig *preconfig)

Preinicializa Python desde la preconfiguración preconfig.

PyStatus Py_PreInitializeFromBytesArgs(const PyPreConfig *preconfig, int argc, char * const *argv)

Preinicializa Python desde la preconfiguración preconfig y argumentos de línea de comando (cadenas de caracteres de bytes).

PyStatus Py_PreInitializeFromArgs(const PyPreConfig *preconfig, int argc, wchar_t * const * argv)

Preinicializa Python desde la preconfiguración preconfig y argumentos de línea de comando (cadenas de caracteres anchas).

La persona que llama es responsable de manejar las excepciones (error o salida) usando PyStatus_Exception() y Py_ExitStatusException().

Para Configuración de Python (PyPreConfig_InitPythonConfig()), si Python se inicializa con argumentos de línea de comando, los argumentos de línea de comando también deben pasarse para preinicializar Python, ya que tienen un efecto en la preconfiguración como codificaciones. Por ejemplo, la opción de línea de comando -X utf8 habilita el modo UTF-8.

PyMem_SetAllocator() se puede llamar después de Py_PreInitialize() y antes Py_InitializeFromConfig() para instalar un asignador de memoria personalizado. Se puede llamar antes Py_PreInitialize() si PyPreConfig.allocator está configurado en PYMEM_ALLOCATOR_NOT_SET.

Las funciones de asignación de memoria de Python como PyMem_RawMalloc() no deben usarse antes de la preinicialización de Python, mientras que llamar directamente a malloc() y free() siempre es seguro. Py_DecodeLocale() no debe llamarse antes de la preinicialización.

Ejemplo usando la preinicialización para habilitar el modo UTF-8:

PyStatus status;
PyPreConfig preconfig;
PyPreConfig_InitPythonConfig(&preconfig);

preconfig.utf8_mode = 1;

status = Py_PreInitialize(&preconfig);
if (PyStatus_Exception(status)) {
    Py_ExitStatusException(status);
}

/* at this point, Python will speak UTF-8 */

Py_Initialize();
/* ... use Python API here ... */
Py_Finalize();

PyConfig

PyConfig

Estructura que contiene la mayoría de los parámetros para configurar Python.

Métodos de estructura:

void PyConfig_InitPythonConfig(PyConfig *config)

Inicializa la configuración con Configuración de Python.

void PyConfig_InitIsolatedConfig(PyConfig *config)

Inicializa la configuración con Configuración aislada.

PyStatus PyConfig_SetString(PyConfig *config, wchar_t * const *config_str, const wchar_t *str)

Copia la cadena de caracteres anchos str en *config_str.

Preinicializa Python si es necesario.

PyStatus PyConfig_SetBytesString(PyConfig *config, wchar_t * const *config_str, const char *str)

Decodifica str usando Py_DecodeLocale() y configure el resultado en *config_str.

Preinicializa Python si es necesario.

PyStatus PyConfig_SetArgv(PyConfig *config, int argc, wchar_t * const *argv)

Establezca argumentos de línea de comando a partir de cadenas de caracteres anchas.

Preinicializa Python si es necesario.

PyStatus PyConfig_SetBytesArgv(PyConfig *config, int argc, char * const *argv)

Establezca argumentos de línea de comando: decodifique bytes usando Py_DecodeLocale().

Preinicializa Python si es necesario.

PyStatus PyConfig_SetWideStringList(PyConfig *config, PyWideStringList *list, Py_ssize_t length, wchar_t **items)

Establece la lista de cadenas de caracteres anchas list a length y items.

Preinicializa Python si es necesario.

PyStatus PyConfig_Read(PyConfig *config)

Lee toda la configuración de Python.

Los campos que ya están inicializados no se modifican.

Preinicializa Python si es necesario.

void PyConfig_Clear(PyConfig *config)

Libera memoria de configuración.

La mayoría de los métodos PyConfig preinicializan Python si es necesario. En ese caso, la configuración de preinicialización de Python se basa en PyConfig. Si los campos de configuración que son comunes con PyPreConfig están ajustados, deben configurarse antes de llamar al método PyConfig:

dev_mode

isolated

parse_argv

use_environment

Además, si se utiliza PyConfig_SetArgv() o PyConfig_SetBytesArgv(), este método debe llamarse primero, antes que otros métodos, ya que la configuración de preinicialización depende de los argumentos de la línea de comandos (si parse_argv no es cero).

Quien llama de estos métodos es responsable de manejar las excepciones (error o salida) usando PyStatus_Exception() y Py_ExitStatusException().

Campos de estructura:

PyWideStringList argv

Argumentos de línea de comando, sys.argv. Consulta parse_argv para analizar argv de la misma manera que Python normal analiza los argumentos de la línea de comandos de Python. Si argv está vacío, se agrega una cadena de caracteres vacía para garantizar que sys.argv siempre exista y nunca esté vacío.

wchar_t* base_exec_prefix

sys.base_exec_prefix.

wchar_t* base_executable

sys._base_executable: __PYVENV_LAUNCHER__ valor de la variable de entorno, o copia de PyConfig.executable.

wchar_t* base_prefix

sys.base_prefix.

wchar_t* platlibdir

sys.platlibdir: nombre del directorio de la biblioteca de la plataforma, establecido en el momento de la configuración por --with-platlibdir, anulable por la variable de entorno PYTHONPLATLIBDIR.

Nuevo en la versión 3.9.

int buffered_stdio

Si es igual a 0, habilite el modo sin búfer, haciendo que las secuencias stdout y stderr no tengan búfer.

stdin siempre se abre en modo de búfer.

int bytes_warning

Si es igual a 1, emita una advertencia cuando compare bytes o bytearray con str, o compare bytes con int. Si es igual o mayor a 2, lanza una excepción BytesWarning.

wchar_t* check_hash_pycs_mode

Controla el comportamiento de validación de los archivos .pyc basados en hash (consulte PEP 552 [https://www.python.org/dev/peps/pep-0552]): con el valor de la opción de línea de comando --check-hash-based-pycs.

Valores válidos: always, never y default.

El valor predeterminado es: default.

int configure_c_stdio

Si no es cero, configure las secuencias estándar C (stdio, stdout, stdout). Por ejemplo, configure su modo en O_BINARY en Windows.

int dev_mode

Si es distinto de cero, habilita Modo de desarrollo de Python.

int dump_refs

Si no es cero, volcar todos los objetos que aún están vivos en la salida.

El macro Py_TRACE_REFS debe ser definido en la construcción.

wchar_t* exec_prefix

sys.exec_prefix.

wchar_t* executable

sys.executable.

int faulthandler

Si no es cero, llama a faulthandler.enable() al inicio.

wchar_t* filesystem_encoding

Codificación del sistema de archivos, sys.getfilesystemencoding().

wchar_t* filesystem_errors

Errores de codificación del sistema de archivos, sys.getfilesystemencodeerrors().

unsigned long hash_seed

int use_hash_seed

Funciones de semillas aleatorias hash.

Si use_hash_seed es cero, se elige una semilla aleatoriamente en Pythonstartup, y hash_seed se ignora.

wchar_t* home

Directorio de inicio de Python.

Inicializado desde valor de variable de entorno PYTHONHOME por defecto.

int import_time

Si no es cero, el tiempo de importación del perfil.

int inspect

Ingresa al modo interactivo después de ejecutar un script o un comando.

int install_signal_handlers

¿Instala manejadores de señal?

int interactive

Modo interactivo.

int isolated

Si es mayor que 0, habilite el modo aislado:

sys.path no contiene ni el directorio del script (calculado a partir de argv[0] o el directorio actual) ni el directorio de paquetes del sitio del usuario.

Python REPL no importa readline ni habilita la configuración predeterminada de readline en mensajes interactivos.

Establece use_environment y user_site_directory en 0.

int legacy_windows_stdio

Si no es cero, usa io.FileIO en lugar de io.WindowsConsoleIO para sys.stdin, sys.stdout y sys.stderr.

Solo disponible en Windows. La macro #ifdef MS_WINDOWS se puede usar para el código específico de Windows.

int malloc_stats

Si no es cero, volcar las estadísticas en Asignador de memoria Python pymalloc en la salida.

La opción se ignora si Python se construye usando --without-pymalloc.

wchar_t* pythonpath_env

Módulo de rutas de búsqueda como una cadena separada por DELIM (os.path.pathsep).

Inicializado desde valor de variable de entorno PYTHONPATH por defecto.

PyWideStringList module_search_paths

int module_search_paths_set

sys.path. Si module_search_paths_set es igual a 0, el module_search_paths es anulado por la función que calcula Configuración de ruta .

int optimization_level

Nivel de optimización de compilación:

0: Optimizador de mirilla (y __debug__ está configurado como True)

1: Elimina las aserciones, establece __debug__ en False

2: Strip docstrings

int parse_argv

Si no es cero, analiza argv de la misma manera que los argumentos regulares de la línea de comandos de Python, y elimine los argumentos de Python de argv: vea Argumentos de línea de comando.

int parser_debug

Si no es cero, activa la salida de depuración del analizador (solo para expertos, dependiendo de las opciones de compilación).

int pathconfig_warnings

Si es igual a 0, suprime las advertencias al calcular Configuración de ruta (solo Unix, Windows no registra ninguna advertencia). De lo contrario, las advertencias se escriben en stderr.

wchar_t* prefix

sys.prefix.

wchar_t* program_name

Nombre del programa Se usa para inicializar executable, y en los primeros mensajes de error.

wchar_t* pycache_prefix

sys.pycache_prefix: prefijo de caché .pyc.

Si NULL, sys.pycache_prefix es establecido a None.

int quiet

Modo silencioso. Por ejemplo, no muestra los mensajes de copyright y versión en modo interactivo.

wchar_t* run_command

Argumento python3 -c COMMAND. Utilizado por Py_RunMain().

wchar_t* run_filename

Argumento python3 FILENAME. Utilizado por Py_RunMain().

wchar_t* run_module

Argumento python3 -m MODULE. Utilizado por Py_RunMain().

int show_ref_count

¿Mostrar el recuento de referencia total en la salida?

Establecido en 1 por la opción de línea de comandos -X showrefcount.

Necesita una compilación de depuración de Python (se debe definir la macro Py_REF_DEBUG).

int site_import

¿Importar el módulo site al inicio?

int skip_source_first_line

¿Saltar la primera línea de la fuente?

wchar_t* stdio_encoding

wchar_t* stdio_errors

Codificación y codificación de errores de sys.stdin, sys.stdout y sys.stderr.

int tracemalloc

Si no es cero, llama a tracemalloc.start() al inicio.

int use_environment

Si es mayor que 0, use variables de entorno.

int user_site_directory

Si no es cero, agrega el directorio del sitio del usuario a sys.path.

int verbose

Si no es cero, habilita el modo detallado.

PyWideStringList warnoptions

sys.warnoptions: opciones del módulo warnings para crear filtros de advertencia: de menor a mayor prioridad.

El módulo warnings agrega sys.warnoptions en el orden inverso: el último elemento PyConfig.warnoptions se convierte en el primer elemento de warnings.filters que es verificado primero (máxima prioridad).

int write_bytecode

Si no es cero, escribe los archivos .pyc.

sys.dont_write_bytecode se inicializa al valor invertido de write_bytecode.

PyWideStringList xoptions

sys._xoptions.

int _use_peg_parser

Habilitar parser PEG? Por defecto: 1.

Establecido en 0 por -X oldparser y PYTHONOLDPARSER.

Vea también PEP 617 [https://www.python.org/dev/peps/pep-0617].

Deprecated since version 3.9, will be removed in version 3.10.

Si parse_argv no es cero, los argumentos argv se analizan de la misma manera que Python analiza los argumentos de línea de comando, y los argumentos de Python se eliminan de argv: ver Argumentos de línea de comando.

Las opciones xoptions se analizan para establecer otras opciones: ver la opción -X.

Distinto en la versión 3.9: El campo show_alloc_count fue removido.

Inicialización con PyConfig

Función para inicializar Python:

PyStatus Py_InitializeFromConfig(const PyConfig *config)

Inicializa Python desde la configuración config.

La persona que llama es responsable de manejar las excepciones (error o salida) usando PyStatus_Exception() y Py_ExitStatusException().

If PyImport_FrozenModules(), PyImport_AppendInittab() or PyImport_ExtendInittab() are used, they must be set or called after Python preinitialization and before the Python initialization. If Python is initialized multiple times, PyImport_AppendInittab() or PyImport_ExtendInittab() must be called before each Python initialization.

Ejemplo de configuración del nombre del programa:

void init_python(void)
{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);

    /* Set the program name. Implicitly preinitialize Python. */
    status = PyConfig_SetString(&config, &config.program_name,
                                L"/path/to/my_program");
    if (PyStatus_Exception(status)) {
        goto fail;
    }

    status = Py_InitializeFromConfig(&config);
    if (PyStatus_Exception(status)) {
        goto fail;
    }
    PyConfig_Clear(&config);
    return;

fail:
    PyConfig_Clear(&config);
    Py_ExitStatusException(status);
}

Ejemplo más completo que modifica la configuración predeterminada, lee la configuración y luego anula algunos parámetros

PyStatus init_python(const char *program_name)
{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);

    /* Set the program name before reading the configuration
       (decode byte string from the locale encoding).

       Implicitly preinitialize Python. */
    status = PyConfig_SetBytesString(&config, &config.program_name,
                                  program_name);
    if (PyStatus_Exception(status)) {
        goto done;
    }

    /* Read all configuration at once */
    status = PyConfig_Read(&config);
    if (PyStatus_Exception(status)) {
        goto done;
    }

    /* Append our custom search path to sys.path */
    status = PyWideStringList_Append(&config.module_search_paths,
                                     L"/path/to/more/modules");
    if (PyStatus_Exception(status)) {
        goto done;
    }

    /* Override executable computed by PyConfig_Read() */
    status = PyConfig_SetString(&config, &config.executable,
                                L"/path/to/my_executable");
    if (PyStatus_Exception(status)) {
        goto done;
    }

    status = Py_InitializeFromConfig(&config);

done:
    PyConfig_Clear(&config);
    return status;
}

Configuración aislada

PyPreConfig_InitIsolatedConfig() y las funciones PyConfig_InitIsolatedConfig() crean una configuración para aislar Python del sistema. Por ejemplo, para incrustar Python en una aplicación.

This configuration ignores global configuration variables, environment variables, command line arguments (PyConfig.argv is not parsed) and user site directory. The C standard streams (ex: stdout) and the LC_CTYPE locale are left unchanged. Signal handlers are not installed.

Los archivos de configuración todavía se usan con esta configuración. Configure Configuración de ruta («campos de salida») para ignorar estos archivos de configuración y evitar la función que calcula la configuración de ruta predeterminada.

Configuración de Python

PyPreConfig_InitPythonConfig() y las funciones PyConfig_InitPythonConfig() crean una configuración para construir un Python personalizado que se comporta como el Python normal.

Las variables de entorno y los argumentos de la línea de comandos se utilizan para configurar Python, mientras que las variables de configuración global se ignoran.

Esta función permite la coerción de configuración regional C (PEP 538 [https://www.python.org/dev/peps/pep-0538]) y el modo UTF-8 (PEP 540 [https://www.python.org/dev/peps/pep-0540]) dependiendo de la configuración regional LC_CTYPE, PYTHONUTF8 y variables de entorno PYTHONCOERCECLOCALE.

Ejemplo de Python personalizado que siempre se ejecuta en modo aislado:

int main(int argc, char **argv)
{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);
    config.isolated = 1;

    /* Decode command line arguments.
       Implicitly preinitialize Python (in isolated mode). */
    status = PyConfig_SetBytesArgv(&config, argc, argv);
    if (PyStatus_Exception(status)) {
        goto fail;
    }

    status = Py_InitializeFromConfig(&config);
    if (PyStatus_Exception(status)) {
        goto fail;
    }
    PyConfig_Clear(&config);

    return Py_RunMain();

fail:
    PyConfig_Clear(&config);
    if (PyStatus_IsExit(status)) {
        return status.exitcode;
    }
    /* Display the error message and exit the process with
       non-zero exit code */
    Py_ExitStatusException(status);
}

Configuración de ruta

PyConfig contiene múltiples campos para la configuración de ruta:

Entradas de configuración de ruta:

PyConfig.home

PyConfig.platlibdir

PyConfig.pathconfig_warnings

PyConfig.program_name

PyConfig.pythonpath_env

directorio de trabajo actual: para obtener rutas absolutas

Variable de entorno PATH para obtener la ruta completa del programa (de PyConfig.program_name)

Variable de entorno __PYVENV_LAUNCHER__

(Solo Windows) Rutas de aplicación en el registro en «SoftwarePythonPythonCoreX.YPythonPath» de HKEY_CURRENT_USER y HKEY_LOCAL_MACHINE (donde X.Y es la versión de Python).

Campos de salida de configuración de ruta:

PyConfig.base_exec_prefix

PyConfig.base_executable

PyConfig.base_prefix

PyConfig.exec_prefix

PyConfig.executable

PyConfig.module_search_paths_set, PyConfig.module_search_paths

PyConfig.prefix

Si no se establece al menos un «campo de salida», Python calcula la configuración de la ruta para completar los campos no definidos. Si module_search_paths_set es igual a 0, module_search_paths se reemplaza y module_search_paths_set se establece en 1.

Es posible ignorar por completo la función que calcula la configuración de ruta predeterminada al establecer explícitamente todos los campos de salida de configuración de ruta enumerados anteriormente. Una cadena de caracteres se considera como un conjunto, incluso si no está vacía. module_search_paths se considera como establecido si module_search_paths_set se establece en 1. En este caso, los campos de entrada de configuración de ruta también se ignoran.

Establezca pathconfig_warnings en 0 para suprimir las advertencias al calcular la configuración de la ruta (solo Unix, Windows no registra ninguna advertencia).

Si base_prefix o los campos base_exec_prefix no están establecidos, heredan su valor de prefix y exec_prefix respectivamente.

Py_RunMain() y Py_Main() modifican sys.path:

Si run_filename está configurado y es un directorio que contiene un script __main__.py, anteponga run_filename a sys.path.

Si isolated es cero:

Si run_module está configurado, anteponga el directorio actual a sys.path. No haga nada si el directorio actual no se puede leer.

Si run_filename está configurado, anteponga el directorio del nombre del archivo a sys.path.

De lo contrario, anteponga una cadena de caracteres vacía a sys.path.

Si site_import no es cero, sys.path puede ser modificado por el módulo site. Si user_site_directory no es cero y el directorio del paquete del sitio del usuario existe, el módulo site agrega el directorio del paquete del sitio del usuario a sys.path.

La configuración de ruta utiliza los siguientes archivos de configuración:

pyvenv.cfg

python._pth (sólo Windows)

pybuilddir.txt (sólo Unix)

La variable de entorno __PYVENV_LAUNCHER__ se usa para establecer PyConfig.base_executable

Py_RunMain()

int Py_RunMain(void)

Ejecuta el comando (PyConfig.run_command), el script (PyConfig.run_filename) o el módulo (PyConfig.run_module) especificado en la línea de comando o en la configuración.

Por defecto y cuando se usa la opción -i, ejecuta el REPL.

Finalmente, finaliza Python y retorna un estado de salida que se puede pasar a la función exit().

Consulte Configuración de Python para ver un ejemplo de Python personalizado que siempre se ejecuta en modo aislado usando Py_RunMain().

Py_GetArgcArgv()

void Py_GetArgcArgv(int *argc, wchar_t ***argv)

Obtiene los argumentos originales de la línea de comandos, antes de que Python los modificara.

API Provisional Privada de Inicialización Multifásica

This section is a private provisional API introducing multi-phase initialization, the core feature of PEP 432 [https://www.python.org/dev/peps/pep-0432]:

Fase de inicialización «Core», «Python mínimo»:

Tipos incorporados;

Excepciones incorporadas;

Módulos incorporados y congelados;

El módulo sys solo se inicializa parcialmente (por ejemplo sys.path aún no existe).

Fase de inicialización «principal», Python está completamente inicializado:

Instala y configura importlib;

Aplique la Configuración de ruta;

Instala manejadores de señal;

Finaliza la inicialización del módulo sys (por ejemplo: crea sys.stdout y sys.path);

Habilita características opcionales como faulthandler y tracemalloc;

Importe el módulo site;

etc.

API provisional privada:

PyConfig._init_main: si se establece en 0, Py_InitializeFromConfig() se detiene en la fase de inicialización «Core».

PyConfig._isolated_interpreter: si no es cero, no permite hilos, subprocesos y bifurcaciones.

PyStatus _Py_InitializeMain(void)

Vaya a la fase de inicialización «Principal», finalice la inicialización de Python.

No se importa ningún módulo durante la fase «Core» y el módulo importlib no está configurado: la Configuración de ruta solo se aplica durante la fase «Principal». Puede permitir personalizar Python en Python para anular o ajustar Configuración de ruta, tal vez instale un importador personalizado sys.meta_path o un enlace de importación, etc.

Puede ser posible calcular Configuración de ruta en Python, después de la fase Core y antes de la fase Main, que es una de las motivaciones PEP 432 [https://www.python.org/dev/peps/pep-0432].

La fase «Núcleo» no está definida correctamente: lo que debería estar y lo que no debería estar disponible en esta fase aún no se ha especificado. La API está marcada como privada y provisional: la API se puede modificar o incluso eliminar en cualquier momento hasta que se diseñe una API pública adecuada.

Ejemplo de ejecución de código Python entre las fases de inicialización «Core» y «Main»:

void init_python(void)
{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);
    config._init_main = 0;

    /* ... customize 'config' configuration ... */

    status = Py_InitializeFromConfig(&config);
    PyConfig_Clear(&config);
    if (PyStatus_Exception(status)) {
        Py_ExitStatusException(status);
    }

    /* Use sys.stderr because sys.stdout is only created
       by _Py_InitializeMain() */
    int res = PyRun_SimpleString(
        "import sys; "
        "print('Run Python code before _Py_InitializeMain', "
               "file=sys.stderr)");
    if (res < 0) {
        exit(1);
    }

    /* ... put more configuration code here ... */

    status = _Py_InitializeMain();
    if (PyStatus_Exception(status)) {
        Py_ExitStatusException(status);
    }
}

Gestión de la memoria

Visión general

La gestión de memoria en Python implica un montón privado que contiene todos los objetos de Python y estructuras de datos. El administrador de memoria de Python garantiza internamente la gestión de este montón privado. El administrador de memoria de Python tiene diferentes componentes que se ocupan de varios aspectos de la gestión dinámica del almacenamiento, como compartir, segmentación, asignación previa o almacenamiento en caché.

En el nivel más bajo, un asignador de memoria sin procesar asegura que haya suficiente espacio en el montón privado para almacenar todos los datos relacionados con Python al interactuar con el administrador de memoria del sistema operativo. Además del asignador de memoria sin procesar, varios asignadores específicos de objeto operan en el mismo montón e implementan políticas de administración de memoria distintas adaptadas a las peculiaridades de cada tipo de objeto. Por ejemplo, los objetos enteros se administran de manera diferente dentro del montón que las cadenas, tuplas o diccionarios porque los enteros implican diferentes requisitos de almacenamiento y compensaciones de velocidad / espacio. El administrador de memoria de Python delega parte del trabajo a los asignadores específicos de objeto, pero asegura que este último opere dentro de los límites del montón privado.

Es importante comprender que la gestión del montón de Python la realiza el propio intérprete y que el usuario no tiene control sobre él, incluso si manipulan regularmente punteros de objetos a bloques de memoria dentro de ese montón. El administrador de memoria de Python realiza la asignación de espacio de almacenamiento dinámico para los objetos de Python y otros búferes internos a pedido a través de las funciones de API de Python/C enumeradas en este documento.

Para evitar daños en la memoria, los escritores de extensiones nunca deberían intentar operar en objetos Python con las funciones exportadas por la biblioteca C: malloc(), calloc(), realloc() y free(). Esto dará como resultado llamadas mixtas entre el asignador de C y el administrador de memoria de Python con consecuencias fatales, ya que implementan diferentes algoritmos y operan en diferentes montones. Sin embargo, uno puede asignar y liberar de forma segura bloques de memoria con el asignador de la biblioteca C para fines individuales, como se muestra en el siguiente ejemplo:

PyObject *res;
char *buf = (char *) malloc(BUFSIZ); /* for I/O */

if (buf == NULL)
    return PyErr_NoMemory();
...Do some I/O operation involving buf...
res = PyBytes_FromString(buf);
free(buf); /* malloc'ed */
return res;

En este ejemplo, la solicitud de memoria para el búfer de E/S es manejada por el asignador de la biblioteca C. El administrador de memoria de Python solo participa en la asignación del objeto de bytes retornado como resultado.

Sin embargo, en la mayoría de las situaciones, se recomienda asignar memoria del montón de Python específicamente porque este último está bajo el control del administrador de memoria de Python. Por ejemplo, esto es necesario cuando el intérprete se amplía con nuevos tipos de objetos escritos en C. Otra razón para usar el montón de Python es el deseo de informar al administrador de memoria de Python sobre las necesidades de memoria del módulo de extensión. Incluso cuando la memoria solicitada se usa exclusivamente para fines internos y altamente específicos, delegar todas las solicitudes de memoria al administrador de memoria de Python hace que el intérprete tenga una imagen más precisa de su huella de memoria en su conjunto. En consecuencia, bajo ciertas circunstancias, el administrador de memoria de Python puede o no desencadenar acciones apropiadas, como recolección de basura, compactación de memoria u otros procedimientos preventivos. Tenga en cuenta que al usar el asignador de la biblioteca C como se muestra en el ejemplo anterior, la memoria asignada para el búfer de E/S escapa completamente al administrador de memoria Python.

Ver también

La variable de entorno PYTHONMALLOC puede usarse para configurar los asignadores de memoria utilizados por Python.

La variable de entorno PYTHONMALLOCSTATS se puede utilizar para imprimir estadísticas de asignador de memoria pymalloc cada vez que se crea un nuevo escenario de objetos pymalloc, y en el apagado.

Interfaz de memoria sin procesar

Los siguientes conjuntos de funciones son envoltorios para el asignador del sistema. Estas funciones son seguras para subprocesos, no es necesario mantener el GIL.

El asignador de memoria sin procesar predeterminado usa las siguientes funciones: malloc(), calloc(), realloc() y free(); llame a malloc(1) (o calloc(1, 1)) cuando solicita cero bytes.

Nuevo en la versión 3.4.

void* PyMem_RawMalloc(size_t n)

Asigna n bytes y retorna un puntero de tipo void* a la memoria asignada, o NULL si la solicitud falla.

Solicitar cero bytes retorna un puntero distinto que no sea NULL si es posible, como si en su lugar se hubiera llamado a PyMem_RawMalloc(1). La memoria no se habrá inicializado de ninguna manera.

void* PyMem_RawCalloc(size_t nelem, size_t elsize)

Asigna nelem elementos cada uno cuyo tamaño en bytes es elsize y retorna un puntero de tipo void* a la memoria asignada, o NULL si la solicitud falla. La memoria se inicializa a ceros.

Solicitar elementos cero o elementos de tamaño cero bytes retorna un puntero distinto NULL si es posible, como si en su lugar se hubiera llamado PyMem_RawCalloc(1, 1).

Nuevo en la versión 3.5.

void* PyMem_RawRealloc(void *p, size_t n)

Cambia el tamaño del bloque de memoria señalado por p a n bytes. Los contenidos no se modificarán al mínimo de los tamaños antiguo y nuevo.

Si p es NULL, la llamada es equivalente a PyMem_RawMalloc(n); de lo contrario, si n es igual a cero, el bloque de memoria cambia de tamaño pero no se libera, y el puntero retornado no es NULL.

A menos que p sea NULL, debe haber sido retornado por una llamada previa a PyMem_RawMalloc(), PyMem_RawRealloc() o PyMem_RawCalloc().

Si la solicitud falla, PyMem_RawRealloc() retorna NULL y p sigue siendo un puntero válido al área de memoria anterior.

void PyMem_RawFree(void *p)

Libera el bloque de memoria al que apunta p, que debe haber sido retornado por una llamada anterior a PyMem_RawMalloc(), PyMem_RawRealloc() o PyMem_RawCalloc(). De lo contrario, o si se ha llamado antes a PyMem_RawFree(p), se produce un comportamiento indefinido.

Si p es NULL, no se realiza ninguna operación.

Interfaz de memoria

Los siguientes conjuntos de funciones, modelados según el estándar ANSI C, pero que especifican el comportamiento cuando se solicitan cero bytes, están disponibles para asignar y liberar memoria del montón de Python.

El asignador de memoria predeterminado usa el asignador de memorya pymalloc.

Advertencia

El GIL debe mantenerse cuando se utilizan estas funciones.

Distinto en la versión 3.6: El asignador predeterminado ahora es pymalloc en lugar del malloc() del sistema.

void* PyMem_Malloc(size_t n)

Asigna n bytes y retorna un puntero de tipo void* a la memoria asignada, o NULL si la solicitud falla.

Solicitar cero bytes retorna un puntero distinto que no sea NULL si es posible, como si en su lugar se hubiera llamado a PyMem_Malloc(1). La memoria no se habrá inicializado de ninguna manera.

void* PyMem_Calloc(size_t nelem, size_t elsize)

Asigna nelem elementos cada uno cuyo tamaño en bytes es elsize y retorna un puntero de tipo void* a la memoria asignada, o NULL si la solicitud falla. La memoria se inicializa a ceros.

Solicitar elementos cero o elementos de tamaño cero bytes retorna un puntero distinto NULL si es posible, como si en su lugar se hubiera llamado PyMem_Calloc(1, 1).

Nuevo en la versión 3.5.

void* PyMem_Realloc(void *p, size_t n)

Cambia el tamaño del bloque de memoria señalado por p a n bytes. Los contenidos no se modificarán al mínimo de los tamaños antiguo y nuevo.

Si p es NULL, la llamada es equivalente a PyMem_Malloc(n); de lo contrario, si n es igual a cero, el bloque de memoria cambia de tamaño pero no se libera, y el puntero retornado no es NULL.

A menos que p sea NULL, debe haber sido retornado por una llamada previa a PyMem_Malloc(), PyMem_Realloc() o PyMem_Calloc().

Si la solicitud falla, PyMem_Realloc() retorna NULL y p sigue siendo un puntero válido al área de memoria anterior.

void PyMem_Free(void *p)

Libera el bloque de memoria señalado por p, que debe haber sido retornado por una llamada anterior a PyMem_Malloc(), PyMem_Realloc() o PyMem_Calloc(). De lo contrario, o si se ha llamado antes a PyMem_Free(p), se produce un comportamiento indefinido.

Si p es NULL, no se realiza ninguna operación.

Las siguientes macros orientadas a tipos se proporcionan por conveniencia. Tenga en cuenta que TYPE se refiere a cualquier tipo de C.

TYPE* PyMem_New(TYPE, size_t n)

Igual que PyMem_Malloc(), pero asigna (n * sizeof(TYPE)) bytes de memoria. Retorna una conversión de puntero a TYPE*. La memoria no se habrá inicializado de ninguna manera.

TYPE* PyMem_Resize(void *p, TYPE, size_t n)

Igual que PyMem_Realloc(), pero el bloque de memoria cambia de tamaño a (n * sizeof(TYPE)) bytes. Retorna una conversión de puntero a TYPE*. Al retornar, p será un puntero a la nueva área de memoria, o NULL en caso de falla.

Esta es una macro de preprocesador C; p siempre se reasigna. Guarde el valor original de p para evitar perder memoria al manejar errores.

void PyMem_Del(void *p)

La misma que PyMem_Free().

Además, se proporcionan los siguientes conjuntos de macros para llamar al asignador de memoria de Python directamente, sin involucrar las funciones de API de C mencionadas anteriormente. Sin embargo, tenga en cuenta que su uso no conserva la compatibilidad binaria entre las versiones de Python y, por lo tanto, está en desuso en los módulos de extensión.

PyMem_MALLOC(size)

PyMem_NEW(type, size)

PyMem_REALLOC(ptr, size)

PyMem_RESIZE(ptr, type, size)

PyMem_FREE(ptr)

PyMem_DEL(ptr)

Asignadores de objetos

Los siguientes conjuntos de funciones, modelados según el estándar ANSI C, pero que especifican el comportamiento cuando se solicitan cero bytes, están disponibles para asignar y liberar memoria del montón de Python.

El asignador predeterminado de objetos usa el asignador de memoria pymalloc.

Advertencia

El GIL debe mantenerse cuando se utilizan estas funciones.

void* PyObject_Malloc(size_t n)

Asigna n bytes y retorna un puntero de tipo void* a la memoria asignada, o NULL si la solicitud falla.

Solicitar cero bytes retorna un puntero distinto que no sea NULL si es posible, como si en su lugar se hubiera llamado a PyObject_Malloc(1). La memoria no se habrá inicializado de ninguna manera.

void* PyObject_Calloc(size_t nelem, size_t elsize)

Asigna nelem elementos cada uno cuyo tamaño en bytes es elsize y retorna un puntero de tipo void* a la memoria asignada, o NULL si la solicitud falla. La memoria se inicializa a ceros.

Solicitar elementos cero o elementos de tamaño cero bytes retorna un puntero distinto NULL si es posible, como si en su lugar se hubiera llamado PyObject_Calloc(1, 1).

Nuevo en la versión 3.5.

void* PyObject_Realloc(void *p, size_t n)

Cambia el tamaño del bloque de memoria señalado por p a n bytes. Los contenidos no se modificarán al mínimo de los tamaños antiguo y nuevo.

Si p es NULL, la llamada es equivalente a PyObject_Malloc(n); de lo contrario, si n es igual a cero, el bloque de memoria cambia de tamaño pero no se libera, y el puntero retornado no es NULL.

A menos que p sea NULL, debe haber sido retornado por una llamada previa a PyObject_Malloc(), PyObject_Realloc() o PyObject_Calloc().

Si la solicitud falla, PyObject_Realloc() retorna NULL y p sigue siendo un puntero válido al área de memoria anterior.

void PyObject_Free(void *p)

Libera el bloque de memoria al que apunta p, que debe haber sido retornado por una llamada anterior a PyObject_Malloc(), PyObject_Realloc() o PyObject_Calloc(). De lo contrario, o si se ha llamado antes a PyObject_Free(p), se produce un comportamiento indefinido.

Si p es NULL, no se realiza ninguna operación.

Asignadores de memoria predeterminados

Asignadores de memoria predeterminados:

Configuración

Nombre

PyMem_RawMalloc

PyMem_Malloc

PyObject_Malloc

Lanzamiento de compilación

"pymalloc"

malloc

malloc + debug

malloc + debug

Compilación de depuración

"pymalloc_debug"

malloc + debug

pymalloc + debug

pymalloc + debug

Lanzamiento de compilación, sin pymalloc

"malloc"

malloc

malloc

malloc

Compilación de depuración, sin pymalloc

"malloc_debug"

malloc + debug

malloc + debug

malloc + debug

Leyenda:

Nombre: valor para variable de entorno PYTHONMALLOC

malloc: asignadores del sistema de la biblioteca C estándar, funciones C: malloc(), calloc(), realloc() y free()

pymalloc: asignador de memoria pymalloc

«+ debug»: con ganchos de depuración instalados por PyMem_SetupDebugHooks()

Personalizar asignadores de memoria

Nuevo en la versión 3.4.

PyMemAllocatorEx

Structure used to describe a memory block allocator. The structure has the following fields:

Campo

Significado

void *ctx

contexto de usuario pasado como primer argumento

void* malloc(void *ctx, size_t size)

asignar un bloque de memoria

void* calloc(void *ctx, size_t nelem, size_t elsize)

asignar un bloque de memoria inicializado con ceros

void* realloc(void *ctx, void *ptr, size_t new_size)

asignar o cambiar el tamaño de un bloque de memoria

void free(void *ctx, void *ptr)

liberar un bloque de memoria

Distinto en la versión 3.5: La estructura PyMemAllocator se renombró a PyMemAllocatorEx y se agregó un nuevo campo calloc.

PyMemAllocatorDomain

Enum se utiliza para identificar un dominio asignador. Dominios:

PYMEM_DOMAIN_RAW

Funciones:

PyMem_RawMalloc()

PyMem_RawRealloc()

PyMem_RawCalloc()

PyMem_RawFree()

PYMEM_DOMAIN_MEM

Funciones:

PyMem_Malloc(),

PyMem_Realloc()

PyMem_Calloc()

PyMem_Free()

PYMEM_DOMAIN_OBJ

Funciones:

PyObject_Malloc()

PyObject_Realloc()

PyObject_Calloc()

PyObject_Free()

void PyMem_GetAllocator(PyMemAllocatorDomain domain, PyMemAllocatorEx *allocator)

Obtenga el asignador de bloque de memoria del dominio especificado.

void PyMem_SetAllocator(PyMemAllocatorDomain domain, PyMemAllocatorEx *allocator)

Establece el asignador de bloque de memoria del dominio especificado.

El nuevo asignador debe retornar un puntero distinto NULL al solicitar cero bytes.

Para el dominio PYMEM_DOMAIN_RAW, el asignador debe ser seguro para subprocesos: el GIL no se mantiene cuando se llama al asignador.

Si el nuevo asignador no es un enlace (no llama al asignador anterior), se debe llamar a la función PyMem_SetupDebugHooks() para reinstalar los enlaces de depuración en la parte superior del nuevo asignador.

void PyMem_SetupDebugHooks(void)

Configurar ganchos para detectar errores en las funciones del asignador de memoria de Python.

La memoria recién asignada se llena con el byte 0xCD (CLEANBYTE), la memoria liberada se llena con el byte 0xDD (DEADBYTE). Los bloques de memoria están rodeados por «bytes prohibidos» (FORBIDDENBYTE: byte 0xFD).

Verificaciones de tiempo de ejecución:

Detecte violaciones de API, por ejemplo: PyObject_Free() llamado en un búfer asignado por PyMem_Malloc()

Detectar escritura antes del inicio del búfer (desbordamiento del búfer)

Detectar escritura después del final del búfer (desbordamiento del búfer)

Comprueba que GIL se mantiene cuando las funciones del asignador de PYMEM_DOMAIN_OBJ (ej: PyObject_Malloc()) y dominios PYMEM_DOMAIN_MEM (por ejemplo: PyMem_Malloc()) se llaman

En caso de error, los enlaces de depuración usan el módulo tracemalloc para obtener el rastreo donde se asignó un bloque de memoria. El rastreo solo se muestra si tracemalloc rastrea las asignaciones de memoria de Python y se rastrea el bloque de memoria.

Estos enlaces son instalado por defecto si Python se compila en modo de depuración. La variable de entorno PYTHONMALLOC puede usarse para instalar enlaces de depuración en un Python compilado en modo de lanzamiento.

Distinto en la versión 3.6: Esta función ahora también funciona en Python compilado en modo de lanzamiento. En caso de error, los enlaces de depuración ahora usan tracemalloc para obtener el rastreo donde se asignó un bloque de memoria. Los enlaces de depuración ahora también verifican si el GIL se mantiene cuando se llaman a las funciones de PYMEM_DOMAIN_OBJ y dominios PYMEM_DOMAIN_MEM.

Distinto en la versión 3.8: Los patrones de bytes 0xCB (CLEANBYTE), 0xDB (DEADBYTE) y 0xFB (FORBIDDENBYTE) han sido reemplazados por 0xCD, 0xDD y 0xFD para usar los mismos valores que la depuración CRT de Windows malloc() y free().

El asignador pymalloc

Python tiene un asignador pymalloc optimizado para objetos pequeños (más pequeños o iguales a 512 bytes) con una vida útil corta. Utiliza asignaciones de memoria llamadas «arenas» con un tamaño fijo de 256 KiB. Vuelve a PyMem_RawMalloc() y PyMem_RawRealloc() para asignaciones de más de 512 bytes.

pymalloc es el asignador por defecto de PYMEM_DOMAIN_MEM (por ejemplo: PyMem_Malloc()) y PYMEM_DOMAIN_OBJ (por ejemplo: PyObject_Malloc()) dominios.

El asignador de arena utiliza las siguientes funciones:

VirtualAlloc() y VirtualFree() en Windows,

mmap() y munmap() si está disponible,

malloc() y free() en caso contrario.

Personalizar asignador de arena de pymalloc

Nuevo en la versión 3.4.

PyObjectArenaAllocator

Estructura utilizada para describir un asignador de arena. La estructura tiene tres campos:

Campo

Significado

void *ctx

contexto de usuario pasado como primer argumento

void* alloc(void *ctx, size_t size)

asignar una arena de bytes de tamaño

void free(void *ctx, void *ptr, size_t size)

liberar la arena

void PyObject_GetArenaAllocator(PyObjectArenaAllocator *allocator)

Consigue el asignador de arena.

void PyObject_SetArenaAllocator(PyObjectArenaAllocator *allocator)

Establecer el asignador de arena.

tracemalloc C API

Nuevo en la versión 3.7.

int PyTraceMalloc_Track(unsigned int domain, uintptr_t ptr, size_t size)

Rastree un bloque de memoria asignado en el módulo tracemalloc.

Retorna 0 en caso de éxito, retorna -1 en caso de error (no se pudo asignar memoria para almacenar la traza). Retorna -2 si tracemalloc está deshabilitado.

Si el bloque de memoria ya está rastreado, actualice el rastreo existente.

int PyTraceMalloc_Untrack(unsigned int domain, uintptr_t ptr)

Descomprima un bloque de memoria asignado en el módulo tracemalloc. No haga nada si el bloque no fue rastreado.

Retorna -2 si tracemalloc está deshabilitado; de lo contrario, retorna 0.

Ejemplos

Aquí está el ejemplo de la sección Visión general, reescrito para que el búfer de E/S se asigne desde el montón de Python utilizando el primer conjunto de funciones:

PyObject *res;
char *buf = (char *) PyMem_Malloc(BUFSIZ); /* for I/O */

if (buf == NULL)
    return PyErr_NoMemory();
/* ...Do some I/O operation involving buf... */
res = PyBytes_FromString(buf);
PyMem_Free(buf); /* allocated with PyMem_Malloc */
return res;

El mismo código que utiliza el conjunto de funciones orientado a tipos:

PyObject *res;
char *buf = PyMem_New(char, BUFSIZ); /* for I/O */

if (buf == NULL)
    return PyErr_NoMemory();
/* ...Do some I/O operation involving buf... */
res = PyBytes_FromString(buf);
PyMem_Del(buf); /* allocated with PyMem_New */
return res;

Tenga en cuenta que en los dos ejemplos anteriores, el búfer siempre se manipula a través de funciones que pertenecen al mismo conjunto. De hecho, es necesario usar la misma familia de API de memoria para un bloque de memoria dado, de modo que el riesgo de mezclar diferentes asignadores se reduzca al mínimo. La siguiente secuencia de código contiene dos errores, uno de los cuales está etiquetado como fatal porque mezcla dos asignadores diferentes que operan en montones diferentes.:

char *buf1 = PyMem_New(char, BUFSIZ);
char *buf2 = (char *) malloc(BUFSIZ);
char *buf3 = (char *) PyMem_Malloc(BUFSIZ);
...
PyMem_Del(buf3);  /* Wrong -- should be PyMem_Free() */
free(buf2);       /* Right -- allocated via malloc() */
free(buf1);       /* Fatal -- should be PyMem_Del()  */

Además de las funciones destinadas a manejar bloques de memoria sin procesar del montón de Python, los objetos en Python se asignan y liberan con PyObject_New(), PyObject_NewVar() y PyObject_Del() .

Esto se explicará en el próximo capítulo sobre cómo definir e implementar nuevos tipos de objetos en C.

Soporte de implementación de objetos

Este capítulo describe las funciones, los tipos y las macros utilizados al definir nuevos tipos de objetos.

Asignación de objetos en el montículo

Estructuras de objetos comunes

Tipos objeto base y macros

Implementando funciones y métodos

Acceder a atributos de tipos de extensión

Objetos Tipo

Referencia rápida

«ranuras tp» (tp slots)

sub-ranuras (sub-slots)

ranura de typedefs

Definición de PyTypeObject

Ranuras (Slots) PyObject

Ranuras PyVarObject

Ranuras PyTypeObject

Tipos Montículos (Heap Types)

Estructuras de Objetos de Números

Estructuras de Objetos Mapeo

Estructuras de objetos secuencia

Estructuras de Objetos Búfer

Estructuras de objetos asíncronos

Tipo Ranura typedefs

Ejemplos

Apoyo a la recolección de basura cíclica

Asignación de objetos en el montículo

PyObject* _PyObject_New(PyTypeObject *type)

Return value: New reference.

PyVarObject* _PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)

Return value: New reference.

PyObject* PyObject_Init(PyObject *op, PyTypeObject *type)

Return value: Borrowed reference.

Inicializa un objeto op recientemente asignado con su tipo y referencia inicial. Retorna el objeto inicializado. Si type indica que el objeto participa en el detector de basura cíclico, se agrega al conjunto de objetos observados del detector. Otros campos del objeto no se ven afectados.

PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)

Return value: Borrowed reference.

Esto hace todo lo que PyObject_Init() hace, y también inicializa la información de longitud para un objeto de tamaño variable.

TYPE* PyObject_New(TYPE, PyTypeObject *type)

Return value: New reference.

Asigna un nuevo objeto Python usando el tipo de estructura de C TYPE y el objeto tipo Python type. Los campos no definidos por el encabezado del objeto Python no se inicializan;el conteo de referencias del objeto será uno. El tamaño de la asignación de memoria se determina a partir del campo tp_basicsize del tipo de objeto.

TYPE* PyObject_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)

Return value: New reference.

Asigna un nuevo objeto Python usando el tipo de estructura de C TYPE y el objeto tipo Python type. Los campos no definidos por el encabezado del objeto Python no se inicializan. La memoria asignada permite los campos de la estructura TYPE más los campos size del tamaño dado por el campo tp_itemsize de type. Esto es útil para implementar objetos como tuplas, que pueden determinar su tamaño en el momento de la construcción. Incrustar el arreglo de campos en la misma asignación disminuye el número de asignaciones, mejorando la eficiencia de la gestión de memoria.

void PyObject_Del(void *op)

Libera memoria asignada a un objeto usando PyObject_New() o PyObject_NewVar(). Esto normalmente se llama desde el manejador tp_dealloc especificado en el tipo de objeto. No se debe acceder a los campos del objeto después de esta llamada, ya que la memoria ya no es un objeto Python válido.

PyObject _Py_NoneStruct

Objeto que es visible en Python como None. Esto solo se debe acceder utilizando el macro Py_None, que se evalúa como un puntero a este objeto.

Ver también

PyModule_Create()

Para asignar y crear módulos de extensión.

Estructuras de objetos comunes

Hay un gran número de estructuras que se utilizan en la definición de los tipos de objetos de Python. Esta sección describe estas estructuras y la forma en que se utilizan.

Tipos objeto base y macros

En última instancia, todos los objetos de Python comparten un pequeño número de campos en el comienzo de la representación del objeto en la memoria. Estos están representados por la PyObject y PyVarObject,que se definen, a su vez, por las expansiones de algunos macros también se utilizan, ya sea directa o indirectamente, en la definición de todos otros objetos de Python.

PyObject

Todos los tipos de objetos son extensiones de este tipo. Este es un tipo que contiene la información que Python necesita para tratar un puntero a un objeto como un objeto. En una construcción «release» normal, que contiene solo contador de referencia del objeto y un puntero al objeto de tipo correspondiente. En realidad nada es declarado como un PyObject, pero cada puntero a un objeto de Python se puede convertir en una PyObject*. El acceso a los miembros debe hacerse mediante el uso de las macros Py_REFCNT y Py_TYPE.

PyVarObject

Esta es una extensión de PyObject que se suma el campo ob_size. Esto sólo se utiliza para objetos que tienen cierta noción de longitud (length). Este tipo no suele aparecer en la API Python/C. El acceso a los miembros debe hacerse mediante el uso de las macros Py_REFCNT, Py_TYPE, y Py_SIZE.

PyObject_HEAD

Esta es una macro utilizado cuando se declara nuevos tipos que representan objetos sin una longitud variable. La macro PyObject_HEAD se expande a:

PyObject ob_base;

Consulte la documentación de PyObject en secciones anteriores.

PyObject_VAR_HEAD

Esta es una macro utilizado cuando se declara nuevos tipos que representan objetos con una longitud que varía de una instancia a otra instancia. La macro PyObject_VAR_HEAD se expande a:

PyVarObject ob_base;

Consulte la documentación de PyVarObject anteriormente.

Py_TYPE(o)

Esta macro se utiliza para acceder al miembro ob_type de un objeto Python. Se expande a:

(((PyObject*)(o))->ob_type)

int Py_IS_TYPE(PyObject *o, PyTypeObject *type)

Retorna un valor distinto de cero si el objeto o tipo es type. Retorna cero en caso contrario. Equivalente a: Py_TYPE(o) == type.

Nuevo en la versión 3.9.

void Py_SET_TYPE(PyObject *o, PyTypeObject *type)

Establece el tipo del objeto o a type.

Nuevo en la versión 3.9.

Py_REFCNT(o)

Esta macro se utiliza para acceder al miembro ob_refcnt de un objeto Python. Se expande a:

(((PyObject*)(o))->ob_refcnt)

void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt)

Establece el conteo de referencia del objeto o a refcnt.

Nuevo en la versión 3.9.

Py_SIZE(o)

Esta macro se utiliza para acceder al miembro ob_size de un objeto Python. Se expande a:

(((PyVarObject*)(o))->ob_size)

void Py_SET_SIZE(PyVarObject *o, Py_ssize_t size)

Establece el tamaño del objeto o a size.

Nuevo en la versión 3.9.

PyObject_HEAD_INIT(type)

Esta es una macro que se expande para valores de inicialización para un nuevo tipo PyObject. Esta macro expande:

_PyObject_EXTRA_INIT
1, type,

PyVarObject_HEAD_INIT(type, size)

Esta es una macro que se expande para valores de inicialización para un nuevo tipo PyVarObject, incluyendo el campo ob_size. Esta macro se expande a:

_PyObject_EXTRA_INIT
1, type, size,

Implementando funciones y métodos

PyCFunction

Tipo de las funciones usadas para implementar la mayoría de invocables Python en C. Funciones de este tipo toman dos parámetros PyObject* y retorna un valor de ese tipo. Si el valor de retorno es NULL, una excepción fue establecida. Si no es NULL, el valor retornado se interpreta como el valor de retorno de la función que se expone en Python. La función debe retornar una nueva referencia.

La firma de la función es:

PyObject *PyCFunction(PyObject *self,
                      PyObject *args);

PyCFunctionWithKeywords

Tipo de las funciones que se utilizan para implementar invocables Python en C con la firma METH_VARARGS | METH_KEYWORDS. La firma de la función es:

PyObject *PyCFunctionWithKeywords(PyObject *self,
                                  PyObject *args,
                                  PyObject *kwargs);

_PyCFunctionFast

Tipo de las funciones que se utilizan para implementar invocables Python en C con la firma METH_FASTCALL. La firma de la función es:

PyObject *_PyCFunctionFast(PyObject *self,
                           PyObject *const *args,
                           Py_ssize_t nargs);

_PyCFunctionFastWithKeywords

Tipo de las funciones que se utilizan para implementar invocables Python en C con la firma METH_FASTCALL | METH_KEYWORDS. La firma de la función es:

PyObject *_PyCFunctionFastWithKeywords(PyObject *self,
                                       PyObject *const *args,
                                       Py_ssize_t nargs,
                                       PyObject *kwnames);

PyCMethod

Tipo de las funciones que se utilizan para implementar invocables Python en C con la firma METH_METHOD | METH_FASTCALL | METH_KEYWORDS. La firma de la función es:

PyObject *PyCMethod(PyObject *self,
                    PyTypeObject *defining_class,
                    PyObject *const *args,
                    Py_ssize_t nargs,
                    PyObject *kwnames)

Nuevo en la versión 3.9.

PyMethodDef

Estructura utiliza para describir un método de un tipo de extensión. Esta estructura tiene cuatro campos:

Campo

Tipo C

Significado

ml_name

const char *

nombre del método

ml_meth

PyCFunction

puntero a la implementación en C

ml_flags

int

flag bits que indican cómo debe ser construida la llamada

ml_doc

const char *

puntos a los contenidos del docstring

El ml_meth es un puntero de función C. Las funciones pueden ser de diferentes tipos, pero siempre retornan PyObject*. Si la función no es la de PyCFunction, el compilador requiere una conversión de tipo en la tabla de métodos. A pesar de que PyCFunction define el primer parámetro como PyObject*, es común que la implementación del método utiliza el tipo específico C del objecto self.

El campo ml_flags es un campo de bits que puede incluir las siguientes flags. Las flags individuales indican o bien una convención de llamada o una convención vinculante.

Existen estas convenciones de llamada:

METH_VARARGS

Esta es la convención de llamada típica, donde los métodos tienen el tipo PyCFunction. La función espera dos valores PyObject*. El primero es objeto self para los métodos; para las funciones del módulo, que es el objeto módulo. El segundo parámetro (a menudo llamado args) es un objeto tupla que representa todos los argumentos. Este parámetro se procesa típicamente usando PyArg_ParseTuple() o PyArg_UnpackTuple().

METH_VARARGS | METH_KEYWORDS

Los métodos con estas flags deben ser del tipo PyCFunctionWithKeywords. La función espera tres parámetros: self, args, kwargs donde kwargs es un diccionario de todos los argumentos de palabras clave o, posiblemente, NULL si no hay argumentos de palabra clave. Los parámetros se procesan típicamente usando PyArg_ParseTupleAndKeywords().

METH_FASTCALL

Convención de llamando rápido que soporta sólo argumentos posicionales. Los métodos tienen el tipo _PyCFunctionFast. El primer parámetro es self, el segundo parámetro es un arreglo C de valores PyObject* que indican los argumentos y el tercer parámetro es el número de argumentos (la longitud del arreglo).

Esto no es parte de la API limitada.

Nuevo en la versión 3.7.

METH_FASTCALL | METH_KEYWORDS

Extensión de METH_FASTCALL que admite también argumentos de palabra clave, con los métodos de tipo _PyCFunctionFastWithKeywords. argumentos de palabra clave se transmiten de la misma manera como en el vectorcall protocol: hay un cuarto parámetro PyObject* adicional que es una tupla que representa los nombres de los argumentos de palabra clave o posiblemente NULL si no hay palabras clave. Los valores de los argumentos de palabras clave se almacenan en el arreglo args, después de los argumentos posicionales.

Esto no es parte de la API limitada.

Nuevo en la versión 3.7.

METH_METHOD | METH_FASTCALL | METH_KEYWORDS

Extensión de METH_FASTCALL | METH_KEYWORDS que admite la clase definitoria, es decir, la clase que contiene el método en cuestión. La clase definitoria podría ser una superclase de Py_TYPE(self).

El método debe ser de tipo PyCMethod, lo mismo que para METH_FASTCALL | METH_KEYWORDS con el argumento defining_clase añadido después de self.

Nuevo en la versión 3.9.

METH_NOARGS

Métodos sin parámetros no tienen que comprobar si los argumentos se dan si están registrados con el flag METH_NOARGS. Tienen que ser de tipo PyCFunction. El primer parámetro normalmente se denomina self y llevará a cabo una referencia a la instancia módulo u objeto. En todos los casos el segundo parámetro será NULL.

METH_O

Los métodos con un solo argumento objeto pueden ser listados con el flag METH_O, en lugar de invocar PyArg_ParseTuple() con un argumento "O". Tienen el tipo PyCFunction, con el parámetro self, y un parámetro PyObject* que representa el único argumento.

Estas dos constantes no se utilizan para indicar la convención de llamada si no la vinculación cuando su usan con métodos de las clases. Estos no se pueden usar para funciones definidas para módulos. A lo sumo uno de estos flags puede establecerse en un método dado.

METH_CLASS

Al método se le pasará el objeto tipo como primer parámetro, en lugar de una instancia del tipo. Esto se utiliza para crear métodos de clase (class methods), similar a lo que se crea cuando se utiliza la función classmethod() incorporada.

METH_STATIC

El método pasará NULL como el primer parámetro en lugar de una instancia del tipo. Esto se utiliza para crear métodos estáticos (static methods), similar a lo que se crea cuando se utiliza la función staticmethod() incorporada.

En otros controles constantes dependiendo si se carga un método en su lugar (in place) de otra definición con el mismo nombre del método.

METH_COEXIST

El método se cargará en lugar de las definiciones existentes. Sin METH_COEXIST, el comportamiento predeterminado es saltarse las definiciones repetidas. Desde envolturas de ranura se cargan antes de la tabla de métodos, la existencia de una ranura sq_contains, por ejemplo, generaría un método envuelto llamado __contains__() e impediría la carga de una PyCFunction correspondiente con el mismo nombre. Con el flag definido, la PyCFunction se cargará en lugar del objeto envoltorio y coexistirá con la ranura. Esto es útil porque las llamadas a PyCFunctions se optimizan más que las llamadas a objetos envolvente.

Acceder a atributos de tipos de extensión

PyMemberDef

Estructura que describe un atributo de un tipo que corresponde a un miembro de la estructura de C. Sus campos son:

Campo

Tipo C

Significado

name

const char *

nombre del miembro

type

int

el tipo de miembro en la estructura de C

offset

Py_ssize_t

el desplazamiento en bytes que el miembro se encuentra en la estructura de objetos tipo

flags

int

flags bits que indican si el campo debe ser de sólo lectura o de escritura

doc

const char *

puntos a los contenidos del docstring

type puede ser uno de muchos macros T_ correspondientes a diversos tipos C. Cuando se accede al miembro en Python, será convertida al tipo Python equivalente.

Nombre de la macro

Tipo C

T_SHORT

short

T_INT

int

T_LONG

long

T_FLOAT

float

T_DOUBLE

double

T_STRING

const char *

T_OBJECT

PyObject *

T_OBJECT_EX

PyObject *

T_CHAR

char

T_BYTE

char

T_UBYTE

unsigned char

T_UINT

unsigned int

T_USHORT

unsigned short

T_ULONG

unsigned long

T_BOOL

char

T_LONGLONG

long long

T_ULONGLONG

unsigned long long

T_PYSSIZET

Py_ssize_t

T_OBJECT y T_OBJECT_EX se diferencian en que T_OBJECT retorna None si el miembro es NULL y T_OBJECT_EX lanza un AttributeError. Trate de usar T_OBJECT_EX sobre T_OBJECT porque T_OBJECT_EX maneja el uso de la declaración del en ese atributo más correctamente que T_OBJECT.

flags puede ser 0 para el acceso de escritura y lectura o READONLY para el acceso de sólo lectura. El uso de T_STRING para type implica READONLY. Los datos T_STRING se interpretan como UTF-8. Sólo se pueden eliminar T_OBJECT y miembros T_OBJECT_EX. (Se establecen a NULL).

Los tipos asignados al heap (creados usando PyType_FromSpec() o similar), PyMemberDef pueden contener definiciones para los miembros especiales __dictoffset__, __weaklistoffset__ y __vectorcalloffset__, correspondientes a tp_dictoffset, tp_weaklistoffset y tp_vectorcall_offset en objetos de tipo. Estos deben definirse con T_PYSSIZET y READONLY, por ejemplo:

static PyMemberDef spam_type_members[] = {
    {"__dictoffset__", T_PYSSIZET, offsetof(Spam_object, dict), READONLY},
    {NULL}  /* Sentinel */
};

PyObject* PyMember_GetOne(const char *obj_addr, struct PyMemberDef *m)

Get an attribute belonging to the object at address obj_addr. The attribute is described by PyMemberDef m. Returns NULL on error.

int PyMember_SetOne(char *obj_addr, struct PyMemberDef *m, PyObject *o)

Set an attribute belonging to the object at address obj_addr to object o. The attribute to set is described by PyMemberDef m. Returns 0 if successful and a negative value on failure.

PyGetSetDef

Estructura para definir el acceso para un tipo como el de una propiedad. Véase también la descripción de la ranura PyTypeObject.tp_getset.

Campo

Tipo C

Significado

nombre

const char *

Nombre del atributo

get

getter

C function to get the attribute

set

setter

función opcional C para establecer o eliminar el atributo, si se omite el atributo es de sólo lectura

doc

const char *

docstring opcional

clausura (closure)

void *

puntero de función opcional, proporcionar datos adicionales para getter y setter

La función get toma un parámetro PyObject* (la instancia) y un puntero de función (el closure asociado):

typedef PyObject *(*getter)(PyObject *, void *);

Debe retornar una nueva referencia en caso de éxito o NULL con una excepción establecida en caso de error.

Las funciones set toman dos parámetros PyObject* (la instancia y el valor a ser establecido) y un puntero de función (el closure asociado):

typedef int (*setter)(PyObject *, PyObject *, void *);

En caso de que el atributo deba suprimirse el segundo parámetro es NULL. Debe retornar 0 en caso de éxito o -1 con una excepción explícita en caso de fallo.

Objetos Tipo

Quizás una de las estructuras más importantes del sistema de objetos Python es la estructura que define un nuevo tipo: la estructura PyTypeObject. Los objetos tipo se pueden manejar utilizando cualquiera de las funciones PyObject_*() o PyType_*(), pero no ofrecen mucho que sea interesante para la mayoría de las aplicaciones de Python. Estos objetos son fundamentales para el comportamiento de los objetos, por lo que son muy importantes para el propio intérprete y para cualquier módulo de extensión que implemente nuevos tipos.

Los objetos de tipo son bastante grandes en comparación con la mayoría de los tipos estándar. La razón del tamaño es que cada objeto de tipo almacena una gran cantidad de valores, principalmente punteros de función C, cada uno de los cuales implementa una pequeña parte de la funcionalidad del tipo. Los campos del objeto tipo se examinan en detalle en esta sección. Los campos se describirán en el orden en que aparecen en la estructura.

Además de la siguiente referencia rápida, la sección Ejemplos proporciona una visión rápida del significado y uso de PyTypeObject.

Referencia rápida

«ranuras tp» (tp slots)

Ranura PyTypeObject 1

Type

métodos/atributos especiales

Información 2

O

T

D

I

<R> tp_name

const char *

__name__

X

X

tp_basicsize

Py_ssize_t

X

X

X

tp_itemsize

Py_ssize_t

X

X

tp_dealloc

destructor

X

X

X

tp_vectorcall_offset

Py_ssize_t

X

X

(tp_getattr)

getattrfunc

__getattribute__, __getattr__

G

(tp_setattr)

setattrfunc

__setattr__, __delattr__

G

tp_as_async

PyAsyncMethods *

sub-ranuras (sub-slots)

%

tp_repr

reprfunc

__repr__

X

X

X

tp_as_number

PyNumberMethods *

sub-ranuras (sub-slots)

%

tp_as_sequence

PySequenceMethods *

sub-ranuras (sub-slots)

%

tp_as_mapping

PyMappingMethods *

sub-ranuras (sub-slots)

%

tp_hash

hashfunc

__hash__

X

G

tp_call

ternaryfunc

__call__

X

X

tp_str

reprfunc

__str__

X

X

tp_getattro

getattrofunc

__getattribute__, __getattr__

X

X

G

tp_setattro

setattrofunc

__setattr__, __delattr__

X

X

G

tp_as_buffer

PyBufferProcs *

%

tp_flags

unsigned long

X

X

?

tp_doc

const char *

__doc__

X

X

tp_traverse

traverseproc

X

G

tp_clear

inquiry

X

G

tp_richcompare

richcmpfunc

__lt__, __le__, __eq__, __ne__, __gt__, __ge__

X

G

tp_weaklistoffset

Py_ssize_t

X

?

tp_iter

getiterfunc

__iter__

X

tp_iternext

iternextfunc

__next__

X

tp_methods

PyMethodDef []

X

X

tp_members

PyMemberDef []

X

tp_getset

PyGetSetDef []

X

X

tp_base

PyTypeObject *

__base__

X

tp_dict

PyObject *

__dict__

?

tp_descr_get

descrgetfunc

__get__

X

tp_descr_set

descrsetfunc

__set__, __delete__

X

tp_dictoffset

Py_ssize_t

X

?

tp_init

initproc

__init__

X

X

X

tp_alloc

allocfunc

X

?

?

tp_new

newfunc

__new__

X

X

?

?

tp_free

freefunc

X

X

?

?

tp_is_gc

inquiry

X

X

<tp_bases>

PyObject *

__bases__

~

<tp_mro>

PyObject *

__mro__

~

[tp_cache]

PyObject *

[tp_subclasses]

PyObject *

__subclasses__

[tp_weaklist]

PyObject *

(tp_del)

destructor

[tp_version_tag]

unsigned int

tp_finalize

destructor

__del__

X

tp_vectorcall

vectorcallfunc

1

Un nombre de ranura entre paréntesis indica que está (efectivamente) en desuso. Los nombres entre paréntesis angulares deben tratarse como de solo lectura. Los nombres entre corchetes son solo para uso interno. «<R>» (como prefijo) significa que el campo es obligatorio (no debe ser NULL).

2

Columnas:

«O»: establecido en PyBaseObject_Type

«T»: establecido en PyType_Type

«D»: por defecto (si la ranura está establecida como NULL)

X - PyType_Ready sets this value if it is NULL
~ - PyType_Ready always sets this value (it should be NULL)
? - PyType_Ready may set this value depending on other slots

Also see the inheritance column ("I").

«I»: herencia

X - type slot is inherited via *PyType_Ready* if defined with a *NULL* value
% - the slots of the sub-struct are inherited individually
G - inherited, but only in combination with other slots; see the slot's description
? - it's complicated; see the slot's description

Tenga en cuenta que algunos espacios se heredan efectivamente a través de la cadena de búsqueda de atributos normal.

sub-ranuras (sub-slots)

Ranuras (Slot)

Type

métodos especiales

am_await

unaryfunc

__await__

am_aiter

unaryfunc

__aiter__

am_anext

unaryfunc

__anext__

nb_add

binaryfunc

__add__ __radd__

nb_inplace_add

binaryfunc

__iadd__

nb_subtract

binaryfunc

__sub__ __rsub__

nb_inplace_subtract

binaryfunc

__isub__

nb_multiply

binaryfunc

__mul__ __rmul__

nb_inplace_multiply

binaryfunc

__imul__

nb_remainder

binaryfunc

__mod__ __rmod__

nb_inplace_remainder

binaryfunc

__imod__

nb_divmod

binaryfunc

__divmod__ __rdivmod__

nb_power

ternaryfunc

__pow__ __rpow__

nb_inplace_power

ternaryfunc

__ipow__

nb_negative

unaryfunc

__neg__

nb_positive

unaryfunc

__pos__

nb_absolute

unaryfunc

__abs__

nb_bool

inquiry

__bool__

nb_invert

unaryfunc

__invert__

nb_lshift

binaryfunc

__lshift__ __rlshift__

nb_inplace_lshift

binaryfunc

__ilshift__

nb_rshift

binaryfunc

__rshift__ __rrshift__

nb_inplace_rshift

binaryfunc

__irshift__

nb_and

binaryfunc

__and__ __rand__

nb_inplace_and

binaryfunc

__iand__

nb_xor

binaryfunc

__xor__ __rxor__

nb_inplace_xor

binaryfunc

__ixor__

nb_or

binaryfunc

__or__ __ror__

nb_inplace_or

binaryfunc

__ior__

nb_int

unaryfunc

__int__

nb_reserved

void *

nb_float

unaryfunc

__float__

nb_floor_divide

binaryfunc

__floordiv__

nb_inplace_floor_divide

binaryfunc

__ifloordiv__

nb_true_divide

binaryfunc

__truediv__

nb_inplace_true_divide

binaryfunc

__itruediv__

nb_index

unaryfunc

__index__

nb_matrix_multiply

binaryfunc

__matmul__ __rmatmul__

nb_inplace_matrix_multiply

binaryfunc

__imatmul__

mp_length

lenfunc

__len__

mp_subscript

binaryfunc

__getitem__

mp_ass_subscript

objobjargproc

__setitem__, __delitem__

sq_length

lenfunc

__len__

sq_concat

binaryfunc

__add__

sq_repeat

ssizeargfunc

__mul__

sq_item

ssizeargfunc

__getitem__

sq_ass_item

ssizeobjargproc

__setitem__ __delitem__

sq_contains

objobjproc

__contains__

sq_inplace_concat

binaryfunc

__iadd__

sq_inplace_repeat

ssizeargfunc

__imul__

bf_getbuffer

getbufferproc()

bf_releasebuffer

releasebufferproc()

ranura de typedefs

typedef

Tipos Parámetros

Tipo de Retorno

allocfunc

PyTypeObject *

Py_ssize_t

PyObject *

destructor

void *

void

freefunc

void *

void

traverseproc

void *

visitproc

void *

int

newfunc

PyObject *

PyObject *

PyObject *

PyObject *

initproc

PyObject *

PyObject *

PyObject *

int

reprfunc

PyObject *

PyObject *

getattrfunc

PyObject *

const char *

PyObject *

setattrfunc

PyObject *

const char *

PyObject *

int

getattrofunc

PyObject *

PyObject *

PyObject *

setattrofunc

PyObject *

PyObject *

PyObject *

int

descrgetfunc

PyObject *

PyObject *

PyObject *

PyObject *

descrsetfunc

PyObject *

PyObject *

PyObject *

int

hashfunc

PyObject *

Py_hash_t

richcmpfunc

PyObject *

PyObject *

int

PyObject *

getiterfunc

PyObject *

PyObject *

iternextfunc

PyObject *

PyObject *

lenfunc

PyObject *

Py_ssize_t

getbufferproc

PyObject *

Py_buffer *

int

int

releasebufferproc

PyObject *

Py_buffer *

void

inquiry

void *

int

unaryfunc

PyObject *

PyObject *

binaryfunc

PyObject *

PyObject *

PyObject *

ternaryfunc

PyObject *

PyObject *

PyObject *

PyObject *

ssizeargfunc

PyObject *

Py_ssize_t

PyObject *

ssizeobjargproc

PyObject *

Py_ssize_t

int

objobjproc

PyObject *

PyObject *

int

objobjargproc

PyObject *

PyObject *

PyObject *

int

Vea Tipo Ranura typedefs abajo para más detalles.

Definición de PyTypeObject

La definición de estructura para PyTypeObject se puede encontrar en Include/object.h. Por conveniencia de referencia, esto repite la definición encontrada allí:

typedef struct _typeobject {
    PyObject_VAR_HEAD
    const char *tp_name; /* For printing, in format "<module>.<name>" */
    Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */

    /* Methods to implement standard operations */

    destructor tp_dealloc;
    Py_ssize_t tp_vectorcall_offset;
    getattrfunc tp_getattr;
    setattrfunc tp_setattr;
    PyAsyncMethods *tp_as_async; /* formerly known as tp_compare (Python 2)
                                    or tp_reserved (Python 3) */
    reprfunc tp_repr;

    /* Method suites for standard classes */

    PyNumberMethods *tp_as_number;
    PySequenceMethods *tp_as_sequence;
    PyMappingMethods *tp_as_mapping;

    /* More standard operations (here for binary compatibility) */

    hashfunc tp_hash;
    ternaryfunc tp_call;
    reprfunc tp_str;
    getattrofunc tp_getattro;
    setattrofunc tp_setattro;

    /* Functions to access object as input/output buffer */
    PyBufferProcs *tp_as_buffer;

    /* Flags to define presence of optional/expanded features */
    unsigned long tp_flags;

    const char *tp_doc; /* Documentation string */

    /* call function for all accessible objects */
    traverseproc tp_traverse;

    /* delete references to contained objects */
    inquiry tp_clear;

    /* rich comparisons */
    richcmpfunc tp_richcompare;

    /* weak reference enabler */
    Py_ssize_t tp_weaklistoffset;

    /* Iterators */
    getiterfunc tp_iter;
    iternextfunc tp_iternext;

    /* Attribute descriptor and subclassing stuff */
    struct PyMethodDef *tp_methods;
    struct PyMemberDef *tp_members;
    struct PyGetSetDef *tp_getset;
    struct _typeobject *tp_base;
    PyObject *tp_dict;
    descrgetfunc tp_descr_get;
    descrsetfunc tp_descr_set;
    Py_ssize_t tp_dictoffset;
    initproc tp_init;
    allocfunc tp_alloc;
    newfunc tp_new;
    freefunc tp_free; /* Low-level free-memory routine */
    inquiry tp_is_gc; /* For PyObject_IS_GC */
    PyObject *tp_bases;
    PyObject *tp_mro; /* method resolution order */
    PyObject *tp_cache;
    PyObject *tp_subclasses;
    PyObject *tp_weaklist;
    destructor tp_del;

    /* Type attribute cache version tag. Added in version 2.6 */
    unsigned int tp_version_tag;

    destructor tp_finalize;

} PyTypeObject;

Ranuras (Slots) PyObject

The type object structure extends the PyVarObject structure. The ob_size field is used for dynamic types (created by type_new(), usually called from a class statement). Note that PyType_Type (the metatype) initializes tp_itemsize, which means that its instances (i.e. type objects) must have the ob_size field.

PyObject* PyObject._ob_next

PyObject* PyObject._ob_prev

Estos campos solo están presentes cuando se define la macro Py_TRACE_REFS. Su inicialización a NULL se ocupa de la macro PyObject_HEAD_INIT. Para los objetos asignados estáticamente, estos campos siempre permanecen NULL. Para los objetos asignados dinámicamente, estos dos campos se utilizan para vincular el objeto en una lista doblemente vinculada de todos objetos vivos en el montón. Esto podría usarse para varios propósitos de depuración; Actualmente, el único uso es imprimir los objetos que aún están vivos al final de una ejecución cuando se establece la variable de entorno PYTHONDUMPREFS.

Herencia:

Estos campos no son heredados por subtipos.

Py_ssize_t PyObject.ob_refcnt

Este es el recuento de referencia del objeto tipo, inicializado a 1 por el macro PyObject_HEAD_INIT. Tenga en cuenta que para los objetos de tipo asignados estáticamente, las instancias del tipo (objetos cuyo ob_type apunta al tipo) no cuentan como referencias. Pero para los objetos de tipo asignados dinámicamente, las instancias sí cuentan como referencias.

Herencia:

Este campo no es heredado por los subtipos.

PyTypeObject* PyObject.ob_type

Este es el tipo del tipo, en otras palabras, su metatipo. Se inicializa mediante el argumento de la macro PyObject_HEAD_INIT, y su valor normalmente debería ser &PyType_Type. Sin embargo, para los módulos de extensión cargables dinámicamente que deben ser utilizables en Windows (al menos), el compilador se queja de que este no es un inicializador válido. Por lo tanto, la convención es pasar NULL al macro PyObject_HEAD_INIT e inicializar este campo explícitamente al comienzo de la función de inicialización del módulo, antes de hacer cualquier otra cosa. Esto normalmente se hace así:

Foo_Type.ob_type = &PyType_Type;

Esto debe hacerse antes de que se creen instancias del tipo. PyType_Ready() comprueba si ob_type es NULL, y si es así, lo inicializa en el campo ob_type de la clase base. PyType_Ready() no cambiará este campo si no es cero.

Herencia:

Este campo es heredado por subtipos.

Ranuras PyVarObject

Py_ssize_t PyVarObject.ob_size

Para los objetos tipo asignados estáticamente, esto debe inicializarse a cero. Para los objetos tipo asignados dinámicamente, este campo tiene un significado interno especial.

Herencia:

Este campo no es heredado por los subtipos.

Ranuras PyTypeObject

Cada ranura tiene una sección que describe la herencia. Si PyType_Ready() puede establecer un valor cuando el campo se establece en NULL, entonces también habrá una sección «Predeterminada». (Tenga en cuenta que muchos campos establecidos en PyBaseObject_Type y PyType_Type actúan efectivamente como valores predeterminados).

const char* PyTypeObject.tp_name

Puntero a una cadena de caracteres terminada en NULL que contiene el nombre del tipo. Para los tipos que son accesibles como módulos globales, la cadena debe ser el nombre completo del módulo, seguido de un punto, seguido del nombre del tipo; para los tipos integrados, debe ser solo el nombre del tipo. Si el módulo es un submódulo de un paquete, el nombre completo del paquete es parte del nombre completo del módulo. Por ejemplo, un tipo llamado T definido en el módulo M en el subpaquete Q en el paquete P debe tener el inicializador tp_name "PQMT".

Para los objetos tipo asignados dinámicamente, este debería ser solo el nombre del tipo, y el nombre del módulo almacenado explícitamente en el tipo diccionario (dict) como el valor para la clave '__module__'.

Para los objetos tipo asignados estáticamente, el campo tp_name debe contener un punto. Todo antes del último punto se hace accesible como el atributo __module__, y todo después del último punto se hace accesible como el atributo __name__.

Si no hay ningún punto, todo el campo tp_name se hace accesible como el atributo __name__, y el atributo __module__ no está definido (a menos que sea explícitamente establecido en el diccionario, como se explicó anteriormente). Esto significa que su tipo será imposible de guardar como pickle. Además, no figurará en la documentación del módulo creado con pydoc.

Este campo no debe ser NULL. Es el único campo obligatorio en PyTypeObject() (que no sea potencialmente tp_itemsize).

Herencia:

Este campo no es heredado por los subtipos.

Py_ssize_t PyTypeObject.tp_basicsize

Py_ssize_t PyTypeObject.tp_itemsize

Estos campos permiten calcular el tamaño en bytes de instancias del tipo.

Hay dos tipos de tipos: los tipos con instancias de longitud fija tienen un campo cero tp_itemsize, los tipos con instancias de longitud variable tienen un campo distinto de cero tp_itemsize. Para un tipo con instancias de longitud fija, todas las instancias tienen el mismo tamaño, dado en tp_basicsize.

Para un tipo con instancias de longitud variable, las instancias deben tener un campo ob_size, y el tamaño de la instancia es tp_basicsize más N veces tp_itemsize, donde N es la «longitud» del objeto. El valor de N generalmente se almacena en el campo ob_size de la instancia. Hay excepciones: por ejemplo, los ints usan un negativo ob_size para indicar un número negativo, y N es abs(ob_size) allí. Además, la presencia de un campo ob_size en el diseño de la instancia no significa que la estructura de la instancia sea de longitud variable (por ejemplo, la estructura para el tipo de lista tiene instancias de longitud fija, aunque esas instancias tienen un significativo campo ob_size).

El tamaño básico incluye los campos en la instancia declarada por el macro PyObject_HEAD o PyObject_VAR_HEAD (lo que se use para declarar la estructura de la instancia) y esto a su vez incluye campos _ob_prev y _ob_next si están presentes. Esto significa que la única forma correcta de obtener un inicializador para tp_basicsize es usar el operador sizeof en la estructura utilizada para declarar el diseño de la instancia. El tamaño básico no incluye el tamaño del encabezado del GC.

Una nota sobre la alineación: si los elementos variables requieren una alineación particular, esto debe ser atendido por el valor de tp_basicsize. Ejemplo: supongamos que un tipo implementa un arreglo de dobles (double). tp_itemsize es sizeof(double). Es responsabilidad del programador que tp_basicsize es un múltiplo de sizeof(double) (suponiendo que este sea el requisito de alineación para double).

Para cualquier tipo con instancias de longitud variable, este campo no debe ser NULL.

Herencia:

Estos campos se heredan por separado por subtipos. Si el tipo base tiene un miembro distinto de cero tp_itemsize, generalmente no es seguro establecer tp_itemsize en un valor diferente de cero en un subtipo ( aunque esto depende de la implementación del tipo base).

destructor PyTypeObject.tp_dealloc

Un puntero a la función destructor de instancias. Esta función debe definirse a menos que el tipo garantice que sus instancias nunca se desasignarán (como es el caso de los singletons None y Ellipsis). La firma de la función es:

void tp_dealloc(PyObject *self);

La función destructor es llamada por las macros Py_DECREF() y Py_XDECREF() cuando el nuevo recuento de referencia es cero. En este punto, la instancia todavía existe, pero no hay referencias a ella. La función destructor debe liberar todas las referencias que posee la instancia, liberar todos los búferes de memoria que posee la instancia (utilizando la función de liberación correspondiente a la función de asignación utilizada para asignar el búfer) y llamar a los tipos función tp_free. Si el tipo no es subtipable (no tiene establecido el bit de indicador Py_TPFLAGS_BASETYPE), está permitido llamar al objeto desasignador directamente en lugar de a través de tp_free. El objeto desasignador debe ser el utilizado para asignar la instancia; normalmente es PyObject_Del() si la instancia se asignó usando PyObject_New() o PyObject_VarNew(), o PyObject_GC_Del() si la instancia se asignó usando PyObject_GC_New() o PyObject_GC_NewVar().

If the type supports garbage collection (has the Py_TPFLAGS_HAVE_GC flag bit set), the destructor should call PyObject_GC_UnTrack() before clearing any member fields.

static void foo_dealloc(foo_object *self) {
    PyObject_GC_UnTrack(self);
    Py_CLEAR(self->ref);
    Py_TYPE(self)->tp_free((PyObject *)self);
}

Finalmente, si el tipo está asignado en el montón (Py_TPFLAGS_HEAPTYPE), el desasignador debería disminuir el conteo de referencia para su objeto tipo después de llamar al desasignador del tipo. Para evitar punteros colgantes, la forma recomendada de lograr esto es:

static void foo_dealloc(foo_object *self) {
    PyTypeObject *tp = Py_TYPE(self);
    // free references and buffers here
    tp->tp_free(self);
    Py_DECREF(tp);
}

Herencia:

Este campo es heredado por subtipos.

Py_ssize_t PyTypeObject.tp_vectorcall_offset

Un desplazamiento opcional a una función por instancia que implementa la llamada al objeto usando vectorcall protocol, una alternativa más eficiente del simple tp_call.

Este campo solo se usa si se establece el flag Py_TPFLAGS_HAVE_VECTORCALL. Si es así, debe ser un entero positivo que contenga el desplazamiento en la instancia de un puntero vectorcallfunc.

El puntero vectorcallfunc puede ser NULL, en cuyo caso la instancia se comporta como si Py_TPFLAGS_HAVE_VECTORCALL no estuviera configurado: llamar a la instancia vuelve a tp_call.

Cualquier clase que establezca _Py_TPFLAGS_HAVE_VECTORCALL también debe establecer tp_call y asegurarse de que su comportamiento sea coherente con la función vectorcallfunc. Esto se puede hacer configurando tp_call en PyVectorcall_Call().

Advertencia

No se recomienda para tipos de pila para implementar el protocolo vectorcall. Cuando un usuario establece __call__ en código Python, solo se actualiza tp_call, lo que probablemente lo haga inconsistente con la función vectorcall.

Nota

La semántica de la ranura tp_vectorcall_offset es provisional y se espera que finalice en Python 3.9. Si usa vectorcall, planifique actualizar su código para Python 3.9.

Distinto en la versión 3.8: Antes de la versión 3.8, este slot se llamaba tp_print. En Python 2.x, se usó para imprimir en un archivo. En Python 3.0 a 3.7, no se usó.

Herencia:

Este campo siempre se hereda. Sin embargo, el flag Py_TPFLAGS_HAVE_VECTORCALL no siempre se hereda. Si no es así, entonces la subclase no usará vectorcall, excepto cuando PyVectorcall_Call() se llame explícitamente. Este es en particular el caso de los heap types (incluidas las subclases definidas en Python).

getattrfunc PyTypeObject.tp_getattr

Un puntero opcional a la función «obtener atributo cadena de caracteres» (get-attribute-string).

Este campo está en desuso. Cuando se define, debe apuntar a una función que actúe igual que la función tp_getattro, pero tomando una cadena de caracteres C en lugar de un objeto de cadena Python para dar el nombre del atributo.

Herencia:

Grupo: tp_getattr, tp_getattro

Este campo es heredado por los subtipos junto con tp_getattro: un subtipo hereda ambos tp_getattr y tp_getattro de su base escriba cuando los subtipos tp_getattr y tp_getattro son ambos NULL.

setattrfunc PyTypeObject.tp_setattr

Un puntero opcional a la función para configurar y eliminar atributos.

Este campo está en desuso. Cuando se define, debe apuntar a una función que actúe igual que la función tp_setattro, pero tomando una cadena de caracteres C en lugar de un objeto de cadena Python para dar el nombre del atributo.

Herencia:

Grupo: tp_setattr, tp_setattro

Este campo es heredado por los subtipos junto con tp_setattro: un subtipo hereda ambos tp_setattr y tp_setattro de su base escriba cuando los subtipos tp_setattr y tp_setattro son ambos NULL.

PyAsyncMethods* PyTypeObject.tp_as_async

Puntero a una estructura adicional que contiene campos relevantes solo para los objetos que implementan los protocolos «esperable» (awaitable) y «iterador asíncrono» (asynchronous iterator) en el nivel C. Ver Estructuras de objetos asíncronos para más detalles.

Nuevo en la versión 3.5: Anteriormente conocidos como tp_compare y tp_reserved.

Herencia:

El campo tp_as_async no se hereda, pero los campos contenidos se heredan individualmente.

reprfunc PyTypeObject.tp_repr

Un puntero opcional a una función que implementa la función incorporada repr().

La firma es la misma que para PyObject_Repr():

PyObject *tp_repr(PyObject *self);

La función debe retornar una cadena de caracteres o un objeto Unicode. Idealmente, esta función debería retornar una cadena que, cuando se pasa a eval(), dado un entorno adecuado, retorna un objeto con el mismo valor. Si esto no es factible, debe retornar una cadena que comience con '<' y termine con '>' desde la cual se puede deducir tanto el tipo como el valor del objeto.

Herencia:

Este campo es heredado por subtipos.

Por defecto:

Cuando este campo no está configurado, se retorna una cadena de caracteres de la forma <%s object at %p>, donde %s se reemplaza por el nombre del tipo y %p por dirección de memoria del objeto.

PyNumberMethods* PyTypeObject.tp_as_number

Puntero a una estructura adicional que contiene campos relevantes solo para objetos que implementan el protocolo numérico. Estos campos están documentados en Estructuras de Objetos de Números.

Herencia:

El campo tp_as_number no se hereda, pero los campos contenidos se heredan individualmente.

PySequenceMethods* PyTypeObject.tp_as_sequence

Puntero a una estructura adicional que contiene campos relevantes solo para objetos que implementan el protocolo de secuencia. Estos campos están documentados en Estructuras de objetos secuencia.

Herencia:

El campo tp_as_sequence no se hereda, pero los campos contenidos se heredan individualmente.

PyMappingMethods* PyTypeObject.tp_as_mapping

Puntero a una estructura adicional que contiene campos relevantes solo para objetos que implementan el protocolo de mapeo. Estos campos están documentados en Estructuras de Objetos Mapeo.

Herencia:

El campo tp_as_mapping no se hereda, pero los campos contenidos se heredan individualmente.

hashfunc PyTypeObject.tp_hash

Un puntero opcional a una función que implementa la función incorporada hash().

La firma es la misma que para PyObject_Hash():

Py_hash_t tp_hash(PyObject *);

El valor -1 no debe retornarse como un valor de retorno normal; Cuando se produce un error durante el cálculo del valor hash, la función debe establecer una excepción y retornar -1.

Cuando este campo no está establecido (y tp_richcompare no está establecido), se lanza TypeError cuando hay un intento de tomar el hash del objeto. Esto es lo mismo que establecerlo en PyObject_HashNotImplemented().

Este campo se puede establecer explícitamente en PyObject_HashNotImplemented() para bloquear la herencia del método hash de un tipo primario. Esto se interpreta como el equivalente de __hash__ = None en el nivel de Python, lo que hace que isinstance(o, collections.Hashable) retorne correctamente False. Tenga en cuenta que lo contrario también es cierto: establecer __hash__ = None en una clase en el nivel de Python dará como resultado que la ranura tp_hash se establezca en PyObject_HashNotImplemented().

Herencia:

Grupo: tp_hash, tp_richcompare

Este campo es heredado por subtipos junto con tp_richcompare: un subtipo hereda ambos tp_richcompare y tp_hash, cuando los subtipos tp_richcompare y tp_hash son ambos NULL.

ternaryfunc PyTypeObject.tp_call

Un puntero opcional a una función que implementa la llamada al objeto. Esto debería ser NULL si el objeto no es invocable. La firma es la misma que para PyObject_Call():

PyObject *tp_call(PyObject *self, PyObject *args, PyObject *kwargs);

Herencia:

Este campo es heredado por subtipos.

reprfunc PyTypeObject.tp_str

Un puntero opcional a una función que implementa la operación integrada str(). (Tenga en cuenta que str es un tipo ahora, y str() llama al constructor para ese tipo. Este constructor llama a PyObject_Str() para hacer el trabajo real, y PyObject_Str() llamará a este controlador.)

La firma es la misma que para PyObject_Str():

PyObject *tp_str(PyObject *self);

La función debe retornar una cadena de caracteres o un objeto Unicode. Debe ser una representación de cadena «amigable» del objeto, ya que esta es la representación que será utilizada, entre otras cosas, por la función print().

Herencia:

Este campo es heredado por subtipos.

Por defecto:

Cuando este campo no está configurado, se llama a PyObject_Repr() para retornar una representación de cadena de caracteres.

getattrofunc PyTypeObject.tp_getattro

Un puntero opcional a la función «obtener atributo» (get-attribute).

La firma es la misma que para PyObject_GetAttr():

PyObject *tp_getattro(PyObject *self, PyObject *attr);

Por lo general, es conveniente establecer este campo en PyObject_GenericGetAttr(), que implementa la forma normal de buscar atributos de objeto.

Herencia:

Grupo: tp_getattr, tp_getattro

Este campo es heredado por los subtipos junto con tp_getattr: un subtipo hereda ambos tp_getattr y tp_getattro de su base escriba cuando los subtipos tp_getattr y tp_getattro son ambos NULL.

Por defecto:

PyBaseObject_Type usa PyObject_GenericGetAttr().

setattrofunc PyTypeObject.tp_setattro

Un puntero opcional a la función para configurar y eliminar atributos.

La firma es la misma que para PyObject_SetAttr():

int tp_setattro(PyObject *self, PyObject *attr, PyObject *value);

Además, se debe admitir la configuración de value en NULL para eliminar un atributo. Por lo general, es conveniente establecer este campo en PyObject_GenericSetAttr(), que implementa la forma normal de establecer los atributos del objeto.

Herencia:

Grupo: tp_setattr, tp_setattro

Los subtipos heredan este campo junto con tp_setattr: un subtipo hereda ambos tp_setattr y tp_setattro de su base escriba cuando los subtipos tp_setattr y tp_setattro son ambos NULL.

Por defecto:

PyBaseObject_Type usa PyObject_GenericSetAttr().

PyBufferProcs* PyTypeObject.tp_as_buffer

Puntero a una estructura adicional que contiene campos relevantes solo para objetos que implementan la interfaz del búfer. Estos campos están documentados en Estructuras de Objetos Búfer.

Herencia:

El campo tp_as_buffer no se hereda, pero los campos contenidos se heredan individualmente.

unsigned long PyTypeObject.tp_flags

Este campo es una máscara de bits de varias banderas. Algunas banderas indican semántica variante para ciertas situaciones; otros se utilizan para indicar que ciertos campos en el tipo de objeto (o en las estructuras de extensión a las que se hace referencia a través de tp_as_number, tp_as_sequence, tp_as_mapping, y tp_as_buffer) que históricamente no siempre estuvieron presentes son válidos; si dicho bit de bandera está claro, no se debe acceder a los campos de tipo que protege y se debe considerar que tienen un valor cero o NULL.

Herencia:

La herencia de este campo es complicada. La mayoría de los bits de bandera se heredan individualmente, es decir, si el tipo base tiene un conjunto de bits de bandera, el subtipo hereda este bit de bandera. Los bits de bandera que pertenecen a las estructuras de extensión se heredan estrictamente si la estructura de extensión se hereda, es decir, el valor del tipo base del bit de bandera se copia en el subtipo junto con un puntero a la estructura de extensión. El bit de bandera Py_TPFLAGS_HAVE_GC se hereda junto con tp_traverse y tp_clear, es decir, si el bit de bandera Py_TPFLAGS_HAVE_GC está claro en el subtipo y los campos tp_traverse y tp_clear en el subtipo existen y tienen valores NULL.

Por defecto:

PyBaseObject_Type usa Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE.

Máscaras de bits:

Las siguientes máscaras de bits están definidas actualmente; estos se pueden unidos por OR usando el operador | para formar el valor del campo tp_flags. El macro PyType_HasFeature() toma un tipo y un valor de banderas, tp y f, y comprueba si tp->tp_flags & f no es cero.

Py_TPFLAGS_HEAPTYPE

Este bit se establece cuando el objeto de tipo se asigna en el montón, por ejemplo, los tipos creados dinámicamente usando PyType_FromSpec(). En este caso, el campo ob_type de sus instancias se considera una referencia al tipo, y el objeto de tipo se llama INCREF cuando se crea una nueva instancia, y DECREF cuando se destruye una instancia (esto hace no se aplica a instancias de subtipos; solo el tipo al que hace referencia el ob_type de la instancia obtiene INCREF o DECREF).

Herencia:

???

Py_TPFLAGS_BASETYPE

Este bit se establece cuando el tipo se puede usar como el tipo base de otro tipo. Si este bit es claro, el tipo no puede subtiparse (similar a una clase «final» en Java).

Herencia:

???

Py_TPFLAGS_READY

Este bit se establece cuando el objeto tipo ha sido completamente inicializado por PyType_Ready().

Herencia:

???

Py_TPFLAGS_READYING

Este bit se establece mientras PyType_Ready() está en el proceso de inicialización del objeto tipo.

Herencia:

???

Py_TPFLAGS_HAVE_GC

Este bit se establece cuando el objeto admite la recolección de elementos no utilizados. Si se establece este bit, las instancias deben crearse usando PyObject_GC_New() y destruirse usando PyObject_GC_Del(). Más información en la sección Apoyo a la recolección de basura cíclica. Este bit también implica que los campos relacionados con GC tp_traverse y tp_clear están presentes en el objeto de tipo.

Herencia:

Grupo: Py_TPFLAGS_HAVE_GC, tp_traverse, tp_clear

El bit de indicador Py_TPFLAGS_HAVE_GC se hereda junto con los campos tp_traverse y tp_clear, es decir, si el bit de indicador Py_TPFLAGS_HAVE_GC está claro en el subtipo y los campos tp_traverse y tp_clear en el subtipo existen y tienen valores NULL.

Py_TPFLAGS_DEFAULT

Esta es una máscara de bits de todos los bits que pertenecen a la existencia de ciertos campos en el objeto tipo y sus estructuras de extensión. Actualmente, incluye los siguientes bits: Py_TPFLAGS_HAVE_STACKLESS_EXTENSION, Py_TPFLAGS_HAVE_VERSION_TAG.

Herencia:

???

Py_TPFLAGS_METHOD_DESCRIPTOR

Este bit indica que los objetos se comportan como métodos independientes.

Si este indicador está configurado para type(meth), entonces:

meth.__get__(obj, cls)(*args, **kwds) (con obj no None) debe ser equivalente a meth(obj, *args, **kwds).

meth.__get__(None, cls)(*args, **kwds) debe ser equivalente a meth(*args, **kwds).

Este indicador (flag) permite una optimización para llamadas a métodos típicos como obj.meth(): evita crear un objeto temporal de «método vinculado» para obj.meth.

Nuevo en la versión 3.8.

Herencia:

Este indicador (flag) nunca es heredada por los tipos de montón. Para los tipos de extensión, se hereda siempre que tp_descr_get se hereda.

Py_TPFLAGS_LONG_SUBCLASS

Py_TPFLAGS_LIST_SUBCLASS

Py_TPFLAGS_TUPLE_SUBCLASS

Py_TPFLAGS_BYTES_SUBCLASS

Py_TPFLAGS_UNICODE_SUBCLASS

Py_TPFLAGS_DICT_SUBCLASS

Py_TPFLAGS_BASE_EXC_SUBCLASS

Py_TPFLAGS_TYPE_SUBCLASS

Estas marcas son utilizadas por funciones como PyLong_Check() para determinar rápidamente si un tipo es una subclase de un tipo incorporado; dichos controles específicos son más rápidos que un control genérico, como PyObject_IsInstance(). Los tipos personalizados que heredan de los elementos integrados deben tener su tp_flags configurado correctamente, o el código que interactúa con dichos tipos se comportará de manera diferente dependiendo del tipo de verificación que se use.

Py_TPFLAGS_HAVE_FINALIZE

Este bit se establece cuando la ranura tp_finalize está presente en la estructura de tipo.

Nuevo en la versión 3.4.

Obsoleto desde la versión 3.8: Este indicador ya no es necesario, ya que el intérprete asume que: el espacio tp_finalize siempre está presente en la estructura de tipos.

Py_TPFLAGS_HAVE_VECTORCALL

Este bit se establece cuando la clase implementa protocolo vectorcall. Consulte tp_vectorcall_offset para obtener más detalles.

Herencia:

Este bit se hereda para subtipos static si tp_call también se hereda. Heap types no heredan Py_TPFLAGS_HAVE_VECTORCALL.

Nuevo en la versión 3.9.

const char* PyTypeObject.tp_doc

Un puntero opcional a una cadena de caracteres de C terminada en NULL que proporciona la cadena de documentación para este tipo de objeto. Esto se expone como el atributo __doc__ en el tipo y las instancias del tipo.

Herencia:

Este campo es no heredado por los subtipos.

traverseproc PyTypeObject.tp_traverse

Un puntero opcional a una función transversal para el recolector de basura. Esto solo se usa si se establece el bit de la bandera (flag) Py_TPFLAGS_HAVE_GC. La firma es:

int tp_traverse(PyObject *self, visitproc visit, void *arg);

Se puede encontrar más información sobre el esquema de recolección de basura de Python en la sección Apoyo a la recolección de basura cíclica.

El puntero tp_traverse es utilizado por el recolector de basura para detectar ciclos de referencia. Una implementación típica de un tp_traverse simplemente llama a Py_VISIT() en cada uno de los miembros de la instancia que son objetos de Python que posee la instancia. Por ejemplo, esta es la función local_traverse() del módulo de extensión _thread:

static int
local_traverse(localobject *self, visitproc visit, void *arg)
{
    Py_VISIT(self->args);
    Py_VISIT(self->kw);
    Py_VISIT(self->dict);
    return 0;
}

Tenga en cuenta que Py_VISIT() solo se llama a aquellos miembros que pueden participar en los ciclos de referencia. Aunque también hay un miembro self->key, solo puede ser NULL o una cadena de caracteres de Python y, por lo tanto, no puede ser parte de un ciclo de referencia.

Por otro lado, incluso si sabe que un miembro nunca puede ser parte de un ciclo, como ayuda para la depuración puede visitarlo de todos modos solo para que la función get_referents() del módulo gc lo incluirá.

Advertencia

Al implementar tp_traverse, solo se deben visitar los miembros que posee la instancia (al tener fuertes referencias a ellos). Por ejemplo, si un objeto admite referencias débiles a través de la ranura tp_weaklist, el puntero que admite la lista vinculada (a lo que tp_weaklist señala) no debe ser visitado como la instancia no posee directamente las referencias débiles a sí mismo (la lista de referencias débiles está ahí para admitir la maquinaria de referencia débil, pero la instancia no tiene una referencia fuerte a los elementos dentro de ella, ya que se puede eliminar incluso si la instancia aún está viva).

Tenga en cuenta que Py_VISIT() requiere los parámetros visit y arg para local_traverse() para tener estos nombres específicos; no les llames de ninguna manera.

Los tipos asignados al heap (Py_TPFLAGS_HEAPTYPE, como los creados con PyType_FromSpec() y API similares) contienen una referencia a su tipo. Por lo tanto, su función transversal debe visitar Py_TYPE(self), o delegar esta responsabilidad llamando a tp_traverse de otro tipo asignado al heap (como una superclase asignada al heap). Si no es así, es posible que el objeto de tipo no se recolecte como basura.

Distinto en la versión 3.9: Se espera que los tipos asignados al montón visiten Py_TYPE(self) en tp_traverse. En versiones anteriores de Python, debido al bug 40217 [https://bugs.python.org/issue40217], hacer esto puede provocar fallas en las subclases.

Herencia:

Grupo: Py_TPFLAGS_HAVE_GC, tp_traverse, tp_clear

Este campo es heredado por los subtipos junto con tp_clear y el Py_TPFLAGS_HAVE_GC bit de bandera: el bit de bandera, tp_traverse, y tp_clear se heredan todos del tipo base si todos son cero en el subtipo.

inquiry PyTypeObject.tp_clear

Un puntero opcional a una función de limpieza (clear function) para el recolector de basura. Esto solo se usa si se establece el bit de bandera Py_TPFLAGS_HAVE_GC. La firma es:

int tp_clear(PyObject *);

La función miembro tp_clear se usa para romper los ciclos de referencia en la basura cíclica detectada por el recolector de basura. En conjunto, todas las funciones tp_clear en el sistema deben combinarse para romper todos los ciclos de referencia. Esto es sutil y, en caso de duda, proporcione una función tp_clear. Por ejemplo, el tipo de tupla no implementa una función tp_clear, porque es posible demostrar que ningún ciclo de referencia puede estar compuesto completamente de tuplas. Por lo tanto, las funciones tp_clear de otros tipos deben ser suficientes para romper cualquier ciclo que contenga una tupla. Esto no es inmediatamente obvio, y rara vez hay una buena razón para evitar la implementación de tp_clear.

Las implementaciones de tp_clear deberían descartar las referencias de la instancia a las de sus miembros que pueden ser objetos de Python, y establecer sus punteros a esos miembros en NULL, como en el siguiente ejemplo:

static int
local_clear(localobject *self)
{
    Py_CLEAR(self->key);
    Py_CLEAR(self->args);
    Py_CLEAR(self->kw);
    Py_CLEAR(self->dict);
    return 0;
}

Se debe utilizar el macro Py_CLEAR(), porque borrar las referencias es delicado: la referencia al objeto contenido no se debe disminuir hasta después de que el puntero al objeto contenido se establezca en NULL. Esto se debe a que la disminución del conteo de referencias puede hacer que el objeto contenido se convierta en basura, lo que desencadena una cadena de actividad de recuperación que puede incluir la invocación de código arbitrario de Python (debido a finalizadores o devoluciones de llamada de reflujo débil, asociadas con el objeto contenido). Si es posible que dicho código haga referencia a self nuevamente, es importante que el puntero al objeto contenido sea NULL en ese momento, de modo que self sepa que el objeto contenido ya no se puede usar. El macro Py_CLEAR() realiza las operaciones en un orden seguro.

Note that tp_clear is not always called before an instance is deallocated. For example, when reference counting is enough to determine that an object is no longer used, the cyclic garbage collector is not involved and tp_dealloc is called directly.

Debido a que el objetivo de tp_clear es romper los ciclos de referencia, no es necesario borrar objetos contenidos como cadenas de caracteres de Python o enteros de Python, que no pueden participar en los ciclos de referencia. Por otro lado, puede ser conveniente borrar todos los objetos Python contenidos y escribir la función tp_dealloc para invocar tp_clear.

Se puede encontrar más información sobre el esquema de recolección de basura de Python en la sección Apoyo a la recolección de basura cíclica.

Herencia:

Grupo: Py_TPFLAGS_HAVE_GC, tp_traverse, tp_clear

Este campo es heredado por subtipos junto con tp_traverse y el Py_TPFLAGS_HAVE_GC bit de bandera: el bit de bandera, tp_traverse, y tp_clear se heredan todos del tipo base si todos son cero en el subtipo.

richcmpfunc PyTypeObject.tp_richcompare

Un puntero opcional a la función de comparación enriquecida, cuya firma es:

PyObject *tp_richcompare(PyObject *self, PyObject *other, int op);

Se garantiza que el primer parámetro será una instancia del tipo definido por PyTypeObject.

La función debería retornar el resultado de la comparación (generalmente Py_True o Py_False). Si la comparación no está definida, debe retornar Py_NotImplemented, si se produce otro error, debe retornar NULL y establecer una condición de excepción.

Las siguientes constantes se definen para ser utilizadas como el tercer argumento para tp_richcompare y para PyObject_RichCompare():

Constante

Comparación

Py_LT

<

Py_LE

<=

Py_EQ

==

Py_NE

!=

Py_GT

>

Py_GE

>=

El siguiente macro está definido para facilitar la escritura de funciones de comparación enriquecidas:

Py_RETURN_RICHCOMPARE(VAL_A, VAL_B, op)

Retorna Py_True o Py_False de la función, según el resultado de una comparación. VAL_A y VAL_B deben ser ordenados por operadores de comparación C (por ejemplo, pueden ser enteros o punto flotantes de C). El tercer argumento especifica la operación solicitada, como por ejemplo PyObject_RichCompare().

El conteo de referencia del valor de retorno se incrementa correctamente.

En caso de error, establece una excepción y retorna NULL de la función.

Nuevo en la versión 3.7.

Herencia:

Grupo: tp_hash, tp_richcompare

Este campo es heredado por subtipos junto con tp_hash: un subtipo hereda tp_richcompare y tp_hash cuando el subtipo tp_richcompare y tp_hash son ambos NULL.

Por defecto:

PyBaseObject_Type proporciona una implementación tp_richcompare, que puede ser heredada. Sin embargo, si solo se define tp_hash, ni siquiera se utiliza la función heredada y las instancias del tipo no podrán participar en ninguna comparación.

Py_ssize_t PyTypeObject.tp_weaklistoffset

Si las instancias de este tipo son débilmente referenciables, este campo es mayor que cero y contiene el desplazamiento en la estructura de instancia del encabezado de la lista de referencia débil (ignorando el encabezado GC, si está presente); este desplazamiento es utilizado por PyObject_ClearWeakRefs() y las funciones PyWeakref_*(). La estructura de la instancia debe incluir un campo de tipo PyObject* que se inicializa en NULL.

No confunda este campo con tp_weaklist; ese es el encabezado de la lista para referencias débiles al objeto de tipo en sí.

Herencia:

Este campo es heredado por subtipos, pero consulte las reglas que se enumeran a continuación. Un subtipo puede anular este desplazamiento; Esto significa que el subtipo utiliza un encabezado de lista de referencia débil diferente que el tipo base. Dado que el encabezado de la lista siempre se encuentra a través de tp_weaklistoffset, esto no debería ser un problema.

Cuando un tipo definido por una declaración de clase no tiene __slots__ declaración, y ninguno de sus tipos base es débilmente referenciable, el tipo se hace débilmente referenciable al agregar una ranura de encabezado de lista de referencia débil al diseño de la instancia y configurando tp_weaklistoffset del desplazamiento de esa ranura.

Cuando la declaración de un tipo __slots__ contiene un espacio llamado __weakref__, ese espacio se convierte en el encabezado de la lista de referencia débil para las instancias del tipo, y el desplazamiento del espacio se almacena en el tipo tp_weaklistoffset.

Cuando la declaración de un tipo __slots__ no contiene un espacio llamado __weakref__, el tipo hereda su tp_weaklistoffset de su tipo base.

getiterfunc PyTypeObject.tp_iter

Un puntero opcional a una función que retorna un iterador para el objeto. Su presencia normalmente indica que las instancias de este tipo son iterables (aunque las secuencias pueden ser iterables sin esta función).

Esta función tiene la misma firma que PyObject_GetIter():

PyObject *tp_iter(PyObject *self);

Herencia:

Este campo es heredado por subtipos.

iternextfunc PyTypeObject.tp_iternext

Un puntero opcional a una función que retorna el siguiente elemento en un iterador. La firma es:

PyObject *tp_iternext(PyObject *self);

Cuando el iterador está agotado, debe retornar NULL; a la excepción StopIteration puede o no establecerse. Cuando se produce otro error, también debe retornar NULL. Su presencia indica que las instancias de este tipo son iteradores.

Los tipos de iterador también deberían definir la función tp_iter, y esa función debería retornar la instancia de iterador en sí (no una nueva instancia de iterador).

Esta función tiene la misma firma que PyIter_Next().

Herencia:

Este campo es heredado por subtipos.

struct PyMethodDef* PyTypeObject.tp_methods

Un puntero opcional a un arreglo estático terminado en NULL de estructuras PyMethodDef, declarando métodos regulares de este tipo.

Para cada entrada en el arreglo, se agrega una entrada al diccionario del tipo (ver tp_dict a continuación) que contiene un descriptor method.

Herencia:

Los subtipos no heredan este campo (los métodos se heredan mediante un mecanismo diferente).

struct PyMemberDef* PyTypeObject.tp_members

Un puntero opcional a un arreglo estático terminado en NULL de estructuras PyMemberDef, declarando miembros de datos regulares (campos o ranuras) de instancias de este tipo.

Para cada entrada en el arreglo, se agrega una entrada al diccionario del tipo (ver tp_dict a continuación) que contiene un descriptor member.

Herencia:

Los subtipos no heredan este campo (los miembros se heredan mediante un mecanismo diferente).

struct PyGetSetDef* PyTypeObject.tp_getset

Un puntero opcional a un arreglo estático terminado en NULL de estructuras PyGetSetDef, declarando atributos calculados de instancias de este tipo.

Para cada entrada en el arreglo, se agrega una entrada al diccionario del tipo (ver tp_dict a continuación) que contiene un descriptor getset.

Herencia:

Este campo no es heredado por los subtipos (los atributos computados se heredan a través de un mecanismo diferente).

PyTypeObject* PyTypeObject.tp_base

Un puntero opcional a un tipo base del que se heredan las propiedades de tipo. En este nivel, solo se admite una herencia única; La herencia múltiple requiere la creación dinámica de un objeto tipo llamando al metatipo.

Nota

La inicialización de ranuras está sujeta a las reglas de inicialización de globales. C99 requiere que los inicializadores sean «constantes de dirección». Los designadores de funciones como PyType_GenericNew(), con conversión implícita a un puntero, son constantes de dirección C99 válidas.

Sin embargo, el operador unario “&” aplicado a una variable no estática como PyBaseObject_Type() no es necesario para producir una dirección constante. Los compiladores pueden admitir esto (gcc lo hace), MSVC no. Ambos compiladores son estrictamente estándar conforme a este comportamiento particular.

En consecuencia, tp_base debe establecerse en la función init del módulo de extensión.

Herencia:

Este campo no es heredado por los subtipos (obviamente).

Por defecto:

Este campo predeterminado es &PyBaseObject_Type (que para los programadores de Python se conoce como el tipo objeto).

PyObject* PyTypeObject.tp_dict

El diccionario del tipo se almacena aquí por PyType_Ready().

Este campo normalmente debe inicializarse a NULL antes de llamar a PyType_Ready; también se puede inicializar en un diccionario que contiene atributos iniciales para el tipo. Una vez PyType_Ready() ha inicializado el tipo, los atributos adicionales para el tipo pueden agregarse a este diccionario solo si no corresponden a operaciones sobrecargadas (como __add__()).

Herencia:

Este campo no es heredado por los subtipos (aunque los atributos definidos aquí se heredan a través de un mecanismo diferente).

Por defecto:

Si este campo es NULL, PyType_Ready() le asignará un nuevo diccionario.

Advertencia

No es seguro usar PyDict_SetItem() en o modificar de otra manera a tp_dict con el diccionario C-API.

descrgetfunc PyTypeObject.tp_descr_get

Un puntero opcional a una función «obtener descriptor» (descriptor ger).

La firma de la función es:

PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type);

Herencia:

Este campo es heredado por subtipos.

descrsetfunc PyTypeObject.tp_descr_set

Un puntero opcional a una función para configurar y eliminar el valor de un descriptor.

La firma de la función es:

int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value);

El argumento value se establece a NULL para borrar el valor.

Herencia:

Este campo es heredado por subtipos.

Py_ssize_t PyTypeObject.tp_dictoffset

Si las instancias de este tipo tienen un diccionario que contiene variables de instancia, este campo no es cero y contiene el desplazamiento en las instancias del tipo del diccionario de variables de instancia; este desplazamiento es utilizado por PyObject_GenericGetAttr().

No confunda este campo con tp_dict; ese es el diccionario para los atributos del tipo de objeto en sí.

Si el valor de este campo es mayor que cero, especifica el desplazamiento desde el inicio de la estructura de la instancia. Si el valor es menor que cero, especifica el desplazamiento desde el end de la estructura de la instancia. Un desplazamiento negativo es más costoso de usar y solo debe usarse cuando la estructura de la instancia contiene una parte de longitud variable. Esto se utiliza, por ejemplo, para agregar un diccionario de variables de instancia a los subtipos de str o tuple. Tenga en cuenta que el campo tp_basicsize debe tener en cuenta el diccionario agregado al final en ese caso, aunque el diccionario no esté incluido en el diseño básico del objeto. En un sistema con un tamaño de puntero de 4 bytes, tp_dictoffset debe establecerse en -4 para indicar que el diccionario está al final de la estructura.

El desplazamiento real del diccionario en una instancia se puede calcular a partir de un elemento negativo tp_dictoffset de la siguiente manera:

dictoffset = tp_basicsize + abs(ob_size)*tp_itemsize + tp_dictoffset
if dictoffset is not aligned on sizeof(void*):
    round up to sizeof(void*)

donde tp_basicsize, tp_itemsize y tp_dictoffset se toman del objeto type, y ob_size está tomado de la instancia. Se toma el valor absoluto porque ints usa el signo de ob_size para almacenar el signo del número. (Nunca es necesario hacer este cálculo usted mismo; lo hace por usted la función _PyObject_GetDictPtr().)

Herencia:

Este campo es heredado por subtipos, pero consulte las reglas que se enumeran a continuación. Un subtipo puede anular este desplazamiento; Esto significa que las instancias de subtipo almacenan el diccionario en un desplazamiento de diferencia que el tipo base. Dado que el diccionario siempre se encuentra a través de tp_dictoffset, esto no debería ser un problema.

Cuando un tipo definido por una declaración de clase no tiene __slots__ declaración, y ninguno de sus tipos base tiene un diccionario de variable de instancia, se agrega un espacio de diccionario al diseño de la instancia y el tp_dictoffset está configurado para el desplazamiento de esa ranura.

Cuando un tipo definido por una declaración de clase tiene una declaración __slots__, el tipo hereda su tp_dictoffset de su tipo base.

(Agrega un espacio llamado __dict__ a la declaración __slots__ no tiene el efecto esperado, solo causa confusión. Quizás esto debería agregarse como una característica como __weakref__ aunque.)

Por defecto:

Esta ranura no tiene valor predeterminado. Para los tipos estáticos, si el campo es NULL, entonces no __dict__ se crea para las instancias.

initproc PyTypeObject.tp_init

Un puntero opcional a una función de inicialización de instancia.

Esta función corresponde al método de clases __init__(). Como __init__(), es posible crear una instancia sin llamar a __init__(), y es posible reinicializar una instancia llamando de nuevo a su método __init__().

La firma de la función es:

int tp_init(PyObject *self, PyObject *args, PyObject *kwds);

El argumento propio es la instancia que se debe inicializar; los argumentos args y kwds representan argumentos posicionales y de palabras clave de la llamada a __init__().

La función tp_init, si no es NULL, se llama cuando una instancia se crea normalmente llamando a su tipo, después de la función tp_new del tipo ha retornado una instancia del tipo. Si la función tp_new retorna una instancia de otro tipo que no es un subtipo del tipo original, no se llama la función tp_init; if tp_new retorna una instancia de un subtipo del tipo original, se llama al subtipo tp_init.

Retorna 0 en caso de éxito, -1 y establece una excepción en caso de error.

Herencia:

Este campo es heredado por subtipos.

Por defecto:

Para los tipos estáticos, este campo no tiene un valor predeterminado.

allocfunc PyTypeObject.tp_alloc

Un puntero opcional a una función de asignación de instancia.

La firma de la función es:

PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems);

Herencia:

Este campo es heredado por subtipos estáticos, pero no por subtipos dinámicos (subtipos creados por una declaración de clase).

Por defecto:

Para subtipos dinámicos, este campo siempre se establece en PyType_GenericAlloc(), para forzar una estrategia de asignación de montón estándar.

Para subtipos estáticos, PyBaseObject_Type utiliza PyType_GenericAlloc(). Ese es el valor recomendado para todos los tipos definidos estáticamente.

newfunc PyTypeObject.tp_new

Un puntero opcional a una función de creación de instancias.

La firma de la función es:

PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds);

El argumento subtype es el tipo de objeto que se está creando; los argumentos args y kwds representan argumentos posicionales y de palabras clave de la llamada al tipo. Tenga en cuenta que subtype no tiene que ser igual al tipo cuya función tp_new es llamada; puede ser un subtipo de ese tipo (pero no un tipo no relacionado).

La función tp_new debería llamar a subtype->tp_alloc(subtype, nitems) para asignar espacio para el objeto, y luego hacer solo la inicialización adicional que sea absolutamente necesaria. La inicialización que se puede ignorar o repetir de forma segura debe colocarse en el controlador tp_init. Una buena regla general es que para los tipos inmutables, toda la inicialización debe tener lugar en tp_new, mientras que para los tipos mutables, la mayoría de las inicializaciones se deben diferir a tp_init.

Herencia:

Este campo es heredado por subtipos, excepto que no es heredado por tipos estáticos cuyo tp_base es NULL o &PyBaseObject_Type.

Por defecto:

Para los tipos estáticos, este campo no tiene valor predeterminado. Esto significa que si el espacio se define como NULL, no se puede llamar al tipo para crear nuevas instancias; presumiblemente hay otra forma de crear instancias, como una función de fábrica.

freefunc PyTypeObject.tp_free

Un puntero opcional a una función de desasignación de instancia. Su firma es:

void tp_free(void *self);

Un inicializador que es compatible con esta firma es PyObject_Free().

Herencia:

Este campo es heredado por subtipos estáticos, pero no por subtipos dinámicos (subtipos creados por una declaración de clase)

Por defecto:

En los subtipos dinámicos, este campo se establece en un desasignador adecuado para que coincida con PyType_GenericAlloc() y el valor del bit de bandera Py_TPFLAGS_HAVE_GC.

Para subtipos estáticos, PyBaseObject_Type usa PyObject_Del.

inquiry PyTypeObject.tp_is_gc

Un puntero opcional a una función llamada por el recolector de basura.

El recolector de basura necesita saber si un objeto en particular es coleccionable o no. Normalmente, es suficiente mirar el el campo tp_flags del tipo objeto , y verificar el bit de bandera Py_TPFLAGS_HAVE_GC. Pero algunos tipos tienen una mezcla de instancias asignadas estáticamente y dinámicamente, y las instancias asignadas estáticamente no son coleccionables. Tales tipos deberían definir esta función; debería retornar 1 para una instancia coleccionable y 0 para una instancia no coleccionable. La firma es:

int tp_is_gc(PyObject *self);

(El único ejemplo de esto son los mismo tipos. El metatipo, PyType_Type, define esta función para distinguir entre tipos asignados estáticamente y dinámicamente.)

Herencia:

Este campo es heredado por subtipos.

Por defecto:

Esta ranura no tiene valor predeterminado. Si este campo es NULL, se utiliza Py_TPFLAGS_HAVE_GC como el equivalente funcional.

PyObject* PyTypeObject.tp_bases

Tupla de tipos base.

Esto se establece para los tipos creados por una declaración de clase. Debería ser NULL para los tipos estáticamente definidos.

Herencia:

Este campo no se hereda.

PyObject* PyTypeObject.tp_mro

Tupla que contiene el conjunto expandido de tipos base, comenzando con el tipo en sí y terminando con object, en orden de resolución de método.

Herencia:

Este campo no se hereda; se calcula fresco por PyType_Ready().

PyObject* PyTypeObject.tp_cache

No usado. Solo para uso interno.

Herencia:

Este campo no se hereda.

PyObject* PyTypeObject.tp_subclasses

Lista de referencias débiles a subclases. Solo para uso interno.

Herencia:

Este campo no se hereda.

PyObject* PyTypeObject.tp_weaklist

Cabecera de lista de referencia débil, para referencias débiles a este tipo de objeto. No heredado Solo para uso interno.

Herencia:

Este campo no se hereda.

destructor PyTypeObject.tp_del

Este campo está en desuso. Use tp_finalize en su lugar.

unsigned int PyTypeObject.tp_version_tag

Se usa para indexar en el caché de métodos. Solo para uso interno.

Herencia:

Este campo no se hereda.

destructor PyTypeObject.tp_finalize

Un puntero opcional a una función de finalización de instancia. Su firma es:

void tp_finalize(PyObject *self);

Si tp_finalize está configurado, el intérprete lo llama una vez cuando finaliza una instancia. Se llama desde el recolector de basura (si la instancia es parte de un ciclo de referencia aislado) o justo antes de que el objeto se desasigne. De cualquier manera, se garantiza que se invocará antes de intentar romper los ciclos de referencia, asegurando que encuentre el objeto en un estado sano.

tp_finalize no debe mutar el estado de excepción actual; por lo tanto, una forma recomendada de escribir un finalizador no trivial es:

static void
local_finalize(PyObject *self)
{
    PyObject *error_type, *error_value, *error_traceback;

    /* Save the current exception, if any. */
    PyErr_Fetch(&error_type, &error_value, &error_traceback);

    /* ... */

    /* Restore the saved exception. */
    PyErr_Restore(error_type, error_value, error_traceback);
}

Para que este campo se tenga en cuenta (incluso a través de la herencia), también debe establecer el bit de banderas Py_TPFLAGS_HAVE_FINALIZE.

Además, tenga en cuenta que, en un Python que ha recolectado basura, se puede llamar a tp_dealloc desde cualquier hilo de Python, no solo el hilo que creó el objeto (si el objeto se convierte en parte de un ciclo de conteo de referencias, ese ciclo puede ser recogido por una recolección de basura en cualquier hilo). Esto no es un problema para las llamadas a la API de Python, ya que el hilo en el que se llama tp_dealloc será el propietario del Bloqueo Global del Intérprete (GIL, por sus siglas en inglés Global Interpreter Lock). Sin embargo, si el objeto que se destruye a su vez destruye objetos de alguna otra biblioteca C o C++, se debe tener cuidado para garantizar que la destrucción de esos objetos en el hilo que se llama tp_dealloc no violará ningún supuesto de la biblioteca.

Herencia:

Este campo es heredado por subtipos.

Nuevo en la versión 3.4.

Ver también

«Finalización segura de objetos» (PEP 442 [https://www.python.org/dev/peps/pep-0442])

vectorcallfunc PyTypeObject.tp_vectorcall

Función Vectorcall a utilizar para llamadas de este tipo de objeto. En otras palabras, se usa para implementar vectorcall para type.__call__. Si tp_vectorcall es NULL, se usa la implementación de llamada predeterminada usando __new__ y __init__.

Herencia:

Este campo nunca se hereda.

Nuevo en la versión 3.9: (el campo existe desde 3.8 pero solo se usa desde 3.9)

Tipos Montículos (Heap Types)

Tradicionalmente, los tipos definidos en el código C son static, es decir, una estructura estática PyTypeObject se define directamente en el código y se inicializa usando PyType_Ready().

Esto da como resultado tipos que están limitados en relación con los tipos definidos en Python:

Los tipos estáticos están limitados a una base, es decir, no pueden usar herencia múltiple.

Los objetos de tipo estático (pero no necesariamente sus instancias) son inmutables. No es posible agregar o modificar los atributos del objeto tipo desde Python.

Los objetos de tipo estático se comparten en sub intérpretes, por lo que no deben incluir ningún estado específico del sub interpretador.

Además, dado que PyTypeObject no forma parte de stable ABI, cualquier módulo de extensión que use tipos estáticos debe compilarse para una versión menor específica de Python.

Una alternativa a los tipos estáticos es tipos asignados al montículo (heap-allocated types), o tipos montículo (heap types) para abreviar, que corresponden estrechamente a las clases creadas por la declaración class de Python.

Esto se hace completando una estructura PyType_Spec y llamando a PyType_FromSpecWithBases().

Estructuras de Objetos de Números

PyNumberMethods

Esta estructura contiene punteros a las funciones que utiliza un objeto para implementar el protocolo numérico. Cada función es utilizada por la función de un nombre similar documentado en la sección Protocolo de números.

Aquí está la definición de la estructura:

typedef struct {
     binaryfunc nb_add;
     binaryfunc nb_subtract;
     binaryfunc nb_multiply;
     binaryfunc nb_remainder;
     binaryfunc nb_divmod;
     ternaryfunc nb_power;
     unaryfunc nb_negative;
     unaryfunc nb_positive;
     unaryfunc nb_absolute;
     inquiry nb_bool;
     unaryfunc nb_invert;
     binaryfunc nb_lshift;
     binaryfunc nb_rshift;
     binaryfunc nb_and;
     binaryfunc nb_xor;
     binaryfunc nb_or;
     unaryfunc nb_int;
     void *nb_reserved;
     unaryfunc nb_float;

     binaryfunc nb_inplace_add;
     binaryfunc nb_inplace_subtract;
     binaryfunc nb_inplace_multiply;
     binaryfunc nb_inplace_remainder;
     ternaryfunc nb_inplace_power;
     binaryfunc nb_inplace_lshift;
     binaryfunc nb_inplace_rshift;
     binaryfunc nb_inplace_and;
     binaryfunc nb_inplace_xor;
     binaryfunc nb_inplace_or;

     binaryfunc nb_floor_divide;
     binaryfunc nb_true_divide;
     binaryfunc nb_inplace_floor_divide;
     binaryfunc nb_inplace_true_divide;

     unaryfunc nb_index;

     binaryfunc nb_matrix_multiply;
     binaryfunc nb_inplace_matrix_multiply;
} PyNumberMethods;

Nota

Las funciones binarias y ternarias deben verificar el tipo de todos sus operandos e implementar las conversiones necesarias (al menos uno de los operandos es una instancia del tipo definido). Si la operación no está definida para los operandos dados, las funciones binarias y ternarias deben retornar Py_NotImplemented, si se produce otro error, deben retornar NULL y establecer una excepción.

Nota

El campo nb_reserved siempre debe ser NULL. Anteriormente se llamaba nb_long, y se renombró en Python 3.0.1.

binaryfunc PyNumberMethods.nb_add

binaryfunc PyNumberMethods.nb_subtract

binaryfunc PyNumberMethods.nb_multiply

binaryfunc PyNumberMethods.nb_remainder

binaryfunc PyNumberMethods.nb_divmod

ternaryfunc PyNumberMethods.nb_power

unaryfunc PyNumberMethods.nb_negative

unaryfunc PyNumberMethods.nb_positive

unaryfunc PyNumberMethods.nb_absolute

inquiry PyNumberMethods.nb_bool

unaryfunc PyNumberMethods.nb_invert

binaryfunc PyNumberMethods.nb_lshift

binaryfunc PyNumberMethods.nb_rshift

binaryfunc PyNumberMethods.nb_and

binaryfunc PyNumberMethods.nb_xor

binaryfunc PyNumberMethods.nb_or

unaryfunc PyNumberMethods.nb_int

void *PyNumberMethods.nb_reserved

unaryfunc PyNumberMethods.nb_float

binaryfunc PyNumberMethods.nb_inplace_add

binaryfunc PyNumberMethods.nb_inplace_subtract

binaryfunc PyNumberMethods.nb_inplace_multiply

binaryfunc PyNumberMethods.nb_inplace_remainder

ternaryfunc PyNumberMethods.nb_inplace_power

binaryfunc PyNumberMethods.nb_inplace_lshift

binaryfunc PyNumberMethods.nb_inplace_rshift

binaryfunc PyNumberMethods.nb_inplace_and

binaryfunc PyNumberMethods.nb_inplace_xor

binaryfunc PyNumberMethods.nb_inplace_or

binaryfunc PyNumberMethods.nb_floor_divide

binaryfunc PyNumberMethods.nb_true_divide

binaryfunc PyNumberMethods.nb_inplace_floor_divide

binaryfunc PyNumberMethods.nb_inplace_true_divide

unaryfunc PyNumberMethods.nb_index

binaryfunc PyNumberMethods.nb_matrix_multiply

binaryfunc PyNumberMethods.nb_inplace_matrix_multiply

Estructuras de Objetos Mapeo

PyMappingMethods

Esta estructura contiene punteros a las funciones que utiliza un objeto para implementar el protocolo de mapeo. Tiene tres miembros:

lenfunc PyMappingMethods.mp_length

Esta función es utilizada por PyMapping_Size() y PyObject_Size(), y tiene la misma firma. Esta ranura puede establecerse en NULL si el objeto no tiene una longitud definida.

binaryfunc PyMappingMethods.mp_subscript

Esta función es utilizada por PyObject_GetItem() y PySequence_GetSlice(), y tiene la misma firma que PyObject_GetItem(). Este espacio debe llenarse para que la función PyMapping_Check() retorna 1, de lo contrario puede ser NULL.

objobjargproc PyMappingMethods.mp_ass_subscript

Esta función es utilizada por PyObject_SetItem(), PyObject_DelItem(), PyObject_SetSlice() y PyObject_DelSlice(). Tiene la misma firma que PyObject_SetItem(), pero v también se puede establecer en NULL para eliminar un elemento. Si este espacio es NULL, el objeto no admite la asignación y eliminación de elementos.

Estructuras de objetos secuencia

PySequenceMethods

Esta estructura contiene punteros a las funciones que utiliza un objeto para implementar el protocolo de secuencia.

lenfunc PySequenceMethods.sq_length

Esta función es utilizada por PySequence_Size() y PyObject_Size(), y tiene la misma firma. También se usa para manejar índices negativos a través de los espacios sq_item y sq_ass_item.

binaryfunc PySequenceMethods.sq_concat

Esta función es utilizada por PySequence_Concat() y tiene la misma firma. También es utilizado por el operador +, después de intentar la suma numérica a través de la ranura nb_add.

ssizeargfunc PySequenceMethods.sq_repeat

Esta función es utilizada por PySequence_Repeat() y tiene la misma firma. También es utilizado por el operador *, después de intentar la multiplicación numérica a través de la ranura nb_multiply.

ssizeargfunc PySequenceMethods.sq_item

Esta función es utilizada por PySequence_GetItem() y tiene la misma firma. También es utilizado por PyObject_GetItem(), después de intentar la suscripción a través de la ranura mp_subscript. Este espacio debe llenarse para que la función PySequence_Check() retorna 1, de lo contrario puede ser NULL.

Los índices negativos se manejan de la siguiente manera: si se llena el espacio sq_length, se llama y la longitud de la secuencia se usa para calcular un índice positivo que se pasa a sq_item. Si sq_length es NULL, el índice se pasa como es a la función.

ssizeobjargproc PySequenceMethods.sq_ass_item

Esta función es utilizada por PySequence_SetItem() y tiene la misma firma. También lo usan PyObject_SetItem() y PyObject_DelItem(), después de intentar la asignación y eliminación del elemento a través de la ranura mp_ass_subscript. Este espacio puede dejarse en NULL si el objeto no admite la asignación y eliminación de elementos.

objobjproc PySequenceMethods.sq_contains

Esta función puede ser utilizada por PySequence_Contains() y tiene la misma firma. Este espacio puede dejarse en NULL, en este caso PySequence_Contains() simplemente atraviesa la secuencia hasta que encuentra una coincidencia.

binaryfunc PySequenceMethods.sq_inplace_concat

Esta función es utilizada por PySequence_InPlaceConcat() y tiene la misma firma. Debería modificar su primer operando y retornarlo. Este espacio puede dejarse en NULL, en este caso PySequence_InPlaceConcat() volverá a PySequence_Concat(). También es utilizado por la asignación aumentada +=, después de intentar la suma numérica en el lugar a través de la ranura nb_inplace_add.

ssizeargfunc PySequenceMethods.sq_inplace_repeat

Esta función es utilizada por PySequence_InPlaceRepeat() y tiene la misma firma. Debería modificar su primer operando y retornarlo. Este espacio puede dejarse en NULL, en este caso PySequence_InPlaceRepeat() volverá a PySequence_Repeat(). También es utilizado por la asignación aumentada *=, después de intentar la multiplicación numérica en el lugar a través de la ranura nb_inplace_multiply.

Estructuras de Objetos Búfer

PyBufferProcs

Esta estructura contiene punteros a las funciones requeridas por Buffer protocol. El protocolo define cómo un objeto exportador puede exponer sus datos internos a objetos de consumo.

getbufferproc PyBufferProcs.bf_getbuffer

La firma de esta función es:

int (PyObject *exporter, Py_buffer *view, int flags);

Maneja una solicitud a exporter para completar view según lo especificado por flags. Excepto por el punto (3), una implementación de esta función DEBE seguir estos pasos:

Comprueba si se puede cumplir con la solicitud. Si no, lanza PyExc_BufferError, establece view->obj en NULL y retorna -1.

Rellene los campos solicitados.

Incrementa un contador interno para el número de exportaciones (exports).

Establece view->obj en exporter e incremente view->obj.

Retorna 0.

Si exporter es parte de una cadena o árbol de proveedores de búfer, se pueden usar dos esquemas principales:

Re-exportación: cada miembro del árbol actúa como el objeto exportador y establece view->obj en una nueva referencia a sí mismo.

Redirigir: la solicitud de búfer se redirige al objeto raíz del árbol. Aquí view->obj será una nueva referencia al objeto raíz.

Los campos individuales de view se describen en la sección Estructura de búfer, las reglas sobre cómo debe reaccionar un exportador a solicitudes específicas se encuentran en la sección Tipos de solicitud de búfer.

Toda la memoria señalada en la estructura Py_buffer pertenece al exportador y debe permanecer válida hasta que no queden consumidores. format, shape, strides, suboffsets y internal son de solo lectura para el consumidor.

PyBuffer_FillInfo() proporciona una manera fácil de exponer un búfer de bytes simple mientras se trata correctamente con todos los tipos de solicitud.

PyObject_GetBuffer() es la interfaz para el consumidor que envuelve esta función.

releasebufferproc PyBufferProcs.bf_releasebuffer

La firma de esta función es:

void (PyObject *exporter, Py_buffer *view);

Maneja una solicitud para liberar los recursos del búfer. Si no es necesario liberar recursos, PyBufferProcs.bf_releasebuffer puede ser NULL. De lo contrario, una implementación estándar de esta función tomará estos pasos opcionales:

Disminuir un contador interno para el número de exportaciones.

Si el contador es 0, libera toda la memoria asociada con view.

El exportador DEBE utilizar el campo internal para realizar un seguimiento de los recursos específicos del búfer. Se garantiza que este campo permanecerá constante, mientras que un consumidor PUEDE pasar una copia del búfer original como argumento view.

Esta función NO DEBE disminuir view->obj, ya que esto se hace automáticamente en PyBuffer_Release() (este esquema es útil para romper los ciclos de referencia).

PyBuffer_Release() es la interfaz para el consumidor que envuelve esta función.

Estructuras de objetos asíncronos

Nuevo en la versión 3.5.

PyAsyncMethods

Esta estructura contiene punteros a las funciones requeridas para implementar objetos «esperable» (awaitable) y «iterador asincrónico» (asynchronous iterator).

Aquí está la definición de la estructura:

typedef struct {
    unaryfunc am_await;
    unaryfunc am_aiter;
    unaryfunc am_anext;
} PyAsyncMethods;

unaryfunc PyAsyncMethods.am_await

La firma de esta función es:

PyObject *am_await(PyObject *self);

El objeto retornado debe ser un iterador, es decir PyIter_Check() debe retornar 1 para ello.

Este espacio puede establecerse en NULL si un objeto no es awaitable.

unaryfunc PyAsyncMethods.am_aiter

La firma de esta función es:

PyObject *am_aiter(PyObject *self);

Must return an asynchronous iterator object. See __anext__() for details.

Este espacio puede establecerse en NULL si un objeto no implementa el protocolo de iteración asincrónica.

unaryfunc PyAsyncMethods.am_anext

La firma de esta función es:

PyObject *am_anext(PyObject *self);

Debe retornar un objeto «esperable» (awaitable). Ver __anext__() para más detalles. Esta ranura puede establecerse en NULL.

Tipo Ranura typedefs

PyObject *(*allocfunc)(PyTypeObject *cls, Py_ssize_t nitems)

El propósito de esta función es separar la asignación de memoria de la inicialización de memoria. Debería retornar un puntero a un bloque de memoria de longitud adecuada para la instancia, adecuadamente alineado e inicializado a ceros, pero con ob_refcnt establecido en 1 y ob_type establecido en argumento de tipo. Si el tipo tp_itemsize no es cero, el campo del objeto ob_size debe inicializarse en nitems y la longitud del bloque de memoria asignado debe ser tp_basicsize + nitems*tp_itemsize, redondeado a un múltiplo de sizeof(void*); de lo contrario, nitems no se usa y la longitud del bloque debe ser tp_basicsize.

Esta función no debe hacer ninguna otra instancia de inicialización, ni siquiera para asignar memoria adicional; eso debe ser realizado por tp_new.

void (*destructor)(PyObject *)

void (*freefunc)(void *)

Consulte tp_free.

PyObject *(*newfunc)(PyObject *, PyObject *, PyObject *)

Consulte tp_new.

int (*initproc)(PyObject *, PyObject *, PyObject *)

Consulte tp_init.

PyObject *(*reprfunc)(PyObject *)

Consulte tp_repr.

PyObject *(*getattrfunc)(PyObject *self, char *attr)

Retorna el valor del atributo nombrado para el objeto.

int (*setattrfunc)(PyObject *self, char *attr, PyObject *value)

Establece el valor del atributo nombrado para el objeto. El argumento del valor se establece en NULL para eliminar el atributo.

PyObject *(*getattrofunc)(PyObject *self, PyObject *attr)

Retorna el valor del atributo nombrado para el objeto.

Consulte tp_getattro.

int (*setattrofunc)(PyObject *self, PyObject *attr, PyObject *value)

Establece el valor del atributo nombrado para el objeto. El argumento del valor se establece en NULL para eliminar el atributo.

Consulte tp_setattro.

PyObject *(*descrgetfunc)(PyObject *, PyObject *, PyObject *)

Consulte tp_descrget.

int (*descrsetfunc)(PyObject *, PyObject *, PyObject *)

Consulte tp_descrset.

Py_hash_t (*hashfunc)(PyObject *)

Consulte tp_hash.

PyObject *(*richcmpfunc)(PyObject *, PyObject *, int)

Consulte tp_richcompare.

PyObject *(*getiterfunc)(PyObject *)

Consulte tp_iter.

PyObject *(*iternextfunc)(PyObject *)

Consulte tp_iternext.

Py_ssize_t (*lenfunc)(PyObject *)

int (*getbufferproc)(PyObject *, Py_buffer *, int)

void (*releasebufferproc)(PyObject *, Py_buffer *)

PyObject *(*unaryfunc)(PyObject *)

PyObject *(*binaryfunc)(PyObject *, PyObject *)

PyObject *(*ternaryfunc)(PyObject *, PyObject *, PyObject *)

PyObject *(*ssizeargfunc)(PyObject *, Py_ssize_t)

int (*ssizeobjargproc)(PyObject *, Py_ssize_t)

int (*objobjproc)(PyObject *, PyObject *)

int (*objobjargproc)(PyObject *, PyObject *, PyObject *)

Ejemplos

Los siguientes son ejemplos simples de definiciones de tipo Python. Incluyen el uso común que puede encontrar. Algunos demuestran casos difíciles de esquina (corner cases). Para obtener más ejemplos, información práctica y un tutorial, consulte «definiendo nuevos tipos» (Definición de tipos de extensión: Tutorial) y «tópicos de nuevos tipos (Definición de tipos de extensión: temas variados).

Un tipo estático básico:

typedef struct {
    PyObject_HEAD
    const char *data;
} MyObject;

static PyTypeObject MyObject_Type = {
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "mymod.MyObject",
    .tp_basicsize = sizeof(MyObject),
    .tp_doc = PyDoc_STR("My objects"),
    .tp_new = myobj_new,
    .tp_dealloc = (destructor)myobj_dealloc,
    .tp_repr = (reprfunc)myobj_repr,
};

También puede encontrar código más antiguo (especialmente en la base de código CPython) con un inicializador más detallado:

static PyTypeObject MyObject_Type = {
    PyVarObject_HEAD_INIT(NULL, 0)
    "mymod.MyObject",               /* tp_name */
    sizeof(MyObject),               /* tp_basicsize */
    0,                              /* tp_itemsize */
    (destructor)myobj_dealloc,      /* tp_dealloc */
    0,                              /* tp_vectorcall_offset */
    0,                              /* tp_getattr */
    0,                              /* tp_setattr */
    0,                              /* tp_as_async */
    (reprfunc)myobj_repr,           /* tp_repr */
    0,                              /* tp_as_number */
    0,                              /* tp_as_sequence */
    0,                              /* tp_as_mapping */
    0,                              /* tp_hash */
    0,                              /* tp_call */
    0,                              /* tp_str */
    0,                              /* tp_getattro */
    0,                              /* tp_setattro */
    0,                              /* tp_as_buffer */
    0,                              /* tp_flags */
    PyDoc_STR("My objects"),        /* tp_doc */
    0,                              /* tp_traverse */
    0,                              /* tp_clear */
    0,                              /* tp_richcompare */
    0,                              /* tp_weaklistoffset */
    0,                              /* tp_iter */
    0,                              /* tp_iternext */
    0,                              /* tp_methods */
    0,                              /* tp_members */
    0,                              /* tp_getset */
    0,                              /* tp_base */
    0,                              /* tp_dict */
    0,                              /* tp_descr_get */
    0,                              /* tp_descr_set */
    0,                              /* tp_dictoffset */
    0,                              /* tp_init */
    0,                              /* tp_alloc */
    myobj_new,                      /* tp_new */
};

Un tipo que admite referencias débiles, instancias de diccionarios (dicts) y hashing:

typedef struct {
    PyObject_HEAD
    const char *data;
    PyObject *inst_dict;
    PyObject *weakreflist;
} MyObject;

static PyTypeObject MyObject_Type = {
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "mymod.MyObject",
    .tp_basicsize = sizeof(MyObject),
    .tp_doc = PyDoc_STR("My objects"),
    .tp_weaklistoffset = offsetof(MyObject, weakreflist),
    .tp_dictoffset = offsetof(MyObject, inst_dict),
    .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC,
    .tp_new = myobj_new,
    .tp_traverse = (traverseproc)myobj_traverse,
    .tp_clear = (inquiry)myobj_clear,
    .tp_alloc = PyType_GenericNew,
    .tp_dealloc = (destructor)myobj_dealloc,
    .tp_repr = (reprfunc)myobj_repr,
    .tp_hash = (hashfunc)myobj_hash,
    .tp_richcompare = PyBaseObject_Type.tp_richcompare,
};

Una subclase de str que no se puede subclasificar (subclassed) y no se puede llamar para crear instancias (por ejemplo, utiliza una función de fábrica separada):

typedef struct {
    PyUnicodeObject raw;
    char *extra;
} MyStr;

static PyTypeObject MyStr_Type = {
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "mymod.MyStr",
    .tp_basicsize = sizeof(MyStr),
    .tp_base = NULL,  // set to &PyUnicode_Type in module init
    .tp_doc = PyDoc_STR("my custom str"),
    .tp_flags = Py_TPFLAGS_DEFAULT,
    .tp_new = NULL,
    .tp_repr = (reprfunc)myobj_repr,
};

El tipo estático más simple (con instancias de longitud fija):

typedef struct {
    PyObject_HEAD
} MyObject;

static PyTypeObject MyObject_Type = {
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "mymod.MyObject",
};

El tipo estático más simple (con instancias de longitud variable):

typedef struct {
    PyObject_VAR_HEAD
    const char *data[1];
} MyObject;

static PyTypeObject MyObject_Type = {
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "mymod.MyObject",
    .tp_basicsize = sizeof(MyObject) - sizeof(char *),
    .tp_itemsize = sizeof(char *),
};

Apoyo a la recolección de basura cíclica

El soporte de Python para detectar y recolectar basura que involucra referencias circulares requiere el soporte de tipos de objetos que son «contenedores» para otros objetos que también pueden ser contenedores. Los tipos que no almacenan referencias a otros objetos, o que solo almacenan referencias a tipos atómicos (como números o cadenas), no necesitan proporcionar ningún soporte explícito para la recolección de basura.

Para crear un tipo de contenedor, el campo tp_flags del objeto tipo debe incluir Py_TPFLAGS_HAVE_GC y proporcionar una implementación del manejador tp_traverse . Si las instancias del tipo son mutables, también se debe proporcionar una implementación a tp_clear.

Py_TPFLAGS_HAVE_GC

Los objetos con un tipo con este indicador establecido deben cumplir con las reglas documentadas aquí. Por conveniencia, estos objetos se denominarán objetos contenedor.

Los constructores para tipos de contenedores deben cumplir con dos reglas:

La memoria para el objeto debe asignarse usando PyObject_GC_New() o PyObject_GC_NewVar().

Una vez que se inicializan todos los campos que pueden contener referencias a otros contenedores, debe llamar a PyObject_GC_Track().

Del mismo modo, el desasignador (deallocator) para el objeto debe cumplir con un par similar de reglas:

Antes de invalidar los campos que se refieren a otros contenedores, debe llamarse PyObject_GC_UnTrack().

La memoria del objeto debe ser desasignada (deallocated) usando PyObject_GC_Del().

Advertencia

If a type adds the Py_TPFLAGS_HAVE_GC, then it must implement at least a tp_traverse handler or explicitly use one from its subclass or subclasses.

When calling PyType_Ready() or some of the APIs that indirectly call it like PyType_FromSpecWithBases() or PyType_FromSpec() the interpreter will automatically populate the tp_flags, tp_traverse and tp_clear fields if the type inherits from a class that implements the garbage collector protocol and the child class does not include the Py_TPFLAGS_HAVE_GC flag.

TYPE* PyObject_GC_New(TYPE, PyTypeObject *type)

Análogo a PyObject_New() pero para objetos de contenedor con el flag Py_TPFLAGS_HAVE_GC establecido.

TYPE* PyObject_GC_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)

Análogo a PyObject_NewVar() pero para objetos de contenedor con el flag Py_TPFLAGS_HAVE_GC establecido.

TYPE* PyObject_GC_Resize(TYPE, PyVarObject *op, Py_ssize_t newsize)

Cambia el tamaño de un objeto asignado por PyObject_NewVar(). Retorna el objeto redimensionado o NULL en caso de falla. op aún no debe ser rastreado por el recolector de basura.

void PyObject_GC_Track(PyObject *op)

Agrega el objeto op al conjunto de objetos contenedor seguidos por el recolector de basura. El recolector puede ejecutarse en momentos inesperados, por lo que los objetos deben ser válidos durante el seguimiento. Esto debería llamarse una vez que todos los campos seguidos por tp_traverse se vuelven válidos, generalmente cerca del final del constructor.

int PyObject_IS_GC(PyObject *obj)

Retorna un valor distinto de cero si el objeto implementa el protocolo del recolector de basura; de lo contrario, retorna 0.

El recolector de basura no puede rastrear el objeto si esta función retorna 0.

int PyObject_GC_IsTracked(PyObject *op)

Retorna 1 si el tipo de objeto de op implementa el protocolo GC y el recolector de basura está rastreando op y 0 en caso contrario.

Esto es análogo a la función de Python gc.is_tracked().

Nuevo en la versión 3.9.

int PyObject_GC_IsFinalized(PyObject *op)

Retorna 1 si el tipo de objeto de op implementa el protocolo GC y op ya ha sido finalizado por el recolector de basura y 0 en caso contrario.

Esto es análogo a la función de Python gc.is_finalized().

Nuevo en la versión 3.9.

void PyObject_GC_Del(void *op)

Libera memoria asignada a un objeto usando PyObject_GC_New() o PyObject_GC_NewVar().

void PyObject_GC_UnTrack(void *op)

Elimina el objeto op del conjunto de objetos contenedor rastreados por el recolector de basura. Tenga en cuenta que PyObject_GC_Track() puede ser llamado nuevamente en este objeto para agregarlo nuevamente al conjunto de objetos rastreados. El desasignador (el manejador tp_dealloc) debería llamarlo para el objeto antes de que cualquiera de los campos utilizados por el manejador tp_traverse no sea válido.

Distinto en la versión 3.8: Los macros _PyObject_GC_TRACK() y _PyObject_GC_UNTRACK() se han eliminado de la API pública de C.

El manejador tp_traverse acepta un parámetro de función de este tipo:

int (*visitproc)(PyObject *object, void *arg)

Tipo de la función visitante que se pasa al manejador tp_traverse. La función debe llamarse con un objeto para atravesar como object y el tercer parámetro para el manejador tp_traverse como arg. El núcleo de Python utiliza varias funciones visitantes para implementar la detección de basura cíclica; No se espera que los usuarios necesiten escribir sus propias funciones visitante.

El manejador tp_traverse debe tener el siguiente tipo:

int (*traverseproc)(PyObject *self, visitproc visit, void *arg)

Función transversal para un objeto contenedor. Las implementaciones deben llamar a la función visit para cada objeto directamente contenido por self, siendo los parámetros a visit el objeto contenido y el valor arg pasado al controlador. La función visit no debe llamarse con un argumento de objeto NULL. Si visit retorna un valor distinto de cero, ese valor debe retornarse inmediatamente.

Para simplificar la escritura de los manejadores tp_traverse, se proporciona un macro a Py_VISIT(). Para usar este macro, la implementación tp_traverse debe nombrar sus argumentos exactamente visit y arg:

void Py_VISIT(PyObject *o)

Si o no es NULL, llama a la devolución de llamada (callback) visit, con argumentos o y arg. Si visit retorna un valor distinto de cero, lo retorna. Usando este macro, los manejadores tp_traverse tienen el siguiente aspecto:

static int
my_traverse(Noddy *self, visitproc visit, void *arg)
{
    Py_VISIT(self->foo);
    Py_VISIT(self->bar);
    return 0;
}

El manejador tp_clear debe ser del tipo query, o NULL si el objeto es inmutable.

int (*inquiry)(PyObject *self)

Descarta referencias que pueden haber creado ciclos de referencia. Los objetos inmutables no tienen que definir este método ya que nunca pueden crear directamente ciclos de referencia. Tenga en cuenta que el objeto aún debe ser válido después de llamar a este método (no solo llame a Py_DECREF() en una referencia). El recolector de basura llamará a este método si detecta que este objeto está involucrado en un ciclo de referencia.

Versiones de API y ABI

PY_VERSION_HEX es el número de versión de Python codificado en un solo entero.

Por ejemplo, si PY_VERSION_HEX se establece en 0x030401a2, la información de la versión subyacente se puede encontrar tratándola como un número de 32 bits de la siguiente manera:

Bytes

Bits (orden big-endian)

Significado

1

1-8

PY_MAJOR_VERSION (el 3 en 3.4.1a2)

2

9-16

PY_MINOR_VERSION (el 4 en 3.4.1a2)

3

17-24

PY_MICRO_VERSION (el 1 en 3.4.1a2)

4

25-28

PY_RELEASE_LEVEL (0xA para alfa, 0xB para beta, 0xC para el candidato de lanzamiento y 0xF para final), en este caso es alfa.

29-32

PY_RELEASE_SERIAL (el 2 en 3.4.1a2, cero para lanzamientos finales)

Así 3.4.1a2 es la hexadecimal 0x030401a2.

Todas las macros dadas se definen en Include/patchlevel.h [https://github.com/python/cpython/tree/3.9/Include/patchlevel.h].

Distribuir módulos de Python

Email

distutils-sig@python.org

Como un proyecto de desarrollo de código abierto popular, Python tiene una comunidad activa de colaboradores y usuarios que también hacen que su software esté disponible para que otros desarrolladores de Python los usen bajo términos de licencia de código abierto.

Esto permite a los usuarios de Python compartir y colaborar eficazmente, beneficiándose de las soluciones que otros ya han creado a problemas comunes (¡y a veces incluso raros!), así como potencialmente contribuyendo con sus propias soluciones al grupo común.

Esta guía cubre la parte de distribución del proceso. Para obtener una guía para instalar otros proyectos de Python, consulte installation guide.

Nota

Para usuarios corporativos y otros usuarios institucionales, tenga en cuenta que muchas organizaciones tienen sus propias políticas en torno al uso y la contribución al software de código abierto. Por favor tenga en cuenta estas políticas al hacer uso de las herramientas de distribución e instalación proporcionadas con Python.

Términos clave

the Python Package Index [https://pypi.org] is a public repository of open source licensed packages made available for use by other Python users

la Python Packaging Authority [https://www.pypa.io/] es el grupo de desarrolladores y autores de documentación responsables del mantenimiento y la evolución de las herramientas de empaquetado estándar y los metadatos asociados y los estándares de formato de archivo. Ellos mantienen una variedad de herramientas, documentación y rastreadores de problemas tanto en GitHub [https://github.com/pypa] como Bitbucket [https://bitbucket.org/pypa/].

distutils es el sistema de distribución y compilación original que se agregó por primera vez a la biblioteca estándar de Python en 1998. Si bien el uso directo de distutils se está eliminando, aún es la base para la infraestructura de empaquetado y distribución actual, y no solo sigue siendo parte de la biblioteca estándar, sino que su nombre vive de otras formas (como el nombre de la lista de correo utilizada para coordinar el desarrollo de estándares de empaquetado de Python).

setuptools [https://setuptools.readthedocs.io/en/latest/] es un reemplazo (en gran parte) directo de distutils publicado por primera vez en 2004. Su adición más notable sobre las herramientas sin modificar distutils fue la capacidad de declarar dependencias en otros paquetes. Actualmente se recomienda como una alternativa actualizada con más regularidad a distutils que ofrece soporte consistente para estándares de empaquetado más recientes en una amplia gama de versiones de Python.

wheel [https://wheel.readthedocs.io/] (en este contexto) es un proyecto que agrega el comando bdist_wheel a distutils/setuptools [https://setuptools.readthedocs.io/en/latest/]. Esto produce un formato de empaquetado binario multiplataforma (llamado «wheels» o «wheel files» y definido en PEP 427 [https://www.python.org/dev/peps/pep-0427]) que permite que las bibliotecas de Python, incluso aquellas que incluyen extensiones binarias, se instalen en un sistema sin necesidad de ser compiladas en la zona.

Licencias de código abierto y colaboración

En la mayor parte del mundo, el software está automáticamente protegido por derechos de autor. Esto significa que otros desarrolladores requieren permiso explícito para copiar, usar, modificar y redistribuir el software.

La concesión de licencias de código abierto es una forma de otorgar explícitamente dicho permiso de una manera relativamente consistente, lo que permite a los desarrolladores compartir y colaborar de manera eficiente al hacer que las soluciones comunes a varios problemas estén disponibles de forma gratuita. Esto deja a muchos desarrolladores libres para dedicar más tiempo a concentrarse en los problemas que son relativamente únicos para su situación específica.

Las herramientas de distribución proporcionadas con Python están diseñadas para que sea razonablemente sencillo para los desarrolladores hacer sus propias contribuciones a ese grupo común de software si así lo desean.

Las mismas herramientas de distribución también se pueden utilizar para distribuir software dentro de una organización, independientemente de si ese software se publica como software de código abierto o no.

Instalando las herramientas

La biblioteca estándar no incluye herramientas de compilación que sean compatibles con los estándares de empaquetado de Python modernos, ya que el equipo de desarrollo central ha descubierto que es importante tener herramientas estándar que funcionen de manera consistente, incluso en versiones anteriores de Python.

Las herramientas de construcción y distribución recomendadas actualmente se pueden instalar invocando el módulo pip en la línea de comando:

python -m pip install setuptools wheel twine

Nota

For POSIX users (including macOS and Linux users), these instructions assume the use of a virtual environment.

Para los usuarios de Windows, estas instrucciones asumen que se seleccionó la opción para ajustar la variable de entorno PATH del sistema al instalar Python.

La «Python Packaging User Guide» incluye más detalles sobre las currently recommended tools [https://packaging.python.org/guides/tool-recommendations/#packaging-tool-recommendations].

Leyendo la «Python Packaging User Guide»

La «Python Packaging User Guide» cubre los diversos pasos y elementos clave involucrados en la creación y publicación de un proyecto:

Estructura del proyecto

Compilando y empaquetando el proyecto

Uploading the project to the Python Package Index

El archivo .pypirc

Cómo puedo…?

Estas son respuestas rápidas o enlaces para algunas tareas comunes.

… elegir un nombre para mi proyecto?

Este no es un tema fácil, pero aquí hay algunos consejos:

check the Python Package Index to see if the name is already in use

verifique sitios de alojamiento populares como GitHub, Bitbucket, etc. para ver si ya existe un proyecto con ese nombre

verifique lo que aparece en una búsqueda web para el nombre que está considerando

evite palabras particularmente comunes, especialmente aquellas con múltiples significados, ya que pueden dificultar que los usuarios encuentren su software cuando lo busquen

… crear y distribuir extensiones binarias?

Este es un tema bastante complejo, con una variedad de alternativas disponibles según exactamente lo que pretenda lograr. Consulte la «Python Packaging User Guide» para obtener más información y recomendaciones.

Ver también

Python Packaging User Guide: Binary Extensions [https://packaging.python.org/guides/packaging-binary-extensions/]

Instalando módulos de Python

Correo electrónico

distutils-sig@python.org

Como un proyecto popular de desarrollo de código abierto, Python tiene una comunidad activa de soporte de contribuyentes y usuarios que también hacen que su software esté disponible para que otros desarrolladores de Python lo usen bajo términos de licencia de código abierto.

Esto permite a los usuarios de Python compartir y colaborar de manera efectiva, beneficiándose de las soluciones que otros ya han creado para problemas comunes (¡y a veces incluso raros!), además de contribuir potencialmente con sus propias soluciones al grupo común.

Esta guía cubre la parte de instalación del proceso. Para obtener una guía para crear y compartir sus propios proyectos de Python, consulta la guía de distribución.

Nota

Para los usuarios corporativos y otros usuarios institucionales, se debe tener en cuenta que muchas organizaciones tienen sus propias políticas sobre el uso y la contribución al software de código abierto. Se deben tener en cuenta dichas políticas al utilizar las herramientas de distribución e instalación proporcionadas con Python.

Palabras clave

pip es el programa de instalación preferido. Desde Python 3.4 viene incluido por defecto con los instaladores binarios de Python.

Un entorno virtual es un entorno de Python parcialmente aislado que permite instalar paquetes para que los use una aplicación en particular, en lugar de instalarlos en todo el sistema.

venv es la herramienta estándar para crear entornos virtuales, y ha sido parte de Python desde Python 3.3. A partir de Python 3.4, instala pip en todos los entornos virtuales que se crean.

virtualenv es una alternativa de terceros (y predecesora) a venv. Permite usar entornos virtuales en versiones de Python anteriores a la 3.4, ya que, o no incluyen venv en absoluto o no pueden instalar automáticamente pip en los entornos recién creados.

The Python Package Index [https://pypi.org] is a public repository of open source licensed packages made available for use by other Python users.

la Python Packaging Authority [https://www.pypa.io/] es el grupo de desarrolladores y autores de documentación responsables del mantenimiento y evolución de las herramientas estándar de empaquetado y de los estándares de metadatos y formatos de archivo. Mantienen una variedad de herramientas, documentación y rastreadores de problemas en GitHub [https://github.com/pypa] y Bitbucket [https://bitbucket.org/pypa/].

distutils es el sistema original de compilación y distribución que se agregó por primera vez a la biblioteca estándar de Python en 1998. Si bien el uso directo de distutils se está eliminando gradualmente, sentó las bases para la infraestructura actual de empaquetado y distribución, y no solo sigue siendo parte de la biblioteca estándar, sino que su nombre sigue vivo de otras maneras (como el nombre de la lista de correo utilizada para coordinar el desarrollo de estándares de empaquetado de Python).

Distinto en la versión 3.5: Ahora se recomienda el uso de venv para crear entornos virtuales.

Ver también

Guía de usuario de empaquetado de Python: Crear y usar entornos virtuales [https://packaging.python.org/installing/#creating-virtual-environments]

Uso básico

Las herramientas estándar de empaquetado están diseñadas para que se usen desde la línea de comandos.

The following command will install the latest version of a module and its dependencies from the Python Package Index:

python -m pip install SomePackage

Nota

For POSIX users (including macOS and Linux users), the examples in this guide assume the use of a virtual environment.

Para los usuarios de Windows, los ejemplos en esta guía asumen que se seleccionó la opción de ajustar la variable de entorno PATH del sistema al instalar Python.

Es posible especificar una versión exacta o mínima directamente en la linea de comandos. Cuando se use un operando comparador como >, < o cualquier otro carácter especial que puede ser interpretado por el intérprete de comandos, el nombre del paquete y la versión deben ir entre comillas dobles:

python -m pip install SomePackage==1.0.4    # specific version
python -m pip install "SomePackage>=1.0.4"  # minimum version

Normalmente, si ya hay instalado un módulo adecuado, intentar instalarlo otra vez no tendrá efecto alguno. Actualizar módulos existentes requiere que se solicite explícitamente:

python -m pip install --upgrade SomePackage

Se puede encontrar más información y recursos acerca de pip y sus capacidades en la Guía de usuario de empaquetado de Python [https://packaging.python.org].

La creación de entornos virtuales se realiza a través de el módulo venv. Instalar paquetes en un entorno virtual activo usa los comandos mostrados arriba.

Ver también

Guía de usuario de empaquetado de Python: Instalando paquetes de distribución de Python [https://packaging.python.org/installing/]

¿Cómo…

Respuestas rápidas o enlaces para algunas tareas comunes.

… instalo pip en versiones de Python anteriores a Python 3.4?

Se empezó a incluir pip en Python con la versión de Python 3.4. Para versiones anteriores, pip tiene que ser instalado tal y como se describe en la Guía de usuario de empaquetado de Python.

Ver también

Guía de usuario de empaquetado de Python: Requisitos para instalar paquetes [https://packaging.python.org/installing/#requirements-for-installing-packages]

… instalo paquetes solamente para el usuario actual?

Pasando la opción --user a python -m pip install instalará el paquete únicamente para el usuario actual, en lugar de hacerlo para todos los usuarios del sistema.

… instalo paquetes científicos de Python?

Varios paquetes científicos de Python tienen dependencias binarias complejas y no se pueden instalar fácilmente usando pip directamente. En este momento, a menudo será más fácil para los usuarios instalar estos paquetes por otros medios [https://packaging.python.org/science/] en lugar de intentar instalarlos usando pip.

Ver también

Guía de usuario de empaquetado de Python: Instalando paquetes científicos [https://packaging.python.org/science/]

… trabajo con múltiples versiones de Python instaladas en paralelo?

On Linux, macOS, and other POSIX systems, use the versioned Python commands in combination with the -m switch to run the appropriate copy of pip:

python2   -m pip install SomePackage  # default Python 2
python2.7 -m pip install SomePackage  # specifically Python 2.7
python3   -m pip install SomePackage  # default Python 3
python3.4 -m pip install SomePackage  # specifically Python 3.4

Los comandos `` pip “” adecuadamente versionados también pueden estar disponibles.

En Windows, use el lanzador de Python `` py`` en combinación con el interruptor `` -m``

py -2   -m pip install SomePackage  # default Python 2
py -2.7 -m pip install SomePackage  # specifically Python 2.7
py -3   -m pip install SomePackage  # default Python 3
py -3.4 -m pip install SomePackage  # specifically Python 3.4

Problemas de instalación comunes

Instalando en el Python del sistema bajo Linux

En sistemas Linux, una instalación de Python se incluye como parte de la distribución. Instalar en esta instalación de Python requiere permisos de administrador de sistema y si algún componente se actualiza usando pip esto puede interferir con en uso del gestor de paquetes del sistema u otros componentes.

En estos sistemas, es generalmente mejor usar un entorno virtual o una instalación por usuario cuando se instalen paquetes con pip.

Pip no está instalado

Es posible que pip no se instale por defecto. Una posible solución es:

python -m ensurepip --default-pip

Hay recursos adicionales para instalar pip. [https://packaging.python.org/tutorials/installing-packages/#install-pip-setuptools-and-wheel]

Instalando extensiones binarias

Python generalmente se ha basado en gran medida en la distribución basada en el código fuente, y se espera que los usuarios finales compilen módulos de extensión desde la fuente como parte del proceso de instalación.

With the introduction of support for the binary wheel format, and the ability to publish wheels for at least Windows and macOS through the Python Package Index, this problem is expected to diminish over time, as users are more regularly able to install pre-built extensions rather than needing to build them themselves.

Algunas de las soluciones para instalar software científico [https://packaging.python.org/science/] aún no disponible como archivo wheel precompilado pueden ser de ayuda para obtener otras extensiones binarias sin tener que compilarlas localmente.

Ver también

Guía de usuario de empaquetado de Python: Extensiones binarias [https://packaging.python.org/extensions/]

Comos (HOWTOs) de Python

Los Comos (HOWTOs) de Python son documentos que cubren un sólo tema específico e intentan cubrirlo de manera bastante completa. Siguiendo el modelo de la colección HOWTO del Proyecto de documentación de Linux, esta colección es un esfuerzo para fomentar la documentación que es más detallada que la Referencia de la biblioteca de Python.

Actualmente, los Comos (HOWTOs) son:

Portando código de Python 2 a Python 3

Portar módulos de extensión a Python 3

Programación de Curses con Python

Guía práctica de uso de los descriptores

HOWTO - Programación funcional

HOWTO Hacer Registros (Logging)

Libro de recetas de Logging

Expresiones regulares COMOS (HOWTO)

HOW TO - Programación con sockets

HOW TO - Ordenar

CÓMO (HOWTO) Unicode

HOWTO - Cómo obtener recursos de Internet con el paquete urllib

Tutorial de Argparse

Introducción al modulo ipaddress

How-To Argument Clinic

Instrumentación de CPython con DTrace y SystemTap

Portando código de Python 2 a Python 3

autor

Brett Cannon

Resumen

Dado que Python 3 es el futuro de Python mientras Python 2 todavía está en uso activo, es bueno tener su proyecto disponible para ambas versiones principales de Python. Esta guía está diseñada para ayudarle a averiguar la mejor manera de admitir Python 2 y 3 simultáneamente.

Si está buscando portar un módulo de extensión en lugar de código Python puro, consulte Portar módulos de extensión a Python 3.

Si desea leer la opinión de un desarrollador central de Python sobre por qué Python 3 nació, puede leer las Python 3 Q & A [https://ncoghlan-devs-python-notes.readthedocs.io/en/latest/python3/questions_and_answers.html] de Nick Coghlan o el artículo de Brett Cannon Why Python 3 exists [https://snarky.ca/why-python-3-exists].

For help with porting, you can view the archived python-porting [https://mail.python.org/pipermail/python-porting/] mailing list.

La breve explicación

Para que su proyecto sea compatible con Python 2/3 de una sola fuente, los pasos básicos son:

Sólo preocúpate por admitir Python 2.7

Asegúrese de tener una buena cobertura de prueba (coberturas.py [https://pypi.org/project/coverage] puede ayudar; python -m pip install coverage)

Aprende las diferencias entre Python 2 & 3

Utilice Futurize [http://python-future.org/automatic_conversion.html] (o Modernize [https://python-modernize.readthedocs.io/]) para actualizar su código (por ejemplo, python -m pip install future)

Use Pylint [https://pypi.org/project/pylint] para asegurarse de que no retrocede en su compatibilidad con Python 3 (python -m pip install pylint)

Use caniusepython3 [https://pypi.org/project/caniusepython3] para averiguar cuáles de sus dependencias están bloqueando el uso de Python 3 (python -m pip install caniusepython3)

Una vez que sus dependencias ya no lo bloqueen, use la integración continua para asegurarse de que sigue siendo compatible con Python 2 y 3 (tox [https://pypi.org/project/tox] puede ayudar a probar contra múltiples versiones de Python; python -m pip install tox)

Considere usar la verificación de tipo estática opcional para asegurarse de que su uso de tipo funcione tanto en Python 2 como en 3 (por ejemplo, use mypy [http://mypy-lang.org/] para verificar su escritura en Python 2 y Python 3; python -m pip install mypy).

Nota

Nota: El uso de python -m pip install garantiza que el pip que invoca es el que está instalado para el Python actualmente en uso, ya sea un pip de todo el sistema o uno instalado dentro de un entorno virtual.

Detalles

Un punto clave sobre el soporte de Python 2 & 3 simultáneamente es que se puede empezar hoy! Incluso si sus dependencias no son compatibles con Python 3 todavía eso no significa que no puede modernizar el código ahora para admitir Python 3. La mayoría de los cambios necesarios para admitir Python 3 conducen a código más limpio utilizando prácticas más recientes incluso en código Python 2.

Otro punto clave es que la modernización del código de Python 2 para que también admita Python 3 está en gran medida automatizada para usted. Si bien es posible que tenga que tomar algunas decisiones de API gracias a python 3 aclarando los datos de texto frente a los datos binarios, el trabajo de nivel inferior ahora se realiza principalmente por usted y, por lo tanto, al menos puede beneficiarse de los cambios automatizados inmediatamente.

Tenga en cuenta esos puntos clave mientras lee sobre los detalles de la migración del código para admitir Python 2 & 3 simultáneamente.

Compatibilidad con Python 2.6 y versiones anteriores

Si bien puede hacer que Python 2.5 funcione con Python 3, es mucho más fácil si solo tiene que trabajar con Python 2.7. Si eliminar Python 2.5 no es una opción, entonces el proyecto six [https://pypi.org/project/six] puede ayudarlo a admitir Python 2.5 y 3 simultáneamente (python -m pip install six). Sin embargo, tenga en cuenta que casi todos los proyectos enumerados en este COMO no estarán disponibles para usted.

Si puede omitir Python 2.5 y versiones anteriores, los cambios necesarios en el código deben seguir pareciendo código Python idiomático. En el peor de los casos tendrá que utilizar una función en lugar de un método en algunos casos o tendrá que importar una función en lugar de usar una integrada, pero de lo contrario la transformación general no debería sentirse ajena a usted.

Pero usted debe apuntar a sólo apoyar Python 2.7. Python 2.6 ya no se admite libremente y, por lo tanto, no recibe correcciones de errores. Esto significa que usted tendrá que solucionar cualquier problema que encuentre con Python 2.6. También hay algunas herramientas mencionadas en este HOWTO que no son compatibles con Python 2.6 (por ejemplo, Pylint [https://pypi.org/project/pylint]), y esto se volverá más común a medida que pasa el tiempo. Simplemente será más fácil para usted si sólo admite las versiones de Python que tiene que admitir.

Asegúrese de especificar el soporte de versión adecuado en su archivo setup.py

En su archivo setup.py debe tener el trove classifier [https://pypi.org/classifiers] adecuado especificando qué versiones de Python admite. Como su proyecto no es compatible con Python 3, al menos debe tener Programming Language :: Python :: 2 :: Only especificado. Idealmente también debe especificar cada versión principal/menor de Python que admita, por ejemplo, Programming Language :: Python :: 2.7.

Tener una buena cobertura de prueba

Una vez que tenga su código compatible con la versión más antigua de Python 2 que desee, querrá asegurarse de que su conjunto de pruebas tenga una buena cobertura. Una buena regla general es que si desea tener la suficiente confianza en su conjunto de pruebas, cualquier falla que aparezca después de que las herramientas reescriban su código son errores reales en las herramientas y no en su código. Si desea un número al que apuntar, intente obtener una cobertura superior al 80% (y no se sienta mal si le resulta difícil obtener una cobertura superior al 90%). Si aún no tiene una herramienta para medir la cobertura de la prueba, se recomienda cover.py [https://pypi.org/project/coverage].

Aprende las diferencias entre Python 2 & 3

Una vez que tenga su código bien probado, ¡está listo para comenzar a migrar su código a Python 3! Pero para comprender completamente cómo va a cambiar el código y qué desea tener en cuenta mientras codifica, querrá aprender qué cambios produce Python 3 en términos de Python 2. Típicamente las dos mejores maneras de hacer eso es leer la documentación «What’s New» para cada versión de Python 3 y el libro Porting to Python 3 [http://python3porting.com/] (que es gratis en línea). También hay una práctica cheat sheet [http://python-future.org/compatible_idioms.html] del proyecto Python-Future.</whatsnew-index>.

Actualiza tu código

Una vez que sientas que sabes lo que es diferente en Python 3 en comparación con Python 2, ¡es hora de actualizar tu código! Puede elegir entre dos herramientas para migrar el código automáticamente: Futurize [http://python-future.org/automatic_conversion.html] y Modernize [https://python-modernize.readthedocs.io/]. La herramienta que elija dependerá de la cantidad similar a Python 3 que desea que sea el código. Futurize [http://python-future.org/automatic_conversion.html] hace todo lo posible para que Python 3 modismos y prácticas existan en Python 2, por ejemplo, backporting el tipo bytes de Python 3 para que tenga paridad semántica entre las versiones principales de Python. Modernize [https://python-modernize.readthedocs.io/], por otro lado, es más conservador y se dirige a un subconjunto de Python 2/3 de Python, basándose directamente en six [https://pypi.org/project/six] para ayudar a proporcionar compatibilidad. Como Python 3 es el futuro, podría ser mejor considerar Futurize para comenzar a adaptarse a cualquier nueva práctica que Python 3 introduce a la que aún no está acostumbrado.

Independientemente de la herramienta que elija, actualizarán el código para que se ejecute en Python 3 mientras se mantienen compatibles con la versión de Python 2 con la que comenzó. Dependiendo de lo conservador que desee ser, es posible que desee ejecutar la herramienta sobre el conjunto de pruebas primero e inspeccionar visualmente la diferencia para asegurarse de que la transformación es precisa. Después de transformar el conjunto de pruebas y comprobar que todas las pruebas siguen pasando según lo esperado, puede transformar el código de la aplicación sabiendo que cualquier prueba que falle es un error de traducción.

Desafortunadamente, las herramientas no pueden automatizar todo para que su código funcione bajo Python 3 y por lo que hay un puñado de cosas que tendrá que actualizar manualmente para obtener soporte completo de Python 3 (cuáles de estos pasos son necesarios varían entre las herramientas). Lea la documentación de la herramienta que elige utilizar para ver lo que corrige de forma predeterminada y lo que puede hacer opcionalmente para saber lo que (no) se fijará para usted y lo que puede tener que corregir por su cuenta (por ejemplo, usando io.open() sobre la función incorporada open() está desactivada por defecto en Modernizar). Afortunadamente, sin embargo, sólo hay un par de cosas a tener en cuenta por las cuales se pueden considerar grandes problemas que pueden ser difíciles de depurar si no se observan.

División

En Python 3, 5 / 2 == 2.5 y no 2; toda división entre los valores int da lugar a un float. Este cambio ha sido planeado desde Python 2.2, que fue lanzado en 2002. Desde entonces, se ha alentado a los usuarios a añadir from __future__ import division a todos y cada uno de los archivos que utilizan los operadores / y // o que ejecuten el intérprete con el indicador -Q. Si no ha estado haciendo esto, entonces tendrá que ir a través de su código y hacer dos cosas:

Añadir from __future__ import division a sus archivos

Actualice cualquier operador de división según sea necesario para utilizar // para usar la división de suelo o continuar usando / y esperar un número flotante

La razón por la que / no se traduce simplemente a // automáticamente es que si un objeto define un método __truediv__ pero no __floordiv__ entonces su código comenzaría a fallar (por ejemplo, una clase definida por el usuario que utiliza / para significar alguna operación pero no // para la misma cosa o en absoluto).

Texto frente a datos binarios

En Python 2 puede usar el tipo str tanto para texto como para datos binarios. Desafortunadamente, esta confluencia de dos conceptos diferentes podría conducir a código frágil que a veces funcionaba para cualquier tipo de datos, a veces no. También podría dar lugar a API confusas si las personas no declaraban explícitamente que algo que aceptaba str aceptaba datos binarios o de texto en lugar de un tipo específico. Esto complicó la situación especialmente para cualquier persona que admita varios idiomas, ya que las API no se molestarían explícitamente en admitir explícitamente Unicode cuando reclamaban compatibilidad con datos de texto.

Para hacer la distinción entre texto y datos binarios más claros y pronunciados, Python 3 hizo lo que la mayoría de los lenguajes creados en la era de Internet han hecho y ha hecho texto y datos binarios distintos tipos que no se pueden mezclar ciegamente (Python es anterior al acceso generalizado a Internet). Para cualquier código que se ocupe solo de texto o solo de datos binarios, esta separación no plantea un problema. Pero para el código que tiene que lidiar con ambos, significa que es posible que tenga que preocuparse ahora cuando está utilizando texto en comparación con los datos binarios, por lo que esto no se puede automatizar por completo.

Para empezar, tendrá que decidir qué API toman texto y cuáles toman binario (es altamente recomendado no diseñar API que pueden tomar ambos debido a la dificultad de mantener el código funcionando; como se indicó anteriormente es difícil hacerlo bien). En Python 2 esto significa asegurarse de que las API que toman texto pueden trabajar con unicode y las que funcionan con datos binarios funcionan con el tipo bytes de Python 3 (que es un subconjunto de str en Python 2 y actúa como un alias para bytes tipo en Python 2). Por lo general, el mayor problema es darse cuenta de qué métodos existen en qué tipos en Python 2 y 3 simultáneamente (para el texto que es Unicode en Python 2 y str en Python 3, para binario que es str/bytes en Python 2 y bytes en Python 3). En la tabla siguiente se enumeran los métodos unicos de cada tipo de datos en Python 2 y 3 (por ejemplo, el método decode() se puede utilizar en el tipo de datos binarios equivalente en Python 2 o 3, pero no puede ser utilizado por el tipo de datos textuales consistentemente entre Python 2 y 3 porque str en Python 3 no tiene el método). Tenga en cuenta que a partir de Python 3.5 se agregó el método __mod__ al tipo bytes.

Datos de texto

Datos binarios

decode

encode

format

isdecimal

isnumeric

La creación de la distinción más fácil de controlar se puede realizar mediante la codificación y descodificación entre datos binarios y texto en el borde del código. Esto significa que cuando reciba texto en datos binarios, debe descodificarlo inmediatamente. Y si el código necesita enviar texto como datos binarios, codificarlo lo más tarde posible. Esto permite que el código funcione solo con texto internamente y, por lo tanto, elimina tener que realizar un seguimiento del tipo de datos con los que está trabajando.

El siguiente problema es asegurarse de saber si los literales de cadena en el código representan texto o datos binarios. Debe agregar un prefijo b a cualquier literal que presente datos binarios. Para el texto debe agregar un prefijo u al literal de texto. (hay una importación __future__ para forzar que todos los literales no especificados sean Unicode, pero el uso ha demostrado que no es tan eficaz como agregar un prefijo b o u a todos los literales explícitamente)

Como parte de esta dicotomía también hay que tener cuidado con la apertura de archivos. A menos que haya estado trabajando en Windows, existe la posibilidad de que no siempre se haya molestado en agregar el modo b al abrir un archivo binario (por ejemplo, rb para la lectura binaria). En Python 3, los archivos binarios y los archivos de texto son claramente distintos y mutuamente incompatibles; ver el módulo io para más detalles. Por lo tanto, debe tomar una decisión de si un archivo se utilizará para el acceso binario (permitiendo que los datos binarios se lean y/o escriban) o el acceso textual (permitiendo que los datos de texto sean leídos y/o escritos). También debe utilizar io.open() para abrir archivos en lugar de la función incorporada open() como el módulo io es consistente de Python 2 a 3, mientras que la función incorporada open() no es (en Python 3 es en realidad io.open()). No se moleste con la práctica obsoleta de usar codecs.open() ya que sólo es necesario para mantener la compatibilidad con Python 2.5.

Los constructores de str y bytes tienen una semántica diferente para los mismos argumentos entre Python 2 y 3. Pasar un entero a bytes en Python 2 le dará la representación de cadena de texto del entero: bytes(3) == '3'. Pero en Python 3, un argumento entero para “”bytes”” le dará un objeto bytes siempre y cuando el entero especificado, lleno de bytes nulos: bytes(3) == b'\x00\x00\x00'. Una preocupación similar es necesaria cuando se pasa un objeto bytes a str. En Python 2, solo se obtiene el objeto bytes: str(b'3') == b'3'. Pero en Python 3 se obtiene la representación de cadena de texto del objeto bytes: str(b'3') == "b'3'".

Por último, la indexación de datos binarios requiere un control cuidadoso (el corte no requiere ningún control especial). En Python 2, b'123'[1] == b'2' mientras que en Python 3 b'123'[1] == 50. Dado que los datos binarios son simplemente una colección de números binarios, Python 3 devuelve el valor entero para el byte en el que indexa. Pero en Python 2, ya que bytes == str, la indexación devuelve un segmento de bytes de un solo elemento. El proyecto six [https://pypi.org/project/six] tiene una función denominada six.indexbytes() que devolverá un entero como en Python 3: six.indexbytes(b'123', 1).

Para resumir:

Decida cuál de sus API toma texto y cuáles toman datos binarios

Asegúrese de que el código que funciona con texto también funciona con unicode y el código para datos binarios funciona con bytes en Python 2 (consulte la tabla anterior para los métodos que no puede usar para cada tipo)

Marque todos los literales binarios con un prefijo b, literales textuales con un prefijo u

Descodificar datos binarios en texto tan pronto como sea posible, codificar texto como datos binarios tan tarde como sea posible

Abra los archivos con io.open() y asegúrese de especificar el modo b cuando sea apropiado

Tenga cuidado al indexar en datos binarios

Utilice la detección de funciones en lugar de la detección de versiones

Inevitablemente tendrá código que tiene que elegir qué hacer en función de qué versión de Python se está ejecutando. La mejor manera de hacerlo es con la detección de características de si la versión de Python en la que se ejecuta es compatible con lo que necesita. Si por alguna razón eso no funciona, entonces usted debe hacer que la comprobación de la versión sea contra Python 2 y no Python 3. Para ayudar a explicar esto, veamos un ejemplo.

Supongamos que necesita acceso a una característica de importlib que está disponible en la biblioteca estándar de Python desde Python 3.3 y disponible para Python 2 a través de importlib2 [https://pypi.org/project/importlib2] en PyPI. Es posible que tenga la tentación de escribir código para acceder, por ejemplo, al módulo importlib.abc haciendo lo siguiente:

import sys

if sys.version_info[0] == 3:
    from importlib import abc
else:
    from importlib2 import abc

El problema con este código es ¿qué sucede cuando sale Python 4? Sería mejor tratar Python 2 como el caso excepcional en lugar de Python 3 y asumir que las futuras versiones de Python serán más compatibles con Python 3 que Python 2:

import sys

if sys.version_info[0] > 2:
    from importlib import abc
else:
    from importlib2 import abc

La mejor solución, sin embargo, es no hacer ninguna detección de versiones en absoluto y en su lugar confiar en la detección de características. Esto evita cualquier problema potencial de conseguir la detección de la versión incorrecta y le ayuda a mantenerse compatible con el futuro:

try:
    from importlib import abc
except ImportError:
    from importlib2 import abc

Evitar regresiones de compatibilidad

Una vez que haya traducido completamente el código para que sea compatible con Python 3, querrá asegurarse de que el código no retroceda y deje de funcionar bajo Python 3. Esto es especialmente cierto si tiene una dependencia que le está bloqueando para que no se ejecute realmente en Python 3 en este momento.

Para ayudar a mantenerse compatible, los módulos nuevos que cree deben tener al menos el siguiente bloque de código en la parte superior del misma:

from __future__ import absolute_import
from __future__ import division
from __future__ import print_function

También puede ejecutar Python 2 con el indicador -3 para recibir una advertencia sobre varios problemas de compatibilidad que el código desencadena durante la ejecución. Si convierte las advertencias en errores con -Werror, puede asegurarse de que no se pierda accidentalmente una advertencia.

También puede usar el proyecto de Pylint [https://pypi.org/project/pylint] y su indicador --py3k para lintar el código para recibir advertencias cuando el código comienza a desviarse de la compatibilidad con Python 3. Esto también evita que tenga que ejecutar Modernize [https://python-modernize.readthedocs.io/] o Futurize [http://python-future.org/automatic_conversion.html] sobre el código con regularidad para detectar las regresiones de compatibilidad. Esto requiere que solo admita Python 2.7 y Python 3.4 o posterior, ya que es la compatibilidad mínima de la versión mínima de Python de Pylint.

Compruebe qué dependencias bloquean la transición

Después de que haya hecho que su código sea compatible con Python 3, debe empezar a preocuparse por si sus dependencias también se han portado. El proyecto caniusepython3 [https://pypi.org/project/caniusepython3] se creó para ayudarle a determinar qué proyectos – directa o indirectamente – le impiden admitir Python 3. Hay una herramienta de línea de comandos, así como una interfaz web en https://caniusepython3.com.

El proyecto también proporciona código que puede integrar en el conjunto de pruebas para que tenga una prueba con errores cuando ya no tenga dependencias que le impidan usar Python 3. Esto le permite evitar tener que comprobar manualmente sus dependencias y recibir notificaciones rápidamente cuando puede empezar a ejecutarse en Python 3.

Actualice su archivo setup.py para denotar compatibilidad con Python 3

Una vez que el código funciona en Python 3, debe actualizar los clasificadores en su setup.py para que contenga Programming Language :: Python :: 3 y no especificar solo compatibilidad con Python 2. Esto le dirá a cualquier persona que use su código que admite Python 2 y 3. Lo ideal es que también desee agregar clasificadores para cada versión principal/menor de Python que ahora admita.

Utilice la integración continua para seguir siendo compatible

Una vez que pueda ejecutar completamente bajo Python 3, querrá asegurarse de que el código siempre funciona en Python 2 y 3. Probablemente la mejor herramienta para ejecutar las pruebas en varios intérpretes de Python es tox [https://pypi.org/project/tox]. A continuación, puede integrar tox con su sistema de integración continua para que nunca interrumpa accidentalmente la compatibilidad con Python 2 o 3.

También es posible que desee utilizar el indicador -bb con el intérprete de Python 3 para desencadenar una excepción cuando se comparan bytes con cadenas o bytes con un int (este último está disponible a partir de Python 3.5). De forma predeterminada, las comparaciones de tipos diferentes simplemente devuelven False, pero si cometió un error en la separación del control de datos de texto/binario o la indexación en bytes, no encontraría fácilmente el error. Esta marca generará una excepción cuando se produzcan este tipo de comparaciones, lo que hace que el error sea mucho más fácil de rastrear.

¡Y eso es sobre todo! En este punto, la base de código es compatible con Python 2 y 3 simultáneamente. Las pruebas también se configurarán para que no interrumpa accidentalmente la compatibilidad de Python 2 o 3, independientemente de la versión en la que ejecute normalmente las pruebas durante el desarrollo.

Considere la posibilidad de usar la comprobación de tipos estáticos opcionales

Otra forma de ayudar a transferir el código es usar un comprobador de tipos estáticos como mypy [http://mypy-lang.org/] o pytype [https://github.com/google/pytype] en el código. Estas herramientas se pueden utilizar para analizar el código como si se estuviera ejecutando en Python 2, puede ejecutar la herramienta por segunda vez como si el código se ejecutara en Python 3. Al ejecutar un comprobador de tipos estáticos dos veces como este, puede descubrir si, por ejemplo, está usando incorrectamente el tipo de datos binarios en una versión de Python en comparación con otra. Si agrega sugerencias de tipo opcionales al código, también puede indicar explícitamente si las API usan datos textuales o binarios, lo que ayuda a asegurarse de que todo funciona según lo esperado en ambas versiones de Python.

Portar módulos de extensión a Python 3

Recomendamos los siguientes recursos para portar módulos de extensiones a Python 3:

El capítulo Migrating C extensions [http://python3porting.com/cextensions.html] de Support Python 3: An in-depth guide, un libro sobre migrar de Python 2 a Python 3 en general, guía al lector a través cómo portar un módulo de extensión.

La Porting guide [https://py3c.readthedocs.io/en/latest/guide.html] de el proyecto py3c provee sugerencias dogmáticas con código de ejemplo.

Las bibliotecas Cython [http://cython.org/] y CFFI [https://cffi.readthedocs.io/en/latest/] ofrecen abstracciones sobre la API C de Python. Generalmente, las extensiones necesitan ser re-escritas para usar uno de ellos, pero la biblioteca luego gestiona las diferencias entre las diferentes versiones de Python y sus implementaciones.

Programación de Curses con Python

Autor

A.M. Kuchling, Eric S. Raymond

Versión

2.04

Resumen

Este documento describe cómo usar el módulo de extensión curses para controlar las pantallas en modo texto.

Qué es curses?

La biblioteca curses proporciona una instalación independiente del terminal para manejo de teclado e impresión de pantalla en terminales basados en texto; tales terminales incluyen VT100, la consola de Linux y el terminal simulado proporcionado por varios programas. Los terminales de pantalla admiten varios códigos de control para realizar operaciones comunes, como mover el cursor, desplazar la pantalla y borrar áreas. Diferentes terminales utilizan códigos muy diferentes y, a menudo, tienen sus propias peculiaridades menores.

En un mundo de pantallas gráficas, uno podría preguntarse « ¿por qué molestarse »? Es cierto que los terminales de pantalla de celdas de caracteres son una tecnología obsoleta, pero hay nichos en los que poder hacer cosas elegantes con ellos sigue siendo valioso. Un nicho está en pequeños Unix incrustados o pequeñas marcas que no ejecutan un servidor X. Por otro lado herramientas como los instaladores del sistema operativo y los configuradores de kernel que pueden tener que ejecutarse antes de que haya soporte gráfico disponible.

La biblioteca curses proporciona una funcionalidad bastante básica, proporcionando al programador una abstracción de una pantalla que contiene múltiples ventanas de texto no superpuestas. El contenido de una ventana se puede cambiar de varias maneras (agregando texto, borrándolo, cambiando su apariencia) y la biblioteca curses descubrirá que códigos de control deben enviarse al terminal para producir la salida correcta. curses no proporciona muchos conceptos de interfaz de usuario como botones, casillas de verificación o cuadros de diálogo; Si necesita tales funciones, considere una biblioteca de interfaz de usuario como Urwid <https://pypi.org/project/urwid/> _.

La biblioteca curses se escribió originalmente para BSD Unix; Las versiones posteriores de Unix de System V de AT&T agregaron muchas mejoras y nuevas funciones. BSD curses ya no se mantiene, ya que ha sido reemplazado por ncurses, que es una implementación de código abierto de la interfaz AT&T. Si está utilizando un Unix de código abierto como Linux o FreeBSD, su sistema casi seguro usa ncurses. Como la mayoría de las versiones comerciales actuales de Unix se basan en el código del Sistema V, todas las funciones descritas aquí probablemente estarán disponibles. Sin embargo, las versiones anteriores de curses llevadas por algunos Unix propietarios no pueden admitir todo.

The Windows version of Python doesn’t include the curses module. A ported version called UniCurses [https://pypi.org/project/UniCurses] is available.

El módulo curses de Python

El módulo Python es un envoltorio bastante simple sobre las funciones C proporcionadas por curses; si ya está familiarizado con la programación de curses en C, es muy fácil transferir ese conocimiento a Python. La mayor diferencia es que la interfaz de Python simplifica las cosas al combinar diferentes funciones de C como addtr() , mvaddstr() , y mvwaddstr() en un solo método addstr(). Verá esto cubierto con más detalle más adelante.

Este HOWTO es una introducción a la escritura de programas en modo texto con curses y Python. No intenta ser una guía completa de la API de curses; para eso, vea la sección de la guía de la biblioteca de Python sobre ncurses, y las páginas del manual de C para ncurses. Sin embargo, le dará las ideas básicas.

Iniciar y finalizar una aplicación de curses

Antes de hacer cualquier cosa, curses deben ser inicializadas. Esto se realiza llamando a la función initscr(), que determinará el tipo de terminal, enviará los códigos de configuración necesarios al terminal y creará varias estructuras de datos internas. Si tiene éxito, initscr() devuelve un objeto de ventana que representa la pantalla completa; Esto generalmente se llama stdscr después del nombre de la variable C correspondiente.

import curses
stdscr = curses.initscr()

Por lo general, las aplicaciones de curses desactivan el eco automático de las teclas en la pantalla, para poder leer las teclas y solo mostrarlas bajo ciertas circunstancias. Esto requiere llamar a la función noecho() function.

curses.noecho()

Las aplicaciones también tendrán que reaccionar a las teclas al instante, sin necesidad de presionar la tecla Intro; Esto se llama modo cbreak, en oposición al modo de entrada almacenado en memoria intermedia habitual.

curses.cbreak()

Los terminales generalmente devuelven teclas especiales, como las teclas del cursor o las teclas de navegación, como Re Pág e Inicio, como una secuencia de escape multibyte. Si bien puede escribir su aplicación para esperar tales secuencias y procesarlas en consecuencia, curses pueden hacerlo por usted, retornando un valor especial como curses.KEY_LEFT. Para obtener que curses haga el trabajo, deberá habilitar el modo de teclado.

stdscr.keypad(True)

Terminar una aplicación de curses es mucho más fácil que iniciar una. Tendrás que llamar a

curses.nocbreak()
stdscr.keypad(False)
curses.echo()

para revertir la configuración de terminal amigable de curses. Llame luego a la función endwin() para restaurar el terminal a su modo operativo original.

curses.endwin()

Un problema común al depurar una aplicación curses es hacer que su terminal se estropee cuando la aplicación muere sin restaurar el terminal a su estado anterior. En Python, esto ocurre comúnmente cuando su código tiene errores y genera una excepción no detectada. Las teclas ya no se repiten en la pantalla cuando las escribe, por ejemplo, lo que dificulta el uso del shell.

En Python puede evitar estas complicaciones y facilitar la depuración importando la función curses.wrapper() y usándola así:

from curses import wrapper

def main(stdscr):
    # Clear screen
    stdscr.clear()

    # This raises ZeroDivisionError when i == 10.
    for i in range(0, 11):
        v = i-10
        stdscr.addstr(i, 0, '10 divided by {} is {}'.format(v, 10/v))

    stdscr.refresh()
    stdscr.getkey()

wrapper(main)

La función wrapper() toma un objeto invocable y realiza las inicializaciones descritas anteriormente, también inicializa los colores si hay soporte de color. wrapper() luego ejecuta su invocable proporcionado. Una vez que vuelve a llamarse, wrapper() restaurará el estado original del terminal. El invocable se llama dentro de try…except que captura excepciones, restaura el estado del terminal y luego vuelve a generar la excepción. Por lo tanto, su terminal no se quedará en un estado extraño de excepción y podrá leer el mensaje de la excepción y el rastreo.

Ventanas y pads

Las ventanas son la abstracción básica en curses. Un objeto de ventana representa un área rectangular de la pantalla y admite métodos para mostrar texto, borrarlo, permitir al usuario ingresar cadenas, etc.

El objeto stdscr devuelto por la función initscr() es un objeto de ventana que cubre toda la pantalla. Es posible que muchos programas solo necesiten esta única ventana, pero es posible que desee dividir la pantalla en ventanas más pequeñas para volver a dibujarlas o borrarlas por separado. La función newwin() crea una nueva ventana de un tamaño dado, retornando el nuevo objeto de ventana.

begin_x = 20; begin_y = 7
height = 5; width = 40
win = curses.newwin(height, width, begin_y, begin_x)

Tenga en cuenta que el sistema de coordenadas utilizado en curses es inusual. Las coordenadas siempre se pasan en el orden y,x, y la esquina superior izquierda de una ventana es la coordenada (0,0). Esto rompe la convención normal para manejar coordenadas donde la coordenada x es lo primero. Esta es una desafortunada diferencia de la mayoría de las otras aplicaciones informáticas, pero ha sido parte de curses desde que se escribió por primera vez, y ahora es demasiado tarde para cambiar las cosas.

Su aplicación puede determinar el tamaño de la pantalla utilizando las variables curses.LINES y curses.COLS para obtener los tamaños y y x. Las coordenadas legales se extenderán de (0,0) a (curses.LINES - 1, curses.COLS - 1).

Cuando llama a un método para mostrar o borrar texto, el efecto no aparece inmediatamente en la pantalla. En su lugar, debe llamar al método refresh() de los objetos de ventana para actualizar la pantalla.

Esto se debe a que curses se escribieron originalmente teniendo en cuenta las conexiones de terminales lentas de 300 baudios; con estos terminales, era muy importante minimizar el tiempo requerido para volver a dibujar la pantalla. En cambio, curses acumula cambios en la pantalla y los muestra de la manera más eficiente cuando llama refresh(). Por ejemplo, si su programa muestra algo de texto en una ventana y luego borra la ventana, no hay necesidad de enviar el texto original porque nunca son visibles.

En la práctica, decirle explícitamente a curses que vuelva a dibujar una ventana no complica mucho la programación con curses. La mayoría de los programas entran en una gran cantidad de actividad y luego se detienen a la espera de que se presione una tecla u otra acción por parte del usuario. Todo lo que tiene que hacer es asegurarse de que la pantalla se haya re-dibujado antes de hacer una pausa para esperar la entrada del usuario, llamando primero a stdscr.refresh() o al método refresh() de alguna otra ventana relevante.

Un pad es un caso especial de una ventana; puede ser más grande que la pantalla de visualización real, y solo se muestra una parte del pad a la vez. La creación de un pad requiere la altura y el ancho del pad, mientras que la actualización de un pad requiere dar las coordenadas del área en pantalla donde se mostrará una subsección del pad.

pad = curses.newpad(100, 100)
# These loops fill the pad with letters; addch() is
# explained in the next section
for y in range(0, 99):
    for x in range(0, 99):
        pad.addch(y,x, ord('a') + (x*x+y*y) % 26)

# Displays a section of the pad in the middle of the screen.
# (0,0) : coordinate of upper-left corner of pad area to display.
# (5,5) : coordinate of upper-left corner of window area to be filled
#         with pad content.
# (20, 75) : coordinate of lower-right corner of window area to be
#          : filled with pad content.
pad.refresh( 0,0, 5,5, 20,75)

La llamada refresh() muestra una sección del pad en el rectángulo que se extiende desde la coordenada (5,5) hasta la coordenada (20,75) en la pantalla; la esquina superior izquierda de la sección mostrada es la coordenada (0,0) en el pad. Más allá de esa diferencia, los pads son exactamente como las ventanas normales y admiten los mismos métodos.

Si tiene varias ventanas y almohadillas en la pantalla, hay una manera más eficiente de actualizar la pantalla y evitar el molesto parpadeo de la pantalla a medida que se actualiza cada parte de la pantalla. refresh() en realidad hace dos cosas:

Llama al método noutrefresh() de cada ventana para actualizar una estructura de datos subyacente que representa el estado deseado de la pantalla.

Llama a la función doupdate() para cambiar la pantalla física para que coincida con el estado deseado registrado en la estructura de datos.

En su lugar, puede llamar a noutrefresh() en varias ventanas para actualizar la estructura de datos, y luego llamar a doupdate() para actualizar la pantalla.

Mostrando el texto

Desde el punto de vista de un programador en C, curses a veces puede parecer un laberinto retorcido de funciones, todas sutilmente diferentes. Por ejemplo, addtr() muestra una cadena en la ubicación actual del cursor en la ventana stdscr, mientras que mvaddstr() se mueve a una determinada coordenada y, x primero antes de mostrar la cadena . waddstr() es como addtr(), pero permite especificar una ventana para usar en lugar de usar stdscr por defecto. mvwaddstr() permite especificar tanto una ventana como una coordenada.

Afortunadamente, la interfaz de Python oculta todos estos detalles. stdscr es un objeto de ventana como cualquier otro, y métodos como addstr() aceptan múltiples formas de argumento. Por lo general, hay cuatro formas diferentes.

Formas

Descripción

str o ch

Mostrar la cadena str o el carácter ch en la posición actual

str o ch, attr

Muestra la cadena str o el carácter ch, utilizando el atributo attr en la posición actual

y, x, str o ch

Moverse a la posición y,x dentro de la ventana, y mostrar st o ch

y, x, str o ch, attr

Muévase a la posición y, x dentro de la ventana y muestre str o ch, usando el atributo attr

Los atributos permiten mostrar texto en formas resaltadas como negrita, subrayado, código inverso o en color. Se explicarán con más detalle en la siguiente subsección.

El método addstr() toma una cadena de Python o una cadena de bytes como el valor que se mostrará. El contenido de las cadenas de bytes se envía al terminal tal como está. Las cadenas se codifican en bytes utilizando el valor del atributo de la ventana encoding; Esto se establece de manera predeterminada en la codificación predeterminada del sistema que devuelve locale.getpreferredencoding().

Los métodos addch() toman un carácter, que puede ser una cadena de longitud 1, una cadena de bytes de longitud 1 o un entero.

Se proporcionan constantes para los caracteres de extensión; estas constantes son enteros mayores que 255. Por ejemplo ACS_PLMINUS es un símbolo +/-, y ACS_ULCORNER es la esquina superior izquierda de un cuadro (útil para dibujar bordes). También puede usar el carácter Unicode apropiado.

Windows recuerda dónde se dejó el cursor después de la última operación, por lo que si deja de lado las coordenadas y, x, la cadena o el carácter se mostrarán donde se haya quedado la última operación. También puede mover el cursor con el método move(y, x). Debido a que algunos terminales siempre muestran un cursor parpadeante, es posible que desee asegurarse de que el cursor esté ubicado en algún lugar donde no distraiga; Puede ser confuso tener el cursor parpadeando en alguna ubicación aparentemente aleatoria.

Si su aplicación no necesita un cursor parpadeante, puede llamar a curs_set (False) para hacerla invisible. Para compatibilidad con versiones anteriores de curses, hay una función jeaveok (bool) que es sinónimo de curs_set(). Cuando bool es verdadero, la biblioteca curses intentará suprimir el cursor parpadeante, y no tendrá que preocuparse por dejarlo en ubicaciones extrañas.

Atributos y color

Los caracteres se pueden mostrar de diferentes maneras. Las líneas de estado en una aplicación basada en texto se muestran comúnmente en video inverso, o un visor de texto puede necesitar resaltar ciertas palabras. curses admite esto al permitirle especificar un atributo para cada celda en la pantalla.

Un atributo es un entero, cada bit representa un atributo diferente. Puede intentar mostrar texto con múltiples conjuntos de bits de atributos, pero curses no garantizan que todas las combinaciones posibles estén disponibles, o que todas sean visualmente distintas. Eso depende de la capacidad del terminal que se utilice, por lo que es más seguro apegarse a los atributos más comúnmente disponibles, enumerados aquí.

Atributo

Descripción

A_BLINK

Texto parpadeante

A_BOLD

Texto extra brillante o en negrita

A_DIM

Texto medio brillante

A_REVERSE

Texto de video inverso

A_STANDOUT

El mejor modo de resaltado disponible

A_UNDERLINE

Texto subrayado

Entonces, para mostrar una línea de estado de video inverso en la línea superior de la pantalla, puede codificar:

stdscr.addstr(0, 0, "Current mode: Typing mode",
              curses.A_REVERSE)
stdscr.refresh()

La biblioteca curses también admite color en los terminales que lo proporcionen. El terminal más común es probablemente la consola de Linux, seguido de xterms en color.

Para usar el color, debe llamar a la función start_color() poco después de llamar initscr(), para inicializar el conjunto de colores predeterminado (la función curses.wrapper() hace esto automáticamente). Una vez hecho esto, la función has_colors() devuelve TRUE si el terminal en uso realmente puede mostrar color. (Nota: curses usa el ‘color’ de la ortografía estadounidense, en lugar del ‘color’ de la ortografía canadiense/británica. Si está acostumbrado a la ortografía británica, tendrá que resignarse a escribir mal por el bien de estas funciones. )

La biblioteca curses mantiene un número finito de pares de colores, que contienen un color de primer plano (o texto) y un color de fondo. Puede obtener el valor del atributo correspondiente a un par de colores con la función color_pair(); esto puede ser operado bit a bit con otros atributos como A_REVERSE, pero nuevamente, no se garantiza que tales combinaciones funcionen en todos los terminales.

Un ejemplo, que muestra una línea de texto usando el par de colores 1

stdscr.addstr("Pretty text", curses.color_pair(1))
stdscr.refresh()

Como dije antes, un par de colores consiste en un color de primer plano y de fondo. La función init_pair (n, f, b) cambia la definición del par de colores n, a color de primer plano f y color de fondo b. El par de colores 0 está cableado a blanco sobre negro, y no se puede cambiar.

Los colores están numerados y start_color() inicializa 8 colores básicos cuando activa el modo de color. Son: 0:negro, 1:rojo, 2:verde, 3:amarillo, 4:azul, 5:magenta, 6:cian y 7:blanco. El módulo curses define constantes con nombre para cada uno de estos colores: curses.COLOR_BLACK, curses.COLOR_RED, y así sucesivamente.

Pongamos todo esto juntos. Para cambiar el color 1 al texto rojo sobre un fondo blanco, debe llamar a:

curses.init_pair(1, curses.COLOR_RED, curses.COLOR_WHITE)

Cuando cambia un par de colores, cualquier texto que ya se muestre usando ese par de colores cambiará a los nuevos colores. También puede mostrar texto nuevo en este color con:

stdscr.addstr(0,0, "RED ALERT!", curses.color_pair(1))

Los terminales muy elegantes pueden cambiar las definiciones de los colores reales a un valor RGB dado. Esto le permite cambiar el color 1, que generalmente es rojo, a púrpura o azul o cualquier otro color que desee. Desafortunadamente, la consola de Linux no admite esto, por lo que no puedo probarlo y no puedo proporcionar ningún ejemplo. Puede verificar si su terminal puede hacer esto llamando a can_change_color(), que devuelve Verdadero si la capacidad está ahí. Si tiene la suerte de tener un terminal tan talentoso, consulte las páginas de manual de su sistema para obtener más información.

Input del usuario

La biblioteca C curses ofrece solo mecanismos de entrada muy simples. El módulo Python curses agrega un widget básico de entrada de texto. (Otras bibliotecas como Urwid [https://pypi.org/project/urwid/] tienen colecciones más extensas de widgets).

Hay dos métodos para obtener información desde una ventana:

getch() actualiza la pantalla y luego espera a que el usuario presione una tecla, mostrando la tecla si echo() ha sido llamado anteriormente. Opcionalmente, puede especificar una coordenada a la que se debe mover el cursor antes de pausar.

getkey() hace lo mismo pero convierte el entero en una cadena. Los caracteres individuales se devuelven como cadenas de 1 carácter, y las teclas especiales como las teclas de función devuelven cadenas más largas que contienen un nombre de tecla como KEY_UP o ^ G.

Es posible no esperar al usuario utilizando el método de ventana nodelay(). Después de nodelay(True), getch() y getkey() para que la ventana no se bloquee. Para indicar que no hay ninguna entrada lista, getch() devuelve curses.ERR (un valor de -1) y getkey() genera una excepción. También hay una función halfdelay(), que se puede usar para (en efecto) establecer un temporizador en cada getch(); Si no hay entrada disponible dentro de un retraso especificado (medido en décimas de segundo), curses generan una excepción.

El método getch() devuelve un entero; si está entre 0 y 255, representa el código ASCII de la tecla presionada. Los valores superiores a 255 son teclas especiales como Re Pág, Inicio o las teclas del cursor. Puede comparar el valor devuelto a constantes como curses.KEY_PPAGE, curses.KEY_HOME, o curses.KEY_LEFT. El bucle principal de su programa puede verse así:

while True:
    c = stdscr.getch()
    if c == ord('p'):
        PrintDocument()
    elif c == ord('q'):
        break  # Exit the while loop
    elif c == curses.KEY_HOME:
        x = y = 0

El módulo curses.ascii proporciona funciones de membresía de clase ASCII que toman argumentos de cadena de entero o de 1 carácter; Estos pueden ser útiles para escribir pruebas más legibles para dichos bucles. También proporciona funciones de conversión que toman argumentos enteros o de cadena de 1 carácter y devuelven el mismo tipo. Por ejemplo, curses.ascii.ctrl() devuelve el carácter de control correspondiente a su argumento.

También hay un método para recuperar una cadena completa, getstr(). No se usa con mucha frecuencia, porque su funcionalidad es bastante limitada; Las únicas teclas de edición disponibles son la tecla de retroceso y la tecla Intro, que termina la cadena. Opcionalmente, puede limitarse a un número fijo de caracteres.

curses.echo()            # Enable echoing of characters

# Get a 15-character string, with the cursor on the top line
s = stdscr.getstr(0,0, 15)

El módulo curses.textpad proporciona un cuadro de texto que admite un conjunto de teclas tipo Emacs. Varios métodos de la clase Textbox admiten la edición con validación de entrada y recopilan los resultados de edición con o sin espacios finales. Aquí hay un ejemplo:

import curses
from curses.textpad import Textbox, rectangle

def main(stdscr):
    stdscr.addstr(0, 0, "Enter IM message: (hit Ctrl-G to send)")

    editwin = curses.newwin(5,30, 2,1)
    rectangle(stdscr, 1,0, 1+5+1, 1+30+1)
    stdscr.refresh()

    box = Textbox(editwin)

    # Let the user edit until Ctrl-G is struck.
    box.edit()

    # Get resulting contents
    message = box.gather()

Consulte la documentación de la biblioteca sobre curses.textpad para más detalles.

Para más información

Este CÓMO no cubre algunos temas avanzados, como leer el contenido de la pantalla o capturar eventos del mouse desde una instancia de xterm, pero la página de la biblioteca de Python para el módulo curses ahora está razonablemente completa. Deberías buscarlo posteriormente.

Si tiene dudas sobre el comportamiento detallado de las funciones de curses, consulte las páginas del manual para su implementación de curses, ya sea ncurses o un proveedor exclusivo de Unix. Las páginas del manual documentarán cualquier peculiaridad y proporcionarán listas completas de todas las funciones, atributos y caracteres ACS_* disponibles para usted.

Debido a que la API de curses es tan grande, algunas funciones no son compatibles con la interfaz de Python. A menudo, esto no se debe a que sean difíciles de implementar, sino a que nadie los ha necesitado todavía. Además, Python aún no admite la biblioteca de menús asociada con ncurses. Los parches que agregan soporte para estos serían bienvenidos; consulte la Guía del desarrollador de Python [https://devguide.python.org/] para obtener más información sobre cómo enviar parches a Python.

Escribir programas con NCURSES [http://invisible-island.net/ncurses/ncurses-intro.html]: un extenso tutoría para programadores de C.

La página web con el manual de ncurses [https://linux.die.net/man/3/ncurses]

Preguntas y respuestas frecuentes de ncurses [http://invisible-island.net/ncurses/ncurses.faq.html]

«Use curses… don’t swear» [https://www.youtube.com/watch?v=eN1eZtjLEnU]: video de una charla de PyCon 2013 sobre el control de terminales usando curses o Urwid.

«Console Applications with Urwid» [http://www.pyvideo.org/video/1568/console-applications-with-urwid]: video de una charla de PyCon CA 2012 que muestra algunas aplicaciones escritas con Urwid.

Guía práctica de uso de los descriptores

Autor

Raymond Hettinger

Contacto

<python at rcn dot com>

Contenido

Guía práctica de uso de los descriptores

Guía introductoria

Ejemplo simple: un descriptor que retorna una constante

Búsquedas dinámicas

Atributos gestionados

Nombres personalizados

Pensamientos finales

Ejemplo completo práctico

Clase validadora

Validadores personalizados

Aplicación práctica

Tutorial técnico

Resumen

Definición e introducción

Protocolo de descriptores

Visión general de invocación de descriptores

Invocación desde una instancia

Invocación desde una clase

Invocación desde super

Resumen de la lógica de invocación

Notificación automática de nombre

Ejemplo de mapeos objeto-relacional (ORM)

Equivalentes en Python puro

Propiedades

Funciones y métodos

Kinds of methods

Métodos estáticos

Métodos de clase

Objetos miembros y __slots__

Los descriptores permiten a objetos personalizar la búsqueda, almacenamiento y eliminación de atributos.

Esta guía tiene cuatro secciones principales:

La guía introductoria da una visión general básica, moviéndose gentilmente por ejemplos simples, añadiendo una funcionalidad a la vez. Comienza acá si eres nuevo con los descriptores.

La segunda sección muestra un ejemplo completo y práctico de un descriptor. Si ya sabes lo básico comienza acá.

La tercera sección provee un tutorial más técnico que adentra en la mecánica detallada de cómo funcionan los descriptores. La mayoría de la gente no necesita este nivel de detalle.

La última sección tiene equivalentes en Python puro para descriptores incorporados que están escritos en C. Lee esta sección si tienes curiosidad de cómo las funciones se convierten en métodos vinculados, o sobre la implementación de herramientas comunes como classmethod(), staticmethod(), property(), y __slots__.

Guía introductoria

En esta guía introductoria comenzamos con el ejemplo más básico posible y luego vamos añadiendo nuevas funcionalidades una a una.

Ejemplo simple: un descriptor que retorna una constante

La clase Ten es un descriptor que siempre retorna el valor constante 10 desde su método __get__():

class Ten:
    def __get__(self, obj, objtype=None):
        return 10

Para usar el descriptor, éste se debe almacenar como una variable de clase en otra clase:

class A:
    x = 5                       # Regular class attribute
    y = Ten()                   # Descriptor instance

Una sesión interactiva muestra la diferencia entre un la búsqueda de atributo normal y la búsqueda a través del descriptor:

>>> a = A()                     # Make an instance of class A
>>> a.x                         # Normal attribute lookup
5
>>> a.y                         # Descriptor lookup
10

En la búsqueda de atributo a.x, el operador punto busca la llave x y el valor 5 en el diccionario de la clase. En la búsqueda a.y, el operador punto encuentra una instancia de un descriptor, reconocible por su método __get__, e invoca este método, el cual retorna 10.

Nota que el valor 10 no es almacenado ni en el diccionario de la clase ni en el diccionario de la instancia. En cambio, el valor 10 es calculado bajo demanda.

Este ejemplo muestra cómo funciona un descriptor simple, pero no es muy útil. Para recuperar constantes una búsqueda de atributos normal sería mejor.

En la próxima sección crearemos algo más útil, una búsqueda dinámica.

Búsquedas dinámicas

Descriptores interesantes típicamente ejecutan cálculos en vez de retornar constantes:

import os

class DirectorySize:

    def __get__(self, obj, objtype=None):
        return len(os.listdir(obj.dirname))

class Directory:

    size = DirectorySize()              # Descriptor instance

    def __init__(self, dirname):
        self.dirname = dirname          # Regular instance attribute

Una sesión interactiva muestra que la búsqueda es dinámica — calcula respuestas diferentes y actualizadas en cada ocasión:

>>> s = Directory('songs')
>>> g = Directory('games')
>>> s.size                              # The songs directory has twenty files
20
>>> g.size                              # The games directory has three files
3
>>> os.remove('games/chess')            # Delete a game
>>> g.size                              # File count is automatically updated
2

Además de mostrar cómo los descriptores puede ejecutar cálculos, este ejemplo también revela el propósitos de los parámetros de __get__(). El parámetro self es size, una instancia de DirectorySize. El parámetro obj es g o s, una instancia de Directory. Es el parámetro obj el que permite que al método __get__() saber el directorio objetivo. El parámetro objtype es una clase Directory.

Atributos gestionados

Un uso popular de descriptores es la gestión de acceso a datos de una instancia. El descriptor se asigna a un atributo público en el diccionario de clase, mientras que los datos reales se guardan en atributos privados en el diccionario de instancia. Los métodos __get__() and __set__() del descriptor se activan cuando se accede al atributo público.

En el siguiente ejemplo, age es el atributo público y _age es el atributo privado. Cuando el atributo público es accedido, el descriptor registra la búsqueda o actualización:

import logging

logging.basicConfig(level=logging.INFO)

class LoggedAgeAccess:

    def __get__(self, obj, objtype=None):
        value = obj._age
        logging.info('Accessing %r giving %r', 'age', value)
        return value

    def __set__(self, obj, value):
        logging.info('Updating %r to %r', 'age', value)
        obj._age = value

class Person:

    age = LoggedAgeAccess()             # Descriptor instance

    def __init__(self, name, age):
        self.name = name                # Regular instance attribute
        self.age = age                  # Calls __set__()

    def birthday(self):
        self.age += 1                   # Calls both __get__() and __set__()

Una sesión interactiva muestra que todos los accesos al atributo gestionado age son registrados, pero que el atributo normal name no es registrado:

>>> mary = Person('Mary M', 30)         # The initial age update is logged
INFO:root:Updating 'age' to 30
>>> dave = Person('David D', 40)
INFO:root:Updating 'age' to 40

>>> vars(mary)                          # The actual data is in a private attribute
{'name': 'Mary M', '_age': 30}
>>> vars(dave)
{'name': 'David D', '_age': 40}

>>> mary.age                            # Access the data and log the lookup
INFO:root:Accessing 'age' giving 30
30
>>> mary.birthday()                     # Updates are logged as well
INFO:root:Accessing 'age' giving 30
INFO:root:Updating 'age' to 31

>>> dave.name                           # Regular attribute lookup isn't logged
'David D'
>>> dave.age                            # Only the managed attribute is logged
INFO:root:Accessing 'age' giving 40
40

Un gran problema con este ejemplo es que el nombre privado _age está fijado en la clase LoggedAgeAccess. Esto significa que cada instancia puede sólo puede registrar un atributo, y que su nombre no se puede cambiar. En el siguiente ejemplo solucionaremos ese problema.

Nombres personalizados

Cuando una clase usa descriptores, puede informar a cada descriptor el nombre se usó para la variable.

En este ejemplo, la clase Person tiene dos instancias de descriptores, name y age. Cuando la clase Person se define, hace una retrollamada a __set_name__() en LoggedAccess para que se pueda registrar los nombres de los campos, dándole a cada descriptor su propio public_name y private_name:

import logging

logging.basicConfig(level=logging.INFO)

class LoggedAccess:

    def __set_name__(self, owner, name):
        self.public_name = name
        self.private_name = '_' + name

    def __get__(self, obj, objtype=None):
        value = getattr(obj, self.private_name)
        logging.info('Accessing %r giving %r', self.public_name, value)
        return value

    def __set__(self, obj, value):
        logging.info('Updating %r to %r', self.public_name, value)
        setattr(obj, self.private_name, value)

class Person:

    name = LoggedAccess()                # First descriptor instance
    age = LoggedAccess()                 # Second descriptor instance

    def __init__(self, name, age):
        self.name = name                 # Calls the first descriptor
        self.age = age                   # Calls the second descriptor

    def birthday(self):
        self.age += 1

Una sesión interactiva muestra que la clase Person ha llamado a __set_name__() para que los nombres de los campos sean registrados. Aquí llamamos a vars() para ver el descriptor sin activarlos:

>>> vars(vars(Person)['name'])
{'public_name': 'name', 'private_name': '_name'}
>>> vars(vars(Person)['age'])
{'public_name': 'age', 'private_name': '_age'}

La nueva clase ahora registrar accesos tanto a name como a age:

>>> pete = Person('Peter P', 10)
INFO:root:Updating 'name' to 'Peter P'
INFO:root:Updating 'age' to 10
>>> kate = Person('Catherine C', 20)
INFO:root:Updating 'name' to 'Catherine C'
INFO:root:Updating 'age' to 20

The two Person instances contain only the private names:

>>> vars(pete)
{'_name': 'Peter P', '_age': 10}
>>> vars(kate)
{'_name': 'Catherine C', '_age': 20}

Pensamientos finales

Llamamos un descriptor a cualquier objeto que define __get__(), __set__() o __delete__().

Opcionalmente, los descriptores pueden tener un método __set_name__(). Éste sólo se usa en los casos en los que el descriptor necesita saber ya sea la clase donde fue creado, o el nombre de la variable de clase a la que fue asignado. (Este método, si está presente, es llamada incluso si la clase no es un descriptor.)

Los descriptores son invocados por el «operator» punto durante la búsqueda de atributos. Si un descriptor es accedido indirectamente con vars(una_clase)[nombre_del_descriptor], la instancia del descriptor es retornada sin ser invocada.

Los descriptores sólo funcionan cuando se usan como variables de clase. Cuando son puestos en una instancia no tienen efecto.

La mayor motivación detrás de los descriptores es el proveer un gancho que permita a los objetos guardados en variables de clase controlar lo que ocurre al buscar un atributo.

Tradicionalmente, la clase que llama controla qué ocurre durante la búsqueda. Los descriptores invierten esta relación y permiten que los datos que están siendo buscados tengan algo qué decir al respecto.

Los descriptores se usan a través de todo el lenguaje. Es cómo funciones se convierten en métodos vinculados. Herramientas comunes como classmethod(), staticmethod(), property(), y functools.cached_property() se implementan todas como descriptores.

Ejemplo completo práctico

En este ejemplo creamos una herramienta práctica y poderosa para encontrar errores de corrupción de datos que son notoriamente difíciles de encontrar.

Clase validadora

Un validador es un descriptor que da acceso a un atributo gestionado. Antes de almacenar cualquier dato, verifica que el nuevo valor cumple con varias restricciones de tipo y rango. Si esas restricciones no se cumplen, lanza una excepción para así prevenir corrupción de datos en su origen.

Esta clase Validator es una tanto una clase base abstracta como un descriptor de un atributo gestionado:

from abc import ABC, abstractmethod

class Validator(ABC):

    def __set_name__(self, owner, name):
        self.private_name = '_' + name

    def __get__(self, obj, objtype=None):
        return getattr(obj, self.private_name)

    def __set__(self, obj, value):
        self.validate(value)
        setattr(obj, self.private_name, value)

    @abstractmethod
    def validate(self, value):
        pass

Validadores personalizados necesitan heredar de Validator y deben proveer un método validate() method para probar las restricciones que sean necesarias.

Validadores personalizados

Acá hay tres utilidades de validación de datos prácticas:

OneOf verifica que un valor está dentro de un grupo restringido de opciones.

Number verifica que un valor es int o float. Opcionalmente verifica que un valor está entre un mínimo y un máximo.

String verifica que un valor es un str. Opcionalmente valida que tenga un largo mínimo o máximo. Puede también validar un predicado [https://es.wikipedia.org/wiki/Predicado_(l%C3%B3gica)#L%C3%B3gica_matem%C3%A1tica] definido por el usuario.

class OneOf(Validator):

    def __init__(self, *options):
        self.options = set(options)

    def validate(self, value):
        if value not in self.options:
            raise ValueError(f'Expected {value!r} to be one of {self.options!r}')

class Number(Validator):

    def __init__(self, minvalue=None, maxvalue=None):
        self.minvalue = minvalue
        self.maxvalue = maxvalue

    def validate(self, value):
        if not isinstance(value, (int, float)):
            raise TypeError(f'Expected {value!r} to be an int or float')
        if self.minvalue is not None and value < self.minvalue:
            raise ValueError(
                f'Expected {value!r} to be at least {self.minvalue!r}'
            )
        if self.maxvalue is not None and value > self.maxvalue:
            raise ValueError(
                f'Expected {value!r} to be no more than {self.maxvalue!r}'
            )

class String(Validator):

    def __init__(self, minsize=None, maxsize=None, predicate=None):
        self.minsize = minsize
        self.maxsize = maxsize
        self.predicate = predicate

    def validate(self, value):
        if not isinstance(value, str):
            raise TypeError(f'Expected {value!r} to be an str')
        if self.minsize is not None and len(value) < self.minsize:
            raise ValueError(
                f'Expected {value!r} to be no smaller than {self.minsize!r}'
            )
        if self.maxsize is not None and len(value) > self.maxsize:
            raise ValueError(
                f'Expected {value!r} to be no bigger than {self.maxsize!r}'
            )
        if self.predicate is not None and not self.predicate(value):
            raise ValueError(
                f'Expected {self.predicate} to be true for {value!r}'
            )

Aplicación práctica

Acá se muestra cómo se puede usar los validadores de datos en una clase real:

class Component:

    name = String(minsize=3, maxsize=10, predicate=str.isupper)
    kind = OneOf('wood', 'metal', 'plastic')
    quantity = Number(minvalue=0)

    def __init__(self, name, kind, quantity):
        self.name = name
        self.kind = kind
        self.quantity = quantity

Los descriptores previenen que se creen instancias inválidas:

>>> Component('Widget', 'metal', 5)      # Blocked: 'Widget' is not all uppercase
Traceback (most recent call last):
    ...
ValueError: Expected <method 'isupper' of 'str' objects> to be true for 'Widget'

>>> Component('WIDGET', 'metle', 5)      # Blocked: 'metle' is misspelled
Traceback (most recent call last):
    ...
ValueError: Expected 'metle' to be one of {'metal', 'plastic', 'wood'}

>>> Component('WIDGET', 'metal', -5)     # Blocked: -5 is negative
Traceback (most recent call last):
    ...
ValueError: Expected -5 to be at least 0
>>> Component('WIDGET', 'metal', 'V')    # Blocked: 'V' isn't a number
Traceback (most recent call last):
    ...
TypeError: Expected 'V' to be an int or float

>>> c = Component('WIDGET', 'metal', 5)  # Allowed:  The inputs are valid

Tutorial técnico

Lo que sigue es un tutorial más práctico sobre las mecánicas y detalles de cómo funcionan los descriptores.

Resumen

Define los descriptores, resume el protocolo, y muestra cómo los descriptores son llamados. Provee ejemplos mostrando cómo funcionan los mapeos objeto-relacional (ORM).

Aprender acerca de los descriptores no sólo brinda acceso a un conjunto de herramientas mayor, sino que genera una comprensión más profunda de cómo funciona Python.

Definición e introducción

En general, un descriptor es un valor atributo que tiene uno de los métodos del protocolo de descriptores. Estos métodos son __get__(), __set__(), y __delete__(). Si cualquiera de esos métodos se definen en un atributo, se dice que éste es un descriptor.

El comportamiento predeterminado para el acceso a los atributos es obtener, establecer o eliminar el atributo del diccionario de un objeto. Por ejemplo, a.x tiene una cadena de búsqueda que comienza con a.__dict__['x'], luego type(a).__dict__['x'] y continúa a través del orden de resolución de métodos de type(a). Si el valor buscado es un objeto que define uno de los métodos de descriptores, entonces Python puede anular el comportamiento predeterminado e invocar el método del descriptor en su lugar. El lugar donde esto ocurre en la cadena de precedencia depende de qué métodos de descriptores fueron definidos.

Los descriptores son un protocolo poderoso y de propósito general. Son el mecanismo detrás de propiedades, métodos, métodos estáticos y super(). Se usan a través de Python mismo. Los descriptores simplifican el código C subyacente y ofrecen un grupo flexible de nuevas herramientas para programas habituales de Python.

Protocolo de descriptores

descr.__get__(self, obj, type=None) -> value

descr.__set__(self, obj, value) -> None

descr.__delete__(self, obj) -> None

Eso es todo lo que hay que hacer. Si se define cualquiera de estos métodos, el objeto se considera un descriptor y puede anular el comportamiento predeterminado al ser buscado como un atributo.

Si un objeto define __set__() o __delete__(), se considera un descriptor de datos. Los descriptores que solo definen __get__() se denominan descriptores de no-datos (normalmente se utilizan para métodos, pero son posibles otros usos).

Los descriptores de datos y de no-datos difieren en cómo se calculan las anulaciones con respecto a las entradas en el diccionario de una instancia. Si el diccionario de una instancia tiene una entrada con el mismo nombre que un descriptor de datos, el descriptor de datos tiene prioridad. Si el diccionario de una instancia tiene una entrada con el mismo nombre que un descriptor de no-datos, la entrada del diccionario tiene prioridad.

Para crear un descriptor de datos de sólo lectura, define tanto __get__() como __set__() donde __set__() lanza un AttributeError cuando es llamado. Definir el método __set__() de forma que lance una excepción genérica es suficiente para convertirlo en un descriptor de datos.

Visión general de invocación de descriptores

Un descriptor puede ser llamado directamente con desc.__get__(obj) o desc.__get__(None, cls).

Pero es más común que un descriptor sea invocado automáticamente por la búsqueda de atributos.

La expresión obj.x busca el atributo x en la cadena de nombres de espacio de obj. Si la búsqueda encuentra un descriptor fuera del __dict__ de la instancia, su método __get__() es invocado de acuerdo a la lista de reglas de precedencia mostradas debajo.

Los detalles de la invocación dependen de si obj es un objeto una clase, o una instancia de super.

Invocación desde una instancia

La búsqueda en instancias escanea a través de una cadena de nombres de espacio dando la más alta prioridad a descriptores de datos, seguidos por variables de instancia, luego descriptores de no-datos, luego variables de clase, y finalmente a __getattr__() si se provee.

Si se encuentra un descriptor para a.x entonces se invoca con desc.__get__(a, type(a)).

La lógica para una búsqueda con puntos se encuentra en object.__getattribute__(). Acá hay un equivalente en Python puro:

def object_getattribute(obj, name):
    "Emulate PyObject_GenericGetAttr() in Objects/object.c"
    null = object()
    objtype = type(obj)
    cls_var = getattr(objtype, name, null)
    descr_get = getattr(type(cls_var), '__get__', null)
    if descr_get is not null:
        if (hasattr(type(cls_var), '__set__')
            or hasattr(type(cls_var), '__delete__')):
            return descr_get(cls_var, obj, objtype)     # data descriptor
    if hasattr(obj, '__dict__') and name in vars(obj):
        return vars(obj)[name]                          # instance variable
    if descr_get is not null:
        return descr_get(cls_var, obj, objtype)         # non-data descriptor
    if cls_var is not null:
        return cls_var                                  # class variable
    raise AttributeError(name)

Note, there is no __getattr__() hook in the __getattribute__() code. That is why calling __getattribute__() directly or with super().__getattribute__ will bypass __getattr__() entirely.

Instead, it is the dot operator and the getattr() function that are responsible for invoking __getattr__() whenever __getattribute__() raises an AttributeError. Their logic is encapsulated in a helper function:

def getattr_hook(obj, name):
    "Emulate slot_tp_getattr_hook() in Objects/typeobject.c"
    try:
        return obj.__getattribute__(name)
    except AttributeError:
        if not hasattr(type(obj), '__getattr__'):
            raise
    return type(obj).__getattr__(obj, name)             # __getattr__

Invocación desde una clase

La lógica para una búsqueda con puntos tal como A.x se encuentra en type.__getattribute__(). Los pasos son similares a los de object.__getattribute__(), pero la búsqueda en el diccionario de instancia se reemplaza por una búsqueda a través del orden de resolución de métodos de la clase.

Si se encuentra un descriptor, se invoca con desc.__get__(None, A).

La implementación completa en C puede ser encontrada en type_getattro() y _PyType_Lookup() en Objects/typeobject.c [https://github.com/python/cpython/tree/3.9/Objects/typeobject.c].

Invocación desde super

La lógica de la búsqueda con puntos para super está en el método __getattribute__() para el objeto retornado por super().

Una búsqueda con puntos tal como super(A, obj).m busca obj.__class__.__mro__ para la clase base B que sigue inmediatamente a A y luego retorna B.__dict__['m'].__get__(obj, A). Si no es un descriptor, m se retorna sin cambiar.

La implementación completa en C puede ser encontrada en super_getattro() en Objects/typeobject.c [https://github.com/python/cpython/tree/3.9/Objects/typeobject.c]. Un equivalente en Python puro se puede encontrar en el Guido’s Tutorial [https://www.python.org/download/releases/2.2.3/descrintro/#cooperation].

Resumen de la lógica de invocación

El mecanismo de descriptores está embebido en los métodos __getattribute__() de object, type, y super().

Los puntos importantes a recordar son:

Los descriptores son invocados por el método __getattribute__().

Las clases heredan esta maquinaria desde object, type, o super().

Redefinir __getattribute__() previene las llamadas automáticas a descriptores porque toda la lógica de descriptores está en ese método.

object.__getattribute__() y type.__getattribute__() realizan diferentes llamadas a __get__(). El primero incluye la instancia y puede incluir la clase. El segundo establece None como instancia, y siempre incluye la clase.

Los descriptores de datos siempre anulan los diccionarios de instancia.

Los descriptores de no-datos pueden ser reemplazados por los diccionarios de instancia.

Notificación automática de nombre

A veces es deseable que un descriptor sepa qué nombre fue asignado a una variable de clase. Cuando una nueva clase es creada, la metaclase type escanea el diccionario de la nueva clase. Si alguna de las entradas es un descriptor, y si define __set_name__(), ese método se llama con dos argumentos. El argumento owner es la clase donde se usa el descriptor, y name es la variable de clase a la cual el descriptor se asigna.

Los detalles de la implementación están en type_new() y set_names() en Objects/typeobject.c [https://github.com/python/cpython/tree/3.9/Objects/typeobject.c].

Dado que la lógica de actualización está en type.__new__(), las notificaciones ocurren sólo al momento de crear la clase. Si se añade descriptores a la clase más tarde, __set_name__() tendrá que ser llamado manualmente.

Ejemplo de mapeos objeto-relacional (ORM)

El siguiente código es un esqueleto simplificado que muestra cómo descriptores de datos pueden ser usados para implementar un mapeo objeto-relacional <https://es.wikipedia.org/wiki/Asignaci%C3%B3n_objeto-relacional>`_.

La idea esencial es que los datos se almacenan en una base de datos externa. Las instancias de Python sólo mantienen llaves a las tablas de la base de datos. Los descriptores se hacen cargo de las búsquedas o actualizaciones:

class Field:

    def __set_name__(self, owner, name):
        self.fetch = f'SELECT {name} FROM {owner.table} WHERE {owner.key}=?;'
        self.store = f'UPDATE {owner.table} SET {name}=? WHERE {owner.key}=?;'

    def __get__(self, obj, objtype=None):
        return conn.execute(self.fetch, [obj.key]).fetchone()[0]

    def __set__(self, obj, value):
        conn.execute(self.store, [value, obj.key])
        conn.commit()

Podemos usar la clase Field para definir modelos [https://es.wikipedia.org/wiki/Modelo_de_base_de_datos] que describen el esquema para cada tabla en la base de datos:

class Movie:
    table = 'Movies'                    # Table name
    key = 'title'                       # Primary key
    director = Field()
    year = Field()

    def __init__(self, key):
        self.key = key

class Song:
    table = 'Music'
    key = 'title'
    artist = Field()
    year = Field()
    genre = Field()

    def __init__(self, key):
        self.key = key

Para usar los modelos, primera conéctate a la base de datos:

>>> import sqlite3
>>> conn = sqlite3.connect('entertainment.db')

Una sesión interactiva muestra cómo los datos son obtenidos desde la base de datos y cómo se pueden actualizar:

>>> Movie('Star Wars').director
'George Lucas'
>>> jaws = Movie('Jaws')
>>> f'Released in {jaws.year} by {jaws.director}'
'Released in 1975 by Steven Spielberg'

>>> Song('Country Roads').artist
'John Denver'

>>> Movie('Star Wars').director = 'J.J. Abrams'
>>> Movie('Star Wars').director
'J.J. Abrams'

Equivalentes en Python puro

El protocolo de descriptores es simple y ofrece posibilidades estimulantes. Varios casos de uso son tan comunes que han sido pre-empaquetados en herramientas incorporadas. Propiedades, métodos vinculados, métodos estáticos, métodos de clase y __slots__ están todos basados en el protocolo de descriptores.

Propiedades

Llamar a property() es una forma sucinta de construir un descriptor de datos que desencadena llamadas a funciones al acceder a un atributo. Su firma es:

property(fget=None, fset=None, fdel=None, doc=None) -> property

La documentación muestra un uso típico para definir un atributo gestionado x:

class C:
    def getx(self): return self.__x
    def setx(self, value): self.__x = value
    def delx(self): del self.__x
    x = property(getx, setx, delx, "I'm the 'x' property.")

Para ver cómo se implementa property() en términos del protocolo de descriptores, aquí hay un equivalente puro de Python:

class Property:
    "Emulate PyProperty_Type() in Objects/descrobject.c"

    def __init__(self, fget=None, fset=None, fdel=None, doc=None):
        self.fget = fget
        self.fset = fset
        self.fdel = fdel
        if doc is None and fget is not None:
            doc = fget.__doc__
        self.__doc__ = doc

    def __get__(self, obj, objtype=None):
        if obj is None:
            return self
        if self.fget is None:
            raise AttributeError("unreadable attribute")
        return self.fget(obj)

    def __set__(self, obj, value):
        if self.fset is None:
            raise AttributeError("can't set attribute")
        self.fset(obj, value)

    def __delete__(self, obj):
        if self.fdel is None:
            raise AttributeError("can't delete attribute")
        self.fdel(obj)

    def getter(self, fget):
        return type(self)(fget, self.fset, self.fdel, self.__doc__)

    def setter(self, fset):
        return type(self)(self.fget, fset, self.fdel, self.__doc__)

    def deleter(self, fdel):
        return type(self)(self.fget, self.fset, fdel, self.__doc__)

La función incorporada property() es de ayuda cuando una interfaz de usuario ha otorgado acceso a atributos y luego los cambios posteriores requieren la intervención de un método.

Por ejemplo, una clase de hoja de cálculo puede otorgar acceso al valor de una celda a través de Cell('b10').value. Las mejoras posteriores del programa requieren que la celda se vuelva a calcular en cada acceso; sin embargo, la programadora no quiere afectar al código de cliente existente que accede al atributo directamente. La solución es envolver el acceso al valor del atributo en un descriptor de datos propiedad:

class Cell:
    ...

    @property
    def value(self):
        "Recalculate the cell before returning value"
        self.recalc()
        return self._value

Tanto la función incorporada property() como nuestra equivalente Property() funcionarían en este ejemplo.

Funciones y métodos

Las características orientadas a objetos de Python se basan en un entorno basado en funciones. Usando descriptores de no-datos, ambas se combinan perfectamente.

Las funciones almacenadas en diccionarios de clase son convertidas en métodos cuando son invocadas. Los métodos sólo difieren de funciones regulares en que la instancia del objeto es antepuesta a los otros argumentos. Por convención, la instancia se llama self, pero podría ser llamada this o cualquier otro nombre de variable.

Los métodos se pueden crear manualmente con types.MethodType, lo que es aproximadamente equivalente a:

class MethodType:
    "Emulate PyMethod_Type in Objects/classobject.c"

    def __init__(self, func, obj):
        self.__func__ = func
        self.__self__ = obj

    def __call__(self, *args, **kwargs):
        func = self.__func__
        obj = self.__self__
        return func(obj, *args, **kwargs)

Para soportar la creación automática de métodos, las funciones incluyen un método __get__() para vincular métodos durante el acceso a atributos. Esto significa que las funciones son descriptores de no-datos que retornan métodos vinculados durante la búsqueda con puntos desde una instancia. Así es como funciona:

class Function:
    ...

    def __get__(self, obj, objtype=None):
        "Simulate func_descr_get() in Objects/funcobject.c"
        if obj is None:
            return self
        return MethodType(self, obj)

Ejecutar la siguiente clase en el intérprete muestra cómo funciona el descriptor de función en la práctica:

class D:
    def f(self, x):
         return x

La función tiene un atributo de nombre calificado para soportar introspección:

>>> D.f.__qualname__
'D.f'

Accediendo a la función a través del diccionario de clase no invoca __get__(). En cambio, retorna el objeto función subyacente:

>>> D.__dict__['f']
<function D.f at 0x00C45070>

Acceso con puntos desde una clase llama a __get__(), lo cual sólo retorna la función subyacente sin cambiar:

>>> D.f
<function D.f at 0x00C45070>

El comportamiento interesante ocurre durante el accesos con puntos desde una instancia. Las búsquedas con punto llaman a __get__(), el cual retorna un objeto de método vinculado:

>>> d = D()
>>> d.f
<bound method D.f of <__main__.D object at 0x00B18C90>>

Internamente, el método vinculado guarda la función subyacente y la instancia vinculada:

>>> d.f.__func__
<function D.f at 0x00C45070>

>>> d.f.__self__
<__main__.D object at 0x1012e1f98>

Si alguna vez te preguntaste de dónde viene self en métodos regulares, o de dónde viene cls en métodos de clase, ¡es acá!

Kinds of methods

Los descriptores de no-datos proporcionan un mecanismo simple para variaciones de los patrones habituales para vincular funciones en métodos.

Para recapitular, las funciones tienen un método __get__() para que se puedan convertir en un método cuando se accede a ellas como atributos. El descriptor de no-datos transforma una llamada a obj.f(*args) en f(obj, *args). Llamar a cls.f(*args) se convierte en f(*args).

Este cuadro resume el enlace (binding) y sus dos variantes más útiles:

Transformación

Llamado desde un objeto

Llamado desde una clase

función

f(obj, *args)

f(*args)

método estático

f(*args)

f(*args)

método de clase

f(type(obj), *args)

f(cls, *args)

Métodos estáticos

Los métodos estáticos devuelven la función subyacente sin cambios. Llamar a c.f o C.f es equivalente a una búsqueda directa en object.__getattribute__(c, "f") o en object.__getattribute__(C, "f"). Como resultado, la función se vuelve idénticamente accesible desde un objeto o una clase.

Buenos candidatos para ser métodos estáticos son los métodos que no hacen referencia a la variable self.

Por ejemplo, un paquete de estadística puede incluir una clase contenedora para datos experimentales. La clase proporciona métodos normales para calcular el promedio, la media, la mediana y otras estadísticas descriptivas que dependen de los datos. Sin embargo, puede haber funciones útiles que están relacionadas conceptualmente pero que no dependen de los datos. Por ejemplo, erf(x) es una práctica rutinaria de conversión que surge en el trabajo estadístico pero que no depende directamente de un conjunto de datos en particular. Se puede llamar desde un objeto o la clase: s.erf(1.5) --> .9332 o Sample.erf(1.5) --> .9332.

Dado que los métodos estáticos devuelven la función subyacente sin cambios, las llamadas de ejemplo carecen de interés:

class E:
    @staticmethod
    def f(x):
        return x * 10

>>> E.f(3)
30
>>> E().f(3)
30

Usando el protocolo de descriptores de no-datos, una versión pura de Python de staticmethod() se vería así:

class StaticMethod:
    "Emulate PyStaticMethod_Type() in Objects/funcobject.c"

    def __init__(self, f):
        self.f = f

    def __get__(self, obj, objtype=None):
        return self.f

Métodos de clase

A diferencia de los métodos estáticos, los métodos de clase anteponen la referencia de clase a la lista de argumentos antes de llamar a la función. Este formato es el mismo si quien llama es un objeto o una clase:

class F:
    @classmethod
    def f(cls, x):
        return cls.__name__, x

>>> F.f(3)
('F', 3)
>>> F().f(3)
('F', 3)

Este comportamiento es útil siempre que la función solo necesite tener una referencia de clase y no necesita contar con los datos almacenados en una instancia específica. Un uso de los métodos de clase es crear constructores de clase alternativos. Por ejemplo, el método de clase dict.fromkeys() crea un nuevo diccionario a partir de una lista de claves. El equivalente puro de Python es:

class Dict(dict):
    @classmethod
    def fromkeys(cls, iterable, value=None):
        "Emulate dict_fromkeys() in Objects/dictobject.c"
        d = cls()
        for key in iterable:
            d[key] = value
        return d

Ahora se puede construir un nuevo diccionario de claves únicas así:

>>> d = Dict.fromkeys('abracadabra')
>>> type(d) is Dict
True
>>> d
{'a': None, 'b': None, 'r': None, 'c': None, 'd': None}

Usando el protocolo de descriptores de no-datos, una implementación pura en Python de classmethod() se vería así:

class ClassMethod:
    "Emulate PyClassMethod_Type() in Objects/funcobject.c"

    def __init__(self, f):
        self.f = f

    def __get__(self, obj, cls=None):
        if cls is None:
            cls = type(obj)
        if hasattr(type(self.f), '__get__'):
            return self.f.__get__(cls)
        return MethodType(self.f, cls)

The code path for hasattr(type(self.f), '__get__') was added in Python 3.9 and makes it possible for classmethod() to support chained decorators. For example, a classmethod and property could be chained together:

class G:
    @classmethod
    @property
    def __doc__(cls):
        return f'A doc for {cls.__name__!r}'

>>> G.__doc__
"A doc for 'G'"

Objetos miembros y __slots__

Cuando una clase define __slots__, reemplaza los diccionarios de instancia por un arreglo de valores de ranura de largo fijo. Desde el punto de vista del usuario esto tiene varios efectos:

1. Provides immediate detection of bugs due to misspelled attribute assignments. Only attribute names specified in __slots__ are allowed:

class Vehicle:
    __slots__ = ('id_number', 'make', 'model')

>>> auto = Vehicle()
>>> auto.id_nubmer = 'VYE483814LQEX'
Traceback (most recent call last):
    ...
AttributeError: 'Vehicle' object has no attribute 'id_nubmer'

2. Helps create immutable objects where descriptors manage access to private attributes stored in __slots__:

class Immutable:

    __slots__ = ('_dept', '_name')          # Replace the instance dictionary

    def __init__(self, dept, name):
        self._dept = dept                   # Store to private attribute
        self._name = name                   # Store to private attribute

    @property                               # Read-only descriptor
    def dept(self):
        return self._dept

    @property
    def name(self):                         # Read-only descriptor
        return self._name

>>> mark = Immutable('Botany', 'Mark Watney')
>>> mark.dept
'Botany'
>>> mark.dept = 'Space Pirate'
Traceback (most recent call last):
    ...
AttributeError: can't set attribute
>>> mark.location = 'Mars'
Traceback (most recent call last):
    ...
AttributeError: 'Immutable' object has no attribute 'location'

3. Saves memory. On a 64-bit Linux build, an instance with two attributes takes 48 bytes with __slots__ and 152 bytes without. This flyweight design pattern [https://en.wikipedia.org/wiki/Flyweight_pattern] likely only matters when a large number of instances are going to be created.

4. Blocks tools like functools.cached_property() which require an instance dictionary to function correctly:

from functools import cached_property

class CP:
    __slots__ = ()                          # Eliminates the instance dict

    @cached_property                        # Requires an instance dict
    def pi(self):
        return 4 * sum((-1.0)**n / (2.0*n + 1.0)
                       for n in reversed(range(100_000)))

>>> CP().pi
Traceback (most recent call last):
  ...
TypeError: No '__dict__' attribute on 'CP' instance to cache 'pi' property.

No es posible crear una versión exacta de __slots__ en Python puro porque requiere acceso directo a estructuras en C y control sobre asignación de memoria de objetos. Sin embargo podemos construir una simulación casi totalmente fiel donde la estructura real en C para las ranuras es emulada con una lista privada _slotvalues. Las lecturas y escrituras de esta estructura privada se manejan con descriptores miembros:

null = object()

class Member:

    def __init__(self, name, clsname, offset):
        'Emulate PyMemberDef in Include/structmember.h'
        # Also see descr_new() in Objects/descrobject.c
        self.name = name
        self.clsname = clsname
        self.offset = offset

    def __get__(self, obj, objtype=None):
        'Emulate member_get() in Objects/descrobject.c'
        # Also see PyMember_GetOne() in Python/structmember.c
        value = obj._slotvalues[self.offset]
        if value is null:
            raise AttributeError(self.name)
        return value

    def __set__(self, obj, value):
        'Emulate member_set() in Objects/descrobject.c'
        obj._slotvalues[self.offset] = value

    def __delete__(self, obj):
        'Emulate member_delete() in Objects/descrobject.c'
        value = obj._slotvalues[self.offset]
        if value is null:
            raise AttributeError(self.name)
        obj._slotvalues[self.offset] = null

    def __repr__(self):
        'Emulate member_repr() in Objects/descrobject.c'
        return f'<Member {self.name!r} of {self.clsname!r}>'

El método type.__new__() se hace cargo de añadir objetos miembros a variables de clase:

class Type(type):
    'Simulate how the type metaclass adds member objects for slots'

    def __new__(mcls, clsname, bases, mapping):
        'Emuluate type_new() in Objects/typeobject.c'
        # type_new() calls PyTypeReady() which calls add_methods()
        slot_names = mapping.get('slot_names', [])
        for offset, name in enumerate(slot_names):
            mapping[name] = Member(name, clsname, offset)
        return type.__new__(mcls, clsname, bases, mapping)

El método object.__new__() se hace cargo de crear instancias que tienen ranuras en vez un diccionario de instancia. Acá hay una simulación aproximada en Python puro:

class Object:
    'Simulate how object.__new__() allocates memory for __slots__'

    def __new__(cls, *args):
        'Emulate object_new() in Objects/typeobject.c'
        inst = super().__new__(cls)
        if hasattr(cls, 'slot_names'):
            empty_slots = [null] * len(cls.slot_names)
            object.__setattr__(inst, '_slotvalues', empty_slots)
        return inst

    def __setattr__(self, name, value):
        'Emulate _PyObject_GenericSetAttrWithDict() Objects/object.c'
        cls = type(self)
        if hasattr(cls, 'slot_names') and name not in cls.slot_names:
            raise AttributeError(
                f'{type(self).__name__!r} object has no attribute {name!r}'
            )
        super().__setattr__(name, value)

    def __delattr__(self, name):
        'Emulate _PyObject_GenericSetAttrWithDict() Objects/object.c'
        cls = type(self)
        if hasattr(cls, 'slot_names') and name not in cls.slot_names:
            raise AttributeError(
                f'{type(self).__name__!r} object has no attribute {name!r}'
            )
        super().__delattr__(name)

Para usar la simulación en una clase real, sólo hereda de Object y establece metaclass a Type:

class H(Object, metaclass=Type):
    'Instance variables stored in slots'

    slot_names = ['x', 'y']

    def __init__(self, x, y):
        self.x = x
        self.y = y

En este punto, la metaclase ha cargado los objetos miembros para x e y:

>>> from pprint import pp
>>> pp(dict(vars(H)))
{'__module__': '__main__',
 '__doc__': 'Instance variables stored in slots',
 'slot_names': ['x', 'y'],
 '__init__': <function H.__init__ at 0x7fb5d302f9d0>,
 'x': <Member 'x' of 'H'>,
 'y': <Member 'y' of 'H'>}

Cuando se crean instancias, éstas tienen una lista slot_values donde se almacenan los atributos:

>>> h = H(10, 20)
>>> vars(h)
{'_slotvalues': [10, 20]}
>>> h.x = 55
>>> vars(h)
{'_slotvalues': [55, 20]}

Atributos mal deletreados o no asignados lazarán una excepción:

>>> h.xz
Traceback (most recent call last):
    ...
AttributeError: 'H' object has no attribute 'xz'

HOWTO - Programación funcional

Autor

A. M. Kuchling

Publicación

0.32

En este documento, haremos un recorrido de las características de Python adecuadas para implementar programas en un estilo funcional. Después de una introducción de los conceptos de programación funcional, veremos las características del lenguaje como iteradores y generadores y módulos de librería relevantes como itertools y functools.

Introducción

Esta sección explica el concepto básico de programación funcional; si solo está interesado en aprender acerca de las características del lenguaje Python, pase a la siguiente sección en Iteradores.

Los lenguajes de programación soportan la descomposición de problemas en muchas formas diferentes:

La mayoría de los lenguajes de programación son procedimentales: los programas son listas de instrucciones que le dicen a la computadora qué hacer con la entrada del programa. C, Pascal e incluso las terminales Unix son lenguajes procedimentales.

En los lenguajes declarativos, se escribe una especificación que describe el problema que se resolverá, y la implementación del lenguaje averigua como realizar el cálculo de forma eficiente. SQL es el lenguaje declarativo con el que probablemente esté más familiarizado; una consulta SQL describe el conjunto de datos que quiere recuperar, y el motor SQL decide si escanear tablas o usar índices, qué subcláusulas deben ejecutarse primero, etc.

Los programas orientados a objetos manipulan colecciones de objetos. Los objetos tienen estado interno y soportan métodos que consultan o modifican su estado interno de alguna manera. Smalltalk y Java son lenguajes orientados a objetos. C++ y Python son lenguajes que soportan la programación orientada a objetos, pero no fuerzan el uso de las características orientadas a objetos.

La programación funcional descompone un problema en un conjunto de funciones. Idealmente, las funciones solo reciben entradas y producen salidas, y no tienen ningún estado interno que afecte la salida producida para una entrada dada. Los lenguajes funcionales bien conocidos incluyen la familia ML (Standard ML, OCaml, y otras variantes) y Haskell.

Los diseñadores de algunos lenguajes de computadora eligen enfatizar en un enfoque particular para programar. Esto a menudo hace difícil escribir programas que usen un enfoque diferente. Otros lenguajes son lenguajes multiparadigma que soportan varios enfoques diferentes. Lisp, C++ y Python son multiparadigma; puede escribir programas o librerías que son en gran parte procedimentales, orientados a objetos o funcionales en todos estos lenguajes. En un programa grande, las diferentes secciones podrían escribirse usando diferentes enfoques; la GUI podría ser orientada a objetos mientras la lógica de procesamiento es procedimental o funcional, por ejemplo.

En un programa funcional, la entrada fluye a través de un conjunto de funciones. Cada función opera sobre su entrada y produce alguna salida. El estilo funcional desalienta las funciones con efectos secundarios que modifican el estado interno o hacen otros cambios que no son visibles en el valor de retorno de la función. Las funciones que no tienen ningún efecto secundario se llaman puramente funcionales. Evitar los efectos secundarios significa no usar estructuras de datos que se actualicen mientras se ejecuta un programa; cada salida de la función debe depender solo de su entrada.

Some languages are very strict about purity and don’t even have assignment statements such as a=3 or c = a + b, but it’s difficult to avoid all side effects, such as printing to the screen or writing to a disk file. Another example is a call to the print() or time.sleep() function, neither of which returns a useful value. Both are called only for their side effects of sending some text to the screen or pausing execution for a second.

Los programas de Python escritos en estilo funcional usualmente no irán al extremo de evitar todas las E/S o todas las asignaciones; en cambio, proveerán una interfaz aparentemente funcional pero internamente usará características no funcionales. Por ejemplo, la implementación de una función todavía usará asignaciones a variables locales, pero no modificará variables globales ni tendrá otros efectos secundarios.

La programación funcional se puede considerar lo opuesto a la programación orientada a objetos. Los objetos son pequeñas capsulas que contienen algún estado interno junto con una colección de llamadas a métodos que le permiten modificar este estado, y los programas consisten en realizar el conjunto correcto de cambios de estado. La programación funcional quiere evitar cambios de estado tanto como sea posible y trabaja con flujos de datos entre funciones. En Python podría combinar los dos enfoques para escribir funciones que reciban y retornen instancias que representen objetos en su aplicación (mensajes de e-mail, transacciones, etc.).

El diseño funcional puede parecer una restricción extraña bajo la cuál trabajar. ¿Por qué evitaría objetos y efectos secundarios? Hay ventajas teóricas y prácticas para el estilo funcional:

Demostrabilidad formal.

Modularidad.

Componibilidad.

Facilidad de depurar y probar.

Demostrabilidad formal

Un beneficio teórico es que es más fácil construir una demostración matemática de que un programa funcional es correcto.

Por un largo tiempo los investigadores se han interesado en buscar formas de demostrar matemáticamente que los programas son correctos. Esto es diferente de probar un programa sobre numerosas entradas y concluir que su salida es usualmente correcta, o leer el código fuente de un programa y concluir que el código se ve bien; en lugar de eso el objetivo es una demostración rigurosa de que un programa produce el resultado correcto para todas las entradas posibles.

La técnica utilizada para demostrar que los programas son correctos es anotar invariantes, propiedades de los datos de entrada y de las variables del programa que siempre son verdaderas. Por cada línea de código, debe mostrar que si las invariantes X e Y son verdaderas antes que la línea sea ejecutada, las invariantes ligeramente diferentes X” e Y” son verdaderas después que la línea se ejecutó. Esto continúa hasta que alcance el fin del programa, punto en el cuál las invariantes deben coincidir con las condiciones deseadas en la salida del programa.

La evitación de las asignaciones de la programación funcional surge porque las asignaciones son difíciles de manejar con esta técnica; las asignaciones pueden romper invariantes que eran verdaderas antes de la asignación sin producir nuevas invariantes que se puedan propagar hacia adelante.

Desafortunadamente, demostrar que los programas son correctos es en gran parte impráctico y no relevante al software de Python. Incluso los programas triviales requieren demostraciones que tienen varias páginas; la demostración de correctitud para un programa moderadamente complicado sería enorme, y pocos o ninguno de los programas que usa diariamente (el interprete de Python, su analizador XML, su navegador web) se podrían demostrar que son correctos. Aún si anotó o generó una demostración, entonces estaría la cuestión de verificar la demostración; quizás hay un error en ella, y equivocadamente cree que demostró que el programa es correcto.

Modularidad

Un beneficio más práctico de la programación funcional es que fuerza a romper su problema en pequeñas piezas. Como resultado los programas son más modulares. Es más fácil especificar y escribir una función pequeña que hace una cosa que una función grande que realiza una transformación complicada. Las funciones pequeñas también son más fáciles de leer y comprobar si hay errores.

Facilidad de depurar y probar

Probar y depurar un programa en estilo funcional es más fácil.

La depuración se simplifica porque las funciones generalmente son pequeñas y claramente especificadas. Cuando un programa no funciona, cada función es un punto de interfaz donde puede comprobar si los datos son correctos. Puede ver las entradas y salidas intermedias para aislar rápidamente la función que es responsable de un error.

Las pruebas son más fáciles porque cada función es un sujeto potencial para una prueba unitaria. Las funciones no dependen de un estado del sistema que necesite ser replicado antes de correr una prueba; en lugar de eso solo tiene que sintetizar la entrada correcta y comprobar que la salida coincida con las expectativas.

Componibilidad

Mientras trabaja en un programa en estilo funcional, escribirá un número de funciones con diferentes entradas y salidas. Algunas de estas funciones inevitablemente estarán especializadas en una aplicación en particular, pero otras serán útiles en una amplia variedad de programas. Por ejemplo, una función que recibe la ruta de un directorio y retorna todos los archivos XML en el directorio, o una función que recibe el nombre de un archivo y retorna su contenido, se puede aplicar a muchas situaciones diferentes.

Con el tiempo formará una librería personal de utilidades. A menudo ensamblará nuevos programas organizando funciones existentes en una nueva configuración y escribiendo unas pocas funciones especializadas para la tarea actual.

Iteradores

Comenzaré viendo una característica del lenguaje Python que es una base importante para escribir programas en estilo funcional: iteradores.

Un iterador es un objeto que representa un flujo de datos; este objeto retorna los datos de a un elemento a la vez. Un iterador de Python debe soportar un método llamado __next__() que no recibe argumentos y siempre retorna el siguiente elemento en el flujo. Si no hay más elementos en el flujo, __next__() debe lanzar la excepción StopIteration. Los iteradores no tienen que ser finitos; es perfectamente razonable escribir un iterador que produce un flujo de datos infinito.

La función incorporada iter() recibe un objeto arbitrario e intenta retornar un iterador que retornará los contenidos o elementos del objeto, lanzando TypeError si el objeto no soporta iteración. Muchos tipos de datos integrados de Python soportan iteración, siendo los más comunes las listas y los diccionarios. Un objeto se llama iterable si puede obtener un iterador para él.

Puede experimentar con la interfaz de iteración manualmente:

>>> L = [1, 2, 3]
>>> it = iter(L)
>>> it
<...iterator object at ...>
>>> it.__next__()  # same as next(it)
1
>>> next(it)
2
>>> next(it)
3
>>> next(it)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
StopIteration
>>>

Python espera objetos iterables en muchos contextos diferentes, siendo el más importante la sentencia for. En la sentencia for X in Y, Y debe ser un iterador o algún objeto para el que iter() puede crear un iterador. Estas dos sentencias son equivalentes:

for i in iter(obj):
    print(i)

for i in obj:
    print(i)

Los iteradores se pueden materializar como listas o tuplas utilizando las funciones constructoras list() o tuple():

>>> L = [1, 2, 3]
>>> iterator = iter(L)
>>> t = tuple(iterator)
>>> t
(1, 2, 3)

El desempaquetado de secuencias también soporta iteradores: si sabe que un iterador retornará N elementos, puede desempaquetarlos en una N-tupla:

>>> L = [1, 2, 3]
>>> iterator = iter(L)
>>> a, b, c = iterator
>>> a, b, c
(1, 2, 3)

Las funciones incorporadas como max() y min() pueden recibir un solo iterador como argumento y retornarán el elemento más grande o más pequeño. Los operadores "in" y "not in" también soportan iteradores: X in iterator es verdadero si X se encuentra en el flujo que retornó el iterador. Se encontrará con problemas obvios si el iterador es infinito; max(), min() nunca retornarán, y si el elemento X nunca aparece en el flujo, los operadores "in" y "not in" tampoco retornarán.

Note que solo puede ir hacia adelante en un iterador; no hay forma de obtener el elemento anterior, reiniciar el iterador o hacer una copia de él. Los objetos iteradores opcionalmente pueden proveer estas capacidades adicionales, pero el protocolo del iterador solo especifica el método __next__(). Por lo tanto las funciones pueden consumir toda la salida del iterador, y si necesita hacer algo diferente con el mismo flujo, tendrá que crear un nuevo iterador.

Tipos de datos que soportan iteradores

Ya hemos visto cómo las listas y tuplas soportan iteradores. De hecho, cualquier tipo de secuencia de Python, como cadenas de caracteres, automáticamente soportará la creación de un iterador.

Llamar a iter() en un diccionario retornará un iterador que recorrerá sobre las claves del diccionario:

>>> m = {'Jan': 1, 'Feb': 2, 'Mar': 3, 'Apr': 4, 'May': 5, 'Jun': 6,
...      'Jul': 7, 'Aug': 8, 'Sep': 9, 'Oct': 10, 'Nov': 11, 'Dec': 12}
>>> for key in m:
...     print(key, m[key])
Jan 1
Feb 2
Mar 3
Apr 4
May 5
Jun 6
Jul 7
Aug 8
Sep 9
Oct 10
Nov 11
Dec 12

Note que a partir de Python 3.7, se garantiza que el orden de iteración del diccionario es el mismo que el orden de inserción. En versiones anteriores, el comportamiento no estaba especificado y podía variar entre implementaciones.

Aplicar iter() a un diccionario siempre recorre sobre las claves, pero los diccionarios tienen métodos que retornan otros iteradores. Si quiere iterar sobre valores o pares clave/valor, puede explícitamente llamar a los métodos values() o items() para obtener un iterador apropiado.

El constructor dict() puede aceptar un iterador que retorna un flujo finito de tuplas (key, value):

>>> L = [('Italy', 'Rome'), ('France', 'Paris'), ('US', 'Washington DC')]
>>> dict(iter(L))
{'Italy': 'Rome', 'France': 'Paris', 'US': 'Washington DC'}

Los archivos también soportan iteración llamando al método readline() hasta que no haya más líneas en el archivo. Esto significa que puede leer cada línea de un archivo de esta forma:

for line in file:
    # do something for each line
    ...

Los conjuntos pueden recibir sus contenidos de un iterable y le permiten iterar sobre los elementos del conjunto:

S = {2, 3, 5, 7, 11, 13}
for i in S:
    print(i)

Expresiones generadoras y listas por comprensión

Dos operaciones comunes en la salida de un iterador son 1) realizar alguna operación para cada elemento, 2) elegir un subconjunto de elementos que reúnen alguna condición. Por ejemplo, dada una lista de cadena de caracteres, podría querer remover los espacios finales de cada línea o extraer todas las cadenas de caracteres que contienen una subcadena de caracteres dada.

Las listas por comprensión y las expresiones generadoras (forma abreviada: «listcomps» y «genexps») son una notación concisa para tales operaciones, prestadas del lenguaje de programación funcional Haskell (https://www.haskell.org/). Puede remover todos los espacios de un flujo de cadena de caracteres con el siguiente código:

line_list = ['  line 1\n', 'line 2  \n', ...]

# Generator expression -- returns iterator
stripped_iter = (line.strip() for line in line_list)

# List comprehension -- returns list
stripped_list = [line.strip() for line in line_list]

Puede seleccionar solo ciertos elementos agregando una condición "if":

stripped_list = [line.strip() for line in line_list
                 if line != ""]

Con una lista por comprensión, obtiene una lista de Python; stripped_list es una lista que contiene las líneas resultantes, no un iterador. Las expresiones generadoras retornan un iterador que calcula los valores cuando es necesario, sin necesidad de materializar todos los valores a la vez. Esto significa que las listas por comprensión son inútiles si está trabajando con iteradores que retornan un flujo infinito o una gran cantidad de datos. En estas situaciones son preferibles las expresiones generadoras.

Las expresiones generadoras están rodeadas por paréntesis («()») y las listas por comprensión están rodeadas por corchetes («[]»). Las expresiones generadoras tienen la forma:

( expression for expr in sequence1
             if condition1
             for expr2 in sequence2
             if condition2
             for expr3 in sequence3 ...
             if condition3
             for exprN in sequenceN
             if conditionN )

Nuevamente, para una lista por comprensión solo los corchetes exteriores son diferentes (corchetes en lugar de paréntesis).

Los elementos de la salida generada serán valores sucesivos de expression. Las cláusulas if son todas opcionales; si está presente, expression es solo evaluado y añadido al resultado cuando condition es verdadero.

Las expresiones generadoras siempre se tienen que escribir dentro de paréntesis, pero los paréntesis que indican la llamada a una función también cuentan. Si quiere crear un iterador que se pase inmediatamente a una función puede escribir:

obj_total = sum(obj.count for obj in list_all_objects())

Las cláusulas for...in contienen las secuencias sobre las que se itera. Las secuencias no tienen que tener la misma longitud, porque son iteradas de izquierda a derecha, no en paralelo. Por cada elemento en sequence1, se recorre sequence2 desde el inicio. Luego se recorre sequence3 por cada par de elementos resultante de sequence1 y sequence2.

Para ponerlo en otra forma, una lista por comprensión o expresión generadora es equivalente al siguiente código Python:

for expr1 in sequence1:
    if not (condition1):
        continue   # Skip this element
    for expr2 in sequence2:
        if not (condition2):
            continue   # Skip this element
        ...
        for exprN in sequenceN:
            if not (conditionN):
                continue   # Skip this element

            # Output the value of
            # the expression.

Esto significa que cuando hay múltiples cláusulas for...in pero no cláusulas if, la longitud de la salida resultante será igual al producto de las longitudes de todas las secuencias. Si tiene dos listas de longitud 3, la lista de salida tendrá 9 elementos:

>>> seq1 = 'abc'
>>> seq2 = (1, 2, 3)
>>> [(x, y) for x in seq1 for y in seq2]
[('a', 1), ('a', 2), ('a', 3),
 ('b', 1), ('b', 2), ('b', 3),
 ('c', 1), ('c', 2), ('c', 3)]

Para evitar introducir una ambigüedad en la gramática de Python, si expression está creando una tupla, debe estar rodeada de paréntesis. La primera lista por comprensión de abajo tiene un error de sintaxis, mientras que la segunda es correcta:

# Syntax error
[x, y for x in seq1 for y in seq2]
# Correct
[(x, y) for x in seq1 for y in seq2]

Generadores

Los generadores son una clase especial de funciones que simplifican la tarea de escribir iteradores. Las funciones regulares calculan un valor y lo devuelven, pero los generadores retornan un iterador que retorna un flujo de valores.

Sin duda está relacionado con cómo funcionan las llamadas a funciones regulares en Python o C. Cuando llama a una función, esta obtiene su espacio de nombres privado donde se crean sus variables locales. Cuando la función alcanza una sentencia return, las variables locales son destruidas y el valor se retorna al llamador. Una llamada posterior a la misma función crea un nuevo espacio de nombres privado y un conjunto limpio de variables locales. Pero, ¿qué pasa si las variables locales no fueron desechadas en la salida de una función? ¿Qué pasa si más tarde podría reanudar la función desde donde quedó? Esto es lo que proveen los generadores; se pueden pensar como funciones que se reanudan.

Este es el ejemplo más simple de una función generadora:

>>> def generate_ints(N):
...    for i in range(N):
...        yield i

Cualquier función que contiene una palabra clave yield es una función generadora; esto es detectado por el compilador bytecode de Python que compila la función de forma especial como resultado.

Cuando llama a una función generadora, no retorna un solo valor; en lugar de eso retorna un objeto generador que soporta el protocolo iterador. Al ejecutar la expresión yield, el generador produce el valor de i, de forma similar a una sentencia return. La gran diferencia entre una sentencia yield y un return es que al alcanzar un yield se suspende el estado de ejecución del generador y se preservan las variables locales. En la próxima llamada al método __next__() del generador, la función reanudará la ejecución.

Este es un ejemplo de uso del generador generate_ints():

>>> gen = generate_ints(3)
>>> gen
<generator object generate_ints at ...>
>>> next(gen)
0
>>> next(gen)
1
>>> next(gen)
2
>>> next(gen)
Traceback (most recent call last):
  File "stdin", line 1, in <module>
  File "stdin", line 2, in generate_ints
StopIteration

De igual forma podría escribir for i in generate_ints(5), o a, b, c = generate_ints(3).

Dentro de una función generadora, return value causa que se lance StopIteration(value) del método __next__(). Una vez que esto pase, o que se alcance el final de la función, termina la procesión de valores y el generador no puede producir más valores.

Podría lograr el efecto de los generadores manualmente escribiendo su propia clase y guardando todas las variables locales del generador como variables de instancia. Por ejemplo, retornar una lista de enteros se podría hacer estableciendo self.count a 0, y teniendo el método __next__() que incrementa self.count y lo retorna. Sin embargo, para un generador moderadamente complicado, escribir una clase correspondiente puede ser mucho más confuso.

El banco de pruebas incluido con la librería de Python, Lib/test/test_generators.py [https://github.com/python/cpython/tree/3.9/Lib/test/test_generators.py], contiene un número de ejemplos más interesantes. Este es un generador que implementa un recorrido inorden de un árbol usando generadores recursivamente.

# A recursive generator that generates Tree leaves in in-order.
def inorder(t):
    if t:
        for x in inorder(t.left):
            yield x

        yield t.label

        for x in inorder(t.right):
            yield x

Otros dos ejemplos en test_generators.py producen soluciones al problema de N-reinas (ubicar N reinas en un tablero de ajedrez de NxN de forma que ninguna reina amenace a otra) y el problema del caballo (encontrar una ruta que lleve a un caballo a cada cuadro de un tablero de ajedrez de NxN sin visitar ningún cuadro dos veces).

Pasar valores a un generador

En Python 2.4 y anteriores, los generadores solo producían salida. Una vez que el código de un generador era invocado para crear un iterador, no había forma de pasar ninguna información nueva a la función cuando se reanuda su ejecución. Podría lograr esta habilidad haciendo que el generador mire una variable global o pasando en algún objeto mutable que el llamador luego modifica, pero estos enfoques son confusos.

En Python 2.5 hay una forma más simple de pasar valores a un generador. yield se convirtió en una expresión, retornando un valor que se puede asignar a una variable o sobre el que se puede operar:

val = (yield i)

Recomiendo que siempre ponga paréntesis alrededor de una expresión yield cuando esté haciendo algo con el valor retornado, como en el ejemplo de arriba. Los paréntesis no siempre son necesarios, pero siempre es más fácil agregarlos en lugar de tener que recordar cuándo son necesarios.

(PEP 342 [https://www.python.org/dev/peps/pep-0342] explica las reglas exactas, que son que una expresión yield siempre debe estar entre paréntesis excepto cuando se encuentra en la expresión de primer nivel en el lado derecho de una asignación. Esto significa que puede escribir val = yield i pero tiene que usar paréntesis cuando hay una operación, como en val = (yield i) + 12.)

Los valores son enviados a un generador llamando a su método send(value). Este método reanuda el código del generador y la expresión yield retorna el valor especificado. Si se llama al método regular __next__(), yield retorna None.

Este es un simple contador que incrementa por 1 y permite cambiar los valores del contador interno.

def counter(maximum):
    i = 0
    while i < maximum:
        val = (yield i)
        # If value provided, change counter
        if val is not None:
            i = val
        else:
            i += 1

Y este es un ejemplo del cambio del contador:

>>> it = counter(10)
>>> next(it)
0
>>> next(it)
1
>>> it.send(8)
8
>>> next(it)
9
>>> next(it)
Traceback (most recent call last):
  File "t.py", line 15, in <module>
    it.next()
StopIteration

Como yield a menudo retornará None, siempre debería comprobar este caso. No use simplemente su valor en expresiones a menos que esté seguro que el método send() será el único método utilizado para reanudar su función generadora.

Además del método send(), hay otros dos métodos para generadores:

throw(value) is used to raise an exception inside the generator; the exception is raised by the yield expression where the generator’s execution is paused.

close() lanza una excepción GeneratorExit dentro del generador para terminar la iteración. Al recibir esta excepción, el código del generador debe lanzar GeneratorExit o StopIteration; capturar la excepción y hacer cualquier otra cosa es ilegal y disparará un RuntimeError. close() también se llamará por el recolector de basura de Python cuando se recolecte el generador.

Si necesita ejecutar un código de limpieza cuando ocurre un GeneratorExit, sugiero usar un try: ... finally: en lugar de capturar GeneratorExit.

El efecto acumulativo de estos cambios es convertir a los generadores de productores de información unidireccionales en productores y consumidores.

Los generadores también se convierten en corrutinas, una forma más generalizada de subrutinas. Las subrutinas inician en un punto y salen en otro punto (el inicio de la función, y la sentencia return), pero las corrutinas pueden iniciar, salir, y reanudarse en muchos puntos diferentes (las sentencias yield).

Funciones incorporadas

Veamos con más detalle las funciones incorporadas usadas a menudo con iteradores.

Dos de las funciones incorporadas de Python, map() y filter() duplican las características de las expresiones generadoras:

map(f, iterA, iterB, ...) retorna un iterador sobre la secuencia

f(iterA[0], iterB[0]), f(iterA[1], iterB[1]), f(iterA[2], iterB[2]), ....

>>> def upper(s):
...     return s.upper()

>>> list(map(upper, ['sentence', 'fragment']))
['SENTENCE', 'FRAGMENT']
>>> [upper(s) for s in ['sentence', 'fragment']]
['SENTENCE', 'FRAGMENT']

Por supuesto puede lograr el mismo efecto con una lista por comprensión.

filter(predicate, iter) retorna un iterador sobre todos los elementos de la secuencia que reúnen cierta condición, y de forma similar está duplicado por las listas por comprensión. Un predicado es una función que retorna un valor de verdad de alguna condición; para usarlo con filter(), el predicado debe recibir un solo valor.

>>> def is_even(x):
...     return (x % 2) == 0

>>> list(filter(is_even, range(10)))
[0, 2, 4, 6, 8]

Esto también se puede escribir como una lista por comprensión:

>>> list(x for x in range(10) if is_even(x))
[0, 2, 4, 6, 8]

enumerate(iter, start=0) enumera los elementos en el iterable retornando 2-tuplas que contienen la enumeración (desde start) y cada elemento.

>>> for item in enumerate(['subject', 'verb', 'object']):
...     print(item)
(0, 'subject')
(1, 'verb')
(2, 'object')

enumerate() a menudo se usa cuando se recorre una lista y se registran los índices en los que se reúnen una cierta condición:

f = open('data.txt', 'r')
for i, line in enumerate(f):
    if line.strip() == '':
        print('Blank line at line #%i' % i)

sorted(iterable, key=None, reverse=False) reúne todos los elementos de un iterable en una lista, ordena la lista, y retorna el resultado ordenado. Los argumentos key y reverse se pasan a través del método sort() de la lista construida.

>>> import random
>>> # Generate 8 random numbers between [0, 10000)
>>> rand_list = random.sample(range(10000), 8)
>>> rand_list
[769, 7953, 9828, 6431, 8442, 9878, 6213, 2207]
>>> sorted(rand_list)
[769, 2207, 6213, 6431, 7953, 8442, 9828, 9878]
>>> sorted(rand_list, reverse=True)
[9878, 9828, 8442, 7953, 6431, 6213, 2207, 769]

(Para un tratamiento más detallado del ordenamiento, ver HOW TO - Ordenar.)

Las funciones incorporadas any(iter) y all(iter) ven los valores de verdad de los contenidos de un iterable. any() retorna True si algún elemento en el iterable es un valor verdadero, y all() retorna True si todos los elementos son valores verdaderos:

>>> any([0, 1, 0])
True
>>> any([0, 0, 0])
False
>>> any([1, 1, 1])
True
>>> all([0, 1, 0])
False
>>> all([0, 0, 0])
False
>>> all([1, 1, 1])
True

zip(iterA, iterB, ...) toma un elemento de cada iterable y los retorna en una tupla:

zip(['a', 'b', 'c'], (1, 2, 3)) =>
  ('a', 1), ('b', 2), ('c', 3)

Esto no construye una lista en memoria y consume todos los iteradores de entrada antes de ejecutar; en lugar de eso, las tuplas se construyen y retornan solo si son requeridas. (El término técnico para este comportamiento es evaluación perezosa [https://es.wikipedia.org/wiki/Evaluaci%C3%B3n_perezosa].)

Se pretende que el iterador se use con iterables que tengan todos la misma longitud. Si los iterables son de diferentes longitudes, el flujo resultante tendrá la misma longitud que el iterable más corto.

zip(['a', 'b'], (1, 2, 3)) =>
  ('a', 1), ('b', 2)

Sin embargo, debería evitar hacer esto, porque se puede tomar un elemento de los iteradores más largos y descartarlo. Esto significa que ya no puede seguir usando los iteradores porque corre el riesgo de saltarse un elemento descartado.

El módulo itertools

El módulo itertools contiene un número de iteradores comúnmente usados así como funciones para combinar varios iteradores. Esta sección presentará los contenidos del módulo mostrando pequeños ejemplos.

Las funciones del módulo caen en unas pocas clases generales:

Funciones que crean un nuevo iterador basado en un iterador existente.

Funciones para tratar los elementos de un iterador como argumentos de función.

Funciones para seleccionar porciones de la salida de un iterador.

Una función para agrupar la salida de un iterador.

Crear nuevos iteradores

itertools.count(start, step) retorna un flujo infinito de valores equiespaciados. Opcionalmente puede suministrar el número de inicio, que por defecto es 0, y el intervalo entre números, que por defecto es 1:

itertools.count() =>
  0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ...
itertools.count(10) =>
  10, 11, 12, 13, 14, 15, 16, 17, 18, 19, ...
itertools.count(10, 5) =>
  10, 15, 20, 25, 30, 35, 40, 45, 50, 55, ...

itertools.cycle(iter) guarda una copia de los contenidos de un iterable provisto y retorna un nuevo iterador que retorna sus elementos del primero al último. El nuevo iterador repetirá estos elementos infinitamente.

itertools.cycle([1, 2, 3, 4, 5]) =>
  1, 2, 3, 4, 5, 1, 2, 3, 4, 5, ...

itertools.repeat(elem, [n]) retorna el elemento provisto n veces, o retorna el elemento indefinidamente si no se provee n.

itertools.repeat('abc') =>
  abc, abc, abc, abc, abc, abc, abc, abc, abc, abc, ...
itertools.repeat('abc', 5) =>
  abc, abc, abc, abc, abc

itertools.chain(iterA, iterB, ...) recibe un número arbitrario de iterables como entrada, y retorna todos los elementos del primer iterador, luego todos los elementos del segundo, y así sucesivamente, hasta que hayan sido agotados todos los iterables.

itertools.chain(['a', 'b', 'c'], (1, 2, 3)) =>
  a, b, c, 1, 2, 3

itertools.islice(iter, [start], stop, [step]) retorna un flujo que es un segmento del iterador. Con solo un argumento stop, retornará los primeros stop elementos. Si suministra un índice de inicio, obtendrá los elementos stop-start, y si suministra un valor para step, los elementos se saltarán en consecuencia. A diferencia de la segmentación de listas y cadenas de caracteres de Python, no puede usar valores negativos para start, stop o step.

itertools.islice(range(10), 8) =>
  0, 1, 2, 3, 4, 5, 6, 7
itertools.islice(range(10), 2, 8) =>
  2, 3, 4, 5, 6, 7
itertools.islice(range(10), 2, 8, 2) =>
  2, 4, 6

itertools.tee(iter, [n]) replica un iterador; retorna n iteradores independientes que retornarán los contenidos del iterador fuente. Si no suministra un valor para n, por defecto es 2. Replicar iteradores requiere guardar algunos de los contenidos del iterador fuente, esto puede consumir memoria significativa si el iterador es grande y uno de los nuevos iteradores se consume más que los otros.

itertools.tee( itertools.count() ) =>
   iterA, iterB

where iterA ->
   0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ...

and   iterB ->
   0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ...

Aplicar funciones a los elementos

El módulo operator contiene un conjunto de funciones correspondientes a los operadores de Python. Algunos ejemplos son operator.add(a, b) (suma dos valores), operator.ne(a, b) (lo mismo que a != b) y operator.attrgetter('id') (retorna un invocable que obtiene el atributo .id).

itertools.starmap(func, iter) asume que el iterable retornará un flujo de tuplas, y llama a func usando estas tuplas como los argumentos:

itertools.starmap(os.path.join,
                  [('/bin', 'python'), ('/usr', 'bin', 'java'),
                   ('/usr', 'bin', 'perl'), ('/usr', 'bin', 'ruby')])
=>
  /bin/python, /usr/bin/java, /usr/bin/perl, /usr/bin/ruby

Seleccionar elementos

Otro grupo de funciones elige un subconjunto de elementos de un iterador basado en un predicado dado.

itertools.filterfalse(predicate, iter) es el opuesto de filter(), retornando todos los elementos para los que el predicado retorna falso:

itertools.filterfalse(is_even, itertools.count()) =>
  1, 3, 5, 7, 9, 11, 13, 15, ...

itertools.takewhile(predicate, iter) retorna los elementos mientras el predicado retorne verdadero. Una vez que el predicado retorna falso, el iterador indicará el final de sus resultados.

def less_than_10(x):
    return x < 10

itertools.takewhile(less_than_10, itertools.count()) =>
  0, 1, 2, 3, 4, 5, 6, 7, 8, 9

itertools.takewhile(is_even, itertools.count()) =>
  0

itertools.dropwhile(predicate, iter) descarta los elementos mientras el predicado retorne verdadero, y luego retorna el resto de los resultados del iterable.

itertools.dropwhile(less_than_10, itertools.count()) =>
  10, 11, 12, 13, 14, 15, 16, 17, 18, 19, ...

itertools.dropwhile(is_even, itertools.count()) =>
  1, 2, 3, 4, 5, 6, 7, 8, 9, 10, ...

itertools.compress(data, selectors) recibe dos iteradores y retorna solo aquellos elementos de data para los cuales el elemento correspondiente de selectors es verdadero, deteniéndose cuando alguno se termine:

itertools.compress([1, 2, 3, 4, 5], [True, True, False, False, True]) =>
   1, 2, 5

Funciones combinatorias

La función itertools.combinations(iterable, r) retorna un iterador proporcionando todas las combinaciones de r-tuplas de los elementos contenidos en iterable.

itertools.combinations([1, 2, 3, 4, 5], 2) =>
  (1, 2), (1, 3), (1, 4), (1, 5),
  (2, 3), (2, 4), (2, 5),
  (3, 4), (3, 5),
  (4, 5)

itertools.combinations([1, 2, 3, 4, 5], 3) =>
  (1, 2, 3), (1, 2, 4), (1, 2, 5), (1, 3, 4), (1, 3, 5), (1, 4, 5),
  (2, 3, 4), (2, 3, 5), (2, 4, 5),
  (3, 4, 5)

Los elementos dentro de cada tupla permanecen en el mismo orden en el que iterable los retornó. Por ejemplo, el número 1 siempre está antes que 2, 3, 4 o 5 en los ejemplos de arriba. Una función similar, itertools.permutations(iterable, r=None), remueve esta restricción en el orden, retornando todas las disposiciones posibles de longitud r:

itertools.permutations([1, 2, 3, 4, 5], 2) =>
  (1, 2), (1, 3), (1, 4), (1, 5),
  (2, 1), (2, 3), (2, 4), (2, 5),
  (3, 1), (3, 2), (3, 4), (3, 5),
  (4, 1), (4, 2), (4, 3), (4, 5),
  (5, 1), (5, 2), (5, 3), (5, 4)

itertools.permutations([1, 2, 3, 4, 5]) =>
  (1, 2, 3, 4, 5), (1, 2, 3, 5, 4), (1, 2, 4, 3, 5),
  ...
  (5, 4, 3, 2, 1)

Si no suministra un valor para r se usa la longitud del iterable, lo que significa que se permutan todos los elementos.

Note que estas funciones producen todas las combinaciones posibles por posición y no requieren que los contenidos de iterable sean únicos:

itertools.permutations('aba', 3) =>
  ('a', 'b', 'a'), ('a', 'a', 'b'), ('b', 'a', 'a'),
  ('b', 'a', 'a'), ('a', 'a', 'b'), ('a', 'b', 'a')

La tupla idéntica ('a', 'a', 'b') aparece dos veces, pero las dos cadenas de caracteres “a” provienen de diferentes posiciones.

La función itertools.combinations_with_replacement(iterable, r) relaja una restricción diferente: los elementos se pueden repetir dentro de una misma tupla. Conceptualmente un elemento se elige para la primera posición de cada tupla y luego se reemplaza antes de que se elija el segundo elemento.

itertools.combinations_with_replacement([1, 2, 3, 4, 5], 2) =>
  (1, 1), (1, 2), (1, 3), (1, 4), (1, 5),
  (2, 2), (2, 3), (2, 4), (2, 5),
  (3, 3), (3, 4), (3, 5),
  (4, 4), (4, 5),
  (5, 5)

Agrupar elementos

La última función que trataré, itertools.groupby(iter, key_func=None), es la más complicada. key_func(elem) es una función que calcula un valor clave para cada elemento retornado por el iterable. Si no suministra una función de clave, la clave será simplemente el elemento mismo.

groupby() reúne todos los elementos consecutivos del iterable subyacente que tienen el mismo valor clave, y retorna un flujo de 2-tuplas que contienen un valor clave y un iterador para los elementos con esa clave.

city_list = [('Decatur', 'AL'), ('Huntsville', 'AL'), ('Selma', 'AL'),
             ('Anchorage', 'AK'), ('Nome', 'AK'),
             ('Flagstaff', 'AZ'), ('Phoenix', 'AZ'), ('Tucson', 'AZ'),
             ...
            ]

def get_state(city_state):
    return city_state[1]

itertools.groupby(city_list, get_state) =>
  ('AL', iterator-1),
  ('AK', iterator-2),
  ('AZ', iterator-3), ...

where
iterator-1 =>
  ('Decatur', 'AL'), ('Huntsville', 'AL'), ('Selma', 'AL')
iterator-2 =>
  ('Anchorage', 'AK'), ('Nome', 'AK')
iterator-3 =>
  ('Flagstaff', 'AZ'), ('Phoenix', 'AZ'), ('Tucson', 'AZ')

groupby() asume que los contenidos del iterable subyacente ya se ordenó basado en la clave. Note que los iteradores retornados también usan el iterable subyacente, así que tiene que consumir los resultados de iterador-1 antes de solicitar iterador-2 y su clave correspondiente.

El módulo functools

El módulo functools en Python 2.5 contiene algunas funciones de orden superior. Una función de orden superior recibe una o más funciones como entrada y retorna una nueva función. La herramienta más útil en este módulo es la función functools.partial().

Para programas escritos en un estilo funcional, a veces querrá construir variantes de funciones existentes que tienen algunos de los parámetros predefinidos. Considere una función de Python f(a, b, c); puede querer crear una nueva función g(b, c) que sea equivalente a f(1, b, c); está completando un valor para uno de los parámetros de f(). Esto se llama «aplicación parcial de funciones».

El constructor para partial() recibe los argumentos (function, arg1, arg2, ..., kwarg1=value1, kwarg2=value2). El objeto resultante es invocable, por lo que puede invocar a function con los argumentos rellenados.

Aquí hay un ejemplo pequeño pero realista:

import functools

def log(message, subsystem):
    """Write the contents of 'message' to the specified subsystem."""
    print('%s: %s' % (subsystem, message))
    ...

server_log = functools.partial(log, subsystem='server')
server_log('Unable to open socket')

functools.reduce(func, iter, [initial_value]) realiza acumulativamente una operación en todos los elementos del iterable y, por lo tanto, no se puede aplicar a infinitos iterables. func debe ser una función que recibe dos elementos y retorna un solo valor. functools.reduce() recibe los primeros dos elementos A y B retornados por el iterador y calcula func(A, B). Luego pide el tercer elemento, C, calcula func(func(A, B), C), combina este resultado con el cuarto elemento retornado, y continua hasta que se agote el iterable. Si el iterable no retorna ningún valor, se lanza una excepción TypeError. Si se suministra el valor inicial, se usa como punto inicial y func(initial_value, A) es el primer cálculo.

>>> import operator, functools
>>> functools.reduce(operator.concat, ['A', 'BB', 'C'])
'ABBC'
>>> functools.reduce(operator.concat, [])
Traceback (most recent call last):
  ...
TypeError: reduce() of empty sequence with no initial value
>>> functools.reduce(operator.mul, [1, 2, 3], 1)
6
>>> functools.reduce(operator.mul, [], 1)
1

Si usa operator.add() con functools.reduce(), sumará todos los elementos del iterable. Este caso es tan común que hay una función incorporada especial llamada sum() para calcularla:

>>> import functools, operator
>>> functools.reduce(operator.add, [1, 2, 3, 4], 0)
10
>>> sum([1, 2, 3, 4])
10
>>> sum([])
0

Sin embargo, para muchos usos de functools.reduce() puede ser mas claro simplemente escribir el ciclo for:

import functools
# Instead of:
product = functools.reduce(operator.mul, [1, 2, 3], 1)

# You can write:
product = 1
for i in [1, 2, 3]:
    product *= i

Una función relacionada es itertools.accumulate(iterable, func=operator.add). Realiza el mismo cálculo, pero en lugar de retornar solo el resultado final, accumulate() retorna un iterador que también produce cada resultado parcial:

itertools.accumulate([1, 2, 3, 4, 5]) =>
  1, 3, 6, 10, 15

itertools.accumulate([1, 2, 3, 4, 5], operator.mul) =>
  1, 2, 6, 24, 120

El módulo operator

El módulo operator se mencionó anteriormente. Contiene un conjunto de funciones que corresponden a los operadores de Python. Estas funciones a menudo son útiles en código en estilo funcional porque le salvan de escribir funciones triviales que realizan una sola operación.

Algunas de las funciones en este módulo son:

Operaciones matemáticas: add(), sub(), mul(), floordiv(), abs(), …

Operaciones lógicas: not_(), truth().

Operaciones bit a bit: and_(), or_(), invert().

Comparaciones: eq(), ne(), lt(), le(), gt() y ge().

Identidad de objeto: is_(), is_not().

Consulte la documentación del módulo operator para una lista completa.

Funciones pequeñas y la expresión lambda

Cuando se escriben programas en estilo funcional, a menudo necesitará pequeñas funciones que actúen como predicados o que combinen elementos de alguna manera.

Si hay una función incorporada o un módulo de Python, no necesita definir una nueva función en absoluto:

stripped_lines = [line.strip() for line in lines]
existing_files = filter(os.path.exists, file_list)

Si la función que necesita no existe, necesita escribirla. Una forma de escribir funciones pequeñas es usar la expresión lambda. lambda recibe un número de parámetros y una expresión que combina estos parámetros, y crea una función anónima que retorna el valor de la expresión:

adder = lambda x, y: x+y

print_assign = lambda name, value: name + '=' + str(value)

Una alternativa es simplemente usar la sentencia def y definir una función en la forma usual:

def adder(x, y):
    return x + y

def print_assign(name, value):
    return name + '=' + str(value)

¿Qué alternativa es preferible? Esa es una pregunta de estilo; mi rumbo usual es evitar usar lambda.

Una razón para mi preferencia es que lambda es muy limitado en las funciones que puede definir. El resultado tiene que ser calculable como una sola expresión, que significa que no tiene comparaciones multivía if... elif... else o sentencias try... except. Si intenta hacer mucho en una sentencia lambda, terminará con una expresión demasiado complicada que es difícil de leer. Rápido, ¿qué hace el siguiente código?

import functools
total = functools.reduce(lambda a, b: (0, a[1] + b[1]), items)[1]

Puede averiguarlo, pero toma tiempo desenredar la expresión para averiguar que está pasando. Usar una corta sentencia def anidada hace las cosas un poco mejor:

import functools
def combine(a, b):
    return 0, a[1] + b[1]

total = functools.reduce(combine, items)[1]

Pero lo mejor de todo sería si simplemente hubiese usado un ciclo for:

total = 0
for a, b in items:
    total += b

O la función incorporada sum() y una expresión generadora:

total = sum(b for a, b in items)

Muchos usos de functools.reduce() son más claros cuando se escriben como ciclos for.

Fredrik Lundh una vez sugirió el siguiente conjunto de reglas para refactorizar los usos de lambda:

Escribir una función lambda.

Escribir un comentario explicando qué demonios hace esa lambda.

Estudiar el comentario por un momento, y pensar en un nombre que capture la esencia del comentario.

Convertir la lambda a una sentencia def, usando ese nombre.

Remover el comentario.

Me gustan mucho estas reglas, pero es libre de disentir acerca de si este estilo libre de lambda es mejor.

Historia de revisiones y reconocimientos

Al autor le gustaría agradecer a las siguientes personar por ofrecer sugerencias, correcciones y asistencia con varios borradores de este articulo: Ian Bicking, Nick Coghlan, Nick Efford, Raymond Hettinger, Jim Jewett, Mike Krell, Leandro Lameiro, Jussi Salmela, Collin Winter, Blake Winton.

Versión 0.1: publicada el 30 de junio de 2006.

Versión 0.11: publicada el 1 de julio de 2006. Errores tipográficos arreglados.

Versión 0.2: publicada el 10 de julio de 2006. Secciones genexp y listcomp unidas en una sola. Errores tipográficos arreglados.

Versión 0.21: Agregadas mas referencias sugeridas en la lista de correos tutor.

Versión 0.30: Agrega una sección sobre el módulo functional escrito por Collin Winter; agrega una sección corta sobre el módulo operator; y unas pocas otras ediciones.

Referencias

Generales

Estructura e interpretación de programas de computadora, por Harold Abelson y Gerald Jay Sussman con Julie Sussman. Texto completo en https://mitpress.mit.edu/sicp/. En este libro clásico de ciencia de computación, los capítulos 2 y 3 tratan el uso de secuencias y flujos para organizar el flujo de datos dentro de un programa. El libro usa Scheme para sus ejemplos, pero muchos de los enfoques de diseño descritos en estos capítulos son aplicables al código de Python en estilo funcional.

http://www.defmacro.org/ramblings/fp.html: Una introducción general a la programación funcional que usa ejemplos en Java y tiene una introducción histórica extensa.

https://es.wikipedia.org/wiki/Programaci%C3%B3n_funcional: Entrada general de Wikipedia que describe la programación funcional.

https://es.wikipedia.org/wiki/Corrutina: Entrada para corrutinas.

https://es.wikipedia.org/wiki/Currificaci%C3%B3n: Entrada para el concepto de currificación.

Específicas de Python

http://gnosis.cx/TPiP/: El primer capítulo del libro de David Mertz Text Processing in Python trata la programación funcional para procesamiento de texto, en la sección titulada «Utilizando funciones de orden superior en procesamiento de texto».

Mertz también escribió una serie de artículos de 3 partes sobre programación funcional para el sitio DeveloperWorks de IBM; ver parte 1 [https://developer.ibm.com/articles/l-prog/], parte 2 [https://developer.ibm.com/tutorials/l-prog2/], y parte 3 [https://developer.ibm.com/tutorials/l-prog3/],

Documentación de Python

Documentación del módulo itertools.

Documentación del módulo functools.

Documentación del módulo operator.

PEP 289 [https://www.python.org/dev/peps/pep-0289]: «Expresiones generadoras»

PEP 342 [https://www.python.org/dev/peps/pep-0342]: «Corrutinas a través de generadores mejorados» describe las características del nuevo generador en Python 2.5.

HOWTO Hacer Registros (Logging)

Autor

Vinay Sajip <vinay_sajip at red-dove dot com>

Tutorial Básico de Logging

Logging es un medio de rastrear los eventos que ocurren cuando se ejecuta algún software. El desarrollador del software agrega llamadas de registro a su código para indicar que ciertos eventos han ocurrido. Un evento se describe mediante un mensaje descriptivo que puede contener opcionalmente datos variables (es decir, datos que son potencialmente diferentes para cada ocurrencia del evento). Los eventos también tienen una importancia que el desarrollador atribuye al evento; la importancia también puede llamarse el nivel o la severidad.

Cuándo usar logging

Logging proporciona un conjunto de funciones convenientes para un uso sencillo de registro. Estas son debug(), info(), warning(), error() y critical(). Para determinar cuándo usar el registro, vea la tabla de abajo, que indica, para cada una de las tareas comunes, la mejor herramienta a usar para ello.

La tarea que quieres realizar

La mejor herramienta para la tarea

Mostrar salidas de la consola para el uso ordinario de un programa o guión (script) de línea de comandos

print()

Reportar eventos que ocurren durante el funcionamiento normal de un programa (por ejemplo, para la supervisión del estado o la investigación de fallos)

logging.info() (o logging.debug() para salidas de registro muy detalladas con fines de diagnóstico)

Emitir una advertencia con respecto a un evento de tiempo de ejecución en particular

warnings.warn() en el código de la biblioteca si el problema es evitable y la aplicación cliente debe ser modificada para eliminar la advertencia

logging.warning() si no hay nada que la aplicación cliente pueda hacer sobre la situación, pero el evento debe ser anotado

Reportar un error con respecto a un evento particular al tiempo de ejecución

Lanza una excepción

Reporta la supresión de un error sin invocar una excepción (por ejemplo, el manejador de errores en un proceso de servidor de larga duración)

logging.error(), logging.exception() o logging.critical() según sea apropiado para el error específico y el dominio de la aplicación

Las funciones de registro se denominan según el nivel o la gravedad de los eventos que se utilizan para rastrear. A continuación se describen los niveles estándar y su aplicabilidad (en orden creciente de gravedad):

Nivel

Cuando es usado

DEBUG

Información detallada, típicamente de interés sólo durante el diagnóstico de problemas.

INFO

Confirmación de que las cosas están funcionando como se esperaba.

WARNING

Un indicio de que algo inesperado sucedió, o indicativo de algún problema en el futuro cercano (por ejemplo, «espacio de disco bajo»). El software sigue funcionando como se esperaba.

ERROR

Debido a un problema más grave, el software no ha sido capaz de realizar alguna función.

CRITICAL

Un grave error, que indica que el programa en sí mismo puede ser incapaz de seguir funcionando.

El nivel por defecto es WARNING, lo que significa que sólo los eventos de este nivel y superiores serán rastreados, a menos que el paquete de registro esté configurado para hacer lo contrario.

Los eventos que se rastrean pueden ser manejados en diferentes maneras. La forma más simple de manejar los eventos rastreados es imprimirlos en la consola o terminal. Otra forma común es escribirlos en un archivo de disco.

Un simple ejemplo

Un ejemplo muy simple es:

import logging
logging.warning('Watch out!')  # will print a message to the console
logging.info('I told you so')  # will not print anything

Si escribes estas líneas en un script y lo ejecutas, verás:

WARNING:root:Watch out!

impreso en la consola. El mensaje INFO no aparece porque el nivel por defecto es WARNING. El mensaje impreso incluye la indicación del nivel y la descripción del evento proporcionado en la llamada de registro, es decir, «¡Cuidado!». No te preocupes por la parte de la ‘root’ por ahora: se explicará más adelante. La salida real puede ser formateada con bastante flexibilidad si lo necesita; las opciones de formato también se explicarán más adelante.

Logging a un archivo

Una situación muy común es la de registrar archivos de log, así que veamos eso a continuación. Asegúrese de intentar lo siguiente en un intérprete de Python recién iniciado, y no sólo continúe de la sesión descrita anteriormente:

import logging
logging.basicConfig(filename='example.log', encoding='utf-8', level=logging.DEBUG)
logging.debug('This message should go to the log file')
logging.info('So should this')
logging.warning('And this, too')
logging.error('And non-ASCII stuff, too, like Øresund and Malmö')

Distinto en la versión 3.9: Se agregó el argumento encoding. En versiones anteriores de Python, o si no se especifica, la codificación utilizada es el valor predeterminado utilizado por open(). Aunque no se muestra en el ejemplo anterior, ahora también se puede pasar un argumento errors, que determina cómo se manejan los errores de codificación. Para conocer los valores disponibles y los predeterminados, consulte la documentación de open().

Y ahora si abrimos el archivo y miramos lo que tenemos, deberíamos encontrar los mensajes de registro:

DEBUG:root:This message should go to the log file
INFO:root:So should this
WARNING:root:And this, too
ERROR:root:And non-ASCII stuff, too, like Øresund and Malmö

Este ejemplo también muestra cómo se puede establecer el nivel de registro que actúa como umbral para el rastreo. En este caso, como establecimos el umbral en DEBUG, todos los mensajes fueron impresos.

Si quieres establecer el nivel de registro desde una opción de línea de comandos como:

--log=INFO

y tienes el valor del parámetro pasado por --log en alguna variable loglevel, puedes usar:

getattr(logging, loglevel.upper())

para obtener el valor que pasarás a basicConfig() mediante el argumento level. Puede que quieras comprobar un error por cualquier valor de entrada del usuario, quizás como en el siguiente ejemplo:

# assuming loglevel is bound to the string value obtained from the
# command line argument. Convert to upper case to allow the user to
# specify --log=DEBUG or --log=debug
numeric_level = getattr(logging, loglevel.upper(), None)
if not isinstance(numeric_level, int):
    raise ValueError('Invalid log level: %s' % loglevel)
logging.basicConfig(level=numeric_level, ...)

La llamada a basicConfig() debería venir antes de cualquier llamada a debug(), info() etc. Como se pretende hacer una simple facilidad de configuración única, sólo la primera llamada hará realmente algo: las llamadas subsiguientes son efectivamente no-ops.

Si ejecutas el script anterior varias veces, los mensajes de las ejecuciones sucesivas se añaden al archivo example.log. Si quieres que cada ejecución se inicie de nuevo, sin recordar los mensajes de ejecuciones anteriores, puedes especificar el argumento filemode, cambiando la llamada en el ejemplo anterior a:

logging.basicConfig(filename='example.log', filemode='w', level=logging.DEBUG)

La impresión será la misma que antes, pero el archivo de registro ya no se adjunta, por lo que los mensajes de las ejecuciones anteriores se pierden.

Logging de múltiples módulos

Si su programa consiste de múltiples módulos, aquí hay un ejemplo de cómo podría organizar el inicio de sesión en él:

# myapp.py
import logging
import mylib

def main():
    logging.basicConfig(filename='myapp.log', level=logging.INFO)
    logging.info('Started')
    mylib.do_something()
    logging.info('Finished')

if __name__ == '__main__':
    main()

# mylib.py
import logging

def do_something():
    logging.info('Doing something')

Si ejecutas myapp.py, deberías ver esto en myapp.log:

INFO:root:Started
INFO:root:Doing something
INFO:root:Finished

que es lo que esperabas ver. Puedes generalizar esto a múltiples módulos, usando el modelo en mylib.py. Ten en cuenta que para este simple patrón de uso, no sabrás, mirando en el archivo de registro, donde en tu aplicación vinieron tus mensajes, aparte de mirar la descripción del evento. Si quieres rastrear la ubicación de tus mensajes, tendrás que consultar la documentación más allá del nivel del tutorial – ver Tutorial de registro avanzado.

Registrar datos de variables

Para registrar los datos de variables, utilice una cadena de formato para el mensaje de descripción del evento y añada los datos variables como argumentos. Por ejemplo:

import logging
logging.warning('%s before you %s', 'Look', 'leap!')

se mostrará:

WARNING:root:Look before you leap!

Como puede ver, la fusión de datos variables en el mensaje de descripción del evento utiliza el antiguo estilo % de formato de cadena. Esto es por compatibilidad con versiones anteriores: el paquete de registro es anterior a opciones de formato más nuevas, como str.format() y string.Template. Estas nuevas opciones de formato son compatibles, pero explorarlas está fuera del alcance de este tutorial: consulte Usar estilos de formato particulares en toda su aplicación para obtener más información.

Cambiar el formato de los mensajes mostrados

Para cambiar el formato que se utiliza para visualizar los mensajes, es necesario especificar el formato que se desea utilizar:

import logging
logging.basicConfig(format='%(levelname)s:%(message)s', level=logging.DEBUG)
logging.debug('This message should appear on the console')
logging.info('So should this')
logging.warning('And this, too')

que se imprimirá:

DEBUG:This message should appear on the console
INFO:So should this
WARNING:And this, too

Noten que la ‘root’ que aparecía en los ejemplos anteriores ha desaparecido. Para un conjunto completo de cosas que pueden aparecer en formato de cadenas, puede consultar la documentación de Atributos LogRecord, pero para un uso sencillo, sólo necesita el levelname (gravedad), message (descripción del evento, incluyendo los datos variables) y tal vez mostrar cuándo ocurrió el evento. Esto se describe en la siguiente sección.

Visualización de la fecha/hora en los mensajes

Para mostrar la fecha y la hora de un evento, usted colocaría “%(asctime)s” en su cadena de formato:

import logging
logging.basicConfig(format='%(asctime)s %(message)s')
logging.warning('is when this event was logged.')

que debería imprimir algo como esto:

2010-12-12 11:41:42,612 is when this event was logged.

El formato por defecto para la visualización de la fecha/hora (mostrado arriba) es como ISO8601 o RFC 3339 [https://tools.ietf.org/html/rfc3339.html]. Si necesita más control sobre el formato de la fecha/hora, proporcione un argumento datefmt a basicConfig, como en este ejemplo:

import logging
logging.basicConfig(format='%(asctime)s %(message)s', datefmt='%m/%d/%Y %I:%M:%S %p')
logging.warning('is when this event was logged.')

que mostraría algo como esto:

12/12/2010 11:46:36 AM is when this event was logged.

El formato del argumento datefmt es el mismo que el soportado por time.strftime().

Próximos pasos

Eso concluye el tutorial básico. Debería ser suficiente para ponerte en marcha con el registro. Hay mucho más que el paquete de registro ofrece, pero para obtener lo mejor de él, tendrá que invertir un poco más de su tiempo en la lectura de las siguientes secciones. Si estás listo para eso, toma un poco de tu bebida favorita y sigue adelante.

Si sus necesidades de registro son sencillas, utilice los ejemplos previos para incorporar el registro en sus propios scripts, y si tiene problemas o no entiende algo, por favor publique una pregunta en el grupo Usenet de comp.lang.python (disponible en https://groups.google.com/forum/#!forum/comp.lang.python) y debería recibir ayuda antes de que transcurra demasiado tiempo.

¿Todavía esta aquí? Puedes seguir leyendo las siguientes secciones, que proporcionan un tutorial un poco más avanzado y profundo que el básico de arriba. Después de eso, puedes echar un vistazo al Libro de recetas de Logging.

Tutorial de registro avanzado

La biblioteca de logging adopta un enfoque modular y ofrece varias categorías de componentes: registradores, gestores, filtros y formateadores.

Los registradores exponen la interfaz que el código de la aplicación utiliza directamente.

Los gestores envían los registros de log (creados por los registradores) al destino apropiado.

Los filtros proporcionan una instalación de grano más fino para determinar qué registros de log se deben producir.

Los formatos especifican la disposición de los archivos de log en el resultado final.

La información de los eventos de registro se pasa entre los registradores, gestores, filtros y formateadores en una instancia LogRecord.

El registro se realiza llamando a métodos en instancias de la clase Logger (de aquí en adelante llamada loggers). Cada instancia tiene un nombre, y se organizan conceptualmente en una jerarquía de espacios de nombres utilizando puntos (puntos) como separadores. Por ejemplo, un registrador llamado “scan” es el padre de los registradores “scan.text”, “scan.html” y “scan.pdf”. Los nombres de los registradores pueden ser cualquier cosa que se desee, e indican el área de una aplicación en la que se origina un mensaje registrado.

Una buena convención que se puede utilizar para nombrar a los registradores es utilizar un registrador a nivel de módulo, en cada módulo que utilice el registro, llamado de la siguiente manera:

logger = logging.getLogger(__name__)

Esto significa que los nombres de los registradores rastrean la jerarquía de paquetes/módulos, y es intuitivamente obvio donde se registran los eventos sólo a partir del nombre del registrador.

La raíz de la jerarquía de los registradores se llama root logger. Ese es el registrador usado por las funciones debug(), info(), warning(), error() y critícal(), que sólo llaman al mismo método del registrador raíz. Las funciones y los métodos tienen las mismas firmas. El nombre del root logger se imprime como ‘root’ en la salida registrada.

Por supuesto, es posible registrar mensajes a diferentes destinos. El paquete incluye soporte para escribir mensajes de registro en archivos, ubicaciones HTTP GET/POST, correo electrónico a través de SMTP, sockets genéricos, colas o mecanismos de registro específicos del sistema operativo como syslog o el registro de eventos de Windows NT. Los destinos son servidos por clases handler. Puedes crear tu propia clase de destino de registro si tienes requisitos especiales que no se cumplen con ninguna de las clases de gestor incorporadas.

Por defecto, no se establece ningún destino para los mensajes de registro. Puede especificar un destino (como consola o archivo) usando basicConfig() como en los ejemplos del tutorial. Si llama a las funciones debug(), info(), warning(), error() y critical(), ellas comprobarán si no hay ningún destino establecido; y si no hay ninguno establecido, establecerán un destino de la consola (sys.stderr) y un formato por defecto para el mensaje mostrado antes de delegar en el registrador root para hacer la salida real del mensaje.

El formato por defecto establecido por basicConfig() para los mensajes es:

severity:logger name:message

Puedes cambiar esto pasando una cadena de formato a basicConfig() con el argumento de la palabra clave format. Para todas las opciones relativas a cómo se construye una cadena de formato, ver Objetos formateadores.

Flujo de Registro

En el siguiente diagrama se ilustra el flujo de información de los eventos de registro en los registradores y gestores.

Registradores

Los objetos de Logger tienen un trabajo triple. Primero, exponen varios métodos al código de la aplicación para que las aplicaciones puedan registrar mensajes en tiempo de ejecución. Segundo, los objetos logger determinan sobre qué mensajes de registro actuar en base de la severidad (la facilidad de filtrado por defecto) o los objetos de filtro. Tercero, los objetos registradores pasan los mensajes de registro relevantes a todos los manejadores de registro interesados.

Los métodos más utilizados en los objetos de registro se dividen en dos categorías: configuración y envío de mensajes.

Estos son los métodos de configuración más comunes:

Logger.setLevel() especifica el mensaje de registro de menor gravedad que un registrador manejará, donde debug es el nivel de gravedad incorporado más bajo y critical es el de mayor gravedad incorporado. Por ejemplo, si el nivel de severidad es INFO, el registrador sólo manejará los mensajes INFO, WARNING, ERROR y CRITICAL e ignorará los mensajes DEBUG.

Logger.addHandler() y Logger.removeHandler() agregan y quitan los objetos handler del objeto logger. Los manejadores (handlers) se tratan con más detalle en Gestores.

Logger.addFilter() y Logger.removeFilter() agregan y quitan los objetos de filtro del objeto logger. Los filtros se tratan con más detalle en Filtro de Objetos.

No es necesario que siempre llames a estos métodos en cada registrador que crees. Vea los dos últimos párrafos de esta sección.

Con el objeto logger configurado, los siguientes métodos crean mensajes de log:

Logger.debug(), Logger.info(), Logger.warning(), Logger.error(), y Logger.critical() todos crean registros de registro con un mensaje y un nivel que corresponde a sus respectivos nombres de método. El mensaje es en realidad una cadena de formato, que puede contener la sintaxis estándar de sustitución de cadenas de %s, %d, %f, y así sucesivamente. El resto de sus argumentos es una lista de objetos que se corresponden con los campos de sustitución del mensaje. Con respecto a **kwargs, los métodos de registro sólo se preocupan por una palabra clave de exc_info y la usan para determinar si registran información de excepción.

Logger.exception() crea un mensaje de registro similar a Logger.error(). La diferencia es que Logger.exception() vuelca un rastro de pila junto con él. Llama a este método sólo desde un manejador de excepciones.

Logger.log() toma un nivel de log como argumento explícito. Esto es un poco más verboso para el registro de mensajes que usar los métodos de conveniencia de nivel de registro listados arriba, pero así es como se registra en niveles de registro personalizados.

getLogger() retorna una referencia a una instancia de logger con el nombre especificado si se proporciona, o root si no. Los nombres son estructuras jerárquicas separadas por períodos. Múltiples llamadas a getLogger() con el mismo nombre retornarán una referencia al mismo objeto logger. Los loggers que están más abajo en la lista jerárquica son hijos de los loggers que están más arriba en la lista. Por ejemplo, dado un logger con un nombre de foo, los loggers con nombres de foo.bar, foo.bar.baz, y foo.bam son todos descendientes de foo.

Los registradores tienen un concepto de nivel efectivo. Si un nivel no se establece explícitamente en un registrador, el nivel de su clase padre se utiliza en su lugar como su nivel efectivo. Si el padre no tiene un nivel explícito establecido, su padre es examinado, y así sucesivamente - se buscan todos los ancestros hasta que se encuentra un nivel explícitamente establecido. El registrador raíz siempre tiene un conjunto de niveles explícito (Advertencia por defecto). Cuando se decide si se procesa un evento, el nivel efectivo del registrador se utiliza para determinar si el evento se pasa a los manejadores del registrador.

Los loggers inferiores propagan mensajes hasta los gestores asociados con sus loggers ancestros. Debido a esto, no es necesario definir y configurar los manejadores para todos los registradores que utiliza una aplicación. Basta con configurar los manejadores para un registrador de nivel superior y crear registradores hijos según sea necesario. (Sin embargo, puedes desactivar la propagación estableciendo el atributo propagate de un logger en False.)

Gestores

Los objetos Handler son responsables de enviar los mensajes de registro apropiados (basados en la severidad de los mensajes de registro) al destino especificado por el handler. Logger los objetos pueden añadir cero o más objetos handler a sí mismos con un método addHandler(). Como escenario de ejemplo, una aplicación puede querer enviar todos los mensajes de registro a un archivo de registro, todos los mensajes de registro de error o superiores a stdout, y todos los mensajes de crítico a una dirección de correo electrónico. Este escenario requiere tres manejadores individuales donde cada manejador es responsable de enviar mensajes de una severidad específica a una ubicación específica.

La biblioteca estándar incluye bastantes tipos de handler (ver Gestores útiles); los tutoriales usan principalmente StreamHandler y FileHandler en sus ejemplos.

Hay muy pocos métodos en un manejador para que los desarrolladores de aplicaciones se preocupen. Los únicos métodos de manejador que parecen relevantes para los desarrolladores de aplicaciones que utilizan los objetos de manejador incorporados (es decir, que no crean manejadores personalizados) son los siguientes métodos de configuración:

El método setLevel(), al igual que en los objetos de logger, especifica la menor gravedad que será enviada al destino apropiado. ¿Por qué hay dos métodos setLevel()? El nivel establecido en el registrador determina qué gravedad de los mensajes pasará a sus manejadores. El nivel establecido en cada manejador determina qué mensajes enviará ese manejador.

setFormatter() selecciona un objeto Formatter para que este handler lo use.

addFilter() y removeFilter() respectivamente configuran y desconfiguran los objetos del filtro en los handlers.

El código de la aplicación no debe instanciar directamente y usar instancias de Handler. En su lugar, la clase Handler es una clase base que define la interfaz que todos los handlers deben tener y establece algún comportamiento por defecto que las clases hijas pueden usar (o anular).

Formateadores

Los objetos de formato configuran el orden final, la estructura y el contenido del mensaje de registro. A diferencia de la clase base logging.Handler, el código de la aplicación puede instanciar clases de formateo, aunque probablemente podría subclasificar el formateo si su aplicación necesita un comportamiento especial. El constructor toma tres argumentos opcionales – una cadena de formato de mensaje, una cadena de formato de fecha y un indicador de estilo.

logging.Formatter.__init__(fmt=None, datefmt=None, style='%')

Si no hay una cadena de formato de mensaje, el valor predeterminado es utilizar el mensaje en bruto. Si no hay una cadena de formato de fecha, el formato de fecha por defecto es:

%Y-%m-%d %H:%M:%S

con los milisegundos clavados al final. El style es uno de %, ‘{‘ o ‘$’. Si uno de estos no se especifica, entonces se usará ‘%’.

Si el style es “%”, la cadena del formato de mensaje utiliza %(<dictionary key>)s estilo de sustitución de cadena; las posibles claves están documentadas en Atributos LogRecord. Si el estilo es “{”, se asume que la cadena del formato del mensaje es compatible con str.format() (usando argumentos de palabras clave), mientras que si el estilo es “$” entonces la cadena del formato del mensaje debe ajustarse a lo que se espera de string.Template.substitute().

Distinto en la versión 3.2: Añadió el parámetro style.

La siguiente cadena de formato de mensaje registrará la hora en un formato legible para los humanos, la gravedad del mensaje y el contenido del mensaje, en ese orden:

'%(asctime)s - %(levelname)s - %(message)s'

Los formateadores utilizan una función configurable por el usuario para convertir la hora de creación de un registro en una tupla. Por defecto, se utiliza time.localtime(); para cambiar esto para una instancia de formateador particular, establezca el atributo converter de la instancia a una función con la misma firma que time.localtime() o time.gmtime(). Para cambiarlo para todos los formateadores, por ejemplo si quieres que todas las horas de registro se muestren en GMT, establece el atributo converter en la clase Formatter (a time.gmtime para mostrar GMT).

Configuración del registro

Los programadores pueden configurar el registro en tres maneras:

Creando registradores, manejadores y formateadores explícitamente usando código Python que llama a los métodos de configuración listados arriba.

Creando un archivo de configuración de registro y leyéndolo usando la función fileConfig().

Creando un diccionario de información de configuración y pasándolo a la función dictConfig().

Para la documentación de referencia sobre las dos últimas opciones, vea Funciones de configuración. El siguiente ejemplo configura un logger muy simple, un manejador de consola, y un formateador simple usando código Python:

import logging

# create logger
logger = logging.getLogger('simple_example')
logger.setLevel(logging.DEBUG)

# create console handler and set level to debug
ch = logging.StreamHandler()
ch.setLevel(logging.DEBUG)

# create formatter
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')

# add formatter to ch
ch.setFormatter(formatter)

# add ch to logger
logger.addHandler(ch)

# 'application' code
logger.debug('debug message')
logger.info('info message')
logger.warning('warn message')
logger.error('error message')
logger.critical('critical message')

Ejecutar este módulo desde la línea de comandos produce la siguiente salida:

$ python simple_logging_module.py
2005-03-19 15:10:26,618 - simple_example - DEBUG - debug message
2005-03-19 15:10:26,620 - simple_example - INFO - info message
2005-03-19 15:10:26,695 - simple_example - WARNING - warn message
2005-03-19 15:10:26,697 - simple_example - ERROR - error message
2005-03-19 15:10:26,773 - simple_example - CRITICAL - critical message

El siguiente módulo de Python crea un registrador, manejador y formateador casi idéntico a los del ejemplo anterior, con la única diferencia de los nombres de los objetos:

import logging
import logging.config

logging.config.fileConfig('logging.conf')

# create logger
logger = logging.getLogger('simpleExample')

# 'application' code
logger.debug('debug message')
logger.info('info message')
logger.warning('warn message')
logger.error('error message')
logger.critical('critical message')

Aquí está el archivo logging.conf:

[loggers]
keys=root,simpleExample

[handlers]
keys=consoleHandler

[formatters]
keys=simpleFormatter

[logger_root]
level=DEBUG
handlers=consoleHandler

[logger_simpleExample]
level=DEBUG
handlers=consoleHandler
qualname=simpleExample
propagate=0

[handler_consoleHandler]
class=StreamHandler
level=DEBUG
formatter=simpleFormatter
args=(sys.stdout,)

[formatter_simpleFormatter]
format=%(asctime)s - %(name)s - %(levelname)s - %(message)s
datefmt=

La salida es casi idéntica a la del ejemplo basado en un archivo no configurado:

$ python simple_logging_config.py
2005-03-19 15:38:55,977 - simpleExample - DEBUG - debug message
2005-03-19 15:38:55,979 - simpleExample - INFO - info message
2005-03-19 15:38:56,054 - simpleExample - WARNING - warn message
2005-03-19 15:38:56,055 - simpleExample - ERROR - error message
2005-03-19 15:38:56,130 - simpleExample - CRITICAL - critical message

Se puede ver que el enfoque del archivo de configuración tiene algunas ventajas sobre el enfoque del código Python, principalmente la separación de la configuración y el código y la capacidad de los no codificadores de modificar fácilmente las propiedades de registro.

Advertencia

La función fileConfig`() toma un parámetro por defecto, disable_existing_loggers, que por defecto es True por razones de compatibilidad retroactiva. Esto puede ser o no lo que usted quiera, ya que causará que cualquier registrador no existente antes de la llamada fileConfig() sea desactivado a menos que ellos (o un ancestro) sean nombrados explícitamente en la configuración. Por favor, consulte la documentación de referencia para más información, y especifique False para este parámetro si lo desea.

El diccionario pasado a dictConfig() también puede especificar un valor booleano con la tecla disable_existing_loggers, que si no se especifica explícitamente en el diccionario también se interpreta por defecto como True. Esto lleva al comportamiento de deshabilitación de los registradores descrito anteriormente, que puede no ser lo que usted desea - en cuyo caso, proporcione a la clave explícitamente un valor de False.

Obsérvese que los nombres de clase a los que se hace referencia en los archivos de configuración deben ser relativos al módulo de registro, o bien valores absolutos que puedan resolverse mediante mecanismos de importación normales. Por lo tanto, puedes usar WatchedFileHandler (relativo al módulo de registro) o mypackage.mymodule.MyHandler (para una clase definida en el paquete mypackage y el módulo mymodule, donde mypackage está disponible en la ruta de importación de Python).

En Python 3.2, se ha introducido un nuevo medio para configurar el registro, utilizando diccionarios para guardar la información de configuración. Esto proporciona un superconjunto de la funcionalidad del enfoque basado en archivos de configuración descrito anteriormente, y es el método de configuración recomendado para nuevas aplicaciones y despliegues. Dado que se utiliza un diccionario de Python para guardar información de configuración, y dado que se puede rellenar ese diccionario utilizando diferentes medios, se dispone de más opciones de configuración. Por ejemplo, puede utilizar un archivo de configuración en formato JSON o, si tiene acceso a la funcionalidad de procesamiento YAML, un archivo en formato YAML, para rellenar el diccionario de configuración. O, por supuesto, puedes construir el diccionario en código Python, recibirlo en forma encurtida sobre un zócalo, o usar cualquier enfoque que tenga sentido para tu aplicación.

Aquí hay un ejemplo de la misma configuración que arriba, en formato YAML para el nuevo enfoque basado en el diccionario:

version: 1
formatters:
  simple:
    format: '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
handlers:
  console:
    class: logging.StreamHandler
    level: DEBUG
    formatter: simple
    stream: ext://sys.stdout
loggers:
  simpleExample:
    level: DEBUG
    handlers: [console]
    propagate: no
root:
  level: DEBUG
  handlers: [console]

Para más información sobre el registro usando un diccionario, ver Funciones de configuración.

¿Qué pasa si no se proporciona ninguna configuración

Si no se proporciona una configuración de registro, es posible que se produzca una situación en la que sea necesario dar salida a un suceso de registro, pero no se puede encontrar a ningún gestor para dar salida al suceso. El comportamiento del paquete de registro en estas circunstancias depende de la versión de Python.

Para las versiones de Python anteriores a la 3.2, el comportamiento es el siguiente:

Si logging.raiseExceptions es Falso (modo de producción), el evento es abandonado silenciosamente.

Si logging.raiseExceptions es True (modo de desarrollo), se imprime una vez un mensaje “No handlers could be found for logger X.Y.Z” (“No se pudo encontrar ningún manejador (handler) para el logger X.Y.Z”).

En Python 3.2 y posteriores, el comportamiento es el siguiente:

El evento es emitido usando un ‘handler de último recurso’, almacenado en logging.lastResort. Este manejador interno no está asociado con ningún logger, y actúa como un StreamHandler` que escribe el mensaje de descripción del evento con el valor actual de sys.stderr (respetando así cualquier redireccionamiento que pueda estar en vigor). No se hace ningún tipo de formateo en el mensaje, sólo se imprime el mensaje de descripción del evento. El nivel del manejador se establece en WARNING, por lo que todos los eventos de esta y mayores severidades serán emitidos.

Para obtener el comportamiento anterior a la 3.2, logging.lastResort se puede configurar como None.

Configurando Logging para una biblioteca

Cuando se desarrolla una biblioteca que utiliza el registro, se debe tener cuidado de documentar la forma en que la biblioteca utiliza el registro, por ejemplo, los nombres de los registradores utilizados. También hay que tener en cuenta su configuración de registro. Si la aplicación que lo utiliza no usa el registro, y el código de la biblioteca hace llamadas de registro, entonces (como se describe en la sección anterior) los eventos de gravedad WARNING y mayores se imprimirán en sys.stderr. Esto se considera el mejor comportamiento por defecto.

Si por alguna razón usted no quiere que estos mensajes se impriman en ausencia de cualquier configuración de registro, puede adjuntar un manejador de no hacer nada al registrador de nivel superior de su biblioteca. Esto evita que el mensaje se imprima, ya que siempre se encontrará un manejador para los eventos de la biblioteca: simplemente no produce ninguna salida. Si el usuario de la biblioteca configura el registro para el uso de la aplicación, presumiblemente esa configuración añadirá algunos manejadores, y si los niveles están configurados adecuadamente, entonces las llamadas de registro realizadas en el código de la biblioteca enviarán una salida a esos manejadores, como es normal.

Un manejador de no hacer nada está incluido en el paquete de registro: NullHandler (desde Python 3.1). Una instancia de este manejador podría ser añadida al logger de nivel superior del espacio de nombres de registro usado por la biblioteca (si quieres evitar que los eventos de registro de tu biblioteca se envíen a sys.stderr en ausencia de la configuración de registro). Si todo el registro de una biblioteca foo se hace usando registradores con nombres que coincidan con “foo.x”, “foo.x.y”, etc. entonces el código:

import logging
logging.getLogger('foo').addHandler(logging.NullHandler())

debería tener el efecto deseado. Si una organización produce varias bibliotecas, el nombre del registrador especificado puede ser ‘orgname.foo’ en lugar de sólo ‘foo’.

Nota

Se recomienda encarecidamente que no añada ningún otro manejador que no sea NullHandler a los loggers de su biblioteca. Esto se debe a que la configuración de los handlers es prerrogativa del desarrollador de aplicaciones que utiliza su biblioteca. El desarrollador de la aplicación conoce su público objetivo y qué manejadores son los más apropiados para su aplicación: si añades manejadores ‘bajo el capó’, podrías interferir en su capacidad de realizar pruebas unitarias y entregar registros que se ajusten a sus necesidades.

Niveles de registro

Los valores numéricos de los niveles de registro se indican en el siguiente cuadro. Éstos son de interés principalmente si se desea definir los propios niveles y se necesita que tengan valores específicos en relación con los niveles predefinidos. Si se define un nivel con el mismo valor numérico, éste sobrescribe el valor predefinido; el nombre predefinido se pierde.

Nivel

Valor numérico

CRITICAL

50

ERROR

40

WARNING

30

INFO

20

DEBUG

10

NOTSET

0

Los niveles también pueden asociarse con los registradores, siendo establecidos por el desarrollador o mediante la carga de una configuración de registro guardada. Cuando se llama a un método de registro en un registrador, éste compara su propio nivel con el nivel asociado a la llamada del método. Si el nivel del registrador es superior al de la llamada al método, no se genera ningún mensaje de registro. Este es el mecanismo básico que controla la verbosidad de la salida del registro.

Los mensajes de registro se codifican como instancias de la clase logging.LogRecord. Cuando un logger decide registrar realmente un evento, se crea una instancia LogRecord a partir del mensaje de registro.

Los mensajes de registro están sujetos a un mecanismo de envío mediante el uso de handlers, que son instancias de subclases de la clase Handler. Los gestores son responsables de asegurar que un mensaje registrado (en forma de LogRecord) termine en una ubicación particular (o conjunto de ubicaciones) que sea útil para el público al que va dirigido ese mensaje (como usuarios finales, personal de asistencia técnica, administradores de sistemas, desarrolladores). Los manejadores pasan instancias LogRecord destinadas a destinos particulares. Cada logger puede tener cero, uno o más manejadores asociados a él (a través del método addHandler() de Logger). Además de los handlers directamente asociados a un logger, todos los manejadores (handlers) asociados a todos los ancestros del logger son llamados a enviar el mensaje (a menos que el flag propagate de un logger se establezca en un valor falso, en cuyo caso el paso a los handlers ancestrales se detiene).

Al igual que para los logger, los gestores pueden tener niveles asociados a ellos. El nivel de un gestor actúa como un filtro de la misma manera que el nivel de un logger. Si un manejador (handler) decide realmente enviar un evento, el método emit() se utiliza para enviar el mensaje a su destino. La mayoría de las subclases definidas por el usuario de Handler necesitarán anular este emit().

Niveles personalizados

Definir sus propios niveles es posible, pero no debería ser necesario, ya que los niveles existentes se han elegido sobre la base de la experiencia práctica. Sin embargo, si usted está convencido de que necesita niveles personalizados, debe tener mucho cuidado al hacer esto, y es posiblemente una muy mala idea definir niveles personalizados si está desarrollando una biblioteca. Esto se debe a que si los autores de múltiples bibliotecas definen sus propios niveles personalizados, existe la posibilidad de que el resultado del registro de tales bibliotecas múltiples utilizadas conjuntamente sea difícil de controlar y/o interpretar para el desarrollador usuario, porque un valor numérico dado podría significar cosas diferentes para diferentes bibliotecas.

Gestores útiles

Además de la base Handler class, se proporcionan muchas subclases útiles:

StreamHandler instancias envían mensajes a los streams (objetos como de tipo archivo).

FileHandler instancias enviar mensajes a los archivos del disco.

BaseRotatingHandler es la clase base para los manejadores (handlers) que rotan los archivos de registro en un punto determinado. No está pensada para ser instanciada directamente. En su lugar, utilice RotatingFileHandler o TimedRotatingFileHandler.

Las instancias de RotatingFileHandler envían mensajes a los archivos de disco, con soporte para el tamaño máximo de los archivos de registro y la rotación de los mismos.

Las instancias de TimedRotatingFileHandler envían mensajes a los archivos de disco, rotando el archivo de registro a ciertos intervalos de tiempo.

Las instancias de SocketHandler envían mensajes a los sockets TCP/IP. Desde la versión 3.4, los sockets de dominio Unix también están soportados.

Instancias de DatagramHandler envían mensajes a los sockets UDP. Desde la versión 3.4, los sockets de dominio Unix también están soportados.

Las instancias de SMTPHandler envían mensajes a una dirección de correo electrónico designada.

Las instancias de SysLogHandler envían mensajes a un demonio del syslog de Unix, posiblemente en una máquina remota.

Las instancias de NTEventLogHandler envían mensajes a un registro de eventos de Windows NT/2000/XP.

Las instancias de MemoryHandler envían mensajes a un buffer en la memoria, que es limpiado cuando se cumplen ciertos criterios.

Las instancias de HTTPHandler envían mensajes a un servidor HTTP usando la semántica de «GET» o «POST».

Las instancias de WatchedFileHandler ven el archivo al que están accediendo. Si el archivo cambia, se cierra y se vuelve a abrir usando el nombre del archivo. Este manejador sólo es útil en sistemas tipo Unix; Windows no soporta el mecanismo subyacente utilizado.

Las instancias de QueueHandler envían mensajes a una cola, como los implementados en los módulos queue or multiprocessing.

NullHandler instancias no hacen nada con los mensajes de error. Son utilizadas por los desarrolladores de bibliotecas que quieren utilizar el registro, pero quieren evitar el mensaje «No se pudo encontrar ningún controlador para el registrador XXX», que puede mostrarse si el usuario de la biblioteca no ha configurado el registro. Vea Configurando Logging para una biblioteca para más información.

Nuevo en la versión 3.1: La clase NullHandler.

Nuevo en la versión 3.2: La QueueHandler (La clase de gestores de Cola).

Las clases NullHandler, StreamHandler y FileHandler están definidas en el paquete de registro del núcleo. Los otros manejadores se definen en un sub-módulo, logging.handlers. (También hay otro submódulo, logging.config, para la funcionalidad de configuración)

Los mensajes registrados se formatean para su presentación a través de instancias de la clase Formatter. Se inicializan con una cadena de formato adecuada para su uso con el operador % y un diccionario.

Para dar formato a varios mensajes en un lote, se pueden utilizar instancias de BufferingFormatter. Además de la cadena de formato (que se aplica a cada mensaje del lote), hay una provisión para cadenas de formato de cabecera y de tráiler.

Cuando el filtrado basado en el nivel de logger o el nivel de manejador (handler) no es suficiente, se pueden añadir instancias de Filter tanto a Logger como a Handler instancias (a través de su método addFilter()). Antes de decidir procesar un mensaje más adelante, tanto los loggers como los manejadores (handlers) consultan todos sus filtros para obtener permiso. Si algún filtro retorna un valor falso, el mensaje no se procesa más.

La funcionalidad básica Filtro permite filtrar por un nombre de registro específico. Si se utiliza esta función, los mensajes enviados al registrador nombrado y a sus hijos se permiten a través del filtro, y todos los demás se eliminan.

Excepciones lanzadas durante logging

El paquete de tala está diseñado para tragarse las excepciones que se producen durante la tala en la producción. Esto es así para que los errores que ocurren durante el manejo de los eventos de registro - como la mala configuración del registro, errores de red u otros errores similares - no causen que la aplicación que utiliza el registro termine prematuramente.

Las excepciones de SystemExit (Salida del sistema) y KeyboardInterrupt (Interrupción del teclado) nunca se tragan. Otras excepciones que ocurren durante el método emit() de una subclase Handler se pasan a su método handleError() .

La implementación por defecto de handleError() en Handler comprueba si una variable de nivel de módulo, raiseExceptions, está establecida. Si se establece, se imprime una traza en sys.stderr. Si no se establece, se traga la excepción.

Nota

El valor por defecto de raiseExceptions (lanzar excepciones) es True. Esto se debe a que durante el desarrollo, normalmente quieres ser notificado de cualquier excepción que ocurra. Se aconseja que establezca raiseExceptions a False para el uso en producción.

Usando objetos arbitrarios como mensajes

En las secciones y ejemplos anteriores, se ha supuesto que el mensaje pasado al registrar el suceso es una cadena. Sin embargo, esta no es la única posibilidad. Se puede pasar un objeto arbitrario como mensaje, y su método __str__() será llamado cuando el sistema de registro necesite convertirlo en una representación de cadena. De hecho, si quieres, puedes evitar computar una representación de cadena por completo - por ejemplo, el método SocketHandler emite un evento al pickling y enviarlo por el cable.

Optimización

El formato de los argumentos del mensaje se aplaza hasta que no se pueda evitar. Sin embargo, el cálculo de los argumentos pasados al método de registro también puede ser costoso, y puede que quieras evitar hacerlo si el registrador simplemente tirará tu evento. Para decidir qué hacer, puedes llamar al método isEnabledFor() que toma un argumento de nivel y retorna true si el evento sería creado por el Logger para ese nivel de llamada. Puedes escribir código como este:

if logger.isEnabledFor(logging.DEBUG):
    logger.debug('Message with %s, %s', expensive_func1(),
                                        expensive_func2())

de modo que si el umbral del registrador se establece por encima de DEBUG, las llamadas a expensive_func1() y expensive_func2() nunca se hacen.

Nota

En algunos casos, isEnabledFor() puede ser en sí mismo más caro de lo que te gustaría (por ejemplo, para los loggers profundamente anidados donde un nivel explícito sólo se establece en lo alto de la jerarquía de loggers). En estos casos (o si quieres evitar llamar a un método en bucles estrechos), puedes guardar en caché el resultado de una llamada a isEnabledFor() en una variable local o de instancia, y usarla en lugar de llamar al método cada vez. Tal valor en caché sólo necesitaría ser recalculado cuando la configuración de registro cambie dinámicamente mientras la aplicación se está ejecutando (lo cual no es tan común).

Hay otras optimizaciones que pueden hacerse para aplicaciones específicas que necesitan un control más preciso sobre la información de registro que se recoge. Aquí hay una lista de cosas que puede hacer para evitar el procesamiento durante el registro que no necesita:

Lo que no quieres colectar

Cómo evitar coleccionarlo

Información sobre dónde se hicieron las llamadas.

Establezca logging._srcfile en None. Esto evita llamar a sys._getframe(), que puede ayudar a acelerar su código en entornos como PyPy (que no puede acelerar el código que usa sys._getframe()).

Información sobre código con hilos.

Ponga logging.logThreads en 0.

Procesar la información.

Ponga logging.logProcesses en 0.

Observe también que el módulo de registro del núcleo sólo incluye los gestores básicos. Si no importas logging.handlers y logging.config, no ocuparán ninguna memoria.

Ver también

Módulo logging

Referencia API para el módulo de registro.

Módulo logging.config

API de configuración para el módulo de registro.

Módulo logging.handlers

Gestores útiles incluidos en el módulo de registro.

Un libro de recetas

Libro de recetas de Logging

Autor

Vinay Sajip <vinay_sajip at red-dove dot com>

Esta página contiene un número de recetas sobre logging, que han sido útiles en el pasado.

Usar logging en múltiples módulos

Múltiples llamadas a logging.getLogger('someLogger') devuelven una referencia al mismo objeto logger. Esto es cierto no solo dentro del mismo módulo, sino también en todos los módulos siempre que estén ejecutándose en el mismo proceso del intérprete de Python. Es válido para las referencias al mismo objeto. Además, el código de la aplicación puede definir y configurar un logger primario en un módulo y crear (pero no configurar) un logger secundario en un módulo separado, y todas las llamadas al secundario pasarán al principal. A continuación un módulo principal:

import logging
import auxiliary_module

# create logger with 'spam_application'
logger = logging.getLogger('spam_application')
logger.setLevel(logging.DEBUG)
# create file handler which logs even debug messages
fh = logging.FileHandler('spam.log')
fh.setLevel(logging.DEBUG)
# create console handler with a higher log level
ch = logging.StreamHandler()
ch.setLevel(logging.ERROR)
# create formatter and add it to the handlers
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
fh.setFormatter(formatter)
ch.setFormatter(formatter)
# add the handlers to the logger
logger.addHandler(fh)
logger.addHandler(ch)

logger.info('creating an instance of auxiliary_module.Auxiliary')
a = auxiliary_module.Auxiliary()
logger.info('created an instance of auxiliary_module.Auxiliary')
logger.info('calling auxiliary_module.Auxiliary.do_something')
a.do_something()
logger.info('finished auxiliary_module.Auxiliary.do_something')
logger.info('calling auxiliary_module.some_function()')
auxiliary_module.some_function()
logger.info('done with auxiliary_module.some_function()')

Y aquí un módulo auxiliar:

import logging

# create logger
module_logger = logging.getLogger('spam_application.auxiliary')

class Auxiliary:
    def __init__(self):
        self.logger = logging.getLogger('spam_application.auxiliary.Auxiliary')
        self.logger.info('creating an instance of Auxiliary')

    def do_something(self):
        self.logger.info('doing something')
        a = 1 + 1
        self.logger.info('done doing something')

def some_function():
    module_logger.info('received a call to "some_function"')

El resultado se ve así:

2005-03-23 23:47:11,663 - spam_application - INFO -
   creating an instance of auxiliary_module.Auxiliary
2005-03-23 23:47:11,665 - spam_application.auxiliary.Auxiliary - INFO -
   creating an instance of Auxiliary
2005-03-23 23:47:11,665 - spam_application - INFO -
   created an instance of auxiliary_module.Auxiliary
2005-03-23 23:47:11,668 - spam_application - INFO -
   calling auxiliary_module.Auxiliary.do_something
2005-03-23 23:47:11,668 - spam_application.auxiliary.Auxiliary - INFO -
   doing something
2005-03-23 23:47:11,669 - spam_application.auxiliary.Auxiliary - INFO -
   done doing something
2005-03-23 23:47:11,670 - spam_application - INFO -
   finished auxiliary_module.Auxiliary.do_something
2005-03-23 23:47:11,671 - spam_application - INFO -
   calling auxiliary_module.some_function()
2005-03-23 23:47:11,672 - spam_application.auxiliary - INFO -
   received a call to 'some_function'
2005-03-23 23:47:11,673 - spam_application - INFO -
   done with auxiliary_module.some_function()

Logging desde múltiples hilos

Realizar logging desde múltiples hilos (threads) no requiere ningún esfuerzo especial. El siguiente ejemplo muestra el logging desde el hilo principal (inicial) y otro hilo:

import logging
import threading
import time

def worker(arg):
    while not arg['stop']:
        logging.debug('Hi from myfunc')
        time.sleep(0.5)

def main():
    logging.basicConfig(level=logging.DEBUG, format='%(relativeCreated)6d %(threadName)s %(message)s')
    info = {'stop': False}
    thread = threading.Thread(target=worker, args=(info,))
    thread.start()
    while True:
        try:
            logging.debug('Hello from main')
            time.sleep(0.75)
        except KeyboardInterrupt:
            info['stop'] = True
            break
    thread.join()

if __name__ == '__main__':
    main()

Cuando se ejecuta, el script debe imprimir algo como lo siguiente:

   0 Thread-1 Hi from myfunc
   3 MainThread Hello from main
 505 Thread-1 Hi from myfunc
 755 MainThread Hello from main
1007 Thread-1 Hi from myfunc
1507 MainThread Hello from main
1508 Thread-1 Hi from myfunc
2010 Thread-1 Hi from myfunc
2258 MainThread Hello from main
2512 Thread-1 Hi from myfunc
3009 MainThread Hello from main
3013 Thread-1 Hi from myfunc
3515 Thread-1 Hi from myfunc
3761 MainThread Hello from main
4017 Thread-1 Hi from myfunc
4513 MainThread Hello from main
4518 Thread-1 Hi from myfunc

Esto muestra la salida de logging intercalada como cabría esperar. Por supuesto, este enfoque funciona para más hilos de lo que se muestran aquí.

Múltiples gestores y formateadores

Los loggers son simples objetos Python. El método addHandler() no tiene una cuota mínima o máxima para la cantidad de gestores (handlers) que puede agregar. A veces será beneficioso para una aplicación registrar todos los mensajes de todas las prioridades en un archivo de texto mientras se registran simultáneamente los errores o más en la consola. Para configurar esto, simplemente configure los gestores apropiados. Las llamadas de logging en el código de la aplicación permanecerán sin cambios. Aquí hay una ligera modificación al ejemplo de configuración simple anterior basado en módulo:

import logging

logger = logging.getLogger('simple_example')
logger.setLevel(logging.DEBUG)
# create file handler which logs even debug messages
fh = logging.FileHandler('spam.log')
fh.setLevel(logging.DEBUG)
# create console handler with a higher log level
ch = logging.StreamHandler()
ch.setLevel(logging.ERROR)
# create formatter and add it to the handlers
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
ch.setFormatter(formatter)
fh.setFormatter(formatter)
# add the handlers to logger
logger.addHandler(ch)
logger.addHandler(fh)

# 'application' code
logger.debug('debug message')
logger.info('info message')
logger.warning('warn message')
logger.error('error message')
logger.critical('critical message')

Tenga en cuenta que el código de la “aplicación” no se preocupa por los gestores múltiples. Todo lo que cambió fue la adición y configuración de un nuevo gestor llamado fh.

La capacidad de crear nuevos gestores con filtros de mayor o menor prioridad puede ser muy útil al escribir y probar una aplicación. En lugar de usar muchas declaraciones print para la depuración, use logger.debug: a diferencia de las declaraciones de impresión, que tendrá que eliminar o comentar más tarde, las declaraciones de logger.debug pueden permanecer intactas en el código fuente y permanecen inactivas hasta que las necesite nuevamente. En ese momento, el único cambio que debe realizar es modificar el nivel de prioridad del logger y/o gestor para depurar.

Logging en múltiples destinos

Supongamos que desea que la consola y un archivo tengan diferentes formatos de mensaje y salida de log para diferentes situaciones. Por ejemplo, desea registrar mensajes con un nivel DEBUG y superiores en un archivo y enviar mensajes con nivel INFO y superior a la consola. Además, suponga que desea grabar una marca de tiempo en el archivo y no imprimirlo en la consola. Puede lograr este comportamiento haciendo lo siguiente:

import logging

# set up logging to file - see previous section for more details
logging.basicConfig(level=logging.DEBUG,
                    format='%(asctime)s %(name)-12s %(levelname)-8s %(message)s',
                    datefmt='%m-%d %H:%M',
                    filename='/temp/myapp.log',
                    filemode='w')
# define a Handler which writes INFO messages or higher to the sys.stderr
console = logging.StreamHandler()
console.setLevel(logging.INFO)
# set a format which is simpler for console use
formatter = logging.Formatter('%(name)-12s: %(levelname)-8s %(message)s')
# tell the handler to use this format
console.setFormatter(formatter)
# add the handler to the root logger
logging.getLogger('').addHandler(console)

# Now, we can log to the root logger, or any other logger. First the root...
logging.info('Jackdaws love my big sphinx of quartz.')

# Now, define a couple of other loggers which might represent areas in your
# application:

logger1 = logging.getLogger('myapp.area1')
logger2 = logging.getLogger('myapp.area2')

logger1.debug('Quick zephyrs blow, vexing daft Jim.')
logger1.info('How quickly daft jumping zebras vex.')
logger2.warning('Jail zesty vixen who grabbed pay from quack.')
logger2.error('The five boxing wizards jump quickly.')

Cuando ejecute esto, en la consola verá

root        : INFO     Jackdaws love my big sphinx of quartz.
myapp.area1 : INFO     How quickly daft jumping zebras vex.
myapp.area2 : WARNING  Jail zesty vixen who grabbed pay from quack.
myapp.area2 : ERROR    The five boxing wizards jump quickly.

y en el archivo verá algo como

10-22 22:19 root         INFO     Jackdaws love my big sphinx of quartz.
10-22 22:19 myapp.area1  DEBUG    Quick zephyrs blow, vexing daft Jim.
10-22 22:19 myapp.area1  INFO     How quickly daft jumping zebras vex.
10-22 22:19 myapp.area2  WARNING  Jail zesty vixen who grabbed pay from quack.
10-22 22:19 myapp.area2  ERROR    The five boxing wizards jump quickly.

Como se puede ver, el mensaje DEBUG sólo se muestra en el archivo. Los otros mensajes se envían a los dos destinos.

Este ejemplo usa gestores de consola y archivos, pero puede usar cualquier número y combinación de los gestores que elija.

Ejemplo de servidor de configuración

Aquí hay un ejemplo de un módulo que usa el servidor de configuración logging:

import logging
import logging.config
import time
import os

# read initial config file
logging.config.fileConfig('logging.conf')

# create and start listener on port 9999
t = logging.config.listen(9999)
t.start()

logger = logging.getLogger('simpleExample')

try:
    # loop through logging calls to see the difference
    # new configurations make, until Ctrl+C is pressed
    while True:
        logger.debug('debug message')
        logger.info('info message')
        logger.warning('warn message')
        logger.error('error message')
        logger.critical('critical message')
        time.sleep(5)
except KeyboardInterrupt:
    # cleanup
    logging.config.stopListening()
    t.join()

Y aquí hay un script que toma un nombre de archivo y envía ese archivo al servidor, precedido adecuadamente con la longitud codificada en binario, como la nueva configuración de logging:

#!/usr/bin/env python
import socket, sys, struct

with open(sys.argv[1], 'rb') as f:
    data_to_send = f.read()

HOST = 'localhost'
PORT = 9999
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
print('connecting...')
s.connect((HOST, PORT))
print('sending config...')
s.send(struct.pack('>L', len(data_to_send)))
s.send(data_to_send)
s.close()
print('complete')

Tratar con gestores que bloquean

A veces tiene que hacer que sus gestores de logging hagan su trabajo sin bloquear el hilo desde el que está iniciando sesión. Esto es común en las aplicaciones web, aunque, por supuesto, también ocurre en otros escenarios.

Un responsable habitual que ejemplifica un comportamiento lento es la SMTPHandler: el envío de correos electrónicos puede llevar mucho tiempo, por varias razones fuera del control del desarrollador (por ejemplo, una infraestructura de red o correo de bajo rendimiento). Pero casi cualquier controlador basado en red puede bloquear: incluso una operación SocketHandler puede estar haciendo a bajo nivel una consulta DNS que es demasiado lenta (y esta consulta puede estar en el código de la biblioteca de socket, debajo de la capa de Python, y fuera de su control).

Una solución es utilizar un enfoque de dos partes. Para la primera parte, adjunte solo una QueueHandler a los loggers que se acceden desde subprocesos críticos de rendimiento. Simplemente escriben en su cola, que puede dimensionarse a una capacidad lo suficientemente grande o inicializarse sin límite superior a su tamaño. La escritura en la cola generalmente se aceptará rápidamente, aunque es probable que deba atrapar la excepción queue.Full como precaución en su código. Si usted es un desarrollador de bibliotecas que tiene subprocesos críticos de rendimiento en su código, asegúrese de documentar esto (junto con una sugerencia de adjuntar solo QueueHandlers a sus loggers) para el beneficio de otros desarrolladores que usarán su código.

La segunda parte de la solución es QueueListener, que fue designado como la contraparte de QueueHandler. Un QueueListener es muy simple: ha pasado una cola y algunos gestores, y activa un hilo interno que escucha su cola para LogRecords enviados desde QueueHandlers (o cualquier otra fuente de LogRecords, para el caso). Los LogRecords se eliminan de la cola y se pasan a los gestores para su procesamiento.

La ventaja de tener una clase separada QueueListener es que puede usar la misma instancia para dar servicio a múltiples QueueHandlers. Esto es más amigable con los recursos que, por ejemplo, tener versiones enhebradas de las clases de gestores existentes, que consumirían un hilo por gestor sin ningún beneficio particular.

Un ejemplo del uso de estas dos clases a continuación (se omiten imports):

que = queue.Queue(-1)  # no limit on size
queue_handler = QueueHandler(que)
handler = logging.StreamHandler()
listener = QueueListener(que, handler)
root = logging.getLogger()
root.addHandler(queue_handler)
formatter = logging.Formatter('%(threadName)s: %(message)s')
handler.setFormatter(formatter)
listener.start()
# The log output will display the thread which generated
# the event (the main thread) rather than the internal
# thread which monitors the internal queue. This is what
# you want to happen.
root.warning('Look out!')
listener.stop()

que, cuando se ejecuta, producirá:

MainThread: Look out!

Distinto en la versión 3.5: Antes de Python 3.5, QueueListener siempre pasaba cada mensaje recibido de la cola a cada controlador con el que se inicializaba. (Esto se debió a que se asumió que el filtrado de nivel se realizó en el otro lado, donde se llena la cola). A partir de 3.5, este comportamiento se puede cambiar pasando un argumento de palabra clave respect_handler_level=True al constructor del oyente . Cuando se hace esto, el oyente compara el nivel de cada mensaje con el nivel del controlador y solo pasa un mensaje a un controlador si es apropiado hacerlo.

Enviar y recibir eventos logging a través de una red

Supongamos que desea enviar eventos de registro a través de una red y manejarlos en el extremo receptor. Una forma sencilla de hacer esto es adjuntar una instancia de SocketHandler al registrador raíz en el extremo de envío:

import logging, logging.handlers

rootLogger = logging.getLogger('')
rootLogger.setLevel(logging.DEBUG)
socketHandler = logging.handlers.SocketHandler('localhost',
                    logging.handlers.DEFAULT_TCP_LOGGING_PORT)
# don't bother with a formatter, since a socket handler sends the event as
# an unformatted pickle
rootLogger.addHandler(socketHandler)

# Now, we can log to the root logger, or any other logger. First the root...
logging.info('Jackdaws love my big sphinx of quartz.')

# Now, define a couple of other loggers which might represent areas in your
# application:

logger1 = logging.getLogger('myapp.area1')
logger2 = logging.getLogger('myapp.area2')

logger1.debug('Quick zephyrs blow, vexing daft Jim.')
logger1.info('How quickly daft jumping zebras vex.')
logger2.warning('Jail zesty vixen who grabbed pay from quack.')
logger2.error('The five boxing wizards jump quickly.')

En el extremo receptor, puede configurar un receptor usando el módulo socketserver. Aquí hay un ejemplo básico de trabajo:

import pickle
import logging
import logging.handlers
import socketserver
import struct

class LogRecordStreamHandler(socketserver.StreamRequestHandler):
    """Handler for a streaming logging request.

    This basically logs the record using whatever logging policy is
    configured locally.
    """

    def handle(self):
        """
        Handle multiple requests - each expected to be a 4-byte length,
        followed by the LogRecord in pickle format. Logs the record
        according to whatever policy is configured locally.
        """
        while True:
            chunk = self.connection.recv(4)
            if len(chunk) < 4:
                break
            slen = struct.unpack('>L', chunk)[0]
            chunk = self.connection.recv(slen)
            while len(chunk) < slen:
                chunk = chunk + self.connection.recv(slen - len(chunk))
            obj = self.unPickle(chunk)
            record = logging.makeLogRecord(obj)
            self.handleLogRecord(record)

    def unPickle(self, data):
        return pickle.loads(data)

    def handleLogRecord(self, record):
        # if a name is specified, we use the named logger rather than the one
        # implied by the record.
        if self.server.logname is not None:
            name = self.server.logname
        else:
            name = record.name
        logger = logging.getLogger(name)
        # N.B. EVERY record gets logged. This is because Logger.handle
        # is normally called AFTER logger-level filtering. If you want
        # to do filtering, do it at the client end to save wasting
        # cycles and network bandwidth!
        logger.handle(record)

class LogRecordSocketReceiver(socketserver.ThreadingTCPServer):
    """
    Simple TCP socket-based logging receiver suitable for testing.
    """

    allow_reuse_address = True

    def __init__(self, host='localhost',
                 port=logging.handlers.DEFAULT_TCP_LOGGING_PORT,
                 handler=LogRecordStreamHandler):
        socketserver.ThreadingTCPServer.__init__(self, (host, port), handler)
        self.abort = 0
        self.timeout = 1
        self.logname = None

    def serve_until_stopped(self):
        import select
        abort = 0
        while not abort:
            rd, wr, ex = select.select([self.socket.fileno()],
                                       [], [],
                                       self.timeout)
            if rd:
                self.handle_request()
            abort = self.abort

def main():
    logging.basicConfig(
        format='%(relativeCreated)5d %(name)-15s %(levelname)-8s %(message)s')
    tcpserver = LogRecordSocketReceiver()
    print('About to start TCP server...')
    tcpserver.serve_until_stopped()

if __name__ == '__main__':
    main()

Primero ejecuta el servidor, y luego el cliente. Del lado del cliente, nada se imprime en la consola; del lado del servidor, se debería ver algo como esto:

About to start TCP server...
   59 root            INFO     Jackdaws love my big sphinx of quartz.
   59 myapp.area1     DEBUG    Quick zephyrs blow, vexing daft Jim.
   69 myapp.area1     INFO     How quickly daft jumping zebras vex.
   69 myapp.area2     WARNING  Jail zesty vixen who grabbed pay from quack.
   69 myapp.area2     ERROR    The five boxing wizards jump quickly.

Tenga en cuenta que existen algunos problemas de seguridad con pickle en algunos escenarios. Si estos le afectan, puede usar un esquema de serialización alternativo anulando el método makePickle() e implementando su alternativa allí, así como adaptar el script anterior para usar su serialización alternativa.

Running a logging socket listener in production

To run a logging listener in production, you may need to use a process-management tool such as Supervisor [http://supervisord.org/]. Here [https://gist.github.com/vsajip/4b227eeec43817465ca835ca66f75e2b] is a Gist which provides the bare-bones files to run the above functionality using Supervisor: you will need to change the /path/to/ parts in the Gist to reflect the actual paths you want to use.

Agregar información contextual a su salida de logging

A veces, desea que la salida de logging contenga información contextual además de los parámetros pasados a la llamada del logging. Por ejemplo, en una aplicación en red, puede ser conveniente registrar información específica del cliente en el logging (por ejemplo, el nombre de usuario del cliente remoto o la dirección IP). Aunque puede usar el parámetro extra para lograr esto, no siempre es conveniente pasar la información de esta manera. Si bien puede resultar tentador crear instancias Logger por conexión, esta no es una buena idea porque estas instancias no se liberan de memoria vía el recolector de basura (garbage collector). Si bien esto no es un problema en la práctica, cuando el número de instancias de Logger depende del nivel de granularidad que desea usar para hacer el logging de una aplicación, podría ser difícil de administrar si el número de instancias Logger se vuelven efectivamente ilimitadas.

Uso de LoggerAdapters para impartir información contextual

Una manera fácil de pasar información contextual para que se genere junto con la información de eventos logging es usar la clase LoggerAdapter. Esta clase está diseñada para parecerse a Logger, de modo que pueda llamar debug(), info(), warning(), error(), excepción(), critical() y log(). Estos métodos tienen las mismas signaturas que sus contrapartes en Logger, por lo que puede usar los dos tipos de instancias indistintamente.

Cuando creas una instancia de LoggerAdapter, le pasas una instancia de Logger y un objeto similar a un dict que contiene tu información contextual. Cuando llamas a uno de los métodos de registro en una instancia de LoggerAdapter, delega la llamada a la instancia subyacente de Logger pasada a su constructor, y se arregla para pasar la información contextual en la llamada delegada . Aquí hay un fragmento del código de LoggerAdapter:

def debug(self, msg, /, *args, **kwargs):
    """
    Delegate a debug call to the underlying logger, after adding
    contextual information from this adapter instance.
    """
    msg, kwargs = self.process(msg, kwargs)
    self.logger.debug(msg, *args, **kwargs)

El método process() de LoggerAdapter es donde la información contextual se agrega a la salida del logging. Se pasa el mensaje y los argumentos de palabra clave de la llamada logging, y retorna versiones (potencialmente) modificadas de estos para usar en la llamada al logging subyacente. La implementación predeterminada de este método deja el mensaje solo, pero inserta una clave “extra” en el argumento de palabra clave cuyo valor es el objeto tipo dict pasado al constructor. Por supuesto, si ha pasado un argumento de palabra clave “extra” en la llamada al adaptador, se sobrescribirá silenciosamente.

La ventaja de usar “extra” es que los valores en el objeto dict se combinan en la instancia LogRecord __dict__, lo que le permite usar cadenas personalizadas con sus instancias Formatter que conocen las claves del objeto dict. Si necesita un método diferente, por ejemplo, si desea anteponer o agregar la información contextual a la cadena del mensaje, solo necesita la subclase LoggerAdapter y anular process() para hacer lo que necesita. Aquí hay un ejemplo simple:

class CustomAdapter(logging.LoggerAdapter):
    """
    This example adapter expects the passed in dict-like object to have a
    'connid' key, whose value in brackets is prepended to the log message.
    """
    def process(self, msg, kwargs):
        return '[%s] %s' % (self.extra['connid'], msg), kwargs

que puede usar así:

logger = logging.getLogger(__name__)
adapter = CustomAdapter(logger, {'connid': some_conn_id})

Luego, cualquier evento que registre en el adaptador tendrá el valor de some_conn_id antepuesto a los mensajes de logging.

Usar objetos distintos a los diccionarios para transmitir información contextual

No es necesario pasar un diccionario real a la LoggerAdapter - puedes pasar una instancia de una clase que implemente __getitem__ y __iter__ de modo que parezca un diccionario para el logging. Esto es útil si quieres generar valores dinámicamente (mientras que los valores en un diccionario son constantes).

Usar filtros para impartir información contextual

También puedes agregar información contextual a la salida del log utilizando un Filter definido por el usuario. Las instancias de Filter pueden modificar los LogRecords que se les pasan, incluido el agregado de atributos adicionales que luego se pueden generar utilizando cadena de caracteres con el formato adecuado, o si es necesario, un Formatter personalizado.

Por ejemplo, en una aplicación web, la solicitud que se está procesando (o al menos, las partes interesantes de la misma) se pueden almacenar en una variable threadlocal (threading.local) y luego se puede acceder a ella desde Filter para agregar información de la solicitud, - digamos, la dirección IP remota y el nombre de usuario-, al LogRecord, usando los nombres de atributo “ip” y “user” como en el ejemplo anterior de LoggerAdapter. En ese caso, se puede usar el mismo formato de cadena de caracteres para obtener un resultado similar al que se muestra arriba. Aquí hay un script de ejemplo:

import logging
from random import choice

class ContextFilter(logging.Filter):
    """
    This is a filter which injects contextual information into the log.

    Rather than use actual contextual information, we just use random
    data in this demo.
    """

    USERS = ['jim', 'fred', 'sheila']
    IPS = ['123.231.231.123', '127.0.0.1', '192.168.0.1']

    def filter(self, record):

        record.ip = choice(ContextFilter.IPS)
        record.user = choice(ContextFilter.USERS)
        return True

if __name__ == '__main__':
    levels = (logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR, logging.CRITICAL)
    logging.basicConfig(level=logging.DEBUG,
                        format='%(asctime)-15s %(name)-5s %(levelname)-8s IP: %(ip)-15s User: %(user)-8s %(message)s')
    a1 = logging.getLogger('a.b.c')
    a2 = logging.getLogger('d.e.f')

    f = ContextFilter()
    a1.addFilter(f)
    a2.addFilter(f)
    a1.debug('A debug message')
    a1.info('An info message with %s', 'some parameters')
    for x in range(10):
        lvl = choice(levels)
        lvlname = logging.getLevelName(lvl)
        a2.log(lvl, 'A message at %s level with %d %s', lvlname, 2, 'parameters')

que cuando se ejecuta, produce algo como:

2010-09-06 22:38:15,292 a.b.c DEBUG    IP: 123.231.231.123 User: fred     A debug message
2010-09-06 22:38:15,300 a.b.c INFO     IP: 192.168.0.1     User: sheila   An info message with some parameters
2010-09-06 22:38:15,300 d.e.f CRITICAL IP: 127.0.0.1       User: sheila   A message at CRITICAL level with 2 parameters
2010-09-06 22:38:15,300 d.e.f ERROR    IP: 127.0.0.1       User: jim      A message at ERROR level with 2 parameters
2010-09-06 22:38:15,300 d.e.f DEBUG    IP: 127.0.0.1       User: sheila   A message at DEBUG level with 2 parameters
2010-09-06 22:38:15,300 d.e.f ERROR    IP: 123.231.231.123 User: fred     A message at ERROR level with 2 parameters
2010-09-06 22:38:15,300 d.e.f CRITICAL IP: 192.168.0.1     User: jim      A message at CRITICAL level with 2 parameters
2010-09-06 22:38:15,300 d.e.f CRITICAL IP: 127.0.0.1       User: sheila   A message at CRITICAL level with 2 parameters
2010-09-06 22:38:15,300 d.e.f DEBUG    IP: 192.168.0.1     User: jim      A message at DEBUG level with 2 parameters
2010-09-06 22:38:15,301 d.e.f ERROR    IP: 127.0.0.1       User: sheila   A message at ERROR level with 2 parameters
2010-09-06 22:38:15,301 d.e.f DEBUG    IP: 123.231.231.123 User: fred     A message at DEBUG level with 2 parameters
2010-09-06 22:38:15,301 d.e.f INFO     IP: 123.231.231.123 User: fred     A message at INFO level with 2 parameters

Logging a un sólo archivo desde múltiples procesos

Aunque logging es seguro para hilos, y el logging a un solo archivo desde múltiples hilos en un solo proceso es compatible, el logging en un solo archivo desde múltiples procesos no es compatible, porque no existe una forma estándar de serializar el acceso a un solo archivo en múltiples procesos en Python. Si necesita hacer esto último, una forma de abordarlo es hacer que todos los procesos se registren en una SocketHandler, y tener un proceso separado que implemente un servidor de socket que lee del socket y los loggings para archivar. (Si lo prefiere, puede dedicar un hilo en uno de los procesos existentes para realizar esta función.) Esta sección documenta este enfoque con más detalle e incluye un receptor socket que funciona que se puede utilizar como punto de partida para que se adapte a sus propias aplicaciones.

También puedes escribir tu propio gestor que use la clase Lock del módulo multiprocessing para serializar el acceso al archivo desde tus procesos. La existente FileHandler y las subclases no hacen uso de multiprocessing en la actualidad, aunque pueden hacerlo en el futuro. Tenga en cuenta que, en la actualidad, el módulo multiprocessing no proporciona la funcionalidad de bloqueo de trabajo en todas las plataformas (ver https://bugs.python.org/issue3770).

Alternativamente, puede usar una Queue y QueueHandler para enviar todos los logging a uno de los procesos en su aplicación multi-proceso. El siguiente script de ejemplo demuestra cómo puede hacer esto; en el ejemplo, un proceso de escucha independiente escucha los eventos enviados por otros procesos y los registra de acuerdo con su propia configuración de logging. Aunque el ejemplo solo demuestra una forma de hacerlo (por ejemplo, es posible que desee utilizar un hilo de escucha en lugar de un proceso de escucha separado; la implementación sería análoga), permite configuraciones de logging completamente diferentes para el oyente y los otros procesos en su aplicación. Y se puede utilizar como base para el código que cumpla con sus propios requisitos específicos:

# You'll need these imports in your own code
import logging
import logging.handlers
import multiprocessing

# Next two import lines for this demo only
from random import choice, random
import time

#
# Because you'll want to define the logging configurations for listener and workers, the
# listener and worker process functions take a configurer parameter which is a callable
# for configuring logging for that process. These functions are also passed the queue,
# which they use for communication.
#
# In practice, you can configure the listener however you want, but note that in this
# simple example, the listener does not apply level or filter logic to received records.
# In practice, you would probably want to do this logic in the worker processes, to avoid
# sending events which would be filtered out between processes.
#
# The size of the rotated files is made small so you can see the results easily.
def listener_configurer():
    root = logging.getLogger()
    h = logging.handlers.RotatingFileHandler('mptest.log', 'a', 300, 10)
    f = logging.Formatter('%(asctime)s %(processName)-10s %(name)s %(levelname)-8s %(message)s')
    h.setFormatter(f)
    root.addHandler(h)

# This is the listener process top-level loop: wait for logging events
# (LogRecords)on the queue and handle them, quit when you get a None for a
# LogRecord.
def listener_process(queue, configurer):
    configurer()
    while True:
        try:
            record = queue.get()
            if record is None:  # We send this as a sentinel to tell the listener to quit.
                break
            logger = logging.getLogger(record.name)
            logger.handle(record)  # No level or filter logic applied - just do it!
        except Exception:
            import sys, traceback
            print('Whoops! Problem:', file=sys.stderr)
            traceback.print_exc(file=sys.stderr)

# Arrays used for random selections in this demo

LEVELS = [logging.DEBUG, logging.INFO, logging.WARNING,
          logging.ERROR, logging.CRITICAL]

LOGGERS = ['a.b.c', 'd.e.f']

MESSAGES = [
    'Random message #1',
    'Random message #2',
    'Random message #3',
]

# The worker configuration is done at the start of the worker process run.
# Note that on Windows you can't rely on fork semantics, so each process
# will run the logging configuration code when it starts.
def worker_configurer(queue):
    h = logging.handlers.QueueHandler(queue)  # Just the one handler needed
    root = logging.getLogger()
    root.addHandler(h)
    # send all messages, for demo; no other level or filter logic applied.
    root.setLevel(logging.DEBUG)

# This is the worker process top-level loop, which just logs ten events with
# random intervening delays before terminating.
# The print messages are just so you know it's doing something!
def worker_process(queue, configurer):
    configurer(queue)
    name = multiprocessing.current_process().name
    print('Worker started: %s' % name)
    for i in range(10):
        time.sleep(random())
        logger = logging.getLogger(choice(LOGGERS))
        level = choice(LEVELS)
        message = choice(MESSAGES)
        logger.log(level, message)
    print('Worker finished: %s' % name)

# Here's where the demo gets orchestrated. Create the queue, create and start
# the listener, create ten workers and start them, wait for them to finish,
# then send a None to the queue to tell the listener to finish.
def main():
    queue = multiprocessing.Queue(-1)
    listener = multiprocessing.Process(target=listener_process,
                                       args=(queue, listener_configurer))
    listener.start()
    workers = []
    for i in range(10):
        worker = multiprocessing.Process(target=worker_process,
                                         args=(queue, worker_configurer))
        workers.append(worker)
        worker.start()
    for w in workers:
        w.join()
    queue.put_nowait(None)
    listener.join()

if __name__ == '__main__':
    main()

Una variante del script anterior mantiene el logging en el proceso principal, en un hilo separado:

import logging
import logging.config
import logging.handlers
from multiprocessing import Process, Queue
import random
import threading
import time

def logger_thread(q):
    while True:
        record = q.get()
        if record is None:
            break
        logger = logging.getLogger(record.name)
        logger.handle(record)

def worker_process(q):
    qh = logging.handlers.QueueHandler(q)
    root = logging.getLogger()
    root.setLevel(logging.DEBUG)
    root.addHandler(qh)
    levels = [logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR,
              logging.CRITICAL]
    loggers = ['foo', 'foo.bar', 'foo.bar.baz',
               'spam', 'spam.ham', 'spam.ham.eggs']
    for i in range(100):
        lvl = random.choice(levels)
        logger = logging.getLogger(random.choice(loggers))
        logger.log(lvl, 'Message no. %d', i)

if __name__ == '__main__':
    q = Queue()
    d = {
        'version': 1,
        'formatters': {
            'detailed': {
                'class': 'logging.Formatter',
                'format': '%(asctime)s %(name)-15s %(levelname)-8s %(processName)-10s %(message)s'
            }
        },
        'handlers': {
            'console': {
                'class': 'logging.StreamHandler',
                'level': 'INFO',
            },
            'file': {
                'class': 'logging.FileHandler',
                'filename': 'mplog.log',
                'mode': 'w',
                'formatter': 'detailed',
            },
            'foofile': {
                'class': 'logging.FileHandler',
                'filename': 'mplog-foo.log',
                'mode': 'w',
                'formatter': 'detailed',
            },
            'errors': {
                'class': 'logging.FileHandler',
                'filename': 'mplog-errors.log',
                'mode': 'w',
                'level': 'ERROR',
                'formatter': 'detailed',
            },
        },
        'loggers': {
            'foo': {
                'handlers': ['foofile']
            }
        },
        'root': {
            'level': 'DEBUG',
            'handlers': ['console', 'file', 'errors']
        },
    }
    workers = []
    for i in range(5):
        wp = Process(target=worker_process, name='worker %d' % (i + 1), args=(q,))
        workers.append(wp)
        wp.start()
    logging.config.dictConfig(d)
    lp = threading.Thread(target=logger_thread, args=(q,))
    lp.start()
    # At this point, the main process could do some useful work of its own
    # Once it's done that, it can wait for the workers to terminate...
    for wp in workers:
        wp.join()
    # And now tell the logging thread to finish up, too
    q.put(None)
    lp.join()

Esta variante muestra cómo puede, por ejemplo, aplicar la configuración para logging particulares: el registrador foo tiene un gestor especial que almacena todos los eventos en el subsistema foo en un archivo mplog-foo.log. Esto será utilizado por la maquinaria de logging en el proceso principal (aunque los eventos logging se generen en los procesos de trabajo) para dirigir los mensajes a los destinos apropiados.

Usando concurrent.futures.ProcessPoolExecutor

Si desea utilizar concurrent.futures.ProcessPoolExecutor para iniciar sus procesos de trabajo, debe crear la cola de manera ligeramente diferente. En vez de

queue = multiprocessing.Queue(-1)

debería usar

queue = multiprocessing.Manager().Queue(-1)  # also works with the examples above

y luego puede reemplazar la creación del trabajador de esto:

workers = []
for i in range(10):
    worker = multiprocessing.Process(target=worker_process,
                                     args=(queue, worker_configurer))
    workers.append(worker)
    worker.start()
for w in workers:
    w.join()

a esto (recuerda el primer import concurrent.futures):

with concurrent.futures.ProcessPoolExecutor(max_workers=10) as executor:
    for i in range(10):
        executor.submit(worker_process, queue, worker_configurer)

Deploying Web applications using Gunicorn and uWSGI

When deploying Web applications using Gunicorn [https://gunicorn.org/] or uWSGI [https://uwsgi-docs.readthedocs.io/en/latest/] (or similar), multiple worker processes are created to handle client requests. In such environments, avoid creating file-based handlers directly in your web application. Instead, use a SocketHandler to log from the web application to a listener in a separate process. This can be set up using a process management tool such as Supervisor - see Running a logging socket listener in production for more details.

Usando rotación de archivos

A veces, se desea dejar que un archivo de log crezca hasta cierto tamaño y luego abra un nuevo archivo e inicie sesión en él. Es posible que desee conservar una cierta cantidad de estos archivos, y cuando se hayan creado tantos archivos, rote los archivos para que la cantidad de archivos y el tamaño de los archivos permanezcan limitados. Para este patrón de uso, el paquete logging proporciona RotatingFileHandler:

import glob
import logging
import logging.handlers

LOG_FILENAME = 'logging_rotatingfile_example.out'

# Set up a specific logger with our desired output level
my_logger = logging.getLogger('MyLogger')
my_logger.setLevel(logging.DEBUG)

# Add the log message handler to the logger
handler = logging.handlers.RotatingFileHandler(
              LOG_FILENAME, maxBytes=20, backupCount=5)

my_logger.addHandler(handler)

# Log some messages
for i in range(20):
    my_logger.debug('i = %d' % i)

# See what files are created
logfiles = glob.glob('%s*' % LOG_FILENAME)

for filename in logfiles:
    print(filename)

El resultado debe ser 6 archivos separados, cada uno con parte del historial de log de la aplicación:

logging_rotatingfile_example.out
logging_rotatingfile_example.out.1
logging_rotatingfile_example.out.2
logging_rotatingfile_example.out.3
logging_rotatingfile_example.out.4
logging_rotatingfile_example.out.5

El archivo más actual siempre es logging_rotatingfile_example.out, y cada vez que alcanza el límite de tamaño, se le cambia el nombre con el sufijo``.1``. Se cambia el nombre de cada uno de los archivos de respaldo existentes para incrementar el sufijo (.1 se convierte en .2, etc.) y se borra el archivo .6.

Obviamente, este ejemplo establece la longitud del log demasiado pequeña como un ejemplo extremo. Se querrá establecer maxBytes en un valor apropiado.

Uso de estilos de formato alternativos

Cuando se agregó logging a la biblioteca estándar de Python, la única forma de formatear mensajes con contenido variable era usar el método de formateo “%”. Desde entonces, Python ha ganado dos nuevos enfoques de formato: string.Template (agregado en Python 2.4) y str.format() (agregado en Python 2.6).

Logging (a partir de la versión 3.2) proporciona un soporte mejorado para estos dos estilos de formato adicionales. La clase Formatter ha sido mejorada para tomar un parámetro de palabra clave adicional llamado style. El valor predeterminado es '%', pero otros valores posibles son '{' y '$', que corresponden a los otros dos estilos de formato. La compatibilidad con versiones anteriores se mantiene de forma predeterminada (como era de esperar), pero al especificar explícitamente un parámetro de estilo, tiene la capacidad de especificar cadenas de formato que funcionan con str.format() o string.Template. Aquí hay una sesión de consola de ejemplo para mostrar las posibilidades:

>>> import logging
>>> root = logging.getLogger()
>>> root.setLevel(logging.DEBUG)
>>> handler = logging.StreamHandler()
>>> bf = logging.Formatter('{asctime} {name} {levelname:8s} {message}',
...                        style='{')
>>> handler.setFormatter(bf)
>>> root.addHandler(handler)
>>> logger = logging.getLogger('foo.bar')
>>> logger.debug('This is a DEBUG message')
2010-10-28 15:11:55,341 foo.bar DEBUG    This is a DEBUG message
>>> logger.critical('This is a CRITICAL message')
2010-10-28 15:12:11,526 foo.bar CRITICAL This is a CRITICAL message
>>> df = logging.Formatter('$asctime $name ${levelname} $message',
...                        style='$')
>>> handler.setFormatter(df)
>>> logger.debug('This is a DEBUG message')
2010-10-28 15:13:06,924 foo.bar DEBUG This is a DEBUG message
>>> logger.critical('This is a CRITICAL message')
2010-10-28 15:13:11,494 foo.bar CRITICAL This is a CRITICAL message
>>>

Tenga en cuenta que el formato de logging para la salida final a los logs es completamente independiente de cómo se construye un mensaje de logging individual. Para eso todavía puede usar el formateo «%», como se muestra aquí:

>>> logger.error('This is an%s %s %s', 'other,', 'ERROR,', 'message')
2010-10-28 15:19:29,833 foo.bar ERROR This is another, ERROR, message
>>>

Las llamadas de Logging (logger.debug(), logger.info(), etc.) solo toman parámetros posicionales para el mensaje de logging real en sí, los parámetros de palabras clave se usan solo para determinar opciones sobre cómo gestionar la llamada propiamente a Logging (por ejemplo, el parámetro de palabra clave exc_info para indicar que la información de rastreo debe registrarse, o el parámetro de palabra clave extra para indicar información contextual adicional que se agregará al log). Por lo tanto, no puede realizar llamadas de logging directamente usando la sintaxis str.format() o string.Template, porque internamente el paquete de logging usa formato % para fusionar la cadena de formato y los argumentos de las variables. No habría ningún cambio en esto mientras se conserva la compatibilidad con versiones anteriores, ya que todas las llamadas de logging que están en el código existente usarán cadenas de formato %.

Sin embargo, existe una forma en la que puede usar el formato {} - y $ - para construir sus mensajes de log individuales. Recuerde que para un mensaje puede usar un objeto arbitrario como una cadena de caracteres de formato de mensaje, y que el paquete logging llamará a str() en ese objeto para obtener la cadena de caracteres de formato real. Considere las siguientes dos clases:

class BraceMessage:
    def __init__(self, fmt, /, *args, **kwargs):
        self.fmt = fmt
        self.args = args
        self.kwargs = kwargs

    def __str__(self):
        return self.fmt.format(*self.args, **self.kwargs)

class DollarMessage:
    def __init__(self, fmt, /, **kwargs):
        self.fmt = fmt
        self.kwargs = kwargs

    def __str__(self):
        from string import Template
        return Template(self.fmt).substitute(**self.kwargs)

Cualquiera de estos puede usarse en lugar de una cadena de formato, para permitir que se use el formato {} - o $ - para construir la parte del «mensaje» real que aparece en la salida del log en lugar de «%(message)s» o «{message}» o «$message». Es un poco difícil de manejar usar los nombres de las clases siempre que quieras registrar algo, pero es bastante aceptable si usas un alias como __ (doble subrayado — no confundir con _, el subrayado simple usado como sinónimo/alias para gettext.gettext() o sus hermanos).

Las clases anteriores no están incluidas en Python, aunque son bastante fáciles de copiar y pegar en su propio código. Se pueden usar de la siguiente manera (asumiendo que están declaradas en un módulo llamado wherever):

>>> from wherever import BraceMessage as __
>>> print(__('Message with {0} {name}', 2, name='placeholders'))
Message with 2 placeholders
>>> class Point: pass
...
>>> p = Point()
>>> p.x = 0.5
>>> p.y = 0.5
>>> print(__('Message with coordinates: ({point.x:.2f}, {point.y:.2f})',
...       point=p))
Message with coordinates: (0.50, 0.50)
>>> from wherever import DollarMessage as __
>>> print(__('Message with $num $what', num=2, what='placeholders'))
Message with 2 placeholders
>>>

Si bien los ejemplos anteriores usan print() para mostrar cómo funciona el formateo, por supuesto usaría logger.debug() o similar para realmente registrar usando este enfoque.

Una cosa a tener en cuenta es que no paga una penalización de rendimiento significativa con este enfoque: el formateo real no ocurre cuando realiza la llamada a logging, sino cuando (y si) el mensaje registrado está a punto de ser enviado a un log por un gestor. Entonces, lo único un poco inusual que podría confundirte es que los paréntesis rodean la cadena de formato y los argumentos, no solo la cadena de formato. Eso es porque la notación __ es solo azúcar sintáctico para una llamada de constructor a una de las clases XXXMessage.

Si lo prefiere, puede usar LoggerAdapter para lograr un efecto similar al anterior, como en el siguiente ejemplo:

import logging

class Message:
    def __init__(self, fmt, args):
        self.fmt = fmt
        self.args = args

    def __str__(self):
        return self.fmt.format(*self.args)

class StyleAdapter(logging.LoggerAdapter):
    def __init__(self, logger, extra=None):
        super().__init__(logger, extra or {})

    def log(self, level, msg, /, *args, **kwargs):
        if self.isEnabledFor(level):
            msg, kwargs = self.process(msg, kwargs)
            self.logger._log(level, Message(msg, args), (), **kwargs)

logger = StyleAdapter(logging.getLogger(__name__))

def main():
    logger.debug('Hello, {}', 'world!')

if __name__ == '__main__':
    logging.basicConfig(level=logging.DEBUG)
    main()

El script anterior debería registrar el mensaje Hello, world! Cuando se ejecuta con Python 3.2 o posterior.

Personalización de LogRecord

Cada evento logging está representado por una instancia LogRecord. Cuando se registra un evento y no se filtra por el nivel de un registrador, se crea LogRecord, se llena con información sobre el evento y luego se pasa a los gestores de ese registrador (y sus antepasados, hasta (e incluyéndolo) el registrador donde se deshabilita una mayor propagación en la jerarquía). Antes de Python 3.2, solo había dos lugares donde se realizaba esta creación:

Logger.makeRecord(), que se llama en el proceso normal de logging de un evento. Esto invoca LogRecord directamente para crear una instancia.

makeLogRecord(), que se llama con un diccionario que contiene atributos que se agregarán al LogRecord. Esto se suele invocar cuando se ha recibido un diccionario adecuado a través de la red (por ejemplo, en forma de pickle a través de SocketHandler, o en formato JSON a través de HTTPHandler).

Por lo general, esto significa que si necesita hacer algo especial con LogRecord, debe hacer una de las siguientes cosas.

Cree su propia subclase Logger, que anula Logger.makeRecord(), y configúrelo usando setLoggerClass() antes de que se creen instancias de los registradores que le interesan.

Agrega un Filter a un registrador o gestor, que realiza la manipulación especial necesaria que necesita cuando se llama a su método filter().

El primer enfoque sería un poco difícil de manejar en el escenario en el que (digamos) varias bibliotecas diferentes quisieran hacer cosas diferentes. Cada uno intentaría establecer su propia subclase Logger, y el que hiciera esto último ganaría.

El segundo enfoque funciona razonablemente bien en muchos casos, pero no le permite, por ejemplo, usar una subclase especializada de LogRecord. Los desarrolladores de bibliotecas pueden establecer un filtro adecuado en sus registradores, pero tendrían que recordar hacerlo cada vez que introduzcan un nuevo registrador (lo que harían simplemente agregando nuevos paquetes o módulos y haciendo

logger = logging.getLogger(__name__)

a nivel de módulo). Probablemente sean demasiadas cosas en las que pensar. Los desarrolladores también podrían agregar el filtro a NullHandler adjunto a su registrador de nivel superior, pero esto no se invocaría si un desarrollador de aplicaciones adjuntara un controlador a un registrador de biblioteca de nivel inferior — así que la salida de ese gestor no reflejaría las intenciones del desarrollador de la biblioteca.

En Python 3.2 y posteriores, la creación de LogRecord se realiza a través de una fábrica, que puede especificar. La fábrica es simplemente un invocable que puede configurar con setLogRecordFactory(), e interrogar con getLogRecordFactory(). La fábrica se invoca con la misma firma que el constructor LogRecord, ya que LogRecord es la configuración predeterminada de la fábrica.

Este enfoque permite que una fábrica personalizada controle todos los aspectos de la creación de LogRecord. Por ejemplo, podría devolver una subclase, o simplemente agregar algunos atributos adicionales al registro una vez creado, usando un patrón similar a este:

old_factory = logging.getLogRecordFactory()

def record_factory(*args, **kwargs):
    record = old_factory(*args, **kwargs)
    record.custom_attribute = 0xdecafbad
    return record

logging.setLogRecordFactory(record_factory)

Este patrón permite que diferentes bibliotecas encadenen fábricas juntas, y siempre que no sobrescriban los atributos de las demás o sobrescriban involuntariamente los atributos proporcionados como estándar, no debería haber sorpresas. Sin embargo, debe tenerse en cuenta que cada eslabón de la cadena agrega una sobrecarga de tiempo de ejecución a todas las operaciones de logging, y la técnica solo debe usarse cuando el uso de Filter no proporciona el resultado deseado.

Subclasificación QueueHandler - un ejemplo de ZeroMQ

Puede usar una subclase QueueHandler para enviar mensajes a otros tipos de colas, por ejemplo, un socket de “publicación” ZeroMQ. En el siguiente ejemplo, el socket se crea por separado y se pasa al gestor (como su “cola”):

import zmq   # using pyzmq, the Python binding for ZeroMQ
import json  # for serializing records portably

ctx = zmq.Context()
sock = zmq.Socket(ctx, zmq.PUB)  # or zmq.PUSH, or other suitable value
sock.bind('tcp://*:5556')        # or wherever

class ZeroMQSocketHandler(QueueHandler):
    def enqueue(self, record):
        self.queue.send_json(record.__dict__)

handler = ZeroMQSocketHandler(sock)

Por supuesto, hay otras formas de organizar esto, por ejemplo, pasando los datos que necesita el gestor para crear el socket:

class ZeroMQSocketHandler(QueueHandler):
    def __init__(self, uri, socktype=zmq.PUB, ctx=None):
        self.ctx = ctx or zmq.Context()
        socket = zmq.Socket(self.ctx, socktype)
        socket.bind(uri)
        super().__init__(socket)

    def enqueue(self, record):
        self.queue.send_json(record.__dict__)

    def close(self):
        self.queue.close()

Subclasificación QueueListener - un ejemplo de ZeroMQ

También puede subclasificar QueueListener para obtener mensajes de otros tipos de colas, por ejemplo, un socket de “suscripción” de ZeroMQ. Aquí tienes un ejemplo:

class ZeroMQSocketListener(QueueListener):
    def __init__(self, uri, /, *handlers, **kwargs):
        self.ctx = kwargs.get('ctx') or zmq.Context()
        socket = zmq.Socket(self.ctx, zmq.SUB)
        socket.setsockopt_string(zmq.SUBSCRIBE, '')  # subscribe to everything
        socket.connect(uri)
        super().__init__(socket, *handlers, **kwargs)

    def dequeue(self):
        msg = self.queue.recv_json()
        return logging.makeLogRecord(msg)

Ver también

Módulo logging

Referencia de API para el módulo logging.

Módulo logging.config

API de configuración para el módulo logging.

Módulo logging.handlers

Gestores útiles incluidos con el módulo logging.

Un tutorial básico de logging

Un tutorial de logging más avanzado

Una configuración de ejemplo basada en diccionario

A continuación se muestra un ejemplo de un diccionario de configuración de logging, tomado de la documentación del proyecto Django [https://docs.djangoproject.com/en/1.9/topics/logging/#configuring-logging]. Este diccionario se pasa a dictConfig() para poner en efecto la configuración:

LOGGING = {
    'version': 1,
    'disable_existing_loggers': True,
    'formatters': {
        'verbose': {
            'format': '%(levelname)s %(asctime)s %(module)s %(process)d %(thread)d %(message)s'
        },
        'simple': {
            'format': '%(levelname)s %(message)s'
        },
    },
    'filters': {
        'special': {
            '()': 'project.logging.SpecialFilter',
            'foo': 'bar',
        }
    },
    'handlers': {
        'null': {
            'level':'DEBUG',
            'class':'django.utils.log.NullHandler',
        },
        'console':{
            'level':'DEBUG',
            'class':'logging.StreamHandler',
            'formatter': 'simple'
        },
        'mail_admins': {
            'level': 'ERROR',
            'class': 'django.utils.log.AdminEmailHandler',
            'filters': ['special']
        }
    },
    'loggers': {
        'django': {
            'handlers':['null'],
            'propagate': True,
            'level':'INFO',
        },
        'django.request': {
            'handlers': ['mail_admins'],
            'level': 'ERROR',
            'propagate': False,
        },
        'myproject.custom': {
            'handlers': ['console', 'mail_admins'],
            'level': 'INFO',
            'filters': ['special']
        }
    }
}

Para obtener más información sobre esta configuración, puede ver la sección correspondiente [https://docs.djangoproject.com/en/1.9/topics/logging/#configuring-logging] de la documentación de Django.

Usar un rotador y un nombre para personalizar el procesamiento de rotación de log

Un ejemplo de cómo puede definir un nombre y un rotador se da en el siguiente fragmento, que muestra la compresión basada en zlib del archivo de log:

def namer(name):
    return name + ".gz"

def rotator(source, dest):
    with open(source, "rb") as sf:
        data = sf.read()
        compressed = zlib.compress(data, 9)
        with open(dest, "wb") as df:
            df.write(compressed)
    os.remove(source)

rh = logging.handlers.RotatingFileHandler(...)
rh.rotator = rotator
rh.namer = namer

Estos no son archivos .gz «verdaderos», ya que son datos comprimidos sin ningún «contenedor» como el que encontraría en un archivo gzip real. Este fragmento es solo para fines ilustrativos.

Un ejemplo de multiprocesamiento más elaborado

El siguiente ejemplo de trabajo muestra cómo logging se puede usar con multiprocesamiento usando archivos de configuración. Las configuraciones son bastante simples, pero sirven para ilustrar cómo se podrían implementar las más complejas en un escenario real de multiprocesamiento.

En el ejemplo, el proceso principal genera un proceso de escucha y algunos procesos de trabajo. Cada uno de los procesos principales, el oyente y los trabajadores tienen tres configuraciones separadas (todos los trabajadores comparten la misma configuración). Podemos ver el registro en el proceso principal, cómo los trabajadores se registran en un QueueHandler y cómo el oyente implementa un QueueListener y una configuración de registro más compleja, y organiza el envío de eventos recibidos a través de la cola a los controladores especificados en la configuración. Tenga en cuenta que estas configuraciones son puramente ilustrativas, pero debería poder adaptar este ejemplo a su propio escenario.

Aquí está el script, el docstrings y los comentarios, esperemos, expliquen cómo funciona:

import logging
import logging.config
import logging.handlers
from multiprocessing import Process, Queue, Event, current_process
import os
import random
import time

class MyHandler:
    """
    A simple handler for logging events. It runs in the listener process and
    dispatches events to loggers based on the name in the received record,
    which then get dispatched, by the logging system, to the handlers
    configured for those loggers.
    """

    def handle(self, record):
        if record.name == "root":
            logger = logging.getLogger()
        else:
            logger = logging.getLogger(record.name)

        if logger.isEnabledFor(record.levelno):
            # The process name is transformed just to show that it's the listener
            # doing the logging to files and console
            record.processName = '%s (for %s)' % (current_process().name, record.processName)
            logger.handle(record)

def listener_process(q, stop_event, config):
    """
    This could be done in the main process, but is just done in a separate
    process for illustrative purposes.

    This initialises logging according to the specified configuration,
    starts the listener and waits for the main process to signal completion
    via the event. The listener is then stopped, and the process exits.
    """
    logging.config.dictConfig(config)
    listener = logging.handlers.QueueListener(q, MyHandler())
    listener.start()
    if os.name == 'posix':
        # On POSIX, the setup logger will have been configured in the
        # parent process, but should have been disabled following the
        # dictConfig call.
        # On Windows, since fork isn't used, the setup logger won't
        # exist in the child, so it would be created and the message
        # would appear - hence the "if posix" clause.
        logger = logging.getLogger('setup')
        logger.critical('Should not appear, because of disabled logger ...')
    stop_event.wait()
    listener.stop()

def worker_process(config):
    """
    A number of these are spawned for the purpose of illustration. In
    practice, they could be a heterogeneous bunch of processes rather than
    ones which are identical to each other.

    This initialises logging according to the specified configuration,
    and logs a hundred messages with random levels to randomly selected
    loggers.

    A small sleep is added to allow other processes a chance to run. This
    is not strictly needed, but it mixes the output from the different
    processes a bit more than if it's left out.
    """
    logging.config.dictConfig(config)
    levels = [logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR,
              logging.CRITICAL]
    loggers = ['foo', 'foo.bar', 'foo.bar.baz',
               'spam', 'spam.ham', 'spam.ham.eggs']
    if os.name == 'posix':
        # On POSIX, the setup logger will have been configured in the
        # parent process, but should have been disabled following the
        # dictConfig call.
        # On Windows, since fork isn't used, the setup logger won't
        # exist in the child, so it would be created and the message
        # would appear - hence the "if posix" clause.
        logger = logging.getLogger('setup')
        logger.critical('Should not appear, because of disabled logger ...')
    for i in range(100):
        lvl = random.choice(levels)
        logger = logging.getLogger(random.choice(loggers))
        logger.log(lvl, 'Message no. %d', i)
        time.sleep(0.01)

def main():
    q = Queue()
    # The main process gets a simple configuration which prints to the console.
    config_initial = {
        'version': 1,
        'handlers': {
            'console': {
                'class': 'logging.StreamHandler',
                'level': 'INFO'
            }
        },
        'root': {
            'handlers': ['console'],
            'level': 'DEBUG'
        }
    }
    # The worker process configuration is just a QueueHandler attached to the
    # root logger, which allows all messages to be sent to the queue.
    # We disable existing loggers to disable the "setup" logger used in the
    # parent process. This is needed on POSIX because the logger will
    # be there in the child following a fork().
    config_worker = {
        'version': 1,
        'disable_existing_loggers': True,
        'handlers': {
            'queue': {
                'class': 'logging.handlers.QueueHandler',
                'queue': q
            }
        },
        'root': {
            'handlers': ['queue'],
            'level': 'DEBUG'
        }
    }
    # The listener process configuration shows that the full flexibility of
    # logging configuration is available to dispatch events to handlers however
    # you want.
    # We disable existing loggers to disable the "setup" logger used in the
    # parent process. This is needed on POSIX because the logger will
    # be there in the child following a fork().
    config_listener = {
        'version': 1,
        'disable_existing_loggers': True,
        'formatters': {
            'detailed': {
                'class': 'logging.Formatter',
                'format': '%(asctime)s %(name)-15s %(levelname)-8s %(processName)-10s %(message)s'
            },
            'simple': {
                'class': 'logging.Formatter',
                'format': '%(name)-15s %(levelname)-8s %(processName)-10s %(message)s'
            }
        },
        'handlers': {
            'console': {
                'class': 'logging.StreamHandler',
                'formatter': 'simple',
                'level': 'INFO'
            },
            'file': {
                'class': 'logging.FileHandler',
                'filename': 'mplog.log',
                'mode': 'w',
                'formatter': 'detailed'
            },
            'foofile': {
                'class': 'logging.FileHandler',
                'filename': 'mplog-foo.log',
                'mode': 'w',
                'formatter': 'detailed'
            },
            'errors': {
                'class': 'logging.FileHandler',
                'filename': 'mplog-errors.log',
                'mode': 'w',
                'formatter': 'detailed',
                'level': 'ERROR'
            }
        },
        'loggers': {
            'foo': {
                'handlers': ['foofile']
            }
        },
        'root': {
            'handlers': ['console', 'file', 'errors'],
            'level': 'DEBUG'
        }
    }
    # Log some initial events, just to show that logging in the parent works
    # normally.
    logging.config.dictConfig(config_initial)
    logger = logging.getLogger('setup')
    logger.info('About to create workers ...')
    workers = []
    for i in range(5):
        wp = Process(target=worker_process, name='worker %d' % (i + 1),
                     args=(config_worker,))
        workers.append(wp)
        wp.start()
        logger.info('Started worker: %s', wp.name)
    logger.info('About to create listener ...')
    stop_event = Event()
    lp = Process(target=listener_process, name='listener',
                 args=(q, stop_event, config_listener))
    lp.start()
    logger.info('Started listener')
    # We now hang around for the workers to finish their work.
    for wp in workers:
        wp.join()
    # Workers all done, listening can now stop.
    # Logging in the parent still works normally.
    logger.info('Telling listener to stop ...')
    stop_event.set()
    lp.join()
    logger.info('All done.')

if __name__ == '__main__':
    main()

Insertar BOM en mensajes enviados a SysLogHandler

RFC 5424 [https://tools.ietf.org/html/rfc5424.html] requiere que se envíe un mensaje Unicode a un demonio syslog como un conjunto de bytes que tienen la siguiente estructura: un componente opcional ASCII puro, seguido de una marca de orden de bytes UTF-8 (BOM), seguida de Codificado en Unicode usando UTF-8. (Ver sección relevante de la especificación RFC 5424#section-6 [https://tools.ietf.org/html/rfc5424.html#section-6].)

En Python 3.1, se agregó código a SysLogHandler para insertar BOM en el mensaje, pero desafortunadamente, se implementó incorrectamente, BOM aparece al principio del mensaje y, por lo tanto, no permite ningún componente ASCII puro para que aparezca antes.

Como este comportamiento no funciona, el código de inserción BOM incorrecto se elimina de Python 3.2.4 y versiones posteriores. Sin embargo, no se está reemplazando, y si desea producir mensajes compatibles con RFC 5424 [https://tools.ietf.org/html/rfc5424.html] que incluyan BOM, una secuencia opcional de ASCII puro antes y Unicode arbitrario después, codificados usando UTF-8; entonces necesita hacer lo siguiente:

Adjunte una instancia de Formatter a su instancia SysLogHandler, con una cadena de caracteres de formato como:

'ASCII section\ufeffUnicode section'

El punto de código Unicode U+ FEFF, cuando se codifica usando UTF-8, se codificará como una BOM UTF-8, la cadena de bytes b'\xef\xbb\xbf'.

Reemplace la sección ASCII con los marcadores de posición que desee, pero asegúrese de que los datos que aparecen allí después de la sustitución sean siempre ASCII (de esa manera, permanecerán sin cambios después de la codificación UTF-8).

Reemplace la sección Unicode con los marcadores de posición que desee; si los datos que aparecen allí después de la sustitución contienen caracteres fuera del rango ASCII, está bien: se codificarán usando UTF-8.

El mensaje formateado se codificará utilizando la codificación UTF-8 por SysLogHandler. Si sigue las reglas anteriores, debería poder producir mensajes compatibles con RFC 5424 [https://tools.ietf.org/html/rfc5424.html]. Si no lo hace, es posible que el logging no se queje, pero sus mensajes no serán compatibles con RFC 5424 y su demonio syslog puede quejarse.

Implementar logging estructurado

Aunque la mayoría de los mensajes de registro están destinados a ser leídos por humanos y, por lo tanto, no se pueden analizar fácilmente mediante una máquina, puede haber circunstancias en las que desee generar mensajes en un formato estructurado que sea capaz de ser analizado por un programa (sin necesidad de expresiones regulares complejas para analizar el mensaje de registro). Esto es sencillo de lograr utilizando el paquete de registro. Hay varias formas de lograr esto, pero el siguiente es un enfoque simple que usa JSON para serializar el evento de una manera analizable por máquina:

import json
import logging

class StructuredMessage:
    def __init__(self, message, /, **kwargs):
        self.message = message
        self.kwargs = kwargs

    def __str__(self):
        return '%s >>> %s' % (self.message, json.dumps(self.kwargs))

_ = StructuredMessage   # optional, to improve readability

logging.basicConfig(level=logging.INFO, format='%(message)s')
logging.info(_('message 1', foo='bar', bar='baz', num=123, fnum=123.456))

Si se ejecuta el script anterior, se imprime:

message 1 >>> {"fnum": 123.456, "num": 123, "bar": "baz", "foo": "bar"}

Tenga en cuenta que el orden de los elementos puede ser diferente según la versión de Python utilizada.

Si necesita un procesamiento más especializado, puede utilizar un codificador JSON personalizado, como en el siguiente ejemplo completo:

from __future__ import unicode_literals

import json
import logging

# This next bit is to ensure the script runs unchanged on 2.x and 3.x
try:
    unicode
except NameError:
    unicode = str

class Encoder(json.JSONEncoder):
    def default(self, o):
        if isinstance(o, set):
            return tuple(o)
        elif isinstance(o, unicode):
            return o.encode('unicode_escape').decode('ascii')
        return super().default(o)

class StructuredMessage:
    def __init__(self, message, /, **kwargs):
        self.message = message
        self.kwargs = kwargs

    def __str__(self):
        s = Encoder().encode(self.kwargs)
        return '%s >>> %s' % (self.message, s)

_ = StructuredMessage   # optional, to improve readability

def main():
    logging.basicConfig(level=logging.INFO, format='%(message)s')
    logging.info(_('message 1', set_value={1, 2, 3}, snowman='\u2603'))

if __name__ == '__main__':
    main()

Cuando se ejecuta el script anterior, se imprime:

message 1 >>> {"snowman": "\u2603", "set_value": [1, 2, 3]}

Tenga en cuenta que el orden de los elementos puede ser diferente según la versión de Python utilizada.

Personalización de gestores con dictConfig()

Hay ocasiones en las que desea personalizar los gestores de logging de formas particulares, y si usa dictConfig() puede hacerlo sin subclases. Como ejemplo, considere que es posible que desee establecer la propiedad de un archivo de log. En POSIX, esto se hace fácilmente usando shutil.chown(), pero los gestores de archivos en stdlib no ofrecen soporte integrado. Puede personalizar la creación de gestores usando una función simple como:

def owned_file_handler(filename, mode='a', encoding=None, owner=None):
    if owner:
        if not os.path.exists(filename):
            open(filename, 'a').close()
        shutil.chown(filename, *owner)
    return logging.FileHandler(filename, mode, encoding)

Luego puede especificar, en una configuración de logging pasada a dictConfig(), que se cree un gestor de logging llamando a esta función:

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        'default': {
            'format': '%(asctime)s %(levelname)s %(name)s %(message)s'
        },
    },
    'handlers': {
        'file':{
            # The values below are popped from this dictionary and
            # used to create the handler, set the handler's level and
            # its formatter.
            '()': owned_file_handler,
            'level':'DEBUG',
            'formatter': 'default',
            # The values below are passed to the handler creator callable
            # as keyword arguments.
            'owner': ['pulse', 'pulse'],
            'filename': 'chowntest.log',
            'mode': 'w',
            'encoding': 'utf-8',
        },
    },
    'root': {
        'handlers': ['file'],
        'level': 'DEBUG',
    },
}

En este ejemplo, se establece la propiedad utilizando el usuario y el grupo pulse, solo con fines ilustrativos. Poniéndolo junto en un script de trabajo, chowntest.py:

import logging, logging.config, os, shutil

def owned_file_handler(filename, mode='a', encoding=None, owner=None):
    if owner:
        if not os.path.exists(filename):
            open(filename, 'a').close()
        shutil.chown(filename, *owner)
    return logging.FileHandler(filename, mode, encoding)

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        'default': {
            'format': '%(asctime)s %(levelname)s %(name)s %(message)s'
        },
    },
    'handlers': {
        'file':{
            # The values below are popped from this dictionary and
            # used to create the handler, set the handler's level and
            # its formatter.
            '()': owned_file_handler,
            'level':'DEBUG',
            'formatter': 'default',
            # The values below are passed to the handler creator callable
            # as keyword arguments.
            'owner': ['pulse', 'pulse'],
            'filename': 'chowntest.log',
            'mode': 'w',
            'encoding': 'utf-8',
        },
    },
    'root': {
        'handlers': ['file'],
        'level': 'DEBUG',
    },
}

logging.config.dictConfig(LOGGING)
logger = logging.getLogger('mylogger')
logger.debug('A debug message')

Para ejecutar esto, probablemente se necesite ejecutarlo como root:

$ sudo python3.3 chowntest.py
$ cat chowntest.log
2013-11-05 09:34:51,128 DEBUG mylogger A debug message
$ ls -l chowntest.log
-rw-r--r-- 1 pulse pulse 55 2013-11-05 09:34 chowntest.log

Tenga en cuenta que este ejemplo usa Python 3.3 porque ahí es donde shutil.chown() aparece. Este enfoque debería funcionar con cualquier versión de Python que admita dictConfig(), es decir, Python 2.7, 3.2 o posterior. Con las versiones anteriores a 3.3, necesitaría implementar el cambio de propiedad real usando, por ejemplo, os.chown().

En la práctica, la función de creación de gestores puede estar en un módulo de utilidad en algún lugar de su proyecto. En lugar de la línea en la configuración:

'()': owned_file_handler,

podrías usar, por ejemplo,:

'()': 'ext://project.util.owned_file_handler',

donde project.util se puede reemplazar con el nombre real del paquete donde reside la función. En el script de trabajo anterior, el uso de 'ext://__main__.owned_file_handler' debería funcionar. Aquí, el invocable real se resuelve mediante dictConfig() de la especificación ext://.

Por fortuna, este ejemplo también indica el camino hacia cómo podría implementar otros tipos de cambio de archivo, por ejemplo, configurando de la misma manera bits de permisos POSIX específicos, usando os.chmod().

Por supuesto, el enfoque también podría extenderse a tipos de gestores distintos a FileHandler - por ejemplo, uno de los gestores de archivos rotativos, o un tipo diferente por completo.

Usar estilos de formato particulares en toda su aplicación

En Python 3.2, Formatter obtuvo un parámetro de palabra clave estilo que, aunque por defecto era % para compatibilidad con versiones anteriores, permitía la especificación de { o $ para permitir los enfoques de formato admitidos por str.format() y string.Template. Tenga en cuenta que esto rige el formato de los mensajes de logging para la salida final a los logging y es completamente ortogonal a cómo se construye un mensaje de logging individual.

Las llamadas de logging (debug(), info(), etc.) solo toman parámetros posicionales para el mensaje logging real en sí, con parámetros de palabras clave que se utilizan solo para determinar las opciones sobre cómo manejar la llamada de logging (por ejemplo, el parámetro de palabra clave exc_info para indicar que la información de rastreo debe registrarse, o el parámetro de palabra clave extra para indicar información contextual adicional que se agregará al log). Por lo tanto, no puede realizar llamadas de logging directamente usando la sintaxis str.format() o string.Template, porque internamente el paquete logging usa formato % para fusionar la cadena de formato y los argumentos de las variables. No se cambiaría esto mientras se conserve la compatibilidad con versiones anteriores, ya que todas las llamadas de logging que están en el código existente utilizarán cadenas de caracteres formato %.

Ha habido sugerencias para asociar estilos de formato con loggers específicos, pero ese enfoque también tiene problemas de compatibilidad con versiones anteriores porque cualquier código existente podría estar usando un nombre de logger dado y usando formato %.

Para que logging funcione de manera interoperable entre cualquier biblioteca de terceros y su código, las decisiones sobre el formato deben tomarse a nivel de la llamada de logging individual. Esto abre un par de formas en las que se pueden acomodar estilos de formato alternativos.

Uso de fábricas de LogRecord

En Python 3.2, junto con los cambios de Formatter mencionados anteriormente, el paquete logging ganó la capacidad de permitir a los usuarios establecer sus propias subclases LogRecord, usando la función setLogRecordFactory(). Puede usar esto para configurar su propia subclase de LogRecord, que hace lo correcto al anular el método getMessage(). La implementación de la clase base de este método es donde ocurre el formato msg % args y donde puede sustituir su formato alternativo; sin embargo, debe tener cuidado de admitir todos los estilos de formato y permitir formato % como predeterminado, para garantizar la interoperabilidad con otro código. También se debe tener cuidado de llamar a str(self.msg), tal como lo hace la implementación base.

Consulte la documentación de referencia en setLogRecordFactory() y LogRecord para obtener más información.

Usar objetos de mensaje personalizados

Existe otra forma, quizás más sencilla, de usar el formato {} - y $ - para construir sus mensajes de log individuales. Al iniciar sesión, recuerde que puede usar cualquier objeto como una cadena de caracteres de formato de mensaje (Usando objetos arbitrarios como mensajes) que al iniciar sesión puede usar un objeto arbitrario como una cadena de formato de mensaje, y que el paquete de logging llamará str() en ese objeto para obtener el cadena de formato real. Considere las siguientes dos clases:

class BraceMessage:
    def __init__(self, fmt, /, *args, **kwargs):
        self.fmt = fmt
        self.args = args
        self.kwargs = kwargs

    def __str__(self):
        return self.fmt.format(*self.args, **self.kwargs)

class DollarMessage:
    def __init__(self, fmt, /, **kwargs):
        self.fmt = fmt
        self.kwargs = kwargs

    def __str__(self):
        from string import Template
        return Template(self.fmt).substitute(**self.kwargs)

Cualquiera de estos puede usarse en lugar de una cadena de formato, para permitir que se use el formato {} - o $ - para construir la parte del «mensaje» real que aparece en la salida del log formateado en lugar de “%(message)s” or “{message}” or “$message”. Si le resulta un poco difícil de manejar usar los nombres de las clases cada vez que desea registrar algo, puede hacerlo más tolerable si usa un alias como M o _ para el mensaje (o quizás __, si está utilizando``_`` para localización).

A continuación se dan ejemplos de este enfoque. En primer lugar, formatear con str.format():

>>> __ = BraceMessage
>>> print(__('Message with {0} {1}', 2, 'placeholders'))
Message with 2 placeholders
>>> class Point: pass
...
>>> p = Point()
>>> p.x = 0.5
>>> p.y = 0.5
>>> print(__('Message with coordinates: ({point.x:.2f}, {point.y:.2f})', point=p))
Message with coordinates: (0.50, 0.50)

En segundo lugar, formatear con string.Template:

>>> __ = DollarMessage
>>> print(__('Message with $num $what', num=2, what='placeholders'))
Message with 2 placeholders
>>>

Una cosa a tener en cuenta es que no paga ninguna penalización significativa del rendimiento con este enfoque: el formato real no se produce cuando se realiza la llamada logging, sino cuando (y si) el mensaje registrado está realmente a punto de ser salida a un log por un gestor. Así que lo único un poco inusual con lo que podría tropezar es que los paréntesis van alrededor de la cadena de caracteres de formato y los argumentos, no sólo la cadena de formato. Esto se debe a que la notación __ es solo azúcar sintáctico para una llamada de constructor a una de las clases XXXMessage mostradas anteriormente.

Configurar filtros con dictConfig()

Puedes configurar filtros usando dictConfig(), aunque a primera vista es posible que no sea obvio cómo hacerlo (de ahí esta receta). Dado que Filter es la única clase de filtro incluida en la biblioteca estándar, y es poco probable que satisfaga muchos requisitos (solo está allí como clase base), normalmente necesitarás definir tu propia subclase Filter con un método filter() sobreescrito. Para hacer esto, especifique la clave () en el diccionario de configuración para el filtro, especificando un invocable que se usará para crear el filtro (una clase es la más obvia, pero puede proporcionar cualquier invocable que devuelva una instancia Filter). Aquí hay un ejemplo completo:

import logging
import logging.config
import sys

class MyFilter(logging.Filter):
    def __init__(self, param=None):
        self.param = param

    def filter(self, record):
        if self.param is None:
            allow = True
        else:
            allow = self.param not in record.msg
        if allow:
            record.msg = 'changed: ' + record.msg
        return allow

LOGGING = {
    'version': 1,
    'filters': {
        'myfilter': {
            '()': MyFilter,
            'param': 'noshow',
        }
    },
    'handlers': {
        'console': {
            'class': 'logging.StreamHandler',
            'filters': ['myfilter']
        }
    },
    'root': {
        'level': 'DEBUG',
        'handlers': ['console']
    },
}

if __name__ == '__main__':
    logging.config.dictConfig(LOGGING)
    logging.debug('hello')
    logging.debug('hello - noshow')

Este ejemplo muestra cómo puede pasar datos de configuración al invocable que construye la instancia, en forma de parámetros de palabras clave. Cuando se ejecuta, se imprimirá el script anterior:

changed: hello

que muestra que el filtro está funcionando según lo configurado.

Un par de puntos adicionales a tener en cuenta:

Si no puede hacer referencia al invocable directamente en la configuración (por ejemplo, si vive en un módulo diferente y no puede importarlo directamente donde está el diccionario de configuración), puede usar el formulario ext://... como se describe en Acceso a objetos externos. Por ejemplo, podría haber usado el texto 'ext://__main__.MyFilter' en lugar de MyFilter en el ejemplo anterior.

Además de los filtros, esta técnica también se puede utilizar para configurar gestores y formateadores personalizados. Consultar Objetos definidos por el usuario para obtener más información sobre cómo logging admite el uso de objetos definidos por el usuario en su configuración, y ver arriba la otra receta Personalización de gestores con dictConfig().

Formato de excepción personalizado

Puede haber ocasiones en las que desee personalizar un formato de excepción; por el bien del argumento, digamos que desea exactamente una línea por evento registrado, incluso cuando la información de la excepción está presente. Puede hacer esto con una clase de formateador personalizada, como se muestra en el siguiente ejemplo:

import logging

class OneLineExceptionFormatter(logging.Formatter):
    def formatException(self, exc_info):
        """
        Format an exception so that it prints on a single line.
        """
        result = super().formatException(exc_info)
        return repr(result)  # or format into one line however you want to

    def format(self, record):
        s = super().format(record)
        if record.exc_text:
            s = s.replace('\n', '') + '|'
        return s

def configure_logging():
    fh = logging.FileHandler('output.txt', 'w')
    f = OneLineExceptionFormatter('%(asctime)s|%(levelname)s|%(message)s|',
                                  '%d/%m/%Y %H:%M:%S')
    fh.setFormatter(f)
    root = logging.getLogger()
    root.setLevel(logging.DEBUG)
    root.addHandler(fh)

def main():
    configure_logging()
    logging.info('Sample message')
    try:
        x = 1 / 0
    except ZeroDivisionError as e:
        logging.exception('ZeroDivisionError: %s', e)

if __name__ == '__main__':
    main()

Cuando se ejecuta, esto produce un archivo con exactamente dos líneas:

28/01/2015 07:21:23|INFO|Sample message|
28/01/2015 07:21:23|ERROR|ZeroDivisionError: integer division or modulo by zero|'Traceback (most recent call last):\n  File "logtest7.py", line 30, in main\n    x = 1 / 0\nZeroDivisionError: integer division or modulo by zero'|

Si bien el tratamiento anterior es simplista, señala el camino hacia cómo se puede formatear la información de excepción a su gusto. El módulo traceback puede resultar útil para necesidades más especializadas.

Mensajes de logging hablantes

Puede haber situaciones en las que sea deseable que los mensajes de logging se presenten en un formato audible en lugar de visible. Esto es fácil de hacer si tiene la funcionalidad de texto a voz (TTS por sus siglas en inglés) disponible en su sistema, incluso si no tiene un binding Python. La mayoría de los sistemas TTS tienen un programa de línea de comandos que puede ejecutar, y esto puede invocarse desde un gestor usando subprocess. Aquí se asume que los programas de línea de comando TTS no esperarán interactuar con los usuarios o tardarán mucho en completarse, y que la frecuencia de los mensajes registrados no será tan alta como para inundar al usuario con mensajes, y que es aceptable que los mensajes se reproducen uno a la vez en lugar de todos al mismo tiempo. La implementación de ejemplo a continuación espera a que se pronuncie un mensaje antes de que se procese el siguiente, y esto puede hacer que otros gestores se mantengan esperando. Aquí hay un breve ejemplo que muestra el enfoque, que asume que el paquete TTS espeak está disponible:

import logging
import subprocess
import sys

class TTSHandler(logging.Handler):
    def emit(self, record):
        msg = self.format(record)
        # Speak slowly in a female English voice
        cmd = ['espeak', '-s150', '-ven+f3', msg]
        p = subprocess.Popen(cmd, stdout=subprocess.PIPE,
                             stderr=subprocess.STDOUT)
        # wait for the program to finish
        p.communicate()

def configure_logging():
    h = TTSHandler()
    root = logging.getLogger()
    root.addHandler(h)
    # the default formatter just returns the message
    root.setLevel(logging.DEBUG)

def main():
    logging.info('Hello')
    logging.debug('Goodbye')

if __name__ == '__main__':
    configure_logging()
    sys.exit(main())

Cuando se ejecute, este script debería decir «Hola» y luego «Adiós» con voz femenina.

El enfoque anterior puede, por supuesto, adaptarse a otros sistemas TTS e incluso a otros sistemas que pueden procesar mensajes a través de programas externos ejecutados desde una línea de comando.

Almacenamiento en búfer de mensajes de logging y su salida condicional

Puede haber situaciones en las que desee registrar mensajes en un área temporal y solo mostrarlos si se produce una determinada condición. Por ejemplo, es posible que desee comenzar a registrar eventos de depuración en una función, y si la función se completa sin errores, no desea saturar el log con la información de depuración recopilada; pero si hay un error, desea toda la información de depuración información así como el error.

Aquí hay un ejemplo que muestra cómo puede hacer esto usando un decorador para sus funciones donde desea que el logging se comporte de esta manera. Hace uso de logging.handlers.MemoryHandler, que permite el almacenamiento en búfer de eventos registrados hasta que se produzca alguna condición, momento en el que los eventos almacenados en búfer se flushed y se pasan a otro gestor (el gestor target) para su procesamiento. De forma predeterminada, el MemoryHandler se vacía cuando su búfer se llena o se ve un evento cuyo nivel es mayor o igual a un umbral especificado. Puede usar esta receta con una subclase más especializada de MemoryHandler si desea un comportamiento de descarga personalizado.

El script de ejemplo tiene una función simple, foo, que recorre todos los niveles de logging, escribiendo en sys.stderr para decir en qué nivel está a punto de loguear y luego registrar un mensaje en ese nivel. Puede pasar un parámetro a foo que, si es verdadero, se registrará en los niveles ERROR y CRITICAL; de lo contrario, solo registrará en los niveles DEBUG, INFO y WARNING.

El script simplemente dispone decorar foo con un decorador que hará el logging condicional que se requiere. El decorador toma un registrador como parámetro y adjunta un gestor de memoria durante la duración de la llamada a la función decorada. El decorador se puede parametrizar adicionalmente utilizando un gestor target, un nivel en el que debe producirse el vaciado y una capacidad para el búfer (número de registros almacenados en búfer). Estos están predeterminados a StreamHandler que escribe en``sys.stderr``, logging.ERROR y 100 respectivamente.

Aquí está el script:

import logging
from logging.handlers import MemoryHandler
import sys

logger = logging.getLogger(__name__)
logger.addHandler(logging.NullHandler())

def log_if_errors(logger, target_handler=None, flush_level=None, capacity=None):
    if target_handler is None:
        target_handler = logging.StreamHandler()
    if flush_level is None:
        flush_level = logging.ERROR
    if capacity is None:
        capacity = 100
    handler = MemoryHandler(capacity, flushLevel=flush_level, target=target_handler)

    def decorator(fn):
        def wrapper(*args, **kwargs):
            logger.addHandler(handler)
            try:
                return fn(*args, **kwargs)
            except Exception:
                logger.exception('call failed')
                raise
            finally:
                super(MemoryHandler, handler).flush()
                logger.removeHandler(handler)
        return wrapper

    return decorator

def write_line(s):
    sys.stderr.write('%s\n' % s)

def foo(fail=False):
    write_line('about to log at DEBUG ...')
    logger.debug('Actually logged at DEBUG')
    write_line('about to log at INFO ...')
    logger.info('Actually logged at INFO')
    write_line('about to log at WARNING ...')
    logger.warning('Actually logged at WARNING')
    if fail:
        write_line('about to log at ERROR ...')
        logger.error('Actually logged at ERROR')
        write_line('about to log at CRITICAL ...')
        logger.critical('Actually logged at CRITICAL')
    return fail

decorated_foo = log_if_errors(logger)(foo)

if __name__ == '__main__':
    logger.setLevel(logging.DEBUG)
    write_line('Calling undecorated foo with False')
    assert not foo(False)
    write_line('Calling undecorated foo with True')
    assert foo(True)
    write_line('Calling decorated foo with False')
    assert not decorated_foo(False)
    write_line('Calling decorated foo with True')
    assert decorated_foo(True)

Cuando se ejecuta este script, se debe observar el siguiente resultado:

Calling undecorated foo with False
about to log at DEBUG ...
about to log at INFO ...
about to log at WARNING ...
Calling undecorated foo with True
about to log at DEBUG ...
about to log at INFO ...
about to log at WARNING ...
about to log at ERROR ...
about to log at CRITICAL ...
Calling decorated foo with False
about to log at DEBUG ...
about to log at INFO ...
about to log at WARNING ...
Calling decorated foo with True
about to log at DEBUG ...
about to log at INFO ...
about to log at WARNING ...
about to log at ERROR ...
Actually logged at DEBUG
Actually logged at INFO
Actually logged at WARNING
Actually logged at ERROR
about to log at CRITICAL ...
Actually logged at CRITICAL

Como puede ver, la salida real de logging solo ocurre cuando se registra un evento cuya gravedad es ERROR o mayor, pero en ese caso, también se registra cualquier evento anterior con una gravedad menor.

Por supuesto, puede utilizar las formas de decoración convencionales:

@log_if_errors(logger)
def foo(fail=False):
    ...

Formateo de horas usando UTC (GMT) a través de la configuración

A veces desea formatear las horas usando UTC, lo que se puede hacer usando una clase como UTCFormatter, como se muestra a continuación:

import logging
import time

class UTCFormatter(logging.Formatter):
    converter = time.gmtime

y luego puede usar el UTCFormatter en su código en lugar de Formatter. Si desea hacer eso a través de la configuración, puede usar la API dictConfig() con un enfoque ilustrado por el siguiente ejemplo completo:

import logging
import logging.config
import time

class UTCFormatter(logging.Formatter):
    converter = time.gmtime

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        'utc': {
            '()': UTCFormatter,
            'format': '%(asctime)s %(message)s',
        },
        'local': {
            'format': '%(asctime)s %(message)s',
        }
    },
    'handlers': {
        'console1': {
            'class': 'logging.StreamHandler',
            'formatter': 'utc',
        },
        'console2': {
            'class': 'logging.StreamHandler',
            'formatter': 'local',
        },
    },
    'root': {
        'handlers': ['console1', 'console2'],
   }
}

if __name__ == '__main__':
    logging.config.dictConfig(LOGGING)
    logging.warning('The local time is %s', time.asctime())

Cuando se ejecuta este script, debería imprimir algo como:

2015-10-17 12:53:29,501 The local time is Sat Oct 17 13:53:29 2015
2015-10-17 13:53:29,501 The local time is Sat Oct 17 13:53:29 2015

mostrando cómo se formatea la hora como hora local y UTC, una para cada gestor.

Usar un administrador de contexto para logging selectivo

Hay ocasiones en las que sería útil cambiar temporalmente la configuración de logging y revertir esto después de hacer algo. Para ello, un administrador de contexto es la forma más obvia de guardar y restaurar el contexto de logging. Aquí hay un ejemplo simple de un administrador de contexto de este tipo, que le permite cambiar opcionalmente el nivel de logging y agregar un gestor de logging exclusivamente en el alcance del administrador de contexto:

import logging
import sys

class LoggingContext:
    def __init__(self, logger, level=None, handler=None, close=True):
        self.logger = logger
        self.level = level
        self.handler = handler
        self.close = close

    def __enter__(self):
        if self.level is not None:
            self.old_level = self.logger.level
            self.logger.setLevel(self.level)
        if self.handler:
            self.logger.addHandler(self.handler)

    def __exit__(self, et, ev, tb):
        if self.level is not None:
            self.logger.setLevel(self.old_level)
        if self.handler:
            self.logger.removeHandler(self.handler)
        if self.handler and self.close:
            self.handler.close()
        # implicit return of None => don't swallow exceptions

Si especifica un valor de nivel, el nivel del registrador se establece en ese valor en el alcance del bloque with cubierto por el administrador de contexto. Si especifica un gestor, se agrega al registrador al entrar al bloque y se elimina al salir del bloque. También puede pedirle al administrador que cierre el gestor por usted al salir del bloque si ya no lo necesita.

Para ilustrar cómo funciona, podemos agregar el siguiente bloque de código al anterior:

if __name__ == '__main__':
    logger = logging.getLogger('foo')
    logger.addHandler(logging.StreamHandler())
    logger.setLevel(logging.INFO)
    logger.info('1. This should appear just once on stderr.')
    logger.debug('2. This should not appear.')
    with LoggingContext(logger, level=logging.DEBUG):
        logger.debug('3. This should appear once on stderr.')
    logger.debug('4. This should not appear.')
    h = logging.StreamHandler(sys.stdout)
    with LoggingContext(logger, level=logging.DEBUG, handler=h, close=True):
        logger.debug('5. This should appear twice - once on stderr and once on stdout.')
    logger.info('6. This should appear just once on stderr.')
    logger.debug('7. This should not appear.')

Inicialmente configuramos el nivel del registrador en INFO, por lo que aparece el mensaje #1 y el mensaje #2 no. Luego cambiamos el nivel a DEBUG temporalmente en el siguiente bloque with, y aparece el mensaje #3. Una vez que se sale del bloque, el nivel del registrador se restaura a INFO y, por lo tanto, el mensaje #4 no aparece. En el siguiente bloque with, configuramos el nivel en DEBUG nuevamente, pero también agregamos un gestor que escribe en sys.stdout. Por lo tanto, el mensaje #5 aparece dos veces en la consola (una vez a través de stderr y una vez a través de stdout). Después de la finalización de la declaración with, se vuelve al estado anterior, por lo que aparece el mensaje #6 (como el mensaje #1) mientras que el mensaje #7 no (como el mensaje #2).

Si ejecutamos el script resultante, el resultado es el siguiente:

$ python logctx.py
1. This should appear just once on stderr.
3. This should appear once on stderr.
5. This should appear twice - once on stderr and once on stdout.
5. This should appear twice - once on stderr and once on stdout.
6. This should appear just once on stderr.

Si lo ejecutamos de nuevo, pero dirigimos stderr a /dev/null, vemos lo siguiente, que es el único mensaje escrito en stdout:

$ python logctx.py 2>/dev/null
5. This should appear twice - once on stderr and once on stdout.

Una vez más, pero canalizando stdout a /dev/null, obtenemos:

$ python logctx.py >/dev/null
1. This should appear just once on stderr.
3. This should appear once on stderr.
5. This should appear twice - once on stderr and once on stdout.
6. This should appear just once on stderr.

En este caso, el mensaje #5 impreso en stdout no aparece, como se esperaba.

Por supuesto, el enfoque descrito aquí puede generalizarse, por ejemplo, para adjuntar filtros de logging temporalmente. Tenga en cuenta que el código anterior funciona tanto en Python 2 como en Python 3.

Una plantilla de inicio de aplicación CLI

Aquí hay un ejemplo que muestra cómo puede:

Utilizar un nivel de logging basado en argumentos de la línea de comandos

Enviar a varios subcomandos en archivos separados, todos registrando en el mismo nivel de forma coherente

Utilizar una configuración mínima y sencilla

Supongamos que tenemos una aplicación de línea de comandos cuyo trabajo es detener, iniciar o reiniciar algunos servicios. Esto podría organizarse con fines ilustrativos como un archivo app.py que es el script principal de la aplicación, con comandos individuales implementados en start.py, stop.py y restart.py. Supongamos además que queremos controlar la verbosidad de la aplicación a través de un argumento de línea de comandos, por defecto en logging.INFO. Aquí hay una forma en que se podría escribir app.py:

import argparse
import importlib
import logging
import os
import sys

def main(args=None):
    scriptname = os.path.basename(__file__)
    parser = argparse.ArgumentParser(scriptname)
    levels = ('DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL')
    parser.add_argument('--log-level', default='INFO', choices=levels)
    subparsers = parser.add_subparsers(dest='command',
                                       help='Available commands:')
    start_cmd = subparsers.add_parser('start', help='Start a service')
    start_cmd.add_argument('name', metavar='NAME',
                           help='Name of service to start')
    stop_cmd = subparsers.add_parser('stop',
                                     help='Stop one or more services')
    stop_cmd.add_argument('names', metavar='NAME', nargs='+',
                          help='Name of service to stop')
    restart_cmd = subparsers.add_parser('restart',
                                        help='Restart one or more services')
    restart_cmd.add_argument('names', metavar='NAME', nargs='+',
                             help='Name of service to restart')
    options = parser.parse_args()
    # the code to dispatch commands could all be in this file. For the purposes
    # of illustration only, we implement each command in a separate module.
    try:
        mod = importlib.import_module(options.command)
        cmd = getattr(mod, 'command')
    except (ImportError, AttributeError):
        print('Unable to find the code for command \'%s\'' % options.command)
        return 1
    # Could get fancy here and load configuration from file or dictionary
    logging.basicConfig(level=options.log_level,
                        format='%(levelname)s %(name)s %(message)s')
    cmd(options)

if __name__ == '__main__':
    sys.exit(main())

Y los comandos start, stop y reiniciar se pueden implementar en módulos separados, como para iniciar:

# start.py
import logging

logger = logging.getLogger(__name__)

def command(options):
    logger.debug('About to start %s', options.name)
    # actually do the command processing here ...
    logger.info('Started the \'%s\' service.', options.name)

y así para detener:

# stop.py
import logging

logger = logging.getLogger(__name__)

def command(options):
    n = len(options.names)
    if n == 1:
        plural = ''
        services = '\'%s\'' % options.names[0]
    else:
        plural = 's'
        services = ', '.join('\'%s\'' % name for name in options.names)
        i = services.rfind(', ')
        services = services[:i] + ' and ' + services[i + 2:]
    logger.debug('About to stop %s', services)
    # actually do the command processing here ...
    logger.info('Stopped the %s service%s.', services, plural)

y de manera similar para reiniciar:

# restart.py
import logging

logger = logging.getLogger(__name__)

def command(options):
    n = len(options.names)
    if n == 1:
        plural = ''
        services = '\'%s\'' % options.names[0]
    else:
        plural = 's'
        services = ', '.join('\'%s\'' % name for name in options.names)
        i = services.rfind(', ')
        services = services[:i] + ' and ' + services[i + 2:]
    logger.debug('About to restart %s', services)
    # actually do the command processing here ...
    logger.info('Restarted the %s service%s.', services, plural)

Si ejecutamos esta aplicación con el nivel de log predeterminado, obtenemos un resultado como este:

$ python app.py start foo
INFO start Started the 'foo' service.

$ python app.py stop foo bar
INFO stop Stopped the 'foo' and 'bar' services.

$ python app.py restart foo bar baz
INFO restart Restarted the 'foo', 'bar' and 'baz' services.

La primera palabra es el nivel de logging y la segunda palabra es el nombre del módulo o paquete del lugar donde se registró el evento.

Si cambiamos el nivel de logging, podemos cambiar la información enviada al log. Por ejemplo, si queremos más información:

$ python app.py --log-level DEBUG start foo
DEBUG start About to start foo
INFO start Started the 'foo' service.

$ python app.py --log-level DEBUG stop foo bar
DEBUG stop About to stop 'foo' and 'bar'
INFO stop Stopped the 'foo' and 'bar' services.

$ python app.py --log-level DEBUG restart foo bar baz
DEBUG restart About to restart 'foo', 'bar' and 'baz'
INFO restart Restarted the 'foo', 'bar' and 'baz' services.

Y si queremos menos:

$ python app.py --log-level WARNING start foo
$ python app.py --log-level WARNING stop foo bar
$ python app.py --log-level WARNING restart foo bar baz

En este caso, los comandos no imprimen nada en la consola, ya que no registran nada en el nivel de WARNING o superior.

Una GUI de Qt para logging

Una pregunta que surge de vez en cuando es sobre cómo loggear en una aplicación GUI. El framework Qt <https://www.qt.io/> _ es un framework popular multiplataforma con bindings de Python que usan PySide2 <https://pypi.org/project/PySide2/>`_ o librerías PyQt5 [https://pypi.org/project/PyQt5/] .

El siguiente ejemplo muestra cómo iniciar sesión en una GUI de Qt. Esto introduce una clase simple QtHandler que toma un invocable, que debería ser un slot en el hilo principal que realiza actualizaciones de la GUI. También se crea un hilo de trabajo para mostrar cómo puede iniciar sesión en la GUI tanto desde la propia interfaz de usuario (a través de un botón para el logging manual) como desde un hilo de trabajo que trabaja en segundo plano (aquí, simplemente registrando mensajes en niveles aleatorios con aleatorio breves retrasos intermedios).

El hilo worker se implementa usando la clase QThread de Qt en lugar del módulo threading, ya que hay circunstancias en las que uno tiene que usar QThread, que ofrece una mejor integración con otros componentes Qt.

El código debería funcionar con versiones recientes de PySide2 o PyQt5. Debería poder adaptar el enfoque a versiones anteriores de Qt. Consulte los comentarios en el fragmento de código para obtener información más detallada.

import datetime
import logging
import random
import sys
import time

# Deal with minor differences between PySide2 and PyQt5
try:
    from PySide2 import QtCore, QtGui, QtWidgets
    Signal = QtCore.Signal
    Slot = QtCore.Slot
except ImportError:
    from PyQt5 import QtCore, QtGui, QtWidgets
    Signal = QtCore.pyqtSignal
    Slot = QtCore.pyqtSlot

logger = logging.getLogger(__name__)

#
# Signals need to be contained in a QObject or subclass in order to be correctly
# initialized.
#
class Signaller(QtCore.QObject):
    signal = Signal(str, logging.LogRecord)

#
# Output to a Qt GUI is only supposed to happen on the main thread. So, this
# handler is designed to take a slot function which is set up to run in the main
# thread. In this example, the function takes a string argument which is a
# formatted log message, and the log record which generated it. The formatted
# string is just a convenience - you could format a string for output any way
# you like in the slot function itself.
#
# You specify the slot function to do whatever GUI updates you want. The handler
# doesn't know or care about specific UI elements.
#
class QtHandler(logging.Handler):
    def __init__(self, slotfunc, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.signaller = Signaller()
        self.signaller.signal.connect(slotfunc)

    def emit(self, record):
        s = self.format(record)
        self.signaller.signal.emit(s, record)

#
# This example uses QThreads, which means that the threads at the Python level
# are named something like "Dummy-1". The function below gets the Qt name of the
# current thread.
#
def ctname():
    return QtCore.QThread.currentThread().objectName()

#
# Used to generate random levels for logging.
#
LEVELS = (logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR,
          logging.CRITICAL)

#
# This worker class represents work that is done in a thread separate to the
# main thread. The way the thread is kicked off to do work is via a button press
# that connects to a slot in the worker.
#
# Because the default threadName value in the LogRecord isn't much use, we add
# a qThreadName which contains the QThread name as computed above, and pass that
# value in an "extra" dictionary which is used to update the LogRecord with the
# QThread name.
#
# This example worker just outputs messages sequentially, interspersed with
# random delays of the order of a few seconds.
#
class Worker(QtCore.QObject):
    @Slot()
    def start(self):
        extra = {'qThreadName': ctname() }
        logger.debug('Started work', extra=extra)
        i = 1
        # Let the thread run until interrupted. This allows reasonably clean
        # thread termination.
        while not QtCore.QThread.currentThread().isInterruptionRequested():
            delay = 0.5 + random.random() * 2
            time.sleep(delay)
            level = random.choice(LEVELS)
            logger.log(level, 'Message after delay of %3.1f: %d', delay, i, extra=extra)
            i += 1

#
# Implement a simple UI for this cookbook example. This contains:
#
# * A read-only text edit window which holds formatted log messages
# * A button to start work and log stuff in a separate thread
# * A button to log something from the main thread
# * A button to clear the log window
#
class Window(QtWidgets.QWidget):

    COLORS = {
        logging.DEBUG: 'black',
        logging.INFO: 'blue',
        logging.WARNING: 'orange',
        logging.ERROR: 'red',
        logging.CRITICAL: 'purple',
    }

    def __init__(self, app):
        super().__init__()
        self.app = app
        self.textedit = te = QtWidgets.QPlainTextEdit(self)
        # Set whatever the default monospace font is for the platform
        f = QtGui.QFont('nosuchfont')
        f.setStyleHint(f.Monospace)
        te.setFont(f)
        te.setReadOnly(True)
        PB = QtWidgets.QPushButton
        self.work_button = PB('Start background work', self)
        self.log_button = PB('Log a message at a random level', self)
        self.clear_button = PB('Clear log window', self)
        self.handler = h = QtHandler(self.update_status)
        # Remember to use qThreadName rather than threadName in the format string.
        fs = '%(asctime)s %(qThreadName)-12s %(levelname)-8s %(message)s'
        formatter = logging.Formatter(fs)
        h.setFormatter(formatter)
        logger.addHandler(h)
        # Set up to terminate the QThread when we exit
        app.aboutToQuit.connect(self.force_quit)

        # Lay out all the widgets
        layout = QtWidgets.QVBoxLayout(self)
        layout.addWidget(te)
        layout.addWidget(self.work_button)
        layout.addWidget(self.log_button)
        layout.addWidget(self.clear_button)
        self.setFixedSize(900, 400)

        # Connect the non-worker slots and signals
        self.log_button.clicked.connect(self.manual_update)
        self.clear_button.clicked.connect(self.clear_display)

        # Start a new worker thread and connect the slots for the worker
        self.start_thread()
        self.work_button.clicked.connect(self.worker.start)
        # Once started, the button should be disabled
        self.work_button.clicked.connect(lambda : self.work_button.setEnabled(False))

    def start_thread(self):
        self.worker = Worker()
        self.worker_thread = QtCore.QThread()
        self.worker.setObjectName('Worker')
        self.worker_thread.setObjectName('WorkerThread')  # for qThreadName
        self.worker.moveToThread(self.worker_thread)
        # This will start an event loop in the worker thread
        self.worker_thread.start()

    def kill_thread(self):
        # Just tell the worker to stop, then tell it to quit and wait for that
        # to happen
        self.worker_thread.requestInterruption()
        if self.worker_thread.isRunning():
            self.worker_thread.quit()
            self.worker_thread.wait()
        else:
            print('worker has already exited.')

    def force_quit(self):
        # For use when the window is closed
        if self.worker_thread.isRunning():
            self.kill_thread()

    # The functions below update the UI and run in the main thread because
    # that's where the slots are set up

    @Slot(str, logging.LogRecord)
    def update_status(self, status, record):
        color = self.COLORS.get(record.levelno, 'black')
        s = '<pre><font color="%s">%s</font></pre>' % (color, status)
        self.textedit.appendHtml(s)

    @Slot()
    def manual_update(self):
        # This function uses the formatted message passed in, but also uses
        # information from the record to format the message in an appropriate
        # color according to its severity (level).
        level = random.choice(LEVELS)
        extra = {'qThreadName': ctname() }
        logger.log(level, 'Manually logged!', extra=extra)

    @Slot()
    def clear_display(self):
        self.textedit.clear()

def main():
    QtCore.QThread.currentThread().setObjectName('MainThread')
    logging.getLogger().setLevel(logging.DEBUG)
    app = QtWidgets.QApplication(sys.argv)
    example = Window(app)
    example.show()
    sys.exit(app.exec_())

if __name__=='__main__':
    main()

Patterns to avoid

Although the preceding sections have described ways of doing things you might need to do or deal with, it is worth mentioning some usage patterns which are unhelpful, and which should therefore be avoided in most cases. The following sections are in no particular order.

Opening the same log file multiple times

On Windows, you will generally not be able to open the same file multiple times as this will lead to a «file is in use by another process» error. However, on POSIX platforms you’ll not get any errors if you open the same file multiple times. This could be done accidentally, for example by:

Adding a file handler more than once which references the same file (e.g. by a copy/paste/forget-to-change error).

Opening two files that look different, as they have different names, but are the same because one is a symbolic link to the other.

Forking a process, following which both parent and child have a reference to the same file. This might be through use of the multiprocessing module, for example.

Opening a file multiple times might appear to work most of the time, but can lead to a number of problems in practice:

Logging output can be garbled because multiple threads or processes try to write to the same file. Although logging guards against concurrent use of the same handler instance by multiple threads, there is no such protection if concurrent writes are attempted by two different threads using two different handler instances which happen to point to the same file.

An attempt to delete a file (e.g. during file rotation) silently fails, because there is another reference pointing to it. This can lead to confusion and wasted debugging time - log entries end up in unexpected places, or are lost altogether.

Use the techniques outlined in Logging a un sólo archivo desde múltiples procesos to circumvent such issues.

Using loggers as attributes in a class or passing them as parameters

While there might be unusual cases where you’ll need to do this, in general there is no point because loggers are singletons. Code can always access a given logger instance by name using logging.getLogger(name), so passing instances around and holding them as instance attributes is pointless. Note that in other languages such as Java and C#, loggers are often static class attributes. However, this pattern doesn’t make sense in Python, where the module (and not the class) is the unit of software decomposition.

Adding handlers other than NullHandler to a logger in a library

Configuring logging by adding handlers, formatters and filters is the responsibility of the application developer, not the library developer. If you are maintaining a library, ensure that you don’t add handlers to any of your loggers other than a NullHandler instance.

Creating a lot of loggers

Loggers are singletons that are never freed during a script execution, and so creating lots of loggers will use up memory which can’t then be freed. Rather than create a logger per e.g. file processed or network connection made, use the existing mechanisms for passing contextual information into your logs and restrict the loggers created to those describing areas within your application (generally modules, but occasionally slightly more fine-grained than that).

Expresiones regulares COMOS (HOWTO)

Autor

A.M. Kuchling <amk@amk.ca>

Resumen

Este documento es un tutorial de introducción al uso de expresiones regulares en Python con el módulo re. Proporciona una introducción más apacible que la sección correspondiente en la Referencia de la Biblioteca.

Introducción

Las expresiones regulares (llamadas RE, o regex, o patrones de regex) son esencialmente en un lenguaje de programación diminuto y altamente especializado incrustado dentro de Python y disponible a través del módulo re. Usando este pequeño lenguaje, especificas las reglas para el conjunto de cadenas de caracteres posibles que deseas hacer coincidir; este conjunto puede contener frases en inglés, o direcciones de correo electrónico, o comandos TeX, o cualquier cosa que desee. A continuación, puede hacer preguntas como «¿Coincide esta cadena con el patrón?» o «¿Hay alguna coincidencia con el patrón en alguna parte de esta cadena?». También puede utilizar RE para modificar una cadena de caracteres o dividirla de varias formas.

Los patrones de expresiones regulares se compilan en una serie de códigos de bytes que luego son ejecutados por un motor de coincidencia escrito en C. Para un uso avanzado, puede ser necesario prestar mucha atención a cómo el motor ejecutará una RE dado y escribir la RE en un de cierta manera para producir un código de bytes que se ejecute más rápido. La optimización no se trata en este documento, porque requiere que tenga un buen conocimiento de los componentes internos del motor de coincidencia.

El lenguaje de expresiones regulares es relativamente pequeño y restringido, por lo que no todas las posibles tareas de procesamiento de cadenas de caracteres se pueden realizar utilizando expresiones regulares. También hay tareas que se pueden hacer con expresiones regulares, pero las expresiones resultan ser muy complicadas. En estos casos, es mejor que escriba código Python para realizar el procesamiento; Si bien el código Python será más lento que una expresión regular elaborada, probablemente también será más comprensible.

Patrones simples

Comenzaremos aprendiendo sobre las expresiones regulares más simples posibles. Dado que las expresiones regulares se utilizan para operar en cadenas de caracteres, comenzaremos con la tarea más común: hacer coincidir caracteres.

Para obtener una explicación detallada de la informática que subyace a las expresiones regulares (autómatas finitos deterministas y no deterministas), puede consultar casi cualquier libro de texto sobre la escritura de compiladores.

Coincidencia de Caracteres (Matching Characters)

La mayoría de letras y caracteres simplemente coincidirán. Por ejemplo, la expresión regular test coincidirá exactamente con la cadena test. (Puede habilitar un modo que no distinga entre mayúsculas y minúsculas que permitiría que este RE coincida con test o TEST también; más sobre esto más adelante.)

Hay excepciones a esta regla; algunos caracteres son especiales metacharacters, y no coinciden. En cambio, señalan que debe coincidir con algo fuera de lo común, o afectan otras partes de la RE repitiéndolos o cambiando su significado. Gran parte de este documento está dedicado a discutir varios metacarácteres y lo que hacen.

Aquí hay una lista completa de los metacarácteres; sus significados se discutirán en el resto de este COMO (HOWTO).

. ^ $ * + ? { } [ ] \ | ( )

Los primeros metacarácteres que veremos son [ and ]. Se utilizan para especificar una clase de carácter, que es un conjunto de caracteres que desea hacer coincidir. Los caracteres se pueden enumerar individualmente, o se puede indicar un rango de caracteres dando dos caracteres y separándolos con un '-'. Por ejemplo, [abc] coincidirá con cualquiera de los caracteres a, b o c; esto es lo mismo que [a-c], que usa un rango para expresar el mismo conjunto de caracteres. Si quisiera hacer coincidir solo letras minúsculas, su RE sería [a-c].

Metacharacters (except \) are not active inside classes. For example, [akm$] will match any of the characters 'a', 'k', 'm', or '$'; '$' is usually a metacharacter, but inside a character class it’s stripped of its special nature.

Puede hacer coincidir los caracteres que no figuran en la clase mediante el conjunto complementing. Esto se indica mediante la inclusión de un '^' como primer carácter de la clase. Por ejemplo, [^5] coincidirá con cualquier carácter excepto con '5'. Si el símbolo de intercalación aparece en otra parte de una clase de caracter, no tiene un significado especial. Por ejemplo: [5^] `` coincidirá con un ``'5' o un '^'.

Quizás el metacarácter más importante es la barra invertida, \. Al igual que en los literales de cadena de Python, la barra invertida puede ir seguida de varios caracteres para señalar varias secuencias especiales. También se usa para escapar de todos los metacarácteres, de modo que aún pueda emparejarlos en patrones; por ejemplo, si necesita hacer coincidir un [ o \, puede precederlos con una barra invertida para eliminar su significado especial: \[ o \\.

Algunas de las secuencias especiales que comienzan con '\' representan conjuntos predefinidos de caracteres que a menudo son útiles, como el conjunto de dígitos, el conjunto de letras o el conjunto de cualquier cosa que no sea un espacio en blanco.

Tomemos un ejemplo: \w coincide con cualquier carácter alfanumérico. Si el patrón de expresiones regulares se expresa en bytes, esto es equivalente a la clase [a-zA-Z0-9_]. Si el patrón de expresiones regulares es una cadena de caracteres, \w coincidirá con todos los caracteres marcados como letras en la base de datos Unicode proporcionada por el módulo unicodedata. Puede usar la definición más restringida de \w en un patrón de cadena proporcionando el indicador re.ASCII al compilar la expresión regular.

La siguiente lista de secuencias especiales no está completa. Para obtener una lista completa de secuencias y definiciones de clases expandidas para patrones de cadenas Unicode, consulte la última parte de Regular Expression Syntax en la referencia de la biblioteca estándar. En general, las versiones Unicode coinciden con cualquier carácter que esté en la categoría apropiada en la base de datos Unicode.

\d

Coincide con cualquier dígito decimal; esto es equivalente a la clase [0-9].

\D

Coincide con cualquier carácter que no sea un dígito; esto es equivalente a la clase [^0-9].

\s

Coincide con cualquier carácter de espacio en blanco; esto es equivalente a la clase [ \t\n\r\f\v].

\S

Coincide con cualquier carácter que no sea un espacio en blanco; esto es equivalente a la clase [^ \t\n\r\f\v].

\w

Coincide con cualquier carácter alfanumérico; esto es equivalente a la clase [a-zA-Z0-9_].

\W

Coincide con cualquier carácter no alfanumérico; esto es equivalente a la clase [^a-zA-Z0-9_].

Estas secuencias se pueden incluir dentro de una clase de carácter. Por ejemplo, [\s,.] es una clase de carácter que coincidirá con cualquier carácter de espacio en blanco, o ',' o '.'.

El metacarácter final en esta sección es .. Coincide con cualquier cosa excepto un carácter de nueva línea, y hay un modo alternativo (re.DOTALL) donde coincidirá incluso con una nueva línea. . se usa a menudo cuando se desea hacer coincidir «cualquier carácter».

Repitiendo cosas

Ser capaz de hacer coincidir diferentes conjuntos de caracteres es lo primero que pueden hacer las expresiones regulares que ya no es posible con los métodos disponibles en cadenas de caracteres. Sin embargo, si esa fuera la única capacidad adicional de las expresiones regulares, no serían un gran avance. Otra capacidad es que puede especificar que partes de la RE deben repetirse un cierto número de veces.

El primer metacarácter para repetir cosas que veremos es *. * no coincide con el carácter literal '*'; en cambio, especifica que el carácter anterior puede coincidir cero o más veces, en lugar de exactamente una vez.

Por ejemplo, ca*t coincidirá con 'ct' (0 'a' caracteres), 'cat' (1 'a'), 'caaat' (3 'a' caracteres), etc.

Las repeticiones como * son greedy; al repetir una RE, el motor de emparejamiento intentará repetirlo tantas veces como sea posible. Si las partes posteriores del patrón no coinciden, el motor de coincidencia hará una copia de seguridad y volverá a intentarlo con menos repeticiones.

Un ejemplo paso a paso hará que esto sea más obvio. Consideremos la expresión a[bcd]*b. Esto coincide con la letra 'a', cero o más letras de la clase [bcd], y finalmente termina con una 'b'. Ahora imagina hacer coincidir este RE con la cadena de caracteres 'abcbd'.

Pasos

Coincidencias

Explicación

1

a

La a en las RE coincide.

2

abcbd

El motor coincide con [bcd]*, yendo tan lejos como puede, que es hasta el final de la cadena de caracteres.

3

Failure

El motor intenta hacer coincidir b, pero la posición actual está al final de la cadena de caracteres, por lo que falla.

4

abcb

Hace una copia de seguridad para que [bcd]* coincida con un carácter menos.

5

Failure

Intente b de nuevo, pero la posición actual está en el último caracter, que es un 'd'.

6

abc

Haga una copia de seguridad de nuevo, de modo que [bcd]* solo coincida con bc.

6

abcb

Intente b de nuevo. Esta vez, el carácter en la posición actual es 'b', por lo que tiene éxito.

Se ha alcanzado el final de la RE y ha coincidido con 'abcb'. Esto demuestra cómo el motor de coincidencias llega tan lejos como puede al principio, y si no se encuentra ninguna coincidencia, retrocederá progresivamente y volverá a intentar de la RE una y otra vez. Hará una copia de seguridad hasta que haya probado cero coincidencias para [bcd]*, y si eso falla posteriormente, el motor concluirá que la cadena no coincide con la RE en absoluto.

Otro metacarácter que se repite es +, que coincide una o más veces. Preste especial atención a la diferencia entre * and +; coincide con cero o más veces, por lo que cualquier cosa que se repita puede no estar presente en absoluto, mientras que + requiere al menos one aparición. Para usar un ejemplo similar, 'cat' (1 'a'), 'caaat' (3 'a's), pero no coincidirá con 'ct'.

Hay dos calificadores más que se repiten. El carácter de signo de interrogación, ?, Coincide una vez o cero veces; puede pensar en ello como si marcara algo como opcional. Por ejemplo, home-?brew coincide con 'homebrew' o 'home-brew'.

El calificador repetido más complicado es {m,n}, donde m y n son enteros decimales. Este calificador significa que debe haber al menos m repeticiones y como máximo n. Por ejemplo, a/{1,3}b coincidirá con``”a/b”, ``'a//b', and 'a///b'. No coincidirá con `` “ab” “, que no tiene barras, ni con 'a////b', que tiene cuatro.

Puede omitir m o n; en ese caso, se asume un valor razonable para el valor faltante. Omitir m se interpreta como un límite inferior de 0, mientras que omitir n da como resultado un límite superior de infinito.

Los lectores de una inclinación reduccionista pueden notar que los otros tres calificativos pueden expresarse usando esta notación. {0,} es lo mismo que *, {1,} es equivalente a +, y {0,1} es lo mismo que ?. Es mejor usar *, +, o ? cuando pueda, simplemente porque son más cortos y fáciles de leer.

Usando Expresiones Regulares

Ahora que hemos visto algunas expresiones regulares simples, ¿cómo las usamos realmente en Python? El módulo re proporciona una interfaz para el motor de expresiones regulares, lo que le permite compilar RE en objetos y luego realizar coincidencias con ellos.

Compilando Expresiones regulares

Las expresiones regulares se compilan en objetos de patrón, que tienen métodos para diversas operaciones, como buscar coincidencias de patrones o realizar sustituciones de cadenas de caracteres.

>>> import re
>>> p = re.compile('ab*')
>>> p
re.compile('ab*')

re.compile() también acepta un argumento opcional flags, usado para habilitar varias características especiales y variaciones de sintaxis. Repasaremos las configuraciones disponibles más adelante, pero por ahora un solo ejemplo servirá:

>>> p = re.compile('ab*', re.IGNORECASE)

La RE se pasa a re.compile() como una cadena de caracteres. Las RE se manejan como cadenas de caracteres porque las expresiones regulares no son parte del lenguaje central de Python y no se creó una sintaxis especial para expresarlas. (Hay aplicaciones que no necesitan RE en absoluto, por lo que no hay necesidad de aumentar la especificación del lenguaje incluyéndolas). En cambio, el módulo re es simplemente un módulo de extensión C incluido en Python, al igual que los módulos socket o zlib.

Poner RE en cadenas de caracteres mantiene el lenguaje Python más simple, pero tiene una desventaja que es el tema de la siguiente sección.

La plaga de la barra invertida (The Backslash Plague)

Como se indicó anteriormente, las expresiones regulares usan el carácter de barra invertida ('\') para indicar formas especiales o para permitir que se usen caracteres especiales sin invocar su significado especial. Esto entra en conflicto con el uso de Python del mismo carácter para el mismo propósito en cadenas literales.

Supongamos que desea escribir una RE que coincida con la cadena de caracteres \section, que podría encontrarse en un archivo LaTeX. Para averiguar qué escribir en el código del programa, comience con la cadena deseada para que coincida. A continuación, debe escapar de las barras invertidas y otros metacarácteres precediéndolos con una barra invertida, lo que da como resultado la cadena \\section. La cadena resultante que debe pasarse a re.compile() debe ser \\section. Sin embargo, para expresar esto como una cadena literal de Python, ambas barras invertidas deben escaparse nuevamente.

Caracteres

Explicación

\section

Cadena de texto que debe coincidir

\\section

Barra invertida de escape para re.compile()

"\\\\section"

Barra invertida de escape para un literal de cadena de caracteres

En resumen, para hacer coincidir una barra invertida literal, uno tiene que escribir '\\\\' como la cadena RE, porque la expresión regular debe ser \\, y cada barra invertida debe expresarse como \\ dentro de un literal de cadena Python normal. En las RE que presentan barras invertidas repetidamente, esto genera muchas barras invertidas repetidas y dificulta la comprensión de las cadenas resultantes.

La solución es utilizar la notación de cadena de caracteres sin formato de Python para expresiones regulares; las barras invertidas no se manejan de ninguna manera especial en una cadena literal con el prefijo 'r', por lo que r"\n" es una cadena de dos caracteres que contiene '\' y 'n', mientras que "\n" es una cadena de un carácter que contiene una nueva línea. Las expresiones regulares a menudo se escribirán en código Python utilizando esta notación de cadena sin formato.

Además, las secuencias de escape especiales que son válidas en expresiones regulares, pero no válidas como literales de cadena de Python, ahora dan como resultado DeprecationWarning y eventualmente se convertirán en SyntaxError, lo que significa que las secuencias no serán válidas. si no se utiliza la notación de cadena sin formato o el escape de las barras invertidas.

Cadena de caracteres regulares

Cadena de caracteres crudas (Raw string)

"ab*"

r"ab*"

"\\\\section"

r"\\section"

"\\w+\\s+\\1"

r"\w+\s+\1"

Realizando coincidencias

Una vez que tiene un objeto que representa una expresión regular compilada, ¿qué hace con él? Los objetos de patrón tienen varios métodos y atributos. Aquí solo se cubrirán los más importantes; consulte los documentos re para obtener una lista completa.

Método/atributo

Objetivo

match()

Determina si la RE coincide con el comienzo de la cadena de caracteres.

search()

Escanea una cadena, buscando cualquier ubicación donde coincida este RE.

findall()

Encuentra todas las subcadenas de caracteres donde coincide la RE y las retorna como una lista.

finditer()

Encuentra todas las subcadenas donde la RE coincide y las retorna como un término iterado iterator.

match() y search() retornan None si la coincidencia no puede ser encontrada. Si tienen éxito, se retorna una instancia match object, que contiene información sobre la coincidencia: dónde comienza y termina, la subcadena de caracteres con la que coincidió, y más.

Puede aprender sobre esto experimentando interactivamente con el módulo re. Si tiene tkinter disponible, también puede consultar Tools/demo/redemo.py [https://github.com/python/cpython/tree/3.9/Tools/demo/redemo.py], un programa de demostración incluido con la distribución de Python. Le permite ingresar RE y cadenas de caracteres, y muestra si la RE coincide o falla. redemo.py puede ser bastante útil cuando se intenta depurar una RE complicado.

Este CÓMO (HOWTO) utiliza el intérprete estándar de Python para sus ejemplos. Primero, ejecute el intérprete de Python, importe el módulo re y compile en RE:

>>> import re
>>> p = re.compile('[a-z]+')
>>> p
re.compile('[a-z]+')

Ahora, puede intentar hacer coincidir varias cadenas con la RE [a-z]+. Una cadena de caracteres vacía no debería coincidir en absoluto, ya que + significa que “una o más repeticiones”. match() debería retornar None en este caso, lo que hará que el intérprete no imprima ningún resultado. Puede imprimir explícitamente el resultado de match() para aclarar esto.

>>> p.match("")
>>> print(p.match(""))
None

Ahora, intentémoslo en una cadena de caracteres que debería coincidir, como tempo.En este caso , match() retornará un match object, por lo que debe almacenar el resultado en una variable para su posterior uso.

>>> m = p.match('tempo')
>>> m
<re.Match object; span=(0, 5), match='tempo'>

Ahora puede consultar match object para obtener información sobre la cadena coincidente. Las instancias de objetos coincidentes también tienen varios métodos y atributos; los más importantes son:

Método/atributo

Objetivo

group()

Retorna la cadena de caracteres que coincide con la RE

start()

Retorna la posición de inicio de la coincidencia

end()

Retorna la posición final de la coincidencia

span()

Retorna una tupla que contiene (inicio, final) las posiciones de coincidencia

Probando estos métodos pronto aclarará sus significados:

>>> m.group()
'tempo'
>>> m.start(), m.end()
(0, 5)
>>> m.span()
(0, 5)

group() retorna la subcadena de caracteres que coincide con la RE. start() y end() retornan el índice inicial y final de la coincidencia. span() retorna el índice inicial y final en una única tupla. Dado que el método match() solo verifica si la RE coincide al comienzo de una cadena de caracteres, start() siempre será cero. Sin embargo, el método de patrones search() escanea a través de la cadena de caracteres, por lo que es posible que la coincidencia no comience en cero en ese caso.

>>> print(p.match('::: message'))
None
>>> m = p.search('::: message'); print(m)
<re.Match object; span=(4, 11), match='message'>
>>> m.group()
'message'
>>> m.span()
(4, 11)

En programas reales, el estilo más común es almacenar match object en una variable, y luego verificar si era None. Esto generalmente se ve así:

p = re.compile( ... )
m = p.match( 'string goes here' )
if m:
    print('Match found: ', m.group())
else:
    print('No match')

Dos métodos de patrón retornan todas las coincidencias de un patrón. findall() retorna una lista de cadenas de caracteres coincidentes:

>>> p = re.compile(r'\d+')
>>> p.findall('12 drummers drumming, 11 pipers piping, 10 lords a-leaping')
['12', '11', '10']

El prefijo r, que convierte al literal en una cadena de caracteres literal sin formato, es necesario en este ejemplo porque las secuencias de escape en un cadena de caracteres literal «cocinado» normal que no son reconocidas por Python, a diferencia de las expresiones regulares, ahora dan como resultado DeprecationWarning y eventualmente se convertirá en SyntaxError. Ver La plaga de la barra invertida (The Backslash Plague).

findall() tiene que crear la lista completa antes de que pueda retornarse como resultado. El método finditer() retorna una secuencia de match object instancias como iterados iterator:

>>> iterator = p.finditer('12 drummers drumming, 11 ... 10 ...')
>>> iterator
<callable_iterator object at 0x...>
>>> for match in iterator:
...     print(match.span())
...
(0, 2)
(22, 24)
(29, 31)

Funciones a nivel de módulo

No es necesario crear un objeto patrón y llamar a sus métodos; el módulo re también proporciona funciones de nivel superior llamadas match() , search() , findall() , sub(), y así sucesivamente. Estas funciones toman los mismos argumentos que el método de patrón correspondiente con la cadena de RE agregada como primer argumento, y aún así retornan una instancia de None o match object.

>>> print(re.match(r'From\s+', 'Fromage amk'))
None
>>> re.match(r'From\s+', 'From amk Thu May 14 19:12:10 1998')
<re.Match object; span=(0, 5), match='From '>

Bajo el capó (hood), estas funciones simplemente crean un objeto patrón para usted y llaman al método apropiado en él. También almacenan el objeto compilado en un caché, por lo que las futuras llamadas que usen el mismo RE no necesitarán analizar el patrón una y otra vez.

¿Debería utilizar estas funciones a nivel de módulo o debería obtener el patrón y llamar a sus métodos usted mismo? Si está accediendo a una expresión regular dentro de un bucle, la compilación previa guardará algunas llamadas a funciones. Fuera de los bucles, no hay mucha diferencia gracias al caché interno.

Los Flags de compilación

Las flags de compilación le permiten modificar algunos aspectos de cómo funcionan las expresiones regulares. Las flags están disponibles en el módulo re con dos nombres, un nombre largo como IGNORECASE y una forma corta de una letra como I. (Si está familiarizado con los modificadores de patrones de Perl, las formas de una letra usan las mismas letras; la forma corta de re.VERBOSE es re.X, por ejemplo).Se pueden especificar varios indicadores uniéndolos con OR bit a bit; re.I | re.M establece los flags I and M, por ejemplo.

Aquí hay una tabla de las flags disponibles, seguida de una explicación más detallada de cada una.

Flag

Significado

ASCII, A

Hace que varios escapes como \w, \b, \s y \d coincidan solo en caracteres ASCII con la propiedad respectiva.

DOTALL, S

Hace que . coincida con cualquier caracter, incluidas las nuevas líneas.

IGNORECASE, I

Hace coincidencias que no distingan entre mayúsculas y minúsculas.

LOCALE, L

Hace una coincidencia con reconocimiento de configuración regional.

MULTILINE, M

Coincidencia de varias líneas, que afecta a ^ y $.

VERBOSE, X (for “extended”)

Habilite RE detallados, que se pueden organizar de manera más limpia y comprensible.

I

IGNORECASE

Realiza una coincidencia que no distinga entre mayúsculas y minúsculas; la clase de caracteres y las cadenas de caracteres literales coincidirán con las letras ignorando las mayúsculas. Por ejemplo, [A-Z] también coincidirá con letras minúsculas. La coincidencia completa de Unicode también funciona a menos que se utilice la flag ASCII para deshabilitar las coincidencias que no sean ASCII. Cuando los patrones Unicode [a-z] o [A-Z] se utilizan en combinación con el indicador IGNORECASE , coincidirán con las 52 letras ASCII y 4 letras adicionales no ASCII “İ” (U+0130, letra mayúscula latina I con un punto arriba), “ı” (U+0131, letra minúscula latina sin punto i),”ſ” (U+017F, letra minúscula latina larga s) y “K” (U+212A, signo de Kelvin). Spam coincidirá 'Spam', 'spam', 'spAM', o 'ſpam' (este último solo coincide en modo Unicode). Estas minúsculas no tiene en cuenta la configuración regional actual; lo hará si también establece la flag LOCALE .

L

LOCALE

Hace que \w, \W, \b, \B y la coincidencia que no distinga entre mayúsculas y minúsculas dependan de la configuración regional actual en lugar de la base de datos Unicode.

Las configuraciones regionales son una característica de la biblioteca C destinada a ayudar a escribir programas que tengan en cuenta las diferencias de idioma. Por ejemplo, si está procesando texto en francés codificado, querrá poder escribir \w+ para que coincida con las palabras, pero \w solo coincide con la clase de caracteres [A-Za-z] en patrones de bytes; no coincidirá con los bytes correspondientes a é or ç. Si su sistema está configurado correctamente y se selecciona una configuración regional francesa, ciertas funciones de C le dirán al programa que el byte correspondiente a é también debe considerarse una letra. Establecer el indicador LOCALE al compilar una expresión regular hará que el objeto compilado resultante use estas funciones C para \w; esto es más lento, pero también permite que \w+ coincida con las palabras en francés como era de esperar. Se desaconseja el uso de esta flag en Python 3 ya que el mecanismo de configuración regional es muy poco confiable, solo maneja una «cultura» a la vez y solo funciona con configuraciones regionales de 8 bits. La coincidencia Unicode ya está habilitada de forma predeterminada en Python 3 para patrones Unicode (str), y puede manejar diferentes configuraciones regionales/idiomas.

M

MULTILINE

(^ y $ aún no se han explicado; se presentarán en la sección Más metacarácteres.)

Por lo general, ^ coincide solo al principio de la cadena de caracteres, y $ solo coincide con el final de la cadena de caracteres e inmediatamente antes del salto de línea (si existe) al final de la cadena de caracteres. Cuando se especifica esta bandera, ^ coincide al principio de la cadena y al comienzo de cada línea dentro de la cadena, inmediatamente después de cada nueva línea. De manera similar, el metacarácter $ coincide al final de la cadena de caracteres y al final de cada línea (inmediatamente antes de cada nueva línea).

S

DOTALL

Hace que el carácter especial '.' coincida con cualquier carácter, incluida una nueva línea; sin esta bandera, '.' coincidirá con cualquier cosa except una nueva línea.

A

ASCII

Haga que \w, \W, \b, \B, \s y \S realicen una coincidencia solo en ASCII en lugar de una coincidencia Unicode completa. Esto solo es significativo para los patrones Unicode y se ignora para los patrones de bytes.

X

VERBOSE

Esta flag le permite escribir expresiones regulares que son más legibles al otorgarle más flexibilidad en cómo puede formatearlas. Cuando se ha especificado esta flag, los espacios en blanco dentro de la cadena de caracteres de la RE se ignoran, excepto cuando el espacio en blanco está en una clase de caracteres o está precedido por una barra invertida sin escape; esto le permite organizar e indentar la RE más claramente. Esta flag también le permite poner comentarios dentro de una RE que serán ignorados por el motor (engine); los comentarios están marcados con un '#' que no está en una clase de carácter ni está precedido por una barra invertida sin escape.

Por ejemplo, aquí hay una RE que usa re.VERBOSE; ¿Ves lo fácil que es leer?

charref = re.compile(r"""
 &[#]                # Start of a numeric entity reference
 (
     0[0-7]+         # Octal form
   | [0-9]+          # Decimal form
   | x[0-9a-fA-F]+   # Hexadecimal form
 )
 ;                   # Trailing semicolon
""", re.VERBOSE)

Sin la configuración detallada, la RE se vería así:

charref = re.compile("&#(0[0-7]+"
                     "|[0-9]+"
                     "|x[0-9a-fA-F]+);")

En el ejemplo anterior, la concatenación automática de cadenas de caracteres literales de Python se ha utilizado para dividir la RE en partes más pequeñas, pero aún es más difícil de entender que la versión que usa re.VERBOSE.

Más poder de patrones

Hasta ahora solo hemos cubierto una parte de las características de las expresiones regulares. En esta sección, cubriremos algunos metacarácteres nuevos y cómo usar grupos para recuperar partes del texto que coincidió.

Más metacarácteres

Hay algunos metacarácteres que aún no hemos cubierto. La mayoría de ellos se tratarán en esta sección.

Algunos de los metacarácteres restantes que se discutirán son zero-width assertions. No hacen que el motor avance a través de la cadena de caracteres; en cambio, no consumen caracteres en absoluto y simplemente tienen éxito o fracasan. Por ejemplo, \b es una flag de que la posición actual se encuentra en el límite de una palabra; la posición no cambia por la \b en absoluto. Esto significa que las aserciones de ancho cero nunca deben repetirse, porque si coinciden una vez en una ubicación determinada, obviamente pueden coincidir un número infinito de veces.

|

Alternancia, o el operador «or». Si A y B son expresiones regulares, A|B coincidirá con cualquier cadena de caracteres que coincida con A o B. | tiene una precedencia muy baja para que funcione razonablemente cuando está alternando cadenas de varios caracteres. Crow|Servo coincidirá con “Crow”` o 'Servo', no 'Cro', un 'w' o un 'S', y 'ervo'.

Para hacer coincidir un literal '|', use \|, o enciérrelo dentro de una clase de carácter, como en [|].

^

Coincide con el comienzo de las líneas. A menos que se haya establecido la flag MULTILINE , esto solo coincidirá al principio de la cadena de caracteres. En modo MULTILINE , esto también coincide inmediatamente después de cada nueva línea dentro de la cadena.

Por ejemplo, si desea hacer coincidir la palabra From solo al principio de una línea, la RE que debe usar es ^From.

>>> print(re.search('^From', 'From Here to Eternity'))
<re.Match object; span=(0, 4), match='From'>
>>> print(re.search('^From', 'Reciting From Memory'))
None

Para una coincidencia literal '^', usar \^.

$

Coincide con el final de una línea, que se define como el final de la cadena o cualquier ubicación seguida de un carácter de nueva línea.

>>> print(re.search('}$', '{block}'))
<re.Match object; span=(6, 7), match='}'>
>>> print(re.search('}$', '{block} '))
None
>>> print(re.search('}$', '{block}\n'))
<re.Match object; span=(6, 7), match='}'>

Para hacer coincidir un literal '$', usar \$ o enciérrelo dentro de una clase de carácter, como en [$].

\A

Coincide solo al comienzo de la cadena de caracteres. Cuando no está en el modo MULTILINE,``A`` y ^ son efectivamente lo mismo. En el modo MULTILINE, son diferentes: \A todavía coincide solo al principio de la cadena, pero ^ puede coincidir en cualquier ubicación dentro de la cadena de caracteres que sigue a un carácter de nueva línea.

\Z

Coincidencias solo al final de la cadena de caracteres.

\b

Límite de palabra. Esta es una aserción de ancho cero que coincide solo al principio o al final de una palabra. Una palabra se define como una secuencia de caracteres alfanuméricos, por lo que el final de una palabra se indica mediante un espacio en blanco o un carácter no alfanumérico.

El siguiente ejemplo coincide con class solo cuando es una palabra completa; no coincidirá cuando esté contenido dentro de otra palabra.

>>> p = re.compile(r'\bclass\b')
>>> print(p.search('no class at all'))
<re.Match object; span=(3, 8), match='class'>
>>> print(p.search('the declassified algorithm'))
None
>>> print(p.search('one subclass is'))
None

Hay dos sutilezas que debe recordar al usar esta secuencia especial. Primero, esta es la peor colisión entre las cadenas literales de caracteres de Python y las secuencias de expresiones regulares. En las cadenas de caracteres literales de Python, \b es el carácter de retroceso (backspace), valor ASCII 8. Si no está utilizando cadenas de caracteres sin procesar, Python convertirá la \b en una linea de retroceso, y su RE no lo hará coincidir como lo espera. El siguiente ejemplo tiene el mismo aspecto que nuestra RE anterior, pero omite la 'r' delante de la cadena de caracteres de RE.

>>> p = re.compile('\bclass\b')
>>> print(p.search('no class at all'))
None
>>> print(p.search('\b' + 'class' + '\b'))
<re.Match object; span=(0, 7), match='\x08class\x08'>

En segundo lugar, dentro de una clase de caracteres, donde no hay uso para esta aserción, \b representa el carácter de retroceso, por compatibilidad con las cadenas de caracteres literales de Python.

\B

Otra flag de ancho cero, esto es lo opuesto a \b, solo coincide cuando la posición actual no está en el límite de una palabra.

Agrupando

Con frecuencia, necesita obtener más información que solo si la RE coincide o no. Las expresiones regulares se utilizan a menudo para diseccionar cadenas de caracteres escribiendo una RE dividido en varios subgrupos que coinciden con diferentes componentes de interés. Por ejemplo, una línea de encabezado RFC-822 se divide en un nombre de encabezado y un valor, separados por un ':', así:

From: author@example.com
User-Agent: Thunderbird 1.5.0.9 (X11/20061227)
MIME-Version: 1.0
To: editor@example.com

Esto se puede manejar escribiendo una expresión regular que coincida con una línea de encabezado completa y que tenga un grupo que coincida con el nombre del encabezado y otro grupo que coincida con el valor del encabezado.

Los grupos están marcados por los '(', ')' metacarácteres. '(' y ')' tienen el mismo significado que en las expresiones matemáticas; agrupan las expresiones contenidas en ellos, y puedes repetir el contenido de un grupo con un calificador repetitivo, como *, +, ?, o {m,n}. Por ejemplo, (ab)* coincidirá con cero o más repeticiones de ab.

>>> p = re.compile('(ab)*')
>>> print(p.match('ababababab').span())
(0, 10)

Los grupos indicados con '(', ')' también capturan el índice inicial y final del texto que coinciden; esto se puede recuperar pasando un argumento a group(), start(), end(), y span(). Los grupos se numeran empezando por 0. El grupo 0 siempre está presente; es todo las RE, entonces todos los métodos match object tienen el grupo 0 como argumento predeterminado. Más adelante veremos cómo expresar grupos que no capturan el espacio de texto que coinciden.

>>> p = re.compile('(a)b')
>>> m = p.match('ab')
>>> m.group()
'ab'
>>> m.group(0)
'ab'

Los subgrupos están numerados de izquierda a derecha, de 1 en adelante. Los grupos se pueden anidar; para determinar el número, simplemente cuente los caracteres del paréntesis de apertura, de izquierda a derecha.

>>> p = re.compile('(a(b)c)d')
>>> m = p.match('abcd')
>>> m.group(0)
'abcd'
>>> m.group(1)
'abc'
>>> m.group(2)
'b'

group() se pueden pasar varios números de grupo a la vez, en cuyo caso retornará una tupla que contiene los valores correspondientes para esos grupos.

>>> m.group(2,1,2)
('b', 'abc', 'b')

El método groups() retorna una tupla que contiene las cadenas de caracteres de todos los subgrupos, desde 1 hasta la cantidad que haya.

>>> m.groups()
('abc', 'b')

Las referencias inversas en un patrón le permiten especificar que el contenido de un grupo de captura anterior también debe encontrarse en la ubicación actual en la cadena. Por ejemplo,``1`` tendrá éxito si el contenido exacto del grupo 1 se puede encontrar en la posición actual y falla en caso contrario. Recuerde que las cadenas de caracteres literales de Python también usan una barra invertida seguida de números para permitir la inclusión de caracteres arbitrarios en una cadena de caracteres, así que asegúrese de usar una cadena de caracteres sin procesar al incorporar referencias inversas en una RE.

Por ejemplo, la siguiente RE detecta palabras duplicadas en una cadena.

>>> p = re.compile(r'\b(\w+)\s+\1\b')
>>> p.search('Paris in the the spring').group()
'the the'

Las referencias inversas como esta no suelen ser útiles para buscar a través de una cadena — hay pocos formatos de texto que repiten datos de esta manera — pero pronto descubrirá que son muy útiles al realizar sustituciones de cadenas de caracteres.

Grupos con nombre y sin captura

Las RE elaboradas pueden utilizar muchos grupos, tanto para capturar subcadenas de caracteres de interés como para agrupar y estructurar la propia RE. En las RE complejas, resulta difícil realizar un seguimiento de los números de los grupos. Hay dos funciones que ayudan con este problema. Ambos usan una sintaxis común para las extensiones de expresiones regulares, así que veremos eso primero.

Perl 5 es bien conocido por sus poderosas adiciones a las expresiones regulares estándar. Para estas nuevas características, los desarrolladores de Perl no podían elegir nuevos metacarácteres de una sola pulsación de tecla o nuevas secuencias especiales que comienzan con \ sin hacer que las expresiones regulares de Perl sean confusamente diferentes de las RE estándar. Si eligieran & como un nuevo metacarácter, por ejemplo, las expresiones antiguas supondrían que & era un carácter regular y no se habría escapado escribiendo \& o [&].

La solución elegida por los desarrolladores de Perl fue utilizar (?...) como sintaxis de extensión. ? inmediatamente después de un paréntesis había un error de sintaxis porque el ? no tendría nada que repetir, por lo que esto no introdujo ningún problema de compatibilidad. Los caracteres inmediatamente después de ? Indican qué extensión se está utilizando, por lo que (?=foo) es una cosa (una flag de anticipación positiva) y (?:foo) es otra cosa (un grupo de no captura que contiene la subexpresión foo).

Python admite varias de las extensiones de Perl y agrega una sintaxis de extensión a la sintaxis de extensión de Perl. Si el primer carácter después del signo de interrogación es una P, sabrá que es una extensión específica de Python.

Ahora que hemos visto la sintaxis de la extensión general, podemos volver a las características que simplifican el trabajo con grupos en RE complejos.

A veces querrá usar un grupo para denotar una parte de una expresión regular, pero no está interesado en recuperar el contenido del grupo. Puede hacer que este hecho sea explícito utilizando un grupo de no captura: (?:...), donde puede reemplazar el ... con cualquier otra expresión regular.

>>> m = re.match("([abc])+", "abc")
>>> m.groups()
('c',)
>>> m = re.match("(?:[abc])+", "abc")
>>> m.groups()
()

Excepto por el hecho de que no puede recuperar el contenido de lo que coincide con el grupo, un grupo que no captura se comporta exactamente igual que un grupo que captura; puede poner cualquier cosa dentro de él, repetirlo con un metacarácter de repetición como * y anidarlo dentro de otros grupos (capturando o no capturando). (?:...) es particularmente útil cuando se modifica un patrón existente, ya que puede agregar nuevos grupos sin cambiar cómo se numeran todos los demás grupos. Cabe mencionar que no hay diferencia de rendimiento en la búsqueda entre grupos de captura y no captura; ninguna forma es más rápida que la otra.

Una característica más significativa son los grupos nombrados: en lugar de referirse a ellos por números, los grupos pueden ser referenciados por un nombre.

La sintaxis de un grupo con nombre es una de las extensiones específicas de Python: (?P<name>...). name es, obviamente, el nombre del grupo. Los grupos con nombre se comportan exactamente como los grupos de captura y, además, asocian un nombre con un grupo. Los métodos match object que tratan con la captura de grupos aceptan enteros que se refieren al grupo por número o cadenas de caracteres que contienen el nombre del grupo deseado. Los grupos con nombre todavía reciben números, por lo que puede recuperar información sobre un grupo de dos maneras:

>>> p = re.compile(r'(?P<word>\b\w+\b)')
>>> m = p.search( '(((( Lots of punctuation )))' )
>>> m.group('word')
'Lots'
>>> m.group(1)
'Lots'

Además, puede recuperar grupos nombrados como un diccionario con groupdict():

>>> m = re.match(r'(?P<first>\w+) (?P<last>\w+)', 'Jane Doe')
>>> m.groupdict()
{'first': 'Jane', 'last': 'Doe'}

Los grupos con nombre son útiles porque le permiten usar nombres fáciles de recordar, en lugar de tener que recordar números. Aquí hay un ejemplo de RE del módulo imaplib:

InternalDate = re.compile(r'INTERNALDATE "'
        r'(?P<day>[ 123][0-9])-(?P<mon>[A-Z][a-z][a-z])-'
        r'(?P<year>[0-9][0-9][0-9][0-9])'
        r' (?P<hour>[0-9][0-9]):(?P<min>[0-9][0-9]):(?P<sec>[0-9][0-9])'
        r' (?P<zonen>[-+])(?P<zoneh>[0-9][0-9])(?P<zonem>[0-9][0-9])'
        r'"')

Obviamente, es mucho más fácil recuperar m.group('zonem'), en lugar de tener que recordar recuperar el grupo 9.

La sintaxis de las referencias inversas en una expresión como (...)\1 se refiere al número del grupo. Naturalmente, existe una variante que usa el nombre del grupo en lugar del número. Esta es otra extensión de Python: (?P=name) indica que el contenido del grupo llamado name debe coincidir nuevamente en el punto actual. La expresión regular para encontrar palabras duplicadas, \b(\w+)\s+\1\b también se puede escribir como \b(?P<word>\w+)\s+(?P=word)\b:

>>> p = re.compile(r'\b(?P<word>\w+)\s+(?P=word)\b')
>>> p.search('Paris in the the spring').group()
'the the'

Aserciones Anticipadas

Otra aserción de ancho cero es la aserción de anticipación. Las afirmaciones anticipadas están disponibles tanto en forma positiva como negativa, y tienen este aspecto:

(?=...)

Aserción de anticipación positiva. Esto tiene éxito si la expresión regular contenida, representada aquí por ..., coincide con éxito en la ubicación actual y falla en caso contrario. Pero, una vez que se ha probado la expresión contenida, el motor de comparación no avanza en absoluto; el resto del patrón se intenta justo donde comenzó la aserción.

(?!...)

Aserción de anticipación negativa. Esto es lo opuesto a la flag positiva; tiene éxito si la expresión contenida no coincide con la posición actual en la cadena.

Para que esto sea concreto, veamos un caso en el que una búsqueda anticipada es útil. Considere un patrón simple para hacer coincidir un nombre de archivo y dividirlo en un nombre base y una extensión, separados por un .. Por ejemplo, en news.rc, news es el nombre base y rc es la extensión del nombre del archivo.

El patrón para que coincida con esto es bastante simple:

.*[.].*$

Tenga en cuenta que el . Debe tratarse especialmente porque es un metacarácter, por lo que está dentro de una clase de carácter para coincidir solo con ese carácter específico. También observe el final $; esto se agrega para garantizar que todo el resto de la cadena deba incluirse en la extensión. Esta expresión regular coincide con foo.bar y autoexec.bat y sendmail.cf y printers.conf.

Ahora, considere complicar un poco el problema; ¿Qué sucede si desea hacer coincidir los nombres de archivo donde la extensión no es bat? Algunos intentos incorrectos:

.*[.][^b].*$ El primer intento anterior intenta excluir bat requiriendo que el primer carácter de la extensión no sea una b. Esto está mal, porque el patrón tampoco coincide foo.bar.

.*[.]([^b]..|.[^a].|..[^t])$

La expresión se vuelve más desordenada cuando intenta parchear la primera solución requiriendo que coincida uno de los siguientes casos: el primer carácter de la extensión no es b; el segundo carácter no es a; o el tercer carácter no es t. Esto acepta foo.bar y rechaza autoexec.bat, pero requiere una extensión de tres letras y no acepta un nombre de archivo con una extensión de dos letras como sendmail.cf. Complicaremos el patrón nuevamente en un esfuerzo por arreglarlo.

.*[.]([^b].?.?|.[^a]?.?|..?[^t]?)$

En el tercer intento, la segunda y tercera letras se hacen opcionales para permitir extensiones coincidentes de menos de tres caracteres, como sendmail.cf.

El patrón se está volviendo realmente complicado ahora, lo que dificulta su lectura y comprensión. Peor aún, si el problema cambia y desea excluir tanto bat y exe como extensiones, el patrón se volvería aún más complicado y confuso.

Una mirada anticipada negativa atraviesa toda esta confusión:

.*[.](?!bat$)[^.]*$ La búsqueda anticipada negativa significa: si la expresión bat no coincide en este punto, pruebe el resto del patrón; si bat$ coincide, todo el patrón fallará. El $ final es necesario para garantizar que se permita algo como sample.batch, donde la extensión solo comienza con bat. El [^.]* asegura que el patrón funcione cuando hay varios puntos en el nombre del archivo.

Ahora es fácil excluir otra extensión de nombre de archivo; simplemente agréguelo como una alternativa dentro de la aserción. El siguiente patrón excluye los nombres de archivo que terminan en bat o exe:

.*[.](?!bat$|exe$)[^.]*$

Modificando cadenas de caracteres

Hasta este punto, simplemente hemos realizado búsquedas en una cadena de caracteres estática. Las expresiones regulares también se utilizan comúnmente para modificar cadenas de varias formas, utilizando los siguientes métodos de patrón:

Método/atributo

Objetivo

split()

Divida la cadena de caracteres en una lista, dividiéndola donde coincida la RE

sub()

Encuentra todas las subcadenas de caracteres donde coincida la RE y las reemplaza con una cadena de caracteres diferente

subn()

Hace lo mismo que sub(), pero retorna la nueva cadena de caracteres y el número de reemplazos

Separando cadenas de caracteres

El método split() de un patrón que divide una cadena de caracteres donde la RE coincide, retornando una lista de las piezas. Es similar al método de cadenas de caracteres split() pero proporciona mucha más generalidad en los delimitadores por los que puede dividir; cadena de caracteres split() solo admite la división por espacios en blanco o por una cadena fija. Como era de esperar, también hay una función a nivel de módulo re.split().

.split(string[, maxsplit=0])

Dividir string por las coincidencias de la expresión regular. Si se utilizan paréntesis de captura en la RE, su contenido también se retornará como parte de la lista resultante. Si maxsplit es distinto de cero, se realizan como máximo divisiones maxsplit .

Puede limitar el número de divisiones realizadas, pasando un valor para maxsplit. Cuando maxsplit es distinto de cero, se realizarán como máximo maxsplit divisiones, y el resto de la cadena de caracteres se retorna como el elemento final de la lista. En el siguiente ejemplo, el delimitador es cualquier secuencia de caracteres no alfanuméricos.

>>> p = re.compile(r'\W+')
>>> p.split('This is a test, short and sweet, of split().')
['This', 'is', 'a', 'test', 'short', 'and', 'sweet', 'of', 'split', '']
>>> p.split('This is a test, short and sweet, of split().', 3)
['This', 'is', 'a', 'test, short and sweet, of split().']

A veces, no solo le interesa cuál es el texto entre delimitadores, sino que también necesita saber cuál era el delimitador. Si se utilizan paréntesis de captura en la RE, sus valores también se retornan como parte de la lista. Compare las siguientes llamadas:

>>> p = re.compile(r'\W+')
>>> p2 = re.compile(r'(\W+)')
>>> p.split('This... is a test.')
['This', 'is', 'a', 'test', '']
>>> p2.split('This... is a test.')
['This', '... ', 'is', ' ', 'a', ' ', 'test', '.', '']

La función de nivel de módulo re.split() agrega la RE que se usará como primer argumento, pero por lo demás es el mismo.

>>> re.split(r'[\W]+', 'Words, words, words.')
['Words', 'words', 'words', '']
>>> re.split(r'([\W]+)', 'Words, words, words.')
['Words', ', ', 'words', ', ', 'words', '.', '']
>>> re.split(r'[\W]+', 'Words, words, words.', 1)
['Words', 'words, words.']

Búsqueda y Remplazo

Otra tarea común es encontrar todas las coincidencias para un patrón y reemplazarlas con una cadena de caracteres diferente. El método sub() toma un valor de reemplazo, que puede ser una cadena de caracteres o una función, y la cadena de caracteres a procesar.

.sub(replacement, string[, count=0])

Retorna la cadena de caracteres obtenida al reemplazar las apariciones no superpuestas del extremo izquierdo de la RE en string por el remplazo replacement. Si no se encuentra el patrón, el string se retorna sin cambios.

El argumento opcional count es el número máximo de ocurrencias de patrones que se reemplazarán; count debe ser un número entero no negativo. El valor predeterminado de 0 significa reemplazar todas las ocurrencias.

Aquí hay un ejemplo simple del uso del método sub(). Reemplaza los nombres de los colores con la palabra colour:

>>> p = re.compile('(blue|white|red)')
>>> p.sub('colour', 'blue socks and red shoes')
'colour socks and colour shoes'
>>> p.sub('colour', 'blue socks and red shoes', count=1)
'colour socks and red shoes'

El método subn() hace el mismo trabajo, pero retorna una tupla de 2 que contiene el nuevo valor de cadena de caracteres y el número de reemplazos que se realizaron:

>>> p = re.compile('(blue|white|red)')
>>> p.subn('colour', 'blue socks and red shoes')
('colour socks and colour shoes', 2)
>>> p.subn('colour', 'no colours at all')
('no colours at all', 0)

Las coincidencias vacías se reemplazan solo cuando no son adyacentes a una coincidencia vacía anterior.

>>> p = re.compile('x*')
>>> p.sub('-', 'abxd')
'-a-b--d-'

Si replacement es una cadena, se procesan los escapes de barra invertida que contenga. Es decir, \n se convierte en un solo carácter de nueva línea, \r se convierte en una REtorno de carro, y así sucesivamente. Los escapes desconocidos como \& se dejan en paz. Las referencias inversas, como \6, se reemplazan con la subcadena de caracteres que coincide con el grupo correspondiente a la RE. Esto le permite incorporar partes del texto original en la cadena de reemplazo resultante.

Este ejemplo hace coincidir la palabra section seguida de una cadena encerrada entre {, }, y cambia section a subsection:

>>> p = re.compile('section{ ( [^}]* ) }', re.VERBOSE)
>>> p.sub(r'subsection{\1}','section{First} section{second}')
'subsection{First} subsection{second}'

También hay una sintaxis para hacer referencia a grupos con nombre según lo definido por la sintaxis (?P<name>…)``syntax. ``\g<name> usará la subcadena de caracteres que coincide con el grupo llamado name, y \g<number> usa el número de grupo correspondiente. \g<2> es equivalente a \2, pero no es ambiguo en una cadena de reemplazo como \g<2>0. (\20 se interpretaría como una referencia al grupo 20, no como una referencia al grupo 2 seguido del carácter literal '0'.) Las siguientes sustituciones son todas equivalentes, pero use las tres variaciones de la cadena de reemplazo.

>>> p = re.compile('section{ (?P<name> [^}]* ) }', re.VERBOSE)
>>> p.sub(r'subsection{\1}','section{First}')
'subsection{First}'
>>> p.sub(r'subsection{\g<1>}','section{First}')
'subsection{First}'
>>> p.sub(r'subsection{\g<name>}','section{First}')
'subsection{First}'

replacement también puede ser una función, lo que le brinda aún más control. Si replacement es una función, la función se llama para cada ocurrencia no superpuesta de pattern. En cada llamada, a la función se le pasa un argumento match object para la coincidencia y puede usar esta información para calcular la cadena de reemplazo deseada y retornarla.

En el siguiente ejemplo, la función de reemplazo traduce decimales a hexadecimales:

>>> def hexrepl(match):
...     "Return the hex string for a decimal number"
...     value = int(match.group())
...     return hex(value)
...
>>> p = re.compile(r'\d+')
>>> p.sub(hexrepl, 'Call 65490 for printing, 49152 for user code.')
'Call 0xffd2 for printing, 0xc000 for user code.'

Cuando se usa la función module-level re.sub(), el patrón se pasa como primer argumento. El patrón puede proporcionarse como un objeto o como una cuerda; Si necesita especificar marcas de expresión regular, debe usar un objeto de patrón como primer parámetro o usar modificadores incrustados en la cadena de patrón, por ejemplo sub("(?i)b+", "x", "bbbb BBBB") retorna 'x x'.

Problemas comunes

Las expresiones regulares son una herramienta poderosa para algunas aplicaciones, pero de alguna manera su comportamiento no es intuitivo y, a veces, no se comportan de la forma esperada. Esta sección señalará algunos de los errores más comunes.

Uso de métodos de cadenas de caracteres

A veces, usar el módulo re es un error. Si está haciendo coincidir una cadena de caracteres fija, o una clase de un solo caracter, y no está usando ninguna característica re como la marca IGNORECASE, entonces todo el poder de las expresiones regulares puede que no sea necesario. Las cadenas tienen varios métodos para realizar operaciones con cadenas fijas y, por lo general, son mucho más rápidas, porque la implementación es un único bucle C pequeño que se ha optimizado para este propósito, en lugar del motor de expresión regular más grande y generalizado.

Un ejemplo podría ser reemplazar una sola cadena fija por otra; por ejemplo, puede reemplazar word por deed. re.sub() parece la función a utilizar para esto, pero considere el método replace(). Tenga en cuenta que replace() también reemplazará word dentro de las palabras, convirtiendo swordfish en sdeedfish, pero la RE naíf word también lo habría hecho. (Para evitar realizar la sustitución en partes de palabras, el patrón tendría que ser \bword\b, para requerir que word tenga un límite de palabra en cada lado. Esto lleva el trabajo más allá de las habilidades de replace().)

Otra tarea común es eliminar cada aparición de un solo carácter de una cadena o reemplazarlo con otro solo carácter. Puede hacer esto con algo como re.sub('\n', ' ', S), pero translate() es capaz de realizar ambas tareas y será más rápido que cualquier expresión regular la operación puede ser.

En resumen, antes de pasar al módulo re, considere si su problema puede resolverse con un método de cadena de caracteres más rápido y simple.

match() versus search()

La función match() solo verifica si la RE coincide con el comienzo de la cadena de caracteres, mientras que search() buscará una coincidencia en la cadena de caracteres. Es importante tener en cuenta esta distinción. Recuerde match() solo informará una coincidencia exitosa que comenzará en 0; si la coincidencia no comienza en cero, match() no lo informará.

>>> print(re.match('super', 'superstition').span())
(0, 5)
>>> print(re.match('super', 'insuperable'))
None

Por otro lado, search() escaneará hacia adelante a través de la cadena de caracteres, informando la primera coincidencia que encuentre.

>>> print(re.search('super', 'superstition').span())
(0, 5)
>>> print(re.search('super', 'insuperable').span())
(2, 7)

A veces, tendrá la tentación de seguir usando re.match(), y simplemente agregar .* al frente de su RE. Resista esta tentación y use re.search() en su lugar. El compilador de expresiones regulares realiza un análisis de las RE para acelerar el proceso de búsqueda de coincidencias. Uno de esos análisis determina cuál debe ser el primer carácter de una coincidencia; por ejemplo, un patrón que comienza con Crow debe coincidir con una 'C'.El análisis permite que el motor escanee rápidamente a través de la cadena en busca del carácter inicial, solo probando la coincidencia completa si se encuentra una 'C'.

Agregar .* anula esta optimización, lo que requiere escanear hasta el final de la cadena y luego retroceder para encontrar una coincidencia para el resto de la RE. Utilice re.search() en su lugar.

Codiciosa versus no codiciosa (Greedy versus Non-Greedy)

Al repetir una expresión regular, como en a*, la acción resultante es consumir la mayor cantidad posible del patrón. Este hecho suele molestarle cuando intenta hacer coincidir un par de delimitadores equilibrados, como los corchetes angulares que rodean una etiqueta HTML. El patrón ingenuo para hacer coincidir una sola etiqueta HTML no funciona debido a la naturaleza codiciosa de .*.

>>> s = '<html><head><title>Title</title>'
>>> len(s)
32
>>> print(re.match('<.*>', s).span())
(0, 32)
>>> print(re.match('<.*>', s).group())
<html><head><title>Title</title>

La RE coincide con el '<' en '<html>', y el .* consume el resto de la cadena de caracteres. Sin embargo, aún queda más en la RE y el > no puede coincidir al final de la cadena de caracteres, por lo que el motor de la expresión regular tiene que retroceder carácter por carácter hasta que encuentre una coincidencia para el >. La coincidencia final se extiende desde el “<”` en '<html>' al '>' en '</title>', que no es lo que queremos.

En este caso, la solución es utilizar los calificadores no codiciosos *?, +?, ??, o {m,n}?, Que coinciden como poco texto como sea posible. En el ejemplo anterior, el '>' se prueba inmediatamente después de las primeras coincidencias '<', y cuando falla, el motor avanza un carácter a la vez, volviendo a intentar el '>' en cada paso. Esto produce el resultado correcto:

>>> print(re.match('<.*?>', s).group())
<html>

(Tenga en cuenta que analizar HTML o XML con expresiones regulares es doloroso. Los patrones rápidos y sucios manejarán casos comunes, pero HTML y XML tienen casos especiales que romperán la expresión regular obvia; para cuando haya escrito una expresión regular que maneja todos los casos posibles, los patrones serán muy complicados. Utilice un módulo analizador HTML o XML para tales tareas.)

Usando re.VERBOSE

Probablemente ya haya notado que las expresiones regulares son una notación muy compacta, pero no son muy legibles. Las RE de complejidad moderada pueden convertirse en largas colecciones de barras invertidas, paréntesis y metacarácteres, lo que dificulta su lectura y comprensión.

Para tales RE, especificar el flag re.VERBOSE al compilar la expresión regular puede ser útil, porque le permite formatear la expresión regular con mayor claridad.

La flag re.VERBOSE tiene varios efectos. Los espacios en blanco en la expresión regular que no están dentro de una clase de caracteres se ignoran. Esto significa que una expresión como dog | cat es equivalente al menos legible dog | cat, pero [a b] seguirá coincidiendo con los caracteres 'a', 'b' o un espacio. Además, también puede poner comentarios dentro de una RE; los comentarios se extienden desde un carácter # hasta la siguiente línea nueva. Cuando se usa con cadenas entre comillas triples, esto permite que las REs sean formateados de manera más ordenada:

pat = re.compile(r"""
 \s*                 # Skip leading whitespace
 (?P<header>[^:]+)   # Header name
 \s* :               # Whitespace, and a colon
 (?P<value>.*?)      # The header's value -- *? used to
                     # lose the following trailing whitespace
 \s*$                # Trailing whitespace to end-of-line
""", re.VERBOSE)

Esto es mas legible que:

pat = re.compile(r"\s*(?P<header>[^:]+)\s*:(?P<value>.*?)\s*$")

Feedback

Las expresiones regulares son un tema complicado. ¿Le ayudó este documento a comprenderlas? ¿Hubo partes que no estaban claras o problemas que encontró que no se trataron aquí? Si es así, envíe sugerencias de mejora al autor.

El libro más completo sobre expresiones regulares es casi con certeza Mastering Regular Expressions de Jeffrey Friedl, publicado por O’Reilly. Desafortunadamente, se concentra exclusivamente en los tipos de expresiones regulares de Perl y Java, y no contiene ningún material de Python, por lo que no será útil como referencia para la programación en Python. (La primera edición cubría el módulo regex de Python, ahora eliminado, que no le ayudará mucho.) Considere sacarlo de su biblioteca.

HOW TO - Programación con sockets

Autor

Gordon McMillan

Resumen

Los sockets son usados casi en todas partes pero son una de las tecnologías más incomprendidas. Esta es una descripción general de los sockets. No es realmente un tutorial, todavía tendrás trabajo para hacer que las cosas funcionen. No cubre los pequeños detalles (y hay muchos de ellos) pero espero que pueda dar suficiente información para comenzar a usarlos decentemente.

Sockets

Solo voy a hablar de los sockets INET (como IPv4), pues solo ellos cubren el 99% del uso de los sockets. Y solo voy a hablar sobre los sockets STREAM (como TCP), a menos que realmente sepas lo que haces (y en ese caso esta guía no es para ti), tendrás mejor comportamiento y rendimiento con un socket STREAM que con cualquier otro. Voy a tratar de aclarar el misterio de que es un socket, además de algunas ideas sobre como trabajar con sockets bloqueantes y no bloqueantes. Pero voy a comenzar hablando de los sockets bloqueantes, necesitarás saber como funcionan antes de lidiar con los no bloqueantes.

Parte del problema para entenderlos es que «socket» puede significar un número de cosas ligeramente diferentes dependiendo del contexto. Entonces, primero vamos a hacer una distinción entre sockets «cliente» - un extremo de una conversación, y un socket «servidor», que es más como una central de teléfonos. La aplicación cliente (tu navegador, por ejemplo) usa sockets «cliente» exclusivamente; el servidor web con quien se está comunicando usa sockets «cliente» y «servidor».

Historia

De las varias formas de comunicación entre procesos (IPC) los sockets son, por mucho, la más popular. En cualquier plataforma es probable que existan otras formas de IPC más rápidas, pero en comunicación multiplataforma los sockets son los únicos competidores.

Fueron inventados en Berkeley como parte de la derivación de Unix BSD y se expandió como la pólvora en internet. Con buena razón — la combinación de los sockets con INET hace que hablar con computadoras arbitrarias alrededor del mundo sea increíblemente sencillo (al menos comparado con otros esquemas).

Creando un socket

De manera general, cuando hiciste click en el enlace que te trajo a esta página tu navegador hizo algo como lo siguiente:

# create an INET, STREAMing socket
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
# now connect to the web server on port 80 - the normal http port
s.connect(("www.python.org", 80))

Cuando connect termina, el socket s puede ser usado en una petición para traer el texto de la página. El mismo socket leerá la respuesta y luego será destruido. Así es, destruido. Los sockets cliente son normalmente usados solo para un intercambio (o un pequeño numero se intercambios secuenciales).

Lo que sucede en el servidor web es un poco más complejo. Primero, el servidor web crea un «socket servidor»:

# create an INET, STREAMing socket
serversocket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
# bind the socket to a public host, and a well-known port
serversocket.bind((socket.gethostname(), 80))
# become a server socket
serversocket.listen(5)

Un par de cosas que señalar: usamos socket.gethostname() para que el socket fuera visible al mundo exterior. Si hubiésemos usado s.bind(('localhost', 80)) o s.bind(('127.0.0.1', 80)) habríamos tenido un socket servidor pero solo habría sido visible en la misma máquina. s.bind(('', 80)) especifica que el socket es accesible desde cualquier dirección que tenga la máquina.

Algo más para señalar: los números de puerto bajos son normalmente reservados para servicios «conocidos» (HTTP, SNMP, etc.). Si estás probando los sockets usa un número grande (4 dígitos).

Finalmente, el argumento que se le pasa a listen le indica a la librería del socket que queremos poner en cola no más de 5 solicitudes de conexión (el máximo normal) antes de rechazar conexiones externas. Si el resto del código está escrito correctamente eso debería ser suficiente.

Ahora que tenemos un socket servidor escuchando en el puerto 80 ya podemos entrar al bucle principal del servidor web:

while True:
    # accept connections from outside
    (clientsocket, address) = serversocket.accept()
    # now do something with the clientsocket
    # in this case, we'll pretend this is a threaded server
    ct = client_thread(clientsocket)
    ct.run()

Existen en realidad 3 maneras generales en las cuales este bucle puede funcionar - despachar un hilo para manejar clientsocket, crear un proceso nuevo para manejar clientsocket o reestructurar esta aplicación para usar sockets no bloqueantes y multiplexar entre nuestro «socket servidor» y cualquier clientsocket activo usando select. Más sobre esto después. Lo importante a entender ahora es: esto es todo lo que un «socket servidor hace». No manda ningún dato. No recibe ningún dato. Solo produce «sockets clientes». Cada clientsocket es creado en respuesta a algún otro «socket cliente» que hace connect() al host y al puerto al que estamos vinculados. Tan pronto como hemos credo ese clientsocket volvemos a escuchar por más conexiones. Los dos «clientes» son libres de «conversar» entre ellos - están usando algún puerto asignado dinámicamente que será reciclado cuando la conversación termine.

IPC

Si necesitas conexiones IPC rápidas entre dos procesos en una misma máquina puedes revisar los pipes o la memoria compartida. Si decides usar sockets AF_INET, vincula el servidor con "localhost". En la mayoría de las plataformas, esto tomará un atajo alrededor de algunas capas del código de red y será un poco más rápido.

Ver también

El módulo multiprocessing integra IPC multiplataforma en un API de alto nivel.

Usando un socket

Lo primero a señalar es que el «socket cliente» del navegador y el «socket cliente» del servidor web son bestias idénticas. Es decir, esta es una conversación peer to peer. O para decirlo de otra manera, como diseñador, tendrás que decidir cuáles son las reglas de etiqueta para una conversación. Normalmente, el socket que se conecta inicia la conversación, enviando una solicitud o tal vez un inicio de sesión. Pero esa es una decisión de diseño: no es una regla de los sockets.

Hay dos conjuntos de verbos que se usan para la comunicación. Puedes usar send y recv o puedes transformar tu socket cliente en algo similar a un archivo y usar read y write. Esta última es la forma en la que Java presenta sus sockets. No voy a hablar acerca de eso aquí, excepto para advertirte que necesitas usar flush en los sockets. Estos son archivos en buffer, y un error común es usar write para escribir algo y luego usar read para leer la respuesta. Sin usar flush en este caso, puedes terminar esperando la respuesta por siempre porque la petición estaría aún en el buffer de salida.

Ahora llegamos al principal problema de los sockets - send y recv operan en los buffers de red. Ellos no manejan necesariamente todos los bytes que se les entrega (o espera de ellos), porque su enfoque principal es manejar los buffers de red. En general, ellos retornan cuando los buffers de red asociados se han llenado (send) o vaciado (recv). Luego ellos dicen cuántos bytes manejaron. Es tu responsabilidad llamarlos nuevamente hasta que su mensaje haya sido tratado por completo.

Cuando recv retorna 0 bytes significa que el otro lado ha cerrado (o está en el proceso de cerrar) la conexión. No recibirás más datos de esta conexión. Nunca. Es posible que puedas mandar datos exitosamente. De eso voy a hablar más tarde.

Un protocolo como HTTP usa un socket para una sola transferencia. El cliente manda una petición, luego lee la respuesta. Eso es todo. El socket es descartado. Esto significa que un cliente puede detectar el final de la respuesta al recibir 0 bytes.

Pero si planeas reusar el socket para más transferencias, tienes que darte cuenta que no hay EOT en un socket. Repito: si la llamada a send o recv de un socket retorna después de manejar 0 bytes, la conexión se ha interrumpido. Si la conexión no se ha interrumpido, puedes esperar un recv para siempre, porque el socket no te dirá cuando no hay más nada por leer (por ahora). Ahora, si piensas sobre eso un poco, te darás cuenta de una verdad fundamental de los sockets: los mensajes deben ser de longitud fija (ouch), o ser delimitados (ouch), o indicar que tan largo son (mucho mejor), o terminar cerrando la conexión. La elección es completamente tuya (pero hay algunas vías más correctas que otras).

Asumiendo que no quieres terminar la conexión, la solución más simple es un mensaje de longitud fija:

class MySocket:
    """demonstration class only
      - coded for clarity, not efficiency
    """

    def __init__(self, sock=None):
        if sock is None:
            self.sock = socket.socket(
                            socket.AF_INET, socket.SOCK_STREAM)
        else:
            self.sock = sock

    def connect(self, host, port):
        self.sock.connect((host, port))

    def mysend(self, msg):
        totalsent = 0
        while totalsent < MSGLEN:
            sent = self.sock.send(msg[totalsent:])
            if sent == 0:
                raise RuntimeError("socket connection broken")
            totalsent = totalsent + sent

    def myreceive(self):
        chunks = []
        bytes_recd = 0
        while bytes_recd < MSGLEN:
            chunk = self.sock.recv(min(MSGLEN - bytes_recd, 2048))
            if chunk == b'':
                raise RuntimeError("socket connection broken")
            chunks.append(chunk)
            bytes_recd = bytes_recd + len(chunk)
        return b''.join(chunks)

El código de envío aquí es usable para prácticamente cualquier esquema de mensajería - en Python envías cadenas y usas len() para determinar su longitud (incluso si tiene caracteres \0 incrustados). Es principalmente el código receptor el que se vuelve más complejo. (Y en C no es mucho peor, excepto que no puedes usar strlen si el mensaje tiene \0 incrustados).

La mejora más fácil es hacer que el primer caracter del mensaje un indicador del tipo de mensaje y que el tipo determine la longitud. Ahora tienes dos recv - el primero para obtener (al menos) ese primer caracter para conocer la longitud, y el segundo en un bucle para obtener el resto. Si decides ir por el camino del delimitador, estarás recibiendo un fragmento de tamaño arbitrario (4096 o 8192 son a menudo buenas elecciones para tamaños de buffers de red) y escaneando lo que recibas en busca del delimitador.

Hay una complicación de la que estar consiente: si el protocolo conversacional permite mandar múltiples mensajes consecutivos (sin ningún tipo de respuesta), y pasas a recv un tamaño de fragmento arbitrario poder terminar leyendo el inicio de un próximo mensaje. Tendrás que dejarlo aparte y guardarlo hasta que sea necesario.

Prefijar el mensaje con su longitud (por ejemplo, 5 caracteres numéricos) se vuelve más complicado porque (créalo o no), puede que no recibas los 5 caracteres en una llamada a recv. Para proyectos pequeños te saldrás con la tuya; pero con altas cargas de red, tu código se romperá rápidamente a menos que uses dos recv en bucle - el primero para determinar la longitud, el segundo para obtener la parte del mensaje. Sucio. También será cuando descubras que send no siempre logra enviar todo de una sola vez. Y a pesar de haber leído esto eventualmente te va a morder!

Con interés de espacio, la construcción de tu carácter (y preservar mi posición competitiva), estas mejoras se dejan como un ejercicio para el lector. Pasemos a la limpieza.

Datos binarios

Es perfectamente posible mandar datos binarios en un socket. El mayor problema es que no todas las máquinas usan el mismo formato para datos binarios. Por ejemplo, un chip Motorola representa un entero de 16 bit con el valor 1 como los dos bytes hexadecimales 00 01. Intel y DEC, sin embargo, son de «bytes invertidos» - el mismo valor 1 es 01 00. Las bibliotecas de sockets tienen funciones para convertir enteros de 16 y 32 bit - ntohl, htonl, ntohs, htons donde la «n» significa «network» y «h» significa «host», «s» significa «short» y «l» significa «long». Cuando el orden de la red es el orden del servidor, estas funciones no hacen nada, pero cuando la máquina es de «bytes invertidos», estas cambian los bytes apropiadamente.

En estos días de máquinas de 32 bit, la representación ascii de los datos binarios es con frecuencia más pequeña que la representación binaria. Esto es porque una sorprendente cantidad de veces, todos esos «longs» tienen de valor 0, o tal vez 1. La cadena «0» tendría dos bytes, mientras el binario cuatro. Por supuesto, esto no funciona bien con los mensajes de longitud fija. Decisiones, decisiones.

Desconectando

Estrictamente hablando, se supone que debes usar shutdown en un socket antes de cerrarlo con close. shutdown es un aviso para el socket en el otro lado. Dependiendo del argumento que se le pase, puede significar «No voy a mandar más datos, pero voy a escuchar» o «No estoy escuchando, adiós!». La mayoría de bibliotecas para sockets, sin embargo, están tan acostumbradas a que los programadores ignoren esta parte de la etiqueta que normalmente close es lo mismo que shutdown(); close(). Por tanto en la mayoría de las situaciones usar shutdown de manera explícita no es necesario.

Una forma de usar shutdown de manera efectiva es en un intercambio similar a HTTP. El cliente manda una petición y entonces hace un shutdown(1). Esto le dice al servidor «El cliente terminó de enviar, pero todavía puede recibir». El servidor puede detectar «EOF» (Fin del Archivo) al recibir 0 bytes. Puede asumir que se completó la petición. El servidor envía una respuesta. Si el send termina satisfactoriamente entonces, en efecto, el cliente todavía estaba recibiendo.

Python lleva el apagado automático un paso más allá, y dice que cuando un socket es eliminado por el recolector de basura, automáticamente llama a close si es necesario. Pero confiar en esto es un mal hábito. Si tu socket simplemente desaparece sin llamar a close, el socket del otro lado puede colgarse indefinidamente, pensando que solo estas siendo lento. Por favor cierra los sockets cuando termines.

Cuando los sockets mueren

Probablemente lo peor de usar sockets bloqueantes es lo que pasa cuando el otro lado se apaga inesperadamente (sin llamar a close). Tu socket es probable que se cuelgue. TCP es un protocolo confiable, y va a esperar un largo, largo tiempo antes de rendirse con una conexión. Si estás usando hilos, todo el hilo está esencialmente muerto. No hay mucho que puedas hacer respecto a eso. A menos que no estés haciendo algo tonto, como mantener un bloqueo mientras se realiza una lectura bloqueante, el hilo realmente no estará consumiendo muchos recursos. No trates de matar el hilo - parte de la razón por la que los hilos son más eficientes que los procesos es que evitan la complicación asociada con el reciclaje automático de recursos. En otras palabras, si te las arreglas para matar el hilo, es muy probable que todo el proceso termine arruinado.

Sockets no bloqueantes

Si has entendido todo lo anterior, ya conoces la mayor parte de lo que necesitas saber sobre las mecánicas del uso de los sockets. Usarás las mismas llamadas, de la misma manera. Es solo eso, si lo haces correctamente, tu aplicación estará casi correcta.

En Python, usa socket.setblocking(False) para que no sea bloqueante. En C, es más complejo (por un lado, deberá elegir entre el sabor BSD O_NONBLOCK y el sabor POSIX casi indistinguible O_NDELAY, que es completamente diferente de TCP_NODELAY) , pero es exactamente la misma idea. Haz esto después de crear el socket, pero antes de usarlo. (En realidad, si estás loco, puedes cambiar de un lado a otro).

La principal diferencia mecánica es que send, recv, connect y accept pueden retornar sin haber hecho nada. Tu tienes (por supuesto) un número de elecciones. Puedes verificar el código de retorno y los códigos de error y en general volverte loco. Si no me crees pruébalo alguna vez. Tu aplicación crecerá grande, con errores y consumirá todo el CPU. Así que vamos a saltarnos las soluciones descerebradas y hacerlo correctamente.

Usando select.

En C, usar select es algo complejo. En Python es pan comido, pero está lo suficientemente cercano a la versión de C que si entiendes el select en Python tendrás pocos problemas con él el C:

ready_to_read, ready_to_write, in_error = \
               select.select(
                  potential_readers,
                  potential_writers,
                  potential_errs,
                  timeout)

A select se le pasan tres listas: la primera contiene todos los sockets que puedes intentar leer; la segunda con todos los sockets que puedes intentar escribir, y la tercera (normalmente se deja vacía) todos los que quieras verificar los errores. Debes tener en cuenta que un socket puede ir en más de una lista. La llamada a select es bloqueante, pero puedes darle un tiempo de espera. Esto generalmente es una cosa sensata de hacer - dale un tiempo de espera largo (un minuto por ejemplo) a menos que tengas una buena razón para no hacerlo.

En el retorno tendrás tres listas. Estas contienen los sockets que son realmente legibles, escribibles y con error. Cada una de estas lista es un subconjunto (posiblemente vacío) de la lista correspondiente que pasaste.

Si un socket está en la lista retornada legible, puedes estar tan-seguro-como-podrías-estarlo-en-este-negocio que una llamada a recv en este socket va a retornar algo. La misma idea se aplica a la lista de escribibles. Serás capaz de mandar algo. Tal vez no todo lo que quieras, pero algo es mejor que nada. (Realmente, cualquier socket socket razonablemente saludable va a retornar como escribible - eso solo significa que el espacio de salida del buffer de red está disponible)

Si tienes un socket servidor, ponlo en la lista de potenciales legibles. Se retorna en la lista de legibles, una llamada a accept va a funcionar (casi seguro). Se has creado un nuevo socket para llamar a connect para conectarte con otro, ponlo en la lista de potenciales escribibles. Si retorna en la lista de escribibles, tienes una buena oportunidad de que esté conectado.

Realmente, select puede ser útil incluso con sockets bloqueantes. Es una manera de determinar si vas a bloquear - el socket retorna como leíble cuando hay algo en el buffer. Sin embargo, esto aun no sirve de ayuda con el problema de determinar si el otro extremo terminó, o solo está ocupado con otra cosa.

Alerta de portabilidad: En Unix, select funciona tanto con sockets como con archivos. No intentes esto en Windows. En Windows select funciona solo con sockets. También ten en cuenta que en C, muchas de las opciones más avanzadas de los sockets se hacen diferentes en Windows. De hecho, en Windows normalmente uso hilos (que funciona muy, muy bien) con los sockets.

HOW TO - Ordenar

Autor

Andrew Dalke and Raymond Hettinger

Versión

0.1

Las listas de Python tienen un método incorporado list.sort() que modifica la lista in situ. También hay una función incorporada sorted() que crea una nueva lista ordenada a partir de un iterable.

En este documento exploramos las distintas técnicas para ordenar datos usando Python.

Conceptos básicos de ordenación

Una simple ordenación ascendente es muy fácil: simplemente llame a la función sorted(). Retorna una nueva lista ordenada:

>>> sorted([5, 2, 3, 1, 4])
[1, 2, 3, 4, 5]

También puede usar el método list.sort(). Modifica la lista in situ (y retorna None para evitar confusiones). Por lo general, es menos conveniente que sorted(), pero si no necesita la lista original, es un poco más eficiente.

>>> a = [5, 2, 3, 1, 4]
>>> a.sort()
>>> a
[1, 2, 3, 4, 5]

Otra diferencia es que el método list.sort() solo aplica para las listas. En contraste, la función sorted() acepta cualquier iterable.

>>> sorted({1: 'D', 2: 'B', 3: 'B', 4: 'E', 5: 'A'})
[1, 2, 3, 4, 5]

Funciones clave

Ambos list.sort() y sorted() tienen un parámetro key para especificar una función (u otra invocable) que se llamará en cada elemento de la lista antes de hacer comparaciones.

Por ejemplo, aquí hay una comparación de cadenas que no distingue entre mayúsculas y minúsculas:

>>> sorted("This is a test string from Andrew".split(), key=str.lower)
['a', 'Andrew', 'from', 'is', 'string', 'test', 'This']

El valor del parámetro key debe ser una función (u otra invocable) que tome un solo argumento y devuelva una clave para usar con fines de clasificación. Esta técnica es rápida porque la función de la tecla se llama exactamente una vez para cada registro de entrada.

Un uso frecuente es ordenar objetos complejos utilizando algunos de los índices del objeto como claves. Por ejemplo:

>>> student_tuples = [
...     ('john', 'A', 15),
...     ('jane', 'B', 12),
...     ('dave', 'B', 10),
... ]
>>> sorted(student_tuples, key=lambda student: student[2])   # sort by age
[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]

La misma técnica funciona para objetos con atributos nombrados. Por ejemplo:

>>> class Student:
...     def __init__(self, name, grade, age):
...         self.name = name
...         self.grade = grade
...         self.age = age
...     def __repr__(self):
...         return repr((self.name, self.grade, self.age))

>>> student_objects = [
...     Student('john', 'A', 15),
...     Student('jane', 'B', 12),
...     Student('dave', 'B', 10),
... ]
>>> sorted(student_objects, key=lambda student: student.age)   # sort by age
[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]

Funciones del módulo operator

Las funciones clave utilizadas anteriormente son muy comunes, por lo que Python proporciona funciones para facilitar y agilizar el uso de las funciones de acceso. El módulo operator contiene las funciones itemgetter(), attrgetter(), y methodcaller().

Usando esas funciones, los ejemplos anteriores se vuelven más simples y rápidos:

>>> from operator import itemgetter, attrgetter

>>> sorted(student_tuples, key=itemgetter(2))
[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]

>>> sorted(student_objects, key=attrgetter('age'))
[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]

Las funciones del módulo operator permiten múltiples niveles de clasificación. Por ejemplo, para ordenar por grade y luego por age:

>>> sorted(student_tuples, key=itemgetter(1,2))
[('john', 'A', 15), ('dave', 'B', 10), ('jane', 'B', 12)]

>>> sorted(student_objects, key=attrgetter('grade', 'age'))
[('john', 'A', 15), ('dave', 'B', 10), ('jane', 'B', 12)]

Ascendente y descendente

Ambos list.sort() y sorted() aceptan un parámetro reverse con un valor booleano. Esto se usa para marcar tipos descendentes. Por ejemplo, para obtener los datos de los estudiantes en orden inverso de edad:

>>> sorted(student_tuples, key=itemgetter(2), reverse=True)
[('john', 'A', 15), ('jane', 'B', 12), ('dave', 'B', 10)]

>>> sorted(student_objects, key=attrgetter('age'), reverse=True)
[('john', 'A', 15), ('jane', 'B', 12), ('dave', 'B', 10)]

Estabilidad de ordenamiento y ordenamientos complejos

Se garantiza que las clasificaciones serán estables [https://es.wikipedia.org/wiki/Algoritmo_de_ordenamiento#Estabilidad]. Eso significa que cuando varios registros tienen la misma clave, se conserva su orden original.

>>> data = [('red', 1), ('blue', 1), ('red', 2), ('blue', 2)]
>>> sorted(data, key=itemgetter(0))
[('blue', 1), ('blue', 2), ('red', 1), ('red', 2)]

Observe cómo los dos registros para blue conservan su orden original de modo que se garantice que ('blue', 1) preceda a ('blue', 2).

Esta maravillosa propiedad le permite construir ordenamientos complejos en varias etapas. Por ejemplo, para ordenar los datos de estudiantes en orden descendente por grade y luego ascendente por age, ordene primero por age y luego por grade:

>>> s = sorted(student_objects, key=attrgetter('age'))     # sort on secondary key
>>> sorted(s, key=attrgetter('grade'), reverse=True)       # now sort on primary key, descending
[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]

Esto se puede encapsular en una función que tome una lista y tuplas (atributo, orden) para ordenarlas por múltiples pases.

>>> def multisort(xs, specs):
...     for key, reverse in reversed(specs):
...         xs.sort(key=attrgetter(key), reverse=reverse)
...     return xs

>>> multisort(list(student_objects), (('grade', True), ('age', False)))
[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]

El algoritmo Timsort [https://en.wikipedia.org/wiki/Timsort] utilizado en Python realiza múltiples ordenamientos de manera eficiente porque puede aprovechar cualquier orden ya presente en el conjunto de datos.

El método tradicional utilizando Decorate-Sort-Undecorate

Este patrón de implementación, llamado DSU (por sus siglas en inglés Decorate-Sort-Undecorate), se realiza en tres pasos:

Primero, la lista inicial está «decorada» con nuevos valores que controlarán el orden en que se realizará el pedido.

En segundo lugar, se ordena la lista decorada.

Finalmente, los valores decorados se eliminan, creando una lista que contiene solo los valores iniciales en el nuevo orden.

Por ejemplo, para ordenar los datos de los estudiantes por grade utilizando el enfoque DSU:

>>> decorated = [(student.grade, i, student) for i, student in enumerate(student_objects)]
>>> decorated.sort()
>>> [student for grade, i, student in decorated]               # undecorate
[('john', 'A', 15), ('jane', 'B', 12), ('dave', 'B', 10)]

Esta técnica funciona porque las tuplas se comparan en orden lexicográfico; se comparan los primeros objetos; si hay objetos idénticos, se compara el siguiente objeto, y así sucesivamente.

No es estrictamente necesario en todos los casos incluir el índice i en la lista decorada, pero incluirlo ofrece dos ventajas:

El orden es estable: si dos elementos tienen la misma clave, su orden se conservará en la lista ordenada.

Los elementos originales no tienen que ser comparables porque el orden de las tuplas decoradas estará determinado por, como máximo, los dos primeros elementos. Entonces, por ejemplo, la lista original podría contener números complejos que no se pueden ordenar directamente.

Otro nombre para esta técnica es Transformación Schwartziana [https://en.wikipedia.org/wiki/Schwartzian_transform], después de que Randal L. Schwartz la popularizara entre los programadores de Perl.

Ahora que la clasificación de Python proporciona funciones clave, esta técnica ya no se usa con frecuencia.

El método tradicional utilizando el Parámetro cmp

Muchos constructores presentados en este CÓMO asumen el uso de Python 2.4 o superior. Antes de eso, no había una función sorted() incorporada y el método list.sort() no tomaba los argumentos nombrados. A pesar de esto, todas las versiones de Py2.x admiten el parámetro cmp para manejar la función de comparación especificada por el usuario.

En Py3.0, el parámetro cmp se eliminó por completo (como parte de un mayor esfuerzo para simplificar y unificar el lenguaje, eliminando el conflicto entre las comparaciones enriquecidas y el método mágico __cmp__()).

En Py2.x, se permitió una función opcional a la que se puede llamar para hacer las comparaciones. Esa función debe tomar dos argumentos para comparar y luego retornar un valor negativo para menor que, retornar cero si son iguales o retornar un valor positivo para mayor que. Por ejemplo, podemos hacer:

>>> def numeric_compare(x, y):
...     return x - y
>>> sorted([5, 2, 4, 1, 3], cmp=numeric_compare)
[1, 2, 3, 4, 5]

O puede revertir el orden de comparación con:

>>> def reverse_numeric(x, y):
...     return y - x
>>> sorted([5, 2, 4, 1, 3], cmp=reverse_numeric)
[5, 4, 3, 2, 1]

Al migrar código de Python 2.x a 3.x, pueden surgir problemas cuando los usuarios proporcionan una función de comparación y es necesario convertir esta función en una función clave. El siguiente paquete hace que sea fácil de hacer:

def cmp_to_key(mycmp):
    'Convert a cmp= function into a key= function'
    class K:
        def __init__(self, obj, *args):
            self.obj = obj
        def __lt__(self, other):
            return mycmp(self.obj, other.obj) < 0
        def __gt__(self, other):
            return mycmp(self.obj, other.obj) > 0
        def __eq__(self, other):
            return mycmp(self.obj, other.obj) == 0
        def __le__(self, other):
            return mycmp(self.obj, other.obj) <= 0
        def __ge__(self, other):
            return mycmp(self.obj, other.obj) >= 0
        def __ne__(self, other):
            return mycmp(self.obj, other.obj) != 0
    return K

Para convertir a una función clave, simplemente ajuste la antigua función de comparación:

>>> sorted([5, 2, 4, 1, 3], key=cmp_to_key(reverse_numeric))
[5, 4, 3, 2, 1]

En Python 3.2, la función functools.cmp_to_key() se agregó al módulo functools en la biblioteca estándar.

Comentarios finales

Para una ordenación local, use locale.strxfrm() para una función clave o locale.strcoll() para una función de comparación.

El parámetro reverse aún mantiene estabilidad de ordenamiento (de modo que los registros con claves iguales conservan el orden original). Curiosamente, ese efecto se puede simular sin el parámetro utilizando la función incorporada reversed() dos veces:

>>> data = [('red', 1), ('blue', 1), ('red', 2), ('blue', 2)]
>>> standard_way = sorted(data, key=itemgetter(0), reverse=True)
>>> double_reversed = list(reversed(sorted(reversed(data), key=itemgetter(0))))
>>> assert standard_way == double_reversed
>>> standard_way
[('red', 1), ('red', 2), ('blue', 1), ('blue', 2)]

The sort routines use < when making comparisons between two objects. So, it is easy to add a standard sort order to a class by defining an __lt__() method:

>>> Student.__lt__ = lambda self, other: self.age < other.age
>>> sorted(student_objects)
[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]

However, note that < can fall back to using __gt__() if __lt__() is not implemented (see object.__lt__()).

Las funciones clave no necesitan depender directamente de los objetos que se ordenan. Una función clave también puede acceder a recursos externos. Por ejemplo, si las calificaciones de los estudiantes se almacenan en un diccionario, se pueden usar para ordenar una lista separada de nombres de estudiantes:

>>> students = ['dave', 'john', 'jane']
>>> newgrades = {'john': 'F', 'jane':'A', 'dave': 'C'}
>>> sorted(students, key=newgrades.__getitem__)
['jane', 'dave', 'john']

CÓMO (HOWTO) Unicode

Lanzamiento

1.12

Este CÓMO (HOWTO) debate el soporte de Python para la especificación Unicode para representar datos textuales, y explica varios problemas que comúnmente encuentra la gente cuando tratan de trabajar con Unicode.

Introducción a Unicode

Definiciones

Los programas de hoy necesitan poder manejar una amplia variedad de caracteres. Las aplicaciones son a menudo internacionalizadas para mostrar mensajes y resultados en una variedad de idiomas seleccionables por el usuario; Es posible que el mismo programa necesite generar un mensaje de error en inglés, francés, japonés, hebreo o ruso. El contenido web se puede escribir en cualquiera de estos idiomas y también puede incluir una variedad de símbolos emoji. El tipo cadena de Python utiliza el estándar Unicode para representar caracteres, lo que permite a los programas de Python trabajar con todos estos caracteres posibles diferentes.

Unicode (https://www.unicode.org/) es una especificación que apunta a listar cada carácter usado por lenguajes humanos y darle a cada carácter su propio código único. La especificación Unicode es continuamente revisada y actualizada para añadir nuevos lenguajes y símbolos.

Un carácter es el componente mas pequeño posible de un texto. “A”, “B”, “C”, etc., son todos diferentes caracteres. También lo son “È” e “Í”. Los caracteres varían dependiendo del lenguaje o del contexto en el que estás hablando. Por ejemplo, Existe un carácter para el «Número Uno Romano», “I”, que es distinto de la letra “I” mayúscula. Estos usualmente lucen igual, pero son dos caracteres diferentes que tienen distintos significados.

El estándar Unicode describe cómo se representan los caracteres mediante puntos de código. Un valor de punto de código es un número entero en el rango de 0 a 0x10FFFF (aproximadamente 1.1 millones de valores, el número real asignado [https://www.unicode.org/versions/latest/#Summary] es menor que eso). En el estándar y en este documento, un punto de código se escribe usando la notación U+265E para significar el carácter con valor 0x265e (9,822 en decimal).

El estándar Unicode contiene muchas tablas que enumeran caracteres y sus puntos de código correspondientes:

0061    'a'; LATIN SMALL LETTER A
0062    'b'; LATIN SMALL LETTER B
0063    'c'; LATIN SMALL LETTER C
...
007B    '{'; LEFT CURLY BRACKET
...
2167    'Ⅷ'; ROMAN NUMERAL EIGHT
2168    'Ⅸ'; ROMAN NUMERAL NINE
...
265E    '♞'; BLACK CHESS KNIGHT
265F    '♟'; BLACK CHESS PAWN
...
1F600   '😀'; GRINNING FACE
1F609   '😉'; WINKING FACE
...

Estrictamente, estas definiciones implican que no tiene sentido decir “este es el carácter U+265E. U+265E es un punto de código, que representa algún carácter en particular; en este caso, representa el carácter “CABALLERO AJEDREZ NEGRO”, “♞”. En contextos informales, esta distinción entre puntos de código y caracteres a veces se olvidará.

Un carácter es representado en una pantalla o en papel por un conjunto de elementos gráficos llamado glifo. El glifo para una A mayúscula, por ejemplo, es dos trazos diagonales y uno horizontal, aunque los detalles exactos van a depender de la fuente utilizada. La mayoría del código de Python no necesita preocuparse por los glifos; averiguar el glifo correcto para mostrar es generalmente el trabajo de un kit de herramientas GUI o el renderizador de fuentes de una terminal.

Codificaciones

Para resumir la sección anterior: Una cadena Unicode es una secuencia de código de posiciones que son números desde 0 hasta 0x10FFFF (1114111 decimal). Esta secuencia de código de posiciones necesita ser representada en memoria como un conjunto de unidades de código, y las unidades de código son mapeadas a bytes de 8 bits. Las reglas para traducir una cadena Unicode a una secuencia de bytes son llamadas Codificación de carácter, o sólo una codificación.

La primera codificación en que podrías pensar es usar enteros de 32 bits como unidad de código, y luego usar la representación de la CPU de enteros de 32 bits. En esta representación, la cadena «Python» podría verse así:

   P           y           t           h           o           n
0x50 00 00 00 79 00 00 00 74 00 00 00 68 00 00 00 6f 00 00 00 6e 00 00 00
   0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

Esta representación es sencilla pero utilizarla presenta una serie de problemas.

No es portable; diferentes procesadores ordenan los bytes de manera diferente.

Es un desperdicio de espacio. En la mayoría de los textos, la mayoría de los códigos de posición son menos de 127, o menos de 255, por lo que una gran cantidad de espacio está ocupado por bytes 0x00. La cadena anterior toma 24 bytes en comparación con los 6 bytes necesarios para una representación ASCII. El aumento en el uso de RAM no importa demasiado (las computadoras de escritorio tienen gigabytes de RAM, y las cadenas no suelen ser tan grandes), pero expandir nuestro uso del disco y el ancho de banda de la red en un factor de 4 es intolerable.

No es compatible con funciones existentes en C como strlen(), para eso se necesitaría una nueva familia de funciones de cadenas.

Por lo tanto esta codificación no es muy utilizada, y la gente prefiere elegir codificaciones que son mas eficientes y convenientes, como UTF-8.

UTF-8 es una de las codificaciones mas utilizadas, y Python generalmente la usa de forma predeterminada. UTF significa «Unicode Transformation Format», y el «8» significa que se utilizan valores de 8 bits en la codificación. (También hay codificaciones UTF-16 y UTF-32, pero son menos frecuentes que UTF-8.) UTF-8 usa las siguientes reglas:

Si el código de posición is < 128, es representado por el valor de byte correspondiente.

Si el código de posición es >= 128, se transforma en una secuencia de dos, tres, o cuatro bytes, donde cada byte de la secuencia está entre 128 y 255.

UTF-8 tiene varias propiedades convenientes:

Puede manejar cualquier punto de código Unicode.

Una cadena Unicode se convierte en una secuencia de bytes que contiene cero bytes incrustados solo donde representan el carácter nulo (U+0000). Esto significa que las cadenas UTF-8 pueden ser procesadas por funciones C como strcpy() y enviadas a través de protocolos que no pueden manejar cero bytes para nada más que marcadores de fin de cadena de caracteres.

Una cadena de texto ASCII es también texto UTF-8.

UTF-8 es bastante compacto; La mayoría de los caracteres comúnmente usados pueden ser representados con uno o dos bytes.

Si los bytes están corruptos o perdidos, es posible determinar el comienzo del próximo código de posición y re-sincronizar. También es poco probable que datos aleatorios de 8 bit se vean como UTF-8 válido.

UTF-8 es una codificación orientada a bytes. La codificación especifica que cada carácter está representado por una secuencia específica de uno o más bytes. Esto evita los problemas de ordenamiento de bytes que pueden ocurrir con codificaciones orientadas a números enteros y palabras, como UTF-16 y UTF-32, donde la secuencia de bytes varía según el hardware en el que se codificó la cadena.

Referencias

El sitio del Consorcio Unicode [https://www.unicode.org] tiene gráficos de caracteres, un glosario y versiones en PDF de la especificación Unicode. Esté preparado para una lectura difícil. Una cronología [https://www.unicode.org/history/] del origen y desarrollo de Unicode también está disponible en el sitio.

En el canal de Youtube Computerphile, Tom Scott discute brevemente la historia de Unicode y UTF-8 <https://www.youtube.com/watch?v=MijmeoH9LT4> (9 minutos 36 segundos).

Para ayudar a entender el estándar, Jukka Korpela escribió una guía introductoria [http://jkorpela.fi/unicode/guide.html] para leer tablas de caracteres Unicode.

Otro buen articulo introductorio [https://www.joelonsoftware.com/2003/10/08/the-absolute-minimum-every-software-developer-absolutely-positively-must-know-about-unicode-and-character-sets-no-excuses/] fue escrito por Joel Spolsky. Si esta introducción no aclara las cosas para usted, debería tratar leyendo este articulo alternativo antes de continuar.

Artículos de Wikipedia son a menudo útiles. Mire los artículos para «codificación de caracteres [https://es.wikipedia.org/wiki/Codificaci%C3%B3n_de_caracteres]» y UTF-8 [https://es.wikipedia.org/wiki/UTF-8], por ejemplo.

Soporte Unicode de Python

Ahora que ya ha aprendido los rudimentos de Unicode, podemos mirar las características de Unicode de Python.

El tipo cadena

Desde Python 3.0, el tipo str del lenguaje contiene caracteres Unicode, lo que significa que cualquier cadena creada usando "unicode rocks!", 'unicode rocks!', o la sintaxis de cadena entre comillas triples es almacenado como Unicode.

La codificación predeterminada para el código fuente de Python es UTF-8, por lo que simplemente puede incluir un carácter Unicode en un literal de cadena de caracteres:

try:
    with open('/tmp/input.txt', 'r') as f:
        ...
except OSError:
    # 'File not found' error message.
    print("Fichier non trouvé")

Nota al margen: Python 3 también soporta el uso de caracteres Unicode en identificadores:

répertoire = "/tmp/records.log"
with open(répertoire, "w") as f:
    f.write("test\n")

Si no puede ingresar un carácter en particular en su editor o desea mantener el código fuente solo ASCII por alguna razón, también puede usar secuencias de escape en cadenas de caracteres literales. (Dependiendo de su sistema, es posible que vea el glifo delta de mayúsculas en lugar de un escape u):

>>> "\N{GREEK CAPITAL LETTER DELTA}"  # Using the character name
'\u0394'
>>> "\u0394"                          # Using a 16-bit hex value
'\u0394'
>>> "\U00000394"                      # Using a 32-bit hex value
'\u0394'

Además, uno puede crear una cadena usando el método decode() de la clase bytes. Este método recibe una codificación como argumento, como UTF-8, y opcionalmente un argumento errores.

El argumento errores especifica la respuesta cuando la cadena ingresada no puede ser convertida de acuerdo a las reglas de codificación. Los posibles valores para este argumento son 'strict' (levanta una excepción UnicodeDecodeError), 'replace' (use U+FFFD'', ``CARACTER DE REEMPLAZO} ``), ``'ignore' (solo deje el carácter fuera del resultado Unicode), o 'backslahsreplace' (inserta una secuencia de escape \xNN). Los siguientes ejemplos muestran las diferencias

>>> b'\x80abc'.decode("utf-8", "strict")
Traceback (most recent call last):
    ...
UnicodeDecodeError: 'utf-8' codec can't decode byte 0x80 in position 0:
  invalid start byte
>>> b'\x80abc'.decode("utf-8", "replace")
'\ufffdabc'
>>> b'\x80abc'.decode("utf-8", "backslashreplace")
'\\x80abc'
>>> b'\x80abc'.decode("utf-8", "ignore")
'abc'

Las codificaciones son especificadas como cadenas que contienen el nombre de la codificación. Python viene con cerca de 100 codificaciones diferentes; consulta la referencia de la biblioteca de Python en Codificaciones estándar para una lista. Algunas codificaciones tienen múltiples nombres; por ejemplo, 'latin-1', 'iso_8859_1' y '8859” son sinónimos para la misma codificación.

Las cadenas de un solo carácter pueden ser creadas también con la función incorporada chr(), que toma un entero y retorna una cadena Unicode de longitud 1 que contiene el correspondiente código de posición. La operación inversa es la función incorporada ord() que toma una cadena Unicode de un carácter y retorna el código de posición:

>>> chr(57344)
'\ue000'
>>> ord('\ue000')
57344

Convirtiendo a Bytes

El método opuesto a bytes.decode() es str.encode(), que retorna una representación de bytes de la cadena Unicode, codificada en la codificación solicitada.

El parámetro errores es el mismo que el parámetro del método decode() pero soporta algunos manejadores mas.

El siguiente ejemplo muestra los diferentes resultados:

>>> u = chr(40960) + 'abcd' + chr(1972)
>>> u.encode('utf-8')
b'\xea\x80\x80abcd\xde\xb4'
>>> u.encode('ascii')
Traceback (most recent call last):
    ...
UnicodeEncodeError: 'ascii' codec can't encode character '\ua000' in
  position 0: ordinal not in range(128)
>>> u.encode('ascii', 'ignore')
b'abcd'
>>> u.encode('ascii', 'replace')
b'?abcd?'
>>> u.encode('ascii', 'xmlcharrefreplace')
b'&#40960;abcd&#1972;'
>>> u.encode('ascii', 'backslashreplace')
b'\\ua000abcd\\u07b4'
>>> u.encode('ascii', 'namereplace')
b'\\N{YI SYLLABLE IT}abcd\\u07b4'

Las rutinas de bajo nivel para registrar y acceder a las codificaciones disponibles se encuentran en el módulo codecs. La implementación de nuevas codificaciones también requiere comprender el módulo codecs. Sin embargo, las funciones de codificación y decodificación retornadas por este módulo generalmente son de nivel más bajo de lo que es cómodo, y escribir nuevas codificaciones es una tarea especializada, por lo que el módulo no se cubrirá en este CÓMO.

Literales Unicode en código fuente Python

En el código fuente de Python, se pueden escribir puntos de código Unicode específicos utilizando la secuencia de escape \u, que es seguida por cuatro dígitos hexadecimales que dan el punto de código. La secuencia de escape \U es similar, pero espera ocho dígitos hexadecimales, no cuatro:

>>> s = "a\xac\u1234\u20ac\U00008000"
... #     ^^^^ two-digit hex escape
... #         ^^^^^^ four-digit Unicode escape
... #                     ^^^^^^^^^^ eight-digit Unicode escape
>>> [ord(c) for c in s]
[97, 172, 4660, 8364, 32768]

El uso de secuencias de escape para puntos de código superiores a 127 está bien en pequeñas dosis, pero se convierte en una molestia si está utilizando muchos caracteres acentuados, como lo haría en un programa con mensajes en francés o algún otro lenguaje que utilice acento. También puede ensamblar cadenas usando la función incorporada chr(), pero esto es aún más tedioso.

Idealmente, desearía poder escribir literales en la codificación natural de su idioma. Luego, puede editar el código fuente de Python con su editor favorito, que mostrará los caracteres acentuados de forma natural y tendrá los caracteres correctos utilizados en tiempo de ejecución.

Python soporta la escritura de código fuente en UTF-8 de forma predeterminada, pero puede usar casi cualquier codificación si declara la codificación que está utilizando. Esto se hace mediante la inclusión de un comentario especial en la primera o segunda línea del archivo fuente:

#!/usr/bin/env python
# -*- coding: latin-1 -*-

u = 'abcdé'
print(ord(u[-1]))

La sintaxis está inspirada en la notación de Emacs para especificar variables locales a un archivo. Emacs admite muchas variables diferentes, pero Python solo admite “coding”. Los símbolos - * - indican a Emacs que el comentario es especial; no tienen importancia para Python pero son una convención. Python busca coding: name o coding=name en el comentario.

Si no incluye dicho comentario, la codificación predeterminada utilizada será UTF-8 como ya se mencionó. Ver también PEP 263 [https://www.python.org/dev/peps/pep-0263] para más información.

Propiedades Unicode

La especificación Unicode incluye una base de datos de información sobre puntos de código. Para cada punto de código definido, la información incluye el nombre del carácter, su categoría, el valor numérico si corresponde (para caracteres que representan conceptos numéricos como los números romanos, fracciones como un tercio y cuatro quintos, etc.). También hay propiedades relacionadas con la visualización, como cómo usar el punto de código en texto bidireccional.

El siguiente programa muestra información sobre varios caracteres e imprime el valor numérico de un carácter en particular:

import unicodedata

u = chr(233) + chr(0x0bf2) + chr(3972) + chr(6000) + chr(13231)

for i, c in enumerate(u):
    print(i, '%04x' % ord(c), unicodedata.category(c), end=" ")
    print(unicodedata.name(c))

# Get numeric value of second character
print(unicodedata.numeric(u[1]))

Cuando se ejecuta, este imprime:

0 00e9 Ll LATIN SMALL LETTER E WITH ACUTE
1 0bf2 No TAMIL NUMBER ONE THOUSAND
2 0f84 Mn TIBETAN MARK HALANTA
3 1770 Lo TAGBANWA LETTER SA
4 33af So SQUARE RAD OVER S SQUARED
1000.0

Los códigos de categoría son abreviaturas que describen la naturaleza del personaje. Estos se agrupan en categorías como «Letra», «Número», «Puntuación» o «Símbolo», que a su vez se dividen en subcategorías. Para tomar los códigos de la salida anterior, 'Ll' significa “Letra, minúscula “, 'No' significa «Número, otro», 'Mn' es «Marca, sin espacios» , y 'So' es «Símbolo, otro». Consulte la sección Valores de categoría generales de la documentación de la base de datos de caracteres Unicode [https://www.unicode.org/reports/tr44/#General_Category_Values] para obtener una lista de códigos de categoría.

Comparando cadenas

Unicode agrega algunas complicaciones a la comparación de cadenas, porque el mismo conjunto de caracteres puede representarse mediante diferentes secuencias de puntos de código. Por ejemplo, una letra como “ê” puede representarse como un único punto de código U+00EA, o como U+0065 U+0302, que es el punto de código para “e” seguido de un punto de código para “COMBINING CIRCUMFLEX ACCENT” . Estos producirán la misma salida cuando se impriman, pero uno es una cadena de longitud 1 y el otro es de longitud 2.

Una herramienta para una comparación que no distingue entre mayúsculas y minúsculas es el método casefold() que convierte una cadena en una forma que no distingue entre mayúsculas y minúsculas siguiendo un algoritmo descrito por el estándar Unicode. Este algoritmo tiene un manejo especial para caracteres como la letra Alemana “ß” (punto de código U+00DF), que se convierte en el par de letras minúsculas “ss”.

>>> street = 'Gürzenichstraße'
>>> street.casefold()
'gürzenichstrasse'

Una segunda herramienta es la función normalize() del módulo unicodedata que convierte las cadenas en una de varias formas normales, donde las letras seguidas de un carácter de combinación se reemplazan con caracteres individuales. normalize() puede usarse para realizar comparaciones de cadenas que no informarán falsamente la desigualdad si dos cadenas usan caracteres combinados de manera diferente:

import unicodedata

def compare_strs(s1, s2):
    def NFD(s):
        return unicodedata.normalize('NFD', s)

    return NFD(s1) == NFD(s2)

single_char = 'ê'
multiple_chars = '\N{LATIN SMALL LETTER E}\N{COMBINING CIRCUMFLEX ACCENT}'
print('length of first string=', len(single_char))
print('length of second string=', len(multiple_chars))
print(compare_strs(single_char, multiple_chars))

Cuando se ejecuta, esto genera:

$ python3 compare-strs.py
length of first string= 1
length of second string= 2
True

El primer argumento para la función normalize() es una cadena que proporciona la forma de normalización deseada, que puede ser una de “NFC”, “NFKC”, “NFD” y “NFKD”.

El estándar Unicode también especifica cómo hacer comparaciones sin mayúsculas y minúsculas:

import unicodedata

def compare_caseless(s1, s2):
    def NFD(s):
        return unicodedata.normalize('NFD', s)

    return NFD(NFD(s1).casefold()) == NFD(NFD(s2).casefold())

# Example usage
single_char = 'ê'
multiple_chars = '\N{LATIN CAPITAL LETTER E}\N{COMBINING CIRCUMFLEX ACCENT}'

print(compare_caseless(single_char, multiple_chars))

Esto imprimirá Verdadero. (¿Por qué se invoca dos veces NFD()? Debido a que hay algunos caracteres que hacen que casefold() devuelva una cadena no normalizada, por lo que el resultado debe normalizarse nuevamente. Consulte la sección 3.13 del Estándar Unicode para una discusión y un ejemplo.)

Expresiones Regulares Unicode

Las expresiones regulares soportadas por el módulo re se pueden proporcionar como bytes o cadenas. Algunas de las secuencias de caracteres especiales como \d y \w tienen diferentes significados dependiendo de si el patrón se suministra como bytes o una cadena. Por ejemplo, \d coincidirá con los caracteres [0-9] en bytes, pero en las cadenas coincidirá con cualquier carácter que esté en la categoría 'Nd'.

La cadena en este ejemplo tiene el número 57 escrito en números tailandeses y árabes:

import re
p = re.compile(r'\d+')

s = "Over \u0e55\u0e57 57 flavours"
m = p.search(s)
print(repr(m.group()))

Cuando se ejecuta, \d+ coincidirá con los números tailandeses y los imprimirá. Si proporciona el indicador re.ASCII a compile(), \d+ coincidirá con la subcadena «57» en su lugar.

Del mismo modo, \w coincide con una amplia variedad de caracteres Unicode pero solo [a-zA-Z0-9_] en bytes o si re.ASCII se suministra, y \s coincidirá con los caracteres de espacio en blanco Unicode o [ \t\n\r\f\v].

Referencias

Algunas buenas discusiones alternativas sobre el soporte Unicode de Python son:

Processing Text Files in Python 3 [http://python-notes.curiousefficiency.org/en/latest/python3/text_file_processing.html], por Nick Coghlan.

Pragmatic Unicode [https://nedbatchelder.com/text/unipain.html], una presentación de Ned Batchelder en PyCon 2012.

El tipo str se describe en la referencia de la biblioteca de Python en Cadenas de caracteres — str.

La documentación para el módulo unicodedata.

La documentación para el módulo codecs.

Marc-André Lemburg hizo una presentación titulada «Python and Unicode» (diapositivas en PDF) <https://downloads.egenix.com/python/Unicode-EPC2002-Talk.pdf>`_ en EuroPython 2002. Las diapositivas son una excelente descripción general del diseño de las características Unicode de Python 2 (donde el tipo de cadena Unicode se llama unicode y los literales comienzan con u).

Leyendo y escribiendo datos Unicode

Una vez que haya escrito un código que funcione con datos Unicode, el siguiente problema es la entrada/salida. ¿Cómo obtiene cadenas Unicode en su programa y cómo convierte Unicode en una forma adecuada para almacenamiento o transmisión?

Es posible que no necesite hacer nada dependiendo de sus fuentes de entrada y destinos de salida; debe verificar si las bibliotecas utilizadas en su aplicación son compatibles con Unicode de forma nativa. Los analizadores XML a menudo retornan datos Unicode, por ejemplo. Muchas bases de datos relacionales también admiten columnas con valores Unicode y pueden retornar valores Unicode de una consulta SQL.

Los datos Unicode generalmente se convierten a una codificación particular antes de escribirse en el disco o enviarse a través de un socket. Es posible hacer todo el trabajo usted mismo: abra un archivo, lea un objeto de bytes de 8 bits y convierta los bytes con bytes.decode(codificación). Sin embargo, no se recomienda el enfoque manual.

Un problema es la naturaleza de múltiples bytes de las codificaciones; Un carácter Unicode puede ser representado por varios bytes. Si desea leer el archivo en fragmentos de tamaño arbitrario (por ejemplo, 1024 o 4096 bytes), debe escribir un código de manejo de errores para detectar el caso en el que solo una parte de los bytes que codifican un solo carácter Unicode se leen al final de Un trozo. Una solución sería leer todo el archivo en la memoria y luego realizar la decodificación, pero eso le impide trabajar con archivos que son extremadamente grandes; si necesita leer un archivo de 2 GB, necesita 2 GB de RAM. (Más, realmente, ya que por al menos un momento necesitarías tener tanto la cadena codificada como su versión Unicode en la memoria).

La solución sería utilizar la interfaz de decodificación de bajo nivel para detectar el caso de secuencias de codificación parcial. El trabajo de implementar esto ya se ha realizado para usted: la función incorporada open() puede retornar un objeto similar a un archivo que asume que el contenido del archivo está en una codificación especificada y acepta parámetros Unicode para métodos como read() y write(). Esto funciona a través de los parámetros enconding y errors de open() que se interpretan como los de str.encode() y bytes.decode().

Por lo tanto, leer Unicode de un archivo es simple:

with open('unicode.txt', encoding='utf-8') as f:
    for line in f:
        print(repr(line))

También es posible abrir archivos en modo de actualización, lo que permite leer y escribir:

with open('test', encoding='utf-8', mode='w+') as f:
    f.write('\u4500 blah blah blah\n')
    f.seek(0)
    print(repr(f.readline()[:1]))

El carácter Unicode U+FEFF se usa como marca de orden de bytes (BOM), y a menudo se escribe como el primer carácter de un archivo para ayudar a la auto detección del orden de bytes del archivo. Algunas codificaciones, como UTF-16, esperan que haya una BOM al comienzo de un archivo; cuando se utiliza dicha codificación, la BOM se escribirá automáticamente como el primer carácter y se descartará en silencio cuando se lea el archivo. Existen variantes de estas codificaciones, como “utf-16-le” y “utf-16-be” para codificaciones “little-endian” y “big-endian”, que especifican un orden de bytes particular y no omiten la BOM.

En algunas áreas, también es convencional usar una «BOM» al comienzo de los archivos codificados UTF-8; el nombre es engañoso ya que UTF-8 no depende del orden de bytes. La marca simplemente anuncia que el archivo está codificado en UTF-8. Para leer dichos archivos, use el códec “utf-8-sig” para omitir automáticamente la marca si está presente.

Nombres de archivos Unicode

La mayoría de los sistemas operativos de uso común hoy en día admiten nombres de archivo que contienen caracteres Unicode arbitrarios. Por lo general, esto se implementa convirtiendo la cadena Unicode en alguna codificación que varía según el sistema. Hoy Python está convergiendo sobre el uso de UTF-8: Python en MacOS ha usado UTF-8 para varias versiones, y Python 3.6 también cambió a usar UTF-8 en Windows. En los sistemas Unix, solo habrá una codificación del sistema de archivos si ha configurado las variables de entorno LANG o LC_CTYPE; si no lo ha hecho, la codificación predeterminada es nuevamente UTF-8.

La función sys.getfilesystemencoding() retorna la codificación para usar en su sistema actual, en caso de que desee realizar la codificación manualmente, pero no hay muchas razones para molestarse. Al abrir un archivo para leer o escribir, generalmente puede proporcionar la cadena Unicode como nombre de archivo, y se convertirá automáticamente a la codificación correcta para usted:

filename = 'filename\u4500abc'
with open(filename, 'w') as f:
    f.write('blah\n')

Las funciones en el módulo os como os.stat() también aceptarán nombres de archivo Unicode.

La función os.listdir() retorna nombres de archivo, lo que plantea un problema: ¿debería retornar la versión Unicode de los nombres de archivo, o debería retornar bytes que contienen las versiones codificadas? os.listdir() puede hacer ambas cosas, dependiendo de si proporcionó la ruta del directorio como bytes o una cadena Unicode. Si pasa una cadena Unicode como ruta, los nombres de archivo se decodificarán utilizando la codificación del sistema de archivos y se retornará una lista de cadenas Unicode, mientras que al pasar una ruta de bytes se retornarán los nombres de archivo como bytes. Por ejemplo, suponiendo que la codificación predeterminada del sistema de archivos es UTF-8, ejecutando el siguiente programa:

fn = 'filename\u4500abc'
f = open(fn, 'w')
f.close()

import os
print(os.listdir(b'.'))
print(os.listdir('.'))

producirá la siguiente salida:

$ python listdir-test.py
[b'filename\xe4\x94\x80abc', ...]
['filename\u4500abc', ...]

La primera lista contiene nombres de archivos codificados con UTF-8, y la segunda lista contiene las versiones Unicode.

Tenga en cuenta que en la mayoría de las ocasiones, debe seguir usando Unicode con estas API. Las API de bytes solo deben usarse en sistemas donde pueden estar presentes nombres de archivo no codificables; eso es prácticamente solo sistemas Unix ahora.

Consejos para escribir programas compatibles con Unicode

Esta sección proporciona algunas sugerencias sobre cómo escribir software que maneje Unicode.

El consejo más importante es:

El software solo debería funcionar con cadenas Unicode internamente, decodificando los datos de entrada lo antes posible y codificando la salida solo al final.

Si intenta escribir funciones de procesamiento que acepten cadenas Unicode y de bytes, encontrará que su programa es vulnerable a errores dondequiera que combine los dos tipos diferentes de cadenas. No hay codificación o decodificación automática: si hace, por ejemplo: str+bytes, un TypeError se generará.

Cuando se usan datos que provienen de un navegador web u otra fuente no confiable, una técnica común es verificar si hay caracteres ilegales en una cadena antes de usar la cadena en una línea de comando generada o almacenarla en una base de datos. Si está haciendo esto, tenga cuidado de verificar la cadena decodificada, no los datos de bytes codificados; Algunas codificaciones pueden tener propiedades interesantes, como no ser biyectivo o no ser totalmente compatible con ASCII. Esto es especialmente cierto si los datos de entrada también especifican la codificación, ya que el atacante puede elegir una forma inteligente de ocultar el texto malicioso en el flujo de bytes codificado.

Conversión entre codificaciones de archivo

La clase StreamRecoder puede convertir de forma transparente entre codificaciones, tomar una secuencia que retorna datos en la codificación 1 y comportarse como una secuencia que retorna datos en la codificación 2.

Por ejemplo, si tiene un archivo de entrada f que está en Latin-1, puede envolverlo con StreamRecoder para retornar bytes codificados en UTF-8:

new_f = codecs.StreamRecoder(f,
    # en/decoder: used by read() to encode its results and
    # by write() to decode its input.
    codecs.getencoder('utf-8'), codecs.getdecoder('utf-8'),

    # reader/writer: used to read and write to the stream.
    codecs.getreader('latin-1'), codecs.getwriter('latin-1') )

Archivos en una codificación desconocida

¿Qué puede hacer si necesita hacer un cambio en un archivo, pero no conoce la codificación del archivo? Si sabe que la codificación es compatible con ASCII y solo desea examinar o modificar las partes ASCII, puede abrir el archivo con el manejador de errores surrogateescape:

with open(fname, 'r', encoding="ascii", errors="surrogateescape") as f:
    data = f.read()

# make changes to the string 'data'

with open(fname + '.new', 'w',
          encoding="ascii", errors="surrogateescape") as f:
    f.write(data)

El manejador de errores surrogateescape decodificará los bytes que no sean ASCII como puntos de código en un rango especial que va desde U+DC80 a U+DCFF. Estos puntos de código volverán a convertirse en los mismos bytes cuando se use el controlador de error subrogateescape para codificar los datos y volver a escribirlos.

Referencias

Una sección de Mastering Python 3 Input/Output [http://pyvideo.org/video/289/pycon-2010--mastering-python-3-i-o], una charla de David Beazley en la PyCon 2010, analiza el procesamiento de texto y el manejo de datos binarios.

El PDF slides for Marc-André Lemburg’s presentation «Writing Unicode-aware Applications in Python» [https://downloads.egenix.com/python/LSM2005-Developing-Unicode-aware-applications-in-Python.pdf] discute cuestiones de codificaciones de caracteres, así como también cómo internacionalizar y localizar una aplicación. Estas diapositivas cubren solo Python 2.x.

The Guts of Unicode in Python [http://pyvideo.org/video/1768/the-guts-of-unicode-in-python] es una charla de Benjamin Peterson en PyCon 2013 que analiza la representación interna de Unicode en Python 3.3.

Agradecimientos

El borrador inicial de este documento fue escrito por Andrew Kuchling. Desde entonces ha sido revisado por Alexander Belopolsky, Georg Brandl, Andrew Kuchling y Ezio Melotti.

293/5000 Gracias a las siguientes personas que notaron errores u ofrecieron sugerencias sobre este artículo: Éric Araujo, Nicholas Bastin, Nick Coghlan, Marius Gedminas, Kent Johnson, Ken Krugler, Marc-André Lemburg, Martin von Löwis, Terry J. Reedy, Serhiy Storchaka , Eryk Sun, Chad Whitacre, Graham Wideman.

HOWTO - Cómo obtener recursos de Internet con el paquete urllib

Autor

Michael Foord [http://www.voidspace.org.uk/python/index.shtml]

Nota

Hay una traducción al francés de una revisión anterior de este HOWTO, disponible en urllib2 - Le Manuel manquant [http://www.voidspace.org.uk/python/articles/urllib2_francais.shtml].

Introducción

Related Articles

También puedes encontrar útil el siguiente artículo sobre la obtención de recursos web con Python:

Basic Authentication [http://www.voidspace.org.uk/python/articles/authentication.shtml]

Un tutorial sobre Autenticación Básica, con ejemplos en Python.

urllib.request es un módulo Python para acceder y utilizar recursos de internet identificados por URLs (Uniform Resource Locators). Ofrece una interfaz muy simple, a través de la función urlopen. Esta función es capaz de acceder a URLs usando una variedad de protocolos diferentes. También ofrece una interfaz un poco más compleja para manejar situaciones comunes - como la autenticación básica, cookies y proxies, entre otros. Estos son proporcionados por los llamados objetos de apertura y gestores.

urllib.request soporta la obtención de recursos identificados por URLs para muchos «esquemas de URL» (identificados por la cadena de texto ubicada antes del ":" en el URL - por ejemplo "ftp" es el esquema de URL de "ftp://python.org/") usando sus protocolos de red asociados (por ejemplo FTP, HTTP). Este tutorial se centra en el caso más común, HTTP.

Para situaciones sencillas urlopen es muy fácil de usar. Pero tan pronto como encuentres errores o casos no triviales al abrir URLs HTTP, necesitarás entender el Protocolo de Transferencia de Hipertexto. La referencia más completa y autorizada para HTTP es RFC 2616 [https://tools.ietf.org/html/rfc2616.html]. Este es un documento técnico y no pretende ser fácil de leer. Este HOWTO tiene como objetivo ilustrar el uso de la urllib, con suficientes detalles sobre HTTP para ayudarte a entenderlo. No pretende reemplazar los documentos urllib.request, pero es complementario a ellos.

Obtención de URLs

La forma más simple de usar urllib.request es la siguiente:

import urllib.request
with urllib.request.urlopen('http://python.org/') as response:
   html = response.read()

Si deseas recuperar un recurso a partir de la URL y almacenarlo en una ubicación temporal, puede hacerlo a través de las funciones shutil.copyfileobj() y tempfile.NamedTemporaryFile():

import shutil
import tempfile
import urllib.request

with urllib.request.urlopen('http://python.org/') as response:
    with tempfile.NamedTemporaryFile(delete=False) as tmp_file:
        shutil.copyfileobj(response, tmp_file)

with open(tmp_file.name) as html:
    pass

Muchos usos de urllib serán así de sencillos (nótese que en lugar de una URL “http:” podríamos haber usado una URL que empezara por “ftp:”, “file:”, etc.). Sin embargo, el propósito de este tutorial es explicar los casos más complicados, concentrándose en el HTTP.

HTTP se basa en peticiones y respuestas - el cliente hace peticiones y los servidores envían respuestas. urllib.request refleja esto con un objeto Request que representa la petición HTTP que estás haciendo. En su forma más simple se crea un objeto Request que especifica la URL que se quiere obtener. Llamar a urlopen con este objeto Request devuelve un objeto respuesta para la URL solicitada. Esta respuesta es un objeto tipo archivo, lo que significa que puedes por ejemplo llamar a .read() en la respuesta:

import urllib.request

req = urllib.request.Request('http://www.voidspace.org.uk')
with urllib.request.urlopen(req) as response:
   the_page = response.read()

Tenga en cuenta que urllib.request utiliza la misma interfaz de Request para gestionar todos los esquemas de URL. Por ejemplo, puedes hacer una petición FTP de la siguiente manera:

req = urllib.request.Request('ftp://example.com/')

En el caso de HTTP, hay dos cosas adicionales que los objetos Request le permiten hacer: Primero, puede pasar datos para enviarlos al servidor. En segundo lugar, puede pasar información adicional («metadatos») about los datos o sobre la solicitud en sí, al servidor; esta información se envía como «encabezados» HTTP. Veamos cada uno de estos por turno.

Datos

A veces quieres enviar datos a una URL (a menudo la URL se referirá a un script CGI (Common Gateway Interface) u otra aplicación web). Con HTTP, esto se hace a menudo usando lo que se conoce como una petición POST. Esto es a menudo lo que su navegador hace cuando envías un formulario HTML que has rellenado en la web. No todos los POSTs tienen que provenir de formularios: puedes usar un POST para transmitir datos arbitrarios a tu propia aplicación. En el caso común de los formularios HTML, los datos tienen que ser codificados de forma estándar, y luego pasados al objeto Request como el argumento data. La codificación se hace usando una función de la biblioteca urllib.parse`.

import urllib.parse
import urllib.request

url = 'http://www.someserver.com/cgi-bin/register.cgi'
values = {'name' : 'Michael Foord',
          'location' : 'Northampton',
          'language' : 'Python' }

data = urllib.parse.urlencode(values)
data = data.encode('ascii') # data should be bytes
req = urllib.request.Request(url, data)
with urllib.request.urlopen(req) as response:
   the_page = response.read()

Ten en cuenta que a veces se requieren otras codificaciones (por ejemplo, para la carga de archivos desde formularios HTML - ver HTML Specification, Form Submission [https://www.w3.org/TR/REC-html40/interact/forms.html#h-17.13] para más detalles).

Si no pasas el argumento data, urllib usa una petición GET. Una de las formas en la que las peticiones GET y POST difieren entre sí es que las peticiones POST a menudo tienen «efectos secundarios»: cambian el estado del sistema de alguna manera (por ejemplo, haciendo una petición al sitio para que un centenar de spam chatarra sea entregado a tu dirección). Aunque el estándar HTTP deja claro que las solicitudes POST están siempre destinadas a causar efectos secundarios, y las solicitudes GET a nunca causar efectos secundarios, nada impide que una solicitud GET tenga efectos secundarios, ni que una solicitud POST no tenga efectos secundarios. Los datos también pueden ser pasados en una solicitud GET HTTP codificándolos en la propia URL.

Esto se hace de la siguiente manera:

>>> import urllib.request
>>> import urllib.parse
>>> data = {}
>>> data['name'] = 'Somebody Here'
>>> data['location'] = 'Northampton'
>>> data['language'] = 'Python'
>>> url_values = urllib.parse.urlencode(data)
>>> print(url_values)  # The order may differ from below.
name=Somebody+Here&language=Python&location=Northampton
>>> url = 'http://www.example.com/example.cgi'
>>> full_url = url + '?' + url_values
>>> data = urllib.request.urlopen(full_url)

Nota que la URL completa se crea añadiendo un ? a la URL, seguido de los valores codificados.

Encabezados (Headers)

Discutiremos aquí un encabezado HTTP en particular, para ilustrar cómo agregar encabezados a su solicitud HTTP.

A algunos sitios web 1 no les gusta ser navegados por programas, o envían diferentes versiones a diferentes navegadores 2. Por defecto urllib se identifica como Python-urllib/x.y (donde x y y son los números mayor y menor de la versión de Python, por ejemplo Python-urllib/2.5), lo que puede confundir el sitio, o simplemente no funcionar. La forma en que un navegador se identifica a sí mismo es a través del encabezado User-Agent 3. Cuando creas un objeto Request puedes pasarle un diccionario de encabezados. El siguiente ejemplo hace la misma petición que arriba, pero se identifica como una versión de Internet Explorer 4.

import urllib.parse
import urllib.request

url = 'http://www.someserver.com/cgi-bin/register.cgi'
user_agent = 'Mozilla/5.0 (Windows NT 6.1; Win64; x64)'
values = {'name': 'Michael Foord',
          'location': 'Northampton',
          'language': 'Python' }
headers = {'User-Agent': user_agent}

data = urllib.parse.urlencode(values)
data = data.encode('ascii')
req = urllib.request.Request(url, data, headers)
with urllib.request.urlopen(req) as response:
   the_page = response.read()

La respuesta también tiene dos métodos útiles. Ver la sección de info y geturl que viene después de que echemos un vistazo a lo que pasa cuando las cosas van mal.

Gestión de excepciones

urlopen genera URLError cuando no puede gestionar una respuesta (aunque como es habitual en las APIs de Python, también se pueden generar excepciones predefinidas tales como ValueError, TypeError etc.).

HTTPError es la subclase de URLError generada en el caso específico de las URLs HTTP.

Las clases de excepción se exportan desde el módulo urllib.error.

URLError

A menudo, URLError se genera porque no hay conexión de red (no se encuentra ruta al servidor especificado), o el servidor especificado no existe. En este caso, la excepción generada tendrá un atributo «reason», que es una tupla que contiene un código de error y un mensaje de error de texto.

por ejemplo

>>> req = urllib.request.Request('http://www.pretend_server.org')
>>> try: urllib.request.urlopen(req)
... except urllib.error.URLError as e:
...     print(e.reason)
...
(4, 'getaddrinfo failed')

HTTPError

Cada respuesta HTTP del servidor contiene un «código de estado» numérico. A veces el código de estado indica que el servidor es incapaz de satisfacer la petición. Los gestores predeterminados se encargarán de algunas de estas respuestas automáticamente (por ejemplo, si la respuesta es una «redirección» que solicita que el cliente obtenga el documento desde una URL diferente, urllib se encargará de eso por ti). Para aquellas respuestas que no puede manejar, urlopen generará un HTTPError. Los errores típicos incluyen “404” (página no encontrada), “403” (petición prohibida), y “401” (autenticación requerida).

Vea la sección 10 de RFC 2616 [https://tools.ietf.org/html/rfc2616.html] para una referencia sobre todos los códigos de error HTTP.

La instancia HTTPError generada tendrá un atributo de “código” numérico de tipo entero, que corresponde al error enviado por el servidor.

Códigos de Error

Debido a que los gestores por defecto gestionan redirecciones (códigos en el rango de 300), y que los códigos en el rango de 100–299 indican éxito, normalmente sólo verás códigos de error en el rango de 400–599.

http.server.BaseHTTPRequestHandler.responses es un diccionario útil de códigos de respuesta en el que se muestran todos los códigos de respuesta utilizados por RFC 2616 [https://tools.ietf.org/html/rfc2616.html]. El diccionario se reproduce aquí por conveniencia

# Table mapping response codes to messages; entries have the
# form {code: (shortmessage, longmessage)}.
responses = {
    100: ('Continue', 'Request received, please continue'),
    101: ('Switching Protocols',
          'Switching to new protocol; obey Upgrade header'),

    200: ('OK', 'Request fulfilled, document follows'),
    201: ('Created', 'Document created, URL follows'),
    202: ('Accepted',
          'Request accepted, processing continues off-line'),
    203: ('Non-Authoritative Information', 'Request fulfilled from cache'),
    204: ('No Content', 'Request fulfilled, nothing follows'),
    205: ('Reset Content', 'Clear input form for further input.'),
    206: ('Partial Content', 'Partial content follows.'),

    300: ('Multiple Choices',
          'Object has several resources -- see URI list'),
    301: ('Moved Permanently', 'Object moved permanently -- see URI list'),
    302: ('Found', 'Object moved temporarily -- see URI list'),
    303: ('See Other', 'Object moved -- see Method and URL list'),
    304: ('Not Modified',
          'Document has not changed since given time'),
    305: ('Use Proxy',
          'You must use proxy specified in Location to access this '
          'resource.'),
    307: ('Temporary Redirect',
          'Object moved temporarily -- see URI list'),

    400: ('Bad Request',
          'Bad request syntax or unsupported method'),
    401: ('Unauthorized',
          'No permission -- see authorization schemes'),
    402: ('Payment Required',
          'No payment -- see charging schemes'),
    403: ('Forbidden',
          'Request forbidden -- authorization will not help'),
    404: ('Not Found', 'Nothing matches the given URI'),
    405: ('Method Not Allowed',
          'Specified method is invalid for this server.'),
    406: ('Not Acceptable', 'URI not available in preferred format.'),
    407: ('Proxy Authentication Required', 'You must authenticate with '
          'this proxy before proceeding.'),
    408: ('Request Timeout', 'Request timed out; try again later.'),
    409: ('Conflict', 'Request conflict.'),
    410: ('Gone',
          'URI no longer exists and has been permanently removed.'),
    411: ('Length Required', 'Client must specify Content-Length.'),
    412: ('Precondition Failed', 'Precondition in headers is false.'),
    413: ('Request Entity Too Large', 'Entity is too large.'),
    414: ('Request-URI Too Long', 'URI is too long.'),
    415: ('Unsupported Media Type', 'Entity body in unsupported format.'),
    416: ('Requested Range Not Satisfiable',
          'Cannot satisfy request range.'),
    417: ('Expectation Failed',
          'Expect condition could not be satisfied.'),

    500: ('Internal Server Error', 'Server got itself in trouble'),
    501: ('Not Implemented',
          'Server does not support this operation'),
    502: ('Bad Gateway', 'Invalid responses from another server/proxy.'),
    503: ('Service Unavailable',
          'The server cannot process the request due to a high load'),
    504: ('Gateway Timeout',
          'The gateway server did not receive a timely response'),
    505: ('HTTP Version Not Supported', 'Cannot fulfill request.'),
    }

Cuando se genera un error, el servidor responde retornando un código de error HTTP y una página de error. Puedes usar la instancia HTTPError como respuesta en la página devuelta. Esto significa que además del atributo de código, también tiene los métodos read, geturl, e info, tal y como son devueltos por el módulo urllib.response:

>>> req = urllib.request.Request('http://www.python.org/fish.html')
>>> try:
...     urllib.request.urlopen(req)
... except urllib.error.HTTPError as e:
...     print(e.code)
...     print(e.read())
...
404
b'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">\n\n\n<html
  ...
  <title>Page Not Found</title>\n
  ...

Resumiéndolo

Si quieres estar preparado para HTTPError o URLError hay dos enfoques básicos. Prefiero el segundo enfoque.

Número 1

from urllib.request import Request, urlopen
from urllib.error import URLError, HTTPError
req = Request(someurl)
try:
    response = urlopen(req)
except HTTPError as e:
    print('The server couldn\'t fulfill the request.')
    print('Error code: ', e.code)
except URLError as e:
    print('We failed to reach a server.')
    print('Reason: ', e.reason)
else:
    # everything is fine

Nota

El error except HTTPError debe ser lo primero en venir, de lo contrario el except URLError también capturará un HTTPError.

Número 2

from urllib.request import Request, urlopen
from urllib.error import URLError
req = Request(someurl)
try:
    response = urlopen(req)
except URLError as e:
    if hasattr(e, 'reason'):
        print('We failed to reach a server.')
        print('Reason: ', e.reason)
    elif hasattr(e, 'code'):
        print('The server couldn\'t fulfill the request.')
        print('Error code: ', e.code)
else:
    # everything is fine

info y geturl

La respuesta retornada por urlopen (o la instancia de HTTPError) tiene dos métodos útiles info() y geturl() y está definida en el módulo urllib.response..

geturl - devuelve la verdadera URL de la página obtenida. Esto es útil porque urlopen (o el objeto de apertura utilizado) puede haber seguido una redirección. El URL de la página obtenida puede no ser el mismo que el URL solicitado.

info - devuelve un objeto parecido a un diccionario que describe la página consultada, particularmente los encabezados enviados por el servidor. Actualmente es una instancia http.client.HTTPMessage.

Los encabezados típicos incluyen “Content-length”, “Content-type” y así sucesivamente. Mira la Quick Reference to HTTP Headers [http://jkorpela.fi/http.html] para un listado útil de encabezados de HTTP con breves explicaciones de su significado y uso.

Objetos de Apertura (Openers) y Gestores (Handlers)

Cuando buscas una URL usas un objeto de apertura (una instancia del quizás confusamente llamado urllib.request.OpenerDirector). Normalmente hemos estado usando el objeto de apertura por defecto - a través de urlopen - pero puedes crear objetos de apertura personalizados. Los objetos de apertura usan gestores. Todo el «trabajo pesado» es hecho por los gestores. Cada gestor sabe cómo abrir URLs para un esquema particular de URL (http, ftp, etc.), o cómo manejar un aspecto de la apertura de URLs, por ejemplo redirecciones HTTP o cookies HTTP.

Desearás crear objetos de apertura si deseas consultar URLs con gestores específicos instalados, por ejemplo para obtener un objeto de apertura que gestione cookies, o para obtener un objeto de apertura que no gestione redireccionamientos.

Para crear un objeto de apertura, debes instanciar un OpenerDirector, y luego llamar .add_handler(some_handler_instance) repetidamente.

Alternativamente, puedes usar build_opener, que es una función conveniente para crear objetos de apertura con una sola llamada a la función. build_opener añade varios gestores por defecto, pero proporciona una forma rápida de añadir más y/o sobrescribir los gestores por defecto.

Otros tipos de gestores que puedes querer permiten manejar proxies, autenticación, y otras situaciones comunes pero ligeramente especializadas.

install_opener puede ser usado para hacer que un objeto opener sea el objeto de apertura (global) por defecto. Esto significa que las llamadas a urlopen usarán el objeto de apertura que has instalado.

Los objetos de apertura tienen un método open, que puede ser llamado directamente para consultar urls de la misma manera que la función «urlopen»: no hay necesidad de llamar install_opener, excepto por conveniencia.

Autenticación Básica

Para ilustrar la creación e instalación de un gestor usaremos HTTPBasicAuthHandler`. Para una discusión más detallada de este tema – incluyendo una explicación de cómo funciona la Autenticación Básica - ver Basic Authentication Tutorial [http://www.voidspace.org.uk/python/articles/authentication.shtml].

Cuando se requiere la autenticación, el servidor envía un encabezado (así como el código de error 401) solicitando la autenticación. Esto especifica el esquema de autenticación y un “realm”. El encabezado tiene el siguiente aspecto: WWW-Authenticate: SCHEME realm="REALM".

por ejemplo.

WWW-Authenticate: Basic realm="cPanel Users"

El cliente debe entonces volver a intentar la solicitud con el nombre y la contraseña apropiados para el realm incluido como encabezamiento en la solicitud. Esto es “autenticación básica”. Para simplificar este proceso podemos crear una instancia de HTTPBasicAuthHandler y un objeto de apertura para usar este manejador.

El HTTPBasicAuthHandler utiliza un objeto llamado administrador de contraseñas para gestionar el mapeo de URLs y realms con contraseñas y nombres de usuario. Si sabes cuál es el realm (por el encabezado de autenticación enviado por el servidor), entonces puedes usar un HTTPPasswordMgr. Frecuentemente a uno no le importa cuál es el realm. En ese caso, es conveniente usar «HTTPPasswordMgrWithDefaultRealm». Esto te permite especificar un nombre de usuario y una contraseña por defecto para una URL. Esto será suministrado en caso de que no proporciones una combinación alternativa para un realm específico. Lo indicamos proporcionando None como el argumento del realm al método add_password.

La URL de primer nivel es la primera URL que requiere autenticación. Las URLs «más profundas» que la URL que pasas a .add_password() también coincidirán.

# create a password manager
password_mgr = urllib.request.HTTPPasswordMgrWithDefaultRealm()

# Add the username and password.
# If we knew the realm, we could use it instead of None.
top_level_url = "http://example.com/foo/"
password_mgr.add_password(None, top_level_url, username, password)

handler = urllib.request.HTTPBasicAuthHandler(password_mgr)

# create "opener" (OpenerDirector instance)
opener = urllib.request.build_opener(handler)

# use the opener to fetch a URL
opener.open(a_url)

# Install the opener.
# Now all calls to urllib.request.urlopen use our opener.
urllib.request.install_opener(opener)

Nota

En el ejemplo anterior sólo suministramos nuestro HTTPBasicAuthHandler a build_opener. Por defecto, los objetos de apertura tienen los gestores para situaciones normales – ProxyHandler (si un ajuste de proxy tal como una variable de entorno http_proxy está establecida), UnknownHandler, HTTPHandler, HTTPDefaultErrorHandler, HTTPRedirectHandler, FTPHandler, FileHandler, DataHandler, HTTPErrorProcessor.

top_level_url es de hecho o una URL completa (incluyendo el componente del esquema “http:” y el nombre del host y opcionalmente el número de puerto) p.ej. "http://example.com/" o una «autoridad» (esto es, el nombre del host, incluyendo opcionalmente el número de puerto) por ejemplo "example.com" o "example.com:8080" (este último ejemplo incluye un número de puerto). La autoridad, si está presente, NO debe contener el componente «userinfo» - por ejemplo "joe:password@example.com" no es correcto.

Proxies

urllib detectará automáticamente tu configuración de proxy y la utilizará. Esto es a través de ProxyHandler, que es parte de la cadena de gestores normales cuando se detecta un ajuste de proxy. Normalmente esto es algo bueno, pero hay ocasiones en las que puede no ser útil 5. Una forma de hacerlo es configurar nuestro propio ProxyHandler, sin proxies definidos. Esto se hace usando pasos similares a la configuración de un gestor Basic Authentication [http://www.voidspace.org.uk/python/articles/authentication.shtml]:

>>> proxy_support = urllib.request.ProxyHandler({})
>>> opener = urllib.request.build_opener(proxy_support)
>>> urllib.request.install_opener(opener)

Nota

Actualmente urllib.request no soporta la consulta de ubicaciones https a través de un proxy. Sin embargo, esto puede ser habilitado extendiendo urllib.request como se muestra en la receta 6.

Nota

HTTP_PROXY será ignorado si se establece una variable REQUEST_METHOD; ver la documentación en getproxies`().

Sockets y Capas

El soporte de Python para obtener recursos de la web funciona en capas. urllib utiliza la biblioteca http.client, que a su vez utiliza la biblioteca de sockets.

A partir de Python 2.3 se puede especificar cuánto tiempo debe esperar un socket para obtener una respuesta antes de que se agote el tiempo de espera. Esto puede ser útil en aplicaciones que tienen que consultar páginas web. Por defecto, el módulo socket no tiene tiempo de espera y puede colgarse. Actualmente, el tiempo de espera de la conexión no se expone en los niveles http.client o urllib.request. Sin embargo, puede establecerse el tiempo de espera por defecto de forma global para todas los sockets usando

import socket
import urllib.request

# timeout in seconds
timeout = 10
socket.setdefaulttimeout(timeout)

# this call to urllib.request.urlopen now uses the default timeout
# we have set in the socket module
req = urllib.request.Request('http://www.voidspace.org.uk')
response = urllib.request.urlopen(req)

Notas a pie de página

Este documento fue examinado y revisado por John Lee.

1

Google por ejemplo.

2

El rastreo de navegadores es una práctica muy mala para el diseño de sitios web - construir sitios usando estándares web es mucho más sensato. Desafortunadamente muchos sitios siguen enviando versiones diferentes a diferentes navegadores.

3

El agente de usuario para MSIE 6 es “Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; .NET CLR 1.1.4322)”

4

Para detalles de más encabezados de peticiones HTTP, ver Quick Reference to HTTP Headers [http://jkorpela.fi/http.html].

5

En mi caso tengo que usar un proxy para acceder a internet en el trabajo. Si intentas consultar URLs de localhost a través de este proxy, las bloquea. IE está configurado para usar el proxy, que urllib recoge. Para poder probar los scripts con un servidor localhost, tengo que evitar que urllib use el proxy.

6

objeto de apertura de urllib para proxy SSL (método CONNECT): ASPN Cookbook Recipe [https://code.activestate.com/recipes/456195/].

Tutorial de Argparse

autor

Tshepang Lekhonkhobe

Este tutorial pretende ser una leve introducción a argparse, el módulo de análisis (parsing) de línea de comandos recomendado en la biblioteca estándar de Python.

Nota

Hay otros dos módulos que cumplen la misma tarea, llamados getopt (un equivalente a getopt() del lenguaje C) y el deprecado optparse. Tenga en cuenta también que argparse está basado en optparse, y por lo tanto muy similar en el uso.

Conceptos

Vamos a mostrar el tipo de funcionalidad que vamos a explorar en este tutorial introductorio haciendo uso del comando ls:

$ ls
cpython  devguide  prog.py  pypy  rm-unused-function.patch
$ ls pypy
ctypes_configure  demo  dotviewer  include  lib_pypy  lib-python ...
$ ls -l
total 20
drwxr-xr-x 19 wena wena 4096 Feb 18 18:51 cpython
drwxr-xr-x  4 wena wena 4096 Feb  8 12:04 devguide
-rwxr-xr-x  1 wena wena  535 Feb 19 00:05 prog.py
drwxr-xr-x 14 wena wena 4096 Feb  7 00:59 pypy
-rw-r--r--  1 wena wena  741 Feb 18 01:01 rm-unused-function.patch
$ ls --help
Usage: ls [OPTION]... [FILE]...
List information about the FILEs (the current directory by default).
Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.
...

Algunos conceptos que podemos aprender de los cuatro comandos:

El comando ls es útil cuando se ejecuta sin ninguna opción en absoluto. Por defecto muestra el contenido del directorio actual.

Si queremos hacer algo, mas allá de lo que provee por defecto, le contamos un poco mas. En este caso, queremos mostrar un directorio diferente, pypy. Lo que hicimos fue especificar lo que se conoce como argumento posicional. Se llama así porque el programa debe saber que hacer con ese valor, basado únicamente en función de donde aparece en la línea de comandos. Este concepto es mas relevante para un comando como cp, cuyo uso mas básico es cp SRC DEST. La primer posición es lo que quieres copiar, y la segunda posición es a donde lo quieres copiar.

Ahora, digamos que queremos cambiar el comportamiento del programa. En nuestro ejemplo, mostramos mas información para cada archivo en lugar de solo mostrar los nombres de los archivos. El argumento -l en ese caso se conoce como argumento opcional.

Este es un fragmento del texto de ayuda. Es muy útil porque puedes encontrar un programa que nunca has usado antes, y puedes darte cuenta de como funciona simplemente leyendo el texto de ayuda.

Las bases

Comencemos con un simple ejemplo, el cual no hace (casi) nada:

import argparse
parser = argparse.ArgumentParser()
parser.parse_args()

Lo siguiente es el resultado de ejecutar el código:

$ python3 prog.py
$ python3 prog.py --help
usage: prog.py [-h]

optional arguments:
  -h, --help  show this help message and exit
$ python3 prog.py --verbose
usage: prog.py [-h]
prog.py: error: unrecognized arguments: --verbose
$ python3 prog.py foo
usage: prog.py [-h]
prog.py: error: unrecognized arguments: foo

Esto es lo que está pasando:

Ejecutar el script sin ninguna opción da como resultado que no se muestra nada en stdout. No es tan útil.

El segundo comienza a mostrar la utilidad del módulo argparse. No hemos hecho casi nada, pero ya recibimos un buen mensaje de ayuda.

La opción --help, que también puede ser abreviada como -h, es la única opción que tenemos gratis (es decir, no necesitamos especificarla). Especificar cualquier otra cosa da como resultado un error. Pero aún así, recibimos un mensaje útil, también gratis.

Introducción a los argumentos posicionales

Un ejemplo:

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("echo")
args = parser.parse_args()
print(args.echo)

Y ejecutando el código:

$ python3 prog.py
usage: prog.py [-h] echo
prog.py: error: the following arguments are required: echo
$ python3 prog.py --help
usage: prog.py [-h] echo

positional arguments:
  echo

optional arguments:
  -h, --help  show this help message and exit
$ python3 prog.py foo
foo

Aquí está lo que está sucediendo:

Hemos agregado el método add_argument(), el cual es el que usamos para especificar cuales opciones de la línea de comandos el programa está dispuesto a aceptar. En este caso, lo he llamado echo para que esté línea con su función.

Llamar nuestro programa ahora requiere que especifiquemos una opción.

El método parse_args() realmente retorna algunos datos de las opciones especificadas, en este caso, echo.

La variable es una forma de “magia” que argparse se realiza de forma gratuita (es decir, no es necesario especificar en qué variable se almacena ese valor). También notará que su nombre coincide con el argumento de cadena dado al método, echo.

Sin embargo, tenga en cuenta que, aunque la pantalla de ayuda luce bien y todo, en realidad no es tan útil como podría ser. Por ejemplo, vemos que tenemos echo como un argumento posicional, pero no sabemos lo que hace, de otra manera que no sea adivinar o leer el código fuente. Entonces, vamos a hacerlo un poco mas útil:

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("echo", help="echo the string you use here")
args = parser.parse_args()
print(args.echo)

Y la salida:

$ python3 prog.py -h
usage: prog.py [-h] echo

positional arguments:
  echo        echo the string you use here

optional arguments:
  -h, --help  show this help message and exit

Ahora, que tal si hacemos algo más útil:

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", help="display a square of a given number")
args = parser.parse_args()
print(args.square**2)

Lo siguiente es el resultado de ejecutar el código:

$ python3 prog.py 4
Traceback (most recent call last):
  File "prog.py", line 5, in <module>
    print(args.square**2)
TypeError: unsupported operand type(s) for ** or pow(): 'str' and 'int'

Eso no fue tan bien. Esto es porque argparse trata las opciones que le damos como cadenas, a menos que le digamos otra cosa. Entonces, vamos a llamar a argparse para tratar esa entrada como un entero:

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", help="display a square of a given number",
                    type=int)
args = parser.parse_args()
print(args.square**2)

Lo siguiente es el resultado de ejecutar el código:

$ python3 prog.py 4
16
$ python3 prog.py four
usage: prog.py [-h] square
prog.py: error: argument square: invalid int value: 'four'

Eso fue bien. El programa ahora aún se cierra útilmente en caso de una entrada ilegal incorrecta antes de proceder.

Introducción a los argumentos opcionales

Hasta ahora hemos estado jugando con argumentos posicionales. Vamos a darle una mirada a como agregar los opcionales:

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("--verbosity", help="increase output verbosity")
args = parser.parse_args()
if args.verbosity:
    print("verbosity turned on")

Y la salida:

$ python3 prog.py --verbosity 1
verbosity turned on
$ python3 prog.py
$ python3 prog.py --help
usage: prog.py [-h] [--verbosity VERBOSITY]

optional arguments:
  -h, --help            show this help message and exit
  --verbosity VERBOSITY
                        increase output verbosity
$ python3 prog.py --verbosity
usage: prog.py [-h] [--verbosity VERBOSITY]
prog.py: error: argument --verbosity: expected one argument

Esto es lo que está pasando:

El programa está escrito para mostrar algo cuando --verbosity sea especificado y no mostrar nada cuando no.

Para mostrar que la opción es realmente opcional, no hay ningún error al ejecutar el programa sin ella. Tenga en cuenta que por defecto, si un argumento opcional no es usado, la variable relevante, en este caso args.verbosity, se le da None como valor, razón por la cual falla la prueba de verdad de la declaración if.

El mensaje de ayuda es un poco diferente.

Cuando usamos la opción --verbosity, también se debe especificar un valor, cualquier valor.

El ejemplo anterior acepta arbitrariamente valores enteros para --verbosity, pero para nuestro simple programa, solo dos valores son realmente útiles, True o False. Modifiquemos el código de acuerdo a esto:

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("--verbose", help="increase output verbosity",
                    action="store_true")
args = parser.parse_args()
if args.verbose:
    print("verbosity turned on")

Y la salida:

$ python3 prog.py --verbose
verbosity turned on
$ python3 prog.py --verbose 1
usage: prog.py [-h] [--verbose]
prog.py: error: unrecognized arguments: 1
$ python3 prog.py --help
usage: prog.py [-h] [--verbose]

optional arguments:
  -h, --help  show this help message and exit
  --verbose   increase output verbosity

Esto es lo que está pasando:

La opción ahora es más una bandera que algo que requiere un valor. Incluso cambiamos el nombre de la opción para que coincida con esa idea. Tenga en cuenta que ahora especificamos una nueva palabra clave, action, y le dimos el valor "store_true". Esto significa que, si la opción es especificada, se asigna el valor True a args.verbose. No especificarlo implica False.

Se queja cuando se especifica un valor, en verdadero espíritu de lo que realmente son los flags.

Observe los diferentes textos de ayuda.

Opciones cortas

Si estas familiarizado con el uso de la línea de comandos, podrás observar que aún no he tocado el tema de las versiones cortas de las opciones. Es bastante simple:

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("-v", "--verbose", help="increase output verbosity",
                    action="store_true")
args = parser.parse_args()
if args.verbose:
    print("verbosity turned on")

Y aquí va:

$ python3 prog.py -v
verbosity turned on
$ python3 prog.py --help
usage: prog.py [-h] [-v]

optional arguments:
  -h, --help     show this help message and exit
  -v, --verbose  increase output verbosity

Tenga en cuenta que la nueva habilidad es también reflejada en el texto de ayuda.

Combinar argumentos opcionales y posicionales

Nuestro programa sigue creciendo en complejidad:

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int,
                    help="display a square of a given number")
parser.add_argument("-v", "--verbose", action="store_true",
                    help="increase output verbosity")
args = parser.parse_args()
answer = args.square**2
if args.verbose:
    print("the square of {} equals {}".format(args.square, answer))
else:
    print(answer)

Y ahora la salida:

$ python3 prog.py
usage: prog.py [-h] [-v] square
prog.py: error: the following arguments are required: square
$ python3 prog.py 4
16
$ python3 prog.py 4 --verbose
the square of 4 equals 16
$ python3 prog.py --verbose 4
the square of 4 equals 16

Hemos traído de vuelta un argumento posicional, de ahí la queja.

Tenga en cuenta que el orden no importa.

Que tal si le retornamos a nuestro programa la capacidad de tener múltiples valores de verbosidad, y realmente usarlos:

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int,
                    help="display a square of a given number")
parser.add_argument("-v", "--verbosity", type=int,
                    help="increase output verbosity")
args = parser.parse_args()
answer = args.square**2
if args.verbosity == 2:
    print("the square of {} equals {}".format(args.square, answer))
elif args.verbosity == 1:
    print("{}^2 == {}".format(args.square, answer))
else:
    print(answer)

Y la salida:

$ python3 prog.py 4
16
$ python3 prog.py 4 -v
usage: prog.py [-h] [-v VERBOSITY] square
prog.py: error: argument -v/--verbosity: expected one argument
$ python3 prog.py 4 -v 1
4^2 == 16
$ python3 prog.py 4 -v 2
the square of 4 equals 16
$ python3 prog.py 4 -v 3
16

Todos estos se ven bien, excepto el último, que expone un error en nuestro programa. Corrijamos esto restringiendo los valores que la opción --verbosity puede aceptar:

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int,
                    help="display a square of a given number")
parser.add_argument("-v", "--verbosity", type=int, choices=[0, 1, 2],
                    help="increase output verbosity")
args = parser.parse_args()
answer = args.square**2
if args.verbosity == 2:
    print("the square of {} equals {}".format(args.square, answer))
elif args.verbosity == 1:
    print("{}^2 == {}".format(args.square, answer))
else:
    print(answer)

Y la salida:

$ python3 prog.py 4 -v 3
usage: prog.py [-h] [-v {0,1,2}] square
prog.py: error: argument -v/--verbosity: invalid choice: 3 (choose from 0, 1, 2)
$ python3 prog.py 4 -h
usage: prog.py [-h] [-v {0,1,2}] square

positional arguments:
  square                display a square of a given number

optional arguments:
  -h, --help            show this help message and exit
  -v {0,1,2}, --verbosity {0,1,2}
                        increase output verbosity

Tenga en cuenta que el cambio se refleja tanto en el mensaje de error como en la cadena de ayuda.

Ahora, usemos un enfoque diferente para jugar con la verbosidad, lo cual es bastante común. También coincide con la forma en que el ejecutable de CPython maneja su propio argumento de verbosidad (verifique el resultado de python --help):

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int,
                    help="display the square of a given number")
parser.add_argument("-v", "--verbosity", action="count",
                    help="increase output verbosity")
args = parser.parse_args()
answer = args.square**2
if args.verbosity == 2:
    print("the square of {} equals {}".format(args.square, answer))
elif args.verbosity == 1:
    print("{}^2 == {}".format(args.square, answer))
else:
    print(answer)

Hemos introducido otra acción, "count", para contar el numero de ocurrencias de un argumento opcional específico:

$ python3 prog.py 4
16
$ python3 prog.py 4 -v
4^2 == 16
$ python3 prog.py 4 -vv
the square of 4 equals 16
$ python3 prog.py 4 --verbosity --verbosity
the square of 4 equals 16
$ python3 prog.py 4 -v 1
usage: prog.py [-h] [-v] square
prog.py: error: unrecognized arguments: 1
$ python3 prog.py 4 -h
usage: prog.py [-h] [-v] square

positional arguments:
  square           display a square of a given number

optional arguments:
  -h, --help       show this help message and exit
  -v, --verbosity  increase output verbosity
$ python3 prog.py 4 -vvv
16

Si, ahora es mas una bandera (similar a action="store_true") en la versión anterior de nuestro script. Esto debería explicar la queja.

También se comporta de manera similar a la acción "store_true".

Ahora aquí una demostración de lo que la acción "count" da. Probablemente haya visto esta clase de uso antes.

Y si no especificas la bandera -v, se considera que esa bandera tiene el valor None.

Como debería esperarse, especificando la forma larga de la bandera, obtendríamos el mismo resultado.

Lamentablemente, nuestra salida de ayuda no es muy informativa sobre la nueva capacidad que ha adquirido nuestro script, pero eso siempre se puede solucionar mejorando la documentación de nuestro script (por ejemplo, a través del argumento de la palabra clave help).

La última salida expone un error en nuestro programa.

Vamos a arreglarlo:

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int,
                    help="display a square of a given number")
parser.add_argument("-v", "--verbosity", action="count",
                    help="increase output verbosity")
args = parser.parse_args()
answer = args.square**2

# bugfix: replace == with >=
if args.verbosity >= 2:
    print("the square of {} equals {}".format(args.square, answer))
elif args.verbosity >= 1:
    print("{}^2 == {}".format(args.square, answer))
else:
    print(answer)

Y esto es lo que da:

$ python3 prog.py 4 -vvv
the square of 4 equals 16
$ python3 prog.py 4 -vvvv
the square of 4 equals 16
$ python3 prog.py 4
Traceback (most recent call last):
  File "prog.py", line 11, in <module>
    if args.verbosity >= 2:
TypeError: '>=' not supported between instances of 'NoneType' and 'int'

La primer salida fue correcta, y corrigió el error que teníamos antes. Es decir, queremos que cualquier valor >= 2 sea lo más detallado posible.

Tercer salida no tan buena.

Vamos a arreglar ese error:

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int,
                    help="display a square of a given number")
parser.add_argument("-v", "--verbosity", action="count", default=0,
                    help="increase output verbosity")
args = parser.parse_args()
answer = args.square**2
if args.verbosity >= 2:
    print("the square of {} equals {}".format(args.square, answer))
elif args.verbosity >= 1:
    print("{}^2 == {}".format(args.square, answer))
else:
    print(answer)

Acabamos de introducir otra palabra clave, default. Lo hemos configurado en 0 para que sea comparable con otros valores int. Recuerde que por defecto, si un argumento opcional no es especificado, obtiene el valor None, y eso no puede ser comparado con un valor int (de ahí la excepción TypeError).

Y:

$ python3 prog.py 4
16

Tu puedes llegar bastante lejos con lo que hemos aprendido hasta ahora, y solo arañado la superficie. El módulo argparse es muy poderoso, y exploraremos un poco mas antes de finalizar este tutorial.

Un poco mas avanzado

Qué pasaría si quisiéramos expandir nuestro pequeño programa para que tenga otros poderes, no solo cuadrados:

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("x", type=int, help="the base")
parser.add_argument("y", type=int, help="the exponent")
parser.add_argument("-v", "--verbosity", action="count", default=0)
args = parser.parse_args()
answer = args.x**args.y
if args.verbosity >= 2:
    print("{} to the power {} equals {}".format(args.x, args.y, answer))
elif args.verbosity >= 1:
    print("{}^{} == {}".format(args.x, args.y, answer))
else:
    print(answer)

Salida:

$ python3 prog.py
usage: prog.py [-h] [-v] x y
prog.py: error: the following arguments are required: x, y
$ python3 prog.py -h
usage: prog.py [-h] [-v] x y

positional arguments:
  x                the base
  y                the exponent

optional arguments:
  -h, --help       show this help message and exit
  -v, --verbosity
$ python3 prog.py 4 2 -v
4^2 == 16

Tenga en cuenta que hasta ahora hemos estado usando el nivel de verbosidad para cambiar el texto que se muestra. El siguiente ejemplo en lugar de usar nivel de verbosidad para mostrar mas texto en su lugar:

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("x", type=int, help="the base")
parser.add_argument("y", type=int, help="the exponent")
parser.add_argument("-v", "--verbosity", action="count", default=0)
args = parser.parse_args()
answer = args.x**args.y
if args.verbosity >= 2:
    print("Running '{}'".format(__file__))
if args.verbosity >= 1:
    print("{}^{} == ".format(args.x, args.y), end="")
print(answer)

Salida:

$ python3 prog.py 4 2
16
$ python3 prog.py 4 2 -v
4^2 == 16
$ python3 prog.py 4 2 -vv
Running 'prog.py'
4^2 == 16

Opciones conflictivas

Hasta ahora, hemos estado trabajando con dos métodos de una instancia de argparse.ArgumentParser. Vamos a introducir un tercer método, add_mutually_exclusive_group(). Nos permite especificar opciones que entran en conflicto entre sí. Cambiemos también el resto del programa para que la nueva funcionalidad tenga mas sentido: presentaremos la opción --quiet, la cual es lo opuesto a la opción --verbose:

import argparse

parser = argparse.ArgumentParser()
group = parser.add_mutually_exclusive_group()
group.add_argument("-v", "--verbose", action="store_true")
group.add_argument("-q", "--quiet", action="store_true")
parser.add_argument("x", type=int, help="the base")
parser.add_argument("y", type=int, help="the exponent")
args = parser.parse_args()
answer = args.x**args.y

if args.quiet:
    print(answer)
elif args.verbose:
    print("{} to the power {} equals {}".format(args.x, args.y, answer))
else:
    print("{}^{} == {}".format(args.x, args.y, answer))

Nuestro programa ahora es mas simple, y perdimos algunas funcionalidades en aras de la demostración. De todos modos, aquí esta el resultado:

$ python3 prog.py 4 2
4^2 == 16
$ python3 prog.py 4 2 -q
16
$ python3 prog.py 4 2 -v
4 to the power 2 equals 16
$ python3 prog.py 4 2 -vq
usage: prog.py [-h] [-v | -q] x y
prog.py: error: argument -q/--quiet: not allowed with argument -v/--verbose
$ python3 prog.py 4 2 -v --quiet
usage: prog.py [-h] [-v | -q] x y
prog.py: error: argument -q/--quiet: not allowed with argument -v/--verbose

Esto debería ser sencillo de seguir. He agregado esa última salida para que se pueda ver el tipo de flexibilidad que obtiene, es decir, mezclar opciones de forma larga con opciones de forma corta.

Antes de concluir, probablemente quiera contarle a sus usuarios el propósito principal de su programa, solo en caso de que no lo supieran:

import argparse

parser = argparse.ArgumentParser(description="calculate X to the power of Y")
group = parser.add_mutually_exclusive_group()
group.add_argument("-v", "--verbose", action="store_true")
group.add_argument("-q", "--quiet", action="store_true")
parser.add_argument("x", type=int, help="the base")
parser.add_argument("y", type=int, help="the exponent")
args = parser.parse_args()
answer = args.x**args.y

if args.quiet:
    print(answer)
elif args.verbose:
    print("{} to the power {} equals {}".format(args.x, args.y, answer))
else:
    print("{}^{} == {}".format(args.x, args.y, answer))

Tenga en cuenta la ligera diferencia en el uso del texto. Tenga en cuenta [-v | -q], lo cual nos indica que podemos usar -v o -q, pero no ambos al mismo tiempo:

$ python3 prog.py --help
usage: prog.py [-h] [-v | -q] x y

calculate X to the power of Y

positional arguments:
  x              the base
  y              the exponent

optional arguments:
  -h, --help     show this help message and exit
  -v, --verbose
  -q, --quiet

Conclusión

El módulo argparse ofrece mucho más que solo lo mostrado aquí. Su documentación es bastante detallada y completa, y está llena de ejemplos. Habiendo seguido este tutorial, debe digerirlos fácilmente sin sentirse abrumado.

Introducción al modulo ipaddress

autor

Peter Moody

autor

Nick Coghlan

Descripción

Este documento tiene como objetivo proporcionar una introducción apacible al módulo ipaddress. Está dirigido principalmente a los usuarios que no están familiarizados con la terminología IP de redes, pero también puede ser útil para los ingenieros de red que quieren una visión general de cómo ipaddress representa los conceptos de direccionamiento IP de red.

Creando objetos Dirección/Red/Interfaz (Address/Network/Interface)

Siendo ipaddress un módulo para inspeccionar y manipular direcciones IP, la primer cosa que usted querrá hacer es crear algunos objetos. Puede utilizar ipaddress para crear objetos a partir de cadenas de caracteres y enteros.

Nota sobre versiones IP

Para los lectores que no están particularmente familiarizados con el direccionamiento IP, es importante saber que el Protocolo de Internet está actualmente en el proceso de pasar de la versión 4 del protocolo a la versión 6. Esta transición se está produciendo en gran parte porque la versión 4 del protocolo no proporciona suficientes direcciones para manejar las necesidades de todo el mundo, especialmente dado el creciente número de dispositivos con conexiones directas a Internet.

Explicando los detalles de las diferencias entre las dos versiones del protocolo está más allá del alcance de esta introducción, pero los lectores deben al menos ser conscientes de que estas dos versiones existen, y a veces será necesario forzar el uso de una versión u otra.

Direcciones IP del Host

Las direcciones, a menudo denominadas «direcciones de host» son la unidad más básica cuando se trabaja con direccionamiento IP. La forma más sencilla de crear direcciones es usar la función de fabrica ipaddress.ip_address(), que determina automáticamente si se crea una dirección IPv4 o IPv6 en función del valor pasado:

>>> ipaddress.ip_address('192.0.2.1')
IPv4Address('192.0.2.1')
>>> ipaddress.ip_address('2001:DB8::1')
IPv6Address('2001:db8::1')

Las direcciones también se pueden crear directamente a partir de enteros. Los valores que caben dentro de 32 bits se asume que son direcciones IPv4:

>>> ipaddress.ip_address(3221225985)
IPv4Address('192.0.2.1')
>>> ipaddress.ip_address(42540766411282592856903984951653826561)
IPv6Address('2001:db8::1')

Para forzar el uso de direcciones IPv4 o IPv6, las clases relevantes se pueden invocar directamente. Esto es particularmente útil para forzar la creación de direcciones IPv6 para enteros pequeños:

>>> ipaddress.ip_address(1)
IPv4Address('0.0.0.1')
>>> ipaddress.IPv4Address(1)
IPv4Address('0.0.0.1')
>>> ipaddress.IPv6Address(1)
IPv6Address('::1')

Definiendo Redes

Las direcciones de host generalmente se agrupan en redes IP, por lo que ipaddress proporciona una forma de crear, inspeccionar y manipular definiciones de red. Los objetos de red IP se construyen a partir de cadenas que definen el rango de direcciones de host que forman parte de esa red. La forma más simple para esa información es un par de «dirección de red/prefijo de red», donde el prefijo define el número de bits iniciales que se comparan para determinar si una dirección es parte de la red y la dirección de red define el valor esperado de esos bits.

En cuanto a las direcciones, se proporciona una función de fábrica que determina automáticamente la versión IP correcta:

>>> ipaddress.ip_network('192.0.2.0/24')
IPv4Network('192.0.2.0/24')
>>> ipaddress.ip_network('2001:db8::0/96')
IPv6Network('2001:db8::/96')

Los objetos de red no pueden tener ningún bit de host establecido. El efecto práctico de esto es que 192.0.2.1/24 no describe una red. Tales definiciones se conocen como objetos de interfaz ya que la notación ip-on-a-network se usa comúnmente para describir interfaces de red de un ordenador en una red determinada y se describen más adelante en la siguiente sección.

De forma predeterminada, al intentar crear un objeto de red con los bits de host establecidos, se lanzará un ValueError. Para solicitar que los bits adicionales se coaccionen a cero, el flag strict=False se puede pasar al constructor:

>>> ipaddress.ip_network('192.0.2.1/24')
Traceback (most recent call last):
   ...
ValueError: 192.0.2.1/24 has host bits set
>>> ipaddress.ip_network('192.0.2.1/24', strict=False)
IPv4Network('192.0.2.0/24')

Si bien la forma de cadena de caracteres ofrece mucha más flexibilidad, las redes también se pueden definir con enteros, al igual que las direcciones de host. En este caso, se considera que la red contiene solo la dirección única identificada por el entero, por lo que el prefijo de red incluye toda la dirección de red:

>>> ipaddress.ip_network(3221225984)
IPv4Network('192.0.2.0/32')
>>> ipaddress.ip_network(42540766411282592856903984951653826560)
IPv6Network('2001:db8::/128')

Al igual que con las direcciones, la creación de un tipo particular de red se puede forzar llamando directamente al constructor de clase en lugar de usar la función de fábrica.

Interfaces de Host

Como se mencionó anteriormente, si necesita describir una dirección en una red en particular, ni la dirección ni las clases de red son suficientes. La notación como 192.0.2.1/24 es comúnmente utilizada por los ingenieros de red y las personas que escriben herramientas para cortafuegos y enrutadores como abreviatura de «el host 192.0.2.1 en la red 192.0.2.0/24», En consecuencia, ipaddress proporciona un conjunto de clases híbridas que asocian una dirección con una red en particular. La interfaz para la creación es idéntica a la de definir objetos de red, excepto que la parte de dirección no está restringida a ser una dirección de red.

>>> ipaddress.ip_interface('192.0.2.1/24')
IPv4Interface('192.0.2.1/24')
>>> ipaddress.ip_interface('2001:db8::1/96')
IPv6Interface('2001:db8::1/96')

Se aceptan entradas enteras (como con las redes), y el uso de una versión IP particular se puede forzar llamando directamente al constructor relevante.

Inspeccionando objetos Dirección/Red/Interfaz (Address/Network/Interface)

Se ha tomado la molestia de crear un objeto IPv(4|6)(Address|Network|Interface), por lo que probablemente desee obtener información al respecto. ipaddress intenta hacer esto fácil e intuitivo.

Extrayendo la versión IP:

>>> addr4 = ipaddress.ip_address('192.0.2.1')
>>> addr6 = ipaddress.ip_address('2001:db8::1')
>>> addr6.version
6
>>> addr4.version
4

Obteniendo la red desde una interfaz:

>>> host4 = ipaddress.ip_interface('192.0.2.1/24')
>>> host4.network
IPv4Network('192.0.2.0/24')
>>> host6 = ipaddress.ip_interface('2001:db8::1/96')
>>> host6.network
IPv6Network('2001:db8::/96')

Averiguando cuántas direcciones individuales hay en una red:

>>> net4 = ipaddress.ip_network('192.0.2.0/24')
>>> net4.num_addresses
256
>>> net6 = ipaddress.ip_network('2001:db8::0/96')
>>> net6.num_addresses
4294967296

Iterando a través de las direcciones «utilizables» en una red:

>>> net4 = ipaddress.ip_network('192.0.2.0/24')
>>> for x in net4.hosts():
...     print(x)
192.0.2.1
192.0.2.2
192.0.2.3
192.0.2.4
...
192.0.2.252
192.0.2.253
192.0.2.254

Obteniendo la máscara de red (es decir, establecer bits correspondientes al prefijo de red) o la máscara de host (cualquier bits que no forme parte de la máscara de red):

>>> net4 = ipaddress.ip_network('192.0.2.0/24')
>>> net4.netmask
IPv4Address('255.255.255.0')
>>> net4.hostmask
IPv4Address('0.0.0.255')
>>> net6 = ipaddress.ip_network('2001:db8::0/96')
>>> net6.netmask
IPv6Address('ffff:ffff:ffff:ffff:ffff:ffff::')
>>> net6.hostmask
IPv6Address('::ffff:ffff')

Expandiendo o comprimiendo la dirección:

>>> addr6.exploded
'2001:0db8:0000:0000:0000:0000:0000:0001'
>>> addr6.compressed
'2001:db8::1'
>>> net6.exploded
'2001:0db8:0000:0000:0000:0000:0000:0000/96'
>>> net6.compressed
'2001:db8::/96'

Si bien IPv4 no admite expansión o compresión, los objetos asociados aún proporcionan las propiedades relevantes para que el código neutral de la versión pueda garantizar fácilmente que se use la forma más concisa o detallada para las direcciones IPv6 mientras se maneja correctamente las direcciones IPv4.

Redes como listas de direcciones

A veces es útil tratar las redes como listas. Esto significa que es posible indexarlas de esta manera:

>>> net4[1]
IPv4Address('192.0.2.1')
>>> net4[-1]
IPv4Address('192.0.2.255')
>>> net6[1]
IPv6Address('2001:db8::1')
>>> net6[-1]
IPv6Address('2001:db8::ffff:ffff')

También significa que los objetos de red se prestan a usar la sintaxis del test de lista de membresía como esta:

if address in network:
    # do something

Las pruebas de contención se realizan de manera eficiente según el prefijo de red:

>>> addr4 = ipaddress.ip_address('192.0.2.1')
>>> addr4 in ipaddress.ip_network('192.0.2.0/24')
True
>>> addr4 in ipaddress.ip_network('192.0.3.0/24')
False

Comparaciones

ipaddress proporciona algunas formas simples e intuitivas de comparar objetos, donde esto tiene sentido:

>>> ipaddress.ip_address('192.0.2.1') < ipaddress.ip_address('192.0.2.2')
True

Se genera una excepción TypeError si intenta comparar objetos de diferentes versiones o tipos diferentes.

Uso de direcciones IP con otros módulos

Otros módulos que usan direcciones IP (como socket ) generalmente no aceptarán directamente objetos de este módulo. En su lugar, deben ser forzados a un entero o una cadena que el otro módulo deberá aceptar:

>>> addr4 = ipaddress.ip_address('192.0.2.1')
>>> str(addr4)
'192.0.2.1'
>>> int(addr4)
3221225985

Obtener más detalles cuando se produce un error en la creación de instancias

Al crear objetos de dirección/red/interfaz utilizando las funciones de fábrica independientes de la versión, cualquier error se informará como ValueError con un mensaje de error genérico que simplemente dice que el valor pasado no se reconoció como un objeto de ese tipo. La falta de un error específico se debe a que es necesario saber si se supone que el valor es IPv4 o IPv6 para poder proporcionar más detalles sobre por qué se ha rechazado.

Para admitir casos de uso en los que es útil tener acceso a este detalle adicional, los constructores de clase individuales en realidad lanza las subclases ValueError ipaddress.AddressValueError y ipaddress.NetmaskValueError para indicar exactamente qué parte de la definición no se pudo analizar correctamente.

Los mensajes de error son significativamente más detallados cuando se usan los constructores de clase directamente. Por ejemplo:

>>> ipaddress.ip_address("192.168.0.256")
Traceback (most recent call last):
  ...
ValueError: '192.168.0.256' does not appear to be an IPv4 or IPv6 address
>>> ipaddress.IPv4Address("192.168.0.256")
Traceback (most recent call last):
  ...
ipaddress.AddressValueError: Octet 256 (> 255) not permitted in '192.168.0.256'

>>> ipaddress.ip_network("192.168.0.1/64")
Traceback (most recent call last):
  ...
ValueError: '192.168.0.1/64' does not appear to be an IPv4 or IPv6 network
>>> ipaddress.IPv4Network("192.168.0.1/64")
Traceback (most recent call last):
  ...
ipaddress.NetmaskValueError: '64' is not a valid netmask

Sin embargo, ambas excepciones específicas del módulo tienen ValueError como su clase principal, por lo que si no le preocupa el tipo particular de error, aún puede escribir código como el siguiente:

try:
    network = ipaddress.IPv4Network(address)
except ValueError:
    print('address/netmask is invalid for IPv4:', address)

How-To Argument Clinic

autor

Larry Hastings

Resumen

Argument Clinic es un preprocesador para archivos CPython C. Su propósito es automatizar todo el texto estándar involucrado con la escritura de código de análisis de argumentos para «incorporados». Este documento le muestra cómo convertir su primera función C para que funcione con Argument Clinic y luego presenta algunos temas avanzados sobre el uso de Argument Clinic.

Actualmente, Argument Clinic se considera solo interno para CPython. Su uso no es compatible con archivos fuera de CPython y no se ofrecen garantías con respecto a la compatibilidad con versiones anteriores. En otras palabras: si mantiene una extensión C externa para CPython, puede experimentar con Argument Clinic en su propio código. Pero la versión de Argument Clinic que se envía con la próxima versión de CPython podría ser totalmente incompatible y romper todo su código.

Los objetivos del Argument Clinic

El objetivo principal de Argument Clinic es asumir la responsabilidad de todo el código de análisis de argumentos dentro de CPython. Esto significa que, cuando convierte una función para que funcione con Argument Clinic, esa función ya no debería realizar ninguno de sus propios análisis de argumentos; el código generado por Argument Clinic debería ser una «caja negra» para usted, donde CPython llama al top, y su código se llama en la parte inferior, con PyObject *args (y tal vez PyObject *kwargs) convertido mágicamente en las variables y tipos C que necesita.

Para que Argument Clinic logre su objetivo principal, debe ser fácil de usar. Actualmente, trabajar con la biblioteca de análisis de argumentos de CPython es una tarea ardua que requiere mantener información redundante en un número sorprendente de lugares. Cuando usa Argument Clinic, no tiene que repetirse.

Obviamente, si Argument Clinic no produjo ningún resultado, es porque encontró un error en su entrada. Siga corrigiendo sus errores y vuelva a intentarlo hasta que Argument Clinic procese su archivo sin quejas.

Además, Argument Clinic debe ser lo suficientemente flexible como para trabajar con cualquier enfoque de análisis de argumentos. Python tiene algunas funciones con algunos comportamientos de análisis muy extraños; el objetivo de Argument Clinic es apoyarlos a todos.

Finalmente, la motivación original de Argument Clinic era proporcionar «signaturas» de introspección para las incorporaciones de CPython. Solía ser, las funciones de consulta de introspección lanzarían una excepción si pasaba un archivo incorporado. ¡Con Argument Clinic, eso es cosa del pasado!

Una idea que debe tener en cuenta al trabajar con Argument Clinic: cuanta más información le dé, mejor será su trabajo. Argument Clinic es ciertamente relativamente simple en este momento. Pero a medida que evolucione, se volverá más sofisticado y debería poder hacer muchas cosas interesantes e inteligentes con toda la información que le proporcione.

Conceptos básicos y uso

Argument Clinic se envía con CPython; lo encontrará en Tools/clinic/clinic.py. Si ejecuta ese script, especificando un archivo C como argumento:

$ python3 Tools/clinic/clinic.py foo.c

Argument Clinic escaneará el archivo buscando líneas que se vean exactamente así:

/*[clinic input]

Cuando encuentra uno, lee todo hasta una línea que se ve exactamente así:

[clinic start generated code]*/

Todo lo que se encuentra entre estas dos líneas es entrada para Argument Clinic. Todas estas líneas, incluidas las líneas de comentarios iniciales y finales, se denominan colectivamente un «bloque» de Argument Clinic.

Cuando Argument Clinic analiza uno de estos bloques, genera una salida. Esta salida se reescribe en el archivo C inmediatamente después del bloque, seguida de un comentario que contiene una suma de comprobación. El bloque Argument Clinic ahora tiene este aspecto:

/*[clinic input]
... clinic input goes here ...
[clinic start generated code]*/
... clinic output goes here ...
/*[clinic end generated code: checksum=...]*/

Si ejecuta Argument Clinic en el mismo archivo por segunda vez, Argument Clinic descartará la salida anterior y escribirá la nueva salida con una nueva línea de suma de comprobación. Sin embargo, si la entrada no ha cambiado, la salida tampoco cambiará.

Nunca debe modificar la parte de salida de un bloque de Argument Clinic. En su lugar, cambie la entrada hasta que produzca la salida que desea. (Ese es el propósito de la suma de comprobación: detectar si alguien cambió la salida, ya que estas ediciones se perderían la próxima vez que Argument Clinic escriba una salida nueva).

En aras de la claridad, esta es la terminología que usaremos con Argument Clinic:

La primera línea del comentario (/*[clinic input]) es la línea de inicio.

La última línea del comentario inicial ([clinic start generated code]*/) es la línea final.

La última línea (/*[clinic end generated code: checksum=...]*/) es la línea de suma de comprobación (chemsum line).

Entre la línea de inicio y la línea final está el input.

Entre la línea final y la línea de suma de comprobación se encuentra la output.

Todo el texto colectivamente, desde la línea de inicio hasta la línea de suma de verificación inclusive, es el bloque. (Un bloque que no ha sido procesado con éxito por Argument Clinic todavía no tiene salida o una línea de suma de verificación, pero aún se considera un bloque).

Convirtiendo su primera función

La mejor manera de tener una idea de cómo funciona Argument Clinic es convertir una función para que funcione con ella. Aquí, entonces, están los pasos mínimos que debe seguir para convertir una función para que funcione con Argument Clinic. Tenga en cuenta que para el código que planea registrar en CPython, realmente debería llevar la conversión más lejos, utilizando algunos de los conceptos avanzados que verá más adelante en el documento (como «convertidores de retorno» y «convertidores automáticos»). Pero lo haremos simple para este tutorial para que pueda aprender.

¡Vamos a sumergirnos!

Asegúrese de estar trabajando con una versión recién actualizada de CPython.

Busca un incorporado de Python que llame a PyArg_ParseTuple() o PyArg_ParseTupleAndKeywords(), y que aún no se haya convertido para funcionar con Argument Clinic. Para mi ejemplo, estoy usando _pickle.Pickler.dump().

Si la llamada a la función PyArg_Parse usa cualquiera de las siguientes unidades de formato:

O&
O!
es
es#
et
et#

o si tiene múltiples llamadas a PyArg_ParseTuple(), debes elegir una función diferente. Argument Clinic sí admite todos estos escenarios. Pero estos son temas avanzados; hagamos algo más simple para su primera función.

Además, si la función tiene múltiples llamadas a PyArg_ParseTuple() o PyArg_ParseTupleAndKeywords() donde admite diferentes tipos para el mismo argumento, o si la función usa algo además de las funciones PyArg_Parse para analizar sus argumentos, probablemente no sea adecuado para la conversión a Argument Clinic. Argument Clinic no admite funciones genéricas ni parámetros polimórficos.

Agrega la siguiente plantilla sobre la función, creando nuestro bloque

/*[clinic input]
[clinic start generated code]*/

Corta el docstring y lo pega entre las líneas [clinic], eliminando toda la basura que la convierte en una cadena C entre comillas. Cuando haya terminado, debería tener solo el texto, basado en el margen izquierdo, sin una línea de más de 80 caracteres. (Argument Clinic conservará las sangrías dentro del docstring).

Si el docstring antiguo tenía una primera línea que parecía una firma de función, elimine esa línea. (El docstring ya no la necesita; cuando use help() en su incorporado en el futuro, la primera línea se creará automáticamente en función de la firma de la función).

Muestra:

/*[clinic input]
Write a pickled representation of obj to the open file.
[clinic start generated code]*/

Si su cadena de documentos no tiene una línea de «resumen», Argument Clinic se quejará. Así que asegurémonos de que tenga uno. La línea de «resumen» debe ser un párrafo que consta de una sola línea de 80 columnas al comienzo de la cadena de documentos.

(Nuestro docstring de ejemplo consiste únicamente en una línea de resumen, por lo que el código de muestra no tiene que cambiar para este paso.)

Sobre el docstring, ingrese el nombre de la función, seguido de una línea en blanco. Este debería ser el nombre de Python de la función, y debería ser la ruta de puntos completa a la función; debería comenzar con el nombre del módulo, incluir cualquier submódulo y, si la función es un método en una clase, debe incluir el nombre de la clase también.

Muestra:

/*[clinic input]
_pickle.Pickler.dump

Write a pickled representation of obj to the open file.
[clinic start generated code]*/

Si es la primera vez que ese módulo o clase se utiliza con Argument Clinic en este archivo C, debe declarar el módulo o la clase. La higiene de la clínica de argumentos apropiados prefiere declararlos en un bloque separado en algún lugar cerca de la parte superior del archivo C, de la misma manera que los archivos de inclusión y las estadísticas van en la parte superior. (En nuestro código de muestra, solo mostraremos los dos bloques uno al lado del otro).

El nombre de la clase y el módulo debe ser el mismo que el visto por Python. Compruebe el nombre definido en PyModuleDef o PyTypeObject según corresponda.

Cuando declaras una clase, también debes especificar dos aspectos de su tipo en C: la declaración de tipo que usarías para un puntero a una instancia de esta clase y un puntero a PyTypeObject para esto clase.

Muestra:

/*[clinic input]
module _pickle
class _pickle.Pickler "PicklerObject *" "&Pickler_Type"
[clinic start generated code]*/

/*[clinic input]
_pickle.Pickler.dump

Write a pickled representation of obj to the open file.
[clinic start generated code]*/

Declare cada uno de los parámetros a la función. Cada parámetro debe tener su propia línea. Todas las líneas de parámetros deben tener sangría del nombre de la función y el docstring.

La forma general de estas líneas de parámetros es la siguiente:

name_of_parameter: converter

Si el parámetro tiene un valor predeterminado, agréguelo después del convertidor:

name_of_parameter: converter = default_value

El soporte de Argument Clinic para «valores predeterminados» es bastante sofisticado; por favor vea la sección a continuación sobre valores predeterminados para más información.

Agrega una línea en blanco debajo de los parámetros.

¿Qué es un «convertidor»? Establece tanto el tipo de variable utilizada en C como el método para convertir el valor de Python en un valor de C en tiempo de ejecución. Por ahora, va a utilizar lo que se llama un «convertidor heredado», una sintaxis conveniente destinada a facilitar la migración del código antiguo a Argument Clinic.

Para cada parámetro, copie la «unidad de formato» para ese parámetro del argumento de formato PyArg_Parse() y especifique eso como su convertidor, como una cadena entre comillas. («unidad de formato» es el nombre formal de la subcadena de caracteres de uno a tres caracteres del parámetro format que le dice a la función de análisis de argumentos cuál es el tipo de variable y cómo convertirla. Para más información sobre las unidades de formato por favor vea Analizando argumentos y construyendo valores.)

Para unidades de formato de caracteres múltiples como z#, use la cadena completa de dos o tres caracteres.

Muestra:

 /*[clinic input]
 module _pickle
 class _pickle.Pickler "PicklerObject *" "&Pickler_Type"
 [clinic start generated code]*/

 /*[clinic input]
 _pickle.Pickler.dump

    obj: 'O'

Write a pickled representation of obj to the open file.
[clinic start generated code]*/

Si su función tiene | en la cadena de formato, lo que significa que algunos parámetros tienen valores predeterminados, puede ignorarlo. Argument Clinic infiere qué parámetros son opcionales en función de si tienen o no valores predeterminados.

Si su función tiene $ en la cadena de caracteres de formato, lo que significa que toma argumentos de solo palabras clave, especifique * en una línea antes del primer argumento de solo palabras clave, con la misma indentación que las líneas de parámetros.

(_pickle.Pickler.dump no tiene ninguno, por lo que nuestro ejemplo no ha cambiado.)

Si la función C existente llama a PyArg_ParseTuple() (a diferencia de PyArg_ParseTupleAndKeywords()), entonces todos sus argumentos son solo posicionales.

Para marcar todos los parámetros como solo posicionales en Argument Clinic, agregue un / en una línea después del último parámetro, con la misma sangría que las líneas de parámetros.

Actualmente esto es todo o nada; o todos los parámetros son solo posicionales o ninguno de ellos lo es. (En el futuro, Argument Clinic puede relajar esta restricción).

Muestra:

/*[clinic input]
module _pickle
class _pickle.Pickler "PicklerObject *" "&Pickler_Type"
[clinic start generated code]*/

/*[clinic input]
_pickle.Pickler.dump

    obj: 'O'
    /

Write a pickled representation of obj to the open file.
[clinic start generated code]*/

Es útil escribir una cadena de documentos por parámetro para cada parámetro. Pero los docstrings por parámetro son opcionales; puede omitir este paso si lo prefiere.

A continuación, se explica cómo agregar un docstring por parámetro. La primera línea del docstring por parámetro debe tener más sangría que la definición del parámetro. El margen izquierdo de esta primera línea establece el margen izquierdo para todo el docstring por parámetro; todo el texto que escriba se verá afectado por esta cantidad. Puede escribir todo el texto que desee, en varias líneas si lo desea.

Muestra:

/*[clinic input]
module _pickle
class _pickle.Pickler "PicklerObject *" "&Pickler_Type"
[clinic start generated code]*/

/*[clinic input]
_pickle.Pickler.dump

    obj: 'O'
        The object to be pickled.
    /

Write a pickled representation of obj to the open file.
[clinic start generated code]*/

Guarde y cierre el archivo, luego ejecute Tools/clinic/clinic.py en él. ¡Con suerte, todo funcionó — su bloque ahora tiene salida y se ha generado un archivo .c.h ! Vuelva a abrir el archivo en su editor de texto para ver:

/*[clinic input]
_pickle.Pickler.dump

    obj: 'O'
        The object to be pickled.
    /

Write a pickled representation of obj to the open file.
[clinic start generated code]*/

static PyObject *
_pickle_Pickler_dump(PicklerObject *self, PyObject *obj)
/*[clinic end generated code: output=87ecad1261e02ac7 input=552eb1c0f52260d9]*/

Obviamente, si Argument Clinic no produjo ningún resultado, es porque encontró un error en su entrada. Siga corrigiendo sus errores y vuelva a intentarlo hasta que Argument Clinic procese su archivo sin quejas.

Para facilitar la lectura, la mayor parte del código de pegamento se ha generado en un archivo .c.h. Deberá incluir eso en su archivo .c original, generalmente justo después del bloque del módulo de la clínica:

#include "clinic/_pickle.c.h"

Vuelva a verificar que el código de análisis de argumentos generado por Argument Clinic se ve básicamente igual al código existente.

Primero, asegúrese de que ambos lugares usen la misma función de análisis de argumentos. El código existente debe llamar a PyArg_ParseTuple() o PyArg_ParseTupleAndKeywords(); asegúrese de que el código generado por Argument Clinic llame a la misma exacta función.

En segundo lugar, la cadena de formato pasada a PyArg_ParseTuple() o PyArg_ParseTupleAndKeywords() debe ser exactamente la misma que la escrita a mano en la función existente, hasta los dos puntos o punto y coma.

(Argument Clinic siempre genera sus cadenas de caracteres de formato con un : seguido del nombre de la función. Si la cadena de caracteres de formato del código existente termina con ;, para proporcionar ayuda de uso, este cambio es inofensivo; no se preocupe)

En tercer lugar, para los parámetros cuyas unidades de formato requieren dos argumentos (como una variable de longitud, una cadena de codificación o un puntero a una función de conversión), asegúrese de que el segundo argumento sea exactamente el mismo entre las dos invocaciones.

En cuarto lugar, dentro de la parte de salida del bloque, encontrará una macro de preprocesador que define la estructura static PyMethodDef apropiada para este incorporado:

#define __PICKLE_PICKLER_DUMP_METHODDEF    \
{"dump", (PyCFunction)__pickle_Pickler_dump, METH_O, __pickle_Pickler_dump__doc__},

Esta estructura estática debe ser exactamente la misma que la estructura estática existente PyMethodDef para este incorporado.

Si alguno de estos elementos difiere de alguna manera, ajuste la especificación de la función de Argument Clinic y vuelva a ejecutar Tools/clinic/clinic.py hasta que sean iguales.

Observe que la última línea de su salida es la declaración de su función «impl». Aquí es donde va la implementación incorporada. Elimine el prototipo existente de la función que está modificando, pero deje la llave de apertura. Ahora elimine su código de análisis de argumentos y las declaraciones de todas las variables en las que vierte los argumentos. Observe cómo los argumentos de Python ahora son argumentos para esta función implícita; si la implementación usó nombres diferentes para estas variables, corríjalo.

Reiteremos, solo porque es un poco extraño. Su código ahora debería verse así:

static return_type
your_function_impl(...)
/*[clinic end generated code: checksum=...]*/
{
...

Argument Clinic generó la línea de suma de comprobación y el prototipo de función justo encima de ella. Debe escribir las llaves de apertura (y cierre) para la función y la implementación en el interior.

Muestra:

/*[clinic input]
module _pickle
class _pickle.Pickler "PicklerObject *" "&Pickler_Type"
[clinic start generated code]*/
/*[clinic end generated code: checksum=da39a3ee5e6b4b0d3255bfef95601890afd80709]*/

/*[clinic input]
_pickle.Pickler.dump

    obj: 'O'
        The object to be pickled.
    /

Write a pickled representation of obj to the open file.
[clinic start generated code]*/

PyDoc_STRVAR(__pickle_Pickler_dump__doc__,
"Write a pickled representation of obj to the open file.\n"
"\n"
...
static PyObject *
_pickle_Pickler_dump_impl(PicklerObject *self, PyObject *obj)
/*[clinic end generated code: checksum=3bd30745bf206a48f8b576a1da3d90f55a0a4187]*/
{
    /* Check whether the Pickler was initialized correctly (issue3664).
       Developers often forget to call __init__() in their subclasses, which
       would trigger a segfault without this check. */
    if (self->write == NULL) {
        PyErr_Format(PicklingError,
                     "Pickler.__init__() was not called by %s.__init__()",
                     Py_TYPE(self)->tp_name);
        return NULL;
    }

    if (_Pickler_ClearBuffer(self) < 0)
        return NULL;

    ...

¿Recuerda la macro con la estructura PyMethodDef para esta función? Busque la estructura existente PyMethodDef para esta función y la reemplaza con una referencia a la macro. (Si el incorporado está en el alcance del módulo, esto probablemente estará muy cerca del final del archivo; si el incorporado es un método de clase, probablemente estará debajo pero relativamente cerca de la implementación).

Tenga en cuenta que el cuerpo de la macro contiene una coma al final. Entonces, cuando reemplace la estructura static PyMethodDef existente con la macro, no agregue una coma al final.

Muestra:

static struct PyMethodDef Pickler_methods[] = {
    __PICKLE_PICKLER_DUMP_METHODDEF
    __PICKLE_PICKLER_CLEAR_MEMO_METHODDEF
    {NULL, NULL}                /* sentinel */
};

Compile y luego ejecute las partes relevantes del conjunto de pruebas de regresión. Este cambio no debería introducir nuevas advertencias o errores en tiempo de compilación, y no debería haber ningún cambio visible desde el exterior en el comportamiento de Python.

Bueno, excepto por una diferencia: inspect.signature() ejecutar en su función ahora debería proporcionar una firma válida!

¡Felicitaciones, ha adaptado su primera función para trabajar con Argument Clinic!

Temas avanzados

Ahora que ha tenido algo de experiencia trabajando con Argument Clinic, es hora de algunos temas avanzados.

Valores predeterminados simbólicos

El valor predeterminado que proporcione para un parámetro no puede ser una expresión arbitraria. Actualmente, lo siguiente se admite explícitamente:

Constantes numéricas (enteros y flotantes)

Constantes de cadena de caracteres

True, False, y None

Constantes simbólicas simples como sys.maxsize, que debe comenzar con el nombre del módulo

En caso de que tenga curiosidad, esto se implementa en from_builtin() en Lib/inspect.py.

(En el futuro, esto puede necesitar ser aún más elaborado, para permitir expresiones completas como CONSTANT - 1.)

Cambiar el nombre de las funciones y variables C generadas por Argument Clinic

Argument Clinic nombra automáticamente las funciones que genera para usted. Ocasionalmente, esto puede causar un problema, si el nombre generado choca con el nombre de una función C existente. Hay una solución sencilla: anule los nombres utilizados para las funciones de C. Simplemente agregue la palabra clave "as" a la línea de declaración de su función, seguida del nombre de la función que desea usar. Argument Clinic usará ese nombre de función para la función base (generada), luego agregará "_impl" al final y lo usará para el nombre de la función impl.

Por ejemplo, si quisiéramos cambiar el nombre de las funciones de C generadas para pickle.Pickler.dump, se vería así:

/*[clinic input]
pickle.Pickler.dump as pickler_dumper

...

La función base ahora se llamaría pickler_dumper(), y la función implícita ahora se llamaría pickler_dumper_impl().

De manera similar, es posible que tenga un problema en el que desee asignar un nombre específico de Python a un parámetro, pero ese nombre puede ser inconveniente en C. Argument Clinic le permite asignar nombres diferentes a un parámetro en Python y en C, usando el mismo "as" como sintaxis:

/*[clinic input]
pickle.Pickler.dump

    obj: object
    file as file_obj: object
    protocol: object = NULL
    *
    fix_imports: bool = True

Aquí, el nombre usado en Python (en la firma y el arreglo de keywords) sería file, pero la variable C se llamaría file_obj.

¡También puede usar esto para cambiar el nombre del parámetro self!

Convirtiendo funciones usando PyArg_UnpackTuple

Para convertir una función que analiza sus argumentos con PyArg_UnpackTuple(), simplemente escribe todos los argumentos, especificando cada uno como un object. Puede especificar el argumento type para convertir el tipo según corresponda. Todos los argumentos deben estar marcados como solo posicionales (agregue un / en una línea después del último argumento).

Actualmente, el código generado usará PyArg_ParseTuple(), pero esto cambiará pronto.

Grupos opcionales

Algunas funciones heredadas tienen un enfoque complicado para analizar sus argumentos: cuentan el número de argumentos posicionales, luego usan una instrucción switch para llamar a una de varias llamadas diferentes PyArg_ParseTuple() dependiendo de cuántos argumentos posicionales existen. (Estas funciones no pueden aceptar argumentos de solo palabras clave). Este enfoque se usó para simular argumentos opcionales antes de que se creara PyArg_ParseTupleAndKeywords().

Si bien las funciones que utilizan este enfoque a menudo se pueden convertir para usar PyArg_ParseTupleAndKeywords(), argumentos opcionales y valores predeterminados, no siempre es posible. Algunas de estas funciones heredadas tienen comportamientos PyArg_ParseTupleAndKeywords() no admite directamente. El ejemplo más obvio es la función incorporada range(), que tiene un argumento opcional en el lado izquierdo de su argumento requerido. Otro ejemplo es curses.window.addch(), que tiene un grupo de dos argumentos que siempre deben especificarse juntos. (Los argumentos se denominan x e y; si llama a la función pasando x, también debe pasar y, y si no pasa x tampoco puede pasar y.)

En cualquier caso, el objetivo de Argument Clinic es admitir el análisis de argumentos para todas las incorporaciones CPython existentes sin cambiar su semántica. Por lo tanto, Argument Clinic admite este enfoque alternativo de análisis, utilizando lo que se denominan grupos opcionales. Los grupos opcionales son grupos de argumentos que deben pasarse todos juntos. Pueden estar a la izquierda o la derecha de los argumentos requeridos. Solo se pueden usar con parámetros de solo posición.

Nota

Los grupos opcionales solo están pensados para su uso al convertir funciones que realizan múltiples llamadas a PyArg_ParseTuple()! Las funciones que usan cualquier otro enfoque para analizar argumentos deben casi nunca convertirse a Argument Clinic usando grupos opcionales. Las funciones que utilizan grupos opcionales actualmente no pueden tener firmas precisas en Python, porque Python simplemente no comprende el concepto. Evite el uso de grupos opcionales siempre que sea posible.

Para especificar un grupo opcional, agregue un [ en una línea antes de los parámetros que desea agrupar y un ] en una línea después de estos parámetros. Como ejemplo, así es como curses.window.addch usa grupos opcionales para hacer que los primeros dos parámetros y el último parámetro sean opcionales:

/*[clinic input]

curses.window.addch

    [
    x: int
      X-coordinate.
    y: int
      Y-coordinate.
    ]

    ch: object
      Character to add.

    [
    attr: long
      Attributes for the character.
    ]
    /

...

Notas:

Para cada grupo opcional, se pasará un parámetro adicional a la función impl que representa al grupo. El parámetro será un int llamado grupo_{direction}_{number}, donde {direction} es right o left dependiendo de si el grupo está antes o después los parámetros requeridos, y {number} es un número que aumenta monótonamente (comenzando en 1) que indica qué tan lejos está el grupo de los parámetros requeridos. Cuando se llama a impl, este parámetro se establecerá en cero si este grupo no se usó, y se establecerá en un valor distinto de cero si se usó este grupo. (Por usado o no usado, me refiero a si los parámetros recibieron argumentos en esta invocación).

Si no hay argumentos requeridos, los grupos opcionales se comportarán como si estuvieran a la derecha de los argumentos requeridos.

En el caso de ambigüedad, el código de análisis de argumentos favorece los parámetros de la izquierda (antes de los parámetros requeridos).

Los grupos opcionales solo pueden contener parámetros posicionales.

Los grupos opcionales son solo destinados al código heredado. No utilice grupos opcionales para el código nuevo.

Usar convertidores de Argument Clinic reales, en lugar de «convertidores heredados»

Para ahorrar tiempo y minimizar cuánto necesita aprender para lograr su primer puerto a Argument Clinic, el tutorial anterior le indica que use «convertidores heredados». Los «convertidores heredados» son una conveniencia, diseñados explícitamente para facilitar la migración del código existente a Argument Clinic. Y para ser claros, su uso es aceptable al portar código para Python 3.4.

Sin embargo, a largo plazo probablemente queramos que todos nuestros bloques utilicen la sintaxis real de Argument Clinic para los convertidores. ¿Por qué? Un par de razones:

Los convertidores adecuados son mucho más fáciles de leer y más claros en su intención.

Hay algunas unidades de formato que no se admiten como «convertidores heredados», porque requieren argumentos y la sintaxis del convertidor heredado no admite la especificación de argumentos.

En el futuro, es posible que tengamos una nueva biblioteca de análisis de argumentos que no esté restringida a lo que PyArg_ParseTuple() admite; esta flexibilidad no estará disponible para los parámetros que utilizan convertidores heredados.

Por lo tanto, si no le importa un poco de esfuerzo adicional, utilice los convertidores normales en lugar de los convertidores heredados.

En pocas palabras, la sintaxis de los convertidores de Argument Clinic (no heredados) parece una llamada a una función de Python. Sin embargo, si no hay argumentos explícitos para la función (todas las funciones toman sus valores predeterminados), puede omitir los paréntesis. Por tanto, bool y bool() son exactamente los mismos convertidores.

Todos los argumentos para los convertidores de Argument Clinic son solo de palabras clave. Todos los convertidores de Argument Clinic aceptan los siguientes argumentos:

c_default

El valor predeterminado para este parámetro cuando se define en C. Específicamente, será el inicializador de la variable declarada en la «función de análisis». Consulte la sección sobre valores predeterminados para saber cómo usar esto. Especificado como una cadena de caracteres.

annotation

El valor de anotación para este parámetro. Actualmente no es compatible, porque PEP 8 [https://www.python.org/dev/peps/pep-0008] exige que la biblioteca de Python no use anotaciones.

Además, algunos convertidores aceptan argumentos adicionales. Aquí hay una lista de estos argumentos, junto con sus significados:

accept

Un conjunto de tipos de Python (y posiblemente pseudo-tipos); esto restringe el argumento permitido de Python a valores de estos tipos. (Esta no es una infraestructura de propósito general; por regla general, solo admite listas específicas de tipos como se muestra en la tabla de convertidores heredados).

Para aceptar None, agregue NoneType a este conjunto.

bitwise

Solo se admite para enteros sin signo. El valor entero nativo de este argumento de Python se escribirá en el parámetro sin ninguna verificación de rango, incluso para valores negativos.

converter

Solo compatible con el convertidor de objetos. Especifica el nombre de una «función de conversión» C para convertir este objeto en un tipo nativo.

encoding

Solo compatible con cadenas de caracteres. Especifica la codificación que se utilizará al convertir esta cadena de un valor Python str (Unicode) en un valor char * de C.

subclass_of

Solo compatible con el convertidor de objetos. Requiere que el valor de Python sea una subclase de un tipo de Python, como se expresa en C.

type

Solo compatible con los convertidores de object y self. Especifica el tipo C que se utilizará para declarar la variable. El valor predeterminado es "PyObject *".

zeroes

Solo compatible con cadenas. Si es verdadero, se permiten bytes NUL incrustados ('\\0') dentro del valor. La longitud de la cadena se pasará a la función impl, justo después del parámetro de cadena, como un parámetro llamado <parameter_name>_length.

Tenga en cuenta que no todas las combinaciones posibles de argumentos funcionarán. Por lo general, estos argumentos se implementan mediante unidades de formato PyArg_ParseTuple específicas, con un comportamiento específico. Por ejemplo, actualmente no puede llamar a unsigned_short sin especificar también bitwise=True. Aunque es perfectamente razonable pensar que esto funcionaría, esta semántica no se asigna a ninguna unidad de formato existente. Entonces, Argument Clinic no lo admite. (O, al menos, todavía no).

A continuación se muestra una tabla que muestra el mapeo de convertidores heredados en convertidores de Argument Clinic reales. A la izquierda está el convertidor heredado, a la derecha está el texto con el que lo reemplazaría.

'B'

unsigned_char(bitwise=True)

'b'

unsigned_char

'c'

char

'C'

int(accept={str})

'd'

double

'D'

Py_complex

'es'

str(encoding='name_of_encoding')

'es#'

str(encoding='name_of_encoding', zeroes=True)

'et'

str(encoding='name_of_encoding', accept={bytes, bytearray, str})

'et#'

str(encoding='name_of_encoding', accept={bytes, bytearray, str}, zeroes=True)

'f'

float

'h'

short

'H'

unsigned_short(bitwise=True)

'i'

int

'I'

unsigned_int(bitwise=True)

'k'

unsigned_long(bitwise=True)

'K'

unsigned_long_long(bitwise=True)

'l'

long

'L'

long long

'n'

Py_ssize_t

'O'

object

'O!'

object(subclass_of='&PySomething_Type')

'O&'

object(converter='name_of_c_function')

'p'

bool

'S'

PyBytesObject

's'

str

's#'

str(zeroes=True)

's*'

Py_buffer(accept={buffer, str})

'U'

unicode

'u'

Py_UNICODE

'u#'

Py_UNICODE(zeroes=True)

'w*'

Py_buffer(accept={rwbuffer})

'Y'

PyByteArrayObject

'y'

str(accept={bytes})

'y#'

str(accept={robuffer}, zeroes=True)

'y*'

Py_buffer

'Z'

Py_UNICODE(accept={str, NoneType})

'Z#'

Py_UNICODE(accept={str, NoneType}, zeroes=True)

'z'

str(accept={str, NoneType})

'z#'

str(accept={str, NoneType}, zeroes=True)

'z*'

Py_buffer(accept={buffer, str, NoneType})

Como ejemplo, aquí está nuestra muestra pickle.Pickler.dump usando el convertidor adecuado:

/*[clinic input]
pickle.Pickler.dump

    obj: object
        The object to be pickled.
    /

Write a pickled representation of obj to the open file.
[clinic start generated code]*/

Una ventaja de los convertidores reales es que son más flexibles que los convertidores heredados. Por ejemplo, el convertidor unsigned_int (y todos los convertidores unsigned_) se pueden especificar sin bitwise=True. Su comportamiento predeterminado realiza una verificación de rango en el valor y no aceptarán números negativos. ¡No puedes hacer eso con un convertidor heredado!

Argument Clinic le mostrará todos los convertidores que tiene disponibles. Para cada convertidor, le mostrará todos los parámetros que acepta, junto con el valor predeterminado para cada parámetro. Simplemente ejecute Tools/clinic/clinic.py --converters para ver la lista completa.

Py_buffer

Cuando se utiliza el convertidor Py_buffer (o los convertidores heredados 's*', 'w*', '*y' o 'z*' ), no debes llamar a PyBuffer_Release() en el búfer provisto. Argument Clinic genera código que lo hace por usted (en la función de análisis).

Convertidores avanzados

¿Recuerda esas unidades de formato que omitió por primera vez porque eran avanzadas? Aquí le mostramos cómo manejarlas también.

El truco es que todas esas unidades de formato toman argumentos, ya sean funciones de conversión o tipos, o cadenas que especifican una codificación. (Pero los «convertidores heredados» no admiten argumentos. Por eso los omitimos para su primera función). El argumento que especificó para la unidad de formato ahora es un argumento para el convertidor; este argumento es converter (para O&), subclass_of (para O!) o encoding (para todas las unidades de formato que comienzan con e).

Al usar subclass_of, es posible que también desee usar el otro argumento personalizado para object(): type, que le permite establecer el tipo que realmente se usa para el parámetro. Por ejemplo, si desea asegurarse de que el objeto es una subclase de PyUnicode_Type, probablemente desee utilizar el convertidor object(type='PyUnicodeObject *', subclass_of='&PyUnicode_Type').

Un posible problema con el uso de Argument Clinic: elimina cierta flexibilidad posible para las unidades de formato que comienzan con e. Al escribir una llamada PyArg_Parse a mano, teóricamente podrías decidir en tiempo de ejecución qué cadena de codificación pasar a PyArg_ParseTuple(). Pero ahora esta cadena debe estar codificada en tiempo de preprocesamiento de Argument-Clinic. Esta limitación es deliberada; hizo que el soporte de esta unidad de formato fuera mucho más fácil y puede permitir futuras optimizaciones. Esta restricción no parece irrazonable; el propio CPython siempre pasa cadenas de codificación estáticas codificadas para parámetros cuyas unidades de formato comienzan con e.

Valores predeterminados de los parámetros

Los valores predeterminados de los parámetros pueden ser cualquiera de varios valores. En su forma más simple, pueden ser literales string, int o float:

foo: str = "abc"
bar: int = 123
bat: float = 45.6

También pueden usar cualquiera de las constantes incorporadas de Python:

yep:  bool = True
nope: bool = False
nada: object = None

También hay soporte especial para un valor predeterminado de NULL y para expresiones simples, documentadas en las siguientes secciones.

El valor predeterminado NULL

Para los parámetros de cadena de caracteres y objeto, puede establecerlos en None para indicar que no hay ningún valor predeterminado. Sin embargo, eso significa que la variable C se inicializará en Py_None. Por conveniencia, hay un valor especial llamado NULL solo por esta razón: desde la perspectiva de Python se comporta como un valor predeterminado de None, pero la variable C se inicializa con NULL.

Expresiones especificadas como valores por defecto

El valor predeterminado de un parámetro puede ser más que un valor literal. Puede ser una expresión completa, utilizando operadores matemáticos y buscando atributos en objetos. Sin embargo, este soporte no es exactamente simple, debido a una semántica no obvia.

Considere el siguiente ejemplo:

foo: Py_ssize_t = sys.maxsize - 1

sys.maxsize puede tener diferentes valores en diferentes plataformas. Por lo tanto, Argument Clinic no puede simplemente evaluar esa expresión localmente y codificarla en C. Por lo tanto, almacena el valor predeterminado de tal manera que se evaluará en tiempo de ejecución, cuando el usuario solicite la firma de la función.

¿Qué espacio de nombres está disponible cuando se evalúa la expresión? Se evalúa en el contexto del módulo del que procede el incorporado. Entonces, si su módulo tiene un atributo llamado «max_widgets», simplemente puede usarlo:

foo: Py_ssize_t = max_widgets

Si el símbolo no se encuentra en el módulo actual, falla para buscar en sys.modules. Así es como puede encontrar sys.maxsize, por ejemplo. (Dado que no sabe de antemano qué módulos cargará el usuario en su intérprete, es mejor limitarse a los módulos que están precargados por el propio Python).

La evaluación de los valores predeterminados solo en tiempo de ejecución significa que Argument Clinic no puede calcular el valor predeterminado de C equivalente correcto. Entonces necesita decirlo explícitamente. Cuando usa una expresión, también debe especificar la expresión equivalente en C, usando el parámetro c_default para el convertidor:

foo: Py_ssize_t(c_default="PY_SSIZE_T_MAX - 1") = sys.maxsize - 1

Otra complicación: Argument Clinic no puede saber de antemano si la expresión que proporciona es válida o no. Lo analiza para asegurarse de que parece legal, pero no puede realmente saberlo. ¡Debe tener mucho cuidado al usar expresiones para especificar valores que están garantizados para ser válidos en tiempo de ejecución!

Finalmente, dado que las expresiones deben ser representables como valores C estáticos, existen muchas restricciones sobre las expresiones legales. Aquí hay una lista de funciones de Python que no está autorizado a usar:

Llamadas a funciones.

Declaraciones if en línea (3 if foo else 5).

Desempaque automático de secuencia (*[1, 2, 3]).

Comprensiones de list/set/dict y expresiones generadoras.

Literales tuple/list/set/dict.

Usando un convertidor de retorno

De forma predeterminada, la función implícita Argument Clinic genera para usted retorna PyObject *. Pero su función C a menudo calcula algún tipo de C, luego lo convierte en el PyObject * en el último momento. Argument Clinic se encarga de convertir sus entradas de tipos de Python en tipos C nativos; ¿por qué no convertir su valor de retorno de un tipo C nativo en un tipo Python también?

Eso es lo que hace un «convertidor de retorno». Cambia su función impl para retornar algún tipo de C, luego agrega código a la función generada (no implícita) para manejar la conversión de ese valor en el PyObject * apropiado.

La sintaxis de los convertidores de retorno es similar a la de los convertidores de parámetros. Especifica el convertidor de retorno como si fuera una anotación de retorno en la función en sí. Los convertidores de retorno se comportan de la misma manera que los convertidores de parámetros; aceptan argumentos, todos los argumentos son solo palabras clave y, si no está cambiando ninguno de los argumentos predeterminados, puede omitir los paréntesis.

(Si utiliza tanto "as" `` *y* un convertidor de retorno para su función, el ``"as" debe aparecer antes del convertidor de retorno.)

Hay una complicación adicional al usar convertidores de retorno: ¿cómo indica que se ha producido un error? Normalmente, una función retorna un puntero válido (no NULL) para el éxito y NULL para el error. Pero si usa un convertidor de retorno de enteros, todos los enteros son válidos. ¿Cómo puede Argument Clinic detectar un error? Su solución: cada convertidor de retorno busca implícitamente un valor especial que indica un error. Si retorna ese valor y se ha establecido un error (PyErr_Occurred() retorna un valor verdadero), el código generado propagará el error. De lo contrario, codificará el valor que retorna como de costumbre.

Actualmente, Argument Clinic solo admite unos pocos convertidores de retorno:

bool
int
unsigned int
long
unsigned int
size_t
Py_ssize_t
float
double
DecodeFSDefault

Ninguno de estos toma parámetros. Para los tres primeros, retorna -1 para indicar error. Para DecodeFSDefault, el tipo de retorno es const char *; retorna un puntero NULL para indicar un error.

(También hay un convertidor experimental NoneType, que le permite retornar Py_None en caso de éxito o NULL en caso de falla, sin tener que incrementar el recuento de referencias en Py_None. seguro que agrega suficiente claridad para que valga la pena usarlo)

Para ver todos los convertidores retornados que admite Argument Clinic, junto con sus parámetros (si los hay), simplemente ejecute Tools/clinic/clinic.py --converters para ver la lista completa.

Clonando funciones existentes

Si tiene varias funciones que parecen similares, es posible que pueda utilizar la función «clone» de Clinic. Cuando clona una función existente, reutiliza:

sus parámetros, incluyendo

sus nombres,

sus convertidores, con todos los parámetros,

sus valores predeterminados,

sus docstrings por parámetro,

su kind (ya sea solo posicional, posicional o por palabra clave, o solo por palabra clave), y

su convertidor de retorno.

Lo único que no se ha copiado de la función original es su docstring; la sintaxis le permite especificar un nuevo docstring.

Aquí está la sintaxis para clonar una función:

/*[clinic input]
module.class.new_function [as c_basename] = module.class.existing_function

Docstring for new_function goes here.
[clinic start generated code]*/

(Las funciones pueden estar en diferentes módulos o clases. Escribí module.class en la muestra solo para ilustrar que debe usar la ruta completa a ambas funciones.)

Lo sentimos, no hay sintaxis para clonar parcialmente una función o clonar una función y luego modificarla. La clonación es una propuesta de todo o nada.

Además, la función desde la que está clonando debe haberse definido previamente en el archivo actual.

Llamando código Python

El resto de los temas avanzados requieren que escriba código Python que vive dentro de su archivo C y modifica el estado de ejecución de Argument Clinic. Esto es simple: simplemente define un bloque de Python.

Un bloque Python utiliza diferentes líneas delimitadoras que un bloque de función de la Argument Clinic. Se parece a esto:

/*[python input]
# python code goes here
[python start generated code]*/

Todo el código dentro del bloque de Python se ejecuta en el momento en que se analiza. Todo el texto escrito en stdout dentro del bloque se redirige a la «salida» después del bloque.

Como ejemplo, aquí hay un bloque de Python que agrega una variable entera estática al código C

/*[python input]
print('static int __ignored_unused_variable__ = 0;')
[python start generated code]*/
static int __ignored_unused_variable__ = 0;
/*[python checksum:...]*/

Usando un «auto convertidor»

Argument Clinic agrega automáticamente un parámetro «self» para usted usando un convertidor predeterminado. Establece automáticamente el tipo de este parámetro en el «puntero a una instancia» que especificó cuando declaró el tipo. Sin embargo, puede anular el convertidor de Argument Clinic y especificar uno usted mismo. Simplemente agregue su propio parámetro self como el primer parámetro en un bloque y asegúrese de que su convertidor sea una instancia de self_converter o una subclase del mismo.

¿Qué sentido tiene ? Esto le permite anular el tipo de self o darle un nombre predeterminado diferente.

¿Cómo especifica el tipo personalizado al que desea transmitir self? Si solo tiene una o dos funciones con el mismo tipo para self, puede usar directamente el convertidor self existente de Argument Clinic, pasando el tipo que desea usar como parámetro de type:

/*[clinic input]

_pickle.Pickler.dump

  self: self(type="PicklerObject *")
  obj: object
  /

Write a pickled representation of the given object to the open file.
[clinic start generated code]*/

Por otro lado, si tiene muchas funciones que usarán el mismo tipo para self, es mejor crear su propio convertidor, subclasificando self_converter pero sobrescribiendo el miembro `` type``:

/*[python input]
class PicklerObject_converter(self_converter):
    type = "PicklerObject *"
[python start generated code]*/

/*[clinic input]

_pickle.Pickler.dump

  self: PicklerObject
  obj: object
  /

Write a pickled representation of the given object to the open file.
[clinic start generated code]*/

Escribiendo un convertidor personalizado

Como dijimos en la sección anterior… ¡puedes escribir tus propios convertidores! Un convertidor es simplemente una clase de Python que hereda de CConverter. El propósito principal de un convertidor personalizado es si tiene un parámetro que usa la unidad de formato O&; analizar este parámetro significa llamar a PyArg_ParseTuple() «función de conversión».

Su clase de convertidor debe llamarse *something*_converter. Si el nombre sigue esta convención, entonces su clase de convertidor se registrará automáticamente con Argument Clinic; su nombre será el nombre de su clase con el sufijo _converter eliminado. (Esto se logra con una metaclase).

No debe subclasificar CConverter.__init__. En su lugar, debe escribir una función converter_init(). converter_init() siempre acepta un parámetro self; después de eso, todos los parámetros adicionales deben ser solo palabras clave. Cualquier argumento que se pase al convertidor en Argument Clinic se pasará a su converter_init().

Hay algunos miembros adicionales de CConverter que tal vez desee especificar en su subclase. Aquí está la lista actual:

type

El tipo C que se utilizará para esta variable. type debe ser una cadena de Python que especifique el tipo, por ejemplo int. Si se trata de un tipo de puntero, la cadena de tipo debe terminar con '*'.

default

El valor predeterminado de Python para este parámetro, como un valor de Python. O el valor mágico unspecified si no hay ningún valor predeterminado.

py_default

default como debería aparecer en el código Python, como una cadena. O None si no hay un valor predeterminado.

c_default

default como debería aparecer en el código C, como una cadena de caracteres. O None si no hay un valor predeterminado.

c_ignored_default

El valor predeterminado utilizado para inicializar la variable C cuando no hay ningún valor predeterminado, pero no especificar un valor predeterminado puede resultar en una advertencia de «variable no inicializada». Esto puede suceder fácilmente cuando se utilizan grupos de opciones, aunque el código escrito correctamente nunca utilizará este valor, la variable se pasa al impl, y el compilador de C se quejará del «uso» del valor no inicializado. Este valor siempre debe ser una cadena de caracteres no vacía.

converter

El nombre de la función de conversión de C, como una cadena de caracteres.

impl_by_reference

Un valor booleano. Si es verdadero, Argument Clinic agregará un & delante del nombre de la variable al pasarlo a la función impl.

parse_by_reference

Un valor booleano. Si es verdadero, Argument Clinic agregará un & delante del nombre de la variable al pasarlo a PyArg_ParseTuple().

Aquí está el ejemplo más simple de un convertidor personalizado, de Modules/zlibmodule.c:

/*[python input]

class ssize_t_converter(CConverter):
    type = 'Py_ssize_t'
    converter = 'ssize_t_converter'

[python start generated code]*/
/*[python end generated code: output=da39a3ee5e6b4b0d input=35521e4e733823c7]*/

This block adds a converter to Argument Clinic named ssize_t. Parameters declared as ssize_t will be declared as type Py_ssize_t, and will be parsed by the 'O&' format unit, which will call the ssize_t_converter converter function. ssize_t variables automatically support default values.

Los convertidores personalizados más sofisticados pueden insertar código C personalizado para manejar la inicialización y la limpieza. Puede ver más ejemplos de convertidores personalizados en el árbol de fuentes de CPython; grep los archivos C para la cadena CConverter.

Escribiendo un convertidor de retorno personalizado

Escribir un convertidor de retorno personalizado es muy parecido a escribir un convertidor personalizado. Excepto que es algo más simple, porque los convertidores de retorno son en sí mismos mucho más simples.

Los convertidores de retorno deben tener una subclase de CReturnConverter. Todavía no hay ejemplos de convertidores de retorno personalizados, porque todavía no se utilizan ampliamente. Si desea escribir su propio convertidor de retorno, lea Tools/clinic/clinic.py, específicamente la implementación de CReturnConverter y todas sus subclases.

METH_O y METH_NOARGS

Para convertir una función usando METH_O, asegúrese de que el único argumento de la función esté usando el convertidor de object y marque los argumentos como solo posicional:

/*[clinic input]
meth_o_sample

     argument: object
     /
[clinic start generated code]*/

Para convertir una función usando METH_NOARGS, simplemente no especifique ningún argumento.

Aún puede usar un autoconversor, un convertidor de retorno y especificar un argumento de tipo para el convertidor de objetos para METH_O.

funciones tp_new y tp_init

Puede convertir las funciones tp_new y tp_init. Simplemente nómbrelas __new__ o __init__ según corresponda. Notas:

El nombre de la función generado para __new__ no termina en __new__ como lo haría por defecto. Es solo el nombre de la clase, convertido en un identificador C válido.

No se genera ningún PyMethodDef #define para estas funciones.

funciones __init__ retornan int, no PyObject *.

Utilice docstring como la clase de documentación.

Aunque las funciones __new__ `` y ``__init__ siempre deben aceptar tanto los objetos args como los kwargs, al realizar la conversión puede especificar cualquier firma para estas funciones que desee. (Si su función no admite palabras clave, la función de análisis generada generará una excepción si recibe alguna).

Cambiar y redirigir la salida de Clinic

Puede ser inconveniente tener la salida de Clinic intercalada con su código C convencional editado a mano. Afortunadamente, Clinic es configurable: puede almacenar en búfer su salida para imprimir más tarde (¡o antes!), O escribir su salida en un archivo separado. También puede agregar un prefijo o sufijo a cada línea del resultado generado por Clinic.

Si bien cambiar la salida de la Clínica de esta manera puede ser una bendición para la legibilidad, puede resultar en que el código de la Clínica utilice tipos antes de que se definan, o que su código intente utilizar el código generado por la Clínica antes de que se defina. Estos problemas pueden resolverse fácilmente reorganizando las declaraciones en su archivo o moviendo el código generado por Clinic a donde va. (Esta es la razón por la que el comportamiento predeterminado de Clinic es enviar todo al bloque actual; aunque muchas personas consideran que esto dificulta la legibilidad, nunca será necesario reorganizar su código para solucionar problemas de definición antes de su uso).

Comencemos por definir alguna terminología:

field

Un campo, en este contexto, es una subsección del resultado de la Clínica. Por ejemplo, el #define para la estructura PyMethodDef es un campo, llamado methoddef_define. La clínica tiene siete campos diferentes que puede generar por definición de función:

docstring_prototype
docstring_definition
methoddef_define
impl_prototype
parser_prototype
parser_definition
impl_definition

Todos los nombres tienen la forma "<a>_<b>", donde "<a>" es el objeto semántico representado (la función de análisis, la función impl, el docstring o la estructura methoddef) y "<b>" representa qué tipo de declaración es el campo. Los nombres de campo que terminan en "_prototype" representan declaraciones hacia adelante de esa cosa, sin el cuerpo/datos reales de la cosa; los nombres de campo que terminan en "_definition" representan la definición real de la cosa, con el cuerpo/datos de la cosa. ("methoddef" es especial, es el único que termina con "_define", lo que representa que es un preprocesador #define).

destination

Un destino es un lugar en el que la Clínica puede escribir resultados. Hay cinco destinos incorporados:

block

El destino predeterminado: impreso en la sección de salida del bloque Clínico actual.

buffer

Un búfer de texto donde puede guardar texto para más tarde. El texto enviado aquí se agrega al final de cualquier texto existente. Es un error dejar texto en el búfer cuando Clinic termina de procesar un archivo.

file

Un «archivo clínico» separado que Clinic creará automáticamente. El nombre de archivo elegido para el archivo es {basename}.clinic{extension}, donde a basename y extension se les asignó la salida de os.path.splitext() ejecutar en El archivo actual. (Ejemplo: el destino del file para _pickle.c se escribiría en _pickle.clinic.c.)

Importante: Al usar un destino **``file``, debe registrar el archivo generado!

two-pass

Un búfer como buffer. Sin embargo, un búfer de dos pasadas solo se puede volcar una vez, e imprime todo el texto que se le envía durante todo el procesamiento, incluso desde los bloques de la Clínica después del punto de descarga.

suppress

El texto se suprime — se tira.

Clinic define cinco nuevas directivas que le permiten reconfigurar su salida.

La primera nueva directiva es dump:

dump <destination>

Esto vuelca el contenido actual del destino nombrado en la salida del bloque actual y lo vacía. Esto solo funciona con destinos de búfer y de dos pasadas.

La segunda nueva directiva es output. La forma más básica de output es así:

output <field> <destination>

Esto le dice a la Clínica que envíe field a destination. output también admite un metadestino especial, llamado everything, que le dice a Clinic que envíe todos los campos a ese destination.

output tiene una serie de otras funciones:

output push
output pop
output preset <preset>

output push y output pop le permiten agregar y quitar configuraciones en una pila de configuración interna, para que pueda modificar temporalmente la configuración de salida, y luego restaurar fácilmente la configuración anterior. Simplemente presione antes de su cambio para guardar la configuración actual, luego haga estallar cuando desee restaurar la configuración anterior.

output preset configura la salida de Clinic en una de varias configuraciones preestablecidas incorporadas, de la siguiente manera:

block

Configuración inicial original de la clínica. Escribe todo inmediatamente después del bloque de entrada.

Suprime el parser_prototype y docstring_prototype, escribe todo lo demás en block.

file

Diseñado para escribir todo lo que pueda en el «archivo clínico». Luego, #include este archivo cerca de la parte superior de su archivo. Es posible que deba reorganizar su archivo para que esto funcione, aunque generalmente esto solo significa crear declaraciones hacia adelante para varias definiciones de typedef y PyTypeObject.

Suprima parser_prototype y docstring_prototype, escriba la impl_definition en block y escriba todo lo demás en file.

El nombre de archivo predeterminado es "{dirname}/clinic/{basename}.h".

buffer

Guarde la mayor parte del resultado de Clinic para escribirlo en su archivo cerca del final. Para los archivos Python que implementan módulos o tipos incorporado, se recomienda que descargue el búfer justo encima de las estructuras estáticas para su módulo o tipo incorporado; estos suelen estar muy cerca del final. El uso de buffer puede requerir incluso más edición que file, si su archivo tiene arreglos estáticos PyMethodDef definidos en el medio del archivo.

Suprima el parser_prototype, impl_prototype y docstring_prototype, escriba impl_definition en block y escriba todo lo demás en file.

two-pass

Similar al ajuste preestablecido de buffer, pero escribe declaraciones hacia adelante en el búfer de dos pasadas y definiciones en el buffer. Esto es similar al ajuste preestablecido de buffer, pero puede requerir menos edición que buffer. Vierta el búfer de dos pasadas cerca de la parte superior de su archivo y descargue el buffer cerca del final como lo haría cuando usa el ajuste preestablecido de buffer.

Suprime el impl_prototype, escribe impl_definition en block, escribe docstring_prototype, methoddef_define y parser_prototype en two-pass, escribe todo lo demás en buffer.

partial-buffer

Similar al ajuste preestablecido de buffer, pero escribe más cosas en block, solo escribe los trozos realmente grandes de código generado en buffer. Esto evita el problema de definición antes del uso de buffer por completo, con el pequeño costo de tener un poco más de material en la salida del bloque. Vierta el buffer cerca del final, tal como lo haría cuando usa el ajuste predeterminado de buffer.

Suprime el impl_prototype, escribe docstring_definition y parser_definition en buffer, escribe todo lo demás en block.

La tercera nueva directiva es destino:

destination <name> <command> [...]

Esto realiza una operación en el destino llamado name.

Hay dos subcomandos definidos: new y clear.

El subcomando new funciona así:

destination <name> new <type>

Esto crea un nuevo destino con el nombre <nombre> y escribe <tipo>.

Hay cinco tipos de destinos:

suppress

Tira el texto.

block

Escribe el texto en el bloque actual. Esto es lo que hizo Clinic originalmente.

buffer

Un búfer de texto simple, como el destino incorporado «búfer» anterior.

file

Un archivo de texto. El destino del archivo toma un argumento adicional, una plantilla para usar para construir el nombre de archivo, así:

destino <name> nuevo <type> <file_template>

La plantilla puede usar tres cadenas internamente que serán reemplazadas por bits del nombre del archivo:

{path}

La ruta completa al archivo, incluido el directorio y el nombre de archivo completo.

{dirname}

El nombre del directorio en el que se encuentra el archivo.

{basename}

Solo el nombre del archivo, sin incluir el directorio.

{basename_root}

Nombre de base con la extensión recortada (todo hasta pero sin incluir el último “.”).

{basename_extension}

El último “.” y todo lo que sigue. Si el nombre base no contiene un punto, esta será la cadena de caracteres vacía.

Si no hay puntos en el nombre del archivo, {basename} y {filename} son iguales, y {extension} está vacía. «{basename}{extension}» es siempre exactamente igual que «{filename}». «

two-pass

Un búfer de dos pasadas (two-pass), como el destino incorporado de «dos pasadas» anterior.

El subcomando clear funciona así:

destination <name> clear

Elimina todo el texto acumulado hasta este punto en el destino. (No sé para qué necesitarías esto, pero pensé que tal vez sería útil mientras alguien está experimentando).

La cuarta nueva directiva está set:

set line_prefix "string"
set line_suffix "string"

set le permite configurar dos variables internas en la Clínica. line_prefix es una cadena que se antepondrá a cada línea de salida de la Clínica; line_suffix es una cadena de caracteres que se agregará a cada línea de salida de la Clínica.

Ambos admiten dos cadenas de caracteres de formato:

{block comment start}

Se convierte en la cadena de caracteres /*, la secuencia de texto de inicio de comentario para archivos C.

{block comment end}

Se convierte en la cadena */, la secuencia de texto del comentario final para los archivos C.

La nueva directiva final es una que no debería necesitar usar directamente, llamada preserve:

preserve

Esto le dice a Clinic que el contenido actual de la salida debe mantenerse, sin modificaciones. La Clínica lo usa internamente cuando se descarga la salida en archivos de file; envolverlo en un bloque Clinic permite que Clinic use su funcionalidad de suma de comprobación existente para garantizar que el archivo no se modificó a mano antes de sobrescribirlo.

El truco #ifdef

Si está convirtiendo una función que no está disponible en todas las plataformas, hay un truco que puede usar para hacer la vida un poco más fácil. El código existente probablemente se ve así:

#ifdef HAVE_FUNCTIONNAME
static module_functionname(...)
{
...
}
#endif /* HAVE_FUNCTIONNAME */

Y luego, en la estructura PyMethodDef en la parte inferior, el código existente tendrá:

#ifdef HAVE_FUNCTIONNAME
{'functionname', ... },
#endif /* HAVE_FUNCTIONNAME */

En este escenario, debe encerrar el cuerpo de su función impl dentro de #ifdef, así:

#ifdef HAVE_FUNCTIONNAME
/*[clinic input]
module.functionname
...
[clinic start generated code]*/
static module_functionname(...)
{
...
}
#endif /* HAVE_FUNCTIONNAME */

Luego, elimine esas tres líneas de la estructura PyMethodDef, reemplazándolas con la macro Argument Clinic generada:

MODULE_FUNCTIONNAME_METHODDEF

(Puede encontrar el nombre real de esta macro dentro del código generado. O puede calcularlo usted mismo: es el nombre de su función tal como se define en la primera línea de su bloque, pero con puntos cambiados a guiones bajos, mayúsculas y "_METHODDEF" agregado al final.)

Quizás se esté preguntando: ¿qué pasa si HAVE_FUNCTIONNAME no está definido? ¡La macro MODULE_FUNCTIONNAME_METHODDEF tampoco se definirá!

Aquí es donde Argument Clinic se vuelve muy inteligente. De hecho, detecta que el bloqueo de Argument Clinic podría estar desactivado por el #ifdef. Cuando eso sucede, genera un pequeño código adicional que se ve así:

#ifndef MODULE_FUNCTIONNAME_METHODDEF
    #define MODULE_FUNCTIONNAME_METHODDEF
#endif /* !defined(MODULE_FUNCTIONNAME_METHODDEF) */

Eso significa que la macro siempre funciona. Si la función está definida, se convierte en la estructura correcta, incluida la coma al final. Si la función no está definida, esto se convierte en nada.

Sin embargo, esto causa un problema delicado: ¿dónde debería poner Argument Clinic este código adicional cuando se usa el ajuste preestablecido de salida «bloque»? No puede entrar en el bloque de salida, porque podría desactivarse con #ifdef. (¡Ese es todo el punto!)

En esta situación, Argument Clinic escribe el código adicional en el destino del «búfer». Esto puede significar que recibe una queja de Argument Clinic:

Warning in file "Modules/posixmodule.c" on line 12357:
Destination buffer 'buffer' not empty at end of file, emptying.

Cuando esto suceda, simplemente abra su archivo, busque el bloque dump buffer que Argument Clinic agregó a su archivo (estará en la parte inferior), luego muévalo arriba de la estructura PyMethodDef donde esa macro se utiliza.

Usando Argument Clinic en archivos Python

De hecho, es posible utilizar Argument Clinic para preprocesar archivos Python. Por supuesto, no tiene sentido usar bloques de Argument Clinic, ya que la salida no tendría ningún sentido para el intérprete de Python. ¡Pero usar Argument Clinic para ejecutar bloques de Python le permite usar Python como un preprocesador de Python!

Dado que los comentarios de Python son diferentes de los comentarios de C, los bloques de Argument Clinic incrustados en archivos de Python tienen un aspecto ligeramente diferente. Se ven así:

#/*[python input]
#print("def foo(): pass")
#[python start generated code]*/
def foo(): pass
#/*[python checksum:...]*/

Instrumentación de CPython con DTrace y SystemTap

autor

David Malcolm

autor

Łukasz Langa

DTrace y SystemTap son herramientas de monitoreo, cada una de las cuales proporciona una forma de inspeccionar lo que están haciendo los procesos en un sistema informático. Ambos usan lenguajes específicos de dominio que permiten al usuario escribir scripts que:

filtrar qué procesos deben observarse

recopilar datos de los procesos de interés

generar reportes sobre los datos

A partir de Python 3.6, CPython se puede construir con «marcadores» incrustados, también conocidos como «sondas», que se pueden observar mediante un script de DTrace o SystemTap, lo que facilita la supervisión de lo que hacen los procesos de CPython en un sistema.

CPython implementation detail: Los marcadores de DTrace son detalles de implementación del intérprete CPython. No se ofrecen garantías sobre la compatibilidad de la sonda entre versiones de CPython. Los scripts de DTrace pueden dejar de funcionar o funcionar incorrectamente sin previo aviso al cambiar las versiones de CPython.

Habilitando los marcadores estáticos

macOS viene con soporte integrado para DTrace. En Linux, para construir CPython con los marcadores incrustados para SystemTap, se deben instalar las herramientas de desarrollo de SystemTap.

En una máquina Linux, esto se puede hacer a través de:

$ yum install systemtap-sdt-devel

o:

$ sudo apt-get install systemtap-sdt-dev

Luego, CPython debe configurarse --with-dtrace:

checking for --with-dtrace... yes

En macOS, puede enumerar las sondas disponibles de DTrace ejecutando un proceso de Python en segundo plano y listando todas las sondas disponibles por el proveedor de Python:

$ python3.6 -q &
$ sudo dtrace -l -P python$!  # or: dtrace -l -m python3.6

   ID   PROVIDER            MODULE                          FUNCTION NAME
29564 python18035        python3.6          _PyEval_EvalFrameDefault function-entry
29565 python18035        python3.6             dtrace_function_entry function-entry
29566 python18035        python3.6          _PyEval_EvalFrameDefault function-return
29567 python18035        python3.6            dtrace_function_return function-return
29568 python18035        python3.6                           collect gc-done
29569 python18035        python3.6                           collect gc-start
29570 python18035        python3.6          _PyEval_EvalFrameDefault line
29571 python18035        python3.6                 maybe_dtrace_line line

En Linux, puede verificar si los marcadores estáticos SystemTap están presentes en el binario construido al ver si contiene una sección «.note.stapsdt».

$ readelf -S ./python | grep .note.stapsdt
[30] .note.stapsdt        NOTE         0000000000000000 00308d78

Si ha creado Python como una biblioteca compartida (con –enable-shared), debe buscar en la biblioteca compartida. Por ejemplo:

$ readelf -S libpython3.3dm.so.1.0 | grep .note.stapsdt
[29] .note.stapsdt        NOTE         0000000000000000 00365b68

Un lector de formato ELF suficientemente moderno puede imprimir los metadatos:

$ readelf -n ./python

Displaying notes found at file offset 0x00000254 with length 0x00000020:
    Owner                 Data size          Description
    GNU                  0x00000010          NT_GNU_ABI_TAG (ABI version tag)
        OS: Linux, ABI: 2.6.32

Displaying notes found at file offset 0x00000274 with length 0x00000024:
    Owner                 Data size          Description
    GNU                  0x00000014          NT_GNU_BUILD_ID (unique build ID bitstring)
        Build ID: df924a2b08a7e89f6e11251d4602022977af2670

Displaying notes found at file offset 0x002d6c30 with length 0x00000144:
    Owner                 Data size          Description
    stapsdt              0x00000031          NT_STAPSDT (SystemTap probe descriptors)
        Provider: python
        Name: gc__start
        Location: 0x00000000004371c3, Base: 0x0000000000630ce2, Semaphore: 0x00000000008d6bf6
        Arguments: -4@%ebx
    stapsdt              0x00000030          NT_STAPSDT (SystemTap probe descriptors)
        Provider: python
        Name: gc__done
        Location: 0x00000000004374e1, Base: 0x0000000000630ce2, Semaphore: 0x00000000008d6bf8
        Arguments: -8@%rax
    stapsdt              0x00000045          NT_STAPSDT (SystemTap probe descriptors)
        Provider: python
        Name: function__entry
        Location: 0x000000000053db6c, Base: 0x0000000000630ce2, Semaphore: 0x00000000008d6be8
        Arguments: 8@%rbp 8@%r12 -4@%eax
    stapsdt              0x00000046          NT_STAPSDT (SystemTap probe descriptors)
        Provider: python
        Name: function__return
        Location: 0x000000000053dba8, Base: 0x0000000000630ce2, Semaphore: 0x00000000008d6bea
        Arguments: 8@%rbp 8@%r12 -4@%eax

Los metadatos anteriores contienen información para SystemTap que describe cómo puede parchear instrucciones de código de máquina ubicadas estratégicamente para habilitar los hooks de rastreo utilizados por un script de SystemTap.

Sondas estáticas DTrace

El siguiente ejemplo de script DTrace se puede utilizar para mostrar la jerarquía de llamada/retorno de un script de Python, solo rastreando dentro de la invocación de una función llamada «start». En otras palabras, las llamadas a funciones durante la importación aparecerán en la lista:

self int indent;

python$target:::function-entry
/copyinstr(arg1) == "start"/
{
        self->trace = 1;
}

python$target:::function-entry
/self->trace/
{
        printf("%d\t%*s:", timestamp, 15, probename);
        printf("%*s", self->indent, "");
        printf("%s:%s:%d\n", basename(copyinstr(arg0)), copyinstr(arg1), arg2);
        self->indent++;
}

python$target:::function-return
/self->trace/
{
        self->indent--;
        printf("%d\t%*s:", timestamp, 15, probename);
        printf("%*s", self->indent, "");
        printf("%s:%s:%d\n", basename(copyinstr(arg0)), copyinstr(arg1), arg2);
}

python$target:::function-return
/copyinstr(arg1) == "start"/
{
        self->trace = 0;
}

Se puede invocar así:

$ sudo dtrace -q -s call_stack.d -c "python3.6 script.py"

La salida se verá así:

156641360502280  function-entry:call_stack.py:start:23
156641360518804  function-entry: call_stack.py:function_1:1
156641360532797  function-entry:  call_stack.py:function_3:9
156641360546807 function-return:  call_stack.py:function_3:10
156641360563367 function-return: call_stack.py:function_1:2
156641360578365  function-entry: call_stack.py:function_2:5
156641360591757  function-entry:  call_stack.py:function_1:1
156641360605556  function-entry:   call_stack.py:function_3:9
156641360617482 function-return:   call_stack.py:function_3:10
156641360629814 function-return:  call_stack.py:function_1:2
156641360642285 function-return: call_stack.py:function_2:6
156641360656770  function-entry: call_stack.py:function_3:9
156641360669707 function-return: call_stack.py:function_3:10
156641360687853  function-entry: call_stack.py:function_4:13
156641360700719 function-return: call_stack.py:function_4:14
156641360719640  function-entry: call_stack.py:function_5:18
156641360732567 function-return: call_stack.py:function_5:21
156641360747370 function-return:call_stack.py:start:28

Marcadores estáticos SystemTap

La forma de bajo nivel para utilizar la integración de SystemTap es utilizar los marcadores estáticos directamente. Esto requiere que indique explícitamente el archivo binario que los contiene.

Por ejemplo, este script SystemTap se puede utilizar para mostrar la jerarquía de llamada/retorno de un script de Python:

probe process("python").mark("function__entry") {
     filename = user_string($arg1);
     funcname = user_string($arg2);
     lineno = $arg3;

     printf("%s => %s in %s:%d\\n",
            thread_indent(1), funcname, filename, lineno);
}

probe process("python").mark("function__return") {
    filename = user_string($arg1);
    funcname = user_string($arg2);
    lineno = $arg3;

    printf("%s <= %s in %s:%d\\n",
           thread_indent(-1), funcname, filename, lineno);
}

Se puede invocar así:

$ stap \
  show-call-hierarchy.stp \
  -c "./python test.py"

La salida se verá así:

11408 python(8274):        => __contains__ in Lib/_abcoll.py:362
11414 python(8274):         => __getitem__ in Lib/os.py:425
11418 python(8274):          => encode in Lib/os.py:490
11424 python(8274):          <= encode in Lib/os.py:493
11428 python(8274):         <= __getitem__ in Lib/os.py:426
11433 python(8274):        <= __contains__ in Lib/_abcoll.py:366

donde las columnas son:

tiempo en microsegundos desde el inicio del script

nombre del ejecutable

PID de proceso

y el resto indica la jerarquía de llamada/retorno a medida que se ejecuta el script.

Para una compilación –enable-shared de CPython, los marcadores están contenidos dentro de la biblioteca compartida libpython, y la ruta de puntos de la sonda debe reflejar esto. Por ejemplo, esta línea del ejemplo anterior:

probe process("python").mark("function__entry") {

en su lugar debería leer:

probe process("python").library("libpython3.6dm.so.1.0").mark("function__entry") {

(asumiendo una compilación de depuración de CPython 3.6)

Marcadores estáticos disponibles

function__entry(str filename, str funcname, int lineno)

Este marcador indica que ha comenzado la ejecución de una función de Python. Solo se activa para funciones de Python puro (código de bytes).

El nombre del archivo, el nombre de la función y el número de línea se devuelven al script de rastreo como argumentos posicionales, a los que se debe acceder usando $arg1, $arg2, $arg3:

$arg1 : (const char *) nombre del archivo, accesible usando user_string($arg1)

$arg2 : (const char *) nombre de la función, accesible usando user_string($arg2)

$arg3 : int número de linea

function__return(str filename, str funcname, int lineno)

Este marcador es el inverso de function__entry(), e indica que la ejecución de una función de Python ha finalizado (ya sea mediante return o vía una excepción). Solo se activa para funciones de Python puro (código de bytes).

Los argumentos son los mismos que para function__entry()

line(str filename, str funcname, int lineno)

Este marcador indica que una línea de Python está a punto de ejecutarse. Es el equivalente al rastreo línea por línea con un generador de perfiles de Python. No se activa con las funciones de C.

Los argumentos son los mismos que para function__entry().

gc__start(int generation)

Se activa cuando el intérprete de Python inicia un ciclo de recolección de basura. arg0 es la generación a escanear, como gc.collect().

gc__done(long collected)

Se activa cuando el intérprete de Python finaliza un ciclo de recolección de basura. arg0 es el número de objetos recopilados.

import__find__load__start(str modulename)

Se activa antes importlib e intenta encontrar y cargar el módulo. arg0 es el nombre del módulo.

Nuevo en la versión 3.7.

import__find__load__done(str modulename, int found)

Se activa después de que la función find_and_load de importlib es llamada. arg0 es el nombre del módulo, arg1 indica si el módulo se cargó correctamente.

Nuevo en la versión 3.7.

audit(str event, void *tuple)

Se activa cuando se llama sys.audit() o PySys_Audit(). arg0 es el nombre del evento como cadena C, arg1 es un puntero PyObject a un objeto tupla.

Nuevo en la versión 3.8.

SystemTap Tapsets

La forma de nivel superior de utilizar la integración de SystemTap es utilizar un «tapset»: el equivalente de SystemTap a una biblioteca, que oculta algunos de los detalles de bajo nivel de los marcadores estáticos.

A continuación un archivo de tapset, basado en una compilación no compartida de CPython:

/*
   Provide a higher-level wrapping around the function__entry and
   function__return markers:
 \*/
probe python.function.entry = process("python").mark("function__entry")
{
    filename = user_string($arg1);
    funcname = user_string($arg2);
    lineno = $arg3;
    frameptr = $arg4
}
probe python.function.return = process("python").mark("function__return")
{
    filename = user_string($arg1);
    funcname = user_string($arg2);
    lineno = $arg3;
    frameptr = $arg4
}

Si este archivo está instalado en el directorio de tapset de SystemTap (por ejemplo, /usr/share/systemtap/tapset), estos puntos de sonda adicionales estarán disponibles:

python.function.entry(str filename, str funcname, int lineno, frameptr)

Este punto de sonda indica que ha comenzado la ejecución de una función de Python. Solo se activa para funciones de Python puro (código de bytes).

python.function.return(str filename, str funcname, int lineno, frameptr)

Este punto de prueba es el inverso de python.function.return, e indica que la ejecución de una función de Python ha finalizado (ya sea mediante return o mediante una excepción). Solo se activa para funciones de Python puro (código de bytes).

Ejemplos

Este script de SystemTap utiliza el tapset anterior para implementar de manera más limpia el ejemplo de rastrear la jerarquía de llamadas a funciones de Python, sin necesidad de nombrar directamente los marcadores estáticos:

probe python.function.entry
{
  printf("%s => %s in %s:%d\n",
         thread_indent(1), funcname, filename, lineno);
}

probe python.function.return
{
  printf("%s <= %s in %s:%d\n",
         thread_indent(-1), funcname, filename, lineno);
}

El siguiente script utiliza el tapset de arriba para proporcionar una vista superior de todo el código CPython en ejecución, mostrando los 20 marcos de código de bytes que se ingresan con más frecuencia, cada segundo, en todo el sistema:

global fn_calls;

probe python.function.entry
{
    fn_calls[pid(), filename, funcname, lineno] += 1;
}

probe timer.ms(1000) {
    printf("\033[2J\033[1;1H") /* clear screen \*/
    printf("%6s %80s %6s %30s %6s\n",
           "PID", "FILENAME", "LINE", "FUNCTION", "CALLS")
    foreach ([pid, filename, funcname, lineno] in fn_calls- limit 20) {
        printf("%6d %80s %6d %30s %6d\n",
            pid, filename, lineno, funcname,
            fn_calls[pid, filename, funcname, lineno]);
    }
    delete fn_calls;
}

Preguntas más frecuentes de Python

Preguntas frecuentes generales sobre Python

Preguntas frecuentes de programación

Preguntas frecuentes sobre diseño e historia

Preguntas frecuentes sobre bibliotecas y extensiones

Extendiendo/Embebiendo FAQ

Preguntas frecuentes sobre Python en Windows

Preguntas frecuentes sobre la Interfaz Gráfica de Usuario (GUI)

«¿Por qué está Python instalado en mi ordenador?» FAQ

Preguntas frecuentes generales sobre Python

Contenido

Preguntas frecuentes generales sobre Python

Información General

¿Qué es Python?

¿Que es la Python Software Foundation?

¿Hay restricciones de copyright sobre el uso de Python?

¿Por qué motivos se creó Python?

¿Para qué es bueno Python?

¿Cómo funciona el esquema numérico de versiones de Python?

¿Cómo obtengo una copia del código fuente de Python?

¿Cómo consigo documentación sobre Python?

Nunca he programado antes. ¿Hay un tutorial de Python?

¿Hay un newsgroup o una lista de correo dedicada a Python?

¿Cómo obtengo una versión de prueba beta de Python?

¿Cómo envío un reporte de bug y parches para Python?

¿Hay algún artículo publicado sobre Python que pueda referir?

¿Hay libros sobre Python?

¿En qué parte del mundo está ubicado www.python.org?

¿Por qué se llama Python?

¿Debe gustarme «Monty Python’s Flying Circus»?

Python en el mundo real

¿Cuán estable es Python?

¿Cuánta gente usa Python?

¿Hay proyectos significativos hechos con Python?

¿Qué nuevos desarrollos se esperan para Python en el futuro?

¿Es razonable proponer cambios incompatibles a Python?

¿Python es un buen lenguaje para principiantes?

Información General

¿Qué es Python?

Python es un lenguaje interpretado, interactivo y orientado a objetos. Incorpora módulos, excepciones, tipado dinámico, tipos de datos de muy alto nivel y clases. Python combina un poder destacado con una sintaxis muy clara. Tiene interfaces a muchas llamadas de sistema y bibliotecas, así como a varios sistemas de ventana, y es extensible en C o C++. También es usable como un lenguaje de extensión para aplicaciones que necesitan una interfaz programable. Por último, Python es portable: corre en muchas variantes de Unix, en Mac y en Windows 2000 y posteriores.

Para saber más, comienza con Tutorial de Python. La Beginner’s Guide to Python [https://wiki.python.org/moin/BeginnersGuide] vincula a otros recursos y tutoriales introductorios para aprender Python.

¿Que es la Python Software Foundation?

La Python Software Foundation es una organización independiente sin fines de lucro que posee los derechos sobre Python desde la versión 2.1 en adelante. La misión de la PSF es hacer avanzar la tecnología open source relacionada al lenguaje de programación Python y publicitar su uso. El sitio web de la PSF es https://www.python.org/psf/.

Las donaciones a la PSF están exentas de impuestos en Estados Unidos. Si usas Python y lo encuentras útil, por favor contribuye a través de la página de donaciones de la PSF [https://www.python.org/psf/donations/].

¿Hay restricciones de copyright sobre el uso de Python?

Puedes hacer cualquier cosa que quieras con el código fuente mientras mantengas y muestres los mensajes de derechos de autor en cualquier documentación sobre Python que produzcas. Si respetas las reglas de derechos de autor, está permitido usar Python para fines comerciales, vender copias de Python en forma de código fuente o binarios (modificados o no), o vender productos que incorporen Python de alguna manera. De cualquier manera nos gustaría saber de todos los usos comerciales de Python, por supuesto.

Mira la página PSF license [https://www.python.org/psf/license/] para encontrar explicaciones más detalladas y un vínculo al texto completo de la licencia.

El logo de Python tiene derechos comerciales (trademarked) y en ciertos casos se requiere un permiso de uso. Consulta la Trademark Usage Policy [https://www.python.org/psf/trademarks/] para más información.

¿Por qué motivos se creó Python?

Aquí hay un muy breve resumen sobre qué fue lo que comenzó todo, escrita por Guido van Rossum:

Tenía vasta experiencia implementando un lenguaje interpretado en el grupo ABC en CWI y trabajando con este grupo había aprendido mucho sobre diseño de lenguajes. Este es el origen de muchas características de Python, incluyendo el uso de sangría para el agrupamiento de sentencias y la inclusión de tipos de datos de muy alto nivel (aunque los detalles son todos diferentes en Python).

Tenía algunos resquemores sobre el lenguaje ABC pero también me gustaban muchas de sus características. Era imposible extenderlo (al lenguaje o sus implementaciones) para remediar mis quejas – de hecho, la ausencia de extensibilidad fue uno de los mayores problemas. Contaba con alguna experiencia usando Modula-2+ y conversé con los diseñadores de Modula-3 y leí su reporte. Modula-3 es el origen de la sintaxis y semántica que usé para las excepciones y otras características de Python.

Estaba trabajando en Grupo del sistema operativo distribuido Amoeba en CWI. Necesitábamos una mejor manera de hacer administración de sistemas que escribir programas en C o scripts de Bourne shell, ya que Amoeba tenía sus propia interfaz de llamadas a sistema que no era fácilmente accesible desde Bourne shell. Mi experiencia con el manejo de errores de Amoeba me hizo muy consciente de la importancia de las excepciones como una característica de los lenguaje de programación.

Se me ocurrió que un lenguaje de scripts con una sintaxis como ABC pero con acceso a las llamadas al sistema Amoeba satisfaría la necesidad. Me di cuenta de que sería una tontería escribir un lenguaje específico para Amoeba, así que decidí que necesitaba un lenguaje que fuera generalmente extensible.

Durante las vacaciones de Navidad de 1989 tenía mucho tiempo libre, así que decidí hacer un intento. Durante el año siguiente, mientras seguía trabajando principalmente en él durante mi propio tiempo, Python se utilizó en el proyecto Amoeba con un éxito creciente, y los comentarios de mis colegas me hicieron agregar muchas mejoras iniciales.

En febrero de 1991, justo después de un año de desarrollo, decidí publicarlo en USENET. El resto está en el archivo Misc/HISTORY.

¿Para qué es bueno Python?

Python es un lenguaje de programación de propósito general de alto nivel que se puede aplicar a muchas clases diferentes de problemas.

El lenguaje viene con una vasta biblioteca estándar que cubre áreas como el procesamiento de texto (expresiones regulares, Unicode, cálculo de diferencias entre archivos), protocolos de Internet (HTTP, FTP, SMTP, XML-RPC, POP, IMAP, programación CGI), ingeniería de software (pruebas unitarias, logging, perfilamiento, análisis sintáctico y gramatical de código Python) e interfaces con el sistema operativo (llamadas a sistema, sistemas de archivo, sockets TCP/IP). Mira la tabla de contenidos en La Biblioteca Estándar de Python para tener una idea de qué está disponible. Una amplia variedad de extensiones de terceros también están disponibles. Consulta el Python Package Index [https://pypi.org] para encontrar paquetes de tu interés.

¿Cómo funciona el esquema numérico de versiones de Python?

La versiones de Python están numeradas A.B.C o A.B. A es el numero de versión más importante – sólo es incrementado por cambios realmente grandes en el lenguaje. B es el número de versión secundario (o menor), incrementado ante cambios menos traumáticos. C es el nivel micro – se incrementa en cada lanzamiento de corrección de errores. Mira el PEP 6 [https://www.python.org/dev/peps/pep-0006] para más información sobre los lanzamientos de corrección de errores.

No todos los lanzamientos son de corrección de errores. En el período previo a un lanzamiento importante, una serie de lanzamientos de desarrollo son realizados, denotados como alpha, beta o release candidate. Las versiones alphas son lanzamientos tempranos en los que las interfaces no están todavía finalizadas; no es inesperado que una interfaz cambie entre dos lanzamientos alpha. Las betas son más estables, preservando las interfaces existentes pero posiblemente agregando nuevos módulos. Los release candidates están congelados, sin hacer cambios excepto los necesarios para corregir bugs críticos.

Las versiones alpha, beta y candidata de lanzamiento (release candidate) tienen un sufijo adicional. El sufijo para la versión alpha es «aN» para algunos números N pequeños; el sufijo para beta es «bN» para algunos números N pequeños, y el sufijo para release candidates es «cN» para algunos números N pequeños. En otras palabras, todas las versiones etiquetadas 2.0aN preceden a las 2.0bN, que preceden a las etiquetadas 2.0cN, y todas esas preceden a la 2.0.

También puedes encontrar números de versión con un sufijo «+», por ejemplo «2.2+». Estas son versiones sin lanzar, construidas directamente desde el repositorio de desarrollo de CPython. En la práctica, luego de que un lanzamiento menor se realiza, la versión es incrementada a la siguiente versión menor, que se vuelve «a0», por ejemplo «2.4a0».

Mira también la documentación para sys.version, sys.hexversion, y sys.version_info.

¿Cómo obtengo una copia del código fuente de Python?

El código fuente de la versión más reciente de Python está siempre disponible desde python.org, en https://www.python.org/downloads/. El código fuente en desarrollo más reciente se puede obtener en https://github.com/python/cpython/.

La distribución de fuentes es un archivo tar comprimido con gzip que contiene el código C completo, documentación en formato Sphinx, los módulos de la biblioteca de Python, programas de ejemplo y varias piezas útiles de software libremente distribuibles. El código fuente compilará y se ejecutará sin problemas en la mayoría de las plataformas Unix.

Consulta Getting Started section of the Python Developer’s Guide [https://devguide.python.org/setup/] para más información sobre cómo obtener el código fuente y compilarlo.

¿Cómo consigo documentación sobre Python?

La documentación estándar para la versión estable actual de Python está disponible en https://docs.python.org/3/. También están disponibles versiones en PDF, texto plano y HTML descargable en https://docs.python.org/3/download.html.

La documentación está escrita en reStructuredText y procesada con la herramienta de documentación Sphinx [http://sphinx-doc.org/]. Las fuentes reStructuredText de la documentación son parte de la distribución fuente de Python.

Nunca he programado antes. ¿Hay un tutorial de Python?

Hay numerosos tutoriales y libros disponibles. La documentación estándar incluye Tutorial de Python.

Consulta the Beginner’s Guide [https://wiki.python.org/moin/BeginnersGuide] para encontrar información para principiantes en Python, incluyendo una lista de tutoriales.

¿Hay un newsgroup o una lista de correo dedicada a Python?

Hay un grupo de noticias, comp.lang.python, y una lista de correo, python-list [https://mail.python.org/mailman/listinfo/python-list]. Tanto el grupo de noticias como la lista de correo están interconectadas entre sí – si puedes leer las noticias no es necesario que te suscribas a la lista de correo. comp.lang.python tiene mucho tráfico, recibiendo cientos de publicaciones cada día. y los lectores de Usenet suelen ser más capaces de hacer frente a este volumen.

Los anuncios de nuevos lanzamientos de software y eventos se pueden encontrar en comp.lang.python.announce, una lista moderada de bajo tráfico que recibe alrededor de cinco publicaciones por día. Está disponible como la lista de correos de anuncios de Python [https://mail.python.org/mailman/listinfo/python-announce-list].

Más información sobre listas de correo o grupos de noticias puede hallarse en https://www.python.org/community/lists/.

¿Cómo obtengo una versión de prueba beta de Python?

Las versiones alpha y beta están disponibles desde https://www.python.org/downloads/. Todos los lanzamientos son anunciados en el grupo de noticias comp.lang.python y comp.lang.python.announce, así como también en la página principal de Python en https://www.python.org/; un feed RSS está disponible.

También puedes acceder a la versión en desarrollo de Python desde Git. Mira The Python Developer’s Guide [https://devguide.python.org/] para los detalles.

¿Cómo envío un reporte de bug y parches para Python?

Para reportar un bug o enviar un parche, por favor usa la instalación de Roundup en https://bugs.python.org/.

Debes tener una cuenta de Roundup para reportar bugs; esto nos permite contactarte si tenemos más preguntas. También permite que Roundup te envíe actualizaciones cuando haya actualizaciones sobre tu bug. Si previamente usaste SourceForge para reportar bugs a Python, puedes obtener tu contraseña de Roundup a través del procedimiento de reinicio de contraseña de Roundup [https://bugs.python.org/user?@template=forgotten].

Para más información sobre cómo se desarrolla Python, consulta the Python Developer’s Guide [https://devguide.python.org/].

¿Hay algún artículo publicado sobre Python que pueda referir?

Lo más probable es que lo mejor sea citar a tu libro preferido sobre Python.

El primer artículo publicado sobre Python fue escrito en 1991 y quedó bastante desactualizado.

Guido van Rossum y Jelke de Boer, «Interactively Testing Remote Servers Using the Python Programming Language», CWI Quarterly, Volume 4, Issue 4 (Diembre de 1991), Amsterdam, pp 283–303.

¿Hay libros sobre Python?

Sí, hay muchos, y hay más siendo publicados. Mira la wiki de python.org en https://wiki.python.org/moin/PythonBooks para ver una lista.

También puedes buscar «Python» en las librerías en línea y excluir las que refieran a los Monty Python; o quizás buscar «Python» y «lenguaje».

¿En qué parte del mundo está ubicado www.python.org?

La infraestructura del proyecto Python está ubicada alrededor de todo el mundo y es gestionada por el Python Infraestructure Team. Detalles aquí [http://infra.psf.io].

¿Por qué se llama Python?

Cuando comenzó a implementar Python, Guido van Rossum también estaba leyendo los guiones publicados de «Monty Python’s Flying Circus» [https://es.wikipedia.org/wiki/Monty_Python], una serie de comedia producida por la BBC de los 70”. Van Rossum pensó que necesitaba un nombre que fuera corto, único y ligeramente misterioso, entonces decidió llamar al lenguaje Python.

¿Debe gustarme «Monty Python’s Flying Circus»?

No, pero ayuda. :)

Python en el mundo real

¿Cuán estable es Python?

Muy estable. Versiones nuevas y estables han sido publicadas cada entre 6 y 18 meses desde 1991, y es muy probable que así continúe. Actualmente pasan alrededor de 18 meses entre los lanzamientos importantes.

Los desarrolladores publican lanzamientos de «bugfix» (corrección de errores) para versiones antiguas, así que la estabilidad de las versiones existentes mejora gradualmente. Los lanzamientos de corrección de errores, indicados por el tercer componente del número de versión (e.g 3.5.3, 3.6.2) son gestionados para estabilidad; sólo correcciones de problemas conocidos se incluyen en uno de estos lanzamientos, y está garantizado que las interfaces se mantendrán a lo largo de la misma serie.

La última versión estable siempre se puede encontrar en la página Python download page [https://www.python.org/downloads/]. Hay dos versiones de Python que están listas para producción: la 3.x y la 2.x. La versión recomendada es la 3.x, que es soportada por la mayoría de las bibliotecas más usadas. Aunque la versión 2.x aún se usa, no es mantenida desde el 1º de enero de 2020 [https://www.python.org/dev/peps/pep-0373/].

¿Cuánta gente usa Python?

Probablemente hay decenas de miles de usuarios y usuarias, aunque es difícil obtener una cuenta exacta.

Python está disponible gratuitamente para ser descargado por lo que no existen cifras de ventas, a su vez se incluye en muchos sitios diferentes y está empaquetado en muchas distribuciones de Linux, por lo que las estadísticas de descarga tampoco cuentan toda la historia.

El grupo de noticias comp.lang.python es muy activo, pero no todos los usuarios de Python publican allí o incluso lo leen.

¿Hay proyectos significativos hechos con Python?

Mira https://www.python.org/about/success para una lista de proyecto que usan Python. Consultar las actas de conferencias de Python pasadas [https://www.python.org/community/workshops/] revelará contribuciones de diferentes empresas y organizaciones.

Proyectos en Python de alto perfil incluyen el gestor de listas de correo Mailman [http://www.list.org] y el servidor de aplicaciones Zope [http://www.zope.org]. Muchas distribuciones de Linux, más notoriamente Red Hat [https://www.redhat.com], han escrito partes de sus instaladores y software de administración en Python. Entre las empresas que usan Python internamente se encuentran Google, Yahoo y Lucasfilm Ltd.

¿Qué nuevos desarrollos se esperan para Python en el futuro?

Mira https://www.python.org/dev/peps/ para las Python Enhancement Proposals («Propuestas de mejora de Python», PEPs). Las PEPs son documentos de diseño que describen una nueva funcionalidad sugerida para Python, proveyendo una especificación técnica concisa y una razón fundamental. Busca una PEP titulada «Python X.Y Release Schedule», donde X.Y es una versión que aún no ha sido publicada.

Los nuevos desarrollos son discutidos en la lista de correo python-dev [https://mail.python.org/mailman/listinfo/python-dev/].

¿Es razonable proponer cambios incompatibles a Python?

En general no. Ya existen millones de líneas de código Python alrededor del mundo, por lo que cualquier cambio en el lenguaje que invalide más que una fracción muy pequeña de los programas existentes tiene que ser mal visto. Incluso si puedes proporcionar un programa de conversión, todavía existe el problema de actualizar toda la documentación; se han escrito muchos libros sobre Python y no queremos invalidarlos a todos de un plumazo.

Si una funcionalidad se debe cambiar, es necesario proporcionar una ruta de actualización gradual. PEP 5 [https://www.python.org/dev/peps/pep-0005] describe el procedimiento seguido para introducir cambios incompatibles con versiones anteriores para minimizar disrupciones a los usuarios y usuarias.

¿Python es un buen lenguaje para principiantes?

Sí.

Todavía es común hacer comenzar a estudiantes con lenguajes procedimentales de tipado estático como Pascal, C o un subconjunto de C++ o Java. Los y las estudiantes pueden verse favorecidos si aprenden Python como primer lenguaje. Python tiene una sintaxis simple y consistente y una gran biblioteca estándar. Y, más importante, usar Python en cursos introductorios de programación permite a los estudiantes concentrarse en lo importante de las habilidades de programación como la descomposición de problemas y el diseño de tipos de datos. Con Python los estudiantes pueden ser rápidamente introducidos a conceptos como bucles y procedimientos. Incluso puede trabajar con objetos definidos por el usuario en su primer curso.

Para estudiantes que nunca han programado antes, usar un lenguaje de tipado estático parece antinatural. Presenta complejidades adicionales que deben ser dominadas y ralentizan el ritmo del curso. Quienes están aprendiendo intentan pensar como la computadora, descomponer problemas, diseñar interfaces consistentes y encapsular datos. Si bien aprender a usar un lenguaje de tipado estático es importante en el largo plazo, no es necesariamente el mejor tema a tratar en un primer curso de programación.

Muchos otros aspectos de Python lo vuelven un buen primer lenguaje. Como Java, Python tiene una biblioteca estándar, de manera que los y las estudiantes pueden recibir, de manera temprana, consignas para realizar proyectos de programación que hagan algo. Estas consignas no están restringidas a las típicas calculadoras de cuatro operaciones o programas de balances contables. Al usar la biblioteca estándar, pueden ganar la satisfacción de trabajar en aplicaciones realistas mientras aprenden los fundamentos de la programación. Usar la biblioteca estándar también enseña a reusar código. Módulos de terceros, como PyGame, también ayudan a extender los alcances de los y las estudiantes.

El intérprete interactivo de Python les permite probar funcionalidades del lenguaje mientras programan. Pueden tener una ventana con el intérprete corriendo mientras escriben el código de su programa en otra. Si no recuerdan los métodos para una lista, pueden hacer algo así:

>>> L = []
>>> dir(L)
['__add__', '__class__', '__contains__', '__delattr__', '__delitem__',
'__dir__', '__doc__', '__eq__', '__format__', '__ge__',
'__getattribute__', '__getitem__', '__gt__', '__hash__', '__iadd__',
'__imul__', '__init__', '__iter__', '__le__', '__len__', '__lt__',
'__mul__', '__ne__', '__new__', '__reduce__', '__reduce_ex__',
'__repr__', '__reversed__', '__rmul__', '__setattr__', '__setitem__',
'__sizeof__', '__str__', '__subclasshook__', 'append', 'clear',
'copy', 'count', 'extend', 'index', 'insert', 'pop', 'remove',
'reverse', 'sort']
>>> [d for d in dir(L) if '__' not in d]
['append', 'clear', 'copy', 'count', 'extend', 'index', 'insert', 'pop', 'remove', 'reverse', 'sort']

>>> help(L.append)
Help on built-in function append:

append(...)
    L.append(object) -> None -- append object to end

>>> L.append(1)
>>> L
[1]

Con el intérprete, la documentación nunca está lejos de los o las estudiantes mientras están programando.

También hay buenas IDEs para Python. IDLE es una IDE multiplataforma para Python que está escrita en Python usando Tkinter. PythonWin es un IDE específico para Windows. Quienes usan Emacs estarán felices de saber que hay un modo para Python muy bueno. Todos estos entornos de programación proveen resaltado de sintaxis, auto-sangrado y acceso al intérprete interactivo mientras se programa. Consulta la wiki de Python [https://wiki.python.org/moin/PythonEditors] para ver una lista completa de entornos de programación.

Si quieres discutir el uso de Python en la educación, quizás te interese unirte a la la lista de correo edu-sig [https://www.python.org/community/sigs/current/edu-sig].

Preguntas frecuentes de programación

Contenido

Preguntas frecuentes de programación

Preguntas generales

¿Existe un depurador a nivel de código fuente con puntos de interrupción, depuración paso a paso, etc?

¿Existe alguna herramienta que ayude a encontrar errores o realizar análisis estático?

¿Cómo puedo crear un binario independiente a partir de un programa Python?

¿Existen estándares de código o una guía de estilo para programas Python?

Núcleo del lenguaje

¿Por qué obtengo un UnboundLocalError cuando la variable tiene un valor?

¿Cuáles son las reglas para las variables locales y globales en Python?

¿Por qué las funciones lambda definidas en un bucle con diferentes valores devuelven todas el mismo resultado?

¿Cómo puedo compartir variables globales entre módulos?

¿Cuáles son las «buenas prácticas» para usar import en un módulo?

¿Por qué los valores por defecto se comparten entre objetos?

¿Cómo puedo pasar parámetros por palabra clave u opcionales de una función a otra?

¿Cuál es la diferencia entre argumentos y parámetros?

¿Por qué cambiando la lista “y” cambia, también, la lista “x”?

¿Cómo puedo escribir una función sin parámetros (invocación mediante referencia)?

¿Cómo se puede hacer una función de orden superior en Python?

¿Cómo copio un objeto en Python?

¿Cómo puedo encontrar los métodos o atributos de un objeto?

¿Cómo puede mi código descubrir el nombre de un objeto?

¿Qué ocurre con la precedencia del operador coma?

¿Existe un equivalente al operador ternario de C «?:»?

¿Es posible escribir expresiones en una línea de forma ofuscada en Python?

¿Qué hace la barra (/) en medio de la lista de parámetros de una función?

Números y cadenas

¿Cómo puedo especificar enteros hexadecimales y octales?

¿Por qué -22 // 10 devuelve -3?

How do I get int literal attribute instead of SyntaxError?

¿Cómo convierto una cadena a un número?

¿Cómo puedo convertir un número a una cadena?

¿Cómo puedo modificar una cadena in situ?

¿Cómo puedo usar cadenas para invocar funciones/métodos?

¿Existe un equivalente a chomp() en Perl para eliminar nuevas líneas al final de las cadenas?

¿Existe un equivalente a scanf() o a sscanf() ?

¿Qué significa “UnicodeDecodeError” o “UnicodeEncodeError”?

Rendimiento

Mi programa es muy lento. ¿Cómo puedo acelerarlo?

¿Cuál es la forma más eficiente de concatenar muchas cadenas conjuntamente?

Secuencias (Tuplas/Listas)

¿Cómo convertir entre tuplas y listas?

¿Qué es un índice negativo?

¿Cómo puedo iterar sobre una secuencia en orden inverso?

¿Cómo eliminar duplicados de una lista?

Cómo eliminar duplicados de una lista

¿Cómo se puede hacer un array en Python?

¿Cómo puedo crear una lista multidimensional?

¿Cómo puedo aplicar un método a una secuencia de objetos?

¿Por qué hacer lo siguiente, a_tuple[i] += ['item'], lanza una excepción cuando la suma funciona?

Quiero hacer una ordenación compleja: ¿Puedes hacer una transformada Schwartziana (Schwartzian Transform) en Python?

¿Cómo puedo ordenar una lista a partir de valores de otra lista?

Objetos

¿Qué es una clase?

¿Qué es un método?

¿Qué es self?

¿Cómo puedo comprobar si un objeto es una instancia de una clase dada o de una subclase de la misma?

¿Qué es la delegación?

¿Cómo invoco a un método definido en una clase base desde una clase derivada que lo ha sobreescrito?

¿Cómo puedo organizar mi código para hacer que sea más sencillo modificar la clase base?

¿Cómo puedo crear datos estáticos de clase y métodos estáticos de clase?

¿Como puedo sobrecargar constructores (o métodos) en Python?

Intento usar __spam y obtengo un error sobre _SomeClassName__spam.

Mi clase define __del__ pero no se le invoca cuando borro el objeto.

¿Cómo puedo obtener una lista de todas las instancias de una clase dada?

¿Por qué el resultado de id() no parece ser único?

When can I rely on identity tests with the is operator?

How can a subclass control what data is stored in an immutable instance?

Módulos

¿Cómo creo un fichero .pyc?

¿Cómo puedo encontrar el nombre del módulo en uso?

¿Cómo podría tener módulos que se importan mutuamente entre ellos?

__import__(“x.y.z”) devuelve <module “x”>; ¿cómo puedo obtener z?

Cuando edito un módulo importado y lo reimporto los cambios no tienen efecto. ¿Por qué sucede esto?

Preguntas generales

¿Existe un depurador a nivel de código fuente con puntos de interrupción, depuración paso a paso, etc?

Sí.

Debajo se describen algunos depuradores para Python y la función integrada breakpoint() te permite ejecutar alguno de ellos.

El módulo pdb es en depurador en modo consola simple pero conveniente para Python. Es parte de la biblioteca estándar de Python y está documentado en el manual de referencia de la biblioteca. Puedes escribir tu propio depurador usando el código de pdb como ejemplo.

El entorno interactivo de desarrollo IDLE, el cual es parte de la distribución Python estándar (disponible, generalmente, como Tools/scripts/idle), incluye un depurador gráfico.

PythonWin is a Python IDE that includes a GUI debugger based on pdb. The PythonWin debugger colors breakpoints and has quite a few cool features such as debugging non-PythonWin programs. PythonWin is available as part of pywin32 [https://github.com/mhammond/pywin32] project and as a part of the ActivePython [https://www.activestate.com/products/python/] distribution.

Eric [http://eric-ide.python-projects.org/] es un IDE creado usando PyQt y el componente de edición Scintilla.

trepan3k [https://github.com/rocky/python3-trepan/] is a gdb-like debugger.

Visual Studio Code [https://code.visualstudio.com/] is an IDE with debugging tools that integrates with version-control software.

Existen varios IDEs comerciales para Python que incluyen depuradores gráficos. Entre ellos tenemos:

Wing IDE [https://wingware.com/]

Komodo IDE [https://www.activestate.com/products/komodo-ide/]

PyCharm [https://www.jetbrains.com/pycharm/]

¿Existe alguna herramienta que ayude a encontrar errores o realizar análisis estático?

Sí.

Pylint [https://www.pylint.org/] y Pyflakes [https://github.com/PyCQA/pyflakes] realizan comprobaciones básicas que le ayudarán a detectar errores antes.

Inspectores estáticos de tipos como Mypy [http://mypy-lang.org/], Pyre [https://pyre-check.org/], y Pytype [https://github.com/google/pytype] pueden hacer comprobaciones de las anotaciones de tipos en código fuente Python.

¿Cómo puedo crear un binario independiente a partir de un programa Python?

No necesitas tener la habilidad de compilar Python a código C si lo único que necesitas es un programa independiente que los usuarios puedan descargar y ejecutar sin necesidad de instalar primero una distribución Python. Existe una serie de herramientas que determinan el conjunto de módulos que necesita un programa y une estos módulos conjuntamente con un binario Python para generar un único ejecutable.

One is to use the freeze tool, which is included in the Python source tree as Tools/freeze. It converts Python byte code to C arrays; with a C compiler you can embed all your modules into a new program, which is then linked with the standard Python modules.

Funciona escaneando su fuente de forma recursiva en busca de declaraciones de importación (en ambas formas) y buscando los módulos en la ruta estándar de Python, así como en el directorio de la fuente (para los módulos incorporados). Luego convierte el bytecode de los módulos escritos en Python en código C (inicializadores de arrays que pueden ser convertidos en objetos de código usando el módulo marshal) y crea un archivo de configuración a medida que sólo contiene aquellos módulos incorporados que se usan realmente en el programa. A continuación, compila el código C generado y lo enlaza con el resto del intérprete de Python para formar un binario autónomo que actúa exactamente igual que su script.

The following packages can help with the creation of console and GUI executables:

Nuitka [https://nuitka.net/] (Cross-platform)

PyInstaller [http://www.pyinstaller.org/] (Cross-platform)

PyOxidizer [https://pyoxidizer.readthedocs.io/en/stable/] (Cross-platform)

cx_Freeze [https://marcelotduarte.github.io/cx_Freeze/] (Cross-platform)

py2app [https://github.com/ronaldoussoren/py2app] (macOS only)

py2exe [http://www.py2exe.org/] (Windows only)

¿Existen estándares de código o una guía de estilo para programas Python?

Sí. El estilo de código requerido para los módulos de la biblioteca estándar se encuentra documentado como PEP 8 [https://www.python.org/dev/peps/pep-0008].

Núcleo del lenguaje

¿Por qué obtengo un UnboundLocalError cuando la variable tiene un valor?

Puede ser una sorpresa el hecho de obtener un UnboundLocalError en código que había estado funcionando previamente cuando se modifica mediante el añadido de una declaración de asignación en alguna parte del cuerpo de una función.

Este código:

>>> x = 10
>>> def bar():
...     print(x)
>>> bar()
10

funciona, pero este código:

>>> x = 10
>>> def foo():
...     print(x)
...     x += 1

resulta en un UnboundLocalError:

>>> foo()
Traceback (most recent call last):
  ...
UnboundLocalError: local variable 'x' referenced before assignment

Esto es debido a que cuando realizas una asignación a una variable en un ámbito de aplicación, esa variable se convierte en local y enmascara cualquier variable llamada de forma similar en un ámbito de aplicación exterior. Desde la última declaración en foo asigna un nuevo valor a x, el compilador la reconoce como una variable local. Consecuentemente, cuando el print(x) más próximo intenta mostrar la variable local no inicializada se muestra un error.

En el ejemplo anterior puedes acceder al ámbito de aplicación exterior a la variable declarándola como global:

>>> x = 10
>>> def foobar():
...     global x
...     print(x)
...     x += 1
>>> foobar()
10

Esta declaración explícita es necesaria de cara a recordarte que (a diferencia de la situación superficialmente análoga con las variables de clase e instancia) estás modificando el valor de la variable en un ámbito de aplicación más externo:

>>> print(x)
11

Puedes hacer algo similar en un ámbito de aplicación anidado usando la palabra clave nonlocal:

>>> def foo():
...    x = 10
...    def bar():
...        nonlocal x
...        print(x)
...        x += 1
...    bar()
...    print(x)
>>> foo()
10
11

¿Cuáles son las reglas para las variables locales y globales en Python?

En Python, las variables que solo se encuentran referenciadas dentro de una función son globales implícitamente. Si a una variable se le asigna un valor en cualquier lugar dentro del cuerpo de una función, se asumirá que es local a no ser que explícitamente se la declare como global.

Aunque, inicialmente, puede parecer sorprendente, un momento de consideración permite explicar esto. Por una parte, requerir global para variables asignadas proporciona una barrera frente a efectos secundarios indeseados. Por otra parte, si global es requerido para todas las referencias globales, deberás usar global en todo momento. Deberías declarar como global cualquier referencia a una función integrada o a un componente de un módulo importado. Este embrollo arruinaría la utilidad de la declaración «global» para identificar los efectos secundarios.

¿Por qué las funciones lambda definidas en un bucle con diferentes valores devuelven todas el mismo resultado?

Considera que usas un bucle for para crear unas pocas funciones lambda (o, incluso, funciones normales), por ejemplo.:

>>> squares = []
>>> for x in range(5):
...     squares.append(lambda: x**2)

Lo siguiente proporciona una lista que contiene 5 funciones lambda que calculan x**2. Esperarías que, cuando se les invoca, retornaran, respectivamente, 0, 1, 4, 9``y ``16. Sin embargo, cuando lo ejecutes verás que todas devuelven 16:

>>> squares[2]()
16
>>> squares[4]()
16

Esto sucede porque x no es una función lambda local pero se encuentra definida en un ámbito de aplicación externo y se accede cuando la lambda es invocada — no cuando ha sido definida. Al final del bucle, el valor de x es 4, por tanto, ahora todas las funciones devuelven 4**2, i.e. 16. También puedes verificar esto mediante el cambio del valor de x y ver como los resultados de las lambdas cambian:

>>> x = 8
>>> squares[2]()
64

De cara a evitar esto necesitas guardar los valores en variables locales a las funciones lambda de tal forma que no dependan del valor de la x global:

>>> squares = []
>>> for x in range(5):
...     squares.append(lambda n=x: n**2)

Aquí, n=x crea una nueva variable n local a la función lambda y ejecutada cuando la función lambda se define de tal forma que tiene el mismo valor que tenía x en ese punto en el bucle. Esto significa que el valor de n será 0 en la primera función lambda, 1 en la segunda, 2 en la tercera y así sucesivamente. Por tanto, ahora cada lambda retornará el resultado correcto:

>>> squares[2]()
4
>>> squares[4]()
16

Es de destacar que este comportamiento no es peculiar de las funciones lambda sino que aplica también a las funciones regulares.

¿Cómo puedo compartir variables globales entre módulos?

La forma canónica de compartir información entre módulos dentro de un mismo programa sería creando un módulo especial (a menudo llamado config o cfg). Simplemente importa el módulo config en todos los módulos de tu aplicación; el módulo estará disponible como un nombre global. Debido a que solo hay una instancia de cada módulo, cualquier cambio hecho en el objeto módulo se reflejará en todos los sitios. Por ejemplo:

config.py:

x = 0   # Default value of the 'x' configuration setting

mod.py:

import config
config.x = 1

main.py:

import config
import mod
print(config.x)

Ten en cuenta que usar un módulo es también la base para la implementación del patrón de diseño Singleton, por la misma razón.

¿Cuáles son las «buenas prácticas» para usar import en un módulo?

En general, no uses from modulename import *. Haciendo eso embarulla el espacio de nombres del importador y hace que sea más difícil para los linters el detectar los nombres sin definir.

Importar los módulos en la parte inicial del fichero. Haciéndolo así deja claro los módulos que son necesarios para tu código y evita preguntas sobre si el nombre del módulo se encuentra en el ámbito de la aplicación. Usar una importación por línea hace que sea sencillo añadir y eliminar módulos importados pero usar múltiples importaciones por línea usa menos espacio de pantalla.

Es una buena práctica si importas los módulos en el orden siguiente:

módulos de la biblioteca estándar – por ejemplo, sys, os, getopt, re

módulos de bibliotecas de terceros (cualquier cosa instalada en el directorio site-packages de Python) – por ejemplo, mx.DateTime, ZODB, PIL.Image, etc.

módulos desarrollados localmente

Hay veces en que es necesario mover las importaciones a una función o clase para evitar problemas de importaciones circulares. Gordon McMillan dice:

No hay problema con las importaciones circulares cuando ambos módulos usan la forma de importación «import <module>». Fallará cuando el segundo módulo quiera coger un nombre del primer módulo («from module import name») y la importación se encuentre en el nivel superior. Esto sucede porque los nombres en el primero todavía no se encuentran disponibles debido a que el primer módulo se encuentra ocupado importando al segundo.

En este caso, si el segundo módulo se usa solamente desde una función, la importación se puede mover de forma sencilla dentro de la función. En el momento en que se invoca a la importación el primer módulo habrá terminado de inicializarse y el segundo módulo podrá hacer la importación.

También podría ser necesario mover importaciones fuera del nivel superior del código si alguno de loa módulos son específicos a la plataforma. En ese caso podría, incluso, no ser posible importar todos los módulos en la parte superior del fichero. Para esos casos, la importación correcta de los módulos en el código correspondiente específico de la plataforma es una buena opción.

Solo debes mover importaciones a un ámbito de aplicación local, como dentro de la definición de una función, si es necesario resolver problemas como una importación circular o al intentar reducir el tiempo de inicialización de un módulo. Esta técnica es especialmente útil si muchas de las importaciones no son necesarias dependiendo de cómo se ejecute el programa. También podrías mover importaciones a una función si los módulos solo se usan dentro de esa función. Nótese que la primera carga de un módulo puede ser costosa debido al tiempo necesario para la inicialización del módulo,pero la carga de un módulo múltiples veces está prácticamente libre de coste ya que solo es necesario hacer búsquedas en un diccionario. Incluso si el nombre del módulo ha salido del ámbito de aplicación el módulo se encuentre, probablemente, en sys.modules.

¿Por qué los valores por defecto se comparten entre objetos?

Este tipo de error golpea a menudo a programadores novatos. Considera esta función:

def foo(mydict={}):  # Danger: shared reference to one dict for all calls
    ... compute something ...
    mydict[key] = value
    return mydict

La primera vez que llamas a esta función, mydict solamente contiene un único elemento. La segunda vez, mydict contiene dos elementos debido a que cuando comienza la ejecución de foo(), mydict comienza conteniendo un elemento de partida.

A menudo se esperaría que una invocación a una función cree nuevos objetos para valores por defecto. Eso no es lo que realmente sucede. Los valores por defecto se crean exactamente una sola vez, cuando se define la función. Se se cambia el objeto, como el diccionario en este ejemplo, posteriores invocaciones a la función estarán referidas al objeto cambiado.

Por definición, los objetos inmutables como números, cadenas, tuplas y None están asegurados frente al cambio. Cambios en objetos mutables como diccionarios, listas e instancias de clase pueden llevar a confusión.

Debido a esta característica es una buena práctica de programación el no usar valores mutables como valores por defecto. En su lugar usa None como valor por defecto dentro de la función, comprueba si el parámetro es None y crea una nueva lista/un nuevo diccionario/cualquier otras cosa que necesites. Por ejemplo, no escribas:

def foo(mydict={}):
    ...

pero:

def foo(mydict=None):
    if mydict is None:
        mydict = {}  # create a new dict for local namespace

Esta característica puede ser útil. Cuando tienes una función que es muy costosa de ejecutar, una técnica común es cachear sus parámetros y el valor resultante de cada invocación a la función y retornar el valor cacheado si se solicita nuevamente el mismo valor. A esto se le llama «memoizing» y se puede implementar de la siguiente forma:

# Callers can only provide two parameters and optionally pass _cache by keyword
def expensive(arg1, arg2, *, _cache={}):
    if (arg1, arg2) in _cache:
        return _cache[(arg1, arg2)]

    # Calculate the value
    result = ... expensive computation ...
    _cache[(arg1, arg2)] = result           # Store result in the cache
    return result

Podrías usar una variable global conteniendo un diccionario en lugar de un valor por defecto; es una cuestión de gustos.

¿Cómo puedo pasar parámetros por palabra clave u opcionales de una función a otra?

Recopila los argumentos usando los especificadores * y ** en la lista de parámetros de la función; esto te proporciona los argumentos posicionales como una tupla y los argumentos con palabras clave como un diccionario. Puedes, entonces, pasar estos argumentos cuando invoques a otra función usando * y **:

def f(x, *args, **kwargs):
    ...
    kwargs['width'] = '14.3c'
    ...
    g(x, *args, **kwargs)

¿Cuál es la diferencia entre argumentos y parámetros?

Parámetros se definen mediante los nombres que aparecen en la definición de una función mientras que argumentos son los valores que se pasan a la función cuando la invocamos. Los Parámetros definen qué tipos de argumentos puede aceptar una función. por ejemplo, dada la definición de la función:

def func(foo, bar=None, **kwargs):
    pass

foo, bar y kwargs son parámetros de func. Sin embargo, cuando invocamos a func, por ejemplo:

func(42, bar=314, extra=somevar)

los valores 42, 314 y somevar son argumentos.

¿Por qué cambiando la lista “y” cambia, también, la lista “x”?

Si escribes código como:

>>> x = []
>>> y = x
>>> y.append(10)
>>> y
[10]
>>> x
[10]

te estarás preguntando porque añadir un elemento a y ha cambiado también a x.

Hay dos factores que provocan este resultado:

Las variables son simplemente nombres que referencian a objetos. Haciendo y = x no crea una copia de la lista – crea una nueva variable y que referencia al mismo objeto al que referencia x . Esto significa que solo existe un objeto (la lista) y tanto x como y hacen referencia al mismo.

Las listas son mutable, lo que significa que puedes cambiar su contenido.

Después de la invocación a append(), el contenido del objeto mutable ha cambiado de [] a``[10]``. Ya que ambas variables referencian al mismo objeto, el usar cualquiera de los nombres accederá al valor modificado [10].

Si, por otra parte, asignamos un objeto inmutable a x:

>>> x = 5  # ints are immutable
>>> y = x
>>> x = x + 1  # 5 can't be mutated, we are creating a new object here
>>> x
6
>>> y
5

podemos ver que x e y ya no son iguales. Esto es debido a que los enteros son immutable, y cuando hacemos x = x + 1 no estamos mutando el entero 5 incrementando su valor; en su lugar, estamos creando un nuevo objeto (el entero 6) y se lo asignamos a x (esto es, cambiando el objeto al cual referencia x). Después de esta asignación tenemos dos objetos (los enteros 6 y 5) y dos variables que referencian a ellos (x ahora referencia a 6 pero y todavía referencia a 5).

Algunas operaciones (por ejemplo y.append(10) y y.sort()) mutan al objeto mientras que operaciones que podrían parecer similares (por ejemplo y = y + [10] y sorted(y)) crean un nuevo objeto. En general, en Python (y en todo momento en la biblioteca estándar) un método que muta un objeto retornará None para evitar tener dos tipos de operaciones que puedan ser confusas. Por tanto, si escribes accidentalmente y.sort() pensando que te retornará una copia ordenada de y, obtendrás, en su lugar, None, lo cual ayudará a que tu programa genera un error que pueda ser diagnosticado fácilmente.

Sin embargo, existe una clase de operaciones en las cuales la misma operación tiene, a veces, distintos comportamientos con diferentes tipos: los operadores de asignación aumentada. Por ejemplo, += muta listas pero no tuplas o enteros (a_list += [1, 2, 3] es equivalente a a_list.extend([1, 2, 3]) y muta a_list, mientras que some_tuple += (1, 2, 3) y some_int += 1 crea nuevos objetos).

En otras palabras:

Si tenemos un objeto mutable (list, dict, set, etc.), podemos usar algunas operaciones específicas para mutarlo y todas las variables que referencian al mismo verán el cambio reflejado.

Si tenemos un objeto inmutable (str, int, tuple, etc.), todas las variables que referencian al mismo verán siempre el mismo valor pero las operaciones que transforman ese valor en un nuevo valor siempre retornan un nuevo objeto.

Si deseas saber si dos variables referencian o no al mismo objeto puedes usar el operador is o la función incorporada id().

¿Cómo puedo escribir una función sin parámetros (invocación mediante referencia)?

Recuerda que los argumentos son pasados mediante asignación en Python. Ya que las asignaciones simplemente crean referencias a objetos, no hay alias entre el nombre de un argumento en el invocador y el invocado y, por tanto, no hay invocación por referencia per se. Puedes obtener el mismo efecto deseado de formas distintas.

Mediante el retorno de una tupla de resultados:

>>> def func1(a, b):
...     a = 'new-value'        # a and b are local names
...     b = b + 1              # assigned to new objects
...     return a, b            # return new values
...
>>> x, y = 'old-value', 99
>>> func1(x, y)
('new-value', 100)

Esta es, casi siempre, la solución más clara.

Mediante el uso de variables globales. No es thread-safe y no se recomienda.

Pasando un objeto mutable (intercambiable en el mismo sitio):

>>> def func2(a):
...     a[0] = 'new-value'     # 'a' references a mutable list
...     a[1] = a[1] + 1        # changes a shared object
...
>>> args = ['old-value', 99]
>>> func2(args)
>>> args
['new-value', 100]

Pasando un diccionario que muta:

>>> def func3(args):
...     args['a'] = 'new-value'     # args is a mutable dictionary
...     args['b'] = args['b'] + 1   # change it in-place
...
>>> args = {'a': 'old-value', 'b': 99}
>>> func3(args)
>>> args
{'a': 'new-value', 'b': 100}

O empaquetar valores en una instancia de clase:

>>> class Namespace:
...     def __init__(self, /, **args):
...         for key, value in args.items():
...             setattr(self, key, value)
...
>>> def func4(args):
...     args.a = 'new-value'        # args is a mutable Namespace
...     args.b = args.b + 1         # change object in-place
...
>>> args = Namespace(a='old-value', b=99)
>>> func4(args)
>>> vars(args)
{'a': 'new-value', 'b': 100}

Casi nunca existe una buena razón para hacer esto tan complicado.

Tu mejor opción es retornar una tupla que contenga los múltiples resultados.

¿Cómo se puede hacer una función de orden superior en Python?

Tienes dos opciones: puedes usar ámbitos de aplicación anidados o puedes usar objetos invocables. Por ejemplo, supón que querías definir linear(a,b) que devuelve una función f(x) que calcula el valor a*x+b. Usar ámbitos de aplicación anidados:

def linear(a, b):
    def result(x):
        return a * x + b
    return result

O usar un objeto invocable:

class linear:

    def __init__(self, a, b):
        self.a, self.b = a, b

    def __call__(self, x):
        return self.a * x + self.b

En ambos casos,

taxes = linear(0.3, 2)

nos da un objeto invocable donde taxes(10e6) == 0.3 * 10e6 + 2.

El enfoque del objeto invocable tiene la desventaja que es un ligeramente más lento y el resultado es un código levemente más largo. Sin embargo, destacar que una colección de invocables pueden compartir su firma vía herencia:

class exponential(linear):
    # __init__ inherited
    def __call__(self, x):
        return self.a * (x ** self.b)

Los objetos pueden encapsular el estado de varios métodos:

class counter:

    value = 0

    def set(self, x):
        self.value = x

    def up(self):
        self.value = self.value + 1

    def down(self):
        self.value = self.value - 1

count = counter()
inc, dec, reset = count.up, count.down, count.set

Aquí inc(), dec() y reset() se comportan como funciones las cuales comparten la misma variable de conteo.

¿Cómo copio un objeto en Python?

En general, prueba copy.copy() o copy.deepcopy() para el caso general. No todos los objetos se pueden copiar pero la mayoría sí que pueden copiarse.

Algunas objetos se pueden copiar de forma más sencilla. Los diccionarios disponen de un método copy():

newdict = olddict.copy()

Las secuencias se pueden copiar usando un rebanado:

new_l = l[:]

¿Cómo puedo encontrar los métodos o atributos de un objeto?

Para la instancia x de una clase definida por el usuario, dir(x) devuelve una lista de nombres ordenados alfabéticamente que contiene los atributos y métodos de la instancia y los atributos definidos mediante su clase.

¿Cómo puede mi código descubrir el nombre de un objeto?

Hablando de forma general no podrían puesto que los objetos no disponen, realmente, de un nombre. Esencialmente, las asignaciones relacionan un nombre con su valor; Lo mismo se cumple con las declaraciones def y class pero, en este caso, el valor es un invocable. Considera el siguiente código:

>>> class A:
...     pass
...
>>> B = A
>>> a = B()
>>> b = a
>>> print(b)
<__main__.A object at 0x16D07CC>
>>> print(a)
<__main__.A object at 0x16D07CC>

Podría decirse que la clase tiene un nombre: aunque está ligada a dos nombres y se invoca a través del nombre B, la instancia creada se sigue reportando como una instancia de la clase A. Sin embargo, es imposible decir si el nombre de la instancia es a o b, ya que ambos nombres están ligados al mismo valor.

En términos generales, no debería ser necesario que tu código «conozca los nombres» de determinados valores. A menos que estés escribiendo deliberadamente programas introspectivos, esto suele ser una indicación de que un cambio de enfoque podría ser beneficioso.

En comp.lang.python, Fredrik Lundh proporcionó una vez una excelente analogía en respuesta a esta pregunta:

De la misma forma que obtienes el nombre de ese gato que te has encontrado en tu porche el propio gato (objeto) no te puede indicar su nombre y, realmente, no importa – por tanto, la única forma de encontrar cómo se llama sería preguntando a todos los vecinos (espacios de nombres) si es su gato (objeto)…

…y no te sorprendas si encuentras que se le conoce mediante diferentes nombres o ¡nadie conoce su nombre!

¿Qué ocurre con la precedencia del operador coma?

La coma no es un operador en Python. Considera la sesión:

>>> "a" in "b", "a"
(False, 'a')

Debido a que la coma no es un operador sino un separador entre expresiones lo anterior se evalúe como se ha introducido:

("a" in "b"), "a"

no:

"a" in ("b", "a")

Lo mismo sucede con varios operadores de asignación (=, +=, etc). No son realmente operadores sino delimitadores sintácticos en declaraciones de asignación.

¿Existe un equivalente al operador ternario de C «?:»?

Sí, existe. La sintaxis es como sigue:

[on_true] if [expression] else [on_false]

x, y = 50, 25
small = x if x < y else y

Antes de que esta sintaxis se introdujera en Python 2.5 una expresión común fue el uso de operadores lógicos:

[expression] and [on_true] or [on_false]

Sin embargo, esa expresión no es segura ya que puede retornar valores erróneos cuando on_true tiene un valor booleano falso. Por tanto, siempre es mejor usar la forma ... if ... else ....

¿Es posible escribir expresiones en una línea de forma ofuscada en Python?

Sí. Normalmente se puede hacer anidando lambda dentro de lambda. Examina los siguientes tres ejemplos, creados por Ulf Bartelt:

from functools import reduce

# Primes < 1000
print(list(filter(None,map(lambda y:y*reduce(lambda x,y:x*y!=0,
map(lambda x,y=y:y%x,range(2,int(pow(y,0.5)+1))),1),range(2,1000)))))

# First 10 Fibonacci numbers
print(list(map(lambda x,f=lambda x,f:(f(x-1,f)+f(x-2,f)) if x>1 else 1:
f(x,f), range(10))))

# Mandelbrot set
print((lambda Ru,Ro,Iu,Io,IM,Sx,Sy:reduce(lambda x,y:x+y,map(lambda y,
Iu=Iu,Io=Io,Ru=Ru,Ro=Ro,Sy=Sy,L=lambda yc,Iu=Iu,Io=Io,Ru=Ru,Ro=Ro,i=IM,
Sx=Sx,Sy=Sy:reduce(lambda x,y:x+y,map(lambda x,xc=Ru,yc=yc,Ru=Ru,Ro=Ro,
i=i,Sx=Sx,F=lambda xc,yc,x,y,k,f=lambda xc,yc,x,y,k,f:(k<=0)or (x*x+y*y
>=4.0) or 1+f(xc,yc,x*x-y*y+xc,2.0*x*y+yc,k-1,f):f(xc,yc,x,y,k,f):chr(
64+F(Ru+x*(Ro-Ru)/Sx,yc,0,0,i)),range(Sx))):L(Iu+y*(Io-Iu)/Sy),range(Sy
))))(-2.1, 0.7, -1.2, 1.2, 30, 80, 24))
#    \___ ___/  \___ ___/  |   |   |__ lines on screen
#        V          V      |   |______ columns on screen
#        |          |      |__________ maximum of "iterations"
#        |          |_________________ range on y axis
#        |____________________________ range on x axis

¡No probéis esto en casa, personitas!

¿Qué hace la barra (/) en medio de la lista de parámetros de una función?

Un slash en la lista de argumentos de una función denota que los parámetros previos al mismo son únicamente posicionales. Parámetros únicamente posicionales son aquellos cuyos nombres no son usables internamente. Mediante la llamada a una función que acepta parámetros únicamente posicionales, los argumentos se mapean a parámetros basados únicamente en su posición. Por ejemplo, pow() es una función que acepta parámetros únicamente posicionales. Su documentación es de la siguiente forma:

>>> help(divmod)
Help on built-in function divmod in module builtins:

divmod(x, y, /)
    Return the tuple (x//y, x%y).  Invariant: div*y + mod == x.

El slash al final de la lista de parámetros indica que los tres parámetros son únicamente posicionales. Por tanto, invocar a pow() con argumentos con palabra clave podría derivar en un error:

>>> divmod(x=3, y=4)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: divmod() takes no keyword arguments

Números y cadenas

¿Cómo puedo especificar enteros hexadecimales y octales?

Para especificar un dígito octal, prefija el valor octal con un cero y una «o» en minúscula o mayúscula. Por ejemplo, para definir la variable «a» con el valor octal «10» (8 en decimal), escribe:

>>> a = 0o10
>>> a
8

Un hexadecimal es igual de simple. Simplemente añade un cero y una «x», en minúscula o mayúscula, antes del número hexadecimal . Los dígitos hexadecimales se pueden especificar en minúsculas o mayúsculas. Por ejemplo, en el intérprete de Python:

>>> a = 0xa5
>>> a
165
>>> b = 0XB2
>>> b
178

¿Por qué -22 // 10 devuelve -3?

Es debido, principalmente al deseo que i % j tenga el mismo signo que j. Si quieres eso y, además, quieres:

i == (i // j) * j + (i % j)

entonces la división entera debe retornar el valor base más bajo. C también requiere que esa esa identidad se mantenga de tal forma que cuando los compiladores truncan i // j necesitan que i % j tenga el mismo signo que i.

Existen unos pocos casos para i % j cuando j es negativo. Cuando j es positivo, existen muchos casos y, virtualmente, en todos ellos es más útil para i % j que sea >= 0. Si el reloj dice que ahora son las 10, ¿qué dijo hace 200 horas? -190 % 12 == 2 es útil; -190 % 12 == -10 es un error listo para morderte.

How do I get int literal attribute instead of SyntaxError?

Trying to lookup an int literal attribute in the normal manner gives a syntax error because the period is seen as a decimal point:

>>> 1.__class__
  File "<stdin>", line 1
  1.__class__
   ^
SyntaxError: invalid decimal literal

The solution is to separate the literal from the period with either a space or parentheses.

>>> 1 .__class__
<class 'int'>
>>> (1).__class__
<class 'int'>

¿Cómo convierto una cadena a un número?

Para enteros puedes usar la función incorporada constructor de tipos int(), por ejemplo int('144') == 144. De forma similar, float() convierte a un número de coma flotante, por ejemplo float('144') == 144.0.

Por defecto, estas interpretan el número como decimal de tal forma que int('0144') == 144 y int('0x144') lanzará ValueError. int(string, base) toma la base para convertirlo desde un segundo parámetro opcional, por tanto int('0x144', 16) == 324. Si la base se especifica como 0, el número se interpreta usando las reglas de Python’s rules: un prefijo “0o” indica octal y un prefijo “0x” indica un número hexadecimal.

No uses la función incorporada eval() si todo lo que necesitas es convertir cadenas a números. eval() será considerablemente más lento y presenta riesgos de seguridad: cualquiera podría introducir una expresión Python que presentara efectos indeseados. Por ejemplo, alguien podría pasar``__import__(“os”).system(«rm -rf $HOME»)`` lo cual borraría el directorio home al completo.

eval() también tiene el efecto de interpretar números como expresiones Python , de tal forma que, por ejemplo, eval('09') dará un error de sintaxis porque Python no permite un “0” inicial en un número decimal (excepto “0”).

¿Cómo puedo convertir un número a una cadena?

Para convertir, por ejemplo, el número 144 a la cadena “144”, usa el constructor de tipos incorporado str(). Si deseas una representación hexadecimal o octal usa la función incorporada hex() o oct(). Para un formateado elaborado puedes ver las secciones de Literales de cadena formateados y Sintaxis de formateo de cadena, por ejemplo "{:04d}".format(144) produce '0144' y "{:.3f}".format(1.0/3.0) produce '0.333'.

¿Cómo puedo modificar una cadena in situ?

No puedes debido a que las cadenas son inmutables. En la mayoría de situaciones solo deberías crear una nueva cadena a partir de varias partes que quieras usar para crearla. Sin embargo, si necesitas un objeto con la habilidad de modificar en el mismo lugar datos unicode prueba usando el objeto io.StringIO o el módulo array:

>>> import io
>>> s = "Hello, world"
>>> sio = io.StringIO(s)
>>> sio.getvalue()
'Hello, world'
>>> sio.seek(7)
7
>>> sio.write("there!")
6
>>> sio.getvalue()
'Hello, there!'

>>> import array
>>> a = array.array('u', s)
>>> print(a)
array('u', 'Hello, world')
>>> a[0] = 'y'
>>> print(a)
array('u', 'yello, world')
>>> a.tounicode()
'yello, world'

¿Cómo puedo usar cadenas para invocar funciones/métodos?

Existen varias técnicas.

Lo mejor sería usar un diccionario que mapee cadenas a funciones. La principal ventaja de esta técnica es que las cadenas no necesitan ser iguales que los nombres de las funciones. Esta es también la principal técnica que se usa para emular un constructo case:

def a():
    pass

def b():
    pass

dispatch = {'go': a, 'stop': b}  # Note lack of parens for funcs

dispatch[get_input()]()  # Note trailing parens to call function

Usa la función incorporada getattr():

import foo
getattr(foo, 'bar')()

Nótese que getattr() funciona en cualquier objeto, incluido clases, instancias de clases, módulos, etc.

Esto se usa en varios lugares de la biblioteca estándar, como esto:

class Foo:
    def do_foo(self):
        ...

    def do_bar(self):
        ...

f = getattr(foo_instance, 'do_' + opname)
f()

Use locals() para resolver el nombre de la función:

def myFunc():
    print("hello")

fname = "myFunc"

f = locals()[fname]
f()

¿Existe un equivalente a chomp() en Perl para eliminar nuevas líneas al final de las cadenas?

Puedes usar S.rstrip("\r\n") para eliminar todas las ocurrencias de cualquier terminación de línea desde el final de la cadena S sin eliminar el resto de espacios en blanco que le siguen. Si la cadena S representa más de una línea con varias líneas vacías al final, las terminaciones de línea para todas las líneas vacías se eliminarán:

>>> lines = ("line 1 \r\n"
...          "\r\n"
...          "\r\n")
>>> lines.rstrip("\n\r")
'line 1 '

Ya que esto solo sería deseable, típicamente, cuando lees texto línea a línea, usar S.rstrip() de esta forma funcionaría bien.

¿Existe un equivalente a scanf() o a sscanf() ?

No de la misma forma.

Para análisis sintáctico simple de la entrada, el método más sencillo es, usualmente, el separar la línea en palabras delimitadas por espacios usando el método split() de los objetos string y, posteriormente, convertir cadenas decimales a valores usando int() o float(). split() permite un parámetro opcional «sep» que es útil si la línea usa algo diferente a espacios en blanco como separador.

Para análisis sintáctico de la entrada más complejo, las expresiones regulares son más poderosas que sscanf() de C y se ajustan mejor a esta tarea.

¿Qué significa “UnicodeDecodeError” o “UnicodeEncodeError”?

Ver CÓMO (HOWTO) Unicode.

Rendimiento

Mi programa es muy lento. ¿Cómo puedo acelerarlo?

Esa es una pregunta difícil, en general. Primero, aquí tienes una lista de cosas a recordar antes de ir más allá:

Las características del rendimiento varían entre las distintas implementaciones de Python. Estas preguntas frecuentes se enfocan en CPython.

El comportamiento puede variar entre distintos sistemas operativos, especialmente cuando se habla de tareas I/O o multi-tarea.

Siempre deberías encontrar las partes importantes en tu programa antes de intentar optimizar el código (ver el módulo profile).

Escribir programas de comparación del rendimiento te permitirá iterar rápidamente cuando te encuentres buscando mejoras (ver el módulo timeit).

Es altamente recomendable disponer de una buena cobertura de código (a partir de pruebas unitarias o cualquier otra técnica) antes de introducir potenciales regresiones ocultas en sofisticadas optimizaciones.

Dicho lo anterior, existen muchos trucos para acelerar código Python. Aquí tienes algunos principios generales que te permitirán llegar a alcanzar niveles de rendimiento aceptables:

El hacer más rápido tu algoritmo (o cambiarlo por alguno más rápido) puede provocar mayores beneficios que intentar unos pocos trucos de micro-optimización a través de todo tu código.

Utiliza las estructuras de datos correctas. Estudia la documentación para los Tipos Integrados y el módulo collections.

Cuando la biblioteca estándar proporciona una primitiva de hacer algo, esta supuestamente será (aunque no se garantiza) más rápida que cualquier otra alternativa que se te ocurra. Esto es doblemente cierto si las primitivas han sido escritas en C, como los builtins y algunos tipos extendidos. Por ejemplo, asegúrate de usar el método integrado list.sort() o la función relacionada sorted() para ordenar (y ver HOW TO - Ordenar para ver ejemplos de uso moderadamente avanzados).

Las abstracciones tienden a crear rodeos y fuerzan al intérprete a trabajar más. Si el nivel de rodeos sobrepasa el trabajo útil realizado tu programa podría ser más lento. Deberías evitar abstracciones excesivas, especialmente, en forma de pequeñas funciones o métodos (que también va en detrimento de la legibilidad).

Si has alcanzado el límite de lo que permite el uso de Python puro, existen otras herramientas que te permiten ir más allá. Por ejemplo, Cython [http://cython.org] puede compilar una versión ligeramente modificada del código Python en una extensión en C y se podría usar en muchas plataformas diferentes. Cython puede obtener ventaja de la compilación (y anotaciones de tipos opcionales) para hacer que tu código sea significativamente más rápido cuando se ejecuta. Si confías en tus habilidades de programar en C también puedes escribir un módulo de extensión en C tú mismo.

Ver también

La página de la wiki dedicada a trucos de rendimiento [https://wiki.python.org/moin/PythonSpeed/PerformanceTips].

¿Cuál es la forma más eficiente de concatenar muchas cadenas conjuntamente?

Los objetos str y bytes son inmutables, por tanto, concatenar muchas cadenas en una sola es ineficiente debido a que cada concatenación crea un nuevo objeto. En el caso más general, el coste total en tiempo de ejecución es cuadrático en relación a la longitud de la cadena final.

Para acumular muchos objetos str, la forma recomendada sería colocarlos en una lista y llamar al método str.join() al final:

chunks = []
for s in my_strings:
    chunks.append(s)
result = ''.join(chunks)

(otra forma que sería razonable en términos de eficiencia sería usar io.StringIO)

Para acumular muchos objetos bytes, la forma recomendada sería extender un objeto bytearray usando el operador de concatenación in situ (el operador +=):

result = bytearray()
for b in my_bytes_objects:
    result += b

Secuencias (Tuplas/Listas)

¿Cómo convertir entre tuplas y listas?

El constructor tuple(seq) convierte cualquier secuencia (en realidad, cualquier iterable) en una tupla con los mismos elementos y en el mismo orden.

Por ejemplo, tuple([1, 2, 3]) lo convierte en (1, 2, 3) y tuple('abc') lo convierte en ('a', 'b', 'c'). Si el argumento es una tupla no creará una nueva copia y retornará el mismo objeto, por tanto, llamar a tuple() no tendrá mucho coste si no estás seguro si un objeto ya es una tupla.

El constructor list(seq) convierte cualquier secuencia o iterable en una lista con los mismos elementos y en el mismo orden. Por ejemplo, list((1, 2, 3)) lo convierte a [1, 2, 3] y list('abc') lo convierte a ['a', 'b', 'c']. Si el argumento es una lista, hará una copia como lo haría seq[:].

¿Qué es un índice negativo?

Las secuencias en Python están indexadas con números positivos y negativos. Para los números positivos el 0 será el primer índice, el 1 el segundo y así en adelante. Para los índices negativos el -1 el último índice, el -2 el penúltimo, etc. Piensa en seq[-n] como si fuera seq[len(seq)-n].

El uso de índices negativos puede ser muy conveniente. Por ejemplo S[:-1] se usa para todo la cadena excepto para su último carácter, lo cual es útil para eliminar el salto de línea final de una cadena.

¿Cómo puedo iterar sobre una secuencia en orden inverso?

Usa la función incorporada reversed():

for x in reversed(sequence):
    ...  # do something with x ...

Esto no transformará la secuencia original sino que creará una nueva copia en orden inverso por la que se puede iterar.

¿Cómo eliminar duplicados de una lista?

Puedes echar un vistazo al recetario de Python para ver una gran discusión mostrando muchas formas de hacer esto:

https://code.activestate.com/recipes/52560/

Si no te preocupa que la lista se reordene la puedes ordenar y, después, y después escanearla desde el final borrando duplicados a medida que avanzas:

if mylist:
    mylist.sort()
    last = mylist[-1]
    for i in range(len(mylist)-2, -1, -1):
        if last == mylist[i]:
            del mylist[i]
        else:
            last = mylist[i]

Si todos los elementos de la lista pueden ser usados como claves (por ejemplo son todos hashable) esto será, en general, más rápido

mylist = list(set(mylist))

Esto convierte la lista en un conjunto eliminando, por tanto, los duplicados y, posteriormente, puedes volver a una lista.

Cómo eliminar duplicados de una lista

Al igual que con la eliminación de duplicados, una posibilidad es iterar explícitamente a la inversa con una condición de eliminación. Sin embargo, es más fácil y rápido utilizar el reemplazo de sectores con una iteración directa implícita o explícita. Aquí hay tres variaciones.:

mylist[:] = filter(keep_function, mylist)
mylist[:] = (x for x in mylist if keep_condition)
mylist[:] = [x for x in mylist if keep_condition]

Esta comprensión de lista puede ser la más rápida.

¿Cómo se puede hacer un array en Python?

Usa una lista:

["this", 1, "is", "an", "array"]

Las listas son equivalentes en complejidad temporal a arrays en C o Pascal; La principal diferencia es que una lista en Python puede contener objetos de diferentes tipos.

The array module also provides methods for creating arrays of fixed types with compact representations, but they are slower to index than lists. Also note that NumPy and other third party packages define array-like structures with various characteristics as well.

Para obtener listas enlazadas al estilo de las de Lisp, puedes emular celdas cons usando tuplas:

lisp_list = ("like",  ("this",  ("example", None) ) )

Si deseas que haya mutabilidad podrías usar listas en lugar de tuplas. El análogo a un car de Lisp es lisp_list[0] y al análogo a cdr es lisp_list[1]. Haz esto solo si estás seguro que es lo que necesitas debido a que, normalmente, será bastante más lento que el usar listas Python.

¿Cómo puedo crear una lista multidimensional?

Seguramente hayas intentado crear un array multidimensional de la siguiente forma:

>>> A = [[None] * 2] * 3

Esto parece correcto si lo muestras en pantalla:

>>> A
[[None, None], [None, None], [None, None]]

Pero cuando asignas un valor, se muestra en múltiples sitios:

>>> A[0][0] = 5
>>> A
[[5, None], [5, None], [5, None]]

La razón es que replicar una lista con * no crea copias, solo crea referencias a los objetos existentes. El *3 crea una lista conteniendo 3 referencias a la misma lista de longitud dos. Cambios a una fila se mostrarán en todas las filas, lo cual, seguramente, no es lo que deseas.

El enfoque recomendado sería crear, primero, una lista de la longitud deseada y, después, rellenar cada elemento con una lista creada en ese momento:

A = [None] * 3
for i in range(3):
    A[i] = [None] * 2

Esto genera una lista conteniendo 3 listas distintas de longitud dos. También puedes usar una comprensión de lista:

w, h = 2, 3
A = [[None] * w for i in range(h)]

O puedes usar una extensión que proporcione un tipo de dato para matrices; NumPy [http://www.numpy.org/] es la más conocida.

¿Cómo puedo aplicar un método a una secuencia de objetos?

Usa una comprensión de listas:

result = [obj.method() for obj in mylist]

¿Por qué hacer lo siguiente, a_tuple[i] += ['item'], lanza una excepción cuando la suma funciona?

Esto es debido a la combinación del hecho de que un operador de asignación aumentada es un operador de asignación y a la diferencia entre objetos mutables e inmutable en Python.

Esta discusión aplica, en general, cuando los operadores de asignación aumentada se aplican a elementos de una tupla que apuntan a objetos mutables. Pero vamos a usar una lista y += para el ejemplo.

Si escribes:

>>> a_tuple = (1, 2)
>>> a_tuple[0] += 1
Traceback (most recent call last):
   ...
TypeError: 'tuple' object does not support item assignment

La razón por la que se produce la excepción debería ser evidente: 1 se añade al objeto a_tuple[0] que apunta a (1), creando el objeto resultante, 2, pero cuando intentamos asignar el resultado del cálculo, 2, al elemento 0 de la tupla, obtenemos un error debido a que no podemos cambiar el elemento al que apunta la tupla.

En realidad, lo que esta declaración de asignación aumentada está haciendo es, aproximadamente, lo siguiente:

>>> result = a_tuple[0] + 1
>>> a_tuple[0] = result
Traceback (most recent call last):
  ...
TypeError: 'tuple' object does not support item assignment

Es la parte de asignación de la operación la que provoca el error, debido a que una tupla es inmutable.

Cuando escribes algo como lo siguiente:

>>> a_tuple = (['foo'], 'bar')
>>> a_tuple[0] += ['item']
Traceback (most recent call last):
  ...
TypeError: 'tuple' object does not support item assignment

La excepción es un poco más sorprendente e, incluso, más sorprendente es el hecho que aunque hubo un error, la agregación funcionó:

>>> a_tuple[0]
['foo', 'item']

Para ver lo que sucede necesitas saber que (a) si un objeto implementa un método mágico __iadd__ , se le llama cuando se ejecuta la asignación aumentada += y el valor devuelto es lo que se usa en la declaración de asignación; y (b) para listas, __iadd__ es equivalente a llamar a extend en la lista y retornar la lista. Es por esto que decimos que para listas, += es un atajo para list.extend:

>>> a_list = []
>>> a_list += [1]
>>> a_list
[1]

Esto es equivalente a

>>> result = a_list.__iadd__([1])
>>> a_list = result

El objeto al que apunta a_list ha mutado y el puntero al objeto mutado es asignado de vuelta a a_list. El resultado final de la asignación no es opción debido a que es un puntero al mismo objeto al que estaba apuntando a_list pero la asignación sí que ocurre.

Por tanto, en nuestro ejemplo con tupla lo que está pasando es equivalente a:

>>> result = a_tuple[0].__iadd__(['item'])
>>> a_tuple[0] = result
Traceback (most recent call last):
  ...
TypeError: 'tuple' object does not support item assignment

El __iadd__ se realiza con éxito y la lista se extiende pero, incluso aunque result apunta al mismo objeto al que ya está apuntando a_tuple[0] la asignación final sigue resultando en un error, debido a que las tuplas son inmutables.

Quiero hacer una ordenación compleja: ¿Puedes hacer una transformada Schwartziana (Schwartzian Transform) en Python?

La técnica, atribuida a Randal Schwartz, miembro de la comunidad Perl, ordena los elementos de una lista mediante una métrica que mapea cada elemento a su «valor orden». En Python, usa el argumento key par el método list.sort():

Isorted = L[:]
Isorted.sort(key=lambda s: int(s[10:15]))

¿Cómo puedo ordenar una lista a partir de valores de otra lista?

Las puedes unir en un iterador de tuplas, ordena la lista resultando y después extrae el elemento que deseas.

>>> list1 = ["what", "I'm", "sorting", "by"]
>>> list2 = ["something", "else", "to", "sort"]
>>> pairs = zip(list1, list2)
>>> pairs = sorted(pairs)
>>> pairs
[("I'm", 'else'), ('by', 'sort'), ('sorting', 'to'), ('what', 'something')]
>>> result = [x[1] for x in pairs]
>>> result
['else', 'sort', 'to', 'something']

Objetos

¿Qué es una clase?

Una clase es un tipo de objeto particular creado mediante la ejecución de la declaración class. Los objetos class se usan como plantillas para crear instancias de objetos que son tanto los datos (atributos) como el código (métodos) específicos para un tipo de dato.

Una clase puede estar basada en una o más clases diferentes, llamadas su(s) clase(s). Hereda los atributos y métodos de sus clases base. Esto permite que se pueda refinar un objeto modelo de forma sucesiva mediante herencia. Puedes tener una clase genérica Mailbox que proporciona métodos de acceso básico para un buzón de correo y subclases como MboxMailbox, MaildirMailbox, OutlookMailbox que gestionan distintos formatos específicos de buzón de correos.

¿Qué es un método?

Un método es una función de un objeto x que puedes llamar, normalmente, de la forma x.name(arguments...). Los métodos se definen como funciones dentro de la definición de la clase:

class C:
    def meth(self, arg):
        return arg * 2 + self.attribute

¿Qué es self?

Self es, básicamente, un nombre que se usa de forma convencional como primer argumento de un método. Un método definido como meth(self, a, b, c) se le llama como x.meth(a, b, c) para una instancia x de la clase es que se definió; el método invocado pensará que se le ha invocado como meth(x, a, b, c).

Ver también ¿Por qué debe usarse “self” explícitamente en las definiciones y llamadas de métodos?.

¿Cómo puedo comprobar si un objeto es una instancia de una clase dada o de una subclase de la misma?

Usa la función incorporada isinstance(obj, cls). Puedes comprobar si un objeto es una instancia de cualquier número de clases proporcionando una tupla en lugar de una sola clase, por ejemplo isinstance(obj, (class1, class2, ...)) y, también, puedes comprobar si un objeto es uno de los tipos incorporados por ejemplo isinstance(obj, str) o isinstance(obj, (int, float, complex)).

Note that isinstance() also checks for virtual inheritance from an abstract base class. So, the test will return True for a registered class even if hasn’t directly or indirectly inherited from it. To test for «true inheritance», scan the MRO of the class:

from collections.abc import Mapping

class P:
     pass

class C(P):
    pass

Mapping.register(P)

>>> c = C()
>>> isinstance(c, C)        # direct
True
>>> isinstance(c, P)        # indirect
True
>>> isinstance(c, Mapping)  # virtual
True

# Actual inheritance chain
>>> type(c).__mro__
(<class 'C'>, <class 'P'>, <class 'object'>)

# Test for "true inheritance"
>>> Mapping in type(c).__mro__
False

Destacar que muchos programas no necesitan usar isinstance() de forma frecuente en clases definidas por el usuario. Si estás desarrollando clases un mejor estilo orientado a objetos sería el de definir los métodos en las clases que encapsulan un comportamiento en particular en lugar de ir comprobando la clase del objeto e ir haciendo cosas en base a la clase que es. Por ejemplo, si tienes una función que hace lo siguiente:

def search(obj):
    if isinstance(obj, Mailbox):
        ...  # code to search a mailbox
    elif isinstance(obj, Document):
        ...  # code to search a document
    elif ...

Un enfoque más adecuado sería definir un método search() en todas las clases e invocarlo:

class Mailbox:
    def search(self):
        ...  # code to search a mailbox

class Document:
    def search(self):
        ...  # code to search a document

obj.search()

¿Qué es la delegación?

La delegación es una técnica orientada a objetos (también llamado un patrón de diseño). Digamos que tienes un objeto x y deseas cambiar el comportamiento de solo uno de sus métodos. Puedes crear una nueva clase que proporciona una nueva implementación del método que te interesa cambiar y delega el resto de métodos al método correspondiente de x.

Los programadores Python pueden implementar la delegación de forma muy sencilla. Por ejemplo, la siguiente clase implementa una clase que se comporta como un fichero pero convierte todos los datos escritos a mayúsculas:

class UpperOut:

    def __init__(self, outfile):
        self._outfile = outfile

    def write(self, s):
        self._outfile.write(s.upper())

    def __getattr__(self, name):
        return getattr(self._outfile, name)

Aquí, la clase UpperOut redefine el método write() para convertir la cadena del argumento a mayúscula antes de invocar al método self._outfile.write(). El resto de métodos han sido delegados al objeto self._outfile. La delegación se consigue mediante el método __getattr__; consulta la referencia del lenguaje para obtener más información sobre cómo controlar el acceso a atributos.

Ten en cuenta que para casos más generales la delegación puede ser algo más complicada. Cuando los atributos se deben colocar y recuperar la clase debe definir, también, un método __setattr__() y hay que hacerlo con cuidado. La implementación básica de __setattr__() es, aproximadamente, equivalente a lo siguiente:

class X:
    ...
    def __setattr__(self, name, value):
        self.__dict__[name] = value
    ...

Muchas implementaciones de __setattr__() deben modificar self.__dict__ para almacenar el estado local para self sin provocar una recursión infinita.

¿Cómo invoco a un método definido en una clase base desde una clase derivada que lo ha sobreescrito?

Usa la función incorporada super():

class Derived(Base):
    def meth(self):
        super(Derived, self).meth()

Para versiones anteriores a la 3.0, puedes usar clases clásicas: Para la definición de una clase como class Derived(Base): ... puedes invocar el método meth() definido en Base (o una de las clases base de Base) como Base.meth(self, arguments...). Aquí, Base.meth es un método no ligado y, por tanto, debes proporcionar el argumento self.

¿Cómo puedo organizar mi código para hacer que sea más sencillo modificar la clase base?

Puede asignar la clase base a un alias y derivar del alias. Entonces todo lo que tiene que cambiar es el valor asignado al alias. Por cierto, este truco también es útil si desea decidir dinámicamente (por ejemplo, dependiendo de la disponibilidad de recursos) qué clase base usar. Ejemplo:

class Base:
    ...

BaseAlias = Base

class Derived(BaseAlias):
    ...

¿Cómo puedo crear datos estáticos de clase y métodos estáticos de clase?

Tanto los datos estáticos como los métodos estáticos (en el sentido de C++ o Java) están permitidos en Python.

Para datos estáticos simplemente define un atributo de clase. Para asignar un nuevo valor al atributo debes usar de forma explícita el nombre de la clase en la asignación:

class C:
    count = 0   # number of times C.__init__ called

    def __init__(self):
        C.count = C.count + 1

    def getcount(self):
        return C.count  # or return self.count

c.count también se refiere a C.count para cualquier c de tal forma que se cumpla isinstance(c, C), a no ser que c sea sobreescrita por si misma o por alguna clase contenida en la búsqueda de clases base desde``c.__class__`` hasta C.

Debes tener cuidado: dentro de un método de C, una asignación como self.count = 42 creará una nueva instancia sin relación con la original que se llamará «count» en el propio diccionario de self. El reunificar el nombre de datos estáticos de una clase debería llevar, siempre, a especificar la clase tanto si se produce desde dentro de un método como si no:

C.count = 314

Los métodos estáticos son posibles:

class C:
    @staticmethod
    def static(arg1, arg2, arg3):
        # No 'self' parameter!
        ...

Sin embargo, una forma más directa de obtener el efecto de un método estático sería mediante una simple función a nivel de módulo:

def getcount():
    return C.count

Si has estructurado tu código para definir una clase única (o una jerarquía de clases altamente relacionadas) por módulo, esto proporcionará la encapsulación deseada.

¿Como puedo sobrecargar constructores (o métodos) en Python?

Esta respuesta es aplicable, en realidad, a todos los métodos pero la pregunta suele surgir primero en el contexto de los constructores.

En C++ deberías escribir

class C {
    C() { cout << "No arguments\n"; }
    C(int i) { cout << "Argument is " << i << "\n"; }
}

En Python solo debes escribir un único constructor que tenga en cuenta todos los casos usando los argumentos por defecto. Por ejemplo:

class C:
    def __init__(self, i=None):
        if i is None:
            print("No arguments")
        else:
            print("Argument is", i)

Esto no es totalmente equivalente pero, en la práctica, es muy similar.

Podrías intentar, también una lista de argumentos de longitud variable, por ejemplo

def __init__(self, *args):
    ...

El mismo enfoque funciona para todas las definiciones de métodos.

Intento usar __spam y obtengo un error sobre _SomeClassName__spam.

Nombres de variable con doble guión prefijado se convierten, con una modificación de nombres, para proporcionar una forma simple pero efectiva de definir variables de clase privadas. Cualquier identificador de la forma __spam (como mínimo dos guiones bajos como prefijo, como máximo un guión bajo como sufijo) se reemplaza con _classname__spam, donde classname es el nombre de la clase eliminando cualquier guión bajo prefijado.

Esto no garantiza la privacidad: un usuario externo puede acceder, de forma deliberada y si así lo desea, al atributo «_classname__spam», y los valores privados son visibles en el __dict__ del objeto. Muchos programadores Python no se suelen molestar en usar nombres privados de variables.

Mi clase define __del__ pero no se le invoca cuando borro el objeto.

Existen varias razones posibles para que suceda así.

La declaración del no invoca, necesariamente, al método __del__() – simplemente reduce el conteo de referencias del objeto y, si se reduce a cero entonces es cuando se invoca a __del__().

Si tus estructuras de datos contienen enlaces circulares (por ejemplo un árbol en el cual cada hijo tiene una referencia al padre y cada padre tiene una lista de hijos) el conteo de referencias no alcanzará nunca el valor de cero. De vez en cuando, Python ejecuta un algoritmo para detectar esos ciclos pero el recolector de basura debe ejecutarse un rato después de que se desvanezca la última referencia a tu estructura de datos, de tal forma que tu método __del__() se pueda invocar en un momento aleatorio que no resulte inconveniente. Esto no es conveniente si estás intentando reproducir un problema. Peor aún, el orden en el que se ejecutan los métodos __del__() del objeto es arbitrario. Puedes ejecutar gc.collect() para forzar una recolección pero existen casos patológicos en los cuales los objetos nunca serán recolectados.

A pesar del recolector de ciclos, siempre será buena idea definir un método close() de forma explícita en objetos que debe ser llamado en el momento que has terminado con ellos. El método close() puede, en ese momento, eliminar atributos que se refieren a subobjetos. No invoques directamente a __del__() – __del__() debe invocar a close() y close() debe asegurarse que puede ser invocado más de una vez en el mismo objeto.

Otra forma de evitar referencias cíclicas sería usando el módulo weakref, que permite apuntar hacia objetos sin incrementar su conteo de referencias. Las estructuras de datos en árbol, por ejemplo, deberían usar referencias débiles para las referencias del padre y hermanos (¡si es que las necesitan!).

Finalmente, si tu método __del__() lanza una excepción, se manda un mensaje de alerta a sys.stderr.

¿Cómo puedo obtener una lista de todas las instancias de una clase dada?

Python no hace seguimiento de todas las instancias de una clase (o de los tipos incorporados). Puedes programar el constructor de una clase para que haga seguimiento de todas sus instancias manteniendo una lista de referencias débiles a cada instancia.

¿Por qué el resultado de id() no parece ser único?

La función incorporada id() devuelve un entero que se garantiza que sea único durante la vida del objeto. Debido a que en CPython esta es la dirección en memoria del objeto, sucede que, frecuentemente, después de que un objeto se elimina de la memoria el siguiente objeto recién creado se localiza en la misma posición en memoria. Esto se puede ver ilustrado en este ejemplo:

>>> id(1000)
13901272
>>> id(2000)
13901272

Las dos ids pertenecen a dos objetos “entero” diferentes que se crean antes y se eliminan inmediatamente después de la ejecución de la invocación a id(). Para estar seguro que los objetos cuya id quieres examinar siguen vivos crea otra referencia al objeto:

>>> a = 1000; b = 2000
>>> id(a)
13901272
>>> id(b)
13891296

When can I rely on identity tests with the is operator?

The is operator tests for object identity. The test a is b is equivalent to id(a) == id(b).

The most important property of an identity test is that an object is always identical to itself, a is a always returns True. Identity tests are usually faster than equality tests. And unlike equality tests, identity tests are guaranteed to return a boolean True or False.

However, identity tests can only be substituted for equality tests when object identity is assured. Generally, there are three circumstances where identity is guaranteed:

1) Assignments create new names but do not change object identity. After the assignment new = old, it is guaranteed that new is old.

2) Putting an object in a container that stores object references does not change object identity. After the list assignment s[0] = x, it is guaranteed that s[0] is x.

3) If an object is a singleton, it means that only one instance of that object can exist. After the assignments a = None and b = None, it is guaranteed that a is b because None is a singleton.

In most other circumstances, identity tests are inadvisable and equality tests are preferred. In particular, identity tests should not be used to check constants such as int and str which aren’t guaranteed to be singletons:

>>> a = 1000
>>> b = 500
>>> c = b + 500
>>> a is c
False

>>> a = 'Python'
>>> b = 'Py'
>>> c = b + 'thon'
>>> a is c
False

Likewise, new instances of mutable containers are never identical:

>>> a = []
>>> b = []
>>> a is b
False

In the standard library code, you will see several common patterns for correctly using identity tests:

1) As recommended by PEP 8 [https://www.python.org/dev/peps/pep-0008], an identity test is the preferred way to check for None. This reads like plain English in code and avoids confusion with other objects that may have boolean values that evaluate to false.

2) Detecting optional arguments can be tricky when None is a valid input value. In those situations, you can create a singleton sentinel object guaranteed to be distinct from other objects. For example, here is how to implement a method that behaves like dict.pop():

_sentinel = object()

def pop(self, key, default=_sentinel):
    if key in self:
        value = self[key]
        del self[key]
        return value
    if default is _sentinel:
        raise KeyError(key)
    return default

3) Container implementations sometimes need to augment equality tests with identity tests. This prevents the code from being confused by objects such as float('NaN') that are not equal to themselves.

For example, here is the implementation of collections.abc.Sequence.__contains__():

def __contains__(self, value):
    for v in self:
        if v is value or v == value:
            return True
    return False

How can a subclass control what data is stored in an immutable instance?

When subclassing an immutable type, override the __new__() method instead of the __init__() method. The latter only runs after an instance is created, which is too late to alter data in an immutable instance.

All of these immutable classes have a different signature than their parent class:

from datetime import date

class FirstOfMonthDate(date):
    "Always choose the first day of the month"
    def __new__(cls, year, month, day):
        return super().__new__(cls, year, month, 1)

class NamedInt(int):
    "Allow text names for some numbers"
    xlat = {'zero': 0, 'one': 1, 'ten': 10}
    def __new__(cls, value):
        value = cls.xlat.get(value, value)
        return super().__new__(cls, value)

class TitleStr(str):
    "Convert str to name suitable for a URL path"
    def __new__(cls, s):
        s = s.lower().replace(' ', '-')
        s = ''.join([c for c in s if c.isalnum() or c == '-'])
        return super().__new__(cls, s)

The classes can be used like this:

>>> FirstOfMonthDate(2012, 2, 14)
FirstOfMonthDate(2012, 2, 1)
>>> NamedInt('ten')
10
>>> NamedInt(20)
20
>>> TitleStr('Blog: Why Python Rocks')
'blog-why-python-rocks'

Módulos

¿Cómo creo un fichero .pyc?

Cuando se importa un módulo por primera vez (o cuando el código fuente ha cambiado desde que el fichero compilado se creó) un fichero .pyc que contiene el código compilado se debería crear en la subcarpeta __pycache__ del directorio que contiene al fichero``.py``. El fichero .pyc tendrá un nombre que empezará con el mismo nombre que el del fichero .py y terminará con .pyc, con un componente intermedio que dependerá del binario python en particular que lo creó. (Ver PEP 3147 [https://www.python.org/dev/peps/pep-3147] para detalles.)

Una razón por la que no se cree un fichero .pyc podría ser debido a un problema de permisos del directorio que contiene al fichero fuente, lo que significa que el subdirectorio __pycache__ no se puede crear. Esto puede suceder, por ejemplo, si desarrollas como un usuario pero lo ejecutas como otro, como si estuvieras probando en un servidor web.

Hasta que no definas la variable de entorno PYTHONDONTWRITEBYTECODE, la creación de un fichero .pyc se hará automáticamente si importas un módulo y Python dispone de la habilidad (permisos, espacio libre, etc…) para crear un subdirectorio __pycache__ y escribir un módulo compilado en ese subdirectorio.

La ejecución de un script principal Python no se considera una importación y no se crea el fichero .pyc. Por ejemplo, Si tienes un módulo principal foo.py que importa a otro módulo xyz.py, cuando ejecutas foo (mediante un comando de la shell python foo.py), se creará un fichero .pyc para xyz porque xyz ha sido importado, pero no se creará un fichero .pyc para foo ya que foo.py no ha sido importado.

Si necesitas crear un fichero .pyc también para foo – es decir, crear un fichero .pyc para un módulo que no ha sido importado – puedes usar los módulos py_compile y compileall.

El módulo py_compile puede compilar manualmente cualquier módulo. Una forma sería usando la función compile() de ese módulo de forma interactiva:

>>> import py_compile
>>> py_compile.compile('foo.py')

Esto escribirá .pyc en el subdirectorio __pycache__ en la misma localización en la que se encuentre foo.py (o, puedes sobreescribir ese comportamiento con el parámetro opcional cfile).

Puedes compilar automáticamente todos los ficheros en un directorio o directorios usando el módulo compileall. Lo puedes hacer desde la línea de comandos ejecutando compileall.py y proporcionando una ruta al directorio que contiene los ficheros Python a compilar:

python -m compileall .

¿Cómo puedo encontrar el nombre del módulo en uso?

Un módulo puede encontrar su propio nombre mirando en la variable global predeterminada __name__. Si tiene el valor '__main__', el programa se está ejecutando como un script. Muchos módulos que se usan, generalmente, importados en otro script proporcionan, además, una interfaz para la línea de comandos o para probarse a si mismos y solo ejecutan código después de comprobar __name__:

def main():
    print('Running test...')
    ...

if __name__ == '__main__':
    main()

¿Cómo podría tener módulos que se importan mutuamente entre ellos?

Supón que tienes los siguientes módulos:

foo.py:

from bar import bar_var
foo_var = 1

bar.py:

from foo import foo_var
bar_var = 2

El problema es que el intérprete realizará los siguientes pasos:

main importa a foo

Se crea un globals vacío para foo

foo se compila y se comienza a ejecutar

foo importa a bar

Se crea un globals vacío para bar

bar se compila y se comienza a ejecutar

bar importa a foo (lo cual no es una opción ya que ya hay un módulo que se llama foo)

bar.foo_var = foo.foo_var

El último paso falla debido a que Python todavía no ha terminado de interpretar a foo y el diccionario de símbolos global para foo todavía se encuentra vacío.

Lo mismo ocurre cuando usas import foo y luego tratas de acceder a foo.foo_var en un código global.

Existen (al menos) tres posibles soluciones para este problema.

Guido van Rossum recomienda evitar todos los usos de from <module> import ..., y colocar todo el código dentro de funciones. La inicialización de variables globales y variables de clase debería usar únicamente constantes o funciones incorporadas . Esto significa que todo se referenciará como <module>.<name> desde un módulo importado.

Jim Roskind sugiere realizar los siguientes pasos en el siguiente orden en cada módulo:

exportar (globals, funciones y clases que no necesitan clases bases importadas)

import declaraciones

código activo (incluyendo globals que han sido inicializados desde valores importados).

Van Rossum doesn’t like this approach much because the imports appear in a strange place, but it does work.

Matthias Urlichs recomienda reestructurar tu código de tal forma que un import recursivo no sea necesario.

Estas soluciones no son mutuamente excluyentes.

__import__(“x.y.z”) devuelve <module “x”>; ¿cómo puedo obtener z?

Considera, en su lugar, usa la función de conveniencia import_module() de importlib:

z = importlib.import_module('x.y.z')

Cuando edito un módulo importado y lo reimporto los cambios no tienen efecto. ¿Por qué sucede esto?

Por razones de eficiencia además de por consistencia, Python solo lee el fichero del módulo la primera vez que el módulo se importa. Si no lo hiciera así, un programa escrito en muchos módulos donde cada módulo importa al mismo módulo básico estaría analizando sintácticamente el mismo módulo básico muchas veces. Para forzar una relectura de un módulo que ha sido modificado haz lo siguiente:

import importlib
import modname
importlib.reload(modname)

Alerta: esta técnica no es 100% segura. En particular, los módulos que contienen declaraciones como

from modname import some_objects

continuarán funcionando con la versión antigua de los objetos importados. Si el módulo contiene definiciones de clase, instancias de clase ya existentes no se actualizarán para usar la nueva definición de la clase. Esto podría resultar en el comportamiento paradójico siguiente:

>>> import importlib
>>> import cls
>>> c = cls.C()                # Create an instance of C
>>> importlib.reload(cls)
<module 'cls' from 'cls.py'>
>>> isinstance(c, cls.C)       # isinstance is false?!?
False

La naturaleza del problema se hace evidente si muestras la «identity» de los objetos clase:

>>> hex(id(c.__class__))
'0x7352a0'
>>> hex(id(cls.C))
'0x4198d0'

Preguntas frecuentes sobre diseño e historia

Contenido

Preguntas frecuentes sobre diseño e historia

¿Por qué Python usa indentación para agrupar declaraciones?

¿Por qué obtengo resultados extraños con operaciones aritméticas simples?

¿Por qué los cálculos de punto flotante son tan inexactos?

¿Por qué las cadenas de caracteres de Python son inmutables?

¿Por qué debe usarse “self” explícitamente en las definiciones y llamadas de métodos?

¿Por qué no puedo usar una tarea en una expresión?

¿Por qué Python usa métodos para alguna funcionalidad (por ejemplo, list.index()) pero funciones para otra (por ejemplo, len(list))?

¿Por qué join() es un método de cadena de caracteres en lugar de un método de lista o tupla?

¿Qué tan rápido van las excepciones?

¿Por qué no hay un switch o una declaración case en Python?

¿No puede emular hilos en el intérprete en lugar de confiar en una implementación de hilos específica del sistema operativo?

¿Por qué las expresiones lambda no pueden contener sentencias?

¿Se puede compilar Python en código máquina, C o algún otro lenguaje?

¿Cómo gestiona Python la memoria?

¿Por qué CPython no utiliza un esquema de recolección de basura más tradicional?

¿Por qué no se libera toda la memoria cuando sale CPython?

¿Por qué hay tipos de datos separados de tuplas y listas?

¿Cómo se implementan las listas en Python?

¿Cómo se implementan los diccionarios en CPython?

¿Por qué las claves del diccionario deben ser inmutables?

¿Por qué list.sort() no retorna la lista ordenada?

¿Cómo se especifica y aplica una especificación de interfaz en Python?

¿Por qué no hay goto?

¿Por qué las cadenas de caracteres sin formato (r-strings) no pueden terminar con una barra diagonal inversa?

¿Por qué Python no tiene una declaración «with» para las asignaciones de atributos?

Why don’t generators support the with statement?

¿Por qué se requieren dos puntos para las declaraciones if/while/def/class?

¿Por qué Python permite comas al final de las listas y tuplas?

¿Por qué Python usa indentación para agrupar declaraciones?

Guido van Rossum cree que usar indentación para agrupar es extremadamente elegante y contribuye mucho a la claridad del programa Python promedio. La mayoría de las personas aprenden a amar esta característica después de un tiempo.

Como no hay corchetes de inicio/fin, no puede haber un desacuerdo entre la agrupación percibida por el analizador y el lector humano. Ocasionalmente, los programadores de C encontrarán un fragmento de código como este:

if (x <= y)
        x++;
        y--;
z++;

Solo se ejecuta la instrucción x ++ si la condición es verdadera, pero la indentación lo lleva a creer lo contrario. Incluso los programadores experimentados de C a veces lo miran durante mucho tiempo preguntándose por qué y se está disminuyendo incluso para x > y.

Debido a que no hay corchetes de inicio/fin, Python es mucho menos propenso a conflictos de estilo de codificación. En C hay muchas formas diferentes de colocar llaves. Después de acostumbrarse a leer y escribir código usando un estilo en particular, es normal sentirse algo incómodo al leer (o tener que escribir) en uno diferente.

Muchos estilos de codificación colocan corchetes de inicio / fin en una línea por sí mismos. Esto hace que los programas sean considerablemente más largos y desperdicia un valioso espacio en la pantalla, lo que dificulta obtener una buena visión general de un programa. Idealmente, una función debería caber en una pantalla (por ejemplo, 20-30 líneas). 20 líneas de Python pueden hacer mucho más trabajo que 20 líneas de C. Esto no se debe únicamente a la falta de corchetes de inicio/fin – la falta de declaraciones y los tipos de datos de alto nivel también son responsables – sino también la indentación basada en la sintaxis ciertamente ayuda.

¿Por qué obtengo resultados extraños con operaciones aritméticas simples?

Ver la siguiente pregunta.

¿Por qué los cálculos de punto flotante son tan inexactos?

Los usuarios a menudo se sorprenden por resultados como este:

>>> 1.2 - 1.0
0.19999999999999996

y creo que es un error en Python. No es. Esto tiene poco que ver con Python, y mucho más con la forma en que la plataforma subyacente maneja los números de punto flotante.

El tipo float en CPython usa una C double para el almacenamiento. Un valor del objeto float se almacena en coma flotante binaria con una precisión fija (típicamente 53 bits) y Python usa operaciones C, que a su vez dependen de la implementación de hardware en el procesador, para realizar operaciones de coma flotante. Esto significa que, en lo que respecta a las operaciones de punto flotante, Python se comporta como muchos lenguajes populares, incluidos C y Java.

Muchos números que se pueden escribir fácilmente en notación decimal no se pueden expresar exactamente en coma flotante binaria. Por ejemplo, después de:

>>> x = 1.2

el valor almacenado para x es una aproximación (muy buena) al valor decimal 1.2, pero no es exactamente igual a él. En una máquina típica, el valor real almacenado es:

1.0011001100110011001100110011001100110011001100110011 (binary)

que es exactamente:

1.1999999999999999555910790149937383830547332763671875 (decimal)

La precisión típica de 53 bits proporciona flotantes Python con 15–16 dígitos decimales de precisión.

Para obtener una explicación más completa, consulte el capítulo aritmética de coma flotante en el tutorial de Python.

¿Por qué las cadenas de caracteres de Python son inmutables?

Hay varias ventajas.

Una es el rendimiento: saber que una cadena es inmutable significa que podemos asignarle espacio en el momento de la creación, y los requisitos de almacenamiento son fijos e inmutables. Esta es también una de las razones para la distinción entre tuplas y listas.

Otra ventaja es que las cadenas en Python se consideran tan «elementales» como los números. Ninguna cantidad de actividad cambiará el valor 8 a otra cosa, y en Python, ninguna cantidad de actividad cambiará la cadena «ocho» a otra cosa.

¿Por qué debe usarse “self” explícitamente en las definiciones y llamadas de métodos?

La idea fue tomada de Modula-3. Resulta ser muy útil, por una variedad de razones.

Primero, es más obvio que está utilizando un método o atributo de instancia en lugar de una variable local. Leer self.x o self.meth() deja absolutamente claro que se usa una variable de instancia o método incluso si no conoce la definición de clase de memoria. En C++, puede darse cuenta de la falta de una declaración de variable local (suponiendo que los globales son raros o fácilmente reconocibles) – pero en Python, no hay declaraciones de variables locales, por lo que debería buscar la definición de clase para estar seguro. Algunos estándares de codificación de C++ y Java requieren que los atributos de instancia tengan un prefijo m_, porque el ser explícito también es útil en esos lenguajes.

En segundo lugar, significa que no es necesaria una sintaxis especial si desea hacer referencia explícita o llamar al método desde una clase en particular. En C++, si desea usar un método de una clase base que se anula en una clase derivada, debe usar el operador :: – en Python puede escribir baseclass.methodname(self, <argument list>). Esto es particularmente útil para métodos __init__(), y en general en los casos en que un método de clase derivada quiere extender el método de clase base del mismo nombre y, por lo tanto, tiene que llamar al método de clase base de alguna manera.

Finalmente, para las variables de instancia se resuelve un problema sintáctico con la asignación: dado que las variables locales en Python son (¡por definición!) Aquellas variables a las que se asigna un valor en un cuerpo de función (y que no se declaran explícitamente como globales), tiene que haber una forma de decirle al intérprete que una asignación estaba destinada a asignar a una variable de instancia en lugar de a una variable local, y que preferiblemente debería ser sintáctica (por razones de eficiencia). C++ hace esto a través de declaraciones, pero Python no tiene declaraciones y sería una pena tener que presentarlas solo para este propósito. Usar el self.var explícito resuelve esto muy bien. Del mismo modo, para usar variables de instancia, tener que escribir self.var significa que las referencias a nombres no calificados dentro de un método no tienen que buscar en los directorios de la instancia. Para decirlo de otra manera, las variables locales y las variables de instancia viven en dos espacios de nombres diferentes, y debe decirle a Python qué espacio de nombres usar.

¿Por qué no puedo usar una tarea en una expresión?

¡A partir de Python 3.8, se puede!

Asignación de expresiones usando el operador de morsa := asigna una variable en una expresión:

while chunk := fp.read(200):
   print(chunk)

Ver PEP 572 [https://www.python.org/dev/peps/pep-0572] para más información.

¿Por qué Python usa métodos para alguna funcionalidad (por ejemplo, list.index()) pero funciones para otra (por ejemplo, len(list))?

Como dijo Guido:

(a) Para algunas operaciones, la notación de prefijo solo se lee mejor que postfijo – las operaciones de prefijo (e ¡infijo!) tienen una larga tradición en matemáticas que le gustan las anotaciones donde las imágenes ayudan al matemático a pensar en un problema. Compare lo fácil con que reescribimos una fórmula como x*(a+b) en x*a + x*b con la torpeza de hacer lo mismo usando una notación OO sin procesar.

(b) Cuando leo un código que dice len(x), sé que está pidiendo la longitud de algo. Esto me dice dos cosas: el resultado es un número entero y el argumento es algún tipo de contenedor. Por el contrario, cuando leo x.len (), ya debo saber que x es algún tipo de contenedor que implementa una interfaz o hereda de una clase que tiene un estándar len(). Sea testigo de la confusión que ocasionalmente tenemos cuando una clase que no está implementando una asignación tiene un método get() o keys(), o algo que no es un archivo tiene un método write().

—https://mail.python.org/pipermail/python-3000/2006-November/004643.html

¿Por qué join() es un método de cadena de caracteres en lugar de un método de lista o tupla?

Las cadenas de caracteres se volvieron mucho más parecidas a otros tipos estándar a partir de Python 1.6, cuando se agregaron métodos que brindan la misma funcionalidad que siempre ha estado disponible utilizando las funciones del módulo de cadenas. La mayoría de estos nuevos métodos han sido ampliamente aceptados, pero el que parece hacer que algunos programadores se sientan incómodos es:

", ".join(['1', '2', '4', '8', '16'])

que da el resultado:

"1, 2, 4, 8, 16"

Hay dos argumentos comunes en contra de este uso.

El primero corre a lo largo de las líneas de: «Se ve realmente feo el uso de un método de un literal de cadena (constante de cadena)», a lo que la respuesta es que sí, pero un literal de cadena es solo un valor fijo. Si se permiten los métodos en nombres vinculados a cadenas, no hay razón lógica para que no estén disponibles en literales.

La segunda objeción generalmente se presenta como: «Realmente estoy diciéndole a una secuencia que una a sus miembros junto con una constante de cadena». Lamentablemente, no lo estas haciendo. Por alguna razón, parece ser mucho menos difícil tener split() como método de cadena, ya que en ese caso es fácil ver que:

"1, 2, 4, 8, 16".split(", ")

es una instrucción a un literal de cadena para retornar las subcadenas de caracteres delimitadas por el separador dado (o, por defecto, ejecuciones arbitrarias de espacio en blanco).

join() es un método de cadena de caracteres porque al usarlo le está diciendo a la cadena de separación que itere sobre una secuencia de cadenas y se inserte entre elementos adyacentes. Este método se puede usar con cualquier argumento que obedezca las reglas para los objetos de secuencia, incluidas las clases nuevas que pueda definir usted mismo. Existen métodos similares para bytes y objetos bytearray.

¿Qué tan rápido van las excepciones?

Un bloque try/except es extremadamente eficiente si no se generan excepciones. En realidad, capturar una excepción es costoso. En versiones de Python anteriores a la 2.0, era común usar este modismo:

try:
    value = mydict[key]
except KeyError:
    mydict[key] = getvalue(key)
    value = mydict[key]

Esto solo tenía sentido cuando esperaba que el dict tuviera la clave casi todo el tiempo. Si ese no fuera el caso, lo codificó así:

if key in mydict:
    value = mydict[key]
else:
    value = mydict[key] = getvalue(key)

Para este caso específico, también podría usar value = dict.setdefault(key, getvalue(key)), pero solo si la llamada getvalue() es lo suficientemente barata porque se evalúa en todos los casos.

¿Por qué no hay un switch o una declaración case en Python?

Puede hacer esto fácilmente con una secuencia de if... elif... elif... else. Ha habido algunas propuestas para cambiar la sintaxis de la declaración, pero todavía no hay consenso sobre si y cómo hacer pruebas de rango. Ver PEP 275 [https://www.python.org/dev/peps/pep-0275] para detalles completos y el estado actual.

Para los casos en los que necesita elegir entre una gran cantidad de posibilidades, puede crear un diccionario que asigne valores de casos a funciones para llamar. Por ejemplo:

functions = {'a': function_1,
             'b': function_2,
             'c': self.method_1}

func = functions[value]
func()

Para invocar métodos en objetos, puede simplificar aún más utilizando getattr() incorporado para recuperar métodos con un nombre particular:

class MyVisitor:
    def visit_a(self):
        ...

    def dispatch(self, value):
        method_name = 'visit_' + str(value)
        method = getattr(self, method_name)
        method()

Se sugiere que utilice un prefijo para los nombres de los métodos, como visit_ en este ejemplo. Sin dicho prefijo, si los valores provienen de una fuente no confiable, un atacante podría invocar cualquier método en su objeto.

¿No puede emular hilos en el intérprete en lugar de confiar en una implementación de hilos específica del sistema operativo?

Respuesta 1: Desafortunadamente, el intérprete empuja al menos un marco de pila C para cada marco de pila de Python. Además, las extensiones pueden volver a llamar a Python en momentos casi aleatorios. Por lo tanto, una implementación completa de subprocesos requiere soporte de subprocesos para C.

Respuesta 2: Afortunadamente, existe Python sin pila [https://github.com/stackless-dev/stackless/wiki], que tiene un bucle de intérprete completamente rediseñado que evita la pila C.

¿Por qué las expresiones lambda no pueden contener sentencias?

Las expresiones lambda de Python no pueden contener declaraciones porque el marco sintáctico de Python no puede manejar declaraciones anidadas dentro de expresiones. Sin embargo, en Python, este no es un problema grave. A diferencia de las formas lambda en otros lenguajes, donde agregan funcionalidad, las lambdas de Python son solo una notación abreviada si eres demasiado vago para definir una función.

Las funciones ya son objetos de primera clase en Python y pueden declararse en un ámbito local. Por lo tanto, la única ventaja de usar una lambda en lugar de una función definida localmente es que no es necesario inventar un nombre para la función, sino que es solo una variable local para la cual el objeto de función (que es exactamente el mismo tipo de se asigna un objeto que produce una expresión lambda)

¿Se puede compilar Python en código máquina, C o algún otro lenguaje?

Cython [http://cython.org/] compila una versión modificada de Python con anotaciones opcionales en extensiones C. Nuitka [http://www.nuitka.net/] es un compilador prometedor de Python en código C ++, con el objetivo de soportar el lenguaje completo de Python. Para compilar en Java puede considerar VOC [https://voc.readthedocs.io].

¿Cómo gestiona Python la memoria?

Los detalles de la administración de memoria de Python dependen de la implementación. La implementación estándar de Python, CPython, utiliza el recuento de referencias para detectar objetos inaccesibles, y otro mecanismo para recopilar ciclos de referencia, ejecutando periódicamente un algoritmo de detección de ciclos que busca ciclos inaccesibles y elimina los objetos involucrados. El módulo gc proporciona funciones para realizar una recolección de basura, obtener estadísticas de depuración y ajustar los parámetros del recolector.

Sin embargo, otras implementaciones (como Jython [http://www.jython.org] o PyPy [http://www.pypy.org]) pueden confiar en un mecanismo diferente, como recolector de basura. Esta diferencia puede causar algunos problemas sutiles de portabilidad si su código de Python depende del comportamiento de la implementación de conteo de referencias.

En algunas implementaciones de Python, el siguiente código (que está bien en CPython) probablemente se quedará sin descriptores de archivo:

for file in very_long_list_of_files:
    f = open(file)
    c = f.read(1)

De hecho, utilizando el esquema de conteo de referencias y destructor de CPython, cada nueva asignación a f cierra el archivo anterior. Sin embargo, con un GC tradicional, esos objetos de archivo solo se recopilarán (y cerrarán) a intervalos variables y posiblemente largos.

Si desea escribir código que funcione con cualquier implementación de Python, debe cerrar explícitamente el archivo o utilizar una declaración with; esto funcionará independientemente del esquema de administración de memoria:

for file in very_long_list_of_files:
    with open(file) as f:
        c = f.read(1)

¿Por qué CPython no utiliza un esquema de recolección de basura más tradicional?

Por un lado, esta no es una característica estándar de C y, por lo tanto, no es portátil. (Sí, sabemos acerca de la biblioteca Boehm GC. Tiene fragmentos de código de ensamblador para la mayoría de las plataformas comunes, no para todas ellas, y aunque es principalmente transparente, no es completamente transparente; se requieren parches para obtener Python para trabajar con eso)

El GC tradicional también se convierte en un problema cuando Python está integrado en otras aplicaciones. Mientras que en un Python independiente está bien reemplazar el estándar malloc() y free() con versiones proporcionadas por la biblioteca GC, una aplicación que incruste Python puede querer tener su propio sustituto de malloc() y free(), y puede No quiero a Python. En este momento, CPython funciona con todo lo que implementa malloc() y free() correctamente.

¿Por qué no se libera toda la memoria cuando sale CPython?

Los objetos a los que se hace referencia desde los espacios de nombres globales de los módulos de Python no siempre se desasignan cuando Python sale. Esto puede suceder si hay referencias circulares. También hay ciertos bits de memoria asignados por la biblioteca de C que son imposibles de liberar (por ejemplo, una herramienta como Purify se quejará de estos). Python es, sin embargo, agresivo sobre la limpieza de la memoria al salir e intenta destruir cada objeto.

Si desea forzar a Python a eliminar ciertas cosas en la desasignación, use el módulo atexit para ejecutar una función que obligará a esas eliminaciones.

¿Por qué hay tipos de datos separados de tuplas y listas?

Las listas y las tuplas, si bien son similares en muchos aspectos, generalmente se usan de maneras fundamentalmente diferentes. Se puede pensar que las tuplas son similares a los registros Pascal o estructuras C; son pequeñas colecciones de datos relacionados que pueden ser de diferentes tipos que funcionan como un grupo. Por ejemplo, una coordenada cartesiana se representa adecuadamente como una tupla de dos o tres números.

Las listas, por otro lado, son más como matrices en otros lenguajes. Tienden a contener un número variable de objetos, todos los cuales tienen el mismo tipo y que se operan uno por uno. Por ejemplo, os.listdir('.') Retorna una lista de cadenas de caracteres que representan los archivos en el directorio actual. Las funciones que operan en esta salida generalmente no se romperían si agregara otro archivo o dos al directorio.

Las tuplas son inmutables, lo que significa que una vez que se ha creado una tupla, no puede reemplazar ninguno de sus elementos con un nuevo valor. Las listas son mutables, lo que significa que siempre puede cambiar los elementos de una lista. Solo los elementos inmutables se pueden usar como claves de diccionario y, por lo tanto, solo las tuplas y no las listas se pueden usar como claves.

¿Cómo se implementan las listas en Python?

Las listas de CPython son realmente matrices de longitud variable, no listas enlazadas al estilo Lisp. La implementación utiliza una matriz contigua de referencias a otros objetos y mantiene un puntero a esta matriz y la longitud de la matriz en una estructura de encabezado de lista.

Esto hace que indexar una lista a[i] una operación cuyo costo es independiente del tamaño de la lista o del valor del índice.

Cuando se añaden o insertan elementos, la matriz de referencias cambia de tamaño. Se aplica cierta inteligencia para mejorar el rendimiento de la adición de elementos repetidamente; cuando la matriz debe crecer, se asigna un espacio extra para que las próximas veces no requieran un cambio de tamaño real.

¿Cómo se implementan los diccionarios en CPython?

Los diccionarios de CPython se implementan como tablas hash redimensionables. En comparación con los árboles B (B-trees), esto proporciona un mejor rendimiento para la búsqueda (la operación más común con diferencia) en la mayoría de las circunstancias, y la implementación es más simple.

Los diccionarios funcionan calculando un código hash para cada clave almacenada en el diccionario utilizando la función incorporada hash(). El código hash varía ampliamente según la clave y una semilla por proceso; por ejemplo, «Python» podría dividir en hash a -539294296 mientras que «python», una cadena que difiere en un solo bit, podría dividir en 1142331976. El código de resumen se usa para calcular una ubicación en una matriz interna donde se almacenará el valor . Suponiendo que está almacenando claves que tienen valores hash diferentes, esto significa que los diccionarios toman tiempo constante – O(1), en notación Big-O – para recuperar una clave.

¿Por qué las claves del diccionario deben ser inmutables?

La implementación de la tabla hash de los diccionarios utiliza un valor hash calculado a partir del valor clave para encontrar la clave. Si la clave fuera un objeto mutable, su valor podría cambiar y, por lo tanto, su hash también podría cambiar. Pero dado que quien cambie el objeto clave no puede decir que se estaba utilizando como clave de diccionario, no puede mover la entrada en el diccionario. Luego, cuando intente buscar el mismo objeto en el diccionario, no se encontrará porque su valor hash es diferente. Si trató de buscar el valor anterior, tampoco lo encontraría, porque el valor del objeto que se encuentra en ese hash bin sería diferente.

Si desea un diccionario indexado con una lista, simplemente convierta la lista a una tupla primero; La función tuple(L) crea una tupla con las mismas entradas que la lista L. Las tuplas son inmutables y, por lo tanto, pueden usarse como claves de diccionario.

Algunas soluciones inaceptables que se han propuesto:

Listas de hash por su dirección (ID de objeto). Esto no funciona porque si construye una nueva lista con el mismo valor, no se encontrará; por ejemplo:

mydict = {[1, 2]: '12'}
print(mydict[[1, 2]])

generaría una excepción KeyError porque la identificación del [1, 2] usado en la segunda línea difiere de la de la primera línea. En otras palabras, las claves del diccionario deben compararse usando ==, no usando is.

Hacer una copia cuando use una lista como clave. Esto no funciona porque la lista, al ser un objeto mutable, podría contener una referencia a sí misma, y luego el código de copia se ejecutaría en un bucle infinito.

Permitir listas como claves pero decirle al usuario que no las modifique. Esto permitiría una clase de errores difíciles de rastrear en los programas cuando olvidó o modificó una lista por accidente. También invalida una invariante importante de diccionarios: cada valor en d.keys() se puede usar como una clave del diccionario.

Marcar las listas como de solo lectura una vez que se usan como clave de diccionario. El problema es que no solo el objeto de nivel superior puede cambiar su valor; podría usar una tupla que contiene una lista como clave. Ingresar cualquier cosa como clave en un diccionario requeriría marcar todos los objetos accesibles desde allí como de solo lectura – y nuevamente, los objetos autoreferenciados podrían causar un bucle infinito.

Hay un truco para evitar esto si lo necesita, pero úselo bajo su propio riesgo: puede envolver una estructura mutable dentro de una instancia de clase que tenga un método __eq__() y a __hash__() . Luego debe asegurarse de que el valor hash para todos los objetos de contenedor que residen en un diccionario (u otra estructura basada en hash) permanezca fijo mientras el objeto está en el diccionario (u otra estructura).

class ListWrapper:
    def __init__(self, the_list):
        self.the_list = the_list

    def __eq__(self, other):
        return self.the_list == other.the_list

    def __hash__(self):
        l = self.the_list
        result = 98767 - len(l)*555
        for i, el in enumerate(l):
            try:
                result = result + (hash(el) % 9999999) * 1001 + i
            except Exception:
                result = (result % 7777777) + i * 333
        return result

Tenga en cuenta que el cálculo de hash se complica por la posibilidad de que algunos miembros de la lista sean inquebrantables y también por la posibilidad de desbordamiento aritmético.

Además, siempre debe darse el caso de que si o1 == o2 (es decir, o1.__eq__(o2) is True), entonces hash(o1) == hash(o2) (es decir, o1.__hash__() == o2.__hash__()), independientemente de si el objeto está en un diccionario o no. Si no cumple con estas restricciones, los diccionarios y otras estructuras basadas en hash se comportarán mal.

En el caso de ListWrapper, siempre que el objeto contenedor esté en un diccionario, la lista ajustada no debe cambiar para evitar anomalías. No haga esto a menos que esté preparado para pensar detenidamente sobre los requisitos y las consecuencias de no cumplirlos correctamente. Considérese advertido.

¿Por qué list.sort() no retorna la lista ordenada?

En situaciones donde el rendimiento es importante, hacer una copia de la lista solo para ordenarlo sería un desperdicio. Por lo tanto, list.sort() ordena la lista en su lugar. Para recordarle ese hecho, no retorna la lista ordenada. De esta manera, no se dejará engañar por sobreescribir accidentalmente una lista cuando necesite una copia ordenada, pero también deberá mantener la versión sin ordenar.

Si desea retornar una nueva lista, use la función incorporada sorted() en su lugar. Esta función crea una nueva lista a partir de un iterativo proporcionado, la ordena y la retorna. Por ejemplo, a continuación se explica cómo iterar sobre las teclas de un diccionario en orden ordenado:

for key in sorted(mydict):
    ...  # do whatever with mydict[key]...

¿Cómo se especifica y aplica una especificación de interfaz en Python?

Una especificación de interfaz para un módulo proporcionada por lenguajes como C++ y Java describe los prototipos para los métodos y funciones del módulo. Muchos sienten que la aplicación en tiempo de compilación de las especificaciones de la interfaz ayuda en la construcción de grandes programas.

Python 2.6 agrega un módulo abc que le permite definir clases base abstractas (ABC). Luego puede usar isinstance() y issubclass() para verificar si una instancia o una clase implementa un ABC en particular. El módulo collections.abc define un conjunto de ABC útiles como Iterable, Container y MutableMapping.

Para Python, muchas de las ventajas de las especificaciones de interfaz se pueden obtener mediante una disciplina de prueba adecuada para los componentes.

Un buen conjunto de pruebas para un módulo puede proporcionar una prueba de regresión y servir como una especificación de interfaz de módulo y un conjunto de ejemplos. Muchos módulos de Python se pueden ejecutar como un script para proporcionar una simple «autocomprobación». Incluso los módulos que usan interfaces externas complejas a menudo se pueden probar de forma aislada utilizando emulaciones triviales de «stub» de la interfaz externa. Los módulos doctest y unittest o marcos de prueba de terceros se pueden utilizar para construir conjuntos de pruebas exhaustivas que ejercitan cada línea de código en un módulo.

Una disciplina de prueba adecuada puede ayudar a construir grandes aplicaciones complejas en Python, así como tener especificaciones de interfaz. De hecho, puede ser mejor porque una especificación de interfaz no puede probar ciertas propiedades de un programa. Por ejemplo, se espera que el método append() agregue nuevos elementos al final de alguna lista interna; una especificación de interfaz no puede probar que su implementación append() realmente haga esto correctamente, pero es trivial verificar esta propiedad en un conjunto de pruebas.

Escribir conjuntos de pruebas es muy útil, y es posible que desee diseñar su código con miras a que sea fácilmente probado. Una técnica cada vez más popular, el desarrollo dirigido por pruebas, requiere escribir partes del conjunto de pruebas primero, antes de escribir el código real. Por supuesto, Python te permite ser descuidado y no escribir casos de prueba.

¿Por qué no hay goto?

En la década de 1970, la gente se dio cuenta de que el goto irrestricto podía generar un código «espagueti» desordenado que era difícil de entender y revisar. En un lenguaje de alto nivel, también es innecesario siempre que haya formas de bifurcar (en Python, con declaraciones if y expresiones or, and e if-else) y repetir (con declaraciones while y for, que posiblemente contengan continue y break).

Puede usar excepciones para proporcionar un «goto estructurado» que incluso funciona en llamadas a funciones. Muchos creen que las excepciones pueden emular convenientemente todos los usos razonables de los constructos «go» o «goto» de C, Fortran y otros lenguajes. Por ejemplo:

class label(Exception): pass  # declare a label

try:
    ...
    if condition: raise label()  # goto label
    ...
except label:  # where to goto
    pass
...

Esto no le permite saltar a la mitad de un bucle, pero de todos modos eso generalmente se considera un abuso de goto. Utilizar con moderación.

¿Por qué las cadenas de caracteres sin formato (r-strings) no pueden terminar con una barra diagonal inversa?

Más precisamente, no pueden terminar con un número impar de barras invertidas: la barra invertida no emparejada al final escapa el carácter de comillas de cierre, dejando una cadena sin terminar.

Las cadenas de caracteres sin formato se diseñaron para facilitar la creación de entradas para procesadores (principalmente motores de expresión regular) que desean realizar su propio procesamiento de escape de barra invertida. Tales procesadores consideran que una barra invertida sin par es un error de todos modos, por lo que las cadenas de caracteres sin procesar no lo permiten. A cambio, le permiten pasar el carácter de comillas de cadena escapándolo con una barra invertida. Estas reglas funcionan bien cuando las cadenas de caracteres r (r-strings) se usan para el propósito previsto.

Si está intentando construir nombres de ruta de Windows, tenga en cuenta que todas las llamadas al sistema de Windows también aceptan barras diagonales:

f = open("/mydir/file.txt")  # works fine!

Si está tratando de construir una ruta para un comando de DOS, intente por ejemplo uno de los siguientes:

dir = r"\this\is\my\dos\dir" "\\"
dir = r"\this\is\my\dos\dir\ "[:-1]
dir = "\\this\\is\\my\\dos\\dir\\"

¿Por qué Python no tiene una declaración «with» para las asignaciones de atributos?

Python tiene una declaración “with” que envuelve la ejecución de un bloque, llamando al código en la entrada y salida del bloque. Algunos lenguajes tienen una construcción que se ve así:

with obj:
    a = 1               # equivalent to obj.a = 1
    total = total + 1   # obj.total = obj.total + 1

En Python, tal construcción sería ambigua.

Otros lenguajes, como Object Pascal, Delphi y C ++, utilizan tipos estáticos, por lo que es posible saber, de manera inequívoca, a qué miembro se le está asignando. Este es el punto principal de la escritura estática: el compilador siempre conoce el alcance de cada variable en tiempo de compilación.

Python usa tipos dinámicos. Es imposible saber de antemano a qué atributo se hará referencia en tiempo de ejecución. Los atributos de los miembros pueden agregarse o eliminarse de los objetos sobre la marcha. Esto hace que sea imposible saber, a partir de una simple lectura, a qué atributo se hace referencia: ¿uno local, uno global o un atributo miembro?

Por ejemplo, tome el siguiente fragmento incompleto:

def foo(a):
    with a:
        print(x)

El fragmento supone que «a» debe tener un atributo miembro llamado «x». Sin embargo, no hay nada en Python que le diga esto al intérprete. ¿Qué debería suceder si «a» es, digamos, un número entero? Si hay una variable global llamada «x», ¿se usará dentro del bloque with? Como puede ver, la naturaleza dinámica de Python hace que tales elecciones sean mucho más difíciles.

Sin embargo, el beneficio principal de «with» y características de lenguaje similares (reducción del volumen del código) se puede lograr fácilmente en Python mediante la asignación. En vez de:

function(args).mydict[index][index].a = 21
function(args).mydict[index][index].b = 42
function(args).mydict[index][index].c = 63

escribe esto:

ref = function(args).mydict[index][index]
ref.a = 21
ref.b = 42
ref.c = 63

Esto también tiene el efecto secundario de aumentar la velocidad de ejecución porque los enlaces de nombres se resuelven en tiempo de ejecución en Python, y la segunda versión solo necesita realizar la resolución una vez.

Why don’t generators support the with statement?

For technical reasons, a generator used directly as a context manager would not work correctly. When, as is most common, a generator is used as an iterator run to completion, no closing is needed. When it is, wrap it as «contextlib.closing(generator)» in the “with” statement.

¿Por qué se requieren dos puntos para las declaraciones if/while/def/class?

Los dos puntos se requieren principalmente para mejorar la legibilidad (uno de los resultados del lenguaje ABC experimental). Considera esto:

if a == b
    print(a)

versus

if a == b:
    print(a)

Observe cómo el segundo es un poco más fácil de leer. Observe más a fondo cómo los dos puntos establecen el ejemplo en esta respuesta de preguntas frecuentes; Es un uso estándar en inglés.

Otra razón menor es que los dos puntos facilitan a los editores con resaltado de sintaxis; pueden buscar dos puntos para decidir cuándo se debe aumentar la indentación en lugar de tener que hacer un análisis más elaborado del texto del programa.

¿Por qué Python permite comas al final de las listas y tuplas?

Python le permite agregar una coma final al final de las listas, tuplas y diccionarios:

[1, 2, 3,]
('a', 'b', 'c',)
d = {
    "A": [1, 5],
    "B": [6, 7],  # last trailing comma is optional but good style
}

Hay varias razones para permitir esto.

Cuando tiene un valor literal para una lista, tupla o diccionario distribuido en varias líneas, es más fácil agregar más elementos porque no tiene que recordar agregar una coma a la línea anterior. Las líneas también se pueden reordenar sin crear un error de sintaxis.

La omisión accidental de la coma puede ocasionar errores difíciles de diagnosticar. Por ejemplo:

x = [
  "fee",
  "fie"
  "foo",
  "fum"
]

Parece que esta lista tiene cuatro elementos, pero en realidad contiene tres: «fee», «fiefoo» y «fum». Agregar siempre la coma evita esta fuente de error.

Permitir la coma final también puede facilitar la generación de código programático.

Preguntas frecuentes sobre bibliotecas y extensiones

Contenido

Preguntas frecuentes sobre bibliotecas y extensiones

Cuestiones generales sobre bibliotecas

¿Cómo encuentro un módulo o aplicación para ejecutar la tarea X?

¿Dónde está el fichero fuente math.py (socket.py, regex.py, etc.)?

¿Cómo hago ejecutable un script Python en Unix?

¿Hay un paquete curses/termcap para Python?

¿Hay un equivalente en Python al onexit() de C?

¿Por qué no funcionan mis manejadores de señales?

Tareas comunes

¿Cómo pruebo un programa o un componente Python?

¿Cómo creo documentación a partir de los docstrings?

¿Cómo consigo presionar una única tecla cada vez?

Hilos

¿Cómo programo usando hilos?

Ninguno de mis hilos parece funcionar: ¿por qué?

¿Cómo puedo dividir trabajo entre un grupo de hilos?

¿Qué tipos de mutación de valores globales son thread-safe?

¿Podemos deshacernos del Global Interpreter Lock?

Entrada y Salida

¿Cómo borro un fichero? (Y otras preguntas sobre ficheros…)

¿Cómo copio un fichero?

¿Cómo leo (o escribo) datos binarios?

No consigo usar os.read() en un pipe creado con os.popen(); ¿por qué?

¿Cómo accedo al puerto serial (RS232)?

¿Por qué al cerrar sys.stdout (stdin, stderr) realmente no se cierran?

Programación de Redes/Internet

¿Qué herramientas de Python existen para WWW?

¿Cómo puedo imitar un envío de formulario CGI (METHOD=POST)?

¿Qué modulo debería usar para generación de HTML?

¿Cómo envío correo desde un script Python?

¿Cómo evito el bloqueo en el método connect() de un socket?

Bases de datos

¿Hay paquetes para interfaces a bases de datos en Python?

¿Cómo implementar objetos persistentes en Python?

Matemáticas y Numérica

¿Cómo genero números aleatorios en Python?

Cuestiones generales sobre bibliotecas

¿Cómo encuentro un módulo o aplicación para ejecutar la tarea X?

Vea la referencia de bibliotecas para comprobar si existe un módulo relevante en la biblioteca estándar. (Eventualmente aprenderá lo que hay en la biblioteca estándar y será capaz de saltarse este paso.)

Para los paquetes de terceros, busque en el Índice de Paquetes de Python [https://pypi.org] o pruebe Google [https://www.google.com] u otro motor de búsqueda. Buscando por «Python» más una o dos palabras clave del tema de interés, generalmente encontrará algo útil.

¿Dónde está el fichero fuente math.py (socket.py, regex.py, etc.)?

Si no puede encontrar un fichero fuente para un módulo, puede ser un módulo incorporado o cargado dinámicamente implementado en C, C++ u otro lenguaje compilado. En este caso puede no disponer del fichero fuente o puede ser algo como mathmodule.c, en algún lugar de un directorio fuente C (fuera del Python Path).

Hay (al menos) tres tipos de módulos en Python:

módulos escritos en Python (.py);

módulos escritos en C y cargados dinámicamente (.dll, .pyd, .so, .sl, etc.);

módulos escritos en C y enlazados con el intérprete; para obtener una lista de estos, escriba:

import sys
print(sys.builtin_module_names)

¿Cómo hago ejecutable un script Python en Unix?

Necesita hacer dos cosas: el modo del fichero del script debe ser ejecutable y la primera línea debe comenzar con #! seguido de la ruta al intérprete de Python.

Lo primero se hace ejecutando chmod +x scriptfile o bien chmod 755 scriptfile.

Lo segundo se puede hacer de distintas maneras. La manera más directa es escribir

#!/usr/local/bin/python

en la primera línea de su fichero, usando la ruta donde está instalado el intérprete de Python en su plataforma.

Si quiere que el script sea independiente de donde se ubique el intérprete de Python, puede usar el programa env. Casi todas las variantes de Unix soportan lo siguiente, asumiendo que el intérprete de Python está en un directorio del PATH de usuario:

#!/usr/bin/env python

No haga esto para scripts CGI. La variable PATH para scripts CGI es mínima, así que necesita usar la ruta real absoluta al intérprete.

Ocasionalmente, un entorno de usuario está tan lleno que el programa /usr/bin/env falla; o bien no existe el programa env. En ese caso, puede intentar el siguiente truco (gracias a Alex Rezinsky):

#! /bin/sh
""":"
exec python $0 ${1+"$@"}
"""

Una pequeña desventaja es que esto define el __doc__ del script. Sin embargo, puede arreglarlo añadiendo

__doc__ = """...Whatever..."""

¿Hay un paquete curses/termcap para Python?

Para variantes Unix: La distribución estándar de Python viene con un módulo curses en el subdirectorio Modules [https://github.com/python/cpython/tree/3.9/Modules], aunque no está compilado por defecto. (Nótese que esto no está disponible en la distribución Windows — no hay módulo curses para Windows.)

El módulo curses soporta características básicas de cursores así como muchas funciones adicionales de ncurses y cursores SYSV como color, soporte para conjuntos de caracteres alternativos, pads, y soporte para ratón. Esto significa que el módulo no es compatible con sistemas operativos que sólo tienen cursores BSD, pero no parece que ningún sistema operativo actualmente mantenido caiga dentro de esta categoría.

¿Hay un equivalente en Python al onexit() de C?

El módulo atexit proporciona una función de registro que es similar a onexit() de C.

¿Por qué no funcionan mis manejadores de señales?

El problema más común es que el manejador de señales esté declarado con la lista incorrecta de argumentos. Se llama como

handler(signum, frame)

así que debería declararse con dos argumentos:

def handler(signum, frame):
    ...

Tareas comunes

¿Cómo pruebo un programa o un componente Python?

Python viene con dos frameworks de testing. El módulo doctest encuentra ejemplos en los docstrings para un módulo y los ejecuta, comparando la salida con la salida esperada especificada en la cadena de documentación.

El módulo unittest es un framework de testing más agradable y modelado sobre los frameworks de testing de Java y Smalltalk.

Para hacer más fácil el testing, debería usar un buen diseño modular en su programa. Su programa debería tener casi toda la funcionalidad encapsulada en funciones o en métodos de clases — y esto algunas veces tiene el efecto sorprendente y encantador de que su programa funcione más rápido (porque los accesos a las variables locales son más rápidas que los accesos a las variables globales). Además el programa debería evitar depender de la mutación de variables globales, ya que esto dificulta mucho más hacer el testing.

La «lógica global principal» de su programa puede ser tan simple como

if __name__ == "__main__":
    main_logic()

al final del módulo principal de su programa.

Una vez que su programa esté organizado en una colección manejable de funciones y comportamientos de clases, usted debería escribir funciones de comprobación que ejerciten los comportamientos. Se puede asociar un conjunto de pruebas a cada módulo. Esto suena a mucho trabajo, pero gracias a que Python es tan conciso y flexible, se hace sorprendentemente fácil. Puede codificar de manera mucho más agradable y divertida escribiendo funciones de comprobación en paralelo con el «código de producción», ya que esto facilita encontrar antes errores e incluso fallos de diseño.

Los «módulos de soporte» que no tienen la intención de estar en el módulo principal de un programa pueden incluir un auto test del módulo.

if __name__ == "__main__":
    self_test()

Incluso los programas que interactúan con interfaces externas complejas se pueden comprobar cuando las interfaces externas no están disponibles usando interfaces «simuladas» implementadas en Python.

¿Cómo creo documentación a partir de los docstrings?

El módulo pydoc puede crear HTML desde los docstrings existentes en su código fuente Python. Una alternativa para crear documentación API estrictamente desde docstrings es epydoc [http://epydoc.sourceforge.net/]. Sphinx [http://sphinx-doc.org] también puede incluir contenido docstring.

¿Cómo consigo presionar una única tecla cada vez?

Para variantes Unix hay varias soluciones. Lo más directo es hacerlo usando cursores, pero curses es un módulo bastante amplio para aprenderlo.

Hilos

¿Cómo programo usando hilos?

Asegúrese de usar el módulo threading y no el módulo _thread. El módulo threading construye abstracciones convenientes sobre las primitivas de bajo nivel proporcionadas por el módulo _thread.

Ninguno de mis hilos parece funcionar: ¿por qué?

Tan pronto como el hilo principal termine, se matan todos los hilos. Su hilo principal está corriendo demasiado rápido, sin dar tiempo a los hilos para hacer algún trabajo.

Una solución sencilla es añadir un sleep al final del programa que sea suficientemente largo para que todos los hilos terminen:

import threading, time

def thread_task(name, n):
    for i in range(n):
        print(name, i)

for i in range(10):
    T = threading.Thread(target=thread_task, args=(str(i), i))
    T.start()

time.sleep(10)  # <---------------------------!

Por ahora (en muchas plataformas) los hilos no corren en paralelo, sino que parece que corren secuencialmente, ¡uno a la vez! La razón es que el planificador de hilos del sistema operativo no inicia un nuevo hilo hasta que el hilo anterior está bloqueado.

Una solución sencilla es añadir un pequeño sleep al comienzo de la función run:

def thread_task(name, n):
    time.sleep(0.001)  # <--------------------!
    for i in range(n):
        print(name, i)

for i in range(10):
    T = threading.Thread(target=thread_task, args=(str(i), i))
    T.start()

time.sleep(10)

En vez de intentar adivinar un valor de retardo adecuado para time.sleep(), es mejor usar algún tipo de mecanismo de semáforo. Una idea es usar el módulo queue para crear un objeto cola, permitiendo que cada hilo añada un token a la cola cuando termine, y permitiendo al hilo principal leer tantos tokens de la cola como hilos haya.

¿Cómo puedo dividir trabajo entre un grupo de hilos?

La manera más fácil es usar el nuevo módulo concurrent.futures, especialmente el módulo ThreadPoolExecutor.

O, si quiere tener un control más preciso sobre el algoritmo de despacho, puede escribir su propia lógica manualmente. Use el módulo queue para crear una cola que contenga una lista de trabajos. La clase Queue mantiene una lista de objetos y tiene un método .put(obj) que añade elementos a la cola y un método .get() que los retorna. Esta clase se encargará de los bloqueos necesarios para asegurar que cada trabajo se reparte exactamente una vez.

Aquí hay un ejemplo trivial:

import threading, queue, time

# The worker thread gets jobs off the queue.  When the queue is empty, it
# assumes there will be no more work and exits.
# (Realistically workers will run until terminated.)
def worker():
    print('Running worker')
    time.sleep(0.1)
    while True:
        try:
            arg = q.get(block=False)
        except queue.Empty:
            print('Worker', threading.currentThread(), end=' ')
            print('queue empty')
            break
        else:
            print('Worker', threading.currentThread(), end=' ')
            print('running with argument', arg)
            time.sleep(0.5)

# Create queue
q = queue.Queue()

# Start a pool of 5 workers
for i in range(5):
    t = threading.Thread(target=worker, name='worker %i' % (i+1))
    t.start()

# Begin adding work to the queue
for i in range(50):
    q.put(i)

# Give threads time to run
print('Main thread sleeping')
time.sleep(5)

Cuando se ejecute, esto producirá la siguiente salida:

Running worker
Running worker
Running worker
Running worker
Running worker
Main thread sleeping
Worker <Thread(worker 1, started 130283832797456)> running with argument 0
Worker <Thread(worker 2, started 130283824404752)> running with argument 1
Worker <Thread(worker 3, started 130283816012048)> running with argument 2
Worker <Thread(worker 4, started 130283807619344)> running with argument 3
Worker <Thread(worker 5, started 130283799226640)> running with argument 4
Worker <Thread(worker 1, started 130283832797456)> running with argument 5
...

Consulte la documentación del módulo para más detalles; la clase Queue proporciona una interfaz llena de características.

¿Qué tipos de mutación de valores globales son thread-safe?

Un global interpreter lock (GIL) se usa internamente para asegurar que sólo un hilo corre a la vez en la VM de Python. En general, Python ofrece cambiar entre hilos sólo en instrucciones bytecode; la frecuencia con la que cambia se puede fijar vía sys.setswitchinterval(). Cada instrucción bytecode y por lo tanto, toda la implementación de código C alcanzada por cada instrucción, es atómica desde el punto de vista de un programa Python.

En teoría, esto significa que un informe exacto requiere de un conocimiento exacto de la implementación en bytecode de la PVM. En la práctica, esto significa que las operaciones entre variables compartidas de tipos de datos built-in (enteros, listas, diccionarios, etc.) que «parecen atómicas» realmente lo son.

Por ejemplo, las siguientes operaciones son todas atómicas (L, L1, L2 son listas, D, D1, D2 son diccionarios, x, y son objetos, i, j son enteros):

L.append(x)
L1.extend(L2)
x = L[i]
x = L.pop()
L1[i:j] = L2
L.sort()
x = y
x.field = y
D[x] = y
D1.update(D2)
D.keys()

Estas no lo son:

i = i+1
L.append(L[-1])
L[i] = L[j]
D[x] = D[x] + 1

Las operaciones que reemplazan otros objetos pueden invocar el método __del__() de esos otros objetos cuando su número de referencias alcance cero, y eso puede afectar a otras cosas. Esto es especialmente cierto para las actualizaciones en masa de diccionarios y listas. Cuando se esté en duda, ¡use un mutex!

¿Podemos deshacernos del Global Interpreter Lock?

El global interpreter lock (GIL) se percibe a menudo como un obstáculo en el despliegue de Python sobre máquinas servidoras finales de múltiples procesadores, porque un programa Python multihilo efectivamente sólo usa una CPU, debido a la exigencia de que (casi) todo el código Python sólo puede correr mientras el GIL esté activado.

En los días de Python 1.5, Greg Stein de hecho implementó un conjunto amplio de parches (los parches «libres de hilo») que eliminaba el GIL y lo reemplazaba con un bloqueo de grano fino. Adam Olsen hizo recientemente un experimento similar con su proyecto python-safethread [https://code.google.com/archive/p/python-safethread]. Desafortunadamente, ambos experimentos mostraron una aguda caída en el rendimiento (al menos del 30% o más baja), debido a la cantidad de bloqueos de grano fino necesarios para compensar la eliminación del GIL.

¡Esto no significa que no pueda hacer buen uso de Python en máquinas de múltiples CPU! Usted sólo tiene que ser creativo a la hora de dividir el trabajo entre múltiples procesos en vez de entre múltiples hilos. La clase ProcessPoolExecutor del nuevo módulo concurrent.futures proporciona una manera sencilla de hacer esto; el módulo multiprocessing proporciona una API de bajo nivel en caso de que se quiera tener un mayor control sobre el despacho de las tareas.

El uso sensato de extensiones C también ayudará; si usa una extensión C para ejecutar una tarea que consume mucho tiempo, la extensión puede liberar al GIL mientras el hilo de ejecución esté en el código C y permite a otros hilos hacer trabajo. Algunos módulos de la biblioteca estándar tales como zlib y hashlib ya lo hacen.

Se ha sugerido que el GIL debería ser un bloqueo por estado de intérprete, en vez de realmente global; luego los intérpretes no serían capaces de compartir objetos. Desafortunadamente, esto tampoco es probable que ocurra. Sería una tremenda cantidad de trabajo, porque muchas implementaciones de objetos actualmente tienen un estado global. Por ejemplo, los enteros pequeños y las cadenas pequeñas están cacheadas; estas caches se tendrían que mover al estado del intérprete. Otros tipos de objetos tienen su propia lista libre; estas listas libres se tendrían que mover al estado del intérprete. Y así sucesivamente.

Y dudo de si se puede hacer en tiempo finito, porque el mismo problema existe para extensiones de terceros. Es probable que las extensiones de terceros se escriban más rápido de lo que se puedan convertir para almacenar todo su estado global en el estado del intérprete.

Y finalmente, una vez que tenga múltiples intérpretes sin compartir ningún estado, ¿qué habrá ganado sobre correr cada intérprete en un proceso separado?

Entrada y Salida

¿Cómo borro un fichero? (Y otras preguntas sobre ficheros…)

Use os.remove(filename) o os.unlink(filename); para la documentación, vea el módulo os. Las dos funciones son idénticas; unlink() es simplemente el nombre de la llamada al sistema UNIX para esta función.

Para borrar un directorio, use os.rmdir(); use os.mkdir() para crear uno. os.makedirs(path) creará cualquier directorio intermedio que no exista en path. os.removedirs(path) borrará los directorios intermedios siempre y cuando estén vacíos; si quiere borrar un árbol de directorios completo y sus contenidos, use shutil.rmtree().

Para renombrar un fichero, use os.rename(old_path, new_path).

Para truncar un fichero, ábralo usando f = open(filename, "rb+"), y use f.truncate(offset); el desplazamiento toma por defecto la posición actual de búsqueda. También existe os.ftruncate(fd, offset) para ficheros abiertos con os.open(), donde fd es el descriptor del fichero (un entero pequeño).

El módulo shutil también contiene distintas funciones para trabajar con ficheros incluyendo copyfile(), copytree() y rmtree().

¿Cómo copio un fichero?

El módulo shutil contiene una función copyfile(). Nótese que en MacOS 9 no copia el fork del recurso ni la información de Finder.

¿Cómo leo (o escribo) datos binarios?

Para leer o escribir formatos binarios de datos complejos, es mejor usar el módulo struct. Esto le permite tomar una cadena de texto que contiene datos binarios (normalmente números) y convertirla a objetos de Python; y viceversa.

Por ejemplo, el siguiente código lee de un fichero dos enteros de 2-bytes y uno de 4-bytes en formato big-endian:

import struct

with open(filename, "rb") as f:
    s = f.read(8)
    x, y, z = struct.unpack(">hhl", s)

El “>” en la cadena de formato fuerza los datos a big-endian; la letra “h” lee un «entero corto» (2 bytes), y “l” lee un «entero largo» (4 bytes) desde la cadena de texto.

Para datos que son más regulares (por ejemplo una lista homogénea de enteros o flotantes), puede también usar el módulo array.

Nota

Para leer y escribir datos binarios, es obligatorio abrir el fichero en modo binario (aquí, pasando "rb" a open()). Si, en cambio, usa "r" (por defecto), el fichero se abrirá en modo texto y f.read() retornará objetos str en vez de objetos bytes.

No consigo usar os.read() en un pipe creado con os.popen(); ¿por qué?

os.read() es una función de bajo nivel que recibe un descriptor de fichero, un entero pequeño representando el fichero abierto. os.popen() crea un objeto fichero de alto nivel, el mismo tipo que retorna la función built-in open(). Así, para leer n bytes de un pipe p creado con os.popen(), necesita usar p.read(n).

¿Cómo accedo al puerto serial (RS232)?

For Win32, OSX, Linux, BSD, Jython, IronPython:

https://pypi.org/project/pyserial/

Para Unix, vea una publicación Usenet de Mitch Chapman:

https://groups.google.com/groups?selm=34A04430.CF9@ohioee.com

¿Por qué al cerrar sys.stdout (stdin, stderr) realmente no se cierran?

Los objetos de tipo fichero en Python son una capa de abstracción de alto nivel sobre los descriptores de ficheros de bajo nivel de C.

Para la mayoría de objetos de tipo fichero que cree en Python vía la función built-in open(), f.close() marca el objeto de tipo fichero Python como ya cerrado desde el punto de vista de Python, y también ordena el cierre del descriptor de fichero subyacente en C. Esto además ocurre automáticamente en el destructor de f, cuando f se convierte en basura.

Pero stdin, stdout y stderr se tratan de manera especial en Python, debido a un estatus especial que también tienen en C. Ejecutando sys.stdout.close() marca el objeto fichero de nivel Python para ser cerrado, pero no cierra el descriptor de fichero asociado en C.

Para cerrar el descriptor de fichero subyacente en C para uno de estos tres casos, debería primero asegurarse de que eso es realmente lo que quiere hacer (por ejemplo, puede confundir módulos de extensión intentado hacer I/O). Si es así, use os.close():

os.close(stdin.fileno())
os.close(stdout.fileno())
os.close(stderr.fileno())

O puede usar las constantes numéricas 0, 1 y 2, respectivamente.

Programación de Redes/Internet

¿Qué herramientas de Python existen para WWW?

Vea los capítulos titulados Protocolos y soporte de Internet y Manejo de Datos de Internet en el manual de referencia de bibliotecas. Python tiene muchos módulos que le ayudarán a construir sistemas web del lado del servidor y del lado del cliente.

Paul Boddie mantiene un resumen de los frameworks disponibles en https://wiki.python.org/moin/WebProgramming.

Cameron Laird mantiene un conjunto útil de páginas sobre tecnologías web Python en http://phaseit.net/claird/comp.lang.python/web_python.

¿Cómo puedo imitar un envío de formulario CGI (METHOD=POST)?

Me gustaría recuperar páginas web que son resultado del envío de un formulario. ¿Existe algún código que me permita hacer esto fácilmente?

Sí. Aquí hay un ejemplo sencillo que usa urllib.request:

#!/usr/local/bin/python

import urllib.request

# build the query string
qs = "First=Josephine&MI=Q&Last=Public"

# connect and send the server a path
req = urllib.request.urlopen('http://www.some-server.out-there'
                             '/cgi-bin/some-cgi-script', data=qs)
with req:
    msg, hdrs = req.read(), req.info()

Nótese que para operaciones POST de tipo percent-encoded, las cadenas de consulta tienen que estar entrecomilladas usando urllib.parse.urlencode(). Por ejemplo, para enviar name=Guy Steele, Jr.:

>>> import urllib.parse
>>> urllib.parse.urlencode({'name': 'Guy Steele, Jr.'})
'name=Guy+Steele%2C+Jr.'

Ver también

HOWTO - Cómo obtener recursos de Internet con el paquete urllib para ejemplos más detallados.

¿Qué modulo debería usar para generación de HTML?

Puede encontrar una colección de enlaces útiles en la página wiki de programación web [https://wiki.python.org/moin/WebProgramming].

¿Cómo envío correo desde un script Python?

Use el módulo smtplib de la biblioteca estándar.

Aquí hay un remitente simple interactivo que lo usa. Este método trabajará en cualquier máquina que soporte un listener SMTP.

import sys, smtplib

fromaddr = input("From: ")
toaddrs  = input("To: ").split(',')
print("Enter message, end with ^D:")
msg = ''
while True:
    line = sys.stdin.readline()
    if not line:
        break
    msg += line

# The actual mail send
server = smtplib.SMTP('localhost')
server.sendmail(fromaddr, toaddrs, msg)
server.quit()

Una alternativa sólo para UNIX es usar sendmail. La ubicación del programa sendmail varía entre sistemas; algunas veces está en /usr/lib/sendmail, otras veces en /usr/sbin/sendmail. El manual de sendmail le ayudará. Aquí hay un ejemplo de código:

import os

SENDMAIL = "/usr/sbin/sendmail"  # sendmail location
p = os.popen("%s -t -i" % SENDMAIL, "w")
p.write("To: receiver@example.com\n")
p.write("Subject: test\n")
p.write("\n")  # blank line separating headers from body
p.write("Some text\n")
p.write("some more text\n")
sts = p.close()
if sts != 0:
    print("Sendmail exit status", sts)

¿Cómo evito el bloqueo en el método connect() de un socket?

El módulo select es mayoritariamente usado para ayudar con entrada/salida de sockets.

Para evitar que la conexión TCP se bloquee, puede configurar el socket en modo sin bloqueo. Luego, cuando hagas el socket.connect(), te conectarás inmediatamente (poco probable) u obtendrás una excepción que contiene el número de error como .errno. errno.EINPROGRESS indica que la conexión está en curso, pero aún no ha terminado. Los diferentes sistemas operativos devolverán valores diferentes, por lo que tendrá que verificar lo que se devuelve en su sistema.

Puede utilizar el método socket.connect_ex() para evitar crear una excepción. Simplemente retornará el valor de errno. Para sondear, puede llamar a socket.connect_ex() nuevamente más tarde – 0 o errno.EISCONN indican que está conectado – o puede pasar este socket a select.select() para comprobar si se puede escribir.

Nota

El módulo asyncio proporciona una biblioteca asíncrona concurrente y de un solo subproceso de propósito general, que se puede utilizar para escribir código de red sin bloqueo. La biblioteca de terceros Twisted [https://twistedmatrix.com/trac/] es una alternativa popular y rica en funciones.

Bases de datos

¿Hay paquetes para interfaces a bases de datos en Python?

Sí.

Interfaces a hashes basados en disco tales como DBM y GDBM están también incluidas en Python estándar. También hay un módulo sqlite3, que proporciona una base de datos relacional ligera basada en disco.

Está disponible el soporte para la mayoría de bases de datos relacionales. Vea la página wiki de Programación de Bases de datos [https://wiki.python.org/moin/DatabaseProgramming] para más detalles.

¿Cómo implementar objetos persistentes en Python?

El módulo de biblioteca pickle soluciona esto de una forma muy general (aunque todavía no puede almacenar cosas como ficheros abiertos, sockets o ventanas), y el módulo de biblioteca shelve usa pickle y (g)dbm para crear mapeos persistentes que contienen objetos arbitrarios Python.

Matemáticas y Numérica

¿Cómo genero números aleatorios en Python?

El módulo estándar random implementa un generador de números aleatorios. El uso es simple:

import random
random.random()

Esto retorna un número flotante aleatorio en el rango [0, 1).

Hay también muchos otros generadores especializados en este módulo, tales como:

randrange(a, b) selecciona un entero en el rango [a, b).

uniform(a, b) selecciona un número flotante en el rango [a, b).

normalvariate(mean, sdev) muestrea una distribución normal (Gausiana).

Algunas funciones de alto nivel operan directamente sobre secuencias, tales como:

choice(S) selecciona un elemento aleatorio de una secuencia dada.

shuffle(L) reorganiza una lista in-situ, es decir, la permuta aleatoriamente.

También hay una clase Random que usted puede instanciar para crear múltiples generadores independientes de valores aleatorios.

Extendiendo/Embebiendo FAQ

Contenido

Extendiendo/Embebiendo FAQ

¿Puedo crear mis propias funciones en C?

¿Puedo crear mis propias funciones en C++?

Escribir en C es difícil; ¿no hay otra alternativa?

¿Cómo puedo ejecutar declaraciones arbitrarias de Python desde C?

¿Cómo puedo evaluar una expresión arbitraria de Python desde C?

¿Cómo extraigo valores C de un objeto Python?

¿Cómo utilizo Py_BuildValue() para crear una tupla de un tamaño arbitrario?

¿Cómo puedo llamar un método de un objeto desde C?

¿Cómo obtengo la salida de PyErr_Print() (o cualquier cosa que se imprime a stdout/stderr)?

¿Cómo accedo al módulo escrito en Python desde C?

¿Cómo hago una interface a objetos C++ desde Python?

He agregado un módulo usando el archivo de configuración y el make falla. ¿Porque?

¿Cómo puedo depurar una extensión?

Quiero compilar un módulo Python en mi sistema Linux, pero me faltan algunos archivos . ¿Por qué?

¿Cómo digo «entrada incompleta» desde «entrada inválida»?

¿Cómo encuentro símbolos g++ __builtin_new o __pure_virtual?

¿Puedo crear una clase objeto con algunos métodos implementado en C y otros en Python (por ejemplo a través de la herencia)?

¿Puedo crear mis propias funciones en C?

Si, puedes crear módulos incorporados que contengan funciones, variables, excepciones y incluso nuevos tipos en C. Esto esta explicado en el documento Ampliación e incrustación del intérprete de Python.

La mayoría de los libros intermedios o avanzados de Python también tratan este tema.

¿Puedo crear mis propias funciones en C++?

Si, utilizando las características de compatibilidad encontradas en C++. Coloca extern "C" { ... } alrededor los archivos incluidos Python y pon extern "C" antes de cada función que será llamada por el interprete Python. Objetos globales o estáticos C++ con constructores no son una buena idea seguramente.

Escribir en C es difícil; ¿no hay otra alternativa?

Hay un número de alternativas a escribir tus propias extensiones C, dependiendo en que estés tratando de hacer.

Cython [http://cython.org] y su relativo Pyrex [https://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/] son compiladores que aceptan una forma de Python ligeramente modificada y generan el código C correspondiente. Cython y Pyrex hacen posible escribir una extensión sin tener que aprender la API de Python C.

Si necesitas hacer una interfaz a alguna biblioteca C o C++ que no posee aún extensión Python, puedes intentar empaquetar los tipo de datos de la biblioteca con una herramienta como SWIG [http://www.swig.org]. SIP [https://riverbankcomputing.com/software/sip/intro], CXX [http://cxx.sourceforge.net/] Boost [http://www.boost.org/libs/python/doc/index.html], o Weave [https://github.com/scipy/weave] también son alternativas para empaquetar bibliotecas C++.

¿Cómo puedo ejecutar declaraciones arbitrarias de Python desde C?

La función de más alto nivel para hacer esto es PyRun_SimpleString() que toma un solo argumento de cadena de caracteres para ser ejecutado en el contexto del módulo __main__ y retorna 0 si tiene éxito y -1 cuando ocurre una excepción (incluyendo SyntaxError). Si quieres mas control, usa PyRun_String(); mira la fuente para PyRun_SimpleString() en Python/pythonrun.c.

¿Cómo puedo evaluar una expresión arbitraria de Python desde C?

Llama a la función PyRun_String() de la pregunta anterior con el símbolo de comienzo Py_eval_input; analiza una expresión, evalúa y retorna su valor.

¿Cómo extraigo valores C de un objeto Python?

Eso depende del tipo de objeto. Si es una tupla, PyTuple_Size() retorna su tamaño, y PyTuple_GetItem() retorna el ítem del índice especificado. Las listas tienen funciones similares, PyListSize() and PyList_GetItem().

Para bytes PyBytes_Size() retorna su tamaño, y PyBytes_AsStringAndSize() proporciona un puntero a su valor y tamaño. Nota que los objetos byte de Python pueden contener bytes null por lo que la función de C strlen() no debe ser utilizada.

Para testear el tipo de un objeto, primero debes estar seguro que no es NULL, y luego usa PyBytes_Check(), PyTuple_Check(), PyList_Check(), etc.

También hay una API de alto nivel para objetos Python que son provistos por la supuestamente llamada interfaz “abstracta” – lee Include/abstract.h para mas detalles. Permite realizar una interfaz con cualquier tipo de secuencia Python usando llamadas como PySequence_Length(), PySequence_GetItem(), etc. así como otros protocolos útiles como números (PyNumber_Index() et al.) y mapeos en las PyMapping APIs.

¿Cómo utilizo Py_BuildValue() para crear una tupla de un tamaño arbitrario?

No puedes hacerlo. Utiliza a cambio PyTuple_Pack().

¿Cómo puedo llamar un método de un objeto desde C?

Se puede utilizar la función PyObject_CallMethod() para llamar a un método arbitrario de un objeto. Los parámetros son el objeto, el nombre del método a llamar, una cadena de caracteres de formato como las usadas con Py_BuildValue(), y los valores de argumento

PyObject *
PyObject_CallMethod(PyObject *object, const char *method_name,
                    const char *arg_format, ...);

Esto funciona para cualquier objeto que tenga métodos – sean estos incorporados o definidos por el usuario. Eres responsable si eventualmente usas Py_DECREF() en el valor de retorno.

Para llamar, por ejemplo, un método «seek» de un objeto archivo con argumentos 10, 0 (considerando que puntero del objeto archivo es «f»):

res = PyObject_CallMethod(f, "seek", "(ii)", 10, 0);
if (res == NULL) {
        ... an exception occurred ...
}
else {
        Py_DECREF(res);
}

Note que debido a PyObject_CallObject() siempre necesita una tupla para la lista de argumento, para llamar una función sin argumentos, deberás pasar «()» para el formato, y para llamar a una función con un solo argumento, encierra el argumento entre paréntesis, por ejemplo «(i)».

¿Cómo obtengo la salida de PyErr_Print() (o cualquier cosa que se imprime a stdout/stderr)?

En código Python, define un objeto que soporta el método write(). Asigna este objeto a sys.stdout y sys.stderr. Llama a print_error, o solo permite que el mecanismo estándar de rastreo funcione. Luego, la salida se hará cuando invoques write().

La manera mas fácil de hacer esto es usar la clase io.StringIO:

>>> import io, sys
>>> sys.stdout = io.StringIO()
>>> print('foo')
>>> print('hello world!')
>>> sys.stderr.write(sys.stdout.getvalue())
foo
hello world!

Un objeto personalizado para hacer lo mismo se vería así:

>>> import io, sys
>>> class StdoutCatcher(io.TextIOBase):
...     def __init__(self):
...         self.data = []
...     def write(self, stuff):
...         self.data.append(stuff)
...
>>> import sys
>>> sys.stdout = StdoutCatcher()
>>> print('foo')
>>> print('hello world!')
>>> sys.stderr.write(''.join(sys.stdout.data))
foo
hello world!

¿Cómo accedo al módulo escrito en Python desde C?

Puedes obtener un puntero al módulo objeto de esta manera:

module = PyImport_ImportModule("<modulename>");

Si el módulo todavía no se importó, (por ejemplo aún no esta presente en sys.modules), esto inicializa el módulo, de otra forma simplemente retorna el valor de sys.modules["<modulename>"]. Nota que no entra el módulo a ningún espacio de nombres (namespace) –solo asegura que fue inicializado y guardado en sys.modules.

Puedes acceder luego a los atributos del módulo (por ejemplo a cualquier nombre definido en el módulo) de esta forma:

attr = PyObject_GetAttrString(module, "<attrname>");

También funciona llamar a PyObject_SetAttrString() para asignar a variables en el módulo.

¿Cómo hago una interface a objetos C++ desde Python?

Dependiendo de lo que necesites, hay varias maneras de hacerlo. Para hacerlo manualmente empieza por leer the «Extending and Embedding» document.Fíjate que para el sistema de tiempo de ejecución Python, no hay una gran diferencia entre C y C++, por lo que la estrategia de construir un nuevo tipo Python alrededor de una estructura de C de tipo puntero, también funcionará para objetos C++.

Para bibliotecas C++, mira Escribir en C es difícil; ¿no hay otra alternativa?.

He agregado un módulo usando el archivo de configuración y el make falla. ¿Porque?

La configuración debe terminar en una nueva linea, si esta no está, entonces el proceso build falla. (reparar esto requiere algún truco de linea de comandos que puede ser no muy prolijo, y seguramente el error es tan pequeño que no valdrá el esfuerzo.)

¿Cómo puedo depurar una extensión?

Cuando se usa GDB con extensiones cargadas de forma dinámica, puedes configurar un punto de verificación (breakpoint) en tu extensión hasta que esta se cargue.

En tu archivo .gdbinit (o interactivamente), agrega el comando:

br _PyImport_LoadDynamicModule

Luego, cuando corras GDB:

$ gdb /local/bin/python
gdb) run myscript.py
gdb) continue # repeat until your extension is loaded
gdb) finish   # so that your extension is loaded
gdb) br myfunction.c:50
gdb) continue

Quiero compilar un módulo Python en mi sistema Linux, pero me faltan algunos archivos . ¿Por qué?

La mayoría de las versiones empaquetadas de Python no incluyen el directorio /usr/lib/python2.x/config/, que contiene varios archivos que son necesarios para compilar las extensiones Python.

Para Red Hat, instala el python-devel RPM para obtener los archivos necesarios.

Para Debian, corre apt-get install python-dev.

¿Cómo digo «entrada incompleta» desde «entrada inválida»?

A veces quieres emular el comportamiento del interprete interactivo de Python, que te da una continuación del prompt cuando la entrada esta incompleta (por ejemplo si comenzaste tu instrucción «if» o no cerraste un paréntesis o triples comillas), pero te da un mensaje de error de sintaxis inmediatamente cuando la entrada es invalida.

En Python puedes usar el módulo codeop, que aproxima el comportamiento del analizador gramatical (parser) . IDLE usa esto, por ejemplo.

La manera mas fácil de hacerlo en C es llamar a PyRun_InteractiveLoop() (quizá en un hilo separado) y dejar que el interprete Python gestione la entrada por ti. Puedes también configurar PyOS_ReadlineFunctionPointer() para apuntar a tu función de entrada personalizada.

¿Cómo encuentro símbolos g++ __builtin_new o __pure_virtual?

Para cargar dinámicamente módulos de extensión g++, debes recompilar Python, hacer un nuevo link usando g++ (cambia LINKCC en el Python Modules Makefile) y enlaza link tu extensión usando g++ (por ejemplo g++ -shared -o mymodule.so mymodule.o`).

¿Puedo crear una clase objeto con algunos métodos implementado en C y otros en Python (por ejemplo a través de la herencia)?

Si, puedes heredar de clases integradas como int, list, dict, etc.

La biblioteca Boost Pyhton (BPL, http://www.boost.org/libs/python/doc/index.html) provee una manera de realizar esto desde C++ (por ejemplo puedes heredar de una clase extensión escrita en C++ usando el BPL).

Preguntas frecuentes sobre Python en Windows

Contenido

Preguntas frecuentes sobre Python en Windows

¿Cómo ejecutar un programa Python en Windows?

¿Cómo hacer que los scripts de Python sean ejecutables?

¿Por qué Python tarda en comenzar?

¿Cómo hacer un ejecutable a partir de un script de Python?

¿Es un archivo *.pyd lo mismo que una DLL?

¿Cómo puedo integrar Python en una aplicación de Windows?

¿Cómo puedo evitar que mi editor inserte pestañas en mi archivo fuente de Python?

¿Cómo verifico una pulsación de tecla sin bloquearla?

¿Cómo ejecutar un programa Python en Windows?

No es necesariamente una pregunta simple. Si ya está familiarizado con el lanzamiento de programas desde la línea de comandos de Windows, todo parecerá obvio; de lo contrario, es posible que necesite un poco más de orientación.

Unless you use some sort of integrated development environment, you will end up typing Windows commands into what is referred to as a «Command prompt window». Usually you can create such a window from your search bar by searching for cmd. You should be able to recognize when you have started such a window because you will see a Windows «command prompt», which usually looks like this:

C:\>

La letra puede ser diferente y puede haber otras cosas seguidas, por lo que también puede verse así:

D:\YourName\Projects\Python>

dependiendo de la configuración de su computadora y de lo que haya hecho recientemente con ella. Una vez que haya abierto esta ventana, está en camino de iniciar los programas de Python.

Tenga en cuenta que sus scripts de Python deben ser procesados ​​por otro programa llamado «intérprete» de Python. El intérprete lee su script, lo compila en bytecode y ejecuta el bytecode para ejecutar su programa. Entonces, ¿cómo le das tu código Python al intérprete?

Primero, debe asegurarse de que la ventana del símbolo del sistema reconoce la palabra «python» como una instrucción para iniciar el intérprete. Si abrió un símbolo del sistema, escriba el comando py y luego presione la tecla Enter:

C:\Users\YourName> py

Debería ver algo como esto:

Python 3.6.4 (v3.6.4:d48eceb, Dec 19 2017, 06:04:45) [MSC v.1900 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>>

Has comenzado el intérprete en su «modo interactivo». Esto significa que puede ingresar declaraciones o expresiones de Python de forma interactiva para ejecutarlas. Esta es una de las características más poderosas de Python. Puede verificar esto ingresando algunos comandos de su elección y ver los resultado:

>>> print("Hello")
Hello
>>> "Hello" * 3
'HelloHelloHello'

Muchas personas usan el modo interactivo como una calculadora práctica pero altamente programable. Cuando desee finalizar su sesión interactiva de Python, llame a la función exit() o mantenga presionada la tecla Ctrl mientras ingresa una Z, luego presione la tecla «Enter» para regresar a su símbolo del sistema de Windows.

Es posible que haya notado una nueva entrada en su menú Inicio, como Inicio ‣ Programas ‣ Python 3.x ‣ Python (línea de comando) que hace que vea el mensaje >>> en una nueva ventana. Si es así, la ventana desaparecerá cuando llame a la función exit() o presione la combinación Ctrl-Z; Windows ejecuta un comando «python» en la ventana y lo cierra cuando cierra el intérprete.

Ahora que sabemos que se reconoce el comando py, puede darle su script Python. Debe proporcionar la ruta absoluta o relativa de la secuencia de comandos de Python. Digamos que su script Python se encuentra en su escritorio y se llama hello.py, y su símbolo del sistema está abierto en su directorio de inicio, por lo que verá algo como:

C:\Users\YourName>

Entonces, le pedirá al comando py que le dé su script a Python escribiendo py seguido de la ruta de su script:

C:\Users\YourName> py Desktop\hello.py
hello

¿Cómo hacer que los scripts de Python sean ejecutables?

En Windows, el instalador de Python asocia la extensión .py con un tipo de archivo (Python.File) y un comando que inicia el intérprete (D:\Archivos de programa\Python\python.exe "%1" %*) . Esto es suficiente para poder ejecutar scripts de Python desde la línea de comandos ingresando “foo.py”. Si desea poder ejecutar los scripts simplemente escribiendo “foo” sin la extensión, debe agregar .py a la variable del entorno PATHEXT.

¿Por qué Python tarda en comenzar?

Normalmente en Windows, Python se inicia muy rápidamente, pero a veces los informes de error indican que Python de repente comienza a tardar mucho tiempo en iniciarse. Es aún más desconcertante porque Python funcionará correctamente con otros Windows configurados de manera idéntica.

El problema puede provenir de un antivirus mal configurado. Se sabe que algunos antivirus duplican el tiempo de arranque cuando se configuran para verificar todas las lecturas del sistema de archivos. Intente verificar si los antivirus de las dos máquinas están configurados correctamente de manera idéntica. McAfee es especialmente problemático cuando se configura para verificar todas las lecturas del sistema de archivos.

¿Cómo hacer un ejecutable a partir de un script de Python?

See ¿Cómo puedo crear un binario independiente a partir de un programa Python? for a list of tools that can be used to make executables.

¿Es un archivo *.pyd lo mismo que una DLL?

Sí, los archivos .pyd son archivos dll, pero hay algunas diferencias. Si tiene una DLL llamada foo.pyd, debe tener una función PyInit_foo(). Luego puede escribir en Python «import foo» y Python buscará el archivo foo.pyd (así como foo.py y foo.pyc); si lo encuentra, intentará llamar a PyInit_foo() para inicializarlo. No vincules tu .exe con foo.lib porque en este caso Windows necesitará la DLL.

Tenga en cuenta que la ruta de búsqueda para foo.pyd es PYTHONPATH, es diferente de la que usa Windows para buscar foo.dll. Además, foo.pyd no necesita estar presente para que su programa se ejecute, mientras que si ha vinculado su programa con una dll, esto es necesario. Por supuesto, foo.pyd es necesario si escribes import foo. En una DLL, el enlace se declara en el código fuente con __declspec(dllexport). En un .pyd, la conexión se define en una lista de funciones disponibles.

¿Cómo puedo integrar Python en una aplicación de Windows?

La integración del intérprete de Python en una aplicación de Windows se puede resumir de la siguiente manera:

_No_ compile Python directamente en su archivo .exe. En Windows, Python debe ser una DLL para poder importar módulos que son DLL en sí mismos (esto constituye información esencial no documentada). En su lugar, haga un enlace al archivo pythonNN.dll; que generalmente se encuentra en C:\Windows\System. NN es la versión de Python, por ejemplo «33» para Python 3.3.

Puede vincular a Python de dos maneras diferentes. Un enlace en tiempo de carga significa apuntar al archivo pythonNN.lib, mientras que un enlace en tiempo de ejecución significa apuntar al archivo pythonNN.dll. (Nota general: el archivo pythonNN.lib es la llamada «lib de importación» correspondiente para el archivo pythonNN.dll. Simplemente define enlaces simbólicos para el enlazador).

El enlace en tiempo real simplifica enormemente las opciones de enlace; Todo sucede en el momento de la ejecución. Su código debe cargar el archivo pythonNN.dll utilizando la rutina de Windows LoadLibraryEx(). El código también debe usar rutinas de acceso y datos en el archivo pythonNN.dll (es decir, las API C de Python) usando punteros obtenidos por la rutina de Windows GetProcAddress(). Las macros pueden hacer que el uso de estos punteros sea transparente para cualquier código C que llame a rutinas en la API C de Python.

Si está utilizando SWIG, es fácil crear un «complemento» de Python que hará que los datos y métodos de la aplicación estén disponibles para Python. SWIG se encargará de todos los detalles aburridos para usted. El resultado es un código C que se vincula adentro de su archivo.exe (!) _No_ necesita crear un archivo DLL, y también simplifica la vinculación.

SWIG creará una función de inicialización (función en C) cuyo nombre depende del nombre del complemento. Por ejemplo, si el nombre del módulo es leo, la función init se llamará initleo(). Si está utilizando clases shadow SWIG, como debería, la función init se llamará initleoc(). Esto inicializa una clase auxiliar invisible utilizada por la clase shadow.

¡La razón por la que puede vincular el código C en el paso 2 en su archivo .exe es que llamar a la función de inicialización es equivalente a importar el módulo a Python! (Este es el segundo hecho clave indocumentado).

En resumen, puede usar el siguiente código para inicializar el intérprete de Python con su complemento.

#include "python.h"
...
Py_Initialize();  // Initialize Python.
initmyAppc();  // Initialize (import) the helper class.
PyRun_SimpleString("import myApp");  // Import the shadow class.

Hay dos problemas con la API de Python C que aparecerán si utiliza un compilador que no sea MSVC, el compilador utilizado para construir pythonNN.dll.

Problema 1: Las llamadas funciones de «Muy Alto Nivel» que toman los argumentos FILE * no funcionarán en un entorno de compilación múltiple porque cada compilador tendrá una noción diferente de la estructura FILE. Desde el punto de vista de la implementación, estas son funciones de muy _bajo_ nivel.

Problema 2: SWIG genera el siguiente código al generar contenedores para cancelar las funciones:

Py_INCREF(Py_None);
_resultobj = Py_None;
return _resultobj;

Por desgracia, Py_None es una macro que se desarrolla con referencia a una estructura de datos compleja llamada _Py_NoneStruct dentro de pythonNN.dll. Nuevamente, este código fallará en un entorno de múltiples compiladores. Reemplace este código con:

return Py_BuildValue("");

Es posible utilizar el comando SWIG %typemap para realizar el cambio automáticamente, aunque no he logrado que funcione (soy un principiante con SWIG).

Usar una secuencia de comandos de shell Python para crear una ventana de intérprete de Python desde su aplicación de Windows no es una buena idea; la ventana resultante será independiente del sistema de ventanas de su aplicación. Usted (o la clase wxPythonWindow) debería crear una ventana de intérprete «nativa». Es fácil conectar esta ventana al intérprete de Python. Puede redirigir la entrada/salida de Python a cualquier objeto que admita lectura y escritura, por lo que todo lo que necesita es un objeto de Python (definido en su complemento) que contenga los métodos de read() y write().

¿Cómo puedo evitar que mi editor inserte pestañas en mi archivo fuente de Python?

Las preguntas frecuentes no recomiendan el uso de pestañas y la guía de estilo de Python, PEP 8 [https://www.python.org/dev/peps/pep-0008], recomienda el uso de 4 espacios para distribuir el código de Python. Este es también el modo predeterminado de Emacs con Python.

Sea cual sea su editor, mezclar pestañas y espacios es una mala idea. MSVC no es diferente en este aspecto, y se puede configurar fácilmente para usar espacios: vaya a Tools ‣ Options ‣ Tabs, y para el tipo de archivo «Default», debe establecer «Tab size» and «Indent size» en 4, luego seleccione Insertar espacios.

Python lanzará los errores IndentationError o TabError si una combinación de tabulación y sangría es problemática al comienzo de la línea. También puede usar el módulo tabnanny para detectar estos errores.

¿Cómo verifico una pulsación de tecla sin bloquearla?

Use el módulo msvcrt. Es una extensión estándar específica de Windows, que define una función kbhit() que verifica si se ha presionado una tecla, y getch() que recupera el carácter sin mostrarlo.

Preguntas frecuentes sobre la Interfaz Gráfica de Usuario (GUI)

Contenido

Preguntas frecuentes sobre la Interfaz Gráfica de Usuario (GUI)

Preguntas generales de la GUI

What GUI toolkits exist for Python?

Preguntas de Tkinter

¿Cómo congelo las aplicaciones de Tkinter?

¿Puedo tener eventos Tk manejados mientras espero por I/O?

No puedo hacer que los atajos de teclado funcionen en Tkinter: ¿por qué?

Preguntas generales de la GUI

What GUI toolkits exist for Python?

Standard builds of Python include an object-oriented interface to the Tcl/Tk widget set, called tkinter. This is probably the easiest to install (since it comes included with most binary distributions [https://www.python.org/downloads/] of Python) and use. For more info about Tk, including pointers to the source, see the Tcl/Tk home page [https://www.tcl.tk]. Tcl/Tk is fully portable to the macOS, Windows, and Unix platforms.

Depending on what platform(s) you are aiming at, there are also several alternatives. A list of cross-platform [https://wiki.python.org/moin/GuiProgramming#Cross-Platform_Frameworks] and platform-specific [https://wiki.python.org/moin/GuiProgramming#Platform-specific_Frameworks] GUI frameworks can be found on the python wiki.

Preguntas de Tkinter

¿Cómo congelo las aplicaciones de Tkinter?

Freeze es una herramienta para crear aplicaciones independientes. Al congelar aplicaciones Tkinter, las aplicaciones no serán realmente independientes, ya que la aplicación seguirá necesitando las bibliotecas Tcl y Tk.

Una solución es enviar la aplicación con las bibliotecas Tcl y Tk, y apuntarlas en tiempo de ejecución utilizando TCL_LIBRARY y las variables de entorno TK_LIBRARY.

Para obtener aplicaciones verdaderamente independientes, los scripts Tcl que forman la biblioteca también deben integrarse en la aplicación. Una herramienta compatible es SAM (módulos independientes), que forma parte de la distribución Tix (http://tix.sourceforge.net/).

Construya Tix con SAM habilitado, realice la llamada apropiada a Tclsam_init(), etc. dentro de Python Modules/tkappinit.c, y enlace con libtclsam libtclsam y libtksam (también puede incluir las bibliotecas Tix).

¿Puedo tener eventos Tk manejados mientras espero por I/O?

En plataformas que no sean Windows, sí, ¡y ni siquiera necesita hilos! Pero tendrá que reestructurar un poco su código de I/O. Tk tiene el equivalente de la llamada Xt XtAddInput(), que le permite registrar una función de callback que se llamará desde el bucle principal de Tk cuando sea posible I/O en un descriptor de archivo. Ver Gestor de archivos.

No puedo hacer que los atajos de teclado funcionen en Tkinter: ¿por qué?

Una queja que se escucha con frecuencia es que los controladores de eventos vinculados a eventos con el método bind() no se manejan incluso cuando se presiona la tecla adecuada.

La causa más común es que el widget al que se aplica el atajo no tiene enfoque de teclado. Consulte la documentación de Tk para el comando de focus. Por lo general, un widget recibe el foco del teclado haciendo clic en él (pero no para las etiquetas; consulte la opción takefocus).

«¿Por qué está Python instalado en mi ordenador?» FAQ

¿Qué es Python?

Python es un lenguaje de programación. Se usa para muchas aplicaciones diferentes. Se utiliza en algunas escuelas secundarias y universidades como un lenguaje de programación introductorio porque Python es fácil de aprender, pero también es utilizado por desarrolladores de software profesionales en lugares como Google, NASA, y Lucasfilm Ltd.

Si desea aprender más sobre Python, comience con la Guía del principiante de Python [https://wiki.python.org/moin/BeginnersGuide].

¿Por qué Python está instalado en mi máquina?

Si encuentras Python instalado en tu sistema pero no recuerdas haberlo instalado, hay varias maneras posibles en las que podría haber llegado ahí.

Tal vez otro usuario de la computadora quiso aprender a programar y la instaló.

Una aplicación de terceros instalada en la máquina podría haber sido escrita en Python e incluir una instalación de Python. Hay muchas aplicaciones de este tipo, desde programas GUI hasta servidores de red y scripts administrativos.

Algunas máquinas Windows también tienen Python instalado. Al momento de escribir este artículo, sabemos que las computadoras de Hewlett-Packard y Compaq incluyen Python. Aparentemente algunas de las herramientas administrativas de HP/Compaq están escritas en Python.

Many Unix-compatible operating systems, such as macOS and some Linux distributions, have Python installed by default; it’s included in the base installation.

¿Puedo eliminar Python?

Eso depende de dónde vino Python.

Si alguien lo instaló deliberadamente, puede quitarlo sin dañar nada. En Windows, utilice el icono Agregar o quitar programas en el Panel de control.

Si Python fue instalado por una aplicación de terceros, también puede eliminarlo, pero esa aplicación ya no funcionará. Deberías usar el desinstalador de esa aplicación en lugar de eliminar Python directamente.

Si Python vino con su sistema operativo, no se recomienda quitarlo. Si lo eliminas, las herramientas escritas en Python ya no funcionarán, y algunas de ellas pueden ser importantes para ti. Reinstalar todo el sistema sería entonces necesario para arreglar las cosas de nuevo.

Glosario

>>>

El prompt en el shell interactivo de Python por omisión. Frecuentemente vistos en ejemplos de código que pueden ser ejecutados interactivamente en el intérprete.

...

Puede referirse a:

El prompt en el shell interactivo de Python por omisión cuando se ingresa código para un bloque indentado de código, y cuando se encuentra entre dos delimitadores que emparejan (paréntesis, corchetes, llaves o comillas triples), o después de especificar un decorador.

La constante incorporada Ellipsis.

2to3

Una herramienta que intenta convertir código de Python 2.x a Python 3.x arreglando la mayoría de las incompatibilidades que pueden ser detectadas analizando el código y recorriendo el árbol de análisis sintáctico.

2to3 está disponible en la biblioteca estándar como lib2to3; un punto de entrada independiente es provisto como Tools/scripts/2to3. Vea 2to3 - Traducción de código Python 2 a 3.

clase base abstracta

Las clases base abstractas (ABC, por sus siglas en inglés Abstract Base Class) complementan al duck-typing brindando un forma de definir interfaces con técnicas como hasattr() que serían confusas o sutilmente erróneas (por ejemplo con magic methods). Las ABC introduce subclases virtuales, las cuales son clases que no heredan desde una clase pero aún así son reconocidas por isinstance() y issubclass(); vea la documentación del módulo abc. Python viene con muchas ABC incorporadas para las estructuras de datos( en el módulo collections.abc), números (en el módulo numbers ) , flujos de datos (en el módulo io ) , buscadores y cargadores de importaciones (en el módulo importlib.abc ) . Puede crear sus propios ABCs con el módulo abc.

anotación

Una etiqueta asociada a una variable, atributo de clase, parámetro de función o valor de retorno, usado por convención como un type hint.

Las anotaciones de variables no pueden ser accedidas en tiempo de ejecución, pero las anotaciones de variables globales, atributos de clase, y funciones son almacenadas en el atributo especial __annotations__ de módulos, clases y funciones, respectivamente.

Vea variable annotation, function annotation, PEP 484 [https://www.python.org/dev/peps/pep-0484] y PEP 526 [https://www.python.org/dev/peps/pep-0526], los cuales describen esta funcionalidad.

argumento

Un valor pasado a una function (o method) cuando se llama a la función. Hay dos clases de argumentos:

argumento nombrado: es un argumento precedido por un identificador (por ejemplo, nombre=) en una llamada a una función o pasado como valor en un diccionario precedido por **. Por ejemplo 3 y 5 son argumentos nombrados en las llamadas a complex():

complex(real=3, imag=5)
complex(**{'real': 3, 'imag': 5})

argumento posicional son aquellos que no son nombrados. Los argumentos posicionales deben aparecer al principio de una lista de argumentos o ser pasados como elementos de un iterable precedido por *. Por ejemplo, 3 y 5 son argumentos posicionales en las siguientes llamadas:

complex(3, 5)
complex(*(3, 5))

Los argumentos son asignados a las variables locales en el cuerpo de la función. Vea en la sección Invocaciones las reglas que rigen estas asignaciones. Sintácticamente, cualquier expresión puede ser usada para representar un argumento; el valor evaluado es asignado a la variable local.

Vea también el parameter en el glosario, la pregunta frecuente la diferencia entre argumentos y parámetros, y PEP 362 [https://www.python.org/dev/peps/pep-0362].

administrador asincrónico de contexto

Un objeto que controla el entorno visible en un sentencia async with al definir los métodos __aenter__() __aexit__(). Introducido por PEP 492 [https://www.python.org/dev/peps/pep-0492].

generador asincrónico

Una función que retorna un asynchronous generator iterator. Es similar a una función corrutina definida con async def excepto que contiene expresiones yield para producir series de variables usadas en un ciclo async for.

Usualmente se refiere a una función generadora asincrónica, pero puede referirse a un iterador generador asincrónico en ciertos contextos. En aquellos casos en los que el significado no está claro, usar los términos completos evita la ambigüedad.

Una función generadora asincrónica puede contener expresiones await así como sentencias async for, y async with.

iterador generador asincrónico

Un objeto creado por una función asynchronous generator.

Este es un asynchronous iterator el cual cuando es llamado usa el método __anext__() retornando un objeto a la espera (awaitable) el cual ejecutará el cuerpo de la función generadora asincrónica hasta la siguiente expresión yield.

Cada yield suspende temporalmente el procesamiento, recordando el estado local de ejecución (incluyendo a las variables locales y las sentencias try pendientes). Cuando el iterador del generador asincrónico vuelve efectivamente con otro objeto a la espera (awaitable) retornado por el método __anext__(), retoma donde lo dejó. Vea PEP 492 [https://www.python.org/dev/peps/pep-0492] y PEP 525 [https://www.python.org/dev/peps/pep-0525].

iterable asincrónico

Un objeto, que puede ser usado en una sentencia async for. Debe retornar un asynchronous iterator de su método __aiter__(). Introducido por PEP 492 [https://www.python.org/dev/peps/pep-0492].

iterador asincrónico

Un objeto que implementa los métodos __aiter__() y __anext__(). __anext__ debe retornar un objeto awaitable. async for resuelve los esperables retornados por un método de iterador asincrónico __anext__() hasta que lanza una excepción StopAsyncIteration. Introducido por PEP 492 [https://www.python.org/dev/peps/pep-0492].

atributo

Un valor asociado a un objeto que es referencias por el nombre usado expresiones de punto. Por ejemplo, si un objeto o tiene un atributo a sería referenciado como o.a.

a la espera

Es un objeto a la espera (awaitable) que puede ser usado en una expresión await. Puede ser una coroutine o un objeto con un método __await__(). Vea también PEP 492 [https://www.python.org/dev/peps/pep-0492].

BDFL

Sigla de Benevolent Dictator For Life, benevolente dictador vitalicio, es decir Guido van Rossum [https://gvanrossum.github.io/], el creador de Python.

archivo binario

Un file object capaz de leer y escribir objetos tipo binarios. Ejemplos de archivos binarios son los abiertos en modo binario ('rb', 'wb' o 'rb+'), sys.stdin.buffer, sys.stdout.buffer, e instancias de io.BytesIO y de gzip.GzipFile.

Vea también text file para un objeto archivo capaz de leer y escribir objetos str.

objetos tipo binarios

Un objeto que soporta Protocolo Búfer y puede exportar un búfer C-contiguous. Esto incluye todas los objetos bytes, bytearray, y array.array, así como muchos objetos comunes memoryview. Los objetos tipo binarios pueden ser usados para varias operaciones que usan datos binarios; éstas incluyen compresión, salvar a archivos binarios, y enviarlos a través de un socket.

Algunas operaciones necesitan que los datos binarios sean mutables. La documentación frecuentemente se refiere a éstos como «objetos tipo binario de lectura y escritura». Ejemplos de objetos de búfer mutables incluyen a bytearray y memoryview de la bytearray. Otras operaciones que requieren datos binarios almacenados en objetos inmutables («objetos tipo binario de sólo lectura»); ejemplos de éstos incluyen bytes y memoryview del objeto bytes.

bytecode

El código fuente Python es compilado en bytecode, la representación interna de un programa python en el intérprete CPython. El bytecode también es guardado en caché en los archivos .pyc de tal forma que ejecutar el mismo archivo es más fácil la segunda vez (la recompilación desde el código fuente a bytecode puede ser evitada). Este «lenguaje intermedio» deberá corren en una virtual machine que ejecute el código de máquina correspondiente a cada bytecode. Note que los bytecodes no tienen como requisito trabajar en las diversas máquina virtuales de Python, ni de ser estable entre versiones Python.

Una lista de las instrucciones en bytecode está disponible en la documentación de el módulo dis.

retrollamada

Una función de subrutina que se pasa como un argumento para ejecutarse en algún momento en el futuro.

clase

Una plantilla para crear objetos definidos por el usuario. Las definiciones de clase normalmente contienen definiciones de métodos que operan una instancia de la clase.

variable de clase

Una variable definida en una clase y prevista para ser modificada sólo a nivel de clase (es decir, no en una instancia de la clase).

coerción

La conversión implícita de una instancia de un tipo en otra durante una operación que involucra dos argumentos del mismo tipo. Por ejemplo, int(3.15) convierte el número de punto flotante al entero 3, pero en 3 + 4.5, cada argumento es de un tipo diferente (uno entero, otro flotante), y ambos deben ser convertidos al mismo tipo antes de que puedan ser sumados o emitiría un TypeError. Sin coerción, todos los argumentos, incluso de tipos compatibles, deberían ser normalizados al mismo tipo por el programador, por ejemplo float(3)+4.5 en lugar de 3+4.5.

número complejo

Una extensión del sistema familiar de número reales en el cual los números son expresados como la suma de una parte real y una parte imaginaria. Los números imaginarios son múltiplos de la unidad imaginaria (la raíz cuadrada de -1), usualmente escrita como i en matemáticas o j en ingeniería. Python tiene soporte incorporado para números complejos, los cuales son escritos con la notación mencionada al final.; la parte imaginaria es escrita con un sufijo j, por ejemplo, 3+1j. Para tener acceso a los equivalentes complejos del módulo math module, use cmath. El uso de números complejos es matemática bastante avanzada. Si no le parecen necesarios, puede ignorarlos sin inconvenientes.

administrador de contextos

Un objeto que controla el entorno en la sentencia with definiendo los métodos __enter__() y __exit__(). Vea PEP 343 [https://www.python.org/dev/peps/pep-0343].

variable de contexto

Una variable que puede tener diferentes valores dependiendo del contexto. Esto es similar a un almacenamiento de hilo local Thread-Local Storage en el cual cada hilo de ejecución puede tener valores diferentes para una variable. Sin embargo, con las variables de contexto, podría haber varios contextos en un hilo de ejecución y el uso principal de las variables de contexto es mantener registro de las variables en tareas concurrentes asíncronas. Vea contextvars.

contiguo

Un búfer es considerado contiguo con precisión si es C-contiguo o Fortran contiguo. Los búferes cero dimensionales con C y Fortran contiguos. En los arreglos unidimensionales, los ítems deben ser dispuestos en memoria uno siguiente al otro, ordenados por índices que comienzan en cero. En arreglos unidimensionales C-contiguos, el último índice varía más velozmente en el orden de las direcciones de memoria. Sin embargo, en arreglos Fortran contiguos, el primer índice vería más rápidamente.

corrutina

Las corrutinas son una forma más generalizadas de las subrutinas. A las subrutinas se ingresa por un punto y se sale por otro punto. Las corrutinas pueden se iniciadas, finalizadas y reanudadas en muchos puntos diferentes. Pueden ser implementadas con la sentencia async def. Vea además PEP 492 [https://www.python.org/dev/peps/pep-0492].

función corrutina

Un función que retorna un objeto coroutine . Una función corrutina puede ser definida con la sentencia async def, y puede contener las palabras claves await, async for, y async with. Las mismas son introducidas en PEP 492 [https://www.python.org/dev/peps/pep-0492].

CPython

La implementación canónica del lenguaje de programación Python, como se distribuye en python.org [https://www.python.org]. El término «CPython» es usado cuando es necesario distinguir esta implementación de otras como Jython o IronPython.

decorador

Una función que retorna otra función, usualmente aplicada como una función de transformación empleando la sintaxis @envoltorio. Ejemplos comunes de decoradores son classmethod() y staticmethod().

La sintaxis del decorador es meramente azúcar sintáctico, las definiciones de las siguientes dos funciones son semánticamente equivalentes:

def f(arg):
    ...
f = staticmethod(f)

@staticmethod
def f(arg):
    ...

El mismo concepto existe para clases, pero son menos usadas. Vea la documentación de function definitions y class definitions para mayor detalle sobre decoradores.

descriptor

Cualquier objeto que define los métodos __get__(), __set__(), o __delete__(). Cuando un atributo de clase es un descriptor, su conducta enlazada especial es disparada durante la búsqueda del atributo. Normalmente, usando a.b para consultar, establecer o borrar un atributo busca el objeto llamado b en el diccionario de clase de a, pero si b es un descriptor, el respectivo método descriptor es llamado. Entender descriptores es clave para lograr una comprensión profunda de Python porque son la base de muchas de las capacidades incluyendo funciones, métodos, propiedades, métodos de clase, métodos estáticos, y referencia a súper clases.

Para obtener más información sobre los métodos de los descriptores, consulte Implementando Descriptores o Guía práctica de uso de los descriptores.

diccionario

Un arreglo asociativo, con claves arbitrarias que son asociadas a valores. Las claves pueden ser cualquier objeto con los métodos __hash__() y __eq__() . Son llamadas hash en Perl.

comprensión de diccionarios

Una forma compacta de procesar todos o parte de los elementos en un iterable y retornar un diccionario con los resultados. results = {n: n ** 2 for n in range(10)} genera un diccionario que contiene la clave n asignada al valor n ** 2. Ver Despliegues para listas, conjuntos y diccionarios.

vista de diccionario

Los objetos retornados por los métodos dict.keys(), dict.values(), y dict.items() son llamados vistas de diccionarios. Proveen una vista dinámica de las entradas de un diccionario, lo que significa que cuando el diccionario cambia, la vista refleja éstos cambios. Para forzar a la vista de diccionario a convertirse en una lista completa, use list(dictview). Vea Objetos tipos vista de diccionario.

docstring

Una cadena de caracteres literal que aparece como la primera expresión en una clase, función o módulo. Aunque es ignorada cuando se ejecuta, es reconocida por el compilador y puesta en el atributo __doc__ de la clase, función o módulo comprendida. Como está disponible mediante introspección, es el lugar canónico para ubicar la documentación del objeto.

tipado de pato

Un estilo de programación que no revisa el tipo del objeto para determinar si tiene la interfaz correcta; en vez de ello, el método o atributo es simplemente llamado o usado («Si se ve como un pato y grazna como un pato, debe ser un pato»). Enfatizando las interfaces en vez de hacerlo con los tipos específicos, un código bien diseñado pues tener mayor flexibilidad permitiendo la sustitución polimórfica. El tipado de pato duck-typing evita usar pruebas llamando a type() o isinstance(). (Nota: si embargo, el tipado de pato puede ser complementado con abstract base classes. En su lugar, generalmente pregunta con hasattr() o EAFP.

EAFP

Del inglés Easier to ask for forgiveness than permission, es más fácil pedir perdón que pedir permiso. Este estilo de codificación común en Python asume la existencia de claves o atributos válidos y atrapa las excepciones si esta suposición resulta falsa. Este estilo rápido y limpio está caracterizado por muchas sentencias try y except. Esta técnica contrasta con estilo LBYL usual en otros lenguajes como C.

expresión

Una construcción sintáctica que puede ser evaluada, hasta dar un valor. En otras palabras, una expresión es una acumulación de elementos de expresión tales como literales, nombres, accesos a atributos, operadores o llamadas a funciones, todos ellos retornando valor. A diferencia de otros lenguajes, no toda la sintaxis del lenguaje son expresiones. También hay statements que no pueden ser usadas como expresiones, como la while. Las asignaciones también son sentencias, no expresiones.

módulo de extensión

Un módulo escrito en C o C++, usando la API para C de Python para interactuar con el núcleo y el código del usuario.

f-string

Son llamadas f-strings las cadenas literales que usan el prefijo 'f' o 'F', que es una abreviatura para formatted string literals. Vea también PEP 498 [https://www.python.org/dev/peps/pep-0498].

objeto archivo

Un objeto que expone una API orientada a archivos (con métodos como read() o write()) al objeto subyacente. Dependiendo de la forma en la que fue creado, un objeto archivo, puede mediar el acceso a un archivo real en el disco u otro tipo de dispositivo de almacenamiento o de comunicación (por ejemplo, entrada/salida estándar, búfer de memoria, sockets, pipes, etc.). Los objetos archivo son también denominados objetos tipo archivo o flujos.

Existen tres categorías de objetos archivo: crudos raw archivos binarios, con búfer archivos binarios y archivos de texto. Sus interfaces son definidas en el módulo io. La forma canónica de crear objetos archivo es usando la función open().

objetos tipo archivo

Un sinónimo de file object.

buscador

Un objeto que trata de encontrar el loader para el módulo que está siendo importado.

Desde la versión 3.3 de Python, existen dos tipos de buscadores: meta buscadores de ruta para usar con sys.meta_path, y buscadores de entradas de rutas para usar con sys.path_hooks.

Vea PEP 302 [https://www.python.org/dev/peps/pep-0302], PEP 420 [https://www.python.org/dev/peps/pep-0420] y PEP 451 [https://www.python.org/dev/peps/pep-0451] para mayores detalles.

división entera

Una división matemática que se redondea hacia el entero menor más cercano. El operador de la división entera es //. Por ejemplo, la expresión 11 // 4 evalúa 2 a diferencia del 2.75 retornado por la verdadera división de números flotantes. Note que (-11) // 4 es -3 porque es -2.75 redondeado para abajo. Ver PEP 238 [https://www.python.org/dev/peps/pep-0238].

función

Una serie de sentencias que retornan un valor al que las llama. También se le puede pasar cero o más argumentos los cuales pueden ser usados en la ejecución de la misma. Vea también parameter, method, y la sección Definiciones de funciones.

anotación de función

Una annotation del parámetro de una función o un valor de retorno.

Las anotaciones de funciones son usadas frecuentemente para indicadores de tipo, por ejemplo, se espera que una función tome dos argumentos de clase int y también se espera que retorne dos valores int:

def sum_two_numbers(a: int, b: int) -> int:
   return a + b

La sintaxis de las anotaciones de funciones son explicadas en la sección Definiciones de funciones.

Vea variable annotation y PEP 484 [https://www.python.org/dev/peps/pep-0484], que describen esta funcionalidad.

__future__

A future statement, from __future__ import <feature>, directs the compiler to compile the current module using syntax or semantics that will become standard in a future release of Python. The __future__ module documents the possible values of feature. By importing this module and evaluating its variables, you can see when a new feature was first added to the language and when it will (or did) become the default:

>>> import __future__
>>> __future__.division
_Feature((2, 2, 0, 'alpha', 2), (3, 0, 0, 'alpha', 0), 8192)

recolección de basura

El proceso de liberar la memoria de lo que ya no está en uso. Python realiza recolección de basura (garbage collection) llevando la cuenta de las referencias, y el recogedor de basura cíclico es capaz de detectar y romper las referencias cíclicas. El recogedor de basura puede ser controlado mediante el módulo gc .

generador

Una función que retorna un generator iterator. Luce como una función normal excepto que contiene la expresión yield para producir series de valores utilizables en un bucle for o que pueden ser obtenidas una por una con la función next().

Usualmente se refiere a una función generadora, pero puede referirse a un iterador generador en ciertos contextos. En aquellos casos en los que el significado no está claro, usar los términos completos evita la ambigüedad.

iterador generador

Un objeto creado por una función generator.

Cada yield suspende temporalmente el procesamiento, recordando el estado de ejecución local (incluyendo las variables locales y las sentencias try pendientes). Cuando el «iterador generado» vuelve, retoma donde ha dejado, a diferencia de lo que ocurre con las funciones que comienzan nuevamente con cada invocación.

expresión generadora

Una expresión que retorna un iterador. Luce como una expresión normal seguida por la cláusula for definiendo así una variable de bucle, un rango y una cláusula opcional if. La expresión combinada genera valores para la función contenedora:

>>> sum(i*i for i in range(10))         # sum of squares 0, 1, 4, ... 81
285

función genérica

Una función compuesta de muchas funciones que implementan la misma operación para diferentes tipos. Qué implementación deberá ser usada durante la llamada a la misma es determinado por el algoritmo de despacho.

Vea también la entrada de glosario single dispatch, el decorador functools.singledispatch(), y PEP 443 [https://www.python.org/dev/peps/pep-0443].

tipos genéricos

A type that can be parameterized; typically a container class such as list or dict. Used for type hints and annotations.

For more details, see generic alias types, PEP 483 [https://www.python.org/dev/peps/pep-0483], PEP 484 [https://www.python.org/dev/peps/pep-0484], PEP 585 [https://www.python.org/dev/peps/pep-0585], and the typing module.

GIL

Vea global interpreter lock.

bloqueo global del intérprete

Mecanismo empleado por el intérprete CPython para asegurar que sólo un hilo ejecute el bytecode Python por vez. Esto simplifica la implementación de CPython haciendo que el modelo de objetos (incluyendo algunos críticos como dict) están implícitamente a salvo de acceso concurrente. Bloqueando el intérprete completo se simplifica hacerlo multi-hilos, a costa de mucho del paralelismo ofrecido por las máquinas con múltiples procesadores.

Sin embargo, algunos módulos de extensión, tanto estándar como de terceros, están diseñados para liberar el GIL cuando se realizan tareas computacionalmente intensivas como la compresión o el hashing. Además, el GIL siempre es liberado cuando se hace entrada/salida.

Esfuerzos previos hechos para crear un intérprete «sin hilos» (uno que bloquee los datos compartidos con una granularidad mucho más fina) no han sido exitosos debido a que el rendimiento sufrió para el caso más común de un solo procesador. Se cree que superar este problema de rendimiento haría la implementación mucho más compleja y por tanto, más costosa de mantener.

hash-based pyc

Un archivo cache de bytecode que usa el hash en vez de usar el tiempo de la última modificación del archivo fuente correspondiente para determinar su validez. Vea Invalidación del código de bytes en caché.

hashable

Un objeto es hashable si tiene un valor de hash que nunca cambiará durante su tiempo de vida (necesita un método __hash__() ), y puede ser comparado con otro objeto (necesita el método __eq__() ). Los objetos hashables que se comparan iguales deben tener el mismo número hash.

Ser hashable hace a un objeto utilizable como clave de un diccionario y miembro de un set, porque éstas estructuras de datos usan los valores de hash internamente.

La mayoría de los objetos inmutables incorporados en Python son hashables; los contenedores mutables (como las listas o los diccionarios) no lo son; los contenedores inmutables (como tuplas y conjuntos frozensets) son hashables si sus elementos son hashables . Los objetos que son instancias de clases definidas por el usuario son hashables por defecto. Todos se comparan como desiguales (excepto consigo mismos), y su valor de hash está derivado de su función id().

IDLE

El entorno integrado de desarrollo de Python, o Integrated Development Environment for Python. IDLE es un editor básico y un entorno de intérprete que se incluye con la distribución estándar de Python.

inmutable

Un objeto con un valor fijo. Los objetos inmutables son números, cadenas y tuplas. Éstos objetos no pueden ser alterados. Un nuevo objeto debe ser creado si un valor diferente ha de ser guardado. Juegan un rol importante en lugares donde es necesario un valor de hash constante, por ejemplo como claves de un diccionario.

ruta de importación

Una lista de las ubicaciones (o entradas de ruta) que son revisadas por path based finder al importar módulos. Durante la importación, ésta lista de localizaciones usualmente viene de sys.path, pero para los subpaquetes también puede incluir al atributo __path__ del paquete padre.

importar

El proceso mediante el cual el código Python dentro de un módulo se hace alcanzable desde otro código Python en otro módulo.

importador

Un objeto que buscan y lee un módulo; un objeto que es tanto finder como loader.

interactivo

Python tiene un intérprete interactivo, lo que significa que puede ingresar sentencias y expresiones en el prompt del intérprete, ejecutarlos de inmediato y ver sus resultados. Sólo ejecute python sin argumentos (podría seleccionarlo desde el menú principal de su computadora). Es una forma muy potente de probar nuevas ideas o inspeccionar módulos y paquetes (recuerde help(x)).

interpretado

Python es un lenguaje interpretado, a diferencia de uno compilado, a pesar de que la distinción puede ser difusa debido al compilador a bytecode. Esto significa que los archivos fuente pueden ser corridos directamente, sin crear explícitamente un ejecutable que es corrido luego. Los lenguajes interpretados típicamente tienen ciclos de desarrollo y depuración más cortos que los compilados, sin embargo sus programas suelen correr más lentamente. Vea también interactive.

apagado del intérprete

Cuando se le solicita apagarse, el intérprete Python ingresa a un fase especial en la cual gradualmente libera todos los recursos reservados, como módulos y varias estructuras internas críticas. También hace varias llamadas al recolector de basura. Esto puede disparar la ejecución de código de destructores definidos por el usuario o weakref callbacks. El código ejecutado durante la fase de apagado puede encontrar varias excepciones debido a que los recursos que necesita pueden no funcionar más (ejemplos comunes son los módulos de bibliotecas o los artefactos de advertencias warnings machinery)

La principal razón para el apagado del intérpreter es que el módulo __main__ o el script que estaba corriendo termine su ejecución.

iterable

Un objeto capaz de retornar sus miembros uno por vez. Ejemplos de iterables son todos los tipos de secuencias (como list, str, y tuple) y algunos de tipos no secuenciales, como dict, objeto archivo, y objetos de cualquier clase que defina con los métodos __iter__() o con un método __getitem__() que implementen la semántica de Sequence.

Los iterables pueden ser usados en el bucle for y en muchos otros sitios donde una secuencia es necesaria (zip(), map(), …). Cuando un objeto iterable es pasado como argumento a la función incorporada iter(), retorna un iterador para el objeto. Este iterador pasa así el conjunto de valores. Cuando se usan iterables, normalmente no es necesario llamar a la función iter() o tratar con los objetos iteradores usted mismo. La sentencia for lo hace automáticamente por usted, creando un variable temporal sin nombre para mantener el iterador mientras dura el bucle. Vea también iterator, sequence, y generator.

iterador

Un objeto que representa un flujo de datos. Llamadas repetidas al método __next__() del iterador (o al pasar la función incorporada next()) retorna ítems sucesivos del flujo. Cuando no hay más datos disponibles, una excepción StopIteration es disparada. En este momento, el objeto iterador está exhausto y cualquier llamada posterior al método __next__() sólo dispara otra vez StopIteration. Los iteradores necesitan tener un método __iter__() que retorna el objeto iterador mismo así cada iterador es también un iterable y puede ser usado en casi todos los lugares donde los iterables son aceptados. Una excepción importante es el código que intenta múltiples pases de iteración. Un objeto contenedor (como la list) produce un nuevo iterador cada vez que pasa a una función iter() o se usa en un bucle for. Intentar ésto con un iterador simplemente retornaría el mismo objeto iterador exhausto usado en previas iteraciones, haciéndolo aparecer como un contenedor vacío.

Puede encontrar más información en Tipos de iteradores.

función clave

Una función clave o una función de colación es un invocable que retorna un valor usado para el ordenamiento o clasificación. Por ejemplo, locale.strxfrm() es usada para producir claves de ordenamiento que se adaptan a las convenciones específicas de ordenamiento de un locale.

Cierta cantidad de herramientas de Python aceptan funciones clave para controlar como los elementos son ordenados o agrupados. Incluyendo a min(), max(), sorted(), list.sort(), heapq.merge(), heapq.nsmallest(), heapq.nlargest(), y itertools.groupby().

Hay varias formas de crear una función clave. Por ejemplo, el método str.lower() puede servir como función clave para ordenamientos que no distingan mayúsculas de minúsculas. Como alternativa, una función clave puede ser realizada con una expresión lambda como lambda r: (r[0], r[2]). También, el módulo operator provee tres constructores de funciones clave: attrgetter(), itemgetter(), y methodcaller(). Vea en Sorting HOW TO ejemplos de cómo crear y usar funciones clave.

argumento nombrado

Vea argument.

lambda

Una función anónima de una línea consistente en un sola expression que es evaluada cuando la función es llamada. La sintaxis para crear una función lambda es lambda [parameters]: expression

LBYL

Del inglés Look before you leap, «mira antes de saltar». Es un estilo de codificación que prueba explícitamente las condiciones previas antes de hacer llamadas o búsquedas. Este estilo contrasta con la manera EAFP y está caracterizado por la presencia de muchas sentencias if.

En entornos multi-hilos, el método LBYL tiene el riesgo de introducir condiciones de carrera entre los hilos que están «mirando» y los que están «saltando». Por ejemplo, el código, if key in mapping: return mapping[key]` puede fallar si otro hilo remueve key de mapping después del test, pero antes de retornar el valor. Este problema puede ser resuelto usando bloqueos o empleando el método EAFP.

lista

Es una sequence Python incorporada. A pesar de su nombre es más similar a un arreglo en otros lenguajes que a una lista enlazada porque el acceso a los elementos es O(1).

comprensión de listas

Una forma compacta de procesar todos o parte de los elementos en una secuencia y retornar una lista como resultado. result = ['{:#04x}'.format(x) for x in range(256) if x % 2 == 0] genera una lista de cadenas conteniendo números hexadecimales (0x..) entre 0 y 255. La cláusula if es opcional. Si es omitida, todos los elementos en range(256) son procesados.

cargador

Un objeto que carga un módulo. Debe definir el método llamado load_module(). Un cargador es normalmente retornados por un finder. Vea PEP 302 [https://www.python.org/dev/peps/pep-0302] para detalles y importlib.abc.Loader para una abstract base class.

método mágico

Una manera informal de llamar a un special method.

mapeado

Un objeto contenedor que permite recupero de claves arbitrarias y que implementa los métodos especificados en la Mapping o MutableMapping abstract base classes. Por ejemplo, dict, collections.defaultdict, collections.OrderedDict y collections.Counter.

meta buscadores de ruta

Un finder retornado por una búsqueda de sys.meta_path. Los meta buscadores de ruta están relacionados a buscadores de entradas de rutas, pero son algo diferente.

Vea en importlib.abc.MetaPathFinder los métodos que los meta buscadores de ruta implementan.

metaclase

La clase de una clase. Las definiciones de clases crean nombres de clase, un diccionario de clase, y una lista de clases base. Las metaclases son responsables de tomar estos tres argumentos y crear la clase. La mayoría de los objetos de un lenguaje de programación orientado a objetos provienen de una implementación por defecto. Lo que hace a Python especial que es posible crear metaclases a medida. La mayoría de los usuario nunca necesitarán esta herramienta, pero cuando la necesidad surge, las metaclases pueden brindar soluciones poderosas y elegantes. Han sido usadas para loggear acceso de atributos, agregar seguridad a hilos, rastrear la creación de objetos, implementar singletons, y muchas otras tareas.

Más información hallará en Metaclases.

método

Una función que es definida dentro del cuerpo de una clase. Si es llamada como un atributo de una instancia de otra clase, el método tomará el objeto instanciado como su primer argument (el cual es usualmente denominado self). Vea function y nested scope.

orden de resolución de métodos

Orden de resolución de métodos es el orden en el cual una clase base es buscada por un miembro durante la búsqueda. Mire en The Python 2.3 Method Resolution Order [https://www.python.org/download/releases/2.3/mro/] los detalles del algoritmo usado por el intérprete Python desde la versión 2.3.

módulo

Un objeto que sirve como unidad de organización del código Python. Los módulos tienen espacios de nombres conteniendo objetos Python arbitrarios. Los módulos son cargados en Python por el proceso de importing.

Vea también package.

especificador de módulo

Un espacio de nombres que contiene la información relacionada a la importación usada al leer un módulo. Una instancia de importlib.machinery.ModuleSpec.

MRO

Vea method resolution order.

mutable

Los objetos mutables pueden cambiar su valor pero mantener su id(). Vea también immutable.

tupla nombrada

La denominación «tupla nombrada» se aplica a cualquier tipo o clase que hereda de una tupla y cuyos elementos indexables son también accesibles usando atributos nombrados. Este tipo o clase puede tener además otras capacidades.

Varios tipos incorporados son tuplas nombradas, incluyendo los valores retornados por time.localtime() y os.stat(). Otro ejemplo es sys.float_info:

>>> sys.float_info[1]                   # indexed access
1024
>>> sys.float_info.max_exp              # named field access
1024
>>> isinstance(sys.float_info, tuple)   # kind of tuple
True

Algunas tuplas nombradas con tipos incorporados (como en los ejemplo precedentes). También puede ser creada con una definición regular de clase que hereda de la clase tuple y que define campos nombrados. Una clase como esta puede ser hechas personalizadamente o puede ser creada con la función factoría collections.namedtuple(). Esta última técnica automáticamente brinda métodos adicionales que pueden no estar presentes en las tuplas nombradas personalizadas o incorporadas.

espacio de nombres

El lugar donde la variable es almacenada. Los espacios de nombres son implementados como diccionarios. Hay espacio de nombre local, global, e incorporado así como espacios de nombres anidados en objetos (en métodos). Los espacios de nombres soportan modularidad previniendo conflictos de nombramiento. Por ejemplo, las funciones builtins.open y os.open() se distinguen por su espacio de nombres. Los espacios de nombres también ayuda a la legibilidad y mantenibilidad dejando claro qué módulo implementa una función. Por ejemplo, escribiendo random.seed() o itertools.islice() queda claro que éstas funciones están implementadas en los módulos random y itertools, respectivamente.

paquete de espacios de nombres

Un PEP 420 [https://www.python.org/dev/peps/pep-0420] package que sirve sólo para contener subpaquetes. Los paquetes de espacios de nombres pueden no tener representación física, y específicamente se diferencian de los regular package porque no tienen un archivo __init__.py.

Vea también module.

alcances anidados

La habilidad de referirse a una variable dentro de una definición encerrada. Por ejemplo, una función definida dentro de otra función puede referir a variables en la función externa. Note que los alcances anidados por defecto sólo funcionan para referencia y no para asignación. Las variables locales leen y escriben sólo en el alcance más interno. De manera semejante, las variables globales pueden leer y escribir en el espacio de nombres global. Con nonlocal se puede escribir en alcances exteriores.

clase de nuevo estilo

Vieja denominación usada para el estilo de clases ahora empleado en todos los objetos de clase. En versiones más tempranas de Python, sólo las nuevas clases podían usar capacidades nuevas y versátiles de Python como __slots__, descriptores, propiedades, __getattribute__(), métodos de clase y métodos estáticos.

objeto

Cualquier dato con estado (atributo o valor) y comportamiento definido (métodos). También es la más básica clase base para cualquier new-style class.

paquete

Un module Python que puede contener submódulos o recursivamente, subpaquetes. Técnicamente, un paquete es un módulo Python con un atributo __path__.

Vea también regular package y namespace package.

parámetro

Una entidad nombrada en una definición de una function (o método) que especifica un argument (o en algunos casos, varios argumentos) que la función puede aceptar. Existen cinco tipos de argumentos:

posicional o nombrado: especifica un argumento que puede ser pasado tanto como posicional o como nombrado. Este es el tipo por defecto de parámetro, como foo y bar en el siguiente ejemplo:

def func(foo, bar=None): ...

sólo posicional: especifica un argumento que puede ser pasado sólo por posición. Los parámetros sólo posicionales pueden ser definidos incluyendo un carácter / en la lista de parámetros de la función después de ellos, como posonly1 y posonly2 en el ejemplo que sigue:

def func(posonly1, posonly2, /, positional_or_keyword): ...

sólo nombrado: especifica un argumento que sólo puede ser pasado por nombre. Los parámetros sólo por nombre pueden ser definidos incluyendo un parámetro posicional de una sola variable o un simple *` antes de ellos en la lista de parámetros en la definición de la función, como kw_only1 y kw_only2 en el ejemplo siguiente:

def func(arg, *, kw_only1, kw_only2): ...

variable posicional: especifica una secuencia arbitraria de argumentos posicionales que pueden ser brindados (además de cualquier argumento posicional aceptado por otros parámetros). Este parámetro puede ser definido anteponiendo al nombre del parámetro *, como a args en el siguiente ejemplo:

def func(*args, **kwargs): ...

variable nombrado: especifica que arbitrariamente muchos argumentos nombrados pueden ser brindados (además de cualquier argumento nombrado ya aceptado por cualquier otro parámetro). Este parámetro puede ser definido anteponiendo al nombre del parámetro con **, como kwargs en el ejemplo precedente.

Los parámetros puede especificar tanto argumentos opcionales como requeridos, así como valores por defecto para algunos argumentos opcionales.

Vea también el glosario de argument, la pregunta respondida en la diferencia entre argumentos y parámetros, la clase inspect.Parameter, la sección Definiciones de funciones , y PEP 362 [https://www.python.org/dev/peps/pep-0362].

entrada de ruta

Una ubicación única en el import path que el path based finder consulta para encontrar los módulos a importar.

buscador de entradas de ruta

Un finder retornado por un invocable en sys.path_hooks (esto es, un path entry hook) que sabe cómo localizar módulos dada una path entry.

Vea en importlib.abc.PathEntryFinder los métodos que los buscadores de entradas de ruta implementan.

gancho a entrada de ruta

Un invocable en la lista sys.path_hook que retorna un path entry finder si éste sabe cómo encontrar módulos en un path entry específico.

buscador basado en ruta

Uno de los meta buscadores de ruta por defecto que busca un import path para los módulos.

objeto tipo ruta

Un objeto que representa una ruta del sistema de archivos. Un objeto tipo ruta puede ser tanto una str como un bytes representando una ruta, o un objeto que implementa el protocolo os.PathLike. Un objeto que soporta el protocolo os.PathLike puede ser convertido a ruta del sistema de archivo de clase str o bytes usando la función os.fspath(); os.fsdecode() os.fsencode() pueden emplearse para garantizar que retorne respectivamente str o bytes. Introducido por PEP 519 [https://www.python.org/dev/peps/pep-0519].

PEP

Propuesta de mejora de Python, del inglés Python Enhancement Proposal. Un PEP es un documento de diseño que brinda información a la comunidad Python, o describe una nueva capacidad para Python, sus procesos o entorno. Los PEPs deberían dar una especificación técnica concisa y una fundamentación para las capacidades propuestas.

Los PEPs tienen como propósito ser los mecanismos primarios para proponer nuevas y mayores capacidad, para recoger la opinión de la comunidad sobre un tema, y para documentar las decisiones de diseño que se han hecho en Python. El autor del PEP es el responsable de lograr consenso con la comunidad y documentar las opiniones disidentes.

Vea PEP 1 [https://www.python.org/dev/peps/pep-0001].

porción

Un conjunto de archivos en un único directorio (posiblemente guardo en un archivo comprimido zip) que contribuye a un espacio de nombres de paquete, como está definido en PEP 420 [https://www.python.org/dev/peps/pep-0420].

argumento posicional

Vea argument.

API provisional

Una API provisoria es aquella que deliberadamente fue excluida de las garantías de compatibilidad hacia atrás de la biblioteca estándar. Aunque no se esperan cambios fundamentales en dichas interfaces, como están marcadas como provisionales, los cambios incompatibles hacia atrás (incluso remover la misma interfaz) podrían ocurrir si los desarrolladores principales lo estiman. Estos cambios no se hacen gratuitamente – solo ocurrirán si fallas fundamentales y serias son descubiertas que no fueron vistas antes de la inclusión de la API.

Incluso para APIs provisorias, los cambios incompatibles hacia atrás son vistos como una «solución de último recurso» - se intentará todo para encontrar una solución compatible hacia atrás para los problemas identificados.

Este proceso permite que la biblioteca estándar continúe evolucionando con el tiempo, sin bloquearse por errores de diseño problemáticos por períodos extensos de tiempo. Vea PEP 411 [https://www.python.org/dev/peps/pep-0411] para más detalles.

paquete provisorio

Vea provisional API.

Python 3000

Apodo para la fecha de lanzamiento de Python 3.x (acuñada en un tiempo cuando llegar a la versión 3 era algo distante en el futuro.) También se lo abrevió como Py3k.

Pythónico

Una idea o pieza de código que sigue ajustadamente la convenciones idiomáticas comunes del lenguaje Python, en vez de implementar código usando conceptos comunes a otros lenguajes. Por ejemplo, una convención común en Python es hacer bucles sobre todos los elementos de un iterable con la sentencia for. Muchos otros lenguajes no tienen este tipo de construcción, así que los que no están familiarizados con Python podrían usar contadores numéricos:

for i in range(len(food)):
    print(food[i])

En contraste, un método Pythónico más limpio:

for piece in food:
    print(piece)

nombre calificado

Un nombre con puntos mostrando la ruta desde el alcance global del módulo a la clase, función o método definido en dicho módulo, como se define en PEP 3155 [https://www.python.org/dev/peps/pep-3155]. Para las funciones o clases de más alto nivel, el nombre calificado es el igual al nombre del objeto:

>>> class C:
...     class D:
...         def meth(self):
...             pass
...
>>> C.__qualname__
'C'
>>> C.D.__qualname__
'C.D'
>>> C.D.meth.__qualname__
'C.D.meth'

Cuando es usado para referirse a los módulos, nombre completamente calificado significa la ruta con puntos completo al módulo, incluyendo cualquier paquete padre, por ejemplo, email.mime.text`:

>>> import email.mime.text
>>> email.mime.text.__name__
'email.mime.text'

contador de referencias

El número de referencias a un objeto. Cuando el contador de referencias de un objeto cae hasta cero, éste es desalojable. En conteo de referencias no suele ser visible en el código de Python, pero es un elemento clave para la implementación de CPython. El módulo sys define la getrefcount() que los programadores pueden emplear para retornar el conteo de referencias de un objeto en particular.

paquete regular

Un package tradicional, como aquellos con un directorio conteniendo el archivo __init__.py.

Vea también namespace package.

__slots__

Es una declaración dentro de una clase que ahorra memoria predeclarando espacio para las atributos de la instancia y eliminando diccionarios de la instancia. Aunque es popular, esta técnica es algo dificultosa de lograr correctamente y es mejor reservarla para los casos raros en los que existen grandes cantidades de instancias en aplicaciones con uso crítico de memoria.

secuencia

Un iterable que logra un acceso eficiente a los elementos usando índices enteros a través del método especial __getitem__() y que define un método __len__() que retorna la longitud de la secuencia. Algunas de las secuencias incorporadas son list, str, tuple, y bytes. Observe que dict también soporta __getitem__() y __len__(), pero es considerada un mapeo más que una secuencia porque las búsquedas son por claves arbitraria immutable y no por enteros.

La clase abstracta base collections.abc.Sequence define una interfaz mucho más rica que va más allá de sólo __getitem__() y __len__(), agregando count(), index(), __contains__(), y __reversed__(). Los tipos que implementan esta interfaz expandida pueden ser registrados explícitamente usando register().

comprensión de conjuntos

Una forma compacta de procesar todos o parte de los elementos en un iterable y retornar un conjunto con los resultados. results = {c for c in 'abracadabra' if c not in 'abc'} genera el conjunto de cadenas {'r', 'd'}. Ver Despliegues para listas, conjuntos y diccionarios.

despacho único

Una forma de despacho de una generic function donde la implementación es elegida a partir del tipo de un sólo argumento.

rebanada

Un objeto que contiene una porción de una sequence. Una rebanada es creada usando la notación de suscripto, [] con dos puntos entre los números cuando se ponen varios, como en nombre_variable[1:3:5]. La notación con corchete (suscrito) usa internamente objetos slice.

método especial

Un método que es llamado implícitamente por Python cuando ejecuta ciertas operaciones en un tipo, como la adición. Estos métodos tienen nombres que comienzan y terminan con doble barra baja. Los métodos especiales están documentados en Nombres especiales de método.

sentencia

Una sentencia es parte de un conjunto (un «bloque» de código). Una sentencia tanto es una expression como alguna de las varias sintaxis usando una palabra clave, como if, while o for.

codificación de texto

A string in Python is a sequence of Unicode code points (in range U+0000–U+10FFFF). To store or transfer a string, it needs to be serialized as a sequence of bytes.

Serializing a string into a sequence of bytes is known as «encoding», and recreating the string from the sequence of bytes is known as «decoding».

There are a variety of different text serialization codecs, which are collectively referred to as «text encodings».

archivo de texto

Un file object capaz de leer y escribir objetos str. Frecuentemente, un archivo de texto también accede a un flujo de datos binario y maneja automáticamente el text encoding. Ejemplos de archivos de texto que son abiertos en modo texto ('r' o 'w'), sys.stdin, sys.stdout, y las instancias de io.StringIO.

Vea también binary file por objeto de archivos capaces de leer y escribir objeto tipo binario.

cadena con triple comilla

Una cadena que está enmarcada por tres instancias de comillas (») o apostrofes (“). Aunque no brindan ninguna funcionalidad que no está disponible usando cadenas con comillas simple, son útiles por varias razones. Permiten incluir comillas simples o dobles sin escapar dentro de las cadenas y pueden abarcar múltiples líneas sin el uso de caracteres de continuación, haciéndolas particularmente útiles para escribir docstrings.

tipo

El tipo de un objeto Python determina qué tipo de objeto es; cada objeto tiene un tipo. El tipo de un objeto puede ser accedido por su atributo __class__ o puede ser conseguido usando type(obj).

alias de tipos

Un sinónimo para un tipo, creado al asignar un tipo a un identificador.

Los alias de tipos son útiles para simplificar los indicadores de tipo. Por ejemplo:

def remove_gray_shades(
        colors: list[tuple[int, int, int]]) -> list[tuple[int, int, int]]:
    pass

podría ser más legible así:

Color = tuple[int, int, int]

def remove_gray_shades(colors: list[Color]) -> list[Color]:
    pass

Vea typing y PEP 484 [https://www.python.org/dev/peps/pep-0484], que describen esta funcionalidad.

indicador de tipo

Una annotation que especifica el tipo esperado para una variable, un atributo de clase, un parámetro para una función o un valor de retorno.

Los indicadores de tipo son opcionales y no son obligados por Python pero son útiles para las herramientas de análisis de tipos estático, y ayuda a las IDE en el completado del código y la refactorización.

Los indicadores de tipo de las variables globales, atributos de clase, y funciones, no de variables locales, pueden ser accedidos usando typing.get_type_hints().

Vea typing y PEP 484 [https://www.python.org/dev/peps/pep-0484], que describen esta funcionalidad.

saltos de líneas universales

Una manera de interpretar flujos de texto en la cual son reconocidos como finales de línea todas siguientes formas: la convención de Unix para fin de línea '\n', la convención de Windows '\r\n', y la vieja convención de Macintosh '\r'. Vea PEP 278 [https://www.python.org/dev/peps/pep-0278] y PEP 3116 [https://www.python.org/dev/peps/pep-3116], además de bytes.splitlines() para usos adicionales.

anotación de variable

Una annotation de una variable o un atributo de clase.

Cuando se anota una variable o un atributo de clase, la asignación es opcional:

class C:
    field: 'annotation'

Las anotaciones de variables son frecuentemente usadas para type hints: por ejemplo, se espera que esta variable tenga valores de clase int:

count: int = 0

La sintaxis de la anotación de variables está explicada en la sección Declaraciones de asignación anotadas.

Vea function annotation, PEP 484 [https://www.python.org/dev/peps/pep-0484] y PEP 526 [https://www.python.org/dev/peps/pep-0526], los cuales describen esta funcionalidad.

entorno virtual

Un entorno cooperativamente aislado de ejecución que permite a los usuarios de Python y a las aplicaciones instalar y actualizar paquetes de distribución de Python sin interferir con el comportamiento de otras aplicaciones de Python en el mismo sistema.

Vea también venv.

máquina virtual

Una computadora definida enteramente por software. La máquina virtual de Python ejecuta el bytecode generado por el compilador de bytecode.

Zen de Python

Un listado de los principios de diseño y la filosofía de Python que son útiles para entender y usar el lenguaje. El listado puede encontrarse ingresando «import this» en la consola interactiva.

Acerca de estos documentos

Estos documentos son generados por reStructuredText [http://docutils.sourceforge.net/rst.html] desarrollado por Sphinx [http://sphinx-doc.org/], un procesador de documentos específicamente escrito para la documentación de Python.

El desarrollo de la documentación y su cadena de herramientas es un esfuerzo enteramente voluntario, al igual que Python. Si tu quieres contribuir, por favor revisa la página Lidiar con errores para más información de cómo hacerlo. Los nuevos voluntarios son siempre bienvenidos!

Agradecemos a:

Fred L. Drake, Jr., el creador original de la documentación del conjunto de herramientas de Python y escritor de gran parte del contenido;

el proyecto Docutils [http://docutils.sourceforge.net/] para creación de reStructuredText y el juego de Utilidades de Documentación;

Fredrik Lundh for his Alternative Python Reference project from which Sphinx got many good ideas.

Contribuidores de la documentación de Python

Muchas personas han contribuido para el lenguaje de Python, la librería estándar de Python, y la documentación de Python. Revisa Misc/ACKS [https://github.com/python/cpython/tree/3.9/Misc/ACKS] la distribución de Python para una lista parcial de contribuidores.

Es solamente con la aportación y contribuciones de la comunidad de Python que Python tiene tan fantástica documentación – Muchas gracias!

Lidiar con errores

Python es un lenguaje de programación maduro que ha establecido una reputación de estabilidad. Con el fin de mantener esta reputación, a los desarrolladores les gustaría conocer cualquier anomalía que encuentre en Python.

A veces puede ser más rápido corregir errores y añadir parches a Python, ya que agiliza el proceso e involucra a menos personas. Aprenda a contribuir.

Documentación de errores

Si encuentras un error en esta documentación o te gustaría proponer una mejora, por favor envía un informe de fallos en el rastreador. Si tienes una sugerencia sobre cómo arreglarlo, inclúyela también.

Si tienes poco tiempo, también puedes enviar un correo electrónico con el informe de errores de documentación a la dirección docs@python.org (los errores de comportamiento puedes enviarlos a la dirección python-list@python.org). “docs@” es una lista de correo iniciada por voluntarios; tu petición será notificada, aunque puede que lleve algo de tiempo el ser procesada.

Ver también

Documentación de errores

Una lista de errores (bugs) que ha sido enviada al issue tracker (sistema de seguimiento de incidentes) de Python.

Seguimiento de incidencias [https://devguide.python.org/tracker/]

Resumen general del proceso necesario para reportar una mejora en el tracker.

Ayudar con la documentación [https://devguide.python.org/docquality/#helping-with-documentation]

Guía detallada para gente interesada en contribuir a la documentación de Python.

Documentation Translations [https://devguide.python.org/documenting/#translating]

A list of GitHub pages for documentation translation and their primary contacts.

Utilizar el issue tracker de Python

Issue reports for Python itself should be submitted via the GitHub issues tracker (https://github.com/python/cpython/issues). The GitHub issues tracker offers a web form which allows pertinent information to be entered and submitted to the developers.

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 tracker using the search box at the top of the page.

If the problem you’re reporting is not already in the list, log in to GitHub. If you don’t already have a GitHub account, create a new account using the «Sign up» link. It is not possible to submit a bug report anonymously.

Being now logged in, you can submit an issue. Click on the «New issue» button in the top bar to report a new issue.

The submission form has two fields, «Title» and «Comment».

For the «Title» field, enter a very short description of the problem; less than ten words is good.

En el campo «Comment», describe el problema con detalle, incluyendo qué esperabas que ocurriera y que ha sucedido en realidad. Asegúrate de incluir si cualquier módulo de extensión está involucrado, y qué plataformas de hardware y software estás usando (incluyendo las versiones correspondientes).

Each issue report will be reviewed by a developer who will determine what needs to be done to correct the problem. You will receive an update each time an action is taken on the issue.

Ver también

Cómo informar de errores de manera efectiva [https://www.chiark.greenend.org.uk/~sgtatham/bugs.html]

Artículo que detalla cómo crear un informe de errores útil. Describe qué tipo de información es útil y por qué lo es.

Bug Writing Guidelines [https://bugzilla.mozilla.org/page.cgi?id=bug-writing.html]

Información sobre cómo escribir un buen informe de errores. Parte de esta información es específica al proyecto Mozilla, pero en general describe buenas prácticas.

Para empezar a contribuir en Python

Más allá de informar de los errores que puedas encontrar, te damos la bienvenida a enviar parches para corregirlos. Puedes encontrar más información en cómo empezar parcheando Python en la Python Developer’s Guide [https://devguide.python.org/]. Si tienes preguntas, el core-mentorship mailing list [https://mail.python.org/mailman3/lists/core-mentorship.python.org/] es un agradable lugar para obtener respuestas a cualquiera y a todas las preguntas pertenecientes al proceso de corrección de problemas en Python.

Derechos de autor

Python y esta documentación es:

Copyright © 2001-2023 Python Software Foundation. All rights reserved.

Derechos de autor © 2000 BeOpen.com. Todos los derechos reservados.

Derechos de autor © 1995-2000 Corporation for National Research Initiatives. Todos los derechos reservados.

Derechos de autor © 1991-1995 Stichting Mathematisch Centrum. Todos los derechos reservados.

Consulte Historia y Licencia para obtener información completa sobre licencias y permisos.

Historia y Licencia

Historia del software

Python fue creado a principios de la década de 1990 por Guido van Rossum en Stichting Mathematisch Centrum (CWI, ver https://www.cwi.nl/) en los Países Bajos como sucesor de un idioma llamado ABC. Guido sigue siendo el autor principal de Python, aunque incluye muchas contribuciones de otros.

En 1995, Guido continuó su trabajo en Python en la Corporation for National Research Initiatives (CNRI, consulte https://www.cnri.reston.va.us/) en Reston, Virginia, donde lanzó varias versiones del software.

En mayo de 2000, Guido y el equipo de desarrollo central de Python se trasladaron a BeOpen.com para formar el equipo de BeOpen PythonLabs. En octubre del mismo año, el equipo de PythonLabs se trasladó a Digital Creations (ahora Zope Corporation; consulte https://www.zope.org/). En 2001, se formó la Python Software Foundation (PSF, consulte https://www.python.org/psf/), una organización sin fines de lucro creada específicamente para poseer la propiedad intelectual relacionada con Python. Zope Corporation es miembro patrocinador del PSF.

Todas las versiones de Python son de código abierto (consulte https://opensource.org/ para conocer la definición de código abierto). Históricamente, la mayoría de las versiones de Python, pero no todas, también han sido compatibles con GPL; la siguiente tabla resume las distintas versiones.

Lanzamiento

Derivado de

Año

Dueño/a

¿compatible con GPL?

0.9.0 hasta 1.2

n/a

1991-1995

CWI

sí

1.3 hasta 1.5.2

1.2

1995-1999

CNRI

sí

1.6

1.5.2

2000

CNRI

no

2.0

1.6

2000

BeOpen.com

no

1.6.1

1.6

2001

CNRI

no

2.1

2.0+1.6.1

2001

PSF

no

2.0.1

2.0+1.6.1

2001

PSF

sí

2.1.1

2.1+2.0.1

2001

PSF

sí

2.1.2

2.1.1

2002

PSF

sí

2.1.3

2.1.2

2002

PSF

sí

2.2 y superior

2.1.1

2001-ahora

PSF

sí

Nota

Compatible con GPL no significa que estemos distribuyendo Python bajo la GPL. Todas las licencias de Python, a diferencia de la GPL, le permiten distribuir una versión modificada sin que los cambios sean de código abierto. Las licencias compatibles con GPL permiten combinar Python con otro software que se publica bajo la GPL; los otros no lo hacen.

Gracias a los muchos voluntarios externos que han trabajado bajo la dirección de Guido para hacer posibles estos lanzamientos.

Términos y condiciones para acceder o usar Python

El software y la documentación de Python están sujetos a Acuerdo de licencia de PSF.

A partir de Python 3.8.6, los ejemplos, recetas y otros códigos de la documentación tienen licencia doble según el Acuerdo de licencia de PSF y la Licencia BSD de cláusula cero.

Parte del software incorporado en Python está bajo diferentes licencias. Las licencias se enumeran con el código correspondiente a esa licencia. Consulte Licencias y reconocimientos para software incorporado para obtener una lista incompleta de estas licencias.

ACUERDO DE LICENCIA DE PSF PARA PYTHON | lanzamiento |

1. This LICENSE AGREEMENT is between the Python Software Foundation ("PSF"), and
   the Individual or Organization ("Licensee") accessing and otherwise using Python
   3.9.18 software in source or binary form and its associated documentation.

2. Subject to the terms and conditions of this License Agreement, PSF hereby
   grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce,
   analyze, test, perform and/or display publicly, prepare derivative works,
   distribute, and otherwise use Python 3.9.18 alone or in any derivative
   version, provided, however, that PSF's License Agreement and PSF's notice of
   copyright, i.e., "Copyright © 2001-2023 Python Software Foundation; All Rights
   Reserved" are retained in Python 3.9.18 alone or in any derivative version
   prepared by Licensee.

3. In the event Licensee prepares a derivative work that is based on or
   incorporates Python 3.9.18 or any part thereof, and wants to make the
   derivative work available to others as provided herein, then Licensee hereby
   agrees to include in any such work a brief summary of the changes made to Python
   3.9.18.

4. PSF is making Python 3.9.18 available to Licensee on an "AS IS" basis.
   PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED.  BY WAY OF
   EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND DISCLAIMS ANY REPRESENTATION OR
   WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE
   USE OF PYTHON 3.9.18 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON 3.9.18
   FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF
   MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 3.9.18, OR ANY DERIVATIVE
   THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

6. This License Agreement will automatically terminate upon a material breach of
   its terms and conditions.

7. Nothing in this License Agreement shall be deemed to create any relationship
   of agency, partnership, or joint venture between PSF and Licensee.  This License
   Agreement does not grant permission to use PSF trademarks or trade name in a
   trademark sense to endorse or promote products or services of Licensee, or any
   third party.

8. By copying, installing or otherwise using Python 3.9.18, Licensee agrees
   to be bound by the terms and conditions of this License Agreement.

ACUERDO DE LICENCIA DE BEOPEN.COM PARA PYTHON 2.0

ACUERDO DE LICENCIA DE CÓDIGO ABIERTO DE BEOPEN PYTHON VERSIÓN 1

1. This LICENSE AGREEMENT is between BeOpen.com ("BeOpen"), having an office at
   160 Saratoga Avenue, Santa Clara, CA 95051, and the Individual or Organization
   ("Licensee") accessing and otherwise using this software in source or binary
   form and its associated documentation ("the Software").

2. Subject to the terms and conditions of this BeOpen Python License Agreement,
   BeOpen hereby grants Licensee a non-exclusive, royalty-free, world-wide license
   to reproduce, analyze, test, perform and/or display publicly, prepare derivative
   works, distribute, and otherwise use the Software alone or in any derivative
   version, provided, however, that the BeOpen Python License is retained in the
   Software, alone or in any derivative version prepared by Licensee.

3. BeOpen is making the Software available to Licensee on an "AS IS" basis.
   BEOPEN MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED.  BY WAY OF
   EXAMPLE, BUT NOT LIMITATION, BEOPEN MAKES NO AND DISCLAIMS ANY REPRESENTATION OR
   WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE
   USE OF THE SOFTWARE WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

4. BEOPEN SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF THE SOFTWARE FOR
   ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF USING,
   MODIFYING OR DISTRIBUTING THE SOFTWARE, OR ANY DERIVATIVE THEREOF, EVEN IF
   ADVISED OF THE POSSIBILITY THEREOF.

5. This License Agreement will automatically terminate upon a material breach of
   its terms and conditions.

6. This License Agreement shall be governed by and interpreted in all respects
   by the law of the State of California, excluding conflict of law provisions.
   Nothing in this License Agreement shall be deemed to create any relationship of
   agency, partnership, or joint venture between BeOpen and Licensee.  This License
   Agreement does not grant permission to use BeOpen trademarks or trade names in a
   trademark sense to endorse or promote products or services of Licensee, or any
   third party.  As an exception, the "BeOpen Python" logos available at
   http://www.pythonlabs.com/logos.html may be used according to the permissions
   granted on that web page.

7. By copying, installing or otherwise using the software, Licensee agrees to be
   bound by the terms and conditions of this License Agreement.

ACUERDO DE LICENCIA CNRI PARA PYTHON 1.6.1

1. This LICENSE AGREEMENT is between the Corporation for National Research
   Initiatives, having an office at 1895 Preston White Drive, Reston, VA 20191
   ("CNRI"), and the Individual or Organization ("Licensee") accessing and
   otherwise using Python 1.6.1 software in source or binary form and its
   associated documentation.

2. Subject to the terms and conditions of this License Agreement, CNRI hereby
   grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce,
   analyze, test, perform and/or display publicly, prepare derivative works,
   distribute, and otherwise use Python 1.6.1 alone or in any derivative version,
   provided, however, that CNRI's License Agreement and CNRI's notice of copyright,
   i.e., "Copyright © 1995-2001 Corporation for National Research Initiatives; All
   Rights Reserved" are retained in Python 1.6.1 alone or in any derivative version
   prepared by Licensee.  Alternately, in lieu of CNRI's License Agreement,
   Licensee may substitute the following text (omitting the quotes): "Python 1.6.1
   is made available subject to the terms and conditions in CNRI's License
   Agreement.  This Agreement together with Python 1.6.1 may be located on the
   Internet using the following unique, persistent identifier (known as a handle):
   1895.22/1013.  This Agreement may also be obtained from a proxy server on the
   Internet using the following URL: http://hdl.handle.net/1895.22/1013."

3. In the event Licensee prepares a derivative work that is based on or
   incorporates Python 1.6.1 or any part thereof, and wants to make the derivative
   work available to others as provided herein, then Licensee hereby agrees to
   include in any such work a brief summary of the changes made to Python 1.6.1.

4. CNRI is making Python 1.6.1 available to Licensee on an "AS IS" basis.  CNRI
   MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED.  BY WAY OF EXAMPLE,
   BUT NOT LIMITATION, CNRI MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY
   OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF
   PYTHON 1.6.1 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

5. CNRI SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON 1.6.1 FOR
   ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF
   MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 1.6.1, OR ANY DERIVATIVE
   THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

6. This License Agreement will automatically terminate upon a material breach of
   its terms and conditions.

7. This License Agreement shall be governed by the federal intellectual property
   law of the United States, including without limitation the federal copyright
   law, and, to the extent such U.S. federal law does not apply, by the law of the
   Commonwealth of Virginia, excluding Virginia's conflict of law provisions.
   Notwithstanding the foregoing, with regard to derivative works based on Python
   1.6.1 that incorporate non-separable material that was previously distributed
   under the GNU General Public License (GPL), the law of the Commonwealth of
   Virginia shall govern this License Agreement only as to issues arising under or
   with respect to Paragraphs 4, 5, and 7 of this License Agreement.  Nothing in
   this License Agreement shall be deemed to create any relationship of agency,
   partnership, or joint venture between CNRI and Licensee.  This License Agreement
   does not grant permission to use CNRI trademarks or trade name in a trademark
   sense to endorse or promote products or services of Licensee, or any third
   party.

8. By clicking on the "ACCEPT" button where indicated, or by copying, installing
   or otherwise using Python 1.6.1, Licensee agrees to be bound by the terms and
   conditions of this License Agreement.

ACUERDO DE LICENCIA CWI PARA PYTHON 0.9.0 HASTA 1.2

Copyright © 1991 - 1995, Stichting Mathematisch Centrum Amsterdam, The
Netherlands.  All rights reserved.

Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted, provided that
the above copyright notice appear in all copies and that both that copyright
notice and this permission notice appear in supporting documentation, and that
the name of Stichting Mathematisch Centrum or CWI not be used in advertising or
publicity pertaining to distribution of the software without specific, written
prior permission.

STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE FOR ANY SPECIAL, INDIRECT
OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
SOFTWARE.

LICENCIA BSD DE CLÁUSULA CERO PARA CÓDIGO EN EL PYTHON | lanzamiento | DOCUMENTACIÓN

Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE.

Licencias y reconocimientos para software incorporado

Esta sección es una lista incompleta, pero creciente, de licencias y reconocimientos para software de terceros incorporado en la distribución de Python.

Mersenne Twister

El módulo _random incluye código basado en una descarga de http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/MT2002/emt19937ar.html. Los siguientes son los comentarios textuales del código original:

A C-program for MT19937, with initialization improved 2002/1/26.
Coded by Takuji Nishimura and Makoto Matsumoto.

Before using, initialize the state by using init_genrand(seed)
or init_by_array(init_key, key_length).

Copyright (C) 1997 - 2002, Makoto Matsumoto and Takuji Nishimura,
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

 1. Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.

 2. Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.

 3. The names of its contributors may not be used to endorse or promote
    products derived from this software without specific prior written
    permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Any feedback is very welcome.
http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html
email: m-mat @ math.sci.hiroshima-u.ac.jp (remove space)

Sockets

El módulo socket usa las funciones, getaddrinfo(), y getnameinfo(), que están codificadas en archivos fuente separados del Proyecto WIDE, http://www.wide.ad.jp /.

Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project.
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
3. Neither the name of the project nor the names of its contributors
   may be used to endorse or promote products derived from this software
   without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

Servicios de socket asincrónicos

Los módulos asynchat y asyncore contienen el siguiente aviso:

Copyright 1996 by Sam Rushing

                        All Rights Reserved

Permission to use, copy, modify, and distribute this software and
its documentation for any purpose and without fee is hereby
granted, provided that the above copyright notice appear in all
copies and that both that copyright notice and this permission
notice appear in supporting documentation, and that the name of Sam
Rushing not be used in advertising or publicity pertaining to
distribution of the software without specific, written prior
permission.

SAM RUSHING DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN
NO EVENT SHALL SAM RUSHING BE LIABLE FOR ANY SPECIAL, INDIRECT OR
CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Gestión de cookies

El módulo http.cookies contiene el siguiente aviso:

Copyright 2000 by Timothy O'Malley <timo@alum.mit.edu>

               All Rights Reserved

Permission to use, copy, modify, and distribute this software
and its documentation for any purpose and without fee is hereby
granted, provided that the above copyright notice appear in all
copies and that both that copyright notice and this permission
notice appear in supporting documentation, and that the name of
Timothy O'Malley  not be used in advertising or publicity
pertaining to distribution of the software without specific, written
prior permission.

Timothy O'Malley DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS, IN NO EVENT SHALL Timothy O'Malley BE LIABLE FOR
ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE.

Seguimiento de ejecución

El módulo trace contiene el siguiente aviso:

portions copyright 2001, Autonomous Zones Industries, Inc., all rights...
err...  reserved and offered to the public under the terms of the
Python 2.2 license.
Author: Zooko O'Whielacronx
http://zooko.com/
mailto:zooko@zooko.com

Copyright 2000, Mojam Media, Inc., all rights reserved.
Author: Skip Montanaro

Copyright 1999, Bioreason, Inc., all rights reserved.
Author: Andrew Dalke

Copyright 1995-1997, Automatrix, Inc., all rights reserved.
Author: Skip Montanaro

Copyright 1991-1995, Stichting Mathematisch Centrum, all rights reserved.

Permission to use, copy, modify, and distribute this Python software and
its associated documentation for any purpose without fee is hereby
granted, provided that the above copyright notice appears in all copies,
and that both that copyright notice and this permission notice appear in
supporting documentation, and that the name of neither Automatrix,
Bioreason or Mojam Media be used in advertising or publicity pertaining to
distribution of the software without specific, written prior permission.

funciones UUencode y UUdecode

El módulo uu contiene el siguiente aviso:

Copyright 1994 by Lance Ellinghouse
Cathedral City, California Republic, United States of America.
                       All Rights Reserved
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation, and that the name of Lance Ellinghouse
not be used in advertising or publicity pertaining to distribution
of the software without specific, written prior permission.
LANCE ELLINGHOUSE DISCLAIMS ALL WARRANTIES WITH REGARD TO
THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS, IN NO EVENT SHALL LANCE ELLINGHOUSE CENTRUM BE LIABLE
FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Modified by Jack Jansen, CWI, July 1995:
- Use binascii module to do the actual line-by-line conversion
  between ascii and binary. This results in a 1000-fold speedup. The C
  version is still 5 times faster, though.
- Arguments more compliant with Python standard

Llamadas a procedimientos remotos XML

El módulo xmlrpc.client contiene el siguiente aviso:

    The XML-RPC client interface is

Copyright (c) 1999-2002 by Secret Labs AB
Copyright (c) 1999-2002 by Fredrik Lundh

By obtaining, using, and/or copying this software and/or its
associated documentation, you agree that you have read, understood,
and will comply with the following terms and conditions:

Permission to use, copy, modify, and distribute this software and
its associated documentation for any purpose and without fee is
hereby granted, provided that the above copyright notice appears in
all copies, and that both that copyright notice and this permission
notice appear in supporting documentation, and that the name of
Secret Labs AB or the author not be used in advertising or publicity
pertaining to distribution of the software without specific, written
prior permission.

SECRET LABS AB AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD
TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANT-
ABILITY AND FITNESS.  IN NO EVENT SHALL SECRET LABS AB OR THE AUTHOR
BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY
DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
OF THIS SOFTWARE.

test_epoll

El módulo test_epoll contiene el siguiente aviso:

Copyright (c) 2001-2006 Twisted Matrix Laboratories.

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Seleccionar kqueue

El módulo select contiene el siguiente aviso para la interfaz kqueue:

Copyright (c) 2000 Doug White, 2006 James Knight, 2007 Christian Heimes
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

SipHash24

El archivo Python/pyhash.c contiene la implementación de Marek Majkowski del algoritmo SipHash24 de Dan Bernstein. Contiene la siguiente nota:

<MIT License>
Copyright (c) 2013  Marek Majkowski <marek@popcount.org>

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
</MIT License>

Original location:
   https://github.com/majek/csiphash/

Solution inspired by code from:
   Samuel Neves (supercop/crypto_auth/siphash24/little)
   djb (supercop/crypto_auth/siphash24/little2)
   Jean-Philippe Aumasson (https://131002.net/siphash/siphash24.c)

strtod y dtoa

El archivo Python/dtoa.c, que proporciona las funciones de C dtoa y strtod para la conversión de C dobles hacia y desde cadenas, se deriva del archivo del mismo nombre de David M. Gay, actualmente disponible en http://www.netlib.org/fp/. El archivo original, recuperado el 16 de marzo de 2009, contiene el siguiente aviso de licencia y derechos de autor:

/****************************************************************
 *
 * The author of this software is David M. Gay.
 *
 * Copyright (c) 1991, 2000, 2001 by Lucent Technologies.
 *
 * Permission to use, copy, modify, and distribute this software for any
 * purpose without fee is hereby granted, provided that this entire notice
 * is included in all copies of any software which is or includes a copy
 * or modification of this software and in all copies of the supporting
 * documentation for such software.
 *
 * THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED
 * WARRANTY.  IN PARTICULAR, NEITHER THE AUTHOR NOR LUCENT MAKES ANY
 * REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY
 * OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.
 *
 ***************************************************************/

OpenSSL

The modules hashlib, posix, ssl, crypt use the OpenSSL library for added performance if made available by the operating system. Additionally, the Windows and macOS installers for Python may include a copy of the OpenSSL libraries, so we include a copy of the OpenSSL license here:

 LICENSE ISSUES
 ==============

 The OpenSSL toolkit stays under a dual license, i.e. both the conditions of
 the OpenSSL License and the original SSLeay license apply to the toolkit.
 See below for the actual license texts. Actually both licenses are BSD-style
 Open Source licenses. In case of any license issues related to OpenSSL
 please contact openssl-core@openssl.org.

 OpenSSL License
 ---------------

   /* ====================================================================
    * Copyright (c) 1998-2008 The OpenSSL Project.  All rights reserved.
    *
    * Redistribution and use in source and binary forms, with or without
    * modification, are permitted provided that the following conditions
    * are met:
    *
    * 1. Redistributions of source code must retain the above copyright
    *    notice, this list of conditions and the following disclaimer.
    *
    * 2. Redistributions in binary form must reproduce the above copyright
    *    notice, this list of conditions and the following disclaimer in
    *    the documentation and/or other materials provided with the
    *    distribution.
    *
    * 3. All advertising materials mentioning features or use of this
    *    software must display the following acknowledgment:
    *    "This product includes software developed by the OpenSSL Project
    *    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
    *
    * 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
    *    endorse or promote products derived from this software without
    *    prior written permission. For written permission, please contact
    *    openssl-core@openssl.org.
    *
    * 5. Products derived from this software may not be called "OpenSSL"
    *    nor may "OpenSSL" appear in their names without prior written
    *    permission of the OpenSSL Project.
    *
    * 6. Redistributions of any form whatsoever must retain the following
    *    acknowledgment:
    *    "This product includes software developed by the OpenSSL Project
    *    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
    *
    * THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
    * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
    * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
    * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
    * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
    * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
    * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
    * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
    * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
    * OF THE POSSIBILITY OF SUCH DAMAGE.
    * ====================================================================
    *
    * This product includes cryptographic software written by Eric Young
    * (eay@cryptsoft.com).  This product includes software written by Tim
    * Hudson (tjh@cryptsoft.com).
    *
    */

Original SSLeay License
-----------------------

   /* Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com)
    * All rights reserved.
    *
    * This package is an SSL implementation written
    * by Eric Young (eay@cryptsoft.com).
    * The implementation was written so as to conform with Netscapes SSL.
    *
    * This library is free for commercial and non-commercial use as long as
    * the following conditions are aheared to.  The following conditions
    * apply to all code found in this distribution, be it the RC4, RSA,
    * lhash, DES, etc., code; not just the SSL code.  The SSL documentation
    * included with this distribution is covered by the same copyright terms
    * except that the holder is Tim Hudson (tjh@cryptsoft.com).
    *
    * Copyright remains Eric Young's, and as such any Copyright notices in
    * the code are not to be removed.
    * If this package is used in a product, Eric Young should be given attribution
    * as the author of the parts of the library used.
    * This can be in the form of a textual message at program startup or
    * in documentation (online or textual) provided with the package.
    *
    * Redistribution and use in source and binary forms, with or without
    * modification, are permitted provided that the following conditions
    * are met:
    * 1. Redistributions of source code must retain the copyright
    *    notice, this list of conditions and the following disclaimer.
    * 2. Redistributions in binary form must reproduce the above copyright
    *    notice, this list of conditions and the following disclaimer in the
    *    documentation and/or other materials provided with the distribution.
    * 3. All advertising materials mentioning features or use of this software
    *    must display the following acknowledgement:
    *    "This product includes cryptographic software written by
    *     Eric Young (eay@cryptsoft.com)"
    *    The word 'cryptographic' can be left out if the rouines from the library
    *    being used are not cryptographic related :-).
    * 4. If you include any Windows specific code (or a derivative thereof) from
    *    the apps directory (application code) you must include an acknowledgement:
    *    "This product includes software written by Tim Hudson (tjh@cryptsoft.com)"
    *
    * THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND
    * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
    * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
    * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
    * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
    * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
    * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
    * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
    * SUCH DAMAGE.
    *
    * The licence and distribution terms for any publically available version or
    * derivative of this code cannot be changed.  i.e. this code cannot simply be
    * copied and put under another distribution licence
    * [including the GNU Public Licence.]
    */

expat

La extensión pyexpat se construye usando una copia incluida de las fuentes de expatriados a menos que la construcción esté configurada --with-system-expat:

Copyright (c) 1998, 1999, 2000 Thai Open Source Software Center Ltd
                               and Clark Cooper

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

libffi

La extensión _ctypes se construye usando una copia incluida de las fuentes de libffi a menos que la construcción esté configurada --with-system-libffi:

Copyright (c) 1996-2008  Red Hat, Inc and others.

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
``Software''), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.

zlib

La extensión zlib se crea utilizando una copia incluida de las fuentes de zlib si la versión de zlib encontrada en el sistema es demasiado antigua para ser utilizada para la compilación:

Copyright (C) 1995-2011 Jean-loup Gailly and Mark Adler

This software is provided 'as-is', without any express or implied
warranty.  In no event will the authors be held liable for any damages
arising from the use of this software.

Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; you must not
   claim that you wrote the original software. If you use this software
   in a product, an acknowledgment in the product documentation would be
   appreciated but is not required.

2. Altered source versions must be plainly marked as such, and must not be
   misrepresented as being the original software.

3. This notice may not be removed or altered from any source distribution.

Jean-loup Gailly        Mark Adler
jloup@gzip.org          madler@alumni.caltech.edu

cfuhash

La implementación de la tabla hash utilizada por tracemalloc se basa en el proyecto cfuhash:

Copyright (c) 2005 Don Owens
All rights reserved.

This code is released under the BSD license:

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

  * Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.

  * Redistributions in binary form must reproduce the above
    copyright notice, this list of conditions and the following
    disclaimer in the documentation and/or other materials provided
    with the distribution.

  * Neither the name of the author nor the names of its
    contributors may be used to endorse or promote products derived
    from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
OF THE POSSIBILITY OF SUCH DAMAGE.

libmpdec

El módulo _decimal se construye usando una copia incluida de la biblioteca libmpdec a menos que la construcción esté configurada --with-system-libmpdec:

Copyright (c) 2008-2020 Stefan Krah. All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

Conjunto de pruebas W3C C14N

The C14N 2.0 test suite in the test package (Lib/test/xmltestdata/c14n-20/) was retrieved from the W3C website at https://www.w3.org/TR/xml-c14n2-testcases/ and is distributed under the 3-clause BSD license:

Copyright (c) 2013 W3C(R) (MIT, ERCIM, Keio, Beihang),
All Rights Reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

* Redistributions of works must retain the original copyright notice,
  this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the original copyright
  notice, this list of conditions and the following disclaimer in the
  documentation and/or other materials provided with the distribution.
* Neither the name of the W3C nor the names of its contributors may be
  used to endorse or promote products derived from this work without
  specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Distribución de módulos de Python (versión heredada)

Autores

Greg Ward, Anthony Baxter

Email

distutils-sig@python.org

Ver también

Distribuir módulos de Python

La documentación de distribución de módulos actualizada

Nota

This document is being retained solely until the setuptools documentation at https://setuptools.readthedocs.io/en/latest/setuptools.html independently covers all of the relevant information currently included here.

Nota

Esta guía solo cubre las herramientas básicas para compilar y distribuir extensiones que se proporcionan como parte de esta versión de Python. Las herramientas de terceros ofrecen alternativas más seguras y más fáciles de usar. Consulte la sección de recomendaciones rápidas [https://packaging.python.org/guides/tool-recommendations/] en la Guía del usuario de Python Packaging para obtener más información.

Este documento describe las utilidades de distribución de Python («Distutils») desde el punto de vista del desarrollador del módulo, describiendo las capacidades subyacentes sobre las que se basan las setuptools para permitir que los desarrolladores de Python hagan que los módulos y extensiones de Python estén disponibles para una audiencia más amplia.

1. Una introducción a Distutils

1.1. Conceptos y Terminología

1.2. Un ejemplo simple

1.3. Terminología general de Python

1.4. Terminología específica de Distutils

2. Escribir el script de configuración

2.1. Listado de paquetes completos

2.2. Listado de módulos individuales

2.3. Describiendo módulos de extensión

2.4. Relaciones entre distribuciones y paquetes

2.5. Instalar scripts

2.6. Instalar datos del paquete

2.7. Instalar archivos adicionales

2.8. Metadatos adicionales

2.9. Depuración del script de configuración

3. Escribiendo el archivo de configuración de instalación (setup)

4. Crear una distribución del código fuente

4.1. Especificar los archivos a distribuir

4.2. Opciones relacionadas con el manifesto

5. Crear distribuciones compiladas

5.1. Creando paquetes RPM

5.2. Crear instaladores de Windows

5.3. Compilación cruzada en Windows

5.4. Vista User Access Control (UAC)

6. Ejemplos de Distutils

6.1. Distribución de Python pura (por módulo)

6.2. Distribución de Python pura (por paquete)

6.3. Módulo de extensión única

6.4. Verificando un paquete

6.5. Leyendo los metadatos

7. Extendiendo Distutils

7.1. Integrando nuevos comandos

7.2. Añadiendo nuevos tipos de distribución

8. Referencia de Instrucciones

8.1. Instalando módulos: la familia de comandos install

8.2. Creando una distribución de origen: el comando sdist

9. Referencia de la API

9.1. distutils.core — Funcionalidad Core Distutils

9.2. distutils.ccompiler — Clase base CCompiler

9.3. distutils.unixccompiler — Unix CCompiler

9.4. distutils.msvccompiler — Compilador de Microsoft

9.5. distutils.bcppcompiler — Compilador Borland

9.6. distutils.cygwincompiler — Compilador Cygwin

9.7. distutils.archive_util — Utilidades de archivo

9.8. distutils.dep_util — Comprobación de dependencias

9.9. distutils.dir_util — Operaciones del árbol de directorios

9.10. distutils.file_util — Operaciones de un solo archivo

9.11. distutils.util — Otras funciones de utilidad varias

9.12. distutils.dist — La clase Distribution

9.13. distutils.extension — La clase Extension

9.14. distutils.debug — modo de depuración Distutils

9.15. distutils.errors — excepciones Distutils

9.16. distutils.fancy_getopt — Wrapper alrededor del módulo estándar getopt

9.17. distutils.filelist — La clase FileList

9.18. distutils.log — Simple PEP 282-registro de estilo

9.19. distutils.spawn — Genera un subproceso

9.20. distutils.sysconfig — Información de configuración del sistema

9.21. distutils.text_file — La clase TextFile

9.22. distutils.version — Clases de número de versión

9.23. distutils.cmd — Clase base abstracta para comandos Distutils

9.24. Creando un nuevo comando Distutils

9.25. distutils.command — Comandos individuales de Distutils

9.26. distutils.command.bdist — Construye un instalador binario

9.27. distutils.command.bdist_packager — Clase base abstracta para empaquetadores

9.28. distutils.command.bdist_dumb — Construye un instalador «dump»

9.29. distutils.command.bdist_msi — Construye un paquete binario instalador de Microsoft

9.30. distutils.command.bdist_rpm — Construye una distribución binaria como RedHat RPM y SRPM

9.31. distutils.command.bdist_wininst — Construye un instalador de Windows

9.32. distutils.command.sdist — Construye una distribución de código fuente

9.33. distutils.command.build — Construye todos los archivos de un paquete

9.34. distutils.command.build_clib — Construye cualquier biblioteca C en un paquete

9.35. distutils.command.build_ext — Construye cualquier extensión en un paquete

9.36. distutils.command.build_py — Construye los archivos .py/.pyc de un paquete

9.37. distutils.command.build_scripts — Construye los scripts de un paquete

9.38. distutils.command.clean — Limpia el área de construcción de un paquete

9.39. distutils.command.config — Realiza la configuración de un paquete

9.40. distutils.command.install — Instala un paquete

9.41. distutils.command.install_data — Instala archivos de datos de un paquete

9.42. distutils.command.install_headers — Instala archivos de encabezado C/C++ desde un paquete

9.43. distutils.command.install_lib — Instala archivos de biblioteca desde un paquete

9.44. distutils.command.install_scripts — Instala archivos de script desde un paquete

9.45. distutils.command.register — Registra un módulo con el índice de paquetes de Python

9.46. distutils.command.check — Verificar los metadatos de un paquete

1. Una introducción a Distutils

Nota

This document is being retained solely until the setuptools documentation at https://setuptools.readthedocs.io/en/latest/setuptools.html independently covers all of the relevant information currently included here.

Este documento cubre el uso de Distutils para distribuir módulos de Python, concentrándose en el rol de desarrollador/distribuidor: si está buscando información de como instalar módulos Python, debe consultar el capítulo Instalación de Módulos de Python (versión antigua).

1.1. Conceptos y Terminología

Usar Distutils es muy simple, tanto para desarrolladores de módulos como para usuarios/administradores que instalan módulos de terceros. Como desarrollador, sus responsabilidades (¡además de escribir código sólido, bien documentado y probado, por supuesto!) son:

escribir un script de configuración (setup.py por convención)

(opcional) escribir un archivo de configuración

crear una distribución fuente

(opcional) crear una o más distribuciones construidas (binarias)

Cada una de estas tareas está cubierta en este documento.

No todos los desarrolladores de módulos tienen acceso a una multitud de plataformas, por lo que no siempre es factible esperar que creen una multitud de distribuciones. Es de esperar que surjan intermediarios, llamados empaquetadores, para ayudar con esta necesidad. Los empaquetadores tomarán distribuciones de origen lanzadas por desarrolladores de módulo, las compilaran en una o más plataformas, y lanzaran las distribuciones resultantes. Así, los usuarios en las plataformas más populares podrán instalar las distribuciones de módulos Python más populares de la manera más natural para su plataforma, sin tener que ejecutar un solo script de configuración o compilar una línea de código.

1.2. Un ejemplo simple

El script de configuración suele ser simple, dado que está escrito en Python, no hay límite para lo que puede hacerse con él, aunque debe tener cuidado al poner operaciones arbitrariamente costosas en el script de configuración. A diferencia de, por ejemplo, las secuencias de comandos de configuración de estilo Autoconf, la secuencia de comandos de configuración se puede ejecutar varias veces en el transcurso de la construcción e instalación de la distribución de su módulo.

Si todo lo que quiere hacer es distribuir un módulo llamado foo, contenido en un archivo foo.py, entonces el script de configuración puede ser tan simple como esto:

from distutils.core import setup
setup(name='foo',
      version='1.0',
      py_modules=['foo'],
      )

Algunas observaciones:

la mayoría de la información que proporcione a Distutils se proporciona como argumentos keyword a la función setup()

esos argumentos keyword se dividen en dos categorías: metadatos del paquete (nombre, número de versión) e información sobre el contenido del paquete (una lista de módulos Python, en este caso)

módulos son especificados por nombre de módulo, no por nombre de archivo (lo mismo aplica para paquetes y extensiones)

se recomienda que proporcione un poco más de metadatos, en particular nombre, dirección de correo electrónico y URL para el proyecto (consulte la sección Escribir el script de configuración para ver un ejemplo)

Para crear una distribución fuente para este módulo, debe crear un script de configuración, setup.py, que contenga el código de arriba, y ejecute este comando en la terminal:

python setup.py sdist

En Windows, abra una ventana de símbolo de sistema (Inicio —> Accesorios) y cambie el comando a:

setup.py sdist

sdist creará un archivo de almacenamiento (por ejemplo, tarball en Unix, archivo ZIP en Windows) que contiene su script de configuración setup.py, y su módulo foo.py. El archivo de almacenamiento se llamará foo-1.0.tar.gz (o .zip), y se descomprimirá en un directorio foo-1.0.

Si un usuario final desea instalar su módulo foo, lo que tiene que hacer es descargar foo-1.0.tar.gz (o .zip), descomprimirlo, y—del directorio foo-1.0—ejecutar

python setup.py install

que finalmente copiará foo.py en el directorio apropiado para módulos de terceros en su instalación de Python.

Este sencillo ejemplo demuestra algunos conceptos fundamentales de Distutils. Primero, tanto los desarrolladores como los instaladores tienen la misma interfaz básica, es decir, el script de configuración. La diferencia es qué comandos de Distutils usan: el comando sdist es casi exclusivamente para desarrolladores de módulos, mientras que install es más frecuente para los instaladores (aunque la mayoría de los desarrolladores querrán instalar su propio código ocasionalmente )

Si desea hacer las cosas realmente fáciles para sus usuarios, puede crear una o más distribuciones integradas para ellos. Por ejemplo, si está ejecutando en una máquina Windows y desea facilitar las cosas para otros usuarios Windows, puede crear un instalador ejecutable (el tipo más apropiado de distribución integrada para esta plataforma) con el comando bdist_wininst. Por ejemplo:

python setup.py bdist_wininst

creará un instalador ejecutable, foo-1.0.win32.exe, en el directorio actual.

Otros formatos de distribución útiles son RPM, implementados por el comando bdist_rpm, Solaris pkgtool (bdist_pkgtool) y HP-UX swinstall (:command:` bdist_sdux`). Por ejemplo, el siguiente comando creará un archivo RPM llamado foo-1.0.noarch.rpm:

python setup.py bdist_rpm

(El comando bdist_rpm utiliza el ejecutable rpm, por lo tanto, esto debe ejecutarse en un sistema basado en RPM como Red Hat Linux, SuSE Linux o Mandrake Linux.)

Puede averiguar qué formatos de distribución están disponibles en cualquier momento ejecutando

python setup.py bdist --help-formats

1.3. Terminología general de Python

Si está leyendo este documento, probablemente tenga una buena idea de qué son los módulos, extensiones, etc. Sin embargo, solo para asegurarnos de que todos operen desde un punto de partida común, ofrecemos el siguiente glosario de términos comunes de Python:

módulo

la unidad básica de reutilización de código en Python: un bloque de código importado por algún otro código. Aquí nos interesan tres tipos de módulos: módulos Python puros, módulos de extensión y paquetes.

módulo Python puro

un módulo escrito en Python y contenido en un solo archivo .py (y posiblemente asociado con archivos .pyc). A veces se lo denomina «módulo puro».

módulo de extensión

un módulo escrito en el lenguaje de bajo nivel de la implementación de Python: C/C++ para Python, Java para Jython. Típicamente contenido en un único archivo precompilado cargable dinámicamente, ejemplo, un archivo de objeto compartido (:file: .so`) para extensiones de Python en Unix, una DLL (dada la extensión .pyd) para extensiones de Python en Windows, o un archivo de clase Java para extensiones de Jython. (Tenga en cuenta que actualmente, Distutils solo maneja extensiones C/C++ para Python.)

paquete

un módulo que contiene otros módulos; típicamente contenido en un directorio en el sistema de archivos y diferenciado de otros directorios por la presencia de un archivo __init __. py.

paquete raíz

la raíz de la jerarquía de paquetes. (Esto no es realmente un paquete, ya que no tiene un archivo __init __.py. Pero tenemos que llamarlo de alguna forma). La gran mayoría de la biblioteca estándar está en el paquete raíz, como muchos módulos de terceros pequeños e independientes que no pertenecen a una colección de módulos más grande. A diferencia de los paquetes regulares, los módulos en el paquete raíz se pueden encontrar en muchos directorios: de hecho, cada directorio listado en sys.path contribuye con módulos al paquete raíz.

1.4. Terminología específica de Distutils

Los siguientes términos se aplican más específicamente al dominio de distribución de módulos de Python utilizando Distutils:

distribución de módulo

una colección de módulos de Python distribuidos como un único recurso descargable y destinado a ser instalados en masa. Ejemplos de algunas distribuciones de módulos conocidas son NumPy, SciPy, Pillow o mxBase. (Esto se llama paquete, excepto que ese término ya se ha tomado en el contexto de Python: una distribución de un solo módulo puede contener cero, uno o muchos paquetes de Python).

distribución pura del módulo

una distribución de módulos que contiene solo módulos y paquetes de Python. A veces se lo denomina «distribución pura».

distribución de módulos no puros

una distribución de módulo que contiene al menos un módulo de extensión. En ocasiones se denomina «distribución no pura».

distribución raíz

el directorio de nivel superior del árbol fuente (o distribución fuente); el directorio donde setup.py existe. Generalmente setup.py se ejecutará desde este directorio.

2. Escribir el script de configuración

Nota

This document is being retained solely until the setuptools documentation at https://setuptools.readthedocs.io/en/latest/setuptools.html independently covers all of the relevant information currently included here.

El script de configuración es el centro de toda actividad en la construcción, distribución e instalación de módulos utilizando Distutils. El propósito principal del script de configuración es describir la distribución de su módulo a Distutils, de modo que los diversos comandos que operan en sus módulos hagan lo correcto. Como vimos en la sección Un ejemplo simple anterior, el script de configuración consiste principalmente en una llamada a setup(), y la mayoría de la información suministrada a Distutils por el desarrollador del módulo se proporciona como argumentos de palabras clave para setup().

Aquí hay un ejemplo un poco más complicado, que seguiremos en las próximas secciones: el propio script de configuración de Distutils. (Tenga en cuenta que aunque los Distutils se incluyen con Python 1.6 y posteriores, también tienen una existencia independiente para que los usuarios de Python 1.5.2 puedan usarlos para instalar otras distribuciones de módulos. Se utiliza el propio script de configuración de Distutils, que se muestra aquí). instalar el paquete en Python 1.5.2.)

#!/usr/bin/env python

from distutils.core import setup

setup(name='Distutils',
      version='1.0',
      description='Python Distribution Utilities',
      author='Greg Ward',
      author_email='gward@python.net',
      url='https://www.python.org/sigs/distutils-sig/',
      packages=['distutils', 'distutils.command'],
     )

Solo hay dos diferencias entre esto y la trivial distribución de un archivo presentada en la sección Un ejemplo simple: más metadatos y la especificación de módulos Python puros por paquete, en lugar de por módulo. Esto es importante ya que los Distutils consisten en un par de docenas de módulos divididos en (hasta ahora) dos paquetes; Una lista explícita de cada módulo sería tediosa de generar y difícil de mantener. Para obtener más información sobre los metadatos adicionales, consulte la sección Metadatos adicionales.

Tenga en cuenta que los nombres de ruta (archivos o directorios) proporcionados en el script de configuración deben escribirse utilizando la convención de Unix, es decir, separados por barras. Distutils se encargará de convertir esta representación neutral de la plataforma en lo que sea apropiado en su plataforma actual antes de usar el nombre de ruta. Esto hace que su script de configuración sea portátil en todos los sistemas operativos, lo que, por supuesto, es uno de los principales objetivos de Distutils. En este espíritu, todos los nombres de ruta en este documento están separados por barras.

Esto, por supuesto, solo se aplica a los nombres de ruta asignados a las funciones de Distutils. Si, por ejemplo, utiliza funciones estándar de Python como glob.glob() o os.listdir() para especificar archivos, debe tener cuidado al escribir código portátil en lugar de codificar separadores de ruta:

glob.glob(os.path.join('mydir', 'subdir', '*.html'))
os.listdir(os.path.join('mydir', 'subdir'))

2.1. Listado de paquetes completos

La opción packages le dice a Distutils que procese (compile, distribuya, instale, etc.) todos los módulos de Python puros que se encuentran en cada paquete mencionado en la lista de packages. Para hacer esto, por supuesto, debe haber una correspondencia entre los nombres de los paquetes y los directorios en el sistema de archivos. La correspondencia predeterminada es la más obvia, es decir, el paquete distutils se encuentra en el directorio distutils en relación con la raíz de distribución. Por lo tanto, cuando diga packages = ['foo'] en su secuencia de comandos de configuración, promete que Distutils encontrará un archivo foo/__init__.py (que podría estar escrito de manera diferente en su sistema , pero te haces una idea) en relación con el directorio donde vive tu script de configuración. Si no cumple esta promesa, Distutils emitirá una advertencia pero de todos modos procesará el paquete roto.

Si usa una convención diferente para diseñar su directorio de origen, no hay problema: solo tiene que proporcionar la opción package_dir para informar a los Distutils sobre su convención. Por ejemplo, supongamos que mantiene toda la fuente de Python en lib, de modo que los módulos en el «paquete raíz» (es decir, no en ningún paquete) estén en lib, módulos en el paquete foo está en archivo lib/foo, y así sucesivamente. Entonces pondrías

package_dir = {'': 'lib'}

en tu script de configuración. Las claves de este diccionario son nombres de paquetes, y un nombre de paquete vacío representa el paquete raíz. Los valores son nombres de directorio relativos a su raíz de distribución. En este caso, cuando dices packages = ['foo'], estás prometiendo que el archivo lib/foo/__init__.py existe.

Otra posible convención es colocar el paquete foo directamente en lib, el paquete foo.bar en lib/bar, etc. Esto se escribiría en el script de configuración como

package_dir = {'foo': 'lib'}

Una entrada package: dir en el diccionario package_dir se aplica implícitamente a todos los paquetes debajo de package, por lo que el caso foo.bar se maneja automáticamente aquí. En este ejemplo, tener packages = ['foo', 'foo.bar'] le dice a los Distutils que busquen lib/__init__.py y lib/bar/__init__.py. (Tenga en cuenta que, aunque package_dir se aplica de forma recursiva, debe enumerar explícitamente todos los paquetes en packages: los Distutils no escanearán recursivamente su árbol de origen buscando cualquier directorio con un archivo __init__.py.)

2.2. Listado de módulos individuales

Para una distribución de módulos pequeños, es posible que prefiera enumerar todos los módulos en lugar de enumerar los paquetes, especialmente el caso de un solo módulo que va en el «paquete raíz» (es decir, ningún paquete). Este caso más simple se mostró en la sección Un ejemplo simple; Aquí hay un ejemplo un poco más complicado:

py_modules = ['mod1', 'pkg.mod2']

Esto describe dos módulos, uno en el paquete «raíz», el otro en el paquete pkg. Nuevamente, el diseño predeterminado del paquete/directorio implica que estos dos módulos se pueden encontrar en mod1.py y pkg/mod2.py, y que pkg/__init__.py existe también. Y nuevamente, puede anular la correspondencia paquete/directorio utilizando la opción package_dir.

2.3. Describiendo módulos de extensión

Así como escribir módulos de extensión Python es un poco más complicado que escribir módulos Python puros, describirlos a Distutils es un poco más complicado. A diferencia de los módulos puros, no basta con enumerar módulos o paquetes y esperar que Distutils salga y encuentre los archivos correctos; debe especificar el nombre de la extensión, el (los) archivo (s) de origen y cualquier requisito de compilación/enlace (incluir directorios, bibliotecas para enlazadores, etc.).

Todo esto se realiza a través de otro argumento de palabra clave para setup(), la opción ext_modules. ext_modules es solo una lista de instancias Extension, cada una de las cuales describe un único módulo de extensión. Suponga que su distribución incluye una sola extensión, llamada foo e implementada por foo.c. Si no se necesitan instrucciones adicionales para el compilador/enlazador, describir esta extensión es bastante simple:

Extension('foo', ['foo.c'])

La clase Extension se puede importar desde distutils.core junto con setup(). Por lo tanto, el script de configuración para una distribución de módulo que contiene solo esta extensión y nada más podría ser:

from distutils.core import setup, Extension
setup(name='foo',
      version='1.0',
      ext_modules=[Extension('foo', ['foo.c'])],
      )

La clase Extension (en realidad, la maquinaria de construcción de extensiones subyacente implementada por el comando build_ext) admite una gran flexibilidad al describir las extensiones de Python, que se explica en las siguientes secciones.

2.3.1. Nombres de extensión y paquetes

El primer argumento para el constructor Extension es siempre el nombre de la extensión, incluidos los nombres de los paquetes. Por ejemplo,

Extension('foo', ['src/foo1.c', 'src/foo2.c'])

describe una extensión que vive en el paquete raíz, mientras que

Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c'])

describe la misma extensión en el paquete pkg. Los archivos fuente y el código objeto resultante son idénticos en ambos casos; la única diferencia es dónde en el sistema de archivos (y, por lo tanto, dónde en la jerarquía del espacio de nombres de Python) vive la extensión resultante.

Si tiene varias extensiones, todas en el mismo paquete (o todas en el mismo paquete base), use el argumento de palabra clave ext_package para setup(). Por ejemplo,

setup(...,
      ext_package='pkg',
      ext_modules=[Extension('foo', ['foo.c']),
                   Extension('subpkg.bar', ['bar.c'])],
     )

compilará foo.c a la extensión pkg.foo, y bar.c a pkg.subpkg.bar.

2.3.2. Extensión de archivos fuente

El segundo argumento para el constructor Extension es una lista de archivos fuente. Dado que Distutils actualmente solo admite extensiones C, C++ y Objective-C, estos normalmente son archivos fuente C/C++/Objective-C. (Asegúrese de usar las extensiones apropiadas para distinguir los archivos fuente de C++ .cc y .cpp que parecen ser reconocidos por los compiladores de Unix y Windows).

Sin embargo, también puede incluir archivos de interfaz SWIG (.i) en la lista; el comando build_ext sabe cómo manejar las extensiones SWIG: ejecutará SWIG en el archivo de interfaz y compilará el archivo C/C++ resultante en su extensión.

A pesar de esta advertencia, las opciones para SWIG se pueden pasar actualmente de esta manera:

setup(...,
      ext_modules=[Extension('_foo', ['foo.i'],
                             swig_opts=['-modern', '-I../include'])],
      py_modules=['foo'],
     )

O en la línea de comandos como esta

> python setup.py build_ext --swig-opts="-modern -I../include"

En algunas plataformas, puede incluir archivos que no sean de origen procesados por el compilador e incluidos en su extensión. Actualmente, esto solo significa archivos de texto de mensaje de Windows (.mc) y archivos de definición de recursos (.rc) para Visual C ++. Estos serán compilados en archivos de recursos binarios (.res) y enlazados.

2.3.3. Opciones de preprocesador

Tres argumentos opcionales para Extension le ayudarán si necesita especificar directorios de inclusión para buscar o preprocesar macros para definir/indefinir: include_dirs, define_macros y undef_macros.

Por ejemplo, si su extensión requiere archivos de encabezado en el directorio include bajo su raíz de distribución, use la opción include_dirs:

Extension('foo', ['foo.c'], include_dirs=['include'])

Puede especificar directorios absolutos allí; si sabe que su extensión solo se construirá en sistemas Unix con X11R6 instalado en /usr, puede salirse con

Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11'])

Debería evitar este tipo de uso no portátil si planea distribuir su código: probablemente sea mejor escribir código C como

#include <X11/Xlib.h>

Si necesita incluir archivos de encabezado de alguna otra extensión de Python, puede aprovechar el hecho de que los archivos de encabezado se instalan de manera coherente mediante el comando Distutils install_headers. Por ejemplo, los archivos de encabezado Python numéricos se instalan (en una instalación estándar de Unix) en /usr/local/include/python1.5/ Numerical. (La ubicación exacta diferirá según la plataforma y la instalación de Python). Dado que el directorio de inclusión de Python — /usr/local/include/python1.5 en este caso — siempre se incluye en ruta de búsqueda al construir extensiones de Python, el mejor enfoque es escribir código C como

#include <Numerical/arrayobject.h>

Sin embargo, si debe colocar el directorio Numerical en la ruta de búsqueda del encabezado, puede encontrar ese directorio utilizando el módulo Distutils distutils.sysconfig:

from distutils.sysconfig import get_python_inc
incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical')
setup(...,
      Extension(..., include_dirs=[incdir]),
      )

Aunque esto es bastante portátil, funcionará en cualquier instalación de Python, independientemente de la plataforma, probablemente sea más fácil escribir su código C de manera sensata.

Puede definir y no definir macros de preprocesador con las opciones define_macros y undef_macros. define_macros toma una lista de tuplas (name, value), donde name es el nombre de la macro a definir (una cadena de caracteres) y value es su valor: ya sea un cadena de caracteres o None. (Definir una macro FOO en None es el equivalente de un simple #define FOO en su fuente C: con la mayoría de los compiladores, esto establece FOO en la cadena 1.) undef_macros es solo una lista de macros para indefinir.

Por ejemplo:

Extension(...,
          define_macros=[('NDEBUG', '1'),
                         ('HAVE_STRFTIME', None)],
          undef_macros=['HAVE_FOO', 'HAVE_BAR'])

es el equivalente a tener esto en la parte superior de cada archivo fuente C:

#define NDEBUG 1
#define HAVE_STRFTIME
#undef HAVE_FOO
#undef HAVE_BAR

2.3.4. Opciones de biblioteca

También puede especificar las bibliotecas para enlazarlas al crear su extensión y los directorios para buscar esas bibliotecas. La opción bibliotecas es una lista de bibliotecas para enlazar, library_dirs es una lista de directorios para buscar bibliotecas en el momento del enlace, y runtime_library_dirs es una lista de directorios para buscar compartidos (cargadas dinámicamente) bibliotecas en tiempo de ejecución.

Por ejemplo, si necesita enlazar con bibliotecas que se sabe que están en la ruta de búsqueda de biblioteca estándar en los sistemas de destino:

Extension(...,
          libraries=['gdbm', 'readline'])

Si necesita enlazar con bibliotecas en una ubicación no estándar, deberá incluir la ubicación en library_dirs:

Extension(...,
          library_dirs=['/usr/X11R6/lib'],
          libraries=['X11', 'Xt'])

(Nuevamente, este tipo de construcción no portátil debe evitarse si tiene la intención de distribuir su código.)

2.3.5. Otras opciones

Todavía hay algunas otras opciones que se pueden usar para manejar casos especiales.

La opción optional es booleana; si es cierto, una falla de compilación en la extensión no abortará el proceso de compilación, sino que simplemente no instalará la extensión que falla.

La opción extra_objects es una lista de archivos de objetos que se pasarán al enlazador. Estos archivos no deben tener extensiones, ya que se usa la extensión predeterminada para el compilador.

extra_compile_args y extra_link_args se pueden usar para especificar opciones de línea de comando adicionales para las líneas de comando del compilador y enlazador respectivo.

export_symbols solo es útil en Windows. Puede contener una lista de símbolos (funciones o variables) para exportar. Esta opción no es necesaria cuando se crean extensiones compiladas: Distutils agregará automáticamente initmodule a la lista de símbolos exportados.

La opción depends es una lista de archivos de los que depende la extensión (por ejemplo, archivos de encabezado). El comando de compilación llamará al compilador en las fuentes para reconstruir la extensión si alguno de estos archivos se ha modificado desde la compilación anterior.

2.4. Relaciones entre distribuciones y paquetes

Una distribución puede relacionarse con paquetes de tres maneras específicas:

Puede requerir paquetes o módulos.

Puede proporcionar paquetes o módulos.

Puede paquetes o módulos obsoletos.

Estas relaciones se pueden especificar utilizando argumentos de palabras clave para la función distutils.core.setup().

Las dependencias en otros módulos y paquetes de Python se pueden especificar proporcionando el argumento de palabra clave requires a setup(). El valor debe ser una lista de cadenas de caracteres. Cada cadena especifica un paquete que se requiere y, opcionalmente, qué versiones son suficientes.

Para especificar que se requiere cualquier versión de un módulo o paquete, la cadena debe consistir completamente en el nombre del módulo o paquete. Los ejemplos incluyen 'mymodule' y 'xml.parsers.expat'.

Si se requieren versiones específicas, se puede proporcionar una secuencia de calificadores entre paréntesis. Cada calificador puede consistir en un operador de comparación y un número de versión. Los operadores de comparación aceptados son:

<    >    ==
<=   >=   !=

Estos se pueden combinar usando múltiples calificadores separados por comas (y espacios en blanco opcionales). En este caso, todos los calificadores deben coincidir; Se utiliza un AND lógico para combinar las evaluaciones.

Veamos algunos ejemplos:

Expresión Requiere

Explicación

==1.0

Solo la versión 1.0 es compatible

>1.0, !=1.5.1, <2.0

Cualquier versión posterior a 1.0 y anterior a 2.0 es compatible, excepto 1.5.1

Ahora que podemos especificar dependencias, también debemos poder especificar qué proporcionamos que otras distribuciones pueden requerir. Esto se hace usando el argumento de palabra clave provides para setup(). El valor de esta palabra clave es una lista de cadenas, cada una de las cuales nombra un módulo o paquete Python, y opcionalmente identifica la versión. Si no se especifica la versión, se supone que coincide con la de la distribución.

Algunos ejemplos:

Expresión Proporciona

Explicación

mypkg

Proporciona mypkg, utilizando la versión de distribución

mypkg (1.1)

Proporcione mypkg versión 1.1, independientemente de la versión de distribución

Un paquete puede declarar que obsoleto otros paquetes utilizando el argumento de palabra clave obsoletes. El valor para esto es similar al de la palabra clave requires: una lista de cadenas que dan especificadores de módulo o paquete. Cada especificador consta de un nombre de módulo o paquete opcionalmente seguido de uno o más calificadores de versión. Los calificadores de versión se dan entre paréntesis después del nombre del módulo o paquete.

Las versiones identificadas por los calificadores son aquellas que están obsoletas por la distribución que se describe. Si no se dan calificadores, se entiende que todas las versiones del módulo o paquete nombrado están obsoletas.

2.5. Instalar scripts

Hasta ahora hemos estado tratando con módulos Python puros y no puros, que generalmente no se ejecutan solos sino que se importan mediante scripts.

Los scripts son archivos que contienen el código fuente de Python, destinados a iniciarse desde la línea de comandos. Los scripts no requieren que Distutils haga nada muy complicado. La única característica inteligente es que si la primera línea del script comienza con #! Y contiene la palabra «python», Distutils ajustará la primera línea para referirse a la ubicación actual del intérprete. Por defecto, se reemplaza con la ubicación actual del intérprete. La opción -executable (o -e) permitirá que la ruta del intérprete se anule explícitamente.

La opción scripts simplemente es una lista de archivos a manejar de esta manera. Desde el script de configuración PyXML:

setup(...,
      scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val']
      )

Distinto en la versión 3.1: Todos los scripts también se agregarán al archivo MANIFEST si no se proporciona una plantilla. Ver Especificar los archivos a distribuir.

2.6. Instalar datos del paquete

A menudo, se necesitan instalar archivos adicionales en un paquete. Estos archivos son a menudo datos que están estrechamente relacionados con la implementación del paquete, o archivos de texto que contienen documentación que podría ser de interés para los programadores que usan el paquete. Estos archivos se llaman paquetes de datos <package data>.

Los datos del paquete se pueden agregar a los paquetes utilizando el argumento de palabra clave package_data para la función setup(). El valor debe ser una asignación del nombre del paquete a una lista de nombres de ruta relativos que deben copiarse en el paquete. Las rutas se interpretan como relativas al directorio que contiene el paquete (la información de la asignación package_dir se usa si corresponde); es decir, se espera que los archivos formen parte del paquete en los directorios de origen. También pueden contener patrones glob.

Los nombres de ruta pueden contener porciones de directorio; cualquier directorio necesario se creará en la instalación.

Por ejemplo, si un paquete debe contener un subdirectorio con varios archivos de datos, los archivos se pueden organizar de esta manera en el árbol de origen:

setup.py
src/
    mypkg/
        __init__.py
        module.py
        data/
            tables.dat
            spoons.dat
            forks.dat

La llamada correspondiente a setup() podría ser:

setup(...,
      packages=['mypkg'],
      package_dir={'mypkg': 'src/mypkg'},
      package_data={'mypkg': ['data/*.dat']},
      )

Distinto en la versión 3.1: Todos los archivos que coincidan con package_data se agregarán al archivo MANIFEST si no se proporciona una plantilla. Ver Especificar los archivos a distribuir.

2.7. Instalar archivos adicionales

La opción data_files se puede usar para especificar archivos adicionales necesarios para la distribución del módulo: archivos de configuración, catálogos de mensajes, archivos de datos, cualquier cosa que no se ajuste a las categorías anteriores.

data_files especifica una secuencia de pares (directory, files) de la siguiente manera:

setup(...,
      data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
                  ('config', ['cfg/data.cfg'])],
     )

Cada par (directory, files) en la secuencia especifica el directorio de instalación y los archivos a instalar allí.

Cada nombre de archivo en files se interpreta en relación con el script setup.py en la parte superior de la distribución de origen del paquete. Tenga en cuenta que puede especificar el directorio donde se instalarán los archivos de datos, pero no puede cambiar el nombre de los archivos de datos.

El directory debe ser una ruta relativa. Se interpreta en relación con el prefijo de instalación (sys.prefix de Python para instalaciones del sistema; site.USER_BASE para instalaciones de usuario). Distutils permite que directory sea una ruta de instalación absoluta, pero esto se desaconseja ya que es incompatible con el formato de empaquetado de la rueda. No se utiliza información de directorio de files para determinar la ubicación final del archivo instalado; solo se usa el nombre del archivo.

Puede especificar las opciones data_files como una secuencia simple de archivos sin especificar un directorio de destino, pero esto no es recomendable, y el comando install imprimirá una advertencia en este caso. Para instalar archivos de datos directamente en el directorio de destino, se debe dar una cadena vacía como directorio.

Distinto en la versión 3.1: Todos los archivos que coincidan con data_files se agregarán al archivo MANIFEST si no se proporciona una plantilla. Ver Especificar los archivos a distribuir.

2.8. Metadatos adicionales

El script de configuración puede incluir metadatos adicionales más allá del nombre y la versión. Esta información incluye:

Metadatos

Descripción

Valor

Notas

name

nombre del paquete

cadena de caracteres corta

(1)

version

versión de este lanzamiento

cadena de caracteres corta

(1)(2)

author

nombre del autor del paquete

cadena de caracteres corta

(3)

author_email

dirección de correo electrónico del autor del paquete

dirección de correo electrónico

(3)

maintainer

nombre del responsable del paquete

cadena de caracteres corta

(3)

maintainer_email

dirección de correo electrónico del mantenedor del paquete

dirección de correo electrónico

(3)

url

página de inicio del paquete

URL

(1)

description

descripción breve y resumida del paquete

cadena de caracteres corta

long_description

descripción más larga del paquete

cadena de caracteres larga

(4)

download_url

ubicación donde se puede descargar el paquete

URL

classifiers

una lista de clasificadores

lista de cadenas de caracteres

(6)(7)

platforms

una lista de plataformas

lista de cadenas de caracteres

(6)(8)

keywords

una lista de palabras clave

lista de cadenas de caracteres

(6)(8)

license

licencia para el paquete

cadena de caracteres corta

(5)

Notas:

Estos campos son obligatorios.

Se recomienda que las versiones tomen la forma major.minor[.patch[.sub]].

Se debe identificar al autor o al mantenedor. Si se proporciona el mantenedor, distutils lo enumera como el autor en PKG-INFO.

PyPI utiliza el campo long_description cuando publica un paquete para construir su página de proyecto.

El campo license es un texto que indica la licencia que cubre el paquete donde la licencia no es una selección de los clasificadores de Trove «License». Vea el campo Classifier. Tenga en cuenta que hay una opción de distribución de license que está en desuso pero que aún actúa como un alias para la license.

Este campo debe ser una lista.

Los clasificadores válidos se enumeran en PyPI [https://pypi.org/classifiers].

Para preservar la compatibilidad con versiones anteriores, este campo también acepta una cadena. Si pasa una cadena separada por comas 'foo, bar', se convertirá en ['foo', 'bar'], de lo contrario, se convertirá en una lista de una cadena de caracteres.

“cadenas de caracteres cortas”

Una sola línea de texto, no más de 200 caracteres.

“cadenas de caracteres largas”

Múltiples líneas de texto plano en formato reStructuredText (consulte http://docutils.sourceforge.net/).

“lista de cadenas de caracteres”

Vea abajo.

Codificar la información de la versión es un arte en sí mismo. Los paquetes de Python generalmente se adhieren al formato de versión major.minor[.patch][sub]. El número principal es 0 para las versiones iniciales y experimentales de software. Se incrementa para versiones que representan hitos importantes en un paquete. El número menor se incrementa cuando se agregan nuevas características importantes al paquete. El número de parche aumenta cuando se realizan versiones de corrección de errores. La información adicional de la versión final a veces se usa para indicar sublanzamientos. Estos son «a1, a2, …, aN» (para versiones alfa, donde la funcionalidad y la API pueden cambiar), «b1, b2, …, bN» (para versiones beta, que solo corrigen errores) y «pr1 , pr2, …, prN» (para la prueba final de lanzamiento previo al lanzamiento). Algunos ejemplos:

0.1.0

el primer lanzamiento experimental de un paquete

1.0.1a2

la segunda versión alfa de la primera versión del parche 1.0

classifiers debe ser especificado en una lista:

setup(...,
      classifiers=[
          'Development Status :: 4 - Beta',
          'Environment :: Console',
          'Environment :: Web Environment',
          'Intended Audience :: End Users/Desktop',
          'Intended Audience :: Developers',
          'Intended Audience :: System Administrators',
          'License :: OSI Approved :: Python Software Foundation License',
          'Operating System :: MacOS :: MacOS X',
          'Operating System :: Microsoft :: Windows',
          'Operating System :: POSIX',
          'Programming Language :: Python',
          'Topic :: Communications :: Email',
          'Topic :: Office/Business',
          'Topic :: Software Development :: Bug Tracking',
          ],
      )

Distinto en la versión 3.7: setup ahora advierte cuando los campos classifiers, keywords o platforms no se especifican como una lista o una cadena de caracteres.

2.9. Depuración del script de configuración

A veces las cosas salen mal y el script de configuración no hace lo que el desarrollador quiere.

Distutils detecta cualquier excepción al ejecutar el script de configuración e imprime un mensaje de error simple antes de que finalice el script. La motivación para este comportamiento es no confundir a los administradores que no saben mucho acerca de Python y están tratando de instalar un paquete. Si obtienen un gran rastreo desde las profundidades de Distutils, pueden pensar que el paquete o la instalación de Python están rotos porque no leen hasta el final y ven que es un problema de permiso.

Por otro lado, esto no ayuda al desarrollador a encontrar la causa de la falla. Para este propósito, la variable de entorno DISTUTILS_DEBUG se puede establecer en cualquier cosa excepto una cadena vacía, y distutils ahora imprimirá información detallada sobre lo que está haciendo, volcará el rastreo completo cuando ocurra una excepción e imprimirá todo el comando línea cuando falla un programa externo (como un compilador de C).

3. Escribiendo el archivo de configuración de instalación (setup)

Nota

This document is being retained solely until the setuptools documentation at https://setuptools.readthedocs.io/en/latest/setuptools.html independently covers all of the relevant information currently included here.

A menudo, no es posible escribir todo lo necesario para construir una distribución a priori: es posible que deba obtener alguna información del usuario, o del sistema del usuario, para poder continuar. Mientras que esa información sea bastante simple —una lista de directorios para buscar archivos de encabezado de o bibliotecas, por ejemplo— proporcionar un archivo de configuración, setup.cfg, para que los usuarios lo editen es una forma fácil y barata de solicitarla. Los archivos de configuración también permiten proporcionar valores predeterminados para cualquier opción de comando, que el instalador puede invalidar en la línea de comando o editando el archivo de configuración.

La configuración del archivo de instalación (setup) es un punto medio útil entre el script de configuración— que, idealmente, sería opaco para los instaladores 1—y la línea de comandos para el script de configuración, que está fuera de su control y depende totalmente del instalador. De hecho, setup.cfg (y cualquiera otros archivos de configuración de Distutils presentes en el sistema destino) se procesa después del contenido del script de configuración, pero antes de la línea de comandos. Esto tiene varias consecuencias útiles:

los instaladores pueden anular o invalidar algo que pongas en setup.py editando setup.cfg

puedes proporcionar valores predeterminados no estándares para las opciones que se pueden configurar fácilmente en setup.py

los instaladores pueden invalidar cualquier cosa en setup.cfg usando las opciones de línea de comandos para setup.py

La sintaxis básica del archivo de configuración es simple:

[command]
option=value
...

donde command es uno de los comandos de Distutils (por ejemplo: build_py, install), y option es una de las opciones que el comando admite. Se puede proporcionar cualquier cantidad de opciones para cada comando, y se puede incluir cualquier número de secciones de comando en el archivo. Las líneas en blanco son ignoradas, al igual que los comentarios, que empiezan desde el carácter '#' hasta el final de la línea. Los valores de opción largos pueden dividirse en varias líneas simplemente indentando las líneas a continuación.

Puedes encontrar la lista de opciones admitidas por un comando particular con la opción universal --help, por ej.

$ python setup.py --help build_ext
[...]
Options for 'build_ext' command:
  --build-lib (-b)     directory for compiled extension modules
  --build-temp (-t)    directory for temporary files (build by-products)
  --inplace (-i)       ignore build-lib and put compiled extensions into the
                       source directory alongside your pure Python modules
  --include-dirs (-I)  list of directories to search for header files
  --define (-D)        C preprocessor macros to define
  --undef (-U)         C preprocessor macros to undefine
  --swig-opts          list of SWIG command line options
[...]

Tenga en cuenta que una opción escrita --foo-bar en la línea de comandos es escribe foo_bar en los archivos de configuración.

Por ejemplo, digamos que quiere que sus extensiones se construyan «en el lugar» (in-place)—esto es, tienes una extensión pkg.ext, y quieres el archivo de extensión compilado (ext.so en Unix, digamos) para ser colocado en el mismo directorio origen que los módulos de Python puro pkg.mod1 y pkg.mod2. Siempre puedes utilizar la opción --inplace en la línea de comandos para asegurarte de eso:

python setup.py build_ext --inplace

Pero esto requiere que siempre especifiques el comando build_ext explícitamente, y recuerdes proporcionarle --inplace. Una forma mas fácil es «configurar y olvidar» esta opción, poniéndolo en setup.cfg, el archivo de configuración para esta distribución:

[build_ext]
inplace=1

Esto afectará a todas las compilaciones de la distribución de este módulo, independientemente de si especificas o no explícitamente build_ext. Si incluyes setup.cfg en tu distribución de origen, también afectará las compilaciones de los usuarios finales— lo que probablemente sea una mala idea para esta opción, ya que siempre construir extensiones en el lugar interrumpiría la instalación de la distribución del módulo. En ciertos casos particulares, sin embargo, los módulos son compilados directamente en el directorio de instalación, por lo que sería una habilidad útil. (Sin embargo, distribuir extensiones que se espera que sean compiladas en su directorio de instalación es casi siempre una mala idea).

Otro ejemplo: ciertos comandos toman muchas opciones que no cambian de ejecución a ejecución; por ejemplo, bdist_rpm necesita conocer todo lo necesario para generar un archivo «spec» para crear una distribución RPM. Parte de esta información proviene del script de configuración, y otra es generada automáticamente por Distutils (como la lista de archivos instalados). Pero parte de esto tiene que ser suministrado como opciones para bdist_rpm, lo cual sería muy tedioso hacer en la línea de comandos para cada ejecución. Por lo tanto, aquí hay un fragmento del propio de Distutils setup.cfg:

[bdist_rpm]
release = 1
packager = Greg Ward <gward@python.net>
doc_files = CHANGES.txt
            README.txt
            USAGE.txt
            doc/
            examples/

Tenga en cuenta que la opción doc_files es simplemente una cadena de texto separada por espacios dividida en varias líneas para facilitar la lectura.

Ver también

Archivos de configuración de sintaxis en «Instalar módulos de Python»

Más información sobre los archivos de configuración está disponible en el manual para administradores del sistema.

Notas al pie

1

Es probable que este ideal no se logre hasta que la configuración automática sea completamente admitida por Distutils.

4. Crear una distribución del código fuente

Nota

This document is being retained solely until the setuptools documentation at https://setuptools.readthedocs.io/en/latest/setuptools.html independently covers all of the relevant information currently included here.

Como se muestra en la sección Un ejemplo simple, use el comando sdist para crear una distribución de código fuente. En el caso más simple,

python setup.py sdist

(suponiendo que no ha especificado ninguna opción sdist en el script de configuración o en el archivo de configuración), sdist crea el archivo con el formato predeterminado para la plataforma actual.El formato predeterminado es un archivo tar comprimido con gzip (.tar.gz) en Unix, y el archivo ZIP en Windows.

Puede especificar tantos formatos como desee usando la opción --formats, por ejemplo:

python setup.py sdist --formats=gztar,zip

para crear un tarball comprimido y un archivo zip. Los formatos disponibles son:

Formato

Descripción

Notas

zip

archivo zip (.zip)

(1),(3)

gztar

archivo tar comprimido con gzip (.tar.gz)

(2)

bztar

archivo tar comprimido con bzip2 (.tar.bz2)

(5)

xztar

archivo tar comprimido con xz (.tar.xz)

(5)

ztar

archivo tar comprimido (.tar.Z)

(4),(5)

tar

archivo tar (.tar)

(5)

Distinto en la versión 3.5: Soporte agregado para el formato xztar.

Notas:

por defecto en Windows

por defecto en Unix

se requiere o bien un programa externo zip o el módulo zipfile (parte del estándar de la biblioteca de Python desde Python 1.6)

requiere el programa compress. Tenga en cuenta que ahora este formato está deprecado y será eliminado en las futuras versiones de Python.

deprecated by PEP 527 [https://www.python.org/dev/peps/pep-0527/]; PyPI [https://pypi.org] only accepts .zip and .tar.gz files.

Al usar cualquier formato tar (gztar, bztar, xztar, ztar o tar), en Unix se puede especificar el nombre del propietario y grupo que se establecerá para cada uno de los miembros del archivo.

Por ejemplo, si quiere que todos los archivos pertenezcan al usuario root:

python setup.py sdist --owner=root --group=root

4.1. Especificar los archivos a distribuir

Si no se proporciona una lista explícita de los archivos (o instrucciones sobre cómo generar uno), el comando sdist pone un conjunto mínimo por defecto en la distribución de código fuente:

todos los archivos de código fuente de Python implícitos por las opciones py_modules y packages

todos los archivos de código fuente de C mencionados en las opciones ext_modules o libraries

scripts identificados por la opción scripts Ver Instalar scripts.

cualquier archivo que parezca un script de pruebas: test/test*.py (actualmente, Distutils no hace nada con scripts de prueba, solo los incluye en la distribución, pero en el futuro habrá un estándar para realizar pruebas de los módulos de Python en las distribuciones)

Cualquiera de los archivos estándar LÉAME (README, README.txt, o README.rst), setup.py (o cualquier nombre que le haya puesto al script de configuración), y setup.cfg.

todos los archivos que coincidan con los metadatos package_data. Vea Instalar datos del paquete.

todos los archivos que coincidan con los metadatos data_files. Vea Instalar archivos adicionales.

A veces esto es suficiente, pero por lo general, va a querer especificar archivos adicionales a distribuir. La forma típica de hacer esto es escribir una plantilla de manifiesto, por defecto con el nombre MANIFEST.in. La plantilla de manifiesto es sólo una lista de instrucciones para generar el archivo de manifiesto, MANIFEST, el cual es la lista exacta de archivos a incluir en la distribución de código fuente. El comando sdist procesa esta plantilla y genera un manifiesto basado en las instrucciones y en lo que encuentra en el sistema de ficheros.

Si prefiere crear su propio archivo de manifiesto, el formato es simple: un nombre de archivo por línea, solamente archivos normales (o enlaces simbólicos a ellos). Si hace su propio MANIFEST, debe especificar todo: el conjunto predeterminado de los archivos descritos más arriba no se aplica en este caso.

Distinto en la versión 3.1: Un MANIFEST ya existente y generado, será regenerado sin sdist comparando su tiempo de modificación con el de MANIFEST.in o setup.py.

Distinto en la versión 3.1.3: MANIFEST los archivos comienzan con un comentario indicando que son generados. Los archivos que no tengan este comentario no se sobrescriben ni eliminan.

Distinto en la versión 3.2.2: sdist leerá un archivo MANIFEST si no existe el archivo MANIFEST.in, como solía hacer.

Distinto en la versión 3.7: README.rst ahora está incluido en la lista de LEAMEs estándar de distutils.

La plantilla de manifiesto tiene un comando por línea, donde cada comando especifica un conjunto de archivos para incluir o excluir de la distribución de código fuente. Para un ejemplo, de nuevo nos dirigimos a la Distutils la propia plantilla de manifiesto:

include *.txt
recursive-include examples *.txt *.py
prune examples/sample?/build

Los significados debe ser bastante claros: incluya todos los archivos en la raíz de la distribución, que coincidan con *.txt, todos los archivos dentro del directorio examples que coincidan con *.txt o *.py, y excluir todos los directorios que coincidan con examples/sample?/build. Todo esto se hace después de seguir el conjunto estándar de inclusión, por lo que puede excluir archivos del conjunto establecido con instrucciones explícitas en la plantilla del manifiesto. (O bien, puede utilizar la opción --no-defaults para desactivar el conjunto estándar completo.) Hay varios otros comandos disponibles en el mini-lenguaje de la plantilla de manifiesto; vea la sección Creando una distribución de origen: el comando sdist.

El orden de los comandos en la plantilla de manifiesto es importante: inicialmente, tenemos la lista de archivos predeterminados como se describió anteriormente, y cada comando en la plantilla agrega o elimina de esa lista de archivos. Una vez que hemos procesado completamente la plantilla del manifiesto, eliminamos los archivos que no deberían incluirse en la distribución del código fuente:

todos los archivos en el árbol «build» de Distutils (por defecto build/)

todos los archivos en directorios nombrados RCS, CVS, .svn, .hg, .git, .bzr o _darcs

Ahora tenemos la lista completa de archivos, que está escrita en el manifiesto para una futura referencia, y luego se utilizará para construir los archivos de distribución de código fuente.

Puede deshabilitar el conjunto predeterminado de archivos incluidos con la opción --no-defaults, y puede deshabilitar el conjunto de exclusión estándar con --no-prune.

Siguiendo la propia plantilla de manifiesto de Distutils, rastreemos cómo el comando sdist crea la lista de archivos para incluir en la distribución fuente de Distutils:

incluir todos los archivos fuente de Python en los sub-directorios distutils y distutils/command (porque los paquetes correspondientes a esos dos directorios se mencionaron en la opción packages en el script de configuración —vea la sección Escribir el script de configuración)

incluir:file:README.txt, setup.py, y setup.cfg (archivos estándar)

incluir test/test*.py (archivos estándar)

incluir *.txt en la raíz de la distribución(esto encontrará README.txt por segunda vez, pero tales redundancias se eliminan más tarde)

incluir cualquier archivo que coincida con *.txt or *.py en el subárbol dentro de examples,

excluir todos los archivos en los subárboles que comiencen en los directorios que coincidan con examples/sample?/build—esto puede excluir los archivos incluidos en los dos pasos anteriores, por lo que es importante que el comando prune en la plantilla de manifiesto vaya después del comando recursive-include

excluir todo el árbol build y cualquier directorio RCS, CVS, .svn, .hg, .git, .bzr y _darcs

Al igual que en el script de configuración, los nombres de archivos y directorios en la plantilla de manifiesto siempre deben estar separados por barras; Distutils se encargará de convertirlos a la representación estándar en su plataforma. De esa manera, la plantilla de manifiesto es portable en todos los sistemas operativos.

4.2. Opciones relacionadas con el manifesto

El curso normal de operaciones para el comando sdist es el siguiente:

si el archivo de manifiesto (MANIFEST por defecto) existe y la primera línea no tiene un comentario que indique que se genera a partir de MANIFEST.in, entonces se usa como está, sin alteraciones

si el archivo de manifiesto no existe o si se ha generado previamente de forma automática, lea MANIFEST.in y cree el manifiesto

si no existe MANIFEST ni MANIFEST.in, cree un manifiesto solamente con el conjunto de archivos predeterminado

use la lista de archivos, que ahora están en MANIFEST (ya sea generado o leído) para crear los archivos de distribución de código fuente

Existen un par de opciones que modifican este comportamiento. Primero, use --no-defaults y --no-prune para desactivar los conjuntos estándar «include» y «exclude».

Segundo, quizá quiera (re)generar el manifesto, pero no crear la distribución del código fuente:

python setup.py sdist --manifest-only

-o es una forma corta de --manifest-only.

5. Crear distribuciones compiladas

Nota

This document is being retained solely until the setuptools documentation at https://setuptools.readthedocs.io/en/latest/setuptools.html independently covers all of the relevant information currently included here.

Una «distribución compilada» es lo que probablemente conoce como un «paquete binario» o un «instalador» (dependiendo de sus antecedentes). No es necesariamente binario, sin embargo, porque podría contener sólo código fuente de Python o código de bytes; y no lo llamamos paquete, porque esa palabra ya existe en Python. (E «instalador» es un término específico para el mundo de los sistemas de escritorio convencionales.)

Una distribución compilada es la forma de hacer la vida lo más fácil posible para los instaladores de la distribución de módulos: para los usuarios de sistemas Linux basados en RPM, es un RPM binario; para los usuarios de Windows, es un instalador ejecutable; para los usuarios de Linux basados en Debian, es un paquete Debian; y así sucesivamente. Obviamente, ninguna persona podrá crear distribuciones compiladas para cada plataforma existente, por lo que los Distutils están diseñados para permitir que los desarrolladores de módulos se concentren en su especialidad—escribir código y crear distribuciones de fuentes—mientras una especie intermedia llamada empaquetadores surge para convertir las distribuciones de fuentes en distribuciones compiladas para tantas plataformas como empaquetadores.

Por supuesto, el desarrollador del módulo podría ser su propio empaquetador; o el empaquetador podría ser un voluntario «por ahí» en algún lugar que tenga acceso a una plataforma a la que el desarrollador original no tiene; o podría ser software que periódicamente obtiene nuevas distribuciones de fuentes y las convierte en distribuciones compiladas para tantas plataformas como el software tenga acceso. Independientemente de quiénes sean, un empaquetador utiliza el script de configuración y la familia de comandos bdist para generar distribuciones compiladas.

Como un ejemplo sencillo, si ejecuto el siguiente comando en el árbol de código de Distutils:

python setup.py bdist

a continuación, Distutils crea mi distribución de módulos (el propio Distutils en este caso), realiza una instalación «falsa» (también en el directorio build) y crea el tipo predeterminado de distribución compilada para mi plataforma. El formato predeterminado para las distribuciones compiladas es un archivo tar «dumb» en Unix, y un simple instalador ejecutable en Windows. (Ese archivo tar se considera «dumb» porque tiene que ser desempaquetado en una ubicación específica para funcionar.)

Por lo tanto, el comando anterior en un sistema Unix crea Distutils-1.0.plat.tar.gz; desempaquetar este tarball desde el lugar correcto instala el Distutils como si hubiera descargado la distribución de fuentes y ejecutado python setup.py install. (El «lugar correcto» es la raíz del sistema de ficheros o del directorio prefix de Python, dependiendo de las opciones dadas al comando bdist_dumb; por defecto se realizan distribuciones dumb relativas a prefix.)

Obviamente, para distribuciones puras de Python, esto es tan simple como ejecutar python setup.py install—pero para distribuciones no puras, que incluyen extensiones que tendrían que ser compiladas, puede significar la diferencia entre alguien que puede usar sus extensiones o no. Y crear distribuciones compiladas «inteligentes», como un paquete RPM o un instalador ejecutable para Windows, es mucho más conveniente para los usuarios, incluso si su distribución no incluye ninguna extensión.

El comando bdist tiene una opción --formats , similar al comando sdist, que puede utilizar para seleccionar los tipos de distribución compilada a generar: por ejemplo,

python setup.py bdist --format=zip

cuando se ejecuta en un sistema Unix, crearía Distutils-1.0.plat.zip—de nuevo, este archivo sería desempaquetado desde el directorio raíz para instalar Distutils.

Los formatos disponibles para distribuciones compiladas son:

Formato

Descripción

Notas

gztar

archivo gzipped tar (.tar.gz)

(1)

bztar

archivo bzipped tar (.tar.bz2)

xztar

archivo xzipped tar (.tar.xz)

ztar

archivo tar comprimido (.tar.Z)

(3)

tar

archivo tar (.tar)

zip

archivo zip (.zip)

(2),(4)

rpm

RPM

(5)

pkgtool

Solaris pkgtool

sdux

HP-UX swinstall

wininst

archivo ZIP autoextraíble para Windows

(4)

msi

Instalador Microsoft.

Distinto en la versión 3.5: Añadido soporte para el formato xztar.

Notas:

predeterminado en Unix

predeterminado en Windows

requiere utilidad externa compress .

requiere o bien la utilidad externa zip o bien el módulo zipfile (parte de la librería estándar de Python desde Python 1.6)

requiere la utilidad externa rpm, versión 3.0.4 o mejor (usar rpm --version para descubrir que versión tiene)

No tiene que usar el comando bdist con la opción --formats; también puede usar el comando que directamente implementa el formato en el que esté interesado. Algunos de estos subcomandos bdist de hecho generan varios formatos similares; por ejemplo, el comando bdist_dumb genera todos los formatos de archivo «dumb» (tar, gztar, bztar, xztar, ztar, y zip), y bdist_rpm genera tanto binario como fuentes RPMs. Los subcomandos bdist, y los formatos generados por cada uno, son:

Comando

Formatos

bdist_dumb

tar, gztar, bztar, xztar, ztar, zip

bdist_rpm

rpm, srpm

bdist_wininst

wininst

bdist_msi

msi

Nota

bdist_wininst se encuentra obsoleto desde Python 3.8.

Nota

bdist_msi está deprecado desde Python 3.9.

Las siguientes secciones proporcionan detalles sobre los comandos individuales de bdist_* .

5.1. Creando paquetes RPM

El formato RPM se usa en muchas distribuciones de Linux populares, incluyendo Red Hat, SuSE, y Mandrake. Si alguna de éstas (o cualquier otra distribución de Linux basada en RPM) es su entorno habitual, crear paquetes RPM para otros usuarios de la misma distribución es trivial. Dependiendo de la complejidad de su módulo de distribución y las diferencias entre distribuciones Linux, también podrá crear RPMs que funcionen en distribuciones diferentes basadas en RPM.

El forma más común de crear un RPM de su distribución de módulo es ejecutar el comando bdist_rpm

python setup.py bdist_rpm

o el comando bdist con la opción --format

python setup.py bdist --formats=rpm

El primero permite especificar las opciones específicas de RPM; el segundo permite especificar fácilmente varios formatos en una ejecución. Si necesita hacer los dos, se pueden especificar explícitamente múltiples comandos bdist_* y sus opciones:

python setup.py bdist_rpm --packager="John Doe <jdoe@example.org>" \
                bdist_wininst --target-version="2.0"

La creación de paquetes RPM es impulsada por un archivo .spec, al igual que el uso de Distutils es impulsado por el script de configuración. Para hacer su vida más fácil, el comando bdist_rpm normalmente crea un archivo .spec basado en la información que usted proporciona en el script de configuración, en la línea de comandos y en cualquier archivo de configuración de Distutils. Varias opciones y secciones en el archivo .spec se derivan de las opciones del script de configuración de la siguiente manera:

Opción de archivo RPM .spec o sección

Opción del script de instalación de Distutils

Nombre

name

Resumen (en el preámbulo)

description

Versión

version

Vendedor

author y author_email, o — & maintainer y maintainer_email

Copyright

license

Url

url

%description (sección)

long_description

Adicionalmente, hay muchas opciones en los archivos .spec que no se corresponden a opciones en el script de configuración. La mayoría de éstas están manejadas a través de opciones al comando bdist_rpm como sigue:

Opción de archivo RPM .spec o sección

Opción bdist_rpm

valor predefinido

Release

release

«1»

Grupo

group

«Desarrollo/Librerías»

Vendedor

vendor

(ver arriba)

Empaquetador

packager

(ninguno)

Proporciona

provides

(ninguno)

Requiere

requires

(ninguno)

Conflictos

conflicts

(ninguno)

Obsolescencias

obsoletes

(ninguno)

Distribución

distribution_name

(ninguno)

Requisitos de compilación

build_requires

(ninguno)

Icono

icon

(ninguno)

Obviamente, proporcionar incluso algunas de estas opciones en la línea de comandos sería tedioso y propenso a errores, por lo que generalmente es mejor ponerlas en el archivo de configuración de instalación,:file:setup.cfg— ver sección Escribiendo el archivo de configuración de instalación (setup). Si distribuye o empaqueta muchas distribuciones de módulos de Python, es posible que desee incluir opciones que se apliquen a todas ellas en su archivo de configuración personal de Distutils (~/.pydistutils.cfg). Si desea deshabilitar temporalmente este archivo, puede pasar la opción --no-user-cfg a setup.py.

Hay tres pasos para construir un paquete RPM binario, los cuales son manejados automáticamente por Distutils:

crear un archivo .spec. que describe el paquete (análogo al script de configuración de Distutils; de hecho, gran parte de la información en el script de configuración termina en el fichero .spec )

crear el fuente RPM

crear el «binario» RPM (que puede o no contener código binario, dependiendo de si la distribución de su módulo contiene extensiones Python)

Normalmente, RPM agrupa los dos últimos pasos; cuando usa las Distutils, los tres pasos generalmente están agrupados.

Si lo desea, puede separar estos tres pasos. Puede usar la opción --spec-only para hacer bdist_rpm simplemente cree el archivo .spec y salga; en este caso, el archivo .spec se escribirá en el «directorio de distribución»— normalmente dist/, pero se puede personalizar con la opción --dist-dir. (Normalmente, el archivo .spec termina en lo más profundo del «árbol de compilación», en un directorio temporal creado por bdist_rpm.)

5.2. Crear instaladores de Windows

Advertencia

bdist_wininst se encuentra obsoleto desde Python 3.8.

Advertencia

bdist_msi está deprecado desde Python 3.9.

Los instaladores ejecutables son el formato natural para distribuciones binarias en Windows. Muestran una agradable interfaz gráfica de usuario, con información sobre la distribución del módulo que se instalará extraída de los metadatos en el script de configuración, permiten al usuario seleccionar algunas opciones e iniciar o cancelar la instalación.

Dado que los metadatos se toman del script de configuración, crear instaladores de Windows suele ser tan fácil como ejecutar:

python setup.py bdist_wininst

o el comando bdist con la opción --formats

python setup.py bdist --formats=wininst

Si tiene una distribución de módulo pura (sólo conteniendo módulos de Python puros y paquetes), el instalador resultante será independiente de la versión y tendrá un nombre similar a foo-1.0.win32.exe. Tenga en cuenta que crear distribuciones binarias wininst sólo se soporta en sistemas Windows.

Si tiene distribuciones no puras, las extensiones sólo se pueden crear en una plataforma Windows, y serán dependientes de la versión de Python. El nombre de archivo del instalador reflejará esto y ahora tiene la forma foo-1.0.win32-py2.0.exe. Debe crear un instalador separado para cada versión de Python que se quiera soportar.

El instalador intentará compilar módulos puros en bytecode después de la instalación en el sistema de destino en modo normal y optimizado. Si no desea que esto suceda por alguna razón, puede ejecutar el comando bdist_wininst con la opción --no-target-compile o la opción --no-target-optimize.

Por defecto, el instalador mostrará el genial logo «Python Powered» cuando se ejecute, pero puede también proporcionar su propio mapa de bits de 152x261 que debe ser un archivo Windows .bmp con la opción --bitmap.

El instalador también mostrará un título grande en la pantalla de fondo del escritorio cuando se ejecute, que se construye a partir del nombre de su distribución y el número de versión. Esto se puede cambiar a otro texto usando la opción --title.

El archivo de instalación se escribirá en el «directorio de distribución» — normalmente dist/, pero se puede personalizar con la opción --dist-dir.

5.3. Compilación cruzada en Windows

A partir de Python 2.6, distutils es capaz de realizar una compilación cruzada entre plataformas Windows. En la práctica, esto significa que con las herramientas correctas instaladas, puede usar una versión de Windows de 32bit para crear extensiones de 64bit y viceversa.

Para compilar para una plataforma alternativa, especifique la opción --plat-name del comando de compilación. Los valores válidos son actualmente “win32”, y “win-amd64”. Por ejemplo, en una versión de Windows de 32bit, puede ejecutar:

python setup.py build --plat-name=win-amd64

para crear una versión de 64bit de su extensión. Los instaladores de Windows también admiten esta opción, por lo que el comando:

python setup.py build --plat-name=win-amd64 bdist_wininst

crearía un ejecutable de instalación de 64bit en su versión de 32bit de Windows.

Para realizar una compilación cruzada, debe descargar el código fuente de Python y compilar el propio Python para la plataforma a la que se dirige; no es posible desde una instalación binaria de Python (ya que el archivo .lib etc para otras plataformas no está incluido). En la práctica, esto significa que el usuario de un sistema operativo de 32bit necesitará usar Visual Studio 2008 para abrir la solución PCbuild/PCbuild.sln en el árbol de código de Python y construir la configuración » x64 » del proyecto “pythoncore” antes de que sea posible la compilación cruzada de extensiones.

Tenga en cuenta que, de forma predeterminada, Visual Studio 2008 no instala compiladores o herramientas de 64bit. Es posible que deba volver a ejecutar el proceso de instalación de Visual Studio y seleccionar estas herramientas (usar Panel de control -> [Agregar/Quitar] Programas es una forma conveniente de verificar o modificar su instalación existente).

5.3.1. El script posterior a la instalación

A partir de Python 2.3, se puede especificar un script posterior a la instalación con la opción --install-script . Se debe especificar el nombre base del script y el nombre del archivo del script también se debe incluir en el argumento de los scripts de la función de configuración.

Este script se ejecutará en el momento de la instalación en el sistema de destino después de que se hayan copiado todos los archivos, con argv[1] establecido en -install, y nuevamente en el momento de la desinstalación antes de que se eliminen los archivos con argv[1] establecido en -remove.

El script de instalación se ejecuta incrustado en el instalador de Windows, cada salida (sys.stdout, sys.stderr) se redirige a un búfer y se mostrará en la GUI una vez finalizado el script.

Algunas funciones especialmente útiles en este contexto están disponibles como funciones integradas adicionales en el script de instalación.

directory_created(path)

file_created(path)

Estas funciones deben llamarse cuando el script posterior a la instalación crea un directorio o archivo en el momento de la instalación. Registrará path con el des-instalador, de modo que se eliminará cuando se desinstale la distribución. Para mayor seguridad, los directorios solo se eliminan si están vacíos.

get_special_folder_path(csidl_string)

Esta función se puede utilizar para recuperar ubicaciones de directorios especiales en Windows como el menú Inicio o el escritorio. Retorna la ruta completa al directorio. csidl_string debe ser una de las siguientes cadenas:

"CSIDL_APPDATA"

"CSIDL_COMMON_STARTMENU"
"CSIDL_STARTMENU"

"CSIDL_COMMON_DESKTOPDIRECTORY"
"CSIDL_DESKTOPDIRECTORY"

"CSIDL_COMMON_STARTUP"
"CSIDL_STARTUP"

"CSIDL_COMMON_PROGRAMS"
"CSIDL_PROGRAMS"

"CSIDL_FONTS"

Si no se puede recuperar el directorio, se lanza OSError.

Los directorios disponibles dependen de la versión exacta de Windows y probablemente también de la configuración. Para obtener más información, consulte la documentación de Microsoft de la función SHGetSpecialFolderPath() .

create_shortcut(target, description, filename[, arguments[, workdir[, iconpath[, iconindex]]]])

Esta función crea un atajo. target es la ruta al programa que se iniciará con el acceso directo. description es la descripción del atajo. filename es el título del acceso directo que verá el usuario. arguments especifica los argumentos de la línea de comandos, si los hay. workdir es el directorio de trabajo del programa. iconpath es el archivo que contiene el icono del acceso directo, y iconindex es el índice del icono en el archivo iconpath. Nuevamente, para obtener más detalles, consulte la documentación de Microsoft para la interfaz IShellLink.

5.4. Vista User Access Control (UAC)

A partir de Python 2.6, bdist_wininst admite una opción --user-access-control. El valor predeterminado es “none” (lo que significa que no se realiza ningún gestión de UAC), y otros valores válidos son “auto” (lo que significa que se solicita la elevación de UAC si Python se instaló para todos los usuarios) y “force” (que significa que siempre se solicita la elevación).

Nota

bdist_wininst se encuentra obsoleto desde Python 3.8.

Nota

bdist_msi está deprecado desde Python 3.9.

6. Ejemplos de Distutils

Nota

This document is being retained solely until the setuptools documentation at https://setuptools.readthedocs.io/en/latest/setuptools.html independently covers all of the relevant information currently included here.

Este capitulo provee varios ejemplos básicos para ayudar a comenzar con distutils. Información adicional sobre el uso de distutils puede ser encontrado en el Distutils Cookbook.

Ver también

Distutils Cookbook [https://wiki.python.org/moin/Distutils/Cookbook]

Colección de recetas que muestran como lograr mayor control sobre distutils.

6.1. Distribución de Python pura (por módulo)

Si solo distribuyes un par de módulos, especialmente si no viven en un paquete en particular, puedes especificarlos individualmente usando la opción py_modules en el script de instalación.

En el caso más simple, tendrás dos archivos de los cuales preocuparte: un script de instalación y el único modulo que estás distribuyendo, en este ejemplo foo.py:

<root>/
        setup.py
        foo.py

(En todos los diagramas en esta sección, <root> se referirá al directorio raíz de la distribución.) Un script de instalación mínimo para describir esta situación seria:

from distutils.core import setup
setup(name='foo',
      version='1.0',
      py_modules=['foo'],
      )

Observe que el nombre de la distribución esta especificada de forma independiente con la opción name, y no hay ninguna regla que diga que tiene que ser el mismo que el nombre del único modulo de la distribución (aunque probablemente sea una buena convención a seguir). Sin embargo, el nombre de la distribución es usado para generar nombres de archivo, así que deberías limitarte a letras, dígitos, guión bajo, y guiones.

Dado que py_modules es una lista, puedes por supuesto especificar múltiples módulos, por ejemplo, si estás distribuyendo los módulos foo y bar, tu configuración podría verse así:

<root>/
        setup.py
        foo.py
        bar.py

y el script de instalación podría ser:

from distutils.core import setup
setup(name='foobar',
      version='1.0',
      py_modules=['foo', 'bar'],
      )

Puedes poner los archivos fuente de los módulos en otro directorio, pero si tienes suficientes módulos para hacerlo, probablemente sea mas fácil especificar los módulos por paquete en lugar de enumerarlos individualmente.

6.2. Distribución de Python pura (por paquete)

Si tienes más de un par de módulos para distribuir, especialmente si están en múltiples paquetes, probablemente sea más fácil especificar paquetes completos en lugar de módulos individuales. Esto funciona incluso si sus módulos no están en un paquete; solo puedes decirle a los Distutils que procese los módulos desde el paquete raíz, y eso funciona igual que cualquier otro paquete (excepto que no tiene que tener un archivo __init__.py.

El script de instalación del último ejemplo también podría ser escrito como:

from distutils.core import setup
setup(name='foobar',
      version='1.0',
      packages=[''],
      )

(La cadena de caracteres vacía representa el paquete raíz.)

Si esos dos archivos son movidos a un subdirectorio, pero permanecen en el paquete raíz, por ejemplo:

<root>/
        setup.py
        src/      foo.py
                  bar.py

entonces seguirías especificando el paquete raíz, pero tienes que decirle a los Distutils dónde viven los archivos fuente del paquete raíz:

from distutils.core import setup
setup(name='foobar',
      version='1.0',
      package_dir={'': 'src'},
      packages=[''],
      )

No obstante, lo mas típico es que quieras distribuir múltiples módulos en el mismo paquete (o en subpaquetes). Por ejemplo, si los módulos foo y bar pertenecen al paquete foobar, una forma de diseñar su estructura fuente es:

<root>/
        setup.py
        foobar/
                 __init__.py
                 foo.py
                 bar.py

Este es, de hecho, la distribución por defecto esperada por los Distutils, y la que requiere menos trabajo para describir en su script de instalación:

from distutils.core import setup
setup(name='foobar',
      version='1.0',
      packages=['foobar'],
      )

Si quieres poner módulos en directorios no nombrados por su paquete, entonces necesitas usar la opción package_dir otra vez. Por ejemplo, si el directorio src contiene los módulos en el paquete foobar:

<root>/
        setup.py
        src/
                 __init__.py
                 foo.py
                 bar.py

un script de instalación apropiado sería:

from distutils.core import setup
setup(name='foobar',
      version='1.0',
      package_dir={'foobar': 'src'},
      packages=['foobar'],
      )

O, podrías poner módulos de tu paquete principal justo en la raíz de la distribución:

<root>/
        setup.py
        __init__.py
        foo.py
        bar.py

en cuyo caso tu script de instalación sería:

from distutils.core import setup
setup(name='foobar',
      version='1.0',
      package_dir={'foobar': ''},
      packages=['foobar'],
      )

(La cadena de caracteres vacía también representa el directorio actual.)

Si tienes subpaquetes, deben ser listados explícitamente en packages, pero cualquier entrada en package_dir se extiende automáticamente a los subpaquetes. (En otras palabras, los Distutils no escanean tu estructura fuente, intentando descubrir que directorios corresponden a los paquetes de Python buscando por archivos __init__.py.) Por lo tanto, si la distribución por defecto hace crece un subpaquete:

<root>/
        setup.py
        foobar/
                 __init__.py
                 foo.py
                 bar.py
                 subfoo/
                           __init__.py
                           blah.py

entonces el script de instalación correspondiente sería:

from distutils.core import setup
setup(name='foobar',
      version='1.0',
      packages=['foobar', 'foobar.subfoo'],
      )

6.3. Módulo de extensión única

Los módulos de extensión son especificados usando la opción ext_modules. package_dir no tiene efecto sobre donde se encuentren los archivos fuente de la extensión; solo afecta a la fuente de los módulos de Python puro. El mas simple caso, un único modulo de extensión en un único archivo fuente de C, es:

<root>/
        setup.py
        foo.c

Si la extensión foo pertenece al paquete raíz, el script de instalación para este podría ser:

from distutils.core import setup
from distutils.extension import Extension
setup(name='foobar',
      version='1.0',
      ext_modules=[Extension('foo', ['foo.c'])],
      )

Si la extensión realmente pertenece a un paquete, digamos foopkg, entonces

Con exactamente la misma distribución del árbol fuente, esta extensión puede ser puesta en el paquete foopkg simplemente cambiando el nombre de la extensión:

from distutils.core import setup
from distutils.extension import Extension
setup(name='foobar',
      version='1.0',
      ext_modules=[Extension('foopkg.foo', ['foo.c'])],
      )

6.4. Verificando un paquete

El comando check le permite verificar si los metadatos de su paquete cumplen los requisitos mínimos para construir la distribución.

Para ejecutarlo, sólo tienes que llamarlo usando tu script setup.py. Si falta algo, check mostrará una advertencia.

Tomemos un ejemplo con un script simple:

from distutils.core import setup

setup(name='foobar')

La ejecución del comando check mostrará algunas advertencias:

$ python setup.py check
running check
warning: check: missing required meta-data: version, url
warning: check: missing meta-data: either (author and author_email) or
         (maintainer and maintainer_email) should be supplied

Si usas la sintaxis reStructuredText en el campo long_description y docutils [http://docutils.sourceforge.net] esta instalado puedes comprobar si la sintaxis está bien con el comando check, usando la opción restructuredtext.

Por ejemplo, si el script setup.py es cambiado así:

from distutils.core import setup

desc = """\
My description
==============

This is the description of the ``foobar`` package.
"""

setup(name='foobar', version='1', author='tarek',
    author_email='tarek@ziade.org',
    url='http://example.com', long_description=desc)

Donde se rompa la descripción larga, check será capaz de detectarla usando el analizador docutils:

$ python setup.py check --restructuredtext
running check
warning: check: Title underline too short. (line 2)
warning: check: Could not finish the parsing.

6.5. Leyendo los metadatos

La función distutils.core.setup() provee una interfaz de línea de comandos que te permite consultar los campos de metadatos de un proyecto a través del script setup.py de un proyecto dado:

$ python setup.py --name
distribute

Esta llamada lee los metadatos de name ejecutando la función distutils.core.setup(). Aunque, cuando se crea una distribución fuente o binaria con Distutils, los campos de metadatos son escritos en un archivo estático llamado PKG-INFO. Cuando un proyecto basado en Distutils es instalado en Python, el archivo PKG-INFO es copiado junto con los módulos y paquetes de la distribución en NAME-VERSION-pyX.X.egg-info, donde NAME es el nombre del proyecto, VERSION su versión como se define en los metadatos, y pyX.X` la versión mayor y menor de Python como ``2.7 o 3.2.

Puedes leer de nuevo este archivo estático usando la clase distutils.dist.DistributionMetadata y su método read_pkg_file():

>>> from distutils.dist import DistributionMetadata
>>> metadata = DistributionMetadata()
>>> metadata.read_pkg_file(open('distribute-0.6.8-py2.7.egg-info'))
>>> metadata.name
'distribute'
>>> metadata.version
'0.6.8'
>>> metadata.description
'Easily download, build, install, upgrade, and uninstall Python packages'

Note que la clase también puede ser instanciada con una ruta de archivo de metadatos para cargar sus valores:

>>> pkg_info_path = 'distribute-0.6.8-py2.7.egg-info'
>>> DistributionMetadata(pkg_info_path).name
'distribute'

7. Extendiendo Distutils

Nota

This document is being retained solely until the setuptools documentation at https://setuptools.readthedocs.io/en/latest/setuptools.html independently covers all of the relevant information currently included here.

Distutils se puede extender de diversas maneras. La mayoría de las extensiones toman la forma de nuevos comandos o reemplazos de comandos ya existentes. Se pueden escribir nuevos comandos para soportar nuevos tipos de paquetes específicos de la plataforma, por ejemplo, mientras que se pueden reemplazar comandos existentes para modificar los detalles de cómo funciona dicho comando en un paquete.

La mayoría de las extensiones de distutils están hechas dentro de los scripts setup.py donde se desea modificar los comandos existentes. Muchos simplemente añaden algunas extensiones de archivo que deben copiarse dentro de los paquetes, además de los archivos .py, para mayor comodidad.

La mayoría de las implementaciones de comandos distutils son subclases de la clase distutils.cmd.Command. Los nuevos comandos pueden heredar directamente de Command. Mientras que los comandos de reemplazo a menudo derivan de la clase Command de manera indirecta, subclasificando directamente el comando que están reemplazando. Se requiere que los comandos deriven de Command.

7.1. Integrando nuevos comandos

Existen diferentes formas de integrar nuevas implementaciones de comandos en distutils. La más difícil es forzar la inclusión de nuevas funciones en distutils y esperar (y requerir) una versión de Python que brinde ese soporte. Esto es realmente complicado por muchas razones.

La más común, y posiblemente la más lógica para casi todas las necesidades, es incluir las nuevas implementaciones con su script setup.py y hacer que la función distutils.core.setup() las utilice:

from distutils.command.build_py import build_py as _build_py
from distutils.core import setup

class build_py(_build_py):
    """Specialized Python source builder."""

    # implement whatever needs to be different...

setup(cmdclass={'build_py': build_py},
      ...)

Este enfoque es más valioso sí las nuevas implementaciones deben utilizarse para hacer uso de un paquete en particular, ya que todos los interesados en el paquete deberán tener la implementación del nuevo comando.

A partir de Python 2.4, hay una tercera opción disponible, destinada a permitir agregar nuevos comandos que sean compatibles con los scripts setup.py existentes, sin requerir modificaciones en la instalación de Python. Se espera que esto permita que las extensiones de terceros brinden soporte para sistemas de empaquetado adicionales, pero los comandos pueden ser usados en los mismos casos en los que los comandos de distutils son utilizados. Una nueva opción de configuración, command_packages (opción de la línea de comandos --command-packages), puede ser aplicada para especificar paquetes adicionales a ser buscados para módulos que implementen comandos. Como todas las opciones de distutils, esto puede especificarse en la línea de comandos o en un archivo de configuración. Esta opción sólo se puede configurar en la sección [global] de un archivo de configuración, o antes de cualquier comando en la línea de comandos. Si se establece en un archivo de configuración, se puede sobrescribir desde la línea de comandos. Establecer una cadena de caracteres vacía como valor de esta opción en la línea de comandos forzará el uso del valor predeterminado. Esto nunca debería ser establecido en un archivo de configuración proporcionado con un paquete.

Esta nueva opción puede ser usada para añadir cualquier cantidad de número de paquetes a la lista de paquetes buscados para las implementaciones de comandos; los nombres múltiples de paquetes deben ser separados por comas. Cuando no se especifica, la búsqueda sólo se realiza en el paquete distutils.command. Sin embargo, cuando setup.py se ejecuta con la opción --command-packages distcmds,buildcmds, se buscarán los paquetes distutils.command, distcmds y buildcmds en ese orden. Se espera que los nuevos comandos se implementen en módulos con idéntico nombre que el comando mediante clases que comparten el mismo nombre. Dado el ejemplo anterior de la opción de línea de comandos, el comando bdist_openpkg podría ser implementado por la clase distcmds.bdist_openpkg.bdist_openpkg o por la clase buildcmds.bdist_openpkg.bdist_openpkg.

7.2. Añadiendo nuevos tipos de distribución

Los comandos que crean distribuciones (archivos en el directorio dist/) necesitan añadir el par (command, filename) a self.distribution.dist_files para que de este modo upload pueda subirlo a PyPI. El elemento filename en el par no contiene información de la ruta, solo el nombre del archive en sí. En el modo ensayo, los pares aún deben ser añadidos para representar lo que se habría creado.

8. Referencia de Instrucciones

Nota

This document is being retained solely until the setuptools documentation at https://setuptools.readthedocs.io/en/latest/setuptools.html independently covers all of the relevant information currently included here.

8.1. Instalando módulos: la familia de comandos install

Los comandos de instalación aseguran que los comandos de construcción se han ejecutado y también se han ejecutado los subcomandos install_lib, install_data y install_scripts.

8.1.1. install_data

Este comando instala todos los archivos de datos proporcionados con la distribución.

8.1.2. install_scripts

Este comando instala todos los scripts (Python) en la distribución.

8.2. Creando una distribución de origen: el comando sdist

Los comandos de la plantilla manifest son:

Comando

Descripción

include pat1 pat2 ...

incluye todos los archivos que coincidan con cualquiera de los patrones enumerados

exclude pat1 pat2 ...

excluye todos los archivos que coincidan con cualquiera de los patrones enumerados

recursive-include dir pat1 pat2 ...

incluye todos los archivos dir que coincidan con cualquiera de los patrones enumerados

recursive-exclude dir pat1 pat2 ...

excluye todos los archivos dir que coincidan con cualquiera de los patrones enumerados

global-include pat1 pat2 ...

incluye todos los archivos de cualquier lugar en el árbol fuente que coincidan — y cualquiera de los patrones enumerados

global-exclude pat1 pat2 ...

excluye todos los archivos de cualquier lugar en el árbol fuente que coincidan — y cualquiera de los patrones enumerados

prune dir

excluye todos los archivos dir

graft dir

incluye todos los archivos dir

Los patrones aquí son patrones «glob» de estilo Unix: * coincide con cualquier secuencia de caracteres de nombre de archivo habitual, ? coincide con cualquier caracter de nombre de archivo habitual, y [range] coincide con cualquiera de los caracteres en range (p. ej., a-z, a-zA-Z, a-f0-9_.). La definición de «caracter de nombre de archivo habitual» es específica de la plataforma: en Unix es cualquier cosa excepto barra; en Windows cualquier cosa excepto barra invertida o dos puntos.

9. Referencia de la API

Ver también

Argumentos nuevos y cambiados de setup.py en setuptools [https://setuptools.readthedocs.io/en/latest/setuptools.html#new-and-changed-setup-keywords]

El proyecto setuptools añade nuevas capacidades a la función setup y otras API, hace que la API sea coherente en diferentes versiones de Python y, por lo tanto, se recomienda usar distutils directamente.

Nota

This document is being retained solely until the setuptools documentation at https://setuptools.readthedocs.io/en/latest/setuptools.html independently covers all of the relevant information currently included here.

9.1. distutils.core — Funcionalidad Core Distutils

El módulo distutils.core es el único módulo que necesita ser instalado para utilizar Distutils. Proporciona el setup() (que es llamado desde el script de configuración). Indirectamente proporciona la clase distutils.dist.Distribution y la clase distutils.cmd.Command.

distutils.core.setup(arguments)

La función básica do-everything hace casi todo lo que podrías pedir de un método Distutils.

La función de configuración toma un gran número de argumentos. Estos se presentan en la siguiente tabla.

nombre del argumento

valor

tipo

name

El nombre del paquete

un string

version

El número de versión del paquete; ver distutils.version

un string

description

Una sola línea describiendo el paquete

un string

long_description

Descripción larga del paquete

un string

author

El nombre del autor del paquete

un string

author_email

La dirección de correo electrónico del autor del paquete

un string

maintainer

El nombre del mantenedor actual, si es diferente del autor. Ten en cuenta que si se proporciona el mantenedor, distuils lo usará como el autor en PKG-INFO

un string

maintainer_email

La dirección de correo electrónico del mantenedor actual, si es diferente del autor

un string

url

Una URL para el paquete (página principal)

un string

download_url

Una URL para descargar el paquete

un string

packages

Una lista de paquetes Python que distutils podrá manipular

una lista de strings

py_modules

Una lista de módulos Python que distutils podrá manipular

una lista de strings

scripts

Una lista de archivos únicos de scripts que serán creados e instalados

una lista de strings

ext_modules

Una lista de extensiones Python para ser creadas

una lista de las instancias de la clase distutils.core.Extension

classifiers

Una lista de categorías para el paquete

una lista de strings; los clasificadores válidos están listados en PyPI [https://pypi.org/classifiers].

distclass

la clase para usar la clase Distribution

una sub-clase de la clase distutils.core.Distribution

script_name

El nombre del script del setup.py - el predeterminado es sys.argv[0]

un string

script_args

Argumentos para suministrar el script de configuración

una lista de strings

options

opciones por defecto para el script de configuración

un diccionario

license

La licencia para el paquete

un string

keywords

Metadatos descriptivos, ver PEP 314 [https://www.python.org/dev/peps/pep-0314]

una lista de strings o un string separado por comas

platforms

una lista de strings o un string separado por comas

cmdclass

Una asignación de los nombres de los comandos a las sub-clases de la clase Command

un diccionario

data_files

Una lista de archivos de datos para instalar

una lista

package_dir

Una asignación de directorios a los nombres de los paquetes

un diccionario

distutils.core.run_setup(script_name[, script_args=None, stop_after='run'])

Ejecuta un script de instalación en un entorno algo controlado y retorna la instancia de la clase distutils.dist.Distribution que maneja las cosas. Esto es útil si se necesitan encontrar los metadatos de distribución (pasados ​​como palabra clave args desde un script a la función setup()), o el contenido de los archivos de configuración o la línea de comandos.

script_name o nombre del script es un archivo que será leído y ejecutado con la función exec(). sys.argv[0] será reemplazado con un script durante la duración de la llamada. script_args es una lista de strings; si se proporciona, sys.argv[1:] será reemplazado por script_args durante la duración de la llamada.

stop_after le dice a la función setup() cuando parar el procesamiento; los valores posibles son:

valor

descripción

init

Detiene después de que la instancia de la clase Distribution haya sido creada y llenada con los argumentos de la palabra clave para la función setup()

config

Detiene después que los archivos de configuración hayan sido analizados (y sus datos almacenados en la instancia de la clase Distribution)

commandline

Detiene después de que la línea de comandos (sys.argv[1:] o script_args) se haya analizado (y los datos almacenados en la instancia de la clase Distribution.)

run

Detiene después de que todos los comandos hayan sido ejecutados (lo mismo que si la función setup() haya sido llamada de forma habitual). Este es el valor predeterminado.

Además, el módulo distutils.core expuso una serie de clases que residen en otros lugares.

la clase Extension del módulo distutils.extension

la clase Command del módulo distutils.cmd

la clase Distribution del módulo distutils.dist

A continuación una breve descripción de cada uno de estos, pero para una referencia completa consulta el módulo correspondiente.

class distutils.core.Extension

La clase Extension describe un solo módulo de extensión C o C++ en un script de configuración. Acepta los siguientes argumentos de palabras clave de su constructor:

nombre del argumento

valor

tipo

name

el nombre completo de la extensión, incluidos los paquetes — es decir, no un nombre de archivo o ruta, sino un nombre punteado Python

un string

sources

lista de nombres de archivos de origen, en relación con la raíz de distribución (donde reside el script de configuración), en forma Unix (separados por barras) para su portabilidad. Los archivos fuente pueden ser C, C ++, SWIG (.i), archivos de recursos específicos de la plataforma o cualquier otra cosa que el comando build_ext reconozca como fuente para una extensión de Python.

una lista de strings

include_dirs

lista de los directorios para buscar archivos de encabezados de C/C++ (en forma de Unix para portabilidad)

una lista de strings

define_macros

lista de macros para definir; cada macro se define usando una tupla de 2 (*name*, *value*), donde value es el string para definirla o None para definirla sin un valor particular (equivalente a #define FOO en la fuente o -DFOO en la línea de comandos de un compilador de Unix C)

una lista de tuplas

undef_macros

lista de macros para indefinir explícitamente

una lista de strings

library_dirs

lista de directorios para buscar bibliotecas C/C++ en el momento del enlace

una lista de strings

libraries

lista de nombres de bibliotecas para vincular (no nombres de archivos o rutas)

una lista de strings

runtime_library_dirs

lista de directorios para buscar bibliotecas C/C++ en tiempo de ejecución (para extensiones compartidas, esto es cuando se carga una extensión)

una lista de strings

extra_objects

lista de archivos adicionales para vincular (por ejemplo, archivos de objeto no implícitos en *sources*, una biblioteca estática que debe especificarse explicitamente, archivos de recursos binarios, etc.)

una lista de strings

extra_compile_args

cualquier adicional específico de la plataforma y del compilador para usar cuando compila los archivos fuente en *sources*. Para plataformas y compiladores donde una línea de comando tiene sentido, esta es típicamente una lista de argumentos de línea de comando pero para otras plataformas podría ser cualquier cosa.

una lista de strings

extra_link_args

cualquier adicional específico de la plataforma y del compilador para usar al vincular archivos del tipo objeto para crear la extensión (o para crear un nuevo intérprete de Python estático). Interpretación similar a la de *extra_compile_args*.

una lista de strings

export_symbols

lista de símbolos que se exportarán desde una extensión compartida. No se usa en todas las plataformas y, en general, no es necesario para las extensiones de Python, que normalmente exportan exactamente un símbolo: init + extension_name.

una lista de strings

depends

lista de archivos de los que depende la extensión

una lista de strings

language

lenguaje de extensión (es decir, 'c', 'c++', 'objc'). Se detectará en las extensiones de origen si no se proporcionan.

un string

optional

especifica que una falla de compilación en la extensión no debe abortar el proceso de compilación, sino simplemente omitir la extensión.

un booleano

Distinto en la versión 3.8: En Unix, las extensiones C ya no están vinculadas a libpython excepto en Android y Cygwin.

class distutils.core.Distribution

Una clase Distribution describe cómo construir, instalar y empaquetar un paquete de software Python.

Consulta la función setup() para obtener una lista de argumentos de palabras clave aceptados por el constructor de distribución. La función setup() crea una instancia de distribución.

Distinto en la versión 3.7: La clase Distribution ahora advierte si los campos *classifiers*, *keywords* y *platforms* no se especifican como una lista o un string.

class distutils.core.Command

Una clase Command (o más bien, una instancia de una de sus subclases) implementa un solo comando distutils.

9.2. distutils.ccompiler — Clase base CCompiler

Este módulo proporciona la clase base abstracta para las clases CCompiler. Una instancia de la clase CCompiler se puede usar para todos los pasos de compilación y enlace necesarios para construir un solo proyecto. Se proporcionan métodos para establecer opciones para el compilador — definiciones de macros, que incluyen directorios, ruta de enlace, bibliotecas y similares.

Este módulo proporciona las siguientes funciones.

distutils.ccompiler.gen_lib_options(compiler, library_dirs, runtime_library_dirs, libraries)

Genera opciones de vinculador para buscar directorios de bibliotecas y vincular con bibliotecas específicas. libraries y * library_dirs* son, respectivamente, listas de nombres de bibliotecas (no nombres de archivos!) y directorios de búsqueda. Retorna una lista de opciones de línea de comandos adecuadas para su uso con algún compilador (dependiendo de los dos strings de formato suministrados).

distutils.ccompiler.gen_preprocess_options(macros, include_dirs)

Genera opciones de preprocesador de C (-D, -U, -I) tal como lo utilizan al menos dos tipos de compiladores: el compilador típico de Unix y el Visual C++. macros es lo habitual, una lista de 1 o 2 tuplas, donde (*name*,) significa indefinir (-U) macro name, y (*name*, *value*) significa definir (-D) macro de name a value. include_dirs es solo una lista de nombres de directorio que se agregarán a la ruta de búsqueda del archivo de encabezado (-I). Retorna una lista de opciones de línea de comandos adecuadas para compiladores de Unix o Visual C++.

distutils.ccompiler.get_default_compiler(osname, platform)

Determina el compilador predeterminado que se utilizará para la plataforma dada.

osname debe ser uno de los nombres estándar de Python OS (es decir, los retornados por os.name) y platform el valor común retornado por sys.platform para la plataforma en cuestión.

Los valores predeterminados son os.name y sys.platform en caso de que no se proporcionen los parámetros.

distutils.ccompiler.new_compiler(plat=None, compiler=None, verbose=0, dry_run=0, force=0)

Función de fábrica para generar una instancia de alguna subclase CCompiler para la combinación de plataforma/compilador proporcionada. plat por defecto es os.name (por ejemplo, 'posix', 'nt'), y compiler por defecto es el compilador por defecto para esa plataforma. Actualmente solo se admiten 'posix' y 'nt', y los compiladores predeterminados son la «interfaz Unix tradicional» (clase UnixCCompiler) y Visual C++ (clase MSVCCompiler). Tenga en cuenta que es perfectamente posible solicitar un objeto de compilador de Unix en Windows y un objeto de compilador de Microsoft en Unix — si proporciona un valor para compiler, plat es ignorado.

distutils.ccompiler.show_compilers()

Imprime la lista de compiladores disponibles (usado por las opciones - help-compiler para build, :command: build_ext, build_clib).

class distutils.ccompiler.CCompiler([verbose=0, dry_run=0, force=0])

La clase base abstracta CCompiler define la interfaz que deben implementar las clases de compiladores reales. La clase también tiene algunos métodos de utilidad utilizados por varias clases de compiladores.

La idea básica detrás de una clase de abstracción de compilador es que cada instancia se puede usar para todos los pasos de compilación/enlace en la construcción de un solo proyecto. Por lo tanto, los atributos comunes a todos esos pasos de compilación y enlace — incluyen directorios, macros para definir, bibliotecas para enlazar, etc. — son atributos de la instancia del compilador. Para permitir la variabilidad en la forma en que se tratan los archivos individuales, la mayoría de esos atributos se pueden variar por compilación o por enlace.

El constructor de cada subclase crea una instancia del objeto Compiler. Los indicadores son verbose (muestra un resultado detallado), dry_run (en realidad no ejecuta los pasos) y force (reconstruye todo, independientemente de las dependencias). Todos estos indicadores están predeterminados en 0 (desactivado). Ten en cuenta que probablemente no desees crear una instancia de CCompiler o una de sus subclases directamente; usa la función de fábrica distutils.CCompiler.new_compiler() en su lugar.

Los siguientes métodos te permiten modificar manualmente las opciones del compilador para la instancia de la clase Compiler.

add_include_dir(dir)

Agrega dir a la lista de directorios en los que se buscarán archivos de encabezado. Se le indica al compilador que busque directorios en el orden en que son proporcionados por llamadas sucesivas a add_include_dir().

set_include_dirs(dirs)

Establece la lista de directorios que se buscarán en dirs (una lista de strings). Anula cualquier llamada anterior a add_include_dir(); llamadas posteriores a add_include_dir() agrega a la lista pasada a set_include_dirs(). Esto no afecta a ninguna lista de directorios de inclusión estándar que el compilador pueda buscar de forma predeterminada.

add_library(libname)

Agrega libname a la lista de bibliotecas que se incluirán en todos los enlaces manejados por este compilador de objeto. Ten en cuenta que libname debería no ser el nombre de un archivo que contenga una biblioteca, sino el nombre de la biblioteca en sí: el enlazador, el compilador o la clase del compilador deducirán el nombre del archivo actual (según el plataforma).

Se le indicará al enlazador que se vincule con las bibliotecas en el orden en que se proporcionaron add_library() y/o set_libraries(). Es perfectamente válido duplicar nombres de bibliotecas; se le indicará al enlazador que se vincule con las bibliotecas tantas veces como se mencionen.

set_libraries(libnames)

Establece la lista de bibliotecas que se incluirán en todos los enlaces manejados ​​por este compilador de objeto en libnames (una lista de strings). Esto no afecta a las bibliotecas del sistema estándar que el vinculador pueda incluir de forma predeterminada.

add_library_dir(dir)

Agrega dir a la lista de directorios en los que se buscarán las bibliotecas especificadas para add_library() y set_libraries(). Se le indicará al enlazador que busque bibliotecas en el orden en que se suministran a add_library_dir() y/o set_library_dirs().

set_library_dirs(dirs)

Establece la lista de directorios de búsqueda de bibliotecas en dirs (una lista de strings). Esto no afecta a ninguna ruta de búsqueda de biblioteca estándar que el enlazador pueda buscar de forma predeterminada.

add_runtime_library_dir(dir)

Agrega dir a la lista de directorios en los que se buscarán bibliotecas compartidas en tiempo de ejecución.

set_runtime_library_dirs(dirs)

Establece la lista de directorios para buscar bibliotecas compartidas en tiempo de ejecución en dirs (una lista de strings). Esto no afecta a ninguna ruta de búsqueda estándar que el enlazador en tiempo de ejecución pueda buscar de forma predeterminada.

define_macro(name[, value=None])

Define una macro de preprocesador para todas las compilaciones impulsadas por este objeto compilador. El parámetro opcional value debe ser un string; si no se proporciona, la macro se definirá sin un valor explícito y el resultado exacto depende del compilador utilizado.

undefine_macro(name)

Anula la definición de una macro de preprocesador para todas las compilaciones impulsadas por este compilador de objeto. Si la misma macro está definida por define_macro() y la indefinida por undefine_macro(), la última llamada tiene prioridad (incluidas varias redefiniciones o indefiniciones). Si la macro está redefinida/indefinida por compilación (es decir, en la llamada a compile()), entonces eso tiene prioridad.

add_link_object(object)

Agrega object a la lista de archivos de objeto (o análogos, como archivos de biblioteca nombrados explícitamente o la salida de «resource compilers» o compiladores de recursos) para que se incluyan en cada enlace impulsado por este objeto de compilador.

set_link_objects(objects)

Establece la lista de archivos de objetos (o análogos) que se incluirán en cada enlace a objects. Esto no afecta a ningún archivo de objeto estándar que el enlazador pueda incluir de forma predeterminada (como las bibliotecas del sistema).

Los siguientes métodos implementan métodos para la detección automática de opciones del compilador, proporcionando alguna funcionalidad similar a GNU :program: autoconf.

detect_language(sources)

Detecta el idioma de un archivo determinado o una lista de archivos. Utiliza los atributos de instancia language_map (un diccionario) y language_order (una lista) para hacer el trabajo.

find_library_file(dirs, lib[, debug=0])

Busca en la lista especificada de directorios un archivo de biblioteca estático o compartido y retorna la ruta completa a ese archive lib. Si debug es verdadero, busca una versión de depuración (si tiene sentido en la plataforma actual). Retorna None si lib no se encontró en ninguno de los directorios especificados.

has_function(funcname[, includes=None, include_dirs=None, libraries=None, library_dirs=None])

Retorna un valor booleano que indica si funcname es compatible con la plataforma actual. Los argumentos opcionales se pueden utilizar para aumentar el entorno de compilación proporcionando archivos y rutas de inclusión adicionales y bibliotecas y rutas.

library_dir_option(dir)

Retorna la opción del compilador para agregar dir a la lista de directorios buscados por bibliotecas.

library_option(lib)

Retorna la opción del compilador para agregar lib a la lista de bibliotecas vinculadas a la biblioteca compartida o ejecutable.

runtime_library_dir_option(dir)

Retorna la opción del compilador para agregar dir a la lista de directorios buscados por bibliotecas en tiempo de ejecución.

set_executables(**args)

Define los ejecutables (y las opciones para ellos) que se ejecutarán para realizar las distintas etapas de compilación. El conjunto exacto de ejecutables que se pueden especificar aquí depende de la clase del compilador (a través del atributo de clase “executables”), pero la mayoría tendrá:

atributo

descripción

compiler

el compilador C/C++

linker_so

enlazador utilizado para crear bibliotecas y objetos compartidos

linker_exe

enlazador utilizado para crear ejecutables binarios

archiver

creador de biblioteca estática

En plataformas con una línea de comandos (Unix, DOS/Windows), cada uno de estos es un string que se dividirá en un nombre ejecutable y una lista de argumentos (opcional). (La división de la cadena se realiza de manera similar a como funcionan los shells de Unix: las palabras están delimitadas por espacios, pero las comillas y las barras invertidas pueden anular esto. Ver distutils.util.split_quoted().)

Los siguientes métodos invocan etapas en el proceso de construcción.

compile(sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None])

Compila uno o más archivos fuente. Genera archivos de objeto (por ejemplo, transforma un archivo .c en un archivo .o).

sources debe ser una lista de nombres de archivo, probablemente archivos C/C ++, pero en realidad cualquier cosa que pueda ser manejada por un compilador particular y un compilador de clase (por ejemplo MSVCCompiler puede manejar archivos de recursos en source). Retorna una lista de nombres de archivos de objetos, uno por nombre de archivo fuente en sources. Dependiendo de la implementación, no se compilarán necesariamente todos los archivos fuente, pero se retornarán todos los nombres de archivo de objeto correspondientes.

Si se indica el output_dir, los objeto de archivos se colocarán debajo de él, conservando su componente de ruta original. Es decir, foo/bar.c normalmente se compila en foo/bar.o (para una implementación de Unix); si output_dir es build, entonces se compilaría en build/foo/bar.o.

macros, si se proporciona, debe ser una lista de definiciones de una macro. Una definición de una macro es un (*name*, *value*) 2-tupla o un (*name*,) 1-tupla. El primero define una macro; si el valor es None, la macro se define sin un valor explícito. El caso de 1 tupla no define una macro. Las definiciones/redefiniciones/indefiniciones posteriores tienen prioridad.

include_dirs, si se proporciona, debe ser una lista de strings, para esta compilación solo se agregarán a la ruta de búsqueda de archivos los directorios de inclusión predeterminada.

debug es un booleano; si es verdadero, se le indicará al compilador que genere símbolos de depuración en (o junto a) los archivos de objetos.

extra_preargs y extra_postargs dependen de la implementación. En plataformas que tienen la noción de línea de comandos (por ejemplo, Unix, DOS/Windows), lo más probable es que sean listas de strings: argumentos de línea de comandos adicionales para anteponer/agregar a la línea de comandos del compilador. En otras plataformas, consulta la documentación de la clase de implementación. En cualquier caso, están pensados ​​como una vía de escape para aquellas ocasiones en las que la marco del compilador abstracto no es suficiente.

depends, si se proporciona, es una lista de nombres de archivos de los que dependen todos los destinos. Si un archivo de origen es más antiguo que cualquier archivo en depends, se volverá a compilar el archivo de origen. Esto admite el seguimiento de dependencias, pero solo con una granularidad aproximada.

Lanza CompileError en caso de falla.

create_static_lib(objects, output_libname[, output_dir=None, debug=0, target_lang=None])

Enlaza un montón de cosas para crear un archivo de biblioteca estático. El «montón de cosas» o «bunch of stuff» consiste en la lista de archivos de objeto suministrados como objects, los archivos de objeto adicionales suministrados a add_link_object() y/o set_link_objects(), las bibliotecas suministradas a add_library() y/o set_libraries(), y las bibliotecas proporcionadas como libraries (si las hay).

output_libname debe ser un nombre de biblioteca, no un nombre de archivo; el nombre del archivo se deducirá del nombre de la biblioteca. output_dir es el directorio donde se colocará el archivo de la biblioteca.

debug es un booleano; si es verdadero, la depuración se incluirá en la biblioteca (ten en cuenta que en la mayoría de las plataformas, es el paso de compilación donde esto es importante: el indicador debug se incluye aquí solo por coherencia).

target_lang es el idioma de destino para el que se compilan los objetos dados. Esto permite un tratamiento específico del tiempo de vinculación de ciertos idiomas.

Lanza LibError en caso de falla.

link(target_desc, objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])

Enlaza un montón de cosas (o bunch of stuff) juntos para crear un archivo de biblioteca ejecutable o compartido.

El «montón de cosas» o (bunch of stuff) consiste en la lista de archivos de objeto suministrados como objects *. *output_filename debe ser un nombre del archivo. Si se proporciona output_dir, output_filename es relativo a él (es decir, output_filename puede proporcionar componentes de directorio si es necesario).

libraries es una lista de bibliotecas para enlazar. Estos son nombres de bibliotecas, no nombres de archivos, ya que se traducen a nombres de archivos de una manera específica de la plataforma (por ejemplo, foo se convierte en libfoo.a en Unix y foo.lib en DOS/Windows). Sin embargo, pueden incluir un componente de directorio, lo que significa que el enlazador buscará en ese directorio específico en lugar de buscar en todas las ubicaciones normales.

library_dirs, si se proporciona, debe ser una lista de directorios para buscar bibliotecas que se especificaron como nombres de bibliotecas descubiertos (es decir, sin componentes de directorio). Estos están en la parte superior del sistema predeterminado y los suministrados a add_library_dir() y/o set_library_dirs(). runtime_library_dirs es una lista de directorios que se incrustarán en la biblioteca compartida y se usarán para buscar otras bibliotecas compartidas de las que depende en tiempo de ejecución. (Esto solo puede ser relevante en Unix).

export_symbols es una lista de símbolos que exportará la biblioteca compartida. (Esto parece ser relevante solo en Windows).

debug es para métodos como compile() y create_static_lib(), con la ligera distinción de que en realidad es relevante en la mayoría de las plataformas (a diferencia de create_static_lib(), que incluye un indicador debug principalmente por el bien de la forma).

extra_preargs y extra_postargs son para métodos como compile() (excepto, por supuesto, que proporcionan argumentos de línea de comandos para el enlazador particular que se está utilizando).

target_lang es el idioma de destino para el que se compilan los objetos dados. Esto permite un tratamiento específico del tiempo de vinculación de ciertos idiomas.

Lanza LinkError en caso de falla.

link_executable(objects, output_progname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, target_lang=None])

Enlaza un ejecutable. output_progname es el nombre del archivo ejecutable, mientras que objects son una lista de nombres de archivos de objetos para vincular. Otros argumentos son para métodos como link().

link_shared_lib(objects, output_libname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])

Enlaza una biblioteca compartida. output_libname es el nombre de la biblioteca de salida, mientras que objects es una lista de nombres de archivos de objetos para vincular. Otros argumentos son para métodos como link().

link_shared_object(objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])

Enlaza un objeto compartido. output_filename es el nombre del objeto compartido que se creará, mientras que objects es una lista de nombres de archivos de objetos para vincular. Otros argumentos son para métodos como link().

preprocess(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None])

Preprocesa un solo archivo fuente C/C ++, nombrado en source. La salida se escribirá en el archivo llamado output_file, o stdout si output_file no se proporciona. macros es una lista de definiciones de macros para métodos como compile(), que aumentará el conjunto de macros con define_macro() y undefine_macro(). include_dirs es una lista de nombres de directorio que se agregarán a la lista predeterminada, de la misma manera que add_include_dir().

Lanza PreprocessError en caso de falla.

Los siguientes métodos de utilidad están definidos por la clase CCompiler, para uso de las distintas subclases concretas.

executable_filename(basename[, strip_dir=0, output_dir=''])

Retorna el nombre de archivo del ejecutable para el basename dado. Por lo general, para las plataformas que no son de Windows, este es el mismo que el nombre base, mientras que Windows obtendrá un archivo .exe agregado.

library_filename(libname[, lib_type='static', strip_dir=0, output_dir=''])

Retorna el nombre de archivo para el nombre de biblioteca dado en la plataforma actual. En Unix, una biblioteca con lib_type de 'static' normalmente tendrá la forma liblibname.a, mientras que lib_type de 'dynamic' tendrá la forma liblibname.so.

object_filenames(source_filenames[, strip_dir=0, output_dir=''])

Retorna el nombre de los archivos de objeto para los archivos de origen dados. source_filenames debe ser una lista de nombres de archivo.

shared_object_filename(basename[, strip_dir=0, output_dir=''])

Retorna el nombre de un archivo de objeto compartido para el nombre de archivo basename.

execute(func, args[, msg=None, level=1])

Invoca el método distutils.util.execute(). Este método invoca una función de Python func con los argumentos args dados, después de iniciar sesión y teniendo en cuenta el indicador dry_run.

spawn(cmd)

Invoca distutils.util.spawn(). Esto invoca un proceso externo para ejecutar el comando dado.

mkpath(name[, mode=511])

Invoca distutils.dir_util.mkpath(). Esto crea un directorio y los directorios ancestros que faltan.

move_file(src, dst)

Invoca distutils.file_util.move_file(). Cambia el nombre de src a dst.

announce(msg[, level=1])

Escribe un mensaje usando distutils.log.debug().

warn(msg)

Escribe un mensaje de advertencia msg al error estándar.

debug_print(msg)

Si el indicador debug está configurado en la instancia de la clase CCompiler, imprime msg en la salida estándar; de lo contrario, no hace nada.

9.3. distutils.unixccompiler — Unix CCompiler

Este módulo proporciona la clase UnixCCompiler, una subclase de CCompiler que maneja el típico compilador C de línea de comandos estilo Unix:

macros definidas con -Dname[= value]

macros definidas con -Uname

incluye directorios de búsqueda especificados con -Idir

bibliotecas especificadas con -llib

directorios de búsqueda de bibliotecas especificados con -Ldir

compilación manejada por cc (o similar) ejecutable con -c opción: compilar .c a .o

enlaza la biblioteca estática manejada por el comando ar (posiblemente con ranlib)

enlaza la biblioteca compartida manejada por cc -shared

9.4. distutils.msvccompiler — Compilador de Microsoft

Este módulo proporciona MSVCCompiler, una implementación de la clase abstracta CCompiler para Microsoft Visual Studio. Por lo general, los módulos de extensión deben compilarse con el mismo compilador Python que se utilizó para compilar. Para Python 2.3 y versiones anteriores, el compilador fue Visual Studio 6. Para Python 2.4 y 2.5, el compilador es Visual Studio .NET 2003.

MSVCCompiler normalmente elegirá el compilador, enlazador, etc. correcto por sí solo. Para anular esta opción, las variables de entorno DISTUTILS_USE_SDK y MSSdk deben estar configuradas. MSSdk indica que el entorno actual ha sido configurado por el script SetEnv.Cmd del SDK, o que las variables de entorno se habían registrado cuando se instaló el SDK; DISTUTILS_USE_SDK indica que el usuario de distutils ha hecho una elección explícita para anular la selección del compilador por MSVCCompiler.

9.5. distutils.bcppcompiler — Compilador Borland

Este módulo proporciona BorlandCCompiler, una subclase de la clase abstracta CCompiler para el compilador Borland C++.

9.6. distutils.cygwincompiler — Compilador Cygwin

Este módulo proporciona la clase CygwinCCompiler, una subclase de UnixCCompiler que maneja el puerto Cygwin del compilador GNU C a Windows. También contiene la clase Mingw32CCompiler que maneja el puerto mingw32 de GCC (igual que cygwin en modo no-cygwin).

9.7. distutils.archive_util — Utilidades de archivo

Este módulo proporciona algunas funciones para crear archivos de almacenamiento, como tarballs o zipfiles.

distutils.archive_util.make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0])

Crea un archivo de almacenamiento (por ejemplo, zip o tar). base_name es el nombre del archivo a crear, menos cualquier extensión específica del formato; format es el formato de archivo: como zip, tar, gztar, bztar, xztar o ztar. root_dir es un directorio que será el directorio raíz del archivo; es decir, normalmente chdir en root_dir antes de crear el archivo. base_dir es el directorio desde donde comenzamos a archivar; es decir, base_dir será el prefijo común de todos los archivos y directorios del archivo. root_dir y base_dir ambos predeterminados al directorio actual. Retorna el nombre del archivo de almacenamiento.

Distinto en la versión 3.5: Se agregó soporte para el formato xztar.

distutils.archive_util.make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0])

Crea un archivo (opcionalmente comprimido) como un archivo tar de todos los archivos en y bajo base_dir. compress debe ser 'gzip' (el valor predeterminado), 'bzip2', 'xz', 'compress” o None. Para el método 'compress', la utilidad de compresión nombrada por compress debe estar en la ruta de búsqueda del programa predeterminada, por lo que probablemente sea específica de Unix. El archivo tar de salida se llamará base_dir.tar, posiblemente más la extensión de compresión apropiada (.gz,``.bz2``,``.xz`` o .Z). Retorna el nombre del archivo de salida.

Distinto en la versión 3.5: Se agregó soporte para la compresión xz.

distutils.archive_util.make_zipfile(base_name, base_dir[, verbose=0, dry_run=0])

Crea un archivo zip a partir de todos los archivos incluidos en base_dir. El archivo zip de salida se llamará base_name + .zip. Utiliza el módulo Python zipfile (si está disponible) o la utilidad InfoZIP zip (si está instalada y se encuentra en la ruta de búsqueda predeterminada). Si ninguna de las herramientas está disponible, lanza DistutilsExecError. Retorna el nombre del archivo zip de salida.

9.8. distutils.dep_util — Comprobación de dependencias

Este módulo proporciona funciones para realizar una dependencia simple basada en marcas de tiempo de archivos y grupos de archivos; también, funciones basadas completamente en dicho análisis de dependencia de marca de tiempo.

distutils.dep_util.newer(source, target)

Retorna verdadero si source existe y se ha modificado más recientemente que target, o si source existe y target no. Retorna falso si ambos existen y si target tiene el mismo tiempo o es más reciente que source. Lanza DistutilsFileError si source no existe.

distutils.dep_util.newer_pairwise(sources, targets)

Recorre dos listas de nombres de archivos en paralelo, probando si cada fuente es más nueva que su correspondiente destino. Retorna un par de listas (sources, target) donde la fuente es más nueva que el destino, de acuerdo con la semántica de newer().

distutils.dep_util.newer_group(sources, target[, missing='error'])

Retorna verdadero si target no está actualizado con respecto a cualquier archivo listado en sources. En otras palabras, si target existe y es más reciente que todos los archivos en sources, retorna falso; de lo contrario, retorna verdadero. missing controla lo que hacemos cuando falta un archivo fuente; el valor predeterminado ('error') explota con un OSError desde os.stat(); si es 'ignore', eliminamos silenciosamente cualquier archivo fuente faltante; si es 'newer', cualquier archivo fuente que falte nos hace suponer que target está desactualizado (esto es útil en el modo de «dry-run» (o ejecución en seco): que hará que pretenda ejecutar comandos que no funcionaría porque faltan entradas, pero no importa porque en realidad no va a ejecutar los comandos).

9.9. distutils.dir_util — Operaciones del árbol de directorios

Este módulo proporciona funciones para operar en directorios y árboles de directorios.

distutils.dir_util.mkpath(name[, mode=0o777, verbose=0, dry_run=0])

Crea un directorio y cualquier directorio ancestro que falte. Si el directorio ya existe (o si name es el string vacío, significa que el directorio actual, por supuesto existe), no hace nada. Lanza DistutilsFileError si no puede crear algún directorio en el camino (por ejemplo, existe alguna subruta, pero es un archivo en lugar de un directorio). Si verbose es verdadero, imprime un resumen de una línea de cada mkdir en stdout. Retorna la lista de directorios realmente creados.

distutils.dir_util.create_tree(base_dir, files[, mode=0o777, verbose=0, dry_run=0])

Crea todos los directorios vacíos en base_dir necesarios para colocar files allí. base_dir es solo el nombre de un directorio que no existe necesariamente todavía; files es una lista de nombres de archivos que se interpretarán en relación con base_dir. base_dir + la parte del directorio de cada archivo en files se creará si aún no existe. Los indicadores mode, verbose y dry_run son para funciones como mkpath().

distutils.dir_util.copy_tree(src, dst[, preserve_mode=1, preserve_times=1, preserve_symlinks=0, update=0, verbose=0, dry_run=0])

Copia un árbol de directorio completo src en una nueva ubicación dst. Tanto src como dst deben ser nombres de directorio. Si src no es un directorio, lanza DistutilsFileError. Si dst no existe, se crea con mkpath(). El resultado final de la copia es que todos los archivos de src se copian en dst, y los directorios de src se copian de forma recursiva en dst. Retorna la lista de archivos que se copiaron o que podrían haberse copiado, utilizando su nombre de salida. El valor de retorno no se ve afectado por update o dry_run: es simplemente la lista de todos los archivos bajo src *, con los nombres cambiados para estar bajo *dst.

preserve_mode y preserve_times son los mismos que para distutils.file_util.copy_file(); ten en cuenta que solo se aplican a archivos normales, no a directorios. Si preserve_symlinks es verdadero, los enlaces simbólicos se copiarán como enlaces simbólicos (en plataformas que los admitan!); de lo contrario (por defecto), se copiará el destino del enlace simbólico. update y verbose son los mismos que para copy_file().

Los archivos en src que comienzan con .nfs se omiten (hay más sobre estos archivos disponible en la respuesta D2 de la página de preguntas frecuentes de`NFS <http://nfs.sourceforge.net/#section_d>`_ ).

Distinto en la versión 3.3.1: Se ignoran los archivos NFS.

distutils.dir_util.remove_tree(directory[, verbose=0, dry_run=0])

Elimina de forma recursiva directory y todos los archivos y directorios que se encuentran debajo. Cualquier error se ignora (aparte de ser informado a sys.stdout si verbose es verdadero).

9.10. distutils.file_util — Operaciones de un solo archivo

Este módulo contiene algunas funciones de utilidad para operar en archivos individuales.

distutils.file_util.copy_file(src, dst[, preserve_mode=1, preserve_times=1, update=0, link=None, verbose=0, dry_run=0])

Copia el archivo desde src a dst. Si dst es un directorio, entonces src se copia allí con el mismo nombre; de lo contrario, debe ser un nombre de archivo. (Si el archivo existe, será atacado). Si preserve_mode es verdadero (el valor predeterminado), se copia el modo del archivo (bits de tipo y permiso, o lo que sea análogo en la plataforma actual). Si preserve_times es verdadero (el valor predeterminado), también se copian las horas de última modificación y de último acceso. Si update es verdadero, src solo se copiará si dst no existe, o si dst existe pero es anterior a src.

link te permite crear enlaces físicos (usando os.link()) o enlaces simbólicos (usando os.symlink()) en lugar de copiar: configúralo en 'hard' o 'sym'; si es None (el predeterminado), los archivos se copian. No establezcas link en sistemas que no lo admitan: copy_file() pues no comprueba si hay enlaces físicos o simbólicos disponibles. Utiliza _copy_file_contents() para copiar el contenido del archivo.

Retorna una tupla (dest_name, copied): dest_name es el nombre real del archivo de salida, y copied es verdadero si el archivo fue copiado (o se habría copiado, si dry_run es verdadero).

distutils.file_util.move_file(src, dst[, verbose, dry_run])

Mueve el archivo src a dst. Si dst es un directorio, el archivo se moverá a el con el mismo nombre; de lo contrario, src simplemente se renombra a dst. Retorna el nuevo nombre completo del archivo.

Advertencia

Maneja movimientos entre dispositivos en Unix usando copy_file(). ¿Qué pasa con otros sistemas?

distutils.file_util.write_file(filename, contents)

Crea un archivo llamado filename y escribe contents (una secuencia de strings sin terminadores de línea) en el.

9.11. distutils.util — Otras funciones de utilidad varias

Este módulo contiene otras partes y piezas variadas que no encajan en ningún otro módulo de utilidad.

distutils.util.get_platform()

Retorna un string que identifica la plataforma actual. Se utiliza principalmente para distinguir los directorios de compilación específicos de la plataforma y las distribuciones compiladas específicas de la plataforma. Por lo general, incluye el nombre y la versión del sistema operativo y la arquitectura (como lo proporciona “os.uname ()”), aunque incluir la exacta depende del sistema operativo; por ejemplo, en Linux, la versión del kernel no es particularmente importante.

Ejemplos de valores retornados:

linux-i586

linux-alpha

solaris-2.6-sun4u

Para las plataformas que no son POSIX, actualmente solo retorna sys.platform.

For macOS systems the OS version reflects the minimal version on which binaries will run (that is, the value of MACOSX_DEPLOYMENT_TARGET during the build of Python), not the OS version of the current system.

For universal binary builds on macOS the architecture value reflects the universal binary status instead of the architecture of the current processor. For 32-bit universal binaries the architecture is fat, for 64-bit universal binaries the architecture is fat64, and for 4-way universal binaries the architecture is universal. Starting from Python 2.7 and Python 3.2 the architecture fat3 is used for a 3-way universal build (ppc, i386, x86_64) and intel is used for a universal build with the i386 and x86_64 architectures

Examples of returned values on macOS:

macosx-10.3-ppc

macosx-10.3-fat

macosx-10.5-universal

macosx-10.6-intel

Para AIX, Python 3.9 y versiones posteriores retornan una cadena que comienza con «aix», seguida de campos adicionales (separados por '-') que representan los valores combinados de Versión de AIX, Release y Nivel de tecnología (primer campo), Fecha de Construcción (segundo campo) y tamaño de bits (tercer campo). Python 3.8 y anteriores retornaban solo un campo adicional con la versión y lanzamiento de AIX.

Ejemplos de valores retornados en AIX:

aix-5307-0747-32 # construcción 32-bit en AIX oslevel -s: 5300-07-00-0000

aix-7105-1731-64 # construcción 64-bit en AIX oslevel -s: 7100-05-01-1731

aix-7.2 # Forma heredada informada en Python 3.8 y versiones anteriores

Distinto en la versión 3.9: El formato de cadena de caracteres de la plataforma AIX ahora también incluye el nivel de tecnología, la fecha de construcción y el tamaño de bits de ABI.

distutils.util.convert_path(pathname)

Retorna “pathname” (o nombre de ruta), como un nombre que funcionará en el sistema de archivos nativo, es decir, divídelo con “/” y vuelve a armarlo usando el separador de directorio actual. Necesario porque los nombres de archivo en el script de configuración siempre se proporcionan en estilo Unix y deben convertirse a la convención local antes de que podamos usarlos en el sistema de archivos. Lanza ValueError en sistemas que no son Unix-ish si pathname comienza o termina con una barra.

distutils.util.change_root(new_root, pathname)

Retorna pathname con new_root precedido. Si pathname es relativo, esto es equivalente a os.path.join (new_root, pathname). De lo contrario, requiere hacer que pathname sea relativo y luego unir los dos, lo cual es complicado en DOS/Windows.

distutils.util.check_environ()

Asegúrate de que “os.environ” tenga todas las variables de entorno garantizamos que los usuarios pueden usar en archivos de configuración, opciones de línea de comandos, etc. Actualmente, esto incluye:

HOME - directorio de inicio del usuario (solo Unix)

PLAT - descripción de la plataforma actual, incluido el hardware y el sistema operativo (consulta get_platform())

distutils.util.subst_vars(s, local_vars)

Realiza la sustitución de variables de estilo shell/Perl en s. Cada aparición de $ seguido de un nombre se considera una variable, y la variable se sustituye por el valor que se encuentra en el diccionario local_vars, o en os.environ si no está en local_vars. os.environ primero se comprueba/aumenta para garantizar que contiene ciertos valores: ver check_environ(). Lanza ValueError para cualquier variable que no se encuentre en local_vars u os.environ.

Ten en cuenta que esta no es una función de interpolación de string completa. Una $ variable válida que puede constar solo de letras mayúsculas y minúsculas, números y un guión bajo. No hay citas de estilo {} o () disponibles.

distutils.util.split_quoted(s)

Divide un string de acuerdo con las reglas de tipo shell de Unix para comillas y barras invertidas. En resumen: las palabras están delimitadas por espacios, siempre que esos espacios no se escapen con una barra invertida o dentro de un string entre comillas. Las comillas simples y dobles son equivalentes, y los caracteres de las comillas pueden tener un escape de barra invertida. La barra invertida se elimina de cualquier secuencia de escape de dos caracteres, dejando solo el carácter de escape. Los caracteres de comillas se eliminan de cualquier string entre comillas. Retorna una lista de palabras.

distutils.util.execute(func, args[, msg=None, verbose=0, dry_run=0])

Realiza alguna acción que afecta al mundo exterior (por ejemplo, escribir en el sistema de archivos). Tales acciones son especiales porque están deshabilitadas por el indicador dry_run. Este método se encarga de toda esa burocracia por ti; todo lo que tienes que hacer es proporcionar la función a llamar y una tupla de argumentos para esta (para incorporar la «acción externa» que se está realizando), y un mensaje opcional para imprimir.

distutils.util.strtobool(val)

Convierte una representación real de un string a verdadero (1) o falso (0).

Los valores verdaderos son y, yes, t, true, on y 1; los valores falsos son n, no, f, false, off and 0. Lanza ValueError si val es cualquier otra cosa.

distutils.util.byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None])

Byte-compile es una colección de archivos fuente de Python de .pyc en un subdirectorio __pycache__ (ver PEP 3147 [https://www.python.org/dev/peps/pep-3147] y PEP 488 [https://www.python.org/dev/peps/pep-0488]). py_files es una lista de archivos para compilar; cualquier archivo que no termine en .py se omite silenciosamente. optimize debe ser uno de los siguientes:

0 - no optimizar

1 - optimización normal (como python -O)

2 - extra optimización (como python -OO)

Si force es verdadero, todos los archivos se vuelven a compilar independientemente de las marcas de tiempo.

El nombre del archivo de origen codificado en cada archivo bytecode tiene por defecto los nombres de archivo listados en py_files; puede modificarlos con prefix y basedir. prefix es un string que se eliminará de cada nombre de archivo de origen, y base_dir es un nombre de directorio que se antepondrá (después de eliminar prefix). Puedes proporcionar uno o ambos (o ninguno) de prefix y * base_dir*, como desees.

Si dry_run es verdadero, actualmente no hace nada que pueda afectar el sistema de archivos.

La compilación de bytes se realiza directamente en este proceso de interpretación con el módulo estándar py_compile, o indirectamente escribiendo un script temporal y ejecutándolo. Normalmente, debería dejar que byte_compile() se dé cuenta de si usar la compilación directa o no (consulta la fuente para obtener más detalles). El indicador direct es utilizado por el script generado en modo indirecto; a menos que sepa lo que está haciendo, se deja configurado en None.

Distinto en la versión 3.2.3: Crea archivos .pyc con una etiqueta mágica import en su nombre, en un subdirectorio __pycache__ en lugar de archivos sin etiqueta en el directorio actual.

Distinto en la versión 3.5: Crea archivos .pyc de acuerdo a PEP 488 [https://www.python.org/dev/peps/pep-0488].

distutils.util.rfc822_escape(header)

Retorna una versión de header para su inclusión en un encabezado RFC 822 [https://tools.ietf.org/html/rfc822.html], asegurándose de que haya 8 espacios después de cada nueva línea. Ten en cuenta que no hace ninguna otra modificación del string.

9.12. distutils.dist — La clase Distribution

Este módulo proporciona la clase Distribution, que representa la distribución del módulo que se está construyendo/instalando/distribuyendo.

9.13. distutils.extension — La clase Extension

Este módulo proporciona la clase Extension, que se utiliza para describir los módulos de extensión C/C ++ en los scripts de configuración.

9.14. distutils.debug — modo de depuración Distutils

Este módulo proporciona el indicador DEBUG.

9.15. distutils.errors — excepciones Distutils

Proporciona excepciones utilizadas por los módulos Distutils. Ten en cuenta que los módulos de Distutils pueden lanzar excepciones estándar; en particular, SystemExit generalmente se lanza por errores que obviamente son culpa del usuario final (por ejemplo, argumentos incorrectos en la línea de comandos).

Este módulo es seguro de usar en el modo from ... import*; solo exporta símbolos cuyos nombres comienzan con Distutils y terminan con Error.

9.16. distutils.fancy_getopt — Wrapper alrededor del módulo estándar getopt

Este módulo proporciona una envoltura alrededor del modulo estándar getopt que proporciona las siguientes características adicionales:

las opciones cortas y largas están unidas

las opciones tienen strings de ayuda, por lo que fancy_getopt() podría potencialmente crear un resumen de uso completo

las opciones establecen atributos de un objeto pasado

las opciones booleanas pueden tener «alias negativos» — p. ej. si -quiet es el «alias negativo» de -verbose, entonces: option:!-quiet en la línea de comando establece falso a verbose.

distutils.fancy_getopt.fancy_getopt(options, negative_opt, object, args)

Función Wrapper. options es una lista de (*long_option*, *short_option*, *help_string*) 3-tuplas como se describe en el constructor para FancyGetopt. negative_opt debe ser un diccionario de mapeo de nombres de opciones a nombres de opciones, tanto la clave como el valor deben estar en la lista de options. object es un objeto que se usará para almacenar valores (ver el método getopt() de la clase FancyGetopt). args es la lista de argumentos. Usará sys.argv [1:] si pasa None como args.

distutils.fancy_getopt.wrap_text(text, width)

Envuelve text a menos de width ancho.

class distutils.fancy_getopt.FancyGetopt([option_table=None])

La opción option_table es una lista de 3 tuplas: (long_option, short_option, help_string)

Si una opción toma un argumento, su long_option debería tener `` “=” `` anexado; short_option debe ser solo un carácter, sin `` “:” `` en cualquier caso. short_option debe ser None si long_option no tiene una short_option correspondiente. Todas las tuplas de opciones deben tener opciones largas.

La clase FancyGetopt proporciona los siguientes métodos:

FancyGetopt.getopt([args=None, object=None])

Analiza las opciones de la línea de comandos en args. Almacena como atributos en object.

Si args es None o no se proporciona, utiliza sys.argv [1:]. Si object es None o no se proporciona, crea una nueva instancia OptionDummy, que allí almacena valores de opción y retorna una tupla (args, object). Si se proporciona object, se modifica en su lugar y getopt() simplemente retorna args; en ambos casos, el args retornado es una copia modificada de la lista args pasada, que se deja intacta.

FancyGetopt.get_option_order()

Retorna la lista de tuplas (*option*, *value*) procesadas por la ejecución anterior de getopt() Lanza RuntimeError si getopt() aún no se ha llamado.

FancyGetopt.generate_help([header=None])

Genera un texto de ayuda (una lista de strings, una por cada línea de salida sugerida) de la tabla de opciones para este objeto FancyGetopt.

Si se suministra, imprime el header suministrado en la parte superior de la ayuda.

9.17. distutils.filelist — La clase FileList

Este módulo proporciona la clase FileList, utilizada para hurgar en el sistema de archivos y crear listas de archivos.

9.18. distutils.log — Simple PEP 282 [https://www.python.org/dev/peps/pep-0282]-registro de estilo

9.19. distutils.spawn — Genera un subproceso

Este módulo proporciona la función spawn(), un front-end para varias funciones específicas de la plataforma para iniciar otro programa en un subproceso. También proporciona find_executable() para buscar en la ruta un nombre ejecutable determinado.

9.20. distutils.sysconfig — Información de configuración del sistema

El modulo distutils.sysconfig proporciona acceso a la configuración de bajo nivel de Python. Las variables de configuración específicas disponibles dependen en gran medida de la plataforma y la configuración. Las variables específicas dependen del proceso de compilación de la versión específica de Python que se está ejecutando; las variables son las que se encuentran en el archivo Makefile y el encabezado de configuración que se instalan con Python en sistemas Unix. El encabezado de configuración se llama pyconfig.h para las versiones de Python que comienzan con 2.2, y config.h para versiones anteriores de Python.

Se proporcionan algunas funciones adicionales que realizan algunas manipulaciones útiles para otras partes del paquete distutils.

distutils.sysconfig.PREFIX

El resultado de os.path.normpath(sys.prefix).

distutils.sysconfig.EXEC_PREFIX

El resultado de os.path.normpath(sys.exec_prefix).

distutils.sysconfig.get_config_var(name)

Retorna el valor de una sola variable. Esto es equivalente a get_config_vars ().get(name).

distutils.sysconfig.get_config_vars(...)

Retorna un conjunto de definiciones de variables. Si no hay argumentos, esto retorna un diccionario que asigna los nombres de las variables de configuración a los valores. Si se proporcionan argumentos, deben ser strings y el valor de retorno será una secuencia que proporcione los valores asociados. Si un nombre de pila no tiene un valor correspondiente, se incluirá None para esa variable.

distutils.sysconfig.get_config_h_filename()

Retorna el nombre completo de la ruta del encabezado de configuración. Para Unix, este será el encabezado generado por el script configure; para otras plataformas, el encabezado habrá sido proporcionado directamente por la distribución fuente de Python. El archivo es un archivo de texto específico de la plataforma.

distutils.sysconfig.get_makefile_filename()

Retorna el nombre completo de la ruta del archivo Makefile usado para construir Python. Para Unix, este será un archivo generado por el script configure; el significado para otras plataformas variará. El archivo es un archivo de texto específico de la plataforma, si existe. Esta función solo es útil en plataformas POSIX.

distutils.sysconfig.get_python_inc([plat_specific[, prefix]])

Retorna el directorio para los archivos de inclusión de C generales o dependientes de la plataforma. Si plat_specific es verdadero, se retorna el directorio de inclusión dependiente de la plataforma; si es falso o se omite, se retorna el directorio independiente de la plataforma. Si se proporciona prefix, se usa como prefijo en lugar de PREFIX, o como exec-prefix en lugar de EXEC_PREFIX si plat_specific es verdadero.

distutils.sysconfig.get_python_lib([plat_specific[, standard_lib[, prefix]]])

Retorna el directorio para la instalación de la biblioteca general o dependiente de la plataforma. Si plat_specific es verdadero, se retorna el directorio de inclusión dependiente de la plataforma; si es falso o se omite, se retorna el directorio independiente de la plataforma. Si se proporciona prefix, se usa como prefijo en lugar de PREFIX, o como exec-prefix en lugar de EXEC_PREFIX si plat_specific es verdadero. Si standard_lib es verdadero, se retorna el directorio de la biblioteca estándar en lugar del directorio para la instalación de extensiones de terceros.

La siguiente función solo está pensada para su uso dentro del paquete distutils.

distutils.sysconfig.customize_compiler(compiler)

Realiza cualquier personalización específica de la plataforma de una instancia distutils.ccompiler.CCompiler.

Esta función solo es necesaria en Unix en este momento, pero se debe llamar de manera consistente para admitir la compatibilidad con versiones posteriores. Inserta la información que varía según los tipos de Unix y se almacena en el archivo de Python Makefile. Esta incluye el compilador seleccionado, las opciones del compilador y del enlazador, y la extensión utilizada por el enlazador para los objetos compartidos.

Esta función tiene un propósito aún más especial y solo debe usarse desde los propios procedimientos de compilación de Python.

distutils.sysconfig.set_python_build()

Informa al módulo distutils.sysconfig que se está utilizando como parte del proceso de compilación de Python. Esto cambia muchas ubicaciones relativas de los archivos, lo que les permite ubicarse en el área de compilación en lugar de en un Python instalado.

9.21. distutils.text_file — La clase TextFile

Este módulo proporciona la clase TextFile, que proporciona una interfaz a los archivos de texto que (opcionalmente) se encarga de eliminar los comentarios, ignorar las líneas en blanco y unir líneas con barras invertidas.

class distutils.text_file.TextFile([filename=None, file=None, **options])

Esta clase proporciona un objeto similar a un archivo que se encarga de todas las cosas que comúnmente desea hacer al procesar un archivo de texto que tiene alguna sintaxis línea por línea: elimina comentarios (siempre que # sea su carácter de comentario), omite líneas en blanco, une líneas adyacentes escapando de la nueva línea (es decir, barra invertida al final de la línea), elimina los espacios en blanco iniciales o finales. Todos estos son opcionales y controlables de forma independiente.

La clase proporciona un método warn() para que pueda generar mensajes de advertencia que informen el número de línea física, incluso si la línea lógica en cuestión abarca varias líneas físicas. También proporciona unreadline() para implementar una búsqueda anticipada de línea a la vez.

Las instancias de TextFile se crean con filename, file o ambos. RuntimeError se lanza si ambos son None. filename debe ser un string, y file un archive de objeto (o algo que proporcione los métodos readline() y close()). Se recomienda que proporcione al menos filename, para que TextFile pueda incluirlo en mensajes de advertencia. Si no se proporciona file, TextFile crea uno propio usando la función incorporada open().

Todas las opciones son booleanas y afectan los valores retornados por readline()

nombre de la opción

descripción

predeterminado

strip_comments

elimina desde '#' hasta el final de la línea, así como cualquier espacio en blanco que conduzca al '#' — a menos que se escape por una barra invertida

verdadero

lstrip_ws

elimina los espacios en blanco iniciales de cada línea antes de retornarlo

falso

rstrip_ws

elimina los espacios en blanco finales (incluido el terminador de línea!) de cada línea antes de retornarlo.

verdadero

skip_blanks

omite las líneas que están vacías * después de* elimina los comentarios y los espacios en blanco. (Si tanto lstrip_ws como rstrip_ws son falsos, algunas líneas pueden consistir únicamente en espacios en blanco: estos no se omitirán, incluso si skip_blanks es verdadero).

verdadero

join_lines

si una barra invertida es el último carácter que no es una nueva línea en una línea después de eliminar los comentarios y los espacios en blanco, únela a la siguiente línea para formar una línea lógica; si N líneas consecutivas terminan con una barra invertida, entonces N + 1 líneas físicas se unirán para formar una línea lógica.

falso

collapse_join

elimina los espacios en blanco iniciales de las líneas que están unidas a su predecesor; solo importa si (*join_lines* y no *lstrip_ws*)

falso

Ten en cuenta que, dado que rstrip_ws puede eliminar la nueva línea final, la semántica de readline() debe diferir de las del método readline() del objeto de archivo integrado. En particular, readline() retorna None para el final del archivo: un string vacío puede ser solo una línea en blanco (o una línea con espacios en blanco), si rstrip_ws es verdadero pero skip_blanks no es.

open(filename)

Abre un nuevo archivo filename. Esto anula cualquier file o filename argumentado del constructor.

close()

Cierra el archivo actual y olvida todo lo que sabemos sobre él (incluido el nombre del archivo y el número de línea actual).

warn(msg[, line=None])

Imprime (a stderr) un mensaje de advertencia vinculado a la línea lógica actual en el archivo actual. Si la línea lógica actual en el archivo abarca varias líneas físicas, la advertencia se refiere a todo el rango, como "lines 3-5". Si se proporciona line, anula el número de línea actual; puede ser una lista o tupla para indicar un rango de líneas físicas, o un número entero para una sola línea física.

readline()

Lee y retorna una sola línea lógica del archivo actual (o de un búfer interno si las líneas han sido «no leídas» previamente con unreadline()). Si la opción join_lines es verdadera, esto puede implicar la lectura de varias líneas físicas concatenadas en una sola cadena. Actualiza el número de línea actual, por lo que llamar a warn() después readline() emite una advertencia sobre las líneas físicas que acaba de leer. Retorna None al final del archivo, ya que un string vacío puede aparecer si rstrip_ws es verdadero pero strip_blanks no lo es.

readlines()

Lee y retorna la lista de todas las líneas lógicas restantes en el archivo actual. Esto actualiza el número de línea actual a la última línea del archivo.

unreadline(line)

Empuja line (un string) en un búfer interno que será verificado por futuras llamadas a readline(). Útil para implementar un analizador con búsqueda anticipada de línea a la vez. Tenga en cuenta que las líneas que están «no leídas» con unreadline() no se vuelven a limpiar posteriormente (se eliminan los espacios en blanco o lo que sea) cuando se leen con readline(). Si se realizan varias llamadas a unreadline() antes de una llamada a readline(), la mayoría de las líneas se retornarán en el primer orden más reciente.

9.22. distutils.version — Clases de número de versión

9.23. distutils.cmd — Clase base abstracta para comandos Distutils

Este módulo proporciona la clase base abstracta Command.

class distutils.cmd.Command(dist)

La clase base abstracta para definir clases de comando, las «worker bees» de Distutils. Una analogía útil para las clases de comando es pensar en ellas como subrutinas con variables locales llamadas options. Las opciones se declaran en initialize_options() y se definen (dados sus valores finales) en finalize_options(), los cuales deben ser definidos por cada clase de comando. La distinción entre los dos es necesaria porque los valores de las opciones pueden provenir del mundo exterior (línea de comando, archivo de configuración, …), y cualquier opción que dependa de otras opciones debe calcularse después de que se hayan procesado estas influencias externas — por lo tanto finalize_options(). El cuerpo de la subrutina, donde hace todo su trabajo basado en los valores de sus opciones, es el método run(), que también debe ser implementado por cada clase de comando.

El constructor de la clase toma un solo argumento dist, una instancia Distribution.

9.24. Creando un nuevo comando Distutils

Esta sección describe los pasos para crear un nuevo comando Distutils.

Un nuevo comando reside en un módulo en el paquete distutils.command. Hay una plantilla de muestra en ese directorio llamada command_template. Copia este archivo en un nuevo módulo con el mismo nombre que el nuevo comando que está implementando. Este módulo debe implementar una clase con el mismo nombre que el módulo (y el comando). Entonces, por ejemplo, para crear el comando peel_banana (para que los usuarios puedan ejecutar setup.py peel_banana), deben copiar command_template a distutils/command/peel_banana.py, luego edítelo para que implemente la clase peel_banana, una subclase de distutils.cmd.Command.

Las subclases de Command deben definir los siguientes métodos.

Command.initialize_options()

Establece valores predeterminados para todas las opciones que admite este comando. Ten en cuenta que estos valores predeterminados pueden ser anulados por otros comandos, por el script de configuración, por los archivos de configuración o por la línea de comandos. Por tanto, este no es el lugar para codificar dependencias entre opciones; generalmente, las implementaciones de initialize_options() son solo un montón de asignaciones self.fo = None .

Command.finalize_options()

Establece valores finales para todas las opciones que admite este comando. Esto siempre se llama lo más tarde posible, es decir. después de que se hayan realizado las asignaciones de opciones desde la línea de comandos o desde otros comandos. Por lo tanto, este es el lugar para codificar las dependencias de opciones: si foo depende de bar, entonces es seguro establecer foo desde bar siempre que foo todavía tenga el mismo valor que se asignó en initialize_options().

Command.run()

La razón de ser de un comando: llevar a cabo la acción que debe realizar, controlada por las opciones inicializadas en initialize_options(), personalizadas por otros comandos, el script de configuración, la línea de comandos y los archivos de configuración, y finalizadas en finalize_options(). Toda la salida de la terminal y la interacción del sistema de archivos debe realizarse mediante run().

Command.sub_commands

sub_commands formaliza la noción de una «familia» de comandos, p. ej. install como padre con subcomandos install_lib, install_headers, etc. El padre de una familia de comandos define sub_commands como un atributo de clase; es una lista de 2 tuplas (command_name, predicate), con command_name un string y predicate una función, un string o None. predicate es un método del comando padre que determina si el comando correspondiente es aplicable en la situación actual. (Por ejemplo, install_headers solo es aplicable si tenemos archivos de encabezado C para instalar). Si predicate es None, ese comando siempre es aplicable.

sub_commands generalmente se define al end de una clase, porque los predicados pueden ser métodos de la clase, por lo que ya deben haber sido definidos. El ejemplo canónico es el comando install.

9.25. distutils.command — Comandos individuales de Distutils

9.26. distutils.command.bdist — Construye un instalador binario

9.27. distutils.command.bdist_packager — Clase base abstracta para empaquetadores

9.28. distutils.command.bdist_dumb — Construye un instalador «dump»

9.29. distutils.command.bdist_msi — Construye un paquete binario instalador de Microsoft

class distutils.command.bdist_msi.bdist_msi

Obsoleto desde la versión 3.9: Utiliza bdist_wheel (paquetes wheel) en su lugar.

Construye un paquete binario Windows Installer [https://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx] (.msi)

En la mayoría de los casos, el instalador bdist_msi es una mejor opción que el instalador bdist_wininst, porque proporciona un mejor soporte para plataformas Win64, permite a los administradores realizar instalaciones no interactivas y permite la instalación a través de políticas de grupo.

9.30. distutils.command.bdist_rpm — Construye una distribución binaria como RedHat RPM y SRPM

9.31. distutils.command.bdist_wininst — Construye un instalador de Windows

Obsoleto desde la versión 3.8: Utiliza bdist_wheel (paquetes wheel) en su lugar.

9.32. distutils.command.sdist — Construye una distribución de código fuente

9.33. distutils.command.build — Construye todos los archivos de un paquete

9.34. distutils.command.build_clib — Construye cualquier biblioteca C en un paquete

9.35. distutils.command.build_ext — Construye cualquier extensión en un paquete

9.36. distutils.command.build_py — Construye los archivos .py/.pyc de un paquete

class distutils.command.build_py.build_py

class distutils.command.build_py.build_py_2to3

Implementación alternativa de build_py que también ejecuta la biblioteca de conversión 2to3 en cada archivo .py que se va a instalar. Para usar esto en un archivo setup.py de una distribución que está diseñada para ejecutarse con Python 2.x y 3.x, agrega:

try:
    from distutils.command.build_py import build_py_2to3 as build_py
except ImportError:
    from distutils.command.build_py import build_py

a su setup.py, y posteriormente:

cmdclass = {'build_py': build_py}

a la invocación de configuración setup().

9.37. distutils.command.build_scripts — Construye los scripts de un paquete

9.38. distutils.command.clean — Limpia el área de construcción de un paquete

Este comando elimina los archivos temporales creados por el comando build y sus subcomandos, como archivos de objeto compilados intermediarios. Con la opción --all, se eliminará el directorio de compilación completo.

Los módulos de extensión construidos in place no se limpiarán, ya que no están en el directorio de construcción.

9.39. distutils.command.config — Realiza la configuración de un paquete

9.40. distutils.command.install — Instala un paquete

9.41. distutils.command.install_data — Instala archivos de datos de un paquete

9.42. distutils.command.install_headers — Instala archivos de encabezado C/C++ desde un paquete

9.43. distutils.command.install_lib — Instala archivos de biblioteca desde un paquete

9.44. distutils.command.install_scripts — Instala archivos de script desde un paquete

9.45. distutils.command.register — Registra un módulo con el índice de paquetes de Python

El comando register registra el paquete con el índice de paquetes de Python. Esto se describe con más detalle en PEP 301 [https://www.python.org/dev/peps/pep-0301].

9.46. distutils.command.check — Verificar los metadatos de un paquete

El comando check realiza algunas pruebas en los metadatos de un paquete. Por ejemplo, verifica que todos los metadatos requeridos se proporcionen como argumentos pasados ​​a la función setup().

Instalación de Módulos de Python (versión antigua)

Autor

Greg Ward

Ver también

Instalando módulos de Python

La documentación actualizada de instalación de módulos. Para el uso regular de Python, es casi seguro que desee ese documento en lugar de este.

Nota

This document is being retained solely until the setuptools documentation at https://setuptools.readthedocs.io/en/latest/setuptools.html independently covers all of the relevant information currently included here.

Nota

Esta guía solamente cubre las herramientas básicas para construir y distribuir extensiones que se proporcionan como parte de esta versión de Python. Herramientas de terceros ofrecen alternativas más sencillas y seguras . Consulte la sección de recomendaciones [https://packaging.python.org/guides/tool-recommendations/] en la Guía de Usuario de Empaquetamiento de Python para mayor detalle.

Introducción

En Python 2.0, la API distutils fue el primer módulo en ser agregado a la biblioteca estándar. Esto proporcionó a los mantenedores de distribución de Linux una forma estándar de convertir proyectos de Python en paquetes de distribución de Linux, y a los administradores de sistemas con una forma estándar de instalarlos directamente en los sistemas de destino.

En los muchos años transcurridos desde el lanzamiento de Python 2.0, el acoplamiento estrecho del sistema de compilación y el instalador del paquete al ciclo de lanzamiento del lenguaje ha sido un problema, ahora se recomienda que los proyectos utilicen el instalador del paquete pip y el sistema de compilación setuptools, en lugar de utilizar directamente distutils.

Ver Instalando módulos de Python y Distribuir módulos de Python para mayor detalles.

Esta documentación heredada se conservará hasta que se esté seguro que la documentación de setuptools cubre todo lo necesario.

Distutils basado la distribuciones de la fuente

Si tu descargas un módulo, puede ser mucho más rápido si el módulo fue empaquetado y distribuido de una manera estándar, por ejemplo usando Distutils. Primero, el nombre y la versión de la distribución aparecerá en el nombre del archivo a descargar, por ejemplo: foo-1.0.tar.gz or widget-0.9.7.zip. A continuación, el archivo se descomprimirá en un directorio con un nombre similar: foo-1.0 or widget-0.9.7. Además, la distribución contendrá un script de configuración setup.py, y un archivo llamado README.txt o simplemente llamado README, que debería explicar cómo construir e instalar la distribución del módulo con una serie de comandos de terminal:

python setup.py install

Para Windows, este comando debería ejecutarse desde la linea de comandos.(Start ‣ Accessories):

setup.py install

Si todo es correcto, entonces ya sabe cómo construir e instalar los módulos que acaba de descargar: ejecute el comando anterior. Al menos que se necesite instalar cosas de una manera no estándar o personalizar el proceso de compilación, no necesitará hacer esto de manera manual. Más bien, el comando anterior es todo lo que necesita obtener de este manual.

Construcción e instalación estándar

Como se describe en la sección Distutils basado la distribuciones de la fuente, construir e instalar una distribución de módulos usando Distutils suele ser un comando simple para ejecutar desde un terminal:

python setup.py install

Variaciones de acuerdo a la plataforma

Siempre debe ejecutar el comando de configuración desde el directorio raíz de distribución, por ejemplo el subdirectorio de nivel superior en el que se descomprime la distribución fuente del módulo. Por ejemplo, si acaba de descargar una distribución fuente del módulo foo-1.0.tar.gz en un sistema Unix, lo normal es:

gunzip -c foo-1.0.tar.gz | tar xf -    # unpacks into directory foo-1.0
cd foo-1.0
python setup.py install

En Windows, probablemente se descargaría foo-1.0.zip. Si descargó el archivo en C:Temp, se descomprimirá en C:Tempfoo-1.0; puede usar un manipulador de archivo con una interfaz gráfica de usuario (como WinZip) o una herramienta de línea de comandos (como unzip o pkunzip) para descomprimir el archivo. Luego, abra una ventana de símbolo del sistema y ejecute:

cd c:\Temp\foo-1.0
python setup.py install

Dividiendo el trabajo

La ejecución de setup.py install compila e instala todos los módulos en una sola ejecución. Si prefiere trabajar de forma incremental, especialmente útil si desea personalizar el proceso de compilación, o si las cosas van mal, puede usar el script de configuración para hacer una cosa a la vez. Esto es particularmente útil cuando la compilación y la instalación serán realizadas por diferentes usuarios, por ejemplo, es posible que desee compilar una distribución de módulos y entregarla a un administrador del sistema para su instalación (o hágalo usted mismo, con privilegios de superusuario )

Por ejemplo, puede compilar todo en un solo paso y luego instalarlo en un segundo paso, invocando el script de configuración dos veces:

python setup.py build
python setup.py install

Si hace esto, notará que al ejecutar el comando install primero ejecuta el comando build, que — en este caso — rápidamente se da cuenta de que no tiene nada que hacer, ya que todo en la carpeta build está actualizado.

Es posible que no necesite esta capacidad de desglosar las cosas si todo lo que hace es instalar módulos descargados de la red, pero es muy útil para tareas más avanzadas. Si llega a distribuir sus propios módulos y extensiones de Python, ejecutará muchos comandos Distutils individuales por su cuenta.

Como funciona la construcción

Como se indicó anteriormente, el comando build es responsable de colocar los archivos para instalar en un directorio de compilación. Por defecto, esto es build bajo la raíz de distribución; si está demasiado preocupado por la velocidad, o si desea mantener el árbol de origen prístino, puede cambiar el directorio de compilación con la opción --build-base. Por ejemplo:

python setup.py build --build-base=/path/to/pybuild/foo-1.0

(O puede hacer esto permanentemente con una directiva en su sistema o archivo de configuración personal de Distutils; ver la sección Archivos de Configuración de Distutils.) Normalmente, esto no es necesario.

El diseño predeterminado para el árbol de compilación es el siguiente:

--- build/ --- lib/
or
--- build/ --- lib.<plat>/
               temp.<plat>/

donde <plat> se expande a una breve descripción de la plataforma actual de SO/hardware y la versión de Python. La primera forma, con solo un directorio lib, se usa para «distribuciones de módulos puros»— es decir, distribuciones de módulos que incluyen solo módulos puros de Python. Si la distribución de un módulo contiene alguna extensión (módulos escritos en C/C ++), se utiliza la segunda forma, con dos directorios <plat>. En ese caso, el directorio temp.plat contiene archivos temporales generados por el proceso de compilación/enlace que en realidad no se instalan. En cualquier caso, el directorio lib (o lib.plat) contiene todos los módulos de Python (Python puro y extensiones) que se instalarán.

En el futuro, se agregarán más directorios para manejar scripts de Python, documentación, ejecutables binarios y todo lo que sea necesario para manejar el trabajo de instalación de módulos y aplicaciones de Python.

Como funciona la instalación

Después de que se ejecute el comando build (ya sea que lo ejecute explícitamente, o el comando install lo hace por usted), el trabajo del comando install es relativamente simple: todo lo que tiene hacer es copiar todo lo que se encuentra en el directorio build/lib (o build/lib.plat) en el directorio de instalación elegido.

If you don’t choose an installation directory—i.e., if you just run setup.py install—then the install command installs to the standard location for third-party Python modules. This location varies by platform and by how you built/installed Python itself. On Unix (and macOS, which is also Unix-based), it also depends on whether the module distribution being installed is pure Python or contains extensions («non-pure»):

Plataforma

Lugar de instalación estándar

Valor por defecto

Notas

Unix (puro)

prefix/lib/pythonX.Y/site-packages

/usr/local/lib/pythonX.Y/site-packages

(1)

Unix (no puro)

exec-prefix/lib/pythonX.Y/site-packages

/usr/local/lib/pythonX.Y/site-packages

(1)

Windows

prefix\Lib\site-packages

C:\PythonXY\Lib\site-packages

(2)

Notas:

La mayoría de las distribuciones de Linux incluyen Python como una parte estándar del sistema, por lo que prefix y exec-prefix generalmente son ambos: file: /usr en Linux. Si construye Python usted mismo en Linux (o en cualquier sistema similar a Unix), el valor predeterminado prefix y exec-prefix son /usr /local.

El directorio de instalación predeterminado en Windows era C:\ Archivos de programa \Python en Python 1.6a1, 1.5.2 y versiones anteriores.

prefix and exec-prefix stand for the directories that Python is installed to, and where it finds its libraries at run-time. They are always the same under Windows, and very often the same under Unix and macOS. You can find out what your Python installation uses for prefix and exec-prefix by running Python in interactive mode and typing a few simple commands. Under Unix, just type python at the shell prompt. Under Windows, choose Start ‣ Programs ‣ Python X.Y ‣ Python (command line). Once the interpreter is started, you type Python code at the prompt. For example, on my Linux system, I type the three Python statements shown below, and get the output as shown, to find out my prefix and exec-prefix:

Python 2.4 (#26, Aug  7 2004, 17:19:02)
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys.prefix
'/usr'
>>> sys.exec_prefix
'/usr'

En este documento se utilizan algunos otros marcadores de posición: X.Y representa la versión de Python, por ejemplo, 3.2; abiflags será reemplazado por el valor de sys.abiflags o la cadena vacía para plataformas que no definen flags ABI; distname será reemplazado por el nombre de la distribución del módulo que se está instalando. Los puntos y las mayúsculas son importantes en los las direcciones; por ejemplo, un valor que usa python3.2 en UNIX generalmente usará Python32 en Windows.

Si no desea instalar módulos en la ubicación estándar, o si no tiene permiso para escribir allí, debe leer acerca de las instalaciones alternativas en la sección Instalación alternativa. Si desea personalizar más sus directorios de instalación, consulte la sección Instalación personalizada en instalaciones personalizadas.

Instalación alternativa

A menudo, es necesario o deseable instalar módulos en una ubicación distinta de la ubicación estándar para módulos Python de terceros. Por ejemplo, en un sistema Unix, es posible que no tenga permiso para escribir en el directorio estándar de módulos de terceros. O quizás desee probar un módulo antes de convertirlo en una parte estándar de su instalación local de Python. Esto es especialmente cierto cuando se actualiza una distribución ya presente: desea asegurarse de que su base de scripts existente todavía funcione con la nueva versión antes de actualizar realmente.

El comando Distutils install está diseñado para hacer que la instalación de distribuciones de módulos en una ubicación alternativa sea simple e indolora. La idea básica es que proporcione un directorio base para la instalación, y el comando install selecciona un conjunto de directorios (llamado esquema de instalación) en este directorio base en el que instalar los archivos. Los detalles difieren entre plataformas, por lo tanto, lea la sección que corresponda a usted.

Tenga en cuenta que los diversos esquemas de instalación alternativos son mutuamente excluyentes: se le puede pasar --user, o --home, o --prefix y --exec-prefix, o --install-base y --install-platbase, pero no puede mezclar desde estos grupos.

Instalación alternativa: el esquema de usuario

This scheme is designed to be the most convenient solution for users that don’t have write permission to the global site-packages directory or don’t want to install into it. It is enabled with a simple option:

python setup.py install --user

Files will be installed into subdirectories of site.USER_BASE (written as userbase hereafter). This scheme installs pure Python modules and extension modules in the same location (also known as site.USER_SITE). Here are the values for UNIX, including macOS:

Tipo de archivo

Directorio de instalación

módulos

userbase/lib/pythonX.Y/site-packages

scripts

userbase/bin

dato

userbase

Cabeceras C

userbase/include/pythonX.Yabiflags/distname

Y aquí están los valores usados en Windows:

Tipo de archivo

Directorio de instalación

módulos

userbase\PythonXY\site-packages

scripts

userbase\PythonXY\Scripts

dato

userbase

Cabeceras C

userbase\PythonXY\Include{distname}

La ventaja de usar este esquema en comparación con los otros descritos a continuación es que el directorio de paquetes de sitio del usuario está en condiciones normales siempre incluido en sys.path (ver site para más información), que significa que no hay que realizar ningún paso adicional después de ejecutar el script setup.py para finalizar la instalación.

El comando build_ext también tiene una opción --user para agregar userbase/include a la ruta de búsqueda del compilador para archivos de encabezado y userbase/lib a la ruta de búsqueda del compilador para bibliotecas, así como a la ruta de búsqueda de tiempo de ejecución para bibliotecas C compartidas (rpath).

Instalación alternativa: el esquema de la casa

La idea detrás del «esquema de inicio» es crear y mantener una reserva personal de módulos Python. El nombre de este esquema se deriva de la idea de un directorio «de inicio» en Unix, ya que no es inusual que un usuario de Unix haga que su directorio de inicio tenga un diseño similar a /usr/ o /usr/local/. Cualquiera puede utilizar este esquema, independientemente del sistema operativo para el que se esté instalando.

Instalar un nuevo módulo de distribución es tan simple como:

python setup.py install --home=<dir>

dónde se puede suministrar cualquier directorio que desee para la opción -inicio. En Unix, los mecanógrafos perezosos pueden simplemente escribir una tilde (~); el comando install expandirá esto a su directorio de inicio:

python setup.py install --home=~

Para hacer que Python encuentre las distribuciones instaladas con este esquema, puede que tenga que modificar la ruta de búsqueda de Python o editar sitecustomize (ver site) para llamar site.addsitedir() o edit sys.path.

La opción -inicio define el directorio base de instalación. Los archivos se instalan en los siguientes directorios bajo la base de instalación de la siguiente manera:

Tipo de archivo

Directorio de instalación

módulos

home/lib/python

scripts

home/bin

dato

home

Cabeceras C

home/include/python/distname

(Reemplace mentalmente las barras diagonales con barras diagonales inversas si está en Windows.)

Instalación alternativa: Unix (el esquema de prefijo)

El «esquema de prefijo» es útil cuando desea utilizar una instalación de Python para realizar la compilación / instalación (por ejemplo, para ejecutar el script de configuración), pero instalar módulos en el directorio de módulos de terceros de una instalación de Python diferente (o algo que parece una instalación diferente de Python). Si esto suena un poco inusual, es — es por eso que el usuario y los esquemas de inicio vienen antes. Sin embargo, hay al menos dos casos conocidos en los que el esquema de prefijo será útil.

Primero, considere que muchas distribuciones de Linux ponen Python en /usr, en lugar del tradicional /usr/local. Esto es completamente apropiado, ya que en esos casos Python es parte del «sistema» en lugar de un complemento local. Sin embargo, si está instalando módulos de Python desde la fuente, probablemente desee que entren en /usr/local/lib/python2.X en lugar de /usr/lib/python2.X. Esto se puede hacer con

/usr/bin/python setup.py install --prefix=/usr/local

Otra posibilidad es un sistema de archivos de red donde el nombre utilizado para escribir en un directorio remoto es diferente del nombre utilizado para leerlo: por ejemplo, el intérprete de Python al que se accede como /usr/local/bin/python podría buscar módulos en /usr/local/lib/python2.X, pero esos módulos tendrían que instalarse en, por ejemplo, /mnt/@servidor/export/lib/python2.X. Esto podría hacerse con

/usr/local/bin/python setup.py install --prefix=/mnt/@server/export

En cualquier caso, la opción --prefix define la base de instalación, y la opción --exec-prefix define la base de instalación específica de la plataforma, que se utiliza para archivos específicos de la plataforma . (Actualmente, esto solo significa distribuciones de módulos no puras, pero podría expandirse a bibliotecas C, ejecutables binarios, etc.) Si:option:!–exec-prefix no se proporciona, el valor predeterminado es --prefix. Los archivos se instalan de la siguiente manera:

Tipo de archivo

Directorio de instalación

Modules de Python

prefix/lib/pythonX.Y/site-packages

extensión de módulos

exec-prefix/lib/pythonX.Y/site-packages

scripts

prefix/bin

dato

prefix

Cabeceras C

prefix/include/pythonX.Yabiflags/distname

No es necesario que --prefix o --exec-prefix realmente apunte a una instalación alternativa de Python; Si los directorios enumerados anteriormente no existen, se crean en el momento de la instalación.

Por cierto, la verdadera razón por la que el esquema de prefijos es importante es simplemente que una instalación estándar de Unix usa el esquema de prefijos, pero con --prefix y --exec-prefix suministrado por Python como sys.prefix y sys.exec_prefix. Por lo tanto, puede pensar que nunca usará el esquema de prefijo, pero cada vez que ejecuta python setup.py install sin ninguna otra opción, lo está usando.

Tenga en cuenta que la instalación de extensiones en una instalación alternativa de Python no tiene efecto sobre cómo se construyen esas extensiones: en particular, los archivos de encabezado de Python (Python.h y amigos) instalados con el intérprete de Python utilizado para ejecutar el script de configuración ser utilizado en la compilación de extensiones. Es su responsabilidad asegurarse de que el intérprete utilizado para ejecutar las extensiones instaladas de esta manera sea compatible con el intérprete utilizado para construirlas. La mejor manera de hacer esto es asegurarse de que los dos intérpretes sean la misma versión de Python (posiblemente compilaciones diferentes, o posiblemente copias de la misma compilación). (Por supuesto, si su --prefix y -- exec-prefix ni siquiera apuntan a una instalación alternativa de Python, esto es irrelevante).

Instalación alternativa: Windows (el esquema de prefijo)

Windows no tiene el concepto del directorio de inicio de un usuario, y dado que la instalación estándar de Python en Windows es más simple que en Unix, la opción --prefix se ha usado tradicionalmente para instalar paquetes adicionales en ubicaciones separadas en Windows.

python setup.py install --prefix="\Temp\Python"

instalar los módulos en el directorio \Temp\Python en el disco actual.

La base de instalación se define mediante la opción --prefix; la opción --exec-prefix no es compatible con Windows, lo que significa que los módulos Python puros y los módulos de extensión están instalados en la misma ubicación. Los archivos se instalan de la siguiente manera:

Tipo de archivo

Directorio de instalación

módulos

prefix\Lib\site-packages

scripts

prefix\Scripts

dato

prefix

Cabeceras C

prefix\Include{distname}

Instalación personalizada

A veces, los esquemas de instalación alternativos descritos en la sección Instalación alternativa simplemente no hacen lo que quieres. Es posible que desee ajustar solo uno o dos directorios mientras mantiene todo bajo el mismo directorio base, o puede que desee redefinir completamente el esquema de instalación. En cualquier caso, está creando un esquema de instalación personalizado.

Para crear un esquema de instalación personalizado, comience con uno de los esquemas alternativos y anule algunos de los directorios de instalación utilizados para los distintos tipos de archivos, utilizando estas opciones:

Tipo de archivo

Sobreescribir opciones

Modules de Python

--install-purelib

extensión de módulos

--install-platlib

todos los módulos

--install-lib

scripts

--install-scripts

dato

--install-data

Cabeceras C

--install-headers

Estas opciones de invalidación pueden ser relativas, absolutas o definidas explícitamente en términos de uno de los directorios base de instalación. (Hay dos directorios base de instalación, y normalmente son los mismos— sólo difieren cuando se utiliza el «esquema de prefijo» de Unix y se proporcionan diferentes opciones de --prefijo y --exec-prefix; usando --install-lib anulará los valores calculados o dados para install-purelib y --install-platlib, y se recomienda para esquemas que no hacen diferencia entre Python y extensión.

Por ejemplo, supongamos que se está instalando una distribución de módulos en su directorio de inicio en Unix—pero se desea que los scripts vayan en /scripts en lugar de /bin. Como es de esperar, puede invalidar este directorio con la opción --install-scripts; en este caso, tiene más sentido proporcionar una ruta relativa, que se interpretará en relación con el directorio base de la instalación (su directorio principal, en este caso):

python setup.py install --home=~ --install-scripts=scripts

Otro ejemplo de Unix: supongamos que la instalación de Python se creó e instaló con un prefijo de /usr/local/python, por lo que bajo una instalación estándar los scripts terminarán en /usr/local/python/bin. Si los desea en /usr/local/bin en su lugar, debe proporcionar este directorio absoluto para la opción --install-scripts:

python setup.py install --install-scripts=/usr/local/bin

(Esto realiza una instalación utilizando el «esquema de prefijo», donde el prefijo es lo que su intérprete de Python se instaló con— /usr/local/python en este caso.)

Si mantiene Python en Windows, es posible que desee que los módulos de terceros vivan en un subdirectorio de prefijo, en lugar de hacerlo en prefijo en sí. Esto es casi tan fácil como personalizar el directorio de instalación de script—sólo hay que recordar que hay dos tipos de módulos de los que preocuparse, Python y módulos de extensión, que pueden ser convenientemente controlados por una opción:

python setup.py install --install-lib=Site

El directorio de instalación especificado es relativo a -prefijo. Por supuesto, también tiene que asegurarse de que este directorio está en la ruta de búsqueda del módulo de Python, por ejemplo, colocando un archivo .pth en un directorio de sitio (consulte site). Consulte la sección Modificando el Camino de Búsqueda de Python para averiguar cómo modificar la ruta de búsqueda de Python.

Si desea definir un esquema de instalación completo, sólo tiene que proporcionar todas las opciones del directorio de instalación. La forma recomendada de hacerlo es proporcionar rutas relativas; por ejemplo, si desea mantener todos los archivos relacionados con el módulo python en python en su directorio principal y desea un directorio independiente para cada plataforma desde la que utilice el directorio principal, puede definir el siguiente esquema de instalación:

python setup.py install --home=~ \
                        --install-purelib=python/lib \
                        --install-platlib=python/lib.$PLAT \
                        --install-scripts=python/scripts
                        --install-data=python/data

o, equivalente,

python setup.py install --home=~/python \
                        --install-purelib=lib \
                        --install-platlib='lib.$PLAT' \
                        --install-scripts=scripts
                        --install-data=data

$PLAT no es (necesariamente) una variable de entorno—se expandirá el Distutils a medida que analiza las opciones de línea de comandos, tal como lo hace al analizar los archivos de configuración.

Obviamente, especificar el esquema de instalación completo cada vez que instala un nuevo módulo de distribución sería muy tedioso. Por lo tanto, puede poner estas opciones en su archivo de configuración de Distutils (consulte la sección Archivos de Configuración de Distutils):

[install]
install-base=$HOME
install-purelib=python/lib
install-platlib=python/lib.$PLAT
install-scripts=python/scripts
install-data=python/data

o ,equivalente,

[install]
install-base=$HOME/python
install-purelib=lib
install-platlib=lib.$PLAT
install-scripts=scripts
install-data=data

Tenga en cuenta que estos dos son no equivalentes si proporciona un directorio base de instalación diferente cuando ejecuta el script de configuración. Por ejemplo,

python setup.py install --install-base=/tmp

instalaría módulos puros en /tmp/python/lib en el primer caso, y en /tmp/lib en el segundo caso. (Para el segundo caso, probablemente desee proporcionar una base de instalación de /tmp/python.)

Probablemente haya notado el uso de $HOME y $ PLAT en la entrada del archivo de configuración de muestra. Estas son las variables de configuración de Distutils, que tienen un gran parecido con las variables de entorno. De hecho, puede usar variables de entorno en archivos de configuración en plataformas que tienen esa noción, pero los Distutils definen adicionalmente algunas variables adicionales que pueden no estar en su entorno, como $PLAT. (Y, por supuesto, en los sistemas que no tienen variables de entorno, como Mac OS 9, las variables de configuración proporcionadas por Distutils son las únicas que puede usar). Consulte la sección Archivos de Configuración de Distutils para detalles.

Nota

Cuando a entorno virtual está activado, cualquier opción que cambie la ruta de instalación será ignorada de todos los archivos de configuración de distutils para evitar la instalación accidental de proyectos fuera del entorno virtual.

Modificando el Camino de Búsqueda de Python

Cuando el intérprete de Python ejecuta una declaración import, busca tanto el código de Python como los módulos de extensión a lo largo de una ruta de búsqueda. Un valor predeterminado para la ruta se configura en el binario de Python cuando se construye el intérprete. Puede determinar la ruta importando el módulo sys e imprimiendo el valor de sys.path.

$ python
Python 2.2 (#11, Oct  3 2002, 13:31:27)
[GCC 2.96 20000731 (Red Hat Linux 7.3 2.96-112)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys.path
['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2',
 '/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload',
 '/usr/local/lib/python2.3/site-packages']
>>>

La cadena nula en sys.path representa el directorio de trabajo actual.

La convención esperada para los paquetes instalados localmente es ponerlos en el directorio …/site-packages/, pero es posible que desee instalar módulos de Python en algún directorio arbitrario. Por ejemplo, su sitio puede tener una convención de mantener todo el software relacionado con el servidor web en /www. Los módulos adicionales de Python pueden pertenecer a /www/python, y para importarlos, este directorio debe agregarse a sys.path. Hay varias formas diferentes de agregar el directorio.

La forma más conveniente es agregar un archivo de configuración de ruta a un directorio que ya está en la ruta de Python, generalmente al directorio .../site-packages/. Los archivos de configuración de ruta tienen una extensión de .pth, y cada línea debe contener una ruta única que se agregará a sys.path. (Debido a que las nuevas rutas se agregan a sys.path, los módulos en los directorios agregados no anularán los módulos estándar. Esto significa que no puede usar este mecanismo para instalar versiones fijas de módulos estándar).

Las rutas pueden ser absolutas o relativas, en cuyo caso son relativas al directorio que contiene el archivo .pth. Consulte la documentación del módulo site para obtener más información.

Una forma un poco menos conveniente es editar el archivo site.py en la biblioteca estándar de Python y modificar sys.path. site.py se importa automáticamente cuando se ejecuta el intérprete de Python, a menos que se proporcione el -S para suprimir este comportamiento. Entonces, simplemente puede editar site.py y agregarle dos líneas:

import sys
sys.path.append('/www/python/')

Sin embargo, si reinstala la misma versión principal de Python (tal vez al actualizar de 2.2 a 2.2.2, por ejemplo) la versión de archivo sobrescribirá el site.py. Debería recordar que se modificó y guardar una copia antes de realizar la instalación.

Hay dos variables de entorno que pueden modificar sys.path. PYTHONHOME establece un valor alternativo para el prefijo de la instalación de Python. Por ejemplo, si PYTHONHOME está configurado en /www/python, la ruta de búsqueda se establecerá en ['', '/www/python/lib/pythonX.Y/', '/www/python/lib/pythonX.Y/plat-linux2', ...].

La variable PYTHONPATH se puede establecer en una lista de rutas que se agregarán al comienzo de sys.path. Por ejemplo, si PYTHONPATH está establecido en /www/python:/opt /py, la ruta de búsqueda comenzará con ['/www/python', '/opt/py'] ``. (Tenga en cuenta que los directorios deben existir para poder agregarlos a ``sys.path; el módulo site elimina las rutas que no existen).

Finalmente,``sys.path`` es solo una lista normal de Python, por lo que cualquier aplicación de Python puede modificarla agregando o eliminando entradas.

Archivos de Configuración de Distutils

Como se mencionó anteriormente, puede usar los archivos de configuración de Distutils para registrar las preferencias personales o del sitio para cualquier opción de Distutils. Es decir, cualquier opción para cualquier comando puede almacenarse en uno de dos o tres (según su plataforma) archivos de configuración, que se consultarán antes de analizar la línea de comandos. Esto significa que los archivos de configuración anularán los valores predeterminados, y la línea de comandos a su vez anulará los archivos de configuración. Además, si se aplican varios archivos de configuración, los valores de los archivos «anteriores» se anulan por los archivos «posteriores».

Ubicación y nombres de los archivos de configuración

The names and locations of the configuration files vary slightly across platforms. On Unix and macOS, the three configuration files (in the order they are processed) are:

Tipo de archivo

Ubicación y nombre de archivo

Notas

sistema

prefix/lib/pythonver/distutils/distutils.cfg

(1)

personal

$HOME/.pydistutils.cfg

(2)

local

setup.cfg

(3)

Y en Windows, los archivos de configuración son:

Tipo de archivo

Ubicación y nombre de archivo

Notas

sistema

prefix\Lib\distutils\distutils.cfg

(4)

personal

%HOME%\pydistutils.cfg

(5)

local

setup.cfg

(3)

En todas las plataformas, el archivo «personal» puede deshabilitarse temporalmente pasando la opción –no-user-cfg.

Notas:

Estrictamente hablando, el archivo de configuración de todo el sistema vive en el directorio donde están instalados los Distutils; bajo Python 1.6 y posterior en Unix, esto es como se muestra. Para Python 1.5.2, Distutils normalmente se instalará en prefijo/lib/python1.5/site-packages/distutils, por lo que el archivo de configuración del sistema debe colocarse allí en Python 1.5.2.

En Unix, si la variable de entorno HOME no está definida, el directorio de inicio del usuario se determinará con la función getpwuid() del módulo estándar pwd. Esto se realiza mediante la función os.path.expanduser() utilizada por Distutils.

Por ejemplo, en el directorio actual (usualmente la ubicación del script de setup).

(Ver nota (1).) En Python 1.6 y posterior, el «prefijo de instalación» por defecto de Python es C:\Python, entonces el archivo de configuración de sistema es normalmente C:\Python\Lib\distutils\distutils.cfg. En Python 1.5.2, el prefijo por defecto era C:\Program Files\Python, y Distutils no eran parte de la biblioteca estándar—entonces el archivo de configuración de sistema debería ser C:\Program Files\Python\distutils\distutils.cfg en una instalación estándar de Python 1.5.2 en Windows.

En Windows, si la variable de entorno HOME no está definida, se probará USERPROFILE y luego HOMEDRIVE y HOMEPATH. Esto se realiza mediante la función os.path.expanduser() utilizada por Distutils.

Archivos de configuración de sintaxis

Todos los archivos de configuración de Distutils tienen la misma sintaxis. Los archivos de configuración se agrupan en secciones. Hay una sección para cada comando de Distutils, más una sección global para las opciones globales que afectan a cada comando. Cada sección consta de una opción por línea, especificada como opción=valor.

Por ejemplo, el siguiente es un archivo de configuración completo que solo obliga a todos los comandos a ejecutarse silenciosamente de manera predeterminada:

[global]
verbose=0

Si se instala como el archivo de configuración del sistema, afectará todo el procesamiento de cualquier distribución del módulo Python por parte de cualquier usuario en el sistema actual. Si se instala como su archivo de configuración personal (en sistemas que los admiten), afectará solo las distribuciones de módulos procesadas por usted. Y si se usa como setup.cfg para una distribución de módulo en particular, solo afecta a esa distribución.

Puede anular el directorio «base de compilación» predeterminado y hacer que los comandos build* siempre reconstruyan a la fuerza todos los archivos con lo siguiente:

[build]
build-base=blib
force=1

que corresponde a los argumentos de la línea de comandos

python setup.py build --build-base=blib --force

excepto que incluir el comando build en la línea de comandos significa que ese comando se ejecutará. Incluir un comando particular en los archivos de configuración no tiene tal implicación; solo significa que si se ejecuta el comando, se aplicarán las opciones en el archivo de configuración. (O si se ejecutan otros comandos que derivan valores de él, utilizarán los valores en el archivo de configuración).

Puede encontrar la lista completa de opciones para cualquier comando usando la opción --help, por ejemplo:

python setup.py build --help

y puede encontrar la lista completa de opciones globales usando -help sin un comando:

python setup.py --help

Ver también la sección «Referencia» del manual de «Distribución de Módulos de Python».

Construyendo Extensiones: Ayudas y trucos

Siempre que sea posible, los Distutils intentan utilizar la información de configuración disponible por el intérprete de Python utilizado para ejecutar el script setup.py. Por ejemplo, los mismos indicadores de compilador y enlazador utilizados para compilar Python también se usarán para compilar extensiones. Por lo general, esto funcionará bien, pero en situaciones complicadas esto puede ser inapropiado. Esta sección discute cómo anular el comportamiento habitual de Distutils.

Ajustar las flags del compilador/enlazador

La compilación de una extensión de Python escrita en C o C ++ a veces requerirá especificar marcas personalizadas para el compilador y el enlazador para usar una biblioteca particular o producir un tipo especial de código de objeto. Esto es especialmente cierto si la extensión no ha sido probada en su plataforma, o si está intentando compilar Python de forma cruzada.

En el caso más general, el autor de la extensión podría haber previsto que compilar las extensiones sería complicado, y proporcionó un archivo Setup para que lo edite. Es probable que esto solo se haga si la distribución del módulo contiene muchos módulos de extensión separados, o si a menudo requieren conjuntos elaborados de indicadores de compilación para funcionar.

Un archivo Setup, si está presente, es parseado para obtener una lista de extensiones para compilar. Cada línea en un archivo Setup describe un solo módulo. Las líneas tienen la siguiente estructura

module ... [sourcefile ...] [cpparg ...] [library ...]

Examinemos cada uno de los campos a su vez.

módulo es el nombre del módulo de extensión que se creará, y debe ser un identificador válido de Python. No puede simplemente cambiar esto para cambiar el nombre de un módulo (también serían necesarias ediciones en el código fuente), por lo que esto debería dejarse solo.

archivo fuente es cualquier cosa que probablemente sea un archivo de código fuente, al menos a juzgar por el nombre del archivo. Se supone que los nombres de archivo que terminan en .c están escritos en C, los nombres de archivo que terminan en .C , .cc, y .c++ son de C ++, y se supone que los nombres de archivo que terminan en .m o .mm están en el Objetivo C.

cpparg es un argumento para el preprocesador C, y es cualquier cosa que comience con -I, -D, -U or -C.

biblioteca es todo aquello que termina con .a or empieza con -l o -L.

Si una plataforma en particular requiere una biblioteca especial en su plataforma, puede agregarla editando el archivo Setup y ejecutando python setup.py build. Por ejemplo, si el módulo definido por la línea

foo foomodule.c

debe estar vinculado con la biblioteca matemática libm.a en su plataforma, simplemente agregue -lm a la línea

foo foomodule.c -lm

Los conmutadores arbitrarios destinados al compilador o al enlazador se pueden suministrar con -Xcompiler arg y -Xlinker arg options:

foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm

La siguiente opción después de -Xcompiler y -Xlinker se agregará a la línea de comando adecuada, por lo que en el ejemplo anterior se pasará al compilador la opción -O32 , y se pasará al enlazador -shared. Si una opción del compilador requiere un argumento, deberá proporcionar varias opciones -Xcompiler; por ejemplo, para pasar -x c++ el Setup debería contener -Xcompiler -x -Xcompiler c++.

Los indicadores del compilador también se pueden suministrar configurando la variable de entorno CFLAGS. Si se establece, el contenido de CFLAGS se agregará a los indicadores del compilador especificados en el archivo Configuración.

Usando un compilador que no sea de Microsoft en Windows

Borland/CodeGear C++

Esta subsección describe los pasos necesarios para usar Distutils con el compilador Borland C++ versión 5.5. Primero debe saber que el formato de archivo de objetos (OMF) de Borland es diferente del formato utilizado por la versión de Python que puede descargar del sitio web de Python o ActiveState. (Python está construido con Microsoft Visual C++, que utiliza COFF como formato de archivo de objeto). Por esta razón, debe convertir la biblioteca de Python python25.lib al formato Borland. Puede hacer esto de la siguiente manera:

coff2omf python25.lib python25_bcpp.lib

El programa coff2omf viene con el compilador Borland. El archivo python25.lib está en el directorio Libs de su instalación de Python. Si su extensión usa otras bibliotecas (zlib, …), también debe convertirlas.

Los archivos convertidos tienen que residir en los mismos directorios que las bibliotecas normales.

¿Cómo logra Distutils usar estas bibliotecas con sus nombres cambiados? Si la extensión necesita una biblioteca (por ejemplo foo) Distutils verifica primero si encuentra una biblioteca con el sufijo _bcpp (por ejemplo foo_bcpp.lib) y luego usa esta biblioteca. En el caso de que no encuentre una biblioteca tan especial, usa el nombre predeterminado (foo.lib.) 1

Para permitir que Distutils compile su extensión con Borland C++, ahora debe escribir:

python setup.py build --compiler=bcpp

Si desea utilizar el compilador Borland C++ como predeterminado, puede especificar esto en su archivo de configuración personal o de todo el sistema para Distutils (consulte la sección Archivos de Configuración de Distutils.)

Ver también

Compilador *C++ Builder* [https://www.embarcadero.com/products]

Información sobre el compilador gratuito de C++ de Borland, incluidos enlaces a las páginas de descarga.

Crear Extensiones de Python usando el Compilador libre de Borland [http://www.cyberus.ca/~g_will/pyExtenDL.shtml]

Documento que describe cómo usar el compilador C ++ de línea de comandos gratuito de Borland para construir Python.

GNU C / Cygwin / MinGW

Esta sección describe los pasos necesarios para usar Distutils con los compiladores GNU C/C++ en sus distribuciones Cygwin y MinGW. 2 Para un intérprete de Python que fue construido con Cygwin, todo debería funcionar sin ninguno de estos pasos.

No todas las extensiones se pueden construir con MinGW o Cygwin, pero muchas sí. Las extensiones que probablemente no funcionen son aquellas que usan C++ o dependen de las extensiones de Microsoft Visual C.

Para dejar que Distutils compile tu extensión con Cygwin tienes que escribir:

python setup.py build --compiler=cygwin

y para Cygwin en modo no-cygwin 3 o para tipo MinGW:

python setup.py build --compiler=mingw32

Si desea utilizar cualquiera de estas opciones/compiladores por defecto, debería considerar escribirlo en su archivo de configuración personal o de todo el sistema para Distutils (consulte la sección Archivos de Configuración de Distutils).

Versiones antiguas de Python y MinGW

Las siguientes instrucciones solo se aplican si está utilizando una versión de Python inferior a 2.4.1 con un MinGW inferior a 3.0.0 (con binutils-2.13.90-20030111-1).

Estos compiladores requieren algunas bibliotecas especiales. Esta tarea es más compleja que para C++ de Borland, porque no hay un programa para convertir la biblioteca. Primero debe crear una lista de símbolos que exporta la DLL de Python. (Puede encontrar un buen programa para esta tarea en https://sourceforge.net/projects/mingw/files/MinGW/Extension/pexports/).

pexports python25.dll >python25.def

La ubicación de un instalado python25.dll dependerá de las opciones de instalación y la versión y el idioma de Windows. En una instalación «solo para mí», aparecerá en la raíz del directorio de instalación. En una instalación compartida, se ubicará en el directorio del sistema.

Luego puede crear a partir de esta información una biblioteca de importación para gcc.

/cygwin/bin/dlltool --dllname python25.dll --def python25.def --output-lib libpython25.a

La biblioteca resultante debe colocarse en el mismo directorio que python25.lib. (Debe ser el directorio libs en el directorio de instalación de Python.)

Si su extensión usa otras bibliotecas (zlib, …), es posible que también deba convertirlas. Los archivos convertidos tienen que residir en los mismos directorios que las bibliotecas normales.

Ver también

Construyendo modules Python en plataformas de Microsoft Windows con MinGW [http://old.zope.org/Members/als/tips/win32_mingw_modules]

Información sobre la creación de las bibliotecas necesarias para el entorno MinGW.

Notas al pie

1

Esto también significa que puede reemplazar todas las bibliotecas COFF existentes con bibliotecas OMF del mismo nombre.

2

Diríjase a https://www.sourceware.org/cygwin/ para mayor información

3

Entonces no tiene disponible la emulación POSIX, pero tampoco necesita cygwin1.dll.

Índice de Módulos Python

_ | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r | s | t | u | v | w | x | z

| _ |
| __future__ | Future statement definitions
| __main__ | The environment where the top-level script is run.
| _thread | Low-level threading API.
| a |
| abc | Abstract base classes according to :pep:`3119`.
| aifc | Obsoleto: Read and write audio files in AIFF or AIFC format.
| argparse | Command-line option and argument parsing library.
| array | Space efficient arrays of uniformly typed numeric values.
| ast | Abstract Syntax Tree classes and manipulation.
| asynchat | Obsoleto: Support for asynchronous command/response protocols.
| asyncio | Asynchronous I/O.
| asyncore | Obsoleto: A base class for developing asynchronous socket handling services.
| atexit | Register and execute cleanup functions.
| audioop | Obsoleto: Manipulate raw audio data.
| b |
| base64 | RFC 3548: Base16, Base32, Base64 Data Encodings; Base85 and Ascii85
| bdb | Debugger framework.
| binascii | Tools for converting between binary and various ASCII-encoded binary representations.
| binhex | Encode and decode files in binhex4 format.
| bisect | Array bisection algorithms for binary searching.
| builtins | The module that provides the built-in namespace.
| bz2 | Interfaces for bzip2 compression and decompression.
| c |
| calendar | Functions for working with calendars, including some emulation of the Unix cal program.
| cgi | Obsoleto: Helpers for running Python scripts via the Common Gateway Interface.
| cgitb | Obsoleto: Configurable traceback handler for CGI scripts.
| chunk | Obsoleto: Module to read IFF chunks.
| cmath | Mathematical functions for complex numbers.
| cmd | Build line-oriented command interpreters.
| code | Facilities to implement read-eval-print loops.
| codecs | Encode and decode data and streams.
| codeop | Compile (possibly incomplete) Python code.
- | collections | Container datatypes
|     collections.abc | Abstract base classes for containers
| colorsys | Conversion functions between RGB and other color systems.
| compileall | Tools for byte-compiling all Python source files in a directory tree.
- | concurrent |
|     concurrent.futures | Execute computations concurrently using threads or processes.
| configparser | Configuration file parser.
| contextlib | Utilities for with-statement contexts.
| contextvars | Context Variables
| copy | Shallow and deep copy operations.
| copyreg | Register pickle support functions.
| cProfile |
| crypt (Unix) | Obsoleto: The crypt() function used to check Unix passwords.
| csv | Write and read tabular data to and from delimited files.
| ctypes | A foreign function library for Python.
- | curses (Unix) | An interface to the curses library, providing portable terminal handling.
|     curses.ascii | Constants and set-membership functions for ASCII characters.
|     curses.panel | A panel stack extension that adds depth to curses windows.
|     curses.textpad | Emacs-like input editing in a curses window.
| d |
| dataclasses | Generate special methods on user-defined classes.
| datetime | Basic date and time types.
- | dbm | Interfaces to various Unix "database" formats.
|     dbm.dumb | Portable implementation of the simple DBM interface.
|     dbm.gnu (Unix) | GNU's reinterpretation of dbm.
|     dbm.ndbm (Unix) | The standard "database" interface, based on ndbm.
| decimal | Implementation of the General Decimal Arithmetic Specification.
| difflib | Helpers for computing differences between objects.
| dis | Disassembler for Python bytecode.
- | distutils | Support for building and installing Python modules into an existing Python installation.
|     distutils.archive_util | Utility functions for creating archive files (tarballs, zip files, ...)
|     distutils.bcppcompiler |
|     distutils.ccompiler | Abstract CCompiler class
|     distutils.cmd | Provides the abstract base class :class:`~distutils.cmd.Command`. This class is subclassed by the modules in the distutils.command subpackage.
|     distutils.command | Contains one module for each standard Distutils command.
|     distutils.command.bdist | Build a binary installer for a package
|     distutils.command.bdist_dumb | Build a "dumb" installer - a simple archive of files
|     distutils.command.bdist_msi | Build a binary distribution as a Windows MSI file
|     distutils.command.bdist_packager | Abstract base class for packagers
|     distutils.command.bdist_rpm | Build a binary distribution as a Redhat RPM and SRPM
|     distutils.command.bdist_wininst | Build a Windows installer
|     distutils.command.build | Build all files of a package
|     distutils.command.build_clib | Build any C libraries in a package
|     distutils.command.build_ext | Build any extensions in a package
|     distutils.command.build_py | Build the .py/.pyc files of a package
|     distutils.command.build_scripts | Build the scripts of a package
|     distutils.command.check | Check the meta-data of a package
|     distutils.command.clean | Clean a package build area
|     distutils.command.config | Perform package configuration
|     distutils.command.install | Install a package
|     distutils.command.install_data | Install data files from a package
|     distutils.command.install_headers | Install C/C++ header files from a package
|     distutils.command.install_lib | Install library files from a package
|     distutils.command.install_scripts | Install script files from a package
|     distutils.command.register | Register a module with the Python Package Index
|     distutils.command.sdist | Build a source distribution
|     distutils.core | The core Distutils functionality
|     distutils.cygwinccompiler |
|     distutils.debug | Provides the debug flag for distutils
|     distutils.dep_util | Utility functions for simple dependency checking
|     distutils.dir_util | Utility functions for operating on directories and directory trees
|     distutils.dist | Provides the Distribution class, which represents the module distribution being built/installed/distributed
|     distutils.errors | Provides standard distutils exceptions
|     distutils.extension | Provides the Extension class, used to describe C/C++ extension modules in setup scripts
|     distutils.fancy_getopt | Additional getopt functionality
|     distutils.file_util | Utility functions for operating on single files
|     distutils.filelist | The FileList class, used for poking about the file system and building lists of files.
|     distutils.log | A simple logging mechanism, :pep:`282`-style
|     distutils.msvccompiler | Microsoft Compiler
|     distutils.spawn | Provides the spawn() function
|     distutils.sysconfig | Low-level access to configuration information of the Python interpreter.
|     distutils.text_file | Provides the TextFile class, a simple interface to text files
|     distutils.unixccompiler | UNIX C Compiler
|     distutils.util | Miscellaneous other utility functions
|     distutils.version | Implements classes that represent module version numbers.
| doctest | Test pieces of code within docstrings.
| e |
- | email | Package supporting the parsing, manipulating, and generating email messages.
|     email.charset | Character Sets
|     email.contentmanager | Storing and Retrieving Content from MIME Parts
|     email.encoders | Encoders for email message payloads.
|     email.errors | The exception classes used by the email package.
|     email.generator | Generate flat text email messages from a message structure.
|     email.header | Representing non-ASCII headers
|     email.headerregistry | Automatic Parsing of headers based on the field name
|     email.iterators | Iterate over a message object tree.
|     email.message | The base class representing email messages.
|     email.mime | Build MIME messages.
|     email.parser | Parse flat text email messages to produce a message object structure.
|     email.policy | Controlling the parsing and generating of messages
|     email.utils | Miscellaneous email package utilities.
- | encodings |
|     encodings.idna | Internationalized Domain Names implementation
|     encodings.mbcs | Windows ANSI codepage
|     encodings.utf_8_sig | UTF-8 codec with BOM signature
| ensurepip | Bootstrapping the "pip" installer into an existing Python installation or virtual environment.
| enum | Implementation of an enumeration class.
| errno | Standard errno system symbols.
| f |
| faulthandler | Dump the Python traceback.
| fcntl (Unix) | The fcntl() and ioctl() system calls.
| filecmp | Compare files efficiently.
| fileinput | Loop over standard input or a list of files.
| fnmatch | Unix shell style filename pattern matching.
| formatter | Obsoleto: Generic output formatter and device interface.
| fractions | Rational numbers.
| ftplib | FTP protocol client (requires sockets).
| functools | Higher-order functions and operations on callable objects.
| g |
| gc | Interface to the cycle-detecting garbage collector.
| getopt | Portable parser for command line options; support both short and long option names.
| getpass | Portable reading of passwords and retrieval of the userid.
| gettext | Multilingual internationalization services.
| glob | Unix shell style pathname pattern expansion.
| graphlib | Functionality to operate with graph-like structures
| grp (Unix) | The group database (getgrnam() and friends).
| gzip | Interfaces for gzip compression and decompression using file objects.
| h |
| hashlib | Secure hash and message digest algorithms.
| heapq | Heap queue algorithm (a.k.a. priority queue).
| hmac | Keyed-Hashing for Message Authentication (HMAC) implementation
- | html | Helpers for manipulating HTML.
|     html.entities | Definitions of HTML general entities.
|     html.parser | A simple parser that can handle HTML and XHTML.
- | http | HTTP status codes and messages
|     http.client | HTTP and HTTPS protocol client (requires sockets).
|     http.cookiejar | Classes for automatic handling of HTTP cookies.
|     http.cookies | Support for HTTP state management (cookies).
|     http.server | HTTP server and request handlers.
| i |
| imaplib | IMAP4 protocol client (requires sockets).
| imghdr | Obsoleto: Determine the type of image contained in a file or byte stream.
| imp | Obsoleto: Access the implementation of the import statement.
- | importlib | The implementation of the import machinery.
|     importlib.abc | Abstract base classes related to import
|     importlib.machinery | Importers and path hooks
|     importlib.metadata | The implementation of the importlib metadata.
|     importlib.resources | Package resource reading, opening, and access
|     importlib.util | Utility code for importers
| inspect | Extract information and source code from live objects.
| io | Core tools for working with streams.
| ipaddress | IPv4/IPv6 manipulation library.
| itertools | Functions creating iterators for efficient looping.
| j |
- | json | Encode and decode the JSON format.
|     json.tool | A command line to validate and pretty-print JSON.
| k |
| keyword | Test whether a string is a keyword in Python.
| l |
| lib2to3 | The 2to3 library
| linecache | Provides random access to individual lines from text files.
| locale | Internationalization services.
- | logging | Flexible event logging system for applications.
|     logging.config | Configuration of the logging module.
|     logging.handlers | Handlers for the logging module.
| lzma | A Python wrapper for the liblzma compression library.
| m |
| mailbox | Manipulate mailboxes in various formats
| mailcap | Obsoleto: Mailcap file handling.
| marshal | Convert Python objects to streams of bytes and back (with different constraints).
| math | Mathematical functions (sin() etc.).
| mimetypes | Mapping of filename extensions to MIME types.
| mmap | Interface to memory-mapped files for Unix and Windows.
| modulefinder | Find modules used by a script.
| msilib (Windows) | Obsoleto: Creation of Microsoft Installer files, and CAB files.
| msvcrt (Windows) | Miscellaneous useful routines from the MS VC++ runtime.
- | multiprocessing | Process-based parallelism.
|     multiprocessing.connection | API for dealing with sockets.
|     multiprocessing.dummy | Dumb wrapper around threading.
|     multiprocessing.managers | Share data between process with shared objects.
|     multiprocessing.pool | Create pools of processes.
|     multiprocessing.shared_memory | Provides shared memory for direct access across processes.
|     multiprocessing.sharedctypes | Allocate ctypes objects from shared memory.
| n |
| netrc | Loading of .netrc files.
| nis (Unix) | Obsoleto: Interface to Sun's NIS (Yellow Pages) library.
| nntplib | Obsoleto: NNTP protocol client (requires sockets).
| numbers | Numeric abstract base classes (Complex, Real, Integral, etc.).
| o |
| operator | Functions corresponding to the standard operators.
| optparse | Obsoleto: Command-line option parsing library.
- | os | Miscellaneous operating system interfaces.
|     os.path | Operations on pathnames.
| ossaudiodev (Linux, FreeBSD) | Obsoleto: Access to OSS-compatible audio devices.
| p |
| parser | Access parse trees for Python source code.
| pathlib | Object-oriented filesystem paths
| pdb | The Python debugger for interactive interpreters.
| pickle | Convert Python objects to streams of bytes and back.
| pickletools | Contains extensive comments about the pickle protocols and pickle-machine opcodes, as well as some useful functions.
| pipes (Unix) | Obsoleto: A Python interface to Unix shell pipelines.
| pkgutil | Utilities for the import system.
| platform | Retrieves as much platform identifying data as possible.
| plistlib | Generate and parse Apple plist files.
| poplib | POP3 protocol client (requires sockets).
| posix (Unix) | The most common POSIX system calls (normally used via module os).
| pprint | Data pretty printer.
| profile | Python source profiler.
| pstats | Statistics object for use with the profiler.
| pty (Linux) | Pseudo-Terminal Handling for Linux.
| pwd (Unix) | The password database (getpwnam() and friends).
| py_compile | Generate byte-code files from Python source files.
| pyclbr | Supports information extraction for a Python module browser.
| pydoc | Documentation generator and online help system.
| q |
| queue | A synchronized queue class.
| quopri | Encode and decode files using the MIME quoted-printable encoding.
| r |
| random | Generate pseudo-random numbers with various common distributions.
| re | Regular expression operations.
| readline (Unix) | GNU readline support for Python.
| reprlib | Alternate repr() implementation with size limits.
| resource (Unix) | An interface to provide resource usage information on the current process.
| rlcompleter | Python identifier completion, suitable for the GNU readline library.
| runpy | Locate and run Python modules without importing them first.
| s |
| sched | General purpose event scheduler.
| secrets | Generate secure random numbers for managing secrets.
| select | Wait for I/O completion on multiple streams.
| selectors | High-level I/O multiplexing.
| shelve | Python object persistence.
| shlex | Simple lexical analysis for Unix shell-like languages.
| shutil | High-level file operations, including copying.
| signal | Set handlers for asynchronous events.
| site | Module responsible for site-specific configuration.
| smtpd | Obsoleto: A SMTP server implementation in Python.
| smtplib | SMTP protocol client (requires sockets).
| sndhdr | Obsoleto: Determine type of a sound file.
| socket | Low-level networking interface.
| socketserver | A framework for network servers.
| spwd (Unix) | Obsoleto: The shadow password database (getspnam() and friends).
| sqlite3 | A DB-API 2.0 implementation using SQLite 3.x.
| ssl | TLS/SSL wrapper for socket objects
| stat | Utilities for interpreting the results of os.stat(), os.lstat() and os.fstat().
| statistics | Mathematical statistics functions
| string | Common string operations.
| stringprep | String preparation, as per RFC 3453
| struct | Interpret bytes as packed binary data.
| subprocess | Subprocess management.
| sunau | Obsoleto: Provide an interface to the Sun AU sound format.
| symbol | Constants representing internal nodes of the parse tree.
| symtable | Interface to the compiler's internal symbol tables.
| sys | Access system-specific parameters and functions.
| sysconfig | Python's configuration information
| syslog (Unix) | An interface to the Unix syslog library routines.
| t |
| tabnanny | Tool for detecting white space related problems in Python source files in a directory tree.
| tarfile | Read and write tar-format archive files.
| telnetlib | Obsoleto: Telnet client class.
| tempfile | Generate temporary files and directories.
| termios (Unix) | POSIX style tty control.
- | test | Regression tests package containing the testing suite for Python.
|     test.support | Support for Python's regression test suite.
|     test.support.bytecode_helper | Support tools for testing correct bytecode generation.
|     test.support.script_helper | Support for Python's script execution tests.
|     test.support.socket_helper | Support for socket tests.
| textwrap | Text wrapping and filling
| threading | Thread-based parallelism.
| time | Time access and conversions.
| timeit | Measure the execution time of small code snippets.
- | tkinter | Interface to Tcl/Tk for graphical user interfaces
|     tkinter.colorchooser (Tk) | Color choosing dialog
|     tkinter.commondialog (Tk) | Tkinter base class for dialogs
|     tkinter.dnd (Tk) | Tkinter drag-and-drop interface
|     tkinter.filedialog (Tk) | Dialog classes for file selection
|     tkinter.font (Tk) | Tkinter font-wrapping class
|     tkinter.messagebox (Tk) | Various types of alert dialogs
|     tkinter.scrolledtext (Tk) | Text widget with a vertical scroll bar.
|     tkinter.simpledialog (Tk) | Simple dialog windows
|     tkinter.tix | Tk Extension Widgets for Tkinter
|     tkinter.ttk | Tk themed widget set
| token | Constants representing terminal nodes of the parse tree.
| tokenize | Lexical scanner for Python source code.
| trace | Trace or track Python statement execution.
| traceback | Print or retrieve a stack traceback.
| tracemalloc | Trace memory allocations.
| tty (Unix) | Utility functions that perform common terminal control operations.
| turtle | An educational framework for simple graphics applications
| turtledemo | A viewer for example turtle scripts
| types | Names for built-in types.
| typing | Support for type hints (see :pep:`484`).
| u |
| unicodedata | Access the Unicode Database.
- | unittest | Unit testing framework for Python.
|     unittest.mock | Mock object library.
- | urllib |
|     urllib.error | Exception classes raised by urllib.request.
|     urllib.parse | Parse URLs into or assemble them from components.
|     urllib.request | Extensible library for opening URLs.
|     urllib.response | Response classes used by urllib.
|     urllib.robotparser | Load a robots.txt file and answer questions about fetchability of other URLs.
| uu | Obsoleto: Encode and decode files in uuencode format.
| uuid | UUID objects (universally unique identifiers) according to RFC 4122
| v |
| venv | Creation of virtual environments.
| w |
| warnings | Issue warning messages and control their disposition.
| wave | Provide an interface to the WAV sound format.
| weakref | Support for weak references and weak dictionaries.
| webbrowser | Easy-to-use controller for Web browsers.
| winreg (Windows) | Routines and objects for manipulating the Windows registry.
| winsound (Windows) | Access to the sound-playing machinery for Windows.
- | wsgiref | WSGI Utilities and Reference Implementation.
|     wsgiref.handlers | WSGI server/gateway base classes.
|     wsgiref.headers | WSGI response header tools.
|     wsgiref.simple_server | A simple WSGI HTTP server.
|     wsgiref.util | WSGI environment utilities.
|     wsgiref.validate | WSGI conformance checker.
| x |
| xdrlib | Obsoleto: Encoders and decoders for the External Data Representation (XDR).
- | xml | Package containing XML processing modules
|     xml.dom | Document Object Model API for Python.
|     xml.dom.minidom | Minimal Document Object Model (DOM) implementation.
|     xml.dom.pulldom | Support for building partial DOM trees from SAX events.
|     xml.etree.ElementTree | Implementation of the ElementTree API.
|     xml.parsers.expat | An interface to the Expat non-validating XML parser.
|     xml.parsers.expat.errors |
|     xml.parsers.expat.model |
|     xml.sax | Package containing SAX2 base classes and convenience functions.
|     xml.sax.handler | Base classes for SAX event handlers.
|     xml.sax.saxutils | Convenience functions and classes for use with SAX.
|     xml.sax.xmlreader | Interface which SAX-compliant XML parsers must implement.
- | xmlrpc |
|     xmlrpc.client | XML-RPC client access.
|     xmlrpc.server | Basic XML-RPC server implementations.
| z |
| zipapp | Manage executable Python zip archives
| zipfile | Read and write ZIP-format archive files.
| zipimport | Support for importing Python modules from ZIP archives.
| zlib | Low-level interface to compression and decompression routines compatible with gzip.
| zoneinfo | IANA time zone support

Índice

Índice alfabético de páginas:

Símbolos | _ | A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

Índice completo en una página (puede ser muy grande)

Download Python 3.9.18 Documentation

Last updated on: feb 07, 2024.

To download an archive containing all the documents for this version of Python in one of various formats, follow one of links in this table.

Format | Packed as .zip | Packed as .tar.bz2
PDF (US-Letter paper size) | Download (ca. 13 MiB) | Download (ca. 13 MiB)
PDF (A4 paper size) | Download (ca. 13 MiB) | Download (ca. 13 MiB)
HTML | Download (ca. 9 MiB) | Download (ca. 6 MiB)
Plain Text | Download (ca. 3 MiB) | Download (ca. 2 MiB)
EPUB | Download (ca. 5 MiB) |

These archives contain all the content in the documentation.

HTML Help (.chm) files are made available in the "Windows" section on the Python download page.

Unpacking

Unix users should download the .tar.bz2 archives; these are bzipped tar archives and can be handled in the usual way using tar and the bzip2 program. The InfoZIP unzip program can be used to handle the ZIP archives if desired. The .tar.bz2 archives provide the best compression and fastest download times.

Windows users can use the ZIP archives since those are customary on that platform. These are created on Unix using the InfoZIP zip program.

Problems

If you have comments or suggestions for the Python documentation, please send email to docs@python.org.

Índice – A

A (en el módulo re)

a la espera

A-LAW, [1]

a-LAW

a2b_base64() (en el módulo binascii)

a2b_hex() (en el módulo binascii)

a2b_hqx() (en el módulo binascii)

a2b_qp() (en el módulo binascii)

a2b_uu() (en el módulo binascii)

a85decode() (en el módulo base64)

a85encode() (en el módulo base64)

ABC (clase en abc)

abc (módulo)

ABCMeta (clase en abc)

abiflags (en el módulo sys)

abort()

(en el módulo os)

(método de asyncio.DatagramTransport)

(método de asyncio.WriteTransport)

(método de ftplib.FTP)

(método de threading.Barrier)

above() (método de curses.panel.Panel)

ABOVE_NORMAL_PRIORITY_CLASS (en el módulo subprocess)

abs

función incorporada, [1]

abs() (en el módulo operator)

(función incorporada)

(método de decimal.Context)

AbsoluteLinkError

AbsolutePathError

abspath() (en el módulo os.path)

AbstractAsyncContextManager (clase en contextlib)

AbstractBasicAuthHandler (clase en urllib.request)

AbstractChildWatcher (clase en asyncio)

abstractclassmethod() (en el módulo abc)

AbstractContextManager (clase en contextlib)

AbstractDigestAuthHandler (clase en urllib.request)

AbstractEventLoop (clase en asyncio)

AbstractEventLoopPolicy (clase en asyncio)

AbstractFormatter (clase en formatter)

abstractmethod() (en el módulo abc)

abstractproperty() (en el módulo abc)

AbstractSet (clase en typing)

abstractstaticmethod() (en el módulo abc)

AbstractWriter (clase en formatter)

accept() (método de asyncore.dispatcher)

(método de multiprocessing.connection.Listener)

(método de socket.socket)

access() (en el módulo os)

accumulate() (en el módulo itertools)

aclose() (método de agen)

(método de contextlib.AsyncExitStack)

acos() (en el módulo cmath)

(en el módulo math)

acosh() (en el módulo cmath)

(en el módulo math)

acquire() (método de _thread.lock)

(método de asyncio.Condition)

(método de asyncio.Lock)

(método de asyncio.Semaphore)

(método de logging.Handler)

(método de multiprocessing.Lock)

(método de multiprocessing.RLock)

(método de threading.Condition)

(método de threading.Lock)

(método de threading.RLock)

(método de threading.Semaphore)

acquire_lock() (en el módulo imp)

action (atributo de optparse.Option)

Action (clase en argparse)

ACTIONS (atributo de optparse.Option)

active_children() (en el módulo multiprocessing)

active_count() (en el módulo threading)

actual() (método de tkinter.font.Font)

Add (clase en ast)

add() (en el módulo audioop)

(en el módulo operator)

(método de decimal.Context)

(método de frozenset)

(método de graphlib.TopologicalSorter)

(método de mailbox.Mailbox)

(método de mailbox.Maildir)

(método de msilib.RadioButtonGroup)

(método de pstats.Stats)

(método de tarfile.TarFile)

(método de tkinter.ttk.Notebook)

add_alias() (en el módulo email.charset)

add_alternative() (método de email.message.EmailMessage)

add_argument() (método de argparse.ArgumentParser)

add_argument_group() (método de argparse.ArgumentParser)

add_attachment() (método de email.message.EmailMessage)

add_cgi_vars() (método de wsgiref.handlers.BaseHandler)

add_charset() (en el módulo email.charset)

add_child_handler() (método de asyncio.AbstractChildWatcher)

add_codec() (en el módulo email.charset)

add_cookie_header() (método de http.cookiejar.CookieJar)

add_data() (en el módulo msilib)

add_dll_directory() (en el módulo os)

add_done_callback() (método de asyncio.Future)

(método de asyncio.Task)

(método de concurrent.futures.Future)

add_fallback() (método de gettext.NullTranslations)

add_file() (método de msilib.Directory)

add_flag() (método de mailbox.MaildirMessage)

(método de mailbox.mboxMessage)

(método de mailbox.MMDFMessage)

add_flowing_data() (método de formatter.formatter)

add_folder() (método de mailbox.Maildir)

(método de mailbox.MH)

add_get_handler() (método de email.contentmanager.ContentManager)

add_handler() (método de urllib.request.OpenerDirector)

add_header() (método de email.message.EmailMessage)

(método de email.message.Message)

(método de urllib.request.Request)

(método de wsgiref.headers.Headers)

add_history() (en el módulo readline)

add_hor_rule() (método de formatter.formatter)

add_include_dir() (método de distutils.ccompiler.CCompiler)

add_label() (método de mailbox.BabylMessage)

add_label_data() (método de formatter.formatter)

add_library() (método de distutils.ccompiler.CCompiler)

add_library_dir() (método de distutils.ccompiler.CCompiler)

add_line_break() (método de formatter.formatter)

add_link_object() (método de distutils.ccompiler.CCompiler)

add_literal_data() (método de formatter.formatter)

add_mutually_exclusive_group() (método de argparse.ArgumentParser)

add_option() (método de optparse.OptionParser)

add_parent() (método de urllib.request.BaseHandler)

add_password() (método de urllib.request.HTTPPasswordMgr)

(método de urllib.request.HTTPPasswordMgrWithPriorAuth)

add_reader() (método de asyncio.loop)

add_related() (método de email.message.EmailMessage)

add_runtime_library_dir() (método de distutils.ccompiler.CCompiler)

add_section() (método de configparser.ConfigParser)

(método de configparser.RawConfigParser)

add_sequence() (método de mailbox.MHMessage)

add_set_handler() (método de email.contentmanager.ContentManager)

add_signal_handler() (método de asyncio.loop)

add_stream() (en el módulo msilib)

add_subparsers() (método de argparse.ArgumentParser)

add_tables() (en el módulo msilib)

add_type() (en el módulo mimetypes)

add_unredirected_header() (método de urllib.request.Request)

add_writer() (método de asyncio.loop)

addAsyncCleanup() (método de unittest.IsolatedAsyncioTestCase)

addaudithook() (en el módulo sys)

addch() (método de curses.window)

addClassCleanup() (método de clase de unittest.TestCase)

addCleanup() (método de unittest.TestCase)

addcomponent() (método de turtle.Shape)

addError() (método de unittest.TestResult)

addExpectedFailure() (método de unittest.TestResult)

addFailure() (método de unittest.TestResult)

addfile() (método de tarfile.TarFile)

addFilter() (método de logging.Handler)

(método de logging.Logger)

addHandler() (método de logging.Logger)

addinfourl (clase en urllib.response)

addition

addLevelName() (en el módulo logging)

addModuleCleanup() (en el módulo unittest)

addnstr() (método de curses.window)

AddPackagePath() (en el módulo modulefinder)

addr (atributo de smtpd.SMTPChannel)

addr_spec (atributo de email.headerregistry.Address)

address (atributo de email.headerregistry.SingleAddressHeader)

(atributo de multiprocessing.connection.Listener)

(atributo de multiprocessing.managers.BaseManager)

Address (clase en email.headerregistry)

address_exclude() (método de ipaddress.IPv4Network)

(método de ipaddress.IPv6Network)

address_family (atributo de socketserver.BaseServer)

address_string() (método de http.server.BaseHTTPRequestHandler)

addresses (atributo de email.headerregistry.AddressHeader)

(atributo de email.headerregistry.Group)

AddressHeader (clase en email.headerregistry)

addressof() (en el módulo ctypes)

AddressValueError

addshape() (en el módulo turtle)

addsitedir() (en el módulo site)

addSkip() (método de unittest.TestResult)

addstr() (método de curses.window)

addSubTest() (método de unittest.TestResult)

addSuccess() (método de unittest.TestResult)

addTest() (método de unittest.TestSuite)

addTests() (método de unittest.TestSuite)

addTypeEqualityFunc() (método de unittest.TestCase)

addUnexpectedSuccess() (método de unittest.TestResult)

adjust_int_max_str_digits() (en el módulo test.support)

adjusted() (método de decimal.Decimal)

adler32() (en el módulo zlib)

administrador asincrónico de contexto

administrador de contextos

ADPCM, Intel/DVI

adpcm2lin() (en el módulo audioop)

AF_ALG (en el módulo socket)

AF_CAN (en el módulo socket)

AF_INET (en el módulo socket)

AF_INET6 (en el módulo socket)

AF_LINK (en el módulo socket)

AF_PACKET (en el módulo socket)

AF_QIPCRTR (en el módulo socket)

AF_RDS (en el módulo socket)

AF_UNIX (en el módulo socket)

AF_VSOCK (en el módulo socket)

aifc (módulo)

aifc() (método de aifc.aifc)

AIFF, [1]

aiff() (método de aifc.aifc)

AIFF-C, [1]

alarm() (en el módulo signal)

alaw2lin() (en el módulo audioop)

alcances anidados

ALERT_DESCRIPTION_HANDSHAKE_FAILURE (en el módulo ssl)

ALERT_DESCRIPTION_INTERNAL_ERROR (en el módulo ssl)

AlertDescription (clase en ssl)

algorithms_available (en el módulo hashlib)

algorithms_guaranteed (en el módulo hashlib)

Alias

Generic

alias (clase en ast)

(pdb command)

alias de tipos

alignment() (en el módulo ctypes)

alive (atributo de weakref.finalize)

all() (función incorporada)

all_errors (en el módulo ftplib)

all_features (en el módulo xml.sax.handler)

all_frames (atributo de tracemalloc.Filter)

all_properties (en el módulo xml.sax.handler)

all_suffixes() (en el módulo importlib.machinery)

all_tasks() (en el módulo asyncio)

allocate_lock() (en el módulo _thread)

allocfunc (tipo C)

allow_reuse_address (atributo de socketserver.BaseServer)

allowed_domains() (método de http.cookiejar.DefaultCookiePolicy)

alt() (en el módulo curses.ascii)

ALT_DIGITS (en el módulo locale)

altsep (en el módulo os)

altzone (en el módulo time)

ALWAYS_EQ (en el módulo test.support)

ALWAYS_TYPED_ACTIONS (atributo de optparse.Option)

AMPER (en el módulo token)

AMPEREQUAL (en el módulo token)

and

bitwise

operador, [1], [2]

And (clase en ast)

and_() (en el módulo operator)

AnnAssign (clase en ast)

annotated

assignment

Annotated (en el módulo typing)

annotation (atributo de inspect.Parameter)

annotations

function, [1]

announce() (método de distutils.ccompiler.CCompiler)

anonymous

function

anotación

anotación de función

anotación de variable

answer_challenge() (en el módulo multiprocessing.connection)

anticipate_failure() (en el módulo test.support)

Any (en el módulo typing)

ANY (en el módulo unittest.mock)

any() (función incorporada)

AnyStr (en el módulo typing)

apagado del intérprete

API provisional

api_version (en el módulo sys)

apilevel (en el módulo sqlite3)

apop() (método de poplib.POP3)

APPDATA

append() (método de array.array)

(método de collections.deque)

(método de email.header.Header)

(método de imaplib.IMAP4)

(método de msilib.CAB)

(método de pipes.Template)

(método de xml.etree.ElementTree.Element)

(sequence method)

append_history_file() (en el módulo readline)

appendChild() (método de xml.dom.Node)

appendleft() (método de collections.deque)

application_uri() (en el módulo wsgiref.util)

apply (2to3 fixer)

apply() (método de multiprocessing.pool.Pool)

apply_async() (método de multiprocessing.pool.Pool)

apply_defaults() (método de inspect.BoundArguments)

architecture() (en el módulo platform)

archive (atributo de zipimport.zipimporter)

archivo binario

archivo de texto

aRepr (en el módulo reprlib)

arg (clase en ast)

argparse (módulo)

args (atributo de BaseException)

(atributo de functools.partial)

(atributo de inspect.BoundArguments)

(atributo de subprocess.CompletedProcess)

(atributo de subprocess.Popen)

(pdb command)

args_from_interpreter_flags() (en el módulo test.support)

argtypes (atributo de ctypes._FuncPtr)

argument

call semantics

difference from parameter

function

function definition

ArgumentDefaultsHelpFormatter (clase en argparse)

ArgumentError

argumento

argumento nombrado

argumento posicional

ArgumentParser (clase en argparse)

arguments (atributo de inspect.BoundArguments)

(clase en ast)

argv (en el módulo sys)

(in module sys)

arithmetic

conversion

operation, binary

operation, unary

ArithmeticError

array

módulo, [1]

array (clase en array)

Array (clase en ctypes)

array (módulo)

Array() (en el módulo multiprocessing)

(en el módulo multiprocessing.sharedctypes)

(método de multiprocessing.managers.SyncManager)

arrays

arraysize (atributo de sqlite3.Cursor)

article() (método de nntplib.NNTP)

as

except clause

import statement

palabra clave, [1], [2]

with statement

as_bytes() (método de email.message.EmailMessage)

(método de email.message.Message)

as_completed() (en el módulo asyncio)

(en el módulo concurrent.futures)

as_file() (en el módulo importlib.resources)

as_integer_ratio() (método de decimal.Decimal)

(método de float)

(método de fractions.Fraction)

(método de int)

AS_IS (en el módulo formatter)

as_posix() (método de pathlib.PurePath)

as_string() (método de email.message.EmailMessage)

(método de email.message.Message)

as_tuple() (método de decimal.Decimal)

as_uri() (método de pathlib.PurePath)

ASCII, [1]

ascii

(en el módulo re)

función incorporada

ascii() (en el módulo curses.ascii)

(función incorporada)

ascii_letters (en el módulo string)

ascii_lowercase (en el módulo string)

ascii_uppercase (en el módulo string)

asctime() (en el módulo time)

asdict() (en el módulo dataclasses)

asend() (método de agen)

asin() (en el módulo cmath)

(en el módulo math)

asinh() (en el módulo cmath)

(en el módulo math)

askcolor() (en el módulo tkinter.colorchooser)

askdirectory() (en el módulo tkinter.filedialog)

askfloat() (en el módulo tkinter.simpledialog)

askinteger() (en el módulo tkinter.simpledialog)

askokcancel() (en el módulo tkinter.messagebox)

askopenfile() (en el módulo tkinter.filedialog)

askopenfilename() (en el módulo tkinter.filedialog)

askopenfilenames() (en el módulo tkinter.filedialog)

askopenfiles() (en el módulo tkinter.filedialog)

askquestion() (en el módulo tkinter.messagebox)

askretrycancel() (en el módulo tkinter.messagebox)

asksaveasfile() (en el módulo tkinter.filedialog)

asksaveasfilename() (en el módulo tkinter.filedialog)

askstring() (en el módulo tkinter.simpledialog)

askyesno() (en el módulo tkinter.messagebox)

askyesnocancel() (en el módulo tkinter.messagebox)

assert

sentencia, [1]

Assert (clase en ast)

assert_any_await() (método de unittest.mock.AsyncMock)

assert_any_call() (método de unittest.mock.Mock)

assert_awaited() (método de unittest.mock.AsyncMock)

assert_awaited_once() (método de unittest.mock.AsyncMock)

assert_awaited_once_with() (método de unittest.mock.AsyncMock)

assert_awaited_with() (método de unittest.mock.AsyncMock)

assert_called() (método de unittest.mock.Mock)

assert_called_once() (método de unittest.mock.Mock)

assert_called_once_with() (método de unittest.mock.Mock)

assert_called_with() (método de unittest.mock.Mock)

assert_has_awaits() (método de unittest.mock.AsyncMock)

assert_has_calls() (método de unittest.mock.Mock)

assert_line_data() (método de formatter.formatter)

assert_not_awaited() (método de unittest.mock.AsyncMock)

assert_not_called() (método de unittest.mock.Mock)

assert_python_failure() (en el módulo test.support.script_helper)

assert_python_ok() (en el módulo test.support.script_helper)

assertAlmostEqual() (método de unittest.TestCase)

assertCountEqual() (método de unittest.TestCase)

assertDictEqual() (método de unittest.TestCase)

assertEqual() (método de unittest.TestCase)

assertFalse() (método de unittest.TestCase)

assertGreater() (método de unittest.TestCase)

assertGreaterEqual() (método de unittest.TestCase)

assertIn() (método de unittest.TestCase)

assertInBytecode() (método de test.support.bytecode_helper.BytecodeTestCase)

AssertionError

excepción

assertions

debugging

assertIs() (método de unittest.TestCase)

assertIsInstance() (método de unittest.TestCase)

assertIsNone() (método de unittest.TestCase)

assertIsNot() (método de unittest.TestCase)

assertIsNotNone() (método de unittest.TestCase)

assertLess() (método de unittest.TestCase)

assertLessEqual() (método de unittest.TestCase)

assertListEqual() (método de unittest.TestCase)

assertLogs() (método de unittest.TestCase)

assertMultiLineEqual() (método de unittest.TestCase)

assertNotAlmostEqual() (método de unittest.TestCase)

assertNotEqual() (método de unittest.TestCase)

assertNotIn() (método de unittest.TestCase)

assertNotInBytecode() (método de test.support.bytecode_helper.BytecodeTestCase)

assertNotIsInstance() (método de unittest.TestCase)

assertNotRegex() (método de unittest.TestCase)

assertRaises() (método de unittest.TestCase)

assertRaisesRegex() (método de unittest.TestCase)

assertRegex() (método de unittest.TestCase)

asserts (2to3 fixer)

assertSequenceEqual() (método de unittest.TestCase)

assertSetEqual() (método de unittest.TestCase)

assertTrue() (método de unittest.TestCase)

assertTupleEqual() (método de unittest.TestCase)

assertWarns() (método de unittest.TestCase)

assertWarnsRegex() (método de unittest.TestCase)

Assign (clase en ast)

assignment

annotated

attribute, [1]

augmented

class attribute

class instance attribute

slice

slicing

statement, [1]

subscript

subscription

target list

AST (clase en ast)

ast (módulo)

ast command line option

--help

--include-attributes

--indent <indent>

--mode <mode>

--no-type-comments

-a

-h

-i <indent>

-m <mode>

astimezone() (método de datetime.datetime)

astuple() (en el módulo dataclasses)

async

palabra clave

ASYNC (en el módulo token)

async def

sentencia

async for

in comprehensions

sentencia

async with

sentencia

async_chat (clase en asynchat)

async_chat.ac_in_buffer_size (en el módulo asynchat)

async_chat.ac_out_buffer_size (en el módulo asynchat)

AsyncContextManager (clase en typing)

asynccontextmanager() (en el módulo contextlib)

AsyncExitStack (clase en contextlib)

AsyncFor (clase en ast)

AsyncFunctionDef (clase en ast)

AsyncGenerator (clase en collections.abc)

(clase en typing)

AsyncGeneratorType (en el módulo types)

asynchat (módulo)

asynchronous generator

asynchronous iterator

function

asynchronous-generator

objeto

asyncio (módulo)

asyncio.subprocess.DEVNULL (variable incorporada)

asyncio.subprocess.PIPE (variable incorporada)

asyncio.subprocess.Process (clase incorporada)

asyncio.subprocess.STDOUT (variable incorporada)

AsyncIterable (clase en collections.abc)

(clase en typing)

AsyncIterator (clase en collections.abc)

(clase en typing)

AsyncMock (clase en unittest.mock)

asyncore (módulo)

AsyncResult (clase en multiprocessing.pool)

asyncSetUp() (método de unittest.IsolatedAsyncioTestCase)

asyncTearDown() (método de unittest.IsolatedAsyncioTestCase)

AsyncWith (clase en ast)

AT (en el módulo token)

at_eof() (método de asyncio.StreamReader)

atan() (en el módulo cmath)

(en el módulo math)

atan2() (en el módulo math)

atanh() (en el módulo cmath)

(en el módulo math)

ATEQUAL (en el módulo token)

atexit (atributo de weakref.finalize)

(módulo)

athrow() (método de agen)

atof() (en el módulo locale)

atoi() (en el módulo locale)

atom

atributo

attach() (método de email.message.Message)

attach_loop() (método de asyncio.AbstractChildWatcher)

attach_mock() (método de unittest.mock.Mock)

AttlistDeclHandler() (método de xml.parsers.expat.xmlparser)

attrgetter() (en el módulo operator)

attrib (atributo de xml.etree.ElementTree.Element)

attribute

assignment, [1]

assignment, class

assignment, class instance

class

class instance

deletion

generic special

reference

special

Attribute (clase en ast)

AttributeError

excepción

attributes (atributo de xml.dom.Node)

AttributesImpl (clase en xml.sax.xmlreader)

AttributesNSImpl (clase en xml.sax.xmlreader)

attroff() (método de curses.window)

attron() (método de curses.window)

attrset() (método de curses.window)

Audio Interchange File Format, [1]

AUDIO_FILE_ENCODING_ADPCM_G721 (en el módulo sunau)

AUDIO_FILE_ENCODING_ADPCM_G722 (en el módulo sunau)

AUDIO_FILE_ENCODING_ADPCM_G723_3 (en el módulo sunau)

AUDIO_FILE_ENCODING_ADPCM_G723_5 (en el módulo sunau)

AUDIO_FILE_ENCODING_ALAW_8 (en el módulo sunau)

AUDIO_FILE_ENCODING_DOUBLE (en el módulo sunau)

AUDIO_FILE_ENCODING_FLOAT (en el módulo sunau)

AUDIO_FILE_ENCODING_LINEAR_16 (en el módulo sunau)

AUDIO_FILE_ENCODING_LINEAR_24 (en el módulo sunau)

AUDIO_FILE_ENCODING_LINEAR_32 (en el módulo sunau)

AUDIO_FILE_ENCODING_LINEAR_8 (en el módulo sunau)

AUDIO_FILE_ENCODING_MULAW_8 (en el módulo sunau)

AUDIO_FILE_MAGIC (en el módulo sunau)

AUDIODEV

audioop (módulo)

audit events

audit() (en el módulo sys)

auditing

AugAssign (clase en ast)

augmented

assignment

auth() (método de ftplib.FTP_TLS)

(método de smtplib.SMTP)

authenticate() (método de imaplib.IMAP4)

AuthenticationError

authenticators() (método de netrc.netrc)

authkey (atributo de multiprocessing.Process)

auto (clase en enum)

autorange() (método de timeit.Timer)

available_timezones() (en el módulo zoneinfo)

avg() (en el módulo audioop)

avgpp() (en el módulo audioop)

avoids_symlink_attacks (atributo de shutil.rmtree)

await

in comprehensions

palabra clave, [1]

Await (clase en ast)

AWAIT (en el módulo token)

await_args (atributo de unittest.mock.AsyncMock)

await_args_list (atributo de unittest.mock.AsyncMock)

await_count (atributo de unittest.mock.AsyncMock)

Awaitable (clase en collections.abc)

(clase en typing)

Índice – B

b"

bytes literal

b'

bytes literal

b16decode() (en el módulo base64)

b16encode() (en el módulo base64)

b2a_base64() (en el módulo binascii)

b2a_hex() (en el módulo binascii)

b2a_hqx() (en el módulo binascii)

b2a_qp() (en el módulo binascii)

b2a_uu() (en el módulo binascii)

b32decode() (en el módulo base64)

b32encode() (en el módulo base64)

b64decode() (en el módulo base64)

b64encode() (en el módulo base64)

b85decode() (en el módulo base64)

b85encode() (en el módulo base64)

Babyl (clase en mailbox)

BabylMessage (clase en mailbox)

back() (en el módulo turtle)

backslash character

backslashreplace

error handler's name

backslashreplace_errors() (en el módulo codecs)

backup() (método de sqlite3.Connection)

backward() (en el módulo turtle)

BadGzipFile

BadStatusLine

BadZipFile

BadZipfile

Balloon (clase en tkinter.tix)

Barrier (clase en multiprocessing)

(clase en threading)

Barrier() (método de multiprocessing.managers.SyncManager)

base64

encoding

módulo

base64 (módulo)

base_exec_prefix (en el módulo sys)

base_prefix (en el módulo sys)

BaseCGIHandler (clase en wsgiref.handlers)

BaseCookie (clase en http.cookies)

BaseException

BaseHandler (clase en urllib.request)

(clase en wsgiref.handlers)

BaseHeader (clase en email.headerregistry)

BaseHTTPRequestHandler (clase en http.server)

BaseManager (clase en multiprocessing.managers)

basename() (en el módulo os.path)

BaseProtocol (clase en asyncio)

BaseProxy (clase en multiprocessing.managers)

BaseRequestHandler (clase en socketserver)

BaseRotatingHandler (clase en logging.handlers)

BaseSelector (clase en selectors)

BaseServer (clase en socketserver)

basestring (2to3 fixer)

BaseTransport (clase en asyncio)

basicConfig() (en el módulo logging)

BasicContext (clase en decimal)

BasicInterpolation (clase en configparser)

BasicTestRunner (clase en test.support)

baudrate() (en el módulo curses)

bbox() (método de tkinter.ttk.Treeview)

BDADDR_ANY (en el módulo socket)

BDADDR_LOCAL (en el módulo socket)

bdb

módulo

Bdb (clase en bdb)

bdb (módulo)

BdbQuit

BDFL

bdist_msi (clase en distutils.command.bdist_msi)

beep() (en el módulo curses)

Beep() (en el módulo winsound)

BEFORE_ASYNC_WITH (opcode)

begin_fill() (en el módulo turtle)

begin_poly() (en el módulo turtle)

below() (método de curses.panel.Panel)

BELOW_NORMAL_PRIORITY_CLASS (en el módulo subprocess)

Benchmarking

benchmarking, [1], [2]

betavariate() (en el módulo random)

bgcolor() (en el módulo turtle)

bgpic() (en el módulo turtle)

bias() (en el módulo audioop)

bidirectional() (en el módulo unicodedata)

bigaddrspacetest() (en el módulo test.support)

BigEndianStructure (clase en ctypes)

bigmemtest() (en el módulo test.support)

bin() (función incorporada)

binary

arithmetic operation

bitwise operation

data, packing

literals

Binary (clase en msilib)

(clase en xmlrpc.client)

binary literal

binary mode

binary semaphores

BINARY_ADD (opcode)

BINARY_AND (opcode)

BINARY_FLOOR_DIVIDE (opcode)

BINARY_LSHIFT (opcode)

BINARY_MATRIX_MULTIPLY (opcode)

BINARY_MODULO (opcode)

BINARY_MULTIPLY (opcode)

BINARY_OR (opcode)

BINARY_POWER (opcode)

BINARY_RSHIFT (opcode)

BINARY_SUBSCR (opcode)

BINARY_SUBTRACT (opcode)

BINARY_TRUE_DIVIDE (opcode)

BINARY_XOR (opcode)

binaryfunc (tipo C)

BinaryIO (clase en typing)

binascii (módulo)

bind (widgets)

bind() (método de asyncore.dispatcher)

(método de inspect.Signature)

(método de socket.socket)

bind_partial() (método de inspect.Signature)

bind_port() (en el módulo test.support.socket_helper)

bind_textdomain_codeset() (en el módulo gettext)

bind_unix_socket() (en el módulo test.support.socket_helper)

binding

global name

name, [1], [2], [3], [4], [5], [6]

bindtextdomain() (en el módulo gettext)

(en el módulo locale)

binhex

módulo

binhex (módulo)

binhex() (en el módulo binhex)

BinOp (clase en ast)

bisect (módulo)

bisect() (en el módulo bisect)

bisect_left() (en el módulo bisect)

bisect_right() (en el módulo bisect)

bit_length() (método de int)

BitAnd (clase en ast)

bitmap() (método de msilib.Dialog)

BitOr (clase en ast)

bitwise

and

operation, binary

operation, unary

operations

or

xor

BitXor (clase en ast)

bk() (en el módulo turtle)

bkgd() (método de curses.window)

bkgdset() (método de curses.window)

blake2b() (en el módulo hashlib)

blake2b, blake2s

blake2b.MAX_DIGEST_SIZE (en el módulo hashlib)

blake2b.MAX_KEY_SIZE (en el módulo hashlib)

blake2b.PERSON_SIZE (en el módulo hashlib)

blake2b.SALT_SIZE (en el módulo hashlib)

blake2s() (en el módulo hashlib)

blake2s.MAX_DIGEST_SIZE (en el módulo hashlib)

blake2s.MAX_KEY_SIZE (en el módulo hashlib)

blake2s.PERSON_SIZE (en el módulo hashlib)

blake2s.SALT_SIZE (en el módulo hashlib)

blank line

block

code

block_size (atributo de hmac.HMAC)

blocked_domains() (método de http.cookiejar.DefaultCookiePolicy)

BlockingIOError, [1]

blocksize (atributo de http.client.HTTPConnection)

bloqueo global del intérprete

BNF, [1]

body() (método de nntplib.NNTP)

(método de tkinter.simpledialog.Dialog)

body_encode() (método de email.charset.Charset)

body_encoding (atributo de email.charset.Charset)

body_line_iterator() (en el módulo email.iterators)

BOLD (en el módulo tkinter.font)

BOM (en el módulo codecs)

BOM_BE (en el módulo codecs)

BOM_LE (en el módulo codecs)

BOM_UTF16 (en el módulo codecs)

BOM_UTF16_BE (en el módulo codecs)

BOM_UTF16_LE (en el módulo codecs)

BOM_UTF32 (en el módulo codecs)

BOM_UTF32_BE (en el módulo codecs)

BOM_UTF32_LE (en el módulo codecs)

BOM_UTF8 (en el módulo codecs)

bool (clase incorporada)

Boolean

objeto, [1]

operation

operations, [1]

type

values

BOOLEAN_STATES (atributo de configparser.ConfigParser)

BoolOp (clase en ast)

bootstrap() (en el módulo ensurepip)

border() (método de curses.window)

bottom() (método de curses.panel.Panel)

bottom_panel() (en el módulo curses.panel)

BoundArguments (clase en inspect)

BoundaryError

BoundedSemaphore (clase en asyncio)

(clase en multiprocessing)

(clase en threading)

BoundedSemaphore() (método de multiprocessing.managers.SyncManager)

box() (método de curses.window)

bpformat() (método de bdb.Breakpoint)

bpprint() (método de bdb.Breakpoint)

break

sentencia, [1], [2], [3], [4]

Break (clase en ast)

break (pdb command)

break_anywhere() (método de bdb.Bdb)

break_here() (método de bdb.Bdb)

break_long_words (atributo de textwrap.TextWrapper)

break_on_hyphens (atributo de textwrap.TextWrapper)

Breakpoint (clase en bdb)

breakpoint() (función incorporada)

breakpointhook() (en el módulo sys)

breakpoints

broadcast_address (atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Network)

broken (atributo de threading.Barrier)

BrokenBarrierError

BrokenExecutor

BrokenPipeError

BrokenProcessPool

BrokenThreadPool

BROWSER, [1]

BsdDbShelf (clase en shelve)

buf (atributo de multiprocessing.shared_memory.SharedMemory)

buffer (2to3 fixer)

(atributo de io.TextIOBase)

(atributo de unittest.TestResult)

buffer interface

(see buffer protocol)

buffer object

(see buffer protocol)

buffer protocol

binary sequence types

str (built-in class)

buffer size, I/O

buffer_info() (método de array.array)

buffer_size (atributo de xml.parsers.expat.xmlparser)

buffer_text (atributo de xml.parsers.expat.xmlparser)

buffer_updated() (método de asyncio.BufferedProtocol)

buffer_used (atributo de xml.parsers.expat.xmlparser)

BufferedIOBase (clase en io)

BufferedProtocol (clase en asyncio)

BufferedRandom (clase en io)

BufferedReader (clase en io)

BufferedRWPair (clase en io)

BufferedWriter (clase en io)

BufferError

BufferingHandler (clase en logging.handlers)

BufferTooShort

bufsize() (método de ossaudiodev.oss_audio_device)

BUILD_CONST_KEY_MAP (opcode)

BUILD_LIST (opcode)

BUILD_MAP (opcode)

build_opener() (en el módulo urllib.request)

build_py (clase en distutils.command.build_py)

build_py_2to3 (clase en distutils.command.build_py)

BUILD_SET (opcode)

BUILD_SLICE (opcode)

BUILD_STRING (opcode)

BUILD_TUPLE (opcode)

built-in

method

types

built-in function

call

objeto, [1]

built-in method

call

objeto, [1]

builtin_module_names (en el módulo sys)

BuiltinFunctionType (en el módulo types)

BuiltinImporter (clase en importlib.machinery)

BuiltinMethodType (en el módulo types)

builtins

módulo, [1], [2], [3], [4]

builtins (módulo)

buscador

buscador basado en ruta

buscador de entradas de ruta

ButtonBox (clase en tkinter.tix)

buttonbox() (método de tkinter.simpledialog.Dialog)

bye() (en el módulo turtle)

byref() (en el módulo ctypes)

byte

byte-code

file, [1]

byte_compile() (en el módulo distutils.util)

bytearray

formatting

interpolation

methods

objeto, [1], [2], [3]

bytearray (clase incorporada)

bytecode, [1]

Bytecode (clase en dis)

Bytecode.codeobj (en el módulo dis)

Bytecode.first_line (en el módulo dis)

BYTECODE_SUFFIXES (en el módulo importlib.machinery)

BytecodeTestCase (clase en test.support.bytecode_helper)

byteorder (en el módulo sys)

bytes

formatting

función incorporada, [1]

interpolation

methods

objeto, [1], [2]

str (built-in class)

bytes (atributo de uuid.UUID)

(clase incorporada)

bytes literal

bytes_le (atributo de uuid.UUID)

BytesFeedParser (clase en email.parser)

BytesGenerator (clase en email.generator)

BytesHeaderParser (clase en email.parser)

BytesIO (clase en io)

BytesParser (clase en email.parser)

ByteString (clase en collections.abc)

(clase en typing)

byteswap() (en el módulo audioop)

(método de array.array)

BytesWarning

bz2 (módulo)

BZ2Compressor (clase en bz2)

BZ2Decompressor (clase en bz2)

BZ2File (clase en bz2)

Índice – C

C

language, [1], [2], [3], [4], [5]

structures

C-contiguous, [1]

C14NWriterTarget (clase en xml.etree.ElementTree)

c_bool (clase en ctypes)

C_BUILTIN (en el módulo imp)

c_byte (clase en ctypes)

c_char (clase en ctypes)

c_char_p (clase en ctypes)

c_contiguous (atributo de memoryview)

c_double (clase en ctypes)

C_EXTENSION (en el módulo imp)

c_float (clase en ctypes)

c_int (clase en ctypes)

c_int16 (clase en ctypes)

c_int32 (clase en ctypes)

c_int64 (clase en ctypes)

c_int8 (clase en ctypes)

c_long (clase en ctypes)

c_longdouble (clase en ctypes)

c_longlong (clase en ctypes)

c_short (clase en ctypes)

c_size_t (clase en ctypes)

c_ssize_t (clase en ctypes)

c_ubyte (clase en ctypes)

c_uint (clase en ctypes)

c_uint16 (clase en ctypes)

c_uint32 (clase en ctypes)

c_uint64 (clase en ctypes)

c_uint8 (clase en ctypes)

c_ulong (clase en ctypes)

c_ulonglong (clase en ctypes)

c_ushort (clase en ctypes)

c_void_p (clase en ctypes)

c_wchar (clase en ctypes)

c_wchar_p (clase en ctypes)

CAB (clase en msilib)

cache() (en el módulo functools)

cache_from_source() (en el módulo imp)

(en el módulo importlib.util)

cached (atributo de importlib.machinery.ModuleSpec)

cached_property() (en el módulo functools)

CacheFTPHandler (clase en urllib.request)

cadena con triple comilla

calcobjsize() (en el módulo test.support)

calcsize() (en el módulo struct)

calcvobjsize() (en el módulo test.support)

Calendar (clase en calendar)

calendar (módulo)

calendar() (en el módulo calendar)

call

built-in function

built-in method

class instance

class object, [1], [2]

function, [1], [2]

instance, [1]

method

procedure

user-defined function

Call (clase en ast)

call() (en el módulo subprocess)

(en el módulo unittest.mock)

call_args (atributo de unittest.mock.Mock)

call_args_list (atributo de unittest.mock.Mock)

call_at() (método de asyncio.loop)

call_count (atributo de unittest.mock.Mock)

call_exception_handler() (método de asyncio.loop)

CALL_FUNCTION (opcode)

CALL_FUNCTION_EX (opcode)

CALL_FUNCTION_KW (opcode)

call_later() (método de asyncio.loop)

call_list() (método de unittest.mock.call)

CALL_METHOD (opcode)

call_soon() (método de asyncio.loop)

call_soon_threadsafe() (método de asyncio.loop)

call_tracing() (en el módulo sys)

callable

objeto, [1]

Callable (clase en collections.abc)

(en el módulo typing)

callable() (función incorporada)

CallableProxyType (en el módulo weakref)

callback (atributo de optparse.Option)

callback() (método de contextlib.ExitStack)

callback_args (atributo de optparse.Option)

callback_kwargs (atributo de optparse.Option)

callbacks (en el módulo gc)

called (atributo de unittest.mock.Mock)

CalledProcessError

calloc()

CAN_BCM (en el módulo socket)

can_change_color() (en el módulo curses)

can_fetch() (método de urllib.robotparser.RobotFileParser)

CAN_ISOTP (en el módulo socket)

CAN_J1939 (en el módulo socket)

CAN_RAW_FD_FRAMES (en el módulo socket)

CAN_RAW_JOIN_FILTERS (en el módulo socket)

can_symlink() (en el módulo test.support)

can_write_eof() (método de asyncio.StreamWriter)

(método de asyncio.WriteTransport)

can_xattr() (en el módulo test.support)

cancel() (método de asyncio.Future)

(método de asyncio.Handle)

(método de asyncio.Task)

(método de concurrent.futures.Future)

(método de sched.scheduler)

(método de threading.Timer)

(método de tkinter.dnd.DndHandler)

cancel_command() (método de tkinter.filedialog.FileDialog)

cancel_dump_traceback_later() (en el módulo faulthandler)

cancel_join_thread() (método de multiprocessing.Queue)

cancelled() (método de asyncio.Future)

(método de asyncio.Handle)

(método de asyncio.Task)

(método de concurrent.futures.Future)

CancelledError, [1]

CannotSendHeader

CannotSendRequest

canonic() (método de bdb.Bdb)

canonical() (método de decimal.Context)

(método de decimal.Decimal)

canonicalize() (en el módulo xml.etree.ElementTree)

capa() (método de poplib.POP3)

capitalize() (método de bytearray)

(método de bytes)

(método de str)

Capsule

objeto

captured_stderr() (en el módulo test.support)

captured_stdin() (en el módulo test.support)

captured_stdout() (en el módulo test.support)

captureWarnings() (en el módulo logging)

capwords() (en el módulo string)

cargador

casefold() (método de str)

cast() (en el módulo ctypes)

(en el módulo typing)

(método de memoryview)

cat() (en el módulo nis)

catch_threading_exception() (en el módulo test.support)

catch_unraisable_exception() (en el módulo test.support)

catch_warnings (clase en warnings)

category() (en el módulo unicodedata)

cbreak() (en el módulo curses)

CC

ccc() (método de ftplib.FTP_TLS)

CCompiler (clase en distutils.ccompiler)

cdf() (método de statistics.NormalDist)

CDLL (clase en ctypes)

ceil() (en el módulo math)

(in module math)

CellType (en el módulo types)

center() (método de bytearray)

(método de bytes)

(método de str)

CERT_NONE (en el módulo ssl)

CERT_OPTIONAL (en el módulo ssl)

CERT_REQUIRED (en el módulo ssl)

cert_store_stats() (método de ssl.SSLContext)

cert_time_to_seconds() (en el módulo ssl)

CertificateError

certificates

CFLAGS, [1], [2]

CFUNCTYPE() (en el módulo ctypes)

cget() (método de tkinter.font.Font)

CGI

debugging

exceptions

protocol

security

tracebacks

cgi (módulo)

cgi_directories (atributo de http.server.CGIHTTPRequestHandler)

CGIHandler (clase en wsgiref.handlers)

CGIHTTPRequestHandler (clase en http.server)

cgitb (módulo)

CGIXMLRPCRequestHandler (clase en xmlrpc.server)

chain() (en el módulo itertools)

chaining

comparisons, [1]

exception

ChainMap (clase en collections)

(clase en typing)

change_cwd() (en el módulo test.support)

change_root() (en el módulo distutils.util)

CHANNEL_BINDING_TYPES (en el módulo ssl)

channel_class (atributo de smtpd.SMTPServer)

channels() (método de ossaudiodev.oss_audio_device)

CHAR_MAX (en el módulo locale)

character, [1], [2]

CharacterDataHandler() (método de xml.parsers.expat.xmlparser)

characters() (método de xml.sax.handler.ContentHandler)

characters_written (atributo de BlockingIOError)

Charset (clase en email.charset)

charset() (método de gettext.NullTranslations)

chdir() (en el módulo os)

check (atributo de lzma.LZMADecompressor)

check() (en el módulo tabnanny)

(método de imaplib.IMAP4)

check__all__() (en el módulo test.support)

check_call() (en el módulo subprocess)

check_environ() (en el módulo distutils.util)

check_free_after_iterating() (en el módulo test.support)

check_hostname (atributo de ssl.SSLContext)

check_impl_detail() (en el módulo test.support)

check_no_resource_warning() (en el módulo test.support)

check_output() (en el módulo subprocess)

(método de doctest.OutputChecker)

check_returncode() (método de subprocess.CompletedProcess)

check_syntax_error() (en el módulo test.support)

check_syntax_warning() (en el módulo test.support)

check_unused_args() (método de string.Formatter)

check_warnings() (en el módulo test.support)

checkbox() (método de msilib.Dialog)

checkcache() (en el módulo linecache)

CHECKED_HASH (atributo de py_compile.PycInvalidationMode)

checkfuncname() (en el módulo bdb)

CheckList (clase en tkinter.tix)

checksizeof() (en el módulo test.support)

checksum

Cyclic Redundancy Check

chflags() (en el módulo os)

chgat() (método de curses.window)

childNodes (atributo de xml.dom.Node)

ChildProcessError

children (atributo de pyclbr.Class)

(atributo de pyclbr.Function)

(atributo de tkinter.Tk)

chmod() (en el módulo os)

(método de pathlib.Path)

choice() (en el módulo random)

(en el módulo secrets)

choices (atributo de optparse.Option)

choices() (en el módulo random)

Chooser (clase en tkinter.colorchooser)

chown() (en el módulo os)

(en el módulo shutil)

chr

función incorporada

chr() (función incorporada)

chroot() (en el módulo os)

Chunk (clase en chunk)

chunk (módulo)

cipher

DES

cipher() (método de ssl.SSLSocket)

circle() (en el módulo turtle)

CIRCUMFLEX (en el módulo token)

CIRCUMFLEXEQUAL (en el módulo token)

Clamped (clase en decimal)

clase

clase base abstracta

clase de nuevo estilo

class

attribute

attribute assignment

body

constructor

definition, [1]

instance

name

objeto, [1], [2]

sentencia

Class (clase en symtable)

Class browser

class instance

attribute

attribute assignment

call

objeto, [1], [2]

class object

call, [1], [2]

ClassDef (clase en ast)

classmethod

función incorporada

classmethod() (función incorporada)

ClassMethodDescriptorType (en el módulo types)

ClassVar (en el módulo typing)

clause

CLD_CONTINUED (en el módulo os)

CLD_DUMPED (en el módulo os)

CLD_EXITED (en el módulo os)

CLD_KILLED (en el módulo os)

CLD_STOPPED (en el módulo os)

CLD_TRAPPED (en el módulo os)

clean() (método de mailbox.Maildir)

cleandoc() (en el módulo inspect)

CleanImport (clase en test.support)

cleanup functions

clear (pdb command)

Clear Breakpoint

clear() (en el módulo turtle)

(método de asyncio.Event)

(método de collections.deque)

(método de curses.window)

(método de dict)

(método de email.message.EmailMessage)

(método de frame)

(método de frozenset)

(método de http.cookiejar.CookieJar)

(método de mailbox.Mailbox)

(método de threading.Event)

(método de xml.etree.ElementTree.Element)

(sequence method)

clear_all_breaks() (método de bdb.Bdb)

clear_all_file_breaks() (método de bdb.Bdb)

clear_bpbynumber() (método de bdb.Bdb)

clear_break() (método de bdb.Bdb)

clear_cache() (en el módulo filecmp)

(método de clase de zoneinfo.ZoneInfo)

clear_content() (método de email.message.EmailMessage)

clear_flags() (método de decimal.Context)

clear_frames() (en el módulo traceback)

clear_history() (en el módulo readline)

clear_session_cookies() (método de http.cookiejar.CookieJar)

clear_traces() (en el módulo tracemalloc)

clear_traps() (método de decimal.Context)

clearcache() (en el módulo linecache)

ClearData() (método de msilib.Record)

clearok() (método de curses.window)

clearscreen() (en el módulo turtle)

clearstamp() (en el módulo turtle)

clearstamps() (en el módulo turtle)

Client() (en el módulo multiprocessing.connection)

client_address (atributo de http.server.BaseHTTPRequestHandler)

CLOCK_BOOTTIME (en el módulo time)

clock_getres() (en el módulo time)

clock_gettime() (en el módulo time)

clock_gettime_ns() (en el módulo time)

CLOCK_HIGHRES (en el módulo time)

CLOCK_MONOTONIC (en el módulo time)

CLOCK_MONOTONIC_RAW (en el módulo time)

CLOCK_PROCESS_CPUTIME_ID (en el módulo time)

CLOCK_PROF (en el módulo time)

CLOCK_REALTIME (en el módulo time)

clock_settime() (en el módulo time)

clock_settime_ns() (en el módulo time)

CLOCK_TAI (en el módulo time)

CLOCK_THREAD_CPUTIME_ID (en el módulo time)

CLOCK_UPTIME (en el módulo time)

CLOCK_UPTIME_RAW (en el módulo time)

clone() (en el módulo turtle)

(método de email.generator.BytesGenerator)

(método de email.generator.Generator)

(método de email.policy.Policy)

(método de pipes.Template)

cloneNode() (método de xml.dom.Node)

close() (en el módulo fileinput)

(en el módulo os)

(en el módulo socket)

(in module os)

(método de aifc.aifc)

(método de asyncio.AbstractChildWatcher)

(método de asyncio.BaseTransport)

(método de asyncio.loop)

(método de asyncio.Server)

(método de asyncio.StreamWriter)

(método de asyncio.SubprocessTransport)

(método de asyncore.dispatcher)

(método de chunk.Chunk)

(método de contextlib.ExitStack)

(método de coroutine)

(método de dbm.dumb.dumbdbm)

(método de dbm.gnu.gdbm)

(método de dbm.ndbm.ndbm)

(método de distutils.text_file.TextFile)

(método de email.parser.BytesFeedParser)

(método de ftplib.FTP)

(método de generator)

(método de html.parser.HTMLParser)

(método de http.client.HTTPConnection)

(método de imaplib.IMAP4)

(método de io.IOBase)

(método de logging.FileHandler)

(método de logging.Handler)

(método de logging.handlers.MemoryHandler)

(método de logging.handlers.NTEventLogHandler)

(método de logging.handlers.SocketHandler)

(método de logging.handlers.SysLogHandler)

(método de mailbox.Mailbox)

(método de mailbox.Maildir)

(método de mailbox.MH)

(método de mmap.mmap)

Close() (método de msilib.Database)

(método de msilib.View)

close() (método de multiprocessing.connection.Connection)

(método de multiprocessing.connection.Listener)

(método de multiprocessing.pool.Pool)

(método de multiprocessing.Process)

(método de multiprocessing.Queue)

(método de multiprocessing.shared_memory.SharedMemory)

(método de multiprocessing.SimpleQueue)

(método de os.scandir)

(método de ossaudiodev.oss_audio_device)

(método de ossaudiodev.oss_mixer_device)

(método de select.devpoll)

(método de select.epoll)

(método de select.kqueue)

(método de selectors.BaseSelector)

(método de shelve.Shelf)

(método de socket.socket)

(método de sqlite3.Connection)

(método de sqlite3.Cursor)

(método de sunau.AU_read)

(método de sunau.AU_write)

(método de tarfile.TarFile)

(método de telnetlib.Telnet)

(método de urllib.request.BaseHandler)

(método de wave.Wave_read)

(método de wave.Wave_write)

Close() (método de winreg.PyHKEY)

close() (método de xml.etree.ElementTree.TreeBuilder)

(método de xml.etree.ElementTree.XMLParser)

(método de xml.etree.ElementTree.XMLPullParser)

(método de xml.sax.xmlreader.IncrementalParser)

(método de zipfile.ZipFile)

close_connection (atributo de http.server.BaseHTTPRequestHandler)

close_when_done() (método de asynchat.async_chat)

closed (atributo de http.client.HTTPResponse)

(atributo de io.IOBase)

(atributo de mmap.mmap)

(atributo de ossaudiodev.oss_audio_device)

(atributo de select.devpoll)

(atributo de select.epoll)

(atributo de select.kqueue)

CloseKey() (en el módulo winreg)

closelog() (en el módulo syslog)

closerange() (en el módulo os)

closing() (en el módulo contextlib)

clrtobot() (método de curses.window)

clrtoeol() (método de curses.window)

cmath (módulo)

cmd

módulo

cmd (atributo de subprocess.CalledProcessError)

(atributo de subprocess.TimeoutExpired)

Cmd (clase en cmd)

cmd (módulo)

cmdloop() (método de cmd.Cmd)

cmdqueue (atributo de cmd.Cmd)

cmp() (en el módulo filecmp)

cmp_op (en el módulo dis)

cmp_to_key() (en el módulo functools)

cmpfiles() (en el módulo filecmp)

CMSG_LEN() (en el módulo socket)

CMSG_SPACE() (en el módulo socket)

co_argcount (code object attribute)

CO_ASYNC_GENERATOR (en el módulo inspect)

co_cellvars (code object attribute)

co_code (code object attribute)

co_consts (code object attribute)

CO_COROUTINE (en el módulo inspect)

co_filename (code object attribute)

co_firstlineno (code object attribute)

co_flags (code object attribute)

co_freevars (code object attribute)

CO_FUTURE_DIVISION (variable C)

CO_GENERATOR (en el módulo inspect)

CO_ITERABLE_COROUTINE (en el módulo inspect)

co_kwonlyargcount (code object attribute)

co_lnotab (code object attribute)

co_name (code object attribute)

co_names (code object attribute)

CO_NESTED (en el módulo inspect)

CO_NEWLOCALS (en el módulo inspect)

co_nlocals (code object attribute)

CO_NOFREE (en el módulo inspect)

CO_OPTIMIZED (en el módulo inspect)

co_posonlyargcount (code object attribute)

co_stacksize (code object attribute)

CO_VARARGS (en el módulo inspect)

CO_VARKEYWORDS (en el módulo inspect)

co_varnames (code object attribute)

code

block

code (atributo de SystemExit)

(atributo de urllib.error.HTTPError)

(atributo de urllib.response.addinfourl)

(atributo de xml.etree.ElementTree.ParseError)

(atributo de xml.parsers.expat.ExpatError)

(módulo)

code object, [1], [2], [3]

code_info() (en el módulo dis)

CodecInfo (clase en codecs)

Codecs

decode

encode

codecs (módulo)

coded_value (atributo de http.cookies.Morsel)

codeop (módulo)

codepoint2name (en el módulo html.entities)

codes (en el módulo xml.parsers.expat.errors)

CODESET (en el módulo locale)

CodeType (clase en types)

codificación de texto

coding

style

coerción

col_offset (atributo de ast.AST)

collapse_addresses() (en el módulo ipaddress)

collapse_rfc2231_value() (en el módulo email.utils)

collect() (en el módulo gc)

collect_incoming_data() (método de asynchat.async_chat)

Collection (clase en collections.abc)

(clase en typing)

collections (módulo)

collections.abc (módulo)

colno (atributo de json.JSONDecodeError)

(atributo de re.error)

COLON (en el módulo token)

COLONEQUAL (en el módulo token)

color() (en el módulo turtle)

color_content() (en el módulo curses)

color_pair() (en el módulo curses)

colormode() (en el módulo turtle)

colorsys (módulo)

COLS, [1]

column() (método de tkinter.ttk.Treeview)

COLUMNS, [1]

columns (atributo de os.terminal_size)

comb() (en el módulo math)

combinations() (en el módulo itertools)

combinations_with_replacement() (en el módulo itertools)

combine() (método de clase de datetime.datetime)

combining() (en el módulo unicodedata)

ComboBox (clase en tkinter.tix)

Combobox (clase en tkinter.ttk)

comma

trailing

COMMA (en el módulo token)

command (atributo de http.server.BaseHTTPRequestHandler)

Command (clase en distutils.cmd)

(clase en distutils.core)

command line

command line option

--check-hash-based-pycs default|always|never

--help

--version

-?

-b

-B

-c <command>

-d

-E

-h

-i

-I

-J

-m <module-name>

-O

-OO

-q

-R

-s

-S

-u

-V

-v

-W arg

-x

-X

CommandCompiler (clase en codeop)

commands (pdb command)

comment

(atributo de http.cookiejar.Cookie)

(atributo de zipfile.ZipFile)

(atributo de zipfile.ZipInfo)

COMMENT (en el módulo token)

Comment() (en el módulo xml.etree.ElementTree)

comment() (método de xml.etree.ElementTree.TreeBuilder)

comment_url (atributo de http.cookiejar.Cookie)

commenters (atributo de shlex.shlex)

CommentHandler() (método de xml.parsers.expat.xmlparser)

commit() (método de msilib.CAB)

Commit() (método de msilib.Database)

commit() (método de sqlite3.Connection)

common (atributo de filecmp.dircmp)

Common Gateway Interface

common_dirs (atributo de filecmp.dircmp)

common_files (atributo de filecmp.dircmp)

common_funny (atributo de filecmp.dircmp)

common_types (en el módulo mimetypes)

commonpath() (en el módulo os.path)

commonprefix() (en el módulo os.path)

communicate() (método de asyncio.subprocess.Process)

(método de subprocess.Popen)

Compare (clase en ast)

compare() (método de decimal.Context)

(método de decimal.Decimal)

(método de difflib.Differ)

compare_digest() (en el módulo hmac)

(en el módulo secrets)

compare_networks() (método de ipaddress.IPv4Network)

(método de ipaddress.IPv6Network)

COMPARE_OP (opcode)

compare_signal() (método de decimal.Context)

(método de decimal.Decimal)

compare_to() (método de tracemalloc.Snapshot)

compare_total() (método de decimal.Context)

(método de decimal.Decimal)

compare_total_mag() (método de decimal.Context)

(método de decimal.Decimal)

comparing

objects

comparison

operator

COMPARISON_FLAGS (en el módulo doctest)

comparisons

chaining, [1]

Compat32 (clase en email.policy)

compat32 (en el módulo email.policy)

compile

función incorporada, [1], [2], [3], [4]

Compile (clase en codeop)

compile() (en el módulo py_compile)

(en el módulo re)

(función incorporada)

(método de distutils.ccompiler.CCompiler)

(método de parser.ST)

compile_command() (en el módulo code)

(en el módulo codeop)

compile_dir() (en el módulo compileall)

compile_file() (en el módulo compileall)

compile_path() (en el módulo compileall)

compileall (módulo)

compileall command line option

--hardlink-dupes

--invalidation-mode [timestamp|checked-hash|unchecked-hash]

-b

-d destdir

-e dir

-f

-i list

-j N

-l

-o level

-p prepend_prefix

-q

-r

-s strip_prefix

-x regex

directory ...

file ...

compilest() (en el módulo parser)

complete() (método de rlcompleter.Completer)

complete_statement() (en el módulo sqlite3)

completedefault() (método de cmd.Cmd)

CompletedProcess (clase en subprocess)

complex

función incorporada, [1]

number

objeto

Complex (clase en numbers)

complex (clase incorporada)

complex literal

complex number

literals

objeto, [1]

compound

statement

comprehension (clase en ast)

comprehensions

dictionary

list

set

comprensión de conjuntos

comprensión de diccionarios

comprensión de listas

compress() (en el módulo bz2)

(en el módulo gzip)

(en el módulo itertools)

(en el módulo lzma)

(en el módulo zlib)

(método de bz2.BZ2Compressor)

(método de lzma.LZMACompressor)

(método de zlib.Compress)

compress_size (atributo de zipfile.ZipInfo)

compress_type (atributo de zipfile.ZipInfo)

compressed (atributo de ipaddress.IPv4Address)

(atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Address)

(atributo de ipaddress.IPv6Network)

compression() (método de ssl.SSLSocket)

CompressionError

compressobj() (en el módulo zlib)

COMSPEC, [1]

concat() (en el módulo operator)

concatenation

operation

concurrent.futures (módulo)

Condition (clase en asyncio)

(clase en multiprocessing)

(clase en threading)

condition (pdb command)

condition() (método de msilib.Control)

Condition() (método de multiprocessing.managers.SyncManager)

Conditional

expression

conditional

expression

config() (método de tkinter.font.Font)

ConfigParser (clase en configparser)

configparser (módulo)

configuration

file

file, debugger

file, path

configuration information

configure() (método de tkinter.ttk.Style)

configure_mock() (método de unittest.mock.Mock)

confstr() (en el módulo os)

confstr_names (en el módulo os)

conjugate() (complex number method)

(método de decimal.Decimal)

(método de numbers.Complex)

conn (atributo de smtpd.SMTPChannel)

connect() (en el módulo sqlite3)

(método de asyncore.dispatcher)

(método de ftplib.FTP)

(método de http.client.HTTPConnection)

(método de multiprocessing.managers.BaseManager)

(método de smtplib.SMTP)

(método de socket.socket)

connect_accepted_socket() (método de asyncio.loop)

connect_ex() (método de socket.socket)

connect_read_pipe() (método de asyncio.loop)

connect_write_pipe() (método de asyncio.loop)

connection (atributo de sqlite3.Cursor)

Connection (clase en multiprocessing.connection)

(clase en sqlite3)

connection_lost() (método de asyncio.BaseProtocol)

connection_made() (método de asyncio.BaseProtocol)

ConnectionAbortedError

ConnectionError

ConnectionRefusedError

ConnectionResetError

ConnectRegistry() (en el módulo winreg)

const (atributo de optparse.Option)

constant

Constant (clase en ast)

constructor

class

constructor() (en el módulo copyreg)

consumed (atributo de asyncio.LimitOverrunError)

contador de referencias

container, [1]

iteration over

Container (clase en collections.abc)

(clase en typing)

contains() (en el módulo operator)

CONTAINS_OP (opcode)

content type

MIME

content_disposition (atributo de email.headerregistry.ContentDispositionHeader)

content_manager (atributo de email.policy.EmailPolicy)

content_type (atributo de email.headerregistry.ContentTypeHeader)

ContentDispositionHeader (clase en email.headerregistry)

ContentHandler (clase en xml.sax.handler)

ContentManager (clase en email.contentmanager)

contents (atributo de ctypes._Pointer)

contents() (en el módulo importlib.resources)

(método de importlib.abc.ResourceReader)

ContentTooShortError

ContentTransferEncoding (clase en email.headerregistry)

ContentTypeHeader (clase en email.headerregistry)

context (atributo de ssl.SSLSocket)

Context (clase en contextvars)

(clase en decimal)

context management protocol

context manager, [1]

context_diff() (en el módulo difflib)

ContextDecorator (clase en contextlib)

contextlib (módulo)

ContextManager (clase en typing)

contextmanager() (en el módulo contextlib)

ContextVar (clase en contextvars)

contextvars (módulo)

contiguo

contiguous

(atributo de memoryview)

continue

sentencia, [1], [2], [3], [4]

Continue (clase en ast)

continue (pdb command)

Control (clase en msilib)

(clase en tkinter.tix)

control() (método de msilib.Dialog)

(método de select.kqueue)

controlnames (en el módulo curses.ascii)

controls() (método de ossaudiodev.oss_mixer_device)

conversion

arithmetic

string, [1]

ConversionError

conversions

numeric

convert_arg_line_to_args() (método de argparse.ArgumentParser)

convert_field() (método de string.Formatter)

convert_path() (en el módulo distutils.util)

Cookie (clase en http.cookiejar)

CookieError

cookiejar (atributo de urllib.request.HTTPCookieProcessor)

CookieJar (clase en http.cookiejar)

CookiePolicy (clase en http.cookiejar)

Coordinated Universal Time

Copy

copy

módulo

protocol

copy (módulo)

copy() (en el módulo copy)

(en el módulo multiprocessing.sharedctypes)

(en el módulo shutil)

(método de collections.deque)

(método de contextvars.Context)

(método de decimal.Context)

(método de dict)

(método de frozenset)

(método de hashlib.hash)

(método de hmac.HMAC)

(método de http.cookies.Morsel)

(método de imaplib.IMAP4)

(método de pipes.Template)

(método de tkinter.font.Font)

(método de types.MappingProxyType)

(método de zlib.Compress)

(método de zlib.Decompress)

(sequence method)

copy2() (en el módulo shutil)

copy_abs() (método de decimal.Context)

(método de decimal.Decimal)

copy_context() (en el módulo contextvars)

copy_decimal() (método de decimal.Context)

copy_file() (en el módulo distutils.file_util)

copy_file_range() (en el módulo os)

copy_location() (en el módulo ast)

copy_negate() (método de decimal.Context)

(método de decimal.Decimal)

copy_sign() (método de decimal.Context)

(método de decimal.Decimal)

copy_tree() (en el módulo distutils.dir_util)

copyfile() (en el módulo shutil)

copyfileobj() (en el módulo shutil)

copying files

copymode() (en el módulo shutil)

copyreg (módulo)

copyright (en el módulo sys)

(in module sys)

(variable incorporada)

copysign() (en el módulo math)

copystat() (en el módulo shutil)

copytree() (en el módulo shutil)

coroutine, [1]

function

Coroutine (clase en collections.abc)

(clase en typing)

coroutine() (en el módulo asyncio)

(en el módulo types)

CoroutineType (en el módulo types)

corrutina

cos() (en el módulo cmath)

(en el módulo math)

cosh() (en el módulo cmath)

(en el módulo math)

count (atributo de tracemalloc.Statistic)

(atributo de tracemalloc.StatisticDiff)

count() (en el módulo itertools)

(método de array.array)

(método de bytearray)

(método de bytes)

(método de collections.deque)

(método de multiprocessing.shared_memory.ShareableList)

(método de str)

(sequence method)

count_diff (atributo de tracemalloc.StatisticDiff)

Counter (clase en collections)

(clase en typing)

countOf() (en el módulo operator)

countTestCases() (método de unittest.TestCase)

(método de unittest.TestSuite)

CoverageResults (clase en trace)

CPP

CPPFLAGS

cProfile (módulo)

CPU time, [1]

cpu_count() (en el módulo multiprocessing)

(en el módulo os)

CPython

cpython_only() (en el módulo test.support)

crawl_delay() (método de urllib.robotparser.RobotFileParser)

CRC (atributo de zipfile.ZipInfo)

crc32() (en el módulo binascii)

(en el módulo zlib)

crc_hqx() (en el módulo binascii)

create() (en el módulo venv)

(método de imaplib.IMAP4)

(método de venv.EnvBuilder)

create_aggregate() (método de sqlite3.Connection)

create_archive() (en el módulo zipapp)

create_autospec() (en el módulo unittest.mock)

CREATE_BREAKAWAY_FROM_JOB (en el módulo subprocess)

create_collation() (método de sqlite3.Connection)

create_configuration() (método de venv.EnvBuilder)

create_connection() (en el módulo socket)

(método de asyncio.loop)

create_datagram_endpoint() (método de asyncio.loop)

create_decimal() (método de decimal.Context)

create_decimal_from_float() (método de decimal.Context)

create_default_context() (en el módulo ssl)

CREATE_DEFAULT_ERROR_MODE (en el módulo subprocess)

create_empty_file() (en el módulo test.support)

create_function() (método de sqlite3.Connection)

create_future() (método de asyncio.loop)

create_module (función C)

create_module() (método de importlib.abc.Loader)

(método de importlib.machinery.ExtensionFileLoader)

CREATE_NEW_CONSOLE (en el módulo subprocess)

CREATE_NEW_PROCESS_GROUP (en el módulo subprocess)

CREATE_NO_WINDOW (en el módulo subprocess)

create_server() (en el módulo socket)

(método de asyncio.loop)

create_shortcut() (función incorporada)

create_socket() (método de asyncore.dispatcher)

create_static_lib() (método de distutils.ccompiler.CCompiler)

create_stats() (método de profile.Profile)

create_string_buffer() (en el módulo ctypes)

create_subprocess_exec() (en el módulo asyncio)

create_subprocess_shell() (en el módulo asyncio)

create_system (atributo de zipfile.ZipInfo)

create_task() (en el módulo asyncio)

(método de asyncio.loop)

create_tree() (en el módulo distutils.dir_util)

create_unicode_buffer() (en el módulo ctypes)

create_unix_connection() (método de asyncio.loop)

create_unix_server() (método de asyncio.loop)

create_version (atributo de zipfile.ZipInfo)

createAttribute() (método de xml.dom.Document)

createAttributeNS() (método de xml.dom.Document)

createComment() (método de xml.dom.Document)

createDocument() (método de xml.dom.DOMImplementation)

createDocumentType() (método de xml.dom.DOMImplementation)

createElement() (método de xml.dom.Document)

createElementNS() (método de xml.dom.Document)

createfilehandler() (método de tkinter.Widget.tk)

CreateKey() (en el módulo winreg)

CreateKeyEx() (en el módulo winreg)

createLock() (método de logging.Handler)

(método de logging.NullHandler)

createProcessingInstruction() (método de xml.dom.Document)

CreateRecord() (en el módulo msilib)

createSocket() (método de logging.handlers.SocketHandler)

createTextNode() (método de xml.dom.Document)

credits (variable incorporada)

critical() (en el módulo logging)

(método de logging.Logger)

CRNCYSTR (en el módulo locale)

cross() (en el módulo audioop)

crypt

módulo

crypt (módulo)

crypt() (en el módulo crypt)

crypt(3), [1], [2]

cryptography

cssclass_month (atributo de calendar.HTMLCalendar)

cssclass_month_head (atributo de calendar.HTMLCalendar)

cssclass_noday (atributo de calendar.HTMLCalendar)

cssclass_year (atributo de calendar.HTMLCalendar)

cssclass_year_head (atributo de calendar.HTMLCalendar)

cssclasses (atributo de calendar.HTMLCalendar)

cssclasses_weekday_head (atributo de calendar.HTMLCalendar)

csv

(módulo)

cte (atributo de email.headerregistry.ContentTransferEncoding)

cte_type (atributo de email.policy.Policy)

ctermid() (en el módulo os)

ctime() (en el módulo time)

(método de datetime.date)

(método de datetime.datetime)

ctrl() (en el módulo curses.ascii)

CTRL_BREAK_EVENT (en el módulo signal)

CTRL_C_EVENT (en el módulo signal)

ctypes (módulo)

curdir (en el módulo os)

currency() (en el módulo locale)

current() (método de tkinter.ttk.Combobox)

current_process() (en el módulo multiprocessing)

current_task() (en el módulo asyncio)

current_thread() (en el módulo threading)

CurrentByteIndex (atributo de xml.parsers.expat.xmlparser)

CurrentColumnNumber (atributo de xml.parsers.expat.xmlparser)

currentframe() (en el módulo inspect)

CurrentLineNumber (atributo de xml.parsers.expat.xmlparser)

curs_set() (en el módulo curses)

curses (módulo)

curses.ascii (módulo)

curses.panel (módulo)

curses.textpad (módulo)

Cursor (clase en sqlite3)

cursor() (método de sqlite3.Connection)

cursyncup() (método de curses.window)

customize_compiler() (en el módulo distutils.sysconfig)

Cut

cwd() (método de clase de pathlib.Path)

(método de ftplib.FTP)

cycle() (en el módulo itertools)

CycleError

Cyclic Redundancy Check

Índice – D

D_FMT (en el módulo locale)

D_T_FMT (en el módulo locale)

daemon (atributo de multiprocessing.Process)

(atributo de threading.Thread)

dangling

else

data

packing binary

tabular

type

type, immutable

data (atributo de collections.UserDict)

(atributo de collections.UserList)

(atributo de collections.UserString)

(atributo de select.kevent)

(atributo de selectors.SelectorKey)

(atributo de urllib.request.Request)

(atributo de xml.dom.Comment)

(atributo de xml.dom.ProcessingInstruction)

(atributo de xml.dom.Text)

(atributo de xmlrpc.client.Binary)

data() (método de xml.etree.ElementTree.TreeBuilder)

data_filter() (en el módulo tarfile)

data_open() (método de urllib.request.DataHandler)

data_received() (método de asyncio.Protocol)

database

Unicode

DatabaseError

databases

dataclass() (en el módulo dataclasses)

dataclasses (módulo)

datagram_received() (método de asyncio.DatagramProtocol)

DatagramHandler (clase en logging.handlers)

DatagramProtocol (clase en asyncio)

DatagramRequestHandler (clase en socketserver)

DatagramTransport (clase en asyncio)

DataHandler (clase en urllib.request)

date (clase en datetime)

date() (método de datetime.datetime)

(método de nntplib.NNTP)

date_time (atributo de zipfile.ZipInfo)

date_time_string() (método de http.server.BaseHTTPRequestHandler)

DateHeader (clase en email.headerregistry)

datetime (atributo de email.headerregistry.DateHeader)

(clase en datetime)

DateTime (clase en xmlrpc.client)

datetime (módulo)

datum

day (atributo de datetime.date)

(atributo de datetime.datetime)

day_abbr (en el módulo calendar)

day_name (en el módulo calendar)

daylight (en el módulo time)

Daylight Saving Time

DbfilenameShelf (clase en shelve)

dbm (módulo)

dbm.dumb (módulo)

dbm.gnu

módulo, [1]

dbm.gnu (módulo)

dbm.ndbm

módulo, [1]

dbm.ndbm (módulo)

dcgettext() (en el módulo locale)

deallocation, object

debug (atributo de imaplib.IMAP4)

(atributo de shlex.shlex)

(atributo de zipfile.ZipFile)

DEBUG (en el módulo re)

debug (pdb command)

debug() (en el módulo doctest)

(en el módulo logging)

(método de logging.Logger)

(método de pipes.Template)

(método de unittest.TestCase)

(método de unittest.TestSuite)

DEBUG_BYTECODE_SUFFIXES (en el módulo importlib.machinery)

DEBUG_COLLECTABLE (en el módulo gc)

DEBUG_LEAK (en el módulo gc)

debug_print() (método de distutils.ccompiler.CCompiler)

DEBUG_SAVEALL (en el módulo gc)

debug_src() (en el módulo doctest)

DEBUG_STATS (en el módulo gc)

DEBUG_UNCOLLECTABLE (en el módulo gc)

debugger, [1], [2]

configuration file

debugging

assertions

CGI

DebuggingServer (clase en smtpd)

debuglevel (atributo de http.client.HTTPResponse)

DebugRunner (clase en doctest)

Decimal (clase en decimal)

decimal (módulo)

decimal literal

decimal() (en el módulo unicodedata)

DecimalException (clase en decimal)

decode

Codecs

decode (atributo de codecs.CodecInfo)

decode() (en el módulo base64)

(en el módulo codecs)

(en el módulo quopri)

(en el módulo uu)

(método de bytearray)

(método de bytes)

(método de codecs.Codec)

(método de codecs.IncrementalDecoder)

(método de json.JSONDecoder)

(método de xmlrpc.client.Binary)

(método de xmlrpc.client.DateTime)

decode_header() (en el módulo email.header)

(en el módulo nntplib)

decode_params() (en el módulo email.utils)

decode_rfc2231() (en el módulo email.utils)

decode_source() (en el módulo importlib.util)

decodebytes() (en el módulo base64)

DecodedGenerator (clase en email.generator)

decodestring() (en el módulo quopri)

decomposition() (en el módulo unicodedata)

decompress() (en el módulo bz2)

(en el módulo gzip)

(en el módulo lzma)

(en el módulo zlib)

(método de bz2.BZ2Decompressor)

(método de lzma.LZMADecompressor)

(método de zlib.Decompress)

decompressobj() (en el módulo zlib)

decorador

DEDENT (en el módulo token)

DEDENT token, [1]

dedent() (en el módulo textwrap)

deepcopy() (en el módulo copy)

def

sentencia

def_prog_mode() (en el módulo curses)

def_shell_mode() (en el módulo curses)

default

parameter value

default (atributo de inspect.Parameter)

(atributo de optparse.Option)

(en el módulo email.policy)

DEFAULT (en el módulo unittest.mock)

default() (método de cmd.Cmd)

(método de json.JSONEncoder)

DEFAULT_BUFFER_SIZE (en el módulo io)

default_bufsize (en el módulo xml.dom.pulldom)

default_exception_handler() (método de asyncio.loop)

default_factory (atributo de collections.defaultdict)

DEFAULT_FORMAT (en el módulo tarfile)

DEFAULT_IGNORES (en el módulo filecmp)

default_open() (método de urllib.request.BaseHandler)

DEFAULT_PROTOCOL (en el módulo pickle)

default_timer() (en el módulo timeit)

DefaultContext (clase en decimal)

DefaultCookiePolicy (clase en http.cookiejar)

defaultdict (clase en collections)

DefaultDict (clase en typing)

DefaultEventLoopPolicy (clase en asyncio)

DefaultHandler() (método de xml.parsers.expat.xmlparser)

DefaultHandlerExpand() (método de xml.parsers.expat.xmlparser)

defaults() (método de configparser.ConfigParser)

DefaultSelector (clase en selectors)

defaultTestLoader (en el módulo unittest)

defaultTestResult() (método de unittest.TestCase)

defects (atributo de email.headerregistry.BaseHeader)

(atributo de email.message.EmailMessage)

(atributo de email.message.Message)

define_macro() (método de distutils.ccompiler.CCompiler)

definition

class, [1]

function, [1]

defpath (en el módulo os)

DefragResult (clase en urllib.parse)

DefragResultBytes (clase en urllib.parse)

degrees() (en el módulo math)

(en el módulo turtle)

del

sentencia, [1], [2], [3]

Del (clase en ast)

del_param() (método de email.message.EmailMessage)

(método de email.message.Message)

delattr() (función incorporada)

delay() (en el módulo turtle)

delay_output() (en el módulo curses)

delayload (atributo de http.cookiejar.FileCookieJar)

delch() (método de curses.window)

dele() (método de poplib.POP3)

Delete (clase en ast)

delete() (método de ftplib.FTP)

(método de imaplib.IMAP4)

(método de tkinter.ttk.Treeview)

DELETE_ATTR (opcode)

DELETE_DEREF (opcode)

DELETE_FAST (opcode)

DELETE_GLOBAL (opcode)

DELETE_NAME (opcode)

DELETE_SUBSCR (opcode)

deleteacl() (método de imaplib.IMAP4)

deletefilehandler() (método de tkinter.Widget.tk)

DeleteKey() (en el módulo winreg)

DeleteKeyEx() (en el módulo winreg)

deleteln() (método de curses.window)

deleteMe() (método de bdb.Breakpoint)

DeleteValue() (en el módulo winreg)

deletion

attribute

target

target list

delimiter (atributo de csv.Dialect)

delimiters

delitem() (en el módulo operator)

deliver_challenge() (en el módulo multiprocessing.connection)

delocalize() (en el módulo locale)

demo_app() (en el módulo wsgiref.simple_server)

denominator (atributo de fractions.Fraction)

(atributo de numbers.Rational)

DeprecationWarning

deque (clase en collections)

Deque (clase en typing)

dequeue() (método de logging.handlers.QueueListener)

DER_cert_to_PEM_cert() (en el módulo ssl)

derwin() (método de curses.window)

DES

cipher

descrgetfunc (tipo C)

description (atributo de inspect.Parameter.kind)

(atributo de sqlite3.Cursor)

description() (método de nntplib.NNTP)

descriptions() (método de nntplib.NNTP)

descriptor

descrsetfunc (tipo C)

despacho único

dest (atributo de optparse.Option)

destructor, [1]

(tipo C)

detach() (método de io.BufferedIOBase)

(método de io.TextIOBase)

(método de socket.socket)

(método de tkinter.ttk.Treeview)

(método de weakref.finalize)

Detach() (método de winreg.PyHKEY)

DETACHED_PROCESS (en el módulo subprocess)

detect_api_mismatch() (en el módulo test.support)

detect_encoding() (en el módulo tokenize)

detect_language() (método de distutils.ccompiler.CCompiler)

deterministic profiling

device_encoding() (en el módulo os)

devnull (en el módulo os)

DEVNULL (en el módulo subprocess)

devpoll() (en el módulo select)

DevpollSelector (clase en selectors)

dgettext() (en el módulo gettext)

(en el módulo locale)

dialect (atributo de csv.csvreader)

(atributo de csv.csvwriter)

Dialect (clase en csv)

Dialog (clase en msilib)

(clase en tkinter.commondialog)

(clase en tkinter.simpledialog)

diccionario

dict (2to3 fixer)

Dict (clase en ast)

(clase en typing)

dict (clase incorporada)

dict() (método de multiprocessing.managers.SyncManager)

DICT_MERGE (opcode)

DICT_UPDATE (opcode)

DictComp (clase en ast)

dictConfig() (en el módulo logging.config)

dictionary

comprehensions

display

objeto, [1], [2], [3], [4], [5], [6], [7]

type, operations on

DictReader (clase en csv)

DictWriter (clase en csv)

diff_bytes() (en el módulo difflib)

diff_files (atributo de filecmp.dircmp)

Differ (clase en difflib)

difference() (método de frozenset)

difference_update() (método de frozenset)

difflib (módulo)

digest() (en el módulo hmac)

(método de hashlib.hash)

(método de hashlib.shake)

(método de hmac.HMAC)

digest_size (atributo de hmac.HMAC)

digit() (en el módulo unicodedata)

digits (en el módulo string)

dir() (función incorporada)

(método de ftplib.FTP)

dircmp (clase en filecmp)

directory

changing

creating

deleting, [1]

site-packages

traversal, [1]

walking, [1]

Directory (clase en msilib)

(clase en tkinter.filedialog)

directory ...

compileall command line option

directory_created() (función incorporada)

DirEntry (clase en os)

DirList (clase en tkinter.tix)

dirname() (en el módulo os.path)

dirs_double_event() (método de tkinter.filedialog.FileDialog)

dirs_select_event() (método de tkinter.filedialog.FileDialog)

DirSelectBox (clase en tkinter.tix)

DirSelectDialog (clase en tkinter.tix)

DirsOnSysPath (clase en test.support)

DirTree (clase en tkinter.tix)

dis (módulo)

dis() (en el módulo dis)

(en el módulo pickletools)

(método de dis.Bytecode)

disable (pdb command)

disable() (en el módulo faulthandler)

(en el módulo gc)

(en el módulo logging)

(método de bdb.Breakpoint)

(método de profile.Profile)

disable_faulthandler() (en el módulo test.support)

disable_gc() (en el módulo test.support)

disable_interspersed_args() (método de optparse.OptionParser)

DisableReflectionKey() (en el módulo winreg)

disassemble() (en el módulo dis)

discard (atributo de http.cookiejar.Cookie)

discard() (método de frozenset)

(método de mailbox.Mailbox)

(método de mailbox.MH)

discard_buffers() (método de asynchat.async_chat)

disco() (en el módulo dis)

discover() (método de unittest.TestLoader)

disk_usage() (en el módulo shutil)

dispatch_call() (método de bdb.Bdb)

dispatch_exception() (método de bdb.Bdb)

dispatch_line() (método de bdb.Bdb)

dispatch_return() (método de bdb.Bdb)

dispatch_table (atributo de pickle.Pickler)

dispatcher (clase en asyncore)

dispatcher_with_send (clase en asyncore)

DISPLAY

display

dictionary

list

set

display (pdb command)

display_name (atributo de email.headerregistry.Address)

(atributo de email.headerregistry.Group)

displayhook() (en el módulo sys)

dist() (en el módulo math)

distance() (en el módulo turtle)

distb() (en el módulo dis)

Distribution (clase en distutils.core)

distutils (módulo)

distutils.archive_util (módulo)

distutils.bcppcompiler (módulo)

distutils.ccompiler (módulo)

distutils.cmd (módulo)

distutils.command (módulo)

distutils.command.bdist (módulo)

distutils.command.bdist_dumb (módulo)

distutils.command.bdist_msi (módulo)

distutils.command.bdist_packager (módulo)

distutils.command.bdist_rpm (módulo)

distutils.command.bdist_wininst (módulo)

distutils.command.build (módulo)

distutils.command.build_clib (módulo)

distutils.command.build_ext (módulo)

distutils.command.build_py (módulo)

distutils.command.build_scripts (módulo)

distutils.command.check (módulo)

distutils.command.clean (módulo)

distutils.command.config (módulo)

distutils.command.install (módulo)

distutils.command.install_data (módulo)

distutils.command.install_headers (módulo)

distutils.command.install_lib (módulo)

distutils.command.install_scripts (módulo)

distutils.command.register (módulo)

distutils.command.sdist (módulo)

distutils.core (módulo)

distutils.cygwinccompiler (módulo)

distutils.debug (módulo)

distutils.dep_util (módulo)

distutils.dir_util (módulo)

distutils.dist (módulo)

distutils.errors (módulo)

distutils.extension (módulo)

distutils.fancy_getopt (módulo)

distutils.file_util (módulo)

distutils.filelist (módulo)

distutils.log (módulo)

distutils.msvccompiler (módulo)

distutils.spawn (módulo)

distutils.sysconfig (módulo)

distutils.text_file (módulo)

distutils.unixccompiler (módulo)

distutils.util (módulo)

distutils.version (módulo)

DISTUTILS_DEBUG

Div (clase en ast)

divide() (método de decimal.Context)

divide_int() (método de decimal.Context)

division

DivisionByZero (clase en decimal)

división entera

divmod

función incorporada, [1], [2]

divmod() (función incorporada)

(método de decimal.Context)

DllCanUnloadNow() (en el módulo ctypes)

DllGetClassObject() (en el módulo ctypes)

dllhandle (en el módulo sys)

dnd_start() (en el módulo tkinter.dnd)

DndHandler (clase en tkinter.dnd)

dngettext() (en el módulo gettext)

dnpgettext() (en el módulo gettext)

do_clear() (método de bdb.Bdb)

do_command() (método de curses.textpad.Textbox)

do_GET() (método de http.server.SimpleHTTPRequestHandler)

do_handshake() (método de ssl.SSLSocket)

do_HEAD() (método de http.server.SimpleHTTPRequestHandler)

do_POST() (método de http.server.CGIHTTPRequestHandler)

doc (atributo de json.JSONDecodeError)

doc_header (atributo de cmd.Cmd)

DocCGIXMLRPCRequestHandler (clase en xmlrpc.server)

DocFileSuite() (en el módulo doctest)

doClassCleanups() (método de clase de unittest.TestCase)

doCleanups() (método de unittest.TestCase)

docmd() (método de smtplib.SMTP)

docstring, [1]

(atributo de doctest.DocTest)

docstrings, [1]

DocTest (clase en doctest)

doctest (módulo)

DocTestFailure

DocTestFinder (clase en doctest)

DocTestParser (clase en doctest)

DocTestRunner (clase en doctest)

DocTestSuite() (en el módulo doctest)

doctype() (método de xml.etree.ElementTree.TreeBuilder)

documentation

generation

online

documentation string

documentation strings, [1]

documentElement (atributo de xml.dom.Document)

DocXMLRPCRequestHandler (clase en xmlrpc.server)

DocXMLRPCServer (clase en xmlrpc.server)

domain (atributo de email.headerregistry.Address)

(atributo de tracemalloc.DomainFilter)

(atributo de tracemalloc.Filter)

(atributo de tracemalloc.Trace)

domain_initial_dot (atributo de http.cookiejar.Cookie)

domain_return_ok() (método de http.cookiejar.CookiePolicy)

domain_specified (atributo de http.cookiejar.Cookie)

DomainFilter (clase en tracemalloc)

DomainLiberal (atributo de http.cookiejar.DefaultCookiePolicy)

DomainRFC2965Match (atributo de http.cookiejar.DefaultCookiePolicy)

DomainStrict (atributo de http.cookiejar.DefaultCookiePolicy)

DomainStrictNoDots (atributo de http.cookiejar.DefaultCookiePolicy)

DomainStrictNonDomain (atributo de http.cookiejar.DefaultCookiePolicy)

DOMEventStream (clase en xml.dom.pulldom)

DOMException

doModuleCleanups() (en el módulo unittest)

DomstringSizeErr

done() (en el módulo turtle)

(método de asyncio.Future)

(método de asyncio.Task)

(método de concurrent.futures.Future)

(método de graphlib.TopologicalSorter)

(método de xdrlib.Unpacker)

DONT_ACCEPT_BLANKLINE (en el módulo doctest)

DONT_ACCEPT_TRUE_FOR_1 (en el módulo doctest)

dont_write_bytecode (en el módulo sys)

doRollover() (método de logging.handlers.RotatingFileHandler)

(método de logging.handlers.TimedRotatingFileHandler)

DOT (en el módulo token)

dot() (en el módulo turtle)

DOTALL (en el módulo re)

doublequote (atributo de csv.Dialect)

DOUBLESLASH (en el módulo token)

DOUBLESLASHEQUAL (en el módulo token)

DOUBLESTAR (en el módulo token)

DOUBLESTAREQUAL (en el módulo token)

doupdate() (en el módulo curses)

down (pdb command)

down() (en el módulo turtle)

dpgettext() (en el módulo gettext)

drain() (método de asyncio.StreamWriter)

drop_whitespace (atributo de textwrap.TextWrapper)

dropwhile() (en el módulo itertools)

dst() (método de datetime.datetime)

(método de datetime.time)

(método de datetime.timezone)

(método de datetime.tzinfo)

DTDHandler (clase en xml.sax.handler)

DumbWriter (clase en formatter)

dump() (en el módulo ast)

(en el módulo json)

(en el módulo marshal)

(en el módulo pickle)

(en el módulo plistlib)

(en el módulo xml.etree.ElementTree)

(método de pickle.Pickler)

(método de tracemalloc.Snapshot)

dump_stats() (método de profile.Profile)

(método de pstats.Stats)

dump_traceback() (en el módulo faulthandler)

dump_traceback_later() (en el módulo faulthandler)

dumps() (en el módulo json)

(en el módulo marshal)

(en el módulo pickle)

(en el módulo plistlib)

(en el módulo xmlrpc.client)

dup() (en el módulo os)

(método de socket.socket)

dup2() (en el módulo os)

DUP_TOP (opcode)

DUP_TOP_TWO (opcode)

DuplicateOptionError

DuplicateSectionError

dwFlags (atributo de subprocess.STARTUPINFO)

DynamicClassAttribute() (en el módulo types)

Índice – E

e

in numeric literal

e (en el módulo cmath)

(en el módulo math)

E2BIG (en el módulo errno)

EACCES (en el módulo errno)

EADDRINUSE (en el módulo errno)

EADDRNOTAVAIL (en el módulo errno)

EADV (en el módulo errno)

EAFNOSUPPORT (en el módulo errno)

EAFP

EAGAIN (en el módulo errno)

EALREADY (en el módulo errno)

east_asian_width() (en el módulo unicodedata)

EBADE (en el módulo errno)

EBADF (en el módulo errno)

EBADFD (en el módulo errno)

EBADMSG (en el módulo errno)

EBADR (en el módulo errno)

EBADRQC (en el módulo errno)

EBADSLT (en el módulo errno)

EBFONT (en el módulo errno)

EBUSY (en el módulo errno)

ECHILD (en el módulo errno)

echo() (en el módulo curses)

echochar() (método de curses.window)

ECHRNG (en el módulo errno)

ECOMM (en el módulo errno)

ECONNABORTED (en el módulo errno)

ECONNREFUSED (en el módulo errno)

ECONNRESET (en el módulo errno)

EDEADLK (en el módulo errno)

EDEADLOCK (en el módulo errno)

EDESTADDRREQ (en el módulo errno)

edit() (método de curses.textpad.Textbox)

EDOM (en el módulo errno)

EDOTDOT (en el módulo errno)

EDQUOT (en el módulo errno)

EEXIST (en el módulo errno)

EFAULT (en el módulo errno)

EFBIG (en el módulo errno)

effective() (en el módulo bdb)

ehlo() (método de smtplib.SMTP)

ehlo_or_helo_if_needed() (método de smtplib.SMTP)

EHOSTDOWN (en el módulo errno)

EHOSTUNREACH (en el módulo errno)

EIDRM (en el módulo errno)

EILSEQ (en el módulo errno)

EINPROGRESS (en el módulo errno)

EINTR (en el módulo errno)

EINVAL (en el módulo errno)

EIO (en el módulo errno)

EISCONN (en el módulo errno)

EISDIR (en el módulo errno)

EISNAM (en el módulo errno)

EL2HLT (en el módulo errno)

EL2NSYNC (en el módulo errno)

EL3HLT (en el módulo errno)

EL3RST (en el módulo errno)

Element (clase en xml.etree.ElementTree)

element_create() (método de tkinter.ttk.Style)

element_names() (método de tkinter.ttk.Style)

element_options() (método de tkinter.ttk.Style)

ElementDeclHandler() (método de xml.parsers.expat.xmlparser)

elements() (método de collections.Counter)

ElementTree (clase en xml.etree.ElementTree)

ELIBACC (en el módulo errno)

ELIBBAD (en el módulo errno)

ELIBEXEC (en el módulo errno)

ELIBMAX (en el módulo errno)

ELIBSCN (en el módulo errno)

elif

palabra clave

Ellinghouse, Lance

Ellipsis

objeto

ELLIPSIS (en el módulo doctest)

(en el módulo token)

Ellipsis (variable incorporada)

ELNRNG (en el módulo errno)

ELOOP (en el módulo errno)

else

conditional expression

dangling

palabra clave, [1], [2], [3], [4], [5]

email (módulo)

email.charset (módulo)

email.contentmanager (módulo)

email.encoders (módulo)

email.errors (módulo)

email.generator (módulo)

email.header (módulo)

email.headerregistry (módulo)

email.iterators (módulo)

email.message (módulo)

email.mime (módulo)

email.parser (módulo)

email.policy (módulo)

email.utils (módulo)

EmailMessage (clase en email.message)

EmailPolicy (clase en email.policy)

EMFILE (en el módulo errno)

emit() (método de logging.FileHandler)

(método de logging.Handler)

(método de logging.handlers.BufferingHandler)

(método de logging.handlers.DatagramHandler)

(método de logging.handlers.HTTPHandler)

(método de logging.handlers.NTEventLogHandler)

(método de logging.handlers.QueueHandler)

(método de logging.handlers.RotatingFileHandler)

(método de logging.handlers.SMTPHandler)

(método de logging.handlers.SocketHandler)

(método de logging.handlers.SysLogHandler)

(método de logging.handlers.TimedRotatingFileHandler)

(método de logging.handlers.WatchedFileHandler)

(método de logging.NullHandler)

(método de logging.StreamHandler)

EMLINK (en el módulo errno)

Empty

empty

list

tuple, [1]

empty (atributo de inspect.Parameter)

(atributo de inspect.Signature)

empty() (método de asyncio.Queue)

(método de multiprocessing.Queue)

(método de multiprocessing.SimpleQueue)

(método de queue.Queue)

(método de queue.SimpleQueue)

(método de sched.scheduler)

EMPTY_NAMESPACE (en el módulo xml.dom)

emptyline() (método de cmd.Cmd)

EMSGSIZE (en el módulo errno)

EMULTIHOP (en el módulo errno)

enable (pdb command)

enable() (en el módulo cgitb)

(en el módulo faulthandler)

(en el módulo gc)

(método de bdb.Breakpoint)

(método de imaplib.IMAP4)

(método de profile.Profile)

enable_callback_tracebacks() (en el módulo sqlite3)

enable_interspersed_args() (método de optparse.OptionParser)

enable_load_extension() (método de sqlite3.Connection)

enable_traversal() (método de tkinter.ttk.Notebook)

ENABLE_USER_SITE (en el módulo site)

EnableControlFlowGuard

EnableReflectionKey() (en el módulo winreg)

ENAMETOOLONG (en el módulo errno)

ENAVAIL (en el módulo errno)

enclose() (método de curses.window)

encode

Codecs

encode (atributo de codecs.CodecInfo)

encode() (en el módulo base64)

(en el módulo codecs)

(en el módulo quopri)

(en el módulo uu)

(método de codecs.Codec)

(método de codecs.IncrementalEncoder)

(método de email.header.Header)

(método de json.JSONEncoder)

(método de str)

(método de xmlrpc.client.Binary)

(método de xmlrpc.client.DateTime)

encode_7or8bit() (en el módulo email.encoders)

encode_base64() (en el módulo email.encoders)

encode_noop() (en el módulo email.encoders)

encode_quopri() (en el módulo email.encoders)

encode_rfc2231() (en el módulo email.utils)

encodebytes() (en el módulo base64)

EncodedFile() (en el módulo codecs)

encodePriority() (método de logging.handlers.SysLogHandler)

encodestring() (en el módulo quopri)

encoding

base64

quoted-printable

encoding (atributo de curses.window)

(atributo de io.TextIOBase)

(atributo de UnicodeError)

ENCODING (en el módulo tarfile)

(en el módulo token)

encoding declarations (source file)

encodings.idna (módulo)

encodings.mbcs (módulo)

encodings.utf_8_sig (módulo)

encodings_map (atributo de mimetypes.MimeTypes)

(en el módulo mimetypes)

end (atributo de UnicodeError)

end() (método de re.Match)

(método de xml.etree.ElementTree.TreeBuilder)

END_ASYNC_FOR (opcode)

end_col_offset (atributo de ast.AST)

end_fill() (en el módulo turtle)

end_headers() (método de http.server.BaseHTTPRequestHandler)

end_lineno (atributo de ast.AST)

end_ns() (método de xml.etree.ElementTree.TreeBuilder)

end_paragraph() (método de formatter.formatter)

end_poly() (en el módulo turtle)

EndCdataSectionHandler() (método de xml.parsers.expat.xmlparser)

EndDoctypeDeclHandler() (método de xml.parsers.expat.xmlparser)

endDocument() (método de xml.sax.handler.ContentHandler)

endElement() (método de xml.sax.handler.ContentHandler)

EndElementHandler() (método de xml.parsers.expat.xmlparser)

endElementNS() (método de xml.sax.handler.ContentHandler)

endheaders() (método de http.client.HTTPConnection)

ENDMARKER (en el módulo token)

EndNamespaceDeclHandler() (método de xml.parsers.expat.xmlparser)

endpos (atributo de re.Match)

endPrefixMapping() (método de xml.sax.handler.ContentHandler)

endswith() (método de bytearray)

(método de bytes)

(método de str)

endwin() (en el módulo curses)

ENETDOWN (en el módulo errno)

ENETRESET (en el módulo errno)

ENETUNREACH (en el módulo errno)

ENFILE (en el módulo errno)

ENOANO (en el módulo errno)

ENOBUFS (en el módulo errno)

ENOCSI (en el módulo errno)

ENODATA (en el módulo errno)

ENODEV (en el módulo errno)

ENOENT (en el módulo errno)

ENOEXEC (en el módulo errno)

ENOLCK (en el módulo errno)

ENOLINK (en el módulo errno)

ENOMEM (en el módulo errno)

ENOMSG (en el módulo errno)

ENONET (en el módulo errno)

ENOPKG (en el módulo errno)

ENOPROTOOPT (en el módulo errno)

ENOSPC (en el módulo errno)

ENOSR (en el módulo errno)

ENOSTR (en el módulo errno)

ENOSYS (en el módulo errno)

ENOTBLK (en el módulo errno)

ENOTCONN (en el módulo errno)

ENOTDIR (en el módulo errno)

ENOTEMPTY (en el módulo errno)

ENOTNAM (en el módulo errno)

ENOTSOCK (en el módulo errno)

ENOTTY (en el módulo errno)

ENOTUNIQ (en el módulo errno)

enqueue() (método de logging.handlers.QueueHandler)

enqueue_sentinel() (método de logging.handlers.QueueListener)

ensure_directories() (método de venv.EnvBuilder)

ensure_future() (en el módulo asyncio)

ensurepip (módulo)

enter() (método de sched.scheduler)

enter_async_context() (método de contextlib.AsyncExitStack)

enter_context() (método de contextlib.ExitStack)

enterabs() (método de sched.scheduler)

entities (atributo de xml.dom.DocumentType)

EntityDeclHandler() (método de xml.parsers.expat.xmlparser)

entitydefs (en el módulo html.entities)

EntityResolver (clase en xml.sax.handler)

entorno virtual

entrada de ruta

Enum (clase en enum)

enum (módulo)

enum_certificates() (en el módulo ssl)

enum_crls() (en el módulo ssl)

enumerate() (en el módulo threading)

(función incorporada)

EnumKey() (en el módulo winreg)

EnumValue() (en el módulo winreg)

EnvBuilder (clase en venv)

environ (en el módulo os)

(en el módulo posix)

environb (en el módulo os)

environment

environment variables

deleting

setting

EnvironmentError

Environments

virtual

EnvironmentVarGuard (clase en test.support)

ENXIO (en el módulo errno)

eof (atributo de bz2.BZ2Decompressor)

(atributo de lzma.LZMADecompressor)

(atributo de shlex.shlex)

(atributo de ssl.MemoryBIO)

(atributo de zlib.Decompress)

eof_received() (método de asyncio.BufferedProtocol)

(método de asyncio.Protocol)

EOFError

(built-in exception)

EOPNOTSUPP (en el módulo errno)

EOVERFLOW (en el módulo errno)

EPERM (en el módulo errno)

EPFNOSUPPORT (en el módulo errno)

epilogue (atributo de email.message.EmailMessage)

(atributo de email.message.Message)

EPIPE (en el módulo errno)

epoch

epoll() (en el módulo select)

EpollSelector (clase en selectors)

EPROTO (en el módulo errno)

EPROTONOSUPPORT (en el módulo errno)

EPROTOTYPE (en el módulo errno)

Eq (clase en ast)

eq() (en el módulo operator)

EQEQUAL (en el módulo token)

EQUAL (en el módulo token)

ERA (en el módulo locale)

ERA_D_FMT (en el módulo locale)

ERA_D_T_FMT (en el módulo locale)

ERA_T_FMT (en el módulo locale)

ERANGE (en el módulo errno)

erase() (método de curses.window)

erasechar() (en el módulo curses)

EREMCHG (en el módulo errno)

EREMOTE (en el módulo errno)

EREMOTEIO (en el módulo errno)

ERESTART (en el módulo errno)

erf() (en el módulo math)

erfc() (en el módulo math)

EROFS (en el módulo errno)

ERR (en el módulo curses)

errcheck (atributo de ctypes._FuncPtr)

errcode (atributo de xmlrpc.client.ProtocolError)

errmsg (atributo de xmlrpc.client.ProtocolError)

errno

módulo

errno (atributo de OSError)

(módulo)

Error, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13]

error, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16]

error handler's name

backslashreplace

ignore

namereplace

replace

strict

surrogateescape

surrogatepass

xmlcharrefreplace

error handling

error() (en el módulo logging)

(método de argparse.ArgumentParser)

(método de logging.Logger)

(método de urllib.request.OpenerDirector)

(método de xml.sax.handler.ErrorHandler)

error_body (atributo de wsgiref.handlers.BaseHandler)

error_content_type (atributo de http.server.BaseHTTPRequestHandler)

error_headers (atributo de wsgiref.handlers.BaseHandler)

error_leader() (método de shlex.shlex)

error_message_format (atributo de http.server.BaseHTTPRequestHandler)

error_output() (método de wsgiref.handlers.BaseHandler)

error_perm

error_proto, [1]

error_received() (método de asyncio.DatagramProtocol)

error_reply

error_status (atributo de wsgiref.handlers.BaseHandler)

error_temp

ErrorByteIndex (atributo de xml.parsers.expat.xmlparser)

ErrorCode (atributo de xml.parsers.expat.xmlparser)

errorcode (en el módulo errno)

ErrorColumnNumber (atributo de xml.parsers.expat.xmlparser)

ErrorHandler (clase en xml.sax.handler)

errorlevel (atributo de tarfile.TarFile)

ErrorLineNumber (atributo de xml.parsers.expat.xmlparser)

Errors

logging

errors

(atributo de io.TextIOBase)

(atributo de unittest.TestLoader)

(atributo de unittest.TestResult)

ErrorString() (en el módulo xml.parsers.expat)

ERRORTOKEN (en el módulo token)

escape (atributo de shlex.shlex)

escape sequence

escape() (en el módulo glob)

(en el módulo html)

(en el módulo re)

(en el módulo xml.sax.saxutils)

escapechar (atributo de csv.Dialect)

escapedquotes (atributo de shlex.shlex)

ESHUTDOWN (en el módulo errno)

ESOCKTNOSUPPORT (en el módulo errno)

espacio de nombres

especificador de módulo

ESPIPE (en el módulo errno)

ESRCH (en el módulo errno)

ESRMNT (en el módulo errno)

ESTALE (en el módulo errno)

ESTRPIPE (en el módulo errno)

ETIME (en el módulo errno)

ETIMEDOUT (en el módulo errno)

Etiny() (método de decimal.Context)

ETOOMANYREFS (en el módulo errno)

Etop() (método de decimal.Context)

ETXTBSY (en el módulo errno)

EUCLEAN (en el módulo errno)

EUNATCH (en el módulo errno)

EUSERS (en el módulo errno)

eval

función incorporada, [1], [2], [3], [4], [5]

eval() (función incorporada)

evaluation

order

Event (clase en asyncio)

(clase en multiprocessing)

(clase en threading)

event scheduling

event() (método de msilib.Control)

Event() (método de multiprocessing.managers.SyncManager)

events (atributo de selectors.SelectorKey)

(widgets)

EWOULDBLOCK (en el módulo errno)

EX_CANTCREAT (en el módulo os)

EX_CONFIG (en el módulo os)

EX_DATAERR (en el módulo os)

EX_IOERR (en el módulo os)

EX_NOHOST (en el módulo os)

EX_NOINPUT (en el módulo os)

EX_NOPERM (en el módulo os)

EX_NOTFOUND (en el módulo os)

EX_NOUSER (en el módulo os)

EX_OK (en el módulo os)

EX_OSERR (en el módulo os)

EX_OSFILE (en el módulo os)

EX_PROTOCOL (en el módulo os)

EX_SOFTWARE (en el módulo os)

EX_TEMPFAIL (en el módulo os)

EX_UNAVAILABLE (en el módulo os)

EX_USAGE (en el módulo os)

example (atributo de doctest.DocTestFailure)

(atributo de doctest.UnexpectedException)

Example (clase en doctest)

examples (atributo de doctest.DocTest)

exc_info (atributo de doctest.UnexpectedException)

(in module sys)

exc_info() (en el módulo sys)

(in module sys)

exc_msg (atributo de doctest.Example)

exc_type (atributo de traceback.TracebackException)

excel (clase en csv)

excel_tab (clase en csv)

excepción

AssertionError

AttributeError

GeneratorExit, [1]

ImportError

NameError

StopAsyncIteration

StopIteration, [1]

TypeError

ValueError

ZeroDivisionError

except

palabra clave

sentencia

except (2to3 fixer)

ExceptHandler (clase en ast)

excepthook() (en el módulo sys)

(en el módulo threading)

(in module sys)

Exception

exception, [1]

chaining

handler

raising

EXCEPTION (en el módulo tkinter)

exception handler

exception() (en el módulo logging)

(método de asyncio.Future)

(método de asyncio.Task)

(método de concurrent.futures.Future)

(método de logging.Logger)

exceptions

in CGI scripts

exclusive

or

EXDEV (en el módulo errno)

exec

función incorporada, [1], [2], [3]

exec (2to3 fixer)

exec() (función incorporada)

exec_module (función C)

exec_module() (método de importlib.abc.InspectLoader)

(método de importlib.abc.Loader)

(método de importlib.abc.SourceLoader)

(método de importlib.machinery.ExtensionFileLoader)

exec_prefix, [1], [2]

EXEC_PREFIX (en el módulo distutils.sysconfig)

exec_prefix (en el módulo sys)

execfile (2to3 fixer)

execl() (en el módulo os)

execle() (en el módulo os)

execlp() (en el módulo os)

execlpe() (en el módulo os)

executable (en el módulo sys)

(in module sys)

Executable Zip Files

executable_filename() (método de distutils.ccompiler.CCompiler)

execute() (en el módulo distutils.util)

(método de distutils.ccompiler.CCompiler)

Execute() (método de msilib.View)

execute() (método de sqlite3.Connection)

(método de sqlite3.Cursor)

executemany() (método de sqlite3.Connection)

(método de sqlite3.Cursor)

executescript() (método de sqlite3.Connection)

(método de sqlite3.Cursor)

execution

frame, [1]

restricted

stack

execution model

ExecutionLoader (clase en importlib.abc)

Executor (clase en concurrent.futures)

execv() (en el módulo os)

execve() (en el módulo os)

execvp() (en el módulo os)

execvpe() (en el módulo os)

ExFileSelectBox (clase en tkinter.tix)

EXFULL (en el módulo errno)

exists() (en el módulo os.path)

(método de pathlib.Path)

(método de tkinter.ttk.Treeview)

(método de zipfile.Path)

exit (variable incorporada)

exit()

(en el módulo _thread)

(en el módulo sys)

(método de argparse.ArgumentParser)

exitcode (atributo de multiprocessing.Process)

exitfunc (2to3 fixer)

exitonclick() (en el módulo turtle)

ExitStack (clase en contextlib)

exp() (en el módulo cmath)

(en el módulo math)

(método de decimal.Context)

(método de decimal.Decimal)

expand() (método de re.Match)

expand_tabs (atributo de textwrap.TextWrapper)

ExpandEnvironmentStrings() (en el módulo winreg)

expandNode() (método de xml.dom.pulldom.DOMEventStream)

expandtabs() (método de bytearray)

(método de bytes)

(método de str)

expanduser() (en el módulo os.path)

(método de pathlib.Path)

expandvars() (en el módulo os.path)

Expat

ExpatError

expect() (método de telnetlib.Telnet)

expected (atributo de asyncio.IncompleteReadError)

expectedFailure() (en el módulo unittest)

expectedFailures (atributo de unittest.TestResult)

expires (atributo de http.cookiejar.Cookie)

exploded (atributo de ipaddress.IPv4Address)

(atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Address)

(atributo de ipaddress.IPv6Network)

expm1() (en el módulo math)

expovariate() (en el módulo random)

Expr (clase en ast)

expr() (en el módulo parser)

expresión

expresión generadora

expression

Conditional

conditional

generator

lambda, [1]

list, [1], [2]

statement

yield

expunge() (método de imaplib.IMAP4)

extend() (método de array.array)

(método de collections.deque)

(método de xml.etree.ElementTree.Element)

(sequence method)

extend_path() (en el módulo pkgutil)

EXTENDED_ARG (opcode)

ExtendedContext (clase en decimal)

ExtendedInterpolation (clase en configparser)

extendleft() (método de collections.deque)

extension

module

Extension (clase en distutils.core)

EXTENSION_SUFFIXES (en el módulo importlib.machinery)

ExtensionFileLoader (clase en importlib.machinery)

extensions_map (atributo de http.server.SimpleHTTPRequestHandler)

External Data Representation, [1]

external_attr (atributo de zipfile.ZipInfo)

ExternalClashError

ExternalEntityParserCreate() (método de xml.parsers.expat.xmlparser)

ExternalEntityRefHandler() (método de xml.parsers.expat.xmlparser)

extra (atributo de zipfile.ZipInfo)

extract() (método de clase de traceback.StackSummary)

(método de tarfile.TarFile)

(método de zipfile.ZipFile)

extract_cookies() (método de http.cookiejar.CookieJar)

extract_stack() (en el módulo traceback)

extract_tb() (en el módulo traceback)

extract_version (atributo de zipfile.ZipInfo)

extractall() (método de tarfile.TarFile)

(método de zipfile.ZipFile)

ExtractError

extractfile() (método de tarfile.TarFile)

extraction_filter (atributo de tarfile.TarFile)

extsep (en el módulo os)

Índice – F

f"

formatted string literal

f'

formatted string literal

f-string, [1]

f_back (frame attribute)

f_builtins (frame attribute)

f_code (frame attribute)

f_contiguous (atributo de memoryview)

f_globals (frame attribute)

f_lasti (frame attribute)

f_lineno (frame attribute)

f_locals (frame attribute)

F_LOCK (en el módulo os)

F_OK (en el módulo os)

F_TEST (en el módulo os)

F_TLOCK (en el módulo os)

f_trace (frame attribute)

f_trace_lines (frame attribute)

f_trace_opcodes (frame attribute)

F_ULOCK (en el módulo os)

fabs() (en el módulo math)

factorial() (en el módulo math)

factory() (método de clase de importlib.util.LazyLoader)

fail() (método de unittest.TestCase)

FAIL_FAST (en el módulo doctest)

failfast (atributo de unittest.TestResult)

failureException (atributo de unittest.TestCase)

failures (atributo de unittest.TestResult)

FakePath (clase en test.support)

False, [1], [2]

false

False (Built-in object)

(variable incorporada)

families() (en el módulo tkinter.font)

family (atributo de socket.socket)

fancy_getopt() (en el módulo distutils.fancy_getopt)

FancyGetopt (clase en distutils.fancy_getopt)

FancyURLopener (clase en urllib.request)

fast (atributo de pickle.Pickler)

FastChildWatcher (clase en asyncio)

fatalError() (método de xml.sax.handler.ErrorHandler)

Fault (clase en xmlrpc.client)

faultCode (atributo de xmlrpc.client.Fault)

faulthandler (módulo)

faultString (atributo de xmlrpc.client.Fault)

fchdir() (en el módulo os)

fchmod() (en el módulo os)

fchown() (en el módulo os)

FCICreate() (en el módulo msilib)

fcntl (módulo)

fcntl() (en el módulo fcntl)

fd (atributo de selectors.SelectorKey)

fd() (en el módulo turtle)

fd_count() (en el módulo test.support)

fdatasync() (en el módulo os)

fdopen() (en el módulo os)

Feature (clase en msilib)

feature_external_ges (en el módulo xml.sax.handler)

feature_external_pes (en el módulo xml.sax.handler)

feature_namespace_prefixes (en el módulo xml.sax.handler)

feature_namespaces (en el módulo xml.sax.handler)

feature_string_interning (en el módulo xml.sax.handler)

feature_validation (en el módulo xml.sax.handler)

feed() (método de email.parser.BytesFeedParser)

(método de html.parser.HTMLParser)

(método de xml.etree.ElementTree.XMLParser)

(método de xml.etree.ElementTree.XMLPullParser)

(método de xml.sax.xmlreader.IncrementalParser)

FeedParser (clase en email.parser)

fetch() (método de imaplib.IMAP4)

Fetch() (método de msilib.View)

fetchall() (método de sqlite3.Cursor)

fetchmany() (método de sqlite3.Cursor)

fetchone() (método de sqlite3.Cursor)

fflags (atributo de select.kevent)

Field (clase en dataclasses)

field() (en el módulo dataclasses)

field_size_limit() (en el módulo csv)

fieldnames (atributo de csv.csvreader)

fields (atributo de uuid.UUID)

fields() (en el módulo dataclasses)

file

.ini

.pdbrc

byte-code, [1]

configuration

copying

debugger configuration

gzip command line option

large files

mime.types

modes

objeto, [1]

path configuration

plist

temporary

file (atributo de pyclbr.Class)

(atributo de pyclbr.Function)

file ...

compileall command line option

file control

UNIX

file name

temporary

file object

io module

open() built-in function

FILE_ATTRIBUTE_ARCHIVE (en el módulo stat)

FILE_ATTRIBUTE_COMPRESSED (en el módulo stat)

FILE_ATTRIBUTE_DEVICE (en el módulo stat)

FILE_ATTRIBUTE_DIRECTORY (en el módulo stat)

FILE_ATTRIBUTE_ENCRYPTED (en el módulo stat)

FILE_ATTRIBUTE_HIDDEN (en el módulo stat)

FILE_ATTRIBUTE_INTEGRITY_STREAM (en el módulo stat)

FILE_ATTRIBUTE_NO_SCRUB_DATA (en el módulo stat)

FILE_ATTRIBUTE_NORMAL (en el módulo stat)

FILE_ATTRIBUTE_NOT_CONTENT_INDEXED (en el módulo stat)

FILE_ATTRIBUTE_OFFLINE (en el módulo stat)

FILE_ATTRIBUTE_READONLY (en el módulo stat)

FILE_ATTRIBUTE_REPARSE_POINT (en el módulo stat)

FILE_ATTRIBUTE_SPARSE_FILE (en el módulo stat)

FILE_ATTRIBUTE_SYSTEM (en el módulo stat)

FILE_ATTRIBUTE_TEMPORARY (en el módulo stat)

FILE_ATTRIBUTE_VIRTUAL (en el módulo stat)

file_created() (función incorporada)

file_dispatcher (clase en asyncore)

file_open() (método de urllib.request.FileHandler)

file_size (atributo de zipfile.ZipInfo)

file_wrapper (clase en asyncore)

filecmp (módulo)

fileConfig() (en el módulo logging.config)

FileCookieJar (clase en http.cookiejar)

FileDialog (clase en tkinter.filedialog)

FileEntry (clase en tkinter.tix)

FileExistsError

FileFinder (clase en importlib.machinery)

FileHandler (clase en logging)

(clase en urllib.request)

FileInput (clase en fileinput)

fileinput (módulo)

FileIO (clase en io)

filelineno() (en el módulo fileinput)

FileLoader (clase en importlib.abc)

filemode() (en el módulo stat)

filename (atributo de doctest.DocTest)

(atributo de http.cookiejar.FileCookieJar)

(atributo de OSError)

(atributo de SyntaxError)

(atributo de traceback.TracebackException)

(atributo de tracemalloc.Frame)

(atributo de zipfile.ZipFile)

(atributo de zipfile.ZipInfo)

filename() (en el módulo fileinput)

filename2 (atributo de OSError)

filename_only (en el módulo tabnanny)

filename_pattern (atributo de tracemalloc.Filter)

filenames

pathname expansion

wildcard expansion

fileno() (en el módulo fileinput)

(método de http.client.HTTPResponse)

(método de io.IOBase)

(método de multiprocessing.connection.Connection)

(método de ossaudiodev.oss_audio_device)

(método de ossaudiodev.oss_mixer_device)

(método de select.devpoll)

(método de select.epoll)

(método de select.kqueue)

(método de selectors.DevpollSelector)

(método de selectors.EpollSelector)

(método de selectors.KqueueSelector)

(método de socket.socket)

(método de socketserver.BaseServer)

(método de telnetlib.Telnet)

FileNotFoundError

fileobj (atributo de selectors.SelectorKey)

files() (en el módulo importlib.resources)

files_double_event() (método de tkinter.filedialog.FileDialog)

files_select_event() (método de tkinter.filedialog.FileDialog)

FileSelectBox (clase en tkinter.tix)

FileType (clase en argparse)

FileWrapper (clase en wsgiref.util)

fill() (en el módulo textwrap)

(método de textwrap.TextWrapper)

fillcolor() (en el módulo turtle)

filling() (en el módulo turtle)

filter (2to3 fixer)

(atributo de select.kevent)

Filter (clase en logging)

(clase en tracemalloc)

filter() (en el módulo curses)

(en el módulo fnmatch)

(función incorporada)

(método de logging.Filter)

(método de logging.Handler)

(método de logging.Logger)

filter_command() (método de tkinter.filedialog.FileDialog)

FILTER_DIR (en el módulo unittest.mock)

filter_traces() (método de tracemalloc.Snapshot)

FilterError

filterfalse() (en el módulo itertools)

filterwarnings() (en el módulo warnings)

Final (en el módulo typing)

final() (en el módulo typing)

finalization, of objects

finalize (clase en weakref)

finalize_options() (método de distutils.cmd.Command)

finalizer

finally

palabra clave, [1], [2], [3], [4]

find() (en el módulo gettext)

(método de bytearray)

(método de bytes)

(método de doctest.DocTestFinder)

(método de mmap.mmap)

(método de str)

(método de xml.etree.ElementTree.Element)

(método de xml.etree.ElementTree.ElementTree)

find_class() (método de pickle.Unpickler)

(pickle protocol)

find_library() (en el módulo ctypes.util)

find_library_file() (método de distutils.ccompiler.CCompiler)

find_loader() (en el módulo importlib)

(en el módulo pkgutil)

(método de importlib.abc.PathEntryFinder)

(método de importlib.machinery.FileFinder)

find_longest_match() (método de difflib.SequenceMatcher)

find_module() (en el módulo imp)

(método de clase de importlib.machinery.PathFinder)

(método de imp.NullImporter)

(método de importlib.abc.Finder)

(método de importlib.abc.MetaPathFinder)

(método de importlib.abc.PathEntryFinder)

(método de zipimport.zipimporter)

find_msvcrt() (en el módulo ctypes.util)

find_spec

finder

find_spec() (en el módulo importlib.util)

(método de clase de importlib.machinery.PathFinder)

(método de importlib.abc.MetaPathFinder)

(método de importlib.abc.PathEntryFinder)

(método de importlib.machinery.FileFinder)

find_unused_port() (en el módulo test.support.socket_helper)

find_user_password() (método de urllib.request.HTTPPasswordMgr)

(método de urllib.request.HTTPPasswordMgrWithPriorAuth)

findall() (en el módulo re)

(método de re.Pattern)

(método de xml.etree.ElementTree.Element)

(método de xml.etree.ElementTree.ElementTree)

findCaller() (método de logging.Logger)

finder

find_spec

Finder (clase en importlib.abc)

findfactor() (en el módulo audioop)

findfile() (en el módulo test.support)

findfit() (en el módulo audioop)

finditer() (en el módulo re)

(método de re.Pattern)

findlabels() (en el módulo dis)

findlinestarts() (en el módulo dis)

findmatch() (en el módulo mailcap)

findmax() (en el módulo audioop)

findtext() (método de xml.etree.ElementTree.Element)

(método de xml.etree.ElementTree.ElementTree)

finish() (método de socketserver.BaseRequestHandler)

(método de tkinter.dnd.DndHandler)

finish_request() (método de socketserver.BaseServer)

firstChild (atributo de xml.dom.Node)

firstkey() (método de dbm.gnu.gdbm)

firstweekday() (en el módulo calendar)

fix_missing_locations() (en el módulo ast)

fix_sentence_endings (atributo de textwrap.TextWrapper)

Flag (clase en enum)

flag_bits (atributo de zipfile.ZipInfo)

flags (atributo de re.Pattern)

(atributo de select.kevent)

(en el módulo sys)

flash() (en el módulo curses)

flatten() (método de email.generator.BytesGenerator)

(método de email.generator.Generator)

flattening

objects

float

función incorporada, [1], [2]

float (clase incorporada)

float_info (en el módulo sys)

float_repr_style (en el módulo sys)

floating point

literals

number

objeto, [1], [2]

floating point literal

FloatingPointError

FloatOperation (clase en decimal)

flock() (en el módulo fcntl)

floor() (en el módulo math)

(in module math)

FloorDiv (clase en ast)

floordiv() (en el módulo operator)

flush() (método de bz2.BZ2Compressor)

(método de formatter.writer)

(método de io.BufferedWriter)

(método de io.IOBase)

(método de logging.Handler)

(método de logging.handlers.BufferingHandler)

(método de logging.handlers.MemoryHandler)

(método de logging.StreamHandler)

(método de lzma.LZMACompressor)

(método de mailbox.Mailbox)

(método de mailbox.Maildir)

(método de mailbox.MH)

(método de mmap.mmap)

(método de zlib.Compress)

(método de zlib.Decompress)

flush_headers() (método de http.server.BaseHTTPRequestHandler)

flush_softspace() (método de formatter.formatter)

flushinp() (en el módulo curses)

FlushKey() (en el módulo winreg)

fma() (método de decimal.Context)

(método de decimal.Decimal)

fmean() (en el módulo statistics)

fmod() (en el módulo math)

FMT_BINARY (en el módulo plistlib)

FMT_XML (en el módulo plistlib)

fnmatch (módulo)

fnmatch() (en el módulo fnmatch)

fnmatchcase() (en el módulo fnmatch)

focus() (método de tkinter.ttk.Treeview)

fold (atributo de datetime.datetime)

(atributo de datetime.time)

fold() (método de email.headerregistry.BaseHeader)

(método de email.policy.Compat32)

(método de email.policy.EmailPolicy)

(método de email.policy.Policy)

fold_binary() (método de email.policy.Compat32)

(método de email.policy.EmailPolicy)

(método de email.policy.Policy)

Font (clase en tkinter.font)

for

in comprehensions

sentencia, [1], [2], [3]

For (clase en ast)

FOR_ITER (opcode)

forget() (en el módulo test.support)

(método de tkinter.ttk.Notebook)

fork() (en el módulo os)

(en el módulo pty)

ForkingMixIn (clase en socketserver)

ForkingTCPServer (clase en socketserver)

ForkingUDPServer (clase en socketserver)

forkpty() (en el módulo os)

form

lambda

Form (clase en tkinter.tix)

format (atributo de memoryview)

(atributo de multiprocessing.shared_memory.ShareableList)

(atributo de struct.Struct)

format() (built-in function)

__str__() (object method)

format() (en el módulo locale)

(función incorporada)

(método de logging.Formatter)

(método de logging.Handler)

(método de pprint.PrettyPrinter)

(método de str)

(método de string.Formatter)

(método de traceback.StackSummary)

(método de traceback.TracebackException)

(método de tracemalloc.Traceback)

format_datetime() (en el módulo email.utils)

format_exc() (en el módulo traceback)

format_exception() (en el módulo traceback)

format_exception_only() (en el módulo traceback)

(método de traceback.TracebackException)

format_field() (método de string.Formatter)

format_help() (método de argparse.ArgumentParser)

format_list() (en el módulo traceback)

format_map() (método de str)

format_stack() (en el módulo traceback)

format_stack_entry() (método de bdb.Bdb)

format_string() (en el módulo locale)

format_tb() (en el módulo traceback)

format_usage() (método de argparse.ArgumentParser)

FORMAT_VALUE (opcode)

formataddr() (en el módulo email.utils)

formatargspec() (en el módulo inspect)

formatargvalues() (en el módulo inspect)

formatdate() (en el módulo email.utils)

FormatError

FormatError() (en el módulo ctypes)

formatException() (método de logging.Formatter)

formatmonth() (método de calendar.HTMLCalendar)

(método de calendar.TextCalendar)

formatStack() (método de logging.Formatter)

formatted string literal

FormattedValue (clase en ast)

Formatter (clase en logging)

(clase en string)

formatter (módulo)

formatTime() (método de logging.Formatter)

formatting

bytearray (%)

bytes (%)

formatting, string (%)

formatwarning() (en el módulo warnings)

formatyear() (método de calendar.HTMLCalendar)

(método de calendar.TextCalendar)

formatyearpage() (método de calendar.HTMLCalendar)

Fortran contiguous, [1]

forward() (en el módulo turtle)

ForwardRef (clase en typing)

found_terminator() (método de asynchat.async_chat)

fpathconf() (en el módulo os)

fqdn (atributo de smtpd.SMTPChannel)

Fraction (clase en fractions)

fractions (módulo)

frame

execution, [1]

objeto

frame (atributo de tkinter.scrolledtext.ScrolledText)

Frame (clase en tracemalloc)

FrameSummary (clase en traceback)

FrameType (en el módulo types)

free

variable

free()

freefunc (tipo C)

freeze utility

freeze() (en el módulo gc)

freeze_support() (en el módulo multiprocessing)

frexp() (en el módulo math)

from

import statement, [1]

palabra clave, [1]

yield from expression

from_address() (método de ctypes._CData)

from_buffer() (método de ctypes._CData)

from_buffer_copy() (método de ctypes._CData)

from_bytes() (método de clase de int)

from_callable() (método de clase de inspect.Signature)

from_decimal() (método de fractions.Fraction)

from_exception() (método de clase de traceback.TracebackException)

from_file() (método de clase de zipfile.ZipInfo)

(método de clase de zoneinfo.ZoneInfo)

from_float() (método de decimal.Decimal)

(método de fractions.Fraction)

from_iterable() (método de clase de itertools.chain)

from_list() (método de clase de traceback.StackSummary)

from_param() (método de ctypes._CData)

from_samples() (método de clase de statistics.NormalDist)

from_traceback() (método de clase de dis.Bytecode)

frombuf() (método de clase de tarfile.TarInfo)

frombytes() (método de array.array)

fromfd() (en el módulo socket)

(método de select.epoll)

(método de select.kqueue)

fromfile() (método de array.array)

fromhex() (método de clase de bytearray)

(método de clase de bytes)

(método de clase de float)

fromisocalendar() (método de clase de datetime.date)

(método de clase de datetime.datetime)

fromisoformat() (método de clase de datetime.date)

(método de clase de datetime.datetime)

(método de clase de datetime.time)

fromkeys() (método de clase de dict)

(método de collections.Counter)

fromlist() (método de array.array)

fromordinal() (método de clase de datetime.date)

(método de clase de datetime.datetime)

fromshare() (en el módulo socket)

fromstring() (en el módulo xml.etree.ElementTree)

fromstringlist() (en el módulo xml.etree.ElementTree)

fromtarfile() (método de clase de tarfile.TarInfo)

fromtimestamp() (método de clase de datetime.date)

(método de clase de datetime.datetime)

fromunicode() (método de array.array)

fromutc() (método de datetime.timezone)

(método de datetime.tzinfo)

FrozenImporter (clase en importlib.machinery)

FrozenInstanceError

frozenset

objeto, [1]

FrozenSet (clase en typing)

frozenset (clase incorporada)

fs_is_case_insensitive() (en el módulo test.support)

FS_NONASCII (en el módulo test.support)

fsdecode() (en el módulo os)

fsencode() (en el módulo os)

fspath() (en el módulo os)

fstat() (en el módulo os)

fstatvfs() (en el módulo os)

fstring

fsum() (en el módulo math)

fsync() (en el módulo os)

FTP

ftplib (standard module)

protocol, [1]

FTP (clase en ftplib)

ftp_open() (método de urllib.request.FTPHandler)

FTP_TLS (clase en ftplib)

FTPHandler (clase en urllib.request)

ftplib (módulo)

ftruncate() (en el módulo os)

Full

full() (método de asyncio.Queue)

(método de multiprocessing.Queue)

(método de queue.Queue)

full_url (atributo de urllib.request.Request)

fullmatch() (en el módulo re)

(método de re.Pattern)

fully_trusted_filter() (en el módulo tarfile)

func (atributo de functools.partial)

funcattrs (2to3 fixer)

función

función clave

función corrutina

función genérica

función incorporada

__import__

abs, [1]

ascii

bytes, [1]

chr

classmethod

compile, [1], [2], [3], [4]

complex, [1]

divmod, [1], [2]

eval, [1], [2], [3], [4], [5]

exec, [1], [2], [3]

float, [1], [2]

hash, [1], [2], [3]

help

id

int, [1], [2]

len, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11]

max

min

open, [1]

ord

pow, [1], [2], [3], [4], [5]

print

range

repr, [1], [2], [3]

round

slice, [1]

staticmethod

tuple, [1]

type, [1], [2], [3]

function

annotations, [1]

anonymous

argument

call, [1], [2]

call, user-defined

definition, [1]

generator, [1]

name, [1]

objeto, [1], [2], [3], [4], [5]

user-defined

Function (clase en symtable)

FunctionDef (clase en ast)

FunctionTestCase (clase en unittest)

FunctionType (en el módulo types)

functools (módulo)

funny_files (atributo de filecmp.dircmp)

future

statement

future (2to3 fixer)

Future (clase en asyncio)

(clase en concurrent.futures)

FutureWarning

fwalk() (en el módulo os)

Índice – G

G.722

gaierror

gamma() (en el módulo math)

gammavariate() (en el módulo random)

gancho a entrada de ruta

garbage (en el módulo gc)

garbage collection

gather() (en el módulo asyncio)

(método de curses.textpad.Textbox)

gauss() (en el módulo random)

gc (módulo)

gc_collect() (en el módulo test.support)

gcd() (en el módulo math)

ge() (en el módulo operator)

gen_lib_options() (en el módulo distutils.ccompiler)

gen_preprocess_options() (en el módulo distutils.ccompiler)

gen_uuid() (en el módulo msilib)

generador

generador asincrónico

generate_help() (método de distutils.fancy_getopt.FancyGetopt)

generate_tokens() (en el módulo tokenize)

generator

expression

function, [1], [2]

iterator, [1]

objeto, [1], [2]

Generator (clase en collections.abc)

(clase en email.generator)

(clase en typing)

generator expression

GeneratorExit

excepción, [1]

GeneratorExp (clase en ast)

GeneratorType (en el módulo types)

Generic

Alias

generic

special attribute

Generic (clase en typing)

generic_visit() (método de ast.NodeVisitor)

GenericAlias

objeto

GenericAlias (clase en types)

genops() (en el módulo pickletools)

geometric_mean() (en el módulo statistics)

get() (en el módulo webbrowser)

(método de asyncio.Queue)

(método de configparser.ConfigParser)

(método de contextvars.Context)

(método de contextvars.ContextVar)

(método de dict)

(método de email.message.EmailMessage)

(método de email.message.Message)

(método de mailbox.Mailbox)

(método de multiprocessing.pool.AsyncResult)

(método de multiprocessing.Queue)

(método de multiprocessing.SimpleQueue)

(método de ossaudiodev.oss_mixer_device)

(método de queue.Queue)

(método de queue.SimpleQueue)

(método de tkinter.ttk.Combobox)

(método de tkinter.ttk.Spinbox)

(método de types.MappingProxyType)

(método de xml.etree.ElementTree.Element)

GET_AITER (opcode)

get_all() (método de email.message.EmailMessage)

(método de email.message.Message)

(método de wsgiref.headers.Headers)

get_all_breaks() (método de bdb.Bdb)

get_all_start_methods() (en el módulo multiprocessing)

GET_ANEXT (opcode)

get_app() (método de wsgiref.simple_server.WSGIServer)

get_archive_formats() (en el módulo shutil)

get_args() (en el módulo typing)

get_asyncgen_hooks() (en el módulo sys)

get_attribute() (en el módulo test.support)

GET_AWAITABLE (opcode)

get_begidx() (en el módulo readline)

get_blocking() (en el módulo os)

get_body() (método de email.message.EmailMessage)

get_body_encoding() (método de email.charset.Charset)

get_boundary() (método de email.message.EmailMessage)

(método de email.message.Message)

get_bpbynumber() (método de bdb.Bdb)

get_break() (método de bdb.Bdb)

get_breaks() (método de bdb.Bdb)

get_buffer() (método de asyncio.BufferedProtocol)

(método de xdrlib.Packer)

(método de xdrlib.Unpacker)

get_bytes() (método de mailbox.Mailbox)

get_ca_certs() (método de ssl.SSLContext)

get_cache_token() (en el módulo abc)

get_channel_binding() (método de ssl.SSLSocket)

get_charset() (método de email.message.Message)

get_charsets() (método de email.message.EmailMessage)

(método de email.message.Message)

get_child_watcher() (en el módulo asyncio)

(método de asyncio.AbstractEventLoopPolicy)

get_children() (método de symtable.SymbolTable)

(método de tkinter.ttk.Treeview)

get_ciphers() (método de ssl.SSLContext)

get_clock_info() (en el módulo time)

get_close_matches() (en el módulo difflib)

get_code() (método de importlib.abc.InspectLoader)

(método de importlib.abc.SourceLoader)

(método de importlib.machinery.ExtensionFileLoader)

(método de importlib.machinery.SourcelessFileLoader)

(método de zipimport.zipimporter)

get_completer() (en el módulo readline)

get_completer_delims() (en el módulo readline)

get_completion_type() (en el módulo readline)

get_config_h_filename() (en el módulo distutils.sysconfig)

(en el módulo sysconfig)

get_config_var() (en el módulo distutils.sysconfig)

(en el módulo sysconfig)

get_config_vars() (en el módulo distutils.sysconfig)

(en el módulo sysconfig)

get_content() (en el módulo email.contentmanager)

(método de email.contentmanager.ContentManager)

(método de email.message.EmailMessage)

get_content_charset() (método de email.message.EmailMessage)

(método de email.message.Message)

get_content_disposition() (método de email.message.EmailMessage)

(método de email.message.Message)

get_content_maintype() (método de email.message.EmailMessage)

(método de email.message.Message)

get_content_subtype() (método de email.message.EmailMessage)

(método de email.message.Message)

get_content_type() (método de email.message.EmailMessage)

(método de email.message.Message)

get_context() (en el módulo multiprocessing)

get_coro() (método de asyncio.Task)

get_coroutine_origin_tracking_depth() (en el módulo sys)

get_count() (en el módulo gc)

get_current_history_length() (en el módulo readline)

get_data() (en el módulo pkgutil)

(método de importlib.abc.FileLoader)

(método de importlib.abc.ResourceLoader)

(método de zipimport.zipimporter)

get_date() (método de mailbox.MaildirMessage)

get_debug() (en el módulo gc)

(método de asyncio.loop)

get_default() (método de argparse.ArgumentParser)

get_default_compiler() (en el módulo distutils.ccompiler)

get_default_domain() (en el módulo nis)

get_default_type() (método de email.message.EmailMessage)

(método de email.message.Message)

get_default_verify_paths() (en el módulo ssl)

get_dialect() (en el módulo csv)

get_disassembly_as_string() (método de test.support.bytecode_helper.BytecodeTestCase)

get_docstring() (en el módulo ast)

get_doctest() (método de doctest.DocTestParser)

get_endidx() (en el módulo readline)

get_environ() (método de wsgiref.simple_server.WSGIRequestHandler)

get_errno() (en el módulo ctypes)

get_escdelay() (en el módulo curses)

get_event_loop() (en el módulo asyncio)

(método de asyncio.AbstractEventLoopPolicy)

get_event_loop_policy() (en el módulo asyncio)

get_examples() (método de doctest.DocTestParser)

get_exception_handler() (método de asyncio.loop)

get_exec_path() (en el módulo os)

get_extra_info() (método de asyncio.BaseTransport)

(método de asyncio.StreamWriter)

get_field() (método de string.Formatter)

get_file() (método de mailbox.Babyl)

(método de mailbox.Mailbox)

(método de mailbox.Maildir)

(método de mailbox.mbox)

(método de mailbox.MH)

(método de mailbox.MMDF)

get_file_breaks() (método de bdb.Bdb)

get_filename() (método de email.message.EmailMessage)

(método de email.message.Message)

(método de importlib.abc.ExecutionLoader)

(método de importlib.abc.FileLoader)

(método de importlib.machinery.ExtensionFileLoader)

(método de zipimport.zipimporter)

get_filter() (método de tkinter.filedialog.FileDialog)

get_flags() (método de mailbox.MaildirMessage)

(método de mailbox.mboxMessage)

(método de mailbox.MMDFMessage)

get_folder() (método de mailbox.Maildir)

(método de mailbox.MH)

get_frees() (método de symtable.Function)

get_freeze_count() (en el módulo gc)

get_from() (método de mailbox.mboxMessage)

(método de mailbox.MMDFMessage)

get_full_url() (método de urllib.request.Request)

get_globals() (método de symtable.Function)

get_grouped_opcodes() (método de difflib.SequenceMatcher)

get_handle_inheritable() (en el módulo os)

get_header() (método de urllib.request.Request)

get_history_item() (en el módulo readline)

get_history_length() (en el módulo readline)

get_id() (método de symtable.SymbolTable)

get_ident() (en el módulo _thread)

(en el módulo threading)

get_identifiers() (método de symtable.SymbolTable)

get_importer() (en el módulo pkgutil)

get_info() (método de mailbox.MaildirMessage)

get_inheritable() (en el módulo os)

(método de socket.socket)

get_instructions() (en el módulo dis)

get_int_max_str_digits() (en el módulo sys)

get_interpreter() (en el módulo zipapp)

GET_ITER (opcode)

get_key() (método de selectors.BaseSelector)

get_labels() (método de mailbox.Babyl)

(método de mailbox.BabylMessage)

get_last_error() (en el módulo ctypes)

get_line_buffer() (en el módulo readline)

get_lineno() (método de symtable.SymbolTable)

get_loader() (en el módulo pkgutil)

get_locals() (método de symtable.Function)

get_logger() (en el módulo multiprocessing)

get_loop() (método de asyncio.Future)

(método de asyncio.Server)

get_magic() (en el módulo imp)

get_makefile_filename() (en el módulo distutils.sysconfig)

(en el módulo sysconfig)

get_map() (método de selectors.BaseSelector)

get_matching_blocks() (método de difflib.SequenceMatcher)

get_message() (método de mailbox.Mailbox)

get_method() (método de urllib.request.Request)

get_methods() (método de symtable.Class)

get_mixed_type_key() (en el módulo ipaddress)

get_name() (método de asyncio.Task)

(método de symtable.Symbol)

(método de symtable.SymbolTable)

get_namespace() (método de symtable.Symbol)

get_namespaces() (método de symtable.Symbol)

get_native_id() (en el módulo _thread)

(en el módulo threading)

get_nonlocals() (método de symtable.Function)

get_nonstandard_attr() (método de http.cookiejar.Cookie)

get_nowait() (método de asyncio.Queue)

(método de multiprocessing.Queue)

(método de queue.Queue)

(método de queue.SimpleQueue)

get_object_traceback() (en el módulo tracemalloc)

get_objects() (en el módulo gc)

get_opcodes() (método de difflib.SequenceMatcher)

get_option() (método de optparse.OptionParser)

get_option_group() (método de optparse.OptionParser)

get_option_order() (método de distutils.fancy_getopt.FancyGetopt)

get_origin() (en el módulo typing)

get_original_stdout() (en el módulo test.support)

get_osfhandle() (en el módulo msvcrt)

get_output_charset() (método de email.charset.Charset)

get_param() (método de email.message.Message)

get_parameters() (método de symtable.Function)

get_params() (método de email.message.Message)

get_path() (en el módulo sysconfig)

get_path_names() (en el módulo sysconfig)

get_paths() (en el módulo sysconfig)

get_payload() (método de email.message.Message)

get_pid() (método de asyncio.SubprocessTransport)

get_pipe_transport() (método de asyncio.SubprocessTransport)

get_platform() (en el módulo distutils.util)

(en el módulo sysconfig)

get_poly() (en el módulo turtle)

get_position() (método de xdrlib.Unpacker)

get_protocol() (método de asyncio.BaseTransport)

get_python_inc() (en el módulo distutils.sysconfig)

get_python_lib() (en el módulo distutils.sysconfig)

get_python_version() (en el módulo sysconfig)

get_ready() (método de graphlib.TopologicalSorter)

get_recsrc() (método de ossaudiodev.oss_mixer_device)

get_referents() (en el módulo gc)

get_referrers() (en el módulo gc)

get_request() (método de socketserver.BaseServer)

get_returncode() (método de asyncio.SubprocessTransport)

get_running_loop() (en el módulo asyncio)

get_scheme() (método de wsgiref.handlers.BaseHandler)

get_scheme_names() (en el módulo sysconfig)

get_selection() (método de tkinter.filedialog.FileDialog)

get_sequences() (método de mailbox.MH)

(método de mailbox.MHMessage)

get_server() (método de multiprocessing.managers.BaseManager)

get_server_certificate() (en el módulo ssl)

get_shapepoly() (en el módulo turtle)

get_socket() (método de telnetlib.Telnet)

get_source() (método de importlib.abc.InspectLoader)

(método de importlib.abc.SourceLoader)

(método de importlib.machinery.ExtensionFileLoader)

(método de importlib.machinery.SourcelessFileLoader)

(método de zipimport.zipimporter)

get_source_segment() (en el módulo ast)

get_special_folder_path() (función incorporada)

get_stack() (método de asyncio.Task)

(método de bdb.Bdb)

get_start_method() (en el módulo multiprocessing)

get_starttag_text() (método de html.parser.HTMLParser)

get_stats() (en el módulo gc)

get_stats_profile() (método de pstats.Stats)

get_stderr() (método de wsgiref.handlers.BaseHandler)

(método de wsgiref.simple_server.WSGIRequestHandler)

get_stdin() (método de wsgiref.handlers.BaseHandler)

get_string() (método de mailbox.Mailbox)

get_subdir() (método de mailbox.MaildirMessage)

get_suffixes() (en el módulo imp)

get_symbols() (método de symtable.SymbolTable)

get_tabsize() (en el módulo curses)

get_tag() (en el módulo imp)

get_task_factory() (método de asyncio.loop)

get_terminal_size() (en el módulo os)

(en el módulo shutil)

get_terminator() (método de asynchat.async_chat)

get_threshold() (en el módulo gc)

get_token() (método de shlex.shlex)

get_traceback_limit() (en el módulo tracemalloc)

get_traced_memory() (en el módulo tracemalloc)

get_tracemalloc_memory() (en el módulo tracemalloc)

get_type() (método de symtable.SymbolTable)

get_type_hints() (en el módulo typing)

get_unixfrom() (método de email.message.EmailMessage)

(método de email.message.Message)

get_unpack_formats() (en el módulo shutil)

get_usage() (método de optparse.OptionParser)

get_value() (método de string.Formatter)

get_version() (método de optparse.OptionParser)

get_visible() (método de mailbox.BabylMessage)

get_wch() (método de curses.window)

get_write_buffer_limits() (método de asyncio.WriteTransport)

get_write_buffer_size() (método de asyncio.WriteTransport)

GET_YIELD_FROM_ITER (opcode)

getacl() (método de imaplib.IMAP4)

getaddresses() (en el módulo email.utils)

getaddrinfo() (en el módulo socket)

(método de asyncio.loop)

getallocatedblocks() (en el módulo sys)

getandroidapilevel() (en el módulo sys)

getannotation() (método de imaplib.IMAP4)

getargspec() (en el módulo inspect)

getargvalues() (en el módulo inspect)

getatime() (en el módulo os.path)

getattr() (función incorporada)

getattr_static() (en el módulo inspect)

getattrfunc (tipo C)

getAttribute() (método de xml.dom.Element)

getAttributeNode() (método de xml.dom.Element)

getAttributeNodeNS() (método de xml.dom.Element)

getAttributeNS() (método de xml.dom.Element)

getattrofunc (tipo C)

GetBase() (método de xml.parsers.expat.xmlparser)

getbegyx() (método de curses.window)

getbkgd() (método de curses.window)

getblocking() (método de socket.socket)

getboolean() (método de configparser.ConfigParser)

getbuffer() (método de io.BytesIO)

getbufferproc (tipo C)

getByteStream() (método de xml.sax.xmlreader.InputSource)

getcallargs() (en el módulo inspect)

getcanvas() (en el módulo turtle)

getcapabilities() (método de nntplib.NNTP)

getcaps() (en el módulo mailcap)

getch() (en el módulo msvcrt)

(método de curses.window)

getCharacterStream() (método de xml.sax.xmlreader.InputSource)

getche() (en el módulo msvcrt)

getChild() (método de logging.Logger)

getclasstree() (en el módulo inspect)

getclosurevars() (en el módulo inspect)

GetColumnInfo() (método de msilib.View)

getColumnNumber() (método de xml.sax.xmlreader.Locator)

getcomments() (en el módulo inspect)

getcompname() (método de aifc.aifc)

(método de sunau.AU_read)

(método de wave.Wave_read)

getcomptype() (método de aifc.aifc)

(método de sunau.AU_read)

(método de wave.Wave_read)

getContentHandler() (método de xml.sax.xmlreader.XMLReader)

getcontext() (en el módulo decimal)

getcoroutinelocals() (en el módulo inspect)

getcoroutinestate() (en el módulo inspect)

getctime() (en el módulo os.path)

getcwd() (en el módulo os)

getcwdb() (en el módulo os)

getcwdu (2to3 fixer)

getdecoder() (en el módulo codecs)

getdefaultencoding() (en el módulo sys)

getdefaultlocale() (en el módulo locale)

getdefaulttimeout() (en el módulo socket)

getdlopenflags() (en el módulo sys)

getdoc() (en el módulo inspect)

getDOMImplementation() (en el módulo xml.dom)

getDTDHandler() (método de xml.sax.xmlreader.XMLReader)

getEffectiveLevel() (método de logging.Logger)

getegid() (en el módulo os)

getElementsByTagName() (método de xml.dom.Document)

(método de xml.dom.Element)

getElementsByTagNameNS() (método de xml.dom.Document)

(método de xml.dom.Element)

getencoder() (en el módulo codecs)

getEncoding() (método de xml.sax.xmlreader.InputSource)

getEntityResolver() (método de xml.sax.xmlreader.XMLReader)

getenv() (en el módulo os)

getenvb() (en el módulo os)

getErrorHandler() (método de xml.sax.xmlreader.XMLReader)

geteuid() (en el módulo os)

getEvent() (método de xml.dom.pulldom.DOMEventStream)

getEventCategory() (método de logging.handlers.NTEventLogHandler)

getEventType() (método de logging.handlers.NTEventLogHandler)

getException() (método de xml.sax.SAXException)

getFeature() (método de xml.sax.xmlreader.XMLReader)

GetFieldCount() (método de msilib.Record)

getfile() (en el módulo inspect)

getFilesToDelete() (método de logging.handlers.TimedRotatingFileHandler)

getfilesystemencodeerrors() (en el módulo sys)

getfilesystemencoding() (en el módulo sys)

getfirst() (método de cgi.FieldStorage)

getfloat() (método de configparser.ConfigParser)

getfmts() (método de ossaudiodev.oss_audio_device)

getfqdn() (en el módulo socket)

getframeinfo() (en el módulo inspect)

getframerate() (método de aifc.aifc)

(método de sunau.AU_read)

(método de wave.Wave_read)

getfullargspec() (en el módulo inspect)

getgeneratorlocals() (en el módulo inspect)

getgeneratorstate() (en el módulo inspect)

getgid() (en el módulo os)

getgrall() (en el módulo grp)

getgrgid() (en el módulo grp)

getgrnam() (en el módulo grp)

getgrouplist() (en el módulo os)

getgroups() (en el módulo os)

getheader() (método de http.client.HTTPResponse)

getheaders() (método de http.client.HTTPResponse)

gethostbyaddr() (en el módulo socket)

(in module socket)

gethostbyname() (en el módulo socket)

gethostbyname_ex() (en el módulo socket)

gethostname() (en el módulo socket)

(in module socket)

getincrementaldecoder() (en el módulo codecs)

getincrementalencoder() (en el módulo codecs)

getinfo() (método de zipfile.ZipFile)

getinnerframes() (en el módulo inspect)

GetInputContext() (método de xml.parsers.expat.xmlparser)

getint() (método de configparser.ConfigParser)

GetInteger() (método de msilib.Record)

getitem() (en el módulo operator)

getiterfunc (tipo C)

getitimer() (en el módulo signal)

getkey() (método de curses.window)

GetLastError() (en el módulo ctypes)

getLength() (método de xml.sax.xmlreader.Attributes)

getLevelName() (en el módulo logging)

getline() (en el módulo linecache)

getLineNumber() (método de xml.sax.xmlreader.Locator)

getlist() (método de cgi.FieldStorage)

getloadavg() (en el módulo os)

getlocale() (en el módulo locale)

getLogger() (en el módulo logging)

getLoggerClass() (en el módulo logging)

getlogin() (en el módulo os)

getLogRecordFactory() (en el módulo logging)

getmark() (método de aifc.aifc)

(método de sunau.AU_read)

(método de wave.Wave_read)

getmarkers() (método de aifc.aifc)

(método de sunau.AU_read)

(método de wave.Wave_read)

getmaxyx() (método de curses.window)

getmember() (método de tarfile.TarFile)

getmembers() (en el módulo inspect)

(método de tarfile.TarFile)

getMessage() (método de logging.LogRecord)

(método de xml.sax.SAXException)

getMessageID() (método de logging.handlers.NTEventLogHandler)

getmodule() (en el módulo inspect)

getmodulename() (en el módulo inspect)

getmouse() (en el módulo curses)

getmro() (en el módulo inspect)

getmtime() (en el módulo os.path)

getname() (método de chunk.Chunk)

getName() (método de threading.Thread)

getNameByQName() (método de xml.sax.xmlreader.AttributesNS)

getnameinfo() (en el módulo socket)

(método de asyncio.loop)

getnames() (método de tarfile.TarFile)

getNames() (método de xml.sax.xmlreader.Attributes)

getnchannels() (método de aifc.aifc)

(método de sunau.AU_read)

(método de wave.Wave_read)

getnframes() (método de aifc.aifc)

(método de sunau.AU_read)

(método de wave.Wave_read)

getnode

getnode() (en el módulo uuid)

getopt (módulo)

getopt() (en el módulo getopt)

(método de distutils.fancy_getopt.FancyGetopt)

GetoptError

getouterframes() (en el módulo inspect)

getoutput() (en el módulo subprocess)

getpagesize() (en el módulo resource)

getparams() (método de aifc.aifc)

(método de sunau.AU_read)

(método de wave.Wave_read)

getparyx() (método de curses.window)

getpass (módulo)

getpass() (en el módulo getpass)

GetPassWarning

getpeercert() (método de ssl.SSLSocket)

getpeername() (método de socket.socket)

getpen() (en el módulo turtle)

getpgid() (en el módulo os)

getpgrp() (en el módulo os)

getpid() (en el módulo os)

getpos() (método de html.parser.HTMLParser)

getppid() (en el módulo os)

getpreferredencoding() (en el módulo locale)

getpriority() (en el módulo os)

getprofile() (en el módulo sys)

GetProperty() (método de msilib.SummaryInformation)

getProperty() (método de xml.sax.xmlreader.XMLReader)

GetPropertyCount() (método de msilib.SummaryInformation)

getprotobyname() (en el módulo socket)

getproxies() (en el módulo urllib.request)

getPublicId() (método de xml.sax.xmlreader.InputSource)

(método de xml.sax.xmlreader.Locator)

getpwall() (en el módulo pwd)

getpwnam() (en el módulo pwd)

getpwuid() (en el módulo pwd)

getQNameByName() (método de xml.sax.xmlreader.AttributesNS)

getQNames() (método de xml.sax.xmlreader.AttributesNS)

getquota() (método de imaplib.IMAP4)

getquotaroot() (método de imaplib.IMAP4)

getrandbits() (en el módulo random)

getrandom() (en el módulo os)

getreader() (en el módulo codecs)

getrecursionlimit() (en el módulo sys)

getrefcount() (en el módulo sys)

getresgid() (en el módulo os)

getresponse() (método de http.client.HTTPConnection)

getresuid() (en el módulo os)

getrlimit() (en el módulo resource)

getroot() (método de xml.etree.ElementTree.ElementTree)

getrusage() (en el módulo resource)

getsample() (en el módulo audioop)

getsampwidth() (método de aifc.aifc)

(método de sunau.AU_read)

(método de wave.Wave_read)

getscreen() (en el módulo turtle)

getservbyname() (en el módulo socket)

getservbyport() (en el módulo socket)

GetSetDescriptorType (en el módulo types)

getshapes() (en el módulo turtle)

getsid() (en el módulo os)

getsignal() (en el módulo signal)

getsitepackages() (en el módulo site)

getsize() (en el módulo os.path)

(método de chunk.Chunk)

getsizeof() (en el módulo sys)

getsockname() (método de socket.socket)

getsockopt() (método de socket.socket)

getsource() (en el módulo inspect)

getsourcefile() (en el módulo inspect)

getsourcelines() (en el módulo inspect)

getspall() (en el módulo spwd)

getspnam() (en el módulo spwd)

getstate() (en el módulo random)

(método de codecs.IncrementalDecoder)

(método de codecs.IncrementalEncoder)

getstatus() (método de http.client.HTTPResponse)

(método de urllib.response.addinfourl)

getstatusoutput() (en el módulo subprocess)

getstr() (método de curses.window)

GetString() (método de msilib.Record)

getSubject() (método de logging.handlers.SMTPHandler)

GetSummaryInformation() (método de msilib.Database)

getswitchinterval() (en el módulo sys)

getSystemId() (método de xml.sax.xmlreader.InputSource)

(método de xml.sax.xmlreader.Locator)

getsyx() (en el módulo curses)

gettarinfo() (método de tarfile.TarFile)

gettempdir() (en el módulo tempfile)

gettempdirb() (en el módulo tempfile)

gettempprefix() (en el módulo tempfile)

gettempprefixb() (en el módulo tempfile)

getTestCaseNames() (método de unittest.TestLoader)

gettext (módulo)

gettext() (en el módulo gettext)

(en el módulo locale)

(método de gettext.GNUTranslations)

(método de gettext.NullTranslations)

gettimeout() (método de socket.socket)

gettrace() (en el módulo sys)

getturtle() (en el módulo turtle)

getType() (método de xml.sax.xmlreader.Attributes)

getuid() (en el módulo os)

geturl() (método de http.client.HTTPResponse)

(método de urllib.parse.urllib.parse.SplitResult)

(método de urllib.response.addinfourl)

getuser() (en el módulo getpass)

getuserbase() (en el módulo site)

getusersitepackages() (en el módulo site)

getvalue() (método de io.BytesIO)

(método de io.StringIO)

getValue() (método de xml.sax.xmlreader.Attributes)

getValueByQName() (método de xml.sax.xmlreader.AttributesNS)

getwch() (en el módulo msvcrt)

getwche() (en el módulo msvcrt)

getweakrefcount() (en el módulo weakref)

getweakrefs() (en el módulo weakref)

getwelcome() (método de ftplib.FTP)

(método de nntplib.NNTP)

(método de poplib.POP3)

getwin() (en el módulo curses)

getwindowsversion() (en el módulo sys)

getwriter() (en el módulo codecs)

getxattr() (en el módulo os)

getyx() (método de curses.window)

gid (atributo de tarfile.TarInfo)

GIL

glob

módulo

glob (módulo)

glob() (en el módulo glob)

(método de msilib.Directory)

(método de pathlib.Path)

global

name binding

namespace

sentencia, [1]

Global (clase en ast)

global interpreter lock

globals() (función incorporada)

globs (atributo de doctest.DocTest)

gmtime() (en el módulo time)

gname (atributo de tarfile.TarInfo)

GNOME

GNU_FORMAT (en el módulo tarfile)

gnu_getopt() (en el módulo getopt)

GNUTranslations (clase en gettext)

go() (método de tkinter.filedialog.FileDialog)

got (atributo de doctest.DocTestFailure)

goto() (en el módulo turtle)

grammar

Graphical User Interface

graphlib (módulo)

GREATER (en el módulo token)

GREATEREQUAL (en el módulo token)

Greenwich Mean Time

GRND_NONBLOCK (en el módulo os)

GRND_RANDOM (en el módulo os)

Group (clase en email.headerregistry)

group() (método de nntplib.NNTP)

(método de pathlib.Path)

(método de re.Match)

groupby() (en el módulo itertools)

groupdict() (método de re.Match)

groupindex (atributo de re.Pattern)

grouping

groups (atributo de email.headerregistry.AddressHeader)

(atributo de re.Pattern)

groups() (método de re.Match)

grp (módulo)

Gt (clase en ast)

gt() (en el módulo operator)

GtE (clase en ast)

guess_all_extensions() (en el módulo mimetypes)

(método de mimetypes.MimeTypes)

guess_extension() (en el módulo mimetypes)

(método de mimetypes.MimeTypes)

guess_scheme() (en el módulo wsgiref.util)

guess_type() (en el módulo mimetypes)

(método de mimetypes.MimeTypes)

GUI

gzip (módulo)

gzip command line option

--best

--decompress

--fast

--help

-d

-h

file

GzipFile (clase en gzip)

Índice – H

halfdelay() (en el módulo curses)

Handle (clase en asyncio)

handle an exception

handle() (método de http.server.BaseHTTPRequestHandler)

(método de logging.Handler)

(método de logging.handlers.QueueListener)

(método de logging.Logger)

(método de logging.NullHandler)

(método de socketserver.BaseRequestHandler)

(método de wsgiref.simple_server.WSGIRequestHandler)

handle_accept() (método de asyncore.dispatcher)

handle_accepted() (método de asyncore.dispatcher)

handle_charref() (método de html.parser.HTMLParser)

handle_close() (método de asyncore.dispatcher)

handle_comment() (método de html.parser.HTMLParser)

handle_connect() (método de asyncore.dispatcher)

handle_data() (método de html.parser.HTMLParser)

handle_decl() (método de html.parser.HTMLParser)

handle_defect() (método de email.policy.Policy)

handle_endtag() (método de html.parser.HTMLParser)

handle_entityref() (método de html.parser.HTMLParser)

handle_error() (método de asyncore.dispatcher)

(método de socketserver.BaseServer)

handle_expect_100() (método de http.server.BaseHTTPRequestHandler)

handle_expt() (método de asyncore.dispatcher)

handle_one_request() (método de http.server.BaseHTTPRequestHandler)

handle_pi() (método de html.parser.HTMLParser)

handle_read() (método de asyncore.dispatcher)

handle_request() (método de socketserver.BaseServer)

(método de xmlrpc.server.CGIXMLRPCRequestHandler)

handle_startendtag() (método de html.parser.HTMLParser)

handle_starttag() (método de html.parser.HTMLParser)

handle_timeout() (método de socketserver.BaseServer)

handle_write() (método de asyncore.dispatcher)

handleError() (método de logging.Handler)

(método de logging.handlers.SocketHandler)

handler

exception

Handler (clase en logging)

handler() (en el módulo cgitb)

harmonic_mean() (en el módulo statistics)

HAS_ALPN (en el módulo ssl)

has_children() (método de symtable.SymbolTable)

has_colors() (en el módulo curses)

has_dualstack_ipv6() (en el módulo socket)

HAS_ECDH (en el módulo ssl)

has_extn() (método de smtplib.SMTP)

has_function() (método de distutils.ccompiler.CCompiler)

has_header() (método de csv.Sniffer)

(método de urllib.request.Request)

has_ic() (en el módulo curses)

has_il() (en el módulo curses)

has_ipv6 (en el módulo socket)

has_key (2to3 fixer)

has_key() (en el módulo curses)

has_location (atributo de importlib.machinery.ModuleSpec)

HAS_NEVER_CHECK_COMMON_NAME (en el módulo ssl)

has_nonstandard_attr() (método de http.cookiejar.Cookie)

HAS_NPN (en el módulo ssl)

has_option() (método de configparser.ConfigParser)

(método de optparse.OptionParser)

has_section() (método de configparser.ConfigParser)

HAS_SNI (en el módulo ssl)

HAS_SSLv2 (en el módulo ssl)

HAS_SSLv3 (en el módulo ssl)

has_ticket (atributo de ssl.SSLSession)

HAS_TLSv1 (en el módulo ssl)

HAS_TLSv1_1 (en el módulo ssl)

HAS_TLSv1_2 (en el módulo ssl)

HAS_TLSv1_3 (en el módulo ssl)

hasattr() (función incorporada)

hasAttribute() (método de xml.dom.Element)

hasAttributeNS() (método de xml.dom.Element)

hasAttributes() (método de xml.dom.Node)

hasChildNodes() (método de xml.dom.Node)

hascompare (en el módulo dis)

hasconst (en el módulo dis)

hasFeature() (método de xml.dom.DOMImplementation)

hasfree (en el módulo dis)

hash

función incorporada, [1], [2], [3]

hash character

hash() (función incorporada)

hash-based pyc

hash.block_size (en el módulo hashlib)

hash.digest_size (en el módulo hashlib)

hash_info (en el módulo sys)

hashable, [1]

Hashable (clase en collections.abc)

(clase en typing)

hasHandlers() (método de logging.Logger)

hashfunc (tipo C)

hashlib (módulo)

hasjabs (en el módulo dis)

hasjrel (en el módulo dis)

haslocal (en el módulo dis)

hasname (en el módulo dis)

HAVE_ARGUMENT (opcode)

HAVE_CONTEXTVAR (en el módulo decimal)

HAVE_DOCSTRINGS (en el módulo test.support)

HAVE_THREADS (en el módulo decimal)

HCI_DATA_DIR (en el módulo socket)

HCI_FILTER (en el módulo socket)

HCI_TIME_STAMP (en el módulo socket)

head() (método de nntplib.NNTP)

Header (clase en email.header)

header_encode() (método de email.charset.Charset)

header_encode_lines() (método de email.charset.Charset)

header_encoding (atributo de email.charset.Charset)

header_factory (atributo de email.policy.EmailPolicy)

header_fetch_parse() (método de email.policy.Compat32)

(método de email.policy.EmailPolicy)

(método de email.policy.Policy)

header_items() (método de urllib.request.Request)

header_max_count() (método de email.policy.EmailPolicy)

(método de email.policy.Policy)

header_offset (atributo de zipfile.ZipInfo)

header_source_parse() (método de email.policy.Compat32)

(método de email.policy.EmailPolicy)

(método de email.policy.Policy)

header_store_parse() (método de email.policy.Compat32)

(método de email.policy.EmailPolicy)

(método de email.policy.Policy)

HeaderError

HeaderParseError

HeaderParser (clase en email.parser)

HeaderRegistry (clase en email.headerregistry)

headers

MIME, [1]

headers (atributo de http.client.HTTPResponse)

(atributo de http.server.BaseHTTPRequestHandler)

(atributo de urllib.error.HTTPError)

(atributo de urllib.response.addinfourl)

(atributo de xmlrpc.client.ProtocolError)

Headers (clase en wsgiref.headers)

heading() (en el módulo turtle)

(método de tkinter.ttk.Treeview)

heapify() (en el módulo heapq)

heapmin() (en el módulo msvcrt)

heappop() (en el módulo heapq)

heappush() (en el módulo heapq)

heappushpop() (en el módulo heapq)

heapq (módulo)

heapreplace() (en el módulo heapq)

helo() (método de smtplib.SMTP)

help

función incorporada

online

help (atributo de optparse.Option)

(pdb command)

help() (función incorporada)

(método de nntplib.NNTP)

herror

hex (atributo de uuid.UUID)

hex() (función incorporada)

(método de bytearray)

(método de bytes)

(método de float)

(método de memoryview)

hexadecimal

literals

hexadecimal literal

hexbin() (en el módulo binhex)

hexdigest() (método de hashlib.hash)

(método de hashlib.shake)

(método de hmac.HMAC)

hexdigits (en el módulo string)

hexlify() (en el módulo binascii)

hexversion (en el módulo sys)

hidden() (método de curses.panel.Panel)

hide() (método de curses.panel.Panel)

(método de tkinter.ttk.Notebook)

hide_cookie2 (atributo de http.cookiejar.CookiePolicy)

hideturtle() (en el módulo turtle)

hierarchy

type

HierarchyRequestErr

HIGH_PRIORITY_CLASS (en el módulo subprocess)

HIGHEST_PROTOCOL (en el módulo pickle)

HKEY_CLASSES_ROOT (en el módulo winreg)

HKEY_CURRENT_CONFIG (en el módulo winreg)

HKEY_CURRENT_USER (en el módulo winreg)

HKEY_DYN_DATA (en el módulo winreg)

HKEY_LOCAL_MACHINE (en el módulo winreg)

HKEY_PERFORMANCE_DATA (en el módulo winreg)

HKEY_USERS (en el módulo winreg)

hline() (método de curses.window)

HList (clase en tkinter.tix)

hls_to_rgb() (en el módulo colorsys)

hmac (módulo)

HOME, [1], [2], [3], [4], [5], [6], [7], [8], [9]

home() (en el módulo turtle)

(método de clase de pathlib.Path)

HOMEDRIVE, [1]

HOMEPATH, [1]

hook_compressed() (en el módulo fileinput)

hook_encoded() (en el módulo fileinput)

hooks

import

meta

path

host (atributo de urllib.request.Request)

hostmask (atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Network)

hostname_checks_common_name (atributo de ssl.SSLContext)

hosts (atributo de netrc.netrc)

hosts() (método de ipaddress.IPv4Network)

(método de ipaddress.IPv6Network)

hour (atributo de datetime.datetime)

(atributo de datetime.time)

HRESULT (clase en ctypes)

hStdError (atributo de subprocess.STARTUPINFO)

hStdInput (atributo de subprocess.STARTUPINFO)

hStdOutput (atributo de subprocess.STARTUPINFO)

hsv_to_rgb() (en el módulo colorsys)

ht() (en el módulo turtle)

HTML, [1]

html (módulo)

html() (en el módulo cgitb)

html.entities (módulo)

html.parser (módulo)

html5 (en el módulo html.entities)

HTMLCalendar (clase en calendar)

HtmlDiff (clase en difflib)

HTMLParser (clase en html.parser)

htonl() (en el módulo socket)

htons() (en el módulo socket)

HTTP

http (standard module)

http.client (standard module)

protocol, [1], [2], [3], [4], [5]

HTTP (en el módulo email.policy)

http (módulo)

http.client (módulo)

http.cookiejar (módulo)

http.cookies (módulo)

http.server

security

http.server (módulo)

http_error_301() (método de urllib.request.HTTPRedirectHandler)

http_error_302() (método de urllib.request.HTTPRedirectHandler)

http_error_303() (método de urllib.request.HTTPRedirectHandler)

http_error_307() (método de urllib.request.HTTPRedirectHandler)

http_error_401() (método de urllib.request.HTTPBasicAuthHandler)

(método de urllib.request.HTTPDigestAuthHandler)

http_error_407() (método de urllib.request.ProxyBasicAuthHandler)

(método de urllib.request.ProxyDigestAuthHandler)

http_error_auth_reqed() (método de urllib.request.AbstractBasicAuthHandler)

(método de urllib.request.AbstractDigestAuthHandler)

http_error_default() (método de urllib.request.BaseHandler)

http_open() (método de urllib.request.HTTPHandler)

HTTP_PORT (en el módulo http.client)

http_proxy, [1], [2]

http_response() (método de urllib.request.HTTPErrorProcessor)

http_version (atributo de wsgiref.handlers.BaseHandler)

HTTPBasicAuthHandler (clase en urllib.request)

HTTPConnection (clase en http.client)

HTTPCookieProcessor (clase en urllib.request)

httpd

HTTPDefaultErrorHandler (clase en urllib.request)

HTTPDigestAuthHandler (clase en urllib.request)

HTTPError

HTTPErrorProcessor (clase en urllib.request)

HTTPException

HTTPHandler (clase en logging.handlers)

(clase en urllib.request)

HTTPPasswordMgr (clase en urllib.request)

HTTPPasswordMgrWithDefaultRealm (clase en urllib.request)

HTTPPasswordMgrWithPriorAuth (clase en urllib.request)

HTTPRedirectHandler (clase en urllib.request)

HTTPResponse (clase en http.client)

https_open() (método de urllib.request.HTTPSHandler)

HTTPS_PORT (en el módulo http.client)

https_response() (método de urllib.request.HTTPErrorProcessor)

HTTPSConnection (clase en http.client)

HTTPServer (clase en http.server)

HTTPSHandler (clase en urllib.request)

HTTPStatus (clase en http)

hypot() (en el módulo math)

Índice – I

I (en el módulo re)

I/O control

buffering, [1]

POSIX

tty

UNIX

iadd() (en el módulo operator)

iand() (en el módulo operator)

iconcat() (en el módulo operator)

id

función incorporada

id (atributo de ssl.SSLSession)

id() (función incorporada)

(método de unittest.TestCase)

idcok() (método de curses.window)

ident (atributo de select.kevent)

(atributo de threading.Thread)

identchars (atributo de cmd.Cmd)

identifier, [1]

identify() (método de tkinter.ttk.Notebook)

(método de tkinter.ttk.Treeview)

(método de tkinter.ttk.Widget)

identify_column() (método de tkinter.ttk.Treeview)

identify_element() (método de tkinter.ttk.Treeview)

identify_region() (método de tkinter.ttk.Treeview)

identify_row() (método de tkinter.ttk.Treeview)

identity

test

identity of an object

idioms (2to3 fixer)

IDLE, [1]

IDLE_PRIORITY_CLASS (en el módulo subprocess)

IDLESTARTUP, [1], [2], [3]

idlok() (método de curses.window)

if

conditional expression

in comprehensions

sentencia, [1]

If (clase en ast)

if_indextoname() (en el módulo socket)

if_nameindex() (en el módulo socket)

if_nametoindex() (en el módulo socket)

IfExp (clase en ast)

ifloordiv() (en el módulo operator)

iglob() (en el módulo glob)

ignorableWhitespace() (método de xml.sax.handler.ContentHandler)

ignore

error handler's name

ignore (pdb command)

ignore_errors() (en el módulo codecs)

IGNORE_EXCEPTION_DETAIL (en el módulo doctest)

ignore_patterns() (en el módulo shutil)

IGNORECASE (en el módulo re)

ihave() (método de nntplib.NNTP)

IISCGIHandler (clase en wsgiref.handlers)

ilshift() (en el módulo operator)

imag (atributo de numbers.Complex)

imaginary literal

imap() (método de multiprocessing.pool.Pool)

IMAP4

protocol

IMAP4 (clase en imaplib)

IMAP4.abort

IMAP4.error

IMAP4.readonly

IMAP4_SSL

protocol

IMAP4_SSL (clase en imaplib)

IMAP4_stream

protocol

IMAP4_stream (clase en imaplib)

imap_unordered() (método de multiprocessing.pool.Pool)

imaplib (módulo)

imatmul() (en el módulo operator)

imghdr (módulo)

immedok() (método de curses.window)

immutable

data type

object, [1]

objeto

sequence types

immutable object

immutable sequence

objeto

immutable types

subclassing

imod() (en el módulo operator)

imp

módulo

imp (módulo)

ImpImporter (clase en pkgutil)

impl_detail() (en el módulo test.support)

implementation (en el módulo sys)

ImpLoader (clase en pkgutil)

import

hooks

sentencia, [1], [2], [3], [4]

import (2to3 fixer)

Import (clase en ast)

import hooks

import machinery

import_fresh_module() (en el módulo test.support)

IMPORT_FROM (opcode)

import_module() (en el módulo importlib)

(en el módulo test.support)

IMPORT_NAME (opcode)

IMPORT_STAR (opcode)

importador

importar

ImportError

excepción

ImportFrom (clase en ast)

importlib (módulo)

importlib.abc (módulo)

importlib.machinery (módulo)

importlib.metadata (módulo)

importlib.resources (módulo)

importlib.util (módulo)

imports (2to3 fixer)

imports2 (2to3 fixer)

ImportWarning

ImproperConnectionState

imul() (en el módulo operator)

in

operador, [1], [2]

palabra clave

In (clase en ast)

in_dll() (método de ctypes._CData)

in_table_a1() (en el módulo stringprep)

in_table_b1() (en el módulo stringprep)

in_table_c11() (en el módulo stringprep)

in_table_c11_c12() (en el módulo stringprep)

in_table_c12() (en el módulo stringprep)

in_table_c21() (en el módulo stringprep)

in_table_c21_c22() (en el módulo stringprep)

in_table_c22() (en el módulo stringprep)

in_table_c3() (en el módulo stringprep)

in_table_c4() (en el módulo stringprep)

in_table_c5() (en el módulo stringprep)

in_table_c6() (en el módulo stringprep)

in_table_c7() (en el módulo stringprep)

in_table_c8() (en el módulo stringprep)

in_table_c9() (en el módulo stringprep)

in_table_d1() (en el módulo stringprep)

in_table_d2() (en el módulo stringprep)

in_transaction (atributo de sqlite3.Connection)

inch() (método de curses.window)

inclusive

or

inclusive (atributo de tracemalloc.DomainFilter)

(atributo de tracemalloc.Filter)

Incomplete

IncompleteRead

IncompleteReadError

incr_item(), [1]

increment_lineno() (en el módulo ast)

incrementaldecoder (atributo de codecs.CodecInfo)

IncrementalDecoder (clase en codecs)

incrementalencoder (atributo de codecs.CodecInfo)

IncrementalEncoder (clase en codecs)

IncrementalNewlineDecoder (clase en io)

IncrementalParser (clase en xml.sax.xmlreader)

indent (atributo de doctest.Example)

INDENT (en el módulo token)

INDENT token

indent() (en el módulo textwrap)

(en el módulo xml.etree.ElementTree)

indentation

IndentationError

index operation

index() (en el módulo operator)

(método de array.array)

(método de bytearray)

(método de bytes)

(método de collections.deque)

(método de multiprocessing.shared_memory.ShareableList)

(método de str)

(método de tkinter.ttk.Notebook)

(método de tkinter.ttk.Treeview)

(sequence method)

IndexError

indexOf() (en el módulo operator)

IndexSizeErr

indicador de tipo

indices() (método de slice)

inet_aton() (en el módulo socket)

inet_ntoa() (en el módulo socket)

inet_ntop() (en el módulo socket)

inet_pton() (en el módulo socket)

Inexact (clase en decimal)

inf (en el módulo cmath)

(en el módulo math)

infile

json.tool command line option

infile (atributo de shlex.shlex)

Infinity

infj (en el módulo cmath)

info() (en el módulo logging)

(método de dis.Bytecode)

(método de gettext.NullTranslations)

(método de http.client.HTTPResponse)

(método de logging.Logger)

(método de urllib.response.addinfourl)

infolist() (método de zipfile.ZipFile)

inheritance

ini file

init() (en el módulo mimetypes)

init_color() (en el módulo curses)

init_database() (en el módulo msilib)

init_pair() (en el módulo curses)

inited (en el módulo mimetypes)

initgroups() (en el módulo os)

initial_indent (atributo de textwrap.TextWrapper)

initialize_options() (método de distutils.cmd.Command)

initproc (tipo C)

initscr() (en el módulo curses)

inmutable

inode() (método de os.DirEntry)

INPLACE_ADD (opcode)

INPLACE_AND (opcode)

INPLACE_FLOOR_DIVIDE (opcode)

INPLACE_LSHIFT (opcode)

INPLACE_MATRIX_MULTIPLY (opcode)

INPLACE_MODULO (opcode)

INPLACE_MULTIPLY (opcode)

INPLACE_OR (opcode)

INPLACE_POWER (opcode)

INPLACE_RSHIFT (opcode)

INPLACE_SUBTRACT (opcode)

INPLACE_TRUE_DIVIDE (opcode)

INPLACE_XOR (opcode)

input

(2to3 fixer)

input() (en el módulo fileinput)

(función incorporada)

input_charset (atributo de email.charset.Charset)

input_codec (atributo de email.charset.Charset)

InputOnly (clase en tkinter.tix)

InputSource (clase en xml.sax.xmlreader)

inquiry (tipo C)

insch() (método de curses.window)

insdelln() (método de curses.window)

insert() (método de array.array)

(método de collections.deque)

(método de tkinter.ttk.Notebook)

(método de tkinter.ttk.Treeview)

(método de xml.etree.ElementTree.Element)

(sequence method)

insert_text() (en el módulo readline)

insertBefore() (método de xml.dom.Node)

insertln() (método de curses.window)

insnstr() (método de curses.window)

insort() (en el módulo bisect)

insort_left() (en el módulo bisect)

insort_right() (en el módulo bisect)

inspect (módulo)

inspect command line option

--details

InspectLoader (clase en importlib.abc)

insstr() (método de curses.window)

install() (en el módulo gettext)

(método de gettext.NullTranslations)

install_opener() (en el módulo urllib.request)

install_scripts() (método de venv.EnvBuilder)

installHandler() (en el módulo unittest)

instance

call, [1]

class

objeto, [1], [2]

instancemethod

objeto

instate() (método de tkinter.ttk.Widget)

instr() (método de curses.window)

instream (atributo de shlex.shlex)

Instruction (clase en dis)

Instruction.arg (en el módulo dis)

Instruction.argrepr (en el módulo dis)

Instruction.argval (en el módulo dis)

Instruction.is_jump_target (en el módulo dis)

Instruction.offset (en el módulo dis)

Instruction.opcode (en el módulo dis)

Instruction.opname (en el módulo dis)

Instruction.starts_line (en el módulo dis)

int

función incorporada, [1], [2]

int (atributo de uuid.UUID)

(clase incorporada)

Int2AP() (en el módulo imaplib)

int_info (en el módulo sys)

integer

literals

objeto, [1], [2]

representation

types, operations on

integer literal

Integral (clase en numbers)

Integrated Development Environment

IntegrityError

Intel/DVI ADPCM

IntEnum (clase en enum)

interact (pdb command)

interact() (en el módulo code)

(método de code.InteractiveConsole)

(método de telnetlib.Telnet)

interactive mode

InteractiveConsole (clase en code)

InteractiveInterpreter (clase en code)

interactivo

intern (2to3 fixer)

intern() (en el módulo sys)

internal type

internal_attr (atributo de zipfile.ZipInfo)

Internaldate2tuple() (en el módulo imaplib)

internalSubset (atributo de xml.dom.DocumentType)

Internet

INTERNET_TIMEOUT (en el módulo test.support)

interpolated string literal

interpolation

bytearray (%)

bytes (%)

interpolation, string (%)

InterpolationDepthError

InterpolationError

InterpolationMissingOptionError

InterpolationSyntaxError

interpretado

interpreter

interpreter lock

interpreter prompts

interpreter_requires_environment() (en el módulo test.support.script_helper)

interrupt() (método de sqlite3.Connection)

interrupt_main() (en el módulo _thread)

InterruptedError

intersection() (método de frozenset)

intersection_update() (método de frozenset)

IntFlag (clase en enum)

intro (atributo de cmd.Cmd)

InuseAttributeErr

inv() (en el módulo operator)

inv_cdf() (método de statistics.NormalDist)

InvalidAccessErr

invalidate_caches() (en el módulo importlib)

(método de clase de importlib.machinery.PathFinder)

(método de importlib.abc.MetaPathFinder)

(método de importlib.abc.PathEntryFinder)

(método de importlib.machinery.FileFinder)

InvalidCharacterErr

InvalidModificationErr

InvalidOperation (clase en decimal)

InvalidStateErr

InvalidStateError, [1]

InvalidTZPathWarning

InvalidURL

inversion

Invert (clase en ast)

invert() (en el módulo operator)

invocation

io

módulo

IO (clase en typing)

io (módulo)

io.StringIO

objeto

IO_REPARSE_TAG_APPEXECLINK (en el módulo stat)

IO_REPARSE_TAG_MOUNT_POINT (en el módulo stat)

IO_REPARSE_TAG_SYMLINK (en el módulo stat)

IOBase (clase en io)

ioctl() (en el módulo fcntl)

(método de socket.socket)

IOCTL_VM_SOCKETS_GET_LOCAL_CID (en el módulo socket)

IOError

ior() (en el módulo operator)

ip (atributo de ipaddress.IPv4Interface)

(atributo de ipaddress.IPv6Interface)

ip_address() (en el módulo ipaddress)

ip_interface() (en el módulo ipaddress)

ip_network() (en el módulo ipaddress)

ipaddress (módulo)

ipow() (en el módulo operator)

ipv4_mapped (atributo de ipaddress.IPv6Address)

IPv4Address (clase en ipaddress)

IPv4Interface (clase en ipaddress)

IPv4Network (clase en ipaddress)

IPV6_ENABLED (en el módulo test.support.socket_helper)

IPv6Address (clase en ipaddress)

IPv6Interface (clase en ipaddress)

IPv6Network (clase en ipaddress)

irshift() (en el módulo operator)

is

operador, [1]

Is (clase en ast)

is not

operador, [1]

is_() (en el módulo operator)

is_absolute() (método de pathlib.PurePath)

is_active() (método de asyncio.AbstractChildWatcher)

(método de graphlib.TopologicalSorter)

is_alive() (método de multiprocessing.Process)

(método de threading.Thread)

is_android (en el módulo test.support)

is_annotated() (método de symtable.Symbol)

is_assigned() (método de symtable.Symbol)

is_attachment() (método de email.message.EmailMessage)

is_authenticated() (método de urllib.request.HTTPPasswordMgrWithPriorAuth)

is_block_device() (método de pathlib.Path)

is_blocked() (método de http.cookiejar.DefaultCookiePolicy)

is_canonical() (método de decimal.Context)

(método de decimal.Decimal)

is_char_device() (método de pathlib.Path)

IS_CHARACTER_JUNK() (en el módulo difflib)

is_check_supported() (en el módulo lzma)

is_closed() (método de asyncio.loop)

is_closing() (método de asyncio.BaseTransport)

(método de asyncio.StreamWriter)

is_dataclass() (en el módulo dataclasses)

is_declared_global() (método de symtable.Symbol)

is_dir() (método de importlib.abc.Traversable)

(método de os.DirEntry)

(método de pathlib.Path)

(método de zipfile.Path)

(método de zipfile.ZipInfo)

is_enabled() (en el módulo faulthandler)

is_expired() (método de http.cookiejar.Cookie)

is_fifo() (método de pathlib.Path)

is_file() (método de importlib.abc.Traversable)

(método de os.DirEntry)

(método de pathlib.Path)

(método de zipfile.Path)

is_finalized() (en el módulo gc)

is_finalizing() (en el módulo sys)

is_finite() (método de decimal.Context)

(método de decimal.Decimal)

is_free() (método de symtable.Symbol)

is_global (atributo de ipaddress.IPv4Address)

(atributo de ipaddress.IPv6Address)

is_global() (método de symtable.Symbol)

is_hop_by_hop() (en el módulo wsgiref.util)

is_imported() (método de symtable.Symbol)

is_infinite() (método de decimal.Context)

(método de decimal.Decimal)

is_integer() (método de float)

is_jython (en el módulo test.support)

IS_LINE_JUNK() (en el módulo difflib)

is_linetouched() (método de curses.window)

is_link_local (atributo de ipaddress.IPv4Address)

(atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Address)

(atributo de ipaddress.IPv6Network)

is_local() (método de symtable.Symbol)

is_loopback (atributo de ipaddress.IPv4Address)

(atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Address)

(atributo de ipaddress.IPv6Network)

is_mount() (método de pathlib.Path)

is_multicast (atributo de ipaddress.IPv4Address)

(atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Address)

(atributo de ipaddress.IPv6Network)

is_multipart() (método de email.message.EmailMessage)

(método de email.message.Message)

is_namespace() (método de symtable.Symbol)

is_nan() (método de decimal.Context)

(método de decimal.Decimal)

is_nested() (método de symtable.SymbolTable)

is_nonlocal() (método de symtable.Symbol)

is_normal() (método de decimal.Context)

(método de decimal.Decimal)

is_normalized() (en el módulo unicodedata)

is_not() (en el módulo operator)

is_not_allowed() (método de http.cookiejar.DefaultCookiePolicy)

IS_OP (opcode)

is_optimized() (método de symtable.SymbolTable)

is_package() (método de importlib.abc.InspectLoader)

(método de importlib.abc.SourceLoader)

(método de importlib.machinery.ExtensionFileLoader)

(método de importlib.machinery.SourceFileLoader)

(método de importlib.machinery.SourcelessFileLoader)

(método de zipimport.zipimporter)

is_parameter() (método de symtable.Symbol)

is_private (atributo de ipaddress.IPv4Address)

(atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Address)

(atributo de ipaddress.IPv6Network)

is_python_build() (en el módulo sysconfig)

is_qnan() (método de decimal.Context)

(método de decimal.Decimal)

is_reading() (método de asyncio.ReadTransport)

is_referenced() (método de symtable.Symbol)

is_relative_to() (método de pathlib.PurePath)

is_reserved (atributo de ipaddress.IPv4Address)

(atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Address)

(atributo de ipaddress.IPv6Network)

is_reserved() (método de pathlib.PurePath)

is_resource() (en el módulo importlib.resources)

(método de importlib.abc.ResourceReader)

is_resource_enabled() (en el módulo test.support)

is_running() (método de asyncio.loop)

is_safe (atributo de uuid.UUID)

is_serving() (método de asyncio.Server)

is_set() (método de asyncio.Event)

(método de threading.Event)

is_signed() (método de decimal.Context)

(método de decimal.Decimal)

is_site_local (atributo de ipaddress.IPv6Address)

(atributo de ipaddress.IPv6Network)

is_snan() (método de decimal.Context)

(método de decimal.Decimal)

is_socket() (método de pathlib.Path)

is_subnormal() (método de decimal.Context)

(método de decimal.Decimal)

is_symlink() (método de os.DirEntry)

(método de pathlib.Path)

is_tarfile() (en el módulo tarfile)

is_term_resized() (en el módulo curses)

is_tracing() (en el módulo tracemalloc)

is_tracked() (en el módulo gc)

is_unspecified (atributo de ipaddress.IPv4Address)

(atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Address)

(atributo de ipaddress.IPv6Network)

is_wintouched() (método de curses.window)

is_zero() (método de decimal.Context)

(método de decimal.Decimal)

is_zipfile() (en el módulo zipfile)

isabs() (en el módulo os.path)

isabstract() (en el módulo inspect)

IsADirectoryError

isalnum() (en el módulo curses.ascii)

(método de bytearray)

(método de bytes)

(método de str)

isalpha() (en el módulo curses.ascii)

(método de bytearray)

(método de bytes)

(método de str)

isascii() (en el módulo curses.ascii)

(método de bytearray)

(método de bytes)

(método de str)

isasyncgen() (en el módulo inspect)

isasyncgenfunction() (en el módulo inspect)

isatty() (en el módulo os)

(método de chunk.Chunk)

(método de io.IOBase)

isawaitable() (en el módulo inspect)

isblank() (en el módulo curses.ascii)

isblk() (método de tarfile.TarInfo)

isbuiltin() (en el módulo inspect)

ischr() (método de tarfile.TarInfo)

isclass() (en el módulo inspect)

isclose() (en el módulo cmath)

(en el módulo math)

iscntrl() (en el módulo curses.ascii)

iscode() (en el módulo inspect)

iscoroutine() (en el módulo asyncio)

(en el módulo inspect)

iscoroutinefunction() (en el módulo asyncio)

(en el módulo inspect)

isctrl() (en el módulo curses.ascii)

isDaemon() (método de threading.Thread)

isdatadescriptor() (en el módulo inspect)

isdecimal() (método de str)

isdev() (método de tarfile.TarInfo)

isdigit() (en el módulo curses.ascii)

(método de bytearray)

(método de bytes)

(método de str)

isdir() (en el módulo os.path)

(método de tarfile.TarInfo)

isdisjoint() (método de frozenset)

isdown() (en el módulo turtle)

iselement() (en el módulo xml.etree.ElementTree)

isenabled() (en el módulo gc)

isEnabledFor() (método de logging.Logger)

isendwin() (en el módulo curses)

ISEOF() (en el módulo token)

isexpr() (en el módulo parser)

(método de parser.ST)

isfifo() (método de tarfile.TarInfo)

isfile() (en el módulo os.path)

(método de tarfile.TarInfo)

isfinite() (en el módulo cmath)

(en el módulo math)

isfirstline() (en el módulo fileinput)

isframe() (en el módulo inspect)

isfunction() (en el módulo inspect)

isfuture() (en el módulo asyncio)

isgenerator() (en el módulo inspect)

isgeneratorfunction() (en el módulo inspect)

isgetsetdescriptor() (en el módulo inspect)

isgraph() (en el módulo curses.ascii)

isidentifier() (método de str)

isinf() (en el módulo cmath)

(en el módulo math)

isinstance (2to3 fixer)

isinstance() (función incorporada)

iskeyword() (en el módulo keyword)

isleap() (en el módulo calendar)

islice() (en el módulo itertools)

islink() (en el módulo os.path)

islnk() (método de tarfile.TarInfo)

islower() (en el módulo curses.ascii)

(método de bytearray)

(método de bytes)

(método de str)

ismemberdescriptor() (en el módulo inspect)

ismeta() (en el módulo curses.ascii)

ismethod() (en el módulo inspect)

ismethoddescriptor() (en el módulo inspect)

ismodule() (en el módulo inspect)

ismount() (en el módulo os.path)

isnan() (en el módulo cmath)

(en el módulo math)

ISNONTERMINAL() (en el módulo token)

IsNot (clase en ast)

isnumeric() (método de str)

isocalendar() (método de datetime.date)

(método de datetime.datetime)

isoformat() (método de datetime.date)

(método de datetime.datetime)

(método de datetime.time)

IsolatedAsyncioTestCase (clase en unittest)

isolation_level (atributo de sqlite3.Connection)

isoweekday() (método de datetime.date)

(método de datetime.datetime)

isprint() (en el módulo curses.ascii)

isprintable() (método de str)

ispunct() (en el módulo curses.ascii)

isqrt() (en el módulo math)

isreadable() (en el módulo pprint)

(método de pprint.PrettyPrinter)

isrecursive() (en el módulo pprint)

(método de pprint.PrettyPrinter)

isreg() (método de tarfile.TarInfo)

isReservedKey() (método de http.cookies.Morsel)

isroutine() (en el módulo inspect)

isSameNode() (método de xml.dom.Node)

issoftkeyword() (en el módulo keyword)

isspace() (en el módulo curses.ascii)

(método de bytearray)

(método de bytes)

(método de str)

isstdin() (en el módulo fileinput)

issubclass() (función incorporada)

issubset() (método de frozenset)

issuite() (en el módulo parser)

(método de parser.ST)

issuperset() (método de frozenset)

issym() (método de tarfile.TarInfo)

ISTERMINAL() (en el módulo token)

istitle() (método de bytearray)

(método de bytes)

(método de str)

istraceback() (en el módulo inspect)

isub() (en el módulo operator)

isupper() (en el módulo curses.ascii)

(método de bytearray)

(método de bytes)

(método de str)

isvisible() (en el módulo turtle)

isxdigit() (en el módulo curses.ascii)

ITALIC (en el módulo tkinter.font)

item

sequence

string

item selection

item() (método de tkinter.ttk.Treeview)

(método de xml.dom.NamedNodeMap)

(método de xml.dom.NodeList)

itemgetter() (en el módulo operator)

items() (método de configparser.ConfigParser)

(método de contextvars.Context)

(método de dict)

(método de email.message.EmailMessage)

(método de email.message.Message)

(método de mailbox.Mailbox)

(método de types.MappingProxyType)

(método de xml.etree.ElementTree.Element)

itemsize (atributo de array.array)

(atributo de memoryview)

ItemsView (clase en collections.abc)

(clase en typing)

iter() (función incorporada)

(método de xml.etree.ElementTree.Element)

(método de xml.etree.ElementTree.ElementTree)

iter_attachments() (método de email.message.EmailMessage)

iter_child_nodes() (en el módulo ast)

iter_fields() (en el módulo ast)

iter_importers() (en el módulo pkgutil)

iter_modules() (en el módulo pkgutil)

iter_parts() (método de email.message.EmailMessage)

iter_unpack() (en el módulo struct)

(método de struct.Struct)

iterable

unpacking

Iterable (clase en collections.abc)

(clase en typing)

iterable asincrónico

iterador

iterador asincrónico

iterador generador

iterador generador asincrónico

Iterator (clase en collections.abc)

(clase en typing)

iterator protocol

iterdecode() (en el módulo codecs)

iterdir() (método de importlib.abc.Traversable)

(método de pathlib.Path)

(método de zipfile.Path)

iterdump() (método de sqlite3.Connection)

iterencode() (en el módulo codecs)

(método de json.JSONEncoder)

iterfind() (método de xml.etree.ElementTree.Element)

(método de xml.etree.ElementTree.ElementTree)

iteritems() (método de mailbox.Mailbox)

iterkeys() (método de mailbox.Mailbox)

itermonthdates() (método de calendar.Calendar)

itermonthdays() (método de calendar.Calendar)

itermonthdays2() (método de calendar.Calendar)

itermonthdays3() (método de calendar.Calendar)

itermonthdays4() (método de calendar.Calendar)

iternextfunc (tipo C)

iterparse() (en el módulo xml.etree.ElementTree)

itertext() (método de xml.etree.ElementTree.Element)

itertools (2to3 fixer)

(módulo)

itertools_imports (2to3 fixer)

itervalues() (método de mailbox.Mailbox)

iterweekdays() (método de calendar.Calendar)

ITIMER_PROF (en el módulo signal)

ITIMER_REAL (en el módulo signal)

ITIMER_VIRTUAL (en el módulo signal)

ItimerError

itruediv() (en el módulo operator)

ixor() (en el módulo operator)

Índice – J

j

in numeric literal

Jansen, Jack

Java

language

java_ver() (en el módulo platform)

join() (en el módulo os.path)

(en el módulo shlex)

(método de asyncio.Queue)

(método de bytearray)

(método de bytes)

(método de multiprocessing.JoinableQueue)

(método de multiprocessing.pool.Pool)

(método de multiprocessing.Process)

(método de queue.Queue)

(método de str)

(método de threading.Thread)

join_thread() (en el módulo test.support)

(método de multiprocessing.Queue)

JoinableQueue (clase en multiprocessing)

JoinedStr (clase en ast)

joinpath() (método de importlib.abc.Traversable)

(método de pathlib.PurePath)

js_output() (método de http.cookies.BaseCookie)

(método de http.cookies.Morsel)

json

módulo

json (módulo)

json.tool (módulo)

json.tool command line option

--compact

--help

--indent

--json-lines

--no-ensure-ascii

--no-indent

--sort-keys

--tab

-h

infile

outfile

JSONDecodeError

JSONDecoder (clase en json)

JSONEncoder (clase en json)

jump (pdb command)

JUMP_ABSOLUTE (opcode)

JUMP_FORWARD (opcode)

JUMP_IF_FALSE_OR_POP (opcode)

JUMP_IF_NOT_EXC_MATCH (opcode)

JUMP_IF_TRUE_OR_POP (opcode)

Índice – K

kbhit() (en el módulo msvcrt)

KDEDIR

kevent() (en el módulo select)

key

(atributo de http.cookies.Morsel)

(atributo de zoneinfo.ZoneInfo)

key/datum pair

KEY_ALL_ACCESS (en el módulo winreg)

KEY_CREATE_LINK (en el módulo winreg)

KEY_CREATE_SUB_KEY (en el módulo winreg)

KEY_ENUMERATE_SUB_KEYS (en el módulo winreg)

KEY_EXECUTE (en el módulo winreg)

KEY_NOTIFY (en el módulo winreg)

KEY_QUERY_VALUE (en el módulo winreg)

KEY_READ (en el módulo winreg)

KEY_SET_VALUE (en el módulo winreg)

KEY_WOW64_32KEY (en el módulo winreg)

KEY_WOW64_64KEY (en el módulo winreg)

KEY_WRITE (en el módulo winreg)

KeyboardInterrupt

(built-in exception), [1]

KeyError

keylog_filename (atributo de ssl.SSLContext)

keyname() (en el módulo curses)

keypad() (método de curses.window)

keyrefs() (método de weakref.WeakKeyDictionary)

keys() (método de contextvars.Context)

(método de dict)

(método de email.message.EmailMessage)

(método de email.message.Message)

(método de mailbox.Mailbox)

(método de sqlite3.Row)

(método de types.MappingProxyType)

(método de xml.etree.ElementTree.Element)

KeysView (clase en collections.abc)

(clase en typing)

keyword

(clase en ast)

(módulo)

keywords (atributo de functools.partial)

kill() (en el módulo os)

(método de asyncio.subprocess.Process)

(método de asyncio.SubprocessTransport)

(método de multiprocessing.Process)

(método de subprocess.Popen)

kill_python() (en el módulo test.support.script_helper)

killchar() (en el módulo curses)

killpg() (en el módulo os)

kind (atributo de inspect.Parameter)

knownfiles (en el módulo mimetypes)

kqueue() (en el módulo select)

KqueueSelector (clase en selectors)

kwargs (atributo de inspect.BoundArguments)

kwlist (en el módulo keyword)

Índice – L

L (en el módulo re)

LabelEntry (clase en tkinter.tix)

LabelFrame (clase en tkinter.tix)

lambda

expression, [1]

form

Lambda (clase en ast)

LambdaType (en el módulo types)

LANG, [1], [2], [3], [4]

LANGUAGE, [1]

language

C, [1], [2], [3], [4], [5]

Java

large files

LARGEST (en el módulo test.support)

LargeZipFile

last() (método de nntplib.NNTP)

last_accepted (atributo de multiprocessing.connection.Listener)

last_traceback (en el módulo sys)

(in module sys)

last_type (en el módulo sys)

last_value (en el módulo sys)

lastChild (atributo de xml.dom.Node)

lastcmd (atributo de cmd.Cmd)

lastgroup (atributo de re.Match)

lastindex (atributo de re.Match)

lastResort (en el módulo logging)

lastrowid (atributo de sqlite3.Cursor)

layout() (método de tkinter.ttk.Style)

lazycache() (en el módulo linecache)

LazyLoader (clase en importlib.util)

LBRACE (en el módulo token)

LBYL

LC_ALL, [1]

(en el módulo locale)

LC_COLLATE (en el módulo locale)

LC_CTYPE (en el módulo locale)

LC_MESSAGES, [1]

(en el módulo locale)

LC_MONETARY (en el módulo locale)

LC_NUMERIC (en el módulo locale)

LC_TIME (en el módulo locale)

lchflags() (en el módulo os)

lchmod() (en el módulo os)

(método de pathlib.Path)

lchown() (en el módulo os)

lcm() (en el módulo math)

LDCXXSHARED

ldexp() (en el módulo math)

LDFLAGS

ldgettext() (en el módulo gettext)

ldngettext() (en el módulo gettext)

le() (en el módulo operator)

leading whitespace

leapdays() (en el módulo calendar)

leaveok() (método de curses.window)

left (atributo de filecmp.dircmp)

left() (en el módulo turtle)

left_list (atributo de filecmp.dircmp)

left_only (atributo de filecmp.dircmp)

LEFTSHIFT (en el módulo token)

LEFTSHIFTEQUAL (en el módulo token)

len

función incorporada, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11]

len() (función incorporada)

lenfunc (tipo C)

length (atributo de xml.dom.NamedNodeMap)

(atributo de xml.dom.NodeList)

length_hint() (en el módulo operator)

LESS (en el módulo token)

LESSEQUAL (en el módulo token)

lexical analysis

lexical definitions

lexists() (en el módulo os.path)

lgamma() (en el módulo math)

lgettext() (en el módulo gettext)

(método de gettext.GNUTranslations)

(método de gettext.NullTranslations)

lib2to3 (módulo)

libc_ver() (en el módulo platform)

library (atributo de ssl.SSLError)

(en el módulo dbm.ndbm)

library_dir_option() (método de distutils.ccompiler.CCompiler)

library_filename() (método de distutils.ccompiler.CCompiler)

library_option() (método de distutils.ccompiler.CCompiler)

LibraryLoader (clase en ctypes)

license (variable incorporada)

LifoQueue (clase en asyncio)

(clase en queue)

light-weight processes

limit_denominator() (método de fractions.Fraction)

LimitOverrunError

lin2adpcm() (en el módulo audioop)

lin2alaw() (en el módulo audioop)

lin2lin() (en el módulo audioop)

lin2ulaw() (en el módulo audioop)

line continuation

line joining, [1]

line structure

line() (método de msilib.Dialog)

line-buffered I/O

line_buffering (atributo de io.TextIOWrapper)

line_num (atributo de csv.csvreader)

linecache (módulo)

lineno (atributo de ast.AST)

(atributo de doctest.DocTest)

(atributo de doctest.Example)

(atributo de json.JSONDecodeError)

(atributo de pyclbr.Class)

(atributo de pyclbr.Function)

(atributo de re.error)

(atributo de shlex.shlex)

(atributo de SyntaxError)

(atributo de traceback.TracebackException)

(atributo de tracemalloc.Filter)

(atributo de tracemalloc.Frame)

(atributo de xml.parsers.expat.ExpatError)

lineno() (en el módulo fileinput)

LINES, [1], [2], [3], [4]

lines (atributo de os.terminal_size)

linesep (atributo de email.policy.Policy)

(en el módulo os)

lineterminator (atributo de csv.Dialect)

LineTooLong

link() (en el módulo os)

(método de distutils.ccompiler.CCompiler)

link_executable() (método de distutils.ccompiler.CCompiler)

link_shared_lib() (método de distutils.ccompiler.CCompiler)

link_shared_object() (método de distutils.ccompiler.CCompiler)

link_to() (método de pathlib.Path)

linkname (atributo de tarfile.TarInfo)

LinkOutsideDestinationError

list

assignment, target

comprehensions

deletion target

display

empty

expression, [1], [2]

objeto, [1], [2], [3], [4], [5], [6], [7], [8]

target, [1]

type, operations on

List (clase en ast)

(clase en typing)

list (clase incorporada)

(pdb command)

list() (método de imaplib.IMAP4)

(método de multiprocessing.managers.SyncManager)

(método de nntplib.NNTP)

(método de poplib.POP3)

(método de tarfile.TarFile)

LIST_APPEND (opcode)

list_dialects() (en el módulo csv)

LIST_EXTEND (opcode)

list_folders() (método de mailbox.Maildir)

(método de mailbox.MH)

LIST_TO_TUPLE (opcode)

lista

ListComp (clase en ast)

listdir() (en el módulo os)

listen() (en el módulo logging.config)

(en el módulo turtle)

(método de asyncore.dispatcher)

(método de socket.socket)

Listener (clase en multiprocessing.connection)

listMethods() (método de xmlrpc.client.ServerProxy.system)

ListNoteBook (clase en tkinter.tix)

listxattr() (en el módulo os)

literal, [1]

Literal (en el módulo typing)

literal_eval() (en el módulo ast)

literals

binary

complex number

floating point

hexadecimal

integer

numeric

octal

LittleEndianStructure (clase en ctypes)

ljust() (método de bytearray)

(método de bytes)

(método de str)

LK_LOCK (en el módulo msvcrt)

LK_NBLCK (en el módulo msvcrt)

LK_NBRLCK (en el módulo msvcrt)

LK_RLCK (en el módulo msvcrt)

LK_UNLCK (en el módulo msvcrt)

ll (pdb command)

LMTP (clase en smtplib)

ln() (método de decimal.Context)

(método de decimal.Decimal)

LNAME

lngettext() (en el módulo gettext)

(método de gettext.GNUTranslations)

(método de gettext.NullTranslations)

Load (clase en ast)

load() (en el módulo json)

(en el módulo marshal)

(en el módulo pickle)

(en el módulo plistlib)

(método de clase de tracemalloc.Snapshot)

(método de http.cookiejar.FileCookieJar)

(método de http.cookies.BaseCookie)

(método de pickle.Unpickler)

LOAD_ASSERTION_ERROR (opcode)

LOAD_ATTR (opcode)

LOAD_BUILD_CLASS (opcode)

load_cert_chain() (método de ssl.SSLContext)

LOAD_CLASSDEREF (opcode)

LOAD_CLOSURE (opcode)

LOAD_CONST (opcode)

load_default_certs() (método de ssl.SSLContext)

LOAD_DEREF (opcode)

load_dh_params() (método de ssl.SSLContext)

load_extension() (método de sqlite3.Connection)

LOAD_FAST (opcode)

LOAD_GLOBAL (opcode)

LOAD_METHOD (opcode)

load_module() (en el módulo imp)

(método de importlib.abc.FileLoader)

(método de importlib.abc.InspectLoader)

(método de importlib.abc.Loader)

(método de importlib.abc.SourceLoader)

(método de importlib.machinery.SourceFileLoader)

(método de importlib.machinery.SourcelessFileLoader)

(método de zipimport.zipimporter)

LOAD_NAME (opcode)

load_package_tests() (en el módulo test.support)

load_verify_locations() (método de ssl.SSLContext)

loader

(atributo de importlib.machinery.ModuleSpec)

Loader (clase en importlib.abc)

loader_state (atributo de importlib.machinery.ModuleSpec)

LoadError

LoadFileDialog (clase en tkinter.filedialog)

LoadKey() (en el módulo winreg)

LoadLibrary() (método de ctypes.LibraryLoader)

loads() (en el módulo json)

(en el módulo marshal)

(en el módulo pickle)

(en el módulo plistlib)

(en el módulo xmlrpc.client)

loadTestsFromModule() (método de unittest.TestLoader)

loadTestsFromName() (método de unittest.TestLoader)

loadTestsFromNames() (método de unittest.TestLoader)

loadTestsFromTestCase() (método de unittest.TestLoader)

local (clase en threading)

localcontext() (en el módulo decimal)

LOCALE (en el módulo re)

locale (módulo)

localeconv() (en el módulo locale)

LocaleHTMLCalendar (clase en calendar)

LocaleTextCalendar (clase en calendar)

localName (atributo de xml.dom.Attr)

(atributo de xml.dom.Node)

locals() (función incorporada)

localtime() (en el módulo email.utils)

(en el módulo time)

Locator (clase en xml.sax.xmlreader)

Lock (clase en asyncio)

(clase en multiprocessing)

(clase en threading)

lock() (método de mailbox.Babyl)

(método de mailbox.Mailbox)

(método de mailbox.Maildir)

(método de mailbox.mbox)

(método de mailbox.MH)

(método de mailbox.MMDF)

Lock() (método de multiprocessing.managers.SyncManager)

lock, interpreter

lock_held() (en el módulo imp)

locked() (método de _thread.lock)

(método de asyncio.Condition)

(método de asyncio.Lock)

(método de asyncio.Semaphore)

(método de threading.Lock)

lockf() (en el módulo fcntl)

(en el módulo os)

locking() (en el módulo msvcrt)

LockType (en el módulo _thread)

log() (en el módulo cmath)

(en el módulo logging)

(en el módulo math)

(método de logging.Logger)

log10() (en el módulo cmath)

(en el módulo math)

(método de decimal.Context)

(método de decimal.Decimal)

log1p() (en el módulo math)

log2() (en el módulo math)

log_date_time_string() (método de http.server.BaseHTTPRequestHandler)

log_error() (método de http.server.BaseHTTPRequestHandler)

log_exception() (método de wsgiref.handlers.BaseHandler)

log_message() (método de http.server.BaseHTTPRequestHandler)

log_request() (método de http.server.BaseHTTPRequestHandler)

log_to_stderr() (en el módulo multiprocessing)

logb() (método de decimal.Context)

(método de decimal.Decimal)

Logger (clase en logging)

LoggerAdapter (clase en logging)

logging

Errors

logging (módulo)

logging.config (módulo)

logging.handlers (módulo)

logical line

logical_and() (método de decimal.Context)

(método de decimal.Decimal)

logical_invert() (método de decimal.Context)

(método de decimal.Decimal)

logical_or() (método de decimal.Context)

(método de decimal.Decimal)

logical_xor() (método de decimal.Context)

(método de decimal.Decimal)

login() (método de ftplib.FTP)

(método de imaplib.IMAP4)

(método de nntplib.NNTP)

(método de smtplib.SMTP)

login_cram_md5() (método de imaplib.IMAP4)

LOGNAME, [1]

lognormvariate() (en el módulo random)

logout() (método de imaplib.IMAP4)

LogRecord (clase en logging)

long (2to3 fixer)

long integer

objeto

LONG_MAX

LONG_TIMEOUT (en el módulo test.support)

longMessage (atributo de unittest.TestCase)

longname() (en el módulo curses)

lookup() (en el módulo codecs)

(en el módulo unicodedata)

(método de symtable.SymbolTable)

(método de tkinter.ttk.Style)

lookup_error() (en el módulo codecs)

LookupError

loop

over mutable sequence

statement, [1], [2], [3]

loop control

target

loop() (en el módulo asyncore)

LOOPBACK_TIMEOUT (en el módulo test.support)

lower() (método de bytearray)

(método de bytes)

(método de str)

LPAR (en el módulo token)

lpAttributeList (atributo de subprocess.STARTUPINFO)

lru_cache() (en el módulo functools)

lseek() (en el módulo os)

LShift (clase en ast)

lshift() (en el módulo operator)

LSQB (en el módulo token)

lstat() (en el módulo os)

(método de pathlib.Path)

lstrip() (método de bytearray)

(método de bytes)

(método de str)

lsub() (método de imaplib.IMAP4)

Lt (clase en ast)

lt() (en el módulo operator)

(en el módulo turtle)

LtE (clase en ast)

LWPCookieJar (clase en http.cookiejar)

lzma (módulo)

LZMACompressor (clase en lzma)

LZMADecompressor (clase en lzma)

LZMAError

LZMAFile (clase en lzma)

Índice – M

M (en el módulo re)

mac_ver() (en el módulo platform)

machine() (en el módulo platform)

macros (atributo de netrc.netrc)

MADV_AUTOSYNC (en el módulo mmap)

MADV_CORE (en el módulo mmap)

MADV_DODUMP (en el módulo mmap)

MADV_DOFORK (en el módulo mmap)

MADV_DONTDUMP (en el módulo mmap)

MADV_DONTFORK (en el módulo mmap)

MADV_DONTNEED (en el módulo mmap)

MADV_FREE (en el módulo mmap)

MADV_HUGEPAGE (en el módulo mmap)

MADV_HWPOISON (en el módulo mmap)

MADV_MERGEABLE (en el módulo mmap)

MADV_NOCORE (en el módulo mmap)

MADV_NOHUGEPAGE (en el módulo mmap)

MADV_NORMAL (en el módulo mmap)

MADV_NOSYNC (en el módulo mmap)

MADV_PROTECT (en el módulo mmap)

MADV_RANDOM (en el módulo mmap)

MADV_REMOVE (en el módulo mmap)

MADV_SEQUENTIAL (en el módulo mmap)

MADV_SOFT_OFFLINE (en el módulo mmap)

MADV_UNMERGEABLE (en el módulo mmap)

MADV_WILLNEED (en el módulo mmap)

madvise() (método de mmap.mmap)

magic

method

MAGIC_NUMBER (en el módulo importlib.util)

MagicMock (clase en unittest.mock)

Mailbox (clase en mailbox)

mailbox (módulo)

mailcap (módulo)

Maildir (clase en mailbox)

MaildirMessage (clase en mailbox)

mailfrom (atributo de smtpd.SMTPChannel)

MailmanProxy (clase en smtpd)

main(), [1], [2]

(en el módulo py_compile)

(en el módulo site)

(en el módulo unittest)

main_thread() (en el módulo threading)

mainloop() (en el módulo turtle)

maintype (atributo de email.headerregistry.ContentTypeHeader)

major (atributo de email.headerregistry.MIMEVersionHeader)

major() (en el módulo os)

make_alternative() (método de email.message.EmailMessage)

make_archive() (en el módulo distutils.archive_util)

(en el módulo shutil)

make_bad_fd() (en el módulo test.support)

make_cookies() (método de http.cookiejar.CookieJar)

make_dataclass() (en el módulo dataclasses)

make_file() (método de difflib.HtmlDiff)

MAKE_FUNCTION (opcode)

make_header() (en el módulo email.header)

make_legacy_pyc() (en el módulo test.support)

make_mixed() (método de email.message.EmailMessage)

make_msgid() (en el módulo email.utils)

make_parser() (en el módulo xml.sax)

make_pkg() (en el módulo test.support.script_helper)

make_related() (método de email.message.EmailMessage)

make_script() (en el módulo test.support.script_helper)

make_server() (en el módulo wsgiref.simple_server)

make_table() (método de difflib.HtmlDiff)

make_tarball() (en el módulo distutils.archive_util)

make_zip_pkg() (en el módulo test.support.script_helper)

make_zip_script() (en el módulo test.support.script_helper)

make_zipfile() (en el módulo distutils.archive_util)

makedev() (en el módulo os)

makedirs() (en el módulo os)

makeelement() (método de xml.etree.ElementTree.Element)

makefile() (método de socket.socket)

(socket method)

makeLogRecord() (en el módulo logging)

makePickle() (método de logging.handlers.SocketHandler)

makeRecord() (método de logging.Logger)

makeSocket() (método de logging.handlers.DatagramHandler)

(método de logging.handlers.SocketHandler)

maketrans() (método estático de bytearray)

(método estático de bytes)

(método estático de str)

malloc()

mangle_from_ (atributo de email.policy.Compat32)

(atributo de email.policy.Policy)

mangling

name, [1]

map (2to3 fixer)

map() (función incorporada)

(método de concurrent.futures.Executor)

(método de multiprocessing.pool.Pool)

(método de tkinter.ttk.Style)

MAP_ADD (opcode)

map_async() (método de multiprocessing.pool.Pool)

map_table_b2() (en el módulo stringprep)

map_table_b3() (en el módulo stringprep)

map_to_type() (método de email.headerregistry.HeaderRegistry)

mapeado

mapLogRecord() (método de logging.handlers.HTTPHandler)

mapping

objeto, [1], [2], [3], [4], [5]

types, operations on

Mapping (clase en collections.abc)

(clase en typing)

mapping() (método de msilib.Control)

MappingProxyType (clase en types)

MappingView (clase en collections.abc)

(clase en typing)

mapPriority() (método de logging.handlers.SysLogHandler)

maps (atributo de collections.ChainMap)

maps() (en el módulo nis)

marshal (módulo)

marshalling

objects

masking

operations

master (atributo de tkinter.Tk)

Match (clase en typing)

match() (en el módulo nis)

(en el módulo re)

(método de pathlib.PurePath)

(método de re.Pattern)

match_hostname() (en el módulo ssl)

match_test() (en el módulo test.support)

match_value() (método de test.support.Matcher)

Matcher (clase en test.support)

matches() (método de test.support.Matcher)

math

módulo, [1]

math (módulo)

matmul() (en el módulo operator)

MatMult (clase en ast)

matrix multiplication

max

función incorporada

max (atributo de datetime.date)

(atributo de datetime.datetime)

(atributo de datetime.time)

(atributo de datetime.timedelta)

max() (en el módulo audioop)

(función incorporada)

(método de decimal.Context)

(método de decimal.Decimal)

max_count (atributo de email.headerregistry.BaseHeader)

MAX_EMAX (en el módulo decimal)

MAX_INTERPOLATION_DEPTH (en el módulo configparser)

max_line_length (atributo de email.policy.Policy)

max_lines (atributo de textwrap.TextWrapper)

max_mag() (método de decimal.Context)

(método de decimal.Decimal)

max_memuse (en el módulo test.support)

MAX_PREC (en el módulo decimal)

max_prefixlen (atributo de ipaddress.IPv4Address)

(atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Address)

(atributo de ipaddress.IPv6Network)

MAX_Py_ssize_t (en el módulo test.support)

maxarray (atributo de reprlib.Repr)

maxdeque (atributo de reprlib.Repr)

maxdict (atributo de reprlib.Repr)

maxDiff (atributo de unittest.TestCase)

maxfrozenset (atributo de reprlib.Repr)

MAXIMUM_SUPPORTED (atributo de ssl.TLSVersion)

maximum_version (atributo de ssl.SSLContext)

maxlen (atributo de collections.deque)

maxlevel (atributo de reprlib.Repr)

maxlist (atributo de reprlib.Repr)

maxlong (atributo de reprlib.Repr)

maxother (atributo de reprlib.Repr)

maxpp() (en el módulo audioop)

maxset (atributo de reprlib.Repr)

maxsize (atributo de asyncio.Queue)

(en el módulo sys)

maxstring (atributo de reprlib.Repr)

maxtuple (atributo de reprlib.Repr)

maxunicode (en el módulo sys)

MAXYEAR (en el módulo datetime)

máquina virtual

MB_ICONASTERISK (en el módulo winsound)

MB_ICONEXCLAMATION (en el módulo winsound)

MB_ICONHAND (en el módulo winsound)

MB_ICONQUESTION (en el módulo winsound)

MB_OK (en el módulo winsound)

mbox (clase en mailbox)

mboxMessage (clase en mailbox)

mean (atributo de statistics.NormalDist)

mean() (en el módulo statistics)

measure() (método de tkinter.font.Font)

median (atributo de statistics.NormalDist)

median() (en el módulo statistics)

median_grouped() (en el módulo statistics)

median_high() (en el módulo statistics)

median_low() (en el módulo statistics)

MemberDescriptorType (en el módulo types)

membership

test

memfd_create() (en el módulo os)

memmove() (en el módulo ctypes)

MemoryBIO (clase en ssl)

MemoryError

MemoryHandler (clase en logging.handlers)

memoryview

objeto, [1]

memoryview (clase incorporada)

memset() (en el módulo ctypes)

merge() (en el módulo heapq)

Message (clase en email.message)

(clase en mailbox)

(clase en tkinter.messagebox)

message digest, MD5

message_factory (atributo de email.policy.Policy)

message_from_binary_file() (en el módulo email)

message_from_bytes() (en el módulo email)

message_from_file() (en el módulo email)

message_from_string() (en el módulo email)

MessageBeep() (en el módulo winsound)

MessageClass (atributo de http.server.BaseHTTPRequestHandler)

MessageError

MessageParseError

messages (en el módulo xml.parsers.expat.errors)

meta

hooks

meta buscadores de ruta

meta hooks

meta() (en el módulo curses)

meta_path (en el módulo sys)

metaclase

metaclass

(2to3 fixer)

metaclass hint

MetaPathFinder (clase en importlib.abc)

metavar (atributo de optparse.Option)

MetavarTypeHelpFormatter (clase en argparse)

Meter (clase en tkinter.tix)

METH_CLASS (variable incorporada)

METH_COEXIST (variable incorporada)

METH_FASTCALL (variable incorporada)

METH_NOARGS (variable incorporada)

METH_O (variable incorporada)

METH_STATIC (variable incorporada)

METH_VARARGS (variable incorporada)

method

built-in

call

magic

objeto, [1], [2], [3], [4], [5]

special

user-defined

method (atributo de urllib.request.Request)

METHOD_BLOWFISH (en el módulo crypt)

method_calls (atributo de unittest.mock.Mock)

METHOD_CRYPT (en el módulo crypt)

METHOD_MD5 (en el módulo crypt)

METHOD_SHA256 (en el módulo crypt)

METHOD_SHA512 (en el módulo crypt)

methodattrs (2to3 fixer)

methodcaller() (en el módulo operator)

MethodDescriptorType (en el módulo types)

methodHelp() (método de xmlrpc.client.ServerProxy.system)

methods

bytearray

bytes

string

methods (atributo de pyclbr.Class)

(en el módulo crypt)

methodSignature() (método de xmlrpc.client.ServerProxy.system)

MethodType (en el módulo types)

(in module types), [1]

MethodWrapperType (en el módulo types)

metrics() (método de tkinter.font.Font)

método

método especial

método mágico

MFD_ALLOW_SEALING (en el módulo os)

MFD_CLOEXEC (en el módulo os)

MFD_HUGE_16GB (en el módulo os)

MFD_HUGE_16MB (en el módulo os)

MFD_HUGE_1GB (en el módulo os)

MFD_HUGE_1MB (en el módulo os)

MFD_HUGE_256MB (en el módulo os)

MFD_HUGE_2GB (en el módulo os)

MFD_HUGE_2MB (en el módulo os)

MFD_HUGE_32MB (en el módulo os)

MFD_HUGE_512KB (en el módulo os)

MFD_HUGE_512MB (en el módulo os)

MFD_HUGE_64KB (en el módulo os)

MFD_HUGE_8MB (en el módulo os)

MFD_HUGE_MASK (en el módulo os)

MFD_HUGE_SHIFT (en el módulo os)

MFD_HUGETLB (en el módulo os)

MH (clase en mailbox)

MHMessage (clase en mailbox)

microsecond (atributo de datetime.datetime)

(atributo de datetime.time)

MIME

base64 encoding

content type

headers, [1]

quoted-printable encoding

MIMEApplication (clase en email.mime.application)

MIMEAudio (clase en email.mime.audio)

MIMEBase (clase en email.mime.base)

MIMEImage (clase en email.mime.image)

MIMEMessage (clase en email.mime.message)

MIMEMultipart (clase en email.mime.multipart)

MIMENonMultipart (clase en email.mime.nonmultipart)

MIMEPart (clase en email.message)

MIMEText (clase en email.mime.text)

MimeTypes (clase en mimetypes)

mimetypes (módulo)

MIMEVersionHeader (clase en email.headerregistry)

min

función incorporada

min (atributo de datetime.date)

(atributo de datetime.datetime)

(atributo de datetime.time)

(atributo de datetime.timedelta)

min() (función incorporada)

(método de decimal.Context)

(método de decimal.Decimal)

MIN_EMIN (en el módulo decimal)

MIN_ETINY (en el módulo decimal)

min_mag() (método de decimal.Context)

(método de decimal.Decimal)

MINEQUAL (en el módulo token)

MINIMUM_SUPPORTED (atributo de ssl.TLSVersion)

minimum_version (atributo de ssl.SSLContext)

minmax() (en el módulo audioop)

minor (atributo de email.headerregistry.MIMEVersionHeader)

minor() (en el módulo os)

minus

MINUS (en el módulo token)

minus() (método de decimal.Context)

minute (atributo de datetime.datetime)

(atributo de datetime.time)

MINYEAR (en el módulo datetime)

mirrored() (en el módulo unicodedata)

misc_header (atributo de cmd.Cmd)

MISSING (atributo de contextvars.Token)

MISSING_C_DOCSTRINGS (en el módulo test.support)

missing_compiler_executable() (en el módulo test.support)

MissingSectionHeaderError

MIXERDEV

mkd() (método de ftplib.FTP)

mkdir() (en el módulo os)

(método de pathlib.Path)

mkdtemp() (en el módulo tempfile)

mkfifo() (en el módulo os)

mknod() (en el módulo os)

mkpath() (en el módulo distutils.dir_util)

(método de distutils.ccompiler.CCompiler)

mksalt() (en el módulo crypt)

mkstemp() (en el módulo tempfile)

mktemp() (en el módulo tempfile)

mktime() (en el módulo time)

mktime_tz() (en el módulo email.utils)

mlsd() (método de ftplib.FTP)

mmap (clase en mmap)

(módulo)

MMDF (clase en mailbox)

MMDFMessage (clase en mailbox)

Mock (clase en unittest.mock)

mock_add_spec() (método de unittest.mock.Mock)

mock_calls (atributo de unittest.mock.Mock)

mock_open() (en el módulo unittest.mock)

Mod (clase en ast)

mod() (en el módulo operator)

mode (atributo de io.FileIO)

(atributo de ossaudiodev.oss_audio_device)

(atributo de statistics.NormalDist)

(atributo de tarfile.TarInfo)

mode() (en el módulo statistics)

(en el módulo turtle)

modes

file

modf() (en el módulo math)

modified() (método de urllib.robotparser.RobotFileParser)

Modify() (método de msilib.View)

modify() (método de select.devpoll)

(método de select.epoll)

(método de select.poll)

(método de selectors.BaseSelector)

module

extension

importing

namespace

objeto, [1], [2]

search path, [1], [2], [3], [4], [5], [6], [7]

module (atributo de pyclbr.Class)

(atributo de pyclbr.Function)

module spec

module_for_loader() (en el módulo importlib.util)

module_from_spec() (en el módulo importlib.util)

module_repr() (método de importlib.abc.Loader)

ModuleFinder (clase en modulefinder)

modulefinder (módulo)

ModuleInfo (clase en pkgutil)

ModuleNotFoundError

modules (atributo de modulefinder.ModuleFinder)

(en el módulo sys)

(in module sys), [1]

modules_cleanup() (en el módulo test.support)

modules_setup() (en el módulo test.support)

ModuleSpec (clase en importlib.machinery)

ModuleType (clase en types)

(in module types)

modulo

monotonic() (en el módulo time)

monotonic_ns() (en el módulo time)

month (atributo de datetime.date)

(atributo de datetime.datetime)

month() (en el módulo calendar)

month_abbr (en el módulo calendar)

month_name (en el módulo calendar)

monthcalendar() (en el módulo calendar)

monthdatescalendar() (método de calendar.Calendar)

monthdays2calendar() (método de calendar.Calendar)

monthdayscalendar() (método de calendar.Calendar)

monthrange() (en el módulo calendar)

Morsel (clase en http.cookies)

most_common() (método de collections.Counter)

mouseinterval() (en el módulo curses)

mousemask() (en el módulo curses)

move() (en el módulo shutil)

(método de curses.panel.Panel)

(método de curses.window)

(método de mmap.mmap)

(método de tkinter.ttk.Treeview)

move_file() (en el módulo distutils.file_util)

(método de distutils.ccompiler.CCompiler)

move_to_end() (método de collections.OrderedDict)

MozillaCookieJar (clase en http.cookiejar)

módulo

__main__, [1], [2], [3], [4], [5], [6], [7]

_locale

_thread

array, [1]

base64

bdb

binhex

builtins, [1], [2], [3], [4]

cmd

copy

crypt

dbm.gnu, [1]

dbm.ndbm, [1]

errno

glob

imp

io

json

math, [1]

os

pickle, [1], [2], [3]

pty

pwd

pyexpat

re, [1]

shelve

signal, [1]

sitecustomize

socket

stat

string

struct

sys, [1], [2], [3], [4], [5], [6]

types

urllib.request

usercustomize

uu

módulo de extensión

MRO

mro() (método de class)

msg (atributo de http.client.HTTPResponse)

(atributo de json.JSONDecodeError)

(atributo de re.error)

(atributo de traceback.TracebackException)

msg() (método de telnetlib.Telnet)

msi

msilib (módulo)

msvcrt (módulo)

mt_interact() (método de telnetlib.Telnet)

mtime (atributo de gzip.GzipFile)

(atributo de tarfile.TarInfo)

mtime() (método de urllib.robotparser.RobotFileParser)

mul() (en el módulo audioop)

(en el módulo operator)

Mult (clase en ast)

MultiCall (clase en xmlrpc.client)

MULTILINE (en el módulo re)

MultiLoopChildWatcher (clase en asyncio)

multimode() (en el módulo statistics)

MultipartConversionError

multiplication

multiply() (método de decimal.Context)

multiprocessing (módulo)

multiprocessing.connection (módulo)

multiprocessing.dummy (módulo)

multiprocessing.Manager() (función incorporada)

multiprocessing.managers (módulo)

multiprocessing.pool (módulo)

multiprocessing.shared_memory (módulo)

multiprocessing.sharedctypes (módulo)

mutable

objeto, [1], [2]

sequence types

mutable object

mutable sequence

loop over

objeto

MutableMapping (clase en collections.abc)

(clase en typing)

MutableSequence (clase en collections.abc)

(clase en typing)

MutableSet (clase en collections.abc)

(clase en typing)

mvderwin() (método de curses.window)

mvwin() (método de curses.window)

myrights() (método de imaplib.IMAP4)

Índice – N

N_TOKENS (en el módulo token)

n_waiting (atributo de threading.Barrier)

name, [1], [2]

binding, [1], [2], [3], [4], [5], [6]

binding, global

class

function, [1]

mangling, [1]

rebinding

unbinding

name (atributo de codecs.CodecInfo)

(atributo de contextvars.ContextVar)

(atributo de doctest.DocTest)

(atributo de email.headerregistry.BaseHeader)

(atributo de hashlib.hash)

(atributo de hmac.HMAC)

(atributo de http.cookiejar.Cookie)

(atributo de importlib.abc.FileLoader)

(atributo de importlib.machinery.ExtensionFileLoader)

(atributo de importlib.machinery.ModuleSpec)

(atributo de importlib.machinery.SourceFileLoader)

(atributo de importlib.machinery.SourcelessFileLoader)

(atributo de inspect.Parameter)

(atributo de io.FileIO)

(atributo de multiprocessing.Process)

(atributo de multiprocessing.shared_memory.SharedMemory)

(atributo de os.DirEntry)

(atributo de ossaudiodev.oss_audio_device)

(atributo de pyclbr.Class)

(atributo de pyclbr.Function)

(atributo de tarfile.TarInfo)

(atributo de threading.Thread)

(atributo de xml.dom.Attr)

(atributo de xml.dom.DocumentType)

(atributo de zipfile.Path)

Name (clase en ast)

name (en el módulo os)

NAME (en el módulo token)

name() (en el módulo unicodedata)

(método de importlib.abc.Traversable)

name2codepoint (en el módulo html.entities)

Named Shared Memory

NamedExpr (clase en ast)

NamedTemporaryFile() (en el módulo tempfile)

NamedTuple (clase en typing)

namedtuple() (en el módulo collections)

NameError

excepción

NameError (built-in exception)

namelist() (método de zipfile.ZipFile)

nameprep() (en el módulo encodings.idna)

namer (atributo de logging.handlers.BaseRotatingHandler)

namereplace

error handler's name

namereplace_errors() (en el módulo codecs)

names

private

names() (en el módulo tkinter.font)

namespace

global

module

package

Namespace (clase en argparse)

(clase en multiprocessing.managers)

namespace() (método de imaplib.IMAP4)

Namespace() (método de multiprocessing.managers.SyncManager)

NAMESPACE_DNS (en el módulo uuid)

NAMESPACE_OID (en el módulo uuid)

NAMESPACE_URL (en el módulo uuid)

NAMESPACE_X500 (en el módulo uuid)

NamespaceErr

namespaceURI (atributo de xml.dom.Node)

nametofont() (en el módulo tkinter.font)

NaN

nan (en el módulo cmath)

(en el módulo math)

nanj (en el módulo cmath)

NannyNag

napms() (en el módulo curses)

nargs (atributo de optparse.Option)

native_id (atributo de threading.Thread)

nbytes (atributo de memoryview)

ncurses_version (en el módulo curses)

ndiff() (en el módulo difflib)

ndim (atributo de memoryview)

ne (2to3 fixer)

ne() (en el módulo operator)

needs_input (atributo de bz2.BZ2Decompressor)

(atributo de lzma.LZMADecompressor)

neg() (en el módulo operator)

negation

netmask (atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Network)

NetmaskValueError

netrc (clase en netrc)

(módulo)

NetrcParseError

netscape (atributo de http.cookiejar.CookiePolicy)

network (atributo de ipaddress.IPv4Interface)

(atributo de ipaddress.IPv6Interface)

Network News Transfer Protocol

network_address (atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Network)

NEVER_EQ (en el módulo test.support)

new() (en el módulo hashlib)

(en el módulo hmac)

new_alignment() (método de formatter.writer)

new_child() (método de collections.ChainMap)

new_class() (en el módulo types)

new_compiler() (en el módulo distutils.ccompiler)

new_event_loop() (en el módulo asyncio)

(método de asyncio.AbstractEventLoopPolicy)

new_font() (método de formatter.writer)

new_margin() (método de formatter.writer)

new_module() (en el módulo imp)

new_panel() (en el módulo curses.panel)

new_spacing() (método de formatter.writer)

new_styles() (método de formatter.writer)

newer() (en el módulo distutils.dep_util)

newer_group() (en el módulo distutils.dep_util)

newer_pairwise() (en el módulo distutils.dep_util)

newfunc (tipo C)

newgroups() (método de nntplib.NNTP)

NEWLINE (en el módulo token)

NEWLINE token, [1]

newlines (atributo de io.TextIOBase)

newnews() (método de nntplib.NNTP)

newpad() (en el módulo curses)

NewType() (en el módulo typing)

newwin() (en el módulo curses)

next (2to3 fixer)

(pdb command)

next() (función incorporada)

(método de nntplib.NNTP)

(método de tarfile.TarFile)

(método de tkinter.ttk.Treeview)

next_minus() (método de decimal.Context)

(método de decimal.Decimal)

next_plus() (método de decimal.Context)

(método de decimal.Decimal)

next_toward() (método de decimal.Context)

(método de decimal.Decimal)

nextafter() (en el módulo math)

nextfile() (en el módulo fileinput)

nextkey() (método de dbm.gnu.gdbm)

nextSibling (atributo de xml.dom.Node)

ngettext() (en el módulo gettext)

(método de gettext.GNUTranslations)

(método de gettext.NullTranslations)

nice() (en el módulo os)

nis (módulo)

NL (en el módulo token)

nl() (en el módulo curses)

nl_langinfo() (en el módulo locale)

nlargest() (en el módulo heapq)

nlst() (método de ftplib.FTP)

NNTP

protocol

NNTP (clase en nntplib)

nntp_implementation (atributo de nntplib.NNTP)

NNTP_SSL (clase en nntplib)

nntp_version (atributo de nntplib.NNTP)

NNTPDataError

NNTPError

nntplib (módulo)

NNTPPermanentError

NNTPProtocolError

NNTPReplyError

NNTPTemporaryError

no_cache() (método de clase de zoneinfo.ZoneInfo)

no_proxy

no_tracing() (en el módulo test.support)

no_type_check() (en el módulo typing)

no_type_check_decorator() (en el módulo typing)

nocbreak() (en el módulo curses)

NoDataAllowedErr

node() (en el módulo platform)

nodelay() (método de curses.window)

nodeName (atributo de xml.dom.Node)

NodeTransformer (clase en ast)

nodeType (atributo de xml.dom.Node)

nodeValue (atributo de xml.dom.Node)

NodeVisitor (clase en ast)

noecho() (en el módulo curses)

NOEXPR (en el módulo locale)

nombre calificado

NoModificationAllowedErr

nonblock() (método de ossaudiodev.oss_audio_device)

NonCallableMagicMock (clase en unittest.mock)

NonCallableMock (clase en unittest.mock)

None

objeto, [1], [2]

None (Built-in object)

(variable incorporada)

nonl() (en el módulo curses)

nonlocal

sentencia

Nonlocal (clase en ast)

nonzero (2to3 fixer)

noop() (método de imaplib.IMAP4)

(método de poplib.POP3)

NoOptionError

NOP (opcode)

noqiflush() (en el módulo curses)

noraw() (en el módulo curses)

NoReturn (en el módulo typing)

NORMAL (en el módulo tkinter.font)

NORMAL_PRIORITY_CLASS (en el módulo subprocess)

NormalDist (clase en statistics)

normalize() (en el módulo locale)

(en el módulo unicodedata)

(método de decimal.Context)

(método de decimal.Decimal)

(método de xml.dom.Node)

NORMALIZE_WHITESPACE (en el módulo doctest)

normalvariate() (en el módulo random)

normcase() (en el módulo os.path)

normpath() (en el módulo os.path)

NoSectionError

NoSuchMailboxError

not

operador, [1]

Not (clase en ast)

not in

operador, [1], [2]

not_() (en el módulo operator)

NotADirectoryError

notation

notationDecl() (método de xml.sax.handler.DTDHandler)

NotationDeclHandler() (método de xml.parsers.expat.xmlparser)

notations (atributo de xml.dom.DocumentType)

NotConnected

NoteBook (clase en tkinter.tix)

Notebook (clase en tkinter.ttk)

NotEmptyError

NotEq (clase en ast)

NOTEQUAL (en el módulo token)

NotFoundErr

notify() (método de asyncio.Condition)

(método de threading.Condition)

notify_all() (método de asyncio.Condition)

(método de threading.Condition)

notimeout() (método de curses.window)

NotImplemented

objeto

NotImplemented (variable incorporada)

NotImplementedError

NotIn (clase en ast)

NotStandaloneHandler() (método de xml.parsers.expat.xmlparser)

NotSupportedErr

NotSupportedError

noutrefresh() (método de curses.window)

now() (método de clase de datetime.datetime)

npgettext() (en el módulo gettext)

(método de gettext.GNUTranslations)

(método de gettext.NullTranslations)

NSIG (en el módulo signal)

nsmallest() (en el módulo heapq)

NT_OFFSET (en el módulo token)

NTEventLogHandler (clase en logging.handlers)

ntohl() (en el módulo socket)

ntohs() (en el módulo socket)

ntransfercmd() (método de ftplib.FTP)

null

operation, [1]

nullcontext() (en el módulo contextlib)

NullFormatter (clase en formatter)

NullHandler (clase en logging)

NullImporter (clase en imp)

NullTranslations (clase en gettext)

NullWriter (clase en formatter)

num_addresses (atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Network)

num_tickets (atributo de ssl.SSLContext)

number

complex

floating point

Number (clase en numbers)

NUMBER (en el módulo token)

number_class() (método de decimal.Context)

(método de decimal.Decimal)

numbers (módulo)

numerator (atributo de fractions.Fraction)

(atributo de numbers.Rational)

numeric

conversions

literals

object

objeto, [1], [2], [3]

types, operations on

numeric literal

numeric() (en el módulo unicodedata)

numinput() (en el módulo turtle)

numliterals (2to3 fixer)

número complejo

Índice – O

O_APPEND (en el módulo os)

O_ASYNC (en el módulo os)

O_BINARY (en el módulo os)

O_CLOEXEC (en el módulo os)

O_CREAT (en el módulo os)

O_DIRECT (en el módulo os)

O_DIRECTORY (en el módulo os)

O_DSYNC (en el módulo os)

O_EXCL (en el módulo os)

O_EXLOCK (en el módulo os)

O_NDELAY (en el módulo os)

O_NOATIME (en el módulo os)

O_NOCTTY (en el módulo os)

O_NOFOLLOW (en el módulo os)

O_NOINHERIT (en el módulo os)

O_NONBLOCK (en el módulo os)

O_PATH (en el módulo os)

O_RANDOM (en el módulo os)

O_RDONLY (en el módulo os)

O_RDWR (en el módulo os)

O_RSYNC (en el módulo os)

O_SEQUENTIAL (en el módulo os)

O_SHLOCK (en el módulo os)

O_SHORT_LIVED (en el módulo os)

O_SYNC (en el módulo os)

O_TEMPORARY (en el módulo os)

O_TEXT (en el módulo os)

O_TMPFILE (en el módulo os)

O_TRUNC (en el módulo os)

O_WRONLY (en el módulo os)

obj (atributo de memoryview)

object

code, [1], [2], [3]

deallocation

finalization

immutable, [1]

numeric

object (atributo de UnicodeError)

(clase incorporada)

object.__slots__ (variable incorporada)

object_filenames() (método de distutils.ccompiler.CCompiler)

objects

comparing

flattening

marshalling

persistent

pickling

serializing

objeto

asynchronous-generator

Boolean, [1]

built-in function, [1]

built-in method, [1]

bytearray, [1], [2], [3]

bytes, [1], [2]

callable, [1]

Capsule

class, [1], [2]

class instance, [1], [2]

complex

complex number, [1]

dictionary, [1], [2], [3], [4], [5], [6], [7]

Ellipsis

file, [1]

floating point, [1], [2]

frame

frozenset, [1]

function, [1], [2], [3], [4], [5]

generator, [1], [2]

GenericAlias

immutable

immutable sequence

instance, [1], [2]

instancemethod

integer, [1], [2]

io.StringIO

list, [1], [2], [3], [4], [5], [6], [7], [8]

long integer

mapping, [1], [2], [3], [4], [5]

memoryview, [1]

method, [1], [2], [3], [4], [5]

module, [1], [2]

mutable, [1], [2]

mutable sequence

None, [1], [2]

NotImplemented

numeric, [1], [2], [3]

range

sequence, [1], [2], [3], [4], [5], [6], [7], [8]

set, [1], [2], [3]

set type

slice

socket

string, [1], [2]

traceback, [1], [2], [3], [4]

tuple, [1], [2], [3], [4], [5], [6]

type, [1], [2]

user-defined function, [1], [2]

user-defined method

objeto archivo

objeto tipo ruta

objetos tipo archivo

objetos tipo binarios

objobjargproc (tipo C)

objobjproc (tipo C)

obufcount() (método de ossaudiodev.oss_audio_device)

obuffree() (método de ossaudiodev.oss_audio_device)

oct() (función incorporada)

octal

literals

octal literal

octdigits (en el módulo string)

offset (atributo de SyntaxError)

(atributo de traceback.TracebackException)

(atributo de xml.parsers.expat.ExpatError)

OK (en el módulo curses)

ok_command() (método de tkinter.filedialog.LoadFileDialog)

(método de tkinter.filedialog.SaveFileDialog)

ok_event() (método de tkinter.filedialog.FileDialog)

old_value (atributo de contextvars.Token)

OleDLL (clase en ctypes)

on_motion() (método de tkinter.dnd.DndHandler)

on_release() (método de tkinter.dnd.DndHandler)

onclick() (en el módulo turtle)

ondrag() (en el módulo turtle)

onecmd() (método de cmd.Cmd)

onkey() (en el módulo turtle)

onkeypress() (en el módulo turtle)

onkeyrelease() (en el módulo turtle)

onrelease() (en el módulo turtle)

onscreenclick() (en el módulo turtle)

ontimer() (en el módulo turtle)

OP (en el módulo token)

OP_ALL (en el módulo ssl)

OP_CIPHER_SERVER_PREFERENCE (en el módulo ssl)

OP_ENABLE_MIDDLEBOX_COMPAT (en el módulo ssl)

OP_IGNORE_UNEXPECTED_EOF (en el módulo ssl)

OP_NO_COMPRESSION (en el módulo ssl)

OP_NO_RENEGOTIATION (en el módulo ssl)

OP_NO_SSLv2 (en el módulo ssl)

OP_NO_SSLv3 (en el módulo ssl)

OP_NO_TICKET (en el módulo ssl)

OP_NO_TLSv1 (en el módulo ssl)

OP_NO_TLSv1_1 (en el módulo ssl)

OP_NO_TLSv1_2 (en el módulo ssl)

OP_NO_TLSv1_3 (en el módulo ssl)

OP_SINGLE_DH_USE (en el módulo ssl)

OP_SINGLE_ECDH_USE (en el módulo ssl)

open

función incorporada, [1]

Open (clase en tkinter.filedialog)

open() (en el módulo aifc)

(en el módulo bz2)

(en el módulo codecs)

(en el módulo dbm)

(en el módulo dbm.dumb)

(en el módulo dbm.gnu)

(en el módulo dbm.ndbm)

(en el módulo gzip)

(en el módulo io)

(en el módulo lzma)

(en el módulo os)

(en el módulo ossaudiodev)

(en el módulo shelve)

(en el módulo sunau)

(en el módulo tarfile)

(en el módulo tokenize)

(en el módulo wave)

(en el módulo webbrowser)

(función incorporada)

(método de clase de tarfile.TarFile)

(método de distutils.text_file.TextFile)

(método de imaplib.IMAP4)

(método de importlib.abc.Traversable)

(método de pathlib.Path)

(método de pipes.Template)

(método de telnetlib.Telnet)

(método de urllib.request.OpenerDirector)

(método de urllib.request.URLopener)

(método de webbrowser.controller)

(método de zipfile.Path)

(método de zipfile.ZipFile)

open_binary() (en el módulo importlib.resources)

open_code() (en el módulo io)

open_connection() (en el módulo asyncio)

open_new() (en el módulo webbrowser)

(método de webbrowser.controller)

open_new_tab() (en el módulo webbrowser)

(método de webbrowser.controller)

open_osfhandle() (en el módulo msvcrt)

open_resource() (método de importlib.abc.ResourceReader)

open_text() (en el módulo importlib.resources)

open_unix_connection() (en el módulo asyncio)

open_unknown() (método de urllib.request.URLopener)

open_urlresource() (en el módulo test.support)

OpenDatabase() (en el módulo msilib)

OpenerDirector (clase en urllib.request)

OpenKey() (en el módulo winreg)

OpenKeyEx() (en el módulo winreg)

openlog() (en el módulo syslog)

openmixer() (en el módulo ossaudiodev)

openpty() (en el módulo os)

(en el módulo pty)

OpenSSL

(use in module hashlib)

(use in module ssl)

OPENSSL_VERSION (en el módulo ssl)

OPENSSL_VERSION_INFO (en el módulo ssl)

OPENSSL_VERSION_NUMBER (en el módulo ssl)

OpenView() (método de msilib.Database)

operador

!=, [1]

% (percent), [1]

& (ampersand), [1]

* (asterisk), [1]

**, [1]

/ (slash), [1]

//, [1]

< (less), [1]

<<, [1]

<=, [1]

==, [1]

> (greater), [1]

>=, [1]

>>, [1]

@ (at)

^ (caret), [1]

| (vertical bar), [1]

~ (tilde), [1]

and, [1], [2]

in, [1], [2]

is, [1]

is not, [1]

not, [1]

not in, [1], [2]

or, [1], [2]

operation

binary arithmetic

binary bitwise

Boolean

concatenation

null, [1]

power

repetition

shifting

slice

subscript

unary arithmetic

unary bitwise

OperationalError

operations

bitwise

Boolean, [1]

masking

shifting

operations on

dictionary type

integer types

list type

mapping types

numeric types

sequence types, [1]

operator

+ (plus), [1], [2]

- (minus), [1], [2]

comparison

overloading

precedence

ternary

operator (2to3 fixer)

(módulo)

operators

opmap (en el módulo dis)

opname (en el módulo dis)

optim_args_from_interpreter_flags() (en el módulo test.support)

optimize() (en el módulo pickletools)

OPTIMIZED_BYTECODE_SUFFIXES (en el módulo importlib.machinery)

Optional (en el módulo typing)

OptionGroup (clase en optparse)

OptionMenu (clase en tkinter.tix)

OptionParser (clase en optparse)

options (atributo de doctest.Example)

(atributo de ssl.SSLContext)

Options (clase en ssl)

options() (método de configparser.ConfigParser)

optionxform() (método de configparser.ConfigParser)

optparse (módulo)

or

bitwise

exclusive

inclusive

operador, [1], [2]

Or (clase en ast)

or_() (en el módulo operator)

ord

función incorporada

ord() (función incorporada)

orden de resolución de métodos

order

evaluation

ordered_attributes (atributo de xml.parsers.expat.xmlparser)

OrderedDict (clase en collections)

(clase en typing)

origin (atributo de importlib.machinery.ModuleSpec)

origin_req_host (atributo de urllib.request.Request)

origin_server (atributo de wsgiref.handlers.BaseHandler)

os

módulo

os (módulo)

os.path (módulo)

os_environ (atributo de wsgiref.handlers.BaseHandler)

OSError

ossaudiodev (módulo)

OSSAudioError

outfile

json.tool command line option

output

standard

output (atributo de subprocess.CalledProcessError)

(atributo de subprocess.TimeoutExpired)

(atributo de unittest.TestCase)

output() (método de http.cookies.BaseCookie)

(método de http.cookies.Morsel)

output_charset (atributo de email.charset.Charset)

output_charset() (método de gettext.NullTranslations)

output_codec (atributo de email.charset.Charset)

output_difference() (método de doctest.OutputChecker)

OutputChecker (clase en doctest)

OutputString() (método de http.cookies.Morsel)

OutsideDestinationError

over() (método de nntplib.NNTP)

Overflow (clase en decimal)

OverflowError

(built-in exception), [1], [2], [3], [4], [5]

overlap() (método de statistics.NormalDist)

overlaps() (método de ipaddress.IPv4Network)

(método de ipaddress.IPv6Network)

overlay() (método de curses.window)

overload() (en el módulo typing)

overloading

operator

overwrite() (método de curses.window)

owner() (método de pathlib.Path)

Índice – P

p (pdb command)

P_ALL (en el módulo os)

P_DETACH (en el módulo os)

P_NOWAIT (en el módulo os)

P_NOWAITO (en el módulo os)

P_OVERLAY (en el módulo os)

P_PGID (en el módulo os)

P_PID (en el módulo os)

P_PIDFD (en el módulo os)

P_WAIT (en el módulo os)

pack() (en el módulo struct)

(método de mailbox.MH)

(método de struct.Struct)

pack_array() (método de xdrlib.Packer)

pack_bytes() (método de xdrlib.Packer)

pack_double() (método de xdrlib.Packer)

pack_farray() (método de xdrlib.Packer)

pack_float() (método de xdrlib.Packer)

pack_fopaque() (método de xdrlib.Packer)

pack_fstring() (método de xdrlib.Packer)

pack_into() (en el módulo struct)

(método de struct.Struct)

pack_list() (método de xdrlib.Packer)

pack_opaque() (método de xdrlib.Packer)

pack_string() (método de xdrlib.Packer)

package, [1]

namespace

portion

regular

Package (en el módulo importlib.resources)

package variable

__all__

packed (atributo de ipaddress.IPv4Address)

(atributo de ipaddress.IPv6Address)

Packer (clase en xdrlib)

packing

binary data

packing (widgets)

PAGER

pair_content() (en el módulo curses)

pair_number() (en el módulo curses)

palabra clave

as, [1], [2]

async

await, [1]

elif

else, [1], [2], [3], [4], [5]

except

finally, [1], [2], [3], [4]

from, [1]

in

yield

PanedWindow (clase en tkinter.tix)

paquete

paquete de espacios de nombres

paquete provisorio

paquete regular

parameter

call semantics

difference from argument

function definition

value, default

Parameter (clase en inspect)

ParameterizedMIMEHeader (clase en email.headerregistry)

parameters (atributo de inspect.Signature)

params (atributo de email.headerregistry.ParameterizedMIMEHeader)

paramstyle (en el módulo sqlite3)

parámetro

pardir (en el módulo os)

paren (2to3 fixer)

parent (atributo de importlib.machinery.ModuleSpec)

(atributo de pyclbr.Class)

(atributo de pyclbr.Function)

(atributo de urllib.request.BaseHandler)

parent() (método de tkinter.ttk.Treeview)

parent_process() (en el módulo multiprocessing)

parenthesized form

parentNode (atributo de xml.dom.Node)

parents (atributo de collections.ChainMap)

paretovariate() (en el módulo random)

parse() (en el módulo ast)

(en el módulo cgi)

(en el módulo xml.dom.minidom)

(en el módulo xml.dom.pulldom)

(en el módulo xml.etree.ElementTree)

(en el módulo xml.sax)

(método de doctest.DocTestParser)

(método de email.parser.BytesParser)

(método de email.parser.Parser)

(método de string.Formatter)

(método de urllib.robotparser.RobotFileParser)

(método de xml.etree.ElementTree.ElementTree)

Parse() (método de xml.parsers.expat.xmlparser)

parse() (método de xml.sax.xmlreader.XMLReader)

parse_and_bind() (en el módulo readline)

parse_args() (método de argparse.ArgumentParser)

PARSE_COLNAMES (en el módulo sqlite3)

parse_config_h() (en el módulo sysconfig)

PARSE_DECLTYPES (en el módulo sqlite3)

parse_header() (en el módulo cgi)

parse_headers() (en el módulo http.client)

parse_intermixed_args() (método de argparse.ArgumentParser)

parse_known_args() (método de argparse.ArgumentParser)

parse_known_intermixed_args() (método de argparse.ArgumentParser)

parse_multipart() (en el módulo cgi)

parse_qs() (en el módulo urllib.parse)

parse_qsl() (en el módulo urllib.parse)

parseaddr() (en el módulo email.utils)

parsebytes() (método de email.parser.BytesParser)

parsedate() (en el módulo email.utils)

parsedate_to_datetime() (en el módulo email.utils)

parsedate_tz() (en el módulo email.utils)

ParseError (clase en xml.etree.ElementTree)

ParseFile() (método de xml.parsers.expat.xmlparser)

ParseFlags() (en el módulo imaplib)

parser

Parser (clase en email.parser)

parser (módulo)

ParserCreate() (en el módulo xml.parsers.expat)

ParserError

ParseResult (clase en urllib.parse)

ParseResultBytes (clase en urllib.parse)

parsestr() (método de email.parser.Parser)

parseString() (en el módulo xml.dom.minidom)

(en el módulo xml.dom.pulldom)

(en el módulo xml.sax)

parsing

Python source code

URL

ParsingError

partial (atributo de asyncio.IncompleteReadError)

partial() (en el módulo functools)

(método de imaplib.IMAP4)

partialmethod (clase en functools)

parties (atributo de threading.Barrier)

partition() (método de bytearray)

(método de bytes)

(método de str)

pass

sentencia

Pass (clase en ast)

pass_() (método de poplib.POP3)

Paste

patch() (en el módulo test.support)

(en el módulo unittest.mock)

patch.dict() (en el módulo unittest.mock)

patch.multiple() (en el módulo unittest.mock)

patch.object() (en el módulo unittest.mock)

patch.stopall() (en el módulo unittest.mock)

PATH, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21], [22], [23], [24], [25], [26], [27], [28], [29], [30], [31], [32], [33], [34], [35], [36], [37], [38], [39]

path

configuration file

hooks

module search, [1], [2], [3], [4], [5], [6], [7]

operations, [1]

path (atributo de http.cookiejar.Cookie)

(atributo de http.server.BaseHTTPRequestHandler)

(atributo de importlib.abc.FileLoader)

(atributo de importlib.machinery.ExtensionFileLoader)

(atributo de importlib.machinery.FileFinder)

(atributo de importlib.machinery.SourceFileLoader)

(atributo de importlib.machinery.SourcelessFileLoader)

(atributo de os.DirEntry)

Path (clase en pathlib)

(clase en zipfile)

path (en el módulo sys)

(in module sys), [1], [2], [3]

path based finder

Path browser

path hooks

path() (en el módulo importlib.resources)

path_hook() (método de clase de importlib.machinery.FileFinder)

path_hooks (en el módulo sys)

path_importer_cache (en el módulo sys)

path_mtime() (método de importlib.abc.SourceLoader)

path_return_ok() (método de http.cookiejar.CookiePolicy)

path_stats() (método de importlib.abc.SourceLoader)

(método de importlib.machinery.SourceFileLoader)

pathconf() (en el módulo os)

pathconf_names (en el módulo os)

PathEntryFinder (clase en importlib.abc)

PATHEXT, [1], [2]

PathFinder (clase en importlib.machinery)

pathlib (módulo)

PathLike (clase en os)

pathname2url() (en el módulo urllib.request)

pathsep (en el módulo os)

pattern (atributo de re.error)

(atributo de re.Pattern)

Pattern (clase en typing)

pause() (en el módulo signal)

pause_reading() (método de asyncio.ReadTransport)

pause_writing() (método de asyncio.BaseProtocol)

PAX_FORMAT (en el módulo tarfile)

pax_headers (atributo de tarfile.TarFile)

(atributo de tarfile.TarInfo)

pbkdf2_hmac() (en el módulo hashlib)

pd() (en el módulo turtle)

Pdb (clase en pdb)

(class in pdb)

pdb (módulo)

pdf() (método de statistics.NormalDist)

peek() (método de bz2.BZ2File)

(método de gzip.GzipFile)

(método de io.BufferedReader)

(método de lzma.LZMAFile)

(método de weakref.finalize)

peer (atributo de smtpd.SMTPChannel)

PEM_cert_to_DER_cert() (en el módulo ssl)

pen() (en el módulo turtle)

pencolor() (en el módulo turtle)

pending (atributo de ssl.MemoryBIO)

pending() (método de ssl.SSLSocket)

PendingDeprecationWarning

pendown() (en el módulo turtle)

pensize() (en el módulo turtle)

penup() (en el módulo turtle)

PEP

PERCENT (en el módulo token)

PERCENTEQUAL (en el módulo token)

perf_counter() (en el módulo time)

perf_counter_ns() (en el módulo time)

Performance

perm() (en el módulo math)

PermissionError

permutations() (en el módulo itertools)

Persist() (método de msilib.SummaryInformation)

persistence

persistent

objects

persistent_id (pickle protocol)

persistent_id() (método de pickle.Pickler)

persistent_load (pickle protocol)

persistent_load() (método de pickle.Unpickler)

PF_CAN (en el módulo socket)

PF_PACKET (en el módulo socket)

PF_RDS (en el módulo socket)

pformat() (en el módulo pprint)

(método de pprint.PrettyPrinter)

pgettext() (en el módulo gettext)

(método de gettext.GNUTranslations)

(método de gettext.NullTranslations)

PGO (en el módulo test.support)

phase() (en el módulo cmath)

Philbrick, Geoff

physical line, [1], [2]

pi (en el módulo cmath)

(en el módulo math)

pi() (método de xml.etree.ElementTree.TreeBuilder)

pickle

módulo, [1], [2], [3]

pickle (módulo)

pickle() (en el módulo copyreg)

PickleBuffer (clase en pickle)

PickleError

Pickler (clase en pickle)

pickletools (módulo)

pickletools command line option

--annotate

--indentlevel=<num>

--memo

--output=<file>

--preamble=<preamble>

-a

-l

-m

-o

-p

pickling

objects

PicklingError

pid (atributo de asyncio.subprocess.Process)

(atributo de multiprocessing.Process)

(atributo de subprocess.Popen)

pidfd_open() (en el módulo os)

pidfd_send_signal() (en el módulo signal)

PidfdChildWatcher (clase en asyncio)

PIP_USER

PIPE (en el módulo subprocess)

Pipe() (en el módulo multiprocessing)

pipe() (en el módulo os)

pipe2() (en el módulo os)

PIPE_BUF (en el módulo select)

pipe_connection_lost() (método de asyncio.SubprocessProtocol)

pipe_data_received() (método de asyncio.SubprocessProtocol)

PIPE_MAX_SIZE (en el módulo test.support)

pipes (módulo)

PKG_DIRECTORY (en el módulo imp)

pkgutil (módulo)

placeholder (atributo de textwrap.TextWrapper)

PLAT

platform (en el módulo sys)

(in module sys)

(módulo)

platform() (en el módulo platform)

platlibdir (en el módulo sys)

PlaySound() (en el módulo winsound)

plist

file

plistlib (módulo)

plock() (en el módulo os)

plus

PLUS (en el módulo token)

plus() (método de decimal.Context)

PLUSEQUAL (en el módulo token)

pm() (en el módulo pdb)

POINTER() (en el módulo ctypes)

pointer() (en el módulo ctypes)

polar() (en el módulo cmath)

Policy (clase en email.policy)

poll() (en el módulo select)

(método de multiprocessing.connection.Connection)

(método de select.devpoll)

(método de select.epoll)

(método de select.poll)

(método de subprocess.Popen)

PollSelector (clase en selectors)

Pool (clase en multiprocessing.pool)

pop() (método de array.array)

(método de collections.deque)

(método de dict)

(método de frozenset)

(método de mailbox.Mailbox)

(sequence method)

POP3

protocol

POP3 (clase en poplib)

POP3_SSL (clase en poplib)

pop_alignment() (método de formatter.formatter)

pop_all() (método de contextlib.ExitStack)

POP_BLOCK (opcode)

POP_EXCEPT (opcode)

pop_font() (método de formatter.formatter)

POP_JUMP_IF_FALSE (opcode)

POP_JUMP_IF_TRUE (opcode)

pop_margin() (método de formatter.formatter)

pop_source() (método de shlex.shlex)

pop_style() (método de formatter.formatter)

POP_TOP (opcode)

Popen (clase en subprocess)

popen() (en el módulo os)

(in module os), [1]

popitem() (método de collections.OrderedDict)

(método de dict)

(método de mailbox.Mailbox)

popleft() (método de collections.deque)

poplib (módulo)

PopupMenu (clase en tkinter.tix)

porción

port (atributo de http.cookiejar.Cookie)

port_specified (atributo de http.cookiejar.Cookie)

portion

package

pos (atributo de json.JSONDecodeError)

(atributo de re.error)

(atributo de re.Match)

pos() (en el módulo operator)

(en el módulo turtle)

position (atributo de xml.etree.ElementTree.ParseError)

position() (en el módulo turtle)

POSIX

I/O control

threads

posix (módulo)

POSIX Shared Memory

POSIX_FADV_DONTNEED (en el módulo os)

POSIX_FADV_NOREUSE (en el módulo os)

POSIX_FADV_NORMAL (en el módulo os)

POSIX_FADV_RANDOM (en el módulo os)

POSIX_FADV_SEQUENTIAL (en el módulo os)

POSIX_FADV_WILLNEED (en el módulo os)

posix_fadvise() (en el módulo os)

posix_fallocate() (en el módulo os)

posix_spawn() (en el módulo os)

POSIX_SPAWN_CLOSE (en el módulo os)

POSIX_SPAWN_DUP2 (en el módulo os)

POSIX_SPAWN_OPEN (en el módulo os)

posix_spawnp() (en el módulo os)

POSIXLY_CORRECT

PosixPath (clase en pathlib)

post() (método de nntplib.NNTP)

(método de ossaudiodev.oss_audio_device)

post_handshake_auth (atributo de ssl.SSLContext)

post_mortem() (en el módulo pdb)

post_setup() (método de venv.EnvBuilder)

postcmd() (método de cmd.Cmd)

postloop() (método de cmd.Cmd)

pow

función incorporada, [1], [2], [3], [4], [5]

Pow (clase en ast)

pow() (en el módulo math)

(en el módulo operator)

(función incorporada)

power

operation

power() (método de decimal.Context)

pp (pdb command)

pp() (en el módulo pprint)

pprint (módulo)

pprint() (en el módulo pprint)

(método de pprint.PrettyPrinter)

prcal() (en el módulo calendar)

pread() (en el módulo os)

preadv() (en el módulo os)

preamble (atributo de email.message.EmailMessage)

(atributo de email.message.Message)

precedence

operator

precmd() (método de cmd.Cmd)

prefix, [1], [2], [3]

(atributo de xml.dom.Attr)

(atributo de xml.dom.Node)

(atributo de zipimport.zipimporter)

PREFIX (en el módulo distutils.sysconfig)

prefix (en el módulo sys)

PREFIXES (en el módulo site)

prefixlen (atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Network)

preloop() (método de cmd.Cmd)

prepare() (método de graphlib.TopologicalSorter)

(método de logging.handlers.QueueHandler)

(método de logging.handlers.QueueListener)

prepare_class() (en el módulo types)

prepare_input_source() (en el módulo xml.sax.saxutils)

prepend() (método de pipes.Template)

preprocess() (método de distutils.ccompiler.CCompiler)

PrettyPrinter (clase en pprint)

prev() (método de tkinter.ttk.Treeview)

previousSibling (atributo de xml.dom.Node)

primary

print

función incorporada

print (2to3 fixer)

print() (built-in function)

__str__() (object method)

print() (función incorporada)

print_callees() (método de pstats.Stats)

print_callers() (método de pstats.Stats)

print_directory() (en el módulo cgi)

print_environ() (en el módulo cgi)

print_environ_usage() (en el módulo cgi)

print_exc() (en el módulo traceback)

(método de timeit.Timer)

print_exception() (en el módulo traceback)

PRINT_EXPR (opcode)

print_form() (en el módulo cgi)

print_help() (método de argparse.ArgumentParser)

print_last() (en el módulo traceback)

print_stack() (en el módulo traceback)

(método de asyncio.Task)

print_stats() (método de profile.Profile)

(método de pstats.Stats)

print_tb() (en el módulo traceback)

print_usage() (método de argparse.ArgumentParser)

(método de optparse.OptionParser)

print_version() (método de optparse.OptionParser)

print_warning() (en el módulo test.support)

printable (en el módulo string)

printdir() (método de zipfile.ZipFile)

printf-style formatting, [1]

PRIO_PGRP (en el módulo os)

PRIO_PROCESS (en el módulo os)

PRIO_USER (en el módulo os)

PriorityQueue (clase en asyncio)

(clase en queue)

private

names

prlimit() (en el módulo resource)

prmonth() (en el módulo calendar)

(método de calendar.TextCalendar)

ProactorEventLoop (clase en asyncio)

procedure

call

process

group, [1]

id

id of parent

killing, [1]

scheduling priority, [1]

signalling, [1]

Process (clase en multiprocessing)

process() (método de logging.LoggerAdapter)

process_exited() (método de asyncio.SubprocessProtocol)

process_message() (método de smtpd.SMTPServer)

process_request() (método de socketserver.BaseServer)

process_time() (en el módulo time)

process_time_ns() (en el módulo time)

process_tokens() (en el módulo tabnanny)

ProcessError

processes, light-weight

ProcessingInstruction() (en el módulo xml.etree.ElementTree)

processingInstruction() (método de xml.sax.handler.ContentHandler)

ProcessingInstructionHandler() (método de xml.parsers.expat.xmlparser)

ProcessLookupError

processor time, [1]

processor() (en el módulo platform)

ProcessPoolExecutor (clase en concurrent.futures)

prod() (en el módulo math)

product() (en el módulo itertools)

Profile (clase en profile)

profile (módulo)

profile function, [1], [2]

profiler, [1]

profiling, deterministic

program

ProgrammingError

Progressbar (clase en tkinter.ttk)

prompt (atributo de cmd.Cmd)

prompt_user_passwd() (método de urllib.request.FancyURLopener)

prompts, interpreter

propagate (atributo de logging.Logger)

property (clase incorporada)

property list

property_declaration_handler (en el módulo xml.sax.handler)

property_dom_node (en el módulo xml.sax.handler)

property_lexical_handler (en el módulo xml.sax.handler)

property_xml_string (en el módulo xml.sax.handler)

PropertyMock (clase en unittest.mock)

prot_c() (método de ftplib.FTP_TLS)

prot_p() (método de ftplib.FTP_TLS)

proto (atributo de socket.socket)

protocol

CGI

context management

copy

FTP, [1]

HTTP, [1], [2], [3], [4], [5]

IMAP4

IMAP4_SSL

IMAP4_stream

iterator

NNTP

POP3

SMTP

Telnet

protocol (atributo de ssl.SSLContext)

Protocol (clase en asyncio)

(clase en typing)

PROTOCOL_SSLv2 (en el módulo ssl)

PROTOCOL_SSLv23 (en el módulo ssl)

PROTOCOL_SSLv3 (en el módulo ssl)

PROTOCOL_TLS (en el módulo ssl)

PROTOCOL_TLS_CLIENT (en el módulo ssl)

PROTOCOL_TLS_SERVER (en el módulo ssl)

PROTOCOL_TLSv1 (en el módulo ssl)

PROTOCOL_TLSv1_1 (en el módulo ssl)

PROTOCOL_TLSv1_2 (en el módulo ssl)

protocol_version (atributo de http.server.BaseHTTPRequestHandler)

PROTOCOL_VERSION (atributo de imaplib.IMAP4)

ProtocolError (clase en xmlrpc.client)

proxy() (en el módulo weakref)

proxyauth() (método de imaplib.IMAP4)

ProxyBasicAuthHandler (clase en urllib.request)

ProxyDigestAuthHandler (clase en urllib.request)

ProxyHandler (clase en urllib.request)

ProxyType (en el módulo weakref)

ProxyTypes (en el módulo weakref)

pryear() (método de calendar.TextCalendar)

ps1 (en el módulo sys)

ps2 (en el módulo sys)

pstats (módulo)

pstdev() (en el módulo statistics)

pthread_getcpuclockid() (en el módulo time)

pthread_kill() (en el módulo signal)

pthread_sigmask() (en el módulo signal)

pthreads

pty

módulo

pty (módulo)

pu() (en el módulo turtle)

publicId (atributo de xml.dom.DocumentType)

PullDom (clase en xml.dom.pulldom)

punctuation (en el módulo string)

punctuation_chars (atributo de shlex.shlex)

PurePath (clase en pathlib)

PurePath.anchor (en el módulo pathlib)

PurePath.drive (en el módulo pathlib)

PurePath.name (en el módulo pathlib)

PurePath.parent (en el módulo pathlib)

PurePath.parents (en el módulo pathlib)

PurePath.parts (en el módulo pathlib)

PurePath.root (en el módulo pathlib)

PurePath.stem (en el módulo pathlib)

PurePath.suffix (en el módulo pathlib)

PurePath.suffixes (en el módulo pathlib)

PurePosixPath (clase en pathlib)

PureProxy (clase en smtpd)

PureWindowsPath (clase en pathlib)

purge() (en el módulo re)

Purpose.CLIENT_AUTH (en el módulo ssl)

Purpose.SERVER_AUTH (en el módulo ssl)

push() (método de asynchat.async_chat)

(método de code.InteractiveConsole)

(método de contextlib.ExitStack)

push_alignment() (método de formatter.formatter)

push_async_callback() (método de contextlib.AsyncExitStack)

push_async_exit() (método de contextlib.AsyncExitStack)

push_font() (método de formatter.formatter)

push_margin() (método de formatter.formatter)

push_source() (método de shlex.shlex)

push_style() (método de formatter.formatter)

push_token() (método de shlex.shlex)

push_with_producer() (método de asynchat.async_chat)

pushbutton() (método de msilib.Dialog)

put() (método de asyncio.Queue)

(método de multiprocessing.Queue)

(método de multiprocessing.SimpleQueue)

(método de queue.Queue)

(método de queue.SimpleQueue)

put_nowait() (método de asyncio.Queue)

(método de multiprocessing.Queue)

(método de queue.Queue)

(método de queue.SimpleQueue)

putch() (en el módulo msvcrt)

putenv() (en el módulo os)

putheader() (método de http.client.HTTPConnection)

putp() (en el módulo curses)

putrequest() (método de http.client.HTTPConnection)

putwch() (en el módulo msvcrt)

putwin() (método de curses.window)

pvariance() (en el módulo statistics)

pwd

módulo

pwd (módulo)

pwd() (método de ftplib.FTP)

pwrite() (en el módulo os)

pwritev() (en el módulo os)

Py_ABS (macro C)

Py_AddPendingCall (función C)

Py_AddPendingCall()

Py_AtExit (función C)

Py_BEGIN_ALLOW_THREADS

(macro C)

Py_BLOCK_THREADS (macro C)

Py_buffer (tipo C)

Py_buffer.buf (miembro C)

Py_buffer.format (miembro C)

Py_buffer.internal (miembro C)

Py_buffer.itemsize (miembro C)

Py_buffer.len (miembro C)

Py_buffer.ndim (miembro C)

Py_buffer.obj (miembro C)

Py_buffer.readonly (miembro C)

Py_buffer.shape (miembro C)

Py_buffer.strides (miembro C)

Py_buffer.suboffsets (miembro C)

Py_BuildValue (función C)

Py_BytesMain (función C)

Py_BytesWarningFlag (variable C)

Py_CHARMASK (macro C)

Py_CLEAR (función C)

py_compile (módulo)

PY_COMPILED (en el módulo imp)

Py_CompileString (función C)

Py_CompileString(), [1], [2]

Py_CompileStringExFlags (función C)

Py_CompileStringFlags (función C)

Py_CompileStringObject (función C)

Py_complex (tipo C)

Py_DebugFlag (variable C)

Py_DecodeLocale (función C)

Py_DECREF (función C)

Py_DECREF()

Py_DEPRECATED (macro C)

Py_DontWriteBytecodeFlag (variable C)

Py_Ellipsis (variable C)

Py_EncodeLocale (función C)

Py_END_ALLOW_THREADS

(macro C)

Py_EndInterpreter (función C)

Py_EnterRecursiveCall (función C)

Py_eval_input (variable C)

Py_Exit (función C)

Py_ExitStatusException (función C)

Py_False (variable C)

Py_FatalError (función C)

Py_FatalError()

Py_FdIsInteractive (función C)

Py_file_input (variable C)

Py_Finalize (función C)

Py_FinalizeEx (función C)

Py_FinalizeEx(), [1], [2], [3], [4]

PY_FROZEN (en el módulo imp)

Py_FrozenFlag (variable C)

Py_GenericAlias (función C)

Py_GenericAliasType (variable C)

Py_GetArgcArgv (función C)

Py_GetBuildInfo (función C)

Py_GetCompiler (función C)

Py_GetCopyright (función C)

Py_GETENV (macro C)

Py_GetExecPrefix (función C)

Py_GetExecPrefix()

Py_GetPath (función C)

Py_GetPath(), [1], [2]

Py_GetPlatform (función C)

Py_GetPrefix (función C)

Py_GetPrefix()

Py_GetProgramFullPath (función C)

Py_GetProgramFullPath()

Py_GetProgramName (función C)

Py_GetPythonHome (función C)

Py_GetVersion (función C)

Py_HashRandomizationFlag (variable C)

Py_IgnoreEnvironmentFlag (variable C)

Py_INCREF (función C)

Py_INCREF()

Py_Initialize (función C)

Py_Initialize(), [1], [2], [3]

Py_InitializeEx (función C)

Py_InitializeFromConfig (función C)

Py_InspectFlag (variable C)

Py_InteractiveFlag (variable C)

Py_IS_TYPE (función C)

Py_IsInitialized (función C)

Py_IsInitialized()

Py_IsolatedFlag (variable C)

Py_LeaveRecursiveCall (función C)

Py_LegacyWindowsFSEncodingFlag (variable C)

Py_LegacyWindowsStdioFlag (variable C)

Py_Main (función C)

Py_MAX (macro C)

Py_MEMBER_SIZE (macro C)

Py_MIN (macro C)

Py_mod_create (macro C)

Py_mod_exec (macro C)

Py_NewInterpreter (función C)

Py_None (variable C)

Py_NoSiteFlag (variable C)

Py_NotImplemented (variable C)

Py_NoUserSiteDirectory (variable C)

py_object (clase en ctypes)

Py_OptimizeFlag (variable C)

Py_PreInitialize (función C)

Py_PreInitializeFromArgs (función C)

Py_PreInitializeFromBytesArgs (función C)

Py_PRINT_RAW

PY_PYTHON

Py_QuietFlag (variable C)

Py_REFCNT (macro C)

Py_ReprEnter (función C)

Py_ReprLeave (función C)

Py_RETURN_FALSE (macro C)

Py_RETURN_NONE (macro C)

Py_RETURN_NOTIMPLEMENTED (macro C)

Py_RETURN_RICHCOMPARE (macro C)

Py_RETURN_TRUE (macro C)

Py_RunMain (función C)

Py_SET_REFCNT (función C)

Py_SET_SIZE (función C)

Py_SET_TYPE (función C)

Py_SetPath (función C)

Py_SetPath()

Py_SetProgramName (función C)

Py_SetProgramName(), [1], [2], [3]

Py_SetPythonHome (función C)

Py_SetStandardStreamEncoding (función C)

Py_single_input (variable C)

Py_SIZE (macro C)

PY_SOURCE (en el módulo imp)

Py_ssize_t (tipo C)

PY_SSIZE_T_MAX

Py_STRINGIFY (macro C)

Py_TPFLAGS_BASE_EXC_SUBCLASS (variable incorporada)

Py_TPFLAGS_BASETYPE (variable incorporada)

Py_TPFLAGS_BYTES_SUBCLASS (variable incorporada)

Py_TPFLAGS_DEFAULT (variable incorporada)

Py_TPFLAGS_DICT_SUBCLASS (variable incorporada)

Py_TPFLAGS_HAVE_FINALIZE (variable incorporada)

Py_TPFLAGS_HAVE_GC (variable incorporada)

Py_TPFLAGS_HAVE_VECTORCALL (variable incorporada)

Py_TPFLAGS_HEAPTYPE (variable incorporada)

Py_TPFLAGS_LIST_SUBCLASS (variable incorporada)

Py_TPFLAGS_LONG_SUBCLASS (variable incorporada)

Py_TPFLAGS_METHOD_DESCRIPTOR (variable incorporada)

Py_TPFLAGS_READY (variable incorporada)

Py_TPFLAGS_READYING (variable incorporada)

Py_TPFLAGS_TUPLE_SUBCLASS (variable incorporada)

Py_TPFLAGS_TYPE_SUBCLASS (variable incorporada)

Py_TPFLAGS_UNICODE_SUBCLASS (variable incorporada)

Py_tracefunc (tipo C)

Py_True (variable C)

Py_tss_NEEDS_INIT (macro C)

Py_tss_t (tipo C)

Py_TYPE (macro C)

Py_UCS1 (tipo C)

Py_UCS2 (tipo C)

Py_UCS4 (tipo C)

Py_UNBLOCK_THREADS (macro C)

Py_UnbufferedStdioFlag (variable C)

Py_UNICODE (tipo C)

Py_UNICODE_IS_HIGH_SURROGATE (macro C)

Py_UNICODE_IS_LOW_SURROGATE (macro C)

Py_UNICODE_IS_SURROGATE (macro C)

Py_UNICODE_ISALNUM (función C)

Py_UNICODE_ISALPHA (función C)

Py_UNICODE_ISDECIMAL (función C)

Py_UNICODE_ISDIGIT (función C)

Py_UNICODE_ISLINEBREAK (función C)

Py_UNICODE_ISLOWER (función C)

Py_UNICODE_ISNUMERIC (función C)

Py_UNICODE_ISPRINTABLE (función C)

Py_UNICODE_ISSPACE (función C)

Py_UNICODE_ISTITLE (función C)

Py_UNICODE_ISUPPER (función C)

Py_UNICODE_JOIN_SURROGATES (macro C)

Py_UNICODE_TODECIMAL (función C)

Py_UNICODE_TODIGIT (función C)

Py_UNICODE_TOLOWER (función C)

Py_UNICODE_TONUMERIC (función C)

Py_UNICODE_TOTITLE (función C)

Py_UNICODE_TOUPPER (función C)

Py_UNREACHABLE (macro C)

Py_UNUSED (macro C)

Py_VaBuildValue (función C)

PY_VECTORCALL_ARGUMENTS_OFFSET (macro C)

Py_VerboseFlag (variable C)

Py_VISIT (función C)

Py_XDECREF (función C)

Py_XDECREF()

Py_XINCREF (función C)

PyAnySet_Check (función C)

PyAnySet_CheckExact (función C)

PyArg_Parse (función C)

PyArg_ParseTuple (función C)

PyArg_ParseTuple()

PyArg_ParseTupleAndKeywords (función C)

PyArg_ParseTupleAndKeywords()

PyArg_UnpackTuple (función C)

PyArg_ValidateKeywordArguments (función C)

PyArg_VaParse (función C)

PyArg_VaParseTupleAndKeywords (función C)

PyASCIIObject (tipo C)

PyAsyncMethods (tipo C)

PyAsyncMethods.am_aiter (miembro C)

PyAsyncMethods.am_anext (miembro C)

PyAsyncMethods.am_await (miembro C)

PyBool_Check (función C)

PyBool_FromLong (función C)

PyBUF_ANY_CONTIGUOUS (macro C)

PyBUF_C_CONTIGUOUS (macro C)

PyBUF_CONTIG (macro C)

PyBUF_CONTIG_RO (macro C)

PyBUF_F_CONTIGUOUS (macro C)

PyBUF_FORMAT (macro C)

PyBUF_FULL (macro C)

PyBUF_FULL_RO (macro C)

PyBUF_INDIRECT (macro C)

PyBUF_ND (macro C)

PyBUF_RECORDS (macro C)

PyBUF_RECORDS_RO (macro C)

PyBUF_SIMPLE (macro C)

PyBUF_STRIDED (macro C)

PyBUF_STRIDED_RO (macro C)

PyBUF_STRIDES (macro C)

PyBUF_WRITABLE (macro C)

PyBuffer_FillContiguousStrides (función C)

PyBuffer_FillInfo (función C)

PyBuffer_FromContiguous (función C)

PyBuffer_GetPointer (función C)

PyBuffer_IsContiguous (función C)

PyBuffer_Release (función C)

PyBuffer_SizeFromFormat (función C)

PyBuffer_ToContiguous (función C)

PyBufferProcs

(tipo C)

PyBufferProcs.bf_getbuffer (miembro C)

PyBufferProcs.bf_releasebuffer (miembro C)

PyByteArray_AS_STRING (función C)

PyByteArray_AsString (función C)

PyByteArray_Check (función C)

PyByteArray_CheckExact (función C)

PyByteArray_Concat (función C)

PyByteArray_FromObject (función C)

PyByteArray_FromStringAndSize (función C)

PyByteArray_GET_SIZE (función C)

PyByteArray_Resize (función C)

PyByteArray_Size (función C)

PyByteArray_Type (variable C)

PyByteArrayObject (tipo C)

PyBytes_AS_STRING (función C)

PyBytes_AsString (función C)

PyBytes_AsStringAndSize (función C)

PyBytes_Check (función C)

PyBytes_CheckExact (función C)

PyBytes_Concat (función C)

PyBytes_ConcatAndDel (función C)

PyBytes_FromFormat (función C)

PyBytes_FromFormatV (función C)

PyBytes_FromObject (función C)

PyBytes_FromString (función C)

PyBytes_FromStringAndSize (función C)

PyBytes_GET_SIZE (función C)

PyBytes_Size (función C)

PyBytes_Type (variable C)

PyBytesObject (tipo C)

pycache_prefix (en el módulo sys)

PyCallable_Check (función C)

PyCallIter_Check (función C)

PyCallIter_New (función C)

PyCallIter_Type (variable C)

PyCapsule (tipo C)

PyCapsule_CheckExact (función C)

PyCapsule_Destructor (tipo C)

PyCapsule_GetContext (función C)

PyCapsule_GetDestructor (función C)

PyCapsule_GetName (función C)

PyCapsule_GetPointer (función C)

PyCapsule_Import (función C)

PyCapsule_IsValid (función C)

PyCapsule_New (función C)

PyCapsule_SetContext (función C)

PyCapsule_SetDestructor (función C)

PyCapsule_SetName (función C)

PyCapsule_SetPointer (función C)

PyCell_Check (función C)

PyCell_GET (función C)

PyCell_Get (función C)

PyCell_New (función C)

PyCell_SET (función C)

PyCell_Set (función C)

PyCell_Type (variable C)

PyCellObject (tipo C)

PyCF_ALLOW_TOP_LEVEL_AWAIT (en el módulo ast)

PyCF_ONLY_AST (en el módulo ast)

PyCF_TYPE_COMMENTS (en el módulo ast)

PyCFunction (tipo C)

PyCFunctionWithKeywords (tipo C)

PycInvalidationMode (clase en py_compile)

pyclbr (módulo)

PyCMethod (tipo C)

PyCode_Check (función C)

PyCode_GetNumFree (función C)

PyCode_New (función C)

PyCode_NewEmpty (función C)

PyCode_NewWithPosOnlyArgs (función C)

PyCode_Type (variable C)

PyCodec_BackslashReplaceErrors (función C)

PyCodec_Decode (función C)

PyCodec_Decoder (función C)

PyCodec_Encode (función C)

PyCodec_Encoder (función C)

PyCodec_IgnoreErrors (función C)

PyCodec_IncrementalDecoder (función C)

PyCodec_IncrementalEncoder (función C)

PyCodec_KnownEncoding (función C)

PyCodec_LookupError (función C)

PyCodec_NameReplaceErrors (función C)

PyCodec_Register (función C)

PyCodec_RegisterError (función C)

PyCodec_ReplaceErrors (función C)

PyCodec_StreamReader (función C)

PyCodec_StreamWriter (función C)

PyCodec_StrictErrors (función C)

PyCodec_XMLCharRefReplaceErrors (función C)

PyCodeObject (tipo C)

PyCompactUnicodeObject (tipo C)

PyCompileError

PyCompilerFlags (tipo C)

PyCompilerFlags.cf_feature_version (miembro C)

PyCompilerFlags.cf_flags (miembro C)

PyComplex_AsCComplex (función C)

PyComplex_Check (función C)

PyComplex_CheckExact (función C)

PyComplex_FromCComplex (función C)

PyComplex_FromDoubles (función C)

PyComplex_ImagAsDouble (función C)

PyComplex_RealAsDouble (función C)

PyComplex_Type (variable C)

PyComplexObject (tipo C)

PyConfig (tipo C)

PyConfig._use_peg_parser (miembro C)

PyConfig.argv (miembro C)

PyConfig.base_exec_prefix (miembro C)

PyConfig.base_executable (miembro C)

PyConfig.base_prefix (miembro C)

PyConfig.buffered_stdio (miembro C)

PyConfig.bytes_warning (miembro C)

PyConfig.check_hash_pycs_mode (miembro C)

PyConfig.configure_c_stdio (miembro C)

PyConfig.dev_mode (miembro C)

PyConfig.dump_refs (miembro C)

PyConfig.exec_prefix (miembro C)

PyConfig.executable (miembro C)

PyConfig.faulthandler (miembro C)

PyConfig.filesystem_encoding (miembro C)

PyConfig.filesystem_errors (miembro C)

PyConfig.hash_seed (miembro C)

PyConfig.home (miembro C)

PyConfig.import_time (miembro C)

PyConfig.inspect (miembro C)

PyConfig.install_signal_handlers (miembro C)

PyConfig.interactive (miembro C)

PyConfig.isolated (miembro C)

PyConfig.legacy_windows_stdio (miembro C)

PyConfig.malloc_stats (miembro C)

PyConfig.module_search_paths (miembro C)

PyConfig.module_search_paths_set (miembro C)

PyConfig.optimization_level (miembro C)

PyConfig.parse_argv (miembro C)

PyConfig.parser_debug (miembro C)

PyConfig.pathconfig_warnings (miembro C)

PyConfig.platlibdir (miembro C)

PyConfig.prefix (miembro C)

PyConfig.program_name (miembro C)

PyConfig.pycache_prefix (miembro C)

PyConfig.pythonpath_env (miembro C)

PyConfig.quiet (miembro C)

PyConfig.run_command (miembro C)

PyConfig.run_filename (miembro C)

PyConfig.run_module (miembro C)

PyConfig.show_ref_count (miembro C)

PyConfig.site_import (miembro C)

PyConfig.skip_source_first_line (miembro C)

PyConfig.stdio_encoding (miembro C)

PyConfig.stdio_errors (miembro C)

PyConfig.tracemalloc (miembro C)

PyConfig.use_environment (miembro C)

PyConfig.use_hash_seed (miembro C)

PyConfig.user_site_directory (miembro C)

PyConfig.verbose (miembro C)

PyConfig.warnoptions (miembro C)

PyConfig.write_bytecode (miembro C)

PyConfig.xoptions (miembro C)

PyConfig_Clear (función C)

PyConfig_InitIsolatedConfig (función C)

PyConfig_InitPythonConfig (función C)

PyConfig_Read (función C)

PyConfig_SetArgv (función C)

PyConfig_SetBytesArgv (función C)

PyConfig_SetBytesString (función C)

PyConfig_SetString (función C)

PyConfig_SetWideStringList (función C)

PyContext (tipo C)

PyContext_CheckExact (función C)

PyContext_Copy (función C)

PyContext_CopyCurrent (función C)

PyContext_Enter (función C)

PyContext_Exit (función C)

PyContext_New (función C)

PyContext_Type (variable C)

PyContextToken (tipo C)

PyContextToken_CheckExact (función C)

PyContextToken_Type (variable C)

PyContextVar (tipo C)

PyContextVar_CheckExact (función C)

PyContextVar_Get (función C)

PyContextVar_New (función C)

PyContextVar_Reset (función C)

PyContextVar_Set (función C)

PyContextVar_Type (variable C)

PyCoro_CheckExact (función C)

PyCoro_New (función C)

PyCoro_Type (variable C)

PyCoroObject (tipo C)

PyDate_Check (función C)

PyDate_CheckExact (función C)

PyDate_FromDate (función C)

PyDate_FromTimestamp (función C)

PyDateTime_Check (función C)

PyDateTime_CheckExact (función C)

PyDateTime_DATE_GET_FOLD (función C)

PyDateTime_DATE_GET_HOUR (función C)

PyDateTime_DATE_GET_MICROSECOND (función C)

PyDateTime_DATE_GET_MINUTE (función C)

PyDateTime_DATE_GET_SECOND (función C)

PyDateTime_DELTA_GET_DAYS (función C)

PyDateTime_DELTA_GET_MICROSECONDS (función C)

PyDateTime_DELTA_GET_SECONDS (función C)

PyDateTime_FromDateAndTime (función C)

PyDateTime_FromDateAndTimeAndFold (función C)

PyDateTime_FromTimestamp (función C)

PyDateTime_GET_DAY (función C)

PyDateTime_GET_MONTH (función C)

PyDateTime_GET_YEAR (función C)

PyDateTime_TIME_GET_FOLD (función C)

PyDateTime_TIME_GET_HOUR (función C)

PyDateTime_TIME_GET_MICROSECOND (función C)

PyDateTime_TIME_GET_MINUTE (función C)

PyDateTime_TIME_GET_SECOND (función C)

PyDateTime_TimeZone_UTC (variable C)

PyDelta_Check (función C)

PyDelta_CheckExact (función C)

PyDelta_FromDSU (función C)

PyDescr_IsData (función C)

PyDescr_NewClassMethod (función C)

PyDescr_NewGetSet (función C)

PyDescr_NewMember (función C)

PyDescr_NewMethod (función C)

PyDescr_NewWrapper (función C)

PyDict_Check (función C)

PyDict_CheckExact (función C)

PyDict_Clear (función C)

PyDict_Contains (función C)

PyDict_Copy (función C)

PyDict_DelItem (función C)

PyDict_DelItemString (función C)

PyDict_GetItem (función C)

PyDict_GetItemString (función C)

PyDict_GetItemWithError (función C)

PyDict_Items (función C)

PyDict_Keys (función C)

PyDict_Merge (función C)

PyDict_MergeFromSeq2 (función C)

PyDict_New (función C)

PyDict_Next (función C)

PyDict_SetDefault (función C)

PyDict_SetItem (función C)

PyDict_SetItemString (función C)

PyDict_Size (función C)

PyDict_Type (variable C)

PyDict_Update (función C)

PyDict_Values (función C)

PyDictObject (tipo C)

PyDictProxy_New (función C)

PyDLL (clase en ctypes)

pydoc (módulo)

PyDoc_STR (macro C)

PyDoc_STRVAR (macro C)

PyErr_BadArgument (función C)

PyErr_BadInternalCall (función C)

PyErr_CheckSignals (función C)

PyErr_Clear (función C)

PyErr_Clear(), [1]

PyErr_ExceptionMatches (función C)

PyErr_ExceptionMatches()

PyErr_Fetch (función C)

PyErr_Fetch()

PyErr_Format (función C)

PyErr_FormatV (función C)

PyErr_GetExcInfo (función C)

PyErr_GivenExceptionMatches (función C)

PyErr_NewException (función C)

PyErr_NewExceptionWithDoc (función C)

PyErr_NoMemory (función C)

PyErr_NormalizeException (función C)

PyErr_Occurred (función C)

PyErr_Occurred()

PyErr_Print (función C)

PyErr_PrintEx (función C)

PyErr_ResourceWarning (función C)

PyErr_Restore (función C)

PyErr_Restore()

PyErr_SetExcFromWindowsErr (función C)

PyErr_SetExcFromWindowsErrWithFilename (función C)

PyErr_SetExcFromWindowsErrWithFilenameObject (función C)

PyErr_SetExcFromWindowsErrWithFilenameObjects (función C)

PyErr_SetExcInfo (función C)

PyErr_SetFromErrno (función C)

PyErr_SetFromErrnoWithFilename (función C)

PyErr_SetFromErrnoWithFilenameObject (función C)

PyErr_SetFromErrnoWithFilenameObjects (función C)

PyErr_SetFromWindowsErr (función C)

PyErr_SetFromWindowsErrWithFilename (función C)

PyErr_SetImportError (función C)

PyErr_SetImportErrorSubclass (función C)

PyErr_SetInterrupt (función C)

PyErr_SetNone (función C)

PyErr_SetObject (función C)

PyErr_SetString (función C)

PyErr_SetString()

PyErr_SyntaxLocation (función C)

PyErr_SyntaxLocationEx (función C)

PyErr_SyntaxLocationObject (función C)

PyErr_WarnEx (función C)

PyErr_WarnExplicit (función C)

PyErr_WarnExplicitObject (función C)

PyErr_WarnFormat (función C)

PyErr_WriteUnraisable (función C)

PyEval_AcquireLock (función C)

PyEval_AcquireThread (función C)

PyEval_AcquireThread()

PyEval_EvalCode (función C)

PyEval_EvalCodeEx (función C)

PyEval_EvalFrame (función C)

PyEval_EvalFrameEx (función C)

PyEval_GetBuiltins (función C)

PyEval_GetFrame (función C)

PyEval_GetFuncDesc (función C)

PyEval_GetFuncName (función C)

PyEval_GetGlobals (función C)

PyEval_GetLocals (función C)

PyEval_InitThreads (función C)

PyEval_InitThreads()

PyEval_MergeCompilerFlags (función C)

PyEval_ReleaseLock (función C)

PyEval_ReleaseThread (función C)

PyEval_ReleaseThread()

PyEval_RestoreThread (función C)

PyEval_RestoreThread(), [1]

PyEval_SaveThread (función C)

PyEval_SaveThread(), [1]

PyEval_SetProfile (función C)

PyEval_SetTrace (función C)

PyEval_ThreadsInitialized (función C)

PyExc_ArithmeticError

PyExc_AssertionError

PyExc_AttributeError

PyExc_BaseException

PyExc_BlockingIOError

PyExc_BrokenPipeError

PyExc_BufferError

PyExc_BytesWarning

PyExc_ChildProcessError

PyExc_ConnectionAbortedError

PyExc_ConnectionError

PyExc_ConnectionRefusedError

PyExc_ConnectionResetError

PyExc_DeprecationWarning

PyExc_EnvironmentError

PyExc_EOFError

PyExc_Exception

PyExc_FileExistsError

PyExc_FileNotFoundError

PyExc_FloatingPointError

PyExc_FutureWarning

PyExc_GeneratorExit

PyExc_ImportError

PyExc_ImportWarning

PyExc_IndentationError

PyExc_IndexError

PyExc_InterruptedError

PyExc_IOError

PyExc_IsADirectoryError

PyExc_KeyboardInterrupt

PyExc_KeyError

PyExc_LookupError

PyExc_MemoryError

PyExc_ModuleNotFoundError

PyExc_NameError

PyExc_NotADirectoryError

PyExc_NotImplementedError

PyExc_OSError

PyExc_OverflowError

PyExc_PendingDeprecationWarning

PyExc_PermissionError

PyExc_ProcessLookupError

PyExc_RecursionError

PyExc_ReferenceError

PyExc_ResourceWarning

PyExc_RuntimeError

PyExc_RuntimeWarning

PyExc_StopAsyncIteration

PyExc_StopIteration

PyExc_SyntaxError

PyExc_SyntaxWarning

PyExc_SystemError

PyExc_SystemExit

PyExc_TabError

PyExc_TimeoutError

PyExc_TypeError

PyExc_UnboundLocalError

PyExc_UnicodeDecodeError

PyExc_UnicodeEncodeError

PyExc_UnicodeError

PyExc_UnicodeTranslateError

PyExc_UnicodeWarning

PyExc_UserWarning

PyExc_ValueError

PyExc_Warning

PyExc_WindowsError

PyExc_ZeroDivisionError

PyException_GetCause (función C)

PyException_GetContext (función C)

PyException_GetTraceback (función C)

PyException_SetCause (función C)

PyException_SetContext (función C)

PyException_SetTraceback (función C)

pyexpat

módulo

PyFile_FromFd (función C)

PyFile_GetLine (función C)

PyFile_SetOpenCodeHook (función C)

PyFile_WriteObject (función C)

PyFile_WriteString (función C)

PyFloat_AS_DOUBLE (función C)

PyFloat_AsDouble (función C)

PyFloat_Check (función C)

PyFloat_CheckExact (función C)

PyFloat_FromDouble (función C)

PyFloat_FromString (función C)

PyFloat_GetInfo (función C)

PyFloat_GetMax (función C)

PyFloat_GetMin (función C)

PyFloat_Type (variable C)

PyFloatObject (tipo C)

PyFrame_GetBack (función C)

PyFrame_GetCode (función C)

PyFrame_GetLineNumber (función C)

PyFrameObject (tipo C)

PyFrozenSet_Check (función C)

PyFrozenSet_CheckExact (función C)

PyFrozenSet_New (función C)

PyFrozenSet_Type (variable C)

PyFunction_Check (función C)

PyFunction_GetAnnotations (función C)

PyFunction_GetClosure (función C)

PyFunction_GetCode (función C)

PyFunction_GetDefaults (función C)

PyFunction_GetGlobals (función C)

PyFunction_GetModule (función C)

PyFunction_New (función C)

PyFunction_NewWithQualName (función C)

PyFunction_SetAnnotations (función C)

PyFunction_SetClosure (función C)

PyFunction_SetDefaults (función C)

PyFunction_Type (variable C)

PyFunctionObject (tipo C)

PYFUNCTYPE() (en el módulo ctypes)

PyGen_Check (función C)

PyGen_CheckExact (función C)

PyGen_New (función C)

PyGen_NewWithQualName (función C)

PyGen_Type (variable C)

PyGenObject (tipo C)

PyGetSetDef (tipo C)

PyGILState_Check (función C)

PyGILState_Ensure (función C)

PyGILState_GetThisThreadState (función C)

PyGILState_Release (función C)

PyImport_AddModule (función C)

PyImport_AddModuleObject (función C)

PyImport_AppendInittab (función C)

PyImport_ExecCodeModule (función C)

PyImport_ExecCodeModuleEx (función C)

PyImport_ExecCodeModuleObject (función C)

PyImport_ExecCodeModuleWithPathnames (función C)

PyImport_ExtendInittab (función C)

PyImport_FrozenModules (variable C)

PyImport_GetImporter (función C)

PyImport_GetMagicNumber (función C)

PyImport_GetMagicTag (función C)

PyImport_GetModule (función C)

PyImport_GetModuleDict (función C)

PyImport_Import (función C)

PyImport_ImportFrozenModule (función C)

PyImport_ImportFrozenModuleObject (función C)

PyImport_ImportModule (función C)

PyImport_ImportModuleEx (función C)

PyImport_ImportModuleLevel (función C)

PyImport_ImportModuleLevelObject (función C)

PyImport_ImportModuleNoBlock (función C)

PyImport_ReloadModule (función C)

PyIndex_Check (función C)

PyInit_modulename (función C)

PyInstanceMethod_Check (función C)

PyInstanceMethod_Function (función C)

PyInstanceMethod_GET_FUNCTION (función C)

PyInstanceMethod_New (función C)

PyInstanceMethod_Type (variable C)

PyInterpreterState (tipo C)

PyInterpreterState_Clear (función C)

PyInterpreterState_Delete (función C)

PyInterpreterState_Get (función C)

PyInterpreterState_GetDict (función C)

PyInterpreterState_GetID (función C)

PyInterpreterState_Head (función C)

PyInterpreterState_Main (función C)

PyInterpreterState_New (función C)

PyInterpreterState_Next (función C)

PyInterpreterState_ThreadHead (función C)

PyIter_Check (función C)

PyIter_Next (función C)

PyList_Append (función C)

PyList_AsTuple (función C)

PyList_Check (función C)

PyList_CheckExact (función C)

PyList_GET_ITEM (función C)

PyList_GET_SIZE (función C)

PyList_GetItem (función C)

PyList_GetItem()

PyList_GetSlice (función C)

PyList_Insert (función C)

PyList_New (función C)

PyList_Reverse (función C)

PyList_SET_ITEM (función C)

PyList_SetItem (función C)

PyList_SetItem()

PyList_SetSlice (función C)

PyList_Size (función C)

PyList_Sort (función C)

PyList_Type (variable C)

PyListObject (tipo C)

PyLong_AsDouble (función C)

PyLong_AsLong (función C)

PyLong_AsLongAndOverflow (función C)

PyLong_AsLongLong (función C)

PyLong_AsLongLongAndOverflow (función C)

PyLong_AsSize_t (función C)

PyLong_AsSsize_t (función C)

PyLong_AsUnsignedLong (función C)

PyLong_AsUnsignedLongLong (función C)

PyLong_AsUnsignedLongLongMask (función C)

PyLong_AsUnsignedLongMask (función C)

PyLong_AsVoidPtr (función C)

PyLong_Check (función C)

PyLong_CheckExact (función C)

PyLong_FromDouble (función C)

PyLong_FromLong (función C)

PyLong_FromLongLong (función C)

PyLong_FromSize_t (función C)

PyLong_FromSsize_t (función C)

PyLong_FromString (función C)

PyLong_FromUnicode (función C)

PyLong_FromUnicodeObject (función C)

PyLong_FromUnsignedLong (función C)

PyLong_FromUnsignedLongLong (función C)

PyLong_FromVoidPtr (función C)

PyLong_Type (variable C)

PyLongObject (tipo C)

PyMapping_Check (función C)

PyMapping_DelItem (función C)

PyMapping_DelItemString (función C)

PyMapping_GetItemString (función C)

PyMapping_HasKey (función C)

PyMapping_HasKeyString (función C)

PyMapping_Items (función C)

PyMapping_Keys (función C)

PyMapping_Length (función C)

PyMapping_SetItemString (función C)

PyMapping_Size (función C)

PyMapping_Values (función C)

PyMappingMethods (tipo C)

PyMappingMethods.mp_ass_subscript (miembro C)

PyMappingMethods.mp_length (miembro C)

PyMappingMethods.mp_subscript (miembro C)

PyMarshal_ReadLastObjectFromFile (función C)

PyMarshal_ReadLongFromFile (función C)

PyMarshal_ReadObjectFromFile (función C)

PyMarshal_ReadObjectFromString (función C)

PyMarshal_ReadShortFromFile (función C)

PyMarshal_WriteLongToFile (función C)

PyMarshal_WriteObjectToFile (función C)

PyMarshal_WriteObjectToString (función C)

PyMem_Calloc (función C)

PyMem_Del (función C)

PYMEM_DOMAIN_MEM (macro C)

PYMEM_DOMAIN_OBJ (macro C)

PYMEM_DOMAIN_RAW (macro C)

PyMem_Free (función C)

PyMem_GetAllocator (función C)

PyMem_Malloc (función C)

PyMem_New (función C)

PyMem_RawCalloc (función C)

PyMem_RawFree (función C)

PyMem_RawMalloc (función C)

PyMem_RawRealloc (función C)

PyMem_Realloc (función C)

PyMem_Resize (función C)

PyMem_SetAllocator (función C)

PyMem_SetupDebugHooks (función C)

PyMemAllocatorDomain (tipo C)

PyMemAllocatorEx (tipo C)

PyMember_GetOne (función C)

PyMember_SetOne (función C)

PyMemberDef (tipo C)

PyMemoryView_Check (función C)

PyMemoryView_FromBuffer (función C)

PyMemoryView_FromMemory (función C)

PyMemoryView_FromObject (función C)

PyMemoryView_GET_BASE (función C)

PyMemoryView_GET_BUFFER (función C)

PyMemoryView_GetContiguous (función C)

PyMethod_Check (función C)

PyMethod_Function (función C)

PyMethod_GET_FUNCTION (función C)

PyMethod_GET_SELF (función C)

PyMethod_New (función C)

PyMethod_Self (función C)

PyMethod_Type (variable C)

PyMethodDef (tipo C)

PyModule_AddFunctions (función C)

PyModule_AddIntConstant (función C)

PyModule_AddIntMacro (función C)

PyModule_AddObject (función C)

PyModule_AddStringConstant (función C)

PyModule_AddStringMacro (función C)

PyModule_AddType (función C)

PyModule_Check (función C)

PyModule_CheckExact (función C)

PyModule_Create (función C)

PyModule_Create2 (función C)

PyModule_ExecDef (función C)

PyModule_FromDefAndSpec (función C)

PyModule_FromDefAndSpec2 (función C)

PyModule_GetDef (función C)

PyModule_GetDict (función C)

PyModule_GetFilename (función C)

PyModule_GetFilenameObject (función C)

PyModule_GetName (función C)

PyModule_GetNameObject (función C)

PyModule_GetState (función C)

PyModule_New (función C)

PyModule_NewObject (función C)

PyModule_SetDocString (función C)

PyModule_Type (variable C)

PyModuleDef (tipo C)

PyModuleDef.m_base (miembro C)

PyModuleDef.m_clear (miembro C)

PyModuleDef.m_doc (miembro C)

PyModuleDef.m_free (miembro C)

PyModuleDef.m_methods (miembro C)

PyModuleDef.m_name (miembro C)

PyModuleDef.m_reload (miembro C)

PyModuleDef.m_size (miembro C)

PyModuleDef.m_slots (miembro C)

PyModuleDef.m_traverse (miembro C)

PyModuleDef_Init (función C)

PyModuleDef_Slot (tipo C)

PyModuleDef_Slot.slot (miembro C)

PyModuleDef_Slot.value (miembro C)

PyNumber_Absolute (función C)

PyNumber_Add (función C)

PyNumber_And (función C)

PyNumber_AsSsize_t (función C)

PyNumber_Check (función C)

PyNumber_Divmod (función C)

PyNumber_Float (función C)

PyNumber_FloorDivide (función C)

PyNumber_Index (función C)

PyNumber_InPlaceAdd (función C)

PyNumber_InPlaceAnd (función C)

PyNumber_InPlaceFloorDivide (función C)

PyNumber_InPlaceLshift (función C)

PyNumber_InPlaceMatrixMultiply (función C)

PyNumber_InPlaceMultiply (función C)

PyNumber_InPlaceOr (función C)

PyNumber_InPlacePower (función C)

PyNumber_InPlaceRemainder (función C)

PyNumber_InPlaceRshift (función C)

PyNumber_InPlaceSubtract (función C)

PyNumber_InPlaceTrueDivide (función C)

PyNumber_InPlaceXor (función C)

PyNumber_Invert (función C)

PyNumber_Long (función C)

PyNumber_Lshift (función C)

PyNumber_MatrixMultiply (función C)

PyNumber_Multiply (función C)

PyNumber_Negative (función C)

PyNumber_Or (función C)

PyNumber_Positive (función C)

PyNumber_Power (función C)

PyNumber_Remainder (función C)

PyNumber_Rshift (función C)

PyNumber_Subtract (función C)

PyNumber_ToBase (función C)

PyNumber_TrueDivide (función C)

PyNumber_Xor (función C)

PyNumberMethods (tipo C)

PyNumberMethods.nb_absolute (miembro C)

PyNumberMethods.nb_add (miembro C)

PyNumberMethods.nb_and (miembro C)

PyNumberMethods.nb_bool (miembro C)

PyNumberMethods.nb_divmod (miembro C)

PyNumberMethods.nb_float (miembro C)

PyNumberMethods.nb_floor_divide (miembro C)

PyNumberMethods.nb_index (miembro C)

PyNumberMethods.nb_inplace_add (miembro C)

PyNumberMethods.nb_inplace_and (miembro C)

PyNumberMethods.nb_inplace_floor_divide (miembro C)

PyNumberMethods.nb_inplace_lshift (miembro C)

PyNumberMethods.nb_inplace_matrix_multiply (miembro C)

PyNumberMethods.nb_inplace_multiply (miembro C)

PyNumberMethods.nb_inplace_or (miembro C)

PyNumberMethods.nb_inplace_power (miembro C)

PyNumberMethods.nb_inplace_remainder (miembro C)

PyNumberMethods.nb_inplace_rshift (miembro C)

PyNumberMethods.nb_inplace_subtract (miembro C)

PyNumberMethods.nb_inplace_true_divide (miembro C)

PyNumberMethods.nb_inplace_xor (miembro C)

PyNumberMethods.nb_int (miembro C)

PyNumberMethods.nb_invert (miembro C)

PyNumberMethods.nb_lshift (miembro C)

PyNumberMethods.nb_matrix_multiply (miembro C)

PyNumberMethods.nb_multiply (miembro C)

PyNumberMethods.nb_negative (miembro C)

PyNumberMethods.nb_or (miembro C)

PyNumberMethods.nb_positive (miembro C)

PyNumberMethods.nb_power (miembro C)

PyNumberMethods.nb_remainder (miembro C)

PyNumberMethods.nb_reserved (miembro C)

PyNumberMethods.nb_rshift (miembro C)

PyNumberMethods.nb_subtract (miembro C)

PyNumberMethods.nb_true_divide (miembro C)

PyNumberMethods.nb_xor (miembro C)

PyObject (tipo C)

PyObject._ob_next (miembro C)

PyObject._ob_prev (miembro C)

PyObject.ob_refcnt (miembro C)

PyObject.ob_type (miembro C)

PyObject_AsCharBuffer (función C)

PyObject_ASCII (función C)

PyObject_AsFileDescriptor (función C)

PyObject_AsReadBuffer (función C)

PyObject_AsWriteBuffer (función C)

PyObject_Bytes (función C)

PyObject_Call (función C)

PyObject_CallFunction (función C)

PyObject_CallFunctionObjArgs (función C)

PyObject_CallMethod (función C)

PyObject_CallMethodNoArgs (función C)

PyObject_CallMethodObjArgs (función C)

PyObject_CallMethodOneArg (función C)

PyObject_CallNoArgs (función C)

PyObject_CallObject (función C)

PyObject_CallObject()

PyObject_Calloc (función C)

PyObject_CallOneArg (función C)

PyObject_CheckBuffer (función C)

PyObject_CheckReadBuffer (función C)

PyObject_Del (función C)

PyObject_DelAttr (función C)

PyObject_DelAttrString (función C)

PyObject_DelItem (función C)

PyObject_Dir (función C)

PyObject_Free (función C)

PyObject_GC_Del (función C)

PyObject_GC_IsFinalized (función C)

PyObject_GC_IsTracked (función C)

PyObject_GC_New (función C)

PyObject_GC_NewVar (función C)

PyObject_GC_Resize (función C)

PyObject_GC_Track (función C)

PyObject_GC_UnTrack (función C)

PyObject_GenericGetAttr (función C)

PyObject_GenericGetDict (función C)

PyObject_GenericSetAttr (función C)

PyObject_GenericSetDict (función C)

PyObject_GetArenaAllocator (función C)

PyObject_GetAttr (función C)

PyObject_GetAttrString (función C)

PyObject_GetBuffer (función C)

PyObject_GetItem (función C)

PyObject_GetIter (función C)

PyObject_HasAttr (función C)

PyObject_HasAttrString (función C)

PyObject_Hash (función C)

PyObject_HashNotImplemented (función C)

PyObject_HEAD (macro C)

PyObject_HEAD_INIT (macro C)

PyObject_Init (función C)

PyObject_InitVar (función C)

PyObject_IS_GC (función C)

PyObject_IsInstance (función C)

PyObject_IsSubclass (función C)

PyObject_IsTrue (función C)

PyObject_Length (función C)

PyObject_LengthHint (función C)

PyObject_Malloc (función C)

PyObject_New (función C)

PyObject_NewVar (función C)

PyObject_Not (función C)

PyObject_Print (función C)

PyObject_Realloc (función C)

PyObject_Repr (función C)

PyObject_RichCompare (función C)

PyObject_RichCompareBool (función C)

PyObject_SetArenaAllocator (función C)

PyObject_SetAttr (función C)

PyObject_SetAttrString (función C)

PyObject_SetItem (función C)

PyObject_Size (función C)

PyObject_Str (función C)

PyObject_Type (función C)

PyObject_TypeCheck (función C)

PyObject_VAR_HEAD (macro C)

PyObject_Vectorcall (función C)

PyObject_VectorcallDict (función C)

PyObject_VectorcallMethod (función C)

PyObjectArenaAllocator (tipo C)

PyOS_AfterFork (función C)

PyOS_AfterFork_Child (función C)

PyOS_AfterFork_Parent (función C)

PyOS_BeforeFork (función C)

PyOS_CheckStack (función C)

PyOS_double_to_string (función C)

PyOS_FSPath (función C)

PyOS_getsig (función C)

PyOS_InputHook (variable C)

PyOS_ReadlineFunctionPointer (variable C)

PyOS_setsig (función C)

PyOS_snprintf (función C)

PyOS_stricmp (función C)

PyOS_string_to_double (función C)

PyOS_strnicmp (función C)

PyOS_vsnprintf (función C)

PyParser_SimpleParseFile (función C)

PyParser_SimpleParseFileFlags (función C)

PyParser_SimpleParseString (función C)

PyParser_SimpleParseStringFlags (función C)

PyParser_SimpleParseStringFlagsFilename (función C)

PyPI

(see Python Package Index (PyPI))

PyPreConfig (tipo C)

PyPreConfig.allocator (miembro C)

PyPreConfig.coerce_c_locale (miembro C)

PyPreConfig.coerce_c_locale_warn (miembro C)

PyPreConfig.configure_locale (miembro C)

PyPreConfig.dev_mode (miembro C)

PyPreConfig.isolated (miembro C)

PyPreConfig.legacy_windows_fs_encoding (miembro C)

PyPreConfig.parse_argv (miembro C)

PyPreConfig.use_environment (miembro C)

PyPreConfig.utf8_mode (miembro C)

PyPreConfig_InitIsolatedConfig (función C)

PyPreConfig_InitPythonConfig (función C)

PyProperty_Type (variable C)

PyRun_AnyFile (función C)

PyRun_AnyFileEx (función C)

PyRun_AnyFileExFlags (función C)

PyRun_AnyFileFlags (función C)

PyRun_File (función C)

PyRun_FileEx (función C)

PyRun_FileExFlags (función C)

PyRun_FileFlags (función C)

PyRun_InteractiveLoop (función C)

PyRun_InteractiveLoopFlags (función C)

PyRun_InteractiveOne (función C)

PyRun_InteractiveOneFlags (función C)

PyRun_SimpleFile (función C)

PyRun_SimpleFileEx (función C)

PyRun_SimpleFileExFlags (función C)

PyRun_SimpleString (función C)

PyRun_SimpleStringFlags (función C)

PyRun_String (función C)

PyRun_StringFlags (función C)

PySeqIter_Check (función C)

PySeqIter_New (función C)

PySeqIter_Type (variable C)

PySequence_Check (función C)

PySequence_Concat (función C)

PySequence_Contains (función C)

PySequence_Count (función C)

PySequence_DelItem (función C)

PySequence_DelSlice (función C)

PySequence_Fast (función C)

PySequence_Fast_GET_ITEM (función C)

PySequence_Fast_GET_SIZE (función C)

PySequence_Fast_ITEMS (función C)

PySequence_GetItem (función C)

PySequence_GetItem()

PySequence_GetSlice (función C)

PySequence_Index (función C)

PySequence_InPlaceConcat (función C)

PySequence_InPlaceRepeat (función C)

PySequence_ITEM (función C)

PySequence_Length (función C)

PySequence_List (función C)

PySequence_Repeat (función C)

PySequence_SetItem (función C)

PySequence_SetSlice (función C)

PySequence_Size (función C)

PySequence_Tuple (función C)

PySequenceMethods (tipo C)

PySequenceMethods.sq_ass_item (miembro C)

PySequenceMethods.sq_concat (miembro C)

PySequenceMethods.sq_contains (miembro C)

PySequenceMethods.sq_inplace_concat (miembro C)

PySequenceMethods.sq_inplace_repeat (miembro C)

PySequenceMethods.sq_item (miembro C)

PySequenceMethods.sq_length (miembro C)

PySequenceMethods.sq_repeat (miembro C)

PySet_Add (función C)

PySet_Check (función C)

PySet_Clear (función C)

PySet_Contains (función C)

PySet_Discard (función C)

PySet_GET_SIZE (función C)

PySet_New (función C)

PySet_Pop (función C)

PySet_Size (función C)

PySet_Type (variable C)

PySetObject (tipo C)

PySignal_SetWakeupFd (función C)

PySlice_AdjustIndices (función C)

PySlice_Check (función C)

PySlice_GetIndices (función C)

PySlice_GetIndicesEx (función C)

PySlice_New (función C)

PySlice_Type (variable C)

PySlice_Unpack (función C)

PyState_AddModule (función C)

PyState_FindModule (función C)

PyState_RemoveModule (función C)

PyStatus (tipo C)

PyStatus.err_msg (miembro C)

PyStatus.exitcode (miembro C)

PyStatus.func (miembro C)

PyStatus_Error (función C)

PyStatus_Exception (función C)

PyStatus_Exit (función C)

PyStatus_IsError (función C)

PyStatus_IsExit (función C)

PyStatus_NoMemory (función C)

PyStatus_Ok (función C)

PyStructSequence_Desc (tipo C)

PyStructSequence_Field (tipo C)

PyStructSequence_GET_ITEM (función C)

PyStructSequence_GetItem (función C)

PyStructSequence_InitType (función C)

PyStructSequence_InitType2 (función C)

PyStructSequence_New (función C)

PyStructSequence_NewType (función C)

PyStructSequence_SET_ITEM (función C)

PyStructSequence_SetItem (función C)

PyStructSequence_UnnamedField (variable C)

PySys_AddAuditHook (función C)

PySys_AddWarnOption (función C)

PySys_AddWarnOptionUnicode (función C)

PySys_AddXOption (función C)

PySys_Audit (función C)

PySys_FormatStderr (función C)

PySys_FormatStdout (función C)

PySys_GetObject (función C)

PySys_GetXOptions (función C)

PySys_ResetWarnOptions (función C)

PySys_SetArgv (función C)

PySys_SetArgv()

PySys_SetArgvEx (función C)

PySys_SetArgvEx(), [1]

PySys_SetObject (función C)

PySys_SetPath (función C)

PySys_WriteStderr (función C)

PySys_WriteStdout (función C)

Python 3000

Python Editor

Python Enhancement Proposals

PEP 1, [1], [2]

PEP 100

PEP 11, [1], [2], [3], [4], [5]

PEP 201

PEP 205, [1]

PEP 207, [1]

PEP 208

PEP 217

PEP 218, [1], [2]

PEP 227, [1], [2]

PEP 229

PEP 230

PEP 232

PEP 234

PEP 235

PEP 236, [1], [2], [3]

PEP 237, [1], [2], [3], [4], [5]

PEP 238, [1], [2], [3], [4], [5], [6]

PEP 241, [1], [2]

PEP 243

PEP 247

PEP 249, [1], [2], [3]

PEP 252, [1], [2]

PEP 253, [1], [2], [3], [4]

PEP 255, [1], [2], [3], [4], [5]

PEP 261, [1]

PEP 263, [1], [2], [3], [4], [5], [6]

PEP 264

PEP 273, [1], [2]

PEP 274

PEP 275

PEP 277

PEP 278, [1]

PEP 279

PEP 282, [1], [2], [3], [4]

PEP 285, [1]

PEP 288

PEP 289, [1], [2]

PEP 292, [1]

PEP 293

PEP 3000

PEP 301, [1]

PEP 302, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21], [22], [23], [24], [25], [26], [27], [28], [29], [30], [31], [32], [33], [34], [35], [36]

PEP 305, [1]

PEP 307, [1], [2], [3]

PEP 308, [1], [2]

PEP 309

PEP 3100

PEP 3101, [1], [2], [3], [4]

PEP 3102

PEP 3104, [1]

PEP 3105, [1], [2]

PEP 3106

PEP 3107, [1], [2], [3]

PEP 3108, [1], [2]

PEP 3109, [1]

PEP 3110, [1], [2]

PEP 3111

PEP 3112, [1]

PEP 3113

PEP 3114

PEP 3115, [1], [2], [3]

PEP 3116, [1], [2]

PEP 3118, [1], [2], [3], [4], [5], [6], [7], [8], [9]

PEP 3119, [1], [2], [3], [4], [5]

PEP 3120, [1], [2]

PEP 3121, [1]

PEP 3123

PEP 3127

PEP 3129, [1]

PEP 3131, [1], [2]

PEP 3132, [1]

PEP 3134, [1], [2]

PEP 3135, [1]

PEP 3137

PEP 3138

PEP 314, [1]

PEP 3141, [1], [2]

PEP 3144

PEP 3147, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21], [22]

PEP 3148, [1]

PEP 3149, [1], [2]

PEP 3151, [1], [2], [3], [4], [5]

PEP 3154, [1], [2], [3]

PEP 3155, [1]

PEP 3156, [1], [2], [3], [4]

PEP 318, [1], [2], [3]

PEP 322, [1]

PEP 324, [1]

PEP 325

PEP 327

PEP 328, [1], [2], [3], [4], [5], [6], [7]

PEP 331

PEP 333, [1]

PEP 3333, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15]

PEP 338, [1], [2], [3]

PEP 339

PEP 341

PEP 342, [1], [2], [3], [4], [5], [6]

PEP 343, [1], [2], [3], [4], [5], [6], [7]

PEP 347

PEP 352, [1], [2]

PEP 353, [1], [2], [3]

PEP 356

PEP 357

PEP 361

PEP 362, [1], [2], [3]

PEP 366, [1], [2], [3], [4], [5], [6]

PEP 370, [1], [2], [3]

PEP 371

PEP 372, [1]

PEP 373

PEP 378, [1], [2]

PEP 380, [1]

PEP 383, [1], [2], [3], [4], [5]

PEP 384, [1]

PEP 385

PEP 387, [1]

PEP 389, [1]

PEP 391, [1]

PEP 392

PEP 393, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12]

PEP 395

PEP 397, [1], [2], [3]

PEP 398

PEP 4

PEP 405, [1]

PEP 409

PEP 411, [1], [2], [3], [4]

PEP 412, [1]

PEP 414, [1]

PEP 418

PEP 420, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14]

PEP 421, [1], [2]

PEP 424, [1]

PEP 427

PEP 428, [1], [2]

PEP 429

PEP 432, [1], [2], [3]

PEP 434

PEP 435, [1], [2]

PEP 436, [1], [2]

PEP 441, [1]

PEP 442, [1], [2], [3], [4], [5], [6], [7], [8]

PEP 443, [1], [2]

PEP 445, [1], [2], [3]

PEP 446, [1], [2], [3]

PEP 448, [1], [2], [3], [4], [5], [6], [7]

PEP 450, [1], [2]

PEP 451, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13]

PEP 453, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]

PEP 454, [1], [2]

PEP 456, [1]

PEP 461, [1], [2]

PEP 465, [1], [2], [3]

PEP 466, [1], [2], [3]

PEP 468, [1], [2]

PEP 471, [1], [2]

PEP 475, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21], [22], [23], [24], [25], [26], [27], [28]

PEP 476

PEP 477

PEP 478

PEP 479, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11]

PEP 483, [1], [2], [3]

PEP 484, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21], [22], [23], [24], [25], [26]

PEP 485, [1], [2], [3], [4]

PEP 486, [1], [2]

PEP 487, [1], [2], [3], [4], [5], [6]

PEP 488, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15]

PEP 489, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21], [22], [23], [24], [25], [26], [27], [28], [29], [30]

PEP 492, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21], [22]

PEP 493

PEP 494

PEP 495, [1], [2], [3]

PEP 498, [1], [2], [3], [4]

PEP 5, [1]

PEP 506, [1], [2]

PEP 511

PEP 514

PEP 515, [1], [2], [3], [4]

PEP 519, [1], [2], [3], [4], [5], [6], [7]

PEP 520

PEP 523, [1], [2], [3], [4], [5], [6], [7]

PEP 524, [1], [2], [3], [4], [5]

PEP 525, [1], [2], [3], [4], [5], [6], [7]

PEP 526, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16]

PEP 528, [1], [2]

PEP 529, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11]

PEP 530, [1], [2], [3]

PEP 538, [1], [2], [3], [4], [5], [6], [7], [8]

PEP 539, [1], [2], [3]

PEP 540, [1], [2], [3], [4]

PEP 544, [1], [2], [3]

PEP 545, [1]

PEP 552, [1], [2], [3], [4], [5], [6]

PEP 553, [1]

PEP 557, [1]

PEP 560, [1], [2], [3], [4], [5], [6]

PEP 562, [1], [2], [3]

PEP 563, [1], [2], [3], [4]

PEP 564, [1], [2], [3]

PEP 565, [1]

PEP 566, [1]

PEP 567, [1], [2], [3], [4], [5], [6], [7], [8], [9]

PEP 570, [1], [2], [3]

PEP 572, [1], [2], [3], [4], [5], [6], [7]

PEP 573, [1], [2], [3]

PEP 574, [1], [2]

PEP 578, [1], [2], [3]

PEP 584, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16]

PEP 585, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21], [22], [23], [24], [25], [26], [27], [28], [29], [30], [31], [32], [33], [34], [35], [36], [37], [38], [39], [40], [41], [42], [43], [44], [45], [46]

PEP 586, [1], [2]

PEP 587, [1], [2], [3], [4]

PEP 589, [1], [2]

PEP 590, [1], [2], [3], [4], [5], [6], [7], [8], [9]

PEP 591, [1], [2], [3]

PEP 593, [1], [2], [3], [4], [5]

PEP 594, [1], [2]

PEP 594#aifc

PEP 594#asynchat

PEP 594#asyncore

PEP 594#audioop

PEP 594#cgi

PEP 594#cgitb

PEP 594#chunk

PEP 594#crypt

PEP 594#imghdr

PEP 594#mailcap

PEP 594#msilib

PEP 594#nis

PEP 594#ossaudiodev

PEP 594#pipes

PEP 594#smtpd

PEP 594#sndhdr

PEP 594#spwd

PEP 594#sunau

PEP 594#telnetlib

PEP 594#uu-and-the-uu-encoding

PEP 594#xdrlib

PEP 596

PEP 6

PEP 602

PEP 612

PEP 614, [1], [2], [3], [4]

PEP 615, [1], [2], [3]

PEP 616, [1], [2]

PEP 617, [1], [2], [3], [4], [5], [6], [7]

PEP 623, [1]

PEP 628, [1], [2]

PEP 649

PEP 7, [1], [2], [3]

PEP 706, [1]

PEP 8, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]

Python Package Index (PyPI)

PYTHON*, [1], [2], [3], [4], [5]

python_branch() (en el módulo platform)

python_build() (en el módulo platform)

python_compiler() (en el módulo platform)

PYTHON_DOM

python_implementation() (en el módulo platform)

python_is_optimized() (en el módulo test.support)

python_revision() (en el módulo platform)

python_version() (en el módulo platform)

python_version_tuple() (en el módulo platform)

PYTHONASYNCIODEBUG, [1], [2]

PYTHONBREAKPOINT, [1], [2], [3]

PYTHONCASEOK, [1], [2], [3]

PYTHONCOERCECLOCALE, [1], [2]

PYTHONDEBUG, [1]

PYTHONDEVMODE, [1]

PYTHONDOCS

PYTHONDONTWRITEBYTECODE, [1], [2], [3], [4], [5]

PYTHONDUMPREFS, [1], [2]

PYTHONFAULTHANDLER, [1], [2]

PYTHONHASHSEED, [1], [2], [3], [4], [5], [6], [7], [8]

PYTHONHOME, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16]

PYTHONINSPECT, [1], [2]

PYTHONINTMAXSTRDIGITS, [1], [2], [3], [4]

PYTHONIOENCODING, [1], [2], [3], [4], [5], [6]

PYTHONLEGACYWINDOWSFSENCODING, [1], [2]

PYTHONLEGACYWINDOWSSTDIO, [1], [2], [3]

PYTHONMALLOC, [1], [2], [3], [4], [5], [6], [7], [8]

PYTHONMALLOCSTATS, [1]

PYTHONNOUSERSITE, [1], [2]

PYTHONOLDPARSER, [1]

PYTHONOPTIMIZE, [1]

PYTHONPATH, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21], [22], [23], [24], [25]

PYTHONPLATLIBDIR

PYTHONPROFILEIMPORTTIME, [1], [2]

PYTHONPYCACHEPREFIX, [1], [2], [3]

PYTHONSHOWALLOCCOUNT

PYTHONSHOWREFCOUNT

PYTHONSTARTUP, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]

PYTHONTRACEMALLOC, [1]

PYTHONTRACEMALLOC`comienzo, configura la variable del entorno a ``25`

PYTHONTZPATH

PYTHONUNBUFFERED, [1], [2], [3]

PYTHONUSERBASE, [1], [2]

PYTHONUSERSITE

PYTHONUTF8, [1], [2], [3], [4], [5]

PYTHONVERBOSE, [1]

PYTHONWARNINGS, [1], [2], [3], [4], [5], [6], [7], [8]

Pythónico

PyThread_create_key (función C)

PyThread_delete_key (función C)

PyThread_delete_key_value (función C)

PyThread_get_key_value (función C)

PyThread_ReInitTLS (función C)

PyThread_set_key_value (función C)

PyThread_tss_alloc (función C)

PyThread_tss_create (función C)

PyThread_tss_delete (función C)

PyThread_tss_free (función C)

PyThread_tss_get (función C)

PyThread_tss_is_created (función C)

PyThread_tss_set (función C)

PyThreadState, [1]

(tipo C)

PyThreadState_Clear (función C)

PyThreadState_Delete (función C)

PyThreadState_DeleteCurrent (función C)

PyThreadState_Get (función C)

PyThreadState_GetDict (función C)

PyThreadState_GetFrame (función C)

PyThreadState_GetID (función C)

PyThreadState_GetInterpreter (función C)

PyThreadState_New (función C)

PyThreadState_Next (función C)

PyThreadState_SetAsyncExc (función C)

PyThreadState_Swap (función C)

PyTime_Check (función C)

PyTime_CheckExact (función C)

PyTime_FromTime (función C)

PyTime_FromTimeAndFold (función C)

PyTimeZone_FromOffset (función C)

PyTimeZone_FromOffsetAndName (función C)

PyTrace_C_CALL (variable C)

PyTrace_C_EXCEPTION (variable C)

PyTrace_C_RETURN (variable C)

PyTrace_CALL (variable C)

PyTrace_EXCEPTION (variable C)

PyTrace_LINE (variable C)

PyTrace_OPCODE (variable C)

PyTrace_RETURN (variable C)

PyTraceMalloc_Track (función C)

PyTraceMalloc_Untrack (función C)

PyTuple_Check (función C)

PyTuple_CheckExact (función C)

PyTuple_GET_ITEM (función C)

PyTuple_GET_SIZE (función C)

PyTuple_GetItem (función C)

PyTuple_GetSlice (función C)

PyTuple_New (función C)

PyTuple_Pack (función C)

PyTuple_SET_ITEM (función C)

PyTuple_SetItem (función C)

PyTuple_SetItem()

PyTuple_Size (función C)

PyTuple_Type (variable C)

PyTupleObject (tipo C)

PyType_Check (función C)

PyType_CheckExact (función C)

PyType_ClearCache (función C)

PyType_FromModuleAndSpec (función C)

PyType_FromSpec (función C)

PyType_FromSpecWithBases (función C)

PyType_GenericAlloc (función C)

PyType_GenericNew (función C)

PyType_GetFlags (función C)

PyType_GetModule (función C)

PyType_GetModuleState (función C)

PyType_GetSlot (función C)

PyType_HasFeature (función C)

PyType_IS_GC (función C)

PyType_IsSubtype (función C)

PyType_Modified (función C)

PyType_Ready (función C)

PyType_Slot (tipo C)

PyType_Slot.PyType_Slot.pfunc (miembro C)

PyType_Slot.PyType_Slot.slot (miembro C)

PyType_Spec (tipo C)

PyType_Spec.PyType_Spec.basicsize (miembro C)

PyType_Spec.PyType_Spec.flags (miembro C)

PyType_Spec.PyType_Spec.itemsize (miembro C)

PyType_Spec.PyType_Spec.name (miembro C)

PyType_Spec.PyType_Spec.slots (miembro C)

PyType_Type (variable C)

PyTypeObject (tipo C)

PyTypeObject.tp_alloc (miembro C)

PyTypeObject.tp_as_async (miembro C)

PyTypeObject.tp_as_buffer (miembro C)

PyTypeObject.tp_as_mapping (miembro C)

PyTypeObject.tp_as_number (miembro C)

PyTypeObject.tp_as_sequence (miembro C)

PyTypeObject.tp_base (miembro C)

PyTypeObject.tp_bases (miembro C)

PyTypeObject.tp_basicsize (miembro C)

PyTypeObject.tp_cache (miembro C)

PyTypeObject.tp_call (miembro C)

PyTypeObject.tp_clear (miembro C)

PyTypeObject.tp_dealloc (miembro C)

PyTypeObject.tp_del (miembro C)

PyTypeObject.tp_descr_get (miembro C)

PyTypeObject.tp_descr_set (miembro C)

PyTypeObject.tp_dict (miembro C)

PyTypeObject.tp_dictoffset (miembro C)

PyTypeObject.tp_doc (miembro C)

PyTypeObject.tp_finalize (miembro C)

PyTypeObject.tp_flags (miembro C)

PyTypeObject.tp_free (miembro C)

PyTypeObject.tp_getattr (miembro C)

PyTypeObject.tp_getattro (miembro C)

PyTypeObject.tp_getset (miembro C)

PyTypeObject.tp_hash (miembro C)

PyTypeObject.tp_init (miembro C)

PyTypeObject.tp_is_gc (miembro C)

PyTypeObject.tp_itemsize (miembro C)

PyTypeObject.tp_iter (miembro C)

PyTypeObject.tp_iternext (miembro C)

PyTypeObject.tp_members (miembro C)

PyTypeObject.tp_methods (miembro C)

PyTypeObject.tp_mro (miembro C)

PyTypeObject.tp_name (miembro C)

PyTypeObject.tp_new (miembro C)

PyTypeObject.tp_repr (miembro C)

PyTypeObject.tp_richcompare (miembro C)

PyTypeObject.tp_setattr (miembro C)

PyTypeObject.tp_setattro (miembro C)

PyTypeObject.tp_str (miembro C)

PyTypeObject.tp_subclasses (miembro C)

PyTypeObject.tp_traverse (miembro C)

PyTypeObject.tp_vectorcall (miembro C)

PyTypeObject.tp_vectorcall_offset (miembro C)

PyTypeObject.tp_version_tag (miembro C)

PyTypeObject.tp_weaklist (miembro C)

PyTypeObject.tp_weaklistoffset (miembro C)

PyTZInfo_Check (función C)

PyTZInfo_CheckExact (función C)

PyUnicode_1BYTE_DATA (función C)

PyUnicode_1BYTE_KIND (macro C)

PyUnicode_2BYTE_DATA (función C)

PyUnicode_2BYTE_KIND (macro C)

PyUnicode_4BYTE_DATA (función C)

PyUnicode_4BYTE_KIND (macro C)

PyUnicode_AS_DATA (función C)

PyUnicode_AS_UNICODE (función C)

PyUnicode_AsASCIIString (función C)

PyUnicode_AsCharmapString (función C)

PyUnicode_AsEncodedString (función C)

PyUnicode_AsLatin1String (función C)

PyUnicode_AsMBCSString (función C)

PyUnicode_AsRawUnicodeEscapeString (función C)

PyUnicode_AsUCS4 (función C)

PyUnicode_AsUCS4Copy (función C)

PyUnicode_AsUnicode (función C)

PyUnicode_AsUnicodeAndSize (función C)

PyUnicode_AsUnicodeCopy (función C)

PyUnicode_AsUnicodeEscapeString (función C)

PyUnicode_AsUTF16String (función C)

PyUnicode_AsUTF32String (función C)

PyUnicode_AsUTF8 (función C)

PyUnicode_AsUTF8AndSize (función C)

PyUnicode_AsUTF8String (función C)

PyUnicode_AsWideChar (función C)

PyUnicode_AsWideCharString (función C)

PyUnicode_Check (función C)

PyUnicode_CheckExact (función C)

PyUnicode_Compare (función C)

PyUnicode_CompareWithASCIIString (función C)

PyUnicode_Concat (función C)

PyUnicode_Contains (función C)

PyUnicode_CopyCharacters (función C)

PyUnicode_Count (función C)

PyUnicode_DATA (función C)

PyUnicode_Decode (función C)

PyUnicode_DecodeASCII (función C)

PyUnicode_DecodeCharmap (función C)

PyUnicode_DecodeFSDefault (función C)

PyUnicode_DecodeFSDefaultAndSize (función C)

PyUnicode_DecodeLatin1 (función C)

PyUnicode_DecodeLocale (función C)

PyUnicode_DecodeLocaleAndSize (función C)

PyUnicode_DecodeMBCS (función C)

PyUnicode_DecodeMBCSStateful (función C)

PyUnicode_DecodeRawUnicodeEscape (función C)

PyUnicode_DecodeUnicodeEscape (función C)

PyUnicode_DecodeUTF16 (función C)

PyUnicode_DecodeUTF16Stateful (función C)

PyUnicode_DecodeUTF32 (función C)

PyUnicode_DecodeUTF32Stateful (función C)

PyUnicode_DecodeUTF7 (función C)

PyUnicode_DecodeUTF7Stateful (función C)

PyUnicode_DecodeUTF8 (función C)

PyUnicode_DecodeUTF8Stateful (función C)

PyUnicode_Encode (función C)

PyUnicode_EncodeASCII (función C)

PyUnicode_EncodeCharmap (función C)

PyUnicode_EncodeCodePage (función C)

PyUnicode_EncodeFSDefault (función C)

PyUnicode_EncodeLatin1 (función C)

PyUnicode_EncodeLocale (función C)

PyUnicode_EncodeMBCS (función C)

PyUnicode_EncodeRawUnicodeEscape (función C)

PyUnicode_EncodeUnicodeEscape (función C)

PyUnicode_EncodeUTF16 (función C)

PyUnicode_EncodeUTF32 (función C)

PyUnicode_EncodeUTF7 (función C)

PyUnicode_EncodeUTF8 (función C)

PyUnicode_Fill (función C)

PyUnicode_Find (función C)

PyUnicode_FindChar (función C)

PyUnicode_Format (función C)

PyUnicode_FromEncodedObject (función C)

PyUnicode_FromFormat (función C)

PyUnicode_FromFormatV (función C)

PyUnicode_FromKindAndData (función C)

PyUnicode_FromObject (función C)

PyUnicode_FromString (función C)

PyUnicode_FromString()

PyUnicode_FromStringAndSize (función C)

PyUnicode_FromUnicode (función C)

PyUnicode_FromWideChar (función C)

PyUnicode_FSConverter (función C)

PyUnicode_FSDecoder (función C)

PyUnicode_GET_DATA_SIZE (función C)

PyUnicode_GET_LENGTH (función C)

PyUnicode_GET_SIZE (función C)

PyUnicode_GetLength (función C)

PyUnicode_GetSize (función C)

PyUnicode_InternFromString (función C)

PyUnicode_InternInPlace (función C)

PyUnicode_IsIdentifier (función C)

PyUnicode_Join (función C)

PyUnicode_KIND (función C)

PyUnicode_MAX_CHAR_VALUE (macro C)

PyUnicode_New (función C)

PyUnicode_READ (función C)

PyUnicode_READ_CHAR (función C)

PyUnicode_ReadChar (función C)

PyUnicode_READY (función C)

PyUnicode_Replace (función C)

PyUnicode_RichCompare (función C)

PyUnicode_Split (función C)

PyUnicode_Splitlines (función C)

PyUnicode_Substring (función C)

PyUnicode_Tailmatch (función C)

PyUnicode_TransformDecimalToASCII (función C)

PyUnicode_Translate (función C)

PyUnicode_TranslateCharmap (función C)

PyUnicode_Type (variable C)

PyUnicode_WCHAR_KIND (macro C)

PyUnicode_WRITE (función C)

PyUnicode_WriteChar (función C)

PyUnicodeDecodeError_Create (función C)

PyUnicodeDecodeError_GetEncoding (función C)

PyUnicodeDecodeError_GetEnd (función C)

PyUnicodeDecodeError_GetObject (función C)

PyUnicodeDecodeError_GetReason (función C)

PyUnicodeDecodeError_GetStart (función C)

PyUnicodeDecodeError_SetEnd (función C)

PyUnicodeDecodeError_SetReason (función C)

PyUnicodeDecodeError_SetStart (función C)

PyUnicodeEncodeError_Create (función C)

PyUnicodeEncodeError_GetEncoding (función C)

PyUnicodeEncodeError_GetEnd (función C)

PyUnicodeEncodeError_GetObject (función C)

PyUnicodeEncodeError_GetReason (función C)

PyUnicodeEncodeError_GetStart (función C)

PyUnicodeEncodeError_SetEnd (función C)

PyUnicodeEncodeError_SetReason (función C)

PyUnicodeEncodeError_SetStart (función C)

PyUnicodeObject (tipo C)

PyUnicodeTranslateError_Create (función C)

PyUnicodeTranslateError_GetEnd (función C)

PyUnicodeTranslateError_GetObject (función C)

PyUnicodeTranslateError_GetReason (función C)

PyUnicodeTranslateError_GetStart (función C)

PyUnicodeTranslateError_SetEnd (función C)

PyUnicodeTranslateError_SetReason (función C)

PyUnicodeTranslateError_SetStart (función C)

PyVarObject (tipo C)

PyVarObject.ob_size (miembro C)

PyVarObject_HEAD_INIT (macro C)

PyVectorcall_Call (función C)

PyVectorcall_Function (función C)

PyVectorcall_NARGS (función C)

PyWeakref_Check (función C)

PyWeakref_CheckProxy (función C)

PyWeakref_CheckRef (función C)

PyWeakref_GET_OBJECT (función C)

PyWeakref_GetObject (función C)

PyWeakref_NewProxy (función C)

PyWeakref_NewRef (función C)

PyWideStringList (tipo C)

PyWideStringList.items (miembro C)

PyWideStringList.length (miembro C)

PyWideStringList_Append (función C)

PyWideStringList_Insert (función C)

PyWrapper_New (función C)

PyZipFile (clase en zipfile)

Índice – Q

qiflush() (en el módulo curses)

QName (clase en xml.etree.ElementTree)

qsize() (método de asyncio.Queue)

(método de multiprocessing.Queue)

(método de queue.Queue)

(método de queue.SimpleQueue)

quantiles() (en el módulo statistics)

(método de statistics.NormalDist)

quantize() (método de decimal.Context)

(método de decimal.Decimal)

QueryInfoKey() (en el módulo winreg)

QueryReflectionKey() (en el módulo winreg)

QueryValue() (en el módulo winreg)

QueryValueEx() (en el módulo winreg)

queue (atributo de sched.scheduler)

Queue (clase en asyncio)

(clase en multiprocessing)

(clase en queue)

queue (módulo)

Queue() (método de multiprocessing.managers.SyncManager)

QueueEmpty

QueueFull

QueueHandler (clase en logging.handlers)

QueueListener (clase en logging.handlers)

quick_ratio() (método de difflib.SequenceMatcher)

quit (pdb command)

(variable incorporada)

quit() (método de ftplib.FTP)

(método de nntplib.NNTP)

(método de poplib.POP3)

(método de smtplib.SMTP)

(método de tkinter.filedialog.FileDialog)

quopri (módulo)

quote() (en el módulo email.utils)

(en el módulo shlex)

(en el módulo urllib.parse)

QUOTE_ALL (en el módulo csv)

quote_from_bytes() (en el módulo urllib.parse)

QUOTE_MINIMAL (en el módulo csv)

QUOTE_NONE (en el módulo csv)

QUOTE_NONNUMERIC (en el módulo csv)

quote_plus() (en el módulo urllib.parse)

quoteattr() (en el módulo xml.sax.saxutils)

quotechar (atributo de csv.Dialect)

quoted-printable

encoding

quotes (atributo de shlex.shlex)

quoting (atributo de csv.Dialect)

Índice – R

r"

raw string literal

r'

raw string literal

R_OK (en el módulo os)

radians() (en el módulo math)

(en el módulo turtle)

RadioButtonGroup (clase en msilib)

radiogroup() (método de msilib.Dialog)

radix() (método de decimal.Context)

(método de decimal.Decimal)

RADIXCHAR (en el módulo locale)

raise

sentencia, [1]

raise (2to3 fixer)

Raise (clase en ast)

raise an exception

raise_on_defect (atributo de email.policy.Policy)

raise_signal() (en el módulo signal)

RAISE_VARARGS (opcode)

raising

exception

RAND_add() (en el módulo ssl)

RAND_bytes() (en el módulo ssl)

RAND_egd() (en el módulo ssl)

RAND_pseudo_bytes() (en el módulo ssl)

RAND_status() (en el módulo ssl)

randbelow() (en el módulo secrets)

randbits() (en el módulo secrets)

randbytes() (en el módulo random)

randint() (en el módulo random)

Random (clase en random)

random (módulo)

random() (en el módulo random)

randrange() (en el módulo random)

range

función incorporada

objeto

range (clase incorporada)

RARROW (en el módulo token)

ratecv() (en el módulo audioop)

ratio() (método de difflib.SequenceMatcher)

Rational (clase en numbers)

raw (atributo de io.BufferedIOBase)

raw string

raw() (en el módulo curses)

(método de pickle.PickleBuffer)

raw_data_manager (en el módulo email.contentmanager)

raw_decode() (método de json.JSONDecoder)

raw_input (2to3 fixer)

raw_input() (método de code.InteractiveConsole)

RawArray() (en el módulo multiprocessing.sharedctypes)

RawConfigParser (clase en configparser)

RawDescriptionHelpFormatter (clase en argparse)

RawIOBase (clase en io)

RawPen (clase en turtle)

RawTextHelpFormatter (clase en argparse)

RawTurtle (clase en turtle)

RawValue() (en el módulo multiprocessing.sharedctypes)

RBRACE (en el módulo token)

rcpttos (atributo de smtpd.SMTPChannel)

re

módulo, [1]

re (atributo de re.Match)

(módulo)

read() (en el módulo os)

(método de asyncio.StreamReader)

(método de chunk.Chunk)

(método de codecs.StreamReader)

(método de configparser.ConfigParser)

(método de http.client.HTTPResponse)

(método de imaplib.IMAP4)

(método de io.BufferedIOBase)

(método de io.BufferedReader)

(método de io.RawIOBase)

(método de io.TextIOBase)

(método de mimetypes.MimeTypes)

(método de mmap.mmap)

(método de ossaudiodev.oss_audio_device)

(método de ssl.MemoryBIO)

(método de ssl.SSLSocket)

(método de urllib.robotparser.RobotFileParser)

(método de zipfile.ZipFile)

read1() (método de io.BufferedIOBase)

(método de io.BufferedReader)

(método de io.BytesIO)

read_all() (método de telnetlib.Telnet)

read_binary() (en el módulo importlib.resources)

read_byte() (método de mmap.mmap)

read_bytes() (método de importlib.abc.Traversable)

(método de pathlib.Path)

(método de zipfile.Path)

read_dict() (método de configparser.ConfigParser)

read_eager() (método de telnetlib.Telnet)

read_environ() (en el módulo wsgiref.handlers)

read_events() (método de xml.etree.ElementTree.XMLPullParser)

read_file() (método de configparser.ConfigParser)

read_history_file() (en el módulo readline)

read_init_file() (en el módulo readline)

read_lazy() (método de telnetlib.Telnet)

read_mime_types() (en el módulo mimetypes)

READ_RESTRICTED

read_sb_data() (método de telnetlib.Telnet)

read_some() (método de telnetlib.Telnet)

read_string() (método de configparser.ConfigParser)

read_text() (en el módulo importlib.resources)

(método de importlib.abc.Traversable)

(método de pathlib.Path)

(método de zipfile.Path)

read_token() (método de shlex.shlex)

read_until() (método de telnetlib.Telnet)

read_very_eager() (método de telnetlib.Telnet)

read_very_lazy() (método de telnetlib.Telnet)

read_windows_registry() (método de mimetypes.MimeTypes)

READABLE (en el módulo tkinter)

readable() (método de asyncore.dispatcher)

(método de io.IOBase)

readall() (método de io.RawIOBase)

reader() (en el módulo csv)

ReadError

readexactly() (método de asyncio.StreamReader)

readfp() (método de configparser.ConfigParser)

(método de mimetypes.MimeTypes)

readframes() (método de aifc.aifc)

(método de sunau.AU_read)

(método de wave.Wave_read)

readinto() (método de http.client.HTTPResponse)

(método de io.BufferedIOBase)

(método de io.RawIOBase)

readinto1() (método de io.BufferedIOBase)

(método de io.BytesIO)

readline (módulo)

readline() (método de asyncio.StreamReader)

(método de codecs.StreamReader)

(método de distutils.text_file.TextFile)

(método de imaplib.IMAP4)

(método de io.IOBase)

(método de io.TextIOBase)

(método de mmap.mmap)

readlines() (método de codecs.StreamReader)

(método de distutils.text_file.TextFile)

(método de io.IOBase)

readlink() (en el módulo os)

(método de pathlib.Path)

readmodule() (en el módulo pyclbr)

readmodule_ex() (en el módulo pyclbr)

READONLY

readonly (atributo de memoryview)

ReadTransport (clase en asyncio)

readuntil() (método de asyncio.StreamReader)

readv() (en el módulo os)

ready() (método de multiprocessing.pool.AsyncResult)

real (atributo de numbers.Complex)

Real (clase en numbers)

Real Media File Format

real_max_memuse (en el módulo test.support)

real_quick_ratio() (método de difflib.SequenceMatcher)

realloc()

realpath() (en el módulo os.path)

REALTIME_PRIORITY_CLASS (en el módulo subprocess)

reap_children() (en el módulo test.support)

reap_threads() (en el módulo test.support)

reason (atributo de http.client.HTTPResponse)

(atributo de ssl.SSLError)

(atributo de UnicodeError)

(atributo de urllib.error.HTTPError)

(atributo de urllib.error.URLError)

reattach() (método de tkinter.ttk.Treeview)

rebanada

rebinding

name

reccontrols() (método de ossaudiodev.oss_mixer_device)

received_data (atributo de smtpd.SMTPChannel)

received_lines (atributo de smtpd.SMTPChannel)

recent() (método de imaplib.IMAP4)

recolección de basura

reconfigure() (método de io.TextIOWrapper)

record_original_stdout() (en el módulo test.support)

records (atributo de unittest.TestCase)

rect() (en el módulo cmath)

rectangle() (en el módulo curses.textpad)

RecursionError

recursive_repr() (en el módulo reprlib)

recv() (método de asyncore.dispatcher)

(método de multiprocessing.connection.Connection)

(método de socket.socket)

recv_bytes() (método de multiprocessing.connection.Connection)

recv_bytes_into() (método de multiprocessing.connection.Connection)

recv_fds() (en el módulo socket)

recv_into() (método de socket.socket)

recvfrom() (método de socket.socket)

recvfrom_into() (método de socket.socket)

recvmsg() (método de socket.socket)

recvmsg_into() (método de socket.socket)

redirect_request() (método de urllib.request.HTTPRedirectHandler)

redirect_stderr() (en el módulo contextlib)

redirect_stdout() (en el módulo contextlib)

redisplay() (en el módulo readline)

redrawln() (método de curses.window)

redrawwin() (método de curses.window)

reduce (2to3 fixer)

reduce() (en el módulo functools)

reducer_override() (método de pickle.Pickler)

ref (clase en weakref)

refcount_test() (en el módulo test.support)

reference

attribute

reference counting

ReferenceError

ReferenceType (en el módulo weakref)

refold_source (atributo de email.policy.EmailPolicy)

refresh() (método de curses.window)

REG_BINARY (en el módulo winreg)

REG_DWORD (en el módulo winreg)

REG_DWORD_BIG_ENDIAN (en el módulo winreg)

REG_DWORD_LITTLE_ENDIAN (en el módulo winreg)

REG_EXPAND_SZ (en el módulo winreg)

REG_FULL_RESOURCE_DESCRIPTOR (en el módulo winreg)

REG_LINK (en el módulo winreg)

REG_MULTI_SZ (en el módulo winreg)

REG_NONE (en el módulo winreg)

REG_QWORD (en el módulo winreg)

REG_QWORD_LITTLE_ENDIAN (en el módulo winreg)

REG_RESOURCE_LIST (en el módulo winreg)

REG_RESOURCE_REQUIREMENTS_LIST (en el módulo winreg)

REG_SZ (en el módulo winreg)

register() (en el módulo atexit)

(en el módulo codecs)

(en el módulo faulthandler)

(en el módulo webbrowser)

(método de abc.ABCMeta)

(método de multiprocessing.managers.BaseManager)

(método de select.devpoll)

(método de select.epoll)

(método de select.poll)

(método de selectors.BaseSelector)

register_adapter() (en el módulo sqlite3)

register_archive_format() (en el módulo shutil)

register_at_fork() (en el módulo os)

register_converter() (en el módulo sqlite3)

register_defect() (método de email.policy.Policy)

register_dialect() (en el módulo csv)

register_error() (en el módulo codecs)

register_function() (método de xmlrpc.server.CGIXMLRPCRequestHandler)

(método de xmlrpc.server.SimpleXMLRPCServer)

register_instance() (método de xmlrpc.server.CGIXMLRPCRequestHandler)

(método de xmlrpc.server.SimpleXMLRPCServer)

register_introspection_functions() (método de xmlrpc.server.CGIXMLRPCRequestHandler)

(método de xmlrpc.server.SimpleXMLRPCServer)

register_multicall_functions() (método de xmlrpc.server.CGIXMLRPCRequestHandler)

(método de xmlrpc.server.SimpleXMLRPCServer)

register_namespace() (en el módulo xml.etree.ElementTree)

register_optionflag() (en el módulo doctest)

register_shape() (en el módulo turtle)

register_unpack_format() (en el módulo shutil)

registerDOMImplementation() (en el módulo xml.dom)

registerResult() (en el módulo unittest)

regular

package

relative

import

URL

relative_to() (método de pathlib.PurePath)

release() (en el módulo platform)

(método de _thread.lock)

(método de asyncio.Condition)

(método de asyncio.Lock)

(método de asyncio.Semaphore)

(método de logging.Handler)

(método de memoryview)

(método de multiprocessing.Lock)

(método de multiprocessing.RLock)

(método de pickle.PickleBuffer)

(método de threading.Condition)

(método de threading.Lock)

(método de threading.RLock)

(método de threading.Semaphore)

release_lock() (en el módulo imp)

releasebufferproc (tipo C)

reload (2to3 fixer)

reload() (en el módulo imp)

(en el módulo importlib)

relpath() (en el módulo os.path)

remainder() (en el módulo math)

(método de decimal.Context)

remainder_near() (método de decimal.Context)

(método de decimal.Decimal)

RemoteDisconnected

remove() (en el módulo os)

(método de array.array)

(método de collections.deque)

(método de frozenset)

(método de mailbox.Mailbox)

(método de mailbox.MH)

(método de xml.etree.ElementTree.Element)

(sequence method)

remove_child_handler() (método de asyncio.AbstractChildWatcher)

remove_done_callback() (método de asyncio.Future)

(método de asyncio.Task)

remove_flag() (método de mailbox.MaildirMessage)

(método de mailbox.mboxMessage)

(método de mailbox.MMDFMessage)

remove_folder() (método de mailbox.Maildir)

(método de mailbox.MH)

remove_header() (método de urllib.request.Request)

remove_history_item() (en el módulo readline)

remove_label() (método de mailbox.BabylMessage)

remove_option() (método de configparser.ConfigParser)

(método de optparse.OptionParser)

remove_pyc() (método de msilib.Directory)

remove_reader() (método de asyncio.loop)

remove_section() (método de configparser.ConfigParser)

remove_sequence() (método de mailbox.MHMessage)

remove_signal_handler() (método de asyncio.loop)

remove_tree() (en el módulo distutils.dir_util)

remove_writer() (método de asyncio.loop)

removeAttribute() (método de xml.dom.Element)

removeAttributeNode() (método de xml.dom.Element)

removeAttributeNS() (método de xml.dom.Element)

removeChild() (método de xml.dom.Node)

removedirs() (en el módulo os)

removeFilter() (método de logging.Handler)

(método de logging.Logger)

removeHandler() (en el módulo unittest)

(método de logging.Logger)

removeprefix() (método de bytearray)

(método de bytes)

(método de str)

removeResult() (en el módulo unittest)

removesuffix() (método de bytearray)

(método de bytes)

(método de str)

removexattr() (en el módulo os)

rename() (en el módulo os)

(método de ftplib.FTP)

(método de imaplib.IMAP4)

(método de pathlib.Path)

renames (2to3 fixer)

renames() (en el módulo os)

reopenIfNeeded() (método de logging.handlers.WatchedFileHandler)

reorganize() (método de dbm.gnu.gdbm)

repeat() (en el módulo itertools)

(en el módulo timeit)

(método de timeit.Timer)

repetition

operation

replace

error handler's name

replace() (en el módulo dataclasses)

(en el módulo os)

(método de bytearray)

(método de bytes)

(método de curses.panel.Panel)

(método de datetime.date)

(método de datetime.datetime)

(método de datetime.time)

(método de inspect.Parameter)

(método de inspect.Signature)

(método de pathlib.Path)

(método de str)

(método de types.CodeType)

replace_errors() (en el módulo codecs)

replace_header() (método de email.message.EmailMessage)

(método de email.message.Message)

replace_history_item() (en el módulo readline)

replace_whitespace (atributo de textwrap.TextWrapper)

replaceChild() (método de xml.dom.Node)

ReplacePackage() (en el módulo modulefinder)

report() (método de filecmp.dircmp)

(método de modulefinder.ModuleFinder)

REPORT_CDIFF (en el módulo doctest)

report_failure() (método de doctest.DocTestRunner)

report_full_closure() (método de filecmp.dircmp)

REPORT_NDIFF (en el módulo doctest)

REPORT_ONLY_FIRST_FAILURE (en el módulo doctest)

report_partial_closure() (método de filecmp.dircmp)

report_start() (método de doctest.DocTestRunner)

report_success() (método de doctest.DocTestRunner)

REPORT_UDIFF (en el módulo doctest)

report_unexpected_exception() (método de doctest.DocTestRunner)

REPORTING_FLAGS (en el módulo doctest)

repr

función incorporada, [1], [2], [3]

repr (2to3 fixer)

Repr (clase en reprlib)

repr() (built-in function)

__repr__() (object method)

repr() (en el módulo reprlib)

(función incorporada)

(método de reprlib.Repr)

repr1() (método de reprlib.Repr)

representation

integer

reprfunc (tipo C)

reprlib (módulo)

Request (clase en urllib.request)

request() (método de http.client.HTTPConnection)

request_queue_size (atributo de socketserver.BaseServer)

request_rate() (método de urllib.robotparser.RobotFileParser)

request_uri() (en el módulo wsgiref.util)

request_version (atributo de http.server.BaseHTTPRequestHandler)

RequestHandlerClass (atributo de socketserver.BaseServer)

requestline (atributo de http.server.BaseHTTPRequestHandler)

requires() (en el módulo test.support)

requires_bz2() (en el módulo test.support)

requires_docstrings() (en el módulo test.support)

requires_freebsd_version() (en el módulo test.support)

requires_gzip() (en el módulo test.support)

requires_IEEE_754() (en el módulo test.support)

requires_linux_version() (en el módulo test.support)

requires_lzma() (en el módulo test.support)

requires_mac_version() (en el módulo test.support)

requires_resource() (en el módulo test.support)

requires_zlib() (en el módulo test.support)

RERAISE (opcode)

reserved (atributo de zipfile.ZipInfo)

reserved word

RESERVED_FUTURE (en el módulo uuid)

RESERVED_MICROSOFT (en el módulo uuid)

RESERVED_NCS (en el módulo uuid)

reset() (en el módulo turtle)

(método de bdb.Bdb)

(método de codecs.IncrementalDecoder)

(método de codecs.IncrementalEncoder)

(método de codecs.StreamReader)

(método de codecs.StreamWriter)

(método de contextvars.ContextVar)

(método de html.parser.HTMLParser)

(método de ossaudiodev.oss_audio_device)

(método de pipes.Template)

(método de threading.Barrier)

(método de xdrlib.Packer)

(método de xdrlib.Unpacker)

(método de xml.dom.pulldom.DOMEventStream)

(método de xml.sax.xmlreader.IncrementalParser)

reset_mock() (método de unittest.mock.AsyncMock)

(método de unittest.mock.Mock)

reset_peak() (en el módulo tracemalloc)

reset_prog_mode() (en el módulo curses)

reset_shell_mode() (en el módulo curses)

reset_tzpath() (en el módulo zoneinfo)

resetbuffer() (método de code.InteractiveConsole)

resetlocale() (en el módulo locale)

resetscreen() (en el módulo turtle)

resetty() (en el módulo curses)

resetwarnings() (en el módulo warnings)

resize() (en el módulo ctypes)

(método de curses.window)

(método de mmap.mmap)

resize_term() (en el módulo curses)

resizemode() (en el módulo turtle)

resizeterm() (en el módulo curses)

resolution (atributo de datetime.date)

(atributo de datetime.datetime)

(atributo de datetime.time)

(atributo de datetime.timedelta)

resolve() (método de pathlib.Path)

resolve_bases() (en el módulo types)

resolve_name() (en el módulo importlib.util)

(en el módulo pkgutil)

resolveEntity() (método de xml.sax.handler.EntityResolver)

Resource (en el módulo importlib.resources)

resource (módulo)

resource_path() (método de importlib.abc.ResourceReader)

ResourceDenied

ResourceLoader (clase en importlib.abc)

ResourceReader (clase en importlib.abc)

ResourceWarning

response (atributo de nntplib.NNTPError)

response() (método de imaplib.IMAP4)

ResponseNotReady

responses (atributo de http.server.BaseHTTPRequestHandler)

(en el módulo http.client)

restart (pdb command)

restore() (en el módulo difflib)

RESTRICTED

restricted

execution

restype (atributo de ctypes._FuncPtr)

result() (método de asyncio.Future)

(método de asyncio.Task)

(método de concurrent.futures.Future)

results() (método de trace.Trace)

resume_reading() (método de asyncio.ReadTransport)

resume_writing() (método de asyncio.BaseProtocol)

retr() (método de poplib.POP3)

retrbinary() (método de ftplib.FTP)

retrieve() (método de urllib.request.URLopener)

retrlines() (método de ftplib.FTP)

retrollamada

return

sentencia, [1], [2]

Return (clase en ast)

return (pdb command)

return_annotation (atributo de inspect.Signature)

return_ok() (método de http.cookiejar.CookiePolicy)

return_value (atributo de unittest.mock.Mock)

RETURN_VALUE (opcode)

returncode (atributo de asyncio.subprocess.Process)

(atributo de subprocess.CalledProcessError)

(atributo de subprocess.CompletedProcess)

(atributo de subprocess.Popen)

retval (pdb command)

reverse() (en el módulo audioop)

(método de array.array)

(método de collections.deque)

(sequence method)

reverse_order() (método de pstats.Stats)

reverse_pointer (atributo de ipaddress.IPv4Address)

(atributo de ipaddress.IPv6Address)

reversed() (función incorporada)

Reversible (clase en collections.abc)

(clase en typing)

revert() (método de http.cookiejar.FileCookieJar)

rewind() (método de aifc.aifc)

(método de sunau.AU_read)

(método de wave.Wave_read)

RFC

RFC 1014, [1]

RFC 1123

RFC 1321

RFC 1422, [1]

RFC 1521, [1], [2]

RFC 1522, [1]

RFC 1524, [1]

RFC 1730

RFC 1738

RFC 1750

RFC 1766, [1]

RFC 1808, [1], [2]

RFC 1832, [1]

RFC 1869, [1]

RFC 1870, [1], [2]

RFC 1939, [1]

RFC 2033

RFC 2045, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13]

RFC 2045#section-6.8

RFC 2046, [1], [2]

RFC 2047, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12]

RFC 2060

RFC 2068

RFC 2104, [1]

RFC 2109, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14]

RFC 2183, [1], [2]

RFC 2231, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14]

RFC 2295

RFC 2324

RFC 2342, [1]

RFC 2368

RFC 2373, [1], [2]

RFC 2396, [1], [2], [3], [4]

RFC 2397

RFC 2449

RFC 2487

RFC 2518

RFC 2595, [1]

RFC 2616, [1], [2], [3], [4], [5], [6], [7], [8], [9]

RFC 2640, [1], [2], [3], [4]

RFC 2732, [1], [2]

RFC 2774

RFC 2818, [1]

RFC 2821

RFC 2822, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18]

RFC 2964

RFC 2965, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18]

RFC 2980, [1]

RFC 3056

RFC 3171

RFC 3207

RFC 3229

RFC 3280

RFC 3330

RFC 3339

RFC 3454, [1]

RFC 3490, [1], [2], [3]

RFC 3490#section-3.1

RFC 3492, [1]

RFC 3493

RFC 3501

RFC 3542, [1]

RFC 3548, [1], [2], [3], [4], [5]

RFC 3659

RFC 3879

RFC 3927

RFC 3977, [1], [2], [3], [4]

RFC 3986, [1], [2], [3], [4], [5], [6], [7], [8], [9]

RFC 4007, [1]

RFC 4086

RFC 4122, [1], [2], [3], [4], [5], [6], [7], [8]

RFC 4180

RFC 4193

RFC 4217

RFC 4291

RFC 4380

RFC 4627, [1]

RFC 4642

RFC 4918, [1], [2], [3], [4]

RFC 4954

RFC 5161, [1]

RFC 5246, [1]

RFC 5280, [1], [2], [3], [4]

RFC 5321, [1], [2], [3], [4]

RFC 5322, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21], [22], [23]

RFC 5424, [1], [2], [3]

RFC 5424#section-6

RFC 5735

RFC 5842, [1]

RFC 5891

RFC 5895

RFC 5929

RFC 6066, [1], [2]

RFC 6125, [1]

RFC 6152, [1]

RFC 6531, [1], [2], [3], [4], [5], [6], [7], [8]

RFC 6532, [1], [2], [3], [4]

RFC 6585, [1], [2], [3]

RFC 6855, [1], [2], [3]

RFC 6856, [1]

RFC 7159, [1], [2]

RFC 7230, [1]

RFC 7231, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21], [22], [23], [24], [25], [26], [27], [28], [29], [30], [31], [32], [33], [34]

RFC 7232, [1]

RFC 7233, [1]

RFC 7235, [1]

RFC 7238

RFC 7301, [1], [2]

RFC 7525

RFC 7540

RFC 7693

RFC 7725

RFC 7914

RFC 821, [1]

RFC 822, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11]

RFC 8297

RFC 8305, [1]

RFC 8470

RFC 854, [1]

RFC 959

RFC 977

rfc2109 (atributo de http.cookiejar.Cookie)

rfc2109_as_netscape (atributo de http.cookiejar.DefaultCookiePolicy)

rfc2965 (atributo de http.cookiejar.CookiePolicy)

rfc822_escape() (en el módulo distutils.util)

RFC_4122 (en el módulo uuid)

rfile (atributo de http.server.BaseHTTPRequestHandler)

rfind() (método de bytearray)

(método de bytes)

(método de mmap.mmap)

(método de str)

rgb_to_hls() (en el módulo colorsys)

rgb_to_hsv() (en el módulo colorsys)

rgb_to_yiq() (en el módulo colorsys)

rglob() (método de pathlib.Path)

richcmpfunc (tipo C)

right (atributo de filecmp.dircmp)

right() (en el módulo turtle)

right_list (atributo de filecmp.dircmp)

right_only (atributo de filecmp.dircmp)

RIGHTSHIFT (en el módulo token)

RIGHTSHIFTEQUAL (en el módulo token)

rindex() (método de bytearray)

(método de bytes)

(método de str)

rjust() (método de bytearray)

(método de bytes)

(método de str)

rlcompleter (módulo)

rlecode_hqx() (en el módulo binascii)

rledecode_hqx() (en el módulo binascii)

RLIM_INFINITY (en el módulo resource)

RLIMIT_AS (en el módulo resource)

RLIMIT_CORE (en el módulo resource)

RLIMIT_CPU (en el módulo resource)

RLIMIT_DATA (en el módulo resource)

RLIMIT_FSIZE (en el módulo resource)

RLIMIT_MEMLOCK (en el módulo resource)

RLIMIT_MSGQUEUE (en el módulo resource)

RLIMIT_NICE (en el módulo resource)

RLIMIT_NOFILE (en el módulo resource)

RLIMIT_NPROC (en el módulo resource)

RLIMIT_NPTS (en el módulo resource)

RLIMIT_OFILE (en el módulo resource)

RLIMIT_RSS (en el módulo resource)

RLIMIT_RTPRIO (en el módulo resource)

RLIMIT_RTTIME (en el módulo resource)

RLIMIT_SBSIZE (en el módulo resource)

RLIMIT_SIGPENDING (en el módulo resource)

RLIMIT_STACK (en el módulo resource)

RLIMIT_SWAP (en el módulo resource)

RLIMIT_VMEM (en el módulo resource)

RLock (clase en multiprocessing)

(clase en threading)

RLock() (método de multiprocessing.managers.SyncManager)

rmd() (método de ftplib.FTP)

rmdir() (en el módulo os)

(en el módulo test.support)

(método de pathlib.Path)

RMFF

rms() (en el módulo audioop)

rmtree() (en el módulo shutil)

(en el módulo test.support)

RobotFileParser (clase en urllib.robotparser)

robots.txt

rollback() (método de sqlite3.Connection)

ROMAN (en el módulo tkinter.font)

ROT_FOUR (opcode)

ROT_THREE (opcode)

ROT_TWO (opcode)

rotate() (método de collections.deque)

(método de decimal.Context)

(método de decimal.Decimal)

(método de logging.handlers.BaseRotatingHandler)

RotatingFileHandler (clase en logging.handlers)

rotation_filename() (método de logging.handlers.BaseRotatingHandler)

rotator (atributo de logging.handlers.BaseRotatingHandler)

round

función incorporada

round() (función incorporada)

ROUND_05UP (en el módulo decimal)

ROUND_CEILING (en el módulo decimal)

ROUND_DOWN (en el módulo decimal)

ROUND_FLOOR (en el módulo decimal)

ROUND_HALF_DOWN (en el módulo decimal)

ROUND_HALF_EVEN (en el módulo decimal)

ROUND_HALF_UP (en el módulo decimal)

ROUND_UP (en el módulo decimal)

Rounded (clase en decimal)

Row (clase en sqlite3)

row_factory (atributo de sqlite3.Connection)

rowcount (atributo de sqlite3.Cursor)

RPAR (en el módulo token)

rpartition() (método de bytearray)

(método de bytes)

(método de str)

rpc_paths (atributo de xmlrpc.server.SimpleXMLRPCRequestHandler)

rpop() (método de poplib.POP3)

rset() (método de poplib.POP3)

RShift (clase en ast)

rshift() (en el módulo operator)

rsplit() (método de bytearray)

(método de bytes)

(método de str)

RSQB (en el módulo token)

rstrip() (método de bytearray)

(método de bytes)

(método de str)

rt() (en el módulo turtle)

RTLD_DEEPBIND (en el módulo os)

RTLD_GLOBAL (en el módulo os)

RTLD_LAZY (en el módulo os)

RTLD_LOCAL (en el módulo os)

RTLD_NODELETE (en el módulo os)

RTLD_NOLOAD (en el módulo os)

RTLD_NOW (en el módulo os)

ruler (atributo de cmd.Cmd)

run (pdb command)

Run script

run() (en el módulo asyncio)

(en el módulo pdb)

(en el módulo profile)

(en el módulo subprocess)

(método de bdb.Bdb)

(método de contextvars.Context)

(método de distutils.cmd.Command)

(método de doctest.DocTestRunner)

(método de multiprocessing.Process)

(método de pdb.Pdb)

(método de profile.Profile)

(método de sched.scheduler)

(método de test.support.BasicTestRunner)

(método de threading.Thread)

(método de trace.Trace)

(método de unittest.IsolatedAsyncioTestCase)

(método de unittest.TestCase)

(método de unittest.TestSuite)

(método de unittest.TextTestRunner)

(método de wsgiref.handlers.BaseHandler)

run_coroutine_threadsafe() (en el módulo asyncio)

run_docstring_examples() (en el módulo doctest)

run_doctest() (en el módulo test.support)

run_forever() (método de asyncio.loop)

run_in_executor() (método de asyncio.loop)

run_in_subinterp() (en el módulo test.support)

run_module() (en el módulo runpy)

run_path() (en el módulo runpy)

run_python_until_end() (en el módulo test.support.script_helper)

run_script() (método de modulefinder.ModuleFinder)

run_setup() (en el módulo distutils.core)

run_unittest() (en el módulo test.support)

run_until_complete() (método de asyncio.loop)

run_with_locale() (en el módulo test.support)

run_with_tz() (en el módulo test.support)

runcall() (en el módulo pdb)

(método de bdb.Bdb)

(método de pdb.Pdb)

(método de profile.Profile)

runcode() (método de code.InteractiveInterpreter)

runctx() (en el módulo profile)

(método de bdb.Bdb)

(método de profile.Profile)

(método de trace.Trace)

runeval() (en el módulo pdb)

(método de bdb.Bdb)

(método de pdb.Pdb)

runfunc() (método de trace.Trace)

running() (método de concurrent.futures.Future)

runpy (módulo)

runsource() (método de code.InteractiveInterpreter)

runtime_checkable() (en el módulo typing)

runtime_library_dir_option() (método de distutils.ccompiler.CCompiler)

RuntimeError

RuntimeWarning

RUSAGE_BOTH (en el módulo resource)

RUSAGE_CHILDREN (en el módulo resource)

RUSAGE_SELF (en el módulo resource)

RUSAGE_THREAD (en el módulo resource)

ruta de importación

RWF_DSYNC (en el módulo os)

RWF_HIPRI (en el módulo os)

RWF_NOWAIT (en el módulo os)

RWF_SYNC (en el módulo os)

Índice – S

S (en el módulo re)

S_ENFMT (en el módulo stat)

S_IEXEC (en el módulo stat)

S_IFBLK (en el módulo stat)

S_IFCHR (en el módulo stat)

S_IFDIR (en el módulo stat)

S_IFDOOR (en el módulo stat)

S_IFIFO (en el módulo stat)

S_IFLNK (en el módulo stat)

S_IFMT() (en el módulo stat)

S_IFPORT (en el módulo stat)

S_IFREG (en el módulo stat)

S_IFSOCK (en el módulo stat)

S_IFWHT (en el módulo stat)

S_IMODE() (en el módulo stat)

S_IREAD (en el módulo stat)

S_IRGRP (en el módulo stat)

S_IROTH (en el módulo stat)

S_IRUSR (en el módulo stat)

S_IRWXG (en el módulo stat)

S_IRWXO (en el módulo stat)

S_IRWXU (en el módulo stat)

S_ISBLK() (en el módulo stat)

S_ISCHR() (en el módulo stat)

S_ISDIR() (en el módulo stat)

S_ISDOOR() (en el módulo stat)

S_ISFIFO() (en el módulo stat)

S_ISGID (en el módulo stat)

S_ISLNK() (en el módulo stat)

S_ISPORT() (en el módulo stat)

S_ISREG() (en el módulo stat)

S_ISSOCK() (en el módulo stat)

S_ISUID (en el módulo stat)

S_ISVTX (en el módulo stat)

S_ISWHT() (en el módulo stat)

S_IWGRP (en el módulo stat)

S_IWOTH (en el módulo stat)

S_IWRITE (en el módulo stat)

S_IWUSR (en el módulo stat)

S_IXGRP (en el módulo stat)

S_IXOTH (en el módulo stat)

S_IXUSR (en el módulo stat)

safe (atributo de uuid.SafeUUID)

safe_substitute() (método de string.Template)

SafeChildWatcher (clase en asyncio)

saferepr() (en el módulo pprint)

SafeUUID (clase en uuid)

saltos de líneas universales

same_files (atributo de filecmp.dircmp)

same_quantum() (método de decimal.Context)

(método de decimal.Decimal)

samefile() (en el módulo os.path)

(método de pathlib.Path)

SameFileError

sameopenfile() (en el módulo os.path)

samestat() (en el módulo os.path)

sample() (en el módulo random)

samples() (método de statistics.NormalDist)

save() (método de http.cookiejar.FileCookieJar)

SaveAs (clase en tkinter.filedialog)

SAVEDCWD (en el módulo test.support)

SaveFileDialog (clase en tkinter.filedialog)

SaveKey() (en el módulo winreg)

SaveSignals (clase en test.support)

savetty() (en el módulo curses)

SAX2DOM (clase en xml.dom.pulldom)

SAXException

SAXNotRecognizedException

SAXNotSupportedException

SAXParseException

scaleb() (método de decimal.Context)

(método de decimal.Decimal)

scandir() (en el módulo os)

scanf()

sched (módulo)

SCHED_BATCH (en el módulo os)

SCHED_FIFO (en el módulo os)

sched_get_priority_max() (en el módulo os)

sched_get_priority_min() (en el módulo os)

sched_getaffinity() (en el módulo os)

sched_getparam() (en el módulo os)

sched_getscheduler() (en el módulo os)

SCHED_IDLE (en el módulo os)

SCHED_OTHER (en el módulo os)

sched_param (clase en os)

sched_priority (atributo de os.sched_param)

SCHED_RESET_ON_FORK (en el módulo os)

SCHED_RR (en el módulo os)

sched_rr_get_interval() (en el módulo os)

sched_setaffinity() (en el módulo os)

sched_setparam() (en el módulo os)

sched_setscheduler() (en el módulo os)

SCHED_SPORADIC (en el módulo os)

sched_yield() (en el módulo os)

scheduler (clase en sched)

schema (en el módulo msilib)

scope, [1]

scope_id (atributo de ipaddress.IPv6Address)

Screen (clase en turtle)

screensize() (en el módulo turtle)

script_from_examples() (en el módulo doctest)

scroll() (método de curses.window)

ScrolledCanvas (clase en turtle)

ScrolledText (clase en tkinter.scrolledtext)

scrollok() (método de curses.window)

scrypt() (en el módulo hashlib)

sdterr

stdin stdout

seal() (en el módulo unittest.mock)

search

path, module, [1], [2], [3], [4], [5], [6], [7]

search() (en el módulo re)

(método de imaplib.IMAP4)

(método de re.Pattern)

second (atributo de datetime.datetime)

(atributo de datetime.time)

seconds since the epoch

secrets (módulo)

SECTCRE (atributo de configparser.ConfigParser)

sections() (método de configparser.ConfigParser)

secuencia

secure (atributo de http.cookiejar.Cookie)

secure hash algorithm, SHA1, SHA224, SHA256, SHA384, SHA512

Secure Sockets Layer

security

CGI

http.server

security considerations

see() (método de tkinter.ttk.Treeview)

seed() (en el módulo random)

seek() (método de chunk.Chunk)

(método de io.IOBase)

(método de io.TextIOBase)

(método de mmap.mmap)

SEEK_CUR (en el módulo os)

SEEK_END (en el módulo os)

SEEK_SET (en el módulo os)

seekable() (método de io.IOBase)

seen_greeting (atributo de smtpd.SMTPChannel)

Select (clase en tkinter.tix)

select (módulo)

select() (en el módulo select)

(método de imaplib.IMAP4)

(método de selectors.BaseSelector)

(método de tkinter.ttk.Notebook)

selected_alpn_protocol() (método de ssl.SSLSocket)

selected_npn_protocol() (método de ssl.SSLSocket)

selection() (método de tkinter.ttk.Treeview)

selection_add() (método de tkinter.ttk.Treeview)

selection_remove() (método de tkinter.ttk.Treeview)

selection_set() (método de tkinter.ttk.Treeview)

selection_toggle() (método de tkinter.ttk.Treeview)

selector (atributo de urllib.request.Request)

SelectorEventLoop (clase en asyncio)

SelectorKey (clase en selectors)

selectors (módulo)

SelectSelector (clase en selectors)

Semaphore (clase en asyncio)

(clase en multiprocessing)

(clase en threading)

Semaphore() (método de multiprocessing.managers.SyncManager)

semaphores, binary

SEMI (en el módulo token)

send() (método de asyncore.dispatcher)

(método de coroutine)

(método de generator)

(método de http.client.HTTPConnection)

(método de imaplib.IMAP4)

(método de logging.handlers.DatagramHandler)

(método de logging.handlers.SocketHandler)

(método de multiprocessing.connection.Connection)

(método de socket.socket)

send_bytes() (método de multiprocessing.connection.Connection)

send_error() (método de http.server.BaseHTTPRequestHandler)

send_fds() (en el módulo socket)

send_flowing_data() (método de formatter.writer)

send_header() (método de http.server.BaseHTTPRequestHandler)

send_hor_rule() (método de formatter.writer)

send_label_data() (método de formatter.writer)

send_line_break() (método de formatter.writer)

send_literal_data() (método de formatter.writer)

send_message() (método de smtplib.SMTP)

send_paragraph() (método de formatter.writer)

send_response() (método de http.server.BaseHTTPRequestHandler)

send_response_only() (método de http.server.BaseHTTPRequestHandler)

send_signal() (método de asyncio.subprocess.Process)

(método de asyncio.SubprocessTransport)

(método de subprocess.Popen)

sendall() (método de socket.socket)

sendcmd() (método de ftplib.FTP)

sendfile() (en el módulo os)

(método de asyncio.loop)

(método de socket.socket)

(método de wsgiref.handlers.BaseHandler)

SendfileNotAvailableError

sendmail() (método de smtplib.SMTP)

sendmsg() (método de socket.socket)

sendmsg_afalg() (método de socket.socket)

sendto() (método de asyncio.DatagramTransport)

(método de socket.socket)

sentencia

assert, [1]

async def

async for

async with

break, [1], [2], [3], [4]

class

continue, [1], [2], [3], [4]

def

del, [1], [2], [3]

except

for, [1], [2], [3]

global, [1]

if, [1]

import, [1], [2], [3], [4]

nonlocal

pass

raise, [1]

return, [1], [2]

try, [1], [2]

while, [1], [2], [3]

with, [1]

yield

sentinel (atributo de multiprocessing.Process)

(en el módulo unittest.mock)

sep (en el módulo os)

sequence

item

iteration

objeto, [1], [2], [3], [4], [5], [6], [7], [8]

types, immutable

types, mutable

types, operations on, [1]

Sequence (clase en collections.abc)

(clase en typing)

sequence (en el módulo msilib)

sequence2st() (en el módulo parser)

SequenceMatcher (clase en difflib)

serializing

objects

serve_forever() (método de asyncio.Server)

(método de socketserver.BaseServer)

server

WWW, [1]

server (atributo de http.server.BaseHTTPRequestHandler)

Server (clase en asyncio)

server_activate() (método de socketserver.BaseServer)

server_address (atributo de socketserver.BaseServer)

server_bind() (método de socketserver.BaseServer)

server_close() (método de socketserver.BaseServer)

server_hostname (atributo de ssl.SSLSocket)

server_side (atributo de ssl.SSLSocket)

server_software (atributo de wsgiref.handlers.BaseHandler)

server_version (atributo de http.server.BaseHTTPRequestHandler)

(atributo de http.server.SimpleHTTPRequestHandler)

ServerProxy (clase en xmlrpc.client)

service_actions() (método de socketserver.BaseServer)

session (atributo de ssl.SSLSocket)

session_reused (atributo de ssl.SSLSocket)

session_stats() (método de ssl.SSLContext)

set

comprehensions

display

objeto, [1], [2], [3]

Set (clase en ast)

(clase en collections.abc)

(clase en typing)

set (clase incorporada)

Set Breakpoint

set type

objeto

set() (método de asyncio.Event)

(método de configparser.ConfigParser)

(método de configparser.RawConfigParser)

(método de contextvars.ContextVar)

(método de http.cookies.Morsel)

(método de ossaudiodev.oss_mixer_device)

(método de test.support.EnvironmentVarGuard)

(método de threading.Event)

(método de tkinter.ttk.Combobox)

(método de tkinter.ttk.Spinbox)

(método de tkinter.ttk.Treeview)

(método de xml.etree.ElementTree.Element)

SET_ADD (opcode)

set_all()

set_allowed_domains() (método de http.cookiejar.DefaultCookiePolicy)

set_alpn_protocols() (método de ssl.SSLContext)

set_app() (método de wsgiref.simple_server.WSGIServer)

set_asyncgen_hooks() (en el módulo sys)

set_authorizer() (método de sqlite3.Connection)

set_auto_history() (en el módulo readline)

set_blocked_domains() (método de http.cookiejar.DefaultCookiePolicy)

set_blocking() (en el módulo os)

set_boundary() (método de email.message.EmailMessage)

(método de email.message.Message)

set_break() (método de bdb.Bdb)

set_charset() (método de email.message.Message)

set_child_watcher() (en el módulo asyncio)

(método de asyncio.AbstractEventLoopPolicy)

set_children() (método de tkinter.ttk.Treeview)

set_ciphers() (método de ssl.SSLContext)

set_completer() (en el módulo readline)

set_completer_delims() (en el módulo readline)

set_completion_display_matches_hook() (en el módulo readline)

set_content() (en el módulo email.contentmanager)

(método de email.contentmanager.ContentManager)

(método de email.message.EmailMessage)

set_continue() (método de bdb.Bdb)

set_cookie() (método de http.cookiejar.CookieJar)

set_cookie_if_ok() (método de http.cookiejar.CookieJar)

set_coroutine_origin_tracking_depth() (en el módulo sys)

set_current() (método de msilib.Feature)

set_data() (método de importlib.abc.SourceLoader)

(método de importlib.machinery.SourceFileLoader)

set_date() (método de mailbox.MaildirMessage)

set_debug() (en el módulo gc)

(método de asyncio.loop)

set_debuglevel() (método de ftplib.FTP)

(método de http.client.HTTPConnection)

(método de nntplib.NNTP)

(método de poplib.POP3)

(método de smtplib.SMTP)

(método de telnetlib.Telnet)

set_default_executor() (método de asyncio.loop)

set_default_type() (método de email.message.EmailMessage)

(método de email.message.Message)

set_default_verify_paths() (método de ssl.SSLContext)

set_defaults() (método de argparse.ArgumentParser)

(método de optparse.OptionParser)

set_ecdh_curve() (método de ssl.SSLContext)

set_errno() (en el módulo ctypes)

set_escdelay() (en el módulo curses)

set_event_loop() (en el módulo asyncio)

(método de asyncio.AbstractEventLoopPolicy)

set_event_loop_policy() (en el módulo asyncio)

set_exception() (método de asyncio.Future)

(método de concurrent.futures.Future)

set_exception_handler() (método de asyncio.loop)

set_executable() (en el módulo multiprocessing)

set_executables() (método de distutils.ccompiler.CCompiler)

set_filter() (método de tkinter.filedialog.FileDialog)

set_flags() (método de mailbox.MaildirMessage)

(método de mailbox.mboxMessage)

(método de mailbox.MMDFMessage)

set_from() (método de mailbox.mboxMessage)

(método de mailbox.MMDFMessage)

set_handle_inheritable() (en el módulo os)

set_history_length() (en el módulo readline)

set_include_dirs() (método de distutils.ccompiler.CCompiler)

set_info() (método de mailbox.MaildirMessage)

set_inheritable() (en el módulo os)

(método de socket.socket)

set_int_max_str_digits() (en el módulo sys)

set_labels() (método de mailbox.BabylMessage)

set_last_error() (en el módulo ctypes)

set_libraries() (método de distutils.ccompiler.CCompiler)

set_library_dirs() (método de distutils.ccompiler.CCompiler)

set_link_objects() (método de distutils.ccompiler.CCompiler)

set_literal (2to3 fixer)

set_loader() (en el módulo importlib.util)

set_match_tests() (en el módulo test.support)

set_memlimit() (en el módulo test.support)

set_name() (método de asyncio.Task)

set_next() (método de bdb.Bdb)

set_nonstandard_attr() (método de http.cookiejar.Cookie)

set_npn_protocols() (método de ssl.SSLContext)

set_ok() (método de http.cookiejar.CookiePolicy)

set_option_negotiation_callback() (método de telnetlib.Telnet)

set_output_charset() (método de gettext.NullTranslations)

set_package() (en el módulo importlib.util)

set_param() (método de email.message.EmailMessage)

(método de email.message.Message)

set_pasv() (método de ftplib.FTP)

set_payload() (método de email.message.Message)

set_policy() (método de http.cookiejar.CookieJar)

set_position() (método de xdrlib.Unpacker)

set_pre_input_hook() (en el módulo readline)

set_progress_handler() (método de sqlite3.Connection)

set_protocol() (método de asyncio.BaseTransport)

set_proxy() (método de urllib.request.Request)

set_python_build() (en el módulo distutils.sysconfig)

set_quit() (método de bdb.Bdb)

set_recsrc() (método de ossaudiodev.oss_mixer_device)

set_result() (método de asyncio.Future)

(método de concurrent.futures.Future)

set_return() (método de bdb.Bdb)

set_running_or_notify_cancel() (método de concurrent.futures.Future)

set_runtime_library_dirs() (método de distutils.ccompiler.CCompiler)

set_selection() (método de tkinter.filedialog.FileDialog)

set_seq1() (método de difflib.SequenceMatcher)

set_seq2() (método de difflib.SequenceMatcher)

set_seqs() (método de difflib.SequenceMatcher)

set_sequences() (método de mailbox.MH)

(método de mailbox.MHMessage)

set_server_documentation() (método de xmlrpc.server.DocCGIXMLRPCRequestHandler)

(método de xmlrpc.server.DocXMLRPCServer)

set_server_name() (método de xmlrpc.server.DocCGIXMLRPCRequestHandler)

(método de xmlrpc.server.DocXMLRPCServer)

set_server_title() (método de xmlrpc.server.DocCGIXMLRPCRequestHandler)

(método de xmlrpc.server.DocXMLRPCServer)

set_servername_callback (atributo de ssl.SSLContext)

set_spacing() (método de formatter.formatter)

set_start_method() (en el módulo multiprocessing)

set_startup_hook() (en el módulo readline)

set_step() (método de bdb.Bdb)

set_subdir() (método de mailbox.MaildirMessage)

set_tabsize() (en el módulo curses)

set_task_factory() (método de asyncio.loop)

set_terminator() (método de asynchat.async_chat)

set_threshold() (en el módulo gc)

set_trace() (en el módulo bdb)

(en el módulo pdb)

(método de bdb.Bdb)

(método de pdb.Pdb)

set_trace_callback() (método de sqlite3.Connection)

set_tunnel() (método de http.client.HTTPConnection)

set_type() (método de email.message.Message)

set_unittest_reportflags() (en el módulo doctest)

set_unixfrom() (método de email.message.EmailMessage)

(método de email.message.Message)

set_until() (método de bdb.Bdb)

SET_UPDATE (opcode)

set_url() (método de urllib.robotparser.RobotFileParser)

set_usage() (método de optparse.OptionParser)

set_userptr() (método de curses.panel.Panel)

set_visible() (método de mailbox.BabylMessage)

set_wakeup_fd() (en el módulo signal)

set_write_buffer_limits() (método de asyncio.WriteTransport)

setacl() (método de imaplib.IMAP4)

setannotation() (método de imaplib.IMAP4)

setattr() (función incorporada)

setattrfunc (tipo C)

setAttribute() (método de xml.dom.Element)

setAttributeNode() (método de xml.dom.Element)

setAttributeNodeNS() (método de xml.dom.Element)

setAttributeNS() (método de xml.dom.Element)

setattrofunc (tipo C)

SetBase() (método de xml.parsers.expat.xmlparser)

setblocking() (método de socket.socket)

setByteStream() (método de xml.sax.xmlreader.InputSource)

setcbreak() (en el módulo tty)

setCharacterStream() (método de xml.sax.xmlreader.InputSource)

SetComp (clase en ast)

setcomptype() (método de aifc.aifc)

(método de sunau.AU_write)

(método de wave.Wave_write)

setContentHandler() (método de xml.sax.xmlreader.XMLReader)

setcontext() (en el módulo decimal)

setDaemon() (método de threading.Thread)

setdefault() (método de dict)

(método de http.cookies.Morsel)

setdefaulttimeout() (en el módulo socket)

setdlopenflags() (en el módulo sys)

setDocumentLocator() (método de xml.sax.handler.ContentHandler)

setDTDHandler() (método de xml.sax.xmlreader.XMLReader)

setegid() (en el módulo os)

setEncoding() (método de xml.sax.xmlreader.InputSource)

setEntityResolver() (método de xml.sax.xmlreader.XMLReader)

setErrorHandler() (método de xml.sax.xmlreader.XMLReader)

seteuid() (en el módulo os)

setFeature() (método de xml.sax.xmlreader.XMLReader)

setfirstweekday() (en el módulo calendar)

setfmt() (método de ossaudiodev.oss_audio_device)

setFormatter() (método de logging.Handler)

setframerate() (método de aifc.aifc)

(método de sunau.AU_write)

(método de wave.Wave_write)

setgid() (en el módulo os)

setgroups() (en el módulo os)

seth() (en el módulo turtle)

setheading() (en el módulo turtle)

sethostname() (en el módulo socket)

setinputsizes() (método de sqlite3.Cursor)

SetInteger() (método de msilib.Record)

setitem() (en el módulo operator)

setitimer() (en el módulo signal)

setLevel() (método de logging.Handler)

(método de logging.Logger)

setlocale() (en el módulo locale)

setLocale() (método de xml.sax.xmlreader.XMLReader)

setLoggerClass() (en el módulo logging)

setlogmask() (en el módulo syslog)

setLogRecordFactory() (en el módulo logging)

setmark() (método de aifc.aifc)

setMaxConns() (método de urllib.request.CacheFTPHandler)

setmode() (en el módulo msvcrt)

setName() (método de threading.Thread)

setnchannels() (método de aifc.aifc)

(método de sunau.AU_write)

(método de wave.Wave_write)

setnframes() (método de aifc.aifc)

(método de sunau.AU_write)

(método de wave.Wave_write)

setoutputsize() (método de sqlite3.Cursor)

SetParamEntityParsing() (método de xml.parsers.expat.xmlparser)

setparameters() (método de ossaudiodev.oss_audio_device)

setparams() (método de aifc.aifc)

(método de sunau.AU_write)

(método de wave.Wave_write)

setpassword() (método de zipfile.ZipFile)

setpgid() (en el módulo os)

setpgrp() (en el módulo os)

setpos() (en el módulo turtle)

(método de aifc.aifc)

(método de sunau.AU_read)

(método de wave.Wave_read)

setposition() (en el módulo turtle)

setpriority() (en el módulo os)

setprofile() (en el módulo sys)

(en el módulo threading)

SetProperty() (método de msilib.SummaryInformation)

setProperty() (método de xml.sax.xmlreader.XMLReader)

setPublicId() (método de xml.sax.xmlreader.InputSource)

setquota() (método de imaplib.IMAP4)

setraw() (en el módulo tty)

setrecursionlimit() (en el módulo sys)

setregid() (en el módulo os)

setresgid() (en el módulo os)

setresuid() (en el módulo os)

setreuid() (en el módulo os)

setrlimit() (en el módulo resource)

setsampwidth() (método de aifc.aifc)

(método de sunau.AU_write)

(método de wave.Wave_write)

setscrreg() (método de curses.window)

setsid() (en el módulo os)

setsockopt() (método de socket.socket)

setstate() (en el módulo random)

(método de codecs.IncrementalDecoder)

(método de codecs.IncrementalEncoder)

setStream() (método de logging.StreamHandler)

SetStream() (método de msilib.Record)

SetString() (método de msilib.Record)

setswitchinterval() (en el módulo sys)

(en el módulo test.support)

(in module sys)

setSystemId() (método de xml.sax.xmlreader.InputSource)

setsyx() (en el módulo curses)

setTarget() (método de logging.handlers.MemoryHandler)

settiltangle() (en el módulo turtle)

settimeout() (método de socket.socket)

setTimeout() (método de urllib.request.CacheFTPHandler)

settrace() (en el módulo sys)

(en el módulo threading)

setuid() (en el módulo os)

setundobuffer() (en el módulo turtle)

setup() (en el módulo distutils.core)

(en el módulo turtle)

(método de socketserver.BaseRequestHandler)

setUp() (método de unittest.TestCase)

SETUP_ANNOTATIONS (opcode)

SETUP_ASYNC_WITH (opcode)

setup_environ() (método de wsgiref.handlers.BaseHandler)

SETUP_FINALLY (opcode)

setup_python() (método de venv.EnvBuilder)

setup_scripts() (método de venv.EnvBuilder)

setup_testing_defaults() (en el módulo wsgiref.util)

SETUP_WITH (opcode)

setUpClass() (método de unittest.TestCase)

setupterm() (en el módulo curses)

SetValue() (en el módulo winreg)

SetValueEx() (en el módulo winreg)

setworldcoordinates() (en el módulo turtle)

setx() (en el módulo turtle)

setxattr() (en el módulo os)

sety() (en el módulo turtle)

SF_APPEND (en el módulo stat)

SF_ARCHIVED (en el módulo stat)

SF_IMMUTABLE (en el módulo stat)

SF_MNOWAIT (en el módulo os)

SF_NODISKIO (en el módulo os)

SF_NOUNLINK (en el módulo stat)

SF_SNAPSHOT (en el módulo stat)

SF_SYNC (en el módulo os)

shape (atributo de memoryview)

Shape (clase en turtle)

shape() (en el módulo turtle)

shapesize() (en el módulo turtle)

shapetransform() (en el módulo turtle)

share() (método de socket.socket)

ShareableList (clase en multiprocessing.shared_memory)

ShareableList() (método de multiprocessing.managers.SharedMemoryManager)

Shared Memory

shared_ciphers() (método de ssl.SSLSocket)

shared_object_filename() (método de distutils.ccompiler.CCompiler)

SharedMemory (clase en multiprocessing.shared_memory)

SharedMemory() (método de multiprocessing.managers.SharedMemoryManager)

SharedMemoryManager (clase en multiprocessing.managers)

shearfactor() (en el módulo turtle)

Shelf (clase en shelve)

shelve

módulo

shelve (módulo)

shield() (en el módulo asyncio)

shift() (método de decimal.Context)

(método de decimal.Decimal)

shift_path_info() (en el módulo wsgiref.util)

shifting

operation

operations

shlex (clase en shlex)

(módulo)

shm (atributo de multiprocessing.shared_memory.ShareableList)

SHORT_TIMEOUT (en el módulo test.support)

shortDescription() (método de unittest.TestCase)

shorten() (en el módulo textwrap)

shouldFlush() (método de logging.handlers.BufferingHandler)

(método de logging.handlers.MemoryHandler)

shouldStop (atributo de unittest.TestResult)

show() (método de curses.panel.Panel)

(método de tkinter.commondialog.Dialog)

show_code() (en el módulo dis)

show_compilers() (en el módulo distutils.ccompiler)

showerror() (en el módulo tkinter.messagebox)

showinfo() (en el módulo tkinter.messagebox)

showsyntaxerror() (método de code.InteractiveInterpreter)

showtraceback() (método de code.InteractiveInterpreter)

showturtle() (en el módulo turtle)

showwarning() (en el módulo tkinter.messagebox)

(en el módulo warnings)

shuffle() (en el módulo random)

shutdown() (en el módulo logging)

(método de concurrent.futures.Executor)

(método de imaplib.IMAP4)

(método de multiprocessing.managers.BaseManager)

(método de socket.socket)

(método de socketserver.BaseServer)

shutdown_asyncgens() (método de asyncio.loop)

shutdown_default_executor() (método de asyncio.loop)

shutil (módulo)

side_effect (atributo de unittest.mock.Mock)

SIG_BLOCK (en el módulo signal)

SIG_DFL (en el módulo signal)

SIG_IGN (en el módulo signal)

SIG_SETMASK (en el módulo signal)

SIG_UNBLOCK (en el módulo signal)

SIGABRT (en el módulo signal)

SIGALRM (en el módulo signal)

SIGBREAK (en el módulo signal)

SIGBUS (en el módulo signal)

SIGCHLD (en el módulo signal)

SIGCLD (en el módulo signal)

SIGCONT (en el módulo signal)

SIGFPE (en el módulo signal)

SIGHUP (en el módulo signal)

SIGILL (en el módulo signal)

SIGINT, [1]

(en el módulo signal)

siginterrupt() (en el módulo signal)

SIGKILL (en el módulo signal)

signal

módulo, [1]

signal (módulo)

signal() (en el módulo signal)

signature (atributo de inspect.BoundArguments)

Signature (clase en inspect)

signature() (en el módulo inspect)

sigpending() (en el módulo signal)

SIGPIPE (en el módulo signal)

SIGSEGV (en el módulo signal)

SIGTERM (en el módulo signal)

sigtimedwait() (en el módulo signal)

SIGUSR1 (en el módulo signal)

SIGUSR2 (en el módulo signal)

sigwait() (en el módulo signal)

sigwaitinfo() (en el módulo signal)

SIGWINCH (en el módulo signal)

simple

statement

Simple Mail Transfer Protocol

SimpleCookie (clase en http.cookies)

simplefilter() (en el módulo warnings)

SimpleHandler (clase en wsgiref.handlers)

SimpleHTTPRequestHandler (clase en http.server)

SimpleNamespace (clase en types)

SimpleQueue (clase en multiprocessing)

(clase en queue)

SimpleXMLRPCRequestHandler (clase en xmlrpc.server)

SimpleXMLRPCServer (clase en xmlrpc.server)

sin() (en el módulo cmath)

(en el módulo math)

SingleAddressHeader (clase en email.headerregistry)

singledispatch() (en el módulo functools)

singledispatchmethod (clase en functools)

singleton

tuple

sinh() (en el módulo cmath)

(en el módulo math)

SIO_KEEPALIVE_VALS (en el módulo socket)

SIO_LOOPBACK_FAST_PATH (en el módulo socket)

SIO_RCVALL (en el módulo socket)

site (módulo)

site command line option

--user-base

--user-site

site-packages

directory

site_maps() (método de urllib.robotparser.RobotFileParser)

sitecustomize

módulo

sixtofour (atributo de ipaddress.IPv6Address)

size (atributo de multiprocessing.shared_memory.SharedMemory)

(atributo de struct.Struct)

(atributo de tarfile.TarInfo)

(atributo de tracemalloc.Statistic)

(atributo de tracemalloc.StatisticDiff)

(atributo de tracemalloc.Trace)

size() (método de ftplib.FTP)

(método de mmap.mmap)

size_diff (atributo de tracemalloc.StatisticDiff)

SIZE_MAX

Sized (clase en collections.abc)

(clase en typing)

sizeof() (en el módulo ctypes)

SKIP (en el módulo doctest)

skip() (en el módulo unittest)

(método de chunk.Chunk)

skip_unless_bind_unix_socket() (en el módulo test.support.socket_helper)

skip_unless_symlink() (en el módulo test.support)

skip_unless_xattr() (en el módulo test.support)

skipIf() (en el módulo unittest)

skipinitialspace (atributo de csv.Dialect)

skipped (atributo de unittest.TestResult)

skippedEntity() (método de xml.sax.handler.ContentHandler)

SkipTest

skipTest() (método de unittest.TestCase)

skipUnless() (en el módulo unittest)

SLASH (en el módulo token)

SLASHEQUAL (en el módulo token)

slave() (método de nntplib.NNTP)

sleep() (en el módulo asyncio)

(en el módulo time)

slice

assignment

función incorporada, [1]

objeto

operation

Slice (clase en ast)

slice (clase incorporada)

slicing, [1], [2]

assignment

SMALLEST (en el módulo test.support)

SMTP

protocol

SMTP (clase en smtplib)

(en el módulo email.policy)

smtp_server (atributo de smtpd.SMTPChannel)

SMTP_SSL (clase en smtplib)

smtp_state (atributo de smtpd.SMTPChannel)

SMTPAuthenticationError

SMTPChannel (clase en smtpd)

SMTPConnectError

smtpd (módulo)

SMTPDataError

SMTPException

SMTPHandler (clase en logging.handlers)

SMTPHeloError

smtplib (módulo)

SMTPNotSupportedError

SMTPRecipientsRefused

SMTPResponseException

SMTPSenderRefused

SMTPServer (clase en smtpd)

SMTPServerDisconnected

SMTPUTF8 (en el módulo email.policy)

Snapshot (clase en tracemalloc)

SND_ALIAS (en el módulo winsound)

SND_ASYNC (en el módulo winsound)

SND_FILENAME (en el módulo winsound)

SND_LOOP (en el módulo winsound)

SND_MEMORY (en el módulo winsound)

SND_NODEFAULT (en el módulo winsound)

SND_NOSTOP (en el módulo winsound)

SND_NOWAIT (en el módulo winsound)

SND_PURGE (en el módulo winsound)

sndhdr (módulo)

sni_callback (atributo de ssl.SSLContext)

sniff() (método de csv.Sniffer)

Sniffer (clase en csv)

sock_accept() (método de asyncio.loop)

SOCK_CLOEXEC (en el módulo socket)

sock_connect() (método de asyncio.loop)

SOCK_DGRAM (en el módulo socket)

SOCK_MAX_SIZE (en el módulo test.support)

SOCK_NONBLOCK (en el módulo socket)

SOCK_RAW (en el módulo socket)

SOCK_RDM (en el módulo socket)

sock_recv() (método de asyncio.loop)

sock_recv_into() (método de asyncio.loop)

sock_sendall() (método de asyncio.loop)

sock_sendfile() (método de asyncio.loop)

SOCK_SEQPACKET (en el módulo socket)

SOCK_STREAM (en el módulo socket)

socket

módulo

objeto

socket (atributo de socketserver.BaseServer)

(clase en socket)

(módulo)

socket() (in module socket)

(método de imaplib.IMAP4)

socket_type (atributo de socketserver.BaseServer)

SocketHandler (clase en logging.handlers)

socketpair() (en el módulo socket)

sockets (atributo de asyncio.Server)

socketserver (módulo)

SocketType (en el módulo socket)

softkwlist (en el módulo keyword)

SOL_ALG (en el módulo socket)

SOL_RDS (en el módulo socket)

SOMAXCONN (en el módulo socket)

sort() (método de imaplib.IMAP4)

(método de list)

sort_stats() (método de pstats.Stats)

sortdict() (en el módulo test.support)

sorted() (función incorporada)

sortTestMethodsUsing (atributo de unittest.TestLoader)

source (atributo de doctest.Example)

(atributo de shlex.shlex)

(pdb command)

source character set

SOURCE_DATE_EPOCH, [1], [2], [3], [4], [5], [6]

source_from_cache() (en el módulo imp)

(en el módulo importlib.util)

source_hash() (en el módulo importlib.util)

SOURCE_SUFFIXES (en el módulo importlib.machinery)

source_to_code() (método estático de importlib.abc.InspectLoader)

SourceFileLoader (clase en importlib.machinery)

sourcehook() (método de shlex.shlex)

SourcelessFileLoader (clase en importlib.machinery)

SourceLoader (clase en importlib.abc)

space

in printf-style formatting, [1]

in string formatting

span() (método de re.Match)

spawn() (en el módulo pty)

(método de distutils.ccompiler.CCompiler)

spawn_python() (en el módulo test.support.script_helper)

spawnl() (en el módulo os)

spawnle() (en el módulo os)

spawnlp() (en el módulo os)

spawnlpe() (en el módulo os)

spawnv() (en el módulo os)

spawnve() (en el módulo os)

spawnvp() (en el módulo os)

spawnvpe() (en el módulo os)

spec_from_file_location() (en el módulo importlib.util)

spec_from_loader() (en el módulo importlib.util)

special

attribute

attribute, generic

method

SpecialFileError

specified_attributes (atributo de xml.parsers.expat.xmlparser)

speed() (en el módulo turtle)

(método de ossaudiodev.oss_audio_device)

Spinbox (clase en tkinter.ttk)

split() (en el módulo os.path)

(en el módulo re)

(en el módulo shlex)

(método de bytearray)

(método de bytes)

(método de re.Pattern)

(método de str)

split_quoted() (en el módulo distutils.util)

splitdrive() (en el módulo os.path)

splitext() (en el módulo os.path)

splitlines() (método de bytearray)

(método de bytes)

(método de str)

SplitResult (clase en urllib.parse)

SplitResultBytes (clase en urllib.parse)

SpooledTemporaryFile() (en el módulo tempfile)

sprintf-style formatting, [1]

spwd (módulo)

sqlite3 (módulo)

sqlite_version (en el módulo sqlite3)

sqlite_version_info (en el módulo sqlite3)

sqrt() (en el módulo cmath)

(en el módulo math)

(método de decimal.Context)

(método de decimal.Decimal)

ssizeargfunc (tipo C)

ssizeobjargproc (tipo C)

SSL

ssl (módulo)

SSL_CERT_FILE

SSL_CERT_PATH

ssl_version (atributo de ftplib.FTP_TLS)

SSLCertVerificationError

SSLContext (clase en ssl)

SSLEOFError

SSLError

SSLErrorNumber (clase en ssl)

SSLKEYLOGFILE, [1]

SSLObject (clase en ssl)

sslobject_class (atributo de ssl.SSLContext)

SSLSession (clase en ssl)

SSLSocket (clase en ssl)

sslsocket_class (atributo de ssl.SSLContext)

SSLSyscallError

SSLv3 (atributo de ssl.TLSVersion)

SSLWantReadError

SSLWantWriteError

SSLZeroReturnError

st() (en el módulo turtle)

st2list() (en el módulo parser)

st2tuple() (en el módulo parser)

st_atime (atributo de os.stat_result)

ST_ATIME (en el módulo stat)

st_atime_ns (atributo de os.stat_result)

st_birthtime (atributo de os.stat_result)

st_blksize (atributo de os.stat_result)

st_blocks (atributo de os.stat_result)

st_creator (atributo de os.stat_result)

st_ctime (atributo de os.stat_result)

ST_CTIME (en el módulo stat)

st_ctime_ns (atributo de os.stat_result)

st_dev (atributo de os.stat_result)

ST_DEV (en el módulo stat)

st_file_attributes (atributo de os.stat_result)

st_flags (atributo de os.stat_result)

st_fstype (atributo de os.stat_result)

st_gen (atributo de os.stat_result)

st_gid (atributo de os.stat_result)

ST_GID (en el módulo stat)

st_ino (atributo de os.stat_result)

ST_INO (en el módulo stat)

st_mode (atributo de os.stat_result)

ST_MODE (en el módulo stat)

st_mtime (atributo de os.stat_result)

ST_MTIME (en el módulo stat)

st_mtime_ns (atributo de os.stat_result)

st_nlink (atributo de os.stat_result)

ST_NLINK (en el módulo stat)

st_rdev (atributo de os.stat_result)

st_reparse_tag (atributo de os.stat_result)

st_rsize (atributo de os.stat_result)

st_size (atributo de os.stat_result)

ST_SIZE (en el módulo stat)

st_type (atributo de os.stat_result)

st_uid (atributo de os.stat_result)

ST_UID (en el módulo stat)

stack

execution

trace

stack (atributo de traceback.TracebackException)

stack viewer

stack() (en el módulo inspect)

stack_effect() (en el módulo dis)

stack_size() (en el módulo _thread)

(en el módulo threading)

stackable

streams

StackSummary (clase en traceback)

stamp() (en el módulo turtle)

standard

output

Standard C

standard input

standard_b64decode() (en el módulo base64)

standard_b64encode() (en el módulo base64)

standarderror (2to3 fixer)

standend() (método de curses.window)

standout() (método de curses.window)

STAR (en el módulo token)

STAREQUAL (en el módulo token)

starmap() (en el módulo itertools)

(método de multiprocessing.pool.Pool)

starmap_async() (método de multiprocessing.pool.Pool)

Starred (clase en ast)

start (atributo de range)

(atributo de UnicodeError)

(slice object attribute), [1]

start() (en el módulo tracemalloc)

(método de logging.handlers.QueueListener)

(método de multiprocessing.managers.BaseManager)

(método de multiprocessing.Process)

(método de re.Match)

(método de threading.Thread)

(método de tkinter.ttk.Progressbar)

(método de xml.etree.ElementTree.TreeBuilder)

start_color() (en el módulo curses)

start_component() (método de msilib.Directory)

start_new_thread() (en el módulo _thread)

start_ns() (método de xml.etree.ElementTree.TreeBuilder)

start_server() (en el módulo asyncio)

start_serving() (método de asyncio.Server)

start_threads() (en el módulo test.support)

start_tls() (método de asyncio.loop)

start_unix_server() (en el módulo asyncio)

StartCdataSectionHandler() (método de xml.parsers.expat.xmlparser)

StartDoctypeDeclHandler() (método de xml.parsers.expat.xmlparser)

startDocument() (método de xml.sax.handler.ContentHandler)

startElement() (método de xml.sax.handler.ContentHandler)

StartElementHandler() (método de xml.parsers.expat.xmlparser)

startElementNS() (método de xml.sax.handler.ContentHandler)

STARTF_USESHOWWINDOW (en el módulo subprocess)

STARTF_USESTDHANDLES (en el módulo subprocess)

startfile() (en el módulo os)

StartNamespaceDeclHandler() (método de xml.parsers.expat.xmlparser)

startPrefixMapping() (método de xml.sax.handler.ContentHandler)

startswith() (método de bytearray)

(método de bytes)

(método de str)

startTest() (método de unittest.TestResult)

startTestRun() (método de unittest.TestResult)

starttls() (método de imaplib.IMAP4)

(método de nntplib.NNTP)

(método de smtplib.SMTP)

STARTUPINFO (clase en subprocess)

stat

módulo

stat (módulo)

stat() (en el módulo os)

(método de nntplib.NNTP)

(método de os.DirEntry)

(método de pathlib.Path)

(método de poplib.POP3)

stat_result (clase en os)

state() (método de tkinter.ttk.Widget)

statement

assignment, [1]

assignment, annotated

assignment, augmented

compound

expression

future

loop, [1], [2], [3]

simple

statement grouping

static_order() (método de graphlib.TopologicalSorter)

staticmethod

función incorporada

staticmethod() (función incorporada)

Statistic (clase en tracemalloc)

StatisticDiff (clase en tracemalloc)

statistics (módulo)

statistics() (método de tracemalloc.Snapshot)

StatisticsError

Stats (clase en pstats)

status (atributo de http.client.HTTPResponse)

(atributo de urllib.response.addinfourl)

status() (método de imaplib.IMAP4)

statvfs() (en el módulo os)

STD_ERROR_HANDLE (en el módulo subprocess)

STD_INPUT_HANDLE (en el módulo subprocess)

STD_OUTPUT_HANDLE (en el módulo subprocess)

StdButtonBox (clase en tkinter.tix)

stderr (atributo de asyncio.subprocess.Process)

(atributo de subprocess.CalledProcessError)

(atributo de subprocess.CompletedProcess)

(atributo de subprocess.Popen)

(atributo de subprocess.TimeoutExpired)

(en el módulo sys)

(in module sys), [1]

stdev (atributo de statistics.NormalDist)

stdev() (en el módulo statistics)

stdin

stdout sdterr

stdin (atributo de asyncio.subprocess.Process)

(atributo de subprocess.Popen)

(en el módulo sys)

(in module sys), [1]

stdio

stdout

sdterr, stdin

stdout (atributo de asyncio.subprocess.Process)

(atributo de subprocess.CalledProcessError)

(atributo de subprocess.CompletedProcess)

(atributo de subprocess.Popen)

(atributo de subprocess.TimeoutExpired)

STDOUT (en el módulo subprocess)

stdout (en el módulo sys)

(in module sys), [1]

step (atributo de range)

(pdb command)

(slice object attribute), [1]

step() (método de tkinter.ttk.Progressbar)

stereocontrols() (método de ossaudiodev.oss_mixer_device)

stls() (método de poplib.POP3)

stop (atributo de range)

(slice object attribute), [1]

stop() (en el módulo tracemalloc)

(método de asyncio.loop)

(método de logging.handlers.QueueListener)

(método de tkinter.ttk.Progressbar)

(método de unittest.TestResult)

stop_here() (método de bdb.Bdb)

StopAsyncIteration

excepción

StopIteration

excepción, [1]

stopListening() (en el módulo logging.config)

stopTest() (método de unittest.TestResult)

stopTestRun() (método de unittest.TestResult)

storbinary() (método de ftplib.FTP)

Store (clase en ast)

store() (método de imaplib.IMAP4)

STORE_ACTIONS (atributo de optparse.Option)

STORE_ATTR (opcode)

STORE_DEREF (opcode)

STORE_FAST (opcode)

STORE_GLOBAL (opcode)

STORE_NAME (opcode)

STORE_SUBSCR (opcode)

storlines() (método de ftplib.FTP)

str (built-in class)

(see also string)

str (clase incorporada)

str() (en el módulo locale)

strcoll() (en el módulo locale)

StreamError

StreamHandler (clase en logging)

streamreader (atributo de codecs.CodecInfo)

StreamReader (clase en asyncio)

(clase en codecs)

StreamReaderWriter (clase en codecs)

StreamRecoder (clase en codecs)

StreamRequestHandler (clase en socketserver)

streams

stackable

streamwriter (atributo de codecs.CodecInfo)

StreamWriter (clase en asyncio)

(clase en codecs)

strerror (atributo de OSError)

strerror()

(en el módulo os)

strftime() (en el módulo time)

(método de datetime.date)

(método de datetime.datetime)

(método de datetime.time)

strict

error handler's name

strict (atributo de csv.Dialect)

(en el módulo email.policy)

strict_domain (atributo de http.cookiejar.DefaultCookiePolicy)

strict_errors() (en el módulo codecs)

strict_ns_domain (atributo de http.cookiejar.DefaultCookiePolicy)

strict_ns_set_initial_dollar (atributo de http.cookiejar.DefaultCookiePolicy)

strict_ns_set_path (atributo de http.cookiejar.DefaultCookiePolicy)

strict_ns_unverifiable (atributo de http.cookiejar.DefaultCookiePolicy)

strict_rfc2965_unverifiable (atributo de http.cookiejar.DefaultCookiePolicy)

strides (atributo de memoryview)

string

__format__() (object method)

__str__() (object method)

conversion, [1]

format() (built-in function)

formatted literal

formatting, printf

immutable sequences

interpolated literal

interpolation, printf

item

methods

módulo

object representation

objeto, [1], [2]

PyObject_Str (C function)

str (built-in class)

str() (built-in function)

text sequence type

string (atributo de re.Match)

STRING (en el módulo token)

string (módulo)

string literal

string_at() (en el módulo ctypes)

StringIO (clase en io)

stringprep (módulo)

strings, documentation, [1]

strip() (método de bytearray)

(método de bytes)

(método de str)

strip_dirs() (método de pstats.Stats)

stripspaces (atributo de curses.textpad.Textbox)

strptime() (en el módulo time)

(método de clase de datetime.datetime)

strsignal() (en el módulo signal)

strtobool() (en el módulo distutils.util)

struct

módulo

Struct (clase en struct)

struct (módulo)

struct_time (clase en time)

Structure (clase en ctypes)

structures

C

strxfrm() (en el módulo locale)

STType (en el módulo parser)

style

coding

Style (clase en tkinter.ttk)

Sub (clase en ast)

sub() (en el módulo operator)

(en el módulo re)

(método de re.Pattern)

sub_commands (atributo de distutils.cmd.Command)

subclassing

immutable types

subdirs (atributo de filecmp.dircmp)

SubElement() (en el módulo xml.etree.ElementTree)

submit() (método de concurrent.futures.Executor)

submodule_search_locations (atributo de importlib.machinery.ModuleSpec)

subn() (en el módulo re)

(método de re.Pattern)

subnet_of() (método de ipaddress.IPv4Network)

(método de ipaddress.IPv6Network)

subnets() (método de ipaddress.IPv4Network)

(método de ipaddress.IPv6Network)

Subnormal (clase en decimal)

suboffsets (atributo de memoryview)

subpad() (método de curses.window)

subprocess (módulo)

subprocess_exec() (método de asyncio.loop)

subprocess_shell() (método de asyncio.loop)

SubprocessError

SubprocessProtocol (clase en asyncio)

SubprocessTransport (clase en asyncio)

subscribe() (método de imaplib.IMAP4)

subscript

assignment

operation

Subscript (clase en ast)

subscription, [1], [2], [3]

assignment

subsequent_indent (atributo de textwrap.TextWrapper)

subst_vars() (en el módulo distutils.util)

substitute() (método de string.Template)

subTest() (método de unittest.TestCase)

subtract() (método de collections.Counter)

(método de decimal.Context)

subtraction

subtype (atributo de email.headerregistry.ContentTypeHeader)

subwin() (método de curses.window)

successful() (método de multiprocessing.pool.AsyncResult)

suffix_map (atributo de mimetypes.MimeTypes)

(en el módulo mimetypes)

suite

suite() (en el módulo parser)

suiteClass (atributo de unittest.TestLoader)

sum() (función incorporada)

sum_list()

sum_sequence(), [1]

summarize() (método de doctest.DocTestRunner)

summarize_address_range() (en el módulo ipaddress)

sunau (módulo)

super (atributo de pyclbr.Class)

super() (función incorporada)

supernet() (método de ipaddress.IPv4Network)

(método de ipaddress.IPv6Network)

supernet_of() (método de ipaddress.IPv4Network)

(método de ipaddress.IPv6Network)

supports_bytes_environ (en el módulo os)

supports_dir_fd (en el módulo os)

supports_effective_ids (en el módulo os)

supports_fd (en el módulo os)

supports_follow_symlinks (en el módulo os)

supports_unicode_filenames (en el módulo os.path)

SupportsAbs (clase en typing)

SupportsBytes (clase en typing)

SupportsComplex (clase en typing)

SupportsFloat (clase en typing)

SupportsIndex (clase en typing)

SupportsInt (clase en typing)

SupportsRound (clase en typing)

suppress() (en el módulo contextlib)

SuppressCrashReport (clase en test.support)

surrogateescape

error handler's name

surrogatepass

error handler's name

SW_HIDE (en el módulo subprocess)

swap_attr() (en el módulo test.support)

swap_item() (en el módulo test.support)

swapcase() (método de bytearray)

(método de bytes)

(método de str)

sym_name (en el módulo symbol)

Symbol (clase en symtable)

symbol (módulo)

SymbolTable (clase en symtable)

symlink() (en el módulo os)

symlink_to() (método de pathlib.Path)

symmetric_difference() (método de frozenset)

symmetric_difference_update() (método de frozenset)

symtable (módulo)

symtable() (en el módulo symtable)

sync() (en el módulo os)

(método de dbm.dumb.dumbdbm)

(método de dbm.gnu.gdbm)

(método de ossaudiodev.oss_audio_device)

(método de shelve.Shelf)

syncdown() (método de curses.window)

synchronized() (en el módulo multiprocessing.sharedctypes)

SyncManager (clase en multiprocessing.managers)

syncok() (método de curses.window)

syncup() (método de curses.window)

syntax

SyntaxErr

SyntaxError

SyntaxWarning

sys

módulo, [1], [2], [3], [4], [5], [6]

sys (módulo)

sys.exc_info

sys.last_traceback

sys.meta_path

sys.modules

sys.path

sys.path_hooks

sys.path_importer_cache

sys.stderr

sys.stdin

sys.stdout

sys_exc (2to3 fixer)

sys_version (atributo de http.server.BaseHTTPRequestHandler)

sysconf() (en el módulo os)

sysconf_names (en el módulo os)

sysconfig (módulo)

syslog (módulo)

syslog() (en el módulo syslog)

SysLogHandler (clase en logging.handlers)

system() (en el módulo os)

(en el módulo platform)

system_alias() (en el módulo platform)

system_must_validate_cert() (en el módulo test.support)

SystemError

(built-in exception), [1]

SystemExit

(built-in exception)

systemId (atributo de xml.dom.DocumentType)

SystemRandom (clase en random)

(clase en secrets)

SystemRoot

Índice – Símbolos

! (exclamation)

in a command interpreter

in curses module

in formatted string literal

in glob-style wildcards, [1]

in string formatting

in struct format strings

! (pdb command)

!=

operador, [1]

" (double quote)

string literal

"""

string literal

# (hash)

comment, [1], [2]

in doctests

in printf-style formatting, [1]

in regular expressions

in string formatting

source encoding declaration

$ (dollar)

environment variables expansion

in regular expressions

in template strings

interpolation in configuration files

% (percent)

datetime format, [1], [2]

environment variables expansion (Windows), [1]

interpolation in configuration files

operador, [1]

printf-style formatting, [1]

%=

augmented assignment

& (ampersand)

operador, [1]

&=

augmented assignment

' (single quote)

string literal

'''

string literal

() (parentheses)

call

class definition

function definition

generator expression

in assignment target list

in printf-style formatting, [1]

in regular expressions

tuple display

(?

in regular expressions

(?!

in regular expressions

(?#

in regular expressions

(?:

in regular expressions

(?<!

in regular expressions

(?<=

in regular expressions

(?=

in regular expressions

(?P<

in regular expressions

(?P=

in regular expressions

* (asterisk)

function definition

import statement

in argparse module

in assignment target list

in AST grammar

in expression lists

in function calls, [1]

in glob-style wildcards, [1]

in printf-style formatting, [1]

in regular expressions

operador, [1]

**

function definition

in dictionary displays

in function calls, [1]

in glob-style wildcards

operador, [1]

**=

augmented assignment

*=

augmented assignment

*?

in regular expressions

+ (plus)

binary operator, [1]

in argparse module

in doctests

in printf-style formatting, [1]

in regular expressions

in string formatting

unary operator, [1]

+=

augmented assignment

+?

in regular expressions

, (comma)

argument list

expression list, [1], [2], [3], [4]

identifier list, [1]

import statement

in dictionary displays

in string formatting

in target list

parameter list

slicing

with statement

- (minus)

binary operator, [1]

in doctests

in glob-style wildcards, [1]

in printf-style formatting, [1]

in regular expressions

in string formatting

unary operator, [1]

--annotate

pickletools command line option

--best

gzip command line option

--buffer

unittest command line option

--catch

unittest command line option

--check-hash-based-pycs default|always|never

command line option

--compact

json.tool command line option

--compress

zipapp command line option

--count

trace command line option

--coverdir=<dir>

trace command line option

--create <tarfile> <source1> ... <sourceN>

tarfile command line option

--create <zipfile> <source1> ... <sourceN>

zipfile command line option

--decompress

gzip command line option

--details

inspect command line option

--exact

tokenize command line option

--extract <tarfile> [<output_dir>]

tarfile command line option

--extract <zipfile> <output_dir>

zipfile command line option

--failfast

unittest command line option

--fast

gzip command line option

--file=<file>

trace command line option

--filter <filtername>

tarfile command line option

--hardlink-dupes

compileall command line option

--help

ast command line option

command line option

gzip command line option

json.tool command line option

timeit command line option

tokenize command line option

trace command line option

zipapp command line option

--ignore-dir=<dir>

trace command line option

--ignore-module=<mod>

trace command line option

--include-attributes

ast command line option

--indent

json.tool command line option

--indent <indent>

ast command line option

--indentlevel=<num>

pickletools command line option

--info

zipapp command line option

--invalidation-mode [timestamp|checked-hash|unchecked-hash]

compileall command line option

--json-lines

json.tool command line option

--list <tarfile>

tarfile command line option

--list <zipfile>

zipfile command line option

--listfuncs

trace command line option

--locals

unittest command line option

--main=<mainfn>

zipapp command line option

--memo

pickletools command line option

--missing

trace command line option

--mode <mode>

ast command line option

--no-ensure-ascii

json.tool command line option

--no-indent

json.tool command line option

--no-report

trace command line option

--no-type-comments

ast command line option

--number=N

timeit command line option

--output=<file>

pickletools command line option

--output=<output>

zipapp command line option

--pattern pattern

unittest-discover command line option

--preamble=<preamble>

pickletools command line option

--process

timeit command line option

--python=<interpreter>

zipapp command line option

--repeat=N

timeit command line option

--report

trace command line option

--setup=S

timeit command line option

--sort-keys

json.tool command line option

--start-directory directory

unittest-discover command line option

--summary

trace command line option

--tab

json.tool command line option

--test <tarfile>

tarfile command line option

--test <zipfile>

zipfile command line option

--timing

trace command line option

--top-level-directory directory

unittest-discover command line option

--trace

trace command line option

--trackcalls

trace command line option

--unit=U

timeit command line option

--user-base

site command line option

--user-site

site command line option

--verbose

tarfile command line option

timeit command line option

unittest-discover command line option

--version

command line option

trace command line option

-=

augmented assignment

->

function annotations, [1]

-?

command line option

-a

ast command line option

pickletools command line option

-B

command line option

-b

command line option

compileall command line option

unittest command line option

-C

trace command line option

-c

trace command line option

unittest command line option

zipapp command line option

-c <command>

command line option

-c <tarfile> <source1> ... <sourceN>

tarfile command line option

-c <zipfile> <source1> ... <sourceN>

zipfile command line option

-d

command line option

gzip command line option

-d destdir

compileall command line option

-E

command line option

-e

tokenize command line option

-e <tarfile> [<output_dir>]

tarfile command line option

-e <zipfile> <output_dir>

zipfile command line option

-e dir

compileall command line option

-f

compileall command line option

trace command line option

unittest command line option

-g

trace command line option

-h

ast command line option

command line option

gzip command line option

json.tool command line option

timeit command line option

tokenize command line option

zipapp command line option

-I

command line option

-i

command line option

-i <indent>

ast command line option

-i list

compileall command line option

-J

command line option

-j N

compileall command line option

-k

unittest command line option

-l

compileall command line option

pickletools command line option

trace command line option

-l <tarfile>

tarfile command line option

-l <zipfile>

zipfile command line option

-m

pickletools command line option

trace command line option

-m <mainfn>

zipapp command line option

-m <mode>

ast command line option

-m <module-name>

command line option

-n N

timeit command line option

-O

command line option

-o

pickletools command line option

-o <output>

zipapp command line option

-o level

compileall command line option

-OO

command line option

-p

pickletools command line option

timeit command line option

unittest-discover command line option

-p <interpreter>

zipapp command line option

-p prepend_prefix

compileall command line option

-q

command line option

compileall command line option

-R

command line option

trace command line option

-r

compileall command line option

trace command line option

-r N

timeit command line option

-S

command line option

-s

command line option

trace command line option

unittest-discover command line option

-s S

timeit command line option

-s strip_prefix

compileall command line option

-T

trace command line option

-t

trace command line option

unittest-discover command line option

-t <tarfile>

tarfile command line option

-t <zipfile>

zipfile command line option

-u

command line option

timeit command line option

-V

command line option

-v

command line option

tarfile command line option

timeit command line option

unittest-discover command line option

-W arg

command line option

-X

command line option

-x

command line option

-x regex

compileall command line option

. (dot)

attribute reference

in glob-style wildcards

in numeric literal

in pathnames, [1]

in printf-style formatting, [1]

in regular expressions

in string formatting

in Tkinter

..

in pathnames

...

ellipsis literal, [1], [2]

in doctests

interpreter prompt, [1]

placeholder, [1], [2]

.ini

file

.pdbrc

file

/ (slash)

function definition

in pathnames, [1]

operador, [1]

//

operador, [1]

//=

augmented assignment

/=

augmented assignment

0b

integer literal

0o

integer literal

0x

integer literal

2-digit years

2to3

: (colon)

annotated variable

compound statement, [1], [2], [3], [4], [5], [6]

function annotations, [1]

in dictionary expressions

in formatted string literal

in SQL statements

in string formatting

lambda expression

path separator (POSIX)

slicing

; (semicolon), [1]

< (less)

in string formatting

in struct format strings

operador, [1]

<<

operador, [1]

<<=

augmented assignment

<=

operador, [1]

<BLANKLINE>

= (equals)

assignment statement

class definition

for help in debugging using string literals

function definition

in function calls

in string formatting

in struct format strings

==

operador, [1]

> (greater)

in string formatting

in struct format strings

operador, [1]

>=

operador, [1]

>>

operador, [1]

>>=

augmented assignment

>>>

interpreter prompt, [1]

? (question mark)

in a command interpreter

in argparse module

in AST grammar

in glob-style wildcards, [1]

in regular expressions

in SQL statements

in struct format strings, [1]

replacement character

??

in regular expressions

@ (at)

class definition

function definition

in struct format strings

operador

[] (square brackets)

in assignment target list

in glob-style wildcards, [1]

in regular expressions

in string formatting

list expression

subscription

\ (backslash)

escape sequence, [1]

in pathnames (Windows)

in regular expressions, [1], [2]

\\

escape sequence

in regular expressions

\A

in regular expressions

\a

escape sequence

in regular expressions

\B

in regular expressions

\b

escape sequence

in regular expressions, [1]

\D

in regular expressions

\d

in regular expressions

\f

escape sequence

in regular expressions

\g

in regular expressions

\N

escape sequence, [1]

in regular expressions

\n

escape sequence

in regular expressions

\r

escape sequence

in regular expressions

\S

in regular expressions

\s

in regular expressions

\t

escape sequence

in regular expressions

\U

escape sequence, [1]

in regular expressions

\u

escape sequence, [1]

in regular expressions

\v

escape sequence

in regular expressions

\W

in regular expressions

\w

in regular expressions

\x

escape sequence, [1]

in regular expressions

\Z

in regular expressions

^ (caret)

in curses module

in regular expressions, [1]

in string formatting

marker, [1]

operador, [1]

^=

augmented assignment

{} (curly brackets)

dictionary expression

in formatted string literal

in regular expressions

in string formatting

set expression

| (vertical bar)

in regular expressions

operador, [1]

|=

augmented assignment

~ (tilde)

home directory expansion

operador, [1]

Índice – T

T_FMT (en el módulo locale)

T_FMT_AMPM (en el módulo locale)

tab

tab() (método de tkinter.ttk.Notebook)

TabError

tabnanny (módulo)

tabs() (método de tkinter.ttk.Notebook)

tabsize (atributo de textwrap.TextWrapper)

tabular

data

tag (atributo de xml.etree.ElementTree.Element)

tag_bind() (método de tkinter.ttk.Treeview)

tag_configure() (método de tkinter.ttk.Treeview)

tag_has() (método de tkinter.ttk.Treeview)

tagName (atributo de xml.dom.Element)

tail (atributo de xml.etree.ElementTree.Element)

take_snapshot() (en el módulo tracemalloc)

takewhile() (en el módulo itertools)

tan() (en el módulo cmath)

(en el módulo math)

tanh() (en el módulo cmath)

(en el módulo math)

tar_filter() (en el módulo tarfile)

TarError

TarFile (clase en tarfile)

tarfile (módulo)

tarfile command line option

--create <tarfile> <source1> ... <sourceN>

--extract <tarfile> [<output_dir>]

--filter <filtername>

--list <tarfile>

--test <tarfile>

--verbose

-c <tarfile> <source1> ... <sourceN>

-e <tarfile> [<output_dir>]

-l <tarfile>

-t <tarfile>

-v

target

deletion

list, [1]

list assignment

list, deletion

loop control

target (atributo de xml.dom.ProcessingInstruction)

tarinfo (atributo de tarfile.FilterError)

TarInfo (clase en tarfile)

Task (clase en asyncio)

task_done() (método de asyncio.Queue)

(método de multiprocessing.JoinableQueue)

(método de queue.Queue)

tau (en el módulo cmath)

(en el módulo math)

tb_frame (traceback attribute)

tb_lasti (traceback attribute)

tb_lineno (traceback attribute)

tb_locals (atributo de unittest.TestResult)

tb_next (traceback attribute)

tbreak (pdb command)

tcdrain() (en el módulo termios)

tcflow() (en el módulo termios)

tcflush() (en el módulo termios)

tcgetattr() (en el módulo termios)

tcgetpgrp() (en el módulo os)

Tcl() (en el módulo tkinter)

TCL_LIBRARY

TCPServer (clase en socketserver)

tcsendbreak() (en el módulo termios)

tcsetattr() (en el módulo termios)

tcsetpgrp() (en el módulo os)

tearDown() (método de unittest.TestCase)

tearDownClass() (método de unittest.TestCase)

tee() (en el módulo itertools)

tell() (método de aifc.aifc)

(método de chunk.Chunk)

(método de io.IOBase)

(método de io.TextIOBase)

(método de mmap.mmap)

(método de sunau.AU_read)

(método de sunau.AU_write)

(método de wave.Wave_read)

(método de wave.Wave_write)

Telnet (clase en telnetlib)

telnetlib (módulo)

TEMP

temp_cwd() (en el módulo test.support)

temp_dir() (en el módulo test.support)

temp_umask() (en el módulo test.support)

tempdir (en el módulo tempfile)

tempfile (módulo)

template (atributo de string.Template)

Template (clase en pipes)

(clase en string)

temporary

file

file name

TemporaryDirectory() (en el módulo tempfile)

TemporaryFile() (en el módulo tempfile)

teredo (atributo de ipaddress.IPv6Address)

TERM, [1]

termattrs() (en el módulo curses)

terminal_size (clase en os)

terminate() (método de asyncio.subprocess.Process)

(método de asyncio.SubprocessTransport)

(método de multiprocessing.pool.Pool)

(método de multiprocessing.Process)

(método de subprocess.Popen)

termination model

terminator (atributo de logging.StreamHandler)

termios (módulo)

termname() (en el módulo curses)

ternary

operator

ternaryfunc (tipo C)

test

identity

membership

test (atributo de doctest.DocTestFailure)

(atributo de doctest.UnexpectedException)

(módulo)

test() (en el módulo cgi)

test.support (módulo)

test.support.bytecode_helper (módulo)

test.support.script_helper (módulo)

test.support.socket_helper (módulo)

TEST_DATA_DIR (en el módulo test.support)

TEST_HOME_DIR (en el módulo test.support)

TEST_HTTP_URL (en el módulo test.support)

TEST_SUPPORT_DIR (en el módulo test.support)

TestCase (clase en unittest)

TestFailed

testfile() (en el módulo doctest)

TESTFN (en el módulo test.support)

TESTFN_ENCODING (en el módulo test.support)

TESTFN_NONASCII (en el módulo test.support)

TESTFN_UNDECODABLE (en el módulo test.support)

TESTFN_UNENCODABLE (en el módulo test.support)

TESTFN_UNICODE (en el módulo test.support)

TestLoader (clase en unittest)

testMethodPrefix (atributo de unittest.TestLoader)

testmod() (en el módulo doctest)

testNamePatterns (atributo de unittest.TestLoader)

TestResult (clase en unittest)

tests (en el módulo imghdr)

testsource() (en el módulo doctest)

testsRun (atributo de unittest.TestResult)

TestSuite (clase en unittest)

testzip() (método de zipfile.ZipFile)

text (atributo de SyntaxError)

(atributo de traceback.TracebackException)

(atributo de xml.etree.ElementTree.Element)

Text (clase en typing)

text (en el módulo msilib)

text mode

text() (en el módulo cgitb)

(método de msilib.Dialog)

text_factory (atributo de sqlite3.Connection)

Textbox (clase en curses.textpad)

TextCalendar (clase en calendar)

textdomain() (en el módulo gettext)

(en el módulo locale)

TextFile (clase en distutils.text_file)

textinput() (en el módulo turtle)

TextIO (clase en typing)

TextIOBase (clase en io)

TextIOWrapper (clase en io)

TextTestResult (clase en unittest)

TextTestRunner (clase en unittest)

textwrap (módulo)

TextWrapper (clase en textwrap)

theme_create() (método de tkinter.ttk.Style)

theme_names() (método de tkinter.ttk.Style)

theme_settings() (método de tkinter.ttk.Style)

theme_use() (método de tkinter.ttk.Style)

THOUSEP (en el módulo locale)

Thread (clase en threading)

thread() (método de imaplib.IMAP4)

thread_info (en el módulo sys)

thread_time() (en el módulo time)

thread_time_ns() (en el módulo time)

ThreadedChildWatcher (clase en asyncio)

threading (módulo)

threading_cleanup() (en el módulo test.support)

threading_setup() (en el módulo test.support)

ThreadingHTTPServer (clase en http.server)

ThreadingMixIn (clase en socketserver)

ThreadingTCPServer (clase en socketserver)

ThreadingUDPServer (clase en socketserver)

ThreadPool (clase en multiprocessing.pool)

ThreadPoolExecutor (clase en concurrent.futures)

threads

POSIX

threadsafety (en el módulo sqlite3)

throw (2to3 fixer)

throw() (método de coroutine)

(método de generator)

ticket_lifetime_hint (atributo de ssl.SSLSession)

tigetflag() (en el módulo curses)

tigetnum() (en el módulo curses)

tigetstr() (en el módulo curses)

TILDE (en el módulo token)

tilt() (en el módulo turtle)

tiltangle() (en el módulo turtle)

time (atributo de ssl.SSLSession)

(clase en datetime)

(módulo)

time() (en el módulo time)

(método de asyncio.loop)

(método de datetime.datetime)

Time2Internaldate() (en el módulo imaplib)

time_ns() (en el módulo time)

timedelta (clase en datetime)

TimedRotatingFileHandler (clase en logging.handlers)

timegm() (en el módulo calendar)

timeit (módulo)

timeit command line option

--help

--number=N

--process

--repeat=N

--setup=S

--unit=U

--verbose

-h

-n N

-p

-r N

-s S

-u

-v

timeit() (en el módulo timeit)

(método de timeit.Timer)

timeout

(atributo de socketserver.BaseServer)

(atributo de ssl.SSLSession)

(atributo de subprocess.TimeoutExpired)

timeout() (método de curses.window)

TIMEOUT_MAX (en el módulo _thread)

(en el módulo threading)

TimeoutError, [1], [2], [3]

TimeoutExpired

Timer (clase en threading)

(clase en timeit)

TimerHandle (clase en asyncio)

times() (en el módulo os)

TIMESTAMP (atributo de py_compile.PycInvalidationMode)

timestamp() (método de datetime.datetime)

timetuple() (método de datetime.date)

(método de datetime.datetime)

timetz() (método de datetime.datetime)

timezone (clase en datetime)

(en el módulo time)

tipado de pato

tipo

tipos genéricos

title() (en el módulo turtle)

(método de bytearray)

(método de bytes)

(método de str)

Tix

tix_addbitmapdir() (método de tkinter.tix.tixCommand)

tix_cget() (método de tkinter.tix.tixCommand)

tix_configure() (método de tkinter.tix.tixCommand)

tix_filedialog() (método de tkinter.tix.tixCommand)

tix_getbitmap() (método de tkinter.tix.tixCommand)

tix_getimage() (método de tkinter.tix.tixCommand)

tix_option_get() (método de tkinter.tix.tixCommand)

tix_resetoptions() (método de tkinter.tix.tixCommand)

tixCommand (clase en tkinter.tix)

Tk

tk (atributo de tkinter.Tk)

Tk (clase en tkinter)

(clase en tkinter.tix)

Tk Option Data Types

TK_LIBRARY

Tkinter

tkinter (módulo)

tkinter.colorchooser (módulo)

tkinter.commondialog (módulo)

tkinter.dnd (módulo)

tkinter.filedialog (módulo)

tkinter.font (módulo)

tkinter.messagebox (módulo)

tkinter.scrolledtext (módulo)

tkinter.simpledialog (módulo)

tkinter.tix (módulo)

tkinter.ttk (módulo)

TList (clase en tkinter.tix)

TLS

TLSv1 (atributo de ssl.TLSVersion)

TLSv1_1 (atributo de ssl.TLSVersion)

TLSv1_2 (atributo de ssl.TLSVersion)

TLSv1_3 (atributo de ssl.TLSVersion)

TLSVersion (clase en ssl)

TMP

TMPDIR

to_bytes() (método de int)

to_eng_string() (método de decimal.Context)

(método de decimal.Decimal)

to_integral() (método de decimal.Decimal)

to_integral_exact() (método de decimal.Context)

(método de decimal.Decimal)

to_integral_value() (método de decimal.Decimal)

to_sci_string() (método de decimal.Context)

to_thread() (en el módulo asyncio)

ToASCII() (en el módulo encodings.idna)

tobuf() (método de tarfile.TarInfo)

tobytes() (método de array.array)

(método de memoryview)

today() (método de clase de datetime.date)

(método de clase de datetime.datetime)

tofile() (método de array.array)

tok_name (en el módulo token)

token

(atributo de shlex.shlex)

Token (clase en contextvars)

token (módulo)

token_bytes() (en el módulo secrets)

token_hex() (en el módulo secrets)

token_urlsafe() (en el módulo secrets)

TokenError

tokenize (módulo)

tokenize command line option

--exact

--help

-e

-h

tokenize() (en el módulo tokenize)

tolist() (método de array.array)

(método de memoryview)

(método de parser.ST)

tomono() (en el módulo audioop)

toordinal() (método de datetime.date)

(método de datetime.datetime)

top() (método de curses.panel.Panel)

(método de poplib.POP3)

top_panel() (en el módulo curses.panel)

TopologicalSorter (clase en graphlib)

toprettyxml() (método de xml.dom.minidom.Node)

toreadonly() (método de memoryview)

tostereo() (en el módulo audioop)

tostring() (en el módulo xml.etree.ElementTree)

tostringlist() (en el módulo xml.etree.ElementTree)

total_changes (atributo de sqlite3.Connection)

total_nframe (atributo de tracemalloc.Traceback)

total_ordering() (en el módulo functools)

total_seconds() (método de datetime.timedelta)

totuple() (método de parser.ST)

touch() (método de pathlib.Path)

touchline() (método de curses.window)

touchwin() (método de curses.window)

ToUnicode() (en el módulo encodings.idna)

tounicode() (método de array.array)

towards() (en el módulo turtle)

toxml() (método de xml.dom.minidom.Node)

tparm() (en el módulo curses)

trace

stack

Trace (clase en trace)

(clase en tracemalloc)

trace (módulo)

trace command line option

--count

--coverdir=<dir>

--file=<file>

--help

--ignore-dir=<dir>

--ignore-module=<mod>

--listfuncs

--missing

--no-report

--report

--summary

--timing

--trace

--trackcalls

--version

-c

-C

-f

-g

-l

-m

-r

-R

-s

-t

-T

trace function, [1], [2]

trace() (en el módulo inspect)

trace_dispatch() (método de bdb.Bdb)

traceback

objeto, [1], [2], [3], [4]

traceback (atributo de tracemalloc.Statistic)

(atributo de tracemalloc.StatisticDiff)

(atributo de tracemalloc.Trace)

Traceback (clase en tracemalloc)

traceback (módulo)

traceback_limit (atributo de tracemalloc.Snapshot)

(atributo de wsgiref.handlers.BaseHandler)

TracebackException (clase en traceback)

tracebacklimit (en el módulo sys)

tracebacks

in CGI scripts

TracebackType (clase en types)

tracemalloc (módulo)

tracer() (en el módulo turtle)

traces (atributo de tracemalloc.Snapshot)

trailing

comma

transfercmd() (método de ftplib.FTP)

transient_internet() (en el módulo test.support.socket_helper)

TransientResource (clase en test.support)

translate() (en el módulo fnmatch)

(método de bytearray)

(método de bytes)

(método de str)

translation() (en el módulo gettext)

transport (atributo de asyncio.StreamWriter)

Transport (clase en asyncio)

Transport Layer Security

Traversable (clase en importlib.abc)

TraversableResources (clase en importlib.abc)

traverseproc (tipo C)

Tree (clase en tkinter.tix)

TreeBuilder (clase en xml.etree.ElementTree)

Treeview (clase en tkinter.ttk)

triangular() (en el módulo random)

triple-quoted string

True, [1], [2]

true

True (variable incorporada)

truediv() (en el módulo operator)

trunc() (en el módulo math)

(in module math)

truncate() (en el módulo os)

(método de io.IOBase)

truth

value

truth() (en el módulo operator)

try

sentencia, [1], [2]

Try (clase en ast)

ttk

tty

I/O control

tty (módulo)

ttyname() (en el módulo os)

tupla nombrada

tuple

empty, [1]

función incorporada, [1]

objeto, [1], [2], [3], [4], [5], [6]

singleton

Tuple (clase en ast)

tuple (clase incorporada)

Tuple (en el módulo typing)

tuple2st() (en el módulo parser)

tuple_params (2to3 fixer)

Turtle (clase en turtle)

turtle (módulo)

turtledemo (módulo)

turtles() (en el módulo turtle)

TurtleScreen (clase en turtle)

turtlesize() (en el módulo turtle)

type

Boolean

data

función incorporada, [1], [2], [3]

hierarchy

immutable data

objeto, [1], [2]

operations on dictionary

operations on list

type (atributo de optparse.Option)

(atributo de socket.socket)

(atributo de tarfile.TarInfo)

(atributo de urllib.request.Request)

Type (clase en typing)

type (clase incorporada)

type of an object

type_check_only() (en el módulo typing)

TYPE_CHECKER (atributo de optparse.Option)

TYPE_CHECKING (en el módulo typing)

type_comment (atributo de ast.arg)

(atributo de ast.Assign)

(atributo de ast.For)

(atributo de ast.FunctionDef)

(atributo de ast.With)

TYPE_COMMENT (en el módulo token)

TYPE_IGNORE (en el módulo token)

typeahead() (en el módulo curses)

typecode (atributo de array.array)

typecodes (en el módulo array)

TYPED_ACTIONS (atributo de optparse.Option)

typed_subpart_iterator() (en el módulo email.iterators)

TypedDict (clase en typing)

TypeError

excepción

types

built-in

immutable sequence

módulo

mutable sequence

operations on integer

operations on mapping

operations on numeric

operations on sequence, [1]

types (2to3 fixer)

TYPES (atributo de optparse.Option)

types (módulo)

types, internal

types_map (atributo de mimetypes.MimeTypes)

(en el módulo mimetypes)

types_map_inv (atributo de mimetypes.MimeTypes)

TypeVar (clase en typing)

typing (módulo)

TZ, [1], [2], [3], [4], [5]

tzinfo (atributo de datetime.datetime)

(atributo de datetime.time)

(clase en datetime)

tzname (en el módulo time)

tzname() (método de datetime.datetime)

(método de datetime.time)

(método de datetime.timezone)

(método de datetime.tzinfo)

TZPATH (en el módulo zoneinfo)

tzset() (en el módulo time)

Índice – U

u"

string literal

u'

string literal

u-LAW, [1], [2]

UAdd (clase en ast)

ucd_3_2_0 (en el módulo unicodedata)

udata (atributo de select.kevent)

UDPServer (clase en socketserver)

UF_APPEND (en el módulo stat)

UF_COMPRESSED (en el módulo stat)

UF_HIDDEN (en el módulo stat)

UF_IMMUTABLE (en el módulo stat)

UF_NODUMP (en el módulo stat)

UF_NOUNLINK (en el módulo stat)

UF_OPAQUE (en el módulo stat)

uid (atributo de tarfile.TarInfo)

UID (clase en plistlib)

uid() (método de imaplib.IMAP4)

uidl() (método de poplib.POP3)

ulaw2lin() (en el módulo audioop)

ULONG_MAX

ulp() (en el módulo math)

umask() (en el módulo os)

unalias (pdb command)

uname (atributo de tarfile.TarInfo)

uname() (en el módulo os)

(en el módulo platform)

unary

arithmetic operation

bitwise operation

UNARY_INVERT (opcode)

UNARY_NEGATIVE (opcode)

UNARY_NOT (opcode)

UNARY_POSITIVE (opcode)

unaryfunc (tipo C)

UnaryOp (clase en ast)

unbinding

name

UnboundLocalError, [1]

unbuffered I/O

UNC paths

and os.makedirs()

UNCHECKED_HASH (atributo de py_compile.PycInvalidationMode)

unconsumed_tail (atributo de zlib.Decompress)

unctrl() (en el módulo curses)

(en el módulo curses.ascii)

undefine_macro() (método de distutils.ccompiler.CCompiler)

Underflow (clase en decimal)

undisplay (pdb command)

undo() (en el módulo turtle)

undobufferentries() (en el módulo turtle)

undoc_header (atributo de cmd.Cmd)

unescape() (en el módulo html)

(en el módulo xml.sax.saxutils)

UnexpectedException

unexpectedSuccesses (atributo de unittest.TestResult)

unfreeze() (en el módulo gc)

unget_wch() (en el módulo curses)

ungetch() (en el módulo curses)

(en el módulo msvcrt)

ungetmouse() (en el módulo curses)

ungetwch() (en el módulo msvcrt)

unhexlify() (en el módulo binascii)

Unicode, [1], [2]

database

unicode (2to3 fixer)

Unicode Consortium

unicodedata (módulo)

UnicodeDecodeError

UnicodeEncodeError

UnicodeError

UnicodeTranslateError

UnicodeWarning

unidata_version (en el módulo unicodedata)

unified_diff() (en el módulo difflib)

uniform() (en el módulo random)

UnimplementedFileMode

Union (clase en ctypes)

(en el módulo typing)

union() (método de frozenset)

unique() (en el módulo enum)

unittest (módulo)

unittest command line option

--buffer

--catch

--failfast

--locals

-b

-c

-f

-k

unittest-discover command line option

--pattern pattern

--start-directory directory

--top-level-directory directory

--verbose

-p

-s

-t

-v

unittest.mock (módulo)

universal newlines

bytearray.splitlines method

bytes.splitlines method

csv.reader function

importlib.abc.InspectLoader.get_source method

io.IncrementalNewlineDecoder class

io.TextIOWrapper class

open() built-in function

str.splitlines method

subprocess module

What's new, [1], [2], [3]

UNIX

file control

I/O control

unix_dialect (clase en csv)

unix_shell (en el módulo test.support)

UnixDatagramServer (clase en socketserver)

UnixStreamServer (clase en socketserver)

unknown (atributo de uuid.SafeUUID)

unknown_decl() (método de html.parser.HTMLParser)

unknown_open() (método de urllib.request.BaseHandler)

(método de urllib.request.UnknownHandler)

UnknownHandler (clase en urllib.request)

UnknownProtocol

UnknownTransferEncoding

unlink() (en el módulo os)

(en el módulo test.support)

(método de multiprocessing.shared_memory.SharedMemory)

(método de pathlib.Path)

(método de xml.dom.minidom.Node)

unload() (en el módulo test.support)

unlock() (método de mailbox.Babyl)

(método de mailbox.Mailbox)

(método de mailbox.Maildir)

(método de mailbox.mbox)

(método de mailbox.MH)

(método de mailbox.MMDF)

unpack() (en el módulo struct)

(método de struct.Struct)

unpack_archive() (en el módulo shutil)

unpack_array() (método de xdrlib.Unpacker)

unpack_bytes() (método de xdrlib.Unpacker)

unpack_double() (método de xdrlib.Unpacker)

UNPACK_EX (opcode)

unpack_farray() (método de xdrlib.Unpacker)

unpack_float() (método de xdrlib.Unpacker)

unpack_fopaque() (método de xdrlib.Unpacker)

unpack_from() (en el módulo struct)

(método de struct.Struct)

unpack_fstring() (método de xdrlib.Unpacker)

unpack_list() (método de xdrlib.Unpacker)

unpack_opaque() (método de xdrlib.Unpacker)

UNPACK_SEQUENCE (opcode)

unpack_string() (método de xdrlib.Unpacker)

Unpacker (clase en xdrlib)

unpacking

dictionary

in function calls

iterable

unparse() (en el módulo ast)

unparsedEntityDecl() (método de xml.sax.handler.DTDHandler)

UnparsedEntityDeclHandler() (método de xml.parsers.expat.xmlparser)

Unpickler (clase en pickle)

UnpicklingError

unquote() (en el módulo email.utils)

(en el módulo urllib.parse)

unquote_plus() (en el módulo urllib.parse)

unquote_to_bytes() (en el módulo urllib.parse)

unraisablehook() (en el módulo sys)

unreachable object

unreadline() (método de distutils.text_file.TextFile)

unrecognized escape sequence

unregister() (en el módulo atexit)

(en el módulo faulthandler)

(método de select.devpoll)

(método de select.epoll)

(método de select.poll)

(método de selectors.BaseSelector)

unregister_archive_format() (en el módulo shutil)

unregister_dialect() (en el módulo csv)

unregister_unpack_format() (en el módulo shutil)

unsafe (atributo de uuid.SafeUUID)

unselect() (método de imaplib.IMAP4)

unset() (método de test.support.EnvironmentVarGuard)

unsetenv() (en el módulo os)

UnstructuredHeader (clase en email.headerregistry)

unsubscribe() (método de imaplib.IMAP4)

UnsupportedOperation

until (pdb command)

untokenize() (en el módulo tokenize)

untouchwin() (método de curses.window)

unused_data (atributo de bz2.BZ2Decompressor)

(atributo de lzma.LZMADecompressor)

(atributo de zlib.Decompress)

unverifiable (atributo de urllib.request.Request)

unwrap() (en el módulo inspect)

(en el módulo urllib.parse)

(método de ssl.SSLSocket)

up (pdb command)

up() (en el módulo turtle)

update() (en el módulo turtle)

(método de collections.Counter)

(método de dict)

(método de frozenset)

(método de hashlib.hash)

(método de hmac.HMAC)

(método de http.cookies.Morsel)

(método de mailbox.Mailbox)

(método de mailbox.Maildir)

(método de trace.CoverageResults)

update_authenticated() (método de urllib.request.HTTPPasswordMgrWithPriorAuth)

update_lines_cols() (en el módulo curses)

update_panels() (en el módulo curses.panel)

update_visible() (método de mailbox.BabylMessage)

update_wrapper() (en el módulo functools)

upgrade_dependencies() (método de venv.EnvBuilder)

upper() (método de bytearray)

(método de bytes)

(método de str)

urandom() (en el módulo os)

URL, [1], [2], [3]

parsing

relative

url (atributo de http.client.HTTPResponse)

(atributo de urllib.response.addinfourl)

(atributo de xmlrpc.client.ProtocolError)

url2pathname() (en el módulo urllib.request)

urlcleanup() (en el módulo urllib.request)

urldefrag() (en el módulo urllib.parse)

urlencode() (en el módulo urllib.parse)

URLError

urljoin() (en el módulo urllib.parse)

urllib (2to3 fixer)

(módulo)

urllib.error (módulo)

urllib.parse (módulo)

urllib.request

módulo

urllib.request (módulo)

urllib.response (módulo)

urllib.robotparser (módulo)

urlopen() (en el módulo urllib.request)

URLopener (clase en urllib.request)

urlparse() (en el módulo urllib.parse)

urlretrieve() (en el módulo urllib.request)

urlsafe_b64decode() (en el módulo base64)

urlsafe_b64encode() (en el módulo base64)

urlsplit() (en el módulo urllib.parse)

urlunparse() (en el módulo urllib.parse)

urlunsplit() (en el módulo urllib.parse)

urn (atributo de uuid.UUID)

use_default_colors() (en el módulo curses)

use_env() (en el módulo curses)

use_rawinput (atributo de cmd.Cmd)

UseForeignDTD() (método de xml.parsers.expat.xmlparser)

USER

user

effective id

id

id, setting

user() (método de poplib.POP3)

user-defined

function

function call

method

user-defined function

objeto, [1], [2]

user-defined method

objeto

USER_BASE

(en el módulo site)

user_call() (método de bdb.Bdb)

user_exception() (método de bdb.Bdb)

user_line() (método de bdb.Bdb)

user_return() (método de bdb.Bdb)

USER_SITE (en el módulo site)

usercustomize

módulo

UserDict (clase en collections)

UserList (clase en collections)

USERNAME, [1]

username (atributo de email.headerregistry.Address)

USERPROFILE, [1], [2], [3], [4]

userptr() (método de curses.panel.Panel)

UserString (clase en collections)

UserWarning

USTAR_FORMAT (en el módulo tarfile)

USub (clase en ast)

UTC

utc (atributo de datetime.timezone)

utcfromtimestamp() (método de clase de datetime.datetime)

utcnow() (método de clase de datetime.datetime)

utcoffset() (método de datetime.datetime)

(método de datetime.time)

(método de datetime.timezone)

(método de datetime.tzinfo)

utctimetuple() (método de datetime.datetime)

utf8 (atributo de email.policy.EmailPolicy)

utf8() (método de poplib.POP3)

utf8_enabled (atributo de imaplib.IMAP4)

utime() (en el módulo os)

uu

módulo

uu (módulo)

UUID (clase en uuid)

uuid (módulo)

uuid1

uuid1() (en el módulo uuid)

uuid3

uuid3() (en el módulo uuid)

uuid4

uuid4() (en el módulo uuid)

uuid5

uuid5() (en el módulo uuid)

UuidCreate() (en el módulo msilib)

Índice – V

v4_int_to_packed() (en el módulo ipaddress)

v6_int_to_packed() (en el módulo ipaddress)

valid_signals() (en el módulo signal)

validator() (en el módulo wsgiref.validate)

value

default parameter

truth

value (atributo de ctypes._SimpleCData)

(atributo de http.cookiejar.Cookie)

(atributo de http.cookies.Morsel)

(atributo de xml.dom.Attr)

value of an object

Value() (en el módulo multiprocessing)

(en el módulo multiprocessing.sharedctypes)

(método de multiprocessing.managers.SyncManager)

value_decode() (método de http.cookies.BaseCookie)

value_encode() (método de http.cookies.BaseCookie)

ValueError

excepción

valuerefs() (método de weakref.WeakValueDictionary)

values

Boolean

writing

values() (método de contextvars.Context)

(método de dict)

(método de email.message.EmailMessage)

(método de email.message.Message)

(método de mailbox.Mailbox)

(método de types.MappingProxyType)

ValuesView (clase en collections.abc)

(clase en typing)

var (atributo de contextvars.Token)

variable

free

variable de clase

variable de contexto

variables de entorno

APPDATA

AUDIODEV

BROWSER, [1]

CC

CFLAGS, [1], [2]

COLS, [1]

COLUMNS, [1]

COMSPEC, [1]

CPP

CPPFLAGS

DISPLAY

DISTUTILS_DEBUG

EnableControlFlowGuard

exec_prefix, [1], [2]

HOME, [1], [2], [3], [4], [5], [6], [7], [8], [9]

HOMEDRIVE, [1]

HOMEPATH, [1]

http_proxy, [1], [2]

IDLESTARTUP, [1], [2], [3]

KDEDIR

LANG, [1], [2], [3], [4]

LANGUAGE, [1]

LC_ALL, [1]

LC_MESSAGES, [1]

LDCXXSHARED

LDFLAGS

LINES, [1], [2], [3], [4]

LNAME

LOGNAME, [1]

MIXERDEV

no_proxy

PAGER

PATH, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21], [22], [23], [24], [25], [26], [27], [28], [29], [30], [31], [32], [33], [34], [35], [36], [37], [38], [39]

PATHEXT, [1], [2]

PIP_USER

PLAT

POSIXLY_CORRECT

prefix, [1], [2], [3]

PY_PYTHON

PYTHON*, [1], [2], [3], [4], [5]

PYTHON_DOM

PYTHONASYNCIODEBUG, [1], [2], [3]

PYTHONBREAKPOINT, [1], [2], [3], [4]

PYTHONCASEOK, [1], [2], [3], [4]

PYTHONCOERCECLOCALE, [1], [2], [3]

PYTHONDEBUG, [1], [2]

PYTHONDEVMODE, [1], [2]

PYTHONDOCS

PYTHONDONTWRITEBYTECODE, [1], [2], [3], [4], [5], [6]

PYTHONDUMPREFS, [1], [2], [3]

PYTHONEXECUTABLE

PYTHONFAULTHANDLER, [1], [2], [3]

PYTHONHASHSEED, [1], [2], [3], [4], [5], [6], [7], [8], [9]

PYTHONHOME, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17]

PYTHONINSPECT, [1], [2], [3]

PYTHONINTMAXSTRDIGITS, [1], [2], [3], [4], [5]

PYTHONIOENCODING, [1], [2], [3], [4], [5], [6], [7]

PYTHONLEGACYWINDOWSFSENCODING, [1], [2], [3]

PYTHONLEGACYWINDOWSSTDIO, [1], [2], [3], [4]

PYTHONMALLOC, [1], [2], [3], [4], [5], [6], [7], [8], [9]

PYTHONMALLOCSTATS, [1], [2]

PYTHONNOUSERSITE, [1], [2], [3]

PYTHONOLDPARSER, [1], [2]

PYTHONOPTIMIZE, [1], [2]

PYTHONPATH, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21], [22], [23], [24], [25]

PYTHONPLATLIBDIR, [1]

PYTHONPROFILEIMPORTTIME, [1], [2], [3]

PYTHONPYCACHEPREFIX, [1], [2], [3], [4]

PYTHONSHOWALLOCCOUNT

PYTHONSHOWREFCOUNT

PYTHONSTARTUP, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11]

PYTHONTHREADDEBUG

PYTHONTRACEMALLOC, [1], [2]

PYTHONTRACEMALLOC`comienzo, configura la variable del entorno a ``25`

PYTHONTZPATH, [1]

PYTHONUNBUFFERED, [1], [2], [3], [4]

PYTHONUSERBASE, [1], [2], [3]

PYTHONUSERSITE

PYTHONUTF8, [1], [2], [3], [4], [5], [6]

PYTHONVERBOSE, [1], [2]

PYTHONWARNINGS, [1], [2], [3], [4], [5], [6], [7], [8], [9]

SOURCE_DATE_EPOCH, [1], [2], [3], [4], [5], [6]

SSL_CERT_FILE

SSL_CERT_PATH

SSLKEYLOGFILE, [1]

SystemRoot

TCL_LIBRARY

TEMP

TERM, [1]

TK_LIBRARY

TMP

TMPDIR

TZ, [1], [2], [3], [4], [5]

USER

USER_BASE

USERNAME, [1]

USERPROFILE, [1], [2], [3], [4]

VIRTUAL_ENV

variance (atributo de statistics.NormalDist)

variance() (en el módulo statistics)

variant (atributo de uuid.UUID)

vars() (función incorporada)

vbar (atributo de tkinter.scrolledtext.ScrolledText)

VBAR (en el módulo token)

VBAREQUAL (en el módulo token)

Vec2D (clase en turtle)

vectorcallfunc (tipo C)

venv (módulo)

VERBOSE (en el módulo re)

verbose (en el módulo tabnanny)

(en el módulo test.support)

verify() (método de smtplib.SMTP)

verify_client_post_handshake() (método de ssl.SSLSocket)

verify_code (atributo de ssl.SSLCertVerificationError)

VERIFY_CRL_CHECK_CHAIN (en el módulo ssl)

VERIFY_CRL_CHECK_LEAF (en el módulo ssl)

VERIFY_DEFAULT (en el módulo ssl)

verify_flags (atributo de ssl.SSLContext)

verify_message (atributo de ssl.SSLCertVerificationError)

verify_mode (atributo de ssl.SSLContext)

verify_request() (método de socketserver.BaseServer)

VERIFY_X509_STRICT (en el módulo ssl)

VERIFY_X509_TRUSTED_FIRST (en el módulo ssl)

VerifyFlags (clase en ssl)

VerifyMode (clase en ssl)

version (atributo de email.headerregistry.MIMEVersionHeader)

(atributo de http.client.HTTPResponse)

(atributo de http.cookiejar.Cookie)

(atributo de ipaddress.IPv4Address)

(atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Address)

(atributo de ipaddress.IPv6Network)

(atributo de urllib.request.URLopener)

(atributo de uuid.UUID)

(en el módulo curses)

(en el módulo marshal)

(en el módulo sqlite3)

(en el módulo sys)

(in module sys), [1], [2]

version() (en el módulo ensurepip)

(en el módulo platform)

(método de ssl.SSLSocket)

version_info (en el módulo sqlite3)

(en el módulo sys)

version_string() (método de http.server.BaseHTTPRequestHandler)

vformat() (método de string.Formatter)

virtual

Environments

VIRTUAL_ENV

visit() (método de ast.NodeVisitor)

visitproc (tipo C)

vista de diccionario

vline() (método de curses.window)

voidcmd() (método de ftplib.FTP)

volume (atributo de zipfile.ZipInfo)

vonmisesvariate() (en el módulo random)

Índice – W

W_OK (en el módulo os)

wait() (en el módulo asyncio)

(en el módulo concurrent.futures)

(en el módulo multiprocessing.connection)

(en el módulo os)

(método de asyncio.Condition)

(método de asyncio.Event)

(método de asyncio.subprocess.Process)

(método de multiprocessing.pool.AsyncResult)

(método de subprocess.Popen)

(método de threading.Barrier)

(método de threading.Condition)

(método de threading.Event)

wait3() (en el módulo os)

wait4() (en el módulo os)

wait_closed() (método de asyncio.Server)

(método de asyncio.StreamWriter)

wait_for() (en el módulo asyncio)

(método de asyncio.Condition)

(método de threading.Condition)

wait_process() (en el módulo test.support)

wait_threads_exit() (en el módulo test.support)

waitid() (en el módulo os)

waitpid() (en el módulo os)

waitstatus_to_exitcode() (en el módulo os)

walk() (en el módulo ast)

(en el módulo os)

(método de email.message.EmailMessage)

(método de email.message.Message)

walk_packages() (en el módulo pkgutil)

walk_stack() (en el módulo traceback)

walk_tb() (en el módulo traceback)

want (atributo de doctest.Example)

warn() (en el módulo warnings)

(método de distutils.ccompiler.CCompiler)

(método de distutils.text_file.TextFile)

warn_explicit() (en el módulo warnings)

Warning, [1]

warning() (en el módulo logging)

(método de logging.Logger)

(método de xml.sax.handler.ErrorHandler)

warnings

(módulo)

WarningsRecorder (clase en test.support)

warnoptions (en el módulo sys)

wasSuccessful() (método de unittest.TestResult)

WatchedFileHandler (clase en logging.handlers)

wave (módulo)

WCONTINUED (en el módulo os)

WCOREDUMP() (en el módulo os)

WeakKeyDictionary (clase en weakref)

WeakMethod (clase en weakref)

weakref (módulo)

WeakSet (clase en weakref)

WeakValueDictionary (clase en weakref)

webbrowser (módulo)

weekday() (en el módulo calendar)

(método de datetime.date)

(método de datetime.datetime)

weekheader() (en el módulo calendar)

weibullvariate() (en el módulo random)

WEXITED (en el módulo os)

WEXITSTATUS() (en el módulo os)

wfile (atributo de http.server.BaseHTTPRequestHandler)

what() (en el módulo imghdr)

(en el módulo sndhdr)

whathdr() (en el módulo sndhdr)

whatis (pdb command)

when() (método de asyncio.TimerHandle)

where (pdb command)

which() (en el módulo shutil)

whichdb() (en el módulo dbm)

while

sentencia, [1], [2], [3]

While (clase en ast)

whitespace (atributo de shlex.shlex)

(en el módulo string)

whitespace_split (atributo de shlex.shlex)

Widget (clase en tkinter.ttk)

width (atributo de textwrap.TextWrapper)

width() (en el módulo turtle)

WIFCONTINUED() (en el módulo os)

WIFEXITED() (en el módulo os)

WIFSIGNALED() (en el módulo os)

WIFSTOPPED() (en el módulo os)

win32_edition() (en el módulo platform)

win32_is_iot() (en el módulo platform)

win32_ver() (en el módulo platform)

WinDLL (clase en ctypes)

window manager (widgets)

window() (método de curses.panel.Panel)

window_height() (en el módulo turtle)

window_width() (en el módulo turtle)

Windows

Windows ini file

WindowsError

WindowsPath (clase en pathlib)

WindowsProactorEventLoopPolicy (clase en asyncio)

WindowsRegistryFinder (clase en importlib.machinery)

WindowsSelectorEventLoopPolicy (clase en asyncio)

winerror (atributo de OSError)

WinError() (en el módulo ctypes)

WINFUNCTYPE() (en el módulo ctypes)

winreg (módulo)

WinSock

winsound (módulo)

winver (en el módulo sys)

with

sentencia, [1]

With (clase en ast)

WITH_EXCEPT_START (opcode)

with_hostmask (atributo de ipaddress.IPv4Interface)

(atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Interface)

(atributo de ipaddress.IPv6Network)

with_name() (método de pathlib.PurePath)

with_netmask (atributo de ipaddress.IPv4Interface)

(atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Interface)

(atributo de ipaddress.IPv6Network)

with_prefixlen (atributo de ipaddress.IPv4Interface)

(atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Interface)

(atributo de ipaddress.IPv6Network)

with_pymalloc() (en el módulo test.support)

with_stem() (método de pathlib.PurePath)

with_suffix() (método de pathlib.PurePath)

with_traceback() (método de BaseException)

withitem (clase en ast)

WNOHANG (en el módulo os)

WNOWAIT (en el módulo os)

wordchars (atributo de shlex.shlex)

World Wide Web, [1], [2]

wrap() (en el módulo textwrap)

(método de textwrap.TextWrapper)

wrap_bio() (método de ssl.SSLContext)

wrap_future() (en el módulo asyncio)

wrap_socket() (en el módulo ssl)

(método de ssl.SSLContext)

wrap_text() (en el módulo distutils.fancy_getopt)

wrapper() (en el módulo curses)

WrapperDescriptorType (en el módulo types)

wraps() (en el módulo functools)

WRITABLE (en el módulo tkinter)

writable() (método de asyncore.dispatcher)

(método de io.IOBase)

write() (en el módulo os)

(en el módulo turtle)

(método de asyncio.StreamWriter)

(método de asyncio.WriteTransport)

(método de code.InteractiveInterpreter)

(método de codecs.StreamWriter)

(método de configparser.ConfigParser)

(método de email.generator.BytesGenerator)

(método de email.generator.Generator)

(método de io.BufferedIOBase)

(método de io.BufferedWriter)

(método de io.RawIOBase)

(método de io.TextIOBase)

(método de mmap.mmap)

(método de ossaudiodev.oss_audio_device)

(método de ssl.MemoryBIO)

(método de ssl.SSLSocket)

(método de telnetlib.Telnet)

(método de xml.etree.ElementTree.ElementTree)

(método de zipfile.ZipFile)

write_byte() (método de mmap.mmap)

write_bytes() (método de pathlib.Path)

write_docstringdict() (en el módulo turtle)

write_eof() (método de asyncio.StreamWriter)

(método de asyncio.WriteTransport)

(método de ssl.MemoryBIO)

write_file() (en el módulo distutils.file_util)

write_history_file() (en el módulo readline)

WRITE_RESTRICTED

write_results() (método de trace.CoverageResults)

write_text() (método de pathlib.Path)

write_through (atributo de io.TextIOWrapper)

writeall() (método de ossaudiodev.oss_audio_device)

writeframes() (método de aifc.aifc)

(método de sunau.AU_write)

(método de wave.Wave_write)

writeframesraw() (método de aifc.aifc)

(método de sunau.AU_write)

(método de wave.Wave_write)

writeheader() (método de csv.DictWriter)

writelines() (método de asyncio.StreamWriter)

(método de asyncio.WriteTransport)

(método de codecs.StreamWriter)

(método de io.IOBase)

writepy() (método de zipfile.PyZipFile)

writer (atributo de formatter.formatter)

writer() (en el módulo csv)

writerow() (método de csv.csvwriter)

writerows() (método de csv.csvwriter)

writestr() (método de zipfile.ZipFile)

WriteTransport (clase en asyncio)

writev() (en el módulo os)

writexml() (método de xml.dom.minidom.Node)

writing

values

WrongDocumentErr

ws_comma (2to3 fixer)

wsgi_file_wrapper (atributo de wsgiref.handlers.BaseHandler)

wsgi_multiprocess (atributo de wsgiref.handlers.BaseHandler)

wsgi_multithread (atributo de wsgiref.handlers.BaseHandler)

wsgi_run_once (atributo de wsgiref.handlers.BaseHandler)

wsgiref (módulo)

wsgiref.handlers (módulo)

wsgiref.headers (módulo)

wsgiref.simple_server (módulo)

wsgiref.util (módulo)

wsgiref.validate (módulo)

WSGIRequestHandler (clase en wsgiref.simple_server)

WSGIServer (clase en wsgiref.simple_server)

wShowWindow (atributo de subprocess.STARTUPINFO)

WSTOPPED (en el módulo os)

WSTOPSIG() (en el módulo os)

wstring_at() (en el módulo ctypes)

WTERMSIG() (en el módulo os)

WUNTRACED (en el módulo os)

WWW, [1], [2]

server, [1]

Índice – X

X (en el módulo re)

X509 certificate

X_OK (en el módulo os)

xatom() (método de imaplib.IMAP4)

XATTR_CREATE (en el módulo os)

XATTR_REPLACE (en el módulo os)

XATTR_SIZE_MAX (en el módulo os)

xcor() (en el módulo turtle)

XDR

xdrlib (módulo)

xhdr() (método de nntplib.NNTP)

XHTML

XHTML_NAMESPACE (en el módulo xml.dom)

xml (módulo)

XML() (en el módulo xml.etree.ElementTree)

xml.dom (módulo)

xml.dom.minidom (módulo)

xml.dom.pulldom (módulo)

xml.etree.ElementInclude.default_loader() (función incorporada)

xml.etree.ElementInclude.include() (función incorporada)

xml.etree.ElementTree (módulo)

xml.parsers.expat (módulo)

xml.parsers.expat.errors (módulo)

xml.parsers.expat.model (módulo)

xml.sax (módulo)

xml.sax.handler (módulo)

xml.sax.saxutils (módulo)

xml.sax.xmlreader (módulo)

XML_ERROR_ABORTED (en el módulo xml.parsers.expat.errors)

XML_ERROR_ASYNC_ENTITY (en el módulo xml.parsers.expat.errors)

XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF (en el módulo xml.parsers.expat.errors)

XML_ERROR_BAD_CHAR_REF (en el módulo xml.parsers.expat.errors)

XML_ERROR_BINARY_ENTITY_REF (en el módulo xml.parsers.expat.errors)

XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING (en el módulo xml.parsers.expat.errors)

XML_ERROR_DUPLICATE_ATTRIBUTE (en el módulo xml.parsers.expat.errors)

XML_ERROR_ENTITY_DECLARED_IN_PE (en el módulo xml.parsers.expat.errors)

XML_ERROR_EXTERNAL_ENTITY_HANDLING (en el módulo xml.parsers.expat.errors)

XML_ERROR_FEATURE_REQUIRES_XML_DTD (en el módulo xml.parsers.expat.errors)

XML_ERROR_FINISHED (en el módulo xml.parsers.expat.errors)

XML_ERROR_INCOMPLETE_PE (en el módulo xml.parsers.expat.errors)

XML_ERROR_INCORRECT_ENCODING (en el módulo xml.parsers.expat.errors)

XML_ERROR_INVALID_TOKEN (en el módulo xml.parsers.expat.errors)

XML_ERROR_JUNK_AFTER_DOC_ELEMENT (en el módulo xml.parsers.expat.errors)

XML_ERROR_MISPLACED_XML_PI (en el módulo xml.parsers.expat.errors)

XML_ERROR_NO_ELEMENTS (en el módulo xml.parsers.expat.errors)

XML_ERROR_NO_MEMORY (en el módulo xml.parsers.expat.errors)

XML_ERROR_NOT_STANDALONE (en el módulo xml.parsers.expat.errors)

XML_ERROR_NOT_SUSPENDED (en el módulo xml.parsers.expat.errors)

XML_ERROR_PARAM_ENTITY_REF (en el módulo xml.parsers.expat.errors)

XML_ERROR_PARTIAL_CHAR (en el módulo xml.parsers.expat.errors)

XML_ERROR_PUBLICID (en el módulo xml.parsers.expat.errors)

XML_ERROR_RECURSIVE_ENTITY_REF (en el módulo xml.parsers.expat.errors)

XML_ERROR_SUSPEND_PE (en el módulo xml.parsers.expat.errors)

XML_ERROR_SUSPENDED (en el módulo xml.parsers.expat.errors)

XML_ERROR_SYNTAX (en el módulo xml.parsers.expat.errors)

XML_ERROR_TAG_MISMATCH (en el módulo xml.parsers.expat.errors)

XML_ERROR_TEXT_DECL (en el módulo xml.parsers.expat.errors)

XML_ERROR_UNBOUND_PREFIX (en el módulo xml.parsers.expat.errors)

XML_ERROR_UNCLOSED_CDATA_SECTION (en el módulo xml.parsers.expat.errors)

XML_ERROR_UNCLOSED_TOKEN (en el módulo xml.parsers.expat.errors)

XML_ERROR_UNDECLARING_PREFIX (en el módulo xml.parsers.expat.errors)

XML_ERROR_UNDEFINED_ENTITY (en el módulo xml.parsers.expat.errors)

XML_ERROR_UNEXPECTED_STATE (en el módulo xml.parsers.expat.errors)

XML_ERROR_UNKNOWN_ENCODING (en el módulo xml.parsers.expat.errors)

XML_ERROR_XML_DECL (en el módulo xml.parsers.expat.errors)

XML_NAMESPACE (en el módulo xml.dom)

xmlcharrefreplace

error handler's name

xmlcharrefreplace_errors() (en el módulo codecs)

XmlDeclHandler() (método de xml.parsers.expat.xmlparser)

XMLFilterBase (clase en xml.sax.saxutils)

XMLGenerator (clase en xml.sax.saxutils)

XMLID() (en el módulo xml.etree.ElementTree)

XMLNS_NAMESPACE (en el módulo xml.dom)

XMLParser (clase en xml.etree.ElementTree)

XMLParserType (en el módulo xml.parsers.expat)

XMLPullParser (clase en xml.etree.ElementTree)

XMLReader (clase en xml.sax.xmlreader)

xmlrpc.client (módulo)

xmlrpc.server (módulo)

xor

bitwise

xor() (en el módulo operator)

xover() (método de nntplib.NNTP)

xrange (2to3 fixer)

xreadlines (2to3 fixer)

xview() (método de tkinter.ttk.Treeview)

Índice – Y

ycor() (en el módulo turtle)

year (atributo de datetime.date)

(atributo de datetime.datetime)

Year 2038

yeardatescalendar() (método de calendar.Calendar)

yeardays2calendar() (método de calendar.Calendar)

yeardayscalendar() (método de calendar.Calendar)

YESEXPR (en el módulo locale)

yield

examples

expression

palabra clave

sentencia

yield from (in What's New)

Yield (clase en ast)

YIELD_FROM (opcode)

YIELD_VALUE (opcode)

YieldFrom (clase en ast)

yiq_to_rgb() (en el módulo colorsys)

yview() (método de tkinter.ttk.Treeview)

Índice – Z

Zen de Python

ZeroDivisionError

excepción

zfill() (método de bytearray)

(método de bytes)

(método de str)

zip (2to3 fixer)

zip() (función incorporada)

ZIP_BZIP2 (en el módulo zipfile)

ZIP_DEFLATED (en el módulo zipfile)

zip_longest() (en el módulo itertools)

ZIP_LZMA (en el módulo zipfile)

ZIP_STORED (en el módulo zipfile)

zipapp (módulo)

zipapp command line option

--compress

--help

--info

--main=<mainfn>

--output=<output>

--python=<interpreter>

-c

-h

-m <mainfn>

-o <output>

-p <interpreter>

ZipFile (clase en zipfile)

zipfile (módulo)

zipfile command line option

--create <zipfile> <source1> ... <sourceN>

--extract <zipfile> <output_dir>

--list <zipfile>

--test <zipfile>

-c <zipfile> <source1> ... <sourceN>

-e <zipfile> <output_dir>

-l <zipfile>

-t <zipfile>

zipimport (módulo)

zipimporter (clase en zipimport)

ZipImportError

ZipInfo (clase en zipfile)

zlib (módulo)

ZLIB_RUNTIME_VERSION (en el módulo zlib)

ZLIB_VERSION (en el módulo zlib)

ZoneInfo (clase en zoneinfo)

zoneinfo (módulo)

ZoneInfoNotFoundError

zscore() (método de statistics.NormalDist)

Índice – _

_ (underscore)

gettext

in numeric literal, [1]

in string formatting

_, identifiers

__, identifiers

__abs__() (en el módulo operator)

(método de object)

__add__() (en el módulo operator)

(método de object)

__aenter__() (método de object)

__aexit__() (método de object)

__aiter__() (método de object)

__all__

(optional module attribute)

(package variable)

__and__() (en el módulo operator)

(método de object)

__anext__() (método de agen)

(método de object)

__annotations__ (class attribute)

(function attribute)

(module attribute)

__args__ (atributo de genericalias)

__await__() (método de object)

__bases__ (atributo de class)

(class attribute)

__bool__() (método de object)

(object method)

__breakpointhook__ (en el módulo sys)

__bytes__() (método de email.message.EmailMessage)

(método de email.message.Message)

(método de object)

__cached__

__call__() (método de email.headerregistry.HeaderRegistry)

(método de object)

(método de weakref.finalize)

(object method)

__callback__ (atributo de weakref.ref)

__cause__ (atributo de traceback.TracebackException)

(exception attribute)

__ceil__() (método de fractions.Fraction)

(método de object)

__class__ (atributo de instance)

(atributo de unittest.mock.Mock)

(instance attribute)

(method cell)

(module attribute)

__class_getitem__() (método de clase de object)

__classcell__ (class namespace entry)

__closure__ (function attribute)

__code__ (function attribute)

(function object attribute)

__complex__() (método de object)

__concat__() (en el módulo operator)

__contains__() (en el módulo operator)

(método de email.message.EmailMessage)

(método de email.message.Message)

(método de mailbox.Mailbox)

(método de object)

__context__ (atributo de traceback.TracebackException)

(exception attribute)

__copy__() (copy protocol)

__debug__

(variable incorporada)

__deepcopy__() (copy protocol)

__defaults__ (function attribute)

__del__() (método de io.IOBase)

(método de object)

__delattr__() (método de object)

__delete__() (método de object)

__delitem__() (en el módulo operator)

(método de email.message.EmailMessage)

(método de email.message.Message)

(método de mailbox.Mailbox)

(método de mailbox.MH)

(método de object)

__dict__ (atributo de object)

(class attribute)

(function attribute)

(instance attribute)

(module attribute), [1]

__dir__ (module attribute)

__dir__() (método de object)

(método de unittest.mock.Mock)

__displayhook__ (en el módulo sys)

__divmod__() (método de object)

__doc__ (atributo de types.ModuleType)

(class attribute)

(function attribute)

(method attribute)

(module attribute), [1]

__enter__() (método de contextmanager)

(método de object)

(método de winreg.PyHKEY)

__eq__() (en el módulo operator)

(instance method)

(método de email.charset.Charset)

(método de email.header.Header)

(método de memoryview)

(método de object)

__excepthook__ (en el módulo sys)

__exit__() (método de contextmanager)

(método de object)

(método de winreg.PyHKEY)

__file__

(module attribute), [1], [2]

__float__() (método de object)

__floor__() (método de fractions.Fraction)

(método de object)

__floordiv__() (en el módulo operator)

(método de object)

__format__

__format__() (método de datetime.date)

(método de datetime.datetime)

(método de datetime.time)

(método de ipaddress.IPv4Address)

(método de ipaddress.IPv6Address)

(método de object)

__fspath__() (método de os.PathLike)

__func__ (method attribute)

__future__

future statement

__future__ (módulo)

__ge__() (en el módulo operator)

(instance method)

(método de object)

__get__() (método de object)

__getattr__ (module attribute)

__getattr__() (método de object)

__getattribute__() (método de object)

__getitem__() (en el módulo operator)

(mapping object method)

(método de email.headerregistry.HeaderRegistry)

(método de email.message.EmailMessage)

(método de email.message.Message)

(método de mailbox.Mailbox)

(método de object)

(método de re.Match)

__getnewargs__() (método de object)

__getnewargs_ex__() (método de object)

__getstate__() (copy protocol)

(método de object)

__globals__ (function attribute)

__gt__() (en el módulo operator)

(instance method)

(método de object)

__hash__() (método de object)

__iadd__() (en el módulo operator)

(método de object)

__iand__() (en el módulo operator)

(método de object)

__iconcat__() (en el módulo operator)

__ifloordiv__() (en el módulo operator)

(método de object)

__ilshift__() (en el módulo operator)

(método de object)

__imatmul__() (en el módulo operator)

(método de object)

__imod__() (en el módulo operator)

(método de object)

__import__

función incorporada

__import__() (en el módulo importlib)

(función incorporada)

__imul__() (en el módulo operator)

(método de object)

__index__() (en el módulo operator)

(método de object)

__init__() (método de difflib.HtmlDiff)

(método de logging.Handler)

(método de logging.logging.Formatter)

(método de object)

__init_subclass__() (método de clase de object)

__instancecheck__() (método de class)

__int__() (método de object)

__interactivehook__ (en el módulo sys)

__inv__() (en el módulo operator)

__invert__() (en el módulo operator)

(método de object)

__ior__() (en el módulo operator)

(método de object)

__ipow__() (en el módulo operator)

(método de object)

__irshift__() (en el módulo operator)

(método de object)

__isub__() (en el módulo operator)

(método de object)

__iter__() (método de container)

(método de iterator)

(método de mailbox.Mailbox)

(método de object)

(método de unittest.TestSuite)

__itruediv__() (en el módulo operator)

(método de object)

__ixor__() (en el módulo operator)

(método de object)

__kwdefaults__ (function attribute)

__le__() (en el módulo operator)

(instance method)

(método de object)

__len__() (mapping object method)

(método de email.message.EmailMessage)

(método de email.message.Message)

(método de mailbox.Mailbox)

(método de object)

__length_hint__() (método de object)

__loader__

(atributo de types.ModuleType)

(module attribute)

__lshift__() (en el módulo operator)

(método de object)

__lt__() (en el módulo operator)

(instance method)

(método de object)

__main__

módulo, [1], [2], [3], [4], [5], [6], [7]

__main__ (módulo)

__matmul__() (en el módulo operator)

(método de object)

__missing__()

(método de collections.defaultdict)

(método de object)

__mod__() (en el módulo operator)

(método de object)

__module__ (class attribute)

(function attribute)

(method attribute)

__mro__ (atributo de class)

__mul__() (en el módulo operator)

(método de object)

__name__

(atributo de definition)

(atributo de types.ModuleType)

(class attribute)

(function attribute)

(method attribute)

(module attribute), [1], [2]

__ne__() (en el módulo operator)

(instance method)

(método de email.charset.Charset)

(método de email.header.Header)

(método de object)

__neg__() (en el módulo operator)

(método de object)

__new__() (método de object)

__next__() (método de csv.csvreader)

(método de generator)

(método de iterator)

__not__() (en el módulo operator)

__optional_keys__ (atributo de typing.TypedDict)

__or__() (en el módulo operator)

(método de object)

__origin__ (atributo de genericalias)

__package__

(atributo de types.ModuleType)

(module attribute)

__parameters__ (atributo de genericalias)

__path__

__pos__() (en el módulo operator)

(método de object)

__pow__() (en el módulo operator)

(método de object)

__prepare__ (metaclass method)

__qualname__ (atributo de definition)

__radd__() (método de object)

__rand__() (método de object)

__rdivmod__() (método de object)

__reduce__() (método de object)

__reduce_ex__() (método de object)

__repr__() (método de multiprocessing.managers.BaseProxy)

(método de netrc.netrc)

(método de object)

__required_keys__ (atributo de typing.TypedDict)

__reversed__() (método de object)

__rfloordiv__() (método de object)

__rlshift__() (método de object)

__rmatmul__() (método de object)

__rmod__() (método de object)

__rmul__() (método de object)

__ror__() (método de object)

__round__() (método de fractions.Fraction)

(método de object)

__rpow__() (método de object)

__rrshift__() (método de object)

__rshift__() (en el módulo operator)

(método de object)

__rsub__() (método de object)

__rtruediv__() (método de object)

__rxor__() (método de object)

__self__ (method attribute)

__set__() (método de object)

__set_name__() (método de object)

__setattr__() (método de object)

__setitem__() (en el módulo operator)

(método de email.message.EmailMessage)

(método de email.message.Message)

(método de mailbox.Mailbox)

(método de mailbox.Maildir)

(método de object)

__setstate__() (copy protocol)

(método de object)

__slots__

__spec__

(atributo de types.ModuleType)

__stderr__ (en el módulo sys)

__stdin__ (en el módulo sys)

__stdout__ (en el módulo sys)

__str__() (método de datetime.date)

(método de datetime.datetime)

(método de datetime.time)

(método de email.charset.Charset)

(método de email.header.Header)

(método de email.headerregistry.Address)

(método de email.headerregistry.Group)

(método de email.message.EmailMessage)

(método de email.message.Message)

(método de multiprocessing.managers.BaseProxy)

(método de object)

__sub__() (en el módulo operator)

(método de object)

__subclasscheck__() (método de class)

__subclasses__() (método de class)

__subclasshook__() (método de abc.ABCMeta)

__suppress_context__ (atributo de traceback.TracebackException)

__total__ (atributo de typing.TypedDict)

__traceback__ (exception attribute)

__truediv__() (en el módulo operator)

(método de importlib.abc.Traversable)

(método de object)

__trunc__() (método de object)

__unraisablehook__ (en el módulo sys)

__xor__() (en el módulo operator)

(método de object)

_anonymous_ (atributo de ctypes.Structure)

_asdict() (método de collections.somenamedtuple)

_b_base_ (atributo de ctypes._CData)

_b_needsfree_ (atributo de ctypes._CData)

_callmethod() (método de multiprocessing.managers.BaseProxy)

_CData (clase en ctypes)

_clear_type_cache() (en el módulo sys)

_current_frames() (en el módulo sys)

_debugmallocstats() (en el módulo sys)

_enablelegacywindowsfsencoding() (en el módulo sys)

_exit() (en el módulo os)

_field_defaults (atributo de collections.somenamedtuple)

_fields (atributo de ast.AST)

(atributo de collections.somenamedtuple)

_fields_ (atributo de ctypes.Structure)

_flush() (método de wsgiref.handlers.BaseHandler)

_frozen (tipo C)

_FuncPtr (clase en ctypes)

_get_child_mock() (método de unittest.mock.Mock)

_getframe() (en el módulo sys)

_getvalue() (método de multiprocessing.managers.BaseProxy)

_handle (atributo de ctypes.PyDLL)

_inittab (tipo C)

_length_ (atributo de ctypes.Array)

_locale

módulo

_make() (método de clase de collections.somenamedtuple)

_makeResult() (método de unittest.TextTestRunner)

_name (atributo de ctypes.PyDLL)

_objects (atributo de ctypes._CData)

_pack_ (atributo de ctypes.Structure)

_parse() (método de gettext.NullTranslations)

_Pointer (clase en ctypes)

_Py_c_diff (función C)

_Py_c_neg (función C)

_Py_c_pow (función C)

_Py_c_prod (función C)

_Py_c_quot (función C)

_Py_c_sum (función C)

_Py_InitializeMain (función C)

_Py_NoneStruct (variable C)

_PyBytes_Resize (función C)

_PyCFunctionFast (tipo C)

_PyCFunctionFastWithKeywords (tipo C)

_PyFrameEvalFunction (tipo C)

_PyInterpreterState_GetEvalFrameFunc (función C)

_PyInterpreterState_SetEvalFrameFunc (función C)

_PyObject_New (función C)

_PyObject_NewVar (función C)

_PyTuple_Resize (función C)

_replace() (método de collections.somenamedtuple)

_setroot() (método de xml.etree.ElementTree.ElementTree)

_SimpleCData (clase en ctypes)

_structure() (en el módulo email.iterators)

_thread

módulo

_thread (módulo)

_type_ (atributo de ctypes._Pointer)

(atributo de ctypes.Array)

_write() (método de wsgiref.handlers.BaseHandler)

_xoptions (en el módulo sys)

Índice

Símbolos | _ | A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

Símbolos

! (exclamation)

in a command interpreter

in curses module

in formatted string literal

in glob-style wildcards, [1]

in string formatting

in struct format strings

! (pdb command)

!=

operador, [1]

" (double quote)

string literal

"""

string literal

# (hash)

comment, [1], [2]

in doctests

in printf-style formatting, [1]

in regular expressions

in string formatting

source encoding declaration

$ (dollar)

environment variables expansion

in regular expressions

in template strings

interpolation in configuration files

% (percent)

datetime format, [1], [2]

environment variables expansion (Windows), [1]

interpolation in configuration files

operador, [1]

printf-style formatting, [1]

%=

augmented assignment

& (ampersand)

operador, [1]

&=

augmented assignment

' (single quote)

string literal

'''

string literal

() (parentheses)

call

class definition

function definition

generator expression

in assignment target list

in printf-style formatting, [1]

in regular expressions

tuple display

(?

in regular expressions

(?!

in regular expressions

(?#

in regular expressions

(?:

in regular expressions

(?<!

in regular expressions

(?<=

in regular expressions

(?=

in regular expressions

(?P<

in regular expressions

(?P=

in regular expressions

* (asterisk)

function definition

import statement

in argparse module

in assignment target list

in AST grammar

in expression lists

in function calls, [1]

in glob-style wildcards, [1]

in printf-style formatting, [1]

in regular expressions

operador, [1]

**

function definition

in dictionary displays

in function calls, [1]

in glob-style wildcards

operador, [1]

**=

augmented assignment

*=

augmented assignment

*?

in regular expressions

+ (plus)

binary operator, [1]

in argparse module

in doctests

in printf-style formatting, [1]

in regular expressions

in string formatting

unary operator, [1]

+=

augmented assignment

+?

in regular expressions

, (comma)

argument list

expression list, [1], [2], [3], [4]

identifier list, [1]

import statement

in dictionary displays

in string formatting

in target list

parameter list

slicing

with statement

- (minus)

binary operator, [1]

in doctests

in glob-style wildcards, [1]

in printf-style formatting, [1]

in regular expressions

in string formatting

unary operator, [1]

--annotate

pickletools command line option

--best

gzip command line option

--buffer

unittest command line option

--catch

unittest command line option

--check-hash-based-pycs default|always|never

command line option

--compact

json.tool command line option

--compress

zipapp command line option

--count

trace command line option

--coverdir=<dir>

trace command line option

--create <tarfile> <source1> ... <sourceN>

tarfile command line option

--create <zipfile> <source1> ... <sourceN>

zipfile command line option

--decompress

gzip command line option

--details

inspect command line option

--exact

tokenize command line option

--extract <tarfile> [<output_dir>]

tarfile command line option

--extract <zipfile> <output_dir>

zipfile command line option

--failfast

unittest command line option

--fast

gzip command line option

--file=<file>

trace command line option

--filter <filtername>

tarfile command line option

--hardlink-dupes

compileall command line option

--help

ast command line option

command line option

gzip command line option

json.tool command line option

timeit command line option

tokenize command line option

trace command line option

zipapp command line option

--ignore-dir=<dir>

trace command line option

--ignore-module=<mod>

trace command line option

--include-attributes

ast command line option

--indent

json.tool command line option

--indent <indent>

ast command line option

--indentlevel=<num>

pickletools command line option

--info

zipapp command line option

--invalidation-mode [timestamp|checked-hash|unchecked-hash]

compileall command line option

--json-lines

json.tool command line option

--list <tarfile>

tarfile command line option

--list <zipfile>

zipfile command line option

--listfuncs

trace command line option

--locals

unittest command line option

--main=<mainfn>

zipapp command line option

--memo

pickletools command line option

--missing

trace command line option

--mode <mode>

ast command line option

--no-ensure-ascii

json.tool command line option

--no-indent

json.tool command line option

--no-report

trace command line option

--no-type-comments

ast command line option

--number=N

timeit command line option

--output=<file>

pickletools command line option

--output=<output>

zipapp command line option

--pattern pattern

unittest-discover command line option

--preamble=<preamble>

pickletools command line option

--process

timeit command line option

--python=<interpreter>

zipapp command line option

--repeat=N

timeit command line option

--report

trace command line option

--setup=S

timeit command line option

--sort-keys

json.tool command line option

--start-directory directory

unittest-discover command line option

--summary

trace command line option

--tab

json.tool command line option

--test <tarfile>

tarfile command line option

--test <zipfile>

zipfile command line option

--timing

trace command line option

--top-level-directory directory

unittest-discover command line option

--trace

trace command line option

--trackcalls

trace command line option

--unit=U

timeit command line option

--user-base

site command line option

--user-site

site command line option

--verbose

tarfile command line option

timeit command line option

unittest-discover command line option

--version

command line option

trace command line option

-=

augmented assignment

->

function annotations, [1]

-?

command line option

-a

ast command line option

pickletools command line option

-B

command line option

-b

command line option

compileall command line option

unittest command line option

-C

trace command line option

-c

trace command line option

unittest command line option

zipapp command line option

-c <command>

command line option

-c <tarfile> <source1> ... <sourceN>

tarfile command line option

-c <zipfile> <source1> ... <sourceN>

zipfile command line option

-d

command line option

gzip command line option

-d destdir

compileall command line option

-E

command line option

-e

tokenize command line option

-e <tarfile> [<output_dir>]

tarfile command line option

-e <zipfile> <output_dir>

zipfile command line option

-e dir

compileall command line option

-f

compileall command line option

trace command line option

unittest command line option

-g

trace command line option

-h

ast command line option

command line option

gzip command line option

json.tool command line option

timeit command line option

tokenize command line option

zipapp command line option

-I

command line option

-i

command line option

-i <indent>

ast command line option

-i list

compileall command line option

-J

command line option

-j N

compileall command line option

-k

unittest command line option

-l

compileall command line option

pickletools command line option

trace command line option

-l <tarfile>

tarfile command line option

-l <zipfile>

zipfile command line option

-m

pickletools command line option

trace command line option

-m <mainfn>

zipapp command line option

-m <mode>

ast command line option

-m <module-name>

command line option

-n N

timeit command line option

-O

command line option

-o

pickletools command line option

-o <output>

zipapp command line option

-o level

compileall command line option

-OO

command line option

-p

pickletools command line option

timeit command line option

unittest-discover command line option

-p <interpreter>

zipapp command line option

-p prepend_prefix

compileall command line option

-q

command line option

compileall command line option

-R

command line option

trace command line option

-r

compileall command line option

trace command line option

-r N

timeit command line option

-S

command line option

-s

command line option

trace command line option

unittest-discover command line option

-s S

timeit command line option

-s strip_prefix

compileall command line option

-T

trace command line option

-t

trace command line option

unittest-discover command line option

-t <tarfile>

tarfile command line option

-t <zipfile>

zipfile command line option

-u

command line option

timeit command line option

-V

command line option

-v

command line option

tarfile command line option

timeit command line option

unittest-discover command line option

-W arg

command line option

-X

command line option

-x

command line option

-x regex

compileall command line option

. (dot)

attribute reference

in glob-style wildcards

in numeric literal

in pathnames, [1]

in printf-style formatting, [1]

in regular expressions

in string formatting

in Tkinter

..

in pathnames

...

ellipsis literal, [1], [2]

in doctests

interpreter prompt, [1]

placeholder, [1], [2]

.ini

file

.pdbrc

file

/ (slash)

function definition

in pathnames, [1]

operador, [1]

//

operador, [1]

//=

augmented assignment

/=

augmented assignment

0b

integer literal

0o

integer literal

0x

integer literal

2-digit years

2to3

: (colon)

annotated variable

compound statement, [1], [2], [3], [4], [5], [6]

function annotations, [1]

in dictionary expressions

in formatted string literal

in SQL statements

in string formatting

lambda expression

path separator (POSIX)

slicing

; (semicolon), [1]

< (less)

in string formatting

in struct format strings

operador, [1]

<<

operador, [1]

<<=

augmented assignment

<=

operador, [1]

<BLANKLINE>

= (equals)

assignment statement

class definition

for help in debugging using string literals

function definition

in function calls

in string formatting

in struct format strings

==

operador, [1]

> (greater)

in string formatting

in struct format strings

operador, [1]

>=

operador, [1]

>>

operador, [1]

>>=

augmented assignment

>>>

interpreter prompt, [1]

? (question mark)

in a command interpreter

in argparse module

in AST grammar

in glob-style wildcards, [1]

in regular expressions

in SQL statements

in struct format strings, [1]

replacement character

??

in regular expressions

@ (at)

class definition

function definition

in struct format strings

operador

[] (square brackets)

in assignment target list

in glob-style wildcards, [1]

in regular expressions

in string formatting

list expression

subscription

\ (backslash)

escape sequence, [1]

in pathnames (Windows)

in regular expressions, [1], [2]

\\

escape sequence

in regular expressions

\A

in regular expressions

\a

escape sequence

in regular expressions

\B

in regular expressions

\b

escape sequence

in regular expressions, [1]

\D

in regular expressions

\d

in regular expressions

\f

escape sequence

in regular expressions

\g

in regular expressions

\N

escape sequence, [1]

in regular expressions

\n

escape sequence

in regular expressions

\r

escape sequence

in regular expressions

\S

in regular expressions

\s

in regular expressions

\t

escape sequence

in regular expressions

\U

escape sequence, [1]

in regular expressions

\u

escape sequence, [1]

in regular expressions

\v

escape sequence

in regular expressions

\W

in regular expressions

\w

in regular expressions

\x

escape sequence, [1]

in regular expressions

\Z

in regular expressions

^ (caret)

in curses module

in regular expressions, [1]

in string formatting

marker, [1]

operador, [1]

^=

augmented assignment

{} (curly brackets)

dictionary expression

in formatted string literal

in regular expressions

in string formatting

set expression

| (vertical bar)

in regular expressions

operador, [1]

|=

augmented assignment

~ (tilde)

home directory expansion

operador, [1]

_

_ (underscore)

gettext

in numeric literal, [1]

in string formatting

_, identifiers

__, identifiers

__abs__() (en el módulo operator)

(método de object)

__add__() (en el módulo operator)

(método de object)

__aenter__() (método de object)

__aexit__() (método de object)

__aiter__() (método de object)

__all__

(optional module attribute)

(package variable)

__and__() (en el módulo operator)

(método de object)

__anext__() (método de agen)

(método de object)

__annotations__ (class attribute)

(function attribute)

(module attribute)

__args__ (atributo de genericalias)

__await__() (método de object)

__bases__ (atributo de class)

(class attribute)

__bool__() (método de object)

(object method)

__breakpointhook__ (en el módulo sys)

__bytes__() (método de email.message.EmailMessage)

(método de email.message.Message)

(método de object)

__cached__

__call__() (método de email.headerregistry.HeaderRegistry)

(método de object)

(método de weakref.finalize)

(object method)

__callback__ (atributo de weakref.ref)

__cause__ (atributo de traceback.TracebackException)

(exception attribute)

__ceil__() (método de fractions.Fraction)

(método de object)

__class__ (atributo de instance)

(atributo de unittest.mock.Mock)

(instance attribute)

(method cell)

(module attribute)

__class_getitem__() (método de clase de object)

__classcell__ (class namespace entry)

__closure__ (function attribute)

__code__ (function attribute)

(function object attribute)

__complex__() (método de object)

__concat__() (en el módulo operator)

__contains__() (en el módulo operator)

(método de email.message.EmailMessage)

(método de email.message.Message)

(método de mailbox.Mailbox)

(método de object)

__context__ (atributo de traceback.TracebackException)

(exception attribute)

__copy__() (copy protocol)

__debug__

(variable incorporada)

__deepcopy__() (copy protocol)

__defaults__ (function attribute)

__del__() (método de io.IOBase)

(método de object)

__delattr__() (método de object)

__delete__() (método de object)

__delitem__() (en el módulo operator)

(método de email.message.EmailMessage)

(método de email.message.Message)

(método de mailbox.Mailbox)

(método de mailbox.MH)

(método de object)

__dict__ (atributo de object)

(class attribute)

(function attribute)

(instance attribute)

(module attribute), [1]

__dir__ (module attribute)

__dir__() (método de object)

(método de unittest.mock.Mock)

__displayhook__ (en el módulo sys)

__divmod__() (método de object)

__doc__ (atributo de types.ModuleType)

(class attribute)

(function attribute)

(method attribute)

(module attribute), [1]

__enter__() (método de contextmanager)

(método de object)

(método de winreg.PyHKEY)

__eq__() (en el módulo operator)

(instance method)

(método de email.charset.Charset)

(método de email.header.Header)

(método de memoryview)

(método de object)

__excepthook__ (en el módulo sys)

__exit__() (método de contextmanager)

(método de object)

(método de winreg.PyHKEY)

__file__

(module attribute), [1], [2]

__float__() (método de object)

__floor__() (método de fractions.Fraction)

(método de object)

__floordiv__() (en el módulo operator)

(método de object)

__format__

__format__() (método de datetime.date)

(método de datetime.datetime)

(método de datetime.time)

(método de ipaddress.IPv4Address)

(método de ipaddress.IPv6Address)

(método de object)

__fspath__() (método de os.PathLike)

__func__ (method attribute)

__future__

future statement

__future__ (módulo)

__ge__() (en el módulo operator)

(instance method)

(método de object)

__get__() (método de object)

__getattr__ (module attribute)

__getattr__() (método de object)

__getattribute__() (método de object)

__getitem__() (en el módulo operator)

(mapping object method)

(método de email.headerregistry.HeaderRegistry)

(método de email.message.EmailMessage)

(método de email.message.Message)

(método de mailbox.Mailbox)

(método de object)

(método de re.Match)

__getnewargs__() (método de object)

__getnewargs_ex__() (método de object)

__getstate__() (copy protocol)

(método de object)

__globals__ (function attribute)

__gt__() (en el módulo operator)

(instance method)

(método de object)

__hash__() (método de object)

__iadd__() (en el módulo operator)

(método de object)

__iand__() (en el módulo operator)

(método de object)

__iconcat__() (en el módulo operator)

__ifloordiv__() (en el módulo operator)

(método de object)

__ilshift__() (en el módulo operator)

(método de object)

__imatmul__() (en el módulo operator)

(método de object)

__imod__() (en el módulo operator)

(método de object)

__import__

función incorporada

__import__() (en el módulo importlib)

(función incorporada)

__imul__() (en el módulo operator)

(método de object)

__index__() (en el módulo operator)

(método de object)

__init__() (método de difflib.HtmlDiff)

(método de logging.Handler)

(método de logging.logging.Formatter)

(método de object)

__init_subclass__() (método de clase de object)

__instancecheck__() (método de class)

__int__() (método de object)

__interactivehook__ (en el módulo sys)

__inv__() (en el módulo operator)

__invert__() (en el módulo operator)

(método de object)

__ior__() (en el módulo operator)

(método de object)

__ipow__() (en el módulo operator)

(método de object)

__irshift__() (en el módulo operator)

(método de object)

__isub__() (en el módulo operator)

(método de object)

__iter__() (método de container)

(método de iterator)

(método de mailbox.Mailbox)

(método de object)

(método de unittest.TestSuite)

__itruediv__() (en el módulo operator)

(método de object)

__ixor__() (en el módulo operator)

(método de object)

__kwdefaults__ (function attribute)

__le__() (en el módulo operator)

(instance method)

(método de object)

__len__() (mapping object method)

(método de email.message.EmailMessage)

(método de email.message.Message)

(método de mailbox.Mailbox)

(método de object)

__length_hint__() (método de object)

__loader__

(atributo de types.ModuleType)

(module attribute)

__lshift__() (en el módulo operator)

(método de object)

__lt__() (en el módulo operator)

(instance method)

(método de object)

__main__

módulo, [1], [2], [3], [4], [5], [6], [7]

__main__ (módulo)

__matmul__() (en el módulo operator)

(método de object)

__missing__()

(método de collections.defaultdict)

(método de object)

__mod__() (en el módulo operator)

(método de object)

__module__ (class attribute)

(function attribute)

(method attribute)

__mro__ (atributo de class)

__mul__() (en el módulo operator)

(método de object)

__name__

(atributo de definition)

(atributo de types.ModuleType)

(class attribute)

(function attribute)

(method attribute)

(module attribute), [1], [2]

__ne__() (en el módulo operator)

(instance method)

(método de email.charset.Charset)

(método de email.header.Header)

(método de object)

__neg__() (en el módulo operator)

(método de object)

__new__() (método de object)

__next__() (método de csv.csvreader)

(método de generator)

(método de iterator)

__not__() (en el módulo operator)

__optional_keys__ (atributo de typing.TypedDict)

__or__() (en el módulo operator)

(método de object)

__origin__ (atributo de genericalias)

__package__

(atributo de types.ModuleType)

(module attribute)

__parameters__ (atributo de genericalias)

__path__

__pos__() (en el módulo operator)

(método de object)

__pow__() (en el módulo operator)

(método de object)

__prepare__ (metaclass method)

__qualname__ (atributo de definition)

__radd__() (método de object)

__rand__() (método de object)

__rdivmod__() (método de object)

__reduce__() (método de object)

__reduce_ex__() (método de object)

__repr__() (método de multiprocessing.managers.BaseProxy)

(método de netrc.netrc)

(método de object)

__required_keys__ (atributo de typing.TypedDict)

__reversed__() (método de object)

__rfloordiv__() (método de object)

__rlshift__() (método de object)

__rmatmul__() (método de object)

__rmod__() (método de object)

__rmul__() (método de object)

__ror__() (método de object)

__round__() (método de fractions.Fraction)

(método de object)

__rpow__() (método de object)

__rrshift__() (método de object)

__rshift__() (en el módulo operator)

(método de object)

__rsub__() (método de object)

__rtruediv__() (método de object)

__rxor__() (método de object)

__self__ (method attribute)

__set__() (método de object)

__set_name__() (método de object)

__setattr__() (método de object)

__setitem__() (en el módulo operator)

(método de email.message.EmailMessage)

(método de email.message.Message)

(método de mailbox.Mailbox)

(método de mailbox.Maildir)

(método de object)

__setstate__() (copy protocol)

(método de object)

__slots__

__spec__

(atributo de types.ModuleType)

__stderr__ (en el módulo sys)

__stdin__ (en el módulo sys)

__stdout__ (en el módulo sys)

__str__() (método de datetime.date)

(método de datetime.datetime)

(método de datetime.time)

(método de email.charset.Charset)

(método de email.header.Header)

(método de email.headerregistry.Address)

(método de email.headerregistry.Group)

(método de email.message.EmailMessage)

(método de email.message.Message)

(método de multiprocessing.managers.BaseProxy)

(método de object)

__sub__() (en el módulo operator)

(método de object)

__subclasscheck__() (método de class)

__subclasses__() (método de class)

__subclasshook__() (método de abc.ABCMeta)

__suppress_context__ (atributo de traceback.TracebackException)

__total__ (atributo de typing.TypedDict)

__traceback__ (exception attribute)

__truediv__() (en el módulo operator)

(método de importlib.abc.Traversable)

(método de object)

__trunc__() (método de object)

__unraisablehook__ (en el módulo sys)

__xor__() (en el módulo operator)

(método de object)

_anonymous_ (atributo de ctypes.Structure)

_asdict() (método de collections.somenamedtuple)

_b_base_ (atributo de ctypes._CData)

_b_needsfree_ (atributo de ctypes._CData)

_callmethod() (método de multiprocessing.managers.BaseProxy)

_CData (clase en ctypes)

_clear_type_cache() (en el módulo sys)

_current_frames() (en el módulo sys)

_debugmallocstats() (en el módulo sys)

_enablelegacywindowsfsencoding() (en el módulo sys)

_exit() (en el módulo os)

_field_defaults (atributo de collections.somenamedtuple)

_fields (atributo de ast.AST)

(atributo de collections.somenamedtuple)

_fields_ (atributo de ctypes.Structure)

_flush() (método de wsgiref.handlers.BaseHandler)

_frozen (tipo C)

_FuncPtr (clase en ctypes)

_get_child_mock() (método de unittest.mock.Mock)

_getframe() (en el módulo sys)

_getvalue() (método de multiprocessing.managers.BaseProxy)

_handle (atributo de ctypes.PyDLL)

_inittab (tipo C)

_length_ (atributo de ctypes.Array)

_locale

módulo

_make() (método de clase de collections.somenamedtuple)

_makeResult() (método de unittest.TextTestRunner)

_name (atributo de ctypes.PyDLL)

_objects (atributo de ctypes._CData)

_pack_ (atributo de ctypes.Structure)

_parse() (método de gettext.NullTranslations)

_Pointer (clase en ctypes)

_Py_c_diff (función C)

_Py_c_neg (función C)

_Py_c_pow (función C)

_Py_c_prod (función C)

_Py_c_quot (función C)

_Py_c_sum (función C)

_Py_InitializeMain (función C)

_Py_NoneStruct (variable C)

_PyBytes_Resize (función C)

_PyCFunctionFast (tipo C)

_PyCFunctionFastWithKeywords (tipo C)

_PyFrameEvalFunction (tipo C)

_PyInterpreterState_GetEvalFrameFunc (función C)

_PyInterpreterState_SetEvalFrameFunc (función C)

_PyObject_New (función C)

_PyObject_NewVar (función C)

_PyTuple_Resize (función C)

_replace() (método de collections.somenamedtuple)

_setroot() (método de xml.etree.ElementTree.ElementTree)

_SimpleCData (clase en ctypes)

_structure() (en el módulo email.iterators)

_thread

módulo

_thread (módulo)

_type_ (atributo de ctypes._Pointer)

(atributo de ctypes.Array)

_write() (método de wsgiref.handlers.BaseHandler)

_xoptions (en el módulo sys)

A

A (en el módulo re)

a la espera

A-LAW, [1]

a-LAW

a2b_base64() (en el módulo binascii)

a2b_hex() (en el módulo binascii)

a2b_hqx() (en el módulo binascii)

a2b_qp() (en el módulo binascii)

a2b_uu() (en el módulo binascii)

a85decode() (en el módulo base64)

a85encode() (en el módulo base64)

ABC (clase en abc)

abc (módulo)

ABCMeta (clase en abc)

abiflags (en el módulo sys)

abort()

(en el módulo os)

(método de asyncio.DatagramTransport)

(método de asyncio.WriteTransport)

(método de ftplib.FTP)

(método de threading.Barrier)

above() (método de curses.panel.Panel)

ABOVE_NORMAL_PRIORITY_CLASS (en el módulo subprocess)

abs

función incorporada, [1]

abs() (en el módulo operator)

(función incorporada)

(método de decimal.Context)

AbsoluteLinkError

AbsolutePathError

abspath() (en el módulo os.path)

AbstractAsyncContextManager (clase en contextlib)

AbstractBasicAuthHandler (clase en urllib.request)

AbstractChildWatcher (clase en asyncio)

abstractclassmethod() (en el módulo abc)

AbstractContextManager (clase en contextlib)

AbstractDigestAuthHandler (clase en urllib.request)

AbstractEventLoop (clase en asyncio)

AbstractEventLoopPolicy (clase en asyncio)

AbstractFormatter (clase en formatter)

abstractmethod() (en el módulo abc)

abstractproperty() (en el módulo abc)

AbstractSet (clase en typing)

abstractstaticmethod() (en el módulo abc)

AbstractWriter (clase en formatter)

accept() (método de asyncore.dispatcher)

(método de multiprocessing.connection.Listener)

(método de socket.socket)

access() (en el módulo os)

accumulate() (en el módulo itertools)

aclose() (método de agen)

(método de contextlib.AsyncExitStack)

acos() (en el módulo cmath)

(en el módulo math)

acosh() (en el módulo cmath)

(en el módulo math)

acquire() (método de _thread.lock)

(método de asyncio.Condition)

(método de asyncio.Lock)

(método de asyncio.Semaphore)

(método de logging.Handler)

(método de multiprocessing.Lock)

(método de multiprocessing.RLock)

(método de threading.Condition)

(método de threading.Lock)

(método de threading.RLock)

(método de threading.Semaphore)

acquire_lock() (en el módulo imp)

action (atributo de optparse.Option)

Action (clase en argparse)

ACTIONS (atributo de optparse.Option)

active_children() (en el módulo multiprocessing)

active_count() (en el módulo threading)

actual() (método de tkinter.font.Font)

Add (clase en ast)

add() (en el módulo audioop)

(en el módulo operator)

(método de decimal.Context)

(método de frozenset)

(método de graphlib.TopologicalSorter)

(método de mailbox.Mailbox)

(método de mailbox.Maildir)

(método de msilib.RadioButtonGroup)

(método de pstats.Stats)

(método de tarfile.TarFile)

(método de tkinter.ttk.Notebook)

add_alias() (en el módulo email.charset)

add_alternative() (método de email.message.EmailMessage)

add_argument() (método de argparse.ArgumentParser)

add_argument_group() (método de argparse.ArgumentParser)

add_attachment() (método de email.message.EmailMessage)

add_cgi_vars() (método de wsgiref.handlers.BaseHandler)

add_charset() (en el módulo email.charset)

add_child_handler() (método de asyncio.AbstractChildWatcher)

add_codec() (en el módulo email.charset)

add_cookie_header() (método de http.cookiejar.CookieJar)

add_data() (en el módulo msilib)

add_dll_directory() (en el módulo os)

add_done_callback() (método de asyncio.Future)

(método de asyncio.Task)

(método de concurrent.futures.Future)

add_fallback() (método de gettext.NullTranslations)

add_file() (método de msilib.Directory)

add_flag() (método de mailbox.MaildirMessage)

(método de mailbox.mboxMessage)

(método de mailbox.MMDFMessage)

add_flowing_data() (método de formatter.formatter)

add_folder() (método de mailbox.Maildir)

(método de mailbox.MH)

add_get_handler() (método de email.contentmanager.ContentManager)

add_handler() (método de urllib.request.OpenerDirector)

add_header() (método de email.message.EmailMessage)

(método de email.message.Message)

(método de urllib.request.Request)

(método de wsgiref.headers.Headers)

add_history() (en el módulo readline)

add_hor_rule() (método de formatter.formatter)

add_include_dir() (método de distutils.ccompiler.CCompiler)

add_label() (método de mailbox.BabylMessage)

add_label_data() (método de formatter.formatter)

add_library() (método de distutils.ccompiler.CCompiler)

add_library_dir() (método de distutils.ccompiler.CCompiler)

add_line_break() (método de formatter.formatter)

add_link_object() (método de distutils.ccompiler.CCompiler)

add_literal_data() (método de formatter.formatter)

add_mutually_exclusive_group() (método de argparse.ArgumentParser)

add_option() (método de optparse.OptionParser)

add_parent() (método de urllib.request.BaseHandler)

add_password() (método de urllib.request.HTTPPasswordMgr)

(método de urllib.request.HTTPPasswordMgrWithPriorAuth)

add_reader() (método de asyncio.loop)

add_related() (método de email.message.EmailMessage)

add_runtime_library_dir() (método de distutils.ccompiler.CCompiler)

add_section() (método de configparser.ConfigParser)

(método de configparser.RawConfigParser)

add_sequence() (método de mailbox.MHMessage)

add_set_handler() (método de email.contentmanager.ContentManager)

add_signal_handler() (método de asyncio.loop)

add_stream() (en el módulo msilib)

add_subparsers() (método de argparse.ArgumentParser)

add_tables() (en el módulo msilib)

add_type() (en el módulo mimetypes)

add_unredirected_header() (método de urllib.request.Request)

add_writer() (método de asyncio.loop)

addAsyncCleanup() (método de unittest.IsolatedAsyncioTestCase)

addaudithook() (en el módulo sys)

addch() (método de curses.window)

addClassCleanup() (método de clase de unittest.TestCase)

addCleanup() (método de unittest.TestCase)

addcomponent() (método de turtle.Shape)

addError() (método de unittest.TestResult)

addExpectedFailure() (método de unittest.TestResult)

addFailure() (método de unittest.TestResult)

addfile() (método de tarfile.TarFile)

addFilter() (método de logging.Handler)

(método de logging.Logger)

addHandler() (método de logging.Logger)

addinfourl (clase en urllib.response)

addition

addLevelName() (en el módulo logging)

addModuleCleanup() (en el módulo unittest)

addnstr() (método de curses.window)

AddPackagePath() (en el módulo modulefinder)

addr (atributo de smtpd.SMTPChannel)

addr_spec (atributo de email.headerregistry.Address)

address (atributo de email.headerregistry.SingleAddressHeader)

(atributo de multiprocessing.connection.Listener)

(atributo de multiprocessing.managers.BaseManager)

Address (clase en email.headerregistry)

address_exclude() (método de ipaddress.IPv4Network)

(método de ipaddress.IPv6Network)

address_family (atributo de socketserver.BaseServer)

address_string() (método de http.server.BaseHTTPRequestHandler)

addresses (atributo de email.headerregistry.AddressHeader)

(atributo de email.headerregistry.Group)

AddressHeader (clase en email.headerregistry)

addressof() (en el módulo ctypes)

AddressValueError

addshape() (en el módulo turtle)

addsitedir() (en el módulo site)

addSkip() (método de unittest.TestResult)

addstr() (método de curses.window)

addSubTest() (método de unittest.TestResult)

addSuccess() (método de unittest.TestResult)

addTest() (método de unittest.TestSuite)

addTests() (método de unittest.TestSuite)

addTypeEqualityFunc() (método de unittest.TestCase)

addUnexpectedSuccess() (método de unittest.TestResult)

adjust_int_max_str_digits() (en el módulo test.support)

adjusted() (método de decimal.Decimal)

adler32() (en el módulo zlib)

administrador asincrónico de contexto

administrador de contextos

ADPCM, Intel/DVI

adpcm2lin() (en el módulo audioop)

AF_ALG (en el módulo socket)

AF_CAN (en el módulo socket)

AF_INET (en el módulo socket)

AF_INET6 (en el módulo socket)

AF_LINK (en el módulo socket)

AF_PACKET (en el módulo socket)

AF_QIPCRTR (en el módulo socket)

AF_RDS (en el módulo socket)

AF_UNIX (en el módulo socket)

AF_VSOCK (en el módulo socket)

aifc (módulo)

aifc() (método de aifc.aifc)

AIFF, [1]

aiff() (método de aifc.aifc)

AIFF-C, [1]

alarm() (en el módulo signal)

alaw2lin() (en el módulo audioop)

alcances anidados

ALERT_DESCRIPTION_HANDSHAKE_FAILURE (en el módulo ssl)

ALERT_DESCRIPTION_INTERNAL_ERROR (en el módulo ssl)

AlertDescription (clase en ssl)

algorithms_available (en el módulo hashlib)

algorithms_guaranteed (en el módulo hashlib)

Alias

Generic

alias (clase en ast)

(pdb command)

alias de tipos

alignment() (en el módulo ctypes)

alive (atributo de weakref.finalize)

all() (función incorporada)

all_errors (en el módulo ftplib)

all_features (en el módulo xml.sax.handler)

all_frames (atributo de tracemalloc.Filter)

all_properties (en el módulo xml.sax.handler)

all_suffixes() (en el módulo importlib.machinery)

all_tasks() (en el módulo asyncio)

allocate_lock() (en el módulo _thread)

allocfunc (tipo C)

allow_reuse_address (atributo de socketserver.BaseServer)

allowed_domains() (método de http.cookiejar.DefaultCookiePolicy)

alt() (en el módulo curses.ascii)

ALT_DIGITS (en el módulo locale)

altsep (en el módulo os)

altzone (en el módulo time)

ALWAYS_EQ (en el módulo test.support)

ALWAYS_TYPED_ACTIONS (atributo de optparse.Option)

AMPER (en el módulo token)

AMPEREQUAL (en el módulo token)

and

bitwise

operador, [1], [2]

And (clase en ast)

and_() (en el módulo operator)

AnnAssign (clase en ast)

annotated

assignment

Annotated (en el módulo typing)

annotation (atributo de inspect.Parameter)

annotations

function, [1]

announce() (método de distutils.ccompiler.CCompiler)

anonymous

function

anotación

anotación de función

anotación de variable

answer_challenge() (en el módulo multiprocessing.connection)

anticipate_failure() (en el módulo test.support)

Any (en el módulo typing)

ANY (en el módulo unittest.mock)

any() (función incorporada)

AnyStr (en el módulo typing)

apagado del intérprete

API provisional

api_version (en el módulo sys)

apilevel (en el módulo sqlite3)

apop() (método de poplib.POP3)

APPDATA

append() (método de array.array)

(método de collections.deque)

(método de email.header.Header)

(método de imaplib.IMAP4)

(método de msilib.CAB)

(método de pipes.Template)

(método de xml.etree.ElementTree.Element)

(sequence method)

append_history_file() (en el módulo readline)

appendChild() (método de xml.dom.Node)

appendleft() (método de collections.deque)

application_uri() (en el módulo wsgiref.util)

apply (2to3 fixer)

apply() (método de multiprocessing.pool.Pool)

apply_async() (método de multiprocessing.pool.Pool)

apply_defaults() (método de inspect.BoundArguments)

architecture() (en el módulo platform)

archive (atributo de zipimport.zipimporter)

archivo binario

archivo de texto

aRepr (en el módulo reprlib)

arg (clase en ast)

argparse (módulo)

args (atributo de BaseException)

(atributo de functools.partial)

(atributo de inspect.BoundArguments)

(atributo de subprocess.CompletedProcess)

(atributo de subprocess.Popen)

(pdb command)

args_from_interpreter_flags() (en el módulo test.support)

argtypes (atributo de ctypes._FuncPtr)

argument

call semantics

difference from parameter

function

function definition

ArgumentDefaultsHelpFormatter (clase en argparse)

ArgumentError

argumento

argumento nombrado

argumento posicional

ArgumentParser (clase en argparse)

arguments (atributo de inspect.BoundArguments)

(clase en ast)

argv (en el módulo sys)

(in module sys)

arithmetic

conversion

operation, binary

operation, unary

ArithmeticError

array

módulo, [1]

array (clase en array)

Array (clase en ctypes)

array (módulo)

Array() (en el módulo multiprocessing)

(en el módulo multiprocessing.sharedctypes)

(método de multiprocessing.managers.SyncManager)

arrays

arraysize (atributo de sqlite3.Cursor)

article() (método de nntplib.NNTP)

as

except clause

import statement

palabra clave, [1], [2]

with statement

as_bytes() (método de email.message.EmailMessage)

(método de email.message.Message)

as_completed() (en el módulo asyncio)

(en el módulo concurrent.futures)

as_file() (en el módulo importlib.resources)

as_integer_ratio() (método de decimal.Decimal)

(método de float)

(método de fractions.Fraction)

(método de int)

AS_IS (en el módulo formatter)

as_posix() (método de pathlib.PurePath)

as_string() (método de email.message.EmailMessage)

(método de email.message.Message)

as_tuple() (método de decimal.Decimal)

as_uri() (método de pathlib.PurePath)

ASCII, [1]

ascii

(en el módulo re)

función incorporada

ascii() (en el módulo curses.ascii)

(función incorporada)

ascii_letters (en el módulo string)

ascii_lowercase (en el módulo string)

ascii_uppercase (en el módulo string)

asctime() (en el módulo time)

asdict() (en el módulo dataclasses)

asend() (método de agen)

asin() (en el módulo cmath)

(en el módulo math)

asinh() (en el módulo cmath)

(en el módulo math)

askcolor() (en el módulo tkinter.colorchooser)

askdirectory() (en el módulo tkinter.filedialog)

askfloat() (en el módulo tkinter.simpledialog)

askinteger() (en el módulo tkinter.simpledialog)

askokcancel() (en el módulo tkinter.messagebox)

askopenfile() (en el módulo tkinter.filedialog)

askopenfilename() (en el módulo tkinter.filedialog)

askopenfilenames() (en el módulo tkinter.filedialog)

askopenfiles() (en el módulo tkinter.filedialog)

askquestion() (en el módulo tkinter.messagebox)

askretrycancel() (en el módulo tkinter.messagebox)

asksaveasfile() (en el módulo tkinter.filedialog)

asksaveasfilename() (en el módulo tkinter.filedialog)

askstring() (en el módulo tkinter.simpledialog)

askyesno() (en el módulo tkinter.messagebox)

askyesnocancel() (en el módulo tkinter.messagebox)

assert

sentencia, [1]

Assert (clase en ast)

assert_any_await() (método de unittest.mock.AsyncMock)

assert_any_call() (método de unittest.mock.Mock)

assert_awaited() (método de unittest.mock.AsyncMock)

assert_awaited_once() (método de unittest.mock.AsyncMock)

assert_awaited_once_with() (método de unittest.mock.AsyncMock)

assert_awaited_with() (método de unittest.mock.AsyncMock)

assert_called() (método de unittest.mock.Mock)

assert_called_once() (método de unittest.mock.Mock)

assert_called_once_with() (método de unittest.mock.Mock)

assert_called_with() (método de unittest.mock.Mock)

assert_has_awaits() (método de unittest.mock.AsyncMock)

assert_has_calls() (método de unittest.mock.Mock)

assert_line_data() (método de formatter.formatter)

assert_not_awaited() (método de unittest.mock.AsyncMock)

assert_not_called() (método de unittest.mock.Mock)

assert_python_failure() (en el módulo test.support.script_helper)

assert_python_ok() (en el módulo test.support.script_helper)

assertAlmostEqual() (método de unittest.TestCase)

assertCountEqual() (método de unittest.TestCase)

assertDictEqual() (método de unittest.TestCase)

assertEqual() (método de unittest.TestCase)

assertFalse() (método de unittest.TestCase)

assertGreater() (método de unittest.TestCase)

assertGreaterEqual() (método de unittest.TestCase)

assertIn() (método de unittest.TestCase)

assertInBytecode() (método de test.support.bytecode_helper.BytecodeTestCase)

AssertionError

excepción

assertions

debugging

assertIs() (método de unittest.TestCase)

assertIsInstance() (método de unittest.TestCase)

assertIsNone() (método de unittest.TestCase)

assertIsNot() (método de unittest.TestCase)

assertIsNotNone() (método de unittest.TestCase)

assertLess() (método de unittest.TestCase)

assertLessEqual() (método de unittest.TestCase)

assertListEqual() (método de unittest.TestCase)

assertLogs() (método de unittest.TestCase)

assertMultiLineEqual() (método de unittest.TestCase)

assertNotAlmostEqual() (método de unittest.TestCase)

assertNotEqual() (método de unittest.TestCase)

assertNotIn() (método de unittest.TestCase)

assertNotInBytecode() (método de test.support.bytecode_helper.BytecodeTestCase)

assertNotIsInstance() (método de unittest.TestCase)

assertNotRegex() (método de unittest.TestCase)

assertRaises() (método de unittest.TestCase)

assertRaisesRegex() (método de unittest.TestCase)

assertRegex() (método de unittest.TestCase)

asserts (2to3 fixer)

assertSequenceEqual() (método de unittest.TestCase)

assertSetEqual() (método de unittest.TestCase)

assertTrue() (método de unittest.TestCase)

assertTupleEqual() (método de unittest.TestCase)

assertWarns() (método de unittest.TestCase)

assertWarnsRegex() (método de unittest.TestCase)

Assign (clase en ast)

assignment

annotated

attribute, [1]

augmented

class attribute

class instance attribute

slice

slicing

statement, [1]

subscript

subscription

target list

AST (clase en ast)

ast (módulo)

ast command line option

--help

--include-attributes

--indent <indent>

--mode <mode>

--no-type-comments

-a

-h

-i <indent>

-m <mode>

astimezone() (método de datetime.datetime)

astuple() (en el módulo dataclasses)

async

palabra clave

ASYNC (en el módulo token)

async def

sentencia

async for

in comprehensions

sentencia

async with

sentencia

async_chat (clase en asynchat)

async_chat.ac_in_buffer_size (en el módulo asynchat)

async_chat.ac_out_buffer_size (en el módulo asynchat)

AsyncContextManager (clase en typing)

asynccontextmanager() (en el módulo contextlib)

AsyncExitStack (clase en contextlib)

AsyncFor (clase en ast)

AsyncFunctionDef (clase en ast)

AsyncGenerator (clase en collections.abc)

(clase en typing)

AsyncGeneratorType (en el módulo types)

asynchat (módulo)

asynchronous generator

asynchronous iterator

function

asynchronous-generator

objeto

asyncio (módulo)

asyncio.subprocess.DEVNULL (variable incorporada)

asyncio.subprocess.PIPE (variable incorporada)

asyncio.subprocess.Process (clase incorporada)

asyncio.subprocess.STDOUT (variable incorporada)

AsyncIterable (clase en collections.abc)

(clase en typing)

AsyncIterator (clase en collections.abc)

(clase en typing)

AsyncMock (clase en unittest.mock)

asyncore (módulo)

AsyncResult (clase en multiprocessing.pool)

asyncSetUp() (método de unittest.IsolatedAsyncioTestCase)

asyncTearDown() (método de unittest.IsolatedAsyncioTestCase)

AsyncWith (clase en ast)

AT (en el módulo token)

at_eof() (método de asyncio.StreamReader)

atan() (en el módulo cmath)

(en el módulo math)

atan2() (en el módulo math)

atanh() (en el módulo cmath)

(en el módulo math)

ATEQUAL (en el módulo token)

atexit (atributo de weakref.finalize)

(módulo)

athrow() (método de agen)

atof() (en el módulo locale)

atoi() (en el módulo locale)

atom

atributo

attach() (método de email.message.Message)

attach_loop() (método de asyncio.AbstractChildWatcher)

attach_mock() (método de unittest.mock.Mock)

AttlistDeclHandler() (método de xml.parsers.expat.xmlparser)

attrgetter() (en el módulo operator)

attrib (atributo de xml.etree.ElementTree.Element)

attribute

assignment, [1]

assignment, class

assignment, class instance

class

class instance

deletion

generic special

reference

special

Attribute (clase en ast)

AttributeError

excepción

attributes (atributo de xml.dom.Node)

AttributesImpl (clase en xml.sax.xmlreader)

AttributesNSImpl (clase en xml.sax.xmlreader)

attroff() (método de curses.window)

attron() (método de curses.window)

attrset() (método de curses.window)

Audio Interchange File Format, [1]

AUDIO_FILE_ENCODING_ADPCM_G721 (en el módulo sunau)

AUDIO_FILE_ENCODING_ADPCM_G722 (en el módulo sunau)

AUDIO_FILE_ENCODING_ADPCM_G723_3 (en el módulo sunau)

AUDIO_FILE_ENCODING_ADPCM_G723_5 (en el módulo sunau)

AUDIO_FILE_ENCODING_ALAW_8 (en el módulo sunau)

AUDIO_FILE_ENCODING_DOUBLE (en el módulo sunau)

AUDIO_FILE_ENCODING_FLOAT (en el módulo sunau)

AUDIO_FILE_ENCODING_LINEAR_16 (en el módulo sunau)

AUDIO_FILE_ENCODING_LINEAR_24 (en el módulo sunau)

AUDIO_FILE_ENCODING_LINEAR_32 (en el módulo sunau)

AUDIO_FILE_ENCODING_LINEAR_8 (en el módulo sunau)

AUDIO_FILE_ENCODING_MULAW_8 (en el módulo sunau)

AUDIO_FILE_MAGIC (en el módulo sunau)

AUDIODEV

audioop (módulo)

audit events

audit() (en el módulo sys)

auditing

AugAssign (clase en ast)

augmented

assignment

auth() (método de ftplib.FTP_TLS)

(método de smtplib.SMTP)

authenticate() (método de imaplib.IMAP4)

AuthenticationError

authenticators() (método de netrc.netrc)

authkey (atributo de multiprocessing.Process)

auto (clase en enum)

autorange() (método de timeit.Timer)

available_timezones() (en el módulo zoneinfo)

avg() (en el módulo audioop)

avgpp() (en el módulo audioop)

avoids_symlink_attacks (atributo de shutil.rmtree)

await

in comprehensions

palabra clave, [1]

Await (clase en ast)

AWAIT (en el módulo token)

await_args (atributo de unittest.mock.AsyncMock)

await_args_list (atributo de unittest.mock.AsyncMock)

await_count (atributo de unittest.mock.AsyncMock)

Awaitable (clase en collections.abc)

(clase en typing)

B

b"

bytes literal

b'

bytes literal

b16decode() (en el módulo base64)

b16encode() (en el módulo base64)

b2a_base64() (en el módulo binascii)

b2a_hex() (en el módulo binascii)

b2a_hqx() (en el módulo binascii)

b2a_qp() (en el módulo binascii)

b2a_uu() (en el módulo binascii)

b32decode() (en el módulo base64)

b32encode() (en el módulo base64)

b64decode() (en el módulo base64)

b64encode() (en el módulo base64)

b85decode() (en el módulo base64)

b85encode() (en el módulo base64)

Babyl (clase en mailbox)

BabylMessage (clase en mailbox)

back() (en el módulo turtle)

backslash character

backslashreplace

error handler's name

backslashreplace_errors() (en el módulo codecs)

backup() (método de sqlite3.Connection)

backward() (en el módulo turtle)

BadGzipFile

BadStatusLine

BadZipFile

BadZipfile

Balloon (clase en tkinter.tix)

Barrier (clase en multiprocessing)

(clase en threading)

Barrier() (método de multiprocessing.managers.SyncManager)

base64

encoding

módulo

base64 (módulo)

base_exec_prefix (en el módulo sys)

base_prefix (en el módulo sys)

BaseCGIHandler (clase en wsgiref.handlers)

BaseCookie (clase en http.cookies)

BaseException

BaseHandler (clase en urllib.request)

(clase en wsgiref.handlers)

BaseHeader (clase en email.headerregistry)

BaseHTTPRequestHandler (clase en http.server)

BaseManager (clase en multiprocessing.managers)

basename() (en el módulo os.path)

BaseProtocol (clase en asyncio)

BaseProxy (clase en multiprocessing.managers)

BaseRequestHandler (clase en socketserver)

BaseRotatingHandler (clase en logging.handlers)

BaseSelector (clase en selectors)

BaseServer (clase en socketserver)

basestring (2to3 fixer)

BaseTransport (clase en asyncio)

basicConfig() (en el módulo logging)

BasicContext (clase en decimal)

BasicInterpolation (clase en configparser)

BasicTestRunner (clase en test.support)

baudrate() (en el módulo curses)

bbox() (método de tkinter.ttk.Treeview)

BDADDR_ANY (en el módulo socket)

BDADDR_LOCAL (en el módulo socket)

bdb

módulo

Bdb (clase en bdb)

bdb (módulo)

BdbQuit

BDFL

bdist_msi (clase en distutils.command.bdist_msi)

beep() (en el módulo curses)

Beep() (en el módulo winsound)

BEFORE_ASYNC_WITH (opcode)

begin_fill() (en el módulo turtle)

begin_poly() (en el módulo turtle)

below() (método de curses.panel.Panel)

BELOW_NORMAL_PRIORITY_CLASS (en el módulo subprocess)

Benchmarking

benchmarking, [1], [2]

betavariate() (en el módulo random)

bgcolor() (en el módulo turtle)

bgpic() (en el módulo turtle)

bias() (en el módulo audioop)

bidirectional() (en el módulo unicodedata)

bigaddrspacetest() (en el módulo test.support)

BigEndianStructure (clase en ctypes)

bigmemtest() (en el módulo test.support)

bin() (función incorporada)

binary

arithmetic operation

bitwise operation

data, packing

literals

Binary (clase en msilib)

(clase en xmlrpc.client)

binary literal

binary mode

binary semaphores

BINARY_ADD (opcode)

BINARY_AND (opcode)

BINARY_FLOOR_DIVIDE (opcode)

BINARY_LSHIFT (opcode)

BINARY_MATRIX_MULTIPLY (opcode)

BINARY_MODULO (opcode)

BINARY_MULTIPLY (opcode)

BINARY_OR (opcode)

BINARY_POWER (opcode)

BINARY_RSHIFT (opcode)

BINARY_SUBSCR (opcode)

BINARY_SUBTRACT (opcode)

BINARY_TRUE_DIVIDE (opcode)

BINARY_XOR (opcode)

binaryfunc (tipo C)

BinaryIO (clase en typing)

binascii (módulo)

bind (widgets)

bind() (método de asyncore.dispatcher)

(método de inspect.Signature)

(método de socket.socket)

bind_partial() (método de inspect.Signature)

bind_port() (en el módulo test.support.socket_helper)

bind_textdomain_codeset() (en el módulo gettext)

bind_unix_socket() (en el módulo test.support.socket_helper)

binding

global name

name, [1], [2], [3], [4], [5], [6]

bindtextdomain() (en el módulo gettext)

(en el módulo locale)

binhex

módulo

binhex (módulo)

binhex() (en el módulo binhex)

BinOp (clase en ast)

bisect (módulo)

bisect() (en el módulo bisect)

bisect_left() (en el módulo bisect)

bisect_right() (en el módulo bisect)

bit_length() (método de int)

BitAnd (clase en ast)

bitmap() (método de msilib.Dialog)

BitOr (clase en ast)

bitwise

and

operation, binary

operation, unary

operations

or

xor

BitXor (clase en ast)

bk() (en el módulo turtle)

bkgd() (método de curses.window)

bkgdset() (método de curses.window)

blake2b() (en el módulo hashlib)

blake2b, blake2s

blake2b.MAX_DIGEST_SIZE (en el módulo hashlib)

blake2b.MAX_KEY_SIZE (en el módulo hashlib)

blake2b.PERSON_SIZE (en el módulo hashlib)

blake2b.SALT_SIZE (en el módulo hashlib)

blake2s() (en el módulo hashlib)

blake2s.MAX_DIGEST_SIZE (en el módulo hashlib)

blake2s.MAX_KEY_SIZE (en el módulo hashlib)

blake2s.PERSON_SIZE (en el módulo hashlib)

blake2s.SALT_SIZE (en el módulo hashlib)

blank line

block

code

block_size (atributo de hmac.HMAC)

blocked_domains() (método de http.cookiejar.DefaultCookiePolicy)

BlockingIOError, [1]

blocksize (atributo de http.client.HTTPConnection)

bloqueo global del intérprete

BNF, [1]

body() (método de nntplib.NNTP)

(método de tkinter.simpledialog.Dialog)

body_encode() (método de email.charset.Charset)

body_encoding (atributo de email.charset.Charset)

body_line_iterator() (en el módulo email.iterators)

BOLD (en el módulo tkinter.font)

BOM (en el módulo codecs)

BOM_BE (en el módulo codecs)

BOM_LE (en el módulo codecs)

BOM_UTF16 (en el módulo codecs)

BOM_UTF16_BE (en el módulo codecs)

BOM_UTF16_LE (en el módulo codecs)

BOM_UTF32 (en el módulo codecs)

BOM_UTF32_BE (en el módulo codecs)

BOM_UTF32_LE (en el módulo codecs)

BOM_UTF8 (en el módulo codecs)

bool (clase incorporada)

Boolean

objeto, [1]

operation

operations, [1]

type

values

BOOLEAN_STATES (atributo de configparser.ConfigParser)

BoolOp (clase en ast)

bootstrap() (en el módulo ensurepip)

border() (método de curses.window)

bottom() (método de curses.panel.Panel)

bottom_panel() (en el módulo curses.panel)

BoundArguments (clase en inspect)

BoundaryError

BoundedSemaphore (clase en asyncio)

(clase en multiprocessing)

(clase en threading)

BoundedSemaphore() (método de multiprocessing.managers.SyncManager)

box() (método de curses.window)

bpformat() (método de bdb.Breakpoint)

bpprint() (método de bdb.Breakpoint)

break

sentencia, [1], [2], [3], [4]

Break (clase en ast)

break (pdb command)

break_anywhere() (método de bdb.Bdb)

break_here() (método de bdb.Bdb)

break_long_words (atributo de textwrap.TextWrapper)

break_on_hyphens (atributo de textwrap.TextWrapper)

Breakpoint (clase en bdb)

breakpoint() (función incorporada)

breakpointhook() (en el módulo sys)

breakpoints

broadcast_address (atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Network)

broken (atributo de threading.Barrier)

BrokenBarrierError

BrokenExecutor

BrokenPipeError

BrokenProcessPool

BrokenThreadPool

BROWSER, [1]

BsdDbShelf (clase en shelve)

buf (atributo de multiprocessing.shared_memory.SharedMemory)

buffer (2to3 fixer)

(atributo de io.TextIOBase)

(atributo de unittest.TestResult)

buffer interface

(see buffer protocol)

buffer object

(see buffer protocol)

buffer protocol

binary sequence types

str (built-in class)

buffer size, I/O

buffer_info() (método de array.array)

buffer_size (atributo de xml.parsers.expat.xmlparser)

buffer_text (atributo de xml.parsers.expat.xmlparser)

buffer_updated() (método de asyncio.BufferedProtocol)

buffer_used (atributo de xml.parsers.expat.xmlparser)

BufferedIOBase (clase en io)

BufferedProtocol (clase en asyncio)

BufferedRandom (clase en io)

BufferedReader (clase en io)

BufferedRWPair (clase en io)

BufferedWriter (clase en io)

BufferError

BufferingHandler (clase en logging.handlers)

BufferTooShort

bufsize() (método de ossaudiodev.oss_audio_device)

BUILD_CONST_KEY_MAP (opcode)

BUILD_LIST (opcode)

BUILD_MAP (opcode)

build_opener() (en el módulo urllib.request)

build_py (clase en distutils.command.build_py)

build_py_2to3 (clase en distutils.command.build_py)

BUILD_SET (opcode)

BUILD_SLICE (opcode)

BUILD_STRING (opcode)

BUILD_TUPLE (opcode)

built-in

method

types

built-in function

call

objeto, [1]

built-in method

call

objeto, [1]

builtin_module_names (en el módulo sys)

BuiltinFunctionType (en el módulo types)

BuiltinImporter (clase en importlib.machinery)

BuiltinMethodType (en el módulo types)

builtins

módulo, [1], [2], [3], [4]

builtins (módulo)

buscador

buscador basado en ruta

buscador de entradas de ruta

ButtonBox (clase en tkinter.tix)

buttonbox() (método de tkinter.simpledialog.Dialog)

bye() (en el módulo turtle)

byref() (en el módulo ctypes)

byte

byte-code

file, [1]

byte_compile() (en el módulo distutils.util)

bytearray

formatting

interpolation

methods

objeto, [1], [2], [3]

bytearray (clase incorporada)

bytecode, [1]

Bytecode (clase en dis)

Bytecode.codeobj (en el módulo dis)

Bytecode.first_line (en el módulo dis)

BYTECODE_SUFFIXES (en el módulo importlib.machinery)

BytecodeTestCase (clase en test.support.bytecode_helper)

byteorder (en el módulo sys)

bytes

formatting

función incorporada, [1]

interpolation

methods

objeto, [1], [2]

str (built-in class)

bytes (atributo de uuid.UUID)

(clase incorporada)

bytes literal

bytes_le (atributo de uuid.UUID)

BytesFeedParser (clase en email.parser)

BytesGenerator (clase en email.generator)

BytesHeaderParser (clase en email.parser)

BytesIO (clase en io)

BytesParser (clase en email.parser)

ByteString (clase en collections.abc)

(clase en typing)

byteswap() (en el módulo audioop)

(método de array.array)

BytesWarning

bz2 (módulo)

BZ2Compressor (clase en bz2)

BZ2Decompressor (clase en bz2)

BZ2File (clase en bz2)

C

C

language, [1], [2], [3], [4], [5]

structures

C-contiguous, [1]

C14NWriterTarget (clase en xml.etree.ElementTree)

c_bool (clase en ctypes)

C_BUILTIN (en el módulo imp)

c_byte (clase en ctypes)

c_char (clase en ctypes)

c_char_p (clase en ctypes)

c_contiguous (atributo de memoryview)

c_double (clase en ctypes)

C_EXTENSION (en el módulo imp)

c_float (clase en ctypes)

c_int (clase en ctypes)

c_int16 (clase en ctypes)

c_int32 (clase en ctypes)

c_int64 (clase en ctypes)

c_int8 (clase en ctypes)

c_long (clase en ctypes)

c_longdouble (clase en ctypes)

c_longlong (clase en ctypes)

c_short (clase en ctypes)

c_size_t (clase en ctypes)

c_ssize_t (clase en ctypes)

c_ubyte (clase en ctypes)

c_uint (clase en ctypes)

c_uint16 (clase en ctypes)

c_uint32 (clase en ctypes)

c_uint64 (clase en ctypes)

c_uint8 (clase en ctypes)

c_ulong (clase en ctypes)

c_ulonglong (clase en ctypes)

c_ushort (clase en ctypes)

c_void_p (clase en ctypes)

c_wchar (clase en ctypes)

c_wchar_p (clase en ctypes)

CAB (clase en msilib)

cache() (en el módulo functools)

cache_from_source() (en el módulo imp)

(en el módulo importlib.util)

cached (atributo de importlib.machinery.ModuleSpec)

cached_property() (en el módulo functools)

CacheFTPHandler (clase en urllib.request)

cadena con triple comilla

calcobjsize() (en el módulo test.support)

calcsize() (en el módulo struct)

calcvobjsize() (en el módulo test.support)

Calendar (clase en calendar)

calendar (módulo)

calendar() (en el módulo calendar)

call

built-in function

built-in method

class instance

class object, [1], [2]

function, [1], [2]

instance, [1]

method

procedure

user-defined function

Call (clase en ast)

call() (en el módulo subprocess)

(en el módulo unittest.mock)

call_args (atributo de unittest.mock.Mock)

call_args_list (atributo de unittest.mock.Mock)

call_at() (método de asyncio.loop)

call_count (atributo de unittest.mock.Mock)

call_exception_handler() (método de asyncio.loop)

CALL_FUNCTION (opcode)

CALL_FUNCTION_EX (opcode)

CALL_FUNCTION_KW (opcode)

call_later() (método de asyncio.loop)

call_list() (método de unittest.mock.call)

CALL_METHOD (opcode)

call_soon() (método de asyncio.loop)

call_soon_threadsafe() (método de asyncio.loop)

call_tracing() (en el módulo sys)

callable

objeto, [1]

Callable (clase en collections.abc)

(en el módulo typing)

callable() (función incorporada)

CallableProxyType (en el módulo weakref)

callback (atributo de optparse.Option)

callback() (método de contextlib.ExitStack)

callback_args (atributo de optparse.Option)

callback_kwargs (atributo de optparse.Option)

callbacks (en el módulo gc)

called (atributo de unittest.mock.Mock)

CalledProcessError

calloc()

CAN_BCM (en el módulo socket)

can_change_color() (en el módulo curses)

can_fetch() (método de urllib.robotparser.RobotFileParser)

CAN_ISOTP (en el módulo socket)

CAN_J1939 (en el módulo socket)

CAN_RAW_FD_FRAMES (en el módulo socket)

CAN_RAW_JOIN_FILTERS (en el módulo socket)

can_symlink() (en el módulo test.support)

can_write_eof() (método de asyncio.StreamWriter)

(método de asyncio.WriteTransport)

can_xattr() (en el módulo test.support)

cancel() (método de asyncio.Future)

(método de asyncio.Handle)

(método de asyncio.Task)

(método de concurrent.futures.Future)

(método de sched.scheduler)

(método de threading.Timer)

(método de tkinter.dnd.DndHandler)

cancel_command() (método de tkinter.filedialog.FileDialog)

cancel_dump_traceback_later() (en el módulo faulthandler)

cancel_join_thread() (método de multiprocessing.Queue)

cancelled() (método de asyncio.Future)

(método de asyncio.Handle)

(método de asyncio.Task)

(método de concurrent.futures.Future)

CancelledError, [1]

CannotSendHeader

CannotSendRequest

canonic() (método de bdb.Bdb)

canonical() (método de decimal.Context)

(método de decimal.Decimal)

canonicalize() (en el módulo xml.etree.ElementTree)

capa() (método de poplib.POP3)

capitalize() (método de bytearray)

(método de bytes)

(método de str)

Capsule

objeto

captured_stderr() (en el módulo test.support)

captured_stdin() (en el módulo test.support)

captured_stdout() (en el módulo test.support)

captureWarnings() (en el módulo logging)

capwords() (en el módulo string)

cargador

casefold() (método de str)

cast() (en el módulo ctypes)

(en el módulo typing)

(método de memoryview)

cat() (en el módulo nis)

catch_threading_exception() (en el módulo test.support)

catch_unraisable_exception() (en el módulo test.support)

catch_warnings (clase en warnings)

category() (en el módulo unicodedata)

cbreak() (en el módulo curses)

CC

ccc() (método de ftplib.FTP_TLS)

CCompiler (clase en distutils.ccompiler)

cdf() (método de statistics.NormalDist)

CDLL (clase en ctypes)

ceil() (en el módulo math)

(in module math)

CellType (en el módulo types)

center() (método de bytearray)

(método de bytes)

(método de str)

CERT_NONE (en el módulo ssl)

CERT_OPTIONAL (en el módulo ssl)

CERT_REQUIRED (en el módulo ssl)

cert_store_stats() (método de ssl.SSLContext)

cert_time_to_seconds() (en el módulo ssl)

CertificateError

certificates

CFLAGS, [1], [2]

CFUNCTYPE() (en el módulo ctypes)

cget() (método de tkinter.font.Font)

CGI

debugging

exceptions

protocol

security

tracebacks

cgi (módulo)

cgi_directories (atributo de http.server.CGIHTTPRequestHandler)

CGIHandler (clase en wsgiref.handlers)

CGIHTTPRequestHandler (clase en http.server)

cgitb (módulo)

CGIXMLRPCRequestHandler (clase en xmlrpc.server)

chain() (en el módulo itertools)

chaining

comparisons, [1]

exception

ChainMap (clase en collections)

(clase en typing)

change_cwd() (en el módulo test.support)

change_root() (en el módulo distutils.util)

CHANNEL_BINDING_TYPES (en el módulo ssl)

channel_class (atributo de smtpd.SMTPServer)

channels() (método de ossaudiodev.oss_audio_device)

CHAR_MAX (en el módulo locale)

character, [1], [2]

CharacterDataHandler() (método de xml.parsers.expat.xmlparser)

characters() (método de xml.sax.handler.ContentHandler)

characters_written (atributo de BlockingIOError)

Charset (clase en email.charset)

charset() (método de gettext.NullTranslations)

chdir() (en el módulo os)

check (atributo de lzma.LZMADecompressor)

check() (en el módulo tabnanny)

(método de imaplib.IMAP4)

check__all__() (en el módulo test.support)

check_call() (en el módulo subprocess)

check_environ() (en el módulo distutils.util)

check_free_after_iterating() (en el módulo test.support)

check_hostname (atributo de ssl.SSLContext)

check_impl_detail() (en el módulo test.support)

check_no_resource_warning() (en el módulo test.support)

check_output() (en el módulo subprocess)

(método de doctest.OutputChecker)

check_returncode() (método de subprocess.CompletedProcess)

check_syntax_error() (en el módulo test.support)

check_syntax_warning() (en el módulo test.support)

check_unused_args() (método de string.Formatter)

check_warnings() (en el módulo test.support)

checkbox() (método de msilib.Dialog)

checkcache() (en el módulo linecache)

CHECKED_HASH (atributo de py_compile.PycInvalidationMode)

checkfuncname() (en el módulo bdb)

CheckList (clase en tkinter.tix)

checksizeof() (en el módulo test.support)

checksum

Cyclic Redundancy Check

chflags() (en el módulo os)

chgat() (método de curses.window)

childNodes (atributo de xml.dom.Node)

ChildProcessError

children (atributo de pyclbr.Class)

(atributo de pyclbr.Function)

(atributo de tkinter.Tk)

chmod() (en el módulo os)

(método de pathlib.Path)

choice() (en el módulo random)

(en el módulo secrets)

choices (atributo de optparse.Option)

choices() (en el módulo random)

Chooser (clase en tkinter.colorchooser)

chown() (en el módulo os)

(en el módulo shutil)

chr

función incorporada

chr() (función incorporada)

chroot() (en el módulo os)

Chunk (clase en chunk)

chunk (módulo)

cipher

DES

cipher() (método de ssl.SSLSocket)

circle() (en el módulo turtle)

CIRCUMFLEX (en el módulo token)

CIRCUMFLEXEQUAL (en el módulo token)

Clamped (clase en decimal)

clase

clase base abstracta

clase de nuevo estilo

class

attribute

attribute assignment

body

constructor

definition, [1]

instance

name

objeto, [1], [2]

sentencia

Class (clase en symtable)

Class browser

class instance

attribute

attribute assignment

call

objeto, [1], [2]

class object

call, [1], [2]

ClassDef (clase en ast)

classmethod

función incorporada

classmethod() (función incorporada)

ClassMethodDescriptorType (en el módulo types)

ClassVar (en el módulo typing)

clause

CLD_CONTINUED (en el módulo os)

CLD_DUMPED (en el módulo os)

CLD_EXITED (en el módulo os)

CLD_KILLED (en el módulo os)

CLD_STOPPED (en el módulo os)

CLD_TRAPPED (en el módulo os)

clean() (método de mailbox.Maildir)

cleandoc() (en el módulo inspect)

CleanImport (clase en test.support)

cleanup functions

clear (pdb command)

Clear Breakpoint

clear() (en el módulo turtle)

(método de asyncio.Event)

(método de collections.deque)

(método de curses.window)

(método de dict)

(método de email.message.EmailMessage)

(método de frame)

(método de frozenset)

(método de http.cookiejar.CookieJar)

(método de mailbox.Mailbox)

(método de threading.Event)

(método de xml.etree.ElementTree.Element)

(sequence method)

clear_all_breaks() (método de bdb.Bdb)

clear_all_file_breaks() (método de bdb.Bdb)

clear_bpbynumber() (método de bdb.Bdb)

clear_break() (método de bdb.Bdb)

clear_cache() (en el módulo filecmp)

(método de clase de zoneinfo.ZoneInfo)

clear_content() (método de email.message.EmailMessage)

clear_flags() (método de decimal.Context)

clear_frames() (en el módulo traceback)

clear_history() (en el módulo readline)

clear_session_cookies() (método de http.cookiejar.CookieJar)

clear_traces() (en el módulo tracemalloc)

clear_traps() (método de decimal.Context)

clearcache() (en el módulo linecache)

ClearData() (método de msilib.Record)

clearok() (método de curses.window)

clearscreen() (en el módulo turtle)

clearstamp() (en el módulo turtle)

clearstamps() (en el módulo turtle)

Client() (en el módulo multiprocessing.connection)

client_address (atributo de http.server.BaseHTTPRequestHandler)

CLOCK_BOOTTIME (en el módulo time)

clock_getres() (en el módulo time)

clock_gettime() (en el módulo time)

clock_gettime_ns() (en el módulo time)

CLOCK_HIGHRES (en el módulo time)

CLOCK_MONOTONIC (en el módulo time)

CLOCK_MONOTONIC_RAW (en el módulo time)

CLOCK_PROCESS_CPUTIME_ID (en el módulo time)

CLOCK_PROF (en el módulo time)

CLOCK_REALTIME (en el módulo time)

clock_settime() (en el módulo time)

clock_settime_ns() (en el módulo time)

CLOCK_TAI (en el módulo time)

CLOCK_THREAD_CPUTIME_ID (en el módulo time)

CLOCK_UPTIME (en el módulo time)

CLOCK_UPTIME_RAW (en el módulo time)

clone() (en el módulo turtle)

(método de email.generator.BytesGenerator)

(método de email.generator.Generator)

(método de email.policy.Policy)

(método de pipes.Template)

cloneNode() (método de xml.dom.Node)

close() (en el módulo fileinput)

(en el módulo os)

(en el módulo socket)

(in module os)

(método de aifc.aifc)

(método de asyncio.AbstractChildWatcher)

(método de asyncio.BaseTransport)

(método de asyncio.loop)

(método de asyncio.Server)

(método de asyncio.StreamWriter)

(método de asyncio.SubprocessTransport)

(método de asyncore.dispatcher)

(método de chunk.Chunk)

(método de contextlib.ExitStack)

(método de coroutine)

(método de dbm.dumb.dumbdbm)

(método de dbm.gnu.gdbm)

(método de dbm.ndbm.ndbm)

(método de distutils.text_file.TextFile)

(método de email.parser.BytesFeedParser)

(método de ftplib.FTP)

(método de generator)

(método de html.parser.HTMLParser)

(método de http.client.HTTPConnection)

(método de imaplib.IMAP4)

(método de io.IOBase)

(método de logging.FileHandler)

(método de logging.Handler)

(método de logging.handlers.MemoryHandler)

(método de logging.handlers.NTEventLogHandler)

(método de logging.handlers.SocketHandler)

(método de logging.handlers.SysLogHandler)

(método de mailbox.Mailbox)

(método de mailbox.Maildir)

(método de mailbox.MH)

(método de mmap.mmap)

Close() (método de msilib.Database)

(método de msilib.View)

close() (método de multiprocessing.connection.Connection)

(método de multiprocessing.connection.Listener)

(método de multiprocessing.pool.Pool)

(método de multiprocessing.Process)

(método de multiprocessing.Queue)

(método de multiprocessing.shared_memory.SharedMemory)

(método de multiprocessing.SimpleQueue)

(método de os.scandir)

(método de ossaudiodev.oss_audio_device)

(método de ossaudiodev.oss_mixer_device)

(método de select.devpoll)

(método de select.epoll)

(método de select.kqueue)

(método de selectors.BaseSelector)

(método de shelve.Shelf)

(método de socket.socket)

(método de sqlite3.Connection)

(método de sqlite3.Cursor)

(método de sunau.AU_read)

(método de sunau.AU_write)

(método de tarfile.TarFile)

(método de telnetlib.Telnet)

(método de urllib.request.BaseHandler)

(método de wave.Wave_read)

(método de wave.Wave_write)

Close() (método de winreg.PyHKEY)

close() (método de xml.etree.ElementTree.TreeBuilder)

(método de xml.etree.ElementTree.XMLParser)

(método de xml.etree.ElementTree.XMLPullParser)

(método de xml.sax.xmlreader.IncrementalParser)

(método de zipfile.ZipFile)

close_connection (atributo de http.server.BaseHTTPRequestHandler)

close_when_done() (método de asynchat.async_chat)

closed (atributo de http.client.HTTPResponse)

(atributo de io.IOBase)

(atributo de mmap.mmap)

(atributo de ossaudiodev.oss_audio_device)

(atributo de select.devpoll)

(atributo de select.epoll)

(atributo de select.kqueue)

CloseKey() (en el módulo winreg)

closelog() (en el módulo syslog)

closerange() (en el módulo os)

closing() (en el módulo contextlib)

clrtobot() (método de curses.window)

clrtoeol() (método de curses.window)

cmath (módulo)

cmd

módulo

cmd (atributo de subprocess.CalledProcessError)

(atributo de subprocess.TimeoutExpired)

Cmd (clase en cmd)

cmd (módulo)

cmdloop() (método de cmd.Cmd)

cmdqueue (atributo de cmd.Cmd)

cmp() (en el módulo filecmp)

cmp_op (en el módulo dis)

cmp_to_key() (en el módulo functools)

cmpfiles() (en el módulo filecmp)

CMSG_LEN() (en el módulo socket)

CMSG_SPACE() (en el módulo socket)

co_argcount (code object attribute)

CO_ASYNC_GENERATOR (en el módulo inspect)

co_cellvars (code object attribute)

co_code (code object attribute)

co_consts (code object attribute)

CO_COROUTINE (en el módulo inspect)

co_filename (code object attribute)

co_firstlineno (code object attribute)

co_flags (code object attribute)

co_freevars (code object attribute)

CO_FUTURE_DIVISION (variable C)

CO_GENERATOR (en el módulo inspect)

CO_ITERABLE_COROUTINE (en el módulo inspect)

co_kwonlyargcount (code object attribute)

co_lnotab (code object attribute)

co_name (code object attribute)

co_names (code object attribute)

CO_NESTED (en el módulo inspect)

CO_NEWLOCALS (en el módulo inspect)

co_nlocals (code object attribute)

CO_NOFREE (en el módulo inspect)

CO_OPTIMIZED (en el módulo inspect)

co_posonlyargcount (code object attribute)

co_stacksize (code object attribute)

CO_VARARGS (en el módulo inspect)

CO_VARKEYWORDS (en el módulo inspect)

co_varnames (code object attribute)

code

block

code (atributo de SystemExit)

(atributo de urllib.error.HTTPError)

(atributo de urllib.response.addinfourl)

(atributo de xml.etree.ElementTree.ParseError)

(atributo de xml.parsers.expat.ExpatError)

(módulo)

code object, [1], [2], [3]

code_info() (en el módulo dis)

CodecInfo (clase en codecs)

Codecs

decode

encode

codecs (módulo)

coded_value (atributo de http.cookies.Morsel)

codeop (módulo)

codepoint2name (en el módulo html.entities)

codes (en el módulo xml.parsers.expat.errors)

CODESET (en el módulo locale)

CodeType (clase en types)

codificación de texto

coding

style

coerción

col_offset (atributo de ast.AST)

collapse_addresses() (en el módulo ipaddress)

collapse_rfc2231_value() (en el módulo email.utils)

collect() (en el módulo gc)

collect_incoming_data() (método de asynchat.async_chat)

Collection (clase en collections.abc)

(clase en typing)

collections (módulo)

collections.abc (módulo)

colno (atributo de json.JSONDecodeError)

(atributo de re.error)

COLON (en el módulo token)

COLONEQUAL (en el módulo token)

color() (en el módulo turtle)

color_content() (en el módulo curses)

color_pair() (en el módulo curses)

colormode() (en el módulo turtle)

colorsys (módulo)

COLS, [1]

column() (método de tkinter.ttk.Treeview)

COLUMNS, [1]

columns (atributo de os.terminal_size)

comb() (en el módulo math)

combinations() (en el módulo itertools)

combinations_with_replacement() (en el módulo itertools)

combine() (método de clase de datetime.datetime)

combining() (en el módulo unicodedata)

ComboBox (clase en tkinter.tix)

Combobox (clase en tkinter.ttk)

comma

trailing

COMMA (en el módulo token)

command (atributo de http.server.BaseHTTPRequestHandler)

Command (clase en distutils.cmd)

(clase en distutils.core)

command line

command line option

--check-hash-based-pycs default|always|never

--help

--version

-?

-b

-B

-c <command>

-d

-E

-h

-i

-I

-J

-m <module-name>

-O

-OO

-q

-R

-s

-S

-u

-V

-v

-W arg

-x

-X

CommandCompiler (clase en codeop)

commands (pdb command)

comment

(atributo de http.cookiejar.Cookie)

(atributo de zipfile.ZipFile)

(atributo de zipfile.ZipInfo)

COMMENT (en el módulo token)

Comment() (en el módulo xml.etree.ElementTree)

comment() (método de xml.etree.ElementTree.TreeBuilder)

comment_url (atributo de http.cookiejar.Cookie)

commenters (atributo de shlex.shlex)

CommentHandler() (método de xml.parsers.expat.xmlparser)

commit() (método de msilib.CAB)

Commit() (método de msilib.Database)

commit() (método de sqlite3.Connection)

common (atributo de filecmp.dircmp)

Common Gateway Interface

common_dirs (atributo de filecmp.dircmp)

common_files (atributo de filecmp.dircmp)

common_funny (atributo de filecmp.dircmp)

common_types (en el módulo mimetypes)

commonpath() (en el módulo os.path)

commonprefix() (en el módulo os.path)

communicate() (método de asyncio.subprocess.Process)

(método de subprocess.Popen)

Compare (clase en ast)

compare() (método de decimal.Context)

(método de decimal.Decimal)

(método de difflib.Differ)

compare_digest() (en el módulo hmac)

(en el módulo secrets)

compare_networks() (método de ipaddress.IPv4Network)

(método de ipaddress.IPv6Network)

COMPARE_OP (opcode)

compare_signal() (método de decimal.Context)

(método de decimal.Decimal)

compare_to() (método de tracemalloc.Snapshot)

compare_total() (método de decimal.Context)

(método de decimal.Decimal)

compare_total_mag() (método de decimal.Context)

(método de decimal.Decimal)

comparing

objects

comparison

operator

COMPARISON_FLAGS (en el módulo doctest)

comparisons

chaining, [1]

Compat32 (clase en email.policy)

compat32 (en el módulo email.policy)

compile

función incorporada, [1], [2], [3], [4]

Compile (clase en codeop)

compile() (en el módulo py_compile)

(en el módulo re)

(función incorporada)

(método de distutils.ccompiler.CCompiler)

(método de parser.ST)

compile_command() (en el módulo code)

(en el módulo codeop)

compile_dir() (en el módulo compileall)

compile_file() (en el módulo compileall)

compile_path() (en el módulo compileall)

compileall (módulo)

compileall command line option

--hardlink-dupes

--invalidation-mode [timestamp|checked-hash|unchecked-hash]

-b

-d destdir

-e dir

-f

-i list

-j N

-l

-o level

-p prepend_prefix

-q

-r

-s strip_prefix

-x regex

directory ...

file ...

compilest() (en el módulo parser)

complete() (método de rlcompleter.Completer)

complete_statement() (en el módulo sqlite3)

completedefault() (método de cmd.Cmd)

CompletedProcess (clase en subprocess)

complex

función incorporada, [1]

number

objeto

Complex (clase en numbers)

complex (clase incorporada)

complex literal

complex number

literals

objeto, [1]

compound

statement

comprehension (clase en ast)

comprehensions

dictionary

list

set

comprensión de conjuntos

comprensión de diccionarios

comprensión de listas

compress() (en el módulo bz2)

(en el módulo gzip)

(en el módulo itertools)

(en el módulo lzma)

(en el módulo zlib)

(método de bz2.BZ2Compressor)

(método de lzma.LZMACompressor)

(método de zlib.Compress)

compress_size (atributo de zipfile.ZipInfo)

compress_type (atributo de zipfile.ZipInfo)

compressed (atributo de ipaddress.IPv4Address)

(atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Address)

(atributo de ipaddress.IPv6Network)

compression() (método de ssl.SSLSocket)

CompressionError

compressobj() (en el módulo zlib)

COMSPEC, [1]

concat() (en el módulo operator)

concatenation

operation

concurrent.futures (módulo)

Condition (clase en asyncio)

(clase en multiprocessing)

(clase en threading)

condition (pdb command)

condition() (método de msilib.Control)

Condition() (método de multiprocessing.managers.SyncManager)

Conditional

expression

conditional

expression

config() (método de tkinter.font.Font)

ConfigParser (clase en configparser)

configparser (módulo)

configuration

file

file, debugger

file, path

configuration information

configure() (método de tkinter.ttk.Style)

configure_mock() (método de unittest.mock.Mock)

confstr() (en el módulo os)

confstr_names (en el módulo os)

conjugate() (complex number method)

(método de decimal.Decimal)

(método de numbers.Complex)

conn (atributo de smtpd.SMTPChannel)

connect() (en el módulo sqlite3)

(método de asyncore.dispatcher)

(método de ftplib.FTP)

(método de http.client.HTTPConnection)

(método de multiprocessing.managers.BaseManager)

(método de smtplib.SMTP)

(método de socket.socket)

connect_accepted_socket() (método de asyncio.loop)

connect_ex() (método de socket.socket)

connect_read_pipe() (método de asyncio.loop)

connect_write_pipe() (método de asyncio.loop)

connection (atributo de sqlite3.Cursor)

Connection (clase en multiprocessing.connection)

(clase en sqlite3)

connection_lost() (método de asyncio.BaseProtocol)

connection_made() (método de asyncio.BaseProtocol)

ConnectionAbortedError

ConnectionError

ConnectionRefusedError

ConnectionResetError

ConnectRegistry() (en el módulo winreg)

const (atributo de optparse.Option)

constant

Constant (clase en ast)

constructor

class

constructor() (en el módulo copyreg)

consumed (atributo de asyncio.LimitOverrunError)

contador de referencias

container, [1]

iteration over

Container (clase en collections.abc)

(clase en typing)

contains() (en el módulo operator)

CONTAINS_OP (opcode)

content type

MIME

content_disposition (atributo de email.headerregistry.ContentDispositionHeader)

content_manager (atributo de email.policy.EmailPolicy)

content_type (atributo de email.headerregistry.ContentTypeHeader)

ContentDispositionHeader (clase en email.headerregistry)

ContentHandler (clase en xml.sax.handler)

ContentManager (clase en email.contentmanager)

contents (atributo de ctypes._Pointer)

contents() (en el módulo importlib.resources)

(método de importlib.abc.ResourceReader)

ContentTooShortError

ContentTransferEncoding (clase en email.headerregistry)

ContentTypeHeader (clase en email.headerregistry)

context (atributo de ssl.SSLSocket)

Context (clase en contextvars)

(clase en decimal)

context management protocol

context manager, [1]

context_diff() (en el módulo difflib)

ContextDecorator (clase en contextlib)

contextlib (módulo)

ContextManager (clase en typing)

contextmanager() (en el módulo contextlib)

ContextVar (clase en contextvars)

contextvars (módulo)

contiguo

contiguous

(atributo de memoryview)

continue

sentencia, [1], [2], [3], [4]

Continue (clase en ast)

continue (pdb command)

Control (clase en msilib)

(clase en tkinter.tix)

control() (método de msilib.Dialog)

(método de select.kqueue)

controlnames (en el módulo curses.ascii)

controls() (método de ossaudiodev.oss_mixer_device)

conversion

arithmetic

string, [1]

ConversionError

conversions

numeric

convert_arg_line_to_args() (método de argparse.ArgumentParser)

convert_field() (método de string.Formatter)

convert_path() (en el módulo distutils.util)

Cookie (clase en http.cookiejar)

CookieError

cookiejar (atributo de urllib.request.HTTPCookieProcessor)

CookieJar (clase en http.cookiejar)

CookiePolicy (clase en http.cookiejar)

Coordinated Universal Time

Copy

copy

módulo

protocol

copy (módulo)

copy() (en el módulo copy)

(en el módulo multiprocessing.sharedctypes)

(en el módulo shutil)

(método de collections.deque)

(método de contextvars.Context)

(método de decimal.Context)

(método de dict)

(método de frozenset)

(método de hashlib.hash)

(método de hmac.HMAC)

(método de http.cookies.Morsel)

(método de imaplib.IMAP4)

(método de pipes.Template)

(método de tkinter.font.Font)

(método de types.MappingProxyType)

(método de zlib.Compress)

(método de zlib.Decompress)

(sequence method)

copy2() (en el módulo shutil)

copy_abs() (método de decimal.Context)

(método de decimal.Decimal)

copy_context() (en el módulo contextvars)

copy_decimal() (método de decimal.Context)

copy_file() (en el módulo distutils.file_util)

copy_file_range() (en el módulo os)

copy_location() (en el módulo ast)

copy_negate() (método de decimal.Context)

(método de decimal.Decimal)

copy_sign() (método de decimal.Context)

(método de decimal.Decimal)

copy_tree() (en el módulo distutils.dir_util)

copyfile() (en el módulo shutil)

copyfileobj() (en el módulo shutil)

copying files

copymode() (en el módulo shutil)

copyreg (módulo)

copyright (en el módulo sys)

(in module sys)

(variable incorporada)

copysign() (en el módulo math)

copystat() (en el módulo shutil)

copytree() (en el módulo shutil)

coroutine, [1]

function

Coroutine (clase en collections.abc)

(clase en typing)

coroutine() (en el módulo asyncio)

(en el módulo types)

CoroutineType (en el módulo types)

corrutina

cos() (en el módulo cmath)

(en el módulo math)

cosh() (en el módulo cmath)

(en el módulo math)

count (atributo de tracemalloc.Statistic)

(atributo de tracemalloc.StatisticDiff)

count() (en el módulo itertools)

(método de array.array)

(método de bytearray)

(método de bytes)

(método de collections.deque)

(método de multiprocessing.shared_memory.ShareableList)

(método de str)

(sequence method)

count_diff (atributo de tracemalloc.StatisticDiff)

Counter (clase en collections)

(clase en typing)

countOf() (en el módulo operator)

countTestCases() (método de unittest.TestCase)

(método de unittest.TestSuite)

CoverageResults (clase en trace)

CPP

CPPFLAGS

cProfile (módulo)

CPU time, [1]

cpu_count() (en el módulo multiprocessing)

(en el módulo os)

CPython

cpython_only() (en el módulo test.support)

crawl_delay() (método de urllib.robotparser.RobotFileParser)

CRC (atributo de zipfile.ZipInfo)

crc32() (en el módulo binascii)

(en el módulo zlib)

crc_hqx() (en el módulo binascii)

create() (en el módulo venv)

(método de imaplib.IMAP4)

(método de venv.EnvBuilder)

create_aggregate() (método de sqlite3.Connection)

create_archive() (en el módulo zipapp)

create_autospec() (en el módulo unittest.mock)

CREATE_BREAKAWAY_FROM_JOB (en el módulo subprocess)

create_collation() (método de sqlite3.Connection)

create_configuration() (método de venv.EnvBuilder)

create_connection() (en el módulo socket)

(método de asyncio.loop)

create_datagram_endpoint() (método de asyncio.loop)

create_decimal() (método de decimal.Context)

create_decimal_from_float() (método de decimal.Context)

create_default_context() (en el módulo ssl)

CREATE_DEFAULT_ERROR_MODE (en el módulo subprocess)

create_empty_file() (en el módulo test.support)

create_function() (método de sqlite3.Connection)

create_future() (método de asyncio.loop)

create_module (función C)

create_module() (método de importlib.abc.Loader)

(método de importlib.machinery.ExtensionFileLoader)

CREATE_NEW_CONSOLE (en el módulo subprocess)

CREATE_NEW_PROCESS_GROUP (en el módulo subprocess)

CREATE_NO_WINDOW (en el módulo subprocess)

create_server() (en el módulo socket)

(método de asyncio.loop)

create_shortcut() (función incorporada)

create_socket() (método de asyncore.dispatcher)

create_static_lib() (método de distutils.ccompiler.CCompiler)

create_stats() (método de profile.Profile)

create_string_buffer() (en el módulo ctypes)

create_subprocess_exec() (en el módulo asyncio)

create_subprocess_shell() (en el módulo asyncio)

create_system (atributo de zipfile.ZipInfo)

create_task() (en el módulo asyncio)

(método de asyncio.loop)

create_tree() (en el módulo distutils.dir_util)

create_unicode_buffer() (en el módulo ctypes)

create_unix_connection() (método de asyncio.loop)

create_unix_server() (método de asyncio.loop)

create_version (atributo de zipfile.ZipInfo)

createAttribute() (método de xml.dom.Document)

createAttributeNS() (método de xml.dom.Document)

createComment() (método de xml.dom.Document)

createDocument() (método de xml.dom.DOMImplementation)

createDocumentType() (método de xml.dom.DOMImplementation)

createElement() (método de xml.dom.Document)

createElementNS() (método de xml.dom.Document)

createfilehandler() (método de tkinter.Widget.tk)

CreateKey() (en el módulo winreg)

CreateKeyEx() (en el módulo winreg)

createLock() (método de logging.Handler)

(método de logging.NullHandler)

createProcessingInstruction() (método de xml.dom.Document)

CreateRecord() (en el módulo msilib)

createSocket() (método de logging.handlers.SocketHandler)

createTextNode() (método de xml.dom.Document)

credits (variable incorporada)

critical() (en el módulo logging)

(método de logging.Logger)

CRNCYSTR (en el módulo locale)

cross() (en el módulo audioop)

crypt

módulo

crypt (módulo)

crypt() (en el módulo crypt)

crypt(3), [1], [2]

cryptography

cssclass_month (atributo de calendar.HTMLCalendar)

cssclass_month_head (atributo de calendar.HTMLCalendar)

cssclass_noday (atributo de calendar.HTMLCalendar)

cssclass_year (atributo de calendar.HTMLCalendar)

cssclass_year_head (atributo de calendar.HTMLCalendar)

cssclasses (atributo de calendar.HTMLCalendar)

cssclasses_weekday_head (atributo de calendar.HTMLCalendar)

csv

(módulo)

cte (atributo de email.headerregistry.ContentTransferEncoding)

cte_type (atributo de email.policy.Policy)

ctermid() (en el módulo os)

ctime() (en el módulo time)

(método de datetime.date)

(método de datetime.datetime)

ctrl() (en el módulo curses.ascii)

CTRL_BREAK_EVENT (en el módulo signal)

CTRL_C_EVENT (en el módulo signal)

ctypes (módulo)

curdir (en el módulo os)

currency() (en el módulo locale)

current() (método de tkinter.ttk.Combobox)

current_process() (en el módulo multiprocessing)

current_task() (en el módulo asyncio)

current_thread() (en el módulo threading)

CurrentByteIndex (atributo de xml.parsers.expat.xmlparser)

CurrentColumnNumber (atributo de xml.parsers.expat.xmlparser)

currentframe() (en el módulo inspect)

CurrentLineNumber (atributo de xml.parsers.expat.xmlparser)

curs_set() (en el módulo curses)

curses (módulo)

curses.ascii (módulo)

curses.panel (módulo)

curses.textpad (módulo)

Cursor (clase en sqlite3)

cursor() (método de sqlite3.Connection)

cursyncup() (método de curses.window)

customize_compiler() (en el módulo distutils.sysconfig)

Cut

cwd() (método de clase de pathlib.Path)

(método de ftplib.FTP)

cycle() (en el módulo itertools)

CycleError

Cyclic Redundancy Check

D

D_FMT (en el módulo locale)

D_T_FMT (en el módulo locale)

daemon (atributo de multiprocessing.Process)

(atributo de threading.Thread)

dangling

else

data

packing binary

tabular

type

type, immutable

data (atributo de collections.UserDict)

(atributo de collections.UserList)

(atributo de collections.UserString)

(atributo de select.kevent)

(atributo de selectors.SelectorKey)

(atributo de urllib.request.Request)

(atributo de xml.dom.Comment)

(atributo de xml.dom.ProcessingInstruction)

(atributo de xml.dom.Text)

(atributo de xmlrpc.client.Binary)

data() (método de xml.etree.ElementTree.TreeBuilder)

data_filter() (en el módulo tarfile)

data_open() (método de urllib.request.DataHandler)

data_received() (método de asyncio.Protocol)

database

Unicode

DatabaseError

databases

dataclass() (en el módulo dataclasses)

dataclasses (módulo)

datagram_received() (método de asyncio.DatagramProtocol)

DatagramHandler (clase en logging.handlers)

DatagramProtocol (clase en asyncio)

DatagramRequestHandler (clase en socketserver)

DatagramTransport (clase en asyncio)

DataHandler (clase en urllib.request)

date (clase en datetime)

date() (método de datetime.datetime)

(método de nntplib.NNTP)

date_time (atributo de zipfile.ZipInfo)

date_time_string() (método de http.server.BaseHTTPRequestHandler)

DateHeader (clase en email.headerregistry)

datetime (atributo de email.headerregistry.DateHeader)

(clase en datetime)

DateTime (clase en xmlrpc.client)

datetime (módulo)

datum

day (atributo de datetime.date)

(atributo de datetime.datetime)

day_abbr (en el módulo calendar)

day_name (en el módulo calendar)

daylight (en el módulo time)

Daylight Saving Time

DbfilenameShelf (clase en shelve)

dbm (módulo)

dbm.dumb (módulo)

dbm.gnu

módulo, [1]

dbm.gnu (módulo)

dbm.ndbm

módulo, [1]

dbm.ndbm (módulo)

dcgettext() (en el módulo locale)

deallocation, object

debug (atributo de imaplib.IMAP4)

(atributo de shlex.shlex)

(atributo de zipfile.ZipFile)

DEBUG (en el módulo re)

debug (pdb command)

debug() (en el módulo doctest)

(en el módulo logging)

(método de logging.Logger)

(método de pipes.Template)

(método de unittest.TestCase)

(método de unittest.TestSuite)

DEBUG_BYTECODE_SUFFIXES (en el módulo importlib.machinery)

DEBUG_COLLECTABLE (en el módulo gc)

DEBUG_LEAK (en el módulo gc)

debug_print() (método de distutils.ccompiler.CCompiler)

DEBUG_SAVEALL (en el módulo gc)

debug_src() (en el módulo doctest)

DEBUG_STATS (en el módulo gc)

DEBUG_UNCOLLECTABLE (en el módulo gc)

debugger, [1], [2]

configuration file

debugging

assertions

CGI

DebuggingServer (clase en smtpd)

debuglevel (atributo de http.client.HTTPResponse)

DebugRunner (clase en doctest)

Decimal (clase en decimal)

decimal (módulo)

decimal literal

decimal() (en el módulo unicodedata)

DecimalException (clase en decimal)

decode

Codecs

decode (atributo de codecs.CodecInfo)

decode() (en el módulo base64)

(en el módulo codecs)

(en el módulo quopri)

(en el módulo uu)

(método de bytearray)

(método de bytes)

(método de codecs.Codec)

(método de codecs.IncrementalDecoder)

(método de json.JSONDecoder)

(método de xmlrpc.client.Binary)

(método de xmlrpc.client.DateTime)

decode_header() (en el módulo email.header)

(en el módulo nntplib)

decode_params() (en el módulo email.utils)

decode_rfc2231() (en el módulo email.utils)

decode_source() (en el módulo importlib.util)

decodebytes() (en el módulo base64)

DecodedGenerator (clase en email.generator)

decodestring() (en el módulo quopri)

decomposition() (en el módulo unicodedata)

decompress() (en el módulo bz2)

(en el módulo gzip)

(en el módulo lzma)

(en el módulo zlib)

(método de bz2.BZ2Decompressor)

(método de lzma.LZMADecompressor)

(método de zlib.Decompress)

decompressobj() (en el módulo zlib)

decorador

DEDENT (en el módulo token)

DEDENT token, [1]

dedent() (en el módulo textwrap)

deepcopy() (en el módulo copy)

def

sentencia

def_prog_mode() (en el módulo curses)

def_shell_mode() (en el módulo curses)

default

parameter value

default (atributo de inspect.Parameter)

(atributo de optparse.Option)

(en el módulo email.policy)

DEFAULT (en el módulo unittest.mock)

default() (método de cmd.Cmd)

(método de json.JSONEncoder)

DEFAULT_BUFFER_SIZE (en el módulo io)

default_bufsize (en el módulo xml.dom.pulldom)

default_exception_handler() (método de asyncio.loop)

default_factory (atributo de collections.defaultdict)

DEFAULT_FORMAT (en el módulo tarfile)

DEFAULT_IGNORES (en el módulo filecmp)

default_open() (método de urllib.request.BaseHandler)

DEFAULT_PROTOCOL (en el módulo pickle)

default_timer() (en el módulo timeit)

DefaultContext (clase en decimal)

DefaultCookiePolicy (clase en http.cookiejar)

defaultdict (clase en collections)

DefaultDict (clase en typing)

DefaultEventLoopPolicy (clase en asyncio)

DefaultHandler() (método de xml.parsers.expat.xmlparser)

DefaultHandlerExpand() (método de xml.parsers.expat.xmlparser)

defaults() (método de configparser.ConfigParser)

DefaultSelector (clase en selectors)

defaultTestLoader (en el módulo unittest)

defaultTestResult() (método de unittest.TestCase)

defects (atributo de email.headerregistry.BaseHeader)

(atributo de email.message.EmailMessage)

(atributo de email.message.Message)

define_macro() (método de distutils.ccompiler.CCompiler)

definition

class, [1]

function, [1]

defpath (en el módulo os)

DefragResult (clase en urllib.parse)

DefragResultBytes (clase en urllib.parse)

degrees() (en el módulo math)

(en el módulo turtle)

del

sentencia, [1], [2], [3]

Del (clase en ast)

del_param() (método de email.message.EmailMessage)

(método de email.message.Message)

delattr() (función incorporada)

delay() (en el módulo turtle)

delay_output() (en el módulo curses)

delayload (atributo de http.cookiejar.FileCookieJar)

delch() (método de curses.window)

dele() (método de poplib.POP3)

Delete (clase en ast)

delete() (método de ftplib.FTP)

(método de imaplib.IMAP4)

(método de tkinter.ttk.Treeview)

DELETE_ATTR (opcode)

DELETE_DEREF (opcode)

DELETE_FAST (opcode)

DELETE_GLOBAL (opcode)

DELETE_NAME (opcode)

DELETE_SUBSCR (opcode)

deleteacl() (método de imaplib.IMAP4)

deletefilehandler() (método de tkinter.Widget.tk)

DeleteKey() (en el módulo winreg)

DeleteKeyEx() (en el módulo winreg)

deleteln() (método de curses.window)

deleteMe() (método de bdb.Breakpoint)

DeleteValue() (en el módulo winreg)

deletion

attribute

target

target list

delimiter (atributo de csv.Dialect)

delimiters

delitem() (en el módulo operator)

deliver_challenge() (en el módulo multiprocessing.connection)

delocalize() (en el módulo locale)

demo_app() (en el módulo wsgiref.simple_server)

denominator (atributo de fractions.Fraction)

(atributo de numbers.Rational)

DeprecationWarning

deque (clase en collections)

Deque (clase en typing)

dequeue() (método de logging.handlers.QueueListener)

DER_cert_to_PEM_cert() (en el módulo ssl)

derwin() (método de curses.window)

DES

cipher

descrgetfunc (tipo C)

description (atributo de inspect.Parameter.kind)

(atributo de sqlite3.Cursor)

description() (método de nntplib.NNTP)

descriptions() (método de nntplib.NNTP)

descriptor

descrsetfunc (tipo C)

despacho único

dest (atributo de optparse.Option)

destructor, [1]

(tipo C)

detach() (método de io.BufferedIOBase)

(método de io.TextIOBase)

(método de socket.socket)

(método de tkinter.ttk.Treeview)

(método de weakref.finalize)

Detach() (método de winreg.PyHKEY)

DETACHED_PROCESS (en el módulo subprocess)

detect_api_mismatch() (en el módulo test.support)

detect_encoding() (en el módulo tokenize)

detect_language() (método de distutils.ccompiler.CCompiler)

deterministic profiling

device_encoding() (en el módulo os)

devnull (en el módulo os)

DEVNULL (en el módulo subprocess)

devpoll() (en el módulo select)

DevpollSelector (clase en selectors)

dgettext() (en el módulo gettext)

(en el módulo locale)

dialect (atributo de csv.csvreader)

(atributo de csv.csvwriter)

Dialect (clase en csv)

Dialog (clase en msilib)

(clase en tkinter.commondialog)

(clase en tkinter.simpledialog)

diccionario

dict (2to3 fixer)

Dict (clase en ast)

(clase en typing)

dict (clase incorporada)

dict() (método de multiprocessing.managers.SyncManager)

DICT_MERGE (opcode)

DICT_UPDATE (opcode)

DictComp (clase en ast)

dictConfig() (en el módulo logging.config)

dictionary

comprehensions

display

objeto, [1], [2], [3], [4], [5], [6], [7]

type, operations on

DictReader (clase en csv)

DictWriter (clase en csv)

diff_bytes() (en el módulo difflib)

diff_files (atributo de filecmp.dircmp)

Differ (clase en difflib)

difference() (método de frozenset)

difference_update() (método de frozenset)

difflib (módulo)

digest() (en el módulo hmac)

(método de hashlib.hash)

(método de hashlib.shake)

(método de hmac.HMAC)

digest_size (atributo de hmac.HMAC)

digit() (en el módulo unicodedata)

digits (en el módulo string)

dir() (función incorporada)

(método de ftplib.FTP)

dircmp (clase en filecmp)

directory

changing

creating

deleting, [1]

site-packages

traversal, [1]

walking, [1]

Directory (clase en msilib)

(clase en tkinter.filedialog)

directory ...

compileall command line option

directory_created() (función incorporada)

DirEntry (clase en os)

DirList (clase en tkinter.tix)

dirname() (en el módulo os.path)

dirs_double_event() (método de tkinter.filedialog.FileDialog)

dirs_select_event() (método de tkinter.filedialog.FileDialog)

DirSelectBox (clase en tkinter.tix)

DirSelectDialog (clase en tkinter.tix)

DirsOnSysPath (clase en test.support)

DirTree (clase en tkinter.tix)

dis (módulo)

dis() (en el módulo dis)

(en el módulo pickletools)

(método de dis.Bytecode)

disable (pdb command)

disable() (en el módulo faulthandler)

(en el módulo gc)

(en el módulo logging)

(método de bdb.Breakpoint)

(método de profile.Profile)

disable_faulthandler() (en el módulo test.support)

disable_gc() (en el módulo test.support)

disable_interspersed_args() (método de optparse.OptionParser)

DisableReflectionKey() (en el módulo winreg)

disassemble() (en el módulo dis)

discard (atributo de http.cookiejar.Cookie)

discard() (método de frozenset)

(método de mailbox.Mailbox)

(método de mailbox.MH)

discard_buffers() (método de asynchat.async_chat)

disco() (en el módulo dis)

discover() (método de unittest.TestLoader)

disk_usage() (en el módulo shutil)

dispatch_call() (método de bdb.Bdb)

dispatch_exception() (método de bdb.Bdb)

dispatch_line() (método de bdb.Bdb)

dispatch_return() (método de bdb.Bdb)

dispatch_table (atributo de pickle.Pickler)

dispatcher (clase en asyncore)

dispatcher_with_send (clase en asyncore)

DISPLAY

display

dictionary

list

set

display (pdb command)

display_name (atributo de email.headerregistry.Address)

(atributo de email.headerregistry.Group)

displayhook() (en el módulo sys)

dist() (en el módulo math)

distance() (en el módulo turtle)

distb() (en el módulo dis)

Distribution (clase en distutils.core)

distutils (módulo)

distutils.archive_util (módulo)

distutils.bcppcompiler (módulo)

distutils.ccompiler (módulo)

distutils.cmd (módulo)

distutils.command (módulo)

distutils.command.bdist (módulo)

distutils.command.bdist_dumb (módulo)

distutils.command.bdist_msi (módulo)

distutils.command.bdist_packager (módulo)

distutils.command.bdist_rpm (módulo)

distutils.command.bdist_wininst (módulo)

distutils.command.build (módulo)

distutils.command.build_clib (módulo)

distutils.command.build_ext (módulo)

distutils.command.build_py (módulo)

distutils.command.build_scripts (módulo)

distutils.command.check (módulo)

distutils.command.clean (módulo)

distutils.command.config (módulo)

distutils.command.install (módulo)

distutils.command.install_data (módulo)

distutils.command.install_headers (módulo)

distutils.command.install_lib (módulo)

distutils.command.install_scripts (módulo)

distutils.command.register (módulo)

distutils.command.sdist (módulo)

distutils.core (módulo)

distutils.cygwinccompiler (módulo)

distutils.debug (módulo)

distutils.dep_util (módulo)

distutils.dir_util (módulo)

distutils.dist (módulo)

distutils.errors (módulo)

distutils.extension (módulo)

distutils.fancy_getopt (módulo)

distutils.file_util (módulo)

distutils.filelist (módulo)

distutils.log (módulo)

distutils.msvccompiler (módulo)

distutils.spawn (módulo)

distutils.sysconfig (módulo)

distutils.text_file (módulo)

distutils.unixccompiler (módulo)

distutils.util (módulo)

distutils.version (módulo)

DISTUTILS_DEBUG

Div (clase en ast)

divide() (método de decimal.Context)

divide_int() (método de decimal.Context)

division

DivisionByZero (clase en decimal)

división entera

divmod

función incorporada, [1], [2]

divmod() (función incorporada)

(método de decimal.Context)

DllCanUnloadNow() (en el módulo ctypes)

DllGetClassObject() (en el módulo ctypes)

dllhandle (en el módulo sys)

dnd_start() (en el módulo tkinter.dnd)

DndHandler (clase en tkinter.dnd)

dngettext() (en el módulo gettext)

dnpgettext() (en el módulo gettext)

do_clear() (método de bdb.Bdb)

do_command() (método de curses.textpad.Textbox)

do_GET() (método de http.server.SimpleHTTPRequestHandler)

do_handshake() (método de ssl.SSLSocket)

do_HEAD() (método de http.server.SimpleHTTPRequestHandler)

do_POST() (método de http.server.CGIHTTPRequestHandler)

doc (atributo de json.JSONDecodeError)

doc_header (atributo de cmd.Cmd)

DocCGIXMLRPCRequestHandler (clase en xmlrpc.server)

DocFileSuite() (en el módulo doctest)

doClassCleanups() (método de clase de unittest.TestCase)

doCleanups() (método de unittest.TestCase)

docmd() (método de smtplib.SMTP)

docstring, [1]

(atributo de doctest.DocTest)

docstrings, [1]

DocTest (clase en doctest)

doctest (módulo)

DocTestFailure

DocTestFinder (clase en doctest)

DocTestParser (clase en doctest)

DocTestRunner (clase en doctest)

DocTestSuite() (en el módulo doctest)

doctype() (método de xml.etree.ElementTree.TreeBuilder)

documentation

generation

online

documentation string

documentation strings, [1]

documentElement (atributo de xml.dom.Document)

DocXMLRPCRequestHandler (clase en xmlrpc.server)

DocXMLRPCServer (clase en xmlrpc.server)

domain (atributo de email.headerregistry.Address)

(atributo de tracemalloc.DomainFilter)

(atributo de tracemalloc.Filter)

(atributo de tracemalloc.Trace)

domain_initial_dot (atributo de http.cookiejar.Cookie)

domain_return_ok() (método de http.cookiejar.CookiePolicy)

domain_specified (atributo de http.cookiejar.Cookie)

DomainFilter (clase en tracemalloc)

DomainLiberal (atributo de http.cookiejar.DefaultCookiePolicy)

DomainRFC2965Match (atributo de http.cookiejar.DefaultCookiePolicy)

DomainStrict (atributo de http.cookiejar.DefaultCookiePolicy)

DomainStrictNoDots (atributo de http.cookiejar.DefaultCookiePolicy)

DomainStrictNonDomain (atributo de http.cookiejar.DefaultCookiePolicy)

DOMEventStream (clase en xml.dom.pulldom)

DOMException

doModuleCleanups() (en el módulo unittest)

DomstringSizeErr

done() (en el módulo turtle)

(método de asyncio.Future)

(método de asyncio.Task)

(método de concurrent.futures.Future)

(método de graphlib.TopologicalSorter)

(método de xdrlib.Unpacker)

DONT_ACCEPT_BLANKLINE (en el módulo doctest)

DONT_ACCEPT_TRUE_FOR_1 (en el módulo doctest)

dont_write_bytecode (en el módulo sys)

doRollover() (método de logging.handlers.RotatingFileHandler)

(método de logging.handlers.TimedRotatingFileHandler)

DOT (en el módulo token)

dot() (en el módulo turtle)

DOTALL (en el módulo re)

doublequote (atributo de csv.Dialect)

DOUBLESLASH (en el módulo token)

DOUBLESLASHEQUAL (en el módulo token)

DOUBLESTAR (en el módulo token)

DOUBLESTAREQUAL (en el módulo token)

doupdate() (en el módulo curses)

down (pdb command)

down() (en el módulo turtle)

dpgettext() (en el módulo gettext)

drain() (método de asyncio.StreamWriter)

drop_whitespace (atributo de textwrap.TextWrapper)

dropwhile() (en el módulo itertools)

dst() (método de datetime.datetime)

(método de datetime.time)

(método de datetime.timezone)

(método de datetime.tzinfo)

DTDHandler (clase en xml.sax.handler)

DumbWriter (clase en formatter)

dump() (en el módulo ast)

(en el módulo json)

(en el módulo marshal)

(en el módulo pickle)

(en el módulo plistlib)

(en el módulo xml.etree.ElementTree)

(método de pickle.Pickler)

(método de tracemalloc.Snapshot)

dump_stats() (método de profile.Profile)

(método de pstats.Stats)

dump_traceback() (en el módulo faulthandler)

dump_traceback_later() (en el módulo faulthandler)

dumps() (en el módulo json)

(en el módulo marshal)

(en el módulo pickle)

(en el módulo plistlib)

(en el módulo xmlrpc.client)

dup() (en el módulo os)

(método de socket.socket)

dup2() (en el módulo os)

DUP_TOP (opcode)

DUP_TOP_TWO (opcode)

DuplicateOptionError

DuplicateSectionError

dwFlags (atributo de subprocess.STARTUPINFO)

DynamicClassAttribute() (en el módulo types)

E

e

in numeric literal

e (en el módulo cmath)

(en el módulo math)

E2BIG (en el módulo errno)

EACCES (en el módulo errno)

EADDRINUSE (en el módulo errno)

EADDRNOTAVAIL (en el módulo errno)

EADV (en el módulo errno)

EAFNOSUPPORT (en el módulo errno)

EAFP

EAGAIN (en el módulo errno)

EALREADY (en el módulo errno)

east_asian_width() (en el módulo unicodedata)

EBADE (en el módulo errno)

EBADF (en el módulo errno)

EBADFD (en el módulo errno)

EBADMSG (en el módulo errno)

EBADR (en el módulo errno)

EBADRQC (en el módulo errno)

EBADSLT (en el módulo errno)

EBFONT (en el módulo errno)

EBUSY (en el módulo errno)

ECHILD (en el módulo errno)

echo() (en el módulo curses)

echochar() (método de curses.window)

ECHRNG (en el módulo errno)

ECOMM (en el módulo errno)

ECONNABORTED (en el módulo errno)

ECONNREFUSED (en el módulo errno)

ECONNRESET (en el módulo errno)

EDEADLK (en el módulo errno)

EDEADLOCK (en el módulo errno)

EDESTADDRREQ (en el módulo errno)

edit() (método de curses.textpad.Textbox)

EDOM (en el módulo errno)

EDOTDOT (en el módulo errno)

EDQUOT (en el módulo errno)

EEXIST (en el módulo errno)

EFAULT (en el módulo errno)

EFBIG (en el módulo errno)

effective() (en el módulo bdb)

ehlo() (método de smtplib.SMTP)

ehlo_or_helo_if_needed() (método de smtplib.SMTP)

EHOSTDOWN (en el módulo errno)

EHOSTUNREACH (en el módulo errno)

EIDRM (en el módulo errno)

EILSEQ (en el módulo errno)

EINPROGRESS (en el módulo errno)

EINTR (en el módulo errno)

EINVAL (en el módulo errno)

EIO (en el módulo errno)

EISCONN (en el módulo errno)

EISDIR (en el módulo errno)

EISNAM (en el módulo errno)

EL2HLT (en el módulo errno)

EL2NSYNC (en el módulo errno)

EL3HLT (en el módulo errno)

EL3RST (en el módulo errno)

Element (clase en xml.etree.ElementTree)

element_create() (método de tkinter.ttk.Style)

element_names() (método de tkinter.ttk.Style)

element_options() (método de tkinter.ttk.Style)

ElementDeclHandler() (método de xml.parsers.expat.xmlparser)

elements() (método de collections.Counter)

ElementTree (clase en xml.etree.ElementTree)

ELIBACC (en el módulo errno)

ELIBBAD (en el módulo errno)

ELIBEXEC (en el módulo errno)

ELIBMAX (en el módulo errno)

ELIBSCN (en el módulo errno)

elif

palabra clave

Ellinghouse, Lance

Ellipsis

objeto

ELLIPSIS (en el módulo doctest)

(en el módulo token)

Ellipsis (variable incorporada)

ELNRNG (en el módulo errno)

ELOOP (en el módulo errno)

else

conditional expression

dangling

palabra clave, [1], [2], [3], [4], [5]

email (módulo)

email.charset (módulo)

email.contentmanager (módulo)

email.encoders (módulo)

email.errors (módulo)

email.generator (módulo)

email.header (módulo)

email.headerregistry (módulo)

email.iterators (módulo)

email.message (módulo)

email.mime (módulo)

email.parser (módulo)

email.policy (módulo)

email.utils (módulo)

EmailMessage (clase en email.message)

EmailPolicy (clase en email.policy)

EMFILE (en el módulo errno)

emit() (método de logging.FileHandler)

(método de logging.Handler)

(método de logging.handlers.BufferingHandler)

(método de logging.handlers.DatagramHandler)

(método de logging.handlers.HTTPHandler)

(método de logging.handlers.NTEventLogHandler)

(método de logging.handlers.QueueHandler)

(método de logging.handlers.RotatingFileHandler)

(método de logging.handlers.SMTPHandler)

(método de logging.handlers.SocketHandler)

(método de logging.handlers.SysLogHandler)

(método de logging.handlers.TimedRotatingFileHandler)

(método de logging.handlers.WatchedFileHandler)

(método de logging.NullHandler)

(método de logging.StreamHandler)

EMLINK (en el módulo errno)

Empty

empty

list

tuple, [1]

empty (atributo de inspect.Parameter)

(atributo de inspect.Signature)

empty() (método de asyncio.Queue)

(método de multiprocessing.Queue)

(método de multiprocessing.SimpleQueue)

(método de queue.Queue)

(método de queue.SimpleQueue)

(método de sched.scheduler)

EMPTY_NAMESPACE (en el módulo xml.dom)

emptyline() (método de cmd.Cmd)

EMSGSIZE (en el módulo errno)

EMULTIHOP (en el módulo errno)

enable (pdb command)

enable() (en el módulo cgitb)

(en el módulo faulthandler)

(en el módulo gc)

(método de bdb.Breakpoint)

(método de imaplib.IMAP4)

(método de profile.Profile)

enable_callback_tracebacks() (en el módulo sqlite3)

enable_interspersed_args() (método de optparse.OptionParser)

enable_load_extension() (método de sqlite3.Connection)

enable_traversal() (método de tkinter.ttk.Notebook)

ENABLE_USER_SITE (en el módulo site)

EnableControlFlowGuard

EnableReflectionKey() (en el módulo winreg)

ENAMETOOLONG (en el módulo errno)

ENAVAIL (en el módulo errno)

enclose() (método de curses.window)

encode

Codecs

encode (atributo de codecs.CodecInfo)

encode() (en el módulo base64)

(en el módulo codecs)

(en el módulo quopri)

(en el módulo uu)

(método de codecs.Codec)

(método de codecs.IncrementalEncoder)

(método de email.header.Header)

(método de json.JSONEncoder)

(método de str)

(método de xmlrpc.client.Binary)

(método de xmlrpc.client.DateTime)

encode_7or8bit() (en el módulo email.encoders)

encode_base64() (en el módulo email.encoders)

encode_noop() (en el módulo email.encoders)

encode_quopri() (en el módulo email.encoders)

encode_rfc2231() (en el módulo email.utils)

encodebytes() (en el módulo base64)

EncodedFile() (en el módulo codecs)

encodePriority() (método de logging.handlers.SysLogHandler)

encodestring() (en el módulo quopri)

encoding

base64

quoted-printable

encoding (atributo de curses.window)

(atributo de io.TextIOBase)

(atributo de UnicodeError)

ENCODING (en el módulo tarfile)

(en el módulo token)

encoding declarations (source file)

encodings.idna (módulo)

encodings.mbcs (módulo)

encodings.utf_8_sig (módulo)

encodings_map (atributo de mimetypes.MimeTypes)

(en el módulo mimetypes)

end (atributo de UnicodeError)

end() (método de re.Match)

(método de xml.etree.ElementTree.TreeBuilder)

END_ASYNC_FOR (opcode)

end_col_offset (atributo de ast.AST)

end_fill() (en el módulo turtle)

end_headers() (método de http.server.BaseHTTPRequestHandler)

end_lineno (atributo de ast.AST)

end_ns() (método de xml.etree.ElementTree.TreeBuilder)

end_paragraph() (método de formatter.formatter)

end_poly() (en el módulo turtle)

EndCdataSectionHandler() (método de xml.parsers.expat.xmlparser)

EndDoctypeDeclHandler() (método de xml.parsers.expat.xmlparser)

endDocument() (método de xml.sax.handler.ContentHandler)

endElement() (método de xml.sax.handler.ContentHandler)

EndElementHandler() (método de xml.parsers.expat.xmlparser)

endElementNS() (método de xml.sax.handler.ContentHandler)

endheaders() (método de http.client.HTTPConnection)

ENDMARKER (en el módulo token)

EndNamespaceDeclHandler() (método de xml.parsers.expat.xmlparser)

endpos (atributo de re.Match)

endPrefixMapping() (método de xml.sax.handler.ContentHandler)

endswith() (método de bytearray)

(método de bytes)

(método de str)

endwin() (en el módulo curses)

ENETDOWN (en el módulo errno)

ENETRESET (en el módulo errno)

ENETUNREACH (en el módulo errno)

ENFILE (en el módulo errno)

ENOANO (en el módulo errno)

ENOBUFS (en el módulo errno)

ENOCSI (en el módulo errno)

ENODATA (en el módulo errno)

ENODEV (en el módulo errno)

ENOENT (en el módulo errno)

ENOEXEC (en el módulo errno)

ENOLCK (en el módulo errno)

ENOLINK (en el módulo errno)

ENOMEM (en el módulo errno)

ENOMSG (en el módulo errno)

ENONET (en el módulo errno)

ENOPKG (en el módulo errno)

ENOPROTOOPT (en el módulo errno)

ENOSPC (en el módulo errno)

ENOSR (en el módulo errno)

ENOSTR (en el módulo errno)

ENOSYS (en el módulo errno)

ENOTBLK (en el módulo errno)

ENOTCONN (en el módulo errno)

ENOTDIR (en el módulo errno)

ENOTEMPTY (en el módulo errno)

ENOTNAM (en el módulo errno)

ENOTSOCK (en el módulo errno)

ENOTTY (en el módulo errno)

ENOTUNIQ (en el módulo errno)

enqueue() (método de logging.handlers.QueueHandler)

enqueue_sentinel() (método de logging.handlers.QueueListener)

ensure_directories() (método de venv.EnvBuilder)

ensure_future() (en el módulo asyncio)

ensurepip (módulo)

enter() (método de sched.scheduler)

enter_async_context() (método de contextlib.AsyncExitStack)

enter_context() (método de contextlib.ExitStack)

enterabs() (método de sched.scheduler)

entities (atributo de xml.dom.DocumentType)

EntityDeclHandler() (método de xml.parsers.expat.xmlparser)

entitydefs (en el módulo html.entities)

EntityResolver (clase en xml.sax.handler)

entorno virtual

entrada de ruta

Enum (clase en enum)

enum (módulo)

enum_certificates() (en el módulo ssl)

enum_crls() (en el módulo ssl)

enumerate() (en el módulo threading)

(función incorporada)

EnumKey() (en el módulo winreg)

EnumValue() (en el módulo winreg)

EnvBuilder (clase en venv)

environ (en el módulo os)

(en el módulo posix)

environb (en el módulo os)

environment

environment variables

deleting

setting

EnvironmentError

Environments

virtual

EnvironmentVarGuard (clase en test.support)

ENXIO (en el módulo errno)

eof (atributo de bz2.BZ2Decompressor)

(atributo de lzma.LZMADecompressor)

(atributo de shlex.shlex)

(atributo de ssl.MemoryBIO)

(atributo de zlib.Decompress)

eof_received() (método de asyncio.BufferedProtocol)

(método de asyncio.Protocol)

EOFError

(built-in exception)

EOPNOTSUPP (en el módulo errno)

EOVERFLOW (en el módulo errno)

EPERM (en el módulo errno)

EPFNOSUPPORT (en el módulo errno)

epilogue (atributo de email.message.EmailMessage)

(atributo de email.message.Message)

EPIPE (en el módulo errno)

epoch

epoll() (en el módulo select)

EpollSelector (clase en selectors)

EPROTO (en el módulo errno)

EPROTONOSUPPORT (en el módulo errno)

EPROTOTYPE (en el módulo errno)

Eq (clase en ast)

eq() (en el módulo operator)

EQEQUAL (en el módulo token)

EQUAL (en el módulo token)

ERA (en el módulo locale)

ERA_D_FMT (en el módulo locale)

ERA_D_T_FMT (en el módulo locale)

ERA_T_FMT (en el módulo locale)

ERANGE (en el módulo errno)

erase() (método de curses.window)

erasechar() (en el módulo curses)

EREMCHG (en el módulo errno)

EREMOTE (en el módulo errno)

EREMOTEIO (en el módulo errno)

ERESTART (en el módulo errno)

erf() (en el módulo math)

erfc() (en el módulo math)

EROFS (en el módulo errno)

ERR (en el módulo curses)

errcheck (atributo de ctypes._FuncPtr)

errcode (atributo de xmlrpc.client.ProtocolError)

errmsg (atributo de xmlrpc.client.ProtocolError)

errno

módulo

errno (atributo de OSError)

(módulo)

Error, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13]

error, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16]

error handler's name

backslashreplace

ignore

namereplace

replace

strict

surrogateescape

surrogatepass

xmlcharrefreplace

error handling

error() (en el módulo logging)

(método de argparse.ArgumentParser)

(método de logging.Logger)

(método de urllib.request.OpenerDirector)

(método de xml.sax.handler.ErrorHandler)

error_body (atributo de wsgiref.handlers.BaseHandler)

error_content_type (atributo de http.server.BaseHTTPRequestHandler)

error_headers (atributo de wsgiref.handlers.BaseHandler)

error_leader() (método de shlex.shlex)

error_message_format (atributo de http.server.BaseHTTPRequestHandler)

error_output() (método de wsgiref.handlers.BaseHandler)

error_perm

error_proto, [1]

error_received() (método de asyncio.DatagramProtocol)

error_reply

error_status (atributo de wsgiref.handlers.BaseHandler)

error_temp

ErrorByteIndex (atributo de xml.parsers.expat.xmlparser)

ErrorCode (atributo de xml.parsers.expat.xmlparser)

errorcode (en el módulo errno)

ErrorColumnNumber (atributo de xml.parsers.expat.xmlparser)

ErrorHandler (clase en xml.sax.handler)

errorlevel (atributo de tarfile.TarFile)

ErrorLineNumber (atributo de xml.parsers.expat.xmlparser)

Errors

logging

errors

(atributo de io.TextIOBase)

(atributo de unittest.TestLoader)

(atributo de unittest.TestResult)

ErrorString() (en el módulo xml.parsers.expat)

ERRORTOKEN (en el módulo token)

escape (atributo de shlex.shlex)

escape sequence

escape() (en el módulo glob)

(en el módulo html)

(en el módulo re)

(en el módulo xml.sax.saxutils)

escapechar (atributo de csv.Dialect)

escapedquotes (atributo de shlex.shlex)

ESHUTDOWN (en el módulo errno)

ESOCKTNOSUPPORT (en el módulo errno)

espacio de nombres

especificador de módulo

ESPIPE (en el módulo errno)

ESRCH (en el módulo errno)

ESRMNT (en el módulo errno)

ESTALE (en el módulo errno)

ESTRPIPE (en el módulo errno)

ETIME (en el módulo errno)

ETIMEDOUT (en el módulo errno)

Etiny() (método de decimal.Context)

ETOOMANYREFS (en el módulo errno)

Etop() (método de decimal.Context)

ETXTBSY (en el módulo errno)

EUCLEAN (en el módulo errno)

EUNATCH (en el módulo errno)

EUSERS (en el módulo errno)

eval

función incorporada, [1], [2], [3], [4], [5]

eval() (función incorporada)

evaluation

order

Event (clase en asyncio)

(clase en multiprocessing)

(clase en threading)

event scheduling

event() (método de msilib.Control)

Event() (método de multiprocessing.managers.SyncManager)

events (atributo de selectors.SelectorKey)

(widgets)

EWOULDBLOCK (en el módulo errno)

EX_CANTCREAT (en el módulo os)

EX_CONFIG (en el módulo os)

EX_DATAERR (en el módulo os)

EX_IOERR (en el módulo os)

EX_NOHOST (en el módulo os)

EX_NOINPUT (en el módulo os)

EX_NOPERM (en el módulo os)

EX_NOTFOUND (en el módulo os)

EX_NOUSER (en el módulo os)

EX_OK (en el módulo os)

EX_OSERR (en el módulo os)

EX_OSFILE (en el módulo os)

EX_PROTOCOL (en el módulo os)

EX_SOFTWARE (en el módulo os)

EX_TEMPFAIL (en el módulo os)

EX_UNAVAILABLE (en el módulo os)

EX_USAGE (en el módulo os)

example (atributo de doctest.DocTestFailure)

(atributo de doctest.UnexpectedException)

Example (clase en doctest)

examples (atributo de doctest.DocTest)

exc_info (atributo de doctest.UnexpectedException)

(in module sys)

exc_info() (en el módulo sys)

(in module sys)

exc_msg (atributo de doctest.Example)

exc_type (atributo de traceback.TracebackException)

excel (clase en csv)

excel_tab (clase en csv)

excepción

AssertionError

AttributeError

GeneratorExit, [1]

ImportError

NameError

StopAsyncIteration

StopIteration, [1]

TypeError

ValueError

ZeroDivisionError

except

palabra clave

sentencia

except (2to3 fixer)

ExceptHandler (clase en ast)

excepthook() (en el módulo sys)

(en el módulo threading)

(in module sys)

Exception

exception, [1]

chaining

handler

raising

EXCEPTION (en el módulo tkinter)

exception handler

exception() (en el módulo logging)

(método de asyncio.Future)

(método de asyncio.Task)

(método de concurrent.futures.Future)

(método de logging.Logger)

exceptions

in CGI scripts

exclusive

or

EXDEV (en el módulo errno)

exec

función incorporada, [1], [2], [3]

exec (2to3 fixer)

exec() (función incorporada)

exec_module (función C)

exec_module() (método de importlib.abc.InspectLoader)

(método de importlib.abc.Loader)

(método de importlib.abc.SourceLoader)

(método de importlib.machinery.ExtensionFileLoader)

exec_prefix, [1], [2]

EXEC_PREFIX (en el módulo distutils.sysconfig)

exec_prefix (en el módulo sys)

execfile (2to3 fixer)

execl() (en el módulo os)

execle() (en el módulo os)

execlp() (en el módulo os)

execlpe() (en el módulo os)

executable (en el módulo sys)

(in module sys)

Executable Zip Files

executable_filename() (método de distutils.ccompiler.CCompiler)

execute() (en el módulo distutils.util)

(método de distutils.ccompiler.CCompiler)

Execute() (método de msilib.View)

execute() (método de sqlite3.Connection)

(método de sqlite3.Cursor)

executemany() (método de sqlite3.Connection)

(método de sqlite3.Cursor)

executescript() (método de sqlite3.Connection)

(método de sqlite3.Cursor)

execution

frame, [1]

restricted

stack

execution model

ExecutionLoader (clase en importlib.abc)

Executor (clase en concurrent.futures)

execv() (en el módulo os)

execve() (en el módulo os)

execvp() (en el módulo os)

execvpe() (en el módulo os)

ExFileSelectBox (clase en tkinter.tix)

EXFULL (en el módulo errno)

exists() (en el módulo os.path)

(método de pathlib.Path)

(método de tkinter.ttk.Treeview)

(método de zipfile.Path)

exit (variable incorporada)

exit()

(en el módulo _thread)

(en el módulo sys)

(método de argparse.ArgumentParser)

exitcode (atributo de multiprocessing.Process)

exitfunc (2to3 fixer)

exitonclick() (en el módulo turtle)

ExitStack (clase en contextlib)

exp() (en el módulo cmath)

(en el módulo math)

(método de decimal.Context)

(método de decimal.Decimal)

expand() (método de re.Match)

expand_tabs (atributo de textwrap.TextWrapper)

ExpandEnvironmentStrings() (en el módulo winreg)

expandNode() (método de xml.dom.pulldom.DOMEventStream)

expandtabs() (método de bytearray)

(método de bytes)

(método de str)

expanduser() (en el módulo os.path)

(método de pathlib.Path)

expandvars() (en el módulo os.path)

Expat

ExpatError

expect() (método de telnetlib.Telnet)

expected (atributo de asyncio.IncompleteReadError)

expectedFailure() (en el módulo unittest)

expectedFailures (atributo de unittest.TestResult)

expires (atributo de http.cookiejar.Cookie)

exploded (atributo de ipaddress.IPv4Address)

(atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Address)

(atributo de ipaddress.IPv6Network)

expm1() (en el módulo math)

expovariate() (en el módulo random)

Expr (clase en ast)

expr() (en el módulo parser)

expresión

expresión generadora

expression

Conditional

conditional

generator

lambda, [1]

list, [1], [2]

statement

yield

expunge() (método de imaplib.IMAP4)

extend() (método de array.array)

(método de collections.deque)

(método de xml.etree.ElementTree.Element)

(sequence method)

extend_path() (en el módulo pkgutil)

EXTENDED_ARG (opcode)

ExtendedContext (clase en decimal)

ExtendedInterpolation (clase en configparser)

extendleft() (método de collections.deque)

extension

module

Extension (clase en distutils.core)

EXTENSION_SUFFIXES (en el módulo importlib.machinery)

ExtensionFileLoader (clase en importlib.machinery)

extensions_map (atributo de http.server.SimpleHTTPRequestHandler)

External Data Representation, [1]

external_attr (atributo de zipfile.ZipInfo)

ExternalClashError

ExternalEntityParserCreate() (método de xml.parsers.expat.xmlparser)

ExternalEntityRefHandler() (método de xml.parsers.expat.xmlparser)

extra (atributo de zipfile.ZipInfo)

extract() (método de clase de traceback.StackSummary)

(método de tarfile.TarFile)

(método de zipfile.ZipFile)

extract_cookies() (método de http.cookiejar.CookieJar)

extract_stack() (en el módulo traceback)

extract_tb() (en el módulo traceback)

extract_version (atributo de zipfile.ZipInfo)

extractall() (método de tarfile.TarFile)

(método de zipfile.ZipFile)

ExtractError

extractfile() (método de tarfile.TarFile)

extraction_filter (atributo de tarfile.TarFile)

extsep (en el módulo os)

F

f"

formatted string literal

f'

formatted string literal

f-string, [1]

f_back (frame attribute)

f_builtins (frame attribute)

f_code (frame attribute)

f_contiguous (atributo de memoryview)

f_globals (frame attribute)

f_lasti (frame attribute)

f_lineno (frame attribute)

f_locals (frame attribute)

F_LOCK (en el módulo os)

F_OK (en el módulo os)

F_TEST (en el módulo os)

F_TLOCK (en el módulo os)

f_trace (frame attribute)

f_trace_lines (frame attribute)

f_trace_opcodes (frame attribute)

F_ULOCK (en el módulo os)

fabs() (en el módulo math)

factorial() (en el módulo math)

factory() (método de clase de importlib.util.LazyLoader)

fail() (método de unittest.TestCase)

FAIL_FAST (en el módulo doctest)

failfast (atributo de unittest.TestResult)

failureException (atributo de unittest.TestCase)

failures (atributo de unittest.TestResult)

FakePath (clase en test.support)

False, [1], [2]

false

False (Built-in object)

(variable incorporada)

families() (en el módulo tkinter.font)

family (atributo de socket.socket)

fancy_getopt() (en el módulo distutils.fancy_getopt)

FancyGetopt (clase en distutils.fancy_getopt)

FancyURLopener (clase en urllib.request)

fast (atributo de pickle.Pickler)

FastChildWatcher (clase en asyncio)

fatalError() (método de xml.sax.handler.ErrorHandler)

Fault (clase en xmlrpc.client)

faultCode (atributo de xmlrpc.client.Fault)

faulthandler (módulo)

faultString (atributo de xmlrpc.client.Fault)

fchdir() (en el módulo os)

fchmod() (en el módulo os)

fchown() (en el módulo os)

FCICreate() (en el módulo msilib)

fcntl (módulo)

fcntl() (en el módulo fcntl)

fd (atributo de selectors.SelectorKey)

fd() (en el módulo turtle)

fd_count() (en el módulo test.support)

fdatasync() (en el módulo os)

fdopen() (en el módulo os)

Feature (clase en msilib)

feature_external_ges (en el módulo xml.sax.handler)

feature_external_pes (en el módulo xml.sax.handler)

feature_namespace_prefixes (en el módulo xml.sax.handler)

feature_namespaces (en el módulo xml.sax.handler)

feature_string_interning (en el módulo xml.sax.handler)

feature_validation (en el módulo xml.sax.handler)

feed() (método de email.parser.BytesFeedParser)

(método de html.parser.HTMLParser)

(método de xml.etree.ElementTree.XMLParser)

(método de xml.etree.ElementTree.XMLPullParser)

(método de xml.sax.xmlreader.IncrementalParser)

FeedParser (clase en email.parser)

fetch() (método de imaplib.IMAP4)

Fetch() (método de msilib.View)

fetchall() (método de sqlite3.Cursor)

fetchmany() (método de sqlite3.Cursor)

fetchone() (método de sqlite3.Cursor)

fflags (atributo de select.kevent)

Field (clase en dataclasses)

field() (en el módulo dataclasses)

field_size_limit() (en el módulo csv)

fieldnames (atributo de csv.csvreader)

fields (atributo de uuid.UUID)

fields() (en el módulo dataclasses)

file

.ini

.pdbrc

byte-code, [1]

configuration

copying

debugger configuration

gzip command line option

large files

mime.types

modes

objeto, [1]

path configuration

plist

temporary

file (atributo de pyclbr.Class)

(atributo de pyclbr.Function)

file ...

compileall command line option

file control

UNIX

file name

temporary

file object

io module

open() built-in function

FILE_ATTRIBUTE_ARCHIVE (en el módulo stat)

FILE_ATTRIBUTE_COMPRESSED (en el módulo stat)

FILE_ATTRIBUTE_DEVICE (en el módulo stat)

FILE_ATTRIBUTE_DIRECTORY (en el módulo stat)

FILE_ATTRIBUTE_ENCRYPTED (en el módulo stat)

FILE_ATTRIBUTE_HIDDEN (en el módulo stat)

FILE_ATTRIBUTE_INTEGRITY_STREAM (en el módulo stat)

FILE_ATTRIBUTE_NO_SCRUB_DATA (en el módulo stat)

FILE_ATTRIBUTE_NORMAL (en el módulo stat)

FILE_ATTRIBUTE_NOT_CONTENT_INDEXED (en el módulo stat)

FILE_ATTRIBUTE_OFFLINE (en el módulo stat)

FILE_ATTRIBUTE_READONLY (en el módulo stat)

FILE_ATTRIBUTE_REPARSE_POINT (en el módulo stat)

FILE_ATTRIBUTE_SPARSE_FILE (en el módulo stat)

FILE_ATTRIBUTE_SYSTEM (en el módulo stat)

FILE_ATTRIBUTE_TEMPORARY (en el módulo stat)

FILE_ATTRIBUTE_VIRTUAL (en el módulo stat)

file_created() (función incorporada)

file_dispatcher (clase en asyncore)

file_open() (método de urllib.request.FileHandler)

file_size (atributo de zipfile.ZipInfo)

file_wrapper (clase en asyncore)

filecmp (módulo)

fileConfig() (en el módulo logging.config)

FileCookieJar (clase en http.cookiejar)

FileDialog (clase en tkinter.filedialog)

FileEntry (clase en tkinter.tix)

FileExistsError

FileFinder (clase en importlib.machinery)

FileHandler (clase en logging)

(clase en urllib.request)

FileInput (clase en fileinput)

fileinput (módulo)

FileIO (clase en io)

filelineno() (en el módulo fileinput)

FileLoader (clase en importlib.abc)

filemode() (en el módulo stat)

filename (atributo de doctest.DocTest)

(atributo de http.cookiejar.FileCookieJar)

(atributo de OSError)

(atributo de SyntaxError)

(atributo de traceback.TracebackException)

(atributo de tracemalloc.Frame)

(atributo de zipfile.ZipFile)

(atributo de zipfile.ZipInfo)

filename() (en el módulo fileinput)

filename2 (atributo de OSError)

filename_only (en el módulo tabnanny)

filename_pattern (atributo de tracemalloc.Filter)

filenames

pathname expansion

wildcard expansion

fileno() (en el módulo fileinput)

(método de http.client.HTTPResponse)

(método de io.IOBase)

(método de multiprocessing.connection.Connection)

(método de ossaudiodev.oss_audio_device)

(método de ossaudiodev.oss_mixer_device)

(método de select.devpoll)

(método de select.epoll)

(método de select.kqueue)

(método de selectors.DevpollSelector)

(método de selectors.EpollSelector)

(método de selectors.KqueueSelector)

(método de socket.socket)

(método de socketserver.BaseServer)

(método de telnetlib.Telnet)

FileNotFoundError

fileobj (atributo de selectors.SelectorKey)

files() (en el módulo importlib.resources)

files_double_event() (método de tkinter.filedialog.FileDialog)

files_select_event() (método de tkinter.filedialog.FileDialog)

FileSelectBox (clase en tkinter.tix)

FileType (clase en argparse)

FileWrapper (clase en wsgiref.util)

fill() (en el módulo textwrap)

(método de textwrap.TextWrapper)

fillcolor() (en el módulo turtle)

filling() (en el módulo turtle)

filter (2to3 fixer)

(atributo de select.kevent)

Filter (clase en logging)

(clase en tracemalloc)

filter() (en el módulo curses)

(en el módulo fnmatch)

(función incorporada)

(método de logging.Filter)

(método de logging.Handler)

(método de logging.Logger)

filter_command() (método de tkinter.filedialog.FileDialog)

FILTER_DIR (en el módulo unittest.mock)

filter_traces() (método de tracemalloc.Snapshot)

FilterError

filterfalse() (en el módulo itertools)

filterwarnings() (en el módulo warnings)

Final (en el módulo typing)

final() (en el módulo typing)

finalization, of objects

finalize (clase en weakref)

finalize_options() (método de distutils.cmd.Command)

finalizer

finally

palabra clave, [1], [2], [3], [4]

find() (en el módulo gettext)

(método de bytearray)

(método de bytes)

(método de doctest.DocTestFinder)

(método de mmap.mmap)

(método de str)

(método de xml.etree.ElementTree.Element)

(método de xml.etree.ElementTree.ElementTree)

find_class() (método de pickle.Unpickler)

(pickle protocol)

find_library() (en el módulo ctypes.util)

find_library_file() (método de distutils.ccompiler.CCompiler)

find_loader() (en el módulo importlib)

(en el módulo pkgutil)

(método de importlib.abc.PathEntryFinder)

(método de importlib.machinery.FileFinder)

find_longest_match() (método de difflib.SequenceMatcher)

find_module() (en el módulo imp)

(método de clase de importlib.machinery.PathFinder)

(método de imp.NullImporter)

(método de importlib.abc.Finder)

(método de importlib.abc.MetaPathFinder)

(método de importlib.abc.PathEntryFinder)

(método de zipimport.zipimporter)

find_msvcrt() (en el módulo ctypes.util)

find_spec

finder

find_spec() (en el módulo importlib.util)

(método de clase de importlib.machinery.PathFinder)

(método de importlib.abc.MetaPathFinder)

(método de importlib.abc.PathEntryFinder)

(método de importlib.machinery.FileFinder)

find_unused_port() (en el módulo test.support.socket_helper)

find_user_password() (método de urllib.request.HTTPPasswordMgr)

(método de urllib.request.HTTPPasswordMgrWithPriorAuth)

findall() (en el módulo re)

(método de re.Pattern)

(método de xml.etree.ElementTree.Element)

(método de xml.etree.ElementTree.ElementTree)

findCaller() (método de logging.Logger)

finder

find_spec

Finder (clase en importlib.abc)

findfactor() (en el módulo audioop)

findfile() (en el módulo test.support)

findfit() (en el módulo audioop)

finditer() (en el módulo re)

(método de re.Pattern)

findlabels() (en el módulo dis)

findlinestarts() (en el módulo dis)

findmatch() (en el módulo mailcap)

findmax() (en el módulo audioop)

findtext() (método de xml.etree.ElementTree.Element)

(método de xml.etree.ElementTree.ElementTree)

finish() (método de socketserver.BaseRequestHandler)

(método de tkinter.dnd.DndHandler)

finish_request() (método de socketserver.BaseServer)

firstChild (atributo de xml.dom.Node)

firstkey() (método de dbm.gnu.gdbm)

firstweekday() (en el módulo calendar)

fix_missing_locations() (en el módulo ast)

fix_sentence_endings (atributo de textwrap.TextWrapper)

Flag (clase en enum)

flag_bits (atributo de zipfile.ZipInfo)

flags (atributo de re.Pattern)

(atributo de select.kevent)

(en el módulo sys)

flash() (en el módulo curses)

flatten() (método de email.generator.BytesGenerator)

(método de email.generator.Generator)

flattening

objects

float

función incorporada, [1], [2]

float (clase incorporada)

float_info (en el módulo sys)

float_repr_style (en el módulo sys)

floating point

literals

number

objeto, [1], [2]

floating point literal

FloatingPointError

FloatOperation (clase en decimal)

flock() (en el módulo fcntl)

floor() (en el módulo math)

(in module math)

FloorDiv (clase en ast)

floordiv() (en el módulo operator)

flush() (método de bz2.BZ2Compressor)

(método de formatter.writer)

(método de io.BufferedWriter)

(método de io.IOBase)

(método de logging.Handler)

(método de logging.handlers.BufferingHandler)

(método de logging.handlers.MemoryHandler)

(método de logging.StreamHandler)

(método de lzma.LZMACompressor)

(método de mailbox.Mailbox)

(método de mailbox.Maildir)

(método de mailbox.MH)

(método de mmap.mmap)

(método de zlib.Compress)

(método de zlib.Decompress)

flush_headers() (método de http.server.BaseHTTPRequestHandler)

flush_softspace() (método de formatter.formatter)

flushinp() (en el módulo curses)

FlushKey() (en el módulo winreg)

fma() (método de decimal.Context)

(método de decimal.Decimal)

fmean() (en el módulo statistics)

fmod() (en el módulo math)

FMT_BINARY (en el módulo plistlib)

FMT_XML (en el módulo plistlib)

fnmatch (módulo)

fnmatch() (en el módulo fnmatch)

fnmatchcase() (en el módulo fnmatch)

focus() (método de tkinter.ttk.Treeview)

fold (atributo de datetime.datetime)

(atributo de datetime.time)

fold() (método de email.headerregistry.BaseHeader)

(método de email.policy.Compat32)

(método de email.policy.EmailPolicy)

(método de email.policy.Policy)

fold_binary() (método de email.policy.Compat32)

(método de email.policy.EmailPolicy)

(método de email.policy.Policy)

Font (clase en tkinter.font)

for

in comprehensions

sentencia, [1], [2], [3]

For (clase en ast)

FOR_ITER (opcode)

forget() (en el módulo test.support)

(método de tkinter.ttk.Notebook)

fork() (en el módulo os)

(en el módulo pty)

ForkingMixIn (clase en socketserver)

ForkingTCPServer (clase en socketserver)

ForkingUDPServer (clase en socketserver)

forkpty() (en el módulo os)

form

lambda

Form (clase en tkinter.tix)

format (atributo de memoryview)

(atributo de multiprocessing.shared_memory.ShareableList)

(atributo de struct.Struct)

format() (built-in function)

__str__() (object method)

format() (en el módulo locale)

(función incorporada)

(método de logging.Formatter)

(método de logging.Handler)

(método de pprint.PrettyPrinter)

(método de str)

(método de string.Formatter)

(método de traceback.StackSummary)

(método de traceback.TracebackException)

(método de tracemalloc.Traceback)

format_datetime() (en el módulo email.utils)

format_exc() (en el módulo traceback)

format_exception() (en el módulo traceback)

format_exception_only() (en el módulo traceback)

(método de traceback.TracebackException)

format_field() (método de string.Formatter)

format_help() (método de argparse.ArgumentParser)

format_list() (en el módulo traceback)

format_map() (método de str)

format_stack() (en el módulo traceback)

format_stack_entry() (método de bdb.Bdb)

format_string() (en el módulo locale)

format_tb() (en el módulo traceback)

format_usage() (método de argparse.ArgumentParser)

FORMAT_VALUE (opcode)

formataddr() (en el módulo email.utils)

formatargspec() (en el módulo inspect)

formatargvalues() (en el módulo inspect)

formatdate() (en el módulo email.utils)

FormatError

FormatError() (en el módulo ctypes)

formatException() (método de logging.Formatter)

formatmonth() (método de calendar.HTMLCalendar)

(método de calendar.TextCalendar)

formatStack() (método de logging.Formatter)

formatted string literal

FormattedValue (clase en ast)

Formatter (clase en logging)

(clase en string)

formatter (módulo)

formatTime() (método de logging.Formatter)

formatting

bytearray (%)

bytes (%)

formatting, string (%)

formatwarning() (en el módulo warnings)

formatyear() (método de calendar.HTMLCalendar)

(método de calendar.TextCalendar)

formatyearpage() (método de calendar.HTMLCalendar)

Fortran contiguous, [1]

forward() (en el módulo turtle)

ForwardRef (clase en typing)

found_terminator() (método de asynchat.async_chat)

fpathconf() (en el módulo os)

fqdn (atributo de smtpd.SMTPChannel)

Fraction (clase en fractions)

fractions (módulo)

frame

execution, [1]

objeto

frame (atributo de tkinter.scrolledtext.ScrolledText)

Frame (clase en tracemalloc)

FrameSummary (clase en traceback)

FrameType (en el módulo types)

free

variable

free()

freefunc (tipo C)

freeze utility

freeze() (en el módulo gc)

freeze_support() (en el módulo multiprocessing)

frexp() (en el módulo math)

from

import statement, [1]

palabra clave, [1]

yield from expression

from_address() (método de ctypes._CData)

from_buffer() (método de ctypes._CData)

from_buffer_copy() (método de ctypes._CData)

from_bytes() (método de clase de int)

from_callable() (método de clase de inspect.Signature)

from_decimal() (método de fractions.Fraction)

from_exception() (método de clase de traceback.TracebackException)

from_file() (método de clase de zipfile.ZipInfo)

(método de clase de zoneinfo.ZoneInfo)

from_float() (método de decimal.Decimal)

(método de fractions.Fraction)

from_iterable() (método de clase de itertools.chain)

from_list() (método de clase de traceback.StackSummary)

from_param() (método de ctypes._CData)

from_samples() (método de clase de statistics.NormalDist)

from_traceback() (método de clase de dis.Bytecode)

frombuf() (método de clase de tarfile.TarInfo)

frombytes() (método de array.array)

fromfd() (en el módulo socket)

(método de select.epoll)

(método de select.kqueue)

fromfile() (método de array.array)

fromhex() (método de clase de bytearray)

(método de clase de bytes)

(método de clase de float)

fromisocalendar() (método de clase de datetime.date)

(método de clase de datetime.datetime)

fromisoformat() (método de clase de datetime.date)

(método de clase de datetime.datetime)

(método de clase de datetime.time)

fromkeys() (método de clase de dict)

(método de collections.Counter)

fromlist() (método de array.array)

fromordinal() (método de clase de datetime.date)

(método de clase de datetime.datetime)

fromshare() (en el módulo socket)

fromstring() (en el módulo xml.etree.ElementTree)

fromstringlist() (en el módulo xml.etree.ElementTree)

fromtarfile() (método de clase de tarfile.TarInfo)

fromtimestamp() (método de clase de datetime.date)

(método de clase de datetime.datetime)

fromunicode() (método de array.array)

fromutc() (método de datetime.timezone)

(método de datetime.tzinfo)

FrozenImporter (clase en importlib.machinery)

FrozenInstanceError

frozenset

objeto, [1]

FrozenSet (clase en typing)

frozenset (clase incorporada)

fs_is_case_insensitive() (en el módulo test.support)

FS_NONASCII (en el módulo test.support)

fsdecode() (en el módulo os)

fsencode() (en el módulo os)

fspath() (en el módulo os)

fstat() (en el módulo os)

fstatvfs() (en el módulo os)

fstring

fsum() (en el módulo math)

fsync() (en el módulo os)

FTP

ftplib (standard module)

protocol, [1]

FTP (clase en ftplib)

ftp_open() (método de urllib.request.FTPHandler)

FTP_TLS (clase en ftplib)

FTPHandler (clase en urllib.request)

ftplib (módulo)

ftruncate() (en el módulo os)

Full

full() (método de asyncio.Queue)

(método de multiprocessing.Queue)

(método de queue.Queue)

full_url (atributo de urllib.request.Request)

fullmatch() (en el módulo re)

(método de re.Pattern)

fully_trusted_filter() (en el módulo tarfile)

func (atributo de functools.partial)

funcattrs (2to3 fixer)

función

función clave

función corrutina

función genérica

función incorporada

__import__

abs, [1]

ascii

bytes, [1]

chr

classmethod

compile, [1], [2], [3], [4]

complex, [1]

divmod, [1], [2]

eval, [1], [2], [3], [4], [5]

exec, [1], [2], [3]

float, [1], [2]

hash, [1], [2], [3]

help

id

int, [1], [2]

len, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11]

max

min

open, [1]

ord

pow, [1], [2], [3], [4], [5]

print

range

repr, [1], [2], [3]

round

slice, [1]

staticmethod

tuple, [1]

type, [1], [2], [3]

function

annotations, [1]

anonymous

argument

call, [1], [2]

call, user-defined

definition, [1]

generator, [1]

name, [1]

objeto, [1], [2], [3], [4], [5]

user-defined

Function (clase en symtable)

FunctionDef (clase en ast)

FunctionTestCase (clase en unittest)

FunctionType (en el módulo types)

functools (módulo)

funny_files (atributo de filecmp.dircmp)

future

statement

future (2to3 fixer)

Future (clase en asyncio)

(clase en concurrent.futures)

FutureWarning

fwalk() (en el módulo os)

G

G.722

gaierror

gamma() (en el módulo math)

gammavariate() (en el módulo random)

gancho a entrada de ruta

garbage (en el módulo gc)

garbage collection

gather() (en el módulo asyncio)

(método de curses.textpad.Textbox)

gauss() (en el módulo random)

gc (módulo)

gc_collect() (en el módulo test.support)

gcd() (en el módulo math)

ge() (en el módulo operator)

gen_lib_options() (en el módulo distutils.ccompiler)

gen_preprocess_options() (en el módulo distutils.ccompiler)

gen_uuid() (en el módulo msilib)

generador

generador asincrónico

generate_help() (método de distutils.fancy_getopt.FancyGetopt)

generate_tokens() (en el módulo tokenize)

generator

expression

function, [1], [2]

iterator, [1]

objeto, [1], [2]

Generator (clase en collections.abc)

(clase en email.generator)

(clase en typing)

generator expression

GeneratorExit

excepción, [1]

GeneratorExp (clase en ast)

GeneratorType (en el módulo types)

Generic

Alias

generic

special attribute

Generic (clase en typing)

generic_visit() (método de ast.NodeVisitor)

GenericAlias

objeto

GenericAlias (clase en types)

genops() (en el módulo pickletools)

geometric_mean() (en el módulo statistics)

get() (en el módulo webbrowser)

(método de asyncio.Queue)

(método de configparser.ConfigParser)

(método de contextvars.Context)

(método de contextvars.ContextVar)

(método de dict)

(método de email.message.EmailMessage)

(método de email.message.Message)

(método de mailbox.Mailbox)

(método de multiprocessing.pool.AsyncResult)

(método de multiprocessing.Queue)

(método de multiprocessing.SimpleQueue)

(método de ossaudiodev.oss_mixer_device)

(método de queue.Queue)

(método de queue.SimpleQueue)

(método de tkinter.ttk.Combobox)

(método de tkinter.ttk.Spinbox)

(método de types.MappingProxyType)

(método de xml.etree.ElementTree.Element)

GET_AITER (opcode)

get_all() (método de email.message.EmailMessage)

(método de email.message.Message)

(método de wsgiref.headers.Headers)

get_all_breaks() (método de bdb.Bdb)

get_all_start_methods() (en el módulo multiprocessing)

GET_ANEXT (opcode)

get_app() (método de wsgiref.simple_server.WSGIServer)

get_archive_formats() (en el módulo shutil)

get_args() (en el módulo typing)

get_asyncgen_hooks() (en el módulo sys)

get_attribute() (en el módulo test.support)

GET_AWAITABLE (opcode)

get_begidx() (en el módulo readline)

get_blocking() (en el módulo os)

get_body() (método de email.message.EmailMessage)

get_body_encoding() (método de email.charset.Charset)

get_boundary() (método de email.message.EmailMessage)

(método de email.message.Message)

get_bpbynumber() (método de bdb.Bdb)

get_break() (método de bdb.Bdb)

get_breaks() (método de bdb.Bdb)

get_buffer() (método de asyncio.BufferedProtocol)

(método de xdrlib.Packer)

(método de xdrlib.Unpacker)

get_bytes() (método de mailbox.Mailbox)

get_ca_certs() (método de ssl.SSLContext)

get_cache_token() (en el módulo abc)

get_channel_binding() (método de ssl.SSLSocket)

get_charset() (método de email.message.Message)

get_charsets() (método de email.message.EmailMessage)

(método de email.message.Message)

get_child_watcher() (en el módulo asyncio)

(método de asyncio.AbstractEventLoopPolicy)

get_children() (método de symtable.SymbolTable)

(método de tkinter.ttk.Treeview)

get_ciphers() (método de ssl.SSLContext)

get_clock_info() (en el módulo time)

get_close_matches() (en el módulo difflib)

get_code() (método de importlib.abc.InspectLoader)

(método de importlib.abc.SourceLoader)

(método de importlib.machinery.ExtensionFileLoader)

(método de importlib.machinery.SourcelessFileLoader)

(método de zipimport.zipimporter)

get_completer() (en el módulo readline)

get_completer_delims() (en el módulo readline)

get_completion_type() (en el módulo readline)

get_config_h_filename() (en el módulo distutils.sysconfig)

(en el módulo sysconfig)

get_config_var() (en el módulo distutils.sysconfig)

(en el módulo sysconfig)

get_config_vars() (en el módulo distutils.sysconfig)

(en el módulo sysconfig)

get_content() (en el módulo email.contentmanager)

(método de email.contentmanager.ContentManager)

(método de email.message.EmailMessage)

get_content_charset() (método de email.message.EmailMessage)

(método de email.message.Message)

get_content_disposition() (método de email.message.EmailMessage)

(método de email.message.Message)

get_content_maintype() (método de email.message.EmailMessage)

(método de email.message.Message)

get_content_subtype() (método de email.message.EmailMessage)

(método de email.message.Message)

get_content_type() (método de email.message.EmailMessage)

(método de email.message.Message)

get_context() (en el módulo multiprocessing)

get_coro() (método de asyncio.Task)

get_coroutine_origin_tracking_depth() (en el módulo sys)

get_count() (en el módulo gc)

get_current_history_length() (en el módulo readline)

get_data() (en el módulo pkgutil)

(método de importlib.abc.FileLoader)

(método de importlib.abc.ResourceLoader)

(método de zipimport.zipimporter)

get_date() (método de mailbox.MaildirMessage)

get_debug() (en el módulo gc)

(método de asyncio.loop)

get_default() (método de argparse.ArgumentParser)

get_default_compiler() (en el módulo distutils.ccompiler)

get_default_domain() (en el módulo nis)

get_default_type() (método de email.message.EmailMessage)

(método de email.message.Message)

get_default_verify_paths() (en el módulo ssl)

get_dialect() (en el módulo csv)

get_disassembly_as_string() (método de test.support.bytecode_helper.BytecodeTestCase)

get_docstring() (en el módulo ast)

get_doctest() (método de doctest.DocTestParser)

get_endidx() (en el módulo readline)

get_environ() (método de wsgiref.simple_server.WSGIRequestHandler)

get_errno() (en el módulo ctypes)

get_escdelay() (en el módulo curses)

get_event_loop() (en el módulo asyncio)

(método de asyncio.AbstractEventLoopPolicy)

get_event_loop_policy() (en el módulo asyncio)

get_examples() (método de doctest.DocTestParser)

get_exception_handler() (método de asyncio.loop)

get_exec_path() (en el módulo os)

get_extra_info() (método de asyncio.BaseTransport)

(método de asyncio.StreamWriter)

get_field() (método de string.Formatter)

get_file() (método de mailbox.Babyl)

(método de mailbox.Mailbox)

(método de mailbox.Maildir)

(método de mailbox.mbox)

(método de mailbox.MH)

(método de mailbox.MMDF)

get_file_breaks() (método de bdb.Bdb)

get_filename() (método de email.message.EmailMessage)

(método de email.message.Message)

(método de importlib.abc.ExecutionLoader)

(método de importlib.abc.FileLoader)

(método de importlib.machinery.ExtensionFileLoader)

(método de zipimport.zipimporter)

get_filter() (método de tkinter.filedialog.FileDialog)

get_flags() (método de mailbox.MaildirMessage)

(método de mailbox.mboxMessage)

(método de mailbox.MMDFMessage)

get_folder() (método de mailbox.Maildir)

(método de mailbox.MH)

get_frees() (método de symtable.Function)

get_freeze_count() (en el módulo gc)

get_from() (método de mailbox.mboxMessage)

(método de mailbox.MMDFMessage)

get_full_url() (método de urllib.request.Request)

get_globals() (método de symtable.Function)

get_grouped_opcodes() (método de difflib.SequenceMatcher)

get_handle_inheritable() (en el módulo os)

get_header() (método de urllib.request.Request)

get_history_item() (en el módulo readline)

get_history_length() (en el módulo readline)

get_id() (método de symtable.SymbolTable)

get_ident() (en el módulo _thread)

(en el módulo threading)

get_identifiers() (método de symtable.SymbolTable)

get_importer() (en el módulo pkgutil)

get_info() (método de mailbox.MaildirMessage)

get_inheritable() (en el módulo os)

(método de socket.socket)

get_instructions() (en el módulo dis)

get_int_max_str_digits() (en el módulo sys)

get_interpreter() (en el módulo zipapp)

GET_ITER (opcode)

get_key() (método de selectors.BaseSelector)

get_labels() (método de mailbox.Babyl)

(método de mailbox.BabylMessage)

get_last_error() (en el módulo ctypes)

get_line_buffer() (en el módulo readline)

get_lineno() (método de symtable.SymbolTable)

get_loader() (en el módulo pkgutil)

get_locals() (método de symtable.Function)

get_logger() (en el módulo multiprocessing)

get_loop() (método de asyncio.Future)

(método de asyncio.Server)

get_magic() (en el módulo imp)

get_makefile_filename() (en el módulo distutils.sysconfig)

(en el módulo sysconfig)

get_map() (método de selectors.BaseSelector)

get_matching_blocks() (método de difflib.SequenceMatcher)

get_message() (método de mailbox.Mailbox)

get_method() (método de urllib.request.Request)

get_methods() (método de symtable.Class)

get_mixed_type_key() (en el módulo ipaddress)

get_name() (método de asyncio.Task)

(método de symtable.Symbol)

(método de symtable.SymbolTable)

get_namespace() (método de symtable.Symbol)

get_namespaces() (método de symtable.Symbol)

get_native_id() (en el módulo _thread)

(en el módulo threading)

get_nonlocals() (método de symtable.Function)

get_nonstandard_attr() (método de http.cookiejar.Cookie)

get_nowait() (método de asyncio.Queue)

(método de multiprocessing.Queue)

(método de queue.Queue)

(método de queue.SimpleQueue)

get_object_traceback() (en el módulo tracemalloc)

get_objects() (en el módulo gc)

get_opcodes() (método de difflib.SequenceMatcher)

get_option() (método de optparse.OptionParser)

get_option_group() (método de optparse.OptionParser)

get_option_order() (método de distutils.fancy_getopt.FancyGetopt)

get_origin() (en el módulo typing)

get_original_stdout() (en el módulo test.support)

get_osfhandle() (en el módulo msvcrt)

get_output_charset() (método de email.charset.Charset)

get_param() (método de email.message.Message)

get_parameters() (método de symtable.Function)

get_params() (método de email.message.Message)

get_path() (en el módulo sysconfig)

get_path_names() (en el módulo sysconfig)

get_paths() (en el módulo sysconfig)

get_payload() (método de email.message.Message)

get_pid() (método de asyncio.SubprocessTransport)

get_pipe_transport() (método de asyncio.SubprocessTransport)

get_platform() (en el módulo distutils.util)

(en el módulo sysconfig)

get_poly() (en el módulo turtle)

get_position() (método de xdrlib.Unpacker)

get_protocol() (método de asyncio.BaseTransport)

get_python_inc() (en el módulo distutils.sysconfig)

get_python_lib() (en el módulo distutils.sysconfig)

get_python_version() (en el módulo sysconfig)

get_ready() (método de graphlib.TopologicalSorter)

get_recsrc() (método de ossaudiodev.oss_mixer_device)

get_referents() (en el módulo gc)

get_referrers() (en el módulo gc)

get_request() (método de socketserver.BaseServer)

get_returncode() (método de asyncio.SubprocessTransport)

get_running_loop() (en el módulo asyncio)

get_scheme() (método de wsgiref.handlers.BaseHandler)

get_scheme_names() (en el módulo sysconfig)

get_selection() (método de tkinter.filedialog.FileDialog)

get_sequences() (método de mailbox.MH)

(método de mailbox.MHMessage)

get_server() (método de multiprocessing.managers.BaseManager)

get_server_certificate() (en el módulo ssl)

get_shapepoly() (en el módulo turtle)

get_socket() (método de telnetlib.Telnet)

get_source() (método de importlib.abc.InspectLoader)

(método de importlib.abc.SourceLoader)

(método de importlib.machinery.ExtensionFileLoader)

(método de importlib.machinery.SourcelessFileLoader)

(método de zipimport.zipimporter)

get_source_segment() (en el módulo ast)

get_special_folder_path() (función incorporada)

get_stack() (método de asyncio.Task)

(método de bdb.Bdb)

get_start_method() (en el módulo multiprocessing)

get_starttag_text() (método de html.parser.HTMLParser)

get_stats() (en el módulo gc)

get_stats_profile() (método de pstats.Stats)

get_stderr() (método de wsgiref.handlers.BaseHandler)

(método de wsgiref.simple_server.WSGIRequestHandler)

get_stdin() (método de wsgiref.handlers.BaseHandler)

get_string() (método de mailbox.Mailbox)

get_subdir() (método de mailbox.MaildirMessage)

get_suffixes() (en el módulo imp)

get_symbols() (método de symtable.SymbolTable)

get_tabsize() (en el módulo curses)

get_tag() (en el módulo imp)

get_task_factory() (método de asyncio.loop)

get_terminal_size() (en el módulo os)

(en el módulo shutil)

get_terminator() (método de asynchat.async_chat)

get_threshold() (en el módulo gc)

get_token() (método de shlex.shlex)

get_traceback_limit() (en el módulo tracemalloc)

get_traced_memory() (en el módulo tracemalloc)

get_tracemalloc_memory() (en el módulo tracemalloc)

get_type() (método de symtable.SymbolTable)

get_type_hints() (en el módulo typing)

get_unixfrom() (método de email.message.EmailMessage)

(método de email.message.Message)

get_unpack_formats() (en el módulo shutil)

get_usage() (método de optparse.OptionParser)

get_value() (método de string.Formatter)

get_version() (método de optparse.OptionParser)

get_visible() (método de mailbox.BabylMessage)

get_wch() (método de curses.window)

get_write_buffer_limits() (método de asyncio.WriteTransport)

get_write_buffer_size() (método de asyncio.WriteTransport)

GET_YIELD_FROM_ITER (opcode)

getacl() (método de imaplib.IMAP4)

getaddresses() (en el módulo email.utils)

getaddrinfo() (en el módulo socket)

(método de asyncio.loop)

getallocatedblocks() (en el módulo sys)

getandroidapilevel() (en el módulo sys)

getannotation() (método de imaplib.IMAP4)

getargspec() (en el módulo inspect)

getargvalues() (en el módulo inspect)

getatime() (en el módulo os.path)

getattr() (función incorporada)

getattr_static() (en el módulo inspect)

getattrfunc (tipo C)

getAttribute() (método de xml.dom.Element)

getAttributeNode() (método de xml.dom.Element)

getAttributeNodeNS() (método de xml.dom.Element)

getAttributeNS() (método de xml.dom.Element)

getattrofunc (tipo C)

GetBase() (método de xml.parsers.expat.xmlparser)

getbegyx() (método de curses.window)

getbkgd() (método de curses.window)

getblocking() (método de socket.socket)

getboolean() (método de configparser.ConfigParser)

getbuffer() (método de io.BytesIO)

getbufferproc (tipo C)

getByteStream() (método de xml.sax.xmlreader.InputSource)

getcallargs() (en el módulo inspect)

getcanvas() (en el módulo turtle)

getcapabilities() (método de nntplib.NNTP)

getcaps() (en el módulo mailcap)

getch() (en el módulo msvcrt)

(método de curses.window)

getCharacterStream() (método de xml.sax.xmlreader.InputSource)

getche() (en el módulo msvcrt)

getChild() (método de logging.Logger)

getclasstree() (en el módulo inspect)

getclosurevars() (en el módulo inspect)

GetColumnInfo() (método de msilib.View)

getColumnNumber() (método de xml.sax.xmlreader.Locator)

getcomments() (en el módulo inspect)

getcompname() (método de aifc.aifc)

(método de sunau.AU_read)

(método de wave.Wave_read)

getcomptype() (método de aifc.aifc)

(método de sunau.AU_read)

(método de wave.Wave_read)

getContentHandler() (método de xml.sax.xmlreader.XMLReader)

getcontext() (en el módulo decimal)

getcoroutinelocals() (en el módulo inspect)

getcoroutinestate() (en el módulo inspect)

getctime() (en el módulo os.path)

getcwd() (en el módulo os)

getcwdb() (en el módulo os)

getcwdu (2to3 fixer)

getdecoder() (en el módulo codecs)

getdefaultencoding() (en el módulo sys)

getdefaultlocale() (en el módulo locale)

getdefaulttimeout() (en el módulo socket)

getdlopenflags() (en el módulo sys)

getdoc() (en el módulo inspect)

getDOMImplementation() (en el módulo xml.dom)

getDTDHandler() (método de xml.sax.xmlreader.XMLReader)

getEffectiveLevel() (método de logging.Logger)

getegid() (en el módulo os)

getElementsByTagName() (método de xml.dom.Document)

(método de xml.dom.Element)

getElementsByTagNameNS() (método de xml.dom.Document)

(método de xml.dom.Element)

getencoder() (en el módulo codecs)

getEncoding() (método de xml.sax.xmlreader.InputSource)

getEntityResolver() (método de xml.sax.xmlreader.XMLReader)

getenv() (en el módulo os)

getenvb() (en el módulo os)

getErrorHandler() (método de xml.sax.xmlreader.XMLReader)

geteuid() (en el módulo os)

getEvent() (método de xml.dom.pulldom.DOMEventStream)

getEventCategory() (método de logging.handlers.NTEventLogHandler)

getEventType() (método de logging.handlers.NTEventLogHandler)

getException() (método de xml.sax.SAXException)

getFeature() (método de xml.sax.xmlreader.XMLReader)

GetFieldCount() (método de msilib.Record)

getfile() (en el módulo inspect)

getFilesToDelete() (método de logging.handlers.TimedRotatingFileHandler)

getfilesystemencodeerrors() (en el módulo sys)

getfilesystemencoding() (en el módulo sys)

getfirst() (método de cgi.FieldStorage)

getfloat() (método de configparser.ConfigParser)

getfmts() (método de ossaudiodev.oss_audio_device)

getfqdn() (en el módulo socket)

getframeinfo() (en el módulo inspect)

getframerate() (método de aifc.aifc)

(método de sunau.AU_read)

(método de wave.Wave_read)

getfullargspec() (en el módulo inspect)

getgeneratorlocals() (en el módulo inspect)

getgeneratorstate() (en el módulo inspect)

getgid() (en el módulo os)

getgrall() (en el módulo grp)

getgrgid() (en el módulo grp)

getgrnam() (en el módulo grp)

getgrouplist() (en el módulo os)

getgroups() (en el módulo os)

getheader() (método de http.client.HTTPResponse)

getheaders() (método de http.client.HTTPResponse)

gethostbyaddr() (en el módulo socket)

(in module socket)

gethostbyname() (en el módulo socket)

gethostbyname_ex() (en el módulo socket)

gethostname() (en el módulo socket)

(in module socket)

getincrementaldecoder() (en el módulo codecs)

getincrementalencoder() (en el módulo codecs)

getinfo() (método de zipfile.ZipFile)

getinnerframes() (en el módulo inspect)

GetInputContext() (método de xml.parsers.expat.xmlparser)

getint() (método de configparser.ConfigParser)

GetInteger() (método de msilib.Record)

getitem() (en el módulo operator)

getiterfunc (tipo C)

getitimer() (en el módulo signal)

getkey() (método de curses.window)

GetLastError() (en el módulo ctypes)

getLength() (método de xml.sax.xmlreader.Attributes)

getLevelName() (en el módulo logging)

getline() (en el módulo linecache)

getLineNumber() (método de xml.sax.xmlreader.Locator)

getlist() (método de cgi.FieldStorage)

getloadavg() (en el módulo os)

getlocale() (en el módulo locale)

getLogger() (en el módulo logging)

getLoggerClass() (en el módulo logging)

getlogin() (en el módulo os)

getLogRecordFactory() (en el módulo logging)

getmark() (método de aifc.aifc)

(método de sunau.AU_read)

(método de wave.Wave_read)

getmarkers() (método de aifc.aifc)

(método de sunau.AU_read)

(método de wave.Wave_read)

getmaxyx() (método de curses.window)

getmember() (método de tarfile.TarFile)

getmembers() (en el módulo inspect)

(método de tarfile.TarFile)

getMessage() (método de logging.LogRecord)

(método de xml.sax.SAXException)

getMessageID() (método de logging.handlers.NTEventLogHandler)

getmodule() (en el módulo inspect)

getmodulename() (en el módulo inspect)

getmouse() (en el módulo curses)

getmro() (en el módulo inspect)

getmtime() (en el módulo os.path)

getname() (método de chunk.Chunk)

getName() (método de threading.Thread)

getNameByQName() (método de xml.sax.xmlreader.AttributesNS)

getnameinfo() (en el módulo socket)

(método de asyncio.loop)

getnames() (método de tarfile.TarFile)

getNames() (método de xml.sax.xmlreader.Attributes)

getnchannels() (método de aifc.aifc)

(método de sunau.AU_read)

(método de wave.Wave_read)

getnframes() (método de aifc.aifc)

(método de sunau.AU_read)

(método de wave.Wave_read)

getnode

getnode() (en el módulo uuid)

getopt (módulo)

getopt() (en el módulo getopt)

(método de distutils.fancy_getopt.FancyGetopt)

GetoptError

getouterframes() (en el módulo inspect)

getoutput() (en el módulo subprocess)

getpagesize() (en el módulo resource)

getparams() (método de aifc.aifc)

(método de sunau.AU_read)

(método de wave.Wave_read)

getparyx() (método de curses.window)

getpass (módulo)

getpass() (en el módulo getpass)

GetPassWarning

getpeercert() (método de ssl.SSLSocket)

getpeername() (método de socket.socket)

getpen() (en el módulo turtle)

getpgid() (en el módulo os)

getpgrp() (en el módulo os)

getpid() (en el módulo os)

getpos() (método de html.parser.HTMLParser)

getppid() (en el módulo os)

getpreferredencoding() (en el módulo locale)

getpriority() (en el módulo os)

getprofile() (en el módulo sys)

GetProperty() (método de msilib.SummaryInformation)

getProperty() (método de xml.sax.xmlreader.XMLReader)

GetPropertyCount() (método de msilib.SummaryInformation)

getprotobyname() (en el módulo socket)

getproxies() (en el módulo urllib.request)

getPublicId() (método de xml.sax.xmlreader.InputSource)

(método de xml.sax.xmlreader.Locator)

getpwall() (en el módulo pwd)

getpwnam() (en el módulo pwd)

getpwuid() (en el módulo pwd)

getQNameByName() (método de xml.sax.xmlreader.AttributesNS)

getQNames() (método de xml.sax.xmlreader.AttributesNS)

getquota() (método de imaplib.IMAP4)

getquotaroot() (método de imaplib.IMAP4)

getrandbits() (en el módulo random)

getrandom() (en el módulo os)

getreader() (en el módulo codecs)

getrecursionlimit() (en el módulo sys)

getrefcount() (en el módulo sys)

getresgid() (en el módulo os)

getresponse() (método de http.client.HTTPConnection)

getresuid() (en el módulo os)

getrlimit() (en el módulo resource)

getroot() (método de xml.etree.ElementTree.ElementTree)

getrusage() (en el módulo resource)

getsample() (en el módulo audioop)

getsampwidth() (método de aifc.aifc)

(método de sunau.AU_read)

(método de wave.Wave_read)

getscreen() (en el módulo turtle)

getservbyname() (en el módulo socket)

getservbyport() (en el módulo socket)

GetSetDescriptorType (en el módulo types)

getshapes() (en el módulo turtle)

getsid() (en el módulo os)

getsignal() (en el módulo signal)

getsitepackages() (en el módulo site)

getsize() (en el módulo os.path)

(método de chunk.Chunk)

getsizeof() (en el módulo sys)

getsockname() (método de socket.socket)

getsockopt() (método de socket.socket)

getsource() (en el módulo inspect)

getsourcefile() (en el módulo inspect)

getsourcelines() (en el módulo inspect)

getspall() (en el módulo spwd)

getspnam() (en el módulo spwd)

getstate() (en el módulo random)

(método de codecs.IncrementalDecoder)

(método de codecs.IncrementalEncoder)

getstatus() (método de http.client.HTTPResponse)

(método de urllib.response.addinfourl)

getstatusoutput() (en el módulo subprocess)

getstr() (método de curses.window)

GetString() (método de msilib.Record)

getSubject() (método de logging.handlers.SMTPHandler)

GetSummaryInformation() (método de msilib.Database)

getswitchinterval() (en el módulo sys)

getSystemId() (método de xml.sax.xmlreader.InputSource)

(método de xml.sax.xmlreader.Locator)

getsyx() (en el módulo curses)

gettarinfo() (método de tarfile.TarFile)

gettempdir() (en el módulo tempfile)

gettempdirb() (en el módulo tempfile)

gettempprefix() (en el módulo tempfile)

gettempprefixb() (en el módulo tempfile)

getTestCaseNames() (método de unittest.TestLoader)

gettext (módulo)

gettext() (en el módulo gettext)

(en el módulo locale)

(método de gettext.GNUTranslations)

(método de gettext.NullTranslations)

gettimeout() (método de socket.socket)

gettrace() (en el módulo sys)

getturtle() (en el módulo turtle)

getType() (método de xml.sax.xmlreader.Attributes)

getuid() (en el módulo os)

geturl() (método de http.client.HTTPResponse)

(método de urllib.parse.urllib.parse.SplitResult)

(método de urllib.response.addinfourl)

getuser() (en el módulo getpass)

getuserbase() (en el módulo site)

getusersitepackages() (en el módulo site)

getvalue() (método de io.BytesIO)

(método de io.StringIO)

getValue() (método de xml.sax.xmlreader.Attributes)

getValueByQName() (método de xml.sax.xmlreader.AttributesNS)

getwch() (en el módulo msvcrt)

getwche() (en el módulo msvcrt)

getweakrefcount() (en el módulo weakref)

getweakrefs() (en el módulo weakref)

getwelcome() (método de ftplib.FTP)

(método de nntplib.NNTP)

(método de poplib.POP3)

getwin() (en el módulo curses)

getwindowsversion() (en el módulo sys)

getwriter() (en el módulo codecs)

getxattr() (en el módulo os)

getyx() (método de curses.window)

gid (atributo de tarfile.TarInfo)

GIL

glob

módulo

glob (módulo)

glob() (en el módulo glob)

(método de msilib.Directory)

(método de pathlib.Path)

global

name binding

namespace

sentencia, [1]

Global (clase en ast)

global interpreter lock

globals() (función incorporada)

globs (atributo de doctest.DocTest)

gmtime() (en el módulo time)

gname (atributo de tarfile.TarInfo)

GNOME

GNU_FORMAT (en el módulo tarfile)

gnu_getopt() (en el módulo getopt)

GNUTranslations (clase en gettext)

go() (método de tkinter.filedialog.FileDialog)

got (atributo de doctest.DocTestFailure)

goto() (en el módulo turtle)

grammar

Graphical User Interface

graphlib (módulo)

GREATER (en el módulo token)

GREATEREQUAL (en el módulo token)

Greenwich Mean Time

GRND_NONBLOCK (en el módulo os)

GRND_RANDOM (en el módulo os)

Group (clase en email.headerregistry)

group() (método de nntplib.NNTP)

(método de pathlib.Path)

(método de re.Match)

groupby() (en el módulo itertools)

groupdict() (método de re.Match)

groupindex (atributo de re.Pattern)

grouping

groups (atributo de email.headerregistry.AddressHeader)

(atributo de re.Pattern)

groups() (método de re.Match)

grp (módulo)

Gt (clase en ast)

gt() (en el módulo operator)

GtE (clase en ast)

guess_all_extensions() (en el módulo mimetypes)

(método de mimetypes.MimeTypes)

guess_extension() (en el módulo mimetypes)

(método de mimetypes.MimeTypes)

guess_scheme() (en el módulo wsgiref.util)

guess_type() (en el módulo mimetypes)

(método de mimetypes.MimeTypes)

GUI

gzip (módulo)

gzip command line option

--best

--decompress

--fast

--help

-d

-h

file

GzipFile (clase en gzip)

H

halfdelay() (en el módulo curses)

Handle (clase en asyncio)

handle an exception

handle() (método de http.server.BaseHTTPRequestHandler)

(método de logging.Handler)

(método de logging.handlers.QueueListener)

(método de logging.Logger)

(método de logging.NullHandler)

(método de socketserver.BaseRequestHandler)

(método de wsgiref.simple_server.WSGIRequestHandler)

handle_accept() (método de asyncore.dispatcher)

handle_accepted() (método de asyncore.dispatcher)

handle_charref() (método de html.parser.HTMLParser)

handle_close() (método de asyncore.dispatcher)

handle_comment() (método de html.parser.HTMLParser)

handle_connect() (método de asyncore.dispatcher)

handle_data() (método de html.parser.HTMLParser)

handle_decl() (método de html.parser.HTMLParser)

handle_defect() (método de email.policy.Policy)

handle_endtag() (método de html.parser.HTMLParser)

handle_entityref() (método de html.parser.HTMLParser)

handle_error() (método de asyncore.dispatcher)

(método de socketserver.BaseServer)

handle_expect_100() (método de http.server.BaseHTTPRequestHandler)

handle_expt() (método de asyncore.dispatcher)

handle_one_request() (método de http.server.BaseHTTPRequestHandler)

handle_pi() (método de html.parser.HTMLParser)

handle_read() (método de asyncore.dispatcher)

handle_request() (método de socketserver.BaseServer)

(método de xmlrpc.server.CGIXMLRPCRequestHandler)

handle_startendtag() (método de html.parser.HTMLParser)

handle_starttag() (método de html.parser.HTMLParser)

handle_timeout() (método de socketserver.BaseServer)

handle_write() (método de asyncore.dispatcher)

handleError() (método de logging.Handler)

(método de logging.handlers.SocketHandler)

handler

exception

Handler (clase en logging)

handler() (en el módulo cgitb)

harmonic_mean() (en el módulo statistics)

HAS_ALPN (en el módulo ssl)

has_children() (método de symtable.SymbolTable)

has_colors() (en el módulo curses)

has_dualstack_ipv6() (en el módulo socket)

HAS_ECDH (en el módulo ssl)

has_extn() (método de smtplib.SMTP)

has_function() (método de distutils.ccompiler.CCompiler)

has_header() (método de csv.Sniffer)

(método de urllib.request.Request)

has_ic() (en el módulo curses)

has_il() (en el módulo curses)

has_ipv6 (en el módulo socket)

has_key (2to3 fixer)

has_key() (en el módulo curses)

has_location (atributo de importlib.machinery.ModuleSpec)

HAS_NEVER_CHECK_COMMON_NAME (en el módulo ssl)

has_nonstandard_attr() (método de http.cookiejar.Cookie)

HAS_NPN (en el módulo ssl)

has_option() (método de configparser.ConfigParser)

(método de optparse.OptionParser)

has_section() (método de configparser.ConfigParser)

HAS_SNI (en el módulo ssl)

HAS_SSLv2 (en el módulo ssl)

HAS_SSLv3 (en el módulo ssl)

has_ticket (atributo de ssl.SSLSession)

HAS_TLSv1 (en el módulo ssl)

HAS_TLSv1_1 (en el módulo ssl)

HAS_TLSv1_2 (en el módulo ssl)

HAS_TLSv1_3 (en el módulo ssl)

hasattr() (función incorporada)

hasAttribute() (método de xml.dom.Element)

hasAttributeNS() (método de xml.dom.Element)

hasAttributes() (método de xml.dom.Node)

hasChildNodes() (método de xml.dom.Node)

hascompare (en el módulo dis)

hasconst (en el módulo dis)

hasFeature() (método de xml.dom.DOMImplementation)

hasfree (en el módulo dis)

hash

función incorporada, [1], [2], [3]

hash character

hash() (función incorporada)

hash-based pyc

hash.block_size (en el módulo hashlib)

hash.digest_size (en el módulo hashlib)

hash_info (en el módulo sys)

hashable, [1]

Hashable (clase en collections.abc)

(clase en typing)

hasHandlers() (método de logging.Logger)

hashfunc (tipo C)

hashlib (módulo)

hasjabs (en el módulo dis)

hasjrel (en el módulo dis)

haslocal (en el módulo dis)

hasname (en el módulo dis)

HAVE_ARGUMENT (opcode)

HAVE_CONTEXTVAR (en el módulo decimal)

HAVE_DOCSTRINGS (en el módulo test.support)

HAVE_THREADS (en el módulo decimal)

HCI_DATA_DIR (en el módulo socket)

HCI_FILTER (en el módulo socket)

HCI_TIME_STAMP (en el módulo socket)

head() (método de nntplib.NNTP)

Header (clase en email.header)

header_encode() (método de email.charset.Charset)

header_encode_lines() (método de email.charset.Charset)

header_encoding (atributo de email.charset.Charset)

header_factory (atributo de email.policy.EmailPolicy)

header_fetch_parse() (método de email.policy.Compat32)

(método de email.policy.EmailPolicy)

(método de email.policy.Policy)

header_items() (método de urllib.request.Request)

header_max_count() (método de email.policy.EmailPolicy)

(método de email.policy.Policy)

header_offset (atributo de zipfile.ZipInfo)

header_source_parse() (método de email.policy.Compat32)

(método de email.policy.EmailPolicy)

(método de email.policy.Policy)

header_store_parse() (método de email.policy.Compat32)

(método de email.policy.EmailPolicy)

(método de email.policy.Policy)

HeaderError

HeaderParseError

HeaderParser (clase en email.parser)

HeaderRegistry (clase en email.headerregistry)

headers

MIME, [1]

headers (atributo de http.client.HTTPResponse)

(atributo de http.server.BaseHTTPRequestHandler)

(atributo de urllib.error.HTTPError)

(atributo de urllib.response.addinfourl)

(atributo de xmlrpc.client.ProtocolError)

Headers (clase en wsgiref.headers)

heading() (en el módulo turtle)

(método de tkinter.ttk.Treeview)

heapify() (en el módulo heapq)

heapmin() (en el módulo msvcrt)

heappop() (en el módulo heapq)

heappush() (en el módulo heapq)

heappushpop() (en el módulo heapq)

heapq (módulo)

heapreplace() (en el módulo heapq)

helo() (método de smtplib.SMTP)

help

función incorporada

online

help (atributo de optparse.Option)

(pdb command)

help() (función incorporada)

(método de nntplib.NNTP)

herror

hex (atributo de uuid.UUID)

hex() (función incorporada)

(método de bytearray)

(método de bytes)

(método de float)

(método de memoryview)

hexadecimal

literals

hexadecimal literal

hexbin() (en el módulo binhex)

hexdigest() (método de hashlib.hash)

(método de hashlib.shake)

(método de hmac.HMAC)

hexdigits (en el módulo string)

hexlify() (en el módulo binascii)

hexversion (en el módulo sys)

hidden() (método de curses.panel.Panel)

hide() (método de curses.panel.Panel)

(método de tkinter.ttk.Notebook)

hide_cookie2 (atributo de http.cookiejar.CookiePolicy)

hideturtle() (en el módulo turtle)

hierarchy

type

HierarchyRequestErr

HIGH_PRIORITY_CLASS (en el módulo subprocess)

HIGHEST_PROTOCOL (en el módulo pickle)

HKEY_CLASSES_ROOT (en el módulo winreg)

HKEY_CURRENT_CONFIG (en el módulo winreg)

HKEY_CURRENT_USER (en el módulo winreg)

HKEY_DYN_DATA (en el módulo winreg)

HKEY_LOCAL_MACHINE (en el módulo winreg)

HKEY_PERFORMANCE_DATA (en el módulo winreg)

HKEY_USERS (en el módulo winreg)

hline() (método de curses.window)

HList (clase en tkinter.tix)

hls_to_rgb() (en el módulo colorsys)

hmac (módulo)

HOME, [1], [2], [3], [4], [5], [6], [7], [8], [9]

home() (en el módulo turtle)

(método de clase de pathlib.Path)

HOMEDRIVE, [1]

HOMEPATH, [1]

hook_compressed() (en el módulo fileinput)

hook_encoded() (en el módulo fileinput)

hooks

import

meta

path

host (atributo de urllib.request.Request)

hostmask (atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Network)

hostname_checks_common_name (atributo de ssl.SSLContext)

hosts (atributo de netrc.netrc)

hosts() (método de ipaddress.IPv4Network)

(método de ipaddress.IPv6Network)

hour (atributo de datetime.datetime)

(atributo de datetime.time)

HRESULT (clase en ctypes)

hStdError (atributo de subprocess.STARTUPINFO)

hStdInput (atributo de subprocess.STARTUPINFO)

hStdOutput (atributo de subprocess.STARTUPINFO)

hsv_to_rgb() (en el módulo colorsys)

ht() (en el módulo turtle)

HTML, [1]

html (módulo)

html() (en el módulo cgitb)

html.entities (módulo)

html.parser (módulo)

html5 (en el módulo html.entities)

HTMLCalendar (clase en calendar)

HtmlDiff (clase en difflib)

HTMLParser (clase en html.parser)

htonl() (en el módulo socket)

htons() (en el módulo socket)

HTTP

http (standard module)

http.client (standard module)

protocol, [1], [2], [3], [4], [5]

HTTP (en el módulo email.policy)

http (módulo)

http.client (módulo)

http.cookiejar (módulo)

http.cookies (módulo)

http.server

security

http.server (módulo)

http_error_301() (método de urllib.request.HTTPRedirectHandler)

http_error_302() (método de urllib.request.HTTPRedirectHandler)

http_error_303() (método de urllib.request.HTTPRedirectHandler)

http_error_307() (método de urllib.request.HTTPRedirectHandler)

http_error_401() (método de urllib.request.HTTPBasicAuthHandler)

(método de urllib.request.HTTPDigestAuthHandler)

http_error_407() (método de urllib.request.ProxyBasicAuthHandler)

(método de urllib.request.ProxyDigestAuthHandler)

http_error_auth_reqed() (método de urllib.request.AbstractBasicAuthHandler)

(método de urllib.request.AbstractDigestAuthHandler)

http_error_default() (método de urllib.request.BaseHandler)

http_open() (método de urllib.request.HTTPHandler)

HTTP_PORT (en el módulo http.client)

http_proxy, [1], [2]

http_response() (método de urllib.request.HTTPErrorProcessor)

http_version (atributo de wsgiref.handlers.BaseHandler)

HTTPBasicAuthHandler (clase en urllib.request)

HTTPConnection (clase en http.client)

HTTPCookieProcessor (clase en urllib.request)

httpd

HTTPDefaultErrorHandler (clase en urllib.request)

HTTPDigestAuthHandler (clase en urllib.request)

HTTPError

HTTPErrorProcessor (clase en urllib.request)

HTTPException

HTTPHandler (clase en logging.handlers)

(clase en urllib.request)

HTTPPasswordMgr (clase en urllib.request)

HTTPPasswordMgrWithDefaultRealm (clase en urllib.request)

HTTPPasswordMgrWithPriorAuth (clase en urllib.request)

HTTPRedirectHandler (clase en urllib.request)

HTTPResponse (clase en http.client)

https_open() (método de urllib.request.HTTPSHandler)

HTTPS_PORT (en el módulo http.client)

https_response() (método de urllib.request.HTTPErrorProcessor)

HTTPSConnection (clase en http.client)

HTTPServer (clase en http.server)

HTTPSHandler (clase en urllib.request)

HTTPStatus (clase en http)

hypot() (en el módulo math)

I

I (en el módulo re)

I/O control

buffering, [1]

POSIX

tty

UNIX

iadd() (en el módulo operator)

iand() (en el módulo operator)

iconcat() (en el módulo operator)

id

función incorporada

id (atributo de ssl.SSLSession)

id() (función incorporada)

(método de unittest.TestCase)

idcok() (método de curses.window)

ident (atributo de select.kevent)

(atributo de threading.Thread)

identchars (atributo de cmd.Cmd)

identifier, [1]

identify() (método de tkinter.ttk.Notebook)

(método de tkinter.ttk.Treeview)

(método de tkinter.ttk.Widget)

identify_column() (método de tkinter.ttk.Treeview)

identify_element() (método de tkinter.ttk.Treeview)

identify_region() (método de tkinter.ttk.Treeview)

identify_row() (método de tkinter.ttk.Treeview)

identity

test

identity of an object

idioms (2to3 fixer)

IDLE, [1]

IDLE_PRIORITY_CLASS (en el módulo subprocess)

IDLESTARTUP, [1], [2], [3]

idlok() (método de curses.window)

if

conditional expression

in comprehensions

sentencia, [1]

If (clase en ast)

if_indextoname() (en el módulo socket)

if_nameindex() (en el módulo socket)

if_nametoindex() (en el módulo socket)

IfExp (clase en ast)

ifloordiv() (en el módulo operator)

iglob() (en el módulo glob)

ignorableWhitespace() (método de xml.sax.handler.ContentHandler)

ignore

error handler's name

ignore (pdb command)

ignore_errors() (en el módulo codecs)

IGNORE_EXCEPTION_DETAIL (en el módulo doctest)

ignore_patterns() (en el módulo shutil)

IGNORECASE (en el módulo re)

ihave() (método de nntplib.NNTP)

IISCGIHandler (clase en wsgiref.handlers)

ilshift() (en el módulo operator)

imag (atributo de numbers.Complex)

imaginary literal

imap() (método de multiprocessing.pool.Pool)

IMAP4

protocol

IMAP4 (clase en imaplib)

IMAP4.abort

IMAP4.error

IMAP4.readonly

IMAP4_SSL

protocol

IMAP4_SSL (clase en imaplib)

IMAP4_stream

protocol

IMAP4_stream (clase en imaplib)

imap_unordered() (método de multiprocessing.pool.Pool)

imaplib (módulo)

imatmul() (en el módulo operator)

imghdr (módulo)

immedok() (método de curses.window)

immutable

data type

object, [1]

objeto

sequence types

immutable object

immutable sequence

objeto

immutable types

subclassing

imod() (en el módulo operator)

imp

módulo

imp (módulo)

ImpImporter (clase en pkgutil)

impl_detail() (en el módulo test.support)

implementation (en el módulo sys)

ImpLoader (clase en pkgutil)

import

hooks

sentencia, [1], [2], [3], [4]

import (2to3 fixer)

Import (clase en ast)

import hooks

import machinery

import_fresh_module() (en el módulo test.support)

IMPORT_FROM (opcode)

import_module() (en el módulo importlib)

(en el módulo test.support)

IMPORT_NAME (opcode)

IMPORT_STAR (opcode)

importador

importar

ImportError

excepción

ImportFrom (clase en ast)

importlib (módulo)

importlib.abc (módulo)

importlib.machinery (módulo)

importlib.metadata (módulo)

importlib.resources (módulo)

importlib.util (módulo)

imports (2to3 fixer)

imports2 (2to3 fixer)

ImportWarning

ImproperConnectionState

imul() (en el módulo operator)

in

operador, [1], [2]

palabra clave

In (clase en ast)

in_dll() (método de ctypes._CData)

in_table_a1() (en el módulo stringprep)

in_table_b1() (en el módulo stringprep)

in_table_c11() (en el módulo stringprep)

in_table_c11_c12() (en el módulo stringprep)

in_table_c12() (en el módulo stringprep)

in_table_c21() (en el módulo stringprep)

in_table_c21_c22() (en el módulo stringprep)

in_table_c22() (en el módulo stringprep)

in_table_c3() (en el módulo stringprep)

in_table_c4() (en el módulo stringprep)

in_table_c5() (en el módulo stringprep)

in_table_c6() (en el módulo stringprep)

in_table_c7() (en el módulo stringprep)

in_table_c8() (en el módulo stringprep)

in_table_c9() (en el módulo stringprep)

in_table_d1() (en el módulo stringprep)

in_table_d2() (en el módulo stringprep)

in_transaction (atributo de sqlite3.Connection)

inch() (método de curses.window)

inclusive

or

inclusive (atributo de tracemalloc.DomainFilter)

(atributo de tracemalloc.Filter)

Incomplete

IncompleteRead

IncompleteReadError

incr_item(), [1]

increment_lineno() (en el módulo ast)

incrementaldecoder (atributo de codecs.CodecInfo)

IncrementalDecoder (clase en codecs)

incrementalencoder (atributo de codecs.CodecInfo)

IncrementalEncoder (clase en codecs)

IncrementalNewlineDecoder (clase en io)

IncrementalParser (clase en xml.sax.xmlreader)

indent (atributo de doctest.Example)

INDENT (en el módulo token)

INDENT token

indent() (en el módulo textwrap)

(en el módulo xml.etree.ElementTree)

indentation

IndentationError

index operation

index() (en el módulo operator)

(método de array.array)

(método de bytearray)

(método de bytes)

(método de collections.deque)

(método de multiprocessing.shared_memory.ShareableList)

(método de str)

(método de tkinter.ttk.Notebook)

(método de tkinter.ttk.Treeview)

(sequence method)

IndexError

indexOf() (en el módulo operator)

IndexSizeErr

indicador de tipo

indices() (método de slice)

inet_aton() (en el módulo socket)

inet_ntoa() (en el módulo socket)

inet_ntop() (en el módulo socket)

inet_pton() (en el módulo socket)

Inexact (clase en decimal)

inf (en el módulo cmath)

(en el módulo math)

infile

json.tool command line option

infile (atributo de shlex.shlex)

Infinity

infj (en el módulo cmath)

info() (en el módulo logging)

(método de dis.Bytecode)

(método de gettext.NullTranslations)

(método de http.client.HTTPResponse)

(método de logging.Logger)

(método de urllib.response.addinfourl)

infolist() (método de zipfile.ZipFile)

inheritance

ini file

init() (en el módulo mimetypes)

init_color() (en el módulo curses)

init_database() (en el módulo msilib)

init_pair() (en el módulo curses)

inited (en el módulo mimetypes)

initgroups() (en el módulo os)

initial_indent (atributo de textwrap.TextWrapper)

initialize_options() (método de distutils.cmd.Command)

initproc (tipo C)

initscr() (en el módulo curses)

inmutable

inode() (método de os.DirEntry)

INPLACE_ADD (opcode)

INPLACE_AND (opcode)

INPLACE_FLOOR_DIVIDE (opcode)

INPLACE_LSHIFT (opcode)

INPLACE_MATRIX_MULTIPLY (opcode)

INPLACE_MODULO (opcode)

INPLACE_MULTIPLY (opcode)

INPLACE_OR (opcode)

INPLACE_POWER (opcode)

INPLACE_RSHIFT (opcode)

INPLACE_SUBTRACT (opcode)

INPLACE_TRUE_DIVIDE (opcode)

INPLACE_XOR (opcode)

input

(2to3 fixer)

input() (en el módulo fileinput)

(función incorporada)

input_charset (atributo de email.charset.Charset)

input_codec (atributo de email.charset.Charset)

InputOnly (clase en tkinter.tix)

InputSource (clase en xml.sax.xmlreader)

inquiry (tipo C)

insch() (método de curses.window)

insdelln() (método de curses.window)

insert() (método de array.array)

(método de collections.deque)

(método de tkinter.ttk.Notebook)

(método de tkinter.ttk.Treeview)

(método de xml.etree.ElementTree.Element)

(sequence method)

insert_text() (en el módulo readline)

insertBefore() (método de xml.dom.Node)

insertln() (método de curses.window)

insnstr() (método de curses.window)

insort() (en el módulo bisect)

insort_left() (en el módulo bisect)

insort_right() (en el módulo bisect)

inspect (módulo)

inspect command line option

--details

InspectLoader (clase en importlib.abc)

insstr() (método de curses.window)

install() (en el módulo gettext)

(método de gettext.NullTranslations)

install_opener() (en el módulo urllib.request)

install_scripts() (método de venv.EnvBuilder)

installHandler() (en el módulo unittest)

instance

call, [1]

class

objeto, [1], [2]

instancemethod

objeto

instate() (método de tkinter.ttk.Widget)

instr() (método de curses.window)

instream (atributo de shlex.shlex)

Instruction (clase en dis)

Instruction.arg (en el módulo dis)

Instruction.argrepr (en el módulo dis)

Instruction.argval (en el módulo dis)

Instruction.is_jump_target (en el módulo dis)

Instruction.offset (en el módulo dis)

Instruction.opcode (en el módulo dis)

Instruction.opname (en el módulo dis)

Instruction.starts_line (en el módulo dis)

int

función incorporada, [1], [2]

int (atributo de uuid.UUID)

(clase incorporada)

Int2AP() (en el módulo imaplib)

int_info (en el módulo sys)

integer

literals

objeto, [1], [2]

representation

types, operations on

integer literal

Integral (clase en numbers)

Integrated Development Environment

IntegrityError

Intel/DVI ADPCM

IntEnum (clase en enum)

interact (pdb command)

interact() (en el módulo code)

(método de code.InteractiveConsole)

(método de telnetlib.Telnet)

interactive mode

InteractiveConsole (clase en code)

InteractiveInterpreter (clase en code)

interactivo

intern (2to3 fixer)

intern() (en el módulo sys)

internal type

internal_attr (atributo de zipfile.ZipInfo)

Internaldate2tuple() (en el módulo imaplib)

internalSubset (atributo de xml.dom.DocumentType)

Internet

INTERNET_TIMEOUT (en el módulo test.support)

interpolated string literal

interpolation

bytearray (%)

bytes (%)

interpolation, string (%)

InterpolationDepthError

InterpolationError

InterpolationMissingOptionError

InterpolationSyntaxError

interpretado

interpreter

interpreter lock

interpreter prompts

interpreter_requires_environment() (en el módulo test.support.script_helper)

interrupt() (método de sqlite3.Connection)

interrupt_main() (en el módulo _thread)

InterruptedError

intersection() (método de frozenset)

intersection_update() (método de frozenset)

IntFlag (clase en enum)

intro (atributo de cmd.Cmd)

InuseAttributeErr

inv() (en el módulo operator)

inv_cdf() (método de statistics.NormalDist)

InvalidAccessErr

invalidate_caches() (en el módulo importlib)

(método de clase de importlib.machinery.PathFinder)

(método de importlib.abc.MetaPathFinder)

(método de importlib.abc.PathEntryFinder)

(método de importlib.machinery.FileFinder)

InvalidCharacterErr

InvalidModificationErr

InvalidOperation (clase en decimal)

InvalidStateErr

InvalidStateError, [1]

InvalidTZPathWarning

InvalidURL

inversion

Invert (clase en ast)

invert() (en el módulo operator)

invocation

io

módulo

IO (clase en typing)

io (módulo)

io.StringIO

objeto

IO_REPARSE_TAG_APPEXECLINK (en el módulo stat)

IO_REPARSE_TAG_MOUNT_POINT (en el módulo stat)

IO_REPARSE_TAG_SYMLINK (en el módulo stat)

IOBase (clase en io)

ioctl() (en el módulo fcntl)

(método de socket.socket)

IOCTL_VM_SOCKETS_GET_LOCAL_CID (en el módulo socket)

IOError

ior() (en el módulo operator)

ip (atributo de ipaddress.IPv4Interface)

(atributo de ipaddress.IPv6Interface)

ip_address() (en el módulo ipaddress)

ip_interface() (en el módulo ipaddress)

ip_network() (en el módulo ipaddress)

ipaddress (módulo)

ipow() (en el módulo operator)

ipv4_mapped (atributo de ipaddress.IPv6Address)

IPv4Address (clase en ipaddress)

IPv4Interface (clase en ipaddress)

IPv4Network (clase en ipaddress)

IPV6_ENABLED (en el módulo test.support.socket_helper)

IPv6Address (clase en ipaddress)

IPv6Interface (clase en ipaddress)

IPv6Network (clase en ipaddress)

irshift() (en el módulo operator)

is

operador, [1]

Is (clase en ast)

is not

operador, [1]

is_() (en el módulo operator)

is_absolute() (método de pathlib.PurePath)

is_active() (método de asyncio.AbstractChildWatcher)

(método de graphlib.TopologicalSorter)

is_alive() (método de multiprocessing.Process)

(método de threading.Thread)

is_android (en el módulo test.support)

is_annotated() (método de symtable.Symbol)

is_assigned() (método de symtable.Symbol)

is_attachment() (método de email.message.EmailMessage)

is_authenticated() (método de urllib.request.HTTPPasswordMgrWithPriorAuth)

is_block_device() (método de pathlib.Path)

is_blocked() (método de http.cookiejar.DefaultCookiePolicy)

is_canonical() (método de decimal.Context)

(método de decimal.Decimal)

is_char_device() (método de pathlib.Path)

IS_CHARACTER_JUNK() (en el módulo difflib)

is_check_supported() (en el módulo lzma)

is_closed() (método de asyncio.loop)

is_closing() (método de asyncio.BaseTransport)

(método de asyncio.StreamWriter)

is_dataclass() (en el módulo dataclasses)

is_declared_global() (método de symtable.Symbol)

is_dir() (método de importlib.abc.Traversable)

(método de os.DirEntry)

(método de pathlib.Path)

(método de zipfile.Path)

(método de zipfile.ZipInfo)

is_enabled() (en el módulo faulthandler)

is_expired() (método de http.cookiejar.Cookie)

is_fifo() (método de pathlib.Path)

is_file() (método de importlib.abc.Traversable)

(método de os.DirEntry)

(método de pathlib.Path)

(método de zipfile.Path)

is_finalized() (en el módulo gc)

is_finalizing() (en el módulo sys)

is_finite() (método de decimal.Context)

(método de decimal.Decimal)

is_free() (método de symtable.Symbol)

is_global (atributo de ipaddress.IPv4Address)

(atributo de ipaddress.IPv6Address)

is_global() (método de symtable.Symbol)

is_hop_by_hop() (en el módulo wsgiref.util)

is_imported() (método de symtable.Symbol)

is_infinite() (método de decimal.Context)

(método de decimal.Decimal)

is_integer() (método de float)

is_jython (en el módulo test.support)

IS_LINE_JUNK() (en el módulo difflib)

is_linetouched() (método de curses.window)

is_link_local (atributo de ipaddress.IPv4Address)

(atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Address)

(atributo de ipaddress.IPv6Network)

is_local() (método de symtable.Symbol)

is_loopback (atributo de ipaddress.IPv4Address)

(atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Address)

(atributo de ipaddress.IPv6Network)

is_mount() (método de pathlib.Path)

is_multicast (atributo de ipaddress.IPv4Address)

(atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Address)

(atributo de ipaddress.IPv6Network)

is_multipart() (método de email.message.EmailMessage)

(método de email.message.Message)

is_namespace() (método de symtable.Symbol)

is_nan() (método de decimal.Context)

(método de decimal.Decimal)

is_nested() (método de symtable.SymbolTable)

is_nonlocal() (método de symtable.Symbol)

is_normal() (método de decimal.Context)

(método de decimal.Decimal)

is_normalized() (en el módulo unicodedata)

is_not() (en el módulo operator)

is_not_allowed() (método de http.cookiejar.DefaultCookiePolicy)

IS_OP (opcode)

is_optimized() (método de symtable.SymbolTable)

is_package() (método de importlib.abc.InspectLoader)

(método de importlib.abc.SourceLoader)

(método de importlib.machinery.ExtensionFileLoader)

(método de importlib.machinery.SourceFileLoader)

(método de importlib.machinery.SourcelessFileLoader)

(método de zipimport.zipimporter)

is_parameter() (método de symtable.Symbol)

is_private (atributo de ipaddress.IPv4Address)

(atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Address)

(atributo de ipaddress.IPv6Network)

is_python_build() (en el módulo sysconfig)

is_qnan() (método de decimal.Context)

(método de decimal.Decimal)

is_reading() (método de asyncio.ReadTransport)

is_referenced() (método de symtable.Symbol)

is_relative_to() (método de pathlib.PurePath)

is_reserved (atributo de ipaddress.IPv4Address)

(atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Address)

(atributo de ipaddress.IPv6Network)

is_reserved() (método de pathlib.PurePath)

is_resource() (en el módulo importlib.resources)

(método de importlib.abc.ResourceReader)

is_resource_enabled() (en el módulo test.support)

is_running() (método de asyncio.loop)

is_safe (atributo de uuid.UUID)

is_serving() (método de asyncio.Server)

is_set() (método de asyncio.Event)

(método de threading.Event)

is_signed() (método de decimal.Context)

(método de decimal.Decimal)

is_site_local (atributo de ipaddress.IPv6Address)

(atributo de ipaddress.IPv6Network)

is_snan() (método de decimal.Context)

(método de decimal.Decimal)

is_socket() (método de pathlib.Path)

is_subnormal() (método de decimal.Context)

(método de decimal.Decimal)

is_symlink() (método de os.DirEntry)

(método de pathlib.Path)

is_tarfile() (en el módulo tarfile)

is_term_resized() (en el módulo curses)

is_tracing() (en el módulo tracemalloc)

is_tracked() (en el módulo gc)

is_unspecified (atributo de ipaddress.IPv4Address)

(atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Address)

(atributo de ipaddress.IPv6Network)

is_wintouched() (método de curses.window)

is_zero() (método de decimal.Context)

(método de decimal.Decimal)

is_zipfile() (en el módulo zipfile)

isabs() (en el módulo os.path)

isabstract() (en el módulo inspect)

IsADirectoryError

isalnum() (en el módulo curses.ascii)

(método de bytearray)

(método de bytes)

(método de str)

isalpha() (en el módulo curses.ascii)

(método de bytearray)

(método de bytes)

(método de str)

isascii() (en el módulo curses.ascii)

(método de bytearray)

(método de bytes)

(método de str)

isasyncgen() (en el módulo inspect)

isasyncgenfunction() (en el módulo inspect)

isatty() (en el módulo os)

(método de chunk.Chunk)

(método de io.IOBase)

isawaitable() (en el módulo inspect)

isblank() (en el módulo curses.ascii)

isblk() (método de tarfile.TarInfo)

isbuiltin() (en el módulo inspect)

ischr() (método de tarfile.TarInfo)

isclass() (en el módulo inspect)

isclose() (en el módulo cmath)

(en el módulo math)

iscntrl() (en el módulo curses.ascii)

iscode() (en el módulo inspect)

iscoroutine() (en el módulo asyncio)

(en el módulo inspect)

iscoroutinefunction() (en el módulo asyncio)

(en el módulo inspect)

isctrl() (en el módulo curses.ascii)

isDaemon() (método de threading.Thread)

isdatadescriptor() (en el módulo inspect)

isdecimal() (método de str)

isdev() (método de tarfile.TarInfo)

isdigit() (en el módulo curses.ascii)

(método de bytearray)

(método de bytes)

(método de str)

isdir() (en el módulo os.path)

(método de tarfile.TarInfo)

isdisjoint() (método de frozenset)

isdown() (en el módulo turtle)

iselement() (en el módulo xml.etree.ElementTree)

isenabled() (en el módulo gc)

isEnabledFor() (método de logging.Logger)

isendwin() (en el módulo curses)

ISEOF() (en el módulo token)

isexpr() (en el módulo parser)

(método de parser.ST)

isfifo() (método de tarfile.TarInfo)

isfile() (en el módulo os.path)

(método de tarfile.TarInfo)

isfinite() (en el módulo cmath)

(en el módulo math)

isfirstline() (en el módulo fileinput)

isframe() (en el módulo inspect)

isfunction() (en el módulo inspect)

isfuture() (en el módulo asyncio)

isgenerator() (en el módulo inspect)

isgeneratorfunction() (en el módulo inspect)

isgetsetdescriptor() (en el módulo inspect)

isgraph() (en el módulo curses.ascii)

isidentifier() (método de str)

isinf() (en el módulo cmath)

(en el módulo math)

isinstance (2to3 fixer)

isinstance() (función incorporada)

iskeyword() (en el módulo keyword)

isleap() (en el módulo calendar)

islice() (en el módulo itertools)

islink() (en el módulo os.path)

islnk() (método de tarfile.TarInfo)

islower() (en el módulo curses.ascii)

(método de bytearray)

(método de bytes)

(método de str)

ismemberdescriptor() (en el módulo inspect)

ismeta() (en el módulo curses.ascii)

ismethod() (en el módulo inspect)

ismethoddescriptor() (en el módulo inspect)

ismodule() (en el módulo inspect)

ismount() (en el módulo os.path)

isnan() (en el módulo cmath)

(en el módulo math)

ISNONTERMINAL() (en el módulo token)

IsNot (clase en ast)

isnumeric() (método de str)

isocalendar() (método de datetime.date)

(método de datetime.datetime)

isoformat() (método de datetime.date)

(método de datetime.datetime)

(método de datetime.time)

IsolatedAsyncioTestCase (clase en unittest)

isolation_level (atributo de sqlite3.Connection)

isoweekday() (método de datetime.date)

(método de datetime.datetime)

isprint() (en el módulo curses.ascii)

isprintable() (método de str)

ispunct() (en el módulo curses.ascii)

isqrt() (en el módulo math)

isreadable() (en el módulo pprint)

(método de pprint.PrettyPrinter)

isrecursive() (en el módulo pprint)

(método de pprint.PrettyPrinter)

isreg() (método de tarfile.TarInfo)

isReservedKey() (método de http.cookies.Morsel)

isroutine() (en el módulo inspect)

isSameNode() (método de xml.dom.Node)

issoftkeyword() (en el módulo keyword)

isspace() (en el módulo curses.ascii)

(método de bytearray)

(método de bytes)

(método de str)

isstdin() (en el módulo fileinput)

issubclass() (función incorporada)

issubset() (método de frozenset)

issuite() (en el módulo parser)

(método de parser.ST)

issuperset() (método de frozenset)

issym() (método de tarfile.TarInfo)

ISTERMINAL() (en el módulo token)

istitle() (método de bytearray)

(método de bytes)

(método de str)

istraceback() (en el módulo inspect)

isub() (en el módulo operator)

isupper() (en el módulo curses.ascii)

(método de bytearray)

(método de bytes)

(método de str)

isvisible() (en el módulo turtle)

isxdigit() (en el módulo curses.ascii)

ITALIC (en el módulo tkinter.font)

item

sequence

string

item selection

item() (método de tkinter.ttk.Treeview)

(método de xml.dom.NamedNodeMap)

(método de xml.dom.NodeList)

itemgetter() (en el módulo operator)

items() (método de configparser.ConfigParser)

(método de contextvars.Context)

(método de dict)

(método de email.message.EmailMessage)

(método de email.message.Message)

(método de mailbox.Mailbox)

(método de types.MappingProxyType)

(método de xml.etree.ElementTree.Element)

itemsize (atributo de array.array)

(atributo de memoryview)

ItemsView (clase en collections.abc)

(clase en typing)

iter() (función incorporada)

(método de xml.etree.ElementTree.Element)

(método de xml.etree.ElementTree.ElementTree)

iter_attachments() (método de email.message.EmailMessage)

iter_child_nodes() (en el módulo ast)

iter_fields() (en el módulo ast)

iter_importers() (en el módulo pkgutil)

iter_modules() (en el módulo pkgutil)

iter_parts() (método de email.message.EmailMessage)

iter_unpack() (en el módulo struct)

(método de struct.Struct)

iterable

unpacking

Iterable (clase en collections.abc)

(clase en typing)

iterable asincrónico

iterador

iterador asincrónico

iterador generador

iterador generador asincrónico

Iterator (clase en collections.abc)

(clase en typing)

iterator protocol

iterdecode() (en el módulo codecs)

iterdir() (método de importlib.abc.Traversable)

(método de pathlib.Path)

(método de zipfile.Path)

iterdump() (método de sqlite3.Connection)

iterencode() (en el módulo codecs)

(método de json.JSONEncoder)

iterfind() (método de xml.etree.ElementTree.Element)

(método de xml.etree.ElementTree.ElementTree)

iteritems() (método de mailbox.Mailbox)

iterkeys() (método de mailbox.Mailbox)

itermonthdates() (método de calendar.Calendar)

itermonthdays() (método de calendar.Calendar)

itermonthdays2() (método de calendar.Calendar)

itermonthdays3() (método de calendar.Calendar)

itermonthdays4() (método de calendar.Calendar)

iternextfunc (tipo C)

iterparse() (en el módulo xml.etree.ElementTree)

itertext() (método de xml.etree.ElementTree.Element)

itertools (2to3 fixer)

(módulo)

itertools_imports (2to3 fixer)

itervalues() (método de mailbox.Mailbox)

iterweekdays() (método de calendar.Calendar)

ITIMER_PROF (en el módulo signal)

ITIMER_REAL (en el módulo signal)

ITIMER_VIRTUAL (en el módulo signal)

ItimerError

itruediv() (en el módulo operator)

ixor() (en el módulo operator)

J

j

in numeric literal

Jansen, Jack

Java

language

java_ver() (en el módulo platform)

join() (en el módulo os.path)

(en el módulo shlex)

(método de asyncio.Queue)

(método de bytearray)

(método de bytes)

(método de multiprocessing.JoinableQueue)

(método de multiprocessing.pool.Pool)

(método de multiprocessing.Process)

(método de queue.Queue)

(método de str)

(método de threading.Thread)

join_thread() (en el módulo test.support)

(método de multiprocessing.Queue)

JoinableQueue (clase en multiprocessing)

JoinedStr (clase en ast)

joinpath() (método de importlib.abc.Traversable)

(método de pathlib.PurePath)

js_output() (método de http.cookies.BaseCookie)

(método de http.cookies.Morsel)

json

módulo

json (módulo)

json.tool (módulo)

json.tool command line option

--compact

--help

--indent

--json-lines

--no-ensure-ascii

--no-indent

--sort-keys

--tab

-h

infile

outfile

JSONDecodeError

JSONDecoder (clase en json)

JSONEncoder (clase en json)

jump (pdb command)

JUMP_ABSOLUTE (opcode)

JUMP_FORWARD (opcode)

JUMP_IF_FALSE_OR_POP (opcode)

JUMP_IF_NOT_EXC_MATCH (opcode)

JUMP_IF_TRUE_OR_POP (opcode)

K

kbhit() (en el módulo msvcrt)

KDEDIR

kevent() (en el módulo select)

key

(atributo de http.cookies.Morsel)

(atributo de zoneinfo.ZoneInfo)

key/datum pair

KEY_ALL_ACCESS (en el módulo winreg)

KEY_CREATE_LINK (en el módulo winreg)

KEY_CREATE_SUB_KEY (en el módulo winreg)

KEY_ENUMERATE_SUB_KEYS (en el módulo winreg)

KEY_EXECUTE (en el módulo winreg)

KEY_NOTIFY (en el módulo winreg)

KEY_QUERY_VALUE (en el módulo winreg)

KEY_READ (en el módulo winreg)

KEY_SET_VALUE (en el módulo winreg)

KEY_WOW64_32KEY (en el módulo winreg)

KEY_WOW64_64KEY (en el módulo winreg)

KEY_WRITE (en el módulo winreg)

KeyboardInterrupt

(built-in exception), [1]

KeyError

keylog_filename (atributo de ssl.SSLContext)

keyname() (en el módulo curses)

keypad() (método de curses.window)

keyrefs() (método de weakref.WeakKeyDictionary)

keys() (método de contextvars.Context)

(método de dict)

(método de email.message.EmailMessage)

(método de email.message.Message)

(método de mailbox.Mailbox)

(método de sqlite3.Row)

(método de types.MappingProxyType)

(método de xml.etree.ElementTree.Element)

KeysView (clase en collections.abc)

(clase en typing)

keyword

(clase en ast)

(módulo)

keywords (atributo de functools.partial)

kill() (en el módulo os)

(método de asyncio.subprocess.Process)

(método de asyncio.SubprocessTransport)

(método de multiprocessing.Process)

(método de subprocess.Popen)

kill_python() (en el módulo test.support.script_helper)

killchar() (en el módulo curses)

killpg() (en el módulo os)

kind (atributo de inspect.Parameter)

knownfiles (en el módulo mimetypes)

kqueue() (en el módulo select)

KqueueSelector (clase en selectors)

kwargs (atributo de inspect.BoundArguments)

kwlist (en el módulo keyword)

L

L (en el módulo re)

LabelEntry (clase en tkinter.tix)

LabelFrame (clase en tkinter.tix)

lambda

expression, [1]

form

Lambda (clase en ast)

LambdaType (en el módulo types)

LANG, [1], [2], [3], [4]

LANGUAGE, [1]

language

C, [1], [2], [3], [4], [5]

Java

large files

LARGEST (en el módulo test.support)

LargeZipFile

last() (método de nntplib.NNTP)

last_accepted (atributo de multiprocessing.connection.Listener)

last_traceback (en el módulo sys)

(in module sys)

last_type (en el módulo sys)

last_value (en el módulo sys)

lastChild (atributo de xml.dom.Node)

lastcmd (atributo de cmd.Cmd)

lastgroup (atributo de re.Match)

lastindex (atributo de re.Match)

lastResort (en el módulo logging)

lastrowid (atributo de sqlite3.Cursor)

layout() (método de tkinter.ttk.Style)

lazycache() (en el módulo linecache)

LazyLoader (clase en importlib.util)

LBRACE (en el módulo token)

LBYL

LC_ALL, [1]

(en el módulo locale)

LC_COLLATE (en el módulo locale)

LC_CTYPE (en el módulo locale)

LC_MESSAGES, [1]

(en el módulo locale)

LC_MONETARY (en el módulo locale)

LC_NUMERIC (en el módulo locale)

LC_TIME (en el módulo locale)

lchflags() (en el módulo os)

lchmod() (en el módulo os)

(método de pathlib.Path)

lchown() (en el módulo os)

lcm() (en el módulo math)

LDCXXSHARED

ldexp() (en el módulo math)

LDFLAGS

ldgettext() (en el módulo gettext)

ldngettext() (en el módulo gettext)

le() (en el módulo operator)

leading whitespace

leapdays() (en el módulo calendar)

leaveok() (método de curses.window)

left (atributo de filecmp.dircmp)

left() (en el módulo turtle)

left_list (atributo de filecmp.dircmp)

left_only (atributo de filecmp.dircmp)

LEFTSHIFT (en el módulo token)

LEFTSHIFTEQUAL (en el módulo token)

len

función incorporada, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11]

len() (función incorporada)

lenfunc (tipo C)

length (atributo de xml.dom.NamedNodeMap)

(atributo de xml.dom.NodeList)

length_hint() (en el módulo operator)

LESS (en el módulo token)

LESSEQUAL (en el módulo token)

lexical analysis

lexical definitions

lexists() (en el módulo os.path)

lgamma() (en el módulo math)

lgettext() (en el módulo gettext)

(método de gettext.GNUTranslations)

(método de gettext.NullTranslations)

lib2to3 (módulo)

libc_ver() (en el módulo platform)

library (atributo de ssl.SSLError)

(en el módulo dbm.ndbm)

library_dir_option() (método de distutils.ccompiler.CCompiler)

library_filename() (método de distutils.ccompiler.CCompiler)

library_option() (método de distutils.ccompiler.CCompiler)

LibraryLoader (clase en ctypes)

license (variable incorporada)

LifoQueue (clase en asyncio)

(clase en queue)

light-weight processes

limit_denominator() (método de fractions.Fraction)

LimitOverrunError

lin2adpcm() (en el módulo audioop)

lin2alaw() (en el módulo audioop)

lin2lin() (en el módulo audioop)

lin2ulaw() (en el módulo audioop)

line continuation

line joining, [1]

line structure

line() (método de msilib.Dialog)

line-buffered I/O

line_buffering (atributo de io.TextIOWrapper)

line_num (atributo de csv.csvreader)

linecache (módulo)

lineno (atributo de ast.AST)

(atributo de doctest.DocTest)

(atributo de doctest.Example)

(atributo de json.JSONDecodeError)

(atributo de pyclbr.Class)

(atributo de pyclbr.Function)

(atributo de re.error)

(atributo de shlex.shlex)

(atributo de SyntaxError)

(atributo de traceback.TracebackException)

(atributo de tracemalloc.Filter)

(atributo de tracemalloc.Frame)

(atributo de xml.parsers.expat.ExpatError)

lineno() (en el módulo fileinput)

LINES, [1], [2], [3], [4]

lines (atributo de os.terminal_size)

linesep (atributo de email.policy.Policy)

(en el módulo os)

lineterminator (atributo de csv.Dialect)

LineTooLong

link() (en el módulo os)

(método de distutils.ccompiler.CCompiler)

link_executable() (método de distutils.ccompiler.CCompiler)

link_shared_lib() (método de distutils.ccompiler.CCompiler)

link_shared_object() (método de distutils.ccompiler.CCompiler)

link_to() (método de pathlib.Path)

linkname (atributo de tarfile.TarInfo)

LinkOutsideDestinationError

list

assignment, target

comprehensions

deletion target

display

empty

expression, [1], [2]

objeto, [1], [2], [3], [4], [5], [6], [7], [8]

target, [1]

type, operations on

List (clase en ast)

(clase en typing)

list (clase incorporada)

(pdb command)

list() (método de imaplib.IMAP4)

(método de multiprocessing.managers.SyncManager)

(método de nntplib.NNTP)

(método de poplib.POP3)

(método de tarfile.TarFile)

LIST_APPEND (opcode)

list_dialects() (en el módulo csv)

LIST_EXTEND (opcode)

list_folders() (método de mailbox.Maildir)

(método de mailbox.MH)

LIST_TO_TUPLE (opcode)

lista

ListComp (clase en ast)

listdir() (en el módulo os)

listen() (en el módulo logging.config)

(en el módulo turtle)

(método de asyncore.dispatcher)

(método de socket.socket)

Listener (clase en multiprocessing.connection)

listMethods() (método de xmlrpc.client.ServerProxy.system)

ListNoteBook (clase en tkinter.tix)

listxattr() (en el módulo os)

literal, [1]

Literal (en el módulo typing)

literal_eval() (en el módulo ast)

literals

binary

complex number

floating point

hexadecimal

integer

numeric

octal

LittleEndianStructure (clase en ctypes)

ljust() (método de bytearray)

(método de bytes)

(método de str)

LK_LOCK (en el módulo msvcrt)

LK_NBLCK (en el módulo msvcrt)

LK_NBRLCK (en el módulo msvcrt)

LK_RLCK (en el módulo msvcrt)

LK_UNLCK (en el módulo msvcrt)

ll (pdb command)

LMTP (clase en smtplib)

ln() (método de decimal.Context)

(método de decimal.Decimal)

LNAME

lngettext() (en el módulo gettext)

(método de gettext.GNUTranslations)

(método de gettext.NullTranslations)

Load (clase en ast)

load() (en el módulo json)

(en el módulo marshal)

(en el módulo pickle)

(en el módulo plistlib)

(método de clase de tracemalloc.Snapshot)

(método de http.cookiejar.FileCookieJar)

(método de http.cookies.BaseCookie)

(método de pickle.Unpickler)

LOAD_ASSERTION_ERROR (opcode)

LOAD_ATTR (opcode)

LOAD_BUILD_CLASS (opcode)

load_cert_chain() (método de ssl.SSLContext)

LOAD_CLASSDEREF (opcode)

LOAD_CLOSURE (opcode)

LOAD_CONST (opcode)

load_default_certs() (método de ssl.SSLContext)

LOAD_DEREF (opcode)

load_dh_params() (método de ssl.SSLContext)

load_extension() (método de sqlite3.Connection)

LOAD_FAST (opcode)

LOAD_GLOBAL (opcode)

LOAD_METHOD (opcode)

load_module() (en el módulo imp)

(método de importlib.abc.FileLoader)

(método de importlib.abc.InspectLoader)

(método de importlib.abc.Loader)

(método de importlib.abc.SourceLoader)

(método de importlib.machinery.SourceFileLoader)

(método de importlib.machinery.SourcelessFileLoader)

(método de zipimport.zipimporter)

LOAD_NAME (opcode)

load_package_tests() (en el módulo test.support)

load_verify_locations() (método de ssl.SSLContext)

loader

(atributo de importlib.machinery.ModuleSpec)

Loader (clase en importlib.abc)

loader_state (atributo de importlib.machinery.ModuleSpec)

LoadError

LoadFileDialog (clase en tkinter.filedialog)

LoadKey() (en el módulo winreg)

LoadLibrary() (método de ctypes.LibraryLoader)

loads() (en el módulo json)

(en el módulo marshal)

(en el módulo pickle)

(en el módulo plistlib)

(en el módulo xmlrpc.client)

loadTestsFromModule() (método de unittest.TestLoader)

loadTestsFromName() (método de unittest.TestLoader)

loadTestsFromNames() (método de unittest.TestLoader)

loadTestsFromTestCase() (método de unittest.TestLoader)

local (clase en threading)

localcontext() (en el módulo decimal)

LOCALE (en el módulo re)

locale (módulo)

localeconv() (en el módulo locale)

LocaleHTMLCalendar (clase en calendar)

LocaleTextCalendar (clase en calendar)

localName (atributo de xml.dom.Attr)

(atributo de xml.dom.Node)

locals() (función incorporada)

localtime() (en el módulo email.utils)

(en el módulo time)

Locator (clase en xml.sax.xmlreader)

Lock (clase en asyncio)

(clase en multiprocessing)

(clase en threading)

lock() (método de mailbox.Babyl)

(método de mailbox.Mailbox)

(método de mailbox.Maildir)

(método de mailbox.mbox)

(método de mailbox.MH)

(método de mailbox.MMDF)

Lock() (método de multiprocessing.managers.SyncManager)

lock, interpreter

lock_held() (en el módulo imp)

locked() (método de _thread.lock)

(método de asyncio.Condition)

(método de asyncio.Lock)

(método de asyncio.Semaphore)

(método de threading.Lock)

lockf() (en el módulo fcntl)

(en el módulo os)

locking() (en el módulo msvcrt)

LockType (en el módulo _thread)

log() (en el módulo cmath)

(en el módulo logging)

(en el módulo math)

(método de logging.Logger)

log10() (en el módulo cmath)

(en el módulo math)

(método de decimal.Context)

(método de decimal.Decimal)

log1p() (en el módulo math)

log2() (en el módulo math)

log_date_time_string() (método de http.server.BaseHTTPRequestHandler)

log_error() (método de http.server.BaseHTTPRequestHandler)

log_exception() (método de wsgiref.handlers.BaseHandler)

log_message() (método de http.server.BaseHTTPRequestHandler)

log_request() (método de http.server.BaseHTTPRequestHandler)

log_to_stderr() (en el módulo multiprocessing)

logb() (método de decimal.Context)

(método de decimal.Decimal)

Logger (clase en logging)

LoggerAdapter (clase en logging)

logging

Errors

logging (módulo)

logging.config (módulo)

logging.handlers (módulo)

logical line

logical_and() (método de decimal.Context)

(método de decimal.Decimal)

logical_invert() (método de decimal.Context)

(método de decimal.Decimal)

logical_or() (método de decimal.Context)

(método de decimal.Decimal)

logical_xor() (método de decimal.Context)

(método de decimal.Decimal)

login() (método de ftplib.FTP)

(método de imaplib.IMAP4)

(método de nntplib.NNTP)

(método de smtplib.SMTP)

login_cram_md5() (método de imaplib.IMAP4)

LOGNAME, [1]

lognormvariate() (en el módulo random)

logout() (método de imaplib.IMAP4)

LogRecord (clase en logging)

long (2to3 fixer)

long integer

objeto

LONG_MAX

LONG_TIMEOUT (en el módulo test.support)

longMessage (atributo de unittest.TestCase)

longname() (en el módulo curses)

lookup() (en el módulo codecs)

(en el módulo unicodedata)

(método de symtable.SymbolTable)

(método de tkinter.ttk.Style)

lookup_error() (en el módulo codecs)

LookupError

loop

over mutable sequence

statement, [1], [2], [3]

loop control

target

loop() (en el módulo asyncore)

LOOPBACK_TIMEOUT (en el módulo test.support)

lower() (método de bytearray)

(método de bytes)

(método de str)

LPAR (en el módulo token)

lpAttributeList (atributo de subprocess.STARTUPINFO)

lru_cache() (en el módulo functools)

lseek() (en el módulo os)

LShift (clase en ast)

lshift() (en el módulo operator)

LSQB (en el módulo token)

lstat() (en el módulo os)

(método de pathlib.Path)

lstrip() (método de bytearray)

(método de bytes)

(método de str)

lsub() (método de imaplib.IMAP4)

Lt (clase en ast)

lt() (en el módulo operator)

(en el módulo turtle)

LtE (clase en ast)

LWPCookieJar (clase en http.cookiejar)

lzma (módulo)

LZMACompressor (clase en lzma)

LZMADecompressor (clase en lzma)

LZMAError

LZMAFile (clase en lzma)

M

M (en el módulo re)

mac_ver() (en el módulo platform)

machine() (en el módulo platform)

macros (atributo de netrc.netrc)

MADV_AUTOSYNC (en el módulo mmap)

MADV_CORE (en el módulo mmap)

MADV_DODUMP (en el módulo mmap)

MADV_DOFORK (en el módulo mmap)

MADV_DONTDUMP (en el módulo mmap)

MADV_DONTFORK (en el módulo mmap)

MADV_DONTNEED (en el módulo mmap)

MADV_FREE (en el módulo mmap)

MADV_HUGEPAGE (en el módulo mmap)

MADV_HWPOISON (en el módulo mmap)

MADV_MERGEABLE (en el módulo mmap)

MADV_NOCORE (en el módulo mmap)

MADV_NOHUGEPAGE (en el módulo mmap)

MADV_NORMAL (en el módulo mmap)

MADV_NOSYNC (en el módulo mmap)

MADV_PROTECT (en el módulo mmap)

MADV_RANDOM (en el módulo mmap)

MADV_REMOVE (en el módulo mmap)

MADV_SEQUENTIAL (en el módulo mmap)

MADV_SOFT_OFFLINE (en el módulo mmap)

MADV_UNMERGEABLE (en el módulo mmap)

MADV_WILLNEED (en el módulo mmap)

madvise() (método de mmap.mmap)

magic

method

MAGIC_NUMBER (en el módulo importlib.util)

MagicMock (clase en unittest.mock)

Mailbox (clase en mailbox)

mailbox (módulo)

mailcap (módulo)

Maildir (clase en mailbox)

MaildirMessage (clase en mailbox)

mailfrom (atributo de smtpd.SMTPChannel)

MailmanProxy (clase en smtpd)

main(), [1], [2]

(en el módulo py_compile)

(en el módulo site)

(en el módulo unittest)

main_thread() (en el módulo threading)

mainloop() (en el módulo turtle)

maintype (atributo de email.headerregistry.ContentTypeHeader)

major (atributo de email.headerregistry.MIMEVersionHeader)

major() (en el módulo os)

make_alternative() (método de email.message.EmailMessage)

make_archive() (en el módulo distutils.archive_util)

(en el módulo shutil)

make_bad_fd() (en el módulo test.support)

make_cookies() (método de http.cookiejar.CookieJar)

make_dataclass() (en el módulo dataclasses)

make_file() (método de difflib.HtmlDiff)

MAKE_FUNCTION (opcode)

make_header() (en el módulo email.header)

make_legacy_pyc() (en el módulo test.support)

make_mixed() (método de email.message.EmailMessage)

make_msgid() (en el módulo email.utils)

make_parser() (en el módulo xml.sax)

make_pkg() (en el módulo test.support.script_helper)

make_related() (método de email.message.EmailMessage)

make_script() (en el módulo test.support.script_helper)

make_server() (en el módulo wsgiref.simple_server)

make_table() (método de difflib.HtmlDiff)

make_tarball() (en el módulo distutils.archive_util)

make_zip_pkg() (en el módulo test.support.script_helper)

make_zip_script() (en el módulo test.support.script_helper)

make_zipfile() (en el módulo distutils.archive_util)

makedev() (en el módulo os)

makedirs() (en el módulo os)

makeelement() (método de xml.etree.ElementTree.Element)

makefile() (método de socket.socket)

(socket method)

makeLogRecord() (en el módulo logging)

makePickle() (método de logging.handlers.SocketHandler)

makeRecord() (método de logging.Logger)

makeSocket() (método de logging.handlers.DatagramHandler)

(método de logging.handlers.SocketHandler)

maketrans() (método estático de bytearray)

(método estático de bytes)

(método estático de str)

malloc()

mangle_from_ (atributo de email.policy.Compat32)

(atributo de email.policy.Policy)

mangling

name, [1]

map (2to3 fixer)

map() (función incorporada)

(método de concurrent.futures.Executor)

(método de multiprocessing.pool.Pool)

(método de tkinter.ttk.Style)

MAP_ADD (opcode)

map_async() (método de multiprocessing.pool.Pool)

map_table_b2() (en el módulo stringprep)

map_table_b3() (en el módulo stringprep)

map_to_type() (método de email.headerregistry.HeaderRegistry)

mapeado

mapLogRecord() (método de logging.handlers.HTTPHandler)

mapping

objeto, [1], [2], [3], [4], [5]

types, operations on

Mapping (clase en collections.abc)

(clase en typing)

mapping() (método de msilib.Control)

MappingProxyType (clase en types)

MappingView (clase en collections.abc)

(clase en typing)

mapPriority() (método de logging.handlers.SysLogHandler)

maps (atributo de collections.ChainMap)

maps() (en el módulo nis)

marshal (módulo)

marshalling

objects

masking

operations

master (atributo de tkinter.Tk)

Match (clase en typing)

match() (en el módulo nis)

(en el módulo re)

(método de pathlib.PurePath)

(método de re.Pattern)

match_hostname() (en el módulo ssl)

match_test() (en el módulo test.support)

match_value() (método de test.support.Matcher)

Matcher (clase en test.support)

matches() (método de test.support.Matcher)

math

módulo, [1]

math (módulo)

matmul() (en el módulo operator)

MatMult (clase en ast)

matrix multiplication

max

función incorporada

max (atributo de datetime.date)

(atributo de datetime.datetime)

(atributo de datetime.time)

(atributo de datetime.timedelta)

max() (en el módulo audioop)

(función incorporada)

(método de decimal.Context)

(método de decimal.Decimal)

max_count (atributo de email.headerregistry.BaseHeader)

MAX_EMAX (en el módulo decimal)

MAX_INTERPOLATION_DEPTH (en el módulo configparser)

max_line_length (atributo de email.policy.Policy)

max_lines (atributo de textwrap.TextWrapper)

max_mag() (método de decimal.Context)

(método de decimal.Decimal)

max_memuse (en el módulo test.support)

MAX_PREC (en el módulo decimal)

max_prefixlen (atributo de ipaddress.IPv4Address)

(atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Address)

(atributo de ipaddress.IPv6Network)

MAX_Py_ssize_t (en el módulo test.support)

maxarray (atributo de reprlib.Repr)

maxdeque (atributo de reprlib.Repr)

maxdict (atributo de reprlib.Repr)

maxDiff (atributo de unittest.TestCase)

maxfrozenset (atributo de reprlib.Repr)

MAXIMUM_SUPPORTED (atributo de ssl.TLSVersion)

maximum_version (atributo de ssl.SSLContext)

maxlen (atributo de collections.deque)

maxlevel (atributo de reprlib.Repr)

maxlist (atributo de reprlib.Repr)

maxlong (atributo de reprlib.Repr)

maxother (atributo de reprlib.Repr)

maxpp() (en el módulo audioop)

maxset (atributo de reprlib.Repr)

maxsize (atributo de asyncio.Queue)

(en el módulo sys)

maxstring (atributo de reprlib.Repr)

maxtuple (atributo de reprlib.Repr)

maxunicode (en el módulo sys)

MAXYEAR (en el módulo datetime)

máquina virtual

MB_ICONASTERISK (en el módulo winsound)

MB_ICONEXCLAMATION (en el módulo winsound)

MB_ICONHAND (en el módulo winsound)

MB_ICONQUESTION (en el módulo winsound)

MB_OK (en el módulo winsound)

mbox (clase en mailbox)

mboxMessage (clase en mailbox)

mean (atributo de statistics.NormalDist)

mean() (en el módulo statistics)

measure() (método de tkinter.font.Font)

median (atributo de statistics.NormalDist)

median() (en el módulo statistics)

median_grouped() (en el módulo statistics)

median_high() (en el módulo statistics)

median_low() (en el módulo statistics)

MemberDescriptorType (en el módulo types)

membership

test

memfd_create() (en el módulo os)

memmove() (en el módulo ctypes)

MemoryBIO (clase en ssl)

MemoryError

MemoryHandler (clase en logging.handlers)

memoryview

objeto, [1]

memoryview (clase incorporada)

memset() (en el módulo ctypes)

merge() (en el módulo heapq)

Message (clase en email.message)

(clase en mailbox)

(clase en tkinter.messagebox)

message digest, MD5

message_factory (atributo de email.policy.Policy)

message_from_binary_file() (en el módulo email)

message_from_bytes() (en el módulo email)

message_from_file() (en el módulo email)

message_from_string() (en el módulo email)

MessageBeep() (en el módulo winsound)

MessageClass (atributo de http.server.BaseHTTPRequestHandler)

MessageError

MessageParseError

messages (en el módulo xml.parsers.expat.errors)

meta

hooks

meta buscadores de ruta

meta hooks

meta() (en el módulo curses)

meta_path (en el módulo sys)

metaclase

metaclass

(2to3 fixer)

metaclass hint

MetaPathFinder (clase en importlib.abc)

metavar (atributo de optparse.Option)

MetavarTypeHelpFormatter (clase en argparse)

Meter (clase en tkinter.tix)

METH_CLASS (variable incorporada)

METH_COEXIST (variable incorporada)

METH_FASTCALL (variable incorporada)

METH_NOARGS (variable incorporada)

METH_O (variable incorporada)

METH_STATIC (variable incorporada)

METH_VARARGS (variable incorporada)

method

built-in

call

magic

objeto, [1], [2], [3], [4], [5]

special

user-defined

method (atributo de urllib.request.Request)

METHOD_BLOWFISH (en el módulo crypt)

method_calls (atributo de unittest.mock.Mock)

METHOD_CRYPT (en el módulo crypt)

METHOD_MD5 (en el módulo crypt)

METHOD_SHA256 (en el módulo crypt)

METHOD_SHA512 (en el módulo crypt)

methodattrs (2to3 fixer)

methodcaller() (en el módulo operator)

MethodDescriptorType (en el módulo types)

methodHelp() (método de xmlrpc.client.ServerProxy.system)

methods

bytearray

bytes

string

methods (atributo de pyclbr.Class)

(en el módulo crypt)

methodSignature() (método de xmlrpc.client.ServerProxy.system)

MethodType (en el módulo types)

(in module types), [1]

MethodWrapperType (en el módulo types)

metrics() (método de tkinter.font.Font)

método

método especial

método mágico

MFD_ALLOW_SEALING (en el módulo os)

MFD_CLOEXEC (en el módulo os)

MFD_HUGE_16GB (en el módulo os)

MFD_HUGE_16MB (en el módulo os)

MFD_HUGE_1GB (en el módulo os)

MFD_HUGE_1MB (en el módulo os)

MFD_HUGE_256MB (en el módulo os)

MFD_HUGE_2GB (en el módulo os)

MFD_HUGE_2MB (en el módulo os)

MFD_HUGE_32MB (en el módulo os)

MFD_HUGE_512KB (en el módulo os)

MFD_HUGE_512MB (en el módulo os)

MFD_HUGE_64KB (en el módulo os)

MFD_HUGE_8MB (en el módulo os)

MFD_HUGE_MASK (en el módulo os)

MFD_HUGE_SHIFT (en el módulo os)

MFD_HUGETLB (en el módulo os)

MH (clase en mailbox)

MHMessage (clase en mailbox)

microsecond (atributo de datetime.datetime)

(atributo de datetime.time)

MIME

base64 encoding

content type

headers, [1]

quoted-printable encoding

MIMEApplication (clase en email.mime.application)

MIMEAudio (clase en email.mime.audio)

MIMEBase (clase en email.mime.base)

MIMEImage (clase en email.mime.image)

MIMEMessage (clase en email.mime.message)

MIMEMultipart (clase en email.mime.multipart)

MIMENonMultipart (clase en email.mime.nonmultipart)

MIMEPart (clase en email.message)

MIMEText (clase en email.mime.text)

MimeTypes (clase en mimetypes)

mimetypes (módulo)

MIMEVersionHeader (clase en email.headerregistry)

min

función incorporada

min (atributo de datetime.date)

(atributo de datetime.datetime)

(atributo de datetime.time)

(atributo de datetime.timedelta)

min() (función incorporada)

(método de decimal.Context)

(método de decimal.Decimal)

MIN_EMIN (en el módulo decimal)

MIN_ETINY (en el módulo decimal)

min_mag() (método de decimal.Context)

(método de decimal.Decimal)

MINEQUAL (en el módulo token)

MINIMUM_SUPPORTED (atributo de ssl.TLSVersion)

minimum_version (atributo de ssl.SSLContext)

minmax() (en el módulo audioop)

minor (atributo de email.headerregistry.MIMEVersionHeader)

minor() (en el módulo os)

minus

MINUS (en el módulo token)

minus() (método de decimal.Context)

minute (atributo de datetime.datetime)

(atributo de datetime.time)

MINYEAR (en el módulo datetime)

mirrored() (en el módulo unicodedata)

misc_header (atributo de cmd.Cmd)

MISSING (atributo de contextvars.Token)

MISSING_C_DOCSTRINGS (en el módulo test.support)

missing_compiler_executable() (en el módulo test.support)

MissingSectionHeaderError

MIXERDEV

mkd() (método de ftplib.FTP)

mkdir() (en el módulo os)

(método de pathlib.Path)

mkdtemp() (en el módulo tempfile)

mkfifo() (en el módulo os)

mknod() (en el módulo os)

mkpath() (en el módulo distutils.dir_util)

(método de distutils.ccompiler.CCompiler)

mksalt() (en el módulo crypt)

mkstemp() (en el módulo tempfile)

mktemp() (en el módulo tempfile)

mktime() (en el módulo time)

mktime_tz() (en el módulo email.utils)

mlsd() (método de ftplib.FTP)

mmap (clase en mmap)

(módulo)

MMDF (clase en mailbox)

MMDFMessage (clase en mailbox)

Mock (clase en unittest.mock)

mock_add_spec() (método de unittest.mock.Mock)

mock_calls (atributo de unittest.mock.Mock)

mock_open() (en el módulo unittest.mock)

Mod (clase en ast)

mod() (en el módulo operator)

mode (atributo de io.FileIO)

(atributo de ossaudiodev.oss_audio_device)

(atributo de statistics.NormalDist)

(atributo de tarfile.TarInfo)

mode() (en el módulo statistics)

(en el módulo turtle)

modes

file

modf() (en el módulo math)

modified() (método de urllib.robotparser.RobotFileParser)

Modify() (método de msilib.View)

modify() (método de select.devpoll)

(método de select.epoll)

(método de select.poll)

(método de selectors.BaseSelector)

module

extension

importing

namespace

objeto, [1], [2]

search path, [1], [2], [3], [4], [5], [6], [7]

module (atributo de pyclbr.Class)

(atributo de pyclbr.Function)

module spec

module_for_loader() (en el módulo importlib.util)

module_from_spec() (en el módulo importlib.util)

module_repr() (método de importlib.abc.Loader)

ModuleFinder (clase en modulefinder)

modulefinder (módulo)

ModuleInfo (clase en pkgutil)

ModuleNotFoundError

modules (atributo de modulefinder.ModuleFinder)

(en el módulo sys)

(in module sys), [1]

modules_cleanup() (en el módulo test.support)

modules_setup() (en el módulo test.support)

ModuleSpec (clase en importlib.machinery)

ModuleType (clase en types)

(in module types)

modulo

monotonic() (en el módulo time)

monotonic_ns() (en el módulo time)

month (atributo de datetime.date)

(atributo de datetime.datetime)

month() (en el módulo calendar)

month_abbr (en el módulo calendar)

month_name (en el módulo calendar)

monthcalendar() (en el módulo calendar)

monthdatescalendar() (método de calendar.Calendar)

monthdays2calendar() (método de calendar.Calendar)

monthdayscalendar() (método de calendar.Calendar)

monthrange() (en el módulo calendar)

Morsel (clase en http.cookies)

most_common() (método de collections.Counter)

mouseinterval() (en el módulo curses)

mousemask() (en el módulo curses)

move() (en el módulo shutil)

(método de curses.panel.Panel)

(método de curses.window)

(método de mmap.mmap)

(método de tkinter.ttk.Treeview)

move_file() (en el módulo distutils.file_util)

(método de distutils.ccompiler.CCompiler)

move_to_end() (método de collections.OrderedDict)

MozillaCookieJar (clase en http.cookiejar)

módulo

__main__, [1], [2], [3], [4], [5], [6], [7]

_locale

_thread

array, [1]

base64

bdb

binhex

builtins, [1], [2], [3], [4]

cmd

copy

crypt

dbm.gnu, [1]

dbm.ndbm, [1]

errno

glob

imp

io

json

math, [1]

os

pickle, [1], [2], [3]

pty

pwd

pyexpat

re, [1]

shelve

signal, [1]

sitecustomize

socket

stat

string

struct

sys, [1], [2], [3], [4], [5], [6]

types

urllib.request

usercustomize

uu

módulo de extensión

MRO

mro() (método de class)

msg (atributo de http.client.HTTPResponse)

(atributo de json.JSONDecodeError)

(atributo de re.error)

(atributo de traceback.TracebackException)

msg() (método de telnetlib.Telnet)

msi

msilib (módulo)

msvcrt (módulo)

mt_interact() (método de telnetlib.Telnet)

mtime (atributo de gzip.GzipFile)

(atributo de tarfile.TarInfo)

mtime() (método de urllib.robotparser.RobotFileParser)

mul() (en el módulo audioop)

(en el módulo operator)

Mult (clase en ast)

MultiCall (clase en xmlrpc.client)

MULTILINE (en el módulo re)

MultiLoopChildWatcher (clase en asyncio)

multimode() (en el módulo statistics)

MultipartConversionError

multiplication

multiply() (método de decimal.Context)

multiprocessing (módulo)

multiprocessing.connection (módulo)

multiprocessing.dummy (módulo)

multiprocessing.Manager() (función incorporada)

multiprocessing.managers (módulo)

multiprocessing.pool (módulo)

multiprocessing.shared_memory (módulo)

multiprocessing.sharedctypes (módulo)

mutable

objeto, [1], [2]

sequence types

mutable object

mutable sequence

loop over

objeto

MutableMapping (clase en collections.abc)

(clase en typing)

MutableSequence (clase en collections.abc)

(clase en typing)

MutableSet (clase en collections.abc)

(clase en typing)

mvderwin() (método de curses.window)

mvwin() (método de curses.window)

myrights() (método de imaplib.IMAP4)

N

N_TOKENS (en el módulo token)

n_waiting (atributo de threading.Barrier)

name, [1], [2]

binding, [1], [2], [3], [4], [5], [6]

binding, global

class

function, [1]

mangling, [1]

rebinding

unbinding

name (atributo de codecs.CodecInfo)

(atributo de contextvars.ContextVar)

(atributo de doctest.DocTest)

(atributo de email.headerregistry.BaseHeader)

(atributo de hashlib.hash)

(atributo de hmac.HMAC)

(atributo de http.cookiejar.Cookie)

(atributo de importlib.abc.FileLoader)

(atributo de importlib.machinery.ExtensionFileLoader)

(atributo de importlib.machinery.ModuleSpec)

(atributo de importlib.machinery.SourceFileLoader)

(atributo de importlib.machinery.SourcelessFileLoader)

(atributo de inspect.Parameter)

(atributo de io.FileIO)

(atributo de multiprocessing.Process)

(atributo de multiprocessing.shared_memory.SharedMemory)

(atributo de os.DirEntry)

(atributo de ossaudiodev.oss_audio_device)

(atributo de pyclbr.Class)

(atributo de pyclbr.Function)

(atributo de tarfile.TarInfo)

(atributo de threading.Thread)

(atributo de xml.dom.Attr)

(atributo de xml.dom.DocumentType)

(atributo de zipfile.Path)

Name (clase en ast)

name (en el módulo os)

NAME (en el módulo token)

name() (en el módulo unicodedata)

(método de importlib.abc.Traversable)

name2codepoint (en el módulo html.entities)

Named Shared Memory

NamedExpr (clase en ast)

NamedTemporaryFile() (en el módulo tempfile)

NamedTuple (clase en typing)

namedtuple() (en el módulo collections)

NameError

excepción

NameError (built-in exception)

namelist() (método de zipfile.ZipFile)

nameprep() (en el módulo encodings.idna)

namer (atributo de logging.handlers.BaseRotatingHandler)

namereplace

error handler's name

namereplace_errors() (en el módulo codecs)

names

private

names() (en el módulo tkinter.font)

namespace

global

module

package

Namespace (clase en argparse)

(clase en multiprocessing.managers)

namespace() (método de imaplib.IMAP4)

Namespace() (método de multiprocessing.managers.SyncManager)

NAMESPACE_DNS (en el módulo uuid)

NAMESPACE_OID (en el módulo uuid)

NAMESPACE_URL (en el módulo uuid)

NAMESPACE_X500 (en el módulo uuid)

NamespaceErr

namespaceURI (atributo de xml.dom.Node)

nametofont() (en el módulo tkinter.font)

NaN

nan (en el módulo cmath)

(en el módulo math)

nanj (en el módulo cmath)

NannyNag

napms() (en el módulo curses)

nargs (atributo de optparse.Option)

native_id (atributo de threading.Thread)

nbytes (atributo de memoryview)

ncurses_version (en el módulo curses)

ndiff() (en el módulo difflib)

ndim (atributo de memoryview)

ne (2to3 fixer)

ne() (en el módulo operator)

needs_input (atributo de bz2.BZ2Decompressor)

(atributo de lzma.LZMADecompressor)

neg() (en el módulo operator)

negation

netmask (atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Network)

NetmaskValueError

netrc (clase en netrc)

(módulo)

NetrcParseError

netscape (atributo de http.cookiejar.CookiePolicy)

network (atributo de ipaddress.IPv4Interface)

(atributo de ipaddress.IPv6Interface)

Network News Transfer Protocol

network_address (atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Network)

NEVER_EQ (en el módulo test.support)

new() (en el módulo hashlib)

(en el módulo hmac)

new_alignment() (método de formatter.writer)

new_child() (método de collections.ChainMap)

new_class() (en el módulo types)

new_compiler() (en el módulo distutils.ccompiler)

new_event_loop() (en el módulo asyncio)

(método de asyncio.AbstractEventLoopPolicy)

new_font() (método de formatter.writer)

new_margin() (método de formatter.writer)

new_module() (en el módulo imp)

new_panel() (en el módulo curses.panel)

new_spacing() (método de formatter.writer)

new_styles() (método de formatter.writer)

newer() (en el módulo distutils.dep_util)

newer_group() (en el módulo distutils.dep_util)

newer_pairwise() (en el módulo distutils.dep_util)

newfunc (tipo C)

newgroups() (método de nntplib.NNTP)

NEWLINE (en el módulo token)

NEWLINE token, [1]

newlines (atributo de io.TextIOBase)

newnews() (método de nntplib.NNTP)

newpad() (en el módulo curses)

NewType() (en el módulo typing)

newwin() (en el módulo curses)

next (2to3 fixer)

(pdb command)

next() (función incorporada)

(método de nntplib.NNTP)

(método de tarfile.TarFile)

(método de tkinter.ttk.Treeview)

next_minus() (método de decimal.Context)

(método de decimal.Decimal)

next_plus() (método de decimal.Context)

(método de decimal.Decimal)

next_toward() (método de decimal.Context)

(método de decimal.Decimal)

nextafter() (en el módulo math)

nextfile() (en el módulo fileinput)

nextkey() (método de dbm.gnu.gdbm)

nextSibling (atributo de xml.dom.Node)

ngettext() (en el módulo gettext)

(método de gettext.GNUTranslations)

(método de gettext.NullTranslations)

nice() (en el módulo os)

nis (módulo)

NL (en el módulo token)

nl() (en el módulo curses)

nl_langinfo() (en el módulo locale)

nlargest() (en el módulo heapq)

nlst() (método de ftplib.FTP)

NNTP

protocol

NNTP (clase en nntplib)

nntp_implementation (atributo de nntplib.NNTP)

NNTP_SSL (clase en nntplib)

nntp_version (atributo de nntplib.NNTP)

NNTPDataError

NNTPError

nntplib (módulo)

NNTPPermanentError

NNTPProtocolError

NNTPReplyError

NNTPTemporaryError

no_cache() (método de clase de zoneinfo.ZoneInfo)

no_proxy

no_tracing() (en el módulo test.support)

no_type_check() (en el módulo typing)

no_type_check_decorator() (en el módulo typing)

nocbreak() (en el módulo curses)

NoDataAllowedErr

node() (en el módulo platform)

nodelay() (método de curses.window)

nodeName (atributo de xml.dom.Node)

NodeTransformer (clase en ast)

nodeType (atributo de xml.dom.Node)

nodeValue (atributo de xml.dom.Node)

NodeVisitor (clase en ast)

noecho() (en el módulo curses)

NOEXPR (en el módulo locale)

nombre calificado

NoModificationAllowedErr

nonblock() (método de ossaudiodev.oss_audio_device)

NonCallableMagicMock (clase en unittest.mock)

NonCallableMock (clase en unittest.mock)

None

objeto, [1], [2]

None (Built-in object)

(variable incorporada)

nonl() (en el módulo curses)

nonlocal

sentencia

Nonlocal (clase en ast)

nonzero (2to3 fixer)

noop() (método de imaplib.IMAP4)

(método de poplib.POP3)

NoOptionError

NOP (opcode)

noqiflush() (en el módulo curses)

noraw() (en el módulo curses)

NoReturn (en el módulo typing)

NORMAL (en el módulo tkinter.font)

NORMAL_PRIORITY_CLASS (en el módulo subprocess)

NormalDist (clase en statistics)

normalize() (en el módulo locale)

(en el módulo unicodedata)

(método de decimal.Context)

(método de decimal.Decimal)

(método de xml.dom.Node)

NORMALIZE_WHITESPACE (en el módulo doctest)

normalvariate() (en el módulo random)

normcase() (en el módulo os.path)

normpath() (en el módulo os.path)

NoSectionError

NoSuchMailboxError

not

operador, [1]

Not (clase en ast)

not in

operador, [1], [2]

not_() (en el módulo operator)

NotADirectoryError

notation

notationDecl() (método de xml.sax.handler.DTDHandler)

NotationDeclHandler() (método de xml.parsers.expat.xmlparser)

notations (atributo de xml.dom.DocumentType)

NotConnected

NoteBook (clase en tkinter.tix)

Notebook (clase en tkinter.ttk)

NotEmptyError

NotEq (clase en ast)

NOTEQUAL (en el módulo token)

NotFoundErr

notify() (método de asyncio.Condition)

(método de threading.Condition)

notify_all() (método de asyncio.Condition)

(método de threading.Condition)

notimeout() (método de curses.window)

NotImplemented

objeto

NotImplemented (variable incorporada)

NotImplementedError

NotIn (clase en ast)

NotStandaloneHandler() (método de xml.parsers.expat.xmlparser)

NotSupportedErr

NotSupportedError

noutrefresh() (método de curses.window)

now() (método de clase de datetime.datetime)

npgettext() (en el módulo gettext)

(método de gettext.GNUTranslations)

(método de gettext.NullTranslations)

NSIG (en el módulo signal)

nsmallest() (en el módulo heapq)

NT_OFFSET (en el módulo token)

NTEventLogHandler (clase en logging.handlers)

ntohl() (en el módulo socket)

ntohs() (en el módulo socket)

ntransfercmd() (método de ftplib.FTP)

null

operation, [1]

nullcontext() (en el módulo contextlib)

NullFormatter (clase en formatter)

NullHandler (clase en logging)

NullImporter (clase en imp)

NullTranslations (clase en gettext)

NullWriter (clase en formatter)

num_addresses (atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Network)

num_tickets (atributo de ssl.SSLContext)

number

complex

floating point

Number (clase en numbers)

NUMBER (en el módulo token)

number_class() (método de decimal.Context)

(método de decimal.Decimal)

numbers (módulo)

numerator (atributo de fractions.Fraction)

(atributo de numbers.Rational)

numeric

conversions

literals

object

objeto, [1], [2], [3]

types, operations on

numeric literal

numeric() (en el módulo unicodedata)

numinput() (en el módulo turtle)

numliterals (2to3 fixer)

número complejo

O

O_APPEND (en el módulo os)

O_ASYNC (en el módulo os)

O_BINARY (en el módulo os)

O_CLOEXEC (en el módulo os)

O_CREAT (en el módulo os)

O_DIRECT (en el módulo os)

O_DIRECTORY (en el módulo os)

O_DSYNC (en el módulo os)

O_EXCL (en el módulo os)

O_EXLOCK (en el módulo os)

O_NDELAY (en el módulo os)

O_NOATIME (en el módulo os)

O_NOCTTY (en el módulo os)

O_NOFOLLOW (en el módulo os)

O_NOINHERIT (en el módulo os)

O_NONBLOCK (en el módulo os)

O_PATH (en el módulo os)

O_RANDOM (en el módulo os)

O_RDONLY (en el módulo os)

O_RDWR (en el módulo os)

O_RSYNC (en el módulo os)

O_SEQUENTIAL (en el módulo os)

O_SHLOCK (en el módulo os)

O_SHORT_LIVED (en el módulo os)

O_SYNC (en el módulo os)

O_TEMPORARY (en el módulo os)

O_TEXT (en el módulo os)

O_TMPFILE (en el módulo os)

O_TRUNC (en el módulo os)

O_WRONLY (en el módulo os)

obj (atributo de memoryview)

object

code, [1], [2], [3]

deallocation

finalization

immutable, [1]

numeric

object (atributo de UnicodeError)

(clase incorporada)

object.__slots__ (variable incorporada)

object_filenames() (método de distutils.ccompiler.CCompiler)

objects

comparing

flattening

marshalling

persistent

pickling

serializing

objeto

asynchronous-generator

Boolean, [1]

built-in function, [1]

built-in method, [1]

bytearray, [1], [2], [3]

bytes, [1], [2]

callable, [1]

Capsule

class, [1], [2]

class instance, [1], [2]

complex

complex number, [1]

dictionary, [1], [2], [3], [4], [5], [6], [7]

Ellipsis

file, [1]

floating point, [1], [2]

frame

frozenset, [1]

function, [1], [2], [3], [4], [5]

generator, [1], [2]

GenericAlias

immutable

immutable sequence

instance, [1], [2]

instancemethod

integer, [1], [2]

io.StringIO

list, [1], [2], [3], [4], [5], [6], [7], [8]

long integer

mapping, [1], [2], [3], [4], [5]

memoryview, [1]

method, [1], [2], [3], [4], [5]

module, [1], [2]

mutable, [1], [2]

mutable sequence

None, [1], [2]

NotImplemented

numeric, [1], [2], [3]

range

sequence, [1], [2], [3], [4], [5], [6], [7], [8]

set, [1], [2], [3]

set type

slice

socket

string, [1], [2]

traceback, [1], [2], [3], [4]

tuple, [1], [2], [3], [4], [5], [6]

type, [1], [2]

user-defined function, [1], [2]

user-defined method

objeto archivo

objeto tipo ruta

objetos tipo archivo

objetos tipo binarios

objobjargproc (tipo C)

objobjproc (tipo C)

obufcount() (método de ossaudiodev.oss_audio_device)

obuffree() (método de ossaudiodev.oss_audio_device)

oct() (función incorporada)

octal

literals

octal literal

octdigits (en el módulo string)

offset (atributo de SyntaxError)

(atributo de traceback.TracebackException)

(atributo de xml.parsers.expat.ExpatError)

OK (en el módulo curses)

ok_command() (método de tkinter.filedialog.LoadFileDialog)

(método de tkinter.filedialog.SaveFileDialog)

ok_event() (método de tkinter.filedialog.FileDialog)

old_value (atributo de contextvars.Token)

OleDLL (clase en ctypes)

on_motion() (método de tkinter.dnd.DndHandler)

on_release() (método de tkinter.dnd.DndHandler)

onclick() (en el módulo turtle)

ondrag() (en el módulo turtle)

onecmd() (método de cmd.Cmd)

onkey() (en el módulo turtle)

onkeypress() (en el módulo turtle)

onkeyrelease() (en el módulo turtle)

onrelease() (en el módulo turtle)

onscreenclick() (en el módulo turtle)

ontimer() (en el módulo turtle)

OP (en el módulo token)

OP_ALL (en el módulo ssl)

OP_CIPHER_SERVER_PREFERENCE (en el módulo ssl)

OP_ENABLE_MIDDLEBOX_COMPAT (en el módulo ssl)

OP_IGNORE_UNEXPECTED_EOF (en el módulo ssl)

OP_NO_COMPRESSION (en el módulo ssl)

OP_NO_RENEGOTIATION (en el módulo ssl)

OP_NO_SSLv2 (en el módulo ssl)

OP_NO_SSLv3 (en el módulo ssl)

OP_NO_TICKET (en el módulo ssl)

OP_NO_TLSv1 (en el módulo ssl)

OP_NO_TLSv1_1 (en el módulo ssl)

OP_NO_TLSv1_2 (en el módulo ssl)

OP_NO_TLSv1_3 (en el módulo ssl)

OP_SINGLE_DH_USE (en el módulo ssl)

OP_SINGLE_ECDH_USE (en el módulo ssl)

open

función incorporada, [1]

Open (clase en tkinter.filedialog)

open() (en el módulo aifc)

(en el módulo bz2)

(en el módulo codecs)

(en el módulo dbm)

(en el módulo dbm.dumb)

(en el módulo dbm.gnu)

(en el módulo dbm.ndbm)

(en el módulo gzip)

(en el módulo io)

(en el módulo lzma)

(en el módulo os)

(en el módulo ossaudiodev)

(en el módulo shelve)

(en el módulo sunau)

(en el módulo tarfile)

(en el módulo tokenize)

(en el módulo wave)

(en el módulo webbrowser)

(función incorporada)

(método de clase de tarfile.TarFile)

(método de distutils.text_file.TextFile)

(método de imaplib.IMAP4)

(método de importlib.abc.Traversable)

(método de pathlib.Path)

(método de pipes.Template)

(método de telnetlib.Telnet)

(método de urllib.request.OpenerDirector)

(método de urllib.request.URLopener)

(método de webbrowser.controller)

(método de zipfile.Path)

(método de zipfile.ZipFile)

open_binary() (en el módulo importlib.resources)

open_code() (en el módulo io)

open_connection() (en el módulo asyncio)

open_new() (en el módulo webbrowser)

(método de webbrowser.controller)

open_new_tab() (en el módulo webbrowser)

(método de webbrowser.controller)

open_osfhandle() (en el módulo msvcrt)

open_resource() (método de importlib.abc.ResourceReader)

open_text() (en el módulo importlib.resources)

open_unix_connection() (en el módulo asyncio)

open_unknown() (método de urllib.request.URLopener)

open_urlresource() (en el módulo test.support)

OpenDatabase() (en el módulo msilib)

OpenerDirector (clase en urllib.request)

OpenKey() (en el módulo winreg)

OpenKeyEx() (en el módulo winreg)

openlog() (en el módulo syslog)

openmixer() (en el módulo ossaudiodev)

openpty() (en el módulo os)

(en el módulo pty)

OpenSSL

(use in module hashlib)

(use in module ssl)

OPENSSL_VERSION (en el módulo ssl)

OPENSSL_VERSION_INFO (en el módulo ssl)

OPENSSL_VERSION_NUMBER (en el módulo ssl)

OpenView() (método de msilib.Database)

operador

!=, [1]

% (percent), [1]

& (ampersand), [1]

* (asterisk), [1]

**, [1]

/ (slash), [1]

//, [1]

< (less), [1]

<<, [1]

<=, [1]

==, [1]

> (greater), [1]

>=, [1]

>>, [1]

@ (at)

^ (caret), [1]

| (vertical bar), [1]

~ (tilde), [1]

and, [1], [2]

in, [1], [2]

is, [1]

is not, [1]

not, [1]

not in, [1], [2]

or, [1], [2]

operation

binary arithmetic

binary bitwise

Boolean

concatenation

null, [1]

power

repetition

shifting

slice

subscript

unary arithmetic

unary bitwise

OperationalError

operations

bitwise

Boolean, [1]

masking

shifting

operations on

dictionary type

integer types

list type

mapping types

numeric types

sequence types, [1]

operator

+ (plus), [1], [2]

- (minus), [1], [2]

comparison

overloading

precedence

ternary

operator (2to3 fixer)

(módulo)

operators

opmap (en el módulo dis)

opname (en el módulo dis)

optim_args_from_interpreter_flags() (en el módulo test.support)

optimize() (en el módulo pickletools)

OPTIMIZED_BYTECODE_SUFFIXES (en el módulo importlib.machinery)

Optional (en el módulo typing)

OptionGroup (clase en optparse)

OptionMenu (clase en tkinter.tix)

OptionParser (clase en optparse)

options (atributo de doctest.Example)

(atributo de ssl.SSLContext)

Options (clase en ssl)

options() (método de configparser.ConfigParser)

optionxform() (método de configparser.ConfigParser)

optparse (módulo)

or

bitwise

exclusive

inclusive

operador, [1], [2]

Or (clase en ast)

or_() (en el módulo operator)

ord

función incorporada

ord() (función incorporada)

orden de resolución de métodos

order

evaluation

ordered_attributes (atributo de xml.parsers.expat.xmlparser)

OrderedDict (clase en collections)

(clase en typing)

origin (atributo de importlib.machinery.ModuleSpec)

origin_req_host (atributo de urllib.request.Request)

origin_server (atributo de wsgiref.handlers.BaseHandler)

os

módulo

os (módulo)

os.path (módulo)

os_environ (atributo de wsgiref.handlers.BaseHandler)

OSError

ossaudiodev (módulo)

OSSAudioError

outfile

json.tool command line option

output

standard

output (atributo de subprocess.CalledProcessError)

(atributo de subprocess.TimeoutExpired)

(atributo de unittest.TestCase)

output() (método de http.cookies.BaseCookie)

(método de http.cookies.Morsel)

output_charset (atributo de email.charset.Charset)

output_charset() (método de gettext.NullTranslations)

output_codec (atributo de email.charset.Charset)

output_difference() (método de doctest.OutputChecker)

OutputChecker (clase en doctest)

OutputString() (método de http.cookies.Morsel)

OutsideDestinationError

over() (método de nntplib.NNTP)

Overflow (clase en decimal)

OverflowError

(built-in exception), [1], [2], [3], [4], [5]

overlap() (método de statistics.NormalDist)

overlaps() (método de ipaddress.IPv4Network)

(método de ipaddress.IPv6Network)

overlay() (método de curses.window)

overload() (en el módulo typing)

overloading

operator

overwrite() (método de curses.window)

owner() (método de pathlib.Path)

P

p (pdb command)

P_ALL (en el módulo os)

P_DETACH (en el módulo os)

P_NOWAIT (en el módulo os)

P_NOWAITO (en el módulo os)

P_OVERLAY (en el módulo os)

P_PGID (en el módulo os)

P_PID (en el módulo os)

P_PIDFD (en el módulo os)

P_WAIT (en el módulo os)

pack() (en el módulo struct)

(método de mailbox.MH)

(método de struct.Struct)

pack_array() (método de xdrlib.Packer)

pack_bytes() (método de xdrlib.Packer)

pack_double() (método de xdrlib.Packer)

pack_farray() (método de xdrlib.Packer)

pack_float() (método de xdrlib.Packer)

pack_fopaque() (método de xdrlib.Packer)

pack_fstring() (método de xdrlib.Packer)

pack_into() (en el módulo struct)

(método de struct.Struct)

pack_list() (método de xdrlib.Packer)

pack_opaque() (método de xdrlib.Packer)

pack_string() (método de xdrlib.Packer)

package, [1]

namespace

portion

regular

Package (en el módulo importlib.resources)

package variable

__all__

packed (atributo de ipaddress.IPv4Address)

(atributo de ipaddress.IPv6Address)

Packer (clase en xdrlib)

packing

binary data

packing (widgets)

PAGER

pair_content() (en el módulo curses)

pair_number() (en el módulo curses)

palabra clave

as, [1], [2]

async

await, [1]

elif

else, [1], [2], [3], [4], [5]

except

finally, [1], [2], [3], [4]

from, [1]

in

yield

PanedWindow (clase en tkinter.tix)

paquete

paquete de espacios de nombres

paquete provisorio

paquete regular

parameter

call semantics

difference from argument

function definition

value, default

Parameter (clase en inspect)

ParameterizedMIMEHeader (clase en email.headerregistry)

parameters (atributo de inspect.Signature)

params (atributo de email.headerregistry.ParameterizedMIMEHeader)

paramstyle (en el módulo sqlite3)

parámetro

pardir (en el módulo os)

paren (2to3 fixer)

parent (atributo de importlib.machinery.ModuleSpec)

(atributo de pyclbr.Class)

(atributo de pyclbr.Function)

(atributo de urllib.request.BaseHandler)

parent() (método de tkinter.ttk.Treeview)

parent_process() (en el módulo multiprocessing)

parenthesized form

parentNode (atributo de xml.dom.Node)

parents (atributo de collections.ChainMap)

paretovariate() (en el módulo random)

parse() (en el módulo ast)

(en el módulo cgi)

(en el módulo xml.dom.minidom)

(en el módulo xml.dom.pulldom)

(en el módulo xml.etree.ElementTree)

(en el módulo xml.sax)

(método de doctest.DocTestParser)

(método de email.parser.BytesParser)

(método de email.parser.Parser)

(método de string.Formatter)

(método de urllib.robotparser.RobotFileParser)

(método de xml.etree.ElementTree.ElementTree)

Parse() (método de xml.parsers.expat.xmlparser)

parse() (método de xml.sax.xmlreader.XMLReader)

parse_and_bind() (en el módulo readline)

parse_args() (método de argparse.ArgumentParser)

PARSE_COLNAMES (en el módulo sqlite3)

parse_config_h() (en el módulo sysconfig)

PARSE_DECLTYPES (en el módulo sqlite3)

parse_header() (en el módulo cgi)

parse_headers() (en el módulo http.client)

parse_intermixed_args() (método de argparse.ArgumentParser)

parse_known_args() (método de argparse.ArgumentParser)

parse_known_intermixed_args() (método de argparse.ArgumentParser)

parse_multipart() (en el módulo cgi)

parse_qs() (en el módulo urllib.parse)

parse_qsl() (en el módulo urllib.parse)

parseaddr() (en el módulo email.utils)

parsebytes() (método de email.parser.BytesParser)

parsedate() (en el módulo email.utils)

parsedate_to_datetime() (en el módulo email.utils)

parsedate_tz() (en el módulo email.utils)

ParseError (clase en xml.etree.ElementTree)

ParseFile() (método de xml.parsers.expat.xmlparser)

ParseFlags() (en el módulo imaplib)

parser

Parser (clase en email.parser)

parser (módulo)

ParserCreate() (en el módulo xml.parsers.expat)

ParserError

ParseResult (clase en urllib.parse)

ParseResultBytes (clase en urllib.parse)

parsestr() (método de email.parser.Parser)

parseString() (en el módulo xml.dom.minidom)

(en el módulo xml.dom.pulldom)

(en el módulo xml.sax)

parsing

Python source code

URL

ParsingError

partial (atributo de asyncio.IncompleteReadError)

partial() (en el módulo functools)

(método de imaplib.IMAP4)

partialmethod (clase en functools)

parties (atributo de threading.Barrier)

partition() (método de bytearray)

(método de bytes)

(método de str)

pass

sentencia

Pass (clase en ast)

pass_() (método de poplib.POP3)

Paste

patch() (en el módulo test.support)

(en el módulo unittest.mock)

patch.dict() (en el módulo unittest.mock)

patch.multiple() (en el módulo unittest.mock)

patch.object() (en el módulo unittest.mock)

patch.stopall() (en el módulo unittest.mock)

PATH, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21], [22], [23], [24], [25], [26], [27], [28], [29], [30], [31], [32], [33], [34], [35], [36], [37], [38], [39]

path

configuration file

hooks

module search, [1], [2], [3], [4], [5], [6], [7]

operations, [1]

path (atributo de http.cookiejar.Cookie)

(atributo de http.server.BaseHTTPRequestHandler)

(atributo de importlib.abc.FileLoader)

(atributo de importlib.machinery.ExtensionFileLoader)

(atributo de importlib.machinery.FileFinder)

(atributo de importlib.machinery.SourceFileLoader)

(atributo de importlib.machinery.SourcelessFileLoader)

(atributo de os.DirEntry)

Path (clase en pathlib)

(clase en zipfile)

path (en el módulo sys)

(in module sys), [1], [2], [3]

path based finder

Path browser

path hooks

path() (en el módulo importlib.resources)

path_hook() (método de clase de importlib.machinery.FileFinder)

path_hooks (en el módulo sys)

path_importer_cache (en el módulo sys)

path_mtime() (método de importlib.abc.SourceLoader)

path_return_ok() (método de http.cookiejar.CookiePolicy)

path_stats() (método de importlib.abc.SourceLoader)

(método de importlib.machinery.SourceFileLoader)

pathconf() (en el módulo os)

pathconf_names (en el módulo os)

PathEntryFinder (clase en importlib.abc)

PATHEXT, [1], [2]

PathFinder (clase en importlib.machinery)

pathlib (módulo)

PathLike (clase en os)

pathname2url() (en el módulo urllib.request)

pathsep (en el módulo os)

pattern (atributo de re.error)

(atributo de re.Pattern)

Pattern (clase en typing)

pause() (en el módulo signal)

pause_reading() (método de asyncio.ReadTransport)

pause_writing() (método de asyncio.BaseProtocol)

PAX_FORMAT (en el módulo tarfile)

pax_headers (atributo de tarfile.TarFile)

(atributo de tarfile.TarInfo)

pbkdf2_hmac() (en el módulo hashlib)

pd() (en el módulo turtle)

Pdb (clase en pdb)

(class in pdb)

pdb (módulo)

pdf() (método de statistics.NormalDist)

peek() (método de bz2.BZ2File)

(método de gzip.GzipFile)

(método de io.BufferedReader)

(método de lzma.LZMAFile)

(método de weakref.finalize)

peer (atributo de smtpd.SMTPChannel)

PEM_cert_to_DER_cert() (en el módulo ssl)

pen() (en el módulo turtle)

pencolor() (en el módulo turtle)

pending (atributo de ssl.MemoryBIO)

pending() (método de ssl.SSLSocket)

PendingDeprecationWarning

pendown() (en el módulo turtle)

pensize() (en el módulo turtle)

penup() (en el módulo turtle)

PEP

PERCENT (en el módulo token)

PERCENTEQUAL (en el módulo token)

perf_counter() (en el módulo time)

perf_counter_ns() (en el módulo time)

Performance

perm() (en el módulo math)

PermissionError

permutations() (en el módulo itertools)

Persist() (método de msilib.SummaryInformation)

persistence

persistent

objects

persistent_id (pickle protocol)

persistent_id() (método de pickle.Pickler)

persistent_load (pickle protocol)

persistent_load() (método de pickle.Unpickler)

PF_CAN (en el módulo socket)

PF_PACKET (en el módulo socket)

PF_RDS (en el módulo socket)

pformat() (en el módulo pprint)

(método de pprint.PrettyPrinter)

pgettext() (en el módulo gettext)

(método de gettext.GNUTranslations)

(método de gettext.NullTranslations)

PGO (en el módulo test.support)

phase() (en el módulo cmath)

Philbrick, Geoff

physical line, [1], [2]

pi (en el módulo cmath)

(en el módulo math)

pi() (método de xml.etree.ElementTree.TreeBuilder)

pickle

módulo, [1], [2], [3]

pickle (módulo)

pickle() (en el módulo copyreg)

PickleBuffer (clase en pickle)

PickleError

Pickler (clase en pickle)

pickletools (módulo)

pickletools command line option

--annotate

--indentlevel=<num>

--memo

--output=<file>

--preamble=<preamble>

-a

-l

-m

-o

-p

pickling

objects

PicklingError

pid (atributo de asyncio.subprocess.Process)

(atributo de multiprocessing.Process)

(atributo de subprocess.Popen)

pidfd_open() (en el módulo os)

pidfd_send_signal() (en el módulo signal)

PidfdChildWatcher (clase en asyncio)

PIP_USER

PIPE (en el módulo subprocess)

Pipe() (en el módulo multiprocessing)

pipe() (en el módulo os)

pipe2() (en el módulo os)

PIPE_BUF (en el módulo select)

pipe_connection_lost() (método de asyncio.SubprocessProtocol)

pipe_data_received() (método de asyncio.SubprocessProtocol)

PIPE_MAX_SIZE (en el módulo test.support)

pipes (módulo)

PKG_DIRECTORY (en el módulo imp)

pkgutil (módulo)

placeholder (atributo de textwrap.TextWrapper)

PLAT

platform (en el módulo sys)

(in module sys)

(módulo)

platform() (en el módulo platform)

platlibdir (en el módulo sys)

PlaySound() (en el módulo winsound)

plist

file

plistlib (módulo)

plock() (en el módulo os)

plus

PLUS (en el módulo token)

plus() (método de decimal.Context)

PLUSEQUAL (en el módulo token)

pm() (en el módulo pdb)

POINTER() (en el módulo ctypes)

pointer() (en el módulo ctypes)

polar() (en el módulo cmath)

Policy (clase en email.policy)

poll() (en el módulo select)

(método de multiprocessing.connection.Connection)

(método de select.devpoll)

(método de select.epoll)

(método de select.poll)

(método de subprocess.Popen)

PollSelector (clase en selectors)

Pool (clase en multiprocessing.pool)

pop() (método de array.array)

(método de collections.deque)

(método de dict)

(método de frozenset)

(método de mailbox.Mailbox)

(sequence method)

POP3

protocol

POP3 (clase en poplib)

POP3_SSL (clase en poplib)

pop_alignment() (método de formatter.formatter)

pop_all() (método de contextlib.ExitStack)

POP_BLOCK (opcode)

POP_EXCEPT (opcode)

pop_font() (método de formatter.formatter)

POP_JUMP_IF_FALSE (opcode)

POP_JUMP_IF_TRUE (opcode)

pop_margin() (método de formatter.formatter)

pop_source() (método de shlex.shlex)

pop_style() (método de formatter.formatter)

POP_TOP (opcode)

Popen (clase en subprocess)

popen() (en el módulo os)

(in module os), [1]

popitem() (método de collections.OrderedDict)

(método de dict)

(método de mailbox.Mailbox)

popleft() (método de collections.deque)

poplib (módulo)

PopupMenu (clase en tkinter.tix)

porción

port (atributo de http.cookiejar.Cookie)

port_specified (atributo de http.cookiejar.Cookie)

portion

package

pos (atributo de json.JSONDecodeError)

(atributo de re.error)

(atributo de re.Match)

pos() (en el módulo operator)

(en el módulo turtle)

position (atributo de xml.etree.ElementTree.ParseError)

position() (en el módulo turtle)

POSIX

I/O control

threads

posix (módulo)

POSIX Shared Memory

POSIX_FADV_DONTNEED (en el módulo os)

POSIX_FADV_NOREUSE (en el módulo os)

POSIX_FADV_NORMAL (en el módulo os)

POSIX_FADV_RANDOM (en el módulo os)

POSIX_FADV_SEQUENTIAL (en el módulo os)

POSIX_FADV_WILLNEED (en el módulo os)

posix_fadvise() (en el módulo os)

posix_fallocate() (en el módulo os)

posix_spawn() (en el módulo os)

POSIX_SPAWN_CLOSE (en el módulo os)

POSIX_SPAWN_DUP2 (en el módulo os)

POSIX_SPAWN_OPEN (en el módulo os)

posix_spawnp() (en el módulo os)

POSIXLY_CORRECT

PosixPath (clase en pathlib)

post() (método de nntplib.NNTP)

(método de ossaudiodev.oss_audio_device)

post_handshake_auth (atributo de ssl.SSLContext)

post_mortem() (en el módulo pdb)

post_setup() (método de venv.EnvBuilder)

postcmd() (método de cmd.Cmd)

postloop() (método de cmd.Cmd)

pow

función incorporada, [1], [2], [3], [4], [5]

Pow (clase en ast)

pow() (en el módulo math)

(en el módulo operator)

(función incorporada)

power

operation

power() (método de decimal.Context)

pp (pdb command)

pp() (en el módulo pprint)

pprint (módulo)

pprint() (en el módulo pprint)

(método de pprint.PrettyPrinter)

prcal() (en el módulo calendar)

pread() (en el módulo os)

preadv() (en el módulo os)

preamble (atributo de email.message.EmailMessage)

(atributo de email.message.Message)

precedence

operator

precmd() (método de cmd.Cmd)

prefix, [1], [2], [3]

(atributo de xml.dom.Attr)

(atributo de xml.dom.Node)

(atributo de zipimport.zipimporter)

PREFIX (en el módulo distutils.sysconfig)

prefix (en el módulo sys)

PREFIXES (en el módulo site)

prefixlen (atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Network)

preloop() (método de cmd.Cmd)

prepare() (método de graphlib.TopologicalSorter)

(método de logging.handlers.QueueHandler)

(método de logging.handlers.QueueListener)

prepare_class() (en el módulo types)

prepare_input_source() (en el módulo xml.sax.saxutils)

prepend() (método de pipes.Template)

preprocess() (método de distutils.ccompiler.CCompiler)

PrettyPrinter (clase en pprint)

prev() (método de tkinter.ttk.Treeview)

previousSibling (atributo de xml.dom.Node)

primary

print

función incorporada

print (2to3 fixer)

print() (built-in function)

__str__() (object method)

print() (función incorporada)

print_callees() (método de pstats.Stats)

print_callers() (método de pstats.Stats)

print_directory() (en el módulo cgi)

print_environ() (en el módulo cgi)

print_environ_usage() (en el módulo cgi)

print_exc() (en el módulo traceback)

(método de timeit.Timer)

print_exception() (en el módulo traceback)

PRINT_EXPR (opcode)

print_form() (en el módulo cgi)

print_help() (método de argparse.ArgumentParser)

print_last() (en el módulo traceback)

print_stack() (en el módulo traceback)

(método de asyncio.Task)

print_stats() (método de profile.Profile)

(método de pstats.Stats)

print_tb() (en el módulo traceback)

print_usage() (método de argparse.ArgumentParser)

(método de optparse.OptionParser)

print_version() (método de optparse.OptionParser)

print_warning() (en el módulo test.support)

printable (en el módulo string)

printdir() (método de zipfile.ZipFile)

printf-style formatting, [1]

PRIO_PGRP (en el módulo os)

PRIO_PROCESS (en el módulo os)

PRIO_USER (en el módulo os)

PriorityQueue (clase en asyncio)

(clase en queue)

private

names

prlimit() (en el módulo resource)

prmonth() (en el módulo calendar)

(método de calendar.TextCalendar)

ProactorEventLoop (clase en asyncio)

procedure

call

process

group, [1]

id

id of parent

killing, [1]

scheduling priority, [1]

signalling, [1]

Process (clase en multiprocessing)

process() (método de logging.LoggerAdapter)

process_exited() (método de asyncio.SubprocessProtocol)

process_message() (método de smtpd.SMTPServer)

process_request() (método de socketserver.BaseServer)

process_time() (en el módulo time)

process_time_ns() (en el módulo time)

process_tokens() (en el módulo tabnanny)

ProcessError

processes, light-weight

ProcessingInstruction() (en el módulo xml.etree.ElementTree)

processingInstruction() (método de xml.sax.handler.ContentHandler)

ProcessingInstructionHandler() (método de xml.parsers.expat.xmlparser)

ProcessLookupError

processor time, [1]

processor() (en el módulo platform)

ProcessPoolExecutor (clase en concurrent.futures)

prod() (en el módulo math)

product() (en el módulo itertools)

Profile (clase en profile)

profile (módulo)

profile function, [1], [2]

profiler, [1]

profiling, deterministic

program

ProgrammingError

Progressbar (clase en tkinter.ttk)

prompt (atributo de cmd.Cmd)

prompt_user_passwd() (método de urllib.request.FancyURLopener)

prompts, interpreter

propagate (atributo de logging.Logger)

property (clase incorporada)

property list

property_declaration_handler (en el módulo xml.sax.handler)

property_dom_node (en el módulo xml.sax.handler)

property_lexical_handler (en el módulo xml.sax.handler)

property_xml_string (en el módulo xml.sax.handler)

PropertyMock (clase en unittest.mock)

prot_c() (método de ftplib.FTP_TLS)

prot_p() (método de ftplib.FTP_TLS)

proto (atributo de socket.socket)

protocol

CGI

context management

copy

FTP, [1]

HTTP, [1], [2], [3], [4], [5]

IMAP4

IMAP4_SSL

IMAP4_stream

iterator

NNTP

POP3

SMTP

Telnet

protocol (atributo de ssl.SSLContext)

Protocol (clase en asyncio)

(clase en typing)

PROTOCOL_SSLv2 (en el módulo ssl)

PROTOCOL_SSLv23 (en el módulo ssl)

PROTOCOL_SSLv3 (en el módulo ssl)

PROTOCOL_TLS (en el módulo ssl)

PROTOCOL_TLS_CLIENT (en el módulo ssl)

PROTOCOL_TLS_SERVER (en el módulo ssl)

PROTOCOL_TLSv1 (en el módulo ssl)

PROTOCOL_TLSv1_1 (en el módulo ssl)

PROTOCOL_TLSv1_2 (en el módulo ssl)

protocol_version (atributo de http.server.BaseHTTPRequestHandler)

PROTOCOL_VERSION (atributo de imaplib.IMAP4)

ProtocolError (clase en xmlrpc.client)

proxy() (en el módulo weakref)

proxyauth() (método de imaplib.IMAP4)

ProxyBasicAuthHandler (clase en urllib.request)

ProxyDigestAuthHandler (clase en urllib.request)

ProxyHandler (clase en urllib.request)

ProxyType (en el módulo weakref)

ProxyTypes (en el módulo weakref)

pryear() (método de calendar.TextCalendar)

ps1 (en el módulo sys)

ps2 (en el módulo sys)

pstats (módulo)

pstdev() (en el módulo statistics)

pthread_getcpuclockid() (en el módulo time)

pthread_kill() (en el módulo signal)

pthread_sigmask() (en el módulo signal)

pthreads

pty

módulo

pty (módulo)

pu() (en el módulo turtle)

publicId (atributo de xml.dom.DocumentType)

PullDom (clase en xml.dom.pulldom)

punctuation (en el módulo string)

punctuation_chars (atributo de shlex.shlex)

PurePath (clase en pathlib)

PurePath.anchor (en el módulo pathlib)

PurePath.drive (en el módulo pathlib)

PurePath.name (en el módulo pathlib)

PurePath.parent (en el módulo pathlib)

PurePath.parents (en el módulo pathlib)

PurePath.parts (en el módulo pathlib)

PurePath.root (en el módulo pathlib)

PurePath.stem (en el módulo pathlib)

PurePath.suffix (en el módulo pathlib)

PurePath.suffixes (en el módulo pathlib)

PurePosixPath (clase en pathlib)

PureProxy (clase en smtpd)

PureWindowsPath (clase en pathlib)

purge() (en el módulo re)

Purpose.CLIENT_AUTH (en el módulo ssl)

Purpose.SERVER_AUTH (en el módulo ssl)

push() (método de asynchat.async_chat)

(método de code.InteractiveConsole)

(método de contextlib.ExitStack)

push_alignment() (método de formatter.formatter)

push_async_callback() (método de contextlib.AsyncExitStack)

push_async_exit() (método de contextlib.AsyncExitStack)

push_font() (método de formatter.formatter)

push_margin() (método de formatter.formatter)

push_source() (método de shlex.shlex)

push_style() (método de formatter.formatter)

push_token() (método de shlex.shlex)

push_with_producer() (método de asynchat.async_chat)

pushbutton() (método de msilib.Dialog)

put() (método de asyncio.Queue)

(método de multiprocessing.Queue)

(método de multiprocessing.SimpleQueue)

(método de queue.Queue)

(método de queue.SimpleQueue)

put_nowait() (método de asyncio.Queue)

(método de multiprocessing.Queue)

(método de queue.Queue)

(método de queue.SimpleQueue)

putch() (en el módulo msvcrt)

putenv() (en el módulo os)

putheader() (método de http.client.HTTPConnection)

putp() (en el módulo curses)

putrequest() (método de http.client.HTTPConnection)

putwch() (en el módulo msvcrt)

putwin() (método de curses.window)

pvariance() (en el módulo statistics)

pwd

módulo

pwd (módulo)

pwd() (método de ftplib.FTP)

pwrite() (en el módulo os)

pwritev() (en el módulo os)

Py_ABS (macro C)

Py_AddPendingCall (función C)

Py_AddPendingCall()

Py_AtExit (función C)

Py_BEGIN_ALLOW_THREADS

(macro C)

Py_BLOCK_THREADS (macro C)

Py_buffer (tipo C)

Py_buffer.buf (miembro C)

Py_buffer.format (miembro C)

Py_buffer.internal (miembro C)

Py_buffer.itemsize (miembro C)

Py_buffer.len (miembro C)

Py_buffer.ndim (miembro C)

Py_buffer.obj (miembro C)

Py_buffer.readonly (miembro C)

Py_buffer.shape (miembro C)

Py_buffer.strides (miembro C)

Py_buffer.suboffsets (miembro C)

Py_BuildValue (función C)

Py_BytesMain (función C)

Py_BytesWarningFlag (variable C)

Py_CHARMASK (macro C)

Py_CLEAR (función C)

py_compile (módulo)

PY_COMPILED (en el módulo imp)

Py_CompileString (función C)

Py_CompileString(), [1], [2]

Py_CompileStringExFlags (función C)

Py_CompileStringFlags (función C)

Py_CompileStringObject (función C)

Py_complex (tipo C)

Py_DebugFlag (variable C)

Py_DecodeLocale (función C)

Py_DECREF (función C)

Py_DECREF()

Py_DEPRECATED (macro C)

Py_DontWriteBytecodeFlag (variable C)

Py_Ellipsis (variable C)

Py_EncodeLocale (función C)

Py_END_ALLOW_THREADS

(macro C)

Py_EndInterpreter (función C)

Py_EnterRecursiveCall (función C)

Py_eval_input (variable C)

Py_Exit (función C)

Py_ExitStatusException (función C)

Py_False (variable C)

Py_FatalError (función C)

Py_FatalError()

Py_FdIsInteractive (función C)

Py_file_input (variable C)

Py_Finalize (función C)

Py_FinalizeEx (función C)

Py_FinalizeEx(), [1], [2], [3], [4]

PY_FROZEN (en el módulo imp)

Py_FrozenFlag (variable C)

Py_GenericAlias (función C)

Py_GenericAliasType (variable C)

Py_GetArgcArgv (función C)

Py_GetBuildInfo (función C)

Py_GetCompiler (función C)

Py_GetCopyright (función C)

Py_GETENV (macro C)

Py_GetExecPrefix (función C)

Py_GetExecPrefix()

Py_GetPath (función C)

Py_GetPath(), [1], [2]

Py_GetPlatform (función C)

Py_GetPrefix (función C)

Py_GetPrefix()

Py_GetProgramFullPath (función C)

Py_GetProgramFullPath()

Py_GetProgramName (función C)

Py_GetPythonHome (función C)

Py_GetVersion (función C)

Py_HashRandomizationFlag (variable C)

Py_IgnoreEnvironmentFlag (variable C)

Py_INCREF (función C)

Py_INCREF()

Py_Initialize (función C)

Py_Initialize(), [1], [2], [3]

Py_InitializeEx (función C)

Py_InitializeFromConfig (función C)

Py_InspectFlag (variable C)

Py_InteractiveFlag (variable C)

Py_IS_TYPE (función C)

Py_IsInitialized (función C)

Py_IsInitialized()

Py_IsolatedFlag (variable C)

Py_LeaveRecursiveCall (función C)

Py_LegacyWindowsFSEncodingFlag (variable C)

Py_LegacyWindowsStdioFlag (variable C)

Py_Main (función C)

Py_MAX (macro C)

Py_MEMBER_SIZE (macro C)

Py_MIN (macro C)

Py_mod_create (macro C)

Py_mod_exec (macro C)

Py_NewInterpreter (función C)

Py_None (variable C)

Py_NoSiteFlag (variable C)

Py_NotImplemented (variable C)

Py_NoUserSiteDirectory (variable C)

py_object (clase en ctypes)

Py_OptimizeFlag (variable C)

Py_PreInitialize (función C)

Py_PreInitializeFromArgs (función C)

Py_PreInitializeFromBytesArgs (función C)

Py_PRINT_RAW

PY_PYTHON

Py_QuietFlag (variable C)

Py_REFCNT (macro C)

Py_ReprEnter (función C)

Py_ReprLeave (función C)

Py_RETURN_FALSE (macro C)

Py_RETURN_NONE (macro C)

Py_RETURN_NOTIMPLEMENTED (macro C)

Py_RETURN_RICHCOMPARE (macro C)

Py_RETURN_TRUE (macro C)

Py_RunMain (función C)

Py_SET_REFCNT (función C)

Py_SET_SIZE (función C)

Py_SET_TYPE (función C)

Py_SetPath (función C)

Py_SetPath()

Py_SetProgramName (función C)

Py_SetProgramName(), [1], [2], [3]

Py_SetPythonHome (función C)

Py_SetStandardStreamEncoding (función C)

Py_single_input (variable C)

Py_SIZE (macro C)

PY_SOURCE (en el módulo imp)

Py_ssize_t (tipo C)

PY_SSIZE_T_MAX

Py_STRINGIFY (macro C)

Py_TPFLAGS_BASE_EXC_SUBCLASS (variable incorporada)

Py_TPFLAGS_BASETYPE (variable incorporada)

Py_TPFLAGS_BYTES_SUBCLASS (variable incorporada)

Py_TPFLAGS_DEFAULT (variable incorporada)

Py_TPFLAGS_DICT_SUBCLASS (variable incorporada)

Py_TPFLAGS_HAVE_FINALIZE (variable incorporada)

Py_TPFLAGS_HAVE_GC (variable incorporada)

Py_TPFLAGS_HAVE_VECTORCALL (variable incorporada)

Py_TPFLAGS_HEAPTYPE (variable incorporada)

Py_TPFLAGS_LIST_SUBCLASS (variable incorporada)

Py_TPFLAGS_LONG_SUBCLASS (variable incorporada)

Py_TPFLAGS_METHOD_DESCRIPTOR (variable incorporada)

Py_TPFLAGS_READY (variable incorporada)

Py_TPFLAGS_READYING (variable incorporada)

Py_TPFLAGS_TUPLE_SUBCLASS (variable incorporada)

Py_TPFLAGS_TYPE_SUBCLASS (variable incorporada)

Py_TPFLAGS_UNICODE_SUBCLASS (variable incorporada)

Py_tracefunc (tipo C)

Py_True (variable C)

Py_tss_NEEDS_INIT (macro C)

Py_tss_t (tipo C)

Py_TYPE (macro C)

Py_UCS1 (tipo C)

Py_UCS2 (tipo C)

Py_UCS4 (tipo C)

Py_UNBLOCK_THREADS (macro C)

Py_UnbufferedStdioFlag (variable C)

Py_UNICODE (tipo C)

Py_UNICODE_IS_HIGH_SURROGATE (macro C)

Py_UNICODE_IS_LOW_SURROGATE (macro C)

Py_UNICODE_IS_SURROGATE (macro C)

Py_UNICODE_ISALNUM (función C)

Py_UNICODE_ISALPHA (función C)

Py_UNICODE_ISDECIMAL (función C)

Py_UNICODE_ISDIGIT (función C)

Py_UNICODE_ISLINEBREAK (función C)

Py_UNICODE_ISLOWER (función C)

Py_UNICODE_ISNUMERIC (función C)

Py_UNICODE_ISPRINTABLE (función C)

Py_UNICODE_ISSPACE (función C)

Py_UNICODE_ISTITLE (función C)

Py_UNICODE_ISUPPER (función C)

Py_UNICODE_JOIN_SURROGATES (macro C)

Py_UNICODE_TODECIMAL (función C)

Py_UNICODE_TODIGIT (función C)

Py_UNICODE_TOLOWER (función C)

Py_UNICODE_TONUMERIC (función C)

Py_UNICODE_TOTITLE (función C)

Py_UNICODE_TOUPPER (función C)

Py_UNREACHABLE (macro C)

Py_UNUSED (macro C)

Py_VaBuildValue (función C)

PY_VECTORCALL_ARGUMENTS_OFFSET (macro C)

Py_VerboseFlag (variable C)

Py_VISIT (función C)

Py_XDECREF (función C)

Py_XDECREF()

Py_XINCREF (función C)

PyAnySet_Check (función C)

PyAnySet_CheckExact (función C)

PyArg_Parse (función C)

PyArg_ParseTuple (función C)

PyArg_ParseTuple()

PyArg_ParseTupleAndKeywords (función C)

PyArg_ParseTupleAndKeywords()

PyArg_UnpackTuple (función C)

PyArg_ValidateKeywordArguments (función C)

PyArg_VaParse (función C)

PyArg_VaParseTupleAndKeywords (función C)

PyASCIIObject (tipo C)

PyAsyncMethods (tipo C)

PyAsyncMethods.am_aiter (miembro C)

PyAsyncMethods.am_anext (miembro C)

PyAsyncMethods.am_await (miembro C)

PyBool_Check (función C)

PyBool_FromLong (función C)

PyBUF_ANY_CONTIGUOUS (macro C)

PyBUF_C_CONTIGUOUS (macro C)

PyBUF_CONTIG (macro C)

PyBUF_CONTIG_RO (macro C)

PyBUF_F_CONTIGUOUS (macro C)

PyBUF_FORMAT (macro C)

PyBUF_FULL (macro C)

PyBUF_FULL_RO (macro C)

PyBUF_INDIRECT (macro C)

PyBUF_ND (macro C)

PyBUF_RECORDS (macro C)

PyBUF_RECORDS_RO (macro C)

PyBUF_SIMPLE (macro C)

PyBUF_STRIDED (macro C)

PyBUF_STRIDED_RO (macro C)

PyBUF_STRIDES (macro C)

PyBUF_WRITABLE (macro C)

PyBuffer_FillContiguousStrides (función C)

PyBuffer_FillInfo (función C)

PyBuffer_FromContiguous (función C)

PyBuffer_GetPointer (función C)

PyBuffer_IsContiguous (función C)

PyBuffer_Release (función C)

PyBuffer_SizeFromFormat (función C)

PyBuffer_ToContiguous (función C)

PyBufferProcs

(tipo C)

PyBufferProcs.bf_getbuffer (miembro C)

PyBufferProcs.bf_releasebuffer (miembro C)

PyByteArray_AS_STRING (función C)

PyByteArray_AsString (función C)

PyByteArray_Check (función C)

PyByteArray_CheckExact (función C)

PyByteArray_Concat (función C)

PyByteArray_FromObject (función C)

PyByteArray_FromStringAndSize (función C)

PyByteArray_GET_SIZE (función C)

PyByteArray_Resize (función C)

PyByteArray_Size (función C)

PyByteArray_Type (variable C)

PyByteArrayObject (tipo C)

PyBytes_AS_STRING (función C)

PyBytes_AsString (función C)

PyBytes_AsStringAndSize (función C)

PyBytes_Check (función C)

PyBytes_CheckExact (función C)

PyBytes_Concat (función C)

PyBytes_ConcatAndDel (función C)

PyBytes_FromFormat (función C)

PyBytes_FromFormatV (función C)

PyBytes_FromObject (función C)

PyBytes_FromString (función C)

PyBytes_FromStringAndSize (función C)

PyBytes_GET_SIZE (función C)

PyBytes_Size (función C)

PyBytes_Type (variable C)

PyBytesObject (tipo C)

pycache_prefix (en el módulo sys)

PyCallable_Check (función C)

PyCallIter_Check (función C)

PyCallIter_New (función C)

PyCallIter_Type (variable C)

PyCapsule (tipo C)

PyCapsule_CheckExact (función C)

PyCapsule_Destructor (tipo C)

PyCapsule_GetContext (función C)

PyCapsule_GetDestructor (función C)

PyCapsule_GetName (función C)

PyCapsule_GetPointer (función C)

PyCapsule_Import (función C)

PyCapsule_IsValid (función C)

PyCapsule_New (función C)

PyCapsule_SetContext (función C)

PyCapsule_SetDestructor (función C)

PyCapsule_SetName (función C)

PyCapsule_SetPointer (función C)

PyCell_Check (función C)

PyCell_GET (función C)

PyCell_Get (función C)

PyCell_New (función C)

PyCell_SET (función C)

PyCell_Set (función C)

PyCell_Type (variable C)

PyCellObject (tipo C)

PyCF_ALLOW_TOP_LEVEL_AWAIT (en el módulo ast)

PyCF_ONLY_AST (en el módulo ast)

PyCF_TYPE_COMMENTS (en el módulo ast)

PyCFunction (tipo C)

PyCFunctionWithKeywords (tipo C)

PycInvalidationMode (clase en py_compile)

pyclbr (módulo)

PyCMethod (tipo C)

PyCode_Check (función C)

PyCode_GetNumFree (función C)

PyCode_New (función C)

PyCode_NewEmpty (función C)

PyCode_NewWithPosOnlyArgs (función C)

PyCode_Type (variable C)

PyCodec_BackslashReplaceErrors (función C)

PyCodec_Decode (función C)

PyCodec_Decoder (función C)

PyCodec_Encode (función C)

PyCodec_Encoder (función C)

PyCodec_IgnoreErrors (función C)

PyCodec_IncrementalDecoder (función C)

PyCodec_IncrementalEncoder (función C)

PyCodec_KnownEncoding (función C)

PyCodec_LookupError (función C)

PyCodec_NameReplaceErrors (función C)

PyCodec_Register (función C)

PyCodec_RegisterError (función C)

PyCodec_ReplaceErrors (función C)

PyCodec_StreamReader (función C)

PyCodec_StreamWriter (función C)

PyCodec_StrictErrors (función C)

PyCodec_XMLCharRefReplaceErrors (función C)

PyCodeObject (tipo C)

PyCompactUnicodeObject (tipo C)

PyCompileError

PyCompilerFlags (tipo C)

PyCompilerFlags.cf_feature_version (miembro C)

PyCompilerFlags.cf_flags (miembro C)

PyComplex_AsCComplex (función C)

PyComplex_Check (función C)

PyComplex_CheckExact (función C)

PyComplex_FromCComplex (función C)

PyComplex_FromDoubles (función C)

PyComplex_ImagAsDouble (función C)

PyComplex_RealAsDouble (función C)

PyComplex_Type (variable C)

PyComplexObject (tipo C)

PyConfig (tipo C)

PyConfig._use_peg_parser (miembro C)

PyConfig.argv (miembro C)

PyConfig.base_exec_prefix (miembro C)

PyConfig.base_executable (miembro C)

PyConfig.base_prefix (miembro C)

PyConfig.buffered_stdio (miembro C)

PyConfig.bytes_warning (miembro C)

PyConfig.check_hash_pycs_mode (miembro C)

PyConfig.configure_c_stdio (miembro C)

PyConfig.dev_mode (miembro C)

PyConfig.dump_refs (miembro C)

PyConfig.exec_prefix (miembro C)

PyConfig.executable (miembro C)

PyConfig.faulthandler (miembro C)

PyConfig.filesystem_encoding (miembro C)

PyConfig.filesystem_errors (miembro C)

PyConfig.hash_seed (miembro C)

PyConfig.home (miembro C)

PyConfig.import_time (miembro C)

PyConfig.inspect (miembro C)

PyConfig.install_signal_handlers (miembro C)

PyConfig.interactive (miembro C)

PyConfig.isolated (miembro C)

PyConfig.legacy_windows_stdio (miembro C)

PyConfig.malloc_stats (miembro C)

PyConfig.module_search_paths (miembro C)

PyConfig.module_search_paths_set (miembro C)

PyConfig.optimization_level (miembro C)

PyConfig.parse_argv (miembro C)

PyConfig.parser_debug (miembro C)

PyConfig.pathconfig_warnings (miembro C)

PyConfig.platlibdir (miembro C)

PyConfig.prefix (miembro C)

PyConfig.program_name (miembro C)

PyConfig.pycache_prefix (miembro C)

PyConfig.pythonpath_env (miembro C)

PyConfig.quiet (miembro C)

PyConfig.run_command (miembro C)

PyConfig.run_filename (miembro C)

PyConfig.run_module (miembro C)

PyConfig.show_ref_count (miembro C)

PyConfig.site_import (miembro C)

PyConfig.skip_source_first_line (miembro C)

PyConfig.stdio_encoding (miembro C)

PyConfig.stdio_errors (miembro C)

PyConfig.tracemalloc (miembro C)

PyConfig.use_environment (miembro C)

PyConfig.use_hash_seed (miembro C)

PyConfig.user_site_directory (miembro C)

PyConfig.verbose (miembro C)

PyConfig.warnoptions (miembro C)

PyConfig.write_bytecode (miembro C)

PyConfig.xoptions (miembro C)

PyConfig_Clear (función C)

PyConfig_InitIsolatedConfig (función C)

PyConfig_InitPythonConfig (función C)

PyConfig_Read (función C)

PyConfig_SetArgv (función C)

PyConfig_SetBytesArgv (función C)

PyConfig_SetBytesString (función C)

PyConfig_SetString (función C)

PyConfig_SetWideStringList (función C)

PyContext (tipo C)

PyContext_CheckExact (función C)

PyContext_Copy (función C)

PyContext_CopyCurrent (función C)

PyContext_Enter (función C)

PyContext_Exit (función C)

PyContext_New (función C)

PyContext_Type (variable C)

PyContextToken (tipo C)

PyContextToken_CheckExact (función C)

PyContextToken_Type (variable C)

PyContextVar (tipo C)

PyContextVar_CheckExact (función C)

PyContextVar_Get (función C)

PyContextVar_New (función C)

PyContextVar_Reset (función C)

PyContextVar_Set (función C)

PyContextVar_Type (variable C)

PyCoro_CheckExact (función C)

PyCoro_New (función C)

PyCoro_Type (variable C)

PyCoroObject (tipo C)

PyDate_Check (función C)

PyDate_CheckExact (función C)

PyDate_FromDate (función C)

PyDate_FromTimestamp (función C)

PyDateTime_Check (función C)

PyDateTime_CheckExact (función C)

PyDateTime_DATE_GET_FOLD (función C)

PyDateTime_DATE_GET_HOUR (función C)

PyDateTime_DATE_GET_MICROSECOND (función C)

PyDateTime_DATE_GET_MINUTE (función C)

PyDateTime_DATE_GET_SECOND (función C)

PyDateTime_DELTA_GET_DAYS (función C)

PyDateTime_DELTA_GET_MICROSECONDS (función C)

PyDateTime_DELTA_GET_SECONDS (función C)

PyDateTime_FromDateAndTime (función C)

PyDateTime_FromDateAndTimeAndFold (función C)

PyDateTime_FromTimestamp (función C)

PyDateTime_GET_DAY (función C)

PyDateTime_GET_MONTH (función C)

PyDateTime_GET_YEAR (función C)

PyDateTime_TIME_GET_FOLD (función C)

PyDateTime_TIME_GET_HOUR (función C)

PyDateTime_TIME_GET_MICROSECOND (función C)

PyDateTime_TIME_GET_MINUTE (función C)

PyDateTime_TIME_GET_SECOND (función C)

PyDateTime_TimeZone_UTC (variable C)

PyDelta_Check (función C)

PyDelta_CheckExact (función C)

PyDelta_FromDSU (función C)

PyDescr_IsData (función C)

PyDescr_NewClassMethod (función C)

PyDescr_NewGetSet (función C)

PyDescr_NewMember (función C)

PyDescr_NewMethod (función C)

PyDescr_NewWrapper (función C)

PyDict_Check (función C)

PyDict_CheckExact (función C)

PyDict_Clear (función C)

PyDict_Contains (función C)

PyDict_Copy (función C)

PyDict_DelItem (función C)

PyDict_DelItemString (función C)

PyDict_GetItem (función C)

PyDict_GetItemString (función C)

PyDict_GetItemWithError (función C)

PyDict_Items (función C)

PyDict_Keys (función C)

PyDict_Merge (función C)

PyDict_MergeFromSeq2 (función C)

PyDict_New (función C)

PyDict_Next (función C)

PyDict_SetDefault (función C)

PyDict_SetItem (función C)

PyDict_SetItemString (función C)

PyDict_Size (función C)

PyDict_Type (variable C)

PyDict_Update (función C)

PyDict_Values (función C)

PyDictObject (tipo C)

PyDictProxy_New (función C)

PyDLL (clase en ctypes)

pydoc (módulo)

PyDoc_STR (macro C)

PyDoc_STRVAR (macro C)

PyErr_BadArgument (función C)

PyErr_BadInternalCall (función C)

PyErr_CheckSignals (función C)

PyErr_Clear (función C)

PyErr_Clear(), [1]

PyErr_ExceptionMatches (función C)

PyErr_ExceptionMatches()

PyErr_Fetch (función C)

PyErr_Fetch()

PyErr_Format (función C)

PyErr_FormatV (función C)

PyErr_GetExcInfo (función C)

PyErr_GivenExceptionMatches (función C)

PyErr_NewException (función C)

PyErr_NewExceptionWithDoc (función C)

PyErr_NoMemory (función C)

PyErr_NormalizeException (función C)

PyErr_Occurred (función C)

PyErr_Occurred()

PyErr_Print (función C)

PyErr_PrintEx (función C)

PyErr_ResourceWarning (función C)

PyErr_Restore (función C)

PyErr_Restore()

PyErr_SetExcFromWindowsErr (función C)

PyErr_SetExcFromWindowsErrWithFilename (función C)

PyErr_SetExcFromWindowsErrWithFilenameObject (función C)

PyErr_SetExcFromWindowsErrWithFilenameObjects (función C)

PyErr_SetExcInfo (función C)

PyErr_SetFromErrno (función C)

PyErr_SetFromErrnoWithFilename (función C)

PyErr_SetFromErrnoWithFilenameObject (función C)

PyErr_SetFromErrnoWithFilenameObjects (función C)

PyErr_SetFromWindowsErr (función C)

PyErr_SetFromWindowsErrWithFilename (función C)

PyErr_SetImportError (función C)

PyErr_SetImportErrorSubclass (función C)

PyErr_SetInterrupt (función C)

PyErr_SetNone (función C)

PyErr_SetObject (función C)

PyErr_SetString (función C)

PyErr_SetString()

PyErr_SyntaxLocation (función C)

PyErr_SyntaxLocationEx (función C)

PyErr_SyntaxLocationObject (función C)

PyErr_WarnEx (función C)

PyErr_WarnExplicit (función C)

PyErr_WarnExplicitObject (función C)

PyErr_WarnFormat (función C)

PyErr_WriteUnraisable (función C)

PyEval_AcquireLock (función C)

PyEval_AcquireThread (función C)

PyEval_AcquireThread()

PyEval_EvalCode (función C)

PyEval_EvalCodeEx (función C)

PyEval_EvalFrame (función C)

PyEval_EvalFrameEx (función C)

PyEval_GetBuiltins (función C)

PyEval_GetFrame (función C)

PyEval_GetFuncDesc (función C)

PyEval_GetFuncName (función C)

PyEval_GetGlobals (función C)

PyEval_GetLocals (función C)

PyEval_InitThreads (función C)

PyEval_InitThreads()

PyEval_MergeCompilerFlags (función C)

PyEval_ReleaseLock (función C)

PyEval_ReleaseThread (función C)

PyEval_ReleaseThread()

PyEval_RestoreThread (función C)

PyEval_RestoreThread(), [1]

PyEval_SaveThread (función C)

PyEval_SaveThread(), [1]

PyEval_SetProfile (función C)

PyEval_SetTrace (función C)

PyEval_ThreadsInitialized (función C)

PyExc_ArithmeticError

PyExc_AssertionError

PyExc_AttributeError

PyExc_BaseException

PyExc_BlockingIOError

PyExc_BrokenPipeError

PyExc_BufferError

PyExc_BytesWarning

PyExc_ChildProcessError

PyExc_ConnectionAbortedError

PyExc_ConnectionError

PyExc_ConnectionRefusedError

PyExc_ConnectionResetError

PyExc_DeprecationWarning

PyExc_EnvironmentError

PyExc_EOFError

PyExc_Exception

PyExc_FileExistsError

PyExc_FileNotFoundError

PyExc_FloatingPointError

PyExc_FutureWarning

PyExc_GeneratorExit

PyExc_ImportError

PyExc_ImportWarning

PyExc_IndentationError

PyExc_IndexError

PyExc_InterruptedError

PyExc_IOError

PyExc_IsADirectoryError

PyExc_KeyboardInterrupt

PyExc_KeyError

PyExc_LookupError

PyExc_MemoryError

PyExc_ModuleNotFoundError

PyExc_NameError

PyExc_NotADirectoryError

PyExc_NotImplementedError

PyExc_OSError

PyExc_OverflowError

PyExc_PendingDeprecationWarning

PyExc_PermissionError

PyExc_ProcessLookupError

PyExc_RecursionError

PyExc_ReferenceError

PyExc_ResourceWarning

PyExc_RuntimeError

PyExc_RuntimeWarning

PyExc_StopAsyncIteration

PyExc_StopIteration

PyExc_SyntaxError

PyExc_SyntaxWarning

PyExc_SystemError

PyExc_SystemExit

PyExc_TabError

PyExc_TimeoutError

PyExc_TypeError

PyExc_UnboundLocalError

PyExc_UnicodeDecodeError

PyExc_UnicodeEncodeError

PyExc_UnicodeError

PyExc_UnicodeTranslateError

PyExc_UnicodeWarning

PyExc_UserWarning

PyExc_ValueError

PyExc_Warning

PyExc_WindowsError

PyExc_ZeroDivisionError

PyException_GetCause (función C)

PyException_GetContext (función C)

PyException_GetTraceback (función C)

PyException_SetCause (función C)

PyException_SetContext (función C)

PyException_SetTraceback (función C)

pyexpat

módulo

PyFile_FromFd (función C)

PyFile_GetLine (función C)

PyFile_SetOpenCodeHook (función C)

PyFile_WriteObject (función C)

PyFile_WriteString (función C)

PyFloat_AS_DOUBLE (función C)

PyFloat_AsDouble (función C)

PyFloat_Check (función C)

PyFloat_CheckExact (función C)

PyFloat_FromDouble (función C)

PyFloat_FromString (función C)

PyFloat_GetInfo (función C)

PyFloat_GetMax (función C)

PyFloat_GetMin (función C)

PyFloat_Type (variable C)

PyFloatObject (tipo C)

PyFrame_GetBack (función C)

PyFrame_GetCode (función C)

PyFrame_GetLineNumber (función C)

PyFrameObject (tipo C)

PyFrozenSet_Check (función C)

PyFrozenSet_CheckExact (función C)

PyFrozenSet_New (función C)

PyFrozenSet_Type (variable C)

PyFunction_Check (función C)

PyFunction_GetAnnotations (función C)

PyFunction_GetClosure (función C)

PyFunction_GetCode (función C)

PyFunction_GetDefaults (función C)

PyFunction_GetGlobals (función C)

PyFunction_GetModule (función C)

PyFunction_New (función C)

PyFunction_NewWithQualName (función C)

PyFunction_SetAnnotations (función C)

PyFunction_SetClosure (función C)

PyFunction_SetDefaults (función C)

PyFunction_Type (variable C)

PyFunctionObject (tipo C)

PYFUNCTYPE() (en el módulo ctypes)

PyGen_Check (función C)

PyGen_CheckExact (función C)

PyGen_New (función C)

PyGen_NewWithQualName (función C)

PyGen_Type (variable C)

PyGenObject (tipo C)

PyGetSetDef (tipo C)

PyGILState_Check (función C)

PyGILState_Ensure (función C)

PyGILState_GetThisThreadState (función C)

PyGILState_Release (función C)

PyImport_AddModule (función C)

PyImport_AddModuleObject (función C)

PyImport_AppendInittab (función C)

PyImport_ExecCodeModule (función C)

PyImport_ExecCodeModuleEx (función C)

PyImport_ExecCodeModuleObject (función C)

PyImport_ExecCodeModuleWithPathnames (función C)

PyImport_ExtendInittab (función C)

PyImport_FrozenModules (variable C)

PyImport_GetImporter (función C)

PyImport_GetMagicNumber (función C)

PyImport_GetMagicTag (función C)

PyImport_GetModule (función C)

PyImport_GetModuleDict (función C)

PyImport_Import (función C)

PyImport_ImportFrozenModule (función C)

PyImport_ImportFrozenModuleObject (función C)

PyImport_ImportModule (función C)

PyImport_ImportModuleEx (función C)

PyImport_ImportModuleLevel (función C)

PyImport_ImportModuleLevelObject (función C)

PyImport_ImportModuleNoBlock (función C)

PyImport_ReloadModule (función C)

PyIndex_Check (función C)

PyInit_modulename (función C)

PyInstanceMethod_Check (función C)

PyInstanceMethod_Function (función C)

PyInstanceMethod_GET_FUNCTION (función C)

PyInstanceMethod_New (función C)

PyInstanceMethod_Type (variable C)

PyInterpreterState (tipo C)

PyInterpreterState_Clear (función C)

PyInterpreterState_Delete (función C)

PyInterpreterState_Get (función C)

PyInterpreterState_GetDict (función C)

PyInterpreterState_GetID (función C)

PyInterpreterState_Head (función C)

PyInterpreterState_Main (función C)

PyInterpreterState_New (función C)

PyInterpreterState_Next (función C)

PyInterpreterState_ThreadHead (función C)

PyIter_Check (función C)

PyIter_Next (función C)

PyList_Append (función C)

PyList_AsTuple (función C)

PyList_Check (función C)

PyList_CheckExact (función C)

PyList_GET_ITEM (función C)

PyList_GET_SIZE (función C)

PyList_GetItem (función C)

PyList_GetItem()

PyList_GetSlice (función C)

PyList_Insert (función C)

PyList_New (función C)

PyList_Reverse (función C)

PyList_SET_ITEM (función C)

PyList_SetItem (función C)

PyList_SetItem()

PyList_SetSlice (función C)

PyList_Size (función C)

PyList_Sort (función C)

PyList_Type (variable C)

PyListObject (tipo C)

PyLong_AsDouble (función C)

PyLong_AsLong (función C)

PyLong_AsLongAndOverflow (función C)

PyLong_AsLongLong (función C)

PyLong_AsLongLongAndOverflow (función C)

PyLong_AsSize_t (función C)

PyLong_AsSsize_t (función C)

PyLong_AsUnsignedLong (función C)

PyLong_AsUnsignedLongLong (función C)

PyLong_AsUnsignedLongLongMask (función C)

PyLong_AsUnsignedLongMask (función C)

PyLong_AsVoidPtr (función C)

PyLong_Check (función C)

PyLong_CheckExact (función C)

PyLong_FromDouble (función C)

PyLong_FromLong (función C)

PyLong_FromLongLong (función C)

PyLong_FromSize_t (función C)

PyLong_FromSsize_t (función C)

PyLong_FromString (función C)

PyLong_FromUnicode (función C)

PyLong_FromUnicodeObject (función C)

PyLong_FromUnsignedLong (función C)

PyLong_FromUnsignedLongLong (función C)

PyLong_FromVoidPtr (función C)

PyLong_Type (variable C)

PyLongObject (tipo C)

PyMapping_Check (función C)

PyMapping_DelItem (función C)

PyMapping_DelItemString (función C)

PyMapping_GetItemString (función C)

PyMapping_HasKey (función C)

PyMapping_HasKeyString (función C)

PyMapping_Items (función C)

PyMapping_Keys (función C)

PyMapping_Length (función C)

PyMapping_SetItemString (función C)

PyMapping_Size (función C)

PyMapping_Values (función C)

PyMappingMethods (tipo C)

PyMappingMethods.mp_ass_subscript (miembro C)

PyMappingMethods.mp_length (miembro C)

PyMappingMethods.mp_subscript (miembro C)

PyMarshal_ReadLastObjectFromFile (función C)

PyMarshal_ReadLongFromFile (función C)

PyMarshal_ReadObjectFromFile (función C)

PyMarshal_ReadObjectFromString (función C)

PyMarshal_ReadShortFromFile (función C)

PyMarshal_WriteLongToFile (función C)

PyMarshal_WriteObjectToFile (función C)

PyMarshal_WriteObjectToString (función C)

PyMem_Calloc (función C)

PyMem_Del (función C)

PYMEM_DOMAIN_MEM (macro C)

PYMEM_DOMAIN_OBJ (macro C)

PYMEM_DOMAIN_RAW (macro C)

PyMem_Free (función C)

PyMem_GetAllocator (función C)

PyMem_Malloc (función C)

PyMem_New (función C)

PyMem_RawCalloc (función C)

PyMem_RawFree (función C)

PyMem_RawMalloc (función C)

PyMem_RawRealloc (función C)

PyMem_Realloc (función C)

PyMem_Resize (función C)

PyMem_SetAllocator (función C)

PyMem_SetupDebugHooks (función C)

PyMemAllocatorDomain (tipo C)

PyMemAllocatorEx (tipo C)

PyMember_GetOne (función C)

PyMember_SetOne (función C)

PyMemberDef (tipo C)

PyMemoryView_Check (función C)

PyMemoryView_FromBuffer (función C)

PyMemoryView_FromMemory (función C)

PyMemoryView_FromObject (función C)

PyMemoryView_GET_BASE (función C)

PyMemoryView_GET_BUFFER (función C)

PyMemoryView_GetContiguous (función C)

PyMethod_Check (función C)

PyMethod_Function (función C)

PyMethod_GET_FUNCTION (función C)

PyMethod_GET_SELF (función C)

PyMethod_New (función C)

PyMethod_Self (función C)

PyMethod_Type (variable C)

PyMethodDef (tipo C)

PyModule_AddFunctions (función C)

PyModule_AddIntConstant (función C)

PyModule_AddIntMacro (función C)

PyModule_AddObject (función C)

PyModule_AddStringConstant (función C)

PyModule_AddStringMacro (función C)

PyModule_AddType (función C)

PyModule_Check (función C)

PyModule_CheckExact (función C)

PyModule_Create (función C)

PyModule_Create2 (función C)

PyModule_ExecDef (función C)

PyModule_FromDefAndSpec (función C)

PyModule_FromDefAndSpec2 (función C)

PyModule_GetDef (función C)

PyModule_GetDict (función C)

PyModule_GetFilename (función C)

PyModule_GetFilenameObject (función C)

PyModule_GetName (función C)

PyModule_GetNameObject (función C)

PyModule_GetState (función C)

PyModule_New (función C)

PyModule_NewObject (función C)

PyModule_SetDocString (función C)

PyModule_Type (variable C)

PyModuleDef (tipo C)

PyModuleDef.m_base (miembro C)

PyModuleDef.m_clear (miembro C)

PyModuleDef.m_doc (miembro C)

PyModuleDef.m_free (miembro C)

PyModuleDef.m_methods (miembro C)

PyModuleDef.m_name (miembro C)

PyModuleDef.m_reload (miembro C)

PyModuleDef.m_size (miembro C)

PyModuleDef.m_slots (miembro C)

PyModuleDef.m_traverse (miembro C)

PyModuleDef_Init (función C)

PyModuleDef_Slot (tipo C)

PyModuleDef_Slot.slot (miembro C)

PyModuleDef_Slot.value (miembro C)

PyNumber_Absolute (función C)

PyNumber_Add (función C)

PyNumber_And (función C)

PyNumber_AsSsize_t (función C)

PyNumber_Check (función C)

PyNumber_Divmod (función C)

PyNumber_Float (función C)

PyNumber_FloorDivide (función C)

PyNumber_Index (función C)

PyNumber_InPlaceAdd (función C)

PyNumber_InPlaceAnd (función C)

PyNumber_InPlaceFloorDivide (función C)

PyNumber_InPlaceLshift (función C)

PyNumber_InPlaceMatrixMultiply (función C)

PyNumber_InPlaceMultiply (función C)

PyNumber_InPlaceOr (función C)

PyNumber_InPlacePower (función C)

PyNumber_InPlaceRemainder (función C)

PyNumber_InPlaceRshift (función C)

PyNumber_InPlaceSubtract (función C)

PyNumber_InPlaceTrueDivide (función C)

PyNumber_InPlaceXor (función C)

PyNumber_Invert (función C)

PyNumber_Long (función C)

PyNumber_Lshift (función C)

PyNumber_MatrixMultiply (función C)

PyNumber_Multiply (función C)

PyNumber_Negative (función C)

PyNumber_Or (función C)

PyNumber_Positive (función C)

PyNumber_Power (función C)

PyNumber_Remainder (función C)

PyNumber_Rshift (función C)

PyNumber_Subtract (función C)

PyNumber_ToBase (función C)

PyNumber_TrueDivide (función C)

PyNumber_Xor (función C)

PyNumberMethods (tipo C)

PyNumberMethods.nb_absolute (miembro C)

PyNumberMethods.nb_add (miembro C)

PyNumberMethods.nb_and (miembro C)

PyNumberMethods.nb_bool (miembro C)

PyNumberMethods.nb_divmod (miembro C)

PyNumberMethods.nb_float (miembro C)

PyNumberMethods.nb_floor_divide (miembro C)

PyNumberMethods.nb_index (miembro C)

PyNumberMethods.nb_inplace_add (miembro C)

PyNumberMethods.nb_inplace_and (miembro C)

PyNumberMethods.nb_inplace_floor_divide (miembro C)

PyNumberMethods.nb_inplace_lshift (miembro C)

PyNumberMethods.nb_inplace_matrix_multiply (miembro C)

PyNumberMethods.nb_inplace_multiply (miembro C)

PyNumberMethods.nb_inplace_or (miembro C)

PyNumberMethods.nb_inplace_power (miembro C)

PyNumberMethods.nb_inplace_remainder (miembro C)

PyNumberMethods.nb_inplace_rshift (miembro C)

PyNumberMethods.nb_inplace_subtract (miembro C)

PyNumberMethods.nb_inplace_true_divide (miembro C)

PyNumberMethods.nb_inplace_xor (miembro C)

PyNumberMethods.nb_int (miembro C)

PyNumberMethods.nb_invert (miembro C)

PyNumberMethods.nb_lshift (miembro C)

PyNumberMethods.nb_matrix_multiply (miembro C)

PyNumberMethods.nb_multiply (miembro C)

PyNumberMethods.nb_negative (miembro C)

PyNumberMethods.nb_or (miembro C)

PyNumberMethods.nb_positive (miembro C)

PyNumberMethods.nb_power (miembro C)

PyNumberMethods.nb_remainder (miembro C)

PyNumberMethods.nb_reserved (miembro C)

PyNumberMethods.nb_rshift (miembro C)

PyNumberMethods.nb_subtract (miembro C)

PyNumberMethods.nb_true_divide (miembro C)

PyNumberMethods.nb_xor (miembro C)

PyObject (tipo C)

PyObject._ob_next (miembro C)

PyObject._ob_prev (miembro C)

PyObject.ob_refcnt (miembro C)

PyObject.ob_type (miembro C)

PyObject_AsCharBuffer (función C)

PyObject_ASCII (función C)

PyObject_AsFileDescriptor (función C)

PyObject_AsReadBuffer (función C)

PyObject_AsWriteBuffer (función C)

PyObject_Bytes (función C)

PyObject_Call (función C)

PyObject_CallFunction (función C)

PyObject_CallFunctionObjArgs (función C)

PyObject_CallMethod (función C)

PyObject_CallMethodNoArgs (función C)

PyObject_CallMethodObjArgs (función C)

PyObject_CallMethodOneArg (función C)

PyObject_CallNoArgs (función C)

PyObject_CallObject (función C)

PyObject_CallObject()

PyObject_Calloc (función C)

PyObject_CallOneArg (función C)

PyObject_CheckBuffer (función C)

PyObject_CheckReadBuffer (función C)

PyObject_Del (función C)

PyObject_DelAttr (función C)

PyObject_DelAttrString (función C)

PyObject_DelItem (función C)

PyObject_Dir (función C)

PyObject_Free (función C)

PyObject_GC_Del (función C)

PyObject_GC_IsFinalized (función C)

PyObject_GC_IsTracked (función C)

PyObject_GC_New (función C)

PyObject_GC_NewVar (función C)

PyObject_GC_Resize (función C)

PyObject_GC_Track (función C)

PyObject_GC_UnTrack (función C)

PyObject_GenericGetAttr (función C)

PyObject_GenericGetDict (función C)

PyObject_GenericSetAttr (función C)

PyObject_GenericSetDict (función C)

PyObject_GetArenaAllocator (función C)

PyObject_GetAttr (función C)

PyObject_GetAttrString (función C)

PyObject_GetBuffer (función C)

PyObject_GetItem (función C)

PyObject_GetIter (función C)

PyObject_HasAttr (función C)

PyObject_HasAttrString (función C)

PyObject_Hash (función C)

PyObject_HashNotImplemented (función C)

PyObject_HEAD (macro C)

PyObject_HEAD_INIT (macro C)

PyObject_Init (función C)

PyObject_InitVar (función C)

PyObject_IS_GC (función C)

PyObject_IsInstance (función C)

PyObject_IsSubclass (función C)

PyObject_IsTrue (función C)

PyObject_Length (función C)

PyObject_LengthHint (función C)

PyObject_Malloc (función C)

PyObject_New (función C)

PyObject_NewVar (función C)

PyObject_Not (función C)

PyObject_Print (función C)

PyObject_Realloc (función C)

PyObject_Repr (función C)

PyObject_RichCompare (función C)

PyObject_RichCompareBool (función C)

PyObject_SetArenaAllocator (función C)

PyObject_SetAttr (función C)

PyObject_SetAttrString (función C)

PyObject_SetItem (función C)

PyObject_Size (función C)

PyObject_Str (función C)

PyObject_Type (función C)

PyObject_TypeCheck (función C)

PyObject_VAR_HEAD (macro C)

PyObject_Vectorcall (función C)

PyObject_VectorcallDict (función C)

PyObject_VectorcallMethod (función C)

PyObjectArenaAllocator (tipo C)

PyOS_AfterFork (función C)

PyOS_AfterFork_Child (función C)

PyOS_AfterFork_Parent (función C)

PyOS_BeforeFork (función C)

PyOS_CheckStack (función C)

PyOS_double_to_string (función C)

PyOS_FSPath (función C)

PyOS_getsig (función C)

PyOS_InputHook (variable C)

PyOS_ReadlineFunctionPointer (variable C)

PyOS_setsig (función C)

PyOS_snprintf (función C)

PyOS_stricmp (función C)

PyOS_string_to_double (función C)

PyOS_strnicmp (función C)

PyOS_vsnprintf (función C)

PyParser_SimpleParseFile (función C)

PyParser_SimpleParseFileFlags (función C)

PyParser_SimpleParseString (función C)

PyParser_SimpleParseStringFlags (función C)

PyParser_SimpleParseStringFlagsFilename (función C)

PyPI

(see Python Package Index (PyPI))

PyPreConfig (tipo C)

PyPreConfig.allocator (miembro C)

PyPreConfig.coerce_c_locale (miembro C)

PyPreConfig.coerce_c_locale_warn (miembro C)

PyPreConfig.configure_locale (miembro C)

PyPreConfig.dev_mode (miembro C)

PyPreConfig.isolated (miembro C)

PyPreConfig.legacy_windows_fs_encoding (miembro C)

PyPreConfig.parse_argv (miembro C)

PyPreConfig.use_environment (miembro C)

PyPreConfig.utf8_mode (miembro C)

PyPreConfig_InitIsolatedConfig (función C)

PyPreConfig_InitPythonConfig (función C)

PyProperty_Type (variable C)

PyRun_AnyFile (función C)

PyRun_AnyFileEx (función C)

PyRun_AnyFileExFlags (función C)

PyRun_AnyFileFlags (función C)

PyRun_File (función C)

PyRun_FileEx (función C)

PyRun_FileExFlags (función C)

PyRun_FileFlags (función C)

PyRun_InteractiveLoop (función C)

PyRun_InteractiveLoopFlags (función C)

PyRun_InteractiveOne (función C)

PyRun_InteractiveOneFlags (función C)

PyRun_SimpleFile (función C)

PyRun_SimpleFileEx (función C)

PyRun_SimpleFileExFlags (función C)

PyRun_SimpleString (función C)

PyRun_SimpleStringFlags (función C)

PyRun_String (función C)

PyRun_StringFlags (función C)

PySeqIter_Check (función C)

PySeqIter_New (función C)

PySeqIter_Type (variable C)

PySequence_Check (función C)

PySequence_Concat (función C)

PySequence_Contains (función C)

PySequence_Count (función C)

PySequence_DelItem (función C)

PySequence_DelSlice (función C)

PySequence_Fast (función C)

PySequence_Fast_GET_ITEM (función C)

PySequence_Fast_GET_SIZE (función C)

PySequence_Fast_ITEMS (función C)

PySequence_GetItem (función C)

PySequence_GetItem()

PySequence_GetSlice (función C)

PySequence_Index (función C)

PySequence_InPlaceConcat (función C)

PySequence_InPlaceRepeat (función C)

PySequence_ITEM (función C)

PySequence_Length (función C)

PySequence_List (función C)

PySequence_Repeat (función C)

PySequence_SetItem (función C)

PySequence_SetSlice (función C)

PySequence_Size (función C)

PySequence_Tuple (función C)

PySequenceMethods (tipo C)

PySequenceMethods.sq_ass_item (miembro C)

PySequenceMethods.sq_concat (miembro C)

PySequenceMethods.sq_contains (miembro C)

PySequenceMethods.sq_inplace_concat (miembro C)

PySequenceMethods.sq_inplace_repeat (miembro C)

PySequenceMethods.sq_item (miembro C)

PySequenceMethods.sq_length (miembro C)

PySequenceMethods.sq_repeat (miembro C)

PySet_Add (función C)

PySet_Check (función C)

PySet_Clear (función C)

PySet_Contains (función C)

PySet_Discard (función C)

PySet_GET_SIZE (función C)

PySet_New (función C)

PySet_Pop (función C)

PySet_Size (función C)

PySet_Type (variable C)

PySetObject (tipo C)

PySignal_SetWakeupFd (función C)

PySlice_AdjustIndices (función C)

PySlice_Check (función C)

PySlice_GetIndices (función C)

PySlice_GetIndicesEx (función C)

PySlice_New (función C)

PySlice_Type (variable C)

PySlice_Unpack (función C)

PyState_AddModule (función C)

PyState_FindModule (función C)

PyState_RemoveModule (función C)

PyStatus (tipo C)

PyStatus.err_msg (miembro C)

PyStatus.exitcode (miembro C)

PyStatus.func (miembro C)

PyStatus_Error (función C)

PyStatus_Exception (función C)

PyStatus_Exit (función C)

PyStatus_IsError (función C)

PyStatus_IsExit (función C)

PyStatus_NoMemory (función C)

PyStatus_Ok (función C)

PyStructSequence_Desc (tipo C)

PyStructSequence_Field (tipo C)

PyStructSequence_GET_ITEM (función C)

PyStructSequence_GetItem (función C)

PyStructSequence_InitType (función C)

PyStructSequence_InitType2 (función C)

PyStructSequence_New (función C)

PyStructSequence_NewType (función C)

PyStructSequence_SET_ITEM (función C)

PyStructSequence_SetItem (función C)

PyStructSequence_UnnamedField (variable C)

PySys_AddAuditHook (función C)

PySys_AddWarnOption (función C)

PySys_AddWarnOptionUnicode (función C)

PySys_AddXOption (función C)

PySys_Audit (función C)

PySys_FormatStderr (función C)

PySys_FormatStdout (función C)

PySys_GetObject (función C)

PySys_GetXOptions (función C)

PySys_ResetWarnOptions (función C)

PySys_SetArgv (función C)

PySys_SetArgv()

PySys_SetArgvEx (función C)

PySys_SetArgvEx(), [1]

PySys_SetObject (función C)

PySys_SetPath (función C)

PySys_WriteStderr (función C)

PySys_WriteStdout (función C)

Python 3000

Python Editor

Python Enhancement Proposals

PEP 1, [1], [2]

PEP 100

PEP 11, [1], [2], [3], [4], [5]

PEP 201

PEP 205, [1]

PEP 207, [1]

PEP 208

PEP 217

PEP 218, [1], [2]

PEP 227, [1], [2]

PEP 229

PEP 230

PEP 232

PEP 234

PEP 235

PEP 236, [1], [2], [3]

PEP 237, [1], [2], [3], [4], [5]

PEP 238, [1], [2], [3], [4], [5], [6]

PEP 241, [1], [2]

PEP 243

PEP 247

PEP 249, [1], [2], [3]

PEP 252, [1], [2]

PEP 253, [1], [2], [3], [4]

PEP 255, [1], [2], [3], [4], [5]

PEP 261, [1]

PEP 263, [1], [2], [3], [4], [5], [6]

PEP 264

PEP 273, [1], [2]

PEP 274

PEP 275

PEP 277

PEP 278, [1]

PEP 279

PEP 282, [1], [2], [3], [4]

PEP 285, [1]

PEP 288

PEP 289, [1], [2]

PEP 292, [1]

PEP 293

PEP 3000

PEP 301, [1]

PEP 302, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21], [22], [23], [24], [25], [26], [27], [28], [29], [30], [31], [32], [33], [34], [35], [36]

PEP 305, [1]

PEP 307, [1], [2], [3]

PEP 308, [1], [2]

PEP 309

PEP 3100

PEP 3101, [1], [2], [3], [4]

PEP 3102

PEP 3104, [1]

PEP 3105, [1], [2]

PEP 3106

PEP 3107, [1], [2], [3]

PEP 3108, [1], [2]

PEP 3109, [1]

PEP 3110, [1], [2]

PEP 3111

PEP 3112, [1]

PEP 3113

PEP 3114

PEP 3115, [1], [2], [3]

PEP 3116, [1], [2]

PEP 3118, [1], [2], [3], [4], [5], [6], [7], [8], [9]

PEP 3119, [1], [2], [3], [4], [5]

PEP 3120, [1], [2]

PEP 3121, [1]

PEP 3123

PEP 3127

PEP 3129, [1]

PEP 3131, [1], [2]

PEP 3132, [1]

PEP 3134, [1], [2]

PEP 3135, [1]

PEP 3137

PEP 3138

PEP 314, [1]

PEP 3141, [1], [2]

PEP 3144

PEP 3147, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21], [22]

PEP 3148, [1]

PEP 3149, [1], [2]

PEP 3151, [1], [2], [3], [4], [5]

PEP 3154, [1], [2], [3]

PEP 3155, [1]

PEP 3156, [1], [2], [3], [4]

PEP 318, [1], [2], [3]

PEP 322, [1]

PEP 324, [1]

PEP 325

PEP 327

PEP 328, [1], [2], [3], [4], [5], [6], [7]

PEP 331

PEP 333, [1]

PEP 3333, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15]

PEP 338, [1], [2], [3]

PEP 339

PEP 341

PEP 342, [1], [2], [3], [4], [5], [6]

PEP 343, [1], [2], [3], [4], [5], [6], [7]

PEP 347

PEP 352, [1], [2]

PEP 353, [1], [2], [3]

PEP 356

PEP 357

PEP 361

PEP 362, [1], [2], [3]

PEP 366, [1], [2], [3], [4], [5], [6]

PEP 370, [1], [2], [3]

PEP 371

PEP 372, [1]

PEP 373

PEP 378, [1], [2]

PEP 380, [1]

PEP 383, [1], [2], [3], [4], [5]

PEP 384, [1]

PEP 385

PEP 387, [1]

PEP 389, [1]

PEP 391, [1]

PEP 392

PEP 393, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12]

PEP 395

PEP 397, [1], [2], [3]

PEP 398

PEP 4

PEP 405, [1]

PEP 409

PEP 411, [1], [2], [3], [4]

PEP 412, [1]

PEP 414, [1]

PEP 418

PEP 420, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14]

PEP 421, [1], [2]

PEP 424, [1]

PEP 427

PEP 428, [1], [2]

PEP 429

PEP 432, [1], [2], [3]

PEP 434

PEP 435, [1], [2]

PEP 436, [1], [2]

PEP 441, [1]

PEP 442, [1], [2], [3], [4], [5], [6], [7], [8]

PEP 443, [1], [2]

PEP 445, [1], [2], [3]

PEP 446, [1], [2], [3]

PEP 448, [1], [2], [3], [4], [5], [6], [7]

PEP 450, [1], [2]

PEP 451, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13]

PEP 453, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]

PEP 454, [1], [2]

PEP 456, [1]

PEP 461, [1], [2]

PEP 465, [1], [2], [3]

PEP 466, [1], [2], [3]

PEP 468, [1], [2]

PEP 471, [1], [2]

PEP 475, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21], [22], [23], [24], [25], [26], [27], [28]

PEP 476

PEP 477

PEP 478

PEP 479, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11]

PEP 483, [1], [2], [3]

PEP 484, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21], [22], [23], [24], [25], [26]

PEP 485, [1], [2], [3], [4]

PEP 486, [1], [2]

PEP 487, [1], [2], [3], [4], [5], [6]

PEP 488, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15]

PEP 489, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21], [22], [23], [24], [25], [26], [27], [28], [29], [30]

PEP 492, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21], [22]

PEP 493

PEP 494

PEP 495, [1], [2], [3]

PEP 498, [1], [2], [3], [4]

PEP 5, [1]

PEP 506, [1], [2]

PEP 511

PEP 514

PEP 515, [1], [2], [3], [4]

PEP 519, [1], [2], [3], [4], [5], [6], [7]

PEP 520

PEP 523, [1], [2], [3], [4], [5], [6], [7]

PEP 524, [1], [2], [3], [4], [5]

PEP 525, [1], [2], [3], [4], [5], [6], [7]

PEP 526, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16]

PEP 528, [1], [2]

PEP 529, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11]

PEP 530, [1], [2], [3]

PEP 538, [1], [2], [3], [4], [5], [6], [7], [8]

PEP 539, [1], [2], [3]

PEP 540, [1], [2], [3], [4]

PEP 544, [1], [2], [3]

PEP 545, [1]

PEP 552, [1], [2], [3], [4], [5], [6]

PEP 553, [1]

PEP 557, [1]

PEP 560, [1], [2], [3], [4], [5], [6]

PEP 562, [1], [2], [3]

PEP 563, [1], [2], [3], [4]

PEP 564, [1], [2], [3]

PEP 565, [1]

PEP 566, [1]

PEP 567, [1], [2], [3], [4], [5], [6], [7], [8], [9]

PEP 570, [1], [2], [3]

PEP 572, [1], [2], [3], [4], [5], [6], [7]

PEP 573, [1], [2], [3]

PEP 574, [1], [2]

PEP 578, [1], [2], [3]

PEP 584, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16]

PEP 585, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21], [22], [23], [24], [25], [26], [27], [28], [29], [30], [31], [32], [33], [34], [35], [36], [37], [38], [39], [40], [41], [42], [43], [44], [45], [46]

PEP 586, [1], [2]

PEP 587, [1], [2], [3], [4]

PEP 589, [1], [2]

PEP 590, [1], [2], [3], [4], [5], [6], [7], [8], [9]

PEP 591, [1], [2], [3]

PEP 593, [1], [2], [3], [4], [5]

PEP 594, [1], [2]

PEP 594#aifc

PEP 594#asynchat

PEP 594#asyncore

PEP 594#audioop

PEP 594#cgi

PEP 594#cgitb

PEP 594#chunk

PEP 594#crypt

PEP 594#imghdr

PEP 594#mailcap

PEP 594#msilib

PEP 594#nis

PEP 594#ossaudiodev

PEP 594#pipes

PEP 594#smtpd

PEP 594#sndhdr

PEP 594#spwd

PEP 594#sunau

PEP 594#telnetlib

PEP 594#uu-and-the-uu-encoding

PEP 594#xdrlib

PEP 596

PEP 6

PEP 602

PEP 612

PEP 614, [1], [2], [3], [4]

PEP 615, [1], [2], [3]

PEP 616, [1], [2]

PEP 617, [1], [2], [3], [4], [5], [6], [7]

PEP 623, [1]

PEP 628, [1], [2]

PEP 649

PEP 7, [1], [2], [3]

PEP 706, [1]

PEP 8, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]

Python Package Index (PyPI)

PYTHON*, [1], [2], [3], [4], [5]

python_branch() (en el módulo platform)

python_build() (en el módulo platform)

python_compiler() (en el módulo platform)

PYTHON_DOM

python_implementation() (en el módulo platform)

python_is_optimized() (en el módulo test.support)

python_revision() (en el módulo platform)

python_version() (en el módulo platform)

python_version_tuple() (en el módulo platform)

PYTHONASYNCIODEBUG, [1], [2]

PYTHONBREAKPOINT, [1], [2], [3]

PYTHONCASEOK, [1], [2], [3]

PYTHONCOERCECLOCALE, [1], [2]

PYTHONDEBUG, [1]

PYTHONDEVMODE, [1]

PYTHONDOCS

PYTHONDONTWRITEBYTECODE, [1], [2], [3], [4], [5]

PYTHONDUMPREFS, [1], [2]

PYTHONFAULTHANDLER, [1], [2]

PYTHONHASHSEED, [1], [2], [3], [4], [5], [6], [7], [8]

PYTHONHOME, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16]

PYTHONINSPECT, [1], [2]

PYTHONINTMAXSTRDIGITS, [1], [2], [3], [4]

PYTHONIOENCODING, [1], [2], [3], [4], [5], [6]

PYTHONLEGACYWINDOWSFSENCODING, [1], [2]

PYTHONLEGACYWINDOWSSTDIO, [1], [2], [3]

PYTHONMALLOC, [1], [2], [3], [4], [5], [6], [7], [8]

PYTHONMALLOCSTATS, [1]

PYTHONNOUSERSITE, [1], [2]

PYTHONOLDPARSER, [1]

PYTHONOPTIMIZE, [1]

PYTHONPATH, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21], [22], [23], [24], [25]

PYTHONPLATLIBDIR

PYTHONPROFILEIMPORTTIME, [1], [2]

PYTHONPYCACHEPREFIX, [1], [2], [3]

PYTHONSHOWALLOCCOUNT

PYTHONSHOWREFCOUNT

PYTHONSTARTUP, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]

PYTHONTRACEMALLOC, [1]

PYTHONTRACEMALLOC`comienzo, configura la variable del entorno a ``25`

PYTHONTZPATH

PYTHONUNBUFFERED, [1], [2], [3]

PYTHONUSERBASE, [1], [2]

PYTHONUSERSITE

PYTHONUTF8, [1], [2], [3], [4], [5]

PYTHONVERBOSE, [1]

PYTHONWARNINGS, [1], [2], [3], [4], [5], [6], [7], [8]

Pythónico

PyThread_create_key (función C)

PyThread_delete_key (función C)

PyThread_delete_key_value (función C)

PyThread_get_key_value (función C)

PyThread_ReInitTLS (función C)

PyThread_set_key_value (función C)

PyThread_tss_alloc (función C)

PyThread_tss_create (función C)

PyThread_tss_delete (función C)

PyThread_tss_free (función C)

PyThread_tss_get (función C)

PyThread_tss_is_created (función C)

PyThread_tss_set (función C)

PyThreadState, [1]

(tipo C)

PyThreadState_Clear (función C)

PyThreadState_Delete (función C)

PyThreadState_DeleteCurrent (función C)

PyThreadState_Get (función C)

PyThreadState_GetDict (función C)

PyThreadState_GetFrame (función C)

PyThreadState_GetID (función C)

PyThreadState_GetInterpreter (función C)

PyThreadState_New (función C)

PyThreadState_Next (función C)

PyThreadState_SetAsyncExc (función C)

PyThreadState_Swap (función C)

PyTime_Check (función C)

PyTime_CheckExact (función C)

PyTime_FromTime (función C)

PyTime_FromTimeAndFold (función C)

PyTimeZone_FromOffset (función C)

PyTimeZone_FromOffsetAndName (función C)

PyTrace_C_CALL (variable C)

PyTrace_C_EXCEPTION (variable C)

PyTrace_C_RETURN (variable C)

PyTrace_CALL (variable C)

PyTrace_EXCEPTION (variable C)

PyTrace_LINE (variable C)

PyTrace_OPCODE (variable C)

PyTrace_RETURN (variable C)

PyTraceMalloc_Track (función C)

PyTraceMalloc_Untrack (función C)

PyTuple_Check (función C)

PyTuple_CheckExact (función C)

PyTuple_GET_ITEM (función C)

PyTuple_GET_SIZE (función C)

PyTuple_GetItem (función C)

PyTuple_GetSlice (función C)

PyTuple_New (función C)

PyTuple_Pack (función C)

PyTuple_SET_ITEM (función C)

PyTuple_SetItem (función C)

PyTuple_SetItem()

PyTuple_Size (función C)

PyTuple_Type (variable C)

PyTupleObject (tipo C)

PyType_Check (función C)

PyType_CheckExact (función C)

PyType_ClearCache (función C)

PyType_FromModuleAndSpec (función C)

PyType_FromSpec (función C)

PyType_FromSpecWithBases (función C)

PyType_GenericAlloc (función C)

PyType_GenericNew (función C)

PyType_GetFlags (función C)

PyType_GetModule (función C)

PyType_GetModuleState (función C)

PyType_GetSlot (función C)

PyType_HasFeature (función C)

PyType_IS_GC (función C)

PyType_IsSubtype (función C)

PyType_Modified (función C)

PyType_Ready (función C)

PyType_Slot (tipo C)

PyType_Slot.PyType_Slot.pfunc (miembro C)

PyType_Slot.PyType_Slot.slot (miembro C)

PyType_Spec (tipo C)

PyType_Spec.PyType_Spec.basicsize (miembro C)

PyType_Spec.PyType_Spec.flags (miembro C)

PyType_Spec.PyType_Spec.itemsize (miembro C)

PyType_Spec.PyType_Spec.name (miembro C)

PyType_Spec.PyType_Spec.slots (miembro C)

PyType_Type (variable C)

PyTypeObject (tipo C)

PyTypeObject.tp_alloc (miembro C)

PyTypeObject.tp_as_async (miembro C)

PyTypeObject.tp_as_buffer (miembro C)

PyTypeObject.tp_as_mapping (miembro C)

PyTypeObject.tp_as_number (miembro C)

PyTypeObject.tp_as_sequence (miembro C)

PyTypeObject.tp_base (miembro C)

PyTypeObject.tp_bases (miembro C)

PyTypeObject.tp_basicsize (miembro C)

PyTypeObject.tp_cache (miembro C)

PyTypeObject.tp_call (miembro C)

PyTypeObject.tp_clear (miembro C)

PyTypeObject.tp_dealloc (miembro C)

PyTypeObject.tp_del (miembro C)

PyTypeObject.tp_descr_get (miembro C)

PyTypeObject.tp_descr_set (miembro C)

PyTypeObject.tp_dict (miembro C)

PyTypeObject.tp_dictoffset (miembro C)

PyTypeObject.tp_doc (miembro C)

PyTypeObject.tp_finalize (miembro C)

PyTypeObject.tp_flags (miembro C)

PyTypeObject.tp_free (miembro C)

PyTypeObject.tp_getattr (miembro C)

PyTypeObject.tp_getattro (miembro C)

PyTypeObject.tp_getset (miembro C)

PyTypeObject.tp_hash (miembro C)

PyTypeObject.tp_init (miembro C)

PyTypeObject.tp_is_gc (miembro C)

PyTypeObject.tp_itemsize (miembro C)

PyTypeObject.tp_iter (miembro C)

PyTypeObject.tp_iternext (miembro C)

PyTypeObject.tp_members (miembro C)

PyTypeObject.tp_methods (miembro C)

PyTypeObject.tp_mro (miembro C)

PyTypeObject.tp_name (miembro C)

PyTypeObject.tp_new (miembro C)

PyTypeObject.tp_repr (miembro C)

PyTypeObject.tp_richcompare (miembro C)

PyTypeObject.tp_setattr (miembro C)

PyTypeObject.tp_setattro (miembro C)

PyTypeObject.tp_str (miembro C)

PyTypeObject.tp_subclasses (miembro C)

PyTypeObject.tp_traverse (miembro C)

PyTypeObject.tp_vectorcall (miembro C)

PyTypeObject.tp_vectorcall_offset (miembro C)

PyTypeObject.tp_version_tag (miembro C)

PyTypeObject.tp_weaklist (miembro C)

PyTypeObject.tp_weaklistoffset (miembro C)

PyTZInfo_Check (función C)

PyTZInfo_CheckExact (función C)

PyUnicode_1BYTE_DATA (función C)

PyUnicode_1BYTE_KIND (macro C)

PyUnicode_2BYTE_DATA (función C)

PyUnicode_2BYTE_KIND (macro C)

PyUnicode_4BYTE_DATA (función C)

PyUnicode_4BYTE_KIND (macro C)

PyUnicode_AS_DATA (función C)

PyUnicode_AS_UNICODE (función C)

PyUnicode_AsASCIIString (función C)

PyUnicode_AsCharmapString (función C)

PyUnicode_AsEncodedString (función C)

PyUnicode_AsLatin1String (función C)

PyUnicode_AsMBCSString (función C)

PyUnicode_AsRawUnicodeEscapeString (función C)

PyUnicode_AsUCS4 (función C)

PyUnicode_AsUCS4Copy (función C)

PyUnicode_AsUnicode (función C)

PyUnicode_AsUnicodeAndSize (función C)

PyUnicode_AsUnicodeCopy (función C)

PyUnicode_AsUnicodeEscapeString (función C)

PyUnicode_AsUTF16String (función C)

PyUnicode_AsUTF32String (función C)

PyUnicode_AsUTF8 (función C)

PyUnicode_AsUTF8AndSize (función C)

PyUnicode_AsUTF8String (función C)

PyUnicode_AsWideChar (función C)

PyUnicode_AsWideCharString (función C)

PyUnicode_Check (función C)

PyUnicode_CheckExact (función C)

PyUnicode_Compare (función C)

PyUnicode_CompareWithASCIIString (función C)

PyUnicode_Concat (función C)

PyUnicode_Contains (función C)

PyUnicode_CopyCharacters (función C)

PyUnicode_Count (función C)

PyUnicode_DATA (función C)

PyUnicode_Decode (función C)

PyUnicode_DecodeASCII (función C)

PyUnicode_DecodeCharmap (función C)

PyUnicode_DecodeFSDefault (función C)

PyUnicode_DecodeFSDefaultAndSize (función C)

PyUnicode_DecodeLatin1 (función C)

PyUnicode_DecodeLocale (función C)

PyUnicode_DecodeLocaleAndSize (función C)

PyUnicode_DecodeMBCS (función C)

PyUnicode_DecodeMBCSStateful (función C)

PyUnicode_DecodeRawUnicodeEscape (función C)

PyUnicode_DecodeUnicodeEscape (función C)

PyUnicode_DecodeUTF16 (función C)

PyUnicode_DecodeUTF16Stateful (función C)

PyUnicode_DecodeUTF32 (función C)

PyUnicode_DecodeUTF32Stateful (función C)

PyUnicode_DecodeUTF7 (función C)

PyUnicode_DecodeUTF7Stateful (función C)

PyUnicode_DecodeUTF8 (función C)

PyUnicode_DecodeUTF8Stateful (función C)

PyUnicode_Encode (función C)

PyUnicode_EncodeASCII (función C)

PyUnicode_EncodeCharmap (función C)

PyUnicode_EncodeCodePage (función C)

PyUnicode_EncodeFSDefault (función C)

PyUnicode_EncodeLatin1 (función C)

PyUnicode_EncodeLocale (función C)

PyUnicode_EncodeMBCS (función C)

PyUnicode_EncodeRawUnicodeEscape (función C)

PyUnicode_EncodeUnicodeEscape (función C)

PyUnicode_EncodeUTF16 (función C)

PyUnicode_EncodeUTF32 (función C)

PyUnicode_EncodeUTF7 (función C)

PyUnicode_EncodeUTF8 (función C)

PyUnicode_Fill (función C)

PyUnicode_Find (función C)

PyUnicode_FindChar (función C)

PyUnicode_Format (función C)

PyUnicode_FromEncodedObject (función C)

PyUnicode_FromFormat (función C)

PyUnicode_FromFormatV (función C)

PyUnicode_FromKindAndData (función C)

PyUnicode_FromObject (función C)

PyUnicode_FromString (función C)

PyUnicode_FromString()

PyUnicode_FromStringAndSize (función C)

PyUnicode_FromUnicode (función C)

PyUnicode_FromWideChar (función C)

PyUnicode_FSConverter (función C)

PyUnicode_FSDecoder (función C)

PyUnicode_GET_DATA_SIZE (función C)

PyUnicode_GET_LENGTH (función C)

PyUnicode_GET_SIZE (función C)

PyUnicode_GetLength (función C)

PyUnicode_GetSize (función C)

PyUnicode_InternFromString (función C)

PyUnicode_InternInPlace (función C)

PyUnicode_IsIdentifier (función C)

PyUnicode_Join (función C)

PyUnicode_KIND (función C)

PyUnicode_MAX_CHAR_VALUE (macro C)

PyUnicode_New (función C)

PyUnicode_READ (función C)

PyUnicode_READ_CHAR (función C)

PyUnicode_ReadChar (función C)

PyUnicode_READY (función C)

PyUnicode_Replace (función C)

PyUnicode_RichCompare (función C)

PyUnicode_Split (función C)

PyUnicode_Splitlines (función C)

PyUnicode_Substring (función C)

PyUnicode_Tailmatch (función C)

PyUnicode_TransformDecimalToASCII (función C)

PyUnicode_Translate (función C)

PyUnicode_TranslateCharmap (función C)

PyUnicode_Type (variable C)

PyUnicode_WCHAR_KIND (macro C)

PyUnicode_WRITE (función C)

PyUnicode_WriteChar (función C)

PyUnicodeDecodeError_Create (función C)

PyUnicodeDecodeError_GetEncoding (función C)

PyUnicodeDecodeError_GetEnd (función C)

PyUnicodeDecodeError_GetObject (función C)

PyUnicodeDecodeError_GetReason (función C)

PyUnicodeDecodeError_GetStart (función C)

PyUnicodeDecodeError_SetEnd (función C)

PyUnicodeDecodeError_SetReason (función C)

PyUnicodeDecodeError_SetStart (función C)

PyUnicodeEncodeError_Create (función C)

PyUnicodeEncodeError_GetEncoding (función C)

PyUnicodeEncodeError_GetEnd (función C)

PyUnicodeEncodeError_GetObject (función C)

PyUnicodeEncodeError_GetReason (función C)

PyUnicodeEncodeError_GetStart (función C)

PyUnicodeEncodeError_SetEnd (función C)

PyUnicodeEncodeError_SetReason (función C)

PyUnicodeEncodeError_SetStart (función C)

PyUnicodeObject (tipo C)

PyUnicodeTranslateError_Create (función C)

PyUnicodeTranslateError_GetEnd (función C)

PyUnicodeTranslateError_GetObject (función C)

PyUnicodeTranslateError_GetReason (función C)

PyUnicodeTranslateError_GetStart (función C)

PyUnicodeTranslateError_SetEnd (función C)

PyUnicodeTranslateError_SetReason (función C)

PyUnicodeTranslateError_SetStart (función C)

PyVarObject (tipo C)

PyVarObject.ob_size (miembro C)

PyVarObject_HEAD_INIT (macro C)

PyVectorcall_Call (función C)

PyVectorcall_Function (función C)

PyVectorcall_NARGS (función C)

PyWeakref_Check (función C)

PyWeakref_CheckProxy (función C)

PyWeakref_CheckRef (función C)

PyWeakref_GET_OBJECT (función C)

PyWeakref_GetObject (función C)

PyWeakref_NewProxy (función C)

PyWeakref_NewRef (función C)

PyWideStringList (tipo C)

PyWideStringList.items (miembro C)

PyWideStringList.length (miembro C)

PyWideStringList_Append (función C)

PyWideStringList_Insert (función C)

PyWrapper_New (función C)

PyZipFile (clase en zipfile)

Q

qiflush() (en el módulo curses)

QName (clase en xml.etree.ElementTree)

qsize() (método de asyncio.Queue)

(método de multiprocessing.Queue)

(método de queue.Queue)

(método de queue.SimpleQueue)

quantiles() (en el módulo statistics)

(método de statistics.NormalDist)

quantize() (método de decimal.Context)

(método de decimal.Decimal)

QueryInfoKey() (en el módulo winreg)

QueryReflectionKey() (en el módulo winreg)

QueryValue() (en el módulo winreg)

QueryValueEx() (en el módulo winreg)

queue (atributo de sched.scheduler)

Queue (clase en asyncio)

(clase en multiprocessing)

(clase en queue)

queue (módulo)

Queue() (método de multiprocessing.managers.SyncManager)

QueueEmpty

QueueFull

QueueHandler (clase en logging.handlers)

QueueListener (clase en logging.handlers)

quick_ratio() (método de difflib.SequenceMatcher)

quit (pdb command)

(variable incorporada)

quit() (método de ftplib.FTP)

(método de nntplib.NNTP)

(método de poplib.POP3)

(método de smtplib.SMTP)

(método de tkinter.filedialog.FileDialog)

quopri (módulo)

quote() (en el módulo email.utils)

(en el módulo shlex)

(en el módulo urllib.parse)

QUOTE_ALL (en el módulo csv)

quote_from_bytes() (en el módulo urllib.parse)

QUOTE_MINIMAL (en el módulo csv)

QUOTE_NONE (en el módulo csv)

QUOTE_NONNUMERIC (en el módulo csv)

quote_plus() (en el módulo urllib.parse)

quoteattr() (en el módulo xml.sax.saxutils)

quotechar (atributo de csv.Dialect)

quoted-printable

encoding

quotes (atributo de shlex.shlex)

quoting (atributo de csv.Dialect)

R

r"

raw string literal

r'

raw string literal

R_OK (en el módulo os)

radians() (en el módulo math)

(en el módulo turtle)

RadioButtonGroup (clase en msilib)

radiogroup() (método de msilib.Dialog)

radix() (método de decimal.Context)

(método de decimal.Decimal)

RADIXCHAR (en el módulo locale)

raise

sentencia, [1]

raise (2to3 fixer)

Raise (clase en ast)

raise an exception

raise_on_defect (atributo de email.policy.Policy)

raise_signal() (en el módulo signal)

RAISE_VARARGS (opcode)

raising

exception

RAND_add() (en el módulo ssl)

RAND_bytes() (en el módulo ssl)

RAND_egd() (en el módulo ssl)

RAND_pseudo_bytes() (en el módulo ssl)

RAND_status() (en el módulo ssl)

randbelow() (en el módulo secrets)

randbits() (en el módulo secrets)

randbytes() (en el módulo random)

randint() (en el módulo random)

Random (clase en random)

random (módulo)

random() (en el módulo random)

randrange() (en el módulo random)

range

función incorporada

objeto

range (clase incorporada)

RARROW (en el módulo token)

ratecv() (en el módulo audioop)

ratio() (método de difflib.SequenceMatcher)

Rational (clase en numbers)

raw (atributo de io.BufferedIOBase)

raw string

raw() (en el módulo curses)

(método de pickle.PickleBuffer)

raw_data_manager (en el módulo email.contentmanager)

raw_decode() (método de json.JSONDecoder)

raw_input (2to3 fixer)

raw_input() (método de code.InteractiveConsole)

RawArray() (en el módulo multiprocessing.sharedctypes)

RawConfigParser (clase en configparser)

RawDescriptionHelpFormatter (clase en argparse)

RawIOBase (clase en io)

RawPen (clase en turtle)

RawTextHelpFormatter (clase en argparse)

RawTurtle (clase en turtle)

RawValue() (en el módulo multiprocessing.sharedctypes)

RBRACE (en el módulo token)

rcpttos (atributo de smtpd.SMTPChannel)

re

módulo, [1]

re (atributo de re.Match)

(módulo)

read() (en el módulo os)

(método de asyncio.StreamReader)

(método de chunk.Chunk)

(método de codecs.StreamReader)

(método de configparser.ConfigParser)

(método de http.client.HTTPResponse)

(método de imaplib.IMAP4)

(método de io.BufferedIOBase)

(método de io.BufferedReader)

(método de io.RawIOBase)

(método de io.TextIOBase)

(método de mimetypes.MimeTypes)

(método de mmap.mmap)

(método de ossaudiodev.oss_audio_device)

(método de ssl.MemoryBIO)

(método de ssl.SSLSocket)

(método de urllib.robotparser.RobotFileParser)

(método de zipfile.ZipFile)

read1() (método de io.BufferedIOBase)

(método de io.BufferedReader)

(método de io.BytesIO)

read_all() (método de telnetlib.Telnet)

read_binary() (en el módulo importlib.resources)

read_byte() (método de mmap.mmap)

read_bytes() (método de importlib.abc.Traversable)

(método de pathlib.Path)

(método de zipfile.Path)

read_dict() (método de configparser.ConfigParser)

read_eager() (método de telnetlib.Telnet)

read_environ() (en el módulo wsgiref.handlers)

read_events() (método de xml.etree.ElementTree.XMLPullParser)

read_file() (método de configparser.ConfigParser)

read_history_file() (en el módulo readline)

read_init_file() (en el módulo readline)

read_lazy() (método de telnetlib.Telnet)

read_mime_types() (en el módulo mimetypes)

READ_RESTRICTED

read_sb_data() (método de telnetlib.Telnet)

read_some() (método de telnetlib.Telnet)

read_string() (método de configparser.ConfigParser)

read_text() (en el módulo importlib.resources)

(método de importlib.abc.Traversable)

(método de pathlib.Path)

(método de zipfile.Path)

read_token() (método de shlex.shlex)

read_until() (método de telnetlib.Telnet)

read_very_eager() (método de telnetlib.Telnet)

read_very_lazy() (método de telnetlib.Telnet)

read_windows_registry() (método de mimetypes.MimeTypes)

READABLE (en el módulo tkinter)

readable() (método de asyncore.dispatcher)

(método de io.IOBase)

readall() (método de io.RawIOBase)

reader() (en el módulo csv)

ReadError

readexactly() (método de asyncio.StreamReader)

readfp() (método de configparser.ConfigParser)

(método de mimetypes.MimeTypes)

readframes() (método de aifc.aifc)

(método de sunau.AU_read)

(método de wave.Wave_read)

readinto() (método de http.client.HTTPResponse)

(método de io.BufferedIOBase)

(método de io.RawIOBase)

readinto1() (método de io.BufferedIOBase)

(método de io.BytesIO)

readline (módulo)

readline() (método de asyncio.StreamReader)

(método de codecs.StreamReader)

(método de distutils.text_file.TextFile)

(método de imaplib.IMAP4)

(método de io.IOBase)

(método de io.TextIOBase)

(método de mmap.mmap)

readlines() (método de codecs.StreamReader)

(método de distutils.text_file.TextFile)

(método de io.IOBase)

readlink() (en el módulo os)

(método de pathlib.Path)

readmodule() (en el módulo pyclbr)

readmodule_ex() (en el módulo pyclbr)

READONLY

readonly (atributo de memoryview)

ReadTransport (clase en asyncio)

readuntil() (método de asyncio.StreamReader)

readv() (en el módulo os)

ready() (método de multiprocessing.pool.AsyncResult)

real (atributo de numbers.Complex)

Real (clase en numbers)

Real Media File Format

real_max_memuse (en el módulo test.support)

real_quick_ratio() (método de difflib.SequenceMatcher)

realloc()

realpath() (en el módulo os.path)

REALTIME_PRIORITY_CLASS (en el módulo subprocess)

reap_children() (en el módulo test.support)

reap_threads() (en el módulo test.support)

reason (atributo de http.client.HTTPResponse)

(atributo de ssl.SSLError)

(atributo de UnicodeError)

(atributo de urllib.error.HTTPError)

(atributo de urllib.error.URLError)

reattach() (método de tkinter.ttk.Treeview)

rebanada

rebinding

name

reccontrols() (método de ossaudiodev.oss_mixer_device)

received_data (atributo de smtpd.SMTPChannel)

received_lines (atributo de smtpd.SMTPChannel)

recent() (método de imaplib.IMAP4)

recolección de basura

reconfigure() (método de io.TextIOWrapper)

record_original_stdout() (en el módulo test.support)

records (atributo de unittest.TestCase)

rect() (en el módulo cmath)

rectangle() (en el módulo curses.textpad)

RecursionError

recursive_repr() (en el módulo reprlib)

recv() (método de asyncore.dispatcher)

(método de multiprocessing.connection.Connection)

(método de socket.socket)

recv_bytes() (método de multiprocessing.connection.Connection)

recv_bytes_into() (método de multiprocessing.connection.Connection)

recv_fds() (en el módulo socket)

recv_into() (método de socket.socket)

recvfrom() (método de socket.socket)

recvfrom_into() (método de socket.socket)

recvmsg() (método de socket.socket)

recvmsg_into() (método de socket.socket)

redirect_request() (método de urllib.request.HTTPRedirectHandler)

redirect_stderr() (en el módulo contextlib)

redirect_stdout() (en el módulo contextlib)

redisplay() (en el módulo readline)

redrawln() (método de curses.window)

redrawwin() (método de curses.window)

reduce (2to3 fixer)

reduce() (en el módulo functools)

reducer_override() (método de pickle.Pickler)

ref (clase en weakref)

refcount_test() (en el módulo test.support)

reference

attribute

reference counting

ReferenceError

ReferenceType (en el módulo weakref)

refold_source (atributo de email.policy.EmailPolicy)

refresh() (método de curses.window)

REG_BINARY (en el módulo winreg)

REG_DWORD (en el módulo winreg)

REG_DWORD_BIG_ENDIAN (en el módulo winreg)

REG_DWORD_LITTLE_ENDIAN (en el módulo winreg)

REG_EXPAND_SZ (en el módulo winreg)

REG_FULL_RESOURCE_DESCRIPTOR (en el módulo winreg)

REG_LINK (en el módulo winreg)

REG_MULTI_SZ (en el módulo winreg)

REG_NONE (en el módulo winreg)

REG_QWORD (en el módulo winreg)

REG_QWORD_LITTLE_ENDIAN (en el módulo winreg)

REG_RESOURCE_LIST (en el módulo winreg)

REG_RESOURCE_REQUIREMENTS_LIST (en el módulo winreg)

REG_SZ (en el módulo winreg)

register() (en el módulo atexit)

(en el módulo codecs)

(en el módulo faulthandler)

(en el módulo webbrowser)

(método de abc.ABCMeta)

(método de multiprocessing.managers.BaseManager)

(método de select.devpoll)

(método de select.epoll)

(método de select.poll)

(método de selectors.BaseSelector)

register_adapter() (en el módulo sqlite3)

register_archive_format() (en el módulo shutil)

register_at_fork() (en el módulo os)

register_converter() (en el módulo sqlite3)

register_defect() (método de email.policy.Policy)

register_dialect() (en el módulo csv)

register_error() (en el módulo codecs)

register_function() (método de xmlrpc.server.CGIXMLRPCRequestHandler)

(método de xmlrpc.server.SimpleXMLRPCServer)

register_instance() (método de xmlrpc.server.CGIXMLRPCRequestHandler)

(método de xmlrpc.server.SimpleXMLRPCServer)

register_introspection_functions() (método de xmlrpc.server.CGIXMLRPCRequestHandler)

(método de xmlrpc.server.SimpleXMLRPCServer)

register_multicall_functions() (método de xmlrpc.server.CGIXMLRPCRequestHandler)

(método de xmlrpc.server.SimpleXMLRPCServer)

register_namespace() (en el módulo xml.etree.ElementTree)

register_optionflag() (en el módulo doctest)

register_shape() (en el módulo turtle)

register_unpack_format() (en el módulo shutil)

registerDOMImplementation() (en el módulo xml.dom)

registerResult() (en el módulo unittest)

regular

package

relative

import

URL

relative_to() (método de pathlib.PurePath)

release() (en el módulo platform)

(método de _thread.lock)

(método de asyncio.Condition)

(método de asyncio.Lock)

(método de asyncio.Semaphore)

(método de logging.Handler)

(método de memoryview)

(método de multiprocessing.Lock)

(método de multiprocessing.RLock)

(método de pickle.PickleBuffer)

(método de threading.Condition)

(método de threading.Lock)

(método de threading.RLock)

(método de threading.Semaphore)

release_lock() (en el módulo imp)

releasebufferproc (tipo C)

reload (2to3 fixer)

reload() (en el módulo imp)

(en el módulo importlib)

relpath() (en el módulo os.path)

remainder() (en el módulo math)

(método de decimal.Context)

remainder_near() (método de decimal.Context)

(método de decimal.Decimal)

RemoteDisconnected

remove() (en el módulo os)

(método de array.array)

(método de collections.deque)

(método de frozenset)

(método de mailbox.Mailbox)

(método de mailbox.MH)

(método de xml.etree.ElementTree.Element)

(sequence method)

remove_child_handler() (método de asyncio.AbstractChildWatcher)

remove_done_callback() (método de asyncio.Future)

(método de asyncio.Task)

remove_flag() (método de mailbox.MaildirMessage)

(método de mailbox.mboxMessage)

(método de mailbox.MMDFMessage)

remove_folder() (método de mailbox.Maildir)

(método de mailbox.MH)

remove_header() (método de urllib.request.Request)

remove_history_item() (en el módulo readline)

remove_label() (método de mailbox.BabylMessage)

remove_option() (método de configparser.ConfigParser)

(método de optparse.OptionParser)

remove_pyc() (método de msilib.Directory)

remove_reader() (método de asyncio.loop)

remove_section() (método de configparser.ConfigParser)

remove_sequence() (método de mailbox.MHMessage)

remove_signal_handler() (método de asyncio.loop)

remove_tree() (en el módulo distutils.dir_util)

remove_writer() (método de asyncio.loop)

removeAttribute() (método de xml.dom.Element)

removeAttributeNode() (método de xml.dom.Element)

removeAttributeNS() (método de xml.dom.Element)

removeChild() (método de xml.dom.Node)

removedirs() (en el módulo os)

removeFilter() (método de logging.Handler)

(método de logging.Logger)

removeHandler() (en el módulo unittest)

(método de logging.Logger)

removeprefix() (método de bytearray)

(método de bytes)

(método de str)

removeResult() (en el módulo unittest)

removesuffix() (método de bytearray)

(método de bytes)

(método de str)

removexattr() (en el módulo os)

rename() (en el módulo os)

(método de ftplib.FTP)

(método de imaplib.IMAP4)

(método de pathlib.Path)

renames (2to3 fixer)

renames() (en el módulo os)

reopenIfNeeded() (método de logging.handlers.WatchedFileHandler)

reorganize() (método de dbm.gnu.gdbm)

repeat() (en el módulo itertools)

(en el módulo timeit)

(método de timeit.Timer)

repetition

operation

replace

error handler's name

replace() (en el módulo dataclasses)

(en el módulo os)

(método de bytearray)

(método de bytes)

(método de curses.panel.Panel)

(método de datetime.date)

(método de datetime.datetime)

(método de datetime.time)

(método de inspect.Parameter)

(método de inspect.Signature)

(método de pathlib.Path)

(método de str)

(método de types.CodeType)

replace_errors() (en el módulo codecs)

replace_header() (método de email.message.EmailMessage)

(método de email.message.Message)

replace_history_item() (en el módulo readline)

replace_whitespace (atributo de textwrap.TextWrapper)

replaceChild() (método de xml.dom.Node)

ReplacePackage() (en el módulo modulefinder)

report() (método de filecmp.dircmp)

(método de modulefinder.ModuleFinder)

REPORT_CDIFF (en el módulo doctest)

report_failure() (método de doctest.DocTestRunner)

report_full_closure() (método de filecmp.dircmp)

REPORT_NDIFF (en el módulo doctest)

REPORT_ONLY_FIRST_FAILURE (en el módulo doctest)

report_partial_closure() (método de filecmp.dircmp)

report_start() (método de doctest.DocTestRunner)

report_success() (método de doctest.DocTestRunner)

REPORT_UDIFF (en el módulo doctest)

report_unexpected_exception() (método de doctest.DocTestRunner)

REPORTING_FLAGS (en el módulo doctest)

repr

función incorporada, [1], [2], [3]

repr (2to3 fixer)

Repr (clase en reprlib)

repr() (built-in function)

__repr__() (object method)

repr() (en el módulo reprlib)

(función incorporada)

(método de reprlib.Repr)

repr1() (método de reprlib.Repr)

representation

integer

reprfunc (tipo C)

reprlib (módulo)

Request (clase en urllib.request)

request() (método de http.client.HTTPConnection)

request_queue_size (atributo de socketserver.BaseServer)

request_rate() (método de urllib.robotparser.RobotFileParser)

request_uri() (en el módulo wsgiref.util)

request_version (atributo de http.server.BaseHTTPRequestHandler)

RequestHandlerClass (atributo de socketserver.BaseServer)

requestline (atributo de http.server.BaseHTTPRequestHandler)

requires() (en el módulo test.support)

requires_bz2() (en el módulo test.support)

requires_docstrings() (en el módulo test.support)

requires_freebsd_version() (en el módulo test.support)

requires_gzip() (en el módulo test.support)

requires_IEEE_754() (en el módulo test.support)

requires_linux_version() (en el módulo test.support)

requires_lzma() (en el módulo test.support)

requires_mac_version() (en el módulo test.support)

requires_resource() (en el módulo test.support)

requires_zlib() (en el módulo test.support)

RERAISE (opcode)

reserved (atributo de zipfile.ZipInfo)

reserved word

RESERVED_FUTURE (en el módulo uuid)

RESERVED_MICROSOFT (en el módulo uuid)

RESERVED_NCS (en el módulo uuid)

reset() (en el módulo turtle)

(método de bdb.Bdb)

(método de codecs.IncrementalDecoder)

(método de codecs.IncrementalEncoder)

(método de codecs.StreamReader)

(método de codecs.StreamWriter)

(método de contextvars.ContextVar)

(método de html.parser.HTMLParser)

(método de ossaudiodev.oss_audio_device)

(método de pipes.Template)

(método de threading.Barrier)

(método de xdrlib.Packer)

(método de xdrlib.Unpacker)

(método de xml.dom.pulldom.DOMEventStream)

(método de xml.sax.xmlreader.IncrementalParser)

reset_mock() (método de unittest.mock.AsyncMock)

(método de unittest.mock.Mock)

reset_peak() (en el módulo tracemalloc)

reset_prog_mode() (en el módulo curses)

reset_shell_mode() (en el módulo curses)

reset_tzpath() (en el módulo zoneinfo)

resetbuffer() (método de code.InteractiveConsole)

resetlocale() (en el módulo locale)

resetscreen() (en el módulo turtle)

resetty() (en el módulo curses)

resetwarnings() (en el módulo warnings)

resize() (en el módulo ctypes)

(método de curses.window)

(método de mmap.mmap)

resize_term() (en el módulo curses)

resizemode() (en el módulo turtle)

resizeterm() (en el módulo curses)

resolution (atributo de datetime.date)

(atributo de datetime.datetime)

(atributo de datetime.time)

(atributo de datetime.timedelta)

resolve() (método de pathlib.Path)

resolve_bases() (en el módulo types)

resolve_name() (en el módulo importlib.util)

(en el módulo pkgutil)

resolveEntity() (método de xml.sax.handler.EntityResolver)

Resource (en el módulo importlib.resources)

resource (módulo)

resource_path() (método de importlib.abc.ResourceReader)

ResourceDenied

ResourceLoader (clase en importlib.abc)

ResourceReader (clase en importlib.abc)

ResourceWarning

response (atributo de nntplib.NNTPError)

response() (método de imaplib.IMAP4)

ResponseNotReady

responses (atributo de http.server.BaseHTTPRequestHandler)

(en el módulo http.client)

restart (pdb command)

restore() (en el módulo difflib)

RESTRICTED

restricted

execution

restype (atributo de ctypes._FuncPtr)

result() (método de asyncio.Future)

(método de asyncio.Task)

(método de concurrent.futures.Future)

results() (método de trace.Trace)

resume_reading() (método de asyncio.ReadTransport)

resume_writing() (método de asyncio.BaseProtocol)

retr() (método de poplib.POP3)

retrbinary() (método de ftplib.FTP)

retrieve() (método de urllib.request.URLopener)

retrlines() (método de ftplib.FTP)

retrollamada

return

sentencia, [1], [2]

Return (clase en ast)

return (pdb command)

return_annotation (atributo de inspect.Signature)

return_ok() (método de http.cookiejar.CookiePolicy)

return_value (atributo de unittest.mock.Mock)

RETURN_VALUE (opcode)

returncode (atributo de asyncio.subprocess.Process)

(atributo de subprocess.CalledProcessError)

(atributo de subprocess.CompletedProcess)

(atributo de subprocess.Popen)

retval (pdb command)

reverse() (en el módulo audioop)

(método de array.array)

(método de collections.deque)

(sequence method)

reverse_order() (método de pstats.Stats)

reverse_pointer (atributo de ipaddress.IPv4Address)

(atributo de ipaddress.IPv6Address)

reversed() (función incorporada)

Reversible (clase en collections.abc)

(clase en typing)

revert() (método de http.cookiejar.FileCookieJar)

rewind() (método de aifc.aifc)

(método de sunau.AU_read)

(método de wave.Wave_read)

RFC

RFC 1014, [1]

RFC 1123

RFC 1321

RFC 1422, [1]

RFC 1521, [1], [2]

RFC 1522, [1]

RFC 1524, [1]

RFC 1730

RFC 1738

RFC 1750

RFC 1766, [1]

RFC 1808, [1], [2]

RFC 1832, [1]

RFC 1869, [1]

RFC 1870, [1], [2]

RFC 1939, [1]

RFC 2033

RFC 2045, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13]

RFC 2045#section-6.8

RFC 2046, [1], [2]

RFC 2047, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12]

RFC 2060

RFC 2068

RFC 2104, [1]

RFC 2109, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14]

RFC 2183, [1], [2]

RFC 2231, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14]

RFC 2295

RFC 2324

RFC 2342, [1]

RFC 2368

RFC 2373, [1], [2]

RFC 2396, [1], [2], [3], [4]

RFC 2397

RFC 2449

RFC 2487

RFC 2518

RFC 2595, [1]

RFC 2616, [1], [2], [3], [4], [5], [6], [7], [8], [9]

RFC 2640, [1], [2], [3], [4]

RFC 2732, [1], [2]

RFC 2774

RFC 2818, [1]

RFC 2821

RFC 2822, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18]

RFC 2964

RFC 2965, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18]

RFC 2980, [1]

RFC 3056

RFC 3171

RFC 3207

RFC 3229

RFC 3280

RFC 3330

RFC 3339

RFC 3454, [1]

RFC 3490, [1], [2], [3]

RFC 3490#section-3.1

RFC 3492, [1]

RFC 3493

RFC 3501

RFC 3542, [1]

RFC 3548, [1], [2], [3], [4], [5]

RFC 3659

RFC 3879

RFC 3927

RFC 3977, [1], [2], [3], [4]

RFC 3986, [1], [2], [3], [4], [5], [6], [7], [8], [9]

RFC 4007, [1]

RFC 4086

RFC 4122, [1], [2], [3], [4], [5], [6], [7], [8]

RFC 4180

RFC 4193

RFC 4217

RFC 4291

RFC 4380

RFC 4627, [1]

RFC 4642

RFC 4918, [1], [2], [3], [4]

RFC 4954

RFC 5161, [1]

RFC 5246, [1]

RFC 5280, [1], [2], [3], [4]

RFC 5321, [1], [2], [3], [4]

RFC 5322, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21], [22], [23]

RFC 5424, [1], [2], [3]

RFC 5424#section-6

RFC 5735

RFC 5842, [1]

RFC 5891

RFC 5895

RFC 5929

RFC 6066, [1], [2]

RFC 6125, [1]

RFC 6152, [1]

RFC 6531, [1], [2], [3], [4], [5], [6], [7], [8]

RFC 6532, [1], [2], [3], [4]

RFC 6585, [1], [2], [3]

RFC 6855, [1], [2], [3]

RFC 6856, [1]

RFC 7159, [1], [2]

RFC 7230, [1]

RFC 7231, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21], [22], [23], [24], [25], [26], [27], [28], [29], [30], [31], [32], [33], [34]

RFC 7232, [1]

RFC 7233, [1]

RFC 7235, [1]

RFC 7238

RFC 7301, [1], [2]

RFC 7525

RFC 7540

RFC 7693

RFC 7725

RFC 7914

RFC 821, [1]

RFC 822, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11]

RFC 8297

RFC 8305, [1]

RFC 8470

RFC 854, [1]

RFC 959

RFC 977

rfc2109 (atributo de http.cookiejar.Cookie)

rfc2109_as_netscape (atributo de http.cookiejar.DefaultCookiePolicy)

rfc2965 (atributo de http.cookiejar.CookiePolicy)

rfc822_escape() (en el módulo distutils.util)

RFC_4122 (en el módulo uuid)

rfile (atributo de http.server.BaseHTTPRequestHandler)

rfind() (método de bytearray)

(método de bytes)

(método de mmap.mmap)

(método de str)

rgb_to_hls() (en el módulo colorsys)

rgb_to_hsv() (en el módulo colorsys)

rgb_to_yiq() (en el módulo colorsys)

rglob() (método de pathlib.Path)

richcmpfunc (tipo C)

right (atributo de filecmp.dircmp)

right() (en el módulo turtle)

right_list (atributo de filecmp.dircmp)

right_only (atributo de filecmp.dircmp)

RIGHTSHIFT (en el módulo token)

RIGHTSHIFTEQUAL (en el módulo token)

rindex() (método de bytearray)

(método de bytes)

(método de str)

rjust() (método de bytearray)

(método de bytes)

(método de str)

rlcompleter (módulo)

rlecode_hqx() (en el módulo binascii)

rledecode_hqx() (en el módulo binascii)

RLIM_INFINITY (en el módulo resource)

RLIMIT_AS (en el módulo resource)

RLIMIT_CORE (en el módulo resource)

RLIMIT_CPU (en el módulo resource)

RLIMIT_DATA (en el módulo resource)

RLIMIT_FSIZE (en el módulo resource)

RLIMIT_MEMLOCK (en el módulo resource)

RLIMIT_MSGQUEUE (en el módulo resource)

RLIMIT_NICE (en el módulo resource)

RLIMIT_NOFILE (en el módulo resource)

RLIMIT_NPROC (en el módulo resource)

RLIMIT_NPTS (en el módulo resource)

RLIMIT_OFILE (en el módulo resource)

RLIMIT_RSS (en el módulo resource)

RLIMIT_RTPRIO (en el módulo resource)

RLIMIT_RTTIME (en el módulo resource)

RLIMIT_SBSIZE (en el módulo resource)

RLIMIT_SIGPENDING (en el módulo resource)

RLIMIT_STACK (en el módulo resource)

RLIMIT_SWAP (en el módulo resource)

RLIMIT_VMEM (en el módulo resource)

RLock (clase en multiprocessing)

(clase en threading)

RLock() (método de multiprocessing.managers.SyncManager)

rmd() (método de ftplib.FTP)

rmdir() (en el módulo os)

(en el módulo test.support)

(método de pathlib.Path)

RMFF

rms() (en el módulo audioop)

rmtree() (en el módulo shutil)

(en el módulo test.support)

RobotFileParser (clase en urllib.robotparser)

robots.txt

rollback() (método de sqlite3.Connection)

ROMAN (en el módulo tkinter.font)

ROT_FOUR (opcode)

ROT_THREE (opcode)

ROT_TWO (opcode)

rotate() (método de collections.deque)

(método de decimal.Context)

(método de decimal.Decimal)

(método de logging.handlers.BaseRotatingHandler)

RotatingFileHandler (clase en logging.handlers)

rotation_filename() (método de logging.handlers.BaseRotatingHandler)

rotator (atributo de logging.handlers.BaseRotatingHandler)

round

función incorporada

round() (función incorporada)

ROUND_05UP (en el módulo decimal)

ROUND_CEILING (en el módulo decimal)

ROUND_DOWN (en el módulo decimal)

ROUND_FLOOR (en el módulo decimal)

ROUND_HALF_DOWN (en el módulo decimal)

ROUND_HALF_EVEN (en el módulo decimal)

ROUND_HALF_UP (en el módulo decimal)

ROUND_UP (en el módulo decimal)

Rounded (clase en decimal)

Row (clase en sqlite3)

row_factory (atributo de sqlite3.Connection)

rowcount (atributo de sqlite3.Cursor)

RPAR (en el módulo token)

rpartition() (método de bytearray)

(método de bytes)

(método de str)

rpc_paths (atributo de xmlrpc.server.SimpleXMLRPCRequestHandler)

rpop() (método de poplib.POP3)

rset() (método de poplib.POP3)

RShift (clase en ast)

rshift() (en el módulo operator)

rsplit() (método de bytearray)

(método de bytes)

(método de str)

RSQB (en el módulo token)

rstrip() (método de bytearray)

(método de bytes)

(método de str)

rt() (en el módulo turtle)

RTLD_DEEPBIND (en el módulo os)

RTLD_GLOBAL (en el módulo os)

RTLD_LAZY (en el módulo os)

RTLD_LOCAL (en el módulo os)

RTLD_NODELETE (en el módulo os)

RTLD_NOLOAD (en el módulo os)

RTLD_NOW (en el módulo os)

ruler (atributo de cmd.Cmd)

run (pdb command)

Run script

run() (en el módulo asyncio)

(en el módulo pdb)

(en el módulo profile)

(en el módulo subprocess)

(método de bdb.Bdb)

(método de contextvars.Context)

(método de distutils.cmd.Command)

(método de doctest.DocTestRunner)

(método de multiprocessing.Process)

(método de pdb.Pdb)

(método de profile.Profile)

(método de sched.scheduler)

(método de test.support.BasicTestRunner)

(método de threading.Thread)

(método de trace.Trace)

(método de unittest.IsolatedAsyncioTestCase)

(método de unittest.TestCase)

(método de unittest.TestSuite)

(método de unittest.TextTestRunner)

(método de wsgiref.handlers.BaseHandler)

run_coroutine_threadsafe() (en el módulo asyncio)

run_docstring_examples() (en el módulo doctest)

run_doctest() (en el módulo test.support)

run_forever() (método de asyncio.loop)

run_in_executor() (método de asyncio.loop)

run_in_subinterp() (en el módulo test.support)

run_module() (en el módulo runpy)

run_path() (en el módulo runpy)

run_python_until_end() (en el módulo test.support.script_helper)

run_script() (método de modulefinder.ModuleFinder)

run_setup() (en el módulo distutils.core)

run_unittest() (en el módulo test.support)

run_until_complete() (método de asyncio.loop)

run_with_locale() (en el módulo test.support)

run_with_tz() (en el módulo test.support)

runcall() (en el módulo pdb)

(método de bdb.Bdb)

(método de pdb.Pdb)

(método de profile.Profile)

runcode() (método de code.InteractiveInterpreter)

runctx() (en el módulo profile)

(método de bdb.Bdb)

(método de profile.Profile)

(método de trace.Trace)

runeval() (en el módulo pdb)

(método de bdb.Bdb)

(método de pdb.Pdb)

runfunc() (método de trace.Trace)

running() (método de concurrent.futures.Future)

runpy (módulo)

runsource() (método de code.InteractiveInterpreter)

runtime_checkable() (en el módulo typing)

runtime_library_dir_option() (método de distutils.ccompiler.CCompiler)

RuntimeError

RuntimeWarning

RUSAGE_BOTH (en el módulo resource)

RUSAGE_CHILDREN (en el módulo resource)

RUSAGE_SELF (en el módulo resource)

RUSAGE_THREAD (en el módulo resource)

ruta de importación

RWF_DSYNC (en el módulo os)

RWF_HIPRI (en el módulo os)

RWF_NOWAIT (en el módulo os)

RWF_SYNC (en el módulo os)

S

S (en el módulo re)

S_ENFMT (en el módulo stat)

S_IEXEC (en el módulo stat)

S_IFBLK (en el módulo stat)

S_IFCHR (en el módulo stat)

S_IFDIR (en el módulo stat)

S_IFDOOR (en el módulo stat)

S_IFIFO (en el módulo stat)

S_IFLNK (en el módulo stat)

S_IFMT() (en el módulo stat)

S_IFPORT (en el módulo stat)

S_IFREG (en el módulo stat)

S_IFSOCK (en el módulo stat)

S_IFWHT (en el módulo stat)

S_IMODE() (en el módulo stat)

S_IREAD (en el módulo stat)

S_IRGRP (en el módulo stat)

S_IROTH (en el módulo stat)

S_IRUSR (en el módulo stat)

S_IRWXG (en el módulo stat)

S_IRWXO (en el módulo stat)

S_IRWXU (en el módulo stat)

S_ISBLK() (en el módulo stat)

S_ISCHR() (en el módulo stat)

S_ISDIR() (en el módulo stat)

S_ISDOOR() (en el módulo stat)

S_ISFIFO() (en el módulo stat)

S_ISGID (en el módulo stat)

S_ISLNK() (en el módulo stat)

S_ISPORT() (en el módulo stat)

S_ISREG() (en el módulo stat)

S_ISSOCK() (en el módulo stat)

S_ISUID (en el módulo stat)

S_ISVTX (en el módulo stat)

S_ISWHT() (en el módulo stat)

S_IWGRP (en el módulo stat)

S_IWOTH (en el módulo stat)

S_IWRITE (en el módulo stat)

S_IWUSR (en el módulo stat)

S_IXGRP (en el módulo stat)

S_IXOTH (en el módulo stat)

S_IXUSR (en el módulo stat)

safe (atributo de uuid.SafeUUID)

safe_substitute() (método de string.Template)

SafeChildWatcher (clase en asyncio)

saferepr() (en el módulo pprint)

SafeUUID (clase en uuid)

saltos de líneas universales

same_files (atributo de filecmp.dircmp)

same_quantum() (método de decimal.Context)

(método de decimal.Decimal)

samefile() (en el módulo os.path)

(método de pathlib.Path)

SameFileError

sameopenfile() (en el módulo os.path)

samestat() (en el módulo os.path)

sample() (en el módulo random)

samples() (método de statistics.NormalDist)

save() (método de http.cookiejar.FileCookieJar)

SaveAs (clase en tkinter.filedialog)

SAVEDCWD (en el módulo test.support)

SaveFileDialog (clase en tkinter.filedialog)

SaveKey() (en el módulo winreg)

SaveSignals (clase en test.support)

savetty() (en el módulo curses)

SAX2DOM (clase en xml.dom.pulldom)

SAXException

SAXNotRecognizedException

SAXNotSupportedException

SAXParseException

scaleb() (método de decimal.Context)

(método de decimal.Decimal)

scandir() (en el módulo os)

scanf()

sched (módulo)

SCHED_BATCH (en el módulo os)

SCHED_FIFO (en el módulo os)

sched_get_priority_max() (en el módulo os)

sched_get_priority_min() (en el módulo os)

sched_getaffinity() (en el módulo os)

sched_getparam() (en el módulo os)

sched_getscheduler() (en el módulo os)

SCHED_IDLE (en el módulo os)

SCHED_OTHER (en el módulo os)

sched_param (clase en os)

sched_priority (atributo de os.sched_param)

SCHED_RESET_ON_FORK (en el módulo os)

SCHED_RR (en el módulo os)

sched_rr_get_interval() (en el módulo os)

sched_setaffinity() (en el módulo os)

sched_setparam() (en el módulo os)

sched_setscheduler() (en el módulo os)

SCHED_SPORADIC (en el módulo os)

sched_yield() (en el módulo os)

scheduler (clase en sched)

schema (en el módulo msilib)

scope, [1]

scope_id (atributo de ipaddress.IPv6Address)

Screen (clase en turtle)

screensize() (en el módulo turtle)

script_from_examples() (en el módulo doctest)

scroll() (método de curses.window)

ScrolledCanvas (clase en turtle)

ScrolledText (clase en tkinter.scrolledtext)

scrollok() (método de curses.window)

scrypt() (en el módulo hashlib)

sdterr

stdin stdout

seal() (en el módulo unittest.mock)

search

path, module, [1], [2], [3], [4], [5], [6], [7]

search() (en el módulo re)

(método de imaplib.IMAP4)

(método de re.Pattern)

second (atributo de datetime.datetime)

(atributo de datetime.time)

seconds since the epoch

secrets (módulo)

SECTCRE (atributo de configparser.ConfigParser)

sections() (método de configparser.ConfigParser)

secuencia

secure (atributo de http.cookiejar.Cookie)

secure hash algorithm, SHA1, SHA224, SHA256, SHA384, SHA512

Secure Sockets Layer

security

CGI

http.server

security considerations

see() (método de tkinter.ttk.Treeview)

seed() (en el módulo random)

seek() (método de chunk.Chunk)

(método de io.IOBase)

(método de io.TextIOBase)

(método de mmap.mmap)

SEEK_CUR (en el módulo os)

SEEK_END (en el módulo os)

SEEK_SET (en el módulo os)

seekable() (método de io.IOBase)

seen_greeting (atributo de smtpd.SMTPChannel)

Select (clase en tkinter.tix)

select (módulo)

select() (en el módulo select)

(método de imaplib.IMAP4)

(método de selectors.BaseSelector)

(método de tkinter.ttk.Notebook)

selected_alpn_protocol() (método de ssl.SSLSocket)

selected_npn_protocol() (método de ssl.SSLSocket)

selection() (método de tkinter.ttk.Treeview)

selection_add() (método de tkinter.ttk.Treeview)

selection_remove() (método de tkinter.ttk.Treeview)

selection_set() (método de tkinter.ttk.Treeview)

selection_toggle() (método de tkinter.ttk.Treeview)

selector (atributo de urllib.request.Request)

SelectorEventLoop (clase en asyncio)

SelectorKey (clase en selectors)

selectors (módulo)

SelectSelector (clase en selectors)

Semaphore (clase en asyncio)

(clase en multiprocessing)

(clase en threading)

Semaphore() (método de multiprocessing.managers.SyncManager)

semaphores, binary

SEMI (en el módulo token)

send() (método de asyncore.dispatcher)

(método de coroutine)

(método de generator)

(método de http.client.HTTPConnection)

(método de imaplib.IMAP4)

(método de logging.handlers.DatagramHandler)

(método de logging.handlers.SocketHandler)

(método de multiprocessing.connection.Connection)

(método de socket.socket)

send_bytes() (método de multiprocessing.connection.Connection)

send_error() (método de http.server.BaseHTTPRequestHandler)

send_fds() (en el módulo socket)

send_flowing_data() (método de formatter.writer)

send_header() (método de http.server.BaseHTTPRequestHandler)

send_hor_rule() (método de formatter.writer)

send_label_data() (método de formatter.writer)

send_line_break() (método de formatter.writer)

send_literal_data() (método de formatter.writer)

send_message() (método de smtplib.SMTP)

send_paragraph() (método de formatter.writer)

send_response() (método de http.server.BaseHTTPRequestHandler)

send_response_only() (método de http.server.BaseHTTPRequestHandler)

send_signal() (método de asyncio.subprocess.Process)

(método de asyncio.SubprocessTransport)

(método de subprocess.Popen)

sendall() (método de socket.socket)

sendcmd() (método de ftplib.FTP)

sendfile() (en el módulo os)

(método de asyncio.loop)

(método de socket.socket)

(método de wsgiref.handlers.BaseHandler)

SendfileNotAvailableError

sendmail() (método de smtplib.SMTP)

sendmsg() (método de socket.socket)

sendmsg_afalg() (método de socket.socket)

sendto() (método de asyncio.DatagramTransport)

(método de socket.socket)

sentencia

assert, [1]

async def

async for

async with

break, [1], [2], [3], [4]

class

continue, [1], [2], [3], [4]

def

del, [1], [2], [3]

except

for, [1], [2], [3]

global, [1]

if, [1]

import, [1], [2], [3], [4]

nonlocal

pass

raise, [1]

return, [1], [2]

try, [1], [2]

while, [1], [2], [3]

with, [1]

yield

sentinel (atributo de multiprocessing.Process)

(en el módulo unittest.mock)

sep (en el módulo os)

sequence

item

iteration

objeto, [1], [2], [3], [4], [5], [6], [7], [8]

types, immutable

types, mutable

types, operations on, [1]

Sequence (clase en collections.abc)

(clase en typing)

sequence (en el módulo msilib)

sequence2st() (en el módulo parser)

SequenceMatcher (clase en difflib)

serializing

objects

serve_forever() (método de asyncio.Server)

(método de socketserver.BaseServer)

server

WWW, [1]

server (atributo de http.server.BaseHTTPRequestHandler)

Server (clase en asyncio)

server_activate() (método de socketserver.BaseServer)

server_address (atributo de socketserver.BaseServer)

server_bind() (método de socketserver.BaseServer)

server_close() (método de socketserver.BaseServer)

server_hostname (atributo de ssl.SSLSocket)

server_side (atributo de ssl.SSLSocket)

server_software (atributo de wsgiref.handlers.BaseHandler)

server_version (atributo de http.server.BaseHTTPRequestHandler)

(atributo de http.server.SimpleHTTPRequestHandler)

ServerProxy (clase en xmlrpc.client)

service_actions() (método de socketserver.BaseServer)

session (atributo de ssl.SSLSocket)

session_reused (atributo de ssl.SSLSocket)

session_stats() (método de ssl.SSLContext)

set

comprehensions

display

objeto, [1], [2], [3]

Set (clase en ast)

(clase en collections.abc)

(clase en typing)

set (clase incorporada)

Set Breakpoint

set type

objeto

set() (método de asyncio.Event)

(método de configparser.ConfigParser)

(método de configparser.RawConfigParser)

(método de contextvars.ContextVar)

(método de http.cookies.Morsel)

(método de ossaudiodev.oss_mixer_device)

(método de test.support.EnvironmentVarGuard)

(método de threading.Event)

(método de tkinter.ttk.Combobox)

(método de tkinter.ttk.Spinbox)

(método de tkinter.ttk.Treeview)

(método de xml.etree.ElementTree.Element)

SET_ADD (opcode)

set_all()

set_allowed_domains() (método de http.cookiejar.DefaultCookiePolicy)

set_alpn_protocols() (método de ssl.SSLContext)

set_app() (método de wsgiref.simple_server.WSGIServer)

set_asyncgen_hooks() (en el módulo sys)

set_authorizer() (método de sqlite3.Connection)

set_auto_history() (en el módulo readline)

set_blocked_domains() (método de http.cookiejar.DefaultCookiePolicy)

set_blocking() (en el módulo os)

set_boundary() (método de email.message.EmailMessage)

(método de email.message.Message)

set_break() (método de bdb.Bdb)

set_charset() (método de email.message.Message)

set_child_watcher() (en el módulo asyncio)

(método de asyncio.AbstractEventLoopPolicy)

set_children() (método de tkinter.ttk.Treeview)

set_ciphers() (método de ssl.SSLContext)

set_completer() (en el módulo readline)

set_completer_delims() (en el módulo readline)

set_completion_display_matches_hook() (en el módulo readline)

set_content() (en el módulo email.contentmanager)

(método de email.contentmanager.ContentManager)

(método de email.message.EmailMessage)

set_continue() (método de bdb.Bdb)

set_cookie() (método de http.cookiejar.CookieJar)

set_cookie_if_ok() (método de http.cookiejar.CookieJar)

set_coroutine_origin_tracking_depth() (en el módulo sys)

set_current() (método de msilib.Feature)

set_data() (método de importlib.abc.SourceLoader)

(método de importlib.machinery.SourceFileLoader)

set_date() (método de mailbox.MaildirMessage)

set_debug() (en el módulo gc)

(método de asyncio.loop)

set_debuglevel() (método de ftplib.FTP)

(método de http.client.HTTPConnection)

(método de nntplib.NNTP)

(método de poplib.POP3)

(método de smtplib.SMTP)

(método de telnetlib.Telnet)

set_default_executor() (método de asyncio.loop)

set_default_type() (método de email.message.EmailMessage)

(método de email.message.Message)

set_default_verify_paths() (método de ssl.SSLContext)

set_defaults() (método de argparse.ArgumentParser)

(método de optparse.OptionParser)

set_ecdh_curve() (método de ssl.SSLContext)

set_errno() (en el módulo ctypes)

set_escdelay() (en el módulo curses)

set_event_loop() (en el módulo asyncio)

(método de asyncio.AbstractEventLoopPolicy)

set_event_loop_policy() (en el módulo asyncio)

set_exception() (método de asyncio.Future)

(método de concurrent.futures.Future)

set_exception_handler() (método de asyncio.loop)

set_executable() (en el módulo multiprocessing)

set_executables() (método de distutils.ccompiler.CCompiler)

set_filter() (método de tkinter.filedialog.FileDialog)

set_flags() (método de mailbox.MaildirMessage)

(método de mailbox.mboxMessage)

(método de mailbox.MMDFMessage)

set_from() (método de mailbox.mboxMessage)

(método de mailbox.MMDFMessage)

set_handle_inheritable() (en el módulo os)

set_history_length() (en el módulo readline)

set_include_dirs() (método de distutils.ccompiler.CCompiler)

set_info() (método de mailbox.MaildirMessage)

set_inheritable() (en el módulo os)

(método de socket.socket)

set_int_max_str_digits() (en el módulo sys)

set_labels() (método de mailbox.BabylMessage)

set_last_error() (en el módulo ctypes)

set_libraries() (método de distutils.ccompiler.CCompiler)

set_library_dirs() (método de distutils.ccompiler.CCompiler)

set_link_objects() (método de distutils.ccompiler.CCompiler)

set_literal (2to3 fixer)

set_loader() (en el módulo importlib.util)

set_match_tests() (en el módulo test.support)

set_memlimit() (en el módulo test.support)

set_name() (método de asyncio.Task)

set_next() (método de bdb.Bdb)

set_nonstandard_attr() (método de http.cookiejar.Cookie)

set_npn_protocols() (método de ssl.SSLContext)

set_ok() (método de http.cookiejar.CookiePolicy)

set_option_negotiation_callback() (método de telnetlib.Telnet)

set_output_charset() (método de gettext.NullTranslations)

set_package() (en el módulo importlib.util)

set_param() (método de email.message.EmailMessage)

(método de email.message.Message)

set_pasv() (método de ftplib.FTP)

set_payload() (método de email.message.Message)

set_policy() (método de http.cookiejar.CookieJar)

set_position() (método de xdrlib.Unpacker)

set_pre_input_hook() (en el módulo readline)

set_progress_handler() (método de sqlite3.Connection)

set_protocol() (método de asyncio.BaseTransport)

set_proxy() (método de urllib.request.Request)

set_python_build() (en el módulo distutils.sysconfig)

set_quit() (método de bdb.Bdb)

set_recsrc() (método de ossaudiodev.oss_mixer_device)

set_result() (método de asyncio.Future)

(método de concurrent.futures.Future)

set_return() (método de bdb.Bdb)

set_running_or_notify_cancel() (método de concurrent.futures.Future)

set_runtime_library_dirs() (método de distutils.ccompiler.CCompiler)

set_selection() (método de tkinter.filedialog.FileDialog)

set_seq1() (método de difflib.SequenceMatcher)

set_seq2() (método de difflib.SequenceMatcher)

set_seqs() (método de difflib.SequenceMatcher)

set_sequences() (método de mailbox.MH)

(método de mailbox.MHMessage)

set_server_documentation() (método de xmlrpc.server.DocCGIXMLRPCRequestHandler)

(método de xmlrpc.server.DocXMLRPCServer)

set_server_name() (método de xmlrpc.server.DocCGIXMLRPCRequestHandler)

(método de xmlrpc.server.DocXMLRPCServer)

set_server_title() (método de xmlrpc.server.DocCGIXMLRPCRequestHandler)

(método de xmlrpc.server.DocXMLRPCServer)

set_servername_callback (atributo de ssl.SSLContext)

set_spacing() (método de formatter.formatter)

set_start_method() (en el módulo multiprocessing)

set_startup_hook() (en el módulo readline)

set_step() (método de bdb.Bdb)

set_subdir() (método de mailbox.MaildirMessage)

set_tabsize() (en el módulo curses)

set_task_factory() (método de asyncio.loop)

set_terminator() (método de asynchat.async_chat)

set_threshold() (en el módulo gc)

set_trace() (en el módulo bdb)

(en el módulo pdb)

(método de bdb.Bdb)

(método de pdb.Pdb)

set_trace_callback() (método de sqlite3.Connection)

set_tunnel() (método de http.client.HTTPConnection)

set_type() (método de email.message.Message)

set_unittest_reportflags() (en el módulo doctest)

set_unixfrom() (método de email.message.EmailMessage)

(método de email.message.Message)

set_until() (método de bdb.Bdb)

SET_UPDATE (opcode)

set_url() (método de urllib.robotparser.RobotFileParser)

set_usage() (método de optparse.OptionParser)

set_userptr() (método de curses.panel.Panel)

set_visible() (método de mailbox.BabylMessage)

set_wakeup_fd() (en el módulo signal)

set_write_buffer_limits() (método de asyncio.WriteTransport)

setacl() (método de imaplib.IMAP4)

setannotation() (método de imaplib.IMAP4)

setattr() (función incorporada)

setattrfunc (tipo C)

setAttribute() (método de xml.dom.Element)

setAttributeNode() (método de xml.dom.Element)

setAttributeNodeNS() (método de xml.dom.Element)

setAttributeNS() (método de xml.dom.Element)

setattrofunc (tipo C)

SetBase() (método de xml.parsers.expat.xmlparser)

setblocking() (método de socket.socket)

setByteStream() (método de xml.sax.xmlreader.InputSource)

setcbreak() (en el módulo tty)

setCharacterStream() (método de xml.sax.xmlreader.InputSource)

SetComp (clase en ast)

setcomptype() (método de aifc.aifc)

(método de sunau.AU_write)

(método de wave.Wave_write)

setContentHandler() (método de xml.sax.xmlreader.XMLReader)

setcontext() (en el módulo decimal)

setDaemon() (método de threading.Thread)

setdefault() (método de dict)

(método de http.cookies.Morsel)

setdefaulttimeout() (en el módulo socket)

setdlopenflags() (en el módulo sys)

setDocumentLocator() (método de xml.sax.handler.ContentHandler)

setDTDHandler() (método de xml.sax.xmlreader.XMLReader)

setegid() (en el módulo os)

setEncoding() (método de xml.sax.xmlreader.InputSource)

setEntityResolver() (método de xml.sax.xmlreader.XMLReader)

setErrorHandler() (método de xml.sax.xmlreader.XMLReader)

seteuid() (en el módulo os)

setFeature() (método de xml.sax.xmlreader.XMLReader)

setfirstweekday() (en el módulo calendar)

setfmt() (método de ossaudiodev.oss_audio_device)

setFormatter() (método de logging.Handler)

setframerate() (método de aifc.aifc)

(método de sunau.AU_write)

(método de wave.Wave_write)

setgid() (en el módulo os)

setgroups() (en el módulo os)

seth() (en el módulo turtle)

setheading() (en el módulo turtle)

sethostname() (en el módulo socket)

setinputsizes() (método de sqlite3.Cursor)

SetInteger() (método de msilib.Record)

setitem() (en el módulo operator)

setitimer() (en el módulo signal)

setLevel() (método de logging.Handler)

(método de logging.Logger)

setlocale() (en el módulo locale)

setLocale() (método de xml.sax.xmlreader.XMLReader)

setLoggerClass() (en el módulo logging)

setlogmask() (en el módulo syslog)

setLogRecordFactory() (en el módulo logging)

setmark() (método de aifc.aifc)

setMaxConns() (método de urllib.request.CacheFTPHandler)

setmode() (en el módulo msvcrt)

setName() (método de threading.Thread)

setnchannels() (método de aifc.aifc)

(método de sunau.AU_write)

(método de wave.Wave_write)

setnframes() (método de aifc.aifc)

(método de sunau.AU_write)

(método de wave.Wave_write)

setoutputsize() (método de sqlite3.Cursor)

SetParamEntityParsing() (método de xml.parsers.expat.xmlparser)

setparameters() (método de ossaudiodev.oss_audio_device)

setparams() (método de aifc.aifc)

(método de sunau.AU_write)

(método de wave.Wave_write)

setpassword() (método de zipfile.ZipFile)

setpgid() (en el módulo os)

setpgrp() (en el módulo os)

setpos() (en el módulo turtle)

(método de aifc.aifc)

(método de sunau.AU_read)

(método de wave.Wave_read)

setposition() (en el módulo turtle)

setpriority() (en el módulo os)

setprofile() (en el módulo sys)

(en el módulo threading)

SetProperty() (método de msilib.SummaryInformation)

setProperty() (método de xml.sax.xmlreader.XMLReader)

setPublicId() (método de xml.sax.xmlreader.InputSource)

setquota() (método de imaplib.IMAP4)

setraw() (en el módulo tty)

setrecursionlimit() (en el módulo sys)

setregid() (en el módulo os)

setresgid() (en el módulo os)

setresuid() (en el módulo os)

setreuid() (en el módulo os)

setrlimit() (en el módulo resource)

setsampwidth() (método de aifc.aifc)

(método de sunau.AU_write)

(método de wave.Wave_write)

setscrreg() (método de curses.window)

setsid() (en el módulo os)

setsockopt() (método de socket.socket)

setstate() (en el módulo random)

(método de codecs.IncrementalDecoder)

(método de codecs.IncrementalEncoder)

setStream() (método de logging.StreamHandler)

SetStream() (método de msilib.Record)

SetString() (método de msilib.Record)

setswitchinterval() (en el módulo sys)

(en el módulo test.support)

(in module sys)

setSystemId() (método de xml.sax.xmlreader.InputSource)

setsyx() (en el módulo curses)

setTarget() (método de logging.handlers.MemoryHandler)

settiltangle() (en el módulo turtle)

settimeout() (método de socket.socket)

setTimeout() (método de urllib.request.CacheFTPHandler)

settrace() (en el módulo sys)

(en el módulo threading)

setuid() (en el módulo os)

setundobuffer() (en el módulo turtle)

setup() (en el módulo distutils.core)

(en el módulo turtle)

(método de socketserver.BaseRequestHandler)

setUp() (método de unittest.TestCase)

SETUP_ANNOTATIONS (opcode)

SETUP_ASYNC_WITH (opcode)

setup_environ() (método de wsgiref.handlers.BaseHandler)

SETUP_FINALLY (opcode)

setup_python() (método de venv.EnvBuilder)

setup_scripts() (método de venv.EnvBuilder)

setup_testing_defaults() (en el módulo wsgiref.util)

SETUP_WITH (opcode)

setUpClass() (método de unittest.TestCase)

setupterm() (en el módulo curses)

SetValue() (en el módulo winreg)

SetValueEx() (en el módulo winreg)

setworldcoordinates() (en el módulo turtle)

setx() (en el módulo turtle)

setxattr() (en el módulo os)

sety() (en el módulo turtle)

SF_APPEND (en el módulo stat)

SF_ARCHIVED (en el módulo stat)

SF_IMMUTABLE (en el módulo stat)

SF_MNOWAIT (en el módulo os)

SF_NODISKIO (en el módulo os)

SF_NOUNLINK (en el módulo stat)

SF_SNAPSHOT (en el módulo stat)

SF_SYNC (en el módulo os)

shape (atributo de memoryview)

Shape (clase en turtle)

shape() (en el módulo turtle)

shapesize() (en el módulo turtle)

shapetransform() (en el módulo turtle)

share() (método de socket.socket)

ShareableList (clase en multiprocessing.shared_memory)

ShareableList() (método de multiprocessing.managers.SharedMemoryManager)

Shared Memory

shared_ciphers() (método de ssl.SSLSocket)

shared_object_filename() (método de distutils.ccompiler.CCompiler)

SharedMemory (clase en multiprocessing.shared_memory)

SharedMemory() (método de multiprocessing.managers.SharedMemoryManager)

SharedMemoryManager (clase en multiprocessing.managers)

shearfactor() (en el módulo turtle)

Shelf (clase en shelve)

shelve

módulo

shelve (módulo)

shield() (en el módulo asyncio)

shift() (método de decimal.Context)

(método de decimal.Decimal)

shift_path_info() (en el módulo wsgiref.util)

shifting

operation

operations

shlex (clase en shlex)

(módulo)

shm (atributo de multiprocessing.shared_memory.ShareableList)

SHORT_TIMEOUT (en el módulo test.support)

shortDescription() (método de unittest.TestCase)

shorten() (en el módulo textwrap)

shouldFlush() (método de logging.handlers.BufferingHandler)

(método de logging.handlers.MemoryHandler)

shouldStop (atributo de unittest.TestResult)

show() (método de curses.panel.Panel)

(método de tkinter.commondialog.Dialog)

show_code() (en el módulo dis)

show_compilers() (en el módulo distutils.ccompiler)

showerror() (en el módulo tkinter.messagebox)

showinfo() (en el módulo tkinter.messagebox)

showsyntaxerror() (método de code.InteractiveInterpreter)

showtraceback() (método de code.InteractiveInterpreter)

showturtle() (en el módulo turtle)

showwarning() (en el módulo tkinter.messagebox)

(en el módulo warnings)

shuffle() (en el módulo random)

shutdown() (en el módulo logging)

(método de concurrent.futures.Executor)

(método de imaplib.IMAP4)

(método de multiprocessing.managers.BaseManager)

(método de socket.socket)

(método de socketserver.BaseServer)

shutdown_asyncgens() (método de asyncio.loop)

shutdown_default_executor() (método de asyncio.loop)

shutil (módulo)

side_effect (atributo de unittest.mock.Mock)

SIG_BLOCK (en el módulo signal)

SIG_DFL (en el módulo signal)

SIG_IGN (en el módulo signal)

SIG_SETMASK (en el módulo signal)

SIG_UNBLOCK (en el módulo signal)

SIGABRT (en el módulo signal)

SIGALRM (en el módulo signal)

SIGBREAK (en el módulo signal)

SIGBUS (en el módulo signal)

SIGCHLD (en el módulo signal)

SIGCLD (en el módulo signal)

SIGCONT (en el módulo signal)

SIGFPE (en el módulo signal)

SIGHUP (en el módulo signal)

SIGILL (en el módulo signal)

SIGINT, [1]

(en el módulo signal)

siginterrupt() (en el módulo signal)

SIGKILL (en el módulo signal)

signal

módulo, [1]

signal (módulo)

signal() (en el módulo signal)

signature (atributo de inspect.BoundArguments)

Signature (clase en inspect)

signature() (en el módulo inspect)

sigpending() (en el módulo signal)

SIGPIPE (en el módulo signal)

SIGSEGV (en el módulo signal)

SIGTERM (en el módulo signal)

sigtimedwait() (en el módulo signal)

SIGUSR1 (en el módulo signal)

SIGUSR2 (en el módulo signal)

sigwait() (en el módulo signal)

sigwaitinfo() (en el módulo signal)

SIGWINCH (en el módulo signal)

simple

statement

Simple Mail Transfer Protocol

SimpleCookie (clase en http.cookies)

simplefilter() (en el módulo warnings)

SimpleHandler (clase en wsgiref.handlers)

SimpleHTTPRequestHandler (clase en http.server)

SimpleNamespace (clase en types)

SimpleQueue (clase en multiprocessing)

(clase en queue)

SimpleXMLRPCRequestHandler (clase en xmlrpc.server)

SimpleXMLRPCServer (clase en xmlrpc.server)

sin() (en el módulo cmath)

(en el módulo math)

SingleAddressHeader (clase en email.headerregistry)

singledispatch() (en el módulo functools)

singledispatchmethod (clase en functools)

singleton

tuple

sinh() (en el módulo cmath)

(en el módulo math)

SIO_KEEPALIVE_VALS (en el módulo socket)

SIO_LOOPBACK_FAST_PATH (en el módulo socket)

SIO_RCVALL (en el módulo socket)

site (módulo)

site command line option

--user-base

--user-site

site-packages

directory

site_maps() (método de urllib.robotparser.RobotFileParser)

sitecustomize

módulo

sixtofour (atributo de ipaddress.IPv6Address)

size (atributo de multiprocessing.shared_memory.SharedMemory)

(atributo de struct.Struct)

(atributo de tarfile.TarInfo)

(atributo de tracemalloc.Statistic)

(atributo de tracemalloc.StatisticDiff)

(atributo de tracemalloc.Trace)

size() (método de ftplib.FTP)

(método de mmap.mmap)

size_diff (atributo de tracemalloc.StatisticDiff)

SIZE_MAX

Sized (clase en collections.abc)

(clase en typing)

sizeof() (en el módulo ctypes)

SKIP (en el módulo doctest)

skip() (en el módulo unittest)

(método de chunk.Chunk)

skip_unless_bind_unix_socket() (en el módulo test.support.socket_helper)

skip_unless_symlink() (en el módulo test.support)

skip_unless_xattr() (en el módulo test.support)

skipIf() (en el módulo unittest)

skipinitialspace (atributo de csv.Dialect)

skipped (atributo de unittest.TestResult)

skippedEntity() (método de xml.sax.handler.ContentHandler)

SkipTest

skipTest() (método de unittest.TestCase)

skipUnless() (en el módulo unittest)

SLASH (en el módulo token)

SLASHEQUAL (en el módulo token)

slave() (método de nntplib.NNTP)

sleep() (en el módulo asyncio)

(en el módulo time)

slice

assignment

función incorporada, [1]

objeto

operation

Slice (clase en ast)

slice (clase incorporada)

slicing, [1], [2]

assignment

SMALLEST (en el módulo test.support)

SMTP

protocol

SMTP (clase en smtplib)

(en el módulo email.policy)

smtp_server (atributo de smtpd.SMTPChannel)

SMTP_SSL (clase en smtplib)

smtp_state (atributo de smtpd.SMTPChannel)

SMTPAuthenticationError

SMTPChannel (clase en smtpd)

SMTPConnectError

smtpd (módulo)

SMTPDataError

SMTPException

SMTPHandler (clase en logging.handlers)

SMTPHeloError

smtplib (módulo)

SMTPNotSupportedError

SMTPRecipientsRefused

SMTPResponseException

SMTPSenderRefused

SMTPServer (clase en smtpd)

SMTPServerDisconnected

SMTPUTF8 (en el módulo email.policy)

Snapshot (clase en tracemalloc)

SND_ALIAS (en el módulo winsound)

SND_ASYNC (en el módulo winsound)

SND_FILENAME (en el módulo winsound)

SND_LOOP (en el módulo winsound)

SND_MEMORY (en el módulo winsound)

SND_NODEFAULT (en el módulo winsound)

SND_NOSTOP (en el módulo winsound)

SND_NOWAIT (en el módulo winsound)

SND_PURGE (en el módulo winsound)

sndhdr (módulo)

sni_callback (atributo de ssl.SSLContext)

sniff() (método de csv.Sniffer)

Sniffer (clase en csv)

sock_accept() (método de asyncio.loop)

SOCK_CLOEXEC (en el módulo socket)

sock_connect() (método de asyncio.loop)

SOCK_DGRAM (en el módulo socket)

SOCK_MAX_SIZE (en el módulo test.support)

SOCK_NONBLOCK (en el módulo socket)

SOCK_RAW (en el módulo socket)

SOCK_RDM (en el módulo socket)

sock_recv() (método de asyncio.loop)

sock_recv_into() (método de asyncio.loop)

sock_sendall() (método de asyncio.loop)

sock_sendfile() (método de asyncio.loop)

SOCK_SEQPACKET (en el módulo socket)

SOCK_STREAM (en el módulo socket)

socket

módulo

objeto

socket (atributo de socketserver.BaseServer)

(clase en socket)

(módulo)

socket() (in module socket)

(método de imaplib.IMAP4)

socket_type (atributo de socketserver.BaseServer)

SocketHandler (clase en logging.handlers)

socketpair() (en el módulo socket)

sockets (atributo de asyncio.Server)

socketserver (módulo)

SocketType (en el módulo socket)

softkwlist (en el módulo keyword)

SOL_ALG (en el módulo socket)

SOL_RDS (en el módulo socket)

SOMAXCONN (en el módulo socket)

sort() (método de imaplib.IMAP4)

(método de list)

sort_stats() (método de pstats.Stats)

sortdict() (en el módulo test.support)

sorted() (función incorporada)

sortTestMethodsUsing (atributo de unittest.TestLoader)

source (atributo de doctest.Example)

(atributo de shlex.shlex)

(pdb command)

source character set

SOURCE_DATE_EPOCH, [1], [2], [3], [4], [5], [6]

source_from_cache() (en el módulo imp)

(en el módulo importlib.util)

source_hash() (en el módulo importlib.util)

SOURCE_SUFFIXES (en el módulo importlib.machinery)

source_to_code() (método estático de importlib.abc.InspectLoader)

SourceFileLoader (clase en importlib.machinery)

sourcehook() (método de shlex.shlex)

SourcelessFileLoader (clase en importlib.machinery)

SourceLoader (clase en importlib.abc)

space

in printf-style formatting, [1]

in string formatting

span() (método de re.Match)

spawn() (en el módulo pty)

(método de distutils.ccompiler.CCompiler)

spawn_python() (en el módulo test.support.script_helper)

spawnl() (en el módulo os)

spawnle() (en el módulo os)

spawnlp() (en el módulo os)

spawnlpe() (en el módulo os)

spawnv() (en el módulo os)

spawnve() (en el módulo os)

spawnvp() (en el módulo os)

spawnvpe() (en el módulo os)

spec_from_file_location() (en el módulo importlib.util)

spec_from_loader() (en el módulo importlib.util)

special

attribute

attribute, generic

method

SpecialFileError

specified_attributes (atributo de xml.parsers.expat.xmlparser)

speed() (en el módulo turtle)

(método de ossaudiodev.oss_audio_device)

Spinbox (clase en tkinter.ttk)

split() (en el módulo os.path)

(en el módulo re)

(en el módulo shlex)

(método de bytearray)

(método de bytes)

(método de re.Pattern)

(método de str)

split_quoted() (en el módulo distutils.util)

splitdrive() (en el módulo os.path)

splitext() (en el módulo os.path)

splitlines() (método de bytearray)

(método de bytes)

(método de str)

SplitResult (clase en urllib.parse)

SplitResultBytes (clase en urllib.parse)

SpooledTemporaryFile() (en el módulo tempfile)

sprintf-style formatting, [1]

spwd (módulo)

sqlite3 (módulo)

sqlite_version (en el módulo sqlite3)

sqlite_version_info (en el módulo sqlite3)

sqrt() (en el módulo cmath)

(en el módulo math)

(método de decimal.Context)

(método de decimal.Decimal)

ssizeargfunc (tipo C)

ssizeobjargproc (tipo C)

SSL

ssl (módulo)

SSL_CERT_FILE

SSL_CERT_PATH

ssl_version (atributo de ftplib.FTP_TLS)

SSLCertVerificationError

SSLContext (clase en ssl)

SSLEOFError

SSLError

SSLErrorNumber (clase en ssl)

SSLKEYLOGFILE, [1]

SSLObject (clase en ssl)

sslobject_class (atributo de ssl.SSLContext)

SSLSession (clase en ssl)

SSLSocket (clase en ssl)

sslsocket_class (atributo de ssl.SSLContext)

SSLSyscallError

SSLv3 (atributo de ssl.TLSVersion)

SSLWantReadError

SSLWantWriteError

SSLZeroReturnError

st() (en el módulo turtle)

st2list() (en el módulo parser)

st2tuple() (en el módulo parser)

st_atime (atributo de os.stat_result)

ST_ATIME (en el módulo stat)

st_atime_ns (atributo de os.stat_result)

st_birthtime (atributo de os.stat_result)

st_blksize (atributo de os.stat_result)

st_blocks (atributo de os.stat_result)

st_creator (atributo de os.stat_result)

st_ctime (atributo de os.stat_result)

ST_CTIME (en el módulo stat)

st_ctime_ns (atributo de os.stat_result)

st_dev (atributo de os.stat_result)

ST_DEV (en el módulo stat)

st_file_attributes (atributo de os.stat_result)

st_flags (atributo de os.stat_result)

st_fstype (atributo de os.stat_result)

st_gen (atributo de os.stat_result)

st_gid (atributo de os.stat_result)

ST_GID (en el módulo stat)

st_ino (atributo de os.stat_result)

ST_INO (en el módulo stat)

st_mode (atributo de os.stat_result)

ST_MODE (en el módulo stat)

st_mtime (atributo de os.stat_result)

ST_MTIME (en el módulo stat)

st_mtime_ns (atributo de os.stat_result)

st_nlink (atributo de os.stat_result)

ST_NLINK (en el módulo stat)

st_rdev (atributo de os.stat_result)

st_reparse_tag (atributo de os.stat_result)

st_rsize (atributo de os.stat_result)

st_size (atributo de os.stat_result)

ST_SIZE (en el módulo stat)

st_type (atributo de os.stat_result)

st_uid (atributo de os.stat_result)

ST_UID (en el módulo stat)

stack

execution

trace

stack (atributo de traceback.TracebackException)

stack viewer

stack() (en el módulo inspect)

stack_effect() (en el módulo dis)

stack_size() (en el módulo _thread)

(en el módulo threading)

stackable

streams

StackSummary (clase en traceback)

stamp() (en el módulo turtle)

standard

output

Standard C

standard input

standard_b64decode() (en el módulo base64)

standard_b64encode() (en el módulo base64)

standarderror (2to3 fixer)

standend() (método de curses.window)

standout() (método de curses.window)

STAR (en el módulo token)

STAREQUAL (en el módulo token)

starmap() (en el módulo itertools)

(método de multiprocessing.pool.Pool)

starmap_async() (método de multiprocessing.pool.Pool)

Starred (clase en ast)

start (atributo de range)

(atributo de UnicodeError)

(slice object attribute), [1]

start() (en el módulo tracemalloc)

(método de logging.handlers.QueueListener)

(método de multiprocessing.managers.BaseManager)

(método de multiprocessing.Process)

(método de re.Match)

(método de threading.Thread)

(método de tkinter.ttk.Progressbar)

(método de xml.etree.ElementTree.TreeBuilder)

start_color() (en el módulo curses)

start_component() (método de msilib.Directory)

start_new_thread() (en el módulo _thread)

start_ns() (método de xml.etree.ElementTree.TreeBuilder)

start_server() (en el módulo asyncio)

start_serving() (método de asyncio.Server)

start_threads() (en el módulo test.support)

start_tls() (método de asyncio.loop)

start_unix_server() (en el módulo asyncio)

StartCdataSectionHandler() (método de xml.parsers.expat.xmlparser)

StartDoctypeDeclHandler() (método de xml.parsers.expat.xmlparser)

startDocument() (método de xml.sax.handler.ContentHandler)

startElement() (método de xml.sax.handler.ContentHandler)

StartElementHandler() (método de xml.parsers.expat.xmlparser)

startElementNS() (método de xml.sax.handler.ContentHandler)

STARTF_USESHOWWINDOW (en el módulo subprocess)

STARTF_USESTDHANDLES (en el módulo subprocess)

startfile() (en el módulo os)

StartNamespaceDeclHandler() (método de xml.parsers.expat.xmlparser)

startPrefixMapping() (método de xml.sax.handler.ContentHandler)

startswith() (método de bytearray)

(método de bytes)

(método de str)

startTest() (método de unittest.TestResult)

startTestRun() (método de unittest.TestResult)

starttls() (método de imaplib.IMAP4)

(método de nntplib.NNTP)

(método de smtplib.SMTP)

STARTUPINFO (clase en subprocess)

stat

módulo

stat (módulo)

stat() (en el módulo os)

(método de nntplib.NNTP)

(método de os.DirEntry)

(método de pathlib.Path)

(método de poplib.POP3)

stat_result (clase en os)

state() (método de tkinter.ttk.Widget)

statement

assignment, [1]

assignment, annotated

assignment, augmented

compound

expression

future

loop, [1], [2], [3]

simple

statement grouping

static_order() (método de graphlib.TopologicalSorter)

staticmethod

función incorporada

staticmethod() (función incorporada)

Statistic (clase en tracemalloc)

StatisticDiff (clase en tracemalloc)

statistics (módulo)

statistics() (método de tracemalloc.Snapshot)

StatisticsError

Stats (clase en pstats)

status (atributo de http.client.HTTPResponse)

(atributo de urllib.response.addinfourl)

status() (método de imaplib.IMAP4)

statvfs() (en el módulo os)

STD_ERROR_HANDLE (en el módulo subprocess)

STD_INPUT_HANDLE (en el módulo subprocess)

STD_OUTPUT_HANDLE (en el módulo subprocess)

StdButtonBox (clase en tkinter.tix)

stderr (atributo de asyncio.subprocess.Process)

(atributo de subprocess.CalledProcessError)

(atributo de subprocess.CompletedProcess)

(atributo de subprocess.Popen)

(atributo de subprocess.TimeoutExpired)

(en el módulo sys)

(in module sys), [1]

stdev (atributo de statistics.NormalDist)

stdev() (en el módulo statistics)

stdin

stdout sdterr

stdin (atributo de asyncio.subprocess.Process)

(atributo de subprocess.Popen)

(en el módulo sys)

(in module sys), [1]

stdio

stdout

sdterr, stdin

stdout (atributo de asyncio.subprocess.Process)

(atributo de subprocess.CalledProcessError)

(atributo de subprocess.CompletedProcess)

(atributo de subprocess.Popen)

(atributo de subprocess.TimeoutExpired)

STDOUT (en el módulo subprocess)

stdout (en el módulo sys)

(in module sys), [1]

step (atributo de range)

(pdb command)

(slice object attribute), [1]

step() (método de tkinter.ttk.Progressbar)

stereocontrols() (método de ossaudiodev.oss_mixer_device)

stls() (método de poplib.POP3)

stop (atributo de range)

(slice object attribute), [1]

stop() (en el módulo tracemalloc)

(método de asyncio.loop)

(método de logging.handlers.QueueListener)

(método de tkinter.ttk.Progressbar)

(método de unittest.TestResult)

stop_here() (método de bdb.Bdb)

StopAsyncIteration

excepción

StopIteration

excepción, [1]

stopListening() (en el módulo logging.config)

stopTest() (método de unittest.TestResult)

stopTestRun() (método de unittest.TestResult)

storbinary() (método de ftplib.FTP)

Store (clase en ast)

store() (método de imaplib.IMAP4)

STORE_ACTIONS (atributo de optparse.Option)

STORE_ATTR (opcode)

STORE_DEREF (opcode)

STORE_FAST (opcode)

STORE_GLOBAL (opcode)

STORE_NAME (opcode)

STORE_SUBSCR (opcode)

storlines() (método de ftplib.FTP)

str (built-in class)

(see also string)

str (clase incorporada)

str() (en el módulo locale)

strcoll() (en el módulo locale)

StreamError

StreamHandler (clase en logging)

streamreader (atributo de codecs.CodecInfo)

StreamReader (clase en asyncio)

(clase en codecs)

StreamReaderWriter (clase en codecs)

StreamRecoder (clase en codecs)

StreamRequestHandler (clase en socketserver)

streams

stackable

streamwriter (atributo de codecs.CodecInfo)

StreamWriter (clase en asyncio)

(clase en codecs)

strerror (atributo de OSError)

strerror()

(en el módulo os)

strftime() (en el módulo time)

(método de datetime.date)

(método de datetime.datetime)

(método de datetime.time)

strict

error handler's name

strict (atributo de csv.Dialect)

(en el módulo email.policy)

strict_domain (atributo de http.cookiejar.DefaultCookiePolicy)

strict_errors() (en el módulo codecs)

strict_ns_domain (atributo de http.cookiejar.DefaultCookiePolicy)

strict_ns_set_initial_dollar (atributo de http.cookiejar.DefaultCookiePolicy)

strict_ns_set_path (atributo de http.cookiejar.DefaultCookiePolicy)

strict_ns_unverifiable (atributo de http.cookiejar.DefaultCookiePolicy)

strict_rfc2965_unverifiable (atributo de http.cookiejar.DefaultCookiePolicy)

strides (atributo de memoryview)

string

__format__() (object method)

__str__() (object method)

conversion, [1]

format() (built-in function)

formatted literal

formatting, printf

immutable sequences

interpolated literal

interpolation, printf

item

methods

módulo

object representation

objeto, [1], [2]

PyObject_Str (C function)

str (built-in class)

str() (built-in function)

text sequence type

string (atributo de re.Match)

STRING (en el módulo token)

string (módulo)

string literal

string_at() (en el módulo ctypes)

StringIO (clase en io)

stringprep (módulo)

strings, documentation, [1]

strip() (método de bytearray)

(método de bytes)

(método de str)

strip_dirs() (método de pstats.Stats)

stripspaces (atributo de curses.textpad.Textbox)

strptime() (en el módulo time)

(método de clase de datetime.datetime)

strsignal() (en el módulo signal)

strtobool() (en el módulo distutils.util)

struct

módulo

Struct (clase en struct)

struct (módulo)

struct_time (clase en time)

Structure (clase en ctypes)

structures

C

strxfrm() (en el módulo locale)

STType (en el módulo parser)

style

coding

Style (clase en tkinter.ttk)

Sub (clase en ast)

sub() (en el módulo operator)

(en el módulo re)

(método de re.Pattern)

sub_commands (atributo de distutils.cmd.Command)

subclassing

immutable types

subdirs (atributo de filecmp.dircmp)

SubElement() (en el módulo xml.etree.ElementTree)

submit() (método de concurrent.futures.Executor)

submodule_search_locations (atributo de importlib.machinery.ModuleSpec)

subn() (en el módulo re)

(método de re.Pattern)

subnet_of() (método de ipaddress.IPv4Network)

(método de ipaddress.IPv6Network)

subnets() (método de ipaddress.IPv4Network)

(método de ipaddress.IPv6Network)

Subnormal (clase en decimal)

suboffsets (atributo de memoryview)

subpad() (método de curses.window)

subprocess (módulo)

subprocess_exec() (método de asyncio.loop)

subprocess_shell() (método de asyncio.loop)

SubprocessError

SubprocessProtocol (clase en asyncio)

SubprocessTransport (clase en asyncio)

subscribe() (método de imaplib.IMAP4)

subscript

assignment

operation

Subscript (clase en ast)

subscription, [1], [2], [3]

assignment

subsequent_indent (atributo de textwrap.TextWrapper)

subst_vars() (en el módulo distutils.util)

substitute() (método de string.Template)

subTest() (método de unittest.TestCase)

subtract() (método de collections.Counter)

(método de decimal.Context)

subtraction

subtype (atributo de email.headerregistry.ContentTypeHeader)

subwin() (método de curses.window)

successful() (método de multiprocessing.pool.AsyncResult)

suffix_map (atributo de mimetypes.MimeTypes)

(en el módulo mimetypes)

suite

suite() (en el módulo parser)

suiteClass (atributo de unittest.TestLoader)

sum() (función incorporada)

sum_list()

sum_sequence(), [1]

summarize() (método de doctest.DocTestRunner)

summarize_address_range() (en el módulo ipaddress)

sunau (módulo)

super (atributo de pyclbr.Class)

super() (función incorporada)

supernet() (método de ipaddress.IPv4Network)

(método de ipaddress.IPv6Network)

supernet_of() (método de ipaddress.IPv4Network)

(método de ipaddress.IPv6Network)

supports_bytes_environ (en el módulo os)

supports_dir_fd (en el módulo os)

supports_effective_ids (en el módulo os)

supports_fd (en el módulo os)

supports_follow_symlinks (en el módulo os)

supports_unicode_filenames (en el módulo os.path)

SupportsAbs (clase en typing)

SupportsBytes (clase en typing)

SupportsComplex (clase en typing)

SupportsFloat (clase en typing)

SupportsIndex (clase en typing)

SupportsInt (clase en typing)

SupportsRound (clase en typing)

suppress() (en el módulo contextlib)

SuppressCrashReport (clase en test.support)

surrogateescape

error handler's name

surrogatepass

error handler's name

SW_HIDE (en el módulo subprocess)

swap_attr() (en el módulo test.support)

swap_item() (en el módulo test.support)

swapcase() (método de bytearray)

(método de bytes)

(método de str)

sym_name (en el módulo symbol)

Symbol (clase en symtable)

symbol (módulo)

SymbolTable (clase en symtable)

symlink() (en el módulo os)

symlink_to() (método de pathlib.Path)

symmetric_difference() (método de frozenset)

symmetric_difference_update() (método de frozenset)

symtable (módulo)

symtable() (en el módulo symtable)

sync() (en el módulo os)

(método de dbm.dumb.dumbdbm)

(método de dbm.gnu.gdbm)

(método de ossaudiodev.oss_audio_device)

(método de shelve.Shelf)

syncdown() (método de curses.window)

synchronized() (en el módulo multiprocessing.sharedctypes)

SyncManager (clase en multiprocessing.managers)

syncok() (método de curses.window)

syncup() (método de curses.window)

syntax

SyntaxErr

SyntaxError

SyntaxWarning

sys

módulo, [1], [2], [3], [4], [5], [6]

sys (módulo)

sys.exc_info

sys.last_traceback

sys.meta_path

sys.modules

sys.path

sys.path_hooks

sys.path_importer_cache

sys.stderr

sys.stdin

sys.stdout

sys_exc (2to3 fixer)

sys_version (atributo de http.server.BaseHTTPRequestHandler)

sysconf() (en el módulo os)

sysconf_names (en el módulo os)

sysconfig (módulo)

syslog (módulo)

syslog() (en el módulo syslog)

SysLogHandler (clase en logging.handlers)

system() (en el módulo os)

(en el módulo platform)

system_alias() (en el módulo platform)

system_must_validate_cert() (en el módulo test.support)

SystemError

(built-in exception), [1]

SystemExit

(built-in exception)

systemId (atributo de xml.dom.DocumentType)

SystemRandom (clase en random)

(clase en secrets)

SystemRoot

T

T_FMT (en el módulo locale)

T_FMT_AMPM (en el módulo locale)

tab

tab() (método de tkinter.ttk.Notebook)

TabError

tabnanny (módulo)

tabs() (método de tkinter.ttk.Notebook)

tabsize (atributo de textwrap.TextWrapper)

tabular

data

tag (atributo de xml.etree.ElementTree.Element)

tag_bind() (método de tkinter.ttk.Treeview)

tag_configure() (método de tkinter.ttk.Treeview)

tag_has() (método de tkinter.ttk.Treeview)

tagName (atributo de xml.dom.Element)

tail (atributo de xml.etree.ElementTree.Element)

take_snapshot() (en el módulo tracemalloc)

takewhile() (en el módulo itertools)

tan() (en el módulo cmath)

(en el módulo math)

tanh() (en el módulo cmath)

(en el módulo math)

tar_filter() (en el módulo tarfile)

TarError

TarFile (clase en tarfile)

tarfile (módulo)

tarfile command line option

--create <tarfile> <source1> ... <sourceN>

--extract <tarfile> [<output_dir>]

--filter <filtername>

--list <tarfile>

--test <tarfile>

--verbose

-c <tarfile> <source1> ... <sourceN>

-e <tarfile> [<output_dir>]

-l <tarfile>

-t <tarfile>

-v

target

deletion

list, [1]

list assignment

list, deletion

loop control

target (atributo de xml.dom.ProcessingInstruction)

tarinfo (atributo de tarfile.FilterError)

TarInfo (clase en tarfile)

Task (clase en asyncio)

task_done() (método de asyncio.Queue)

(método de multiprocessing.JoinableQueue)

(método de queue.Queue)

tau (en el módulo cmath)

(en el módulo math)

tb_frame (traceback attribute)

tb_lasti (traceback attribute)

tb_lineno (traceback attribute)

tb_locals (atributo de unittest.TestResult)

tb_next (traceback attribute)

tbreak (pdb command)

tcdrain() (en el módulo termios)

tcflow() (en el módulo termios)

tcflush() (en el módulo termios)

tcgetattr() (en el módulo termios)

tcgetpgrp() (en el módulo os)

Tcl() (en el módulo tkinter)

TCL_LIBRARY

TCPServer (clase en socketserver)

tcsendbreak() (en el módulo termios)

tcsetattr() (en el módulo termios)

tcsetpgrp() (en el módulo os)

tearDown() (método de unittest.TestCase)

tearDownClass() (método de unittest.TestCase)

tee() (en el módulo itertools)

tell() (método de aifc.aifc)

(método de chunk.Chunk)

(método de io.IOBase)

(método de io.TextIOBase)

(método de mmap.mmap)

(método de sunau.AU_read)

(método de sunau.AU_write)

(método de wave.Wave_read)

(método de wave.Wave_write)

Telnet (clase en telnetlib)

telnetlib (módulo)

TEMP

temp_cwd() (en el módulo test.support)

temp_dir() (en el módulo test.support)

temp_umask() (en el módulo test.support)

tempdir (en el módulo tempfile)

tempfile (módulo)

template (atributo de string.Template)

Template (clase en pipes)

(clase en string)

temporary

file

file name

TemporaryDirectory() (en el módulo tempfile)

TemporaryFile() (en el módulo tempfile)

teredo (atributo de ipaddress.IPv6Address)

TERM, [1]

termattrs() (en el módulo curses)

terminal_size (clase en os)

terminate() (método de asyncio.subprocess.Process)

(método de asyncio.SubprocessTransport)

(método de multiprocessing.pool.Pool)

(método de multiprocessing.Process)

(método de subprocess.Popen)

termination model

terminator (atributo de logging.StreamHandler)

termios (módulo)

termname() (en el módulo curses)

ternary

operator

ternaryfunc (tipo C)

test

identity

membership

test (atributo de doctest.DocTestFailure)

(atributo de doctest.UnexpectedException)

(módulo)

test() (en el módulo cgi)

test.support (módulo)

test.support.bytecode_helper (módulo)

test.support.script_helper (módulo)

test.support.socket_helper (módulo)

TEST_DATA_DIR (en el módulo test.support)

TEST_HOME_DIR (en el módulo test.support)

TEST_HTTP_URL (en el módulo test.support)

TEST_SUPPORT_DIR (en el módulo test.support)

TestCase (clase en unittest)

TestFailed

testfile() (en el módulo doctest)

TESTFN (en el módulo test.support)

TESTFN_ENCODING (en el módulo test.support)

TESTFN_NONASCII (en el módulo test.support)

TESTFN_UNDECODABLE (en el módulo test.support)

TESTFN_UNENCODABLE (en el módulo test.support)

TESTFN_UNICODE (en el módulo test.support)

TestLoader (clase en unittest)

testMethodPrefix (atributo de unittest.TestLoader)

testmod() (en el módulo doctest)

testNamePatterns (atributo de unittest.TestLoader)

TestResult (clase en unittest)

tests (en el módulo imghdr)

testsource() (en el módulo doctest)

testsRun (atributo de unittest.TestResult)

TestSuite (clase en unittest)

testzip() (método de zipfile.ZipFile)

text (atributo de SyntaxError)

(atributo de traceback.TracebackException)

(atributo de xml.etree.ElementTree.Element)

Text (clase en typing)

text (en el módulo msilib)

text mode

text() (en el módulo cgitb)

(método de msilib.Dialog)

text_factory (atributo de sqlite3.Connection)

Textbox (clase en curses.textpad)

TextCalendar (clase en calendar)

textdomain() (en el módulo gettext)

(en el módulo locale)

TextFile (clase en distutils.text_file)

textinput() (en el módulo turtle)

TextIO (clase en typing)

TextIOBase (clase en io)

TextIOWrapper (clase en io)

TextTestResult (clase en unittest)

TextTestRunner (clase en unittest)

textwrap (módulo)

TextWrapper (clase en textwrap)

theme_create() (método de tkinter.ttk.Style)

theme_names() (método de tkinter.ttk.Style)

theme_settings() (método de tkinter.ttk.Style)

theme_use() (método de tkinter.ttk.Style)

THOUSEP (en el módulo locale)

Thread (clase en threading)

thread() (método de imaplib.IMAP4)

thread_info (en el módulo sys)

thread_time() (en el módulo time)

thread_time_ns() (en el módulo time)

ThreadedChildWatcher (clase en asyncio)

threading (módulo)

threading_cleanup() (en el módulo test.support)

threading_setup() (en el módulo test.support)

ThreadingHTTPServer (clase en http.server)

ThreadingMixIn (clase en socketserver)

ThreadingTCPServer (clase en socketserver)

ThreadingUDPServer (clase en socketserver)

ThreadPool (clase en multiprocessing.pool)

ThreadPoolExecutor (clase en concurrent.futures)

threads

POSIX

threadsafety (en el módulo sqlite3)

throw (2to3 fixer)

throw() (método de coroutine)

(método de generator)

ticket_lifetime_hint (atributo de ssl.SSLSession)

tigetflag() (en el módulo curses)

tigetnum() (en el módulo curses)

tigetstr() (en el módulo curses)

TILDE (en el módulo token)

tilt() (en el módulo turtle)

tiltangle() (en el módulo turtle)

time (atributo de ssl.SSLSession)

(clase en datetime)

(módulo)

time() (en el módulo time)

(método de asyncio.loop)

(método de datetime.datetime)

Time2Internaldate() (en el módulo imaplib)

time_ns() (en el módulo time)

timedelta (clase en datetime)

TimedRotatingFileHandler (clase en logging.handlers)

timegm() (en el módulo calendar)

timeit (módulo)

timeit command line option

--help

--number=N

--process

--repeat=N

--setup=S

--unit=U

--verbose

-h

-n N

-p

-r N

-s S

-u

-v

timeit() (en el módulo timeit)

(método de timeit.Timer)

timeout

(atributo de socketserver.BaseServer)

(atributo de ssl.SSLSession)

(atributo de subprocess.TimeoutExpired)

timeout() (método de curses.window)

TIMEOUT_MAX (en el módulo _thread)

(en el módulo threading)

TimeoutError, [1], [2], [3]

TimeoutExpired

Timer (clase en threading)

(clase en timeit)

TimerHandle (clase en asyncio)

times() (en el módulo os)

TIMESTAMP (atributo de py_compile.PycInvalidationMode)

timestamp() (método de datetime.datetime)

timetuple() (método de datetime.date)

(método de datetime.datetime)

timetz() (método de datetime.datetime)

timezone (clase en datetime)

(en el módulo time)

tipado de pato

tipo

tipos genéricos

title() (en el módulo turtle)

(método de bytearray)

(método de bytes)

(método de str)

Tix

tix_addbitmapdir() (método de tkinter.tix.tixCommand)

tix_cget() (método de tkinter.tix.tixCommand)

tix_configure() (método de tkinter.tix.tixCommand)

tix_filedialog() (método de tkinter.tix.tixCommand)

tix_getbitmap() (método de tkinter.tix.tixCommand)

tix_getimage() (método de tkinter.tix.tixCommand)

tix_option_get() (método de tkinter.tix.tixCommand)

tix_resetoptions() (método de tkinter.tix.tixCommand)

tixCommand (clase en tkinter.tix)

Tk

tk (atributo de tkinter.Tk)

Tk (clase en tkinter)

(clase en tkinter.tix)

Tk Option Data Types

TK_LIBRARY

Tkinter

tkinter (módulo)

tkinter.colorchooser (módulo)

tkinter.commondialog (módulo)

tkinter.dnd (módulo)

tkinter.filedialog (módulo)

tkinter.font (módulo)

tkinter.messagebox (módulo)

tkinter.scrolledtext (módulo)

tkinter.simpledialog (módulo)

tkinter.tix (módulo)

tkinter.ttk (módulo)

TList (clase en tkinter.tix)

TLS

TLSv1 (atributo de ssl.TLSVersion)

TLSv1_1 (atributo de ssl.TLSVersion)

TLSv1_2 (atributo de ssl.TLSVersion)

TLSv1_3 (atributo de ssl.TLSVersion)

TLSVersion (clase en ssl)

TMP

TMPDIR

to_bytes() (método de int)

to_eng_string() (método de decimal.Context)

(método de decimal.Decimal)

to_integral() (método de decimal.Decimal)

to_integral_exact() (método de decimal.Context)

(método de decimal.Decimal)

to_integral_value() (método de decimal.Decimal)

to_sci_string() (método de decimal.Context)

to_thread() (en el módulo asyncio)

ToASCII() (en el módulo encodings.idna)

tobuf() (método de tarfile.TarInfo)

tobytes() (método de array.array)

(método de memoryview)

today() (método de clase de datetime.date)

(método de clase de datetime.datetime)

tofile() (método de array.array)

tok_name (en el módulo token)

token

(atributo de shlex.shlex)

Token (clase en contextvars)

token (módulo)

token_bytes() (en el módulo secrets)

token_hex() (en el módulo secrets)

token_urlsafe() (en el módulo secrets)

TokenError

tokenize (módulo)

tokenize command line option

--exact

--help

-e

-h

tokenize() (en el módulo tokenize)

tolist() (método de array.array)

(método de memoryview)

(método de parser.ST)

tomono() (en el módulo audioop)

toordinal() (método de datetime.date)

(método de datetime.datetime)

top() (método de curses.panel.Panel)

(método de poplib.POP3)

top_panel() (en el módulo curses.panel)

TopologicalSorter (clase en graphlib)

toprettyxml() (método de xml.dom.minidom.Node)

toreadonly() (método de memoryview)

tostereo() (en el módulo audioop)

tostring() (en el módulo xml.etree.ElementTree)

tostringlist() (en el módulo xml.etree.ElementTree)

total_changes (atributo de sqlite3.Connection)

total_nframe (atributo de tracemalloc.Traceback)

total_ordering() (en el módulo functools)

total_seconds() (método de datetime.timedelta)

totuple() (método de parser.ST)

touch() (método de pathlib.Path)

touchline() (método de curses.window)

touchwin() (método de curses.window)

ToUnicode() (en el módulo encodings.idna)

tounicode() (método de array.array)

towards() (en el módulo turtle)

toxml() (método de xml.dom.minidom.Node)

tparm() (en el módulo curses)

trace

stack

Trace (clase en trace)

(clase en tracemalloc)

trace (módulo)

trace command line option

--count

--coverdir=<dir>

--file=<file>

--help

--ignore-dir=<dir>

--ignore-module=<mod>

--listfuncs

--missing

--no-report

--report

--summary

--timing

--trace

--trackcalls

--version

-c

-C

-f

-g

-l

-m

-r

-R

-s

-t

-T

trace function, [1], [2]

trace() (en el módulo inspect)

trace_dispatch() (método de bdb.Bdb)

traceback

objeto, [1], [2], [3], [4]

traceback (atributo de tracemalloc.Statistic)

(atributo de tracemalloc.StatisticDiff)

(atributo de tracemalloc.Trace)

Traceback (clase en tracemalloc)

traceback (módulo)

traceback_limit (atributo de tracemalloc.Snapshot)

(atributo de wsgiref.handlers.BaseHandler)

TracebackException (clase en traceback)

tracebacklimit (en el módulo sys)

tracebacks

in CGI scripts

TracebackType (clase en types)

tracemalloc (módulo)

tracer() (en el módulo turtle)

traces (atributo de tracemalloc.Snapshot)

trailing

comma

transfercmd() (método de ftplib.FTP)

transient_internet() (en el módulo test.support.socket_helper)

TransientResource (clase en test.support)

translate() (en el módulo fnmatch)

(método de bytearray)

(método de bytes)

(método de str)

translation() (en el módulo gettext)

transport (atributo de asyncio.StreamWriter)

Transport (clase en asyncio)

Transport Layer Security

Traversable (clase en importlib.abc)

TraversableResources (clase en importlib.abc)

traverseproc (tipo C)

Tree (clase en tkinter.tix)

TreeBuilder (clase en xml.etree.ElementTree)

Treeview (clase en tkinter.ttk)

triangular() (en el módulo random)

triple-quoted string

True, [1], [2]

true

True (variable incorporada)

truediv() (en el módulo operator)

trunc() (en el módulo math)

(in module math)

truncate() (en el módulo os)

(método de io.IOBase)

truth

value

truth() (en el módulo operator)

try

sentencia, [1], [2]

Try (clase en ast)

ttk

tty

I/O control

tty (módulo)

ttyname() (en el módulo os)

tupla nombrada

tuple

empty, [1]

función incorporada, [1]

objeto, [1], [2], [3], [4], [5], [6]

singleton

Tuple (clase en ast)

tuple (clase incorporada)

Tuple (en el módulo typing)

tuple2st() (en el módulo parser)

tuple_params (2to3 fixer)

Turtle (clase en turtle)

turtle (módulo)

turtledemo (módulo)

turtles() (en el módulo turtle)

TurtleScreen (clase en turtle)

turtlesize() (en el módulo turtle)

type

Boolean

data

función incorporada, [1], [2], [3]

hierarchy

immutable data

objeto, [1], [2]

operations on dictionary

operations on list

type (atributo de optparse.Option)

(atributo de socket.socket)

(atributo de tarfile.TarInfo)

(atributo de urllib.request.Request)

Type (clase en typing)

type (clase incorporada)

type of an object

type_check_only() (en el módulo typing)

TYPE_CHECKER (atributo de optparse.Option)

TYPE_CHECKING (en el módulo typing)

type_comment (atributo de ast.arg)

(atributo de ast.Assign)

(atributo de ast.For)

(atributo de ast.FunctionDef)

(atributo de ast.With)

TYPE_COMMENT (en el módulo token)

TYPE_IGNORE (en el módulo token)

typeahead() (en el módulo curses)

typecode (atributo de array.array)

typecodes (en el módulo array)

TYPED_ACTIONS (atributo de optparse.Option)

typed_subpart_iterator() (en el módulo email.iterators)

TypedDict (clase en typing)

TypeError

excepción

types

built-in

immutable sequence

módulo

mutable sequence

operations on integer

operations on mapping

operations on numeric

operations on sequence, [1]

types (2to3 fixer)

TYPES (atributo de optparse.Option)

types (módulo)

types, internal

types_map (atributo de mimetypes.MimeTypes)

(en el módulo mimetypes)

types_map_inv (atributo de mimetypes.MimeTypes)

TypeVar (clase en typing)

typing (módulo)

TZ, [1], [2], [3], [4], [5]

tzinfo (atributo de datetime.datetime)

(atributo de datetime.time)

(clase en datetime)

tzname (en el módulo time)

tzname() (método de datetime.datetime)

(método de datetime.time)

(método de datetime.timezone)

(método de datetime.tzinfo)

TZPATH (en el módulo zoneinfo)

tzset() (en el módulo time)

U

u"

string literal

u'

string literal

u-LAW, [1], [2]

UAdd (clase en ast)

ucd_3_2_0 (en el módulo unicodedata)

udata (atributo de select.kevent)

UDPServer (clase en socketserver)

UF_APPEND (en el módulo stat)

UF_COMPRESSED (en el módulo stat)

UF_HIDDEN (en el módulo stat)

UF_IMMUTABLE (en el módulo stat)

UF_NODUMP (en el módulo stat)

UF_NOUNLINK (en el módulo stat)

UF_OPAQUE (en el módulo stat)

uid (atributo de tarfile.TarInfo)

UID (clase en plistlib)

uid() (método de imaplib.IMAP4)

uidl() (método de poplib.POP3)

ulaw2lin() (en el módulo audioop)

ULONG_MAX

ulp() (en el módulo math)

umask() (en el módulo os)

unalias (pdb command)

uname (atributo de tarfile.TarInfo)

uname() (en el módulo os)

(en el módulo platform)

unary

arithmetic operation

bitwise operation

UNARY_INVERT (opcode)

UNARY_NEGATIVE (opcode)

UNARY_NOT (opcode)

UNARY_POSITIVE (opcode)

unaryfunc (tipo C)

UnaryOp (clase en ast)

unbinding

name

UnboundLocalError, [1]

unbuffered I/O

UNC paths

and os.makedirs()

UNCHECKED_HASH (atributo de py_compile.PycInvalidationMode)

unconsumed_tail (atributo de zlib.Decompress)

unctrl() (en el módulo curses)

(en el módulo curses.ascii)

undefine_macro() (método de distutils.ccompiler.CCompiler)

Underflow (clase en decimal)

undisplay (pdb command)

undo() (en el módulo turtle)

undobufferentries() (en el módulo turtle)

undoc_header (atributo de cmd.Cmd)

unescape() (en el módulo html)

(en el módulo xml.sax.saxutils)

UnexpectedException

unexpectedSuccesses (atributo de unittest.TestResult)

unfreeze() (en el módulo gc)

unget_wch() (en el módulo curses)

ungetch() (en el módulo curses)

(en el módulo msvcrt)

ungetmouse() (en el módulo curses)

ungetwch() (en el módulo msvcrt)

unhexlify() (en el módulo binascii)

Unicode, [1], [2]

database

unicode (2to3 fixer)

Unicode Consortium

unicodedata (módulo)

UnicodeDecodeError

UnicodeEncodeError

UnicodeError

UnicodeTranslateError

UnicodeWarning

unidata_version (en el módulo unicodedata)

unified_diff() (en el módulo difflib)

uniform() (en el módulo random)

UnimplementedFileMode

Union (clase en ctypes)

(en el módulo typing)

union() (método de frozenset)

unique() (en el módulo enum)

unittest (módulo)

unittest command line option

--buffer

--catch

--failfast

--locals

-b

-c

-f

-k

unittest-discover command line option

--pattern pattern

--start-directory directory

--top-level-directory directory

--verbose

-p

-s

-t

-v

unittest.mock (módulo)

universal newlines

bytearray.splitlines method

bytes.splitlines method

csv.reader function

importlib.abc.InspectLoader.get_source method

io.IncrementalNewlineDecoder class

io.TextIOWrapper class

open() built-in function

str.splitlines method

subprocess module

What's new, [1], [2], [3]

UNIX

file control

I/O control

unix_dialect (clase en csv)

unix_shell (en el módulo test.support)

UnixDatagramServer (clase en socketserver)

UnixStreamServer (clase en socketserver)

unknown (atributo de uuid.SafeUUID)

unknown_decl() (método de html.parser.HTMLParser)

unknown_open() (método de urllib.request.BaseHandler)

(método de urllib.request.UnknownHandler)

UnknownHandler (clase en urllib.request)

UnknownProtocol

UnknownTransferEncoding

unlink() (en el módulo os)

(en el módulo test.support)

(método de multiprocessing.shared_memory.SharedMemory)

(método de pathlib.Path)

(método de xml.dom.minidom.Node)

unload() (en el módulo test.support)

unlock() (método de mailbox.Babyl)

(método de mailbox.Mailbox)

(método de mailbox.Maildir)

(método de mailbox.mbox)

(método de mailbox.MH)

(método de mailbox.MMDF)

unpack() (en el módulo struct)

(método de struct.Struct)

unpack_archive() (en el módulo shutil)

unpack_array() (método de xdrlib.Unpacker)

unpack_bytes() (método de xdrlib.Unpacker)

unpack_double() (método de xdrlib.Unpacker)

UNPACK_EX (opcode)

unpack_farray() (método de xdrlib.Unpacker)

unpack_float() (método de xdrlib.Unpacker)

unpack_fopaque() (método de xdrlib.Unpacker)

unpack_from() (en el módulo struct)

(método de struct.Struct)

unpack_fstring() (método de xdrlib.Unpacker)

unpack_list() (método de xdrlib.Unpacker)

unpack_opaque() (método de xdrlib.Unpacker)

UNPACK_SEQUENCE (opcode)

unpack_string() (método de xdrlib.Unpacker)

Unpacker (clase en xdrlib)

unpacking

dictionary

in function calls

iterable

unparse() (en el módulo ast)

unparsedEntityDecl() (método de xml.sax.handler.DTDHandler)

UnparsedEntityDeclHandler() (método de xml.parsers.expat.xmlparser)

Unpickler (clase en pickle)

UnpicklingError

unquote() (en el módulo email.utils)

(en el módulo urllib.parse)

unquote_plus() (en el módulo urllib.parse)

unquote_to_bytes() (en el módulo urllib.parse)

unraisablehook() (en el módulo sys)

unreachable object

unreadline() (método de distutils.text_file.TextFile)

unrecognized escape sequence

unregister() (en el módulo atexit)

(en el módulo faulthandler)

(método de select.devpoll)

(método de select.epoll)

(método de select.poll)

(método de selectors.BaseSelector)

unregister_archive_format() (en el módulo shutil)

unregister_dialect() (en el módulo csv)

unregister_unpack_format() (en el módulo shutil)

unsafe (atributo de uuid.SafeUUID)

unselect() (método de imaplib.IMAP4)

unset() (método de test.support.EnvironmentVarGuard)

unsetenv() (en el módulo os)

UnstructuredHeader (clase en email.headerregistry)

unsubscribe() (método de imaplib.IMAP4)

UnsupportedOperation

until (pdb command)

untokenize() (en el módulo tokenize)

untouchwin() (método de curses.window)

unused_data (atributo de bz2.BZ2Decompressor)

(atributo de lzma.LZMADecompressor)

(atributo de zlib.Decompress)

unverifiable (atributo de urllib.request.Request)

unwrap() (en el módulo inspect)

(en el módulo urllib.parse)

(método de ssl.SSLSocket)

up (pdb command)

up() (en el módulo turtle)

update() (en el módulo turtle)

(método de collections.Counter)

(método de dict)

(método de frozenset)

(método de hashlib.hash)

(método de hmac.HMAC)

(método de http.cookies.Morsel)

(método de mailbox.Mailbox)

(método de mailbox.Maildir)

(método de trace.CoverageResults)

update_authenticated() (método de urllib.request.HTTPPasswordMgrWithPriorAuth)

update_lines_cols() (en el módulo curses)

update_panels() (en el módulo curses.panel)

update_visible() (método de mailbox.BabylMessage)

update_wrapper() (en el módulo functools)

upgrade_dependencies() (método de venv.EnvBuilder)

upper() (método de bytearray)

(método de bytes)

(método de str)

urandom() (en el módulo os)

URL, [1], [2], [3]

parsing

relative

url (atributo de http.client.HTTPResponse)

(atributo de urllib.response.addinfourl)

(atributo de xmlrpc.client.ProtocolError)

url2pathname() (en el módulo urllib.request)

urlcleanup() (en el módulo urllib.request)

urldefrag() (en el módulo urllib.parse)

urlencode() (en el módulo urllib.parse)

URLError

urljoin() (en el módulo urllib.parse)

urllib (2to3 fixer)

(módulo)

urllib.error (módulo)

urllib.parse (módulo)

urllib.request

módulo

urllib.request (módulo)

urllib.response (módulo)

urllib.robotparser (módulo)

urlopen() (en el módulo urllib.request)

URLopener (clase en urllib.request)

urlparse() (en el módulo urllib.parse)

urlretrieve() (en el módulo urllib.request)

urlsafe_b64decode() (en el módulo base64)

urlsafe_b64encode() (en el módulo base64)

urlsplit() (en el módulo urllib.parse)

urlunparse() (en el módulo urllib.parse)

urlunsplit() (en el módulo urllib.parse)

urn (atributo de uuid.UUID)

use_default_colors() (en el módulo curses)

use_env() (en el módulo curses)

use_rawinput (atributo de cmd.Cmd)

UseForeignDTD() (método de xml.parsers.expat.xmlparser)

USER

user

effective id

id

id, setting

user() (método de poplib.POP3)

user-defined

function

function call

method

user-defined function

objeto, [1], [2]

user-defined method

objeto

USER_BASE

(en el módulo site)

user_call() (método de bdb.Bdb)

user_exception() (método de bdb.Bdb)

user_line() (método de bdb.Bdb)

user_return() (método de bdb.Bdb)

USER_SITE (en el módulo site)

usercustomize

módulo

UserDict (clase en collections)

UserList (clase en collections)

USERNAME, [1]

username (atributo de email.headerregistry.Address)

USERPROFILE, [1], [2], [3], [4]

userptr() (método de curses.panel.Panel)

UserString (clase en collections)

UserWarning

USTAR_FORMAT (en el módulo tarfile)

USub (clase en ast)

UTC

utc (atributo de datetime.timezone)

utcfromtimestamp() (método de clase de datetime.datetime)

utcnow() (método de clase de datetime.datetime)

utcoffset() (método de datetime.datetime)

(método de datetime.time)

(método de datetime.timezone)

(método de datetime.tzinfo)

utctimetuple() (método de datetime.datetime)

utf8 (atributo de email.policy.EmailPolicy)

utf8() (método de poplib.POP3)

utf8_enabled (atributo de imaplib.IMAP4)

utime() (en el módulo os)

uu

módulo

uu (módulo)

UUID (clase en uuid)

uuid (módulo)

uuid1

uuid1() (en el módulo uuid)

uuid3

uuid3() (en el módulo uuid)

uuid4

uuid4() (en el módulo uuid)

uuid5

uuid5() (en el módulo uuid)

UuidCreate() (en el módulo msilib)

V

v4_int_to_packed() (en el módulo ipaddress)

v6_int_to_packed() (en el módulo ipaddress)

valid_signals() (en el módulo signal)

validator() (en el módulo wsgiref.validate)

value

default parameter

truth

value (atributo de ctypes._SimpleCData)

(atributo de http.cookiejar.Cookie)

(atributo de http.cookies.Morsel)

(atributo de xml.dom.Attr)

value of an object

Value() (en el módulo multiprocessing)

(en el módulo multiprocessing.sharedctypes)

(método de multiprocessing.managers.SyncManager)

value_decode() (método de http.cookies.BaseCookie)

value_encode() (método de http.cookies.BaseCookie)

ValueError

excepción

valuerefs() (método de weakref.WeakValueDictionary)

values

Boolean

writing

values() (método de contextvars.Context)

(método de dict)

(método de email.message.EmailMessage)

(método de email.message.Message)

(método de mailbox.Mailbox)

(método de types.MappingProxyType)

ValuesView (clase en collections.abc)

(clase en typing)

var (atributo de contextvars.Token)

variable

free

variable de clase

variable de contexto

variables de entorno

APPDATA

AUDIODEV

BROWSER, [1]

CC

CFLAGS, [1], [2]

COLS, [1]

COLUMNS, [1]

COMSPEC, [1]

CPP

CPPFLAGS

DISPLAY

DISTUTILS_DEBUG

EnableControlFlowGuard

exec_prefix, [1], [2]

HOME, [1], [2], [3], [4], [5], [6], [7], [8], [9]

HOMEDRIVE, [1]

HOMEPATH, [1]

http_proxy, [1], [2]

IDLESTARTUP, [1], [2], [3]

KDEDIR

LANG, [1], [2], [3], [4]

LANGUAGE, [1]

LC_ALL, [1]

LC_MESSAGES, [1]

LDCXXSHARED

LDFLAGS

LINES, [1], [2], [3], [4]

LNAME

LOGNAME, [1]

MIXERDEV

no_proxy

PAGER

PATH, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21], [22], [23], [24], [25], [26], [27], [28], [29], [30], [31], [32], [33], [34], [35], [36], [37], [38], [39]

PATHEXT, [1], [2]

PIP_USER

PLAT

POSIXLY_CORRECT

prefix, [1], [2], [3]

PY_PYTHON

PYTHON*, [1], [2], [3], [4], [5]

PYTHON_DOM

PYTHONASYNCIODEBUG, [1], [2], [3]

PYTHONBREAKPOINT, [1], [2], [3], [4]

PYTHONCASEOK, [1], [2], [3], [4]

PYTHONCOERCECLOCALE, [1], [2], [3]

PYTHONDEBUG, [1], [2]

PYTHONDEVMODE, [1], [2]

PYTHONDOCS

PYTHONDONTWRITEBYTECODE, [1], [2], [3], [4], [5], [6]

PYTHONDUMPREFS, [1], [2], [3]

PYTHONEXECUTABLE

PYTHONFAULTHANDLER, [1], [2], [3]

PYTHONHASHSEED, [1], [2], [3], [4], [5], [6], [7], [8], [9]

PYTHONHOME, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17]

PYTHONINSPECT, [1], [2], [3]

PYTHONINTMAXSTRDIGITS, [1], [2], [3], [4], [5]

PYTHONIOENCODING, [1], [2], [3], [4], [5], [6], [7]

PYTHONLEGACYWINDOWSFSENCODING, [1], [2], [3]

PYTHONLEGACYWINDOWSSTDIO, [1], [2], [3], [4]

PYTHONMALLOC, [1], [2], [3], [4], [5], [6], [7], [8], [9]

PYTHONMALLOCSTATS, [1], [2]

PYTHONNOUSERSITE, [1], [2], [3]

PYTHONOLDPARSER, [1], [2]

PYTHONOPTIMIZE, [1], [2]

PYTHONPATH, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11], [12], [13], [14], [15], [16], [17], [18], [19], [20], [21], [22], [23], [24], [25]

PYTHONPLATLIBDIR, [1]

PYTHONPROFILEIMPORTTIME, [1], [2], [3]

PYTHONPYCACHEPREFIX, [1], [2], [3], [4]

PYTHONSHOWALLOCCOUNT

PYTHONSHOWREFCOUNT

PYTHONSTARTUP, [1], [2], [3], [4], [5], [6], [7], [8], [9], [10], [11]

PYTHONTHREADDEBUG

PYTHONTRACEMALLOC, [1], [2]

PYTHONTRACEMALLOC`comienzo, configura la variable del entorno a ``25`

PYTHONTZPATH, [1]

PYTHONUNBUFFERED, [1], [2], [3], [4]

PYTHONUSERBASE, [1], [2], [3]

PYTHONUSERSITE

PYTHONUTF8, [1], [2], [3], [4], [5], [6]

PYTHONVERBOSE, [1], [2]

PYTHONWARNINGS, [1], [2], [3], [4], [5], [6], [7], [8], [9]

SOURCE_DATE_EPOCH, [1], [2], [3], [4], [5], [6]

SSL_CERT_FILE

SSL_CERT_PATH

SSLKEYLOGFILE, [1]

SystemRoot

TCL_LIBRARY

TEMP

TERM, [1]

TK_LIBRARY

TMP

TMPDIR

TZ, [1], [2], [3], [4], [5]

USER

USER_BASE

USERNAME, [1]

USERPROFILE, [1], [2], [3], [4]

VIRTUAL_ENV

variance (atributo de statistics.NormalDist)

variance() (en el módulo statistics)

variant (atributo de uuid.UUID)

vars() (función incorporada)

vbar (atributo de tkinter.scrolledtext.ScrolledText)

VBAR (en el módulo token)

VBAREQUAL (en el módulo token)

Vec2D (clase en turtle)

vectorcallfunc (tipo C)

venv (módulo)

VERBOSE (en el módulo re)

verbose (en el módulo tabnanny)

(en el módulo test.support)

verify() (método de smtplib.SMTP)

verify_client_post_handshake() (método de ssl.SSLSocket)

verify_code (atributo de ssl.SSLCertVerificationError)

VERIFY_CRL_CHECK_CHAIN (en el módulo ssl)

VERIFY_CRL_CHECK_LEAF (en el módulo ssl)

VERIFY_DEFAULT (en el módulo ssl)

verify_flags (atributo de ssl.SSLContext)

verify_message (atributo de ssl.SSLCertVerificationError)

verify_mode (atributo de ssl.SSLContext)

verify_request() (método de socketserver.BaseServer)

VERIFY_X509_STRICT (en el módulo ssl)

VERIFY_X509_TRUSTED_FIRST (en el módulo ssl)

VerifyFlags (clase en ssl)

VerifyMode (clase en ssl)

version (atributo de email.headerregistry.MIMEVersionHeader)

(atributo de http.client.HTTPResponse)

(atributo de http.cookiejar.Cookie)

(atributo de ipaddress.IPv4Address)

(atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Address)

(atributo de ipaddress.IPv6Network)

(atributo de urllib.request.URLopener)

(atributo de uuid.UUID)

(en el módulo curses)

(en el módulo marshal)

(en el módulo sqlite3)

(en el módulo sys)

(in module sys), [1], [2]

version() (en el módulo ensurepip)

(en el módulo platform)

(método de ssl.SSLSocket)

version_info (en el módulo sqlite3)

(en el módulo sys)

version_string() (método de http.server.BaseHTTPRequestHandler)

vformat() (método de string.Formatter)

virtual

Environments

VIRTUAL_ENV

visit() (método de ast.NodeVisitor)

visitproc (tipo C)

vista de diccionario

vline() (método de curses.window)

voidcmd() (método de ftplib.FTP)

volume (atributo de zipfile.ZipInfo)

vonmisesvariate() (en el módulo random)

W

W_OK (en el módulo os)

wait() (en el módulo asyncio)

(en el módulo concurrent.futures)

(en el módulo multiprocessing.connection)

(en el módulo os)

(método de asyncio.Condition)

(método de asyncio.Event)

(método de asyncio.subprocess.Process)

(método de multiprocessing.pool.AsyncResult)

(método de subprocess.Popen)

(método de threading.Barrier)

(método de threading.Condition)

(método de threading.Event)

wait3() (en el módulo os)

wait4() (en el módulo os)

wait_closed() (método de asyncio.Server)

(método de asyncio.StreamWriter)

wait_for() (en el módulo asyncio)

(método de asyncio.Condition)

(método de threading.Condition)

wait_process() (en el módulo test.support)

wait_threads_exit() (en el módulo test.support)

waitid() (en el módulo os)

waitpid() (en el módulo os)

waitstatus_to_exitcode() (en el módulo os)

walk() (en el módulo ast)

(en el módulo os)

(método de email.message.EmailMessage)

(método de email.message.Message)

walk_packages() (en el módulo pkgutil)

walk_stack() (en el módulo traceback)

walk_tb() (en el módulo traceback)

want (atributo de doctest.Example)

warn() (en el módulo warnings)

(método de distutils.ccompiler.CCompiler)

(método de distutils.text_file.TextFile)

warn_explicit() (en el módulo warnings)

Warning, [1]

warning() (en el módulo logging)

(método de logging.Logger)

(método de xml.sax.handler.ErrorHandler)

warnings

(módulo)

WarningsRecorder (clase en test.support)

warnoptions (en el módulo sys)

wasSuccessful() (método de unittest.TestResult)

WatchedFileHandler (clase en logging.handlers)

wave (módulo)

WCONTINUED (en el módulo os)

WCOREDUMP() (en el módulo os)

WeakKeyDictionary (clase en weakref)

WeakMethod (clase en weakref)

weakref (módulo)

WeakSet (clase en weakref)

WeakValueDictionary (clase en weakref)

webbrowser (módulo)

weekday() (en el módulo calendar)

(método de datetime.date)

(método de datetime.datetime)

weekheader() (en el módulo calendar)

weibullvariate() (en el módulo random)

WEXITED (en el módulo os)

WEXITSTATUS() (en el módulo os)

wfile (atributo de http.server.BaseHTTPRequestHandler)

what() (en el módulo imghdr)

(en el módulo sndhdr)

whathdr() (en el módulo sndhdr)

whatis (pdb command)

when() (método de asyncio.TimerHandle)

where (pdb command)

which() (en el módulo shutil)

whichdb() (en el módulo dbm)

while

sentencia, [1], [2], [3]

While (clase en ast)

whitespace (atributo de shlex.shlex)

(en el módulo string)

whitespace_split (atributo de shlex.shlex)

Widget (clase en tkinter.ttk)

width (atributo de textwrap.TextWrapper)

width() (en el módulo turtle)

WIFCONTINUED() (en el módulo os)

WIFEXITED() (en el módulo os)

WIFSIGNALED() (en el módulo os)

WIFSTOPPED() (en el módulo os)

win32_edition() (en el módulo platform)

win32_is_iot() (en el módulo platform)

win32_ver() (en el módulo platform)

WinDLL (clase en ctypes)

window manager (widgets)

window() (método de curses.panel.Panel)

window_height() (en el módulo turtle)

window_width() (en el módulo turtle)

Windows

Windows ini file

WindowsError

WindowsPath (clase en pathlib)

WindowsProactorEventLoopPolicy (clase en asyncio)

WindowsRegistryFinder (clase en importlib.machinery)

WindowsSelectorEventLoopPolicy (clase en asyncio)

winerror (atributo de OSError)

WinError() (en el módulo ctypes)

WINFUNCTYPE() (en el módulo ctypes)

winreg (módulo)

WinSock

winsound (módulo)

winver (en el módulo sys)

with

sentencia, [1]

With (clase en ast)

WITH_EXCEPT_START (opcode)

with_hostmask (atributo de ipaddress.IPv4Interface)

(atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Interface)

(atributo de ipaddress.IPv6Network)

with_name() (método de pathlib.PurePath)

with_netmask (atributo de ipaddress.IPv4Interface)

(atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Interface)

(atributo de ipaddress.IPv6Network)

with_prefixlen (atributo de ipaddress.IPv4Interface)

(atributo de ipaddress.IPv4Network)

(atributo de ipaddress.IPv6Interface)

(atributo de ipaddress.IPv6Network)

with_pymalloc() (en el módulo test.support)

with_stem() (método de pathlib.PurePath)

with_suffix() (método de pathlib.PurePath)

with_traceback() (método de BaseException)

withitem (clase en ast)

WNOHANG (en el módulo os)

WNOWAIT (en el módulo os)

wordchars (atributo de shlex.shlex)

World Wide Web, [1], [2]

wrap() (en el módulo textwrap)

(método de textwrap.TextWrapper)

wrap_bio() (método de ssl.SSLContext)

wrap_future() (en el módulo asyncio)

wrap_socket() (en el módulo ssl)

(método de ssl.SSLContext)

wrap_text() (en el módulo distutils.fancy_getopt)

wrapper() (en el módulo curses)

WrapperDescriptorType (en el módulo types)

wraps() (en el módulo functools)

WRITABLE (en el módulo tkinter)

writable() (método de asyncore.dispatcher)

(método de io.IOBase)

write() (en el módulo os)

(en el módulo turtle)

(método de asyncio.StreamWriter)

(método de asyncio.WriteTransport)

(método de code.InteractiveInterpreter)

(método de codecs.StreamWriter)

(método de configparser.ConfigParser)

(método de email.generator.BytesGenerator)

(método de email.generator.Generator)

(método de io.BufferedIOBase)

(método de io.BufferedWriter)

(método de io.RawIOBase)

(método de io.TextIOBase)

(método de mmap.mmap)

(método de ossaudiodev.oss_audio_device)

(método de ssl.MemoryBIO)

(método de ssl.SSLSocket)

(método de telnetlib.Telnet)

(método de xml.etree.ElementTree.ElementTree)

(método de zipfile.ZipFile)

write_byte() (método de mmap.mmap)

write_bytes() (método de pathlib.Path)

write_docstringdict() (en el módulo turtle)

write_eof() (método de asyncio.StreamWriter)

(método de asyncio.WriteTransport)

(método de ssl.MemoryBIO)

write_file() (en el módulo distutils.file_util)

write_history_file() (en el módulo readline)

WRITE_RESTRICTED

write_results() (método de trace.CoverageResults)

write_text() (método de pathlib.Path)

write_through (atributo de io.TextIOWrapper)

writeall() (método de ossaudiodev.oss_audio_device)

writeframes() (método de aifc.aifc)

(método de sunau.AU_write)

(método de wave.Wave_write)

writeframesraw() (método de aifc.aifc)

(método de sunau.AU_write)

(método de wave.Wave_write)

writeheader() (método de csv.DictWriter)

writelines() (método de asyncio.StreamWriter)

(método de asyncio.WriteTransport)

(método de codecs.StreamWriter)

(método de io.IOBase)

writepy() (método de zipfile.PyZipFile)

writer (atributo de formatter.formatter)

writer() (en el módulo csv)

writerow() (método de csv.csvwriter)

writerows() (método de csv.csvwriter)

writestr() (método de zipfile.ZipFile)

WriteTransport (clase en asyncio)

writev() (en el módulo os)

writexml() (método de xml.dom.minidom.Node)

writing

values

WrongDocumentErr

ws_comma (2to3 fixer)

wsgi_file_wrapper (atributo de wsgiref.handlers.BaseHandler)

wsgi_multiprocess (atributo de wsgiref.handlers.BaseHandler)

wsgi_multithread (atributo de wsgiref.handlers.BaseHandler)

wsgi_run_once (atributo de wsgiref.handlers.BaseHandler)

wsgiref (módulo)

wsgiref.handlers (módulo)

wsgiref.headers (módulo)

wsgiref.simple_server (módulo)

wsgiref.util (módulo)

wsgiref.validate (módulo)

WSGIRequestHandler (clase en wsgiref.simple_server)

WSGIServer (clase en wsgiref.simple_server)

wShowWindow (atributo de subprocess.STARTUPINFO)

WSTOPPED (en el módulo os)

WSTOPSIG() (en el módulo os)

wstring_at() (en el módulo ctypes)

WTERMSIG() (en el módulo os)

WUNTRACED (en el módulo os)

WWW, [1], [2]

server, [1]

X

X (en el módulo re)

X509 certificate

X_OK (en el módulo os)

xatom() (método de imaplib.IMAP4)

XATTR_CREATE (en el módulo os)

XATTR_REPLACE (en el módulo os)

XATTR_SIZE_MAX (en el módulo os)

xcor() (en el módulo turtle)

XDR

xdrlib (módulo)

xhdr() (método de nntplib.NNTP)

XHTML

XHTML_NAMESPACE (en el módulo xml.dom)

xml (módulo)

XML() (en el módulo xml.etree.ElementTree)

xml.dom (módulo)

xml.dom.minidom (módulo)

xml.dom.pulldom (módulo)

xml.etree.ElementInclude.default_loader() (función incorporada)

xml.etree.ElementInclude.include() (función incorporada)

xml.etree.ElementTree (módulo)

xml.parsers.expat (módulo)

xml.parsers.expat.errors (módulo)

xml.parsers.expat.model (módulo)

xml.sax (módulo)

xml.sax.handler (módulo)

xml.sax.saxutils (módulo)

xml.sax.xmlreader (módulo)

XML_ERROR_ABORTED (en el módulo xml.parsers.expat.errors)

XML_ERROR_ASYNC_ENTITY (en el módulo xml.parsers.expat.errors)

XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF (en el módulo xml.parsers.expat.errors)

XML_ERROR_BAD_CHAR_REF (en el módulo xml.parsers.expat.errors)

XML_ERROR_BINARY_ENTITY_REF (en el módulo xml.parsers.expat.errors)

XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING (en el módulo xml.parsers.expat.errors)

XML_ERROR_DUPLICATE_ATTRIBUTE (en el módulo xml.parsers.expat.errors)

XML_ERROR_ENTITY_DECLARED_IN_PE (en el módulo xml.parsers.expat.errors)

XML_ERROR_EXTERNAL_ENTITY_HANDLING (en el módulo xml.parsers.expat.errors)

XML_ERROR_FEATURE_REQUIRES_XML_DTD (en el módulo xml.parsers.expat.errors)

XML_ERROR_FINISHED (en el módulo xml.parsers.expat.errors)

XML_ERROR_INCOMPLETE_PE (en el módulo xml.parsers.expat.errors)

XML_ERROR_INCORRECT_ENCODING (en el módulo xml.parsers.expat.errors)

XML_ERROR_INVALID_TOKEN (en el módulo xml.parsers.expat.errors)

XML_ERROR_JUNK_AFTER_DOC_ELEMENT (en el módulo xml.parsers.expat.errors)

XML_ERROR_MISPLACED_XML_PI (en el módulo xml.parsers.expat.errors)

XML_ERROR_NO_ELEMENTS (en el módulo xml.parsers.expat.errors)

XML_ERROR_NO_MEMORY (en el módulo xml.parsers.expat.errors)

XML_ERROR_NOT_STANDALONE (en el módulo xml.parsers.expat.errors)

XML_ERROR_NOT_SUSPENDED (en el módulo xml.parsers.expat.errors)

XML_ERROR_PARAM_ENTITY_REF (en el módulo xml.parsers.expat.errors)

XML_ERROR_PARTIAL_CHAR (en el módulo xml.parsers.expat.errors)

XML_ERROR_PUBLICID (en el módulo xml.parsers.expat.errors)

XML_ERROR_RECURSIVE_ENTITY_REF (en el módulo xml.parsers.expat.errors)

XML_ERROR_SUSPEND_PE (en el módulo xml.parsers.expat.errors)

XML_ERROR_SUSPENDED (en el módulo xml.parsers.expat.errors)

XML_ERROR_SYNTAX (en el módulo xml.parsers.expat.errors)

XML_ERROR_TAG_MISMATCH (en el módulo xml.parsers.expat.errors)

XML_ERROR_TEXT_DECL (en el módulo xml.parsers.expat.errors)

XML_ERROR_UNBOUND_PREFIX (en el módulo xml.parsers.expat.errors)

XML_ERROR_UNCLOSED_CDATA_SECTION (en el módulo xml.parsers.expat.errors)

XML_ERROR_UNCLOSED_TOKEN (en el módulo xml.parsers.expat.errors)

XML_ERROR_UNDECLARING_PREFIX (en el módulo xml.parsers.expat.errors)

XML_ERROR_UNDEFINED_ENTITY (en el módulo xml.parsers.expat.errors)

XML_ERROR_UNEXPECTED_STATE (en el módulo xml.parsers.expat.errors)

XML_ERROR_UNKNOWN_ENCODING (en el módulo xml.parsers.expat.errors)

XML_ERROR_XML_DECL (en el módulo xml.parsers.expat.errors)

XML_NAMESPACE (en el módulo xml.dom)

xmlcharrefreplace

error handler's name

xmlcharrefreplace_errors() (en el módulo codecs)

XmlDeclHandler() (método de xml.parsers.expat.xmlparser)

XMLFilterBase (clase en xml.sax.saxutils)

XMLGenerator (clase en xml.sax.saxutils)

XMLID() (en el módulo xml.etree.ElementTree)

XMLNS_NAMESPACE (en el módulo xml.dom)

XMLParser (clase en xml.etree.ElementTree)

XMLParserType (en el módulo xml.parsers.expat)

XMLPullParser (clase en xml.etree.ElementTree)

XMLReader (clase en xml.sax.xmlreader)

xmlrpc.client (módulo)

xmlrpc.server (módulo)

xor

bitwise

xor() (en el módulo operator)

xover() (método de nntplib.NNTP)

xrange (2to3 fixer)

xreadlines (2to3 fixer)

xview() (método de tkinter.ttk.Treeview)

Y

ycor() (en el módulo turtle)

year (atributo de datetime.date)

(atributo de datetime.datetime)

Year 2038

yeardatescalendar() (método de calendar.Calendar)

yeardays2calendar() (método de calendar.Calendar)

yeardayscalendar() (método de calendar.Calendar)

YESEXPR (en el módulo locale)

yield

examples

expression

palabra clave

sentencia

yield from (in What's New)

Yield (clase en ast)

YIELD_FROM (opcode)

YIELD_VALUE (opcode)

YieldFrom (clase en ast)

yiq_to_rgb() (en el módulo colorsys)

yview() (método de tkinter.ttk.Treeview)

Z

Zen de Python

ZeroDivisionError

excepción

zfill() (método de bytearray)

(método de bytes)

(método de str)

zip (2to3 fixer)

zip() (función incorporada)

ZIP_BZIP2 (en el módulo zipfile)

ZIP_DEFLATED (en el módulo zipfile)

zip_longest() (en el módulo itertools)

ZIP_LZMA (en el módulo zipfile)

ZIP_STORED (en el módulo zipfile)

zipapp (módulo)

zipapp command line option

--compress

--help

--info

--main=<mainfn>

--output=<output>

--python=<interpreter>

-c

-h

-m <mainfn>

-o <output>

-p <interpreter>

ZipFile (clase en zipfile)

zipfile (módulo)

zipfile command line option

--create <zipfile> <source1> ... <sourceN>

--extract <zipfile> <output_dir>

--list <zipfile>

--test <zipfile>

-c <zipfile> <source1> ... <sourceN>

-e <zipfile> <output_dir>

-l <zipfile>

-t <zipfile>

zipimport (módulo)

zipimporter (clase en zipimport)

ZipImportError

ZipInfo (clase en zipfile)

zlib (módulo)

ZLIB_RUNTIME_VERSION (en el módulo zlib)

ZLIB_VERSION (en el módulo zlib)

ZoneInfo (clase en zoneinfo)

zoneinfo (módulo)

ZoneInfoNotFoundError

zscore() (método de statistics.NormalDist)

documentación de Python - 3.9.18

Welcome! This is the official documentation for Python 3.9.18.

Áreas de la documentación:

¿Qué hay de nuevo en Python 3.9?
o todos los "Qué hay de nuevo" desde 2.0

Tutorial
empieza aquí

Referencia de la Biblioteca
Mantén esto bajo tu almohada

Referencia del lenguaje
descripción de sintaxis y los elementos del lenguaje

Configuración y uso de Python
como usar Python en diferentes plataformas

Cómos (HOWTOs) de Python
documentos detallados sobre temas específicos

Instalación de módulos de Python
instalación desde el Índice de paquete de Python (Python Package Index) y otras fuentes

Distribuir módulos de Python
publicación de módulos para que otros los instalen

Extender e incrustar
tutorial para programadores y programadoras de C/C++

Python/C API
referencia para programadores y programadoras de C/C++

Preguntas frecuentes
preguntas frecuentes (¡con respuestas!)

Índices y tablas:

Índice Global de Módulos
acceso rápido a todos los módulos

Índice General
todas las funciones, clases, términos

Glosario
los términos más importantes explicados

Página de búsqueda
buscar en esta documentación

Índice de contenidos completo
muestra todas las secciones y subsecciones

Meta información:

Reportar errores

Contributing to Docs

Acerca de la documentación

Historia y licencia de Python

Copyright

Nota

Este documento se conserva únicamente hasta que la documentación de setuptools en https://setuptools.readthedocs.io/en/latest/setuptools.html cubra de forma independiente toda la información relevante incluida actualmente aquí.

El Indice de Paquetes de Python (PyPI)

El Python Package Index (PyPI) [https://pypi.org] almacena metadatos describiendo distribuciones empaquetadas con distutils y otras herramientas de publicación, así como los propios archivos de la distribución.

Las referencias vigentes de la documentación de PyPI pueden ser consultadas en Leyendo la «Python Packaging User Guide».

Subir paquetes al índice de paquetes

Referencias a la documentación actualizada de PyPI pueden encontrarse en Leyendo la «Python Packaging User Guide».